@modusensus/dsh-mneme 0.8.14 → 0.8.16

package/src/scope.js

@@ -1,146 +1,146 @@
-// v0.8.0 A1（issue #17）：写入端 scope 解析。
-//
-// 身份模型（issue #17 的核心约定）：session 只是「载体」，记忆挂在持久化身份
-// 标签上——agent_scope = session header 的 agentPreset（跨会话稳定的 agent 模板
-// 身份），workspace_scope = 会话工作目录（registry 反查的 canonical path 优先，
-// header.cwd 兜底）。session_id 永不作为作用域键。
-//
-// 硬约束：解析失败绝不阻塞写入——任何一步取不到就落 NULL（读侧 NULL = 未标注
-// = 全局可见），任何异常都被吞掉（registry 故障 warn 一次后降级）。
-//
-// v0.8.1（issue #170 复核项 2）：scopeEnabled 的闸门从解析器挪到「写标注」处
-// （memory_save 的 auto 分支）。解析器恒返回会话身份（真取不到才是 null）——
-// 读取侧（strictVisibility / memory_get / inject）与显式声明都依赖它：flag 关
-// 只关「自动标注」，不能连读取身份一起关，否则 strictScope 硬墙被静默拆掉
-// （fail-open）。
-
-/**
- * @param {object} deps
- * @param {object} [deps.ctx] 宿主上下文（可能带 workspaceRegistry；旧版 dsh 没有）
- * @param {object} [deps.config] 已解析配置（读 scopeEnabled）
- * @param {object} [deps.logger]
- * @returns {(exec: object) => {agent_scope: string|null, workspace_scope: string|null}|null}
- */
-export function createScopeResolver({ ctx, config, logger } = {}) {
-  let warned = false;
-  const warnOnce = (msg) => {
-    if (warned) return;
-    warned = true;
-    try {
-      logger?.warn?.(msg);
-    } catch {
-      // logger 自身故障同样不能影响写入路径
-    }
-  };
-
-  return function resolveWriteScope(exec) {
-    const session = sessionOf(exec);
-
-    // 持久化 header（issue #17 的身份契约）：session.header 是创建时冻结的
-    // SessionHeader（含 agentPreset/cwd）。⚠️ 不能先读 requestHeader()——那返回
-    // EpochHeader（请求级模型路由头，首个请求后即为真值），会把 session.header
-    // 遮蔽掉，agentPreset/cwd 双双取空（本地 web 复验 2026-09-13 实测踩中）。
-    // 仅当宿主没有 .header 属性时才降级尝试 requestHeader().config（旧形状）。
-    let header = null;
-    try {
-      header = session?.header ?? session?.requestHeader?.()?.config ?? null;
-    } catch {
-      header = null;
-    }
-
-    let agentScope = null;
-    const preset = header?.agentPreset;
-    if (typeof preset === "string" && preset.trim()) agentScope = preset.trim();
-
-    // workspace：registry 反查优先（成员资格 = id 命中 + header canonical cwd
-    // 校验过，path 已 realpath 归一），失败回退 header.cwd，再失败留 NULL。
-    let workspaceScope = null;
-    try {
-      const list = ctx?.workspaceRegistry?.list?.();
-      const sessionId = session?.id;
-      if (Array.isArray(list) && sessionId != null) {
-        const hit = list.find(
-          (ws) => Array.isArray(ws?.sessionIds) && ws.sessionIds.includes(sessionId)
-        );
-        if (typeof hit?.path === "string" && hit.path.trim()) workspaceScope = hit.path.trim();
-      }
-    } catch (e) {
-      warnOnce(
-        `[dsh-mneme] workspaceRegistry lookup failed, falling back to session header cwd: ${String(e)}`
-      );
-    }
-    if (!workspaceScope) {
-      const cwd = header?.cwd;
-      if (typeof cwd === "string" && cwd.trim()) workspaceScope = cwd.trim();
-    }
-
-    return { agent_scope: agentScope, workspace_scope: workspaceScope };
-  };
-}
-
-/**
- * 工具 exec 上的会话对象。宿主 ctx 是 Proxy（cordis 4），裸读未 inject 的属性会
- * 抛错——所以取值恒包在 try 里，取不到返回 null。scope 解析与写入准入的会话键
- * 共用这一处取值口径。
- * @param {object} exec
- * @returns {object|null}
- */
-export function sessionOf(exec) {
-  try {
-    return exec?.agent?.session ?? null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * 写入准入的会话键（#254 G1 会话写入预算的计数单位）。session_id 在这里只作
- * 「同一段对话」的标识，不作为作用域键（见文件头：记忆挂在持久化身份标签上）；
- * 取不到会话身份（系统写入）返回 null = 不进预算。
- * @param {object} exec
- * @returns {string|null}
- */
-export function sessionKeyOf(exec) {
-  // 整个取值（含 .id）都在 try 里：宿主 session 可能是会抛错的 accessor，而这个
-  // 函数在 memory_save 的保存之前被调用——抛出去就是一次工具调用直接失败。
-  try {
-    const id = sessionOf(exec)?.id;
-    return id == null ? null : String(id);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * v0.8.1 底座（issue #170）：显式 scope 参数（memory_save / memory_update /
- * 面板编辑）的归一化。约定：
- *   - 省略（undefined，由调用方判断）= 该维不声明，回落载体自动标注；
- *   - "global"（大小写不敏感）/ "*" / 空白 = 显式声明全局 → 存储 NULL
- *     （行上的 agent_scope_source='explicit' 承担「显式全局」与「从未标注」
- *     的区分，NULL 本身继续表示全局可见）；
- *   - 其余非空 trim 字符串 = 收窄到该标签。
- * 脏输入（非字符串）落 NULL（等同声明全局）——与 resolveWriteScope 的「解析
- * 绝不阻塞写入」同一哲学：显式声明是用户意图，形状不对时宁可放宽不报错。
- *
- * @param {unknown} raw 工具/HTTP 参数原值
- * @returns {string|null} 归一化后的标签值（null=显式全局）
- */
-export function normalizeExplicitScope(raw) {
-  if (typeof raw !== "string") return null;
-  const s = raw.trim();
-  if (!s || s === "*" || s.toLowerCase() === "global") return null;
-  return s;
-}
-
-/**
- * scope 标注的比较键（去重键/检索加权/跨 scope 配对共用口径）：非空 trim 字符串
- * 原样返回，其余（NULL/undefined/空串/非字符串）统一为 null（「未标注」）。
- * v0.8.1（issue #170 第 2 步）从 service.js 上提为共享定义——sleep 的跨 scope
- * 候选配对必须与去重键用同一把钥匙，NULL 与已标注才不会错配。
- *
- * @param {unknown} v scope 标注原值
- * @returns {string|null} 比较键（null=未标注）
- */
-export function scopeKeyOf(v) {
-  return typeof v === "string" && v.trim() ? v.trim() : null;
-}
+// v0.8.0 A1（issue #17）：写入端 scope 解析。
+//
+// 身份模型（issue #17 的核心约定）：session 只是「载体」，记忆挂在持久化身份
+// 标签上——agent_scope = session header 的 agentPreset（跨会话稳定的 agent 模板
+// 身份），workspace_scope = 会话工作目录（registry 反查的 canonical path 优先，
+// header.cwd 兜底）。session_id 永不作为作用域键。
+//
+// 硬约束：解析失败绝不阻塞写入——任何一步取不到就落 NULL（读侧 NULL = 未标注
+// = 全局可见），任何异常都被吞掉（registry 故障 warn 一次后降级）。
+//
+// v0.8.1（issue #170 复核项 2）：scopeEnabled 的闸门从解析器挪到「写标注」处
+// （memory_save 的 auto 分支）。解析器恒返回会话身份（真取不到才是 null）——
+// 读取侧（strictVisibility / memory_get / inject）与显式声明都依赖它：flag 关
+// 只关「自动标注」，不能连读取身份一起关，否则 strictScope 硬墙被静默拆掉
+// （fail-open）。
+
+/**
+ * @param {object} deps
+ * @param {object} [deps.ctx] 宿主上下文（可能带 workspaceRegistry；旧版 dsh 没有）
+ * @param {object} [deps.config] 已解析配置（读 scopeEnabled）
+ * @param {object} [deps.logger]
+ * @returns {(exec: object) => {agent_scope: string|null, workspace_scope: string|null}|null}
+ */
+export function createScopeResolver({ ctx, config, logger } = {}) {
+  let warned = false;
+  const warnOnce = (msg) => {
+    if (warned) return;
+    warned = true;
+    try {
+      logger?.warn?.(msg);
+    } catch {
+      // logger 自身故障同样不能影响写入路径
+    }
+  };
+
+  return function resolveWriteScope(exec) {
+    const session = sessionOf(exec);
+
+    // 持久化 header（issue #17 的身份契约）：session.header 是创建时冻结的
+    // SessionHeader（含 agentPreset/cwd）。⚠️ 不能先读 requestHeader()——那返回
+    // EpochHeader（请求级模型路由头，首个请求后即为真值），会把 session.header
+    // 遮蔽掉，agentPreset/cwd 双双取空（本地 web 复验 2026-09-13 实测踩中）。
+    // 仅当宿主没有 .header 属性时才降级尝试 requestHeader().config（旧形状）。
+    let header = null;
+    try {
+      header = session?.header ?? session?.requestHeader?.()?.config ?? null;
+    } catch {
+      header = null;
+    }
+
+    let agentScope = null;
+    const preset = header?.agentPreset;
+    if (typeof preset === "string" && preset.trim()) agentScope = preset.trim();
+
+    // workspace：registry 反查优先（成员资格 = id 命中 + header canonical cwd
+    // 校验过，path 已 realpath 归一），失败回退 header.cwd，再失败留 NULL。
+    let workspaceScope = null;
+    try {
+      const list = ctx?.workspaceRegistry?.list?.();
+      const sessionId = session?.id;
+      if (Array.isArray(list) && sessionId != null) {
+        const hit = list.find(
+          (ws) => Array.isArray(ws?.sessionIds) && ws.sessionIds.includes(sessionId)
+        );
+        if (typeof hit?.path === "string" && hit.path.trim()) workspaceScope = hit.path.trim();
+      }
+    } catch (e) {
+      warnOnce(
+        `[dsh-mneme] workspaceRegistry lookup failed, falling back to session header cwd: ${String(e)}`
+      );
+    }
+    if (!workspaceScope) {
+      const cwd = header?.cwd;
+      if (typeof cwd === "string" && cwd.trim()) workspaceScope = cwd.trim();
+    }
+
+    return { agent_scope: agentScope, workspace_scope: workspaceScope };
+  };
+}
+
+/**
+ * 工具 exec 上的会话对象。宿主 ctx 是 Proxy（cordis 4），裸读未 inject 的属性会
+ * 抛错——所以取值恒包在 try 里，取不到返回 null。scope 解析与写入准入的会话键
+ * 共用这一处取值口径。
+ * @param {object} exec
+ * @returns {object|null}
+ */
+export function sessionOf(exec) {
+  try {
+    return exec?.agent?.session ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 写入准入的会话键（#254 G1 会话写入预算的计数单位）。session_id 在这里只作
+ * 「同一段对话」的标识，不作为作用域键（见文件头：记忆挂在持久化身份标签上）；
+ * 取不到会话身份（系统写入）返回 null = 不进预算。
+ * @param {object} exec
+ * @returns {string|null}
+ */
+export function sessionKeyOf(exec) {
+  // 整个取值（含 .id）都在 try 里：宿主 session 可能是会抛错的 accessor，而这个
+  // 函数在 memory_save 的保存之前被调用——抛出去就是一次工具调用直接失败。
+  try {
+    const id = sessionOf(exec)?.id;
+    return id == null ? null : String(id);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * v0.8.1 底座（issue #170）：显式 scope 参数（memory_save / memory_update /
+ * 面板编辑）的归一化。约定：
+ *   - 省略（undefined，由调用方判断）= 该维不声明，回落载体自动标注；
+ *   - "global"（大小写不敏感）/ "*" / 空白 = 显式声明全局 → 存储 NULL
+ *     （行上的 agent_scope_source='explicit' 承担「显式全局」与「从未标注」
+ *     的区分，NULL 本身继续表示全局可见）；
+ *   - 其余非空 trim 字符串 = 收窄到该标签。
+ * 脏输入（非字符串）落 NULL（等同声明全局）——与 resolveWriteScope 的「解析
+ * 绝不阻塞写入」同一哲学：显式声明是用户意图，形状不对时宁可放宽不报错。
+ *
+ * @param {unknown} raw 工具/HTTP 参数原值
+ * @returns {string|null} 归一化后的标签值（null=显式全局）
+ */
+export function normalizeExplicitScope(raw) {
+  if (typeof raw !== "string") return null;
+  const s = raw.trim();
+  if (!s || s === "*" || s.toLowerCase() === "global") return null;
+  return s;
+}
+
+/**
+ * scope 标注的比较键（去重键/检索加权/跨 scope 配对共用口径）：非空 trim 字符串
+ * 原样返回，其余（NULL/undefined/空串/非字符串）统一为 null（「未标注」）。
+ * v0.8.1（issue #170 第 2 步）从 service.js 上提为共享定义——sleep 的跨 scope
+ * 候选配对必须与去重键用同一把钥匙，NULL 与已标注才不会错配。
+ *
+ * @param {unknown} v scope 标注原值
+ * @returns {string|null} 比较键（null=未标注）
+ */
+export function scopeKeyOf(v) {
+  return typeof v === "string" && v.trim() ? v.trim() : null;
+}

package/src/search/adaptive.js

@@ -1,60 +1,60 @@
-// Adaptive vector threshold (v0.5.0 召回率优化 1.2): replaces the fixed
-// vectorSearchThreshold=0.65 with a query-aware cutoff.
-//   entity:/attr: prefixes → 0.5  (entity recall is name-driven; loosen)
-//   very short queries      → 0.7  (<5 chars match almost anything; tighten)
-//   very long queries       → 0.6  (semantically specific; loosen a little)
-//   head-gap rule           → when the top-1 vs top-5 candidate gap exceeds
-//                             0.3 the head is decisive — loosen to 0.5 so
-//                             the tail still reaches the reranker
-//   otherwise               → 0.65 (the legacy default)
-// Pure and total: same inputs, same cutoff, no store access.
-export function adaptiveThreshold(query, candidates = []) {
-  const q = String(query ?? "");
-  if (q.startsWith("entity:") || q.startsWith("attr:")) return 0.5;
-  if (q.length > 0 && q.length < 5) return 0.7;
-  if (q.length > 50) return 0.6;
-  const scores = (Array.isArray(candidates) ? candidates : [])
-    .map((c) => (typeof c?._score === "number" ? c._score : typeof c?.score === "number" ? c.score : 0))
-    .filter((s) => s > 0)
-    .sort((a, b) => b - a);
-  if (scores.length >= 5 && scores[0] - scores[4] > 0.3) return 0.5;
-  return 0.65;
-}
-
-// Issue #239（第 5 项）：注入条数的查询自适应（去 always-on 化的一半）。
-// 依据：不确定性强的话题多召回、确定性的少召回（Oblivion 的不确定性驱动读路径）；
-// 但**注入相关却带偏生成**的内容可能比不注入更糟（2607.24010 与 2604.02280 两处
-// 独立出处），所以这里只做**单向收缩**：模糊 → 维持用户配置的上限，确定 → 收缩，
-// 绝不越过上限。判据只看查询本身——不做额外检索（2607.24010：触发侧成本别忽略，
-// 先探针检索等于白付一次 fuseRecall）。
-const RECALL_CUES = [
-  // 中文回指 / 时间线索：出现即说明用户要的是「记忆里的东西」，当场算不出来
-  "上次", "之前", "以前", "那天", "那次", "刚才", "刚刚", "后来", "很早",
-  "还记得", "记不记得", "我们讨论", "我们聊", "我说过", "你提过", "提到过",
-  "最近", "上次说", "之前说",
-  // 英文同类线索
-  "last time", "previously", "earlier", "remember", "we discussed",
-  "i mentioned", "you said", "that thing", "remind me"
-];
-
-/**
- * 这段查询是否需要「宽召回」。命中回指/时间线索，或短到几乎匹配任何东西
- * （与 adaptiveThreshold 对 <5 字符的判断同源）。纯函数、零成本。
- * 拿不到查询时不猜——返回 true 维持现状。
- */
-export function needsBroadRecall(query) {
-  const q = String(query ?? "").trim().toLowerCase();
-  if (q === "") return true;
-  if (q.length < 5) return true;
-  return RECALL_CUES.some((cue) => q.includes(cue));
-}
-
-/**
- * 注入条数的自适应预算：模糊 → 维持配置上限；确定 → 收缩到一半（下限 1）。
- * `maxItems <= 1` 时原样返回（含 0 = 不注入，flag 打开也不该把 0 变成 1）。
- */
-export function adaptiveInjectBudget(query, maxItems) {
-  const cap = Number.isFinite(maxItems) && maxItems > 0 ? Math.floor(maxItems) : maxItems;
-  if (!Number.isFinite(cap) || cap <= 1) return cap;
-  return needsBroadRecall(query) ? cap : Math.max(1, Math.ceil(cap / 2));
-}
+// Adaptive vector threshold (v0.5.0 召回率优化 1.2): replaces the fixed
+// vectorSearchThreshold=0.65 with a query-aware cutoff.
+//   entity:/attr: prefixes → 0.5  (entity recall is name-driven; loosen)
+//   very short queries      → 0.7  (<5 chars match almost anything; tighten)
+//   very long queries       → 0.6  (semantically specific; loosen a little)
+//   head-gap rule           → when the top-1 vs top-5 candidate gap exceeds
+//                             0.3 the head is decisive — loosen to 0.5 so
+//                             the tail still reaches the reranker
+//   otherwise               → 0.65 (the legacy default)
+// Pure and total: same inputs, same cutoff, no store access.
+export function adaptiveThreshold(query, candidates = []) {
+  const q = String(query ?? "");
+  if (q.startsWith("entity:") || q.startsWith("attr:")) return 0.5;
+  if (q.length > 0 && q.length < 5) return 0.7;
+  if (q.length > 50) return 0.6;
+  const scores = (Array.isArray(candidates) ? candidates : [])
+    .map((c) => (typeof c?._score === "number" ? c._score : typeof c?.score === "number" ? c.score : 0))
+    .filter((s) => s > 0)
+    .sort((a, b) => b - a);
+  if (scores.length >= 5 && scores[0] - scores[4] > 0.3) return 0.5;
+  return 0.65;
+}
+
+// Issue #239（第 5 项）：注入条数的查询自适应（去 always-on 化的一半）。
+// 依据：不确定性强的话题多召回、确定性的少召回（Oblivion 的不确定性驱动读路径）；
+// 但**注入相关却带偏生成**的内容可能比不注入更糟（2607.24010 与 2604.02280 两处
+// 独立出处），所以这里只做**单向收缩**：模糊 → 维持用户配置的上限，确定 → 收缩，
+// 绝不越过上限。判据只看查询本身——不做额外检索（2607.24010：触发侧成本别忽略，
+// 先探针检索等于白付一次 fuseRecall）。
+const RECALL_CUES = [
+  // 中文回指 / 时间线索：出现即说明用户要的是「记忆里的东西」，当场算不出来
+  "上次", "之前", "以前", "那天", "那次", "刚才", "刚刚", "后来", "很早",
+  "还记得", "记不记得", "我们讨论", "我们聊", "我说过", "你提过", "提到过",
+  "最近", "上次说", "之前说",
+  // 英文同类线索
+  "last time", "previously", "earlier", "remember", "we discussed",
+  "i mentioned", "you said", "that thing", "remind me"
+];
+
+/**
+ * 这段查询是否需要「宽召回」。命中回指/时间线索，或短到几乎匹配任何东西
+ * （与 adaptiveThreshold 对 <5 字符的判断同源）。纯函数、零成本。
+ * 拿不到查询时不猜——返回 true 维持现状。
+ */
+export function needsBroadRecall(query) {
+  const q = String(query ?? "").trim().toLowerCase();
+  if (q === "") return true;
+  if (q.length < 5) return true;
+  return RECALL_CUES.some((cue) => q.includes(cue));
+}
+
+/**
+ * 注入条数的自适应预算：模糊 → 维持配置上限；确定 → 收缩到一半（下限 1）。
+ * `maxItems <= 1` 时原样返回（含 0 = 不注入，flag 打开也不该把 0 变成 1）。
+ */
+export function adaptiveInjectBudget(query, maxItems) {
+  const cap = Number.isFinite(maxItems) && maxItems > 0 ? Math.floor(maxItems) : maxItems;
+  if (!Number.isFinite(cap) || cap <= 1) return cap;
+  return needsBroadRecall(query) ? cap : Math.max(1, Math.ceil(cap / 2));
+}

package/src/search/bm25.js

@@ -1,96 +1,96 @@
-// BM25 sparse retrieval (v0.5.0 召回率优化 1.1): the third recall path beside
-// vector search and the LIKE keyword scan. The LIKE path only matches full
-// substrings, so a multi-term query ("rust 异步 tokio") misses rows whose
-// terms are scattered. BM25 scores per-token overlap with IDF weighting,
-// which is exactly the gap: identifiers, code fragments and mixed CJK/ASCII
-// queries recall rows the substring scan cannot see.
-
-// Tokenizer: ASCII words keep their shape (identifiers like "dsh-mneme" or
-// "ZFS_4421" survive as whole tokens); CJK runs become sliding bigrams
-// (unigram only for single characters), the standard workaround for BM25's
-// whitespace tokenization on Chinese.
-export function tokenize(text) {
-  const raw = String(text ?? "").toLowerCase();
-  const tokens = [];
-  const ascii = raw.match(/[a-z0-9_]+/g) ?? [];
-  tokens.push(...ascii);
-  const cjkRuns = raw.match(/[\u4e00-\u9fff]+/g) ?? [];
-  for (const run of cjkRuns) {
-    if (run.length === 1) { tokens.push(run); continue; }
-    for (let i = 0; i < run.length - 1; i++) tokens.push(run.slice(i, i + 2));
-  }
-  return tokens;
-}
-
-const K1 = 1.5; // term-frequency saturation
-const B = 0.75;  // length normalization
-
-/**
- * Build a BM25 index over documents: [{id, title, content}].
- * Returns { score, search }:
- *   score(query, doc) — per-spec ad-hoc scoring (re-tokenizes the doc)
- *   search(query, {limit}) — precomputed-tf ranking, scores normalized to
- *     [0,1] by the max so BM25 hits can weight-blend with vector/keyword
- *     scores on one scale. Rows the query does not touch at all are dropped.
- */
-export function createBM25Index(documents) {
-  const docs = Array.isArray(documents) ? documents.filter(Boolean) : [];
-  const N = docs.length;
-  const df = new Map();
-  const prepared = docs.map((doc) => {
-    const tokens = tokenize(`${doc.title ?? ""} ${doc.content ?? ""}`);
-    const tf = new Map();
-    for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1);
-    for (const t of tf.keys()) df.set(t, (df.get(t) ?? 0) + 1);
-    return { doc, tf, len: tokens.length };
-  });
-  const avgLen = N ? prepared.reduce((s, p) => s + p.len, 0) / N : 0 || 1;
-
-  const idf = (t) => {
-    const n = df.get(t) ?? 0;
-    return Math.log((N - n + 0.5) / (n + 0.5) + 1);
-  };
-
-  function scorePrepared(queryTokens, p) {
-    let score = 0;
-    for (const t of queryTokens) {
-      const f = p.tf.get(t);
-      if (!f) continue;
-      const norm = p.len ? K1 * (1 - B + B * (p.len / avgLen)) : K1;
-      score += idf(t) * ((f * (K1 + 1)) / (f + norm));
-    }
-    return score;
-  }
-
-  return {
-    score(query, doc) {
-      const tokens = tokenize(`${doc?.title ?? ""} ${doc?.content ?? ""}`);
-      const tf = new Map();
-      for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1);
-      const len = tokens.length;
-      // Ad-hoc scoring can't see corpus df; fall back to tf-only saturation
-      // (df is approximated as 1 so idf ≈ log(N - 0.5 + 1) is constant).
-      let score = 0;
-      for (const t of tokenize(query)) {
-        const f = tf.get(t);
-        if (!f) continue;
-        const norm = len ? K1 * (1 - B + B * (len / avgLen)) : K1;
-        score += idf(t) * ((f * (K1 + 1)) / (f + norm));
-      }
-      return score;
-    },
-    search(query, { limit = 20 } = {}) {
-      const qTokens = tokenize(query);
-      if (!qTokens.length || !N) return [];
-      const scored = [];
-      for (const p of prepared) {
-        const s = scorePrepared(qTokens, p);
-        if (s > 0) scored.push({ row: p.doc, raw: s });
-      }
-      scored.sort((a, b) => b.raw - a.raw);
-      const top = scored.slice(0, limit);
-      const max = top[0]?.raw || 1;
-      return top.map(({ row, raw }) => ({ ...row, score: max ? raw / max : 0 }));
-    }
-  };
-}
+// BM25 sparse retrieval (v0.5.0 召回率优化 1.1): the third recall path beside
+// vector search and the LIKE keyword scan. The LIKE path only matches full
+// substrings, so a multi-term query ("rust 异步 tokio") misses rows whose
+// terms are scattered. BM25 scores per-token overlap with IDF weighting,
+// which is exactly the gap: identifiers, code fragments and mixed CJK/ASCII
+// queries recall rows the substring scan cannot see.
+
+// Tokenizer: ASCII words keep their shape (identifiers like "dsh-mneme" or
+// "ZFS_4421" survive as whole tokens); CJK runs become sliding bigrams
+// (unigram only for single characters), the standard workaround for BM25's
+// whitespace tokenization on Chinese.
+export function tokenize(text) {
+  const raw = String(text ?? "").toLowerCase();
+  const tokens = [];
+  const ascii = raw.match(/[a-z0-9_]+/g) ?? [];
+  tokens.push(...ascii);
+  const cjkRuns = raw.match(/[\u4e00-\u9fff]+/g) ?? [];
+  for (const run of cjkRuns) {
+    if (run.length === 1) { tokens.push(run); continue; }
+    for (let i = 0; i < run.length - 1; i++) tokens.push(run.slice(i, i + 2));
+  }
+  return tokens;
+}
+
+const K1 = 1.5; // term-frequency saturation
+const B = 0.75;  // length normalization
+
+/**
+ * Build a BM25 index over documents: [{id, title, content}].
+ * Returns { score, search }:
+ *   score(query, doc) — per-spec ad-hoc scoring (re-tokenizes the doc)
+ *   search(query, {limit}) — precomputed-tf ranking, scores normalized to
+ *     [0,1] by the max so BM25 hits can weight-blend with vector/keyword
+ *     scores on one scale. Rows the query does not touch at all are dropped.
+ */
+export function createBM25Index(documents) {
+  const docs = Array.isArray(documents) ? documents.filter(Boolean) : [];
+  const N = docs.length;
+  const df = new Map();
+  const prepared = docs.map((doc) => {
+    const tokens = tokenize(`${doc.title ?? ""} ${doc.content ?? ""}`);
+    const tf = new Map();
+    for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1);
+    for (const t of tf.keys()) df.set(t, (df.get(t) ?? 0) + 1);
+    return { doc, tf, len: tokens.length };
+  });
+  const avgLen = N ? prepared.reduce((s, p) => s + p.len, 0) / N : 0 || 1;
+
+  const idf = (t) => {
+    const n = df.get(t) ?? 0;
+    return Math.log((N - n + 0.5) / (n + 0.5) + 1);
+  };
+
+  function scorePrepared(queryTokens, p) {
+    let score = 0;
+    for (const t of queryTokens) {
+      const f = p.tf.get(t);
+      if (!f) continue;
+      const norm = p.len ? K1 * (1 - B + B * (p.len / avgLen)) : K1;
+      score += idf(t) * ((f * (K1 + 1)) / (f + norm));
+    }
+    return score;
+  }
+
+  return {
+    score(query, doc) {
+      const tokens = tokenize(`${doc?.title ?? ""} ${doc?.content ?? ""}`);
+      const tf = new Map();
+      for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1);
+      const len = tokens.length;
+      // Ad-hoc scoring can't see corpus df; fall back to tf-only saturation
+      // (df is approximated as 1 so idf ≈ log(N - 0.5 + 1) is constant).
+      let score = 0;
+      for (const t of tokenize(query)) {
+        const f = tf.get(t);
+        if (!f) continue;
+        const norm = len ? K1 * (1 - B + B * (len / avgLen)) : K1;
+        score += idf(t) * ((f * (K1 + 1)) / (f + norm));
+      }
+      return score;
+    },
+    search(query, { limit = 20 } = {}) {
+      const qTokens = tokenize(query);
+      if (!qTokens.length || !N) return [];
+      const scored = [];
+      for (const p of prepared) {
+        const s = scorePrepared(qTokens, p);
+        if (s > 0) scored.push({ row: p.doc, raw: s });
+      }
+      scored.sort((a, b) => b.raw - a.raw);
+      const top = scored.slice(0, limit);
+      const max = top[0]?.raw || 1;
+      return top.map(({ row, raw }) => ({ ...row, score: max ? raw / max : 0 }));
+    }
+  };
+}