dsh-prime-memory 0.22.2 → 0.24.0

package/dist/store/obsolete-notices.js

@@ -0,0 +1,153 @@
+/**
+ * 「记忆已声明过时」待播报队列（outbox，`obsolete-notices.json`）。
+ *
+ * 为什么需要它：用户在召回卡上打 `-1` 之后，**记忆库那一侧当场就改了**（退场），
+ * 但模型此刻的上下文里那条记忆还在——它得被告知"这条已由用户判定过时、别再依据它
+ * 作答"。这个告知是一次性的：下一轮注入即出队，不常驻（常驻是槽位的语义，见
+ * `hooks/slot-recall.ts`）。
+ *
+ * 落盘而非纯内存：打 `-1` 到下一轮之间若进程重启，纯内存会**静默丢掉这一票**——
+ * 记忆已经退场了，而模型从没被告知。所以 outbox 必须持久化（与 session-recalled
+ * 同款纪律：写穿 + 版本 + 损坏只读降级，绝不抛进注入热路径）。
+ *
+ * 键 = sessionKey（`agent.session?.id ?? agent.id`），与活召回集、pill 的 sessionId
+ * 同源；三处不同键会直接导致"播报错会话"，见 store/session-recalled.ts 头注。
+ */
+import * as path from 'node:path';
+import { readJsonStrict, atomicWriteText, ensureDir } from '../util/io.js';
+export const OBSOLETE_NOTICES_FILE_VERSION = 1;
+/** 单会话待播报上限（超出丢最旧：模型只需知道"这些别再信"，不需历史）。 */
+const PER_SESSION_CAP = 8;
+/** 会话数上限，按最近写入时间淘汰。 */
+const SESSION_CAP = 200;
+const TITLE_MAX = 120;
+export class ObsoleteNoticeStore {
+    logger;
+    file;
+    buckets = new Map();
+    loaded = false;
+    degraded;
+    degradedLogged = false;
+    writeChain = Promise.resolve();
+    rev = 0;
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = path.join(dataDir, 'obsolete-notices.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.sessions ?? {};
+        for (const [sid, list] of Object.entries(raw)) {
+            const kept = this.normalize(list);
+            if (kept.length > 0)
+                this.buckets.set(sid, kept);
+        }
+        this.loaded = true;
+    }
+    normalize(list) {
+        if (!Array.isArray(list))
+            return [];
+        const out = [];
+        for (const raw of list) {
+            if (!raw || typeof raw !== 'object')
+                continue;
+            const e = raw;
+            if (typeof e.id !== 'string' || !e.id || typeof e.title !== 'string' || typeof e.at !== 'number')
+                continue;
+            out.push({ id: e.id, title: e.title, at: e.at });
+            if (out.length >= PER_SESSION_CAP)
+                break;
+        }
+        return out;
+    }
+    ensureLoaded() {
+        if (!this.loaded)
+            throw new Error('过时播报队列未初始化(先 await init())');
+    }
+    /** 判脏序号(测试/观测用;注入侧靠 drain 的返回值判断有无)。 */
+    revision() {
+        return this.rev;
+    }
+    /** 入队一条(幂等由调用方保证:同 id 重复入队只会多播一行，故这里去重)。 */
+    push(sessionKey, notice) {
+        this.ensureLoaded();
+        if (!sessionKey)
+            return;
+        const list = this.buckets.get(sessionKey) ?? [];
+        if (list.some((n) => n.id === notice.id))
+            return;
+        const title = notice.title.length > TITLE_MAX ? `${notice.title.slice(0, TITLE_MAX)}…` : notice.title;
+        const next = [...list, { ...notice, title }];
+        this.buckets.set(sessionKey, next.slice(-PER_SESSION_CAP));
+        this.rev += 1;
+        this.prune();
+        this.schedulePersist();
+    }
+    /** 出队并清空该会话的待播报(一次性语义:取走即离开 outbox)。 */
+    drain(sessionKey) {
+        this.ensureLoaded();
+        const list = this.buckets.get(sessionKey);
+        if (list === undefined || list.length === 0)
+            return [];
+        this.buckets.delete(sessionKey);
+        this.rev += 1;
+        this.schedulePersist();
+        return list;
+    }
+    /** 只看不取(测试/诊断)。 */
+    peek(sessionKey) {
+        this.ensureLoaded();
+        return [...(this.buckets.get(sessionKey) ?? [])];
+    }
+    size() {
+        this.ensureLoaded();
+        let n = 0;
+        for (const list of this.buckets.values())
+            n += list.length;
+        return n;
+    }
+    prune() {
+        if (this.buckets.size <= SESSION_CAP)
+            return;
+        const newestAt = (list) => list.reduce((m, n) => Math.max(m, n.at), 0);
+        const byOldest = [...this.buckets.entries()].sort((a, b) => newestAt(a[1]) - newestAt(b[1]));
+        for (const [sid] of byOldest.slice(0, this.buckets.size - SESSION_CAP))
+            this.buckets.delete(sid);
+    }
+    schedulePersist() {
+        if (this.degraded)
+            return;
+        this.writeChain = this.writeChain.then(() => this.persist(), () => this.persist());
+    }
+    async persist() {
+        if (this.degraded)
+            return;
+        const body = {
+            version: OBSOLETE_NOTICES_FILE_VERSION,
+            sessions: Object.fromEntries(this.buckets),
+        };
+        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-feedback.d.ts

@@ -0,0 +1,75 @@
+import type { MemoryLogger } from '../types.js';
+export declare const RECALL_FEEDBACK_FILE_VERSION: 1;
+/** 合法打分：-1（声明过时）与 0..5（相关度）。 */
+export declare const FEEDBACK_SCORES: readonly [-1, 0, 1, 2, 3, 4, 5];
+export type FeedbackScore = (typeof FEEDBACK_SCORES)[number];
+/** 单条记忆的反馈聚合。 */
+export interface RecallFeedbackEntry {
+    /** 最近一次打分(-1..5)。 */
+    last: FeedbackScore;
+    /** 有效相关度评分次数(不含 -1)。 */
+    rated: number;
+    /** 0..5 评分均值(rated=0 时为 0)。 */
+    mean: number;
+    /** 被声明过时的次数(-1 计数)。 */
+    obsolete: number;
+    /** 最近一次打分时刻(epoch ms)。 */
+    updatedAt: number;
+    /** 最近若干条打分轨迹(旧→新，截断至 HISTORY_CAP)。 */
+    history: Array<{
+        s: FeedbackScore;
+        at: number;
+    }>;
+}
+/** 是否合法打分(供端点入参校验复用)。 */
+export declare function isFeedbackScore(v: unknown): v is FeedbackScore;
+export declare class RecallFeedbackStore {
+    private readonly logger?;
+    private readonly file;
+    private entries;
+    private loaded;
+    private degraded;
+    private degradedLogged;
+    private writeChain;
+    /** 判脏序号:每次有效写入 +1(投影 view 带 rating，靠它决定要不要重建)。 */
+    private rev;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    init(): Promise<void>;
+    /** 读侧逐条收窄:形状不符的条目丢弃，不让一条坏数据拖垮整表。 */
+    private normalize;
+    private ensureLoaded;
+    /** 判脏序号(供投影 O(1) 决定要不要重建 view)。 */
+    revision(): number;
+    /**
+     * 记一次打分。返回聚合后的条目(供端点回执)。
+     * 只聚合不裁决:`-1` 进 obsolete 计数、不进均值(过时不是"不相关",两回事)。
+     */
+    rate(id: string, score: FeedbackScore, at?: number): RecallFeedbackEntry;
+    get(id: string): RecallFeedbackEntry | undefined;
+    /** 均值(0..5);无有效评分 → undefined(缺席 ≠ 0 分)。 */
+    meanOf(id: string): number | undefined;
+    /** 最近一次打分(-1..5);未标注 → undefined。 */
+    lastOf(id: string): FeedbackScore | undefined;
+    /**
+     * 把一条记录的人工标注搬到新 id（merge 之后由管线调用，P0-d）。
+     *
+     * 不搬的后果比使用史更直接：成熟度只吃“人工最近一笔”，而 `last` 留在旧 id 上
+     * 就等于新记录**看起来从没被人打过**；更坏的是旧 id 上那一笔 `-1`（已判过时）
+     * 会跟着旧行一起沉进垃圾堆，新行反而以“未标注”的活状态回到召回里。
+     *
+     * 计数按相加、不按轨迹重算：`history` 截断到 12 条，拿它反推 `obsolete` 必然少算。
+     * 两侧都有条目时取较新一侧的 `last`，轨迹按时间归并。
+     */
+    rekey(oldId: string, newId: string): boolean;
+    summary(): {
+        tracked: number;
+        rated: number;
+        obsolete: number;
+    };
+    private prune;
+    /** 立即落盘(串行链上排队,不与在途写交错)。 */
+    private schedulePersist;
+    private persist;
+    /** 等待在途写完成(测试/停机用)。 */
+    flush(): Promise<void>;
+}

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>;