@crewhaus/checkpoint-store 0.1.4 → 0.1.6

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+import { CrewhausError } from "@crewhaus/errors";
+export declare const DEFAULT_ROOT_DIR = ".crewhaus/graphs";
+export type GraphRunId = string;
+export type CheckpointId = string;
+export type Checkpoint = {
+    readonly version: 1;
+    readonly id: CheckpointId;
+    readonly graphRunId: GraphRunId;
+    readonly nodeName: string;
+    readonly state: unknown;
+    /** Parent within the same graph run — `undefined` for the entry node. */
+    readonly parentCheckpointId?: CheckpointId;
+    readonly createdAt: string;
+};
+export type BranchInfo = {
+    readonly graphRunId: GraphRunId;
+    readonly checkpointId: CheckpointId;
+};
+export type GraphRunMeta = {
+    readonly version: 1;
+    readonly graphRunId: GraphRunId;
+    /** Most recently saved checkpoint id; absent on a freshly-branched run with no new commits. */
+    head?: CheckpointId;
+    readonly createdAt: string;
+    /** Set when this run was branched from a sibling. */
+    readonly branchedFrom?: BranchInfo;
+};
+export type ListOptions = {
+    /** Cap the number of returned checkpoints (insertion order, oldest first). */
+    readonly limit?: number;
+    /** Skip checkpoints created before this ISO timestamp. */
+    readonly since?: string;
+};
+export interface CheckpointStoreAdapter {
+    save(c: Checkpoint): Promise<void>;
+    load(graphRunId: GraphRunId, checkpointId: CheckpointId): Promise<Checkpoint | undefined>;
+    list(graphRunId: GraphRunId, opts: ListOptions): Promise<ReadonlyArray<Checkpoint>>;
+    loadMeta(graphRunId: GraphRunId): Promise<GraphRunMeta | undefined>;
+    saveMeta(meta: GraphRunMeta): Promise<void>;
+    /** Delete the entire graph run (best-effort; idempotent). */
+    drop(graphRunId: GraphRunId): Promise<void>;
+}
+export interface CheckpointStore {
+    /** Persist a new checkpoint and update the graph run's head. */
+    save(opts: {
+        graphRunId: GraphRunId;
+        nodeName: string;
+        state: unknown;
+        parentCheckpointId?: CheckpointId;
+    }): Promise<Checkpoint>;
+    /** Load a specific checkpoint, or the head when `checkpointId` is omitted. */
+    load(graphRunId: GraphRunId, checkpointId?: CheckpointId): Promise<Checkpoint | undefined>;
+    /** Walk the run's checkpoints in insertion order. */
+    list(graphRunId: GraphRunId, opts?: ListOptions): Promise<ReadonlyArray<Checkpoint>>;
+    /**
+     * Materialise a NEW graph run that starts from `checkpointId` of
+     * `graphRunId`. The head of the new run is a fresh copy of the source
+     * checkpoint and the `_meta.json` records `branchedFrom: { graphRunId,
+     * checkpointId }` for time-travel auditing.
+     */
+    branch(graphRunId: GraphRunId, checkpointId: CheckpointId): Promise<{
+        newGraphRunId: GraphRunId;
+        head: Checkpoint;
+    }>;
+    /** Read the `_meta.json` for `graphRunId`. */
+    meta(graphRunId: GraphRunId): Promise<GraphRunMeta | undefined>;
+    /** Delete a graph run's directory tree. Idempotent. */
+    drop(graphRunId: GraphRunId): Promise<void>;
+}
+export declare class CheckpointStoreError extends CrewhausError {
+    readonly name = "CheckpointStoreError";
+    constructor(message: string, cause?: unknown);
+}
+export declare function newGraphRunId(): GraphRunId;
+export declare function newCheckpointId(): CheckpointId;
+export type CreateCheckpointStoreOptions = {
+    readonly rootDir?: string;
+    readonly adapter?: CheckpointStoreAdapter;
+    readonly now?: () => Date;
+};
+export declare function createCheckpointStore(opts?: CreateCheckpointStoreOptions): CheckpointStore;

package/dist/index.js

@@ -0,0 +1,242 @@
+/**
+ * Catalog R7 `checkpoint-store` — durable, branchable graph-run state.
+ *
+ * One subdirectory per graph run at `<rootDir>/<graphRunId>/`, with one
+ * JSON file per checkpoint (`<checkpointId>.json`) plus a `_meta.json`
+ * pointer that names the current head and the parent run+checkpoint
+ * (when branched). The format mirrors `event-log`'s "schema version
+ * stamped on every record" convention so future migrations can fan out
+ * on `version`.
+ *
+ * Branching: `branch(parentRunId, checkpointId)` creates a NEW
+ * `graphRunId` whose `_meta.json` points to `parentRunId` +
+ * `checkpointId` and whose head is a fresh COPY of the requested
+ * checkpoint. Reads on the new run still work even if the parent run is
+ * later deleted — checkpoint files are duplicated, not aliased — so
+ * long-lived branches are independent.
+ *
+ * Path-traversal defense: every public method validates ids against
+ * stable regexes (`grun_<16hex>`, `ckpt_<16hex>`); anything else throws
+ * `RuntimeError` before the filesystem is touched, mirroring
+ * `session-store`'s pattern.
+ *
+ * Pluggable adapter: callers can substitute a different
+ * `CheckpointStoreAdapter` (SQLite, Postgres, S3) and the
+ * `createCheckpointStore({ adapter })` factory wires it through. The
+ * default adapter is the file-backed implementation in this module.
+ *
+ * Layer R7. Pairs with `graph-engine` (R11) and `branch-history` (R7).
+ */
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { join, resolve } from "node:path";
+import { CrewhausError, RuntimeError } from "@crewhaus/errors";
+import { assertSamePath, currentTenantContext, requireTenant } from "@crewhaus/tenancy";
+export const DEFAULT_ROOT_DIR = ".crewhaus/graphs";
+const GRAPH_RUN_ID_RE = /^grun_[0-9a-f]{16}$/;
+const CHECKPOINT_ID_RE = /^ckpt_[0-9a-f]{16}$/;
+export class CheckpointStoreError extends CrewhausError {
+    name = "CheckpointStoreError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+export function newGraphRunId() {
+    return `grun_${randomBytes(8).toString("hex")}`;
+}
+export function newCheckpointId() {
+    return `ckpt_${randomBytes(8).toString("hex")}`;
+}
+function validateGraphRunId(id) {
+    if (!GRAPH_RUN_ID_RE.test(id)) {
+        throw new RuntimeError(`checkpoint-store: invalid graphRunId "${id}" — expected grun_<16 hex>`);
+    }
+}
+function validateCheckpointId(id) {
+    if (!CHECKPOINT_ID_RE.test(id)) {
+        throw new RuntimeError(`checkpoint-store: invalid checkpointId "${id}" — expected ckpt_<16 hex>`);
+    }
+}
+// ---------------------------------------------------------------------------
+// File-backed adapter — default implementation.
+// ---------------------------------------------------------------------------
+class FileSystemAdapter {
+    rootDir;
+    constructor(rootDir) {
+        this.rootDir = rootDir;
+        mkdirSync(this.rootDir, { recursive: true });
+    }
+    dir(graphRunId) {
+        validateGraphRunId(graphRunId);
+        const dir = join(this.rootDir, graphRunId);
+        // When a tenant context is active, fail closed on a resolved path that
+        // escapes the tenant's sessionRoot (CWE-1230). Every checkpoint/meta path
+        // is built under this directory, so fencing here covers every read/write.
+        // Outside a tenant scope (the common CLI case) this is a no-op so
+        // non-tenant behaviour is unchanged.
+        if (currentTenantContext() !== undefined) {
+            assertSamePath(resolve(dir), requireTenant().sessionRoot);
+        }
+        return dir;
+    }
+    metaPath(graphRunId) {
+        return join(this.dir(graphRunId), "_meta.json");
+    }
+    checkpointPath(graphRunId, checkpointId) {
+        validateCheckpointId(checkpointId);
+        return join(this.dir(graphRunId), `${checkpointId}.json`);
+    }
+    async save(c) {
+        const dir = this.dir(c.graphRunId);
+        mkdirSync(dir, { recursive: true });
+        const tmp = `${this.checkpointPath(c.graphRunId, c.id)}.tmp.${randomBytes(4).toString("hex")}`;
+        writeFileSync(tmp, JSON.stringify(c), { mode: 0o600 });
+        // Atomic rename so concurrent reads never see a half-written file.
+        const final = this.checkpointPath(c.graphRunId, c.id);
+        renameSync(tmp, final);
+    }
+    async load(graphRunId, checkpointId) {
+        const path = this.checkpointPath(graphRunId, checkpointId);
+        if (!existsSync(path))
+            return undefined;
+        const raw = readFileSync(path, "utf8");
+        return JSON.parse(raw);
+    }
+    async list(graphRunId, opts) {
+        const dir = this.dir(graphRunId);
+        if (!existsSync(dir))
+            return [];
+        const files = readdirSync(dir).filter((f) => f.startsWith("ckpt_") && f.endsWith(".json"));
+        // Order by mtime ascending — file-backed adapter has no other notion of insertion order.
+        const withStat = files.map((f) => {
+            const full = join(dir, f);
+            return { name: f, mtimeMs: statSync(full).mtimeMs, full };
+        });
+        withStat.sort((a, b) => a.mtimeMs - b.mtimeMs);
+        const out = [];
+        const sinceTs = opts.since !== undefined ? Date.parse(opts.since) : Number.NEGATIVE_INFINITY;
+        for (const { full } of withStat) {
+            const c = JSON.parse(readFileSync(full, "utf8"));
+            if (Date.parse(c.createdAt) < sinceTs)
+                continue;
+            out.push(c);
+            if (opts.limit !== undefined && out.length >= opts.limit)
+                break;
+        }
+        return out;
+    }
+    async loadMeta(graphRunId) {
+        const path = this.metaPath(graphRunId);
+        if (!existsSync(path))
+            return undefined;
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    async saveMeta(meta) {
+        const dir = this.dir(meta.graphRunId);
+        mkdirSync(dir, { recursive: true });
+        const tmp = `${this.metaPath(meta.graphRunId)}.tmp.${randomBytes(4).toString("hex")}`;
+        writeFileSync(tmp, JSON.stringify(meta), { mode: 0o600 });
+        renameSync(tmp, this.metaPath(meta.graphRunId));
+    }
+    async drop(graphRunId) {
+        const dir = this.dir(graphRunId);
+        if (!existsSync(dir))
+            return;
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+export function createCheckpointStore(opts = {}) {
+    const rootDir = opts.rootDir ?? DEFAULT_ROOT_DIR;
+    const adapter = opts.adapter ?? new FileSystemAdapter(rootDir);
+    const now = opts.now ?? (() => new Date());
+    async function ensureMeta(graphRunId) {
+        const existing = await adapter.loadMeta(graphRunId);
+        if (existing !== undefined)
+            return existing;
+        const meta = {
+            version: 1,
+            graphRunId,
+            createdAt: now().toISOString(),
+        };
+        await adapter.saveMeta(meta);
+        return meta;
+    }
+    return {
+        async save(req) {
+            validateGraphRunId(req.graphRunId);
+            if (req.parentCheckpointId !== undefined)
+                validateCheckpointId(req.parentCheckpointId);
+            if (typeof req.nodeName !== "string" || req.nodeName.length === 0) {
+                throw new CheckpointStoreError("nodeName must be a non-empty string");
+            }
+            const id = newCheckpointId();
+            const cp = {
+                version: 1,
+                id,
+                graphRunId: req.graphRunId,
+                nodeName: req.nodeName,
+                state: req.state,
+                ...(req.parentCheckpointId !== undefined
+                    ? { parentCheckpointId: req.parentCheckpointId }
+                    : {}),
+                createdAt: now().toISOString(),
+            };
+            await adapter.save(cp);
+            const prevMeta = await ensureMeta(req.graphRunId);
+            const meta = { ...prevMeta, head: id };
+            await adapter.saveMeta(meta);
+            return cp;
+        },
+        async load(graphRunId, checkpointId) {
+            validateGraphRunId(graphRunId);
+            let id = checkpointId;
+            if (id === undefined) {
+                const meta = await adapter.loadMeta(graphRunId);
+                if (meta?.head === undefined)
+                    return undefined;
+                id = meta.head;
+            }
+            validateCheckpointId(id);
+            return adapter.load(graphRunId, id);
+        },
+        async list(graphRunId, listOpts = {}) {
+            validateGraphRunId(graphRunId);
+            return adapter.list(graphRunId, listOpts);
+        },
+        async branch(graphRunId, checkpointId) {
+            validateGraphRunId(graphRunId);
+            validateCheckpointId(checkpointId);
+            const source = await adapter.load(graphRunId, checkpointId);
+            if (source === undefined) {
+                throw new CheckpointStoreError(`checkpoint ${checkpointId} not found in graph run ${graphRunId}`);
+            }
+            const branchedRunId = newGraphRunId();
+            const newHead = {
+                version: 1,
+                id: newCheckpointId(),
+                graphRunId: branchedRunId,
+                nodeName: source.nodeName,
+                state: source.state,
+                createdAt: now().toISOString(),
+            };
+            await adapter.save(newHead);
+            const meta = {
+                version: 1,
+                graphRunId: branchedRunId,
+                head: newHead.id,
+                createdAt: newHead.createdAt,
+                branchedFrom: { graphRunId, checkpointId },
+            };
+            await adapter.saveMeta(meta);
+            return { newGraphRunId: branchedRunId, head: newHead };
+        },
+        async meta(graphRunId) {
+            validateGraphRunId(graphRunId);
+            return adapter.loadMeta(graphRunId);
+        },
+        async drop(graphRunId) {
+            validateGraphRunId(graphRunId);
+            await adapter.drop(graphRunId);
+        },
+    };
+}

package/package.json

@@ -1,19 +1,22 @@
 {
   "name": "@crewhaus/checkpoint-store",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "description": "File-backed checkpoint store for graph-engine — save/load/list/branch over per-graph-run JSON files",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.4",
-    "@crewhaus/tenancy": "0.1.4"
+    "@crewhaus/errors": "0.1.6",
+    "@crewhaus/tenancy": "0.1.6"
   },
   "license": "Apache-2.0",
   "author": {
@@ -33,5 +36,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,401 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { RuntimeError } from "@crewhaus/errors";
-import { TenancyError, buildTenant, withTenant } from "@crewhaus/tenancy";
-import {
-  type Checkpoint,
-  type CheckpointStore,
-  type CheckpointStoreAdapter,
-  CheckpointStoreError,
-  type GraphRunId,
-  type GraphRunMeta,
-  type ListOptions,
-  createCheckpointStore,
-  newCheckpointId,
-  newGraphRunId,
-} from "./index";
-
-let tmp: string;
-let store: CheckpointStore;
-
-beforeEach(() => {
-  tmp = mkdtempSync(join(tmpdir(), "checkpoint-store-"));
-  store = createCheckpointStore({ rootDir: tmp });
-});
-
-afterEach(() => {
-  rmSync(tmp, { recursive: true, force: true });
-});
-
-describe("id generators", () => {
-  test("newGraphRunId matches the regex", () => {
-    expect(newGraphRunId()).toMatch(/^grun_[0-9a-f]{16}$/);
-  });
-  test("newCheckpointId matches the regex", () => {
-    expect(newCheckpointId()).toMatch(/^ckpt_[0-9a-f]{16}$/);
-  });
-});
-
-describe("save + load round-trip", () => {
-  test("save returns a Checkpoint with the requested fields", async () => {
-    const grun = newGraphRunId();
-    const cp = await store.save({ graphRunId: grun, nodeName: "plan", state: { foo: 1 } });
-    expect(cp.graphRunId).toBe(grun);
-    expect(cp.nodeName).toBe("plan");
-    expect(cp.state).toEqual({ foo: 1 });
-    expect(cp.id).toMatch(/^ckpt_[0-9a-f]{16}$/);
-    expect(cp.parentCheckpointId).toBeUndefined();
-  });
-
-  test("load returns the saved checkpoint", async () => {
-    const grun = newGraphRunId();
-    const cp = await store.save({ graphRunId: grun, nodeName: "plan", state: { x: 1 } });
-    const loaded = await store.load(grun, cp.id);
-    expect(loaded?.id).toBe(cp.id);
-    expect(loaded?.state).toEqual({ x: 1 });
-  });
-
-  test("load without checkpointId returns the head", async () => {
-    const grun = newGraphRunId();
-    const a = await store.save({ graphRunId: grun, nodeName: "a", state: 1 });
-    const b = await store.save({
-      graphRunId: grun,
-      nodeName: "b",
-      state: 2,
-      parentCheckpointId: a.id,
-    });
-    const head = await store.load(grun);
-    expect(head?.id).toBe(b.id);
-    expect(head?.state).toBe(2);
-  });
-
-  test("load returns undefined for an unknown checkpoint", async () => {
-    const grun = newGraphRunId();
-    const ck = newCheckpointId();
-    expect(await store.load(grun, ck)).toBeUndefined();
-  });
-
-  test("save updates _meta.json head pointer", async () => {
-    const grun = newGraphRunId();
-    const cp = await store.save({ graphRunId: grun, nodeName: "x", state: 1 });
-    const meta = await store.meta(grun);
-    expect(meta?.head).toBe(cp.id);
-  });
-});
-
-describe("list", () => {
-  test("returns checkpoints in insertion order", async () => {
-    const grun = newGraphRunId();
-    const a = await store.save({ graphRunId: grun, nodeName: "a", state: 1 });
-    // small delay so mtime ordering is deterministic
-    await new Promise((r) => setTimeout(r, 10));
-    const b = await store.save({ graphRunId: grun, nodeName: "b", state: 2 });
-    const list = await store.list(grun);
-    expect(list.map((c) => c.id)).toEqual([a.id, b.id]);
-  });
-
-  test("limit caps the list", async () => {
-    const grun = newGraphRunId();
-    await store.save({ graphRunId: grun, nodeName: "a", state: 1 });
-    await new Promise((r) => setTimeout(r, 10));
-    await store.save({ graphRunId: grun, nodeName: "b", state: 2 });
-    const list = await store.list(grun, { limit: 1 });
-    expect(list.length).toBe(1);
-  });
-
-  test("empty list for an unknown graph run", async () => {
-    const grun = newGraphRunId();
-    expect(await store.list(grun)).toEqual([]);
-  });
-});
-
-describe("branch", () => {
-  test("creates a new run with a fresh head copy", async () => {
-    const parentRun = newGraphRunId();
-    const a = await store.save({ graphRunId: parentRun, nodeName: "plan", state: { plan: "foo" } });
-    const b = await store.save({
-      graphRunId: parentRun,
-      nodeName: "execute",
-      state: { result: "bar" },
-      parentCheckpointId: a.id,
-    });
-
-    const { newGraphRunId: child, head } = await store.branch(parentRun, a.id);
-    expect(child).not.toBe(parentRun);
-    expect(child).toMatch(/^grun_[0-9a-f]{16}$/);
-    expect(head.nodeName).toBe("plan");
-    expect(head.state).toEqual({ plan: "foo" });
-    expect(head.id).not.toBe(a.id);
-    expect(head.graphRunId).toBe(child);
-
-    const meta = await store.meta(child);
-    expect(meta?.branchedFrom).toEqual({ graphRunId: parentRun, checkpointId: a.id });
-    expect(meta?.head).toBe(head.id);
-
-    // Parent's head is unchanged.
-    const parentMeta = await store.meta(parentRun);
-    expect(parentMeta?.head).toBe(b.id);
-  });
-
-  test("throws when branching from an unknown checkpoint", async () => {
-    const grun = newGraphRunId();
-    const ck = newCheckpointId();
-    await expect(store.branch(grun, ck)).rejects.toBeInstanceOf(CheckpointStoreError);
-  });
-});
-
-describe("path-traversal defense (T8)", () => {
-  test("rejects malformed graphRunId on save", async () => {
-    await expect(
-      store.save({ graphRunId: "../etc/passwd", nodeName: "a", state: 1 }),
-    ).rejects.toBeInstanceOf(RuntimeError);
-  });
-  test("rejects malformed graphRunId on load", async () => {
-    await expect(store.load("not-a-grun")).rejects.toBeInstanceOf(RuntimeError);
-  });
-  test("rejects malformed graphRunId on list", async () => {
-    await expect(store.list("../etc")).rejects.toBeInstanceOf(RuntimeError);
-  });
-  test("rejects malformed graphRunId on branch (parent)", async () => {
-    await expect(store.branch("../etc", newCheckpointId())).rejects.toBeInstanceOf(RuntimeError);
-  });
-  test("rejects malformed checkpointId on branch", async () => {
-    const grun = newGraphRunId();
-    await store.save({ graphRunId: grun, nodeName: "a", state: 1 });
-    await expect(store.branch(grun, "../../bad")).rejects.toBeInstanceOf(RuntimeError);
-  });
-  test("rejects malformed nodeName on save", async () => {
-    const grun = newGraphRunId();
-    await expect(store.save({ graphRunId: grun, nodeName: "", state: 1 })).rejects.toBeInstanceOf(
-      CheckpointStoreError,
-    );
-  });
-});
-
-describe("drop", () => {
-  test("removes the graph run directory", async () => {
-    const grun = newGraphRunId();
-    await store.save({ graphRunId: grun, nodeName: "a", state: 1 });
-    await store.drop(grun);
-    expect(await store.list(grun)).toEqual([]);
-    expect(await store.meta(grun)).toBeUndefined();
-  });
-
-  test("idempotent on a missing run", async () => {
-    const grun = newGraphRunId();
-    await store.drop(grun);
-    await store.drop(grun);
-  });
-});
-
-describe("stress (T7-lite)", () => {
-  // 500 sequential async fs writes is tight against bun:test's 5 s default
-  // on shared CI runners — observed 5.3 s with 5 s budget. The 15 s budget
-  // gives ~3× headroom without sacrificing the stress shape (still 500
-  // round-trips against real disk).
-  test("saving 500 checkpoints round-trips correctly", async () => {
-    const grun = newGraphRunId();
-    let parent: string | undefined;
-    for (let i = 0; i < 500; i += 1) {
-      const cp = await store.save({
-        graphRunId: grun,
-        nodeName: `n${i}`,
-        state: { i },
-        ...(parent !== undefined ? { parentCheckpointId: parent } : {}),
-      });
-      parent = cp.id;
-    }
-    const list = await store.list(grun);
-    expect(list.length).toBe(500);
-    expect(list[499]?.state).toEqual({ i: 499 });
-  }, 15_000);
-});
-
-describe("cross-tenant fencing (CWE-1230)", () => {
-  test("inside tenantA, a store rooted under tenantB fails closed", async () => {
-    const tenantsRoot = mkdtempSync(join(tmpdir(), "checkpoint-tenants-"));
-    try {
-      const tenantA = buildTenant("tenant-a", { tenantsRoot });
-      const tenantB = buildTenant("tenant-b", { tenantsRoot });
-      // Store rooted under tenantB while tenantA is active — every resolved
-      // graph-run directory escapes tenantA's sessionRoot, so it fails closed.
-      const fenced = createCheckpointStore({ rootDir: tenantB.sessionRoot });
-      await withTenant(tenantA, async () => {
-        const grun = newGraphRunId();
-        await expect(fenced.save({ graphRunId: grun, nodeName: "a", state: 1 })).rejects.toThrow(
-          TenancyError,
-        );
-        await expect(fenced.load(grun)).rejects.toThrow(/cross-tenant access denied/);
-      });
-    } finally {
-      rmSync(tenantsRoot, { recursive: true, force: true });
-    }
-  });
-
-  test("inside tenantA, a store rooted under tenantA round-trips", async () => {
-    const tenantsRoot = mkdtempSync(join(tmpdir(), "checkpoint-tenants-"));
-    try {
-      const tenantA = buildTenant("tenant-a", { tenantsRoot });
-      const ok = createCheckpointStore({ rootDir: tenantA.sessionRoot });
-      await withTenant(tenantA, async () => {
-        const grun = newGraphRunId();
-        const cp = await ok.save({ graphRunId: grun, nodeName: "a", state: { x: 1 } });
-        const loaded = await ok.load(grun, cp.id);
-        expect(loaded?.id).toBe(cp.id);
-      });
-    } finally {
-      rmSync(tenantsRoot, { recursive: true, force: true });
-    }
-  });
-
-  test("no active tenant — behaviour is unchanged (no fencing)", async () => {
-    const grun = newGraphRunId();
-    const cp = await store.save({ graphRunId: grun, nodeName: "a", state: { x: 1 } });
-    const loaded = await store.load(grun, cp.id);
-    expect(loaded?.id).toBe(cp.id);
-  });
-});
-
-describe("list: since filter", () => {
-  // A controllable clock keeps checkpoint timestamps deterministic so the
-  // `since` boundary is exercised without depending on the real wall clock.
-  test("skips checkpoints created strictly before `since`", async () => {
-    const clock = { ms: Date.parse("2026-01-01T00:00:00.000Z") };
-    const clocked = createCheckpointStore({
-      rootDir: tmp,
-      now: () => new Date(clock.ms),
-    });
-    const grun = newGraphRunId();
-
-    const older = await clocked.save({ graphRunId: grun, nodeName: "old", state: 1 });
-    clock.ms += 60_000; // advance one minute
-    const newer = await clocked.save({ graphRunId: grun, nodeName: "new", state: 2 });
-
-    // `since` lands between the two checkpoints: the older one is filtered out
-    // (the `continue` branch), the newer one is kept.
-    const cutoff = new Date(clock.ms - 30_000).toISOString();
-    const list = await clocked.list(grun, { since: cutoff });
-    expect(list.map((c) => c.id)).toEqual([newer.id]);
-    expect(list.map((c) => c.id)).not.toContain(older.id);
-  });
-
-  test("`since` in the future drops everything", async () => {
-    const grun = newGraphRunId();
-    await store.save({ graphRunId: grun, nodeName: "a", state: 1 });
-    const list = await store.list(grun, { since: "2999-01-01T00:00:00.000Z" });
-    expect(list).toEqual([]);
-  });
-});
-
-describe("save: parentCheckpointId validation", () => {
-  test("rejects a malformed parentCheckpointId before any write", async () => {
-    const grun = newGraphRunId();
-    await expect(
-      store.save({ graphRunId: grun, nodeName: "a", state: 1, parentCheckpointId: "../../bad" }),
-    ).rejects.toBeInstanceOf(RuntimeError);
-    // Nothing was persisted for this run.
-    expect(await store.meta(grun)).toBeUndefined();
-  });
-});
-
-describe("pluggable adapter", () => {
-  // A minimal in-memory adapter proves `createCheckpointStore({ adapter })`
-  // wires a non-filesystem backend through every public method, and lets us
-  // reach states the file-backed adapter never produces on its own.
-  function makeMemoryAdapter(): {
-    adapter: CheckpointStoreAdapter;
-    checkpoints: Map<string, Checkpoint>;
-    metas: Map<GraphRunId, GraphRunMeta>;
-  } {
-    const checkpoints = new Map<string, Checkpoint>();
-    const metas = new Map<GraphRunId, GraphRunMeta>();
-    const key = (g: GraphRunId, c: string): string => `${g}/${c}`;
-    const adapter: CheckpointStoreAdapter = {
-      async save(c: Checkpoint): Promise<void> {
-        checkpoints.set(key(c.graphRunId, c.id), c);
-      },
-      async load(g: GraphRunId, c: string): Promise<Checkpoint | undefined> {
-        return checkpoints.get(key(g, c));
-      },
-      async list(g: GraphRunId, _opts: ListOptions): Promise<ReadonlyArray<Checkpoint>> {
-        return [...checkpoints.values()].filter((c) => c.graphRunId === g);
-      },
-      async loadMeta(g: GraphRunId): Promise<GraphRunMeta | undefined> {
-        return metas.get(g);
-      },
-      async saveMeta(m: GraphRunMeta): Promise<void> {
-        metas.set(m.graphRunId, m);
-      },
-      async drop(g: GraphRunId): Promise<void> {
-        metas.delete(g);
-        for (const k of [...checkpoints.keys()]) {
-          if (k.startsWith(`${g}/`)) checkpoints.delete(k);
-        }
-      },
-    };
-    return { adapter, checkpoints, metas };
-  }
-
-  test("save → load → branch → drop all route through the custom adapter", async () => {
-    const { adapter, checkpoints, metas } = makeMemoryAdapter();
-    const custom = createCheckpointStore({ adapter });
-
-    const grun = newGraphRunId();
-    const cp = await custom.save({ graphRunId: grun, nodeName: "plan", state: { a: 1 } });
-    expect(checkpoints.get(`${grun}/${cp.id}`)?.nodeName).toBe("plan");
-    expect(metas.get(grun)?.head).toBe(cp.id);
-
-    expect((await custom.load(grun, cp.id))?.id).toBe(cp.id);
-    expect((await custom.load(grun))?.id).toBe(cp.id);
-
-    const { newGraphRunId: child, head } = await custom.branch(grun, cp.id);
-    expect(metas.get(child)?.branchedFrom).toEqual({ graphRunId: grun, checkpointId: cp.id });
-    expect(head.state).toEqual({ a: 1 });
-
-    await custom.drop(grun);
-    expect(metas.has(grun)).toBe(false);
-    expect(await custom.load(grun, cp.id)).toBeUndefined();
-  });
-
-  test("load without checkpointId returns undefined when meta has no head", async () => {
-    const { adapter, metas } = makeMemoryAdapter();
-    const custom = createCheckpointStore({ adapter });
-    const grun = newGraphRunId();
-    // Seed a meta with no head — a state a freshly-created run can hold before
-    // its first commit. `load(grun)` must short-circuit to undefined.
-    metas.set(grun, { version: 1, graphRunId: grun, createdAt: new Date(0).toISOString() });
-    expect(await custom.load(grun)).toBeUndefined();
-  });
-
-  test("save preserves an existing meta's branchedFrom when advancing head", async () => {
-    const { adapter, metas } = makeMemoryAdapter();
-    const custom = createCheckpointStore({ adapter });
-    const grun = newGraphRunId();
-    const branchedFrom = { graphRunId: newGraphRunId(), checkpointId: newCheckpointId() };
-    // Pre-seed a branched-run meta (head absent), then commit: ensureMeta must
-    // reuse the existing meta so branchedFrom survives the head update.
-    metas.set(grun, {
-      version: 1,
-      graphRunId: grun,
-      createdAt: new Date(0).toISOString(),
-      branchedFrom,
-    });
-    const cp = await custom.save({ graphRunId: grun, nodeName: "n", state: 1 });
-    expect(metas.get(grun)?.head).toBe(cp.id);
-    expect(metas.get(grun)?.branchedFrom).toEqual(branchedFrom);
-  });
-});
-
-describe("CheckpointStoreError", () => {
-  test("carries the config code and serializes its cause chain", () => {
-    const root = new Error("disk gone");
-    const err = new CheckpointStoreError("save failed", root);
-    expect(err).toBeInstanceOf(CheckpointStoreError);
-    expect(err.code).toBe("config");
-    expect(err.name).toBe("CheckpointStoreError");
-    const json = err.toJSON();
-    expect(json.cause).toEqual({ name: "Error", message: "disk gone" });
-  });
-});

package/src/index.ts

@@ -1,351 +0,0 @@
-/**
- * Catalog R7 `checkpoint-store` — durable, branchable graph-run state.
- *
- * One subdirectory per graph run at `<rootDir>/<graphRunId>/`, with one
- * JSON file per checkpoint (`<checkpointId>.json`) plus a `_meta.json`
- * pointer that names the current head and the parent run+checkpoint
- * (when branched). The format mirrors `event-log`'s "schema version
- * stamped on every record" convention so future migrations can fan out
- * on `version`.
- *
- * Branching: `branch(parentRunId, checkpointId)` creates a NEW
- * `graphRunId` whose `_meta.json` points to `parentRunId` +
- * `checkpointId` and whose head is a fresh COPY of the requested
- * checkpoint. Reads on the new run still work even if the parent run is
- * later deleted — checkpoint files are duplicated, not aliased — so
- * long-lived branches are independent.
- *
- * Path-traversal defense: every public method validates ids against
- * stable regexes (`grun_<16hex>`, `ckpt_<16hex>`); anything else throws
- * `RuntimeError` before the filesystem is touched, mirroring
- * `session-store`'s pattern.
- *
- * Pluggable adapter: callers can substitute a different
- * `CheckpointStoreAdapter` (SQLite, Postgres, S3) and the
- * `createCheckpointStore({ adapter })` factory wires it through. The
- * default adapter is the file-backed implementation in this module.
- *
- * Layer R7. Pairs with `graph-engine` (R11) and `branch-history` (R7).
- */
-import { randomBytes } from "node:crypto";
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  renameSync,
-  rmSync,
-  statSync,
-  writeFileSync,
-} from "node:fs";
-import { join, resolve } from "node:path";
-import { CrewhausError, RuntimeError } from "@crewhaus/errors";
-import { assertSamePath, currentTenantContext, requireTenant } from "@crewhaus/tenancy";
-
-export const DEFAULT_ROOT_DIR = ".crewhaus/graphs";
-
-const GRAPH_RUN_ID_RE = /^grun_[0-9a-f]{16}$/;
-const CHECKPOINT_ID_RE = /^ckpt_[0-9a-f]{16}$/;
-
-export type GraphRunId = string;
-export type CheckpointId = string;
-
-export type Checkpoint = {
-  readonly version: 1;
-  readonly id: CheckpointId;
-  readonly graphRunId: GraphRunId;
-  readonly nodeName: string;
-  readonly state: unknown;
-  /** Parent within the same graph run — `undefined` for the entry node. */
-  readonly parentCheckpointId?: CheckpointId;
-  readonly createdAt: string;
-};
-
-export type BranchInfo = {
-  readonly graphRunId: GraphRunId;
-  readonly checkpointId: CheckpointId;
-};
-
-export type GraphRunMeta = {
-  readonly version: 1;
-  readonly graphRunId: GraphRunId;
-  /** Most recently saved checkpoint id; absent on a freshly-branched run with no new commits. */
-  head?: CheckpointId;
-  readonly createdAt: string;
-  /** Set when this run was branched from a sibling. */
-  readonly branchedFrom?: BranchInfo;
-};
-
-export type ListOptions = {
-  /** Cap the number of returned checkpoints (insertion order, oldest first). */
-  readonly limit?: number;
-  /** Skip checkpoints created before this ISO timestamp. */
-  readonly since?: string;
-};
-
-export interface CheckpointStoreAdapter {
-  save(c: Checkpoint): Promise<void>;
-  load(graphRunId: GraphRunId, checkpointId: CheckpointId): Promise<Checkpoint | undefined>;
-  list(graphRunId: GraphRunId, opts: ListOptions): Promise<ReadonlyArray<Checkpoint>>;
-  loadMeta(graphRunId: GraphRunId): Promise<GraphRunMeta | undefined>;
-  saveMeta(meta: GraphRunMeta): Promise<void>;
-  /** Delete the entire graph run (best-effort; idempotent). */
-  drop(graphRunId: GraphRunId): Promise<void>;
-}
-
-export interface CheckpointStore {
-  /** Persist a new checkpoint and update the graph run's head. */
-  save(opts: {
-    graphRunId: GraphRunId;
-    nodeName: string;
-    state: unknown;
-    parentCheckpointId?: CheckpointId;
-  }): Promise<Checkpoint>;
-  /** Load a specific checkpoint, or the head when `checkpointId` is omitted. */
-  load(graphRunId: GraphRunId, checkpointId?: CheckpointId): Promise<Checkpoint | undefined>;
-  /** Walk the run's checkpoints in insertion order. */
-  list(graphRunId: GraphRunId, opts?: ListOptions): Promise<ReadonlyArray<Checkpoint>>;
-  /**
-   * Materialise a NEW graph run that starts from `checkpointId` of
-   * `graphRunId`. The head of the new run is a fresh copy of the source
-   * checkpoint and the `_meta.json` records `branchedFrom: { graphRunId,
-   * checkpointId }` for time-travel auditing.
-   */
-  branch(
-    graphRunId: GraphRunId,
-    checkpointId: CheckpointId,
-  ): Promise<{ newGraphRunId: GraphRunId; head: Checkpoint }>;
-  /** Read the `_meta.json` for `graphRunId`. */
-  meta(graphRunId: GraphRunId): Promise<GraphRunMeta | undefined>;
-  /** Delete a graph run's directory tree. Idempotent. */
-  drop(graphRunId: GraphRunId): Promise<void>;
-}
-
-export class CheckpointStoreError extends CrewhausError {
-  override readonly name = "CheckpointStoreError";
-  constructor(message: string, cause?: unknown) {
-    super("config", message, cause);
-  }
-}
-
-export function newGraphRunId(): GraphRunId {
-  return `grun_${randomBytes(8).toString("hex")}`;
-}
-
-export function newCheckpointId(): CheckpointId {
-  return `ckpt_${randomBytes(8).toString("hex")}`;
-}
-
-function validateGraphRunId(id: string): void {
-  if (!GRAPH_RUN_ID_RE.test(id)) {
-    throw new RuntimeError(`checkpoint-store: invalid graphRunId "${id}" — expected grun_<16 hex>`);
-  }
-}
-
-function validateCheckpointId(id: string): void {
-  if (!CHECKPOINT_ID_RE.test(id)) {
-    throw new RuntimeError(
-      `checkpoint-store: invalid checkpointId "${id}" — expected ckpt_<16 hex>`,
-    );
-  }
-}
-
-// ---------------------------------------------------------------------------
-// File-backed adapter — default implementation.
-// ---------------------------------------------------------------------------
-
-class FileSystemAdapter implements CheckpointStoreAdapter {
-  constructor(private readonly rootDir: string) {
-    mkdirSync(this.rootDir, { recursive: true });
-  }
-
-  private dir(graphRunId: GraphRunId): string {
-    validateGraphRunId(graphRunId);
-    const dir = join(this.rootDir, graphRunId);
-    // When a tenant context is active, fail closed on a resolved path that
-    // escapes the tenant's sessionRoot (CWE-1230). Every checkpoint/meta path
-    // is built under this directory, so fencing here covers every read/write.
-    // Outside a tenant scope (the common CLI case) this is a no-op so
-    // non-tenant behaviour is unchanged.
-    if (currentTenantContext() !== undefined) {
-      assertSamePath(resolve(dir), requireTenant().sessionRoot);
-    }
-    return dir;
-  }
-
-  private metaPath(graphRunId: GraphRunId): string {
-    return join(this.dir(graphRunId), "_meta.json");
-  }
-
-  private checkpointPath(graphRunId: GraphRunId, checkpointId: CheckpointId): string {
-    validateCheckpointId(checkpointId);
-    return join(this.dir(graphRunId), `${checkpointId}.json`);
-  }
-
-  async save(c: Checkpoint): Promise<void> {
-    const dir = this.dir(c.graphRunId);
-    mkdirSync(dir, { recursive: true });
-    const tmp = `${this.checkpointPath(c.graphRunId, c.id)}.tmp.${randomBytes(4).toString("hex")}`;
-    writeFileSync(tmp, JSON.stringify(c), { mode: 0o600 });
-    // Atomic rename so concurrent reads never see a half-written file.
-    const final = this.checkpointPath(c.graphRunId, c.id);
-    renameSync(tmp, final);
-  }
-
-  async load(graphRunId: GraphRunId, checkpointId: CheckpointId): Promise<Checkpoint | undefined> {
-    const path = this.checkpointPath(graphRunId, checkpointId);
-    if (!existsSync(path)) return undefined;
-    const raw = readFileSync(path, "utf8");
-    return JSON.parse(raw) as Checkpoint;
-  }
-
-  async list(graphRunId: GraphRunId, opts: ListOptions): Promise<ReadonlyArray<Checkpoint>> {
-    const dir = this.dir(graphRunId);
-    if (!existsSync(dir)) return [];
-    const files = readdirSync(dir).filter((f) => f.startsWith("ckpt_") && f.endsWith(".json"));
-    // Order by mtime ascending — file-backed adapter has no other notion of insertion order.
-    const withStat = files.map((f) => {
-      const full = join(dir, f);
-      return { name: f, mtimeMs: statSync(full).mtimeMs, full };
-    });
-    withStat.sort((a, b) => a.mtimeMs - b.mtimeMs);
-    const out: Checkpoint[] = [];
-    const sinceTs = opts.since !== undefined ? Date.parse(opts.since) : Number.NEGATIVE_INFINITY;
-    for (const { full } of withStat) {
-      const c = JSON.parse(readFileSync(full, "utf8")) as Checkpoint;
-      if (Date.parse(c.createdAt) < sinceTs) continue;
-      out.push(c);
-      if (opts.limit !== undefined && out.length >= opts.limit) break;
-    }
-    return out;
-  }
-
-  async loadMeta(graphRunId: GraphRunId): Promise<GraphRunMeta | undefined> {
-    const path = this.metaPath(graphRunId);
-    if (!existsSync(path)) return undefined;
-    return JSON.parse(readFileSync(path, "utf8")) as GraphRunMeta;
-  }
-
-  async saveMeta(meta: GraphRunMeta): Promise<void> {
-    const dir = this.dir(meta.graphRunId);
-    mkdirSync(dir, { recursive: true });
-    const tmp = `${this.metaPath(meta.graphRunId)}.tmp.${randomBytes(4).toString("hex")}`;
-    writeFileSync(tmp, JSON.stringify(meta), { mode: 0o600 });
-    renameSync(tmp, this.metaPath(meta.graphRunId));
-  }
-
-  async drop(graphRunId: GraphRunId): Promise<void> {
-    const dir = this.dir(graphRunId);
-    if (!existsSync(dir)) return;
-    rmSync(dir, { recursive: true, force: true });
-  }
-}
-
-export type CreateCheckpointStoreOptions = {
-  readonly rootDir?: string;
-  readonly adapter?: CheckpointStoreAdapter;
-  readonly now?: () => Date;
-};
-
-export function createCheckpointStore(opts: CreateCheckpointStoreOptions = {}): CheckpointStore {
-  const rootDir = opts.rootDir ?? DEFAULT_ROOT_DIR;
-  const adapter = opts.adapter ?? new FileSystemAdapter(rootDir);
-  const now = opts.now ?? ((): Date => new Date());
-
-  async function ensureMeta(graphRunId: GraphRunId): Promise<GraphRunMeta> {
-    const existing = await adapter.loadMeta(graphRunId);
-    if (existing !== undefined) return existing;
-    const meta: GraphRunMeta = {
-      version: 1,
-      graphRunId,
-      createdAt: now().toISOString(),
-    };
-    await adapter.saveMeta(meta);
-    return meta;
-  }
-
-  return {
-    async save(req): Promise<Checkpoint> {
-      validateGraphRunId(req.graphRunId);
-      if (req.parentCheckpointId !== undefined) validateCheckpointId(req.parentCheckpointId);
-      if (typeof req.nodeName !== "string" || req.nodeName.length === 0) {
-        throw new CheckpointStoreError("nodeName must be a non-empty string");
-      }
-      const id = newCheckpointId();
-      const cp: Checkpoint = {
-        version: 1,
-        id,
-        graphRunId: req.graphRunId,
-        nodeName: req.nodeName,
-        state: req.state,
-        ...(req.parentCheckpointId !== undefined
-          ? { parentCheckpointId: req.parentCheckpointId }
-          : {}),
-        createdAt: now().toISOString(),
-      };
-      await adapter.save(cp);
-      const prevMeta = await ensureMeta(req.graphRunId);
-      const meta: GraphRunMeta = { ...prevMeta, head: id };
-      await adapter.saveMeta(meta);
-      return cp;
-    },
-    async load(graphRunId, checkpointId): Promise<Checkpoint | undefined> {
-      validateGraphRunId(graphRunId);
-      let id = checkpointId;
-      if (id === undefined) {
-        const meta = await adapter.loadMeta(graphRunId);
-        if (meta?.head === undefined) return undefined;
-        id = meta.head;
-      }
-      validateCheckpointId(id);
-      return adapter.load(graphRunId, id);
-    },
-    async list(graphRunId, listOpts = {}): Promise<ReadonlyArray<Checkpoint>> {
-      validateGraphRunId(graphRunId);
-      return adapter.list(graphRunId, listOpts);
-    },
-    async branch(
-      graphRunId,
-      checkpointId,
-    ): Promise<{
-      newGraphRunId: GraphRunId;
-      head: Checkpoint;
-    }> {
-      validateGraphRunId(graphRunId);
-      validateCheckpointId(checkpointId);
-      const source = await adapter.load(graphRunId, checkpointId);
-      if (source === undefined) {
-        throw new CheckpointStoreError(
-          `checkpoint ${checkpointId} not found in graph run ${graphRunId}`,
-        );
-      }
-      const branchedRunId = newGraphRunId();
-      const newHead: Checkpoint = {
-        version: 1,
-        id: newCheckpointId(),
-        graphRunId: branchedRunId,
-        nodeName: source.nodeName,
-        state: source.state,
-        createdAt: now().toISOString(),
-      };
-      await adapter.save(newHead);
-      const meta: GraphRunMeta = {
-        version: 1,
-        graphRunId: branchedRunId,
-        head: newHead.id,
-        createdAt: newHead.createdAt,
-        branchedFrom: { graphRunId, checkpointId },
-      };
-      await adapter.saveMeta(meta);
-      return { newGraphRunId: branchedRunId, head: newHead };
-    },
-    async meta(graphRunId): Promise<GraphRunMeta | undefined> {
-      validateGraphRunId(graphRunId);
-      return adapter.loadMeta(graphRunId);
-    },
-    async drop(graphRunId): Promise<void> {
-      validateGraphRunId(graphRunId);
-      await adapter.drop(graphRunId);
-    },
-  };
-}