rlp-schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/vdsx-cloud/reasoning-ledger-protocol/rlp-schema.json",
  "title": "Reasoning Ledger Protocol Schema",
  "description": "JSON Schema for Reasoning Ledger Protocol commits",
  "type": "object",
  "required": ["rlp_version", "commit_type", "timestamp"],
  "properties": {
    "rlp_version": {
      "type": "string",
      "description": "RLP protocol version",
      "pattern": "^1\\.0$",
      "examples": ["1.0"]
    },
    "commit_type": {
      "type": "string",
      "description": "Type of commit",
      "enum": ["gene_promotion", "execution_record", "system_event", "economic_record", "promotion_record"],
      "examples": ["gene_promotion"]
    },
    "timestamp": {
      "type": "string",
      "description": "ISO 8601 timestamp",
      "format": "date-time",
      "examples": ["2024-04-08T04:30:00Z"]
    },
    "gene": {
      "type": "object",
      "description": "Gene definition",
      "required": ["id", "domain", "trigger", "action"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique gene identifier",
          "pattern": "^[a-zA-Z0-9:_-]+$",
          "examples": ["research:abc123", "g_mnp9ygmf_tw6"]
        },
        "locus": {
          "type": "string",
          "description": "Human-readable gene identifier",
          "examples": ["research:search for machine learning papers:navigate to https://arxiv.org and search"]
        },
        "domain": {
          "type": "string",
          "description": "Behavioral domain",
          "enum": ["research", "navigation", "analysis", "universal"],
          "examples": ["research"]
        },
        "trigger": {
          "type": "string",
          "description": "Context that triggers this behavior",
          "minLength": 1,
          "examples": ["search for machine learning papers"]
        },
        "action": {
          "type": "string",
          "description": "Executable action or thought process",
          "minLength": 1,
          "examples": ["navigate to https://arxiv.org and search for \"machine learning\""]
        },
        "type": {
          "type": "string",
          "description": "Gene type",
          "enum": ["do", "think", "check"],
          "default": "do",
          "examples": ["do"]
        },
        "promoted": {
          "type": ["boolean", "integer"],
          "description": "Whether gene is actively promoted",
          "examples": [true, 1, false, 0]
        },
        "confidence": {
          "type": "number",
          "description": "Match confidence score",
          "minimum": 0,
          "maximum": 1,
          "examples": [0.9]
        },
        "usage_count": {
          "type": "integer",
          "description": "Number of times successfully used",
          "minimum": 0,
          "examples": [3]
        }
      }
    },
    "evidence": {
      "type": "object",
      "description": "Evidence supporting gene promotion",
      "properties": {
        "first_observed": {
          "type": "string",
          "description": "ISO 8601 timestamp of first observation",
          "format": "date-time",
          "examples": ["2024-04-08T04:15:00Z"]
        },
        "last_observed": {
          "type": "string",
          "description": "ISO 8601 timestamp of last observation",
          "format": "date-time",
          "examples": ["2024-04-08T04:25:00Z"]
        },
        "success_count": {
          "type": "integer",
          "description": "Number of successful executions",
          "minimum": 0,
          "examples": [3]
        },
        "failure_count": {
          "type": "integer",
          "description": "Number of failed executions",
          "minimum": 0,
          "examples": [0]
        },
        "token_savings": {
          "type": "integer",
          "description": "Total tokens saved by this gene",
          "minimum": 0,
          "examples": [6108]
        },
        "average_tokens_saved": {
          "type": "number",
          "description": "Average tokens saved per execution",
          "minimum": 0,
          "examples": [2036]
        },
        "promotion_threshold": {
          "type": "integer",
          "description": "Success count required for promotion",
          "minimum": 1,
          "default": 3,
          "examples": [3]
        }
      }
    },
    "execution": {
      "type": "object",
      "description": "Execution record details",
      "required": ["decision_source", "domain"],
      "properties": {
        "decision_source": {
          "type": "string",
          "description": "Source of the decision",
          "enum": ["dna_gene", "dna_gene_invalid_action", "dna_PREFER__", "llm_fallback", "llm_forced_exploration"],
          "examples": ["dna_gene"]
        },
        "metric_bucket": {
          "type": "string",
          "description": "Metric categorization",
          "enum": ["dna_match_valid", "dna_match_invalid_action", "dna_PREFER__", "llm_fallback"],
          "examples": ["dna_match_valid"]
        },
        "gene_id": {
          "type": "string",
          "description": "Gene identifier that matched",
          "examples": ["research:abc123", "dna_match_1775639397809"]
        },
        "domain": {
          "type": "string",
          "description": "Behavioral domain",
          "enum": ["research", "navigation", "analysis", "universal"],
          "examples": ["research"]
        },
        "saved_tokens": {
          "type": "integer",
          "description": "Tokens saved by using DNA match",
          "minimum": 0,
          "examples": [2036, 0]
        },
        "confidence": {
          "type": "number",
          "description": "Match confidence score",
          "minimum": 0,
          "maximum": 1,
          "examples": [0.9]
        },
        "match_threshold": {
          "type": "number",
          "description": "Confidence threshold for matching",
          "minimum": 0,
          "maximum": 1,
          "examples": [0.3]
        },
        "failure_reason": {
          "type": ["string", "null"],
          "description": "Reason for failure if applicable",
          "examples": ["EMPTY_OR_INVALID_ACTION", null]
        }
      }
    },
    "provenance": {
      "type": "object",
      "description": "Cryptographic provenance information",
      "properties": {
        "previous_commit": {
          "type": "string",
          "description": "Hash of previous commit",
          "examples": ["sha256:abc123def456"]
        },
        "commit_hash": {
          "type": "string",
          "description": "Hash of this commit",
          "examples": ["sha256:def456abc123"]
        },
        "system_fingerprint": {
          "type": "string",
          "description": "System identifier",
          "examples": ["edge-node-001"]
        },
        "agent_version": {
          "type": "string",
          "description": "Agent software version",
          "examples": ["1.0.0"]
        },
        "ledger_depth": {
          "type": "integer",
          "description": "Depth in the ledger",
          "minimum": 0,
          "examples": [1525]
        }
      }
    },
    "metadata": {
      "type": "object",
      "description": "Additional metadata",
      "properties": {
        "experiment_id": {
          "type": "string",
          "description": "Experiment identifier",
          "examples": ["exp4"]
        },
        "epsilon_arch": {
          "type": "number",
          "description": "ε-arch exploration rate",
          "minimum": 0,
          "maximum": 1,
          "examples": [0.2]
        },
        "monopoly_brakes": {
          "type": "boolean",
          "description": "Whether monopoly brakes are enabled",
          "examples": [true]
        },
        "ts": {
          "type": "integer",
          "description": "Timestamp in milliseconds (WAL format)",
          "minimum": 0,
          "examples": [1775639397809]
        },
        "type": {
          "type": "string",
          "description": "Record type (WAL format)",
          "examples": ["execution_record", "promotion_record"]
        }
      }
    }
  },
  "oneOf": [
    {
      "properties": {
        "commit_type": { "const": "gene_promotion" },
        "gene": { "$ref": "#/properties/gene" },
        "evidence": { "$ref": "#/properties/evidence" }
      },
      "required": ["gene", "evidence"]
    },
    {
      "properties": {
        "commit_type": { "const": "execution_record" },
        "execution": { "$ref": "#/properties/execution" }
      },
      "required": ["execution"]
    },
    {
      "properties": {
        "commit_type": { "const": "promotion_record" }
      }
    },
    {
      "properties": {
        "commit_type": { "const": "system_event" }
      }
    },
    {
      "properties": {
        "commit_type": { "const": "economic_record" }
      }
    }
  ],
  "additionalProperties": true,
  "examples": [
    {
      "rlp_version": "1.0",
      "commit_type": "gene_promotion",
      "timestamp": "2024-04-08T04:30:00Z",
      "gene": {
        "id": "research:abc123",
        "locus": "research:search for machine learning papers:navigate to https://arxiv.org and search",
        "domain": "research",
        "trigger": "search for machine learning papers",
        "action": "navigate to https://arxiv.org and search for \"machine learning\"",
        "type": "do",
        "promoted": true,
        "confidence": 0.9,
        "usage_count": 0
      },
      "evidence": {
        "first_observed": "2024-04-08T04:15:00Z",
        "last_observed": "2024-04-08T04:25:00Z",
        "success_count": 3,
        "failure_count": 0,
        "token_savings": 6108,
        "average_tokens_saved": 2036,
        "promotion_threshold": 3
      },
      "provenance": {
        "previous_commit": "sha256:abc123def456",
        "commit_hash": "sha256:def456abc123",
        "system_fingerprint": "edge-node-001",
        "agent_version": "1.0.0",
        "ledger_depth": 1525
      },
      "metadata": {
        "experiment_id": "exp4",
        "epsilon_arch": 0.2,
        "monopoly_brakes": true
      }
    },
    {
      "ts": 1775639397809,
      "type": "execution_record",
      "execution": {
        "decision_source": "dna_gene_invalid_action",
        "metric_bucket": "dna_match_invalid_action",
        "gene_id": "dna_match_1775639397809",
        "domain": "research",
        "saved_tokens": 0,
        "confidence": 0.9,
        "match_threshold": 0.3,
        "failure_reason": "EMPTY_OR_INVALID_ACTION"
      }
    }
  ]
}