@ggui-ai/protocol-conformance 0.15.0 → 0.17.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`, `registry-completeness` and `transport-refusal`. 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
@@ -66,9 +67,14 @@ 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 { runN1CompatConformance } from './n1-compat-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.
  */
@@ -76,6 +82,9 @@ export const PURE_FUNCTION_CATALOG_SLUGS = [
     'refusal-envelope',
     'registry-completeness',
     'transport-refusal',
+    'domain-error',
+    'theme-binding',
+    'n1-compat',
 ];
 // =============================================================================
 // Runner
@@ -113,7 +122,7 @@ export async function runConformance(config) {
                 break;
         }
     }
-    runPureFunctionCatalogs(config, reporter, { passed, failed, skipped });
+    await runPureFunctionCatalogs(config, reporter, { passed, failed, skipped });
     const result = {
         passed,
         failed,
@@ -138,7 +147,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) => {
@@ -201,6 +210,33 @@ function runPureFunctionCatalogs(config, reporter, buckets) {
             });
         }
     }
+    // ── 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) {
@@ -222,6 +258,46 @@ 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,
+            });
+        }
+    }
+    // ── n1-compat (ggui#1014 §3.6) ──
+    // Previous-release payloads against today's protocol parsers: no adopter
+    // input, never skipped; a failing row is a receiver that broke N−1.
+    for (const graded of runN1CompatConformance()) {
+        const name = `n1-compat/${graded.name}`;
+        if (graded.pass) {
+            pass(name);
+        }
+        else {
+            fail({
+                name,
+                criterion: 'N−1 wire compatibility (VERSION-POLICY §3.6, ggui#1014)',
+                expected: graded.direction === 'forward'
+                    ? 'a later release\u2019s payload KEPT by today\u2019s read door — the unknown top-level member stripped and named'
+                    : 'the previous release\u2019s payload accepted by today\u2019s parser',
+                received: graded.detail,
+                message: graded.detail,
+            });
+        }
+    }
 }
 async function runOneFixture(fixture, config, _reporter) {
     const fixtureStarted = Date.now();
@@ -684,8 +760,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

@@ -1,11 +1,12 @@
 {
     "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 \u2014 code, message, fix, retry \u2014 so the client reads app_deprovisioned instead of guessing between a deleted app and a bad credential. error.code is -32003 (APP_NOT_FOUND \u2014 the endpoint no longer serves this app) and error.message is App not found; an untyped authorization failure answers -32001 (UNAUTHORIZED) with no data, so a client can tell the two apart by code and can tell neither from a dropped socket by mistake \u2014 -32000 is the SDK client's ConnectionClosed and a first-party server never chooses it (ggui#836).",
+    "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 \u2014 the app was 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"
+        "retry": "never",
+        "appId": "app_deprov_1"
     },
     "expect": {
         "httpStatus": 403,
@@ -15,9 +16,10 @@
             "data": {
                 "refusal": {
                     "code": "app_deprovisioned",
-                    "message": "the app record has no owner claim any more \u2014 the app was 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"
+                    "retry": "never",
+                    "appId": "app_deprov_1"
                 }
             }
         }

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

@@ -1,11 +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 \u2014 naming any of them would say which is true.",
+    "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"
+        "retry": "after-fix",
+        "appId": "app_live_1"
     },
     "expect": null
 }

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

@@ -14,6 +14,8 @@ export interface TransportRefusalInput {
     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 {

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transport-refusal-conformance/index.ts"],"names":[],"mappings":"AAyBA;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6BAA6B;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,gFAAgF;AAChF,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,IAAI,EAAE;YAAE,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAA;SAAE,CAAC;KAC5D,CAAC;CACH;AAED,qEAAqE;AACrE,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,yBAAyB,GAAG,IAAI,CAAC;CACnD;AAED,eAAO,MAAM,qBAAqB,EAAE,SAAS,+BAA+B,EAG3E,CAAC;AAEF,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI,CAAC;IACpD,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,yBAAyB,GAAG,IAAI,GAAG,MAAM,CAAC;CAC5D;AAED,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,SAAS,wBAAwB,EAAE,CAAC;CACtD;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,yBAAyB,GAAG,IAAI,GAC5E,iCAAiC,CAiBnC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transport-refusal-conformance/index.ts"],"names":[],"mappings":"AAyBA;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6BAA6B;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uFAAuF;IACvF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,gFAAgF;AAChF,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,IAAI,EAAE;YAAE,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAA;SAAE,CAAC;KAC5D,CAAC;CACH;AAED,qEAAqE;AACrE,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,yBAAyB,GAAG,IAAI,CAAC;CACnD;AAED,eAAO,MAAM,qBAAqB,EAAE,SAAS,+BAA+B,EAG3E,CAAC;AAEF,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI,CAAC;IACpD,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,yBAAyB,GAAG,IAAI,GAAG,MAAM,CAAC;CAC5D;AAED,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,SAAS,wBAAwB,EAAE,CAAC;CACtD;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,yBAAyB,GAAG,IAAI,GAC5E,iCAAiC,CAiBnC"}

package/dist/transport-refusal-conformance/index.js

@@ -8,8 +8,8 @@
  * The contract it makes observable: a deprovisioned app answers 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`); an authorization failure that is
- * NOT a registry state answers 403 with `-32001` and no `data` — the untyped
+ * (`code`, `message`, `fix`, `retry`, `appId`); an authorization failure that is
+ * NOT a registry state answers 403 with `-32007` and no `data` — the untyped
  * arms deliberately indistinguishable among themselves, so a client never
  * learns which one it hit (codes ruled in ggui#836).
  *

package/dist/types.d.ts

@@ -167,7 +167,7 @@ export interface CreateGguiSessionStep {
     /** Opaque render id the host allocates. Downstream steps + the
      *  fixture's `inputEnvelope` reference it by value. */
     readonly sessionId: string;
-    /** Optional app (tenant) id the render scopes to. Defaults to the
+    /** Optional app id the render scopes to. Defaults to the
      *  host's implementation-defined "default app". */
     readonly appId?: string;
     /**