@plurnk/plurnk-contracts 1.17.0 → 1.19.0

package/SPEC.md

@@ -2,14 +2,15 @@
 
 ## 1. Overview
 
-§contract-authority This package is the single authority for PLURNK's language, schemas, generated
-types, parser, and runtime-neutral wire envelopes. Its package root
-is the single code API for those contracts.
+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
+({§root-value-api}).
 
 | Surface                                                                         | Canonical export or artifact                        |
 | ------------------------------------------------------------------------------- | --------------------------------------------------- |
-| Parser, AST, validators, Problems, results, Notices, text regions and extents   | `@plurnk/plurnk-contracts`                          |
-| Capability and loop policies with their defaults                                | `CapabilityPolicy`, `LoopPolicy`, `DEFAULT_CAPABILITY_POLICY`, `DEFAULT_LOOP_POLICY` |
+| 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`             |
 | Model route and catalog discovery                                               | `ModelRoute`, `ModelCatalogQuery`, `ModelCatalogPage`, `ModelReadiness` |
 | Stopped-world client contract                                                   | `ProposalDisposition`, `ProposalProjection`         |
@@ -89,12 +90,10 @@ and previews; never reformat literal resources, JSONL framing, or wire/evidence
 serialization. Compact aggregate rows ({§json-result-rendering}) and packet
 metadata retain their deliberate layouts.
 
-## §contract-layers 1.1 Contract layers and admission boundary
+## 1.1 Contract layers and admission boundary
 
-PLURNK uses one contract with deliberately different projections. A tolerant
-ingester accepting a spelling does not make that spelling canonical model
-teaching, and an operator's sampling grammar admitting a sentence does not
-make its runtime semantics valid.
+One contract, deliberately different projections (ARCHITECTURE.md). Each layer
+below owns what it alone can decide.
 
 ```mermaid
 flowchart LR
@@ -127,7 +126,7 @@ WHATWG `URL`, ECMAScript `RegExp`, XPath 1.0, and RFC 9535 JSONPath parsers.
 The runtime owner decides facts that require state or operation-specific
 meaning, including registered scheme resolution, target existence, tag
 selection, text-region bounds, result ordering, full-text ranking, mutation
-effects, executor behavior, and numeric operation-code semantics.
+effects, and executor behavior.
 
 ### §contract-proposal-projection Loop policy and stopped-world projection
 
@@ -168,11 +167,15 @@ workspace layer and their normalized intersection: `service`, `workspace`, and
 capability policy or inherited bound; every actor uses the same live workspace
 policy. A client never derives effective authority from the mutable layer alone.
 
-§loop-policy `DEFAULT_CAPABILITY_POLICY` and `DEFAULT_LOOP_POLICY` are the
-contracts-owned complete defaults. A loop policy is immutable after creation;
-its `proposals` field chooses one downstream settlement posture, independently
-of workspace capability policy. Capability
-admission precedes effect classification and proposal settlement.
+§loop-policy A `LoopPolicy` is complete and immutable after creation:
+`proposals` chooses one downstream settlement posture and `attended` says
+whether anyone can answer, independently of workspace capability policy. An
+unattended loop cannot hold a proposal for review, so the schema refuses that
+pair. A `LoopPolicyRequest` is the part of a policy its creator chose to state.
+Contracts hold no default for the rest: the daemon's panel supplies it
+({§loop-policy-composition}). `PROPOSAL_POLICIES` is the schema-owned
+vocabulary of `proposals`. Capability admission precedes effect
+classification and proposal settlement.
 
 §reasoning-policy-wire `ReasoningPolicy` is exactly `off | adaptive | low |
 medium | high`. The schema owns this shared wire vocabulary. Providers own the
@@ -255,7 +258,8 @@ and parse diagnostics are separate contracts.
 body
 ```
 
-```OP (path)? <scope>?```
+```OP (path)? <scope>?
+```
 
 ```executor (program-or-tool)?
 input
@@ -263,37 +267,56 @@ input
 `````
 
 §section-boundary Every statement is one backtick block. Its header occupies one
-physical line: a fence of at least three backticks, an optional numeric delimiter
+physical line: a fence of at least four backticks ({§four-backtick-operations}), an optional numeric delimiter
 ({§numeric-delimiter}), then the name and its slots. A closer is shown by
 convention and never demanded ({§fence-closer}, {§closer-fallback}). There are no
-operation suffixes or heading levels. Nothing in the language is counted by the
-author: every boundary is an anchored line the parser recognizes by its first
-characters (operator, 2026-09-12: counted pairs failed 52 of 363 turns on
-GLM-5.3-flash; anchored tokens failed none).
+operation suffixes or heading levels. Complete nested matches take precedence
+over local recovery ({§balanced-fences}).
 
 §fence-closer A block opened with N backticks and delimiter D (its digits, possibly
-none) closes at the first line at column zero made of at least N backticks,
+none) closes at the first unclaimed line made of at least N backticks,
 exactly D, and nothing else but horizontal whitespace. Count follows CommonMark: a
 shorter fence inside the body is body; an equal or longer bare fence closes a bare
-block. The delimiter compares exactly: a bare fence never closes a delimited block,
+block unless it closes a balanced nested block ({§balanced-fences}). The delimiter
+compares exactly: a bare fence never closes a delimited block,
 and a delimited fence never closes a bare one. 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 an undelimited body, line-leading labeled fences open literal
+blocks; their matching closers close the innermost block first. The enclosing
+block and its nested blocks must all close, with matching widths and delimiters
+under {§fence-closer}. Equal opener/closer totals alone are insufficient. A complete
+inline block is already closed; a numerically delimited block is opaque until its
+own closer. 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.
+
 §numeric-delimiter Digits between the opening backticks and the name (an opener
-carrying `42EDIT (x)`) identify the block, and only a fence carrying `42` closes it. This is how a
-block nests fences of its own width: with a delimiter, a body may carry bare fences
-and headings of the same count. The delimiter is syntax, never AST or persistence
+carrying `42EDIT (x)`) identify the block, and only a fence carrying `42` closes it.
+This explicitly protects bare fences and headings, including incomplete examples.
+The delimiter is syntax, never AST or persistence
 state; `PlurnkParser.frame` chooses one when the body it wraps holds a heading line
 of four or more backticks ({§statement-rendering}).
 
-§fence-heading-in-body A fence line of four or more backticks, optional digits, and
-a name that is a native operation or a known executor is a heading wherever it
-stands. Inside an open block it ends that block without closing it
+§four-backtick-operations **An operation opens with four backticks.** A heading is a fence of
+four or more backticks; a three-backtick fence is markdown wherever it stands, so an answer's
+code blocks (```` ```sh ````, ```` ```ts ````) are prose and never run (operator,
+2026-09-18, #761). A three-backtick fence naming an operation or known executor draws one warning that it
+needs four backticks; any other three-backtick fence draws none. `plurnk.md` teaches exactly
+four; longer fences are tolerated, not taught. Every producer of a statement — the parser, a
+client composing `/look`, a client's tab-completion — writes `PLURNK_FENCE` rather than its own
+literal, so no surface can ship a width the parser will quote (plurnk/plurnk#92).
+
+§fence-heading-in-body Outside a complete nested block ({§balanced-fences}), a fence
+line of four or more backticks, optional digits, and a name that is a native operation
+or a known executor is a heading. Inside an open block it ends that block without closing it
 ({§closer-fallback}) and opens the next statement. Fence lines of fewer than four
-backticks are headings only outside any block. Known executors are `sh` plus what
+backticks are never headings ({§four-backtick-operations}). Known executors are `sh` plus what
 the host names in `ParseOptions.executors`. Consequences: a closer glued to the next
-opener (eight backticks then `READ`) can never swallow the rest of a turn, and a quoted
-heading of four or more backticks inside a body needs the numeric delimiter to stay body.
+opener (eight backticks then `READ`) can never swallow an unbalanced turn, and a numeric
+delimiter preserves quoted headings even when their own fences are incomplete.
 
 §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,
@@ -302,48 +325,67 @@ ending goes with it; when no bare fence line exists the body is the whole span l
 one terminating line ending. This carries no diagnostic: a missing closer is never
 an admission failure, and {§unparsed-tail-boundary} is not involved.
 
-§fence-boundary Inside a body, fences are read by count and delimiter, never by
-name, except for the heading rule above:
+§fence-boundary Balanced nesting is resolved before local recovery. Otherwise,
+fences are read by count and delimiter, except for the heading rule above:
 
 | Fence encountered inside a body | Meaning |
 |---|---|
+| Part of a complete nested block | Literal body, including its openers and closers |
 | Fewer backticks than the block's own | Body |
 | At least the block's backticks, bare, block undelimited | The block's closer |
 | At least the block's backticks carrying the block's delimiter | The block's closer |
 | At least the block's backticks with any other delimiter | Body |
 | Four or more backticks naming a native operation or known executor | A heading: ends the block, opens the next statement |
 
-§indented-fences Leading horizontal whitespace before an opener or a closer is
-not part of the fence: an indented fence line is a fence line, on openers,
-closers, headings that end a block, and the closer fallback. A body keeps its own
-lines' indentation. CommonMark allows three spaces; this allows any, because a
-model that indents an emission indents all of it (operator, 2026-09-12: measured
-at five to ten percent of emissions on GLM-5.3-flash).
+§indented-fences Leading horizontal whitespace before a CLOSER is not part of the fence: an
+indented closer, heading-that-ends-a-block, or closer fallback still closes, and a body keeps its
+own lines' indentation. An OPENER is different: an operation's backticks follow a newline
+directly (operator, 2026-09-18), so an indented fence opens a quotation, never an operation —
+CommonMark reads an indented block as code, and `plurnk.md` shows its own examples that way. This
+reverses the 2026-09-12 tolerance (then measured at five to ten percent of emissions on
+GLM-5.3-flash; 2.8% of that lane's emissions today). The cost is paid loudly: an indented fence
+naming a known operation draws `must start its line to run` and is an operation attempt, never an
+answer ({§prose-conclusion}), so the loop continues instead of delivering a program as prose.
 
 §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 opener; the closer still closes, and the
 opener opens. This absorbs the habit of writing several operations in one
-paragraph after prose. Prose after a closer on its line ends the chain.
+paragraph after prose. Prose after a closer on its line ends the chain; slot-shaped
+text there is the heading's own and is read under {§transparent-inline-closer}.
+
+§transparent-inline-closer **A closer mid-heading is read as if it were not written.** A
+closing fence on a heading line followed by more of that heading — a `<scope>`, an
+`[option block]`, a `<!-- aside -->`, or a naked matcher — does not end the reading: the
+heading keeps taking its slots under {§trailing-slots} and {§naked-pattern}, exactly as though
+the closer were absent, so ````` ````READ (a.md)```` ````` `<1,2>` is the same operation as `READ (a.md) <1,2>`.
+The closer is still a closer: the block ends with that physical line and never reaches down for
+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").
 
 §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 in any case is still prose
-({§interstitial-fence}).
-
-§one-line-turn **A whole turn on one line.** The most frequent private rejection
-across the 2026-09-12/13 dumbox runs (five of eleven) was a turn emitted as a
-single line: prose, then heading after heading with no line ending anywhere. Two
+(2026-09-13 census). 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
+`node` under {§executor-case}. Parsing normalizes the runtime before admission
+and dispatch; execution, policy, receipts, and output addresses remain Node's.
+The authored source remains unchanged. This spelling adds no executor, discovery
+entry, or model-facing teaching. An explicitly registered `js` retains its own
+identity; absent `node`, the shorthand grants no executable capability.
+
+§one-line-turn **A whole turn on one line.** A model may emit a turn as a single
+line: prose, then heading after heading with no line ending anywhere. Two
 rules absorb it. The next opener on a heading's own line, after the heading's
 slots, ends that heading's block bodyless and opens ({§empty-section}), so
 `````EDIT (a.rs) <60,66> <!-- drop --> ````EDIT (b.rs) <31,38>` is two scoped
-deletions; and a TASK whose inventory rides its heading line as a `[…]` block
-(`````TASK [{"content": "…", "status": "in_progress"}] ````) takes that block as
-its body when nothing sits beneath the heading, with one warning-severity
-advisory naming the body as where the inventory belongs. A block beneath the
-heading still wins.
+deletions. Literal inline bodies follow {§heading-inline-body}.
 
 §anchor-digits In a text scope, `@` followed by one to four digits cannot be a
 hash and is read as that line number, with one warning-severity advisory naming
@@ -353,33 +395,81 @@ the five-character anchor form. Five characters after `@` are always an anchor.
 line takes the rest of the line as the aside, with one warning-severity advisory.
 A closed aside followed by more text is unchanged.
 
-§interstitial-fence A fence line that names no native operation and no known
-executor opens nothing: unlabeled, or tagged like a code block (`ts`, `json`),
-outside a block it is prose and ignored like every other outside line
-({§whitespace-contract}); inside a body it is body. Nothing is promoted into a
-header or recursively parsed. There is no implicit SEND: a reply is an explicit
-`SEND` block. (This replaces the retired unlabeled-fence SEND of the fences
-chapter, whose unlabeled fences turned displaced headings into silent messages.)
+§quotation **A fence that opens no operation quotes.** Outside a body, a line-start fence that
+is not an operation heading — unlabeled, tagged like a code block (`ts`, `json`), three
+backticks ({§four-backtick-operations}), indented, or four or more with an unknown name — 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, native tool-call
+markup is not read ({§native-tool-calls}), and no heading draws an advisory. So a model may show
+plurnk's own operations in an answer. Three 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; a bare fence directly under a
+line carrying a fence run, which is an orphaned closer and quotes nothing; and a tag that is a
+missed operation — a known name under four backticks or off column zero, or an unknown name at
+operation width — which still draws one warning (`markdown` and `md` are polite envelopes and
+draw none). There is no implicit SEND: a reply is prose ({§prose-conclusion}) or an explicit
+`SEND` block. Origin (#767, 2026-09-18): under prose answers, a quoted example executed.
+
+§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.)
+
+§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
+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
+reading, with no diagnostic and no teaching (#758):
+
+- an aside written before the heading's remaining scope or JSON option block is
+  read after them (`READ (a.md) <!-- why --> <1,-1>`); an aside followed by a
+  target or a non-JSON block keeps its place and stays refused;
+- zero-width characters (U+200B–U+200D, U+2060, U+FEFF) on a heading line are skipped;
+- a matcher that begins with a sigil and is quoted in single backticks
+  (`` `^def test_` ``) is that matcher; quoted text without a sigil stays refused.
+
+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 (DeepSeek's `<｜｜DSML｜｜ calls>` block) naming a plurnk operation or
+a known executor. Each `invoke` is read as that operation's canonical fence:
+`path`/`target` fill the target, `scope`/`range`/`lines` the scope, `pattern` a
+matcher option, `aside` the aside, and `body`/`content`/`command` or plain lines
+inside the invoke the body; plurnk slots written after the invoke name are kept.
+Each block keeps its line count, so statement positions still name the source
+line. An invoke 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).
+
+§operation-attempt An emission with no operation is either prose, which a host may take
+as the model's answer, or an operation attempt. `PlurnkParser.operationAttempt(input,
+executors)` names the attempt: a line opening a four-backtick fence, a heading outside
+any fence ({§bare-heading-advisory}; a known executor's name is a heading only when a
+slot follows it), native tool-call markup that {§native-tool-calls} did not read, or
+echoed packet rows (`### log://…`). Anything else, three-backtick code blocks included,
+is prose (#761).
 
 §bare-heading-advisory An operation name that opens a line outside any block in the
-shape of a heading (`READ (…)`, `TASK`, …) is prose and runs nothing. The parser
+shape of a heading (`READ (…)`, `NOTE`, …) is prose and runs nothing. The parser
 emits one warning-severity advisory naming the fence form, placed after the parsed
 items, so the loss is never quiet.
 
 §empty-section Both the compact bodyless form and an empty multiline block
-normalize optional bodies to null. TASK normalizes an empty body to `[]`
-under {§plan-value}. Closing fences are conventional, never required
+normalize optional bodies to null. Closing fences are conventional, never required
 ({§closer-fallback}).
 
 §statement-rendering `PlurnkParser.stringify` renders native OP names and named
-EXEC executors from the shared AST, with one blank line between operations.
+runtime fences from the shared AST, with one blank line between operations.
 Every closing fence occupies its own line, including bodyless operations;
 inline fences remain accepted input, not generated examples.
 It chooses at least four backticks and more than any run within the body, and a
 numeric delimiter whenever the body holds a heading line of four or more backticks
 ({§fence-heading-in-body}), preserving body bytes on reparse. Fence length and
 delimiter are syntax, not AST or persistence state. Core-authored programs use
-this serializer and the ordinary admission parser.
+this serializer and the ordinary admission parser. Rendering preserves a matcher
+beside owner metadata, not only a matcher carried inside its `pattern` option.
 
 | Element | Contract |
 |---|---|
@@ -398,8 +488,9 @@ adjacent slots and scope/metadata permutations within a selection without
 changing ownership or making them distinct canonical forms. Each selection
 has at most one scope; its metadata blocks retain their authored order.
 
-§plan-slotless TASK accepts no target or metadata. Its optional scope carries
-waiting timing; its inventory body begins below the header.
+§lifecycle-slots NOTE accepts no target, scope, or metadata. WAIT retains its
+optional target and ignores syntactically valid scope and metadata without diagnostics
+({§send-wait-scope}). Their literal bodies begin below the header.
 
 §heading-inline-body Nonempty body text belongs below the fence header.
 The ingester tolerates body text after horizontal whitespace on the header,
@@ -413,7 +504,7 @@ routing, timing, or body input. Comments inside a body remain literal except
 for the narrowly owned {§misplaced-aside-advisory}.
 
 §scheme-metadata-modifier A target may carry one single-line `[metadata]`
-block after its scope; an executor fence also admits it without a target.
+block after its scope; executor and SEND fences also admit it without a target.
 Read with its brackets, the block is a JSON array of option objects, merged
 left to right with later keys winning; the keys belong to the selected scheme
 or executor, which owns interpretation, validation and authority. The language
@@ -422,8 +513,10 @@ balanced brackets inside the block are retained, and double-quoted strings
 protect their brackets. Brackets inside `(path)` remain ordinary path and
 glob characters. A block that is not valid JSON, or a second block on one
 operand, is the owner's `400`, never a parser diagnostic. An unfinished block
-or multiline metadata loses its boundary. One key is the language's own:
-`pattern` ({§matcher-option}).
+or multiline metadata loses its boundary. Two keys never reach an owner:
+`pattern`, the language's own ({§matcher-option}), and `env`, reserved for the
+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
@@ -453,7 +546,7 @@ whose block left no metadata back bare when the bare form reads back identically
 
 | Element | Shape or role |
 |---|---|
-| Native OP | `FIND READ EDIT COPY MOVE SEND EXEC BARE WORK FORK KILL TASK` |
+| Native OP | `FIND READ EDIT COPY MOVE SEND BARE WORK FORK KILL NOTE WAIT` |
 | Executor name | Letters, digits, `_`, `.`, `+`, or `-`; reserved OPs win |
 | Fence | Three or more backticks, matched by exact count |
 | `(path)` | Local path, URI, program or tool name; §5 |
@@ -473,90 +566,68 @@ governed by {§canonical-statement}; runtime conditions remain explicit below.
 | EDIT | required file or entry                       | required for an existing target | literal text                   |
 | COPY | required source and destination              | optional region after each path | empty                          |
 | MOVE | required source and destination              | optional region after each path | empty                          |
-| EXEC | fence names executor; optional program/tool path ({§exec-executor-slot}) | optional timeout, poll     | optional program input        |
+| execution | the fence name is the runtime; optional program/tool path ({§exec-executor-slot}) | optional timeout, poll     | optional program input        |
 | BARE | optional prompt resource                     | none                            | prompt; optional with a path   |
 | WORK | optional fresh `worker://name`, or a prompt resource ({§worker-spawn-prompt-resource}) | none | prompt; optional with a resource |
 | FORK | optional context-inheriting `worker://name`, or a prompt resource | none            | prompt; optional with a resource |
 | KILL | required target, including a log item        | optional text region ({§kill-scope}) | none; the matcher is the `pattern` option |
-| SEND | optional recipient | optional recipient timing | message |
-| TASK | none | optional timeout and poll for waiting intent | Plurnk Plan JSON array |
-
-§operation-code-polymorphism Operation-result statuses and turn dispositions are
-distinct facts. TASK derives lifecycle intent from its inventory;
-SEND and KILL carry no disposition operand.
-
-§plan-value **TASK carries the complete current task inventory.** Admission
-parses one JSON array in any whitespace layout, including
-{§json-result-rendering}, strips unknown entry keys, and validates string
-`content` and native `status`. Opaque `_meta` remains optional. Nonempty plain
-text, malformed JSON, or an invalid array becomes one `in_progress` entry
-containing the exact body, with one factual warning. No partial repair or list
-inference occurs. A blank body becomes `[]`, never inferred completion.
-The normalized array is the sole semantic value in AST, persistence and model
-log; exact authored bytes remain in `turnOps`. Earlier inventories are history,
-not accumulated obligations. Task descriptions are not executable dependencies.
-
-§task-inventory-intent The first matching row determines intent, independently
-of entry order. Actual execution adjudicates intent under {§wait-obligation-matrix}.
-
-| Inventory condition | Intent | Derived lifecycle status |
-|---|---|---|
-| TASK omitted | Continue silently | 102 |
-| Explicit empty inventory | Recover empty inventory | 102 |
-| Any `in_progress` | Continue independent actionable work | 102 |
-| Any `waiting`, no `in_progress` | Await work or an event | 202 |
-| Any `pending`, no actionable or waiting entry | Review blocked dependencies | 102 |
-| All terminal, any `completed` | End successfully | 200 |
-| All `failed`, nonempty | End unsuccessfully | 499 |
-
-`pending` is blocked on another task; `in_progress` can be actively advanced;
-`waiting` awaits an ongoing stream, worker or external event. `completed` is
-successful resolution; `failed` is unsuccessful resolution. A failed sibling
-does not terminate independent unfinished work. The engine does not infer a
-dependency graph from task text.
-
-§plan-acp-projection **Only an ACP-facing boundary projects the model-native
-Plan.** It constructs ACP's `{ "entries": [...] }` Plan object from the internal
-array, synthesizes the ACP-required neutral `medium` priority on every entry
-(the model-native Plan carries none). The internal value is never mutated.
-Native `waiting` maps to ACP `in_progress`, with `Waiting:` and a space prepended
-to its display content; native `failed` maps to ACP `completed`, with `Failed:` and a space.
-Both carry their native status in `_meta["plurnk.xyz/status"]`, an edge-owned
-key derived from the native status rather than trusted from authored metadata.
-Other statuses and unrelated metadata remain unchanged. The labels preserve
-meaning even when a generic client ignores extension metadata.
-The projected value validates against the separately owned ACP Plan schema pinned
-to ACP v1
-[`schema-v1.21.0`](https://github.com/agentclientprotocol/agent-client-protocol/tree/schema-v1.21.0)
-commit `272bf799f35a258c6a4107a0410ed361e83683d3`.
+| SEND | optional recipient | recipient-defined; none for workers ({§send-directed-scope}) | message |
+| NOTE | none | none | literal working memory |
+| WAIT | optional event source ({§send-wait-scope}) | ignored | explanation of the wait |
+
+§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. A NOTE-only turn is subject to ordinary conclusion,
+repetition and strike rules.
+
+§reasoning-notes NOTE is the only operation admitted from exposed provider
+reasoning. The shared fence parser selects line-leading NOTE statements in a
+quotation-preserving reasoning context: other backtick or tilde code blocks are
+opaque, and operation-heading recovery cannot escape them. Blockquoted and inline
+examples are not headings. Program parsing is unchanged; other reasoned operations
+never execute.
+Selected notes precede the content program in the admitted turn and use the
+ordinary dispatcher, persistence and log projection. Reasoning bytes and content
+bytes remain separate, unchanged forensic sources. Rejected or superseded
+provider attempts cannot commit notes. Non-thinking models use NOTE in their
+ordinary program. No task inventory is inferred from notes or lifecycle prose.
 
 §exec-executor-slot The fence name selects the executor directly: for example,
 `python3 (tools/report.py)` or `gitea (issue_list)` on the opening fence line.
-Reserved native OP names take precedence. Other names lower to the same EXEC
-AST with `executor`, `target`, metadata, timing and body fields.
+Reserved native OP names take precedence. Any other name is an executor fence: its
+AST carries the `runtime` tag and no operation keyword, then `target`, metadata, timing and body fields.
 Registration is checked by the runtime, not by the syntax parser. An attached
 MCP service uses that executor path and its owner validates the named tool and
 input-body JSON against its schema. Unknown names do not fall back to a shell.
-The native `EXEC` form without a selected executor retains the runtime's
-default executor contract; canonical shell examples name `sh` explicitly.
+There is no runtime-less form: every execution names its runtime, and canonical
+shell examples name `sh` explicitly.
 The path names a program or tool and is never split. Metadata such as
 `[{"cwd": "…"}]` remains interpreted by the selected executor.
 
-§turn-disposition TASK is the sole workflow declaration. `TurnDisposition`
-derives intent from its canonical inventory under {§task-inventory-intent}.
-The AST has no independently settable lifecycle status, target or metadata.
-SEND deliberately messages its recipient, or the user when targetless; it
-neither changes task status nor terminates a run. A program contains one final
-TASK, not last-wins competing inventories. Former lifecycle names are not aliases.
-
-§send-wait-scope TASK accepts `<timeout[,poll]>` in whole minutes. It applies
-only to a waiting intent ({§park-202-only}); the dispatcher validates its bounds.
-Otherwise it is unused, with a factual warning rather than a changed outcome.
-
-§send-directed-scope A recipient SEND preserves an optional numeric scope after
-its target and metadata. The addressed owner assigns its semantics; worker
-actors use `<delay[,interval]>` ({§worker-scheduled-send}). A targetless message
-takes no scope. Scheduling does not change the message body or disposition.
+§turn-disposition WAIT requests parking; its literal body does not control
+scheduling, and its optional target is the label the row keeps, never a join;
+the AST has no independently settable lifecycle status or metadata.
+A turn admits any number of WAITs, all deferred until its other operations
+settle and together one park. End-of-program adjudication owns continuation, joining and completion
+under {§wait-obligation-matrix}; no terminal verb or synthetic receipt is required.
+SEND delivers messages and NOTE retains memory, neither declaring an outcome.
+
+§send-wait-scope WAIT's optional target is retained as the row's label; no
+scheme handler runs for it, so every WAIT is the bare park. Scope and metadata
+are discarded without diagnostics,
+including structured scopes. The body, aside, and exact submitted program
+remain intact. WAIT neither creates a schedule nor restricts which ordinary
+events may awaken the loop. A scope slot's content is skipped unread whatever it
+holds (`<sh:///…>` included; #756). Ordinary malformed-header rules still apply;
+a second WAIT is one more label on the same park, never a refusal.
+
+§send-directed-scope A recipient SEND carries an optional numeric scope after
+its target and metadata through to the addressed owner, which assigns its
+semantics or refuses it; worker actors refuse one (`scope-unsupported`, 400),
+because later and recurring delivery belong to the schedule family. 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
@@ -575,7 +646,7 @@ and is refused there; a bracket before the target of a non-executor OP is one
 bounded header diagnostic that selects nothing.
 
 The `<scope>` slot is optional where admitted and its domain is OP-specific. FIND
-scopes ordered results. EXEC and SEND scope owner-defined timing. READ, EDIT, COPY,
+scopes ordered results. Executions and SEND scope owner-defined timing. READ, EDIT, COPY,
 MOVE, and KILL use one universal text algebra independent of mimetype; a log
 KILL admits only its one- and two-line forms for canonical log-body visibility:
 
@@ -621,8 +692,8 @@ parses as `{ kind: "local", raw: "data/users.html", fragment: "readable" }`: the
 the path and the rest is the channel (a spelling that opens with `#` names no path and stays
 whole), exactly as `worker:///a.html#readable` decomposes, so
 the `#channel` a READ receipt advertises (`channels: {"#readable": N}`) is addressable in the
-same bare spelling the receipt used (2026-09-13 dumbox demo: the model appended it and was
-told no entry existed at `users.html#readable`). `raw` is therefore always the path alone; a
+same bare spelling the receipt used: a model that appends the channel to the path it was just
+shown addresses the same entry. `raw` is therefore always the path alone; a
 bare path never contains a literal `#`, and `PlurnkParser.stringify` renders the channel back.
 Without a `#` the field is absent, so an older `LocalPath` literal stays valid.
 
@@ -642,9 +713,12 @@ Mutation semantics:
 - `<0>` prepends and `<-1>` appends.
 - §empty-mutation-scope Empty mutation content has one writable position: `<0>`, `<1>`, `<-1>`, and `<1,-1>` all insert the body as its complete value. Other scopes resolve against that same empty value through the ordinary coordinate algebra.
 - `<SL,SC,EL,EC>` deletes the exact exclusive-end region and inserts the body at its start.
-- §transfer-resource-selections COPY and MOVE require two singular `ResourceSelection` operands on the heading, source first and destination second, and admit no body. Each operand consists of `(path)`, optional `<scope>`, and optional `{metadata}` blocks; modifiers bind only to that operand. The two operands independently select their resource, channel, scheme metadata, and text region.
+- §transfer-resource-selections COPY and MOVE require two singular
+  `ResourceSelection` operands, source first and destination second, and admit
+  no body. Each selection binds its own target, scope, matcher, and metadata
+  under {§slot-order}, {§matcher-option}, and {§scheme-metadata-modifier}.
 
-### §operation-observation Per-operation observations
+### Per-operation observations
 
 | OP   | Successful observation                                                            |
 |------|-----------------------------------------------------------------------------------|
@@ -654,16 +728,16 @@ Mutation semantics:
 | COPY | Source and destination selections plus ordered destination effects                |
 | MOVE | Source and destination selections plus ordered destination and source effects     |
 | SEND | Status and recipient acknowledgement when applicable                              |
-| EXEC | Spawn acknowledgement; output arrives through named stream channels               |
+| execution | Spawn acknowledgement; output arrives through named stream channels               |
 | BARE | The one-shot model response                                                        |
 | WORK | Spawn acknowledgement; the deliverable arrives through the log                    |
 | FORK | Spawn acknowledgement; the inherited worker's deliverable arrives through the log |
 | KILL | Status of deletion or termination                                                 |
-| TASK | Current inventory and adjudicated lifecycle outcome                              |
+| NOTE / WAIT | Literal memory or wait explanation                              |
 
 §find-result-unit For FIND, authored target shape fixes the paginated result
 unit. An exact target with a matcher pages flat match locations; a glob or
-folder target, and every body-less FIND, pages resources. Resolving a glob to
+folder target, and every matcher-less FIND, pages resources. Resolving a glob to
 one resource does not make it exact. The same `<N>`, inclusive `<N,M>`,
 markerless `<1,16>`, and explicit-all `<1,-1>` forms apply to either unit.
 
@@ -676,7 +750,7 @@ EDIT. Whole-channel transfers remain bodyless structural effects; runtime
 owners reject binary markers rather than treating a text field as a byte lane.
 
 Every operation returns the runtime-neutral `OperationResult` defined by
-{§operation-result}. Its `status` belongs to the result envelope; TASK supplies
+{§operation-result}. Its `status` belongs to the result envelope; a lifecycle operation supplies
 the authored lifecycle intent. Durable operation observations are projected into a later packet;
 retrieval never returns inline within the emitting turn.
 
@@ -733,12 +807,12 @@ never target content. Glob metacharacters remain legal path data.
 Matching and folder-scope semantics remain runtime concerns.
 
 §worker-name The exported `WORKER_NAME` contract governs names minted for URI
-authority slots: a lowercase DNS label matching
-`[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?`. `RESERVED_AUTHORITIES` contains the
-authority-shaped internal worker names `commons` and `plurnk`, which are
-unavailable for minting. `~` is the sole current-worker sigil and falls outside
-the mintable alphabet; every matching unreserved value, including `self`, is an
-ordinary literal worker name. This is a minting and registry invariant, not an
+authority slots: `[A-Za-z0-9][A-Za-z0-9_-]{0,62}` (1–63 ASCII characters,
+starting with a letter or digit). Case is preserved and significant;
+`Approach_A` and `approach_a` are distinct names. There is no reserved-name list: the
+runtime's own actor is named `_plurnk`, a spelling the predicate never admits.
+Every matching value, including `self` and `plurnk`, is an ordinary
+literal worker name. This is a minting and registry invariant, not an
 ingestion restriction: the parser decomposes arbitrary URL authorities.
 
 ## §matcher-prefix-claims 6. Bulk pattern matching
@@ -754,17 +828,17 @@ matching.
   statement-level error the parser discards the rest of that statement and resumes at the
   next heading; the turn shape is decided locally (a turn disposition is recognized by its own
   token, never by a whole-turn alternative), so one malformed heading costs one
-  diagnostic and every later statement, the turn disposition included, stands on its own. Any
-  other second path slot names the one-slot rule.
+  diagnostic and every later statement, the turn disposition included, stands on its own.
 - §scope-slot-tolerance A line scope written inside a path slot (```` ```COPY (worker:///src.md<2,3>) ````)
   is read as `(worker:///src.md) <2,3>` — `<` and `>` are not URI characters, so a `<…>` right
   before a slot's closing paren can only be a scope; every path slot of a statement is repaired
   the same way — and the slip is one warning-severity advisory at the `<`, placed right after its
   statement, stating the `(path) <scope>` form that was used. The statement runs; a warning is
   never a strike. A `<` anywhere else in the slot remains the lexer's refusal.
-- §second-path-slot A second `(path)` on a heading that already closed one is a parser
-  error at the second paren stating the one-slot rule and that a pattern belongs in the
-  `[{"pattern": …}]` option; the statement is dropped and its siblings run.
+- §extra-path-slot A path slot beyond the operation's admitted operands is a parser
+  error at its opening paren. Report the unexpected slot and the grammar's expected
+  alternatives when available, without inferring pattern intent or imposing another
+  operation's operand count. The statement is dropped and its siblings run.
 
 | Prefix    | Dialect  | Canonical form                       | Typed admission                   | Runtime owner       |
 |-----------|----------|--------------------------------------|-----------------------------------|---------------------|
@@ -816,9 +890,9 @@ The operation column names the canonical AST operation after
 | COPY/MOVE source      | 0/1/2/4 text coordinates               | Region copied or moved from the selected source                            |
 | COPY/MOVE destination | 0/1/2/4 text coordinates after target  | Region replaced or insertion point at the destination                      |
 | KILL                  | 0/1/2 text coordinates                 | Whole target when absent; one physical line or inclusive range when present ({§kill-scope}) |
-| EXEC                  | `timeout[,poll]`                       | Spawn lifetime bound and poll cadence in minutes                           |
-| ```` ```TASK ````     | `timeout[,poll]`                       | Waiting intent: bounded or indefinite wait and optional poll cadence ({§send-wait-scope}) |
-| Directed SEND         | Owner-defined numeric scope           | Worker actors schedule a task with `delay[,interval]` ({§send-directed-scope}) |
+| execution             | `timeout[,poll]`                       | Spawn lifetime bound and poll cadence in minutes                           |
+| WAIT                  | None                                   | Scope is ignored ({§send-wait-scope}) |
+| Directed SEND         | Owner-defined numeric scope           | Carried to the addressed owner; worker actors refuse it ({§send-directed-scope}) |
 
 Text coordinates use the algebra in {§text-scope-semantics}: one integer is a
 whole line, two integers are an inclusive whole-line range, and four integers
@@ -834,8 +908,7 @@ its `L`, `SL`, or `EL` position denotes a line. Columns, prepend `0`, and append
 `-1` remain numeric. Exact READ, EDIT, COPY/MOVE source and destination,
 KILL, and client LOOK preserve these positions in `TextLineMarker`; core resolves them
 against the addressed current text before operation-specific numeric scope
-semantics run. A matcher-bearing or path-glob READ normalizes to FIND, whose
-result positions remain numeric and reject anchors. Numeric text scopes remain
+semantics run. FIND's result positions remain numeric and reject anchors. Numeric text scopes remain
 canonical and fully supported. Parser acceptance does not imply model-facing
 recommendation.
 
@@ -870,56 +943,49 @@ npm test
 ````
 `````
 
-The inner shell example is EDIT content, not an EXEC invocation. The same
+The inner shell example is EDIT content, not an execution. The same
 rule protects code examples in SEND, WORK, FORK, BARE and every other body.
 
 ## 9. Turn dispositions
 
-TASK inventory intent maps to the existing HTTP-shaped lifecycle statuses
-({§task-inventory-intent}). The runtime adjudicates that intent against actual
-results, obligations and timing:
+The runtime adjudicates a nonempty admitted program against actual messages,
+results and live obligations ({§wait-obligation-matrix}). A response with no
+operation receives empty-turn recovery, not successful completion ({§empty-turn}).
 
 | Intent | Nominal status | Meaning |
 |---|---|---|
-| TASK omitted | 102 | Continue silently, without a receipt or strike for omission |
-| empty, continue, pending | 102 | Continue or recover; an explicit empty inventory is refused with a soft 409 receipt, no strike |
-| wait | 202 | Park when a live obligation or explicit timing exists |
-| complete | 200 | Conclude once execution results permit completion |
-| fail | 499 | End unsuccessfully and cancel unresolved descendant scope |
+| Unanswered messages or unobserved results | 102 | Continue silently |
+| WAIT | 202 | Park when a live obligation exists; otherwise continue at 102 |
+| All messages answered, live work remains | 202 | Join the held work |
+| All messages answered, results observed, no held work | 200 | The admitted program concludes; no repeated response is required |
+| KILL own worker | 499 | Cancel unfinished work in that worker and its descendants |
 | Runtime or infrastructure failure | 5xx | Not a model-authored task status |
 
-### §waitpid-dispositions The terminal contract (waitpid)
+### The terminal contract (waitpid)
 
-The model may supply one current inventory per turn; its statuses determine
-one intention. Without TASK, an operation-bearing turn continues silently.
-The engine verifies an explicit intention against the loop's actual
-obligations (spawned children, open streams, pending results); the grammar
-polices *shape* only. Asking
-the human is the native `question` EXEC tool ({§question-tool}), not a
+The model may supply one WAIT per turn. The host, not the grammar, owns
+turn boundaries and adjudicates the loop's actual obligations. Asking
+the human is the native `question` executor tool ({§question-tool}), not a
 disposition. The shape rules ARE structural:
 
-- §send-mid-reservation TASK has a reserved token ({§turn-disposition}).
-  A turn admits at most one TASK, anywhere among its operations
-  ({§disposition-anywhere}); the runtime executes it last. A second
-  disposition is a structural error, not a choice between competing outcomes.
-- §disposition-anywhere The disposition may sit anywhere in a model turn
-  (operator, 2026-09-12: models state the plan first; the inventory is a
-  statement about state, not a boundary). `PlurnkParser.parse` admits every
+- §send-mid-reservation WAIT is reserved ({§turn-disposition}).
+  A turn admits any number of lifecycle declarations, anywhere among its
+  operations ({§disposition-anywhere}); the runtime executes them last, as one park.
+- §disposition-anywhere A disposition may sit anywhere in a model turn
+  without imposing a program boundary. `PlurnkParser.parse` admits every
   operation before and after it in authored order; the runtime defers only the
-  disposition until the other admitted operations settle
+  dispositions until the other admitted operations settle
   ({§op-execution-order}). Nothing is dropped and no diagnostic is raised for
-  position. TASK omission does not synthesize a disposition ({§turn-shape}).
+  position. Omission does not synthesize a disposition ({§turn-shape}).
 - SEND is communication: an optional recipient path and an optional body.
-- §park-202-only TASK wait intent applies `<T>` (wait up to T minutes),
-  `<T,P>` (adds a poll cadence, mirroring EXEC's slot), `<-1>`
-  (indefinite; the join's own liveness bounds it). See §7 for the scope
-  slot's shape. Other intents leave timing unapplied
-  with a factual warning; timing does not override the inventory's intent.
-- §inventory-only-turn A TASK-only turn is valid for every inventory intent.
-  Actionable work does not require an invented OP and does not imply parking.
+- §park-202-only WAIT joins live work: an open stream or a live
+  child. With none, it continues. It takes no scope ({§send-wait-scope});
+  a future message is scheduled through the schedule family.
+- §lifecycle-only-turn A WAIT-, SEND-, or NOTE-only turn is valid.
+  NOTE does not request parking or acknowledge messages.
   Ordinary repetition, strike and execution limits still apply.
 
-SEND with no `(path)` responds to the Active Prompts without ending the turn. SEND with
+SEND with no `(path)` answers the open messages without ending the turn. SEND with
 `(path)` directs the message to that recipient. Neither changes loop status.
 
 ### §send-body SEND body projection
@@ -932,17 +998,22 @@ defines no synthetic scheme or READ-back convention for them.
 
 ## §parser-architecture 10. Parser architecture
 
+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.
 
 ```mermaid
 stateDiagram-v2
     [*] --> DEFAULT
+    DEFAULT --> QUOTATION: a fence that opens no operation
+    QUOTATION --> DEFAULT: its matching closer
     DEFAULT --> SLOTS: fenced native OP or executor
     SLOTS --> TARGET: (
     TARGET --> SLOTS: )
-    SLOTS --> METADATA: {
-    METADATA --> SLOTS: }
+    SLOTS --> METADATA: [
+    METADATA --> SLOTS: ]
     SLOTS --> BODY: header newline or tolerated inline body
     SLOTS --> DEFAULT: matching compact closer
     BODY --> DEFAULT: matching standalone closer, no nested block
@@ -960,13 +1031,13 @@ already ends in one. Interstatement whitespace belongs to no body.
 A header starts at column zero; the first operation may follow provider preamble
 without a separating newline. Text outside operation blocks is ignored in every
 parser tier: before, between, and after operations. It produces no AST item,
-message, receipt, or diagnostic. Exact source remains in `ops:///` under
+message, receipt, or diagnostic. Exact source remains in `ops://<worker>/` under
 {§turn-ops-log-curation}; body bytes and source positions are unchanged. A matching
 closer still ends its body, and no missing closer is inferred. No generic Markdown
 rendering, indentation stripping or recursive code-block extraction occurs.
 Only a header aside has aside semantics.
 
-## §public-api 12. Public API
+## 12. Public API
 
 The package root is the single JavaScript and TypeScript entry point. Shared AST
 and wire types come from generated schemas; the small hand-maintained parser
@@ -977,26 +1048,23 @@ express. Consumers never receive ANTLR parse-tree or token types.
 operation is reported by one hard diagnostic (`no valid Plurnk operation was
 found.`), which the host may admit as an empty turn rather than reject
 (plurnk-core `§empty-turn`). An explicit disposition may sit anywhere in it
-({§disposition-anywhere}). Omitted TASK
-means silent continuation: no synthesized statement, diagnostic, receipt,
+({§disposition-anywhere}). An omitted WAIT produces no synthesized statement, diagnostic, receipt,
 warning, or strike. The authored operations and source remain unchanged.
-Explicit empty or malformed inventories retain their own handling.
 Unfinished blocks never receive inferred closers.
-Bounded operation errors retain valid siblings. Duplicate dispositions
-and failed document boundaries remain structural failures.
+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}).
 
-`parseLog` reads consecutive saved turns separated by their dispositions and
-requires their dispositions; a saved turn is stored per turn, so a mid-turn
-disposition never needs splitting. There is no outer Markdown program wrapper;
-the executable blocks themselves are the program.
+The host records programs per turn; no operation acts as a separator between
+saved programs. There is no outer Markdown program wrapper; the executable
+blocks themselves are the program.
 
 §tier-entrypoints Each parser entry point owns one document tier:
 
 | Entry point                    | Accepted document                                              | Result statement type |
 |--------------------------------|----------------------------------------------------------------|-----------------------|
-| `PlurnkParser.parse`           | One operation-bearing model turn; at most one TASK, anywhere | `PlurnkStatement`     |
+| `PlurnkParser.parse`           | One operation-bearing model turn; at most one lifecycle declaration, anywhere | `PlurnkStatement`     |
 | `PlurnkParser.parseStatements` | Zero or more protocol statements                              | `PlurnkStatement`     |
-| `PlurnkParser.parseLog`        | One or more consecutive disposition-ended turns           | `PlurnkStatement`     |
 | `PlurnkParser.parseClient`     | Executable blocks, including the read-shaped LOOK command        | `ClientStatement`     |
 
 Every entry point ignores outside text under {§whitespace-contract} and returns
@@ -1004,26 +1072,28 @@ ordered `statement` and `error` items. When present, {§unparsed-tail-boundary}
 extent. The statement `op` field discriminates the generated per-operation
 union.
 
-§root-value-api The package-root runtime namespace is closed and consists of the
-following supported consumer values. All other root exports are TypeScript types.
-
-| Root value(s)                         | Consumer contract                                                   | Exact owner                                 |
-|---------------------------------------|---------------------------------------------------------------------|---------------------------------------------|
-| `PlurnkParser`                        | Four document-tier entry points listed above                        | {§parser-architecture}, {§tier-entrypoints} |
-| `PlurnkParseError`                    | JSON-serializable positioned parser diagnostic                      | {§parse-diagnostics}                        |
-| `parsePath`                           | Parser-equivalent target admission                                   | {§path-syntax}, {§tier-entrypoints}         |
-| `PathSyntax`                          | Target-slot spelling and exact-versus-glob classification           | {§path-parentheses}, {§path-glob}           |
-| `Validator`                           | Validation and assertion against the owning JSON Schemas            | {§wire-entrypoint}                          |
-| `InvalidNoticeError`                  | Typed failure from `Validator.assertNotice`                         | {§notice}                                   |
-| `InvalidProblemDetailsError`          | Typed failure from `Validator.assertProblemDetails`                 | {§problem-details}                          |
-| `InvalidProblemProjectionError`       | Typed failure from `Validator.assertProblemProjection`              | {§problem-projection}                       |
-| `InvalidOperationResultError`         | Typed failure from `Validator.assertOperationResult`                | {§operation-result}                         |
-| `InvalidTextRegionError`              | Typed failure from `Validator.assertTextRegion`                     | {§text-region}                              |
-| `InvalidRangeExtentError`             | Typed failure from `Validator.assertRangeExtent`                    | {§range-extent}                             |
-| `Problems`                            | RFC 9457 Problem construction and model projection                  | {§problem-details}, {§problem-projection}   |
-| `PLURNK_OPS`                          | Runtime tuple from which the closed `PlurnkOp` union is derived     | {§canonical-statement}                      |
-| `WORKER_NAME`, `RESERVED_AUTHORITIES` | Authority minting predicate and internal reserved names             | {§worker-name}                              |
-| `UNKNOWN_POSITION`                    | Frozen sentinel for an AST statement without retained parsed source | {§parser-position}                          |
+§root-value-api The package-root runtime namespace is closed. Its exact membership has one home,
+`src/index.test.ts`, which fails on any addition or removal; the table names the families and
+their owners. All other root exports are TypeScript types. `PlurnkParser` and `parsePath` are not
+among them: the parser is `@plurnk/plurnk-parser`'s ({§parser-consumers}).
+
+| Root value(s)                                       | Consumer contract                                                   | Exact owner                               |
+|-----------------------------------------------------|---------------------------------------------------------------------|-------------------------------------------|
+| `Validator` and one `Invalid…Error` per assertion   | Validation and typed failure against the owning JSON Schemas        | {§wire-entrypoint}                        |
+| `Problems`                                          | RFC 9457 Problem construction and model projection                  | {§problem-details}, {§problem-projection} |
+| `PlurnkParseError`                                  | JSON-serializable positioned parser diagnostic                      | {§parse-diagnostics}                      |
+| `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}                    |
+| `PROPOSAL_POLICIES`                                 | The vocabulary a loop policy chooses from                           | {§loop-policy}                            |
+| `WORKER_NAME`                                       | Authority minting predicate                                         | {§worker-name}                            |
+| `UNKNOWN_POSITION`                                  | Frozen sentinel for an AST statement without retained parsed source | {§parser-position}                        |
+
+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`).
 
 §parser-construction-boundary Parser construction components are internal rather
 than alternate consumer entry points:
@@ -1033,20 +1103,10 @@ than alternate consumer entry points:
 | `AstBuilder`                               | Consumes generated ANTLR contexts; `PlurnkParser` and `parsePath` own its API                                |
 | `PlurnkErrorStrategy`, `RecordingListener` | Assemble parser recovery and diagnostics around `antlr4ng`; consumers receive `PlurnkParseError` values       |
 
-### CLI
-
-```text
-plurnk-contracts [file]    parse a file, or standard input when omitted
-plurnk-contracts --help    show usage
-```
-
-The CLI prints the parse result as JSON. It exits `0` when no error item or
-`unparsedTail` exists and `1` otherwise.
-
 ## 13. Runtime-neutral wire contracts
 
 §wire-entrypoint The package root exports generated wire types, `Problems`, and
-`Validator` alongside the parser and AST. Their owning JSON Schemas are published
+`Validator` 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
@@ -1164,6 +1224,19 @@ Internal invariant violations throw and preserve their cause. An external
 protocol may require its own error envelope; its adapter maps that envelope to
 or from the canonical Problem without creating another PLURNK failure contract.
 
+§problem-error-carrier `Problems.fromError(error)` recognizes existing failure
+carriers without depending on a producer's exception class:
+
+| Carrier | Interpretation |
+|---------|----------------|
+| `error.result` present | Validate the complete {§operation-result}; return its Problem, if any |
+| Otherwise, `error.problem` present | Validate and return {§problem-details} unchanged |
+| Absent or malformed carrier | Return `null`; the caller retains the original exception as an unexpected failure |
+
+Recognition never derives recovery text from an exception message, changes its
+status, or rescues a malformed result through a second Problem field. Unexpected
+accessor or validator exceptions propagate.
+
 §problem-projection `ProblemProjection` is the sole compact model-packet view of
 an exact `ProblemDetails`. `Problems.project(problem, context)` validates both
 representations and rejects a status that contradicts the enclosing row.
@@ -1225,22 +1298,23 @@ client ID plus symbolic secret, or neither for server-advertised Dynamic Client
 Registration fallback. A definition cannot combine those identity modes.
 
 §mcp-configuration-overlay `McpConfigurationOverlay` is the bounded raw
-configuration projection a client may carry to MCP list and enable actions. It
-contains only string-valued `PLURNK_MCP_*` server declaration variables;
-service-owned connection/request timeouts and default enabledness are excluded.
+configuration projection a client may carry to MCP list and enable actions: its
+string-valued `PLURNK_MCP_*` variables, whole. Which of those names are the
+host's own controls is the host's fact alone — its parser skips every control
+it owns, so a carried timeout or enabled list has no effect and no client or
+contract restates that vocabulary.
 The client does not interpret this map. The MCP host composes it over the
 lower normalized definition through the same parser that admits service
 environment declarations, then validates the resulting
 `McpServerDefinition`. Carrying the overlay does not connect, persist, or
 expand credentials by itself.
 
-`SkillDefinition` is the one definition the Worker `skills` Functionality
-family accepts and persists: the standard Agent Skills `name` (the directory
-name), the universal root `scope` (`project` or `global`), and — for a
-Worker-installed skill — the standard installer package `source` that
-provides it. `Validator.assertSkillDefinition` is the family's admission
-boundary; the filesystem under the scope's root, never the definition, is the
-truth about installation.
+`SkillDefinition` is the one definition the workspace `skills` Functionality
+family accepts and persists: the standard `name`, source `scope`, and optional
+installer `source`. `Validator.assertSkillDefinition` validates the wire shape;
+the schema's name grammar is exposed as `SKILL_NAME` for loaders and discovery
+({§agent-skills-name}). Core owns installation truth and lifecycle
+({§skills-functionality}).
 
 `A2aAgentDefinition` is the one definition the Worker `a2a` Functionality
 family accepts and persists: the local alias `name` (the `a2a://<name>`
@@ -1264,11 +1338,22 @@ interaction, and event owners through this port.
 from user-authored prompt content. An adapter may expose no public means to set
 it; Core validates and records it through the same prompt admission path.
 
+`runLoop.attachments` carries typed bytes selected by the adapter;
+`runLoop.envelope` retains opaque protocol evidence under
+{§message-envelope-evidence}. `readMessages` projects durable inbox messages
+and successful conversation replies independently of log visibility, retaining
+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` (`conversation`; `fork` for a
 child carrying a fork boundary; `work` for any other child), and `lifecycle`,
-the worker's latest work loop projected through {§loop-lifecycle-vocabulary} (`idle`
-when it has none). Maintenance-only loops do not change this projection;
+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`
@@ -1286,9 +1371,7 @@ in `@plurnk/plurnk-contracts` is that projection's one owner.
 §application-loop-observation Loop observation exposes the durable scheduler
 state of work loops (excluding maintenance-only administrative loops), exact terminal `OperationResult`, and exact count of packet-bearing
 Turns for one owned Worker. Packetless producer Turns and physical provider
-retries do not contribute to `packetCount`. Scheduled tasks expose `scheduledAt`
-(ISO date), optional `intervalMinutes`, and `recurrenceId` (the original task id).
-Packet notifications carry the same timing; ordinary tasks omit it. Exterior
+retries do not contribute to `packetCount`. Exterior
 adapters consume this projection instead of reconstructing lifecycle from
 events or persistence; events remain the live notification edge.
 
@@ -1307,7 +1390,6 @@ class PlurnkParseError extends Error {
     readonly column: number;
     readonly source: ErrorSource;
     readonly severity: Severity;
-    readonly code?: "invalid-turn-structure";
 }
 ```
 
@@ -1345,10 +1427,8 @@ and 3.30.2](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html).
 the sole and complete owner of syntax-error messaging because it holds the
 parse state, lexer mode, and expected-token set that no consumer has. It
 produces the final diagnostic message, deduplicated expected-token lists, and
-turn-shape diagnostics ({§turn-shape}). Omitted TASK produces no diagnostic, and
-neither does the position of a present one ({§disposition-anywhere}). A failed
-document boundary carries `code: "invalid-turn-structure"`, which cannot be
-recovered as an individual failed operation. Source with no
+turn-shape diagnostics ({§turn-shape}). An omitted lifecycle declaration produces no diagnostic, and
+neither does the position of a present one ({§disposition-anywhere}). Source with no
 parsed operation yields `no valid Plurnk operation was found.` Targeted
 diagnostics are:
 
@@ -1358,9 +1438,7 @@ diagnostics are:
   its flags (`/(?i)shutdown|reactor/` is `/shutdown|reactor/i`; `^(?i)note:` is the
   anchored regex with `i`), with one warning-severity advisory naming the flag
   position after the closing `/`. Only a leading group of `i`, `m` and `s` lifts;
-  `(?i:…)` scoped modifiers are valid ECMAScript and pass through untouched. From
-  the 2026-09-13 dumbox demo pass, where the model wrote the inline form, was
-  refused, and rewrote it as a trailing flag one turn later.
+  `(?i:…)` scoped modifiers are valid ECMAScript and pass through untouched.
 - §regex-trailing-text A valid `/pattern/flags` prefix followed by horizontal
   whitespace and trailing text receives one concise trailing-content
   diagnostic, with or without flags, without assuming what the extra text was
@@ -1371,7 +1449,9 @@ diagnostics are:
   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`. Those
-  operations take no body, so heading-line text can mean nothing else. On EDIT only
+  matchers remain independent of owner options: a block without `pattern` never
+  erases the heading matcher, and invalid blocks still reach the owning validator.
+  These operations take no body, so heading-line text can mean nothing else. 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
@@ -1381,8 +1461,7 @@ diagnostics are:
   `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 (reasoning:///1/1) ^NOTE:.*` selects a turn's note lines (operator,
-  2026-09-12: "Recursive Reasoning").
+  `READ (notes.md) ^Decision:.*` selects lines beginning with `Decision:`.
 - §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
@@ -1390,9 +1469,8 @@ diagnostics are:
   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
-  (operator, 2026-09-13: "swallow up anything that passes as legitimate plurnk"; the
-  2026-09-13 dumbox run refused three headings for this in one turn). A matcher that
+  one warning-severity advisory naming the canonical order for the scope or block:
+  the grammar swallows up anything that passes as legitimate plurnk. A matcher that
   itself ends in one of those shapes takes the option escape.
 - §matcher-body-redirect **A body beneath those headings.** Text below the heading
   of a FIND, READ or KILL is a body, and those operations take none: the builder
@@ -1413,7 +1491,7 @@ diagnostics are:
 - §invalid-scope-diagnostic **Malformed scope content.** After a properly spaced
   scope opener, report the offending scope (at most 64 code points, ending at
   `>` or the heading's line end) and its operation's constraint: FIND result
-  positions, EXEC/TASK minutes, text coordinates, or no scope. Do not append advice for
+  positions, execution minutes, text coordinates, or no scope. Do not append advice for
   other operations or infer why the producer supplied the value. Spacing and
   boundary-loss diagnostics retain their own contracts.
 - §misplaced-aside-advisory **Aside in the body.** A READ or FIND whose
@@ -1427,7 +1505,10 @@ diagnostics are:
   ({§matcher-body-redirect}).
 
 §error-shape The diagnostic class determines how much guidance the parser may
-provide:
+provide. Advisories belong to one successfully built statement. A rejected
+statement emits its hard diagnostic, not normalization advisories; neither a
+rejection nor an internal exception carries advisories into another statement
+or parser invocation.
 
 | Class                  | Surface               | Message contract                                                                          |
 |------------------------|-----------------------|-------------------------------------------------------------------------------------------|
@@ -1449,7 +1530,7 @@ Examples of canonical hard facts:
 - `unrecognized character '<' in target`
 - `unexpected bracket modifier; the fence name selects the executor`
 - `unrecognized character 'X' in statement header`
-- `TASK's body begins below the header`
+- `WAIT's body begins below the header`
 - `expected ')'; got ':'`
 
 Each malformed statement produces at most one hard error. The first recorded
@@ -1466,7 +1547,9 @@ without a closer is not such a case: it ends under {§closer-fallback}. `ParseRe
 before that point; recovered contexts and diagnostics at or beyond it are not
 public results. The tail is one separate boundary fact, not an additional
 malformed-statement diagnostic. Consumers must treat anything from that point
-onward as undefined and must never dispatch a recovered statement from it.
+onward as undefined and must never dispatch a recovered statement from it; the
+facts before it are ordinary facts, and a consumer that runs them owes the
+author the tail's reason.
 
 | Consumer duty      | Contract                                                                                                       |
 |--------------------|----------------------------------------------------------------------------------------------------------------|
@@ -1485,6 +1568,6 @@ runtime constructs this; the parser provides the fields):
     "column": 12,
     "source": "parser",
     "severity": "error",
-    "message": "READ block opened at line 1 but was not closed with 3 backticks"
+    "message": "READ block opened at line 1 but was not closed with 4 backticks"
 }
 ```