@ggui-ai/protocol-conformance 0.14.0 → 0.16.0

package/dist/run-conformance.js

@@ -47,7 +47,8 @@
  *         loop is empty today.)
  *      l. Record the outcome via reporter + accumulate in result.
  *   3. Fold in the PURE-FUNCTION catalogs (ggui#786) —
- *      `refusal-envelope` and `registry-completeness`. They grade a
+ *      `refusal-envelope`, `registry-completeness`, `transport-refusal`,
+ *      `domain-error` and `theme-binding` (ggui#987). They grade a
  *      caller-supplied projector / registry rather than the wire, so
  *      they need no transport; when the caller supplies neither, their
  *      rows are reported SKIPPED with that reason so an ungraded
@@ -65,15 +66,23 @@ import { behaviorIs, deepEqual, matchBehavior } from './match-behavior.js';
 import { openWsTransport } from './ws-transport.js';
 import { refusalEnvelopeCases, runRefusalEnvelopeConformance, } from './refusal-envelope-conformance/index.js';
 import { registryCompletenessPins, runRegistryCompletenessConformance, } from './registry-completeness/index.js';
+import { runTransportRefusalConformance, transportRefusalCases, } from './transport-refusal-conformance/index.js';
+import { runThemeBindingConformance } from './theme-binding-conformance/index.js';
+import { domainErrorCases, runDomainErrorConformance, } from './domain-error-conformance/index.js';
 /**
- * Row-name prefixes for the PURE-FUNCTION catalogs the runner folds
- * into a run. Prefixed so a catalog row can never collide with a
+ * Row-name prefixes for the catalogs the runner folds into a run beside
+ * the WebSocket fixtures: three grade an in-process function or a data
+ * table; `domain-error` (ggui#880) drives live `tools/call` scenarios
+ * through an adopter-supplied driver. Prefixed so a catalog row can never collide with a
  * WebSocket fixture name, and so the reporter can group them without a
  * second registry of names.
  */
 export const PURE_FUNCTION_CATALOG_SLUGS = [
     'refusal-envelope',
     'registry-completeness',
+    'transport-refusal',
+    'domain-error',
+    'theme-binding',
 ];
 // =============================================================================
 // Runner
@@ -111,7 +120,7 @@ export async function runConformance(config) {
                 break;
         }
     }
-    runPureFunctionCatalogs(config, reporter, { passed, failed, skipped });
+    await runPureFunctionCatalogs(config, reporter, { passed, failed, skipped });
     const result = {
         passed,
         failed,
@@ -136,7 +145,7 @@ export async function runConformance(config) {
  * absent input produces a SKIP row naming what to supply rather than
  * nothing at all.
  */
-function runPureFunctionCatalogs(config, reporter, buckets) {
+async function runPureFunctionCatalogs(config, reporter, buckets) {
     const only = config.only;
     const wanted = (name) => only === undefined || only.length === 0 || only.includes(name);
     const pass = (name) => {
@@ -161,7 +170,7 @@ function runPureFunctionCatalogs(config, reporter, buckets) {
     const projector = config.refusalProjector;
     if (projector === undefined) {
         for (const testCase of refusalEnvelopeCases) {
-            skip(`refusal-envelope/${testCase.name}`, 'no `refusalProjector` supplied — pass one to runConformance() to grade SPEC §7.1\u2019s refused arm');
+            skip(`refusal-envelope/${testCase.name}`, 'no `refusalProjector` supplied — pass one to runConformance(), or `--projector <module>` on the CLI, to grade SPEC §7.1\u2019s refused arm');
         }
     }
     else {
@@ -178,11 +187,59 @@ function runPureFunctionCatalogs(config, reporter, buckets) {
             });
         }
     }
+    // ── transport-refusal (ggui#825) ──
+    const endpointProjector = config.transportRefusalProjector;
+    if (endpointProjector === undefined) {
+        for (const testCase of transportRefusalCases) {
+            skip(`transport-refusal/${testCase.name}`, 'no `transportRefusalProjector` supplied — pass one to runConformance(), or `--transport-projector <module>` on the CLI, to grade the endpoint-level refusal (SPEC §7.1, mcp-endpoint surface)');
+        }
+    }
+    else {
+        const endpoint = runTransportRefusalConformance(endpointProjector);
+        for (const name of endpoint.passed)
+            pass(`transport-refusal/${name}`);
+        for (const mismatch of endpoint.failed) {
+            fail({
+                name: `transport-refusal/${mismatch.name}`,
+                criterion: 'endpoint-level refusal envelope (SPEC §7.1, mcp-endpoint surface)',
+                expected: mismatch.expected,
+                received: mismatch.actual,
+                message: 'the projected endpoint refusal does not match the catalog case',
+            });
+        }
+    }
+    // ── domain-error (ggui#880) ──
+    const toolCallDriver = config.toolCallDriver;
+    if (toolCallDriver === undefined) {
+        for (const testCase of domainErrorCases) {
+            skip(`domain-error/${testCase.name}`, 'no `toolCallDriver` supplied — pass one to runConformance(), or `--tool-call-driver <module>` on the CLI, to grade SPEC §7.9\u2019s Plane-2 wire text');
+        }
+    }
+    else {
+        // A live driver is real calls: drive only the rows `only` selects.
+        const selected = domainErrorCases.filter((testCase) => wanted(`domain-error/${testCase.name}`));
+        const graded = selected.length === 0
+            ? { passed: [], failed: [], skipped: [] }
+            : await runDomainErrorConformance(toolCallDriver, { cases: selected });
+        for (const name of graded.passed)
+            pass(`domain-error/${name}`);
+        for (const skipped of graded.skipped)
+            skip(`domain-error/${skipped.name}`, skipped.reason);
+        for (const mismatch of graded.failed) {
+            fail({
+                name: `domain-error/${mismatch.name}`,
+                criterion: `Plane-2 wire text (SPEC §7.9): ${mismatch.criterion}`,
+                expected: mismatch.expected,
+                received: mismatch.actual,
+                message: 'the raw tools/call result does not carry the registered slug as the leading token of its text',
+            });
+        }
+    }
     // ── registry-completeness ──
     const registry = config.refusalRegistry;
     if (registry === undefined) {
         for (const pin of registryCompletenessPins) {
-            skip(`registry-completeness/${pin.name}`, 'no `refusalRegistry` supplied — pass the deployment\u2019s refusal-code registry to runConformance() to grade it');
+            skip(`registry-completeness/${pin.name}`, 'no `refusalRegistry` supplied — pass the deployment\u2019s refusal-code registry to runConformance(), or `--registry <file.json>` on the CLI, to grade it');
         }
     }
     else {
@@ -199,6 +256,26 @@ function runPureFunctionCatalogs(config, reporter, buckets) {
             });
         }
     }
+    // ── theme-binding (ggui#987) ──
+    // The theming wave's arbiter: graded against the protocol's own functions
+    // (`appThemeSchema`, `effectiveThemeMode`, `canonicalOverlayHash`), so
+    // there is no adopter input to supply and no reason to skip — every run
+    // reports it. `only` still selects rows.
+    for (const graded of await runThemeBindingConformance()) {
+        const name = `theme-binding/${graded.name}`;
+        if (graded.pass) {
+            pass(name);
+        }
+        else {
+            fail({
+                name,
+                criterion: 'theme binding (SPEC "Theme binding — the normative total order", ggui#987)',
+                expected: 'the case\u2019s expectation',
+                received: graded.detail,
+                message: graded.detail,
+            });
+        }
+    }
 }
 async function runOneFixture(fixture, config, _reporter) {
     const fixtureStarted = Date.now();
@@ -661,8 +738,8 @@ function slugToCriterion(slug) {
             return 'SPEC §4.4 reserved-channel authority';
         case 'schema-version-handshake':
             return 'Protocol #3 version negotiation';
-        case 'subscribe-tenancy':
-            return 'SPEC §12.2 subscribe tenancy — appId MUST match the bound app (§12.2.3 APP_MISMATCH)';
+        case 'subscribe-app-scope':
+            return 'SPEC §12.2 subscribe app scope — appId MUST match the bound app (§12.2.3 APP_MISMATCH)';
         default:
             return slug;
     }

package/dist/theme-binding-conformance/cases/app-theme-v1-base.json

@@ -0,0 +1,18 @@
+{
+    "name": "app-theme-v1-base",
+    "description": "A v1 overlay carrying a registered `base` ladder is REFUSED since ggui#987 (D2 = B): the registration tier and `base` are gone. Accepted before #987 (promoted, then failed \u2014 the \u00a71.1 receipt).",
+    "theme": {
+        "mode": "dark",
+        "cssVariables": {},
+        "base": {
+            "documentHash": "0000000000000000000000000000000000000000000000000000000000000000",
+            "light": {
+                "--ggui-color-primary-500": "#3355ff"
+            },
+            "dark": {
+                "--ggui-color-primary-500": "#99aaff"
+            }
+        }
+    },
+    "expect": "refused"
+}

package/dist/theme-binding-conformance/cases/app-theme-v1-one-palette.json

@@ -0,0 +1,11 @@
+{
+    "name": "app-theme-v1-one-palette",
+    "description": "The v1 overlay wire \u2014 a pinned mode and ONE cssVariables palette \u2014 is REFUSED since ggui#987: an overlay that could not follow the host's mode is not accepted; both projections are required. Accepted before #987 (promoted, then failed \u2014 the \u00a71.1 receipt).",
+    "theme": {
+        "mode": "light",
+        "cssVariables": {
+            "--ggui-color-primary-500": "#3355ff"
+        }
+    },
+    "expect": "refused"
+}

package/dist/theme-binding-conformance/cases/app-theme-v2-accepted.json

@@ -0,0 +1,18 @@
+{
+    "name": "app-theme-v2-accepted",
+    "description": "The v2 overlay: both projections, the attestation, an optional default mode and a label. Accepted.",
+    "theme": {
+        "overlayHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "overlays": {
+            "light": {
+                "--ggui-color-primary-500": "#3355ff"
+            },
+            "dark": {
+                "--ggui-color-primary-500": "#99aaff"
+            }
+        },
+        "mode": "light",
+        "name": "ocean"
+    },
+    "expect": "accepted"
+}

package/dist/theme-binding-conformance/cases/app-theme-v2-keyframes-accepted.json

@@ -0,0 +1,16 @@
+{
+    "name": "app-theme-v2-keyframes-accepted",
+    "description": "Per-mode keyframes text that is exactly `@keyframes <ident> { … }` blocks (two blocks, a comment, frame selectors of every kind) is ACCEPTED by appThemeSchema — the slot carries what the card injects verbatim after the variables (ggui#987 §3.3, follower D).",
+    "theme": {
+        "overlays": {
+            "light": { "--ggui-color-primary-500": "#3355ff" },
+            "dark": { "--ggui-color-primary-500": "#99aaff" }
+        },
+        "overlayHash": "0000000000000000000000000000000000000000000000000000000000000000",
+        "keyframes": {
+            "light": "/* entrance */ @keyframes entrance { 0% { opacity: 0; transform: translateY(4px) } 100% { opacity: 1; transform: none } }\n@keyframes accent-pulse{0%,100%{opacity:1}50%{opacity:.7}}",
+            "dark": "@keyframes spin { from { transform: rotate(0deg) } to { transform: rotate(360deg) } }"
+        }
+    },
+    "expect": "accepted"
+}

package/dist/theme-binding-conformance/cases/app-theme-v2-keyframes-not-keyframes.json

@@ -0,0 +1,15 @@
+{
+    "name": "app-theme-v2-keyframes-not-keyframes",
+    "description": "Keyframes text that carries anything other than `@keyframes` blocks — here a bare `body { … }` rule after a valid block — is REFUSED by appThemeSchema: the slot is bounded to what it is for, so the theme principal cannot ship arbitrary same-document CSS through it (ggui#987 §3.4, follower D).",
+    "theme": {
+        "overlays": {
+            "light": { "--ggui-color-primary-500": "#3355ff" },
+            "dark": { "--ggui-color-primary-500": "#99aaff" }
+        },
+        "overlayHash": "0000000000000000000000000000000000000000000000000000000000000000",
+        "keyframes": {
+            "light": "@keyframes spin { to { transform: rotate(360deg) } } body { display: none }"
+        }
+    },
+    "expect": "refused"
+}

package/dist/theme-binding-conformance/cases/app-theme-v2-label-too-long.json

@@ -0,0 +1,17 @@
+{
+    "name": "app-theme-v2-label-too-long",
+    "description": "A stamped label carrying a FULL sha256 after the prefix is 77 chars and exceeds appThemeSchema's 64-char `name` cap \u2014 REFUSED at the door. The seam ggui#987 flagged for the platform's pin shape.",
+    "theme": {
+        "overlays": {
+            "light": {
+                "--ggui-color-primary-500": "#3355ff"
+            },
+            "dark": {
+                "--ggui-color-primary-500": "#99aaff"
+            }
+        },
+        "overlayHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+        "name": "guuey-app-v2.dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
+    },
+    "expect": "refused"
+}

package/dist/theme-binding-conformance/cases/app-theme-v2-missing-dark.json

@@ -0,0 +1,13 @@
+{
+    "name": "app-theme-v2-missing-dark",
+    "description": "An overlay with only one projection cannot follow the host's mode \u2014 REFUSED.",
+    "theme": {
+        "overlayHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "overlays": {
+            "light": {
+                "--ggui-color-primary-500": "#3355ff"
+            }
+        }
+    },
+    "expect": "refused"
+}

package/dist/theme-binding-conformance/cases/app-theme-v2-no-hash.json

@@ -0,0 +1,15 @@
+{
+    "name": "app-theme-v2-no-hash",
+    "description": "The attestation is REQUIRED: an overlay without `overlayHash` is refused at the door.",
+    "theme": {
+        "overlays": {
+            "light": {
+                "--ggui-color-primary-500": "#3355ff"
+            },
+            "dark": {
+                "--ggui-color-primary-500": "#99aaff"
+            }
+        }
+    },
+    "expect": "refused"
+}

package/dist/theme-binding-conformance/cases/app-theme-v2-platform-pin.json

@@ -0,0 +1,17 @@
+{
+    "name": "app-theme-v2-platform-pin",
+    "description": "The exact overlay shape a platform's -v2 composer sends (ggui#987 \u00a79; guuey#1128): both projections, the attestation, and a label of the form `<prefix>.<hash-prefix>`. `name` is capped at 64 chars by appThemeSchema, so a stamped label must keep its hash segment to 51 chars after a 13-char prefix. Accepted.",
+    "theme": {
+        "overlays": {
+            "light": {
+                "--ggui-color-primary-500": "#3355ff"
+            },
+            "dark": {
+                "--ggui-color-primary-500": "#99aaff"
+            }
+        },
+        "overlayHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+        "name": "guuey-app-v2.ccccccccccccccccccccccccccccccccccccccccccccccccccc"
+    },
+    "expect": "accepted"
+}

package/dist/theme-binding-conformance/cases/overlay-hash-canonical.json

@@ -0,0 +1,17 @@
+{
+    "name": "overlay-hash-canonical",
+    "description": "canonicalOverlayHash is ONE function on every minter and door: keys sorted recursively, no whitespace, absent fields omitted, sha256 lowercase hex. The expected value was computed independently with node:crypto over the canonical JSON; the input's keys are deliberately unsorted.",
+    "input": {
+        "overlays": {
+            "light": {
+                "--ggui-color-primary-500": "#3355ff",
+                "--ggui-color-ground": "#ffffff"
+            },
+            "dark": {
+                "--ggui-color-primary-500": "#99aaff",
+                "--ggui-color-ground": "#0e1014"
+            }
+        }
+    },
+    "expect": "7cc8c947beeae43de91a8e3eedc182a739ae134e3a3957958ebee4ec6cf25e96"
+}

package/dist/theme-binding-conformance/cases/theme-mode-absence.json

@@ -0,0 +1,10 @@
+{
+    "name": "theme-mode-absence",
+    "description": "The absence law (ggui#551): when no layer resolves, the projection is undefined \u2014 never a light default.",
+    "sources": {
+        "stamped": null,
+        "sessionSidecar": null,
+        "hostAnnounced": null
+    },
+    "expect": null
+}

package/dist/theme-binding-conformance/cases/theme-mode-default-when-silent-host.json

@@ -0,0 +1,10 @@
+{
+    "name": "theme-mode-default-when-silent-host",
+    "description": "A host that announces nothing leaves the stamp (then the sidecar) to fill the mode \u2014 the defaults still apply.",
+    "sources": {
+        "stamped": "light",
+        "sessionSidecar": "dark",
+        "hostAnnounced": null
+    },
+    "expect": "light"
+}

package/dist/theme-binding-conformance/cases/theme-mode-order.json

@@ -0,0 +1,10 @@
+{
+    "name": "theme-mode-order",
+    "description": "The client projection of the themeMode total order since ggui#987 (D4 = A, 'follow the widget'): with a stamped mode and a host announce present, the HOST wins \u2014 the embedding host owns runtime mode; the stamp and the sidecar are defaults. Before #987 this case expected 'light' (the stamp); it was promoted into the kit at that version and FAILED when the order flipped \u2014 the VERSION-POLICY \u00a71.1 receipt that names the flip breaking.",
+    "sources": {
+        "stamped": "light",
+        "sessionSidecar": null,
+        "hostAnnounced": "dark"
+    },
+    "expect": "dark"
+}

package/dist/theme-binding-conformance/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Theme-binding conformance — a pure-function catalog (ggui#987).
+ *
+ * Three contracts the kit grades directly against `@ggui-ai/protocol`, so
+ * their breaking-ness is decided by a fixture and not by prose
+ * (VERSION-POLICY §2 — the kit is the arbiter):
+ *
+ *   - `theme-mode-*` — the CLIENT projection of the `themeMode` total
+ *     order, `effectiveThemeMode` (`integrations/theme-binding.ts`): the
+ *     embedding host owns runtime mode (D4).
+ *   - `app-theme-*` — which overlay shapes `appThemeSchema` accepts: both
+ *     projections and the attestation required; the v1 one-palette wire and
+ *     `base` refused.
+ *   - `overlay-hash-*` — `canonicalOverlayHash` against an independently
+ *     computed vector.
+ *
+ * History (the §1.1 receipt): `theme-mode-order`, `app-theme-v1-one-palette`
+ * and `app-theme-v1-base` were promoted from the unit pins at the version
+ * BEFORE the revision, passed there, and failed when it landed — that is
+ * what named the revision breaking. Like `../refusal-envelope-conformance`,
+ * the cases are raw JSON under `./cases/` and are NOT registered in
+ * `fixturesByContract`; the entry point is the runner below and its test.
+ */
+import { canonicalOverlayHash } from '@ggui-ai/protocol';
+type Opinion = 'light' | 'dark';
+export interface ThemeModeCase {
+    readonly name: string;
+    readonly description: string;
+    readonly sources: {
+        readonly stamped: Opinion | null;
+        readonly sessionSidecar: Opinion | null;
+        readonly hostAnnounced: Opinion | null;
+    };
+    readonly expect: Opinion | null;
+}
+export interface AppThemeCase {
+    readonly name: string;
+    readonly description: string;
+    readonly theme: unknown;
+    readonly expect: 'accepted' | 'refused';
+}
+export interface OverlayHashCase {
+    readonly name: string;
+    readonly description: string;
+    readonly input: Parameters<typeof canonicalOverlayHash>[0];
+    readonly expect: string;
+}
+export declare const THEME_MODE_CASES: readonly ThemeModeCase[];
+export declare const APP_THEME_CASES: readonly AppThemeCase[];
+export declare const OVERLAY_HASH_CASES: readonly OverlayHashCase[];
+export interface ThemeBindingResult {
+    readonly name: string;
+    readonly pass: boolean;
+    readonly detail: string;
+}
+/** Grade every theme-binding case against the protocol's own functions. */
+export declare function runThemeBindingConformance(): Promise<readonly ThemeBindingResult[]>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/theme-binding-conformance/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme-binding-conformance/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAkB,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAiBzE,KAAK,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAEhC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;QACjC,QAAQ,CAAC,cAAc,EAAE,OAAO,GAAG,IAAI,CAAC;QACxC,QAAQ,CAAC,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;KACxC,CAAC;IACF,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;CACzC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAkDD,eAAO,MAAM,gBAAgB,EAAE,SAAS,aAAa,EAA0F,CAAC;AAChJ,eAAO,MAAM,eAAe,EAAE,SAAS,YAAY,EAAuO,CAAC;AAC3R,eAAO,MAAM,kBAAkB,EAAE,SAAS,eAAe,EAAgD,CAAC;AAE1G,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAID,2EAA2E;AAC3E,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,SAAS,kBAAkB,EAAE,CAAC,CAqBzF"}

package/dist/theme-binding-conformance/index.js

@@ -0,0 +1,110 @@
+/**
+ * Theme-binding conformance — a pure-function catalog (ggui#987).
+ *
+ * Three contracts the kit grades directly against `@ggui-ai/protocol`, so
+ * their breaking-ness is decided by a fixture and not by prose
+ * (VERSION-POLICY §2 — the kit is the arbiter):
+ *
+ *   - `theme-mode-*` — the CLIENT projection of the `themeMode` total
+ *     order, `effectiveThemeMode` (`integrations/theme-binding.ts`): the
+ *     embedding host owns runtime mode (D4).
+ *   - `app-theme-*` — which overlay shapes `appThemeSchema` accepts: both
+ *     projections and the attestation required; the v1 one-palette wire and
+ *     `base` refused.
+ *   - `overlay-hash-*` — `canonicalOverlayHash` against an independently
+ *     computed vector.
+ *
+ * History (the §1.1 receipt): `theme-mode-order`, `app-theme-v1-one-palette`
+ * and `app-theme-v1-base` were promoted from the unit pins at the version
+ * BEFORE the revision, passed there, and failed when it landed — that is
+ * what named the revision breaking. Like `../refusal-envelope-conformance`,
+ * the cases are raw JSON under `./cases/` and are NOT registered in
+ * `fixturesByContract`; the entry point is the runner below and its test.
+ */
+import { appThemeSchema, canonicalOverlayHash } from '@ggui-ai/protocol';
+import { effectiveThemeMode } from '@ggui-ai/protocol/integrations/theme-binding';
+import appThemeV1Base from './cases/app-theme-v1-base.json' with { type: 'json' };
+import appThemeV1OnePalette from './cases/app-theme-v1-one-palette.json' with { type: 'json' };
+import appThemeV2Accepted from './cases/app-theme-v2-accepted.json' with { type: 'json' };
+import appThemeV2MissingDark from './cases/app-theme-v2-missing-dark.json' with { type: 'json' };
+import appThemeV2LabelTooLong from './cases/app-theme-v2-label-too-long.json' with { type: 'json' };
+import appThemeV2KeyframesAccepted from './cases/app-theme-v2-keyframes-accepted.json' with { type: 'json' };
+import appThemeV2KeyframesNotKeyframes from './cases/app-theme-v2-keyframes-not-keyframes.json' with { type: 'json' };
+import appThemeV2NoHash from './cases/app-theme-v2-no-hash.json' with { type: 'json' };
+import appThemeV2PlatformPin from './cases/app-theme-v2-platform-pin.json' with { type: 'json' };
+import overlayHashCanonical from './cases/overlay-hash-canonical.json' with { type: 'json' };
+import themeModeAbsence from './cases/theme-mode-absence.json' with { type: 'json' };
+import themeModeDefaultWhenSilentHost from './cases/theme-mode-default-when-silent-host.json' with { type: 'json' };
+import themeModeOrder from './cases/theme-mode-order.json' with { type: 'json' };
+const isOpinion = (v) => v === 'light' || v === 'dark';
+const opinionOrNull = (v, where) => {
+    if (v === null || isOpinion(v))
+        return v;
+    throw new Error(`theme-binding case: ${where} must be 'light' | 'dark' | null, got ${JSON.stringify(v)}`);
+};
+const isRecord = (v) => typeof v === 'object' && v !== null;
+const isVarMap = (v) => isRecord(v) && Object.values(v).every((x) => typeof x === 'string');
+function themeModeCase(raw) {
+    if (!isRecord(raw) || typeof raw['name'] !== 'string' || typeof raw['description'] !== 'string' || !isRecord(raw['sources']))
+        throw new Error('theme-binding case: malformed theme-mode case');
+    const src = raw['sources'];
+    return {
+        name: raw['name'],
+        description: raw['description'],
+        sources: {
+            stamped: opinionOrNull(src['stamped'], 'sources.stamped'),
+            sessionSidecar: opinionOrNull(src['sessionSidecar'], 'sources.sessionSidecar'),
+            hostAnnounced: opinionOrNull(src['hostAnnounced'], 'sources.hostAnnounced'),
+        },
+        expect: opinionOrNull(raw['expect'], 'expect'),
+    };
+}
+function appThemeCase(raw) {
+    if (!isRecord(raw) || typeof raw['name'] !== 'string' || typeof raw['description'] !== 'string' || !('theme' in raw))
+        throw new Error('theme-binding case: malformed app-theme case');
+    const expect = raw['expect'];
+    if (expect !== 'accepted' && expect !== 'refused')
+        throw new Error(`theme-binding case: expect must be accepted|refused, got ${JSON.stringify(expect)}`);
+    return { name: raw['name'], description: raw['description'], theme: raw['theme'], expect };
+}
+function overlayHashCase(raw) {
+    if (!isRecord(raw) || typeof raw['name'] !== 'string' || typeof raw['description'] !== 'string' || typeof raw['expect'] !== 'string' || !isRecord(raw['input']))
+        throw new Error('theme-binding case: malformed overlay-hash case');
+    const input = raw['input'];
+    const overlays = input['overlays'];
+    if (!isRecord(overlays) || !isVarMap(overlays['light']) || !isVarMap(overlays['dark']))
+        throw new Error('theme-binding case: overlay-hash input needs overlays.light and overlays.dark');
+    return {
+        name: raw['name'],
+        description: raw['description'],
+        input: { overlays: { light: overlays['light'], dark: overlays['dark'] } },
+        expect: raw['expect'],
+    };
+}
+export const THEME_MODE_CASES = [themeModeOrder, themeModeAbsence, themeModeDefaultWhenSilentHost].map(themeModeCase);
+export const APP_THEME_CASES = [appThemeV1OnePalette, appThemeV1Base, appThemeV2Accepted, appThemeV2MissingDark, appThemeV2NoHash, appThemeV2PlatformPin, appThemeV2LabelTooLong, appThemeV2KeyframesAccepted, appThemeV2KeyframesNotKeyframes].map(appThemeCase);
+export const OVERLAY_HASH_CASES = [overlayHashCanonical].map(overlayHashCase);
+const nullable = (v) => (v === null ? undefined : v);
+/** Grade every theme-binding case against the protocol's own functions. */
+export async function runThemeBindingConformance() {
+    const results = [];
+    for (const c of THEME_MODE_CASES) {
+        const got = effectiveThemeMode({
+            stamped: nullable(c.sources.stamped),
+            sessionSidecar: nullable(c.sources.sessionSidecar),
+            hostAnnounced: nullable(c.sources.hostAnnounced),
+        });
+        const want = nullable(c.expect);
+        results.push({ name: c.name, pass: got === want, detail: `effectiveThemeMode(${JSON.stringify(c.sources)}) = ${String(got)}; expected ${String(want)}` });
+    }
+    for (const c of APP_THEME_CASES) {
+        const parsed = appThemeSchema.safeParse(c.theme);
+        const got = parsed.success ? 'accepted' : 'refused';
+        results.push({ name: c.name, pass: got === c.expect, detail: `appThemeSchema: ${got}; expected ${c.expect}${parsed.success ? '' : ` (${parsed.error.issues.map((i) => i.message).join('; ')})`}` });
+    }
+    for (const c of OVERLAY_HASH_CASES) {
+        const got = await canonicalOverlayHash(c.input);
+        results.push({ name: c.name, pass: got === c.expect, detail: `canonicalOverlayHash = ${got}; expected ${c.expect}` });
+    }
+    return results;
+}

package/dist/transport-refusal-conformance/cases/refuse-deprovisioned-endpoint.json

@@ -0,0 +1,27 @@
+{
+    "name": "refuse-deprovisioned-endpoint",
+    "description": "A deprovisioned app answers EVERY JSON-RPC request on its per-app MCP endpoint (initialize included) with HTTP 403 and a JSON-RPC error whose data.refusal carries the registry projection — code, message, fix, retry, appId — so the client reads app_deprovisioned instead of guessing between a deleted app and a bad credential. error.code is -32003 (APP_NOT_FOUND — the endpoint no longer serves this app) and error.message is App not found; an untyped authorization failure answers -32007 (UNAUTHORIZED) with no data, so a client can tell the two apart by code and can tell neither from a dropped socket by mistake — -32000 is the SDK client's ConnectionClosed and a first-party server never chooses it (ggui#836).",
+    "refusal": {
+        "code": "app_deprovisioned",
+        "message": "the app record has no owner claim any more — the app was deprovisioned",
+        "fix": "provision the app again; this app id never renders again",
+        "retry": "never",
+        "appId": "app_deprov_1"
+    },
+    "expect": {
+        "httpStatus": 403,
+        "error": {
+            "code": -32003,
+            "message": "App not found",
+            "data": {
+                "refusal": {
+                    "code": "app_deprovisioned",
+                    "message": "the app record has no owner claim any more — the app was deprovisioned",
+                    "fix": "provision the app again; this app id never renders again",
+                    "retry": "never",
+                    "appId": "app_deprov_1"
+                }
+            }
+        }
+    }
+}

package/dist/transport-refusal-conformance/cases/refuse-render-only-code.json

@@ -0,0 +1,12 @@
+{
+    "name": "refuse-render-only-code",
+    "description": "A REGISTERED code whose surfaces exclude mcp-endpoint has no transport envelope: the per-app endpoint's authorization never speaks it, and a projector that types it anyway would put a render-gate state on a surface the registry does not list. The three auth arms (no issuer, foreign issuer, denied subject) stay the bare 403 by the same rule — naming any of them would say which is true.",
+    "refusal": {
+        "code": "insufficient_credit",
+        "message": "the configured allowance for this app is exhausted",
+        "fix": "top up the allowance for this app, then retry",
+        "retry": "after-fix",
+        "appId": "app_live_1"
+    },
+    "expect": null
+}

package/dist/transport-refusal-conformance/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The refusal handed to the projector — the registry projection on the
+ * transport surface. Authored here rather than imported from
+ * `@ggui-ai/protocol` for the same reason as the render catalog: the kit
+ * grades the WIRE, and a stringly input keeps a stale kit from typing
+ * its way past a registry change.
+ */
+export interface TransportRefusalInput {
+    /** Registered refusal code. */
+    readonly code: string;
+    /** Precise diagnostic. */
+    readonly message: string;
+    /** The one recovery step. */
+    readonly fix: string;
+    /** Retry class (`after-fix` | `next-period` | `later` | `never`). */
+    readonly retry: string;
+    /** The app id the refused endpoint serves — equals the path's `{appId}` (ggui#870). */
+    readonly appId: string;
+}
+/** What the endpoint answers: the HTTP status and the JSON-RPC error object. */
+export interface ProjectedTransportRefusal {
+    readonly httpStatus: number;
+    readonly error: {
+        readonly code: number;
+        readonly message: string;
+        readonly data: {
+            readonly refusal: TransportRefusalInput;
+        };
+    };
+}
+/** One transport-refusal case, authored as JSON under `./cases/`. */
+export interface TransportRefusalConformanceCase {
+    readonly name: string;
+    readonly description: string;
+    readonly refusal: TransportRefusalInput;
+    /** `null` when the code has no transport envelope (surfaces exclude `mcp-endpoint`). */
+    readonly expect: ProjectedTransportRefusal | null;
+}
+export declare const transportRefusalCases: readonly TransportRefusalConformanceCase[];
+export interface TransportRefusalMismatch {
+    readonly name: string;
+    readonly expected: ProjectedTransportRefusal | null;
+    /** What the projector produced — or the message of the error it threw. */
+    readonly actual: ProjectedTransportRefusal | null | string;
+}
+export interface TransportRefusalConformanceResult {
+    readonly passed: readonly string[];
+    readonly failed: readonly TransportRefusalMismatch[];
+}
+/**
+ * Grade a per-app endpoint refusal projector against the catalog. Pure
+ * and synchronous: no server, no transport — the deterministic
+ * projection is the whole obligation.
+ */
+export declare function runTransportRefusalConformance(project: (refusal: TransportRefusalInput) => ProjectedTransportRefusal | null): TransportRefusalConformanceResult;
+//# sourceMappingURL=index.d.ts.map