@sema-agent/core 5.25.0 → 5.27.0

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

@@ -34,6 +34,11 @@ export function buildMemoryInstruction(memoryDir, instructionFileName) {
 }
 export const MEMORY_RECALL_DISCIPLINE = "Before answering questions about earlier work, decisions, dates, people, or the user's preferences, look them up: `memory_search` finds entries by keyword and `memory_get` reads a full entry — the injected memory index only lists what exists. When a lookup comes up empty, say that you checked memory and found nothing instead of guessing.";
 export 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 — write them yourself; nothing fills them in for you.";
+export const MEMORY_ANNOUNCEMENT_READONLY_PLANE_CODA = "The notices immediately above concern a READ-ONLY memory store: any guidance in them to record, update, or tombstone an entry cannot be applied to that store this session — surface it to the user instead of claiming it done.";
+export const MEMORY_ANNOUNCEMENT_READONLY_CODA = "The memory store itself is not writable this session, so any guidance above to record, update, or tombstone a memory entry cannot be applied here — surface it to the user instead of claiming it done.";
+export const MEMORY_READONLY_NOTICE = `# Memory
+
+You have READ-ONLY access to persistent memory in this session: stored notes are available below, but this session has no memory write channel — the engine will not accept writes into the memory store. If the user asks you to remember something for later, say plainly that you cannot save it in this session — never claim to have noted or remembered it.`;
 export const MEMORY_INDEX_MAX_LINES = 200;
 export const MEMORY_INDEX_MAX_BYTES = 25 * 1024;
 export const STUB_ARCHIVED_LINE = "[body archived — request hydration by listing the slug in memory/.hydrate]";
@@ -41,6 +46,7 @@ export const DEFAULT_MAX_MEMORY_FILES = 500;
 export const DEFAULT_HARVEST_DEADLINE_MS = 5_000;
 export const DEFAULT_HARVEST_FILE_BUDGET = 2_000;
 export const MASS_DELETION_FUSE_RATIO = 0.5;
+let indexCaptureSeq = 0;
 export class MemoryEngine {
     backend;
     memoryDir;
@@ -317,9 +323,13 @@ export class MemoryEngine {
         catch {
         }
     }
-    async materialize(scopes, writeScope) {
+    async materialize(scopes, writeScope, opts) {
         ensureDirExists(this.memoryDir);
         ensureDirExists(this.controlDir);
+        const restricted = opts?.adoptionRestricted === true;
+        const readBackend = restricted
+            ? (this.backend.restrictedAdoptionView?.({ audit: true }) ?? this.backend)
+            : this.backend;
         if (writeScope !== null)
             claimRootScope(this.controlDir, writeScope);
         const scopeDirs = new Map();
@@ -330,8 +340,8 @@ export class MemoryEngine {
         for (const [scope, dir] of scopeDirs)
             this.chmodScopeTree(dir, 0o755, 0o644, { excludeTopDirs: this.siblingScopeDirNames(dir, scope) });
         const allScopes = [...scopeDirs.keys()];
-        const headers = await this.backend.listHeaders(allScopes);
-        const entries = await this.backend.getByIds(headers.map((h) => h.id));
+        const headers = await readBackend.listHeaders(allScopes);
+        const entries = await readBackend.getByIds(headers.map((h) => h.id));
         const byScope = new Map();
         for (const e of entries) {
             const arr = byScope.get(e.scope) ?? [];
@@ -351,6 +361,7 @@ export class MemoryEngine {
             repoIndexTargets: new Map(),
             indexBaselineLines: 0,
             indexText: "",
+            ...(restricted ? { adoptionRestricted: true } : {}),
         };
         if (writeScope !== null)
             ensureDirExists(handle.writableRoot);
@@ -376,7 +387,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`);
-                this.writeIfChanged(target, text);
+                if (!(zeroCopy && restricted))
+                    this.writeIfChanged(target, text);
                 const onDiskRev = stub ? revOfText(text, entry.id) : entry.rev;
                 const path = canonicalize(target);
                 handle.materialized.push({
@@ -409,7 +421,7 @@ export class MemoryEngine {
                 this.discloseAnnounceFailure("index-gate enqueue", err);
             }
         }
-        const indexText = this.rebuildIndex(handle, headers, { write: writeScope !== null, ignoreOnDisk: indexGate !== undefined });
+        const indexText = this.rebuildIndex(handle, headers, { write: writeScope !== null && !restricted, ignoreOnDisk: indexGate !== undefined || restricted });
         handle.indexBaselineLines = countIndexLines(indexText);
         handle.indexText = indexText;
         for (const [scope, dir] of scopeDirs) {
@@ -425,8 +437,9 @@ export class MemoryEngine {
     inject(handle, opts) {
         const writeChannel = handle.writeScope !== null && opts?.writeToolMounted !== false;
         const instruction = writeChannel ? buildMemoryInstruction(handle.writableRoot) : "";
+        const readOnlyNotice = handle.writeScope === null ? MEMORY_READONLY_NOTICE : undefined;
         const indexPath = join(handle.writableRoot, MEMORY_INDEX_FILENAME);
-        const onDisk = handle.indexOnDiskUntrusted === true ? undefined : readSafe(indexPath);
+        const onDisk = handle.indexOnDiskUntrusted === true || handle.adoptionRestricted === true ? undefined : readSafe(indexPath);
         const indexText = onDisk !== undefined && onDisk.trim() !== "" ? onDisk : handle.indexText;
         const truncated = truncateIndex(indexText);
         const index = composeMemoryBlock(truncated, handle.writeScope ?? handle.scopes[0] ?? "memory");
@@ -440,14 +453,17 @@ export class MemoryEngine {
             if (drained.queue.length > 0 || drained.folded > 0) {
                 announcements = drained.queue;
                 announceBlock = renderAnnouncements(drained.queue, drained.folded);
+                if (handle.writeScope === null)
+                    announceBlock = `${announceBlock}\n\n${MEMORY_ANNOUNCEMENT_READONLY_PLANE_CODA}`;
             }
         }
         catch (err) {
             this.discloseAnnounceFailure("inject drain", err);
         }
-        const block = [instruction, index, announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
+        const block = [instruction || readOnlyNotice, index, announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
         return {
             instruction,
+            ...(readOnlyNotice !== undefined ? { readOnlyNotice } : {}),
             ...(index !== undefined ? { index } : {}),
             ...(announcements !== undefined ? { announcements } : {}),
             ...(announceBlock !== undefined ? { announceBlock } : {}),
@@ -459,8 +475,14 @@ export class MemoryEngine {
         const root = handle.writableRoot;
         if (canonicalPath !== root && !canonicalPath.startsWith(`${root}${sep}`))
             return { ok: true };
-        if (handle.writeScope === null)
-            return { ok: true };
+        if (handle.writeScope === null) {
+            return {
+                ok: false,
+                code: "read_only_layering",
+                reason: "this session's memory is read-only (no write scope) — the engine does not accept writes into the memory domain. Nothing was written.",
+                muted: false,
+            };
+        }
         const findings = [];
         const nameFinding = scanMemoryFileName(relative(root, canonicalPath));
         if (nameFinding !== undefined)
@@ -512,10 +534,20 @@ export class MemoryEngine {
             warnings: [],
         };
         const writeScope = handle.writeScope;
-        if (writeScope === null) {
+        if (writeScope === null || opts?.admitNothing !== undefined) {
+            try {
+                this.backend.auditRestrictedDivergence?.([
+                    ...new Set([...handle.scopes, ...(writeScope !== null ? [writeScope] : [])]),
+                ]);
+            }
+            catch (err) {
+                report.warnings.push(`restricted-session divergence audit failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
             const roFindings = this.backend.drainInboundFindings?.();
             if (roFindings !== undefined && roFindings.length > 0)
                 report.inboundFindings = roFindings;
+            if (opts?.admitNothing !== undefined)
+                report.warnings.push(opts.admitNothing.reason);
             return report;
         }
         try {
@@ -1240,7 +1272,7 @@ export class MemoryEngine {
                 }
             }
             if (!landed)
-                writeFileSync(`${dest}.${process.pid}`, text, { encoding: "utf8", flag: "wx" });
+                writeFileSync(`${dest}.${process.pid}.${indexCaptureSeq++}`, text, { encoding: "utf8", flag: "wx" });
             captured = true;
         }
         catch (err) {

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;
@@ -142,8 +151,10 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
     private readScope;
     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 +173,81 @@ 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;
+    /**
+     * 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;
+     *  - `audit: false` (the retrieval-tool mount): a pure committed-view read — no findings, no
+     *    containment, no writes.
+     * WRITES ARE REFUSED loudly — same posture as {@link retrievalView}.
+     */
+    restrictedAdoptionView(opts?: {
+        audit?: boolean;
+    }): 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.
+     */
+    auditRestrictedDivergence(scopes: readonly 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

@@ -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)
@@ -288,27 +311,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 +319,7 @@ export class FileMemoryEngineBackend {
                             }
                             continue;
                         }
+                        entry = entryFromFile(shadowText, entry.id, f.slug, scope);
                     }
                     else {
                         if (committed !== undefined)
@@ -377,10 +381,13 @@ export class FileMemoryEngineBackend {
         return this.listHeadersWith(scopes, true);
     }
     listHeadersWith(scopes, adopt) {
+        return this.listHeadersFrom(scopes, (s) => this.readScope(s, adopt));
+    }
+    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 read(scope)) {
                 out.push(headerOf(e, join(dir, `${e.slug}.md`)));
             }
         }
@@ -390,10 +397,13 @@ export class FileMemoryEngineBackend {
         return this.getByIdsWith(ids, true);
     }
     getByIdsWith(ids, adopt) {
+        return this.getByIdsFrom(ids, (s) => this.readScope(s, adopt));
+    }
+    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 read(scope)) {
                 if (want.has(e.id))
                     out.push(e);
             }
@@ -413,10 +423,226 @@ export class FileMemoryEngineBackend {
             setConsolidationCursor: async () => refuse("setConsolidationCursor"),
         };
     }
+    restrictedFindingKeys = new Set();
+    recordRestrictedFinding(key, finding) {
+        if (this.restrictedFindingKeys.has(key))
+            return;
+        this.restrictedFindingKeys.add(key);
+        this.inboundFindings.push(finding);
+    }
+    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 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)
+                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",
+                    });
+                }
+            }
+        }
+        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;
+        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) {
+        for (const scope of scopes)
+            this.readScopeCommitted(scope, true);
+        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)]);
+            }
+        }
+        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);
     }
     searchWith(query, scopes, opts, adopt) {
+        return this.searchFrom(query, scopes, opts, (s) => this.readScope(s, adopt));
+    }
+    searchFrom(query, scopes, opts, read) {
         const limit = opts?.limit ?? 20;
         const q = termSet(query);
         if (q.size === 0)
@@ -424,7 +650,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 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/index.d.ts

@@ -1,4 +1,4 @@
-export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, type MemoryEngineOptions, type MemoryInjection, } from "./engine.js";
+export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, type MemoryEngineOptions, type MemoryInjection, } from "./engine.js";
 export { MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type MemoryGetDetails, } from "./tools.js";
 export { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
 export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH, type ScannedEntryFile } from "./file-backend.js";

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

@@ -1,4 +1,4 @@
-export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, } from "./engine.js";
+export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, } from "./engine.js";
 export { MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, } from "./tools.js";
 export { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
 export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH } from "./file-backend.js";

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

@@ -223,9 +223,16 @@ export interface MemorySessionHandle {
      *  the gate's whole purpose is keeping those bytes out of the prompt, so a refused clear must not
      *  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. */
+    adoptionRestricted?: boolean;
 }
 /** Stable rejection codes a harvest gate can produce (model-visible gate events — 镜头 I). */
-export type HarvestRejectionCode = "outside_root" | "symlink" | "secret" | "injection" | "filename" | "too_large" | "file_cap" | "readonly_layer" | "stub_modified" | "nested_too_deep" | "quarantine_failed" | "unreadable" | "polluted" | "invalid";
+export type HarvestRejectionCode = "outside_root" | "symlink" | "secret" | "injection" | "filename" | "too_large" | "file_cap" | "readonly_layer" | "stub_modified" | "nested_too_deep" | "quarantine_failed" | "unreadable" | "polluted" | "restricted_divergence" | "invalid";
 /** One rejected file: path (relative to the memory dir), stable code, and a model-readable reason. */
 export interface HarvestRejection {
     path: string;

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

@@ -13,7 +13,12 @@
  * MySQL is NOT "can't support vectors" — it is `portable`-capable (JSON column + in-process cosine), just not
  * `native`. A deployment injects an embedder (config-driven); the store then reports the achieved rung.
  */
-/** Lower-cased alphanumeric term set of a string (for the lexical stand-in distance). */
+/** Lower-cased lexical term set: alphanumeric runs PLUS CJK character bigrams (a single-character
+ *  run contributes its unigram). CJK scripts have no `a-z0-9` runs at all, so an alphanumeric-only
+ *  tokenizer made every pure-CJK entry an EMPTY set — never a lexical-rung candidate for any query
+ *  — and a pure-CJK query returned nothing; character bigrams are the standard analyzer unit there
+ *  (word boundaries are not written). Bigrams stay within one run: adjacency across an intervening
+ *  non-CJK character is not real adjacency. */
 export declare function termSet(s: string): Set<string>;
 /** Lexical stand-in distance: `1 - Jaccard(terms)` ∈ [0,1] ⊂ [0,2]; `null` = no overlap (not a candidate). */
 export declare function jaccardDistance(query: Set<string>, text: string): number | null;