{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docforge.local/schema/context-capsule-v1.json",
  "title": "DocForge task context capsule",
  "$defs": {
    "sha256": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$"
    },
    "pagination": {
      "type": "object",
      "required": [
        "schema_version",
        "kind",
        "returned_count",
        "limit",
        "total_count",
        "has_more",
        "next_cursor"
      ],
      "properties": {
        "schema_version": { "const": 1 },
        "kind": { "const": "task-context.items" },
        "returned_count": { "type": "integer", "minimum": 0 },
        "limit": { "type": "integer", "minimum": 1 },
        "total_count": { "type": "integer", "minimum": 0 },
        "has_more": { "type": "boolean" },
        "next_cursor": {
          "type": ["string", "null"],
          "minLength": 1,
          "maxLength": 8192
        }
      },
      "additionalProperties": false
    },
    "category": {
      "enum": [
        "structure",
        "implementation",
        "dependency",
        "execution",
        "data",
        "evidence",
        "context",
        "unclassified"
      ]
    },
    "step": {
      "type": "object",
      "required": [
        "step_id",
        "operation",
        "relation_scope",
        "relation_set_hash",
        "direction",
        "depth",
        "limit",
        "required",
        "evidence_role"
      ],
      "properties": {
        "step_id": { "type": "string", "minLength": 1, "maxLength": 64 },
        "operation": {
          "enum": ["exact", "search", "outgoing", "incoming", "metadata"]
        },
        "relation_scope": { "enum": ["none", "project_allowed"] },
        "relation_set_hash": {
          "oneOf": [
            { "$ref": "#/$defs/sha256" },
            { "type": "null" }
          ]
        },
        "direction": { "enum": ["none", "outgoing", "incoming"] },
        "depth": { "type": "integer", "minimum": 0 },
        "limit": { "type": "integer", "minimum": 1 },
        "required": { "type": "boolean" },
        "evidence_role": { "type": "string", "minLength": 1, "maxLength": 64 }
      },
      "additionalProperties": false
    },
    "requirement": {
      "type": "object",
      "required": ["requirement_id", "check", "category", "required"],
      "properties": {
        "requirement_id": { "type": "string", "minLength": 1, "maxLength": 128 },
        "check": { "const": "selected_relation_category" },
        "category": { "$ref": "#/$defs/category" },
        "required": { "const": true }
      },
      "additionalProperties": false
    },
    "plan": {
      "type": "object",
      "required": [
        "schema_version",
        "planner",
        "task_kind",
        "request_hash",
        "effective_policy_hash",
        "focus_node_id",
        "limits",
        "category_order",
        "steps",
        "requirements",
        "plan_hash"
      ],
      "properties": {
        "schema_version": { "const": 1 },
        "planner": {
          "type": "object",
          "required": ["id", "version"],
          "properties": {
            "id": { "const": "docforge.core.task-context" },
            "version": { "const": 1 }
          },
          "additionalProperties": false
        },
        "task_kind": {
          "enum": [
            "change",
            "implementation",
            "failure",
            "ownership",
            "test",
            "operation",
            "release"
          ]
        },
        "request_hash": { "$ref": "#/$defs/sha256" },
        "effective_policy_hash": { "$ref": "#/$defs/sha256" },
        "focus_node_id": { "type": ["string", "null"], "maxLength": 256 },
        "limits": {
          "type": "object",
          "required": [
            "max_evidence",
            "max_tokens",
            "max_depth",
            "max_candidate_edges"
          ],
          "properties": {
            "max_evidence": { "type": "integer", "minimum": 1, "maximum": 1000 },
            "max_tokens": { "type": "integer", "minimum": 1 },
            "max_depth": { "type": "integer", "minimum": 0 },
            "max_candidate_edges": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000
            }
          },
          "additionalProperties": false
        },
        "category_order": {
          "type": "array",
          "minItems": 8,
          "maxItems": 8,
          "items": { "$ref": "#/$defs/category" },
          "uniqueItems": true
        },
        "steps": {
          "type": "array",
          "minItems": 4,
          "maxItems": 4,
          "items": { "$ref": "#/$defs/step" }
        },
        "requirements": {
          "type": "array",
          "minItems": 1,
          "maxItems": 8,
          "items": { "$ref": "#/$defs/requirement" }
        },
        "plan_hash": { "$ref": "#/$defs/sha256" }
      },
      "additionalProperties": false
    },
    "relationship": {
      "type": "object",
      "required": [
        "source_id",
        "relation",
        "target_id",
        "direction",
        "category",
        "provenance"
      ],
      "properties": {
        "source_id": { "type": "string", "minLength": 1 },
        "relation": { "type": "string", "minLength": 1 },
        "target_id": { "type": "string", "minLength": 1 },
        "direction": { "enum": ["outgoing", "incoming"] },
        "category": { "$ref": "#/$defs/category" },
        "provenance": {
          "const": "validated_graph_edge_without_source_provenance"
        }
      },
      "additionalProperties": false
    },
    "evidence": {
      "type": "object",
      "required": [
        "evidence_hash",
        "role",
        "reason_code",
        "node_id",
        "title",
        "family",
        "authority",
        "status",
        "tags",
        "summary",
        "text",
        "estimated_tokens",
        "source",
        "depth",
        "relationship_path",
        "relationship_reasons",
        "provenance_limitations"
      ],
      "properties": {
        "evidence_hash": { "$ref": "#/$defs/sha256" },
        "role": { "enum": ["focus", "related"] },
        "reason_code": {
          "enum": ["exact_focus", "lexical_focus", "relationship_path"]
        },
        "node_id": { "type": "string", "minLength": 1 },
        "title": { "type": "string" },
        "family": { "type": "string" },
        "authority": { "type": "string" },
        "status": { "type": "string" },
        "tags": {
          "type": "array",
          "items": { "type": "string" }
        },
        "summary": { "type": "string" },
        "text": { "type": "string" },
        "estimated_tokens": { "type": "integer", "minimum": 1 },
        "source": {
          "type": "object",
          "required": ["path", "anchor", "content_hash"],
          "properties": {
            "path": { "type": "string", "minLength": 1 },
            "anchor": { "type": ["string", "null"] },
            "content_hash": { "$ref": "#/$defs/sha256" }
          },
          "additionalProperties": false
        },
        "depth": { "type": "integer", "minimum": 0 },
        "relationship_path": {
          "type": "array",
          "items": { "$ref": "#/$defs/relationship" }
        },
        "relationship_reasons": {
          "type": "array",
          "items": { "$ref": "#/$defs/relationship" },
          "uniqueItems": true
        },
        "provenance_limitations": {
          "const": [
            "evidence_type_unavailable",
            "extractor_identity_unavailable",
            "relationship_provenance_unavailable",
            "observation_time_unavailable"
          ]
        }
      },
      "additionalProperties": false
    },
    "gap": {
      "type": "object",
      "required": [
        "code",
        "requirement_id",
        "category",
        "state",
        "check_complete",
        "detail"
      ],
      "properties": {
        "code": {
          "enum": [
            "focus_not_found",
            "focus_ambiguous",
            "category_not_declared",
            "no_selected_evidence",
            "evidence_incomplete",
            "unclassified_relation"
          ]
        },
        "requirement_id": { "type": "string", "minLength": 1 },
        "category": {
          "oneOf": [
            { "$ref": "#/$defs/category" },
            { "type": "null" }
          ]
        },
        "state": { "enum": ["missing", "incomplete", "blocked", "limitation"] },
        "check_complete": { "type": "boolean" },
        "detail": { "type": "string", "minLength": 1, "maxLength": 1000 }
      },
      "additionalProperties": false
    },
    "omission": {
      "type": "object",
      "required": ["code", "subject", "detail_hash"],
      "properties": {
        "code": {
          "enum": [
            "result_limit",
            "token_budget",
            "response_limit",
            "edge_examination_limit",
            "unclassified_relation_limit"
          ]
        },
        "subject": { "type": "string", "minLength": 1, "maxLength": 256 },
        "detail_hash": { "$ref": "#/$defs/sha256" }
      },
      "additionalProperties": false
    }
  },
  "type": "object",
  "required": [
    "schema_version",
    "state",
    "task_kind",
    "generation",
    "plan",
    "focus",
    "evidence",
    "gaps",
    "omissions",
    "summary",
    "collection_hash",
    "capsule_hash"
  ],
  "properties": {
    "schema_version": { "const": 1 },
    "state": { "enum": ["complete", "incomplete", "blocked"] },
    "task_kind": {
      "enum": [
        "change",
        "implementation",
        "failure",
        "ownership",
        "test",
        "operation",
        "release"
      ]
    },
    "generation": {
      "type": "object",
      "required": [
        "project_id",
        "project_root_fingerprint",
        "adapter",
        "revision",
        "source_hash",
        "index_schema_version"
      ],
      "properties": {
        "project_id": { "type": "string", "minLength": 1 },
        "project_root_fingerprint": {
          "type": "string",
          "pattern": "^[0-9a-f]{16}$"
        },
        "adapter": { "type": "string", "minLength": 1 },
        "revision": { "type": "string", "minLength": 1 },
        "source_hash": { "$ref": "#/$defs/sha256" },
        "index_schema_version": { "type": "integer", "minimum": 1 }
      },
      "additionalProperties": false
    },
    "plan": { "$ref": "#/$defs/plan" },
    "focus": {
      "type": "object",
      "required": ["state", "node_id", "candidate_count"],
      "properties": {
        "state": { "enum": ["resolved", "not_found", "ambiguous"] },
        "node_id": { "type": ["string", "null"] },
        "candidate_count": { "type": "integer", "minimum": 0 }
      },
      "additionalProperties": false
    },
    "evidence": {
      "type": "array",
      "maxItems": 10000,
      "items": { "$ref": "#/$defs/evidence" }
    },
    "gaps": {
      "type": "array",
      "maxItems": 10000,
      "items": { "$ref": "#/$defs/gap" }
    },
    "omissions": {
      "type": "array",
      "maxItems": 10000,
      "items": { "$ref": "#/$defs/omission" }
    },
    "summary": {
      "type": "object",
      "required": [
        "evidence_count",
        "gap_count",
        "omission_count",
        "selected_count",
        "examined_edge_count",
        "estimated_tokens",
        "unclassified_relations"
      ],
      "properties": {
        "evidence_count": { "type": "integer", "minimum": 0 },
        "gap_count": { "type": "integer", "minimum": 0 },
        "omission_count": { "type": "integer", "minimum": 0 },
        "selected_count": { "type": "integer", "minimum": 0 },
        "examined_edge_count": { "type": "integer", "minimum": 0 },
        "estimated_tokens": { "type": "integer", "minimum": 0 },
        "unclassified_relations": {
          "type": "array",
          "maxItems": 10000,
          "items": { "type": "string", "minLength": 1 },
          "uniqueItems": true
        },
        "page_evidence_count": { "type": "integer", "minimum": 0 },
        "page_omission_count": { "type": "integer", "minimum": 0 },
        "page_item_count": { "type": "integer", "minimum": 0 }
      },
      "additionalProperties": false
    },
    "collection_hash": { "$ref": "#/$defs/sha256" },
    "capsule_hash": { "$ref": "#/$defs/sha256" },
    "page_state": { "enum": ["complete", "incomplete", "blocked"] },
    "page_hash": { "$ref": "#/$defs/sha256" },
    "pagination": { "$ref": "#/$defs/pagination" }
  },
  "additionalProperties": false
}