@ggui-ai/protocol-conformance 0.14.0 → 0.16.0

package/README.md

@@ -19,7 +19,7 @@ A fifth surface — the **Path-B browser-host driver** for DOM-level claims (`bo
 
 **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` is the only MCP method bound today; `tools/call` has no driver yet.
+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.
 
 ## Path-A vs Path-B matchability
 
@@ -51,7 +51,7 @@ One declared grading gap on the action loop: `action-ack` proves the append half
 
 The behavioral fixture catalog above asserts what an implementation _does_ over the wire. Some protocol obligations aren't transport-observable at all — they are deterministic _validation functions_: given an input, accept or reject it. SPEC §7.7.2's gadget obligations are exactly this. Modeling them as WebSocket fixtures would mean faking wire frames the protocol never emits; instead the kit ships **pure-function catalogs** — accept/reject cases graded against a caller-supplied function, with no host, render, or transport.
 
-Each catalog ships its cases as raw JSON so a non-TypeScript implementer can grade their own implementation, and each runner takes the implementation as a callback — the kit never hard-binds a concrete one. Eight catalogs ship today:
+Each catalog ships its cases as raw JSON so a non-TypeScript implementer can grade their own implementation, and each runner takes the implementation as a callback — the kit never hard-binds a concrete one. Nine catalogs ship today:
 
 - **`@ggui-ai/protocol-conformance/schema-conformance`** — which `DataContract.clientCapabilities` payloads a conformant parser MUST accept / reject (the gadget wire shape).
 - **`@ggui-ai/protocol-conformance/registration-conformance`** — which `(contract, appGadgets, appPublicEnv)` triples the push-time gadget gate stack MUST accept / reject, and with which precise SPEC §7.9 reject code (`gadget_not_registered` / `gadget_package_mismatch` / `gadget_public_env_missing` / `duplicate_gadget_hook`).
@@ -61,6 +61,7 @@ Each catalog ships its cases as raw JSON so a non-TypeScript implementer can gra
 - **`@ggui-ai/protocol-conformance/host-helper-conformance`** — which render coordinates a HOST-HELPER library MUST extract from a `tools/call` result, and which malformed results it MUST decline rather than guess at.
 - **`@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`.
 
 ```ts
 import { runSchemaConformance } from "@ggui-ai/protocol-conformance/schema-conformance";
@@ -115,24 +116,33 @@ The catalog grades all four failure classes (`NOT_FOUND` on `-32002`; `BLUEPRINT
 
 It deliberately does **not** grade: the order in which a substrate-less server answers (`NOT_SUPPORTED` describes the deployment, so answering it immediately is correct); `detail` wording on any code; the `NOT_FOUND` message literal (its _constancy_ is what is normative); internal-error message text; the number a URI naming no locator receives (that belongs to the transport binding — only the negative is graded, that it must not be one of the four); and the shell's markup (success is graded on the projected render meta, never on DOM shape).
 
+## Domain-error conformance — the `tools/call` binding (SPEC §7.9 Plane 2, ggui#880)
+
+The kit's first `tools/call` driver. A Plane-2 failure — a missing session or handshake, props that do not satisfy the contract, an undeclared channel — is a tool-execution error, so it is a tool RESULT with `isError: true` (never a JSON-RPC error frame) whose `content[0].text` LEADS with the registered slug: `<code>: <detail>`. No `structuredContent`, no `_meta`. A raw MCP agent branches on `text.startsWith(code + ': ')` for a code in `@ggui-ai/protocol`'s `DOMAIN_ERROR_CODES` and on nothing else.
+
+Vendor-neutral like `resources/read`: the kit imports no server. The adopter supplies a **driver** — `toolCallDriver` on `runConformance()`, or `--tool-call-driver <module>` on the CLI (an ES module exporting `drive(scenario)` or a default) — that performs ONE `tools/call` against the deployment and returns the raw result the MCP client received, or `null` when the tool is not bound there (that case is SKIPPED, named). The kit owns the scenarios and every assertion. Six no-setup cases under `src/domain-error-conformance/cases/`: an unknown `handshakeId` on `ggui_render` (`handshake_not_found`) and an unknown `sessionId` on `ggui_consume` / `ggui_get_session` / `ggui_update` / `ggui_amend` / `ggui_emit` (`session_not_found`). Each is graded on the raw result — `isError`, `content-text`, `slug-leads`, `no-structuredContent`, `no-meta` — and reported as `domain-error/<case>`; a driver that throws fails that case only.
+
+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.
+
 ## 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 ten 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` — **8 pass / 4 skip / 0 fail**             |
-| Path-A WS fixtures — vendor-neutral                                     | `@ggui-ai/protocol-reference-server`                                                       | `protocol-reference-server/src/conformance.test.ts` — **9 pass / 3 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` — **12 pass / 0 skip / 0 fail** |
-| 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)                     | the shipping `ggui_render` refusal projection in `@ggui-ai/mcp-server-handlers`            | `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`                             |
+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 twelve 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` — **12 pass / 0 skip / 0 fail**                  |
+| 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.
 
@@ -170,6 +180,13 @@ npx @ggui-ai/protocol-conformance --url ws://localhost:3000/ws --auth bearer:$TO
 
 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 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.
+
+```
+npx @ggui-ai/protocol-conformance --url ws://localhost:3000/ws --auth bearer:$TOKEN \
+  --registry ./refusal-registry.json --projector ./project.mjs --transport-projector ./endpoint.mjs
+```
+
 To grade setup-dependent fixtures (and any `session-state` fixture), pass a `host` implementing the `ConformanceHost` adapter — `dispatchSetup` / `dispatchTeardown` for the directive vocabulary, plus the optional `readSessionField(sessionId, field)` introspection seam. Fixtures whose requirements the host doesn't meet skip with a precise reason; they never silently pass.
 
 ## License

package/dist/cli.d.ts

@@ -1,16 +1,42 @@
 #!/usr/bin/env node
-import { type ConformanceResult } from './run-conformance.js';
+import { type ConformanceResult, type RunConformanceConfig } from './run-conformance.js';
 import type { AuthConfig } from './types.js';
 interface ParsedArgs {
     readonly url?: string;
     readonly auth?: string;
     readonly only?: readonly string[];
     readonly timeoutMs?: number;
+    /** Path to a JSON file holding the deployment's refusal registry (code → row). */
+    readonly registry?: string;
+    /** Path to an ES module exporting the SPEC §7.1 refusal projector. */
+    readonly projector?: string;
+    /** Path to an ES module exporting the endpoint-level refusal projector. */
+    readonly transportProjector?: string;
+    /** Path to an ES module exporting a `tools/call` driver (SPEC §7.9 Plane 2, ggui#880). */
+    readonly toolCallDriver?: string;
     readonly verbose: boolean;
     readonly help: boolean;
 }
 declare function parseArgs(argv: readonly string[]): ParsedArgs;
 declare function parseAuth(spec: string): AuthConfig;
+/** The three optional inputs a CLI run can hand the pure-function catalogs. */
+export type CatalogInputs = Pick<RunConformanceConfig, 'refusalRegistry' | 'refusalProjector' | 'transportRefusalProjector' | 'toolCallDriver'>;
+/** The flag values that name where each catalog input comes from. */
+export interface CatalogInputPaths {
+    readonly registry?: string | undefined;
+    readonly projector?: string | undefined;
+    readonly transportProjector?: string | undefined;
+    readonly toolCallDriver?: string | undefined;
+}
+/**
+ * Resolve the `--registry` / `--projector` / `--transport-projector` /
+ * `--tool-call-driver`
+ * flags into the runner's catalog inputs. A flag that is absent yields
+ * no input, and the runner reports that catalog SKIPPED with the flag
+ * named. Every failure names the flag and the path.
+ */
+export declare function loadCatalogInputs(paths: CatalogInputPaths): Promise<CatalogInputs>;
+export declare const USAGE: string;
 declare function main(argv: readonly string[]): Promise<number>;
 /**
  * Map a {@link ConformanceResult} to the CLI exit code:

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA+BA,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9E,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,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,CA8CtD;AAED,iBAAS,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAY3C;AA6CD,iBAAe,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA0D5D;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,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"}

package/dist/cli.js

@@ -16,25 +16,46 @@
  * may legitimately not provide every `ConformanceHost` directive in
  * v1.0 — but a run that is ALL skips carries no signal.
  *
+ * The three PURE-FUNCTION catalogs (refusal-envelope,
+ * registry-completeness, transport-refusal) grade an in-process
+ * function and a data table, not the wire: `--registry <file.json>`,
+ * `--projector <module>`, `--transport-projector <module>` and
+ * `--tool-call-driver <module>` (the domain-error catalog, the kit's
+ * first tools/call driver, ggui#880) hand
+ * them their inputs (ggui#803 leg 3). A flag left out leaves its
+ * catalog SKIPPED with the flag named, never silently absent. 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,
+ * not only the exit code, for a wire signal.
+ *
  * Honest scope of the bundled CLI: no `host` wiring. The CLI runs
  * the runner with an absent host, meaning every fixture with non-empty
  * `setup` skips cleanly with the "no host provided" reason — and
  * since every fixture in the current catalog declares setup, a
- * hostless CLI run skips them all and exits 2 by 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 for setups where the server under test is provisioned
- * out-of-band rather than through a `ConformanceHost` injection.
+ * hostless CLI run with no catalog flag skips them all and exits 2 by
+ * 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
+ * for setups where the server under test is provisioned out-of-band
+ * rather than through a `ConformanceHost` injection.
  */
+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 { runConformance } from './run-conformance.js';
+import { runConformance, } from './run-conformance.js';
 function parseArgs(argv) {
     let url;
     let auth;
     const only = [];
     let timeoutMs;
+    let registry;
+    let projector;
+    let toolCallDriver;
+    let transportProjector;
     let verbose = false;
     let help = false;
     for (let i = 0; i < argv.length; i += 1) {
@@ -62,6 +83,18 @@ function parseArgs(argv) {
                 if (Number.isNaN(timeoutMs))
                     throw new Error('--timeout-ms must be an integer');
                 break;
+            case '--registry':
+                registry = next();
+                break;
+            case '--projector':
+                projector = next();
+                break;
+            case '--transport-projector':
+                transportProjector = next();
+                break;
+            case '--tool-call-driver':
+                toolCallDriver = next();
+                break;
             case '--verbose':
             case '-v':
                 verbose = true;
@@ -74,7 +107,11 @@ function parseArgs(argv) {
                 throw new Error(`unknown flag '${flag}' — run with --help for usage`);
         }
     }
-    return { url, auth, only, timeoutMs, verbose, help };
+    return { url, auth, only, timeoutMs, registry, projector, transportProjector, toolCallDriver, verbose, help };
+}
+/** The message of a thrown value, without pretending every throw is an Error. */
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
 }
 function parseAuth(spec) {
     const idx = spec.indexOf(':');
@@ -89,10 +126,184 @@ function parseAuth(spec) {
         return { kind: 'session-cookie', cookie: value };
     throw new Error(`--auth kind '${kind}' is not recognized; supported: 'bearer', 'session-cookie'`);
 }
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+/**
+ * The runtime twin of {@link RefusalRegistryRow} — a JSON registry is
+ * held to exactly the shape a programmatic caller has to satisfy at
+ * compile time. Value-level rules (recognized retry class, `fixBy` on
+ * `after-fix`, code equals key, non-empty surfaces) are NOT checked
+ * here: those are the registry-completeness catalog's pins, and a
+ * deliberately broken registry must stay expressible so they can
+ * grade it.
+ */
+function isRegistryRow(value) {
+    return (isRecord(value) &&
+        typeof value.code === 'string' &&
+        isStringArray(value.surfaces) &&
+        typeof value.retry === 'string' &&
+        (value.fixBy === undefined || typeof value.fixBy === 'string') &&
+        typeof value.emitter === 'string' &&
+        typeof value.description === 'string');
+}
+function parseRegistryView(text, path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`--registry ${path} is not JSON: ${errorMessage(err)}`);
+    }
+    if (!isRecord(parsed)) {
+        throw new Error(`--registry ${path} must be a JSON object of rows keyed by code`);
+    }
+    const rows = [];
+    for (const [code, row] of Object.entries(parsed)) {
+        if (!isRegistryRow(row)) {
+            throw new Error(`--registry ${path}: row '${code}' is not a registry row (needs string code, string[] surfaces, string retry, string emitter, string description, optional string fixBy)`);
+        }
+        rows.push([code, row]);
+    }
+    // fromEntries defines OWN properties — a row keyed `__proto__` stays a row.
+    return Object.fromEntries(rows);
+}
+function isRefusalInput(value) {
+    return (isRecord(value) &&
+        typeof value.code === 'string' &&
+        typeof value.message === 'string' &&
+        typeof value.fix === 'string' &&
+        typeof value.retry === 'string' &&
+        typeof value.handshake === 'string' &&
+        (value.balanceCentsAtCheck === undefined || typeof value.balanceCentsAtCheck === 'number'));
+}
+function isProjectedRefusalResult(value) {
+    return (isRecord(value) &&
+        typeof value.isError === 'boolean' &&
+        typeof value.text === 'string' &&
+        isRecord(value.structuredContent) &&
+        typeof value.structuredContent.outcome === 'string' &&
+        isRefusalInput(value.structuredContent.refusal) &&
+        typeof value.hasMeta === 'boolean' &&
+        isStringArray(value.identityFields));
+}
+function isTransportRefusalInput(value) {
+    return (isRecord(value) &&
+        typeof value.code === 'string' &&
+        typeof value.message === 'string' &&
+        typeof value.fix === 'string' &&
+        typeof value.retry === 'string' &&
+        typeof value.appId === 'string');
+}
+function isProjectedTransportRefusal(value) {
+    return (isRecord(value) &&
+        typeof value.httpStatus === 'number' &&
+        isRecord(value.error) &&
+        typeof value.error.code === 'number' &&
+        typeof value.error.message === 'string' &&
+        isRecord(value.error.data) &&
+        isTransportRefusalInput(value.error.data.refusal));
+}
+/**
+ * Import an ES module at `path` (resolved against the working
+ * directory) and return the projector it exports —
+ * `export function project(...)` or the default export. The module is
+ * an external boundary: its export is checked to be a function here,
+ * and every value it returns is checked against the projection shape
+ * by `guard` before the catalog sees it, so a module that returns the
+ * wrong shape fails by flag name instead of typing its way into a
+ * grade. The catalogs grade that throw as a FAIL on the case in hand
+ * and keep grading the rest — never a crash of the run.
+ */
+async function loadProjector(flag, path, guard) {
+    const href = pathToFileURL(resolve(path)).href;
+    let mod;
+    try {
+        mod = await import(/* @vite-ignore */ href);
+    }
+    catch (err) {
+        throw new Error(`${flag} ${path} could not be imported: ${errorMessage(err)}`);
+    }
+    const candidate = mod.project ?? mod.default;
+    if (typeof candidate !== 'function') {
+        throw new Error(`${flag} ${path} must export \`project\` (or a default export) as a function`);
+    }
+    return (input) => {
+        const out = candidate(input);
+        if (out === null)
+            return null;
+        if (!guard(out)) {
+            throw new Error(`${flag} ${path} returned a value that is not a projection: ${JSON.stringify(out)}`);
+        }
+        return out;
+    };
+}
+/**
+ * Like {@link loadProjector} for a `tools/call` DRIVER: the export is
+ * `drive` (or the default export), it may be async, and `null` means
+ * "the tool is not bound on this deployment" (the catalog SKIPS that
+ * case, named). Every other value is held to the raw-result shape.
+ */
+async function loadDriver(flag, path, guard) {
+    const href = pathToFileURL(resolve(path)).href;
+    let mod;
+    try {
+        mod = await import(/* @vite-ignore */ href);
+    }
+    catch (err) {
+        throw new Error(`${flag} ${path} could not be imported: ${errorMessage(err)}`);
+    }
+    const candidate = mod.drive ?? mod.default;
+    if (typeof candidate !== 'function') {
+        throw new Error(`${flag} ${path} must export \`drive\` (or a default export) as a function`);
+    }
+    return async (input) => {
+        const out = await candidate(input);
+        if (out === null)
+            return null;
+        if (!guard(out)) {
+            throw new Error(`${flag} ${path} returned a value that is not a raw tools/call result: ${JSON.stringify(out)}`);
+        }
+        return out;
+    };
+}
+/**
+ * Resolve the `--registry` / `--projector` / `--transport-projector` /
+ * `--tool-call-driver`
+ * flags into the runner's catalog inputs. A flag that is absent yields
+ * no input, and the runner reports that catalog SKIPPED with the flag
+ * named. Every failure names the flag and the path.
+ */
+export async function loadCatalogInputs(paths) {
+    const inputs = {};
+    if (paths.registry !== undefined) {
+        let text;
+        try {
+            text = await readFile(resolve(paths.registry), 'utf8');
+        }
+        catch (err) {
+            throw new Error(`--registry ${paths.registry} could not be read: ${errorMessage(err)}`);
+        }
+        inputs.refusalRegistry = parseRegistryView(text, paths.registry);
+    }
+    if (paths.projector !== undefined) {
+        inputs.refusalProjector = await loadProjector('--projector', paths.projector, isProjectedRefusalResult);
+    }
+    if (paths.transportProjector !== undefined) {
+        inputs.transportRefusalProjector = await loadProjector('--transport-projector', paths.transportProjector, isProjectedTransportRefusal);
+    }
+    if (paths.toolCallDriver !== undefined) {
+        inputs.toolCallDriver = await loadDriver('--tool-call-driver', paths.toolCallDriver, isRawToolCallResult);
+    }
+    return inputs;
+}
 // =============================================================================
 // Entry point
 // =============================================================================
-const USAGE = `
+export const USAGE = `
 ggui-protocol-conformance — run the protocol conformance kit against a live server
 
 Usage:
@@ -113,22 +324,47 @@ Options:
                            filters the pure-function catalog rows, whose
                            names are prefixed <catalog>/<case>.
   --timeout-ms <N>         Per-fixture observation window. Default 2000.
+  --registry <file.json>   The deployment's refusal-code registry, a JSON
+                           object keyed by code (grades registry-completeness).
+  --projector <module>     ES module whose \`project(refusal)\` — a named or
+                           default export — returns the SPEC §7.1 tool result
+                           for a refusal, or null when the code has no
+                           envelope on the render-gate surface (grades
+                           refusal-envelope).
+  --transport-projector <module>
+                           ES module whose \`project(refusal)\` — named or
+                           default export — returns the endpoint's
+                           { httpStatus, error } for a refusal, or null when
+                           the code has no transport envelope (grades
+                           transport-refusal).
+  --tool-call-driver <module>
+                           ES module exporting drive(scenario) (or default):
+                           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.
   --help, -h               Show this help.
 
-Pure-function catalogs (refusal-envelope, registry-completeness):
+Pure-function catalogs (refusal-envelope, registry-completeness, transport-refusal):
   These grade an in-process function and a data table, not the wire, so
-  the CLI cannot supply them over a URL. They appear on every scorecard
-  as SKIPPED with the reason — an ungraded obligation stays visible
-  rather than vanishing. To GRADE them, call runConformance()
-  programmatically with refusalProjector / refusalRegistry.
+  a URL alone cannot reach them: the four flags above hand them their
+  inputs. A flag left out leaves its catalog on the scorecard as SKIPPED
+  with the flag named — an ungraded obligation stays visible rather
+  than vanishing. File and module paths resolve against the working
+  directory. A projector is synchronous and a tools/call driver may be async; one that throws, returns
+  undefined, or returns a non-projection is graded as a FAIL on that
+  case (exit 1) and the remaining cases are still graded — never a
+  crash. Catalog rows count as executed fixtures: a run given a
+  catalog flag can exit 0 while every wire fixture is SKIPPED, so read
+  the scorecard, not only the exit code, for a wire signal.
 
 Exit codes:
   0  — at least one fixture executed and none failed.
   1  — at least one fixture failed.
-  2  — invocation error (bad args, cannot reach server, etc.), or the
-       run executed zero fixtures (every fixture skipped) — a run that
-       proved nothing never reads as success.
+  2  — invocation error (bad args, unreadable registry or projector,
+       cannot reach server, etc.), or the run executed zero fixtures
+       (every fixture skipped) — a run that proved nothing never reads
+       as success.
 `.trimStart();
 async function main(argv) {
     let parsed;
@@ -136,7 +372,7 @@ async function main(argv) {
         parsed = parseArgs(argv);
     }
     catch (err) {
-        process.stderr.write(`error: ${String(err.message ?? err)}\n\n`);
+        process.stderr.write(`error: ${errorMessage(err)}\n\n`);
         process.stderr.write(USAGE);
         return 2;
     }
@@ -159,7 +395,16 @@ async function main(argv) {
         auth = parseAuth(parsed.auth);
     }
     catch (err) {
-        process.stderr.write(`error: ${String(err.message ?? err)}\n\n`);
+        process.stderr.write(`error: ${errorMessage(err)}\n\n`);
+        process.stderr.write(USAGE);
+        return 2;
+    }
+    let catalogInputs;
+    try {
+        catalogInputs = await loadCatalogInputs(parsed);
+    }
+    catch (err) {
+        process.stderr.write(`error: ${errorMessage(err)}\n\n`);
         process.stderr.write(USAGE);
         return 2;
     }
@@ -170,6 +415,7 @@ async function main(argv) {
         only: parsed.only !== undefined && parsed.only.length > 0 ? parsed.only : undefined,
         observationTimeoutMs: parsed.timeoutMs,
         reporter,
+        ...catalogInputs,
     });
     if (parsed.verbose) {
         const failures = formatFailures(result.failed);
@@ -201,11 +447,11 @@ function exitCodeForResult(result) {
     return 0;
 }
 // Immediately-invoked — this module IS the bin entry. Tests import
-// `parseArgs` / `parseAuth` / `exitCodeForResult` / `main` via named
-// exports without triggering the run.
+// `parseArgs` / `parseAuth` / `loadCatalogInputs` / `exitCodeForResult`
+// / `main` via named exports without triggering the run.
 if (isEntryPoint()) {
     main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
-        process.stderr.write(`fatal: ${String(err.message ?? err)}\n`);
+        process.stderr.write(`fatal: ${errorMessage(err)}\n`);
         process.exit(2);
     });
 }

package/dist/domain-error-conformance/cases/amend-unknown-session.json

@@ -0,0 +1,9 @@
+{
+    "name": "amend-unknown-session",
+    "description": "An in-place amend on an unknown sessionId: `session_not_found` leads the text; nothing was mutated.",
+    "scenario": {
+        "tool": "ggui_amend",
+        "args": { "sessionId": "render_does_not_exist", "kind": "replace", "props": {} }
+    },
+    "expect": { "code": "session_not_found" }
+}

package/dist/domain-error-conformance/cases/consume-unknown-session.json

@@ -0,0 +1,9 @@
+{
+    "name": "consume-unknown-session",
+    "description": "A sessionId no session this caller can reach carries: `session_not_found` leads the text of the consume result — the same slug for never-minted, expired, closed and cross-app ids.",
+    "scenario": {
+        "tool": "ggui_consume",
+        "args": { "sessionId": "render_does_not_exist", "timeout": 0 }
+    },
+    "expect": { "code": "session_not_found" }
+}

package/dist/domain-error-conformance/cases/emit-unknown-session.json

@@ -0,0 +1,9 @@
+{
+    "name": "emit-unknown-session",
+    "description": "A stream emit on an unknown sessionId: `session_not_found` leads the text before any channel is checked.",
+    "scenario": {
+        "tool": "ggui_emit",
+        "args": { "sessionId": "render_does_not_exist", "channel": "x", "payload": {} }
+    },
+    "expect": { "code": "session_not_found" }
+}

package/dist/domain-error-conformance/cases/get-session-unknown-session.json

@@ -0,0 +1,6 @@
+{
+    "name": "get-session-unknown-session",
+    "description": "The projection read on an unknown sessionId: `session_not_found` leads the text; no JSON-RPC error frame, no structuredContent.",
+    "scenario": { "tool": "ggui_get_session", "args": { "sessionId": "render_does_not_exist" } },
+    "expect": { "code": "session_not_found" }
+}

package/dist/domain-error-conformance/cases/render-unknown-handshake.json

@@ -0,0 +1,6 @@
+{
+    "name": "render-unknown-handshake",
+    "description": "A handshakeId nothing minted: the render fails as not found — `handshake_not_found` leads the text. No handshake is consumed, nothing is committed; the caller re-handshakes.",
+    "scenario": { "tool": "ggui_render", "args": { "handshakeId": "h_does_not_exist", "props": {} } },
+    "expect": { "code": "handshake_not_found" }
+}

package/dist/domain-error-conformance/cases/update-unknown-session.json

@@ -0,0 +1,9 @@
+{
+    "name": "update-unknown-session",
+    "description": "A history-advancing update on an unknown sessionId: `session_not_found` leads the text; nothing was mutated.",
+    "scenario": {
+        "tool": "ggui_update",
+        "args": { "sessionId": "render_does_not_exist", "kind": "replace", "props": {} }
+    },
+    "expect": { "code": "session_not_found" }
+}