@sema-ai/core 1.275.1

package/dist/stores/file/fs-atomic.js

@@ -0,0 +1,415 @@
+import { closeSync, constants as FS, existsSync, linkSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync, writeSync, fsyncSync, } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+/**
+ * design/80 §2 — the file-backend's two write primitives + boot guard, shared by all four file stores.
+ *
+ * The whole file backend is selected purely by injecting the four stores into `RunnerDeps` (no engine
+ * change). This module owns the crash-safety mechanics every store leans on:
+ *  - {@link atomicWriteFile} — the 5-step whole-file replace (write-temp → fsync data → rename → fsync dir).
+ *  - {@link AppendLog} — an `O_APPEND` JSONL handle whose torn-tail recovery ({@link readJsonlRecords}) makes
+ *    a crash never corrupt the store (the trailing torn line is discarded; everything before it is intact).
+ *  - {@link sanitizePathComponent} / {@link sanitizeScope} — path-component hygiene (defense-in-depth; a
+ *    model-influenced scope is the one untrusted key).
+ *  - {@link resolveDataRoot} — `$AGENT_DATA_DIR ?? ~/.ai-agent`, NFC-normalized + realpath-canonicalized.
+ *  - {@link BootLock} — the SINGLE coarse advisory lock (an `O_EXCL` PID file with a stale-PID prune) that
+ *    forbids two processes sharing a data dir → fail fast. **The only legitimate file lock here** (§2.4):
+ *    the once-only CAS is in-process (one event loop), so there is NO per-operation flock.
+ *
+ * `fsync` is plain (Node can't reach `F_FULLFSYNC`). Durable across an app crash / SIGKILL (the realistic
+ * threat) — NOT across sudden power loss mid-write on APFS. This is exactly CC's bar (§7 decision 3).
+ */
+/** Strict allow-list for a single path component (engine-minted ids are already safe; this is a backstop). */
+const SAFE_COMPONENT = /^[A-Za-z0-9_.-]+$/;
+/**
+ * Validate an engine-minted id (sessionId / tool-result ref) before using it as a path component. These are
+ * `uuidv7` / `tr_<sessionId>_<toolCallId>` — already filename-safe — but a strict guard is cheap
+ * defense-in-depth: reject `.`/`..`/empty/separators so nothing can traverse out of the store dir.
+ */
+export function sanitizePathComponent(raw) {
+    if (raw === "" || raw === "." || raw === ".." || !SAFE_COMPONENT.test(raw)) {
+        throw new Error(`file store: unsafe path component ${JSON.stringify(raw)}`);
+    }
+    return raw;
+}
+/**
+ * Map a model-influenced memory `scope` to a safe directory name (CC `sanitizePath` parity). Replace every
+ * non-alphanumeric run with `-`; if the result is over 200 chars, append a short content hash so two long
+ * scopes can't collide. The ORIGINAL scope is the partition key the engine passes — this only affects the
+ * on-disk dir name, never the stored data. Never `path.join` a raw scope.
+ */
+export function sanitizeScope(scope) {
+    const base = scope.replace(/[^A-Za-z0-9]/g, "-");
+    // ALWAYS append a short content hash of the RAW scope so the mapping is INJECTIVE — `a:b` and `a/b` both
+    // base-map to `a-b` but must get DISTINCT dirs (codex review BUG-2: a colliding scope key cross-leaks memory;
+    // the on-disk dir is the authoritative partition and the notes log does not re-store the raw scope).
+    // The FULL sha256 of the RAW scope makes the dir name COLLISION-FREE in practice (codex review r2 BUG-2: a
+    // 12-char 32-bit hash collides → distinct scopes share a dir → cross-scope memory leak). The readable base
+    // prefix (capped) only aids debugging; the 64-hex 256-bit digest is the injective key.
+    return `${(base || "_").slice(0, 120)}-${createHash("sha256").update(scope, "utf8").digest("hex")}`;
+}
+/**
+ * Resolve the data root (CC `getClaudeConfigHomeDir` analog): `$AGENT_DATA_DIR ?? ~/.ai-agent`,
+ * NFC-normalized, and `realpath`-canonicalized once the dir exists. Creates the dir (0o700) if absent.
+ */
+export function resolveDataRoot(explicit) {
+    const raw = (explicit ?? process.env.AGENT_DATA_DIR ?? join(homedir(), ".ai-agent")).normalize("NFC");
+    mkdirSync(raw, { recursive: true, mode: 0o700 });
+    // realpath only after the dir exists (resolves symlinks so the `tmp` dir is provably on the same FS).
+    return realpathSync(raw);
+}
+/** Ensure a directory exists with 0o700 perms (idempotent). */
+/**
+ * Atomically CREATE `target` carrying `content` — it appears in ONE step already fully written, no empty/partial
+ * window. Fixes the create-then-write race (codex review BUG-1/BUG-3): a reader/pruner can see a half-written
+ * file, and a crash mid-write leaves a zero-byte target a retry would silently keep. Writes a temp in `target`'s
+ * OWN dir (same FS → `link` is atomic) + fsync, then `linkSync`-publishes it; throws `EEXIST` if `target` exists.
+ */
+export function writeThenLink(target, content) {
+    ensureDir(dirnameOf(target));
+    const tmp = `${target}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+    let linked = false;
+    try {
+        const fd = openSync(tmp, FS.O_CREAT | FS.O_EXCL | FS.O_WRONLY, 0o600);
+        try {
+            // writeFileSync (NOT bare writeSync) LOOPS until every byte is flushed — `writeSync(fd, x)` issues a single
+            // write(2) and silently SHORT-WRITES (codex/Opus review B1): a partial write would publish a blob whose
+            // filename is the sha256 of the FULL content but whose bytes are truncated = a permanent content-address
+            // lie. `writeFileSync` accepts string|Uint8Array, exactly like `atomicWriteFile` uses.
+            writeFileSync(fd, content);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        linkSync(tmp, target); // atomic publish — throws EEXIST if target already exists
+        linked = true;
+    }
+    finally {
+        // Always drop the temp — on success the link holds the inode; on ANY failure (write/fsync/close/EEXIST) this
+        // cleans the orphan temp so it can never leak (codex review r2 BUG-1: cleanup was only post-link).
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    if (linked)
+        fsyncDir(dirnameOf(target)); // persist the link itself
+}
+export function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+/**
+ * The 5-step atomic whole-file replace (§2.1). Skipping any of steps 3/5/6 is the classic corruption bug:
+ *  1. open a temp under `root/tmp/` (same FS → rename is atomic),
+ *  2. write the bytes,
+ *  3. fsync the DATA (else ext4 "zero-length file after crash"),
+ *  4. close → rename(tmp, target) (atomic intra-FS namespace swap),
+ *  5. fsync the containing DIRECTORY (persists the rename itself).
+ * On any failure the temp is unlinked so a crashed write leaves no scratch behind.
+ */
+export function atomicWriteFile(tmpDir, target, bytes) {
+    ensureDir(tmpDir);
+    const tmp = join(tmpDir, `${basenameOf(target)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    let fd;
+    try {
+        fd = openSync(tmp, "w", 0o600);
+        writeFileSync(fd, bytes);
+        fsyncSync(fd); // step 3 — fsync data
+        closeSync(fd);
+        fd = undefined;
+        renameSync(tmp, target); // step 4 — atomic swap
+        fsyncDir(dirnameOf(target)); // step 5 — persist the rename
+    }
+    catch (err) {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* already closing */
+            }
+        }
+        try {
+            if (existsSync(tmp))
+                unlinkSync(tmp);
+        }
+        catch {
+            /* best-effort scratch cleanup */
+        }
+        throw err;
+    }
+}
+/** fsync a directory entry so a rename/create in it is itself durable (best-effort: some platforms reject
+ *  opening a dir, in which case the rename is still namespace-atomic, just not directory-fsync'd). */
+function fsyncDir(dir) {
+    let dfd;
+    try {
+        dfd = openSync(dir, "r");
+        fsyncSync(dfd);
+    }
+    catch {
+        /* directory fsync not supported on this platform — rename remains atomic */
+    }
+    finally {
+        if (dfd !== undefined) {
+            try {
+                closeSync(dfd);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}
+// channel [380] (service win32 真机逮): these were hand-written POSIX-only (`lastIndexOf("/")`) — on
+// Windows `C:\sema\...` has no `/`, so dirnameOf returned `/`, ensureDir tried `mkdir C:\` → EPERM on
+// the FIRST atomic write = every File store dead on Windows boot. `node:path` is platform-correct
+// (same fix swept onto basenameOf — identical hand-rolled class).
+function basenameOf(p) {
+    return basename(p);
+}
+function dirnameOf(p) {
+    return dirname(p);
+}
+/**
+ * Read a JSONL file and return every COMPLETE, parseable record — the universal torn-tail recovery (§2.2):
+ *  - a trailing line with no terminating `\n` (a crash mid-write) is discarded,
+ *  - any line (interior or tail) that fails `JSON.parse` is skipped (never throws — `listRemoteAgentMetadata`
+ *    parity), so a single corrupt interior line never poisons the whole replay.
+ * A missing file → `[]`. This is why JSONL beats one big JSON blob: a torn tail can never corrupt the store.
+ */
+export function readJsonlRecords(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    if (raw === "")
+        return [];
+    // Split on newline. The LAST element is a complete record iff `raw` ended with `\n` (then it is ""); an
+    // unterminated tail leaves a non-empty last element that we drop as torn.
+    const parts = raw.split("\n");
+    // The last element is "" iff `raw` ended with "\n" (a clean record boundary); a non-empty last element is an
+    // unterminated TORN tail (a partial write) we drop. Interior / clean-trailing "" lines carry no record.
+    const endedClean = parts[parts.length - 1] === "";
+    const out = [];
+    for (let i = 0; i < parts.length; i++) {
+        if (i === parts.length - 1 && !endedClean)
+            break; // drop the unterminated torn tail
+        const line = parts[i];
+        if (line === "")
+            continue; // a blank/`""` line (incl. the clean trailing one) carries no record
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // Skip a corrupt interior line (tolerate, never throw) — CC `listRemoteAgentMetadata` parity.
+        }
+    }
+    return out;
+}
+/**
+ * An append-only JSONL log opened once with `O_APPEND` and held for the file's lifetime. One record =
+ * one `JSON.stringify(...) + "\n"` written in a SINGLE `writeSync` call (never split across writes → the
+ * only torn line possible is a crash tail, which {@link readJsonlRecords} drops). `fsync` is opt-in per
+ * append (the checkpoint commit point ALWAYS fsyncs; session/memory cadence is the caller's `fsyncEvery`).
+ */
+export class AppendLog {
+    fd;
+    constructor(path) {
+        ensureDir(dirnameOf(path));
+        this.fd = openSync(path, "a", 0o600); // O_APPEND — every write goes to EOF atomically
+    }
+    /** Append one record (single write of `json + "\n"`). `fsync:true` makes the record durable before return. */
+    append(record, fsync) {
+        const line = `${JSON.stringify(record)}\n`;
+        writeSync(this.fd, line); // single write → no interior torn line
+        if (fsync)
+            fsyncSync(this.fd);
+    }
+    close() {
+        try {
+            closeSync(this.fd);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+/**
+ * The SINGLE coarse boot guard (§2.4): an `O_EXCL` PID file at `root/LOCK` that forbids two processes
+ * sharing a data dir. A second instance fails fast ("another instance owns this data dir"). A STALE lock
+ * (the writing PID is dead) is pruned and re-acquired — `proper-lockfile`/CC `concurrentSessions` parity.
+ *
+ * This is the ONLY legitimate file lock in the backend: the once-only CAS is in-process (one event loop +
+ * a per-token async mutex), so there is NO per-operation flock — this fence just guarantees the
+ * in-process model's premise (a single writer to the dir) holds. Cross-process CORRECT concurrency is the
+ * Pg/TiDB backend's job, by design.
+ */
+export class BootLock {
+    lockPath;
+    held = false;
+    constructor(lockPath) {
+        this.lockPath = lockPath;
+    }
+    /** Acquire the lock or throw. Prunes a stale lock whose recorded PID is not running. */
+    acquire() {
+        try {
+            this.writeLock();
+            this.held = true;
+            return;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+        }
+        // Lock file exists — check liveness of the recorded PID. A LIVE owner (including THIS process — a second
+        // FileStorageBackend over the same dir in the same process is still a conflict) → fail fast. Only a dead
+        // foreign PID (or an unreadable lock) is stale and prunable.
+        const ownerPid = this.readLockPid();
+        if (ownerPid === undefined) {
+            // With write-then-link the lock ALWAYS carries a parseable PID; an unreadable one is genuinely corrupt —
+            // do NOT prune it blindly (pruning an unreadable lock races a live writer, codex review BUG-1). Fail safe.
+            throw new Error(`file store: lock file at ${this.lockPath} is unreadable/corrupt; remove it manually if it is stale`);
+        }
+        if (isProcessRunning(ownerPid)) {
+            throw new Error(`file store: another instance (pid ${ownerPid}) owns this data dir (${dirnameOf(this.lockPath)})`);
+        }
+        // Parseable but DEAD foreign PID — stale; remove and retry exactly once.
+        try {
+            unlinkSync(this.lockPath);
+        }
+        catch {
+            /* a concurrent pruner may have removed it */
+        }
+        try {
+            this.writeLock();
+            this.held = true;
+        }
+        catch (err) {
+            if (err.code === "EEXIST") {
+                throw new Error(`file store: another instance won the lock race for this data dir`);
+            }
+            throw err;
+        }
+    }
+    writeLock() {
+        // write-then-link: the LOCK appears ATOMICALLY with the PID already in it — no empty window where a
+        // concurrent acquirer reads an unparseable lock and wrongly prunes a live owner (codex review BUG-1).
+        writeThenLink(this.lockPath, String(process.pid));
+    }
+    readLockPid() {
+        try {
+            const raw = readFileSync(this.lockPath, "utf8").trim();
+            // STRICT pure-numeric match — `parseInt("123junk")` would wrongly accept `123` and let a corrupt lock get
+            // pruned (codex review r2 BUG-1). A non-numeric/garbage lock → undefined → fail-safe (NOT pruned).
+            if (!/^[1-9][0-9]*$/.test(raw))
+                return undefined;
+            const pid = Number.parseInt(raw, 10);
+            return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Release the lock (only if we hold it). Best-effort; never throws. */
+    release() {
+        if (!this.held)
+            return;
+        this.held = false;
+        try {
+            // Only unlink if it is still OUR pid (don't delete a successor's lock after a stale-prune handoff).
+            if (this.readLockPid() === process.pid)
+                unlinkSync(this.lockPath);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+/**
+ * design/84 Seam B (TOC profile) — a per-scope CONSOLIDATION lock factory for the file backend's
+ * {@link import("../../core/consolidate-scope.js").ConsolidateScopeDeps.acquire} injection point. A single
+ * machine may run a periodic-consolidation timer AND a task-end inline pass concurrently; this advisory lock
+ * stops two processes consolidating the SAME scope at once (the in-process model the file backend assumes —
+ * see {@link BootLock} — does not cover a second OS process with its own timer).
+ *
+ * `acquire(scope)` writes `lockDir/<sanitizedScope>.consolidate.lock` carrying THIS pid (atomic
+ * {@link writeThenLink}, so the lock appears with its pid already in it — no empty-window prune race). It
+ * returns a `release` callback on success, or `undefined` when a LIVE owner already holds it (the caller
+ * treats `undefined` as "busy → skip this pass", a no-op). A STALE lock (recorded pid is dead) is pruned and
+ * re-acquired once. The implementation lives HERE (the deployment shell's persist/exec axis), NOT core — core
+ * only DEFINES the injection point (the constitutional split: gate-presence in core, mechanism in the profile).
+ */
+export function createFileConsolidationLock(lockDir) {
+    return (scope) => {
+        ensureDir(lockDir);
+        const lockPath = join(lockDir, `${sanitizeScope(scope)}.consolidate.lock`);
+        const tryWrite = () => {
+            try {
+                writeThenLink(lockPath, String(process.pid));
+                return true;
+            }
+            catch (err) {
+                if (err.code !== "EEXIST")
+                    throw err;
+                return false;
+            }
+        };
+        const readPid = () => {
+            try {
+                const raw = readFileSync(lockPath, "utf8").trim();
+                if (!/^[1-9][0-9]*$/.test(raw))
+                    return undefined; // unreadable/garbage → fail-safe (NOT pruned)
+                const pid = Number.parseInt(raw, 10);
+                return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const release = () => {
+            try {
+                // Only unlink if it is still OUR pid (don't delete a successor's lock after a stale-prune handoff).
+                if (readPid() === process.pid)
+                    unlinkSync(lockPath);
+            }
+            catch {
+                /* best-effort */
+            }
+        };
+        if (tryWrite())
+            return release;
+        // Lock exists — a LIVE owner (incl. this pid: a second pass in the same process is still a conflict) →
+        // busy (no-op). Only a parseable-but-DEAD foreign pid is stale and prunable.
+        const ownerPid = readPid();
+        if (ownerPid === undefined || isProcessRunning(ownerPid))
+            return undefined;
+        try {
+            unlinkSync(lockPath);
+        }
+        catch {
+            /* a concurrent pruner may have removed it */
+        }
+        return tryWrite() ? release : undefined; // lost the re-acquire race → busy (no-op)
+    };
+}
+/** Is a PID currently running? `kill(pid, 0)` throws ESRCH for a dead PID, EPERM for a live one we can't signal. */
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM"; // exists but not signalable
+    }
+}
+//# sourceMappingURL=fs-atomic.js.map

package/dist/stores/file/fs-atomic.js.map

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

package/dist/stores/file/index.d.ts

@@ -0,0 +1,98 @@
+import { type MemoryStore, type UtilityGate } from "../../core/memory.js";
+import type { CheckpointStore } from "../../core/checkpoint-store.js";
+import type { ToolResultStore } from "../../core/tool-result-store.js";
+import { type EvictPolicy } from "../../core/session-store.js";
+import type { SessionStore } from "../../core/session.js";
+import { type FileCheckpointStoreOptions } from "./checkpoint-store.js";
+import type { SessionPolicyStore } from "../../core/session-policy-store.js";
+import type { FileSnapshotStore } from "../../core/file-snapshot-store.js";
+import type { WorkflowJournalStore } from "../../core/workflow-journal-store.js";
+export { FileCheckpointStore, type FileCheckpointStoreOptions } from "./checkpoint-store.js";
+export { FileMemoryStore } from "./memory-store.js";
+export { FileSessionRepo } from "./session-store.js";
+export { FileToolResultStore } from "./tool-result-store.js";
+export { FileSessionPolicyStore } from "./session-policy-store.js";
+export { FileFileSnapshotStore } from "./file-snapshot-store.js";
+export { FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "./workflow-journal-store.js";
+export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
+export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
+/**
+ * design/80 — the file-backed `StorageBackend` for the local (TOC) single-user binary: the 3rd store impl
+ * alongside `InMemory*` and `Pg*`, selected purely by what the embedder injects into `RunnerDeps` (no engine
+ * change). Construct one over a single data root and pass its four members straight into `RunnerDeps`:
+ *
+ * ```ts
+ * const backend = new FileStorageBackend(); // ~/.ai-agent (or $AGENT_DATA_DIR)
+ * const runner = new Runner({
+ *   brain,
+ *   sessionStore: backend.sessionStore,
+ *   checkpointStore: backend.checkpointStore,
+ *   memoryStore: backend.memoryStore,
+ *   toolResultStore: backend.toolResultStore,
+ * });
+ * // …on shutdown:
+ * await backend.dispose();
+ * ```
+ *
+ * **Single-instance-per-data-dir (§2.4 / §7 decision 4):** the constructor takes a coarse boot `flock` on
+ * `root/LOCK`. A second `FileStorageBackend` over the same dir FAILS FAST ("another instance owns this data
+ * dir"); a stale lock from a dead PID is pruned. This is the ONLY file lock here — the once-only checkpoint
+ * CAS is in-process (one event loop), so there is no per-operation lock. Cross-process correct concurrency
+ * is the Pg/TiDB backend's job, by design.
+ */
+export interface FileStorageBackendOptions {
+    /** Data root. Default `$AGENT_DATA_DIR ?? ~/.ai-agent`, NFC-normalized + realpath-canonicalized. */
+    root?: string;
+    /** Profile-injected promotable-write gate (design/77 §2). Threaded into `guardedMemoryStore`. */
+    utilityGate?: UtilityGate;
+    /** `TtlSessionStore` idle-eviction policy. Default `"forget"` (§7 decision 5 — durable history is never
+     *  deleted by an idle timer). */
+    evict?: EvictPolicy;
+    /** Checkpoint store tuning (fsync cadence for `put`, ledger compaction threshold). */
+    checkpoint?: FileCheckpointStoreOptions;
+    /** design/101 §E19 — file-snapshot enumerator bounds (maxFiles/maxBytes/ignoreDirs). Default
+     *  {@link DEFAULT_SNAPSHOT_BOUNDS}. */
+    snapshotBounds?: Partial<import("../../core/file-snapshot-store.js").FileSnapshotBounds>;
+    /** design/81 Slice 5 — an optional {@link import("../../core/memory.js").Embedder}. Injected ⇒ the memory
+     *  store does portable (in-process) vector recall over a rebuildable sidecar index (`vectorMode:"portable"`);
+     *  absent ⇒ the lexical floor, byte-identical to before. Config-driven (the deployment injects it); OFF by
+     *  default. 🔴 the consolidation band `{0.05,0.3}` is tuned for the lexical distance — a real embedding model
+     *  needs it re-tuned + a no-mis-merge live check BEFORE production-enable (design/81 Slice 5 release gate). */
+    embedder?: import("../../core/memory.js").Embedder;
+}
+export declare class FileStorageBackend {
+    /** The resolved, canonical data root all four stores live under. */
+    readonly root: string;
+    readonly sessionStore: SessionStore;
+    readonly checkpointStore: CheckpointStore;
+    /** Wrapped in `guardedMemoryStore` (Gate-2 chokepoint). design/81: implements the id-addressable trio on
+     *  a lexical cosine-distance → `supportsConsolidation` is true → end-of-task consolidation lights up. */
+    readonly memoryStore: MemoryStore;
+    readonly toolResultStore: ToolResultStore;
+    /** design/99 §E6 — file-backed per-session permission rules (E6). Wire into `RunnerDeps.sessionPolicyStore`
+     *  for a local deployment that needs session rules to survive a restart. */
+    readonly sessionPolicyStore: SessionPolicyStore;
+    /** design/101 §E19 — file-backed working-tree snapshots (rewind-files). Wire into
+     *  `RunnerDeps.fileSnapshotStore`. Content-addressed blobs persist across restarts (local-only; a remote env
+     *  defers rewind to its own VM-snapshot backend). */
+    readonly fileSnapshotStore: FileSnapshotStore;
+    /** SVC-2 / [381]⑥ (onboarded per [375]) — file-backed durable workflow resume journal. Wire into
+     *  `RunnerDeps.workflowJournalStore` so `resumeFromRunId` survives a process restart on a TOC box. */
+    readonly workflowJournalStore: WorkflowJournalStore;
+    /**
+     * design/84 Seam B (TOC) — the per-scope consolidation lock for `consolidateScope`'s `acquire` injection
+     * point: `consolidateScope(scope, { store: backend.memoryStore, llm, acquire: backend.consolidationLock })`.
+     * Stops two OS processes sharing this data dir from consolidating the SAME scope at once (a busy scope ⇒
+     * `undefined` ⇒ the pass is a no-op). The locks live under `root/consolidation-locks/`.
+     */
+    readonly consolidationLock: (scope: string) => (() => void) | undefined;
+    private readonly lock;
+    private readonly fileCheckpoints;
+    private readonly fileMemory;
+    private readonly ttl;
+    private readonly fileWorkflowJournal;
+    constructor(opts?: FileStorageBackendOptions);
+    /** Release file handles + the boot lock (best-effort). Call on shutdown so a successor can acquire. */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/stores/file/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/stores/file/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAsB,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC9F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,OAAO,EAAuB,KAAK,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AAO7F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAEjF,OAAO,EAAE,mBAAmB,EAAE,KAAK,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACxH,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AAIpH,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAExG;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,yBAAyB;IACxC,oGAAoG;IACpG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iGAAiG;IACjG,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;qCACiC;IACjC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,sFAAsF;IACtF,UAAU,CAAC,EAAE,0BAA0B,CAAC;IACxC;2CACuC;IACvC,cAAc,CAAC,EAAE,OAAO,CAAC,OAAO,mCAAmC,EAAE,kBAAkB,CAAC,CAAC;IACzF;;;;mHAI+G;IAC/G,QAAQ,CAAC,EAAE,OAAO,sBAAsB,EAAE,QAAQ,CAAC;CACpD;AAED,qBAAa,kBAAkB;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C;6GACyG;IACzG,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C;gFAC4E;IAC5E,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,CAAC;IAChD;;yDAEqD;IACrD,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;IAC9C;0GACsG;IACtG,QAAQ,CAAC,oBAAoB,EAAE,oBAAoB,CAAC;IACpD;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IAExE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAW;IAChC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsB;IACtD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkB;IAC7C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IACtC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA2B;gBAEnD,IAAI,GAAE,yBAA8B;IAsChD,uGAAuG;IACjG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAkB/B"}

package/dist/stores/file/index.js

@@ -0,0 +1,109 @@
+import { join } from "node:path";
+import { guardedMemoryStore } from "../../core/memory.js";
+import { TtlSessionStore } from "../../core/session-store.js";
+import { BootLock, createFileConsolidationLock, resolveDataRoot } from "./fs-atomic.js";
+import { FileCheckpointStore } from "./checkpoint-store.js";
+import { FileMemoryStore } from "./memory-store.js";
+import { FileSessionRepo } from "./session-store.js";
+import { FileToolResultStore } from "./tool-result-store.js";
+import { FileSessionPolicyStore } from "./session-policy-store.js";
+import { FileFileSnapshotStore } from "./file-snapshot-store.js";
+import { FileWorkflowJournalStore } from "./workflow-journal-store.js";
+export { FileCheckpointStore } from "./checkpoint-store.js";
+export { FileMemoryStore } from "./memory-store.js";
+export { FileSessionRepo } from "./session-store.js";
+export { FileToolResultStore } from "./tool-result-store.js";
+export { FileSessionPolicyStore } from "./session-policy-store.js";
+export { FileFileSnapshotStore } from "./file-snapshot-store.js";
+export { FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "./workflow-journal-store.js";
+export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
+// Crash-safe fs persistence primitives (service [269]): the fsync-data + fsync-dir + torn-tail-drop discipline a
+// downstream file-backed store reuses instead of hand-rolling (hand-rolled writes risk the zero-length/torn-tail
+// corruption these specifically guard against). Same single-source rationale as secret-env/D2-tail.
+export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
+export class FileStorageBackend {
+    /** The resolved, canonical data root all four stores live under. */
+    root;
+    sessionStore;
+    checkpointStore;
+    /** Wrapped in `guardedMemoryStore` (Gate-2 chokepoint). design/81: implements the id-addressable trio on
+     *  a lexical cosine-distance → `supportsConsolidation` is true → end-of-task consolidation lights up. */
+    memoryStore;
+    toolResultStore;
+    /** design/99 §E6 — file-backed per-session permission rules (E6). Wire into `RunnerDeps.sessionPolicyStore`
+     *  for a local deployment that needs session rules to survive a restart. */
+    sessionPolicyStore;
+    /** design/101 §E19 — file-backed working-tree snapshots (rewind-files). Wire into
+     *  `RunnerDeps.fileSnapshotStore`. Content-addressed blobs persist across restarts (local-only; a remote env
+     *  defers rewind to its own VM-snapshot backend). */
+    fileSnapshotStore;
+    /** SVC-2 / [381]⑥ (onboarded per [375]) — file-backed durable workflow resume journal. Wire into
+     *  `RunnerDeps.workflowJournalStore` so `resumeFromRunId` survives a process restart on a TOC box. */
+    workflowJournalStore;
+    /**
+     * design/84 Seam B (TOC) — the per-scope consolidation lock for `consolidateScope`'s `acquire` injection
+     * point: `consolidateScope(scope, { store: backend.memoryStore, llm, acquire: backend.consolidationLock })`.
+     * Stops two OS processes sharing this data dir from consolidating the SAME scope at once (a busy scope ⇒
+     * `undefined` ⇒ the pass is a no-op). The locks live under `root/consolidation-locks/`.
+     */
+    consolidationLock;
+    lock;
+    fileCheckpoints;
+    fileMemory;
+    ttl;
+    fileWorkflowJournal;
+    constructor(opts = {}) {
+        this.root = resolveDataRoot(opts.root);
+        // Coarse boot guard FIRST — fail fast if another process owns this dir (single-instance contract).
+        this.lock = new BootLock(join(this.root, "LOCK"));
+        this.lock.acquire();
+        try {
+            const repo = new FileSessionRepo(this.root);
+            // Hand the repo to the built-in cache/pin layer (do NOT reimplement it). `evict: "forget"` so idle
+            // eviction never deletes durable session history.
+            this.ttl = new TtlSessionStore({ repo, evict: opts.evict ?? "forget" });
+            this.sessionStore = this.ttl;
+            this.fileCheckpoints = new FileCheckpointStore(this.root, opts.checkpoint);
+            this.checkpointStore = this.fileCheckpoints;
+            this.fileMemory = new FileMemoryStore(this.root, opts.embedder ? { embedder: opts.embedder } : {});
+            // Gate-2 chokepoint: a promotable write with no positive verdict is fail-closed at the boundary.
+            this.memoryStore = guardedMemoryStore(this.fileMemory, opts.utilityGate);
+            this.toolResultStore = new FileToolResultStore(this.root);
+            // design/99 §E6 + design/101 §E19 — the two newer durable seams, file-backed over the same data dir.
+            this.sessionPolicyStore = new FileSessionPolicyStore(this.root);
+            this.fileSnapshotStore = new FileFileSnapshotStore(this.root, opts.snapshotBounds);
+            // SVC-2 / [381]⑥ — the file-backed workflow resume journal (fsync per append: LOAD-BEARING).
+            this.fileWorkflowJournal = new FileWorkflowJournalStore(this.root);
+            this.workflowJournalStore = this.fileWorkflowJournal;
+            // design/84 Seam B (TOC): the per-scope consolidation lock factory, rooted under the data dir.
+            this.consolidationLock = createFileConsolidationLock(join(this.root, "consolidation-locks"));
+        }
+        catch (err) {
+            // Constructing a store failed after the lock was taken — release it so a retry can acquire.
+            this.lock.release();
+            throw err;
+        }
+    }
+    /** Release file handles + the boot lock (best-effort). Call on shutdown so a successor can acquire. */
+    async dispose() {
+        try {
+            await this.ttl.dispose();
+        }
+        catch {
+            /* best-effort */
+        }
+        this.fileCheckpoints.close();
+        // Slice 5: drain in-flight background embeds BEFORE closing the vlog fd, so a late embed can't writeSync to a
+        // closed (possibly recycled) fd. `close()` also flips a `closed` flag as a backstop for anything queued after.
+        try {
+            await this.fileMemory.flushEmbeds();
+        }
+        catch {
+            /* best-effort — a stuck embed must not block shutdown */
+        }
+        this.fileMemory.close();
+        this.fileWorkflowJournal.dispose();
+        this.lock.release();
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/stores/file/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/stores/file/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAsC,MAAM,sBAAsB,CAAC;AAG9F,OAAO,EAAE,eAAe,EAAoB,MAAM,6BAA6B,CAAC;AAEhF,OAAO,EAAE,QAAQ,EAAE,2BAA2B,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACxF,OAAO,EAAE,mBAAmB,EAAmC,MAAM,uBAAuB,CAAC;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAKvE,OAAO,EAAE,mBAAmB,EAAmC,MAAM,uBAAuB,CAAC;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACxH,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AACpH,iHAAiH;AACjH,iHAAiH;AACjH,oGAAoG;AACpG,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AA+CxG,MAAM,OAAO,kBAAkB;IAC7B,oEAAoE;IAC3D,IAAI,CAAS;IACb,YAAY,CAAe;IAC3B,eAAe,CAAkB;IAC1C;6GACyG;IAChG,WAAW,CAAc;IACzB,eAAe,CAAkB;IAC1C;gFAC4E;IACnE,kBAAkB,CAAqB;IAChD;;yDAEqD;IAC5C,iBAAiB,CAAoB;IAC9C;0GACsG;IAC7F,oBAAoB,CAAuB;IACpD;;;;;OAKG;IACM,iBAAiB,CAA8C;IAEvD,IAAI,CAAW;IACf,eAAe,CAAsB;IACrC,UAAU,CAAkB;IAC5B,GAAG,CAAkB;IACrB,mBAAmB,CAA2B;IAE/D,YAAY,OAAkC,EAAE;QAC9C,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvC,mGAAmG;QACnG,IAAI,CAAC,IAAI,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC5C,mGAAmG;YACnG,kDAAkD;YAClD,IAAI,CAAC,GAAG,GAAG,IAAI,eAAe,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,QAAQ,EAAE,CAAC,CAAC;YACxE,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC;YAE7B,IAAI,CAAC,eAAe,GAAG,IAAI,mBAAmB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;YAC3E,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,CAAC;YAE5C,IAAI,CAAC,UAAU,GAAG,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACnG,iGAAiG;YACjG,IAAI,CAAC,WAAW,GAAG,kBAAkB,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;YAEzE,IAAI,CAAC,eAAe,GAAG,IAAI,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAE1D,qGAAqG;YACrG,IAAI,CAAC,kBAAkB,GAAG,IAAI,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAChE,IAAI,CAAC,iBAAiB,GAAG,IAAI,qBAAqB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;YAEnF,6FAA6F;YAC7F,IAAI,CAAC,mBAAmB,GAAG,IAAI,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACnE,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC,mBAAmB,CAAC;YAErD,+FAA+F;YAC/F,IAAI,CAAC,iBAAiB,GAAG,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC;QAC/F,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,4FAA4F;YAC5F,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,uGAAuG;IACvG,KAAK,CAAC,OAAO;QACX,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,iBAAiB;QACnB,CAAC;QACD,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAC7B,8GAA8G;QAC9G,+GAA+G;QAC/G,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,yDAAyD;QAC3D,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,mBAAmB,CAAC,OAAO,EAAE,CAAC;QACnC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;IACtB,CAAC;CACF"}