@b4run/testing 0.8.28

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Brian Love
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/cacheplane/b4run/main/docs/brand/b4-logo-horizontal-black-on-white.png" alt="B4.run" width="180" />
+</p>
+
+# @b4run/testing
+
+Supported harnesses, fixtures, matchers, deterministic embedders, and runtime helpers for testing B4.run applications.
+
+**Use this when:** You want to test B4.run agent behavior without making live model calls.
+
+## Install
+
+```bash
+pnpm add -D @b4run/testing vitest
+```
+
+## Example
+
+```ts
+import { createAgentHarness, expectFinalMessage, script } from "@b4run/testing"
+
+await using harness = await createAgentHarness({
+  appRoot: process.cwd(),
+  route: "/support#agent",
+})
+const result = await harness.run({
+  input: "Say hello",
+  fixtures: script().user("Say hello").replies("Hello!"),
+})
+
+expectFinalMessage(result).toContain("Hello")
+```
+
+## Runtime and stability
+
+`@b4run/testing` is a supported node-only testing surface. `createAgentHarness()` temporarily changes process-wide model environment variables and runtime caches; await `close()` and do not run concurrent harnesses in one process. Fixture replay is deterministic and CI-safe; live recording requires model credentials.
+
+## Related
+
+- [Testing API reference](https://b4.run/docs/api/testing) — exact harness and lifecycle contracts.
+- [Agent Test Harness](https://b4.run/docs/testing-agents) — end-to-end agent testing.
+- [Fixtures and Recording](https://b4.run/docs/testing-agents/fixtures) — deterministic replay and optional live recording.
+- [`@b4run/evals`](https://www.npmjs.com/package/@b4run/evals) — repeatable datasets, scorers, and release gates.
+
+## Maturity and support
+
+B4.run is pre-1.0, and its public surface can change. All publishable B4.run packages release together as a fixed group; review the [`@b4run/testing` changelog](https://github.com/cacheplane/b4run/blob/main/packages/testing/CHANGELOG.md) and [upgrading guide](https://b4.run/docs/upgrading) before upgrading. For support, use [GitHub Discussions](https://github.com/cacheplane/b4run/discussions); report defects in [GitHub Issues](https://github.com/cacheplane/b4run/issues).
+
+## License
+
+MIT. See the [repository license](https://github.com/cacheplane/b4run/blob/main/LICENSE).

package/dist/aimock-runner.d.ts

@@ -0,0 +1,48 @@
+import type { AimockFixture } from "./fixture-builder.js";
+import type { Recording } from "./record-fixtures.js";
+export interface Aimock {
+    readonly port: number;
+    /** Base URL with the `/v1` suffix the OpenAI SDK expects. */
+    readonly baseUrl: string;
+    /** Append more fixtures onto the live mock without restarting it. */
+    addFixtures(fixtures: readonly AimockFixture[]): void;
+    /** Remove all registered fixtures (the mock keeps running). */
+    clearFixtures(): void;
+    /** All requests the mock has received (aimock's journal). */
+    getRequests(): ReadonlyArray<{
+        body: {
+            messages?: Array<{
+                role: string;
+                content: unknown;
+            }>;
+            tools?: Array<{
+                type?: string;
+                function?: {
+                    name?: string;
+                };
+            }>;
+        } | null;
+    }>;
+    /** Current count of registered fixtures (snapshot point for getRecordingsSince). */
+    getFixtureCount(): number;
+    /**
+     * Recordings captured since the given journal length and fixture count — pairs
+     * proxied journal entries (request) with newly-recorded fixtures (response),
+     * both windowed to a single run so multi-run reuse can't cross-align.
+     */
+    getRecordingsSince(journalStart: number, fixtureStart: number): readonly Recording[];
+    /** Ordered recordings (request + baked response) for proxied calls captured in record mode. */
+    getRecordings(): readonly Recording[];
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export declare function createAimock(opts: {
+    readonly fixtures: readonly AimockFixture[];
+    /** When set, proxy unmatched requests to the given upstream providers. */
+    readonly proxy?: {
+        openai: string;
+    };
+    /** With proxy: capture (record) proxied responses so getRecordings() returns them. */
+    readonly record?: boolean;
+}): Promise<Aimock>;
+//# sourceMappingURL=aimock-runner.d.ts.map

package/dist/aimock-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aimock-runner.d.ts","sourceRoot":"","sources":["../src/aimock-runner.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,sBAAsB,CAAA;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAErD,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,qEAAqE;IACrE,WAAW,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,GAAG,IAAI,CAAA;IACrD,+DAA+D;IAC/D,aAAa,IAAI,IAAI,CAAA;IACrB,6DAA6D;IAC7D,WAAW,IAAI,aAAa,CAAC;QAC3B,IAAI,EAAE;YACJ,QAAQ,CAAC,EAAE,KAAK,CAAC;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,OAAO,EAAE,OAAO,CAAA;aAAE,CAAC,CAAA;YACpD,KAAK,CAAC,EAAE,KAAK,CAAC;gBAAE,IAAI,CAAC,EAAE,MAAM,CAAC;gBAAC,QAAQ,CAAC,EAAE;oBAAE,IAAI,CAAC,EAAE,MAAM,CAAA;iBAAE,CAAA;aAAE,CAAC,CAAA;SAC/D,GAAG,IAAI,CAAA;KACT,CAAC,CAAA;IACF,oFAAoF;IACpF,eAAe,IAAI,MAAM,CAAA;IACzB;;;;OAIG;IACH,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS,SAAS,EAAE,CAAA;IACpF,+FAA+F;IAC/F,aAAa,IAAI,SAAS,SAAS,EAAE,CAAA;IACrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvC;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAA;IAC3C,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IACnC,sFAAsF;IACtF,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CA8FlB"}

package/dist/aimock-runner.js

@@ -0,0 +1,81 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { LLMock } from "@copilotkit/aimock";
+export async function createAimock(opts) {
+    // When recording, use a private temp dir so aimock writes fixtures there
+    // instead of ./fixtures/recorded in the caller's CWD.
+    const recordTmpDir = opts.proxy && opts.record === true
+        ? fs.mkdtempSync(path.join(os.tmpdir(), "b4-runmock-record-"))
+        : null;
+    const mock = new LLMock(opts.proxy
+        ? {
+            port: 0,
+            chunkSize: 4096,
+            record: {
+                providers: { openai: opts.proxy.openai },
+                proxyOnly: opts.record !== true,
+                ...(recordTmpDir !== null ? { fixturePath: recordTmpDir } : {}),
+            },
+        }
+        : { port: 0, chunkSize: 4096 });
+    if (opts.fixtures.length > 0) {
+        mock.addFixturesFromJSON(opts.fixtures);
+    }
+    await mock.start();
+    // Capture the fixture count at start so getRecordings() can diff against it.
+    const initialFixtureCount = mock.getFixtures().length;
+    // Local helper — windowed to [journalStart, fixtureStart) so multi-run reuse
+    // can't cross-align recorded responses with the wrong requests.
+    const getRecordingsSince = (journalStart, fixtureStart) => {
+        const newFixtures = mock.getFixtures().slice(fixtureStart);
+        if (newFixtures.length === 0)
+            return [];
+        const proxyEntries = mock.getRequests()
+            .slice(journalStart)
+            .filter((e) => e.response?.source === "proxy");
+        return newFixtures.map((fixture, i) => {
+            const messages = proxyEntries[i]?.body?.messages;
+            const response = fixture.response;
+            return { request: messages !== undefined ? { messages } : {}, response };
+        });
+    };
+    let stopped = false;
+    const handle = {
+        port: mock.port,
+        baseUrl: `${mock.url}/v1`,
+        addFixtures(fixtures) {
+            if (fixtures.length > 0) {
+                mock.addFixturesFromJSON(fixtures);
+            }
+        },
+        clearFixtures() {
+            mock.clearFixtures();
+        },
+        getRequests() {
+            return mock.getRequests();
+        },
+        getFixtureCount() {
+            return mock.getFixtures().length;
+        },
+        getRecordingsSince(journalStart, fixtureStart) {
+            return getRecordingsSince(journalStart, fixtureStart);
+        },
+        getRecordings() {
+            return getRecordingsSince(0, initialFixtureCount);
+        },
+        async close() {
+            if (stopped)
+                return;
+            stopped = true;
+            await mock.stop();
+            if (recordTmpDir !== null) {
+                fs.rmSync(recordTmpDir, { recursive: true, force: true });
+            }
+        },
+        [Symbol.asyncDispose]() {
+            return this.close();
+        },
+    };
+    return handle;
+}

package/dist/checkpointer-conformance.d.ts

@@ -0,0 +1,43 @@
+import type { BaseCheckpointSaver } from "@langchain/langgraph-checkpoint";
+/**
+ * The contract every checkpointer must satisfy. Run against B4.run's SQLite saver
+ * (in-process, always) and any other backend (e.g. Postgres, gated) so they
+ * cannot drift. Pass vitest's `describe`; `makeSaver` returns a FRESH empty
+ * saver per call.
+ *
+ * Asserted through the PUBLIC saver API only — never the tables. The backends
+ * genuinely differ underneath (SQLite stores the whole Checkpoint as one BLOB;
+ * another saver may split payloads across columns or externalize channel values
+ * keyed by version), and none of that is contract.
+ *
+ * Two behaviors are CAPABILITY FLAGS rather than assertions, because SQLite
+ * deliberately does less than a backend legitimately can:
+ *   - `listPendingWrites` — SQLite's `list()` yields lightweight tuples with
+ *     `pendingWrites: []` and expects callers needing writes to re-fetch via
+ *     `getTuple`.
+ *   - `listFilter` — SQLite ignores `options.filter` entirely.
+ * Asserting SQLite's shortcuts as contract would fail a richer backend for
+ * being better, so each backend declares what it actually promises instead.
+ *
+ * The two hostile round-trips (a NUL byte and a lone surrogate, in metadata AND
+ * in a channel name and value) are not edge-case trivia: they are exactly where
+ * a jsonb-backed store diverges from the BLOB-backed incumbent, and B4.run
+ * produces such payloads for real — sandbox stdout flows unmodified into tool
+ * results and from there into checkpoint metadata. They are deliberately NOT
+ * asserted for a pending write's channel column, which is plain text in every
+ * backend (SQLite transcodes a lone surrogate there to U+FFFD) and is fed by
+ * the graph definition rather than by model or tool output.
+ */
+export declare function runCheckpointerConformance(opts: {
+    readonly name: string;
+    readonly makeSaver: () => Promise<BaseCheckpointSaver> | BaseCheckpointSaver;
+    readonly describe: (name: string, fn: () => void) => void;
+    readonly close?: (saver: BaseCheckpointSaver) => Promise<void> | void;
+    readonly supports?: {
+        /** `list()` hydrates `pendingWrites` (SQLite: no). */
+        readonly listPendingWrites?: boolean;
+        /** `list({ filter })` narrows by metadata (SQLite: no). */
+        readonly listFilter?: boolean;
+    };
+}): void;
+//# sourceMappingURL=checkpointer-conformance.d.ts.map

package/dist/checkpointer-conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpointer-conformance.d.ts","sourceRoot":"","sources":["../src/checkpointer-conformance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EAKpB,MAAM,iCAAiC,CAAA;AAgExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAAA;IAC5E,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAA;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,sDAAsD;QACtD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;QACpC,2DAA2D;QAC3D,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;KAC9B,CAAA;CACF,GAAG,IAAI,CAqTP"}

package/dist/checkpointer-conformance.js

@@ -0,0 +1,381 @@
+import { expect, test } from "vitest";
+/** A payload SQLite's BLOB round-trips but a jsonb column rejects (SQLSTATE 22P05). */
+const NUL = "before\u0000after";
+/** Unpaired high surrogate — rejected by jsonb columns (SQLSTATE 22P02). */
+const LONE_SURROGATE = "lone\ud800end";
+/**
+ * A checkpoint plus the `newVersions` LangGraph would pass alongside it.
+ *
+ * `newVersions` is REALISTIC (one entry per written channel) on purpose: a
+ * backend that externalizes `channel_values` keyed by version silently drops
+ * them when `newVersions` is empty, so an empty map would let that divergence
+ * pass unnoticed.
+ */
+function mk(id, channelValues, version = 2) {
+    const channelVersions = {};
+    for (const key of Object.keys(channelValues))
+        channelVersions[key] = version;
+    return {
+        checkpoint: {
+            v: 4,
+            id,
+            ts: "2026-08-07T00:00:00.000Z",
+            channel_values: channelValues,
+            channel_versions: channelVersions,
+            versions_seen: { agent: { ...channelVersions } },
+        },
+        newVersions: { ...channelVersions },
+    };
+}
+const meta = (over = {}) => ({
+    source: over.source ?? "loop",
+    step: over.step ?? 1,
+    parents: {},
+});
+const cfg = (threadId, ns = "", checkpointId) => ({
+    configurable: {
+        thread_id: threadId,
+        checkpoint_ns: ns,
+        ...(checkpointId === undefined ? {} : { checkpoint_id: checkpointId }),
+    },
+});
+async function collect(gen) {
+    const out = [];
+    for await (const tuple of gen)
+        out.push(tuple);
+    return out;
+}
+const noteOf = (metadata) => metadata?.note;
+/**
+ * The contract every checkpointer must satisfy. Run against B4.run's SQLite saver
+ * (in-process, always) and any other backend (e.g. Postgres, gated) so they
+ * cannot drift. Pass vitest's `describe`; `makeSaver` returns a FRESH empty
+ * saver per call.
+ *
+ * Asserted through the PUBLIC saver API only — never the tables. The backends
+ * genuinely differ underneath (SQLite stores the whole Checkpoint as one BLOB;
+ * another saver may split payloads across columns or externalize channel values
+ * keyed by version), and none of that is contract.
+ *
+ * Two behaviors are CAPABILITY FLAGS rather than assertions, because SQLite
+ * deliberately does less than a backend legitimately can:
+ *   - `listPendingWrites` — SQLite's `list()` yields lightweight tuples with
+ *     `pendingWrites: []` and expects callers needing writes to re-fetch via
+ *     `getTuple`.
+ *   - `listFilter` — SQLite ignores `options.filter` entirely.
+ * Asserting SQLite's shortcuts as contract would fail a richer backend for
+ * being better, so each backend declares what it actually promises instead.
+ *
+ * The two hostile round-trips (a NUL byte and a lone surrogate, in metadata AND
+ * in a channel name and value) are not edge-case trivia: they are exactly where
+ * a jsonb-backed store diverges from the BLOB-backed incumbent, and B4.run
+ * produces such payloads for real — sandbox stdout flows unmodified into tool
+ * results and from there into checkpoint metadata. They are deliberately NOT
+ * asserted for a pending write's channel column, which is plain text in every
+ * backend (SQLite transcodes a lone surrogate there to U+FFFD) and is fed by
+ * the graph definition rather than by model or tool output.
+ */
+export function runCheckpointerConformance(opts) {
+    const { name, makeSaver, describe, close, supports } = opts;
+    describe(`Checkpointer conformance: ${name}`, () => {
+        test("put + getTuple round-trips the checkpoint, channel values and metadata", async () => {
+            const s = await makeSaver();
+            try {
+                const { checkpoint, newVersions } = mk("ckpt-1", { messages: ["hi"], count: 3 });
+                const metadata = meta({ step: 7 });
+                const returned = await s.put(cfg("t1"), checkpoint, metadata, newVersions);
+                expect(returned.configurable?.thread_id).toBe("t1");
+                expect(returned.configurable?.checkpoint_ns).toBe("");
+                expect(returned.configurable?.checkpoint_id).toBe("ckpt-1");
+                const tuple = await s.getTuple(cfg("t1", "", "ckpt-1"));
+                expect(tuple?.checkpoint.id).toBe("ckpt-1");
+                expect(tuple?.checkpoint.ts).toBe(checkpoint.ts);
+                expect(tuple?.checkpoint.channel_values).toEqual({ messages: ["hi"], count: 3 });
+                expect(tuple?.checkpoint.channel_versions).toEqual(checkpoint.channel_versions);
+                expect(tuple?.checkpoint.versions_seen).toEqual(checkpoint.versions_seen);
+                expect(tuple?.metadata).toEqual(metadata);
+                expect(tuple?.config.configurable?.thread_id).toBe("t1");
+                expect(tuple?.config.configurable?.checkpoint_ns).toBe("");
+                expect(tuple?.config.configurable?.checkpoint_id).toBe("ckpt-1");
+            }
+            finally {
+                await close?.(s);
+            }
+        });
+        test("getTuple without a checkpoint_id returns the newest checkpoint", async () => {
+            const s = await makeSaver();
+            try {
+                const a = mk("ckpt-a", { messages: ["a"] });
+                const b = mk("ckpt-b", { messages: ["b"] });
+                await s.put(cfg("t1"), a.checkpoint, meta({ step: 0 }), a.newVersions);
+                await s.put(cfg("t1"), b.checkpoint, meta({ step: 1 }), b.newVersions);
+                expect((await s.getTuple(cfg("t1")))?.checkpoint.id).toBe("ckpt-b");
+            }
+            finally {
+                await close?.(s);
+            }
+        });
+        test("getTuple returns undefined for an unknown thread or checkpoint", async () => {
+            const s = await makeSaver();
+            try {
+                expect(await s.getTuple(cfg("t-missing"))).toBeUndefined();
+                const a = mk("ckpt-a", { messages: ["a"] });
+                await s.put(cfg("t1"), a.checkpoint, meta(), a.newVersions);
+                expect(await s.getTuple(cfg("t1", "", "ckpt-nope"))).toBeUndefined();
+            }
+            finally {
+                await close?.(s);
+            }
+        });
+        test("put replaces a checkpoint written under the same id", async () => {
+            const s = await makeSaver();
+            try {
+                const first = mk("ckpt-1", { messages: ["v1"] });
+                const second = mk("ckpt-1", { messages: ["v2"] }, 3);
+                await s.put(cfg("t1"), first.checkpoint, meta({ step: 1 }), first.newVersions);
+                await s.put(cfg("t1"), second.checkpoint, meta({ step: 2 }), second.newVersions);
+                const tuple = await s.getTuple(cfg("t1", "", "ckpt-1"));
+                expect(tuple?.checkpoint.channel_values).toEqual({ messages: ["v2"] });
+                expect(tuple?.metadata?.step).toBe(2);
+                expect(await collect(s.list(cfg("t1")))).toHaveLength(1);
+            }
+            finally {
+                await close?.(s);
+            }
+        });
+        test("the parent chain is recorded: root has none, children point back", async () => {
+            const s = await makeSaver();
+            try {
+                const root = mk("ckpt-1", { messages: ["a"] });
+                const rootConfig = await s.put(cfg("t1"), root.checkpoint, meta({ step: 0 }), root.newVersions);
+                const child = mk("ckpt-2", { messages: ["a", "b"] }, 3);
+                await s.put(rootConfig, child.checkpoint, meta({ step: 1 }), child.newVersions);
+                expect((await s.getTuple(cfg("t1", "", "ckpt-1")))?.parentConfig).toBeUndefined();
+                const childTuple = await s.getTuple(cfg("t1", "", "ckpt-2"));
+                expect(childTuple?.parentConfig?.configurable?.thread_id).toBe("t1");
+                expect(childTuple?.parentConfig?.configurable?.checkpoint_ns).toBe("");
+                expect(childTuple?.parentConfig?.configurable?.checkpoint_id).toBe("ckpt-1");
+            }
+            finally {
+                await close?.(s);
+            }
+        });
+        test("putWrites is visible in getTuple().pendingWrites, in call order", async () => {
+            const s = await makeSaver();
+            try {
+                const a = mk("ckpt-1", { messages: ["a"] });
+                const config = await s.put(cfg("t1"), a.checkpoint, meta(), a.newVersions);
+                await s.putWrites(config, [
+                    ["messages", { role: "ai", text: "one" }],
+                    ["counter", 2],
+                ], "task-1");
+                expect((await s.getTuple(cfg("t1", "", "ckpt-1")))?.pendingWrites).toEqual([
+                    ["task-1", "messages", { role: "ai", text: "one" }],
+                    ["task-1", "counter", 2],
+                ]);
+            }
+            finally {
+                await close?.(s);
+            }
+        });
+        test("putWrites is idempotent on (task_id, idx)", async () => {
+            const s = await makeSaver();
+            try {
+                const a = mk("ckpt-1", { messages: ["a"] });
+                const config = await s.put(cfg("t1"), a.checkpoint, meta(), a.newVersions);
+                await s.putWrites(config, [["messages", "a"]], "task-1");
+                await s.putWrites(config, [["messages", "a"]], "task-1");
+                expect((await s.getTuple(cfg("t1", "", "ckpt-1")))?.pendingWrites).toEqual([
+                    ["task-1", "messages", "a"],
+                ]);
+            }
+            finally {
+                await close?.(s);
+            }
+        });
+        test("writes are scoped to their own checkpoint", async () => {
+            const s = await makeSaver();
+            try {
+                const a = mk("ckpt-1", { messages: ["a"] });
+                const b = mk("ckpt-2", { messages: ["b"] }, 3);
+                const configA = await s.put(cfg("t1"), a.checkpoint, meta({ step: 0 }), a.newVersions);
+                await s.put(configA, b.checkpoint, meta({ step: 1 }), b.newVersions);
+                await s.putWrites(configA, [["messages", "only-for-1"]], "task-1");
+                expect((await s.getTuple(cfg("t1", "", "ckpt-2")))?.pendingWrites).toEqual([]);
+            }
+            finally {
+                await close?.(s);
+            }
+        });
+        test("list yields checkpoints newest-first", async () => {
+            const s = await makeSaver();
+            try {
+                for (const id of ["ckpt-a", "ckpt-b", "ckpt-c"]) {
+                    const c = mk(id, { messages: [id] });
+                    await s.put(cfg("t1"), c.checkpoint, meta(), c.newVersions);
+                }
+                expect((await collect(s.list(cfg("t1")))).map((t) => t.checkpoint.id)).toEqual([
+                    "ckpt-c",
+                    "ckpt-b",
+                    "ckpt-a",
+                ]);
+            }
+            finally {
+                await close?.(s);
+            }
+        });
+        test("list honors limit", async () => {
+            const s = await makeSaver();
+            try {
+                for (const id of ["ckpt-a", "ckpt-b", "ckpt-c"]) {
+                    const c = mk(id, { messages: [id] });
+                    await s.put(cfg("t1"), c.checkpoint, meta(), c.newVersions);
+                }
+                expect((await collect(s.list(cfg("t1"), { limit: 2 }))).map((t) => t.checkpoint.id)).toEqual(["ckpt-c", "ckpt-b"]);
+            }
+            finally {
+                await close?.(s);
+            }
+        });
+        test("list honors before, exclusively", async () => {
+            const s = await makeSaver();
+            try {
+                for (const id of ["ckpt-a", "ckpt-b", "ckpt-c"]) {
+                    const c = mk(id, { messages: [id] });
+                    await s.put(cfg("t1"), c.checkpoint, meta(), c.newVersions);
+                }
+                const tuples = await collect(s.list(cfg("t1"), { before: cfg("t1", "", "ckpt-c") }));
+                expect(tuples.map((t) => t.checkpoint.id)).toEqual(["ckpt-b", "ckpt-a"]);
+            }
+            finally {
+                await close?.(s);
+            }
+        });
+        test("list on an unknown thread yields nothing", async () => {
+            const s = await makeSaver();
+            try {
+                expect(await collect(s.list(cfg("t-missing")))).toEqual([]);
+            }
+            finally {
+                await close?.(s);
+            }
+        });
+        test("checkpoint_ns isolates checkpoints, writes and listing", async () => {
+            const s = await makeSaver();
+            try {
+                const root = mk("ckpt-1", { messages: ["root"] });
+                const sub = mk("ckpt-1", { messages: ["sub"] });
+                const rootConfig = await s.put(cfg("t1"), root.checkpoint, meta(), root.newVersions);
+                await s.put(cfg("t1", "child"), sub.checkpoint, meta(), sub.newVersions);
+                await s.putWrites(rootConfig, [["messages", "root-write"]], "task-1");
+                expect((await s.getTuple(cfg("t1", "", "ckpt-1")))?.checkpoint.channel_values).toEqual({
+                    messages: ["root"],
+                });
+                const subTuple = await s.getTuple(cfg("t1", "child", "ckpt-1"));
+                expect(subTuple?.checkpoint.channel_values).toEqual({ messages: ["sub"] });
+                expect(subTuple?.config.configurable?.checkpoint_ns).toBe("child");
+                expect(subTuple?.pendingWrites).toEqual([]);
+                expect(await collect(s.list(cfg("t1", "child")))).toHaveLength(1);
+            }
+            finally {
+                await close?.(s);
+            }
+        });
+        test("deleteThread removes that thread's checkpoints and writes, leaving others", async () => {
+            const s = await makeSaver();
+            try {
+                const doomed = mk("ckpt-1", { messages: ["doomed"] });
+                const keeper = mk("ckpt-1", { messages: ["keeper"] });
+                const doomedConfig = await s.put(cfg("t1"), doomed.checkpoint, meta(), doomed.newVersions);
+                const keeperConfig = await s.put(cfg("t2"), keeper.checkpoint, meta(), keeper.newVersions);
+                await s.putWrites(doomedConfig, [["messages", "gone"]], "task-1");
+                await s.putWrites(keeperConfig, [["messages", "kept"]], "task-1");
+                await s.put(cfg("t1", "child"), doomed.checkpoint, meta(), doomed.newVersions);
+                await s.deleteThread("t1");
+                expect(await s.getTuple(cfg("t1", "", "ckpt-1"))).toBeUndefined();
+                expect(await s.getTuple(cfg("t1", "child", "ckpt-1"))).toBeUndefined();
+                expect(await collect(s.list(cfg("t1")))).toEqual([]);
+                const kept = await s.getTuple(cfg("t2", "", "ckpt-1"));
+                expect(kept?.checkpoint.channel_values).toEqual({ messages: ["keeper"] });
+                expect(kept?.pendingWrites).toEqual([["task-1", "messages", "kept"]]);
+                // Re-putting the same id proves the old writes really went away rather
+                // than lingering to re-attach.
+                await s.put(cfg("t1"), doomed.checkpoint, meta(), doomed.newVersions);
+                expect((await s.getTuple(cfg("t1", "", "ckpt-1")))?.pendingWrites).toEqual([]);
+            }
+            finally {
+                await close?.(s);
+            }
+        });
+        test("round-trips a NUL byte in metadata, a channel name and a channel value", async () => {
+            const s = await makeSaver();
+            try {
+                // Hostile bytes go everywhere the payload travels: a channel NAME and a
+                // channel VALUE inside the serialized checkpoint (which also carries
+                // them into channel_versions and versions_seen), an extra metadata
+                // field, and a pending-write value. NOT into the write's channel
+                // column: that is a plain text column in every backend, and channel
+                // names come from the graph definition, never from model or tool output.
+                const { checkpoint, newVersions } = mk("ckpt-1", { [NUL]: NUL, messages: [NUL] });
+                const metadata = { ...meta(), note: NUL };
+                const config = await s.put(cfg("t1"), checkpoint, metadata, newVersions);
+                await s.putWrites(config, [["messages", NUL]], "task-1");
+                const tuple = await s.getTuple(cfg("t1", "", "ckpt-1"));
+                expect(tuple?.checkpoint.channel_values).toEqual({ [NUL]: NUL, messages: [NUL] });
+                expect(tuple?.checkpoint.channel_versions).toEqual(checkpoint.channel_versions);
+                expect(tuple?.checkpoint.versions_seen).toEqual(checkpoint.versions_seen);
+                expect(noteOf(tuple?.metadata)).toBe(NUL);
+                expect(tuple?.pendingWrites).toEqual([["task-1", "messages", NUL]]);
+            }
+            finally {
+                await close?.(s);
+            }
+        });
+        test("round-trips a lone surrogate in metadata, a channel name and a channel value", async () => {
+            const s = await makeSaver();
+            try {
+                const values = { [LONE_SURROGATE]: LONE_SURROGATE, messages: [LONE_SURROGATE] };
+                const { checkpoint, newVersions } = mk("ckpt-1", values);
+                const metadata = { ...meta(), note: LONE_SURROGATE };
+                const config = await s.put(cfg("t1"), checkpoint, metadata, newVersions);
+                await s.putWrites(config, [["messages", LONE_SURROGATE]], "task-1");
+                const tuple = await s.getTuple(cfg("t1", "", "ckpt-1"));
+                expect(tuple?.checkpoint.channel_values).toEqual(values);
+                expect(tuple?.checkpoint.channel_versions).toEqual(checkpoint.channel_versions);
+                expect(tuple?.checkpoint.versions_seen).toEqual(checkpoint.versions_seen);
+                expect(noteOf(tuple?.metadata)).toBe(LONE_SURROGATE);
+                expect(tuple?.pendingWrites).toEqual([["task-1", "messages", LONE_SURROGATE]]);
+            }
+            finally {
+                await close?.(s);
+            }
+        });
+        test.skipIf(supports?.listPendingWrites !== true)("list hydrates pendingWrites (declared capability)", async () => {
+            const s = await makeSaver();
+            try {
+                const a = mk("ckpt-1", { messages: ["a"] });
+                const config = await s.put(cfg("t1"), a.checkpoint, meta(), a.newVersions);
+                await s.putWrites(config, [["messages", "w"]], "task-1");
+                const [tuple] = await collect(s.list(cfg("t1")));
+                expect(tuple?.pendingWrites).toEqual([["task-1", "messages", "w"]]);
+            }
+            finally {
+                await close?.(s);
+            }
+        });
+        test.skipIf(supports?.listFilter !== true)("list narrows by metadata filter (declared capability)", async () => {
+            const s = await makeSaver();
+            try {
+                const a = mk("ckpt-a", { messages: ["a"] });
+                const b = mk("ckpt-b", { messages: ["b"] });
+                await s.put(cfg("t1"), a.checkpoint, meta({ source: "input", step: 0 }), a.newVersions);
+                await s.put(cfg("t1"), b.checkpoint, meta({ source: "loop", step: 1 }), b.newVersions);
+                const tuples = await collect(s.list(cfg("t1"), { filter: { source: "loop" } }));
+                expect(tuples.map((t) => t.checkpoint.id)).toEqual(["ckpt-b"]);
+            }
+            finally {
+                await close?.(s);
+            }
+        });
+    });
+}

package/dist/fake-embedder.d.ts

@@ -0,0 +1,9 @@
+import type { Embedder } from "@b4run/core";
+/**
+ * Deterministic, network-free embedder for tests: a normalized bag-of-token-hash
+ * vector, so strings sharing tokens are nearer in cosine. NOT for production.
+ */
+export declare function fakeEmbedder(opts?: {
+    readonly dims?: number;
+}): Embedder;
+//# sourceMappingURL=fake-embedder.d.ts.map

package/dist/fake-embedder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-embedder.d.ts","sourceRoot":"","sources":["../src/fake-embedder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAW3C;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,QAAQ,CAuBxE"}