ucwm/schemas/routing.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "ucwm/schemas/routing.json",
  "title": "Routing Schemas",
  "description": "GateSignal and RoutingDecision schemas for the RSA relay layer.",
  "$defs": {
    "GateSignal": {
      "type": "object",
      "title": "GateSignal",
      "description": "Output of a single relation gate. Does not solve anything — only informs the router.",
      "required": ["gate_id", "activated", "confidence"],
      "additionalProperties": false,
      "properties": {
        "gate_id": {
          "type": "string",
          "description": "Identifier of the gate that produced this signal.",
          "examples": [
            "is_math",
            "has_temporal_relation",
            "has_entity_reference",
            "has_ownership_transfer",
            "has_quantity"
          ]
        },
        "activated": {
          "type": "boolean",
          "description": "Whether the gate fired. High-recall design: prefer true when uncertain."
        },
        "confidence": {
          "type": "number",
          "minimum": 0.0,
          "maximum": 1.0,
          "description": "Confidence in the activation decision."
        },
        "evidence_spans": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "text": { "type": "string" },
              "start": { "type": "integer" },
              "end": { "type": "integer" }
            }
          },
          "description": "Text spans that triggered this gate."
        },
        "method": {
          "type": "string",
          "enum": ["regex", "rule", "classifier", "neural", "hybrid"],
          "description": "Implementation method used by this gate instance."
        }
      }
    },

    "BudgetSpec": {
      "type": "object",
      "title": "BudgetSpec",
      "description": "Resource budget granted to a specialist by the relay.",
      "properties": {
        "level": {
          "type": "string",
          "enum": ["minimal", "bounded", "full"],
          "description": "minimal=one fast pass; bounded=normal depth; full=exhaust all evidence"
        },
        "max_objects": {
          "type": "integer",
          "description": "Maximum number of objects the specialist may inspect."
        },
        "max_constraints": {
          "type": "integer",
          "description": "Maximum number of constraints the specialist may emit."
        },
        "max_iterations": {
          "type": "integer",
          "description": "Maximum processing iterations for iterative specialists."
        }
      }
    },

    "SpecialistAssignment": {
      "type": "object",
      "title": "SpecialistAssignment",
      "description": "Activation of a single specialist within a RoutingDecision.",
      "required": ["specialist_id", "target_refs", "budget"],
      "properties": {
        "specialist_id": {
          "type": "string",
          "description": "Registered ID of the specialist to activate.",
          "examples": [
            "temporal",
            "spatial",
            "entity",
            "quantity",
            "logic",
            "causal",
            "ownership",
            "social",
            "planning",
            "code"
          ]
        },
        "target_refs": {
          "type": "array",
          "items": { "type": "string" },
          "description": "object_ids the specialist should inspect."
        },
        "budget": { "$ref": "#/$defs/BudgetSpec" },
        "priority": {
          "type": "integer",
          "description": "Relative priority for constraint merging. Lower number = higher priority."
        }
      }
    },

    "RoutingDecision": {
      "type": "object",
      "title": "RoutingDecision",
      "description": "Composite routing decision emitted by the RSA relay. Activates multiple specialists on the same targets.",
      "required": ["decision_id", "assignments", "mode"],
      "additionalProperties": false,
      "properties": {
        "decision_id": {
          "type": "string",
          "description": "Unique ID for this routing decision."
        },
        "assignments": {
          "type": "array",
          "items": { "$ref": "#/$defs/SpecialistAssignment" },
          "minItems": 1,
          "description": "Ordered list of specialist assignments."
        },
        "mode": {
          "type": "string",
          "enum": ["parallel", "sequential", "iterative", "conflict_checking"],
          "description": "Execution mode for specialists in this decision."
        },
        "gate_signals": {
          "type": "array",
          "items": { "$ref": "#/$defs/GateSignal" },
          "description": "The gate signals that informed this routing decision."
        },
        "input_object_refs": {
          "type": "array",
          "items": { "type": "string" },
          "description": "All canonical object IDs available at routing time."
        },
        "provenance_refs": {
          "type": "array",
          "items": { "type": "string" },
          "default": []
        }
      }
    }
  },

  "examples": [
    {
      "decision_id": "RD_001",
      "mode": "parallel",
      "gate_signals": [
        { "gate_id": "has_entity_reference", "activated": true, "confidence": 0.99 },
        { "gate_id": "has_quantity", "activated": true, "confidence": 0.99 },
        { "gate_id": "has_ownership_transfer", "activated": true, "confidence": 0.96 },
        { "gate_id": "is_math", "activated": true, "confidence": 0.94 },
        { "gate_id": "has_temporal_relation", "activated": true, "confidence": 0.88 }
      ],
      "input_object_refs": ["E1", "E2", "O_apples", "Q1", "Q2", "EV_transfer"],
      "assignments": [
        {
          "specialist_id": "entity",
          "target_refs": ["E1", "E2"],
          "budget": { "level": "bounded" },
          "priority": 1
        },
        {
          "specialist_id": "quantity",
          "target_refs": ["Q1", "Q2"],
          "budget": { "level": "full" },
          "priority": 2
        },
        {
          "specialist_id": "ownership",
          "target_refs": ["E1", "E2", "O_apples"],
          "budget": { "level": "bounded" },
          "priority": 3
        },
        {
          "specialist_id": "temporal",
          "target_refs": ["EV_transfer"],
          "budget": { "level": "minimal" },
          "priority": 4
        }
      ]
    }
  ]
}