dsh-prime-memory 0.22.1 → 0.24.0

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

@@ -0,0 +1,84 @@
+/**
+ * P3 归档面：退场批次被物理删除时，把它的人类可读归档正文与投射文件一起收进**快照目录**。
+ *
+ * 两个刻意的决定：
+ *
+ * ① **归档不另起目录树，就住在快照目录里**（`<dataDir>/snapshots/<name>/`）。计划里原本写
+ *    `<dataDir>/archives/<name>/`，但那样一次清理就有两个"批次"事实源（快照一份、归档一份），
+ *    名字对不上时没人能回答"这批到底删了什么"。住在一起之后：`manifest.json` 是库内容快照、
+ *    `retired.md` 是给人读的归档正文、`files/` 是搬进来的投射文件——同一个批次名寻址，
+ *    `snapshot-restore` 天然还能用得上。名字白名单也因此**直接继承** `isSnapshotName`
+ *    （长度上限 / 固定前缀 / 禁 `/ \ ..`），不需要再造一个 `isArchiveName`，更不吃调用方的绝对路径。
+ *
+ * ② **搬运在物理删除之后**，且失败只 warn。库删了是既成事实，文件留在原地是可修的不对称
+ *    （下一次导出会按 `retired` 把它们重写回去）；反过来先搬文件再删库，一旦删除中止就变成
+ *    "记录还活着、文件已经不见了"，那才是真的说不清。
+ */
+import type { MemoryLogger, MemoryRecord } from '../types.js';
+/** 归档正文文件名（人在归档目录里第一个该看见的东西）。 */
+export declare const ARCHIVE_MD = "retired.md";
+/** 投射文件在归档里的落点子目录。 */
+export declare const ARCHIVE_FILES_DIR = "files";
+/** 一次清理的归档元信息。 */
+export interface ArchiveMeta {
+    /** 批次原因（`cleanup-retired` / `pre-rebuild`）。 */
+    reason: string;
+    /** 归档时刻。 */
+    at: Date;
+    /** 操作者可选附的一句话（进正文头部，不参与任何判据）。 */
+    note?: string;
+}
+/** 一个磁盘上真实存在的投射文件（侧别在收集时就算好，搬运时不猜）。 */
+export interface ProjectionFile {
+    absPath: string;
+    /** 落在 workspace 根下（true）还是单根下（false）——N10 同一个 `targetFor` 的结论。 */
+    inWorkspace: boolean;
+}
+/** 记录 id → 该记录在磁盘上真实存在的投射文件（含 `.disable` 兄弟）。 */
+export type FilesByRecord = ReadonlyMap<string, ProjectionFile[]>;
+/** 归档搬运的结果（进清理响应，便于人核对"文件到底动没动"）。 */
+export interface ArchiveFileOutcome {
+    moved: number;
+    failed: number;
+    /** 该记录在磁盘上没有投射文件（没开过投射/从没导出过）。 */
+    absent: number;
+}
+/**
+ * 收集这批记录在磁盘上存在的投射文件。
+ *
+ * 只 `stat`，不读内容——归档要的是"把原物搬走"，不是"按当前库重渲染一份"。
+ *
+ * @param records - 待清理的记录（已退场那批）。
+ * @param cfgRoot - `cfg.memExport.root`。
+ * @param dataDir - 插件数据目录。
+ * @param logger - 宿主日志接口。
+ * @returns `recordId → 文件[]`；没有任何文件时返回**空 Map**（调用方据此走旧行为）。
+ */
+export declare function collectProjectionFiles(records: readonly MemoryRecord[], cfgRoot: string | undefined, dataDir: string, logger?: MemoryLogger): Promise<FilesByRecord>;
+/**
+ * 渲染归档正文：按 `type` 分片的单一 Markdown，每条一节。
+ *
+ * frontmatter 与投射文件同构（同一份 `renderRecord`），只往里插两行退场信息——这样
+ * "归档里读到的"和"当初磁盘上的"是同一个形状，人不需要在两套元数据格式之间换算。
+ */
+export declare function renderArchiveMarkdown(records: readonly MemoryRecord[], meta: ArchiveMeta): string;
+/**
+ * 写归档正文。失败**抛出**：正文是这批数据的唯一人可读物，写不成得让调用方知道
+ * （搬运失败则相反——那只影响便利度，不影响事实）。
+ */
+export declare function writeArchiveMarkdown(dir: string, records: readonly MemoryRecord[], meta: ArchiveMeta): Promise<string>;
+/**
+ * 把这批记录的投射文件搬进归档目录。
+ *
+ * 目标形状 `<归档根>/files/<ws|home>/<type>/<原文件名>`（自顶向下建目录）。失败只计数并
+ * 留痕——绝不因为文件搬不动而回滚库删除（不对称的方向是"文件可重生成，库删了不可逆"）。
+ *
+ * @param dir - 归档根（= 快照目录）。
+ * @param records - 该批记录（用 id 与 `files` 配对）。
+ * @param files - `collectProjectionFiles` 的产物。
+ * @param logger - 只需要 warn（清理侧的 logger 形状比 MemoryLogger 狭，这里不装宽）。
+ * @returns 搬运计数。
+ */
+export declare function moveProjectionFiles(dir: string, records: readonly MemoryRecord[], files: FilesByRecord, logger?: {
+    warn: (m: string) => void;
+}): Promise<ArchiveFileOutcome>;

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

@@ -0,0 +1,155 @@
+/**
+ * P3 归档面：退场批次被物理删除时，把它的人类可读归档正文与投射文件一起收进**快照目录**。
+ *
+ * 两个刻意的决定：
+ *
+ * ① **归档不另起目录树，就住在快照目录里**（`<dataDir>/snapshots/<name>/`）。计划里原本写
+ *    `<dataDir>/archives/<name>/`，但那样一次清理就有两个"批次"事实源（快照一份、归档一份），
+ *    名字对不上时没人能回答"这批到底删了什么"。住在一起之后：`manifest.json` 是库内容快照、
+ *    `retired.md` 是给人读的归档正文、`files/` 是搬进来的投射文件——同一个批次名寻址，
+ *    `snapshot-restore` 天然还能用得上。名字白名单也因此**直接继承** `isSnapshotName`
+ *    （长度上限 / 固定前缀 / 禁 `/ \ ..`），不需要再造一个 `isArchiveName`，更不吃调用方的绝对路径。
+ *
+ * ② **搬运在物理删除之后**，且失败只 warn。库删了是既成事实，文件留在原地是可修的不对称
+ *    （下一次导出会按 `retired` 把它们重写回去）；反过来先搬文件再删库，一旦删除中止就变成
+ *    "记录还活着、文件已经不见了"，那才是真的说不清。
+ */
+import { mkdir, rename, stat, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { disablePathOf, renderRecord, targetFor } from './memory-md.js';
+/** 归档正文文件名（人在归档目录里第一个该看见的东西）。 */
+export const ARCHIVE_MD = 'retired.md';
+/** 投射文件在归档里的落点子目录。 */
+export const ARCHIVE_FILES_DIR = 'files';
+/** 换行符（取字符码，避开任何转义写法）。 */
+const NL = String.fromCharCode(10);
+/**
+ * 收集这批记录在磁盘上存在的投射文件。
+ *
+ * 只 `stat`，不读内容——归档要的是"把原物搬走"，不是"按当前库重渲染一份"。
+ *
+ * @param records - 待清理的记录（已退场那批）。
+ * @param cfgRoot - `cfg.memExport.root`。
+ * @param dataDir - 插件数据目录。
+ * @param logger - 宿主日志接口。
+ * @returns `recordId → 文件[]`；没有任何文件时返回**空 Map**（调用方据此走旧行为）。
+ */
+export async function collectProjectionFiles(records, cfgRoot, dataDir, logger) {
+    const map = new Map();
+    for (const r of records) {
+        const target = targetFor(r, cfgRoot, dataDir, logger);
+        if (target.absPath === undefined)
+            continue;
+        // `.disable` 优先：退场记录在文件侧的标准形态就是它（N11）。两个都在就都搬。
+        const candidates = [
+            { absPath: disablePathOf(target.absPath), inWorkspace: target.inWorkspace },
+            { absPath: target.absPath, inWorkspace: target.inWorkspace },
+        ];
+        const found = [];
+        for (const c of candidates) {
+            try {
+                const st = await stat(c.absPath);
+                if (st.isFile())
+                    found.push(c);
+            }
+            catch {
+                // 没文件是常态（没开过投射、或这条从没导出过）：静默跳过，不刷日志
+            }
+        }
+        if (found.length > 0)
+            map.set(r.id, found);
+    }
+    return map;
+}
+/**
+ * 渲染归档正文：按 `type` 分片的单一 Markdown，每条一节。
+ *
+ * frontmatter 与投射文件同构（同一份 `renderRecord`），只往里插两行退场信息——这样
+ * "归档里读到的"和"当初磁盘上的"是同一个形状，人不需要在两套元数据格式之间换算。
+ */
+export function renderArchiveMarkdown(records, meta) {
+    const head = [
+        `# 退场记忆归档（${records.length} 条）`,
+        '',
+        `- 批次原因：${meta.reason}`,
+        `- 归档时刻：${meta.at.toISOString()}`,
+    ];
+    if (meta.note !== undefined && meta.note.trim().length > 0)
+        head.push(`- 备注：${meta.note.trim()}`);
+    head.push('');
+    const byType = new Map();
+    for (const r of records) {
+        const key = r.type.length > 0 ? r.type : 'unsorted';
+        const bucket = byType.get(key);
+        if (bucket === undefined)
+            byType.set(key, [r]);
+        else
+            bucket.push(r);
+    }
+    const sections = [];
+    for (const type of [...byType.keys()].sort()) {
+        const rows = [`## ${type}`, ''];
+        for (const r of byType.get(type) ?? []) {
+            const retiredAt = r.validTo === undefined ? meta.at.toISOString() : new Date(r.validTo).toISOString();
+            // 只往开栏后插两行，闭栏与正文一律不动：插进闭栏之后就成了正文的一部分。
+            // 这里刻意不用转义写法拼字符串（同一份产物里换行被展开过一次，正则字面量直接断法），
+            // 改成找第一个换行位置做切片——形状依赖的是文件真实结构，不是写法。
+            const { text } = renderRecord(r);
+            const at = text.indexOf(NL);
+            const extra = `retiredAt: ${JSON.stringify(retiredAt)}${NL}retireReason: ${JSON.stringify(meta.reason)}`;
+            rows.push(at < 0 ? text : `${text.slice(0, at)}${NL}${extra}${text.slice(at)}`);
+            rows.push('');
+        }
+        sections.push(rows.join('\n'));
+    }
+    return `${head.join('\n')}\n${sections.join('\n')}`;
+}
+/**
+ * 写归档正文。失败**抛出**：正文是这批数据的唯一人可读物，写不成得让调用方知道
+ * （搬运失败则相反——那只影响便利度，不影响事实）。
+ */
+export async function writeArchiveMarkdown(dir, records, meta) {
+    const path = join(dir, ARCHIVE_MD);
+    await mkdir(dir, { recursive: true });
+    await writeFile(path, renderArchiveMarkdown(records, meta), 'utf8');
+    return path;
+}
+/**
+ * 把这批记录的投射文件搬进归档目录。
+ *
+ * 目标形状 `<归档根>/files/<ws|home>/<type>/<原文件名>`（自顶向下建目录）。失败只计数并
+ * 留痕——绝不因为文件搬不动而回滚库删除（不对称的方向是"文件可重生成，库删了不可逆"）。
+ *
+ * @param dir - 归档根（= 快照目录）。
+ * @param records - 该批记录（用 id 与 `files` 配对）。
+ * @param files - `collectProjectionFiles` 的产物。
+ * @param logger - 只需要 warn（清理侧的 logger 形状比 MemoryLogger 狭，这里不装宽）。
+ * @returns 搬运计数。
+ */
+export async function moveProjectionFiles(dir, records, files, logger) {
+    const out = { moved: 0, failed: 0, absent: 0 };
+    if (files.size === 0)
+        return out;
+    for (const r of records) {
+        const entry = files.get(r.id);
+        if (entry === undefined) {
+            out.absent += 1;
+            continue;
+        }
+        const type = r.type.length > 0 ? r.type : 'unsorted';
+        for (const f of entry) {
+            const side = f.inWorkspace ? 'ws' : 'home';
+            const toDir = join(dir, ARCHIVE_FILES_DIR, side, type);
+            try {
+                await mkdir(toDir, { recursive: true });
+                await rename(f.absPath, join(toDir, basename(f.absPath)));
+                out.moved += 1;
+            }
+            catch (err) {
+                out.failed += 1;
+                logger?.warn(`[memory] 归档搬运失败（库已删，文件留在原地）: ${f.absPath} - ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1,23 @@
+import type { MdLedgerStore } from './memory-md-ledger.js';
+import type { MemoryLogger, MemoryRecord } from '../types.js';
+/** 文件侧的结果，原样进端点响应（面板看得见"到底动没动文件"）。 */
+export type DisableOutcome = 'renamed' | 'created' | 'already' | 'no-workspace' | 'failed';
+export interface DisableDeps {
+    /**
+     * 刚被退场的那条记录。调用方应传**退场后**的快照（带 `validTo`），这样渲染出的
+     * frontmatter 自然包含 `retired: true`——凭证自己就说清了它为什么存在。
+     */
+    record: MemoryRecord;
+    /** `cfg.memExport.root`（只管无 workspace 那批，这里用不到但落点函数要它）。 */
+    cfgRoot: string | undefined;
+    dataDir: string;
+    ledger: MdLedgerStore;
+    logger?: MemoryLogger;
+}
+/**
+ * 把一条已退场记忆的投射文件标成 `.disable`。
+ *
+ * @param deps - 记录、根配置、数据目录、账本与日志。
+ * @returns 文件侧结果；**任何异常都收敛成 `'failed'`，不抛**。
+ */
+export declare function disableProjectionFile(deps: DisableDeps): Promise<DisableOutcome>;

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

@@ -0,0 +1,106 @@
+/**
+ * 失效联动（N11 / P1.5）：人在 brief 上点「声明过时」时，除了退场库记录，还要动到投射文件。
+ *
+ * 为什么这件事在服务端而不是在 brief：brief 只是发一个 RPC，它既不知道记录住在哪个
+ * workspace，也不该拿到文件系统的写权限。**库是事实源，文件是投影**——所以退场先成立，
+ * 文件侧只是把"人已处置"这件事也写到磁盘上。
+ *
+ * 三种落点（用户口径）：
+ * - 有 workspace 且 `.memory.md` 存在 → **改名**成 `.memory.md.disable`；
+ * - 有 workspace 但文件还没导出过 → **创建** `.disable`（内容就是渲染结果，带 `retired: true`），
+ *   人不点导出也有一份磁盘凭证，P2 与人都看得见；
+ * - 没有 workspace → **什么都不写**。宁缺勿猜：为一个归属不明的记忆在单根凭空造文件，
+ *   等于把"没路由上"伪装成"它属于默认根"。
+ *
+ * 三条硬约束：
+ * 1. **绝不抛**：退场已经成功，文件侧失败不能把端点变成 500（那会让人以为标注没生效）。
+ * 2. **幂等**：`.disable` 已在就返回 `already`，再点一次 `-1` 不会长出第二个凭证。
+ * 3. **改名而不是删除**：`.disable` 是凭证，删了 P2 与人都无从对齐。
+ */
+import { dirname } from 'node:path';
+import { readFile, rename, stat } from 'node:fs/promises';
+import { atomicWriteText, ensureDir } from '../util/io.js';
+import { disablePathOf, digest, recordDigest, renderRecord, targetFor } from './memory-md.js';
+/** 存在性判定：一次 `stat`，任何错误都当"不存在"（权限/竞态都不该让失效动作失败）。 */
+async function exists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 账本跟着换键。
+ *
+ * 键是绝对路径（N10），所以改名必须"删旧键、记新键"——只改文件不改账本，下一轮对账
+ * 会同时报"旧键文件缺失"和"新文件是外人加的"，两边都错。
+ * 没有旧条目（人从没导出过）时只记新键，不补造旧键。
+ *
+ * ⚠️ `fileDigest` **取磁盘上的真实字节**，不取我们手上那份渲染结果：改名分支里
+ * 旧文件是“未退场时导出的那一版”（不带 `retired`），拿新渲染的摘要当基线，
+ * 下一轮对账就会把“我们自己改的文件”报成“人改过文件”。
+ */
+async function moveLedger(ledger, fromAbs, toAbs, r, fallbackText) {
+    const prev = ledger.get(fromAbs);
+    const st = await stat(toAbs).catch(() => undefined);
+    const actual = await readFile(toAbs, 'utf8').catch(() => fallbackText);
+    ledger.set(toAbs, {
+        id: r.id,
+        extKey: r.extKey ?? '',
+        root: prev?.root ?? '',
+        relPath: prev?.relPath ?? '',
+        dbDigest: recordDigest(r),
+        fileDigest: digest(actual),
+        fileMtimeMs: st?.mtimeMs ?? 0,
+        fileSize: st?.size ?? 0,
+        syncedAt: new Date().toISOString(),
+    });
+    if (prev !== undefined)
+        ledger.delete(fromAbs);
+    await ledger.flush();
+}
+/**
+ * 把一条已退场记忆的投射文件标成 `.disable`。
+ *
+ * @param deps - 记录、根配置、数据目录、账本与日志。
+ * @returns 文件侧结果；**任何异常都收敛成 `'failed'`，不抛**。
+ */
+export async function disableProjectionFile(deps) {
+    const { record: r, ledger, logger } = deps;
+    const ws = (r.workspaceId ?? '').trim();
+    if (ws.length === 0)
+        return 'no-workspace';
+    try {
+        const target = targetFor(r, deps.cfgRoot, deps.dataDir, logger);
+        const abs = target.absPath;
+        if (abs === undefined) {
+            logger?.warn(`[memory] 失效联动跳过（路径越界）: ${r.id} → ${target.relPath}`);
+            return 'failed';
+        }
+        const dis = disablePathOf(abs);
+        const { text } = renderRecord(r);
+        if (await exists(dis)) {
+            // 已经是 .disable：仍要确保账本认得它（上一轮可能改完文件就崩了）。
+            if (ledger.get(dis) === undefined)
+                await moveLedger(ledger, abs, dis, r, text);
+            return 'already';
+        }
+        if (await exists(abs)) {
+            await rename(abs, dis);
+            await moveLedger(ledger, abs, dis, r, text);
+            logger?.info(`[memory] 声明过时 → 投射文件已改名: ${dis}`);
+            return 'renamed';
+        }
+        await ensureDir(dirname(dis));
+        await atomicWriteText(dis, text);
+        await moveLedger(ledger, abs, dis, r, text);
+        logger?.info(`[memory] 声明过时 → 已创建失效凭证（此前未导出过）: ${dis}`);
+        return 'created';
+    }
+    catch (err) {
+        logger?.warn(`[memory] 失效联动文件侧失败（退场已完成，不回滚）: ${r.id} - ${err instanceof Error ? err.message : String(err)}`);
+        return 'failed';
+    }
+}

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

@@ -0,0 +1,50 @@
+import { safeJoin, resolveMemoriesRoot } from './memory-md.js';
+import type { MdLedgerStore } from './memory-md-ledger.js';
+import type { MemExportReport, MemExportResponse, ReconcileCounts, ReconcileReport, ReconcileSample } from './memory-md-types.js';
+import type { MemoryLogger, MemoryRecord } from '../types.js';
+export type { MemExportReport, MemExportResponse, ReconcileCounts, ReconcileReport, ReconcileSample };
+export { resolveMemoriesRoot, safeJoin };
+/** 导出报告等形状见 `memory-md-types.ts`（与契约层共用）。 */
+export interface MemExportDeps {
+    /** 待投射的记录（含退场行——退场也要有投影，否则文件树里看不到它）。 */
+    records: readonly MemoryRecord[];
+    /** `cfg.memExport.root`（空 = 默认单根）；workspace 优先时它只管无归属那批。 */
+    cfgRoot: string | undefined;
+    /** 插件数据目录：算默认单根用。 */
+    dataDir: string;
+    ledger: MdLedgerStore;
+    maxRecords: number;
+    timeBudgetMs: number;
+    logger?: MemoryLogger;
+    /** 注入时钟（测试用）。 */
+    now?: () => number;
+}
+/**
+ * 单向导出：库 → 文件 + 账本。
+ *
+ * 每次**全量重写**该写的：增量 patch 与内容指纹判据互相打脸（patch 的前提是"我知道
+ * 差在哪"，而那正是指纹要回答的）。指纹一致就跳过，不刷 mtime——刷了会让下一轮
+ * 对账把"我们没动过"误判成"文件被改过"。
+ */
+export declare function exportRecords(deps: MemExportDeps): Promise<MemExportReport>;
+/** 四态计数与报告形状见 `memory-md-types.ts`。 */
+export interface ReconcileDeps {
+    records: readonly MemoryRecord[];
+    /** `cfg.memExport.root`（空 = 默认单根）；与 `dataDir` 一起交给 `targetFor`。 */
+    cfgRoot: string | undefined;
+    dataDir: string;
+    ledger: MdLedgerStore;
+    maxRecords: number;
+    timeBudgetMs: number;
+    logger?: MemoryLogger;
+    sampleCap?: number;
+    now?: () => number;
+}
+/**
+ * 只读对账：按账本基线判每条记录落在哪个象限。
+ *
+ * 判据是**三方**的（基线 = 账本里的两个 digest）：
+ * `dbDigest ≠ 现在库内容` → 库动过；`fileDigest ≠ 现在文件内容` → 动过文件。
+ * 两方比较必吃一边，这就是账本要同时存两个 digest 的原因。
+ */
+export declare function reconcileLedger(deps: ReconcileDeps): Promise<ReconcileReport>;

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

@@ -0,0 +1,200 @@
+/**
+ * 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, 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;
+            }
+            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 };
+}