@plurnk/plurnk-contracts 3.3.0 → 4.1.0

package/.env.defaults

@@ -9,3 +9,20 @@ PLURNK_PORT=1066
 # The whole URL a client dials instead: a remote portal, or a daemon bound to an address no
 # client can dial (0.0.0.0). Unset = http://$PLURNK_HOST:$PLURNK_PORT/agui.
 # PLURNK_AGUI_URL=
+
+# Whether the daemon authenticates ({§credential-authority}): 1 = every request to the client
+# interface and to the hosted agent presents a credential this daemon issued, and the daemon serves
+# the authorization server that issues them; 0 = no credential exists and every request is
+# anonymous, for a harness driving a daemon of its own. The posture is this value, never inferred
+# from what else is set.
+PLURNK_AUTH=1
+# The operator's client secret ({§agui-oauth-clients}): what the terminal client and every other
+# tool of yours exchanges for access tokens. Unset, the daemon mints one at every boot into the
+# file `secret` beside its database (0600), where a tool running as you reads it. Set it here, and
+# the same value in the tool's environment, for a tool on another host or under another user.
+# PLURNK_SECRET=
+# The operator's browser sign-in ({§agui-oauth-login}): the password a browser signs in with,
+# compared in constant time at the authorization endpoint. No browser is the operator without it:
+# while it is empty, the sign-in page says so and where to set it, and admits nobody
+# ({§agui-oauth-session}). The terminal client and your other tools use PLURNK_SECRET instead.
+PLURNK_PASS=

package/README.md

@@ -52,7 +52,9 @@ Validator.assertOperationResult(result);
 
 Generated wire types, constructors, and validators share the package root entry
 point described by SPEC {§wire-entrypoint}. Owning JSON Schemas use the published
-`@plurnk/plurnk-contracts/schema/*.json` subpaths.
+`@plurnk/plurnk-contracts/schema/*.json` subpaths. The root is runtime-neutral, so
+a browser type-checks it without Node; the application port that modules consume,
+which names Node's HTTP types, is `@plurnk/plurnk-contracts/port` ({§runtime-neutral-root}).
 
 ## Development
 

package/SPEC.md

@@ -16,7 +16,7 @@ runtime-neutral wire envelopes; `@plurnk/plurnk-parser` implements the language
 | Stopped-world client contract                                                   | `ProposalDisposition`, `ProposalProjection`         |
 | Client-owned interaction contract                                               | `ClientInteractionRequest`, `ClientInteractionProjection`, `ClientInteractionResolution` |
 | Client capability presentation                                                 | `ClientDisplayCapabilities`                         |
-| Exterior adapter application calls                                             | `ApplicationPort`                                   |
+| 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` |
@@ -295,11 +295,11 @@ wider bare fence nests where closing there would cost the reading more
 ({§fence-pairing}). A nested block ends at its first valid closer, as a CommonMark code block
 does. So a wider outer fence holds any narrower body, finished or not, and equal widths nest
 when every inner block closes. Preserve every nested body byte, including apparent operations
-and known executors, without dispatching them. These rules apply equally to model programs,
+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 naming a native operation or registered executor opens that
+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
@@ -328,7 +328,7 @@ aside, an operand, or other heading text does not qualify and remains the unfenc
 read this way.
 
 §fence-heading-in-body Outside a complete nested block ({§balanced-fences}), a fence
-line of three or more backticks and a name that is a native operation or a known executor
+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
@@ -356,8 +356,8 @@ input at once by {§fence-pairing}:
 | 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, naming nothing known | The opener of a nested block, or body |
-| Three or more backticks naming a native operation or known executor | A heading that ends the block, or a literal example |
+| 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
 
@@ -410,7 +410,7 @@ repaired reading: a complete nested interpretation takes precedence. Each class
 | Counted | Complete readings | Repaired readings | Why |
 |---|---|---|---|
 | Hidden operations: a heading that will not run, written at its block's width or wider | 1, together with the next row | 1 | Every operation the author wrote should run |
-| Repairs: a supplied closer (except a message's run to the end of the input, {§message-run-on}), a fence read as a stray, a narrower closer accepted, a body under an operation that takes none (FIND, READ, COPY, MOVE, 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 |
+| Repairs: a supplied closer (except a message's run to the end of the input, {§message-run-on}), a fence read as a stray, a narrower closer accepted, a body under an operation that takes none (COPY, MOVE, non-log targeted KILL), a body not well-formed in the media type its runtime declares ({§executor-invocation}) | none by definition | 2 | The least-errors distance |
 | Literal by declaration: a heading narrower than its block, or no wider than the labeled block or example holding it, or inside a quotation or a KILL, or an executor heading inside a SEND, WORK, FORK or BARE body ({§prose-code-blocks}); a labeled fence in a body read as text | 1, together with the row above | 3 | Every code block the author declared should stand |
 | 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 |
@@ -499,12 +499,11 @@ by the next opener is {§inline-chain}, and by nothing is the ordinary {§fence-
 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.** A fence tag that matches a
-registered executor's name case-insensitively opens that executor (`SH` opens
-`sh`), and the statement's `executor` is the registered spelling, so a lookup
-by that name never misses. Operation names stay uppercase by teaching and were
-never written otherwise in 12,000 fences; one `SH` in 1,300 `sh` fences was. An unregistered name without an accepted spelling
-({§executor-js-spelling}) is still prose ({§interstitial-fence}).
+§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
@@ -529,8 +528,8 @@ line takes the rest of the line as the aside, with one warning-severity advisory
 A closed aside followed by more text is unchanged.
 
 §quotation **A fence that opens no operation quotes.** Outside a body, a line-start fence that
-is not an operation heading — unlabeled, tagged like a code block (`ts`, `json`), or naming
-nothing registered — opens a
+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
@@ -552,23 +551,29 @@ belongs in a properly nested body ({§balanced-fences}) or a quotation ({§quota
 So a model may show plurnk's own operations in an answer. Two exceptions keep programs whole:
 CommonMark's own rule that a backtick opener's line carries no further backtick, so
 ```` ```READ (x)``` ```` is inline code and quotes nothing after it; and a bare fence directly under
-a line carrying a fence run, which is an orphaned closer and quotes nothing. An unknown tag at
-any width is a code block and draws nothing, unless its line carries a target slot, `(…)`: that
-is an operation the model missed by its tag, and it draws one warning — `` `OP` is not an
-operation or a known executor here. `` An offset example draws nothing either
+a line carrying a fence run, which is an orphaned closer and quotes nothing. An unknown tag
+without invocation slots is a code block and draws nothing. An offset example draws nothing either
 ({§indented-fences}). Quotation outside an operation is
 response text under {§response-text}, not an executable program or a completion envelope.
 
 `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 all quote. Each is a shape a model reaches for from ordinary Markdown rather than from this
+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.
 
-§interstitial-fence Only a native operation or a known executor opens a block. A fence naming
-anything else, or nothing at all, opens no operation: outside a block it quotes under
-{§quotation}, inside a body it is body.
+§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
@@ -655,7 +660,7 @@ beside owner metadata, not only a matcher carried inside its `pattern` option.
 
 | Element | Contract |
 |---|---|
-| Fence name | Reserved native OP, otherwise a registered executor or attached MCP service |
+| 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 |
@@ -722,20 +727,18 @@ compact empty block or permit unmatched fences.
 | 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, executors | One JSON object is the option block where the heading admits one ({§bare-option-object}); otherwise the body. |
+| 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. On an operation that takes an option block and no bare matcher — SEND, BARE, WORK, FORK and
-every executor fence — heading text after the slots that is exactly one JSON object `{…}`, where the
+block. On SEND, BARE, WORK and FORK, heading text after the slots that is exactly one JSON object `{…}`, where the
 heading admits a block (BARE, WORK and FORK only after their target), is read
 as `[{…}]`: the AST carries the array form, the written heading renders it, and one
 warning-severity receipt names the indulgence in place of the {§heading-inline-body} advisory:
-"`SEND` took a bare option object; the taught form is `[{…}]`." The option array is a house
-convention, not a language rule ({§scheme-metadata-modifier}): an executor whose declared body is
-JSON ({§executor-invocation}), an MCP tool, reads the object as its body instead — its arguments,
-written on the heading line — under {§heading-inline-body}. The host names those executors to the parse
-(`ParseOptions.jsonBodyExecutors`). A heading that already carries a block keeps the object as
+"`SEND` took a bare option object; the taught form is `[{…}]`." Executor headings always read an
+unbracketed object as input under {§heading-inline-body}, regardless of registration or input media
+type; their metadata is only the bracketed slot ({§scheme-metadata-modifier}). A heading that already carries a block keeps the object as
 inline body. On FIND, READ and KILL the same text is the matcher
 ({§naked-pattern}), because a search for JSON text is legitimate; a bare matcher
 that parses as a JSON object draws one advisory saying so: "`{…}` was read as the
@@ -744,8 +747,7 @@ 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 except
-for the narrowly owned {§misplaced-aside-advisory}.
+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.
@@ -783,13 +785,10 @@ the owner verbatim, and the owner's reader treats `pattern` as reserved. The
 language lifts only from one block that parses as a JSON array of objects;
 anything else lifts nothing and reaches the owner's `400` untouched. A
 `pattern` that is present but not a string is the language's own positioned
-diagnostic, as is a matcher of a claimed dialect that fails admission. FIND,
-READ, and targeted KILL take no body: a body beneath their heading is not used and
-the operation still runs, with one warning-severity advisory naming the lines not
-used (`FIND takes no body; lines 4–6 were not used.`); it is never silently read as a
-matcher, and it never strikes ({§matcher-body-redirect}). The heading line itself
-is the matcher's home ({§naked-pattern}). A body that is only an HTML comment is
-still the aside under {§misplaced-aside-advisory}. EDIT keeps its literal body:
+diagnostic, as is a matcher of a claimed dialect that fails admission. FIND and
+READ bodies become memory under {§retrieval-annotation}; a non-log KILL's body is
+unused and receives the advisory under {§matcher-body-redirect}. The heading line
+is the matcher's home ({§naked-pattern}). EDIT keeps its literal body:
 with a matcher it is the replacement for every selected span ({§edit-pattern}),
 and an absent body deletes them. `PlurnkParser.stringify` writes a lifted matcher
 whose block left no metadata back bare when the bare form reads back identically
@@ -814,8 +813,8 @@ governed by {§canonical-statement}; runtime conditions remain explicit below.
 
 | OP   | `(path)`                                     | `<scope>`                       | `body`                         |
 |------|----------------------------------------------|---------------------------------|--------------------------------|
-| FIND | required target or glob                      | optional result range           | empty                          |
-| READ | required target                              | optional text region            | empty                          |
+| 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                          |
@@ -828,11 +827,22 @@ governed by {§canonical-statement}; runtime conditions remain explicit below.
 | 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 NOTE-only turn does not request completion; ordinary
-repetition and strike rules still apply.
+automatically hidden. Each turn may contain zero or more NOTEs; their omission
+produces neither a notice nor a failure. A NOTE-only turn does not request
+completion; ordinary repetition and strike rules still apply.
 
 §reasoning-operations The shared fence parser admits complete, line-leading NOTE,
 FIND and READ statements from exposed provider reasoning. Admission is part of
@@ -856,9 +866,10 @@ 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. Any other name is an executor fence: its
-AST carries the `runtime` tag and no operation keyword, then `target`, metadata, timing and body fields.
-Registration is checked by the runtime, not by the syntax parser. An attached
+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
@@ -1094,8 +1105,7 @@ ingestion restriction: the parser decomposes arbitrary URL authorities.
 ## §matcher-prefix-claims 6. Bulk pattern matching
 
 FIND, READ, KILL, EDIT, and the COPY/MOVE operands accept an optional matcher
-through the `pattern` option ({§matcher-option}); the client-tier LOOK still
-carries its matcher as a body. AstBuilder assigns the dialect from the
+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.
@@ -1160,8 +1170,8 @@ statements remain recoverable when their boundaries are trustworthy.
 
 - §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}), one line by construction; the client-tier LOOK still carries its matcher as a body, and AstBuilder
-  rejects a multiline one before dialect classification. A regex that matches a
+  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.
 
@@ -1178,7 +1188,7 @@ The operation column names the canonical AST operation after
 | 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 / client LOOK    | 0/1/2/4 text coordinates               | Text projection from one exact selected file, entry, or log item           |
+| 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                      |
@@ -1199,7 +1209,7 @@ body, while unsupported arity is a runtime failure.
 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,
-KILL, and client LOOK preserve these positions in `TextLineMarker`; core resolves them
+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
@@ -1386,8 +1396,8 @@ reports how many recorded turns concluded in a way the current contract would re
 
 ## 12. Public API
 
-The package root is the single JavaScript and TypeScript entry point. Shared AST
-and wire types come from generated schemas; the small hand-maintained parser
+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.
 
@@ -1415,7 +1425,6 @@ blocks themselves are the program.
 |--------------------------------|----------------------------------------------------------------|-----------------------|
 | `PlurnkParser.parse`           | One model turn, including recoverable outside text and operation diagnostics | `PlurnkStatement`     |
 | `PlurnkParser.parseStatements` | Zero or more protocol statements                              | `PlurnkStatement`     |
-| `PlurnkParser.parseClient`     | Executable blocks, including the read-shaped LOOK command        | `ClientStatement`     |
 
 Every entry point returns ordered `statement` and `error` items. The model-turn
 entry point also returns `text` items under {§response-text}. When present,
@@ -1423,6 +1432,14 @@ entry point also returns `text` items under {§response-text}. When present,
 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
@@ -1443,8 +1460,8 @@ among them: the parser is `@plurnk/plurnk-parser`'s ({§parser-consumers}).
 
 The remaining values are small pure helpers over those contracts (`isExecution`, `writtenOp`,
 `lifecycleOfLoopStatus`, `selectWorkerLoop`, `renderJsonResult`, `formatJsonDocument`,
-`aguiConformanceReport`) and the closed name patterns and vocabularies (`RUNTIME_TAG`,
-`SKILL_NAME`, `EFFORTS`).
+`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:
@@ -1678,7 +1695,8 @@ authority, and optional local `cardPath`, `headers`, and bearer
 
 `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. The port
+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
@@ -1700,13 +1718,13 @@ it; Core validates and records it through the same prompt admission path.
 `runLoop.attachments` carries typed bytes selected by the adapter;
 `runLoop.envelope` retains opaque protocol evidence under
 {§message-envelope-evidence}. `readMessages` projects durable inbox messages
-and successful conversation replies independently of log visibility, retaining
+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 durable identity,
-origin, immediate parent identity, minted `kind` (`conversation`; `fork` for a
+origin, immediate parent identity, minted `kind` (`root` for a worker with no parent; `fork` for a
 child carrying a fork boundary; `work` for any other child), and `lifecycle`,
 the worker's representative work loop projected through {§loop-lifecycle-vocabulary} (`idle`
 when it has none). `selectWorkerLoop` chooses running before parked before queued;
@@ -1729,7 +1747,11 @@ in `@plurnk/plurnk-contracts` is that projection's one owner.
 
 §application-loop-observation Loop observation exposes the durable scheduler
 state of work loops (excluding maintenance-only administrative loops), nullable
-`waitUntil` (the durable observation deadline in Unix milliseconds), exact terminal `OperationResult`, and exact count of packet-bearing
+`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
@@ -1756,15 +1778,15 @@ class PlurnkParseError extends Error {
 ```
 
 §parse-admission **A diagnostic's severity does not describe whether an operation ran.**
-`operationOmitted` identifies unexecuted unfenced operations, unknown operation-shaped
-tags and unrecovered native calls. A warning about a retained operation or a quoted
+`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; READ takes no body. ``), a refused scope the scope's form, and a refused
+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
@@ -1853,7 +1875,7 @@ diagnostics are:
   that already names a channel keeps such a token as its pattern. Those
   matchers remain independent of owner options: a block without `pattern` never
   erases the heading matcher, and invalid blocks still reach the owning validator.
-  These operations take no body, so heading-line text can mean nothing else. On EDIT only
+  Their heading-line text owns selection independently of annotation or distillation bodies. On EDIT only
   a sigil lifts, because plain heading-line text is the replacement body it always
   was; the lines beneath the heading are then the replacement, and none deletes each
   match ({§edit-pattern}). A trailing `<!-- aside -->` on the same line stays the
@@ -1914,15 +1936,12 @@ diagnostics are:
   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 body text on bodyless operations.** FIND, READ and bodyless
-  KILL keep the statement but do not use text the matcher did not consume, with one warning
-  naming where it stands: `READ takes no body; lines 4–38 were not used.`, or `the text after its
-  heading on line 3` when it shares the heading's line. KILL's advisory says `This KILL`, limiting the claim to that invocation:
-  log distillation bodies remain valid. Delivered like
-  {§misplaced-aside-advisory} as a `parse_advisory` notice (a warning, never an error).
-  One sigil line beneath a bodyless heading is the bare form written a line low and still lifts;
-  nothing else is promoted into a matcher from below the heading. An option block's `pattern`
-  prevents that lift, and the advisory never echoes the discarded text.
+- §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
@@ -1938,15 +1957,6 @@ diagnostics are:
   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.
-- §misplaced-aside-advisory **Aside in the body.** A READ or FIND whose
-  body is solely an HTML comment (`<!-- … -->`) can never carry a matcher: it is
-  the aside the model put on the line below the heading. The builder takes
-  the comment as the aside when the heading has none, builds the operation
-  with no body, and raises one warning-severity advisory stating that observed
-  normalization; the parser places the advisory right after its statement and
-  the service delivers it as a `parse_advisory` notice with its position. A body
-  with any other content is ignored under the same advisory path
-  ({§matcher-body-redirect}).
 
 §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
@@ -1969,6 +1979,11 @@ 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`