@specific.dev/spectest 0.100.0 → 0.101.0

package/dist/components/index.d.ts

@@ -13,6 +13,6 @@ export { github, type GithubOptions } from "./github.js";
 export { apple, type AppleOptions } from "./apple.js";
 export { microsoft, type MicrosoftOptions } from "./microsoft.js";
 export { okta, type OktaOptions } from "./okta.js";
-export { replayFake, type ReplayFakeOptions, type ReplayKey, type ReplayRequest, type MatchKey, type JsonValue, type InjectRule, type InjectMatch, type StringMatch, type SignConfig, type AwsSigV4Sign, type ReplayHelpers, type ReplaySummary, type Cassette, type CassetteInteraction, type CassetteRequest, type CassetteResponse, type CassetteState, } from "./replayFake.js";
+export { replayFake, type ReplayFakeOptions, type ReplayFakeContext, type ReplayHandler, type ReplayKey, type ReplayRequest, type MatchKey, type JsonValue, type InjectRule, type InjectMatch, type StringMatch, type SignConfig, type AwsSigV4Sign, type ReplayHelpers, type ReplaySummary, type Cassette, type CassetteInteraction, type CassetteRequest, type CassetteResponse, type CassetteState, } from "./replayFake.js";
 export { electron, type ElectronOptions } from "./electron.js";
 export { android, type AndroidOptions } from "./android.js";

package/dist/components/replayFake.d.ts

@@ -1,4 +1,4 @@
-import type { FakeDefinition } from "../index.js";
+import type { FakeContext, FakeDefinition } from "../index.js";
 import { type ReplayKey } from "./replay-key.js";
 export type { JsonValue, MatchKey, ReplayRequest, ReplayKey } from "./replay-key.js";
 /** Match one request dimension. A bare string is an exact match; the
@@ -54,7 +54,15 @@ export interface AwsSigV4Sign {
     sessionToken?: string;
 }
 export type SignConfig = AwsSigV4Sign;
-export interface ReplayFakeOptions {
+/** A normal fake context with explicit delegation to recording/replay. */
+export interface ReplayFakeContext extends FakeContext {
+    /** Record against the real upstream in record mode, or consume a matching
+     *  cassette interaction in replay mode. A replay miss returns 599; there
+     *  is no fallback to scripted logic. Inspect a body's clone before calling. */
+    replay(request: Request): Promise<Response>;
+}
+export type ReplayHandler<S> = (request: Request, state: S, ctx: ReplayFakeContext) => Response | Promise<Response>;
+export interface ReplayFakeOptions<S = undefined, H extends Record<string, unknown> = {}> {
     /** Stable name — the `ctx.fakes` key. */
     name: string;
     /** The REAL host to fake, e.g. `"api.stripe.com"`. The fake answers for
@@ -87,6 +95,19 @@ export interface ReplayFakeOptions {
     /** `"auto"` (default) records under eval and replays under test;
      *  `"record"` / `"replay"` force a mode. */
     mode?: "auto" | "record" | "replay";
+    /** Custom state, with the same lifecycle as a normal fake's state. Kept
+     *  separate from cassette internals; helpers and handler see only S. */
+    state?: () => S | Promise<S>;
+    /** Custom helpers exposed alongside replay/dump/recorded/count. Those
+     *  names are reserved. Loading a cassette does not change custom state. */
+    helpers?: (args: {
+        name: string;
+        state: S;
+        ctx: FakeContext;
+    }) => H | Promise<H>;
+    /** Decide whether to answer in code or call ctx.replay(request). Without
+     *  a handler, every request delegates. Only delegated requests record. */
+    handler?: ReplayHandler<S>;
 }
 export interface CassetteRequest {
     method: string;
@@ -144,8 +165,9 @@ export interface ReplaySummary {
     interactions: number;
 }
 export interface ReplayHelpers extends Record<string, unknown> {
-    /** Load a cassette into THIS fork's replay set and replay from it,
+    /** Load a cassette into THIS fork's replay set for delegated requests,
      *  replacing whatever was loaded before and resetting the replay cursor.
+     *  Does not change custom state or bypass a custom handler.
      *  Cassettes are NOT auto-loaded — call this at the top of a test. Pass a
      *  path relative to `spectest/tests/` (e.g. `"recordings/stripe.json"`; it
      *  must stay under `spectest/tests/`) or a cassette object; a missing file
@@ -161,4 +183,6 @@ export interface ReplayHelpers extends Record<string, unknown> {
     /** Count of interactions captured this record session. */
     count(): number;
 }
-export declare function replayFake(opts: ReplayFakeOptions): FakeDefinition<CassetteState, ReplayHelpers>;
+export declare function replayFake<S = undefined, H extends Record<string, unknown> = {}>(opts: ReplayFakeOptions<S, H>): FakeDefinition<CassetteState & {
+    custom: S;
+}, ReplayHelpers & H>;

package/dist/components/replayFake.js

@@ -14,7 +14,7 @@
 //   - REPLAY (hermetic): the request is matched against the cassette the
 //     test EXPLICITLY loaded (`ctx.fakes.<name>.replay(file)`) and the
 //     recorded response is returned. No network. Nothing is auto-loaded:
-//     a test that loads no cassette gets a fail-loud 599 on every request.
+//     a test that loads no cassette gets a fail-loud 599 on every delegated request.
 //     This is what runs under `spectest test`.
 //   - RECORD (MITM): the request is forwarded to the REAL host and the
 //     request/response pair is captured (decoded, redacted), and the real
@@ -35,6 +35,8 @@
 // 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.
+// An optional custom handler can return scripted responses or explicitly
+// delegate with ctx.replay(request). Only delegated traffic uses this engine.
 //
 // Credential brokering (per-fake): `inject` rules set
 // headers on the egress forward — overwriting whatever the app sent — so
@@ -644,6 +646,9 @@ export function replayFake(opts) {
     }
     // ── handler ─────────────────────────────────────────────────────────
     const handler = async (req, state, _ctx) => {
+        if (req.bodyUsed) {
+            throw new Error(`replayFake(${opts.name}): cannot delegate a consumed request body; inspect request.clone() before calling ctx.replay(request)`);
+        }
         const url = new URL(req.url);
         const bodyBytes = req.method === "GET" || req.method === "HEAD"
             ? new Uint8Array(0)
@@ -668,71 +673,89 @@ export function replayFake(opts) {
             return replay(reqLike, state);
         return record(req, url, reqLike, bodyBytes, state);
     };
+    const replayHelpers = (state) => ({
+        replay(file) {
+            let loaded;
+            let label;
+            if (file && typeof file === "object") {
+                loaded = coerceCassette(file, opts.name, host);
+                label = file.fake || "(inline)";
+            }
+            else if (typeof file === "string" && file.length > 0) {
+                label = file;
+                loaded = readCassetteFile(opts.name, file, host);
+            }
+            else {
+                throw new Error(`replayFake(${opts.name}): replay(...) needs a cassette path under spectest/tests/ ` +
+                    `(e.g. "recordings/${opts.name}.json").`);
+            }
+            // Build/validate before replacing live state: a bad key/cassette
+            // must leave the previous cassette and consumption cursors intact.
+            const index = new Map();
+            for (const [i, interaction] of loaded.interactions.entries()) {
+                const sig = signature(interaction.request, `${JSON.stringify(label)} interaction #${i + 1}`);
+                const queue = index.get(sig);
+                if (queue)
+                    queue.push(i);
+                else
+                    index.set(sig, [i]);
+            }
+            // 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 };
+        },
+        dump() {
+            return structuredClone({
+                version: 1,
+                fake: opts.name,
+                host,
+                interactions: [...state.cassette.interactions, ...state.recorded],
+            });
+        },
+        recorded() {
+            return structuredClone(state.recorded);
+        },
+        count() {
+            return state.recorded.length;
+        },
+    });
+    const initialState = (custom) => ({
+        cassette: emptyCassette(opts.name, host),
+        index: new Map(),
+        cursor: new Map(),
+        recorded: [],
+        dirty: false,
+        custom,
+    });
     const def = {
         name: opts.name,
-        // Fake = real: we answer for the real host on :80 and :443.
         hostnames: [host],
         secretRefs,
-        // Cassettes are NOT auto-loaded — a fork starts with an empty replay
-        // set, so a test that loads nothing fails loud (599). Tests call
-        // `replay(...)` to populate it.
-        state: () => ({
-            cassette: emptyCassette(opts.name, host),
-            index: new Map(),
-            cursor: new Map(),
-            recorded: [],
-            dirty: false,
-        }),
-        handler,
-        helpers: ({ state }) => ({
-            replay(file) {
-                let loaded;
-                let label;
-                if (file && typeof file === "object") {
-                    loaded = coerceCassette(file, opts.name, host);
-                    label = file.fake || "(inline)";
-                }
-                else if (typeof file === "string" && file.length > 0) {
-                    label = file;
-                    loaded = readCassetteFile(opts.name, file, host);
-                }
-                else {
-                    throw new Error(`replayFake(${opts.name}): replay(...) needs a cassette path under spectest/tests/ ` +
-                        `(e.g. "recordings/${opts.name}.json").`);
-                }
-                // Build/validate before replacing live state: a bad key/cassette
-                // must leave the previous cassette and consumption cursors intact.
-                const index = new Map();
-                for (const [i, interaction] of loaded.interactions.entries()) {
-                    const sig = signature(interaction.request, `${JSON.stringify(label)} interaction #${i + 1}`);
-                    const queue = index.get(sig);
-                    if (queue)
-                        queue.push(i);
-                    else
-                        index.set(sig, [i]);
+        state: () => opts.state
+            ? Promise.resolve(opts.state()).then(initialState)
+            : initialState(undefined),
+        handler: (request, state, ctx) => opts.handler
+            ? opts.handler(request, state.custom, {
+                ...ctx,
+                replay: (delegated) => handler(delegated, state, ctx),
+            })
+            : handler(request, state, ctx),
+        helpers: ({ name, state, ctx }) => {
+            const builtins = replayHelpers(state);
+            if (!opts.helpers)
+                return builtins;
+            return Promise.resolve(opts.helpers({ name, state: state.custom, ctx })).then((custom) => {
+                for (const key of Object.keys(builtins)) {
+                    if (key in custom) {
+                        throw new Error(`replayFake(${opts.name}): custom helper ${JSON.stringify(key)} is reserved for recording/replay; choose another name`);
+                    }
                 }
-                // 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 };
-            },
-            dump() {
-                return structuredClone({
-                    version: 1,
-                    fake: opts.name,
-                    host,
-                    interactions: [...state.cassette.interactions, ...state.recorded],
-                });
-            },
-            recorded() {
-                return structuredClone(state.recorded);
-            },
-            count() {
-                return state.recorded.length;
-            },
-        }),
+                return { ...custom, ...builtins };
+            });
+        },
     };
     return def;
 }

package/package.json

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

package/src/components/index.ts

@@ -85,6 +85,8 @@ export { okta, type OktaOptions } from "./okta.js";
 export {
   replayFake,
   type ReplayFakeOptions,
+  type ReplayFakeContext,
+  type ReplayHandler,
   type ReplayKey,
   type ReplayRequest,
   type MatchKey,

package/src/components/replayFake-handler.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineEnvironment, type FakeContext } from "../index.js";
+import { replayFake, type Cassette, type ReplayFakeContext, type ReplayHandler } from "./index.js";
+
+const host = "api.example.test";
+const context = {} as FakeContext;
+const fixture: Cassette = {
+  version: 1, fake: "mixed", host,
+  interactions: ["one", "two"].map((task) => ({
+    request: {
+      method: "POST", path: "/messages", query: {}, headers: {},
+      body: JSON.stringify({ task }), bodyEncoding: "utf8",
+    },
+    response: { status: 200, headers: {}, body: `recorded-${task}`, bodyEncoding: "utf8" },
+  })),
+};
+const request = (task = "one", path = "/messages") => new Request(`https://${host}${path}`, {
+  method: "POST", body: JSON.stringify({ task }),
+});
+
+function mixedFake() {
+  return replayFake({
+    name: "mixed", host, mode: "replay",
+    state: () => ({ useRecordings: false, reply: "scripted", seen: [] as string[] }),
+    helpers: ({ state }) => ({
+      useRecordings(enabled = true) { state.useRecordings = enabled; },
+      reply(text: string) { state.reply = text; },
+      seen() { return [...state.seen]; },
+    }),
+    async handler(req, state, ctx) {
+      const body = await req.clone().json() as { task: string };
+      state.seen.push(body.task);
+      if (state.useRecordings && new URL(req.url).pathname === "/messages") {
+        return ctx.replay(req);
+      }
+      return new Response(state.reply);
+    },
+  });
+}
+
+describe("scripted behavior on replay fakes", () => {
+  test("loading only loads; custom helpers select behavior and misses never fall back", async () => {
+    const fake = mixedFake();
+    const state = await fake.state!();
+    const helpers = await fake.helpers!({ name: "mixed", state, ctx: context });
+    const send = (task?: string, path?: string) => fake.handler(request(task, path), state, context);
+
+    expect(await (await send()).text()).toBe("scripted");
+    helpers.reply("configured");
+    helpers.replay(fixture);
+    expect(await (await send()).text()).toBe("configured");
+    helpers.useRecordings();
+    expect((await send("missing")).status).toBe(599);
+    // The same fake mixes scripted and replayed endpoints concurrently.
+    expect(await Promise.all([
+      send("two"), send("one", "/transcription"), send("one"),
+    ].map(async (response) => (await response).text()))).toEqual([
+      "recorded-two", "configured", "recorded-one",
+    ]);
+    expect((await send()).status).toBe(599);
+    helpers.useRecordings(false);
+    expect(await (await send()).text()).toBe("configured");
+    expect(helpers.count()).toBe(0);
+    expect(helpers.recorded()).toEqual([]);
+    expect(helpers.seen()).toHaveLength(8);
+  });
+
+  test("delegating without a cassette fails even when scripted responses are available", async () => {
+    const fake = mixedFake();
+    const state = await fake.state!();
+    const helpers = await fake.helpers!({ name: "mixed", state, ctx: context });
+    helpers.useRecordings();
+    expect((await fake.handler(request(), state, context)).status).toBe(599);
+  });
+
+  test("custom state and cassette cursors survive cloning and siblings remain independent", async () => {
+    const fake = mixedFake();
+    const parent = await fake.state!();
+    const parentHelpers = await fake.helpers!({ name: "mixed", state: parent, ctx: context });
+    parentHelpers.replay(fixture);
+    parentHelpers.useRecordings();
+    await fake.handler(request("one"), parent, context);
+    // Model the state inherited by forks, including custom state and cursors.
+    const left = structuredClone(parent);
+    const right = structuredClone(parent);
+    const leftHelpers = await fake.helpers!({ name: "mixed", state: left, ctx: context });
+    leftHelpers.reply("left only");
+    expect((await fake.handler(request("one"), right, context)).status).toBe(599);
+    expect(await (await fake.handler(request("two"), left, context)).text()).toBe("recorded-two");
+    expect(await (await fake.handler(request("two"), right, context)).text()).toBe("recorded-two");
+    leftHelpers.useRecordings(false);
+    expect(right.custom.useRecordings).toBe(true);
+    expect(right.custom.reply).toBe("scripted");
+    expect(parent.cursor.size).toBe(1);
+  });
+
+  test("async factories receive custom state and the normal fake context", async () => {
+    const ctx = { dnsName: async () => {} } as unknown as FakeContext;
+    const fake = replayFake({
+      name: "mixed", host, mode: "replay",
+      state: async () => ({ reply: "async" }),
+      helpers: async ({ state, name, ctx: received }) => {
+        expect(name).toBe("mixed");
+        expect(received).toBe(ctx);
+        return { reply: (text: string) => { state.reply = text; } };
+      },
+      handler: (_req, state, received) => {
+        expect(received.dnsName).toBe(ctx.dnsName);
+        expect(typeof received.replay).toBe("function");
+        expect("replay" in ctx).toBe(false);
+        return new Response(state.reply);
+      },
+    });
+    const state = await fake.state!();
+    const helpers = await fake.helpers!({ name: "mixed", state, ctx });
+    helpers.reply("updated");
+    expect(await (await fake.handler(request(), state, ctx)).text()).toBe("updated");
+  });
+
+  test.each(["replay", "dump", "recorded", "count"])("rejects reserved helper name %s", async (name) => {
+    const fake = replayFake({ name: "mixed", host, helpers: () => ({ [name]: () => {} }) });
+    const state = await fake.state!();
+    await expect(Promise.resolve().then(() => fake.helpers!({ name: "mixed", state, ctx: context })))
+      .rejects.toThrow(`custom helper "${name}" is reserved`);
+  });
+
+  test("handler-only customization needs no state or helpers", async () => {
+    const fake = replayFake({
+      name: "mixed", host, mode: "replay",
+      handler(req, state, ctx) {
+        expect(state).toBeUndefined();
+        return ctx.replay(req);
+      },
+    });
+    const state = await fake.state!();
+    const helpers = await fake.helpers!({ name: "mixed", state, ctx: context });
+    helpers.replay(fixture);
+    expect(await (await fake.handler(request(), state, context)).text()).toBe("recorded-one");
+  });
+
+  test("a consumed body reports how to inspect safely before delegation", async () => {
+    const fake = replayFake({
+      name: "mixed", host, mode: "replay",
+      async handler(req, _state, ctx) {
+        await req.json();
+        return ctx.replay(req);
+      },
+    });
+    const state = await fake.state!();
+    await expect(fake.handler(request(), state, context)).rejects.toThrow("inspect request.clone()");
+  });
+
+  test("public state, context, and helper types stay inferred through defineEnvironment", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spectest-replay-types-"));
+    try {
+      const config = join(dir, "tsconfig.json");
+      await writeFile(config, JSON.stringify({
+        extends: fileURLToPath(new URL("../../tsconfig.json", import.meta.url)),
+        compilerOptions: {
+          noEmit: true,
+          typeRoots: [fileURLToPath(new URL("../../node_modules/@types", import.meta.url))],
+        },
+        include: [fileURLToPath(import.meta.url)],
+        exclude: [],
+      }));
+      const child = Bun.spawn([process.execPath, fileURLToPath(import.meta.resolve("typescript/bin/tsc")), "-p", config], {
+        stdout: "pipe", stderr: "pipe",
+      });
+      const [exit, stdout, stderr] = await Promise.all([
+        child.exited, new Response(child.stdout).text(), new Response(child.stderr).text(),
+      ]);
+      expect(exit, stdout + stderr).toBe(0);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  }, 30_000);
+});
+
+// Checked with tsc as well as the runtime tests: inference must survive the
+// public components export and defineEnvironment's wrapped helper surface.
+function checkPublicTypes() {
+  const fake = replayFake({
+    name: "typed", host,
+    state: () => ({ enabled: false }),
+    helpers: ({ state }) => ({
+      enable(value: boolean) {
+        state.enabled = value;
+        // @ts-expect-error custom state is inferred, not any
+        state.missing;
+      },
+    }),
+    handler(req, state, ctx) {
+      const enabled: boolean = state.enabled;
+      const typedContext: ReplayFakeContext = ctx;
+      // @ts-expect-error internal cassette state is not exposed to the handler
+      state.cassette;
+      return enabled ? typedContext.replay(req) : new Response("scripted");
+    },
+  });
+  const env = defineEnvironment({ name: "typed", services: {}, fakes: { typed: fake } });
+  env.test("types", (ctx) => {
+    ctx.fakes.typed.enable(true);
+    ctx.fakes.typed.replay(fixture);
+    ctx.fakes.typed.dump();
+    // @ts-expect-error helper arguments retain their inferred types
+    ctx.fakes.typed.enable("yes");
+    // @ts-expect-error unknown helpers are not callable
+    ctx.fakes.typed.missing();
+  });
+  const handler: ReplayHandler<{ enabled: boolean }> = (req, state, ctx) =>
+    state.enabled ? ctx.replay(req) : new Response("scripted");
+  return handler;
+}

package/src/components/replayFake-record.test.ts

@@ -95,6 +95,48 @@ test("recorded headers, redaction, and exact body bytes survive record → repla
       }
     }
     assert.equal(upstreamHeaders.length, 3); // Replay never forwards.
+
+    // The custom handler delegates through the same auto-mode pipeline.
+    // Scripted requests must neither forward nor enter the cassette.
+    const { startRecording, stopRecording } = await import(${moduleUrl("../recorder.ts")});
+    const mixed = replayFake({
+      ...options,
+      state: () => ({ useRecordings: false }),
+      helpers: ({ state }) => ({ useRecordings() { state.useRecordings = true; } }),
+      async handler(request, state, ctx) {
+        const body = await request.clone().text();
+        return state.useRecordings && body !== "scripted"
+          ? ctx.replay(request)
+          : new Response("scripted response");
+      },
+    });
+    const mixedState = await mixed.state();
+    const mixedHelpers = await mixed.helpers({ name: "test", state: mixedState, ctx: {} });
+    const send = (body) => mixed.handler(new Request("https://api.example.test/messages", {
+      method: "POST", body,
+    }), mixedState, {});
+    assert.equal(await (await send("delegated")).text(), "scripted response");
+    assert.equal(upstreamHeaders.length, 3);
+    mixedHelpers.useRecordings();
+    assert.equal(await (await send("scripted")).text(), "scripted response");
+    assert.equal(await (await send("delegated")).text(), "response");
+    assert.equal(upstreamHeaders.length, 4);
+    assert.equal(upstreamHeaders[3].authorization, "Bearer recording-secret");
+    assert.equal(mixedHelpers.count(), 1);
+    const mixedCassette = mixedHelpers.dump();
+    assert.equal(mixedCassette.interactions[0].request.body, "delegated");
+    mixedHelpers.replay(mixedCassette);
+    startRecording(); // Enter a test: auto now replays instead of forwarding.
+    try {
+      assert.equal(await (await send("scripted")).text(), "scripted response");
+      assert.equal(await (await send("delegated")).text(), "response");
+      assert.equal((await send("delegated")).status, 599);
+      assert.equal((await send("unrecorded")).status, 599);
+      assert.equal(mixedHelpers.count(), 1);
+      assert.equal(upstreamHeaders.length, 4);
+    } finally {
+      stopRecording();
+    }
     });
   `;
   const dir = await mkdtemp(join(tmpdir(), "spectest-replay-record-"));

package/src/components/replayFake.ts

@@ -14,7 +14,7 @@
 //   - REPLAY (hermetic): the request is matched against the cassette the
 //     test EXPLICITLY loaded (`ctx.fakes.<name>.replay(file)`) and the
 //     recorded response is returned. No network. Nothing is auto-loaded:
-//     a test that loads no cassette gets a fail-loud 599 on every request.
+//     a test that loads no cassette gets a fail-loud 599 on every delegated request.
 //     This is what runs under `spectest test`.
 //   - RECORD (MITM): the request is forwarded to the REAL host and the
 //     request/response pair is captured (decoded, redacted), and the real
@@ -35,6 +35,8 @@
 // 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.
+// An optional custom handler can return scripted responses or explicitly
+// delegate with ctx.replay(request). Only delegated traffic uses this engine.
 //
 // Credential brokering (per-fake): `inject` rules set
 // headers on the egress forward — overwriting whatever the app sent — so
@@ -133,7 +135,24 @@ export interface AwsSigV4Sign {
 
 export type SignConfig = AwsSigV4Sign;
 
-export interface ReplayFakeOptions {
+/** A normal fake context with explicit delegation to recording/replay. */
+export interface ReplayFakeContext extends FakeContext {
+  /** Record against the real upstream in record mode, or consume a matching
+   *  cassette interaction in replay mode. A replay miss returns 599; there
+   *  is no fallback to scripted logic. Inspect a body's clone before calling. */
+  replay(request: Request): Promise<Response>;
+}
+
+export type ReplayHandler<S> = (
+  request: Request,
+  state: S,
+  ctx: ReplayFakeContext,
+) => Response | Promise<Response>;
+
+export interface ReplayFakeOptions<
+  S = undefined,
+  H extends Record<string, unknown> = {},
+> {
   /** Stable name — the `ctx.fakes` key. */
   name: string;
   /** The REAL host to fake, e.g. `"api.stripe.com"`. The fake answers for
@@ -166,6 +185,15 @@ export interface ReplayFakeOptions {
   /** `"auto"` (default) records under eval and replays under test;
    *  `"record"` / `"replay"` force a mode. */
   mode?: "auto" | "record" | "replay";
+  /** Custom state, with the same lifecycle as a normal fake's state. Kept
+   *  separate from cassette internals; helpers and handler see only S. */
+  state?: () => S | Promise<S>;
+  /** Custom helpers exposed alongside replay/dump/recorded/count. Those
+   *  names are reserved. Loading a cassette does not change custom state. */
+  helpers?: (args: { name: string; state: S; ctx: FakeContext }) => H | Promise<H>;
+  /** Decide whether to answer in code or call ctx.replay(request). Without
+   *  a handler, every request delegates. Only delegated requests record. */
+  handler?: ReplayHandler<S>;
 }
 
 export interface CassetteRequest {
@@ -230,8 +258,9 @@ export interface ReplaySummary {
 }
 
 export interface ReplayHelpers extends Record<string, unknown> {
-  /** Load a cassette into THIS fork's replay set and replay from it,
+  /** Load a cassette into THIS fork's replay set for delegated requests,
    *  replacing whatever was loaded before and resetting the replay cursor.
+   *  Does not change custom state or bypass a custom handler.
    *  Cassettes are NOT auto-loaded — call this at the top of a test. Pass a
    *  path relative to `spectest/tests/` (e.g. `"recordings/stripe.json"`; it
    *  must stay under `spectest/tests/`) or a cassette object; a missing file
@@ -627,9 +656,9 @@ function forwardToRealUpstream(args: {
 // replayFake
 // ────────────────────────────────────────────────────────────────────────
 
-export function replayFake(
-  opts: ReplayFakeOptions,
-): FakeDefinition<CassetteState, ReplayHelpers> {
+export function replayFake<S = undefined, H extends Record<string, unknown> = {}>(
+  opts: ReplayFakeOptions<S, H>,
+): FakeDefinition<CassetteState & { custom: S }, ReplayHelpers & H> {
   if (!opts.name) throw new Error("replayFake: `name` is required");
   if (!opts.host || typeof opts.host !== "string") {
     throw new Error(`replayFake(${opts.name}): "host" (the real hostname) is required`);
@@ -914,6 +943,9 @@ export function replayFake(
     state: CassetteState,
     _ctx: FakeContext,
   ): Promise<Response> => {
+    if (req.bodyUsed) {
+      throw new Error(`replayFake(${opts.name}): cannot delegate a consumed request body; inspect request.clone() before calling ctx.replay(request)`);
+    }
     const url = new URL(req.url);
     const bodyBytes =
       req.method === "GET" || req.method === "HEAD"
@@ -940,69 +972,88 @@ export function replayFake(
     return record(req, url, reqLike, bodyBytes, state);
   };
 
-  const def: FakeDefinition<CassetteState, ReplayHelpers> = {
+  const replayHelpers = (state: CassetteState): ReplayHelpers => ({
+    replay(file: string | Cassette): ReplaySummary {
+      let loaded: Cassette;
+      let label: string;
+      if (file && typeof file === "object") {
+        loaded = coerceCassette(file, opts.name, host);
+        label = file.fake || "(inline)";
+      } else if (typeof file === "string" && file.length > 0) {
+        label = file;
+        loaded = readCassetteFile(opts.name, file, host);
+      } else {
+        throw new Error(
+          `replayFake(${opts.name}): replay(...) needs a cassette path under spectest/tests/ ` +
+            `(e.g. "recordings/${opts.name}.json").`,
+        );
+      }
+      // Build/validate before replacing live state: a bad key/cassette
+      // must leave the previous cassette and consumption cursors intact.
+      const index = new Map<string, number[]>();
+      for (const [i, interaction] of loaded.interactions.entries()) {
+        const sig = signature(interaction.request, `${JSON.stringify(label)} interaction #${i + 1}`);
+        const queue = index.get(sig);
+        if (queue) queue.push(i);
+        else index.set(sig, [i]);
+      }
+      // 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 };
+    },
+    dump(): Cassette {
+      return structuredClone({
+        version: 1,
+        fake: opts.name,
+        host,
+        interactions: [...state.cassette.interactions, ...state.recorded],
+      });
+    },
+    recorded(): CassetteInteraction[] {
+      return structuredClone(state.recorded);
+    },
+    count(): number {
+      return state.recorded.length;
+    },
+  });
+
+  const initialState = (custom: S): CassetteState & { custom: S } => ({
+    cassette: emptyCassette(opts.name, host),
+    index: new Map(),
+    cursor: new Map(),
+    recorded: [],
+    dirty: false,
+    custom,
+  });
+
+  const def: FakeDefinition<CassetteState & { custom: S }, ReplayHelpers & H> = {
     name: opts.name,
-    // Fake = real: we answer for the real host on :80 and :443.
     hostnames: [host],
     secretRefs,
-    // Cassettes are NOT auto-loaded — a fork starts with an empty replay
-    // set, so a test that loads nothing fails loud (599). Tests call
-    // `replay(...)` to populate it.
-    state: (): CassetteState => ({
-      cassette: emptyCassette(opts.name, host),
-      index: new Map(),
-      cursor: new Map(),
-      recorded: [],
-      dirty: false,
-    }),
-    handler,
-    helpers: ({ state }): ReplayHelpers => ({
-      replay(file: string | Cassette): ReplaySummary {
-        let loaded: Cassette;
-        let label: string;
-        if (file && typeof file === "object") {
-          loaded = coerceCassette(file, opts.name, host);
-          label = file.fake || "(inline)";
-        } else if (typeof file === "string" && file.length > 0) {
-          label = file;
-          loaded = readCassetteFile(opts.name, file, host);
-        } else {
-          throw new Error(
-            `replayFake(${opts.name}): replay(...) needs a cassette path under spectest/tests/ ` +
-              `(e.g. "recordings/${opts.name}.json").`,
-          );
-        }
-        // Build/validate before replacing live state: a bad key/cassette
-        // must leave the previous cassette and consumption cursors intact.
-        const index = new Map<string, number[]>();
-        for (const [i, interaction] of loaded.interactions.entries()) {
-          const sig = signature(interaction.request, `${JSON.stringify(label)} interaction #${i + 1}`);
-          const queue = index.get(sig);
-          if (queue) queue.push(i);
-          else index.set(sig, [i]);
+    state: () => opts.state
+      ? Promise.resolve(opts.state()).then(initialState)
+      : initialState(undefined as S),
+    handler: (request, state, ctx) => opts.handler
+      ? opts.handler(request, state.custom, {
+          ...ctx,
+          replay: (delegated) => handler(delegated, state, ctx),
+        })
+      : handler(request, state, ctx),
+    helpers: ({ name, state, ctx }) => {
+      const builtins = replayHelpers(state);
+      if (!opts.helpers) return builtins as ReplayHelpers & H;
+      return Promise.resolve(opts.helpers({ name, state: state.custom, ctx })).then((custom) => {
+        for (const key of Object.keys(builtins)) {
+          if (key in custom) {
+            throw new Error(`replayFake(${opts.name}): custom helper ${JSON.stringify(key)} is reserved for recording/replay; choose another name`);
+          }
         }
-        // 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 };
-      },
-      dump(): Cassette {
-        return structuredClone({
-          version: 1,
-          fake: opts.name,
-          host,
-          interactions: [...state.cassette.interactions, ...state.recorded],
-        });
-      },
-      recorded(): CassetteInteraction[] {
-        return structuredClone(state.recorded);
-      },
-      count(): number {
-        return state.recorded.length;
-      },
-    }),
+        return { ...custom, ...builtins };
+      });
+    },
   };
   return def;
 }