[{"k":"h","depth":1,"text":"16 · Projections","id":"16--projections"},{"k":"quote","inline":[{"k":"text","text":"The first fifteen chapters define what a workflow "},{"k":"em","text":"is"},{"k":"text","text":" and what a run\n"},{"k":"em","text":"proves"},{"k":"text","text":". This chapter defines what a tool "},{"k":"em","text":"sees"},{"k":"text","text":": the "},{"k":"strong","text":"oracle\nsurface"},{"k":"text","text":" — the single, versioned, read-only projection of a workflow\nthat the CLI, the language server, and the MCP tool all serve "},{"k":"strong","text":"byte\nfor byte the same"},{"k":"text","text":". One truth, many lenses."},{"k":"text","text":"This is the first chapter of the post-1.0, additive arc. Everything it\nadds is a "},{"k":"strong","text":"projection over the frozen `nika: v1` IR"},{"k":"text","text":" — never a change\nto the language. A projection is a "},{"k":"em","text":"view"},{"k":"text","text":"; the thing viewed does not\nmove."}]},{"k":"hr"},{"k":"h","depth":2,"text":"The one projection (normative)","id":"the-one-projection-normative"},{"k":"p","inline":[{"k":"text","text":"There is "},{"k":"strong","text":"one canonical projection"},{"k":"text","text":" of a workflow — the graph of\n"},{"k":"link","text":"03","href":"./03-dag.md"},{"k":"text","text":" ("},{"k":"code","text":"graph_format: 2"},{"k":"text","text":") — and every surface serves "},{"k":"em","text":"that same\nprojection"},{"k":"text","text":". "},{"k":"code","text":"nika inspect --format json"},{"k":"text","text":" (CLI), "},{"k":"code","text":"nika/semanticDocument"},{"k":"text","text":"\n(LSP), and the "},{"k":"code","text":"nika_inspect"},{"k":"text","text":" MCP tool all carry the "},{"k":"strong","text":"byte-identical"},{"k":"text","text":"\ncanonical projection; the surfaces differ only in what presentation they\nwrap around it."}]},{"k":"p","inline":[{"k":"text","text":"A "},{"k":"strong","text":"semantic document"},{"k":"text","text":" is the LSP-side surface: the canonical projection\n"},{"k":"em","text":"verbatim"},{"k":"text","text":", plus the source spans a client needs to link graph nodes back\nto text, plus — when the graph cannot be built — the one-word reason why.\nIt is a "},{"k":"strong","text":"superset"},{"k":"text","text":" of the bare projection (the CLI and MCP serve the\nprojection without editor spans), and it is the "},{"k":"strong","text":"growth point"},{"k":"text","text":" of the\noracle: holes, actions, and capabilities land here (§the additive arc),\nwhich is why it carries its own version."}]},{"k":"code","lang":"text","text":"semantic_document = (\n  semantic_document_format   # the surface's OWN version (this chapter)\n  graph?                     # the canonical projection (03 · graph_format: 2) · absent when unbuildable\n  reason?                    # WHY graph is absent · one word · closed vocabulary · omitted when graph is present\n  spans                      # task id → the range of its declaring `id` token\n)"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"`semantic_document_format: 1`"},{"k":"text","text":" — the surface names its "},{"k":"strong","text":"own"},{"k":"text","text":"\nversion, independent of the nested "},{"k":"code","text":"graph.graph_format"},{"k":"text","text":". Until now the\ndocument versioned itself "},{"k":"em","text":"implicitly"},{"k":"text","text":" through "},{"k":"code","text":"graph.graph_format: 2"},{"k":"text","text":";\na projection that will grow additive fields (holes · actions ·\ncapabilities · §the additive arc) needs a version of its own so a\nconsumer can reason about the "},{"k":"em","text":"surface"},{"k":"text","text":" without unwrapping the graph."}],[{"k":"strong","text":"`graph`"},{"k":"text","text":" is the canonical projection of "},{"k":"link","text":"03","href":"./03-dag.md"},{"k":"text","text":" "},{"k":"em","text":"verbatim"},{"k":"text","text":"\n("},{"k":"code","text":"graph_format: 2"},{"k":"text","text":" · the derived edges · the reference identity). The\nsemantic document never re-derives it — it carries it."}],[{"k":"strong","text":"`spans`"},{"k":"text","text":" map each task id to the LSP range of its declaring "},{"k":"code","text":"id"},{"k":"text","text":"\ntoken, so a canvas or a lens links a node back to source without\nre-scanning YAML."}]]},{"k":"h","depth":2,"text":"`reason` · *why the graph is absent (normative · closed)*","id":"reason--why-the-graph-is-absent-normative--closed"},{"k":"p","inline":[{"k":"text","text":"When the graph cannot be projected, "},{"k":"code","text":"graph"},{"k":"text","text":" is null and "},{"k":"code","text":"reason"},{"k":"text","text":" names\nwhy in "},{"k":"strong","text":"one word"},{"k":"text","text":", from a closed vocabulary — never a sentence, never a\nduplicate of a diagnostic (the details live in the diagnostics lane, "},{"k":"link","text":"05","href":"./05-errors.md"},{"k":"text","text":"):"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"`reason` · Meaning"}],[{"k":"text","text":"`parse` · the source did not parse — there is no tree to project"}],[{"k":"text","text":"`findings` · the source parsed but a check finding blocks a sound graph"}]]},{"k":"p","inline":[{"k":"text","text":"The set is "},{"k":"strong","text":"closed"},{"k":"text","text":": a new reason is an additive change that bumps\n"},{"k":"code","text":"semantic_document_format"},{"k":"text","text":". "},{"k":"code","text":"reason"},{"k":"text","text":" is omitted entirely when "},{"k":"code","text":"graph"},{"k":"text","text":" is\npresent (a healthy document carries no reason key) — presence is the\nsignal, not a sentinel value."}]},{"k":"h","depth":2,"text":"The triangle law (normative)","id":"the-triangle-law-normative"},{"k":"p","inline":[{"k":"text","text":"The "},{"k":"strong","text":"canonical projection"},{"k":"text","text":" has "},{"k":"strong","text":"exactly one producer"},{"k":"text","text":" and is served,\nbyte-identical, by three surfaces:"}]},{"k":"code","lang":"text","text":"nika inspect --format json     ┐  the canonical projection (graph_format: 2)\nnika/semanticDocument (LSP)     ├─ byte-identical · one projection, three lenses\nnika_inspect (MCP)              ┘  (the LSP additionally wraps editor spans)"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"The three MUST serve the "},{"k":"strong","text":"same canonical-projection bytes"},{"k":"text","text":" for the\nsame input — a lens that drifts is a bug, tested by parity, not by\nconvention. The LSP's semantic document carries that same projection\n"},{"k":"em","text":"verbatim"},{"k":"text","text":" and adds spans (a presentation superset, not a re-derivation);\nthe CLI and MCP serve the projection without editor spans."}],[{"k":"text","text":"Each surface is a "},{"k":"strong","text":"typed contract"},{"k":"text","text":", not a JSON bag: renaming a field\nbreaks the producer's compilation (and the law tests) before it can\nbreak a consumer silently."}]]},{"k":"h","depth":2,"text":"Read discipline (normative)","id":"read-discipline-normative"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"A projection always answers."},{"k":"text","text":" The request is a "},{"k":"em","text":"read"},{"k":"text","text":", never a\njudgment. A malformed document still returns a semantic document — with\na "},{"k":"code","text":"reason"},{"k":"text","text":" and whatever spans it could recover — never an error. Judgment\nlives in "},{"k":"code","text":"nika check"},{"k":"text","text":" (05), never in the projection."}],[{"k":"strong","text":"Structure only."},{"k":"text","text":" The projection carries names, shapes, spans, and\nderived structure — "},{"k":"strong","text":"never"},{"k":"text","text":" a "},{"k":"code","text":"config"},{"k":"text","text":" value, a secret, or resolved\nmaterial ("},{"k":"link","text":"10","href":"./10-authority.md"},{"k":"text","text":" flow laws hold here too). A projection\nthat leaked a secret would be a sink; it is not one, by construction."}],[{"k":"strong","text":"A projection is a view over the frozen IR."},{"k":"text","text":" It never mutates, never\nre-orders, never re-interprets the workflow. Given the same source it is\ndeterministic — the same bytes, every time."}]]},{"k":"h","depth":2,"text":"The additive arc (normative · forward-compat)","id":"the-additive-arc-normative--forward-compat"},{"k":"p","inline":[{"k":"text","text":"This surface is the plug-board for the post-1.0 oracle work. Every future\nfield is "},{"k":"strong","text":"additive under the version key"},{"k":"text","text":", and every future field is a\n"},{"k":"strong","text":"projection or an edit-proposal over the frozen v1 IR"},{"k":"text","text":" — never a new\npiece of the language:"}]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Additive-field discipline."},{"k":"text","text":" A new optional field (holes · actions ·\ncapabilities) bumps "},{"k":"code","text":"semantic_document_format"},{"k":"text","text":" and is "},{"k":"code","text":"skip"},{"k":"text","text":"-omitted when\nempty. A consumer that ignores an additive field still reads the whole\nolder surface correctly — the same forward-compat the "},{"k":"code","text":"graph_format: 2"},{"k":"text","text":"\nenvelope already keeps (03). A consumer MUST ignore fields it does not\nknow, never fail on them."}],[{"k":"strong","text":"Capabilities are negotiated, not assumed."},{"k":"text","text":" A client announces which\nextensions it understands under "},{"k":"code","text":"experimental.nika.*"},{"k":"text","text":"; the server offers\nan extension only when the client asked. An un-negotiated field is never\nsent."}],[{"k":"strong","text":"Projection, never grammar."},{"k":"text","text":" No field on this surface adds syntax a\nworkflow author writes. Holes describe "},{"k":"em","text":"where a workflow is incomplete"},{"k":"text","text":";\nactions describe "},{"k":"em","text":"an edit a tool could apply"},{"k":"text","text":"; both are computed "},{"k":"strong","text":"from"},{"k":"text","text":"\nthe v1 IR and validated "},{"k":"strong","text":"against"},{"k":"text","text":" it. The language stays frozen (the\n1.0 contract) while the oracle around it grows."}]]},{"k":"h","depth":2,"text":"What v1 deliberately does not do (yet)","id":"what-v1-deliberately-does-not-do-yet"},{"k":"p","inline":[{"k":"text","text":"The following are "},{"k":"strong","text":"named"},{"k":"text","text":" here so the surface reserves room for them,\nand "},{"k":"strong","text":"specified in their own later windows"},{"k":"text","text":" — not shipped by this chapter:"}]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"`holes`"},{"k":"text","text":" — typed descriptions of where a workflow is incomplete (a\nmissing "},{"k":"code","text":"prompt:"},{"k":"text","text":", an unfilled output), each anchored to a span,\nincluding spans for "},{"k":"strong","text":"absent"},{"k":"text","text":" fields. ("},{"k":"code","text":"nika/holes"},{"k":"text","text":" · "},{"k":"code","text":"nika/fillHole"},{"k":"text","text":".)"}],[{"k":"strong","text":"`actions`"},{"k":"text","text":" — "},{"k":"code","text":"SemanticAction"},{"k":"text","text":"s: edit proposals a tool can apply,\neach carrying its own verification (apply-in-memory → re-check → delta)\nso an action is never offered that "},{"k":"code","text":"nika check"},{"k":"text","text":" would then reject."}],[{"k":"strong","text":"`witness`"},{"k":"text","text":" on a finding — the computed DAG/taint path that justifies\nit, promoted from thrown-away intermediate to payload."}],[{"k":"strong","text":"`pathToRunnable`"},{"k":"text","text":" and the planner over actions — a route from an\nincomplete document to a checkable one, searched by BFS/Dijkstra (an\nadmissible A* only once its heuristic law is written)."}]]},{"k":"p","inline":[{"k":"text","text":"Each stays out of the shipped surface until its window proves it. Naming\nthem is a reservation, never a promise they exist."}]},{"k":"h","depth":2,"text":"One obvious way (normative for linters)","id":"one-obvious-way-normative-for-linters"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"A tool that shows structure reads the semantic document — it does not\nre-parse the YAML itself (one producer, one truth)."}],[{"k":"text","text":"The version a surface reasons about is "},{"k":"code","text":"semantic_document_format"},{"k":"text","text":" — the\nnested "},{"k":"code","text":"graph.graph_format"},{"k":"text","text":" versions the graph, not the document."}],[{"k":"text","text":"An unknown field on the surface is ignored, never rejected (additive\nforward-compat)."}]]},{"k":"h","depth":2,"text":"Related","id":"related"},{"k":"list","ordered":false,"items":[[{"k":"link","text":"03 · DAG","href":"./03-dag.md"},{"k":"text","text":" — the "},{"k":"code","text":"graph_format: 2"},{"k":"text","text":" projection this carries"}],[{"k":"link","text":"05 · Errors","href":"./05-errors.md"},{"k":"text","text":" — the diagnostics lane (judgment lives there, not here)"}],[{"k":"link","text":"10 · Authority","href":"./10-authority.md"},{"k":"text","text":" — the flow laws the projection also obeys (structure only)"}],[{"k":"link","text":"15 · Proof","href":"./15-proof.md"},{"k":"text","text":" — the semantic identity the projected graph commits to"}]]}]

the spec · 16

Projections

The first fifteen chapters define what a workflow *is* and what a run *proves*.

16 · Projections #

The first fifteen chapters define what a workflow is and what a run proves. This chapter defines what a tool sees: the oracle surface — the single, versioned, read-only projection of a workflow that the CLI, the language server, and the MCP tool all serve byte for byte the same. One truth, many lenses.This is the first chapter of the post-1.0, additive arc. Everything it adds is a projection over the frozen `nika: v1` IR — never a change to the language. A projection is a view; the thing viewed does not move.

The one projection (normative) #

There is one canonical projection of a workflow — the graph of 03 (graph_format: 2) — and every surface serves that same projection. nika inspect --format json (CLI), nika/semanticDocument (LSP), and the nika_inspect MCP tool all carry the byte-identical canonical projection; the surfaces differ only in what presentation they wrap around it.

A semantic document is the LSP-side surface: the canonical projection verbatim, plus the source spans a client needs to link graph nodes back to text, plus — when the graph cannot be built — the one-word reason why. It is a superset of the bare projection (the CLI and MCP serve the projection without editor spans), and it is the growth point of the oracle: holes, actions, and capabilities land here (§the additive arc), which is why it carries its own version.

text

1semantic_document = (2  semantic_document_format   # the surface's OWN version (this chapter)3  graph?                     # the canonical projection (03 · graph_format: 2) · absent when unbuildable4  reason?                    # WHY graph is absent · one word · closed vocabulary · omitted when graph is present5  spans                      # task id → the range of its declaring `id` token6)

`semantic_document_format: 1` — the surface names its own version, independent of the nested graph.graph_format. Until now the document versioned itself implicitly through graph.graph_format: 2; a projection that will grow additive fields (holes · actions · capabilities · §the additive arc) needs a version of its own so a consumer can reason about the surface without unwrapping the graph.
`graph` is the canonical projection of 03 verbatim (graph_format: 2 · the derived edges · the reference identity). The semantic document never re-derives it — it carries it.
`spans` map each task id to the LSP range of its declaring id token, so a canvas or a lens links a node back to source without re-scanning YAML.

`reason` · why the graph is absent (normative · closed) #

When the graph cannot be projected, graph is null and reason names why in one word, from a closed vocabulary — never a sentence, never a duplicate of a diagnostic (the details live in the diagnostics lane, 05):

`reason` · Meaning
`parse` · the source did not parse — there is no tree to project
`findings` · the source parsed but a check finding blocks a sound graph

The set is closed: a new reason is an additive change that bumps semantic_document_format. reason is omitted entirely when graph is present (a healthy document carries no reason key) — presence is the signal, not a sentinel value.

The triangle law (normative) #

The canonical projection has exactly one producer and is served, byte-identical, by three surfaces:

text

1nika inspect --format json     ┐  the canonical projection (graph_format: 2)2nika/semanticDocument (LSP)     ├─ byte-identical · one projection, three lenses3nika_inspect (MCP)              ┘  (the LSP additionally wraps editor spans)

The three MUST serve the same canonical-projection bytes for the same input — a lens that drifts is a bug, tested by parity, not by convention. The LSP's semantic document carries that same projection verbatim and adds spans (a presentation superset, not a re-derivation); the CLI and MCP serve the projection without editor spans.
Each surface is a typed contract, not a JSON bag: renaming a field breaks the producer's compilation (and the law tests) before it can break a consumer silently.

Read discipline (normative) #

A projection always answers. The request is a read, never a judgment. A malformed document still returns a semantic document — with a reason and whatever spans it could recover — never an error. Judgment lives in nika check (05), never in the projection.
Structure only. The projection carries names, shapes, spans, and derived structure — never a config value, a secret, or resolved material (10 flow laws hold here too). A projection that leaked a secret would be a sink; it is not one, by construction.
A projection is a view over the frozen IR. It never mutates, never re-orders, never re-interprets the workflow. Given the same source it is deterministic — the same bytes, every time.

The additive arc (normative · forward-compat) #

This surface is the plug-board for the post-1.0 oracle work. Every future field is additive under the version key, and every future field is a projection or an edit-proposal over the frozen v1 IR — never a new piece of the language:

Additive-field discipline. A new optional field (holes · actions · capabilities) bumps semantic_document_format and is skip-omitted when empty. A consumer that ignores an additive field still reads the whole older surface correctly — the same forward-compat the graph_format: 2 envelope already keeps (03). A consumer MUST ignore fields it does not know, never fail on them.
Capabilities are negotiated, not assumed. A client announces which extensions it understands under experimental.nika.*; the server offers an extension only when the client asked. An un-negotiated field is never sent.
Projection, never grammar. No field on this surface adds syntax a workflow author writes. Holes describe where a workflow is incomplete; actions describe an edit a tool could apply; both are computed from the v1 IR and validated against it. The language stays frozen (the 1.0 contract) while the oracle around it grows.

What v1 deliberately does not do (yet) #

The following are named here so the surface reserves room for them, and specified in their own later windows — not shipped by this chapter:

`holes` — typed descriptions of where a workflow is incomplete (a missing prompt:, an unfilled output), each anchored to a span, including spans for absent fields. (nika/holes · nika/fillHole.)
`actions` — SemanticActions: edit proposals a tool can apply, each carrying its own verification (apply-in-memory → re-check → delta) so an action is never offered that nika check would then reject.
`witness` on a finding — the computed DAG/taint path that justifies it, promoted from thrown-away intermediate to payload.
`pathToRunnable` and the planner over actions — a route from an incomplete document to a checkable one, searched by BFS/Dijkstra (an admissible A* only once its heuristic law is written).

Each stays out of the shipped surface until its window proves it. Naming them is a reservation, never a promise they exist.

One obvious way (normative for linters) #

A tool that shows structure reads the semantic document — it does not re-parse the YAML itself (one producer, one truth).
The version a surface reasons about is semantic_document_format — the nested graph.graph_format versions the graph, not the document.
An unknown field on the surface is ignored, never rejected (additive forward-compat).

03 · DAG — the graph_format: 2 projection this carries
05 · Errors — the diagnostics lane (judgment lives there, not here)
10 · Authority — the flow laws the projection also obeys (structure only)
15 · Proof — the semantic identity the projected graph commits to

nika-spec@6ac29351a · 16-projections.md · sha256 619a4b7af3c95fd5… · the pack upstream