@specific.dev/spectest 0.109.1 → 0.110.0

package/dist/components/replayFake.js

@@ -31,10 +31,9 @@
 // with our in-VM-CA leaf; the upstream leg is a genuine public-cert TLS
 // handshake to the real host.
 //
-// Mode is chosen by `isRecording()`: it is true only inside an active
-// recorder (a `spectest test` case), false in eval/manual. So `auto`
-// (the default) replays under test and records during manual use — no new
-// control-plane mode flag. `mode: "record" | "replay"` overrides it.
+// Mode belongs to the environment, not the per-case event recorder. Tests
+// and shared baselines always replay, including startup and between cases.
+// Interactive environments record unless `mode: "replay"` is requested.
 // An optional custom handler can return scripted responses or explicitly
 // delegate with ctx.replay(request). Only delegated traffic uses this engine.
 //
@@ -62,8 +61,11 @@ import { request as httpsRequest } from "node:https";
 import path from "node:path";
 import { brotliDecompressSync, gunzipSync, inflateSync } from "node:zlib";
 import * as dnsPacket from "dns-packet";
-import { isRecording } from "../recorder.js";
+import { resolveReplayMode } from "../replay-mode.js";
+import { getWebSocketLifetime } from "../harness/fake-websocket-lifetime.js";
+import { reportBackgroundFailure } from "../harness/background-failures.js";
 import { getRecordSecret } from "../record-secrets.js";
+import { recordWebSocket, replayWebSocket, validateWebSocketKey, validateWebSocketRecording, websocketMatcher, } from "./replay-websocket.js";
 import { replaySignature } from "./replay-key.js";
 import { inferSigV4Scope, signAwsV4Request, } from "../aws-sigv4.js";
 // ────────────────────────────────────────────────────────────────────────
@@ -162,6 +164,7 @@ function coerceCassette(parsed, name, host) {
         fake: parsed.fake ?? name,
         host: parsed.host ?? host,
         interactions: structuredClone(parsed.interactions),
+        ...(parsed.websockets !== undefined ? { websockets: structuredClone(parsed.websockets) } : {}),
     };
 }
 /** Read a cassette by its path relative to `spectest/tests/` (e.g.
@@ -411,18 +414,17 @@ export function replayFake(opts) {
     if (opts.key !== undefined && typeof opts.key !== "function") {
         throw new Error(`replayFake(${opts.name}): \`key\` must be a synchronous function`);
     }
+    validateWebSocketKey(opts.websocketKey);
+    const websocketTimeoutMs = opts.websocketTimeoutMs ?? 30_000;
+    if (!Number.isFinite(websocketTimeoutMs) || websocketTimeoutMs <= 0 || websocketTimeoutMs > 2_147_483_647) {
+        throw new Error(`replayFake(${opts.name}): websocketTimeoutMs must be positive and at most 2147483647`);
+    }
     const injectRules = opts.inject ?? [];
     // Refs every header template references — the control plane resolves these
     // server-side and pushes them for the environment lifetime (see the daemon's
     // /record-secret-refs endpoint, which reads `def.secretRefs`).
     const secretRefs = collectSecretRefs(injectRules, opts.sign);
-    const resolveMode = () => {
-        if (opts.mode === "record")
-            return "record";
-        if (opts.mode === "replay")
-            return "replay";
-        return isRecording() ? "replay" : "record";
-    };
+    const resolveMode = () => resolveReplayMode(opts.mode);
     // ── REPLAY ──────────────────────────────────────────────────────────
     function signature(request, location) {
         try {
@@ -673,6 +675,83 @@ export function replayFake(opts) {
             return replay(reqLike, state);
         return record(req, url, reqLike, bodyBytes, state);
     };
+    const websocket = async (req, state) => {
+        const url = new URL(req.url);
+        const request = {
+            method: req.method.toUpperCase(), path: url.pathname,
+            query: normalizeQuery(url.searchParams, opts.sign !== undefined),
+            headers: recordable(req.headers, [...req.headers.keys()].filter(k => !["sec-websocket-key", "sec-websocket-accept"].includes(k))),
+        };
+        const sig = signature(request, "WebSocket handshake");
+        const match = websocketMatcher(opts.websocketKey);
+        const lifetime = getWebSocketLifetime(req);
+        const track = (session) => {
+            if (!lifetime.ended)
+                state.websocketSessions.add(session);
+        };
+        const finished = (session, error) => {
+            state.websocketSessions.delete(session);
+            if (error) {
+                state.websocketErrors.push(error.message);
+                reportBackgroundFailure(error);
+            }
+        };
+        const offered = (req.headers.get("sec-websocket-protocol") ?? "").split(",").map(p => p.trim()).filter(Boolean);
+        if (resolveMode() === "replay") {
+            const position = state.websocketCursor.get(sig) ?? 0;
+            const index = state.websocketIndex.get(sig)?.[position];
+            const label = `replayFake(${opts.name}) WebSocket ${sig} connection #${position + 1}`;
+            if (index === undefined) {
+                const error = `${label}: no recording available (handshake unmatched or exhausted)`;
+                state.websocketErrors.push(error);
+                reportBackgroundFailure(new Error(error));
+                return new Response(error, { status: 599 });
+            }
+            const recording = state.cassette.websockets[index];
+            if (recording.protocol && !offered.includes(recording.protocol)) {
+                throw new Error(`${label}: client did not offer recorded subprotocol`);
+            }
+            const { handlers, session } = replayWebSocket({ recording, match, label, timeoutMs: websocketTimeoutMs, lifetime, finished });
+            state.websocketCursor.set(sig, position + 1);
+            track(session);
+            return handlers;
+        }
+        if (opts.sign)
+            throw new Error(`replayFake(${opts.name}): SigV4 WebSocket signing is not supported`);
+        const rule = injectRules.find(r => ruleMatches(r.match, {
+            method: request.method, path: request.path, query: url.searchParams, headers: req.headers,
+        }));
+        const brokered = rule ? brokerHeaders(rule) : { headers: {}, secrets: [], missing: [] };
+        if (brokered.missing.length)
+            throw new Error(`replayFake(${opts.name}): missing WebSocket secrets ${brokered.missing.join(", ")}`);
+        const redact = makeRedactor(brokered.secrets, opts.redactPatterns);
+        const storedRequest = {
+            ...request,
+            query: Object.fromEntries(Object.entries(request.query).map(([k, v]) => [k, v.map(redact)])),
+            headers: Object.fromEntries(Object.entries(request.headers).map(([k, v]) => [k, redact(v)])),
+        };
+        for (const { ref, value } of brokered.secrets)
+            if (value && JSON.stringify(storedRequest).includes(value))
+                throw new Error(`replayFake(${opts.name}): secret ${ref} survived WebSocket handshake redaction`);
+        const ips = await resolveExternalA(new URL(`https://${host}`).hostname);
+        if (!ips.length)
+            throw new Error(`replayFake(${opts.name}): could not resolve real upstream ${host}`);
+        const headers = {};
+        req.headers.forEach((v, k) => {
+            if (!STRIP_FORWARD_HEADERS.has(k) && !k.startsWith("sec-websocket-"))
+                headers[k] = v;
+        });
+        Object.assign(headers, brokered.headers);
+        const { handlers, session } = await recordWebSocket({
+            url: `wss://${host}${url.pathname}${url.search}`, ip: ips[0], host, headers, protocols: offered,
+            request: storedRequest, match, redact, secrets: brokered.secrets,
+            label: `replayFake(${opts.name}) WebSocket ${sig} connection #${state.recordedWebSockets.length + 1}`,
+            captured(recording) { state.recordedWebSockets.push(recording); state.dirty = true; },
+            lifetime, finished,
+        });
+        track(session);
+        return handlers;
+    };
     const replayHelpers = (state) => ({
         replay(file) {
             let loaded;
@@ -700,12 +779,29 @@ export function replayFake(opts) {
                 else
                     index.set(sig, [i]);
             }
+            const websocketIndex = new Map();
+            if (loaded.websockets !== undefined && !Array.isArray(loaded.websockets))
+                throw new Error("cassette websockets must be an array");
+            for (const [i, recording] of (loaded.websockets ?? []).entries()) {
+                validateWebSocketRecording(recording);
+                const sig = signature(recording.request, `WebSocket connection #${i + 1}`);
+                const queue = websocketIndex.get(sig);
+                if (queue)
+                    queue.push(i);
+                else
+                    websocketIndex.set(sig, [i]);
+            }
+            if (state.websocketSessions.size)
+                throw new Error("close active WebSockets before loading a cassette");
+            state.websocketIndex = websocketIndex;
+            state.websocketCursor = new Map();
+            state.websocketErrors = [];
             // Mutate the live state object (the handler reads the same
             // reference); reset the cursor so replay starts from the top.
             state.cassette = loaded;
             state.index = index;
             state.cursor = new Map();
-            return { cassette: label, host: loaded.host, interactions: loaded.interactions.length };
+            return { cassette: label, host: loaded.host, interactions: loaded.interactions.length, ...(loaded.websockets ? { websockets: loaded.websockets.length } : {}) };
         },
         dump() {
             return structuredClone({
@@ -713,6 +809,9 @@ export function replayFake(opts) {
                 fake: opts.name,
                 host,
                 interactions: [...state.cassette.interactions, ...state.recorded],
+                ...((state.cassette.websockets?.length || state.recordedWebSockets.length) ? {
+                    websockets: [...(state.cassette.websockets ?? []), ...state.recordedWebSockets],
+                } : {}),
             });
         },
         recorded() {
@@ -728,12 +827,15 @@ export function replayFake(opts) {
         cursor: new Map(),
         recorded: [],
         dirty: false,
+        websocketIndex: new Map(), websocketCursor: new Map(), recordedWebSockets: [],
+        websocketSessions: new Set(), websocketErrors: [],
         custom,
     });
     const def = {
         name: opts.name,
         hostnames: [host],
         secretRefs,
+        websocket,
         state: () => opts.state
             ? Promise.resolve(opts.state()).then(initialState)
             : initialState(undefined),

package/dist/daemon.js

@@ -1,3 +1,4 @@
+import { runWithBackgroundFailures } from "./harness/background-failures.js";
 import { generateHostCert as mintHostCert } from "./harness/certificate.js";
 import { componentBuildTasks, COMPONENT_RUNTIME } from "./harness/component-images.js";
 import { waitForAll } from "./harness/concurrency.js";
@@ -77,6 +78,7 @@ import { trackHelpers } from "./helper-tracking.js";
 import { isRecording, recordEnv, recordExec, recordStep, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, startRecording, stopRecording, truncateUtf8, } from "./recorder.js";
 import { readRaw, wrap } from "./inspect.js";
 import { setRecordSecrets } from "./record-secrets.js";
+import { setReplayEnvironmentMode } from "./replay-mode.js";
 import { encodeReplayBundle, replayChunk } from "./replay-bundle.js";
 function namedServices(cfg) {
     return Object.entries(cfg.services).map(([name, def]) => ({ name, ...def, image: normalizeServiceImage(def.image) }));
@@ -4470,10 +4472,10 @@ async function runOne(testCase) {
     // drains) so we hoist these out of the try/catch.
     let outcome = { status: "passed" };
     try {
-        const value = await Promise.race([
+        const value = await runWithBackgroundFailures(() => Promise.race([
             Promise.resolve(runInstrumented(fetchScope, async () => { await nativeAndroid.begin(Object.values(base.svc).filter(isAndroidApp)); return testCase.run(ctx); })),
             timedOut,
-        ]);
+        ]));
         // Stash the return value so child cases — which fork from the snapshot
         // we're about to capture — can read it off ctx.parent.
         TEST_DATA.set(testCase.id, value);
@@ -5142,6 +5144,7 @@ export function harnessMethods(state) {
             // Optional discovery: old SDKs omit this field and are never sent the
             // new method. Check the loaded project, including after warm restore.
             setupInteractive: typeof loaded?.project.setupInteractive === "function",
+            replayEnvironmentMode: true,
         }),
         // Live bootstrap progress, polled by the control plane during
         // `bootstrap` and streamed into the test-run row. `{}` before the
@@ -5241,6 +5244,16 @@ export function harnessMethods(state) {
             }
             return { refs: [...refs], environmentScoped: true };
         },
+        setReplayEnvironmentMode: async (params) => {
+            if (params.mode !== "test" && params.mode !== "interactive") {
+                throw badRequest("mode must be test or interactive");
+            }
+            if (state.inFlightTest || state.inFlightBootstrap || state.inFlightProjectSetup) {
+                throw conflict("cannot change replay mode while work is in progress");
+            }
+            setReplayEnvironmentMode(params.mode);
+            return { ok: true };
+        },
         setRecordSecrets: async (params) => {
             configureSecrets(params);
             return { ok: true };
@@ -5319,6 +5332,8 @@ export function harnessMethods(state) {
             if (!tc)
                 throw notFound(`unknown caseId: ${caseId}`);
             return exclusive(state, "inFlightTest", "another test is already running", async () => {
+                // A manually invoked case also stays in replay after its recorder stops.
+                setReplayEnvironmentMode("test");
                 const result = await runOne(tc);
                 // Recordings go out-of-band: encode and park the bundle, reply with
                 // a size ref only. A bundle-encoding failure drops the recordings

package/dist/fake-websocket.d.ts

@@ -3,6 +3,8 @@ export interface FakeWebSocket {
     readonly readyState: number;
     send(message: string | Uint8Array | ArrayBuffer): void;
     close(code?: number, reason?: string): void;
+    /** Abrupt transport closure (no close frame), used for recorded disconnects. */
+    terminate?(): void;
 }
 /** Returned by a fake's websocket handshake callback to accept a connection.
  * Callbacks run in order per connection, including async callbacks. Capture

package/dist/harness/background-failures.d.ts

@@ -0,0 +1,2 @@
+export declare function reportBackgroundFailure(error: unknown): void;
+export declare function runWithBackgroundFailures<T>(run: () => Promise<T>): Promise<T>;

package/dist/harness/background-failures.js

@@ -0,0 +1,19 @@
+// The harness runs one test at a time. Transport callbacks run outside the
+// test's async stack, so report their failures through its existing race.
+let rejectActiveTest;
+export function reportBackgroundFailure(error) {
+    const failure = error instanceof Error ? error : new Error(String(error));
+    console.error("[spectest] background callback failed:", failure);
+    rejectActiveTest?.(failure);
+}
+export async function runWithBackgroundFailures(run) {
+    if (rejectActiveTest)
+        throw new Error("A test is already handling background failures");
+    const failed = new Promise((_resolve, reject) => { rejectActiveTest = reject; });
+    try {
+        return await Promise.race([failed, Promise.resolve().then(run)]);
+    }
+    finally {
+        rejectActiveTest = undefined;
+    }
+}

package/dist/harness/fake-websocket-connection.d.ts

@@ -1,5 +1,5 @@
 import type WebSocket from "ws";
 import type { FakeWebSocketHandlers } from "../fake-websocket.js";
-/** Serialize async fake callbacks without allowing a slow handler or peer to
- * retain unbounded audio. A handler failure closes just this connection. */
+/** Serialize callbacks, but release connection resources immediately when the
+ * transport ends, even if an async callback is still running. */
 export declare function attachFakeWebSocket(ws: WebSocket, handlers: FakeWebSocketHandlers): void;

package/dist/harness/fake-websocket-connection.js

@@ -1,12 +1,30 @@
+import { getWebSocketLifetime } from "./fake-websocket-lifetime.js";
+import { reportBackgroundFailure } from "./background-failures.js";
 const MAX_BUFFER = 16 * 1024 * 1024;
 const MAX_PENDING = 1024;
-/** Serialize async fake callbacks without allowing a slow handler or peer to
- * retain unbounded audio. A handler failure closes just this connection. */
+/** Serialize callbacks, but release connection resources immediately when the
+ * transport ends, even if an async callback is still running. */
 export function attachFakeWebSocket(ws, handlers) {
-    let tail = Promise.resolve();
-    let pending = 0;
+    const lifetime = getWebSocketLifetime(handlers);
+    const queue = [];
+    let running = false;
+    let inFlightBytes = 0;
     let bytes = 0;
     let failed = false;
+    lifetime.onEnd(() => { queue.length = 0; bytes = inFlightBytes; });
+    const fail = (err, code = 1011, reason = "fake handler failed") => {
+        if (failed)
+            return;
+        failed = true;
+        reportBackgroundFailure(err);
+        lifetime.end({ kind: "failed", error: err });
+        try {
+            ws.close(code, reason);
+        }
+        catch {
+            ws.terminate();
+        }
+    };
     const socket = {
         get readyState() { return ws.readyState; },
         send(message) {
@@ -14,45 +32,61 @@ export function attachFakeWebSocket(ws, handlers) {
                 throw new Error("WebSocket is not open");
             const size = typeof message === "string" ? Buffer.byteLength(message) : message.byteLength;
             if (ws.bufferedAmount + size > MAX_BUFFER) {
-                failed = true;
-                ws.close(1009, "fake output buffer exceeded");
-                throw new Error("fake WebSocket output buffer exceeded");
+                const error = new Error("fake WebSocket output buffer exceeded");
+                fail(error, 1009, "fake output buffer exceeded");
+                throw error;
             }
             ws.send(message);
         },
         close: (code, reason) => ws.close(code, reason),
+        terminate: () => ws.terminate(),
     };
-    const fail = (err) => {
-        failed = true;
-        console.error("[spectest] fake WebSocket callback failed:", err);
+    const drain = async () => {
+        if (running)
+            return;
+        running = true;
         try {
-            ws.close(1011, "fake handler failed");
+            while (queue.length) {
+                const task = queue.shift();
+                inFlightBytes = task.size;
+                try {
+                    await task.run();
+                }
+                catch (error) {
+                    fail(error);
+                }
+                finally {
+                    bytes -= task.size;
+                    inFlightBytes = 0;
+                }
+            }
         }
-        catch {
-            ws.terminate();
+        finally {
+            running = false;
         }
     };
-    const enqueue = (fn, size = 0, closing = false) => {
-        if (failed && !closing)
+    const enqueue = (run, size = 0, closing = false) => {
+        if (lifetime.ended && !closing)
             return;
-        if (!closing && (pending >= MAX_PENDING || bytes + size > MAX_BUFFER)) {
-            failed = true;
-            ws.close(1009, "fake input buffer exceeded");
+        if (!closing && (queue.length + Number(running) >= MAX_PENDING || bytes + size > MAX_BUFFER)) {
+            fail(new Error("fake WebSocket input buffer exceeded"), 1009, "fake input buffer exceeded");
             return;
         }
-        pending++;
+        queue.push({ run, size });
         bytes += size;
-        tail = tail.then(async () => {
-            if (!failed || closing)
-                await fn();
-        }).catch(fail).finally(() => { pending--; bytes -= size; });
+        void drain();
     };
     ws.on("message", (data, binary) => {
         const buffer = Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data);
-        const message = binary ? new Uint8Array(buffer) : buffer.toString();
-        enqueue(() => handlers.message?.(socket, message), buffer.length);
+        enqueue(() => handlers.message?.(socket, binary ? new Uint8Array(buffer) : buffer.toString()), buffer.length);
+    });
+    ws.on("close", (code, reason) => {
+        lifetime.end({ kind: "closed", code, reason: reason.toString() });
+        enqueue(() => handlers.close?.(socket, code, reason.toString()), 0, true);
     });
-    ws.on("close", (code, reason) => enqueue(() => handlers.close?.(socket, code, reason.toString()), 0, true));
     ws.on("error", fail);
-    enqueue(() => handlers.open?.(socket));
+    if (lifetime.ended)
+        ws.terminate();
+    else
+        enqueue(() => handlers.open?.(socket));
 }

package/dist/harness/fake-websocket-lifetime.d.ts

@@ -0,0 +1,22 @@
+import type { FakeWebSocketHandlers } from "../fake-websocket.js";
+export type WebSocketEnd = {
+    kind: "closed";
+    code: number;
+    reason: string;
+} | {
+    kind: "failed";
+    error: unknown;
+} | {
+    kind: "aborted";
+};
+/** Internal connection ownership, independent of serialized user callbacks.
+ * Runs once on disconnect, failure or abandoned handshake, never at test end. */
+export declare class FakeWebSocketLifetime {
+    private result?;
+    private callbacks;
+    get ended(): boolean;
+    onEnd(callback: (event: WebSocketEnd) => void): () => void;
+    end(event: WebSocketEnd): void;
+}
+export declare function getWebSocketLifetime(target: Request | FakeWebSocketHandlers): FakeWebSocketLifetime;
+export declare function bindWebSocketLifetime(handlers: FakeWebSocketHandlers, lifetime: FakeWebSocketLifetime): FakeWebSocketHandlers;

package/dist/harness/fake-websocket-lifetime.js

@@ -0,0 +1,50 @@
+import { reportBackgroundFailure } from "./background-failures.js";
+/** Internal connection ownership, independent of serialized user callbacks.
+ * Runs once on disconnect, failure or abandoned handshake, never at test end. */
+export class FakeWebSocketLifetime {
+    result;
+    callbacks = new Set();
+    get ended() { return this.result !== undefined; }
+    onEnd(callback) {
+        if (this.result)
+            callback(this.result);
+        else
+            this.callbacks.add(callback);
+        return () => { this.callbacks.delete(callback); };
+    }
+    end(event) {
+        if (this.result)
+            return;
+        this.result = event;
+        const callbacks = [...this.callbacks];
+        this.callbacks.clear();
+        for (const callback of callbacks) {
+            try {
+                callback(event);
+            }
+            catch (error) {
+                reportBackgroundFailure(error);
+            }
+        }
+    }
+}
+const lifetimes = new WeakMap();
+export function getWebSocketLifetime(target) {
+    let lifetime = lifetimes.get(target);
+    if (lifetime)
+        return lifetime;
+    lifetime = new FakeWebSocketLifetime();
+    lifetimes.set(target, lifetime);
+    if (target instanceof Request) {
+        const abort = () => lifetime.end({ kind: "aborted" });
+        target.signal.addEventListener("abort", abort, { once: true });
+        lifetime.onEnd(() => target.signal.removeEventListener("abort", abort));
+        if (target.signal.aborted)
+            abort();
+    }
+    return lifetime;
+}
+export function bindWebSocketLifetime(handlers, lifetime) {
+    lifetimes.set(handlers, lifetime);
+    return handlers;
+}

package/dist/harness/fake-websocket.js

@@ -1,14 +1,24 @@
 import { runUninstrumented } from "./instrumentation-scope.js";
+import { bindWebSocketLifetime, getWebSocketLifetime } from "./fake-websocket-lifetime.js";
+import { reportBackgroundFailure } from "./background-failures.js";
 import { parseSubprotocols } from "./ws-bridge.js";
 /** HTTP and WebSocket dispatch share fake state, helpers, and execution scope. */
 export async function dispatchFake(req, server, def, state, ctx) {
-    try {
-        if (req.headers.get("upgrade")?.toLowerCase() !== "websocket" || !def.websocket) {
+    if (req.headers.get("upgrade")?.toLowerCase() !== "websocket" || !def.websocket) {
+        try {
             return await runUninstrumented(() => def.handler(req, state, ctx));
         }
+        catch (err) {
+            return fakeError(def.name, err);
+        }
+    }
+    const lifetime = getWebSocketLifetime(req);
+    try {
         const accepted = await runUninstrumented(() => def.websocket(req, state, ctx));
-        if (accepted instanceof Response)
+        if (accepted instanceof Response) {
+            lifetime.end({ kind: "aborted" });
             return accepted;
+        }
         if (!accepted || typeof accepted !== "object")
             throw new Error("websocket must return handlers or a Response");
         if (accepted.protocol !== undefined && !parseSubprotocols(req.headers.get("sec-websocket-protocol")).includes(accepted.protocol)) {
@@ -19,14 +29,23 @@ export async function dispatchFake(req, server, def, state, ctx) {
             message: (socket, message) => runUninstrumented(() => accepted.message?.(socket, message)),
             close: (socket, code, reason) => runUninstrumented(() => accepted.close?.(socket, code, reason)),
         };
-        return server.upgrade(req, {
-            handlers,
+        const upgraded = server.upgrade(req, {
+            handlers: bindWebSocketLifetime(handlers, lifetime),
             headers: accepted.protocol ? { "sec-websocket-protocol": accepted.protocol } : undefined,
-        }) ? new Response(null, { status: 101 }) : new Response("WebSocket upgrade refused", { status: 426 });
+        });
+        if (!upgraded)
+            lifetime.end({ kind: "aborted" });
+        return upgraded ? new Response(null, { status: 101 }) : new Response("WebSocket upgrade refused", { status: 426 });
     }
     catch (err) {
-        return new Response(`spectest-daemon: fake ${def.name} threw: ${err instanceof Error ? err.message : String(err)}\n`, {
-            status: 500, headers: { "content-type": "text/plain" },
-        });
+        if (!lifetime.ended)
+            reportBackgroundFailure(new Error(`fake ${def.name} WebSocket handshake failed: ${err instanceof Error ? err.message : String(err)}`));
+        lifetime.end({ kind: "failed", error: err });
+        return fakeError(def.name, err);
     }
 }
+function fakeError(name, error) {
+    return new Response(`spectest-daemon: fake ${name} threw: ${error instanceof Error ? error.message : String(error)}\n`, {
+        status: 500, headers: { "content-type": "text/plain" },
+    });
+}

package/dist/replay-mode.d.ts

@@ -0,0 +1,2 @@
+export declare function setReplayEnvironmentMode(value: "test" | "interactive"): void;
+export declare function resolveReplayMode(requested?: "auto" | "record" | "replay"): "record" | "replay";

package/dist/replay-mode.js

@@ -0,0 +1,12 @@
+// Environment state: travels with memory snapshots, independently of the
+// per-case event recorder. Shared/warm baselines must never record upstream.
+// The control plane enables recording only on an interactive environment,
+// after capturing/restoring the shared baseline and before interactive setup.
+let mode = "test";
+export function setReplayEnvironmentMode(value) {
+    mode = value;
+}
+export function resolveReplayMode(requested = "auto") {
+    // Even an explicit record option cannot send test traffic to real providers.
+    return mode === "test" || requested === "replay" ? "replay" : "record";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.109.1",
+  "version": "0.110.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/index.ts

@@ -88,6 +88,11 @@ export {
   type ReplayFakeContext,
   type ReplayHandler,
   type ReplayKey,
+  type WebSocketKey,
+  type ReplayWebSocketMessage,
+  type CassetteWebSocket,
+  type CassetteWebSocketMessage,
+  type WebSocketTiming,
   type ReplayRequest,
   type MatchKey,
   type JsonValue,

package/src/components/replay-key.ts

@@ -34,7 +34,7 @@ export type ReplayKey = (request: ReplayRequest) => MatchKey;
 /** Stream a typed, length-delimited canonical representation into the hash.
  *  Never call toJSON: unsupported values must fail rather than silently lose
  *  identity fields. In particular, an async callback must not become `{}`. */
-function hashKey(key: MatchKey): string {
+export function hashKey(key: MatchKey): string {
   const hash = createHash("sha256");
   const ancestors = new Set<object>();
   const visit = (value: unknown): void => {