{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "ucwm/schemas/provenance.json",
  "title": "Provenance",
  "description": "Tracks where every fact, object, facet, and constraint came from. Enables failure localization and explainability.",
  "type": "object",
  "required": ["provenance_id", "record_type", "source_module", "timestamp"],
  "additionalProperties": false,
  "properties": {
    "provenance_id": {
      "type": "string",
      "description": "Unique identifier. Format: P{sequence}"
    },
    "record_type": {
      "type": "string",
      "enum": ["object_proposal", "facet_attachment", "constraint_emission", "resolver_operation", "object_merge", "object_split", "synthesis_step"],
      "description": "What kind of operation created this provenance record."
    },
    "source_module": {
      "type": "string",
      "description": "Module ID that triggered this event."
    },
    "input_refs": {
      "type": "array",
      "items": { "type": "string" },
      "description": "IDs of objects, facets, or constraints that were inputs to the operation.",
      "default": []
    },
    "output_refs": {
      "type": "array",
      "items": { "type": "string" },
      "description": "IDs of objects, facets, or constraints produced by the operation.",
      "default": []
    },
    "evidence_span": {
      "type": "object",
      "description": "Text span that provided evidence for this operation.",
      "properties": {
        "text": { "type": "string" },
        "start": { "type": "integer" },
        "end": { "type": "integer" }
      }
    },
    "confidence": {
      "type": "number",
      "minimum": 0.0,
      "maximum": 1.0
    },
    "timestamp": {
      "type": "string",
      "description": "ISO 8601 timestamp of when this operation occurred."
    },
    "notes": {
      "type": "string",
      "description": "Optional free-text note. For debugging only — not part of the reasoning chain."
    }
  },
  "examples": [
    {
      "provenance_id": "P1",
      "record_type": "object_proposal",
      "source_module": "entity_specialist",
      "input_refs": [],
      "output_refs": ["E1"],
      "evidence_span": { "text": "Alice", "start": 0, "end": 5 },
      "confidence": 0.97,
      "timestamp": "2026-05-01T00:00:00Z"
    },
    {
      "provenance_id": "P4",
      "record_type": "resolver_operation",
      "source_module": "resolver",
      "input_refs": ["C1", "C2", "C3"],
      "output_refs": ["Q_alice_final"],
      "confidence": 0.99,
      "timestamp": "2026-05-01T00:00:01Z",
      "notes": "Arithmetic resolution: 5 - 2 = 3"
    }
  ]
}