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

package/dist/registration-conformance/cases/gate-export-not-registered.json

@@ -15,5 +15,6 @@
             "exports": [{ "hook": "useLeafletMap" }]
         }
     ],
+    "appPublicEnv": {},
     "expect": { "outcome": "reject", "code": "gadget_not_registered" }
 }

package/dist/registration-conformance/cases/gate-multi-package-distinct-names-accept.json

@@ -0,0 +1,26 @@
+{
+    "name": "gate-multi-package-distinct-names-accept",
+    "description": "The duplicate-hook check fires on the same export NAME across packages — not on multi-package contracts per se. The contract declares two DIFFERENT export names from two different packages (`useCheckout` under `@stripe/ggui-checkout`, `useShippingEstimate` under `@acme/shipping`); both `(package, export)` pairs are registered and neither descriptor has `requires`. The composed gate MUST accept. Guards against an over-eager duplicate check that rejects any contract spanning more than one gadget package.",
+    "contract": {
+        "clientCapabilities": {
+            "gadgets": {
+                "@stripe/ggui-checkout": { "useCheckout": {} },
+                "@acme/shipping": { "useShippingEstimate": {} }
+            }
+        }
+    },
+    "appGadgets": [
+        {
+            "package": "@stripe/ggui-checkout",
+            "version": "1.0.0",
+            "exports": [{ "hook": "useCheckout" }]
+        },
+        {
+            "package": "@acme/shipping",
+            "version": "1.0.0",
+            "exports": [{ "hook": "useShippingEstimate" }]
+        }
+    ],
+    "appPublicEnv": {},
+    "expect": { "outcome": "accept" }
+}

package/dist/registration-conformance/cases/gate-no-gadgets-accept.json

@@ -9,5 +9,6 @@
             "exports": [{ "hook": "useLeafletMap" }]
         }
     ],
+    "appPublicEnv": {},
     "expect": { "outcome": "accept" }
 }

package/dist/registration-conformance/cases/gate-package-mismatch.json

@@ -15,5 +15,6 @@
             "exports": [{ "hook": "useLeafletMap" }]
         }
     ],
+    "appPublicEnv": {},
     "expect": { "outcome": "reject", "code": "gadget_package_mismatch" }
 }

package/dist/registration-conformance/cases/gate-priority-not-registered-outranks-mismatch.json

@@ -16,5 +16,6 @@
             "exports": [{ "hook": "useLeafletMap" }]
         }
     ],
+    "appPublicEnv": {},
     "expect": { "outcome": "reject", "code": "gadget_not_registered" }
 }

package/dist/registration-conformance/cases/gate-priority-registry-outranks-public-env.json

@@ -0,0 +1,22 @@
+{
+    "name": "gate-priority-registry-outranks-public-env",
+    "description": "A single push that fails BOTH gadget gates: it references an export absent from every registered package (`useTurnstile` under `@acme/turnstile`) AND a registered wrapper whose `requires` is unsatisfied (`useMapboxMap` under `@acme/mapbox`, requiring `GGUI_PUBLIC_APP_MAPBOX_TOKEN` while `App.publicEnv` is empty). SPEC §7.7.3 pins the order: the registry gate runs FIRST so the operator gets the right diagnostic when both fail — an author who referenced an unknown export needs the registration miss, not a downstream env complaint. The composed gate MUST reject with `gadget_not_registered`.",
+    "contract": {
+        "clientCapabilities": {
+            "gadgets": {
+                "@acme/turnstile": { "useTurnstile": {} },
+                "@acme/mapbox": { "useMapboxMap": {} }
+            }
+        }
+    },
+    "appGadgets": [
+        {
+            "package": "@acme/mapbox",
+            "version": "1.0.0",
+            "exports": [{ "hook": "useMapboxMap" }],
+            "requires": ["GGUI_PUBLIC_APP_MAPBOX_TOKEN"]
+        }
+    ],
+    "appPublicEnv": {},
+    "expect": { "outcome": "reject", "code": "gadget_not_registered" }
+}

package/dist/registration-conformance/cases/gate-public-env-missing.json

@@ -0,0 +1,21 @@
+{
+    "name": "gate-public-env-missing",
+    "description": "The contract references `useMapboxMap` under `@acme/mapbox`, and the app registers that exact `(package, export)` pair — registry membership passes — but the registered descriptor's `requires` lists the public env key `GGUI_PUBLIC_APP_MAPBOX_TOKEN` and `App.publicEnv` carries no keys at all. The render-time env gate (SPEC §7.7.3 — `assertPublicEnvSatisfied`) MUST reject with code `gadget_public_env_missing`: without the key, the wrapper's `getPublicEnv()` would throw at hook-mount inside the iframe, so the gate surfaces the misconfiguration as a recoverable author/operator-time error instead. Recovery: stamp the key on the app's public env, or drop the wrapper binding from the contract.",
+    "contract": {
+        "clientCapabilities": {
+            "gadgets": {
+                "@acme/mapbox": { "useMapboxMap": {} }
+            }
+        }
+    },
+    "appGadgets": [
+        {
+            "package": "@acme/mapbox",
+            "version": "1.0.0",
+            "exports": [{ "hook": "useMapboxMap" }],
+            "requires": ["GGUI_PUBLIC_APP_MAPBOX_TOKEN"]
+        }
+    ],
+    "appPublicEnv": {},
+    "expect": { "outcome": "reject", "code": "gadget_public_env_missing" }
+}

package/dist/registration-conformance/cases/gate-public-env-satisfied-accept.json

@@ -0,0 +1,21 @@
+{
+    "name": "gate-public-env-satisfied-accept",
+    "description": "The positive counterpart of `gate-public-env-missing`. The contract references `useMapboxMap` under `@acme/mapbox`; the registered descriptor requires `GGUI_PUBLIC_APP_MAPBOX_TOKEN`; and `App.publicEnv` carries that exact key. Every declared wrapper's `requires` is satisfied, so the composed gate MUST accept. Paired with the reject case, this also proves the gate actually reads `appPublicEnv` — an env-blind gate passes one of the pair but never both.",
+    "contract": {
+        "clientCapabilities": {
+            "gadgets": {
+                "@acme/mapbox": { "useMapboxMap": {} }
+            }
+        }
+    },
+    "appGadgets": [
+        {
+            "package": "@acme/mapbox",
+            "version": "1.0.0",
+            "exports": [{ "hook": "useMapboxMap" }],
+            "requires": ["GGUI_PUBLIC_APP_MAPBOX_TOKEN"]
+        }
+    ],
+    "appPublicEnv": { "GGUI_PUBLIC_APP_MAPBOX_TOKEN": "pk.conformance-fixture-value" },
+    "expect": { "outcome": "accept" }
+}

package/dist/registration-conformance/cases/gate-public-env-undeclared-wrapper-accept.json

@@ -0,0 +1,26 @@
+{
+    "name": "gate-public-env-undeclared-wrapper-accept",
+    "description": "The env gate is scoped to wrappers the CONTRACT references, not the whole catalog. The contract declares only `useLeafletMap` under `@ggui-samples/leaflet` (registered, no `requires`). The app catalog ALSO registers `@acme/mapbox`, whose `requires` lists `GGUI_PUBLIC_APP_MAPBOX_TOKEN` — unsatisfied, since `App.publicEnv` is empty — but the contract never references that wrapper, so it cannot affect this render's iframe. SPEC §7.7.3 walks `requires` for every wrapper the contract references; registered-but-undeclared wrappers MUST NOT fail the push. The gate MUST accept. Guards against a gate that validates the operator's entire catalog instead of the declared subset.",
+    "contract": {
+        "clientCapabilities": {
+            "gadgets": {
+                "@ggui-samples/leaflet": { "useLeafletMap": {} }
+            }
+        }
+    },
+    "appGadgets": [
+        {
+            "package": "@ggui-samples/leaflet",
+            "version": "2.3.1",
+            "exports": [{ "hook": "useLeafletMap" }]
+        },
+        {
+            "package": "@acme/mapbox",
+            "version": "1.0.0",
+            "exports": [{ "hook": "useMapboxMap" }],
+            "requires": ["GGUI_PUBLIC_APP_MAPBOX_TOKEN"]
+        }
+    ],
+    "appPublicEnv": {},
+    "expect": { "outcome": "accept" }
+}

package/dist/registration-conformance/cases/gate-registered-resolves-accept.json

@@ -21,5 +21,6 @@
             "exports": [{ "component": "RevenueChart" }, { "hook": "useChartTheme" }]
         }
     ],
+    "appPublicEnv": {},
     "expect": { "outcome": "accept" }
 }

package/dist/registration-conformance/cases/gate-stdlib-hook-accept.json

@@ -23,5 +23,6 @@
             ]
         }
     ],
+    "appPublicEnv": {},
     "expect": { "outcome": "accept" }
 }

package/dist/registration-conformance/cases/gate-typo-classifies-as-not-registered.json

@@ -23,5 +23,6 @@
             ]
         }
     ],
+    "appPublicEnv": {},
     "expect": { "outcome": "reject", "code": "gadget_not_registered" }
 }

package/dist/registration-conformance/index.d.ts

@@ -1,51 +1,72 @@
 /**
  * Registration-conformance catalog — accept / reject cases for the
- * gadget push-time registry gate (SPEC §7.7.2 — `assertGadgetsRegistered`).
+ * render-time gadget gate stack:
+ *
+ *   - registry membership (SPEC §7.7.2 — `assertGadgetsRegistered`):
+ *     every `(package, export)` the contract references resolves in
+ *     `App.gadgets`, with the miss classified into a precise reject
+ *     code (`gadget_not_registered` ▸ `gadget_package_mismatch`);
+ *   - public-env satisfaction (SPEC §7.7.3 —
+ *     `assertPublicEnvSatisfied`): every declared wrapper's
+ *     `requires[]` key is present in `App.publicEnv`
+ *     (`gadget_public_env_missing`). §7.7.3 pins the registry gate
+ *     FIRST when both fail;
+ *   - duplicate export names (SPEC §7.9 —
+ *     `assertNoDuplicateGadgetHooks`): the same export name declared
+ *     under two packages collides in the generated module scope
+ *     (`duplicate_gadget_hook`). The catalog deliberately authors its
+ *     duplicate cases so every pair resolves cleanly — this check's
+ *     priority relative to the other two is NOT pinned.
  *
  * ## Why this is a pure-function catalog, not a behavioral fixture
  *
- * The push-time gadget gate answers a pure question: given a contract
- * and the app's registered `App.gadgets` catalog, does every
- * `(package, export)` the contract references resolve — and if not,
- * which precise reject code applies? There is no render, no
- * transport, no wire frame in that question — it is a deterministic
- * classification, exactly like the `clientCapabilities` schema check
- * in `../schema-conformance`.
+ * The gadget gate stack answers a pure question: given a contract,
+ * the app's registered `App.gadgets` catalog, and the app's
+ * `App.publicEnv` map, does the push commit — and if not, which
+ * precise reject code applies? There is no render, no transport, no
+ * wire frame in that question — it is a deterministic classification,
+ * exactly like the `clientCapabilities` schema check in
+ * `../schema-conformance`.
  *
  * Modeling it as a WebSocket behavioral fixture would mean inventing a
- * wire frame the real protocol never emits (the gate runs at MCP-push
+ * wire frame the real protocol never emits (the gates run at MCP-push
  * time, before any live channel exists) — the dishonest modeling the
- * kit's Path-A / Path-B partition exists to forbid. So the gate gets
- * the same treatment as the wire schema: a catalog of cases graded
- * against a caller-supplied gate function.
+ * kit's Path-A / Path-B partition exists to forbid. So the gate stack
+ * gets the same treatment as the wire schema: a catalog of cases
+ * graded against a caller-supplied gate function.
  *
  * ## Polyglot, decoupled
  *
  * Each case ships as raw JSON under `./cases/`. {@link runRegistrationConformance}
  * takes the gate as a callback — the kit never imports a concrete gate
- * implementation here, so adopters drive their OWN gate. The reference
- * binding (`./registration-conformance.test.ts`) wraps
- * `@ggui-ai/mcp-server-handlers`'s `assertGadgetsRegistered`.
+ * implementation, so adopters drive their OWN gate. The kit's
+ * meta-test (`./registration-conformance.test.ts`) grades a kit-local
+ * gate built from the SPEC, proving catalog coherence while keeping
+ * the vendor-neutral kit free of any server implementation; the
+ * drift-catch against a SHIPPING gate lives implementation-side (the
+ * first-party one is `assert-gadgets.conformance.test.ts` in
+ * `@ggui-ai/mcp-server-handlers`) so the dependency edge stays
+ * implementation → kit.
  *
  * The `DataContract` / `GadgetDescriptor` types ARE imported (type-only)
  * from `@ggui-ai/protocol` — unlike the behavioral fixture vocabulary
  * in `../types.ts`, these are the gate's actual input contract, not a
  * frozen authored union; the runner's `gate` signature MUST match the
- * real function for the reference binding to be cast-free.
+ * real function for an implementation binding to be cast-free.
  */
 import type { DataContract, GadgetDescriptor } from '@ggui-ai/protocol';
 /**
- * The precise reject codes the gadget gate classifies a miss into.
- * Mirrors `GadgetGateErrorCode`'s registry-gate arms in
- * `@ggui-ai/mcp-server-handlers`. Extensibly-closed `(string & {})`
- * tail so a later protocol revision's code rides through without a kit
- * bump — same discipline as `ContractErrorCode` in `../types.ts`.
+ * The precise reject codes the gadget gate stack classifies a failing
+ * push into — the SPEC §7.9 Plane-2 slugs for the four gadget gate
+ * rejections. Extensibly-closed `(string & {})` tail so a later
+ * protocol revision's code rides through without a kit bump — same
+ * discipline as `BootstrapFailureReason` in `../types.ts`.
  */
-export type GadgetGateRejectCode = 'gadget_not_registered' | 'gadget_package_mismatch' | (string & {});
+export type GadgetGateRejectCode = 'gadget_not_registered' | 'gadget_package_mismatch' | 'gadget_public_env_missing' | 'duplicate_gadget_hook' | (string & {});
 /**
- * The outcome of running the gate against one `(contract, appGadgets)`
- * pair. A conformant gate either accepts the push or rejects it with
- * one classified code.
+ * The outcome of running the gate stack against one
+ * `(contract, appGadgets, appPublicEnv)` triple. A conformant gate
+ * either accepts the push or rejects it with one classified code.
  */
 export type GateOutcome = {
     readonly outcome: 'accept';
@@ -70,6 +91,12 @@ export interface RegistrationConformanceCase {
     readonly contract: DataContract;
     /** The app's registered gadget catalog the gate resolves against. */
     readonly appGadgets: readonly GadgetDescriptor[];
+    /**
+     * The app's operator-stamped public-env map the gate checks declared
+     * wrappers' `requires[]` against (SPEC §7.7.3). Always present on a
+     * case — `{}` models an app with no public env configured.
+     */
+    readonly appPublicEnv: Readonly<Record<string, string>>;
     /** The outcome a spec-conformant gate MUST produce. */
     readonly expect: GateOutcome;
 }
@@ -97,18 +124,22 @@ export interface RegistrationConformanceResult {
 /**
  * Grade a gadget registration gate against the catalog.
  *
- * `gate` MUST be a pure classification of `(contract, appGadgets)` —
- * return `{outcome:'accept'}` when every referenced `(package, export)`
- * resolves, or `{outcome:'reject', code}` with the precise reject code
- * otherwise. The kit deliberately does NOT import a concrete gate —
- * adopters pass their own (the reference binding wraps
- * `assertGadgetsRegistered`; see `./registration-conformance.test.ts`).
- * A conformant gate produces an empty `failed` array.
+ * `gate` MUST be a pure classification of
+ * `(contract, appGadgets, appPublicEnv)` — return `{outcome:'accept'}`
+ * when the push commits (every referenced `(package, export)`
+ * resolves, every declared wrapper's `requires[]` is satisfied, no
+ * export name repeats across packages), or `{outcome:'reject', code}`
+ * with the precise reject code otherwise. Implementations that compose
+ * separate checks wrap the composition. The kit deliberately does NOT
+ * import a concrete gate — adopters pass their own (the first-party
+ * drift-catch wraps `@ggui-ai/mcp-server-handlers`'s gate trio in its
+ * own package; see the module doc). A conformant gate produces an
+ * empty `failed` array.
  *
  * `gate` is invoked exactly once per case, in {@link gadgetRegistrationCases}
  * order; it MUST be pure and MUST NOT throw (a throwing gate is itself
  * non-conformant — wrap it so a classified rejection becomes a
  * returned `GateOutcome`).
  */
-export declare function runRegistrationConformance(gate: (contract: DataContract, appGadgets: readonly GadgetDescriptor[]) => GateOutcome): RegistrationConformanceResult;
+export declare function runRegistrationConformance(gate: (contract: DataContract, appGadgets: readonly GadgetDescriptor[], appPublicEnv: Readonly<Record<string, string>>) => GateOutcome): RegistrationConformanceResult;
 //# sourceMappingURL=index.d.ts.map

package/dist/registration-conformance/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/registration-conformance/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAUxE;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAC5B,uBAAuB,GACvB,yBAAyB,GACzB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAExE;;;;;;;GAOG;AACH,MAAM,WAAW,2BAA2B;IAC1C,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjD,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,2BAA2B,EAQzE,CAAC;AAEF,iDAAiD;AACjD,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,qDAAqD;AACrD,MAAM,WAAW,6BAA6B;IAC5C,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,SAAS,+BAA+B,EAAE,CAAC;CAC7D;AAUD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,CACJ,QAAQ,EAAE,YAAY,EACtB,UAAU,EAAE,SAAS,gBAAgB,EAAE,KACpC,WAAW,GACf,6BAA6B,CAgB/B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/registration-conformance/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAgBxE;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAC5B,uBAAuB,GACvB,yBAAyB,GACzB,2BAA2B,GAC3B,uBAAuB,GACvB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAExE;;;;;;;GAOG;AACH,MAAM,WAAW,2BAA2B;IAC1C,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjD;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACxD,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,2BAA2B,EAczE,CAAC;AAEF,iDAAiD;AACjD,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,qDAAqD;AACrD,MAAM,WAAW,6BAA6B;IAC5C,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,SAAS,+BAA+B,EAAE,CAAC;CAC7D;AAUD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,CACJ,QAAQ,EAAE,YAAY,EACtB,UAAU,EAAE,SAAS,gBAAgB,EAAE,EACvC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAC3C,WAAW,GACf,6BAA6B,CAoB/B"}

package/dist/registration-conformance/index.js

@@ -1,7 +1,13 @@
+import gateDuplicateHook from './cases/gate-duplicate-hook.json' with { type: 'json' };
 import gateExportNotRegistered from './cases/gate-export-not-registered.json' with { type: 'json' };
+import gateMultiPackageDistinctNamesAccept from './cases/gate-multi-package-distinct-names-accept.json' with { type: 'json' };
 import gateNoGadgetsAccept from './cases/gate-no-gadgets-accept.json' with { type: 'json' };
 import gatePackageMismatch from './cases/gate-package-mismatch.json' with { type: 'json' };
 import gatePriorityNotRegisteredOutranksMismatch from './cases/gate-priority-not-registered-outranks-mismatch.json' with { type: 'json' };
+import gatePriorityRegistryOutranksPublicEnv from './cases/gate-priority-registry-outranks-public-env.json' with { type: 'json' };
+import gatePublicEnvMissing from './cases/gate-public-env-missing.json' with { type: 'json' };
+import gatePublicEnvSatisfiedAccept from './cases/gate-public-env-satisfied-accept.json' with { type: 'json' };
+import gatePublicEnvUndeclaredWrapperAccept from './cases/gate-public-env-undeclared-wrapper-accept.json' with { type: 'json' };
 import gateRegisteredResolvesAccept from './cases/gate-registered-resolves-accept.json' with { type: 'json' };
 import gateStdlibHookAccept from './cases/gate-stdlib-hook-accept.json' with { type: 'json' };
 import gateTypoClassifiesAsNotRegistered from './cases/gate-typo-classifies-as-not-registered.json' with { type: 'json' };
@@ -15,9 +21,15 @@ export const gadgetRegistrationCases = [
     gatePackageMismatch,
     gatePriorityNotRegisteredOutranksMismatch,
     gateTypoClassifiesAsNotRegistered,
+    gatePublicEnvMissing,
+    gatePriorityRegistryOutranksPublicEnv,
+    gateDuplicateHook,
     gateStdlibHookAccept,
     gateRegisteredResolvesAccept,
     gateNoGadgetsAccept,
+    gatePublicEnvSatisfiedAccept,
+    gatePublicEnvUndeclaredWrapperAccept,
+    gateMultiPackageDistinctNamesAccept,
 ];
 function gateOutcomeEquals(a, b) {
     if (a.outcome !== b.outcome)
@@ -30,13 +42,17 @@ function gateOutcomeEquals(a, b) {
 /**
  * Grade a gadget registration gate against the catalog.
  *
- * `gate` MUST be a pure classification of `(contract, appGadgets)` —
- * return `{outcome:'accept'}` when every referenced `(package, export)`
- * resolves, or `{outcome:'reject', code}` with the precise reject code
- * otherwise. The kit deliberately does NOT import a concrete gate —
- * adopters pass their own (the reference binding wraps
- * `assertGadgetsRegistered`; see `./registration-conformance.test.ts`).
- * A conformant gate produces an empty `failed` array.
+ * `gate` MUST be a pure classification of
+ * `(contract, appGadgets, appPublicEnv)` — return `{outcome:'accept'}`
+ * when the push commits (every referenced `(package, export)`
+ * resolves, every declared wrapper's `requires[]` is satisfied, no
+ * export name repeats across packages), or `{outcome:'reject', code}`
+ * with the precise reject code otherwise. Implementations that compose
+ * separate checks wrap the composition. The kit deliberately does NOT
+ * import a concrete gate — adopters pass their own (the first-party
+ * drift-catch wraps `@ggui-ai/mcp-server-handlers`'s gate trio in its
+ * own package; see the module doc). A conformant gate produces an
+ * empty `failed` array.
  *
  * `gate` is invoked exactly once per case, in {@link gadgetRegistrationCases}
  * order; it MUST be pure and MUST NOT throw (a throwing gate is itself
@@ -47,7 +63,7 @@ export function runRegistrationConformance(gate) {
     const passed = [];
     const failed = [];
     for (const testCase of gadgetRegistrationCases) {
-        const actual = gate(testCase.contract, testCase.appGadgets);
+        const actual = gate(testCase.contract, testCase.appGadgets, testCase.appPublicEnv);
         if (gateOutcomeEquals(actual, testCase.expect)) {
             passed.push(testCase.name);
         }

package/dist/run-conformance.d.ts

@@ -1,10 +1,15 @@
-import type { ConformanceHost } from './conformance-host.js';
-import type { AuthConfig, ContractErrorBehavior, StreamUpdateBehavior, VersionMismatchBehavior } from './types.js';
+import type { HostContextObservedPayload } from '@ggui-ai/protocol';
+import type { ConformanceHost, SetupStep as HostSetupStep } from './conformance-host.js';
+import { type MatchResult } from './match-behavior.js';
+import type { AuthConfig, SessionStateBehavior, StreamUpdateBehavior, VersionMismatchBehavior } from './types.js';
 export interface RunConformanceConfig {
     /**
-     * Base URL of the implementation under test. The runner appends
-     * `/ws` to reach the live-channel endpoint; provide `http://host:port`
-     * or `https://…` and the runner derives `ws://` / `wss://`.
+     * URL of the implementation under test. `http://` / `https://`
+     * schemes derive `ws://` / `wss://`. A bare origin (no path, e.g.
+     * `http://localhost:3000`) gets the default live-channel path `/ws`
+     * appended; a URL that already carries a path (e.g.
+     * `ws://localhost:3000/ws`, or a non-default mount point) is used
+     * exactly as given — the runner never appends to an explicit path.
      */
     readonly serverUrl: string;
     /** Auth carried on the WS upgrade. See {@link AuthConfig}. */
@@ -54,5 +59,139 @@ export interface ConformanceReporter {
     onComplete?(result: ConformanceResult): void;
 }
 export declare function runConformance(config: RunConformanceConfig): Promise<ConformanceResult>;
-export type { ContractErrorBehavior, StreamUpdateBehavior, VersionMismatchBehavior };
+/**
+ * Resolve the WS endpoint from `config.serverUrl`:
+ *   - `http://` / `https://` schemes become `ws://` / `wss://`; a
+ *     scheme-less value is assumed `ws://`.
+ *   - A bare origin (no path) gets the default live-channel path
+ *     `/ws` appended.
+ *   - A URL that already carries a path is used exactly as given —
+ *     the runner never appends to an explicit path, so
+ *     `ws://host:3000/ws` (or a non-default mount point) works
+ *     without double-appending.
+ *
+ * Exported for unit tests; not part of the package's public API.
+ */
+export declare function deriveWsUrl(serverUrl: string): string;
+/**
+ * Fixture-authored `host_context_observed` Client→Server frame — the
+ * wire shape from `@ggui-ai/protocol` (`transport/websocket`):
+ * `{type: 'host_context_observed', payload: {sessionId, hostContext}}`.
+ * The iframe-runtime emits it after `ui/initialize` resolves (and on
+ * every `host-context-changed` notification); the server's obligation
+ * is to persist `payload.hostContext` onto `GguiSession.hostContext`
+ * with no synchronous response — which is why fixtures authoring this
+ * envelope pair it with a `session-state` expectation, not a frame
+ * expectation.
+ */
+export interface HostContextObservedInputEnvelope {
+    readonly type: 'host_context_observed';
+    readonly requestId?: string;
+    readonly payload: HostContextObservedPayload;
+}
+/**
+ * Classification of a fixture's `inputEnvelope` into the CLOSED
+ * dispatch vocabulary — exactly the C→S frame types the shipped
+ * fixture catalog authors for explicit post-subscribe dispatch.
+ *
+ *   - `action` — the live-channel action dispatch shape, sent
+ *     VERBATIM. Deliberately untyped beyond the discriminator: action
+ *     fixtures may author adversarial payloads (undeclared action
+ *     names, malformed bodies) precisely because the server's
+ *     rejection path is what's under test — the kit MUST NOT
+ *     pre-validate away the inputs the contract is graded on.
+ *   - `host_context_observed` — the validated typed arm
+ *     ({@link HostContextObservedInputEnvelope}). The kit authors this
+ *     frame as a well-formed client, so a malformed one is a
+ *     fixture-authoring error, not a server probe.
+ *   - `none` — every other authored envelope (`render`, `handshake`,
+ *     `props-update`) is driven by the subscribe itself or by a
+ *     Path-B host harness; the explicit send is skipped.
+ */
+export type InputEnvelopeDispatch = {
+    readonly kind: 'action';
+    readonly envelope: unknown;
+} | {
+    readonly kind: 'host_context_observed';
+    readonly envelope: HostContextObservedInputEnvelope;
+} | {
+    readonly kind: 'none';
+};
+/**
+ * Validating classifier for the fixture's `inputEnvelope`. The fixture
+ * JSON enters the type system through a compile-time cast, so —
+ * exactly like {@link parseSetupStep} — the dispatchable arms are
+ * re-validated structurally here, and a malformed
+ * `host_context_observed` frame throws a descriptive fixture-authoring
+ * error (never a skip, never a fail of the implementation under test).
+ *
+ * Exported for unit tests; not part of the package's public API.
+ */
+export declare function parseInputEnvelope(fixtureName: string, envelope: unknown): InputEnvelopeDispatch;
+/**
+ * Grade a `session-state` expectation — the input message left no wire
+ * trace, so the honest verdict is a post-observation-window read-back
+ * of the mutated GguiSession field via
+ * {@link ConformanceHost.readSessionField}, compared with the SAME
+ * exact {@link deepEqual} the frame matchers use.
+ *
+ * A missing host, a host without `readSessionField`, or a read that
+ * throws all yield `unmatchable-on-ws` — the runner records a SKIP
+ * with the reason. The kit refuses to grade a stateful obligation it
+ * has no introspection seam for (a host that cannot read state cannot
+ * grade it); it never converts that gap into a pass or a fail.
+ *
+ * Exported for unit tests; not part of the package's public API.
+ */
+export declare function matchSessionState(behavior: SessionStateBehavior, sessionId: string, host: ConformanceHost | undefined): Promise<MatchResult>;
+/**
+ * Resolved, runner-ready form of `SubscribeFrameShaping`: the
+ * `'current'` sentinel is already replaced by the kit's compiled
+ * `PROTOCOL_SCHEMA_VERSION`, so the subscribe-send site only ever
+ * sees a concrete declaration (or none).
+ */
+export interface ResolvedSubscribeShaping {
+    readonly omitAppId: boolean;
+    readonly supportedVersions?: readonly string[];
+}
+/**
+ * Validating narrower for the fixture-authored `subscribe` knob
+ * (`SubscribeFrameShaping`, types.ts). Same trust-boundary posture as
+ * {@link parseSetupStep}: the fixture JSON enters the type system
+ * through a compile-time cast, so the shape is re-validated
+ * structurally here and any malformed or unknown shaping is a
+ * fixture-authoring error the runner throws on — never a skip, never
+ * a fail of the implementation under test.
+ *
+ * The vocabulary is CLOSED — exactly the shaping fields the shipped
+ * catalog authors (`omitAppId`, `supportedVersions`); an unknown key
+ * is rejected so a typo'd knob can never silently no-op into a
+ * vacuous grade. `supportedVersions: 'current'` resolves to
+ * `[PROTOCOL_SCHEMA_VERSION]` (the kit's compiled canonical), keeping
+ * fixtures evergreen across protocol version bumps.
+ *
+ * Exported for unit tests; not part of the package's public API.
+ */
+export declare function parseSubscribeShaping(fixtureName: string, shaping: unknown): ResolvedSubscribeShaping;
+/**
+ * Validating narrower from the fixture-JSON `SetupStep` (discriminated
+ * on `type`) to the host's runtime `SetupStep` (discriminated on
+ * `kind`). The fixture JSON enters the type system through a
+ * compile-time cast (tsc widens JSON-module string literals), so the
+ * static union cannot be trusted at runtime — every directive is
+ * re-validated structurally here.
+ *
+ * The setup vocabulary is CLOSED: an unknown or malformed directive is
+ * a fixture-authoring error, thrown with a descriptive message. It is
+ * never mapped to a skip or a fail — those verdicts describe the
+ * implementation under test, not the fixture catalog.
+ *
+ * The input is `unknown` by design — this function IS the trust
+ * boundary, so it never leans on the static union it produces
+ * evidence for.
+ *
+ * Exported for unit tests; not part of the package's public API.
+ */
+export declare function parseSetupStep(fixtureName: string, step: unknown): HostSetupStep;
+export type { StreamUpdateBehavior, VersionMismatchBehavior };
 //# sourceMappingURL=run-conformance.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"run-conformance.d.ts","sourceRoot":"","sources":["../src/run-conformance.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,KAAK,EACV,UAAU,EACV,qBAAqB,EAErB,oBAAoB,EAGpB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAOpB,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,qDAAqD;IACrD,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IACxC;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC;IAChC,sDAAsD;IACtD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,aAAa,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACtD,aAAa,CAAC,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAClD,aAAa,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACnD;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACxD,UAAU,CAAC,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;CAC9C;AAMD,wBAAsB,cAAc,CAClC,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CA6C5B;AAyPD,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,CAAC"}
+{"version":3,"file":"run-conformance.d.ts","sourceRoot":"","sources":["../src/run-conformance.ts"],"names":[],"mappings":"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"}