@sema-agent/core 5.31.0 → 5.33.0

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

@@ -5,7 +5,7 @@ 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, QUARANTINE_DIR, atomicWriteFileSync, quarantineAndTombstone, claimRootScope, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, ensureDirExists, enqueueMemoryAnnouncement, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirName, writeAllSync, } from "./layout.js";
+import { ControlPlaneCorruptError, CURSORS_FILE, QUARANTINE_DIR, atomicWriteFileSync, quarantineAndTombstone, claimRootScope, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, ensureDirExists, enqueueMemoryAnnouncement, isContainedIn, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, writeAllSync, } from "./layout.js";
 import { scanMemoryFileName, scanMemoryWrite } from "./scan.js";
 export const MEMORY_INDEX_FILENAME = "MEMORY.md";
 export const DEFAULT_MAX_ENTRY_DEPTH = 3;
@@ -63,16 +63,257 @@ export function scanEntryFiles(dir, opts = {}) {
     return out;
 }
 const LEDGER_FILE = "revs.json";
+const LEDGER_SCHEMA_VERSION = 2;
+const LEDGER_V1_BACKUP_FILE = "revs.v1.json.bak";
+const TRANSFERS_FILE = "transfers.jsonl";
 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";
+function rowsRev(rows, id) {
+    return rows[id]?.rev;
+}
+function rowsBinding(rows, id) {
+    const row = rows[id];
+    if (row === undefined || typeof row.scope !== "string" || typeof row.slug !== "string")
+        return undefined;
+    return { scope: row.scope, slug: row.slug };
+}
+function rowsEntries(rows) {
+    return Object.entries(rows);
+}
+function deleteRow(rows, id) {
+    delete rows[id];
+}
+function hasUnboundRows(rows) {
+    return rowsEntries(rows).some(([id]) => rowsBinding(rows, id) === undefined);
+}
+function unboundRowIds(rows) {
+    return rowsEntries(rows)
+        .filter(([id]) => rowsBinding(rows, id) === undefined)
+        .map(([id]) => id);
+}
+function bindingEquals(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    return a.scope === b.scope && a.slug === b.slug;
+}
+function bindRowTracked(rows, id, next, transfers, channel) {
+    const old = rows[id];
+    const oldBinding = rowsBinding(rows, id);
+    const row = { ...(old ?? {}), rev: next.rev, scope: next.scope, slug: next.slug, at: next.at };
+    if (oldBinding !== undefined && !bindingEquals(oldBinding, { scope: next.scope, slug: next.slug })) {
+        row.prev = { scope: oldBinding.scope, slug: oldBinding.slug, at: next.at };
+        transfers.push({ ev: randomUUID(), channel, id, from: oldBinding, to: { scope: next.scope, slug: next.slug }, at: next.at });
+    }
+    else if (old !== undefined && oldBinding === undefined) {
+        transfers.push({ ev: randomUUID(), channel: "migration-bind", id, to: { scope: next.scope, slug: next.slug }, at: next.at });
+    }
+    rows[id] = row;
+}
+function cloneRows(rows) {
+    const out = {};
+    for (const [id, row] of rowsEntries(rows))
+        out[id] = { ...row, ...(row.prev !== undefined ? { prev: { ...row.prev } } : {}) };
+    return out;
+}
+function ledgerEnvelope(rows, extras) {
+    return { v: LEDGER_SCHEMA_VERSION, ...(extras ?? {}), rows };
+}
+function slugEscapes(slug) {
+    if (slug.length === 0 || slug.startsWith("/") || slug.includes("\\"))
+        return true;
+    return slug.split("/").some((seg) => seg === "" || seg === "." || seg === "..");
+}
+function validateLedgerRowsV2(rowsRaw, path) {
+    if (!rowsRaw || typeof rowsRaw !== "object" || Array.isArray(rowsRaw)) {
+        throw new ControlPlaneCorruptError(`committed-rev ledger rows have the wrong shape: ${path}`);
+    }
+    const out = {};
+    for (const [id, rowRaw] of Object.entries(rowsRaw)) {
+        if (!rowRaw || typeof rowRaw !== "object" || Array.isArray(rowRaw)) {
+            throw new ControlPlaneCorruptError(`committed-rev ledger row ${JSON.stringify(id)} has the wrong shape: ${path}`);
+        }
+        const row = rowRaw;
+        if (typeof row.rev !== "string") {
+            throw new ControlPlaneCorruptError(`committed-rev ledger row ${JSON.stringify(id)} has no string rev: ${path}`);
+        }
+        const hasScope = row.scope !== undefined;
+        const hasSlug = row.slug !== undefined;
+        if (hasScope !== hasSlug) {
+            throw new ControlPlaneCorruptError(`committed-rev ledger row ${JSON.stringify(id)} is half-bound (scope and slug must appear together): ${path}`);
+        }
+        if (hasScope && (typeof row.scope !== "string" || typeof row.slug !== "string")) {
+            throw new ControlPlaneCorruptError(`committed-rev ledger row ${JSON.stringify(id)} has a non-string binding: ${path}`);
+        }
+        if (typeof row.slug === "string" && slugEscapes(row.slug)) {
+            throw new ControlPlaneCorruptError(`committed-rev ledger row ${JSON.stringify(id)} has a path-escaping slug: ${path}`);
+        }
+        if (row.at !== undefined && (typeof row.at !== "number" || !Number.isInteger(row.at))) {
+            throw new ControlPlaneCorruptError(`committed-rev ledger row ${JSON.stringify(id)} has a non-integer 'at': ${path}`);
+        }
+        if (row.prev !== undefined) {
+            const prev = row.prev;
+            if (!prev || typeof prev !== "object" || Array.isArray(prev) || typeof prev.scope !== "string" || typeof prev.slug !== "string" || typeof prev.at !== "number" || !Number.isInteger(prev.at)) {
+                throw new ControlPlaneCorruptError(`committed-rev ledger row ${JSON.stringify(id)} has a malformed 'prev' trace: ${path}`);
+            }
+            if (slugEscapes(prev.slug)) {
+                throw new ControlPlaneCorruptError(`committed-rev ledger row ${JSON.stringify(id)} has a path-escaping 'prev' slug: ${path}`);
+            }
+        }
+        out[id] = { ...row };
+    }
+    return out;
+}
+function parseLedgerText(raw, path) {
+    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}`);
+    }
+    const rec = parsed;
+    if ("v" in rec) {
+        const v = rec.v;
+        if (typeof v !== "number" || !Number.isInteger(v)) {
+            throw new ControlPlaneCorruptError(`committed-rev ledger schema version is not an integer: ${path}`);
+        }
+        if (v > LEDGER_SCHEMA_VERSION) {
+            throw new ControlPlaneCorruptError(`committed-rev ledger schema v${v} is newer than this engine supports (v${LEDGER_SCHEMA_VERSION}) — refusing to reinterpret it: ${path}`);
+        }
+        if (v !== LEDGER_SCHEMA_VERSION) {
+            throw new ControlPlaneCorruptError(`committed-rev ledger has an unknown enveloped schema v${v}: ${path}`);
+        }
+        const rows = validateLedgerRowsV2(rec.rows, path);
+        const envelopeExtras = {};
+        for (const [k, val] of Object.entries(rec)) {
+            if (k !== "v" && k !== "rows")
+                envelopeExtras[k] = val;
+        }
+        return { form: "v2", rows, envelopeExtras };
+    }
+    const rows = {};
+    for (const [k, v] of Object.entries(rec)) {
+        if (typeof v !== "string") {
+            throw new ControlPlaneCorruptError(`committed-rev ledger entry ${JSON.stringify(k)} is not a string: ${path}`);
+        }
+        rows[k] = { rev: v };
+    }
+    return { form: "v1", rows };
+}
+function transferEventInvalid(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return "event is not an object";
+    const e = raw;
+    if (typeof e.ev !== "string" || e.ev.length === 0)
+        return "missing event id 'ev'";
+    if (typeof e.at !== "number" || !Number.isInteger(e.at))
+        return "missing/non-integer 'at'";
+    const bindingInvalid = (b) => {
+        if (!b || typeof b !== "object" || Array.isArray(b))
+            return true;
+        const r = b;
+        return typeof r.scope !== "string" || typeof r.slug !== "string";
+    };
+    if (e.channel === "migration") {
+        if (typeof e.boundRows !== "number" || !Number.isInteger(e.boundRows))
+            return "migration summary missing integer 'boundRows'";
+        if (typeof e.unboundRows !== "number" || !Number.isInteger(e.unboundRows))
+            return "migration summary missing integer 'unboundRows'";
+        if (e.id !== undefined || e.from !== undefined || e.to !== undefined)
+            return "migration summary must not carry id/from/to";
+        return undefined;
+    }
+    if (e.channel === "adopted-move" || e.channel === "applyPatches-move" || e.channel === "migration-bind") {
+        if (typeof e.id !== "string" || e.id.length === 0)
+            return "row transfer missing 'id'";
+        if (bindingInvalid(e.to))
+            return "row transfer missing/malformed 'to'";
+        if (e.channel === "migration-bind") {
+            if (e.from !== undefined && bindingInvalid(e.from))
+                return "malformed 'from'";
+        }
+        else if (bindingInvalid(e.from)) {
+            return `'${e.channel}' requires a well-formed 'from'`;
+        }
+        return undefined;
+    }
+    return `unknown channel ${JSON.stringify(e.channel)}`;
+}
+function readControlFileOrAbsent(path, what) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return undefined;
+        throw new ControlPlaneCorruptError(`${what} could not be read (${code ?? "io error"}) at ${path} — a read failure is not absence (fail-closed); fix the filesystem fault and retry`);
+    }
+}
+function journalOpInvalid(raw, directoryRoot) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return "op is not an object";
+    const op = raw;
+    if (typeof op.target !== "string" || op.target.length === 0)
+        return "missing string target";
+    if (op.staged !== undefined && typeof op.staged !== "string")
+        return "non-string staged";
+    switch (op.kind) {
+        case "write":
+            if (typeof op.content !== "string")
+                return "write op without full content";
+            if (!isContainedIn(directoryRoot, op.target))
+                return "write target escapes the store root";
+            return undefined;
+        case "delete":
+            if (op.content !== undefined)
+                return "delete op must not carry content";
+            if (!isContainedIn(directoryRoot, op.target))
+                return "delete target escapes the store root";
+            return undefined;
+        case "shadow-write":
+            if (typeof op.content !== "string")
+                return "shadow-write op without full content";
+            if (!isValidEntryId(op.target))
+                return "shadow target is not an entry id";
+            return undefined;
+        case "shadow-delete":
+            if (op.content !== undefined)
+                return "shadow-delete op must not carry content";
+            if (!isValidEntryId(op.target))
+                return "shadow target is not an entry id";
+            return undefined;
+        default:
+            return "unknown op kind";
+    }
+}
+function probeProjection(absPath, id) {
+    let text;
+    try {
+        text = readFileSync(absPath, "utf8");
+    }
+    catch (err) {
+        return err.code === "ENOENT" ? "absent" : "undecidable";
+    }
+    return parseEntryFile(text).id === id ? "present" : "undecidable";
+}
 export class FileMemoryEngineBackend {
     directoryRoot;
     controlPlaneRoot;
     now;
     ledger;
+    envelopeExtras;
+    persistedSchemaVersion;
+    announcedV1Compat = false;
+    unboundRowsKnown = false;
+    adoptionNoticeKeys = new Set();
+    transfersAppendFault;
     inboundFindings = [];
     batchScan;
     constructor(dir, opts = {}) {
@@ -84,12 +325,28 @@ export class FileMemoryEngineBackend {
         ensureDirExists(dir);
         ensureDirExists(this.controlPlaneRoot);
         this.recoverJournal({ unlocked: true });
+        try {
+            this.loadLedger();
+        }
+        catch {
+        }
+        if (this.persistedSchemaVersion === "v1" || (this.ledger !== undefined && hasUnboundRows(this.ledger)))
+            this.tryOpportunisticMigrate();
     }
     checkControlPlane() {
         this.recoverJournal({ unlocked: true });
         this.ledger = undefined;
         this.loadLedger();
         registeredScopes(this.controlPlaneRoot);
+        if (this.persistedSchemaVersion === "v1" || hasUnboundRows(this.loadLedger()))
+            this.tryOpportunisticMigrate();
+        const rows = this.loadLedger();
+        if (this.persistedSchemaVersion === "v2" && hasUnboundRows(rows)) {
+            const ids = unboundRowIds(rows);
+            this.enqueueExternalItems([
+                `memory ledger has ${ids.length} unbound row(s) (no derivable committed projection): ${ids.slice(0, 8).join(", ")}${ids.length > 8 ? ", …" : ""} — v2 binding guarantees do not cover them until they converge (duplicate projections need an unrestricted harvest or manual removal)`,
+            ]);
+        }
     }
     drainInboundFindings() {
         const out = this.inboundFindings;
@@ -106,56 +363,422 @@ export class FileMemoryEngineBackend {
         if (this.ledger)
             return this.ledger;
         const path = join(this.controlPlaneRoot, LEDGER_FILE);
-        let raw;
-        try {
-            raw = readFileSync(path, "utf8");
-        }
-        catch {
-            raw = undefined;
-        }
+        const raw = readControlFileOrAbsent(path, "committed-rev ledger");
         if (raw === undefined) {
             this.ledger = {};
+            this.persistedSchemaVersion = "v2";
+            this.unboundRowsKnown = false;
             return this.ledger;
         }
-        let parsed;
+        const parsed = parseLedgerText(raw, path);
+        this.ledger = parsed.rows;
+        this.envelopeExtras = parsed.envelopeExtras;
+        this.persistedSchemaVersion = parsed.form;
+        this.unboundRowsKnown = hasUnboundRows(parsed.rows);
+        if (parsed.form === "v1" && !this.announcedV1Compat) {
+            this.announcedV1Compat = true;
+            this.enqueueExternalItems(["memory ledger v1-compat active — v2 binding guarantees not yet in force (the migration runs at the next uncontended entry)"]);
+        }
+        return this.ledger;
+    }
+    saveLedger() {
+        if (!this.ledger)
+            return;
+        if (this.persistedSchemaVersion !== "v2") {
+            throw new ControlPlaneCorruptError("committed-rev ledger write refused: the on-disk ledger is still schema v1 and the migration has not run (mutations must migrate first)");
+        }
+        atomicWriteFileSync(join(this.controlPlaneRoot, LEDGER_FILE), `${JSON.stringify(ledgerEnvelope(this.ledger, this.envelopeExtras), null, 2)}\n`);
+        this.unboundRowsKnown = hasUnboundRows(this.ledger);
+    }
+    persistLedgerV1(rows) {
+        const map = {};
+        for (const [id, row] of rowsEntries(rows))
+            map[id] = row.rev;
+        atomicWriteFileSync(join(this.controlPlaneRoot, LEDGER_FILE), `${JSON.stringify(map, null, 2)}\n`);
+        this.unboundRowsKnown = Object.keys(map).length > 0;
+    }
+    enqueueExternalItems(items) {
+        if (items.length === 0)
+            return;
         try {
-            parsed = JSON.parse(raw);
+            enqueueMemoryAnnouncement(this.controlPlaneRoot, { kind: "external", at: this.now(), items });
         }
         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}`);
+    }
+    announceAdoptionNotice(key, item) {
+        if (this.adoptionNoticeKeys.has(key))
+            return;
+        this.adoptionNoticeKeys.add(key);
+        this.enqueueExternalItems([item]);
+    }
+    bindingAbsPath(binding) {
+        return join(scopeDirFor(this.directoryRoot, this.controlPlaneRoot, binding.scope), `${binding.slug}.md`);
+    }
+    bindingRelPath(binding) {
+        return relative(this.directoryRoot, this.bindingAbsPath(binding));
+    }
+    censusProjectionsLocked() {
+        let complete = true;
+        const byId = new Map();
+        for (const scope of Object.keys(registeredScopes(this.controlPlaneRoot))) {
+            const dir = this.scopeDir(scope);
+            const isRoot = dir === this.directoryRoot;
+            const exclude = isRoot ? this.excludedSubdirNames(scope) : undefined;
+            const walk = (d, depth) => {
+                let names;
+                try {
+                    names = readdirSync(d);
+                }
+                catch (err) {
+                    if (err.code === "ENOENT" && depth === 0)
+                        return;
+                    complete = false;
+                    return;
+                }
+                for (const name of names.sort()) {
+                    if (name.startsWith(".") || name === MEMORY_INDEX_FILENAME)
+                        continue;
+                    const p = join(d, name);
+                    let st;
+                    try {
+                        st = lstatSync(p);
+                    }
+                    catch {
+                        complete = false;
+                        continue;
+                    }
+                    if (st.isSymbolicLink())
+                        continue;
+                    if (st.isDirectory()) {
+                        if (depth === 0 && exclude?.has(name))
+                            continue;
+                        if (depth + 1 <= DEFAULT_MAX_ENTRY_DEPTH)
+                            walk(p, depth + 1);
+                        continue;
+                    }
+                    if (!st.isFile() || !name.endsWith(".md"))
+                        continue;
+                    let text;
+                    try {
+                        text = readFileSync(p, "utf8");
+                    }
+                    catch {
+                        complete = false;
+                        continue;
+                    }
+                    const id = parseEntryFile(text).id;
+                    if (id === undefined)
+                        continue;
+                    const list = byId.get(id) ?? [];
+                    list.push({ scope, slug: relative(dir, p).replace(/\.md$/, "") });
+                    byId.set(id, list);
+                }
+            };
+            walk(dir, 0);
+        }
+        return { complete, byId };
+    }
+    writeV1BackupOnce() {
+        const raw = readControlFileOrAbsent(join(this.controlPlaneRoot, LEDGER_FILE), "committed-rev ledger");
+        if (raw === undefined)
+            throw new ControlPlaneCorruptError(`committed-rev ledger vanished under the migration lock: ${join(this.controlPlaneRoot, LEDGER_FILE)}`);
+        const bak = join(this.controlPlaneRoot, LEDGER_V1_BACKUP_FILE);
+        let fd;
+        try {
+            fd = openSync(bak, "wx", 0o600);
+        }
+        catch (err) {
+            if (err.code === "EEXIST")
+                return;
+            throw err;
+        }
+        try {
+            writeAllSync(fd, raw);
+            fsyncSync(fd);
         }
-        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}`);
+        finally {
+            closeSync(fd);
         }
-        this.ledger = parsed;
-        return this.ledger;
     }
-    saveLedger() {
-        if (!this.ledger)
+    tryAcquireTxnLockSync() {
+        const lockDir = this.txnLockDir();
+        const ownerPath = join(lockDir, "owner");
+        const tryMkdir = () => {
+            try {
+                mkdirSync(this.controlPlaneRoot, { recursive: true });
+                mkdirSync(lockDir);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        let acquired = tryMkdir();
+        if (!acquired) {
+            let mtimeMs;
+            try {
+                mtimeMs = statSync(lockDir).mtimeMs;
+            }
+            catch {
+                mtimeMs = undefined;
+            }
+            if (mtimeMs !== undefined && this.now() - mtimeMs > TXN_LOCK_STALE_MS) {
+                let tokenPresent = false;
+                try {
+                    statSync(ownerPath);
+                    tokenPresent = true;
+                }
+                catch {
+                }
+                if (tokenPresent) {
+                    const tomb = join(this.controlPlaneRoot, `txn.lock.stale-${randomUUID()}`);
+                    let stolen = false;
+                    try {
+                        renameSync(lockDir, tomb);
+                        stolen = true;
+                    }
+                    catch {
+                    }
+                    if (stolen) {
+                        rmSync(tomb, { recursive: true, force: true });
+                        acquired = tryMkdir();
+                    }
+                }
+            }
+            if (!acquired)
+                return undefined;
+        }
+        const token = randomUUID();
+        try {
+            const fd = openSync(ownerPath, "w", 0o600);
+            try {
+                writeAllSync(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 {
+                }
+            },
+        };
+    }
+    tryOpportunisticMigrate() {
+        const lock = this.tryAcquireTxnLockSync();
+        if (lock === undefined)
+            return;
+        try {
+            this.recoverJournal();
+            this.migrateLockedIfNeeded(lock.token);
+        }
+        finally {
+            lock.release();
+        }
+    }
+    migrateLockedIfNeeded(lockToken) {
+        this.ledger = undefined;
+        const rows = this.loadLedger();
+        if (this.persistedSchemaVersion === "v2" && !hasUnboundRows(rows))
             return;
-        atomicWriteFileSync(join(this.controlPlaneRoot, LEDGER_FILE), `${JSON.stringify(this.ledger, null, 2)}\n`);
+        const fullMigration = this.persistedSchemaVersion === "v1";
+        const census = this.censusProjectionsLocked();
+        if (!census.complete) {
+            this.announceAdoptionNotice("migration-incomplete", `memory ledger ${fullMigration ? "v1→v2 migration" : "unbound-row convergence"} abandoned this pass — the projection census could not read every scope (bindings derived from a partial view could be wrong); it retries at the next entry`);
+            return;
+        }
+        const now = this.now();
+        const next = {};
+        const bound = [];
+        const unbound = [];
+        const events = [];
+        for (const [id, row] of rowsEntries(rows)) {
+            if (!fullMigration && rowsBinding(rows, id) !== undefined) {
+                next[id] = { ...row };
+                continue;
+            }
+            const projections = census.byId.get(id) ?? [];
+            const sole = projections[0];
+            if (projections.length === 1 && sole !== undefined) {
+                next[id] = { ...row, scope: sole.scope, slug: sole.slug };
+                bound.push(id);
+                if (!fullMigration)
+                    events.push({ ev: randomUUID(), channel: "migration-bind", id, to: sole, at: now });
+            }
+            else {
+                next[id] = { ...row };
+                unbound.push(`${id} (${projections.length} projection(s))`);
+            }
+        }
+        if (fullMigration) {
+            this.writeV1BackupOnce();
+            events.push({ ev: randomUUID(), channel: "migration", boundRows: bound.length, unboundRows: unbound.length, at: now });
+        }
+        else if (bound.length === 0) {
+            return;
+        }
+        this.assertTxnLockOwnership(lockToken);
+        this.precheckTransfersAppendable();
+        const journal = { txn: `${Date.now()}-migrate`, ops: [], ledger2: ledgerEnvelope(next, this.envelopeExtras), transfers: events };
+        atomicWriteFileSync(join(this.controlPlaneRoot, JOURNAL_FILE), JSON.stringify(journal));
+        this.ledger = next;
+        this.persistedSchemaVersion = "v2";
+        this.saveLedger();
+        this.appendTransfers(events);
+        rmSync(join(this.controlPlaneRoot, JOURNAL_FILE), { force: true });
+        this.enqueueExternalItems([
+            fullMigration
+                ? `memory ledger upgraded to v2 (${bound.length} row(s) bound, ${unbound.length} unbound${unbound.length > 0 ? `: ${unbound.slice(0, 8).join(", ")}${unbound.length > 8 ? ", …" : ""}` : ""})`
+                : `memory ledger unbound row(s) converged to bound: ${bound.slice(0, 8).join(", ")}${bound.length > 8 ? ", …" : ""}`,
+        ]);
+    }
+    readTransferEvs() {
+        const path = join(this.controlPlaneRoot, TRANSFERS_FILE);
+        const raw = readControlFileOrAbsent(path, "transfer evidence log");
+        const evs = new Set();
+        if (raw === undefined)
+            return evs;
+        const lines = raw.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (line === undefined || line === "")
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                const isTail = lines.slice(i + 1).every((l) => l === "");
+                if (isTail) {
+                    try {
+                        ensureDirExists(join(this.controlPlaneRoot, QUARANTINE_DIR));
+                        atomicWriteFileSync(join(this.controlPlaneRoot, QUARANTINE_DIR, `transfers-torn-tail-${this.now()}.fragment`), line);
+                        atomicWriteFileSync(path, lines.slice(0, i).join("\n") + (i > 0 ? "\n" : ""));
+                    }
+                    catch {
+                        throw new ControlPlaneCorruptError(`transfer evidence log has a torn tail that could not be quarantined: ${path}`);
+                    }
+                    this.enqueueExternalItems([`transfer evidence log had a torn tail (crash mid-append) — the fragment is quarantined and the sound prefix stands: ${TRANSFERS_FILE}`]);
+                    break;
+                }
+                throw new ControlPlaneCorruptError(`transfer evidence log line ${i + 1} is unparseable (not a torn tail — fail-closed): ${path}`);
+            }
+            const invalid = transferEventInvalid(parsed);
+            if (invalid !== undefined)
+                throw new ControlPlaneCorruptError(`transfer evidence log line ${i + 1} is invalid (${invalid}): ${path}`);
+            evs.add(parsed.ev);
+        }
+        return evs;
+    }
+    precheckTransfersAppendable() {
+        this.readTransferEvs();
+        const fd = openSync(join(this.controlPlaneRoot, TRANSFERS_FILE), "a", 0o600);
+        closeSync(fd);
+    }
+    appendTransfers(events) {
+        if (events.length === 0)
+            return;
+        this.transfersAppendFault?.();
+        const existing = this.readTransferEvs();
+        const missing = events.filter((e) => !existing.has(e.ev));
+        if (missing.length === 0)
+            return;
+        const fd = openSync(join(this.controlPlaneRoot, TRANSFERS_FILE), "a", 0o600);
+        try {
+            writeAllSync(fd, missing.map((e) => `${JSON.stringify(e)}\n`).join(""));
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
     }
     recoverJournal(opts = {}) {
         const jp = join(this.controlPlaneRoot, JOURNAL_FILE);
         if (opts.unlocked && this.txnInFlight())
             return;
-        const raw = readSafe(jp);
+        const raw = readControlFileOrAbsent(jp, "transaction journal");
         if (raw !== undefined) {
             let journal;
             try {
                 const parsed = JSON.parse(raw);
-                if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.ops) || typeof parsed.ledger !== "object") {
+                if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.ops))
                     throw new Error("wrong shape");
-                }
                 journal = parsed;
             }
             catch {
                 throw new ControlPlaneCorruptError(`transaction journal is unparseable: ${jp}`);
             }
+            const hasV2 = journal.ledger2 !== undefined;
+            const hasV1 = journal.ledger !== undefined;
+            if (hasV2 === hasV1) {
+                throw new ControlPlaneCorruptError(`transaction journal has ${hasV2 ? "both ledger snapshots" : "no ledger snapshot"} (wrong shape): ${jp}`);
+            }
+            let snapshotRows;
+            let snapshotExtras;
+            if (hasV2) {
+                const env = journal.ledger2;
+                if (!env || typeof env !== "object" || Array.isArray(env) || env.v !== LEDGER_SCHEMA_VERSION) {
+                    throw new ControlPlaneCorruptError(`transaction journal ledger2 snapshot has the wrong shape: ${jp}`);
+                }
+                snapshotRows = validateLedgerRowsV2(env.rows, jp);
+                snapshotExtras = {};
+                for (const [k, val] of Object.entries(env))
+                    if (k !== "v" && k !== "rows")
+                        snapshotExtras[k] = val;
+            }
+            else {
+                const map = journal.ledger;
+                if (!map || typeof map !== "object" || Array.isArray(map))
+                    throw new ControlPlaneCorruptError(`transaction journal ledger snapshot has the wrong shape: ${jp}`);
+                snapshotRows = {};
+                for (const [id, rev] of Object.entries(map)) {
+                    if (typeof rev !== "string")
+                        throw new ControlPlaneCorruptError(`transaction journal v1 ledger snapshot entry ${JSON.stringify(id)} is not a string: ${jp}`);
+                    snapshotRows[id] = { rev };
+                }
+            }
+            for (const op of journal.ops) {
+                const invalid = journalOpInvalid(op, this.directoryRoot);
+                if (invalid !== undefined) {
+                    throw new ControlPlaneCorruptError(`transaction journal op is invalid (${invalid}; kind=${JSON.stringify(op.kind)} target=${JSON.stringify(op.target)}) — the whole journal is refused and kept at ${jp} (control data is malformed: repair via the explicit control-plane rebuild path, not a replay guess)`);
+                }
+            }
+            if (journal.transfers !== undefined) {
+                if (!Array.isArray(journal.transfers))
+                    throw new ControlPlaneCorruptError(`transaction journal transfers is not an array: ${jp}`);
+                for (const e of journal.transfers) {
+                    const invalid = transferEventInvalid(e);
+                    if (invalid !== undefined)
+                        throw new ControlPlaneCorruptError(`transaction journal transfer event is invalid (${invalid}): ${jp}`);
+                    if (e.channel !== "migration" && !bindingEquals(rowsBinding(snapshotRows, e.id), e.to)) {
+                        throw new ControlPlaneCorruptError(`transaction journal transfer event for ${JSON.stringify(e.id)} disagrees with the snapshot binding: ${jp}`);
+                    }
+                }
+                if (hasV1)
+                    throw new ControlPlaneCorruptError(`transaction journal carries transfers with a v1 snapshot (impossible form): ${jp}`);
+            }
             for (const op of journal.ops) {
                 try {
                     if (op.kind === "write" && op.content !== undefined) {
@@ -173,11 +796,23 @@ export class FileMemoryEngineBackend {
                         rmSync(this.shadowPath(op.target), { force: true });
                     }
                 }
-                catch {
+                catch (err) {
+                    const code = err.code;
+                    throw new ControlPlaneCorruptError(`transaction journal replay failed on op kind=${op.kind} target=${JSON.stringify(op.target)} (${code ?? (err instanceof Error ? err.message : String(err))}) — the journal is kept at ${jp}; an I/O failure retries at the next construction, a persistent fault needs the explicit control-plane rebuild path`);
                 }
             }
-            this.ledger = { ...journal.ledger };
-            this.saveLedger();
+            if (hasV2) {
+                this.ledger = snapshotRows;
+                this.envelopeExtras = snapshotExtras;
+                this.persistedSchemaVersion = "v2";
+                this.saveLedger();
+                this.appendTransfers(journal.transfers ?? []);
+            }
+            else {
+                this.ledger = snapshotRows;
+                this.persistedSchemaVersion = "v1";
+                this.persistLedgerV1(snapshotRows);
+            }
             rmSync(jp, { force: true });
         }
         this.sweepStagedFiles();
@@ -186,8 +821,11 @@ export class FileMemoryEngineBackend {
         try {
             return this.now() - statSync(this.txnLockDir()).mtimeMs < TXN_LOCK_STALE_MS;
         }
-        catch {
-            return false;
+        catch (err) {
+            const code = err.code;
+            if (code === "ENOENT")
+                return false;
+            throw new ControlPlaneCorruptError(`txn lock state could not be probed (${code ?? "io error"}) at ${this.txnLockDir()} — a probe failure is not "no writer" (fail-closed)`);
         }
     }
     sweepStagedFiles() {
@@ -269,13 +907,17 @@ export class FileMemoryEngineBackend {
             if (memo !== undefined)
                 return memo;
         }
+        if (this.persistedSchemaVersion === "v1" || this.unboundRowsKnown)
+            this.tryOpportunisticMigrate();
         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;
+        const rows = sync ? this.loadLedger() : undefined;
         let ledgerChanged = false;
         const adoptedExternal = [];
+        const moveEvents = [];
+        const moveAnnouncements = [];
         const skippedUnreadable = [];
         for (const f of files) {
             let text;
@@ -290,35 +932,44 @@ export class FileMemoryEngineBackend {
             if (parsed.id === undefined)
                 continue;
             let entry = entryFromFile(text, parsed.id, f.slug, scope);
-            if (ledger) {
-                const committed = ledger[entry.id];
+            if (rows) {
+                const committed = rowsRev(rows, entry.id);
+                const binding = rowsBinding(rows, entry.id);
+                const relPath = relative(this.directoryRoot, f.path);
+                if (committed !== undefined && binding !== undefined && !(binding.scope === scope && binding.slug === f.slug)) {
+                    const probe = probeProjection(this.bindingAbsPath(binding), entry.id);
+                    if (probe === "present") {
+                        this.announceAdoptionNotice(`copy|${relPath}|${entry.rev}`, `duplicate projection of committed entry ${entry.id} at ${JSON.stringify(inlineUntrusted(relPath))} — the committed projection lives at ${JSON.stringify(inlineUntrusted(this.bindingRelPath(binding)))}; the copy is not served (a copy is not a scope credential) and stays on disk for an unrestricted harvest or manual removal to adjudicate`);
+                        continue;
+                    }
+                    if (probe === "undecidable") {
+                        this.announceAdoptionNotice(`bindprobe|${relPath}`, `committed entry ${entry.id} appears at ${JSON.stringify(inlineUntrusted(relPath))} but is bound to ${JSON.stringify(inlineUntrusted(this.bindingRelPath(binding)))}, and the bound projection could not be probed conclusively (a read failure, or a foreign file at that address — not ENOENT) — nothing is served or adopted this pass`);
+                        continue;
+                    }
+                    if (probeOnly)
+                        return undefined;
+                    if (lockToken !== undefined)
+                        this.assertTxnLockOwnership(lockToken);
+                    const adopted = this.adoptMoveCandidateLocked(rows, entry, f.path, f.slug, scope, relPath, text, committed, binding, moveEvents, moveAnnouncements, adoptedExternal);
+                    if (adopted !== undefined) {
+                        entries.push(adopted);
+                        ledgerChanged = true;
+                    }
+                    continue;
+                }
                 if (committed !== entry.rev) {
                     if (probeOnly)
                         return undefined;
                     if (lockToken !== undefined)
                         this.assertTxnLockOwnership(lockToken);
-                    const relPath = relative(this.directoryRoot, f.path);
                     let finding = this.inboundGate(relPath, text);
-                    if (finding === undefined && committed !== undefined) {
-                        const committedShadow = this.readCommittedShadow(entry.id);
-                        const committedFm = committedShadow !== undefined ? parseEntryFile(committedShadow).frontmatter : undefined;
-                        if (committedFm?.provenance?.kind === "repo_file") {
-                            const stripsProvenance = entry.frontmatter.provenance === undefined;
-                            const stripsTrust = committedFm.trust !== undefined && entry.frontmatter.trust === undefined;
-                            if (stripsProvenance || stripsTrust) {
-                                finding = {
-                                    path: relPath,
-                                    code: "invalid",
-                                    reason: `inbound memory change blocked: repo_file provenance whitewash refused — the on-disk change drops ${stripsProvenance ? "provenance" : "trust"} from a repo-ingested entry (quarantined; committed content restored)`,
-                                };
-                            }
-                        }
-                    }
+                    if (finding === undefined && committed !== undefined)
+                        finding = this.whitewashInboundFinding(relPath, entry, "restored");
                     if (finding) {
                         const shadowText = this.containInboundReject(finding, f.path, text, entry.id, committed);
                         if (shadowText === undefined) {
                             if (committed !== undefined) {
-                                delete ledger[entry.id];
+                                deleteRow(rows, entry.id);
                                 ledgerChanged = true;
                             }
                             continue;
@@ -327,8 +978,8 @@ export class FileMemoryEngineBackend {
                     }
                     else {
                         if (committed !== undefined)
-                            adoptedExternal.push(relative(this.directoryRoot, f.path));
-                        ledger[entry.id] = entry.rev;
+                            adoptedExternal.push(relPath);
+                        bindRowTracked(rows, entry.id, { rev: entry.rev, scope, slug: f.slug, at: this.now() }, moveEvents, "adopted-move");
                         try {
                             atomicWriteFileSync(this.shadowPath(entry.id), text);
                         }
@@ -350,7 +1001,25 @@ export class FileMemoryEngineBackend {
         if (ledgerChanged) {
             if (lockToken !== undefined)
                 this.assertTxnLockOwnership(lockToken);
-            this.saveLedger();
+            if (moveEvents.length > 0) {
+                this.precheckTransfersAppendable();
+                const journal = {
+                    txn: `${Date.now()}-${randomUUID().slice(0, 8)}`,
+                    ops: [],
+                    ledger2: ledgerEnvelope(rows, this.envelopeExtras),
+                    transfers: moveEvents,
+                };
+                atomicWriteFileSync(join(this.controlPlaneRoot, JOURNAL_FILE), JSON.stringify(journal));
+                this.saveLedger();
+                this.appendTransfers(moveEvents);
+                rmSync(join(this.controlPlaneRoot, JOURNAL_FILE), { force: true });
+            }
+            else {
+                this.saveLedger();
+            }
+        }
+        if (moveAnnouncements.length > 0) {
+            this.enqueueExternalItems(moveAnnouncements.slice(0, 12).concat(moveAnnouncements.length > 12 ? [`…and ${moveAnnouncements.length - 12} more adopted move(s)`] : []));
         }
         if (adoptedExternal.length > 0) {
             try {
@@ -384,6 +1053,58 @@ export class FileMemoryEngineBackend {
             this.batchScan.set(scope, entries);
         return entries;
     }
+    whitewashInboundFinding(relPath, entry, containment) {
+        const committedShadow = this.readCommittedShadow(entry.id);
+        const committedFm = committedShadow !== undefined ? parseEntryFile(committedShadow).frontmatter : undefined;
+        if (committedFm?.provenance?.kind !== "repo_file")
+            return undefined;
+        const stripsProvenance = entry.frontmatter.provenance === undefined;
+        const stripsTrust = committedFm.trust !== undefined && entry.frontmatter.trust === undefined;
+        if (!stripsProvenance && !stripsTrust)
+            return undefined;
+        return {
+            path: relPath,
+            code: "invalid",
+            reason: `inbound memory change blocked: repo_file provenance whitewash refused — the on-disk change drops ${stripsProvenance ? "provenance" : "trust"} from a repo-ingested entry ${containment === "restored" ? "(quarantined; committed content restored)" : "(quarantined)"}`,
+        };
+    }
+    adoptMoveCandidateLocked(rows, entry, absPath, slug, scope, relPath, text, committedRev, from, moveEvents, moveAnnouncements, adoptedExternal) {
+        const census = this.censusProjectionsLocked();
+        if (!census.complete) {
+            this.inboundFindings.push({
+                path: relPath,
+                code: "unreadable",
+                reason: `move adoption deferred: committed entry ${entry.id} lost its committed projection, but the store-wide projection census could not read every scope — nothing is served or adopted off a partial view; the next pass retries`,
+            });
+            return undefined;
+        }
+        const projections = census.byId.get(entry.id) ?? [];
+        const others = projections.filter((p) => !(p.scope === scope && p.slug === slug));
+        if (others.length > 0) {
+            this.announceAdoptionNotice(`ambiguous|${entry.id}|${projections
+                .map((p) => `${p.scope}/${p.slug}`)
+                .sort()
+                .join(",")}`, `committed entry ${entry.id} lost its committed projection and now appears at ${projections.length} path(s) — no copy is a scope credential, so none is served or adopted (read order never picks an owner); an unrestricted harvest or manual removal adjudicates which is real`);
+            return undefined;
+        }
+        const gateFinding = this.inboundGate(relPath, text) ?? (committedRev !== entry.rev ? this.whitewashInboundFinding(relPath, entry, "quarantined-only") : undefined);
+        if (gateFinding !== undefined) {
+            this.containInboundReject(gateFinding, absPath, text, entry.id, undefined);
+            return undefined;
+        }
+        const now = this.now();
+        bindRowTracked(rows, entry.id, { rev: entry.rev, scope, slug, at: now }, moveEvents, "adopted-move");
+        moveAnnouncements.push(`out-of-session memory move adopted: ${entry.id} ${JSON.stringify(inlineUntrusted(this.bindingRelPath(from)))} → ${JSON.stringify(inlineUntrusted(relPath))} — re-read it before relying on prior knowledge of it`);
+        if (committedRev !== entry.rev) {
+            adoptedExternal.push(relPath);
+            try {
+                atomicWriteFileSync(this.shadowPath(entry.id), text);
+            }
+            catch {
+            }
+        }
+        return entry;
+    }
     async readScopeAdopting(scope, timings) {
         const probed = this.readScope(scope, true, true);
         if (probed !== undefined)
@@ -393,6 +1114,7 @@ export class FileMemoryEngineBackend {
             this.assertTxnLockOwnership(lock.token);
             this.ledger = undefined;
             this.recoverJournal();
+            this.migrateLockedIfNeeded(lock.token);
             return this.readScope(scope, true, false, lock.token);
         }
         catch (err) {
@@ -453,6 +1175,8 @@ export class FileMemoryEngineBackend {
     restrictedIdlessScope;
     restrictedIdlessBaseline;
     readScopeCommitted(scope, audit) {
+        if (this.persistedSchemaVersion === "v1" || this.unboundRowsKnown)
+            this.tryOpportunisticMigrate();
         const dir = this.scopeDir(scope);
         const isRoot = dir === this.directoryRoot;
         const files = scanEntryFiles(dir, {
@@ -471,7 +1195,7 @@ export class FileMemoryEngineBackend {
                 : undefined,
         });
         this.ledger = undefined;
-        const ledger = this.loadLedger();
+        const rows = this.loadLedger();
         const idlessSeen = audit && scope === this.restrictedIdlessScope ? new Set() : undefined;
         const entries = [];
         for (const f of files) {
@@ -496,8 +1220,38 @@ export class FileMemoryEngineBackend {
                 continue;
             }
             const entry = entryFromFile(text, parsed.id, f.slug, scope);
-            const committed = ledger[entry.id];
+            const committed = rowsRev(rows, entry.id);
+            const binding = rowsBinding(rows, entry.id);
+            const boundElsewhere = binding !== undefined && !(binding.scope === scope && binding.slug === f.slug);
             if (committed === entry.rev) {
+                if (boundElsewhere) {
+                    if (audit) {
+                        const boundRel = this.bindingRelPath(binding);
+                        const probe = probeProjection(this.bindingAbsPath(binding), entry.id);
+                        if (probe === "present") {
+                            this.recordRestrictedFinding(`bindcopy|${rel}|${entry.rev}`, {
+                                path: rel,
+                                code: "restricted_divergence",
+                                reason: `this file carries the bytes of committed entry ${entry.id}, whose committed projection is in place at ${JSON.stringify(inlineUntrusted(boundRel))} — a filesystem copy is not a scope credential, so this copy is withheld; an unrestricted session's harvest adjudicates it`,
+                            });
+                        }
+                        else if (probe === "absent") {
+                            this.recordRestrictedFinding(`bindmove|${rel}|${entry.rev}`, {
+                                path: rel,
+                                code: "restricted_divergence",
+                                reason: `committed entry ${entry.id} is bound to ${JSON.stringify(inlineUntrusted(boundRel))} but its projection appears here instead — an unattributed move, or a delete-then-plant; this adoption-restricted session serves neither reading and leaves adjudication to an unrestricted session`,
+                            });
+                        }
+                        else {
+                            this.recordRestrictedFinding(`bindprobe|${rel}`, {
+                                path: rel,
+                                code: "unreadable",
+                                reason: `committed entry ${entry.id} is bound elsewhere and the bound projection could not be probed conclusively (a read failure, not absence) — the binding audit for this file is incomplete; it is withheld this pass`,
+                            });
+                        }
+                    }
+                    continue;
+                }
                 if (audit && this.readCommittedShadow(entry.id) === undefined) {
                     try {
                         atomicWriteFileSync(this.shadowPath(entry.id), text);
@@ -511,11 +1265,11 @@ export class FileMemoryEngineBackend {
             const shadowText = committed !== undefined ? this.readCommittedShadow(entry.id) : undefined;
             if (shadowText !== undefined) {
                 const shadowEntry = entryFromFile(shadowText, entry.id, f.slug, scope);
-                if (shadowEntry.rev === entry.rev) {
+                if (shadowEntry.rev === entry.rev && !boundElsewhere) {
                     entries.push(entry);
                     continue;
                 }
-                const otherProjection = this.idProjectionElsewhere(entry.id, f.path);
+                const otherProjection = binding !== undefined ? (boundElsewhere ? this.bindingRelPath(binding) : undefined) : this.idProjectionElsewhere(entry.id, f.path);
                 if (otherProjection !== undefined) {
                     if (audit) {
                         const finding = this.inboundGate(rel, text);
@@ -526,7 +1280,9 @@ export class FileMemoryEngineBackend {
                             this.recordRestrictedFinding(`dupserve|${rel}|${entry.rev}`, {
                                 path: rel,
                                 code: "restricted_divergence",
-                                reason: `this file carries the id of a committed entry that has another projection (${otherProjection}) — the committed copy may only stand in for an entry's unique projection, so this copy is withheld; an unrestricted session's harvest adjudicates it`,
+                                reason: binding !== undefined
+                                    ? `this file diverges from committed entry ${entry.id}, whose committed projection is bound at ${JSON.stringify(inlineUntrusted(otherProjection))} — the committed copy may only stand in at the entry's committed projection, so this copy is withheld; an unrestricted session's harvest adjudicates it`
+                                    : `this file carries the id of a committed entry that has another projection (${otherProjection}) — the committed copy may only stand in for an entry's unique projection, so this copy is withheld; an unrestricted session's harvest adjudicates it`,
                             });
                         }
                     }
@@ -595,6 +1351,7 @@ export class FileMemoryEngineBackend {
     restrictedAdoptionView(opts) {
         const audit = opts?.audit === true;
         if (audit) {
+            this.restrictedFindingKeys = new Set();
             this.restrictedIdlessScope = typeof opts?.writeScope === "string" ? opts.writeScope : undefined;
             this.restrictedIdlessBaseline = undefined;
         }
@@ -615,7 +1372,15 @@ export class FileMemoryEngineBackend {
             this.readScopeCommitted(scope, true);
         const idlessBaseline = opts?.idlessWriteScope !== undefined && opts.idlessWriteScope === this.restrictedIdlessScope ? this.restrictedIdlessBaseline : undefined;
         const idlessScope = idlessBaseline !== undefined ? opts?.idlessWriteScope : undefined;
-        const ledger = { ...this.loadLedger() };
+        if (this.persistedSchemaVersion === "v1" || hasUnboundRows(this.loadLedger()))
+            this.tryOpportunisticMigrate();
+        const rows = { ...this.loadLedger() };
+        if (this.persistedSchemaVersion === "v2" && hasUnboundRows(rows)) {
+            const unboundIds = unboundRowIds(rows);
+            this.enqueueExternalItems([
+                `memory ledger has ${unboundIds.length} unbound row(s) (no derivable committed projection): ${unboundIds.slice(0, 8).join(", ")}${unboundIds.length > 8 ? ", …" : ""} — v2 binding guarantees do not cover them until they converge`,
+            ]);
+        }
         const present = new Map();
         let complete = true;
         for (const scope of Object.keys(registeredScopes(this.controlPlaneRoot))) {
@@ -652,12 +1417,13 @@ export class FileMemoryEngineBackend {
             }
         }
         for (const [id, paths] of present) {
-            if (paths.length < 2 || ledger[id] === undefined)
+            if (paths.length < 2 || rowsRev(rows, id) === undefined)
                 continue;
+            const dupBinding = rowsBinding(rows, id);
             this.recordRestrictedFinding(`dup|${id}|${paths.sort().join(",")}`, {
                 path: paths[0] ?? id,
                 code: "restricted_divergence",
-                reason: `committed memory entry ${id} appears at ${paths.length} paths (${paths.join(", ")}) — a filesystem copy is not a rename; this adoption-restricted session flags it and an unrestricted session's harvest adjudicates which projection is real`,
+                reason: `committed memory entry ${id} appears at ${paths.length} paths (${paths.join(", ")}) — a filesystem copy is not a rename; ${dupBinding !== undefined ? `the committed projection is ${JSON.stringify(inlineUntrusted(this.bindingRelPath(dupBinding)))}, the other path(s) carry no account backing` : "this adoption-restricted session flags it"} and an unrestricted session's harvest adjudicates`,
             });
         }
         if (!complete) {
@@ -668,16 +1434,30 @@ export class FileMemoryEngineBackend {
             });
             return;
         }
-        for (const [id, rev] of Object.entries(ledger)) {
-            if (present.has(id))
-                continue;
+        for (const [id, row] of rowsEntries(rows)) {
+            const binding = rowsBinding(rows, id);
+            const paths = present.get(id) ?? [];
+            if (binding === undefined) {
+                if (paths.length > 0)
+                    continue;
+            }
+            else {
+                if (paths.includes(this.bindingRelPath(binding)))
+                    continue;
+            }
             this.ledger = undefined;
-            if (this.loadLedger()[id] === undefined)
+            const current = this.loadLedger();
+            if (rowsRev(current, id) === undefined)
                 continue;
-            this.recordRestrictedFinding(`missing|${id}|${rev}`, {
-                path: `id:${id}`,
+            if (!bindingEquals(rowsBinding(current, id), binding))
+                continue;
+            const aliens = binding !== undefined ? paths.filter((p) => p !== this.bindingRelPath(binding)) : [];
+            this.recordRestrictedFinding(`missing|${id}|${row.rev}`, {
+                path: binding !== undefined ? this.bindingRelPath(binding) : `id:${id}`,
                 code: "restricted_divergence",
-                reason: `committed memory entry ${id} is missing from disk with no transaction backing the removal; this adoption-restricted session neither restores nor forgets it — an unrestricted session can restore it from the committed copy`,
+                reason: binding !== undefined
+                    ? `committed memory entry ${id} is missing from its committed projection ${JSON.stringify(inlineUntrusted(this.bindingRelPath(binding)))} with no transaction backing the removal${aliens.length > 0 ? ` while byte-carriers of its id appear at ${aliens.join(", ")} — an unattributed move, or a delete-then-plant` : ""}; this adoption-restricted session neither restores nor forgets it — an unrestricted session adjudicates`
+                    : `committed memory entry ${id} is missing from disk with no transaction backing the removal; this adoption-restricted session neither restores nor forgets it — an unrestricted session can restore it from the committed copy`,
             });
         }
     }
@@ -825,12 +1605,14 @@ export class FileMemoryEngineBackend {
     async applyPatchesLocked(patches, lockToken) {
         this.ledger = undefined;
         this.recoverJournal();
-        const ledger = { ...this.loadLedger() };
+        this.migrateLockedIfNeeded(lockToken);
+        const rows = cloneRows(this.loadLedger());
         const report = { applied: [], conflicts: [] };
         const ops = [];
+        const transfers = [];
         const plannedTargets = new Set();
         const nonDeleteIds = new Set();
-        const plannedDeletes = new Set();
+        const plannedDeletes = new Map();
         this.batchScan = new Map();
         try {
             for (const patch of patches) {
@@ -846,7 +1628,7 @@ export class FileMemoryEngineBackend {
                         }
                         nonDeleteIds.add(patch.id);
                     }
-                    this.planOne(patch, report, ops, ledger, plannedTargets, plannedDeletes);
+                    this.planOne(patch, report, ops, rows, plannedTargets, plannedDeletes, transfers);
                 }
                 catch (err) {
                     report.conflicts.push({ op: patch.op, id: patch.id, reason: `io error: ${err instanceof Error ? err.message : String(err)}` });
@@ -876,8 +1658,11 @@ export class FileMemoryEngineBackend {
             }
             op.staged = staged;
         }
+        const coherentTransfers = transfers.filter((e) => e.channel === "migration" || bindingEquals(rowsBinding(rows, e.id), e.to));
         this.assertTxnLockOwnership(lockToken);
-        const journal = { txn, ops, ledger };
+        if (coherentTransfers.length > 0)
+            this.precheckTransfersAppendable();
+        const journal = { txn, ops, ledger2: ledgerEnvelope(rows, this.envelopeExtras), ...(coherentTransfers.length > 0 ? { transfers: coherentTransfers } : {}) };
         atomicWriteFileSync(join(this.controlPlaneRoot, JOURNAL_FILE), JSON.stringify(journal));
         for (const op of ops) {
             if (op.kind === "write" && op.staged) {
@@ -893,16 +1678,21 @@ export class FileMemoryEngineBackend {
                 rmSync(this.shadowPath(op.target), { force: true });
             }
         }
-        this.ledger = ledger;
+        this.ledger = rows;
         this.saveLedger();
+        this.appendTransfers(coherentTransfers);
         rmSync(join(this.controlPlaneRoot, JOURNAL_FILE), { force: true });
         return report;
     }
-    planOne(patch, report, ops, ledger, plannedTargets, plannedDeletes) {
+    planOne(patch, report, ops, rows, plannedTargets, plannedDeletes, transfers) {
         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 !== "delete" && patch.entry !== undefined && slugEscapes(patch.entry.slug)) {
+            report.conflicts.push({ op: patch.op, id: patch.id, reason: `invalid_slug_shape (slug ${JSON.stringify(patch.entry.slug)} is empty, absolute, or path-escaping — a projection must stay inside its scope dir)` });
+            return;
+        }
         if (patch.op === "add") {
             const entry = patch.entry;
             if (!entry) {
@@ -913,7 +1703,7 @@ export class FileMemoryEngineBackend {
             const existingAnywhere = locatedAnywhere !== undefined && plannedDeletes.has(patch.id) ? undefined : locatedAnywhere;
             if (patch.guard === "absent") {
                 if (existingAnywhere) {
-                    const currentRev = ledger[patch.id] ?? existingAnywhere.entry.rev;
+                    const currentRev = rowsRev(rows, 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;
@@ -956,7 +1746,14 @@ export class FileMemoryEngineBackend {
             plannedTargets.add(target);
             ops.push({ kind: "write", target, content });
             ops.push({ kind: "shadow-write", target: entry.id, content });
-            ledger[entry.id] = computeEntryRev(entry);
+            const now = this.now();
+            bindRowTracked(rows, entry.id, { rev: computeEntryRev(entry), scope: entry.scope, slug, at: now }, transfers, "applyPatches-move");
+            const priorBinding = plannedDeletes.get(entry.id);
+            const justBound = rows[entry.id];
+            if (priorBinding !== undefined && justBound !== undefined && !bindingEquals(priorBinding, { scope: entry.scope, slug })) {
+                rows[entry.id] = { ...justBound, prev: { scope: priorBinding.scope, slug: priorBinding.slug, at: now } };
+                transfers.push({ ev: randomUUID(), channel: "applyPatches-move", id: entry.id, from: priorBinding, to: { scope: entry.scope, slug }, at: now });
+            }
             report.applied.push({ op: "add", id: entry.id, slug });
             return;
         }
@@ -982,7 +1779,7 @@ export class FileMemoryEngineBackend {
                 }
             }
         }
-        const currentRev = ledger[patch.id] ?? found.entry.rev;
+        const currentRev = rowsRev(rows, 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);
@@ -994,8 +1791,9 @@ export class FileMemoryEngineBackend {
         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);
+            const deletedBinding = rowsBinding(rows, patch.id);
+            deleteRow(rows, patch.id);
+            plannedDeletes.set(patch.id, deletedBinding);
             report.applied.push({ op: "delete", id: patch.id, slug: found.entry.slug });
             return;
         }
@@ -1012,7 +1810,7 @@ export class FileMemoryEngineBackend {
         plannedTargets.add(target);
         ops.push({ kind: "write", target, content });
         ops.push({ kind: "shadow-write", target: entry.id, content });
-        ledger[entry.id] = computeEntryRev(entry);
+        bindRowTracked(rows, entry.id, { rev: computeEntryRev(entry), scope: entry.scope, slug: entry.slug, at: this.now() }, transfers, "applyPatches-move");
         report.applied.push({ op: "update", id: entry.id, slug: entry.slug });
     }
     locateById(id, preferScope) {