@sema-ai/core 1.275.1

package/dist/core/memory-engine/file-backend.js

@@ -0,0 +1,948 @@
+// design/138 S1 — FileMemoryEngineBackend: the TOC 权威盘. The memory DIRECTORY ITSELF is the storage
+// (直通零拷贝): each entry is one `<slug>.md` file with CC frontmatter + a hidden immutable `id:`.
+// The engine's session projection and this backend's storage share ONE layout (layout.ts), so
+// materialize on this backend writes nothing (files are already exactly where the projection wants
+// them) and applyPatches is the sole write path (add/update/delete + per-id CAS on the content rev).
+//
+// 双轨评审 (B1/B2/B3/H4): zero-copy alone cannot carry the safety invariants, so this backend runs a
+// CONTROL PLANE (layout.deriveControlPlaneDir — model-invisible, outside the memory dir):
+//  - `revs.json` — the committed-rev ledger (B3: atomic writes, corrupt ⇒ fail-closed, never a silent
+//    empty-ledger downgrade);
+//  - `scopes.json` — the scope registry (B3, via layout.ts);
+//  - `shadow/<id>.md` — the committed content copy per entry (B1: 「缺失≠删除」has an actual recovery
+//    source; written at the applyPatches commit point + backfilled on read-side sync);
+//  - `quarantine/` — inbound-gate-rejected files moved OUT of the model-visible plane (B2/L4);
+//  - `journal.json` + same-dir `.stage-*` files — the applyPatches transaction (H4: staged writes,
+//    fsync'd journal, atomic renames; a crash is rolled forward/back on the next construction).
+import { lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, openSync, writeSync, fsyncSync, closeSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, join, relative } from "node:path";
+import { jaccardDistance, termSet } from "../memory-vector.js";
+import { MAX_MEMORY_BYTES } from "../memory.js";
+import { inlineUntrusted } from "../untrusted-text.js";
+import { computeEntryRev, entryFromFile, parseEntryFile, serializeEntryFile } from "./frontmatter.js";
+import { ControlPlaneCorruptError, CURSORS_FILE, atomicWriteFileSync, claimRootScope, deriveControlPlaneDir, ensureDirExists, enqueueMemoryAnnouncement, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirName, } from "./layout.js";
+import { scanMemoryFileName, scanMemoryWrite } from "./scan.js";
+/** Files/dirs the entry scan never treats as entries: the derived index, dotfiles (`.hydrate`,
+ *  transaction staging files), and anything not `.md`. */
+export const MEMORY_INDEX_FILENAME = "MEMORY.md";
+/** Default nesting depth cap under a scope dir (CC memory is flat; a small allowance for topic dirs). */
+export const DEFAULT_MAX_ENTRY_DEPTH = 3;
+/**
+ * Enumerate a scope dir's entry files (depth-capped, symlinks skipped, dotfiles/index/non-`.md`
+ * ignored, `exclude` dirs — sibling scope homes under the root — skipped). Shared by the backend
+ * and the engine's harvest scan so the two can never disagree on what counts as an entry file.
+ */
+export function scanEntryFiles(dir, opts = {}) {
+    const maxDepth = opts.maxDepth ?? DEFAULT_MAX_ENTRY_DEPTH;
+    const out = [];
+    const walk = (d, depth) => {
+        let names;
+        try {
+            names = readdirSync(d);
+        }
+        catch {
+            return; // unreadable/missing dir ⇒ no entries (fail-open on reads)
+        }
+        for (const name of names.sort()) {
+            if (name.startsWith(".") || name === MEMORY_INDEX_FILENAME) {
+                if (name.startsWith("."))
+                    opts.onSkip?.(join(d, name), "dotfile");
+                continue;
+            }
+            const p = join(d, name);
+            let st;
+            try {
+                st = lstatSync(p);
+            }
+            catch {
+                continue;
+            }
+            if (st.isSymbolicLink()) {
+                opts.onSkip?.(p, "symlink"); // containment gate: symlinks are never entries
+                continue;
+            }
+            if (st.isDirectory()) {
+                if (depth === 0 && opts.exclude?.has(name))
+                    continue; // a sibling scope's home under the root
+                if (depth + 1 <= maxDepth)
+                    walk(p, depth + 1);
+                else
+                    opts.onSkip?.(p, "depth");
+                continue;
+            }
+            if (!st.isFile())
+                continue;
+            if (!name.endsWith(".md")) {
+                opts.onSkip?.(p, "nonmd");
+                continue;
+            }
+            out.push({ path: p, slug: relative(dir, p).replace(/\.md$/, "") });
+        }
+    };
+    walk(dir, 0);
+    return out;
+}
+const LEDGER_FILE = "revs.json";
+const JOURNAL_FILE = "journal.json";
+/** codex B5 — cross-process txn mutex: a lock older than this is a crashed holder (stolen; the
+ *  journal recovery inside the lock makes the steal safe). */
+const TXN_LOCK_STALE_MS = 30_000;
+/** How long a writer waits for the mutex before failing loud (harvest is a boundary side-effect —
+ *  a wedged sibling must surface, not hang the task teardown). */
+const TXN_LOCK_WAIT_MS = 15_000;
+/** 对抗复审 L3 — steal grace: a waiter that OBSERVES a lock extends its deadline to that lock's
+ *  stale line plus this ε, so a holder that crashed inside the fixed-WAIT window ([T, T+WAIT) with
+ *  WAIT < STALE) is still reachable by one steal attempt instead of every waiter timing out. */
+const TXN_LOCK_STEAL_GRACE_MS = 250;
+const SHADOW_DIR = "shadow";
+const QUARANTINE_DIR = "quarantine";
+/**
+ * ⚠️ DEPLOYMENT BOUNDARY (N0 定谳,channel 给service-AI.md [412],2026-07-09):this backend — and the
+ * file memory engine's materialize/harvest — operates on the WORKER-HOST fs plane (node:fs), matching
+ * CC's `~/.claude` host-plane memory (the only behavior anchor). It is NOT ExecutionEnv-aware: when a
+ * deployment routes the model's file tools to a REMOTE sandbox (e2b/k8s/ssh/adb/local-docker), the two
+ * planes do not intersect — the model cannot see the memory dir and harvest cannot see sandbox writes.
+ * Remote-hands deployments MUST gate the engine off for non-host lanes (reference: service
+ * `memoryEngineBackendFor` lane gate, fail-closed + `MEMORY_ENGINE_REMOTE_LANE=allow` override for
+ * lanes that genuinely share the worker fs, e.g. ssh+NFS). A future "remote-memory-materialize" design
+ * (ExecutionEnv-seam placement/harvest with sandbox-lifecycle contracts) is demand-triggered — do not
+ * bolt it on here.
+ */
+export class FileMemoryEngineBackend {
+    /** The repo-level memory dir this backend is the authority for (engine reads it for zero-copy). */
+    directoryRoot;
+    /** B3 — the engine control plane home (ledger/scopes/shadow/quarantine/journal). Model-invisible:
+     *  NEVER under {@link directoryRoot}, always on the config-root side even for an in-repo memory dir.
+     *  The engine picks this up (like `directoryRoot`) so both sides share ONE control plane. */
+    controlPlaneRoot;
+    /** Injected clock (opus 1.258 LOW: match the engine's `this.now` determinism discipline). */
+    now;
+    /**
+     * The COMMITTED-rev ledger (`revs.json`, id → rev). Zero-copy makes it load-bearing for CAS: the
+     * entry files are the SAME files the session edits, so "read the current rev from the file" would
+     * make every legitimate update self-conflict (the file already holds the new content). The ledger
+     * records the rev as of the last COMMIT (applyPatches) — a CAS compares against IT, so an in-session
+     * edit passes (baseRev == ledger) while a concurrently-committed change conflicts (ledger advanced).
+     * Read-side (`listHeaders`/`getByIds`/`search`) SYNCS the ledger to disk THROUGH the inbound gate
+     * (B2 — out-of-session edits, e.g. a git pull into an in-repo memory dir, are secret/cap-scanned;
+     * rejects are quarantined + shadow-restored, never adopted); the applyPatches lookup does NOT sync
+     * (that would erase the very baseline CAS needs). B3: corrupt ⇒ {@link ControlPlaneCorruptError}
+     * (fail-closed), never a silent empty-ledger downgrade.
+     */
+    ledger;
+    /** B2 — inbound-gate findings accumulated by read-side syncs; the engine drains them into
+     *  `HarvestReport.inboundFindings` at harvest. */
+    inboundFindings = [];
+    /** ⚠️ [508] service 逮的分家坑:不显式传 `controlDir` 时,控制平面按无参 `resolveMemoryEngineRoot()`
+     *  派生(env/默认 config 根)——若你的记忆目录带自定义根,控制面会与记忆目录分家。自建 backend 的
+     *  consumer 应显式钉 `controlDir`(engine 同参)。`now` = 注入时钟(determinism,engine 同款)。 */
+    constructor(dir, opts = {}) {
+        this.now = opts.now ?? Date.now;
+        this.directoryRoot = dir;
+        this.controlPlaneRoot = opts.controlDir ?? deriveControlPlaneDir(resolveMemoryEngineRoot(), dir);
+        ensureDirExists(dir);
+        ensureDirExists(this.controlPlaneRoot);
+        this.recoverJournal(); // H4: roll an interrupted transaction forward before anything reads state
+    }
+    /** B3 fail-closed preflight (engine harvest duck-types this): force-reload every load-bearing
+     *  sidecar from disk; throws {@link ControlPlaneCorruptError} when one is corrupt. Also completes
+     *  any interrupted transaction (H4 recovery). */
+    checkControlPlane() {
+        this.recoverJournal();
+        this.ledger = undefined;
+        this.loadLedger();
+        registeredScopes(this.controlPlaneRoot); // throws on a corrupt scopes.json
+    }
+    /** B2 — drain the accumulated inbound-gate findings (engine harvest reporting). */
+    drainInboundFindings() {
+        const out = this.inboundFindings;
+        this.inboundFindings = [];
+        return out;
+    }
+    /** B1 — read an entry's COMMITTED content copy from the control-plane shadow (undefined = none).
+     *  The engine's missing-file recovery reads this (zero-copy: a deleted file is gone from the
+     *  directory scan, so the shadow is the only committed copy left). */
+    readCommittedShadow(id) {
+        return readSafe(this.shadowPath(id));
+    }
+    shadowPath(id) {
+        return join(this.controlPlaneRoot, SHADOW_DIR, `${id}.md`);
+    }
+    /** B2/L4 + C-F9 (S2-0) — capture a gate-rejected file into control-plane quarantine FROM THE
+     *  ALREADY-READ CONTENT (never re-reading the path — TOCTOU: the disk bytes may have been swapped
+     *  since the gate scanned them), then remove the suspect from the model-visible plane (delete →
+     *  clear in place). `detail` is set on ANY deviation from the clean path; callers escalate it into
+     *  {@link inboundFindings} (report-visible) — never a silent best-effort downgrade. */
+    quarantineFile(path, content) {
+        const dest = join(this.controlPlaneRoot, QUARANTINE_DIR, `${Date.now()}-${basename(path)}`);
+        let captured;
+        let detail;
+        try {
+            ensureDirExists(dirname(dest));
+            writeFileSync(dest, content, "utf8");
+            captured = dest;
+        }
+        catch (err) {
+            detail = `quarantine copy failed: ${err instanceof Error ? err.message : String(err)}`;
+        }
+        let removed = false;
+        try {
+            rmSync(path, { force: true });
+            removed = true;
+        }
+        catch (rmErr) {
+            try {
+                // Second rung: overwrite in place with a TOMBSTONE, not an empty string (opus review 1.257.2,
+                // mirrors the engine-side fix): in zero-copy the engine's next harvest scans this same dir —
+                // an empty husk would be minted into an empty entry; a `deleted: true` tombstone is skipped.
+                writeFileSync(path, "---\ndeleted: true\n---\n", "utf8");
+                removed = true;
+                detail = `${detail !== undefined ? `${detail}; ` : ""}delete failed (${rmErr instanceof Error ? rmErr.message : String(rmErr)}) — tombstoned in place`;
+            }
+            catch (clearErr) {
+                detail = `${detail !== undefined ? `${detail}; ` : ""}suspect file could not be deleted or cleared: ${clearErr instanceof Error ? clearErr.message : String(clearErr)}`;
+            }
+        }
+        return { ...(captured !== undefined ? { dest: captured } : {}), removed, ...(detail !== undefined ? { detail } : {}) };
+    }
+    loadLedger() {
+        if (this.ledger)
+            return this.ledger;
+        const path = join(this.controlPlaneRoot, LEDGER_FILE);
+        let raw;
+        try {
+            raw = readFileSync(path, "utf8");
+        }
+        catch {
+            raw = undefined; // absent ⇒ first run (empty ledger is the true state, not a downgrade)
+        }
+        if (raw === undefined) {
+            this.ledger = {};
+            return this.ledger;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new ControlPlaneCorruptError(`committed-rev ledger is unparseable: ${path}`);
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new ControlPlaneCorruptError(`committed-rev ledger has the wrong shape: ${path}`);
+        }
+        for (const [k, v] of Object.entries(parsed)) {
+            if (typeof v !== "string")
+                throw new ControlPlaneCorruptError(`committed-rev ledger entry ${JSON.stringify(k)} is not a string: ${path}`);
+        }
+        this.ledger = parsed;
+        return this.ledger;
+    }
+    /** B3: atomic + fail-closed — a ledger that cannot be persisted throws (the commit is incomplete
+     *  and the caller must know), never a silent swallow. */
+    saveLedger() {
+        if (!this.ledger)
+            return;
+        atomicWriteFileSync(join(this.controlPlaneRoot, LEDGER_FILE), `${JSON.stringify(this.ledger, null, 2)}\n`);
+    }
+    // ==========================================================================
+    // H4 — transaction journal (redo log) + crash recovery
+    // ==========================================================================
+    recoverJournal() {
+        const jp = join(this.controlPlaneRoot, JOURNAL_FILE);
+        const raw = readSafe(jp);
+        if (raw !== undefined) {
+            let journal;
+            try {
+                const parsed = JSON.parse(raw);
+                if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.ops) || typeof parsed.ledger !== "object") {
+                    throw new Error("wrong shape");
+                }
+                journal = parsed;
+            }
+            catch {
+                // The journal is atomically renamed into place, so a torn journal should be impossible; if it
+                // happens anyway the transaction's effects are unknowable — fail closed for a human decision.
+                throw new ControlPlaneCorruptError(`transaction journal is unparseable: ${jp}`);
+            }
+            // REDO (idempotent — the journal carries full content): finish every op, restore the ledger
+            // snapshot, then drop the journal.
+            for (const op of journal.ops) {
+                try {
+                    if (op.kind === "write" && op.content !== undefined) {
+                        atomicWriteFileSync(op.target, op.content);
+                        if (op.staged)
+                            rmSync(op.staged, { force: true });
+                    }
+                    else if (op.kind === "delete") {
+                        rmSync(op.target, { force: true });
+                    }
+                    else if (op.kind === "shadow-write" && op.content !== undefined) {
+                        atomicWriteFileSync(this.shadowPath(op.target), op.content);
+                    }
+                    else if (op.kind === "shadow-delete") {
+                        rmSync(this.shadowPath(op.target), { force: true });
+                    }
+                }
+                catch {
+                    /* per-op best effort; the ledger snapshot below is the commit marker */
+                }
+            }
+            this.ledger = { ...journal.ledger };
+            this.saveLedger();
+            rmSync(jp, { force: true });
+        }
+        this.sweepStagedFiles();
+    }
+    /** Remove orphaned `.stage-*` files (a crash BEFORE the journal rename = clean rollback: nothing
+     *  was committed, the staged tmps are litter). Dotfiles are invisible to entry scans regardless. */
+    sweepStagedFiles() {
+        const walk = (d, depth) => {
+            let names;
+            try {
+                names = readdirSync(d);
+            }
+            catch {
+                return;
+            }
+            for (const name of names) {
+                const p = join(d, name);
+                if (name.startsWith(".stage-")) {
+                    rmSync(p, { force: true });
+                    continue;
+                }
+                if (depth < DEFAULT_MAX_ENTRY_DEPTH + 1) {
+                    try {
+                        if (lstatSync(p).isDirectory())
+                            walk(p, depth + 1);
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+            }
+        };
+        walk(this.directoryRoot, 0);
+    }
+    /** The names of sibling scope subdirs to exclude when scanning the ROOT scope's own nested content. */
+    excludedSubdirNames(forScope) {
+        const reg = registeredScopes(this.controlPlaneRoot);
+        const names = new Set();
+        for (const [scope, dirName] of Object.entries(reg)) {
+            if (scope !== forScope && dirName !== "")
+                names.add(dirName);
+        }
+        return names;
+    }
+    scopeDir(scope) {
+        return registerScope(this.directoryRoot, this.controlPlaneRoot, scope);
+    }
+    /** B2 inbound gate for content that did NOT come through applyPatches (git pull / hand edits /
+     *  a hand-seeded file): secret + cap + structure. Returns the rejection, or undefined (clean). */
+    inboundGate(relPath, text) {
+        // S2-B 判决四 (入库面): the file-NAME charset whitelist guards the inbound channel too — a
+        // git-pull-borne `foo</system-reminder>bar.md` must never be adopted (its PATH is an injection
+        // payload wherever it is echoed). Shared rule (scan.ts) with the harvest/beforeWrite mounts.
+        const nameFinding = scanMemoryFileName(relPath);
+        if (nameFinding !== undefined)
+            return { path: relPath, code: "filename", reason: `inbound memory change blocked: ${nameFinding.reason} (quarantined)` };
+        // codex 1.258 review (MED): the FULL shared rule set — scanMemoryWrite = secret + injection +
+        // (with maxBytes) too_large — so an inbound git-pull change carrying a framing break-out tag is
+        // quarantined exactly like the same content would be write-rejected / harvest-rejected. One rule
+        // set, three mounts (beforeWrite / harvest / inbound), zero drift.
+        const findings = scanMemoryWrite(text, { maxBytes: MAX_MEMORY_BYTES });
+        const first = findings[0];
+        if (first !== undefined) {
+            return { path: relPath, code: first.code, reason: `inbound memory change blocked: ${first.reason} (quarantined)` };
+        }
+        return undefined;
+    }
+    /** Read every COMMITTED entry of `scope` — a file must carry a valid `id:` to count. An id-less
+     *  file is UNCOMMITTED session material: it becomes an entry only through the engine's harvest
+     *  gates (which mint the id on commit). Reading it as an entry here would let gate-rejected files
+     *  (secret / cap / quarantine) leak into the authoritative set through the zero-copy disk scan.
+     *  `sync` (read-side callers) adopts a committed file's CURRENT disk rev into the committed-rev
+     *  ledger ONLY through the inbound gate (B2: out-of-session edits, e.g. git-pull, are scanned;
+     *  a reject is moved to control-plane quarantine and the committed shadow content is restored to
+     *  disk). The applyPatches lookup passes false (the ledger must keep the baseline for CAS). */
+    readScope(scope, sync = true) {
+        const dir = this.scopeDir(scope);
+        const isRoot = dir === this.directoryRoot;
+        const files = scanEntryFiles(dir, { exclude: isRoot ? this.excludedSubdirNames(scope) : undefined });
+        const entries = [];
+        const ledger = sync ? this.loadLedger() : undefined;
+        let ledgerChanged = false;
+        // S2-B event class ② — KNOWN entries whose disk rev ≠ ledger (a git pull / hand edit adopted
+        // through the inbound gate). Announced below so the session that first SEES the change gets a
+        // session-first notice (materialize runs before inject). Hand-seeded never-committed files are
+        // NOT announced (no ledger baseline ⇒ not a "change"; first-run seeding would be pure noise).
+        const adoptedExternal = [];
+        for (const f of files) {
+            let text;
+            try {
+                text = readFileSync(f.path, "utf8");
+            }
+            catch {
+                continue;
+            }
+            const parsed = parseEntryFile(text);
+            if (parsed.id === undefined)
+                continue; // uncommitted (id-less) — only harvest can admit it
+            let entry = entryFromFile(text, parsed.id, f.slug, scope);
+            if (ledger) {
+                const committed = ledger[entry.id];
+                if (committed !== entry.rev) {
+                    // Non-committed content on disk (external channel, or a hand-seeded file the ledger never
+                    // saw): it must pass the inbound gate to be adopted as the new committed baseline (B2).
+                    const finding = this.inboundGate(relative(this.directoryRoot, f.path), text);
+                    if (finding) {
+                        this.inboundFindings.push(finding);
+                        // C-F9 (S2-0): quarantine from the already-read `text` (no path re-read — TOCTOU).
+                        const q = this.quarantineFile(f.path, text);
+                        const shadowText = committed !== undefined ? this.readCommittedShadow(entry.id) : undefined;
+                        let restoredShadow = false;
+                        if (shadowText !== undefined) {
+                            // Restore the last committed content — the entry survives, the poison does not. This is
+                            // also the third containment rung when delete/clear failed (overwrite with committed).
+                            try {
+                                atomicWriteFileSync(f.path, shadowText);
+                                restoredShadow = true;
+                            }
+                            catch {
+                                /* restore is best-effort; the entry below still serves the committed content */
+                            }
+                            entry = entryFromFile(shadowText, entry.id, f.slug, scope);
+                        }
+                        // C-F9 escalation: any quarantine deviation is REPORT-VISIBLE (drained into
+                        // HarvestReport.inboundFindings at harvest), never debug-only.
+                        if (q.detail !== undefined || (!q.removed && !restoredShadow)) {
+                            const contained = q.removed || restoredShadow;
+                            this.inboundFindings.push({
+                                path: finding.path,
+                                code: "quarantine_failed",
+                                reason: `quarantine escalation: ${q.detail ?? "suspect copy not captured"}${contained ? "" : " — rejected content may still be on the model-visible plane"}`,
+                            });
+                        }
+                        if (shadowText === undefined) {
+                            // Never committed (or shadow-less legacy): nothing to restore — the id leaves the set.
+                            if (committed !== undefined) {
+                                delete ledger[entry.id];
+                                ledgerChanged = true;
+                            }
+                            continue;
+                        }
+                    }
+                    else {
+                        if (committed !== undefined)
+                            adoptedExternal.push(relative(this.directoryRoot, f.path));
+                        ledger[entry.id] = entry.rev; // gate-passed external edit adopted as the committed baseline
+                        try {
+                            atomicWriteFileSync(this.shadowPath(entry.id), text);
+                        }
+                        catch {
+                            /* shadow backfill is best-effort */
+                        }
+                        ledgerChanged = true;
+                    }
+                }
+                else if (this.readCommittedShadow(entry.id) === undefined) {
+                    // Shadow backfill for entries committed before the shadow existed.
+                    try {
+                        atomicWriteFileSync(this.shadowPath(entry.id), text);
+                    }
+                    catch {
+                        /* best-effort */
+                    }
+                }
+            }
+            entries.push(entry);
+        }
+        if (ledgerChanged)
+            this.saveLedger();
+        if (adoptedExternal.length > 0) {
+            // Journaled + locked queue (O-F6/C-F5) — fail-open: an unwritable queue never fails a read.
+            try {
+                enqueueMemoryAnnouncement(this.controlPlaneRoot, {
+                    kind: "external",
+                    at: this.now(),
+                    items: adoptedExternal
+                        .slice(0, 12)
+                        .map((rel) => `out-of-session memory change adopted: ${JSON.stringify(inlineUntrusted(rel))} — re-read it before relying on prior knowledge of it`)
+                        .concat(adoptedExternal.length > 12 ? [`…and ${adoptedExternal.length - 12} more adopted change(s)`] : []),
+                });
+            }
+            catch {
+                /* fail-open */
+            }
+        }
+        return entries;
+    }
+    async listHeaders(scopes) {
+        const out = [];
+        for (const scope of scopes) {
+            const dir = this.scopeDir(scope);
+            for (const e of this.readScope(scope)) {
+                out.push(headerOf(e, join(dir, `${e.slug}.md`)));
+            }
+        }
+        return out;
+    }
+    async getByIds(ids) {
+        const want = new Set(ids);
+        const out = [];
+        for (const scope of Object.keys(registeredScopes(this.controlPlaneRoot))) {
+            for (const e of this.readScope(scope)) {
+                if (want.has(e.id))
+                    out.push(e);
+            }
+        }
+        return out;
+    }
+    /** Lexical floor (design/138 §2.1): `1 - Jaccard` distance over name+description+body, ascending. */
+    async search(query, scopes, opts) {
+        const limit = opts?.limit ?? 20;
+        const q = termSet(query);
+        if (q.size === 0)
+            return [];
+        const scored = [];
+        for (const scope of scopes) {
+            const dir = this.scopeDir(scope);
+            for (const e of this.readScope(scope)) {
+                const haystack = `${e.frontmatter.name ?? e.slug} ${e.frontmatter.description ?? ""} ${e.body}`;
+                const d = jaccardDistance(q, haystack);
+                if (d === null)
+                    continue;
+                scored.push({ ...headerOf(e, join(dir, `${e.slug}.md`)), score: d });
+            }
+        }
+        // S3-core (opus 审 C4): deterministic id tie-break — tied jaccard scores must not order by
+        // directory-listing accident (the Pg backend mirrors this; the cross-backend equivalence
+        // assertion compares ordered projections).
+        scored.sort((a, b) => a.score - b.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        return scored.slice(0, limit);
+    }
+    /**
+     * H4 — the entry transaction, staged and journaled:
+     *  1. RELOAD the ledger from disk (验收 M2: a concurrently-committed transaction from another
+     *     process becomes a CAS conflict here, never a blind write over it) + finish any interrupted
+     *     transaction (redo journal).
+     *  2. PLAN every patch against current state (CAS/conflicts decided now; no disk writes yet).
+     *  3. STAGE: write each new file content to a same-directory `.stage-*` tmp (fsync'd).
+     *  4. JOURNAL: atomically write the full redo log (ops with content + the post-txn ledger snapshot).
+     *     ← the commit point: a crash after this rolls FORWARD (recovery redoes the journal); a crash
+     *     before it rolls BACK (staged tmps are swept, nothing was committed).
+     *  5. EXECUTE: atomic renames / deletes / shadow updates.
+     *  6. Persist the ledger (atomic, fail-closed) and drop the journal.
+     */
+    async applyPatches(patches) {
+        // codex 复审 B5 (design/142 S2b 连带): the reload→plan→journal→execute→ledger transaction was
+        // single-writer by assumption — two instances over the SAME root (dual-root personal mount:
+        // concurrent tasks of one principal; or plain multi-process TOC) could both pass CAS on the
+        // same stale ledger, overwrite each other's journal file and silently drop the loser's commit
+        // while BOTH report applied. A cross-process mutex serializes the whole transaction; a crashed
+        // holder's lock is stolen after a deadline — safe BECAUSE recovery replays/sweeps the journal
+        // inside the lock before planning.
+        const lock = await this.acquireTxnLock();
+        try {
+            return await this.applyPatchesLocked(patches, lock.token);
+        }
+        finally {
+            lock.release();
+        }
+    }
+    txnLockDir() {
+        return join(this.controlPlaneRoot, "txn.lock");
+    }
+    /**
+     * 对抗复审 L1/L2/L3 — the mkdir mutex, hardened (same shape as layout.ts' acquireSidecarLock, but
+     * fail-closed timings and an async wait):
+     *  - L2: every acquisition writes an OWNER TOKEN (`<lock>/owner`, crypto-random — never a
+     *    timestamp) immediately after mkdir. Release only removes the lock while the token is still
+     *    ours; {@link assertTxnLockOwnership} re-verifies it at the commit point.
+     *  - L1: the stale steal is SINGLE-WINNER — atomic rename of the stale lock dir to a unique
+     *    tombstone (exactly one racer's rename succeeds; losers ENOENT back into the wait loop), then
+     *    the winner removes the tombstone and re-acquires through a NORMAL mkdir. Never a bare
+     *    rmSync+mkdir (two same-window stealers would force-rm each other's FRESH lock = double hold).
+     *  - L2 (steal side): only a lock that is BOTH past its stale line AND carries an owner token is
+     *    stealable (a tokenless dir is a mid-acquisition, not a crashed holder).
+     *  - L3: the wait deadline is `max(waitMs, observed lock's stale line + grace)` — a holder that
+     *    crashed with `remaining stale > waitMs` no longer strands every waiter in an all-throw window.
+     */
+    async acquireTxnLock(timings = {}) {
+        const staleMs = timings.staleMs ?? TXN_LOCK_STALE_MS;
+        const waitMs = timings.waitMs ?? TXN_LOCK_WAIT_MS;
+        const stealGraceMs = timings.stealGraceMs ?? TXN_LOCK_STEAL_GRACE_MS;
+        const lockDir = this.txnLockDir();
+        const ownerPath = join(lockDir, "owner");
+        mkdirSync(this.controlPlaneRoot, { recursive: true });
+        const start = Date.now();
+        let deadline = start + waitMs;
+        for (;;) {
+            let acquired = false;
+            try {
+                mkdirSync(lockDir); // NOT recursive: recursive:true reports success on an EXISTING dir
+                acquired = true;
+            }
+            catch (err) {
+                if (err.code !== "EEXIST")
+                    throw err;
+            }
+            if (acquired) {
+                // L2: the token names THIS acquisition. Written (fsync'd) before we return — a lock without
+                // it is never stolen, so failing the write must release the dir and surface (fail-closed).
+                const token = randomUUID();
+                try {
+                    const fd = openSync(ownerPath, "w", 0o600);
+                    try {
+                        writeSync(fd, token);
+                        fsyncSync(fd);
+                    }
+                    finally {
+                        closeSync(fd);
+                    }
+                }
+                catch (err) {
+                    try {
+                        rmSync(lockDir, { recursive: true, force: true });
+                    }
+                    catch {
+                        /* best-effort — a tokenless leftover is unstealable but times waiters out loudly */
+                    }
+                    throw new Error(`memory txn lock owner token could not be written at ${ownerPath}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                return {
+                    token,
+                    release: () => {
+                        try {
+                            if (readFileSync(ownerPath, "utf8") !== token)
+                                return; // stolen while we stalled — the lock is someone else's now
+                        }
+                        catch {
+                            return; // lock already gone (stolen + tombstoned) — nothing of ours left to release
+                        }
+                        try {
+                            rmSync(lockDir, { recursive: true, force: true });
+                        }
+                        catch {
+                            /* release is best-effort — a leaked lock is stolen after the stale deadline */
+                        }
+                    },
+                };
+            }
+            // Lock exists — decide steal / wait / timeout.
+            let mtimeMs;
+            try {
+                mtimeMs = statSync(lockDir).mtimeMs;
+            }
+            catch {
+                continue; // raced with the holder's release — retry the mkdir immediately
+            }
+            const staleAt = mtimeMs + staleMs;
+            deadline = Math.max(deadline, staleAt + stealGraceMs); // L3: reach the stale line + one steal attempt
+            if (Date.now() > staleAt) {
+                let tokenPresent = false;
+                try {
+                    statSync(ownerPath);
+                    tokenPresent = true;
+                }
+                catch {
+                    /* tokenless = mid-acquisition (or already renamed away) — not stealable */
+                }
+                if (tokenPresent) {
+                    // L1 single-winner steal (see doc above).
+                    const tomb = join(this.controlPlaneRoot, `txn.lock.stale-${randomUUID()}`);
+                    try {
+                        renameSync(lockDir, tomb);
+                    }
+                    catch {
+                        continue; // another waiter stole it (or the holder released) — back to the wait loop
+                    }
+                    rmSync(tomb, { recursive: true, force: true });
+                    continue; // stolen: re-acquire through a NORMAL mkdir (journal recovery inside the lock covers the crashed txn)
+                }
+            }
+            if (Date.now() > deadline) {
+                throw new Error(`memory txn lock timeout (${waitMs}ms, extended to the lock's stale line) at ${lockDir} — another writer is wedged?`);
+            }
+            await new Promise((r) => setTimeout(r, 20 + Math.floor(Math.random() * 40)));
+        }
+    }
+    /** 对抗复审 L2 — 提交点归属复验: called immediately before the JOURNAL write (the persistent commit
+     *  point). A holder that stalled past the stale deadline (slow disk / GC pause / long txn) and was
+     *  stolen from must ABORT — its staged tmps carry no committed state and the stealer's journal
+     *  recovery is now authoritative; committing anyway would overwrite the stealer's transaction. */
+    assertTxnLockOwnership(token) {
+        let held;
+        try {
+            held = readFileSync(join(this.txnLockDir(), "owner"), "utf8");
+        }
+        catch {
+            held = undefined; // lock dir gone = stolen (we ALWAYS write a token on acquire)
+        }
+        if (held !== token) {
+            throw new ControlPlaneCorruptError("txn lock ownership lost before commit (holder stalled past the stale deadline and was stolen from?) — transaction aborted, nothing was committed");
+        }
+    }
+    async applyPatchesLocked(patches, lockToken) {
+        this.ledger = undefined; // M2: reload from disk — cross-process commits must be visible to CAS
+        this.recoverJournal();
+        const ledger = { ...this.loadLedger() };
+        const report = { applied: [], conflicts: [] };
+        const ops = [];
+        const plannedTargets = new Set();
+        // codex review (1.257.2): at most ONE non-delete op per id per batch. A rename legitimately pairs
+        // delete(X)+update(X); but two adds/updates for the same id (a COPY that kept its frontmatter id)
+        // would leave the caller's projection↔applied binding ambiguous — refuse the later one as a
+        // conflict so the committed-restore path handles its file instead of promoting unsanctioned content.
+        const nonDeleteIds = new Set();
+        for (const patch of patches) {
+            try {
+                if (patch.op !== "delete") {
+                    // S3-core (codex 审): a patch whose entry carries a DIFFERENT id than the patch addresses is
+                    // malformed — refused up front, byte-uniform with the Pg backend (which would otherwise key
+                    // its SELECT on patch.id but its write on entry.id).
+                    if (patch.entry !== undefined && patch.entry.id !== patch.id) {
+                        report.conflicts.push({ op: patch.op, id: patch.id, reason: `patch id ${JSON.stringify(patch.id)} != entry id ${JSON.stringify(patch.entry.id)} (malformed patch refused)` });
+                        continue;
+                    }
+                    if (nonDeleteIds.has(patch.id)) {
+                        report.conflicts.push({ op: patch.op, id: patch.id, reason: "duplicate id in batch: another add/update for this id is already planned (copied file keeping its frontmatter id?)" });
+                        continue;
+                    }
+                    nonDeleteIds.add(patch.id);
+                }
+                this.planOne(patch, report, ops, ledger, plannedTargets);
+            }
+            catch (err) {
+                report.conflicts.push({ op: patch.op, id: patch.id, reason: `io error: ${err instanceof Error ? err.message : String(err)}` });
+            }
+        }
+        if (ops.length === 0) {
+            // Nothing to write — still persist the (unchanged) ledger view? No: no-op transactions must not
+            // touch the sidecars at all.
+            return report;
+        }
+        // STAGE: durable tmp files next to their targets (same-dir rename atomicity).
+        const txn = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        let n = 0;
+        for (const op of ops) {
+            if (op.kind !== "write" || op.content === undefined)
+                continue;
+            const staged = join(dirname(op.target), `.stage-${txn}-${n++}`);
+            mkdirSync(dirname(op.target), { recursive: true });
+            const fd = openSync(staged, "w", 0o600);
+            try {
+                writeSync(fd, op.content);
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+            op.staged = staged;
+        }
+        // JOURNAL (the commit marker) — atomic rename means it either exists complete or not at all.
+        // L2: 归属复验 first — never write the commit marker after the lock was stolen from us.
+        this.assertTxnLockOwnership(lockToken);
+        const journal = { txn, ops, ledger };
+        atomicWriteFileSync(join(this.controlPlaneRoot, JOURNAL_FILE), JSON.stringify(journal));
+        // EXECUTE.
+        for (const op of ops) {
+            if (op.kind === "write" && op.staged) {
+                renameSync(op.staged, op.target);
+            }
+            else if (op.kind === "delete") {
+                rmSync(op.target, { force: true });
+            }
+            else if (op.kind === "shadow-write" && op.content !== undefined) {
+                atomicWriteFileSync(this.shadowPath(op.target), op.content);
+            }
+            else if (op.kind === "shadow-delete") {
+                rmSync(this.shadowPath(op.target), { force: true });
+            }
+        }
+        // COMMIT the ledger (atomic; throws = fail-closed, the journal stays for redo) then drop the journal.
+        this.ledger = ledger;
+        this.saveLedger();
+        rmSync(join(this.controlPlaneRoot, JOURNAL_FILE), { force: true });
+        return report;
+    }
+    /** Plan one patch: decide CAS/conflicts against CURRENT state, emit journal ops (no entry-file
+     *  writes here — staging/execution happen in {@link applyPatches}). */
+    planOne(patch, report, ops, ledger, plannedTargets) {
+        if (patch.op === "add") {
+            const entry = patch.entry;
+            if (!entry) {
+                report.conflicts.push({ op: "add", id: patch.id, reason: "add patch without an entry" });
+                return;
+            }
+            // E-02 add-if-absent guard (design/142 S2.5): a `guard: "absent"` add must NEVER blind-overwrite
+            // an existing id. If the id already exists, compare revs — same rev = idempotent apply (fall
+            // through to the normal add path, which zero-copy re-writes the same content), DIFFERENT rev =
+            // a reported conflict carrying the current rev, never a write. A plain (unguarded) add keeps the
+            // idempotent-overwrite semantics (contract clause unchanged) — this branch only runs when armed.
+            if (patch.guard === "absent") {
+                const existing = this.locateById(patch.id);
+                if (existing) {
+                    const currentRev = ledger[patch.id] ?? existing.entry.rev;
+                    if (currentRev !== computeEntryRev(entry)) {
+                        report.conflicts.push({ op: "add", id: patch.id, reason: "add_guard_absent_conflict (id already exists at a different rev; add-if-absent refuses to overwrite)", currentRev });
+                        return;
+                    }
+                    // 三轮复查 (2026-07-12): same rev alone is NOT the idempotence proof — computeEntryRev hashes
+                    // (id, frontmatter, body) but neither slug nor scope, so an existing copy at a DIFFERENT
+                    // projection (renamed slug, or another scope after a central cross-scope move) would make the
+                    // "no-op re-write" below mint a SECOND file for the same id (duplicate projection: getByIds
+                    // then returns the id twice — the id-as-unit-of-truth invariant breaks). Idempotent ⇔ same
+                    // rev AND same (scope, slug); a projection mismatch is a REPORTED conflict, never a write.
+                    if (existing.entry.scope !== entry.scope || existing.entry.slug !== entry.slug) {
+                        report.conflicts.push({
+                            op: "add",
+                            id: patch.id,
+                            reason: `add_guard_absent_conflict (id already exists at the same rev but a different projection ${JSON.stringify(`${existing.entry.scope}/${existing.entry.slug}`)}; add-if-absent refuses to duplicate)`,
+                            currentRev,
+                        });
+                        return;
+                    }
+                    // same rev AND same projection ⇒ idempotent; fall through to the normal add (a zero-copy no-op re-write).
+                }
+            }
+            // First-ever write claims the root for its scope (the engine claims for writeScope at
+            // materialize; this is the standalone-usage counterpart — first-writer-wins, durable).
+            claimRootScope(this.controlPlaneRoot, entry.scope);
+            const dir = this.scopeDir(entry.scope);
+            let slug = entry.slug;
+            let target = join(dir, `${slug}.md`);
+            // Slug collision with a DIFFERENT entry (same slug, other id) → deterministic suffix. In-batch
+            // planned targets count as taken too (two adds of one slug in one transaction).
+            for (let n = 2;; n++) {
+                const existing = plannedTargets.has(target) ? "" : readSafe(target);
+                if (existing === undefined)
+                    break;
+                if (existing !== "") {
+                    const parsed = parseEntryFile(existing);
+                    if (parsed.id === undefined || parsed.id === entry.id)
+                        break; // same entry (zero-copy re-write) or claimable
+                }
+                slug = `${entry.slug}-${n}`;
+                target = join(dir, `${slug}.md`);
+            }
+            const content = serializeEntryFile(entry);
+            plannedTargets.add(target);
+            ops.push({ kind: "write", target, content });
+            ops.push({ kind: "shadow-write", target: entry.id, content });
+            ledger[entry.id] = computeEntryRev(entry);
+            report.applied.push({ op: "add", id: entry.id, slug });
+            return;
+        }
+        // update/delete address an EXISTING entry by immutable id.
+        const found = this.locateById(patch.id, patch.op === "update" ? patch.entry?.scope : undefined);
+        if (!found) {
+            report.conflicts.push({ op: patch.op, id: patch.id, reason: "unknown id (entry not found in backend)" });
+            return;
+        }
+        // CAS against the COMMITTED-rev ledger (see its docs) — the on-disk rev is the fallback only when
+        // the ledger has no record (a hand-seeded file never committed through this backend).
+        const currentRev = ledger[patch.id] ?? found.entry.rev;
+        if (patch.baseRev !== undefined && patch.baseRev !== currentRev) {
+            // Per-id CAS (§2.4 并发): NEVER blind-write over a concurrent change — report; the next task
+            // re-materializes the fresh state. B2: the conflicted DISK content is not left to be adopted as
+            // a new baseline by the next read-side sync — restore the committed shadow (the CAS winner).
+            report.conflicts.push({ op: patch.op, id: patch.id, reason: "rev mismatch (concurrent change)", baseRev: patch.baseRev, currentRev });
+            const shadowText = this.readCommittedShadow(patch.id);
+            if (shadowText !== undefined && shadowText !== serializeEntryFile(found.entry)) {
+                ops.push({ kind: "write", target: found.path, content: shadowText });
+            }
+            return;
+        }
+        if (patch.op === "delete") {
+            ops.push({ kind: "delete", target: found.path });
+            ops.push({ kind: "shadow-delete", target: patch.id });
+            delete ledger[patch.id];
+            report.applied.push({ op: "delete", id: patch.id, slug: found.entry.slug });
+            return;
+        }
+        const entry = patch.entry;
+        if (!entry) {
+            report.conflicts.push({ op: "update", id: patch.id, reason: "update patch without an entry" });
+            return;
+        }
+        const dir = this.scopeDir(entry.scope);
+        const target = join(dir, `${entry.slug}.md`);
+        const content = serializeEntryFile(entry);
+        if (target !== found.path)
+            ops.push({ kind: "delete", target: found.path }); // slug rename: old projection removed
+        plannedTargets.add(target);
+        ops.push({ kind: "write", target, content });
+        ops.push({ kind: "shadow-write", target: entry.id, content });
+        ledger[entry.id] = computeEntryRev(entry);
+        report.applied.push({ op: "update", id: entry.id, slug: entry.slug });
+    }
+    locateById(id, preferScope) {
+        const scopes = Object.keys(registeredScopes(this.controlPlaneRoot));
+        const ordered = preferScope !== undefined ? [preferScope, ...scopes.filter((s) => s !== preferScope)] : scopes;
+        for (const scope of ordered) {
+            const dir = this.scopeDir(scope);
+            // sync=false: the applyPatches lookup must NOT adopt in-session disk edits into the ledger —
+            // that would erase the committed baseline the CAS above compares against.
+            for (const e of this.readScope(scope, false)) {
+                if (e.id === id)
+                    return { entry: e, path: join(dir, `${e.slug}.md`) };
+            }
+        }
+        return undefined;
+    }
+    // design/84 Seam B cursor pair — durable control-plane `cursors.json` (S2 rewires consolidation).
+    async getConsolidationCursor(scope) {
+        const cursors = this.readCursors();
+        return cursors[scope];
+    }
+    async setConsolidationCursor(scope, cursor) {
+        const cursors = this.readCursors();
+        cursors[scope] = cursor;
+        atomicWriteFileSync(join(this.controlPlaneRoot, CURSORS_FILE), `${JSON.stringify(cursors, null, 2)}\n`);
+    }
+    readCursors() {
+        try {
+            const parsed = JSON.parse(readFileSync(join(this.controlPlaneRoot, CURSORS_FILE), "utf8"));
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                return Object.fromEntries(Object.entries(parsed).filter(([, v]) => typeof v === "string"));
+            }
+        }
+        catch {
+            /* absent/corrupt ⇒ no cursors (a periodic pass then sweeps from the start — safe: cursors are
+               an optimization, not a CAS baseline, so this one sidecar stays fail-open by design) */
+        }
+        return {};
+    }
+}
+function headerOf(e, path) {
+    let mtimeMs = 0;
+    try {
+        mtimeMs = statSync(path).mtimeMs;
+    }
+    catch {
+        /* header stays age-less (rendered as oldest) */
+    }
+    return {
+        id: e.id,
+        slug: e.slug,
+        scope: e.scope,
+        ...(e.frontmatter.name !== undefined ? { name: e.frontmatter.name } : {}),
+        ...(e.frontmatter.description !== undefined ? { description: e.frontmatter.description } : {}),
+        ...(e.frontmatter.type !== undefined ? { type: e.frontmatter.type } : {}),
+        mtimeMs,
+        rev: e.rev,
+        sizeBytes: Buffer.byteLength(serializeEntryFile(e), "utf8"),
+    };
+}
+function readSafe(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+// Re-export for engine use (single scan definition — see scanEntryFiles docs).
+export { scopeDirName };
+//# sourceMappingURL=file-backend.js.map