@sema-ai/core 1.275.1

package/dist/stores/file/session-policy-store.js

@@ -0,0 +1,123 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { loosenReasons, normalizeRules, stripRev, SessionPolicyError, } from "../../core/session-policy-store.js";
+import { atomicWriteFile, ensureDir, sanitizeScope } from "./fs-atomic.js";
+/**
+ * design/99 §E6 — file-backed {@link SessionPolicyStore} for the local (TOC) backend: ONE JSON file per
+ * `(sessionId, principal)`, semantics **byte-for-byte identical to `InMemorySessionPolicyStore`** (the
+ * cross-backend equivalence contract). CAS-rev OCC + tighten-only reuse the SAME pure helpers
+ * (`loosenReasons`/`normalizeRules`/`stripRev`) as core — no re-implemented rule logic that could drift.
+ *
+ * Atomicity: the file backend is single-process (the `FileStorageBackend` boot lock guarantees ONE writer per
+ * data dir), and `getRules`/`putRules` read-check-write SYNCHRONOUSLY (no await between the rev read and the
+ * atomic write), so the read-modify-write is atomic in the one event loop — exactly the InMemory store's premise.
+ * Cross-process CORRECT concurrency is the Pg/TiDB backend's job (a CAS WHERE clause), by design.
+ */
+export class FileSessionPolicyStore {
+    dir;
+    constructor(root) {
+        this.dir = join(root, "session-policy");
+        ensureDir(this.dir);
+    }
+    /** `(sessionId, principal)` → a safe, INJECTIVE filename (sanitizeScope appends the full sha256 of the raw
+     *  composite key, so distinct keys never collide on disk). */
+    pathFor(sessionId, principal) {
+        const composite = JSON.stringify([sessionId, principal ?? null]); // delimiter-injection-safe, matches InMemory
+        return join(this.dir, `${sanitizeScope(composite)}.json`);
+    }
+    read(sessionId, principal) {
+        let raw;
+        try {
+            raw = readFileSync(this.pathFor(sessionId, principal), "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+        try {
+            // A torn/zero-byte/corrupt rules file must NOT throw out of getRules/putRules (bug-hunt MAJOR-3): getRules
+            // throwing would fail the whole task; putRules throwing would self-LOCK (a re-tighten reads first, so the
+            // rules could never be repaired by writing). Treat corrupt as ABSENT = fail-open, consistent with the
+            // opt-in tighten-only design (no rules ⇒ no constraint; an operator/normal write then re-establishes them).
+            const parsed = JSON.parse(raw);
+            // Validate the SHAPE, not just truthy-object — a foreign/hand-edited file could be a JSON ARRAY (passes
+            // typeof "object") or carry a STRING `rev` that poisons the CAS arithmetic ("5" + 1 → "51", permanently
+            // breaking OCC for that key). Treat anything malformed as ABSENT (fail-open, same as a torn file); the
+            // store itself only ever writes a non-array object with a numeric rev + string-array fields.
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+                return null;
+            const r = parsed;
+            if (r.rev !== undefined && (typeof r.rev !== "number" || !Number.isFinite(r.rev)))
+                return null;
+            const strArr = (x) => x === undefined || (Array.isArray(x) && x.every((e) => typeof e === "string"));
+            if (!strArr(r.toolAllow) || !strArr(r.toolDeny) || !strArr(r.commandAllow) || !strArr(r.commandDeny) || !strArr(r.allowDirs))
+                return null;
+            // Strip the `__sid`/`__principal` enumeration metadata ([271]) so getRules returns the CLEAN
+            // StoredSessionRules — byte-identical to InMemory (which keeps that pair in its composite map key, not the value).
+            const { __sid: _sid, __principal: _principal, ...clean } = r;
+            void _sid;
+            void _principal;
+            return clean;
+        }
+        catch {
+            return null;
+        }
+    }
+    async getRules(sessionId, principal) {
+        return this.read(sessionId, principal);
+    }
+    async putRules(sessionId, principal, rules, opts) {
+        const prior = this.read(sessionId, principal);
+        if (opts?.expectedRev !== undefined && (prior?.rev ?? 0) !== opts.expectedRev) {
+            throw new SessionPolicyError("conflict", `session rules rev mismatch (expected ${opts.expectedRev}, have ${prior?.rev ?? 0})`);
+        }
+        const clean = normalizeRules(stripRev(rules)); // normalize allowDirs so the tighten diff + stored form match the runtime
+        if (prior && opts?.operator !== true) {
+            const loosens = loosenReasons(prior, clean);
+            if (loosens.length > 0) {
+                throw new SessionPolicyError("loosen_forbidden", `a non-operator session-rule write may only tighten; refused: ${loosens.join("; ")}`);
+            }
+        }
+        const next = { ...clean, rev: (prior?.rev ?? 0) + 1 };
+        // Atomic whole-file replace (fsync data + dir) — a crash never leaves a partial/zero-byte rules file.
+        // The `__sid`/`__principal` metadata ([271]) rides ALONGSIDE the rules (the filename is a one-way hash, so
+        // listBySession can't recover the principal from it); `read()` strips it so getRules stays equivalence-clean.
+        atomicWriteFile(join(this.dir, "tmp"), this.pathFor(sessionId, principal), JSON.stringify({ ...next, __sid: sessionId, __principal: principal ?? null }));
+        return next;
+    }
+    async listBySession(sessionId) {
+        // [271]: enumerate every policy file, filter by the `__sid` metadata, return (principal, clean rules).
+        let files;
+        try {
+            files = readdirSync(this.dir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return [];
+            throw err;
+        }
+        const out = [];
+        for (const file of files) {
+            if (!file.endsWith(".json"))
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(readFileSync(join(this.dir, file), "utf8"));
+            }
+            catch {
+                continue; // torn/corrupt → skip (fail-open, same tolerance as read())
+            }
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+                continue;
+            const r = parsed;
+            if (r.__sid !== sessionId)
+                continue;
+            const { __sid: _sid, __principal, ...rules } = r;
+            void _sid;
+            out.push({ principal: __principal ?? undefined, rules: rules });
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=session-policy-store.js.map

package/dist/stores/file/session-policy-store.js.map

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

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

@@ -0,0 +1,34 @@
+import { Session } from "../../internal/harness.js";
+import type { SessionMetadata, SessionRepo, SessionTreeEntry } from "../../internal/harness.js";
+export declare class FileSessionRepo implements SessionRepo {
+    private readonly dir;
+    private readonly tmpDir;
+    constructor(root: string);
+    private pathFor;
+    /** Read + torn-tail-recover a session file into (meta, entries); a missing file → not_found. */
+    private read;
+    private storage;
+    create(options?: {
+        id?: string;
+    }): Promise<Session>;
+    open(metadata: SessionMetadata): Promise<Session>;
+    list(): Promise<SessionMetadata[]>;
+    delete(metadata: SessionMetadata): Promise<void>;
+    fork(sourceMetadata: SessionMetadata, options?: {
+        entryId?: string;
+        position?: "before" | "at";
+        id?: string;
+    }): Promise<Session>;
+    /** 2c session-sync ([275], the FILE half of [266]②): the FULL oldest-first log for export. The file backend
+     *  has NO F3 floor — `read` returns EVERY persisted entry (`id`/`parentId` verbatim) — so this is the complete
+     *  log, BYPASSing any bounded tail (matches `InMemorySessionRepo.exportEntries`). Missing file → not_found. */
+    exportEntries(sessionId: string): Promise<SessionTreeEntry[]>;
+    /** 2c session-sync ([275]): import a verbatim log into `sessionId`. The single fail-closed invariant gate runs
+     *  FIRST ({@link validateEntriesForImport}); `owner` is a durable multi-tenant concept the local file backend
+     *  has no field for (accepted, unused — same as `InMemorySessionRepo`). Writes the WHOLE file (meta + entries)
+     *  atomically via tmp→fsync→rename — the rename is the commit point, so a crash leaves either nothing or an
+     *  orphan temp, never a partially-imported session (mirrors `fork`). An existing session is REPLACED (the
+     *  orchestrator's importSession owns the already-exists policy, same as InMemory's overwrite). */
+    importEntries(sessionId: string, owner: string | undefined, entries: SessionTreeEntry[]): Promise<void>;
+}
+//# sourceMappingURL=session-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.d.ts","sourceRoot":"","sources":["../../../src/stores/file/session-store.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,OAAO,EAKR,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EACX,gBAAgB,EAEjB,MAAM,2BAA2B,CAAC;AAuDnC,qBAAa,eAAgB,YAAW,WAAW;IACjD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,IAAI,EAAE,MAAM;IAOxB,OAAO,CAAC,OAAO;IAIf,gGAAgG;IAChG,OAAO,CAAC,IAAI;IAkBZ,OAAO,CAAC,OAAO;IAQT,MAAM,CAAC,OAAO,GAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAuBvD,IAAI,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IAKjD,IAAI,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAqBlC,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAShD,IAAI,CACR,cAAc,EAAE,eAAe,EAC/B,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAO,GAC1E,OAAO,CAAC,OAAO,CAAC;IAoBnB;;mHAE+G;IACzG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAInE;;;;;sGAKkG;IAC5F,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAU9G"}

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

@@ -0,0 +1,175 @@
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { BaseSessionStorage, Session, SessionError, getEntriesToFork, uuidv7, validateEntriesForImport, } from "../../internal/harness.js";
+import { AppendLog, atomicWriteFile, ensureDir, readJsonlRecords, sanitizePathComponent } from "./fs-atomic.js";
+/**
+ * design/80 §3 — file {@link SessionRepo} + {@link SessionStorage} (one append-only JSONL per session).
+ *
+ * Mirrors {@link import("../pg.js").PgSessionRepo}, on the local FS instead of Postgres:
+ *  - one `sessions/<sessionId>.jsonl` per session, first line a `meta` record, the rest `entry` records;
+ *  - the session FILE's existence is the liveness marker (the Pg "session row" analog): `open` of a missing
+ *    file → `SessionError("not_found")` (so `TtlSessionStore.openOrCreate` falls back to create);
+ *  - `fork` writes entries to a temp name → fsync → rename (atomic-rename = the commit point), so a mid-fork
+ *    crash leaves either nothing or an orphan temp, never a partially-live session;
+ *  - full-tree wake (read the whole JSONL) — the reference-grade trade-off `PgSessionRepo.load` documents.
+ *
+ * Hand the repo to the built-in `new TtlSessionStore({ repo, evict: "forget" })` — do NOT reimplement the
+ * cache/pin layer. `expectedLeafId` CAS is in-memory here (single process, one writer to the dir guaranteed
+ * by the boot LOCK — no shared-state CAS needed, unlike Pg's `(session_id, seq)` key) but still throws
+ * `SessionError("conflict")` on mismatch so the Runner's reconcile-retry path is unchanged.
+ */
+const SUFFIX = ".jsonl";
+class FileSessionStorage extends BaseSessionStorage {
+    log;
+    constructor(log, meta, entries) {
+        super(meta, entries);
+        this.log = log;
+    }
+    async persist(entry) {
+        // Single append of one entry line, fsync'd at the leaf/turn boundary (the leaf-advance commit point).
+        this.log.append({ kind: "entry", entry }, true);
+    }
+    async appendEntry(entry, opts) {
+        this.assertExpectedLeaf(opts); // in-memory optimistic-lock check (single process); throws "conflict"
+        await this.persist(entry);
+        this.recordEntry(entry);
+    }
+    async setLeafId(leafId, opts) {
+        this.assertExpectedLeaf(opts);
+        const entry = this.createLeafEntry(leafId);
+        await this.persist(entry);
+        this.recordEntry(entry);
+    }
+}
+export class FileSessionRepo {
+    dir;
+    tmpDir;
+    constructor(root) {
+        this.dir = join(root, "sessions");
+        this.tmpDir = join(root, "tmp");
+        ensureDir(this.dir);
+        ensureDir(this.tmpDir);
+    }
+    pathFor(id) {
+        return join(this.dir, `${sanitizePathComponent(id)}${SUFFIX}`);
+    }
+    /** Read + torn-tail-recover a session file into (meta, entries); a missing file → not_found. */
+    read(id) {
+        const path = this.pathFor(id);
+        if (!existsSync(path)) {
+            throw new SessionError("not_found", `Session not found: ${id}`);
+        }
+        const lines = readJsonlRecords(path);
+        let createdAt = "";
+        let forkedFrom;
+        const entries = [];
+        for (const line of lines) {
+            if (line.kind === "meta") {
+                createdAt = line.createdAt;
+                forkedFrom = line.forkedFrom;
+            }
+            else
+                entries.push(line.entry);
+        }
+        return { createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}), entries };
+    }
+    storage(id, createdAt, entries, forkedFrom) {
+        return new FileSessionStorage(new AppendLog(this.pathFor(id)), { id, createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}) }, entries);
+    }
+    async create(options = {}) {
+        const id = options.id ?? uuidv7();
+        const createdAt = new Date().toISOString();
+        const path = this.pathFor(id);
+        // A FRESH create over an EXISTING id is a no-op on history? No — match PgSessionRepo: an explicit id with
+        // no prior file starts clean; an explicit id WITH a prior file opens the SAME session (idempotent-ish).
+        // We seed the meta line atomically only when the file is absent (the file's existence is the liveness
+        // marker — a fresh create writes line 1; a re-create of an existing id re-opens it).
+        if (!existsSync(path)) {
+            // Atomic seed of line 1 (meta) via the tmp→rename path so a partial create never leaves a headerless file.
+            atomicWriteFile(this.tmpDir, path, `${JSON.stringify({ kind: "meta", id, createdAt })}\n`);
+            return new Session(this.storage(id, createdAt, []));
+        }
+        // Re-open path: thread the persisted lineage through, same as open() — a re-created fork must not
+        // surface metadata without its `forkedFrom` (codex 1.265.0 review F4).
+        const { createdAt: existingCreatedAt, forkedFrom, entries } = this.read(id);
+        return new Session(this.storage(id, existingCreatedAt || createdAt, entries, forkedFrom));
+    }
+    async open(metadata) {
+        const { createdAt, forkedFrom, entries } = this.read(metadata.id); // throws not_found on a missing file
+        return new Session(this.storage(metadata.id, createdAt, entries, forkedFrom));
+    }
+    async list() {
+        let names;
+        try {
+            names = readdirSync(this.dir);
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const name of names) {
+            if (!name.endsWith(SUFFIX))
+                continue;
+            const id = name.slice(0, -SUFFIX.length);
+            try {
+                const { createdAt, forkedFrom } = this.read(id);
+                out.push({ id, createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}) });
+            }
+            catch {
+                // A torn/headerless file is skipped from listing (still openable if it has any meta line).
+            }
+        }
+        return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    }
+    async delete(metadata) {
+        // Remove the session file — its absence makes `open` → not_found (the liveness marker is gone).
+        try {
+            rmSync(this.pathFor(metadata.id), { force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    async fork(sourceMetadata, options = {}) {
+        const source = await this.open(sourceMetadata);
+        const forked = await getEntriesToFork(source.getStorage(), options);
+        const id = options.id ?? uuidv7();
+        const createdAt = new Date().toISOString();
+        const path = this.pathFor(id);
+        // Re-seq from 0: entry ids/parent links are per-session and copy verbatim (matches PgSessionRepo). Write
+        // the WHOLE new file (meta + entries) atomically via tmp→fsync→rename — the rename is the commit point,
+        // so a mid-fork crash leaves either nothing or an orphan temp, never a partially-live session.
+        // F7 fork-GC seam: the meta line stamps the parent id so a retention/reap can walk fork lineage.
+        const lines = [
+            JSON.stringify({ kind: "meta", id, createdAt, forkedFrom: sourceMetadata.id }),
+        ];
+        for (const entry of forked) {
+            lines.push(JSON.stringify({ kind: "entry", entry }));
+        }
+        atomicWriteFile(this.tmpDir, path, `${lines.join("\n")}\n`);
+        return new Session(this.storage(id, createdAt, [...forked], sourceMetadata.id));
+    }
+    /** 2c session-sync ([275], the FILE half of [266]②): the FULL oldest-first log for export. The file backend
+     *  has NO F3 floor — `read` returns EVERY persisted entry (`id`/`parentId` verbatim) — so this is the complete
+     *  log, BYPASSing any bounded tail (matches `InMemorySessionRepo.exportEntries`). Missing file → not_found. */
+    async exportEntries(sessionId) {
+        return this.read(sessionId).entries;
+    }
+    /** 2c session-sync ([275]): import a verbatim log into `sessionId`. The single fail-closed invariant gate runs
+     *  FIRST ({@link validateEntriesForImport}); `owner` is a durable multi-tenant concept the local file backend
+     *  has no field for (accepted, unused — same as `InMemorySessionRepo`). Writes the WHOLE file (meta + entries)
+     *  atomically via tmp→fsync→rename — the rename is the commit point, so a crash leaves either nothing or an
+     *  orphan temp, never a partially-imported session (mirrors `fork`). An existing session is REPLACED (the
+     *  orchestrator's importSession owns the already-exists policy, same as InMemory's overwrite). */
+    async importEntries(sessionId, owner, entries) {
+        void owner;
+        const validated = validateEntriesForImport(entries);
+        const createdAt = new Date().toISOString();
+        const lines = [JSON.stringify({ kind: "meta", id: sessionId, createdAt })];
+        for (const entry of validated) {
+            lines.push(JSON.stringify({ kind: "entry", entry }));
+        }
+        atomicWriteFile(this.tmpDir, this.pathFor(sessionId), `${lines.join("\n")}\n`);
+    }
+}
+//# sourceMappingURL=session-store.js.map

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

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

package/dist/stores/file/tool-result-store.d.ts

@@ -0,0 +1,23 @@
+import type { ToolResultSlice, ToolResultStore } from "../../core/tool-result-store.js";
+/**
+ * design/80 §2.5 — file {@link ToolResultStore}: write-once-idempotent, ONE file per ref.
+ *
+ * `ref = tr_<sessionId>_<toolCallId>` (engine-minted, already globally unique). `put` is an
+ * `O_CREAT|O_EXCL` create (`"wx"`) → on `EEXIST` it SILENTLY no-ops (write-once-idempotent; never
+ * re-writes — a re-write risks a non-identical preview and breaks the prompt cache, §2.5 / the in-memory
+ * store's `if (!map.has(ref))`). Content is fsync'd before return. `get` slices the file by `{offset,
+ * limit}` over CHARS to match `ToolResultSlice.totalChars` semantics; an unknown ref → `undefined` (the
+ * model is told it's gone — degrades, never crashes). `withToolResultOffload` joins text with `\n` and
+ * stores the joined string verbatim, so the char-offset slice here is exactly the in-memory store's slice.
+ */
+export declare class FileToolResultStore implements ToolResultStore {
+    private readonly dir;
+    constructor(root: string);
+    private pathFor;
+    put(ref: string, content: string): void;
+    get(ref: string, opts?: {
+        offset?: number;
+        limit?: number;
+    }): ToolResultSlice | undefined;
+}
+//# sourceMappingURL=tool-result-store.d.ts.map

package/dist/stores/file/tool-result-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result-store.d.ts","sourceRoot":"","sources":["../../../src/stores/file/tool-result-store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAGxF;;;;;;;;;;GAUG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,IAAI,EAAE,MAAM;IAKxB,OAAO,CAAC,OAAO;IAKf,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAWvC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,eAAe,GAAG,SAAS;CAgB1F"}

package/dist/stores/file/tool-result-store.js

@@ -0,0 +1,61 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ensureDir, sanitizePathComponent, writeThenLink } from "./fs-atomic.js";
+/**
+ * design/80 §2.5 — file {@link ToolResultStore}: write-once-idempotent, ONE file per ref.
+ *
+ * `ref = tr_<sessionId>_<toolCallId>` (engine-minted, already globally unique). `put` is an
+ * `O_CREAT|O_EXCL` create (`"wx"`) → on `EEXIST` it SILENTLY no-ops (write-once-idempotent; never
+ * re-writes — a re-write risks a non-identical preview and breaks the prompt cache, §2.5 / the in-memory
+ * store's `if (!map.has(ref))`). Content is fsync'd before return. `get` slices the file by `{offset,
+ * limit}` over CHARS to match `ToolResultSlice.totalChars` semantics; an unknown ref → `undefined` (the
+ * model is told it's gone — degrades, never crashes). `withToolResultOffload` joins text with `\n` and
+ * stores the joined string verbatim, so the char-offset slice here is exactly the in-memory store's slice.
+ */
+export class FileToolResultStore {
+    dir;
+    constructor(root) {
+        this.dir = join(root, "tool-results");
+        ensureDir(this.dir);
+    }
+    pathFor(ref) {
+        // `ref` is engine-minted but still passes the strict component guard (defense-in-depth — never traverse).
+        return join(this.dir, `${sanitizePathComponent(ref)}.txt`);
+    }
+    put(ref, content) {
+        try {
+            // write-then-link: the file appears ATOMICALLY with FULL content — a crash mid-write leaves only an orphan
+            // temp (ignored), never a zero-byte target that a retry's EEXIST would silently keep (codex review BUG-3).
+            writeThenLink(this.pathFor(ref), content);
+        }
+        catch (err) {
+            if (err.code === "EEXIST")
+                return; // already stored (full) → idempotent no-op
+            throw err;
+        }
+    }
+    get(ref, opts) {
+        let full;
+        try {
+            full = readFileSync(this.pathFor(ref), "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return undefined; // unknown ref → undefined
+            // A malformed ref (rejected by the component guard) also degrades to undefined rather than crashing.
+            if (err instanceof Error && err.message.startsWith("file store: unsafe path component"))
+                return undefined;
+            throw err;
+        }
+        // Char-offset slice, identical to the in-memory store (`tool-result-store.ts:56`).
+        const offset = Math.min(full.length, Math.max(0, intOr(opts?.offset, 0)));
+        const limit = opts?.limit != null ? Math.max(0, intOr(opts.limit, 0)) : undefined;
+        const content = limit != null ? full.slice(offset, offset + limit) : full.slice(offset);
+        return { content, offset, totalChars: full.length };
+    }
+}
+/** Floor a finite number, else fall back — rejects NaN/Infinity (mirrors the in-memory store's `intOr`). */
+function intOr(x, fallback) {
+    return Number.isFinite(x) ? Math.floor(x) : fallback;
+}
+//# sourceMappingURL=tool-result-store.js.map

package/dist/stores/file/tool-result-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result-store.js","sourceRoot":"","sources":["../../../src/stores/file/tool-result-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,SAAS,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEjF;;;;;;;;;;GAUG;AACH,MAAM,OAAO,mBAAmB;IACb,GAAG,CAAS;IAE7B,YAAY,IAAY;QACtB,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QACtC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtB,CAAC;IAEO,OAAO,CAAC,GAAW;QACzB,0GAA0G;QAC1G,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,qBAAqB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7D,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,OAAe;QAC9B,IAAI,CAAC;YACH,2GAA2G;YAC3G,2GAA2G;YAC3G,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;QAC5C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,CAAC,2CAA2C;YACzG,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,IAA0C;QACzD,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;QACjD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,SAAS,CAAC,CAAC,0BAA0B;YAClG,qGAAqG;YACrG,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,mCAAmC,CAAC;gBAAE,OAAO,SAAS,CAAC;YAC1G,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,mFAAmF;QACnF,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1E,MAAM,KAAK,GAAG,IAAI,EAAE,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAClF,MAAM,OAAO,GAAG,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACxF,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IACtD,CAAC;CACF;AAED,4GAA4G;AAC5G,SAAS,KAAK,CAAC,CAAqB,EAAE,QAAgB;IACpD,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AACjE,CAAC"}

package/dist/stores/file/workflow-journal-store.d.ts

@@ -0,0 +1,36 @@
+import { type WorkflowJournalEntry, type WorkflowJournalStore } from "../../core/workflow-journal-store.js";
+/**
+ * SVC-2 — the shared size bound for a journaled workflow-agent result, so ALL backends DEGRADE IDENTICALLY on
+ * an oversize TaskResult (no dialect divergence). Inlined from service's `workflow-journal-limits` on
+ * onboarding (channel [375]) — the 5 MiB figure aligns with TiDB's ~6 MiB per-row txn-entry-size-limit (a row
+ * over it is REJECTED with "entry too large"); a LOAD-BEARING `append` that hit that would THROW and kill the
+ * whole workflow. PostgreSQL TEXT has no such low limit, so without a shared guard the same large result would
+ * journal fine on PG but fail the workflow on TiDB. All backends instead skip-journal a result whose serialized
+ * size exceeds {@link MAX_JOURNAL_RESULT_BYTES} (a no-op, never an insert/throw): the agent's ordinal is simply
+ * not cached, so a resume re-runs that one agent live. Resume is an optimization — a too-big-to-cache result is
+ * a graceful degrade, not a failure. Measured in BYTES (UTF-8) — a multibyte result can be larger than its
+ * `.length` in chars.
+ */
+export declare const MAX_JOURNAL_RESULT_BYTES: number;
+/** True when a serialized journal result is too large to store (UTF-8 byte length over {@link MAX_JOURNAL_RESULT_BYTES}). */
+export declare function oversizeJournalResult(serialized: string): boolean;
+export declare class FileWorkflowJournalStore implements WorkflowJournalStore {
+    private readonly fsyncEnabled;
+    private readonly dir;
+    private readonly fds;
+    /** Per-run committed scope, cached at first touch — the append-path scope guard must NOT re-read the whole
+     *  ledger per append (a journaled result can be MBs; a many-agent workflow would go O(n²) on disk). One replay
+     *  discovers it; every later append compares against the cache. */
+    private readonly scopes;
+    constructor(root: string, fsyncEnabled?: boolean);
+    private pathFor;
+    /** Replay a run's ledger: last-writer-wins per ordinal; a torn/unparsable line is skipped (uncommitted). */
+    private replay;
+    append(runId: string, scope: string, entry: WorkflowJournalEntry): Promise<void>;
+    load(runId: string, scope: string): Promise<WorkflowJournalEntry[]>;
+    /** GC (service extra, mirrors the SQL twins): drop the run's ledger once the run is terminal + retained. */
+    deleteByRun(runId: string): Promise<number>;
+    /** Release ledger fds (graceful shutdown; parity with the other file stores' dispose). */
+    dispose(): void;
+}
+//# sourceMappingURL=workflow-journal-store.d.ts.map

package/dist/stores/file/workflow-journal-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-journal-store.d.ts","sourceRoot":"","sources":["../../../src/stores/file/workflow-journal-store.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAkB,KAAK,oBAAoB,EAAE,KAAK,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAI5H;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,QAAkB,CAAC;AAExD,6HAA6H;AAC7H,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEjE;AASD,qBAAa,wBAAyB,YAAW,oBAAoB;IAQzC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAPvD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA6B;IACjD;;uEAEmE;IACnE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;gBAExC,IAAI,EAAE,MAAM,EAAmB,YAAY,UAAO;IAK9D,OAAO,CAAC,OAAO;IAIf,4GAA4G;IAC5G,OAAO,CAAC,MAAM;IA6BR,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBhF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAMzE,4GAA4G;IACtG,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAajD,0FAA0F;IAC1F,OAAO,IAAI,IAAI;CAMhB"}