dsh-prime-memory 0.22.2 → 0.24.1

package/dist/store/recall-feedback.js

@@ -0,0 +1,213 @@
+/**
+ * 召回相关度反馈 sidecar（`recall-feedback.json`）。
+ *
+ * 口径（用户裁定）：概要侧栏「本会话召回」卡上，人对**这条被召回的记忆**做主动标注：
+ * - `0..5` = 相关度评分（人给的、显式的，区别于系统算的 priority/usage/aging）；
+ * - `-1`   = 声明这条记忆**已过时**（配套动作由调用方执行：退场 + 会话内声明）。
+ *
+ * 为什么单开一个 sidecar 而**不写进 L1 metadata**：metadata 进 `canonicalRecords`
+ * 快照哈希（`store/l1-snapshot.ts`），往既有记录里塞新键 = 旧快照永久失配（conflicts
+ * 列事故同款）。反馈是**关于**记忆的观察值，不是记忆内容，本就该另立面。
+ *
+ * 纪律与 recall-usage 同族：缺失 = 合法空表；损坏/不可读 → 只读降级（内存态照用、
+ * 停止回写），绝不抛进读路径。差别只有一处：**打分是用户动作、低频**，所以
+ * **立即落盘**而非去抖——点完就崩不该丢这一票。
+ */
+import * as path from 'node:path';
+import { readJsonStrict, atomicWriteText, ensureDir } from '../util/io.js';
+export const RECALL_FEEDBACK_FILE_VERSION = 1;
+/** 合法打分：-1（声明过时）与 0..5（相关度）。 */
+export const FEEDBACK_SCORES = [-1, 0, 1, 2, 3, 4, 5];
+/** 条目上限(防已退场记忆的 id 无限累积):超限按 updatedAt 淘汰最旧。 */
+const MAX_ENTRIES = 20_000;
+/** 轨迹条数上限。 */
+const HISTORY_CAP = 12;
+/** 是否合法打分(供端点入参校验复用)。 */
+export function isFeedbackScore(v) {
+    return typeof v === 'number' && FEEDBACK_SCORES.includes(v);
+}
+export class RecallFeedbackStore {
+    logger;
+    file;
+    entries = new Map();
+    loaded = false;
+    degraded;
+    degradedLogged = false;
+    writeChain = Promise.resolve();
+    /** 判脏序号:每次有效写入 +1(投影 view 带 rating，靠它决定要不要重建)。 */
+    rev = 0;
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = path.join(dataDir, 'recall-feedback.json');
+    }
+    async init() {
+        await ensureDir(path.dirname(this.file));
+        const read = await readJsonStrict(this.file);
+        if (!read.ok) {
+            if (read.reason !== 'missing') {
+                this.degraded = `${read.reason}${'detail' in read && read.detail ? `: ${read.detail}` : ''}`;
+                this.logger?.warn(`[memory] 召回反馈只读降级: ${this.degraded}`);
+            }
+            this.loaded = true;
+            return;
+        }
+        const raw = read.value.entries ?? {};
+        for (const [id, e] of Object.entries(raw)) {
+            const parsed = this.normalize(e);
+            if (parsed)
+                this.entries.set(id, parsed);
+        }
+        this.loaded = true;
+    }
+    /** 读侧逐条收窄:形状不符的条目丢弃，不让一条坏数据拖垮整表。 */
+    normalize(e) {
+        if (!e || typeof e !== 'object')
+            return undefined;
+        const raw = e;
+        if (!isFeedbackScore(raw.last) || typeof raw.updatedAt !== 'number')
+            return undefined;
+        const rated = typeof raw.rated === 'number' && raw.rated >= 0 ? Math.floor(raw.rated) : 0;
+        const history = Array.isArray(raw.history)
+            ? raw.history
+                .filter((h) => isFeedbackScore(h.s) && typeof h.at === 'number')
+                .slice(-HISTORY_CAP)
+            : [];
+        return {
+            last: raw.last,
+            rated,
+            mean: typeof raw.mean === 'number' ? raw.mean : 0,
+            obsolete: typeof raw.obsolete === 'number' && raw.obsolete >= 0 ? Math.floor(raw.obsolete) : 0,
+            updatedAt: raw.updatedAt,
+            history,
+        };
+    }
+    ensureLoaded() {
+        if (!this.loaded)
+            throw new Error('召回反馈未初始化(先 await init())');
+    }
+    /** 判脏序号(供投影 O(1) 决定要不要重建 view)。 */
+    revision() {
+        return this.rev;
+    }
+    /**
+     * 记一次打分。返回聚合后的条目(供端点回执)。
+     * 只聚合不裁决:`-1` 进 obsolete 计数、不进均值(过时不是"不相关",两回事)。
+     */
+    rate(id, score, at = Date.now()) {
+        this.ensureLoaded();
+        const prev = this.entries.get(id);
+        const history = [...(prev?.history ?? []), { s: score, at }].slice(-HISTORY_CAP);
+        const rated = (prev?.rated ?? 0) + (score >= 0 ? 1 : 0);
+        const sum = (prev?.mean ?? 0) * (prev?.rated ?? 0) + (score >= 0 ? score : 0);
+        const next = {
+            last: score,
+            rated,
+            mean: rated > 0 ? Math.round((sum / rated) * 100) / 100 : 0,
+            obsolete: (prev?.obsolete ?? 0) + (score === -1 ? 1 : 0),
+            updatedAt: at,
+            history,
+        };
+        this.entries.set(id, next);
+        this.rev += 1;
+        this.prune();
+        this.schedulePersist();
+        return { ...next };
+    }
+    get(id) {
+        this.ensureLoaded();
+        const e = this.entries.get(id);
+        return e ? { ...e, history: [...e.history] } : undefined;
+    }
+    /** 均值(0..5);无有效评分 → undefined(缺席 ≠ 0 分)。 */
+    meanOf(id) {
+        this.ensureLoaded();
+        const e = this.entries.get(id);
+        return e && e.rated > 0 ? e.mean : undefined;
+    }
+    /** 最近一次打分(-1..5);未标注 → undefined。 */
+    lastOf(id) {
+        this.ensureLoaded();
+        return this.entries.get(id)?.last;
+    }
+    /**
+     * 把一条记录的人工标注搬到新 id（merge 之后由管线调用，P0-d）。
+     *
+     * 不搬的后果比使用史更直接：成熟度只吃“人工最近一笔”，而 `last` 留在旧 id 上
+     * 就等于新记录**看起来从没被人打过**；更坏的是旧 id 上那一笔 `-1`（已判过时）
+     * 会跟着旧行一起沉进垃圾堆，新行反而以“未标注”的活状态回到召回里。
+     *
+     * 计数按相加、不按轨迹重算：`history` 截断到 12 条，拿它反推 `obsolete` 必然少算。
+     * 两侧都有条目时取较新一侧的 `last`，轨迹按时间归并。
+     */
+    rekey(oldId, newId) {
+        this.ensureLoaded();
+        if (oldId === newId)
+            return false;
+        const from = this.entries.get(oldId);
+        if (from === undefined)
+            return false;
+        const to = this.entries.get(newId);
+        const ratedCount = (to?.rated ?? 0) + from.rated;
+        const ratedSum = (to?.mean ?? 0) * (to?.rated ?? 0) + from.mean * from.rated;
+        const newer = to !== undefined && to.updatedAt >= from.updatedAt ? to : from;
+        const next = {
+            last: newer.last,
+            rated: ratedCount,
+            mean: ratedCount > 0 ? Math.round((ratedSum / ratedCount) * 100) / 100 : 0,
+            obsolete: (to?.obsolete ?? 0) + from.obsolete,
+            updatedAt: Math.max(to?.updatedAt ?? 0, from.updatedAt),
+            history: [...(to?.history ?? []), ...from.history].sort((a, b) => a.at - b.at).slice(-HISTORY_CAP),
+        };
+        this.entries.set(newId, next);
+        this.entries.delete(oldId);
+        this.rev += 1;
+        this.prune();
+        this.schedulePersist();
+        return true;
+    }
+    summary() {
+        this.ensureLoaded();
+        let rated = 0;
+        let obsolete = 0;
+        for (const e of this.entries.values()) {
+            rated += e.rated;
+            obsolete += e.obsolete;
+        }
+        return { tracked: this.entries.size, rated, obsolete };
+    }
+    prune() {
+        if (this.entries.size <= MAX_ENTRIES)
+            return;
+        const byOldest = [...this.entries.entries()].sort((a, b) => a[1].updatedAt - b[1].updatedAt);
+        for (const [id] of byOldest.slice(0, this.entries.size - MAX_ENTRIES))
+            this.entries.delete(id);
+    }
+    /** 立即落盘(串行链上排队,不与在途写交错)。 */
+    schedulePersist() {
+        if (this.degraded)
+            return;
+        this.writeChain = this.writeChain.then(() => this.persist(), () => this.persist());
+    }
+    async persist() {
+        if (this.degraded)
+            return;
+        const body = {
+            version: RECALL_FEEDBACK_FILE_VERSION,
+            entries: Object.fromEntries(this.entries),
+        };
+        try {
+            await atomicWriteText(this.file, JSON.stringify(body, null, 2));
+        }
+        catch (err) {
+            this.degraded = err instanceof Error ? err.message : String(err);
+            if (!this.degradedLogged) {
+                this.degradedLogged = true;
+                this.logger?.warn(`[memory] 召回反馈落盘失败,转只读降级: ${this.degraded}`);
+            }
+        }
+    }
+    /** 等待在途写完成(测试/停机用)。 */
+    flush() {
+        return this.writeChain;
+    }
+}

package/dist/store/recall-usage.d.ts

@@ -32,6 +32,17 @@ export declare class RecallUsageStore {
      *  (used 不在候选内 = 防御路径,同样算一次尝试——用了就是被尝试过)。 */
     recordAttempt(candidateIds: readonly string[], usedIds: readonly string[]): void;
     get(id: string): RecallUsageEntry | undefined;
+    /**
+     * 把一条记录的使用史搬到新 id（merge 之后由管线调用，P0-d）。
+     *
+     * 必须搬的理由：成熟度 = `priority + used + 老化 + 人工最近一笔` 的合成，而 merge
+     * 每次新铸 id——不搬就等于**每次合并把这条记忆的使用史清零**，它会被系统当成
+     * “没用过”而沉底，而且从面板上看不出来（统计仍挂在已退场的旧 id 上）。
+     *
+     * 两侧都有条目时按“次数相加、时刻取新”合并：这是纯计数，不存在语义冲突。
+     * 没条目（旧 id 从未被召回过）时返回 false，**不造零条目**——那会把表灌满噪声行。
+     */
+    rekey(oldId: string, newId: string): boolean;
     summary(): RecallUsageSummary;
     /** 立即落盘(去抖窗口内的兜底;测试/停机用)。 */
     flush(): Promise<void>;

package/dist/store/recall-usage.js

@@ -89,6 +89,35 @@ export class RecallUsageStore {
         const e = this.entries.get(id);
         return e ? { ...e } : undefined;
     }
+    /**
+     * 把一条记录的使用史搬到新 id（merge 之后由管线调用，P0-d）。
+     *
+     * 必须搬的理由：成熟度 = `priority + used + 老化 + 人工最近一笔` 的合成，而 merge
+     * 每次新铸 id——不搬就等于**每次合并把这条记忆的使用史清零**，它会被系统当成
+     * “没用过”而沉底，而且从面板上看不出来（统计仍挂在已退场的旧 id 上）。
+     *
+     * 两侧都有条目时按“次数相加、时刻取新”合并：这是纯计数，不存在语义冲突。
+     * 没条目（旧 id 从未被召回过）时返回 false，**不造零条目**——那会把表灌满噪声行。
+     */
+    rekey(oldId, newId) {
+        this.ensureLoaded();
+        if (oldId === newId)
+            return false;
+        const from = this.entries.get(oldId);
+        if (from === undefined)
+            return false;
+        const to = this.entries.get(newId);
+        this.entries.set(newId, {
+            attempts: (to?.attempts ?? 0) + from.attempts,
+            used: (to?.used ?? 0) + from.used,
+            lastAttemptAt: Math.max(to?.lastAttemptAt ?? 0, from.lastAttemptAt ?? 0) || null,
+            lastUsedAt: Math.max(to?.lastUsedAt ?? 0, from.lastUsedAt ?? 0) || null,
+        });
+        this.entries.delete(oldId);
+        this.prune();
+        this.schedulePersist();
+        return true;
+    }
     summary() {
         this.ensureLoaded();
         let attempted = 0;

package/dist/store/session-recalled.d.ts

@@ -13,10 +13,45 @@ export declare class SessionRecalledStore {
     revision(): number;
     private init;
     /** 记入本 sessionKey 本轮实际注入的记录 id（写穿；插入序淘汰最旧）。 */
-    add(sessionKey: string, recordIds: readonly string[]): void;
+    add(sessionKey: string, recordIds: readonly string[], injectionId?: string): void;
+    /**
+     * 标为受保护（判过时/软退场）：条目留在列表里，且不受上限淘汰与压缩清理影响。
+     * id 不在本会话列表里时忽略（不凭这个调用新建条目）。
+     */
+    protect(sessionKey: string, recordIds: readonly string[]): void;
     list(sessionKey: string): string[];
-    /** 压缩/清空：注入内容已离开上下文，清该会话活召回集（写穿）。 */
-    reset(sessionKey: string): void;
+    /**
+     * 上下文事件：按原因区分。`'clear'`（用户主动清空）整表清；`'compact'`（摘要替换）**只打取代标记**。
+     *
+     * 旧实现两种都整表清，于是“压缩过一次”就把本会话召回历史（含已判过时的裁决凭证）抹平；
+     * 改成“压缩什么都不做”又让列表谎报“这些正文还在上下文里”。现在压缩只动一维：
+     * 把**此刻在列表里的**标为「已被摘要取代」（已在标记里的不再推序号）。
+     * 压缩仍然重置**去重与占用账本**（那两者关心的是“能不能重新注入”，与这张展示表无关）。
+     */
+    reset(sessionKey: string, reason?: 'compact' | 'clear'): void;
+    /**
+     * 本会话「正文已被摘要取代」的 id 集（投影与端点用；只读共享。
+     * 未出现过取代的会话返回共享空集，不每次新建）。
+     */
+    supersededOf(sessionKey: string): ReadonlySet<string>;
+    /**
+     * 用会话日志的可见性事实**对账**取代标记（Phase 0B）。
+     *
+     * 判据来自宿主官方服务的 `surface.nodes`（模型可见节点集），而不是“有没有收到一条压缩事件”：
+     * 事件会漏、换代形状还会漂移，而且漏一次就永久错、无法补算。本函数每轮从事实源重算，
+     * 所以既能**标上**也能**撤销**（重新注入、或上一轮粗标记误伤的，都能自愈）。
+     *
+     * @param visible 当前仍在上下文里的注入消息 id 集
+     * @param known   会话日志里出现过的本插件注入消息 id 集。**不在 known 里的 = 该注入从未落日志**
+     *                （被宿主取消/覆盖），属“无从判”——不动它，绝不猜成“已被取代”。
+     * @returns 是否真的改动了状态（无改动不推 rev、不写盘）
+     */
+    reconcileSuperseded(sessionKey: string, visible: ReadonlySet<string>, known: ReadonlySet<string>): boolean;
+    /**
+     * 注：曾有 `remove(sessionKey, recordIds)` 供「声明过时」单条摘除，已删。
+     * 理由：用户判过时后条目得留在召回列表里显示删除线，所以**只有** `reset(…, 'clear')`
+     * 能让条目离开这张列表（判过时的还受 `protectedIds` 保护，连淘汰都走不到它）。
+     */
     size(): number;
     /** 等待在途持久化写完成（测试/停机）。 */
     flush(): Promise<void>;

package/dist/store/session-recalled.js

@@ -4,7 +4,12 @@
  * 语义（对齐"当前会话召回后对 session 有影响的条目"，且**旧会话重开也有效**）：
  * - 每次召回**实际注入**（recall.ts 注入成功点）按 **sessionKey**（=agent.session?.id ?? agent.id，
  *   与 pill 的 sessionId、投影 header.id 同源）记入；
- * - 上下文压缩/清空（agent/created source=compact|clear）按 sessionKey **reset**；
+ * - 上下文压缩/清空（agent/created source=compact|clear）按 sessionKey 处理，**两者不同**：
+ *   `clear`（用户主动清空会话）整表清；`compact`（摘要替换）**不删条目**，而是把**此刻在列表里
+ *   的那批**标成「正文已被摘要取代」（`supersededIds`）——它们的正文确实离开了模型上下文，
+ *   但**已判过时的条目是人对这条记忆的裁决凭证**，删了就没了（2026-10-13 用户口径）。
+ *   所以压缩只改「这条还在不在上下文里」这一维，不动「本会话召回过什么」这条历史。
+ *   重新被注入时取代标记应当撤销（正文又回到上下文了）。
  * - **写穿持久化到 `session-recalled.json`**（独立 sidecar，与 recall-dedupe 同款：串行原子写 +
  *   未知版本/损坏只读降级、失败绝不抛进召回热路径）→ 重启/旧会话重开时 `init()` 载回，卡不空。
  *
@@ -16,6 +21,23 @@ import { errDetail } from '../util/filelog.js';
 import { ensureDir, readJsonStrict, rmwJson } from '../util/io.js';
 import { SESSION_RECALLED_FILE_VERSION } from './file-versions.js';
 import { RECALL_DEDUPE_IDS_CAP, RECALL_DEDUPE_SESSION_CAP } from './recall-dedupe.js';
+/** 共享空集（未出现过取代的会话重复取用，不必每次新建）。 */
+const EMPTY_SET = new Set();
+/**
+ * 读 `injectedBy` 的宽容解析：非对象/值非字符串一律丢弃。
+ * 宁可让那条记录“无从判”（对账不动它），也不把脏值喂给可见性判定——
+ * 一个错的 message id 会把仍在本上下文里的正文误标成“已被摘要取代”。
+ */
+function toIdMap(raw) {
+    const out = new Map();
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return out;
+    for (const [k, v] of Object.entries(raw)) {
+        if (typeof v === 'string' && v.length > 0)
+            out.set(k, v);
+    }
+    return out;
+}
 /** 条目过期清理（90 天，与 recall-dedupe 同量级）。 */
 const PRUNE_MS = 90 * 24 * 3600_000;
 export class SessionRecalledStore {
@@ -65,43 +87,159 @@ export class SessionRecalledStore {
                 continue;
             if (now - (entry.updatedAt ?? 0) > PRUNE_MS)
                 continue;
-            this.entries.set(sid, { ids: new Set(entry.recordIds), updatedAt: entry.updatedAt ?? now });
+            this.entries.set(sid, {
+                ids: new Set(entry.recordIds),
+                // 旧文件没这个字段（不升版本号：升了会让老文件整体进只读降级），默认空集。
+                protectedIds: new Set(Array.isArray(entry.protectedIds) ? entry.protectedIds : []),
+                supersededIds: new Set(Array.isArray(entry.supersededIds) ? entry.supersededIds : []),
+                injectedBy: toIdMap(entry.injectedBy),
+                updatedAt: entry.updatedAt ?? now,
+            });
         }
     }
     /** 记入本 sessionKey 本轮实际注入的记录 id（写穿；插入序淘汰最旧）。 */
-    add(sessionKey, recordIds) {
+    add(sessionKey, recordIds, injectionId) {
         if (!sessionKey || recordIds.length === 0)
             return;
         let entry = this.entries.get(sessionKey);
         if (!entry) {
-            entry = { ids: new Set(), updatedAt: 0 };
+            entry = { ids: new Set(), protectedIds: new Set(), supersededIds: new Set(), injectedBy: new Map(), updatedAt: 0 };
             this.entries.set(sessionKey, entry);
         }
+        const stamp = typeof injectionId === 'string' && injectionId.length > 0 ? injectionId : undefined;
         for (const id of recordIds) {
             entry.ids.add(id);
+            // 重新注入 = 正文又回到模型上下文，取代标记随之撤销（否则一条记忆只能被取代一次）。
+            entry.supersededIds.delete(id);
+            // 记下这次注入落在哪条消息上：没有它，对账就无从判“这条正文还在不在”。
+            if (stamp !== undefined)
+                entry.injectedBy.set(id, stamp);
+            // 淘汰只能淘汰**没被判过时的**：受保护条目数本身超顶时宁可超顶，也不能把人的裁决
+            // 凭证挤掉（那等于“因为后面又召回了几条，所以之前那条的判定历史丢了”）。
             while (entry.ids.size > RECALL_DEDUPE_IDS_CAP) {
-                const oldest = entry.ids.values().next().value;
+                const oldest = [...entry.ids].find((x) => !entry.protectedIds.has(x));
                 if (oldest === undefined)
                     break;
                 entry.ids.delete(oldest);
+                entry.protectedIds.delete(oldest);
+                entry.supersededIds.delete(oldest);
+                entry.injectedBy.delete(oldest);
             }
         }
         entry.updatedAt = Date.now();
         this.rev++;
         this.writeChain = this.writeChain.then(() => this.persist());
     }
+    /**
+     * 标为受保护（判过时/软退场）：条目留在列表里，且不受上限淘汰与压缩清理影响。
+     * id 不在本会话列表里时忽略（不凭这个调用新建条目）。
+     */
+    protect(sessionKey, recordIds) {
+        const entry = this.entries.get(sessionKey);
+        if (!entry)
+            return;
+        let touched = false;
+        for (const id of recordIds) {
+            if (!entry.ids.has(id) || entry.protectedIds.has(id))
+                continue;
+            entry.protectedIds.add(id);
+            touched = true;
+        }
+        if (!touched)
+            return;
+        entry.updatedAt = Date.now();
+        this.rev++;
+        this.writeChain = this.writeChain.then(() => this.persist());
+    }
     list(sessionKey) {
         const entry = this.entries.get(sessionKey);
         return entry ? [...entry.ids] : [];
     }
-    /** 压缩/清空：注入内容已离开上下文，清该会话活召回集（写穿）。 */
-    reset(sessionKey) {
-        if (!this.entries.has(sessionKey))
+    /**
+     * 上下文事件：按原因区分。`'clear'`（用户主动清空）整表清；`'compact'`（摘要替换）**只打取代标记**。
+     *
+     * 旧实现两种都整表清，于是“压缩过一次”就把本会话召回历史（含已判过时的裁决凭证）抹平；
+     * 改成“压缩什么都不做”又让列表谎报“这些正文还在上下文里”。现在压缩只动一维：
+     * 把**此刻在列表里的**标为「已被摘要取代」（已在标记里的不再推序号）。
+     * 压缩仍然重置**去重与占用账本**（那两者关心的是“能不能重新注入”，与这张展示表无关）。
+     */
+    reset(sessionKey, reason = 'clear') {
+        const entry = this.entries.get(sessionKey);
+        if (reason !== 'clear') {
+            if (entry === undefined)
+                return;
+            let touched = false;
+            for (const id of entry.ids) {
+                // 正文已经离开上下文（它就是摘要替掉的那一批）。
+                if (entry.supersededIds.has(id))
+                    continue;
+                entry.supersededIds.add(id);
+                touched = true;
+            }
+            // 无变更不推序号：否则每次压缩都白写一遍盘、白推一次投影。
+            if (!touched)
+                return;
+            entry.updatedAt = Date.now();
+            this.rev++;
+            this.writeChain = this.writeChain.then(() => this.persist());
+            return;
+        }
+        if (entry === undefined)
             return;
         this.entries.delete(sessionKey);
         this.rev++;
         this.writeChain = this.writeChain.then(() => this.persist());
     }
+    /**
+     * 本会话「正文已被摘要取代」的 id 集（投影与端点用；只读共享。
+     * 未出现过取代的会话返回共享空集，不每次新建）。
+     */
+    supersededOf(sessionKey) {
+        return this.entries.get(sessionKey)?.supersededIds ?? EMPTY_SET;
+    }
+    /**
+     * 用会话日志的可见性事实**对账**取代标记（Phase 0B）。
+     *
+     * 判据来自宿主官方服务的 `surface.nodes`（模型可见节点集），而不是“有没有收到一条压缩事件”：
+     * 事件会漏、换代形状还会漂移，而且漏一次就永久错、无法补算。本函数每轮从事实源重算，
+     * 所以既能**标上**也能**撤销**（重新注入、或上一轮粗标记误伤的，都能自愈）。
+     *
+     * @param visible 当前仍在上下文里的注入消息 id 集
+     * @param known   会话日志里出现过的本插件注入消息 id 集。**不在 known 里的 = 该注入从未落日志**
+     *                （被宿主取消/覆盖），属“无从判”——不动它，绝不猜成“已被取代”。
+     * @returns 是否真的改动了状态（无改动不推 rev、不写盘）
+     */
+    reconcileSuperseded(sessionKey, visible, known) {
+        const entry = this.entries.get(sessionKey);
+        if (entry === undefined || entry.injectedBy.size === 0)
+            return false;
+        let touched = false;
+        for (const [id, messageId] of entry.injectedBy) {
+            if (!entry.ids.has(id))
+                continue;
+            if (!known.has(messageId))
+                continue;
+            if (visible.has(messageId)) {
+                if (entry.supersededIds.delete(id))
+                    touched = true;
+            }
+            else if (!entry.supersededIds.has(id)) {
+                entry.supersededIds.add(id);
+                touched = true;
+            }
+        }
+        if (!touched)
+            return false;
+        entry.updatedAt = Date.now();
+        this.rev++;
+        this.writeChain = this.writeChain.then(() => this.persist());
+        return true;
+    }
+    /**
+     * 注：曾有 `remove(sessionKey, recordIds)` 供「声明过时」单条摘除，已删。
+     * 理由：用户判过时后条目得留在召回列表里显示删除线，所以**只有** `reset(…, 'clear')`
+     * 能让条目离开这张列表（判过时的还受 `protectedIds` 保护，连淘汰都走不到它）。
+     */
     size() {
         return this.entries.size;
     }
@@ -156,7 +294,16 @@ export class SessionRecalledStore {
         for (const [sid, e] of this.entries) {
             if (e.ids.size === 0)
                 continue;
-            sessions[sid] = { recordIds: [...e.ids], updatedAt: e.updatedAt };
+            // 不落这个字段 = 保护只活在内存里，重启后判过时的条目又变回可被淘汰的普通条目。
+            // 空集不写键：让没保护条目的会话与改动前的文件形状逐字一致（零漂移）。
+            // 两个可选键同口径；都为空时形状仍是 {recordIds, updatedAt}。
+            sessions[sid] = {
+                recordIds: [...e.ids],
+                ...(e.protectedIds.size > 0 ? { protectedIds: [...e.protectedIds] } : {}),
+                ...(e.supersededIds.size > 0 ? { supersededIds: [...e.supersededIds] } : {}),
+                ...(e.injectedBy.size > 0 ? { injectedBy: Object.fromEntries(e.injectedBy) } : {}),
+                updatedAt: e.updatedAt,
+            };
         }
         return { version: SESSION_RECALLED_FILE_VERSION, sessions };
     }

package/dist/store/sqlite.d.ts

@@ -119,6 +119,21 @@ export declare class MemoryDb {
      * (三处列清单:DDL / insert 语句 / 本函数),故在此留下警示。
      */
     private backfillL1Fts;
+    /**
+     * 已退场 L1 行数。原本只给回灌留痕用，现在展示面也要它：
+     * `vectorCounts` 算“待补”时得分掉退场行（它们合法地无向量），否则那个数永远归不了零。
+     * 失败返回 -1——宁可日志写“未知”也不假装 0 条。
+     */
+    countL1Retired(): number;
+    /**
+     * 清除“已退场但仍待在检索面”的残留行（FTS + 向量）。幂等：第二次跑命中 0 行。
+     *
+     * 为什么必须存在于启动路径：口径修复只挡住**新增**的脏行，而存量脏行仍在给
+     * BM25/向量检索供货——对用户而言就是“标了失效却还能被召回”。
+     * 失败只 warn：这是个修复动作，无权把库拖进 degraded，更不能抛进启动
+     * 的 await 链（那里报错 = storageOk=false = 记忆功能整体停用）。
+     */
+    private purgeRetiredRetrievalRows;
     /** 重建后的 l0_fts 从 l0_conversations 全量回灌(仅 drop 重建时调用;iterate 流式)。 */
     private backfillL0Fts;
     private readEmbeddingMeta;
@@ -227,6 +242,57 @@ export declare class MemoryDb {
         repoKeyName?: string;
         repoKeyOwner?: string;
     }, expectRepoKeyName?: string): number;
+    /**
+     * 批量写 `workspace_id`（内容路由 / 存量 re-link 用）。单事务，**刻意不碰 `updated_time`**。
+     *
+     * 为什么不碰 `updated_time`（三条都是硬约束）：
+     * ① 它在 `canonicalRecords` 的哈希字段表里——动了就是“静默改写”，会让改动前建的快照
+     *    永久 verify 不通过（`workspace_id` 本身不在表里，所以**只**写它才是快照安全的）；
+     * ② 它是时效衰减（agingWeight）与列表排序的输入，改一下归属顺手把记忆“刷陈旧”是意外副作用；
+     * ③ re-link 按固定序分页扫，不写它才不会边扫边漂。
+     *
+     * 为什么连 `l1_fts` 一起改：FTS 行**自带** `workspace_id`（UNINDEXED 随行），
+     * 而检索过滤 `(? = '' OR scope='global' OR workspace_id = ?)` 读的就是 FTS 行那一列。
+     * 只改主表 = 一旦启用围栏，关键词路按旧归属过滤、向量路按新归属过滤，两路结果不一致。
+     * 退场行不在 FTS 里，那条 UPDATE 自然命中 0 行，不是错误。
+     */
+    setL1WorkspaceIds(items: ReadonlyArray<{
+        id: string;
+        workspaceId: string;
+    }>): number;
+    /**
+     * 改一条记录的文件身份名（N1）。三态返回，**不碰 `updated_time`**：它在快照哈希
+     * 字段表里、又是衰减与排序的输入——改名不是“内容变了”，不该顺带把这条记成刚更新过
+     * （与 `setL1WorkspaceIds` 同一个理由）。`name=''` 是合法值（= 没名字，部分索引不约束空串）。
+     *
+     * 唯一性由 `l1_records_name_uidx` 挡：撞名 ⇒ `'dup'`，由调用方决定报错还是让用户先改
+     * 另一条——**不自动加后缀**，那会静默造出语义重叠的第二条记忆。
+     * （另一个口径：机器给**本来没名字**的记录起名时必须消歧，见 `renameL1Batch` 的注释。）
+     */
+    renameL1(id: string, name: string): 'ok' | 'dup' | 'missing' | 'failed';
+    /**
+     * 批量写 `name`（单事务）。给“机器起名”用：存量记录没名字时一次补齐。
+     *
+     * 与 `renameL1` 的分工不是性能而是**语义**：那里是**人给的**名字，撞了就报错让用户
+     * 先改另一条，绝不静默加后缀；这里是机器给**本来没名字**的记录派生名字，同正文的
+     * 多条必然撞名（真机实测 42 条挤进 17 个路径），**不消歧就是每轮导出重刷 + 反向同步
+     * 把一份内容回灌给多条**。所以消歧必须在本层之上先把名字算唯一，本层只负责落库。
+     *
+     * 与 `renameL1` 同样**不碰 `updated_time`**（起名不是“内容变了”），也不动 FTS——
+     * `name` 不在检索面里（`l1_fts` 没这一列）。
+     *
+     * @param items - `{ id, name }`，name 已由调用方保证全库唯一。
+     * @returns 实际写入的 id 集（现值已等于目标值的跳过——幂等）与失败集。
+     */
+    renameL1Batch(items: ReadonlyArray<{
+        id: string;
+        name: string;
+    }>): {
+        done: string[];
+        failed: string[];
+    };
+    /** 按文件身份名反查 record_id（重名预检与 md 回灌用）；没这条名 ⇒ undefined。*/
+    findRecordIdByName(name: string): string | undefined;
     /** 入队一个重聚类作业(demote-to-wiki / repo 归属变化触发;source 区分来源)。 */
     enqueueSceneRecluster(family: string, sceneNames: readonly string[], batchId: string, source?: string): string;
     /** 取一个待处理作业(ruminate 空闲消费;按创建序)。 */