@ggui-ai/protocol-conformance 0.1.0-rc.1

package/dist/run-conformance.d.ts

@@ -0,0 +1,58 @@
+import type { ConformanceHost } from './conformance-host.js';
+import type { AuthConfig, ContractErrorBehavior, 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://`.
+     */
+    readonly serverUrl: string;
+    /** Auth carried on the WS upgrade. See {@link AuthConfig}. */
+    readonly auth: AuthConfig;
+    /** Optional abort signal — cancels the run between fixtures. */
+    readonly signal?: AbortSignal;
+    /** Filter fixtures by name. Useful for debugging. */
+    readonly only?: readonly string[];
+    /** Reporter callbacks. Default is a silent reporter. */
+    readonly reporter?: ConformanceReporter;
+    /**
+     * Conformance host the runner dispatches setup/teardown against.
+     * Fixtures with non-empty `setup` skip if `host` is undefined.
+     */
+    readonly host?: ConformanceHost;
+    /** Per-fixture observation window. Default 2000ms. */
+    readonly observationTimeoutMs?: number;
+}
+export interface ConformanceResult {
+    readonly passed: readonly string[];
+    readonly failed: readonly ConformanceFailure[];
+    readonly skipped: readonly SkippedFixture[];
+    readonly totalMs: number;
+}
+export interface ConformanceFailure {
+    readonly name: string;
+    readonly criterion: string;
+    readonly expected: unknown;
+    readonly received: unknown;
+    readonly message: string;
+}
+export interface SkippedFixture {
+    readonly name: string;
+    readonly reason: string;
+}
+export interface ConformanceReporter {
+    onStart?(totalFixtures: number): void;
+    onFixturePass?(name: string, elapsedMs: number): void;
+    onFixtureFail?(failure: ConformanceFailure): void;
+    onFixtureSkip?(name: string, reason: string): void;
+    /**
+     * Invoked when a teardown step throws. Non-fatal — the fixture's
+     * pass/fail verdict is NOT affected. Surfaces cleanup gaps for
+     * operator attention.
+     */
+    onTeardownWarning?(name: string, message: string): void;
+    onComplete?(result: ConformanceResult): void;
+}
+export declare function runConformance(config: RunConformanceConfig): Promise<ConformanceResult>;
+export type { ContractErrorBehavior, StreamUpdateBehavior, VersionMismatchBehavior };
+//# sourceMappingURL=run-conformance.d.ts.map

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

@@ -0,0 +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"}

package/dist/run-conformance.js

@@ -0,0 +1,286 @@
+/**
+ * `runConformance()` — drive every fixture in the catalog against a
+ * live implementation and return a pass / fail / skip scorecard.
+ *
+ * Orchestration:
+ *   1. Invoke `reporter.onStart(totalFixtures)`.
+ *   2. For each fixture (filtered by `config.only` if provided):
+ *      a. If `fixture.skipReason !== null` → skip with the reason.
+ *      b. If `fixture.setup` non-empty AND `config.host` absent →
+ *         skip with "no host provided".
+ *      c. Dispatch every setup step via `host.dispatchSetup()`.
+ *         Throw → skip with the error message (NOT a fail).
+ *      d. Open a WS transport against `config.serverUrl`.
+ *      e. Send the canonical `subscribe` frame (the runner knows the
+ *         wire shape — fixture's `inputEnvelope` is NOT the subscribe
+ *         frame; subscribe is always runner-owned).
+ *      f. If the fixture's `inputEnvelope.type === 'action'`, send
+ *         it as a live-channel action frame AFTER subscribe.
+ *      g. Observe frames for `config.observationTimeoutMs` (default
+ *         2000ms).
+ *      h. Match observed frames against `fixture.expectedBehavior`.
+ *      i. Close the WS.
+ *      j. Dispatch every teardown step via `host.dispatchTeardown()`.
+ *         Throw → reporter warning; does NOT flip pass → fail.
+ *      k. Record the outcome via reporter + accumulate in result.
+ *   3. Invoke `reporter.onComplete(result)` + return.
+ *
+ * Scope v1: pure WS transport. Browser-level fixtures (bootstrap-
+ * failure, props-update, observability-event) automatically skip via
+ * the matcher's `unmatchable-on-ws` arm.
+ */
+import { allFixtures, fixturesByContract } from './fixtures/index.js';
+import { matchBehavior } from './match-behavior.js';
+import { openWsTransport } from './ws-transport.js';
+// =============================================================================
+// Runner
+// =============================================================================
+export async function runConformance(config) {
+    const started = Date.now();
+    const fixtures = filterFixtures(config.only);
+    const reporter = config.reporter ?? {};
+    reporter.onStart?.(fixtures.length);
+    const passed = [];
+    const failed = [];
+    const skipped = [];
+    for (const fixture of fixtures) {
+        if (config.signal?.aborted === true) {
+            skipped.push({
+                name: fixture.name,
+                reason: 'aborted by signal before dispatch',
+            });
+            reporter.onFixtureSkip?.(fixture.name, 'aborted by signal before dispatch');
+            continue;
+        }
+        const outcome = await runOneFixture(fixture, config, reporter);
+        switch (outcome.kind) {
+            case 'pass':
+                passed.push(fixture.name);
+                reporter.onFixturePass?.(fixture.name, outcome.elapsedMs);
+                break;
+            case 'fail':
+                failed.push(outcome.failure);
+                reporter.onFixtureFail?.(outcome.failure);
+                break;
+            case 'skip':
+                skipped.push({ name: fixture.name, reason: outcome.reason });
+                reporter.onFixtureSkip?.(fixture.name, outcome.reason);
+                break;
+        }
+    }
+    const result = {
+        passed,
+        failed,
+        skipped,
+        totalMs: Date.now() - started,
+    };
+    reporter.onComplete?.(result);
+    return result;
+}
+async function runOneFixture(fixture, config, _reporter) {
+    const fixtureStarted = Date.now();
+    if (fixture.skipReason !== null) {
+        return { kind: 'skip', reason: fixture.skipReason };
+    }
+    if (fixture.setup.length > 0 && config.host === undefined) {
+        return {
+            kind: 'skip',
+            reason: `fixture has ${fixture.setup.length} setup step(s) and no \`host\` was provided — supply a ConformanceHost to drive setup directives.`,
+        };
+    }
+    // Dispatch setup via host. A throw means "host doesn't implement
+    // this directive" — record as skip, NOT fail.
+    if (config.host !== undefined) {
+        for (const step of fixture.setup) {
+            try {
+                await config.host.dispatchSetup(narrowSetupStep(step));
+            }
+            catch (err) {
+                return {
+                    kind: 'skip',
+                    reason: `host refused setup step type='${step.type ?? 'unknown'}': ${String(err.message ?? err)}`,
+                };
+            }
+        }
+    }
+    // Open WS + subscribe + dispatch + observe.
+    let transport = null;
+    try {
+        const wsUrl = deriveWsUrl(config.serverUrl);
+        transport = await openWsTransport({ kind: 'ws', url: wsUrl, auth: config.auth });
+        const sessionId = extractSessionId(fixture);
+        transport.send({
+            type: 'subscribe',
+            payload: {
+                sessionId,
+                appId: 'conformance',
+                role: 'user',
+                ...(maybeSupportedVersions(fixture.expectedBehavior) ?? {}),
+            },
+            requestId: `conformance-subscribe-${fixture.name}`,
+        });
+        if (shouldDispatchInputEnvelope(fixture)) {
+            transport.send(fixture.inputEnvelope);
+        }
+        const frames = await transport.observe({
+            timeoutMs: config.observationTimeoutMs ?? 2000,
+        });
+        const match = matchBehavior(fixture.expectedBehavior, frames);
+        // Dispatch teardown regardless of match outcome. Failures in
+        // teardown surface as warnings; they do not flip pass → fail.
+        if (config.host !== undefined) {
+            for (const step of fixture.teardown) {
+                try {
+                    await config.host.dispatchTeardown(narrowTeardownStep(step));
+                }
+                catch (err) {
+                    _reporter.onTeardownWarning?.(fixture.name, `teardown step type='${step.type ?? 'unknown'}' threw: ${String(err.message ?? err)}`);
+                }
+            }
+        }
+        if (match.kind === 'pass') {
+            return { kind: 'pass', elapsedMs: Date.now() - fixtureStarted };
+        }
+        if (match.kind === 'fail') {
+            return {
+                kind: 'fail',
+                failure: {
+                    name: fixture.name,
+                    criterion: criterionForFixture(fixture.name),
+                    expected: match.expected,
+                    received: match.received,
+                    message: match.message,
+                },
+            };
+        }
+        // match.kind === 'unmatchable-on-ws'
+        return { kind: 'skip', reason: match.reason };
+    }
+    catch (err) {
+        return {
+            kind: 'fail',
+            failure: {
+                name: fixture.name,
+                criterion: criterionForFixture(fixture.name),
+                expected: 'transport reachable + fixture driveable',
+                received: String(err.message ?? err),
+                message: `runner-side error dispatching fixture: ${String(err.message ?? err)}`,
+            },
+        };
+    }
+    finally {
+        if (transport !== null)
+            await transport.close();
+    }
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+function filterFixtures(only) {
+    if (only === undefined || only.length === 0)
+        return allFixtures;
+    const allow = new Set(only);
+    return allFixtures.filter((fixture) => allow.has(fixture.name));
+}
+function deriveWsUrl(serverUrl) {
+    const trimmed = serverUrl.replace(/\/+$/, '');
+    if (trimmed.startsWith('ws://') || trimmed.startsWith('wss://')) {
+        return `${trimmed}/ws`;
+    }
+    if (trimmed.startsWith('https://'))
+        return `wss://${trimmed.slice('https://'.length)}/ws`;
+    if (trimmed.startsWith('http://'))
+        return `ws://${trimmed.slice('http://'.length)}/ws`;
+    // No scheme provided — assume plain ws.
+    return `ws://${trimmed}/ws`;
+}
+function extractSessionId(fixture) {
+    // Prefer a sessionId from the first `create-session` setup step —
+    // this is the fixture's declared session identity. Fall back to
+    // inputEnvelope.sessionId, then to the fixture name.
+    for (const step of fixture.setup) {
+        if (step.type === 'create-session' &&
+            typeof step.sessionId === 'string') {
+            return step.sessionId;
+        }
+    }
+    const envelope = fixture.inputEnvelope;
+    if (envelope !== null &&
+        typeof envelope === 'object' &&
+        'sessionId' in envelope &&
+        typeof envelope.sessionId === 'string') {
+        return envelope.sessionId;
+    }
+    return fixture.name;
+}
+/**
+ * Fixtures with `inputEnvelope.type === 'action'` (or another channel-
+ * 3 dispatch shape) get sent verbatim after subscribe. Fixtures with
+ * `type === 'render'` are bootstrap-path — the subscribe itself is
+ * the dispatch, so we skip the explicit send.
+ */
+function shouldDispatchInputEnvelope(fixture) {
+    const envelope = fixture.inputEnvelope;
+    if (envelope === null || typeof envelope !== 'object')
+        return false;
+    const type = envelope.type;
+    return type === 'action' || type === 'pop' || type === 'close';
+}
+function maybeSupportedVersions(behavior) {
+    if (behavior.kind === 'version-mismatch') {
+        // Cast to the specific arm — the extensibly-closed `UnknownBehavior`
+        // in the union has `kind: string & {}` which widens narrowing and
+        // makes TS forget it already checked the discriminant literal.
+        const narrow = behavior;
+        return { supportedVersions: narrow.clientAccepts };
+    }
+    return undefined;
+}
+/**
+ * Map fixture name → the bar criterion it exercises, for the
+ * `ConformanceFailure.criterion` field. Derived from the
+ * `fixturesByContract` classification so the runner stays in sync
+ * with the reporter's scorecard grouping.
+ */
+function criterionForFixture(name) {
+    for (const [slug, fixtures] of Object.entries(fixturesByContract)) {
+        if (fixtures.some((f) => f.name === name))
+            return slugToCriterion(slug);
+    }
+    return 'unknown criterion';
+}
+function slugToCriterion(slug) {
+    switch (slug) {
+        case 'bootstrap-protocol':
+            return 'Protocol #5 named failure modes — bootstrap contract';
+        case 'observability-events':
+            return 'Phase 2 C12 observability contract';
+        case 'refresh-semantics':
+            return 'SPEC §2.3 StreamSpec refresh triggers';
+        case 'reserved-channel-authority':
+            return 'SPEC §4.4 reserved-channel authority';
+        case 'schema-version-handshake':
+            return 'Protocol #3 version negotiation';
+        case 'wired-action-dispatch':
+            return 'Contract #3 defined failure modes (wiredActionRouter)';
+        default:
+            return slug;
+    }
+}
+/**
+ * The fixture-JSON `SetupStep` and the host's runtime `SetupStep` use
+ * slightly different shapes (`type` vs `kind` field, respectively).
+ * The runner accepts JSON-shape at the fixture boundary and narrows
+ * here — translating `{type,...}` → `{kind,...}` — before dispatching
+ * to the host.
+ */
+function narrowSetupStep(step) {
+    const raw = step;
+    const { type, ...rest } = raw;
+    return { kind: type ?? 'unknown', ...rest };
+}
+function narrowTeardownStep(step) {
+    const raw = step;
+    const { type, ...rest } = raw;
+    return { kind: type ?? 'unknown', ...rest };
+}

package/dist/schema-conformance/cases/wire-bad-export-name-reject.json

@@ -0,0 +1,11 @@
+{
+    "name": "wire-bad-export-name-reject",
+    "description": "A package entry whose export-name KEY (`leafletmap`) is neither a `use`-prefixed hook (`HOOK_NAME_RE` — `/^use[A-Z][A-Za-z0-9]*$/`) nor a PascalCase component (`COMPONENT_NAME_RE` — `/^[A-Z][A-Za-z0-9]*$/`). The export name grammar is load-bearing — it is the only discriminator of hook vs component on the wire — so a key matching neither grammar MUST be rejected.",
+    "clientCapabilities": {
+        "gadgets": {
+            "@ggui-samples/leaflet": { "leafletmap": {} }
+        }
+    },
+    "expect": "reject",
+    "rejectReason": "export-name key must match HOOK_NAME_RE (use-prefixed) or COMPONENT_NAME_RE (PascalCase); `leafletmap` matches neither."
+}

package/dist/schema-conformance/cases/wire-bad-package-name-reject.json

@@ -0,0 +1,11 @@
+{
+    "name": "wire-bad-package-name-reject",
+    "description": "A `gadgets` map keyed by `Leaflet` — not a valid npm package name (uppercase first character). Package keys MUST match `NPM_PACKAGE_NAME_RE` (lowercase alphanumerics + `.`/`_`/`-`, an optional single `@scope/` prefix, no leading non-alphanumeric, no URL). A descriptor is looked up by npm package name, so a malformed key cannot resolve and MUST be rejected.",
+    "clientCapabilities": {
+        "gadgets": {
+            "Leaflet": { "useLeafletMap": {} }
+        }
+    },
+    "expect": "reject",
+    "rejectReason": "package key must match NPM_PACKAGE_NAME_RE; `Leaflet` is uppercase."
+}

package/dist/schema-conformance/cases/wire-component-export-accept.json

@@ -0,0 +1,10 @@
+{
+    "name": "wire-component-export-accept",
+    "description": "A gadget export name is either a `use`-prefixed hook or a PascalCase component — the two grammars are disjoint, so the map KEY alone discriminates kind with no `hook`/`component` tag on the wire. A PascalCase key (`RevenueChart`) is a valid component export reference.",
+    "clientCapabilities": {
+        "gadgets": {
+            "@ggui-samples/charts": { "RevenueChart": {} }
+        }
+    },
+    "expect": "accept"
+}

package/dist/schema-conformance/cases/wire-empty-package-reject.json

@@ -0,0 +1,11 @@
+{
+    "name": "wire-empty-package-reject",
+    "description": "A package entry with an empty export map (`{}`). A `clientCapabilities.gadgets` package entry MUST declare at least one export — an entry that names a package but uses none of its exports carries no wire meaning. `gadgetPackageUseSchema` refines on `Object.keys(r).length > 0`, so an empty entry MUST be rejected.",
+    "clientCapabilities": {
+        "gadgets": {
+            "@ggui-samples/leaflet": {}
+        }
+    },
+    "expect": "reject",
+    "rejectReason": "a clientCapabilities.gadgets package entry must declare at least one export (gadgetPackageUseSchema non-empty refine)."
+}

package/dist/schema-conformance/cases/wire-minimal-accept.json

@@ -0,0 +1,10 @@
+{
+    "name": "wire-minimal-accept",
+    "description": "Minimal well-formed gadget wire shape: `clientCapabilities.gadgets` keyed by an npm package name, each value a map of export name → entry. A bare `{}` export entry is valid — the wire carries identity only, `(package, export name)`, and both prose fields are optional.",
+    "clientCapabilities": {
+        "gadgets": {
+            "@ggui-samples/leaflet": { "useLeafletMap": {} }
+        }
+    },
+    "expect": "accept"
+}

package/dist/schema-conformance/cases/wire-multi-package-accept.json

@@ -0,0 +1,14 @@
+{
+    "name": "wire-multi-package-accept",
+    "description": "`clientCapabilities.gadgets` MAY reference multiple packages, and a single package MAY expose multiple exports — hooks and components mixed. Each package entry is its own export map; there is no package-level wrapper field on the wire.",
+    "clientCapabilities": {
+        "gadgets": {
+            "@ggui-samples/charts": {
+                "RevenueChart": {},
+                "useChartTheme": { "usage": "Match the chart palette to the app theme." }
+            },
+            "@ggui-ai/gadgets": { "useClipboardWrite": {} }
+        }
+    },
+    "expect": "accept"
+}

package/dist/schema-conformance/cases/wire-prose-accept.json

@@ -0,0 +1,15 @@
+{
+    "name": "wire-prose-accept",
+    "description": "A gadget export entry MAY carry the two optional intent-specific prose fields `description` and `usage`. When present the agent's prose wins over the registered export's text; when omitted, push-time resolution inherits the registered text verbatim. Both are the ONLY wire-authored payload on an export entry.",
+    "clientCapabilities": {
+        "gadgets": {
+            "@ggui-samples/leaflet": {
+                "useLeafletMap": {
+                    "description": "Interactive map of the delivery route.",
+                    "usage": "Render once the courier location stream is live."
+                }
+            }
+        }
+    },
+    "expect": "accept"
+}

package/dist/schema-conformance/cases/wire-registry-metadata-reject.json

@@ -0,0 +1,13 @@
+{
+    "name": "wire-registry-metadata-reject",
+    "description": "An export entry carrying per-export registry metadata (`permission`). The registry-side teaching + gating fields — `permission`, `example`, `gotchas`, `required` — live on each `exports[*]` of the registered descriptor, never on the wire. `gadgetExportUseSchema` admits only the optional prose pair `description`/`usage` and is `.strict()`, so a `permission` field MUST be rejected at parse time.",
+    "clientCapabilities": {
+        "gadgets": {
+            "@ggui-ai/gadgets": {
+                "useGeolocation": { "permission": "geolocation" }
+            }
+        }
+    },
+    "expect": "reject",
+    "rejectReason": "per-export registry metadata (permission/example/gotchas/required) is descriptor-side, not a wire field; gadgetExportUseSchema is .strict()."
+}

package/dist/schema-conformance/cases/wire-stale-libraries-reject.json

@@ -0,0 +1,14 @@
+{
+    "name": "wire-stale-libraries-reject",
+    "description": "A `clientCapabilities` object carrying the retired `libraries` sibling alongside `gadgets`. `libraries` was renamed to `gadgets`; `clientCapabilitiesSpecSchema` is `.strict()` (not `.passthrough()`) precisely so a stale `libraries` field — or any other unknown sibling — MUST fail loudly at parse time rather than being silently dropped.",
+    "clientCapabilities": {
+        "gadgets": {
+            "@ggui-samples/leaflet": { "useLeafletMap": {} }
+        },
+        "libraries": {
+            "@ggui-samples/leaflet": { "useLeafletMap": {} }
+        }
+    },
+    "expect": "reject",
+    "rejectReason": "`libraries` is the retired pre-rename name of `gadgets`; clientCapabilitiesSpecSchema is .strict()."
+}

package/dist/schema-conformance/cases/wire-stdlib-accept.json

@@ -0,0 +1,10 @@
+{
+    "name": "wire-stdlib-accept",
+    "description": "The first-party `@ggui-ai/gadgets` stdlib package is referenced on the wire exactly like any other gadget package — by its npm package name keying a map of export names. A stdlib browser-capability hook (`useGeolocation`) is a valid wire reference; the stdlib enjoys no special wire shape.",
+    "clientCapabilities": {
+        "gadgets": {
+            "@ggui-ai/gadgets": { "useGeolocation": {} }
+        }
+    },
+    "expect": "accept"
+}

package/dist/schema-conformance/cases/wire-transport-field-reject.json

@@ -0,0 +1,15 @@
+{
+    "name": "wire-transport-field-reject",
+    "description": "An export entry carrying a transport field (`bundleUrl`). Transport metadata — `bundleUrl`, `bundleHost`, `bundleSri`, `styleUrl`, `connect`, `requires`, `typesUrl`, `typesSri` — lives once on the registered `GadgetDescriptor`, never on the wire. `gadgetExportUseSchema` is `.strict()`, so a transport field MUST be rejected at parse time.",
+    "clientCapabilities": {
+        "gadgets": {
+            "@ggui-samples/leaflet": {
+                "useLeafletMap": {
+                    "bundleUrl": "https://cdn.example.com/bundles/leaflet/bundle.js"
+                }
+            }
+        }
+    },
+    "expect": "reject",
+    "rejectReason": "transport metadata is descriptor-side (App.gadgets), not a wire field; gadgetExportUseSchema is .strict()."
+}

package/dist/schema-conformance/cases/wire-version-field-reject.json

@@ -0,0 +1,13 @@
+{
+    "name": "wire-version-field-reject",
+    "description": "An export entry carrying a `version` field. `version` is the operator's deployment pin in `App.gadgets`, never the agent's to author — it is resolved from the registry at push time, never carried on the wire. `gadgetExportUseSchema` is `.strict()`, so a `version` field MUST be rejected at parse time rather than silently dropped.",
+    "clientCapabilities": {
+        "gadgets": {
+            "@ggui-samples/leaflet": {
+                "useLeafletMap": { "version": "2.3.1" }
+            }
+        }
+    },
+    "expect": "reject",
+    "rejectReason": "`version` is registry-side (App.gadgets), not a wire field; gadgetExportUseSchema is .strict()."
+}

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

@@ -0,0 +1,71 @@
+/**
+ * One schema-conformance case. Authored as JSON under `./cases/`,
+ * consumed via {@link gadgetWireSchemaCases}, graded by
+ * {@link runSchemaConformance}.
+ *
+ * The shape IS the public API — additive changes only, mirroring the
+ * `TestCase` discipline in `../types.ts`.
+ */
+export interface SchemaConformanceCase {
+    /** Unique case name. MUST match the JSON filename without `.json`. */
+    readonly name: string;
+    /** What structural obligation this case proves. */
+    readonly description: string;
+    /**
+     * The `DataContract.clientCapabilities` value fed verbatim to the
+     * validator. `unknown` because reject cases are deliberately
+     * malformed — the catalog's whole point is feeding the parser
+     * payloads its type would not admit.
+     */
+    readonly clientCapabilities: unknown;
+    /**
+     * Whether a spec-conformant `clientCapabilities` parser MUST accept
+     * or reject {@link clientCapabilities}.
+     */
+    readonly expect: 'accept' | 'reject';
+    /**
+     * The normative reason a conformant parser rejects this case.
+     * Present iff `expect === 'reject'`.
+     */
+    readonly rejectReason?: string;
+}
+/**
+ * Every gadget-wire schema-conformance case the kit ships, in
+ * deterministic order — accepts first, then rejects, each group
+ * lexicographic by `name`.
+ */
+export declare const gadgetWireSchemaCases: readonly SchemaConformanceCase[];
+/** One case the validator graded wrong. */
+export interface SchemaConformanceMismatch {
+    readonly name: string;
+    /** What the catalog says a conformant parser MUST do. */
+    readonly expected: 'accept' | 'reject';
+    /** What the validator under test actually did. */
+    readonly actual: 'accept' | 'reject';
+    /** The reject reason from the case, when `expected === 'reject'`. */
+    readonly rejectReason?: string;
+}
+/** Outcome of grading a validator against the catalog. */
+export interface SchemaConformanceResult {
+    /** Names of cases the validator graded correctly. */
+    readonly passed: readonly string[];
+    /** Cases the validator graded wrong — empty iff fully conformant. */
+    readonly failed: readonly SchemaConformanceMismatch[];
+}
+/**
+ * Grade a `clientCapabilities` validator against the gadget-wire
+ * schema-conformance catalog.
+ *
+ * `validate` MUST return `true` iff its parser accepts the input as a
+ * well-formed `DataContract.clientCapabilities`, `false` otherwise.
+ * The kit deliberately does NOT import a concrete schema — adopters
+ * pass their own parser (a zod `safeParse`, a Go struct decode, a
+ * pydantic model) and the catalog grades it. A conformant validator
+ * produces an empty `failed` array.
+ *
+ * `validate` is invoked exactly once per case; it MUST be pure and
+ * MUST NOT throw (a throwing parser is itself non-conformant — wrap
+ * it). Cases are graded in {@link gadgetWireSchemaCases} order.
+ */
+export declare function runSchemaConformance(validate: (clientCapabilities: unknown) => boolean): SchemaConformanceResult;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schema-conformance/index.ts"],"names":[],"mappings":"AA+CA;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,qBAAqB,EAajE,CAAC;AAEF,2CAA2C;AAC3C,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACvC,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACrC,qEAAqE;IACrE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,0DAA0D;AAC1D,MAAM,WAAW,uBAAuB;IACtC,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,SAAS,yBAAyB,EAAE,CAAC;CACvD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,CAAC,kBAAkB,EAAE,OAAO,KAAK,OAAO,GACjD,uBAAuB,CAqBzB"}