{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docforge.local/schema/result-v1.json",
  "title": "DocForge result envelope",
  "$defs": {
    "diagnostics": {
      "type": "object",
      "required": [
        "schema_version",
        "operation",
        "outcome",
        "elapsed_ns",
        "stages",
        "counters"
      ],
      "properties": {
        "schema_version": { "const": 1 },
        "operation": {
          "enum": [
            "test",
            "benchmark.m1",
            "benchmark.m2",
            "benchmark.m3",
            "mcp.invoke",
            "mcp.bootstrap",
            "mcp.sync",
            "mcp.project_info",
            "mcp.contract",
            "mcp.get_node",
            "mcp.get_logic",
            "mcp.search",
            "mcp.filter",
            "mcp.backlinks",
            "mcp.dependencies",
            "mcp.impact",
            "mcp.context",
            "mcp.task_context",
            "mcp.generation_diff",
            "mcp.validate_project",
            "mcp.render_status",
            "mcp.graph_plan",
            "mcp.graph_render_status",
            "mcp.visualize",
            "mcp.visualization_status",
            "mcp.stop_visualization",
            "mcp.changeset",
            "mcp.mutation",
            "cli.onboard",
            "cli.info",
            "cli.validate",
            "cli.build",
            "cli.reindex",
            "cli.sync",
            "cli.check",
            "cli.validate-index",
            "cli.show",
            "cli.search",
            "cli.filter",
            "cli.backlinks",
            "cli.dependencies",
            "cli.impact",
            "cli.context",
            "cli.generation-diff",
            "cli.graph-plan",
            "cli.graph-render",
            "cli.graph-render-status",
            "cli.configure",
            "cli.doctor",
            "cli.render",
            "cli.render-status",
            "cli.preview",
            "cli.apply",
            "cli.visualize",
            "cli.visualization-status",
            "cli.visualization-stop"
          ]
        },
        "outcome": { "enum": ["ok", "error"] },
        "elapsed_ns": { "type": "integer", "minimum": 0 },
        "stages": {
          "type": "object",
          "maxProperties": 14,
          "propertyNames": {
            "enum": [
              "source.generation",
              "source.parse",
              "adapter.projection",
              "adapter.extract",
              "index.check",
              "index.synchronize",
              "index.build",
              "index.read",
              "render.status",
              "render.prepare",
              "render.output_hash",
              "visualization.status",
              "viewer.manager",
              "mcp.runtime_validation"
            ]
          },
          "additionalProperties": {
            "type": "object",
            "required": ["calls", "elapsed_ns"],
            "properties": {
              "calls": { "type": "integer", "minimum": 1 },
              "elapsed_ns": { "type": "integer", "minimum": 0 }
            },
            "additionalProperties": false
          }
        },
        "counters": {
          "type": "object",
          "required": [
            "project_loads",
            "source_files_parsed",
            "source_bytes_parsed",
            "adapter_projection_loads",
            "adapter_source_extractions",
            "source_generation_checks",
            "index_checks",
            "index_synchronizations",
            "index_builds",
            "render_prepare_calls",
            "render_output_bytes_built",
            "render_output_bytes_hashed",
            "viewer_manager_requests"
          ],
          "properties": {
            "project_loads": { "type": "integer", "minimum": 0 },
            "source_files_parsed": { "type": "integer", "minimum": 0 },
            "source_bytes_parsed": { "type": "integer", "minimum": 0 },
            "adapter_projection_loads": { "type": "integer", "minimum": 0 },
            "adapter_source_extractions": { "type": "integer", "minimum": 0 },
            "source_generation_checks": { "type": "integer", "minimum": 0 },
            "index_checks": { "type": "integer", "minimum": 0 },
            "index_synchronizations": { "type": "integer", "minimum": 0 },
            "index_builds": { "type": "integer", "minimum": 0 },
            "render_prepare_calls": { "type": "integer", "minimum": 0 },
            "render_output_bytes_built": { "type": "integer", "minimum": 0 },
            "render_output_bytes_hashed": { "type": "integer", "minimum": 0 },
            "viewer_manager_requests": { "type": "integer", "minimum": 0 }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "pagination": {
      "type": "object",
      "required": [
        "schema_version",
        "kind",
        "returned_count",
        "limit",
        "total_count",
        "has_more",
        "next_cursor"
      ],
      "properties": {
        "schema_version": { "const": 1 },
        "kind": {
          "enum": [
            "context.items",
            "task-context.items",
            "generation-diff.items",
            "changeset.list",
            "changeset.inspect",
            "changeset.validate",
            "changeset.diff",
            "changeset.diff-chunks"
          ]
        },
        "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
    }
  },
  "oneOf": [
    {
      "type": "object",
      "required": ["status", "project_id", "source_hash"],
      "properties": {
        "status": { "const": "ok" },
        "project_id": { "type": "string" },
        "revision": { "type": "string" },
        "source_hash": {
          "type": ["string", "null"],
          "pattern": "^[0-9a-f]{64}$"
        },
        "adapter": { "type": "string" },
        "pagination": { "$ref": "#/$defs/pagination" },
        "diagnostics": { "$ref": "#/$defs/diagnostics" }
      },
      "additionalProperties": true
    },
    {
      "type": "object",
      "required": ["status", "error"],
      "properties": {
        "status": { "const": "error" },
        "project_id": { "type": "string" },
        "project_root_fingerprint": {
          "type": "string",
          "pattern": "^[0-9a-f]{16}$"
        },
        "adapter": { "type": "string" },
        "server_version": { "type": "string" },
        "revision": { "type": "string" },
        "source_hash": {
          "type": ["string", "null"],
          "pattern": "^[0-9a-f]{64}$"
        },
        "content_warning": { "type": "string" },
        "staleness": { "enum": ["current", "stale", "unknown"] },
        "synchronization": { "type": "object" },
        "diagnostics": { "$ref": "#/$defs/diagnostics" },
        "error": {
          "type": "object",
          "required": ["code", "message", "details"],
          "properties": {
            "code": { "type": "string", "minLength": 1 },
            "message": { "type": "string", "minLength": 1 },
            "details": { "type": "object" },
            "remediation": {
              "type": "object",
              "required": ["retryable"],
              "properties": {
                "retryable": { "type": "boolean" },
                "action": { "type": "string", "minLength": 1 },
                "tool": { "type": "string", "minLength": 1 },
                "arguments": { "type": "object" }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": true
    }
  ]
}