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

package/dist/run-conformance.js

@@ -6,31 +6,56 @@
  *   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 →
+ *      b. Validate every authored setup/teardown directive against
+ *         the closed `SetupStep` vocabulary (`parseSetupStep`), the
+ *         authored `inputEnvelope` against the closed input-
+ *         envelope dispatch vocabulary (`parseInputEnvelope`), and
+ *         the authored `subscribe` shaping against the closed
+ *         `SubscribeFrameShaping` vocabulary
+ *         (`parseSubscribeShaping`). Unknown / malformed directives
+ *         are fixture-authoring errors — the runner throws, aborting
+ *         the run loudly (NOT a skip, NOT a fail of the
+ *         implementation under test).
+ *      c. If `fixture.setup` non-empty AND `config.host` absent →
  *         skip with "no host provided".
- *      c. Dispatch every setup step via `host.dispatchSetup()`.
+ *      d. 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
+ *      e. Open a WS transport against `config.serverUrl`.
+ *      f. 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
+ *         frame; subscribe is always runner-owned), shaped by the
+ *         fixture's validated `subscribe` knob (`omitAppId`,
+ *         `supportedVersions` with the `'current'` sentinel resolved
+ *         to the kit's compiled `PROTOCOL_SCHEMA_VERSION`).
+ *      g. If the fixture's `inputEnvelope` is a dispatchable C→S
+ *         frame (`action` live-channel dispatch, or
+ *         `host_context_observed` — the validated typed arm), send
+ *         it AFTER subscribe.
+ *      h. 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()`.
+ *      i. Match observed frames against `fixture.expectedBehavior` —
+ *         EXCEPT `session-state`, a stateful obligation with no wire
+ *         response: the runner grades it after the observation window
+ *         by reading the GguiSession field back via
+ *         `host.readSessionField()` (`matchSessionState`). Absent
+ *         host / absent method / a throwing read → skip-with-reason,
+ *         never a weakened pass.
+ *      j. Close the WS.
+ *      k. Dispatch every teardown step via `host.dispatchTeardown()`.
  *         Throw → reporter warning; does NOT flip pass → fail.
- *      k. Record the outcome via reporter + accumulate in result.
+ *         (No teardown vocabulary exists in this kit version, so the
+ *         loop is empty today.)
+ *      l. 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.
+ * failure, props-update) automatically skip via the matcher's
+ * `unmatchable-on-ws` arm.
  */
+import { PROTOCOL_SCHEMA_VERSION } from '@ggui-ai/protocol';
 import { allFixtures, fixturesByContract } from './fixtures/index.js';
-import { matchBehavior } from './match-behavior.js';
+import { isRecord } from '@ggui-ai/protocol';
+import { behaviorIs, deepEqual, matchBehavior } from './match-behavior.js';
 import { openWsTransport } from './ws-transport.js';
 // =============================================================================
 // Runner
@@ -82,23 +107,34 @@ async function runOneFixture(fixture, config, _reporter) {
     if (fixture.skipReason !== null) {
         return { kind: 'skip', reason: fixture.skipReason };
     }
-    if (fixture.setup.length > 0 && config.host === undefined) {
+    // Validate the authored directives BEFORE any host or transport
+    // work. An unknown / malformed directive is a fixture-authoring
+    // error, not a behavior of the implementation under test — the
+    // parse throws a descriptive error that aborts the whole run. The
+    // input envelope goes through the same gate: a malformed
+    // `host_context_observed` frame is a fixture-authoring error, never
+    // a verdict on the server.
+    const setupSteps = fixture.setup.map((step) => parseSetupStep(fixture.name, step));
+    const teardownSteps = (fixture.teardown ?? []).map((step) => parseTeardownStep(fixture.name, step));
+    const inputDispatch = parseInputEnvelope(fixture.name, fixture.inputEnvelope);
+    const subscribeShaping = parseSubscribeShaping(fixture.name, fixture.subscribe);
+    if (setupSteps.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.`,
+            reason: `fixture has ${setupSteps.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) {
+        for (const step of setupSteps) {
             try {
-                await config.host.dispatchSetup(narrowSetupStep(step));
+                await config.host.dispatchSetup(step);
             }
             catch (err) {
                 return {
                     kind: 'skip',
-                    reason: `host refused setup step type='${step.type ?? 'unknown'}': ${String(err.message ?? err)}`,
+                    reason: `host refused setup step kind='${step.kind}': ${String(err.message ?? err)}`,
                 };
             }
         }
@@ -108,33 +144,55 @@ async function runOneFixture(fixture, config, _reporter) {
     try {
         const wsUrl = deriveWsUrl(config.serverUrl);
         transport = await openWsTransport({ kind: 'ws', url: wsUrl, auth: config.auth });
-        const renderId = extractRenderId(fixture);
+        const sessionId = extractSessionId(fixture, setupSteps);
+        // `subscribe` (SubscribeFrameShaping, validated above) shapes the
+        // runner-owned frame: `omitAppId` drops the conventional
+        // `appId: 'conformance'` stamp — the probe for SPEC §12.2's
+        // identity-default resolution — and `supportedVersions` declares
+        // the client half of §12.2.2's version handshake (the `'current'`
+        // sentinel already resolved to the kit's compiled
+        // PROTOCOL_SCHEMA_VERSION).
         transport.send({
             type: 'subscribe',
             payload: {
-                renderId,
-                appId: 'conformance',
+                sessionId,
+                ...(subscribeShaping.omitAppId ? {} : { appId: 'conformance' }),
                 role: 'user',
-                ...(maybeSupportedVersions(fixture.expectedBehavior) ?? {}),
+                ...(subscribeShaping.supportedVersions !== undefined
+                    ? { supportedVersions: subscribeShaping.supportedVersions }
+                    : {}),
             },
             requestId: `conformance-subscribe-${fixture.name}`,
         });
-        if (shouldDispatchInputEnvelope(fixture)) {
-            transport.send(fixture.inputEnvelope);
+        if (inputDispatch.kind !== 'none') {
+            transport.send(inputDispatch.envelope);
         }
         const frames = await transport.observe({
             timeoutMs: config.observationTimeoutMs ?? 2000,
         });
-        const match = matchBehavior(fixture.expectedBehavior, frames);
+        // `session-state` is a stateful obligation — the input message
+        // produced no wire response, so the grade is a post-observation-
+        // window read-back of the GguiSession field via the host, not a
+        // frame match. Every other behavior kind grades against observed
+        // frames. (`behaviorIs` narrows to the specific arm — the
+        // extensibly-closed `UnknownBehavior` in the union has
+        // `kind: string & {}` which defeats bare literal narrowing.)
+        const expectedBehavior = fixture.expectedBehavior;
+        const match = behaviorIs(expectedBehavior, 'session-state')
+            ? await matchSessionState(expectedBehavior, sessionId, config.host)
+            : matchBehavior(expectedBehavior, frames);
         // Dispatch teardown regardless of match outcome. Failures in
         // teardown surface as warnings; they do not flip pass → fail.
-        if (config.host !== undefined && fixture.teardown !== undefined) {
-            for (const step of fixture.teardown) {
+        // (The teardown vocabulary is empty in this kit version, so
+        // `teardownSteps` is always empty today — the loop is the slot
+        // future cleanup directives flow through.)
+        if (config.host !== undefined) {
+            for (const step of teardownSteps) {
                 try {
-                    await config.host.dispatchTeardown(narrowTeardownStep(step));
+                    await config.host.dispatchTeardown(step);
                 }
                 catch (err) {
-                    _reporter.onTeardownWarning?.(fixture.name, `teardown step type='${step.type ?? 'unknown'}' threw: ${String(err.message ?? err)}`);
+                    _reporter.onTeardownWarning?.(fixture.name, `teardown step threw: ${String(err.message ?? err)}`);
                 }
             }
         }
@@ -182,59 +240,303 @@ function filterFixtures(only) {
     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`;
+/**
+ * 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 function deriveWsUrl(serverUrl) {
+    const withScheme = /^(?:https?|wss?):\/\//.test(serverUrl)
+        ? serverUrl
+        : `ws://${serverUrl}`;
+    const url = new URL(withScheme);
+    if (url.protocol === 'http:')
+        url.protocol = 'ws:';
+    if (url.protocol === 'https:')
+        url.protocol = 'wss:';
+    if (url.pathname === '' || url.pathname === '/') {
+        url.pathname = '/ws';
+    }
+    return url.toString();
 }
-function extractRenderId(fixture) {
-    // Prefer a renderId from the first `create-render` setup step —
+function extractSessionId(fixture, setupSteps) {
+    // Prefer a sessionId from the first `create-session` setup step —
     // this is the fixture's declared render identity. Fall back to
-    // inputEnvelope.renderId, then to the fixture name.
-    for (const step of fixture.setup) {
-        if (step.type === 'create-render' &&
-            typeof step.renderId === 'string') {
-            return step.renderId;
-        }
+    // inputEnvelope.sessionId, then to the fixture name.
+    for (const step of setupSteps) {
+        if (step.kind === 'create-session')
+            return step.sessionId;
     }
     const envelope = fixture.inputEnvelope;
-    if (envelope !== null &&
-        typeof envelope === 'object' &&
-        'renderId' in envelope &&
-        typeof envelope.renderId === 'string') {
-        return envelope.renderId;
+    if (isRecord(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.
+ * 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.
  */
-function shouldDispatchInputEnvelope(fixture) {
-    const envelope = fixture.inputEnvelope;
-    if (envelope === null || typeof envelope !== 'object')
-        return false;
-    const type = envelope.type;
-    return type === 'action';
+export function parseInputEnvelope(fixtureName, envelope) {
+    if (!isRecord(envelope) || typeof envelope['type'] !== 'string') {
+        return { kind: 'none' };
+    }
+    if (envelope['type'] === 'action') {
+        return { kind: 'action', envelope };
+    }
+    if (envelope['type'] === 'host_context_observed') {
+        return {
+            kind: 'host_context_observed',
+            envelope: parseHostContextObservedEnvelope(fixtureName, envelope),
+        };
+    }
+    return { kind: 'none' };
+}
+function parseHostContextObservedEnvelope(fixtureName, envelope) {
+    const requestId = envelope['requestId'];
+    if (requestId !== undefined && typeof requestId !== 'string') {
+        throw malformedInputEnvelope(fixtureName, "'requestId' must be a string when present", envelope);
+    }
+    const payload = envelope['payload'];
+    if (!isRecord(payload)) {
+        throw malformedInputEnvelope(fixtureName, "'payload' must be an object carrying {sessionId, hostContext}", envelope);
+    }
+    const sessionId = payload['sessionId'];
+    if (typeof sessionId !== 'string' || sessionId.length === 0) {
+        throw malformedInputEnvelope(fixtureName, "'payload.sessionId' must be a non-empty string", envelope);
+    }
+    const hostContext = parseHostContextProjection(fixtureName, payload['hostContext'], envelope);
+    return {
+        type: 'host_context_observed',
+        ...(requestId !== undefined ? { requestId } : {}),
+        payload: { sessionId, hostContext },
+    };
+}
+/**
+ * Validating narrower for the authored `hostContext` body against the
+ * live `HostContextProjection` (`@ggui-ai/protocol`,
+ * `types/host-context`). Every field is optional, so presence is never
+ * required — but a present field MUST carry the projection's shape,
+ * and unknown keys are REJECTED: a key outside the projection (e.g. a
+ * stale `theme` — theme flows through ggui's theming pipeline, not
+ * host context) is state no conformant server is obligated to read
+ * back, which would make the paired `session-state` grade dishonest.
+ */
+function parseHostContextProjection(fixtureName, value, envelope) {
+    if (!isRecord(value)) {
+        throw malformedInputEnvelope(fixtureName, "'payload.hostContext' must be an object (the HostContextProjection wire shape)", envelope);
+    }
+    const out = {};
+    for (const [key, field] of Object.entries(value)) {
+        switch (key) {
+            case 'availableDisplayModes': {
+                if (!Array.isArray(field)) {
+                    throw malformedInputEnvelope(fixtureName, "'hostContext.availableDisplayModes' must be an array of display modes ('inline' | 'fullscreen' | 'pip')", envelope);
+                }
+                const modes = [];
+                for (const item of field) {
+                    if (!isDisplayMode(item)) {
+                        throw malformedInputEnvelope(fixtureName, `'hostContext.availableDisplayModes' carries ${JSON.stringify(item)} — display modes are 'inline' | 'fullscreen' | 'pip'`, envelope);
+                    }
+                    modes.push(item);
+                }
+                out.availableDisplayModes = modes;
+                break;
+            }
+            case 'currentDisplayMode': {
+                if (!isDisplayMode(field)) {
+                    throw malformedInputEnvelope(fixtureName, "'hostContext.currentDisplayMode' must be 'inline' | 'fullscreen' | 'pip'", envelope);
+                }
+                out.currentDisplayMode = field;
+                break;
+            }
+            case 'containerDimensions': {
+                if (!isRecord(field)) {
+                    throw malformedInputEnvelope(fixtureName, "'hostContext.containerDimensions' must be an object of numeric width/maxWidth/height/maxHeight", envelope);
+                }
+                const dims = {};
+                for (const [dimKey, dimValue] of Object.entries(field)) {
+                    if (dimKey !== 'width' &&
+                        dimKey !== 'maxWidth' &&
+                        dimKey !== 'height' &&
+                        dimKey !== 'maxHeight') {
+                        throw malformedInputEnvelope(fixtureName, `'hostContext.containerDimensions' carries unknown key '${dimKey}' — the projection knows width, maxWidth, height, maxHeight`, envelope);
+                    }
+                    if (typeof dimValue !== 'number') {
+                        throw malformedInputEnvelope(fixtureName, `'hostContext.containerDimensions.${dimKey}' must be a number`, envelope);
+                    }
+                    dims[dimKey] = dimValue;
+                }
+                out.containerDimensions = dims;
+                break;
+            }
+            case 'platform': {
+                if (field !== 'web' && field !== 'desktop' && field !== 'mobile') {
+                    throw malformedInputEnvelope(fixtureName, "'hostContext.platform' must be 'web' | 'desktop' | 'mobile'", envelope);
+                }
+                out.platform = field;
+                break;
+            }
+            case 'deviceCapabilities': {
+                if (!isRecord(field)) {
+                    throw malformedInputEnvelope(fixtureName, "'hostContext.deviceCapabilities' must be an object of boolean touch/hover", envelope);
+                }
+                const caps = {};
+                for (const [capKey, capValue] of Object.entries(field)) {
+                    if (capKey !== 'touch' && capKey !== 'hover') {
+                        throw malformedInputEnvelope(fixtureName, `'hostContext.deviceCapabilities' carries unknown key '${capKey}' — the projection knows touch, hover`, envelope);
+                    }
+                    if (typeof capValue !== 'boolean') {
+                        throw malformedInputEnvelope(fixtureName, `'hostContext.deviceCapabilities.${capKey}' must be a boolean`, envelope);
+                    }
+                    caps[capKey] = capValue;
+                }
+                out.deviceCapabilities = caps;
+                break;
+            }
+            case 'locale': {
+                if (typeof field !== 'string' || field.length === 0) {
+                    throw malformedInputEnvelope(fixtureName, "'hostContext.locale' must be a non-empty string", envelope);
+                }
+                out.locale = field;
+                break;
+            }
+            case 'timeZone': {
+                if (typeof field !== 'string' || field.length === 0) {
+                    throw malformedInputEnvelope(fixtureName, "'hostContext.timeZone' must be a non-empty string", envelope);
+                }
+                out.timeZone = field;
+                break;
+            }
+            default:
+                throw malformedInputEnvelope(fixtureName, `'hostContext' carries unknown key '${key}' — the HostContextProjection vocabulary is availableDisplayModes, currentDisplayMode, containerDimensions, platform, deviceCapabilities, locale, timeZone`, envelope);
+        }
+    }
+    return out;
+}
+function isDisplayMode(value) {
+    return value === 'inline' || value === 'fullscreen' || value === 'pip';
 }
-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;
+function malformedInputEnvelope(fixtureName, problem, envelope) {
+    return new Error(`protocol-conformance: fixture '${fixtureName}' authors a malformed 'host_context_observed' input envelope — ${problem}. Received: ${JSON.stringify(envelope)}`);
+}
+// =============================================================================
+// Session-state grading (the kit's third grading mechanism)
+// =============================================================================
+/**
+ * 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 async function matchSessionState(behavior, sessionId, host) {
+    if (host === undefined || host.readSessionField === undefined) {
+        return {
+            kind: 'unmatchable-on-ws',
+            reason: host === undefined
+                ? 'session-state expectation needs a ConformanceHost with readSessionField() — no host was provided.'
+                : 'session-state expectation needs ConformanceHost.readSessionField() — the provided host does not implement it, so the kit cannot observe the GguiSession-field mutation. SKIP, not a pass.',
+        };
+    }
+    let actual;
+    try {
+        actual = await host.readSessionField(sessionId, behavior.field);
+    }
+    catch (err) {
+        return {
+            kind: 'unmatchable-on-ws',
+            reason: `host.readSessionField('${sessionId}', '${behavior.field}') threw — a host that cannot read state cannot grade it: ${String(err.message ?? err)}`,
+        };
+    }
+    if (deepEqual(actual, behavior.expected)) {
+        return { kind: 'pass' };
+    }
+    return {
+        kind: 'fail',
+        expected: { field: behavior.field, value: behavior.expected },
+        received: { field: behavior.field, value: actual },
+        message: `session field '${behavior.field}' did not hold the expected value after the input envelope was dispatched — the implementation under test may have dropped the message instead of persisting it.`,
+    };
+}
+/**
+ * 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 function parseSubscribeShaping(fixtureName, shaping) {
+    if (shaping === undefined)
+        return { omitAppId: false };
+    if (!isRecord(shaping)) {
+        throw malformedSubscribeShaping(fixtureName, 'expected an object carrying the SubscribeFrameShaping fields', shaping);
+    }
+    for (const key of Object.keys(shaping)) {
+        if (key !== 'omitAppId' && key !== 'supportedVersions') {
+            throw malformedSubscribeShaping(fixtureName, `unknown key '${key}' — the subscribe-shaping vocabulary is closed: omitAppId, supportedVersions`, shaping);
+        }
+    }
+    const omitAppId = shaping['omitAppId'];
+    if (omitAppId !== undefined && typeof omitAppId !== 'boolean') {
+        throw malformedSubscribeShaping(fixtureName, "'omitAppId' must be a boolean when present", shaping);
+    }
+    const supportedVersions = parseSupportedVersionsDecl(fixtureName, shaping, shaping['supportedVersions']);
+    return {
+        omitAppId: omitAppId === true,
+        ...(supportedVersions !== undefined ? { supportedVersions } : {}),
+    };
+}
+function parseSupportedVersionsDecl(fixtureName, shaping, decl) {
+    if (decl === undefined)
+        return undefined;
+    if (decl === 'current') {
+        // The evergreen sentinel — the version this kit release was
+        // compiled against, never a stale fixture literal.
+        return [PROTOCOL_SCHEMA_VERSION];
+    }
+    if (Array.isArray(decl) &&
+        decl.length > 0 &&
+        decl.every((version) => typeof version === 'string' && version.length > 0)) {
+        return decl;
+    }
+    throw malformedSubscribeShaping(fixtureName, "'supportedVersions' must be the sentinel 'current' or a non-empty array of non-empty strings", shaping);
+}
+function malformedSubscribeShaping(fixtureName, problem, shaping) {
+    return new Error(`protocol-conformance: fixture '${fixtureName}' authors a malformed 'subscribe' frame shaping — ${problem}. Received: ${JSON.stringify(shaping)}`);
 }
 /**
  * Map fixture name → the bar criterion it exercises, for the
@@ -253,34 +555,170 @@ 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 'consume-buffer':
+            return 'Single action-routing model — consume-buffer persistence + declared-action contract (name membership + payload schema)';
+        case 'host-context':
+            return 'Host-context persistence — host_context_observed MUST persist onto GguiSession.hostContext';
         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)';
+        case 'subscribe-tenancy':
+            return 'SPEC §12.2 subscribe tenancy — appId MUST match the bound app (§12.2.3 APP_MISMATCH)';
         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.
+ * 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.
  */
-function narrowSetupStep(step) {
-    const raw = step;
-    const { type, ...rest } = raw;
-    return { kind: type ?? 'unknown', ...rest };
+export function parseSetupStep(fixtureName, step) {
+    if (!isRecord(step) || typeof step['type'] !== 'string') {
+        throw new Error(`protocol-conformance: fixture '${fixtureName}' authors a malformed setup directive — expected an object with a string 'type'. Received: ${JSON.stringify(step)}`);
+    }
+    const type = step['type'];
+    if (type === 'create-session') {
+        const sessionId = requireStringField(fixtureName, type, step, 'sessionId');
+        const appId = step['appId'];
+        if (appId !== undefined && typeof appId !== 'string') {
+            throw malformedDirective(fixtureName, type, step, "'appId' must be a string when present");
+        }
+        const actionSpec = step['actionSpec'];
+        if (actionSpec !== undefined && !isActionSpecDecl(actionSpec)) {
+            throw malformedDirective(fixtureName, type, step, "'actionSpec' must be an object mapping action names to entry objects (each entry's optional 'schema' a shape-valid JSON-Schema node) when present");
+        }
+        return {
+            kind: 'create-session',
+            sessionId,
+            ...(appId !== undefined ? { appId } : {}),
+            ...(actionSpec !== undefined ? { actionSpec } : {}),
+        };
+    }
+    if (type === 'renderer-url-override') {
+        return {
+            kind: 'renderer-url-override',
+            sessionId: requireStringField(fixtureName, type, step, 'sessionId'),
+            url: requireStringField(fixtureName, type, step, 'url'),
+        };
+    }
+    if (type === 'server-version-override') {
+        return {
+            kind: 'server-version-override',
+            sessionId: requireStringField(fixtureName, type, step, 'sessionId'),
+            advertiseVersion: requireStringField(fixtureName, type, step, 'advertiseVersion'),
+        };
+    }
+    if (type === 'ui-initialize-response-override') {
+        const sessionId = requireStringField(fixtureName, type, step, 'sessionId');
+        if (!('override' in step)) {
+            throw malformedDirective(fixtureName, type, step, "missing the 'override' response body");
+        }
+        return { kind: 'ui-initialize-response-override', sessionId, override: step['override'] };
+    }
+    if (type === 'emit-envelope') {
+        const channel = requireStringField(fixtureName, type, step, 'channel');
+        if (!('payload' in step)) {
+            throw malformedDirective(fixtureName, type, step, "missing the 'payload' envelope body");
+        }
+        return { kind: 'emit-envelope', channel, payload: step['payload'] };
+    }
+    throw new Error(`protocol-conformance: fixture '${fixtureName}' authors unknown setup directive type='${type}'. The setup vocabulary is closed; known directives: create-session, renderer-url-override, server-version-override, ui-initialize-response-override, emit-envelope.`);
+}
+/**
+ * Teardown counterpart of {@link parseSetupStep}. The teardown
+ * vocabulary is empty in this kit version (renders decay via TTL), so
+ * ANY authored teardown directive is a fixture-authoring error.
+ */
+function parseTeardownStep(fixtureName, step) {
+    throw new Error(`protocol-conformance: fixture '${fixtureName}' authors a teardown directive, but this kit version defines no teardown vocabulary (renders decay via TTL). Received: ${JSON.stringify(step)}`);
+}
+function requireStringField(fixtureName, directiveType, step, field) {
+    const value = step[field];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw malformedDirective(fixtureName, directiveType, step, `'${field}' must be a non-empty string`);
+    }
+    return value;
+}
+function malformedDirective(fixtureName, directiveType, step, problem) {
+    return new Error(`protocol-conformance: fixture '${fixtureName}' authors a malformed '${directiveType}' setup directive — ${problem}. Received: ${JSON.stringify(step)}`);
+}
+/**
+ * Validating narrower for `CreateGguiSessionStep.actionSpec`. Each
+ * entry must be an object whose optional `schema` field — when
+ * authored — is a shape-valid {@link JsonSchemaDecl} per
+ * {@link isJsonSchemaDecl}.
+ */
+function isActionSpecDecl(value) {
+    return (isRecord(value) &&
+        Object.values(value).every((entry) => isRecord(entry) &&
+            (entry['schema'] === undefined || isJsonSchemaDecl(entry['schema']))));
 }
-function narrowTeardownStep(step) {
-    const raw = step;
-    const { type, ...rest } = raw;
-    return { kind: type ?? 'unknown', ...rest };
+/** The `type` keyword values the kit's authored JSON-Schema subset names. */
+const JSON_SCHEMA_DECL_TYPES = [
+    'string',
+    'number',
+    'integer',
+    'boolean',
+    'array',
+    'object',
+    'null',
+];
+/**
+ * Validating parse for the typed core of {@link JsonSchemaDecl} —
+ * recursively checks that every keyword the kit's authored vocabulary
+ * names carries the shape the type declares. Keywords outside the
+ * typed core pass through verbatim (the implementation under test
+ * owns their interpretation), mirroring the index-signature tail on
+ * the declared type. A fixture authoring a malformed schema node is a
+ * fixture-authoring error the runner throws on — never a skip or a
+ * fail of the implementation under test.
+ */
+function isJsonSchemaDecl(value) {
+    if (!isRecord(value))
+        return false;
+    if (value['type'] !== undefined && !JSON_SCHEMA_DECL_TYPES.includes(value['type'])) {
+        return false;
+    }
+    if (value['description'] !== undefined && typeof value['description'] !== 'string') {
+        return false;
+    }
+    if (value['enum'] !== undefined && !Array.isArray(value['enum']))
+        return false;
+    if (value['items'] !== undefined && !isJsonSchemaDecl(value['items']))
+        return false;
+    const properties = value['properties'];
+    if (properties !== undefined) {
+        if (!isRecord(properties))
+            return false;
+        if (!Object.values(properties).every(isJsonSchemaDecl))
+            return false;
+    }
+    const required = value['required'];
+    if (required !== undefined &&
+        !(Array.isArray(required) && required.every((name) => typeof name === 'string'))) {
+        return false;
+    }
+    const additionalProperties = value['additionalProperties'];
+    if (additionalProperties !== undefined &&
+        typeof additionalProperties !== 'boolean' &&
+        !isJsonSchemaDecl(additionalProperties)) {
+        return false;
+    }
+    return true;
 }