@sema-agent/core 5.38.0 → 5.40.0

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

@@ -1,11 +1,12 @@
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, openSync, fsyncSync, closeSync } from "node:fs";
+import { existsSync, linkSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, openSync, fsyncSync, closeSync } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import { dirname, join, relative } from "node:path";
 import { jaccardDistance, termSet } from "../memory-vector.js";
 import { MAX_MEMORY_BYTES } from "../memory.js";
 import { inlineUntrusted } from "../untrusted-text.js";
 import { computeEntryRev, entryFromFile, isValidEntryId, parseEntryFile, serializeEntryFile } from "./frontmatter.js";
-import { ControlPlaneCorruptError, CURSORS_FILE, QUARANTINE_DIR, atomicWriteFileSync, quarantineAndTombstone, captureAndClearLineageForEntries, claimRootScope, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, ensureDirExists, enqueueMemoryAnnouncement, isContainedIn, lineageContributionsOfSession, readLineageRecord, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, writeAllSync, } from "./layout.js";
+import { ControlPlaneCorruptError, CURSORS_FILE, QUARANTINE_DIR, CHALLENGES_FILE, IMPORT_RECEIPTS_DIR, LINEAGE_FILE, SESSION_POLLUTION_DIR, appendChallengeEvents, atomicWriteFileSync, quarantineAndTombstone, captureAndClearLineageForEntries, claimRootScope, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, ensureDirExists, enqueueMemoryAnnouncement, importLatchTxnId, importLineageCommitted, importSessionPollution, isContainedIn, lineageContributionsOfSession, listSessionPollution, readChallengeEvents, readLineageRecord, registerScope, registeredScopes, releaseImportLatch, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, stageImportLatch, writeAllSync, } from "./layout.js";
+import { screenInboundEntries } from "./data-plane.js";
 import { scanMemoryFileName, scanMemoryWrite } from "./scan.js";
 export const MEMORY_INDEX_FILENAME = "MEMORY.md";
 export const DEFAULT_MAX_ENTRY_DEPTH = 3;
@@ -159,6 +160,7 @@ const TXN_LOCK_STALE_MS = 30_000;
 const TXN_LOCK_WAIT_MS = 15_000;
 const TXN_LOCK_STEAL_GRACE_MS = 250;
 const SHADOW_DIR = "shadow";
+const STORE_IDENTITY_FILE = "store-identity.json";
 function rowsRev(rows, id) {
     return rows[id]?.rev;
 }
@@ -331,9 +333,18 @@ function transferEventInvalid(raw) {
         return "non-string/empty 'origin'";
     if (e.srcEv !== undefined && (typeof e.srcEv !== "string" || e.srcEv.length === 0))
         return "non-string/empty 'srcEv'";
+    const redactedKeys = new Set();
     if (e.redacted !== undefined) {
-        if (e.redacted !== true)
-            return "'redacted', when present, must be literal true";
+        const list = Array.isArray(e.redacted) ? e.redacted : undefined;
+        if (list === undefined || list.length === 0)
+            return "'redacted', when present, must be a non-empty array naming the removed keys";
+        for (const k of list) {
+            if (k !== "from" && k !== "to")
+                return "'redacted' may only name 'from'/'to'";
+            if (redactedKeys.has(k))
+                return "'redacted' names a key twice";
+            redactedKeys.add(k);
+        }
         if (e.origin === undefined)
             return "'redacted' requires the import pair (origin/srcEv) — a local row is never redacted";
     }
@@ -349,12 +360,25 @@ function transferEventInvalid(raw) {
     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))
+        if (e.to !== undefined && redactedKeys.has("to"))
+            return "'to' is present but named in 'redacted'";
+        if (e.from !== undefined && redactedKeys.has("from"))
+            return "'from' is present but named in 'redacted'";
+        if (e.to === undefined) {
+            if (!redactedKeys.has("to"))
+                return "row transfer missing/malformed 'to'";
+        }
+        else 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 (e.from === undefined) {
+            if (!redactedKeys.has("from"))
+                return `'${e.channel}' requires a well-formed 'from'`;
+        }
         else if (bindingInvalid(e.from)) {
             return `'${e.channel}' requires a well-formed 'from'`;
         }
@@ -516,6 +540,7 @@ export class FileMemoryEngineBackend {
     unboundRowsKnown = false;
     adoptionNoticeKeys = new Set();
     transfersAppendFault;
+    exportFaceProbe;
     deletedIdsDigest;
     inboundFindings = [];
     batchScan;
@@ -2704,7 +2729,7 @@ export class FileMemoryEngineBackend {
             `(or the ledger kept advancing) across every try — the committed account cannot be snapshotted without tearing. ` +
             `A journal that never clears is a crashed transaction: the next backend construction or locked write recovers it.`);
     }
-    resolveCommittedContent(id, rev, binding, final) {
+    resolveCommittedContent(id, rev, binding, final, lockHeld = false) {
         if (binding === undefined)
             return { state: "unavailable", reason: "carrier-missing" };
         if (!isValidEntryId(id))
@@ -2726,6 +2751,8 @@ export class FileMemoryEngineBackend {
                     if (projEntry.rev === rev)
                         return { state: "present", entry: projEntry };
                 }
+                if (lockHeld)
+                    return { state: "unavailable", reason: "carrier-missing" };
                 if (!final)
                     throw new AuditObservationUnstableError(`shadow bytes for ${id} do not carry the committed rev — possible adoption in flight`);
                 if (this.txnInFlight()) {
@@ -2884,6 +2911,610 @@ export class FileMemoryEngineBackend {
         }
         return out;
     }
+    static EXPORT_INCOMPLETE = "memory.export_incomplete";
+    storeIdentityLocked() {
+        const path = join(this.controlPlaneRoot, STORE_IDENTITY_FILE);
+        const parse = (raw) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                throw new ControlPlaneCorruptError(`store identity is unparseable: ${path}`);
+            }
+            const rec = parsed;
+            if (!rec || typeof rec !== "object" || rec.v !== 1 || typeof rec.storeId !== "string" || rec.storeId.length === 0) {
+                throw new ControlPlaneCorruptError(`store identity has the wrong shape: ${path}`);
+            }
+            return rec.storeId;
+        };
+        const raw = readControlFileOrAbsent(path, "store identity");
+        if (raw !== undefined)
+            return parse(raw);
+        const storeId = randomUUID();
+        let fd;
+        try {
+            fd = openSync(path, "wx", 0o600);
+        }
+        catch (err) {
+            if (err.code === "EEXIST") {
+                const again = readControlFileOrAbsent(path, "store identity");
+                if (again === undefined)
+                    throw new ControlPlaneCorruptError(`store identity vanished between its EEXIST and the re-read: ${path}`);
+                return parse(again);
+            }
+            throw err;
+        }
+        try {
+            writeAllSync(fd, `${JSON.stringify({ v: 1, storeId }, null, 2)}\n`);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        return storeId;
+    }
+    exportGovernanceFingerprint() {
+        const h = createHash("sha256");
+        const feed = (label, text) => {
+            h.update(JSON.stringify([label, text]));
+        };
+        for (const file of [LINEAGE_FILE, CHALLENGES_FILE]) {
+            feed(file, readControlFileOrAbsent(join(this.controlPlaneRoot, file), `${file} (export fence)`) ?? "<absent>");
+            let journalRaw;
+            try {
+                journalRaw = readControlFileOrAbsent(join(this.controlPlaneRoot, `${file}.journal`), `${file} journal (export fence)`);
+            }
+            catch (err) {
+                throw erasureCodedError(`memory export refused: the ${file} journal could not be read (${err instanceof Error ? err.message : String(err)}) — a journal read failure is not absence, and exporting over it could seal stale governance under an honest hash`, FileMemoryEngineBackend.EXPORT_INCOMPLETE);
+            }
+            feed(`${file}.journal`, journalRaw ?? "<absent>");
+        }
+        const dir = join(this.controlPlaneRoot, SESSION_POLLUTION_DIR);
+        let names = [];
+        try {
+            names = readdirSync(dir).sort();
+        }
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                throw new ControlPlaneCorruptError(`session pollution markers could not be enumerated for export (${err.code ?? "io error"}) at ${dir} — fail-closed`, { cause: err });
+            }
+        }
+        for (const name of names) {
+            let text;
+            try {
+                text = readFileSync(join(dir, name), "utf8");
+            }
+            catch (err) {
+                text = `<unreadable:${err.code ?? "io error"}>`;
+            }
+            feed(`pollution/${name}`, text);
+        }
+        return h.digest("hex");
+    }
+    readExportChainRowsPure() {
+        const path = join(this.controlPlaneRoot, TRANSFERS_FILE);
+        const raw = readControlFileOrAbsent(path, "transfer evidence log");
+        const out = [];
+        if (raw === undefined)
+            return out;
+        const byEv = new Map();
+        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 {
+                if (lines.slice(i + 1).every((l) => l === "")) {
+                    throw erasureCodedError(`memory export refused: the transfer evidence log has a torn tail (line ${i + 1}) — the export reads it purely (the file is untouched); run any locked mutation entry (a write, an adopting read) to heal the chain, then export again`, FileMemoryEngineBackend.EXPORT_INCOMPLETE);
+                }
+                throw new ControlPlaneCorruptError(`transfer evidence log line ${i + 1} is unparseable (not a torn tail — fail-closed): ${path}`);
+            }
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new ControlPlaneCorruptError(`transfer evidence log line ${i + 1} is not an object (fail-closed): ${path}`);
+            }
+            const e = parsed;
+            if (typeof e.ev !== "string" || e.ev.length === 0 || typeof e.channel !== "string" || e.channel.length === 0 || typeof e.at !== "number" || !Number.isInteger(e.at)) {
+                throw new ControlPlaneCorruptError(`transfer evidence log line ${i + 1} is missing its base keys (ev/channel/at) — fail-closed: ${path}`);
+            }
+            if (!KNOWN_TRANSFER_CHANNELS.has(e.channel)) {
+                throw erasureCodedError(`memory export refused: the evidence chain carries channel ${JSON.stringify(e.channel)} this exporter does not know (line ${i + 1}) — an unknown row can neither be tenant-sliced nor silently dropped; export with the binary that wrote it (or newer)`, FileMemoryEngineBackend.EXPORT_INCOMPLETE);
+            }
+            const invalid = transferEventInvalid(parsed);
+            if (invalid !== undefined)
+                throw new ControlPlaneCorruptError(`transfer evidence log line ${i + 1} is invalid (${invalid}): ${path}`);
+            const canonical = canonicalJsonStringify(e);
+            const prior = byEv.get(e.ev);
+            if (prior !== undefined) {
+                if (prior !== canonical) {
+                    throw erasureCodedError(`memory export refused: the evidence chain carries event id ${JSON.stringify(e.ev)} twice with DIFFERENT payloads (line ${i + 1}) — a spliced chain cannot be exported`, FileMemoryEngineBackend.EXPORT_INCOMPLETE);
+                }
+                continue;
+            }
+            byEv.set(e.ev, canonical);
+            out.push(e);
+        }
+        return out;
+    }
+    sliceCustodyForScopes(rows, scopeSet, fullStore, storeId) {
+        const custody = [];
+        let unsliceable = 0;
+        for (const e of rows) {
+            const channel = e.channel;
+            if (channel === "migration" || channel === "erasure-anchor")
+                continue;
+            if (channel === "erasure-request") {
+                if (scopeSet.has(e.scope))
+                    custody.push(e);
+                continue;
+            }
+            if (channel === "delete") {
+                const from = e.from;
+                if (from !== undefined && typeof from.scope === "string") {
+                    if (scopeSet.has(from.scope))
+                        custody.push(e);
+                }
+                else if (fullStore) {
+                    custody.push(e);
+                }
+                else {
+                    unsliceable++;
+                }
+                continue;
+            }
+            const from = e.from;
+            const to = e.to;
+            const fromIn = from !== undefined && typeof from.scope === "string" && scopeSet.has(from.scope);
+            const toIn = to !== undefined && typeof to.scope === "string" && scopeSet.has(to.scope);
+            if (!fromIn && !toIn)
+                continue;
+            if ((from === undefined || fromIn) && (to === undefined || toIn)) {
+                custody.push(e);
+                continue;
+            }
+            const redacted = { ...e };
+            const named = new Set(Array.isArray(e.redacted) ? e.redacted : []);
+            if (from !== undefined && !fromIn) {
+                delete redacted.from;
+                named.add("from");
+            }
+            if (to !== undefined && !toIn) {
+                delete redacted.to;
+                named.add("to");
+            }
+            redacted.redacted = [...named].sort();
+            if (redacted.origin === undefined) {
+                redacted.origin = storeId();
+                redacted.srcEv = e.ev;
+            }
+            custody.push(redacted);
+        }
+        return { custody, unsliceable };
+    }
+    enumerateQuarantineFor(ids) {
+        const qDir = join(this.controlPlaneRoot, QUARANTINE_DIR);
+        let names = [];
+        try {
+            names = readdirSync(qDir);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                throw new ControlPlaneCorruptError(`export residual enumeration failed: the quarantine dir could not be read (${err.code ?? "io error"}) at ${qDir} — a bundle must not silently claim an empty residual set`);
+            }
+        }
+        const quarantined = [];
+        let quarantineOpaque = 0;
+        for (const name of names.sort()) {
+            const text = readSafe(join(qDir, name));
+            if (text === undefined) {
+                quarantineOpaque++;
+                continue;
+            }
+            const qid = parseEntryFile(text).id;
+            if (qid === undefined) {
+                quarantineOpaque++;
+                continue;
+            }
+            if (ids.has(qid))
+                quarantined.push(name);
+        }
+        return { quarantined, quarantineOpaque };
+    }
+    async exportSnapshotOf(scopes, timings) {
+        const scopeSet = new Set(scopes);
+        const lock = await this.acquireTxnLock(timings);
+        try {
+            this.assertTxnLockOwnership(lock.token);
+            this.ledger = undefined;
+            this.recoverJournal();
+            const rows = this.loadLedger();
+            if (this.persistedSchemaVersion !== "v2") {
+                throw erasureCodedError("memory export refused: the committed-rev ledger is still schema v1 (pre-binding) — the store migrates itself at its next write/read entry or checkControlPlane; an export never triggers the migration", FileMemoryEngineBackend.EXPORT_INCOMPLETE);
+            }
+            if (this.chainDegradedMarkerPresent()) {
+                throw erasureCodedError("memory export refused: the custody chain carries the durable degradation marker (transfers.chain-degraded.json) — evidence rows were lost to an out-of-band tear and a bundle cannot testify to a complete deletion history; resolve the marker deliberately before exporting", FileMemoryEngineBackend.EXPORT_INCOMPLETE);
+            }
+            const storeId = this.storeIdentityLocked();
+            const registered = registeredScopes(this.controlPlaneRoot);
+            const fullStore = Object.keys(registered).every((s) => scopeSet.has(s));
+            for (let round = 0; round < 3; round++) {
+                const before = this.exportGovernanceFingerprint();
+                const lineageRec = readLineageRecord(this.controlPlaneRoot);
+                const challenges = readChallengeEvents(this.controlPlaneRoot);
+                const polluted = listSessionPollution(this.controlPlaneRoot);
+                const chainRows = this.readExportChainRowsPure();
+                this.exportFaceProbe?.(round);
+                const after = this.exportGovernanceFingerprint();
+                if (before !== after)
+                    continue;
+                const latched = new Set();
+                for (const txn of Object.values(lineageRec.pending))
+                    for (const row of txn.rows)
+                        latched.add(row.entryId);
+                const entries = [];
+                const contentUnavailable = [];
+                const boundIdsInScopes = new Set();
+                for (const [id, row] of rowsEntries(rows)) {
+                    const binding = rowsBinding(rows, id);
+                    if (binding === undefined || !scopeSet.has(binding.scope))
+                        continue;
+                    boundIdsInScopes.add(id);
+                    if (latched.has(id))
+                        continue;
+                    const content = this.resolveCommittedContent(id, row.rev, binding, true, true);
+                    if (content.state === "present")
+                        entries.push(content.entry);
+                    else
+                        contentUnavailable.push({ id, scope: binding.scope, slug: binding.slug, rev: row.rev, reason: content.reason });
+                }
+                const sliced = this.sliceCustodyForScopes(chainRows, scopeSet, fullStore, () => storeId);
+                const residual = this.enumerateQuarantineFor(boundIdsInScopes);
+                const lineage = [];
+                for (const [entryId, sessions] of Object.entries(lineageRec.committed)) {
+                    for (const [sessionId, c] of Object.entries(sessions))
+                        lineage.push({ entryId, sessionId, lastRev: c.lastRev, lastAt: c.lastAt });
+                }
+                const pollutedSessions = Object.entries(polluted).map(([sessionId, r]) => ({ sessionId, at: r.at, reason: r.reason }));
+                try {
+                    this.assertTxnLockOwnership(lock.token);
+                }
+                catch (err) {
+                    throw erasureCodedError(`memory export refused: the transaction lock was lost during assembly (a stalled hold past the stale line was stolen from) — the read set can no longer be proven consistent; retry the export (${err instanceof Error ? err.message : String(err)})`, FileMemoryEngineBackend.EXPORT_INCOMPLETE);
+                }
+                return {
+                    storeId,
+                    fullStore,
+                    entries,
+                    contentUnavailable,
+                    unbound: unboundRowIds(rows).sort(),
+                    pendingLatch: [...latched].sort(),
+                    custody: sliced.custody,
+                    unsliceableCustody: sliced.unsliceable,
+                    challenges,
+                    lineage,
+                    pollutedSessions,
+                    quarantined: residual.quarantined,
+                    quarantineOpaque: residual.quarantineOpaque,
+                };
+            }
+            throw erasureCodedError("memory export refused: the governance faces (challenge/lineage/pollution) kept changing across three consistency rounds — the store is too hot to snapshot without tearing; retry when its writers settle", FileMemoryEngineBackend.EXPORT_INCOMPLETE);
+        }
+        finally {
+            lock.release();
+        }
+    }
+    async governanceExport(scopes, timings) {
+        const scopeSet = new Set(scopes);
+        const lock = await this.acquireTxnLock(timings);
+        try {
+            this.assertTxnLockOwnership(lock.token);
+            this.ledger = undefined;
+            this.recoverJournal();
+            const rows = this.loadLedger();
+            if (this.persistedSchemaVersion !== "v2")
+                return { custody: [], unbound: [], complete: false, unsliceableCustody: 0, reason: "the committed-rev ledger is still schema v1 (migrate first)" };
+            if (this.chainDegradedMarkerPresent()) {
+                return { custody: [], unbound: [], complete: false, unsliceableCustody: 0, reason: "the custody chain carries the durable degradation marker (transfers.chain-degraded.json) — evidence rows were lost to an out-of-band tear" };
+            }
+            const registered = registeredScopes(this.controlPlaneRoot);
+            const fullStore = Object.keys(registered).every((s) => scopeSet.has(s));
+            try {
+                const chainRows = this.readExportChainRowsPure();
+                const sliced = this.sliceCustodyForScopes(chainRows, scopeSet, fullStore, () => this.storeIdentityLocked());
+                this.assertTxnLockOwnership(lock.token);
+                return { custody: sliced.custody, unbound: unboundRowIds(rows).sort(), complete: true, unsliceableCustody: sliced.unsliceable };
+            }
+            catch (err) {
+                if (err.code === FileMemoryEngineBackend.EXPORT_INCOMPLETE || err instanceof ControlPlaneCorruptError) {
+                    if (err instanceof ControlPlaneCorruptError && !err.message.includes("ownership"))
+                        throw err;
+                    return { custody: [], unbound: [], complete: false, unsliceableCustody: 0, reason: err instanceof Error ? err.message : String(err) };
+                }
+                throw err;
+            }
+        }
+        finally {
+            lock.release();
+        }
+    }
+    async custodyImport(rows, opts, timings) {
+        if (typeof opts?.bundleHash !== "string" || opts.bundleHash.length === 0 || typeof opts.sourceStoreId !== "string" || opts.sourceStoreId.length === 0) {
+            throw erasureCodedError("custodyImport: bundleHash and sourceStoreId are required (the remint namespace and the origin stamp)", "config.memory_import_request");
+        }
+        const lock = await this.acquireTxnLock(timings);
+        try {
+            this.assertTxnLockOwnership(lock.token);
+            this.recoverJournal();
+            return this.custodyImportLocked(rows, opts);
+        }
+        finally {
+            lock.release();
+        }
+    }
+    custodyImportLocked(rows, opts) {
+        const withheld = [];
+        const toAppend = [];
+        for (const row of rows) {
+            const channel = typeof row.channel === "string" ? row.channel : "<malformed>";
+            const srcEv = typeof row.srcEv === "string" ? row.srcEv : typeof row.ev === "string" ? row.ev : "<malformed>";
+            if (typeof row.ev !== "string" || row.ev.length === 0 || typeof row.channel !== "string" || row.channel.length === 0 || typeof row.at !== "number" || !Number.isInteger(row.at)) {
+                withheld.push({ srcEv, channel });
+                continue;
+            }
+            if (!KNOWN_TRANSFER_CHANNELS.has(row.channel)) {
+                withheld.push({ srcEv, channel });
+                continue;
+            }
+            if (transferEventInvalid(row) !== undefined) {
+                withheld.push({ srcEv, channel });
+                continue;
+            }
+            const reminted = {
+                ...row,
+                ev: `imp:${opts.bundleHash}:${row.ev}`,
+                origin: row.origin ?? opts.sourceStoreId,
+                srcEv: row.srcEv ?? row.ev,
+            };
+            if (transferEventInvalid(reminted) !== undefined) {
+                withheld.push({ srcEv, channel });
+                continue;
+            }
+            toAppend.push(reminted);
+        }
+        this.appendTransfers(toAppend);
+        return { appended: toAppend.length, withheld };
+    }
+    appendImportChallengesVerified(events) {
+        if (events.length === 0)
+            return;
+        const { assignments } = appendChallengeEvents(this.controlPlaneRoot, events, this.now);
+        const replayed = assignments.filter((a) => a.replayed);
+        if (replayed.length === 0)
+            return;
+        const byEventId = new Map();
+        for (const e of readChallengeEvents(this.controlPlaneRoot))
+            if (!byEventId.has(e.eventId))
+                byEventId.set(e.eventId, e);
+        for (const a of replayed) {
+            const want = events.find((e) => e.eventId === a.eventId);
+            const got = byEventId.get(a.eventId);
+            if (want === undefined || got === undefined || got.kind !== "challenge" || got.entryId !== want.entryId || got.reason !== want.reason || got.challengedRev !== want.challengedRev) {
+                throw new ControlPlaneCorruptError(`bundle import aborted: challenge event ${JSON.stringify(a.eventId)} replayed onto an existing ledger event with a DIFFERENT payload (kind/entryId/reason/challengedRev) — key idempotency would silently swallow the imported challenge; the import latch stays until a clean re-import converges`);
+            }
+        }
+    }
+    async importBundleCommit(plan, timings) {
+        const bundleHash = typeof plan?.bundleHash === "string" ? plan.bundleHash : "";
+        const sourceStoreId = typeof plan?.sourceStoreId === "string" ? plan.sourceStoreId : "";
+        if (!/^[0-9a-f]{64}$/.test(bundleHash) || sourceStoreId.length === 0) {
+            throw erasureCodedError("importBundleCommit: plan.bundleHash must be the 64-hex bundle digest and sourceStoreId a non-empty string", "config.memory_import_request");
+        }
+        const lock = await this.acquireTxnLock(timings);
+        try {
+            this.assertTxnLockOwnership(lock.token);
+            this.ledger = undefined;
+            this.recoverJournal();
+            this.migrateLockedIfNeeded(lock.token);
+            const ctl = this.controlPlaneRoot;
+            const txnId = importLatchTxnId(bundleHash);
+            const receiptPath = join(ctl, IMPORT_RECEIPTS_DIR, `${bundleHash}.json`);
+            const receiptRaw = readControlFileOrAbsent(receiptPath, "bundle import completion receipt");
+            if (receiptRaw !== undefined) {
+                let report;
+                try {
+                    const parsed = JSON.parse(receiptRaw);
+                    if (parsed === null ||
+                        typeof parsed !== "object" ||
+                        !("v" in parsed) ||
+                        parsed.v !== 1 ||
+                        !("bundleHash" in parsed) ||
+                        parsed.bundleHash !== bundleHash ||
+                        !("report" in parsed)) {
+                        throw new Error("wrong envelope");
+                    }
+                    const rep = parsed.report;
+                    if (!rep ||
+                        typeof rep !== "object" ||
+                        rep.v !== 1 ||
+                        rep.bundleHash !== bundleHash ||
+                        typeof rep.sourceStoreId !== "string" ||
+                        !Array.isArray(rep.landed) ||
+                        !Array.isArray(rep.alreadyPresent) ||
+                        !Array.isArray(rep.refusedErased) ||
+                        !Array.isArray(rep.refusedUntrusted) ||
+                        !Array.isArray(rep.conflicts) ||
+                        !Array.isArray(rep.governanceWithheld) ||
+                        !Array.isArray(rep.erasedAtSource) ||
+                        !Array.isArray(rep.pollutionDivergence) ||
+                        !Array.isArray(rep.referentialOrphans) ||
+                        !Array.isArray(rep.lineageDivergence) ||
+                        !Array.isArray(rep.custodyWithheld) ||
+                        typeof rep.custodyAppended !== "number") {
+                        throw new Error("wrong report shape");
+                    }
+                    report = rep;
+                }
+                catch {
+                    throw new ControlPlaneCorruptError(`bundle import completion receipt is unreadable/malformed at ${receiptPath} — it cannot prove completion and cannot be re-minted; repair or remove it deliberately (fail-closed)`);
+                }
+                releaseImportLatch(ctl, txnId);
+                return report;
+            }
+            const digest = this.deletedIdsDigestLocked();
+            if (digest.state === "damaged" || this.chainDegradedMarkerPresent()) {
+                throw erasureCodedError("memory bundle import refused: the destination evidence chain is damaged or durably marked degraded — deletion history cannot be proven, so the anti-resurrection judgment cannot run; heal/rebuild the chain (locked mutation entry / explicit rebuild), then import again (nothing was landed, no latch was set)", "memory.import_rejected");
+            }
+            stageImportLatch(ctl, bundleHash, plan.entries.map((e) => ({ entryId: e.id, rev: e.rev })), this.now);
+            const rows = this.loadLedger();
+            const rowPresent = (id) => Object.prototype.hasOwnProperty.call(rows, id);
+            const report = {
+                v: 1,
+                bundleHash,
+                sourceStoreId,
+                landed: [],
+                alreadyPresent: [],
+                refusedErased: [],
+                refusedUntrusted: [],
+                conflicts: [],
+                governanceWithheld: [],
+                erasedAtSource: [],
+                pollutionDivergence: [],
+                referentialOrphans: [],
+                lineageDivergence: [],
+                custodyWithheld: [],
+                custodyAppended: 0,
+            };
+            const entryById = new Map(plan.entries.map((e) => [e.id, e]));
+            const toLand = [];
+            for (const e of plan.entries) {
+                const present = rowPresent(e.id);
+                if (!present && digest.ids.has(e.id)) {
+                    report.refusedErased.push(e.id);
+                    continue;
+                }
+                if (present && rowsRev(rows, e.id) === e.rev && rowsBinding(rows, e.id)?.scope === e.scope) {
+                    report.alreadyPresent.push(e.id);
+                    continue;
+                }
+                if (!present && e.frontmatter.provenance?.kind === "repo_file" && e.frontmatter.trust === undefined) {
+                    report.refusedUntrusted.push(e.id);
+                    continue;
+                }
+                toLand.push(e);
+            }
+            const erasedAtSource = new Set();
+            for (const c of plan.custody) {
+                if (c.channel === "delete" && typeof c.id === "string" && rowPresent(c.id))
+                    erasedAtSource.add(c.id);
+            }
+            report.erasedAtSource = [...erasedAtSource].sort();
+            const screened = new Set();
+            for (const finding of screenInboundEntries(toLand, { perFileBytes: MAX_MEMORY_BYTES })) {
+                screened.add(finding.id);
+                report.conflicts.push({ id: finding.id, reason: `inbound screen: ${finding.findings.map((f) => `${f.code} (${f.reason})`).join("; ")}` });
+            }
+            const patches = toLand.filter((e) => !screened.has(e.id)).map((e) => ({ op: "add", id: e.id, entry: e, guard: "absent" }));
+            const patchReport = patches.length > 0 ? await this.applyPatchesLocked(patches, lock.token) : { applied: [], conflicts: [] };
+            for (const c of patchReport.conflicts)
+                report.conflicts.push({ id: c.id, reason: c.reason });
+            const landedIds = new Set();
+            for (const a of patchReport.applied) {
+                if (a.op !== "add")
+                    continue;
+                landedIds.add(a.id);
+                const src = entryById.get(a.id);
+                report.landed.push({ id: a.id, scope: src?.scope ?? "", slug: a.slug ?? src?.slug ?? "" });
+            }
+            const custodyOutcome = this.custodyImportLocked(plan.custody, { bundleHash, sourceStoreId });
+            report.custodyAppended = custodyOutcome.appended;
+            report.custodyWithheld = custodyOutcome.withheld;
+            const eligible = new Set([...landedIds, ...report.alreadyPresent]);
+            const destRows = this.loadLedger();
+            const destKnown = (id) => Object.prototype.hasOwnProperty.call(destRows, id);
+            const withheldIds = new Set();
+            const orphanIds = new Set();
+            const lineageToApply = [];
+            for (const row of plan.lineage) {
+                if (eligible.has(row.entryId))
+                    lineageToApply.push(row);
+                else if (destKnown(row.entryId) || entryById.has(row.entryId))
+                    withheldIds.add(row.entryId);
+                else
+                    orphanIds.add(row.entryId);
+            }
+            const challengesToApply = [];
+            for (const c of plan.challenges) {
+                if (eligible.has(c.entryId))
+                    challengesToApply.push(c);
+                else if (destKnown(c.entryId) || entryById.has(c.entryId))
+                    withheldIds.add(c.entryId);
+                else
+                    orphanIds.add(c.entryId);
+            }
+            report.governanceWithheld = [...withheldIds].sort();
+            report.referentialOrphans = [...orphanIds].sort();
+            report.lineageDivergence = importLineageCommitted(ctl, lineageToApply);
+            this.appendImportChallengesVerified(challengesToApply.map((c) => ({
+                eventId: `imp:${bundleHash}:${c.eventId}`,
+                entryId: c.entryId,
+                reason: c.reason,
+                ...(c.challengedRev !== undefined ? { challengedRev: c.challengedRev } : {}),
+            })));
+            for (const p of [...plan.pollutedSessions].sort((a, b) => (a.sessionId < b.sessionId ? -1 : 1))) {
+                const contributions = lineageContributionsOfSession(ctl, p.sessionId);
+                this.appendImportChallengesVerified(contributions.map((c) => ({
+                    eventId: `imp-sweep:${bundleHash}:pollution:${p.sessionId}:${p.at}:${c.entryId}`,
+                    entryId: c.entryId,
+                    reason: `challenged: the contributing session was marked polluted`,
+                    challengedRev: c.lastRev,
+                })));
+                const outcome = importSessionPollution(ctl, p.sessionId, { at: p.at, reason: p.reason });
+                if (outcome === "divergent")
+                    report.pollutionDivergence.push({ sessionId: p.sessionId, kept: "destination" });
+            }
+            ensureDirExists(join(ctl, IMPORT_RECEIPTS_DIR));
+            if (readControlFileOrAbsent(receiptPath, "bundle import completion receipt") !== undefined) {
+                throw new ControlPlaneCorruptError(`bundle import completion receipt appeared mid-import at ${receiptPath} — refusing to overwrite it (fail-closed)`);
+            }
+            const staged = join(ctl, IMPORT_RECEIPTS_DIR, `.stage-${bundleHash}-${randomUUID().slice(0, 8)}`);
+            const fd = openSync(staged, "wx", 0o600);
+            try {
+                writeAllSync(fd, `${JSON.stringify({ v: 1, bundleHash, at: this.now(), report }, null, 2)}\n`);
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+            try {
+                linkSync(staged, receiptPath);
+                rmSync(staged, { force: true });
+            }
+            catch (err) {
+                try {
+                    rmSync(staged, { force: true });
+                }
+                catch {
+                }
+                if (err.code === "EEXIST") {
+                    throw new ControlPlaneCorruptError(`bundle import completion receipt appeared mid-import at ${receiptPath} — refusing to overwrite it (fail-closed)`);
+                }
+                throw err;
+            }
+            releaseImportLatch(ctl, txnId);
+            return report;
+        }
+        catch (err) {
+            this.ledger = undefined;
+            throw err;
+        }
+        finally {
+            lock.release();
+        }
+    }
     async getConsolidationCursor(scope) {
         const cursors = this.readCursors();
         return cursors[scope];