@sema-agent/core 7.14.0 → 7.16.0

package/dist/core/memory-engine/layout.js

@@ -1,4 +1,4 @@
-import { closeSync, constants as fsConstants, copyFileSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import { chmodSync, closeSync, constants as fsConstants, copyFileSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync, writeSync } from "node:fs";
 const { O_WRONLY, O_CREAT, O_TRUNC, O_NOFOLLOW, O_EXCL } = fsConstants;
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
@@ -201,7 +201,7 @@ function lstatOrAbsent(p) {
     }
 }
 function probeDirCaseFolds(dir) {
-    const name = `.casefold-probe-${process.pid}-${caseFoldProbeSeq++}`;
+    const name = `${CASEFOLD_PROBE_PREFIX}${process.pid}-${caseFoldProbeSeq++}`;
     const writeLeg = (() => {
         let fd;
         try {
@@ -301,6 +301,18 @@ export function dirCaseFolds(dir) {
     caseFoldByDirIdentity.set(key, folds);
     return folds;
 }
+export const SCOPE_DIR_LABEL_RE = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/;
+export const CASEFOLD_PROBE_PREFIX = ".casefold-probe-";
+export const SCOPE_REGISTRY_SHAPES = ["absent", "v1", "v2", "migrating"];
+export const REGISTRY_SHAPE_DERIVES_PATHS = {
+    absent: true,
+    v1: false,
+    v2: true,
+    migrating: false,
+};
+function ownLabel(scopes, scope) {
+    return scopes !== undefined && Object.prototype.hasOwnProperty.call(scopes, scope) ? scopes[scope] : undefined;
+}
 function readScopesRecord(controlDir) {
     const path = join(controlDir, SCOPES_FILE);
     const journalPath = `${path}.journal`;
@@ -322,7 +334,7 @@ function readScopesRecord(controlDir) {
         }
         catch (err) {
             if (err.code === "ENOENT")
-                return {};
+                return { shape: "absent", rec: { v: 2, scopes: {} } };
             throw new ControlPlaneCorruptError(`scope registry unreadable (${err.code ?? "io error"}): ${path}`, { cause: err });
         }
     }
@@ -337,95 +349,357 @@ function readScopesRecord(controlDir) {
         throw new ControlPlaneCorruptError(`scope registry has the wrong shape: ${path}`);
     }
     const rec = parsed;
-    if (rec.rootScope !== undefined && typeof rec.rootScope !== "string") {
-        throw new ControlPlaneCorruptError(`scope registry rootScope is not a string: ${path}`);
-    }
-    let scopes;
-    if (rec.scopes !== undefined) {
-        if (!rec.scopes || typeof rec.scopes !== "object" || Array.isArray(rec.scopes)) {
-            throw new ControlPlaneCorruptError(`scope registry scopes map has the wrong shape: ${path}`);
-        }
-        for (const [k, v] of Object.entries(rec.scopes)) {
-            if (typeof v !== "string")
-                throw new ControlPlaneCorruptError(`scope registry entry ${JSON.stringify(k)} is not a string: ${path}`);
-            if ((v === "") !== (k === rec.rootScope)) {
-                throw new ControlPlaneCorruptError(v === ""
-                    ? `scope registry maps ${JSON.stringify(k)} to the root home but rootScope is ${rec.rootScope === undefined ? "unclaimed" : JSON.stringify(rec.rootScope)}: ${path}`
-                    : `scope registry maps the root scope ${JSON.stringify(k)} to subdir ${JSON.stringify(v)} instead of the root home: ${path}`);
-            }
+    const scopes = coerceScopeLabels(rec.scopes, path);
+    if (rec.v === undefined) {
+        if (rec.rootScope !== undefined && typeof rec.rootScope !== "string") {
+            throw new ControlPlaneCorruptError(`scope registry rootScope is not a string: ${path}`);
+        }
+        return { shape: "v1", ...(rec.rootScope !== undefined ? { rootScope: rec.rootScope } : {}), scopes };
+    }
+    if (rec.v !== 2) {
+        throw new ControlPlaneCorruptError(`scope registry version ${JSON.stringify(rec.v)} is not one this engine reads (expected 2): ${path}`);
+    }
+    for (const [k, label] of Object.entries(scopes)) {
+        if (!SCOPE_DIR_LABEL_RE.test(label)) {
+            throw new ControlPlaneCorruptError(`scope registry maps ${JSON.stringify(k)} to the label ${JSON.stringify(label)}, which is not a single non-hidden path segment — refusing (fail-closed): ${path}`);
         }
-        scopes = rec.scopes;
     }
-    return { rootScope: rec.rootScope, scopes };
+    if (rec.rootOwner !== undefined && typeof rec.rootOwner !== "string") {
+        throw new ControlPlaneCorruptError(`scope registry rootOwner is not a string: ${path}`);
+    }
+    const v2 = { v: 2, scopes, ...(rec.rootOwner !== undefined ? { rootOwner: rec.rootOwner } : {}) };
+    if (rec.migrating === undefined)
+        return { shape: "v2", rec: v2 };
+    const m = rec.migrating;
+    if (!m || typeof m !== "object" || Array.isArray(m) || typeof m.root !== "string" || typeof m.owner !== "string" || typeof m.label !== "string" || !SCOPE_DIR_LABEL_RE.test(m.label)) {
+        throw new ControlPlaneCorruptError(`scope registry carries a malformed migrating marker: ${path}`);
+    }
+    return { shape: "migrating", rec: { ...v2, migrating: { root: m.root, owner: m.owner, label: m.label } } };
+}
+function coerceScopeLabels(raw, path) {
+    if (raw === undefined)
+        return {};
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new ControlPlaneCorruptError(`scope registry scopes map has the wrong shape: ${path}`);
+    }
+    const out = Object.create(null);
+    for (const [k, v] of Object.entries(raw)) {
+        if (typeof v !== "string")
+            throw new ControlPlaneCorruptError(`scope registry entry ${JSON.stringify(k)} is not a string: ${path}`);
+        out[k] = v;
+    }
+    return out;
 }
-function lockedScopesUpdate(controlDir, fn) {
+function requireV2Registry(read, controlDir) {
+    if (REGISTRY_SHAPE_DERIVES_PATHS[read.shape])
+        return read.rec;
+    throw new ControlPlaneCorruptError(read.shape === "v1"
+        ? `scope registry is in the v1 (pre-v2, root-owning) form at ${join(controlDir, SCOPES_FILE)} — scope homes cannot be derived until the layout adoption has run (a mount or a locked backend face runs it); refusing (fail-closed)`
+        : `scope registry carries an unfinished layout move (migrating marker) at ${join(controlDir, SCOPES_FILE)} — scope homes cannot be derived until the move completes (the next mount or locked backend face finishes it); refusing (fail-closed)`);
+}
+function commitScopesRecord(controlDir, lock, token, next) {
+    const file = join(controlDir, SCOPES_FILE);
+    const journal = `${file}.journal`;
+    const data = `${JSON.stringify(next, null, 2)}\n`;
+    const fence = () => assertSidecarLockOwnership(lock, token, "scope registry", "strict");
+    fence();
+    atomicWriteFileSync(journal, data);
+    fence();
+    atomicWriteFileSync(file, data);
+    fence();
+    rmSync(journal, { force: true });
+}
+function withScopesRegistry(controlDir, fn) {
     ensureDirExists(controlDir);
     const file = join(controlDir, SCOPES_FILE);
     const journal = `${file}.journal`;
     const lock = `${file}.lock`;
     const token = acquireSidecarLock(lock, { onDeadline: "throw" });
     try {
-        rollForwardStrictSidecar(file, journal);
-        const rec = readScopesRecord(controlDir);
-        const { next, result } = fn(rec);
-        if (next !== undefined) {
-            const data = `${JSON.stringify(next, null, 2)}\n`;
-            assertSidecarLockOwnership(lock, token, "scope registry");
-            atomicWriteFileSync(journal, data);
-            atomicWriteFileSync(file, data);
-            rmSync(journal, { force: true });
-        }
-        return result;
+        rollForwardStrictSidecar(file, journal, () => assertSidecarLockOwnership(lock, token, "scope registry", "strict"));
+        return fn({
+            read: () => readScopesRecord(controlDir),
+            commit: (next) => commitScopesRecord(controlDir, lock, token, next),
+            renew: () => {
+                const now = new Date();
+                utimesSync(lock, now, now);
+                assertSidecarLockOwnership(lock, token, "scope registry", "strict");
+            },
+        });
     }
     finally {
         releaseSidecarLock(lock, token);
     }
 }
-export function rootScopeOf(controlDir) {
-    return readScopesRecord(controlDir).rootScope;
+function assertNoLabelCollision(memoryDir, scopes, scope, label, caseFoldingFs) {
+    for (const [other, otherLabel] of Object.entries(scopes)) {
+        if (other === scope)
+            continue;
+        if (otherLabel === label) {
+            throw new ControlPlaneCorruptError(`scope directory collision: ${JSON.stringify(scope)} and ${JSON.stringify(other)} both map to ${JSON.stringify(label)} — refusing (fail-closed)`);
+        }
+        if (otherLabel.toLowerCase() === label.toLowerCase()) {
+            const folds = caseFoldingFs ?? dirCaseFolds(memoryDir);
+            if (folds !== false) {
+                throw new ControlPlaneCorruptError(`scope directory collision on a case-folding filesystem: ${JSON.stringify(scope)} → ${JSON.stringify(label)} and ${JSON.stringify(other)} → ${JSON.stringify(otherLabel)} are one physical directory under ${memoryDir}` +
+                    `${folds === undefined ? " (volume case semantics could not be probed — refusing the fold-equal pair rather than risking a silent cross-scope merge)" : ""} — refusing (fail-closed)`);
+            }
+        }
+    }
+}
+function assertHomePhysicalForm(home) {
+    const st = lstatOrAbsent(home);
+    if (st === undefined)
+        return "absent";
+    if (st.isDirectory())
+        return "dir";
+    throw new ControlPlaneCorruptError(`scope home ${home} is ${st.isSymbolicLink() ? "a symbolic link" : "not a directory"} — a scope home must be a real directory (fail-closed)`);
 }
-export function claimRootScope(controlDir, scope) {
-    return lockedScopesUpdate(controlDir, (rec) => {
-        if (rec.rootScope !== undefined)
-            return { result: rec.rootScope };
-        return { next: { rootScope: scope, scopes: { ...rec.scopes, [scope]: "" } }, result: scope };
-    });
+function ensureScopeHome(home) {
+    if (assertHomePhysicalForm(home) === "absent")
+        mkdirSync(home, { recursive: true });
+    assertHomePhysicalForm(home);
 }
 export function registerScope(memoryDir, controlDir, scope, opts) {
-    return lockedScopesUpdate(controlDir, (rec) => {
-        const registered = rec.scopes !== undefined && Object.prototype.hasOwnProperty.call(rec.scopes, scope) ? rec.scopes[scope] : undefined;
-        const dirName = rec.rootScope === scope ? "" : (registered ?? scopeDirName(scope));
-        for (const [other, otherDir] of Object.entries(rec.scopes ?? {})) {
-            if (other === scope || otherDir === "")
-                continue;
-            if (otherDir === dirName) {
-                throw new ControlPlaneCorruptError(`scope directory collision: ${JSON.stringify(scope)} and ${JSON.stringify(other)} both map to ${JSON.stringify(dirName)} — refusing (fail-closed)`);
-            }
-            if (dirName !== "" && otherDir.toLowerCase() === dirName.toLowerCase()) {
-                const folds = opts?.caseFoldingFs ?? dirCaseFolds(memoryDir);
-                if (folds !== false) {
-                    throw new ControlPlaneCorruptError(`scope directory collision on a case-folding filesystem: ${JSON.stringify(scope)} → ${JSON.stringify(dirName)} and ${JSON.stringify(other)} → ${JSON.stringify(otherDir)} are one physical directory under ${memoryDir}` +
-                        `${folds === undefined ? " (volume case semantics could not be probed — refusing the fold-equal pair rather than risking a silent cross-scope merge)" : ""} — refusing (fail-closed)`);
-                }
-            }
-        }
+    return withScopesRegistry(controlDir, ({ read, commit }) => {
+        const rec = requireV2Registry(read(), controlDir);
+        const registered = ownLabel(rec.scopes, scope);
+        const label = registered ?? scopeDirName(scope);
+        assertNoLabelCollision(memoryDir, rec.scopes, scope, label, opts?.caseFoldingFs);
+        const home = join(memoryDir, label);
         if (registered === undefined) {
-            return { next: { ...rec, scopes: { ...rec.scopes, [scope]: dirName } }, result: dirName === "" ? memoryDir : join(memoryDir, dirName) };
+            ensureDirExists(memoryDir);
+            ensureScopeHome(home);
+            commit({ ...rec, scopes: { ...rec.scopes, [scope]: label } });
         }
-        return { result: dirName === "" ? memoryDir : join(memoryDir, dirName) };
+        else {
+            assertHomePhysicalForm(home);
+        }
+        return home;
     });
 }
 export function registeredScopes(controlDir) {
-    return readScopesRecord(controlDir).scopes ?? {};
+    return requireV2Registry(readScopesRecord(controlDir), controlDir).scopes;
 }
 export function scopeDirFor(memoryDir, controlDir, scope) {
-    const rec = readScopesRecord(controlDir);
-    if (rec.rootScope === scope)
-        return memoryDir;
-    const registered = rec.scopes !== undefined && Object.prototype.hasOwnProperty.call(rec.scopes, scope) ? rec.scopes[scope] : undefined;
-    if (registered !== undefined)
-        return registered === "" ? memoryDir : join(memoryDir, registered);
-    return join(memoryDir, scopeDirName(scope));
+    const rec = requireV2Registry(readScopesRecord(controlDir), controlDir);
+    return join(memoryDir, ownLabel(rec.scopes, scope) ?? scopeDirName(scope));
+}
+export function scopeRegistryShape(controlDir) {
+    return readScopesRecord(controlDir).shape;
+}
+export function v1MemoryPathKeyResolver(controlDir) {
+    const read = readScopesRecord(controlDir);
+    const owner = read.shape === "v1" ? read.rootScope : read.rec.rootOwner;
+    const scopes = read.shape === "v1" ? read.scopes : read.rec.scopes;
+    const byLabel = new Map();
+    for (const [scope, label] of Object.entries(scopes))
+        if (label !== "" && scope !== owner)
+            byLabel.set(label, scope);
+    return (relPath) => {
+        const norm = relPath.split(sep).join("/");
+        const cut = norm.indexOf("/");
+        if (cut > 0) {
+            const scope = byLabel.get(norm.slice(0, cut));
+            if (scope !== undefined)
+                return { scope, rel: norm.slice(cut + 1) };
+        }
+        return owner === undefined ? undefined : { scope: owner, rel: norm };
+    };
+}
+const UNOWNED_ROOT_CONTENT_NAMES_MAX = 8;
+function discloseLayoutIncident(sink, code, message) {
+    if (sink === undefined)
+        return;
+    try {
+        const e = new Error(message);
+        e.code = code;
+        sink(e);
+    }
+    catch {
+    }
+}
+function sameEntry(a, b) {
+    const sa = lstatOrAbsent(a);
+    const sb = lstatOrAbsent(b);
+    return sa !== undefined && sb !== undefined && sa.dev === sb.dev && sa.ino === sb.ino;
+}
+function looseRootContent(root, labels, controlDir) {
+    let names;
+    try {
+        names = readdirSync(root);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return { names: [], probes: [] };
+        throw new ControlPlaneCorruptError(`memory root ${root} could not be enumerated for the layout adoption (${err.code ?? "io error"}) — refusing (fail-closed)`, { cause: err });
+    }
+    const canonicalControl = canonicalize(controlDir);
+    const out = [];
+    const probes = [];
+    const foldedLabels = new Map();
+    for (const label of labels)
+        foldedLabels.set(label.toLowerCase(), label);
+    for (const name of names.sort()) {
+        if (labels.has(name))
+            continue;
+        if (name.startsWith(CASEFOLD_PROBE_PREFIX)) {
+            probes.push(name);
+            continue;
+        }
+        if (canonicalize(join(root, name)) === canonicalControl)
+            continue;
+        const label = foldedLabels.get(name.toLowerCase());
+        if (label !== undefined && sameEntry(join(root, name), join(root, label)))
+            continue;
+        out.push(name);
+    }
+    return { names: out, probes };
+}
+export function layoutNeedsAdoption(root, controlDir) {
+    const read = readScopesRecord(controlDir);
+    if (read.shape === "v1" || read.shape === "migrating")
+        return true;
+    const { names, probes } = looseRootContent(root, new Set(Object.values(read.rec.scopes)), controlDir);
+    return names.length > 0 || probes.length > 0;
+}
+export function adoptRootScopeLayout(rootPath, controlDir, opts = {}) {
+    const root = resolve(rootPath);
+    withScopesRegistry(controlDir, (ctx) => {
+        const renew = () => {
+            ctx.renew();
+            opts.renew?.();
+        };
+        const convertSidecars = () => {
+            renew();
+            opts.convertSidecars?.(controlDir);
+        };
+        const read = ctx.read();
+        let rec;
+        let converting = false;
+        if (read.shape === "v1") {
+            converting = true;
+            const scopes = Object.create(null);
+            for (const [scope, label] of Object.entries(read.scopes)) {
+                if (label === "")
+                    continue;
+                if (!SCOPE_DIR_LABEL_RE.test(label)) {
+                    throw new ControlPlaneCorruptError(`scope registry (v1 form) maps ${JSON.stringify(scope)} to the label ${JSON.stringify(label)}, which is not a single non-hidden path segment — refusing (fail-closed): ${join(controlDir, SCOPES_FILE)}`);
+                }
+                scopes[scope] = label;
+            }
+            rec = { v: 2, scopes, ...(read.rootScope !== undefined ? { rootOwner: read.rootScope } : {}) };
+            if (read.rootScope !== undefined && ownLabel(scopes, read.rootScope) === undefined) {
+                const label = scopeDirName(read.rootScope);
+                assertNoLabelCollision(root, scopes, read.rootScope, label, undefined);
+                const home = join(root, label);
+                if (assertHomePhysicalForm(home) === "dir" && readdirSync(home).length > 0) {
+                    throw new ControlPlaneCorruptError(`memory root ${root} holds a non-empty directory ${home} named like the home of its root-owning scope ${JSON.stringify(read.rootScope)} — the layout adoption cannot tell a topic directory from a home; resolve by hand (fail-closed)`);
+                }
+                rec.scopes = { ...scopes, [read.rootScope]: label };
+            }
+        }
+        else if (read.shape === "migrating") {
+            rec = read.rec;
+            const m = read.rec.migrating;
+            const { migrating: _m, ...rest } = rec;
+            rec = { ...rest, scopes: { ...rec.scopes, [m.owner]: m.label }, rootOwner: m.owner };
+            moveLooseContent(m.root, controlDir, rec, m.owner, m.label, renew, opts.onIncident, true);
+            convertSidecars();
+            ctx.commit(rec);
+            if (canonicalize(m.root) === canonicalize(root))
+                return;
+        }
+        else {
+            rec = read.rec;
+        }
+        const labels = new Set(Object.values(rec.scopes));
+        const { names, probes } = looseRootContent(root, labels, controlDir);
+        if (names.length === 0) {
+            if (converting) {
+                convertSidecars();
+                ctx.commit(rec);
+            }
+            for (const p of probes)
+                rmSync(join(root, p), { force: true });
+            return;
+        }
+        const candidate = opts.ownerCandidate ?? undefined;
+        const owner = rec.rootOwner ?? candidate;
+        if (owner === undefined) {
+            if (converting) {
+                convertSidecars();
+                ctx.commit(rec);
+            }
+            discloseLayoutIncident(opts.onIncident, "memory.layout_unowned_root_content", `memory root ${root} holds ${names.length} loose entr${names.length === 1 ? "y" : "ies"} that belong to no recorded scope (${names.slice(0, UNOWNED_ROOT_CONTENT_NAMES_MAX).join(", ")}${names.length > UNOWNED_ROOT_CONTENT_NAMES_MAX ? ", …" : ""}) — left in place, not served; the next mount with a write scope adopts them into that scope's home`);
+            return;
+        }
+        if (isContainedIn(root, controlDir)) {
+            throw new ControlPlaneCorruptError(`memory control plane ${controlDir} lies inside the memory root ${root} — the layout adoption refuses to move engine metadata as scope content (fail-closed)`);
+        }
+        const label = ownLabel(rec.scopes, owner) ?? scopeDirName(owner);
+        assertNoLabelCollision(root, rec.scopes, owner, label, undefined);
+        const home = join(root, label);
+        renew();
+        const homeForm = assertHomePhysicalForm(home);
+        if (homeForm === "dir") {
+            const inHome = readdirSync(home);
+            if (inHome.length > 0) {
+                throw new ControlPlaneCorruptError(`memory root ${root} holds loose content for ${JSON.stringify(owner)} while its home ${home} is already a non-empty directory with no move in progress — the two cannot be merged automatically (a topic directory named like the home, a root re-occupied by an older engine, or a registry that lost this scope's row); resolve by hand (fail-closed)`);
+            }
+        }
+        for (const name of names) {
+            renew();
+            if (lstatOrAbsent(join(home, name)) !== undefined) {
+                throw new ControlPlaneCorruptError(`memory root ${root} and the home ${home} both hold ${JSON.stringify(name)} — the layout adoption refuses to overwrite either (fail-closed)`);
+            }
+        }
+        const next = { v: 2, scopes: { ...rec.scopes, [owner]: label }, rootOwner: owner, migrating: { root, owner, label } };
+        renew();
+        ctx.commit(next);
+        const { migrating: _marker, ...done } = next;
+        moveLooseContent(root, controlDir, done, owner, label, renew, opts.onIncident, false);
+        convertSidecars();
+        renew();
+        ctx.commit(done);
+    });
+}
+function moveLooseContent(root, controlDir, rec, owner, label, renew, sink, resumed) {
+    const labels = new Set(Object.values(rec.scopes));
+    const { names, probes } = looseRootContent(root, labels, controlDir);
+    const home = join(root, label);
+    if (names.length > 0) {
+        ensureScopeHome(home);
+        chmodSync(home, 0o755);
+    }
+    let moved = 0;
+    for (const name of names) {
+        renew();
+        const src = join(root, name);
+        const dst = join(home, name);
+        if (sameEntry(src, home)) {
+            throw new ControlPlaneCorruptError(`memory root ${root}: ${JSON.stringify(name)} is the home ${home} itself under another spelling — the layout adoption refuses to move a directory into itself (fail-closed)`);
+        }
+        if (lstatOrAbsent(dst) !== undefined) {
+            throw new ControlPlaneCorruptError(`memory root ${root} and the home ${home} both hold ${JSON.stringify(name)} — the layout adoption refuses to overwrite either (fail-closed)`);
+        }
+        try {
+            renameSync(src, dst);
+            moved += 1;
+        }
+        catch (err) {
+            if (err.code === "ENOENT" && lstatOrAbsent(src) === undefined)
+                continue;
+            throw err;
+        }
+    }
+    for (const p of probes) {
+        renew();
+        rmSync(join(root, p), { force: true });
+    }
+    renew();
+    writeIndexRevs(controlDir, {});
+    discloseLayoutIncident(sink, "memory.layout_migrated", `memory layout adopted at ${root}: ${moved} loose entr${moved === 1 ? "y" : "ies"} moved into the home of ${JSON.stringify(owner)} (${label})${resumed ? " — an interrupted move was finished" : ""}`);
 }
 export function canonicalize(p) {
     try {
@@ -720,11 +994,17 @@ export function drainMemoryAnnouncements(controlDir) {
 export function peekMemoryAnnouncements(controlDir) {
     return coerceAnnouncements(readSidecarJson(controlDir, ANNOUNCEMENTS_FILE));
 }
+export function scanFuseKey(scope, rel) {
+    return JSON.stringify([scope, rel.split(sep).join("/")]);
+}
 function coerceFuse(raw) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
         return {};
+    const rec = raw;
+    if (rec.v !== 2 || !rec.counts || typeof rec.counts !== "object" || Array.isArray(rec.counts))
+        return {};
     const out = {};
-    for (const [k, v] of Object.entries(raw)) {
+    for (const [k, v] of Object.entries(rec.counts)) {
         if (typeof v === "number" && Number.isFinite(v) && v > 0)
             out[k] = Math.floor(v);
     }
@@ -736,7 +1016,7 @@ export function bumpScanFuse(controlDir, key) {
         const counts = coerceFuse(current);
         prior = counts[key] ?? 0;
         counts[key] = prior + 1;
-        return counts;
+        return { v: 2, counts };
     });
     return prior;
 }
@@ -992,7 +1272,7 @@ export function clearScanFuse(controlDir, keys) {
                 changed = true;
             }
         }
-        return changed ? counts : undefined;
+        return changed ? { v: 2, counts } : undefined;
     });
 }
 export const LINEAGE_FILE = "lineage.json";
@@ -1000,7 +1280,7 @@ export const CHALLENGES_FILE = "challenges.json";
 export const LINEAGE_AUDIT_FILE = "lineage-audit.json";
 export const LINEAGE_AUDIT_MAX_ROWS = 2048;
 export const CHALLENGED_HISTORY_FILE = "usage-challenged-history.json";
-function rollForwardStrictSidecar(file, journal) {
+function rollForwardStrictSidecar(file, journal, fence) {
     let raw;
     try {
         raw = readFileSync(journal, "utf8");
@@ -1014,7 +1294,9 @@ function rollForwardStrictSidecar(file, journal) {
     catch {
         throw new ControlPlaneCorruptError(`control-plane journal is unparseable (fail-closed sidecar): ${journal}`);
     }
+    fence?.();
     atomicWriteFileSync(file, raw);
+    fence?.();
     rmSync(journal, { force: true });
 }
 export function lockedStrictUpdate(controlDir, fileName, what, coerce, fn) {
@@ -1024,14 +1306,17 @@ export function lockedStrictUpdate(controlDir, fileName, what, coerce, fn) {
     const lock = `${file}.lock`;
     const token = acquireSidecarLock(lock, { onDeadline: "throw" });
     try {
-        rollForwardStrictSidecar(file, journal);
+        rollForwardStrictSidecar(file, journal, () => assertSidecarLockOwnership(lock, token, what, "strict"));
         const current = coerce(readStrictSidecarRaw(file, what));
         const { next, result } = fn(current);
         if (next !== undefined) {
             const data = `${JSON.stringify(next, null, 2)}\n`;
-            assertSidecarLockOwnership(lock, token, what, "strict");
+            const fence = () => assertSidecarLockOwnership(lock, token, what, "strict");
+            fence();
             atomicWriteFileSync(journal, data);
+            fence();
             atomicWriteFileSync(file, data);
+            fence();
             rmSync(journal, { force: true });
         }
         return result;
@@ -1628,63 +1913,115 @@ export function readChallengedHistory(controlDir) {
     return coerceChallengedHistory(readSidecarJson(controlDir, CHALLENGED_HISTORY_FILE));
 }
 export const PROJECTION_DEBTS_FILE = "projection-debts.json";
+function safeLedgerRel(rel) {
+    return typeof rel === "string" && rel.length > 0 && !rel.startsWith("/") && !rel.split(/[\\/]/).includes("..");
+}
+function malformedDebtRow(row) {
+    return (typeof row !== "object" ||
+        row === null ||
+        typeof row.entryId !== "string" ||
+        row.entryId.length === 0 ||
+        typeof row.rev !== "string" ||
+        row.rev.length === 0 ||
+        typeof row.at !== "number" ||
+        !Number.isFinite(row.at));
+}
 function coerceProjectionDebts(raw) {
     if (raw === undefined)
-        return { version: 1, rows: [] };
+        return { version: 2, rows: [] };
     const rec = raw;
-    if (typeof rec !== "object" || rec === null || rec.version !== 1 || !Array.isArray(rec.rows)) {
+    if (typeof rec !== "object" || rec === null || (rec.version !== 1 && rec.version !== 2) || !Array.isArray(rec.rows)) {
         throw new ControlPlaneCorruptError("memory projection-debt ledger has the wrong shape — refusing (fail-closed; an unreadable debt account must not read as 'no debts')");
     }
-    for (const r of rec.rows) {
-        const row = r;
-        if (typeof row !== "object" ||
-            row === null ||
-            typeof row.relPath !== "string" ||
-            row.relPath.length === 0 ||
-            row.relPath.startsWith("/") ||
-            row.relPath.split(/[\\/]/).includes("..") ||
-            typeof row.entryId !== "string" ||
-            row.entryId.length === 0 ||
-            typeof row.rev !== "string" ||
-            row.rev.length === 0 ||
-            typeof row.at !== "number" ||
-            !Number.isFinite(row.at)) {
-            throw new ControlPlaneCorruptError("memory projection-debt ledger: a row is malformed — refusing (fail-closed)");
+    const bad = () => {
+        throw new ControlPlaneCorruptError("memory projection-debt ledger: a row is malformed — refusing (fail-closed)");
+    };
+    const rows = rec.rows;
+    if (rec.version === 1) {
+        for (const r of rows) {
+            const row = r;
+            if (malformedDebtRow(row) || !safeLedgerRel(row.relPath))
+                bad();
         }
+        return { version: 1, rows: rows };
     }
-    return rec;
+    for (const r of rows) {
+        const row = r;
+        if (malformedDebtRow(row) || typeof row.scope !== "string" || row.scope.length === 0 || !safeLedgerRel(row.rel))
+            bad();
+    }
+    const unresolved = rec.unresolved === undefined ? undefined : Array.isArray(rec.unresolved) ? rec.unresolved : bad();
+    for (const r of unresolved ?? []) {
+        const row = r;
+        if (malformedDebtRow(row) || !safeLedgerRel(row.relPath))
+            bad();
+    }
+    return { version: 2, rows: rows, ...(unresolved !== undefined ? { unresolved: unresolved } : {}) };
+}
+function convertProjectionDebts(read, controlDir) {
+    if (read.version === 2)
+        return { rec: read, converted: false };
+    const resolve = v1MemoryPathKeyResolver(controlDir);
+    const rows = [];
+    const unresolved = [];
+    for (const r of read.rows) {
+        const key = resolve(r.relPath);
+        if (key === undefined)
+            unresolved.push(r);
+        else
+            rows.push({ scope: key.scope, rel: key.rel, entryId: r.entryId, rev: r.rev, at: r.at });
+    }
+    return { rec: { version: 2, rows, ...(unresolved.length > 0 ? { unresolved } : {}) }, converted: true };
+}
+function debtSeatKey(scope, rel) {
+    return JSON.stringify([scope, rel]);
 }
 export function stageProjectionDebts(controlDir, rows, now) {
     if (rows.length === 0)
         return { refused: [] };
     const at = now();
-    return lockedStrictUpdate(controlDir, PROJECTION_DEBTS_FILE, "memory projection-debt ledger", coerceProjectionDebts, (rec) => {
-        const byPath = new Map(rec.rows.map((r) => [r.relPath, r]));
+    return lockedStrictUpdate(controlDir, PROJECTION_DEBTS_FILE, "memory projection-debt ledger", coerceProjectionDebts, (read) => {
+        const { rec } = convertProjectionDebts(read, controlDir);
+        const bySeat = new Map(rec.rows.map((r) => [debtSeatKey(r.scope, r.rel), r]));
         const refused = [];
         for (const r of rows) {
-            const existing = byPath.get(r.relPath);
+            const seat = debtSeatKey(r.scope, r.rel);
+            const existing = bySeat.get(seat);
             if (existing !== undefined && existing.entryId !== r.entryId && existing.entryId !== r.replaces) {
-                refused.push({ relPath: r.relPath, entryId: r.entryId });
+                refused.push({ scope: r.scope, rel: r.rel, entryId: r.entryId });
                 continue;
             }
-            byPath.set(r.relPath, { relPath: r.relPath, entryId: r.entryId, rev: r.rev, at });
+            bySeat.set(seat, { scope: r.scope, rel: r.rel, entryId: r.entryId, rev: r.rev, at });
         }
-        return { next: { version: 1, rows: [...byPath.values()] }, result: { refused } };
+        return { next: { ...rec, version: 2, rows: [...bySeat.values()] }, result: { refused } };
     });
 }
 export function settleProjectionDebts(controlDir, rows) {
     if (rows.length === 0)
         return;
-    const drop = new Set(rows.map((r) => JSON.stringify([r.entryId, r.relPath])));
-    lockedStrictUpdate(controlDir, PROJECTION_DEBTS_FILE, "memory projection-debt ledger", coerceProjectionDebts, (rec) => {
-        const kept = rec.rows.filter((r) => !drop.has(JSON.stringify([r.entryId, r.relPath])));
-        if (kept.length === rec.rows.length)
+    const drop = new Set(rows.map((r) => JSON.stringify([r.entryId, r.scope, r.rel])));
+    lockedStrictUpdate(controlDir, PROJECTION_DEBTS_FILE, "memory projection-debt ledger", coerceProjectionDebts, (read) => {
+        const { rec, converted } = convertProjectionDebts(read, controlDir);
+        const kept = rec.rows.filter((r) => !drop.has(JSON.stringify([r.entryId, r.scope, r.rel])));
+        if (kept.length === rec.rows.length && !converted)
             return { result: undefined };
-        return { next: { version: 1, rows: kept }, result: undefined };
+        return { next: { ...rec, version: 2, rows: kept }, result: undefined };
     });
 }
 export function readProjectionDebts(controlDir) {
-    return coerceProjectionDebts(readStrictSidecar(controlDir, PROJECTION_DEBTS_FILE, "memory projection-debt ledger")).rows;
+    const read = coerceProjectionDebts(readStrictSidecar(controlDir, PROJECTION_DEBTS_FILE, "memory projection-debt ledger"));
+    if (read.version === 2)
+        return read.rows;
+    return lockedStrictUpdate(controlDir, PROJECTION_DEBTS_FILE, "memory projection-debt ledger", coerceProjectionDebts, (again) => {
+        const { rec, converted } = convertProjectionDebts(again, controlDir);
+        return converted ? { next: rec, result: rec.rows } : { result: rec.rows };
+    });
+}
+export function unresolvedProjectionDebts(controlDir) {
+    const read = coerceProjectionDebts(readStrictSidecar(controlDir, PROJECTION_DEBTS_FILE, "memory projection-debt ledger"));
+    if (read.version === 1)
+        return read.rows.map((r) => ({ relPath: r.relPath, entryId: r.entryId }));
+    return (read.unresolved ?? []).map((r) => ({ relPath: r.relPath, entryId: r.entryId }));
 }
 export function writeAllSync(fd, data) {
     const buf = Buffer.from(data, "utf8");