@modusensus/dsh-mneme 0.8.3 → 0.8.5

package/test/reranker-single-logit.test.js

@@ -1,73 +1,73 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { LocalReranker } from "../src/reranker.js";
-
-// 回归（issue #188）：Xenova/bge-reranker-base 是单 logit 交叉编码器——每个
-// (query, passage) 对只输出 1 个 logit。tc 策略此前在 cols===1 时把 l1 退化成
-// l0，sigmoid(l0 - l1) = sigmoid(0) = 0.5：所有候选分数恒为常量，重排静默失效
-// （不抛错、日志照常 ready、语义状态照常 reranker="ready"，只有分数是死的）。
-// 单 logit 头的正类概率是 sigmoid(logit)；sigmoid(l1 - l0) 只对双 logit 头
-// （num_labels=2 的导出，如 bge-reranker-v2-m3）成立。修复后按 cols 分支，
-// 两路各有回归；另加「分数全等 → warn 一次」的静默失效绊线。
-
-function sigmoid(x) {
-  return 1 / (1 + Math.exp(-x));
-}
-
-function candidates(ids) {
-  return ids.map((id) => ({ id, title: `T-${id}`, content: `C-${id}` }));
-}
-
-// 只支持 text-classification 的假引擎：cascade 先试 "rerank"（transformers
-// 4.2.0 无此任务，真机上也必然先失败），随后落到 tc。
-function makeTcFactory(dims, data) {
-  return async (task) => {
-    if (task === "rerank") throw new Error("unsupported task: rerank");
-    assert.equal(task, "text-classification");
-    return {
-      tokenizer: (texts, _opts) => ({ texts }),
-      model: async (inputs) => ({ logits: { dims, data: Float64Array.from(data.slice(0, inputs.texts.length * dims[1])) } })
-    };
-  };
-}
-
-test("#188: single-logit head scores sigmoid(logit) instead of constant 0.5", async () => {
-  // 报告的实测 logits：相关 -0.556、无关 -10.193，区分度近 10——模型判断得
-  // 很好，只是旧公式把它们全抹成 0.5000。
-  const r = new LocalReranker({
-    engineFactory: makeTcFactory([3, 1], [-0.5561, -10.193, 8.7])
-  });
-  await r.init();
-  const out = await r.rerank("查询", candidates(["rel", "noise", "hit"]));
-  // sigmoid(-0.5561)≈0.3645 保留；sigmoid(-10.193)≈3.7e-5 被 0.1 阈值滤掉；
-  // sigmoid(8.7)≈0.9998 居首。修复前三者全 0.5、顺序不变。
-  assert.deepEqual(out.map((x) => x.id), ["hit", "rel"]);
-  assert.ok(Math.abs(out[0].score - sigmoid(8.7)) < 1e-6, "hit = sigmoid(logit)");
-  assert.ok(Math.abs(out[1].score - sigmoid(-0.5561)) < 1e-6, "rel = sigmoid(logit)");
-  r.dispose();
-});
-
-test("#188: dual-logit head keeps softmax-positive-class semantics", async () => {
-  // l0=-2,l1=2 → sigmoid(4)；l0=1,l1=1.5 → sigmoid(0.5)——与原实现逐字节等价。
-  const r = new LocalReranker({
-    engineFactory: makeTcFactory([2, 2], [-2, 2, 1, 1.5])
-  });
-  await r.init();
-  const out = await r.rerank("查询", candidates(["a", "b"]));
-  assert.deepEqual(out.map((x) => x.id), ["a", "b"]);
-  assert.ok(Math.abs(out[0].score - sigmoid(4)) < 1e-6);
-  assert.ok(Math.abs(out[1].score - sigmoid(0.5)) < 1e-6);
-  r.dispose();
-});
-
-test("#188: constant-score batch warns once (silent-failure tripwire)", async () => {
-  const warns = [];
-  const r = new LocalReranker({
-    scorePair: async () => 0.5,
-    logger: { warn: (m) => warns.push(m), info: () => {} }
-  });
-  await r.rerank("查询", candidates(["a", "b", "c"]));
-  await r.rerank("查询", candidates(["a", "b", "c"]));
-  assert.equal(warns.length, 1, "constant-score batch warns exactly once across calls");
-  r.dispose();
-});
+import test from "node:test";
+import assert from "node:assert/strict";
+import { LocalReranker } from "../src/reranker.js";
+
+// 回归（issue #188）：Xenova/bge-reranker-base 是单 logit 交叉编码器——每个
+// (query, passage) 对只输出 1 个 logit。tc 策略此前在 cols===1 时把 l1 退化成
+// l0，sigmoid(l0 - l1) = sigmoid(0) = 0.5：所有候选分数恒为常量，重排静默失效
+// （不抛错、日志照常 ready、语义状态照常 reranker="ready"，只有分数是死的）。
+// 单 logit 头的正类概率是 sigmoid(logit)；sigmoid(l1 - l0) 只对双 logit 头
+// （num_labels=2 的导出，如 bge-reranker-v2-m3）成立。修复后按 cols 分支，
+// 两路各有回归；另加「分数全等 → warn 一次」的静默失效绊线。
+
+function sigmoid(x) {
+  return 1 / (1 + Math.exp(-x));
+}
+
+function candidates(ids) {
+  return ids.map((id) => ({ id, title: `T-${id}`, content: `C-${id}` }));
+}
+
+// 只支持 text-classification 的假引擎：cascade 先试 "rerank"（transformers
+// 4.2.0 无此任务，真机上也必然先失败），随后落到 tc。
+function makeTcFactory(dims, data) {
+  return async (task) => {
+    if (task === "rerank") throw new Error("unsupported task: rerank");
+    assert.equal(task, "text-classification");
+    return {
+      tokenizer: (texts, _opts) => ({ texts }),
+      model: async (inputs) => ({ logits: { dims, data: Float64Array.from(data.slice(0, inputs.texts.length * dims[1])) } })
+    };
+  };
+}
+
+test("#188: single-logit head scores sigmoid(logit) instead of constant 0.5", async () => {
+  // 报告的实测 logits：相关 -0.556、无关 -10.193，区分度近 10——模型判断得
+  // 很好，只是旧公式把它们全抹成 0.5000。
+  const r = new LocalReranker({
+    engineFactory: makeTcFactory([3, 1], [-0.5561, -10.193, 8.7])
+  });
+  await r.init();
+  const out = await r.rerank("查询", candidates(["rel", "noise", "hit"]));
+  // sigmoid(-0.5561)≈0.3645 保留；sigmoid(-10.193)≈3.7e-5 被 0.1 阈值滤掉；
+  // sigmoid(8.7)≈0.9998 居首。修复前三者全 0.5、顺序不变。
+  assert.deepEqual(out.map((x) => x.id), ["hit", "rel"]);
+  assert.ok(Math.abs(out[0].score - sigmoid(8.7)) < 1e-6, "hit = sigmoid(logit)");
+  assert.ok(Math.abs(out[1].score - sigmoid(-0.5561)) < 1e-6, "rel = sigmoid(logit)");
+  r.dispose();
+});
+
+test("#188: dual-logit head keeps softmax-positive-class semantics", async () => {
+  // l0=-2,l1=2 → sigmoid(4)；l0=1,l1=1.5 → sigmoid(0.5)——与原实现逐字节等价。
+  const r = new LocalReranker({
+    engineFactory: makeTcFactory([2, 2], [-2, 2, 1, 1.5])
+  });
+  await r.init();
+  const out = await r.rerank("查询", candidates(["a", "b"]));
+  assert.deepEqual(out.map((x) => x.id), ["a", "b"]);
+  assert.ok(Math.abs(out[0].score - sigmoid(4)) < 1e-6);
+  assert.ok(Math.abs(out[1].score - sigmoid(0.5)) < 1e-6);
+  r.dispose();
+});
+
+test("#188: constant-score batch warns once (silent-failure tripwire)", async () => {
+  const warns = [];
+  const r = new LocalReranker({
+    scorePair: async () => 0.5,
+    logger: { warn: (m) => warns.push(m), info: () => {} }
+  });
+  await r.rerank("查询", candidates(["a", "b", "c"]));
+  await r.rerank("查询", candidates(["a", "b", "c"]));
+  assert.equal(warns.length, 1, "constant-score batch warns exactly once across calls");
+  r.dispose();
+});

package/test/reranker.test.js

@@ -1,197 +1,197 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { LocalReranker } from "../src/reranker.js";
-
-/** Injected scorer: records (query, passage) calls, returns a fixed score. */
-function makeScorer(scoreOf) {
-  const calls = [];
-  const fn = async (query, passage) => {
-    calls.push({ query, passage });
-    return typeof scoreOf === "function" ? scoreOf(passage) : scoreOf;
-  };
-  return { fn, calls };
-}
-
-/** Fake feature-extraction engine: each input embeds to [1, k*0.25, 0, 0]. */
-function makeFakeExtractor(dim = 4, calls = []) {
-  let k = 0;
-  const fn = async (texts) => {
-    calls.push({ count: texts.length });
-    const rows = texts.map(() => {
-      const n = k++;
-      return Array.from({ length: dim }, (__, j) => (j === 0 ? 1 : j === 1 ? n * 0.25 : 0));
-    });
-    const flat = Float32Array.from(rows.flat());
-    return { data: flat, dims: [texts.length, dim] };
-  };
-  fn.dispose = () => {
-    fn.disposed = true;
-  };
-  return fn;
-}
-
-/** Fake text-classification engine exposing tokenizer + model for the tc path. */
-function makeFakeTc(logitsPerRow) {
-  const tokenizer = (texts, opts) => ({ texts, text_pair: opts.text_pair });
-  const model = async (inputs) => {
-    const n = inputs.texts.length;
-    const flat = new Float32Array(logitsPerRow.slice(0, n * 2));
-    return { logits: { data: flat, dims: [n, 2] } };
-  };
-  return { tokenizer, model, dispose: () => {} };
-}
-
-function candidates(ids) {
-  return ids.map((id) => ({ id, title: `T-${id}`, content: `C-${id}` }));
-}
-
-test("init with injected scorePair skips model loading", async () => {
-  let factoryCalled = false;
-  const { fn, calls } = makeScorer(0.7);
-  const r = new LocalReranker({
-    scorePair: fn,
-    engineFactory: async () => {
-      factoryCalled = true;
-      throw new Error("should never load");
-    }
-  });
-  await r.init();
-  assert.equal(factoryCalled, false);
-  const out = await r.rerank("q", candidates(["a"]));
-  assert.deepEqual(out, [{ id: "a", score: 0.7 }]);
-  assert.equal(calls.length, 1);
-  assert.equal(calls[0].query, "q");
-  assert.equal(calls[0].passage, "T-a\nC-a");
-});
-
-test("rerank returns results sorted by descending score", async () => {
-  const { fn } = makeScorer((p) => (p.includes("A") ? 0.9 : p.includes("B") ? 0.5 : 0.2));
-  const r = new LocalReranker({ scorePair: fn });
-  await r.init();
-  const out = await r.rerank("q", candidates(["A", "B", "C"]));
-  assert.deepEqual(out.map((x) => x.id), ["A", "B", "C"]);
-  assert.deepEqual(out.map((x) => x.score), [0.9, 0.5, 0.2]);
-});
-
-test("rerank returns [] for empty candidates", async () => {
-  const { fn } = makeScorer(0.9);
-  const r = new LocalReranker({ scorePair: fn });
-  await r.init();
-  assert.deepEqual(await r.rerank("q", []), []);
-});
-
-test("rerank drops candidates below scoreThreshold", async () => {
-  const { fn } = makeScorer((p) => (p.includes("A") ? 0.8 : p.includes("B") ? 0.4 : 0.05));
-  const r = new LocalReranker({ scorePair: fn, scoreThreshold: 0.3 });
-  await r.init();
-  const out = await r.rerank("q", candidates(["A", "B", "C"]));
-  assert.deepEqual(out.map((x) => x.id), ["A", "B"]);
-});
-
-test("rerank clamps scores into 0..1", async () => {
-  const { fn } = makeScorer((p) => (p.includes("A") ? 1.5 : p.includes("B") ? -0.2 : NaN));
-  const r = new LocalReranker({ scorePair: fn, scoreThreshold: 0 });
-  await r.init();
-  const out = await r.rerank("q", candidates(["A", "B", "C"]));
-  assert.deepEqual(out.map((x) => x.score), [1, 0, 0]);
-});
-
-test("rerank truncates to maxCandidates", async () => {
-  const { fn, calls } = makeScorer(0.6);
-  const r = new LocalReranker({ scorePair: fn, maxCandidates: 2 });
-  await r.init();
-  const out = await r.rerank("q", candidates(["a", "b", "c", "d"]));
-  assert.equal(calls.length, 2);
-  assert.equal(out.length, 2);
-});
-
-test("passage falls back to title when content is missing", async () => {
-  const { fn, calls } = makeScorer(0.8);
-  const r = new LocalReranker({ scorePair: fn });
-  await r.init();
-  await r.rerank("q", [{ id: "x", title: "only-title", content: "" }]);
-  assert.equal(calls[0].passage, "only-title");
-});
-
-test("rerank propagates injected scorer failures", async () => {
-  const bad = async () => {
-    throw new Error("scorer boom");
-  };
-  const r = new LocalReranker({ scorePair: bad });
-  await r.init();
-  await assert.rejects(() => r.rerank("q", candidates(["a"])), /scorer boom/);
-});
-
-test("rerank throws on non-array candidates", async () => {
-  const r = new LocalReranker({ scorePair: async () => 0.5 });
-  await r.init();
-  await assert.rejects(() => r.rerank("q", "not-an-array"), /array/);
-});
-
-test("init throws when no strategy can load", async () => {
-  const r = new LocalReranker({
-    engineFactory: async () => {
-      throw new Error("Unsupported pipeline");
-    }
-  });
-  await assert.rejects(() => r.init(), /LocalReranker failed to load/);
-});
-
-test("init cascades rerank -> tc -> feature-extraction and batches", async () => {
-  const calls = [];
-  const loader = async (task) => {
-    if (task === "feature-extraction") return makeFakeExtractor(4, calls);
-    throw new Error(`Unsupported pipeline: ${task}`);
-  };
-  const r = new LocalReranker({ engineFactory: loader, batchSize: 2 });
-  await r.init();
-  const out = await r.rerank("q", candidates(["a", "b", "c"]));
-  // Query k=0 [1,0,0,0]; a,b,c embed at k=1..3 -> cosine 0.970, 0.894, 0.8,
-  // all above the default threshold.
-  assert.equal(out.length, 3);
-  assert.deepEqual(out.map((x) => x.id), ["a", "b", "c"]);
-  assert.ok(out[0].score >= out[1].score && out[1].score >= out[2].score);
-  // Query embed (cached) + two batches of size 2 and 1.
-  assert.deepEqual(calls.map((c) => c.count), [1, 2, 1]);
-  // Query vector is cached: a second rerank only makes batch calls.
-  await r.rerank("q", candidates(["a", "b", "c"]));
-  assert.deepEqual(calls.map((c) => c.count), [1, 2, 1, 2, 1]);
-});
-
-test("text-classification strategy scores via logit delta", async () => {
-  const loader = async (task) => {
-    if (task === "text-classification") return makeFakeTc([0, 1, 0, 0, -2, 2]);
-    throw new Error(`Unsupported pipeline: ${task}`);
-  };
-  const r = new LocalReranker({ engineFactory: loader });
-  await r.init();
-  const out = await r.rerank("q", candidates(["A", "B", "C"]));
-  // sigmoid(1-0)=0.731, sigmoid(0)=0.5, sigmoid(2-(-2))=0.982.
-  assert.deepEqual(out.map((x) => x.id), ["C", "A", "B"]);
-  assert.ok(Math.abs(out[0].score - 0.982) < 1e-3);
-  assert.ok(Math.abs(out[1].score - 0.731) < 1e-3);
-  assert.ok(Math.abs(out[2].score - 0.5) < 1e-3);
-});
-
-test("modelHash follows the embedder convention", () => {
-  const a = new LocalReranker({ model: "Xenova/bge-reranker-base" });
-  const b = new LocalReranker({ model: "Xenova/bge-reranker-base" });
-  assert.equal(a.modelHash, b.modelHash);
-  assert.match(a.modelHash, /^Xenova\/bge-reranker-base#[0-9a-f]+$/);
-  assert.notEqual(a.modelHash, new LocalReranker({ model: "other/model" }).modelHash);
-});
-
-test("dispose releases the loaded pipeline", async () => {
-  const extractor = makeFakeExtractor(4);
-  const r = new LocalReranker({
-    engineFactory: async (task) => {
-      if (task === "feature-extraction") return extractor;
-      throw new Error("Unsupported pipeline");
-    }
-  });
-  await r.init();
-  assert.ok(r.pipeline);
-  r.dispose();
-  assert.equal(r.pipeline, null);
-  assert.equal(extractor.disposed, true);
-});
+import test from "node:test";
+import assert from "node:assert/strict";
+import { LocalReranker } from "../src/reranker.js";
+
+/** Injected scorer: records (query, passage) calls, returns a fixed score. */
+function makeScorer(scoreOf) {
+  const calls = [];
+  const fn = async (query, passage) => {
+    calls.push({ query, passage });
+    return typeof scoreOf === "function" ? scoreOf(passage) : scoreOf;
+  };
+  return { fn, calls };
+}
+
+/** Fake feature-extraction engine: each input embeds to [1, k*0.25, 0, 0]. */
+function makeFakeExtractor(dim = 4, calls = []) {
+  let k = 0;
+  const fn = async (texts) => {
+    calls.push({ count: texts.length });
+    const rows = texts.map(() => {
+      const n = k++;
+      return Array.from({ length: dim }, (__, j) => (j === 0 ? 1 : j === 1 ? n * 0.25 : 0));
+    });
+    const flat = Float32Array.from(rows.flat());
+    return { data: flat, dims: [texts.length, dim] };
+  };
+  fn.dispose = () => {
+    fn.disposed = true;
+  };
+  return fn;
+}
+
+/** Fake text-classification engine exposing tokenizer + model for the tc path. */
+function makeFakeTc(logitsPerRow) {
+  const tokenizer = (texts, opts) => ({ texts, text_pair: opts.text_pair });
+  const model = async (inputs) => {
+    const n = inputs.texts.length;
+    const flat = new Float32Array(logitsPerRow.slice(0, n * 2));
+    return { logits: { data: flat, dims: [n, 2] } };
+  };
+  return { tokenizer, model, dispose: () => {} };
+}
+
+function candidates(ids) {
+  return ids.map((id) => ({ id, title: `T-${id}`, content: `C-${id}` }));
+}
+
+test("init with injected scorePair skips model loading", async () => {
+  let factoryCalled = false;
+  const { fn, calls } = makeScorer(0.7);
+  const r = new LocalReranker({
+    scorePair: fn,
+    engineFactory: async () => {
+      factoryCalled = true;
+      throw new Error("should never load");
+    }
+  });
+  await r.init();
+  assert.equal(factoryCalled, false);
+  const out = await r.rerank("q", candidates(["a"]));
+  assert.deepEqual(out, [{ id: "a", score: 0.7 }]);
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].query, "q");
+  assert.equal(calls[0].passage, "T-a\nC-a");
+});
+
+test("rerank returns results sorted by descending score", async () => {
+  const { fn } = makeScorer((p) => (p.includes("A") ? 0.9 : p.includes("B") ? 0.5 : 0.2));
+  const r = new LocalReranker({ scorePair: fn });
+  await r.init();
+  const out = await r.rerank("q", candidates(["A", "B", "C"]));
+  assert.deepEqual(out.map((x) => x.id), ["A", "B", "C"]);
+  assert.deepEqual(out.map((x) => x.score), [0.9, 0.5, 0.2]);
+});
+
+test("rerank returns [] for empty candidates", async () => {
+  const { fn } = makeScorer(0.9);
+  const r = new LocalReranker({ scorePair: fn });
+  await r.init();
+  assert.deepEqual(await r.rerank("q", []), []);
+});
+
+test("rerank drops candidates below scoreThreshold", async () => {
+  const { fn } = makeScorer((p) => (p.includes("A") ? 0.8 : p.includes("B") ? 0.4 : 0.05));
+  const r = new LocalReranker({ scorePair: fn, scoreThreshold: 0.3 });
+  await r.init();
+  const out = await r.rerank("q", candidates(["A", "B", "C"]));
+  assert.deepEqual(out.map((x) => x.id), ["A", "B"]);
+});
+
+test("rerank clamps scores into 0..1", async () => {
+  const { fn } = makeScorer((p) => (p.includes("A") ? 1.5 : p.includes("B") ? -0.2 : NaN));
+  const r = new LocalReranker({ scorePair: fn, scoreThreshold: 0 });
+  await r.init();
+  const out = await r.rerank("q", candidates(["A", "B", "C"]));
+  assert.deepEqual(out.map((x) => x.score), [1, 0, 0]);
+});
+
+test("rerank truncates to maxCandidates", async () => {
+  const { fn, calls } = makeScorer(0.6);
+  const r = new LocalReranker({ scorePair: fn, maxCandidates: 2 });
+  await r.init();
+  const out = await r.rerank("q", candidates(["a", "b", "c", "d"]));
+  assert.equal(calls.length, 2);
+  assert.equal(out.length, 2);
+});
+
+test("passage falls back to title when content is missing", async () => {
+  const { fn, calls } = makeScorer(0.8);
+  const r = new LocalReranker({ scorePair: fn });
+  await r.init();
+  await r.rerank("q", [{ id: "x", title: "only-title", content: "" }]);
+  assert.equal(calls[0].passage, "only-title");
+});
+
+test("rerank propagates injected scorer failures", async () => {
+  const bad = async () => {
+    throw new Error("scorer boom");
+  };
+  const r = new LocalReranker({ scorePair: bad });
+  await r.init();
+  await assert.rejects(() => r.rerank("q", candidates(["a"])), /scorer boom/);
+});
+
+test("rerank throws on non-array candidates", async () => {
+  const r = new LocalReranker({ scorePair: async () => 0.5 });
+  await r.init();
+  await assert.rejects(() => r.rerank("q", "not-an-array"), /array/);
+});
+
+test("init throws when no strategy can load", async () => {
+  const r = new LocalReranker({
+    engineFactory: async () => {
+      throw new Error("Unsupported pipeline");
+    }
+  });
+  await assert.rejects(() => r.init(), /LocalReranker failed to load/);
+});
+
+test("init cascades rerank -> tc -> feature-extraction and batches", async () => {
+  const calls = [];
+  const loader = async (task) => {
+    if (task === "feature-extraction") return makeFakeExtractor(4, calls);
+    throw new Error(`Unsupported pipeline: ${task}`);
+  };
+  const r = new LocalReranker({ engineFactory: loader, batchSize: 2 });
+  await r.init();
+  const out = await r.rerank("q", candidates(["a", "b", "c"]));
+  // Query k=0 [1,0,0,0]; a,b,c embed at k=1..3 -> cosine 0.970, 0.894, 0.8,
+  // all above the default threshold.
+  assert.equal(out.length, 3);
+  assert.deepEqual(out.map((x) => x.id), ["a", "b", "c"]);
+  assert.ok(out[0].score >= out[1].score && out[1].score >= out[2].score);
+  // Query embed (cached) + two batches of size 2 and 1.
+  assert.deepEqual(calls.map((c) => c.count), [1, 2, 1]);
+  // Query vector is cached: a second rerank only makes batch calls.
+  await r.rerank("q", candidates(["a", "b", "c"]));
+  assert.deepEqual(calls.map((c) => c.count), [1, 2, 1, 2, 1]);
+});
+
+test("text-classification strategy scores via logit delta", async () => {
+  const loader = async (task) => {
+    if (task === "text-classification") return makeFakeTc([0, 1, 0, 0, -2, 2]);
+    throw new Error(`Unsupported pipeline: ${task}`);
+  };
+  const r = new LocalReranker({ engineFactory: loader });
+  await r.init();
+  const out = await r.rerank("q", candidates(["A", "B", "C"]));
+  // sigmoid(1-0)=0.731, sigmoid(0)=0.5, sigmoid(2-(-2))=0.982.
+  assert.deepEqual(out.map((x) => x.id), ["C", "A", "B"]);
+  assert.ok(Math.abs(out[0].score - 0.982) < 1e-3);
+  assert.ok(Math.abs(out[1].score - 0.731) < 1e-3);
+  assert.ok(Math.abs(out[2].score - 0.5) < 1e-3);
+});
+
+test("modelHash follows the embedder convention", () => {
+  const a = new LocalReranker({ model: "Xenova/bge-reranker-base" });
+  const b = new LocalReranker({ model: "Xenova/bge-reranker-base" });
+  assert.equal(a.modelHash, b.modelHash);
+  assert.match(a.modelHash, /^Xenova\/bge-reranker-base#[0-9a-f]+$/);
+  assert.notEqual(a.modelHash, new LocalReranker({ model: "other/model" }).modelHash);
+});
+
+test("dispose releases the loaded pipeline", async () => {
+  const extractor = makeFakeExtractor(4);
+  const r = new LocalReranker({
+    engineFactory: async (task) => {
+      if (task === "feature-extraction") return extractor;
+      throw new Error("Unsupported pipeline");
+    }
+  });
+  await r.init();
+  assert.ok(r.pipeline);
+  r.dispose();
+  assert.equal(r.pipeline, null);
+  assert.equal(extractor.disposed, true);
+});

package/test/resident-status.test.js

@@ -0,0 +1,83 @@
+// 常驻状态条（#164 对齐，PR-3）测试。
+// 覆盖：总览即「唯一常驻叙述」——每次 dream 刷新走 _overwrite supersede
+// （单行、content_history 可追溯）、内容带快照口径脚注（条数 + run 片段 +
+// 日期）、summary tier 注入位不变。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createDreamScheduler } from "../src/dream.js";
+
+function setup() {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  return { store, service };
+}
+
+function mockCtx(sequence) {
+  // sequence = 按流顺序的响应表：consolidation 调用给 {decisions}，summary
+  // 调用给 {summary}，一次 runDream 消费两项。
+  let calls = 0;
+  return {
+    llm: {
+      stream: async function* () {
+        const step = sequence[calls] ?? { summary: "空转叙述" };
+        calls++;
+        const text = step.decisions !== undefined ? JSON.stringify(step.decisions) : step.summary;
+        yield { type: "text-delta", text };
+        yield { type: "finish", reason: { kind: "ok" } };
+      }
+    },
+    logger: { warn: () => {} }
+  };
+}
+
+test("overview refresh carries the snapshot-scope footer", async () => {
+  const { store, service } = setup();
+  service.saveWithDedupe({ type: "project", title: "项目", content: "活跃中" });
+  const dream = createDreamScheduler({ thresholdCount: 1, thresholdChars: 0, delayMs: 0 });
+  const result = await dream.runDream(
+    mockCtx([{ decisions: [] }, { summary: "当前在推进记忆插件，蒸馏管线已稳定。" }]),
+    service,
+    { dreamProvider: "deepseek", dreamModel: "deepseek-chat" }
+  );
+  assert.equal(result.ok, true);
+  const summary = store.all().find((m) => m.type === "summary");
+  assert.ok(summary, "resident bar created");
+  assert.ok(summary.content.startsWith("当前在推进记忆插件"), "narrative body first");
+  assert.match(summary.content, /〔口径：基于整理后 \d+ 条记忆快照 · run [0-9a-f]{8} · \d{4}-\d{2}-\d{2}〕/, "scope footer carries count/run/date");
+  store.close();
+});
+
+test("second refresh supersedes in place: one row, overwrite traceable in content_history", async () => {
+  const { store, service } = setup();
+  service.saveWithDedupe({ type: "project", title: "项目", content: "活跃中" });
+  const dream = createDreamScheduler({ thresholdCount: 1, thresholdChars: 0, delayMs: 0 });
+  const ctx = mockCtx([
+    { decisions: [] },
+    { summary: "第一版状态叙述。" },
+    { decisions: [] },
+    { summary: "第二版状态叙述。" }
+  ]);
+  await dream.runDream(ctx, service, { dreamProvider: "deepseek", dreamModel: "deepseek-chat" });
+  await dream.runDream(ctx, service, { dreamProvider: "deepseek", dreamModel: "deepseek-chat" });
+  const summaries = store.all().filter((m) => m.type === "summary");
+  assert.equal(summaries.length, 1, "exactly one resident bar (supersede, not append)");
+  assert.ok(summaries[0].content.startsWith("第二版状态叙述。"), "latest narrative wins");
+  assert.ok((summaries[0].content_history ?? []).length >= 1, "overwrite recorded in content_history");
+  store.close();
+});
+
+test("resident bar rides the summary tier 0 injection slot", () => {
+  const { store, service } = setup();
+  service.saveWithDedupe({ type: "summary", title: "记忆库总览", content: "当前状态叙述正文", importance: 5 });
+  service.saveWithDedupe({ type: "preference", title: "语言", content: "中文", importance: 5 });
+  // injectCandidates 的 summary=0 档位契约：总览排在普通记忆前
+  const candidates = service.injectCandidates({ query: "", maxItems: 5 });
+  const ids = candidates.map((c) => c.id);
+  const summaryId = store.all().find((m) => m.type === "summary").id;
+  const prefId = store.all().find((m) => m.type === "preference").id;
+  assert.ok(ids.includes(summaryId), "resident bar in candidates");
+  assert.ok(ids.indexOf(summaryId) < ids.indexOf(prefId), "resident bar ahead of normal memories");
+  store.close();
+});