dsh-prime-memory 0.24.0 → 0.24.2

package/dist/settings.js

@@ -81,6 +81,8 @@ const ALWAYS_ON = {
     memoryMutate: false,
     conflictFreeze: false,
     skillsEnabled: false,
+    // md 投射护栏运行时覆盖:0 = 跟随部署 cfg.memExport.maxRecords（面板上可改）
+    mdExportMaxRecords: 0,
     toolRoom: true,
     toolGraph: true,
     toolRuminate: true,
@@ -315,6 +317,8 @@ function resolveSettings(value) {
         conflictFreeze: v.conflictFreeze === true,
         // 轨2 技能结晶:严格 === true(默认关,新功能默认关)
         skillsEnabled: v.skillsEnabled === true,
+        // md 投射护栏钳 0~10000（与 live schema 同上限）；0 = 跟随部署默认
+        mdExportMaxRecords: Math.min(10_000, Math.max(0, num(v.mdExportMaxRecords))),
         // 工具分组封印:严格 !== false(缺省/异常值 = 未封印,工具照常注册)
         toolRoom: v.toolRoom !== false,
         toolGraph: v.toolGraph !== false,

package/dist/stats.d.ts

@@ -177,6 +177,12 @@ export declare function hitToUiRecord(r: {
     metadata?: Record<string, unknown>;
     score?: number;
     family?: string;
+    /** 名称（md 投射相）：投射文件名取它；无名字 = undefined。 */
+    name?: string;
+    /** 可见范围（§E）：'workspace' 才带归属，其余一律归一 'global'。 */
+    scope?: string;
+    /** 归属工作区路径（仅 scope='workspace' 时非空）。 */
+    workspaceId?: string;
     /** 退场判据:`valid_to` 闭合即已退场(软删)。由 `listL1`/`getByIds` 透传。 */
     validTo?: number;
 }, extra?: {

package/dist/stats.js

@@ -38,7 +38,8 @@ import { snapshotTokenCost } from './token-cost.js';
 import { computeMaturity } from './util/maturity.js';
 import { isFeedbackScore } from './store/recall-feedback.js';
 import { relinkWorkspaces } from './pipeline/workspace-relink.js';
-import { exportRecords, reconcileLedger } from './store/memory-md-export.js';
+import { reconcileLedger } from './store/memory-md-export.js';
+import { mdRunStatus, runProjection } from './store/memory-md-run.js';
 import { disableProjectionFile } from './store/memory-md-disable.js';
 import { MEMORY_TYPE_DIRS, UNSORTED_DIR, resolveMemoriesRoot, targetFor } from './store/memory-md.js';
 import { ensureTypeSkeleton } from './store/memory-md-skeleton.js';
@@ -114,6 +115,7 @@ export const MEMORY_ENDPOINTS = [
     'dsh-memory/recall-feedback',
     'dsh-memory/workspace-relink',
     'dsh-memory/mem-export',
+    'dsh-memory/mem-run-status',
     'dsh-memory/mem-reconcile',
     'dsh-memory/mem-sync',
     'dsh-memory/mem-orphans',
@@ -398,6 +400,8 @@ function sanitizeSettings(s) {
 /** 端点分发表(导出供测试直调:可精确注入 rebuild/ruminate 等可选控制器,验证 deps 接线)。 */
 export async function handleEndpoint(endpoint, payload, deps) {
     const { cfg, stores, status, live, modes, dataDir, rebuild, ruminate, embedManager, sessionInfo, roomRegistry, memorySources, skillStore } = deps;
+    // 退场/恢复/新增的文件跟随已收口在 `L1Store` 的汇流口（`store/memory-md-sync.ts`），
+    // 本分发层不再自己建点火器——那 8 处事件挂钩已被真机证伪（会漏）。
     switch (endpoint) {
         case 'dsh-memory/stats':
             return buildStats(cfg, stores, status);
@@ -554,7 +558,9 @@ export async function handleEndpoint(endpoint, payload, deps) {
         case 'dsh-memory/mem-export': {
             // 单向导出：库 → md 文件 + 账本。**不写检索面**（用例钉住：导出前后 hashRecords 相同）。
             // 先查配置门再查装配门：“整面默认关”时该听到的是“没开”，不是“没装配”。
-            const exp = cfg.memExport;
+            // 护栏读**生效**配置（含面板上的 `mdExportMaxRecords` 覆盖）：只看启动快照
+            // 就会“调了没反应”，而这条路径的护栏正是给人调的。
+            const exp = effectiveCfg(cfg, live).memExport;
             if (exp?.enabled !== true)
                 throw new Error('md 投射未开启（cfg.memExport.enabled）');
             const md = stores.mdLedger;
@@ -584,7 +590,10 @@ export async function handleEndpoint(endpoint, payload, deps) {
                     skeletonRoots.add(t.root);
             }
             await ensureTypeSkeleton({ roots: [...skeletonRoots], countsByType, logger: deps.logger });
-            const rep = await exportRecords({
+            // 滚动执行到清完：先把导出游标推到表尾，再把后缀收敛游标推到表尾。
+            // 单轮护栏（`maxRecords`/`timeBudgetMs`）不变，跨轮另有轮数与总墙钟兜底；
+            // 进度经 `dsh-memory/mem-run-status` 读（面板画进度条）。
+            const run = await runProjection({
                 records: all,
                 cfgRoot: exp.root,
                 dataDir: deps.dataDir,
@@ -593,11 +602,17 @@ export async function handleEndpoint(endpoint, payload, deps) {
                 timeBudgetMs: exp.timeBudgetMs,
                 logger: deps.logger,
             });
-            return { ...rep, named: naming.named, nameFailed: naming.failed };
+            return { ...run, named: naming.named, nameFailed: naming.failed };
+        }
+        case 'dsh-memory/mem-run-status': {
+            // 只读进度快照。故意不查配置门：任务没在跑时也要能读到上一次的 `notice`
+            // （“预算用尽、还剩 N 条”这句话必须在人下次点击之前也看得见）。
+            return mdRunStatus();
         }
         case 'dsh-memory/mem-reconcile': {
             // 只读对账：不写库、不写文件，只按账本基线出四态报告（所以不需高权限门）。
-            const exp = cfg.memExport;
+            // 同样读生效配置：对账与导出共用护栏，两边半生效会让人看不出差异从哪来。
+            const exp = effectiveCfg(cfg, live).memExport;
             if (exp?.enabled !== true)
                 throw new Error('md 投射未开启（cfg.memExport.enabled）');
             const md = stores.mdLedger;
@@ -981,7 +996,8 @@ export async function handleEndpoint(endpoint, payload, deps) {
                         const page = stores.l1.list({ tag: slug, retired: false, limit: 200, offset });
                         if (page.items.length === 0)
                             break;
-                        const n = stores.l1.retire(page.items.map((r) => r.id), { at: new Date().toISOString(), reason: 'manual' });
+                        const pageIds = page.items.map((r) => r.id);
+                        const n = stores.l1.retire(pageIds, { at: new Date().toISOString(), reason: 'manual' });
                         retiredRecords += n;
                         if (page.items.length < 200)
                             break;
@@ -1233,6 +1249,7 @@ export async function handleEndpoint(endpoint, payload, deps) {
                     memoryMutate: false,
                     conflictFreeze: live?.get()?.conflictFreeze === true,
                     skillsEnabled: live?.get()?.skillsEnabled === true,
+                    mdExportMaxRecords: live?.get()?.mdExportMaxRecords ?? 0,
                 }),
                 // 静态部署上限(cordis.patch.yml):运行时开关与它取 AND
                 ceilings: { capture: cfg.capture.enabled, distill: cfg.extract.enabled, recall: cfg.recall.enabled },
@@ -1275,7 +1292,12 @@ export async function handleEndpoint(endpoint, payload, deps) {
                 if (typeof patch[key] === 'boolean')
                     clean[key] = patch[key];
             }
-            // 运行时统一路由链:结构校验后整体写入(空数组 = 回到跟随部署配置)
+            // md 投射护栏运行时覆盖：数字才收，钳 0~10000（与 live schema 同上限）；0 = 跟随部署默认。
+            // 不加进白名单的话，面板上那个输入框会“写成功但被静默丢”——看得到数字、不生效。
+            if (typeof patch.mdExportMaxRecords === 'number' && Number.isFinite(patch.mdExportMaxRecords)) {
+                clean.mdExportMaxRecords = Math.min(10_000, Math.max(0, Math.floor(patch.mdExportMaxRecords)));
+            }
+            // 运行时统一路由链：结构校验后整体写入（空数组 = 回到跟随部署配置）
             if (patch.distillChain !== undefined) {
                 const err = validateDistillChain(patch.distillChain);
                 if (err)
@@ -1648,6 +1670,7 @@ export async function handleEndpoint(endpoint, payload, deps) {
                 throw new Error('ids 缺失');
             const r = await stores.l1.restore(ids);
             deps.logger.info(`[memory] 恢复已退场记忆 ${r.restored} 条(补向量 ${r.vectorsWritten} 条)`);
+            // 掉 `.disable` 后缀由 `l1.restore()` 里的钩子承接（与退场对称的那一半）。
             const resp = r;
             return resp;
         }
@@ -2203,6 +2226,16 @@ export function hitToUiRecord(r, extra) {
         }),
         // G1 使用场景：从命名空间保留键读出（功能关/无键 → undefined）。
         usageScenario: Array.isArray(r.metadata?.dsh_usage_scenario) ? r.metadata?.dsh_usage_scenario : undefined,
+        // 投射身份三项（N1）：名称 / 可见范围 / 归属工作区。面板靠它们核对“这条记忆
+        // 对应哪个投射文件、对谁可见”——这三个值此前从不进 UiRecord，于是面板上
+        // 无法把记忆与投射文件对上。纯投影，不从存储侧另算。
+        name: r.name ?? null,
+        scope: r.scope === 'workspace' ? 'workspace' : 'global',
+        workspaceId: r.scope === 'workspace' ? (r.workspaceId ?? '') || null : null,
+        // 关键词（保留字段，用于 BM25）：与 usageScenario 同范式，从保留键读出（无键 → undefined）。
+        keywords: Array.isArray(r.metadata?.dsh_keywords)
+            ? (r.metadata?.dsh_keywords).filter((k) => typeof k === 'string' && k !== '')
+            : undefined,
         // 人给相关度均值：读时从 sidecar 派生（不进存储/快照）；未打分 → 字段缺席。
         userRelevance: extra?.userRelevance ?? undefined,
     };

package/dist/store/l1.d.ts

@@ -6,6 +6,7 @@ import { type SupersedeInfo } from './supersede.js';
 import { type ExportThenPurgeResult, type PurgeOptions, type RestoreResult, type SnapshotRestorePlan, type SnapshotSummary } from './l1-snapshot.js';
 import { type EmbeddingService } from './embedding.js';
 import { type L1MetaLite, type MemoryDb } from './sqlite.js';
+import type { L1FileSyncHook } from './memory-md-sync.js';
 export type RecallStrategy = 'keyword' | 'embedding' | 'hybrid';
 /**
  * 图谱路提供者(§D 第 3 路):按查询返回图谱命中(已按 score 降序)。
@@ -73,6 +74,15 @@ export declare class L1Store {
     untaggedL1Count(): number;
     /** Room 计数缓存(见 `listRooms()`:tags 仅随反刍变化,不必每次敲库)。 */
     private roomCache;
+    /**
+     * 库→文件投射的跟随钩子(收口点;未注入 = 零文件动作)。
+     *
+     * 为什么不放在调用方:改变记录有效性/身份的写路径全部汇流在本类的 `appendNew` /
+     * `retire` / `restore` / `rename` 四个方法上,而上游有 8 处 `retire()` 调用点——事件挂钩
+     * 已被真机证伪(920 条退场只有 8 个 `.disable`)。放这里意味着新增调用点不会漏。
+     * 与构造函数里的 `autoName: () => cfg.memExport.enabled` 同一先例:只拿判据,不拿配置快照。
+     */
+    private fileSync?;
     constructor(dataDir: string, db: MemoryDb, embed?: EmbeddingService, strategy?: RecallStrategy, logger?: MemoryLogger, 
     /** 时效衰减半衰期(天;0=关)。缺省 30 与 config 默认一致。 */
     decayHalfLifeDays?: number, 
@@ -88,6 +98,15 @@ export declare class L1Store {
     autoName?: (() => boolean) | undefined);
     /** 读路径时效半衰期(天;0=关)。老化权重展示与召回衰减同一事实源。 */
     get decayHalfLife(): number;
+    /**
+     * 装配层晚绑定投射跟随钩子。
+     *
+     * 必须晚于构造:`stores.l1` 先建,md 账本(`stores.mdLedger`)后装,构造期拿不到 ledger。
+     * 未注入时四个汇流口行为与注入前逐字一致(投射面关着也是这条)。
+     */
+    setFileSyncHook(hook: L1FileSyncHook): void;
+    /** 有效性变更点火(增/退场/恢复共用一个入口:钩子内部自己跑「导出→后缀收敛」)。 */
+    private fireFileSync;
     init(): Promise<void>;
     /** 旧版单文件 records.jsonl 一次性导入检索库,成功后改名 .imported。 */
     private importLegacy;

package/dist/store/l1.js

@@ -42,6 +42,15 @@ export class L1Store {
     }
     /** Room 计数缓存(见 `listRooms()`:tags 仅随反刍变化,不必每次敲库)。 */
     roomCache = null;
+    /**
+     * 库→文件投射的跟随钩子(收口点;未注入 = 零文件动作)。
+     *
+     * 为什么不放在调用方:改变记录有效性/身份的写路径全部汇流在本类的 `appendNew` /
+     * `retire` / `restore` / `rename` 四个方法上,而上游有 8 处 `retire()` 调用点——事件挂钩
+     * 已被真机证伪(920 条退场只有 8 个 `.disable`)。放这里意味着新增调用点不会漏。
+     * 与构造函数里的 `autoName: () => cfg.memExport.enabled` 同一先例:只拿判据,不拿配置快照。
+     */
+    fileSync;
     constructor(dataDir, db, embed = new NoopEmbeddingService(), strategy = 'hybrid', logger, 
     /** 时效衰减半衰期(天;0=关)。缺省 30 与 config 默认一致。 */
     decayHalfLifeDays, 
@@ -71,6 +80,21 @@ export class L1Store {
     get decayHalfLife() {
         return this.decayHalfLifeDays;
     }
+    /**
+     * 装配层晚绑定投射跟随钩子。
+     *
+     * 必须晚于构造:`stores.l1` 先建,md 账本(`stores.mdLedger`)后装,构造期拿不到 ledger。
+     * 未注入时四个汇流口行为与注入前逐字一致(投射面关着也是这条)。
+     */
+    setFileSyncHook(hook) {
+        this.fileSync = hook;
+    }
+    /** 有效性变更点火(增/退场/恢复共用一个入口:钩子内部自己跑「导出→后缀收敛」)。 */
+    fireFileSync(ids, why) {
+        if (this.fileSync === undefined || ids.length === 0)
+            return;
+        this.fileSync.sync(ids, why);
+    }
     async init() {
         await ensureDir(this.recordsDir);
         await this.importLegacy();
@@ -153,9 +177,16 @@ export class L1Store {
      * 改名不触发场景重聚类，也不动 `updated_time`（约束在 `renameL1` 里）。
      */
     rename(id, name) {
+        // 改名前的身份要先把住：投射文件名就是 `name`（`targetFor` 算路径），库里改了而盘上
+        // 没跟进就会长期对不上，后缀收敛器也修不了（它按**当前** name 算路径）。
+        const oldName = this.db.getL1ByIds([id])[0]?.name;
         const r = this.db.renameL1(id, name);
-        if (r === 'ok')
+        if (r === 'ok') {
+            if (oldName !== undefined && oldName !== '' && oldName !== name && this.fileSync !== undefined) {
+                this.fileSync.renamed(new Map([[id, oldName]]), 'rename');
+            }
             return { ok: true };
+        }
         return { ok: false, reason: r };
     }
     /** 按名字反查 id（重名预检 / md 回灌）；未命中 ⇒ undefined。 */
@@ -452,6 +483,8 @@ export class L1Store {
             this.logger?.error(`[memory] L1 检索库批量写入失败(${records.length} 条,JSONL 事实源完好),` +
                 '这批记忆暂不可检索;可在设置页运行「重建记忆」修复');
         }
+        // 写对称:新增也即时上盘(不阻塞、失败只 warn)——否则「文件树 = 库当前状态」只对删成立。
+        this.fireFileSync(records.map((r) => r.id), 'appendNew');
     }
     /** 去重 update/merge 产出的记录:只更新检索库(JSONL 事实源不改写,官方语义)。 */
     async upsert(record) {
@@ -488,7 +521,11 @@ export class L1Store {
      * 而那种不一致只有在误删发生时才暴露。
      */
     retire(ids, info) {
-        return this.db.retireL1Batch(ids, info);
+        const n = this.db.retireL1Batch(ids, info);
+        // 退场汇流口(人工软删 / 合并取代 / 冲突判负 都经这里)——所以机器侧自动退场也自动有文件跟随。
+        // 不 await:库侧结果先成立,投射是旁路(见 `setFileSyncHook` 的注释)。
+        this.fireFileSync(ids, 'retire');
+        return n;
     }
     /** 已退场(可恢复)记录列表(面板用)。 */
     listRetired(opts) {
@@ -517,6 +554,8 @@ export class L1Store {
                 vectorsWritten++;
             this.db.upsertL1(rec, vec);
         }
+        // 恢复活跃 = 有效性变更,后缀该从 `.disable` 掉回去(与 `retire` 对称的那一半)。
+        this.fireFileSync(records.map((r) => r.id), 'restore');
         return { restored: records.length, vectorsWritten };
     }
     /**
@@ -624,6 +663,11 @@ export class L1Store {
             unretired = back.restored;
             stillRetired = [];
         }
+        // 回到主表就等于“库里多一份可投射的份”：无论带不带退场标记都要上盘
+        // （带标记的那批由钩子内部的收敛器接成 `.disable`）。走 `restore` 的那批已点火，不重发。
+        if (r.restored > 0 && unretired === 0) {
+            this.fireFileSync(targetIds, 'restoreFromSnapshot');
+        }
         return { ...r, dir: resolved.dir, found: true, missing, unretired, stillRetired };
     }
     /** 这批 id 里当前**在库**的集合(分块查,避免一次 IN 太多参数)。 */

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

@@ -1,7 +1,15 @@
+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`），这样渲染出的
@@ -14,6 +22,24 @@ export interface DisableDeps {
     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`。
  *
@@ -21,3 +47,28 @@ export interface DisableDeps {
  * @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

@@ -5,11 +5,20 @@
  * workspace，也不该拿到文件系统的写权限。**库是事实源，文件是投影**——所以退场先成立，
  * 文件侧只是把"人已处置"这件事也写到磁盘上。
  *
- * 三种落点（用户口径）：
- * - 有 workspace 且 `.memory.md` 存在 → **改名**成 `.memory.md.disable`；
- * - 有 workspace 但文件还没导出过 → **创建** `.disable`（内容就是渲染结果，带 `retired: true`），
+ * 后缀不变式（作者口径 2026-10-14）：文件后缀**只跟「这条记录在库里是否有效」有关**，
+ * `name` 字段无感，「是谁把它退场的」也无感。所以不能只在一个退场按钮后面挂一刀——
+ * 全仓有 8 处 `.retire()` 调用点（手动判过时 / 批量软删 / 合并取代 / 冲突判负 / slot 连带…），
+ * 事件挂钩注定会漏。`convergeDisabledSuffix` 就是这个不变式的收敛器：每次导出后按
+ * 「文件存在性 + 当前后缀 + 指纹一致性」三项检查重算一遍，与退场路径无关。
+ *
+ * 点火已由 `L1Store` 的汇流口接管（`store/memory-md-sync.ts`），本模块只供收敛器与
+ * 单条凭证两个原件——曾经住在这里的旧「后缀点火器工厂」已退役，不留第二事实源。
+ *
+ * 单点失效联动（`disableProjectionFile`）的三种落点：
+ * - 盘上有 `.memory.md`（**不再要求有 workspace**：无归属那条也要改，它的文件本来就在单根）→ **改名**成 `.memory.md.disable`；
+ * - 盘上什么都没有、但**有** workspace → **创建** `.disable`（内容就是渲染结果，带 `retired: true`），
  *   人不点导出也有一份磁盘凭证，P2 与人都看得见；
- * - 没有 workspace → **什么都不写**。宁缺勿猜：为一个归属不明的记忆在单根凭空造文件，
+ * - 盘上什么都没有、且没有 workspace → **什么都不写**。宁缺勿猜：为一个归属不明的记忆在单根凭空造文件，
  *   等于把"没路由上"伪装成"它属于默认根"。
  *
  * 三条硬约束：
@@ -18,9 +27,15 @@
  * 3. **改名而不是删除**：`.disable` 是凭证，删了 P2 与人都无从对齐。
  */
 import { dirname } from 'node:path';
-import { readFile, rename, stat } from 'node:fs/promises';
+import { readFile, rename, rm, stat } from 'node:fs/promises';
 import { atomicWriteText, ensureDir } from '../util/io.js';
-import { disablePathOf, digest, recordDigest, renderRecord, targetFor } from './memory-md.js';
+import { disablePathOf, digest, isRetiredRecord, recordDigest, renderRecord, targetFor } from './memory-md.js';
+/**
+ * 退场判据的单一真源在 `memory-md.ts`（导出侧与这里必须共用一个），本模块只转发，
+ * 免得既有调用方拿不到。另起一套（比如再叠上 `persistence`）只会让"列表说它退了、
+ * 文件却没后缀"重新变成常态。
+ */
+export { isRetiredRecord };
 /** 存在性判定：一次 `stat`，任何错误都当"不存在"（权限/竞态都不该让失效动作失败）。 */
 async function exists(p) {
     try {
@@ -41,8 +56,14 @@ async function exists(p) {
  * ⚠️ `fileDigest` **取磁盘上的真实字节**，不取我们手上那份渲染结果：改名分支里
  * 旧文件是“未退场时导出的那一版”（不带 `retired`），拿新渲染的摘要当基线，
  * 下一轮对账就会把“我们自己改的文件”报成“人改过文件”。
+ *
+ * @param persist - 默认 true（单条失效联动：写完就该落盘）。**批量收敛必须传 false**：
+ * 账本是整本 JSON 的原子重写，每条都 `flush()` 就把「窗口内只记脏、收尾落一次」
+ * 的设计退化成 O(n²)（真机 912 条回填会被墙钟 `timeBudgetMs` 拦成好几次点击）。
+ *
+ * 导出给 `memory-md-sync.ts` 的改名跟随用——「取磁盘真实字节当基线」这条纪律只该有一份。
  */
-async function moveLedger(ledger, fromAbs, toAbs, r, fallbackText) {
+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);
@@ -59,7 +80,8 @@ async function moveLedger(ledger, fromAbs, toAbs, r, fallbackText) {
     });
     if (prev !== undefined)
         ledger.delete(fromAbs);
-    await ledger.flush();
+    if (persist)
+        await ledger.flush();
 }
 /**
  * 把一条已退场记忆的投射文件标成 `.disable`。
@@ -70,8 +92,6 @@ async function moveLedger(ledger, fromAbs, toAbs, r, fallbackText) {
 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;
@@ -88,11 +108,28 @@ export async function disableProjectionFile(deps) {
             return 'already';
         }
         if (await exists(abs)) {
-            await rename(abs, dis);
+            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);
@@ -104,3 +141,162 @@ export async function disableProjectionFile(deps) {
         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;
+}