dsh-prime-memory 0.22.2 → 0.24.1

package/dist/store/graph-store.d.ts

@@ -106,6 +106,20 @@ export declare class GraphStore {
      * 记录跳过。返回实际新建的 job 数。
      */
     queueGraphProjection(recordIds: readonly string[], priority: number): number;
+    /**
+     * 记录被物理删除后，把两张**索引表**里指向它的行一并抹掉。
+     *
+     * 为什么必需（F19）：`graph_projected_records` 之前全仓**只增不减**。记录行删了而投影行还在，
+     * 就留下两类静默问题：① 投影进度表里挂着一批查不到主人的 record_id；② 从快照**恢复**回来的
+     * 记录因为投影行已存在而被当成“已投影”，**永远不会重投影**（检索图里就这么缺一条，不报错）。
+     *
+     * 只删索引行，**不动图节点/边**：节点是跨记录聚合出来的事实，归图自己的生命周期管。
+     * 失败只 warn 并返回已删数——清理的既成事实不应被旁路索引拖挂。
+     *
+     * @param ids - 已被物理删除的记录 id。
+     * @returns 从投影表删掉的行数。
+     */
+    forgetRecords(ids: readonly string[]): number;
     /**
      * 取下一个可执行 job 并置 running(attempts +1):只认当前 projectorVersion,
      * attempts 封顶与退避窗口在 WHERE 里过滤;来源全缺失 → job 判 dead 返 null

package/dist/store/graph-store.js

@@ -514,6 +514,41 @@ export class GraphStore {
             return 0;
         }
     }
+    /**
+     * 记录被物理删除后，把两张**索引表**里指向它的行一并抹掉。
+     *
+     * 为什么必需（F19）：`graph_projected_records` 之前全仓**只增不减**。记录行删了而投影行还在，
+     * 就留下两类静默问题：① 投影进度表里挂着一批查不到主人的 record_id；② 从快照**恢复**回来的
+     * 记录因为投影行已存在而被当成“已投影”，**永远不会重投影**（检索图里就这么缺一条，不报错）。
+     *
+     * 只删索引行，**不动图节点/边**：节点是跨记录聚合出来的事实，归图自己的生命周期管。
+     * 失败只 warn 并返回已删数——清理的既成事实不应被旁路索引拖挂。
+     *
+     * @param ids - 已被物理删除的记录 id。
+     * @returns 从投影表删掉的行数。
+     */
+    forgetRecords(ids) {
+        if (!this.db || ids.length === 0)
+            return 0;
+        const db = this.db;
+        let removed = 0;
+        try {
+            // 分批：IN 列表不能无限长（与入队/去重查询同一个口径）
+            for (let i = 0; i < ids.length; i += 500) {
+                const chunk = ids.slice(i, i + 500);
+                const ph = chunk.map(() => '?').join(',');
+                db.prepare(`DELETE FROM graph_projected_records WHERE record_id IN (${ph})`).run(...chunk);
+                const jobInfo = db.prepare(`DELETE FROM graph_job_records WHERE record_id IN (${ph})`).run(...chunk);
+                removed += chunk.length;
+                void jobInfo;
+            }
+            return removed;
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} 图索引遗录清理失败(忽略): ${err instanceof Error ? err.message : String(err)}`);
+            return removed;
+        }
+    }
     /**
      * 取下一个可执行 job 并置 running(attempts +1):只认当前 projectorVersion,
      * attempts 封顶与退避窗口在 WHERE 里过滤;来源全缺失 → job 判 dead 返 null

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,9 +3,10 @@ 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';
+import type { L1FileSyncHook } from './memory-md-sync.js';
 export type RecallStrategy = 'keyword' | 'embedding' | 'hybrid';
 /**
  * 图谱路提供者(§D 第 3 路):按查询返回图谱命中(已按 score 降序)。
@@ -50,6 +51,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;
@@ -65,13 +74,39 @@ 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, 
     /** 图谱路提供者(§D 第 3 路);不传则该路不存在,融合退回双路。 */
-    graphLane?: GraphLaneProvider);
+    graphLane?: GraphLaneProvider, 
+    /**
+     * “该不该给没名字的新记录起名”的实时判据（装配层递 `() => cfg.memExport.enabled`）。
+     *
+     * 用函数而不是布尔：设置面可热改，存下快照就会与当前开关漂移。
+     * 不传 = 不主动起名（“投射关着时零动作”这条既有承诺不改），但**别人占着的名字照样修**
+     * ——那是防丢数据，与开关无关。
+     */
+    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;
@@ -97,6 +132,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 +346,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;
@@ -40,13 +42,31 @@ 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, 
     /** 图谱路提供者(§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');
@@ -60,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();
@@ -128,6 +163,118 @@ 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) {
+        // 改名前的身份要先把住：投射文件名就是 `name`（`targetFor` 算路径），库里改了而盘上
+        // 没跟进就会长期对不上，后缀收敛器也修不了（它按**当前** name 算路径）。
+        const oldName = this.db.getL1ByIds([id])[0]?.name;
+        const r = this.db.renameL1(id, name);
+        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。 */
+    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 +461,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());
@@ -333,11 +483,15 @@ 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) {
         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 事实源完好),该记忆暂不可检索,重建可修复`);
@@ -367,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) {
@@ -396,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 };
     }
     /**
@@ -404,13 +564,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` 会先落快照,但只落不接等于
@@ -503,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 太多参数)。 */