@sema-agent/core 5.27.0 → 5.29.0

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

@@ -37,7 +37,7 @@ export declare const MEMORY_RECALL_DISCIPLINE = "Before answering questions abou
  * CC-verbatim `# Memory` instruction stays byte-identical to its sha256-pinned capture. Appended
  * only when a WRITE channel exists (prepare-memory gates it) — the lines it teaches are frontmatter
  * the MODEL writes; the engine has no write arm for them (writing usage evidence for the model
- * would forge the very account the three-tier discipline forbids forging).
+ * would self-declare the very account the three-tier discipline forbids forging).
  */
 export declare const MEMORY_PREFERENCE_DISCIPLINE = "When the user confirms a stored preference or fact still holds, refresh that entry's `last-confirmed: <YYYY-MM-DD>` frontmatter line (add it when absent). When you save a preference, add an `applies-when: <context>` frontmatter line naming when it applies. Both are plain frontmatter lines \u2014 write them yourself; nothing fills them in for you.";
 /**

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

@@ -328,7 +328,7 @@ export class MemoryEngine {
         ensureDirExists(this.controlDir);
         const restricted = opts?.adoptionRestricted === true;
         const readBackend = restricted
-            ? (this.backend.restrictedAdoptionView?.({ audit: true }) ?? this.backend)
+            ? (this.backend.restrictedAdoptionView?.({ audit: true, writeScope }) ?? this.backend)
             : this.backend;
         if (writeScope !== null)
             claimRootScope(this.controlDir, writeScope);
@@ -536,9 +536,7 @@ export class MemoryEngine {
         const writeScope = handle.writeScope;
         if (writeScope === null || opts?.admitNothing !== undefined) {
             try {
-                this.backend.auditRestrictedDivergence?.([
-                    ...new Set([...handle.scopes, ...(writeScope !== null ? [writeScope] : [])]),
-                ]);
+                this.backend.auditRestrictedDivergence?.([...new Set([...handle.scopes, ...(writeScope !== null ? [writeScope] : [])])], handle.adoptionRestricted === true && writeScope !== null ? { idlessWriteScope: writeScope } : undefined);
             }
             catch (err) {
                 report.warnings.push(`restricted-session divergence audit failed: ${err instanceof Error ? err.message : String(err)}`);

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

@@ -147,13 +147,48 @@ 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
@@ -181,6 +216,19 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      *  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:
@@ -223,13 +271,15 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      * 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;
+     *    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.
+     *    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
@@ -240,13 +290,22 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      * 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[]): void;
+    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:
@@ -264,7 +323,7 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
     applyPatches(patches: readonly NotePatch[]): Promise<PatchReport>;
     private txnLockDir;
     /**
-     * 对抗复审 L1/L2/L3 — the mkdir mutex, hardened (same shape as layout.ts' acquireSidecarLock, but
+     * 证伪式复审 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
@@ -279,7 +338,7 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      *    crashed with `remaining stale > waitMs` no longer strands every waiter in an all-throw window.
      */
     private acquireTxnLock;
-    /** 对抗复审 L2 — 提交点归属复验: called immediately before the JOURNAL write (the persistent commit
+    /** 证伪式复审 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
      *  stolen from must ABORT — its staged tmps carry no committed state and the stealer's journal
      *  recovery is now authoritative; committing anyway would overwrite the stealer's transaction. */

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";
@@ -263,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)
@@ -293,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) {
@@ -343,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, {
@@ -377,33 +384,46 @@ export class FileMemoryEngineBackend {
             this.batchScan.set(scope, entries);
         return entries;
     }
-    async listHeaders(scopes) {
-        return this.listHeadersWith(scopes, true);
+    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();
+        }
     }
-    listHeadersWith(scopes, adopt) {
-        return this.listHeadersFrom(scopes, (s) => this.readScope(s, adopt));
+    async listHeaders(scopes) {
+        return this.listHeadersFrom(scopes, (s) => this.readScopeAdopting(s));
     }
-    listHeadersFrom(scopes, read) {
+    async listHeadersFrom(scopes, read) {
         const out = [];
         for (const scope of scopes) {
             const dir = this.scopeDir(scope);
-            for (const e of read(scope)) {
+            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);
-    }
-    getByIdsWith(ids, adopt) {
-        return this.getByIdsFrom(ids, (s) => this.readScope(s, adopt));
+        return this.getByIdsFrom(ids, (s) => this.readScopeAdopting(s));
     }
-    getByIdsFrom(ids, read) {
+    async getByIdsFrom(ids, read) {
         const want = new Set(ids);
         const out = [];
         for (const scope of Object.keys(registeredScopes(this.controlPlaneRoot))) {
-            for (const e of read(scope)) {
+            for (const e of await read(scope)) {
                 if (want.has(e.id))
                     out.push(e);
             }
@@ -415,9 +435,9 @@ 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"),
@@ -430,6 +450,8 @@ export class FileMemoryEngineBackend {
         this.restrictedFindingKeys.add(key);
         this.inboundFindings.push(finding);
     }
+    restrictedIdlessScope;
+    restrictedIdlessBaseline;
     readScopeCommitted(scope, audit) {
         const dir = this.scopeDir(scope);
         const isRoot = dir === this.directoryRoot;
@@ -450,6 +472,7 @@ export class FileMemoryEngineBackend {
         });
         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);
@@ -468,8 +491,10 @@ export class FileMemoryEngineBackend {
                 continue;
             }
             const parsed = parseEntryFile(text);
-            if (parsed.id === undefined)
+            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) {
@@ -547,6 +572,8 @@ export class FileMemoryEngineBackend {
                 }
             }
         }
+        if (idlessSeen !== undefined && this.restrictedIdlessBaseline === undefined)
+            this.restrictedIdlessBaseline = idlessSeen;
         return entries;
     }
     idProjectionElsewhere(id, excludeAbsPath) {
@@ -567,6 +594,10 @@ export class FileMemoryEngineBackend {
     }
     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`);
         };
@@ -579,9 +610,11 @@ export class FileMemoryEngineBackend {
             setConsolidationCursor: async () => refuse("setConsolidationCursor"),
         };
     }
-    auditRestrictedDivergence(scopes) {
+    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;
@@ -602,8 +635,20 @@ export class FileMemoryEngineBackend {
                     continue;
                 }
                 const id = parseEntryFile(text).id;
-                if (id !== undefined)
+                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) {
@@ -637,12 +682,9 @@ export class FileMemoryEngineBackend {
         }
     }
     async search(query, scopes, opts) {
-        return this.searchWith(query, scopes, opts, true);
-    }
-    searchWith(query, scopes, opts, adopt) {
-        return this.searchFrom(query, scopes, opts, (s) => this.readScope(s, adopt));
+        return this.searchFrom(query, scopes, opts, (s) => this.readScopeAdopting(s));
     }
-    searchFrom(query, scopes, opts, read) {
+    async searchFrom(query, scopes, opts, read) {
         const limit = opts?.limit ?? 20;
         const q = termSet(query);
         if (q.size === 0)
@@ -650,7 +692,7 @@ export class FileMemoryEngineBackend {
         const scored = [];
         for (const scope of scopes) {
             const dir = this.scopeDir(scope);
-            for (const e of read(scope)) {
+            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/header-hints.d.ts

@@ -11,7 +11,7 @@
  * This accessor is the ONLY consumer-side reading: pure, lenient, and closed over bad values —
  * a malformed line reads as FIELD ABSENT, never an error and never a partial adoption. Nothing in
  * the engine writes these lines; the model does (the preference-discipline paragraph teaches it),
- * because an engine-written confirmation would forge the usage evidence it is supposed to record.
+ * because an engine-written confirmation would self-declare the usage evidence it is supposed to record.
  */
 /** The parsed v2 hints. Every field is absent unless a well-formed line was found. */
 export interface V2HeaderHints {

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 / caller-declared 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
@@ -444,7 +473,7 @@ export declare function appendChallengeEvents(controlDir: string, events: Readon
  *
  *  `eventCount` rides along for the same reason it does on {@link appendChallengeEvents}: a resolve
  *  APPENDS an event too, so it crosses the size bound exactly as a challenge does (independent
- *  adversarial review, verified — hanging the disclosure off the challenge writer alone leaves a ledger
+ *  falsification review, verified — hanging the disclosure off the challenge writer alone leaves a ledger
  *  that crossed the bound on a resolve silent until the next challenge, which may never come).
  *  `undefined` when nothing was appended. */
 export declare function resolveChallengeEvent(controlDir: string, entryId: string, generation: number, reason: string, now: () => number, requestId?: string): {

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

@@ -1,5 +1,5 @@
-import { closeSync, constants as fsConstants, copyFileSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
-const { O_WRONLY, O_CREAT, O_TRUNC, O_NOFOLLOW } = fsConstants;
+import { closeSync, constants as fsConstants, copyFileSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+const { O_WRONLY, O_CREAT, O_TRUNC, O_NOFOLLOW, O_EXCL } = fsConstants;
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
@@ -184,6 +184,119 @@ export function scopeDirName(scope) {
     const hash = createHash("sha256").update(scope, "utf8").digest("hex").slice(0, 6);
     return `${cleaned}-${hash}`;
 }
+const caseFoldByDirIdentity = new Map();
+let caseFoldProbeSeq = 0;
+function lstatOrAbsent(p) {
+    try {
+        return lstatSync(p);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+}
+function probeDirCaseFolds(dir) {
+    const name = `.casefold-probe-${process.pid}-${caseFoldProbeSeq++}`;
+    const writeLeg = (() => {
+        let fd;
+        try {
+            fd = openSync(join(dir, name), O_WRONLY | O_CREAT | O_EXCL, 0o600);
+        }
+        catch {
+            return undefined;
+        }
+        let identity;
+        try {
+            const st = fstatSync(fd);
+            identity = { dev: st.dev, ino: st.ino };
+        }
+        catch {
+        }
+        finally {
+            closeSync(fd);
+        }
+        try {
+            let swapped;
+            let orig;
+            try {
+                swapped = lstatOrAbsent(join(dir, name.toUpperCase()));
+                orig = swapped === undefined ? lstatOrAbsent(join(dir, name)) : undefined;
+            }
+            catch {
+                return undefined;
+            }
+            if (swapped !== undefined) {
+                return identity === undefined || (swapped.dev === identity.dev && swapped.ino === identity.ino) ? true : undefined;
+            }
+            if (orig === undefined || identity === undefined)
+                return undefined;
+            return orig.dev === identity.dev && orig.ino === identity.ino ? false : undefined;
+        }
+        finally {
+            try {
+                rmSync(join(dir, name), { force: true });
+            }
+            catch {
+            }
+        }
+    })();
+    if (writeLeg !== undefined)
+        return writeLeg;
+    try {
+        for (const entry of readdirSync(dir)) {
+            if (!/[A-Za-z]/.test(entry))
+                continue;
+            const swapped = entry.toLowerCase() !== entry ? entry.toLowerCase() : entry.toUpperCase();
+            try {
+                const orig = lstatOrAbsent(join(dir, entry));
+                if (orig === undefined)
+                    continue;
+                const other = lstatOrAbsent(join(dir, swapped));
+                const again = lstatOrAbsent(join(dir, entry));
+                if (again === undefined || again.dev !== orig.dev || again.ino !== orig.ino)
+                    continue;
+                if (other === undefined)
+                    return false;
+                return other.dev === orig.dev && other.ino === orig.ino;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    catch {
+    }
+    return undefined;
+}
+export function dirCaseFolds(dir) {
+    let key;
+    try {
+        ensureDirExists(dir);
+        const s = statSync(dir);
+        key = `${s.dev}:${s.ino}`;
+    }
+    catch {
+    }
+    if (key !== undefined) {
+        const cached = caseFoldByDirIdentity.get(key);
+        if (cached !== undefined)
+            return cached;
+    }
+    const folds = probeDirCaseFolds(dir);
+    if (folds === undefined)
+        return undefined;
+    try {
+        const after = statSync(dir);
+        if (key === undefined || key !== `${after.dev}:${after.ino}`)
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    caseFoldByDirIdentity.set(key, folds);
+    return folds;
+}
 function readScopesRecord(controlDir) {
     const path = join(controlDir, SCOPES_FILE);
     let raw;
@@ -217,6 +330,11 @@ function readScopesRecord(controlDir) {
         for (const [k, v] of Object.entries(rec.scopes)) {
             if (typeof v !== "string")
                 throw new ControlPlaneCorruptError(`scope registry entry ${JSON.stringify(k)} is not a string: ${path}`);
+            if ((v === "") !== (k === rec.rootScope)) {
+                throw new ControlPlaneCorruptError(v === ""
+                    ? `scope registry maps ${JSON.stringify(k)} to the root home but rootScope is ${rec.rootScope === undefined ? "unclaimed" : JSON.stringify(rec.rootScope)}: ${path}`
+                    : `scope registry maps the root scope ${JSON.stringify(k)} to subdir ${JSON.stringify(v)} instead of the root home: ${path}`);
+            }
         }
         scopes = rec.scopes;
     }
@@ -255,20 +373,26 @@ export function claimRootScope(controlDir, scope) {
         return { next: { rootScope: scope, scopes: { ...rec.scopes, [scope]: "" } }, result: scope };
     });
 }
-export function registerScope(memoryDir, controlDir, scope) {
+export function registerScope(memoryDir, controlDir, scope, opts) {
     return lockedScopesUpdate(controlDir, (rec) => {
-        const dirName = rec.rootScope === scope ? "" : scopeDirName(scope);
+        const dirName = rec.rootScope === scope ? "" : (rec.scopes?.[scope] ?? scopeDirName(scope));
         for (const [other, otherDir] of Object.entries(rec.scopes ?? {})) {
-            if (other !== scope && otherDir !== "" && otherDir === dirName) {
+            if (other === scope || otherDir === "")
+                continue;
+            if (otherDir === dirName) {
                 throw new ControlPlaneCorruptError(`scope directory collision: ${JSON.stringify(scope)} and ${JSON.stringify(other)} both map to ${JSON.stringify(dirName)} — refusing (fail-closed)`);
             }
+            if (dirName !== "" && otherDir.toLowerCase() === dirName.toLowerCase()) {
+                const folds = opts?.caseFoldingFs ?? dirCaseFolds(memoryDir);
+                if (folds !== false) {
+                    throw new ControlPlaneCorruptError(`scope directory collision on a case-folding filesystem: ${JSON.stringify(scope)} → ${JSON.stringify(dirName)} and ${JSON.stringify(other)} → ${JSON.stringify(otherDir)} are one physical directory under ${memoryDir}` +
+                        `${folds === undefined ? " (volume case semantics could not be probed — refusing the fold-equal pair rather than risking a silent cross-scope merge)" : ""} — refusing (fail-closed)`);
+                }
+            }
         }
         if (rec.scopes?.[scope] === undefined) {
             return { next: { ...rec, scopes: { ...rec.scopes, [scope]: dirName } }, result: dirName === "" ? memoryDir : join(memoryDir, dirName) };
         }
-        if (rec.scopes[scope] !== dirName) {
-            return { result: rec.scopes[scope] === "" ? memoryDir : join(memoryDir, rec.scopes[scope]) };
-        }
         return { result: dirName === "" ? memoryDir : join(memoryDir, dirName) };
     });
 }

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

@@ -224,11 +224,12 @@ export interface MemorySessionHandle {
      *  leave the injection path reading them anyway. Absent ⇒ the normal "live file wins" behavior. */
     indexOnDiskUntrusted?: boolean;
     /** True ⇔ this session materialized through the ADOPTION-RESTRICTED (committed-view) read face:
-     *  either the plane is a read-only layering (`writeScope === null`) or the caller declared the
-     *  session unable to persist (an explicit verdict — never inferred down here). Restricted sessions
-     *  read committed state only (ledger + control-plane shadow); disk divergence with no transaction
-     *  backing is neither adopted into the committed account nor served, and `inject` reads the
-     *  materialize-time index text instead of the live on-disk file. */
+     *  the caller declared the session unable to persist (an explicit session-level verdict — never
+     *  inferred down here, and never derived from the plane's shape: a read-only layering
+     *  (`writeScope === null`) keeps its ordinary adopt-on-read semantics and does NOT set this).
+     *  Restricted sessions read committed state only (ledger + control-plane shadow); disk divergence
+     *  with no transaction backing is neither adopted into the committed account nor served, and
+     *  `inject` reads the materialize-time index text instead of the live on-disk file. */
     adoptionRestricted?: boolean;
 }
 /** Stable rejection codes a harvest gate can produce (model-visible gate events — 镜头 I). */

package/dist/core/memory-recall.d.ts

@@ -162,7 +162,7 @@ export declare function composeSelectiveBody(manifestText: string, selected: Mem
 /** A `(scope, id)` composite key for the multi-scope durable de-dup (design/84 Seam A decision 5). Note ids
  *  are only unique WITHIN a scope, so the cross-scope `priorSurfacedKeys`/`surfacedKeys` set MUST be keyed on
  *  both. Core owns the FORMAT so a caller can't drift the wire format (decision 7) — the encoding is OPAQUE
- *  and length-prefixes the scope so a scope/id containing the separator cannot forge a collision.
+ *  and length-prefixes the scope so a scope/id containing the separator cannot self-declare a collision.
  *
  *  ONE-WAY by design (codex MINOR (d)): the key is only ever PRODUCED here (`surfacedKeys`) and compared by
  *  STRING EQUALITY against the caller's persisted set ({@link LayeredRecallOptions.priorSurfacedKeys}, applied