@sema-agent/core 1.279.0

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

@@ -0,0 +1,752 @@
+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, isValidEntryId, 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";
+export const MEMORY_INDEX_FILENAME = "MEMORY.md";
+export const DEFAULT_MAX_ENTRY_DEPTH = 3;
+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;
+        }
+        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");
+                continue;
+            }
+            if (st.isDirectory()) {
+                if (depth === 0 && opts.exclude?.has(name))
+                    continue;
+                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";
+const TXN_LOCK_STALE_MS = 30_000;
+const TXN_LOCK_WAIT_MS = 15_000;
+const TXN_LOCK_STEAL_GRACE_MS = 250;
+const SHADOW_DIR = "shadow";
+const QUARANTINE_DIR = "quarantine";
+export class FileMemoryEngineBackend {
+    directoryRoot;
+    controlPlaneRoot;
+    now;
+    ledger;
+    inboundFindings = [];
+    batchScan;
+    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();
+    }
+    checkControlPlane() {
+        this.recoverJournal();
+        this.ledger = undefined;
+        this.loadLedger();
+        registeredScopes(this.controlPlaneRoot);
+    }
+    drainInboundFindings() {
+        const out = this.inboundFindings;
+        this.inboundFindings = [];
+        return out;
+    }
+    readCommittedShadow(id) {
+        return readSafe(this.shadowPath(id));
+    }
+    shadowPath(id) {
+        return join(this.controlPlaneRoot, SHADOW_DIR, `${id}.md`);
+    }
+    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 {
+                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;
+        }
+        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;
+    }
+    saveLedger() {
+        if (!this.ledger)
+            return;
+        atomicWriteFileSync(join(this.controlPlaneRoot, LEDGER_FILE), `${JSON.stringify(this.ledger, null, 2)}\n`);
+    }
+    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 {
+                throw new ControlPlaneCorruptError(`transaction journal is unparseable: ${jp}`);
+            }
+            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 {
+                }
+            }
+            this.ledger = { ...journal.ledger };
+            this.saveLedger();
+            rmSync(jp, { force: true });
+        }
+        this.sweepStagedFiles();
+    }
+    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 {
+                    }
+                }
+            }
+        };
+        walk(this.directoryRoot, 0);
+    }
+    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);
+    }
+    inboundGate(relPath, text) {
+        const nameFinding = scanMemoryFileName(relPath);
+        if (nameFinding !== undefined)
+            return { path: relPath, code: "filename", reason: `inbound memory change blocked: ${nameFinding.reason} (quarantined)` };
+        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;
+    }
+    readScope(scope, sync = true) {
+        if (!sync && this.batchScan !== undefined) {
+            const memo = this.batchScan.get(scope);
+            if (memo !== undefined)
+                return memo;
+        }
+        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;
+        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;
+            let entry = entryFromFile(text, parsed.id, f.slug, scope);
+            if (ledger) {
+                const committed = ledger[entry.id];
+                if (committed !== entry.rev) {
+                    const finding = this.inboundGate(relative(this.directoryRoot, f.path), text);
+                    if (finding) {
+                        this.inboundFindings.push(finding);
+                        const q = this.quarantineFile(f.path, text);
+                        const shadowText = committed !== undefined ? this.readCommittedShadow(entry.id) : undefined;
+                        let restoredShadow = false;
+                        if (shadowText !== undefined) {
+                            try {
+                                atomicWriteFileSync(f.path, shadowText);
+                                restoredShadow = true;
+                            }
+                            catch {
+                            }
+                            entry = entryFromFile(shadowText, entry.id, f.slug, scope);
+                        }
+                        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) {
+                            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;
+                        try {
+                            atomicWriteFileSync(this.shadowPath(entry.id), text);
+                        }
+                        catch {
+                        }
+                        ledgerChanged = true;
+                    }
+                }
+                else if (this.readCommittedShadow(entry.id) === undefined) {
+                    try {
+                        atomicWriteFileSync(this.shadowPath(entry.id), text);
+                    }
+                    catch {
+                    }
+                }
+            }
+            entries.push(entry);
+        }
+        if (ledgerChanged)
+            this.saveLedger();
+        if (adoptedExternal.length > 0) {
+            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 {
+            }
+        }
+        if (!sync && this.batchScan !== undefined)
+            this.batchScan.set(scope, entries);
+        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;
+    }
+    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 });
+            }
+        }
+        scored.sort((a, b) => a.score - b.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        return scored.slice(0, limit);
+    }
+    async applyPatches(patches) {
+        const lock = await this.acquireTxnLock();
+        try {
+            return await this.applyPatchesLocked(patches, lock.token);
+        }
+        finally {
+            lock.release();
+        }
+    }
+    txnLockDir() {
+        return join(this.controlPlaneRoot, "txn.lock");
+    }
+    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);
+                acquired = true;
+            }
+            catch (err) {
+                if (err.code !== "EEXIST")
+                    throw err;
+            }
+            if (acquired) {
+                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 {
+                    }
+                    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;
+                        }
+                        catch {
+                            return;
+                        }
+                        try {
+                            rmSync(lockDir, { recursive: true, force: true });
+                        }
+                        catch {
+                        }
+                    },
+                };
+            }
+            let mtimeMs;
+            try {
+                mtimeMs = statSync(lockDir).mtimeMs;
+            }
+            catch {
+                continue;
+            }
+            const staleAt = mtimeMs + staleMs;
+            deadline = Math.max(deadline, staleAt + stealGraceMs);
+            if (Date.now() > staleAt) {
+                let tokenPresent = false;
+                try {
+                    statSync(ownerPath);
+                    tokenPresent = true;
+                }
+                catch {
+                }
+                if (tokenPresent) {
+                    const tomb = join(this.controlPlaneRoot, `txn.lock.stale-${randomUUID()}`);
+                    try {
+                        renameSync(lockDir, tomb);
+                    }
+                    catch {
+                        continue;
+                    }
+                    rmSync(tomb, { recursive: true, force: true });
+                    continue;
+                }
+            }
+            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)));
+        }
+    }
+    assertTxnLockOwnership(token) {
+        let held;
+        try {
+            held = readFileSync(join(this.txnLockDir(), "owner"), "utf8");
+        }
+        catch {
+            held = undefined;
+        }
+        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;
+        this.recoverJournal();
+        const ledger = { ...this.loadLedger() };
+        const report = { applied: [], conflicts: [] };
+        const ops = [];
+        const plannedTargets = new Set();
+        const nonDeleteIds = new Set();
+        const plannedDeletes = new Set();
+        this.batchScan = new Map();
+        try {
+            for (const patch of patches) {
+                try {
+                    if (patch.op !== "delete") {
+                        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, plannedDeletes);
+                }
+                catch (err) {
+                    report.conflicts.push({ op: patch.op, id: patch.id, reason: `io error: ${err instanceof Error ? err.message : String(err)}` });
+                }
+            }
+        }
+        finally {
+            this.batchScan = undefined;
+        }
+        if (ops.length === 0) {
+            return report;
+        }
+        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;
+        }
+        this.assertTxnLockOwnership(lockToken);
+        const journal = { txn, ops, ledger };
+        atomicWriteFileSync(join(this.controlPlaneRoot, JOURNAL_FILE), JSON.stringify(journal));
+        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 });
+            }
+        }
+        this.ledger = ledger;
+        this.saveLedger();
+        rmSync(join(this.controlPlaneRoot, JOURNAL_FILE), { force: true });
+        return report;
+    }
+    planOne(patch, report, ops, ledger, plannedTargets, plannedDeletes) {
+        if (!isValidEntryId(patch.id)) {
+            report.conflicts.push({ op: patch.op, id: patch.id, reason: `invalid_id_shape (id ${JSON.stringify(patch.id)} fails the frontmatter id contract — the read side would drop it, leaving an applied-but-invisible entry)` });
+            return;
+        }
+        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;
+            }
+            const locatedAnywhere = this.locateById(patch.id);
+            const existingAnywhere = locatedAnywhere !== undefined && plannedDeletes.has(patch.id) ? undefined : locatedAnywhere;
+            if (patch.guard === "absent") {
+                if (existingAnywhere) {
+                    const currentRev = ledger[patch.id] ?? existingAnywhere.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;
+                    }
+                    if (existingAnywhere.entry.scope !== entry.scope || existingAnywhere.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(`${existingAnywhere.entry.scope}/${existingAnywhere.entry.slug}`)}; add-if-absent refuses to duplicate)`,
+                            currentRev,
+                        });
+                        return;
+                    }
+                }
+            }
+            if (existingAnywhere !== undefined && existingAnywhere.entry.scope !== entry.scope) {
+                report.conflicts.push({ op: "add", id: patch.id, reason: `id already exists in scope ${JSON.stringify(existingAnywhere.entry.scope)} (cross-scope add refused)` });
+                return;
+            }
+            if (existingAnywhere !== undefined && existingAnywhere.entry.slug !== entry.slug) {
+                ops.push({ kind: "delete", target: existingAnywhere.path });
+            }
+            claimRootScope(this.controlPlaneRoot, entry.scope);
+            const dir = this.scopeDir(entry.scope);
+            let slug = entry.slug;
+            let target = join(dir, `${slug}.md`);
+            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;
+                }
+                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;
+        }
+        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;
+        }
+        const currentRev = ledger[patch.id] ?? found.entry.rev;
+        if (patch.baseRev !== undefined && patch.baseRev !== currentRev) {
+            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];
+            plannedDeletes.add(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 });
+        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);
+            for (const e of this.readScope(scope, false)) {
+                if (e.id === id)
+                    return { entry: e, path: join(dir, `${e.slug}.md`) };
+            }
+        }
+        return undefined;
+    }
+    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 {
+        }
+        return {};
+    }
+}
+function headerOf(e, path) {
+    let mtimeMs = 0;
+    try {
+        mtimeMs = statSync(path).mtimeMs;
+    }
+    catch {
+    }
+    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;
+    }
+}
+export { scopeDirName };
+//# sourceMappingURL=file-backend.js.map