@plurnk/plurnk-contracts 1.21.1 → 1.23.0

package/SPEC.md

@@ -11,7 +11,7 @@ runtime-neutral wire envelopes; `@plurnk/plurnk-parser` implements the language
 | ------------------------------------------------------------------------------- | --------------------------------------------------- |
 | AST, validators, Problems, results, Notices, text regions and extents          | `@plurnk/plurnk-contracts`                          |
 | Capability and loop policies                                                    | `CapabilityPolicy`, `LoopPolicy`, `LoopPolicyRequest`, `PROPOSAL_POLICIES` |
-| Durable reasoning intent                                                        | `ReasoningPolicy`, `REASONING_POLICIES`             |
+| Durable effort                                                                  | `Effort`, `EFFORTS`             |
 | Model route and catalog discovery                                               | `ModelRoute`, `ModelCatalogQuery`, `ModelCatalogPage`, `ModelReadiness` |
 | Stopped-world client contract                                                   | `ProposalDisposition`, `ProposalProjection`         |
 | Client-owned interaction contract                                               | `ClientInteractionRequest`, `ClientInteractionProjection`, `ClientInteractionResolution` |
@@ -177,7 +177,7 @@ Contracts hold no default for the rest: the daemon's panel supplies it
 vocabulary of `proposals`. Capability admission precedes effect
 classification and proposal settlement.
 
-§reasoning-policy-wire `ReasoningPolicy` is exactly `off | adaptive | low |
+§effort-wire `Effort` is exactly `off | adaptive | low |
 medium | high`. The schema owns this shared wire vocabulary. Providers own the
 supported subset and native projection for a selected route; core owns the
 durable worker value.
@@ -190,8 +190,8 @@ physical limits, capabilities, and local `ModelReadiness`. A readiness cause
 contains alternative environment-variable sets—every name within a set is
 required and any set may satisfy the cause. It carries names only, never values,
 and asserts neither credential validity nor endpoint reachability.
-`capabilities.reasoningPolicies` lists the route's admitted members of
-{§reasoning-policy-wire}, including supported activation policies; clients do
+`capabilities.efforts` lists the route's admitted members of
+{§effort-wire}, including supported activation policies; clients do
 not infer fixed efforts from the `reasoning` capability bit. It is not a
 worker's model/spawn intersection or an alias-specific tuning projection.
 
@@ -273,26 +273,21 @@ convention and never demanded ({§fence-closer}, {§closer-fallback}). There are
 operation suffixes or heading levels. Complete nested matches take precedence
 over local recovery ({§balanced-fences}).
 
-§fence-closer A block opened with N backticks closes at the first unclaimed line made of
-at least N backticks and nothing else but horizontal whitespace, within three spaces of
-its line start ({§indented-fences}). Count follows CommonMark: a shorter fence inside the
-body is body; an equal or longer bare fence closes the block unless {§balanced-fences}
-claims it for a nested block. The compact one-line form closes on its heading line after
-the modifiers under the same rule.
+§fence-closer A block opened with N backticks closes at a line made of at least N backticks and
+nothing else but horizontal whitespace, within three spaces of its line start
+({§indented-fences}). Count follows CommonMark: a shorter fence inside the body is body; an equal
+or longer bare fence may close the block or open a nested one, and {§fence-pairing} decides
+which. The compact one-line form closes on its heading line after the modifiers under the same
+rule.
 
 §balanced-fences A complete nested interpretation takes precedence over missing-closer
-recovery. Within a body, line-leading labeled fences open literal blocks. A bare fence
-closes the innermost open block of exactly its width, otherwise the outermost open block
-narrower than it; the narrower blocks it steps over are literal body, and a wider or
-differently fenced block inside stops it. So a wider outer fence holds any narrower body,
-finished or not, and equal widths nest when every inner block closes. The enclosing block
-and its nested blocks must all
-close under {§fence-closer}; equal opener/closer totals alone are insufficient, and a
-complete inline block is already closed. Preserve every nested body byte, including
-apparent OPs and known executors, without dispatching them. If no complete enclosing
-interpretation exists, retain {§fence-heading-in-body} and {§closer-fallback}. These
-rules apply equally to model programs, stored programs, client operations, and
-reasoning quotations.
+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
+({§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
+and known executors, without dispatching them. These rules apply equally to model programs,
+stored programs, client operations, and reasoning quotations.
 
 §operation-fences **Accept three or more backticks; teach and render three.** A line-start fence
 of three or more backticks naming a native operation or registered executor opens that
@@ -311,48 +306,176 @@ horizontal whitespace after it, opens that operation as if it were fenced with t
 backticks: no target, no modifiers, and a body that 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}). It runs, and one warning-severity receipt follows its statement —
+back ({§closer-fallback}). A naked `KILL` alone holds every fence inside it as text ({§naked-kill}). It runs, and one warning-severity receipt follows its statement —
 `` `KILL` 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. Only the bare name qualifies; a name with anything else on its line is
+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 `KILL`, then the answer, then a closing fence delivers
+the answer alone. Only the bare name qualifies; a name with anything else on its line is
 the unfenced form and still refuses ({§unfenced-operation}), executors are runtimes rather than
-operations, and reasoning is never read this way. Measured before it was accepted (2026-09-22):
-48 naked `KILL` lines in 9,196 recorded emissions, every one followed by the deliverable, and
-three loops lost to the refusal at the strike threshold.
+operations, and reasoning is never read this way. In 9,196 recorded emissions, all 48 naked
+`KILL` lines were followed by the deliverable.
 
 §fence-heading-in-body Outside a complete nested block ({§balanced-fences}), a fence
 line of three or more backticks and a name that is a native operation or a known executor
-is a heading. Inside an open block of any width it ends that block without closing it
-({§closer-fallback}) and opens the next statement: a wider fence holds the narrower headings
-inside it only while it closes ({§balanced-fences}). Fence lines of fewer than three
-backticks are never headings ({§operation-fences}). Known executors are `sh` plus what
-the host names in `ParseOptions.executors`. Consequences: a closer glued to the next opener
-(six backticks then `READ`) can never swallow an unbalanced turn, and no unclosed block, however
-wide, swallows the operations after it.
-
-§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 cut back to its last bare fence line (any count, within
-three spaces of its line start), which is the closer the author meant, and one terminating line
-ending goes with it; when no bare fence line exists the body is the whole span less
-one terminating line ending. This carries no diagnostic: a missing closer is never
-an admission failure, and {§unparsed-tail-boundary} is not involved.
+is a heading. Inside an open block it either ends that block without closing it and opens the
+next statement, or it is a literal example held by the block; the block holds it only while
+the block ends at a real closer, and {§fence-pairing} chooses between the two. Fence lines of
+fewer than three backticks are never headings ({§operation-fences}). Known executors are `sh`
+plus what the host names in `ParseOptions.executors`. Inside a parameterless `KILL` a
+heading never ends the block ({§terminal-kill}).
+
+§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 span less one terminating line ending. Where a same-character fence
+narrower than an outermost block stands where its closer belongs, {§fence-pairing} may read it
+as that closer, at the cost of one repair; an unclosed EDIT yields to the native heading after it
+({§unclosed-mutation-yields}). This carries no diagnostic: a missing closer is
+never an admission failure, and {§unparsed-tail-boundary} is not involved.
 
 `plurnk.md` shows every operation closed; this recovery is not taught. It sits at the quiet end of
-the scale {§response-text-note} describes: the model opened the operation correctly
+the scale {§outside-text} describes: the model opened the operation correctly
 and only failed to close it, so the harness reads what it plainly meant and says nothing.
 A departure that small earns no correction — telling a model its closer was missing costs
 a sentence in every future packet to fix something already fixed.
 
-§fence-boundary Balanced nesting is resolved before local recovery. Otherwise,
-fences are read by count, except for the heading rule above:
+§fence-boundary Every fence line inside a body takes one of these meanings, chosen for the whole
+input at once by {§fence-pairing}:
 
 | Fence encountered inside a body | Meaning |
 |---|---|
-| Part of a complete nested block | Literal body, including its openers and closers |
 | Indented four spaces or more, or by a tab | Body ({§indented-fences}) |
-| Fewer backticks than the block's own | Body |
-| At least the block's backticks, bare | The block's closer |
-| Three or more backticks naming a native operation or known executor | A heading: ends the block, opens the next statement |
+| Fewer backticks than the block's own, or another character | Body, or the opener of a nested block |
+| At least the block's backticks, bare | The block's closer, or the opener of a nested block |
+| Labeled, naming nothing known | The opener of a nested block, or body |
+| Three or more backticks naming a native operation or known executor | A heading that ends the block, or a literal example |
+
+### §fence-pairing Fence pairing
+
+A whole-input pass, `FencePairing`, decides where every block ends before the lexer reads a
+token; the lexer's semantic predicates consult its decision, and ANTLR keeps framing, slots and
+statement composition ({§parser-architecture}). The pass is a least-cost parse of the fence
+lines as a bracket language, in the manner of Aho and Peterson's least-errors parser
+(SIAM J. Comput. 1(4), 1972): every reading of the fences is a derivation, and the pass returns
+the cheapest.
+
+§pairing-need **Why a pass ahead of the grammar.** Whether a bare fence closes a block or opens a
+nested one depends on every fence after it, unboundedly. Measured on 10,486 distinct recorded
+emissions:
+
+| Alternative | Result |
+|---|---|
+| The fence structure as an ANTLR grammar under SLL prediction | 10,000 accepted, 0.2 ms mean; 486 not: 119 valid only under full LL, 243 needing repair, 113 unrepairable |
+| The same grammar under full LL | A 267 KB packet echo took 4.8 s. Full-context results are not cached: the runtime records that caching them "was slower than interpreting and much more complicated" (`ParserATNSimulator`) |
+| ANTLR's error recovery for the 356 that need repair | `DefaultErrorStrategy` repairs only at the point of detection, by single-token insertion or deletion; it has no least-cost repair over the input |
+| Nongreedy lexer loops | A lexer decision is local, not "globally correct" (ANTLR `doc/wildcard.md`), so a nongreedy body ends at the first closer even when a later one is the block's |
+| CommonMark's rule alone | The first closer of sufficient width closes (CommonMark 0.31.2 §4.5), and CommonMark declines to backtrack because it "would require backtracking… much less efficient". It cuts 110 recorded bodies at an inner bare block |
+| A budgeted depth-first search over stacks | Exhausted its step budget on 20 recorded emissions of 188 to 3,501 fence lines |
+
+The ALL(*) paper (Parr, Harwell, Fisher, OOPSLA 2014) states the limits relied on here: SLL either
+behaves like LL or reports an error (Theorem 6.5, §3.2), and an ambiguity resolves to the lowest
+alternative (§4.2), so neither mode chooses among complete readings by cost. The grammars-v4
+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-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 |
+| 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 (FIND, READ, COPY, MOVE, 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 |
+| 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}.
+
+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
+heading. An operation example quoted in a body of its own width therefore reads as the body
+closing and the example running; the wider outer fence or the tab offset quotes it
+({§operation-fences}).
+
+§terminal-kill **A KILL body is the deliverable.** Inside a parameterless `KILL`, at any depth, a
+heading is a literal example or text and never ends the block; the block ends at its closer or
+the end of the input. Of 796 recorded parameterless KILLs, 9 were followed by any other
+operation, while 62 of 120 SENDs were, so the rule is KILL's alone. It keeps a final report whole
+and never runs a command the report only shows.
+
+§prose-code-blocks **A message or a prompt shows code.** Inside a `SEND`, `WORK`, `FORK` or `BARE`
+body, at any depth, a heading that names an executor (` ```sh `, ` ```python3 `) is a code block the
+text shows, exactly as under {§terminal-kill}: it never ends the block and never runs. A native
+operation's heading still ends such a block, since a message is often followed by the author's next
+operation. In the distinct recorded benchmark emissions an executor heading ended an unclosed
+`WORK` body 14 times, a `BARE` body 9 times and a `SEND` body twice; every one inspected (qflash
+run218, run114 and run118, deepdumb run44) was the child's task, the prompt's code or code quoted in
+a report, and reading it as an operation truncated the task and ran the example in the parent.
+
+§message-run-on **A message runs to the end of the turn.** A parameterless `KILL`, or a `SEND`,
+`WORK`, `FORK` or `BARE`, whose block reaches the end of the input without its closer takes it
+there with no repair: the text after its last inner block is still the deliverable, the message
+or the task, never outside text. The run counts as a supplied closer, so a reading that closes at
+a real fence still wins, and it never costs an operation: when the reading that runs on hides more
+operations the author wrote than the best repaired reading, the repaired reading stands. Across the
+11,235 distinct recorded benchmark emissions this changes 26 readings: bodies that had ended at an
+inner fence keep what followed it (the qflash run192, run90 and run210 deliverables regain their last
+sections), one echoed transcript (glm run155) runs one more operation, and none loses one.
+
+§naked-kill **A naked KILL is the whole rest of the turn.** A parameterless `KILL` opened by its
+name alone ({§naked-operation}) is a completion, and nothing can follow a completion: every fenced
+block inside it, a native operation heading included, is text the deliverable shows, exactly as
+inside a fenced KILL ({§terminal-kill}), and the block ends only at its name alone on a line or at
+the end of the input. No operation the deliverable shows runs. In the rtx5070 demo
+`demo-show-dont-run-sJU8zO` the model, asked to show a deletion without doing it, answered with a
+naked `KILL` whose deliverable quoted ```` ```KILL (notes.md) ````; read as a heading that ended
+the deliverable, the quoted KILL ran and deleted the file. The fenced form of the same answer had
+already read as quotation; this rule makes the two forms one.
+
+§pairing-witness **Witnesses.**
+
+| Witness | Result |
+|---|---|
+| Every input up to six lines over eleven line shapes, against a forward exhaustive search over explicit stacks under the same moves and class orders | 1,948,716 inputs, 0 differences in chosen cost; the same harness reports 37 differences at four lines when a summary keeps one entry per end regardless of class |
+| The generated matrix: six operations × widths 3–5 × twelve body shapes × four tails | 864 of 864 (`fence-matrix.test.ts`); the four `EDIT · outer 3 · labeled quoted operation` cells read the example as an operation ({§unclosed-mutation-yields}), and in the `next operation` cell the EDIT's written closer, now a stray top-level fence, quotes the operation after it ({§quotation}) |
+| 10,486 recorded emissions | All parse; 0.9 ms mean, 267 ms at most (3,501 fence lines). The work is polynomial in fence lines, cubic at worst, so no step bound is needed |
+| The same, against the single-order objective | 10,466 identical; 19 read more operations, where headings follow unclosed blocks or a closer is glued to the next opener; 1 echoed transcript reads a different operation; none reads fewer |
 
 §indented-fences **CommonMark's indentation, everywhere.** A fence line may follow at most three
 spaces; four or more, or a tab, make it indented code. That one rule reads every fence purpose the
@@ -360,9 +483,8 @@ same way: an opener within three spaces opens, a closer within three closes, a h
 three ends an unclosed block, and a body keeps its own lines' indentation. A fence indented
 further is literal wherever it stands — prose outside a block, body inside one — and draws no
 advisory: `plurnk.md` shows its own examples offset, so an offset fence is the page's own form
-and there is no mistake to report (operator, 2026-09-21). The parser presumes nothing about why a fence is offset. This one
-rule replaces the column-zero opener (operator, 2026-09-18) and the lenient closer beside it
-(operator, 2026-09-23). Outside an operation, offset text is response text under
+and there is no mistake to report. The parser presumes nothing about why a fence is offset.
+Outside an operation, offset text is response text under
 {§response-text}; inside a body, it stays literal body content.
 
 §inline-chain A closer on a heading line, or on a body's closing line, may be
@@ -380,15 +502,13 @@ The closer is still a closer: the block ends with that physical line and never r
 the next operation, which is what a bare heading carrying a matcher would do. A closer followed
 by the next opener is {§inline-chain}, and by nothing is the ordinary {§fence-closer}. There is
 no ambiguity to resolve: a slot begins with `<` or `[` and an opener with a backtick run, so the
-shapes are disjoint (operator, 2026-09-13: "If there is no risk of ambiguity, then we add
-tolerance. Turning model soup into operations instead of errors is a cardinal imperative").
+shapes are disjoint.
 
 §executor-case **An executor tag in any case.** A fence tag that matches a
 registered executor's name case-insensitively opens that executor (`SH` opens
 `sh`), and the statement's `executor` is the registered spelling, so a lookup
 by that name never misses. Operation names stay uppercase by teaching and were
-never written otherwise in 12,000 fences; one `SH` in 1,300 `sh` fences was
-(2026-09-13 census). An unregistered name without an accepted spelling
+never written otherwise in 12,000 fences; one `SH` in 1,300 `sh` fences was. An unregistered name without an accepted spelling
 ({§executor-js-spelling}) is still prose ({§interstitial-fence}).
 
 §executor-js-spelling When `node` is registered and `js` is not, `js` names
@@ -419,12 +539,22 @@ nothing registered — opens a
 quotation that runs to its matching closer (same character, width at least the opener's) or to
 the end of the input. Everything inside is data: no operation runs there and native tool-call
 markup is not read ({§native-tool-calls}). An operation fenced inside an unlabeled code block
-draws one warning that it was shown, not run. An unlabeled fence whose first line is an operation
-heading is the operation with its tag forgotten, and draws one warning — `` `READ` inside an
-unlabeled fence did not run; the tag is the operation. `` — a native name alone or with a slot, an
-executor's name with its operand (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 the fence itself draws nothing). A labeled
-block is an example by declaration, and nothing else inside draws an advisory.
+draws one warning that it was shown, not run. At the top level, a bare fence whose next line is an
+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. With the answer carried by the final KILL,
+whose body shows and never runs ({§terminal-kill}), an example the model means only to show lives
+in a body.
 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
@@ -439,17 +569,16 @@ response text under {§response-text}, not an executable program or a completion
 example, and shows its own examples offset; the other quoting fences are untaught: a tilde
 fence, an unlabeled fence and an unknown tag all quote. Each is a shape a model reaches for from ordinary Markdown rather than from this
 teaching, so honouring it protects an example the model already believed was safe
-({§response-text-note} places the scale). The offset is the one form that survives every
+({§outside-text} places the scale). The offset is the one form that survives every
 fence style.
 
-§interstitial-fence Superseded by {§quotation}: an unlabeled fence no longer opens nothing, it
-quotes. (It in turn replaced the retired unlabeled-fence SEND of the fences chapter, whose
-unlabeled fences turned displaced headings into silent messages.)
+§interstitial-fence Only a native operation or a known executor opens a block. A fence naming
+anything else, or nothing at all, opens no operation: outside a block it quotes under
+{§quotation}, inside a body it is body.
 
 §closer-aside A closing fence followed on its line by one aside and nothing else
 is the closer; the aside is outside text. Read as body, that line would be written
-into the edited resource (#758: a recorded EDIT deleting a line wrote
-```` ```` <!-- remove duplicated Result import --> ```` into a Python file). A
+into the edited resource (#758). A
 closing fence followed by any other text is still body.
 
 §heading-slot-order A heading near-miss with exactly one reading is read as that
@@ -480,9 +609,42 @@ the aside, and `body`/`content`/`command`/`text`/`input` or plain text inside th
 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.
-A call with an unknown name or parameter leaves the whole emission as it was. An
-emission that already yields an operation is never rewritten. No diagnostic, notice
-or teaching mentions the reading (#760).
+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.
+Of 69 distinct recorded emissions carrying DSML markup (the 11,500 distinct emissions recorded
+through run429), 60 read this way and 9 draw the {§native-tool-call-receipt}: a bare
+`<｜｜DSML｜｜ calls>` with nothing inside, and calls whose native operation carries a parameter
+plurnk has no slot for.
+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-call-receipt **Markup that was not read is named.** When an emission yields no
+operation and carries native tool-call markup that could not be read, the parse reports one
+hard diagnostic at the markup, naming it and the fenced form that runs — `` `<tool_call>` is
+tool-call markup, which plurnk does not run, so nothing ran. An operation is a fenced block:
+three backticks and `READ (django/forms/widgets.py)` on the opening line. `` The form names
+the operation and target the markup itself names where it names them (`sh` for a shell
+command, `NOTE` for a note or narration), and otherwise the generic "the operation with its target,
+such as `READ (path)`". The model believes it
+acted; silence would let it wait on a result that never comes. Of 107 distinct recorded
+no-operation qflash emissions carrying call-like markup, 63 read under {§native-tool-calls}, 42 draw
+this receipt, and 2, a bare JSON object of narration with no tool-call marker, draw neither.
 
 §empty-section Both the compact bodyless form and an empty multiline block
 normalize optional bodies to null. Closing fences are conventional, never required
@@ -519,19 +681,35 @@ has at most one scope; its metadata blocks retain their authored order.
 optional target and ignores syntactically valid scope and metadata without diagnostics
 ({§send-wait-scope}). Their literal bodies begin below the header.
 
+§scope-on-scopeless **A scope on an operation that takes none is dropped, and named.** WORK, FORK,
+BARE and NOTE take no scope, and neither does a SEND without a recipient; a `<…>` slot on such a
+heading, in any position, is skipped and the operation runs, with one warning-severity advisory
+naming the operation's slots and the dropped scope — `` `WORK` takes a target only; the scope
+`<1,-1>` was ignored. A scope selects lines in READ, EDIT and KILL. `` (`` `NOTE` takes no target or
+scope; … ``, `` `SEND` without a recipient takes no scope; … ``). An aside is never a scope, a
+recipient SEND keeps its scope for the recipient ({§send-directed-scope}), and WAIT's is skipped
+unread ({§send-wait-scope}). There is no ambiguity: the operation has one reading with or without
+the slot. Before this, the heading drew the grammar's expected-token diagnostic and the turn was
+dead; in the distinct recorded emissions one heading carried the form (zai run426,
+```` ```WORK (worker://deprecation-implementer) <1,-1> ````), beside two recipient SENDs whose scope
+the recipient refuses at runtime.
+
 §heading-inline-body Nonempty body text belongs below the fence header.
 The ingester tolerates body text after horizontal whitespace on the header,
 preserves it, and emits one warning stating that normalization. This does not
 change the meaning of a compact empty block or permit unmatched fences.
 
-§bare-option-object A bare option object is the option block. On an
-operation that takes an option block and no bare matcher — SEND, BARE, WORK,
-FORK and every executor fence — heading text after the slots that is exactly
-one JSON object `{…}` is read as `[{…}]`: the AST carries the array form, the
-written heading renders it, every consumer sees the taught shape, 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 `[{…}]`." A heading that already carries a block keeps the object as
+§bare-option-object A bare option object is the option block, where the house option array owns the
+block. On an operation that takes an option block and no bare matcher — SEND, BARE, WORK, FORK and
+every executor fence — heading text after the slots that is exactly one JSON object `{…}` 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 `[{…}]`." The option array is a house
+convention, not a language rule ({§scheme-metadata-modifier}): an executor whose declared body is
+JSON ({§executor-invocation}), an MCP tool, reads the object as its body instead — its arguments,
+written on the heading line — with one warning: "`gitea` took its body on the heading line; the
+body belongs on the lines below it." The host names those executors to the parse
+(`ParseOptions.jsonBodyExecutors`). 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 naming the option form ("`{…}`
@@ -731,9 +909,9 @@ accounting, and observation timing belong to the consuming service.
 §read-find-normalization An authored READ is never rewritten into a FIND. A
 glob target on READ keeps its glob, and the runtime fans it out into one exact
 READ per matching path, with the authored scope and matcher ({§read-fan-out}
-in the core SPEC; operator, 2026-09-13: "give it what it asked for" — a model
+in the core SPEC). A model
 that asks to read every file under a glob gets those files, bounded by the
-FIND page and the preview scope, not a catalog it did not ask for). A matcher
+FIND page and the preview scope, not a catalog it did not ask for. A matcher
 never changes the operation either: READ with a `pattern` on an exact target
 stays READ and renders the selected lines ({§read-pattern}). The survey of
 paths is FIND, and only FIND.
@@ -927,7 +1105,7 @@ statements remain recoverable when their boundaries are trustworthy.
 
 ## §scope-slot 7. Scope markers
 
-The model-facing slot is `<scope>`; the AST field remains the historical
+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
 carry rendered anchors. The operation owner assigns every component's role.
@@ -1058,7 +1236,8 @@ The implementation this section describes lives in `@plurnk/plurnk-parser`
 ({§parser-consumers}); this section remains the contract it implements.
 
 ANTLR owns framing, slots and statement composition; AstBuilder produces the
-schema-owned AST. Registration, effects and authority remain runtime concerns.
+schema-owned AST. Where each block ends is decided first, over the whole input, by
+{§fence-pairing}; the lexer's fence predicates consult that decision and never decide it. Registration, effects and authority remain runtime concerns.
 
 ```mermaid
 stateDiagram-v2
@@ -1097,41 +1276,37 @@ Quoted blocks remain literal text, including every nested operation-looking line
 Operation bodies, asides, malformed operation regions and unfenced operation lines
 ({§unfenced-operation}) are not response text;
 nothing at or beyond a lost boundary is recovered as text. The statement and client
-tiers ignore outside text. Core alone owns filing it as a NOTE ({§response-text-note})
+tiers ignore outside text. Core alone owns storing it as the turn's outside source ({§outside-text})
 and no-operation strikes ({§empty-turn}); parsing never infers delivery or completion
 intent.
 
 §unfenced-operation **An operation written without its fence did not run, and the parser says
 so.** An outside-text line that opens at column zero with an operation's name and anything else
 — `KILL The answer…`, `READ (a.md)`, `KILL (notes.md)` — draws one warning: `` `KILL` has no
-fence, so it did not run. `` The line is not response text ({§response-text}): it is neither filed as
-a NOTE nor echoed into the next packet, and the exact emission remains at `ops://` (operator,
-2026-09-23); the bare name alone
+fence, so it did not run. `` The line is not response text ({§response-text}): it is neither stored
+as outside text nor echoed into the next packet, and the exact emission remains at `ops://`; the bare name alone
 opens the operation instead ({§naked-operation}). A registered executor's name 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, since `sh`,
-`env` and `members` are ordinary words. The model that wrote it believes it ran: while the line was
-still filed as a NOTE ({§response-text-note}), an unfenced KILL read back as an answer already given,
-and the model repeated it until the cycle detector ended the loop (`demo-overflow-recovery-AC4Ul4`;
-the same shape defeated SEND recovery and a count of invalid characters; operator, 2026-09-22). The
-warning and the exclusion together end that echo.
+`env` and `members` are ordinary words. The model that wrote it believes it ran: stored as
+outside text ({§outside-text}), an unfenced KILL would sit in the record as an answer never given,
+and only the warning tells the model otherwise. The warning and the exclusion together keep the
+line out of the record.
 
 §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, how many parameterless KILLs 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, and the difference is not academic: the
-regressions in #802 and #809 both shipped through a fully green suite, because every
-fixture in it was ours.
+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 under a contract that no longer would, which is
-the drift between what the harness once accepted and what it accepts now.
+reports how many recorded turns concluded in a way the current contract would reject.
 
 ## 12. Public API
 
@@ -1150,9 +1325,9 @@ An explicit disposition may sit anywhere in it
 ({§disposition-anywhere}). An omitted WAIT produces no synthesized statement, diagnostic, receipt,
 warning, or strike. The authored operations and source remain unchanged.
 Unfinished blocks never receive inferred closers.
-Bounded operation errors retain valid siblings, and so does a lost boundary:
-the statements that closed before `unparsedTail.from` are facts, and only what
-follows is undefined ({§unparsed-tail-boundary}).
+A bounded operation error leaves its siblings' facts intact, and a lost boundary
+leaves the facts before it ({§unparsed-tail-boundary}); running them is the
+consumer's admission ({§emission-admission}).
 
 The host records programs per turn; no operation acts as a separator between
 saved programs. There is no outer Markdown program wrapper; the executable
@@ -1193,7 +1368,7 @@ among them: the parser is `@plurnk/plurnk-parser`'s ({§parser-consumers}).
 The remaining values are small pure helpers over those contracts (`isExecution`, `writtenOp`,
 `lifecycleOfLoopStatus`, `selectWorkerLoop`, `renderJsonResult`, `formatJsonDocument`,
 `aguiConformanceReport`) and the closed name patterns and vocabularies (`RUNTIME_TAG`,
-`SKILL_NAME`, `REASONING_POLICIES`).
+`SKILL_NAME`, `EFFORTS`).
 
 §parser-construction-boundary Parser construction components are internal rather
 than alternate consumer entry points:
@@ -1490,9 +1665,22 @@ class PlurnkParseError extends Error {
     readonly column: number;
     readonly source: ErrorSource;
     readonly severity: Severity;
+    readonly recovery: string | undefined;
 }
 ```
 
+§parse-recovery **Every hard diagnostic carries its working form.** A `severity: "error"`
+diagnostic names, in `recovery`, the form that runs, in the model's terms: a refused heading
+carries the operation's canonical line (`` `READ (path) <L,M>? pattern? <!-- aside -->?` on the
+opening fence line; READ takes no body. ``), a refused matcher the dialect's form with an example,
+and a refused regex the regex that matches the words the model wrote — `` A pattern is a regex:
+write `/url/` to match lines containing url; `*` repeats what precedes it. To select files by
+name, put the glob in the target: `FIND (tests/*url*)`. `` — where the glob suggestion is derived
+from the pattern only when it is glob-shaped, and the regex sentence stands alone otherwise. The
+runtime projects `recovery` as the Problem's `recovery` beside the verbatim `message`; an advisory
+carries none, since its statement ran. Before this, a refused regex (`/*url*/`, DeepSeek run429)
+reported `Nothing to repeat` with no way forward and the turn was spent.
+
 §parser-position Parser source locations are points, not text regions. An AST
 statement's `position` identifies the first backtick of its header; a diagnostic
 identifies the offending or recovery point; `unparsedTail.from` identifies where
@@ -1540,7 +1728,7 @@ diagnostics are:
   position after the closing `/`. Only a leading group of `i`, `m` and `s` lifts;
   `(?i:…)` scoped modifiers are valid ECMAScript and pass through untouched.
   `plurnk.md` teaches one regex spelling, `/\btimeout\b/i`, with flags after the closing
-  slash; the lift is not taught. Unlike the tolerances on the {§response-text-note}
+  slash; the lift is not taught. Unlike the tolerances on the {§outside-text}
   scale, this one forgives a departure the model did not choose: `(?i)` is the spelling
   a great many models were trained on, so refusing it would punish an instinct rather
   than a mistake ({§naked-pattern} carries `^` for the same reason). The advisory still
@@ -1550,6 +1738,11 @@ diagnostics are:
   diagnostic, with or without flags, without assuming what the extra text was
   intended to represent. Invalid patterns or flags retain the native
   regex failure; no branch silently removes or executes trailing content.
+- §regex-sed-range **A sed line range is named as one.** A regex matcher written as a sed
+  address range — `/a/,/b/` or `/a/,+N` — is refused as a range, never as invalid flags: the
+  diagnostic says a matcher selects only the lines it matches, gives the one regex that
+  locates the ends (`/a|b/`, or `/a/`) and the scope that then addresses the span
+  (`<first,last>`, or `<N,M>` with M being N plus the range's count).
 - §unclosed-regex **A regex that never closes.** A `/pattern` matcher with no closing
   `/` is read as the whole pattern with no flags, with one warning-severity advisory
   naming the closing slash and the flag position. The reading is deterministic because
@@ -1577,7 +1770,7 @@ diagnostics are:
   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 and belongs here instead
-  (operator, 2026-09-21, #804). It is carried because `^` meaning "anchor" is among the
+  (#804). It is carried because `^` meaning "anchor" is among the
   strongest instincts a model arrives with: it will write `^Decision:.*` whether or not it
   was taught to, and the engine honours what it will reach for anyway. Teaching it would
   spend hot-path weight on a line that changes no behaviour. The omission is therefore not
@@ -1597,23 +1790,49 @@ diagnostics are:
   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 ({§response-text-note}): every slot the model wrote is present and
+  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
+  piece has one reading, so each is read and named with one warning-severity advisory after its
+  statement:
+
+  | Written | Read as | Advisory |
+  |---|---|---|
+  | `READ → sh:///x#stdout <1,50>` | the target, `READ (sh:///x#stdout) <1,50>`; COPY/MOVE take one arrow per operand | `` `→ sh:///x#stdout` is how the log shows an address; it was read as the target. Write the target in parentheses: `READ (sh:///x#stdout) <1,50>`. `` |
+  | `READ (a.py) <1,50> · 900`, `· 320 tokens`, a bare `·` | nothing: the token charge is dropped, on the heading or after a matcher | `` `· 900` is the token charge the log shows on a heading; it is not part of an operation and was ignored. `` |
+  | `FIND (x) /re/ · locate the sign handling` | the aside | `` `· locate the sign handling` was read as the aside; a note on an operation is written `<!-- locate the sign handling -->`. `` |
+
+  The arrow's path runs to the next space, `<` or `[`; a `·` never begins a heading matcher. In
+  distinct recorded benchmark emissions the arrow form opened 40 headings and the charge ended 52,
+  where they drew a missing-target 400 or a false-empty glob match.
+- §bare-target **A target written without its parentheses is refused with the line that runs.**
+  A FIND, READ or EDIT heading with no target whose heading text opens with a word that is no
+  matcher sigil, `READ a.py <1,4>`, cannot run: the word stands where the target goes, but on FIND it
+  could as well be a pattern. The statement is one hard diagnostic that writes the corrected line —
+  `` `READ` has no target: `a.py` stands where the target goes. Write the target in parentheses:
+  `READ (a.py) <1,4>`. `` A targetless KILL's heading text remains its inline deliverable.
+- §bare-anchor-scope **An EDIT's anchor without its angle brackets is its scope.** On an EDIT
+  heading, `@abcde` or `@abcde,@fghij` standing alone where the scope goes — nothing but an aside, a
+  closer or the line end after it — is the scope `<@abcde>`, with one warning-severity advisory:
+  `` `@abcde` was read as the scope `<@abcde>`; a scope is written in angle brackets. `` Read as
+  body instead, the anchor would be written into the file, or the EDIT refused for want of a line
+  marker (14 distinct recorded headings). On READ and KILL the same text stays a literal matcher,
+  since `@patch` is a search a model means.
 - §matcher-body-redirect **A body beneath those headings.** Text below the heading
   of a FIND, READ or targeted KILL is a body, and those operations take none: the builder
   keeps the statement without it and raises one warning-severity advisory (`READ
   takes no body; the body was ignored. A pattern belongs on the opening fence line
   after the path.`), delivered like {§misplaced-aside-advisory} as a
-  `parse_advisory` notice (operator, 2026-09-12: a gentle warning, never an error
-  the model must recover from). One sigil line beneath the heading is the bare form
+  `parse_advisory` notice (a warning, never an error). One sigil line beneath the heading is the bare form
   written a line low and still lifts; nothing else is promoted into a matcher from
   below the heading, and the advisory never echoes the body.
-- §combined-anchor-tolerance **Combined anchor and line number in a scope.** A
-  text-coordinate scope position written `@hash:L` or `@hash L` is the displayed
-  `@abcde 42:` prefix copied whole (a koota-entity turn refused nine of them in a
-  row, 2026-09-12): the position is the anchor, the number is dropped, and one
+- §combined-anchor-tolerance **Combined line number and anchor in a scope.** A
+  text-coordinate scope written `L<@hash>` — digits immediately before the opener — is the
+  displayed `42<@abcde>` row prefix copied whole: the scope is the anchor, the number is dropped, and one
   warning-severity advisory names the anchor-only form. The scope lexes as one
   ordinary marker at any text-coordinate operation, either COPY/MOVE operand
   included; nothing cascades.
@@ -1684,7 +1903,7 @@ author the tail's reason.
 |--------------------|----------------------------------------------------------------------------------------------------------------|
 | Diagnostic text    | Project `message` verbatim; do not strip prefixes, restate coordinates, or synthesize generic syntax recovery. |
 | Structured context | Preserve `line`, `column`, `source`, and `severity` as separate fields.                                        |
-| Runtime recovery   | Attach only a separately owned fact, such as Core knowing that bounded sibling operations were retained.       |
+| Runtime recovery   | Project the parser's `recovery` ({§parse-recovery}) and attach only a separately owned fact, such as Core knowing that bounded sibling operations were retained. |
 | Durable projection | Map bounded hard errors to failed operation results; warnings may become Notices with `level: "warn"`.         |
 | Presentation       | Normalize or bound the diagnostic only when the surface requires it, without changing its meaning.             |