@ggui-ai/protocol-conformance 0.25.0 → 0.27.0

package/README.md

@@ -1,6 +1,6 @@
 # @ggui-ai/protocol-conformance
 
-Conformance test kit for the ggui protocol. Ships JSON case catalogs + runners that drive them against a live implementation — the behavioral fixtures over WebSocket, the `resources/read` cases over the MCP binding — and report scorecard-style pass / fail / skip output.
+Conformance test kit for the GGUI protocol. Ships JSON case catalogs + runners that drive them against a live implementation — the behavioral fixtures over WebSocket, the `resources/read` cases over the MCP binding — and report scorecard-style pass / fail / skip output.
 
 This kit is the protocol's conformance surface: it lets a third-party MCP builder prove their implementation is protocol-conformant without reimplementing the test harness.
 
@@ -13,11 +13,13 @@ The kit grades protocol obligations through **four mechanisms**, each matched to
 3. **Session-state host read-back** — stateful obligations with no wire response (e.g. `host_context_observed` persisting onto `GguiSession.hostContext`): the runner dispatches the C→S frame, waits out the observation window, then reads the GguiSession field back through `ConformanceHost.readSessionField()` and deep-equals it against the fixture's `expected`. No host (or a host without the method, or a read that throws) → the fixture SKIPS with the reason — a host that cannot read state cannot grade it, and the kit never converts that gap into a pass.
 4. **MCP-binding scenario driver** — request/response obligations on the MCP surface, where the deployment shape is part of what is under test. The `resources/read` catalog is the first: a case declares a server shape, a caller identity and a seed set, the adopter's driver brings a server up that way, and the kit reads locators against it and grades the raw JSON-RPC frames. A driver that cannot express a scenario throws, and the case SKIPS — never passes.
 
+**Obligation strength.** A fixture grades a MUST unless it declares `"level": "should"`. An unmet MUST is a failure. An unmet SHOULD is a **warning**: it lands in `result.warned` with the same evidence a failure carries, is printed as `WARN`, and never fails a run. A skip stays a skip at either level.
+
 A fifth surface — the **Path-B browser-host driver** for DOM-level claims (`bootstrap-failure`, `props-update`) — is honestly absent: it is not yet packaged, and those fixtures skip wherever the kit runs (see below).
 
 ## Transport
 
-**The behavioral fixture catalog is WebSocket-only.** The canonical ggui live-channel transport is WS (see SPEC §12 Transport Bindings). `TransportConfig` is shaped as an extensibly-closed union so later live-channel transports (HTTP long-poll) can be added without breaking the public API.
+**The behavioral fixture catalog is WebSocket-only.** The canonical GGUI live-channel transport is WS (see SPEC §12 Transport Bindings). `TransportConfig` is shaped as an extensibly-closed union so later live-channel transports (HTTP long-poll) can be added without breaking the public API.
 
 The MCP surface is graded separately, by catalog rather than by transport config — see `resource-read-conformance` below. Its cases are deliberately NOT registered in `fixturesByContract`: everything in that map is driven over a WebSocket, so an MCP case there would be a permanent skip on every WS run, which is the false gate the kit's exact skip-set pinning exists to prevent. `resources/read` and — since ggui#880 — one `tools/call` catalog (`domain-error`, SPEC §7.9 Plane 2) are the MCP methods bound today.
 
@@ -58,12 +60,12 @@ Each catalog ships its cases as raw JSON so a non-TypeScript implementer can gra
 - **`@ggui-ai/protocol-conformance/resolution-conformance`** — which bundle + style URLs the server MUST compute for a gadget descriptor's transport fields (`bundleHost` precedence, default host, loopback `http` scheme).
 - **`@ggui-ai/protocol-conformance/binding-conformance`** — which MCP tool-binding set a manifest resolves to (a declared `mcpTools` list wins entirely; blueprints without it derive bare tool-name entries from contract tool names) and which artifacts the registry `tool=` / `server=` search filters MUST match (SPEC §7.7.4.1).
 - **`@ggui-ai/protocol-conformance/props-schema-conformance`** — the schema-precise render arbiter (SPEC §2.3.2): the enforced-props-schema builder (drift), its RFC 8785 sha256 hash, the grammar-safe profile verdict, and returned-schema AUTHORITY (sample validity under the case's own `propsSchema`, including the 2026-08-19 out-of-vocabulary enum incident pinned as a permanent sample).
-- **`@ggui-ai/protocol-conformance/host-helper-conformance`** — grades a HOST-HELPER library (what mounts a ggui view and answers the MCP Apps bridge) through a JSON-RPC port the implementer supplies: a well-formed `ui/initialize` (H1), truthful capability advertisement (H2: an advertised `serverTools` answers `tools/call`, an advertised `serverResources` answers `resources/read`), honest and bounded refusals (H3/H4), and an unmodified `tools/call` relay (R1/R2), plus optional chrome (C1), theme-coverage (T1) and model-tool-set (M1 — the host's own visibility filter graded against `toolVisibleToModel`: withhold the app-only `ggui_runtime_*` tools, keep every model-visible one; ggui#1414) grades. The scorecard names a tier: `relaying`, `read-only` (a legal grade), or `nonconforming`. Runner: `runHostHelperConformance(port)`.
+- **`@ggui-ai/protocol-conformance/host-helper-conformance`** — grades a HOST-HELPER library (what mounts a GGUI view and answers the MCP Apps bridge) through a JSON-RPC port the implementer supplies: a well-formed `ui/initialize` (H1), truthful capability advertisement (H2: an advertised `serverTools` answers `tools/call`, an advertised `serverResources` answers `resources/read`), honest and bounded refusals (H3/H4), and an unmodified `tools/call` relay (R1/R2), plus optional chrome (C1), theme-coverage (T1) and model-tool-set (M1 — the host's own visibility filter graded against `toolVisibleToModel`: withhold the app-only `ggui_runtime_*` tools, keep every model-visible one; ggui#1414), view-material (V1 — the host's own model-context rules, fed a render result and a render read body whose slice is marked in every value: none may reach the model, raw, percent-encoded or base64-encoded, while the result's own marker must, and no `ui://ggui/render` read may be offered to the model; ggui#1415) and view-binding (L1 — the host's own relay decision: a view's own reads, in every locator form, and every session-naming call a view may make relay, another session's refuse; ggui#1415) grades. M1, V1 and L1 grade the host's rule against fixtures, not a running host: they are self-certified. The scorecard names a tier: `relaying`, `read-only` (a legal grade), or `nonconforming`. Runner: `runHostHelperConformance(port)`.
 - **`@ggui-ai/protocol-conformance/refusal-envelope-conformance`** — the tool result a server MUST project for a PRE-GENERATION refusal (SPEC §7.1's refused arm): an in-result `isError` (never a throw), `content[0].text` leading with the code, `structuredContent` carrying `{outcome: 'refused', refusal}` and nothing else, no `_meta` — and no envelope at all for a registered code whose surfaces exclude the render gate.
 - **`@ggui-ai/protocol-conformance/registry-completeness`** — the structural obligations a deployment's closed refusal-code registry MUST satisfy: `surfaces` non-empty, `code === key`, every `after-fix` entry naming who acts (`fixBy`), and `retry` inside the closed four-value set. Grades DATA rather than a function — the caller passes their registry.
 - **`@ggui-ai/protocol-conformance/transport-refusal-conformance`** — the JSON-RPC error a per-app MCP endpoint MUST answer with when it refuses a request for a typed reason (SPEC §7.1's endpoint-level refusal, ggui#825): HTTP 403 with `{ code: -32003, message: 'App not found', data: { refusal } }`, where `refusal` is the registry projection without the render-only fields (`code`, `message`, `fix`, `retry`) — and no envelope at all for a registered code whose surfaces exclude `mcp-endpoint` (an untyped authorization failure answers 403 with `-32007` and no `data`, by contract — ggui#836). Runner: `runTransportRefusalConformance(project)`; folded into `runConformance()` via `transportRefusalProjector`.
 - **`@ggui-ai/protocol-conformance/theme-binding-conformance`** — the theme-binding total order (ggui#987): which host-announced / stamped / sidecar mode a read door MUST paint, and which overlays it MUST keep.
-- **`@ggui-ai/protocol-conformance/n1-compat-conformance`** — N−1 wire compatibility (VERSION-POLICY §3.6, ggui#1014): BACKWARD cases are the previous release's payloads today's parsers MUST accept; the FORWARD case (ggui#1093) is a later release's payload today's READ door MUST keep, stripping and naming the unknown top-level member. Graded on every `runConformance()`.
+- **`@ggui-ai/protocol-conformance/n1-compat-conformance`** — N−1 wire compatibility (VERSION-POLICY §3.6, ggui#1014): BACKWARD cases are the previous release's payloads today's parsers MUST accept; a FORWARD case (ggui#1093) is a later release's payload today's READ door MUST keep, stripping and naming the unknown top-level member. The view-origin proof (ggui#1415) has two forward cases: a later proof version still fits the relay door shape and reads `version_unknown`, never `malformed`, and a v1 proof whose root carries a later claim still parses. Graded on every `runConformance()`.
 
 ```ts
 import { runSchemaConformance } from "@ggui-ai/protocol-conformance/schema-conformance";
@@ -149,35 +151,49 @@ Vendor-neutral like `resources/read`: the kit imports no server. The adopter sup
 
 The catalog exists for one receipt: before the slug led the text, every first-party server failed every case on `slug-leads` (executed, ggui#880). `src/cli-samples/tool-call-driver.mjs` is a spec-correct sample of what the flag imports.
 
+## Dispatch-idempotency conformance — a retried dispatch is one gesture (SPEC §11.1, ggui#1519)
+
+A host or relay that could not confirm a `ggui_runtime_submit_action` dispatch may retry it. The server treats a repeat of an earlier committed `(sessionId, actionId)` as the same gesture: one pending event for `ggui_consume` and one `user.submitted` row in the ledger `ggui_runtime_pull` serves, even with both requests in flight at once. An `actionId` reused for a different gesture keeps the first. Three cases: `sequential-retry-is-one-gesture`, `concurrent-retry-is-one-gesture`, `reused-id-keeps-the-first-gesture`. Each has a control: the SAME gesture under a distinct `actionId` is a second gesture, so a server that dedupes by content rather than by id fails it. The cases share their ids, each in a fresh session, so a server that dedupes ids across sessions fails from the second case on. A driver that throws, or a read that answers `isError`, is named on that case, and the run goes on.
+
+**SHOULD level this release:** a case that does not hold is reported `warned`, never `failed`. §11.1 makes the promise a MUST in the next release, and the catalog moves every case to `failed` with it.
+
+The adopter supplies the same `ToolCallDriver` the domain-error catalog takes, plus an `openSession()` seam: a fresh session that declares `DISPATCH_IDEMPOTENCY_ACTION_SPEC` and has a pending-event pipe, with a `close()` the kit calls after each case. Nothing on the wire mints such a session without generation, which is why it is a host seam. It is also why the CLI does not run this catalog: bind it in your own test, as `@ggui-ai/mcp-server`'s `dispatch-idempotency.conformance.test.ts` does. A host with no seam, or without the three tools, is SKIPPED with the reason named.
+
+**What the reuse case grades, and what it cannot yet:** it grades that the first gesture stands. It cannot tell a server that detects the reuse from one that dedupes by id alone, because both keep the first. The difference is visible only in the server's own log until `ACTION_ID_REUSED` is emitted, from the next release.
+
+**Not graded by the kit:** §11.1's spend clauses (a repeat, or a reused id, does not use up a one-shot action a second time). They are visible only inside the server; `@ggui-ai/mcp-server-handlers`' own tests grade them for the first-party server.
+
 ## Conformance status
 
 What is actually graded against shipping code today, and what is still awaiting a driver. This is an inventory, not a roadmap — a mechanism is listed as proven only if a test in the repo drives it against the real implementation on every push.
 
-Every test below is a plain `*.test.ts` inside a package's `src/`, so it runs in that package's ordinary vitest suite. The ggui repo's per-push CI runs `turbo run test` across all non-e2e packages, so **all thirteen rows below are gated on every push** — the kit needs no dedicated workflow, and adopters wiring it into their own CI need nothing more than their existing unit-test task.
-
-| Obligation                                                              | Graded against                                                                                                                                                                                                                                                                                | Driver                                                                                                                                                                        |
-| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Gadget wire schema (§7.7.2)                                             | the shipping `@ggui-ai/protocol` `clientCapabilitiesSpecSchema`                                                                                                                                                                                                                               | this kit's own `src/schema-conformance/schema-conformance.test.ts`                                                                                                            |
-| Registration gate (§7.7.3, §7.9)                                        | the shipping gate trio in `@ggui-ai/mcp-server-handlers`                                                                                                                                                                                                                                      | `mcp-server-handlers/src/renders/assert-gadgets.conformance.test.ts`                                                                                                          |
-| Bundle-URL resolution (§7.7.2)                                          | the shipping `resolveGadgetUrls` in `@ggui-ai/mcp-server-handlers`                                                                                                                                                                                                                            | `mcp-server-handlers/src/renders/resolve-gadget-urls.conformance.test.ts`                                                                                                     |
-| Path-A WS fixtures — first-party                                        | the real `@ggui-ai/mcp-server` GguiSession channel, booted in-process on an ephemeral port                                                                                                                                                                                                    | `mcp-server/src/ggui-session-channel.conformance.test.ts` — **24 pass / 12 skip / 0 fail**                                                                                    |
-| Path-A WS fixtures — vendor-neutral                                     | `@ggui-ai/protocol-reference-server`                                                                                                                                                                                                                                                          | `protocol-reference-server/src/conformance.test.ts` — **19 pass / 5 skip / 0 fail**                                                                                           |
-| `resources/read` typed failures + mount invariant                       | the shipping `registerGguiRenderResourceTemplate` in `@ggui-ai/mcp-server`                                                                                                                                                                                                                    | `mcp-server/src/mcp-apps-outbound.resource-read.conformance.test.ts` — **16 pass / 0 skip / 0 fail** (the pass set is pinned as the whole catalog)                            |
-| `tools/call` domain errors (§7.9 Plane 2, ggui#880)                     | the shipping `createGguiServer` in `@ggui-ai/mcp-server`, over Streamable HTTP                                                                                                                                                                                                                | `mcp-server/src/domain-error.conformance.test.ts` — **6 pass / 0 skip / 0 fail**                                                                                              |
-| Read-plane-only posture result (§7.10.6, ggui#1304)                     | the shipping `createGguiServer({ withholdResultMeta: true })` in `@ggui-ai/mcp-server`, over Streamable HTTP                                                                                                                                                                                  | `mcp-server/src/read-plane-only.conformance.test.ts` — **1 pass / 0 skip / 0 fail**, plus a posture-OFF control that fails exactly `slice-withheld` and `credential-withheld` |
-| Tool-binding resolution — declared wins, contract derivation (§7.7.4.1) | the shipping `resolveMcpToolBindings` in `@ggui-ai/artifact-manifest`                                                                                                                                                                                                                         | `artifact-manifest/src/mcp-tool-bindings.conformance.test.ts`                                                                                                                 |
-| Tool-binding search filters — `tool=` / `server=` semantics (§7.7.4.1)  | the shipping `matchesMcpToolFilters` in `@ggui-ai/registry-core`                                                                                                                                                                                                                              | `registry-core/src/mcp-tool-filters.conformance.test.ts`                                                                                                                      |
-| Pre-generation refusal envelope (§7.1, refused arm)                     | `projectRenderRefusal` in `@ggui-ai/protocol` — the one source both the shipping `ggui_render` handler (`@ggui-ai/mcp-server-handlers`) and `@ggui-ai/protocol-reference-server` answer through                                                                                               | `mcp-server-handlers/src/renders/render-refusal-projection.conformance.test.ts`                                                                                               |
-| Refusal-registry completeness (ggui#786 ruling 5b)                      | the shipping `PRE_GENERATION_REFUSAL_CODES` in `@ggui-ai/protocol`                                                                                                                                                                                                                            | this kit's own `src/registry-completeness/registry-completeness.test.ts`                                                                                                      |
-| Endpoint-level refusal (§7.1, `mcp-endpoint` surface, ggui#825)         | the catalog's kit-local reference projector only — no shipping deployment projector is graded yet: the OSS route is generic (`errorMapper`), the first-party server and the reference server supply no projector (SKIPPED, named), and a hosted deployment's projector lands after this slice | this kit's own `src/transport-refusal-conformance/transport-refusal-conformance.test.ts` (coherence + discrimination)                                                         |
-
-Both WS drivers pin their pass set _and_ their skip set as exact sets, and the resource-read driver pins its skip set as exactly empty. A fixture silently degrading to a skip fails the build, and so does a skipped fixture that quietly starts passing — a skip set that can grow unnoticed is a false gate, and re-pinning it is meant to be a deliberate act.
+Every test below is a plain `*.test.ts` inside a package's `src/`, so it runs in that package's ordinary vitest suite. The GGUI repo's per-push CI runs `turbo run test` across all non-e2e packages, so **all fourteen rows below are gated on every push** — the kit needs no dedicated workflow, and adopters wiring it into their own CI need nothing more than their existing unit-test task.
+
+| Obligation                                                              | Graded against                                                                                                                                                                                                                                                                                | Driver                                                                                                                                                                                      |
+| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Gadget wire schema (§7.7.2)                                             | the shipping `@ggui-ai/protocol` `clientCapabilitiesSpecSchema`                                                                                                                                                                                                                               | this kit's own `src/schema-conformance/schema-conformance.test.ts`                                                                                                                          |
+| Registration gate (§7.7.3, §7.9)                                        | the shipping gate trio in `@ggui-ai/mcp-server-handlers`                                                                                                                                                                                                                                      | `mcp-server-handlers/src/renders/assert-gadgets.conformance.test.ts`                                                                                                                        |
+| Bundle-URL resolution (§7.7.2)                                          | the shipping `resolveGadgetUrls` in `@ggui-ai/mcp-server-handlers`                                                                                                                                                                                                                            | `mcp-server-handlers/src/renders/resolve-gadget-urls.conformance.test.ts`                                                                                                                   |
+| Path-A WS fixtures — first-party                                        | the real `@ggui-ai/mcp-server` GguiSession channel, booted in-process on an ephemeral port                                                                                                                                                                                                    | `mcp-server/src/ggui-session-channel.conformance.test.ts` — **39 pass / 18 skip / 0 warn / 0 fail**, plus a no-replay control that warns exactly `fresh-subscribe-replays-reserved-preview` |
+| Path-A WS fixtures — vendor-neutral                                     | `@ggui-ai/protocol-reference-server`                                                                                                                                                                                                                                                          | `protocol-reference-server/src/conformance.test.ts` — **45 pass / 11 skip / 1 warn / 0 fail** (it declines the fresh-subscribe reserved replay, a SHOULD)                                   |
+| `resources/read` typed failures + mount invariant                       | the shipping `registerGguiRenderResourceTemplate` in `@ggui-ai/mcp-server`                                                                                                                                                                                                                    | `mcp-server/src/mcp-apps-outbound.resource-read.conformance.test.ts` — **16 pass / 0 skip / 0 fail** (the pass set is pinned as the whole catalog)                                          |
+| `tools/call` dispatch idempotency (§11.1, ggui#1519; SHOULD level)      | the shipping `defaultHandlers` in `@ggui-ai/mcp-server` (`submit_action`, `consume`, `runtime_pull` over one store and pipe)                                                                                                                                                                  | `mcp-server/src/dispatch-idempotency.conformance.test.ts` — **3 pass / 0 warn / 0 skip / 0 fail**                                                                                           |
+| `tools/call` domain errors (§7.9 Plane 2, ggui#880)                     | the shipping `createGguiServer` in `@ggui-ai/mcp-server`, over Streamable HTTP                                                                                                                                                                                                                | `mcp-server/src/domain-error.conformance.test.ts` — **6 pass / 0 skip / 0 fail**                                                                                                            |
+| Read-plane-only posture result (§7.10.6, ggui#1304)                     | the shipping `createGguiServer({ withholdResultMeta: true })` in `@ggui-ai/mcp-server`, over Streamable HTTP                                                                                                                                                                                  | `mcp-server/src/read-plane-only.conformance.test.ts` — **1 pass / 0 skip / 0 fail**, plus a posture-OFF control that fails exactly `slice-withheld` and `credential-withheld`               |
+| Tool-binding resolution — declared wins, contract derivation (§7.7.4.1) | the shipping `resolveMcpToolBindings` in `@ggui-ai/artifact-manifest`                                                                                                                                                                                                                         | `artifact-manifest/src/mcp-tool-bindings.conformance.test.ts`                                                                                                                               |
+| Tool-binding search filters — `tool=` / `server=` semantics (§7.7.4.1)  | the shipping `matchesMcpToolFilters` in `@ggui-ai/registry-core`                                                                                                                                                                                                                              | `registry-core/src/mcp-tool-filters.conformance.test.ts`                                                                                                                                    |
+| Pre-generation refusal envelope (§7.1, refused arm)                     | `projectRenderRefusal` in `@ggui-ai/protocol` — the one source both the shipping `ggui_render` handler (`@ggui-ai/mcp-server-handlers`) and `@ggui-ai/protocol-reference-server` answer through                                                                                               | `mcp-server-handlers/src/renders/render-refusal-projection.conformance.test.ts`                                                                                                             |
+| Refusal-registry completeness (ggui#786 ruling 5b)                      | the shipping `PRE_GENERATION_REFUSAL_CODES` in `@ggui-ai/protocol`                                                                                                                                                                                                                            | this kit's own `src/registry-completeness/registry-completeness.test.ts`                                                                                                                    |
+| Endpoint-level refusal (§7.1, `mcp-endpoint` surface, ggui#825)         | the catalog's kit-local reference projector only — no shipping deployment projector is graded yet: the OSS route is generic (`errorMapper`), the first-party server and the reference server supply no projector (SKIPPED, named), and a hosted deployment's projector lands after this slice | this kit's own `src/transport-refusal-conformance/transport-refusal-conformance.test.ts` (coherence + discrimination)                                                                       |
+
+Both WS drivers pin their pass set, their skip set _and_ their warned set as exact sets, and the resource-read driver pins its skip set as exactly empty. A fixture silently degrading to a skip fails the build, and so does a skipped fixture that quietly starts passing — a skip set that can grow unnoticed is a false gate, and re-pinning it is meant to be a deliberate act.
 
 **Awaiting a driver:**
 
 - **Path-B browser-host fixtures** — `bootstrap-bundle-fetch-failed`, `bootstrap-meta-missing` (both need MCP-Apps-host fault injection) and `props-update-roundtrip` (assertion is on rendered DOM). No browser-host adapter ships with the kit, so these skip on every WS driver above. Honestly absent, not silently passing.
 - **`version-mismatch` on the first-party server** — needs a `server-version-override` seam the channel deliberately does not expose; adding a production seam with no production caller purely to drive a fixture was rejected. It passes on the reference server, which has a per-render override.
 - **The `ggui_consume` retrieval half of the action loop, and `stream-delivery-roundtrip`** — both are `tools/call` obligations (`ggui_consume`, `ggui_emit`). The resource-read driver binds `resources/read` only, so neither is closed by it; both await a tool-call driver.
+- **The client side of SPEC §12.2.1 invariant 3** — after a fresh ack a client applies every frame, including those at `seq ≤ streamSeq`, and dedupes against the highest `seq` it applied, never against `streamSeq`. The kit has no driver for a live-channel _client_ (the runner is the client here, and the host-helper kit grades MCP Apps host helpers, not a view's channel), so this obligation is ungraded.
 - **`resources/read` on a second implementation** — the catalog is vendor-neutral by construction (the kit imports no server; the adopter supplies the driver), but it is graded against one implementation today. A second binding is what would ground the vendor-neutrality claim empirically, the way `protocol-reference-server` does for the WS catalog.
 
 ## Public API
@@ -192,9 +208,13 @@ const result = await runConformance({
 
 // A failed fixture is a red build — and so is a run that executed
 // ZERO fixtures (all skips prove nothing).
-if (result.failed.length > 0 || result.passed.length === 0) {
+// A warned fixture executed too, so it counts against the zero-executed
+// rule, but a warning never fails the run.
+if (result.failed.length > 0 || result.passed.length + result.warned.length === 0) {
   process.exit(1);
 }
+// `result.warned` lists the SHOULD fixtures the implementation
+// declined. Read them, don't gate on them.
 ```
 
 `serverUrl` accepts either a bare origin (`http://localhost:3000` — the runner derives `ws://localhost:3000/ws`) or the full live-channel endpoint (`ws://localhost:3000/ws` — used exactly as given; the runner never appends to an explicit path).
@@ -205,7 +225,7 @@ CLI equivalent:
 npx @ggui-ai/protocol-conformance --url ws://localhost:3000/ws --auth bearer:$TOKEN
 ```
 
-The CLI exits `0` only when at least one fixture executed and none failed; `1` on any fixture failure; `2` on invocation errors **or** when every fixture skipped (a zero-executed run never reads as success in CI).
+The CLI exits `0` only when at least one fixture executed and none failed; `1` on any fixture failure; `2` on invocation errors **or** when every fixture skipped (a zero-executed run never reads as success in CI). A warning never changes the exit code, and a warned fixture counts as executed.
 
 The three pure-function catalogs (`refusal-envelope`, `registry-completeness`, `transport-refusal`) grade an in-process function and a data table, not the wire, so a URL alone cannot reach them. The CLI hands them their inputs by flag — `--registry <file.json>` (the deployment's refusal registry, a JSON object keyed by code), `--projector <module>` (an ES module whose `project(refusal)` — named or default export — returns the SPEC §7.1 tool result, or `null` for a code with no render envelope) and `--transport-projector <module>` (same shape, returning the endpoint's `{ httpStatus, error }` or `null`). A flag left out leaves its catalog on the scorecard as SKIPPED with the flag named. Catalog rows count as executed fixtures, so a run given a catalog flag can exit 0 while every wire fixture is SKIPPED — read the scorecard for the wire signal. Minimal spec-correct samples of each input live in the repository at [`src/cli-samples/`](https://github.com/ggui-ai/ggui/tree/main/packages/protocol-conformance/src/cli-samples) (not in the npm tarball); the test suite pins that they pass their catalogs.
 

package/dist/cli.d.ts

@@ -40,8 +40,10 @@ export declare const USAGE: string;
 declare function main(argv: readonly string[]): Promise<number>;
 /**
  * Map a {@link ConformanceResult} to the CLI exit code:
- *   - `1` — at least one fixture failed.
- *   - `2` — zero fixtures executed (every fixture skipped). A run
+ *   - `1` — at least one fixture failed. A warning (a SHOULD fixture
+ *     whose expectation was not met) never does.
+ *   - `2` — zero fixtures executed (every fixture skipped). A warned
+ *     fixture executed. A run
  *     that graded nothing carries no conformance signal and must not
  *     read as success in CI.
  *   - `0` — at least one fixture executed and none failed.

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA6DA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAC;AAK9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAM7C,UAAU,UAAU;IAClB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,0FAA0F;IAC1F,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,iBAAS,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CA8DtD;AAOD,iBAAS,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAY3C;AAMD,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,IAAI,CAC9B,oBAAoB,EACpB,iBAAiB,GAAG,kBAAkB,GAAG,2BAA2B,GAAG,gBAAgB,CACxF,CAAC;AAEF,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9C;AA6KD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAqCxF;AAMD,eAAO,MAAM,KAAK,QA8DL,CAAC;AAEd,iBAAe,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAoE5D;AAED;;;;;;;GAOG;AACH,iBAAS,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAI/D;AA+BD,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA6DA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAC;AAK9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAM7C,UAAU,UAAU;IAClB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,0FAA0F;IAC1F,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,iBAAS,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CA8DtD;AAOD,iBAAS,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAY3C;AAMD,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,IAAI,CAC9B,oBAAoB,EACpB,iBAAiB,GAAG,kBAAkB,GAAG,2BAA2B,GAAG,gBAAgB,CACxF,CAAC;AAEF,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9C;AA6KD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAqCxF;AAMD,eAAO,MAAM,KAAK,QA8DL,CAAC;AAEd,iBAAe,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAsE5D;AAED;;;;;;;;;GASG;AACH,iBAAS,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAI/D;AA+BD,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC"}

package/dist/cli.js

@@ -36,8 +36,8 @@
  * design. To get real pass/fail signal against an implementation,
  * consumers call `runConformance({ host: myImpl })` programmatically
  * and apply the same guard:
- * `result.failed.length > 0 || result.passed.length === 0` is a red
- * build. The CLI remains the lowest-friction wire-level smoke check
+ * `result.failed.length > 0 || result.passed.length + result.warned.length === 0`
+ * is a red build (a warned fixture executed, and never fails a run). The CLI remains the lowest-friction wire-level smoke check
  * for setups where the server under test is provisioned out-of-band
  * rather than through a `ConformanceHost` injection.
  */
@@ -45,7 +45,7 @@ import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isRawToolCallResult, } from './domain-error-conformance/index.js';
-import { createDefaultReporter, formatFailures, formatSkips } from './reporter.js';
+import { createDefaultReporter, formatFailures, formatSkips, formatWarnings } from './reporter.js';
 import { runConformance, } from './run-conformance.js';
 function parseArgs(argv) {
     let url;
@@ -342,7 +342,7 @@ Options:
                            performs ONE tools/call and returns the raw result
                            (null = tool not bound). Grades the domain-error
                            catalog — SPEC §7.9 Plane 2 on the wire (ggui#880).
-  --verbose, -v            Print failure details + skip reasons at the end.
+  --verbose, -v            Print failure details, warnings + skip reasons at the end.
   --help, -h               Show this help.
 
 Pure-function catalogs (refusal-envelope, registry-completeness, transport-refusal):
@@ -421,20 +421,25 @@ async function main(argv) {
         const failures = formatFailures(result.failed);
         if (failures.length > 0)
             process.stdout.write(`${failures}\n`);
+        const warnings = formatWarnings(result.warned);
+        if (warnings.length > 0)
+            process.stdout.write(`${warnings}\n`);
         const skips = formatSkips(result.skipped);
         if (skips.length > 0)
             process.stdout.write(`${skips}\n`);
     }
     const code = exitCodeForResult(result);
     if (code === 2) {
-        process.stderr.write(`error: conformance run executed ZERO fixtures (0 passed, ${result.failed.length} failed, ${result.skipped.length} skipped) — an all-skip run proves nothing and must not read as success; exiting 2. Run with --verbose for skip reasons.\n`);
+        process.stderr.write(`error: conformance run executed ZERO fixtures (0 passed, ${result.failed.length} failed, 0 warned, ${result.skipped.length} skipped) — an all-skip run proves nothing and must not read as success; exiting 2. Run with --verbose for skip reasons.\n`);
     }
     return code;
 }
 /**
  * Map a {@link ConformanceResult} to the CLI exit code:
- *   - `1` — at least one fixture failed.
- *   - `2` — zero fixtures executed (every fixture skipped). A run
+ *   - `1` — at least one fixture failed. A warning (a SHOULD fixture
+ *     whose expectation was not met) never does.
+ *   - `2` — zero fixtures executed (every fixture skipped). A warned
+ *     fixture executed. A run
  *     that graded nothing carries no conformance signal and must not
  *     read as success in CI.
  *   - `0` — at least one fixture executed and none failed.
@@ -442,7 +447,7 @@ async function main(argv) {
 function exitCodeForResult(result) {
     if (result.failed.length > 0)
         return 1;
-    if (result.passed.length === 0)
+    if (result.passed.length === 0 && result.warned.length === 0)
         return 2;
     return 0;
 }

package/dist/dispatch-idempotency-conformance/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * `dispatch-idempotency` catalog — SPEC §11.1 "A retried dispatch is one
+ * gesture" (ggui#1519), graded on the `tools/call` wire.
+ *
+ * A host or relay that could not confirm a `ggui_runtime_submit_action`
+ * dispatch may retry it. The server treats a repeat of an earlier committed
+ * `(sessionId, actionId)` as the same gesture: one pending event for the
+ * agent's `ggui_consume`, one `user.submitted` row in the ledger that
+ * `ggui_runtime_pull` serves, even when both requests are in flight at once.
+ * An `actionId` reused for a DIFFERENT gesture keeps the first.
+ *
+ * SHOULD LEVEL THIS RELEASE. §11.1 states the promise as a SHOULD and makes
+ * it a MUST in the next release, so a case that does not hold is reported
+ * `warned`, never `failed`. The next release moves every case to `failed`.
+ *
+ * Vendor-neutral by construction: the kit imports no server. The adopter
+ * supplies a {@link ToolCallDriver} (the same one the `domain-error` catalog
+ * takes) and a {@link DispatchIdempotencyHost.openSession} seam that opens a
+ * live session declaring the kit's action, with a pending-event pipe, and
+ * later closes it. Nothing on the wire mints such a session without
+ * generation, which is why it is a host seam. A host that supplies no seam,
+ * or binds none of the three tools, is SKIPPED with the reason named.
+ *
+ * What the cases are built to catch, beyond "no dedupe at all": the control
+ * repeats the SAME gesture under a new id, so a server that dedupes by content
+ * rather than by id loses it; the ids repeat across cases, each in a fresh
+ * session, so a server that dedupes by id across sessions loses the later
+ * cases' first gesture; and the concurrent case puts both requests in flight
+ * at once, so a check-then-write dedupe lets both through. A driver that
+ * throws, or a read that answers `isError`, is named on its case rather than
+ * read as an empty pipe.
+ *
+ * Not graded here: whether a repeat re-spends a one-shot action. That clause
+ * of §11.1 is visible only inside the server, and the first-party server's
+ * own tests grade it.
+ */
+import type { ActionSpec } from '@ggui-ai/protocol';
+import type { ToolCallDriver } from '../domain-error-conformance/index.js';
+/** The one action every case dispatches; the host's session must declare it. */
+export declare const DISPATCH_IDEMPOTENCY_ACTION: "pick";
+/**
+ * The action spec the host's session declares: one action whose payload is
+ * `{ choice: string }`. Declared in full because a contract gate treats an
+ * object schema as closed, and the cases tell gestures apart by `choice`.
+ */
+export declare const DISPATCH_IDEMPOTENCY_ACTION_SPEC: ActionSpec;
+/** A live session the host opened for one case, and how to release it. */
+export interface DispatchIdempotencySession {
+    readonly sessionId: string;
+    readonly appId: string;
+    close(): Promise<void>;
+}
+/** What the adopter supplies. */
+export interface DispatchIdempotencyHost {
+    readonly callTool: ToolCallDriver;
+    /**
+     * Open a fresh session declaring {@link DISPATCH_IDEMPOTENCY_ACTION_SPEC},
+     * with its pending-event pipe open. The seam owns cleanup: the kit calls
+     * `close()` after the case, whatever its outcome.
+     */
+    readonly openSession?: () => Promise<DispatchIdempotencySession>;
+}
+export type DispatchIdempotencyCaseName = 'sequential-retry-is-one-gesture' | 'concurrent-retry-is-one-gesture' | 'reused-id-keeps-the-first-gesture';
+export interface DispatchIdempotencyCaseResult {
+    /** Reported as `dispatch-idempotency/<name>`. */
+    readonly name: DispatchIdempotencyCaseName;
+    readonly detail: string;
+}
+export interface DispatchIdempotencyResult {
+    readonly passed: readonly DispatchIdempotencyCaseResult[];
+    /** SHOULD level: a case that does not hold lands here, not in `failed`. */
+    readonly warned: readonly DispatchIdempotencyCaseResult[];
+    readonly failed: readonly DispatchIdempotencyCaseResult[];
+    readonly skipped: readonly DispatchIdempotencyCaseResult[];
+}
+/** Run the catalog. Each case gets its own session from the host's seam. */
+export declare function runDispatchIdempotencyConformance(host: DispatchIdempotencyHost): Promise<DispatchIdempotencyResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/dispatch-idempotency-conformance/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dispatch-idempotency-conformance/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAgB,cAAc,EAAqB,MAAM,sCAAsC,CAAC;AAE5G,gFAAgF;AAChF,eAAO,MAAM,2BAA2B,EAAG,MAAe,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,EAAE,UAK9C,CAAC;AAEF,0EAA0E;AAC1E,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,iCAAiC;AACjC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,0BAA0B,CAAC,CAAC;CAClE;AAED,MAAM,MAAM,2BAA2B,GACnC,iCAAiC,GACjC,iCAAiC,GACjC,mCAAmC,CAAC;AAExC,MAAM,WAAW,6BAA6B;IAC5C,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,SAAS,6BAA6B,EAAE,CAAC;IAC1D,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,SAAS,6BAA6B,EAAE,CAAC;IAC1D,QAAQ,CAAC,MAAM,EAAE,SAAS,6BAA6B,EAAE,CAAC;IAC1D,QAAQ,CAAC,OAAO,EAAE,SAAS,6BAA6B,EAAE,CAAC;CAC5D;AA0ID,4EAA4E;AAC5E,wBAAsB,iCAAiC,CACrD,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,yBAAyB,CAAC,CAyBpC"}

package/dist/dispatch-idempotency-conformance/index.js

@@ -0,0 +1,173 @@
+/** The one action every case dispatches; the host's session must declare it. */
+export const DISPATCH_IDEMPOTENCY_ACTION = 'pick';
+/**
+ * The action spec the host's session declares: one action whose payload is
+ * `{ choice: string }`. Declared in full because a contract gate treats an
+ * object schema as closed, and the cases tell gestures apart by `choice`.
+ */
+export const DISPATCH_IDEMPOTENCY_ACTION_SPEC = {
+    [DISPATCH_IDEMPOTENCY_ACTION]: {
+        label: 'Pick',
+        schema: { type: 'object', properties: { choice: { type: 'string' } }, required: ['choice'] },
+    },
+};
+const CASES = [
+    'sequential-retry-is-one-gesture',
+    'concurrent-retry-is-one-gesture',
+    'reused-id-keeps-the-first-gesture',
+];
+/**
+ * The ids every case uses. The SAME ids in every case, each case in its own
+ * session: the promise is per `(sessionId, actionId)`, so a later case's first
+ * dispatch is a new gesture, and a server that remembers ids across sessions
+ * drops it.
+ */
+const X = 'kit-1519-x';
+const Y = 'kit-1519-y';
+/** Thrown inside a case when the host cannot run it at all (a tool unbound). */
+class Unbound extends Error {
+}
+function field(value, key) {
+    return typeof value === 'object' && value !== null ? Reflect.get(value, key) : undefined;
+}
+function dispatchArgs(session, actionId, choice) {
+    return {
+        sessionId: session.sessionId,
+        appId: session.appId,
+        kind: 'dispatch',
+        actionId,
+        firedAt: '2026-09-29T00:00:00.000Z',
+        payload: { intent: DISPATCH_IDEMPOTENCY_ACTION, actionData: { choice }, uiContext: {} },
+    };
+}
+async function call(host, tool, args) {
+    const result = await host.callTool({ tool, args });
+    if (result === null)
+        throw new Unbound(`${tool} is not bound on this deployment`);
+    return result;
+}
+/** `ok: true` from submit_action, or the declared reuse answer where a case allows it. */
+function answerOf(result) {
+    const structured = result.structuredContent;
+    if (field(structured, 'ok') === true)
+        return 'ok';
+    const code = field(structured, 'code');
+    return typeof code === 'string' ? code : result.isError === true ? 'isError' : 'unknown';
+}
+/**
+ * A read tool's `events`, or the reason there are none to count: a read that
+ * answered `isError`, or no `events` array, is a problem of its own and not an
+ * empty pipe (which would misreport the case as a delivery count).
+ */
+async function readEvents(host, tool, args) {
+    const result = await call(host, tool, args);
+    if (result.isError === true)
+        return { problem: `${tool} answered isError` };
+    const events = field(result.structuredContent, 'events');
+    if (!Array.isArray(events))
+        return { problem: `${tool} answered no events array` };
+    return { events };
+}
+/** Run one case against a fresh session. Returns the reasons it does not hold (empty = holds). */
+async function runCase(name, host, session) {
+    const problems = [];
+    let answers;
+    switch (name) {
+        case 'sequential-retry-is-one-gesture':
+            answers = [
+                answerOf(await call(host, 'ggui_runtime_submit_action', dispatchArgs(session, X, 'a'))),
+                answerOf(await call(host, 'ggui_runtime_submit_action', dispatchArgs(session, X, 'a'))),
+            ];
+            break;
+        case 'concurrent-retry-is-one-gesture':
+            answers = (await Promise.all([
+                call(host, 'ggui_runtime_submit_action', dispatchArgs(session, X, 'a')),
+                call(host, 'ggui_runtime_submit_action', dispatchArgs(session, X, 'a')),
+            ])).map(answerOf);
+            break;
+        case 'reused-id-keeps-the-first-gesture':
+            answers = [
+                answerOf(await call(host, 'ggui_runtime_submit_action', dispatchArgs(session, X, 'a'))),
+                answerOf(await call(host, 'ggui_runtime_submit_action', dispatchArgs(session, X, 'b'))),
+            ];
+            break;
+    }
+    // Control: the SAME gesture under a DISTINCT id is a second gesture, so a
+    // server that drops every dispatch, every second one, or every repeat of
+    // content, cannot pass.
+    const control = answerOf(await call(host, 'ggui_runtime_submit_action', dispatchArgs(session, Y, 'a')));
+    const reuseCase = name === 'reused-id-keeps-the-first-gesture';
+    if (answers[0] !== 'ok')
+        problems.push(`the first dispatch answered ${answers[0]}, not ok`);
+    // The repeat is answered as the first was; a reuse may instead be refused
+    // ACTION_ID_REUSED (declared this release, emitted from the next).
+    if (!(answers[1] === 'ok' || (reuseCase && answers[1] === 'ACTION_ID_REUSED'))) {
+        problems.push(`the repeat answered ${answers[1]}${reuseCase ? ', not ok or ACTION_ID_REUSED' : ', not as the first'}`);
+    }
+    if (control !== 'ok')
+        problems.push(`the control (a distinct actionId) answered ${control}, not ok`);
+    // One consume: it clears what it returns, so a second would read nothing.
+    const drained = await readEvents(host, 'ggui_consume', { sessionId: session.sessionId, timeout: 0 });
+    if ('problem' in drained) {
+        problems.push(drained.problem);
+    }
+    else {
+        const events = drained.events.filter((e) => field(e, 'actionId') === X).map((e) => field(e, 'actionData'));
+        if (events.length !== 1)
+            problems.push(`ggui_consume delivered ${events.length} events for the repeated actionId, not 1`);
+        if (reuseCase && events.length === 1 && field(events[0], 'choice') !== 'a') {
+            problems.push('the delivered event is not the first gesture');
+        }
+        const controlEvents = drained.events.filter((e) => field(e, 'actionId') === Y).length;
+        if (controlEvents !== 1)
+            problems.push(`the control's gesture was delivered ${controlEvents} times, not once`);
+    }
+    const ledger = await readEvents(host, 'ggui_runtime_pull', { sessionId: session.sessionId, sinceSequence: 0, limit: 100 });
+    if ('problem' in ledger) {
+        problems.push(ledger.problem);
+    }
+    else {
+        const rowsFor = (id) => ledger.events.filter((e) => field(e, 'type') === 'user.submitted' && field(field(e, 'data'), 'actionId') === id)
+            .length;
+        const rows = rowsFor(X);
+        if (rows !== 1)
+            problems.push(`the ledger holds ${rows} user.submitted rows for the repeated actionId, not 1`);
+        const controlRows = rowsFor(Y);
+        if (controlRows !== 1)
+            problems.push(`the control's gesture has ${controlRows} ledger rows, not 1`);
+    }
+    return problems;
+}
+/** Run the catalog. Each case gets its own session from the host's seam. */
+export async function runDispatchIdempotencyConformance(host) {
+    const passed = [];
+    const warned = [];
+    const skipped = [];
+    for (const name of CASES) {
+        if (!host.openSession) {
+            skipped.push({ name, detail: 'the host supplies no openSession seam, so no session declares the kit action' });
+            continue;
+        }
+        const session = await host.openSession();
+        try {
+            const problems = await runCase(name, host, session);
+            if (problems.length === 0)
+                passed.push({ name, detail: 'one gesture: one consumed event and one ledger row' });
+            else
+                warned.push({ name, detail: problems.join('; ') });
+        }
+        catch (err) {
+            // An unbound tool skips the case. Any other throw (the driver's, or the
+            // server's through it) is the case not holding, named, and the run goes
+            // on: one case's transport failure grades that case only.
+            if (err instanceof Unbound)
+                skipped.push({ name, detail: err.message });
+            else
+                warned.push({ name, detail: `the case threw: ${err instanceof Error ? err.message : String(err)}` });
+        }
+        finally {
+            await session.close();
+        }
+    }
+    return { passed, warned, failed: [], skipped };
+}

package/dist/fixtures/index.d.ts

@@ -20,7 +20,7 @@
  *
  * ## Current coverage
  *
- * Six WebSocket sub-modules with content (12 fixtures). Additional sub-modules
+ * Seven WebSocket sub-modules with content (13 fixtures). Additional sub-modules
  * (`data-contract`, `tool-name-uniqueness`)
  * are reserved for additive fixture expansion and not yet
  * materialized — adding fixtures there is a kit minor version.
@@ -90,8 +90,8 @@
  * false fail: the runner dispatches every setup directive BEFORE it
  * opens the WebSocket and subscribes, and `emit-envelope` fans out to
  * live subscribers only — a fresh, `fromSeq`-less subscribe replays
- * nothing on declared channels (SPEC §12.2.1 invariant 1: "`fromSeq`
- * absent always means empty replay"), so the setup-time emission is
+ * nothing on declared channels (SPEC §12.2.1 invariant 1: a fresh
+ * subscribe replays no agent-declared channel), so the setup-time emission is
  * gone before the runner can observe it. The fixture's
  * `inputEnvelope` cannot carry the emission either: an input envelope
  * is by contract a Client→Server wire frame the runner sends on the
@@ -102,11 +102,29 @@
  * driver bound to `tools/call`. The `resources/read` driver above is
  * NOT that driver. Declared here rather than papered over with a
  * fixture that fails conformant servers on sequencing alone.
+ *
+ * A KNOWN-RESERVED channel is different, and that case IS authored
+ * (`reserved-channel-replay`, ggui#1526): a fresh subscribe SHOULD
+ * replay its retained envelopes after the ack (SPEC §12.2.1, the
+ * ggui#1521 erratum), so the setup-time emission is observable as that
+ * replay. It is graded at `level: 'should'`: a server that declines it
+ * is warned, never failed.
+ *
+ * ## What is NOT here — the client side of invariant 3
+ *
+ * SPEC §12.2.1 invariant 3 is a CLIENT obligation: after a fresh ack,
+ * apply every frame, including those at `seq ≤ streamSeq`, and dedupe
+ * against the highest `seq` applied, never against `streamSeq`. The kit
+ * has no driver for a live-channel CLIENT (the runner IS the client
+ * here, and the host-helper kit grades MCP Apps host helpers, not a
+ * view's channel), so it cannot grade that obligation. Declared as a
+ * gap, not implied as covered.
  */
 export { bootstrapProtocolFixtures } from './bootstrap-protocol/index.js';
 export { consumeBufferFixtures } from './consume-buffer/index.js';
 export { hostContextFixtures } from './host-context/index.js';
 export { reservedChannelAuthorityFixtures } from './reserved-channel-authority/index.js';
+export { reservedChannelReplayFixtures } from './reserved-channel-replay/index.js';
 export { schemaVersionHandshakeFixtures } from './schema-version-handshake/index.js';
 export { subscribeAppScopeFixtures } from './subscribe-app-scope/index.js';
 import type { TestCase } from '../types.js';
@@ -116,7 +134,7 @@ import type { TestCase } from '../types.js';
  * Extensibly-closed via `(string & {})` so additive sub-modules
  * register without an API break.
  */
-export type ContractSlug = 'bootstrap-protocol' | 'consume-buffer' | 'host-context' | 'reserved-channel-authority' | 'schema-version-handshake' | 'subscribe-app-scope' | (string & {});
+export type ContractSlug = 'bootstrap-protocol' | 'consume-buffer' | 'host-context' | 'reserved-channel-authority' | 'reserved-channel-replay' | 'schema-version-handshake' | 'subscribe-app-scope' | (string & {});
 /**
  * Every fixture the kit ships, grouped by the contract it exercises.
  * Order within each group matches the sub-module's `export` order.

package/dist/fixtures/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fixtures/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwGG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,gCAAgC,EAAE,MAAM,uCAAuC,CAAC;AACzF,OAAO,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAE3E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAQ5C;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GACpB,oBAAoB,GACpB,gBAAgB,GAChB,cAAc,GACd,4BAA4B,GAC5B,0BAA0B,GAC1B,qBAAqB,GACrB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,SAAS,QAAQ,EAAE,CAAC,CAOlF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,QAAQ,EAGwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fixtures/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyHG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,gCAAgC,EAAE,MAAM,uCAAuC,CAAC;AACzF,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AACnF,OAAO,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAE3E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAS5C;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GACpB,oBAAoB,GACpB,gBAAgB,GAChB,cAAc,GACd,4BAA4B,GAC5B,yBAAyB,GACzB,0BAA0B,GAC1B,qBAAqB,GACrB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,SAAS,QAAQ,EAAE,CAAC,CAQlF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,QAAQ,EAGwB,CAAC"}