@specific.dev/spectest 0.109.0 → 0.110.0

package/src/harness/fake-websocket-connection.ts

@@ -1,54 +1,75 @@
 import type WebSocket from "ws";
 import type { FakeWebSocket, FakeWebSocketHandlers } from "../fake-websocket.js";
+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: WebSocket, handlers: FakeWebSocketHandlers): void {
-  let tail = Promise.resolve();
-  let pending = 0;
+  const lifetime = getWebSocketLifetime(handlers);
+  const queue: { run: () => void | Promise<void>; size: number }[] = [];
+  let running = false;
+  let inFlightBytes = 0;
   let bytes = 0;
   let failed = false;
+  lifetime.onEnd(() => { queue.length = 0; bytes = inFlightBytes; });
+
+  const fail = (err: unknown, 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: FakeWebSocket = {
     get readyState() { return ws.readyState; },
     send(message) {
       if (ws.readyState !== 1) 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: unknown) => {
-    failed = true;
-    console.error("[spectest] fake WebSocket callback failed:", err);
-    try { ws.close(1011, "fake handler failed"); } catch { ws.terminate(); }
+  const drain = async () => {
+    if (running) return;
+    running = true;
+    try {
+      while (queue.length) {
+        const task = queue.shift()!;
+        inFlightBytes = task.size;
+        try { await task.run(); } catch (error) { fail(error); }
+        finally { bytes -= task.size; inFlightBytes = 0; }
+      }
+    } finally { running = false; }
   };
-  const enqueue = (fn: () => void | Promise<void>, size = 0, closing = false) => {
-    if (failed && !closing) return;
-    if (!closing && (pending >= MAX_PENDING || bytes + size > MAX_BUFFER)) {
-      failed = true;
-      ws.close(1009, "fake input buffer exceeded");
+  const enqueue = (run: () => void | Promise<void>, size = 0, closing = false) => {
+    if (lifetime.ended && !closing) return;
+    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 as ArrayBuffer);
-    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/src/harness/fake-websocket-lifetime.test.ts

@@ -0,0 +1,185 @@
+import { afterEach, expect, spyOn, test } from "bun:test";
+import { once } from "node:events";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { createServer } from "node:http";
+import type { FakeContext, FakeWebSocketHandlers } from "../index.js";
+import { defineFake } from "../index.js";
+import { FakeWebSocketLifetime, getWebSocketLifetime } from "./fake-websocket-lifetime.js";
+import { runWithBackgroundFailures, reportBackgroundFailure } from "./background-failures.js";
+import { dispatchFake } from "./fake-websocket.js";
+import { startIngressServer } from "./ingress-server.js";
+import { recordWebSocket } from "../components/replay-websocket.js";
+import { replayFake } from "../components/replayFake.js";
+
+const require = createRequire(import.meta.url);
+const WS = require(join(dirname(require.resolve("ws/package.json")), "index.js")) as typeof import("ws");
+const cleanup: (() => void)[] = [];
+afterEach(() => { for (const fn of cleanup.splice(0).reverse()) fn(); });
+const ctx = {} as FakeContext;
+
+function silenceErrors() {
+  const errors = spyOn(console, "error").mockImplementation(() => {});
+  cleanup.push(() => errors.mockRestore());
+}
+
+test("transport disconnect disposes immediately while callbacks are blocked, discarding queued messages", async () => {
+  let release!: () => void;
+  const blocked = new Promise<void>(resolve => release = resolve);
+  cleanup.push(release);
+  let entered!: () => void;
+  const started = new Promise<void>(resolve => entered = resolve);
+  let ended!: () => void;
+  const disposed = new Promise<void>(resolve => ended = resolve);
+  let closed!: () => void;
+  const closeCallback = new Promise<void>(resolve => closed = resolve);
+  let disposals = 0;
+  const messages: string[] = [];
+  const fake = defineFake({ name: "slow", hostnames: ["slow.test"], handler: () => new Response("http"),
+    websocket(req) {
+      getWebSocketLifetime(req).onEnd(() => { disposals++; ended(); });
+      return {
+        async message(_socket, message) { messages.push(String(message)); entered(); await blocked; },
+        close() { closed(); },
+      };
+    },
+  });
+  const server = await startIngressServer({ port: 0, hostname: "127.0.0.1", fetch: (req, server) => dispatchFake(req, server, fake, undefined, ctx) });
+  cleanup.push(() => server.stop(true));
+  const client = new WS(`ws://127.0.0.1:${server.port}`);
+  await once(client, "open");
+  const disconnected = once(client, "close");
+  client.send("first"); await started;
+  client.send("queued"); client.close();
+  await disconnected; await disposed;
+  expect(disposals).toBe(1);
+  expect(messages).toEqual(["first"]);
+  release(); await closeCallback;
+  expect(messages).toEqual(["first"]);
+  expect(disposals).toBe(1);
+});
+
+test.each(["refused", "invalid-protocol", "throw", "aborted"])("failed %s handshake disposes once before any open callback", async failure => {
+  const controller = new AbortController();
+  const req = new Request("https://voice.test/live", { signal: controller.signal, headers: { upgrade: "websocket" } });
+  let disposals = 0;
+  let opened = false;
+  const fake = defineFake({ name: "voice", hostnames: ["voice.test"], handler: () => new Response("http"),
+    async websocket(request) {
+      getWebSocketLifetime(request).onEnd(() => disposals++);
+      if (failure === "throw") throw new Error("handshake failed");
+      if (failure === "aborted") { controller.abort(); await Bun.sleep(1); }
+      return { protocol: failure === "invalid-protocol" ? "unoffered" : undefined, open() { opened = true; } };
+    },
+  });
+  const server = { port: 0, stop() {}, requestIP: () => undefined, upgrade: () => false };
+  const response = await dispatchFake(req, server, fake, undefined, ctx);
+  expect(response.status).toBe(failure === "throw" || failure === "invalid-protocol" ? 500 : 426);
+  expect(disposals).toBe(1); expect(opened).toBe(false);
+  controller.abort(); expect(disposals).toBe(1);
+});
+
+test("aborting a pending upstream handshake releases the socket without waiting for timeout", async () => {
+  const server = createServer();
+  const accepted = once(server, "upgrade");
+  server.listen(0, "127.0.0.1"); await once(server, "listening");
+  cleanup.push(() => server.close());
+  const lifetime = new FakeWebSocketLifetime();
+  cleanup.push(() => lifetime.end({ kind: "aborted" }));
+  let finished = 0;
+  const recording = recordWebSocket({
+    url: `ws://voice.test:${(server.address() as { port: number }).port}/live`, host: "voice.test", ip: "127.0.0.1",
+    headers: {}, protocols: [], request: { method: "GET", path: "/live", query: {}, headers: {} },
+    match: () => null, redact: s => s, secrets: [], label: "pending", lifetime,
+    captured() { throw new Error("should not finish handshake"); }, finished() { finished++; },
+  });
+  const rejected = recording.then(() => undefined, error => error);
+  const [, socket] = await accepted;
+  cleanup.push(() => socket.destroy());
+  const disconnected = once(socket, "end");
+  socket.resume();
+  lifetime.end({ kind: "aborted" });
+  expect((await rejected)?.message).toContain("handshake aborted");
+  await disconnected;
+  expect(finished).toBe(1);
+});
+
+test("callback failures automatically reject the running test and release connection resources", async () => {
+  silenceErrors();
+  let disposals = 0;
+  const fake = defineFake({ name: "broken", hostnames: ["broken.test"], handler: () => new Response("http"), websocket(req) {
+    getWebSocketLifetime(req).onEnd(() => disposals++);
+    return { message() { throw new Error("callback exploded"); } };
+  } });
+  const server = await startIngressServer({ port: 0, hostname: "127.0.0.1", fetch: (req, server) => dispatchFake(req, server, fake, undefined, ctx) });
+  cleanup.push(() => server.stop(true));
+  const client = new WS(`ws://127.0.0.1:${server.port}`);
+  await once(client, "open");
+  const closed = once(client, "close");
+  await expect(runWithBackgroundFailures(async () => {
+    client.send("fail");
+    await new Promise(() => {}); // Represents a test waiting for an app response.
+  })).rejects.toThrow("callback exploded");
+  expect(disposals).toBe(1);
+  expect((await closed)[0]).toBe(1011);
+  expect(await runWithBackgroundFailures(async () => "next test")).toBe("next test");
+});
+
+test("replay timeout automatically fails a test; open connections do not require end-of-test verification", async () => {
+  silenceErrors();
+  const fake = replayFake({ name: "voice", host: "voice.test", mode: "replay", websocketTimeoutMs: 50 });
+  const state = await fake.state!();
+  const helpers = await fake.helpers!({ name: "voice", state, ctx });
+  expect(Object.keys(helpers).sort()).toEqual(["count", "dump", "recorded", "replay"]);
+  helpers.replay({ version: 1, fake: "voice", host: "voice.test", interactions: [], websockets: [{
+    request: { method: "GET", path: "/", query: {}, headers: {} }, inputs: ["a".repeat(64)], messages: [],
+  }] });
+  const server = await startIngressServer({ port: 0, hostname: "127.0.0.1", fetch: (req, server) => dispatchFake(req, server, fake, state, ctx) });
+  cleanup.push(() => server.stop(true));
+  let client!: InstanceType<typeof WS>;
+  let closed!: Promise<unknown[]>;
+  await expect(runWithBackgroundFailures(async () => {
+    client = new WS(`ws://127.0.0.1:${server.port}`);
+    closed = once(client, "close");
+    await once(client, "open");
+    await new Promise(() => {});
+  })).rejects.toThrow("required input never arrived");
+  expect((await closed)[0]).toBe(1011);
+  expect(state.websocketSessions.size).toBe(0);
+  helpers.replay({ version: 1, fake: "voice", host: "voice.test", interactions: [], websockets: [{
+    request: { method: "GET", path: "/", query: {}, headers: {} }, inputs: [], messages: [],
+  }] });
+  await runWithBackgroundFailures(async () => {
+    client = new WS(`ws://127.0.0.1:${server.port}`); closed = once(client, "close");
+    await once(client, "open");
+  });
+  expect(state.websocketSessions.size).toBe(1); // Test returned; connection is still usable.
+  client.close(); await closed;
+  await Bun.sleep(5);
+  expect(state.websocketSessions.size).toBe(0);
+});
+
+test("connection failure cancels replay timers immediately without a later timeout failure", async () => {
+  silenceErrors();
+  const fake = replayFake({ name: "voice", host: "voice.test", mode: "replay", websocketTimeoutMs: 20 });
+  const state = await fake.state!();
+  const helpers = await fake.helpers!({ name: "voice", state, ctx });
+  helpers.replay({ version: 1, fake: "voice", host: "voice.test", interactions: [], websockets: [{
+    request: { method: "GET", path: "/", query: {}, headers: {} }, inputs: ["a".repeat(64)],
+    messages: [{ afterInput: 0, delayMs: 10, type: "text", data: "late" }],
+  }] });
+  const req = new Request("https://voice.test/");
+  const handlers = await fake.websocket!(req, state, ctx) as FakeWebSocketHandlers;
+  const sent: unknown[] = [];
+  await handlers.open!({ readyState: 1, send: value => sent.push(value), close() {} });
+  getWebSocketLifetime(req).end({ kind: "failed", error: new Error("transport error") });
+  await Bun.sleep(40);
+  expect(sent).toEqual([]); expect(state.websocketSessions.size).toBe(0);
+  expect(state.websocketErrors).toEqual([]); // The transport owns reporting the original failure.
+});
+
+test("background failures outside a running test are logged without poisoning the next test", async () => {
+  silenceErrors();
+  reportBackgroundFailure(new Error("manual recording failed"));
+  expect(await runWithBackgroundFailures(async () => 42)).toBe(42);
+});

package/src/harness/fake-websocket-lifetime.ts

@@ -0,0 +1,52 @@
+import type { FakeWebSocketHandlers } from "../fake-websocket.js";
+import { reportBackgroundFailure } from "./background-failures.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 class FakeWebSocketLifetime {
+  private result?: WebSocketEnd;
+  private callbacks = new Set<(event: WebSocketEnd) => void>();
+  get ended(): boolean { return this.result !== undefined; }
+
+  onEnd(callback: (event: WebSocketEnd) => void): () => void {
+    if (this.result) callback(this.result);
+    else this.callbacks.add(callback);
+    return () => { this.callbacks.delete(callback); };
+  }
+
+  end(event: WebSocketEnd): void {
+    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<object, FakeWebSocketLifetime>();
+
+export function getWebSocketLifetime(target: Request | FakeWebSocketHandlers): FakeWebSocketLifetime {
+  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: FakeWebSocketHandlers, lifetime: FakeWebSocketLifetime): FakeWebSocketHandlers {
+  lifetimes.set(handlers, lifetime);
+  return handlers;
+}

package/src/harness/fake-websocket.ts

@@ -2,6 +2,8 @@ import type { FakeWebSocketHandlers } from "../fake-websocket.js";
 import type { FakeContext, FakeDefinition } from "../index.js";
 import type { IngressServer } from "./ingress-server.js";
 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. */
@@ -12,12 +14,14 @@ export async function dispatchFake<S>(
   state: S,
   ctx: FakeContext,
 ): Promise<Response> {
+  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 {
-    if (req.headers.get("upgrade")?.toLowerCase() !== "websocket" || !def.websocket) {
-      return await runUninstrumented(() => def.handler(req, state, ctx));
-    }
     const accepted = await runUninstrumented(() => def.websocket!(req, state, ctx));
-    if (accepted instanceof Response) return accepted;
+    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)) {
       throw new Error("websocket selected a protocol the client did not offer");
@@ -27,13 +31,21 @@ export async function dispatchFake<S>(
       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 });
-  } 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 (!upgraded) lifetime.end({ kind: "aborted" });
+    return upgraded ? new Response(null, { status: 101 }) : new Response("WebSocket upgrade refused", { status: 426 });
+  } catch (err) {
+    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: string, error: unknown): Response {
+  return new Response(`spectest-daemon: fake ${name} threw: ${error instanceof Error ? error.message : String(error)}\n`, {
+    status: 500, headers: { "content-type": "text/plain" },
+  });
+}

package/src/helper-tracking.test.ts

@@ -3,6 +3,7 @@ import { annotate } from "./annotate.js";
 import { expect as assertValue, type ServiceHandlesFor, type Wrapped } from "./index.js";
 import { readRaw, readTag, wrap } from "./inspect.js";
 import { trackHelpers } from "./helper-tracking.js";
+import { SQL } from "./sql.js";
 import {
   recordHttp, recordWait, recorderEventCount, recorderMarkChildren, recorderTruncate,
   startRecording, stopRecording,
@@ -175,6 +176,41 @@ test("live objects, callable clients, function properties and receivers survive"
   expect<unknown>(readRaw(helper.latest.call({...raw, subject: "Other"}))).toEqual({subject: "Other"});
 });
 
+test("a tracked SQL client keeps tagged queries and attached methods instrumented", async () => {
+  const client = new SQL("sqlite://:memory:", { label: "db" });
+  const helper = trackHelpers("service", "db", { client });
+  startRecording();
+  try {
+    const rows = await helper.client<{ id: number }>`SELECT ${7} AS id`;
+    assertValue(rows.transform("ids", (rows) => Array.from(rows, (row) => row.id))).toEqual([7]);
+    const other = await helper.client.unsafe<{ id: number }>("SELECT ? AS id", [8]);
+    assertValue(other[0]!.id).toBe(8);
+    const events = stopRecording();
+    expect(events.map((event) => event.kind)).toEqual(["db", "assertion", "db", "assertion"]);
+    expect(events[0]).toMatchObject({ service: "db", query: "SELECT $1 AS id", params: [7], rows: [{ id: 7 }] });
+    expect(events[1]).toMatchObject({ sourceSeq: events[0]!.seq, path: ["<ids>"] });
+    expect(events[2]).toMatchObject({ service: "db", query: "SELECT ? AS id", params: [8], rows: [{ id: 8 }] });
+    expect(events[3]).toMatchObject({ sourceSeq: events[2]!.seq, path: ["0", "id"] });
+  } finally {
+    await helper.client.close!();
+  }
+});
+
+test("a tracked SQL client preserves query failure diagnostics", async () => {
+  const client = new SQL("sqlite://:memory:", { label: "db" });
+  const helper = trackHelpers("service", "db", { client });
+  startRecording();
+  try {
+    await expect(helper.client`SELECT * FROM missing_table`).rejects.toThrow("no such table");
+    const events = stopRecording();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ kind: "db", service: "db", query: "SELECT * FROM missing_table",
+      error: expect.stringContaining("no such table") });
+  } finally {
+    await helper.client.close!();
+  }
+});
+
 test("setup/eval unwrap annotated returns without recording", async () => {
   const scope = createInstrumentationScope(false);
   const helper = trackHelpers("service", "mail", { latest: () => annotate({subject: "Invoice"}, "email") });

package/src/helper-tracking.ts

@@ -93,9 +93,11 @@ function invokeHelper(
   };
   let result: unknown;
   try {
+    // Reading a callable proxy's `.apply` can bind directly to its raw client
+    // and bypass instrumentation (SQL does this). Invoke the proxy itself.
     result = recording.run(() => kind === "fake"
-      ? runUninstrumented(() => fn.apply(receiver, args))
-      : fn.apply(receiver, args));
+      ? runUninstrumented(() => Reflect.apply(fn, receiver, args))
+      : Reflect.apply(fn, receiver, args));
   } catch (error) {
     return fail(error);
   }

package/src/replay-mode.test.ts

@@ -0,0 +1,96 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+test("test environments replay HTTP and WebSockets throughout the recorder lifecycle, even with credentials", async () => {
+  // Isolate daemon state and transport mocks. Any attempted external I/O fails
+  // locally, even if this regression returns; no real provider is contacted.
+  const root = await mkdtemp(join(tmpdir(), "spectest-replay-mode-"));
+  const module = (file: string) => JSON.stringify(new URL(file, import.meta.url).href);
+  try {
+    const file = join(root, "mode.test.ts");
+    await writeFile(file, `
+      import { test, mock } from "bun:test";
+      import { strict as assert } from "node:assert";
+      test("environment lifetime", async () => {
+        let networkCalls = 0;
+        const forbidden = () => { networkCalls++; throw new Error("unexpected upstream I/O"); };
+        mock.module("node:dgram", () => ({ createSocket: forbidden }));
+        mock.module("node:https", () => ({ request: forbidden }));
+        const { METHODS } = await import(${module("./daemon.ts")});
+        const { replayFake } = await import(${module("./components/replayFake.ts")});
+        const { resolveReplayMode } = await import(${module("./replay-mode.ts")});
+        const { startRecording, stopRecording, pauseRecording, resumeRecording } = await import(${module("./recorder.ts")});
+        assert.equal((await METHODS.health({})).replayEnvironmentMode, true);
+        await METHODS.setRecordSecrets({ secrets: { API_KEY: "available-credential" } });
+        await assert.rejects(METHODS.setReplayEnvironmentMode({ mode: "typo" }));
+        assert.equal(resolveReplayMode(), "replay");
+        const request = { method: "GET", path: "/messages", query: {}, headers: {} };
+        const cassette = {
+          version: 1, fake: "test", host: "provider.test",
+          interactions: [{ request, response: { status: 200, headers: {}, body: "cassette" } }],
+          websockets: [{ request, inputs: [], messages: [] }],
+        };
+        const fakes = await Promise.all([undefined, "auto", "record", "replay"].map(async mode => {
+          const fake = replayFake({ name: "test", host: "provider.test", mode,
+            inject: [{ headers: { authorization: "Bearer {{secret:API_KEY}}" } }],
+          });
+          const state = await fake.state();
+          return { fake, state, helpers: await fake.helpers({ name: "test", state, ctx: {} }) };
+        }));
+        const check = async () => {
+          for (const { fake, state, helpers } of fakes) {
+            const http = () => fake.handler(new Request("https://provider.test/messages"), state, {});
+            const ws = () => fake.websocket(new Request("https://provider.test/messages", {
+              headers: { upgrade: "websocket", "sec-websocket-key": "test" },
+            }), state, {});
+            helpers.replay({ ...cassette, interactions: [], websockets: [] });
+            assert.equal((await http()).status, 599); // no cassette
+            assert.equal((await ws()).status, 599);
+            helpers.replay(cassette);
+            assert.equal(await (await http()).text(), "cassette");
+            const connection = await ws();
+            assert.equal(connection instanceof Response, false);
+            for (const session of state.websocketSessions) session.cancel();
+            assert.equal((await http()).status, 599); // exhausted cassette
+            assert.equal((await ws()).status, 599);
+            assert.equal(helpers.recorded().length, 0);
+          }
+          assert.equal(networkCalls, 0);
+        };
+        await check(); // startup, before any case has ever run
+        startRecording();
+        await check();
+        pauseRecording();
+        await check();
+        resumeRecording();
+        stopRecording();
+        await check(); // background traffic between cases / before a snapshot
+        startRecording();
+        stopRecording();
+        await check(); // another case cannot reset the environment mode
+        assert.equal((await METHODS.eval({ code: "export default 42;" })).ok, true);
+        assert.equal((await METHODS.eval({ code: 'throw new Error("expected");' })).ok, false);
+        await check(); // eval on a test environment cannot enable recording
+        await METHODS.setReplayEnvironmentMode({ mode: "interactive" });
+        assert.equal(resolveReplayMode(), "record");
+        assert.equal(resolveReplayMode("record"), "record");
+        assert.equal(resolveReplayMode("replay"), "replay");
+        startRecording(); stopRecording();
+        assert.equal(resolveReplayMode(), "record");
+        await METHODS.setReplayEnvironmentMode({ mode: "test" });
+        await check();
+      });
+    `);
+    const child = Bun.spawn([process.execPath, "test", file], {
+      env: { ...process.env, SPECTEST_APP_DIR: root }, stdout: "pipe", stderr: "pipe",
+    });
+    const [code, stdout, stderr] = await Promise.all([
+      child.exited, new Response(child.stdout).text(), new Response(child.stderr).text(),
+    ]);
+    expect(code, stdout + stderr).toBe(0);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}, 20_000);

package/src/replay-mode.ts

@@ -0,0 +1,14 @@
+// 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" | "interactive" = "test";
+
+export function setReplayEnvironmentMode(value: "test" | "interactive"): void {
+  mode = value;
+}
+
+export function resolveReplayMode(requested: "auto" | "record" | "replay" = "auto"): "record" | "replay" {
+  // Even an explicit record option cannot send test traffic to real providers.
+  return mode === "test" || requested === "replay" ? "replay" : "record";
+}