@sema-agent/core 5.26.0 → 5.28.0

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

@@ -128,6 +128,15 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
     /** The names of sibling scope subdirs to exclude when scanning the ROOT scope's own nested content. */
     private excludedSubdirNames;
     private scopeDir;
+    /** B2/C-F9 — contain one inbound-gate REJECT, shared by the adopting read (`readScope` sync) and
+     *  the adoption-restricted committed view (`readScopeCommitted`) so the two doors can never drift:
+     *  report the finding, capture the SCANNED bytes into control-plane quarantine (never a path
+     *  re-read — TOCTOU), restore the committed shadow over the suspect where one exists (the write
+     *  lands by `rename`, which REPLACES a link at the final component instead of traversing it —
+     *  pinned by test), and escalate any deviation as a report-visible `quarantine_failed`. Returns
+     *  the shadow text that now backs the entry (undefined ⇔ never committed / shadow-less legacy —
+     *  each caller decides what leaving the set means on its channel). */
+    private containInboundReject;
     /** B2 inbound gate for content that did NOT come through applyPatches (git pull / hand edits /
      *  a hand-seeded file): secret + cap + structure. Returns the rejection, or undefined (clean). */
     private inboundGate;
@@ -138,12 +147,49 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      *  `sync` (read-side callers) adopts a committed file's CURRENT disk rev into the committed-rev
      *  ledger ONLY through the inbound gate (B2: out-of-session edits, e.g. git-pull, are scanned;
      *  a reject is moved to control-plane quarantine and the committed shadow content is restored to
-     *  disk). The applyPatches lookup passes false (the ledger must keep the baseline for CAS). */
+     *  disk). The applyPatches lookup passes false (the ledger must keep the baseline for CAS).
+     *
+     *  Ledger-write discipline: the sync=true adoption path WRITES `revs.json`, and that write is
+     *  wholesale (atomic replace) — unserialized against applyPatches' transaction it is a
+     *  lost update (the later writer drops every row the earlier one added). sync=true is therefore
+     *  reachable ONLY through {@link readScopeAdopting}: `probeOnly` runs the scan with NO adoption
+     *  side effects and returns undefined at the FIRST divergent entry (adoption required — the
+     *  caller re-runs the scan under the txn mutex against a freshly reloaded ledger); a completed
+     *  probe pass returns the entries (nothing to adopt, no lock ever taken). */
     private readScope;
+    /**
+     * The adopting read: {@link readScope} sync=true with its ledger write serialized behind the
+     * SAME cross-process txn mutex applyPatches holds (acquisition/steal/timeout semantics shared,
+     * never duplicated). Without it, an adoption landing beside a sibling process's commit is a
+     * lost update: both read the ledger, both write it wholesale, the later atomic write drops the
+     * earlier writer's rows (the entry file stays on disk but the ledger no longer knows it).
+     *  - PROBE first (no lock): disk agreeing with the ledger is the common case, and that pass writes
+     *    no LEDGER row — the read stays lock-free and never contends with a writer over the ledger.
+     *    (Precision, merged-code scan: the non-divergent branch may still BACKFILL a missing shadow
+     *    file for a committed entry, an unserialized control-plane write with a narrow pre-existing
+     *    last-writer window against a sibling's commit — see the shadow-backfill site below; that
+     *    window predates this probe and is the same one the v2 single-lock design closes.)
+     *  - Divergence ⇒ acquire the mutex, finish any interrupted transaction (the steal-safety
+     *    contract: a stolen stale lock is safe BECAUSE recovery runs inside the lock), RELOAD the
+     *    ledger from disk (the probe's cached view is exactly the stale baseline that loses
+     *    updates), then re-run the scan with adoption and save inside the lock. The save re-verifies
+     *    lock OWNERSHIP first (a holder stalled past the stale deadline was stolen from — its
+     *    snapshot is behind the stealer's commit and must abort, exactly like the applyPatches
+     *    journal write).
+     *  - A lock that cannot be acquired throws (same loud arm as the write path): an adoption that
+     *    cannot be serialized must surface, never silently skip the gate or serve stale state as
+     *    adopted.
+     * No self-deadlock: nothing under the lock re-enters acquireTxnLock — the scan's quarantine /
+     * shadow / announcement writes use their own per-file sidecar locks (whose holders never take
+     * the txn mutex), and applyPatchesLocked only issues sync=false reads. The two UNLOCKED
+     * recovery observers (constructor / checkControlPlane) are unaffected: they already stand down
+     * while a live holder exists ({@link txnInFlight}), which now covers adoption holds too.
+     */
+    private readScopeAdopting;
     listHeaders(scopes: readonly string[]): Promise<MemoryEntryHeader[]>;
-    private listHeadersWith;
+    private listHeadersFrom;
     getByIds(ids: readonly string[]): Promise<MemoryEntry[]>;
-    private getByIdsWith;
+    private getByIdsFrom;
     /**
      * design/178 §3 (ruled 2026-08-08) — a SIDE-EFFECT-FREE projection of this backend for the session's
      * RETRIEVAL face (`memory_search` / `memory_get`).
@@ -162,11 +208,105 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      * WRITES ARE REFUSED, loudly — a view handed to a write path is a defect, not a fallback.
      */
     retrievalView(): MemoryBackend;
+    /** Dedup keys for divergence findings the restricted view already recorded on THIS instance: one
+     *  materialize reads a scope several times (listHeaders, then getByIds per scope), and a
+     *  checkpoint-cadence harvest re-audits the same still-pending state — without the key, one
+     *  untouched divergence would mint a finding per read. Per-process on purpose (no durable state to
+     *  lifecycle: a cross-process resume re-discloses once, which is the desired "still pending"
+     *  notice); a divergence whose bytes CHANGE mints a new key and is reported again. */
+    private restrictedFindingKeys;
+    private recordRestrictedFinding;
+    /** Id-less audit state for an adoption-restricted session's WRITE scope. Armed only by the
+     *  audited mount, which carries the caller's explicit session verdict together with the session's
+     *  write scope — never inferred from plane structure (a writeScope-null layering has no write
+     *  scope and is never given this surface: id-less files there are ordinary working files or
+     *  external drops). The baseline is the set of id-less rel paths already under the scope at the
+     *  first audited read after the mount (= materialize time): a pre-existing id-less file cannot be
+     *  attributed to this session and stays unflagged, while a session under the restriction verdict
+     *  has no sanctioned write channel into the store — so an id-less file that APPEARS after the
+     *  baseline arrived out of band by construction and is worth naming. Per-process like the finding
+     *  keys; when restricted sessions interleave on one instance the later mount re-baselines, which
+     *  degrades toward silence, never toward a false alarm. */
+    private restrictedIdlessScope?;
+    private restrictedIdlessBaseline?;
+    /**
+     * The ADOPTION-RESTRICTED read of one scope: serve the COMMITTED account (ledger + control-plane
+     * shadow) and never advance it. This is the tamper boundary for a session with no write intent:
+     * the ordinary `readScope(sync=true)` ADOPTS disk divergence as the new committed baseline
+     * regardless of session intent, so a byte landed by a side channel (e.g. a shell write under a
+     * session whose persistence is declared unavailable, or into a read-only layering) would be
+     * committed by the very session that was told it cannot persist — its own checkpoint-resume
+     * materialize included. Here instead:
+     *  - disk rev == committed rev ⇒ served as-is (it IS the committed content);
+     *  - divergence whose bytes equal the committed SHADOW ⇒ served as-is: the shadow is written at
+     *    the applyPatches commit point, so matching it is transactional proof that a concurrent
+     *    writable session committed this state and only this call's ledger snapshot raced it —
+     *    never treated as tampering;
+     *  - other divergence of a shadow-backed entry ⇒ the SHADOW (committed content) is served; the
+     *    divergent disk bytes stay in place UNLESS they fail the inbound gate (the existing
+     *    quarantine door, unchanged under restriction). Scan-clean divergence is never quarantined,
+     *    overwritten, or adopted — it stays on disk as deferred external state a later unrestricted
+     *    session adjudicates normally;
+     *  - a divergent entry with NO shadow (shadow-less legacy), and a never-committed id-bearing
+     *    file, have no committed content to serve ⇒ WITHHELD with a loud finding, never served from
+     *    disk, never adopted.
+     * The ledger is reloaded from disk on every call (a stale cache would misread a concurrent commit
+     * as divergence) and NEVER written here; the only writes this path may perform are the
+     * gate-failing containment above and a shadow backfill for a rev-matching entry (recording
+     * committed content — the account itself does not move).
+     *
+     * `audit` picks the mount: true = the engine's materialize/harvest boundary (findings recorded,
+     * gate-failing divergence contained); false = the retrieval-tool face (a PURE committed read —
+     * no findings, no containment, no writes: a model lookup must be side-effect-free).
+     */
+    private readScopeCommitted;
+    /** Does `id` have a projection file anywhere in the store OTHER than `excludeAbsPath`? Returns
+     *  that projection's rel path, or undefined. Early-exits on the first hit; only consulted on the
+     *  rare divergent-with-shadow path (the scope-binding guard above), never on clean reads. */
+    private idProjectionElsewhere;
+    /**
+     * The ADOPTION-RESTRICTED projection of this backend (see {@link readScopeCommitted}) — what a
+     * session with no write intent materializes and retrieves through. The CALLER decides restriction
+     * (an explicit verdict: a read-only layering, or persistence declared unavailable) and mounts this
+     * view; the backend never guesses a session's intent from its own state.
+     *  - `audit: true` (the engine's materialize/harvest mount): divergence findings are recorded for
+     *    the harvest report + announcement queue, and gate-FAILING divergence is contained by the
+     *    existing quarantine door; `writeScope` (when the session has one) additionally arms the
+     *    id-less baseline for that scope — see {@link auditRestrictedDivergence};
+     *  - `audit: false` (the retrieval-tool mount): a pure committed-view read — no findings, no
+     *    containment, no writes, no baseline.
+     * WRITES ARE REFUSED loudly — same posture as {@link retrievalView}.
+     */
+    restrictedAdoptionView(opts?: {
+        audit?: boolean;
+        writeScope?: string | null;
+    }): MemoryBackend;
+    /**
+     * The harvest-boundary divergence sweep for an adoption-restricted session (the engine's
+     * zero-admission harvest arm calls this BEFORE draining findings): re-run the committed-view audit
+     * over the session's scopes — bytes landed AFTER materialize (a mid-session shell write) are
+     * detected here, at the very boundary where an unrestricted harvest would have admitted them —
+     * then check the committed account for entries MISSING from disk entirely (an unattributed delete
+     * is divergence too). Ledger rows carry no scope, so presence is judged across every registered
+     * scope, the same resolution `getByIds` uses; a rename or cross-scope move therefore never reads
+     * as missing. Non-destructive throughout: nothing is restored, forgotten, or adopted here.
+     *
+     * `opts.idlessWriteScope` is the CALLER's per-call session verdict (same posture as the mount:
+     * the backend never guesses): when the audited session HAS a write scope, id-less files under it
+     * that were not in the mount-time baseline are named too — the session has no sanctioned write
+     * channel into the store, so a new arrival is out of band by construction. Left out (a
+     * writeScope-null layering, or a caller that never mounted the audit), the sweep is exactly the
+     * id-bearing audit above; a scope mismatch with the armed mount likewise degrades to silence
+     * rather than judging against a foreign baseline.
+     */
+    auditRestrictedDivergence(scopes: readonly string[], opts?: {
+        idlessWriteScope?: string;
+    }): void;
     /** Lexical floor (design/138 §2.1): `1 - Jaccard` distance over name+description+body, ascending. */
     search(query: string, scopes: readonly string[], opts?: {
         limit?: number;
     }): Promise<ScoredMemoryEntry[]>;
-    private searchWith;
+    private searchFrom;
     /**
      * H4 — the entry transaction, staged and journaled:
      *  1. RELOAD the ledger from disk (验收 M2: a concurrently-committed transaction from another

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

@@ -1,5 +1,5 @@
 import { lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, openSync, fsyncSync, closeSync } from "node:fs";
-import { randomUUID } from "node:crypto";
+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";
@@ -229,6 +229,29 @@ export class FileMemoryEngineBackend {
     scopeDir(scope) {
         return registerScope(this.directoryRoot, this.controlPlaneRoot, scope);
     }
+    containInboundReject(finding, absPath, text, entryId, committed) {
+        this.inboundFindings.push(finding);
+        const q = quarantineAndTombstone(absPath, text, join(this.controlPlaneRoot, QUARANTINE_DIR), this.now);
+        const shadowText = committed !== undefined ? this.readCommittedShadow(entryId) : undefined;
+        let restoredShadow = false;
+        if (shadowText !== undefined) {
+            try {
+                atomicWriteFileSync(absPath, shadowText);
+                restoredShadow = true;
+            }
+            catch {
+            }
+        }
+        if (q.detail !== undefined || (!q.removed && !restoredShadow)) {
+            const contained = q.removed || restoredShadow;
+            this.inboundFindings.push({
+                path: finding.path,
+                code: "quarantine_failed",
+                reason: `quarantine escalation: ${q.detail ?? "suspect copy not captured"}${contained ? "" : " — rejected content may still be on the model-visible plane"}`,
+            });
+        }
+        return shadowText;
+    }
     inboundGate(relPath, text) {
         const nameFinding = scanMemoryFileName(relPath);
         if (nameFinding !== undefined)
@@ -240,7 +263,7 @@ export class FileMemoryEngineBackend {
         }
         return undefined;
     }
-    readScope(scope, sync = true) {
+    readScope(scope, sync, probeOnly, lockToken) {
         if (!sync && this.batchScan !== undefined) {
             const memo = this.batchScan.get(scope);
             if (memo !== undefined)
@@ -270,6 +293,10 @@ export class FileMemoryEngineBackend {
             if (ledger) {
                 const committed = ledger[entry.id];
                 if (committed !== entry.rev) {
+                    if (probeOnly)
+                        return undefined;
+                    if (lockToken !== undefined)
+                        this.assertTxnLockOwnership(lockToken);
                     const relPath = relative(this.directoryRoot, f.path);
                     let finding = this.inboundGate(relPath, text);
                     if (finding === undefined && committed !== undefined) {
@@ -288,27 +315,7 @@ export class FileMemoryEngineBackend {
                         }
                     }
                     if (finding) {
-                        this.inboundFindings.push(finding);
-                        const q = quarantineAndTombstone(f.path, text, join(this.controlPlaneRoot, QUARANTINE_DIR), this.now);
-                        const shadowText = committed !== undefined ? this.readCommittedShadow(entry.id) : undefined;
-                        let restoredShadow = false;
-                        if (shadowText !== undefined) {
-                            try {
-                                atomicWriteFileSync(f.path, shadowText);
-                                restoredShadow = true;
-                            }
-                            catch {
-                            }
-                            entry = entryFromFile(shadowText, entry.id, f.slug, scope);
-                        }
-                        if (q.detail !== undefined || (!q.removed && !restoredShadow)) {
-                            const contained = q.removed || restoredShadow;
-                            this.inboundFindings.push({
-                                path: finding.path,
-                                code: "quarantine_failed",
-                                reason: `quarantine escalation: ${q.detail ?? "suspect copy not captured"}${contained ? "" : " — rejected content may still be on the model-visible plane"}`,
-                            });
-                        }
+                        const shadowText = this.containInboundReject(finding, f.path, text, entry.id, committed);
                         if (shadowText === undefined) {
                             if (committed !== undefined) {
                                 delete ledger[entry.id];
@@ -316,6 +323,7 @@ export class FileMemoryEngineBackend {
                             }
                             continue;
                         }
+                        entry = entryFromFile(shadowText, entry.id, f.slug, scope);
                     }
                     else {
                         if (committed !== undefined)
@@ -339,8 +347,11 @@ export class FileMemoryEngineBackend {
             }
             entries.push(entry);
         }
-        if (ledgerChanged)
+        if (ledgerChanged) {
+            if (lockToken !== undefined)
+                this.assertTxnLockOwnership(lockToken);
             this.saveLedger();
+        }
         if (adoptedExternal.length > 0) {
             try {
                 enqueueMemoryAnnouncement(this.controlPlaneRoot, {
@@ -373,27 +384,46 @@ export class FileMemoryEngineBackend {
             this.batchScan.set(scope, entries);
         return entries;
     }
+    async readScopeAdopting(scope, timings) {
+        const probed = this.readScope(scope, true, true);
+        if (probed !== undefined)
+            return probed;
+        const lock = await this.acquireTxnLock(timings);
+        try {
+            this.assertTxnLockOwnership(lock.token);
+            this.ledger = undefined;
+            this.recoverJournal();
+            return this.readScope(scope, true, false, lock.token);
+        }
+        catch (err) {
+            this.ledger = undefined;
+            throw err;
+        }
+        finally {
+            lock.release();
+        }
+    }
     async listHeaders(scopes) {
-        return this.listHeadersWith(scopes, true);
+        return this.listHeadersFrom(scopes, (s) => this.readScopeAdopting(s));
     }
-    listHeadersWith(scopes, adopt) {
+    async listHeadersFrom(scopes, read) {
         const out = [];
         for (const scope of scopes) {
             const dir = this.scopeDir(scope);
-            for (const e of this.readScope(scope, adopt)) {
+            for (const e of await read(scope)) {
                 out.push(headerOf(e, join(dir, `${e.slug}.md`)));
             }
         }
         return out;
     }
     async getByIds(ids) {
-        return this.getByIdsWith(ids, true);
+        return this.getByIdsFrom(ids, (s) => this.readScopeAdopting(s));
     }
-    getByIdsWith(ids, adopt) {
+    async getByIdsFrom(ids, read) {
         const want = new Set(ids);
         const out = [];
         for (const scope of Object.keys(registeredScopes(this.controlPlaneRoot))) {
-            for (const e of this.readScope(scope, adopt)) {
+            for (const e of await read(scope)) {
                 if (want.has(e.id))
                     out.push(e);
             }
@@ -405,18 +435,256 @@ export class FileMemoryEngineBackend {
             throw new Error(`memory retrieval view is read-only — ${op} must go through the backend itself`);
         };
         return {
-            listHeaders: async (scopes) => this.listHeadersWith(scopes, false),
-            getByIds: async (ids) => this.getByIdsWith(ids, false),
-            search: async (query, scopes, opts) => this.searchWith(query, scopes, opts, false),
+            listHeaders: async (scopes) => this.listHeadersFrom(scopes, (s) => this.readScope(s, false)),
+            getByIds: async (ids) => this.getByIdsFrom(ids, (s) => this.readScope(s, false)),
+            search: async (query, scopes, opts) => this.searchFrom(query, scopes, opts, (s) => this.readScope(s, false)),
             applyPatches: async () => refuse("applyPatches"),
             getConsolidationCursor: async (scope) => this.getConsolidationCursor(scope),
             setConsolidationCursor: async () => refuse("setConsolidationCursor"),
         };
     }
+    restrictedFindingKeys = new Set();
+    recordRestrictedFinding(key, finding) {
+        if (this.restrictedFindingKeys.has(key))
+            return;
+        this.restrictedFindingKeys.add(key);
+        this.inboundFindings.push(finding);
+    }
+    restrictedIdlessScope;
+    restrictedIdlessBaseline;
+    readScopeCommitted(scope, audit) {
+        const dir = this.scopeDir(scope);
+        const isRoot = dir === this.directoryRoot;
+        const files = scanEntryFiles(dir, {
+            exclude: isRoot ? this.excludedSubdirNames(scope) : undefined,
+            onSkip: audit
+                ? (p, kind) => {
+                    if (kind !== "unreadable")
+                        return;
+                    const rel = relative(this.directoryRoot, p);
+                    this.recordRestrictedFinding(`unreadable|${rel}`, {
+                        path: rel,
+                        code: "unreadable",
+                        reason: "the path could not be read (lstat/readdir failed) — the restricted-session divergence audit is incomplete under it",
+                    });
+                }
+                : undefined,
+        });
+        this.ledger = undefined;
+        const ledger = this.loadLedger();
+        const idlessSeen = audit && scope === this.restrictedIdlessScope ? new Set() : undefined;
+        const entries = [];
+        for (const f of files) {
+            const rel = relative(this.directoryRoot, f.path);
+            let text;
+            try {
+                text = readFileSync(f.path, "utf8");
+            }
+            catch {
+                if (audit) {
+                    this.recordRestrictedFinding(`unreadable|${rel}`, {
+                        path: rel,
+                        code: "unreadable",
+                        reason: "memory entry file could not be read — it is missing from this restricted session's view",
+                    });
+                }
+                continue;
+            }
+            const parsed = parseEntryFile(text);
+            if (parsed.id === undefined) {
+                idlessSeen?.add(rel);
+                continue;
+            }
+            const entry = entryFromFile(text, parsed.id, f.slug, scope);
+            const committed = ledger[entry.id];
+            if (committed === entry.rev) {
+                if (audit && this.readCommittedShadow(entry.id) === undefined) {
+                    try {
+                        atomicWriteFileSync(this.shadowPath(entry.id), text);
+                    }
+                    catch {
+                    }
+                }
+                entries.push(entry);
+                continue;
+            }
+            const shadowText = committed !== undefined ? this.readCommittedShadow(entry.id) : undefined;
+            if (shadowText !== undefined) {
+                const shadowEntry = entryFromFile(shadowText, entry.id, f.slug, scope);
+                if (shadowEntry.rev === entry.rev) {
+                    entries.push(entry);
+                    continue;
+                }
+                const otherProjection = this.idProjectionElsewhere(entry.id, f.path);
+                if (otherProjection !== undefined) {
+                    if (audit) {
+                        const finding = this.inboundGate(rel, text);
+                        if (finding !== undefined) {
+                            this.containInboundReject(finding, f.path, text, entry.id, undefined);
+                        }
+                        else {
+                            this.recordRestrictedFinding(`dupserve|${rel}|${entry.rev}`, {
+                                path: rel,
+                                code: "restricted_divergence",
+                                reason: `this file carries the id of a committed entry that has another projection (${otherProjection}) — the committed copy may only stand in for an entry's unique projection, so this copy is withheld; an unrestricted session's harvest adjudicates it`,
+                            });
+                        }
+                    }
+                    continue;
+                }
+                if (audit) {
+                    const finding = this.inboundGate(rel, text);
+                    if (finding !== undefined) {
+                        this.containInboundReject(finding, f.path, text, entry.id, committed);
+                    }
+                    else {
+                        this.recordRestrictedFinding(`divergence|${rel}|${entry.rev}`, {
+                            path: rel,
+                            code: "restricted_divergence",
+                            reason: "on-disk content diverges from the committed entry with no backend transaction backing it; this adoption-restricted session serves the committed content and leaves the disk state pending — an unrestricted session can adopt it normally",
+                        });
+                    }
+                }
+                entries.push(shadowEntry);
+                continue;
+            }
+            if (committed !== undefined) {
+                if (audit) {
+                    this.recordRestrictedFinding(`legacy|${rel}|${entry.rev}`, {
+                        path: rel,
+                        code: "restricted_divergence",
+                        reason: "on-disk content diverges from a committed entry that has no committed shadow copy; this adoption-restricted session withholds the entry (nothing trustworthy to serve) — an unrestricted session can adjudicate it",
+                    });
+                }
+                continue;
+            }
+            if (audit) {
+                const finding = this.inboundGate(rel, text);
+                if (finding !== undefined) {
+                    this.containInboundReject(finding, f.path, text, entry.id, undefined);
+                }
+                else {
+                    this.recordRestrictedFinding(`uncommitted|${rel}|${entry.rev}`, {
+                        path: rel,
+                        code: "restricted_divergence",
+                        reason: "an id-bearing memory file exists on disk that the committed account has never seen; this adoption-restricted session neither adopts nor serves it — it stays on disk for an unrestricted session to adopt normally",
+                    });
+                }
+            }
+        }
+        if (idlessSeen !== undefined && this.restrictedIdlessBaseline === undefined)
+            this.restrictedIdlessBaseline = idlessSeen;
+        return entries;
+    }
+    idProjectionElsewhere(id, excludeAbsPath) {
+        for (const scope of Object.keys(registeredScopes(this.controlPlaneRoot))) {
+            const dir = this.scopeDir(scope);
+            const isRoot = dir === this.directoryRoot;
+            for (const f of scanEntryFiles(dir, { exclude: isRoot ? this.excludedSubdirNames(scope) : undefined })) {
+                if (f.path === excludeAbsPath)
+                    continue;
+                const text = readSafe(f.path);
+                if (text === undefined)
+                    continue;
+                if (parseEntryFile(text).id === id)
+                    return relative(this.directoryRoot, f.path);
+            }
+        }
+        return undefined;
+    }
+    restrictedAdoptionView(opts) {
+        const audit = opts?.audit === true;
+        if (audit) {
+            this.restrictedIdlessScope = typeof opts?.writeScope === "string" ? opts.writeScope : undefined;
+            this.restrictedIdlessBaseline = undefined;
+        }
+        const refuse = (op) => {
+            throw new Error(`memory adoption-restricted view is read-only — ${op} must go through the backend itself`);
+        };
+        return {
+            listHeaders: async (scopes) => this.listHeadersFrom(scopes, (s) => this.readScopeCommitted(s, audit)),
+            getByIds: async (ids) => this.getByIdsFrom(ids, (s) => this.readScopeCommitted(s, audit)),
+            search: async (query, scopes, o) => this.searchFrom(query, scopes, o, (s) => this.readScopeCommitted(s, audit)),
+            applyPatches: async () => refuse("applyPatches"),
+            getConsolidationCursor: async (scope) => this.getConsolidationCursor(scope),
+            setConsolidationCursor: async () => refuse("setConsolidationCursor"),
+        };
+    }
+    auditRestrictedDivergence(scopes, opts) {
+        for (const scope of scopes)
+            this.readScopeCommitted(scope, true);
+        const idlessBaseline = opts?.idlessWriteScope !== undefined && opts.idlessWriteScope === this.restrictedIdlessScope ? this.restrictedIdlessBaseline : undefined;
+        const idlessScope = idlessBaseline !== undefined ? opts?.idlessWriteScope : undefined;
+        const ledger = { ...this.loadLedger() };
+        const present = new Map();
+        let complete = true;
+        for (const scope of Object.keys(registeredScopes(this.controlPlaneRoot))) {
+            const dir = this.scopeDir(scope);
+            const isRoot = dir === this.directoryRoot;
+            const files = scanEntryFiles(dir, {
+                exclude: isRoot ? this.excludedSubdirNames(scope) : undefined,
+                onSkip: (_p, kind) => {
+                    if (kind === "unreadable")
+                        complete = false;
+                },
+            });
+            for (const f of files) {
+                const text = readSafe(f.path);
+                if (text === undefined) {
+                    complete = false;
+                    continue;
+                }
+                const id = parseEntryFile(text).id;
+                if (id !== undefined) {
+                    present.set(id, [...(present.get(id) ?? []), relative(this.directoryRoot, f.path)]);
+                    continue;
+                }
+                if (scope === idlessScope && idlessBaseline !== undefined) {
+                    const rel = relative(this.directoryRoot, f.path);
+                    if (!idlessBaseline.has(rel)) {
+                        this.recordRestrictedFinding(`idless|${rel}|${createHash("sha256").update(text, "utf8").digest("hex").slice(0, 16)}`, {
+                            path: rel,
+                            code: "restricted_divergence",
+                            reason: "an id-less file appeared under the session's write scope after materialize, through none of this session's channels: a concurrent session's in-flight material, or an out-of-band drop — left on disk for an unrestricted harvest to adjudicate",
+                        });
+                    }
+                }
+            }
+        }
+        for (const [id, paths] of present) {
+            if (paths.length < 2 || ledger[id] === undefined)
+                continue;
+            this.recordRestrictedFinding(`dup|${id}|${paths.sort().join(",")}`, {
+                path: paths[0] ?? id,
+                code: "restricted_divergence",
+                reason: `committed memory entry ${id} appears at ${paths.length} paths (${paths.join(", ")}) — a filesystem copy is not a rename; this adoption-restricted session flags it and an unrestricted session's harvest adjudicates which projection is real`,
+            });
+        }
+        if (!complete) {
+            this.recordRestrictedFinding(`missing-audit-incomplete`, {
+                path: ".",
+                code: "restricted_divergence",
+                reason: "the divergence audit could not scan every path (unreadable subtree) — missing-entry detection was skipped this pass rather than judged from an incomplete scan",
+            });
+            return;
+        }
+        for (const [id, rev] of Object.entries(ledger)) {
+            if (present.has(id))
+                continue;
+            this.ledger = undefined;
+            if (this.loadLedger()[id] === undefined)
+                continue;
+            this.recordRestrictedFinding(`missing|${id}|${rev}`, {
+                path: `id:${id}`,
+                code: "restricted_divergence",
+                reason: `committed memory entry ${id} is missing from disk with no transaction backing the removal; this adoption-restricted session neither restores nor forgets it — an unrestricted session can restore it from the committed copy`,
+            });
+        }
+    }
     async search(query, scopes, opts) {
-        return this.searchWith(query, scopes, opts, true);
+        return this.searchFrom(query, scopes, opts, (s) => this.readScopeAdopting(s));
     }
-    searchWith(query, scopes, opts, adopt) {
+    async searchFrom(query, scopes, opts, read) {
         const limit = opts?.limit ?? 20;
         const q = termSet(query);
         if (q.size === 0)
@@ -424,7 +692,7 @@ export class FileMemoryEngineBackend {
         const scored = [];
         for (const scope of scopes) {
             const dir = this.scopeDir(scope);
-            for (const e of this.readScope(scope, adopt)) {
+            for (const e of await read(scope)) {
                 const haystack = `${e.frontmatter.name ?? e.slug} ${e.frontmatter.description ?? ""} ${e.body}`;
                 const d = jaccardDistance(q, haystack);
                 if (d === null)

package/dist/core/memory-engine/layout.d.ts

@@ -111,6 +111,17 @@ export declare function resolveMemoryEngineRoot(explicit?: string): string;
  * collision (two distinct scopes → one dir name), so even a hash collision cannot silently merge scopes.
  */
 export declare function scopeDirName(scope: string): string;
+/**
+ * Whether `dir`'s volume FOLDS letter case — two names differing only in case address ONE
+ * directory entry (the macOS/Windows default). Probed on the actual directory, never guessed from
+ * the platform: case-sensitive APFS volumes and case-insensitive Linux mounts both exist, and this
+ * answer gates a fail-closed isolation refusal, so it must describe the volume the scope dirs
+ * really land on — a platform guess would fail OPEN exactly on the mismatched deployments.
+ * `undefined` = the volume answered on neither leg (unwritable AND no letter-bearing entry to read
+ * against); the caller must treat that as unresolved, never as either determined answer.
+ * Exported for the layout pins; not part of the package surface.
+ */
+export declare function dirCaseFolds(dir: string): boolean | undefined;
 /** Which scope owns the memory dir ROOT (undefined = unclaimed). */
 export declare function rootScopeOf(controlDir: string): string | undefined;
 /**
@@ -121,8 +132,26 @@ export declare function rootScopeOf(controlDir: string): string | undefined;
 export declare function claimRootScope(controlDir: string, scope: string): string;
 /** Register `scope` in the durable registry (idempotent) and return its home dir under `memoryDir`.
  *  H5 fail-closed: a dir-name collision with a DIFFERENT registered scope throws — two scopes must
- *  never share one directory (silent cross-scope merge). Lock-serialized (独立轨 F5). */
-export declare function registerScope(memoryDir: string, controlDir: string, scope: string): string;
+ *  never share one directory (silent cross-scope merge). The collision test has TWO arms:
+ *   - exact: two scopes whose labels are the SAME string (hash collision / forged registry);
+ *   - case-fold (2026-08-12): two labels differing ONLY in letter case are distinct strings to this
+ *     registry yet ONE physical directory on a case-folding volume — cross-scope bleed the exact arm
+ *     cannot see. The fold arm compares the FINAL dir labels (ASCII by construction, so toLowerCase
+ *     is an exact fold) and only fires when the volume actually folds — probed lazily on a fold-equal
+ *     candidate ({@link dirCaseFolds}), so the no-collision path never pays the probe and a
+ *     case-SENSITIVE volume keeps hosting case-differing scope pairs as the genuinely distinct
+ *     directories they are there. An UNPROBEABLE volume (neither probe leg answers) refuses the
+ *     fold-equal pair too — an unresolved semantics guess would fail open exactly where the guard
+ *     is needed. `opts.caseFoldingFs` overrides the probe for callers (and pins) that already
+ *     measured the volume's semantics. The scope→dir MAPPING itself is unchanged on purpose:
+ *     folding scopeDirName would re-home every existing mixed-case scope's directory.
+ *  Both arms compare the scope's EFFECTIVE label — the registered one when present (a registered
+ *  scope's home NEVER moves; entries live there), the formula only for a never-registered scope —
+ *  so a registry whose stored labels drifted from the current formula is judged by the directories
+ *  it actually serves, not by labels nobody uses. Lock-serialized (独立轨 F5). */
+export declare function registerScope(memoryDir: string, controlDir: string, scope: string, opts?: {
+    caseFoldingFs?: boolean;
+}): string;
 /** All registered scopes → home dir name (`""` = the root). */
 export declare function registeredScopes(controlDir: string): Record<string, string>;
 /** The stable home directory of `scope`'s entry files: the root when it owns the root, else the