@plurnk/plurnk-contracts 1.6.1 → 1.8.0

package/SPEC.md

@@ -10,8 +10,12 @@ 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 configuration                                                    | `McpServerDefinition`, `McpServerOptions`, `McpConfigurationOverlay` |
 | JSON Schemas                                                                    | `@plurnk/plurnk-contracts/schema/*.json`            |
 | Generated JSON result rendering                                                 | `renderJsonResult`                                  |
 | Local-model rails                                                               | `@plurnk/plurnk-contracts/plurnk.{gemma,qwen}.gbnf` |
@@ -61,7 +65,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.
@@ -87,6 +91,35 @@ 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
+for structured input without transferring private protocol continuation state.
+
+| 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
@@ -186,14 +219,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.
@@ -201,32 +234,33 @@ 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 and normalizes to a null body.
 
 | 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              |
@@ -234,21 +268,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:
 
@@ -266,10 +310,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
@@ -285,8 +330,8 @@ governed by {§canonical-statement}; runtime conditions remain explicit below.
 | 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                |
@@ -312,11 +357,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                                        |
 |---------------|---------------------------------------------------------------------|------------------------------------------------------|
@@ -531,6 +578,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                       |
 
@@ -539,13 +587,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
@@ -560,27 +610,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
@@ -616,23 +666,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.
@@ -683,6 +732,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
@@ -690,13 +740,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.
@@ -711,13 +762,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
@@ -729,7 +782,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
 
@@ -948,6 +1002,37 @@ 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 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 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.
+
 ## 14. Parse diagnostics
 
 §parse-diagnostics `PlurnkParseError` is a JSON-serializable Error subclass.

package/dist/plurnk.gemma.gbnf

@@ -45,29 +45,32 @@ section-body-b40 ::= ("#" section-body-b1 | [ PLANFDRETCOYMVSXBWK] section-body-
 section-body-b41 ::= ("#" section-body-b1 | [ PANFIDRETCOYMVSXBWK] section-body-b0 | "L" section-body-b42 | [^\x00-\x08\x0B-\x0C\x0E-\x1F\x7F# PLANFIDRETCOYMVSXBWK] section-body-b0)?
 section-body-b42 ::= ("#" section-body-b1 | [ PANFIDRETCOYMVSXBWK] section-body-b0 | [^\x00-\x08\x0B-\x0C\x0E-\x1F\x7F# PLANFIDRETCOYMVSXBWK] section-body-b0)?
 section-body-ne ::= "#" section-body-b1 | [ PLANFIDRETCOYMVSXBWK] section-body-b0 | [^\x00-\x08\x0B-\x0C\x0E-\x1F\x7F# PLANFIDRETCOYMVSXBWK] section-body-b0
+annotation-body-b0 ::= ("-" annotation-body-b1 | ">" annotation-body-b0 | [^\x00-\x08\x0B-\x0C\x0E-\x1F\x7F\n\r>-] annotation-body-b0)?
+annotation-body-b1 ::= ("-" annotation-body-b2 | ">" annotation-body-b0 | [^\x00-\x08\x0B-\x0C\x0E-\x1F\x7F\n\r>-] annotation-body-b0)?
+annotation-body-b2 ::= ("-" annotation-body-b2 | [^\x00-\x08\x0B-\x0C\x0E-\x1F\x7F\n\r>-] annotation-body-b0)?
+annotation-body-ne ::= "-" annotation-body-b1 | ">" annotation-body-b0 | [^\x00-\x08\x0B-\x0C\x0E-\x1F\x7F\n\r>-] annotation-body-b0
 pattern-body-ne ::= [^\x00-\x08\x0B-\x0C\x0E-\x1F\x7F\n\r:#] [^\x00-\x08\x0B-\x0C\x0E-\x1F\x7F\n\r]*
 log-selection ::= (curation-tags-slot log-target-slot? | log-target-slot)?
-plan ::= "# PLAN0" "\n" section-body-ne "\n\n"
-find ::= "## FIND0" add-tags-slot? target-slot line-slot? "\n\n" | "## FIND0" add-tags-slot? target-slot line-slot? "\n" pattern-body-ne "\n\n"
-read ::= "## READ0" add-tags-slot? target-slot text-line-slot? "\n\n" | "## READ0" add-tags-slot? target-slot text-line-slot? "\n" pattern-body-ne "\n\n"
-edit ::= "## EDIT0" add-tags-slot? target-slot text-line-slot? "\n\n" | "## EDIT0" add-tags-slot? target-slot text-line-slot? "\n" section-body-ne "\n\n"
-copy ::= "## COPY0" add-tags-slot? target-slot text-line-slot? "\n" section-body-ne "\n\n"
-move ::= "## MOVE0" add-tags-slot? target-slot text-line-slot? "\n" section-body-ne "\n\n"
-open ::= "## OPEN0" log-selection "\n\n" | "## OPEN0" log-selection "\n" pattern-body-ne "\n\n"
-fold ::= "## FOLD0" log-selection "\n\n" | "## FOLD0" log-selection "\n" pattern-body-ne "\n\n"
-exec ::= "## EXEC0" exec-slot? target-slot? line-slot? "\n\n" | "## EXEC0" exec-slot? target-slot? line-slot? "\n" section-body-ne "\n\n"
-bare ::= "## BARE0" add-tags-slot? "\n" section-body-ne "\n\n"
-work ::= "## WORK0" branch-slot? target-slot "\n" section-body-ne "\n\n"
-fork ::= "## FORK0" branch-slot? target-slot "\n" section-body-ne "\n\n"
-kill ::= "## KILL0" kill-slot? target-slot "\n\n"
-send-mid ::= "## SEND0" status-mid-slot target-slot? "\n\n" | "## SEND0" status-mid-slot target-slot? "\n" section-body-ne "\n\n" | "## SEND0" target-slot? "\n\n" | "## SEND0" target-slot? "\n" section-body-ne "\n\n"
-send-102 ::= "## SEND0 [102]" target-slot? "\n" section-body-ne
-send-200 ::= "## SEND0 [200]" target-slot? "\n" section-body-ne
-send-202 ::= "## SEND0 [202]" target-slot? park-slot? "\n" section-body-ne
-send-300 ::= "## SEND0 [300]" target-slot? "\n" section-body-ne
-send-499 ::= "## SEND0 [499]" target-slot? "\n" section-body-ne
-send-final-any ::= send-102 | send-200 | send-202 | send-300 | send-499
-send-final-first ::= send-200 | send-202 | send-300 | send-499
+plan ::= "# PLAN0" annotation-slot? "\n" section-body-ne "\n"
+find ::= "## FIND0" add-tags-slot? target-slot line-slot? annotation-slot? "\n" | "## FIND0" add-tags-slot? target-slot line-slot? annotation-slot? "\n" pattern-body-ne "\n"
+read ::= "## READ0" add-tags-slot? target-slot text-line-slot? annotation-slot? "\n" | "## READ0" add-tags-slot? target-slot text-line-slot? annotation-slot? "\n" pattern-body-ne "\n"
+edit ::= "## EDIT0" add-tags-slot? target-slot text-line-slot? annotation-slot? "\n" | "## EDIT0" add-tags-slot? target-slot text-line-slot? annotation-slot? "\n" section-body-ne "\n"
+copy ::= "## COPY0" add-tags-slot? target-slot text-line-slot? annotation-slot? "\n" section-body-ne "\n"
+move ::= "## MOVE0" add-tags-slot? target-slot text-line-slot? annotation-slot? "\n" section-body-ne "\n"
+open ::= "## OPEN0" log-selection text-line-slot? annotation-slot? "\n" | "## OPEN0" log-selection text-line-slot? annotation-slot? "\n" pattern-body-ne "\n"
+fold ::= "## FOLD0" log-selection text-line-slot? annotation-slot? "\n" | "## FOLD0" log-selection text-line-slot? annotation-slot? "\n" pattern-body-ne "\n"
+exec ::= "## EXEC0" exec-slot? target-slot? line-slot? annotation-slot? "\n" | "## EXEC0" exec-slot? target-slot? line-slot? annotation-slot? "\n" section-body-ne "\n"
+bare ::= "## BARE0" add-tags-slot? annotation-slot? "\n" section-body-ne "\n"
+work ::= "## WORK0" branch-slot? target-slot annotation-slot? "\n" section-body-ne "\n"
+fork ::= "## FORK0" branch-slot? target-slot annotation-slot? "\n" section-body-ne "\n"
+kill ::= "## KILL0" kill-slot? target-slot annotation-slot? "\n"
+send-mid ::= "## SEND0" status-mid-slot target-slot? annotation-slot? "\n" | "## SEND0" status-mid-slot target-slot? annotation-slot? "\n" section-body-ne "\n" | "## SEND0" target-slot? annotation-slot? "\n" | "## SEND0" target-slot? annotation-slot? "\n" section-body-ne "\n"
+send-102 ::= "## SEND0 [102]" target-slot? annotation-slot? "\n" section-body-ne
+send-200 ::= "## SEND0 [200]" target-slot? annotation-slot? "\n" section-body-ne
+send-202 ::= "## SEND0 [202]" target-slot? park-slot? annotation-slot? "\n" section-body-ne
+send-499 ::= "## SEND0 [499]" target-slot? annotation-slot? "\n" section-body-ne
+send-final-any ::= send-102 | send-200 | send-202 | send-499
+send-final-first ::= send-200 | send-202 | send-499
 op-statement ::= find | read | edit | copy | move | open | fold | exec | bare | work | fork | kill
 tail-0 ::= send-mid tail-1 | op-statement tail-1 | send-final-first
 tail-1 ::= send-mid tail-2 | op-statement tail-2 | send-final-any
@@ -126,10 +129,11 @@ branch-slot ::= " " branch
 kill-slot ::= " " kill-sig
 status-mid-slot ::= " [" status-mid "]"
 park-slot ::= " " park
+annotation-slot ::= " <!-- " annotation-body-ne " -->"
 status-mid ::= [05-9] [0-9] [0-9] | "1" status-mid-1 | "2" status-mid-2 | "3" status-mid-3 | "4" status-mid-4
 status-mid-1 ::= "0" [0-13-9] | [1-9] [0-9]
 status-mid-2 ::= "0" [13-9] | [1-9] [0-9]
-status-mid-3 ::= "0" [1-9] | [1-9] [0-9]
+status-mid-3 ::= "0" [0-9] | [1-9] [0-9]
 status-mid-4 ::= "9" [0-8] | [0-8] [0-9]
 add-tags ::= "[" add-tag add-tag-rest* "]"
 curation-tags ::= "[" curation-term curation-term-rest* "]"

package/dist/plurnk.qwen.gbnf

@@ -45,29 +45,32 @@ section-body-b40 ::= ("#" section-body-b1 | [ PLANFDRETCOYMVSXBWK] section-body-
 section-body-b41 ::= ("#" section-body-b1 | [ PANFIDRETCOYMVSXBWK] section-body-b0 | "L" section-body-b42 | [^\x00-\x08\x0B-\x0C\x0E-\x1F\x7F# PLANFIDRETCOYMVSXBWK] section-body-b0)?
 section-body-b42 ::= ("#" section-body-b1 | [ PANFIDRETCOYMVSXBWK] section-body-b0 | [^\x00-\x08\x0B-\x0C\x0E-\x1F\x7F# PLANFIDRETCOYMVSXBWK] section-body-b0)?
 section-body-ne ::= "#" section-body-b1 | [ PLANFIDRETCOYMVSXBWK] section-body-b0 | [^\x00-\x08\x0B-\x0C\x0E-\x1F\x7F# PLANFIDRETCOYMVSXBWK] section-body-b0
+annotation-body-b0 ::= ("-" annotation-body-b1 | ">" annotation-body-b0 | [^\x00-\x08\x0B-\x0C\x0E-\x1F\x7F\n\r>-] annotation-body-b0)?
+annotation-body-b1 ::= ("-" annotation-body-b2 | ">" annotation-body-b0 | [^\x00-\x08\x0B-\x0C\x0E-\x1F\x7F\n\r>-] annotation-body-b0)?
+annotation-body-b2 ::= ("-" annotation-body-b2 | [^\x00-\x08\x0B-\x0C\x0E-\x1F\x7F\n\r>-] annotation-body-b0)?
+annotation-body-ne ::= "-" annotation-body-b1 | ">" annotation-body-b0 | [^\x00-\x08\x0B-\x0C\x0E-\x1F\x7F\n\r>-] annotation-body-b0
 pattern-body-ne ::= [^\x00-\x08\x0B-\x0C\x0E-\x1F\x7F\n\r:#] [^\x00-\x08\x0B-\x0C\x0E-\x1F\x7F\n\r]*
 log-selection ::= (curation-tags-slot log-target-slot? | log-target-slot)?
-plan ::= "# PLAN0" "\n" section-body-ne "\n\n"
-find ::= "## FIND0" add-tags-slot? target-slot line-slot? "\n\n" | "## FIND0" add-tags-slot? target-slot line-slot? "\n" pattern-body-ne "\n\n"
-read ::= "## READ0" add-tags-slot? target-slot text-line-slot? "\n\n" | "## READ0" add-tags-slot? target-slot text-line-slot? "\n" pattern-body-ne "\n\n"
-edit ::= "## EDIT0" add-tags-slot? target-slot text-line-slot? "\n\n" | "## EDIT0" add-tags-slot? target-slot text-line-slot? "\n" section-body-ne "\n\n"
-copy ::= "## COPY0" add-tags-slot? target-slot text-line-slot? "\n" section-body-ne "\n\n"
-move ::= "## MOVE0" add-tags-slot? target-slot text-line-slot? "\n" section-body-ne "\n\n"
-open ::= "## OPEN0" log-selection "\n\n" | "## OPEN0" log-selection "\n" pattern-body-ne "\n\n"
-fold ::= "## FOLD0" log-selection "\n\n" | "## FOLD0" log-selection "\n" pattern-body-ne "\n\n"
-exec ::= "## EXEC0" exec-slot? target-slot? line-slot? "\n\n" | "## EXEC0" exec-slot? target-slot? line-slot? "\n" section-body-ne "\n\n"
-bare ::= "## BARE0" add-tags-slot? "\n" section-body-ne "\n\n"
-work ::= "## WORK0" branch-slot? target-slot "\n" section-body-ne "\n\n"
-fork ::= "## FORK0" branch-slot? target-slot "\n" section-body-ne "\n\n"
-kill ::= "## KILL0" kill-slot? target-slot "\n\n"
-send-mid ::= "## SEND0" status-mid-slot target-slot? "\n\n" | "## SEND0" status-mid-slot target-slot? "\n" section-body-ne "\n\n" | "## SEND0" target-slot? "\n\n" | "## SEND0" target-slot? "\n" section-body-ne "\n\n"
-send-102 ::= "## SEND0 [102]" target-slot? "\n" section-body-ne
-send-200 ::= "## SEND0 [200]" target-slot? "\n" section-body-ne
-send-202 ::= "## SEND0 [202]" target-slot? park-slot? "\n" section-body-ne
-send-300 ::= "## SEND0 [300]" target-slot? "\n" section-body-ne
-send-499 ::= "## SEND0 [499]" target-slot? "\n" section-body-ne
-send-final-any ::= send-102 | send-200 | send-202 | send-300 | send-499
-send-final-first ::= send-200 | send-202 | send-300 | send-499
+plan ::= "# PLAN0" annotation-slot? "\n" section-body-ne "\n"
+find ::= "## FIND0" add-tags-slot? target-slot line-slot? annotation-slot? "\n" | "## FIND0" add-tags-slot? target-slot line-slot? annotation-slot? "\n" pattern-body-ne "\n"
+read ::= "## READ0" add-tags-slot? target-slot text-line-slot? annotation-slot? "\n" | "## READ0" add-tags-slot? target-slot text-line-slot? annotation-slot? "\n" pattern-body-ne "\n"
+edit ::= "## EDIT0" add-tags-slot? target-slot text-line-slot? annotation-slot? "\n" | "## EDIT0" add-tags-slot? target-slot text-line-slot? annotation-slot? "\n" section-body-ne "\n"
+copy ::= "## COPY0" add-tags-slot? target-slot text-line-slot? annotation-slot? "\n" section-body-ne "\n"
+move ::= "## MOVE0" add-tags-slot? target-slot text-line-slot? annotation-slot? "\n" section-body-ne "\n"
+open ::= "## OPEN0" log-selection text-line-slot? annotation-slot? "\n" | "## OPEN0" log-selection text-line-slot? annotation-slot? "\n" pattern-body-ne "\n"
+fold ::= "## FOLD0" log-selection text-line-slot? annotation-slot? "\n" | "## FOLD0" log-selection text-line-slot? annotation-slot? "\n" pattern-body-ne "\n"
+exec ::= "## EXEC0" exec-slot? target-slot? line-slot? annotation-slot? "\n" | "## EXEC0" exec-slot? target-slot? line-slot? annotation-slot? "\n" section-body-ne "\n"
+bare ::= "## BARE0" add-tags-slot? annotation-slot? "\n" section-body-ne "\n"
+work ::= "## WORK0" branch-slot? target-slot annotation-slot? "\n" section-body-ne "\n"
+fork ::= "## FORK0" branch-slot? target-slot annotation-slot? "\n" section-body-ne "\n"
+kill ::= "## KILL0" kill-slot? target-slot annotation-slot? "\n"
+send-mid ::= "## SEND0" status-mid-slot target-slot? annotation-slot? "\n" | "## SEND0" status-mid-slot target-slot? annotation-slot? "\n" section-body-ne "\n" | "## SEND0" target-slot? annotation-slot? "\n" | "## SEND0" target-slot? annotation-slot? "\n" section-body-ne "\n"
+send-102 ::= "## SEND0 [102]" target-slot? annotation-slot? "\n" section-body-ne
+send-200 ::= "## SEND0 [200]" target-slot? annotation-slot? "\n" section-body-ne
+send-202 ::= "## SEND0 [202]" target-slot? park-slot? annotation-slot? "\n" section-body-ne
+send-499 ::= "## SEND0 [499]" target-slot? annotation-slot? "\n" section-body-ne
+send-final-any ::= send-102 | send-200 | send-202 | send-499
+send-final-first ::= send-200 | send-202 | send-499
 op-statement ::= find | read | edit | copy | move | open | fold | exec | bare | work | fork | kill
 tail-0 ::= send-mid tail-1 | op-statement tail-1 | send-final-first
 tail-1 ::= send-mid tail-2 | op-statement tail-2 | send-final-any
@@ -115,10 +118,11 @@ branch-slot ::= " " branch
 kill-slot ::= " " kill-sig
 status-mid-slot ::= " [" status-mid "]"
 park-slot ::= " " park
+annotation-slot ::= " <!-- " annotation-body-ne " -->"
 status-mid ::= [05-9] [0-9] [0-9] | "1" status-mid-1 | "2" status-mid-2 | "3" status-mid-3 | "4" status-mid-4
 status-mid-1 ::= "0" [0-13-9] | [1-9] [0-9]
 status-mid-2 ::= "0" [13-9] | [1-9] [0-9]
-status-mid-3 ::= "0" [1-9] | [1-9] [0-9]
+status-mid-3 ::= "0" [0-9] | [1-9] [0-9]
 status-mid-4 ::= "9" [0-8] | [0-8] [0-9]
 add-tags ::= "[" add-tag add-tag-rest* "]"
 curation-tags ::= "[" curation-term curation-term-rest* "]"

package/dist/schema/ClientInteractionProjection.json

@@ -0,0 +1,16 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/ClientInteractionProjection.json",
+    "title": "ClientInteractionProjection",
+    "description": "The runtime-neutral client-interface projection of one pending client interaction. Live delivery and reconnect discovery expose this same shape.",
+    "type": "object",
+    "required": ["interactionId", "workerId", "loopId", "turnId", "request"],
+    "additionalProperties": false,
+    "properties": {
+        "interactionId": { "type": "integer", "minimum": 1 },
+        "workerId": { "type": "integer", "minimum": 1 },
+        "loopId": { "type": "integer", "minimum": 1 },
+        "turnId": { "type": "integer", "minimum": 1 },
+        "request": { "$ref": "https://schemas.plurnk.dev/v0/ClientInteractionRequest.json" }
+    }
+}

package/dist/schema/ClientInteractionRequest.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/ClientInteractionRequest.json",
+    "title": "ClientInteractionRequest",
+    "description": "A runtime-neutral request for one client-owned interaction. The owner supplies the standard tool presentation and response contract; protocol-private continuation state is excluded.",
+    "type": "object",
+    "required": ["toolName", "arguments", "responseSchema"],
+    "additionalProperties": false,
+    "properties": {
+        "toolName": { "type": "string", "minLength": 1 },
+        "arguments": { "type": "object", "additionalProperties": true },
+        "message": { "type": "string", "minLength": 1 },
+        "responseSchema": { "type": "object", "additionalProperties": true }
+    }
+}

package/dist/schema/ClientInteractionResolution.json

@@ -0,0 +1,25 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/ClientInteractionResolution.json",
+    "title": "ClientInteractionResolution",
+    "description": "The client response that settles one pending interaction. A cancelled interaction carries no fabricated payload.",
+    "oneOf": [
+        {
+            "type": "object",
+            "required": ["status"],
+            "additionalProperties": false,
+            "properties": {
+                "status": { "const": "resolved" },
+                "payload": true
+            }
+        },
+        {
+            "type": "object",
+            "required": ["status"],
+            "additionalProperties": false,
+            "properties": {
+                "status": { "const": "cancelled" }
+            }
+        }
+    ]
+}