@plurnk/plurnk-contracts 6.0.0 → 7.0.0

package/SPEC.md

@@ -1,129 +1,22 @@
 # PLURNK Contracts Specification
 
-## 1. Overview
+## §contract-representations 1. Overview and schema representations
 
-<!-- map -->
-| Tag | Promise |
-| --- | --- |
-| {§contract-representations} | JSON Schema is authoritative for shared data shapes. |
-| {§agui-discovery-contract} | `AguiDiscovery` is the complete installed AG-UI+ surface at one instant. |
-| {§agui-action-schema-enforcement} | The JSON Schema values in {§agui-discovery-contract} are executable boundary contracts, not prose or hints. |
-| {§agui-client-conformance} | `AguiClientConformance` is a language-neutral JSON document accounting for every action and notification in… |
-| {§agui-conformance-kit} | `AguiConformanceKit` is the one versioned, language-neutral corpus of raw SSE boundary specimens and AG-UI… |
-| {§json-result-rendering} | `renderJsonResult` renders compact aggregate operation rows. |
-| {§json-document-presentation} | Generated JSON documents use two-space indentation. |
-<!-- /map -->
-
-This package is the single authority for PLURNK's language, schemas, generated types and
-runtime-neutral wire envelopes; `@plurnk/plurnk-parser` implements the language it specifies
-({§parser-consumers}). Its package root is the single code API for those contracts
-({§root-value-api}).
-
-| Surface                                                                         | Canonical export or artifact                        |
-| ------------------------------------------------------------------------------- | --------------------------------------------------- |
-| AST, validators, Problems, results, Notices, text regions and extents          | `@plurnk/plurnk-contracts`                          |
-| Capability admission and approval ownership | `CapabilityPolicy`, `WorkerOwner`, `ProposalPolicy`, `PROPOSAL_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` |
-| Client capability presentation                                                 | `ClientDisplayCapabilities`                         |
-| Exterior adapter application calls                                             | `ApplicationPort`, from `@plurnk/plurnk-contracts/port` ({§runtime-neutral-root}) |
-| Workspace MCP configuration                                                    | `McpServerDefinition`, `McpOAuth` |
-| Worker Agent Skills definition                                                 | `SkillDefinition` |
-| Worker outbound A2A agent definition                                           | `A2aAgentDefinition` |
-| Worker Functionality lifecycle projections (family-neutral)                     | `FunctionalityProvenance`, `FunctionalityCandidate`, `FunctionalityDiscoverQuery`, `FunctionalityDiscoverResult`, `FunctionalityDefinitionState`, `FunctionalityListResult`, `FunctionalityMutationResult` |
-| AG-UI discovery, client accounting, and shared conformance specimens           | `AguiDiscovery`, `AguiClientConformance`, `AguiConformanceKit` |
-| JSON Schemas                                                                    | `@plurnk/plurnk-contracts/schema/*.json`            |
-| Generated JSON result rendering                                                 | `renderJsonResult`                                  |
-| Model language reference                                                        | `plurnk.md` in the package                          |
-
-§contract-representations JSON Schema is authoritative for shared data shapes. TypeScript types are
-generated from the schemas; ANTLR is authoritative for accepted model-language
-syntax. An operator's own GBNF is carried verbatim to a llama-server route by
-the providers package.
-
-§agui-discovery-contract `AguiDiscovery` is the complete installed AG-UI+
-surface at one instant. `schemaVersion` identifies its discovery shape;
-`actions` maps each unique public name to exactly one `scope`, `inputSchema`,
-and `outputSchema`; `notifications` maps each unique event-family name to one
-`payloadSchema`; and `display` carries {§client-display-capabilities} without
-another presentation mechanism. The AG-UI owner supplies the built-in registry;
-an extension contributes the same schema-bearing action descriptor through its
-core module registration rather than creating a second action type.
-
-§agui-action-schema-enforcement The JSON Schema values in
-{§agui-discovery-contract} are executable boundary contracts, not prose or
-hints. The AG-UI boundary rejects an action input before dispatch when it does
-not satisfy the advertised `inputSchema`, rejects an owner's successful output
-when it does not satisfy `outputSchema`, and validates a known notification
-before projecting it to AG-UI. Schemas are discovery values owned by their
-registrants; validation must not annotate or otherwise mutate them.
-Input Problems retain the structured validation `issues` and name the failing
-instance locations and constraints in `detail`. Parent aggregate errors are
-omitted from that prose when their specific child errors are available; input
-objects are never echoed wholesale or interpreted as intent.
-
-§agui-client-conformance `AguiClientConformance` is a language-neutral JSON
-document accounting for every action and notification in one
-{§agui-discovery-contract}. Each name is classified as `native` (dedicated
-client behavior), `generic` (lossless protocol support without dedicated UI),
-or `unsupported` with an explicit reason, and cites nonempty verification
-evidence. Each disposition declares the exact verification dimensions its
-evidence covers; native behavior includes admission and presentation, every
-action includes projection plus success and failure, and every notification
-includes framing plus projection. Validation requires exact action and
-notification key equality with the installed discovery surface; adding or
-removing a public capability therefore breaks every stale client matrix
-visibly. The contracts-owned report procedure resolves every cited evidence
-path and emits one record per member with its posture and verified dimensions;
-a stale or fictional citation fails the report.
-
-§agui-conformance-kit `AguiConformanceKit` is the one versioned,
-language-neutral corpus of raw SSE boundary specimens and AG-UI lifecycle
-sequences used by every client transport. Its JSON resource is test input, not
-a third protocol implementation: each client feeds the same chunks and events
-through its production parser and projection seam, then verifies the declared
-outcome. Specimen names are unique within their transport or lifecycle family.
-
-§json-result-rendering `renderJsonResult` renders compact aggregate operation
-rows. A top-level array remains one valid,
-compact JSON value but places each item on its own physical line by adding only
-item-boundary newlines; an empty or single-item array and every non-array value
-remain one line. It never rewrites arbitrary stored JSON, whose original lines
-remain source coordinates.
-
-§json-document-presentation Generated JSON documents use two-space indentation.
-Normalized remote JSON text uses `formatJsonDocument`: whitespace-only formatting
-of a complete, strict JSON document, preserving key order, duplicate keys, number
-lexemes, and string escapes. Invalid or incomplete input is declined, not repaired.
-Apply formatting at the representation owner before storage, indexing, scoping,
-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.
+`@plurnk/plurnk-contracts` is the single authority for PLURNK's model-facing language specification, JSON Schemas (`schema/*.json`), generated TypeScript types, and runtime-neutral wire envelopes. `@plurnk/plurnk-parser` implements the language it specifies ({§parser-build}).
 
-## 1.1 Contract layers and admission boundary
-
-<!-- map -->
-| Tag | Promise |
+| Surface | Canonical export or artifact |
 | --- | --- |
-| {§contract-proposal-projection} | Admission policy and stopped-world projection |
-| {§capability-policy-matching} | A selector is an exact conjunction: every field it declares must equal the descriptor, while every selected… |
-| {§capability-policy-cascade} | Capability layers are purely subtractive and order-independent: a descriptor is admitted only when every… |
-| {§capability-policy-projection} | A `CapabilityProjection` reports every durable workspace layer and their normalized intersection: `service`,… |
-| {§proposal-policy} | `ProposalPolicy` names one server disposition; `PROPOSAL_POLICIES` is its schema-owned vocabulary. |
-| {§effort-wire} | `Effort` is exactly `off \| adaptive \| low \| medium \| high \| xhigh \| max`. |
-| {§model-catalog-wire} | `ModelRoute` is one exact client-visible provider/model identity with optional alias provenance. |
-| {§client-interaction-wire} | Client-owned interaction wire |
-| {§provider-usage} | `ProviderUsage` records only known non-negative safe-integer quantities. |
-| {§provider-cost} | `ProviderCost` represents one physical provider request's monetary disposition. |
-| {§provider-request-accounting} | `ProviderRequestAccounting` is the indivisible accounting fact for one issued physical request. |
-| {§provider-request-evidence} | The physical-request settlement may also carry JSON-serializable, provider-owned response/failure evidence. |
-| {§provider-accounting} | `ProviderAccounting.requests` is the source evidence. |
-<!-- /map -->
-
-One contract, deliberately different projections (ARCHITECTURE.md). Each layer
-below owns what it alone can decide.
+| AST, validators, Problems, results, Notices, text regions and extents | `@plurnk/plurnk-contracts` |
+| Capability admission and approval ownership | `CapabilityPolicy`, `SessionOwner`, `ProposalPolicy`, `PROPOSAL_POLICIES` |
+| Durable effort and model catalog discovery | `Effort`, `EFFORTS`, `ModelRoute`, `ModelCatalogQuery`, `ModelCatalogPage`, `ModelReadiness` |
+| Stopped-world proposals and client interactions | `ProposalDisposition`, `ProposalProjection`, `ClientInteractionRequest`, `ClientInteractionProjection`, `ClientInteractionResolution` |
+| Client capability presentation | `ClientDisplayCapabilities` |
+| Exterior adapter application calls | `ApplicationPort`, from `@plurnk/plurnk-contracts/port` |
+| Workspace MCP and Agent Skills definitions | `McpServerDefinition`, `McpOAuth`, `SkillDefinition` |
+| Session Functionality lifecycle projections | `FunctionalityProvenance`, `FunctionalityCandidate`, `FunctionalityDiscoverQuery`, `FunctionalityDiscoverResult`, `FunctionalityDefinitionState`, `FunctionalityListResult`, `FunctionalityMutationResult` |
+| ACP discovery manifest | `AcpDiscovery` |
+| JSON Schemas and JSON rendering | `@plurnk/plurnk-contracts/schema/*.json`, `renderJsonResult`, `formatJsonDocument` |
+| Model language reference | `plurnk.md` in the package |
 
 ```mermaid
 flowchart LR
@@ -139,2004 +32,215 @@ flowchart LR
     ast --> runtime
 ```
 
-| Layer                    | Owner or artifact                   | Contract                                                                        |
-|--------------------------|-------------------------------------|---------------------------------------------------------------------------------|
-| Stable current law       | `SPEC.md`                           | Owns invariants and boundaries; forge issues retain history                     |
-| Canonical model teaching | `plurnk.md`                         | Teaches the lean spelling and operational model the model should emit           |
-| Accepted syntax          | `plurnkLexer.g4`, `plurnkParser.g4` | Recognizes document tiers, operation fences, slot shape, and section boundaries    |
-| Typed admission          | `AstBuilder`                        | Produces JSON-serializable unions and validates deterministic body/path syntax  |
-| Shared wire data         | `schema/*.json`                     | Defines runtime-neutral data shapes projected into generated TypeScript         |
-| Stateful behavior        | consuming runtime                   | Resolves addresses, permissions, selection arithmetic, effects, and lifecycle   |
-
-ANTLR owns statement structure, fence matching, slot multiplicity, accepted
-slot permutations, scope-number syntax, and interstatement text recognition.
-AstBuilder owns URL decomposition and deterministic matcher validation through
-WHATWG `URL`, ECMAScript `RegExp`, XPath 1.0, and RFC 9535 JSONPath parsers.
+| Layer | Owner or artifact | Contract |
+| --- | --- | --- |
+| Stable current law | `SPEC.md` | Owns invariants and boundaries; forge issues retain history |
+| Canonical model teaching | `plurnk.md` | Teaches the lean spelling and operational model the model should emit |
+| Accepted syntax | `plurnkLexer.g4`, `plurnkParser.g4` | Recognizes document tiers, operation fences, slot shape, and section boundaries |
+| Typed admission | `AstBuilder` | Produces JSON-serializable unions and validates deterministic body/path syntax |
+| Shared wire data | `schema/*.json` | Defines runtime-neutral data shapes projected into generated TypeScript |
+| Stateful behavior | consuming runtime | Resolves addresses, permissions, selection arithmetic, effects, and lifecycle |
 
-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, and executor behavior.
+- **Authoritative representations**: JSON Schema is authoritative for shared wire data shapes; TypeScript types are generated from `schema/*.json`; ANTLR grammars in `@plurnk/plurnk-parser` are authoritative for accepted model-language syntax.
+- **ACP discovery and schema enforcement**: `AcpDiscovery` enumerates the installed ACP v2 actions (`scope`, `inputSchema`, `outputSchema`), notifications (`payloadSchema`), and `display` capabilities. Boundary validators enforce these schemas without mutating them and report structured validation `issues` in RFC 9457 Problem `detail`.
+- **JSON result and document presentation**: `renderJsonResult` formats compact aggregate operation rows (placing top-level array items on individual lines without rewriting stored JSON coordinates). `formatJsonDocument` performs two-space whitespace-only formatting of complete strict JSON documents before representation storage.
 
-### §contract-proposal-projection Admission policy and stopped-world projection
+### §capability-policy-cascade Capability admission, proposals, and model catalog
 
-The schemas own the runtime-neutral shapes; core owns their stateful values.
+```mermaid
+flowchart LR
+  S["Service CapabilityPolicy"] & W["Workspace CapabilityPolicy"] --> E["Effective intersection (deny > only > allow)"]
+  E --> D{"Admitted?"}
+  D -->|no| R["403 capability-denied"]
+  D -->|yes, allow match| A["Auto-accepted execution"]
+  D -->|yes, gated| P["ProposalDisposition (review | accept | reject)"]
+```
 
-| Contract                  | Shape invariant                                                                 | Runtime responsibility                                                                 |
-| ------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `CapabilityDescriptor`    | One routed operation demand with its operation, access class, resource/runtime/tool coordinates, and declared traits | Derive every demand before dispatch |
-| `CapabilityPolicy`        | Exact `only`/`deny` selectors; omitted `only` is unrestricted and present empty `only` denies all | Intersect service and workspace layers |
-| `CapabilityProjection`    | Exact service, workspace, and normalized effective policies | Expose the resolver's workspace cascade without claiming one layer is effective authority |
-| `WorkerOwner` | Nonempty address, unique client-tool names, and whether it is interactive | Persist by workspace; inherit through worker creation |
-| `ProposalPolicy` | `review`, `accept`, or `reject` | Read the server's disposition knob at the proposal boundary |
+| Contract | Shape invariant | Runtime responsibility |
+| --- | --- | --- |
+| `CapabilityDescriptor` | One routed operation demand with its operation, access class (`read \| write \| exec \| network \| session \| interact`), resource/runtime/tool coordinates, and declared traits | Derive every demand before dispatch |
+| `CapabilityPolicy` | Exact `allow`/`only`/`deny` selectors; omitted `only` is unrestricted, present empty `only` denies all, and `allow` pre-approves admitted proposals | Intersect service and workspace policies |
+| `CapabilityProjection` | Durable `service`, client-mutable `workspace`, and normalized `effective` policies | Expose effective authority without storing session/loop policy copies |
+| `ProposalPolicy` | `review`, `accept`, or `reject` (`PROPOSAL_POLICIES`) | Read the server's disposition knob at the proposal boundary |
 | `ProposalDisposition` | Review, or automatic accept/reject with optional outcome | Select once for the pending gate |
-| `ProposalProjection` | Identity, review target, body/attrs, owner, stale signal, disposition | One validated projection for live delivery and reconnect |
-| `ProviderUsage`           | Conventional input/output totals with cache and reasoning details                | Preserve observed quantities without replacing absence with zero                        |
-| `ProviderCost`            | Exact charged, estimated, or unknown monetary evidence                           | Normalize one monetary disposition for each physical provider request                    |
-| `ProviderRequestAccounting` | Usage and cost evidence for one physical provider request                      | Preserve request order across retries, failover, success, and failure                    |
-| `ProviderAccounting`      | Ordered requests plus deterministic usage and exact-USD projections              | Derive loop, protocol, telemetry, and client reporting without a second authority        |
-
-§capability-policy-matching A selector is an exact conjunction: every field it
-declares must equal the descriptor, while every selected `trait` must occur in
-the descriptor's trait set. `deny` wins within a layer. When `only` is present, at
-least one selector must match. An empty policy admits everything and an empty
-`only` list admits nothing.
+| `ProposalProjection` | Identity, review target, body/attrs, owner, capability selector, ACP v2 subject, stale signal, disposition | One validated projection for live delivery and reconnect |
 
-§capability-policy-cascade Capability layers are purely subtractive and
-order-independent: a descriptor is admitted only when every layer admits it.
-Workspace policy cannot restore authority denied by the service. A
-composed operation is admitted only when every routed demand survives. These
-descriptors govern routed external authority, not every grammar statement:
-log/program control such as log KILL, the native dispositions, and
-targetless SEND creates no capability demand. A known interactive runtime is represented by
-access class `interact`; scheme and runtime manifests contribute traits rather
-than hidden policy behavior.
+- **Exact selector conjunction**: A capability selector matches a `CapabilityDescriptor` when every declared field equals the descriptor and every declared `trait` occurs in the descriptor's trait set. Within a policy layer, `deny` wins over `only` and `allow`; when `only` is present, at least one selector must match. An empty policy admits everything; an empty `only` list admits nothing.
+- **Subtractive cascade**: Capability admission is purely subtractive and order-independent: a descriptor is admitted only when every active layer (`service` and `workspace`) admits it. Workspace policy cannot restore authority denied by the service. A demand is pre-approved across layers only when it is admitted across every layer and matches at least one layer's `allow` selector. Log/program control (`KILL (log:///...)`, native dispositions `WAIT`/`NOTE`, and targetless `SEND`) creates no capability demand.
+- **Proposals and session ownership**: `ProposalPolicy` (`review | accept | reject`) and `SessionOwner` (`address`, `clientTools`, `interactive`) govern stopped-world approval after capability admission succeeds.
+- **Effort and model catalog wire**: `Effort` is `off | adaptive | low | medium | high | xhigh | max`. `ModelRoute`, `ModelCatalogPage`, and `ModelReadiness` expose provider/model identity, capabilities (including supported `efforts`), physical limits, and alternative required environment-variable name sets (names only, never values, credentials, or tuning internals).
 
-§capability-policy-projection A `CapabilityProjection` reports every durable
-workspace layer and their normalized intersection: `service`, `workspace`, and
-`effective`. Only `workspace` is client-mutable. Workers and loops store no
-capability policy and inherit no bound; every actor uses the same live workspace
-policy. Core derives one further ring per asking worker from its owner, and it only
-removes interaction runtimes ({§owner-interaction-ring}). A client never derives
-effective authority from the mutable layer alone.
-
-§proposal-policy `ProposalPolicy` names one server disposition; `PROPOSAL_POLICIES`
-is its schema-owned vocabulary. `WorkerOwner` carries an address, the client-tool
-names that recipient implements, and `interactive`: whether a person attends it. Neither
-contains resource permissions or
-message-carried authority. Core owns persistence, inheritance and settlement
-({§worker-ownership}, {§proposal-disposition}); capability admission precedes approval.
-
-§effort-wire `Effort` is exactly `off | adaptive | low |
-medium | high | xhigh | max`. 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.
-
-§model-catalog-wire `ModelRoute` is one exact client-visible provider/model
-identity with optional alias provenance. Provider credentials, endpoints, and
-tuning never enter this wire shape. Catalog discovery uses a
-closed bounded query and page: entries carry exact selectors, display facts,
-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.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.
-
-### §client-interaction-wire Client-owned interaction wire
-
-The closed client-interaction schemas describe one operation asking its client
-for structured input without transferring private protocol continuation state.
+### §provider-request-accounting Client interactions and provider request accounting
 
 | Contract | Shape invariant |
-|---|---|
-| `ClientInteractionRequest` | Non-empty `toolName`, object `arguments`, optional non-empty `message`, and object `responseSchema` |
-| `ClientInteractionProjection` | Positive interaction, worker, loop, and turn identities plus the exact request; workspace scope remains the containing transport envelope |
-| `ClientInteractionResolution` | Exactly `{ status: "resolved", payload? }` or `{ status: "cancelled" }` |
-
-Opaque upstream request identities, retry state, credentials, and callbacks are
-not members of these schemas. The operation owner retains and interprets those
-facts; core and client interfaces carry only this standard interaction.
-
-§provider-usage `ProviderUsage` records only known non-negative safe-integer
-quantities. `inputTokens` includes every input category; cache reads and cache
-writes are details within it. `outputTokens` includes reasoning; text and
-reasoning are details within it. Within one physical request, `totalTokens`
-equals input plus output whenever all three are present, a detail is no greater
-than its containing total, and a complete detail partition sums to that total.
-An omitted field is unknown; an explicit zero is provider evidence or an exact
-derivation from complete known components. Consumers never estimate a token
-category from text length.
-
-§provider-cost `ProviderCost` represents one physical provider request's
-monetary disposition. `charged` preserves a provider-reported canonical decimal
-amount and currency, with an optional decimal USD equivalent for a non-USD
-charge. `estimated` preserves a calculated decimal amount and currency.
-`unknown` requires a reason. Zero is an ordinary exact amount under `charged`
-or `estimated`; there is no separate free mechanism. Decimal strings preserve
-evidence without binary floating-point rewriting. Unknown is not zero.
-
-§provider-request-accounting `ProviderRequestAccounting` is the indivisible
-accounting fact for one issued physical request. Its provider, model, outcome,
-optional protocol status, optional {§provider-usage}, and required
-{§provider-cost} travel together. Ordered request records preserve retries and
-capacity failover; a later response never replaces an earlier request.
-
-§provider-request-evidence The physical-request settlement may also carry
-JSON-serializable, provider-owned response/failure evidence. This is forensic
-data, separate from accounting and executable output. Consumers persist it
-with the same request, including failed requests before a successful retry;
-they never substitute it for an admitted response. Missing historical evidence
-remains absent. Heavy evidence is not copied into accounting or client events.
-
-§provider-accounting `ProviderAccounting.requests` is the source evidence.
-The projections are derived, not independent inputs:
+| --- | --- |
+| `ClientInteractionRequest` | Non-empty `toolName`, `mode: "form"` with non-empty `message` and object `requestedSchema`, or `mode: "url"` with non-empty `message`, non-empty `elicitationId`, and URI `url` |
+| `ClientInteractionProjection` | Positive interaction, session, loop, and turn identities plus the exact request; workspace scope remains the containing transport envelope |
+| `ClientInteractionResolution` | Exactly `{ action: "accept", content? }`, `{ action: "decline" }`, or `{ action: "cancel" }` |
 
 | Projection | Complete total | Known subtotal |
 | --- | --- | --- |
-| Tokens | Each `usage` field is present only if every request reports that quantity. | `knownUsage` sums each reported field, omitting wholly unknown quantities. Its detail sums need not form a complete partition. |
-| USD | `costUsd` is `null` if any request lacks USD-expressible cost. | `knownCostUsd` sums expressible costs, or is `null` when none are known. |
+| Tokens (`ProviderUsage`) | Each `usage` field (`inputTokens`, `outputTokens`, `totalTokens`, cache and reasoning details) is present only if every request reports that quantity; `totalTokens === inputTokens + outputTokens` when all three are present | `knownUsage` sums each reported non-negative safe-integer field, omitting wholly unknown quantities without substituting zero for unknown |
+| Monetary (`ProviderCost`) | `costUsd` is `null` if any request lacks USD-expressible cost (`charged` or `estimated` decimal string; `unknown` requires a `reason`) | `knownCostUsd` sums expressible USD costs as an exact decimal string, or is `null` when none are known |
 
-The empty request set projects explicit zero usage and cost in both columns.
-Unknown is never zero. Human presentations identify a subtotal as incomplete;
-comparative totals, ratios, and cost-per-success use only complete evidence.
-Consumers do not reconstruct rates or currencies from these projections.
+- **Indivisible request accounting and evidence**: `ProviderRequestAccounting` binds one physical request's provider, model, outcome, optional protocol status, `ProviderUsage`, and `ProviderCost` in issue order across retries and capacity failover; a later response never replaces an earlier request. JSON-serializable forensic response/failure payloads travel alongside as separate evidence without entering client events.
 
-The parser ignores outside text and returns ordered statement and error items
-under {§whitespace-contract}. It recovers at a
-trustworthy statement boundary when possible and sets `unparsedTail` when a
-boundary-destroying failure makes later input undefined. Operation status codes
-and parse diagnostics are separate contracts.
+---
 
-## §canonical-statement 2. Canonical statement form
-
-<!-- map -->
-| Tag | Promise |
-| --- | --- |
-| {§section-boundary} | Every statement is one backtick block. |
-| {§fence-closer} | A block opened with N backticks closes at a line made of at least N backticks and nothing else but horizontal… |
-| {§balanced-fences} | A complete nested interpretation takes precedence over missing-closer recovery. |
-| {§operation-fences} | Accept three or more backticks; teach and render three. |
-| {§naked-operation} | A native name with only an optional aside opens without a fence. |
-| {§fence-heading-in-body} | Outside a complete nested block ({§balanced-fences}), a fence line of three or more backticks carrying a… |
-| {§closer-fallback} | A block that ends at a heading or at the end of the input has no closer of its own; its body is the whole… |
-| {§fence-boundary} | Every fence line inside a body takes one of these meanings, chosen for the whole input at once by… |
-| {§fence-pairing} | Fence pairing |
-| {§pairing-need} | Why a pass ahead of the grammar. |
-| {§pairing-algorithm} | Algorithm. |
-| {§pairing-objective} | Objective. |
-| {§unclosed-mutation-yields} | A mutation body never swallows a native operation. |
-| {§prose-code-blocks} | A message or a prompt shows code. |
-| {§message-run-on} | A message runs to the end of the turn. |
-| {§pairing-witness} | Witnesses. |
-| {§indented-fences} | CommonMark's indentation, everywhere. |
-| {§inline-chain} | A closer on a heading line, or on a body's closing line, may be followed on that same line by the next… |
-| {§transparent-inline-closer} | A closer mid-heading is read as if it were not written. |
-| {§executor-case} | An executor tag in any case. |
-| {§executor-js-spelling} | When `node` is registered and `js` is not, `js` names `node` under {§executor-case}. |
-| {§one-line-turn} | A whole turn on one line. |
-| {§anchor-digits} | In a text scope, `@` followed by one to four digits cannot be a hash and is read as that line number, with… |
-| {§unclosed-aside} | A heading whose aside opens with `<!--` and never closes on its line takes the rest of the line as the aside,… |
-| {§quotation} | A fence that opens no operation quotes. |
-| {§forgotten-tag} | A tag on the line under a bare fence is the operation. |
-| {§executor-heading} | Syntax identifies an invocation; dispatch resolves its runtime. |
-| {§interstitial-fence} | Only a heading under {§executor-heading} opens an operation. |
-| {§closer-aside} | A closing fence followed on its line by one aside and nothing else is the closer; the aside is outside text. |
-| {§heading-slot-order} | A heading near-miss with exactly one reading is read as that reading, with no diagnostic and no teaching… |
-| {§native-tool-calls} | An emission that yields no operation may be a model's native tool-call markup naming a plurnk operation or a… |
-| {§native-tool-call-receipt} | Unexecuted native markup draws a warning. |
-| {§empty-section} | Both the compact bodyless form and an empty multiline block normalize optional bodies to null. |
-| {§statement-rendering} | `PlurnkParser.stringify` renders native OP names and named runtime fences from the shared AST, with one blank… |
-| {§slot-order} | Producers put target, scope, metadata, then aside, separated by one ASCII space. |
-| {§lifecycle-slots} | NOTE accepts no target, scope, or metadata. |
-| {§target-group} | READ and KILL take a target group. |
-| {§safe-uri-target-groups} | An explicit URI list is a target group. |
-| {§scope-on-scopeless} | A scope on an operation that takes none is dropped, and named. |
-| {§heading-inline-body} | Nonempty body text belongs below the fence header. |
-| {§bare-option-object} | A bare option object is the option block, where the house option array owns the block. |
-| {§operation-aside} | The final header modifier may be one single-line HTML comment. |
-| {§scheme-metadata-modifier} | A target may carry one single-line `[metadata]` block, placed under {§slot-order}; executor and SEND fences… |
-| {§matcher-option} | `pattern` is the matcher, and it lives in the heading. |
-<!-- /map -->
+## §operation-fences 2. Canonical statement form and operation fences
 
 `````text
 ```OP (path)? <scope>? [metadata]? <!-- aside -->?
 body
 ```
 
-```OP (path)? <scope>?
-```
-
 ```executor (program-or-tool)?
 input
 ```
 `````
 
-§section-boundary Every statement is one backtick block. Its header occupies one
-physical line: a fence of at least three backticks ({§operation-fences}), 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. Complete nested matches take precedence
-over local recovery ({§balanced-fences}).
-
-§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, a line-leading labeled fence opens a literal block, and an equal or
-wider bare fence nests unless closing there costs the reading less
-({§fence-pairing}). A nested block ends at its first valid closer, as a CommonMark code block
-does. So a wider outer fence holds any narrower body, finished or not, and equal widths nest
-when every inner block closes. Preserve every nested body byte, including apparent operations
-and executor invocations, 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 carrying an operation heading ({§executor-heading}) opens that
-operation ({§indented-fences}), and no width draws a receipt. Three is the taught form and the
-rendered form; a wider fence is the same statement, and it is how a body holding fence lines of
-its own is held: an opener wider than any of them ({§balanced-fences}). Enclosing quotations
-remain inert ({§quotation}), and a fence inside an intact block is never promoted to an
-operation ({§fence-heading-in-body}). `plurnk.md` teaches exactly three and shows the wider
-fence only as the nesting form. Every producer of a statement — the parser, a client composing
-`/look`, a client's tab-completion — writes `PLURNK_FENCE` rather than its own literal
-(plurnk/plurnk#92).
-
-§naked-operation **A native name with only an optional aside opens without a fence.** A column-zero line outside any block containing a native operation's name and at most one complete `<!-- aside -->`, with only horizontal whitespace otherwise, opens that operation as if it were fenced with the taught three backticks. The aside retains its ordinary meaning: no target or modifiers are inferred. One warning-severity receipt follows a recovered statement — `` `NOTE` opened with no fence; the taught form is three backticks. `` One rule for every native operation: a naked `WAIT` parks, a naked `NOTE` takes its text, a naked `READ` meets the ordinary missing-target refusal. Executors are runtimes rather than operations, and reasoning is never read this way.
-
-| Fact | Rule |
-| --- | --- |
-| The body | runs to a line that is exactly the name again, to the next heading ({§fence-heading-in-body}), or to the end of the turn; a fence inside naming nothing known is body; the block expects no closer, so its body is never cut back ({§closer-fallback}) |
-| A closer the author wrote anyway | still not body: when the body's last line is a bare backtick fence that no other fence line in the body pairs with (an odd count of fence lines), that line is the block's closer and leaves the body, so `SEND`, then the answer, then a closing fence delivers the answer alone; an aside-bearing name inside a body is not a closer |
-| Not the form | an incomplete or repeated aside, an operand, or other heading text does not qualify and remains the unfenced form ({§unfenced-operation}) |
-
-§fence-heading-in-body Outside a complete nested block ({§balanced-fences}), a fence
-line of three or more backticks carrying a heading under {§executor-heading}
-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. {§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`.
-
-§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 {§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 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 |
-|---|---|
-| Indented four spaces or more, or by a tab | Body ({§indented-fences}) |
-| 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, without an operation heading | The opener of a nested block, or body |
-| Three or more backticks with an operation heading ({§executor-heading}) | 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}). Heading shape comes from the same grammar and
-AST interpretation as normal admission, including recovered operand order and target notation;
-fence pairing does not infer slot ownership from raw text. 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. Evaluation runs on an explicit work stack.
-
-| Step | Rule |
-| --- | --- |
-| Summaries | a block's contents read the same whatever lies beneath it on the stack, so the pass summarizes each (position, block, what the block holds so far) once; for a nested block, the summary maps every place the block could end to its cheapest reading up to there, and parents compose their children's summaries; an outermost block is evaluated in the root's frame, where only the cost to the end of the input matters, so it holds one entry |
-| Candidates | taken in preference order and replace one another only by costing strictly less, so each entry is the reading a preference-ordered exhaustive search returns |
-| Closers | inside a quotation or a nested block the first valid closer closes, CommonMark's rule, applied as a disambiguation filter (Klint and Visser, 1994); an operation body keeps the choice between nesting and closing |
-| A block opened by a bare fence | must hold a line, except a quotation at the top level: two stray fences in a row there are an empty quotation, shown and harmless, rather than two repairs that a reading could avoid only by hiding an operation |
-
-§pairing-objective **Objective.** A complete reading, one that needs no repair, wins over every
-repaired reading: a complete nested interpretation takes precedence. Each class has its own order.
-
-| Counted | Complete readings | Repaired readings | Why |
-|---|---|---|---|
-| Hidden operations: a heading that will not run, written at its block's width or wider | 1, together with discarded code | 1 | Every operation the author wrote should run |
-| Repairs: a supplied closer (except a message's run to the end of the input, {§message-run-on}), a fence read as a stray, a narrower closer accepted, a body under an operation that takes none (COPY, MOVE, non-log targeted KILL), a body not well-formed in the media type its runtime declares ({§executor-invocation}) | none by definition | 2 | The least-errors distance |
-| Literal by declaration: a heading narrower than its block, or no wider than the labeled block or example holding it, or inside a quotation or a KILL, or an executor heading shown as a code block inside a SEND, WORK, FORK or BARE body ({§prose-code-blocks}) | none: the author's enclosure wrote it as an example | 3, together with the row below | A heading the author wrapped is the example it was written as |
-| Discarded code: a labeled fence in a body read as text, or such an executor heading read as text | 1, together with hidden operations | 3, together with the row above | Every code block the author declared should stand |
-| Supplied closers | 2 | 4 | A block the author opened should end at a fence the author wrote |
-| Other fences read as text | 3 | 5 | The least departure from the fences as written |
-
-Complete readings compare as a single least-errors order over departures from the fences as written, and a heading the author enclosed in a wider or labeled fence is the example it was written as, not a departure.
-
-| Rule | What |
-| --- | --- |
-| A narrower message fence | a message whose own fence is narrower than the fences wrapping its examples still holds them: the reading that lets a wrapper close the message and runs the examples ties on cost and loses on preference, since a body nests before it closes ({§balanced-fences}) |
-| A broken shape | once every reading of an emission needs a repair, its shape is already broken, and saving a repair is not worth an operation the author wrote |
-| The summary | keeps, for every place a block could end, the best complete reading under each order and the best repaired reading, so the search stays exact: a repaired total may take either class for any of its parts |
-
-§unclosed-mutation-yields **A mutation body never swallows a native operation.** An example inside an EDIT is written with a wider outer fence ({§operation-fences}); a heading narrower than the EDIT's fence is literal by declaration and stays text. At the EDIT's own width a native operation heading runs, closed or not: read as the body's example it would be a *swallowed* operation, and a swallowed operation outranks any number of repairs — a reading that swallows one is never complete, and among repaired readings the fewest swallowed wins before every other class. Only EDIT mutates from its body, so only EDIT carries the rule: an executor heading inside an EDIT keeps the ordinary reading, and SEND, WORK, FORK and BARE bodies keep {§prose-code-blocks}.
-
-| Shape | Reading |
-| --- | --- |
-| ```` ```EDIT (b.py) ```` follows ```` ```EDIT (a.py) ```` with no closer between | the reading that supplies `a.py`'s closer before that heading wins, both EDITs run, and no operation heading is written into a file |
-| The same shape with a closer after the example | fence-identical, and reads the same way |
-
-Equal cost goes to the earlier alternative: nesting before closing in an operation body,
-closing before nesting in a quotation, and a supplied closer before a literal example at a
-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}).
-
-§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: 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 `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.
-
-§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
-same way: an opener within three spaces opens, a closer within three closes, a heading within
-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. 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
-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; 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.
-
-§executor-case **An executor tag in any case.** An executor heading matches a
-known executor's name case-insensitively (`SH` opens `sh`); its AST carries the
-registered spelling when known, otherwise the lowercase name. Native operation
-names remain case-sensitive. Recognition follows {§executor-heading}; availability
-and permission are checked at dispatch, not granted by a recognized spelling.
-
-§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. Literal inline bodies follow {§heading-inline-body}.
+- **Backtick block boundaries**: Every canonical statement is a fenced block opened at column 0–3 by three or more backticks (`PLURNK_FENCE` is ``` ``` ```) followed on the same physical line by an operation keyword (`FIND`, `READ`, `EDIT`, `COPY`, `MOVE`, `SEND`, `BARE`, `WORK`, `FORK`, `KILL`, `NOTE`, `WAIT`) or a runtime executor name.
+- **Fence width and nesting**: The parser accepts three or more backticks and renders three; a wider outer fence encloses narrower inner fences verbatim without dispatching them. A block closes at a line with at least the opening backtick count and only horizontal whitespace (or an optional closer aside), or falls back at the next outer operation heading or end of input.
+- **Naked operation recovery**: A column-zero line outside any block containing only a native operation name and optional `<!-- aside -->` opens that operation with a warning-severity advisory naming three backticks as the taught form.
 
-§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
-the five-character anchor form. Five characters after `@` are always an anchor.
+### §fence-pairing Fence pairing, quotations, and native tool calls
 
-§unclosed-aside A heading whose aside opens with `<!--` and never closes on its
-line takes the rest of the line as the aside, with one warning-severity advisory.
-A closed aside followed by more text is unchanged.
+`FencePairing` runs ahead of the lexer as a least-cost bracket parse over all fence lines in the turn so nested code blocks, unclosed blocks, and quoted examples resolve globally:
 
-§quotation **A fence that opens no operation quotes.** Outside a body, a line-start fence that
-is not an operation heading ({§executor-heading}) — unlabeled or tagged like an unknown
-code language (`ts`, `json`) without invocation slots — 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. 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. A bare fence alone draws nothing: nearly every one holds code or quoted output. An example the model means only to show belongs in a properly nested body ({§balanced-fences}) or a quotation ({§quotation}), so a model may show plurnk's own operations in an answer. Quotation outside an operation is response text under {§response-text}, not an executable program or a completion envelope.
-
-| Draws nothing | Why |
+| Rule | Contract |
 | --- | --- |
-| ```` ```READ (x)``` ```` on one line | CommonMark's own rule that a backtick opener's line carries no further backtick: it is inline code and quotes nothing after it |
-| A bare fence directly under a line carrying a fence run | an orphaned closer; it quotes nothing |
-| An unknown tag without invocation slots | a code block |
-| An offset example | {§indented-fences} |
-
-`plurnk.md` names the tab offset as the form for an example, in the aside of its nesting
-example, and shows its own examples offset; the other quoting fences are untaught: a tilde
-fence, an unlabeled fence and an unknown tag without invocation slots 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
-({§outside-text} places the scale). The offset is the one form that survives every
-fence style.
-
-§executor-heading **Syntax identifies an invocation; dispatch resolves its runtime.** A native
-operation or a known executor name opens a heading. An otherwise unknown fence name also opens an
-executor heading when the next non-horizontal-whitespace character starts an invocation slot:
-`(` for the target, `[` for metadata, or `<` for scope (not `<!--`, an aside). The same slot grammar
-then validates and binds it, including malformed-slot diagnostics and permitted slot ordering.
-Availability does not affect that parse. Known executors are the host's supplied vocabulary plus
-`sh`; knowing a name also permits its targetless, slotless form. Enclosing quotations, indented
-examples and reasoning-channel restrictions remain unchanged.
-
-§interstitial-fence Only a heading under {§executor-heading} opens an operation. Any other fence
-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
-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 naming a plurnk operation or a known executor, and every popular family is read the same way.** A block keeps its line count where its lines allow, so statement positions name the source line; an inline block grows to its fences. A call with an unknown name or parameter, or a FIND, READ, EDIT, COPY or MOVE naming no target, leaves the whole emission as it was; calls that cannot be mapped draw {§native-tool-call-receipt}. An emission that already yields an operation is never rewritten. No diagnostic, notice or teaching mentions a successful reading (#760).
-
-| Family | Shape |
-| --- | --- |
-| DeepSeek | `<｜｜DSML｜｜ calls>` blocks of `invoke` elements with `parameter` children; DeepSeek writes the whole heading into the invoke's name — `<｜｜DSML｜｜ invoke name="FIND (docs/**) /Http404/ <!-- docs mentions -->">`, or `name="sh` with no closing quote and the script on the lines below — and the element's content is the body: the first word of the name is the operation, the rest its slots, and `parameter` tags around the content are debris, as are a copied facts line (`{"lines":6}`) under the heading, a `comment` attribute (the aside), and `<｜｜DSML｜｜tool_calls>` spelled without spaces |
-| Anthropic-style | `<function_calls>` blocks of `invoke` elements with `parameter` children |
-| The `<tool_call>` family | `<function=NAME>` with `<parameter=key>` children (Qwen, MiMo); a JSON object with `name` and `arguments` (Hermes and kin); a name followed by `<arg_key>`/`<arg_value>` pairs (GLM) |
-| Llama | a bare `<function=NAME>` element; a `<\|python_tag\|>` JSON object |
-| Mistral | a `[TOOL_CALLS]` JSON array |
-| Kimi | `<\|tool_call_begin\|>` sections |
-| Qwen's own shapes | a flat JSON call whose operation is the value of an `op`, `action` or `cmd` key in any case (`{"op": "READ", "path": …, "range": …}`); an XML element named by the operation (`<NOTE>…</NOTE>`, `<FIND (path) <1,3></FIND>`, `<read path="…"/>`) or by a generic `op` element or function (`<op op="READ" …>`, `<op verb="READ" …/>` in `<ops>`, `<op=READ (path) …>`, `<function=OP name="READ" …>`, `<function=OP>` around such a JSON call or a plurnk heading); a plurnk heading written as the call's text (`<tool_call>READ (a.py) <60,120>`, `=READ (…)`) |
-
-| Call piece | Read as |
-| --- | --- |
-| `path`/`target`/`file_path`/`file`/`resource`/`uri` | the target |
-| `scope`/`range`/`lines`, `start`/`end` written apart, `offset`/`limit` (a first line and a count), a JSON array (`[500,530]`) or a `{"start", "end"}` object | the scope; plurnk slots written after the name are kept, and a trailing scope's own bracket may close the tag |
-| `pattern`/`regex`/`query` | a matcher option |
-| `aside`, `reason`, `description` | the aside |
-| `body`/`content`/`command`/`text`/`input` or plain text inside the call; an executor's string `input` | the body, an executor's program |
-| An executor's unknown parameter | one of its options, `[{"maxTokens": "2500"}]`, for its owner to accept or refuse; `bash` names `sh` when `sh` is the registered shell |
-| Closing tags left over from another family (`</parameter>`, `</invoke>`, `</>`) after a call | markup noise |
-
-Bare `invoke` elements use the same slots as wrapped calls. A complete JSON object
-inside an invoke supplies arguments when no explicit parameter elements are
-present; parameter bodies remain literal. Unknown native-operation arguments
-are not guessed.
-
-§native-tool-call-receipt **Unexecuted native markup draws a warning.** After exact
-recovery, the first remaining native-call block in outside text receives one
-warning naming its markup and the fenced form. It does not invalidate real OPs
-beside it, become an operation, or independently earn a strike. A turn with no
-operation follows {§empty-turn}. Quoted examples and operation bodies are not
-attempted calls. Outside text remains unchanged evidence under {§outside-text}.
-
-§empty-section Both the compact bodyless form and an empty multiline block
-normalize optional bodies to null. Closing fences are conventional, never required
-({§closer-fallback}).
-
-§statement-rendering `PlurnkParser.stringify` renders native OP names and named
-runtime fences from the shared AST, with one blank line between operations. A
-target group compiles to ordinary statements, each rendered with its resolved
-selection ({§target-group}).
-Every closing fence occupies its own line, including bodyless operations;
-inline fences remain accepted input, not generated examples.
-It chooses at least three backticks and more than any run within the body
-({§balanced-fences}), preserving body bytes on reparse. Fence length is syntax,
-not AST or persistence state. Core-authored programs use
-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 |
-|---|---|
-| Fence name | Reserved native OP, otherwise an executor name under {§executor-heading} |
-| `(path)` | Target/program/tool slot; COPY and MOVE each have two resource operands |
-| `[metadata]` | One owner-interpreted block; options, never the op's input |
-| `<scope>` | Operation-specific numeric or anchored coordinates |
-| `<!-- … -->` | Optional final, single-line aside |
-| Body | Literal content between framing newlines |
-| Closing fence | The opening backtick count, on its own line |
-
-§slot-order Producers put target, scope, metadata, then aside, separated
-by one ASCII space. Target and scope form one resource selection; COPY/MOVE
-repeat the complete selection/metadata group per operand. ANTLR accepts
-adjacent slots and scope/metadata permutations within a selection without
-changing ownership or making them distinct canonical forms. Metadata may also
-precede the first target, belonging to that first selection. Between targets it
-belongs to the preceding selection, never the following one. Single-target
-scope-first tolerance remains valid with metadata before or after that scope.
-Each selection has at most one scope; its metadata blocks retain their authored order. A second scope
-is refused; the recovery is the scope's working form ({§parse-recovery}).
-
-§lifecycle-slots NOTE accepts no target, scope, or metadata. WAIT retains its
-optional target and duration under {§send-wait-scope}. Their literal bodies begin
-below the header.
-
-§target-group **READ and KILL take a target group.** A READ or KILL heading may carry several `(path)` slots, each binding the scope and metadata that follow it under {§slot-order}; a naked pattern on the heading ({§naked-pattern}) supplies the default for each member without its own metadata `pattern`. The form is accepted, not taught: it rescues a bulk attempt written one path per slot.
-
-| Fact | Rule |
-| --- | --- |
-| Compilation | the parser compiles the complete heading into one ordinary statement per member, in authored order, each with its own target, scope, metadata and resolved matcher; no duplicated first-member or group representation crosses the parser boundary |
-| Position and aside | every resulting statement retains the heading's source position and aside; a heading-level parse error refuses all its members, not valid sibling headings |
-| A distilling body ({§log-kill-distillation}) | lands once, with the first member |
-| Other operations | COPY and MOVE keep their two operands with their own meaning ({§transfer-resource-selections}); every other operation takes one slot, and a second slot on its heading is the slot-opener diagnostic |
-
-§safe-uri-target-groups **An explicit URI list is a target group.** In READ and KILL only,
-one path slot may contain several explicit `scheme://` URIs separated by top-level commas or
-whitespace; braces protect their contents. Every member must independently parse as a URI,
-otherwise the target stays singular and exact. Local filenames containing spaces or commas
-are never split. Each URI inherits its slot's scope and metadata and compiles through
-{§target-group}; COPY/MOVE and other operations do not admit this tolerance.
-
-§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. `` (`` `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 follows
-{§send-wait-scope}. There is no ambiguity: the operation has one reading with or without
-the slot.
-
-§heading-inline-body Nonempty body text belongs below the fence header. Text after the slots
-on the heading line is read by the operation's shape, by the builder that reads that operation,
-and that reading is named: no text on the line is dropped silently, and none loses the operation.
-Taken as the body, it is the first body line, with one warning: "`EDIT` body text was on the OP
-line and was taken as the body; body content goes immediately beneath the opening fence line." A
-sigil claims a matcher only on an operation that has one. This does not change the meaning of a
-compact empty block or permit unmatched fences.
-
-| Operation | Text after the slots on the heading line |
-|---|---|
-| FIND, READ, KILL with a non-log target | The matcher ({§naked-pattern}). Beside an option block's `pattern`, ignored ({§matcher-body-redirect}). |
-| KILL on a log target | The matcher. Beside an option block's `pattern`, the first line of the distillation ({§log-kill-distillation}). |
-| EDIT | A sigil-led matcher ({§edit-pattern}), unless an option block carries the `pattern`; otherwise the body. |
-| COPY, MOVE | Ignored ({§transfer-resource-selections}). |
-| SEND, WORK, FORK, BARE | One JSON object is the option block where the heading admits one ({§bare-option-object}); otherwise the body. |
-| executors | The input body, including an unbracketed JSON object; metadata requires brackets. |
-| NOTE, WAIT, KILL without a target | The body. |
-
-§bare-option-object **A bare option object is the option block, where the house option array owns the block.** Executor headings always read an unbracketed object as input under {§heading-inline-body}, regardless of registration or input media type; their metadata is only the bracketed slot ({§scheme-metadata-modifier}).
-
-| Heading | `{…}` after the slots is |
-| --- | --- |
-| SEND, BARE, WORK and FORK, where the heading admits a block (BARE, WORK and FORK only after their target) | read as `[{…}]`: the AST carries the array form, the written heading renders it, and one warning-severity receipt names the indulgence in place of the {§heading-inline-body} advisory: "`SEND` took a bare option object; the taught form is `[{…}]`." |
-| One that already carries a block | inline body |
-| FIND, READ and KILL | the matcher ({§naked-pattern}), because a search for JSON text is legitimate; a bare matcher that parses as a JSON object draws one advisory saying so: "`{…}` was read as the matcher." ({§diagnostic-observation}) |
-
-§operation-aside The final header modifier may be one single-line HTML
-comment. AstBuilder removes its delimiters and surrounding whitespace into
-`aside: string | null`. It is durable descriptive text, not authority,
-routing, timing, or body input. Comments inside a body remain literal.
-
-§scheme-metadata-modifier A target may carry one single-line `[metadata]`
-block, placed under {§slot-order}; executor and SEND fences also admit it without a target.
-The block belongs to the selected scheme or executor, which owns its shape,
-interpretation, validation and authority. The language assigns no meaning to
-the content and stores each block's exact inner text: 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 the owner cannot read, 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.
-
-**House policy, not a language rule:** every first-party scheme and executor
-reads its block through the shared `MetadataOptions` reader, which takes the
-block with its brackets as a JSON array of option objects, merged left to
-right with later keys winning. Reply SEND additionally owns a numeric completion
-element ({§message-completion}); WAIT owns its numeric duration ({§send-wait-scope}).
-A third-party owner may read its block any way
-it likes — the language guarantees only the exact inner text. Documentation
-for a first-party owner therefore shows the bracketed array form.
-
-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 `[{"pattern": "<matcher>"}]` carries the matcher string: the leading prefix claims its dialect under {§matcher-prefix-claims}, and AstBuilder lifts it into the statement's `matcher` (`MatcherBody | null`), positioned dialect errors included. The heading line is the matcher's home ({§naked-pattern}).
-
-| Fact | Rule |
-| --- | --- |
-| The block | one that carries only `pattern` leaves `metadata: null` for the owner; beside other keys the block stays with the owner verbatim, and the owner's reader treats `pattern` as reserved; the language lifts only from one block that parses as a JSON array of objects, and anything else lifts nothing and reaches the owner's `400` untouched |
-| Diagnostics | a `pattern` that is present but not a string is the language's own positioned diagnostic, as is a matcher of a claimed dialect that fails admission |
-| Bodies | FIND and READ bodies become memory under {§retrieval-annotation}; a non-log KILL's body is unused and receives the advisory under {§matcher-body-redirect}; EDIT keeps its literal body: with a matcher it is the replacement for every selected span ({§edit-pattern}), and an absent body deletes them |
-| `PlurnkParser.stringify` | writes a lifted matcher whose block left no metadata back bare when the bare form reads back identically and draws no advisory ({§naked-pattern}), otherwise as `[{"pattern": "…"}]` |
-
-## 3. Lexical elements
-
-| Element | Shape or role |
-|---|---|
-| 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 |
-| `[metadata]` | One owner-interpreted block of owner-defined options |
-| `<scope>` | Numeric or anchored coordinates; §7 |
-| Body | Literal text; never recursively interpreted as operations |
-
-## §op-shapes 4. Per-operation semantics
-
-<!-- map -->
-| Tag | Promise |
-| --- | --- |
-| {§retrieval-annotation} | A retrieval's authored body is memory, not selection or output. |
-| {§note-value} | NOTE retains its literal body as ordinary model-owned working memory. |
-| {§reasoning-operations} | The shared fence parser admits complete, line-leading NOTE, FIND and READ statements from exposed provider… |
-| {§exec-executor-slot} | The fence name selects the executor directly: for example, `python3 (tools/report.py)` or `gitea… |
-| {§turn-disposition} | WAIT requests parking; its literal body does not control scheduling, and its optional target is the label the… |
-| {§send-wait-scope} | WAIT's optional `[seconds]` metadata is a non-negative finite scalar bounding this park, not the lifetime of… |
-| {§send-directed-scope} | A recipient SEND carries an optional numeric scope after its target and metadata through to the addressed… |
-| {§kill-scope} | KILL takes an optional text-coordinate scope beside its target, and an optional matcher. |
-| {§bracket-metadata-slot} | Brackets are the owner's metadata modifier: the runtime or MCP service is the fence name, and tool input… |
-| {§text-scope-semantics} | Exact regions use 1-based lines and Unicode code-point columns. |
-| {§bare-statement} | BARE requests one isolated model inference. |
-| {§read-find-normalization} | An authored READ is never rewritten into a FIND. |
-| {§local-path-fragment} | A bare path takes `#channel` like a URL. |
-| {§read-exact-target} | READ targets one exact resource (a local path or scheme URL, with optional `#channel` fragment or… |
-| {§unscoped-edit-create-only} | No scope and an existing target is refused. |
-| {§empty-mutation-scope} | Empty mutation content has one writable position: `<0>`, `<1>`, `<-1>`, and `<1,-1>` all insert the body as… |
-| {§transfer-resource-selections} | COPY and MOVE require two singular `ResourceSelection` operands, source first and destination second, and… |
-| {§find-result-unit} | For FIND, target selection fixes the paginated result unit after scheme address resolution… |
-| {§copy-move-observation} | COPY and MOVE log projections preserve both admitted operand selections, including their independent scopes,… |
-<!-- /map -->
-
-The model-facing forms below are the canonical projection. Parser tolerance is
-governed by {§canonical-statement}; runtime conditions remain explicit below.
-
-| OP   | `(path)`                                     | `<scope>`                       | `body`                         |
-|------|----------------------------------------------|---------------------------------|--------------------------------|
-| FIND | required target or glob                      | optional result range           | annotation normalized to NOTE |
-| READ | required target                              | optional text region            | annotation normalized to NOTE |
-| 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                          |
-| execution | the fence name is the runtime; optional program/tool path ({§exec-executor-slot}) | none ({§exec-lifetime}) | 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 | optional text region on a target ({§kill-scope}) | the distillation of what a `log:///` target retires ({§kill-scope}); none for other targets |
-| SEND | optional recipient | recipient-defined; none for workers ({§send-directed-scope}) | message |
-| NOTE | none | none | literal working memory |
-| WAIT | optional label ({§send-wait-scope}) | none; duration is `[seconds]` metadata | explanation of the wait |
-
-§retrieval-annotation **A retrieval's authored body is memory, not selection or output.**
-A nonblank body beneath FIND or READ becomes one ordinary NOTE immediately before
-the retrieval, including a body consisting of a pattern or an HTML comment. A
-grouped READ contributes one NOTE before its expanded statements. The retrieval
-itself has no body; its selector comes only from its header. Normalization is the
-same in content and exposed reasoning and never executes quoted body text. The
-canonical rendering is NOTE followed by bodyless retrieval; exact submitted text
-remains source evidence. The NOTE persists independently of retrieval success and
-is curated normally. Explicit NOTE remains the taught form.
-
-§note-value NOTE retains its literal body as ordinary model-owned working memory.
-It has no target, scope, metadata, or lifecycle effect. Its full body participates
-in ordinary log token accounting and model-driven curation; prior notes are not
-automatically hidden. A continuing or parked turn that carried no NOTE is told so in
-the next packet ({§continued-without-note}); the omission is never a failure. A
-NOTE-only turn does not request completion; ordinary repetition and strike rules
-still apply.
-
-§reasoning-operations The shared fence parser admits complete, line-leading NOTE,
-FIND and READ statements from exposed provider reasoning. Admission is part of
-the language. Other backtick or tilde code blocks are opaque; heading and
-missing-closer recovery cannot escape them or complete an unfinished reasoning
-operation. Blockquoted and inline examples are not headings. Other reasoned
-operations never execute.
-
-Operations are admitted only after the provider response completes; their
-presence never interrupts generation. Selected operations precede the content
-program, in source order without deduplication, and use ordinary dispatch,
-permissions, persistence and log
-projection. Every admitted reasoning operation is the turn's work for admission and
-continuation, a NOTE exactly as in the content program ({§note-value}); a turn that landed one is never empty. Reasoning
-and content remain separate, unchanged forensic sources. Rejected or superseded
-provider attempts execute none of their operations. All three operations remain
-available in the ordinary program; no task inventory is inferred from reasoning.
-Builder normalization warnings for admitted reasoning operations surface as
-ordinary non-striking notices. Quoted, unfinished, malformed or disallowed
-reasoning operations contribute neither execution nor normalization notices.
-
-§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. An executor heading's AST ({§executor-heading})
-carries the `runtime` tag and no operation keyword, then `target`, metadata, timing and body fields.
-Registration is checked at the invocation's execution point, after earlier operations settle
-({§op-execution-order}), 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.
-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 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 retains the normalized metadata duration as `seconds`, separate from text coordinates.
-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}. SEND carries optional message-completion metadata
-under {§message-completion}. KILL requires a target; NOTE retains memory.
-
-§send-wait-scope WAIT's optional `[seconds]` metadata is a non-negative finite scalar bounding
-this park, not the lifetime of its work. Without it, the service supplies its
-configured bound ({§worker-wait-timing}). Repeated duration slots select the
-smallest valid scalar. Zero continues without parking or a diagnostic. Invalid
-duration metadata is ignored with a terse warning; when none is valid, the configured
-bound applies. A text scope cannot supply a duration and receives the same warning.
-The optional target is a label, never a selected wake source;
-the body is the wait's explanation. Neither creates a schedule or restricts ordinary
-wake events. Ordinary malformed-header rules still apply. Multiple WAITs request
-one park with the earliest bound, including the configured bound for each bare WAIT.
-
-§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). 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, and an optional matcher.** The scope is numeric or anchored (```` ```KILL (log:///**/READ) <17,-1>``` ```` or ```` ```KILL (worker:///notes.md) <@aB3dE,@0Aa9Z>``` ````); the matcher option selects rows or lines (```` ```KILL (log:///**) [{"pattern": "~stale"}]``` ````, {§matcher-option}). Each operand becomes an ordinary KILL statement with its own `target`, `lineMarker` and `matcher`; no grouped AST reaches execution ({§target-group}). KILL requires a target.
-
-| Fact | Rule |
-| --- | --- |
-| The body | retained on a `log:///` target, where it is the model's distillation of what the KILL retires and lands as its own NOTE row ({§log-kill-distillation}); every other targeted KILL has `body: null`, and a body beneath one draws the advisory ({§matcher-body-redirect}); beneath a `log:///` KILL the body is never read as a matcher, while an inline pattern on the heading line still lifts |
-| Without a scope | KILL retires or deletes the whole target |
-| With one | it removes exactly that span — of a log body's packet projection or of an entry's content; Core owns the one-way semantics: there is no operation that restores a scoped-away log body |
-
-§bracket-metadata-slot Brackets are the owner's metadata modifier: the runtime
-or MCP service is the fence name, and tool input belongs in the body. A bracket
-block is metadata before or after the target, with ownership under {§slot-order};
-its position does not select an executor or change its interpretation.
-
-The `<scope>` slot is optional where admitted and its domain is OP-specific. FIND
-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:
-
-| Arity         | Surface meaning                                                     | Endpoint rule                                        |
-|---------------|---------------------------------------------------------------------|------------------------------------------------------|
-| one integer   | One whole physical line, or the documented `0`/`-1` mutation anchor | Exactly one ordinal line                             |
-| two integers  | Whole physical lines `firstLine..lastLine`                          | Both lines are included                              |
-| four integers | Exact `startLine,startColumn,endLine,endColumn` region              | Start included, end excluded; equality is zero-width |
-
-§text-scope-semantics **Exact regions use 1-based lines and Unicode code-point columns.** One- and two-integer line selections normalize to the same exclusive-end `TextRegion` used by four-coordinate selections. Whole-line replacement deliberately accounts for newline separators; it is an ergonomic projection over exact replacement, not a different mimetype navigation mode. An end bound beyond the available content clamps to the final addressable endpoint; the start bound must resolve. Other arities and decimal text coordinates are runtime 416 failures.
-
-| `-1` as | Means |
-| --- | --- |
-| A one-integer mutation scope | the append point |
-| The end of an inclusive range | through the last line |
-| An exact region's start or end line | the end of the content, so `<1,1,-1,1>` is the whole text and `<-1,1,-1,1>` appends |
-| A column | the end of its line, so `<3,1,3,-1>` is line 3 to its end and `<3,-1,3,-1>` appends to that line |
-
-An unadvertised ingestion tolerance: the runtime accepts three integers as `startLine,startColumn,endLine` and immediately normalizes them to the complete four-coordinate region ending after the final code point of `endLine`; producers never emit that form.
-
-§bare-statement **BARE requests one isolated model inference.** Its optional
-path names a prompt resource; its body supplies inline prompt text. At least
-one must supply nonempty text at execution. With both, the complete resource
-text precedes the body, separated by two newlines. The target's scheme owns any
-metadata modifier. No scope, persistent worker identity, or output-language
-shape is represented. Provider selection, source admission, batching,
-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). 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
-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.
-
-§local-path-fragment **A bare path takes `#channel` like a URL.** `data/users.html#readable`
-parses as `{ kind: "local", raw: "data/users.html", fragment: "readable" }`: the first `#` ends
-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: a model that appends the channel to the path it was just
-shown addresses the same entry, and so does one that writes it after the parenthesis,
-`(page.html) #readable`, which {§naked-pattern} reads as the channel. `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.
-
-§read-exact-target READ targets one exact resource (a local path or scheme
-URL, with optional `#channel` fragment or `[metadata]`) and has no body. A
-`<scope>` on READ selects
-a text region from that exact target. Without a scope, READ takes the configured
-first page ({§markerless-first-page}); `<1,-1>` explicitly selects all text. Decimal scope components are
-invalid on READ.
-
-Mutation semantics:
-
-- No scope and a target address that does not yet exist creates a file or entry from the body. This is the only unscoped EDIT.
-- §unscoped-edit-create-only No scope and an existing target is refused. Replacing existing content requires a precise text scope or `<1,-1>`; core owns the existence check.
-- `<N>` replaces whole line `N`; `<N,M>` replaces inclusive whole lines `N` through `M`.
-- An empty body deletes the selected text.
-- `<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, source first and destination second, and admit
-  no body: text after the slots on the heading line, or beneath it, is ignored and the
-  operation still runs, with one warning-severity advisory (`MOVE takes no body; the body
-  was ignored.`). Each selection binds its own target, scope, matcher, and metadata under
-  {§slot-order}, {§matcher-option}, and {§scheme-metadata-modifier}.
-
-### Per-operation observations
-
-| OP   | Successful observation                                                            |
-|------|-----------------------------------------------------------------------------------|
-| FIND | Resource catalog groups or exact-target match locations                           |
-| READ | Complete or scoped body projections plus optional text match evidence             |
-| EDIT | Status plus a bounded receipt for the effect that landed                          |
-| 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                              |
-| 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                                                 |
-| NOTE / WAIT | Literal memory or wait explanation                              |
-
-§find-result-unit For FIND, target selection fixes the paginated result
-unit after scheme address resolution ({§entry-address-resolution}). An exact
-resource target with a matcher pages flat match locations; a glob or
-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>`,
-configured markerless first page ({§markerless-first-page}), and explicit-all
-`<1,-1>` forms apply to either unit.
-
-§copy-move-observation COPY and MOVE log projections preserve both admitted operand selections,
-including their independent scopes, whether the result changed state, was a
-304 no-op, or failed after admission. Operands identify the request; `effects`
-describe only mutations that landed. If either operand uses textual scope,
-each landed textual create or update carries the same bounded receipt used by
-EDIT. Whole-channel transfers remain bodyless structural effects; runtime
-owners reject binary markers rather than treating a text field as a byte lane.
+| Complete vs. repaired readings | Complete nested interpretations take precedence over missing-closer repairs; among repaired readings, preserving authored operations outranks repair count. |
+| Unclosed mutation yields | An `EDIT` body never swallows a same-width native operation heading; a missing closer is supplied before the next native heading so both operations run. |
+| Prose code blocks and message run-on | Inside `SEND`, `WORK`, `FORK`, or `BARE` bodies, executor headings (` ```sh `, ` ```python3 `) are literal code blocks shown in the message, and an unclosed message body runs to the end of the turn. |
+| Quotations and indented fences | A bare fence or non-operation info string opens an inert quotation block; fences indented by 4+ spaces or a tab are literal CommonMark indented code. |
+| Near-miss tolerances | Inline chains on a closer line, closing fences with stray non-heading trailing text (repaired with trailing characters and any immediately following retry closers discarded), transparent mid-heading closers, case-insensitive executor names, `js`/`ts`/`node` alias fallback, forgotten tag on the line below a bare fence, unclosed header asides, and `@<1-4 digits>` line anchors are recovered with deterministic advisories. |
+| Native tool-call recovery | When a model emits provider-native tool-call markup (`<tool_call>`, `<function=...>`, JSON tool calls) instead of fenced operations, the parser recovers recognizable PLURNK operations or emits a warning receipt for unexecuted markup. |
+| Statement rendering | `PlurnkParser.stringify` formats AST statements back into canonical three-backtick blocks (or wider when the body contains fences), normalizing empty optional bodies to `null`. |
 
-Every operation returns the runtime-neutral `OperationResult` defined by
-{§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.
+### §slot-order Heading slot order, target groups, and metadata modifiers
 
-## §path-syntax 5. Target and path grammar
+Producers write `(target) <scope> [metadata] <!-- aside -->` separated by single ASCII spaces; ANTLR tolerates adjacent slots and scope/metadata permutations within a resource selection.
 
-<!-- map -->
-| Tag | Promise |
+| Construct | Contract |
 | --- | --- |
-| {§path-query} | The serialized query component is the lossless representation. |
-| {§path-parentheses} | An unescaped depth-zero `)` closes the target slot. |
-| {§path-glob} | `PathSyntax` owns exact-path versus path-pattern classification. |
-| {§worker-name} | The exported `WORKER_NAME` contract governs names minted for URI authority slots:… |
-<!-- /map -->
+| Target groups and multi-target slots | A `READ` or `KILL` heading may carry multiple `(path)` slots, and a `FIND`, `READ`, or `KILL` `(path)` slot may carry a comma/pipe/whitespace-separated list of explicit `scheme://` URIs or a comma/pipe-separated list of local paths/globs outside brackets/braces, compiling into one statement per target in authored order. |
+| Scope on scopeless OPs | A `<scope>` written on `WORK`, `FORK`, `BARE`, `NOTE`, or targetless `SEND` is dropped with a warning advisory while the operation still runs. |
+| Heading inline body & bare options | Trailing text on the heading line is read as the matcher on `FIND`/`READ`/`KILL` (and sigil-led `EDIT`), as `[{...}]` metadata when a bare JSON object appears on `SEND`/`WORK`/`FORK`/`BARE`, or as the first body line with a warning advisory. |
+| Scheme metadata modifier | `[metadata]` preserves balanced brackets and quoted strings as raw inner text for the target scheme or executor (`MetadataOptions` parses first-party arrays of option objects and reserves `env`). |
+| Operation aside | A trailing `<!-- aside -->` comment on the heading line is stripped into `aside` (`string` or `null`) as descriptive metadata. |
 
-The target slot contains either a local path or a scheme URL. Exact addresses
-and path globs share the slot; content matchers follow the heading forms in
-{§matcher-option}.
+---
 
-| Form                    | Typed admission                                                     | Runtime meaning                                      |
-|-------------------------|---------------------------------------------------------------------|------------------------------------------------------|
-| Bare path               | `LocalPath { kind: "local", raw, fragment? }`                       | Resolves through the runtime's file surface; `#channel` is `fragment` ({§local-path-fragment}) |
-| `scheme://…`            | WHATWG-decomposed `UrlPath`                                         | Resolves only when a runtime scheme owns the address |
-| Path glob               | Preserved in either path kind                                       | Scheme defines collection selection and ordering     |
-| `#channel` fragment     | Preserved as `UrlPath.fragment`                                     | Selects a named channel when the scheme supports it  |
-| `?query`                | Preserved as ordered `UrlPath.query`; `null` = absent, `""` = `?`   | Participates in scheme resource identity             |
+## §op-shapes 3. Per-operation semantics and dispositions
 
-AstBuilder recognizes a URL with the case-insensitive prefix
-`[a-z][a-z0-9+.-]*://`, passes it through WHATWG `URL`, and surfaces malformed
-URL structure as a visitor error. A target without that prefix remains a raw
-local path. Grammar acceptance does not register a scheme; the runtime scheme
-catalogue and packet-time scheme teaching remain dynamically owned elsewhere.
+| OP | `(path)` | `<scope>` | `body` |
+| --- | --- | --- | --- |
+| `FIND` | required target or glob | optional result range | annotation normalized to `NOTE` |
+| `READ` | required target (exact or glob fan-out) | optional text region | annotation normalized to `NOTE` |
+| `EDIT` | required file or entry | required for existing target; omitted only for creation | literal replacement/creation text |
+| `COPY` / `MOVE` | required source and destination | optional region after each path | empty (any body is ignored with a warning) |
+| execution | fence name is runtime; optional `(program-or-tool)` | none (lifetime in `[metadata]`) | optional program/tool input |
+| `BARE` | optional prompt resource | none | prompt text |
+| `WORK` / `FORK` | optional `session://name` or prompt resource | none | task prompt |
+| `KILL` | required target | optional text region | distillation `NOTE` on `log:///`; empty otherwise |
+| `SEND` | optional recipient | recipient-defined; none for sessions | message body |
+| `NOTE` | none | none | literal working memory |
+| `WAIT` | optional label | none (`[seconds]` in metadata) | wait explanation |
 
-§path-query The serialized query component is the lossless representation.
-Ordering, duplicate names, encoded spelling, and the distinction between an
-absent query and an explicit empty query survive parsing. Consumers that need
-key/value access may construct `URLSearchParams`; the shared AST does not replace
-URI identity with a grouped object projection.
+- **Retrieval annotations and reasoning operations**: Nonblank bodies beneath `FIND` or `READ` normalize into a preceding `NOTE` statement. `PlurnkParser.parseReasoningOperations` extracts complete line-leading `NOTE`, `FIND`, and `READ` blocks from exposed model reasoning to run before the content program.
+- **Text scope algebra**: `<N>` selects whole line `N` (`0` prepends, `-1` appends on mutation); `<N,M>` selects inclusive lines `N..M`; `<SL,SC,EL,EC>` selects an exact 1-based Unicode code-point region with exclusive end (three-integer scopes normalize to four).
+- **Local path fragments**: Bare paths decompose `#channel` into `fragment` just like `scheme://` URLs so channel selectors round-trip identically.
+- **Turn dispositions (`WAIT` and `SEND`)**: Dispositions may appear anywhere in a turn; multiple `WAIT` statements coalesce to the shortest `[seconds]` bound, and `SEND [200]` (or `[202]` park) governs loop completion once all earlier operations in the turn settle.
 
-§path-parentheses An unescaped depth-zero `)` closes the target slot. The
-tolerant lexer preserves balanced unescaped parentheses, while canonical
-producers use one lossless Plurnk lexical layer before target interpretation:
+---
 
-| Target-slot spelling | Interpreted character |
-| -------------------- | --------------------- |
-| `\\`                 | `\`                   |
-| `\(`                 | `(`                   |
-| `\)`                 | `)`                   |
+## §path-syntax 4. Target and path grammar
 
-Decoding consumes only those three pairs in one left-to-right pass; unknown
-pairs such as `\*` retain both characters for glob interpretation. Encoding
-escapes backslashes before parentheses, so every target string round-trips.
-Pathname producers retain the deliberate `%28`/`%29` alias and `%3C` spelling,
-but must use the lexical layer for identity-bearing query and fragment text
-rather than changing their percent-encoded spelling. Newlines and raw `<` are
-never target content. Glob metacharacters remain legal path data.
+- **URL vs. local path decomposition**: Targets matching `[a-z][a-z0-9+._-]*://` decompose via WHATWG `URL` into `UrlPath` (preserving lossless serialized `query` and `fragment`); all other targets become `LocalPath { kind: "local", raw, fragment? }`.
+- **Parenthesis escaping**: An unescaped depth-zero `)` closes `(path)`; balanced parentheses are tolerated and `\\`, `\(`, `\)` provide lossless escaping via `PathSyntax`.
+- **Glob classification and session names**: `PathSyntax.hasGlob` and `globMagicIndex` classify glob metacharacters vs. exact paths. `SESSION_NAME` (`[A-Za-z0-9][A-Za-z0-9_-]{0,62}`) validates minted session authority names (excluding `_plurnk`).
 
-§path-glob `PathSyntax` owns exact-path versus path-pattern classification.
+---
 
-| Method                           | Contract                                                                 |
-| -------------------------------- | ------------------------------------------------------------------------ |
-| `hasGlob(pathname)`              | Recognizes `*`, `?`, character-class, brace, extglob, and escape syntax  |
-| `globMagicIndex(pathname)`       | First such position, solely for conservative candidate-prefix selection  |
+## §matcher-prefix-claims 5. Bulk pattern matching and scope markers
 
-Matching and folder-scope semantics remain runtime concerns.
+`FIND`, `READ`, `KILL`, and `EDIT` accept a single-line matcher on the heading line classified by leading sigil:
 
-§worker-name The exported `WORKER_NAME` contract governs names minted for URI
-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
-
-<!-- map -->
-| Tag | Promise |
-| --- | --- |
-| {§heading-boundary-recovery} | A column-0 heading is the trustworthy boundary. |
-| {§scope-slot-tolerance} | A line scope written inside a path slot (```` ```COPY (worker:///src.md<2,3>) ````) is read as… |
-| {§extra-path-slot} | A path slot beyond the operation's admitted operands — one for every operation, two for COPY and MOVE, any… |
-| {§matcher-refusal} | A matcher the parser cannot read refuses its operation, never the turn. |
-| {§regex-dialect-readings} | Three habits of other regex dialects are read, with one advisory each. |
-| {§pattern-body-single-line} | Every matcher is one physical line. |
-<!-- /map -->
-
-FIND, READ, KILL, EDIT, and the COPY/MOVE operands accept an optional matcher
-through the `pattern` option ({§matcher-option}). AstBuilder assigns the dialect from the
-matcher's leading characters. A leading prefix claims its dialect. Invalid
-claimed syntax never falls back to glob matching: it is the operation's own
-refusal ({§matcher-refusal}), not a parse error.
-
-- §heading-boundary-recovery A column-0 heading is the trustworthy boundary. After a
-  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.
-- §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.
-- §extra-path-slot A path slot beyond the operation's admitted operands — one for every
-  operation, two for COPY and MOVE, any number on READ and KILL ({§target-group}) — 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. Recovery-only body text is not advertised as a valid body
-  for an operation that takes none. The statement is dropped and its siblings run.
+| Prefix | Dialect | Validation & tolerance |
+| --- | --- | --- |
+| `//` | `xpath` | Validated with XPath 1.0 parser before regex classification |
+| `/` or `^` | `regex` | ECMAScript `RegExp`; tolerates `\|` alternation, trailing `-flags`, and glob-shaped `/*text*/` with advisories |
+| `$` | `jsonpath` | Validated with RFC 9535 `json-p3` |
+| `~` | `fulltext` | Single-line FTS5 query string |
+| `&` | `graph` | `&symbol`, `&<symbol`, or `&>symbol` relation query |
+| none | `glob` | Fallback shell glob or literal substring |
 
-| Prefix    | Dialect  | Canonical form                       | Typed admission                   | Runtime owner       |
-|-----------|----------|--------------------------------------|-----------------------------------|---------------------|
-| `//`      | XPath    | `//selector`                         | XPath 1.0 `xpath.parse()`         | Mimetype projection |
-| `/`       | Regex    | `/pattern/flags`                     | ECMAScript `RegExp` construction  | Mimetype projection |
-| `^`       | Regex    | `^pattern`, no slashes or flags      | ECMAScript `RegExp` construction  | Mimetype projection |
-| `$`       | JSONPath | RFC 9535 expression                  | `json-p3` compilation             | Mimetype projection |
-| `~`       | Full-text | `~query`                            | Single-line raw string            | SQLite FTS5 index   |
-| `&`       | Graph    | `&symbol`, `&<symbol`, or `&>symbol` | Exact shape validation            | Symbol index        |
-| none      | Glob     | Shell glob or literal text           | Single-line raw string            | Mimetype projection |
+- **Soft matcher refusal**: An invalid matcher expression is admitted as `matcher.dialect = "unreadable"` with its diagnostic and working-form `recovery` so only that operation fails `400 grammar/matcher/unreadable-pattern` while sibling statements in the turn still execute.
+- **Heading recovery and slot tolerances**: Statement errors recover at the next column-0 heading; a `<scope>` written inside `(path<L,M>)` is lifted with a warning; extra `(path)` slots beyond the operation's arity fail only that statement.
+- **Line anchors and scope range recovery**: `TextLineMarker` accepts `@<5 Base62 chars>` line anchors in line positions; reversed or zero-based two-number scopes (`<0,N>`, `<M,N>` with `M > N`, `<N,+K>`) normalize with a warning advisory.
 
-XPath is classified before regex because its prefix is two slashes. Regex
-splitting respects escapes and character classes; `\/` represents a literal
-slash. The AST stores regex `pattern` and `flags`, not a compiled object.
-SQLite validates full-text query expressions at execution. Graph admission validates its direction
-and non-whitespace symbol before runtime. Every other leading character remains
-in the fallback glob/literal dialect; `@(...)` is therefore an extglob group and
-bare `@text` remains literal matcher text. Rendered READ coordinates are
-structural output rows, not a reserved matcher prefix. FIND scope selects result
-positions without changing the matcher.
+---
 
-AstBuilder validation is compile-only and never evaluates a document. Matcher
-evaluation belongs to the runtime's selected mimetype, FTS5, or symbol
-implementation. A matcher admission error is local to its statement; later
-statements remain recoverable when their boundaries are trustworthy.
+## §whitespace-contract 6. Parser architecture, whitespace, and public API
 
-- §matcher-refusal **A matcher the parser cannot read refuses its operation, never the turn.**
-  A fumbled pattern is not a failure of the core contract: the statement is admitted with
-  `matcher.dialect = "unreadable"` carrying the authored text, the diagnostic as `message`, and the
-  dialect's working form as `recovery` ({§parse-recovery}); the operation lands as its own `400` row,
-  `grammar/matcher/unreadable-pattern`, with that message and recovery, its siblings run, and the
-  rail treats it as soft ({§strike-progress-immunity} in the core SPEC). An unreadable matcher
-  renders back as written ({§statement-rendering}). Only the one-line and string-typed shape of a
-  `pattern` option remains the option block's own admission.
-- §regex-dialect-readings **Three habits of other regex dialects are read, with one advisory each.**
-  `\|` is alternation, `|`, and a literal pipe is `[|]`; `-flags` after the closing slash are the
-  flags; a `/pattern/` that fails to compile on a leading or doubled `*` or `?` and is otherwise
-  glob-shaped is read as that glob over each line, `*` as `.*` and `?` as `.`, so `/*/` is every
-  line and `/*kernel_pca*/` contains `kernel_pca`. A regex that compiles is never rewritten, and
-  the AST keeps the authored `raw` beside the pattern it was read as.
+- **Body framing and outside text**: Body framing strips only the opening header newline and the single newline before the closing fence. `PlurnkParser.parse` partitions a model turn into ordered `statement`, `error`, and outside `text` items, flagging unfenced operation-like lines at column 0 with `Unfenced \`OP\` ignored.` warnings.
+- **Recorded emissions corpus**: `test/fixtures/recorded-emissions.jsonl` regresses the parser against real model emissions across live and demo runs.
+- **Tier entry points and runtime-neutral root**: `PlurnkParser.parse` (model turn) and `PlurnkParser.parseStatements` (protocol statements) are exported by `@plurnk/plurnk-parser`. The `@plurnk/plurnk-contracts` root is closed (verified by `src/index.test.ts`) and browser/DOM runtime-neutral (`tsconfig.browser.json`), with Node HTTP host types isolated in `@plurnk/plurnk-contracts/port`.
 
-- §pattern-body-single-line Every matcher is one physical line. On the protocol
-  operations it is the heading line's text ({§naked-pattern}) or the `pattern` option's
-  JSON string ({§matcher-option}); AstBuilder rejects a multiline one before dialect
-  classification. A regex that matches a
-  newline uses the two-character `\n` escape. Non-matcher operation bodies remain
-  multiline.
+---
 
-## §scope-slot 7. Scope markers
+## §text-region 7. Runtime-neutral wire contracts, text regions, and entry reads
 
-<!-- map -->
-| Tag | Promise |
+| Contract | Fields & Invariants |
 | --- | --- |
-| {§text-line-anchor-syntax} | A text coordinate admits a case-sensitive line anchor spelled `@` followed by exactly five Base62 characters… |
-| {§scope-marker-forms} | Canonical producers separate components with commas and no spaces. |
-| {§scope-range-recovery} | For FIND result positions and text-coordinate operations, the parser normalizes these two-component numeric… |
-<!-- /map -->
-
-The model-facing slot is `<scope>`; the AST field is
-`lineMarker`. Numeric scopes preserve ordered components in `LineMarker`;
-text-coordinate operations use `TextLineMarker`, whose line positions may also
-carry rendered anchors. The operation owner assigns every component's role.
-
-The operation column names the canonical AST operation after
-{§read-find-normalization}.
-
-| Operation             | Canonical components                   | Meaning                                                                    |
-|-----------------------|----------------------------------------|----------------------------------------------------------------------------|
-| FIND                  | 0–2 positions                          | Inclusive resource or exact-target location positions ({§find-result-unit}; markerless first page under {§markerless-first-page}) |
-| READ                  | 0/1/2/4 text coordinates               | Text projection from one exact selected file, entry, or log item           |
-| EDIT                  | 0/1/2/4 text coordinates               | Text replacement, deletion, prepend, or append                             |
-| 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}) |
-| execution             | None                                   | Lifetime uses metadata; observation cadence belongs to the daemon ({§exec-lifetime}) |
-| WAIT                  | None                                   | Maximum park duration uses metadata ({§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
-are an exact start-inclusive/end-exclusive region. Mutation scopes additionally
-admit `0` as prepend and `-1` as append. FIND result positions and READ
-text coordinates do not admit decimal scope components. A log KILL intersects a valid body-relative line
-scope with each selected body; an absent line is a successful no-op for that
-body, while unsupported arity is a runtime failure.
+| `TextRegion` | `{ startLine, startColumn, endLine, endColumn }` — 1-based positive safe integers counting Unicode code points (`LF`, `CRLF`, `CR` line separators; `CRLF` is one indivisible separator). `end` is exclusive; equal start and end identify a zero-length insertion point. Validated by `Validator.assertTextRegion`. |
+| `RangeExtent` | `{ unit: "line" \| "result" \| "byte", total, requested: [first, last], returned?: [first, last] }` — `requested` preserves the numeric request; `returned` names inclusive positive ordered positions (`<= total`) and is omitted on empty or failed selections. Validated by `Validator.assertRangeExtent`. |
+| `EntryReadResult` | `{ status: 200, entry: ClientEntry } \| { status: 400..599, problem: ProblemDetails, entry: null }` — `ClientEntry` carries `{ entryId: number \| null, target: string, channels: Record<string, ClientEntryChannel> }`. Every returned channel (`content`, `contentOffset`, `contentLength`, `mimetype`, `weight`, `state: "static" \| "active" \| "closed" \| "errored"`) satisfies `contentOffset + codePointLength(content) === contentLength`. |
 
-§text-line-anchor-syntax A text coordinate admits a case-sensitive line anchor
-spelled `@` followed by exactly five Base62 characters (`0-9A-Za-z`) wherever
-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,
-and KILL preserve these positions in `TextLineMarker`; core resolves them
-against the addressed current text before operation-specific numeric scope
-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.
-
-§scope-marker-forms Canonical producers separate components with commas and no
-spaces. ANTLR tolerates a dash separator and one space after a comma. Each
-component greedily consumes an optional leading minus sign, digits, and an
-optional decimal fraction, so the ingester preserves even noncanonical numeric
-shapes for runtime validation. An anchor-bearing text scope uses commas; ANTLR
-tolerates one space after each comma.
-
-§scope-range-recovery For FIND result positions and text-coordinate operations,
-the parser normalizes these two-component numeric scopes, emitting one warning
-`Scope <written> was read as <canonical>.` per normalized scope:
-
-| Written coordinates | Canonical inclusive range | Example |
-|---|---|---|
-| Positive integers `start,count`, with `count < start` | `start,start+count-1` | `<395,12>` → `<395,406>` |
-| Positive integer `start` followed by `+offset`, with nonnegative integer offset | `start,start+offset` | `<395,+12>` → `<395,407>` |
-
-Recovery requires safe integer operands and a safe integer endpoint; arithmetic
-overflow is refused. Forward/equal ranges, zero and negative sentinels, noninteger
-coordinates, three/four-component regions, and scopes containing anchors are not
-reinterpreted as counts. Anchor-relative endpoints retain {§anchor-offset};
-standalone `+N` has no base and is invalid. WAIT durations and owner-defined SEND
-or execution scopes are outside this normalization. The AST carries canonical
-coordinates; the retained emission preserves the authored spelling. These
-tolerances do not add hot-path teaching.
-
-After syntax normalization, ordinary {§text-scope-semantics}, pagination and
-{§read-zero-start} rules apply. Unsupported arity, unresolved inversions and
-noninteger coordinates remain failures; normalization does not bypass an
-operation's bounds checks, end clamping or empty-page semantics. FIND owns a
-deterministic result order so the same inclusive range selects the same positions
-from unchanged state. The parser does not resolve resource bounds or ordering.
-
-## 8. Literal programs and code blocks
-
-A producer carrying literal fences uses an outer backtick count absent from
-standalone fence lines in its body ({§fence-boundary}). The serializer chooses
-a count greater than every backtick run in the body; parsed AST values carry
-no framing state.
-
-`````text
-````EDIT (README.md) <1,-1>
-Run the tests:
+### §diagnostic-observation Operation results, Problem Details, and Notices
 
-```sh
-npm test
-```
-````
-`````
-
-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
-
-<!-- map -->
-| Tag | Promise |
+| Envelope / Method | Contract |
 | --- | --- |
-| {§send-mid-reservation} | WAIT is reserved ({§turn-disposition}). |
-| {§disposition-anywhere} | A disposition may sit anywhere in a model turn without imposing a program boundary. |
-| {§park-202-only} | WAIT joins live work: an open stream or a live child. |
-| {§lifecycle-only-turn} | A WAIT-, SEND-, NOTE-, or KILL-only turn is valid. |
-| {§send-body} | SEND body projection |
-<!-- /map -->
-
-The runtime adjudicates each admitted turn against actual message resolutions,
-results and live obligations ({§wait-obligation-matrix}). A response with no
-operation resolves no message and creates no new observation obligation ({§empty-turn}).
-
-| Intent | Nominal status | Meaning |
-|---|---|---|
-| Unobserved messages or results | 102 | Continue silently |
-| No operations while messages remain unresolved, or fresh operation/parser failure, without WAIT | 102 | Recover before automatic parking |
-| WAIT with live obligations | 202 | Park with the supplied or configured duration |
-| Resolved messages, observed results, live work remains | 202 | Join the held work; replies remain delivered |
-| Resolved messages, observed results, no held work | 200 or 499 | Settle under {§loop-completion}, retaining the aggregate message outcome |
-| KILL own worker | 499 | Cancel unfinished work in that worker and its descendants |
-| Runtime or infrastructure failure | 5xx | Not a model-authored task status |
-
-### The terminal contract (waitpid)
-
-The model may supply WAIT or complete message obligations with SEND metadata. The host, not the grammar, owns
-turn boundaries and adjudicates the loop's actual obligations. Asking
-the human uses the native `question` executor tool, offered only when a person attends the
-worker's owner ({§owner-interaction-ring}), not a disposition. The shape rules ARE structural:
+| `OperationResult` | Status `100..399` forbids `problem`; status `400..599` requires one RFC 9457 `ProblemDetails` object whose `status` equals the containing operation status. |
+| `ProblemDetails` | Requires `type` (stable absolute URI), `title` (stable summary with no occurrence data), `status`, and `detail` (failed subject, observed fact, and violated constraint); optional `instance`, `stage`, `recovery` (one working-form next action), `retryable`, and factual producer extensions. |
+| `Problems.fromError(error)` | If `error.result` is present, validates the complete `OperationResult` and returns its `problem`; otherwise if `error.problem` is present, validates and returns `ProblemDetails` unchanged; otherwise returns `null`. |
+| `Problems.project(problem, context)` | Produces `ProblemProjection` for model packets: retains `type` and `detail`, retains `stage`/`recovery`/`retryable`/extensions when not duplicated by the enclosing row, and strips `title`, `status`, and `instance`. |
+| `Notice` | Transient, non-terminal observation (`level`, `source`, `kind`, `message`, optional `directive` starting with `YOU MUST` / `YOU MUST NOT` / `YOU MUST ONLY` / `YOU SHOULD` / `YOU SHOULD NOT` for model-output advisories). |
 
-- §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
-  dispositions until the other admitted operations settle
-  ({§op-execution-order}). Nothing is dropped and no diagnostic is raised for
-  position. Omission does not synthesize a disposition ({§turn-shape}).
-- SEND is communication: an optional recipient path and an optional body.
-- §park-202-only WAIT joins live work: an open stream or a live
-  child. With none, it does not park. Its optional duration bounds parking ({§send-wait-scope});
-  a future message is scheduled through the schedule family.
-- §lifecycle-only-turn A WAIT-, SEND-, NOTE-, or KILL-only turn is valid.
-  NOTE does not request parking or acknowledge messages.
-  Ordinary repetition, strike and execution limits still apply.
+- **Diagnostic observation**: Every Problem `detail` and `recovery`, parse diagnostic, and `Notice` states what was read, what was done with it, and where, and may show the working form of the construct it read or refused — never guessing author intent or why.
 
-SEND with no `(path)` replies to open messages. SEND with `(path)` directs the
-message to that recipient. Completion metadata resolves message obligations
-({§message-completion}); dispatch still executes the whole program.
+### §mcp-server-definition Client display capabilities, MCP servers, and skills
 
-### §send-body SEND body projection
+- **`ClientDisplayCapabilities`**: Ordered array of closed discriminated objects (`{ kind: "scheme", scheme, display }` or `{ kind: "mimetype", mimetype, display }`), where `display.glyph` is an optional non-empty opaque string.
+- **`McpServerDefinition` and `McpOAuth`**: Closed union of `stdio` (`command`, optional `args`, `env`, `cwd`, `plurnkWorkspace`, `plurnkSession`) and `streamable-http` (`url`, optional `headers`, `authorization`, `plurnkWorkspace`, `plurnkSession`) definitions. `McpOAuth` (`Validator.assertMcpOAuth`) validates interactive OAuth (`callbackUrl`, mutually exclusive HTTPS Client ID Metadata Document URL / pre-registered client ID + `${NAME}` secret / Dynamic Client Registration, optional `issuer` and `authorizationParams`) and `client_credentials` grants.
+- **`SkillDefinition`**: Workspace skill definition (optional `source`, `ref`, `commit`; skill alias validated against `SKILL_NAME`) validated by `Validator.assertSkillDefinition`.
 
-SEND body syntax is opaque. AstBuilder preserves the exact `raw` string and
-also exposes a best-effort `json` value when `JSON.parse` succeeds; invalid JSON
-leaves `json: null` without invalidating an otherwise legal SEND. Plain text and
-JSON are both messages, not implicitly stored resources, and the language
-defines no synthetic scheme or READ-back convention for them.
+### §application-session-observation Exterior application port and session/loop observation
 
-## §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. 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
-    [*] --> 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 --> BODY: header newline or tolerated inline body
-    SLOTS --> DEFAULT: matching compact closer
-    BODY --> DEFAULT: matching standalone closer, no nested block
-    BODY --> BODY: nested literal block or other body content
-```
-
-## §whitespace-contract 11. Whitespace and interstatement text
-
-<!-- map -->
-| Tag | Promise |
+| Projection / Helper | Contract |
 | --- | --- |
-| {§response-text} | The parser owns the partition between operations and response text. |
-| {§unfenced-operation} | The parser identifies ignored unfenced fragments. |
-| {§recorded-emissions} | The parser is regressed against emissions models actually produced, not fixtures we wrote. |
-<!-- /map -->
+| `ApplicationPort` | Transport-neutral interface in `@plurnk/plurnk-contracts/port` driving workspaces, sessions, loops (`runLoop` with causal `source`, `attachments`, `envelope`), operations, proposals, client interactions, and event subscriptions (`ApplicationOperationEvent`). |
+| `selectSessionLoop` | Chooses `running` before `parked` before `queued` (oldest unresolved sequence wins ties); with no live work, the latest terminal settlement wins. Maintenance-only loops do not change this projection. |
+| `lifecycleOfLoopStatus` | Maps loop status to client lifecycle vocabulary: no loop `idle`; `100` `queued`; `102` `running`; `202` `parked`; `< 400` `completed`; `499` `cancelled`; `>= 400` `failed` (`413` budget, `429` turn ceiling, `500` fail, `504` timeout, `508` runaway). |
+| `excerptOf` | Extracts the first non-blank line of a message truncated to at most `N` code points without splitting a character, with trailing whitespace trimmed and `continued: boolean`. |
+| `ApplicationSessionOverview` | Projects non-hidden model-origin sessions (`{ workspaceId, id, name, parentSessionId, kind, lifecycle, gates, reply }`) ordered by most recently finished reply row first, then newest unreplied sessions, always including all gated sessions before applying `limit` and reporting `omitted`. |
 
-Body framing removes the header line ending and the single line ending
-immediately before the closing fence. Every other body character is preserved,
-including leading/trailing blank lines, indentation, CRLF and literal
-backslash escapes. A formatter adds its own framing newline even when a body
-already ends in one. Interstatement whitespace belongs to no body.
+---
 
-A header starts at column zero. Whitespace outside operation blocks is inert.
-Only a header aside has aside semantics. A matching closer ends its body, and no
-missing closer is inferred. No generic Markdown rendering, indentation stripping
-or recursive code-block extraction occurs. Exact source remains in `ops://<worker>/`
-under {§turn-ops-log-curation}; body bytes and source positions are unchanged.
+## §parse-recovery 8. Parse diagnostics, tolerances, and error shapes
 
-§response-text **The parser owns the partition between operations and response text.**
-The model-turn entry point returns each non-whitespace text span outside operation
-regions as an ordered `text` item with its exact content and source position.
-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 storing it as the turn's outside source ({§outside-text})
-and no-operation strikes ({§empty-turn}); parsing never infers delivery or completion
-intent.
+`PlurnkParseError` is a JSON-serializable `Error` carrying `{ line, column, source: "lexer" | "parser" | "visitor", severity: "error" | "warning", recovery?, attempt?, operationOmitted }`:
 
-§unfenced-operation **The parser identifies ignored unfenced fragments.** 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: `` Unfenced `KILL` ignored. ``
-This describes only that fragment, never a fenced operation elsewhere in the turn or its reasoning.
-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://`. A name with only an optional
-complete aside 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.
+| Representation | Line | Column | Absence or extent |
+| --- | --- | --- | --- |
+| Parser/AST `Position` | 1-based | 0-based Unicode code points | `UNKNOWN_POSITION = { line: 0, column: 0 }` is the sole unknown sentinel |
+| Notice `content-offset` | 1-based | 0-based Unicode code points | Omit or set `position` to `null` when unknown |
+| Contracts `TextRegion` | 1-based | 1-based Unicode code points | Start included, end excluded; equality is zero-width |
+| SARIF 2.1.0 region | 1-based | 1-based (`columnKind: "unicodeCodePoints"`) | End excluded; parser point adapters add 1 to `column` |
 
-§recorded-emissions **The parser is regressed against emissions models actually produced, not fixtures we wrote.** `test/fixtures/recorded-emissions.jsonl` holds one real exemplar of every distinct parse shape observed across the live and demo drills — the operations authored, whether outside text appeared, and the status the engine recorded at the time. A fixture encodes what we believe a model emits; a recording encodes what one did, so only recordings test the shapes models actually produce (#802, #809).
-
-| Fact | Rule |
+| Mechanism | Contract |
 | --- | --- |
-| Shape coverage, not volume | 120 exemplars are ~60 KB against ~88 MB for every emission ever recorded |
-| The recorded status | **provenance, never an assertion**: the contract has changed under these turns and will again, so the replay asserts only that today's parser still reads each emission the way the corpus says it does |
-| Regeneration | `scriptify/extract-emission-corpus.ts --write` after a drill; a changed shape is the contract moving and the diff names every shape that moved with it; the extractor also reports how many recorded turns concluded in a way the current contract would reject |
-
-## 12. Public API
-
-<!-- map -->
-| Tag | Promise |
-| --- | --- |
-| {§turn-shape} | `PlurnkParser.parse` accepts one model turn. |
-| {§tier-entrypoints} | Each parser entry point owns one document tier: |
-| {§runtime-neutral-root} | The package root is runtime-neutral. |
-| {§root-value-api} | The package-root runtime namespace is closed. |
-| {§parser-construction-boundary} | Parser construction components are internal rather than alternate consumer entry points: |
-<!-- /map -->
-
-The package root is the single JavaScript and TypeScript entry point for the language and wire
-contracts ({§runtime-neutral-root}). Shared AST and wire types come from generated schemas; the small hand-maintained parser
-types cover ordered parse items and `PlurnkParseError`, which JSON Schema cannot
-express. Consumers never receive ANTLR parse-tree or token types.
-
-§turn-shape `PlurnkParser.parse` accepts one model turn. A turn without any
-authored operation is reported by one hard diagnostic
-(`No valid Operation Syntax OPs detected.`), alongside any response text
-({§response-text}). Core admits this as a recoverable turn under {§empty-turn},
-silently: the diagnostic is the parser's report to its host, never a notice the
-model is shown.
-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.
-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
-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 model turn, including recoverable outside text and operation diagnostics | `PlurnkStatement`     |
-| `PlurnkParser.parseStatements` | Zero or more protocol statements                              | `PlurnkStatement`     |
-
-Every entry point returns ordered `statement` and `error` items. The model-turn
-entry point also returns `text` items under {§response-text}. When present,
-{§unparsed-tail-boundary} governs the result's item
-extent. The statement `op` field discriminates the generated per-operation
-union.
-
-§runtime-neutral-root **The package root is runtime-neutral.** A browser type-checks it with DOM
-libraries and no Node globals: nothing it reaches names a Node module or global. The application port
-({§application-port}), whose HTTP host hands an adapter Node's request and response ({§http-host}), is
-the one Node-bound contract and its own types-only entry, `@plurnk/plurnk-contracts/port`, with
-`HttpHost` and `HttpRouteHandler`; the types it speaks stay in the root. A helper that reads a request
-takes only its headers (`RequestHeaders`), which a Node request satisfies. Lint checks the root's whole
-source graph under those settings (`tsconfig.browser.json`).
-
-§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`, `isPlurnkOp`, `INTERNAL_ROW_OPS`, `PLURNK_FENCE` | The closed operation alphabet, its membership test, and the language's fence | {§canonical-statement} |
-| `PROPOSAL_POLICIES` | Server proposal disposition vocabulary | {§proposal-policy} |
-| `WORKER_NAME`                                       | Authority minting predicate                                         | {§worker-name}                            |
-| `UNKNOWN_POSITION`                                  | Frozen sentinel for an AST statement without retained parsed source | {§parser-position}                        |
-
-The remaining values are small pure helpers over those contracts (`isExecution`, `writtenOp`,
-`lifecycleOfLoopStatus`, `selectWorkerLoop`, `renderJsonResult`, `formatJsonDocument`,
-`aguiConformanceReport`, `requestOrigin` for {§http-request-origin}) and the closed name patterns
-and vocabularies (`RUNTIME_TAG`, `SKILL_NAME`, `EFFORTS`).
-
-§parser-construction-boundary Parser construction components are internal rather
-than alternate consumer entry points:
-
-| Internal component                         | Boundary                                                                                                      |
-|--------------------------------------------|---------------------------------------------------------------------------------------------------------------|
-| `AstBuilder`                               | Consumes generated ANTLR contexts; `PlurnkParser` and `parsePath` own its API                                |
-| `PlurnkErrorStrategy`, `RecordingListener` | Assemble parser recovery and diagnostics around `antlr4ng`; consumers receive `PlurnkParseError` values       |
-
-## 13. Runtime-neutral wire contracts
-
-<!-- map -->
-| Tag | Promise |
-| --- | --- |
-| {§wire-entrypoint} | The package root exports generated wire types, `Problems`, `Validator` and the value guards `isRecord`,… |
-| {§text-region} | 13.1 Text regions |
-| {§range-extent} | 13.2 Range extents |
-| {§entry-read-result} | 13.3 Client entry reads |
-| {§operation-result} | Every public PLURNK operation returns one `OperationResult`: |
-| {§diagnostic-observation} | A diagnostic says what happened, never why. |
-| {§problem-details} | `ProblemDetails` requires `type`, `title`, `status`, and `detail`; `instance` is optional until a durable… |
-| {§problem-error-carrier} | `Problems.fromError(error)` recognizes existing failure carriers without depending on a producer's exception… |
-| {§problem-projection} | `ProblemProjection` is the sole compact model-packet view of an exact `ProblemDetails`. |
-| {§notice} | A `Notice` is a transient, nonterminal observation. |
-| {§notice-directive} | A Notice's `message` states what happened ({§diagnostic-observation}). |
-| {§client-display-capabilities} | 13.7 Client display capabilities |
-| {§mcp-server-definition} | 13.8 MCP server definitions |
-| {§mcp-oauth} | `McpOAuth` is the client-managed OAuth plurnk holds for one Streamable HTTP server, included in that server's… |
-| {§application-port} | 13.9 Exterior application port |
-| {§application-worker-observation} | Worker observation exposes identity, lineage, kind and lifecycle; it is neither a client binding nor a… |
-| {§loop-lifecycle-vocabulary} | One projection maps a loop's durable status onto the lifecycle words every client renders, shared by the… |
-| {§list-excerpt} | A list shows a message by its excerpt. |
-| {§application-worker-overview} | The worker overview is the places in a scope with what waits there. |
-| {§application-loop-observation} | Loop observation exposes the durable scheduler state of work loops (excluding maintenance-only administrative… |
-<!-- /map -->
-
-§wire-entrypoint The package root exports generated wire types, `Problems`, `Validator` and
-the value guards `isRecord`, `isSafeInteger` and `errnoCode` alongside the AST types. Their owning
-JSON Schemas are published through `@plurnk/plurnk-contracts/schema/*.json`, not re-exported
-as root values.
-
-### §text-region 13.1 Text regions
-
-`TextRegion` identifies one contiguous region of textual content:
-
-| Required field | Coordinate                                                |
-|----------------|-----------------------------------------------------------|
-| `startLine`    | Line containing the included start                        |
-| `startColumn`  | Unicode code-point column of the included start           |
-| `endLine`      | Line containing the excluded end                          |
-| `endColumn`    | Unicode code-point column immediately after the selection |
-
-Lines and columns are positive safe integers and 1-based. Columns count Unicode
-code points. LF, CRLF, and CR are line separators; CRLF is one indivisible
-separator, and separator code units are not column positions. The end is
-exclusive; equal start and end coordinates identify a zero-length insertion
-point. A producer supplies all four coordinates or omits the region. It never
-substitutes UTF-16 offsets, readable-row indices, or partial coordinates.
-`Validator.assertTextRegion` rejects an end before its start.
-
-### §range-extent 13.2 Range extents
-
-`RangeExtent` is the compact wire projection of one line or ordered-result
-selection: `{ unit, total, requested: [first,last], returned?: [first,last] }`.
-`requested` preserves the numeric request, including invalid fractional
-evidence on a failed selection; a one-position request therefore repeats its
-endpoint. Successful selection endpoints are integers. `total` is the complete
-available cardinality.
-`returned` names the inclusive positions actually projected and is absent for
-an empty selection or a failed request. Its endpoints are positive, ordered,
-and no greater than `total`.
-
-The transparent coordinates make completion and continuation derivable. The
-shape has no separate `complete`, `next`, or all-results instruction. Exact
-text-coordinate selections use {§text-region} instead. `Validator.assertRangeExtent`
-enforces both the schema and the relational endpoint invariants. `unit: "byte"`
-names a selection of a binary resource's bytes, positions being 1-based byte
-offsets; the byte view is one octet per line, so the same positional algebra
-applies ({§read-bytes} in the core specification).
-
-### §entry-read-result 13.3 Client entry reads
-
-`EntryReadResult` is the exact transport-neutral projection of one entry. It
-does not expose workspace IDs, storage owner IDs, split persistence-coordinate fields,
-scope, or other persistence columns.
-
-| Outcome | Exact shape                                                      |
-|---------|------------------------------------------------------------------|
-| Success | `{ status: 200, entry: ClientEntry }`                            |
-| Failure | `{ status: 400..599, problem: ProblemDetails, entry: null }`      |
-
-| `ClientEntry` field | Contract                                                                                     |
-|---------------------|----------------------------------------------------------------------------------------------|
-| `entryId`           | Positive durable entry identifier, or `null` for a representation core computes rather than stores |
-| `target`            | Client selector for the resolved entry, with any channel fragment removed                    |
-| `channels`          | Every channel for a full read, or exactly the selected channel for a sliced read, by name; the empty name is the unnamed default channel of a scheme whose default is unnamed, a log row's |
-
-| Channel field   | Contract                                                                                                      |
-|-----------------|---------------------------------------------------------------------------------------------------------------|
-| `content`       | Full content, or the suffix beginning at `contentOffset`                                                      |
-| `contentOffset` | Actual Unicode-code-point offset of `content`; zero for a full read and capped at `contentLength`              |
-| `contentLength` | Unicode-code-point length of the complete stored channel                                                      |
-| `mimetype`      | Stored channel mimetype                                                                                        |
-| `weight`        | Stored model-independent curation weight for the complete channel                                            |
-| `state`         | `static`, `active`, `closed`, or `errored`                                                                     |
-
-For every returned channel,
-`contentOffset + codePointLength(content) === contentLength`. Therefore an
-offset beyond the current end returns empty content at `contentLength`, not the
-unbounded requested offset. `Validator.assertEntryReadResult` enforces the
-schema, this suffix invariant, and Problem status equality.
-
-### 13.4 Operation results
-
-§operation-result Every public PLURNK operation returns one `OperationResult`:
-
-| Status  | Required shape                            |
-|---------|-------------------------------------------|
-| 100–399 | `problem` is forbidden                    |
-| 400–599 | One RFC 9457 `problem` object is required |
-
-Producer-specific success fields and Problem Details extension members remain
-open. A malformed result is
-an internal producer contract violation; it is not converted into a second
-model-facing failure envelope.
-
-### 13.5 Diagnostics and Problem Details
-
-§diagnostic-observation **A diagnostic says what happened, never why.** Every Problem `detail`
-and `recovery`, parse diagnostic and notice names what was read, what was done with it, and
-where, and may show the working form of the construct it read or refused. It never names a cause
-or an intent the input does not establish: no likely mistake, no reconstruction of what the author
-meant, no alternative the producer did not apply, and no form the language no longer has. Each
-sentence presupposes only what the producer itself decided.
-
-§problem-details `ProblemDetails` requires `type`, `title`, `status`, and `detail`;
-`instance` is optional until a durable host can attach the occurrence URI.
-
-| Field       | Contract                                                                                                                                |
-|-------------|-----------------------------------------------------------------------------------------------------------------------------------------|
-| `type`      | Stable absolute URI for the problem class                                                                                               |
-| `title`     | Stable summary with no occurrence data or instruction                                                                                   |
-| `status`    | Equals the containing operation status                                                                                                  |
-| `detail`    | Tersely states the failed subject, observed fact, and violated constraint at the layer that knows the cause                             |
-| `instance`  | Durable URI for this occurrence                                                                                                         |
-| `stage`     | Stable failed stage, only when neighboring stages imply different recovery                                                              |
-| `recovery`  | One generally valid next action; omitted when the producer cannot know                                                                  |
-| `retryable` | `true` only when the producer recommends automatically retrying the identical request; otherwise false or unknown/omitted as applicable |
-| extensions  | Factual producer-known operands or constraints                                                                                          |
-
-`detail` is failure truth; `recovery` is not a second explanation. Producers do
-not blame the model, restate status, or expose an implementation accident as the
-cause ({§diagnostic-observation}). General syntax and workflow teaching remain in the model
-packet rather than being repeated in every Problem.
-
-`Problems.create(owner, code, status, detail, extensions?, options?)` derives a
-stable title from `code` unless an established type supplies
-`options.title`. Occurrence-specific text never belongs in `title`.
-
-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.
-
-| Projection member | Contract |
-|-------------------|----------|
-| `type`, `detail` | Always retained; together they identify the stable class and occurrence-specific cause |
-| `stage`, `recovery`, `retryable`, extensions | Retained only when present and not exactly duplicated by the enclosing row |
-| `title`, `status`, `instance` | Forbidden; the exact Problem owns stable title and occurrence identity while the enclosing packet row already owns model-facing status and address |
-
-Projection never mutates or replaces the exact Problem. Durable storage,
-external protocols, clients, and forensic artifacts continue to receive the
-complete RFC 9457 object.
-
-### 13.6 Notices
-
-§notice A `Notice` is a transient, nonterminal observation. It cannot determine durable
-failure truth, lifecycle, scheduling, or recovery. Sharing a renderer with
-Problems does not merge their semantics.
-
-§notice-directive A Notice's `message` states what happened ({§diagnostic-observation}).
-When the observation concerns the model's own output, the producer may attach one
-`directive`: `YOU MUST`, `YOU MUST NOT`, `YOU MUST ONLY`, `YOU SHOULD` or
-`YOU SHOULD NOT`, then the rule. An observation of the environment carries none.
-Clients display the message; the model packet leads with the directive.
-
-### §client-display-capabilities 13.7 Client display capabilities
-
-`ClientDisplayCapabilities` is the transport-neutral installed-capability
-projection used by external clients. It is an ordered array of closed,
-discriminated values:
-
-| `kind` | Identity field | `display` |
-|--------|----------------|-----------|
-| `scheme` | Non-empty `scheme` URI-family name | `CapabilityDisplay` |
-| `mimetype` | Non-empty `mimetype` media type | `CapabilityDisplay` |
-
-`CapabilityDisplay` is a closed object whose optional `glyph` is a non-empty,
-opaque string. Frameworks own and validate their intrinsic
-declarations; Core owns composition of the installed extensions; interface
-modules expose this exact shape; clients own rendering, font support, theme,
-and identity fallback when `glyph` is absent. Empty framework sentinels are
-normalized to absence at composition. Display metadata is client state, never
-model-language syntax or model packet teaching.
-
-### §mcp-server-definition 13.8 MCP server definitions
-
-`McpServerDefinition` is the one definition the workspace `mcp` Functionality family
-accepts and persists: one complete connection definition with its alias `name`.
-It is a closed union of the two supported transports, `stdio`
-(`command`, optional `args`, `env`, `cwd`) and `streamable-http` (`url`, optional
-`headers` and `authorization`). Source provenance, workspace scope, connection
-state, catalog and resolved credentials are not definition fields. Adding or
-removing a definition does not install or remove a plugin. Transport and
-authentication fields replace together ({§configuration-definition-resolution}).
-
-§mcp-oauth `McpOAuth` is the client-managed OAuth plurnk holds for one Streamable
-HTTP server, included in that server's `authorization`. Interactive OAuth always requires a callback URL, and
-its structurally exclusive identity modes are an HTTPS Client ID Metadata Document URL,
-a pre-registered client ID with a symbolic secret, or neither for server-advertised
-Dynamic Client Registration. Any interactive mode may name the `issuer` its sign-in binds to,
-where discovery starts, and `authorizationParams` added to the authorization request; the
-parameters the flow sets itself cannot be named. A client-credentials grant names its client ID and
-symbolic secret, optionally binding an issuer. Every secret is one complete `${NAME}`
-reference to the operator environment; `Validator.assertMcpOAuth` validates the shape.
-
-`SkillDefinition` is the one definition the workspace `skills` Functionality
-family accepts and persists: the standard `name`, its `source`, an optional git
-`ref`, and the `commit` the service recorded. Only host-provided trees omit
-`source`; installation scopes are not part of this shape. `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 source resolution and lifecycle
-({§skills-functionality}).
-
-`A2aAgentDefinition` is the one definition the Worker `a2a` Functionality
-family accepts and persists: the local alias `name` (the `a2a://<name>`
-authority), the remote `url` whose standard Agent Card remains the protocol
-authority, and optional local `cardPath`, `headers`, and bearer
-`authorization` whose token is a symbolic `${NAME}` reference.
-`Validator.assertA2aAgentDefinition` is the family's admission boundary.
-
-### §application-port 13.9 Exterior application port
-
-`ApplicationPort` is the single transport-neutral TypeScript contract through
-which an exterior adapter drives and observes the Plurnk application. Core
-implements it; AG-UI, A2A, and other interface modules consume it from
-`@plurnk/plurnk-contracts/port` ({§runtime-neutral-root}). The port
-contains typed application calls and a scoped event subscription, not wire
-route names, protocol framing, persistence access, or adapter-specific methods.
-An exterior adapter owns its own protocol validation, identity binding, and
-projection while reusing the same workspace, worker, loop, operation, proposal,
-interaction, and event owners through this port.
-
-`ApplicationOperationEvent` is the schema-owned dispatch observation consumed
-through that subscription; its production boundary is {§notifications-operation-event}.
-
-`configurationNotices` exposes current launcher-owned configuration diagnostics
-without acquiring a workspace or provider. Adapters use the existing Notice
-projection; model turns combine these with workspace diagnostics according to
-{§configuration-repair-path}.
-
-`runLoop.source` is trusted causal provenance supplied by an adapter, distinct
-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 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 identity, lineage, kind and lifecycle; it is neither a client binding nor a permission grant.** It exposes durable identity, origin, immediate parent identity, minted `kind` (`root` for a worker with no parent; `fork` for a child carrying a fork boundary; `work` for any other child), and `lifecycle`, the worker's representative work loop projected through {§loop-lifecycle-vocabulary} (`idle` when it has none), and `hidden_at`, when the worker was hidden ({§place-hiding}), null while it is shown. A client renders kind and lifecycle, it never infers them.
-
-| Fact | Rule |
-| --- | --- |
-| `selectWorkerLoop` | chooses running before parked before queued; ties select the oldest unresolved sequence; with no live work, the latest terminal settlement wins (sequence breaks equal timestamps); newer terminal history never hides unfinished work; maintenance-only loops do not change this projection, and their ordinary turns and results remain durable history |
-| `readWorker` | resolves exactly one id or name and returns `null` when absent |
-| `listWorkers` | filters collections by origin, lineage position or mark; an omitted parent filter means every position and an explicit `null` means roots; an omitted `hidden` means shown and hidden workers alike; singular and plural cardinalities are distinct contracts |
-
-§loop-lifecycle-vocabulary One projection maps a loop's durable status onto the
-lifecycle words every client renders, shared by the status gauge and the worker
-directory: no loop `idle`; 100 `queued`; 102 `running`; 202 `parked`; any other status is a
-concluded loop's: below 400 `completed`; 499 `cancelled`, a loop stopped without failing
-({§agui-run-outcome}); any other of 400 or more `failed` (413 budget, 429 turn ceiling, 500 fail,
-504 execution timeout, 508 runaway). `lifecycleOfLoopStatus`
-in `@plurnk/plurnk-contracts` is that projection's one owner.
-
-§list-excerpt **A list shows a message by its excerpt.** The excerpt is the message's first line holding anything but
-blanks (spaces, tabs and line ends), cut to at most N characters, a character never cut in two, with blanks trimmed from
-its end; `continued` says whether anything but blanks follows. `excerptOf` in `@plurnk/plurnk-contracts` is that rule's one
-owner, for a loop's opening in a worker's loop list ({§agui-worker-loops}) and a worker's latest finished reply
-({§worker-finished-reply}).
-
-§application-worker-overview **The worker overview is the places in a scope with what waits there.** A place is a
-model-origin worker; bookkeeping workers are not places. The scope is the daemon or one workspace; hidden places are out
-of it ({§place-hiding}).
-
-| Fact | Rule |
-| --- | --- |
-| A place | `{ workspaceId, id, name, parentWorkerId, kind, lifecycle, gates, reply }`: `kind` and `lifecycle` as {§application-worker-observation} projects them, `gates` the proposals and client interactions it waits on as `pendingProposals` and `pendingClientInteractions` project them, `reply` its latest finished reply or `null` |
-| A reply | `{ id, coordinate, completion, at, excerpt, continued }`: its durable log row, `L/T/S` in its worker's log, the completion its receipt records, when it was recorded (Unix milliseconds) and its excerpt ({§list-excerpt}) |
-| Order | most recently finished first, by reply row (the log's commit order, so two replies never tie), then the places with no reply, newest first |
-| Bound | every place waiting on a gate, then the first `limit` in that order; `omitted` counts the places in scope it leaves out, so no place is left out silently |
-| Workspaces | `{ id, name, projectRoot, projectLabel }` for each workspace a held place belongs to ({§workspace-label}) |
-
-§application-loop-observation Loop observation exposes the durable scheduler
-state of work loops (excluding maintenance-only administrative loops), nullable
-`waitUntil` (the durable observation deadline in Unix milliseconds), the times a loop first
-ran (`claimedAt`, {§loop-claim-latency}) and concluded (`terminatedAt`), ISO 8601 UTC and null
-until they happen, exact terminal `OperationResult`, the operation that opened the loop
-(`invocation`: its Worker and log address, {§worker-obligations}; null when no Worker's operation did),
-and exact count of packet-bearing
-Turns for one owned Worker. Packetless producer Turns and physical provider
-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.
-
-## 14. Parse diagnostics
-
-<!-- map -->
-| Tag | Promise |
-| --- | --- |
-| {§parse-diagnostics} | `PlurnkParseError` is a JSON-serializable Error subclass. |
-| {§parse-admission} | A diagnostic's severity does not describe whether an operation ran. |
-| {§parse-recovery} | Every hard diagnostic carries its working form. |
-| {§parser-position} | Parser source locations are points, not text regions. |
-| {§inline-flag-tolerance} | PCRE inline modifiers. |
-| {§regex-trailing-text} | A valid `/pattern/flags` prefix followed by horizontal whitespace and trailing text receives one concise… |
-| {§regex-sed-range} | A sed line range is named as one. |
-| {§unclosed-regex} | A regex that never closes. |
-| {§naked-pattern} | The matcher rides the heading bare. |
-| {§trailing-slots} | Slots after the matcher peel off the right. |
-| {§log-heading-notation} | The log's heading notation, copied as syntax, is read as the slot it stands for. |
-| {§bare-target} | A target written without its parentheses is refused with the line that runs. |
-| {§bare-anchor-scope} | An EDIT's anchor without its angle brackets is its scope. |
-| {§matcher-body-redirect} | Unread selector text. |
-| {§combined-anchor-tolerance} | Combined line number and anchor in a scope. |
-| {§invalid-scope-diagnostic} | Malformed scope content. |
-| {§error-shape} | The diagnostic class determines the parts of a message; every class says what happened, never why… |
-| {§parse-attempt} | A hard fact that refused a statement the parser opened carries its `attempt`: the statement's text exactly as… |
-| {§unparsed-tail-boundary} | When the lexer cannot determine where a malformed statement ends — an unfinished `(target` or `[metadata`… |
-<!-- /map -->
-
-§parse-diagnostics `PlurnkParseError` is a JSON-serializable Error subclass.
-Its `message` contains only the parser-owned diagnostic; position, source, and
-severity remain separate facts.
-
-```typescript
-type ErrorSource = "lexer" | "parser" | "visitor";
-type Severity = "error" | "warning";
-
-class PlurnkParseError extends Error {
-    readonly line: number;
-    readonly column: number;
-    readonly source: ErrorSource;
-    readonly severity: Severity;
-    readonly recovery: string | undefined;
-    readonly operationOmitted: boolean;
-}
-```
-
-§parse-admission **A diagnostic's severity does not describe whether an operation ran.**
-`operationOmitted` identifies unexecuted unfenced operations and unrecovered native
-calls. A warning about a retained operation or a quoted
-example does not set it. This fact survives serialization when true; consumers do
-not infer it from diagnostic wording. It does not independently prescribe a strike.
-
-§parse-recovery **Every hard diagnostic carries its working form.** A `severity: "error"`
-diagnostic names, in `recovery`, the form of the construct it refused, 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. ``), a refused scope the scope's form, and a refused
-matcher its dialect's form with an example (`` A pattern is a regex written `/pattern/flags`, such
-as `/timeout/i`. ``). The working form is the language's, never a reconstruction of the input
-({§diagnostic-observation}). The runtime projects `recovery` as the Problem's `recovery` beside the
-verbatim `message`; an advisory carries none. A refused matcher carries
-the same pair into its own operation's Problem ({§matcher-refusal}).
-
-§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
-the undefined tail begins. A
-statement constructed without retained parsed source uses `UNKNOWN_POSITION`,
-the unknown sentinel; its dispatch origin remains a separate fact.
-
-| Representation                      | Line                     | Column                                   | Absence or extent                                      |
-|-------------------------------------|--------------------------|------------------------------------------|--------------------------------------------------------|
-| Parser/AST `Position`               | 1-based                  | 0-based Unicode code points              | `{ line: 0, column: 0 }` is the sole unknown sentinel  |
-| Notice `content-offset`             | 1-based                  | 0-based Unicode code points              | Omit or set `position` to null when unknown            |
-| Contracts `TextRegion`              | 1-based                  | 1-based Unicode code points              | Start included, end excluded; equality is zero-width   |
-| SARIF 2.1.0 line/column region      | 1-based                  | 1-based, declared by `columnKind`        | End excluded; equality is zero-width                   |
-
-Parser columns count code points, not UTF-16 code units or grapheme clusters.
-LF and CRLF delimit source lines; a lone CR occupies one column. A point may sit
-immediately after the final code point and carries no implicit character extent.
-Consumers preserve parser points unchanged inside PLURNK. A SARIF adapter that
-preserves one must add one to `column`, declare `columnKind` as
-`"unicodeCodePoints"`, and emit equal start/end coordinates rather than
-inventing an extent. `TextRegion` already uses SARIF's base and exclusive-end algebra but
-remains a distinct contracts-owned representation. See [SARIF 2.1.0 §§3.14.26–27
-and 3.30.2](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html).
-
-| Source      | Boundary                                                                               |
-|-------------|----------------------------------------------------------------------------------------|
-| `"lexer"`   | Token-level failure, such as an unrecognized character or malformed `<L>` integer.     |
-| `"parser"`  | Structural failure, such as the wrong heading depth or slot order.                     |
-| `"visitor"` | Semantic AST-construction failure, such as an invalid matcher dialect or signal shape. |
-
-`severity` distinguishes a hard error from a non-fatal advisory. The parser is
-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}). 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:
-
-- §inline-flag-tolerance **PCRE inline modifiers.** A regex whose pattern opens with
-  `(?i)`, `(?m)`, `(?s)` or a combination — the pretrained spelling of a flag, which
-  ECMAScript refuses as an invalid group — is read with those letters lifted into
-  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.
-  `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 {§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
-  names the canonical position, because here the model *can* learn a better spelling.
-- §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
-  intended to represent — except `-flags`, which {§regex-dialect-readings} reads as
-  the flags. Invalid patterns or flags retain the native regex failure; no branch
-  silently removes or executes trailing content. Each diagnostic is the matcher's
-  refusal ({§matcher-refusal}).
-- §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 ({§matcher-refusal}) as a range, never as invalid flags: the
-  diagnostic names the range suffix and gives the regex matcher's working form.
-  It does not synthesize a different selector or a workflow ({§diagnostic-observation}).
-- §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
-  the heading's own boundaries bound it ({§naked-pattern}: the matcher runs to the end
-  of the heading, and an aside is lexed apart from it). A bare `/` with nothing after
-  it has no pattern to read and is refused as `invalid-operation-syntax` naming what
-  is missing. A matcher with a second unescaped `/` is not unclosed: it is
-  `/pattern/flags`, and invalid flags keep their native failure with the escape hint.
-- §naked-pattern **The matcher rides the heading bare.** After the path, and any scope or option block, the rest of a FIND, READ or KILL heading line is the matcher, in whichever dialect its first characters claim ({§matcher-prefix-claims}): `/re/i`, `^anchored`, `//xpath`, `$.json`, `~words`, `&symbol`, or a sigil-less glob or literal such as `TODO` or `*.ts`. `FIND (src/parser.ts) /\bparse\w+\b/` is the same operation as `FIND (src/parser.ts) [{"pattern": "/\\bparse\\w+\\b/"}]`: the lift is exactly what `[{"pattern": "…"}]` produces, and that option remains the escape for a matcher the heading cannot hold bare — one opening with `(`, `<`, `[` or a backtick, one containing `<!--`, and every COPY/MOVE operand.
-
-  | Fact | Rule |
-  | --- | --- |
-  | Not a matcher | `#name` alone, a `#` followed by one channel token and nothing else, after a target that names no channel, is that target's channel exactly as if written on the path ({§local-path-fragment}); a target that already names a channel keeps such a token as its pattern |
-  | Independence | heading matchers remain independent of owner options: a block without `pattern` never erases the heading matcher, and invalid blocks still reach the owning validator; their heading-line text owns selection independently of annotation or distillation bodies |
-  | EDIT | only a sigil lifts, because plain heading-line text is the replacement body it always was; the lines beneath the heading are then the replacement, and none deletes each match ({§edit-pattern}) |
-  | The aside | a trailing `<!-- aside -->` on the same line stays the aside |
-  | `^` | claims the regex dialect without slashes or flags: the whole text is the pattern, so `READ (notes.md) ^Decision:.*` selects lines beginning with `Decision:`; `^` is deliberately absent from `plurnk.md`'s dialect table — a model writes the anchor whether or not it is taught, so the engine honours it without spending hot-path teaching on it, and the omission is not drift between the teaching and the engine |
-
-- §trailing-slots **Slots after the matcher peel off the right.** The heading text after the matcher is read backwards: a trailing `<!-- aside -->`, a trailing `<scope>` in the shapes the lexer admits (result positions on FIND, text coordinates elsewhere) and a trailing `[option block]` that parses as an array of objects come off the right end in any order, each taken once and only when the heading did not already carry that slot, until what remains is the matcher. `READ (a.rs) /fn resolve_/ <1,-1> <!-- entities -->` is the same operation as `READ (a.rs) <1,-1> /fn resolve_/ <!-- entities -->`, with one warning-severity advisory naming the canonical order for the scope or block.
-
-  | Fact | Rule |
-  | --- | --- |
-  | Recovery | requires a single possible path-slot owner: with multiple slots, a trailing scope or metadata block refuses the heading rather than relocating or discarding the slot |
-  | A matcher that itself ends in one of those shapes | takes the option escape |
-  | Teaching | `plurnk.md` teaches one order — `OP (path)? <scope\|range>? [metadata]? pattern? <!-- aside -->?` — and free ordering is not taught; small departure, small reinterpretation ({§outside-text}): every slot the model wrote is present and unambiguous, so only their sequence differs from the taught form, and nothing is invented to read it; the advisory names the canonical order rather than refusing, because the operation the model meant is never in doubt |
-
-- §log-heading-notation **The log's heading notation, copied as syntax, is read as the slot it
-  stands for.** A packet's log row heading is `### log:///L/T/S/OP → path pattern · N`
-  ({§log-wire-format} in the core SPEC); models copy its notation onto their own headings. Each
-  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 -->`. `` |
-  | `FIND (x) <84,180> · no <!-- read the helpers -->` | the comment is the aside; the dot note before it is stray text, dropped | `` `· no` was ignored; the aside is `<!-- read the helpers -->`. `` |
-
-  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,
-  `` `READ` has no target: `a.py` stands where the target goes. ``, whose recovery is the operation's
-  working form ({§parse-recovery}).
-- §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 **Unread selector text.** An option block's `pattern` owns the
-  selector; surplus heading text is unused with one warning naming its location.
-  A non-log KILL's body is likewise unused: `This KILL takes no body; line 2 was not used.`
-  Neither warning echoes discarded text. No operation recovers a matcher from below
-  its header. READ/FIND bodies follow {§retrieval-annotation}; log KILL bodies follow
-  {§log-kill-distillation}.
-- §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.
-- §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, text coordinates, or no scope. Do not append advice for
-  other operations or infer why the producer supplied the value. A text-coordinate
-  scope that pairs an anchor with the same five characters unmarked (`<@abcde,fghij>`)
-  states the anchor rule instead, with the scope marked: `` every line anchor carries
-  its `@`: `<@abcde,@fghij>` ``. Spacing and boundary-loss diagnostics retain their own
-  contracts.
-
-§error-shape The diagnostic class determines the parts of a message; every class says what
-happened, never why ({§diagnostic-observation}). 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                                                                                                  |
-|---------------|-----------------------|-------------------------------------------------------------------------------------------------------------------|
-| Hard fact     | `severity: "error"`   | What was read, where, and the constraint it violates, in PLURNK vocabulary; `recovery` is the construct's working form ({§parse-recovery}). |
-| Advisory      | `severity: "warning"` | What was read and what was done with it, read as a named construct or not used, and where; the statement remains admitted. |
-| Boundary loss | `unparsedTail`        | Where trust ends and which header slot remains open; later input is undefined.                                   |
-
-All messages use PLURNK protocol vocabulary: opening fence, closing fence, target,
-scope, line marker, body, section boundary, or space between slots. They never
-expose ANTLR rule or token names. They refer to a slot or
-feature rather than an implementation rule. Generic tutoring, coordinate
-restatement and multiple repair strategies are forbidden, and no message names an
-intent ({§diagnostic-observation}).
-Unexpected top-level text immediately after a closed operation identifies that
-operation's opening line, closing line, and matching backtick count.
-
-§parse-attempt A hard fact that refused a statement the parser opened carries its `attempt`: the
-statement's text exactly as written, from its opening fence as far as the parser read it, and the
-`verb` that fence names, an operation keyword or an execution's runtime tag. A diagnostic that refused no opened
-statement, such as a lost boundary or a stray character outside every statement, carries none.
-
-Examples of canonical hard facts:
-
-- `unrecognized character '<' in target`
-- `unrecognized character '[' in the sh header`
-- `unrecognized character 'X' in statement header`
-- `unrecognized character '[' in the WAIT header`
-- `expected ')'; got ':'`
-
-Each malformed statement produces at most one hard error. The first recorded
-hard lexer or parser error within its source range wins; later failures in that
-same range are consumed rather than projected as a cascade. A visitor failure
-surfaces when syntax admitted the statement but AST construction did not.
-Independent malformed statements each retain one hard error. Advisories remain
-separate because they do not represent failed admission.
-
-§unparsed-tail-boundary When the lexer cannot determine where a malformed
-statement ends — an unfinished `(target` or `[metadata` slot on a heading line —
-the result's `unparsedTail` marks the position from which parsing gave up. A block
-without a closer is not such a case: it ends under {§closer-fallback}. `ParseResult.items` contains only facts that begin strictly
-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; the
-facts before it are ordinary facts, and a consumer that runs them owes the
-author the tail's reason.
-
-| Consumer duty      | Contract                                                                                                       |
-|--------------------|----------------------------------------------------------------------------------------------------------------|
-| 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   | 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.             |
-
-Serialization convention for transmission to the model (the agent
-runtime constructs this; the parser provides the fields):
-
-```json
-{
-    "line": 1,
-    "column": 12,
-    "source": "parser",
-    "severity": "error",
-    "message": "READ block opened at line 1 but was not closed with 3 backticks"
-}
-```
+| Working-form recovery & attempt | Every hard error (`severity: "error"`) populates `recovery` with the canonical syntax of the refused construct and `attempt` (`{ text, verb }`) with the refused statement's source text; `operationOmitted` marks unexecuted unfenced or native-call fragments. Each malformed statement produces at most one hard error. |
+| Regex and matcher tolerances | Lifts leading PCRE inline flags `(?ims)` with a warning; folds comma-separated `/pattern/` lists on `FIND` and `READ` into alternation with a warning while refusing numeric/open sed ranges (`/a/,+N`, `/a/,-1`, `/a/,`) and mutating `/a/,/b/` ranges; diagnoses trailing text after `/pattern/flags`; recovers unclosed `/pattern` at EOL; flags unused non-log `KILL` body lines (`This KILL takes no body; line 2 was not used.`). |
+| Heading & slot tolerances | Reads bare heading patterns (`naked-pattern`, treating bare `#channel` after a channelless target as its channel fragment), peels trailing `<scope>`/`[metadata]`/`<!-- aside -->` slots from the right of a matcher when the heading has a single target, refuses unparenthesized bare targets (`READ a.py <1,4>`), recovers bare `EDIT` anchors (`@abcde` -> `<@abcde>`) and combined `42<@abcde>` scopes, and sets `unparsedTail` when an unclosed `(target` or `[metadata` destroys statement boundaries. |
+| Log-heading notation recovery | Recovers copied log-heading forms with a warning advisory: `OP → path <scope>` is read as `(path)`; `· 900` / `· 320 tokens` token charges are dropped; `· note text` at the end of a heading is read as `<!-- note text -->` (or dropped when an explicit `<!-- aside -->` follows). |