dsh-prime-memory 0.22.2 → 0.24.0

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 空闲消费;按创建序)。 */