{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "ReadOutput",
"description": "NDJSON output for read operations with metadata and optional content.",
"type": "object",
"properties": {
"type": {
"description": "Event type discriminator.",
"type": "string"
},
"path": {
"description": "Absolute path of the file.",
"type": "string"
},
"content": {
"description": "File content, omitted in stat-only mode or for binary files.",
"type": [
"string",
"null"
]
},
"lines": {
"description": "Number of lines in the returned content.\n\nAs of v0.1.20 (GAP-2026-008), this is the FILTERED count when a partial\nread filter (`--head`, `--tail`, `--line`, `--lines`, `--grep`) is\nin effect. The original file total is preserved in `lines_total`.",
"type": "integer",
"format": "uint64",
"minimum": 0
},
"lines_total": {
"description": "Total lines in the original file before any filter (GAP-2026-008).\nOmitted when no filter is applied or the filter did not change the\nline count.",
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0
},
"truncated": {
"description": "Whether the byte ceiling cut the content (v0.1.39).\n\nAbsent when nothing was cut, so a full read keeps its old shape.",
"type": [
"boolean",
"null"
]
},
"next": {
"description": "Ready-made command that reads the rest, when the ceiling cut content.",
"type": [
"string",
"null"
]
},
"bytes": {
"description": "File size in bytes.",
"type": "integer",
"format": "uint64",
"minimum": 0
},
"checksum": {
"description": "BLAKE3 checksum of the file contents.",
"type": "string"
},
"permissions": {
"description": "Filesystem permissions string.",
"type": "string"
},
"modified": {
"description": "Last modification timestamp.",
"type": "string"
},
"kind": {
"description": "File kind (file, directory, symlink).",
"type": "string"
},
"binary": {
"description": "Whether the file was detected as binary.",
"type": "boolean"
},
"range": {
"description": "Line range returned when a subset was requested.",
"anyOf": [
{
"$ref": "#/$defs/LineRange"
},
{
"type": "null"
}
]
},
"verified": {
"description": "Checksum verification result, if --verify-checksum was used.",
"type": [
"boolean",
"null"
]
},
"mode": {
"description": "Read mode discriminator (GAP-2026-009): \"full\" | \"head\" | \"tail\" |\n\"line\" | \"lines\" | \"grep\" | \"stat\" | \"raw\". Allows downstream consumers to\ndistinguish partial reads from full reads without parsing content.",
"type": "string"
},
"media": {
"description": "What the media channel measured, for a picture or a PDF.",
"anyOf": [
{
"$ref": "#/$defs/MediaInfo"
},
{
"type": "null"
}
]
},
"ok": {
"description": "Outcome of the run, stamped by the writer",
"type": "boolean"
},
"code": {
"description": "Machine error code, present when ok is false",
"type": "string"
},
"exit": {
"description": "Process exit status, present when ok is false",
"type": "integer",
"minimum": 0
},
"target_resolved": {
"description": "Absolute targets the run resolved, in invocation order, and never a joined string, so a path holding `,` stays readable; a run with one target publishes a one-item array, so the shape never depends on the count",
"type": "array",
"items": {
"type": "string"
}
},
"target_source": {
"description": "Where the target came from: named in the invocation line, inherited from the workspace slot, or the standard-input stream",
"type": "string",
"enum": [
"argv",
"workspace",
"stdin"
]
},
"workspace_source": {
"description": "Where the workspace root came from: the `--workspace` flag or the process working directory",
"type": "string",
"enum": [
"argv",
"cwd"
]
},
"records_suppressed": {
"description": "Records the writer dropped before the terminal event: `--filter` rejections, `--select` projections that emptied the record, dedupe duplicates and `--limit` cuts. It counts records, never files, so it does not compare with `files_matched`: one file can contribute several records",
"type": "integer",
"minimum": 0
},
"files_budget_dropped": {
"description": "Entries the `--limit` budget dropped, in the unit the verb produces: files for walking verbs, records for streaming ones; a floor, because workers may stop before producing the rest",
"type": "integer",
"minimum": 0
},
"files_planned": {
"description": "Files the run would have modified in `--dry-run` or `--preview`; absent from a run that really wrote",
"type": "integer",
"minimum": 0
},
"truncated_records": {
"description": "Records the writer cut this run, counted once per record",
"type": "integer",
"minimum": 0
}
},
"required": [
"type",
"path",
"lines",
"bytes",
"checksum",
"permissions",
"modified",
"kind",
"binary",
"mode"
],
"$defs": {
"LineRange": {
"description": "Inclusive 1-based line range for partial file reads.",
"type": "object",
"properties": {
"start": {
"description": "First line number returned (1-based).",
"type": "integer",
"format": "uint",
"minimum": 0
},
"end": {
"description": "Last line number returned (1-based).",
"type": "integer",
"format": "uint",
"minimum": 0
}
},
"required": [
"start",
"end"
]
},
"MediaInfo": {
"description": "Facts about a picture or a PDF page set, measured before delivery.",
"type": "object",
"properties": {
"kind": {
"description": "Media family: `image` or `pdf`.",
"type": "string"
},
"width": {
"description": "Picture width after orientation, absent for a PDF.",
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0
},
"height": {
"description": "Picture height after orientation, absent for a PDF.",
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0
},
"format": {
"description": "Format named by the magic bytes, or `pdf`.",
"type": [
"string",
"null"
]
},
"visual_tokens": {
"description": "Visual tokens the delivered picture costs.",
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0
},
"frames": {
"description": "Frames of an animated GIF.",
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0
},
"orientation": {
"description": "EXIF orientation that was applied.",
"type": [
"integer",
"null"
],
"format": "uint16",
"minimum": 0,
"maximum": 65535
},
"pages": {
"description": "Pages whose text was returned.",
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "uint32",
"minimum": 0
}
},
"needs_vision": {
"description": "Pages that carry no text and therefore need the drawn page.",
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "uint32",
"minimum": 0
}
}
},
"required": [
"kind"
]
}
}
}