dsh-prime-memory 0.22.2 → 0.24.0

package/dist/store/l1-snapshot.d.ts

@@ -1,3 +1,4 @@
+import { type ArchiveFileOutcome, type FilesByRecord } from './memory-md-archive.js';
 import type { MemoryLogger, MemoryRecord } from '../types.js';
 import type { ConflictPair } from './conflicts.js';
 export declare const SNAPSHOT_VERSION = 1;
@@ -246,6 +247,30 @@ export interface ExportThenPurgeResult {
     purged: number;
     /** 校验差异(仅 aborted 时非空)。 */
     diffs: string[];
+    /**
+     * 本批之外发生漂移的记录数(仅计数、**不中止**)。
+     *
+     * 旧实现拿整库哈希当门禁：并发蒸馏/另一处写入改过任何一条与本批无关的记录，
+     * 本次清理就会永远中止（而它要删的那批逐字未动、完全可恢复）。漂移信息仍要报，
+     * 但它不是删除本批的安全障碍。
+     */
+    otherChanged: number;
+    /** 归档正文路径（未写 = 空串）。 */
+    archiveMd: string;
+    /** 投射文件搬运计数（N12）。 */
+    files: ArchiveFileOutcome;
+}
+/** 清理时的可选动作（P3）。 */
+export interface PurgeOptions {
+    /**
+     * 投射文件映射（由 `collectProjectionFiles` 产出）。
+     *
+     * **不传 = 只删库，行为与改动前逐字一致**——投射面默认关，归档搬运不能变成它的前置条
+     * 件。传了就在全部门禁通过后把文件搬进快照目录，失败只 warn。
+     */
+    files?: FilesByRecord;
+    /** 是否写 `retired.md` 归档正文（默认 true）。 */
+    archiveMd?: boolean;
 }
 /**
  * **先导出,后清理**——把这句话变成调用方绕不过去的一步。
@@ -263,4 +288,4 @@ export interface ExportThenPurgeResult {
 export declare function exportThenPurge(db: PurgeDbLike, dataDir: string, ids: readonly string[], reason: string, logger?: {
     info: (m: string) => void;
     warn: (m: string) => void;
-}, now?: Date): Promise<ExportThenPurgeResult>;
+}, now?: Date, opts?: PurgeOptions): Promise<ExportThenPurgeResult>;

package/dist/store/l1-snapshot.js

@@ -33,6 +33,7 @@
  * 等于把证据链悄悄拆了。这条有专门用例。
  */
 import { createHash } from 'node:crypto';
+import { moveProjectionFiles, writeArchiveMarkdown } from './memory-md-archive.js';
 import { readdir } from 'node:fs/promises';
 import { atomicWriteJson, readJsonStrict } from '../util/io.js';
 export const SNAPSHOT_VERSION = 1;
@@ -368,9 +369,10 @@ export async function snapshotBeforeClear(db, dataDir, reason, now = new Date())
  * 而清理一旦没有可信的导出物,就只剩 `records/*.jsonl` 事实源这一条后路,
  * 且那条路只覆盖 L1 记录、不覆盖 receipts/conflicts 的当时快照。
  */
-export async function exportThenPurge(db, dataDir, ids, reason, logger, now = new Date()) {
+export async function exportThenPurge(db, dataDir, ids, reason, logger, now = new Date(), opts = {}) {
+    const empty = { moved: 0, failed: 0, absent: 0 };
     if (ids.length === 0)
-        return { ok: true, aborted: false, dir: '', name: '', purged: 0, diffs: [] };
+        return { ok: true, aborted: false, dir: '', name: '', purged: 0, diffs: [], otherChanged: 0, archiveMd: '', files: empty };
     let dir = '';
     let name = '';
     try {
@@ -381,14 +383,57 @@ export async function exportThenPurge(db, dataDir, ids, reason, logger, now = ne
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         logger?.warn(`[memory] 清理中止:快照写入失败(${msg})——未删除任何记录`);
-        return { ok: false, aborted: true, dir, name, purged: 0, diffs: [`快照写入失败:${msg}`] };
+        return { ok: false, aborted: true, dir, name, purged: 0, diffs: [`快照写入失败:${msg}`], otherChanged: 0, archiveMd: '', files: empty };
     }
-    const verdict = await verifySnapshot(db, dir);
-    if (!verdict.ok) {
-        logger?.warn(`[memory] 清理中止:快照校验未通过(${verdict.diffs.join(';')})——未删除任何记录`);
-        return { ok: false, aborted: true, dir, name, purged: 0, diffs: verdict.diffs };
+    // 门禁第二半——**批次级投影**。不再拿整库哈希当门禁：那会把“本批逐字未动、但库里有
+    // 别的东西被并发改过”误判成不安全，而事实恰好相反——要删的那批在快照里完整可信，
+    // 删错了能原样回灌。整库漂移仍计数（它是要给人看的信息），但它不拦住删除。
+    let subset = [];
+    let otherChanged = 0;
+    try {
+        const want = new Set(ids);
+        const snapAll = await readSnapshotRecords(dir);
+        subset = snapAll.filter((r) => want.has(r.id));
+        const current = listAllL1(db);
+        const curSubset = current.filter((r) => want.has(r.id));
+        const snapRest = snapAll.filter((r) => !want.has(r.id));
+        const curRest = current.filter((r) => !want.has(r.id));
+        otherChanged = hashRecords(snapRest) === hashRecords(curRest) ? 0 : curRest.length;
+        const diffs = [];
+        if (subset.length !== want.size)
+            diffs.push(`快照里本批只有 ${subset.length}/${want.size} 条`);
+        if (hashRecords(subset) !== hashRecords(curSubset))
+            diffs.push('本批内容与快照不一致(快照后这批被改过)');
+        if (diffs.length > 0) {
+            logger?.warn(`[memory] 清理中止:批次校验未通过(${diffs.join(';')})——未删除任何记录`);
+            return { ok: false, aborted: true, dir, name, purged: 0, diffs, otherChanged, archiveMd: '', files: empty };
+        }
+        if (otherChanged > 0)
+            logger?.warn(`[memory] 清理放行:本批之外有 ${otherChanged} 条处于差异状态(不影响本批可恢复性)`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger?.warn(`[memory] 清理中止:快照读回失败(${msg})——未删除任何记录`);
+        return { ok: false, aborted: true, dir, name, purged: 0, diffs: [`快照读回失败:${msg}`], otherChanged, files: empty, archiveMd: '' };
     }
     const purged = db.deleteL1Batch([...ids]);
     logger?.info(`[memory] 已物理清理 ${purged} 条已退场记录(快照:${dir})`);
-    return { ok: true, aborted: false, dir, name, purged, diffs: [] };
+    // 归档两面：先写给人读的正文，再搬投射文件。两者失败都**不回滚已完成的删除**
+    // （不对称的方向特别重要：文件可重生成，库删了不可逆，而快照已经先落盘了）。
+    let archiveMd = '';
+    if (opts.archiveMd !== false) {
+        try {
+            archiveMd = await writeArchiveMarkdown(dir, subset, { reason, at: now });
+        }
+        catch (err) {
+            logger?.warn(`[memory] 归档正文写入失败(记录已删，快照仍在): ${dir} - ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    const files = opts.files === undefined
+        ? empty
+        : await moveProjectionFiles(dir, subset, opts.files, logger).catch((err) => {
+            logger?.warn(`[memory] 归档搬运异常(文件留在原地): ${err instanceof Error ? err.message : String(err)}`);
+            return empty;
+        });
+    return { ok: true, aborted: false, dir, name, purged, diffs: [], otherChanged, archiveMd, files };
 }

package/dist/store/l1.d.ts

@@ -3,7 +3,7 @@ import type { GraphNodeSearchResult } from '../graph/types.js';
 import type { L1Receipt, ReceiptQuery } from './receipts.js';
 import type { ConflictClaimGroup, ConflictPair, ConflictRejected, ConflictResolution, ConflictType } from './conflicts.js';
 import { type SupersedeInfo } from './supersede.js';
-import { type ExportThenPurgeResult, type RestoreResult, type SnapshotRestorePlan, type SnapshotSummary } from './l1-snapshot.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';
 export type RecallStrategy = 'keyword' | 'embedding' | 'hybrid';
@@ -50,6 +50,14 @@ export interface SnapshotRestoreOutcome extends RestoreResult {
 export declare class L1Store {
     private readonly db;
     private readonly strategy;
+    /**
+     * “该不该给没名字的新记录起名”的实时判据（装配层递 `() => cfg.memExport.enabled`）。
+     *
+     * 用函数而不是布尔：设置面可热改，存下快照就会与当前开关漂移。
+     * 不传 = 不主动起名（“投射关着时零动作”这条既有承诺不改），但**别人占着的名字照样修**
+     * ——那是防丢数据，与开关无关。
+     */
+    private readonly autoName?;
     /** 记忆库根目录(`records/` 与 `snapshots/` 都在它下面)。 */
     private readonly dataDir;
     private readonly recordsDir;
@@ -69,7 +77,15 @@ export declare class L1Store {
     /** 时效衰减半衰期(天;0=关)。缺省 30 与 config 默认一致。 */
     decayHalfLifeDays?: number, 
     /** 图谱路提供者(§D 第 3 路);不传则该路不存在,融合退回双路。 */
-    graphLane?: GraphLaneProvider);
+    graphLane?: GraphLaneProvider, 
+    /**
+     * “该不该给没名字的新记录起名”的实时判据（装配层递 `() => cfg.memExport.enabled`）。
+     *
+     * 用函数而不是布尔：设置面可热改，存下快照就会与当前开关漂移。
+     * 不传 = 不主动起名（“投射关着时零动作”这条既有承诺不改），但**别人占着的名字照样修**
+     * ——那是防丢数据，与开关无关。
+     */
+    autoName?: (() => boolean) | undefined);
     /** 读路径时效半衰期(天;0=关)。老化权重展示与召回衰减同一事实源。 */
     get decayHalfLife(): number;
     init(): Promise<void>;
@@ -97,6 +113,62 @@ export declare class L1Store {
         repoKeyName?: string;
         repoKeyOwner?: string;
     }, expectRepoKeyName?: string): number;
+    /**
+     * 批量写内容路由得出的 workspace 归属（不触发场景重聚类——归属变化不影响场景划分，
+     * 与 repoKey 那条不一样）。具体约束（不碰 updated_time、同步改 l1_fts）在
+     * `store/sqlite.ts` 的 `setL1WorkspaceIds` 里，那里是硬约束的**唯一**落点。
+     */
+    setWorkspaceIds(items: ReadonlyArray<{
+        id: string;
+        workspaceId: string;
+    }>): number;
+    /**
+     * 改一条记忆的文件身份名（N1）。形状校验在调用方（`normalizeName`），唯一性由
+     * 存储层的部分唯一索引挡——撞名就返 `{ ok: false, reason: 'dup' }`，**不自动加后缀**。
+     * 改名不触发场景重聚类，也不动 `updated_time`（约束在 `renameL1` 里）。
+     */
+    rename(id: string, name: string): {
+        ok: boolean;
+        reason?: string;
+    };
+    /** 按名字反查 id（重名预检 / md 回灌）；未命中 ⇒ undefined。 */
+    findIdByName(name: string): string | undefined;
+    /**
+     * 给一批**名字缺失或被别人占着**的记录分配文件身份名（N1 的机器起名，全库唯一判据的唯一真源）。
+     *
+     * 为什么必须做：`deriveName` 只取正文首行前 24 字，同一段话的多条记录必然洗出同名。
+     * 真机实测 1166 条记录 `name` 全空、42 条挤进 17 个同名投射文件（最狠一个路径 6 条），
+     * 后果是导出每轮重刷被覆盖的那几条、反向同步会把一份内容回灌给六条记录。不回填 name，
+     * P0 加的这一列与部分唯一索引就一直是空转。
+     *
+     * “要起名”的判据不是“name 为空”，而是两种都要管：
+     * - **空名**（存量与“抽取时没起名”的新行）——只在 `autoName()` 为真时补；
+     * - **名字属于库里另一条**——无条件重命。这一类不是想象：调用方拿 `{ ...旧记录, id: 新 id }`
+     *   复制新记录（去重 merge / 取代路径就这么写），旧记录刚被本函数填上 name；不重命的话
+     *   新记录拿着别人占着的名字去写库，**撞部分唯一索引 → 整条写不进检索库**（旧记录已退场、
+     *   取代者根本不存，两个自家用例就是这么挂的）。
+     *
+     * 三条约束：
+     * - **不覆写属于它自己的名字**：人的命名是权威；
+     * - **只改 name**：不碰内容/类型/退场态，也不进快照哈希字段表（`canonicalRecords` 里没有
+     *   `name`），所以这一步不会弄挂「导出不改检索面」的护栏；
+     * - **按 id 排序后再分配**：同一个基底谁先拿到裸名由顺序决定，不钉死会给同一条记录
+     *   两次分到不同名字，文件在盘上跳来跳去。
+     *
+     * @param records - 待起名的记录（**就地改 `.name`**，内存与库保持一致）。
+     * @param opts.persist - true 走 `renameL1Batch` 落库（存量回填）；false 只算名不落库
+     *   （新增记录还没进库，名字由随后的 upsert 一并写）。
+     * @param opts.fillEmpty - 是否给**空名**起名（默认按 `autoName()` 判）。“名字属于别人”那类
+     *   不受此参数影响，永远修。
+     * @returns `named` 本轮起名条数，`failed` 落库失败条数（persist=false 时恒为 0）。
+     */
+    assignMissingNames(records: MemoryRecord[], opts?: {
+        persist?: boolean;
+        fillEmpty?: boolean;
+    }): {
+        named: number;
+        failed: number;
+    };
     /**
      * repo 归属变化 → 受影响场景的重聚类作业(治理 W3,repo-change 触发源)。
      * 归属变了,记忆对场景的归属度就变了——受影响场景的摘要必须由当前事实重算
@@ -255,7 +327,7 @@ export declare class L1Store {
      * 门禁本体在 `l1-snapshot.exportThenPurge`(与"重建前必快照"同一套设施);
      * 这里只把 L1Store 已知的 dataDir 与 logger 接上去,避免端点层自己去推路径。
      */
-    purgeRetired(ids: string[], reason: string): Promise<ExportThenPurgeResult>;
+    purgeRetired(ids: string[], reason: string, opts?: PurgeOptions): Promise<ExportThenPurgeResult>;
     /** 可用快照列表(按时间倒序;面板/工具据此选一份来恢复)。 */
     listSnapshots(opts?: {
         limit?: number;

package/dist/store/l1.js

@@ -14,6 +14,7 @@ import { isRetired } from './supersede.js';
 import { exportThenPurge, readSnapshotManifest, readSnapshotRecords, restoreL1Snapshot, selectSnapshotTargets, snapshotDirFor, listSnapshots as listSnapshotsIn } from './l1-snapshot.js';
 import { EmbedHelper, NoopEmbeddingService } from './embedding.js';
 import { appendJsonl, dayKey, ensureDir, readJsonl } from '../util/io.js';
+import { allocUniqueName, deriveName } from '../util/md-name.js';
 import { applyDecayWeight, normalizeRrf, rrfMerge, markDedupPath } from './search-utils.js';
 import { isZeroVector } from './sqlite.js';
 /** Room 计数缓存 TTL(tags 只在反刍标签段变化;面板常开也不必每次敲库)。 */
@@ -23,6 +24,7 @@ const CANDIDATE_MULTIPLIER = 3;
 export class L1Store {
     db;
     strategy;
+    autoName;
     /** 记忆库根目录(`records/` 与 `snapshots/` 都在它下面)。 */
     dataDir;
     recordsDir;
@@ -44,9 +46,18 @@ export class L1Store {
     /** 时效衰减半衰期(天;0=关)。缺省 30 与 config 默认一致。 */
     decayHalfLifeDays, 
     /** 图谱路提供者(§D 第 3 路);不传则该路不存在,融合退回双路。 */
-    graphLane) {
+    graphLane, 
+    /**
+     * “该不该给没名字的新记录起名”的实时判据（装配层递 `() => cfg.memExport.enabled`）。
+     *
+     * 用函数而不是布尔：设置面可热改，存下快照就会与当前开关漂移。
+     * 不传 = 不主动起名（“投射关着时零动作”这条既有承诺不改），但**别人占着的名字照样修**
+     * ——那是防丢数据，与开关无关。
+     */
+    autoName) {
         this.db = db;
         this.strategy = strategy;
+        this.autoName = autoName;
         this.dataDir = dataDir;
         this.recordsDir = path.join(dataDir, 'records');
         this.legacyFile = path.join(dataDir, 'l1', 'records.jsonl');
@@ -128,6 +139,111 @@ export class L1Store {
             this.enqueueRepoChangeRecluster([id]);
         return changed;
     }
+    /**
+     * 批量写内容路由得出的 workspace 归属（不触发场景重聚类——归属变化不影响场景划分，
+     * 与 repoKey 那条不一样）。具体约束（不碰 updated_time、同步改 l1_fts）在
+     * `store/sqlite.ts` 的 `setL1WorkspaceIds` 里，那里是硬约束的**唯一**落点。
+     */
+    setWorkspaceIds(items) {
+        return this.db.setL1WorkspaceIds(items);
+    }
+    /**
+     * 改一条记忆的文件身份名（N1）。形状校验在调用方（`normalizeName`），唯一性由
+     * 存储层的部分唯一索引挡——撞名就返 `{ ok: false, reason: 'dup' }`，**不自动加后缀**。
+     * 改名不触发场景重聚类，也不动 `updated_time`（约束在 `renameL1` 里）。
+     */
+    rename(id, name) {
+        const r = this.db.renameL1(id, name);
+        if (r === 'ok')
+            return { ok: true };
+        return { ok: false, reason: r };
+    }
+    /** 按名字反查 id（重名预检 / md 回灌）；未命中 ⇒ undefined。 */
+    findIdByName(name) {
+        return this.db.findRecordIdByName(name);
+    }
+    /**
+     * 给一批**名字缺失或被别人占着**的记录分配文件身份名（N1 的机器起名，全库唯一判据的唯一真源）。
+     *
+     * 为什么必须做：`deriveName` 只取正文首行前 24 字，同一段话的多条记录必然洗出同名。
+     * 真机实测 1166 条记录 `name` 全空、42 条挤进 17 个同名投射文件（最狠一个路径 6 条），
+     * 后果是导出每轮重刷被覆盖的那几条、反向同步会把一份内容回灌给六条记录。不回填 name，
+     * P0 加的这一列与部分唯一索引就一直是空转。
+     *
+     * “要起名”的判据不是“name 为空”，而是两种都要管：
+     * - **空名**（存量与“抽取时没起名”的新行）——只在 `autoName()` 为真时补；
+     * - **名字属于库里另一条**——无条件重命。这一类不是想象：调用方拿 `{ ...旧记录, id: 新 id }`
+     *   复制新记录（去重 merge / 取代路径就这么写），旧记录刚被本函数填上 name；不重命的话
+     *   新记录拿着别人占着的名字去写库，**撞部分唯一索引 → 整条写不进检索库**（旧记录已退场、
+     *   取代者根本不存，两个自家用例就是这么挂的）。
+     *
+     * 三条约束：
+     * - **不覆写属于它自己的名字**：人的命名是权威；
+     * - **只改 name**：不碰内容/类型/退场态，也不进快照哈希字段表（`canonicalRecords` 里没有
+     *   `name`），所以这一步不会弄挂「导出不改检索面」的护栏；
+     * - **按 id 排序后再分配**：同一个基底谁先拿到裸名由顺序决定，不钉死会给同一条记录
+     *   两次分到不同名字，文件在盘上跳来跳去。
+     *
+     * @param records - 待起名的记录（**就地改 `.name`**，内存与库保持一致）。
+     * @param opts.persist - true 走 `renameL1Batch` 落库（存量回填）；false 只算名不落库
+     *   （新增记录还没进库，名字由随后的 upsert 一并写）。
+     * @param opts.fillEmpty - 是否给**空名**起名（默认按 `autoName()` 判）。“名字属于别人”那类
+     *   不受此参数影响，永远修。
+     * @returns `named` 本轮起名条数，`failed` 落库失败条数（persist=false 时恒为 0）。
+     */
+    assignMissingNames(records, opts = {}) {
+        const fillEmpty = opts.fillEmpty ?? (this.autoName?.() === true);
+        // 名字属于库里另一条的（含被 `{...旧记录}` 复制走的），一律重新分配。
+        const foreignName = (r) => {
+            const n = (r.name ?? '').trim();
+            if (n.length === 0)
+                return false;
+            const owner = this.db.findRecordIdByName(n);
+            return owner !== undefined && owner !== r.id;
+        };
+        const emptyName = (r) => (r.name ?? '').trim().length === 0;
+        const needSet = new Set();
+        for (const r of records) {
+            if (foreignName(r) || (fillEmpty && emptyName(r)))
+                needSet.add(r);
+        }
+        const need = records.filter((r) => needSet.has(r)).sort((a, b) => a.id.localeCompare(b.id));
+        if (need.length === 0)
+            return { named: 0, failed: 0 };
+        // 占用集：本批里**不需要重新分配**的那些名字（它们确实是自己的）+ 本轮刚分出去的。
+        const reserved = new Set();
+        for (const r of records) {
+            if (needSet.has(r))
+                continue;
+            const n = (r.name ?? '').trim();
+            if (n.length > 0)
+                reserved.add(n);
+        }
+        const needIds = new Set(need.map((r) => r.id));
+        const isFree = (name) => {
+            const owner = this.db.findRecordIdByName(name);
+            // 持者是本轮正要起名的某条自己（存量回填时它们已在库里），不算占。
+            return owner === undefined || needIds.has(owner);
+        };
+        const items = [];
+        for (const r of need) {
+            // 基底始终取正文，而不是取那个“属于别人的旧名字”。
+            const name = allocUniqueName(deriveName(r.content), r.id, isFree, reserved);
+            r.name = name;
+            items.push({ id: r.id, name });
+        }
+        if (opts.persist !== true)
+            return { named: items.length, failed: 0 };
+        const { done, failed } = this.db.renameL1Batch(items);
+        // 落库失败的条目把内存侧名字收回：否则内存与库不一致，下一轮又当“已有名字”而永不重试。
+        if (failed.length > 0) {
+            const bad = new Set(failed);
+            for (const r of need)
+                if (bad.has(r.id))
+                    r.name = '';
+        }
+        return { named: done.length, failed: failed.length };
+    }
     /**
      * repo 归属变化 → 受影响场景的重聚类作业(治理 W3,repo-change 触发源)。
      * 归属变了,记忆对场景的归属度就变了——受影响场景的摘要必须由当前事实重算
@@ -314,6 +430,9 @@ export class L1Store {
             if (!r.family)
                 r.family = familyForType(r.type);
         }
+        // 起名必须在**追加事实源之前**：名字是文件身份键，进了 JSONL 才能跟记录一起重生。
+        // 这批还没进库，所以只算名字不落库（persist=false），由下面的 upsert 一并写。
+        this.assignMissingNames(records, { persist: false });
         const byDay = new Map();
         for (const r of records) {
             const k = dayKey(r.createdAt || Date.now());
@@ -338,6 +457,8 @@ export class L1Store {
     async upsert(record) {
         if (!record.family)
             record.family = familyForType(record.type);
+        // merge 分支会继承胜方的 name；两边都没名字时在这里补上，别让新铸的行继续带空名。
+        this.assignMissingNames([record], { persist: false });
         const vec = (await this.helper.batch([record.content]))[0];
         if (!this.db.upsertL1(record, vec)) {
             this.logger?.error(`[memory] L1 检索库写入失败 id=${record.id}(JSONL 事实源完好),该记忆暂不可检索,重建可修复`);
@@ -404,13 +525,13 @@ export class L1Store {
      * 门禁本体在 `l1-snapshot.exportThenPurge`(与"重建前必快照"同一套设施);
      * 这里只把 L1Store 已知的 dataDir 与 logger 接上去,避免端点层自己去推路径。
      */
-    async purgeRetired(ids, reason) {
+    async purgeRetired(ids, reason, opts = {}) {
         // **只清理确实处于退场态的记录**。这道复核必须在删除发生的地方(而不是调用方):
         // 否则任何调用方传一个 id 列表就能绕过软删、把活动记忆直接物理抹掉——
         // 那等于给"先导出后清理"留了一条硬删后门。
         const known = new Map(this.db.getL1ByIds(ids).map((r) => [r.id, r]));
         const retiredIds = ids.filter((id) => known.get(id)?.validTo !== undefined);
-        return exportThenPurge(this.db, this.dataDir, retiredIds, reason, this.logger);
+        return exportThenPurge(this.db, this.dataDir, retiredIds, reason, this.logger, new Date(), opts);
     }
     // ───────────────────────────────────────────────────────────────────────────
     // 快照的**读与回灌**(task_27):`purgeRetired` 会先落快照,但只落不接等于

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