@ggui-ai/protocol-conformance 0.2.0-alpha.4 → 0.3.0-rc.0

package/README.md

@@ -4,6 +4,16 @@ Conformance test kit for the ggui protocol. Ships a JSON fixture catalog + a run
 
 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.
 
+## Grading mechanisms
+
+The kit grades protocol obligations through **three mechanisms**, each matched to where the obligation is observable:
+
+1. **Path-A WS fixtures** — wire-observable behaviors graded from frames the runner collects over the live channel (acks, error frames, canonical `data` deliveries).
+2. **Pure-function catalogs** — deterministic validation obligations (the SPEC §7.7.2 gadget obligations) graded against a caller-supplied function; no host, render, or transport.
+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.
+
+A fourth 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
 
 **v1.0 is WebSocket-only.** The canonical ggui transport is WS (see SPEC §12 Transport Bindings). `TransportConfig` is shaped as an extensibly-closed union so later transports (stdio MCP, HTTP long-poll) can be added post-v1.1 without breaking the public API.
@@ -14,23 +24,26 @@ The fixture catalog spans both wire-observable claims and surface-observable cla
 
 Path-A-matchable kinds (`matchBehavior` returns `pass` / `fail`):
 
-- `bootstrap-success` — subscribe → `ack` round-trip
-- `version-mismatch` — `error` frame with `code: UPGRADE_REQUIRED`
-- `contract-error` — `_ggui:contract-error` envelope on the reserved channel
-- `stream-update` — `stream` frame on a named channel matching the declared value
+- `bootstrap-success` — subscribe → `ack` round-trip; optionally (`serverVersion: 'current'`) the ack must also advertise `payload.serverVersion` equal to the kit's compiled `PROTOCOL_SCHEMA_VERSION` — the server half of SPEC §12.2.2's version handshake
+- `version-mismatch` — `error` frame with `code: UPGRADE_REQUIRED`; the provoking client declaration travels on the fixture's `subscribe.supportedVersions` knob (`'current'` resolves to the compiled canonical, keeping fixtures evergreen across version bumps)
+- `action-ack` — the action's `ack` frame (matched by echoed `requestId`) carries a numeric `payload.sequence`, proving the action event persisted to the GguiSession's consume buffer before the ack
+- `error-frame` — `error` frame with the expected `payload.code` (e.g. `CONTRACT_VIOLATION` for an action absent from the declared actionSpec, or one whose `data` violates the declared entry's payload schema)
+- `stream-update` — canonical channel-3 delivery frame (`{type: 'data', payload: StreamEnvelope}`, SPEC §12.2) whose envelope names the declared channel and carries the declared value as its `payload` body — exact deep-equal by default, or declared-keys-subset when the fixture authors `valueMatch: 'subset'` (for payloads carrying non-deterministic fields like generated ids)
 - `no-op` — silence after input dispatch
-- `observability-event` — `wired-tool-invoked` and `contract-error-emitted` arms (the WS evidence the protocol-and-contract bar mandates a conformant host mirror-emit on)
+
+One kind is neither Path A nor Path B: `session-state` is graded by the **runner**, not the frame matcher — a post-observation-window read-back via `ConformanceHost.readSessionField()` (mechanism 3 above). `matchBehavior` returns `unmatchable-on-ws` for it, because frames cannot prove state.
 
 Path-B-only kinds (`matchBehavior` returns `unmatchable-on-ws` → runner records SKIP):
 
 - `bootstrap-failure` — fault surface is the host's bootstrap-fetch + `ui/initialize` postMessage round-trip; `renderer-url-override` / `ui-initialize-response-override` setup directives are MCP-Apps-host concerns, not WS server concerns.
 - `props-update` — assertion is on rendered DOM after `_ggui:props` is emitted; matchable on WS only as "frame was emitted", not as "DOM reflects it".
-- Future `observability-event` arms beyond the two above (e.g. `schema-version-mismatch`, `subscribe-failed`).
 
-A Path-B browser-host harness drives these fixtures via Playwright + `page.route()` fault injection + DOM assertion. A future packaged browser-host adapter will fold that capability into the kit so third-party adopters don't reimplement it.
+The Path-B driver is not yet packaged — no browser-host harness ships with the kit today, so Path-B fixtures skip wherever the kit runs. A future packaged browser-host adapter will fold that capability into the kit so third-party adopters don't reimplement it.
 
 The partition is intentional: Path-A FAILs are vendor-neutrality bugs the server owns; Path-B SKIPs are not fails — they are claims a different driver is responsible for.
 
+One declared grading gap on the action loop: `action-ack` proves the append half of the consume-buffer contract; the retrieval half (the agent draining the buffer via `ggui_consume`) is an MCP tool call a WS-only runner cannot drive. Grading it needs an MCP-binding driver — a future kit surface, not a weaker WS assertion.
+
 ## Pure-function conformance catalogs
 
 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.
@@ -38,7 +51,7 @@ The behavioral fixture catalog above asserts what an implementation _does_ over
 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. Three 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)` pairs the push-time gadget registry gate MUST accept / reject, and with which precise reject code (`gadget_not_registered` / `gadget_package_mismatch`).
+- **`@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`).
 - **`@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).
 
 ```ts
@@ -49,8 +62,8 @@ import { runResolutionConformance } from "@ggui-ai/protocol-conformance/resoluti
 const schema = runSchemaConformance((clientCapabilities) =>
   myGadgetWireParser.isValid(clientCapabilities)
 );
-const gate = runRegistrationConformance((contract, appGadgets) =>
-  myGadgetGate(contract, appGadgets)
+const gate = runRegistrationConformance((contract, appGadgets, appPublicEnv) =>
+  myGadgetGate(contract, appGadgets, appPublicEnv)
 );
 const urls = runResolutionConformance((entry) => myGadgetUrlResolver(entry));
 
@@ -61,7 +74,7 @@ if (schema.failed.length + gate.failed.length + urls.failed.length > 0) {
 
 The `schema-conformance` meta-test binds its catalog to the live `@ggui-ai/protocol` `clientCapabilitiesSpecSchema` — a drift-catch if the wire schema diverges from the §7.7.2 obligations the catalog freezes. The `registration-conformance` and `resolution-conformance` meta-tests verify catalog coherence against faithful in-test implementations (the kit stays vendor-neutral — it does not depend on a server implementation); grading the _shipping_ gate / resolver is an implementation-side test that drives the corresponding runner.
 
-## Public API (target)
+## Public API
 
 ```ts
 import { runConformance } from "@ggui-ai/protocol-conformance";
@@ -71,18 +84,24 @@ const result = await runConformance({
   auth: { kind: "bearer", token: process.env.TOKEN! },
 });
 
-if (result.failed.length > 0) {
+// 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) {
   process.exit(1);
 }
 ```
 
+`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).
+
 CLI equivalent:
 
 ```
 npx @ggui-ai/protocol-conformance --url ws://localhost:3000/ws --auth bearer:$TOKEN
 ```
 
-Full adoption guide + fixture-to-contract mapping table land with the fixture-extraction commit.
+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).
+
+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,4 +1,5 @@
 #!/usr/bin/env node
+import { type ConformanceResult } from './run-conformance.js';
 import type { AuthConfig } from './types.js';
 interface ParsedArgs {
     readonly url?: string;
@@ -11,5 +12,14 @@ interface ParsedArgs {
 declare function parseArgs(argv: readonly string[]): ParsedArgs;
 declare function parseAuth(spec: string): AuthConfig;
 declare function main(argv: readonly string[]): Promise<number>;
-export { main, parseArgs, parseAuth };
+/**
+ * Map a {@link ConformanceResult} to the CLI exit code:
+ *   - `1` — at least one fixture failed.
+ *   - `2` — zero fixtures executed (every fixture skipped). 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.
+ */
+declare function exitCodeForResult(result: ConformanceResult): 0 | 1 | 2;
+export { exitCodeForResult, main, parseArgs, parseAuth };
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA4BA,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;AA+BD,iBAAe,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAoD5D;AA+BD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC"}
+{"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;AAoCD,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"}

package/dist/cli.js

@@ -8,21 +8,25 @@
  *       --url http://localhost:3000 \
  *       --auth bearer:TOKEN
  *
- * Exits with code 0 if every fixture passed OR skipped; exits 1 if
- * ANY fixture failed. Skips are not failures — an implementation may
- * legitimately not provide every `ConformanceHost` directive in
- * v1.0. Operators who want skip-is-failure semantics can pair
- * `--require-host` (future) with a host that implements every known
- * directive.
+ * Exits 0 only when at least one fixture executed AND none failed.
+ * Exits 1 if ANY fixture failed. Exits 2 on invocation errors AND
+ * when the run executed zero fixtures (everything skipped) — a
+ * conformance run that proved nothing must not read as success in
+ * CI. Individual skips are still not failures — an implementation
+ * may legitimately not provide every `ConformanceHost` directive in
+ * v1.0 — but a run that is ALL skips carries no 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. To get
- * real pass/fail signal against an implementation, consumers call
- * `runConformance({ host: myImpl })` programmatically. The CLI is the
- * lowest-friction entry point for a smoke check, and for CI jobs where
- * the server under test is exercised directly over the wire via a
- * subprocess harness rather than a `ConformanceHost` injection.
+ * `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.
  */
 import { createDefaultReporter, formatFailures, formatSkips } from './reporter.js';
 import { runConformance } from './run-conformance.js';
@@ -95,8 +99,11 @@ Usage:
   ggui-protocol-conformance --url <URL> --auth <kind:value> [options]
 
 Required:
-  --url <URL>              Base URL of the server (http://… or https://…).
-                           The runner derives ws://…/ws from this.
+  --url <URL>              Server URL. A bare origin (http://… or ws://…
+                           without a path) gets the default live-channel
+                           path /ws appended; a URL that already carries
+                           a path (e.g. ws://host:3000/ws) is used as
+                           given. http(s) schemes derive ws(s).
   --auth <kind:value>      Auth carried on the WS upgrade.
                              bearer:TOKEN          — Authorization header
                              session-cookie:COOKIE — Cookie header
@@ -108,9 +115,11 @@ Options:
   --help, -h               Show this help.
 
 Exit codes:
-  0  — all fixtures passed or skipped.
+  0  — at least one fixture executed and none failed.
   1  — at least one fixture failed.
-  2  — invocation error (bad args, cannot reach server, etc.).
+  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.
 `.trimStart();
 async function main(argv) {
     let parsed;
@@ -161,11 +170,30 @@ async function main(argv) {
         if (skips.length > 0)
             process.stdout.write(`${skips}\n`);
     }
-    return result.failed.length > 0 ? 1 : 0;
+    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`);
+    }
+    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
+ *     that graded nothing carries no conformance signal and must not
+ *     read as success in CI.
+ *   - `0` — at least one fixture executed and none failed.
+ */
+function exitCodeForResult(result) {
+    if (result.failed.length > 0)
+        return 1;
+    if (result.passed.length === 0)
+        return 2;
+    return 0;
 }
 // Immediately-invoked — this module IS the bin entry. Tests import
-// `parseArgs` / `parseAuth` / `main` via named exports without
-// triggering the run.
+// `parseArgs` / `parseAuth` / `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`);
@@ -190,4 +218,4 @@ function isEntryPoint() {
         return false;
     }
 }
-export { main, parseArgs, parseAuth };
+export { exitCodeForResult, main, parseArgs, parseAuth };

package/dist/conformance-host.d.ts

@@ -11,113 +11,96 @@
  *
  * When a host IS provided, the runner calls `dispatchSetup()` for
  * every step before driving the fixture's `inputEnvelope`, then
- * `dispatchTeardown()` for every step after the assertion. Unknown
- * `kind` values MUST throw so unimplemented directives surface as a
+ * `dispatchTeardown()` for every step after the assertion. A host
+ * that does not implement a directive MUST throw so it surfaces as a
  * test SKIP with a clear "host does not implement X" reason — never
  * a silent pass.
  *
- * ## Extensibly-closed
+ * ## Closed vocabulary
  *
- * The concrete step vocabulary below mirrors `./types`' vocabulary
- * but is re-exported here as a host-facing narrower form:
- *   - Every arm carries the full semantic payload (not the JSON-
- *     loader's `unknown`-fields view).
- *   - The tail `(Record<string, unknown> & { readonly kind: string & {} })`
- *     catches fixture-JSON directives the host hasn't wired — the host
- *     returns by throwing, the runner maps it to a skip.
- *
- * Third-party hosts MAY extend either union with additional arms by
- * augmenting the declaration in their own module. v1.0 of the kit
- * does not require exhaustive coverage — it requires *honest*
- * coverage: either implement the directive OR throw, never silently
- * succeed on an unknown kind.
+ * Both step unions here are CLOSED — they carry exactly the directive
+ * vocabulary the shipped fixture catalog authors, with the same field
+ * names the fixture JSON uses. The runner validates every authored
+ * directive against the JSON-authoring union in `./types` before
+ * dispatch (unknown / malformed directives are fixture-authoring
+ * errors, thrown loudly, never dispatched), so a host only ever
+ * receives shape-valid steps of a known kind. Hosts therefore need
+ * exactly two behaviors per directive: implement it, or throw
+ * "not implemented" — never silently succeed.
  *
  * ## Relation to `./types`
  *
- * `./types` defines the JSON-authoring surface: every directive has
- * optional-by-default fields so JSON authors don't have to think
- * about shape. This module defines the *runtime* surface: once the
- * loader has validated a directive, the host receives a narrowed
- * form. The two are intentionally parallel but not identical — JSON
- * loaders accept what the author wrote; hosts receive what the
- * runner confirmed is shape-valid.
+ * `./types` defines the JSON-authoring surface (discriminated on
+ * `type`); this module defines the *runtime* surface the host
+ * receives (discriminated on `kind`). The two are intentionally
+ * parallel: same directives, same field names, different
+ * discriminator key.
  */
+import type { ActionSpecEntryDecl } from './types.js';
 /**
  * Setup directive the host dispatches BEFORE a fixture's input
  * envelope drives the system under test.
  *
- * Extensibly-closed: a host that receives a `kind` it doesn't
- * recognize MUST throw `Error('conformance-host: unknown setup kind: <kind>')`
- * so the runner records the fixture as SKIPPED with that reason —
- * never silently succeed.
+ * Closed union — the runner validates fixture-authored directives
+ * before dispatch, so only these five kinds ever reach a host. A host
+ * that does not implement one of them MUST throw (e.g.
+ * `Error('host does not implement renderer-url-override')`) so the
+ * runner records the fixture as SKIPPED with that reason — never
+ * silently succeed.
  */
-export type SetupStep = CreateRenderSetup | RegisterToolSetup | RegisterActionSpecSetup | EmitEnvelopeSetup | RendererUrlOverrideSetup | UiInitializeResponseOverrideSetup | ServerVersionOverrideSetup | UnknownSetupStep;
-export interface CreateRenderSetup {
-    readonly kind: 'create-render';
-    readonly renderId: string;
+export type SetupStep = CreateGguiSessionSetup | RendererUrlOverrideSetup | ServerVersionOverrideSetup | UiInitializeResponseOverrideSetup | EmitEnvelopeSetup;
+export interface CreateGguiSessionSetup {
+    readonly kind: 'create-session';
+    readonly sessionId: string;
     readonly appId?: string;
+    /**
+     * Optional actionSpec declared on the GguiSession at creation. See
+     * `CreateGguiSessionStep.actionSpec` in `./types` — hosts that
+     * receive the field MUST install it as the render's declared-action
+     * contract before the fixture's input envelope is dispatched.
+     */
+    readonly actionSpec?: Readonly<Record<string, ActionSpecEntryDecl>>;
 }
-/**
- * Register a tool on the render by symbolic handler name. Known
- * handlers the reference implementation supports:
- *   - `'echo'`     — returns `{received: args}`.
- *   - `'throw'`    — rejects with `Error('tool_threw_for_fixture')`.
- *   - `'timeout'`  — never resolves; runner times out per policy.
- *   - `'malformed'`— returns `{wrong:'shape'}` to exercise
- *                    `SCHEMA_VIOLATION`.
- */
-export interface RegisterToolSetup {
-    readonly kind: 'register-tool';
-    readonly name: string;
-    readonly handler: 'echo' | 'throw' | 'timeout' | 'malformed' | (string & {});
-}
-export interface RegisterActionSpecSetup {
-    readonly kind: 'register-actionspec';
-    readonly name: string;
-    readonly tool: string;
-}
-export interface EmitEnvelopeSetup {
-    readonly kind: 'emit-envelope';
-    readonly channel: string;
-    readonly payload: unknown;
-}
+/** Runtime form of `RendererUrlOverrideStep` (see `./types`). */
 export interface RendererUrlOverrideSetup {
     readonly kind: 'renderer-url-override';
+    readonly sessionId: string;
     readonly url: string;
 }
+/** Runtime form of `ServerVersionOverrideStep` (see `./types`). */
+export interface ServerVersionOverrideSetup {
+    readonly kind: 'server-version-override';
+    readonly sessionId: string;
+    readonly advertiseVersion: string;
+}
+/** Runtime form of `UiInitializeResponseOverrideStep` (see `./types`). */
 export interface UiInitializeResponseOverrideSetup {
     readonly kind: 'ui-initialize-response-override';
-    readonly response: unknown;
+    readonly sessionId: string;
+    readonly override: unknown;
 }
-export interface ServerVersionOverrideSetup {
-    readonly kind: 'server-version-override';
-    readonly version: string;
+/** Runtime form of `EmitEnvelopeStep` (see `./types`). */
+export interface EmitEnvelopeSetup {
+    readonly kind: 'emit-envelope';
+    readonly channel: string;
+    readonly payload: unknown;
 }
 /**
- * Future-compat catch. A host that reaches this arm MUST throw rather
- * than return silently — the runner interprets the throw as a skip
- * with the error message as the reason.
+ * Closed-and-empty, mirroring `./types`' `TeardownStep`: no teardown
+ * vocabulary exists in this kit version (renders decay via TTL), so
+ * `dispatchTeardown` is never invoked today. The slot stays so future
+ * cleanup directives land additively as union arms.
  */
-export type UnknownSetupStep = Record<string, unknown> & {
-    readonly kind: string & {};
-};
-export type TeardownStep = UnregisterToolTeardown | UnknownTeardownStep;
-export interface UnregisterToolTeardown {
-    readonly kind: 'unregister-tool';
-    readonly name: string;
-}
-export type UnknownTeardownStep = Record<string, unknown> & {
-    readonly kind: string & {};
-};
+export type TeardownStep = never;
 /**
  * Adapter the implementation under test provides to the runner. An
  * implementation MAY:
  *
  *   - Implement every directive the kit authors (full coverage — the
  *     reference `@ggui-ai/mcp-server`-backed host target).
- *   - Implement a subset + throw on unknown kinds (partial coverage
- *     — the kit records unimplemented directives as SKIPPED rather
- *     than failed).
+ *   - Implement a subset + throw on the rest (partial coverage — the
+ *     kit records unimplemented directives as SKIPPED rather than
+ *     failed).
  *   - Not be provided at all (the runner drops every fixture with a
  *     non-empty `setup` or `teardown` as skip-with-reason).
  *
@@ -147,5 +130,27 @@ export interface ConformanceHost {
      * the cleanup gap without corrupting the pass/fail tally.
      */
     dispatchTeardown(step: TeardownStep): Promise<void>;
+    /**
+     * Read one field off a live GguiSession — the introspection seam a
+     * `session-state` expectation (`./types`' `SessionStateBehavior`)
+     * grades against. The runner calls this AFTER the fixture's input
+     * envelope has been dispatched and the observation window has
+     * elapsed, then deep-equals the result against the fixture's
+     * `expected`.
+     *
+     * Optional. A host that does not provide it makes every
+     * `session-state` fixture SKIP — the kit cannot honestly grade a
+     * stateful obligation it has no way to observe. Throwing signals
+     * "this field is not exposed" and the runner records a SKIP with
+     * the error's message; a throw is never treated as a pass or a
+     * fail — a host that cannot read state cannot grade it.
+     *
+     * Honest-grade contract: the returned value MUST reflect the
+     * GguiSession's true post-dispatch state. A host that fabricates a
+     * passing value is cheating its own conformance audit — that is the
+     * implementer's integrity to keep, exactly as with every other
+     * host-mediated directive.
+     */
+    readSessionField?(sessionId: string, field: string): Promise<unknown>;
 }
 //# sourceMappingURL=conformance-host.d.ts.map

package/dist/conformance-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conformance-host.d.ts","sourceRoot":"","sources":["../src/conformance-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAMH;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GACjB,iBAAiB,GACjB,iBAAiB,GACjB,uBAAuB,GACvB,iBAAiB,GACjB,wBAAwB,GACxB,iCAAiC,GACjC,0BAA0B,GAC1B,gBAAgB,CAAC;AAErB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;CAC9E;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC;IACjD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,EAAE,CAAC;CAC5B,CAAC;AAMF,MAAM,MAAM,YAAY,GACpB,sBAAsB,GACtB,mBAAmB,CAAC;AAExB,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,EAAE,CAAC;CAC5B,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C;;;;;OAKG;IACH,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD"}
+{"version":3,"file":"conformance-host.d.ts","sourceRoot":"","sources":["../src/conformance-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAMtD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,SAAS,GACjB,sBAAsB,GACtB,wBAAwB,GACxB,0BAA0B,GAC1B,iCAAiC,GACjC,iBAAiB,CAAC;AAEtB,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC;CACrE;AAED,iEAAiE;AACjE,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,mEAAmE;AACnE,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,0EAA0E;AAC1E,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,0DAA0D;AAC1D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAMD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC;AAMjC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C;;;;;OAKG;IACH,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,gBAAgB,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACvE"}

package/dist/conformance-host.js

@@ -1,45 +1 @@
-/**
- * `ConformanceHost` — the seam between the kit's authored fixtures
- * and the implementation under test.
- *
- * Most fixtures declare `setup` / `teardown` directives (see
- * {@link SetupStep} / {@link TeardownStep} in `./types`) that the host
- * dispatches against its live server. v1.0 of the kit does NOT
- * require implementations to ship a host — fixtures that need setup
- * directives skip cleanly when `runConformance()` is called without
- * a `host`.
- *
- * When a host IS provided, the runner calls `dispatchSetup()` for
- * every step before driving the fixture's `inputEnvelope`, then
- * `dispatchTeardown()` for every step after the assertion. Unknown
- * `kind` values MUST throw so unimplemented directives surface as a
- * test SKIP with a clear "host does not implement X" reason — never
- * a silent pass.
- *
- * ## Extensibly-closed
- *
- * The concrete step vocabulary below mirrors `./types`' vocabulary
- * but is re-exported here as a host-facing narrower form:
- *   - Every arm carries the full semantic payload (not the JSON-
- *     loader's `unknown`-fields view).
- *   - The tail `(Record<string, unknown> & { readonly kind: string & {} })`
- *     catches fixture-JSON directives the host hasn't wired — the host
- *     returns by throwing, the runner maps it to a skip.
- *
- * Third-party hosts MAY extend either union with additional arms by
- * augmenting the declaration in their own module. v1.0 of the kit
- * does not require exhaustive coverage — it requires *honest*
- * coverage: either implement the directive OR throw, never silently
- * succeed on an unknown kind.
- *
- * ## Relation to `./types`
- *
- * `./types` defines the JSON-authoring surface: every directive has
- * optional-by-default fields so JSON authors don't have to think
- * about shape. This module defines the *runtime* surface: once the
- * loader has validated a directive, the host receives a narrowed
- * form. The two are intentionally parallel but not identical — JSON
- * loaders accept what the author wrote; hosts receive what the
- * runner confirmed is shape-valid.
- */
 export {};

package/dist/fixtures/bootstrap-protocol/bootstrap-bundle-fetch-failed.json

@@ -3,16 +3,16 @@
     "description": "Thin shell reads a valid `_meta.ggui.bootstrap.runtimeUrl` but the `<script src>` errors (network failure / 404 / CSP reject). Shell emits `postMessage({type:'ggui:bootstrap-failed', reason:'BUNDLE_FETCH_FAILED', message})` to the parent. No WS opens.",
     "skipReason": null,
     "setup": [
-        { "type": "create-render", "renderId": "ck-bundle-fetch-failed-1" },
+        { "type": "create-session", "sessionId": "ck-bundle-fetch-failed-1" },
         {
             "type": "renderer-url-override",
-            "renderId": "ck-bundle-fetch-failed-1",
+            "sessionId": "ck-bundle-fetch-failed-1",
             "url": "http://127.0.0.1:1/does-not-exist.js"
         }
     ],
     "inputEnvelope": {
         "type": "render",
-        "renderId": "ck-bundle-fetch-failed-1",
+        "sessionId": "ck-bundle-fetch-failed-1",
         "resource": {
             "uri": "ui://ggui/render"
         }

package/dist/fixtures/bootstrap-protocol/bootstrap-meta-missing.json

@@ -3,10 +3,10 @@
     "description": "Host's `ui/initialize` response returns a tool-output without `_meta.ggui.bootstrap` (or missing the `runtimeUrl` field). Thin shell emits `postMessage({type:'ggui:bootstrap-failed', reason:'BOOTSTRAP_META_MISSING', message})` to the parent. No WS connection opens — live-channel envelopes are out of scope pre-handshake.",
     "skipReason": null,
     "setup": [
-        { "type": "create-render", "renderId": "ck-bootstrap-meta-missing-1" },
+        { "type": "create-session", "sessionId": "ck-bootstrap-meta-missing-1" },
         {
             "type": "ui-initialize-response-override",
-            "renderId": "ck-bootstrap-meta-missing-1",
+            "sessionId": "ck-bootstrap-meta-missing-1",
             "override": {
                 "toolOutput": {
                     "_meta": {
@@ -18,7 +18,7 @@
     ],
     "inputEnvelope": {
         "type": "render",
-        "renderId": "ck-bootstrap-meta-missing-1",
+        "sessionId": "ck-bootstrap-meta-missing-1",
         "resource": {
             "uri": "ui://ggui/render"
         }

package/dist/fixtures/bootstrap-protocol/bootstrap-success.json

@@ -1,11 +1,11 @@
 {
     "name": "bootstrap-success",
-    "description": "Happy-path boot: host reads `_meta.ui.resourceUri`, fetches `ui://ggui/render`, the thin shell loads the renderer bundle, `ui/initialize` returns valid `_meta.ggui.bootstrap.{wsUrl, token, renderId, appId, runtimeUrl}`, WS handshake succeeds, the render mounts with `data-ggui-code-ready=\"true\"`. No bootstrap-failed postMessage, no contract-error, no upgrade-required.",
+    "description": "Happy-path boot: host reads `_meta.ui.resourceUri`, fetches `ui://ggui/render`, the thin shell loads the renderer bundle, `ui/initialize` returns valid `_meta.ggui.bootstrap.{wsUrl, token, sessionId, appId, runtimeUrl}`, WS handshake succeeds, the render mounts with `data-ggui-code-ready=\"true\"`. No bootstrap-failed postMessage, no upgrade-required.",
     "skipReason": null,
-    "setup": [{ "type": "create-render", "renderId": "ck-bootstrap-success-1" }],
+    "setup": [{ "type": "create-session", "sessionId": "ck-bootstrap-success-1" }],
     "inputEnvelope": {
         "type": "render",
-        "renderId": "ck-bootstrap-success-1",
+        "sessionId": "ck-bootstrap-success-1",
         "resource": {
             "uri": "ui://ggui/render"
         }

package/dist/fixtures/consume-buffer/action-ack-sequence.json

@@ -0,0 +1,28 @@
+{
+    "name": "action-ack-sequence",
+    "description": "A declared action dispatched on the live channel persists to the GguiSession's consume buffer before the ack: the server appends the envelope as an event, assigns a monotonic sequence, and the ack frame echoes the action's requestId carrying `payload.sequence`. Proves the persistence half of the single action-routing model — the agent drains the buffer via `ggui_consume` on its next turn (an MCP tool call outside this WS kit's observation window).",
+    "skipReason": null,
+    "setup": [
+        {
+            "type": "create-session",
+            "sessionId": "ck-action-ack-1",
+            "actionSpec": { "toggleTask": {} }
+        }
+    ],
+    "inputEnvelope": {
+        "type": "action",
+        "requestId": "ck-action-ack-1-req",
+        "payload": {
+            "sessionId": "ck-action-ack-1",
+            "type": "data:submit",
+            "payload": {
+                "action": "toggleTask",
+                "data": { "id": "seed-1" }
+            }
+        }
+    },
+    "expectedBehavior": {
+        "kind": "action-ack",
+        "requestId": "ck-action-ack-1-req"
+    }
+}