{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://example.com/pipeline/bulk-read-output.schema.json",
  "title": "Bulk Read Output",
  "description": "Schema for the bulk-reader worker's answer. Source: pipeline/agents/bulk-reader.md, invoked by pipeline/scripts/bulk-read.sh when check-read-size.sh blocks a whole-file read. Every positional field is a LINE NUMBER in the file as given to the worker, because a summary the caller cannot open is a summary the caller will pay to replace.",
  "type": "object",
  "additionalProperties": false,
  "required": ["summary"],
  "properties": {
    "answer": {
      "type": "string",
      "description": "Direct answer to the question the caller asked, or a plain statement that this file cannot answer it. Never a guess  -  an unanswerable question is reported, not filled in."
    },
    "summary": {
      "type": "string",
      "description": "What the file is and does, 3-6 sentences. Descriptive only: no review, no judgement, no proposed change."
    },
    "symbols": {
      "type": "array",
      "description": "Top-level declarations the file contains, in file order.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["name", "line"],
        "properties": {
          "name": { "type": "string" },
          "kind": { "type": "string", "enum": ["type", "func", "var", "extension", "other"] },
          "line": { "type": "integer", "minimum": 1 }
        }
      }
    },
    "regions": {
      "type": "array",
      "maxItems": 8,
      "description": "Spans worth opening next, most important first. The intended use is a bounded Read(offset:limit:) over one of these, which is both cheaper than the whole file and exact  -  and which the read gate allows through.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["start", "end"],
        "properties": {
          "why": { "type": "string", "description": "What a reader finds in this span." },
          "start": { "type": "integer", "minimum": 1 },
          "end": { "type": "integer", "minimum": 1 }
        }
      }
    },
    "truncated": {
      "type": "boolean",
      "description": "True when the worker did not see the whole file. A partial read summarized as a whole one is the failure this flag exists to make visible."
    }
  }
}