sage-mem 1.6.3 → 1.6.5

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `1.6.3`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
+**Current release: `1.6.5`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
 [frozen contract](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md).
 
 If it is useful to you, a Star is the most direct feedback.
@@ -482,7 +482,7 @@ Version-by-version compatibility record:
 | 0.2.0-rc.2 | compatible |
 | 0.2.1-rc.1 | compatible |
 
-**How to read `compatible`.** It means this plugin's codec and manifest contract has been checked against that host generation (code-level comparison plus the unit/contract suite), **not** that an end-to-end probe was run on that exact host build. The table is a declaration; how each claim was checked is summarized here. Real-host probes so far: `headless` (2026-10-15) and `web` (2026-10-16); the `desktop` profile has **not** been probed yet (see [release-checklist.md](https://github.com/gezi-wen/sage-mem/blob/main/docs/release-checklist.md) §4b). CI runs only on Ubuntu + Node 24 against the `0.2.0-rc.1` peer generation; `engines.node` still declares `>=18`, but Node 18 is not part of the CI matrix.
+**How to read `compatible`.** It means this plugin's codec and manifest contract has been checked against that host generation (code-level comparison plus the unit/contract suite), **not** that an end-to-end probe was run on that exact host build. The table is a declaration; how each claim was checked is summarized here. Real-host probes so far: `headless` (2026-10-15) and `web` (2026-10-16); the `desktop` profile has **not** been probed yet (see [release-checklist.md](https://github.com/gezi-wen/sage-mem/blob/main/docs/release-checklist.md) §4b). CI runs on Ubuntu against **Node 18.x / 20.x / 24.x** with the `0.2.0-rc.1` peer generation; macOS and Windows are not CI-covered, and there is no desktop-host probe yet.
 
 Two points worth spelling out:
 

package/README.zh.md

@@ -14,7 +14,7 @@
 
 > File-based cross-session memory for DeepSeek Harness — every memory is a plain markdown file you can open, edit and delete. No database, no worker, no port.
 
-**当前发布版本：`1.6.3`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`1.6.5`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。
@@ -484,7 +484,7 @@ sage-mem 是纯 DSH 插件，用 `package.json` 的 **`engines.dsh`** 声明宿
 | 0.2.0-rc.2 | compatible |
 | 0.2.1-rc.1 | compatible |
 
-**`compatible` 怎么读**：它表示本插件的 codec / manifest 契约在该宿主代上核对过（代码层比对 + 单元/契约测试），**不表示**在那个确切宿主构建上跑过端到端探针。这张表是声明，核对方式总结在下面。真实宿主探针目前只跑过 `headless`（2026-10-15）与 `web`（2026-10-16）；`desktop` profile **还没跑过**（见 [release-checklist.md](https://github.com/gezi-wen/sage-mem/blob/main/docs/release-checklist.md) §4b）。CI 只在 Ubuntu + Node 24 上、对着 `0.2.0-rc.1` 一代 peer 跑；`engines.node` 仍声明 `>=18`，但 Node 18 不在 CI 矩阵里。
+**`compatible` 怎么读**：它表示本插件的 codec / manifest 契约在该宿主代上核对过（代码层比对 + 单元/契约测试），**不表示**在那个确切宿主构建上跑过端到端探针。这张表是声明，核对方式总结在下面。真实宿主探针目前只跑过 `headless`（2026-10-15）与 `web`（2026-10-16）；`desktop` profile **还没跑过**（见 [release-checklist.md](https://github.com/gezi-wen/sage-mem/blob/main/docs/release-checklist.md) §4b）。CI 在 Ubuntu 上覆盖 **Node 18.x / 20.x / 24.x**，peer 钉 `0.2.0-rc.1` 一代；macOS 与 Windows 没有 CI 覆盖，desktop 宿主探针也还没有。
 
 两点值得说明：
 

package/lib/memory/bm25.js

@@ -97,6 +97,28 @@ export function scoreDoc(queryTerms, tf, dl, stats) {
   return score
 }
 
+/**
+ * 与 `scoreDoc` 同一口径的**逐词元贡献**。用于诊断报告：
+ * 「这条命中凭什么得分」不能只给一个总分，要能看到是哪个词元贡献了多少。
+ *
+ * 返回数组（按 queryTerms 顺序，只含真的命中的词元）；各项 `score` 之和**严格等于**
+ * `scoreDoc` —— 两边共用同一个公式，`scoreDoc` 就是它的求和，不存在第二份实现。
+ *
+ * @returns {Array<{term:string, tf:number, idf:number, score:number}>}
+ */
+export function scoreDocBreakdown(queryTerms, tf, dl, stats) {
+  if (!stats || stats.N === 0) return []
+  const out = []
+  for (const t of queryTerms) {
+    const f = tf.get(t)
+    if (!f) continue
+    const idf = idfOf(stats.df.get(t) ?? 0, stats.N)
+    const score = (idf * (f * (BM25_K1 + 1))) / (f + BM25_K1 * (1 - BM25_B + (BM25_B * dl) / stats.avgdl))
+    out.push({ term: t, tf: f, idf, score })
+  }
+  return out
+}
+
 /**
  * 词元的逆文档频率。加 1 的对数形式：df 等于 N 时（到处都是的词元）趋近 0 而不为负。
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sage-mem",
   "description": "Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.",
-  "version": "1.6.3",
+  "version": "1.6.5",
   "type": "module",
   "main": "lib/index.js",
   "exports": {