dsh-prime-memory 0.22.1 → 0.24.0

package/dist/store/embedding-source.d.ts

@@ -97,6 +97,14 @@ export declare class EmbeddingManager {
     private applyBusy;
     private reindex;
     private reindexCancel;
+    /**
+     * 上一次重建的留痕（类型就地取自契约，不另开 import）。
+     *
+     * 为什么必须存：进度条只在 `running` 期间存在，而“待补 0 条”的重建会瞬间跑完，
+     * 界面上与“点了没反应”长得一模一样——真机反馈就是这么读的。留痕存**前后待补数**，
+     * 让“效果”是两个可比数字而不是一句“我转了一下”。
+     */
+    private reindexLast;
     /**
      * 向量计数缓存(分级 TTL)。
      *

package/dist/store/embedding-source.js

@@ -187,6 +187,14 @@ export class EmbeddingManager {
         cancelled: false,
     };
     reindexCancel = false;
+    /**
+     * 上一次重建的留痕（类型就地取自契约，不另开 import）。
+     *
+     * 为什么必须存：进度条只在 `running` 期间存在，而“待补 0 条”的重建会瞬间跑完，
+     * 界面上与“点了没反应”长得一模一样——真机反馈就是这么读的。留痕存**前后待补数**，
+     * 让“效果”是两个可比数字而不是一句“我转了一下”。
+     */
+    reindexLast;
     /**
      * 向量计数缓存(分级 TTL)。
      *
@@ -471,6 +479,27 @@ export class EmbeddingManager {
     async reindexNow() {
         this.reindexCancel = false;
         this.reindex = { running: true, l1Done: 0, l1Total: 0, l0Done: 0, l0Total: 0, startedAt: Date.now(), cancelled: false };
+        // 重建**前**的待补数：先破缓存再取，否则拿到的可能是 TTL 里的旧值（那会让“前后差”假报 0）。
+        // 口径故意与界面用的同一个（相减法），不拿精确口径去对展示数字，否则两边永远对不上。
+        this.invalidateVecCache();
+        const v0 = this.vectorCounts();
+        const missingBefore = { l1: v0.l1.missing, l0: v0.l0.missing };
+        const finish = (cancelled, error) => {
+            this.invalidateVecCache();
+            const v1 = this.vectorCounts();
+            const at = Date.now();
+            this.reindexLast = {
+                finishedAt: at,
+                durationMs: Math.max(0, at - this.reindex.startedAt),
+                processed: this.reindex.l1Done + this.reindex.l0Done,
+                planned: this.reindex.l1Total + this.reindex.l0Total,
+                failed: failedTotal,
+                cancelled,
+                ...(error === undefined ? {} : { error }),
+                missingBefore,
+                missingAfter: { l1: v1.l1.missing, l0: v1.l0.missing },
+            };
+        };
         let failedTotal = 0;
         try {
             const r1 = await this.deps.l1.reindex({
@@ -493,6 +522,7 @@ export class EmbeddingManager {
             this.reindex.cancelled = cancelled;
             this.reindex.running = false;
             this.invalidateVecCache(); // 收尾:计数必须立刻反映重建结果(TTL 可能还压着 1s 旧值)
+            finish(cancelled);
             return { cancelled, failedTotal };
         }
         catch (err) {
@@ -500,6 +530,7 @@ export class EmbeddingManager {
             this.reindex.running = false;
             this.reindex.error = message;
             this.invalidateVecCache();
+            finish(false, message);
             return { cancelled: false, failedTotal, error: `重嵌入失败: ${message}` };
         }
     }
@@ -538,7 +569,7 @@ export class EmbeddingManager {
             download: this.downloader.getProgress(),
             apply: { phase: this.applyPhase, message: this.applyMessage, startedAt: this.applyStartedAt, busy: this.applyBusy },
             local: this.localSvc ? { state: this.localSvc.getState(), error: this.localSvc.getLoadError() } : null,
-            reindex: { ...this.reindex },
+            reindex: { ...this.reindex, last: this.reindexLast },
             vectors: this.vectorsCached(),
             activeNote: this.activeNote,
         };
@@ -562,7 +593,13 @@ export class EmbeddingManager {
         const count = (kind) => {
             const skip = this.deps.db.getVecSkipSet(kind);
             const embedded = kind === 'l1' ? this.deps.db.countL1Vec() : this.deps.db.countL0Vec();
-            const total = kind === 'l1' ? this.deps.db.countL1() : this.deps.db.countL0();
+            // 相减法还有第二条前提，之前漏了：**分母必须是活跃行**。退场行按设计就合法地没有
+            // 向量（撤检索面时 vec 行被 detach），把它们算进 total 会让 missing 恒等于退场数、
+            // 永不归零；而真正驱动补齐的 `countVecMissing`/`getL1ForReindex` 都排除退场行，于是
+            // 界面上同时出现“待补 114 条”与“重建索引无事可做”。本机实测：1280 总 / 114 退场 /
+            // 1166 活跃且全部已嵌，正是这个形状。`countL1Retired` 失败给 -1，按 0 处理退回旧行为。
+            const retired = kind === 'l1' ? Math.max(0, this.deps.db.countL1Retired()) : 0;
+            const total = (kind === 'l1' ? this.deps.db.countL1() : this.deps.db.countL0()) - retired;
             // 缺失数走**相减**而非 LEFT JOIN:见下方 vectorsCached 上方的说明。
             const missing = embedded < 0 || total < 0 ? -1 : Math.max(0, total - embedded - skip.size);
             return { embedded, total, missing, skipped: skip.size };

package/dist/store/file-versions.d.ts

@@ -21,7 +21,11 @@ export declare const SESSION_MODES_FILE_VERSION = 1;
 export declare const OCCUPANCY_FILE_VERSION = 1;
 /** `recall-dedupe.json`。 */
 export declare const RECALL_DEDUPE_FILE_VERSION = 1;
+/** `session-recalled.json`（G-live 活召回集，持久化以令旧会话重开可读）。 */
+export declare const SESSION_RECALLED_FILE_VERSION = 1;
 /** `pending.json`。 */
 export declare const PENDING_FILE_VERSION = 1;
 /** `reconcile-state.json`。 */
 export declare const RECONCILE_STATE_FILE_VERSION = 1;
+/** `mem-md-ledger.json`（md 投射指纹账本，N9；派生态，删了可重建）。*/
+export declare const MEM_MD_LEDGER_FILE_VERSION = 1;

package/dist/store/file-versions.js

@@ -21,7 +21,11 @@ export const SESSION_MODES_FILE_VERSION = 1;
 export const OCCUPANCY_FILE_VERSION = 1;
 /** `recall-dedupe.json`。 */
 export const RECALL_DEDUPE_FILE_VERSION = 1;
+/** `session-recalled.json`（G-live 活召回集，持久化以令旧会话重开可读）。 */
+export const SESSION_RECALLED_FILE_VERSION = 1;
 /** `pending.json`。 */
 export const PENDING_FILE_VERSION = 1;
 /** `reconcile-state.json`。 */
 export const RECONCILE_STATE_FILE_VERSION = 1;
+/** `mem-md-ledger.json`（md 投射指纹账本，N9；派生态，删了可重建）。*/
+export const MEM_MD_LEDGER_FILE_VERSION = 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,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 触发源)。
      * 归属变了,记忆对场景的归属度就变了——受影响场景的摘要必须由当前事实重算
@@ -142,6 +214,8 @@ export declare class L1Store {
     };
     /** 按 id 精确取记录(去重决策的版本号查询用,避免全表扫描)。 */
     getByIds(ids: string[]): MemoryRecord[];
+    /** 外部导入幂等 pre-check(轨3-P0):ext_key 命中已存在记录则返回其 id,否则 undefined。 */
+    findIdByExtKey(extKey: string): string | undefined;
     /**
      * §B 决策凭证落盘(L1Store 的薄缝)。
      * 刻意放在 store 上:`runExtraction` 已经持有 L1Store,凭证写入因此无需新增
@@ -253,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 触发源)。
      * 归属变了,记忆对场景的归属度就变了——受影响场景的摘要必须由当前事实重算
@@ -229,6 +345,10 @@ export class L1Store {
     getByIds(ids) {
         return this.db.getL1ByIds(ids);
     }
+    /** 外部导入幂等 pre-check(轨3-P0):ext_key 命中已存在记录则返回其 id,否则 undefined。 */
+    findIdByExtKey(extKey) {
+        return this.db.findRecordIdByExtKey(extKey);
+    }
     /**
      * §B 决策凭证落盘(L1Store 的薄缝)。
      * 刻意放在 store 上:`runExtraction` 已经持有 L1Store,凭证写入因此无需新增
@@ -310,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());
@@ -334,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 事实源完好),该记忆暂不可检索,重建可修复`);
@@ -400,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` 会先落快照,但只落不接等于