{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://topicspace.ai/schemas/warrant-v0.1.json",
  "title": "Belief Stack Warrant (v0.1)",
  "description": "The evidence backing a label in a Belief Stack pipeline. A warrant says why a label is allowed to be made. Required fields vary by substrate; common fields below.",
  "type": "object",
  "properties": {
    "schema_version": {
      "type": "string",
      "const": "warrant-v0.1",
      "description": "Pins the schema version. Required."
    },
    "warrant_type": {
      "type": "string",
      "enum": ["decaying", "invariant"],
      "description": "decaying: warrant authority weakens over time/turns. invariant: warrant validates against evidence or doesn't; no decay."
    },
    "birth_timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "When the warrant was established."
    },
    "support_n": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of training observations or evidence units backing this warrant. 0 = no support; treat with caution."
    },
    "coverage_status": {
      "type": "string",
      "enum": ["IN_DISTRIBUTION", "OUT_OF_DISTRIBUTION", "UNCLASSIFIED"],
      "description": "Whether the label assignment falls within the support of the trained / declared structure."
    },
    "confidence": {
      "type": ["number", "null"],
      "minimum": 0.0,
      "maximum": 1.0,
      "description": "Strength of the warrant at birth. May be heuristic (softmax over distances) or calibrated (density estimate)."
    },
    "evidence_refs": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Pointers into the L0 substrate that license the label. Examples: JSON paths, document offsets, cluster centroid IDs."
    },
    "validation_status": {
      "type": "string",
      "enum": ["PASS", "FAIL", "UNKNOWN"],
      "description": "Whether the warrant's evidence_refs actually resolved when checked."
    },
    "distance_to_centroid": {
      "type": ["number", "null"],
      "minimum": 0.0,
      "description": "For clustering-based L1: distance from this assignment to its assigned region's centroid. Optional."
    },
    "coverage_threshold": {
      "type": ["number", "null"],
      "minimum": 0.0,
      "description": "For clustering-based L1: the radius (e.g. p95 of training distances) defining IN_DISTRIBUTION for this region."
    },
    "relaxation_half_life_seconds": {
      "type": ["integer", "null"],
      "minimum": 1,
      "description": "For decaying warrants: half-life of warrant authority in seconds (or analogous unit for conversation-turn substrates)."
    }
  },
  "required": [
    "schema_version",
    "warrant_type",
    "birth_timestamp",
    "support_n",
    "coverage_status"
  ],
  "examples": [
    {
      "schema_version": "warrant-v0.1",
      "warrant_type": "decaying",
      "birth_timestamp": "2026-05-28T07:13:00Z",
      "support_n": 337,
      "coverage_status": "IN_DISTRIBUTION",
      "confidence": 0.72,
      "distance_to_centroid": 0.81,
      "coverage_threshold": 0.93,
      "relaxation_half_life_seconds": 21600
    },
    {
      "schema_version": "warrant-v0.1",
      "warrant_type": "invariant",
      "birth_timestamp": "2026-05-28T07:13:00Z",
      "support_n": 1,
      "coverage_status": "IN_DISTRIBUTION",
      "evidence_refs": ["json.company.ebitda", "json.company.revenue"],
      "validation_status": "PASS"
    }
  ]
}