@sema-agent/core 7.48.0 → 7.49.0

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

@@ -18,7 +18,7 @@ import { landedUndecided, layerDigest, layerObservationLookup, readOnlyLayerCand
 import { markOriginClearanceTombstoned, openOriginClearance, readOriginClearances, settleOriginClearance } from "./origin-clearance.js";
 import { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, canonicalJsonStringify, captureErasureInput, erasureRequestInvalid, erasureSelectHash, scanEntryFiles, } from "./file-backend.js";
 import { assembleMemoryExportBundle, computeMemoryBundleHash, memoryBundleInvalid, } from "./export-bundle.js";
-import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, restoreContainedBaseline, indexLineIsStale, readIndexRevs, writeIndexRevs, bumpScanFuse, scanFuseKey, canonicalize, landingPathOf, landsOutsideStore, storeActRefusal, storeRootMovedRefusal, adoptRootScopeLayout, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, markSessionPolluted, readSessionPollution, fileSessionCaptureRecordStore, recordRetrievedAccount, writeFileNoFollow, withPermissionRemedy, permissionRemedyOf, readRetrievedAccount, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, appendChallengeEvents, appendLineageAudit, rebuildStrictControlPlaneLedger, isStrictControlPlaneLedgerCorrupt, CHALLENGE_LEDGER_MAX_EVENTS, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageAccountOfEntry, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, readProjectionDebts, resolveChallengeEvent, settleProjectionDebts, stageLineagePending, stageProjectionDebts, } from "./layout.js";
+import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, restoreContainedBaseline, indexLineIsStale, readIndexRevs, writeIndexRevs, bumpScanFuse, scanFuseKey, canonicalize, anchorStoreRoot, landingPathOf, landsOutsideStore, storeActRefusal, storeRootMovedRefusal, adoptRootScopeLayout, clearScanFuse, effectiveControlRootOf, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, markSessionPolluted, readSessionPollution, fileSessionCaptureRecordStore, recordRetrievedAccount, writeFileNoFollow, withPermissionRemedy, permissionRemedyOf, readRetrievedAccount, registerScope, registeredScopes, scopeDirFor, appendChallengeEvents, appendLineageAudit, rebuildStrictControlPlaneLedger, isStrictControlPlaneLedgerCorrupt, CHALLENGE_LEDGER_MAX_EVENTS, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageAccountOfEntry, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, readProjectionDebts, resolveChallengeEvent, settleProjectionDebts, stageLineagePending, stageProjectionDebts, } from "./layout.js";
 import { createSessionIncarnationSeat, recalledForAnyIdentity, recalledForIdentity, rememberForIdentity } from "./session-incarnation.js";
 import { scanMemoryFileName, scanMemoryWrite, scanRemediation } from "./scan.js";
 import { writableRootOf } from "./types.js";
@@ -311,7 +311,6 @@ const STALE_LEG_NOTE = "memory session account: this harvest belongs to an earli
 export class MemoryEngine {
     backend;
     memoryDir;
-    mountedRoot;
     controlDir;
     now;
     perScopeBudgetBytes;
@@ -324,7 +323,7 @@ export class MemoryEngine {
     provenance;
     onIncident;
     unsettleableDisclosed = false;
-    backendPinnedRoot;
+    zeroCopy;
     constructor(opts) {
         if (opts.provenance !== undefined && opts.provenance !== "off" && opts.provenance !== "carry") {
             const got = typeof opts.provenance === "string" ? JSON.stringify(opts.provenance) : opts.provenance === null ? "null" : typeof opts.provenance;
@@ -336,13 +335,13 @@ export class MemoryEngine {
         this.backend = opts.backend;
         this.memoryDir = opts.memoryDir;
         const pinned = opts.backend.directoryRoot;
-        if (typeof pinned === "string" && pinned)
-            this.backendPinnedRoot = pinned;
-        const backendControl = opts.backend.controlPlaneRoot;
-        this.controlDir =
-            typeof backendControl === "string" && backendControl
-                ? backendControl
-                : (opts.controlDir ?? (adoptCanonicalKeyedControlDir(resolveMemoryEngineRoot(), opts.memoryDir, opts.onIncident), deriveControlPlaneDir(resolveMemoryEngineRoot(), opts.memoryDir)));
+        if (typeof pinned === "string" && pinned !== "" && landingPathOf(pinned) !== landingPathOf(opts.memoryDir)) {
+            const e = new Error(`MemoryEngineOptions.memoryDir must be the File backend's own directory (the backend is pinned to ${pinned}, memoryDir is ${opts.memoryDir}) — a copy-out projection over a File backend is not supported; pass the backend's directoryRoot as memoryDir.`);
+            e.code = "config.memory_dir_not_backend_root";
+            throw e;
+        }
+        this.zeroCopy = typeof pinned === "string" && pinned !== "";
+        this.controlDir = effectiveControlRootOf(opts.memoryDir, { pinnedBy: opts.backend, controlDir: opts.controlDir, onIncident: opts.onIncident });
         this.now = opts.now ?? Date.now;
         this.perScopeBudgetBytes = opts.perScopeBudgetBytes ?? Number.MAX_SAFE_INTEGER;
         this.perFileBytes = opts.perFileBytes ?? MAX_MEMORY_BYTES;
@@ -416,8 +415,7 @@ export class MemoryEngine {
         return candidates;
     }
     async committedContentUnadopted(id) {
-        const zeroCopy = this.backendPinnedRoot !== undefined && canonicalize(this.backendPinnedRoot) === canonicalize(this.memoryDir);
-        const view = zeroCopy ? undefined : this.backend.restrictedAdoptionView?.({ audit: false });
+        const view = this.zeroCopy ? undefined : this.backend.restrictedAdoptionView?.({ audit: false });
         if (view === undefined)
             return this.committedContentFor(id);
         try {
@@ -429,7 +427,7 @@ export class MemoryEngine {
         }
         return this.backend.readCommittedShadow?.(id) ?? readSafe(join(this.controlDir, "shadow", `${id}.md`));
     }
-    async restoreReadOnlyLayers(candidates, report, selfLeg, root) {
+    async restoreReadOnlyLayers(candidates, report, selfLeg, handle) {
         let writers;
         for (const c of candidates) {
             const text = readSafe(c.path);
@@ -452,7 +450,7 @@ export class MemoryEngine {
                 continue;
             }
             try {
-                this.refuseOutsideStore(root, c.path, "restoring the read-only layer file");
+                this.refuseOutsideStore(c.path, "restoring the read-only layer file", handle);
                 writeFileNoFollow(c.path, committed);
                 report.restored.push(c.relPath);
             }
@@ -754,11 +752,12 @@ export class MemoryEngine {
         const writableRoot = handle.writableRoot;
         if (handle.writeScope === null || writableRoot === null || !existsSync(writableRoot))
             return out;
+        this.assertRootAnchored(handle);
         {
             const indexPath = join(writableRoot, MEMORY_INDEX_FILENAME);
             const baseline = handle.planeBaseline !== undefined ? handle.planeBaseline.index : handle.indexText;
             try {
-                this.refuseOutsideStore(handle.memoryDir, indexPath, "sweeping the index");
+                this.refuseOutsideStore(indexPath, "sweeping the index", handle);
                 const first = existsSync(indexPath) ? readSafe(indexPath) : undefined;
                 if (first !== undefined && first !== baseline) {
                     const onDisk = readSafe(indexPath);
@@ -839,6 +838,11 @@ export class MemoryEngine {
                 }
                 text2 = fresh;
             }
+            const refusedHere = this.storeActRefusedText(canonical, "sweeping a residue file", handle);
+            if (refusedHere !== undefined) {
+                out.failures.push({ path: rel, detail: `${refusedHere} — not swept` });
+                continue;
+            }
             const q = quarantineAndTombstone(canonical, text2, join(this.controlDir, QUARANTINE_DIR), this.now);
             let contained = q.removed;
             if (committed !== undefined) {
@@ -1092,7 +1096,7 @@ export class MemoryEngine {
                 if (kept.length === lines.length)
                     continue;
                 try {
-                    this.refuseOutsideStore(landingPathOf(this.memoryDir), indexPath, "rewriting the index");
+                    this.refuseOutsideStore(indexPath, "rewriting the index");
                     writeFileNoFollow(indexPath, kept.join("\n"));
                 }
                 catch {
@@ -1395,10 +1399,11 @@ export class MemoryEngine {
     }
     async adoptLayoutBeforeMount(writeScope) {
         const adopt = this.backend.adoptRootScopeLayout;
-        const zeroCopy = this.backendPinnedRoot !== undefined && canonicalize(this.backendPinnedRoot) === canonicalize(this.memoryDir);
-        if (adopt !== undefined)
+        if (adopt !== undefined) {
             await adopt.call(this.backend, { ownerCandidate: writeScope, onIncident: this.onIncident });
-        if (adopt === undefined || !zeroCopy)
+            this.assertRootAnchored();
+        }
+        if (adopt === undefined || !this.zeroCopy)
             adoptRootScopeLayout(this.memoryDir, this.controlDir, { ownerCandidate: writeScope, onIncident: this.onIncident, convertSidecars: convertV1SidecarKeys });
     }
     async materialize(scopes, writeScope, opts) {
@@ -1413,13 +1418,11 @@ export class MemoryEngine {
         }
     }
     async materializeCore(scopes, writeScope, opts, legSeat) {
+        this.assertRootAnchored();
         ensureDirExists(this.memoryDir);
-        const physicalRoot = landingPathOf(this.memoryDir);
-        this.mountedRoot ??= physicalRoot;
-        if (physicalRoot !== this.mountedRoot)
-            throw storeRootMovedRefusal("engine", this.memoryDir);
         ensureDirExists(this.controlDir);
         await this.adoptLayoutBeforeMount(writeScope);
+        this.assertRootAnchored();
         const restricted = opts?.adoptionRestricted === true;
         let sessionAccountFailed = false;
         let accountLeg;
@@ -1433,7 +1436,7 @@ export class MemoryEngine {
             scopeDirs.set(writeScope, registerScope(this.memoryDir, this.controlDir, writeScope));
         for (const dir of scopeDirs.values())
             this.censusScopeTree(dir);
-        const layerBaseline = this.backendPinnedRoot !== undefined && canonicalize(this.backendPinnedRoot) === canonicalize(this.memoryDir)
+        const layerBaseline = this.zeroCopy
             ? readOnlyLayerCensus([...scopeDirs].filter(([scope]) => scope !== writeScope).map(([, dir]) => dir))
             : undefined;
         if (layerBaseline !== undefined)
@@ -1509,6 +1512,7 @@ export class MemoryEngine {
                                         const stagingName = `${captureName}.staging`;
                                         const stagingPath = stagingPathBeside(canonical, stagingName);
                                         try {
+                                            this.refuseOutsideStore(canonical, "containing session residue");
                                             renameSync(canonical, stagingPath);
                                             if (readFileSync(stagingPath, "utf8") === text) {
                                                 writeFileNoFollow(canonical, committed);
@@ -1599,10 +1603,11 @@ export class MemoryEngine {
             ...(layerBaseline !== undefined ? { layerBaseline } : {}),
             ...(accountLeg !== undefined ? { accountLeg } : {}),
         };
-        if (handle.writableRoot !== null)
+        if (handle.writableRoot !== null) {
+            this.refuseOutsideStore(join(handle.writableRoot, MEMORY_INDEX_FILENAME), "creating the write home", handle);
             ensureDirExists(handle.writableRoot);
-        const zeroCopy = this.backendPinnedRoot !== undefined && canonicalize(this.backendPinnedRoot) === canonicalize(this.memoryDir);
-        const projectionRoot = zeroCopy ? undefined : this.mountedRoot;
+        }
+        const zeroCopy = this.zeroCopy;
         for (const [scope, dir] of scopeDirs) {
             const scopeEntries = (byScope.get(scope) ?? []).slice();
             scopeEntries.sort((a, b) => (mtimeById.get(b.id) ?? 0) - (mtimeById.get(a.id) ?? 0));
@@ -1612,8 +1617,10 @@ export class MemoryEngine {
                     handle.repoIndexTargets?.set(entry.id, entry.frontmatter.provenance.path);
                     const stale = join(dir, `${entry.slug}.md`);
                     const staleText = readSafe(stale);
-                    if (staleText !== undefined && parseEntryFile(staleText).id === entry.id)
+                    if (staleText !== undefined && parseEntryFile(staleText).id === entry.id) {
+                        this.refuseOutsideStore(stale, "removing a stale projection", handle);
                         rmSync(stale, { force: true });
+                    }
                     continue;
                 }
                 const fullText = serializeEntryFile(entry);
@@ -1624,8 +1631,8 @@ export class MemoryEngine {
                 const { deleted: _stubDrop, ...stubFm } = entry.frontmatter;
                 const text = stub ? serializeEntryFile({ id: entry.id, frontmatter: stubFm, body: STUB_ARCHIVED_LINE }) : fullText;
                 const target = join(dir, `${entry.slug}.md`);
-                if (projectionRoot !== undefined)
-                    this.writeIfChanged(target, text, projectionRoot);
+                if (!zeroCopy)
+                    this.writeIfChanged(target, text, handle);
                 const onDiskRev = stub ? revOfText(text, entry.id) : entry.rev;
                 const path = canonicalize(target);
                 handle.materialized.push({
@@ -1908,6 +1915,14 @@ export class MemoryEngine {
             restored: [],
             warnings: [],
         };
+        try {
+            this.assertRootAnchored(handle);
+        }
+        catch (err) {
+            report.ok = false;
+            report.incident = { kind: "sidecar_corrupt", detail: `memory control plane refused: ${this.writeFailureText(err)}` };
+            return report;
+        }
         const writeScope = handle.writeScope;
         const captureRead = opts?.sessionId !== undefined ? await this.sessionCaptureOptOutOrFault(opts.sessionId) : { fault: false };
         const captureOptOut = captureRead.record;
@@ -1962,6 +1977,7 @@ export class MemoryEngine {
             return report;
         }
         try {
+            this.assertRootAnchored(handle);
             this.backend.checkControlPlane?.();
         }
         catch (err) {
@@ -1977,6 +1993,7 @@ export class MemoryEngine {
         await this.settleUndecidedObservations(handle, report, landedUndecided(observed));
         try {
             if (carry) {
+                this.assertRootAnchored(handle);
                 reconcileHolds(this.controlDir, { homeOf: (scope) => scopeDirFor(this.memoryDir, this.controlDir, scope), now: this.now });
                 const newlyExpired = expireOverdueSettlements(this.controlDir, { timeoutMs: this.holdSettleTimeoutMs, now: this.now });
                 if (newlyExpired.length > 0) {
@@ -2077,6 +2094,11 @@ export class MemoryEngine {
                 report.rejections.push({ path: rel, code: "outside_root", reason: "file resolves outside the writable memory root (containment gate, fail-closed)" });
                 return;
             }
+            const refusedHere = this.storeActRefusedText(f.canonical, "containing a withheld file", handle);
+            if (refusedHere !== undefined) {
+                report.rejections.push({ path: rel, code: "outside_root", reason: `containment refused (fail-closed): ${refusedHere}` });
+                return;
+            }
             const baseId = handle.baseIds.get(f.canonical);
             if (baseId !== undefined && !pollutedStubs.has(f.canonical) && revOfText(f.text, baseId) === handle.baseRevs.get(f.canonical))
                 return;
@@ -2106,7 +2128,10 @@ export class MemoryEngine {
             if (priorId !== undefined) {
                 const committed = await this.committedContentFor(priorId);
                 if (committed !== undefined) {
-                    const put = restoreContainedBaseline(f.canonical, committed, q.leftOnPlane);
+                    const refusedRestore = this.storeActRefusedText(f.canonical, "restoring a contained file's baseline", handle);
+                    if (refusedRestore !== undefined)
+                        report.warnings.push(`${rel}: the committed baseline was not restored — ${refusedRestore}`);
+                    const put = refusedRestore === undefined ? restoreContainedBaseline(f.canonical, committed, q.leftOnPlane) : undefined;
                     if (put === "written") {
                         report.restored.push(rel);
                         contained = true;
@@ -2151,6 +2176,7 @@ export class MemoryEngine {
             catch {
             }
             try {
+                this.refuseOutsideStore(pollutedIndexPath, "restoring the index", handle);
                 writeFileNoFollow(pollutedIndexPath, handle.indexText);
                 report.warnings.push(`memory index restored to its pre-session state — this session's index additions were not retained (session polluted; ${indexCaptureLanded ? "the removed text was captured to quarantine" : "the quarantine capture did NOT land — the removed text is gone"})`);
                 return true;
@@ -2186,7 +2212,7 @@ export class MemoryEngine {
                 signalContainment((c) => (c.indexRolledBack = true));
             report.warnings.push(`memory harvest refused by an incident while this session is marked externally exposed — no entries were committed; instruction-form files were withheld and the derived index rolled back: ${inlineUntrusted(pollutedReason, 200)}`);
         };
-        await this.restoreReadOnlyLayers(readOnlyRestorable, report, handle.accountLeg, handle.memoryDir);
+        await this.restoreReadOnlyLayers(readOnlyRestorable, report, handle.accountLeg, handle);
         const missingWritable = writable.filter((m) => !recordByPath.has(m.path) && !existsSync(m.path) && !presentIds.has(m.id));
         report.missing.push(...missingWritable.map((m) => m.relPath));
         if (writable.length > 0 && missingWritable.length / writable.length > MASS_DELETION_FUSE_RATIO) {
@@ -2213,7 +2239,7 @@ export class MemoryEngine {
             if (content === undefined)
                 continue;
             try {
-                this.refuseOutsideStore(handle.memoryDir, m.path, "restoring a memory file");
+                this.refuseOutsideStore(m.path, "restoring a memory file", handle);
                 mkdirSync(dirname(m.path), { recursive: true });
                 writeFileNoFollow(m.path, content);
                 report.restored.push(m.relPath);
@@ -2281,7 +2307,7 @@ export class MemoryEngine {
             if (fastBaseId !== undefined && !stubByPath.has(f.canonical) && revOfText(f.text, fastBaseId) === revByBasePath.get(f.canonical)) {
                 const fastDebt = projectionDebts.get(debtSeat(writeScope, homeRel(writableRoot, f.canonical)));
                 if (fastDebt !== undefined && fastDebt.entryId === fastBaseId)
-                    await this.repairProjectionSeat(seatOf(f.canonical), f.canonical, fastBaseId, debtClears, report.warnings);
+                    await this.repairProjectionSeat(seatOf(f.canonical), f.canonical, fastBaseId, debtClears, report.warnings, handle);
                 continue;
             }
             processed++;
@@ -2307,13 +2333,15 @@ export class MemoryEngine {
             scanFindings.push(...scanMemoryWrite(f.text));
             const finding = scanFindings[0];
             if (finding !== undefined) {
-                const q = quarantineAndTombstone(f.canonical, f.text, join(this.controlDir, QUARANTINE_DIR), this.now);
+                const refusedHere = this.storeActRefusedText(f.canonical, "quarantining a rejected file", handle);
+                const q = refusedHere === undefined ? quarantineAndTombstone(f.canonical, f.text, join(this.controlDir, QUARANTINE_DIR), this.now) : { removed: false, leftOnPlane: f.text, detail: refusedHere };
                 let contained = q.removed;
                 const priorId = idByBasePath.get(f.canonical);
                 if (priorId !== undefined) {
                     const committed = await this.committedContentFor(priorId);
                     if (committed !== undefined) {
                         try {
+                            this.refuseOutsideStore(f.canonical, "restoring a rejected file's committed content", handle);
                             writeFileNoFollow(f.canonical, committed);
                             report.restored.push(rel);
                             contained = true;
@@ -2415,7 +2443,8 @@ export class MemoryEngine {
                 continue;
             }
             if (instructionForm && sessionPending && lineageSessionId !== undefined) {
-                const held = openInstructionHold(this.controlDir, {
+                const holdRefused = this.storeActRefusedText(f.canonical, "holding an instruction-form file", handle);
+                const held = holdRefused !== undefined ? { ok: false, reason: holdRefused } : openInstructionHold(this.controlDir, {
                     sessionId: lineageSessionId,
                     rel: homeRel(writableRoot, f.canonical),
                     absPath: f.canonical,
@@ -2438,6 +2467,7 @@ export class MemoryEngine {
                         const committed = await this.committedContentFor(committedIdHere);
                         if (committed !== undefined) {
                             try {
+                                this.refuseOutsideStore(f.canonical, "restoring a held entry's committed content", handle);
                                 writeFileNoFollow(f.canonical, committed);
                                 report.restored.push(rel);
                             }
@@ -2489,7 +2519,7 @@ export class MemoryEngine {
                 if (revOfText(f.text, id) === revByBasePath.get(f.canonical)) {
                     const seatDebt = projectionDebts.get(debtSeat(writeScope, homeRel(writableRoot, f.canonical)));
                     if (seatDebt !== undefined && seatDebt.entryId === id)
-                        await this.repairProjectionSeat(seatOf(f.canonical), f.canonical, id, debtClears, report.warnings);
+                        await this.repairProjectionSeat(seatOf(f.canonical), f.canonical, id, debtClears, report.warnings, handle);
                     continue;
                 }
                 pendingProjections.push({ path: f.canonical, entry, needed: minted || parsed.id !== id || needsCompletion(parsed, fm), ...(debtReconciled ? { idCompletion: true } : {}) });
@@ -2507,6 +2537,7 @@ export class MemoryEngine {
                 reboundId = parsed.id;
                 const idless = serializeEntryFile({ id: "", frontmatter: fm, body: parsed.body }).replace(/^id:[ \t]*$\r?\n/m, "");
                 try {
+                    this.refuseOutsideStore(f.canonical, "stripping a copied id", handle);
                     writeFileNoFollow(f.canonical, idless);
                 }
                 catch (err) {
@@ -2526,6 +2557,7 @@ export class MemoryEngine {
             if (fm.origin !== undefined && parsed.id !== undefined && reboundId === undefined) {
                 const idless = serializeEntryFile({ id: "", frontmatter: fm, body: parsed.body }).replace(/^id:[ \t]*$\r?\n/m, "");
                 try {
+                    this.refuseOutsideStore(f.canonical, "stripping a model-written id", handle);
                     writeFileNoFollow(f.canonical, idless);
                 }
                 catch (err) {
@@ -2648,6 +2680,7 @@ export class MemoryEngine {
                                 }
                                 const idless = serializeEntryFile({ id: "", frontmatter: p.entry.frontmatter, body: p.entry.body }).replace(/^id:[ \t]*$\r?\n/m, "");
                                 try {
+                                    this.refuseOutsideStore(flipRec.canonical, "re-minting a marked commit's id", handle);
                                     writeFileNoFollow(flipRec.canonical, idless);
                                 }
                                 catch (err) {
@@ -2760,7 +2793,7 @@ export class MemoryEngine {
                     }
                 }
                 try {
-                    patchReport = await this.backend.applyPatches(patches);
+                    patchReport = await this.backend.applyPatches(patches, { anchoredRoot: handle.memoryDir });
                 }
                 catch (err) {
                     if (lineageArmed) {
@@ -2827,14 +2860,14 @@ export class MemoryEngine {
             }
         }
         const appliedIds = new Set(patchReport.applied.filter((a) => a.op !== "delete").map((a) => a.id));
-        const planeAfterFailedWriteBack = this.backendPinnedRoot !== undefined && canonicalize(this.backendPinnedRoot) === canonicalize(this.memoryDir)
+        const planeAfterFailedWriteBack = this.zeroCopy
             ? "this plane is the store itself: the next read adopts them as an out-of-session edit unless the committed copy is put back first"
             : "the next materialize re-projects the committed copy over them";
         for (const p of pendingProjections) {
             const pRel = relative(handle.memoryDir, p.path);
             const pSeat = seatOf(p.path);
             if (appliedIds.has(p.entry.id)) {
-                const writeBackFailure = this.writeBackProjection(p.path, p.entry, p.needed);
+                const writeBackFailure = this.writeBackProjection(p.path, p.entry, p.needed, handle);
                 if (p.idCompletion !== true) {
                     if (writeBackFailure !== undefined)
                         report.warnings.push(`${pRel}: the entry committed but its projection write-back FAILED — the plane keeps this session's bytes (${planeAfterFailedWriteBack}): ${writeBackFailure}`);
@@ -2855,6 +2888,7 @@ export class MemoryEngine {
             let planeHoldsCommitted = false;
             if (committed !== undefined && readNoFollowSafe(p.path) !== committed) {
                 try {
+                    this.refuseOutsideStore(p.path, "writing a CAS winner's committed copy back", handle);
                     writeFileNoFollow(p.path, committed);
                     planeHoldsCommitted = true;
                 }
@@ -3069,7 +3103,7 @@ export class MemoryEngine {
         }
         let patchReport;
         try {
-            patchReport = await this.backend.applyPatches([patch]);
+            patchReport = await this.backend.applyPatches([patch], { anchoredRoot: handle.memoryDir });
         }
         catch (err) {
             try {
@@ -4832,7 +4866,7 @@ export class MemoryEngine {
         if (opts.write) {
             let wrote = false;
             try {
-                this.refuseOutsideStore(handle.memoryDir, indexPath, "writing the index");
+                this.refuseOutsideStore(indexPath, "writing the index", handle);
                 mkdirSync(dirname(indexPath), { recursive: true });
                 if (readNoFollowSafe(indexPath) !== text)
                     writeFileNoFollow(indexPath, text);
@@ -4852,8 +4886,7 @@ export class MemoryEngine {
     }
     async committedContentOrFault(id) {
         let fault = false;
-        const zeroCopy = this.backendPinnedRoot !== undefined && canonicalize(this.backendPinnedRoot) === canonicalize(this.memoryDir);
-        if (!zeroCopy) {
+        if (!this.zeroCopy) {
             try {
                 const [entry] = await this.backend.getByIds([id]);
                 if (entry !== undefined && entry.id === id)
@@ -4872,8 +4905,7 @@ export class MemoryEngine {
         return { fault };
     }
     async committedFrontmatterFor(id) {
-        const zeroCopy = this.backendPinnedRoot !== undefined && canonicalize(this.backendPinnedRoot) === canonicalize(this.memoryDir);
-        if (!zeroCopy) {
+        if (!this.zeroCopy) {
             const face = this.backend.retrievalView?.() ?? this.backend;
             try {
                 const [entry] = await face.getByIds([id]);
@@ -4923,7 +4955,7 @@ export class MemoryEngine {
         }
         let cleared = false;
         try {
-            this.refuseOutsideStore(handle.memoryDir, indexPath, "clearing the index");
+            this.refuseOutsideStore(indexPath, "clearing the index", handle);
             writeFileNoFollow(indexPath, "");
             cleared = true;
         }
@@ -4943,25 +4975,41 @@ export class MemoryEngine {
             contained: cleared,
         };
     }
-    refuseOutsideStore(root, path, act) {
-        if (landsOutsideStore(root, path))
+    refuseOutsideStore(path, act, handle) {
+        if (landsOutsideStore(this.assertRootAnchored(handle), path))
             throw storeActRefusal(act, path);
     }
-    writeIfChanged(target, text, root) {
-        this.refuseOutsideStore(root, target, "the projection write");
+    storeActRefusedText(path, act, handle) {
+        try {
+            this.refuseOutsideStore(path, act, handle);
+            return undefined;
+        }
+        catch (err) {
+            return this.writeFailureText(err);
+        }
+    }
+    assertRootAnchored(handle) {
+        const root = anchorStoreRoot(this.memoryDir, this.controlDir, { onIncident: this.onIncident, now: this.now });
+        if (handle !== undefined && handle.memoryDir !== root)
+            throw storeRootMovedRefusal(this.memoryDir, { controlDir: this.controlDir, recorded: root, now: handle.memoryDir });
+        return root;
+    }
+    writeIfChanged(target, text, handle) {
+        this.refuseOutsideStore(target, "the projection write", handle);
         const current = readNoFollowSafe(target);
         if (current === text)
             return;
         mkdirSync(dirname(target), { recursive: true });
         writeFileNoFollow(target, text);
     }
-    writeBackProjection(path, entry, needed) {
+    writeBackProjection(path, entry, needed, handle) {
         if (!needed)
             return undefined;
         const text = serializeEntryFile(entry);
         if (readNoFollowSafe(path) === text)
             return undefined;
         try {
+            this.refuseOutsideStore(path, "the projection write-back", handle);
             writeFileNoFollow(path, text);
             return undefined;
         }
@@ -4969,12 +5017,13 @@ export class MemoryEngine {
             return this.writeFailureText(err);
         }
     }
-    async repairProjectionSeat(seat, canonical, entryId, debtClears, warnings) {
+    async repairProjectionSeat(seat, canonical, entryId, debtClears, warnings, handle) {
         const committed = await this.committedContentFor(entryId);
         if (committed === undefined)
             return;
         if (readNoFollowSafe(canonical) !== committed) {
             try {
+                this.refuseOutsideStore(canonical, "repairing a projection seat", handle);
                 writeFileNoFollow(canonical, committed);
             }
             catch (err) {
@@ -4985,8 +5034,7 @@ export class MemoryEngine {
         debtClears.push({ ...seat, entryId });
     }
     async debtCommittedProjection(entryId) {
-        const zeroCopy = this.backendPinnedRoot !== undefined && canonicalize(this.backendPinnedRoot) === canonicalize(this.memoryDir);
-        if (zeroCopy)
+        if (this.zeroCopy)
             return { state: "stale" };
         const face = this.backend.retrievalView?.() ?? this.backend;
         try {

package/dist/core/memory-engine/file-backend.d.ts

@@ -1,4 +1,4 @@
-import { scopeDirName, type ChallengeEvent, type MemoryPartitionIncidentSink } from "./layout.js";
+import { scopeDirName, type TxnLockTimings, type ChallengeEvent, type MemoryPartitionIncidentSink } from "./layout.js";
 import type { MemoryBundleImportPlan, MemoryImportReport } from "./export-bundle.js";
 import type { HarvestRejection, MemoryBackend, MemoryEntry, MemoryEntryHeader, MemoryScopeEnumeration, NotePatch, PatchReport, ScoredMemoryEntry } from "./types.js";
 export { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, scanEntryFiles, type ScannedEntryFile } from "./entry-scan.js";
@@ -312,12 +312,6 @@ export interface MemoryExportSnapshot {
     quarantined: string[];
     quarantineOpaque: number;
 }
-/** Test hook (证伪式复审 L3): small constants so the crash-window leg does not really wait 15-30s. */
-interface TxnLockTimings {
-    staleMs?: number;
-    waitMs?: number;
-    stealGraceMs?: number;
-}
 /** Construction options for {@link FileMemoryEngineBackend}. */
 export interface FileMemoryEngineBackendOptions {
     /** ⚠️ 分家坑(service 报告 2026-07-09):不显式传时,控制平面按无参 `resolveMemoryEngineRoot()`
@@ -353,8 +347,6 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      *  NEVER under {@link directoryRoot}, always on the config-root side even for an in-repo memory dir.
      *  The engine picks this up (like `directoryRoot`) so both sides share ONE control plane. */
     readonly controlPlaneRoot: string;
-    /** {@link directoryRoot}'s physical form at construction — the root every act on a store path is judged against. */
-    private readonly physicalRoot;
     /** Injected clock (opus 1.258 LOW: match the engine's `this.now` determinism discipline). */
     private readonly now;
     /** The construction-time incident sink (partition adoption, layout adoption on the standalone faces). */
@@ -687,13 +679,16 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      * first op that would land outside the store, naming the op (its path on `detail.path`). Runs over a
      * whole batch before its commit marker (no journal is written; a caller that staged files removes
      * them) and per op at the act itself; past the marker a refusal keeps the journal, which replays
-     * once the path resolves inside the store again.
+     * once the path resolves inside the store again. The root judged against is the anchored one, read at
+     * this call ({@link assertRootAnchored}); with `anchoredRoot` (the caller's session root) it must be that one.
      */
     private refuseEscapingTargets;
-    /** At the head of every face (both recovery legs, the lock-free faces' layout seat, the adoption face):
-     *  the store root still resolves to the directory this backend opened. A root re-pointed since would
-     *  carry every read, adoption, sweep and restore — not only the journal's acts — into another directory. */
-    private assertRootIntact;
+    /** At construction and at the head of every face (both recovery legs, the lock-free faces' layout seat,
+     *  the adoption face): the store root against its anchor ({@link anchorStoreRoot}); answers the anchored
+     *  physical root. A root re-pointed since would carry every read, adoption, sweep and restore — not only
+     *  the journal's acts — into another directory. Read every time, never kept. With `expected` (a caller
+     *  session's root) the anchor must be that root too — the engine's handle comparison, at this act. */
+    private assertRootAnchored;
     /** Remove orphaned `.stage-*` files (a crash BEFORE the journal rename = clean rollback: nothing
      *  was committed, the staged tmps are litter). Dotfiles are invisible to entry scans regardless. */
     private sweepStagedFiles;
@@ -978,23 +973,11 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      *  5. EXECUTE: atomic renames / deletes / shadow updates.
      *  6. Persist the ledger (atomic, fail-closed) and drop the journal.
      */
-    applyPatches(patches: readonly NotePatch[]): Promise<PatchReport>;
+    applyPatches(patches: readonly NotePatch[], opts?: {
+        readonly anchoredRoot?: string;
+    }): Promise<PatchReport>;
     private txnLockDir;
-    /**
-     * 证伪式复审 L1/L2/L3 — the mkdir mutex, hardened (same shape as layout.ts' acquireSidecarLock, but
-     * fail-closed timings and an async wait):
-     *  - L2: every acquisition writes an OWNER TOKEN (`<lock>/owner`, crypto-random — never a
-     *    timestamp) immediately after mkdir. Release only removes the lock while the token is still
-     *    ours; {@link assertTxnLockOwnership} re-verifies it at the commit point.
-     *  - L1: the stale steal is SINGLE-WINNER — atomic rename of the stale lock dir to a unique
-     *    tombstone (exactly one racer's rename succeeds; losers ENOENT back into the wait loop), then
-     *    the winner removes the tombstone and re-acquires through a NORMAL mkdir. Never a bare
-     *    rmSync+mkdir (two same-window stealers would force-rm each other's FRESH lock = double hold).
-     *  - L2 (steal side): only a lock that is BOTH past its stale line AND carries an owner token is
-     *    stealable (a tokenless dir is a mid-acquisition, not a crashed holder).
-     *  - L3: the wait deadline is `max(waitMs, observed lock's stale line + grace)` — a holder that
-     *    crashed with `remaining stale > waitMs` no longer strands every waiter in an all-throw window.
-     */
+    /** The store's transaction lock, waited for ({@link acquireStoreTxnLock} — the one mkdir mutex, shared with a re-anchor of the root). */
     private acquireTxnLock;
     /** 证伪式复审 L2 — 提交点归属复验: called immediately before the JOURNAL write (the persistent commit
      *  point). A holder that stalled past the stale deadline (slow disk / GC pause / long txn) and was