@specific.dev/spectest 0.98.0 → 0.100.0

package/dist/harness/ingress-table.d.ts

@@ -41,6 +41,7 @@
  * thing {@link planBind} still has to say is whether the listener exists
  * yet.
  */
+import type { CorsMode } from "../ingress.js";
 /**
  * One hostname's upstream: a fake handled in-process, or a container.
  *
@@ -56,6 +57,7 @@ export type Route<F = unknown> = {
     service: string;
     port: number;
     http2?: boolean;
+    cors?: CorsMode;
 };
 /** A PEM leaf + key, as handed to `Bun.serve`'s TLS config. */
 export interface Leaf {

package/dist/index.d.ts

@@ -29,8 +29,8 @@ export { type CoverageAdapter, type CoverageCaptureContext, type CoverageConfigu
 import { type ServiceCoverage } from "./coverage.js";
 export { ca } from "./environment-ca.js";
 export { certificate, dnsName, proxy, provides, lowerIngress, isWildcard, SELF_SERVICE_TOKEN, } from "./ingress.js";
-export type { CertificateDecl, DnsDecl, ProxyDecl, IngressDecl, DnsTarget, LoweredIngress, } from "./ingress.js";
-import type { DnsTarget } from "./ingress.js";
+export type { CorsMode, CertificateDecl, DnsDecl, ProxyDecl, IngressDecl, DnsTarget, LoweredIngress, } from "./ingress.js";
+import { type CorsMode, type DnsTarget } from "./ingress.js";
 import type { InterceptHandler, InterceptNext, InterceptedRequest } from "./harness/intercept.js";
 export type { InterceptHandler, InterceptNext, InterceptedRequest };
 /**
@@ -744,6 +744,9 @@ export interface ServiceTls {
     /** Accept HTTP/2 over TLS and forward it as plaintext HTTP/2 (h2c).
      * Required for gRPC. HTTP/1.1 continues to use the existing HTTP proxy. */
     http2?: boolean;
+    /** Preserve upstream CORS policy by default. "permissive" opts HTTP/1
+     * ingress into answering preflights and adding credentialed CORS headers. */
+    cors?: CorsMode;
 }
 /** @internal Normalized wire representation; legacy definitions remain accepted. */
 export type NormalizedServiceImage = {
@@ -1458,6 +1461,9 @@ export interface FakeDefinition<S = any, H extends Record<string, unknown> = Rec
     hostnames: readonly string[];
     /** TCP port the fake listens on. Default `80`. */
     port?: number;
+    /** Preserve handler/interceptor CORS policy by default. "permissive"
+     * answers preflights and adds credentialed CORS headers at ingress. */
+    cors?: CorsMode;
     /**
      * Build the fake's initial state. Called once when the project loads.
      * The returned value lives in daemon memory for the rest of the

package/dist/index.js

@@ -49,6 +49,7 @@ export { ca } from "./environment-ca.js";
 // `tls` / `hostnames` fields and `defineFake(...)` are built on. See
 // `ingress.ts`.
 export { certificate, dnsName, proxy, provides, lowerIngress, isWildcard, SELF_SERVICE_TOKEN, } from "./ingress.js";
+import { validateCorsMode } from "./ingress.js";
 import { isWildcard as isWildcardHost } from "./ingress.js";
 // ──────────────────────────────────────────────────────────────────────────
 // Service groups — one services-map entry that expands to several services.
@@ -363,6 +364,7 @@ function validateEnvironmentConfig(config) {
             }
             if (entry.http2 !== undefined && typeof entry.http2 !== "boolean")
                 throw new Error(`service "${name}" tls http2 must be a boolean`);
+            validateCorsMode(entry.cors);
             const h = entry.hostname.toLowerCase();
             if (!HOSTNAME_RE.test(hostPatternBody(h))) {
                 throw new Error(`service "${name}" tls hostname ${JSON.stringify(entry.hostname)} is not a multi-label DNS name or wildcard (e.g. "app.test", "*.us-east-1.amazonaws.com")`);
@@ -408,6 +410,7 @@ export function defineFake(opts) {
             throw new Error(`defineFake(${opts.name}): hostname ${JSON.stringify(h)} ends in reserved ".internal" TLD`);
         }
     }
+    validateCorsMode(opts.cors);
     if (typeof opts.handler !== "function") {
         throw new Error(`defineFake(${opts.name}): \`handler\` is required`);
     }

package/dist/ingress.d.ts

@@ -7,6 +7,11 @@ export type DnsTarget = {
 } | {
     service: string;
 };
+/** Passthrough preserves application CORS policy (the default). Permissive
+ * answers preflights and adds credentialed CORS headers at HTTP/1 ingress. */
+export type CorsMode = "passthrough" | "permissive";
+/** @internal Validate JavaScript config as well as TypeScript callers. */
+export declare function validateCorsMode(cors: unknown): void;
 export interface CertificateDecl {
     kind: "certificate";
     /** Hostnames the leaf cert's SANs cover. One cert is minted per decl. */
@@ -24,6 +29,7 @@ export interface ProxyDecl {
         service: string;
         port: number;
         http2?: boolean;
+        cors?: CorsMode;
     };
 }
 export type IngressDecl = CertificateDecl | DnsDecl | ProxyDecl;
@@ -71,6 +77,7 @@ export declare function proxy(hostname: string, upstream: {
     service: string;
     port: number;
     http2?: boolean;
+    cors?: CorsMode;
 }): ProxyDecl;
 /**
  * Attach low-level ingress decls to a service definition a component
@@ -100,6 +107,7 @@ export interface LoweredIngress {
         service: string;
         port: number;
         http2?: boolean;
+        cors?: CorsMode;
     }[];
     /** Hostnames that resolve to the daemon ingress gateway (DNS registry
      *  + `--add-host` on every container). Covers fakes, TLS proxies, and

package/dist/ingress.js

@@ -17,6 +17,12 @@
 // deserialises: the decls live on the `Project` (daemon-side only) and,
 // when attached to a service, ride on a Symbol key that `JSON.stringify`
 // drops — so Rust's `deny_unknown_fields` never sees them.
+/** @internal Validate JavaScript config as well as TypeScript callers. */
+export function validateCorsMode(cors) {
+    if (cors !== undefined && cors !== "passthrough" && cors !== "permissive") {
+        throw new Error('cors must be "passthrough" or "permissive"');
+    }
+}
 /** Token a component can use in a decl where it can't know its own
  *  services-map key yet — resolved to that key during `lowerIngress`.
  *  Mirrors the `{{SPECTEST_SERVICE}}` token honoured in `files`. */
@@ -101,6 +107,7 @@ export function proxy(hostname, upstream) {
     }
     if (upstream.http2 !== undefined && typeof upstream.http2 !== "boolean")
         throw new Error("proxy(): http2 must be a boolean");
+    validateCorsMode(upstream.cors);
     return { kind: "proxy", hostname: hostname.toLowerCase(), upstream };
 }
 /** Symbol key under which `provides(...)` stashes a component's ingress
@@ -165,7 +172,7 @@ export function lowerIngress(project) {
                 break;
             case "proxy": {
                 const service = resolveSelf(decl.upstream.service, selfKey);
-                proxies.push({ hostname: decl.hostname, service, port: decl.upstream.port, ...(decl.upstream.http2 ? { http2: true } : {}) });
+                proxies.push({ hostname: decl.hostname, service, port: decl.upstream.port, ...(decl.upstream.http2 ? { http2: true } : {}), ...(decl.upstream.cors ? { cors: decl.upstream.cors } : {}) });
                 // A proxied hostname must route to the daemon. A wildcard one can
                 // only be answered by the resolver (there is no `--add-host` for a
                 // pattern), so it goes in the wildcard table pointed at the ingress.
@@ -204,7 +211,7 @@ export function lowerIngress(project) {
         // `tls: [{ hostname, port }]` → cert + TLS-terminated reverse proxy.
         for (const entry of svc.tls ?? []) {
             applyDecl(certificate([entry.hostname]), name);
-            applyDecl(proxy(entry.hostname, { service: name, port: entry.port, ...(entry.http2 ? { http2: true } : {}) }), name);
+            applyDecl(proxy(entry.hostname, { service: name, port: entry.port, ...(entry.http2 ? { http2: true } : {}), ...(entry.cors ? { cors: entry.cors } : {}) }), name);
         }
         // `hostnames: [h]` → plain peer alias (no daemon hop).
         for (const h of svc.hostnames ?? []) {

package/package.json

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

package/src/components/index.ts

@@ -85,7 +85,10 @@ export { okta, type OktaOptions } from "./okta.js";
 export {
   replayFake,
   type ReplayFakeOptions,
-  type ReplayMatch,
+  type ReplayKey,
+  type ReplayRequest,
+  type MatchKey,
+  type JsonValue,
   type InjectRule,
   type InjectMatch,
   type StringMatch,

package/src/components/replay-key.ts

@@ -0,0 +1,127 @@
+import { createHash } from "node:crypto";
+import type { CassetteRequest } from "./replayFake.js";
+
+export type JsonValue =
+  | null | boolean | number | string
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+/** Identity content. Objects compare independently of property order; arrays
+ *  preserve order. Bytes are distinct from strings, arrays, and objects. */
+export type MatchKey =
+  | null | boolean | number | string | Uint8Array
+  | readonly MatchKey[]
+  | { readonly [key: string]: MatchKey };
+
+/** A buffered request view shared by incoming and recorded requests.
+ *  Headers are lowercase and exclude credentials. Recorded values may be
+ *  redacted; choose identity fields that survive recording. */
+export interface ReplayRequest {
+  readonly method: string;
+  readonly path: string;
+  readonly query: Readonly<Record<string, readonly string[]>>;
+  readonly headers: Readonly<Record<string, string>>;
+  /** Decode UTF-8, throwing on invalid text. */
+  text(): string;
+  /** Parse JSON. The type parameter is not runtime validation. */
+  json<T = JsonValue>(): T;
+  /** Return an independent copy of the body bytes. */
+  bytes(): Uint8Array;
+}
+
+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 {
+  const hash = createHash("sha256");
+  const ancestors = new Set<object>();
+  const visit = (value: unknown): void => {
+    if (value === null || typeof value === "boolean" || typeof value === "string") {
+      hash.update(JSON.stringify(value));
+      return;
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+      hash.update(JSON.stringify(value));
+      return;
+    }
+    if (value instanceof Uint8Array) {
+      hash.update(`bytes:${value.byteLength}:`);
+      hash.update(value);
+      return;
+    }
+    if (value instanceof Promise) {
+      // Report the invalid callback synchronously without leaving a rejected
+      // async callback to become an unrelated unhandled-rejection failure.
+      void value.catch(() => {});
+      throw new Error("key callbacks must be synchronous, not return promises");
+    }
+    if (typeof value !== "object" || value === null) {
+      throw new Error("key must contain only JSON values or Uint8Array bytes (no undefined, functions, or non-finite numbers)");
+    }
+    if (ancestors.has(value)) throw new Error("key must not contain cycles");
+    if (Object.getOwnPropertySymbols(value).length > 0) {
+      throw new Error("key must not contain symbol properties");
+    }
+    ancestors.add(value);
+    if (Array.isArray(value)) {
+      if (Object.keys(value).length !== value.length) {
+        throw new Error("key arrays must be dense and have no extra properties");
+      }
+      hash.update("[");
+      for (let i = 0; i < value.length; i++) {
+        if (!Object.hasOwn(value, i)) throw new Error("key arrays must be dense");
+        visit(value[i]);
+        hash.update(",");
+      }
+      hash.update("]");
+    } else {
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) {
+        throw new Error("key must use plain objects, not promises, dates, maps, or class instances; callbacks must be synchronous");
+      }
+      hash.update("{");
+      for (const name of Object.keys(value).sort()) {
+        hash.update(JSON.stringify(name));
+        hash.update(":");
+        visit((value as Record<string, unknown>)[name]);
+        hash.update(",");
+      }
+      hash.update("}");
+    }
+    ancestors.delete(value);
+  };
+  visit(key);
+  return hash.digest("hex");
+}
+
+function bodyBytes(request: CassetteRequest): Uint8Array {
+  return Buffer.from(request.body ?? "", request.bodyEncoding === "base64" ? "base64" : "utf8");
+}
+
+function requestView(request: CassetteRequest): ReplayRequest {
+  let bytes: Uint8Array | undefined;
+  let text: string | undefined;
+  const readBytes = () => bytes ??= bodyBytes(request);
+  const readText = () => text ??= new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(readBytes());
+  const query = Object.fromEntries(Object.entries(request.query).map(([k, v]) => [k, Object.freeze([...v])]));
+  return Object.freeze({
+    method: request.method.toUpperCase(),
+    path: request.path,
+    query: Object.freeze(query),
+    headers: Object.freeze({ ...request.headers }),
+    text: readText,
+    json: <T = JsonValue>(): T => JSON.parse(readText()) as T,
+    bytes: () => Uint8Array.from(readBytes()),
+  });
+}
+
+/** Internal only; the SDK exports the request/key types, not this function. */
+export function replaySignature(request: CassetteRequest, key?: ReplayKey): string {
+  if (key) return hashKey(key(requestView(request)));
+  // Existing cassettes retain the original byte hash even when their stored
+  // text was redacted. Older/hand-written cassettes may only have the body.
+  const body = request.bodyHash ?? `sha256:${createHash("sha256").update(bodyBytes(request)).digest("hex")}`;
+  return hashKey({ method: request.method.toUpperCase(), path: request.path, query: request.query, body });
+}

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

@@ -0,0 +1,114 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Isolate module mocks from other tests. Drive the actual record handler,
+// replacing only DNS/HTTPS transport; no credentials or external egress.
+test("recorded headers, redaction, and exact body bytes survive record → replay", async () => {
+  const moduleUrl = (file: string) => JSON.stringify(new URL(file, import.meta.url).href);
+  const script = `
+    import { strict as assert } from "node:assert";
+    import { EventEmitter } from "node:events";
+    import { mock, test } from "bun:test";
+    import * as dnsPacket from ${JSON.stringify(import.meta.resolve("dns-packet"))};
+
+    test("record round trip", async () => {
+    mock.module("node:dgram", () => ({ createSocket() {
+      const socket = new EventEmitter();
+      socket.close = () => {};
+      socket.send = (_query, _port, _host, done) => {
+        done();
+        queueMicrotask(() => socket.emit("message", dnsPacket.encode({
+          type: "response", id: 1,
+          answers: [{ type: "A", name: "api.example.test", ttl: 60, data: "127.0.0.1" }],
+        })));
+      };
+      return socket;
+    } }));
+
+    const upstreamHeaders = [];
+    mock.module("node:https", () => ({ request(options, callback) {
+      upstreamHeaders.push(options.headers);
+      const req = new EventEmitter();
+      req.write = () => {};
+      req.end = () => queueMicrotask(() => {
+        const res = new EventEmitter();
+        res.statusCode = 200;
+        res.headers = { "content-type": "text/plain" };
+        callback(res);
+        res.emit("data", Buffer.from("response"));
+        res.emit("end");
+      });
+      return req;
+    } }));
+
+    const { replayFake } = await import(${moduleUrl("./replayFake.ts")});
+    const { setRecordSecrets } = await import(${moduleUrl("../record-secrets.ts")});
+    setRecordSecrets({ API_KEY: "recording-secret" });
+    const options = {
+      name: "test", host: "api.example.test",
+      inject: [{ headers: { authorization: "Bearer {{secret:API_KEY}}" } }],
+      redactPatterns: ["private-field"],
+    };
+    const record = replayFake({ ...options, mode: "record" });
+    const state = record.state();
+    const helpers = record.helpers({ name: "test", state, ctx: {} });
+    const bodies = ["\\ufeffhello", new Uint8Array([0, 128, 255]), "recording-secret private-field"];
+    for (const [i, body] of bodies.entries()) {
+      const res = await record.handler(new Request("https://api.example.test/messages", {
+        method: "POST", body,
+        headers: {
+          "X-Task": "task-" + i,
+          authorization: "Bearer dummy", cookie: "dummy-cookie",
+          "api-key": "dummy-api-key", "x-goog-api-key": "dummy-google-key",
+          "x-extra": "recording-secret private-field",
+        },
+      }), state, {});
+      assert.equal(res.status, 200, await res.text());
+    }
+    assert.equal(helpers.count(), 3);
+    assert.equal(upstreamHeaders[0].authorization, "Bearer recording-secret");
+    const cassette = JSON.parse(JSON.stringify(helpers.dump()));
+    assert.equal(cassette.interactions[0].request.body, "\\ufeffhello");
+    assert.equal(cassette.interactions[1].request.bodyEncoding, "base64");
+    assert.equal(cassette.interactions[2].request.body, "<REDACTED:API_KEY> <REDACTED>");
+    for (const [i, it] of cassette.interactions.entries()) {
+      assert.equal(it.request.headers["x-task"], "task-" + i);
+      assert.equal(it.request.headers["x-extra"], "<REDACTED:API_KEY> <REDACTED>");
+      for (const name of ["authorization", "cookie", "api-key", "x-goog-api-key"]) {
+        assert.equal(it.request.headers[name], undefined);
+      }
+    }
+    assert.equal(JSON.stringify(cassette).includes("recording-secret"), false);
+
+    for (const key of [undefined, r => r.headers["x-task"]]) {
+      const replay = replayFake({ ...options, mode: "replay", key });
+      const replayState = replay.state();
+      replay.helpers({ name: "test", state: replayState, ctx: {} }).replay(cassette);
+      for (const i of [2, 0, 1]) {
+        const res = await replay.handler(new Request("https://api.example.test/messages", {
+          method: "POST", body: bodies[i], headers: { "X-Task": "task-" + i },
+        }), replayState, {});
+        assert.equal(res.status, 200);
+        assert.equal(await res.text(), "response");
+      }
+    }
+    assert.equal(upstreamHeaders.length, 3); // Replay never forwards.
+    });
+  `;
+  const dir = await mkdtemp(join(tmpdir(), "spectest-replay-record-"));
+  try {
+    const file = join(dir, "record.test.ts");
+    await writeFile(file, script);
+    const child = Bun.spawn([process.execPath, "test", file], {
+      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 });
+  }
+}, 10_000);

package/src/components/replayFake.test.ts

@@ -0,0 +1,254 @@
+import { describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import type { FakeContext } from "../index.js";
+import { replayFake, type Cassette, type CassetteInteraction, type ReplayFakeOptions, type ReplayRequest, type ReplayKey, type MatchKey } from "./index.js";
+
+const context = {} as FakeContext;
+const host = "api.example.test";
+const sha = (body: string | Uint8Array) => `sha256:${createHash("sha256").update(body).digest("hex")}`;
+
+function interaction(body: string | Uint8Array, answer: string, path = "/messages"): CassetteInteraction {
+  return {
+    request: {
+      method: "POST", path, query: {}, headers: { "content-type": "application/json" },
+      body: typeof body === "string" ? body : Buffer.from(body).toString("base64"),
+      bodyEncoding: typeof body === "string" ? "utf8" : "base64",
+      bodyHash: sha(body),
+    },
+    response: { status: 200, headers: {}, body: answer, bodyEncoding: "utf8" },
+  };
+}
+
+function cassette(interactions: CassetteInteraction[]): Cassette {
+  return { version: 1, fake: "test", host, interactions };
+}
+
+async function harness(options: Partial<ReplayFakeOptions> = {}) {
+  const fake = replayFake({ name: "test", host, mode: "replay", ...options });
+  const state = await fake.state!();
+  const helpers = await fake.helpers!({ name: "test", state, ctx: context });
+  return {
+    state, helpers,
+    async send(body: string | Uint8Array = "", path = "/messages", init: RequestInit = {}) {
+      return await fake.handler(new Request(`https://${host}${path}`, {
+        method: "POST", body: body as BodyInit, ...init,
+      }), state, context);
+    },
+  };
+}
+
+describe("replay request identity", () => {
+  test("default matches 654 concurrent requests by body, independently of arrival order", async () => {
+    const h = await harness();
+    const calls = Array.from({ length: 654 }, (_, id) => interaction(JSON.stringify({ id }), `answer-${id}`));
+    h.helpers.replay(cassette(calls));
+    // A permutation visits every identity once in a different order.
+    const results = await Promise.all(calls.map(async (_, i) => {
+      const id = (i * 37) % calls.length;
+      const response = await h.send(JSON.stringify({ id }));
+      expect(response.status).toBe(200);
+      expect(await response.text()).toBe(`answer-${id}`);
+    }));
+    expect(results).toHaveLength(654);
+    expect(h.state.cursor.size).toBe(654);
+  });
+
+  test("default uses method/path/normalized query/exact bytes, including old cassettes without hashes", async () => {
+    const h = await harness();
+    const it = interaction('{"a":1}', "ok");
+    delete it.request.bodyHash;
+    delete it.request.bodyEncoding;
+    it.request.query = { b: ["1", "2"], a: ["x"] };
+    h.helpers.replay(cassette([it]));
+    for (const [body, path, init] of [
+      ['{ "a":1}', "/messages?a=x&b=2&b=1", {}],
+      ['{"a":1}', "/other?a=x&b=2&b=1", {}],
+      ['{"a":1}', "/messages?a=x&b=2&b=1", { method: "PUT" }],
+      ['{"a":1}', "/messages?a=y&b=2&b=1", {}],
+    ] as const) expect((await h.send(body, path, init)).status).toBe(599);
+    expect(await (await h.send('{"a":1}', "/messages?b=2&a=x&b=1")).text()).toBe("ok");
+  });
+
+  test("the existing committed HTTP cassette still replays with the new default", async () => {
+    const h = await harness();
+    const existing = await Bun.file(new URL("../../../examples/replay-fake/spectest/tests/recordings/httpbin.json", import.meta.url)).json() as Cassette;
+    h.helpers.replay(existing);
+    const response = await h.send("", "/get?hello=world", { method: "GET", body: null });
+    expect(response.status).toBe(200);
+    expect((await response.json()).args).toEqual({ hello: ["world"] });
+  });
+
+  test("SigV4 query credentials stay outside default and custom identity", async () => {
+    for (const key of [undefined, (r: ReplayRequest) => ({ path: r.path, query: r.query })]) {
+      const h = await harness({ key, sign: { type: "awsSigv4", accessKeyId: "ACCESS", secretAccessKey: "SECRET" } });
+      h.helpers.replay(cassette([interaction("body", "ok")]));
+      expect(await (await h.send("body", "/messages?X-Amz-Signature=changing&X-Amz-Date=20261001")).text()).toBe("ok");
+    }
+  });
+
+  test("Dentio keys separate model/tasks while ignoring a changing date", async () => {
+    let evaluations = 0;
+    const h = await harness({ key(request) {
+      evaluations++;
+      const body = request.json<{ system: { text: string }[] }>();
+      return { model: request.path, task: body.system[0].text.slice(0, 200) };
+    } });
+    const calls = Array.from({ length: 8 }, (_, i) => ({
+      task: `task-${i}`.padEnd(200, "."),
+      path: `/model/${i < 4 ? "haiku" : "sonnet"}/converse`,
+    }));
+    const body = (task: string, date: string) => JSON.stringify({ system: [{ text: `${task} Today: ${date}` }] });
+    h.helpers.replay(cassette(calls.map((call, i) => interaction(body(call.task, "2026-10-01"), i === 4 ? "Karies 16o" : `task-${i}`, call.path))));
+    expect(evaluations).toBe(8);
+    for (const i of [7, 2, 4, 0, 6, 1, 5, 3]) {
+      expect(await (await h.send(body(calls[i].task, "2026-10-02"), calls[i].path)).text()).toBe(i === 4 ? "Karies 16o" : `task-${i}`);
+    }
+    expect(evaluations).toBe(16); // No rescanning/recomputing cassette keys.
+  });
+
+  test("custom key is the entire identity, with no implicit HTTP dimensions", async () => {
+    const h = await harness({ key: request => request.json<{ task: string }>().task });
+    h.helpers.replay(cassette([interaction('{"task":"same","date":"yesterday"}', "ok", "/old")]));
+    expect(await (await h.send('{"task":"same","date":"today"}', "/new?nonce=123", { method: "PUT" })).text()).toBe("ok");
+  });
+
+  test("JSON objects compare structurally but arrays preserve order", async () => {
+    const h = await harness({ key: request => request.json() });
+    h.helpers.replay(cassette([interaction('{"b":2,"a":{"x":[1,2]}}', "ok")]));
+    expect((await h.send('{"a":{"x":[2,1]},"b":2}')).status).toBe(599);
+    expect(await (await h.send('{ "a": {"x":[1,2]}, "b": 2 }')).text()).toBe("ok");
+  });
+
+  test("binary keys are lossless and distinct from JSON lookalikes", async () => {
+    const h = await harness({ key: request => ({ body: request.bytes() }) });
+    const bytes = new Uint8Array([0, 255, 128]);
+    h.helpers.replay(cassette([interaction(bytes, "binary")]));
+    expect((await h.send("[0,255,128]")).status).toBe(599);
+    expect(await (await h.send(bytes)).text()).toBe("binary");
+
+    const mixed = await harness({ key: r => r.path === "/binary" ? new Uint8Array([1, 2]) : r.json() });
+    mixed.helpers.replay(cassette([interaction("", "bytes", "/binary"), interaction("[1,2]", "array"), interaction('{"0":1,"1":2}', "object")]));
+    expect(await (await mixed.send("[1,2]")).text()).toBe("array");
+    expect(await (await mixed.send('{"0":1,"1":2}')).text()).toBe("object");
+    expect(await (await mixed.send("", "/binary")).text()).toBe("bytes");
+  });
+
+  test("empty and BOM-prefixed bodies preserve their bytes", async () => {
+    for (const key of [undefined, (r: ReplayRequest) => r.bytes()]) {
+      const h = await harness({ key });
+      h.helpers.replay(cassette([interaction("", "empty"), interaction("\ufeffhello", "bom")]));
+      expect(await (await h.send("")).text()).toBe("empty");
+      expect((await h.send("hello")).status).toBe(599);
+      expect(await (await h.send("\ufeffhello")).text()).toBe("bom");
+    }
+  });
+
+  test("same-key queues consume once, fail on exhaustion, and reset on reload", async () => {
+    const h = await harness();
+    const c = cassette([interaction("same", "first"), interaction("other", "other"), interaction("same", "second")]);
+    h.helpers.replay(c);
+    expect(await Promise.all([h.send("same"), h.send("same")].map(async p => (await p).text()))).toEqual(["first", "second"]);
+    const exhausted = await h.send("same");
+    expect(exhausted.status).toBe(599);
+    expect(await exhausted.text()).toContain("exhausted key");
+    expect(await (await h.send("missing")).text()).toContain("unknown key");
+    expect(await (await h.send("other")).text()).toBe("other");
+    h.helpers.replay(c);
+    expect(await (await h.send("same")).text()).toBe("first");
+  });
+
+  test("cassette keys and cursors are isolated between fake states", async () => {
+    const a = await harness(), b = await harness();
+    const c = cassette([interaction("same", "ok")]);
+    a.helpers.replay(c); b.helpers.replay(c);
+    expect(await (await a.send("same")).text()).toBe("ok");
+    expect((await a.send("same")).status).toBe(599);
+    expect(await (await b.send("same")).text()).toBe("ok");
+    // Inline input cannot mutate a loaded/indexed cassette.
+    c.interactions[0].response.body = "mutated";
+    expect(a.helpers.dump().interactions[0].response.body).toBe("ok");
+    a.helpers.dump().interactions[0].response.body = "mutated dump";
+    expect(a.helpers.dump().interactions[0].response.body).toBe("ok");
+  });
+
+  test("request accessors are synchronous, reusable, and omit internal hashes/credentials", async () => {
+    const h = await harness({ key(r) {
+      expect("bodyHash" in r).toBe(false);
+      expect(r.headers.authorization).toBeUndefined();
+      expect(r.headers.cookie).toBeUndefined();
+      expect(Object.isFrozen(r)).toBe(true);
+      expect(Object.isFrozen(r.query)).toBe(true);
+      const bytes = r.bytes(); bytes.fill(0);
+      expect(r.text()).toBe('{"a":1}');
+      expect(r.json<{ a: number }>()).toEqual({ a: 1 });
+      return r.headers["x-task"]!;
+    } });
+    const it = interaction('{"a":1}', "ok");
+    it.request.headers["x-task"] = "journal";
+    h.helpers.replay(cassette([it]));
+    expect(await (await h.send('{"a":1}', "/messages", { headers: { "X-Task": "journal", authorization: "secret", cookie: "secret" } })).text()).toBe("ok");
+  });
+
+  test("bad incoming JSON fails without consuming a response; bad loads preserve live state", async () => {
+    const h = await harness({ key: r => r.json() });
+    h.helpers.replay(cassette([interaction("{}", "ok")]));
+    expect(() => h.helpers.replay(cassette([interaction("invalid", "bad")]))).toThrow("interaction #1");
+    const bad = await h.send("invalid");
+    expect(bad.status).toBe(599);
+    expect(await bad.text()).toContain("invalid replay key");
+    expect(await (await h.send("{}")).text()).toBe("ok");
+  });
+
+  test.each([
+    undefined, NaN, Infinity, BigInt(1), new Date(), new Map(), Promise.resolve("x"),
+    { missing: undefined }, [undefined], Array(1), () => "x",
+  ])("rejects unsupported keys instead of silently collapsing identities: %p", async value => {
+    const h = await harness({ key: () => value as MatchKey });
+    expect(() => h.helpers.replay(cassette([interaction("", "bad")]))).toThrow("invalid replay key");
+  });
+
+  test("rejects cyclic keys but permits shared subobjects", async () => {
+    const value: Record<string, MatchKey> = {};
+    value.self = value;
+    const bad = await harness({ key: () => value });
+    expect(() => bad.helpers.replay(cassette([interaction("", "bad")]))).toThrow("cycles");
+    const shared = { a: 1 };
+    const good = await harness({ key: () => [shared, shared] });
+    good.helpers.replay(cassette([interaction("", "ok")]));
+    expect(await (await good.send()).text()).toBe("ok");
+  });
+
+  test("rejects an async callback that throws without leaking an unhandled rejection", async () => {
+    const h = await harness({ key: (async () => { throw new Error("async failure"); }) as unknown as ReplayFakeOptions["key"] });
+    expect(() => h.helpers.replay(cassette([interaction("", "bad")]))).toThrow("synchronous");
+    await Promise.resolve();
+  });
+
+  test("old match options fail with migration guidance", () => {
+    expect(() => replayFake({ name: "test", host, match: { body: "hash" } } as unknown as ReplayFakeOptions)).toThrow("has been replaced by `key(request)`");
+  });
+});
+
+// Compile-time API checks, verified by the targeted TypeScript check as well
+// as the SDK build. Never invoked: invalid callbacks must not run.
+function publicTypes(request: ReplayRequest): void {
+  const json: ReplayKey = r => r.json();
+  const bytes: ReplayKey = r => ({ body: r.bytes(), query: r.query });
+  void [json, bytes];
+  // @ts-expect-error bodyHash is internal, not part of the callback view.
+  request.bodyHash;
+  // @ts-expect-error Request metadata is read-only.
+  request.method = "POST";
+  // @ts-expect-error Query values are read-only.
+  request.query.id.push("another");
+  // @ts-expect-error Callbacks must be synchronous.
+  const asyncKey: ReplayKey = async r => r.text();
+  // @ts-expect-error Undefined is not an identity.
+  const absentKey: ReplayKey = () => undefined;
+  void [asyncKey, absentKey];
+  replayFake({ name: "test", host,
+    // @ts-expect-error Per-dimension matching switches have been removed.
+    match: { body: "hash" },
+  });
+}
+void publicTypes;