@ggui-ai/protocol-conformance 0.2.0-alpha.4 → 0.4.0-rc.0

package/dist/match-behavior.js

@@ -1,36 +1,145 @@
+/**
+ * Match observed WS frames against a fixture's {@link ExpectedBehavior}.
+ *
+ * Each matcher is pure — it consumes a read-only array of frames the
+ * runner collected from the transport and returns either a pass or a
+ * {@link MatchFailure} the runner lifts into a
+ * {@link ConformanceFailure}. No side-effects, no hidden state — the
+ * runner owns orchestration.
+ *
+ * ## Path-A vs Path-B partition
+ *
+ * The kit's behavior vocabulary spans both wire-observable claims (the
+ * subscribe ack, the action ack's persistence sequence, error frames,
+ * stream updates) AND surface-observable claims (DOM state after a
+ * props update, browser-side bootstrap failure modes). This file
+ * matches the **Path-A** subset — the wire-observable behaviors a
+ * runner can assert from frames alone, with no MCP-Apps-host adapter
+ * and no browser page. The Path-B subset (browser-host harness) is
+ * inherently NOT WS-reducible: bootstrap-failure modes are caused by
+ * the renderer-bundle fetch + `ui/initialize` round-trip the host
+ * speaks over postMessage; props-update assertions are assertions on
+ * the rendered DOM the renderer paints, not on WS frames the server
+ * emits. For these kinds we return `unmatchable-on-ws` with a sharp
+ * reason and the runner records SKIP — they are NOT failures of the
+ * server, they are claims a different driver must drive.
+ *
+ * The Path-B driver is not yet packaged — no browser-host harness
+ * ships with the kit today, so Path-B fixtures are skipped wherever
+ * the kit runs. A future packaged browser-host adapter folds that
+ * capability into the kit so third-party adopters don't have to
+ * reimplement it. Until then, the partition is honest: Path A handles
+ * wire claims, Path B is a declared grading gap, and
+ * `unmatchable-on-ws` is the partition seam.
+ *
+ * v1 Path-A scope:
+ *
+ *   - `bootstrap-success` — subscribe produced an `ack` frame. When
+ *     the behavior authors `serverVersion: 'current'`, the ack MUST
+ *     additionally advertise `payload.serverVersion` equal to the
+ *     kit's compiled `PROTOCOL_SCHEMA_VERSION` — the server half of
+ *     SPEC §12.2.2's version handshake (the `version-match` fixture's
+ *     happy-path claim).
+ *   - `version-mismatch` — subscribe produced an `error` frame with
+ *     `code: 'UPGRADE_REQUIRED'` (the generic error-frame read
+ *     narrowed to one code). The provoking client declaration travels
+ *     on the fixture's `subscribe.supportedVersions` knob, not on
+ *     this behavior.
+ *   - `action-ack`     — the action's `ack` frame (matched by echoed
+ *     `requestId`) carries a numeric `payload.sequence` — proof the
+ *     event persisted to the GguiSession's consume buffer.
+ *   - `error-frame`    — an `error` frame with the expected
+ *     `payload.code` (+ optional echoed `requestId`).
+ *   - `stream-update`  — canonical channel-3 delivery frame
+ *     (`{type: 'data', payload: StreamEnvelope}`, SPEC §12.2) whose
+ *     envelope names the declared channel and carries the declared
+ *     value as its `payload` body.
+ *   - `no-op`          — no frames observed after input dispatch.
+ *
+ * One kind is neither Path A nor Path B: `session-state` is a
+ * *stateful* obligation — the input message produces no wire response,
+ * so frames cannot prove it. This module returns `unmatchable-on-ws`
+ * for it; the RUNNER (`run-conformance.ts`) grades it after the
+ * observation window via `ConformanceHost.readSessionField`, reusing
+ * this module's exported {@link deepEqual}. A caller that routes a
+ * `session-state` behavior through the frame matcher gets the honest
+ * skip, never a frame-derived verdict.
+ *
+ * v1 Path-B-only kinds (return `unmatchable-on-ws`):
+ *
+ *   - `bootstrap-failure` — the fault surface lives in the host's
+ *     bootstrap-fetch + `ui/initialize` round-trip; the fixture's
+ *     `renderer-url-override` / `ui-initialize-response-override`
+ *     setup directives are MCP-Apps-host concerns, not WS server
+ *     concerns. The reference server's host adapter correctly throws
+ *     "out of scope" on these directives — that's not a bug, it's
+ *     the partition being respected.
+ *   - `props-update` — the assertion is on rendered DOM after the
+ *     server emits a `_ggui:props` frame; matchable on WS only as
+ *     "frame was emitted", not as "DOM reflects it" — and the fixture
+ *     vocabulary asserts the latter.
+ *
+ * ## Declared grading gap — the `ggui_consume` retrieval half
+ *
+ * `action-ack` proves the append half of the consume-buffer contract.
+ * The retrieval half — the agent draining the buffer via
+ * `ggui_consume({sessionId})` — is an MCP tool call a WS-only runner
+ * cannot drive. Grading it needs an MCP-binding driver; that gap is
+ * declared here rather than papered over with a weaker assertion.
+ */
+import { PROTOCOL_SCHEMA_VERSION } from '@ggui-ai/protocol';
+import { isRecord } from '@ggui-ai/protocol';
+/**
+ * Discriminant narrowing for the extensibly-closed
+ * {@link ExpectedBehavior} union. The `UnknownBehavior` arm's
+ * `kind: string & {}` deliberately widens the discriminant (future
+ * fixture vocabulary must flow through as opaque records), which also
+ * stops TS narrowing on direct literal checks — so the kit dispatches
+ * through this predicate instead of per-site casts. The runtime check
+ * is exactly the literal comparison the predicate claims.
+ */
+export function behaviorIs(behavior, kind) {
+    return behavior.kind === kind;
+}
 export function matchBehavior(behavior, frames) {
-    // Dispatch on the `kind` discriminator with explicit casts because
-    // the extensibly-closed `UnknownBehavior` (`kind: string & {}`) in
-    // the union widens the discriminant, preventing TS from narrowing
-    // on literals. We checked the literal above — the cast is sound.
-    if (behavior.kind === 'bootstrap-success') {
+    // Dispatch on the `kind` discriminator through `behaviorIs` — the
+    // extensibly-closed `UnknownBehavior` (`kind: string & {}`) in the
+    // union widens the discriminant, preventing TS from narrowing on
+    // bare literal checks.
+    if (behaviorIs(behavior, 'bootstrap-success')) {
         return matchBootstrapSuccess(behavior, frames);
     }
-    if (behavior.kind === 'version-mismatch') {
+    if (behaviorIs(behavior, 'version-mismatch')) {
         return matchVersionMismatch(behavior, frames);
     }
-    if (behavior.kind === 'contract-error') {
-        return matchContractError(behavior, frames);
+    if (behaviorIs(behavior, 'action-ack')) {
+        return matchActionAck(behavior, frames);
+    }
+    if (behaviorIs(behavior, 'error-frame')) {
+        return matchErrorFrame(behavior, frames);
     }
-    if (behavior.kind === 'stream-update') {
+    if (behaviorIs(behavior, 'stream-update')) {
         return matchStreamUpdate(behavior, frames);
     }
-    if (behavior.kind === 'no-op') {
+    if (behaviorIs(behavior, 'no-op')) {
         return matchNoOp(behavior, frames);
     }
     if (behavior.kind === 'bootstrap-failure') {
         return {
             kind: 'unmatchable-on-ws',
-            reason: 'bootstrap-failure is a Path-B (browser-host) claim — the fault surface is the host\'s bootstrap-fetch + `ui/initialize` postMessage round-trip, not a WS frame the server emits. The `renderer-url-override` / `ui-initialize-response-override` setup directives are MCP-Apps-host concerns; the reference server\'s host adapter throws "out of scope" on them by design. Drive these fixtures via a Path-B browser-host harness (today: PENDING a new driver; future: packaged Phase-3.2 adapter inside the kit).',
+            reason: 'bootstrap-failure is a Path-B (browser-host) claim — the fault surface is the host\'s bootstrap-fetch + `ui/initialize` postMessage round-trip, not a WS frame the server emits. The `renderer-url-override` / `ui-initialize-response-override` setup directives are MCP-Apps-host concerns; the reference server\'s host adapter throws "out of scope" on them by design. The Path-B driver is not yet packaged — these fixtures skip until a browser-host adapter ships with the kit.',
         };
     }
-    if (behavior.kind === 'observability-event') {
-        return matchObservabilityEvent(behavior, frames);
-    }
     if (behavior.kind === 'props-update') {
         return {
             kind: 'unmatchable-on-ws',
-            reason: 'props-update is a Path-B (browser-host) claim — the assertion is on rendered DOM (selector + attribute/text), not on the `_ggui:props` WS frame in isolation. Matchable on WS only as "frame was emitted"; the fixture vocabulary asserts "DOM reflects the update". Drive via a Path-B browser-host harness; future: packaged Phase-3.2 adapter inside the kit.',
+            reason: 'props-update is a Path-B (browser-host) claim — the assertion is on rendered DOM (selector + attribute/text), not on the `_ggui:props` WS frame in isolation. Matchable on WS only as "frame was emitted"; the fixture vocabulary asserts "DOM reflects the update". The Path-B driver is not yet packaged — this fixture skips until a browser-host adapter ships with the kit.',
+        };
+    }
+    if (behavior.kind === 'session-state') {
+        return {
+            kind: 'unmatchable-on-ws',
+            reason: 'session-state is a stateful obligation — its grade is a post-dispatch read-back of the GguiSession field via `ConformanceHost.readSessionField`, not a WS frame; frames cannot prove state. The runner (`run-conformance.ts`) grades this kind after the observation window; it never reaches the frame matcher there. Reaching here means a caller invoked `matchBehavior` directly on a session-state behavior.',
         };
     }
     // Extensibly-closed union catch — unknown `kind` = new fixture
@@ -43,7 +152,7 @@ export function matchBehavior(behavior, frames) {
 // =============================================================================
 // Per-behavior matchers
 // =============================================================================
-function matchBootstrapSuccess(_behavior, frames) {
+function matchBootstrapSuccess(behavior, frames) {
     const ack = frames.find((f) => f.kind === 'frame' && f.parsed['type'] === 'ack');
     if (ack === undefined) {
         return {
@@ -64,13 +173,32 @@ function matchBootstrapSuccess(_behavior, frames) {
             message: 'expected bootstrap-success but received an error frame — the subscribe was rejected.',
         };
     }
+    // Optional ack-field assertion (`serverVersion: 'current'`) — the
+    // server half of SPEC §12.2.2: a successful ack MUST advertise
+    // `payload.serverVersion` equal to the kit's compiled canonical.
+    // An ack that omits the field is legacy-pass-through on the wire,
+    // but a fixture authoring this assertion is grading the handshake
+    // — silence does not satisfy it.
+    if (behavior.serverVersion === 'current') {
+        const payload = ack.kind === 'frame' ? ack.parsed['payload'] : undefined;
+        const advertised = isRecord(payload) ? payload['serverVersion'] : undefined;
+        if (advertised !== PROTOCOL_SCHEMA_VERSION) {
+            return {
+                kind: 'fail',
+                expected: { type: 'ack', payload: { serverVersion: PROTOCOL_SCHEMA_VERSION } },
+                received: { ackFrame: ack.kind === 'frame' ? ack.parsed : ack },
+                message: advertised === undefined
+                    ? `ack does not advertise \`payload.serverVersion\` — the fixture asserts the SPEC §12.2.2 server half (advertise '${PROTOCOL_SCHEMA_VERSION}' on every successful ack); a versionless ack proves only the pre-handshake subscribe path.`
+                    : `ack advertises \`payload.serverVersion\` ${JSON.stringify(advertised)} but the kit's compiled canonical is '${PROTOCOL_SCHEMA_VERSION}'.`,
+            };
+        }
+    }
     return { kind: 'pass' };
 }
 function matchVersionMismatch(behavior, frames) {
-    const error = frames.find((f) => f.kind === 'frame' &&
-        f.parsed['type'] === 'error' &&
-        isRecord(f.parsed['payload']) &&
-        f.parsed['payload']['code'] === 'UPGRADE_REQUIRED');
+    // The generalized error-frame read narrowed to the version
+    // handshake's canonical rejection code.
+    const error = findErrorFrame(frames, 'UPGRADE_REQUIRED');
     if (error === undefined) {
         return {
             kind: 'fail',
@@ -85,92 +213,111 @@ function matchVersionMismatch(behavior, frames) {
     }
     return { kind: 'pass' };
 }
-function matchContractError(behavior, frames) {
-    const candidates = frames.filter((f) => f.kind === 'frame' &&
-        f.parsed['type'] === 'stream' &&
-        isRecord(f.parsed['payload']) &&
-        f.parsed['payload']['channel'] === '_ggui:contract-error');
-    if (candidates.length === 0) {
+/**
+ * `action-ack` — the ack frame echoing the action's `requestId` MUST
+ * carry a numeric `payload.sequence`: the monotonic event sequence the
+ * server assigned when it appended the action to the GguiSession's
+ * consume buffer. Matching on the echoed `requestId` distinguishes the
+ * action's ack from the subscribe ack the runner's own subscribe frame
+ * produces.
+ */
+function matchActionAck(behavior, frames) {
+    const acks = frames.filter((f) => f.kind === 'frame' &&
+        f.parsed['type'] === 'ack' &&
+        f.parsed['requestId'] === behavior.requestId);
+    if (acks.length === 0) {
         return {
             kind: 'fail',
-            expected: {
-                channel: '_ggui:contract-error',
-                code: behavior.code,
-                toolName: behavior.toolName,
-            },
+            expected: { type: 'ack', requestId: behavior.requestId },
             received: frames.map((f) => (f.kind === 'frame' ? f.parsed : f)),
-            message: 'expected a `stream` frame on the `_ggui:contract-error` reserved channel; none observed.',
+            message: `expected an \`ack\` frame echoing requestId '${behavior.requestId}' after action dispatch; received none.`,
         };
     }
-    // Check at least one candidate carries the expected code + tool.
-    //
-    // Canonical shape per SPEC §4.4 `ContractErrorPayload`: `code` is
-    // NESTED under `value.error.code`, alongside `value.error.message`
-    // and `value.error.causedBy`. `toolName` / `actionName` /
-    // `sourceAction` / `timestamp` live at the top of `value`. The
-    // matcher reads the canonical shape exclusively — the reference
-    // server (and `@ggui-ai/mcp-server`'s router) emits via
-    // `makeContractErrorPayload`, which is the authoritative builder.
-    // Any producer emitting a flat `code` field is a spec violation and
-    // will correctly fail this match — that's the point of Protocol #5
-    // (named failure modes) being assertable.
-    const match = candidates.find((f) => {
+    const match = acks.find((f) => {
         if (f.kind !== 'frame')
             return false;
         const payload = f.parsed['payload'];
-        if (!isRecord(payload))
-            return false;
-        const value = payload['value'];
-        if (!isRecord(value))
-            return false;
-        const error = value['error'];
-        if (!isRecord(error))
-            return false;
-        if (error['code'] !== behavior.code)
-            return false;
-        if (value['toolName'] !== behavior.toolName)
-            return false;
-        if (behavior.actionName !== undefined &&
-            value['actionName'] !== behavior.actionName) {
-            return false;
-        }
-        if (behavior.sourceAction !== undefined) {
-            const source = value['sourceAction'];
-            const sourceType = isRecord(source) ? source['type'] : source;
-            if (sourceType !== behavior.sourceAction)
-                return false;
-        }
-        return true;
+        return isRecord(payload) && typeof payload['sequence'] === 'number';
     });
     if (match === undefined) {
         return {
             kind: 'fail',
             expected: {
-                code: behavior.code,
-                toolName: behavior.toolName,
-                actionName: behavior.actionName,
-                sourceAction: behavior.sourceAction,
+                type: 'ack',
+                requestId: behavior.requestId,
+                payload: { sequence: '<number>' },
             },
-            received: candidates.map((f) => (f.kind === 'frame' ? f.parsed : f)),
-            message: '`_ggui:contract-error` frame observed but payload did not match the expected code/tool/action triple.',
+            received: acks.map((f) => (f.kind === 'frame' ? f.parsed : f)),
+            message: 'action `ack` frame observed but `payload.sequence` is missing or non-numeric — the ack does not prove the event persisted to the consume buffer.',
         };
     }
     return { kind: 'pass' };
 }
+/**
+ * `error-frame` — an `error` frame with the expected `payload.code`
+ * (+ the echoed `requestId` when the fixture declares one).
+ */
+function matchErrorFrame(behavior, frames) {
+    const match = findErrorFrame(frames, behavior.code, behavior.requestId);
+    if (match === undefined) {
+        return {
+            kind: 'fail',
+            expected: {
+                type: 'error',
+                payload: { code: behavior.code },
+                ...(behavior.requestId !== undefined ? { requestId: behavior.requestId } : {}),
+            },
+            received: frames.map((f) => (f.kind === 'frame' ? f.parsed : f)),
+            message: `expected an \`error\` frame with \`payload.code === ${behavior.code}\`${behavior.requestId !== undefined ? ` echoing requestId '${behavior.requestId}'` : ''}; received none.`,
+        };
+    }
+    return { kind: 'pass' };
+}
+/**
+ * `stream-update` — matches the canonical channel-3 delivery frame
+ * (SPEC §12.2): `{type: 'data', payload: StreamEnvelope}`. The
+ * {@link StreamEnvelope} (from `@ggui-ai/protocol`) carries the
+ * channel identity on `channel` and the delivery body on `payload`;
+ * the matcher requires a `data` frame whose envelope names the
+ * declared channel and whose body matches the declared value —
+ * exact deep-equal by default, or declared-keys-subset when the
+ * fixture authors `valueMatch: 'subset'` (see
+ * {@link deepMatchSubset}).
+ *
+ * Two near-miss frames deliberately do NOT match:
+ *   - Any frame whose `type` is not `data` — e.g. the retired
+ *     `{type: 'stream'}` text-chunk frame (left the protocol union
+ *     draft-2026-06-11; an implementation still emitting it never
+ *     satisfies a stream-update expectation).
+ *   - Any `data` frame whose body fails the {@link StreamEnvelope}
+ *     shape (missing `sessionId` / `channel` / `mode`) — a
+ *     non-conformant envelope must not satisfy the assertion.
+ */
 function matchStreamUpdate(behavior, frames) {
-    const match = frames.find((f) => f.kind === 'frame' &&
-        f.parsed['type'] === 'stream' &&
-        isRecord(f.parsed['payload']) &&
-        f.parsed['payload']['channel'] === behavior.channel &&
-        deepEqual(f.parsed['payload']['value'], behavior.value));
+    const envelopes = frames.flatMap((f) => {
+        if (f.kind !== 'frame' || f.parsed['type'] !== 'data')
+            return [];
+        const body = f.parsed['payload'];
+        return isStreamEnvelope(body) ? [body] : [];
+    });
+    // `valueMatch: 'subset'` relaxes the value comparison to "every
+    // declared key is present + matching; extra observed keys ignored".
+    // Default ('exact' / absent) is the exact deep-equal.
+    const subset = behavior.valueMatch === 'subset';
+    const valueMatches = (observed) => subset ? deepMatchSubset(behavior.value, observed) : deepEqual(observed, behavior.value);
+    const match = envelopes.find((envelope) => envelope.channel === behavior.channel && valueMatches(envelope.payload));
     if (match === undefined) {
         return {
             kind: 'fail',
-            expected: { channel: behavior.channel, value: behavior.value },
+            expected: {
+                type: 'data',
+                payload: { channel: behavior.channel, payload: behavior.value },
+                valueMatch: subset ? 'subset' : 'exact',
+            },
             received: frames
-                .filter((f) => f.kind === 'frame' && f.parsed['type'] === 'stream')
-                .map((f) => (f.kind === 'frame' ? f.parsed['payload'] : f)),
-            message: `expected a \`stream\` frame on channel '${behavior.channel}' with the declared value shape; none matched.`,
+                .filter((f) => f.kind === 'frame' && f.parsed['type'] === 'data')
+                .map((f) => (f.kind === 'frame' ? f.parsed : f)),
+            message: `expected a \`data\` frame whose StreamEnvelope names channel '${behavior.channel}' and carries the declared value as its payload (${subset ? 'subset match — every declared key present + matching' : 'exact match'}); none matched.`,
         };
     }
     return { kind: 'pass' };
@@ -192,172 +339,47 @@ function matchNoOp(behavior, frames) {
     }
     return { kind: 'pass' };
 }
+// =============================================================================
+// Helpers
+// =============================================================================
 /**
- * Match an observability-event behavior against WS evidence the
- * protocol-and-contract bar mandates a conformant host mirror-emit on.
- *
- * Two arms are matchable on pure WS today; everything else returns
- * `unmatchable-on-ws` with a sharp reason — see the file-level
- * docstring for the rationale.
+ * Find an `error` frame carrying `payload.code === code` and, when
+ * `requestId` is given, echoing it. Shared by the generic
+ * `error-frame` matcher and the `version-mismatch` arm.
  */
-function matchObservabilityEvent(behavior, frames) {
-    const { event } = behavior;
-    if (event.kind === 'wired-tool-invoked') {
-        return matchWiredToolInvoked(event, frames);
-    }
-    if (event.kind === 'contract-error-emitted') {
-        return matchContractErrorEmitted(event, frames);
-    }
-    return {
-        kind: 'unmatchable-on-ws',
-        reason: `observability-event of kind '${event.kind}' is a Path-B (browser-host) claim — not grounded in WS-observable evidence by the kit's matcher. Drive via a Path-B browser-host harness (today: \`page.exposeBinding\` in spec-side dispatch; future: packaged Phase-3.2 adapter inside the kit).`,
-    };
+function findErrorFrame(frames, code, requestId) {
+    return frames.find((f) => f.kind === 'frame' &&
+        f.parsed['type'] === 'error' &&
+        isRecord(f.parsed['payload']) &&
+        f.parsed['payload']['code'] === code &&
+        (requestId === undefined || f.parsed['requestId'] === requestId));
 }
 /**
- * `wired-tool-invoked` — the WS evidence is a `stream` frame on the
- * canonical `_ggui:wired-tool-invoked` channel carrying
- * `value: {toolName, actionName?}`. The reference server's
- * `action-router.ts::dispatchAction()` emits this after a successful
- * handler resolution; the bar mandates equivalent WS evidence from any
- * conformant host on the wired-tool-invoked path.
+ * Validating narrower for {@link StreamEnvelope} — the body of a
+ * channel-3 `data` frame. Field names come from `@ggui-ai/protocol`
+ * (`types/live-channel`): `sessionId` + `channel` are required
+ * strings, `mode` is the declared state-folding mode
+ * (`'append' | 'replace'`), and the delivery body lives under
+ * `payload`.
  */
-function matchWiredToolInvoked(event, frames) {
-    if (event.toolName === undefined) {
-        return {
-            kind: 'fail',
-            expected: { kind: 'wired-tool-invoked', toolName: '<required>' },
-            received: { event },
-            message: 'observability-event of kind `wired-tool-invoked` MUST declare `toolName` for the matcher to assert against; fixture is under-specified.',
-        };
-    }
-    const candidates = frames.filter((f) => f.kind === 'frame' &&
-        f.parsed['type'] === 'stream' &&
-        isRecord(f.parsed['payload']) &&
-        f.parsed['payload']['channel'] === '_ggui:wired-tool-invoked');
-    if (candidates.length === 0) {
-        return {
-            kind: 'fail',
-            expected: {
-                channel: '_ggui:wired-tool-invoked',
-                value: { toolName: event.toolName, actionName: event.actionName },
-            },
-            received: frames.map((f) => (f.kind === 'frame' ? f.parsed : f)),
-            message: 'expected a `stream` frame on `_ggui:wired-tool-invoked` (the WS-observable evidence the protocol bar mandates a conformant host mirror-emit `wired-tool-invoked` on); none observed.',
-        };
-    }
-    const match = candidates.find((f) => {
-        if (f.kind !== 'frame')
-            return false;
-        const payload = f.parsed['payload'];
-        if (!isRecord(payload))
-            return false;
-        const value = payload['value'];
-        if (!isRecord(value))
-            return false;
-        if (value['toolName'] !== event.toolName)
-            return false;
-        if (event.actionName !== undefined &&
-            value['actionName'] !== event.actionName) {
-            return false;
-        }
-        return true;
-    });
-    if (match === undefined) {
-        return {
-            kind: 'fail',
-            expected: {
-                channel: '_ggui:wired-tool-invoked',
-                value: { toolName: event.toolName, actionName: event.actionName },
-            },
-            received: candidates.map((f) => (f.kind === 'frame' ? f.parsed : f)),
-            message: '`_ggui:wired-tool-invoked` frame observed but value did not match the expected toolName/actionName.',
-        };
-    }
-    return { kind: 'pass' };
+function isStreamEnvelope(value) {
+    if (!isRecord(value))
+        return false;
+    if (typeof value['sessionId'] !== 'string')
+        return false;
+    if (typeof value['channel'] !== 'string')
+        return false;
+    if (value['mode'] !== 'append' && value['mode'] !== 'replace')
+        return false;
+    return 'payload' in value;
 }
 /**
- * `contract-error-emitted` — the WS evidence is the canonical SPEC
- * §4.4 `_ggui:contract-error` envelope itself. Per the bar, every such
- * envelope MUST be mirrored as a `contract-error-emitted` observability
- * event on the host side; asserting on the WS frame is asserting on
- * the cause the bar makes load-bearing for the mirror.
+ * Exact deep-equal — objects must have identical key sets, arrays
+ * identical length + ordered contents. Exported so the runner grades
+ * `session-state` read-backs with the SAME comparison the frame
+ * matchers use — one equality, no matcher/runner drift.
  */
-function matchContractErrorEmitted(event, frames) {
-    if (event.code === undefined || event.toolName === undefined) {
-        return {
-            kind: 'fail',
-            expected: {
-                kind: 'contract-error-emitted',
-                code: event.code ?? '<required>',
-                toolName: event.toolName ?? '<required>',
-            },
-            received: { event },
-            message: 'observability-event of kind `contract-error-emitted` MUST declare both `code` and `toolName` for the matcher to assert against; fixture is under-specified.',
-        };
-    }
-    const candidates = frames.filter((f) => f.kind === 'frame' &&
-        f.parsed['type'] === 'stream' &&
-        isRecord(f.parsed['payload']) &&
-        f.parsed['payload']['channel'] === '_ggui:contract-error');
-    if (candidates.length === 0) {
-        return {
-            kind: 'fail',
-            expected: {
-                channel: '_ggui:contract-error',
-                code: event.code,
-                toolName: event.toolName,
-            },
-            received: frames.map((f) => (f.kind === 'frame' ? f.parsed : f)),
-            message: 'expected a `stream` frame on `_ggui:contract-error` (the WS-observable evidence the protocol bar mandates a conformant host mirror-emit `contract-error-emitted` on); none observed.',
-        };
-    }
-    // Same canonical-shape reader as `matchContractError` — code is
-    // nested under `payload.value.error.code`, toolName at the top of
-    // `payload.value`.
-    const match = candidates.find((f) => {
-        if (f.kind !== 'frame')
-            return false;
-        const payload = f.parsed['payload'];
-        if (!isRecord(payload))
-            return false;
-        const value = payload['value'];
-        if (!isRecord(value))
-            return false;
-        const error = value['error'];
-        if (!isRecord(error))
-            return false;
-        if (error['code'] !== event.code)
-            return false;
-        if (value['toolName'] !== event.toolName)
-            return false;
-        if (event.actionName !== undefined &&
-            value['actionName'] !== event.actionName) {
-            return false;
-        }
-        return true;
-    });
-    if (match === undefined) {
-        return {
-            kind: 'fail',
-            expected: {
-                channel: '_ggui:contract-error',
-                code: event.code,
-                toolName: event.toolName,
-                actionName: event.actionName,
-            },
-            received: candidates.map((f) => (f.kind === 'frame' ? f.parsed : f)),
-            message: '`_ggui:contract-error` frame observed but payload did not match the expected code/tool/action triple for the mandated mirror-emission.',
-        };
-    }
-    return { kind: 'pass' };
-}
-// =============================================================================
-// Helpers
-// =============================================================================
-function isRecord(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-function deepEqual(a, b) {
+export function deepEqual(a, b) {
     if (a === b)
         return true;
     if (typeof a !== typeof b)
@@ -373,13 +395,34 @@ function deepEqual(a, b) {
             return false;
         return a.every((item, i) => deepEqual(item, b[i]));
     }
-    const aObj = a;
-    const bObj = b;
-    const aKeys = Object.keys(aObj).sort();
-    const bKeys = Object.keys(bObj).sort();
+    if (!isRecord(a) || !isRecord(b))
+        return false;
+    const aKeys = Object.keys(a).sort();
+    const bKeys = Object.keys(b).sort();
     if (aKeys.length !== bKeys.length)
         return false;
     if (!aKeys.every((k, i) => k === bKeys[i]))
         return false;
-    return aKeys.every((k) => deepEqual(aObj[k], bObj[k]));
+    return aKeys.every((k) => deepEqual(a[k], b[k]));
+}
+/**
+ * Subset deep-match: every key in `expected` MUST be present and
+ * recursively matching in `actual`; extra keys on `actual` are
+ * ignored. Subset semantics relax ONLY object key sets — primitives
+ * and arrays fall back to exact {@link deepEqual} (an array with a
+ * missing element is a different array, not a subset).
+ *
+ * Backs `StreamUpdateBehavior.valueMatch === 'subset'`: a fixture
+ * pins only the deterministic keys of a payload that also carries
+ * non-deterministic fields (generated ids, timestamps) without
+ * wrongly rejecting a correct server over a random id.
+ */
+function deepMatchSubset(expected, actual) {
+    if (!isRecord(expected)) {
+        // Primitives + arrays: exact match.
+        return deepEqual(expected, actual);
+    }
+    if (!isRecord(actual))
+        return false;
+    return Object.keys(expected).every((k) => k in actual && deepMatchSubset(expected[k], actual[k]));
 }

package/dist/registration-conformance/cases/gate-duplicate-hook.json

@@ -0,0 +1,26 @@
+{
+    "name": "gate-duplicate-hook",
+    "description": "The contract declares the SAME export name (`useCheckout`) under two different packages — `@stripe/ggui-checkout` and `@paypal/ggui-checkout` — and the app registers BOTH `(package, export)` pairs, so registry membership and public-env are clean; the only violation is the cross-package name collision. The boilerplate emits one `import { useCheckout }` per export name, so same-named exports collide in module scope regardless of package (SPEC §7.9). The gate MUST reject with `duplicate_gadget_hook`. Note the wire is package-keyed, so a name cannot repeat WITHIN one package; the hazard is strictly cross-package. Because every pair here resolves cleanly, this case pins NO priority between the duplicate check and the registry/env gates — a conformant implementation may run the checks in any order.",
+    "contract": {
+        "clientCapabilities": {
+            "gadgets": {
+                "@stripe/ggui-checkout": { "useCheckout": {} },
+                "@paypal/ggui-checkout": { "useCheckout": {} }
+            }
+        }
+    },
+    "appGadgets": [
+        {
+            "package": "@stripe/ggui-checkout",
+            "version": "1.0.0",
+            "exports": [{ "hook": "useCheckout" }]
+        },
+        {
+            "package": "@paypal/ggui-checkout",
+            "version": "1.0.0",
+            "exports": [{ "hook": "useCheckout" }]
+        }
+    ],
+    "appPublicEnv": {},
+    "expect": { "outcome": "reject", "code": "duplicate_gadget_hook" }
+}