@plurnk/plurnk-contracts 1.7.0 → 1.9.0

package/SPEC.md

@@ -10,10 +10,17 @@ is the single code API for those contracts.
 | ------------------------------------------------------------------------------- | --------------------------------------------------- |
 | Parser, AST, validators, Problems, results, Notices, text regions and extents   | `@plurnk/plurnk-contracts`                          |
 | Effective loop policy and its default                                           | `LoopFlags`, `DEFAULT_LOOP_FLAGS`                   |
+| Durable reasoning intent                                                        | `ReasoningPolicy`, `REASONING_POLICIES`             |
+| 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`                         |
-| Workspace MCP server attachment                                                | `McpServerDefinition`                               |
+| Exterior adapter application calls                                             | `ApplicationPort`                                   |
+| Workspace MCP configuration                                                    | `McpServerDefinition`, `McpServerOptions`, `McpConfigurationOverlay` |
+| Worker Agent Skills definition                                                 | `SkillDefinition` |
+| Worker outbound A2A agent definition                                           | `A2aAgentDefinition` |
+| Worker Functionality lifecycle projections (family-neutral)                     | `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`                                  |
 | Local-model rails                                                               | `@plurnk/plurnk-contracts/plurnk.{gemma,qwen}.gbnf` |
@@ -23,6 +30,45 @@ is the single code API for those contracts.
 generated from the schemas; ANTLR is authoritative for accepted model-language
 syntax; GBNF remains the bounded generation aid described in §1.2.
 
+§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.
+
+§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` is the one presentation serializer
 for generated JSON operation results. A top-level array remains one valid,
 compact JSON value but places each item on its own physical line by adding only
@@ -63,7 +109,7 @@ flowchart LR
 | 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, suffix matching, slot multiplicity, accepted
+ANTLR owns statement structure, delimiter 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.
@@ -81,7 +127,7 @@ The schemas own the runtime-neutral shapes; core owns their stateful values.
 | ------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
 | `LoopFlags`               | Complete effective `mode`, `auto`, `noWeb`, `noInteraction`, and `noProposals`  | Validate/expand persisted partial policy before use                                    |
 | `ProposalDisposition`     | Client authority, or the loop's exact automatic accept/reject                   | Compute precedence from effective loop policy, proposal kind, and stale-target truth   |
-| `ProposalProjection`      | Identity, review target/body/attrs, effective flags, stale signal, disposition  | Derive one validated projection for live delivery and durable reconnect discovery      |
+| `ProposalProjection`      | Identity, `{ scheme, authority, pathname }` review target, body/attrs, effective flags, stale signal, disposition | Derive one validated projection for live delivery and durable reconnect discovery |
 | `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                    |
@@ -89,6 +135,20 @@ The schemas own the runtime-neutral shapes; core owns their stateful values.
 
 `DEFAULT_LOOP_FLAGS` is the contracts-owned effective default value. A consumer may persist a partial object as an implementation detail, but it never exposes or acts on that partial representation as though it were the complete contract.
 
+§reasoning-policy-wire `ReasoningPolicy` is exactly `off | adaptive | low |
+medium | high`. The schema owns this shared wire vocabulary. Providers own the
+supported subset and native projection for a selected route; core owns the
+durable worker value.
+
+§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.
+
 ### §client-interaction-wire Client-owned interaction wire
 
 The closed client-interaction schemas describe one operation asking its client
@@ -203,14 +263,14 @@ response roots plus the parser/AstBuilder result.
 
 §rail-heading-boundaries On the GBNF rail, PLAN and every operation use lane `0`.
 Every reserved PLAN or operation heading stem is structural, regardless of the
-suffix a model attempts next, so a non-`0` pseudo-heading cannot be swallowed as
+delimiter a model attempts next, so a non-`0` pseudo-heading cannot be swallowed as
 literal body text. Rail bodies therefore cannot quote reserved headings from any
-lane. This makes both the canonical suffix and section boundary structurally
+lane. This makes both the canonical delimiter and section boundary structurally
 available during constrained generation; ANTLR remains the wider language and
 accepts intentional alternate-lane literals during ingestion.
 
 §gbnf-curation-shaping The rail admits OPEN/FOLD curation terms, a canonical
-`log:` target, and a matcher independently. It accepts any ordered mixture of
+`log:` target, an optional log-body line scope, and a matcher independently. It accepts any ordered mixture of
 unsigned, `+`, and `-` terms without proving that the combination selects a log
 item; ANTLR and AstBuilder own that condition, while runtime owns wider ingested
 target resolution.
@@ -218,32 +278,35 @@ target resolution.
 ## §canonical-statement 2. Canonical statement form
 
 ```text
-# PLANsuffix
+# PLANdelimiter
 body
 
-## OPsuffix [signal]? (path)? <scope>?
+## OPdelimiter [signal]? (path)? <scope>? <!-- annotation -->?
 body?
 ```
 
 §section-boundary A statement is one Markdown section. PLAN alone uses a level-one
 heading; every other operation uses a level-two heading. Its body is the
 character-perfect section content before the next structural heading or EOF.
-Canonical adjacent sections have one blank separator line. That final separator
-line is syntax and is not body content; any additional preceding blank lines
-remain body content. The tolerant ingester also admits a structural heading on
-the immediately following line.
+Canonical adjacent sections place the next structural heading on the immediately
+following line. The tolerant ingester also admits one empty separator line; that
+separator is syntax rather than body content, while any additional preceding
+blank lines remain body content.
 
-§empty-section An empty section has no body lines between its heading and the
-section separator (or EOF) and normalizes to a null body.
+§empty-section An empty section has no body lines between its heading and the next
+structural heading, tolerated separator, or EOF. Optional operation bodies normalize
+to null; PLAN admission normalizes its required semantic body to `[]`
+under {§plan-value}.
 
 | Element      | Canonical contract                                                        |
 |--------------|---------------------------------------------------------------------------|
 | `# PLAN`     | Required level-one turn anchor                                             |
 | `## OP`      | Level-two protocol operation                                               |
-| `suffix`     | Heading lane, joined directly to PLAN or OP                                |
+| `delimiter`     | Heading lane, joined directly to PLAN or OP                                |
 | `[signal]`   | Optional operation-specific signal, preceded by one space                  |
 | `(path)`     | Optional target slot, preceded by one space                                |
 | `<scope>`    | Optional numeric scope, preceded by one space                              |
+| `<!-- … -->` | Optional trailing operation annotation, preceded by one space               |
 | line ending  | Ends the single-line heading                                               |
 | `body`       | Zero or more characters of operation-specific, character-perfect content  |
 | blank line   | Canonical section separator; excluded from the preceding body              |
@@ -251,21 +314,31 @@ section separator (or EOF) and normalizes to a null body.
 The following constraints are structural:
 
 - §lane-match PLAN establishes one lane for the turn. A heading is structural
-  only when its suffix character-matches that lane; a different suffix remains
+  only when its delimiter character-matches that lane; a different delimiter remains
   ordinary body text.
 - PLAN is the only H1 operation and every non-PLAN operation is H2.
 - A header occupies one physical line.
 - Each admitted signal, target, and scope slot appears at most once.
-- OPEN, FOLD, BARE, WORK, FORK, and KILL do not admit a scope slot.
-- An ingested suffix is `[A-Za-z0-9_]*`; canonical teaching and the GBNF use `0`.
+- An annotation follows every present modifier and appears at most once.
+- BARE, WORK, FORK, and KILL do not admit a scope slot.
+- An ingested delimiter is `[A-Za-z0-9_]*`; canonical teaching and the GBNF use `0`.
 
 §slot-order Canonical producers and the GBNF rail emit signal, then target, then
-scope, with one ASCII space before every present slot. Slot delimiters make
+scope, then annotation, with one ASCII space before every present slot. Slot delimiters make
 their boundaries unambiguous, so the tolerant ANTLR ingester accepts zero or
 more horizontal whitespace characters before each slot and any permutation of
 the slots admitted by that operation, at most once each. Accepted spacing and
 permutation are not second canonical spellings.
 
+§operation-annotation A heading may end with one single-line Markdown HTML
+comment. AstBuilder strips the delimiters and surrounding horizontal whitespace
+into the statement's fixed `annotation: string | null` field. The annotation is
+durable, model- and client-facing descriptive text but semantically inert: it
+does not alter operation identity, signal, target, scope, dispatch, effect,
+authorization, status, or body. An empty comment normalizes to the empty string.
+Text containing a newline or lacking the closing `-->` is not an annotation;
+`<!--` elsewhere remains ordinary body text.
+
 The ingester also accepts several bounded noncanonical forms so it can explain
 or safely execute understandable input:
 
@@ -283,10 +356,11 @@ or safely execute understandable input:
 | Element     | Accepted shape or role                                             |
 |-------------|--------------------------------------------------------------------|
 | `OP`        | `FIND READ EDIT COPY MOVE OPEN FOLD SEND EXEC BARE WORK FORK KILL PLAN` |
-| `suffix`    | `[A-Za-z0-9_]*`, adjacent to PLAN or OP                            |
+| `delimiter`    | `[A-Za-z0-9_]*`, adjacent to PLAN or OP                            |
 | `[signal]`  | Operation-specific tags, identifier, branch, or integer            |
 | `(path)`    | Local path or scheme URL target; detailed in §5                    |
 | `<scope>`   | One or more signed integers or decimals; detailed in §7            |
+| annotation  | Optional trailing `<!-- … -->` descriptive text                    |
 | `body`      | Opaque section text before the next same-lane heading or EOF        |
 
 ## §op-shapes 4. Per-operation semantics
@@ -296,14 +370,14 @@ governed by {§canonical-statement}; runtime conditions remain explicit below.
 
 | OP   | `[signal]`                    | `(path)`                                     | `<scope>`                       | `body`                         |
 |------|-------------------------------|----------------------------------------------|---------------------------------|--------------------------------|
-| PLAN | none                          | none                                         | none                            | required intended goals        |
+| PLAN | none                          | none                                         | none                            | required Plurnk Plan JSON array |
 | FIND | optional add log tags         | required target or glob                      | optional result range           | optional matcher               |
 | READ | optional add log tags         | required target                              | optional text region            | empty                          |
 | EDIT | optional add log tags         | required file or entry                       | required for an existing target | literal text                   |
 | COPY | optional add log tags         | required source                              | optional source region          | required destination selection |
 | MOVE | optional add log tags         | required source                              | optional source region          | required destination selection |
-| FOLD | optional filter/change tags   | optional log selection                       | none                            | optional matcher               |
-| OPEN | optional filter/change tags   | optional log selection                       | none                            | optional matcher               |
+| FOLD | optional filter/change tags   | optional log selection                       | optional log-body line scope    | optional matcher               |
+| OPEN | optional filter/change tags   | optional log selection                       | optional log-body line scope    | optional matcher               |
 | EXEC | optional executor             | optional local working path                  | optional timeout, poll          | optional executor input        |
 | BARE | optional add log tags         | none                                         | none                            | required prompt                |
 | WORK | optional Git branch           | required fresh `worker://name`               | none                            | required prompt                |
@@ -317,10 +391,33 @@ Directed SEND and KILL delegate any present code to the addressed target's
 operation contract; a live process may interpret a KILL code as a Unix signal,
 but that interpretation does not define KILL generally.
 
-§plan-intended-goals **PLAN records working-state deltas.** Its concise body adds
-new material conclusions or unresolved questions and the current turn's priorities;
-it does not restate settled context. PLAN is public, durable log content—not provider
-reasoning. Dispatch records it and has no other runtime effect.
+§plan-value **PLAN carries one complete Plurnk Plan.** Its entries are the
+model's current working-memory inventory: durable findings are `memory`, finished
+actions are `completed`, open inquiries are `pending`, and active priorities are
+`in_progress`. Admission parses the JSON body — one JSON array document in any whitespace layout, including the {§json-result-rendering} spread the log projects — and supplies the neutral `medium`
+priority to each entry that omits it, and validates the canonical bare array:
+every entry has string `content`, `priority` in
+`high | medium | low`, and `status` in
+`pending | in_progress | completed | memory`. A nonempty plain-text,
+malformed-JSON, or otherwise invalid body becomes one `medium`, `in_progress`
+entry whose content is the exact authored body; admission performs no partial
+repair or list inference. An empty body becomes the planless `[]`
+value. Each PLAN completely replaces the current Plan; it never expresses a
+delta. The exact `turnOps` source remains forensic program evidence, while the
+normalized array is the sole semantic value used by AST, persistence, durable
+log bodies, and model-packet materialization. PLAN is public log content—not
+provider reasoning—and Plurnk initially mints no `_meta` values. Dispatch records
+the canonical value and has no other runtime effect.
+
+§plan-acp-projection **Only an ACP-facing boundary projects the model-native
+Plan.** It constructs ACP's `{ "entries": [...] }` Plan object from the internal
+array, maps each `memory` entry to ACP `completed`, and prefixes its content with
+exact "Memory: " framing without duplicating an existing prefix. Every other
+entry field remains unchanged, and the internal value is not mutated.
+The projected value validates against the separately owned ACP Plan schema pinned
+to ACP v1
+[`schema-v1.21.0`](https://github.com/agentclientprotocol/agent-client-protocol/tree/schema-v1.21.0)
+commit `272bf799f35a258c6a4107a0410ed361e83683d3`.
 
 §log-tag-signal FIND, READ, EDIT, COPY, MOVE, and BARE canonically express additions
 as `+tag`. Because those operations have no tag-selection semantics, ANTLR also
@@ -329,11 +426,13 @@ strips any `+`; the signal neither filters nor modifies resources. OPEN and
 FOLD treat every unsigned `tag` as an ALL-tags selector, then add each `+tag`
 and remove each `-tag` from the selected log items. Signed terms never select,
 so either a target, matcher, or unsigned tag is required. Adding and removing
-the same tag conflicts. Neither curation operation exposes a positional scope.
+the same tag conflicts. An optional OPEN/FOLD line scope changes visibility
+inside every selected canonical log body; it does not participate in row selection.
 
 The `<scope>` slot is optional where admitted and its domain is OP-specific. FIND
 scopes ordered results. EXEC and SEND scope timing. READ, EDIT, COPY, and
-MOVE use one universal text algebra independent of mimetype:
+MOVE use one universal text algebra independent of mimetype; OPEN/FOLD admit
+only its one- and two-line forms for canonical log-body visibility:
 
 | Arity         | Surface meaning                                                     | Endpoint rule                                        |
 |---------------|---------------------------------------------------------------------|------------------------------------------------------|
@@ -401,7 +500,7 @@ Mutation semantics:
 | 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                                                 |
-| PLAN | Status of durable intended-goals logging                                          |
+| PLAN | Status of durable complete-Plan logging                                           |
 
 §find-result-unit For FIND, authored target shape fixes the paginated result
 unit. An exact target with a matcher pages flat match locations; a glob or
@@ -548,6 +647,7 @@ The operation column names the canonical AST operation after
 | 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                      |
+| OPEN / FOLD           | 0/1/2 body-relative line coordinates   | Whole log body when absent; one physical line or inclusive range when present |
 | EXEC                  | `timeout[,poll]`                       | Spawn lifetime bound and poll cadence in seconds                           |
 | Terminal SEND `[202]` | `timeout[,poll]`                       | Bounded or indefinite wait and optional poll cadence                       |
 
@@ -556,13 +656,15 @@ 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. A leading decimal on semantic FIND
 is a similarity threshold; any remaining integers select result positions. READ
-does not admit decimal scope components.
+does not admit decimal scope components. OPEN/FOLD intersect 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.
 
 §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
-client LOOK preserve these positions in `TextLineMarker`; core resolves them
+`-1` remain numeric. Exact READ, EDIT, COPY/MOVE source and destination,
+OPEN/FOLD, and client LOOK preserve these positions in `TextLineMarker`; core resolves them
 against the addressed current text before operation-specific numeric scope
 semantics run. A matcher-bearing or path-glob READ normalizes to FIND, whose
 result positions remain numeric and reject anchors. Numeric text scopes remain
@@ -577,27 +679,27 @@ shapes for runtime validation. An anchor-bearing text scope uses commas; ANTLR
 tolerates one space after each comma.
 
 Apart from the unadvertised three-coordinate text-scope tolerance in
-{§text-scope-semantics}, the runtime rejects invalid arity, out-of-range or
+{§text-scope-semantics} and OPEN/FOLD's per-body empty intersection, the runtime rejects invalid arity, out-of-range or
 inverted positions, and decimal text coordinates rather than rounding or
 reinterpreting them. FIND owns a deterministic result order so the same
 inclusive range selects the same positions from unchanged state. The parser
 does not enforce either condition.
 
-## §suffix-discipline 8. Suffix Discipline
+## §delimiter-discipline 8. Delimiter Discipline
 
-The suffix is a turn-wide heading lane. A heading carrying the active lane
+The delimiter is a turn-wide heading lane. A heading carrying the active lane
 is structural; an otherwise valid PLURNK heading carrying another lane is body
 text. The lane therefore makes literal or nested PLURNK unambiguous.
 
-Suffix rules:
+Delimiter rules:
 
-- `suffix` is `[A-Za-z0-9_]*`, concatenated to PLAN or OP with no separator.
+- `delimiter` is `[A-Za-z0-9_]*`, concatenated to PLAN or OP with no separator.
 - The H1 PLAN establishes the lane; every real H2 operation heading in that
-  turn has the exact same suffix.
-- An empty suffix is accepted only by ANTLR ingestion. Canonical teaching and
+  turn has the exact same delimiter.
+- An empty delimiter is accepted only by ANTLR ingestion. Canonical teaching and
   the generated rail use `0` on PLAN and every operation.
-- A body may contain any heading whose suffix differs from the active lane.
-- To carry a nested turn written with lane `0`, choose another suffix for the
+- A body may contain any heading whose delimiter differs from the active lane.
+- To carry a nested turn written with lane `0`, choose another delimiter for the
   outer turn and repeat it on every outer heading.
 - The GBNF deliberately emits only lane `0`. It cannot emit body content that
   contains a same-lane structural heading; unconstrained producers use another
@@ -607,11 +709,11 @@ Example — a lane-0 turn stored inside a lane-2 EDIT body:
 
 ```plurnk
 # PLAN2
-Store the quoted turn.
+[{"content":"Store the quoted turn.","status":"in_progress"}]
 
 ## EDIT2 (worker:///quoted.plurnk)
 # PLAN0
-Answer from memory.
+[{"content":"Answer from memory.","status":"in_progress"}]
 
 ## SEND0 [200]
 Paris.
@@ -633,23 +735,22 @@ transfers directly:
 |-------|-----------------------------------------------------------------|-------------------------------|
 | `1xx` | Continue after submitted operations                             | `102 Processing`              |
 | `2xx` | Conclude successfully or wait on live obligations               | `200 OK`, `202 Accepted`      |
-| `3xx` | Ask the interactive user a stop-the-world multiple choice       | `300 Multiple Choices`        |
 | `4xx` | Abandon the loop after a model-side inability                   | `499`                         |
 | `5xx` | Runtime or infrastructure failure; never a model terminal claim | none                          |
 
 ### §waitpid-dispositions The terminal contract (waitpid)
 
 The model signals one intention per turn — **continue (102)**, **done
-(200)**, **wait (202)**, or **give up (499)**, plus the operator-facing
-**question (300)** — and the engine verifies the claim against the
-loop's live obligations (spawned children, open streams, pending
-retrievals); the grammar polices *shape* only. The shape rules ARE
-structural:
+(200)**, **wait (202)**, or **give up (499)** — and the engine verifies
+the claim against the loop's live obligations (spawned children, open
+streams, pending retrievals); the grammar polices *shape* only. Asking
+the human is the native `question` EXEC tool ({§question-tool}), not a
+disposition. The shape rules ARE structural:
 
-- §send-mid-reservation The five disposition codes `{102, 200, 202, 300, 499}` lex as a
+- §send-mid-reservation The four disposition codes `{102, 200, 202, 499}` lex as a
   distinct `DISPOSITION` token, making a disposition-coded SEND
   **structurally terminal**: a statement after it is a parse error
-  (the mid-termination rule), and the GBNF reserves the five from
+  (the mid-termination rule), and the GBNF reserves the four from
   mid-position SENDs (`status-mid` is their complement over `DDD`).
   This keeps the grammar's last-SEND model and the dispatcher's
   first-disposition model coincident.
@@ -700,6 +801,7 @@ stateDiagram-v2
     TARGET --> TARGET: balanced literals / target escapes
     TARGET --> SLOTS: target close at depth zero
     SLOTS --> SLOTS: scope token
+    SLOTS --> SLOTS: trailing annotation
     SLOTS --> BODY: heading line end
     BODY --> DEFAULT: same-lane heading boundary
     BODY --> [*]: end of input
@@ -707,13 +809,14 @@ stateDiagram-v2
 
 The first H1 PLAN establishes the turn lane. DEFAULT recognizes only an H1
 PLAN or H2 minted operation carrying that exact lane. SLOTS admits
-operation-appropriate signal, target, and scope openers in any order; the parser
-grammar enforces at-most-once multiplicity. Signal submodes select tags, integer,
+operation-appropriate signal, target, and scope openers in any order, followed
+by an optional annotation; the parser grammar enforces at-most-once multiplicity.
+Signal submodes select tags, integer,
 or identifier tokens by operation family. TARGET preserves balanced inner
 parentheses and recognized target escapes. BODY emits opaque text until a
 same-lane heading boundary or EOF.
 
-A differently suffixed heading stays BODY text. Multi-turn logs are plain
+A differently delimited heading stays BODY text. Multi-turn logs are plain
 sequences of independently lane-anchored PLAN turns. Complete native reasoning
 enclosures before PLAN remain one TEXT token so an operation drafted inside
 provider reasoning cannot become the turn anchor.
@@ -728,13 +831,15 @@ possible. EOF is a valid body boundary. An unfinished signal or target produces
 | Location                    | Canonical generation                  | Tolerant ANTLR ingestion                                  |
 |-----------------------------|---------------------------------------|-----------------------------------------------------------|
 | Heading marker              | `# PLAN0` or `## OP0` at column zero  | The initial PLAN may directly follow leading TEXT; subsequent headings retain exact depth and column |
-| Between OP and suffix       | Adjacent                              | Must remain adjacent                                      |
+| Between OP and delimiter       | Adjacent                              | Must remain adjacent                                      |
 | Before each header slot     | One ASCII space                       | Zero or more horizontal whitespace characters             |
 | Inside signal               | Adjacent values                       | Horizontal whitespace is ignored; newline is invalid      |
 | Inside target               | Path alias plus target escapes         | Balanced literals tolerated; newline is invalid           |
 | Inside scope                | Comma-separated numbers               | Dash separator and one post-comma space are also accepted |
+| Before annotation           | One ASCII space                        | Zero or more horizontal whitespace characters             |
+| Inside annotation           | One-line prose padded by one space     | Any single-line text through the first closing `-->`       |
 | Inside body                 | Character-perfect                     | Character-perfect                                         |
-| Between canonical sections  | One empty separator line              | A directly following structural heading is also admitted  |
+| Between canonical sections  | No empty separator line                | One empty separator line is also admitted                  |
 | Before the first PLAN       | Nothing                               | Whitespace or TEXT may surface as preamble items without requiring a separator before PLAN |
 
 PLURNK never escape-decodes body text: `\n` reaches the owning operation as
@@ -746,7 +851,8 @@ content emit an actual newline.
 break, and returns it as ordered text items without assigning semantics. Once
 a heading begins, all nonstructural text belongs to that section body.
 `parseStatements` and `parseClient` admit H2 statements;
-`parseLog` admits consecutive H1 PLAN turns. PLURNK defines no comment syntax.
+`parseLog` admits consecutive H1 PLAN turns. PLURNK defines no general comment
+syntax; only the trailing heading position gives `<!-- … -->` annotation meaning.
 
 ## §public-api 12. Public API
 
@@ -867,7 +973,7 @@ enforces both the schema and the relational endpoint invariants.
 ### §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 scheme/pathname fields,
+does not expose workspace IDs, storage owner IDs, split persistence-coordinate fields,
 scope, or other persistence columns.
 
 | Outcome | Exact shape                                                      |
@@ -967,19 +1073,77 @@ model-language syntax or model packet teaching.
 
 ### §mcp-server-definition 13.8 MCP server definitions
 
-`McpServerDefinition` is the transport-neutral, client/daemon-shared definition
-of one workspace MCP server. It is a closed `stdio`/`http` union. The schema
+`McpServerDefinition` is the transport-neutral normalized definition of one
+workspace MCP server. It is a closed `stdio`/`http` union. The schema
 owns transport-specific fields, enabled/read tool sets, supported HTTP
 authorization choices, and symbolic credential references; it carries no
 workspace identifier, connection state, discovered catalog, or secret value.
-`Validator.assertMcpServerDefinition` is the admission boundary used by every
-client interface and the MCP host before persistence or connection work.
+`Validator.assertMcpServerDefinition` is the MCP host's admission boundary
+before persistence or connection work.
+
+§mcp-server-options `McpServerOptions` is the closed client/daemon-shared
+supplement accepted when adding an MCP server by alias and target. It reuses
+only `McpServerDefinition` option fields and cannot repeat identity, target, or
+transport. The target determines the transport; normalization through
+`McpServerDefinition` rejects options belonging to the other transport.
 
 Interactive OAuth always requires a callback URL. Its structurally exclusive
 identity modes are an HTTPS Client ID Metadata Document URL, a pre-registered
 client ID plus symbolic secret, or neither for server-advertised Dynamic Client
 Registration fallback. A definition cannot combine those identity modes.
 
+§mcp-configuration-overlay `McpConfigurationOverlay` is the bounded raw
+configuration projection a client may carry to MCP list and enable actions. It
+contains only string-valued `PLURNK_MCP_*` server declaration variables;
+service-owned connection/request timeouts and default enabledness are excluded.
+The client does not interpret this map. The MCP host composes it over the
+lower normalized definition through the same parser that admits service
+environment declarations, then validates the resulting
+`McpServerDefinition`. Carrying the overlay does not connect, persist, or
+expand credentials by itself.
+
+`SkillDefinition` is the one definition the Worker `skills` Functionality
+family accepts and persists: the standard Agent Skills `name` (the directory
+name), the universal root `scope` (`project` or `global`), and — for a
+Worker-installed skill — the standard installer package `source` that
+provides it. `Validator.assertSkillDefinition` is the family's admission
+boundary; the filesystem under the scope's root, never the definition, is the
+truth about installation.
+
+`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. 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.
+
+`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.
+
+§application-worker-observation Worker observation exposes durable identity,
+origin, and immediate parent identity. `readWorker` resolves exactly one id or
+name and returns `null` when absent. `listWorkers` filters collections by origin
+or lineage position; an omitted parent filter means every position and an
+explicit `null` means roots. Singular and plural cardinalities are distinct
+contracts. Observation is not a client binding or permission grant.
+
+§application-loop-observation Loop observation exposes the durable scheduler
+state and exact terminal `OperationResult` for one owned Worker. Exterior
+adapters consume this projection instead of reconstructing lifecycle from
+events or persistence; events remain the live notification edge.
+
 ## 14. Parse diagnostics
 
 §parse-diagnostics `PlurnkParseError` is a JSON-serializable Error subclass.