@modusensus/dsh-mneme 0.12.0 → 0.14.0-beta.1

package/lib/service.js

@@ -7,10 +7,11 @@ 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";
-import { applyDecisions } from "./dream/decisions.js";
+import { applyDecisions, EPISTEMIC_PRIORITY } from "./dream/decisions.js";
 import { createDocumentRegistrar } from "./document.js";
 import { createOrganizer } from "./organize.js";
 import { createShareImport } from "./share-import.js";
@@ -532,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
@@ -541,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 +
@@ -789,7 +835,7 @@ export function createService({ store, mirror, config, onWrite, logger, document
    * Returns { merged, signals }, where signals is Map<id, {keyword, vector,
    * bm25}> so searchMemories can decorate rows when signalTransparency is on.
    */
-  function fuseRecall({ keyword, vector, bm25, entity, lim, mode, wv, wk, wb, we }) {
+  function fuseRecall({ keyword, vector, bm25, entity, lim, mode, wv, wk, wb, we, supersededIds = null }) {
     const recipe = config?.recallFusion ?? "blend";
 
     // Per-source scores are recorded for every recipe so signalTransparency
@@ -922,17 +968,28 @@ 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 排序就是它们各自算出来的排序。
+
+    // #641（T3 取代链的检索侧，beta 第三阶段）：已被取代的行整体降权后重排——
+    // 它仍是「曾经为真」的可追溯历史，显式搜索照样能找到，但不该与取代它的
+    // 那行竞争注入名次。乘 0.5 的语义是「同卷必排继任者之后」，不是隐藏；
+    // 取代链只会在 enforce 档下落笔，链没落过时本段与从前逐字节一致。
+    // keyword 短路在前面已 return——那是人的显式检索动作，保留完整可见性与
+    // 原始排序。已知边界：各分支已按 lim 截断，这里只重排不再回填——极端
+    // 情况下一个刚挤进末位的被取代行会占住名额，但它被压到继任者之后，按
+    // 名次消费的注入实际效果等价；把降权挪进各分支截断前是显式重构，等
+    // 召回基准跑过一轮再决定值不值。行形状随来源不一（向量源可能是瘦行），
+    // 所以按 id 集合判定而不是读行上的 superseded_by。
+    if (supersededIds?.size) {
+      merged = merged
+        .map((m) => (supersededIds.has(m.id) ? { ...m, score: (m.score ?? 0) * 0.5 } : m))
+        .sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
     }
 
     return { merged, signals };
@@ -1049,7 +1106,9 @@ export function createService({ store, mirror, config, onWrite, logger, document
     const wv = config?.hybridSearchVectorWeight ?? DEFAULT_HYBRID_WEIGHTS.vector;
     const wk = config?.hybridSearchKeywordWeight ?? DEFAULT_HYBRID_WEIGHTS.keyword;
 
-    const { merged: fusedMerged, signals } = fuseRecall({ keyword, vector, bm25, entity, lim, mode, wv, wk, wb, we: wb });
+    // T3 降权的判定集：一次部分索引查询拿全部已取代行 id（通常为空或个位数）。
+    const supersededIds = new Set(store.supersededIds());
+    const { merged: fusedMerged, signals } = fuseRecall({ keyword, vector, bm25, entity, lim, mode, wv, wk, wb, we: wb, supersededIds });
     let merged = fusedMerged;
     // v0.8.0 A3（issue #17）：strictScope 硬过滤——他 scope 的候选直接出局
     // （区别于 A2 的降权保留可见）；未标注行与命中行保留。strict 与 A2 加权
@@ -1778,62 +1837,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);
-        }
+        for (const m of lastSemanticRecall.items) if (passesGate(m)) vectorHits.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));
-        }
-      }
-      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) => {
@@ -1841,7 +1898,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;
         }
@@ -1927,16 +1984,29 @@ export function createService({ store, mirror, config, onWrite, logger, document
     // 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));
         }
@@ -2045,7 +2115,49 @@ export function createService({ store, mirror, config, onWrite, logger, document
     }
     // #249 第一批：pin 前置到块内相关性排序之前（验收项），且不占 maxItems 名额。
     // pinned 为空时 selected 就是 general 本身——关闭态与改动前逐字节一致。
-    const selected = pinned.length > 0 ? [...pinned, ...general] : general;
+    let selected = pinned.length > 0 ? [...pinned, ...general] : general;
+    // Issue #641（T3/T4 注入侧，beta 第三阶段）：取代链行不进注入——继任者携带
+    // 现状，旧值注入只会浪费名额、冒着被采用的风险（supersedeChain 只由 enforce
+    // 落笔，shadow/关闭态下集合恒空，本过滤与从前逐字节一致）。矛盾对（tier=
+    // conflict 且仍 open）同批时按「可信度 → 新者」排位并互相标注：#537 的教训
+    // 是标注必须把区分信息带进注入文本，否则重演「记账了但没用上」；标注再显式
+    // 门控在 enforce 档——shadow 只记账零处置。
+    const supersededIdSet = new Set(store.supersededIds());
+    if (supersededIdSet.size) {
+      selected = selected.filter((m) => !supersededIdSet.has(m.id));
+    }
+    if (config.conflictLedgerMode === "enforce" && selected.length > 1) {
+      const language = langOf(config);
+      const byId = new Map(selected.map((m) => [m.id, m]));
+      for (const p of store.openConflictPairs()) {
+        const ma = byId.get(p.memory_a);
+        const mb = byId.get(p.memory_b);
+        if (!ma || !mb) continue;
+        // 确定性排位：可信度（observation > inferred > subjective，与
+        // applyConflict 的换位同序）优先，平手退回服务器时钟新者。多对并存时
+        // 逐一交换以相对次序为准——矛盾对是稀有事件，交换足够且可预测。
+        const rank = (m) => EPISTEMIC_PRIORITY[m.epistemic_status] ?? 0;
+        let preferred = ma;
+        let other = mb;
+        const ra = rank(ma);
+        const rb = rank(mb);
+        if (ra !== rb) {
+          if (rb > ra) { preferred = mb; other = ma; }
+        } else if ((mb.created_at ?? "") > (ma.created_at ?? "")) {
+          preferred = mb;
+          other = ma;
+        }
+        const detected = String(p.detected ?? "").slice(0, 10);
+        preferred.conflictNote = STR.conflictPairPreferred[language](String(other.title ?? "").slice(0, 24), detected);
+        other.conflictNote = STR.conflictPairSecondary[language](String(preferred.title ?? "").slice(0, 24), detected);
+        const pi = selected.indexOf(preferred);
+        const oi = selected.indexOf(other);
+        if (pi > oi) {
+          selected.splice(pi, 1);
+          selected.splice(oi, 0, preferred);
+        }
+      }
+    }
     if (pinnedStats) {
       // 「未展示」只数**真的没进块**的 pin 类条目：被 pin 预算挤下来的条目会回到
       // 候选池，仍可能被 general 槽选中——那就是展示了。按 eligible - pinned 直接
@@ -2260,6 +2372,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)
@@ -2612,6 +2728,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 = {}) {
@@ -2765,6 +2946,7 @@ export function createService({ store, mirror, config, onWrite, logger, document
     organize,
     recoverMirror,
     getMirrorHealth,
+    getCapacityHealth,
     getMirrorState: () => store.getMirrorState(),
     injectCandidates,
     mergeHumanEdits,
@@ -2897,6 +3079,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 判「库里有没有一条活跃向量与查询同维」。注意
@@ -2916,6 +3099,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);
@@ -3013,6 +3198,17 @@ export function createService({ store, mirror, config, onWrite, logger, document
     saveConflictReviewed: (r) => store.saveConflictReviewed(r),
     loadConflictReviewed: () => store.loadConflictReviewed(),
     listConflictReviewed: (opts) => store.listConflictReviewed(opts),
+    // #641：冲突分诊账本。与上面 conflict_reviewed 同一条 bookkeeping 纪律——纯
+    // 测量记录，写它绝不触发 write hooks，否则 shadow 档的每轮记账都会把睡眠
+    // 调度器叫醒。
+    saveConflictLedgerEntry: (r) => store.saveConflictLedgerEntry(r),
+    setConflictLedgerStatus: (a, b, s) => store.setConflictLedgerStatus(a, b, s),
+    listConflictLedger: (opts) => store.listConflictLedger(opts),
+    countConflictLedger: (opts) => store.countConflictLedger(opts),
+    // #641 T3 取代链：与上面 ledger 同一条 bookkeeping 纪律——纯元数据标注绝不
+    // 触发 write hooks（正文零变化，镜像无 diff；bump updated_at 会污染
+    // 「这一对刚判过」的宽松代理判定）。
+    supersedeChain: (loserId, winnerId) => store.supersedeChain(loserId, winnerId),
     // Recall evaluation trail (方案 B): audit-bookkeeping semantics like the
     // dream/recall passthroughs above — a recall_evals write is a snapshot, not
     // a memory mutation, so it never triggers write hooks.
@@ -3035,9 +3231,12 @@ 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),
+    relationsByType: (type, limit) => store.relationsByType(type, limit),
     // #24 块4 被动确认的复核出口：列出权重被 bump 抬过的边（gain = 现权 −
     // 该 source 的初值）。纯读，不动权重——「看哪些边被用出来过」是人的动作。
     listBoostedRelations: (o) => store.listBoostedRelations(o),