@sema-ai/core 1.275.1

package/dist/stores/file/checkpoint-store.js

@@ -0,0 +1,250 @@
+import { join } from "node:path";
+import { CheckpointError, summarizeCheckpoint, validatePendingSteer, winnerFromOutcome, } from "../../core/checkpoint-store.js";
+import { AppendLog, atomicWriteFile, ensureDir, readJsonlRecords } from "./fs-atomic.js";
+export class FileCheckpointStore {
+    dir;
+    tmpDir;
+    ledgerPath;
+    snapshotPath;
+    fsyncEnabled;
+    compactEvery;
+    /** Authoritative in-memory state (replayed at boot). The CAS reads/writes THIS; disk is the durable log. */
+    cps = new Map();
+    /** Per-token async mutex chain (identical shape to `TtlSessionStore.pending`). */
+    locks = new Map();
+    /** Number of events appended to the live ledger since the last compaction (drives auto-compaction). */
+    ledgerEvents = 0;
+    log;
+    /** One-shot crash fault (mirrors `InMemoryCheckpointStore.testInjectFault`). */
+    fault = null;
+    constructor(root, opts = {}) {
+        this.dir = join(root, "checkpoints");
+        this.tmpDir = join(root, "tmp");
+        this.ledgerPath = join(this.dir, "checkpoints.jsonl");
+        this.snapshotPath = join(this.dir, "checkpoints.snapshot.jsonl");
+        this.fsyncEnabled = opts.fsync !== false;
+        this.compactEvery = opts.compactEvery ?? 1000;
+        ensureDir(this.dir);
+        ensureDir(this.tmpDir);
+        this.replay();
+        this.log = new AppendLog(this.ledgerPath);
+    }
+    /** Rebuild the authoritative map: snapshot first (the compacted base), then the live ledger's events. */
+    replay() {
+        for (const snap of readJsonlRecords(this.snapshotPath)) {
+            this.cps.set(snap.token, snap);
+        }
+        const events = readJsonlRecords(this.ledgerPath);
+        this.ledgerEvents = events.length;
+        for (const ev of events)
+            this.applyEvent(ev);
+    }
+    /** Fold one ledger event into the authoritative map (last-writer-wins by event order). */
+    applyEvent(ev) {
+        if (ev.t === "put") {
+            this.cps.set(ev.token, ev.cp);
+            return;
+        }
+        const cp = this.cps.get(ev.token);
+        if (!cp)
+            return; // an event for an unknown/pruned token — ignore (snapshot may post-date a put)
+        switch (ev.t) {
+            case "resolve":
+                cp.status = "resolved";
+                cp.rev = ev.rev;
+                cp.resolvedOutcome = ev.resolvedOutcome;
+                cp.reopenReason = undefined;
+                break;
+            case "reopen":
+                cp.status = "pending";
+                cp.rev = ev.rev;
+                cp.reopenReason = ev.reason;
+                // resolvedOutcome PRESERVED across reopen (an env_failed re-resume must replay it).
+                break;
+            case "expire":
+                cp.status = "expired";
+                break;
+            case "steer":
+                cp.state.pendingSteer = ev.steer;
+                break;
+        }
+    }
+    /**
+     * Serialize an op behind any in-flight op on the same token (the in-process per-token async mutex — the
+     * SAME `Map<token, Promise>` chain shape as `TtlSessionStore.pending`). Each call appends a new tail to the
+     * chain; the next caller awaits THIS op before running. A prior op's rejection never blocks the chain
+     * (we await it `.catch`-guarded). The chain entry is GC'd once it is the settled tail (no op queued after).
+     */
+    withLock(token, fn) {
+        const prev = this.locks.get(token) ?? Promise.resolve();
+        // The new tail resolves only after `fn` settles (success OR failure) — so the next op waits for us.
+        const run = prev.then(() => fn(), () => fn());
+        // Store a never-rejecting tail so a future op can `await` it without inheriting our error.
+        const tail = run.then(() => { }, () => { });
+        this.locks.set(token, tail);
+        // Prune the chain entry once it is the settled tail with nothing queued behind it.
+        void tail.then(() => {
+            if (this.locks.get(token) === tail)
+                this.locks.delete(token);
+        });
+        return run;
+    }
+    /** Commit one ledger event (append + fsync) THEN flip the in-memory map (crash-safe ordering, §2.4). */
+    commit(ev, fsync) {
+        this.log.append(ev, fsync); // durable FIRST
+        this.applyEvent(ev); // in-memory flip AFTER the fsync'd append
+        this.ledgerEvents++;
+        if (this.ledgerEvents >= this.compactEvery)
+            this.compact();
+    }
+    async put(token, cp) {
+        return this.withLock(token, () => {
+            // Create-once predicate, identical to InMemory: a reused token must never clobber a live suspension.
+            if (this.cps.has(token)) {
+                throw new CheckpointError("checkpoint.already_exists", `checkpoint token already exists`);
+            }
+            // Defensive deep copy so a later mutation of the caller's object can't corrupt the persisted row,
+            // and so the ledger event holds a snapshot (matches InMemory's structuredClone on put).
+            const stored = structuredClone(cp);
+            this.commit({ t: "put", token, cp: stored }, this.fsyncEnabled);
+        });
+    }
+    async get(token) {
+        const cp = this.cps.get(token);
+        return cp ? structuredClone(cp) : null;
+    }
+    async resolve(token, scope, outcome, expect) {
+        return this.withLock(token, () => {
+            if (this.fault === "resolve-before-commit") {
+                this.fault = null;
+                throw new Error("injected fault: resolve before commit");
+            }
+            const cp = this.cps.get(token);
+            // CAS predicate IDENTICAL to InMemory (`checkpoint-store.ts:1040`): scope in the WHERE for
+            // multi-tenant isolation; only a still-`pending` row can flip.
+            if (!cp || cp.scope !== scope || cp.status !== "pending") {
+                return false;
+            }
+            // OCC guard, evaluated atomically with the CAS (design/80 D-1): a concurrent resolve/reopen cycle
+            // that bumped `rev` in the caller's get→resolve window loses (fail-closed). `rev`, not `reopenReason`
+            // — a 2-valued enum can ABA back to a prior value while the winner changed (round-2 BLOCKER fix).
+            if (expect !== undefined && (cp.rev ?? 0) !== expect.rev) {
+                return false;
+            }
+            const winner = winnerFromOutcome(outcome);
+            const rev = (cp.rev ?? 0) + 1;
+            // COMMIT POINT — append + fsync the resolve event BEFORE the in-memory flip (so a crash can never
+            // leave "memory resolved, disk pending"). The checkpoint commit ALWAYS fsyncs regardless of config.
+            this.commit({ t: "resolve", token, rev, resolvedOutcome: winner }, true);
+            if (this.fault === "resolve-after-commit") {
+                // The CAS is now committed (status → resolved on disk + memory); a crash here must NOT re-execute —
+                // a retry sees `resolved` and returns false. Mirrors the InMemory fault semantics.
+                this.fault = null;
+                throw new Error("injected fault: resolve after commit");
+            }
+            return true;
+        });
+    }
+    async reopen(token, scope, reason) {
+        return this.withLock(token, () => {
+            const cp = this.cps.get(token);
+            // Inverse CAS resolved→pending; scope in the WHERE (identical to InMemory `:1072`).
+            if (!cp || cp.scope !== scope || cp.status !== "resolved") {
+                return false;
+            }
+            const rev = (cp.rev ?? 0) + 1;
+            this.commit({ t: "reopen", token, rev, reason }, true);
+            return true;
+        });
+    }
+    async setPendingSteer(token, scope, steer) {
+        // §3 inv #2: validate FIRST, BEFORE the row lookup (reuse the shared helper verbatim) — a dirty steer is
+        // rejected (typed `steering.invalid_content`) even on a missing/resolved checkpoint, byte-identically to
+        // InMemory (`:1090`). The validation is pure → no need to take the lock for it.
+        const clean = validatePendingSteer(steer);
+        return this.withLock(token, () => {
+            const cp = this.cps.get(token);
+            // Scope in the WHERE + only a still-`pending` checkpoint can be steered (§3 inv #6). No status flip:
+            // a steer is GUIDANCE, never an approval (§3 inv #4).
+            if (!cp || cp.scope !== scope || cp.status !== "pending") {
+                return false;
+            }
+            // Last-writer-wins on a still-pending row (idempotent-safe). Steer is guidance → fsync per config.
+            this.commit({ t: "steer", token, steer: clean }, this.fsyncEnabled);
+            return true;
+        });
+    }
+    async expire(token, scope) {
+        return this.withLock(token, () => {
+            const cp = this.cps.get(token);
+            // Scope in the WHERE + only a `pending` row flips → mutually exclusive with `resolve` on the same row
+            // (the per-token mutex serializes them, exactly as the DB serializes the Pg conditional UPDATE).
+            if (!cp || cp.scope !== scope || cp.status !== "pending") {
+                return false;
+            }
+            this.commit({ t: "expire", token }, true);
+            return true;
+        });
+    }
+    async reap(scope, cutoff) {
+        // Scan the map for matching pending past-deadline rows, expire each under its own token lock so the
+        // expire races `resolve`/`expire(token)` correctly (the same fence-then-reap serialization).
+        let n = 0;
+        const candidates = [...this.cps.values()].filter((cp) => cp.scope === scope && cp.status === "pending" && cp.deadline !== undefined && cp.deadline <= cutoff);
+        for (const cp of candidates) {
+            const won = await this.withLock(cp.token, () => {
+                const live = this.cps.get(cp.token);
+                // Re-check under the lock (a concurrent resolve may have consumed it since the scan).
+                if (!live || live.scope !== scope || live.status !== "pending")
+                    return false;
+                if (live.deadline === undefined || live.deadline > cutoff)
+                    return false;
+                this.commit({ t: "expire", token: cp.token }, true);
+                return true;
+            });
+            if (won)
+                n++;
+        }
+        return n;
+    }
+    async listByScope(scope) {
+        // design/80 assistant-scheduler seam #1: READ-ONLY query over the authoritative replayed map. The PENDING
+        // predicate is byte-for-byte the resolve CAS's (`cp.scope === scope && cp.status === 'pending'`), so the
+        // list reflects exactly the still-resumable rows. No per-token lock, no mutation, NO commit/fsync (a query
+        // never touches the once-only CAS); `summarizeCheckpoint` is the shared projection (anti-drift with InMemory).
+        const out = [];
+        for (const cp of this.cps.values()) {
+            if (cp.scope === scope && cp.status === "pending")
+                out.push(summarizeCheckpoint(cp));
+        }
+        return out;
+    }
+    /** Rewrite the snapshot from the current authoritative map (atomic) and truncate the live ledger. After
+     *  this, `replay` reads the full state from the snapshot alone — the round-trip is identical. */
+    compact() {
+        const lines = [...this.cps.values()].map((cp) => JSON.stringify(cp)).join("\n");
+        atomicWriteFile(this.tmpDir, this.snapshotPath, lines.length ? `${lines}\n` : "");
+        // Truncate the live ledger: a fresh empty O_APPEND handle (the snapshot now holds all state).
+        this.log.close();
+        atomicWriteFile(this.tmpDir, this.ledgerPath, ""); // atomic replace → empty ledger
+        this.log = new AppendLog(this.ledgerPath);
+        this.ledgerEvents = 0;
+    }
+    /** Force a compaction now (test/inspection). */
+    compactNow() {
+        this.compact();
+    }
+    /** Arm a one-shot fault on the next `resolve` (mirrors InMemory `testInjectFault`, council #5). */
+    testInjectFault(mode) {
+        this.fault = mode;
+    }
+    /** Test/inspection helper: number of stored checkpoints. */
+    get size() {
+        return this.cps.size;
+    }
+    /** Release the append handle (best-effort). The boot LOCK is released by the backend factory. */
+    close() {
+        this.log.close();
+    }
+}
+//# sourceMappingURL=checkpoint-store.js.map

package/dist/stores/file/checkpoint-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-store.js","sourceRoot":"","sources":["../../../src/stores/file/checkpoint-store.ts"],"names":[],"mappings":"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"}

package/dist/stores/file/file-snapshot-store.d.ts

@@ -0,0 +1,43 @@
+import type { ExecutionEnv } from "../../internal/harness.js";
+import { type FileSnapshotBounds, type FileSnapshotResult, type FileSnapshotStore } from "../../core/file-snapshot-store.js";
+/**
+ * design/101 §E19 — file-backed {@link FileSnapshotStore} for the local (TOC) backend: content-addressed blobs
+ * on disk + ONE manifest file per `(scope, key)`. Semantics **byte-for-byte identical to
+ * `InMemoryFileSnapshotStore`** (the cross-backend equivalence contract) — it REUSES core's `captureManifest`/
+ * `applyManifest`, so the security-critical convergence (symlink-ancestor neutralization, remove-before-write,
+ * fail-closed) can NEVER drift from the InMemory reference.
+ *
+ * On-disk layout under `<root>/file-snapshots/`:
+ *  - `blobs/<sha256>` — write-ONCE content-addressed blob (an EEXIST is a dedup no-op; shared across all keys).
+ *  - `manifests/<sanitizeScope(scope)>/<key>.json` — a JSON array of `[relPath, sha256]` pairs.
+ *
+ * Atomicity: single-process (the `FileStorageBackend` boot lock); an `inFlight` set guards create-once against
+ * two concurrent `snapshot()`s for the same key. A blob is published atomically (write-then-link); a manifest is
+ * written ONLY after the full capture succeeds (fail-closed — never a partial manifest). Cross-replica durable
+ * snapshots are the Pg/TiDB/object-store backend's job.
+ */
+export declare class FileFileSnapshotStore implements FileSnapshotStore {
+    private readonly base;
+    private readonly blobsDir;
+    private readonly manifestsDir;
+    private readonly inFlight;
+    private readonly bounds;
+    constructor(root: string, bounds?: Partial<FileSnapshotBounds>);
+    private scopeDir;
+    private manifestPath;
+    /** manifestPath, but a key that fails the strict path-component guard → null (so the seam's NEVER-throw
+     *  contract holds for a direct SDK caller; engine keys are uuidv7 so this never fires in practice). */
+    private tryManifestPath;
+    private blobPath;
+    private readManifest;
+    snapshot(scope: string, key: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileSnapshotResult>;
+    restore(scope: string, key: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileSnapshotResult>;
+    listKeys(scope: string): Promise<string[]>;
+    has(scope: string, key: string): Promise<boolean>;
+    exportManifest(scope: string, key: string): Promise<Map<string, string> | null>;
+    getBlob(hash: string): Promise<Uint8Array | undefined>;
+    putBlob(hash: string, bytes: Uint8Array): Promise<FileSnapshotResult>;
+    importManifest(scope: string, key: string, manifest: Map<string, string>, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>): Promise<FileSnapshotResult>;
+    reap(scope: string, keepKeys: string[]): Promise<number>;
+}
+//# sourceMappingURL=file-snapshot-store.d.ts.map

package/dist/stores/file/file-snapshot-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-snapshot-store.d.ts","sourceRoot":"","sources":["../../../src/stores/file/file-snapshot-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAIL,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACvB,MAAM,mCAAmC,CAAC;AAG3C;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,qBAAsB,YAAW,iBAAiB;IAC7D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAGtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;gBAEhC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC;IAa9D,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,YAAY;IAKpB;2GACuG;IACvG,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,YAAY;IAmBd,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0CxH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAevH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAiB1C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKjD,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAK/E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAQtD,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAgBrE,cAAc,CAClB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC7B,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,GAC5D,OAAO,CAAC,kBAAkB,CAAC;IA2DxB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;CAuE/D"}