@tanstack/ai-sandbox 0.3.4 → 0.4.0

package/dist/esm/testkit/checkpoint-fork-conformance.js

@@ -0,0 +1,191 @@
+import { InMemorySandboxCheckpointStore } from "../checkpoint-store.js";
+import { describe, expect, it } from "vitest";
+//#region src/testkit/checkpoint-fork-conformance.ts
+function sourceCheckpoint() {
+	return {
+		id: "source-root",
+		threadId: "source",
+		parentCheckpointId: null,
+		createdAt: 10,
+		reason: "named",
+		label: "source label",
+		sourceRunId: "run-1",
+		files: [{
+			path: "a.txt",
+			kind: "file",
+			blobKey: `sandbox-files/sha256/${"a".repeat(64)}`,
+			size: 1
+		}],
+		conversation: [{
+			role: "user",
+			content: "checkpoint conversation"
+		}],
+		artifacts: []
+	};
+}
+async function appendSource(checkpoints) {
+	const sourceWriter = await checkpoints.acquireWriter("source");
+	const source = sourceCheckpoint();
+	await checkpoints.append({
+		checkpoint: source,
+		expectedHeadId: null,
+		writer: sourceWriter
+	});
+	return {
+		source,
+		sourceWriter
+	};
+}
+function forkInput(writer, overrides = {}) {
+	return {
+		sourceThreadId: "source",
+		sourceCheckpointId: "source-root",
+		destinationThreadId: "destination",
+		destinationCheckpointId: "fork-root",
+		createdAt: 20,
+		writer,
+		...overrides
+	};
+}
+async function destinationState(persistence, checkpoints) {
+	return {
+		transcript: await persistence.stores.messages.loadThread("destination"),
+		head: await checkpoints.getHead("destination"),
+		checkpoints: await checkpoints.list("destination"),
+		references: await checkpoints.listBlobReferences()
+	};
+}
+async function expectRejectedWithoutDestinationChanges(persistence, checkpoints, operation, code) {
+	const before = await destinationState(persistence, checkpoints);
+	await expect(operation).rejects.toMatchObject({ code });
+	expect(await destinationState(persistence, checkpoints)).toEqual(before);
+}
+function runSandboxCheckpointForkConformance(name, makeSnapshots) {
+	describe(`Sandbox checkpoint fork conformance: ${name}`, () => {
+		it("copies a selected historical checkpoint and creates an exact fork root", async () => {
+			const { persistence, checkpoints } = await makeSnapshots();
+			const { source, sourceWriter } = await appendSource(checkpoints);
+			await checkpoints.append({
+				checkpoint: {
+					id: "source-head",
+					threadId: "source",
+					parentCheckpointId: source.id,
+					createdAt: 11,
+					reason: "automatic",
+					files: [],
+					conversation: [{
+						role: "user",
+						content: "newer conversation"
+					}],
+					artifacts: []
+				},
+				expectedHeadId: source.id,
+				writer: sourceWriter
+			});
+			await persistence.stores.messages.saveThread("source", [{
+				role: "user",
+				content: "current source message"
+			}]);
+			const destinationWriter = await checkpoints.acquireWriter("destination");
+			const result = await checkpoints.forkFromCheckpoint(forkInput(destinationWriter));
+			expect(result.checkpoint).toEqual({
+				id: "fork-root",
+				threadId: "destination",
+				parentCheckpointId: null,
+				createdAt: 20,
+				reason: "fork-root",
+				files: source.files,
+				conversation: source.conversation,
+				artifacts: []
+			});
+			expect(await persistence.stores.messages.loadThread("destination")).toEqual(source.conversation);
+			expect(await checkpoints.getHead("source")).toBe("source-head");
+		});
+		it("rejects a plain checkpoint store because it has no fork capability", () => {
+			const store = new InMemorySandboxCheckpointStore();
+			expect("forkFromCheckpoint" in store).toBe(false);
+		});
+		it("rejects a missing source without changing the destination", async () => {
+			const { persistence, checkpoints } = await makeSnapshots();
+			const writer = await checkpoints.acquireWriter("destination");
+			await expectRejectedWithoutDestinationChanges(persistence, checkpoints, checkpoints.forkFromCheckpoint(forkInput(writer, { sourceCheckpointId: "missing" })), "SANDBOX_SNAPSHOT_FORK_SOURCE_NOT_FOUND");
+		});
+		it("rejects a source thread mismatch without changing the destination", async () => {
+			const { persistence, checkpoints } = await makeSnapshots();
+			await appendSource(checkpoints);
+			const writer = await checkpoints.acquireWriter("destination");
+			await expectRejectedWithoutDestinationChanges(persistence, checkpoints, checkpoints.forkFromCheckpoint(forkInput(writer, { sourceThreadId: "another-source" })), "SANDBOX_SNAPSHOT_FORK_SOURCE_THREAD_MISMATCH");
+		});
+		it("rejects equal source and destination threads without changing the source", async () => {
+			const { persistence, checkpoints } = await makeSnapshots();
+			const { source, sourceWriter } = await appendSource(checkpoints);
+			const before = {
+				transcript: await persistence.stores.messages.loadThread("source"),
+				head: await checkpoints.getHead("source"),
+				checkpoints: await checkpoints.list("source"),
+				references: await checkpoints.listBlobReferences()
+			};
+			await expect(checkpoints.forkFromCheckpoint(forkInput(sourceWriter, { destinationThreadId: source.threadId }))).rejects.toMatchObject({ code: "SANDBOX_SNAPSHOT_FORK_SOURCE_THREAD_MISMATCH" });
+			expect({
+				transcript: await persistence.stores.messages.loadThread("source"),
+				head: await checkpoints.getHead("source"),
+				checkpoints: await checkpoints.list("source"),
+				references: await checkpoints.listBlobReferences()
+			}).toEqual(before);
+		});
+		it("rejects a missing destination writer without changing the destination", async () => {
+			const { persistence, checkpoints } = await makeSnapshots();
+			await appendSource(checkpoints);
+			await expectRejectedWithoutDestinationChanges(persistence, checkpoints, checkpoints.forkFromCheckpoint(forkInput({
+				threadId: "destination",
+				ownerToken: "missing-owner",
+				fence: 1
+			})), "SANDBOX_SNAPSHOT_WRITER_LOST");
+		});
+		it("rejects a wrong destination writer without changing the destination", async () => {
+			const { persistence, checkpoints } = await makeSnapshots();
+			await appendSource(checkpoints);
+			const wrongWriter = await checkpoints.acquireWriter("another-thread");
+			await expectRejectedWithoutDestinationChanges(persistence, checkpoints, checkpoints.forkFromCheckpoint(forkInput(wrongWriter)), "SANDBOX_SNAPSHOT_WRITER_LOST");
+		});
+		it("rejects a stale destination writer without changing the destination", async () => {
+			const { persistence, checkpoints } = await makeSnapshots();
+			await appendSource(checkpoints);
+			const staleWriter = await checkpoints.acquireWriter("destination");
+			await staleWriter.release();
+			await expectRejectedWithoutDestinationChanges(persistence, checkpoints, checkpoints.forkFromCheckpoint(forkInput(staleWriter)), "SANDBOX_SNAPSHOT_WRITER_LOST");
+		});
+		it("rejects a destination transcript without changing its checkpoint state", async () => {
+			const { persistence, checkpoints } = await makeSnapshots();
+			await appendSource(checkpoints);
+			await persistence.stores.messages.saveThread("destination", [{
+				role: "user",
+				content: "already here"
+			}]);
+			const writer = await checkpoints.acquireWriter("destination");
+			await expectRejectedWithoutDestinationChanges(persistence, checkpoints, checkpoints.forkFromCheckpoint(forkInput(writer)), "SANDBOX_SNAPSHOT_FORK_DESTINATION_NOT_EMPTY");
+		});
+		it("rejects an orphaned checkpoint id without changing the destination", async () => {
+			const { persistence, checkpoints } = await makeSnapshots();
+			const { source } = await appendSource(checkpoints);
+			const orphanWriter = await checkpoints.acquireWriter("orphan-thread");
+			await checkpoints.append({
+				checkpoint: {
+					...source,
+					id: "orphaned-id",
+					threadId: "orphan-thread",
+					parentCheckpointId: null,
+					createdAt: 11
+				},
+				expectedHeadId: null,
+				writer: orphanWriter
+			});
+			const destinationWriter = await checkpoints.acquireWriter("destination");
+			await expectRejectedWithoutDestinationChanges(persistence, checkpoints, checkpoints.forkFromCheckpoint(forkInput(destinationWriter, { destinationCheckpointId: "orphaned-id" })), "SANDBOX_SNAPSHOT_FORK_DESTINATION_NOT_EMPTY");
+		});
+	});
+}
+//#endregion
+export { runSandboxCheckpointForkConformance };
+
+//# sourceMappingURL=checkpoint-fork-conformance.js.map

package/dist/esm/testkit/checkpoint-fork-conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-fork-conformance.js","names":[],"sources":["../../../src/testkit/checkpoint-fork-conformance.ts"],"sourcesContent":["import { describe, expect, it } from 'vitest'\nimport type { ModelMessage } from '@tanstack/ai'\nimport type {\n  ForkCapableSandboxCheckpointStore,\n  SandboxCheckpoint,\n  SandboxCheckpointForkInput,\n  SandboxCheckpointWriter,\n  SandboxCheckpointWriterLease,\n} from '../checkpoint-store'\nimport { InMemorySandboxCheckpointStore } from '../checkpoint-store'\n\n/** Combined stores required to exercise an atomic checkpoint fork. */\nexport interface SandboxCheckpointForkConformanceInput {\n  persistence: {\n    stores: {\n      messages: {\n        loadThread: (threadId: string) => Promise<Array<ModelMessage>>\n        saveThread: (\n          threadId: string,\n          messages: Array<ModelMessage>,\n        ) => Promise<void>\n      }\n    }\n  }\n  checkpoints: ForkCapableSandboxCheckpointStore\n}\n\nexport interface SandboxCheckpointForkConformanceFactory {\n  ():\n    | SandboxCheckpointForkConformanceInput\n    | Promise<SandboxCheckpointForkConformanceInput>\n}\n\ntype ForkInputWithoutWriter = Omit<SandboxCheckpointForkInput, 'writer'>\n\nfunction sourceCheckpoint(): SandboxCheckpoint {\n  return {\n    id: 'source-root',\n    threadId: 'source',\n    parentCheckpointId: null,\n    createdAt: 10,\n    reason: 'named',\n    label: 'source label',\n    sourceRunId: 'run-1',\n    files: [\n      {\n        path: 'a.txt',\n        kind: 'file',\n        blobKey: `sandbox-files/sha256/${'a'.repeat(64)}`,\n        size: 1,\n      },\n    ],\n    conversation: [{ role: 'user', content: 'checkpoint conversation' }],\n    artifacts: [],\n  }\n}\n\nasync function appendSource(\n  checkpoints: ForkCapableSandboxCheckpointStore,\n): Promise<{\n  source: SandboxCheckpoint\n  sourceWriter: SandboxCheckpointWriterLease\n}> {\n  const sourceWriter = await checkpoints.acquireWriter('source')\n  const source = sourceCheckpoint()\n  await checkpoints.append({\n    checkpoint: source,\n    expectedHeadId: null,\n    writer: sourceWriter,\n  })\n  return { source, sourceWriter }\n}\n\nfunction forkInput(\n  writer: SandboxCheckpointWriter,\n  overrides: Partial<ForkInputWithoutWriter> = {},\n): SandboxCheckpointForkInput {\n  return {\n    sourceThreadId: 'source',\n    sourceCheckpointId: 'source-root',\n    destinationThreadId: 'destination',\n    destinationCheckpointId: 'fork-root',\n    createdAt: 20,\n    writer,\n    ...overrides,\n  }\n}\n\nasync function destinationState(\n  persistence: SandboxCheckpointForkConformanceInput['persistence'],\n  checkpoints: ForkCapableSandboxCheckpointStore,\n) {\n  return {\n    transcript: await persistence.stores.messages.loadThread('destination'),\n    head: await checkpoints.getHead('destination'),\n    checkpoints: await checkpoints.list('destination'),\n    references: await checkpoints.listBlobReferences(),\n  }\n}\n\nasync function expectRejectedWithoutDestinationChanges(\n  persistence: SandboxCheckpointForkConformanceInput['persistence'],\n  checkpoints: ForkCapableSandboxCheckpointStore,\n  operation: Promise<unknown>,\n  code: string,\n): Promise<void> {\n  const before = await destinationState(persistence, checkpoints)\n  await expect(operation).rejects.toMatchObject({ code })\n  expect(await destinationState(persistence, checkpoints)).toEqual(before)\n}\n\nexport function runSandboxCheckpointForkConformance(\n  name: string,\n  makeSnapshots: SandboxCheckpointForkConformanceFactory,\n): void {\n  describe(`Sandbox checkpoint fork conformance: ${name}`, () => {\n    it('copies a selected historical checkpoint and creates an exact fork root', async () => {\n      const { persistence, checkpoints } = await makeSnapshots()\n      const { source, sourceWriter } = await appendSource(checkpoints)\n      await checkpoints.append({\n        checkpoint: {\n          id: 'source-head',\n          threadId: 'source',\n          parentCheckpointId: source.id,\n          createdAt: 11,\n          reason: 'automatic',\n          files: [],\n          conversation: [{ role: 'user', content: 'newer conversation' }],\n          artifacts: [],\n        },\n        expectedHeadId: source.id,\n        writer: sourceWriter,\n      })\n      await persistence.stores.messages.saveThread('source', [\n        { role: 'user', content: 'current source message' },\n      ])\n      const destinationWriter = await checkpoints.acquireWriter('destination')\n      const result = await checkpoints.forkFromCheckpoint(\n        forkInput(destinationWriter),\n      )\n      expect(result.checkpoint).toEqual({\n        id: 'fork-root',\n        threadId: 'destination',\n        parentCheckpointId: null,\n        createdAt: 20,\n        reason: 'fork-root',\n        files: source.files,\n        conversation: source.conversation,\n        artifacts: [],\n      })\n      expect(\n        await persistence.stores.messages.loadThread('destination'),\n      ).toEqual(source.conversation)\n      expect(await checkpoints.getHead('source')).toBe('source-head')\n    })\n\n    it('rejects a plain checkpoint store because it has no fork capability', () => {\n      const store = new InMemorySandboxCheckpointStore()\n      expect('forkFromCheckpoint' in store).toBe(false)\n    })\n\n    it('rejects a missing source without changing the destination', async () => {\n      const { persistence, checkpoints } = await makeSnapshots()\n      const writer = await checkpoints.acquireWriter('destination')\n      await expectRejectedWithoutDestinationChanges(\n        persistence,\n        checkpoints,\n        checkpoints.forkFromCheckpoint(\n          forkInput(writer, { sourceCheckpointId: 'missing' }),\n        ),\n        'SANDBOX_SNAPSHOT_FORK_SOURCE_NOT_FOUND',\n      )\n    })\n\n    it('rejects a source thread mismatch without changing the destination', async () => {\n      const { persistence, checkpoints } = await makeSnapshots()\n      await appendSource(checkpoints)\n      const writer = await checkpoints.acquireWriter('destination')\n      await expectRejectedWithoutDestinationChanges(\n        persistence,\n        checkpoints,\n        checkpoints.forkFromCheckpoint(\n          forkInput(writer, { sourceThreadId: 'another-source' }),\n        ),\n        'SANDBOX_SNAPSHOT_FORK_SOURCE_THREAD_MISMATCH',\n      )\n    })\n\n    it('rejects equal source and destination threads without changing the source', async () => {\n      const { persistence, checkpoints } = await makeSnapshots()\n      const { source, sourceWriter } = await appendSource(checkpoints)\n      const before = {\n        transcript: await persistence.stores.messages.loadThread('source'),\n        head: await checkpoints.getHead('source'),\n        checkpoints: await checkpoints.list('source'),\n        references: await checkpoints.listBlobReferences(),\n      }\n      await expect(\n        checkpoints.forkFromCheckpoint(\n          forkInput(sourceWriter, {\n            destinationThreadId: source.threadId,\n          }),\n        ),\n      ).rejects.toMatchObject({\n        code: 'SANDBOX_SNAPSHOT_FORK_SOURCE_THREAD_MISMATCH',\n      })\n      expect({\n        transcript: await persistence.stores.messages.loadThread('source'),\n        head: await checkpoints.getHead('source'),\n        checkpoints: await checkpoints.list('source'),\n        references: await checkpoints.listBlobReferences(),\n      }).toEqual(before)\n    })\n\n    it('rejects a missing destination writer without changing the destination', async () => {\n      const { persistence, checkpoints } = await makeSnapshots()\n      await appendSource(checkpoints)\n      const missingWriter: SandboxCheckpointWriter = {\n        threadId: 'destination',\n        ownerToken: 'missing-owner',\n        fence: 1,\n      }\n      await expectRejectedWithoutDestinationChanges(\n        persistence,\n        checkpoints,\n        checkpoints.forkFromCheckpoint(forkInput(missingWriter)),\n        'SANDBOX_SNAPSHOT_WRITER_LOST',\n      )\n    })\n\n    it('rejects a wrong destination writer without changing the destination', async () => {\n      const { persistence, checkpoints } = await makeSnapshots()\n      await appendSource(checkpoints)\n      const wrongWriter = await checkpoints.acquireWriter('another-thread')\n      await expectRejectedWithoutDestinationChanges(\n        persistence,\n        checkpoints,\n        checkpoints.forkFromCheckpoint(forkInput(wrongWriter)),\n        'SANDBOX_SNAPSHOT_WRITER_LOST',\n      )\n    })\n\n    it('rejects a stale destination writer without changing the destination', async () => {\n      const { persistence, checkpoints } = await makeSnapshots()\n      await appendSource(checkpoints)\n      const staleWriter = await checkpoints.acquireWriter('destination')\n      await staleWriter.release()\n      await expectRejectedWithoutDestinationChanges(\n        persistence,\n        checkpoints,\n        checkpoints.forkFromCheckpoint(forkInput(staleWriter)),\n        'SANDBOX_SNAPSHOT_WRITER_LOST',\n      )\n    })\n\n    it('rejects a destination transcript without changing its checkpoint state', async () => {\n      const { persistence, checkpoints } = await makeSnapshots()\n      await appendSource(checkpoints)\n      await persistence.stores.messages.saveThread('destination', [\n        { role: 'user', content: 'already here' },\n      ])\n      const writer = await checkpoints.acquireWriter('destination')\n      await expectRejectedWithoutDestinationChanges(\n        persistence,\n        checkpoints,\n        checkpoints.forkFromCheckpoint(forkInput(writer)),\n        'SANDBOX_SNAPSHOT_FORK_DESTINATION_NOT_EMPTY',\n      )\n    })\n\n    it('rejects an orphaned checkpoint id without changing the destination', async () => {\n      const { persistence, checkpoints } = await makeSnapshots()\n      const { source } = await appendSource(checkpoints)\n      const orphanWriter = await checkpoints.acquireWriter('orphan-thread')\n      await checkpoints.append({\n        checkpoint: {\n          ...source,\n          id: 'orphaned-id',\n          threadId: 'orphan-thread',\n          parentCheckpointId: null,\n          createdAt: 11,\n        },\n        expectedHeadId: null,\n        writer: orphanWriter,\n      })\n      const destinationWriter = await checkpoints.acquireWriter('destination')\n      await expectRejectedWithoutDestinationChanges(\n        persistence,\n        checkpoints,\n        checkpoints.forkFromCheckpoint(\n          forkInput(destinationWriter, {\n            destinationCheckpointId: 'orphaned-id',\n          }),\n        ),\n        'SANDBOX_SNAPSHOT_FORK_DESTINATION_NOT_EMPTY',\n      )\n    })\n  })\n}\n"],"mappings":";;;AAmCA,SAAS,mBAAsC;CAC7C,OAAO;EACL,IAAI;EACJ,UAAU;EACV,oBAAoB;EACpB,WAAW;EACX,QAAQ;EACR,OAAO;EACP,aAAa;EACb,OAAO,CACL;GACE,MAAM;GACN,MAAM;GACN,SAAS,wBAAwB,IAAI,OAAO,EAAE;GAC9C,MAAM;EACR,CACF;EACA,cAAc,CAAC;GAAE,MAAM;GAAQ,SAAS;EAA0B,CAAC;EACnE,WAAW,CAAC;CACd;AACF;AAEA,eAAe,aACb,aAIC;CACD,MAAM,eAAe,MAAM,YAAY,cAAc,QAAQ;CAC7D,MAAM,SAAS,iBAAiB;CAChC,MAAM,YAAY,OAAO;EACvB,YAAY;EACZ,gBAAgB;EAChB,QAAQ;CACV,CAAC;CACD,OAAO;EAAE;EAAQ;CAAa;AAChC;AAEA,SAAS,UACP,QACA,YAA6C,CAAC,GAClB;CAC5B,OAAO;EACL,gBAAgB;EAChB,oBAAoB;EACpB,qBAAqB;EACrB,yBAAyB;EACzB,WAAW;EACX;EACA,GAAG;CACL;AACF;AAEA,eAAe,iBACb,aACA,aACA;CACA,OAAO;EACL,YAAY,MAAM,YAAY,OAAO,SAAS,WAAW,aAAa;EACtE,MAAM,MAAM,YAAY,QAAQ,aAAa;EAC7C,aAAa,MAAM,YAAY,KAAK,aAAa;EACjD,YAAY,MAAM,YAAY,mBAAmB;CACnD;AACF;AAEA,eAAe,wCACb,aACA,aACA,WACA,MACe;CACf,MAAM,SAAS,MAAM,iBAAiB,aAAa,WAAW;CAC9D,MAAM,OAAO,SAAS,CAAC,CAAC,QAAQ,cAAc,EAAE,KAAK,CAAC;CACtD,OAAO,MAAM,iBAAiB,aAAa,WAAW,CAAC,CAAC,CAAC,QAAQ,MAAM;AACzE;AAEA,SAAgB,oCACd,MACA,eACM;CACN,SAAS,wCAAwC,cAAc;EAC7D,GAAG,0EAA0E,YAAY;GACvF,MAAM,EAAE,aAAa,gBAAgB,MAAM,cAAc;GACzD,MAAM,EAAE,QAAQ,iBAAiB,MAAM,aAAa,WAAW;GAC/D,MAAM,YAAY,OAAO;IACvB,YAAY;KACV,IAAI;KACJ,UAAU;KACV,oBAAoB,OAAO;KAC3B,WAAW;KACX,QAAQ;KACR,OAAO,CAAC;KACR,cAAc,CAAC;MAAE,MAAM;MAAQ,SAAS;KAAqB,CAAC;KAC9D,WAAW,CAAC;IACd;IACA,gBAAgB,OAAO;IACvB,QAAQ;GACV,CAAC;GACD,MAAM,YAAY,OAAO,SAAS,WAAW,UAAU,CACrD;IAAE,MAAM;IAAQ,SAAS;GAAyB,CACpD,CAAC;GACD,MAAM,oBAAoB,MAAM,YAAY,cAAc,aAAa;GACvE,MAAM,SAAS,MAAM,YAAY,mBAC/B,UAAU,iBAAiB,CAC7B;GACA,OAAO,OAAO,UAAU,CAAC,CAAC,QAAQ;IAChC,IAAI;IACJ,UAAU;IACV,oBAAoB;IACpB,WAAW;IACX,QAAQ;IACR,OAAO,OAAO;IACd,cAAc,OAAO;IACrB,WAAW,CAAC;GACd,CAAC;GACD,OACE,MAAM,YAAY,OAAO,SAAS,WAAW,aAAa,CAC5D,CAAC,CAAC,QAAQ,OAAO,YAAY;GAC7B,OAAO,MAAM,YAAY,QAAQ,QAAQ,CAAC,CAAC,CAAC,KAAK,aAAa;EAChE,CAAC;EAED,GAAG,4EAA4E;GAC7E,MAAM,QAAQ,IAAI,+BAA+B;GACjD,OAAO,wBAAwB,KAAK,CAAC,CAAC,KAAK,KAAK;EAClD,CAAC;EAED,GAAG,6DAA6D,YAAY;GAC1E,MAAM,EAAE,aAAa,gBAAgB,MAAM,cAAc;GACzD,MAAM,SAAS,MAAM,YAAY,cAAc,aAAa;GAC5D,MAAM,wCACJ,aACA,aACA,YAAY,mBACV,UAAU,QAAQ,EAAE,oBAAoB,UAAU,CAAC,CACrD,GACA,wCACF;EACF,CAAC;EAED,GAAG,qEAAqE,YAAY;GAClF,MAAM,EAAE,aAAa,gBAAgB,MAAM,cAAc;GACzD,MAAM,aAAa,WAAW;GAC9B,MAAM,SAAS,MAAM,YAAY,cAAc,aAAa;GAC5D,MAAM,wCACJ,aACA,aACA,YAAY,mBACV,UAAU,QAAQ,EAAE,gBAAgB,iBAAiB,CAAC,CACxD,GACA,8CACF;EACF,CAAC;EAED,GAAG,4EAA4E,YAAY;GACzF,MAAM,EAAE,aAAa,gBAAgB,MAAM,cAAc;GACzD,MAAM,EAAE,QAAQ,iBAAiB,MAAM,aAAa,WAAW;GAC/D,MAAM,SAAS;IACb,YAAY,MAAM,YAAY,OAAO,SAAS,WAAW,QAAQ;IACjE,MAAM,MAAM,YAAY,QAAQ,QAAQ;IACxC,aAAa,MAAM,YAAY,KAAK,QAAQ;IAC5C,YAAY,MAAM,YAAY,mBAAmB;GACnD;GACA,MAAM,OACJ,YAAY,mBACV,UAAU,cAAc,EACtB,qBAAqB,OAAO,SAC9B,CAAC,CACH,CACF,CAAC,CAAC,QAAQ,cAAc,EACtB,MAAM,+CACR,CAAC;GACD,OAAO;IACL,YAAY,MAAM,YAAY,OAAO,SAAS,WAAW,QAAQ;IACjE,MAAM,MAAM,YAAY,QAAQ,QAAQ;IACxC,aAAa,MAAM,YAAY,KAAK,QAAQ;IAC5C,YAAY,MAAM,YAAY,mBAAmB;GACnD,CAAC,CAAC,CAAC,QAAQ,MAAM;EACnB,CAAC;EAED,GAAG,yEAAyE,YAAY;GACtF,MAAM,EAAE,aAAa,gBAAgB,MAAM,cAAc;GACzD,MAAM,aAAa,WAAW;GAM9B,MAAM,wCACJ,aACA,aACA,YAAY,mBAAmB,UAAU;IAPzC,UAAU;IACV,YAAY;IACZ,OAAO;GAKkC,CAAa,CAAC,GACvD,8BACF;EACF,CAAC;EAED,GAAG,uEAAuE,YAAY;GACpF,MAAM,EAAE,aAAa,gBAAgB,MAAM,cAAc;GACzD,MAAM,aAAa,WAAW;GAC9B,MAAM,cAAc,MAAM,YAAY,cAAc,gBAAgB;GACpE,MAAM,wCACJ,aACA,aACA,YAAY,mBAAmB,UAAU,WAAW,CAAC,GACrD,8BACF;EACF,CAAC;EAED,GAAG,uEAAuE,YAAY;GACpF,MAAM,EAAE,aAAa,gBAAgB,MAAM,cAAc;GACzD,MAAM,aAAa,WAAW;GAC9B,MAAM,cAAc,MAAM,YAAY,cAAc,aAAa;GACjE,MAAM,YAAY,QAAQ;GAC1B,MAAM,wCACJ,aACA,aACA,YAAY,mBAAmB,UAAU,WAAW,CAAC,GACrD,8BACF;EACF,CAAC;EAED,GAAG,0EAA0E,YAAY;GACvF,MAAM,EAAE,aAAa,gBAAgB,MAAM,cAAc;GACzD,MAAM,aAAa,WAAW;GAC9B,MAAM,YAAY,OAAO,SAAS,WAAW,eAAe,CAC1D;IAAE,MAAM;IAAQ,SAAS;GAAe,CAC1C,CAAC;GACD,MAAM,SAAS,MAAM,YAAY,cAAc,aAAa;GAC5D,MAAM,wCACJ,aACA,aACA,YAAY,mBAAmB,UAAU,MAAM,CAAC,GAChD,6CACF;EACF,CAAC;EAED,GAAG,sEAAsE,YAAY;GACnF,MAAM,EAAE,aAAa,gBAAgB,MAAM,cAAc;GACzD,MAAM,EAAE,WAAW,MAAM,aAAa,WAAW;GACjD,MAAM,eAAe,MAAM,YAAY,cAAc,eAAe;GACpE,MAAM,YAAY,OAAO;IACvB,YAAY;KACV,GAAG;KACH,IAAI;KACJ,UAAU;KACV,oBAAoB;KACpB,WAAW;IACb;IACA,gBAAgB;IAChB,QAAQ;GACV,CAAC;GACD,MAAM,oBAAoB,MAAM,YAAY,cAAc,aAAa;GACvE,MAAM,wCACJ,aACA,aACA,YAAY,mBACV,UAAU,mBAAmB,EAC3B,yBAAyB,cAC3B,CAAC,CACH,GACA,6CACF;EACF,CAAC;CACH,CAAC;AACH"}

package/dist/esm/testkit/conformance.d.ts

@@ -8,6 +8,10 @@ export type { ReaperConformanceConfig } from './reaper-conformance.js';
 export { runDurableRunFieldsConformance } from './durable-run-fields-conformance.js';
 export type { MakeRunStore } from './durable-run-fields-conformance.js';
 export { makeFakeShellSpawn } from './shell-spawn.js';
+export { runSandboxCheckpointStoreConformance } from './checkpoint-conformance.js';
+export type { SandboxCheckpointStoreOptions } from '../checkpoint-store.js';
+export { runSandboxCheckpointForkConformance } from './checkpoint-fork-conformance.js';
+export type { SandboxCheckpointForkConformanceInput, SandboxCheckpointForkConformanceFactory, } from './checkpoint-fork-conformance.js';
 /**
  * Assert `makeStore()` produces a spec-compliant {@link SandboxInstanceStore}. Each
  * `it` gets a fresh store, so implementations may share process state across

package/dist/esm/testkit/conformance.js

@@ -3,6 +3,8 @@ import { runTakeoverConformance } from "./takeover-conformance.js";
 import { runReaperConformance } from "./reaper-conformance.js";
 import { runDurableRunFieldsConformance } from "./durable-run-fields-conformance.js";
 import { makeFakeShellSpawn } from "./shell-spawn.js";
+import { runSandboxCheckpointStoreConformance } from "./checkpoint-conformance.js";
+import { runSandboxCheckpointForkConformance } from "./checkpoint-fork-conformance.js";
 import { describe, expect, it } from "vitest";
 //#region src/testkit/conformance.ts
 /**
@@ -94,6 +96,6 @@ function runSandboxInstanceStoreConformance(name, makeStore) {
 	});
 }
 //#endregion
-export { makeFakeShellSpawn, runDurableRunFieldsConformance, runJournalConformance, runReaperConformance, runSandboxInstanceStoreConformance, runTakeoverConformance };
+export { makeFakeShellSpawn, runDurableRunFieldsConformance, runJournalConformance, runReaperConformance, runSandboxCheckpointForkConformance, runSandboxCheckpointStoreConformance, runSandboxInstanceStoreConformance, runTakeoverConformance };
 
 //# sourceMappingURL=conformance.js.map

package/dist/esm/testkit/conformance.js.map

@@ -1 +1 @@
-{"version":3,"file":"conformance.js","names":[],"sources":["../../../src/testkit/conformance.ts"],"sourcesContent":["/**\n * Conformance suite for a {@link SandboxInstanceStore} implementation.\n *\n * Run this against a fresh BYO store (or the in-memory reference) to prove it\n * satisfies the get / upsert / delete contract `@tanstack/ai-sandbox`'s ensure\n * algorithm relies on — including insert-vs-overwrite and optional-field\n * handling (full replace must clear omitted optionals).\n *\n * Vitest is an OPTIONAL peer dependency: this module is imported only from test\n * files, which already run under Vitest.\n */\nimport { describe, expect, it } from 'vitest'\nimport type {\n  SandboxInstanceRecord,\n  SandboxInstanceStore,\n} from '../instance-store'\n\n// The `./testkit` package.json subpath resolves to THIS module's build output\n// only (`dist/esm/testkit/conformance.js`), not a barrel over `src/testkit/`.\n// Re-export the journal, takeover, and reaper conformance suites here so they\n// are reachable from `@tanstack/ai-sandbox/testkit` without changing that\n// mapping.\nexport { runJournalConformance } from './journal-conformance'\nexport type { JournalConformanceConfig } from './journal-conformance'\nexport { runTakeoverConformance } from './takeover-conformance'\nexport type { TakeoverConformanceConfig } from './takeover-conformance'\nexport { runReaperConformance } from './reaper-conformance'\nexport type { ReaperConformanceConfig } from './reaper-conformance'\nexport { runDurableRunFieldsConformance } from './durable-run-fields-conformance'\nexport type { MakeRunStore } from './durable-run-fields-conformance'\nexport { makeFakeShellSpawn } from './shell-spawn'\n\nfunction makeRecord(\n  overrides?: Partial<SandboxInstanceRecord>,\n): SandboxInstanceRecord {\n  return {\n    key: 'thread-1',\n    provider: 'fake',\n    providerSandboxId: 'sb-1',\n    threadId: 'thread-1',\n    updatedAt: 1,\n    ...overrides,\n  }\n}\n\n/**\n * Assert `makeStore()` produces a spec-compliant {@link SandboxInstanceStore}. Each\n * `it` gets a fresh store, so implementations may share process state across\n * calls without cross-test bleed only if `makeStore` returns an isolated store.\n */\nexport function runSandboxInstanceStoreConformance(\n  name: string,\n  makeStore: () => SandboxInstanceStore | Promise<SandboxInstanceStore>,\n): void {\n  describe(`SandboxInstanceStore conformance: ${name}`, () => {\n    it('returns null for a missing key', async () => {\n      const store = await makeStore()\n      expect(await store.get('absent')).toBeNull()\n    })\n\n    it('round-trips an upserted record with all fields', async () => {\n      const store = await makeStore()\n      const record = makeRecord({\n        latestSnapshotId: 'snap-1',\n        latestRunId: 'run-1',\n      })\n      await store.upsert(record)\n      expect(await store.get(record.key)).toEqual(record)\n    })\n\n    it('omits absent optional fields on read', async () => {\n      const store = await makeStore()\n      const record = makeRecord()\n      await store.upsert(record)\n      const loaded = await store.get(record.key)\n      expect(loaded).toEqual(record)\n      expect(loaded && 'latestSnapshotId' in loaded).toBe(false)\n      expect(loaded && 'latestRunId' in loaded).toBe(false)\n    })\n\n    it('overwrites an existing record on re-upsert', async () => {\n      const store = await makeStore()\n      await store.upsert(makeRecord({ latestSnapshotId: 'snap-1' }))\n      await store.upsert(\n        makeRecord({ providerSandboxId: 'sb-2', updatedAt: 2 }),\n      )\n      const loaded = await store.get('thread-1')\n      expect(loaded?.providerSandboxId).toBe('sb-2')\n      expect(loaded?.updatedAt).toBe(2)\n      // The overwrite dropped latestSnapshotId — a durable store must clear it,\n      // not retain the prior value.\n      expect(loaded && 'latestSnapshotId' in loaded).toBe(false)\n    })\n\n    it('isolates records by key', async () => {\n      const store = await makeStore()\n      await store.upsert(makeRecord({ key: 'a', threadId: 'a' }))\n      await store.upsert(\n        makeRecord({ key: 'b', threadId: 'b', providerSandboxId: 'sb-b' }),\n      )\n      expect((await store.get('a'))?.providerSandboxId).toBe('sb-1')\n      expect((await store.get('b'))?.providerSandboxId).toBe('sb-b')\n    })\n\n    it('deletes a record', async () => {\n      const store = await makeStore()\n      await store.upsert(makeRecord())\n      await store.delete('thread-1')\n      expect(await store.get('thread-1')).toBeNull()\n    })\n\n    it('delete of a missing key is a no-op', async () => {\n      const store = await makeStore()\n      await expect(store.delete('absent')).resolves.toBeUndefined()\n    })\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAgCA,SAAS,WACP,WACuB;CACvB,OAAO;EACL,KAAK;EACL,UAAU;EACV,mBAAmB;EACnB,UAAU;EACV,WAAW;EACX,GAAG;CACL;AACF;;;;;;AAOA,SAAgB,mCACd,MACA,WACM;CACN,SAAS,qCAAqC,cAAc;EAC1D,GAAG,kCAAkC,YAAY;GAC/C,MAAM,QAAQ,MAAM,UAAU;GAC9B,OAAO,MAAM,MAAM,IAAI,QAAQ,CAAC,CAAC,CAAC,SAAS;EAC7C,CAAC;EAED,GAAG,kDAAkD,YAAY;GAC/D,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,SAAS,WAAW;IACxB,kBAAkB;IAClB,aAAa;GACf,CAAC;GACD,MAAM,MAAM,OAAO,MAAM;GACzB,OAAO,MAAM,MAAM,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,QAAQ,MAAM;EACpD,CAAC;EAED,GAAG,wCAAwC,YAAY;GACrD,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,SAAS,WAAW;GAC1B,MAAM,MAAM,OAAO,MAAM;GACzB,MAAM,SAAS,MAAM,MAAM,IAAI,OAAO,GAAG;GACzC,OAAO,MAAM,CAAC,CAAC,QAAQ,MAAM;GAC7B,OAAO,UAAU,sBAAsB,MAAM,CAAC,CAAC,KAAK,KAAK;GACzD,OAAO,UAAU,iBAAiB,MAAM,CAAC,CAAC,KAAK,KAAK;EACtD,CAAC;EAED,GAAG,8CAA8C,YAAY;GAC3D,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,MAAM,OAAO,WAAW,EAAE,kBAAkB,SAAS,CAAC,CAAC;GAC7D,MAAM,MAAM,OACV,WAAW;IAAE,mBAAmB;IAAQ,WAAW;GAAE,CAAC,CACxD;GACA,MAAM,SAAS,MAAM,MAAM,IAAI,UAAU;GACzC,OAAO,QAAQ,iBAAiB,CAAC,CAAC,KAAK,MAAM;GAC7C,OAAO,QAAQ,SAAS,CAAC,CAAC,KAAK,CAAC;GAGhC,OAAO,UAAU,sBAAsB,MAAM,CAAC,CAAC,KAAK,KAAK;EAC3D,CAAC;EAED,GAAG,2BAA2B,YAAY;GACxC,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,MAAM,OAAO,WAAW;IAAE,KAAK;IAAK,UAAU;GAAI,CAAC,CAAC;GAC1D,MAAM,MAAM,OACV,WAAW;IAAE,KAAK;IAAK,UAAU;IAAK,mBAAmB;GAAO,CAAC,CACnE;GACA,QAAQ,MAAM,MAAM,IAAI,GAAG,EAAA,EAAI,iBAAiB,CAAC,CAAC,KAAK,MAAM;GAC7D,QAAQ,MAAM,MAAM,IAAI,GAAG,EAAA,EAAI,iBAAiB,CAAC,CAAC,KAAK,MAAM;EAC/D,CAAC;EAED,GAAG,oBAAoB,YAAY;GACjC,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,MAAM,OAAO,WAAW,CAAC;GAC/B,MAAM,MAAM,OAAO,UAAU;GAC7B,OAAO,MAAM,MAAM,IAAI,UAAU,CAAC,CAAC,CAAC,SAAS;EAC/C,CAAC;EAED,GAAG,sCAAsC,YAAY;GACnD,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,OAAO,MAAM,OAAO,QAAQ,CAAC,CAAC,CAAC,SAAS,cAAc;EAC9D,CAAC;CACH,CAAC;AACH"}
+{"version":3,"file":"conformance.js","names":[],"sources":["../../../src/testkit/conformance.ts"],"sourcesContent":["/**\n * Conformance suite for a {@link SandboxInstanceStore} implementation.\n *\n * Run this against a fresh BYO store (or the in-memory reference) to prove it\n * satisfies the get / upsert / delete contract `@tanstack/ai-sandbox`'s ensure\n * algorithm relies on — including insert-vs-overwrite and optional-field\n * handling (full replace must clear omitted optionals).\n *\n * Vitest is an OPTIONAL peer dependency: this module is imported only from test\n * files, which already run under Vitest.\n */\nimport { describe, expect, it } from 'vitest'\nimport type {\n  SandboxInstanceRecord,\n  SandboxInstanceStore,\n} from '../instance-store'\n\n// The `./testkit` package.json subpath resolves to THIS module's build output\n// only (`dist/esm/testkit/conformance.js`), not a barrel over `src/testkit/`.\n// Re-export the journal, takeover, and reaper conformance suites here so they\n// are reachable from `@tanstack/ai-sandbox/testkit` without changing that\n// mapping.\nexport { runJournalConformance } from './journal-conformance'\nexport type { JournalConformanceConfig } from './journal-conformance'\nexport { runTakeoverConformance } from './takeover-conformance'\nexport type { TakeoverConformanceConfig } from './takeover-conformance'\nexport { runReaperConformance } from './reaper-conformance'\nexport type { ReaperConformanceConfig } from './reaper-conformance'\nexport { runDurableRunFieldsConformance } from './durable-run-fields-conformance'\nexport type { MakeRunStore } from './durable-run-fields-conformance'\nexport { makeFakeShellSpawn } from './shell-spawn'\nexport { runSandboxCheckpointStoreConformance } from './checkpoint-conformance'\nexport type { SandboxCheckpointStoreOptions } from '../checkpoint-store'\nexport { runSandboxCheckpointForkConformance } from './checkpoint-fork-conformance'\nexport type {\n  SandboxCheckpointForkConformanceInput,\n  SandboxCheckpointForkConformanceFactory,\n} from './checkpoint-fork-conformance'\n\nfunction makeRecord(\n  overrides?: Partial<SandboxInstanceRecord>,\n): SandboxInstanceRecord {\n  return {\n    key: 'thread-1',\n    provider: 'fake',\n    providerSandboxId: 'sb-1',\n    threadId: 'thread-1',\n    updatedAt: 1,\n    ...overrides,\n  }\n}\n\n/**\n * Assert `makeStore()` produces a spec-compliant {@link SandboxInstanceStore}. Each\n * `it` gets a fresh store, so implementations may share process state across\n * calls without cross-test bleed only if `makeStore` returns an isolated store.\n */\nexport function runSandboxInstanceStoreConformance(\n  name: string,\n  makeStore: () => SandboxInstanceStore | Promise<SandboxInstanceStore>,\n): void {\n  describe(`SandboxInstanceStore conformance: ${name}`, () => {\n    it('returns null for a missing key', async () => {\n      const store = await makeStore()\n      expect(await store.get('absent')).toBeNull()\n    })\n\n    it('round-trips an upserted record with all fields', async () => {\n      const store = await makeStore()\n      const record = makeRecord({\n        latestSnapshotId: 'snap-1',\n        latestRunId: 'run-1',\n      })\n      await store.upsert(record)\n      expect(await store.get(record.key)).toEqual(record)\n    })\n\n    it('omits absent optional fields on read', async () => {\n      const store = await makeStore()\n      const record = makeRecord()\n      await store.upsert(record)\n      const loaded = await store.get(record.key)\n      expect(loaded).toEqual(record)\n      expect(loaded && 'latestSnapshotId' in loaded).toBe(false)\n      expect(loaded && 'latestRunId' in loaded).toBe(false)\n    })\n\n    it('overwrites an existing record on re-upsert', async () => {\n      const store = await makeStore()\n      await store.upsert(makeRecord({ latestSnapshotId: 'snap-1' }))\n      await store.upsert(\n        makeRecord({ providerSandboxId: 'sb-2', updatedAt: 2 }),\n      )\n      const loaded = await store.get('thread-1')\n      expect(loaded?.providerSandboxId).toBe('sb-2')\n      expect(loaded?.updatedAt).toBe(2)\n      // The overwrite dropped latestSnapshotId — a durable store must clear it,\n      // not retain the prior value.\n      expect(loaded && 'latestSnapshotId' in loaded).toBe(false)\n    })\n\n    it('isolates records by key', async () => {\n      const store = await makeStore()\n      await store.upsert(makeRecord({ key: 'a', threadId: 'a' }))\n      await store.upsert(\n        makeRecord({ key: 'b', threadId: 'b', providerSandboxId: 'sb-b' }),\n      )\n      expect((await store.get('a'))?.providerSandboxId).toBe('sb-1')\n      expect((await store.get('b'))?.providerSandboxId).toBe('sb-b')\n    })\n\n    it('deletes a record', async () => {\n      const store = await makeStore()\n      await store.upsert(makeRecord())\n      await store.delete('thread-1')\n      expect(await store.get('thread-1')).toBeNull()\n    })\n\n    it('delete of a missing key is a no-op', async () => {\n      const store = await makeStore()\n      await expect(store.delete('absent')).resolves.toBeUndefined()\n    })\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAuCA,SAAS,WACP,WACuB;CACvB,OAAO;EACL,KAAK;EACL,UAAU;EACV,mBAAmB;EACnB,UAAU;EACV,WAAW;EACX,GAAG;CACL;AACF;;;;;;AAOA,SAAgB,mCACd,MACA,WACM;CACN,SAAS,qCAAqC,cAAc;EAC1D,GAAG,kCAAkC,YAAY;GAC/C,MAAM,QAAQ,MAAM,UAAU;GAC9B,OAAO,MAAM,MAAM,IAAI,QAAQ,CAAC,CAAC,CAAC,SAAS;EAC7C,CAAC;EAED,GAAG,kDAAkD,YAAY;GAC/D,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,SAAS,WAAW;IACxB,kBAAkB;IAClB,aAAa;GACf,CAAC;GACD,MAAM,MAAM,OAAO,MAAM;GACzB,OAAO,MAAM,MAAM,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,QAAQ,MAAM;EACpD,CAAC;EAED,GAAG,wCAAwC,YAAY;GACrD,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,SAAS,WAAW;GAC1B,MAAM,MAAM,OAAO,MAAM;GACzB,MAAM,SAAS,MAAM,MAAM,IAAI,OAAO,GAAG;GACzC,OAAO,MAAM,CAAC,CAAC,QAAQ,MAAM;GAC7B,OAAO,UAAU,sBAAsB,MAAM,CAAC,CAAC,KAAK,KAAK;GACzD,OAAO,UAAU,iBAAiB,MAAM,CAAC,CAAC,KAAK,KAAK;EACtD,CAAC;EAED,GAAG,8CAA8C,YAAY;GAC3D,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,MAAM,OAAO,WAAW,EAAE,kBAAkB,SAAS,CAAC,CAAC;GAC7D,MAAM,MAAM,OACV,WAAW;IAAE,mBAAmB;IAAQ,WAAW;GAAE,CAAC,CACxD;GACA,MAAM,SAAS,MAAM,MAAM,IAAI,UAAU;GACzC,OAAO,QAAQ,iBAAiB,CAAC,CAAC,KAAK,MAAM;GAC7C,OAAO,QAAQ,SAAS,CAAC,CAAC,KAAK,CAAC;GAGhC,OAAO,UAAU,sBAAsB,MAAM,CAAC,CAAC,KAAK,KAAK;EAC3D,CAAC;EAED,GAAG,2BAA2B,YAAY;GACxC,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,MAAM,OAAO,WAAW;IAAE,KAAK;IAAK,UAAU;GAAI,CAAC,CAAC;GAC1D,MAAM,MAAM,OACV,WAAW;IAAE,KAAK;IAAK,UAAU;IAAK,mBAAmB;GAAO,CAAC,CACnE;GACA,QAAQ,MAAM,MAAM,IAAI,GAAG,EAAA,EAAI,iBAAiB,CAAC,CAAC,KAAK,MAAM;GAC7D,QAAQ,MAAM,MAAM,IAAI,GAAG,EAAA,EAAI,iBAAiB,CAAC,CAAC,KAAK,MAAM;EAC/D,CAAC;EAED,GAAG,oBAAoB,YAAY;GACjC,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,MAAM,OAAO,WAAW,CAAC;GAC/B,MAAM,MAAM,OAAO,UAAU;GAC7B,OAAO,MAAM,MAAM,IAAI,UAAU,CAAC,CAAC,CAAC,SAAS;EAC/C,CAAC;EAED,GAAG,sCAAsC,YAAY;GACnD,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,OAAO,MAAM,OAAO,QAAQ,CAAC,CAAC,CAAC,SAAS,cAAc;EAC9D,CAAC;CACH,CAAC;AACH"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-sandbox",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Provider-agnostic sandbox layer for TanStack AI — run harness adapters inside isolated sandboxes (defineSandbox, defineWorkspace, withSandbox) with a uniform SandboxHandle, workspace bootstrap, policy, and resumable lifecycle.",
   "author": "",
   "license": "MIT",
@@ -60,12 +60,16 @@
   "peerDependencies": {
     "@ngrok/ngrok": "^1.0.0",
     "vitest": "^4.1.10",
-    "@tanstack/ai": "^0.46.0"
+    "@tanstack/ai": "^0.47.1",
+    "@tanstack/ai-persistence": "^0.4.0"
   },
   "peerDependenciesMeta": {
     "@ngrok/ngrok": {
       "optional": true
     },
+    "@tanstack/ai-persistence": {
+      "optional": true
+    },
     "vitest": {
       "optional": true
     }
@@ -74,7 +78,8 @@
     "@ngrok/ngrok": "^1.7.0",
     "@vitest/coverage-v8": "4.1.10",
     "vitest": "^4.1.10",
-    "@tanstack/ai": "0.46.0"
+    "@tanstack/ai": "0.47.1",
+    "@tanstack/ai-persistence": "0.4.0"
   },
   "scripts": {
     "build": "vite build",

package/skills/ai-sandbox/SKILL.md

@@ -8,7 +8,13 @@ description: >
   fileSkill), plugins, instructions → canonical AGENTS.md + symlinks projected
   per harness; shallow-clone default with depth opt-out; serial/parallel setup
   callback over a persistent shell; snapshot-after-setup default with
-  snapshotMaxAge TTL; defineWorkspace (git/setup/scripts/skills/secrets/
+  snapshotMaxAge TTL. It also covers portable snapshots after a successful
+  terminal run with withPersistence before withSandbox and
+  memorySandboxSnapshots for local examples. It covers named saves with
+  snapshots.save, selected-checkpoint forks with snapshots.fork, and
+  authorized artifact reads with snapshots.readArtifact. See
+  docs/sandbox/portable-snapshots.md. It covers defineWorkspace
+  (git/setup/scripts/skills/secrets/
   instructions/plugins), defineSandboxPolicy (allow/ask/deny), lifecycle/resume,
   the SandboxHandle (fs/git/process/ports), capability tokens, defineSandbox
   hooks (onFile/onFileCreate/onFileChange/onFileDelete/onReady/onError/
@@ -185,6 +191,87 @@ lifecycle: {
 
 Providers without snapshot support skip the step silently.
 
+### Portable sandbox snapshots
+
+Portable snapshots keep completed workspace files in application persistence.
+They are separate from provider-native bootstrap snapshots. Configure the
+middleware in this order, with the same persistence value in both places:
+
+```typescript
+import { withPersistence } from '@tanstack/ai-persistence'
+import { memorySandboxSnapshots, withSandbox } from '@tanstack/ai-sandbox'
+
+const snapshots = await memorySandboxSnapshots({ sandbox, instances })
+
+const middleware = [
+  withPersistence(snapshots.persistence),
+  withSandbox(sandbox, { instances, snapshots }),
+]
+```
+
+Each successful terminal run saves regular files, empty directories, durable
+conversation data, and persisted thread artifacts. A later run restores the
+latest checkpoint only into a new private sandbox. A live resumed sandbox is
+never overwritten. The default policy excludes `.git`, `node_modules`, and
+`.env*` path segments at every depth. It excludes the exact projection marker
+only at the workspace root. It also excludes root `CLAUDE.md` and `GEMINI.md`,
+plus direct `.claude/skills/<name>`, `.codex/skills/<name>`, and
+`.grok/skills/<name>` paths. These exclusions use paths even for regular files
+or copies. If you pass only `include` or only `redact`, the default
+exclusions stay in place. If you pass `exclude`, that function replaces
+the default exclusions, except for exact projection-marker protection.
+Copy `defaultSandboxSnapshotPolicy()` first when you write `exclude`.
+Pass `include` and `exclude` functions on `policy` to store only some files,
+including one file. There is no `save({ files })` list. See
+`docs/sandbox/portable-snapshots-files.md`. Resolved secrets are redacted before the data is stored. Symlinks,
+executables, and special filesystem entries fail the capture or restore. Each
+thread has one writer lease. Pause and detach release the lease without a
+partial checkpoint. Blob retention is manual because there is no automatic
+garbage collection yet.
+
+Read these pages for the server-only setup:
+
+- `docs/sandbox/portable-snapshots.md`
+- `docs/sandbox/portable-snapshots-configure.md`
+- `docs/sandbox/portable-snapshots-save.md`
+- `docs/sandbox/portable-snapshots-fork.md`
+- `docs/sandbox/portable-snapshots-artifacts.md`
+- `docs/sandbox/portable-snapshots-tools.md`
+- `docs/sandbox/portable-snapshots-files.md`
+- `docs/sandbox/portable-snapshots-safety.md`
+
+For a user-marked workspace state, call `snapshots.save` on the server. Bind
+`sandbox` and `instances` at create time, or pass them on `save`. The call
+needs `threadId`, `runId`, and a label. It requires a live reusable sandbox.
+`reuse: 'none'` cannot save a named checkpoint.
+
+To branch from a selected checkpoint, call `snapshots.fork` with the thread id,
+checkpoint id, and destination thread id. The store must implement atomic
+`forkFromCheckpoint`. The destination thread must be empty. A fork copies the
+selected snapshot, not the latest snapshot.
+
+To send a checkpoint artifact, call `snapshots.readArtifact` on the server.
+First authorize the caller for the supplied thread. The method makes sure that
+the checkpoint belongs to that thread, then returns its metadata and bytes. It
+does not authorize a caller or create an HTTP response.
+
+For a SQLite checkpoint store, use one transaction for a checkpoint write, its
+head update, and every blob reference update. Use one transaction for a fork,
+including its copied conversation. A partial transaction breaks snapshot
+consistency.
+
+Snapshot capture supports regular files and empty directories only. It excludes
+`.git`, `node_modules`, and `.env*` path segments at every depth. It excludes
+the exact projection marker only at the workspace root. It also excludes root
+`CLAUDE.md` and `GEMINI.md`, plus direct `.claude/skills/<name>`,
+`.codex/skills/<name>`, and `.grok/skills/<name>` paths. These exclusions use
+paths even for regular files or copies. If you pass only `include` or only
+`redact`, the default exclusions stay in place. If you pass `exclude`, that
+function replaces the default exclusions, except for exact projection-marker
+protection. It rejects symlinks, executable files, and special filesystem
+entries. Restore verifies the manifest and blobs before
+it changes a new private sandbox. It never writes into a live resumed sandbox.
+
 ## Providers
 
 - `localProcessSandbox()` — runs on the host (no isolation; dev loop only).
@@ -983,14 +1070,15 @@ including the client `joinRun` side, is in `docs/sandbox/takeover.md`.
 
 - **Harness adapters require a sandbox.** Always include `withSandbox(...)` in
   `middleware` — without it `chat()` throws a missing-capability error.
-- **Secrets** (`workspace.secrets`) are injected into the sandbox env and never
-  persisted (no snapshots, no sandbox store, no event log). Always create them
-  with `createSecrets(...)` so the values stay hidden behind `SecretRef` tokens.
-  The agent binary (`claude`) must exist in the sandbox image (install it in
-  `setup` or bake it into the image).
+- **Secrets** (`workspace.secrets`) are injected into the sandbox env. Their
+  raw values are never persisted in snapshots, the sandbox store, or the event
+  log. Always create them with `createSecrets(...)` so the values stay hidden
+  behind `SecretRef` tokens. The agent binary (`claude`) must exist in the
+  sandbox image (install it in `setup` or bake it into the image).
 - **Secret-bearing projected files** (e.g. MCP config with resolved header
-  values) are re-written on every projection call so rotated secrets re-apply;
-  they are never included in a snapshot.
+  values) can be included by default capture. Capture replaces resolved secret
+  bytes with zero bytes before it hashes or writes snapshot blobs. Restore runs
+  before projection, so projection writes current secret values after restore.
 - **chat()-provided `tools` are bridged** into the in-sandbox agent over a
   host-side MCP tool-proxy: the agent calls them as `mcp__tanstack__<tool>` and
   each call is proxied back to the host where the tool's `execute()` runs (with