@plurnk/plurnk-contracts 4.1.0 → 6.0.0

package/SPEC.md

@@ -2,6 +2,18 @@
 
 ## 1. Overview
 
+<!-- map -->
+| Tag | Promise |
+| --- | --- |
+| {§contract-representations} | JSON Schema is authoritative for shared data shapes. |
+| {§agui-discovery-contract} | `AguiDiscovery` is the complete installed AG-UI+ surface at one instant. |
+| {§agui-action-schema-enforcement} | The JSON Schema values in {§agui-discovery-contract} are executable boundary contracts, not prose or hints. |
+| {§agui-client-conformance} | `AguiClientConformance` is a language-neutral JSON document accounting for every action and notification in… |
+| {§agui-conformance-kit} | `AguiConformanceKit` is the one versioned, language-neutral corpus of raw SSE boundary specimens and AG-UI… |
+| {§json-result-rendering} | `renderJsonResult` renders compact aggregate operation rows. |
+| {§json-document-presentation} | Generated JSON documents use two-space indentation. |
+<!-- /map -->
+
 This package is the single authority for PLURNK's language, schemas, generated types and
 runtime-neutral wire envelopes; `@plurnk/plurnk-parser` implements the language it specifies
 ({§parser-consumers}). Its package root is the single code API for those contracts
@@ -92,6 +104,24 @@ metadata retain their deliberate layouts.
 
 ## 1.1 Contract layers and admission boundary
 
+<!-- map -->
+| Tag | Promise |
+| --- | --- |
+| {§contract-proposal-projection} | Admission policy and stopped-world projection |
+| {§capability-policy-matching} | A selector is an exact conjunction: every field it declares must equal the descriptor, while every selected… |
+| {§capability-policy-cascade} | Capability layers are purely subtractive and order-independent: a descriptor is admitted only when every… |
+| {§capability-policy-projection} | A `CapabilityProjection` reports every durable workspace layer and their normalized intersection: `service`,… |
+| {§proposal-policy} | `ProposalPolicy` names one server disposition; `PROPOSAL_POLICIES` is its schema-owned vocabulary. |
+| {§effort-wire} | `Effort` is exactly `off \| adaptive \| low \| medium \| high \| xhigh \| max`. |
+| {§model-catalog-wire} | `ModelRoute` is one exact client-visible provider/model identity with optional alias provenance. |
+| {§client-interaction-wire} | Client-owned interaction wire |
+| {§provider-usage} | `ProviderUsage` records only known non-negative safe-integer quantities. |
+| {§provider-cost} | `ProviderCost` represents one physical provider request's monetary disposition. |
+| {§provider-request-accounting} | `ProviderRequestAccounting` is the indivisible accounting fact for one issued physical request. |
+| {§provider-request-evidence} | The physical-request settlement may also carry JSON-serializable, provider-owned response/failure evidence. |
+| {§provider-accounting} | `ProviderAccounting.requests` is the source evidence. |
+<!-- /map -->
+
 One contract, deliberately different projections (ARCHITECTURE.md). Each layer
 below owns what it alone can decide.
 
@@ -262,6 +292,55 @@ and parse diagnostics are separate contracts.
 
 ## §canonical-statement 2. Canonical statement form
 
+<!-- map -->
+| Tag | Promise |
+| --- | --- |
+| {§section-boundary} | Every statement is one backtick block. |
+| {§fence-closer} | A block opened with N backticks closes at a line made of at least N backticks and nothing else but horizontal… |
+| {§balanced-fences} | A complete nested interpretation takes precedence over missing-closer recovery. |
+| {§operation-fences} | Accept three or more backticks; teach and render three. |
+| {§naked-operation} | A native name with only an optional aside opens without a fence. |
+| {§fence-heading-in-body} | Outside a complete nested block ({§balanced-fences}), a fence line of three or more backticks carrying a… |
+| {§closer-fallback} | A block that ends at a heading or at the end of the input has no closer of its own; its body is the whole… |
+| {§fence-boundary} | Every fence line inside a body takes one of these meanings, chosen for the whole input at once by… |
+| {§fence-pairing} | Fence pairing |
+| {§pairing-need} | Why a pass ahead of the grammar. |
+| {§pairing-algorithm} | Algorithm. |
+| {§pairing-objective} | Objective. |
+| {§unclosed-mutation-yields} | A mutation body never swallows a native operation. |
+| {§prose-code-blocks} | A message or a prompt shows code. |
+| {§message-run-on} | A message runs to the end of the turn. |
+| {§pairing-witness} | Witnesses. |
+| {§indented-fences} | CommonMark's indentation, everywhere. |
+| {§inline-chain} | A closer on a heading line, or on a body's closing line, may be followed on that same line by the next… |
+| {§transparent-inline-closer} | A closer mid-heading is read as if it were not written. |
+| {§executor-case} | An executor tag in any case. |
+| {§executor-js-spelling} | When `node` is registered and `js` is not, `js` names `node` under {§executor-case}. |
+| {§one-line-turn} | A whole turn on one line. |
+| {§anchor-digits} | In a text scope, `@` followed by one to four digits cannot be a hash and is read as that line number, with… |
+| {§unclosed-aside} | A heading whose aside opens with `<!--` and never closes on its line takes the rest of the line as the aside,… |
+| {§quotation} | A fence that opens no operation quotes. |
+| {§forgotten-tag} | A tag on the line under a bare fence is the operation. |
+| {§executor-heading} | Syntax identifies an invocation; dispatch resolves its runtime. |
+| {§interstitial-fence} | Only a heading under {§executor-heading} opens an operation. |
+| {§closer-aside} | A closing fence followed on its line by one aside and nothing else is the closer; the aside is outside text. |
+| {§heading-slot-order} | A heading near-miss with exactly one reading is read as that reading, with no diagnostic and no teaching… |
+| {§native-tool-calls} | An emission that yields no operation may be a model's native tool-call markup naming a plurnk operation or a… |
+| {§native-tool-call-receipt} | Unexecuted native markup draws a warning. |
+| {§empty-section} | Both the compact bodyless form and an empty multiline block normalize optional bodies to null. |
+| {§statement-rendering} | `PlurnkParser.stringify` renders native OP names and named runtime fences from the shared AST, with one blank… |
+| {§slot-order} | Producers put target, scope, metadata, then aside, separated by one ASCII space. |
+| {§lifecycle-slots} | NOTE accepts no target, scope, or metadata. |
+| {§target-group} | READ and KILL take a target group. |
+| {§safe-uri-target-groups} | An explicit URI list is a target group. |
+| {§scope-on-scopeless} | A scope on an operation that takes none is dropped, and named. |
+| {§heading-inline-body} | Nonempty body text belongs below the fence header. |
+| {§bare-option-object} | A bare option object is the option block, where the house option array owns the block. |
+| {§operation-aside} | The final header modifier may be one single-line HTML comment. |
+| {§scheme-metadata-modifier} | A target may carry one single-line `[metadata]` block, placed under {§slot-order}; executor and SEND fences… |
+| {§matcher-option} | `pattern` is the matcher, and it lives in the heading. |
+<!-- /map -->
+
 `````text
 ```OP (path)? <scope>? [metadata]? <!-- aside -->?
 body
@@ -291,7 +370,7 @@ rule.
 
 §balanced-fences A complete nested interpretation takes precedence over missing-closer
 recovery. Within a body, a line-leading labeled fence opens a literal block, and an equal or
-wider bare fence nests where closing there would cost the reading more
+wider bare fence nests unless closing there costs the reading less
 ({§fence-pairing}). A nested block ends at its first valid closer, as a CommonMark code block
 does. So a wider outer fence holds any narrower body, finished or not, and equal widths nest
 when every inner block closes. Preserve every nested body byte, including apparent operations
@@ -309,23 +388,13 @@ fence only as the nesting form. Every producer of a statement — the parser, a
 `/look`, a client's tab-completion — writes `PLURNK_FENCE` rather than its own literal
 (plurnk/plurnk#92).
 
-§naked-operation **A native name with only an optional aside opens without a fence.** A
-column-zero line outside any block containing a native operation's name and at most one complete
-`<!-- aside -->`, with only horizontal whitespace otherwise, opens that operation as if it were
-fenced with the taught three backticks. The aside retains its ordinary meaning: no target or
-modifiers are inferred. Its body runs to a line that is exactly the name
-again, to the next heading ({§fence-heading-in-body}), or to the end of the turn. A fence inside
-naming nothing known is body; the block expects no closer, so its body is never cut
-back ({§closer-fallback}). One warning-severity receipt follows a recovered statement —
-`` `NOTE` opened with no fence; the taught form is three backticks. `` One rule for every native
-operation: a naked `WAIT` parks, a naked `NOTE` takes its text, a naked `READ` meets the ordinary
-missing-target refusal. A closer the author wrote anyway is still not body: when the body's last line is
-a bare backtick fence that no other fence line in the body pairs with (an odd count of fence lines), that
-line is the block's closer and leaves the body, so `SEND`, then the answer, then a closing fence delivers
-the answer alone. An aside-bearing name inside a body is not a closer. An incomplete or repeated
-aside, an operand, or other heading text does not qualify and remains the unfenced form
-({§unfenced-operation}). Executors are runtimes rather than operations, and reasoning is never
-read this way.
+§naked-operation **A native name with only an optional aside opens without a fence.** A column-zero line outside any block containing a native operation's name and at most one complete `<!-- aside -->`, with only horizontal whitespace otherwise, opens that operation as if it were fenced with the taught three backticks. The aside retains its ordinary meaning: no target or modifiers are inferred. One warning-severity receipt follows a recovered statement — `` `NOTE` opened with no fence; the taught form is three backticks. `` One rule for every native operation: a naked `WAIT` parks, a naked `NOTE` takes its text, a naked `READ` meets the ordinary missing-target refusal. Executors are runtimes rather than operations, and reasoning is never read this way.
+
+| Fact | Rule |
+| --- | --- |
+| The body | runs to a line that is exactly the name again, to the next heading ({§fence-heading-in-body}), or to the end of the turn; a fence inside naming nothing known is body; the block expects no closer, so its body is never cut back ({§closer-fallback}) |
+| A closer the author wrote anyway | still not body: when the body's last line is a bare backtick fence that no other fence line in the body pairs with (an odd count of fence lines), that line is the block's closer and leaves the body, so `SEND`, then the answer, then a closing fence delivers the answer alone; an aside-bearing name inside a body is not a closer |
+| Not the form | an incomplete or repeated aside, an operand, or other heading text does not qualify and remains the unfenced form ({§unfenced-operation}) |
 
 §fence-heading-in-body Outside a complete nested block ({§balanced-fences}), a fence
 line of three or more backticks carrying a heading under {§executor-heading}
@@ -389,54 +458,41 @@ alternative (§4.2), so neither mode chooses among complete readings by cost. Th
 Python (`INDENT`/`DEDENT`) and PHP (heredoc) grammars settle block structure the same way:
 outside the grammar, then hand the lexer tokens.
 
-§pairing-algorithm **Algorithm.** Each line is classified by the lexer's line-start rules: text, a
-bare fence, a labeled fence, a heading, a closer glued to a heading, or a naked operation name.
-A block's contents read the same whatever lies beneath it on the stack, so the pass summarizes
-each (position, block, what the block holds so far) once. For a nested block, the summary maps
-every place the block could end to its cheapest reading up to there; parents compose their
-children's summaries. An outermost block is evaluated in the root's frame, where only the cost
-to the end of the input matters, so it holds one entry. Evaluation runs on an explicit work
-stack. Candidates are taken in preference order and replace one another only by costing
-strictly less, so each entry is the reading a preference-ordered exhaustive search returns.
-Inside a quotation or a nested block the first valid closer closes, CommonMark's rule, applied
-as a disambiguation filter (Klint and Visser, 1994); an operation body keeps the choice between
-nesting and closing. A block opened by a bare fence must hold a line, except a quotation at the
-top level: two stray fences in a row there are an empty quotation, shown and harmless, rather
-than two repairs that a reading could avoid only by hiding an operation.
+§pairing-algorithm **Algorithm.** Each line is classified by the lexer's line-start rules: text, a bare fence, a labeled fence, a heading, a closer glued to a heading, or a naked operation name. Evaluation runs on an explicit work stack.
+
+| Step | Rule |
+| --- | --- |
+| Summaries | a block's contents read the same whatever lies beneath it on the stack, so the pass summarizes each (position, block, what the block holds so far) once; for a nested block, the summary maps every place the block could end to its cheapest reading up to there, and parents compose their children's summaries; an outermost block is evaluated in the root's frame, where only the cost to the end of the input matters, so it holds one entry |
+| Candidates | taken in preference order and replace one another only by costing strictly less, so each entry is the reading a preference-ordered exhaustive search returns |
+| Closers | inside a quotation or a nested block the first valid closer closes, CommonMark's rule, applied as a disambiguation filter (Klint and Visser, 1994); an operation body keeps the choice between nesting and closing |
+| A block opened by a bare fence | must hold a line, except a quotation at the top level: two stray fences in a row there are an empty quotation, shown and harmless, rather than two repairs that a reading could avoid only by hiding an operation |
 
 §pairing-objective **Objective.** A complete reading, one that needs no repair, wins over every
 repaired reading: a complete nested interpretation takes precedence. Each class has its own order.
 
 | Counted | Complete readings | Repaired readings | Why |
 |---|---|---|---|
-| Hidden operations: a heading that will not run, written at its block's width or wider | 1, together with the next row | 1 | Every operation the author wrote should run |
+| Hidden operations: a heading that will not run, written at its block's width or wider | 1, together with discarded code | 1 | Every operation the author wrote should run |
 | Repairs: a supplied closer (except a message's run to the end of the input, {§message-run-on}), a fence read as a stray, a narrower closer accepted, a body under an operation that takes none (COPY, MOVE, non-log targeted KILL), a body not well-formed in the media type its runtime declares ({§executor-invocation}) | none by definition | 2 | The least-errors distance |
-| Literal by declaration: a heading narrower than its block, or no wider than the labeled block or example holding it, or inside a quotation or a KILL, or an executor heading inside a SEND, WORK, FORK or BARE body ({§prose-code-blocks}); a labeled fence in a body read as text | 1, together with the row above | 3 | Every code block the author declared should stand |
+| Literal by declaration: a heading narrower than its block, or no wider than the labeled block or example holding it, or inside a quotation or a KILL, or an executor heading shown as a code block inside a SEND, WORK, FORK or BARE body ({§prose-code-blocks}) | none: the author's enclosure wrote it as an example | 3, together with the row below | A heading the author wrapped is the example it was written as |
+| Discarded code: a labeled fence in a body read as text, or such an executor heading read as text | 1, together with hidden operations | 3, together with the row above | Every code block the author declared should stand |
 | Supplied closers | 2 | 4 | A block the author opened should end at a fence the author wrote |
 | Other fences read as text | 3 | 5 | The least departure from the fences as written |
 
-Complete readings compare exactly as a single least-errors order would. Once every reading of an
-emission needs a repair, its shape is already broken, and saving a repair is not worth an operation
-the author wrote: across the corpus, readings that traded operations for repairs held a WORK in a
-BARE behind two stray fences, wrote 11,485 characters of operation text into a file as an EDIT
-body, and ended a turn's KILL inside a WAIT. A summary keeps, for every place a block could end, the
-best complete reading under each order and the best repaired reading, so the search stays exact:
-a repaired total may take either class for any of its parts.
-
-§unclosed-mutation-yields **A mutation body never swallows a native operation.** An example
-inside an EDIT is written with a wider outer fence ({§operation-fences}); a heading narrower than
-the EDIT's fence is literal by declaration and stays text. At the EDIT's own width a native
-operation heading runs, closed or not: read as the body's example it would be a *swallowed*
-operation, and a swallowed operation outranks any number of repairs — a reading that swallows one
-is never complete, and among repaired readings the fewest swallowed wins before every other class.
-So where ```` ```EDIT (b.py) ```` follows ```` ```EDIT (a.py) ```` with no closer between, the
-reading that supplies `a.py`'s closer before that heading wins, both EDITs run, and no operation
-heading is written into a file; the same shape with a closer after the example is fence-identical
-and reads the same way. Of 67 recorded EDIT bodies holding a native heading, 66 use the wider fence
-and read unchanged, and the one at equal width (glm run158) had written a test EDIT's heading and
-body into `functional.py` and never run it. Only EDIT mutates from its body, so only EDIT carries
-the rule: an executor heading inside an EDIT keeps the ordinary reading, and SEND, WORK, FORK and
-BARE bodies keep {§prose-code-blocks}.
+Complete readings compare as a single least-errors order over departures from the fences as written, and a heading the author enclosed in a wider or labeled fence is the example it was written as, not a departure.
+
+| Rule | What |
+| --- | --- |
+| A narrower message fence | a message whose own fence is narrower than the fences wrapping its examples still holds them: the reading that lets a wrapper close the message and runs the examples ties on cost and loses on preference, since a body nests before it closes ({§balanced-fences}) |
+| A broken shape | once every reading of an emission needs a repair, its shape is already broken, and saving a repair is not worth an operation the author wrote |
+| The summary | keeps, for every place a block could end, the best complete reading under each order and the best repaired reading, so the search stays exact: a repaired total may take either class for any of its parts |
+
+§unclosed-mutation-yields **A mutation body never swallows a native operation.** An example inside an EDIT is written with a wider outer fence ({§operation-fences}); a heading narrower than the EDIT's fence is literal by declaration and stays text. At the EDIT's own width a native operation heading runs, closed or not: read as the body's example it would be a *swallowed* operation, and a swallowed operation outranks any number of repairs — a reading that swallows one is never complete, and among repaired readings the fewest swallowed wins before every other class. Only EDIT mutates from its body, so only EDIT carries the rule: an executor heading inside an EDIT keeps the ordinary reading, and SEND, WORK, FORK and BARE bodies keep {§prose-code-blocks}.
+
+| Shape | Reading |
+| --- | --- |
+| ```` ```EDIT (b.py) ```` follows ```` ```EDIT (a.py) ```` with no closer between | the reading that supplies `a.py`'s closer before that heading wins, both EDITs run, and no operation heading is written into a file |
+| The same shape with a closer after the example | fence-identical, and reads the same way |
 
 Equal cost goes to the earlier alternative: nesting before closing in an operation body,
 closing before nesting in a quotation, and a supplied closer before a literal example at a
@@ -537,24 +593,14 @@ draws one warning that it was shown, not run. At the top level, a bare fence who
 operation heading opens that operation instead ({§forgotten-tag}). A labeled block is an example by
 declaration, and nothing else inside draws an advisory.
 
-§forgotten-tag **A tag on the line under a bare fence is the operation.** At the top level, a bare
-fence whose next line is an operation heading, a native name alone or with a slot or an executor's
-name with its operand, opens that operation as if both were written on one line: the heading takes
-its slots, the lines after it are its body, and it closes like any operation. It runs, and one
-warning-severity receipt names the form — `` `READ` ran, though its fence was malformed: the
-opening fence, OP, parameters, and aside share one line. `` Saying that it ran keeps the model from
-issuing it again. Inside a body the same lines stay literal. Measured: of 2,308 naked fences in
-12,797 recorded emissions, 51 open that way and 2,238 hold code or quoted output, which is why a
-bare fence alone draws nothing; in the 10,486-emission fence corpus every one of the 12 that open
-that way was an operation the model meant to run. An example the model means only to show
-belongs in a properly nested body ({§balanced-fences}) or a quotation ({§quotation}).
-So a model may show plurnk's own operations in an answer. Two exceptions keep programs whole:
-CommonMark's own rule that a backtick opener's line carries no further backtick, so
-```` ```READ (x)``` ```` is inline code and quotes nothing after it; and a bare fence directly under
-a line carrying a fence run, which is an orphaned closer and quotes nothing. An unknown tag
-without invocation slots is a code block and draws nothing. An offset example draws nothing either
-({§indented-fences}). Quotation outside an operation is
-response text under {§response-text}, not an executable program or a completion envelope.
+§forgotten-tag **A tag on the line under a bare fence is the operation.** At the top level, a bare fence whose next line is an operation heading, a native name alone or with a slot or an executor's name with its operand, opens that operation as if both were written on one line: the heading takes its slots, the lines after it are its body, and it closes like any operation. It runs, and one warning-severity receipt names the form — `` `READ` ran, though its fence was malformed: the opening fence, OP, parameters, and aside share one line. `` Saying that it ran keeps the model from issuing it again. Inside a body the same lines stay literal. A bare fence alone draws nothing: nearly every one holds code or quoted output. An example the model means only to show belongs in a properly nested body ({§balanced-fences}) or a quotation ({§quotation}), so a model may show plurnk's own operations in an answer. Quotation outside an operation is response text under {§response-text}, not an executable program or a completion envelope.
+
+| Draws nothing | Why |
+| --- | --- |
+| ```` ```READ (x)``` ```` on one line | CommonMark's own rule that a backtick opener's line carries no further backtick: it is inline code and quotes nothing after it |
+| A bare fence directly under a line carrying a fence run | an orphaned closer; it quotes nothing |
+| An unknown tag without invocation slots | a code block |
+| An offset example | {§indented-fences} |
 
 `plurnk.md` names the tab offset as the form for an example, in the aside of its nesting
 example, and shows its own examples offset; the other quoting fences are untaught: a tilde
@@ -592,43 +638,27 @@ reading, with no diagnostic and no teaching (#758):
 
 Tokens keep their source positions; only their order in the stream changes.
 
-§native-tool-calls An emission that yields no operation may be a model's native
-tool-call markup naming a plurnk operation or a known executor, and every popular
-family is read the same way: DeepSeek's `<｜｜DSML｜｜ calls>` and Anthropic-style
-`<function_calls>` blocks of `invoke` elements with `parameter` children; the
-`<tool_call>` family as `<function=NAME>` with `<parameter=key>` children (Qwen,
-MiMo), as a JSON object with `name` and `arguments` (Hermes and kin), or as a name
-followed by `<arg_key>`/`<arg_value>` pairs (GLM); a bare `<function=NAME>` element
-(Llama); Mistral's `[TOOL_CALLS]` JSON array; Llama's `<|python_tag|>` JSON object; and
-Kimi's `<|tool_call_begin|>` sections. Each call is read as that operation's
-canonical fence: `path`/`target`/`file_path`/`file`/`resource`/`uri` fill the target,
-`scope`/`range`/`lines` the scope, as do `start`/`end` written apart and `offset`/`limit`
-(a first line and a count), `pattern`/`regex`/`query` a matcher option, `aside`
-the aside, and `body`/`content`/`command`/`text`/`input` or plain text inside the
-call the body; plurnk slots written after the name are kept, a trailing scope's own
-bracket may close the tag. A block keeps its line count where its lines allow, so
-statement positions name the source line; an inline block grows to its fences.
-DeepSeek writes the whole heading into the invoke's name — `<｜｜DSML｜｜ invoke name="FIND (docs/**)
-/Http404/ <!-- docs mentions -->">`, or `name="sh` with no closing quote and the script on the lines
-below — and the element's content is the body: the first word of the name is the operation, the rest
-its slots, and `parameter` tags around the content are debris, as are a copied facts line
-(`{"lines":6}`) under the heading, a `comment` attribute (the aside), and `<｜｜DSML｜｜tool_calls>`
-spelled without spaces. An executor's unknown parameter is one of its options, `[{"maxTokens":
-"2500"}]`, for its owner to accept or refuse; `bash` names `sh` when `sh` is the registered shell.
-Calls that cannot be mapped draw {§native-tool-call-receipt}.
-Qwen's own shapes read the same way: a flat JSON call whose operation is the value
-of an `op`, `action` or `cmd` key in any case (`{"op": "READ", "path": …, "range": …}`),
-an XML element named by the operation (`<NOTE>…</NOTE>`, `<FIND (path) <1,3></FIND>`,
-`<read path="…"/>`) or by a generic `op` element or function (`<op op="READ" …>`,
-`<op verb="READ" …/>` in `<ops>`, `<op=READ (path) …>`, `<function=OP name="READ" …>`,
-`<function=OP>` around such a JSON call or a plurnk heading), and a plurnk heading written
-as the call's text (`<tool_call>READ (a.py) <60,120>`, `=READ (…)`). Closing tags left over
-from another family (`</parameter>`, `</invoke>`, `</>`) after a call are markup noise;
-`reason` and `description` are the aside; a scope may be a JSON array (`[500,530]`) or a
-`{"start", "end"}` object; an executor's string `input` is its program. A call with an
-unknown name or parameter, or a FIND, READ, EDIT, COPY or MOVE naming no target, leaves the
-whole emission as it was. An emission that already yields an operation is never
-rewritten. No diagnostic, notice or teaching mentions a successful reading (#760).
+§native-tool-calls **An emission that yields no operation may be a model's native tool-call markup naming a plurnk operation or a known executor, and every popular family is read the same way.** A block keeps its line count where its lines allow, so statement positions name the source line; an inline block grows to its fences. A call with an unknown name or parameter, or a FIND, READ, EDIT, COPY or MOVE naming no target, leaves the whole emission as it was; calls that cannot be mapped draw {§native-tool-call-receipt}. An emission that already yields an operation is never rewritten. No diagnostic, notice or teaching mentions a successful reading (#760).
+
+| Family | Shape |
+| --- | --- |
+| DeepSeek | `<｜｜DSML｜｜ calls>` blocks of `invoke` elements with `parameter` children; DeepSeek writes the whole heading into the invoke's name — `<｜｜DSML｜｜ invoke name="FIND (docs/**) /Http404/ <!-- docs mentions -->">`, or `name="sh` with no closing quote and the script on the lines below — and the element's content is the body: the first word of the name is the operation, the rest its slots, and `parameter` tags around the content are debris, as are a copied facts line (`{"lines":6}`) under the heading, a `comment` attribute (the aside), and `<｜｜DSML｜｜tool_calls>` spelled without spaces |
+| Anthropic-style | `<function_calls>` blocks of `invoke` elements with `parameter` children |
+| The `<tool_call>` family | `<function=NAME>` with `<parameter=key>` children (Qwen, MiMo); a JSON object with `name` and `arguments` (Hermes and kin); a name followed by `<arg_key>`/`<arg_value>` pairs (GLM) |
+| Llama | a bare `<function=NAME>` element; a `<\|python_tag\|>` JSON object |
+| Mistral | a `[TOOL_CALLS]` JSON array |
+| Kimi | `<\|tool_call_begin\|>` sections |
+| Qwen's own shapes | a flat JSON call whose operation is the value of an `op`, `action` or `cmd` key in any case (`{"op": "READ", "path": …, "range": …}`); an XML element named by the operation (`<NOTE>…</NOTE>`, `<FIND (path) <1,3></FIND>`, `<read path="…"/>`) or by a generic `op` element or function (`<op op="READ" …>`, `<op verb="READ" …/>` in `<ops>`, `<op=READ (path) …>`, `<function=OP name="READ" …>`, `<function=OP>` around such a JSON call or a plurnk heading); a plurnk heading written as the call's text (`<tool_call>READ (a.py) <60,120>`, `=READ (…)`) |
+
+| Call piece | Read as |
+| --- | --- |
+| `path`/`target`/`file_path`/`file`/`resource`/`uri` | the target |
+| `scope`/`range`/`lines`, `start`/`end` written apart, `offset`/`limit` (a first line and a count), a JSON array (`[500,530]`) or a `{"start", "end"}` object | the scope; plurnk slots written after the name are kept, and a trailing scope's own bracket may close the tag |
+| `pattern`/`regex`/`query` | a matcher option |
+| `aside`, `reason`, `description` | the aside |
+| `body`/`content`/`command`/`text`/`input` or plain text inside the call; an executor's string `input` | the body, an executor's program |
+| An executor's unknown parameter | one of its options, `[{"maxTokens": "2500"}]`, for its owner to accept or refuse; `bash` names `sh` when `sh` is the registered shell |
+| Closing tags left over from another family (`</parameter>`, `</invoke>`, `</>`) after a call | markup noise |
 
 Bare `invoke` elements use the same slots as wrapped calls. A complete JSON object
 inside an invoke supplies arguments when no explicit parameter elements are
@@ -683,18 +713,14 @@ is refused; the recovery is the scope's working form ({§parse-recovery}).
 optional target and duration under {§send-wait-scope}. Their literal bodies begin
 below the header.
 
-§target-group **READ and KILL take a target group.** A READ or KILL heading may carry several
-`(path)` slots, each binding the scope and metadata that follow it under {§slot-order}; a naked
-pattern on the heading ({§naked-pattern}) supplies the default for each member without its own
-metadata `pattern`. The parser compiles the complete heading into one ordinary statement per
-member, in authored order, each with its own target, scope, metadata and resolved matcher. No
-duplicated first-member or group representation crosses the parser boundary. Every resulting
-statement retains the heading's source position and aside; a heading-level parse error refuses
-all its members, not valid sibling headings. A distilling body ({§log-kill-distillation}) lands
-once, with the first member. COPY and MOVE keep their two operands with their own meaning
-({§transfer-resource-selections}); every other operation takes one slot, and a second slot on its
-heading is the slot-opener diagnostic. The form is accepted, not taught: it rescues a bulk attempt
-written one path per slot.
+§target-group **READ and KILL take a target group.** A READ or KILL heading may carry several `(path)` slots, each binding the scope and metadata that follow it under {§slot-order}; a naked pattern on the heading ({§naked-pattern}) supplies the default for each member without its own metadata `pattern`. The form is accepted, not taught: it rescues a bulk attempt written one path per slot.
+
+| Fact | Rule |
+| --- | --- |
+| Compilation | the parser compiles the complete heading into one ordinary statement per member, in authored order, each with its own target, scope, metadata and resolved matcher; no duplicated first-member or group representation crosses the parser boundary |
+| Position and aside | every resulting statement retains the heading's source position and aside; a heading-level parse error refuses all its members, not valid sibling headings |
+| A distilling body ({§log-kill-distillation}) | lands once, with the first member |
+| Other operations | COPY and MOVE keep their two operands with their own meaning ({§transfer-resource-selections}); every other operation takes one slot, and a second slot on its heading is the slot-opener diagnostic |
 
 §safe-uri-target-groups **An explicit URI list is a target group.** In READ and KILL only,
 one path slot may contain several explicit `scheme://` URIs separated by top-level commas or
@@ -731,18 +757,13 @@ compact empty block or permit unmatched fences.
 | executors | The input body, including an unbracketed JSON object; metadata requires brackets. |
 | NOTE, WAIT, KILL without a target | The body. |
 
-§bare-option-object A bare option object is the option block, where the house option array owns the
-block. On SEND, BARE, WORK and FORK, heading text after the slots that is exactly one JSON object `{…}`, where the
-heading admits a block (BARE, WORK and FORK only after their target), is read
-as `[{…}]`: the AST carries the array form, the written heading renders it, and one
-warning-severity receipt names the indulgence in place of the {§heading-inline-body} advisory:
-"`SEND` took a bare option object; the taught form is `[{…}]`." Executor headings always read an
-unbracketed object as input under {§heading-inline-body}, regardless of registration or input media
-type; their metadata is only the bracketed slot ({§scheme-metadata-modifier}). A heading that already carries a block keeps the object as
-inline body. On FIND, READ and KILL the same text is the matcher
-({§naked-pattern}), because a search for JSON text is legitimate; a bare matcher
-that parses as a JSON object draws one advisory saying so: "`{…}` was read as the
-matcher." ({§diagnostic-observation}).
+§bare-option-object **A bare option object is the option block, where the house option array owns the block.** Executor headings always read an unbracketed object as input under {§heading-inline-body}, regardless of registration or input media type; their metadata is only the bracketed slot ({§scheme-metadata-modifier}).
+
+| Heading | `{…}` after the slots is |
+| --- | --- |
+| SEND, BARE, WORK and FORK, where the heading admits a block (BARE, WORK and FORK only after their target) | read as `[{…}]`: the AST carries the array form, the written heading renders it, and one warning-severity receipt names the indulgence in place of the {§heading-inline-body} advisory: "`SEND` took a bare option object; the taught form is `[{…}]`." |
+| One that already carries a block | inline body |
+| FIND, READ and KILL | the matcher ({§naked-pattern}), because a search for JSON text is legitimate; a bare matcher that parses as a JSON object draws one advisory saying so: "`{…}` was read as the matcher." ({§diagnostic-observation}) |
 
 §operation-aside The final header modifier may be one single-line HTML
 comment. AstBuilder removes its delimiters and surrounding whitespace into
@@ -774,25 +795,14 @@ Two keys never reach an owner:
 service's environment option on the operations that open a process or a
 Worker; the shared reader withholds both from the owner's options.
 
-§matcher-option **`pattern` is the matcher, and it lives in the heading.** On
-FIND, READ, KILL, EDIT, and each COPY/MOVE operand, the option
-`[{"pattern": "<matcher>"}]` carries the matcher string: the leading prefix
-claims its dialect under {§matcher-prefix-claims}, and
-AstBuilder lifts it into the statement's `matcher` (`MatcherBody | null`),
-positioned dialect errors included. A block that carries only `pattern`
-leaves `metadata: null` for the owner; beside other keys the block stays with
-the owner verbatim, and the owner's reader treats `pattern` as reserved. The
-language lifts only from one block that parses as a JSON array of objects;
-anything else lifts nothing and reaches the owner's `400` untouched. A
-`pattern` that is present but not a string is the language's own positioned
-diagnostic, as is a matcher of a claimed dialect that fails admission. FIND and
-READ bodies become memory under {§retrieval-annotation}; a non-log KILL's body is
-unused and receives the advisory under {§matcher-body-redirect}. The heading line
-is the matcher's home ({§naked-pattern}). EDIT keeps its literal body:
-with a matcher it is the replacement for every selected span ({§edit-pattern}),
-and an absent body deletes them. `PlurnkParser.stringify` writes a lifted matcher
-whose block left no metadata back bare when the bare form reads back identically
-and draws no advisory ({§naked-pattern}), otherwise as `[{"pattern": "…"}]`.
+§matcher-option **`pattern` is the matcher, and it lives in the heading.** On FIND, READ, KILL, EDIT, and each COPY/MOVE operand, the option `[{"pattern": "<matcher>"}]` carries the matcher string: the leading prefix claims its dialect under {§matcher-prefix-claims}, and AstBuilder lifts it into the statement's `matcher` (`MatcherBody | null`), positioned dialect errors included. The heading line is the matcher's home ({§naked-pattern}).
+
+| Fact | Rule |
+| --- | --- |
+| The block | one that carries only `pattern` leaves `metadata: null` for the owner; beside other keys the block stays with the owner verbatim, and the owner's reader treats `pattern` as reserved; the language lifts only from one block that parses as a JSON array of objects, and anything else lifts nothing and reaches the owner's `400` untouched |
+| Diagnostics | a `pattern` that is present but not a string is the language's own positioned diagnostic, as is a matcher of a claimed dialect that fails admission |
+| Bodies | FIND and READ bodies become memory under {§retrieval-annotation}; a non-log KILL's body is unused and receives the advisory under {§matcher-body-redirect}; EDIT keeps its literal body: with a matcher it is the replacement for every selected span ({§edit-pattern}), and an absent body deletes them |
+| `PlurnkParser.stringify` | writes a lifted matcher whose block left no metadata back bare when the bare form reads back identically and draws no advisory ({§naked-pattern}), otherwise as `[{"pattern": "…"}]` |
 
 ## 3. Lexical elements
 
@@ -808,6 +818,30 @@ and draws no advisory ({§naked-pattern}), otherwise as `[{"pattern": "…"}]`.
 
 ## §op-shapes 4. Per-operation semantics
 
+<!-- map -->
+| Tag | Promise |
+| --- | --- |
+| {§retrieval-annotation} | A retrieval's authored body is memory, not selection or output. |
+| {§note-value} | NOTE retains its literal body as ordinary model-owned working memory. |
+| {§reasoning-operations} | The shared fence parser admits complete, line-leading NOTE, FIND and READ statements from exposed provider… |
+| {§exec-executor-slot} | The fence name selects the executor directly: for example, `python3 (tools/report.py)` or `gitea… |
+| {§turn-disposition} | WAIT requests parking; its literal body does not control scheduling, and its optional target is the label the… |
+| {§send-wait-scope} | WAIT's optional `[seconds]` metadata is a non-negative finite scalar bounding this park, not the lifetime of… |
+| {§send-directed-scope} | A recipient SEND carries an optional numeric scope after its target and metadata through to the addressed… |
+| {§kill-scope} | KILL takes an optional text-coordinate scope beside its target, and an optional matcher. |
+| {§bracket-metadata-slot} | Brackets are the owner's metadata modifier: the runtime or MCP service is the fence name, and tool input… |
+| {§text-scope-semantics} | Exact regions use 1-based lines and Unicode code-point columns. |
+| {§bare-statement} | BARE requests one isolated model inference. |
+| {§read-find-normalization} | An authored READ is never rewritten into a FIND. |
+| {§local-path-fragment} | A bare path takes `#channel` like a URL. |
+| {§read-exact-target} | READ targets one exact resource (a local path or scheme URL, with optional `#channel` fragment or… |
+| {§unscoped-edit-create-only} | No scope and an existing target is refused. |
+| {§empty-mutation-scope} | Empty mutation content has one writable position: `<0>`, `<1>`, `<-1>`, and `<1,-1>` all insert the body as… |
+| {§transfer-resource-selections} | COPY and MOVE require two singular `ResourceSelection` operands, source first and destination second, and… |
+| {§find-result-unit} | For FIND, target selection fixes the paginated result unit after scheme address resolution… |
+| {§copy-move-observation} | COPY and MOVE log projections preserve both admitted operand selections, including their independent scopes,… |
+<!-- /map -->
+
 The model-facing forms below are the canonical projection. Parser tolerance is
 governed by {§canonical-statement}; runtime conditions remain explicit below.
 
@@ -840,9 +874,10 @@ is curated normally. Explicit NOTE remains the taught form.
 §note-value NOTE retains its literal body as ordinary model-owned working memory.
 It has no target, scope, metadata, or lifecycle effect. Its full body participates
 in ordinary log token accounting and model-driven curation; prior notes are not
-automatically hidden. Each turn may contain zero or more NOTEs; their omission
-produces neither a notice nor a failure. A NOTE-only turn does not request
-completion; ordinary repetition and strike rules still apply.
+automatically hidden. A continuing or parked turn that carried no NOTE is told so in
+the next packet ({§continued-without-note}); the omission is never a failure. A
+NOTE-only turn does not request completion; ordinary repetition and strike rules
+still apply.
 
 §reasoning-operations The shared fence parser admits complete, line-leading NOTE,
 FIND and READ statements from exposed provider reasoning. Admission is part of
@@ -902,20 +937,13 @@ semantics or refuses it; worker actors refuse one (`scope-unsupported`, 400). A
 targetless message takes no scope. A scope never changes the message body or
 disposition.
 
-§kill-scope KILL takes an optional text-coordinate scope beside its target, numeric or
-anchored (```` ```KILL (log:///**/READ) <17,-1>``` ```` or
-```` ```KILL (worker:///notes.md) <@aB3dE,@0Aa9Z>``` ````), and an optional matcher option that
-selects rows or lines (```` ```KILL (log:///**) [{"pattern": "~stale"}]``` ````, {§matcher-option}).
-Each operand becomes an ordinary KILL statement with its own `target`, `lineMarker` and
-`matcher`; no grouped AST reaches execution ({§target-group}).
-KILL requires a target. Its body is retained on a `log:///` target, where
-it is the model's distillation of what the KILL retires and lands as its own NOTE row
-({§log-kill-distillation}); every other targeted KILL has `body: null`, and a body beneath one
-draws the advisory ({§matcher-body-redirect}). Beneath a `log:///` KILL the body is never read as
-a matcher; an inline pattern on the heading line still lifts.
-Without a scope, KILL retires or deletes the whole target; with one, it removes exactly
-that span — of a log body's packet projection or of an entry's content. Core owns the
-one-way semantics: there is no operation that restores a scoped-away log body.
+§kill-scope **KILL takes an optional text-coordinate scope beside its target, and an optional matcher.** The scope is numeric or anchored (```` ```KILL (log:///**/READ) <17,-1>``` ```` or ```` ```KILL (worker:///notes.md) <@aB3dE,@0Aa9Z>``` ````); the matcher option selects rows or lines (```` ```KILL (log:///**) [{"pattern": "~stale"}]``` ````, {§matcher-option}). Each operand becomes an ordinary KILL statement with its own `target`, `lineMarker` and `matcher`; no grouped AST reaches execution ({§target-group}). KILL requires a target.
+
+| Fact | Rule |
+| --- | --- |
+| The body | retained on a `log:///` target, where it is the model's distillation of what the KILL retires and lands as its own NOTE row ({§log-kill-distillation}); every other targeted KILL has `body: null`, and a body beneath one draws the advisory ({§matcher-body-redirect}); beneath a `log:///` KILL the body is never read as a matcher, while an inline pattern on the heading line still lifts |
+| Without a scope | KILL retires or deletes the whole target |
+| With one | it removes exactly that span — of a log body's packet projection or of an entry's content; Core owns the one-way semantics: there is no operation that restores a scoped-away log body |
 
 §bracket-metadata-slot Brackets are the owner's metadata modifier: the runtime
 or MCP service is the fence name, and tool input belongs in the body. A bracket
@@ -933,22 +961,16 @@ KILL admits only its one- and two-line forms for canonical log-body visibility:
 | two integers  | Whole physical lines `firstLine..lastLine`                          | Both lines are included                              |
 | four integers | Exact `startLine,startColumn,endLine,endColumn` region              | Start included, end excluded; equality is zero-width |
 
-§text-scope-semantics Exact regions use 1-based lines and Unicode code-point columns. One- and
-two-integer line selections normalize to the same exclusive-end `TextRegion`
-used by four-coordinate selections. Whole-line replacement deliberately
-accounts for newline separators; it is an ergonomic projection over exact
-replacement, not a different mimetype navigation mode. An end bound beyond
-the available content clamps to the final addressable endpoint; the start bound
-must resolve. `-1` as a line coordinate of any form is that final endpoint: the
-append point as a one-integer mutation scope, through the last line in an inclusive
-range, and the end of the content as an exact region's start or end, so `<1,1,-1,1>`
-is the whole text and `<-1,1,-1,1>` appends; as a column it is the end of its line,
-so `<3,1,3,-1>` is line 3 to its end and `<3,-1,3,-1>` appends to that line. As an unadvertised
-ingestion tolerance, the runtime accepts three integers as
-`startLine,startColumn,endLine` and immediately normalizes them to the complete
-four-coordinate region ending after the final code point of `endLine`.
-Producers never emit that form. Other arities and decimal text coordinates are
-runtime 416 failures.
+§text-scope-semantics **Exact regions use 1-based lines and Unicode code-point columns.** One- and two-integer line selections normalize to the same exclusive-end `TextRegion` used by four-coordinate selections. Whole-line replacement deliberately accounts for newline separators; it is an ergonomic projection over exact replacement, not a different mimetype navigation mode. An end bound beyond the available content clamps to the final addressable endpoint; the start bound must resolve. Other arities and decimal text coordinates are runtime 416 failures.
+
+| `-1` as | Means |
+| --- | --- |
+| A one-integer mutation scope | the append point |
+| The end of an inclusive range | through the last line |
+| An exact region's start or end line | the end of the content, so `<1,1,-1,1>` is the whole text and `<-1,1,-1,1>` appends |
+| A column | the end of its line, so `<3,1,3,-1>` is line 3 to its end and `<3,-1,3,-1>` appends to that line |
+
+An unadvertised ingestion tolerance: the runtime accepts three integers as `startLine,startColumn,endLine` and immediately normalizes them to the complete four-coordinate region ending after the final code point of `endLine`; producers never emit that form.
 
 §bare-statement **BARE requests one isolated model inference.** Its optional
 path names a prompt resource; its body supplies inline prompt text. At least
@@ -1042,6 +1064,15 @@ retrieval never returns inline within the emitting turn.
 
 ## §path-syntax 5. Target and path grammar
 
+<!-- map -->
+| Tag | Promise |
+| --- | --- |
+| {§path-query} | The serialized query component is the lossless representation. |
+| {§path-parentheses} | An unescaped depth-zero `)` closes the target slot. |
+| {§path-glob} | `PathSyntax` owns exact-path versus path-pattern classification. |
+| {§worker-name} | The exported `WORKER_NAME` contract governs names minted for URI authority slots:… |
+<!-- /map -->
+
 The target slot contains either a local path or a scheme URL. Exact addresses
 and path globs share the slot; content matchers follow the heading forms in
 {§matcher-option}.
@@ -1104,6 +1135,17 @@ ingestion restriction: the parser decomposes arbitrary URL authorities.
 
 ## §matcher-prefix-claims 6. Bulk pattern matching
 
+<!-- map -->
+| Tag | Promise |
+| --- | --- |
+| {§heading-boundary-recovery} | A column-0 heading is the trustworthy boundary. |
+| {§scope-slot-tolerance} | A line scope written inside a path slot (```` ```COPY (worker:///src.md<2,3>) ````) is read as… |
+| {§extra-path-slot} | A path slot beyond the operation's admitted operands — one for every operation, two for COPY and MOVE, any… |
+| {§matcher-refusal} | A matcher the parser cannot read refuses its operation, never the turn. |
+| {§regex-dialect-readings} | Three habits of other regex dialects are read, with one advisory each. |
+| {§pattern-body-single-line} | Every matcher is one physical line. |
+<!-- /map -->
+
 FIND, READ, KILL, EDIT, and the COPY/MOVE operands accept an optional matcher
 through the `pattern` option ({§matcher-option}). AstBuilder assigns the dialect from the
 matcher's leading characters. A leading prefix claims its dialect. Invalid
@@ -1177,6 +1219,14 @@ statements remain recoverable when their boundaries are trustworthy.
 
 ## §scope-slot 7. Scope markers
 
+<!-- map -->
+| Tag | Promise |
+| --- | --- |
+| {§text-line-anchor-syntax} | A text coordinate admits a case-sensitive line anchor spelled `@` followed by exactly five Base62 characters… |
+| {§scope-marker-forms} | Canonical producers separate components with commas and no spaces. |
+| {§scope-range-recovery} | For FIND result positions and text-coordinate operations, the parser normalizes these two-component numeric… |
+<!-- /map -->
+
 The model-facing slot is `<scope>`; the AST field is
 `lineMarker`. Numeric scopes preserve ordered components in `LineMarker`;
 text-coordinate operations use `TextLineMarker`, whose line positions may also
@@ -1269,6 +1319,16 @@ rule protects code examples in SEND, WORK, FORK, BARE and every other body.
 
 ## 9. Turn dispositions
 
+<!-- map -->
+| Tag | Promise |
+| --- | --- |
+| {§send-mid-reservation} | WAIT is reserved ({§turn-disposition}). |
+| {§disposition-anywhere} | A disposition may sit anywhere in a model turn without imposing a program boundary. |
+| {§park-202-only} | WAIT joins live work: an open stream or a live child. |
+| {§lifecycle-only-turn} | A WAIT-, SEND-, NOTE-, or KILL-only turn is valid. |
+| {§send-body} | SEND body projection |
+<!-- /map -->
+
 The runtime adjudicates each admitted turn against actual message resolutions,
 results and live obligations ({§wait-obligation-matrix}). A response with no
 operation resolves no message and creates no new observation obligation ({§empty-turn}).
@@ -1346,6 +1406,14 @@ stateDiagram-v2
 
 ## §whitespace-contract 11. Whitespace and interstatement text
 
+<!-- map -->
+| Tag | Promise |
+| --- | --- |
+| {§response-text} | The parser owns the partition between operations and response text. |
+| {§unfenced-operation} | The parser identifies ignored unfenced fragments. |
+| {§recorded-emissions} | The parser is regressed against emissions models actually produced, not fixtures we wrote. |
+<!-- /map -->
+
 Body framing removes the header line ending and the single line ending
 immediately before the closing fence. Every other body character is preserved,
 including leading/trailing blank lines, indentation, CRLF and literal
@@ -1379,23 +1447,26 @@ complete aside opens the operation instead ({§naked-operation}). A registered e
 followed by an operand slot — `gitea (list_issues)`, `sh(build.sh)` — draws the same warning under
 the executor's own spelling. Quoted blocks, offset lines and names inside a sentence draw nothing.
 
-§recorded-emissions **The parser is regressed against emissions models actually produced,
-not fixtures we wrote.** `test/fixtures/recorded-emissions.jsonl` holds one real exemplar
-of every distinct parse shape observed across the live and demo drills — the operations
-authored, whether outside text appeared, and
-the status the engine recorded at the time. A fixture encodes what we believe a model
-emits; a recording encodes what one did, so only recordings test the shapes models actually
-produce (#802, #809).
-Shape coverage, not volume, is the point — 120 exemplars are ~60 KB against ~88 MB for
-every emission ever recorded. The recorded status is **provenance, never an assertion**:
-the contract has changed under these turns and will again, so the replay asserts only that
-today's parser still reads each emission the way the corpus says it does. Regenerate with
-`scriptify/extract-emission-corpus.ts --write` after a drill; a changed shape is the
-contract moving and the diff names every shape that moved with it. The extractor also
-reports how many recorded turns concluded in a way the current contract would reject.
+§recorded-emissions **The parser is regressed against emissions models actually produced, not fixtures we wrote.** `test/fixtures/recorded-emissions.jsonl` holds one real exemplar of every distinct parse shape observed across the live and demo drills — the operations authored, whether outside text appeared, and the status the engine recorded at the time. A fixture encodes what we believe a model emits; a recording encodes what one did, so only recordings test the shapes models actually produce (#802, #809).
+
+| Fact | Rule |
+| --- | --- |
+| Shape coverage, not volume | 120 exemplars are ~60 KB against ~88 MB for every emission ever recorded |
+| The recorded status | **provenance, never an assertion**: the contract has changed under these turns and will again, so the replay asserts only that today's parser still reads each emission the way the corpus says it does |
+| Regeneration | `scriptify/extract-emission-corpus.ts --write` after a drill; a changed shape is the contract moving and the diff names every shape that moved with it; the extractor also reports how many recorded turns concluded in a way the current contract would reject |
 
 ## 12. Public API
 
+<!-- map -->
+| Tag | Promise |
+| --- | --- |
+| {§turn-shape} | `PlurnkParser.parse` accepts one model turn. |
+| {§tier-entrypoints} | Each parser entry point owns one document tier: |
+| {§runtime-neutral-root} | The package root is runtime-neutral. |
+| {§root-value-api} | The package-root runtime namespace is closed. |
+| {§parser-construction-boundary} | Parser construction components are internal rather than alternate consumer entry points: |
+<!-- /map -->
+
 The package root is the single JavaScript and TypeScript entry point for the language and wire
 contracts ({§runtime-neutral-root}). Shared AST and wire types come from generated schemas; the small hand-maintained parser
 types cover ordered parse items and `PlurnkParseError`, which JSON Schema cannot
@@ -1453,7 +1524,7 @@ among them: the parser is `@plurnk/plurnk-parser`'s ({§parser-consumers}).
 | `PathSyntax`                                        | Target-slot spelling and exact-versus-glob classification           | {§path-parentheses}, {§path-glob}         |
 | `TurnDisposition`                                   | The one turn disposition and its recognition                        | {§turn-disposition}                       |
 | `CapabilityAdmission`                               | Admission of a capability descriptor against policy layers          | {§capability-admission}                   |
-| `PLURNK_OPS`, `INTERNAL_ROW_OPS`, `PLURNK_FENCE`    | The closed operation alphabet and the language's fence              | {§canonical-statement}                    |
+| `PLURNK_OPS`, `isPlurnkOp`, `INTERNAL_ROW_OPS`, `PLURNK_FENCE` | The closed operation alphabet, its membership test, and the language's fence | {§canonical-statement} |
 | `PROPOSAL_POLICIES` | Server proposal disposition vocabulary | {§proposal-policy} |
 | `WORKER_NAME`                                       | Authority minting predicate                                         | {§worker-name}                            |
 | `UNKNOWN_POSITION`                                  | Frozen sentinel for an AST statement without retained parsed source | {§parser-position}                        |
@@ -1473,9 +1544,35 @@ than alternate consumer entry points:
 
 ## 13. Runtime-neutral wire contracts
 
-§wire-entrypoint The package root exports generated wire types, `Problems`, and
-`Validator` alongside the AST types. Their owning JSON Schemas are published
-through `@plurnk/plurnk-contracts/schema/*.json`, not re-exported as root values.
+<!-- map -->
+| Tag | Promise |
+| --- | --- |
+| {§wire-entrypoint} | The package root exports generated wire types, `Problems`, `Validator` and the value guards `isRecord`,… |
+| {§text-region} | 13.1 Text regions |
+| {§range-extent} | 13.2 Range extents |
+| {§entry-read-result} | 13.3 Client entry reads |
+| {§operation-result} | Every public PLURNK operation returns one `OperationResult`: |
+| {§diagnostic-observation} | A diagnostic says what happened, never why. |
+| {§problem-details} | `ProblemDetails` requires `type`, `title`, `status`, and `detail`; `instance` is optional until a durable… |
+| {§problem-error-carrier} | `Problems.fromError(error)` recognizes existing failure carriers without depending on a producer's exception… |
+| {§problem-projection} | `ProblemProjection` is the sole compact model-packet view of an exact `ProblemDetails`. |
+| {§notice} | A `Notice` is a transient, nonterminal observation. |
+| {§notice-directive} | A Notice's `message` states what happened ({§diagnostic-observation}). |
+| {§client-display-capabilities} | 13.7 Client display capabilities |
+| {§mcp-server-definition} | 13.8 MCP server definitions |
+| {§mcp-oauth} | `McpOAuth` is the client-managed OAuth plurnk holds for one Streamable HTTP server, included in that server's… |
+| {§application-port} | 13.9 Exterior application port |
+| {§application-worker-observation} | Worker observation exposes identity, lineage, kind and lifecycle; it is neither a client binding nor a… |
+| {§loop-lifecycle-vocabulary} | One projection maps a loop's durable status onto the lifecycle words every client renders, shared by the… |
+| {§list-excerpt} | A list shows a message by its excerpt. |
+| {§application-worker-overview} | The worker overview is the places in a scope with what waits there. |
+| {§application-loop-observation} | Loop observation exposes the durable scheduler state of work loops (excluding maintenance-only administrative… |
+<!-- /map -->
+
+§wire-entrypoint The package root exports generated wire types, `Problems`, `Validator` and
+the value guards `isRecord`, `isSafeInteger` and `errnoCode` alongside the AST types. Their owning
+JSON Schemas are published through `@plurnk/plurnk-contracts/schema/*.json`, not re-exported
+as root values.
 
 ### §text-region 13.1 Text regions
 
@@ -1529,9 +1626,9 @@ scope, or other persistence columns.
 
 | `ClientEntry` field | Contract                                                                                     |
 |---------------------|----------------------------------------------------------------------------------------------|
-| `entryId`           | Positive durable entry identifier                                                            |
+| `entryId`           | Positive durable entry identifier, or `null` for a representation core computes rather than stores |
 | `target`            | Client selector for the resolved entry, with any channel fragment removed                    |
-| `channels`          | Every channel for a full read, or exactly the selected channel for a sliced read             |
+| `channels`          | Every channel for a full read, or exactly the selected channel for a sliced read, by name; the empty name is the unnamed default channel of a scheme whose default is unnamed, a log row's |
 
 | Channel field   | Contract                                                                                                      |
 |-----------------|---------------------------------------------------------------------------------------------------------------|
@@ -1672,7 +1769,9 @@ authentication fields replace together ({§configuration-definition-resolution})
 HTTP server, included in that server's `authorization`. Interactive OAuth always requires a callback URL, and
 its structurally exclusive identity modes are an HTTPS Client ID Metadata Document URL,
 a pre-registered client ID with a symbolic secret, or neither for server-advertised
-Dynamic Client Registration. A client-credentials grant names its client ID and
+Dynamic Client Registration. Any interactive mode may name the `issuer` its sign-in binds to,
+where discovery starts, and `authorizationParams` added to the authorization request; the
+parameters the flow sets itself cannot be named. A client-credentials grant names its client ID and
 symbolic secret, optionally binding an issuer. Every secret is one complete `${NAME}`
 reference to the operator environment; `Validator.assertMcpOAuth` validates the shape.
 
@@ -1723,28 +1822,40 @@ each reply's `answers` addresses (empty for incoming messages).
 `resolveClientInteraction` may carry the accepted answer's message evidence;
 Core validates the resolution, retains the arrival, then resumes the operation.
 
-§application-worker-observation Worker observation exposes durable identity,
-origin, immediate parent identity, minted `kind` (`root` for a worker with no parent; `fork` for a
-child carrying a fork boundary; `work` for any other child), and `lifecycle`,
-the worker's representative work loop projected through {§loop-lifecycle-vocabulary} (`idle`
-when it has none). `selectWorkerLoop` chooses running before parked before queued;
-ties select the oldest unresolved sequence. With no live work, the latest terminal
-settlement wins (sequence breaks equal timestamps). Newer terminal history never
-hides unfinished work. Maintenance-only loops do not change this projection;
-their ordinary turns and results remain durable history. `readWorker` resolves exactly one id or name and returns
-`null` when absent. `listWorkers` filters collections by origin or lineage
-position; an omitted parent filter means every position and an explicit `null`
-means roots. Singular and plural cardinalities are distinct contracts.
-Observation is not a client binding or permission grant; a client renders kind
-and lifecycle, it never infers them.
+§application-worker-observation **Worker observation exposes identity, lineage, kind and lifecycle; it is neither a client binding nor a permission grant.** It exposes durable identity, origin, immediate parent identity, minted `kind` (`root` for a worker with no parent; `fork` for a child carrying a fork boundary; `work` for any other child), and `lifecycle`, the worker's representative work loop projected through {§loop-lifecycle-vocabulary} (`idle` when it has none), and `hidden_at`, when the worker was hidden ({§place-hiding}), null while it is shown. A client renders kind and lifecycle, it never infers them.
+
+| Fact | Rule |
+| --- | --- |
+| `selectWorkerLoop` | chooses running before parked before queued; ties select the oldest unresolved sequence; with no live work, the latest terminal settlement wins (sequence breaks equal timestamps); newer terminal history never hides unfinished work; maintenance-only loops do not change this projection, and their ordinary turns and results remain durable history |
+| `readWorker` | resolves exactly one id or name and returns `null` when absent |
+| `listWorkers` | filters collections by origin, lineage position or mark; an omitted parent filter means every position and an explicit `null` means roots; an omitted `hidden` means shown and hidden workers alike; singular and plural cardinalities are distinct contracts |
 
 §loop-lifecycle-vocabulary One projection maps a loop's durable status onto the
 lifecycle words every client renders, shared by the status gauge and the worker
-directory: no loop `idle`; 100 `queued`; 102 `running`; 202 `parked`; 200
-`completed`; any status of 400 or more `failed` (413 budget, 429 turn ceiling,
-499 cancel, 500 fail, 504 execution timeout, 508 runaway). `lifecycleOfLoopStatus`
+directory: no loop `idle`; 100 `queued`; 102 `running`; 202 `parked`; any other status is a
+concluded loop's: below 400 `completed`; 499 `cancelled`, a loop stopped without failing
+({§agui-run-outcome}); any other of 400 or more `failed` (413 budget, 429 turn ceiling, 500 fail,
+504 execution timeout, 508 runaway). `lifecycleOfLoopStatus`
 in `@plurnk/plurnk-contracts` is that projection's one owner.
 
+§list-excerpt **A list shows a message by its excerpt.** The excerpt is the message's first line holding anything but
+blanks (spaces, tabs and line ends), cut to at most N characters, a character never cut in two, with blanks trimmed from
+its end; `continued` says whether anything but blanks follows. `excerptOf` in `@plurnk/plurnk-contracts` is that rule's one
+owner, for a loop's opening in a worker's loop list ({§agui-worker-loops}) and a worker's latest finished reply
+({§worker-finished-reply}).
+
+§application-worker-overview **The worker overview is the places in a scope with what waits there.** A place is a
+model-origin worker; bookkeeping workers are not places. The scope is the daemon or one workspace; hidden places are out
+of it ({§place-hiding}).
+
+| Fact | Rule |
+| --- | --- |
+| A place | `{ workspaceId, id, name, parentWorkerId, kind, lifecycle, gates, reply }`: `kind` and `lifecycle` as {§application-worker-observation} projects them, `gates` the proposals and client interactions it waits on as `pendingProposals` and `pendingClientInteractions` project them, `reply` its latest finished reply or `null` |
+| A reply | `{ id, coordinate, completion, at, excerpt, continued }`: its durable log row, `L/T/S` in its worker's log, the completion its receipt records, when it was recorded (Unix milliseconds) and its excerpt ({§list-excerpt}) |
+| Order | most recently finished first, by reply row (the log's commit order, so two replies never tie), then the places with no reply, newest first |
+| Bound | every place waiting on a gate, then the first `limit` in that order; `omitted` counts the places in scope it leaves out, so no place is left out silently |
+| Workspaces | `{ id, name, projectRoot, projectLabel }` for each workspace a held place belongs to ({§workspace-label}) |
+
 §application-loop-observation Loop observation exposes the durable scheduler
 state of work loops (excluding maintenance-only administrative loops), nullable
 `waitUntil` (the durable observation deadline in Unix milliseconds), the times a loop first
@@ -1759,6 +1870,30 @@ events or persistence; events remain the live notification edge.
 
 ## 14. Parse diagnostics
 
+<!-- map -->
+| Tag | Promise |
+| --- | --- |
+| {§parse-diagnostics} | `PlurnkParseError` is a JSON-serializable Error subclass. |
+| {§parse-admission} | A diagnostic's severity does not describe whether an operation ran. |
+| {§parse-recovery} | Every hard diagnostic carries its working form. |
+| {§parser-position} | Parser source locations are points, not text regions. |
+| {§inline-flag-tolerance} | PCRE inline modifiers. |
+| {§regex-trailing-text} | A valid `/pattern/flags` prefix followed by horizontal whitespace and trailing text receives one concise… |
+| {§regex-sed-range} | A sed line range is named as one. |
+| {§unclosed-regex} | A regex that never closes. |
+| {§naked-pattern} | The matcher rides the heading bare. |
+| {§trailing-slots} | Slots after the matcher peel off the right. |
+| {§log-heading-notation} | The log's heading notation, copied as syntax, is read as the slot it stands for. |
+| {§bare-target} | A target written without its parentheses is refused with the line that runs. |
+| {§bare-anchor-scope} | An EDIT's anchor without its angle brackets is its scope. |
+| {§matcher-body-redirect} | Unread selector text. |
+| {§combined-anchor-tolerance} | Combined line number and anchor in a scope. |
+| {§invalid-scope-diagnostic} | Malformed scope content. |
+| {§error-shape} | The diagnostic class determines the parts of a message; every class says what happened, never why… |
+| {§parse-attempt} | A hard fact that refused a statement the parser opened carries its `attempt`: the statement's text exactly as… |
+| {§unparsed-tail-boundary} | When the lexer cannot determine where a malformed statement ends — an unfinished `(target` or `[metadata`… |
+<!-- /map -->
+
 §parse-diagnostics `PlurnkParseError` is a JSON-serializable Error subclass.
 Its `message` contains only the parser-owned diagnostic; position, source, and
 severity remain separate facts.
@@ -1864,49 +1999,24 @@ diagnostics are:
   it has no pattern to read and is refused as `invalid-operation-syntax` naming what
   is missing. A matcher with a second unescaped `/` is not unclosed: it is
   `/pattern/flags`, and invalid flags keep their native failure with the escape hint.
-- §naked-pattern **The matcher rides the heading bare.** After the path, and any
-  scope or option block, the rest of a FIND, READ or KILL heading line is the
-  matcher, in whichever dialect its first characters claim
-  ({§matcher-prefix-claims}): `/re/i`, `^anchored`, `//xpath`, `$.json`, `~words`,
-  `&symbol`, or a sigil-less glob or literal such as `TODO` or `*.ts`. One
-  spelling is not a matcher: `#name` alone, a `#` followed by one channel token
-  and nothing else, after a target that names no channel, is that target's
-  channel exactly as if written on the path ({§local-path-fragment}); a target
-  that already names a channel keeps such a token as its pattern. Those
-  matchers remain independent of owner options: a block without `pattern` never
-  erases the heading matcher, and invalid blocks still reach the owning validator.
-  Their heading-line text owns selection independently of annotation or distillation bodies. On EDIT only
-  a sigil lifts, because plain heading-line text is the replacement body it always
-  was; the lines beneath the heading are then the replacement, and none deletes each
-  match ({§edit-pattern}). A trailing `<!-- aside -->` on the same line stays the
-  aside. The lift is exactly what `[{"pattern": "…"}]` produces, and that option
-  remains the escape for a matcher the heading cannot hold bare: one opening with
-  `(`, `<`, `[` or a backtick, one containing `<!--`, and every COPY/MOVE operand.
-  `FIND (src/parser.ts) /\bparse\w+\b/` is the same operation as
-  `FIND (src/parser.ts) [{"pattern": "/\\bparse\\w+\\b/"}]`. `^` claims the regex
-  dialect without slashes or flags: the whole text is the pattern, so
-  `READ (notes.md) ^Decision:.*` selects lines beginning with `Decision:`.
-  `^` is deliberately absent from `plurnk.md`'s dialect table: a model writes the anchor
-  whether or not it is taught, so the engine honours it without spending hot-path teaching
-  on it. The omission is not drift between the teaching and the engine.
-- §trailing-slots **Slots after the matcher peel off the right.** The heading text after
-  the matcher is read backwards: a trailing `<!-- aside -->`, a trailing `<scope>` in the
-  shapes the lexer admits (result positions on FIND, text coordinates elsewhere) and a
-  trailing `[option block]` that parses as an array of objects come off the right end in
-  any order, each taken once and only when the heading did not already carry that slot,
-  until what remains is the matcher. `READ (a.rs) /fn resolve_/ <1,-1> <!-- entities -->`
-  is the same operation as `READ (a.rs) <1,-1> /fn resolve_/ <!-- entities -->`, with
-  one warning-severity advisory naming the canonical order for the scope or block:
-  recovery requires a single possible path-slot owner. With multiple slots, a trailing scope
-  or metadata block refuses the heading rather than relocating or discarding the slot.
-  A matcher that
-  itself ends in one of those shapes takes the option escape.
-  `plurnk.md` teaches one order — `OP (path)? <scope|range>? [metadata]? pattern?
-  <!-- aside -->?` — and free ordering is not taught. Small departure, small
-  reinterpretation ({§outside-text}): every slot the model wrote is present and
-  unambiguous, so only their sequence differs from the taught form, and nothing is
-  invented to read it. The advisory names the canonical order rather than refusing,
-  because the operation the model meant is never in doubt.
+- §naked-pattern **The matcher rides the heading bare.** After the path, and any scope or option block, the rest of a FIND, READ or KILL heading line is the matcher, in whichever dialect its first characters claim ({§matcher-prefix-claims}): `/re/i`, `^anchored`, `//xpath`, `$.json`, `~words`, `&symbol`, or a sigil-less glob or literal such as `TODO` or `*.ts`. `FIND (src/parser.ts) /\bparse\w+\b/` is the same operation as `FIND (src/parser.ts) [{"pattern": "/\\bparse\\w+\\b/"}]`: the lift is exactly what `[{"pattern": "…"}]` produces, and that option remains the escape for a matcher the heading cannot hold bare — one opening with `(`, `<`, `[` or a backtick, one containing `<!--`, and every COPY/MOVE operand.
+
+  | Fact | Rule |
+  | --- | --- |
+  | Not a matcher | `#name` alone, a `#` followed by one channel token and nothing else, after a target that names no channel, is that target's channel exactly as if written on the path ({§local-path-fragment}); a target that already names a channel keeps such a token as its pattern |
+  | Independence | heading matchers remain independent of owner options: a block without `pattern` never erases the heading matcher, and invalid blocks still reach the owning validator; their heading-line text owns selection independently of annotation or distillation bodies |
+  | EDIT | only a sigil lifts, because plain heading-line text is the replacement body it always was; the lines beneath the heading are then the replacement, and none deletes each match ({§edit-pattern}) |
+  | The aside | a trailing `<!-- aside -->` on the same line stays the aside |
+  | `^` | claims the regex dialect without slashes or flags: the whole text is the pattern, so `READ (notes.md) ^Decision:.*` selects lines beginning with `Decision:`; `^` is deliberately absent from `plurnk.md`'s dialect table — a model writes the anchor whether or not it is taught, so the engine honours it without spending hot-path teaching on it, and the omission is not drift between the teaching and the engine |
+
+- §trailing-slots **Slots after the matcher peel off the right.** The heading text after the matcher is read backwards: a trailing `<!-- aside -->`, a trailing `<scope>` in the shapes the lexer admits (result positions on FIND, text coordinates elsewhere) and a trailing `[option block]` that parses as an array of objects come off the right end in any order, each taken once and only when the heading did not already carry that slot, until what remains is the matcher. `READ (a.rs) /fn resolve_/ <1,-1> <!-- entities -->` is the same operation as `READ (a.rs) <1,-1> /fn resolve_/ <!-- entities -->`, with one warning-severity advisory naming the canonical order for the scope or block.
+
+  | Fact | Rule |
+  | --- | --- |
+  | Recovery | requires a single possible path-slot owner: with multiple slots, a trailing scope or metadata block refuses the heading rather than relocating or discarding the slot |
+  | A matcher that itself ends in one of those shapes | takes the option escape |
+  | Teaching | `plurnk.md` teaches one order — `OP (path)? <scope\|range>? [metadata]? pattern? <!-- aside -->?` — and free ordering is not taught; small departure, small reinterpretation ({§outside-text}): every slot the model wrote is present and unambiguous, so only their sequence differs from the taught form, and nothing is invented to read it; the advisory names the canonical order rather than refusing, because the operation the model meant is never in doubt |
+
 - §log-heading-notation **The log's heading notation, copied as syntax, is read as the slot it
   stands for.** A packet's log row heading is `### log:///L/T/S/OP → path pattern · N`
   ({§log-wire-format} in the core SPEC); models copy its notation onto their own headings. Each