dsh-prime-memory 0.22.2 → 0.24.1

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,74 @@
+import { isRetiredRecord } from './memory-md.js';
+import type { SuffixReport } from './memory-md-types.js';
+import type { MdLedgerStore } from './memory-md-ledger.js';
+import type { MemoryLogger, MemoryRecord } from '../types.js';
+/** 文件侧的结果，原样进端点响应（面板看得见"到底动没动文件"）。 */
+export type DisableOutcome = 'renamed' | 'created' | 'already' | 'no-workspace' | 'failed';
+/**
+ * 退场判据的单一真源在 `memory-md.ts`（导出侧与这里必须共用一个），本模块只转发，
+ * 免得既有调用方拿不到。另起一套（比如再叠上 `persistence`）只会让"列表说它退了、
+ * 文件却没后缀"重新变成常态。
+ */
+export { isRetiredRecord };
+export interface DisableDeps {
+    /**
+     * 刚被退场的那条记录。调用方应传**退场后**的快照（带 `validTo`），这样渲染出的
+     * frontmatter 自然包含 `retired: true`——凭证自己就说清了它为什么存在。
+     */
+    record: MemoryRecord;
+    /** `cfg.memExport.root`（只管无 workspace 那批，这里用不到但落点函数要它）。 */
+    cfgRoot: string | undefined;
+    dataDir: string;
+    ledger: MdLedgerStore;
+    logger?: MemoryLogger;
+}
+/**
+ * 账本跟着换键。
+ *
+ * 键是绝对路径（N10），所以改名必须"删旧键、记新键"——只改文件不改账本，下一轮对账
+ * 会同时报"旧键文件缺失"和"新文件是外人加的"，两边都错。
+ * 没有旧条目（人从没导出过）时只记新键，不补造旧键。
+ *
+ * ⚠️ `fileDigest` **取磁盘上的真实字节**，不取我们手上那份渲染结果：改名分支里
+ * 旧文件是“未退场时导出的那一版”（不带 `retired`），拿新渲染的摘要当基线，
+ * 下一轮对账就会把“我们自己改的文件”报成“人改过文件”。
+ *
+ * @param persist - 默认 true（单条失效联动：写完就该落盘）。**批量收敛必须传 false**：
+ * 账本是整本 JSON 的原子重写，每条都 `flush()` 就把「窗口内只记脏、收尾落一次」
+ * 的设计退化成 O(n²)（真机 912 条回填会被墙钟 `timeBudgetMs` 拦成好几次点击）。
+ *
+ * 导出给 `memory-md-sync.ts` 的改名跟随用——「取磁盘真实字节当基线」这条纪律只该有一份。
+ */
+export declare function moveLedger(ledger: MdLedgerStore, fromAbs: string, toAbs: string, r: MemoryRecord, fallbackText: string, persist?: boolean): Promise<void>;
+/**
+ * 把一条已退场记忆的投射文件标成 `.disable`。
+ *
+ * @param deps - 记录、根配置、数据目录、账本与日志。
+ * @returns 文件侧结果；**任何异常都收敛成 `'failed'`，不抛**。
+ */
+export declare function disableProjectionFile(deps: DisableDeps): Promise<DisableOutcome>;
+export interface SuffixConvergeDeps {
+    /** 全量记录（含退场的）——收敛是库→盘的形状对齐，不是增量事件。 */
+    records: readonly MemoryRecord[];
+    cfgRoot: string | undefined;
+    dataDir: string;
+    ledger: MdLedgerStore;
+    /** 与 `exportRecords` 同口径：只约束**真碰了磁盘**的动作数，判为“形状已对”的不吃配额。 */
+    maxRecords: number;
+    timeBudgetMs: number;
+    logger?: MemoryLogger;
+    /** 注入时钟（测试用）。 */
+    now?: () => number;
+}
+/**
+ * 后缀不变式收敛：把「库里的有/无效」与「文件的 `.memory.md` / `.memory.md.disable`」对齐。
+ *
+ * 为什么挂在导出后面而不是各个退场调用点：那 8 处 `.retire()` 分布在手动软删、批量退场、
+ * 合并取代、冲突判负、slot 连带等路径上，事件挂钩注定会漏（真机实测：920 条退场记录
+ * 只有 8 个 `.disable`，全部来自召回面板那一条路径）。收敛器只依赖三个可观测事实：
+ * 文件存在性、当前后缀、指纹一致性。
+ *
+ * 护栏与导出同一套（`maxRecords` 只数碰盘动作 + `timeBudgetMs` 墙钟），所以第一次点可能只
+ * 收敛一部分，`capped`/`remaining` 会告诉你还要点几次。
+ */
+export declare function convergeDisabledSuffix(deps: SuffixConvergeDeps): Promise<SuffixReport>;

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

@@ -0,0 +1,302 @@
+/**
+ * 失效联动（N11 / P1.5）：人在 brief 上点「声明过时」时，除了退场库记录，还要动到投射文件。
+ *
+ * 为什么这件事在服务端而不是在 brief：brief 只是发一个 RPC，它既不知道记录住在哪个
+ * workspace，也不该拿到文件系统的写权限。**库是事实源，文件是投影**——所以退场先成立，
+ * 文件侧只是把"人已处置"这件事也写到磁盘上。
+ *
+ * 后缀不变式（作者口径 2026-10-14）：文件后缀**只跟「这条记录在库里是否有效」有关**，
+ * `name` 字段无感，「是谁把它退场的」也无感。所以不能只在一个退场按钮后面挂一刀——
+ * 全仓有 8 处 `.retire()` 调用点（手动判过时 / 批量软删 / 合并取代 / 冲突判负 / slot 连带…），
+ * 事件挂钩注定会漏。`convergeDisabledSuffix` 就是这个不变式的收敛器：每次导出后按
+ * 「文件存在性 + 当前后缀 + 指纹一致性」三项检查重算一遍，与退场路径无关。
+ *
+ * 点火已由 `L1Store` 的汇流口接管（`store/memory-md-sync.ts`），本模块只供收敛器与
+ * 单条凭证两个原件——曾经在这里的 `makeSuffixSync` 点火器已退役，不留第二事实源。
+ *
+ * 单点失效联动（`disableProjectionFile`）的三种落点：
+ * - 盘上有 `.memory.md`（**不再要求有 workspace**：无归属那条也要改，它的文件本来就在单根）→ **改名**成 `.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, rm, stat } from 'node:fs/promises';
+import { atomicWriteText, ensureDir } from '../util/io.js';
+import { disablePathOf, digest, isRetiredRecord, recordDigest, renderRecord, targetFor } from './memory-md.js';
+/**
+ * 退场判据的单一真源在 `memory-md.ts`（导出侧与这里必须共用一个），本模块只转发，
+ * 免得既有调用方拿不到。另起一套（比如再叠上 `persistence`）只会让"列表说它退了、
+ * 文件却没后缀"重新变成常态。
+ */
+export { isRetiredRecord };
+/** 存在性判定：一次 `stat`，任何错误都当"不存在"（权限/竞态都不该让失效动作失败）。 */
+async function exists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 账本跟着换键。
+ *
+ * 键是绝对路径（N10），所以改名必须"删旧键、记新键"——只改文件不改账本，下一轮对账
+ * 会同时报"旧键文件缺失"和"新文件是外人加的"，两边都错。
+ * 没有旧条目（人从没导出过）时只记新键，不补造旧键。
+ *
+ * ⚠️ `fileDigest` **取磁盘上的真实字节**，不取我们手上那份渲染结果：改名分支里
+ * 旧文件是“未退场时导出的那一版”（不带 `retired`），拿新渲染的摘要当基线，
+ * 下一轮对账就会把“我们自己改的文件”报成“人改过文件”。
+ *
+ * @param persist - 默认 true（单条失效联动：写完就该落盘）。**批量收敛必须传 false**：
+ * 账本是整本 JSON 的原子重写，每条都 `flush()` 就把「窗口内只记脏、收尾落一次」
+ * 的设计退化成 O(n²)（真机 912 条回填会被墙钟 `timeBudgetMs` 拦成好几次点击）。
+ *
+ * 导出给 `memory-md-sync.ts` 的改名跟随用——「取磁盘真实字节当基线」这条纪律只该有一份。
+ */
+export async function moveLedger(ledger, fromAbs, toAbs, r, fallbackText, persist = true) {
+    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);
+    if (persist)
+        await ledger.flush();
+}
+/**
+ * 把一条已退场记忆的投射文件标成 `.disable`。
+ *
+ * @param deps - 记录、根配置、数据目录、账本与日志。
+ * @returns 文件侧结果；**任何异常都收敛成 `'failed'`，不抛**。
+ */
+export async function disableProjectionFile(deps) {
+    const { record: r, ledger, logger } = deps;
+    const ws = (r.workspaceId ?? '').trim();
+    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)) {
+            try {
+                await rename(abs, dis);
+            }
+            catch (err) {
+                // 竞态兜底：存在性检查和改名之间，收口挂钩可能已经把这个文件改走了（同一批次
+                // 双触发时两条路径都会走到这里）。改成功过的文件再改名报 ENOENT——盘上已经是
+                // 想要的那份，该报 `already`，不该刷 warn（真机日志里噪声会淹掉真失败）。
+                if (err instanceof Error && 'code' in err && err.code === 'ENOENT' && await exists(dis)) {
+                    if (ledger.get(dis) === undefined)
+                        await moveLedger(ledger, abs, dis, r, text);
+                    return 'already';
+                }
+                throw err;
+            }
+            await moveLedger(ledger, abs, dis, r, text);
+            logger?.info(`[memory] 声明过时 → 投射文件已改名: ${dis}`);
+            return 'renamed';
+        }
+        // 盘上什么都没有：无归属时不凭空在单根造文件（原「宁缺勿猜」红线只保留在这一分支）。
+        // 旧写法是在函数入头就早退，于是「导出能写进单根、退场却改不了名」——写得出收不回。
+        if (ws.length === 0)
+            return 'no-workspace';
+        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';
+    }
+}
+/** 让出事件循环一次：收敛是长任务，不能独占 tick（面板会僵）。 */
+function tick() {
+    return new Promise((resolveTick) => { setImmediate(resolveTick); });
+}
+/**
+ * 盘上这份是不是被人改过：拿真实字节与账本的 `fileDigest` 比。
+ *
+ * 没账（从没导出过 / 首轮基线未建）时返回 false——“没基线”不等于“被改过”。
+ * 注意这里只诊断不阻断：改名只动后缀、不动字节，所以人改的内容跟着文件一起走，
+ * 丢不了；计数与重新记账是为了让下一遍对账能把这件事说清。
+ */
+async function looksEdited(ledger, abs) {
+    const prev = ledger.get(abs);
+    if (prev === undefined)
+        return false;
+    const actual = await readFile(abs, 'utf8').catch(() => undefined);
+    return actual !== undefined && digest(actual) !== prev.fileDigest;
+}
+/**
+ * 后缀不变式收敛：把「库里的有/无效」与「文件的 `.memory.md` / `.memory.md.disable`」对齐。
+ *
+ * 为什么挂在导出后面而不是各个退场调用点：那 8 处 `.retire()` 分布在手动软删、批量退场、
+ * 合并取代、冲突判负、slot 连带等路径上，事件挂钩注定会漏（真机实测：920 条退场记录
+ * 只有 8 个 `.disable`，全部来自召回面板那一条路径）。收敛器只依赖三个可观测事实：
+ * 文件存在性、当前后缀、指纹一致性。
+ *
+ * 护栏与导出同一套（`maxRecords` 只数碰盘动作 + `timeBudgetMs` 墙钟），所以第一次点可能只
+ * 收敛一部分，`capped`/`remaining` 会告诉你还要点几次。
+ */
+export async function convergeDisabledSuffix(deps) {
+    const { records, ledger, logger } = deps;
+    const startedAt = (deps.now ?? Date.now)();
+    const rep = {
+        scanned: 0, renamed: 0, revived: 0, edited: 0, already: 0, both: 0, absent: 0, skipped: 0, remaining: 0, capped: false,
+    };
+    let worked = 0;
+    for (let i = 0; i < records.length; i++) {
+        // 两条护栏都在循环顶部查：写在末尾会被 `continue` 跳过（exportRecords 自家测试抓过）。
+        if (worked >= deps.maxRecords || (deps.now ?? Date.now)() - startedAt >= deps.timeBudgetMs) {
+            rep.capped = true;
+            rep.remaining = records.length - i;
+            break;
+        }
+        const r = records[i];
+        if (r === undefined)
+            continue;
+        rep.scanned++;
+        const target = targetFor(r, deps.cfgRoot, deps.dataDir, logger);
+        const abs = target.absPath;
+        if (abs === undefined) {
+            rep.skipped++;
+            logger?.warn(`[memory] 后缀收敛跳过（路径越界）: ${r.id} → ${target.relPath}`);
+            continue;
+        }
+        const dis = disablePathOf(abs);
+        try {
+            const hasDis = await exists(dis);
+            const hasAbs = await exists(abs);
+            if (isRetiredRecord(r)) {
+                if (hasDis && hasAbs) {
+                    // 两份都在：可能是上一遍改名中途崩了，也可能是人复制了一份。删哪份都是不可逆判断，
+                    // 所以只报账，交孤儿归档/人裁决。
+                    rep.both++;
+                    continue;
+                }
+                if (hasDis) {
+                    // 后缀已对上；仍要保证账本认得它（改完文件就崩的残留态）。
+                    if (ledger.get(dis) === undefined) {
+                        await moveLedger(ledger, abs, dis, r, renderRecord(r).text, false);
+                        worked++;
+                    }
+                    rep.already++;
+                    continue;
+                }
+                if (!hasAbs) {
+                    rep.absent++;
+                    continue;
+                }
+                if (await looksEdited(ledger, abs))
+                    rep.edited++;
+                try {
+                    await rename(abs, dis);
+                }
+                catch (err) {
+                    // 与 `disableProjectionFile` 同一条竞态兜底：双触发时另一条路径可能已把这份改走了。
+                    // 盘上已是想要的那份 → 算 `already`，不刷 warn（否则噪声会淹掉真失败）。
+                    if (err instanceof Error && 'code' in err && err.code === 'ENOENT' && await exists(dis)) {
+                        if (ledger.get(dis) === undefined)
+                            await moveLedger(ledger, abs, dis, r, renderRecord(r).text, false);
+                        rep.already++;
+                        continue;
+                    }
+                    throw err;
+                }
+                await moveLedger(ledger, abs, dis, r, renderRecord(r).text, false);
+                rep.renamed++;
+                worked++;
+                await tick();
+                continue;
+            }
+            // 有效记录：后缀应该是 `.memory.md`。
+            if (hasDis && !hasAbs) {
+                const entry = ledger.get(dis);
+                if (entry === undefined || entry.id !== r.id) {
+                    // 人手造的 `.disable` 是文件侧退场凭证（recall-feedback 的文件侧对偶）。
+                    // P2 关着时库里不知道这件事，自动改回去等于揉掉人的裁决 → 只报账不动盘。
+                    rep.both++;
+                    continue;
+                }
+                await rename(dis, abs);
+                await moveLedger(ledger, dis, abs, r, renderRecord(r).text, false);
+                rep.revived++;
+                worked++;
+                await tick();
+                continue;
+            }
+            if (hasDis && hasAbs) {
+                // 有效记录两份都在。多数不是人手复制，而是「恢复后导出补写了非退场路径，
+                // `.disable` 那份还留着」——不收这一格，恢复一轮就会永久多出双份。
+                // 删得同时满足三个条件才算“机器自己造的陈年标记”，不丢任何信息：
+                // ① 凭证确实是我们给**这条记录**写的（账本同 id）；② 它自我们写下后没被人改过
+                //（磁盘字节 == 账本 fileDigest）；③ `.memory.md` 这份就是我们当前渲染的那份
+                //（人手放的一份不会正好等于渲染结果）。任一不成立 → 只报账，交人裁决。
+                const entry = ledger.get(dis);
+                const disText = await readFile(dis, 'utf8').catch(() => undefined);
+                const absText = await readFile(abs, 'utf8').catch(() => undefined);
+                if (entry !== undefined && entry.id === r.id
+                    && disText !== undefined && digest(disText) === entry.fileDigest
+                    && absText !== undefined && absText === renderRecord(r).text) {
+                    await rm(dis);
+                    ledger.delete(dis);
+                    rep.revived++;
+                    worked++;
+                    await tick();
+                    continue;
+                }
+                rep.both++;
+                continue;
+            }
+            if (hasAbs) {
+                rep.already++;
+                continue;
+            }
+            rep.absent++;
+        }
+        catch (err) {
+            // 单条失败不阻断整批：下一遍还会重算（收敛是无状态的）。
+            rep.skipped++;
+            logger?.warn(`[memory] 后缀收敛失败(下轮重试): ${abs} - ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // 收尾落一次账：循环里只记脏（`moveLedger` 的 `persist=false`）。中途崩了就丢本轮账，
+    // 但收敛器无状态且幂等——下一遍重算即可，所以不值得为它每条写一次整本 JSON。
+    await ledger.flush();
+    if (rep.renamed + rep.revived + rep.both + rep.edited > 0) {
+        logger?.info(`[memory] 后缀收敛：改名 ${rep.renamed}（其中人改过 ${rep.edited}）· 改回 ${rep.revived} · 已对 ${rep.already} · 冲突 ${rep.both} · 无文件 ${rep.absent}${rep.capped ? ` · 剩余 ${rep.remaining}` : ''}`);
+    }
+    return rep;
+}

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>;