{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "SurfaceManifest",
"type": "object",
"properties": {
"type": {
"type": "string"
},
"version": {
"type": "string"
},
"integration": {
"type": "string"
},
"tools": {
"type": "array",
"items": {
"$ref": "#/$defs/ToolSurface"
}
},
"exit_codes": {
"description": "Every process exit status this build can return, with its machine\ncode, recovery class and provenance. Derived from the error enum\n(B3) so the list cannot drift from the code that produces it.",
"type": "array",
"items": {
"$ref": "#/$defs/ExitCodeEntry"
}
},
"flag_contract": {
"description": "Flag semantics that are contract rather than prose: what each flag\nmeans and which combinations the CLI rejects.",
"type": "array",
"items": {
"$ref": "#/$defs/FlagContractEntry"
}
},
"discovery": {
"description": "How to discover the schema surface without parsing help text.",
"$ref": "#/$defs/DiscoveryEntry"
},
"notes": {
"type": "array",
"items": {
"type": "string"
}
},
"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 target the run resolved, or `-` for standard input; several subjects are joined with `,` in invocation order",
"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": {
"description": "The record itself was cut by `--truncate-content` or `--max-output-bytes`, so the fields are shorter than the source",
"type": "boolean"
},
"truncated_records": {
"description": "Records the writer cut this run, counted once per record",
"type": "integer",
"minimum": 0
}
},
"required": [
"type",
"version",
"integration",
"tools",
"exit_codes",
"flag_contract",
"discovery",
"notes"
],
"$defs": {
"ToolSurface": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"name": {
"type": "string"
},
"summary": {
"type": "string"
},
"schema_hint": {
"type": "string"
},
"available": {
"description": "Whether the tool is usable in this build (A-009).",
"type": "boolean"
},
"install_hint": {
"description": "Optional rebuild / install hint when `available` is false.",
"type": [
"string",
"null"
]
},
"stdout_kind": {
"description": "stdout contract for this tool (A-011).",
"type": "string"
}
},
"required": [
"type",
"name",
"summary",
"schema_hint",
"available",
"stdout_kind"
]
},
"ExitCodeEntry": {
"description": "One exit status of the process, derived from an error variant.",
"type": "object",
"properties": {
"code": {
"description": "Numeric status the process returns to the shell.",
"type": "integer",
"format": "uint8",
"minimum": 0,
"maximum": 255
},
"name": {
"description": "Machine-readable error code, or the process-level label.",
"type": "string"
},
"error_class": {
"description": "Recovery class: `transient`, `conflict`, `precondition_failed`\nor `permanent`.",
"type": "string"
},
"retryable": {
"description": "Whether retrying the same operation may succeed.",
"type": "boolean"
},
"source": {
"description": "Provenance: `error-variant` (derived from the error enum) or\n`process` (status produced by the runtime, not by an error variant).",
"type": "string"
}
},
"required": [
"code",
"name",
"error_class",
"retryable",
"source"
]
},
"FlagContractEntry": {
"description": "One flag whose semantics are part of the agent contract.",
"type": "object",
"properties": {
"flag": {
"description": "Flag name as accepted on the command line.",
"type": "string"
},
"semantics": {
"description": "What the flag means, including the combinations the CLI rejects.",
"type": "string"
}
},
"required": [
"flag",
"semantics"
]
},
"DiscoveryEntry": {
"description": "The schema-discovery door, published so an agent can find it by field.\n\nWithout this, discovering that a schema dump exists at all meant reading\n`--help` prose and hoping the wording survived a release. The names come from\n[`crate::SCHEMA_NAMES`], the same list the dispatcher serves, so the count\nhere cannot drift from what `--print-schema` actually answers.",
"type": "object",
"properties": {
"flag": {
"description": "Global flag that answers both forms.",
"type": "string"
},
"list_form": {
"description": "What the no-argument form emits.",
"type": "string"
},
"name_form": {
"description": "What the name-argument form emits.",
"type": "string"
},
"schema_names": {
"description": "Every schema name this build serves, alphabetically ordered.",
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"flag",
"list_form",
"name_form",
"schema_names"
]
}
}
}