dsh-prime-memory 0.26.10 → 0.26.12

package/dist/pipeline/fact-source.d.ts

@@ -0,0 +1,127 @@
+/**
+ * 重建事实源抽象（issue #14-B）。
+ *
+ * ## 为什么需要这一层
+ *
+ * 重建原先硬编码 `MemoryDb.listL0All()`：写入侧（capture）自 T8.4 起已把 L0 正文停写、
+ * 历史面交给 DRSC 投影，读侧却仍只认本地那张**冻结表**。这层把「事实源」抽成可替换的
+ * provider，让本地 L0 与 DRSC 两套实现共用同一条重建管线。
+ *
+ * ## 两个刻意的设计约束
+ *
+ * 1. **`estimate()` 必须同步**：`RebuildController.start()` 是同步 RPC，要在返回前就
+ *    给出体量与"能不能重建"的判定。DRSC 做不到同步报数，故 `FactEstimate.known=false`
+ *    表示"未知"，调用方据此**跳过**同步前置门（改在 prepare 阶段用实际结果判定）。
+ * 2. **`chunks()` 而不是"先全量再分组"**：`listL0All()` 在 3 万条量级上峰值约 88MB 且
+ *    整个重建期常驻。按会话产出块，峰值降到单会话量级。`groupL0Sessions` 仍保留为
+ *    纯函数（测试与本地实现的组装点），但生产路径按会话流式拉取。
+ *
+ * ## 不丢优先
+ *
+ * `snapshotIds()` 给 `planPreserve` 判 `post-watermark` 用。DRSC 实现**无法**枚举消息 id
+ * （id 是采集端合成的 `drsc:<sid>:<seq>`，与事实源里的 `source_message_ids` 不同域），
+ * 因此返回空集 —— 效果是**全部判为不可重蒸、全部保留**。这是安全侧失败：多保留只是多
+ * 一条待去重，丢掉是不可逆。
+ */
+import type { ConversationMessage, MemoryLogger } from '../types.js';
+import type { DrscClient } from '../clients/drsc.js';
+import type { MemoryDb } from '../store/sqlite.js';
+/** 重建分块：一个会话的全部消息（按时间升序）。 */
+export interface RebuildChunk {
+    sessionId: string;
+    messages: ConversationMessage[];
+}
+/** 事实源侧的一条消息（与 `L0MessageRecord` 结构兼容，但不带 recordedAt/turn/step）。 */
+export interface FactMessage {
+    id: string;
+    sessionId: string;
+    role: 'user' | 'assistant';
+    content: string;
+    timestamp: number;
+}
+/** 体量预估。`known=false` = 事实源无法同步报数（DRSC），字段值不可作为判定依据。 */
+export interface FactEstimate {
+    sessions: number;
+    messages: number;
+    chars: number;
+    known: boolean;
+}
+/** 事实源覆盖范围（面板"重建只覆盖到 X"的依据）。 */
+export interface FactCoverage {
+    /** 覆盖到的时刻（ISO）；null = 未知/无正文。 */
+    untilIso: string | null;
+    sessions: number;
+}
+export interface FactSourceProvider {
+    readonly kind: 'l0-local' | 'drsc';
+    /** 同步体量预估；`known=false` 时调用方不得据此做拒绝判定。 */
+    estimate(): FactEstimate;
+    /**
+     * 异步精确预估 + 内部预取（DRSC 在这里一次性枚举会话，`chunks()` 复用缓存）。
+     *
+     * 与 `estimate()` 的分工：后者是同步门（`start()` 返回前就要有结论），
+     * 前者是 prepare 阶段的真实体量（能发请求、能报准确会话数）。
+     */
+    prepare(): Promise<FactEstimate>;
+    /** 消息级流（诊断/测试用；生产走 chunks）。 */
+    snapshot(): AsyncIterable<FactMessage>;
+    /** 会话级流 —— 生产路径：单会话内存，不驻留全量正文。 */
+    chunks(): AsyncIterable<RebuildChunk>;
+    /**
+     * 本次事实源的**消息 id 集**，供 `post-watermark` 判据。
+     * 空集 = "判不出来" ⇒ 所有有来源的记录都会被保守判为不可重蒸并保留。
+     */
+    snapshotIds(): Promise<ReadonlySet<string>>;
+    coverage(): FactCoverage;
+}
+/**
+ * 把一批事实消息按会话分组（纯函数）。
+ *
+ * 保留这个签名是因为它有两个真实用途：① 本地实现按"一次全量"路径时可复用；
+ * ② 测试要能直接断言分组与排序语义而不必起 provider。生产路径用 `chunks()` 流式，
+ * 不经过这里 —— 否则又把全量正文攒回内存了。
+ *
+ * **仍然做归一 + 过滤**（与迁移前同口径）：入参允许是原始 L0 行，非法行（id 空、
+ * role 非 user/assistant、正文空）一律丢弃。过滤不能只留在 provider 里，
+ * 否则任何直接调本函数的调用方（含测试夹具）都得自己重复一遍。
+ */
+export declare function groupL0Sessions(records: Iterable<FactMessage | Readonly<Record<string, unknown>>>): RebuildChunk[];
+/** 本地 L0 事实源（默认）：已停写的冻结存量，读面走会话点查避免全量驻留。 */
+export declare class LocalL0FactSource implements FactSourceProvider {
+    private readonly db;
+    private readonly logger;
+    readonly kind: "l0-local";
+    constructor(db: MemoryDb, logger: MemoryLogger);
+    estimate(): FactEstimate;
+    prepare(): Promise<FactEstimate>;
+    coverage(): FactCoverage;
+    snapshotIds(): Promise<ReadonlySet<string>>;
+    snapshot(): AsyncIterable<FactMessage>;
+    chunks(): AsyncIterable<RebuildChunk>;
+}
+/**
+ * DRSC 事实源（实验性，默认不用）：枚举会话 → 逐会话拉全量。
+ *
+ * 顺序说明：collector 的 `op=sessions` 按 `last_time_ms` **降序**返回，这里显式反转成
+ * 升序，与本地实现的"会话按首条时间升序"对齐（上下文链的衔接方向一致）。
+ */
+export declare class DrscFactSource implements FactSourceProvider {
+    private readonly client;
+    private readonly logger;
+    /** 会话分页大小（collector 侧钳 1..500）。 */
+    private readonly pageSize;
+    readonly kind: "drsc";
+    constructor(client: DrscClient, logger: MemoryLogger, 
+    /** 会话分页大小（collector 侧钳 1..500）。 */
+    pageSize?: number);
+    estimate(): FactEstimate;
+    /** 会话枚举缓存（prepare 拉一次，chunks/snapshot 复用，不重复请求）。 */
+    private sessionsCache;
+    prepare(): Promise<FactEstimate>;
+    coverage(): FactCoverage;
+    snapshotIds(): Promise<ReadonlySet<string>>;
+    private listAllSessions;
+    private sessions;
+    snapshot(): AsyncIterable<FactMessage>;
+    chunks(): AsyncIterable<RebuildChunk>;
+}

package/dist/pipeline/fact-source.js

@@ -0,0 +1,192 @@
+import { drscRoleOf } from '../clients/drsc.js';
+/** L0 记录 → 事实消息（角色/内容过滤与 `groupL0Sessions` 同口径）。 */
+function factMessageOf(rec) {
+    const id = typeof rec.id === 'string' ? rec.id : '';
+    if (id === '')
+        return undefined;
+    const role = rec.role === 'user' || rec.role === 'assistant' ? rec.role : undefined;
+    if (role === undefined)
+        return undefined;
+    const content = typeof rec.content === 'string' ? rec.content : '';
+    if (content.trim() === '')
+        return undefined;
+    return {
+        id,
+        sessionId: typeof rec.sessionId === 'string' && rec.sessionId !== '' ? rec.sessionId : 'default',
+        role,
+        content,
+        timestamp: typeof rec.timestamp === 'number' && Number.isFinite(rec.timestamp) ? rec.timestamp : 0,
+    };
+}
+/**
+ * 把一批事实消息按会话分组（纯函数）。
+ *
+ * 保留这个签名是因为它有两个真实用途：① 本地实现按"一次全量"路径时可复用；
+ * ② 测试要能直接断言分组与排序语义而不必起 provider。生产路径用 `chunks()` 流式，
+ * 不经过这里 —— 否则又把全量正文攒回内存了。
+ *
+ * **仍然做归一 + 过滤**（与迁移前同口径）：入参允许是原始 L0 行，非法行（id 空、
+ * role 非 user/assistant、正文空）一律丢弃。过滤不能只留在 provider 里，
+ * 否则任何直接调本函数的调用方（含测试夹具）都得自己重复一遍。
+ */
+export function groupL0Sessions(
+// 入参保持宽松：原始 L0 行（多带 recordedAt/turn/step）与 FactMessage 都能喂。
+records) {
+    const bySession = new Map();
+    for (const raw of records) {
+        const msg = factMessageOf(raw);
+        if (msg === undefined)
+            continue;
+        const arr = bySession.get(msg.sessionId) ?? [];
+        arr.push({ id: msg.id, role: msg.role, content: msg.content, timestamp: msg.timestamp });
+        bySession.set(msg.sessionId, arr);
+    }
+    const chunks = [];
+    for (const [sessionId, messages] of bySession) {
+        messages.sort((a, b) => a.timestamp - b.timestamp);
+        chunks.push({ sessionId, messages });
+    }
+    // 会话按首条消息时间升序:情境链按时间顺序衔接(与原始发生顺序一致)
+    chunks.sort((a, b) => a.messages[0].timestamp - b.messages[0].timestamp);
+    return chunks;
+}
+/** 本地 L0 事实源（默认）：已停写的冻结存量，读面走会话点查避免全量驻留。 */
+export class LocalL0FactSource {
+    db;
+    logger;
+    kind = 'l0-local';
+    constructor(db, logger) {
+        this.db = db;
+        this.logger = logger;
+    }
+    estimate() {
+        const est = this.db.l0RebuildEstimate();
+        return { ...est, known: true };
+    }
+    async prepare() {
+        return this.estimate();
+    }
+    coverage() {
+        const wm = this.db.rebuildWatermark();
+        return { untilIso: wm.l0Iso, sessions: wm.l0SessionCount };
+    }
+    async snapshotIds() {
+        // 只读 record_id 列，不碰正文 —— 这是"不发 88MB 也要能判 post-watermark"的关键。
+        return this.db.l0MessageIds();
+    }
+    async *snapshot() {
+        for (const sessionId of this.db.l0SessionIds()) {
+            for (const rec of this.db.l0MessagesBySession(sessionId)) {
+                const msg = factMessageOf({ ...rec, id: rec.id });
+                if (msg !== undefined)
+                    yield msg;
+            }
+        }
+    }
+    async *chunks() {
+        const sessions = this.db.l0SessionIds();
+        this.logger.debug?.(`[memory] 重建事实源：本地 L0，${sessions.length} 个会话（按会话流式读）`);
+        for (const sessionId of sessions) {
+            const messages = [];
+            for (const rec of this.db.l0MessagesBySession(sessionId)) {
+                const msg = factMessageOf({ ...rec, id: rec.id });
+                if (msg !== undefined)
+                    messages.push({ id: msg.id, role: msg.role, content: msg.content, timestamp: msg.timestamp });
+            }
+            if (messages.length > 0)
+                yield { sessionId, messages };
+        }
+    }
+}
+/**
+ * DRSC 事实源（实验性，默认不用）：枚举会话 → 逐会话拉全量。
+ *
+ * 顺序说明：collector 的 `op=sessions` 按 `last_time_ms` **降序**返回，这里显式反转成
+ * 升序，与本地实现的"会话按首条时间升序"对齐（上下文链的衔接方向一致）。
+ */
+export class DrscFactSource {
+    client;
+    logger;
+    pageSize;
+    kind = 'drsc';
+    constructor(client, logger, 
+    /** 会话分页大小（collector 侧钳 1..500）。 */
+    pageSize = 200) {
+        this.client = client;
+        this.logger = logger;
+        this.pageSize = pageSize;
+    }
+    estimate() {
+        // 同步拿不到（要发请求）。known=false 让调用方跳过同步前置门，
+        // 真正的“空事实源”判定落在 prepare 的会话数上。
+        return { sessions: 0, messages: 0, chars: 0, known: false };
+    }
+    /** 会话枚举缓存（prepare 拉一次，chunks/snapshot 复用，不重复请求）。 */
+    sessionsCache = null;
+    async prepare() {
+        this.sessionsCache = await this.listAllSessions();
+        return { sessions: this.sessionsCache.length, messages: 0, chars: 0, known: true };
+    }
+    coverage() {
+        return { untilIso: null, sessions: 0 };
+    }
+    async snapshotIds() {
+        this.logger.warn('[memory] DRSC 事实源无法枚举消息 id（drsc:<sid>:<seq> 与 source_message_ids 不同域）——'
+            + '本轮重建会把所有有来源的记忆判为不可重蒸并原样保留（保守侧失败，不丢数据）');
+        return new Set();
+    }
+    async listAllSessions() {
+        const ids = [];
+        let offset = 0;
+        for (;;) {
+            const page = await this.client.listSessions(offset, this.pageSize);
+            for (const row of page.rows) {
+                if (typeof row.session_id === 'string' && row.session_id !== '') {
+                    ids.push({ id: row.session_id, last: row.last_time_ms });
+                }
+            }
+            offset += page.rows.length;
+            if (page.rows.length === 0 || offset >= page.total)
+                break;
+        }
+        // 反转 collector 的 last_time_ms 降序 → 升序（见类注释）
+        return ids.sort((a, b) => a.last - b.last).map((r) => r.id);
+    }
+    async sessions() {
+        if (this.sessionsCache !== null)
+            return this.sessionsCache;
+        this.sessionsCache = await this.listAllSessions();
+        return this.sessionsCache;
+    }
+    async *snapshot() {
+        for (const sessionId of await this.sessions()) {
+            for (const row of await this.client.sessionAll(sessionId)) {
+                const role = drscRoleOf(row.kind);
+                if (role === undefined)
+                    continue;
+                if (row.text.trim() === '')
+                    continue;
+                yield { id: `drsc:${sessionId}:${row.seq}`, sessionId, role, content: row.text, timestamp: row.time };
+            }
+        }
+    }
+    async *chunks() {
+        const sessions = await this.sessions();
+        this.logger.info(`[memory] 重建事实源：DRSC，${sessions.length} 个会话（逐会话拉全量，redact=1）`);
+        for (const sessionId of sessions) {
+            const rows = await this.client.sessionAll(sessionId);
+            const messages = [];
+            for (const row of rows) {
+                const role = drscRoleOf(row.kind);
+                if (role === undefined)
+                    continue;
+                if (row.text.trim() === '')
+                    continue;
+                messages.push({ id: `drsc:${sessionId}:${row.seq}`, role, content: row.text, timestamp: row.time });
+            }
+            messages.sort((a, b) => a.timestamp - b.timestamp);
+            if (messages.length > 0)
+                yield { sessionId, messages };
+        }
+    }
+}

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

@@ -54,8 +54,19 @@ export interface FactSourceRead {
 export type PreserveReason = 
 /** 事实源里没有 `source_message_ids` —— 不是从 L0 蒸馏来的。 */
 'no-source'
-/** 内容为空白 —— 重蒸馏不会产出空记忆,保留它也无从重造。 */
+/** 内容为空白 —— 重蒸馏不会产出空记忆，保留它也无从重造。 */
  | 'empty-content'
+/**
+ * 来源消息**不在本次 L0 快照内**。
+ *
+ * 与 `no-source` 的区别：这条记录**有**来源 id，但那些 id 指向的消息不在本次
+ * 重建的事实源里——结构上重蒸不出来，故必须保留。
+ *
+ * 典型成因是 L0 写停（T8.4 后 l0 正文三表退役）：停写之后新增的 L1 记录
+ * 全部落这一类。判据用**集合包含**而不是时间差——L1 的 `created_time` 会随
+ * 每次蒸馏前移，任何时间阈值终将被跳过，用它做门槛会把重建**永久锁死**。
+ */
+ | 'post-watermark'
 /**
  * 检索库里有、事实源里**完全没有**这一行 —— 来源无从证明。
  *
@@ -86,6 +97,14 @@ export interface PreservePlan {
 }
 /** 判定单条记录是否可由 L0 重蒸馏出来(事实源侧判据)。 */
 export declare function isRederivable(record: MemoryRecord): boolean;
+/**
+ * 来源是否**全部**落在本次快照内。
+ *
+ * `every` 而不是 `some`：只要有一张原料缺失，重蒸馏就只会产出一个缺角的新记录，
+ * 不如原样保留。无来源时返回 `false`——但那一类由 `no-source` 先行接住，
+ * 不应依赖本函数的返回值。
+ */
+export declare function sourcesCoveredBySnapshot(record: MemoryRecord, snapshotIds: ReadonlySet<string>): boolean;
 /**
  * 读取事实源目录(`<dataDir>/records/*.jsonl`)。
  *
@@ -103,7 +122,17 @@ export declare function readFactSource(recordsDir: string): Promise<FactSourceRe
  * `liveDbRecords` 由调用方从**检索库**取(它没有 `source_message_ids` 列,
  * 只用来回答"这条还在不在"),恢复时以检索库副本为准 —— 那是当前检索态。
  */
-export declare function planPreserve(factRecords: readonly MemoryRecord[], liveDbRecords: readonly MemoryRecord[]): PreservePlan;
+export interface PreserveOptions {
+    /**
+     * 本次重建事实源（L0 快照）的**消息 id 集**。
+     *
+     * 不给 = 保持旧口径（只看"有无来源"）。给了才能判 `post-watermark`，
+     * 而**给了才是安全的**：L0 已写停的库只看"有无来源"会把停写后的记录
+     * 当成可重蒸，清库后真的丢。
+     */
+    readonly snapshotIds?: ReadonlySet<string>;
+}
+export declare function planPreserve(factRecords: readonly MemoryRecord[], liveDbRecords: readonly MemoryRecord[], opts?: PreserveOptions): PreservePlan;
 /** 清空闸门的判定码。 */
 export type ClearGateCode = 
 /** 放行。 */

package/dist/pipeline/rebuild-preserve.js

@@ -44,6 +44,19 @@ export function isRederivable(record) {
     const src = record.source_message_ids;
     return Array.isArray(src) && src.length > 0;
 }
+/**
+ * 来源是否**全部**落在本次快照内。
+ *
+ * `every` 而不是 `some`：只要有一张原料缺失，重蒸馏就只会产出一个缺角的新记录，
+ * 不如原样保留。无来源时返回 `false`——但那一类由 `no-source` 先行接住，
+ * 不应依赖本函数的返回值。
+ */
+export function sourcesCoveredBySnapshot(record, snapshotIds) {
+    const src = record.source_message_ids;
+    if (!Array.isArray(src) || src.length === 0)
+        return false;
+    return src.every((id) => snapshotIds.has(id));
+}
 /**
  * 读取事实源目录(`<dataDir>/records/*.jsonl`)。
  *
@@ -89,16 +102,7 @@ export async function readFactSource(recordsDir) {
     }
     return { ok: true, records: [...byId.values()], files: names.length };
 }
-/**
- * 出保留计划。纯函数:输入事实源记录 + 检索库现存记录,输出要保留什么。
- *
- * 两个方向都保守:事实源说"这条没来源"要留,**检索库里查不到出处**也要留
- * (`unprovenanced`)—— 判据缺失时留,而不是丢。
- *
- * `liveDbRecords` 由调用方从**检索库**取(它没有 `source_message_ids` 列,
- * 只用来回答"这条还在不在"),恢复时以检索库副本为准 —— 那是当前检索态。
- */
-export function planPreserve(factRecords, liveDbRecords) {
+export function planPreserve(factRecords, liveDbRecords, opts = {}) {
     const live = new Map();
     for (const r of liveDbRecords)
         if (r && typeof r.id === 'string')
@@ -112,6 +116,21 @@ export function planPreserve(factRecords, liveDbRecords) {
             continue;
         seen.add(f.id);
         if (isRederivable(f)) {
+            // 顺序纪律：「外部可重蒸」必须在「post-watermark 保留」**之后**判。
+            // 停写后新增的记录 `source_message_ids` 非空，但指向的消息在本地
+            // `l0_conversations` 已查不到 —— 清库后蒸不出来，等于丢失；
+            // 而按旧口径（只看非空）它们恰好会被归进 `rederivable` 然后被清掉。
+            if (opts.snapshotIds && !sourcesCoveredBySnapshot(f, opts.snapshotIds)) {
+                const current = live.get(f.id);
+                // 已退场的不复活（与 no-source 分支同口径）
+                if (current) {
+                    preserved.push({
+                        record: current,
+                        reason: String(current.content ?? '').trim() ? 'post-watermark' : 'empty-content',
+                    });
+                }
+                continue;
+            }
             // 有来源但已退场(合并掉了)的不必计数——重建会按 L0 再造。
             if (live.has(f.id))
                 rederivable++;
@@ -175,8 +194,8 @@ export function gateClear(read, plan) {
         allowed: true,
         code: 'ok',
         note: keep > 0
-            ? `保留 ${keep} 条无 L0 来源的记忆(导入/手工写入),重建只重造 ${plan.rederivable} 条有来源的记忆`
-            : `无无来源记忆需要保留,重建重造 ${plan.rederivable} 条有来源的记忆`,
+            ? `保留 ${keep} 条不可重蒸的记忆(导入/手工写入/来源不在本次快照),重建只重造 ${plan.rederivable} 条有来源的记忆`
+            : `无不可重蒸记忆需要保留,重建重造 ${plan.rederivable} 条有来源的记忆`,
     };
 }
 /**
@@ -195,12 +214,19 @@ export async function restorePreserved(l1, plan) {
     const missing = ids.filter((id) => !back.has(id));
     return { attempted: ids.length, restored: ids.length - missing.length, missing };
 }
+/** reason → 中文标签（日志/状态栏直接给人看，不再打印英文枚举）。 */
+const REASON_LABEL = {
+    'no-source': '无来源',
+    'empty-content': '内容为空',
+    unprovenanced: '来源无从证明',
+    'post-watermark': '来源不在本次快照',
+};
 /** 面向日志/状态栏的一行摘要。 */
 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(' / ')})` : ''};` +
+    const parts = [...byReason].map(([r, n]) => `${REASON_LABEL[r] ?? r} ${n}`);
+    return (`保留 ${plan.preserved.length} 条不可重蒸记忆${parts.length ? `(${parts.join(' / ')})` : ''};` +
         `可重蒸馏 ${plan.rederivable} 条;事实源 ${plan.factCount} 条(其中无来源但已退场 ${plan.retiredNoSource} 条,不恢复)`);
 }

package/dist/pipeline/rebuild.d.ts

@@ -6,24 +6,36 @@ import type { SceneStore } from '../store/scenes.js';
 import type { StateStore } from '../store/state.js';
 import type { MemoryDb } from '../store/sqlite.js';
 import type { LiveSettingsHandle } from '../settings.js';
-import type { ConversationMessage, L0MessageRecord, MemoryFamily, MemoryLogger } from '../types.js';
+import type { MemoryFamily, MemoryLogger } from '../types.js';
 import { type MemoryRunner } from './runner.js';
+import type { DrscClient } from '../clients/drsc.js';
+export type { FactCoverage, FactEstimate, FactMessage, FactSourceProvider, RebuildChunk } from './fact-source.js';
+export { DrscFactSource, groupL0Sessions, LocalL0FactSource } from './fact-source.js';
 /** 重建所需的存储子集(l0 不需要——快照直接走 db)。 */
 export interface RebuildStores {
     l1: L1Store;
     scenes: Record<MemoryFamily, SceneStore>;
     persona: Record<MemoryFamily, PersonaStore>;
     state: StateStore;
+    /**
+     * DRSC 客户端（issue #14-B）：仅当 `rebuild.factSource === 'drsc'` 时用到。
+     * 缺席时选 drsc 会**显式中止**，不静默回退本地表。
+     */
+    drsc?: DrscClient;
 }
 import type { RebuildStatus } from '../contract.js';
 export type { RebuildPhase, RebuildStatus } from '../contract.js';
-export interface RebuildChunk {
-    sessionId: string;
-    messages: ConversationMessage[];
-}
-export declare function groupL0Sessions(records: L0MessageRecord[]): RebuildChunk[];
 /** 抽取调用数下界估算(与 l1.ts 的 perChunk 同式;会话数与字符预算取大)。 */
 export declare function estimateCalls(sessions: number, messages: number, chars: number, maxInputChars: number): number;
+/**
+ * 水位落差**提示**阀值：检索库里晚于 L0 水位的占比超过此值，就要求二次确认。
+ *
+ * 为什么叫“提示阀值”而不是“拒绝阀值”：L0 写停后这个比例只会单调上升，
+ * 拿它做硬门槛等于把重建**永久锁死**（issue #14 原提案的致命缺陷）。
+ * 所以它只负责“提醒你正在做什么”，放行靠 `force`；真正的**不丢**由
+ * `planPreserve` 的集合判据（`post-watermark`）结构性保证。
+ */
+export declare const STALE_RATIO_THRESHOLD = 0.5;
 export declare class RebuildController {
     private readonly ctx;
     private readonly cfg;
@@ -33,22 +45,44 @@ export declare class RebuildController {
     private readonly logger;
     private readonly live;
     private status;
-    private chunks;
+    /**
+     * 会话级事实源迭代器（issue #14-B）：不再把全量 L0 正文驻留内存。
+     * null = 尚未进入蒸馏 / 已收尾。
+     */
+    private chunkIter;
     private cancelRequested;
     /** 快照时刻(收尾时按它区分重建产物与重建后新对话的记录)。 */
     private rebuildStartMs;
     constructor(ctx: Context, cfg: MemoryConfig, stores: RebuildStores, db: MemoryDb, runner: Pick<MemoryRunner, 'enqueueRebuildTask' | 'runRebuildTurn' | 'states'>, logger: MemoryLogger, live: LiveSettingsHandle);
-    /** 状态快照(idle 时附带实时 L0 预估,供确认弹窗显示成本)。 */
+    /** 状态快照(idle 时附带实时预估与事实源水位,供确认弹窗讲清"会发生什么")。 */
     getStatus(): RebuildStatus;
-    /** 内存中尚未处理的会话快照块数(收尾后应为 0——快照即弃,诊断/冒烟用)。 */
+    /** 尚未处理的会话块数（流式下为估算 `total - done`；未运行时为 0，诊断/冒烟用）。 */
     get chunkCount(): number;
-    /** 启动重建(校验后入队准备任务;真正的清库/归档在管线队列里串行执行,避开并发竞态)。 */
-    start(): RebuildStatus;
+    /**
+     * 按 `cfg.rebuild.factSource` 选事实源（issue #14-B）。
+     *
+     * 选 drsc 但客户端未装配时**显式抛错**，不静默回退本地表 —— “以为用了新源其实还是旧表”
+     * 会让用户拿重建结果去判断 DRSC 数据是否完整，那是最坏的误判。
+     */
+    private provider;
+    /**
+     * 启动重建(校验后入队准备任务;真正的清库/归档在管线队列里串行执行,避开并发竞态)。
+     *
+     * `force` 只用于跨过**提示门槛**（水位落差超过 `STALE_RATIO_THRESHOLD` 时的二次确认），
+     * 不能跨过唯一那条硬拒：「L0 一条消息都没有、检索库却有记录」—— 那种形状下重建
+     * 只会清空、一条也重造不出来，属于纯亏。
+     */
+    start(force?: boolean): RebuildStatus;
     /** 请求取消:当前块完成后停止,已重建部分保留并照常收尾 L2/L3。 */
     requestCancel(): RebuildStatus;
     private prepare;
-    /** 分块链:一次只挂一个重建块,跑完再挂下一块——正常轮次可随时插队。 */
-    private scheduleChunk;
+    /**
+     * 分块链:一次只挂一个重建块,跑完再挂下一块——正常轮次可随时插队。
+     *
+     * 流式版（issue #14-B）：从事实源迭代器拉下一个会话，不再按下标从内存数组取。
+     * 内存峰值从"全量正文"降到"单会话"。
+     */
+    private scheduleNext;
     private finalize;
     /**
      * 收集重建窗口内某族的记录:重建产物全部是新插入(updated==created),