@modusensus/dsh-mneme 0.11.0 → 0.13.0

package/src/service.js

@@ -7,6 +7,7 @@ import { STR, langOf } from "./lang.js";
 import { computeHeat } from "./heat.js";
 import { recallStats } from "./recall-stats.js";
 import { evaluateMemoryQuality } from "./quality-filter.js";
+import { CAPACITY_WARNING_DEFAULTS } from "./config.js";
 // 外来行（source='imported'，导入路径落的来源）的身份判定只许有一个定义处——本文件的
 // 两处汇流口与巩固/降级那些读侧行池都调这同一个谓词，避免各处自己写字符串比较然后各自漂移。
 import { isImportedRow } from "./memory-source.js";
@@ -516,9 +517,12 @@ export function createService({ store, mirror, config, onWrite, logger, document
   // Weighted blend factor for hybrid search; exposed so callers can tune it.
   const DEFAULT_HYBRID_WEIGHTS = { vector: 0.6, keyword: 0.4 };
 
-  // Cosine over two plain arrays (shared by the search-time semantic dedup).
+  // Cosine over two numeric vectors (shared by the search-time semantic dedup).
+  // Accepts typed arrays too — the store's cache holds Float32Array, and
+  // `Array.isArray` is false for typed arrays (would score everything 0).
   function cosineVec(a, b) {
-    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length || !a.length) return 0;
+    const isVec = (v) => Array.isArray(v) || (ArrayBuffer.isView(v) && !(v instanceof DataView));
+    if (!isVec(a) || !isVec(b) || a.length !== b.length || !a.length) return 0;
     let dot = 0, na = 0, nb = 0;
     for (let i = 0; i < a.length; i++) {
       dot += a[i] * b[i];
@@ -529,6 +533,25 @@ export function createService({ store, mirror, config, onWrite, logger, document
     return dot / (Math.sqrt(na) * Math.sqrt(nb));
   }
 
+  // BM25 语料索引缓存（#617 审计 O2）。此前每次渲染都 store.list 500 行 + 重新
+  // tokenize 全语料，实测 4.318ms/次、每个 step 一次；其中 store.list 占 4.318ms
+  // 里的绝大部分，而语料在两次写入之间根本没变。
+  //
+  // 失效键用 mirror_state.generation，不另建计数器：改正文/可见性的写入（insert /
+  // update / remove / setArchived / setForgotten / setContent …）都已经 bump 它，
+  // 而 last_accessed_at 与 embedding 这两类写入**刻意不 bump**（store.js 里写明
+  // reads must not mark the mirror dirty）——这两类恰好也不改 title+content 语料，
+  // 正是我们要的失效粒度，不用额外判断。
+  //
+  // 水位每次从库里现读，不在进程内记本地计数：多宿主共用一个 memoryDir 是支持形态
+  // （busy_timeout + WAL），另一个进程写完 bump 的是库里的 generation，本地计数
+  // 永远看不见，只有现读才收得到。
+  //
+  // 只缓存索引、不缓存查询结果：search() 返回的是 {...row, score} 副本，索引里
+  // 留着的原始行不会被调用方改到；缓存结果则会跨 step 串味（同一 query 在不同
+  // 池子状态下该给不同答案）。
+  let bm25IndexCache = null; // { generation, index } | null
+
   /**
    * BM25 third recall path (v0.5.0 1.1). Scores the query tokens against the
    * live non-archived rows and returns the top `limit` hits with scores
@@ -538,14 +561,40 @@ export function createService({ store, mirror, config, onWrite, logger, document
   function bm25Recall(q, limit) {
     if (config?.bm25SearchEnabled === false) return [];
     try {
-      const docs = store.list({ limit: 500, includeForgotten: false }).filter((m) => !m.archived);
-      if (!docs.length) return [];
-      return createBM25Index(docs).search(q, { limit });
+      const index = bm25CorpusIndex();
+      if (!index) return [];
+      return index.search(q, { limit });
     } catch {
       return [];
     }
   }
 
+  /**
+   * 取（必要时重建）BM25 语料索引。水位读不到时退化成每次重建而不是报错：这条
+   * 通路是 recall booster，读不到 mirror_state 只该慢一点，不该让词法召回整批消失。
+   */
+  function bm25CorpusIndex() {
+    let generation = null;
+    try {
+      generation = store.getMirrorState().generation;
+    } catch { /* 水位不可读：本次退回重建，且不写缓存 */ }
+    if (bm25IndexCache && generation !== null && bm25IndexCache.generation === generation) {
+      return bm25IndexCache.index;
+    }
+    const docs = store.list({ limit: 500, includeForgotten: false }).filter((m) => !m.archived);
+    if (!docs.length) {
+      bm25IndexCache = null;
+      return null;
+    }
+    const index = createBM25Index(docs);
+    // 水位读不到时**不碰缓存**，保留上一份「已知有效 generation」的条目：读失败
+    // 若只是偶发（库锁、迁移窗口）而期间没有写入，恢复后水位与条目一致，直接命中；
+    // 期间真有写入，水位已经变了，下一轮自然重建。反过来把 null 当键存进去则是纯
+    // 噪声——那样的条目永远命不中，还把有效的那份挤掉了。
+    if (generation !== null) bm25IndexCache = { generation, index };
+    return index;
+  }
+
   /**
    * Graph fourth recall path (issue #219 → #24 块1 锚定层). When the query text
    * mentions a known entity name, memories linked to that entity (attrs +
@@ -919,18 +968,13 @@ export function createService({ store, mirror, config, onWrite, logger, document
       }
     }
 
-    // Mode contract, auto (aligns rrf/minmax with blend): keyword leads, the
-    // recipe fills the remaining slots. blend.auto already front-loads keyword;
-    // rrf/minmax rank across sources, so re-apply the same "keyword first"
-    // ordering here to preserve the pre-fusion auto contract — the keyword
-    // hit list keeps its power, and only slots it couldn't fill go to the
-    // recipe's ranking.
-    if (recipe !== "blend" && mode === "auto" && keyword.length) {
-      const head = keyword.slice(0, lim);
-      const seen = new Set(head.map((m) => m.id));
-      const tail = merged.filter((m) => !seen.has(m.id)).slice(0, Math.max(0, lim - head.length));
-      merged = head.concat(tail);
-    }
+    // #617 第 3 条：这里原本还有一段「recipe !== "blend" 且 mode === "auto" 时用
+    // keyword.slice(0,lim) 覆盖 merged」的收尾，注释自称是「保留 blend 的 auto
+    // 契约」。但 rrf/minmax 的全部意义就是跨源排序——把它们算出来的序整个换成
+    // 「关键词命中先上」，等于配置了 rrf 却在 auto 下拿到 keyword 的顺序，配方
+    // 白选。auto 的「关键词领位」语义只属于 blend（它在 :906-922 里自己实现了，
+    // 且带 seen 去重与容量控制），不该由收尾段替别的配方代劳。删掉后 rrf/minmax
+    // 的 auto 排序就是它们各自算出来的排序。
 
     return { merged, signals };
   }
@@ -1775,62 +1819,60 @@ export function createService({ store, mirror, config, onWrite, logger, document
           (effImportance(a) * qualityWeight(a) * heatOf(a) * scopeMultOf(a));
       });
     let candidates = items;
+    // #617 第 2 条（前半）：向量路与 BM25 路此前是**互斥**的——`if (!semanticItems.length)`
+    // 包住 BM25，于是「有向量」等于「词法命中整批消失」。可两条路测的不是同一件事：
+    // 向量管「意思像」，BM25 管「词面撞上」，专有名词、issue 编号、函数名这类查询
+    // 恰恰是向量最容易糊、词法最准的地方。现在两路都跑，用 RRF（k=60）融合排名：
+    // 某一路的第 1 名恒得 1/(60+1)，两路都靠前的行自然走高，不再由「谁先跑」决定。
+    // 另外先按 fetchLimit 多取再过滤——旧代码先按 poolSize 截断再筛门控，筛掉的
+    // 名额永远补不回来（缩水），池子越脏越明显。
+    let fusedRrf = null; // id -> RRF 原始分；selectiveInject 复用它做二次重排
     if (config.hybridInject !== false && q) {
-      // Bug4: semantic-first recall. Vector hits (queryVector, cached by the
-      // injector's async prefetch) lead when present; otherwise the last
-      // searchMemories recall for the exact same query is reused. Rule-based
-      // items fill + dedupe the remaining slots. Empty query / no vector /
-      // no cached recall → pure legacy rule-based selection.
-      const semanticItems = [];
+      const fetchLimit = Math.max(poolSize * 4, 40);
+      const passesGate = (m) => Boolean(m) && !m.archived && injectTypes.has(m.type) && !m.forgotten &&
+        (m.source !== "narrative" || allowNarrative) &&
+        codingGate(m) &&
+        (m.type === "summary" || m.type === "preference" || m.importance >= threshold);
+      const vectorHits = [];
       if (Array.isArray(queryVector) && queryVector.length && vectorIndex) {
         try {
-          const hits = vectorIndex.search(queryVector, { limit: poolSize, threshold: 0 });
-          for (const m of hits) {
-            if (m && !m.archived && injectTypes.has(m.type) && !m.forgotten &&
-              (m.source !== "narrative" || allowNarrative) &&
-              codingGate(m) &&
-              (m.type === "summary" || m.type === "preference" || m.importance >= threshold)) {
-              semanticItems.push(m);
-            }
+          for (const m of vectorIndex.search(queryVector, { limit: fetchLimit, threshold: 0 })) {
+            if (passesGate(m)) vectorHits.push(m);
           }
         } catch { /* vector unavailable: fall through to the recall cache */ }
       }
-      if (!semanticItems.length && lastSemanticRecall?.query === q && lastSemanticRecall.items?.length) {
-        // CodeRabbit on #404：这条回填分支此前独漏重要度门槛——向量路（上方）与
-        // BM25 路（下方 :1655 注释「门控与向量路径一致（含 importance 阈值）」）
+      if (!vectorHits.length && lastSemanticRecall?.query === q && lastSemanticRecall.items?.length) {
+        // CodeRabbit on #404：这条回填分支此前独漏重要度门槛——向量路与 BM25 路
         // 都带着它。#369 收编 history 后缺口会被放大：库里低于闸门的行（实测
         // history 378 条中有 27 条 i<=2）走一次检索进缓存就能绕开门槛占注入位。
-        for (const m of lastSemanticRecall.items) {
-          if (m && !m.archived && injectTypes.has(m.type) && !m.forgotten &&
-            (m.source !== "narrative" || allowNarrative) && codingGate(m) &&
-            (m.type === "summary" || m.type === "preference" || m.importance >= threshold)) semanticItems.push(m);
-        }
-      }
-      // Issue #198：首轮（无向量、无缓存召回）的同步兜底——BM25 词法召回领位。
-      // 注入渲染是同步的（宿主 systemPrompt 的 contexts 不支持异步 text），
-      // 查询向量只能异步 prefetch 给下一轮，首轮必 miss；此时纯静态排序会让
-      // 老的高重要性 summary/preference 占满槽位，当前话题的 decision/project
-      // 进不来。查询文本本身就在手上，BM25 是纯进程内同步计算，词法相关性
-      // 足以把当前话题顶到前排；门控与向量路径一致（含 importance 阈值）。
-      // 语义向量命中时本分支不参与，行为不变。
-      if (!semanticItems.length) {
-        for (const hit of bm25Recall(q, poolSize)) {
-          if (hit && !hit.archived && injectTypes.has(hit.type) && !hit.forgotten &&
-            (hit.source !== "narrative" || allowNarrative) &&
-            codingGate(hit) &&
-            (hit.type === "summary" || hit.type === "preference" || hit.importance >= threshold)) {
-            semanticItems.push(hit);
-          }
-        }
-        // issue #339（CodeRabbit review on #350）：首轮 BM25 兜底领跑合并池，
-        // 而 selectiveInject 相似度重排要等查询向量就绪才执行——软加权必须
-        // 在这里就位，否则 foreign 命中绕过降权直接占注入位。
-        if (softScopeActive) {
-          semanticItems.sort((a, b) =>
-            (b.score ?? 0) * scopeMultOf(b) - (a.score ?? 0) * scopeMultOf(a));
-        }
+        for (const m of lastSemanticRecall.items) if (passesGate(m)) vectorHits.push(m);
       }
-      if (semanticItems.length) {
+      // Issue #198：BM25 词法路。首轮（无向量、无缓存召回）这是唯一的同步相关性
+      // 信号；有向量时它补上向量糊掉的那一类命中。#617 之后它不再被向量挤掉。
+      const bm25Hits = [];
+      for (const hit of bm25Recall(q, fetchLimit)) if (passesGate(hit)) bm25Hits.push(hit);
+      if (vectorHits.length || bm25Hits.length) {
+        const RRF_K = 60;
+        const rrf = new Map();
+        const rowById = new Map();
+        const addList = (list) => {
+          list.forEach((m, idx) => {
+            rowById.set(m.id, m);
+            rrf.set(m.id, (rrf.get(m.id) ?? 0) + 1 / (RRF_K + idx + 1));
+          });
+        };
+        addList(vectorHits);
+        addList(bm25Hits);
+        fusedRrf = rrf;
+        // 软加权（issue #339 / CodeRabbit on #350）作用在融合分上：foreign 行不再
+        // 靠一路的原始 score 绕过降权，也不需要像旧代码那样单独给 BM25 排一次序。
+        const ranked = [...rrf.entries()]
+          .map(([id, score]) => {
+            const m = rowById.get(id);
+            return { m, score: score * scopeMultOf(m) };
+          })
+          .sort((a, b) => b.score - a.score)
+          .map((row) => row.m);
         const seen = new Set();
         const merged = [];
         const push = (m) => {
@@ -1838,7 +1880,7 @@ export function createService({ store, mirror, config, onWrite, logger, document
           seen.add(m.id);
           merged.push(m);
         };
-        for (const m of semanticItems) {
+        for (const m of ranked) {
           push(m);
           if (merged.length >= poolSize) break;
         }
@@ -1849,21 +1891,104 @@ export function createService({ store, mirror, config, onWrite, logger, document
         candidates = merged;
       }
     }
+    // pin 池取数修复（#249 第一批）：pin 类行被混合合并的封顶挡在候选池外面。
+    // `merged.length >= poolSize` 在 pin 筛选**之前**就封顶（生产 maxItems=5 →
+    // poolSize=10，向量路一次正好返回 10 条即 break），规则窗口里那些
+    // constraint/preference 于是一条都进不了 candidates，pin 池只能从那 10 条里
+    // 碰运气选——而本文件注释（:1919）与 issue #249 验收都写着「pin 不占
+    // maxItems 名额」。实测真库 maxItems=5 时 pin shown 只有 2/5，补回后恒 5/5；
+    // maxItems=10（poolSize=20）时前后都是 5/5——所以这不是多给名额，只是把被
+    // 向量路吃掉的那部分补回来。
+    // 两条纪律：①只在 pin 预算 > 0 时补，预算关时 candidates 与改前逐字节一致；
+    // ②只补到候选池尾部，后面的 strictScope（:1923）与 scopeState（:1930）两道
+    // 闸门照旧作用其上，「pin 池 eligible 取自过滤之后的候选」这条位置纪律不变。
+    //
+    // #249 第二批（显式 pin）：判据从「类型」换成「用户亲手钉的 id」。两种口径
+    // 由 pinned_memories 表**里能用的行**回答，而不是由「表里有几行」回答：
+    // - 有可用行 → explicit：按 id 点查（store.listByIdsForInject）取回行，于是
+    //   **200 行规则窗口之外的记忆也能进**（这是第二层存在的理由本身）；不再按
+    //   type 认 pin（写得最全的那版往往是 pattern，限类型就只能拿残缺版）。
+    // - 一条可用行都没有 → 回落旧的类型口径，升级即等价；她钉第一条才切换。
+    //
+    // ⚠ 判据为什么必须看「能用的」而不是 countPinned()>0：pin 行会在 memories
+    // 那边被归档、遗忘、硬删，而 pinned_memories 对这三种一无所知。用 count(*)
+    // 当判据，只要表里剩一行（哪怕是归档行），pinMode 就永远钉在 explicit，而
+    // eligible 恒为空 → pin 全灭且**永不回落**，无日志无报错——正是这批改动要
+    // 治的那类静默失败。删除路径补 DELETE 只堵「硬删」这一种，归档/遗忘比硬删
+    // 常见得多，所以根因在判据，不在清理。
+    // 只要还有一条能用就留在 explicit、只注入能用的那几条：若因为「有 3 条归档」
+    // 就整段回落到类型口径，会突然冒出一批她没钉过的条目，那比少注入更糟。
+    // 补位仍在这段：早于 topic 重排（:1930）、strictScope（:1972）、scopeState
+    // （:1979），所以越权行与暂停作用域行照样过两道闸——pin 不是绕过闸门的通道。
+    // 预算 0 时整段不执行：不读表、不改 candidates，逐字节等于改前。
+    const pinnedBudget = Math.max(0, Math.min(5, Math.floor(config?.pinnedInjectBudget ?? 0)));
+    // null | "explicit" | "type-fallback" | "fallback-none-usable"
+    let pinMode = null;
+    let pinRows = [];              // explicit：按 pin 先后（created_at ASC）排好、已滤遗忘/归档
+    let pinOutsideWindow = 0;      // explicit：点查取回、原本不在候选池的行数（观测点）
+    if (pinnedBudget > 0) {
+      let pinRecords = [];
+      try {
+        // 先读表（本表行数以个位计）；能用的行下一步按 id 点查回来再判。
+        pinRecords = store.countPinned() > 0 ? store.listPinned() : [];
+      } catch { pinRecords = []; }
+      if (pinRecords.length > 0) {
+        try {
+          // 点查带列裁剪（listByIdsForInject 复用 memoryColumnList，已排除 embedding）。
+          // 遗忘/归档行在这里就滤掉：pin 不是复活通道（验收第 7 条）。
+          const byId = new Map(store.listByIdsForInject(pinRecords.map((p) => p.memory_id))
+            .map((m) => [m.id, m]));
+          pinRows = pinRecords.map((p) => byId.get(p.memory_id)).filter((m) => m && !m.forgotten && !m.archived);
+        } catch { pinRows = []; }
+      }
+      if (pinRows.length > 0) {
+        pinMode = "explicit";
+        const knownIds = new Set(candidates.map((m) => m.id));
+        const additions = pinRows.filter((m) => !knownIds.has(m.id));
+        pinOutsideWindow = additions.length;
+        if (additions.length) candidates = [...candidates, ...additions];
+      } else {
+        // 表空，或表里有行但一条都用不了（归档/遗忘/被删）。两种都回落类型口径，
+        // 但 source 分开记：后者是一次**静默降级**，必须留痕，否则读的人只会看到
+        // 「pin 一条都没注入」而不知道为什么。
+        pinMode = pinRecords.length > 0 ? "fallback-none-usable" : "type-fallback";
+        if (candidates !== items) {
+          const knownIds = new Set(candidates.map((m) => m.id));
+          const spilledPins = items.filter(
+            (m) => PINNED_MEMORY_TYPES.has(m.type) && m.graphHint !== true && !knownIds.has(m.id)
+          );
+          if (spilledPins.length) candidates = [...candidates, ...spilledPins];
+        }
+      }
+    }
     // Topic-ranked selection (v0.5.0 2.2): when the current query's vector is
     // available the whole candidate list is re-ordered by similarity to that
     // vector, so the injected slots go to memories on the current topic
     // rather than to the rule-based order. Rows the index did not return
     // keep their relative order after the scored ones.
+    //
+    // #617 第 2 条（后半）：这段此前是**纯余弦**全量 sort，于是上游用 RRF 顶上来的
+    // BM25 命中（词面精确、余弦却低）会被重新压到 maxItems 之后，再被 general 槽
+    // 的 `general.length >= maxItems` 丢掉——融合白做。现在余弦只占一半权重，另一半
+    // 给 RRF 分（同一轮融合算出来的那份）：纯余弦命中仍是主体，但词法精确命中
+    // 不会因为「意思不够像」被挤出去。
+    // RRF 归一化：单路第 1 名原始分 1/(60+1)，乘 (60+1)/2 得 0.5，双路都在第 1 名
+    // 得 1.0 —— 与余弦同量纲，且天然落在 [0,1]。
     if (config?.selectiveInjectEnabled !== false && Array.isArray(queryVector) && queryVector.length && vectorIndex) {
       try {
         const hits = vectorIndex.search(queryVector, { limit: 200, threshold: 0 });
         const sim = new Map(hits.map((m) => [m.id, m.score ?? 0]));
         if (sim.size) {
-          // 软加权作用在真实 sim 上；未命中的规则候选保持 -1 沉底（缺失项
-          // 乘乘数会让 foreign 缺失项反而排到自己的缺失项之上，故不乘）。
+          const RRF_NORM = (60 + 1) / 2;
+          // 软加权乘在融合分上（不是乘在某一路的原始分上）；两路都没有的规则
+          // 候选保持 -1 沉底（缺失项乘乘数会让 foreign 缺失项反而排到自己的缺失
+          // 项之上，故不乘）。
           const scopedSim = (m) => {
             const s = sim.get(m.id);
-            return s === undefined ? -1 : s * scopeMultOf(m);
+            const rrf = fusedRrf?.get(m.id);
+            if (s === undefined && rrf === undefined) return -1;
+            const fused = 0.5 * (s ?? 0) + 0.5 * (rrf ?? 0) * RRF_NORM;
+            return fused * scopeMultOf(m);
           };
           candidates = [...candidates].sort((a, b) => scopedSim(b) - scopedSim(a));
         }
@@ -1909,12 +2034,24 @@ export function createService({ store, mirror, config, onWrite, logger, document
     // （验收：pin 不参与跨轮轮换）。独立预算的两层意义：pin 既不占 maxItems
     // 名额、也不被 document 预算截断，因此不会把当前任务需要的情景候选挤出去；
     // 超预算的条数回报给调用方，在块内如实标注（绝不静默省略）。
-    const pinnedBudget = Math.max(0, Math.min(5, Math.floor(config?.pinnedInjectBudget ?? 0)));
+    // （pinnedBudget 与口径在候选池那段已算好——见 :1876 起的 #249 第二批注释。）
     // eligible 留到块外：未展示条数要等 general 槽选完才算得准（见 selected 之后）。
     // graphHint 行不进 pin 池：pin 是「每轮必进的约束/偏好」，而线索行按定义是
     // 「链路信息、非事实断言」，且 pin 长在候选池遍历之前——不排除的话，保守档
     // （graphInjectHint 关）也能从 pin 侧把它放回注入块，线索开关就被绕过去了。
-    const eligible = pinnedBudget > 0 ? candidates.filter((m) => PINNED_MEMORY_TYPES.has(m.type) && m.graphHint !== true) : [];
+    //
+    // 两种口径（#249 第二批）：explicit 时 eligible 就是「钉过、点查取回、且过了
+    // 两道闸（仍在 candidates 里）」的行，次序按 pin 先后（created_at ASC）——
+    // 稳定偏好按「什么时候被钉」排，而不是按「最近改过」，正是第二层要修的
+    // 那个排序维度；type-fallback 时保持旧口径（候选里按类型筛），升级即等价。
+    const eligible = pinnedBudget > 0
+      ? (pinMode === "explicit"
+        ? (() => {
+            const live = new Set(candidates.map((m) => m.id));
+            return pinRows.filter((m) => live.has(m.id) && m.graphHint !== true);
+          })()
+        : candidates.filter((m) => PINNED_MEMORY_TYPES.has(m.type) && m.graphHint !== true))
+      : [];
     let pinned = [];
     if (pinnedBudget > 0 && eligible.length > 0) {
       pinned = eligible.slice(0, pinnedBudget);
@@ -1969,6 +2106,17 @@ export function createService({ store, mirror, config, onWrite, logger, document
       const shownIds = new Set(selected.map((m) => m.id));
       pinnedStats.shown = pinned.length;
       pinnedStats.suppressed = eligible.filter((m) => !shownIds.has(m.id)).length;
+      // #249 第二批：口径来源与「绕开窗口」的观测点。source 四档（预算 0 时整个
+      // 键不出现）：
+      //   "explicit"              用户钉的行里有能用的，按 pin 先后注入
+      //   "type-fallback"         表里从没钉过（含升级后还没钉），走旧类型口径
+      //   "fallback-none-usable"  钉过，但那些行全被归档/遗忘/删了 —— 这次是一次
+      //                           静默降级，留这一档就是为了让它不再静默
+      // 前两档的行为差异在「窗口外也能进」：只有 explicit 享受点查补位，
+      // outsideWindow 也只数这批（cognee 那条「别让它进候选池」的等价做法）；
+      // 两个 fallback 档恒 0（它们只能从窗口里取）。
+      pinnedStats.source = pinMode ?? undefined;
+      pinnedStats.outsideWindow = pinOutsideWindow;
     }
     // Issue #380：注入前判定（preInjectGate）在这里消费——**必须在 touchRecalled
     // 之前**，与 strictScope 同纪律（见本文件 :419-422 的注释：闸门放在记账之后，
@@ -2164,6 +2312,10 @@ export function createService({ store, mirror, config, onWrite, logger, document
       id: r.id,
       run_id: r.run_id ?? null,
       reason: r.reason ?? null,
+      // Issue #603 第 2 层：入队时记下的相似度（0–1）。存量行与 LLM 裁决路径
+      // 没记 → null。面板据此排序与画条，不再从 reason 文本里正则回收；
+      // null 与 0 必须区分开（「没测过」不是「不相似」）。
+      similarity: typeof r.similarity === "number" ? r.similarity : null,
       created_at: r.created_at,
       memory_a: side(r.memory_a),
       memory_b: side(r.memory_b)
@@ -2516,6 +2668,71 @@ export function createService({ store, mirror, config, onWrite, logger, document
     }
   }
 
+  // getCapacityHealth：容量预警（#275 空间维度）——库体积 / 归档区规模是否过线。
+  // 与 getMirrorHealth 同款 fail-safe：读失败显式 unknown，绝不伪装成 ok，也绝不
+  // 向外抛（/health 还有镜像那半张答复，容量不能把整张健康面拖塌）。
+  // 阈值读 config.capacityWarning；config 缺席（直连调用方 / 测试传裸对象）时退回
+  // config.js 的同一份常量，不另立一套数字。答复里只有数字，**绝不带 storageStats
+  // 的 path**——那是本机文件系统布局，/health 是半张对外面。
+  function getCapacityHealth() {
+    const unknown = () => ({
+      status: "unknown",
+      file_bytes: null,
+      freelist_bytes: null,
+      active_rows: null,
+      archived_rows: null,
+      archived_ratio: null,
+      checks: []
+    });
+    try {
+      const cfg = { ...CAPACITY_WARNING_DEFAULTS, ...(config?.capacityWarning ?? {}) };
+      const stats = store.storageStats();
+      const counts = store.capacityStats();
+      const total = counts.active + counts.archived;
+      const ratio = total > 0 ? counts.archived / total : null;
+      const checks = [];
+      // 每条检查：阈值 > 0 才启用（0 = 显式关掉这一条），过线判 >= ——「到阈值」
+      // 即报警（#275 口径）。没法评的检查直接缺席而不是伪装 ok：file_bytes 为
+      // null（:memory: 库）时体积检查进不了列表，total 为 0 时占比检查同理。
+      if (cfg.dbSizeWarnMb > 0 && stats.fileBytes !== null) {
+        checks.push({
+          key: "db_size",
+          status: stats.fileBytes >= cfg.dbSizeWarnMb * 1048576 ? "warn" : "ok",
+          value_bytes: stats.fileBytes,
+          threshold_bytes: cfg.dbSizeWarnMb * 1048576
+        });
+      }
+      if (cfg.archivedRowsWarn > 0) {
+        checks.push({
+          key: "archived_rows",
+          status: counts.archived >= cfg.archivedRowsWarn ? "warn" : "ok",
+          value: counts.archived,
+          threshold: cfg.archivedRowsWarn
+        });
+      }
+      if (cfg.archivedRatioWarn > 0 && ratio !== null) {
+        checks.push({
+          key: "archived_ratio",
+          status: ratio >= cfg.archivedRatioWarn ? "warn" : "ok",
+          value: Math.round(ratio * 1000) / 1000,
+          threshold: cfg.archivedRatioWarn
+        });
+      }
+      return {
+        status: checks.some((c) => c.status === "warn") ? "warn" : "ok",
+        file_bytes: stats.fileBytes,
+        freelist_bytes: stats.freelistCount * stats.pageSize,
+        active_rows: counts.active,
+        archived_rows: counts.archived,
+        archived_ratio: ratio === null ? null : Math.round(ratio * 1000) / 1000,
+        checks
+      };
+    } catch (error) {
+      logger?.warn?.("getCapacityHealth failed:", error);
+      return unknown();
+    }
+  }
+
   // 返回字面量与内部裁决器（resolveConflictPending → applyDecisions 的 conflict
   // 处置）共用的写路径：mirror 同步、写通知、嵌入调度全部同源，不能各写一份。
   function updateMemory(id, p, ctx = {}) {
@@ -2669,6 +2886,7 @@ export function createService({ store, mirror, config, onWrite, logger, document
     organize,
     recoverMirror,
     getMirrorHealth,
+    getCapacityHealth,
     getMirrorState: () => store.getMirrorState(),
     injectCandidates,
     mergeHumanEdits,
@@ -2688,6 +2906,15 @@ export function createService({ store, mirror, config, onWrite, logger, document
     setScopeState: (r) => store.setScopeState(r),
     getScopeState: (d, v) => store.getScopeState(d, v),
     listScopeStates: (o) => store.listScopeStates(o),
+    // #249 第二批：pin 的读写口。这四个都是纯 bookkeeping——它们不动任何记忆行，
+    // 只动 pinned_memories 这张关系表，所以照 setScopeState 那一批的纪律**不挂
+    // write hook**（不 afterSync、不 notifyWrite）：pin 一条不该让 mirror 重渲染，
+    // 也不该把那行记忆的 heat/embedding 重新排队。注入侧只经 store 读本表
+    // （listPinned / listByIdsForInject），写侧只经这里，两处都绕开 memories 主表。
+    pinMemory: (id, opts) => store.pinMemory(id, opts),
+    unpinMemory: (id) => store.unpinMemory(id),
+    listPinned: () => store.listPinned(),
+    countPinned: () => store.countPinned(),
     // 巩固（dream.js）侧的过滤出口。暴露出来而不是让 dream 自己读状态表，是因为
     // 判定只能有一份实现（gateByScope 注释里那条「过滤点漂移」的教训）；dream 侧
     // 的三个读入口各自的附加条件不同（有的排 forgotten、有的不排），但「被按下的
@@ -2792,6 +3019,7 @@ export function createService({ store, mirror, config, onWrite, logger, document
     // 向量出身的两个分组读数：状态端点 /semantic 用它们区分「有向量」和
     // 「可检索」（byModel 按行级 embedding_model，byDimension 按向量维数）。
     // passthrough 形状与 embeddedCount 同款，api 层不直接摸 store。
+    countNeedsEmbeddingFor: (modelHash) => store.countNeedsEmbeddingFor(modelHash),
     embeddingModelBreakdown: () => store.embeddingModelBreakdown(),
     embeddingDimensionBreakdown: () => store.embeddingDimensionBreakdown(),
     // #383：维度探针，供 /context 判「库里有没有一条活跃向量与查询同维」。注意
@@ -2811,6 +3039,8 @@ export function createService({ store, mirror, config, onWrite, logger, document
     list: (o) => store.list(o),
     all: () => store.all(),
     count: (type, opts) => store.count(type, opts),
+    // #597：/list 的 typeCounts——同一份筛选、不带 type 的全库分布（面板分类栏数字源）。
+    countByType: (opts) => store.countByType(opts),
     getById: (id) => store.getById(id),
     remove: (id) => {
       store.remove(id);
@@ -2930,6 +3160,8 @@ export function createService({ store, mirror, config, onWrite, logger, document
     // migrates entity_attrs on merge. Bookkeeping writes like the audit
     // passthroughs above — never write-hook-triggering memory mutations.
     saveRelation: (r) => store.saveRelation(r),
+    // #619：同一条边被后续观察补充证据时回写 metadata（情感相位判重命中）。
+    updateRelationMetadata: (id, metadata) => store.updateRelationMetadata(id, metadata),
     listEntities: (o) => store.listEntities(o),
     countEntities: () => store.countEntities(),
     getRelations: (id) => store.getRelations(id),