@modusensus/dsh-mneme 0.8.16 → 0.9.1

package/test/publish-gate.test.js

@@ -0,0 +1,272 @@
+// scripts/publish-gate.mjs 的回归测试。
+//
+// 这一步的价值全在「不许假绿」上：原先的 Verify published version 是
+//   echo "Published: $(npm view "@modusensus/dsh-mneme@${V}" version)"
+// 命令替换里的失败不让 `set -e` 退出 —— v0.8.16 那次日志里明明 `404 No match found for version
+// 0.8.16`，step 与 job 却都是 success。下面第一条与第三条各自钉住两端：
+//   · 版本已在 registry（幂等跳过路径）→ 立刻通过，不为传播延迟白等；
+//   · 等满预算仍看不见 → 必须 `ok:false` 且入口退出 1。
+// 谁要是把「拿不到」改成「跳过校验」或「返回成功」，第三条会红。
+//
+// 全部用例走假时钟 + 注入 probe：零网络、零真实等待，跑起来是毫秒级。
+// 还有一条走真进程（spawnSync）的端到端用例：工作流红不红只看真进程退出码，函数级断言钉不到
+// 「主模块判别 + process.exitCode」那条路径。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  DEFAULT_INTERVAL_MS,
+  DEFAULT_TIMEOUT_MS,
+  PACKAGE_NAME,
+  main,
+  parseArgs,
+  probeVersion,
+  versionUrl,
+  waitForPublished
+} from "../scripts/publish-gate.mjs";
+
+/** 被测入口的真实路径：端到端用例要把它当子进程跑起来。 */
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+
+/** 假时钟：只有 sleep() 会让时间前进，于是超时逻辑可以确定性断言。 */
+function fakeClock() {
+  let t = 0;
+  return {
+    now: () => t,
+    sleep: async (ms) => { t += ms; },
+    slept: () => t
+  };
+}
+
+const noop = () => {};
+
+/** 前 `misses` 次报 404、之后可见的 probe；锁的是「重试真的发生了」。 */
+function probeMissingTimes(misses, { version = "0.8.16" } = {}) {
+  let calls = 0;
+  return async () => {
+    calls += 1;
+    if (calls <= misses) return { ok: false, reason: "missing", detail: "HTTP 404，registry 上还看不到" };
+    return { ok: true, version, tarball: "https://registry.npmjs.org/x/-/x-0.8.16.tgz" };
+  };
+}
+
+test("版本已在 registry：首次探测即通过，不为传播延迟白等（幂等跳过路径）", async () => {
+  const clock = fakeClock();
+  let sleeps = 0;
+  const result = await waitForPublished("0.8.16", {
+    now: clock.now,
+    sleep: async (ms) => { sleeps += 1; await clock.sleep(ms); },
+    probe: probeMissingTimes(0),
+    log: noop
+  });
+  assert.equal(result.ok, true);
+  assert.equal(result.attempts, 1);
+  assert.equal(result.waitedMs, 0);
+  assert.equal(sleeps, 0, "已发布路径不该有任何等待");
+});
+
+test("传播延迟：前两次 404、第三次可见 → 通过，且等待时间与重试次数如实报出", async () => {
+  const clock = fakeClock();
+  const result = await waitForPublished("0.8.16", {
+    now: clock.now,
+    sleep: clock.sleep,
+    intervalMs: 15000,
+    probe: probeMissingTimes(2),
+    log: noop
+  });
+  assert.equal(result.ok, true);
+  assert.equal(result.attempts, 3);
+  assert.equal(result.waitedMs, 30000, "两次间隔的等待要计入");
+  assert.ok(result.tarball.includes("0.8.16"));
+});
+
+test("等满预算仍看不见：必须 ok:false + reason timeout（防的就是 v0.8.16 那种假绿）", async () => {
+  const clock = fakeClock();
+  const result = await waitForPublished("0.8.16", {
+    now: clock.now,
+    sleep: clock.sleep,
+    timeoutMs: 30000,
+    intervalMs: 15000,
+    probe: probeMissingTimes(Infinity),
+    log: noop
+  });
+  assert.equal(result.ok, false, "拿不到版本时绝不是成功");
+  assert.equal(result.reason, "timeout");
+  assert.equal(result.attempts, 3, "t=0 / 15s / 30s 各一次探测");
+  assert.equal(result.waitedMs, 30000);
+  assert.match(result.lastError, /404/);
+});
+
+test("探测自己耗时到超过预算、但回来时版本已可见：仍然通过（预算约束等待，不约束判定）", async () => {
+  // 锁的是刻意选择：单次探测带 HTTP 超时，晚到的成功最多超出预算十几秒；而版本真的在 registry 上
+  // 就是发布成功，为晚到几秒判红是假红——闸门要消灭的是假绿，不该顺手制造另一种失真。
+  const clock = fakeClock();
+  const result = await waitForPublished("0.8.16", {
+    now: clock.now,
+    sleep: clock.sleep,
+    timeoutMs: 15000,
+    intervalMs: 15000,
+    probe: async () => {
+      await clock.sleep(20000); // 这一次探测自己就把预算耗穿了
+      return { ok: true, version: "0.8.16", tarball: "" };
+    },
+    log: noop
+  });
+  assert.equal(result.ok, true);
+  assert.equal(result.attempts, 1);
+  assert.equal(result.waitedMs, 20000);
+});
+
+test("预算不是间隔整数倍时：最后一轮只睡到超时点，不多睡一整轮", async () => {
+  const clock = fakeClock();
+  const result = await waitForPublished("0.8.16", {
+    now: clock.now,
+    sleep: clock.sleep,
+    timeoutMs: 20000,
+    intervalMs: 15000,
+    probe: probeMissingTimes(Infinity),
+    log: noop
+  });
+  assert.equal(result.ok, false);
+  assert.equal(result.attempts, 3, "t=0 / 15s / 20s（最后一次落在超时点上）");
+  assert.equal(result.waitedMs, 20000);
+  assert.equal(clock.slept(), 20000, "总睡眠时间恰为预算，而不是 30000");
+});
+
+test("网络异常同样计入重试（既不崩也不当作成功），最终以最后一次原因报出", async () => {
+  const clock = fakeClock();
+  let calls = 0;
+  const result = await waitForPublished("0.8.16", {
+    now: clock.now,
+    sleep: clock.sleep,
+    timeoutMs: 15000,
+    intervalMs: 15000,
+    probe: async () => { calls += 1; return { ok: false, detail: `请求失败：fetch failed（第 ${calls} 次）` }; },
+    log: noop
+  });
+  assert.equal(result.ok, false);
+  assert.equal(result.attempts, 2, "异常也继续重试");
+  assert.match(result.lastError, /第 2 次/, "报的是最后一次原因");
+});
+
+test("probe 返回形状异常（undefined）也不炸，按拿不到处理", async () => {
+  const clock = fakeClock();
+  const result = await waitForPublished("0.8.16", {
+    now: clock.now,
+    sleep: clock.sleep,
+    timeoutMs: 0,
+    intervalMs: 15000,
+    probe: async () => undefined,
+    log: noop
+  });
+  assert.equal(result.ok, false);
+  assert.equal(result.reason, "timeout");
+});
+
+test("默认预算：超时 10 分钟 / 间隔 15 秒（覆盖实测 ~4.5 分钟的传播延迟）", () => {
+  assert.equal(DEFAULT_TIMEOUT_MS, 600000);
+  assert.equal(DEFAULT_INTERVAL_MS, 15000);
+});
+
+test("versionUrl：scoped 包名整体编码，origin 尾斜杠不重复", () => {
+  assert.equal(
+    versionUrl(PACKAGE_NAME, "0.8.16"),
+    "https://registry.npmjs.org/%40modusensus%2Fdsh-mneme/0.8.16"
+  );
+  assert.equal(
+    versionUrl(PACKAGE_NAME, "0.8.16", "https://registry.npmjs.org/"),
+    "https://registry.npmjs.org/%40modusensus%2Fdsh-mneme/0.8.16"
+  );
+});
+
+test("probeVersion：404 = 还没传播，200 且版本一致 = 可见（带 tarball）", async () => {
+  const missing = await probeVersion("0.8.16", {
+    fetchImpl: async () => ({ ok: false, status: 404, json: async () => ({}) })
+  });
+  assert.equal(missing.ok, false);
+  assert.equal(missing.reason, "missing");
+
+  const found = await probeVersion("0.8.16", {
+    fetchImpl: async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({ version: "0.8.16", dist: { tarball: "https://registry.npmjs.org/x/-/x-0.8.16.tgz" } })
+    })
+  });
+  assert.equal(found.ok, true);
+  assert.equal(found.tarball, "https://registry.npmjs.org/x/-/x-0.8.16.tgz");
+});
+
+test("probeVersion：请求抛错 / 5xx / 响应不是 JSON / 版本对不上，都折成 ok:false 而不抛", async () => {
+  const net = await probeVersion("0.8.16", { fetchImpl: async () => { throw new Error("fetch failed"); } });
+  assert.equal(net.reason, "network");
+
+  const http = await probeVersion("0.8.16", { fetchImpl: async () => ({ ok: false, status: 500, json: async () => ({}) }) });
+  assert.equal(http.reason, "http");
+
+  const badJson = await probeVersion("0.8.16", {
+    fetchImpl: async () => ({ ok: true, status: 200, json: async () => { throw new Error("boom"); } })
+  });
+  assert.equal(badJson.reason, "bad-json");
+
+  const mismatch = await probeVersion("0.8.16", {
+    fetchImpl: async () => ({ ok: true, status: 200, json: async () => ({ version: "0.8.15" }) })
+  });
+  assert.equal(mismatch.ok, false);
+  assert.equal(mismatch.reason, "mismatch");
+});
+
+test("parseArgs：位置参数给版本号，可覆盖预算；缺版本号如实回报", () => {
+  assert.deepEqual(parseArgs(["0.8.16"]), { ok: true, version: "0.8.16", timeoutMs: 600000, intervalMs: 15000 });
+  assert.deepEqual(parseArgs(["0.8.16", "--timeout-ms", "1000", "--interval-ms", "500"]), {
+    ok: true, version: "0.8.16", timeoutMs: 1000, intervalMs: 500
+  });
+  assert.equal(parseArgs([]).reason, "missing-version");
+  assert.equal(parseArgs(["0.8.16", "0.8.17"]).reason, "missing-version");
+  assert.equal(parseArgs(["0.8.16", "--timeout-ms", "abc"]).ok, false);
+});
+
+test("入口退出码：通过 → 0；超时 → 1 且 stderr 指明去翻 publish 步日志", async () => {
+  const logs = [];
+  const errors = [];
+  const okCode = await main(["0.8.16"], {
+    log: (line) => logs.push(line),
+    error: (line) => errors.push(line),
+    wait: async (version) => ({ ok: true, version, attempts: 1, waitedMs: 0, tarball: "" })
+  });
+  assert.equal(okCode, 0);
+  assert.equal(errors.length, 0);
+
+  const failCode = await main(["0.8.16"], {
+    log: noop,
+    error: (line) => errors.push(line),
+    wait: async () => ({ ok: false, reason: "timeout", attempts: 40, waitedMs: 600000, lastError: "HTTP 404" })
+  });
+  assert.equal(failCode, 1, "闸门未通过必须以非零退出让 job 变红");
+  assert.ok(errors.some((line) => line.includes("发布闸门未通过")));
+  assert.ok(errors.some((line) => line.includes("publish 步")));
+});
+
+test("入口退出码：缺版本号 → 1 并打印用法", async () => {
+  const errors = [];
+  const code = await main([], { log: noop, error: (line) => errors.push(line), wait: async () => ({ ok: true }) });
+  assert.equal(code, 1);
+  assert.ok(errors.some((line) => line.includes("用法")));
+});
+
+test("真进程端到端：不存在的版本 → 退出码 1 且 stderr 指明原因（这一步红了 job 才会红）", () => {
+  // 单测里的 main() 是函数调用，钉不到「主模块判别 + process.exitCode」这条真实退出路径——而
+  // 工作流红不红只看真进程的退出码。目标版本刻意取一个永不存在、与发布无关的名字：registry 回
+  // 404（连不上网络则是 network 原因），两种都会走到同一个超时分支，所以这条例外不引入网络依赖。
+  const result = spawnSync(
+    process.execPath,
+    [join(scriptDir, "..", "scripts", "publish-gate.mjs"), "0.0.0-mneme-gate-test", "--timeout-ms", "1", "--interval-ms", "1"],
+    { encoding: "utf8" }
+  );
+  assert.equal(result.status, 1, `期望非零退出，实际 ${result.status}（stderr: ${result.stderr}）`);
+  assert.match(result.stderr, /发布闸门未通过/);
+  assert.match(result.stdout, /等待 @modusensus\/dsh-mneme@0\.0\.0-mneme-gate-test/);
+});

package/test/recall-retention.test.js

@@ -0,0 +1,128 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { createStore } from "../src/store.js";
+
+// 2026-10-14 找回：recall_runs 的滚动清理（函数 + 启动调用）在 dd0ed78「release:
+// v0.7.12」里被整块弄丢，而配置键 recallRetentionDays、README.md 与
+// docs/CONFIGURATION.md 一直宣称它有保留期 —— 于是本机那张表只增不减，没人发现
+// （2026-10-13 当天实测就从 16,041 涨到 20,510 行）。
+//
+// 这组测试故意分两半，因为**弄丢的正是「两半都在」这件事**：
+//   1. 行为锁：函数真的删对行、边界正确、空表不炸；
+//   2. 接线锁：index.js 的启动块真的调它，且读的是装配后的 cfg（不是 rawCfg）。
+// 只锁 1 不锁 2，函数写得再对也没人调；只锁 2 不锁 1，调用调的可能是空壳。
+// 第二半用源码文本断言，理由与 test/client.test.js 的 bilingual 锁同款：这是
+// 「接线还在不在」的问题，运行时冒烟测不到一个**在运维时才会跑**的启动分支。
+
+const here = dirname(fileURLToPath(import.meta.url));
+const srcText = (name) => readFileSync(join(here, "..", "src", name), "utf8");
+
+function seedRun(store, { query, createdAt }) {
+  store.saveRecallRun({
+    query,
+    mode: "auto",
+    topK: 5,
+    threshold: null,
+    candidates: [],
+    created_at: createdAt
+  });
+}
+
+const daysAgo = (n) => new Date(Date.now() - n * 86400000).toISOString();
+
+test("保留期：删掉窗口外的行、留下窗口内的行，返回值是真实删除数", () => {
+  const store = createStore(":memory:");
+  seedRun(store, { query: "老", createdAt: daysAgo(120) });
+  seedRun(store, { query: "也老", createdAt: daysAgo(91) });
+  seedRun(store, { query: "新", createdAt: daysAgo(89) });
+  seedRun(store, { query: "很新", createdAt: daysAgo(1) });
+
+  const removed = store.purgeRecallRunsOlderThan(90);
+  assert.equal(removed, 2, "只有窗口外的两行该被删");
+
+  // 两侧都排过再比：assert 的是「留下了哪两行」，不是它们的物理顺序
+  const left = store.listRecallRunsSince(daysAgo(3650)).rows.map((r) => r.query).sort();
+  assert.deepEqual(left, ["很新", "新"].sort());
+  store.close();
+});
+
+test("保留期：边界按字典序比较，窗口内的留、窗口外的删（两侧各留 1 小时裕量）", () => {
+  const store = createStore(":memory:");
+  // 不骑刀刃：cutoff 是在**清理那一刻**用 Date.now() 现算的，而造数据也取一次
+  // Date.now()，测试跑几毫秒就足以让「正好 90 天前」翻到界外。这里两侧各留
+  // 1 小时，锁的是比较方向（`created_at < cutoff` 才删），不是毫秒级巧合。
+  const boundary = 90 * 86400000;
+  seedRun(store, { query: "窗口内一小时", createdAt: new Date(Date.now() - boundary + 3600000).toISOString() });
+  seedRun(store, { query: "窗口外一小时", createdAt: new Date(Date.now() - boundary - 3600000).toISOString() });
+
+  const removed = store.purgeRecallRunsOlderThan(90);
+  assert.equal(removed, 1, "越过界的才删，贴近界的要留");
+  assert.deepEqual(store.listRecallRunsSince(daysAgo(3650)).rows.map((r) => r.query), ["窗口内一小时"]);
+  store.close();
+});
+
+test("保留期：空表返回 0，不抛（清理是 bookkeeping，不许挡启动）", () => {
+  const store = createStore(":memory:");
+  assert.equal(store.purgeRecallRunsOlderThan(90), 0);
+  store.close();
+});
+
+test("接线锁：index.js 启动块真的调 purgeRecallRunsOlderThan，且读装配后的 cfg", () => {
+  const index = srcText("index.js");
+  assert.match(index, /store\.purgeRecallRunsOlderThan\(recallRetentionDays\)/,
+    "启动期必须真的调用清理——这对曾在 dd0ed78 里双双蒸发");
+  assert.match(index, /cfg\.recallRetentionDays/,
+    "必须读装配后的 cfg（面板改保留期才生效），不能读 rawCfg");
+  // 失败必须真的出声。这一对当初就是**无声**蒸发的：函数与调用一起没了、没人发现，
+  // 表涨到两万余行。清理再失败一次若仍然静默，同一类回归照样看不见——所以这里
+  // 两个方向都锁：接住（catch(err)，不 rethrow、不挡启动）与出声（真调 logger.warn）。
+  // 只锁「不挡启动」会放过静默吞，只锁「出声」会放过把异常抛出去挡启动。
+  const at = index.indexOf("store.purgeRecallRunsOlderThan(recallRetentionDays)");
+  assert.ok(at > 0, "启动期必须真的调用清理——这对曾在 dd0ed78 里双双蒸发");
+  const tail = index.slice(at, at + 600);
+  assert.match(tail, /catch \(err\) \{/, "清理失败要接住，不许挡插件启动");
+  assert.match(tail, /ctx\.logger\?\.warn\?\.\(/, "清理失败要 warn 出声，静默吞等于把回归再藏一次");
+  // 就近确认它落在同一族启动清理之间：失败表 → llm_audit → distill → recall_runs
+  const llm = index.indexOf("store.deleteOldLlmAudits");
+  const distill = index.indexOf("store.clearDistillRecords");
+  assert.ok(llm > 0 && distill > 0 && at > llm, "recall_runs 清理应排在 llm_audit 之后");
+  assert.ok(at > distill, "recall_runs 清理应排在 distill_records 之后（与现有启动顺序一致）");
+});
+
+test("接线锁：store.js 导出 purgeRecallRunsOlderThan（函数存在但没导出同样是断线）", () => {
+  const store = srcText("store.js");
+  assert.match(store, /function purgeRecallRunsOlderThan\(days\)/);
+  assert.match(store, /^\s*purgeRecallRunsOlderThan,\s*$/m, "必须在 createStore 的返回对象里导出");
+  assert.match(store, /DELETE FROM recall_runs WHERE created_at < \?/);
+});
+
+// 启动期清理是**一族的四个兄弟**：失败表 / llm_audit / distill_records / recall_runs。
+// 上面那条只锁了 recall_runs 一个，但四个的注释互相引用（llm_audit 那条原文写着
+// 「失败只 warn，与失败表清理同款」），而 2026-10-14 实测前三个全是
+// `catch { /* non-fatal */ }` —— 静默吞，与注释宣称的相反。recall_runs 那一对当初
+// 就是无声蒸发的，所以这一族必须一起锁：只要有一个偷偷退回静默吞，这条就红。
+test("接线锁：四个启动期清理都必须出声（catch(err) + logger.warn，不许静默吞）", () => {
+  const index = srcText("index.js");
+  const family = [
+    ["失败表", "store.deleteOldFailures("],
+    ["llm_audit", "store.deleteOldLlmAudits("],
+    ["distill_records", "store.clearDistillRecords("],
+    ["recall_runs", "store.purgeRecallRunsOlderThan(recallRetentionDays)"]
+  ];
+  for (const [label, call] of family) {
+    const at = index.indexOf(call);
+    assert.ok(at > 0, `${label} 的启动期清理调用必须在（弄丢过一次的就是这一族）`);
+    const tail = index.slice(at, at + 700);
+    assert.match(tail, /catch \(err\) \{/, `${label} 清理失败要接住，不许挡插件启动`);
+    assert.match(tail, /ctx\.logger\?\.warn\?\.\(/, `${label} 清理失败要 warn 出声，静默吞等于把回归再藏一次`);
+  }
+});
+
+test("接线锁：配置键与文档对外宣称的保留期一致（键还在、默认 90 天）", () => {
+  const cfgText = srcText("config.js");
+  assert.match(cfgText, /recallRetentionDays: z\.natural\(\)\.min\(1\)\.max\(3650\)\.default\(90\)/,
+    "配置键被改或删掉时，这条和文档一起要动——别让文档继续说谎");
+});

package/test/reindex-backfill.test.js

@@ -28,13 +28,13 @@ test("Issue #128: fingerprint match no longer blocks backfill; archived rows are
   };
 
   const logs = [];
-  const indexed = await backfillMissingEmbeddings({
+  const summary = await backfillMissingEmbeddings({
     store, embedder, vectorIndex,
     logger: { info: (m) => logs.push(m) },
     rateLimitMs: 0
   });
 
-  assert.equal(indexed, 1, "the active row is backfilled despite the matching fingerprint");
+  assert.equal(summary.indexed, 1, "the active row is backfilled despite the matching fingerprint");
   assert.equal(store.getEmbeddings([active.id]).get(active.id)?.length, 3, "active row now carries a vector");
   assert.equal(store.getEmbeddings([dead.id]).get(dead.id), undefined, "archived row is skipped");
   assert.equal(vectorIndex.modelHash(), "mock-model#abc", "fingerprint unchanged (markModel idempotent)");
@@ -51,12 +51,91 @@ test("Issue #128: backfill is bounded by maxTotal; the rest stays queued", async
   const embedder = { embedSingle: async () => [1, 0, 0], modelHash: "h#1", dimension: 3 };
   const vectorIndex = createVectorIndex({ store });
 
-  const indexed = await backfillMissingEmbeddings({
+  const summary = await backfillMissingEmbeddings({
     store, embedder, vectorIndex,
     logger: { info() {} },
     maxTotal: 4, batchSize: 2, rateLimitMs: 0
   });
-  assert.equal(indexed, 4, "stops at the maxTotal bound");
+  assert.equal(summary.indexed, 4, "stops at the maxTotal bound");
+  // A capped run must SAY it was capped. The old bare-count return made a
+  // capped run indistinguishable from a run that drained the backlog.
+  assert.equal(summary.finishReason, "capped");
+  assert.equal(summary.stillStale, true, "reports that work remains");
   assert.equal(store.needsEmbedding(10).length, 1, "remaining rows stay queued for the next boot");
   store.close();
 });
+
+test("maxTotal: 0 drains the whole backlog in one run", async () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  for (let i = 0; i < 5; i++) {
+    service.saveWithDedupe({ type: "preference", title: `记忆${i}`, content: `内容${i}` });
+  }
+  const embedder = { embedSingle: async () => [1, 0, 0], modelHash: "h#1", dimension: 3 };
+  const vectorIndex = createVectorIndex({ store });
+
+  const summary = await backfillMissingEmbeddings({
+    store, embedder, vectorIndex,
+    logger: { info() {} },
+    maxTotal: 0, batchSize: 2, rateLimitMs: 0
+  });
+  assert.equal(summary.indexed, 5, "no cap: every row is embedded");
+  assert.equal(summary.finishReason, "drained");
+  assert.equal(summary.stillStale, false, "nothing left behind");
+  store.close();
+});
+
+test("a full-model switch re-embeds old vectors, not just the empty ones", async () => {
+  // The old selector only matched NULL/'' — vectors from the previous model
+  // stayed "present" forever and were never re-embedded, so they kept
+  // inflating coverage while being incomparable to the new query embedding.
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const a = service.saveWithDedupe({ type: "preference", title: "旧向量", content: "甲" }).memory;
+  const b = service.saveWithDedupe({ type: "preference", title: "无向量", content: "乙" }).memory;
+  store.setEmbedding(a.id, [1, 0, 0], "old-model#aaa");
+  // b stays empty.
+
+  const embedder = { embedSingle: async () => [0, 1, 0], modelHash: "new-model#bbb", dimension: 3 };
+  const vectorIndex = createVectorIndex({ store });
+  const summary = await backfillMissingEmbeddings({
+    store, embedder, vectorIndex, logger: { info() {} }, rateLimitMs: 0
+  });
+
+  assert.equal(summary.indexed, 2, "both the stale-model row and the empty row are re-embedded");
+  assert.equal(summary.finishReason, "drained");
+  assert.equal(store.needsEmbeddingFor("new-model#bbb", 10).length, 0, "nothing stale remains");
+  const breakdown = store.embeddingModelBreakdown();
+  assert.equal(breakdown.length, 1, "every vector now carries the new model");
+  assert.equal(breakdown[0].model, "new-model#bbb");
+  assert.equal(breakdown[0].c, 2);
+  store.close();
+});
+
+test("rows with unknown provenance (NULL embedding_model) count as stale", async () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const r = service.saveWithDedupe({ type: "preference", title: "存量", content: "丙" }).memory;
+  // Simulate a pre-migration row: vector present, provenance unknown.
+  store.setEmbedding(r.id, [1, 0, 0]);
+
+  assert.equal(store.needsEmbedding(10).length, 0, "old selector sees nothing to do");
+  assert.equal(store.needsEmbeddingFor("new-model#bbb", 10).length, 1, "new selector flags unknown origin");
+  assert.equal(store.hasStaleEmbedding("new-model#bbb"), true);
+  store.close();
+});
+
+test("setEmbedding records provenance and clearing the vector clears it", async () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const r = service.saveWithDedupe({ type: "preference", title: "出身", content: "丁" }).memory;
+
+  store.setEmbedding(r.id, [1, 0, 0], "m#1");
+  assert.equal(store.embeddingModelBreakdown()[0].model, "m#1");
+
+  store.setEmbedding(r.id, null);
+  const row = store.db.prepare("SELECT embedding, embedding_model FROM memories WHERE id = ?").get(r.id);
+  assert.equal(row.embedding, null);
+  assert.equal(row.embedding_model, null, "a cleared vector never keeps a stale model name");
+  store.close();
+});

package/test/release-docs.test.js

@@ -0,0 +1,130 @@
+// 锁发布准备里「改文档表格」这一段的三件事，它们各自都静默失效过或随时会：
+//
+// 1. 根 README 的路线图版本列写的是两段式 **v0.9**，旧实现只认三段式 **v0.9.0**，于是
+//    对根 README 一个字节没改，打印的却是「无版本表格行，跳过」——把「没做」说成「不需要做」。
+// 2. 往 CRLF 文件里插一行而不显式保行尾，会把文件混成一半 CRLF 一半 LF（changelog-prep 踩过）。
+// 3. SECURITY.md 的支持版本表跨 minor 时必须由人挪格。脚本只核对；核对一旦退化成永真，
+//    0.10.0 就能带着「0.9.x 活跃开发中」的表格发出去——那是安全策略文档里的谎话。
+//
+// 前两类直接读真实 README 断言（正则被改窄时，用户会静默看到「跳过」，而测试必须变红）。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { checkSupportTable, scanReleaseRows, syncReadmeTables } from "../scripts/release-docs.mjs";
+
+const pkgRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const repoRoot = path.dirname(pkgRoot);
+const rootReadme = readFileSync(path.join(repoRoot, "README.md"), "utf8");
+const pkgReadme = readFileSync(path.join(pkgRoot, "README.md"), "utf8");
+const securityDoc = readFileSync(path.join(repoRoot, "SECURITY.md"), "utf8");
+const { version } = JSON.parse(readFileSync(path.join(pkgRoot, "package.json"), "utf8"));
+
+const CRLF = "\r\n";
+const crlf = (...lines) => lines.join(CRLF) + CRLF;
+
+test("两份真实 README 的版本表都还认得出（根按 minor、子按 patch）", () => {
+  const root = scanReleaseRows(rootReadme);
+  assert.ok(root.two.length >= 3, `根 README 的路线图应解析出至少 3 行两段式版本行，实际 ${root.two.length}`);
+  assert.equal(root.three.length, 0,
+    "根 README 的路线图按 minor 排，不该出现三段式版本行——出现了说明表格形状变了，插入位置需要重算");
+  const sub = scanReleaseRows(pkgReadme);
+  assert.ok(sub.three.length >= 1, `子 README 的版本历史应解析出至少 1 行三段式版本行，实际 ${sub.three.length}`);
+});
+
+test("根 README 的两段式路线图能插进新 minor 占位行（旧实现零命中）", () => {
+  const sample = crlf(
+    "| 版本 | 主题 | 状态 |",
+    "|------|------|------|",
+    "| **v0.8** | 生态化 | ✅ 已发布（至 v0.8.16） |",
+    "| **v0.9** | 手法 beta | ✅ 已发布（v0.9.0） |",
+  );
+  const { text, actions } = syncReadmeTables(sample, "0.10.0", "2026-11-01");
+  assert.equal(actions.filter((a) => a.kind === "insert").length, 1, "应插入且只插入一行");
+  assert.match(text, /\| \*\*v0\.10\*\* \| （待填） \| ✅ 已发布（v0\.10\.0） \|/,
+    "占位行按 minor 写 v0.10，状态写这次要发出去的完整版本");
+  // 插在 v0.9 之后，而不是表尾——表尾将来会有更高的计划行
+  assert.ok(text.indexOf("**v0.10**") > text.indexOf("**v0.9**"), "占位行应排在 v0.9 之后");
+});
+
+test("真实根 README 的中英两张路线图各插一行（同一版本号，不能只插一张）", () => {
+  // 两张表版本行完全一样，旧实现把全文件版本行合成一个数组判断「已存在」，
+  // 于是先插的中文表会让英文表被跳过——英文读者永远等不到那一行。
+  const { actions } = syncReadmeTables(rootReadme, "0.10.0", "2026-11-01");
+  const inserts = actions.filter((a) => a.kind === "insert");
+  assert.equal(inserts.length, 2, "中英路线图各一行，实际：" + JSON.stringify(actions));
+});
+
+test("子 README 的版本历史插占位行时写完整 patch 号并带日期", () => {
+  const sample = crlf(
+    "| 版本 | 主题 |",
+    "|------|------|",
+    "| **v0.9.0**（2026-10-17） | 手法 beta |",
+    "| **v0.8.x** | 作用域隔离 |",
+  );
+  const { text } = syncReadmeTables(sample, "0.9.1", "2026-10-18");
+  assert.match(text, /\| \*\*v0\.9\.1\*\*（2026-10-18） \| （待填） \|/);
+  assert.ok(text.indexOf("**v0.9.1**") < text.indexOf("**v0.8.x**"),
+    "占位行要排在低于它的最新版本之后、概括行之前");
+});
+
+test("路线图里上一版留下的「🚧 准备中」在发版准备时回填成已发布", () => {
+  const sample = crlf(
+    "| 版本 | 主题 | 状态 |",
+    "|------|------|------|",
+    "| **v0.9** | 手法 beta | 🚧 准备中 |",
+  );
+  const { text } = syncReadmeTables(sample, "0.9.0", "2026-10-17");
+  assert.match(text, /\| \*\*v0\.9\*\* \| 手法 beta \| ✅ 已发布（v0\.9\.0） \|/);
+  // 已经写着已发布的行不动：脚本跑在打 tag 之前，改写补丁号等于提前宣布一个还没发出去的版本。
+  const already = crlf(
+    "| 版本 | 主题 | 状态 |",
+    "|------|------|------|",
+    "| **v0.9** | 手法 beta | ✅ 已发布（v0.9.0） |",
+  );
+  assert.equal(syncReadmeTables(already, "0.9.1", "2026-10-18").text, already,
+    "已发布的补丁号由人在真正发出去之后更新，脚本不擅自提前改");
+});
+
+test("插入占位行不改变行尾风格（CRLF 文件不会混进裸 LF）", () => {
+  const sample = crlf(
+    "| 版本 | 主题 |",
+    "|------|------|",
+    "| **v0.9.0**（2026-10-17） | 手法 beta |",
+  );
+  const { text } = syncReadmeTables(sample, "0.9.1", "2026-10-18");
+  const bareLf = (text.match(/(?<!\r)\n/g) || []).length;
+  assert.equal(bareLf, 0, `输出里出现了 ${bareLf} 个裸 LF——CRLF 文件被混写了一半 LF`);
+});
+
+test("重复跑是幂等的：已有目标的占位行就不再插第二行", () => {
+  const sample = crlf(
+    "| 版本 | 主题 |",
+    "|------|------|",
+    "| **v0.9.0**（2026-10-17） | 手法 beta |",
+  );
+  const once = syncReadmeTables(sample, "0.9.1", "2026-10-18").text;
+  const twice = syncReadmeTables(once, "0.9.1", "2026-10-18");
+  assert.equal(twice.text, once);
+  assert.deepEqual(twice.actions, [], "第二次应报告零变更，而不是再插一行");
+});
+
+test("SECURITY.md 支持版本表：同 minor 通过，跨 minor 如实报出中英两处", () => {
+  const sameMinor = checkSupportTable(securityDoc, version);
+  assert.equal(sameMinor.ok, true, `真实 SECURITY.md 应与 package.json ${version} 一致：${sameMinor.problems.join("；")}`);
+
+  const nextMinor = `${version.split(".")[0]}.${Number(version.split(".")[1]) + 1}.0`;
+  const crossing = checkSupportTable(securityDoc, nextMinor);
+  assert.equal(crossing.ok, false, "跨 minor 时必须报错——否则会带着过时的支持范围发版");
+  assert.equal(crossing.problems.length, 2, "中英两张表各报一条：" + crossing.problems.join("；"));
+  assert.ok(crossing.problems.every((p) => p.includes(crossing.expected)),
+    "每条问题都要写出期望值，否则人不知道改成什么：" + crossing.problems.join("；"));
+});
+
+test("SECURITY.md 支持版本表：节缺失或表格形状变了也报错（不能静默通过）", () => {
+  assert.equal(checkSupportTable("# Security\n\n## 别的节\n", "0.9.0").ok, false);
+  const noRows = "## Supported Versions\r\n\r\n没有表格\r\n\r\n## 支持版本\r\n\r\n没有表格\r\n";
+  assert.equal(checkSupportTable(noRows, "0.9.0").ok, false,
+    "解析不出任何版本行时必须失败：正则失配不能变成永真");
+});