dsh-prime-memory 0.13.1 → 0.14.0-beta.2

package/dist/pipeline/l1.js

@@ -12,6 +12,7 @@ import { buildReceipts, newRunId, persistReceiptsSafely } from '../store/receipt
 import { buildConflictPair, validateConflictPair } from '../store/conflicts.js';
 import { formatExtractionPrompt, getExtractMemoriesSystemPrompt } from '../prompts/l1-extraction.js';
 import { formatBatchConflictPrompt, getConflictDetectionSystemPrompt } from '../prompts/l1-dedup.js';
+import { resolveSourceAnchors, withSourceAnchors } from './anchors.js';
 import { familyForType, normPersistence, normScope, resolveRecordFamily, resolveRecordScope } from '../types.js';
 /** 解析 ISO/epoch 时间证据,非法或非正值一律 undefined——不猜测。 */
 function parseTimeEvidence(raw) {
@@ -51,8 +52,11 @@ function mergeTemporal(self, targets) {
  * 构造一条**全新**L1 记录(store 语义)。§C 冻结复用同一构造:
  * "新记忆照常入 L1"必须与既有 store 路径**逐字段一致**,否则冻结会引入
  * 一种只在开启开关时才出现的新记录形状。
+ *
+ * 第 4 个参数是 R7 的锚点映射(`L0 消息 id → 会话坐标`)。**传 undefined 时
+ * 行为与改动前逐字一致**——老调用方与没有锚点的会话走这条分支。
  */
-function toStoreRecord(m, now, ts) {
+function toStoreRecord(m, now, ts, anchorMap) {
     return {
         id: m.record_id,
         content: m.content,
@@ -64,7 +68,9 @@ function toStoreRecord(m, now, ts) {
         updatedAt: now,
         version: 0,
         source_message_ids: m.source_message_ids ?? [],
-        metadata: m.metadata ?? {},
+        // R7:锚点与 source_message_ids 同源解析;解析不到就**不写键**(不是空数组),
+        // 使无锚点记录与改动前的 metadata 逐字一致。
+        metadata: withSourceAnchors(m.metadata, anchorMap === undefined ? undefined : resolveSourceAnchors(m.source_message_ids, anchorMap)),
         family: m.family,
         scope: m.scope,
         workspaceId: m.workspaceId,
@@ -104,7 +110,13 @@ export async function runExtraction(ctx, cfg, store, states, pending, background
  * 传 undefined 时行为与改动前**逐字一致**——`cfg.scope='global'` 的既有部署
  * 永远走这条分支,这是零漂移的构造性保证。
  */
-workspaceId) {
+workspaceId, 
+/**
+ * R7 锚点映射(`L0 消息 id → 会话坐标`),由调用方经 `buildAnchorMap` 构造。
+ * **缺省时行为与改动前逐字一致**——传入的 `pending` 消息若不带锚点(老数据、
+ * 未启用捕获侧打戳),`resolveSourceAnchors` 一律返回 undefined,不写 metadata 键。
+ */
+anchorMap) {
     if (!cfg.extract.enabled)
         return { stored: 0, skipped: true, sceneName: chainHead(states, mode), newRecords: [] };
     // 触发阈值(渐进爬坡 + 按会话切片计数)由 runner 判定(trigger.ts);
@@ -272,7 +284,7 @@ workspaceId) {
         const action = decision.action;
         const ts = m.metadata?.activity_start_time ? Date.parse(String(m.metadata.activity_start_time)) : now;
         if (action === 'store') {
-            added.push(toStoreRecord(m, now, ts));
+            added.push(toStoreRecord(m, now, ts, anchorMap));
             continue;
         }
         // ── §C 矛盾冻结:不自动裁决 ──
@@ -286,7 +298,7 @@ workspaceId) {
                 ? validateConflictPair(m.record_id, decision.winner, decision.loser, new Set(byId.keys()))
                 : null;
             if (pair) {
-                added.push(toStoreRecord(m, now, ts));
+                added.push(toStoreRecord(m, now, ts, anchorMap));
                 const built = buildConflictPair({
                     runId,
                     winnerId: pair.winnerId,
@@ -307,7 +319,7 @@ workspaceId) {
             else {
                 logger.warn(`[memory] 矛盾冻结:第 ${m.record_id} 条的 conflict 决策无法构成冻结对` +
                     `(winner=${String(decision.winner)} loser=${String(decision.loser)}),已回落 store`);
-                added.push(toStoreRecord(m, now, ts));
+                added.push(toStoreRecord(m, now, ts, anchorMap));
             }
             continue;
         }
@@ -334,7 +346,10 @@ workspaceId) {
             updatedAt: now,
             version: targetVersion + 1,
             source_message_ids: m.source_message_ids ?? [],
-            metadata: m.metadata ?? {},
+            // R7:合并/更新产出的记录同样带锚点——否则"合并一次就丢坐标",
+            // 而合并恰恰是长会话里最常发生的动作。无映射时传空表 →
+            // resolveSourceAnchors 返回 undefined → 不写 metadata 键(零漂移)。
+            metadata: withSourceAnchors(m.metadata, resolveSourceAnchors(m.source_message_ids, anchorMap ?? new Map())),
             family: m.family,
             // 合并的有效期取并集:起 = 两侧最早;止 = 任一侧未闭合则仍未闭合(undefined)。
             ...mergeTemporal(temporalOf(m.metadata), targets.map((id) => byId.get(id)).filter((r) => r !== undefined)),

package/dist/pipeline/rebuild-preserve.d.ts

@@ -0,0 +1,149 @@
+/**
+ * 保留式重建:清空 L1 前判定**哪些记忆不可能被 L0 重蒸馏出来**,并把这些保住。
+ *
+ * ## 为什么需要这个模块
+ *
+ * `RebuildController.prepare()` 的语义是"清空 L1 检索库 → 从 L0 全量重蒸馏"。
+ * 这个语义对**由 L0 蒸馏而来**的记忆是自洽的(清掉也能再造一遍),但对
+ * **不由 L0 派生**的记忆是破坏性的:`memory_add` / `memory_import` 写进来的
+ * 外部记忆(其他 AI 工具导出的记忆包)在任何会话日志里都没有对应位置,
+ * 重建不会再造出它们。实测(`_analysis_output` 探针,2026-09-17)这类记录
+ * 当时有 19 条存活,涉及 `__manual__` 与若干外部导入场景名。
+ *
+ * ## 判据为什么是 `source_message_ids`,而不是"有没有锚点"
+ *
+ * 计划书原稿写的是"无来源记忆(**导入类 / 无锚点类**)",但实测推翻了后半句:
+ *
+ * - 检索库 `l1_records` **没有 `source_message_ids` 列**(见 `types.ts:224` 的
+ *   既有注释"JSONL 事实源保留;检索库不存该列"),所以判据只能来自**事实源**;
+ * - 检索库里 `dsh_source_anchors` 的命中数是 **0/740** —— task_31 落地的锚点
+ *   写入**尚未产出任何一行**(没有新的蒸馏发生过)。把"无锚点"当判据会把
+ *   **全部 740 条**都判成"要保留",重建直接退化成空操作。
+ *
+ * 所以判据取事实源里的 `source_message_ids`:非空 ⇒ 该记忆的位置在 L0 日志里
+ * 有据可查、重建能再造;空/缺失 ⇒ 造不出来,**必须保留**。
+ *
+ * ## 为什么必须取"事实源 ∩ 检索库"
+ *
+ * 事实源是**只增不改**的历史(合并/更新产出新 id 后,旧行仍留在 JSONL)。
+ * 实测:事实源 1,694 个唯一 id,检索库 740 个,`事实源 ∩ 检索库 == 检索库`
+ * (即检索库是事实源的真子集,反向差集为 0)。其中**已从检索库退场、但没有
+ * `source_message_ids` 的有 25 条** —— 按事实源无脑恢复会**复活这 25 条已删记录**。
+ * 故保留集 = 事实源无来源 **且** 检索库仍存在,两个条件缺一不可。
+ *
+ * ## 静默缺席的处理
+ *
+ * 事实源读不出来时,"没有记录需要保留"与"不知道哪些记录需要保留"长得一模一样。
+ * 后者若按前者处理,重建就**静默退化**成原来的破坏性行为。故 `gateClear()` 在
+ * 事实源不可读(或可读但零记录)**且检索库非空**时**拒绝放行**,而不是放行。
+ */
+import type { MemoryRecord } from '../types.js';
+/** 事实源读取结果的失败原因。成功时为 undefined。 */
+export type FactSourceFailure = 'dir-missing' | 'read-error';
+export interface FactSourceRead {
+    /** 事实源是否可读。false 时 `records` 必为空。 */
+    readonly ok: boolean;
+    readonly records: readonly MemoryRecord[];
+    /** 实际读到的文件数(诊断用:0 个文件与目录缺失是两回事)。 */
+    readonly files: number;
+    readonly reason?: FactSourceFailure;
+    /** 读取异常原文(仅 `read-error` 时)。 */
+    readonly detail?: string;
+}
+/** 保留原因。 */
+export type PreserveReason = 
+/** 事实源里没有 `source_message_ids` —— 不是从 L0 蒸馏来的。 */
+'no-source'
+/** 内容为空白 —— 重蒸馏不会产出空记忆,保留它也无从重造。 */
+ | 'empty-content'
+/**
+ * 检索库里有、事实源里**完全没有**这一行 —— 来源无从证明。
+ *
+ * 实测该集合当前为 **0**(检索库 740 ⊆ 事实源 1,694),所以它不是常规路径,
+ * 而是**事实源部分损坏时的兜底**:`readJsonl` 会静默跳过坏行(`util/io.ts:78`),
+ * 半张文件坏掉时"事实源里没有它"会与"它本来就没有来源"长得一样。
+ * 判不出来源的记忆一律留下 —— 留错是多一条待去重的记录,丢掉是不可逆的。
+ */
+ | 'unprovenanced';
+export interface PreserveEntry {
+    readonly record: MemoryRecord;
+    readonly reason: PreserveReason;
+}
+export interface PreservePlan {
+    /** 清空后要原样放回的记忆。 */
+    readonly preserved: readonly PreserveEntry[];
+    /** 可由 L0 重蒸馏的记忆条数(不保留,重建会再造)。 */
+    readonly rederivable: number;
+    /**
+     * 事实源里无来源、但**已从检索库退场**的条数 —— 已被合并/取代,
+     * 恢复它们等于复活已删记录。**只计数,不恢复**。
+     */
+    readonly retiredNoSource: number;
+    /** 事实源唯一 id 数(含已退场)。 */
+    readonly factCount: number;
+    /** 检索库条数。 */
+    readonly dbCount: number;
+}
+/** 判定单条记录是否可由 L0 重蒸馏出来(事实源侧判据)。 */
+export declare function isRederivable(record: MemoryRecord): boolean;
+/**
+ * 读取事实源目录(`<dataDir>/records/*.jsonl`)。
+ *
+ * 只读 `*.jsonl` 顶层文件:`archiveDerived()` 把旧目录整体改名为
+ * `records.bak.<ts>`,它是**兄弟目录**不是文件,不会被 glob 命中。
+ * **必须在 `archiveDerived()` 之前调用** —— 归档之后事实源就搬走了。
+ */
+export declare function readFactSource(recordsDir: string): Promise<FactSourceRead>;
+/**
+ * 出保留计划。纯函数:输入事实源记录 + 检索库现存记录,输出要保留什么。
+ *
+ * 两个方向都保守:事实源说"这条没来源"要留,**检索库里查不到出处**也要留
+ * (`unprovenanced`)—— 判据缺失时留,而不是丢。
+ *
+ * `liveDbRecords` 由调用方从**检索库**取(它没有 `source_message_ids` 列,
+ * 只用来回答"这条还在不在"),恢复时以检索库副本为准 —— 那是当前检索态。
+ */
+export declare function planPreserve(factRecords: readonly MemoryRecord[], liveDbRecords: readonly MemoryRecord[]): PreservePlan;
+/** 清空闸门的判定码。 */
+export type ClearGateCode = 
+/** 放行。 */
+'ok'
+/** 放行:检索库本来就是空的,没有可失去的东西。 */
+ | 'empty-db'
+/** **拒绝**:事实源目录读不到,而检索库非空 —— 判不出该保留什么。 */
+ | 'source-missing'
+/** **拒绝**:事实源可读但零记录,而检索库非空 —— 事实源异常,同上。 */
+ | 'source-empty';
+export interface ClearGate {
+    readonly allowed: boolean;
+    readonly code: ClearGateCode;
+    /** 面向用户的中文说明(会进 `RebuildStatus.error`,故必须讲清怎么补救)。 */
+    readonly note: string;
+}
+/**
+ * 清空前的守门判定。
+ *
+ * 拒绝而不是放行,是因为"没有需要保留的"与"不知道有没有需要保留的"在数据上
+ * 无法区分(见文件头「静默缺席的处理」)。检索库为空时不存在可失去的记忆,
+ * 故那一路照常放行 —— 不把功能卡死在干净环境上。
+ */
+export declare function gateClear(read: FactSourceRead, plan: PreservePlan): ClearGate;
+/** 恢复结果。**逐条核实**,不靠 `appendNew` 的"没抛就算成功"。 */
+export interface PreserveRestoreResult {
+    readonly attempted: number;
+    readonly restored: number;
+    readonly missing: readonly string[];
+}
+/**
+ * 把保留集放回检索库 + 事实源。
+ *
+ * 走 `L1Store.appendNew` 而不是 `db.upsertL1`:前者**双写**(JSONL 事实源 + 检索库),
+ * 而此刻 `records/` 刚被 `archiveDerived()` 改名走,只写检索库会让这些记忆
+ * 再次成为"没有事实源副本"的孤儿 —— 下一次重建就再也判不出它们了。
+ */
+export declare function restorePreserved(l1: {
+    appendNew: (records: MemoryRecord[]) => Promise<void>;
+    getByIds: (ids: string[]) => MemoryRecord[];
+}, plan: PreservePlan): Promise<PreserveRestoreResult>;
+/** 面向日志/状态栏的一行摘要。 */
+export declare function describePlan(plan: PreservePlan): string;

package/dist/pipeline/rebuild-preserve.js

@@ -0,0 +1,206 @@
+/**
+ * 保留式重建:清空 L1 前判定**哪些记忆不可能被 L0 重蒸馏出来**,并把这些保住。
+ *
+ * ## 为什么需要这个模块
+ *
+ * `RebuildController.prepare()` 的语义是"清空 L1 检索库 → 从 L0 全量重蒸馏"。
+ * 这个语义对**由 L0 蒸馏而来**的记忆是自洽的(清掉也能再造一遍),但对
+ * **不由 L0 派生**的记忆是破坏性的:`memory_add` / `memory_import` 写进来的
+ * 外部记忆(其他 AI 工具导出的记忆包)在任何会话日志里都没有对应位置,
+ * 重建不会再造出它们。实测(`_analysis_output` 探针,2026-09-17)这类记录
+ * 当时有 19 条存活,涉及 `__manual__` 与若干外部导入场景名。
+ *
+ * ## 判据为什么是 `source_message_ids`,而不是"有没有锚点"
+ *
+ * 计划书原稿写的是"无来源记忆(**导入类 / 无锚点类**)",但实测推翻了后半句:
+ *
+ * - 检索库 `l1_records` **没有 `source_message_ids` 列**(见 `types.ts:224` 的
+ *   既有注释"JSONL 事实源保留;检索库不存该列"),所以判据只能来自**事实源**;
+ * - 检索库里 `dsh_source_anchors` 的命中数是 **0/740** —— task_31 落地的锚点
+ *   写入**尚未产出任何一行**(没有新的蒸馏发生过)。把"无锚点"当判据会把
+ *   **全部 740 条**都判成"要保留",重建直接退化成空操作。
+ *
+ * 所以判据取事实源里的 `source_message_ids`:非空 ⇒ 该记忆的位置在 L0 日志里
+ * 有据可查、重建能再造;空/缺失 ⇒ 造不出来,**必须保留**。
+ *
+ * ## 为什么必须取"事实源 ∩ 检索库"
+ *
+ * 事实源是**只增不改**的历史(合并/更新产出新 id 后,旧行仍留在 JSONL)。
+ * 实测:事实源 1,694 个唯一 id,检索库 740 个,`事实源 ∩ 检索库 == 检索库`
+ * (即检索库是事实源的真子集,反向差集为 0)。其中**已从检索库退场、但没有
+ * `source_message_ids` 的有 25 条** —— 按事实源无脑恢复会**复活这 25 条已删记录**。
+ * 故保留集 = 事实源无来源 **且** 检索库仍存在,两个条件缺一不可。
+ *
+ * ## 静默缺席的处理
+ *
+ * 事实源读不出来时,"没有记录需要保留"与"不知道哪些记录需要保留"长得一模一样。
+ * 后者若按前者处理,重建就**静默退化**成原来的破坏性行为。故 `gateClear()` 在
+ * 事实源不可读(或可读但零记录)**且检索库非空**时**拒绝放行**,而不是放行。
+ */
+import { readdir } from 'node:fs/promises';
+import { readJsonl } from '../util/io.js';
+/** 判定单条记录是否可由 L0 重蒸馏出来(事实源侧判据)。 */
+export function isRederivable(record) {
+    const src = record.source_message_ids;
+    return Array.isArray(src) && src.length > 0;
+}
+/**
+ * 读取事实源目录(`<dataDir>/records/*.jsonl`)。
+ *
+ * 只读 `*.jsonl` 顶层文件:`archiveDerived()` 把旧目录整体改名为
+ * `records.bak.<ts>`,它是**兄弟目录**不是文件,不会被 glob 命中。
+ * **必须在 `archiveDerived()` 之前调用** —— 归档之后事实源就搬走了。
+ */
+export async function readFactSource(recordsDir) {
+    let names;
+    try {
+        names = (await readdir(recordsDir)).filter((n) => n.endsWith('.jsonl'));
+    }
+    catch (err) {
+        const code = err?.code;
+        return {
+            ok: false,
+            records: [],
+            files: 0,
+            reason: code === 'ENOENT' ? 'dir-missing' : 'read-error',
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+    // 同名 id 后者胜:JSONL 是追加日志,同日文件里后写的是更新形态。
+    const byId = new Map();
+    for (const name of names) {
+        try {
+            const rows = await readJsonl(`${recordsDir.replace(/[\\/]+$/, '')}/${name}`);
+            for (const r of rows) {
+                if (!r || typeof r.id !== 'string' || !r.id)
+                    continue;
+                byId.set(r.id, r);
+            }
+        }
+        catch (err) {
+            return {
+                ok: false,
+                records: [],
+                files: names.length,
+                reason: 'read-error',
+                detail: `${name}: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    return { ok: true, records: [...byId.values()], files: names.length };
+}
+/**
+ * 出保留计划。纯函数:输入事实源记录 + 检索库现存记录,输出要保留什么。
+ *
+ * 两个方向都保守:事实源说"这条没来源"要留,**检索库里查不到出处**也要留
+ * (`unprovenanced`)—— 判据缺失时留,而不是丢。
+ *
+ * `liveDbRecords` 由调用方从**检索库**取(它没有 `source_message_ids` 列,
+ * 只用来回答"这条还在不在"),恢复时以检索库副本为准 —— 那是当前检索态。
+ */
+export function planPreserve(factRecords, liveDbRecords) {
+    const live = new Map();
+    for (const r of liveDbRecords)
+        if (r && typeof r.id === 'string')
+            live.set(r.id, r);
+    const preserved = [];
+    let rederivable = 0;
+    let retiredNoSource = 0;
+    const seen = new Set();
+    for (const f of factRecords) {
+        if (typeof f?.id !== 'string' || !f.id)
+            continue;
+        seen.add(f.id);
+        if (isRederivable(f)) {
+            // 有来源但已退场(合并掉了)的不必计数——重建会按 L0 再造。
+            if (live.has(f.id))
+                rederivable++;
+            continue;
+        }
+        const current = live.get(f.id);
+        if (!current) {
+            retiredNoSource++;
+            continue;
+        }
+        preserved.push({
+            record: current,
+            reason: String(current.content ?? '').trim() ? 'no-source' : 'empty-content',
+        });
+    }
+    // 检索库里有、事实源里没有 ⇒ 来源无从证明,一律保留(见 PreserveReason 注释)。
+    for (const [id, r] of live) {
+        if (seen.has(id))
+            continue;
+        preserved.push({ record: r, reason: 'unprovenanced' });
+    }
+    preserved.sort((a, b) => a.record.id.localeCompare(b.record.id));
+    return {
+        preserved,
+        rederivable,
+        retiredNoSource,
+        factCount: factRecords.length,
+        dbCount: live.size,
+    };
+}
+/**
+ * 清空前的守门判定。
+ *
+ * 拒绝而不是放行,是因为"没有需要保留的"与"不知道有没有需要保留的"在数据上
+ * 无法区分(见文件头「静默缺席的处理」)。检索库为空时不存在可失去的记忆,
+ * 故那一路照常放行 —— 不把功能卡死在干净环境上。
+ */
+export function gateClear(read, plan) {
+    if (plan.dbCount === 0) {
+        return { allowed: true, code: 'empty-db', note: '检索库为空,无可保留项' };
+    }
+    if (!read.ok) {
+        const why = read.reason === 'dir-missing' ? '事实源目录不存在' : `事实源读取失败(${read.detail ?? '未知原因'})`;
+        return {
+            allowed: false,
+            code: 'source-missing',
+            note: `${why},而检索库有 ${plan.dbCount} 条记忆 —— 无法判定其中哪些不是从 L0 蒸馏来的,` +
+                '已中止重建且**未清空任何数据**。请先恢复 records/ 事实源(或从 snapshots/ 的快照找回)后重试。',
+        };
+    }
+    if (read.records.length === 0) {
+        return {
+            allowed: false,
+            code: 'source-empty',
+            note: `事实源可读但一条记录都没有,而检索库有 ${plan.dbCount} 条记忆 —— 事实源与检索库不一致,` +
+                '已中止重建且**未清空任何数据**。请检查 records/ 是否被清空或迁移过。',
+        };
+    }
+    const keep = plan.preserved.length;
+    return {
+        allowed: true,
+        code: 'ok',
+        note: keep > 0
+            ? `保留 ${keep} 条无 L0 来源的记忆(导入/手工写入),重建只重造 ${plan.rederivable} 条有来源的记忆`
+            : `无无来源记忆需要保留,重建重造 ${plan.rederivable} 条有来源的记忆`,
+    };
+}
+/**
+ * 把保留集放回检索库 + 事实源。
+ *
+ * 走 `L1Store.appendNew` 而不是 `db.upsertL1`:前者**双写**(JSONL 事实源 + 检索库),
+ * 而此刻 `records/` 刚被 `archiveDerived()` 改名走,只写检索库会让这些记忆
+ * 再次成为"没有事实源副本"的孤儿 —— 下一次重建就再也判不出它们了。
+ */
+export async function restorePreserved(l1, plan) {
+    const ids = plan.preserved.map((p) => p.record.id);
+    if (ids.length === 0)
+        return { attempted: 0, restored: 0, missing: [] };
+    await l1.appendNew(plan.preserved.map((p) => p.record));
+    const back = new Set(l1.getByIds(ids).map((r) => r.id));
+    const missing = ids.filter((id) => !back.has(id));
+    return { attempted: ids.length, restored: ids.length - missing.length, missing };
+}
+/** 面向日志/状态栏的一行摘要。 */
+export function describePlan(plan) {
+    const byReason = new Map();
+    for (const p of plan.preserved)
+        byReason.set(p.reason, (byReason.get(p.reason) ?? 0) + 1);
+    const parts = [...byReason].map(([r, n]) => `${r} ${n}`);
+    return (`保留 ${plan.preserved.length} 条无来源记忆${parts.length ? `(${parts.join(' / ')})` : ''};` +
+        `可重蒸馏 ${plan.rederivable} 条;事实源 ${plan.factCount} 条(其中无来源但已退场 ${plan.retiredNoSource} 条,不恢复)`);
+}

package/dist/pipeline/rebuild.js

@@ -3,19 +3,28 @@
  *
  * 语义(CONTEXT.md「重建」):
  * - L0 永不改动;旧派生层归档保留(records/ scenes/ persona-*.md → *.bak.<ts>,不硬删);
- * - 检索库 L1 三表清空、checkpoint 原地重置;
+ * - 检索库 L1 清空、checkpoint 原地重置;
  * - 统一按 auto 档、按会话分块重蒸馏;分块经 runner 的低优先级队列让位于正常轮次;
  * - 收尾强制一轮 L2(各族残余记录)+ L3(重建后 hasPersona=false → 冷启动触发)。
  *
+ * **保留式清空(task_8c)**:"清空 + 重蒸馏"对**由 L0 派生**的记忆自洽,对
+ * **不由 L0 派生**的记忆则是破坏性的:`memory_add` / `memory_import` 写进来的
+ * 外部记忆在会话日志里没有对应位置,清掉就再也造不出来。故 `prepare()` 的固定顺序为
+ * **读事实源 → 判保留集 → 过闸门 → 快照 → 归档 → 清空 → 放回保留集**;
+ * 判据与实测依据见 `rebuild-preserve.ts` 文件头。事实源读不到时**拒绝清空** ——
+ * 判不出该保留什么,放行等于静默退化成破坏性重建。
+ *
  * 失败语义:准备/归档任一步失败 → phase=failed,绝不拖垮宿主;
  * 单块蒸馏失败继续下一块(消息留在未蒸馏缓冲,下轮对话/重启补跑自愈)。
  */
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { resolveDataDir } from '../config.js';
+import { snapshotBeforeClear } from '../store/l1-snapshot.js';
 import { errDetail } from '../util/filelog.js';
 import { runSceneConsolidation } from './l2.js';
 import { runPersona } from './l3.js';
+import { describePlan, gateClear, planPreserve, readFactSource, restorePreserved } from './rebuild-preserve.js';
 import { effectiveCfg } from './runner.js';
 export function groupL0Sessions(records) {
     const bySession = new Map();
@@ -62,6 +71,7 @@ function idleStatus() {
         finishedAt: null,
         error: null,
         archiveNote: null,
+        preserveNote: null,
     };
 }
 /** 时间戳后缀(归档命名,秒级防撞)。 */
@@ -149,12 +159,35 @@ export class RebuildController {
                 return;
             }
             this.status.total = this.chunks.length;
-            // 归档旧派生层(改名不硬删;任一失败即终止——半清半留会破坏"全量重导"语义)
+            const dataDir = resolveDataDir(this.cfg);
+            // ── ① 读事实源 + 判定保留集(必须在 archiveDerived 之前:归档会把 records/ 搬走)──
+            const factRead = await readFactSource(path.join(dataDir, 'records'));
+            const plan = planPreserve(factRead.records, this.stores.l1.all());
+            // ── ② 过闸门:判不出该保留什么时**拒绝清空**(见 rebuild-preserve.ts 文件头)──
+            const gate = gateClear(factRead, plan);
+            if (!gate.allowed) {
+                this.logger.error(`[memory] 重建已中止:${gate.note}`);
+                this.finish('failed', gate.note);
+                return;
+            }
+            // ── ③ 先快照后清空:快照失败即终止(此刻还没清任何东西,中止是零代价的)──
+            const snap = await snapshotBeforeClear(this.db, dataDir, 'pre-rebuild');
+            this.logger.info(`[memory] 重建前快照已建:${path.basename(snap.dir)}(${snap.manifest.sections.records.count} 条,哈希 ${snap.manifest.sections.records.hash.slice(0, 8)})`);
+            // ── ④ 归档旧派生层(改名不硬删;任一失败即终止——半清半留会破坏"全量重导"语义)──
             const archiveNote = await this.archiveDerived();
             this.status.archiveNote = archiveNote ?? null;
-            // 清检索库 + 重置 checkpoint;归档后重建空目录(records/ 由 appendNew 自动重建)
+            // ── ⑤ 清检索库 + 重置 checkpoint;归档后重建空目录(records/ 由 appendNew 自动重建)──
             if (!this.db.clearL1())
                 throw new Error('L1 检索库清空失败');
+            // ── ⑥ 把无来源记忆放回:清空后立刻、且在首块蒸馏之前 ——
+            //     放回后它们在检索库里,后续 L1 去重候选就能看见它们,不会重复造出新副本。
+            const restored = await restorePreserved(this.stores.l1, plan);
+            if (restored.missing.length > 0) {
+                // 不静默:保留集里没回来的 id 必须点名(它们在快照里,可手工找回)
+                this.logger.error(`[memory] 保留集恢复不完整:${restored.restored}/${restored.attempted} 条,缺失 ${restored.missing.join(', ')}` +
+                    `(缺失项仍在本轮快照 ${path.basename(snap.dir)} 中)`);
+            }
+            this.status.preserveNote = describePlan(plan);
             this.stores.state.reset();
             await this.stores.state.save();
             await Promise.all([
@@ -164,7 +197,7 @@ export class RebuildController {
                 this.stores.persona.work.init(),
             ]);
             this.status.phase = 'distilling';
-            this.logger.info(`[memory] 重建准备完成(归档:${archiveNote ?? '无旧产物'},${this.chunks.length} 个会话块)`);
+            this.logger.info(`[memory] 重建准备完成(归档:${archiveNote ?? '无旧产物'},保留:${this.status.preserveNote},${this.chunks.length} 个会话块)`);
             this.scheduleChunk(0);
         }
         catch (err) {

package/dist/pipeline/reconcile-run.d.ts

@@ -0,0 +1,102 @@
+import type { EvidenceSource } from '../store/evidence-source.js';
+import type { MemoryLogger } from '../types.js';
+import { type MemoryVerdict, type ReconcileDeps, type ReconcileInput, type ReconcileState } from './reconcile.js';
+/**
+ * 三重上限 + 调用数上限。**每一项都是硬闸门**:超了就裁掉并在计划里写清楚裁了什么。
+ */
+export interface ReconcileBudget {
+    /** 单次运行最多核对多少条记忆。 */
+    maxRecords: number;
+    /** 单条记忆最多用几个锚点(锚点多 = 证据长 = 贵)。 */
+    maxAnchorsPerMemory: number;
+    /** 单条记忆的证据文本上限(字符)。 */
+    maxEvidenceChars: number;
+    /** 单次运行最多多少次模型调用(有锚点且未完成的条目才会产生调用)。 */
+    maxCalls: number;
+}
+export declare const DEFAULT_RECONCILE_BUDGET: ReconcileBudget;
+/** 预估结果(展示给人看的就是这个)。 */
+export interface ReconcileEstimate {
+    /** 输入里一共有多少条记忆。 */
+    total: number;
+    /** 其中带锚点(会花钱)的条数。 */
+    billable: number;
+    /** 没有锚点(免费,直接跳过)的条数。 */
+    skippedNoAnchor: number;
+    /** 因上限被裁掉的条数。 */
+    trimmedByRecords: number;
+    /** 因 `maxCalls` 被裁掉的条数。 */
+    trimmedByCalls: number;
+    /** 会被使用的锚点总数(裁剪后)。 */
+    anchors: number;
+    /** 已在上次运行中完成、本次不会重复计费的条数。 */
+    alreadyDone: number;
+    /** 输入字符上界(记忆正文 + 证据上限)。 */
+    estInputChars: number;
+    /** 输入 token 上界(按既有 CHARS_PER_TOKEN 口径,与官方同式)。 */
+    estInputTokens: number;
+    /** 模型调用次数上界。 */
+    estCalls: number;
+}
+/** 预估 + 裁剪后的执行计划。**只有它能进 `executeReconcile`。** */
+export interface ReconcilePlan {
+    budget: ReconcileBudget;
+    estimate: ReconcileEstimate;
+    /** 裁剪后的待核对条目。 */
+    memories: readonly ReconcileInput[];
+    /** 人类可读的预估说明(面板/CLI 直接展示)。 */
+    summary: string;
+}
+/** 断点续跑状态文件。 */
+export interface ReconcileRunState {
+    version: 1;
+    runId: string;
+    startedAt: number;
+    updatedAt: number;
+    /** 已完成条目键:`<memoryId>:<内容哈希前 8 位>`。 */
+    done: string[];
+}
+/** 内容哈希前 8 位:**正文一变就必须重核**(见模块头注释)。 */
+export declare function contentHash(text: string): string;
+/** 续跑键:`(memoryId, 内容哈希)`。 */
+export declare function resumeKey(memory: Pick<ReconcileInput, 'id' | 'text'>): string;
+/** 状态文件路径(与 `pendingPathFor` / `state.json` 同目录)。 */
+export declare function reconcileStatePathFor(dataDir: string): string;
+/** 读状态;**文件损坏/版本不符一律当作空状态**,不抛(续跑状态坏了不该阻止运行)。 */
+export declare function loadRunState(file: string): Promise<ReconcileRunState | undefined>;
+/**
+ * 预估并裁剪。
+ *
+ * @param memories - 全部候选记忆。
+ * @param budget - 三重上限。
+ * @param doneKeys - 上次已完成、本次要跳过的键。
+ * @returns 预估 + 计划。**这是唯一能产出 `ReconcilePlan` 的入口。**
+ */
+export declare function planReconcile(memories: readonly ReconcileInput[], budget?: ReconcileBudget, doneKeys?: readonly string[]): ReconcilePlan;
+/** 预估说明(先给人看)。**必须写清裁掉了什么**——只报"要跑多少"会让人以为跑全了。 */
+export declare function renderEstimate(estimate: ReconcileEstimate, budget: ReconcileBudget): string;
+export interface ExecuteReconcileOptions {
+    signal?: AbortSignal;
+    /** 状态文件路径;不传则不落盘(纯内存运行)。 */
+    stateFile?: string;
+    logger?: MemoryLogger;
+    onProgress?: (done: number, total: number, verdict: MemoryVerdict) => void;
+}
+export interface ExecuteReconcileResult {
+    verdicts: MemoryVerdict[];
+    report: string;
+    counts: Record<ReconcileState, number>;
+    /** 本次是否因中断提前结束(续跑时从状态文件接着来)。 */
+    interrupted: boolean;
+    state?: ReconcileRunState;
+}
+/**
+ * 执行计划(只读;唯一的副作用是写**续跑状态文件**,不是记忆库)。
+ *
+ * 逐条执行、**每条完成后原子落盘**:进程被杀也能续跑,已完成的不重复计费。
+ */
+export declare function executeReconcile(deps: ReconcileDeps, plan: ReconcilePlan, opts?: ExecuteReconcileOptions): Promise<ExecuteReconcileResult>;
+/** 清空续跑状态(显式动作:下次运行会重核所有条目,**会重复计费**)。 */
+export declare function resetRunState(file: string): Promise<void>;
+/** 供装配层使用:把证据面与 judge 组装成 deps。 */
+export declare function makeReconcileDeps(evidence: EvidenceSource, judge: ReconcileDeps['judge'], logger?: MemoryLogger): ReconcileDeps;