@ggui-ai/protocol-conformance 0.15.0 → 0.16.0

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;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/protocol-conformance",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Conformance test kit for the ggui protocol. Drives a behavioral fixture catalog against a live implementation over WebSocket, a resources/read catalog against a live MCP server, and nine pure-function catalogs (schema, registration, resolution, binding, props-schema, host-helper, refusal-envelope, registry-completeness, transport-refusal) for the gadget, tool-binding, schema-precise-render, host-helper and pre-generation-refusal obligations, reporting a scorecard-style pass / fail / skip. MCP builders adopt this kit to prove their implementation is protocol-conformant.",
   "license": "Apache-2.0",
   "keywords": [
@@ -51,6 +51,11 @@
       "import": "./dist/resource-read-conformance/index.js",
       "default": "./dist/resource-read-conformance/index.js"
     },
+    "./theme-binding-conformance": {
+      "types": "./dist/theme-binding-conformance/index.d.ts",
+      "import": "./dist/theme-binding-conformance/index.js",
+      "default": "./dist/theme-binding-conformance/index.js"
+    },
     "./binding-conformance": {
       "types": "./dist/binding-conformance/index.d.ts",
       "import": "./dist/binding-conformance/index.js",
@@ -71,6 +76,11 @@
       "import": "./dist/refusal-envelope-conformance/index.js",
       "default": "./dist/refusal-envelope-conformance/index.js"
     },
+    "./domain-error-conformance": {
+      "types": "./dist/domain-error-conformance/index.d.ts",
+      "import": "./dist/domain-error-conformance/index.js",
+      "default": "./dist/domain-error-conformance/index.js"
+    },
     "./registry-completeness": {
       "types": "./dist/registry-completeness/index.d.ts",
       "import": "./dist/registry-completeness/index.js",
@@ -84,7 +94,7 @@
   },
   "dependencies": {
     "ws": "^8.20.1",
-    "@ggui-ai/protocol": "0.15.0"
+    "@ggui-ai/protocol": "0.16.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/dist/fixtures/subscribe-tenancy/index.d.ts

@@ -1,6 +0,0 @@
-import type { TestCase } from '../../types.js';
-/** All fixtures asserting subscribe-time tenancy (SPEC §12.2 field
- *  table — identity-default resolution on absent `appId` — and
- *  §12.2.3 `APP_MISMATCH`). */
-export declare const subscribeTenancyFixtures: readonly TestCase[];
-//# sourceMappingURL=index.d.ts.map

package/dist/fixtures/subscribe-tenancy/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/fixtures/subscribe-tenancy/index.ts"],"names":[],"mappings":"AAwDA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;+BAE+B;AAC/B,eAAO,MAAM,wBAAwB,EAAE,SAAS,QAAQ,EAGvD,CAAC"}