@dynamicagents/core 0.9.0

package/dist/testing/mock-model.d.ts

@@ -0,0 +1,77 @@
+import { MockLanguageModelV3 } from "ai/test";
+export interface MockStep {
+    /**
+     * Assistant text for this step. On its own → finishReason "stop", which for the
+     * main-agent round is a *failed* attempt: prose is not an ending there, so use
+     * {@link finalReply} to script an answer. Alongside `toolCall` → the
+     * intermediate content emitted before a tool call.
+     */
+    text?: string;
+    /** Emit a tool call (finishReason "tool-calls"); may accompany `text`. */
+    toolCall?: {
+        toolName: string;
+        input?: unknown;
+    };
+    /**
+     * Emit several tool calls in **one** step, which a real model does whenever it
+     * decides two things at once. That is the only way to script the cases the round
+     * has to arbitrate: two different endings in one step (precedence decides), or
+     * the same ending twice (the tool's own `parse` decides).
+     */
+    toolCalls?: {
+        toolName: string;
+        input?: unknown;
+    }[];
+}
+/**
+ * A step where the main agent answers the user — the `final_reply` control call.
+ *
+ * Scripting a bare `{ text }` instead reproduces the bug this tool exists to catch
+ * (a model narrating rather than acting) and fails the attempt, which is what the
+ * error-path specs use it for.
+ */
+export declare function finalReply(text: string, opts?: {
+    text?: string;
+}): MockStep;
+/**
+ * A mock model that returns each step in sequence — one per `generateText` call.
+ * Uses the function form (with our own counter) rather than the array form, whose
+ * call-count indexing is off by one in this SDK version. Extra calls repeat the
+ * last step.
+ */
+export declare function mockModel(...steps: MockStep[]): MockLanguageModelV3;
+/**
+ * A model whose every call throws, and a count of how many times it was asked.
+ *
+ * The count is the point. Several of the attempt ladder's rules are about a call
+ * that must *not* happen — a fallback slot left unspent, a repair not attempted
+ * — and those are invisible to an assertion on the returned outcome alone, which
+ * can be right for the wrong reason.
+ */
+export declare function throwingModel(error: unknown): {
+    model: MockLanguageModelV3;
+    calls: () => number;
+};
+/** {@link mockModel}, plus the same call count {@link throwingModel} reports. */
+export declare function countingModel(...steps: MockStep[]): {
+    model: MockLanguageModelV3;
+    calls: () => number;
+};
+/**
+ * A model that fails the first `failures` calls with a retryable `APICallError`,
+ * then behaves like {@link mockModel}.
+ *
+ * Exists for the one behaviour a scripted-outcome assertion cannot see: whether
+ * a rate limit was *waited out on the same model* or fell straight through to
+ * the fallback. Only the call count distinguishes them — both produce a
+ * successful round.
+ *
+ * `retry-after: 0` is deliberate. The AI SDK honours the header and its own
+ * backoff opens at two seconds, which would spend real seconds asserting
+ * something that has nothing to do with duration. Zero exercises the identical
+ * path — header parsed, preferred over the exponential delay, waited — for free.
+ */
+export declare function rateLimitedModel(failures: number, ...steps: MockStep[]): {
+    model: MockLanguageModelV3;
+    calls: () => number;
+};

package/dist/testing/mock-model.js

@@ -0,0 +1,136 @@
+import { MockLanguageModelV3 } from "ai/test";
+// From `ai`, not `@ai-sdk/provider`. `ai` re-exports the class and is a declared
+// peer; reaching for the provider package directly makes this module — which is
+// on the published `/testing` subpath every consumer loads — depend on a package
+// core does not declare and only resolves today by hoisting.
+import { APICallError } from "ai";
+/**
+ * Test doubles for the LLM. Lets the tool-loop / executor specs run the real
+ * `generateText` machinery (tool execution, multi-step, fallback) against a
+ * scripted model with no network or `AI` binding.
+ */
+/** Zeroed usage block satisfying the LanguageModelV3 result shape. */
+const USAGE = {
+    inputTokens: { total: 0, noCache: 0, cacheRead: 0, cacheWrite: 0 },
+    outputTokens: { total: 0, text: 0, reasoning: 0 }
+};
+/**
+ * A step where the main agent answers the user — the `final_reply` control call.
+ *
+ * Scripting a bare `{ text }` instead reproduces the bug this tool exists to catch
+ * (a model narrating rather than acting) and fails the attempt, which is what the
+ * error-path specs use it for.
+ */
+export function finalReply(text, opts = {}) {
+    return {
+        ...(opts.text !== undefined ? { text: opts.text } : {}),
+        toolCall: { toolName: "final_reply", input: { text } }
+    };
+}
+function stepResult(step) {
+    const content = [];
+    // Keep the empty-string text part so a `{ text: "" }` step still yields "".
+    if (step.text !== undefined)
+        content.push({ type: "text", text: step.text });
+    const calls = [
+        ...(step.toolCall ? [step.toolCall] : []),
+        ...(step.toolCalls ?? [])
+    ];
+    for (const call of calls) {
+        content.push({
+            type: "tool-call",
+            toolCallId: crypto.randomUUID(),
+            toolName: call.toolName,
+            input: JSON.stringify(call.input ?? {})
+        });
+    }
+    const unified = calls.length > 0 ? "tool-calls" : "stop";
+    return {
+        content,
+        finishReason: { unified, raw: undefined },
+        usage: USAGE,
+        warnings: []
+    };
+}
+/**
+ * A mock model that returns each step in sequence — one per `generateText` call.
+ * Uses the function form (with our own counter) rather than the array form, whose
+ * call-count indexing is off by one in this SDK version. Extra calls repeat the
+ * last step.
+ */
+export function mockModel(...steps) {
+    let i = 0;
+    return new MockLanguageModelV3({
+        doGenerate: async () => stepResult(steps[Math.min(i++, steps.length - 1)])
+    });
+}
+/**
+ * A model whose every call throws, and a count of how many times it was asked.
+ *
+ * The count is the point. Several of the attempt ladder's rules are about a call
+ * that must *not* happen — a fallback slot left unspent, a repair not attempted
+ * — and those are invisible to an assertion on the returned outcome alone, which
+ * can be right for the wrong reason.
+ */
+export function throwingModel(error) {
+    let calls = 0;
+    return {
+        model: new MockLanguageModelV3({
+            doGenerate: async () => {
+                calls += 1;
+                throw error;
+            }
+        }),
+        calls: () => calls
+    };
+}
+/** {@link mockModel}, plus the same call count {@link throwingModel} reports. */
+export function countingModel(...steps) {
+    let calls = 0;
+    let i = 0;
+    return {
+        model: new MockLanguageModelV3({
+            doGenerate: async () => {
+                calls += 1;
+                return stepResult(steps[Math.min(i++, steps.length - 1)]);
+            }
+        }),
+        calls: () => calls
+    };
+}
+/**
+ * A model that fails the first `failures` calls with a retryable `APICallError`,
+ * then behaves like {@link mockModel}.
+ *
+ * Exists for the one behaviour a scripted-outcome assertion cannot see: whether
+ * a rate limit was *waited out on the same model* or fell straight through to
+ * the fallback. Only the call count distinguishes them — both produce a
+ * successful round.
+ *
+ * `retry-after: 0` is deliberate. The AI SDK honours the header and its own
+ * backoff opens at two seconds, which would spend real seconds asserting
+ * something that has nothing to do with duration. Zero exercises the identical
+ * path — header parsed, preferred over the exponential delay, waited — for free.
+ */
+export function rateLimitedModel(failures, ...steps) {
+    let calls = 0;
+    let i = 0;
+    return {
+        model: new MockLanguageModelV3({
+            doGenerate: async () => {
+                calls += 1;
+                if (calls <= failures) {
+                    throw new APICallError({
+                        message: "429 Wholesale Rate limited",
+                        url: "mock:chat:test",
+                        requestBodyValues: {},
+                        statusCode: 429,
+                        responseHeaders: { "retry-after": "0" }
+                    });
+                }
+                return stepResult(steps[Math.min(i++, steps.length - 1)]);
+            }
+        }),
+        calls: () => calls
+    };
+}

package/dist/testing/node.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `@dynamicagents/core/testing/node` — the **Node-realm** half of the VCR harness.
+ *
+ * Separate from `@dynamicagents/core/testing` because the two halves cannot share a
+ * module graph. This side reaches `node:fs`; the other side runs inside workerd,
+ * which has no filesystem. `vcr-shared.ts` is the only thing both may touch, and
+ * it is deliberately dependency-free so it can load in either realm.
+ *
+ * Import this from a Vitest **config** (or anything else running in Node), never
+ * from a spec:
+ *
+ * ```ts
+ * // vitest.config.ts
+ * import { defineConfig } from "vitest/config";
+ * import { cloudflareTest } from "@cloudflare/vitest-pool-workers";
+ * import path from "node:path";
+ * import { createVcr, recordFromEnv } from "@dynamicagents/core/testing/node";
+ *
+ * const vcr = createVcr({
+ *   snapshotsDir: path.resolve(import.meta.dirname, "test/snapshots"),
+ *   record: recordFromEnv(),
+ *   // Why a committed cassette is safe, and why playback needs no credentials.
+ *   excludeHeaders: ["x-api-key", "authorization", "cookie", "set-cookie"]
+ * });
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     cloudflareTest({
+ *       wrangler: { configPath: "./wrangler.jsonc" },
+ *       miniflare: { outboundService: vcr.outboundService }
+ *     })
+ *   ],
+ *   test: { globalSetup: ["@dynamicagents/core/testing/vcr-global-setup"] }
+ * });
+ * ```
+ *
+ * `RECORD=1` captures live traffic into every cassette a run activates; anything
+ * else replays. A host with no active cassette is **blocked**, so a test that
+ * was never wired for recording cannot reach the network by accident.
+ *
+ * ## Version constraints: there are none
+ *
+ * This used to carry two, both of which failed unreadably, and both of which
+ * were consequences of installing the recorder as Miniflare's `fetchMock`:
+ * the pool had to be `^0.18` (Miniflare 5 dropped the option, and pool 0.20
+ * removed it from its overrides), and your `undici` had to be byte-identical to
+ * Miniflare's (`fetchMock` was validated with `instanceof MockAgent`).
+ *
+ * The recorder is now a plain `outboundService` function — the hook `fetchMock`
+ * was sugar over in the first place. It is present and identical in Miniflare 4
+ * and 5, it type-checks against both, and it involves no `undici` at all. Core
+ * declares no `undici` peer and the pool peer is open.
+ */
+export { createVcr, recordFromEnv, closeVcr, type Vcr, type VcrOptions, type VcrRequest, type VcrRequestHeaders, type VcrOutboundService } from "./vcr.js";
+export { Cassette, requestKey, replayable, type CassetteEntry, type CassetteOptions, type RecordedRequest, type RecordedResponse, type ReplayableResponse } from "./vcr-store.js";
+export { VCR_CONTROL_ORIGIN, VCR_MARKER_HEADER, CASSETTE_NAME_RE, type VcrReleaseResult } from "./vcr-shared.js";

package/dist/testing/node.js

@@ -0,0 +1,56 @@
+/**
+ * `@dynamicagents/core/testing/node` — the **Node-realm** half of the VCR harness.
+ *
+ * Separate from `@dynamicagents/core/testing` because the two halves cannot share a
+ * module graph. This side reaches `node:fs`; the other side runs inside workerd,
+ * which has no filesystem. `vcr-shared.ts` is the only thing both may touch, and
+ * it is deliberately dependency-free so it can load in either realm.
+ *
+ * Import this from a Vitest **config** (or anything else running in Node), never
+ * from a spec:
+ *
+ * ```ts
+ * // vitest.config.ts
+ * import { defineConfig } from "vitest/config";
+ * import { cloudflareTest } from "@cloudflare/vitest-pool-workers";
+ * import path from "node:path";
+ * import { createVcr, recordFromEnv } from "@dynamicagents/core/testing/node";
+ *
+ * const vcr = createVcr({
+ *   snapshotsDir: path.resolve(import.meta.dirname, "test/snapshots"),
+ *   record: recordFromEnv(),
+ *   // Why a committed cassette is safe, and why playback needs no credentials.
+ *   excludeHeaders: ["x-api-key", "authorization", "cookie", "set-cookie"]
+ * });
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     cloudflareTest({
+ *       wrangler: { configPath: "./wrangler.jsonc" },
+ *       miniflare: { outboundService: vcr.outboundService }
+ *     })
+ *   ],
+ *   test: { globalSetup: ["@dynamicagents/core/testing/vcr-global-setup"] }
+ * });
+ * ```
+ *
+ * `RECORD=1` captures live traffic into every cassette a run activates; anything
+ * else replays. A host with no active cassette is **blocked**, so a test that
+ * was never wired for recording cannot reach the network by accident.
+ *
+ * ## Version constraints: there are none
+ *
+ * This used to carry two, both of which failed unreadably, and both of which
+ * were consequences of installing the recorder as Miniflare's `fetchMock`:
+ * the pool had to be `^0.18` (Miniflare 5 dropped the option, and pool 0.20
+ * removed it from its overrides), and your `undici` had to be byte-identical to
+ * Miniflare's (`fetchMock` was validated with `instanceof MockAgent`).
+ *
+ * The recorder is now a plain `outboundService` function — the hook `fetchMock`
+ * was sugar over in the first place. It is present and identical in Miniflare 4
+ * and 5, it type-checks against both, and it involves no `undici` at all. Core
+ * declares no `undici` peer and the pool peer is open.
+ */
+export { createVcr, recordFromEnv, closeVcr } from "./vcr.js";
+export { Cassette, requestKey, replayable } from "./vcr-store.js";
+export { VCR_CONTROL_ORIGIN, VCR_MARKER_HEADER, CASSETTE_NAME_RE } from "./vcr-shared.js";

package/dist/testing/vcr-global-setup.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Vitest `globalSetup`: the exported teardown runs after all tests but before
+ * Vite tears down its server, so it is the last point at which a cassette can
+ * still be written.
+ *
+ * Belt and braces rather than load-bearing — each cassette is already flushed
+ * when its test releases it, so a run that ends normally has nothing left to do
+ * here, and a run that dies mid-test keeps everything recorded up to that point.
+ * The recorder holds no sockets and no timers, so nothing here has to close.
+ */
+export declare function setup(): void;
+export declare function teardown(): Promise<void>;

package/dist/testing/vcr-global-setup.js

@@ -0,0 +1,15 @@
+import { closeVcr } from "./vcr.js";
+/**
+ * Vitest `globalSetup`: the exported teardown runs after all tests but before
+ * Vite tears down its server, so it is the last point at which a cassette can
+ * still be written.
+ *
+ * Belt and braces rather than load-bearing — each cassette is already flushed
+ * when its test releases it, so a run that ends normally has nothing left to do
+ * here, and a run that dies mid-test keeps everything recorded up to that point.
+ * The recorder holds no sockets and no timers, so nothing here has to close.
+ */
+export function setup() { }
+export async function teardown() {
+    await closeVcr();
+}

package/dist/testing/vcr-shared.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Constants shared between the two sides of the VCR harness that must NOT import
+ * each other: the Node-side recorder (`vcr.ts` / `vcr-store.ts`, which reach
+ * `node:fs`) and the worker-side spec helper (`vcr-spec.ts`, which runs in
+ * workerd). Keep this file dependency-free so both realms can load it.
+ */
+/**
+ * Reserved origin for the in-band control channel. A recorded spec `fetch`es
+ * here — through the same Miniflare `outboundService` every worker fetch already
+ * flows through — to tell the Node-side recorder which cassette is active for
+ * the current test. See `setupRecording` (vcr-spec.ts) and `createVcr` (vcr.ts).
+ * Never a real network host.
+ */
+export declare const VCR_CONTROL_ORIGIN = "https://vcr.internal";
+/**
+ * Stamped on every response the recorder produces.
+ *
+ * The point is to prove the recorder is *installed*. A Miniflare option that no
+ * longer exists is silently ignored rather than rejected — which is exactly how
+ * a harness still wired to `fetchMock` on pool 0.20 failed: nothing intercepted
+ * anything, every request escaped to the real network, and each one died as
+ * `internal error; reference = …` naming nothing. Checking for this header on
+ * the control response turns that whole class of failure into one named error
+ * before any test runs.
+ */
+export declare const VCR_MARKER_HEADER = "x-vcr";
+/** Body of a successful `POST /release`: what the recorder could not serve. */
+export interface VcrReleaseResult {
+    /** `"<METHOD> <url>"` for each blocked or unmatched request in the test. */
+    misses: string[];
+}
+/**
+ * Cassette filenames are derived from kebab-cased file + describe + test names
+ * (see `cassetteNameFor`), so they are always lowercase `a-z0-9-` plus the
+ * `.snapshot.json` suffix. Enforced on the control channel as a path-traversal
+ * guard (no `/`, no `..`) before the name is joined to the snapshots dir.
+ */
+export declare const CASSETTE_NAME_RE: RegExp;

package/dist/testing/vcr-shared.js

@@ -0,0 +1,33 @@
+/**
+ * Constants shared between the two sides of the VCR harness that must NOT import
+ * each other: the Node-side recorder (`vcr.ts` / `vcr-store.ts`, which reach
+ * `node:fs`) and the worker-side spec helper (`vcr-spec.ts`, which runs in
+ * workerd). Keep this file dependency-free so both realms can load it.
+ */
+/**
+ * Reserved origin for the in-band control channel. A recorded spec `fetch`es
+ * here — through the same Miniflare `outboundService` every worker fetch already
+ * flows through — to tell the Node-side recorder which cassette is active for
+ * the current test. See `setupRecording` (vcr-spec.ts) and `createVcr` (vcr.ts).
+ * Never a real network host.
+ */
+export const VCR_CONTROL_ORIGIN = "https://vcr.internal";
+/**
+ * Stamped on every response the recorder produces.
+ *
+ * The point is to prove the recorder is *installed*. A Miniflare option that no
+ * longer exists is silently ignored rather than rejected — which is exactly how
+ * a harness still wired to `fetchMock` on pool 0.20 failed: nothing intercepted
+ * anything, every request escaped to the real network, and each one died as
+ * `internal error; reference = …` naming nothing. Checking for this header on
+ * the control response turns that whole class of failure into one named error
+ * before any test runs.
+ */
+export const VCR_MARKER_HEADER = "x-vcr";
+/**
+ * Cassette filenames are derived from kebab-cased file + describe + test names
+ * (see `cassetteNameFor`), so they are always lowercase `a-z0-9-` plus the
+ * `.snapshot.json` suffix. Enforced on the control channel as a path-traversal
+ * guard (no `/`, no `..`) before the name is joined to the snapshots dir.
+ */
+export const CASSETTE_NAME_RE = /^[a-z0-9-]+\.snapshot\.json$/;

package/dist/testing/vcr-spec.d.ts

@@ -0,0 +1,25 @@
+import type { RunnerTestCase } from "vitest";
+/**
+ * Cassette filename for a test: `kebab(<project-relative path, minus
+ * .spec.ts>)` then each describe level then the test name, all kebab-cased and
+ * joined by `--`, plus `.snapshot.json`. Example:
+ * `test-arc-agi-recorded--arc-recorded-real-api--plays-a-real-game.snapshot.json`.
+ * Exported for debugging / the cassette-rename step.
+ */
+export declare function cassetteNameFor(task: RunnerTestCase): string;
+export interface SetupRecordingOptions {
+    /**
+     * Let a test finish even though the recorder could not serve one of its
+     * requests. Only for a spec that deliberately exercises a failing `fetch`;
+     * the default is to fail, because a silent miss reads as a broken assertion
+     * several frames from its cause.
+     */
+    allowMisses?: boolean;
+}
+/**
+ * Call once at the top of a recorded spec file (outside any `describe`). Adds
+ * per-test hooks that activate the test's cassette before it runs and release
+ * it after. A missing cassette **fails** the test with instructions to record
+ * (never skips — CI must go red so the gap is visible).
+ */
+export declare function setupRecording(options?: SetupRecordingOptions): void;

package/dist/testing/vcr-spec.js

@@ -0,0 +1,124 @@
+import { beforeEach, afterEach } from "vitest";
+import { VCR_CONTROL_ORIGIN, VCR_MARKER_HEADER } from "./vcr-shared.js";
+/**
+ * Worker-side half of the VCR harness. `setupRecording()` is the *only* thing a
+ * recorded spec wires up: one call at the top of the file gives every `it` its
+ * own cassette, auto-named from the file + describe + test names, recorded under
+ * `RECORD=1` and replayed otherwise. No per-recipe config, no registry.
+ *
+ * How it reaches the Node-side recorder: specs run in workerd (no filesystem),
+ * so the active cassette is announced over an in-band control channel — a
+ * `fetch` to {@link VCR_CONTROL_ORIGIN} that `createVcr` (vcr.ts) answers from
+ * the same Miniflare `outboundService` every worker fetch already flows through.
+ */
+const kebab = (s) => s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+/** The File task (root of the tree) carries `filepath`; describe suites don't. */
+function isFileTask(suite) {
+    return typeof suite.filepath === "string";
+}
+/**
+ * The spec's path relative to the project root.
+ *
+ * Vitest already computes this as `file.name`, which is the whole answer: it is
+ * stable across machines and checkouts, and it is *unique per spec file*, which
+ * is what a cassette name has to be.
+ *
+ * Deriving it from `filepath` instead — by stripping a leading `test/` or
+ * `src/` — got this wrong twice. Splitting on a segment that never matched
+ * returned the absolute path unchanged, so a cassette was named after the
+ * developer's home directory; and stripping *both* roots collapsed
+ * `test/api.spec.ts` and `src/api.spec.ts` onto one name, which for a store
+ * keyed solely by filename means one recording silently overwrites the other
+ * and playback serves the wrong responses.
+ *
+ * The fallback is only for a runner that does not populate `name`; a bare
+ * filename can still collide, but it is strictly better than an absolute path
+ * and nothing here reaches it.
+ */
+function relativeSpecPath(file) {
+    if (typeof file.name === "string" && file.name !== "")
+        return file.name;
+    return file.filepath.replace(/\\/g, "/").split("/").pop();
+}
+/**
+ * Cassette filename for a test: `kebab(<project-relative path, minus
+ * .spec.ts>)` then each describe level then the test name, all kebab-cased and
+ * joined by `--`, plus `.snapshot.json`. Example:
+ * `test-arc-agi-recorded--arc-recorded-real-api--plays-a-real-game.snapshot.json`.
+ * Exported for debugging / the cassette-rename step.
+ */
+export function cassetteNameFor(task) {
+    const rel = relativeSpecPath(task.file).replace(/\.spec\.ts$/, "");
+    const suites = [];
+    let suite = task.suite;
+    while (suite && !isFileTask(suite)) {
+        suites.unshift(suite.name);
+        suite = suite.suite;
+    }
+    return [rel, ...suites, task.name].map(kebab).join("--") + ".snapshot.json";
+}
+/**
+ * The recorder answers every control request with {@link VCR_MARKER_HEADER}, so
+ * its absence — or a `fetch` that rejects outright, which is what a request to
+ * a host that does not resolve does — means nothing is intercepting outbound
+ * traffic at all.
+ */
+const NOT_INSTALLED = `The VCR recorder is not installed, so ${VCR_CONTROL_ORIGIN} went to the ` +
+    `real network. Wire it into your vitest config:\n\n` +
+    `  const vcr = createVcr({ snapshotsDir, record: recordFromEnv() });\n` +
+    `  cloudflareTest({ miniflare: { outboundService: vcr.outboundService } })\n\n` +
+    `(\`fetchMock\` is not it: pool 0.20 removed the option, and an unknown key ` +
+    `in \`miniflare\` is ignored rather than rejected.)`;
+/**
+ * Call once at the top of a recorded spec file (outside any `describe`). Adds
+ * per-test hooks that activate the test's cassette before it runs and release
+ * it after. A missing cassette **fails** the test with instructions to record
+ * (never skips — CI must go red so the gap is visible).
+ */
+export function setupRecording(options = {}) {
+    beforeEach(async (ctx) => {
+        const cassette = cassetteNameFor(ctx.task);
+        const res = await fetch(`${VCR_CONTROL_ORIGIN}/use?cassette=${cassette}`, {
+            method: "POST"
+        }).catch(() => {
+            throw new Error(NOT_INSTALLED);
+        });
+        if (res.headers.get(VCR_MARKER_HEADER) === null) {
+            throw new Error(NOT_INSTALLED);
+        }
+        if (res.status === 404) {
+            throw new Error(`No VCR cassette "${cassette}". Record it with \`RECORD=1\` ` +
+                `(add \`-t "${ctx.task.name}"\` to record only this test), which needs ` +
+                `whatever real credentials the recorded API calls require.`);
+        }
+        if (res.status === 409) {
+            throw new Error(`VCR cassette "${cassette}" could not activate: another recorded test is ` +
+                `already using the shared recorder. Recorded specs must not run in ` +
+                `parallel — keep them sequential.`);
+        }
+        if (!res.ok) {
+            throw new Error(`VCR control channel error (HTTP ${res.status}) activating "${cassette}".`);
+        }
+    });
+    afterEach(async () => {
+        const res = await fetch(`${VCR_CONTROL_ORIGIN}/release`, {
+            method: "POST"
+        });
+        if (options.allowMisses === true || !res.ok)
+            return;
+        const { misses } = (await res.json());
+        if (misses.length === 0)
+            return;
+        // A miss cannot reject the Worker's own `fetch()` — Miniflare turns anything
+        // an outbound service throws into a 500 — so the request under test sees a
+        // 500 body and fails somewhere downstream, if at all. Reporting it here is
+        // what makes the *cause* the failure.
+        throw new Error(`VCR could not serve ${misses.length} request(s) in this test:\n` +
+            misses.map((m) => `  • ${m}`).join("\n") +
+            `\nRe-record with \`RECORD=1\`, or pass ` +
+            `\`setupRecording({ allowMisses: true })\` if the failure is the point.`);
+    });
+}

package/dist/testing/vcr-store.d.ts

@@ -0,0 +1,86 @@
+/** A stored request. `body` is utf-8 text; binary request bodies are not supported. */
+export interface RecordedRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string | string[]>;
+    body: string;
+}
+/** A stored response. `body` is base64, so a binary payload survives the file. */
+export interface RecordedResponse {
+    statusCode: number;
+    headers: Record<string, string | string[]>;
+    body: string;
+    trailers?: Record<string, string>;
+}
+/**
+ * One cassette entry: a request and every response recorded for it, in order.
+ *
+ * The array is what makes a replayed sequence work — two identical requests
+ * that returned different things (an ARC frame after a move, say) are one entry
+ * with two responses, walked in order. See {@link Cassette.match}.
+ */
+export interface CassetteEntry {
+    request: RecordedRequest;
+    responses: RecordedResponse[];
+}
+/** What {@link Cassette.match} hands back: everything needed to build a Response. */
+export interface ReplayableResponse {
+    status: number;
+    headers: [string, string][];
+    body: Uint8Array;
+}
+export interface CassetteOptions {
+    /** Request *and* response headers never written to the file (API keys, auth). */
+    excludeHeaders?: string[];
+}
+/** `${METHOD}\n${url}\n${sha256(body)}` — the whole matching rule. */
+export declare function requestKey(method: string, url: string, body: string): string;
+/**
+ * Turn a stored response into the pieces a `Response` is built from: body
+ * decoded from base64, headers flattened (a repeated header such as
+ * `set-cookie` becomes one entry per value) and {@link HOP_BY_HOP} dropped.
+ *
+ * Used on both paths, so a response served straight after recording is framed
+ * exactly as the same response will be on replay.
+ */
+export declare function replayable(response: RecordedResponse): ReplayableResponse;
+/**
+ * One cassette file, loaded lazily and written only when it has changed.
+ *
+ * Playback is **read-only**: nothing here mutates on a replay, which is what
+ * stops a plain `npm test` from dirtying committed cassettes. The sequence
+ * counter ({@link #calls}) is in memory and dies with the process, deliberately
+ * — `SnapshotAgent` persisted its equivalent and re-saved on close, so every
+ * run left every cassette modified in git.
+ */
+export declare class Cassette {
+    #private;
+    constructor(file: string, options?: CassetteOptions);
+    get file(): string;
+    /** Every request in the file, as `METHOD url`, for error messages. */
+    get recorded(): string[];
+    /**
+     * Read the file into memory, keying each entry by its own request rather than
+     * trusting anything stored alongside it.
+     *
+     * Two entries that key the same are a mistake rather than a merge: a request
+     * that was issued twice belongs in one entry with two `responses`, which is
+     * what {@link match} walks. Saying so here turns a hand-edit slip into a named
+     * error instead of a replay that silently serves the wrong response second.
+     */
+    load(): void;
+    /**
+     * The next recorded response for this request, or `null` if it was never
+     * recorded.
+     *
+     * Repeated identical requests walk `responses` in order and then **hold on
+     * the last one**, so a recording that captured a single response replays it
+     * for every call — which is what a poll loop needs when it runs a different
+     * number of times on replay than it did while recording.
+     */
+    match(method: string, url: string, body: string): ReplayableResponse | null;
+    /** Append a live response. Repeats of a request extend its `responses`. */
+    record(request: RecordedRequest, response: RecordedResponse): void;
+    /** Write if anything was recorded since the last flush. A no-op in playback. */
+    flush(): void;
+}