events.schema.json

{
  "$defs": {
    "JobEvent": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "additionalProperties": false,
      "properties": {
        "attempt": {
          "default": 0,
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "details": {
          "additionalProperties": true,
          "type": "object"
        },
        "event_id": {
          "type": "string"
        },
        "job_id": {
          "$ref": "#/$defs/JobEvent_JobId"
        },
        "message": {
          "type": "string"
        },
        "phase": {
          "$ref": "#/$defs/JobEvent_PipelinePhase"
        },
        "sequence": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "severity": {
          "$ref": "#/$defs/JobEvent_Severity"
        },
        "stage_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/JobEvent_StageId"
            },
            {
              "type": "null"
            }
          ]
        },
        "status": {
          "$ref": "#/$defs/JobEvent_LifecycleStatus"
        },
        "timestamp": {
          "type": "string"
        },
        "visibility": {
          "$ref": "#/$defs/JobEvent_Visibility",
          "default": "internal"
        }
      },
      "required": [
        "event_id",
        "sequence",
        "job_id",
        "phase",
        "status",
        "severity",
        "message",
        "timestamp",
        "details"
      ],
      "title": "JobEvent",
      "type": "object"
    },
    "JobEventPage": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "additionalProperties": false,
      "properties": {
        "events": {
          "items": {
            "$ref": "#/$defs/JobEventPage_JobEvent"
          },
          "type": "array"
        },
        "last_sequence": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "limit": {
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "next_cursor": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "events",
        "last_sequence"
      ],
      "title": "JobEventPage",
      "type": "object"
    },
    "JobEventPage_JobEvent": {
      "additionalProperties": false,
      "properties": {
        "attempt": {
          "default": 0,
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "details": {
          "additionalProperties": true,
          "type": "object"
        },
        "event_id": {
          "type": "string"
        },
        "job_id": {
          "$ref": "#/$defs/JobEventPage_JobId"
        },
        "message": {
          "type": "string"
        },
        "phase": {
          "$ref": "#/$defs/JobEventPage_PipelinePhase"
        },
        "sequence": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "severity": {
          "$ref": "#/$defs/JobEventPage_Severity"
        },
        "stage_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/JobEventPage_StageId"
            },
            {
              "type": "null"
            }
          ]
        },
        "status": {
          "$ref": "#/$defs/JobEventPage_LifecycleStatus"
        },
        "timestamp": {
          "type": "string"
        },
        "visibility": {
          "$ref": "#/$defs/JobEventPage_Visibility",
          "default": "internal"
        }
      },
      "required": [
        "event_id",
        "sequence",
        "job_id",
        "phase",
        "status",
        "severity",
        "message",
        "timestamp",
        "details"
      ],
      "type": "object"
    },
    "JobEventPage_JobId": {
      "format": "uuid",
      "type": "string"
    },
    "JobEventPage_LifecycleStatus": {
      "enum": [
        "queued",
        "pending",
        "running",
        "waiting",
        "blocked",
        "canceling",
        "completed",
        "completed_degraded",
        "failed",
        "canceled",
        "expired",
        "skipped"
      ],
      "type": "string"
    },
    "JobEventPage_PipelinePhase": {
      "enum": [
        "queued",
        "requested",
        "resolving",
        "routing",
        "authorizing",
        "planning",
        "leasing",
        "discovering",
        "diffing",
        "fetching",
        "rendering",
        "enriching",
        "normalizing",
        "parsing",
        "graphing",
        "preparing",
        "batching",
        "embedding",
        "vectorizing",
        "upserting",
        "retrieving",
        "synthesizing",
        "evaluating",
        "publishing",
        "cleaning",
        "complete",
        "canceled"
      ],
      "type": "string"
    },
    "JobEventPage_Severity": {
      "enum": [
        "debug",
        "info",
        "warning",
        "degraded",
        "failed",
        "fatal"
      ],
      "type": "string"
    },
    "JobEventPage_StageId": {
      "format": "uuid",
      "type": "string"
    },
    "JobEventPage_Visibility": {
      "enum": [
        "public",
        "internal",
        "sensitive",
        "redacted",
        "derived"
      ],
      "type": "string"
    },
    "JobEvent_JobId": {
      "format": "uuid",
      "type": "string"
    },
    "JobEvent_LifecycleStatus": {
      "enum": [
        "queued",
        "pending",
        "running",
        "waiting",
        "blocked",
        "canceling",
        "completed",
        "completed_degraded",
        "failed",
        "canceled",
        "expired",
        "skipped"
      ],
      "type": "string"
    },
    "JobEvent_PipelinePhase": {
      "enum": [
        "queued",
        "requested",
        "resolving",
        "routing",
        "authorizing",
        "planning",
        "leasing",
        "discovering",
        "diffing",
        "fetching",
        "rendering",
        "enriching",
        "normalizing",
        "parsing",
        "graphing",
        "preparing",
        "batching",
        "embedding",
        "vectorizing",
        "upserting",
        "retrieving",
        "synthesizing",
        "evaluating",
        "publishing",
        "cleaning",
        "complete",
        "canceled"
      ],
      "type": "string"
    },
    "JobEvent_Severity": {
      "enum": [
        "debug",
        "info",
        "warning",
        "degraded",
        "failed",
        "fatal"
      ],
      "type": "string"
    },
    "JobEvent_StageId": {
      "format": "uuid",
      "type": "string"
    },
    "JobEvent_Visibility": {
      "enum": [
        "public",
        "internal",
        "sensitive",
        "redacted",
        "derived"
      ],
      "type": "string"
    },
    "JobHeartbeat": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "additionalProperties": false,
      "properties": {
        "attempt": {
          "default": 0,
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "counts": {
          "anyOf": [
            {
              "$ref": "#/$defs/JobHeartbeat_StageCounts"
            },
            {
              "type": "null"
            }
          ]
        },
        "heartbeat_at": {
          "type": "string"
        },
        "job_id": {
          "$ref": "#/$defs/JobHeartbeat_JobId"
        },
        "last_event_sequence": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "last_progress_at": {
          "description": "Timestamp of the last progress-bearing event observed for this job\n(distinct from `heartbeat_at`, which is just the liveness ping time).",
          "type": [
            "string",
            "null"
          ]
        },
        "phase": {
          "$ref": "#/$defs/JobHeartbeat_PipelinePhase"
        },
        "provider_reservations": {
          "items": {
            "$ref": "#/$defs/JobHeartbeat_ProviderReservationSnapshot"
          },
          "type": "array"
        },
        "sequence": {
          "default": 0,
          "description": "Monotonic heartbeat sequence number for this job, per\n`docs/pipeline-unification/schemas/event-schema.md`'s `JobHeartbeat` shape.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "stage_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/JobHeartbeat_StageId"
            },
            {
              "type": "null"
            }
          ]
        },
        "status": {
          "$ref": "#/$defs/JobHeartbeat_LifecycleStatus"
        },
        "worker_id": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "job_id",
        "phase",
        "status",
        "heartbeat_at"
      ],
      "title": "JobHeartbeat",
      "type": "object"
    },
    "JobHeartbeat_JobId": {
      "format": "uuid",
      "type": "string"
    },
    "JobHeartbeat_JobPriority": {
      "enum": [
        "interactive",
        "high",
        "normal",
        "background",
        "maintenance"
      ],
      "type": "string"
    },
    "JobHeartbeat_LifecycleStatus": {
      "enum": [
        "queued",
        "pending",
        "running",
        "waiting",
        "blocked",
        "canceling",
        "completed",
        "completed_degraded",
        "failed",
        "canceled",
        "expired",
        "skipped"
      ],
      "type": "string"
    },
    "JobHeartbeat_PipelinePhase": {
      "enum": [
        "queued",
        "requested",
        "resolving",
        "routing",
        "authorizing",
        "planning",
        "leasing",
        "discovering",
        "diffing",
        "fetching",
        "rendering",
        "enriching",
        "normalizing",
        "parsing",
        "graphing",
        "preparing",
        "batching",
        "embedding",
        "vectorizing",
        "upserting",
        "retrieving",
        "synthesizing",
        "evaluating",
        "publishing",
        "cleaning",
        "complete",
        "canceled"
      ],
      "type": "string"
    },
    "JobHeartbeat_ProviderCoolingSnapshot": {
      "additionalProperties": false,
      "properties": {
        "degraded": {
          "type": "boolean"
        },
        "reason": {
          "type": "string"
        },
        "retry_after": {
          "type": [
            "string",
            "null"
          ]
        },
        "started_at": {
          "type": "string"
        }
      },
      "required": [
        "reason",
        "started_at",
        "degraded"
      ],
      "type": "object"
    },
    "JobHeartbeat_ProviderId": {
      "type": "string"
    },
    "JobHeartbeat_ProviderKind": {
      "enum": [
        "llm",
        "embedding",
        "vector",
        "search",
        "fetch",
        "render",
        "parser",
        "network_capture",
        "artifact",
        "ledger",
        "graph",
        "memory",
        "job",
        "watch",
        "config",
        "credential",
        "cache",
        "security",
        "rate_limiter",
        "health_probe"
      ],
      "type": "string"
    },
    "JobHeartbeat_ProviderReservationSnapshot": {
      "additionalProperties": false,
      "properties": {
        "acquired_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "cooling": {
          "anyOf": [
            {
              "$ref": "#/$defs/JobHeartbeat_ProviderCoolingSnapshot"
            },
            {
              "type": "null"
            }
          ]
        },
        "expires_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "granted_units": {
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "priority": {
          "$ref": "#/$defs/JobHeartbeat_JobPriority"
        },
        "provider_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/JobHeartbeat_ProviderId"
            },
            {
              "type": "null"
            }
          ]
        },
        "provider_kind": {
          "$ref": "#/$defs/JobHeartbeat_ProviderKind"
        },
        "queue_depth": {
          "format": "uint32",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "requested_units": {
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "reservation_id": {
          "$ref": "#/$defs/JobHeartbeat_ReservationId"
        },
        "status": {
          "$ref": "#/$defs/JobHeartbeat_ProviderReservationStatus"
        }
      },
      "required": [
        "reservation_id",
        "provider_kind",
        "priority",
        "requested_units",
        "granted_units",
        "status"
      ],
      "type": "object"
    },
    "JobHeartbeat_ProviderReservationStatus": {
      "enum": [
        "requested",
        "queued",
        "granted",
        "active",
        "released",
        "expired",
        "canceled",
        "failed"
      ],
      "type": "string"
    },
    "JobHeartbeat_ReservationId": {
      "type": "string"
    },
    "JobHeartbeat_StageCounts": {
      "additionalProperties": false,
      "properties": {
        "bytes_done": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "bytes_total": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "chunks_done": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "chunks_total": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "documents_done": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "documents_total": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "items_done": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "items_total": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "required": [
        "items_done",
        "documents_done",
        "chunks_done",
        "bytes_done"
      ],
      "type": "object"
    },
    "JobHeartbeat_StageId": {
      "format": "uuid",
      "type": "string"
    },
    "LogFieldSet": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "description": "The canonical structured-log field set. See the \"Logs\" table in\n`runtime/observability-contract.md` for the required-field list and the\n\"Forbidden in logs\" list (raw auth headers, tokens/API keys/cookies, raw\nenv values, unredacted private prompts/responses, unredacted local\nabsolute paths in public logs).",
      "properties": {
        "error_code": {
          "type": [
            "string",
            "null"
          ]
        },
        "job_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/LogFieldSet_JobId"
            },
            {
              "type": "null"
            }
          ]
        },
        "level": {
          "$ref": "#/$defs/LogFieldSet_LogLevel"
        },
        "message": {
          "type": "string"
        },
        "phase": {
          "anyOf": [
            {
              "$ref": "#/$defs/LogFieldSet_PipelinePhase"
            },
            {
              "type": "null"
            }
          ]
        },
        "provider_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/LogFieldSet_ProviderId"
            },
            {
              "type": "null"
            }
          ]
        },
        "request_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "source_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/LogFieldSet_SourceId"
            },
            {
              "type": "null"
            }
          ]
        },
        "target": {
          "type": "string"
        },
        "timestamp": {
          "type": "string"
        }
      },
      "required": [
        "timestamp",
        "level",
        "target",
        "message"
      ],
      "title": "LogFieldSet",
      "type": "object"
    },
    "LogFieldSet_JobId": {
      "format": "uuid",
      "type": "string"
    },
    "LogFieldSet_LogLevel": {
      "description": "Log severity. Mirrors `tracing::Level`'s five levels so `LogFieldSet` can\nbe built from either a `tracing` event or a non-`tracing` log sink.",
      "enum": [
        "trace",
        "debug",
        "info",
        "warn",
        "error"
      ],
      "type": "string"
    },
    "LogFieldSet_PipelinePhase": {
      "enum": [
        "queued",
        "requested",
        "resolving",
        "routing",
        "authorizing",
        "planning",
        "leasing",
        "discovering",
        "diffing",
        "fetching",
        "rendering",
        "enriching",
        "normalizing",
        "parsing",
        "graphing",
        "preparing",
        "batching",
        "embedding",
        "vectorizing",
        "upserting",
        "retrieving",
        "synthesizing",
        "evaluating",
        "publishing",
        "cleaning",
        "complete",
        "canceled"
      ],
      "type": "string"
    },
    "LogFieldSet_ProviderId": {
      "type": "string"
    },
    "LogFieldSet_SourceId": {
      "type": "string"
    },
    "MetricSample": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "labels": {
          "additionalProperties": true,
          "type": "object"
        },
        "name": {
          "type": "string"
        },
        "timestamp": {
          "type": "string"
        },
        "unit": {
          "type": [
            "string",
            "null"
          ]
        },
        "value": {
          "format": "double",
          "type": "number"
        }
      },
      "required": [
        "name",
        "value",
        "labels",
        "timestamp"
      ],
      "title": "MetricSample",
      "type": "object"
    },
    "ProgressCurrent": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "additionalProperties": false,
      "properties": {
        "adapter": {
          "type": [
            "string",
            "null"
          ]
        },
        "chunk_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/ProgressCurrent_ChunkId"
            },
            {
              "type": "null"
            }
          ]
        },
        "document_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/ProgressCurrent_DocumentId"
            },
            {
              "type": "null"
            }
          ]
        },
        "message": {
          "type": [
            "string",
            "null"
          ]
        },
        "provider": {
          "anyOf": [
            {
              "$ref": "#/$defs/ProgressCurrent_ProviderId"
            },
            {
              "type": "null"
            }
          ]
        },
        "source_item_key": {
          "anyOf": [
            {
              "$ref": "#/$defs/ProgressCurrent_SourceItemKey"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "title": "ProgressCurrent",
      "type": "object"
    },
    "ProgressCurrent_ChunkId": {
      "type": "string"
    },
    "ProgressCurrent_DocumentId": {
      "type": "string"
    },
    "ProgressCurrent_ProviderId": {
      "type": "string"
    },
    "ProgressCurrent_SourceItemKey": {
      "type": "string"
    },
    "ProgressTiming": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "additionalProperties": false,
      "properties": {
        "elapsed_ms": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "eta_ms": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "started_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        }
      },
      "required": [
        "started_at",
        "updated_at",
        "elapsed_ms"
      ],
      "title": "ProgressTiming",
      "type": "object"
    },
    "SourceProgressEvent": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "additionalProperties": false,
      "properties": {
        "adapter": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_AdapterRef"
            },
            {
              "type": "null"
            }
          ]
        },
        "attempt": {
          "default": 0,
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "batch_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_BatchId"
            },
            {
              "type": "null"
            }
          ]
        },
        "canonical_uri": {
          "type": [
            "string",
            "null"
          ]
        },
        "checkpoint_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_CheckpointId"
            },
            {
              "type": "null"
            }
          ]
        },
        "counts": {
          "$ref": "#/$defs/SourceProgressEvent_StageCounts"
        },
        "current": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_ProgressCurrent"
            },
            {
              "type": "null"
            }
          ]
        },
        "dedupe_key": {
          "type": [
            "string",
            "null"
          ]
        },
        "error": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_ApiError"
            },
            {
              "type": "null"
            }
          ]
        },
        "event_id": {
          "type": "string"
        },
        "generation": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_SourceGenerationId"
            },
            {
              "type": "null"
            }
          ]
        },
        "job_id": {
          "$ref": "#/$defs/SourceProgressEvent_JobId"
        },
        "message": {
          "type": "string"
        },
        "phase": {
          "$ref": "#/$defs/SourceProgressEvent_PipelinePhase"
        },
        "reservation_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_ReservationId"
            },
            {
              "type": "null"
            }
          ]
        },
        "retry": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_RetryState"
            },
            {
              "type": "null"
            }
          ]
        },
        "scope": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_SourceScope"
            },
            {
              "type": "null"
            }
          ]
        },
        "sequence": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "severity": {
          "$ref": "#/$defs/SourceProgressEvent_Severity"
        },
        "source_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_SourceId"
            },
            {
              "type": "null"
            }
          ]
        },
        "stage_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_StageId"
            },
            {
              "type": "null"
            }
          ]
        },
        "status": {
          "$ref": "#/$defs/SourceProgressEvent_LifecycleStatus"
        },
        "throughput": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_ProgressThroughput"
            },
            {
              "type": "null"
            }
          ]
        },
        "timestamp": {
          "type": "string"
        },
        "timing": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_ProgressTiming"
            },
            {
              "type": "null"
            }
          ]
        },
        "visibility": {
          "$ref": "#/$defs/SourceProgressEvent_Visibility"
        },
        "warning": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_SourceWarning"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "event_id",
        "sequence",
        "job_id",
        "phase",
        "status",
        "severity",
        "visibility",
        "message",
        "timestamp",
        "counts"
      ],
      "title": "SourceProgressEvent",
      "type": "object"
    },
    "SourceProgressEvent_AdapterRef": {
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string"
        },
        "version": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "version"
      ],
      "type": "object"
    },
    "SourceProgressEvent_ApiError": {
      "description": "The shared, transport-neutral error shape.\n\nEvery crate reports failures as an `ApiError` so CLI, REST, MCP, jobs, logs,\nand progress streams render one consistent structure.",
      "properties": {
        "chunk_id": {
          "description": "Chunk id.",
          "type": [
            "string",
            "null"
          ]
        },
        "code": {
          "$ref": "#/$defs/SourceProgressEvent_ErrorCode",
          "description": "Stable machine code (e.g. `provider.unavailable`)."
        },
        "cooldown_until": {
          "description": "Provider/job cooling timestamp.",
          "format": "date-time",
          "type": [
            "string",
            "null"
          ]
        },
        "details": {
          "additionalProperties": {
            "type": "string"
          },
          "description": "Redacted structured context (safe key/value pairs only).",
          "type": "object"
        },
        "document_id": {
          "description": "Document id.",
          "type": [
            "string",
            "null"
          ]
        },
        "job_id": {
          "description": "Job correlation id.",
          "type": [
            "string",
            "null"
          ]
        },
        "message": {
          "description": "Redacted human-readable message.",
          "type": "string"
        },
        "provider_id": {
          "description": "Provider that failed.",
          "type": [
            "string",
            "null"
          ]
        },
        "retry_after_ms": {
          "description": "Suggested retry delay, in milliseconds.",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "retryable": {
          "description": "Whether retry may succeed.",
          "type": "boolean"
        },
        "severity": {
          "$ref": "#/$defs/SourceProgressEvent_ErrorSeverity",
          "description": "Severity classification."
        },
        "source_id": {
          "description": "Source id.",
          "type": [
            "string",
            "null"
          ]
        },
        "source_item_key": {
          "description": "Item/file/page key.",
          "type": [
            "string",
            "null"
          ]
        },
        "stage": {
          "$ref": "#/$defs/SourceProgressEvent_ErrorStage",
          "description": "Pipeline/transport stage."
        },
        "visibility": {
          "$ref": "#/$defs/SourceProgressEvent_ErrorVisibility",
          "description": "Where this error may be surfaced."
        }
      },
      "required": [
        "code",
        "message",
        "stage",
        "retryable",
        "severity",
        "visibility",
        "details"
      ],
      "type": "object"
    },
    "SourceProgressEvent_BatchId": {
      "format": "uuid",
      "type": "string"
    },
    "SourceProgressEvent_CheckpointId": {
      "type": "string"
    },
    "SourceProgressEvent_ChunkId": {
      "type": "string"
    },
    "SourceProgressEvent_DocumentId": {
      "type": "string"
    },
    "SourceProgressEvent_ErrorCode": {
      "description": "A stable, machine-readable error code (e.g. `provider.unavailable`).",
      "type": "string"
    },
    "SourceProgressEvent_ErrorSeverity": {
      "description": "How severe an error is and whether it terminates the item/job.",
      "oneOf": [
        {
          "const": "info",
          "description": "Informational event; not terminal.",
          "type": "string"
        },
        {
          "const": "warning",
          "description": "Non-fatal issue, full behavior preserved; not terminal.",
          "type": "string"
        },
        {
          "const": "degraded",
          "description": "Behavior reduced but acceptable by policy; may or may not be terminal.",
          "type": "string"
        },
        {
          "const": "failed",
          "description": "Required work failed; terminal for the affected item/job.",
          "type": "string"
        },
        {
          "const": "fatal",
          "description": "Cannot continue safely; terminal.",
          "type": "string"
        }
      ]
    },
    "SourceProgressEvent_ErrorStage": {
      "description": "Pipeline/transport stage an error is attributed to.",
      "oneOf": [
        {
          "const": "parsing",
          "description": "CLI/MCP/REST request parse, removed command/action.",
          "type": "string"
        },
        {
          "const": "validation",
          "description": "Missing fields, bad types, unsupported flags.",
          "type": "string"
        },
        {
          "const": "resolving",
          "description": "Source resolution, canonical URI, authority.",
          "type": "string"
        },
        {
          "const": "routing",
          "description": "Adapter/scope/provider selection.",
          "type": "string"
        },
        {
          "const": "authorizing",
          "description": "Auth, credentials, execution policy.",
          "type": "string"
        },
        {
          "const": "planning",
          "description": "Source plan, prune plan.",
          "type": "string"
        },
        {
          "const": "leasing",
          "description": "Job/watch/source lease.",
          "type": "string"
        },
        {
          "const": "discovering",
          "description": "Manifest/map discovery.",
          "type": "string"
        },
        {
          "const": "diffing",
          "description": "Manifest diff.",
          "type": "string"
        },
        {
          "const": "fetching",
          "description": "HTTP/git/package/local/MCP/CLI fetch.",
          "type": "string"
        },
        {
          "const": "rendering",
          "description": "Browser/CDP/render provider.",
          "type": "string"
        },
        {
          "const": "enriching",
          "description": "Enrichment (metadata/classification/summary/extraction/authority).",
          "type": "string"
        },
        {
          "const": "normalizing",
          "description": "SourceDocument creation.",
          "type": "string"
        },
        {
          "const": "parsing_content",
          "description": "Parser facts/chunk parser (serialized as `parsing_content`).",
          "type": "string"
        },
        {
          "const": "graphing",
          "description": "Graph writes/merge/conflict.",
          "type": "string"
        },
        {
          "const": "preparing",
          "description": "Chunking/PreparedDocument.",
          "type": "string"
        },
        {
          "const": "batching",
          "description": "Batch assembly for embedding/vectorizing.",
          "type": "string"
        },
        {
          "const": "embedding",
          "description": "Embedding provider/batch.",
          "type": "string"
        },
        {
          "const": "vectorizing",
          "description": "Vector point construction/payload build.",
          "type": "string"
        },
        {
          "const": "upserting",
          "description": "VectorStore writes.",
          "type": "string"
        },
        {
          "const": "publishing",
          "description": "Generation publish.",
          "type": "string"
        },
        {
          "const": "cleaning",
          "description": "Cleanup/prune/dedupe.",
          "type": "string"
        },
        {
          "const": "retrieving",
          "description": "Query/retrieve context.",
          "type": "string"
        },
        {
          "const": "synthesizing",
          "description": "LLM synthesis.",
          "type": "string"
        },
        {
          "const": "evaluating",
          "description": "RAG/evaluation scoring.",
          "type": "string"
        },
        {
          "const": "observing",
          "description": "Progress/log/status emit.",
          "type": "string"
        },
        {
          "const": "storage",
          "description": "Storage boundary (ledger/artifact/job store), phase-contextual.",
          "type": "string"
        },
        {
          "const": "provider",
          "description": "Provider boundary (embedding/llm/render/search), phase-contextual.",
          "type": "string"
        },
        {
          "const": "transport",
          "description": "Transport boundary (CLI/REST/MCP dispatch), phase-contextual.",
          "type": "string"
        },
        {
          "const": "internal",
          "description": "Internal/unclassified failure within the active operation phase.",
          "type": "string"
        }
      ]
    },
    "SourceProgressEvent_ErrorVisibility": {
      "description": "Where a context entry (or error) may be surfaced.\n\nFrom the \"visibility\" field in the error shape: `public`, `internal`,\n`sensitive`.",
      "oneOf": [
        {
          "const": "public",
          "description": "Safe to render to any caller, including remote/unauthenticated.",
          "type": "string"
        },
        {
          "const": "internal",
          "description": "Internal diagnostics; render only to internal/admin surfaces.",
          "type": "string"
        },
        {
          "const": "sensitive",
          "description": "Sensitive/secret-adjacent; never render raw, redaction required.",
          "type": "string"
        }
      ]
    },
    "SourceProgressEvent_JobId": {
      "format": "uuid",
      "type": "string"
    },
    "SourceProgressEvent_LifecycleStatus": {
      "enum": [
        "queued",
        "pending",
        "running",
        "waiting",
        "blocked",
        "canceling",
        "completed",
        "completed_degraded",
        "failed",
        "canceled",
        "expired",
        "skipped"
      ],
      "type": "string"
    },
    "SourceProgressEvent_PipelinePhase": {
      "enum": [
        "queued",
        "requested",
        "resolving",
        "routing",
        "authorizing",
        "planning",
        "leasing",
        "discovering",
        "diffing",
        "fetching",
        "rendering",
        "enriching",
        "normalizing",
        "parsing",
        "graphing",
        "preparing",
        "batching",
        "embedding",
        "vectorizing",
        "upserting",
        "retrieving",
        "synthesizing",
        "evaluating",
        "publishing",
        "cleaning",
        "complete",
        "canceled"
      ],
      "type": "string"
    },
    "SourceProgressEvent_ProgressCurrent": {
      "additionalProperties": false,
      "properties": {
        "adapter": {
          "type": [
            "string",
            "null"
          ]
        },
        "chunk_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_ChunkId"
            },
            {
              "type": "null"
            }
          ]
        },
        "document_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_DocumentId"
            },
            {
              "type": "null"
            }
          ]
        },
        "message": {
          "type": [
            "string",
            "null"
          ]
        },
        "provider": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_ProviderId"
            },
            {
              "type": "null"
            }
          ]
        },
        "source_item_key": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_SourceItemKey"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "type": "object"
    },
    "SourceProgressEvent_ProgressThroughput": {
      "additionalProperties": false,
      "properties": {
        "bytes_per_second": {
          "format": "double",
          "type": [
            "number",
            "null"
          ]
        },
        "chunks_per_second": {
          "format": "double",
          "type": [
            "number",
            "null"
          ]
        },
        "items_per_second": {
          "format": "double",
          "type": [
            "number",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "SourceProgressEvent_ProgressTiming": {
      "additionalProperties": false,
      "properties": {
        "elapsed_ms": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "eta_ms": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "started_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        }
      },
      "required": [
        "started_at",
        "updated_at",
        "elapsed_ms"
      ],
      "type": "object"
    },
    "SourceProgressEvent_ProviderId": {
      "type": "string"
    },
    "SourceProgressEvent_ReservationId": {
      "type": "string"
    },
    "SourceProgressEvent_RetryState": {
      "additionalProperties": false,
      "properties": {
        "attempt": {
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "max_attempts": {
          "format": "uint32",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "next_retry_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "reason": {
          "type": "string"
        }
      },
      "required": [
        "attempt",
        "reason"
      ],
      "type": "object"
    },
    "SourceProgressEvent_Severity": {
      "enum": [
        "debug",
        "info",
        "warning",
        "degraded",
        "failed",
        "fatal"
      ],
      "type": "string"
    },
    "SourceProgressEvent_SourceGenerationId": {
      "type": "string"
    },
    "SourceProgressEvent_SourceId": {
      "type": "string"
    },
    "SourceProgressEvent_SourceItemKey": {
      "type": "string"
    },
    "SourceProgressEvent_SourceScope": {
      "enum": [
        "page",
        "site",
        "docs",
        "repo",
        "workspace",
        "branch",
        "org",
        "package",
        "version",
        "feed",
        "subreddit",
        "thread",
        "comment",
        "video",
        "playlist",
        "channel",
        "issue",
        "pull_request",
        "merge_request",
        "release",
        "wiki",
        "file",
        "directory",
        "map",
        "tool",
        "script",
        "api"
      ],
      "type": "string"
    },
    "SourceProgressEvent_SourceWarning": {
      "additionalProperties": false,
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        },
        "severity": {
          "$ref": "#/$defs/SourceProgressEvent_Severity"
        },
        "source_item_key": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceProgressEvent_SourceItemKey"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "code",
        "severity",
        "message",
        "retryable"
      ],
      "type": "object"
    },
    "SourceProgressEvent_StageCounts": {
      "additionalProperties": false,
      "properties": {
        "bytes_done": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "bytes_total": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "chunks_done": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "chunks_total": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "documents_done": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "documents_total": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "items_done": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "items_total": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "required": [
        "items_done",
        "documents_done",
        "chunks_done",
        "bytes_done"
      ],
      "type": "object"
    },
    "SourceProgressEvent_StageId": {
      "format": "uuid",
      "type": "string"
    },
    "SourceProgressEvent_Visibility": {
      "enum": [
        "public",
        "internal",
        "sensitive",
        "redacted",
        "derived"
      ],
      "type": "string"
    },
    "SpanFieldSet": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "description": "The canonical bounded span/log field set.",
      "properties": {
        "adapter": {
          "type": [
            "string",
            "null"
          ]
        },
        "canonical_uri": {
          "type": [
            "string",
            "null"
          ]
        },
        "chunk_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/SpanFieldSet_ChunkId"
            },
            {
              "type": "null"
            }
          ]
        },
        "counts": {
          "anyOf": [
            {
              "$ref": "#/$defs/SpanFieldSet_StageCounts"
            },
            {
              "type": "null"
            }
          ]
        },
        "document_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/SpanFieldSet_DocumentId"
            },
            {
              "type": "null"
            }
          ]
        },
        "error_code": {
          "type": [
            "string",
            "null"
          ]
        },
        "generation": {
          "anyOf": [
            {
              "$ref": "#/$defs/SpanFieldSet_SourceGenerationId"
            },
            {
              "type": "null"
            }
          ]
        },
        "job_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/SpanFieldSet_JobId"
            },
            {
              "type": "null"
            }
          ]
        },
        "phase": {
          "anyOf": [
            {
              "$ref": "#/$defs/SpanFieldSet_PipelinePhase"
            },
            {
              "type": "null"
            }
          ]
        },
        "provider_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/SpanFieldSet_ProviderId"
            },
            {
              "type": "null"
            }
          ]
        },
        "scope": {
          "anyOf": [
            {
              "$ref": "#/$defs/SpanFieldSet_SourceScope"
            },
            {
              "type": "null"
            }
          ]
        },
        "severity": {
          "anyOf": [
            {
              "$ref": "#/$defs/SpanFieldSet_Severity"
            },
            {
              "type": "null"
            }
          ]
        },
        "source_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/SpanFieldSet_SourceId"
            },
            {
              "type": "null"
            }
          ]
        },
        "source_item_key": {
          "anyOf": [
            {
              "$ref": "#/$defs/SpanFieldSet_SourceItemKey"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "title": "SpanFieldSet",
      "type": "object"
    },
    "SpanFieldSet_ChunkId": {
      "type": "string"
    },
    "SpanFieldSet_DocumentId": {
      "type": "string"
    },
    "SpanFieldSet_JobId": {
      "format": "uuid",
      "type": "string"
    },
    "SpanFieldSet_PipelinePhase": {
      "enum": [
        "queued",
        "requested",
        "resolving",
        "routing",
        "authorizing",
        "planning",
        "leasing",
        "discovering",
        "diffing",
        "fetching",
        "rendering",
        "enriching",
        "normalizing",
        "parsing",
        "graphing",
        "preparing",
        "batching",
        "embedding",
        "vectorizing",
        "upserting",
        "retrieving",
        "synthesizing",
        "evaluating",
        "publishing",
        "cleaning",
        "complete",
        "canceled"
      ],
      "type": "string"
    },
    "SpanFieldSet_ProviderId": {
      "type": "string"
    },
    "SpanFieldSet_Severity": {
      "enum": [
        "debug",
        "info",
        "warning",
        "degraded",
        "failed",
        "fatal"
      ],
      "type": "string"
    },
    "SpanFieldSet_SourceGenerationId": {
      "type": "string"
    },
    "SpanFieldSet_SourceId": {
      "type": "string"
    },
    "SpanFieldSet_SourceItemKey": {
      "type": "string"
    },
    "SpanFieldSet_SourceScope": {
      "enum": [
        "page",
        "site",
        "docs",
        "repo",
        "workspace",
        "branch",
        "org",
        "package",
        "version",
        "feed",
        "subreddit",
        "thread",
        "comment",
        "video",
        "playlist",
        "channel",
        "issue",
        "pull_request",
        "merge_request",
        "release",
        "wiki",
        "file",
        "directory",
        "map",
        "tool",
        "script",
        "api"
      ],
      "type": "string"
    },
    "SpanFieldSet_StageCounts": {
      "additionalProperties": false,
      "properties": {
        "bytes_done": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "bytes_total": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "chunks_done": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "chunks_total": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "documents_done": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "documents_total": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "items_done": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "items_total": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "required": [
        "items_done",
        "documents_done",
        "chunks_done",
        "bytes_done"
      ],
      "type": "object"
    },
    "StageCounts": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "additionalProperties": false,
      "properties": {
        "bytes_done": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "bytes_total": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "chunks_done": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "chunks_total": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "documents_done": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "documents_total": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "items_done": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "items_total": {
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "required": [
        "items_done",
        "documents_done",
        "chunks_done",
        "bytes_done"
      ],
      "title": "StageCounts",
      "type": "object"
    },
    "StreamEvent": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "additionalProperties": false,
      "description": "The contracted flat SSE/MCP streaming envelope. `data` carries the\nkind-specific payload (a `SourceProgressEvent` for `progress`, the\nroute-specific result DTO for `final`, a `{ \"text\": ... }` object for\n`token`, etc.) — see the contract doc for the per-kind validation rules.",
      "properties": {
        "data": {
          "default": {}
        },
        "error": {
          "anyOf": [
            {
              "$ref": "#/$defs/StreamEvent_ApiError"
            },
            {
              "type": "null"
            }
          ]
        },
        "event_id": {
          "type": "string"
        },
        "job_id": {
          "anyOf": [
            {
              "$ref": "#/$defs/StreamEvent_JobId"
            },
            {
              "type": "null"
            }
          ]
        },
        "kind": {
          "$ref": "#/$defs/StreamEvent_StreamKind"
        },
        "request_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "sequence": {
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "timestamp": {
          "type": "string"
        },
        "warning": {
          "anyOf": [
            {
              "$ref": "#/$defs/StreamEvent_SourceWarning"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "event_id",
        "kind",
        "sequence",
        "timestamp"
      ],
      "title": "StreamEvent",
      "type": "object"
    },
    "StreamEvent_ApiError": {
      "description": "The shared, transport-neutral error shape.\n\nEvery crate reports failures as an `ApiError` so CLI, REST, MCP, jobs, logs,\nand progress streams render one consistent structure.",
      "properties": {
        "chunk_id": {
          "description": "Chunk id.",
          "type": [
            "string",
            "null"
          ]
        },
        "code": {
          "$ref": "#/$defs/StreamEvent_ErrorCode",
          "description": "Stable machine code (e.g. `provider.unavailable`)."
        },
        "cooldown_until": {
          "description": "Provider/job cooling timestamp.",
          "format": "date-time",
          "type": [
            "string",
            "null"
          ]
        },
        "details": {
          "additionalProperties": {
            "type": "string"
          },
          "description": "Redacted structured context (safe key/value pairs only).",
          "type": "object"
        },
        "document_id": {
          "description": "Document id.",
          "type": [
            "string",
            "null"
          ]
        },
        "job_id": {
          "description": "Job correlation id.",
          "type": [
            "string",
            "null"
          ]
        },
        "message": {
          "description": "Redacted human-readable message.",
          "type": "string"
        },
        "provider_id": {
          "description": "Provider that failed.",
          "type": [
            "string",
            "null"
          ]
        },
        "retry_after_ms": {
          "description": "Suggested retry delay, in milliseconds.",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "retryable": {
          "description": "Whether retry may succeed.",
          "type": "boolean"
        },
        "severity": {
          "$ref": "#/$defs/StreamEvent_ErrorSeverity",
          "description": "Severity classification."
        },
        "source_id": {
          "description": "Source id.",
          "type": [
            "string",
            "null"
          ]
        },
        "source_item_key": {
          "description": "Item/file/page key.",
          "type": [
            "string",
            "null"
          ]
        },
        "stage": {
          "$ref": "#/$defs/StreamEvent_ErrorStage",
          "description": "Pipeline/transport stage."
        },
        "visibility": {
          "$ref": "#/$defs/StreamEvent_ErrorVisibility",
          "description": "Where this error may be surfaced."
        }
      },
      "required": [
        "code",
        "message",
        "stage",
        "retryable",
        "severity",
        "visibility",
        "details"
      ],
      "type": "object"
    },
    "StreamEvent_ErrorCode": {
      "description": "A stable, machine-readable error code (e.g. `provider.unavailable`).",
      "type": "string"
    },
    "StreamEvent_ErrorSeverity": {
      "description": "How severe an error is and whether it terminates the item/job.",
      "oneOf": [
        {
          "const": "info",
          "description": "Informational event; not terminal.",
          "type": "string"
        },
        {
          "const": "warning",
          "description": "Non-fatal issue, full behavior preserved; not terminal.",
          "type": "string"
        },
        {
          "const": "degraded",
          "description": "Behavior reduced but acceptable by policy; may or may not be terminal.",
          "type": "string"
        },
        {
          "const": "failed",
          "description": "Required work failed; terminal for the affected item/job.",
          "type": "string"
        },
        {
          "const": "fatal",
          "description": "Cannot continue safely; terminal.",
          "type": "string"
        }
      ]
    },
    "StreamEvent_ErrorStage": {
      "description": "Pipeline/transport stage an error is attributed to.",
      "oneOf": [
        {
          "const": "parsing",
          "description": "CLI/MCP/REST request parse, removed command/action.",
          "type": "string"
        },
        {
          "const": "validation",
          "description": "Missing fields, bad types, unsupported flags.",
          "type": "string"
        },
        {
          "const": "resolving",
          "description": "Source resolution, canonical URI, authority.",
          "type": "string"
        },
        {
          "const": "routing",
          "description": "Adapter/scope/provider selection.",
          "type": "string"
        },
        {
          "const": "authorizing",
          "description": "Auth, credentials, execution policy.",
          "type": "string"
        },
        {
          "const": "planning",
          "description": "Source plan, prune plan.",
          "type": "string"
        },
        {
          "const": "leasing",
          "description": "Job/watch/source lease.",
          "type": "string"
        },
        {
          "const": "discovering",
          "description": "Manifest/map discovery.",
          "type": "string"
        },
        {
          "const": "diffing",
          "description": "Manifest diff.",
          "type": "string"
        },
        {
          "const": "fetching",
          "description": "HTTP/git/package/local/MCP/CLI fetch.",
          "type": "string"
        },
        {
          "const": "rendering",
          "description": "Browser/CDP/render provider.",
          "type": "string"
        },
        {
          "const": "enriching",
          "description": "Enrichment (metadata/classification/summary/extraction/authority).",
          "type": "string"
        },
        {
          "const": "normalizing",
          "description": "SourceDocument creation.",
          "type": "string"
        },
        {
          "const": "parsing_content",
          "description": "Parser facts/chunk parser (serialized as `parsing_content`).",
          "type": "string"
        },
        {
          "const": "graphing",
          "description": "Graph writes/merge/conflict.",
          "type": "string"
        },
        {
          "const": "preparing",
          "description": "Chunking/PreparedDocument.",
          "type": "string"
        },
        {
          "const": "batching",
          "description": "Batch assembly for embedding/vectorizing.",
          "type": "string"
        },
        {
          "const": "embedding",
          "description": "Embedding provider/batch.",
          "type": "string"
        },
        {
          "const": "vectorizing",
          "description": "Vector point construction/payload build.",
          "type": "string"
        },
        {
          "const": "upserting",
          "description": "VectorStore writes.",
          "type": "string"
        },
        {
          "const": "publishing",
          "description": "Generation publish.",
          "type": "string"
        },
        {
          "const": "cleaning",
          "description": "Cleanup/prune/dedupe.",
          "type": "string"
        },
        {
          "const": "retrieving",
          "description": "Query/retrieve context.",
          "type": "string"
        },
        {
          "const": "synthesizing",
          "description": "LLM synthesis.",
          "type": "string"
        },
        {
          "const": "evaluating",
          "description": "RAG/evaluation scoring.",
          "type": "string"
        },
        {
          "const": "observing",
          "description": "Progress/log/status emit.",
          "type": "string"
        },
        {
          "const": "storage",
          "description": "Storage boundary (ledger/artifact/job store), phase-contextual.",
          "type": "string"
        },
        {
          "const": "provider",
          "description": "Provider boundary (embedding/llm/render/search), phase-contextual.",
          "type": "string"
        },
        {
          "const": "transport",
          "description": "Transport boundary (CLI/REST/MCP dispatch), phase-contextual.",
          "type": "string"
        },
        {
          "const": "internal",
          "description": "Internal/unclassified failure within the active operation phase.",
          "type": "string"
        }
      ]
    },
    "StreamEvent_ErrorVisibility": {
      "description": "Where a context entry (or error) may be surfaced.\n\nFrom the \"visibility\" field in the error shape: `public`, `internal`,\n`sensitive`.",
      "oneOf": [
        {
          "const": "public",
          "description": "Safe to render to any caller, including remote/unauthenticated.",
          "type": "string"
        },
        {
          "const": "internal",
          "description": "Internal diagnostics; render only to internal/admin surfaces.",
          "type": "string"
        },
        {
          "const": "sensitive",
          "description": "Sensitive/secret-adjacent; never render raw, redaction required.",
          "type": "string"
        }
      ]
    },
    "StreamEvent_JobId": {
      "format": "uuid",
      "type": "string"
    },
    "StreamEvent_Severity": {
      "enum": [
        "debug",
        "info",
        "warning",
        "degraded",
        "failed",
        "fatal"
      ],
      "type": "string"
    },
    "StreamEvent_SourceItemKey": {
      "type": "string"
    },
    "StreamEvent_SourceWarning": {
      "additionalProperties": false,
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        },
        "severity": {
          "$ref": "#/$defs/StreamEvent_Severity"
        },
        "source_item_key": {
          "anyOf": [
            {
              "$ref": "#/$defs/StreamEvent_SourceItemKey"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "code",
        "severity",
        "message",
        "retryable"
      ],
      "type": "object"
    },
    "StreamEvent_StreamKind": {
      "description": "`StreamEvent.kind` — the flat set of streaming event kinds shared by SSE\nand MCP streaming, per `docs/pipeline-unification/schemas/event-schema.md`\n(\"StreamEvent Shape\").",
      "enum": [
        "progress",
        "token",
        "citation",
        "artifact",
        "warning",
        "error",
        "final"
      ],
      "type": "string"
    },
    "enums": {
      "ArtifactKind": {
        "enum": [
          "raw_content",
          "normalized_content",
          "manifest",
          "report",
          "screenshot",
          "warc",
          "provider_trace"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "ArtifactKind"
        }
      },
      "ArtifactMode": {
        "enum": [
          "none",
          "on_large_output",
          "always"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "ArtifactMode"
        }
      },
      "AuthorityLevel": {
        "enum": [
          "official",
          "verified",
          "user_pinned",
          "inferred",
          "community",
          "mirror",
          "conflicting",
          "unknown"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "AuthorityLevel"
        }
      },
      "CachePolicy": {
        "enum": [
          "bypass",
          "use",
          "revalidate",
          "offline"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "CachePolicy"
        }
      },
      "ChunkProfile": {
        "enum": [
          "code_symbol",
          "code_manifest",
          "markdown_sections",
          "html_article",
          "plain_text_windows",
          "transcript_segments",
          "structured_records",
          "api_schema",
          "tool_output",
          "session_turns",
          "atomic_metadata"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "ChunkProfile"
        }
      },
      "CleanupDebtKind": {
        "enum": [
          "vector_delete",
          "artifact_delete",
          "ledger_prune",
          "graph_prune",
          "memory_prune",
          "job_retention",
          "cache_prune",
          "adapter_release"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "CleanupDebtKind"
        }
      },
      "ContentKind": {
        "enum": [
          "code",
          "markdown",
          "html",
          "plain_text",
          "transcript",
          "structured",
          "json",
          "yaml",
          "toml",
          "xml",
          "binary_metadata"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "ContentKind"
        }
      },
      "CredentialKind": {
        "enum": [
          "api_key",
          "o_auth_token",
          "bearer_token",
          "basic_auth",
          "cookie",
          "ssh_key",
          "local_config"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "CredentialKind"
        }
      },
      "DiffKind": {
        "enum": [
          "added",
          "modified",
          "removed",
          "unchanged",
          "skipped",
          "failed"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "DiffKind"
        }
      },
      "DocumentLifecycleStatus": {
        "enum": [
          "discovered",
          "fetched",
          "normalized",
          "enriched",
          "parsed",
          "prepared",
          "embedded",
          "vectorized",
          "published",
          "cleaned",
          "degraded",
          "failed",
          "skipped"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "DocumentLifecycleStatus"
        }
      },
      "EnrichmentKind": {
        "enum": [
          "none",
          "metadata",
          "classification",
          "summary",
          "extraction",
          "authority",
          "dependency",
          "api_schema",
          "tool_schema",
          "session",
          "custom"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "EnrichmentKind"
        }
      },
      "ExecutionAffinity": {
        "enum": [
          "inline",
          "worker",
          "scheduler",
          "provider_bound"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "ExecutionAffinity"
        }
      },
      "ExecutionMode": {
        "enum": [
          "foreground",
          "background",
          "wait"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "ExecutionMode"
        }
      },
      "HealthStatus": {
        "enum": [
          "healthy",
          "degraded",
          "unavailable",
          "cooling",
          "unknown"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "HealthStatus"
        }
      },
      "ItemKind": {
        "enum": [
          "web_page",
          "repo_file",
          "local_file",
          "package_version",
          "feed_entry",
          "transcript",
          "session_turn",
          "tool_call",
          "cli_output",
          "mcp_tool_output",
          "memory_record",
          "artifact"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "ItemKind"
        }
      },
      "JobKind": {
        "enum": [
          "source",
          "watch",
          "map",
          "extract",
          "research",
          "ask",
          "query",
          "retrieve",
          "memory",
          "graph",
          "prune",
          "provider_probe",
          "reset"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "JobKind"
        }
      },
      "JobPriority": {
        "enum": [
          "interactive",
          "high",
          "normal",
          "background",
          "maintenance"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "JobPriority"
        }
      },
      "LifecycleStatus": {
        "enum": [
          "queued",
          "pending",
          "running",
          "waiting",
          "blocked",
          "canceling",
          "completed",
          "completed_degraded",
          "failed",
          "canceled",
          "expired",
          "skipped"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "LifecycleStatus"
        }
      },
      "PipelinePhase": {
        "enum": [
          "queued",
          "requested",
          "resolving",
          "routing",
          "authorizing",
          "planning",
          "leasing",
          "discovering",
          "diffing",
          "fetching",
          "rendering",
          "enriching",
          "normalizing",
          "parsing",
          "graphing",
          "preparing",
          "batching",
          "embedding",
          "vectorizing",
          "upserting",
          "retrieving",
          "synthesizing",
          "evaluating",
          "publishing",
          "cleaning",
          "complete",
          "canceled"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "PipelinePhase"
        }
      },
      "ProviderKind": {
        "enum": [
          "llm",
          "embedding",
          "vector",
          "search",
          "fetch",
          "render",
          "parser",
          "network_capture",
          "artifact",
          "ledger",
          "graph",
          "memory",
          "job",
          "watch",
          "config",
          "credential",
          "cache",
          "security",
          "rate_limiter",
          "health_probe"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "ProviderKind"
        }
      },
      "PublishState": {
        "enum": [
          "planning",
          "writing",
          "publishing",
          "committed",
          "cleanup_pending",
          "cleaning",
          "cleaned"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "PublishState"
        }
      },
      "ResponseMode": {
        "enum": [
          "auto",
          "summary",
          "full",
          "inline",
          "artifact",
          "path",
          "job_only"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "ResponseMode"
        }
      },
      "SafetyClass": {
        "enum": [
          "public_network",
          "authenticated_network",
          "local_filesystem",
          "tool_execution"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "SafetyClass"
        }
      },
      "Severity": {
        "enum": [
          "debug",
          "info",
          "warning",
          "degraded",
          "failed",
          "fatal"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "Severity"
        }
      },
      "SourceIntent": {
        "enum": [
          "acquire",
          "refresh",
          "watch",
          "map"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "SourceIntent"
        }
      },
      "SourceKind": {
        "enum": [
          "web",
          "local",
          "git",
          "registry",
          "feed",
          "reddit",
          "youtube",
          "session",
          "cli_tool",
          "mcp_tool",
          "memory",
          "upload"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "SourceKind"
        }
      },
      "SourceRefreshPolicy": {
        "enum": [
          "if_stale",
          "force",
          "never"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "SourceRefreshPolicy"
        }
      },
      "SourceScope": {
        "enum": [
          "page",
          "site",
          "docs",
          "repo",
          "workspace",
          "branch",
          "org",
          "package",
          "version",
          "feed",
          "subreddit",
          "thread",
          "comment",
          "video",
          "playlist",
          "channel",
          "issue",
          "pull_request",
          "merge_request",
          "release",
          "wiki",
          "file",
          "directory",
          "map",
          "tool",
          "script",
          "api"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "SourceScope"
        }
      },
      "SourceWatchPolicy": {
        "enum": [
          "disabled",
          "ensure",
          "enabled"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "SourceWatchPolicy"
        }
      },
      "Visibility": {
        "enum": [
          "public",
          "internal",
          "sensitive",
          "redacted",
          "derived"
        ],
        "type": "string",
        "x-axon": {
          "owner_crate": "axon-api",
          "rust_enum": "Visibility"
        }
      }
    }
  },
  "$id": "https://axon.local/schemas/runtime/events.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "description": "Generated Axon schema contract artifact.",
  "title": "AxonEventSchema",
  "type": "object",
  "x-axon": {
    "clean_break": true,
    "contract_version": "2026-06-30",
    "generated_by": "cargo xtask schemas events",
    "owner_crates": [
      "axon-observe"
    ],
    "source_inputs": [
      {
        "checksum": "sha256:0431ae0e49e02633f95b0abbe54dcf0b20b5a4367e0fd4ca2dc1cf3ce3a06342",
        "kind": "rust_module",
        "path": "crates/axon-observe/src/metric.rs"
      },
      {
        "checksum": "sha256:bdd484ac24fd7b662c75b8917981f8a6ebfe07b5dc59e7f4c518be69de22c046",
        "kind": "rust_module",
        "path": "crates/axon-observe/src/schema_registry.rs"
      },
      {
        "checksum": "sha256:11698f7a5004224ceac5d1697af2f880ab9676cfa89e2e25a4cfd2f2308b7596",
        "kind": "markdown_contract",
        "path": "docs/pipeline-unification/schemas/event-schema.md"
      }
    ]
  }
}