dsh-prime-memory 0.22.1 → 0.24.0

package/dist/pipeline/ruminate.js

@@ -1,7 +1,10 @@
+import { resolveDataDir } from '../config.js';
 import { InProcMemoryBackend } from '../store/memory-backend.js';
+import { exportRecords } from '../store/memory-md-export.js';
 import { groupPendingBySession, loadPending, } from '../store/pending.js';
 import { errDetail } from '../util/filelog.js';
 import { runSceneConsolidation } from './l2.js';
+import { migrateLegacySlots } from './slot-migrate.js';
 import { relabelPass } from './relabel.js';
 import { processSceneReclusterJobs } from './recluster.js';
 import { annotateOrphanCandidates } from '../room-review.js';
@@ -48,6 +51,13 @@ export class RuminateController {
     pendingFile;
     /** Room 注册表(可选;孤儿候选预标记的合并词表来源)。 */
     roomRegistry;
+    /**
+     * 本轮起始时的库快照（id → updatedAt），供收尾算「本轮新增/变更」增量集（task_2.8）。
+     * `undefined` = 本轮没拍（投射门未开或拍失败）→ 收尾一律不做全库重导。
+     */
+    mdBaseline;
+    /** 投射旁路失败累计次数（只 warn 不抛，计数供诊断/测试读取）。 */
+    mdFailures = 0;
     /** 记忆后端:未注入时包 l1(进程内,行为与改造前等价)。 */
     backend() {
         return this.stores.backend ?? new InProcMemoryBackend(this.stores.l1);
@@ -89,6 +99,9 @@ export class RuminateController {
             this.sessions = groupSessions(buckets);
             this.cancelRequested = false;
             this.totalL1 = 0;
+            // md 投射基线（task_2.8）：两条收尾路径（finalize / doLightRefresh）共用同一份起点，
+            // 所以必须在这里拍——放在 `sessions.length === 0` 分支之前，轻量刷新才覆盖得到。
+            this.snapshotMdBaseline();
             if (this.sessions.length === 0) {
                 // 没有 pending 切片 → 做 L2/L3 轻量刷新
                 return await this.doLightRefresh();
@@ -148,7 +161,11 @@ export class RuminateController {
         // 原先 setImmediate 连发会把全部会话一次性塞进 runner 队列(无界堆积),
         // LLM e2e 延迟波动时既拖慢 live 任务也让取消语义变钝;链式入队后
         // 进度(done)真实逐会话推进,取消即刻停止入队。
-        this.runner.enqueue(session.sessionId, session.messages, session.mode, {
+        // 传空消息（与 enqueueSessionSlices 同一语义）：让 runTurn 不回灌缓冲，
+        // 由 distillSession 直接处理该会话在内存缓冲里的既有切片。
+        // （旧代码传 session.messages——那是从 pending.json 读出的、已在缓冲中的消息，
+        //   经 runTurn 的 `bucket.push(...messages)` 会重复入桶 → 反刍后待处理计数“还原/变多”。）
+        this.runner.enqueue(session.sessionId, [], session.mode, {
             force: true,
             onTurnDone: (records) => {
                 this.totalL1 += records;
@@ -199,7 +216,18 @@ export class RuminateController {
                         if (scenes.length === 0)
                             continue;
                         const fstate = this.runner.states?.[family];
+                        // 强制 L3：runPersona 自带触发判定(memoriesSinceL3>=interval 才跑)，反刍是用户
+                        // 显式整理动作，需绕过阈值真跑——置 personaRequestedReason 走“主动请求”分支。
+                        if (fstate)
+                            fstate.personaRequestedReason = '反刍收尾';
                         await runPersona(this.ctx, this.cfg, this.stores.scenes[family], this.stores.persona[family], fstate || undefined, this.logger, family);
+                        // 与 L2 块对称：无论 runPersona 是否因“无变化场景”早退，反刍收尾都清零 L3 计数，
+                        // 否则“待 L3 新记忆”会永远卡在阈值下(本 bug 根因)。runPersona 成功时已自清，这里幂等兜底。
+                        if (fstate) {
+                            fstate.memoriesSinceL3 = 0;
+                            fstate.lastL3At = Date.now();
+                            fstate.personaRequestedReason = undefined;
+                        }
                         this.logger.info(`[memory] 反刍 L3 完成(family=${family})`);
                     }
                     catch (err) {
@@ -207,6 +235,15 @@ export class RuminateController {
                     }
                 }
             }
+            // 反刍收尾改了 L2/L3 计数（runner.states 是 StateStore 的活引用，内存态）——
+            // 必须显式落盘，否则重启从 state.json 读回旧值，表现为“待处理计数反复”。
+            // （正常蒸馏路径由 runTurn 末尾 save；反刍 finalize 是独立路径，需自己 save。）
+            await this.stores.state.save();
+            // 旧 slot 语义迁移（cfg.slots.migrateLegacy 默认关 → 直接 0 动作）：
+            // 把“钉成常驻、内容已由活 L1 记忆承载”的 rule 槽位软退场。
+            if (this.stores.slots !== undefined) {
+                await migrateLegacySlots(this.stores.slots, this.stores.l1, this.cfg.slots.migrateLegacy === true, this.logger);
+            }
             // 标注校验/重标定:Wing 合法性 + 认知 hall 映射 + 未打标补标 + 涌现标签
             // 批次进度经 onProgress 写入 detail + sub 子进度(非会话阶段的进度由重标批次决定)
             this.status.phase = 'relabeling';
@@ -250,6 +287,8 @@ export class RuminateController {
             catch (err) {
                 this.logger.warn(`[memory] 孤儿候选预标记失败(忽略): ${errDetail(err)}`);
             }
+            // md 投射收尾（task_2.8）：只导本轮新增/变更的记录；旁路，失败不影响本次产物。
+            await this.projectMd('反刍收尾');
             this.status.phase = 'done';
             this.finish(null);
         }
@@ -333,7 +372,18 @@ export class RuminateController {
             this.status.detail = `L3 画像更新(${family})`;
             const fstate = this.runner.states?.[family];
             try {
+                // 强制 L3：runPersona 自带触发判定(memoriesSinceL3>=interval 才跑)，反刍是显式整理动作，
+                // 需绕过阈值真跑——置 personaRequestedReason 走“主动请求”分支。
+                if (fstate)
+                    fstate.personaRequestedReason = '反刍轻量刷新';
                 await runPersona(this.ctx, this.cfg, this.stores.scenes[family], this.stores.persona[family], fstate, this.logger, family);
+                // 与 L2 循环对称：无论 runPersona 是否因“无变化场景”早退，都清零 L3 计数，
+                // 否则“待 L3 新记忆”永远卡在阈值下。runPersona 成功时已自清，这里幂等兜底。
+                if (fstate) {
+                    fstate.memoriesSinceL3 = 0;
+                    fstate.lastL3At = Date.now();
+                    fstate.personaRequestedReason = undefined;
+                }
             }
             catch (err) {
                 this.logger.warn(`[memory] 反刍轻量刷新 L3 失败(family=${family}): ${errDetail(err)}`);
@@ -361,6 +411,22 @@ export class RuminateController {
             this.status.sub = null;
             this.status.done++;
         }
+        // 轻量刷新改了 L2/L3 计数（runner.states 是 StateStore 活引用）——必须显式落盘，
+        // 否则重启从 state.json 读回旧值，表现为“待 L2/L3 计数反复”。
+        try {
+            await this.stores.state.save();
+        }
+        catch (err) {
+            this.logger.warn(`[memory] 反刍轻量刷新 state 落盘失败(计数可能不持久): ${errDetail(err)}`);
+        }
+        // 旧 slot 语义迁移：无 pending 缓冲时走的是本路径（“待 L3 12/20”那类场景），
+        // 与 finalize 同一动作、同样默认关；两处幂等（退场后不再命中 open）。
+        if (this.stores.slots !== undefined) {
+            await migrateLegacySlots(this.stores.slots, this.stores.l1, this.cfg.slots.migrateLegacy === true, this.logger);
+        }
+        // md 投射收尾（task_2.8）：与 finalize 同一动作的两个挂载点之一——历史教训是
+        // `sessions.length === 0` 走本路径，只挂 finalize 等于没挂。
+        await this.projectMd('轻量刷新');
         this.status.running = false;
         this.status.detail = null;
         this.status.phase = this.cancelRequested ? 'cancelled' : 'done';
@@ -369,6 +435,89 @@ export class RuminateController {
         this.logger.info(`[memory] 反刍轻量刷新结束(${this.status.phase}):${this.status.done}/${this.status.total} 步,耗时 ${Math.round(cost / 1000)}s`);
         return this.getStatus();
     }
+    /**
+     * 投射侧诊断计数（只增不减；不进任何端点，避开契约五处齐改的面）。
+     */
+    getMdFailures() {
+        return this.mdFailures;
+    }
+    /**
+     * 拍本轮起始基线（id → updatedAt）。三道门任一不满足就**一个动作都不做**：
+     * 连 `l1.all()` 都不调，这样“投射关着”时的产物与改动前逐字一致（本仓红线）。
+     *
+     * 为什么用基线 diff 而不是 `updatedAt >= startedAt`：relabel / 退场等改写走的是
+     * `patchMetadata` 那类最小写回，**不碰 `updated_time`**（它在快照哈希字段表里），
+     * 按时间戳筛会把这批真变了的记录漏掉。
+     */
+    snapshotMdBaseline() {
+        this.mdBaseline = undefined;
+        const exp = this.cfg.memExport;
+        if (exp === undefined || exp.enabled !== true)
+            return;
+        if (this.stores.mdLedger === undefined)
+            return;
+        try {
+            const map = new Map();
+            for (const r of this.stores.l1.all())
+                map.set(r.id, r.updatedAt);
+            this.mdBaseline = map;
+        }
+        catch (err) {
+            // 拍不上基线 = 本轮不投射（而不是退回全库重导）；旁路失败不拖垮反刍。
+            this.mdFailures++;
+            this.logger.warn(`[memory] 反刍 md 投射基线失败(本次不做投射): ${errDetail(err)}`);
+        }
+    }
+    /**
+     * 反刍收尾的增量 md 投射（task_2.8）：库 → 文件 + 账本，**只碰本轮新增/变更的那批**。
+     *
+     * 与手动的 `dsh-memory/mem-export` 端点的区别：
+     * - 不跑命名回填（`assignMissingNames` 会写库，反刍是只读旁路，不能在那里改库）；
+     *   本轮新记录的 `name` 已在写入前由管线单一真源分配，未命名的按 `fileStemFor` 回落。
+     * - 不建类型目录骨架（`ensureTypeSkeleton`），那是面板显式触发的动作。
+     * 护栏全部复用 `cfg.memExport` 既有值（`maxRecords`/`timeBudgetMs`），**不新增配置项**。
+     *
+     * 失败面：整个方法自吞异常，只 warn + 计数，绝不抛给调用方、绝不改变反刍结果。
+     * @param stage - 日志里的路径名（区分 finalize 与轻量刷新两条挂载点）。
+     */
+    async projectMd(stage) {
+        const baseline = this.mdBaseline;
+        if (baseline === undefined)
+            return;
+        const exp = this.cfg.memExport;
+        const ledger = this.stores.mdLedger;
+        if (exp === undefined || exp.enabled !== true || ledger === undefined)
+            return;
+        try {
+            const changed = [];
+            for (const r of this.stores.l1.all()) {
+                const prev = baseline.get(r.id);
+                // 新 id（本轮蒸馏产出）或 updatedAt 变了（合并/改写）才算变更；其余不重导。
+                if (prev === undefined || prev !== r.updatedAt)
+                    changed.push(r);
+            }
+            if (changed.length === 0)
+                return;
+            const rep = await exportRecords({
+                records: changed,
+                cfgRoot: exp.root,
+                dataDir: resolveDataDir(this.cfg),
+                ledger,
+                maxRecords: exp.maxRecords,
+                timeBudgetMs: exp.timeBudgetMs,
+                logger: this.logger,
+            });
+            this.logger.info(`[memory] 反刍 md 投射(${stage}):增量 ${changed.length} 条,写 ${rep.written},未变 ${rep.unchanged},跳过 ${rep.skipped},落点 ${rep.root}${rep.capped ? `,护栏截断剩 ${rep.remaining} 条(下轮反刍继续)` : ''}`);
+        }
+        catch (err) {
+            this.mdFailures++;
+            this.logger.warn(`[memory] 反刍 md 投射失败(旁路忽略,不影响本次产物,累计 ${this.mdFailures} 次): ${errDetail(err)}`);
+        }
+        finally {
+            // 基线一次性消费：同一次运行不重投射同一批（两条挂载点互斥，这里只防异常复用）。
+            this.mdBaseline = undefined;
+        }
+    }
     finish(error) {
         this.status.running = false;
         this.status.detail = null;

package/dist/pipeline/runner.d.ts

@@ -30,6 +30,16 @@ export interface MemoryStores {
     state: StateStore;
     /** 图谱存储(可选:测试缝/未装配时图谱泵整体停用;GraphStore 自带降级 no-op)。 */
     graph?: GraphStore;
+    /**
+     * 派生数据搬运面（P0-d）：merge 后把使用史与人工标注搬到新 id。
+     * 只声明用到的那个方法（不拉整个类入参）——未装配时不搬，行为与改动前一致。
+     */
+    usage?: {
+        rekey(oldId: string, newId: string): boolean;
+    };
+    feedback?: {
+        rekey(oldId: string, newId: string): boolean;
+    };
 }
 /** 管线任务(优先级调度:live > graph > rebuild)。 */
 export interface PipelineTask {

package/dist/pipeline/runner.js

@@ -662,7 +662,13 @@ export class MemoryRunner {
             // §E 写入侧工作区:后台蒸馏手上只有 sessionId(没有 exec),经
             // `ctx.get('agents')` 宽容解析——与 §A 的多级父链解析同一招。
             // 拿不到 → undefined → 归属回落 global(pipeline 侧 `resolveRecordScope` 兜底)。
-            sessionWorkspaceIdOf(this.ctx, sessionId), anchorMap);
+            sessionWorkspaceIdOf(this.ctx, sessionId), anchorMap, 
+            // 派生数据跟着搬（P0-d）：不搬等于每次合并把这条记忆的使用史与人工标注清零。
+            // 两个 sidecar 都是后装上的（`stores.usage` 在装配段才填），故在调用时点现取。
+            (oldId, newId) => {
+                this.stores.usage?.rekey(oldId, newId);
+                this.stores.feedback?.rekey(oldId, newId);
+            });
             if (!result.skipped) {
                 this.pending[mode] = rest;
                 // 重建轮(force)不是有机对话,不推进爬坡

package/dist/pipeline/slot-migrate.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 旧 slot 语义迁移（`cfg.slots.migrateLegacy`，默认关）。
+ *
+ * 背景：常驻槽位是"每轮硬注入"的 opt-in 约定。早期用法里有一类槽位其实是
+ * **把一条已经存在的 L1 记忆钉成常驻**（`refs` 直指那条记录）——内容载体还在，
+ * 却占了固定 token 预算、还在概要里显示成常驻清单。新取向是"记忆按相关性隐式
+ * 浮现，除非手动提醒激活"，所以这类槽位应当退场，让那条记忆回到召回。
+ *
+ * 判据（四条同时满足，宁缺勿滥）：
+ *  1. 开关显式开启（动的是用户手动建的约定，不自动生效）；
+ *  2. `status='open'` 且 `pinned=true` 且 `kind='rule'`（todo/anchor/pointer 各有语义，一律不碰）；
+ *  3. `refs` 至少一条解析到**未退场**的 L1 记录（退场不丢信息：正文仍在记忆里）；
+ *  4. 记录本身可被召回（未退场即可检索，不再另设条件）。
+ *
+ * 动作：`close(id, 'dropped')` —— **软退场**，不删数据；记忆仍在，需要时可
+ * 重新 `memory_slot_write`。逐条 info 日志，便于事后核对。
+ */
+import type { Slot } from '../store/slots.js';
+import type { MemoryLogger } from '../types.js';
+/** 迁移需要的槽位面。 */
+export interface SlotMigrateStoreFace {
+    list(): Slot[];
+    close(id: string, status: 'done' | 'dropped'): Promise<boolean>;
+}
+/** 迁移需要的 L1 只读面（validTo 非空 = 已退场（epoch ms），不作为信息载体）。 */
+export interface SlotMigrateL1Face {
+    getByIds(ids: string[]): Array<{
+        id: string;
+        validTo?: number | null;
+    }>;
+}
+/** 一条可迁移槽位（预览用，执行前即可展示）。 */
+export interface MigrateCandidate {
+    id: string;
+    title: string;
+    /** 承载内容的活记录 id。 */
+    carrier: string;
+}
+/** 判定 + 挑选可迁移槽位（纯读，无副作用；面板预览与反刍执行共用）。 */
+export declare function pickMigratableSlots(slots: readonly Slot[], l1: SlotMigrateL1Face | undefined): MigrateCandidate[];
+/**
+ * 执行迁移：软退场命中的槽位。
+ * @returns 实际退场条数（close 返回 false 的不计）。
+ */
+export declare function migrateLegacySlots(slots: SlotMigrateStoreFace, l1: SlotMigrateL1Face | undefined, enabled: boolean, logger?: MemoryLogger): Promise<number>;

package/dist/pipeline/slot-migrate.js

@@ -0,0 +1,45 @@
+import { errDetail } from '../util/filelog.js';
+/** 判定 + 挑选可迁移槽位（纯读，无副作用；面板预览与反刍执行共用）。 */
+export function pickMigratableSlots(slots, l1) {
+    if (l1 === undefined)
+        return [];
+    const open = slots.filter((s) => s.status === 'open' && s.pinned === true && s.kind === 'rule');
+    if (open.length === 0)
+        return [];
+    // 一次批量取全部 refs，避免 N 次查询。
+    const allRefs = [...new Set(open.flatMap((s) => s.refs ?? []))];
+    const alive = new Set(l1.getByIds(allRefs).filter((r) => r.validTo === undefined || r.validTo === null).map((r) => r.id));
+    const out = [];
+    for (const s of open) {
+        const carrier = (s.refs ?? []).find((r) => alive.has(r));
+        if (carrier !== undefined)
+            out.push({ id: s.id, title: s.title, carrier });
+    }
+    return out;
+}
+/**
+ * 执行迁移：软退场命中的槽位。
+ * @returns 实际退场条数（close 返回 false 的不计）。
+ */
+export async function migrateLegacySlots(slots, l1, enabled, logger) {
+    if (enabled !== true)
+        return 0;
+    const candidates = pickMigratableSlots(slots.list(), l1);
+    if (candidates.length === 0)
+        return 0;
+    let done = 0;
+    for (const c of candidates) {
+        try {
+            if (await slots.close(c.id, 'dropped')) {
+                done++;
+                logger?.info(`[memory] 旧槽位迁移:「${c.title}」常驻退场，内容改由召回承载(${c.carrier})`);
+            }
+        }
+        catch (err) {
+            logger?.warn(`[memory] 旧槽位迁移失败(${c.id}): ${errDetail(err)}`);
+        }
+    }
+    if (done > 0)
+        logger?.info(`[memory] 旧槽位迁移完成: 常驻约定退场 ${done} 条`);
+    return done;
+}

package/dist/pipeline/workspace-relink.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 存量记忆的 workspace re-link（内容路由回填）。
+ *
+ * 为什么需要它：新写入的路由只覆盖此后产生的记忆，而库里已有的记录归属列全空
+ * （实测 1279 条活跃记录里 `workspace_id` 非空为 0）。不回填，「按项目看记忆」这件事
+ * 就永远只有增量、没有存量。
+ *
+ * 三条设计约束：
+ * 1. **只写 `workspace_id`，不动 `scope`、不动 `updated_time`**。前者保可见性零变化
+ *    （`cfg.scope='global'` 下 `isScopeVisible` 直接放行），后者保快照哈希零失配
+ *    （见 `store/sqlite.ts` 的 `setL1WorkspaceIds` 注释，三条硬约束都在那儿）。
+ * 2. **宁缺勿猜**：路由不命中的记录保持原样，绝不给一个"默认归属"。归错项目会让记忆
+ *    在错误的工作区可见/不可见，比不归难查得多。
+ * 3. **有界可重入**：照 `wing-backfill` 的双护栏 + 扫描阶段也查墙钟 + 剩余留待再次触发；
+ *    且因不写 `updated_time`，按更新时间倒序分页**不会边扫边漂**。
+ */
+import type { MemoryRecord } from '../types.js';
+import type { WorkspaceRoute } from '../workspace-route.js';
+/** re-link 需要的存储面（结构化声明，便于单测注入）。 */
+export interface RelinkStoreFace {
+    list(opts: {
+        limit: number;
+        offset: number;
+    }): {
+        items: MemoryRecord[];
+        total: number;
+    };
+    setWorkspaceIds(items: ReadonlyArray<{
+        id: string;
+        workspaceId: string;
+    }>): number;
+}
+export interface RelinkReport {
+    dryRun: boolean;
+    /** 扫过的记录数（含未命中）。 */
+    scanned: number;
+    /** 路由命中的记录数。 */
+    matched: number;
+    /** 归属已是目标值、无需写的记录数（幂等重跑时等于 matched）。 */
+    unchanged: number;
+    /** 干跑时“若真跑会写多少条”；真写时恒为 0（那一步看 written）。 */
+    toWrite: number;
+    /** 实际写入条数（dryRun 时恒为 0）。 */
+    written: number;
+    /** 因预算未处理、留待下次触发的条数。 */
+    remaining: number;
+    /** 命中记录按归属的分布（先看这个数就知道路由表合不合口味）。 */
+    byWorkspace: Record<string, number>;
+}
+export declare function relinkWorkspaces(deps: {
+    l1: RelinkStoreFace;
+    routes: readonly WorkspaceRoute[];
+    dryRun?: boolean;
+    maxRecords?: number;
+    timeBudgetMs?: number;
+    logger?: {
+        info: (m: string) => void;
+        warn: (m: string) => void;
+    };
+}): Promise<RelinkReport>;

package/dist/pipeline/workspace-relink.js

@@ -0,0 +1,73 @@
+import { routeWorkspace } from '../workspace-route.js';
+import { yieldLoop } from '../util/yield.js';
+const PAGE = 200;
+/** 攒够一批再写：一批一个事务，避免逐条开事务的 fsync 开销。 */
+const FLUSH = 500;
+export async function relinkWorkspaces(deps) {
+    const { l1, routes, logger } = deps;
+    const dryRun = deps.dryRun !== false; // 缺省干跑：先看报告，再决定真写
+    const maxRecords = Math.max(1, Math.floor(deps.maxRecords ?? 300));
+    const budgetMs = Math.max(1000, Math.floor(deps.timeBudgetMs ?? 120_000));
+    const started = Date.now();
+    const overBudget = () => Date.now() - started > budgetMs;
+    const report = {
+        dryRun, scanned: 0, matched: 0, unchanged: 0, toWrite: 0, written: 0, remaining: 0, byWorkspace: {},
+    };
+    if (routes.length === 0)
+        return report;
+    let offset = 0;
+    let batch = [];
+    // 计数在此结算：`flush()` 会清空 batch，调用点再拿 `batch.length` 必然归零。
+    const flush = () => {
+        if (batch.length === 0)
+            return;
+        if (dryRun)
+            report.toWrite += batch.length;
+        else
+            report.written += l1.setWorkspaceIds(batch);
+        batch = [];
+    };
+    for (;;) {
+        if (report.scanned >= maxRecords)
+            break;
+        // 扫描阶段本身也查墙钟：1279 条不慢，但同一个护栏要能扛住更大的库。
+        if (overBudget())
+            break;
+        const page = l1.list({ limit: PAGE, offset });
+        if (page.items.length === 0)
+            break;
+        for (const rec of page.items) {
+            // 上限检查必须在**循环顶部**：放在末尾时，未命中的记录会先 `continue` 掉，
+            // 于是 maxRecords=1 实际能扫 2 条（实测翻出）——有界性得对所有分支都成立。
+            if (report.scanned >= maxRecords)
+                break;
+            report.scanned++;
+            const routed = routeWorkspace(`${rec.content}\n${rec.scene_name}`, routes);
+            if (routed === undefined)
+                continue;
+            report.matched++;
+            report.byWorkspace[routed] = (report.byWorkspace[routed] ?? 0) + 1;
+            if (rec.workspaceId === routed) {
+                report.unchanged++;
+                continue;
+            }
+            batch.push({ id: rec.id, workspaceId: routed });
+            if (batch.length >= FLUSH)
+                flush();
+        }
+        offset += page.items.length;
+        if (offset >= page.total)
+            break;
+        await yieldLoop(); // 让出事件循环：面板 RPC / 状态查询优先
+    }
+    flush();
+    // 剩余 = 总数 - 实扫条数。**不能用 offset 算**：中途按 maxRecords/预算 break 时，
+    // offset 已推进整个页（一页 PAGE 条），会把“还剩 2 条没扫”算成 0，
+    // 于是报告谎称已扫完——下次也就不会再触发续扫了。
+    const totalRows = l1.list({ limit: 1, offset: 0 }).total;
+    report.remaining = Math.max(0, totalRows - report.scanned);
+    logger?.info(`[memory] workspace re-link${dryRun ? '(干跑)' : ''}：扫 ${report.scanned} 条，命中 ${report.matched} 条，`
+        + `待写 ${report.toWrite} 条，实写 ${report.written} 条，`
+        + `剩 ${report.remaining} 条未扫(下次触发续)；分布 ${JSON.stringify(report.byWorkspace)}`);
+    return report;
+}

package/dist/projection/recall.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 会话「活召回集」服务端投影(memoryRecall)。
+ *
+ * 语义：本会话**已注入**的记忆，以及其中「此刻仍在上下文里」的那部分。
+ * 数据源是 `SessionRecalledStore`（sessionKey 键、写穿持久化），所以**旧会话重开也读得到**。
+ *
+ * 压缩/清空对这张表的作用不同（2026-10-13 用户口径）：
+ * - `clear`（主动清空）整表清，view 随之空；
+ * - `compact`（摘要替换）**不删条目**，只把当时在列表里的那批标成 `superseded`（正文已被
+ *   摘要取代、已不在上下文里）。读侧据此把旧召回与当前召回区分开，而不是继续谎报“还在”。
+ *   已退场（`retired`）的条目必须留在列表里（人的裁决凭证），取代标记与它正交。
+ *
+ * 与 memorySlots 的分工（两条轴，互不替代）：
+ * - `memorySlots` = 用户手动 pin 的**常驻约定**（每轮硬注入，注册表语义）；
+ * - `memoryRecall` = 按相关性**隐式浮现**的召回结果（非常驻，本投影）。
+ * 召回记录绝不灌进 memorySlots：那会把"非常驻"伪装成槽位注册表。
+ *
+ * 会话感知靠 `init(header)`：宿主在 `session/created` 与冷加载 restore 两处都传
+ * `session.header`（`dsh-session/lib/index.js` 实证形状 `{ version, id, createdAt, … }`），
+ * `header.id` 即会话 id，与召回记账的 sessionKey（`agent.session?.id ?? agent.id`）同源。
+ * state 里带上 sessionId，apply 无 session 参数也能按本会话重读 store。
+ *
+ * 消费方是 dsh-brief-sidebar 的「本会话召回」分区（`useProjectionValue(ctx, sessionId, key)`）。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionRecalledStore } from '../store/session-recalled.js';
+import type { MemoryRecord } from '../types.js';
+export declare const MEMORY_RECALL_KEY = "memoryRecall";
+/** view 最多透出条数（最近在上；超出部分只计入 count，防 wire 体量失控）。 */
+export declare const RECALL_VIEW_CAP = 20;
+/** 一条召回记录在 wire view 上的呈现。 */
+export interface RecallItemView {
+    id: string;
+    type: string;
+    /** 正文首行（截断至 TITLE_MAX）；全文由消费方按需走面板读。 */
+    title: string;
+    priority: number;
+    /** 使用场景（metadata.dsh_usage_scenario）；无则缺席（附加字段，旧帧没有也整条通过）。 */
+    scenario?: string[];
+    /**
+     * 人给的最近一次打分(-1..5)；未标注则缺席。
+     * 卡片靠它把已打的那一笔显示成选中态；均值等细粒度数据走 `session-recalled` 端点。
+     */
+    rating?: number;
+    /**
+     * 正文全文（截断至 BODY_MAX）；消费方悬停泡泡直接读它，不再回查端点。
+     * 缺席 = 旧帧（读侧退化成只显示 title）。
+     */
+    body?: string;
+    /**
+     * 该记录已被判定过时（`isRetired`）。只写 true：未退场时字段缺席，
+     * 读侧按「缺席即活跃」处理，旧帧自然兼容。
+     */
+    retired?: true;
+    /**
+     * 该条目的正文**已被摘要取代**（压缩发生时时它就在列表里），即不在模型上下文里了。
+     * 只写 true（同 `retired` 的兼容手法）；与 `retired` 正交，两者可共存。
+     * 读侧据此把「已被摘要取代的旧召回」与「此刻仍在上下文里的召回」区分开。
+     */
+    superseded?: true;
+}
+/** 持久态：本会话的活召回 id 集 + 判脏序号。 */
+export interface RecallProjectionState {
+    rev: number;
+    /**
+     * 反馈 sidecar 的序号（打分也会让 view 变：条目要显示已打的那一笔）。
+     * 可选：旧 checkpoint 帧里没这个字段，读侧必须容忍。
+     */
+    fb?: number;
+    sessionId: string;
+    /** 注入序（旧→新），由 store 保证。 */
+    ids: string[];
+    /**
+     * 已被摘要取代的 id（压缩水位之上的那批）。可选：旧 checkpoint 没有这个字段，
+     * 读侧必须容忍（缺席 = 无取代，与改动前逐字一致）。
+     */
+    superseded?: string[];
+}
+/** wire view：count 是总数，items 是**最近在上**的截断视图。 */
+export interface RecallView {
+    rev: number;
+    sessionId: string;
+    count: number;
+    items: RecallItemView[];
+}
+/** 零依赖 schema（同 slots 投影的理由：registry 只调 `parse`，且按 Object.is 比较引用）。 */
+interface SchemaLike<T> {
+    parse(value: unknown): T;
+}
+/** state 校验（registry 用它挡掉损坏/过期的 checkpoint 行）。 */
+export declare const stateSchema: SchemaLike<RecallProjectionState>;
+/** view 校验（出网前调用；未知键容忍，同 slots 投影的语义边界）。 */
+export declare const viewSchema: SchemaLike<RecallView>;
+/** 投影需要的 L1 只读面（结构化声明，避免跨模块类型耦合）。
+ *  判退场要 `validTo`/`metadata`，故直接 Pick 自 MemoryRecord，不在投影里自写时间比较。 */
+export interface RecallL1Face {
+    getByIds(ids: string[]): Array<Pick<MemoryRecord, 'id' | 'type' | 'content' | 'priority' | 'metadata' | 'validTo'>>;
+}
+/** 投影需要的反馈只读面（缺席 = view 不带 rating，旧行为）。 */
+export interface RecallFeedbackFace {
+    revision(): number;
+    lastOf(id: string): number | undefined;
+}
+/**
+ * 注册 memoryRecall 投影。
+ *
+ * 缺席降级同 slots 投影：`ctx.inject` 在服务未提供时不回调；形状不符静默不注册。
+ * apply 是 O(1) 判脏（store.revision() 与反馈序号比对），任意已提交事件都会带进来看一眼。
+ * @param feedback - 相关度反馈只读面；缺席时 view 不带 rating（旧行为）。
+ */
+export declare function registerRecallProjection(ctx: Context, store: SessionRecalledStore, l1?: RecallL1Face, feedback?: RecallFeedbackFace): void;
+export {};