dsh-prime-memory 0.22.2 → 0.24.1

package/dist/store/memory-md-export.js

@@ -0,0 +1,227 @@
+/**
+ * md 投射的导出与对账（P1 / N1 + N9）。
+ *
+ * 两个函数共享同一套路径纪律，但**权限面完全不同**：
+ * - `exportRecords` 写文件、写账本，**一字不改库**（导出前后 `hashRecords` 必须相同，
+ *   用例钉住这条）；
+ * - `reconcileLedger` 什么都不写，只按账本与磁盘现状出四态报告——"看看差在哪"
+ *   不该需要高权限，`memoryMutate` 的门留给 P2 的真同步。
+ *
+ * 有界性照 `wing-backfill` / `workspace-relink` 的既有口径，但**配额数的是「动作」不是「遍历」**：
+ * `maxRecords` 只约束真碰了磁盘的条数（写入 / 补账 / 失败），判为「未变且已记账」的不吃配额。
+ * 原来的写法把未变也计入配额，于是**第二次点击扫的还是同一批前 N 条**，`remaining` 恒等于
+ * 同一个数——真机实测「已写 9 · 未变 291 · 剩余 866」点多少次都停在 300。扫描总量改由
+ * `timeBudgetMs` 兜底（只数条数不看时间，一条超大记录就能把一次点击挂死，这条理由不变），
+ * 剩余条数照旧如实回报 `remaining`。
+ */
+import { dirname } from 'node:path';
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { digest, disablePathOf, isRetiredRecord, recordDigest, renderRecord, safeJoin, targetFor, resolveMemoriesRoot } from './memory-md.js';
+// 路径纪律已收到 `memory-md.ts`（N10 后导出/对账/失效/归档四处共用）；这里再导一次
+// 只为不拆已有调用方（stats.ts 与用例都从本模块拿它们）。
+export { resolveMemoriesRoot, safeJoin };
+/** 让出事件循环一次：投射是长任务，不能独占 tick（面板会僵）。 */
+function tick() {
+    return new Promise((resolveTick) => { setImmediate(resolveTick); });
+}
+/**
+ * 单向导出：库 → 文件 + 账本。
+ *
+ * 每次**全量重写**该写的：增量 patch 与内容指纹判据互相打脸（patch 的前提是"我知道
+ * 差在哪"，而那正是指纹要回答的）。指纹一致就跳过，不刷 mtime——刷了会让下一轮
+ * 对账把"我们没动过"误判成"文件被改过"。
+ */
+export async function exportRecords(deps) {
+    const { records, cfgRoot, dataDir, ledger, logger } = deps;
+    const startedAt = (deps.now ?? Date.now)();
+    const root = resolveMemoriesRoot(cfgRoot, dataDir, logger);
+    const report = { root, inWorkspace: 0, scanned: 0, written: 0, unchanged: 0, skipped: 0, remaining: 0, capped: false };
+    // 吃配额的只有**碰过磁盘**的条数：写入、未变但补账、以及失败的那条（它已经碰过盘）。
+    let worked = 0;
+    for (let i = 0; i < records.length; i++) {
+        // 两条护栏都在**循环顶部**查：写在末尾会被 `continue` 跳过（自家测试抓过这个 bug）。
+        if (worked >= deps.maxRecords || (deps.now ?? Date.now)() - startedAt >= deps.timeBudgetMs) {
+            report.capped = true;
+            report.remaining = records.length - i;
+            break;
+        }
+        const r = records[i];
+        // 防御：`records` 来自 `store.all()`，类型上是满的，但 noUncheckedIndexedAccess
+        // 下的 client 程序会把它当 `| undefined`——这里不猜，直接跳过。
+        if (r === undefined) {
+            report.skipped++;
+            continue;
+        }
+        report.scanned++;
+        // N10：落点由 `targetFor` 一个函数定（workspace 优先），账本键 = 绝对路径。
+        const target = targetFor(r, cfgRoot, dataDir, logger);
+        if (target.absPath === undefined) {
+            report.skipped++;
+            logger?.warn(`[memory] md 投射跳过（路径越界）: ${r.id} → ${target.relPath}`);
+            continue;
+        }
+        const { text } = renderRecord(r);
+        const abs = target.absPath;
+        if (target.inWorkspace)
+            report.inWorkspace++;
+        const dbDg = recordDigest(r);
+        const fileDg = digest(text);
+        try {
+            const existing = await readFile(abs, 'utf8').catch(() => undefined);
+            if (existing !== undefined && digest(existing) === fileDg) {
+                report.unchanged++;
+                // 内容没变也要补账：首轮导出前账本是空的，不补就永远判不出"文件被改过"。
+                // 补账要吃配额（它写盘），纯未变不吃——否则「再点一次」永远在同一批上打转。
+                if (ledger.get(abs) === undefined) {
+                    try {
+                        await stamp(ledger, r, target.root, target.relPath, abs, dbDg, fileDg);
+                        worked++;
+                    }
+                    catch (err) {
+                        // 文件与库都没动，只是没记上账：不能算 skipped（它没失败），也不能反回退成未计。
+                        logger?.warn(`[memory] md 投射补账失败(下轮仍会重补): ${abs} - ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+                await tick();
+                continue;
+            }
+            // 退场记录的投射可能已经在 `.disable` 上（后缀不变式，见 `memory-md-disable.ts`）。
+            // 这时“非退场路径上没文件”**不等于**“从没导出过”：拿 `.disable` 那份比指纹，
+            // 一致就记未变。不拦这个的话，每轮导出都会把刚改完名的文件写回非退场路径，
+            // 收敛再改一次名——两轮之间来回倒腾，`written` 永远不归零。
+            if (existing === undefined && isRetiredRecord(r)) {
+                const dis = disablePathOf(abs);
+                const disText = await readFile(dis, 'utf8').catch(() => undefined);
+                // 两种形状都得认（都是合法盘态）：
+                // · 先导出后退场 → 改名分支不重写内容，盘上是 live 渲染（既有用例钉着）；
+                // · 生下来就退场、首次导出就是那份 → 盘上是带 `retired: true` 的当前渲染。
+                // 拿其中任一份对上就记未变；都对不上（正文被改过）才落到下面重写，由收敛再改名。
+                const liveDg = digest(renderRecord({ ...r, validTo: undefined }).text);
+                if (disText !== undefined && (digest(disText) === liveDg || digest(disText) === fileDg)) {
+                    report.unchanged++;
+                    if (ledger.get(dis) === undefined) {
+                        try {
+                            await stamp(ledger, r, target.root, target.relPath, dis, dbDg, digest(disText));
+                            worked++;
+                        }
+                        catch (err) {
+                            logger?.warn(`[memory] md 投射退场凭证补账失败(下轮仍会重补): ${dis} - ${err instanceof Error ? err.message : String(err)}`);
+                        }
+                    }
+                    await tick();
+                    continue;
+                }
+            }
+            await mkdir(dirname(abs), { recursive: true });
+            await writeFile(abs, text, 'utf8');
+            report.written++;
+            worked++;
+            // 盘已经写成功了，之后记账失败**不能再算成 skipped**：同一条既 written 又 skipped
+            // 会让三个计数加起来大于 scanned（自家基准测出 1200 条同时报「写 1200 跳 1200」），
+            // 而报告是给人判断「这批要不要重来」的依据，自洽性比分类精细更要紧。
+            try {
+                await stamp(ledger, r, target.root, target.relPath, abs, dbDg, fileDg);
+            }
+            catch (err) {
+                logger?.warn(`[memory] md 投射已落盘但记账失败(下轮仍会重写这条): ${abs} - ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        catch (err) {
+            report.skipped++;
+            worked++;
+            logger?.warn(`[memory] md 投射单条失败(跳过，不影响其余): ${abs} - ${err instanceof Error ? err.message : String(err)}`);
+        }
+        await tick();
+    }
+    await ledger.flush();
+    return report;
+}
+/** 写账：文件侧字段取**落盘后**的真实 stat，不取内存值（否则对账基线就是假的）。 */
+async function stamp(ledger, r, root, relPath, absPath, dbDg, fileDg) {
+    const st = await stat(absPath).catch(() => undefined);
+    const entry = {
+        id: r.id,
+        extKey: r.extKey ?? '',
+        root,
+        relPath,
+        dbDigest: dbDg,
+        fileDigest: fileDg,
+        fileMtimeMs: st?.mtimeMs ?? 0,
+        fileSize: st?.size ?? 0,
+        syncedAt: new Date().toISOString(),
+    };
+    ledger.set(absPath, entry);
+}
+/**
+ * 只读对账：按账本基线判每条记录落在哪个象限。
+ *
+ * 判据是**三方**的（基线 = 账本里的两个 digest）：
+ * `dbDigest ≠ 现在库内容` → 库动过；`fileDigest ≠ 现在文件内容` → 动过文件。
+ * 两方比较必吃一边，这就是账本要同时存两个 digest 的原因。
+ */
+export async function reconcileLedger(deps) {
+    const { records, cfgRoot, dataDir, ledger, logger } = deps;
+    const startedAt = (deps.now ?? Date.now)();
+    const root = resolveMemoriesRoot(cfgRoot, dataDir, logger);
+    const counts = { firstTime: 0, same: 0, dbOnly: 0, fileOnly: 0, both: 0, missingFile: 0 };
+    const samples = [];
+    const sampleCap = deps.sampleCap ?? 10;
+    let scanned = 0;
+    // 与导出同口径：`maxRecords` 数的是**需要人处理差异**的条数，`same` 不吃配额。
+    // 否则一个已经收敛的库会把配额全花在“确认没差”上，真正要看的差异反而被护到窗外。
+    let worked = 0;
+    let capped = false;
+    for (let i = 0; i < records.length; i++) {
+        if (worked >= deps.maxRecords || (deps.now ?? Date.now)() - startedAt >= deps.timeBudgetMs) {
+            capped = true;
+            break;
+        }
+        const r = records[i];
+        scanned++;
+        if (r === undefined)
+            continue;
+        // 与导出同一个 `targetFor`：否则“库侧算出的落点”与“导出时写的落点”会不一致，
+        // 对账就只会报“文件缺失”。
+        const target = targetFor(r, cfgRoot, dataDir, logger);
+        const abs = target.absPath;
+        const entry = abs === undefined ? undefined : ledger.get(abs);
+        const push = (state) => {
+            counts[state]++;
+            if (state !== 'same')
+                worked++;
+            if (samples.length < sampleCap)
+                samples.push({ relPath: target.relPath, id: r.id, state });
+        };
+        if (abs === undefined) {
+            push('missingFile');
+            logger?.warn(`[memory] 对账遇到越界路径: ${target.relPath}`);
+            await tick();
+            continue;
+        }
+        if (entry === undefined) {
+            push('firstTime');
+            await tick();
+            continue;
+        }
+        const existing = await readFile(abs, 'utf8').catch(() => undefined);
+        if (existing === undefined) {
+            push('missingFile');
+            await tick();
+            continue;
+        }
+        // 两个“变了”都是**相对账本基线**判的，不能拿“与现在会渲染出的文本不同”当依据：
+        // 库一变渲染就变，那会把纯粹的 dbOnly 误判成“文件也被人改了”，象限表全盘跑偏。
+        const dbChanged = entry.dbDigest !== recordDigest(r);
+        const fileChanged = digest(existing) !== entry.fileDigest;
+        if (dbChanged && fileChanged)
+            push('both');
+        else if (dbChanged)
+            push('dbOnly');
+        else if (fileChanged)
+            push('fileOnly');
+        else
+            push('same');
+        await tick();
+    }
+    return { root, capped, scanned, ...counts, samples };
+}

package/dist/store/memory-md-ledger.d.ts

@@ -0,0 +1,94 @@
+import type { MemoryLogger } from '../types.js';
+/** 看起来就是绝对路径（Windows 盘符形状或 POSIX 以 `/` 开头）。归档侧也要用它挡坏数据。 */
+export declare function looksAbsolute(p: string): boolean;
+/**
+ * 由「绝对键 + 条目记的 root」推出相对形状（正斜杠）。
+ *
+ * 这是 relPath 的唯一正确算法：键才是事实源（N10 以后它是绝对路径），root 只是
+ * 其中一个字段。`root` 缺失、键不在 root 下、或推出 `..` 开头都返回 `undefined`——不猜。
+ *
+ * @param root - 投射根（绝对）。
+ * @param key - 账本键 = 文件绝对路径。
+ * @returns `<类型>/<名>` 的相对形状，推不出时 `undefined`。
+ */
+export declare function deriveRelPath(root: string, key: string): string | undefined;
+/** 一条投射记录的指纹账。`db*` 是库侧、`file*` 是磁盘侧，两边成对才能判象限。 */
+export interface MdLedgerEntry {
+    /** 记录 id（写入时刻的那一个；merge 后可能变，故只当线索不当键）。 */
+    id: string;
+    /** 外部导入幂等键（有则可用于跨 id 认人）。 */
+    extKey: string;
+    /** 投射根（workspace 根或单根），绝对路径。 */
+    root: string;
+    /** 相对根的路径（正斜杠），展示与归档分目录用。 */
+    relPath: string;
+    /** 上次投射时**库侧**的内容指纹。 */
+    dbDigest: string;
+    /** 上次投射时**文件侧**的内容指纹。 */
+    fileDigest: string;
+    fileMtimeMs: number;
+    fileSize: number;
+    /** 写入时刻（ISO）。只作展示，不参与任何判据——参与就会让渲染不纯。 */
+    syncedAt: string;
+}
+export declare class MdLedgerStore {
+    private readonly logger?;
+    private readonly file;
+    private entries;
+    private loaded;
+    private degraded;
+    private degradedLogged;
+    private writeChain;
+    /** 有未落盘的变更。 */
+    private dirty;
+    /** 已提醒过的 relPath 修正数（防上千条条目刷屏）。 */
+    private mismatchWarned;
+    /** 已发生的整本落盘次数（见 `writeCount`）。 */
+    private writes;
+    /** 已排上的合批定时器（undefined = 窗口外）。 */
+    private timer;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    init(): Promise<void>;
+    /** 逐条收窄：形状不符的条目丢弃，不让一条坏数据拖垮整表。 */
+    private normalize;
+    private ensureLoaded;
+    get(absPath: string): MdLedgerEntry | undefined;
+    all(): MdLedgerEntry[];
+    /**
+     * 带键遍历：**账本的键（绝对路径）是唯一认身份的口径**，而 `all()` 把它抹掉了。
+     *
+     * 为什么需要这个口：孤儿扫描要回答“这个**路径**现在还有没有记录认领”，而条目里的
+     * `root`/`relPath` 只是归档时恢复相对形状用的——手工编辑过账本时两者可以不一致，
+     * 拿它们当路径就会把“键”与“内容”两套事实源弄混。只读，不暴露可变 Map。
+     */
+    allWithKeys(): Array<{
+        path: string;
+        entry: MdLedgerEntry;
+    }>;
+    set(absPath: string, entry: MdLedgerEntry): void;
+    delete(absPath: string): boolean;
+    /** 条目上限护栏：投射是"文件 ↔ 库"的一一对应，超量只可能是脏数据堆积。 */
+    private prune;
+    private schedulePersist;
+    /** 串行落盘：并发 set 不能交叠写同一个临时文件。 */
+    private enqueuePersist;
+    private persistNow;
+    /**
+     * 已发生的整本落盘次数。
+     *
+     * 留着它是因为这个类的性能形状就是它的全部意义：账本每次落盘都重写整本 JSON，
+     * 所以「这个数是不是跟 `set()` 次数一起涨」直接就能区分 O(n) 与 O(n²)。合批前 200 次
+     * `set()` 会落盘 200 次；合批后应该恒为 1。没这个计数器就只能靠时间差或磁盘状态去猜，
+     * 那种断言在旧实现上也能绿（自家刚踩过）。
+     */
+    get writeCount(): number;
+    private persist;
+    /**
+     * 等待在途写完成（测试/停机/导出收尾）。
+     *
+     * 合批之后这一步是**语义上的“现在就要落盘”**：清掉定时器并强制一次写，所以写完
+     * `set()` 不 `flush()` 就不能假设磁盘已经可信。`persistNow` 自带脏位判定，
+     * 没变更时不会空写一轮。
+     */
+    flush(): Promise<void>;
+}

package/dist/store/memory-md-ledger.js

@@ -0,0 +1,243 @@
+/**
+ * md 投射的指纹账本（N9）。
+ *
+ * 它存在的唯一理由：**库里没有任何 hash 列**（spec F26），三处现成 hash 又全不落库
+ * （F27：快照是整集粗粒度、memport 每次现算、reconcile 只活在状态文件里）。没有这张
+ * 账本就无从回答"这个文件是被人改的，还是被我们上次写出去的"——而那是双向同步的
+ * 全部难点：两方比较必吃一边。
+ *
+ * 三条口径：
+ * - **键是文件的绝对路径**（N10 后根不止一个：workspace 根 + 单根，同名不同 workspace 会
+ *   在 relPath 上撞车）。绝对路径由 `targetFor` 一函数算出，读写对账改名四处共用，
+ *   所以键是确定性的（Windows 下 `workspace_id` 是小写形态，这一点已写进 `memory-md.ts`）。
+ * - **派生态**：删了这张表最坏是"下次全量重写一遍文件"，不会丢任何记忆。所以它
+ *   **不进**快照哈希投影（`canonicalRecords` 不动），也不需要迁移。
+ * - **写穿失败只降级为只读并 warn 一次**，绝不抛给调用方：投射是旁路，旁路不能弄挂主路。
+ */
+import { basename, dirname, join, relative, sep } from 'node:path';
+import { atomicWriteText, ensureDir, readJsonStrict } from '../util/io.js';
+import { MEM_MD_LEDGER_FILE_VERSION } from './file-versions.js';
+/** 看起来就是绝对路径（Windows 盘符形状或 POSIX 以 `/` 开头）。归档侧也要用它挡坏数据。 */
+export function looksAbsolute(p) {
+    return /^[A-Za-z]:[\\/]/.test(p) || p.startsWith('/');
+}
+/**
+ * 由「绝对键 + 条目记的 root」推出相对形状（正斜杠）。
+ *
+ * 这是 relPath 的唯一正确算法：键才是事实源（N10 以后它是绝对路径），root 只是
+ * 其中一个字段。`root` 缺失、键不在 root 下、或推出 `..` 开头都返回 `undefined`——不猜。
+ *
+ * @param root - 投射根（绝对）。
+ * @param key - 账本键 = 文件绝对路径。
+ * @returns `<类型>/<名>` 的相对形状，推不出时 `undefined`。
+ */
+export function deriveRelPath(root, key) {
+    if (root.length === 0 || looksAbsolute(key) === false)
+        return undefined;
+    const rel = relative(root, key);
+    if (rel.length === 0 || rel.startsWith('..'))
+        return undefined;
+    return rel.split(sep).join('/');
+}
+/**
+ * 合批窗口(ms)。
+ *
+ * 账本是**整本 JSON 的原子重写**（临时文件 + rename），所以“每 set 一条就落盘”把导出
+ * 成本变成 O(n²)：本机实测 1200 条记录 9.4 秒，其中只碰文件面只需 1.6 秒。改为窗口内
+ * 只记脏、由 `flush()` 收尾落一次，1200 次 set 就是一次落盘。
+ * 窗口只是**兜底**：三个写方（导出 / 失效 / 同步）本来就在收尾 `await flush()`。
+ */
+const PERSIST_COALESCE_MS = 250;
+export class MdLedgerStore {
+    logger;
+    file;
+    entries = new Map();
+    loaded = false;
+    degraded;
+    degradedLogged = false;
+    writeChain = Promise.resolve();
+    /** 有未落盘的变更。 */
+    dirty = false;
+    /** 已提醒过的 relPath 修正数（防上千条条目刷屏）。 */
+    mismatchWarned = 0;
+    /** 已发生的整本落盘次数（见 `writeCount`）。 */
+    writes = 0;
+    /** 已排上的合批定时器（undefined = 窗口外）。 */
+    timer;
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = join(dataDir, 'mem-md-ledger.json');
+    }
+    async init() {
+        await ensureDir(dirname(this.file));
+        const read = await readJsonStrict(this.file);
+        if (!read.ok) {
+            if (read.reason !== 'missing') {
+                this.degraded = `${read.reason}${'detail' in read && read.detail ? `: ${read.detail}` : ''}`;
+                this.logger?.warn(`[memory] md 投射账本只读降级: ${this.degraded}`);
+            }
+            this.loaded = true;
+            return;
+        }
+        for (const [key, e] of Object.entries(read.value.entries ?? {})) {
+            const parsed = this.normalize(e);
+            if (parsed === undefined)
+                continue;
+            // 键是**绝对路径**（N10），relPath 是 `<类型>/<名>` 的相对形状——两者本来就不该相等。
+            // 旧写法是“键与 relPath 不一致就以键为准重写”，那是键还叫 relPath 时代的逻辑；
+            // N10 之后它每次加载都必然判定不一致，于是相对形状被绝对键吃掉（真机 1167/1241 条命中）。
+            // 危害不是难看而是下游：孤儿归档拼出 `<批次>/home/C:\Users\...` 这种含冒号的非法
+            // 目录，75 条搬家全 ENOENT。现在规整判据换成“键 == join(root, relPath)”：
+            // 只有真推不出相对形状（root 缺失/越界）才退回存下来的值。
+            const derived = deriveRelPath(parsed.root, key);
+            let relPath = derived ?? parsed.relPath;
+            if (looksAbsolute(relPath)) {
+                // 坏数据兼容：以前被绝对键污染过的条目，若 root 也推不出来，退到文件名——
+                // 至少归档不会拼出带冒号的非法路径。名字重复由 freeSlot 的数字尾巴兼着。
+                relPath = basename(relPath);
+            }
+            if (relPath !== parsed.relPath && this.mismatchWarned < 8) {
+                this.mismatchWarned++;
+                this.logger?.warn(`[memory] md 账本 relPath 已按键修正: ${key} → ${relPath}`);
+            }
+            this.entries.set(key, { ...parsed, relPath });
+        }
+        this.loaded = true;
+    }
+    /** 逐条收窄：形状不符的条目丢弃，不让一条坏数据拖垮整表。 */
+    normalize(e) {
+        if (!e || typeof e !== 'object')
+            return undefined;
+        const raw = e;
+        if (typeof raw.relPath !== 'string' || raw.relPath.length === 0)
+            return undefined;
+        if (typeof raw.dbDigest !== 'string' || typeof raw.fileDigest !== 'string')
+            return undefined;
+        return {
+            id: typeof raw.id === 'string' ? raw.id : '',
+            extKey: typeof raw.extKey === 'string' ? raw.extKey : '',
+            root: typeof raw.root === 'string' ? raw.root : '',
+            relPath: raw.relPath,
+            dbDigest: raw.dbDigest,
+            fileDigest: raw.fileDigest,
+            fileMtimeMs: typeof raw.fileMtimeMs === 'number' ? raw.fileMtimeMs : 0,
+            fileSize: typeof raw.fileSize === 'number' ? raw.fileSize : 0,
+            syncedAt: typeof raw.syncedAt === 'string' ? raw.syncedAt : '',
+        };
+    }
+    ensureLoaded() {
+        if (!this.loaded)
+            throw new Error('md 投射账本未初始化(先 await init())');
+    }
+    get(absPath) {
+        this.ensureLoaded();
+        return this.entries.get(absPath);
+    }
+    all() {
+        this.ensureLoaded();
+        return [...this.entries.values()];
+    }
+    /**
+     * 带键遍历：**账本的键（绝对路径）是唯一认身份的口径**，而 `all()` 把它抹掉了。
+     *
+     * 为什么需要这个口：孤儿扫描要回答“这个**路径**现在还有没有记录认领”，而条目里的
+     * `root`/`relPath` 只是归档时恢复相对形状用的——手工编辑过账本时两者可以不一致，
+     * 拿它们当路径就会把“键”与“内容”两套事实源弄混。只读，不暴露可变 Map。
+     */
+    allWithKeys() {
+        this.ensureLoaded();
+        return [...this.entries.entries()].map(([path, entry]) => ({ path, entry }));
+    }
+    set(absPath, entry) {
+        this.ensureLoaded();
+        this.entries.set(absPath, entry);
+        this.schedulePersist();
+    }
+    delete(absPath) {
+        this.ensureLoaded();
+        if (!this.entries.delete(absPath))
+            return false;
+        this.schedulePersist();
+        return true;
+    }
+    /** 条目上限护栏：投射是"文件 ↔ 库"的一一对应，超量只可能是脏数据堆积。 */
+    prune() {
+        const MAX = 50_000;
+        if (this.entries.size <= MAX)
+            return;
+        const sorted = [...this.entries.entries()].sort((a, b) => (a[1].syncedAt < b[1].syncedAt ? -1 : 1));
+        for (const [rel] of sorted.slice(0, this.entries.size - MAX))
+            this.entries.delete(rel);
+    }
+    schedulePersist() {
+        if (this.degraded)
+            return;
+        this.dirty = true;
+        // 已在窗口内就不再排：一个 burst 只留一次落盘。
+        if (this.timer !== undefined)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            void this.enqueuePersist();
+        }, PERSIST_COALESCE_MS);
+        // 不让一个兜底定时器拖住进程退出（宿主常驻时无影响，测试收尾时干净）。
+        this.timer.unref?.();
+    }
+    /** 串行落盘：并发 set 不能交叠写同一个临时文件。 */
+    enqueuePersist() {
+        this.writeChain = this.writeChain.then(() => this.persistNow(), () => this.persistNow());
+        return this.writeChain;
+    }
+    async persistNow() {
+        if (!this.dirty || this.degraded)
+            return;
+        this.dirty = false;
+        this.writes += 1;
+        await this.persist();
+    }
+    /**
+     * 已发生的整本落盘次数。
+     *
+     * 留着它是因为这个类的性能形状就是它的全部意义：账本每次落盘都重写整本 JSON，
+     * 所以「这个数是不是跟 `set()` 次数一起涨」直接就能区分 O(n) 与 O(n²)。合批前 200 次
+     * `set()` 会落盘 200 次；合批后应该恒为 1。没这个计数器就只能靠时间差或磁盘状态去猜，
+     * 那种断言在旧实现上也能绿（自家刚踩过）。
+     */
+    get writeCount() {
+        return this.writes;
+    }
+    async persist() {
+        if (this.degraded)
+            return;
+        this.prune();
+        const data = {
+            version: MEM_MD_LEDGER_FILE_VERSION,
+            entries: Object.fromEntries(this.entries),
+        };
+        try {
+            await ensureDir(dirname(this.file));
+            await atomicWriteText(this.file, JSON.stringify(data, null, 2));
+        }
+        catch (err) {
+            this.degraded = err instanceof Error ? err.message : String(err);
+            if (!this.degradedLogged) {
+                this.degradedLogged = true;
+                this.logger?.warn(`[memory] md 投射账本写入失败，只读降级: ${this.degraded}`);
+            }
+        }
+    }
+    /**
+     * 等待在途写完成（测试/停机/导出收尾）。
+     *
+     * 合批之后这一步是**语义上的“现在就要落盘”**：清掉定时器并强制一次写，所以写完
+     * `set()` 不 `flush()` 就不能假设磁盘已经可信。`persistNow` 自带脏位判定，
+     * 没变更时不会空写一轮。
+     */
+    flush() {
+        if (this.timer !== undefined) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        return this.enqueuePersist();
+    }
+}

package/dist/store/memory-md-orphan.d.ts

@@ -0,0 +1,27 @@
+import { type MdLedgerStore } from './memory-md-ledger.js';
+import type { MemoryLogger, MemoryRecord } from '../types.js';
+import type { OrphanReport } from './memory-md-types.js';
+export interface OrphanDeps {
+    /** 当前全部记录（含退场行——退场行仍认领自己的文件，那不是孤儿）。 */
+    records: readonly MemoryRecord[];
+    /** `cfg.memExport.root`（空 = 默认单根）。 */
+    cfgRoot: string | undefined;
+    dataDir: string;
+    ledger: MdLedgerStore;
+    /** true = 只报告不搬（默认值由端点侧兜死，这里不设默认）。 */
+    dryRun: boolean;
+    maxFiles: number;
+    timeBudgetMs: number;
+    logger?: MemoryLogger;
+    /** 归档根；缺省 `<dataDir>/memories-orphans`。测试注入临时目录用。 */
+    archiveRoot?: string;
+    /** 注入时钟（测试用）。 */
+    now?: () => number;
+}
+/**
+ * 扫一遍账本，把无人认领的投射文件搬进归档目录。
+ *
+ * @param deps - 见 `OrphanDeps`。
+ * @returns 报告；`dir` 在干跑时是空串（还没建批次目录）。任何单条失败只计数并留痕，绝不抛挂整轮。
+ */
+export declare function sweepOrphanFiles(deps: OrphanDeps): Promise<OrphanReport>;