@modusensus/dsh-mneme 0.13.0 → 0.14.0-beta.2

package/test/embed-ready-poll.test.js

@@ -1,94 +1,94 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { createStore } from "../src/store.js";
-import { createService } from "../src/service.js";
-
-// 这条锁防的是一类「上限形同不存在」的回归：上限判断如果排在会抛错的那次读取
-// 后面，轮询就永远不会停手。
-//
-// service.js 的 setEmbedder 为异步初始化的 embedder 起了个轮询：每 100ms 读一次
-// `emb.ready`，读到 true 或撞上 EMBED_READY_POLL_LIMIT(=30) 就停
-// （注释原文 "~3s ceiling; never poll forever"）。但 `ready` 是个 getter
-// —— embedding.js 的 OpenAI embedder 直接读库 —— 于是写成
-//     if (emb.ready === true || attempts >= EMBED_READY_POLL_LIMIT) { stop(); }
-// 的整条 `||` 会在左半边当场中断，右半边的天花板永远轮不到：stopEmbedReadyPolling()
-// 不执行，定时器活过上限，并且每 100ms 抛一次未捕获异常。
-//
-// 实测现场（2026-10-14，加蒸馏留存的装配级用例时撞上）：fiber.dispose() 走完
-// index.js 的 disposer（末尾一句就是 store.close()）之后，每次读 ready 都抛
-// "database is not open" [ERR_INVALID_STATE]，5s 内读了 46 次 —— 天花板 31 被
-// 击穿，node --test 进程因此不再退出。一个只在启动时读一次库的 getter，能把
-// 宿主的事件循环钉死；而现有测试全都「装配完不拆」，所以从 v0.7.1 起一直没人碰到。
-//
-// 时序照真实卸载顺序复现：安装时未就绪（轮询启动）→ store.close()（此后每次读
-// ready 都抛）→ 等超过天花板 → 看它停没停手、报了几次。
-const POLL_LIMIT = 30; // 与 src/service.js 的 EMBED_READY_POLL_LIMIT 同值，改那边要改这里
-const POLL_MS = 100;
-const CEILING_READS = 1 + POLL_LIMIT; // setEmbedder 自己读一次，之后每个 tick 一次
-const SETTLE_MS = 400; // 静默这么久没新读取，就认为定时器已经停手
-const DEADLINE_MS = 30000; // 上限：等到这里还没静默就按超时处理
-
-// 等「读取次数不再增长」。不能用「睡够 POLL_MS*30 + 600ms 再断言」——
-// 全量 npm test 是多文件并行跑的，CPU 一挤，30 个 tick 未必在 3.6s 内跑完，
-// 断言就会读到 30 而不是 31（2026-10-15 rebase 后在全量跑里实测撞到一次，
-// 单跑 3/3 通过、紧接着全量跑两遍也全绿——纯粹的负载抖动）。
-// 静默判定是可靠的：定时器周期 100ms，而越过上限后 stopEmbedReadyPolling()
-// 会 clearInterval，此后 reads 恒不再变，两者不会混淆。
-async function waitUntilSettled(getReads) {
-  const started = Date.now();
-  let last = getReads();
-  let lastChange = Date.now();
-  while (Date.now() - started < DEADLINE_MS) {
-    await new Promise((resolve) => setTimeout(resolve, 50));
-    const now = getReads();
-    if (now !== last) {
-      last = now;
-      lastChange = Date.now();
-      continue;
-    }
-    if (Date.now() - lastChange >= SETTLE_MS) return now;
-  }
-  return getReads();
-}
-
-test("the embedder ready poll stops at its ceiling even when reading ready throws", async () => {
-  const warns = [];
-  const store = createStore(":memory:");
-  const service = createService({
-    store,
-    mirror: null,
-    config: {},
-    logger: { warn: (...args) => warns.push(args) }
-  });
-
-  let reads = 0;
-  let closed = false;
-  const embedder = {
-    get ready() {
-      reads++;
-      if (closed) {
-        // 与 embedding.js 的 OpenAI embedder 同形：getter 内部经 settings 读库。
-        store.db.prepare("SELECT count(*) AS c FROM memories").get();
-      }
-      return false; // 始终「未就绪」：轮询会一直跑下去，除非天花板真的生效
-    }
-  };
-
-  service.setEmbedder(embedder);
-  assert.equal(reads, 1, "setEmbedder 先读一次 ready，决定要不要起轮询");
-
-  closed = true;
-  store.close(); // 卸载路径的最后一步
-
-  await waitUntilSettled(() => reads);
-  const atCeiling = reads;
-
-  assert.equal(
-    atCeiling,
-    CEILING_READS,
-    `读 ready 抛错也必须按上限停手（实际读了 ${atCeiling} 次，上限 ${CEILING_READS}）`
-  );
-  assert.equal(reads, atCeiling, "越过天花板之后不许再有读取：定时器必须已经清掉");
-  assert.equal(warns.length, 1, "读不出来只报一次，别把 3s 上限变成 30 条刷屏");
-  assert.match(String(warns[0][0]), /embedder ready probe failed/);
-});
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+
+// 这条锁防的是一类「上限形同不存在」的回归：上限判断如果排在会抛错的那次读取
+// 后面，轮询就永远不会停手。
+//
+// service.js 的 setEmbedder 为异步初始化的 embedder 起了个轮询：每 100ms 读一次
+// `emb.ready`，读到 true 或撞上 EMBED_READY_POLL_LIMIT(=30) 就停
+// （注释原文 "~3s ceiling; never poll forever"）。但 `ready` 是个 getter
+// —— embedding.js 的 OpenAI embedder 直接读库 —— 于是写成
+//     if (emb.ready === true || attempts >= EMBED_READY_POLL_LIMIT) { stop(); }
+// 的整条 `||` 会在左半边当场中断，右半边的天花板永远轮不到：stopEmbedReadyPolling()
+// 不执行，定时器活过上限，并且每 100ms 抛一次未捕获异常。
+//
+// 实测现场（2026-10-14，加蒸馏留存的装配级用例时撞上）：fiber.dispose() 走完
+// index.js 的 disposer（末尾一句就是 store.close()）之后，每次读 ready 都抛
+// "database is not open" [ERR_INVALID_STATE]，5s 内读了 46 次 —— 天花板 31 被
+// 击穿，node --test 进程因此不再退出。一个只在启动时读一次库的 getter，能把
+// 宿主的事件循环钉死；而现有测试全都「装配完不拆」，所以从 v0.7.1 起一直没人碰到。
+//
+// 时序照真实卸载顺序复现：安装时未就绪（轮询启动）→ store.close()（此后每次读
+// ready 都抛）→ 等超过天花板 → 看它停没停手、报了几次。
+const POLL_LIMIT = 30; // 与 src/service.js 的 EMBED_READY_POLL_LIMIT 同值，改那边要改这里
+const POLL_MS = 100;
+const CEILING_READS = 1 + POLL_LIMIT; // setEmbedder 自己读一次，之后每个 tick 一次
+const SETTLE_MS = 400; // 静默这么久没新读取，就认为定时器已经停手
+const DEADLINE_MS = 30000; // 上限：等到这里还没静默就按超时处理
+
+// 等「读取次数不再增长」。不能用「睡够 POLL_MS*30 + 600ms 再断言」——
+// 全量 npm test 是多文件并行跑的，CPU 一挤，30 个 tick 未必在 3.6s 内跑完，
+// 断言就会读到 30 而不是 31（2026-10-15 rebase 后在全量跑里实测撞到一次，
+// 单跑 3/3 通过、紧接着全量跑两遍也全绿——纯粹的负载抖动）。
+// 静默判定是可靠的：定时器周期 100ms，而越过上限后 stopEmbedReadyPolling()
+// 会 clearInterval，此后 reads 恒不再变，两者不会混淆。
+async function waitUntilSettled(getReads) {
+  const started = Date.now();
+  let last = getReads();
+  let lastChange = Date.now();
+  while (Date.now() - started < DEADLINE_MS) {
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    const now = getReads();
+    if (now !== last) {
+      last = now;
+      lastChange = Date.now();
+      continue;
+    }
+    if (Date.now() - lastChange >= SETTLE_MS) return now;
+  }
+  return getReads();
+}
+
+test("the embedder ready poll stops at its ceiling even when reading ready throws", async () => {
+  const warns = [];
+  const store = createStore(":memory:");
+  const service = createService({
+    store,
+    mirror: null,
+    config: {},
+    logger: { warn: (...args) => warns.push(args) }
+  });
+
+  let reads = 0;
+  let closed = false;
+  const embedder = {
+    get ready() {
+      reads++;
+      if (closed) {
+        // 与 embedding.js 的 OpenAI embedder 同形：getter 内部经 settings 读库。
+        store.db.prepare("SELECT count(*) AS c FROM memories").get();
+      }
+      return false; // 始终「未就绪」：轮询会一直跑下去，除非天花板真的生效
+    }
+  };
+
+  service.setEmbedder(embedder);
+  assert.equal(reads, 1, "setEmbedder 先读一次 ready，决定要不要起轮询");
+
+  closed = true;
+  store.close(); // 卸载路径的最后一步
+
+  await waitUntilSettled(() => reads);
+  const atCeiling = reads;
+
+  assert.equal(
+    atCeiling,
+    CEILING_READS,
+    `读 ready 抛错也必须按上限停手（实际读了 ${atCeiling} 次，上限 ${CEILING_READS}）`
+  );
+  assert.equal(reads, atCeiling, "越过天花板之后不许再有读取：定时器必须已经清掉");
+  assert.equal(warns.length, 1, "读不出来只报一次，别把 3s 上限变成 30 条刷屏");
+  assert.match(String(warns[0][0]), /embedder ready probe failed/);
+});

package/test/embed-text-reasons.test.js

@@ -1,112 +1,112 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { embedText, embedTextDetailed, createEmbedder } from "../src/embedding.js";
-
-// distill-tx-embed-gap 的"坏了为什么看不出来"半边：embedText 此前把「配置缺」
-// 「网络挂」「超时」「HTTP 4xx/5xx」「响应不是 JSON」「响应没有向量」全部压成
-// null，回执账本只能统一写 embedding-request-returned-no-vector——分诊不可能。
-// embedTextDetailed 把失败模式拆开；embedText 保留旧 null 契约（调用方不变）。
-
-const FULL = {
-  enabled: true,
-  baseUrl: "https://api.example.com/v1",
-  apiKey: "sk-test",
-  model: "text-embedding-3-small"
-};
-
-async function withFetch(impl, fn) {
-  const original = globalThis.fetch;
-  globalThis.fetch = impl;
-  try {
-    return await fn();
-  } finally {
-    globalThis.fetch = original;
-  }
-}
-
-test("detailed: 成功时 reason 为 null，vector 与旧契约一致", async () => {
-  await withFetch(async () => ({ ok: true, json: async () => ({ data: [{ embedding: [1, 2, 3] }] }) }), async () => {
-    const out = await embedTextDetailed(FULL, "猫咪");
-    assert.deepEqual(out.vector, [1, 2, 3]);
-    assert.equal(out.reason, null);
-    // 旧包装的 null 契约不变
-    assert.deepEqual(await embedText(FULL, "猫咪"), [1, 2, 3]);
-  });
-});
-
-test("detailed: 配置缺失时逐字段点名，不伪装成网络故障", async () => {
-  assert.match((await embedTextDetailed({ ...FULL, model: "" }, "x")).reason, /^config-incomplete:model$/);
-  assert.match((await embedTextDetailed({ ...FULL, apiKey: "" }, "x")).reason, /^config-incomplete:apiKey$/);
-  assert.match((await embedTextDetailed({ ...FULL, baseUrl: "" }, "x")).reason, /^config-incomplete:baseUrl$/);
-  assert.match(await embedTextDetailed(FULL, "").then((o) => o.reason), /config-incomplete:text/);
-});
-
-test("detailed: HTTP 状态码进 reason（401 钥匙 / 404 路径 / 429 限流）", async () => {
-  await withFetch(async () => ({ ok: false, status: 404, text: async () => "Not Found" }), async () => {
-    const out = await embedTextDetailed(FULL, "x");
-    assert.equal(out.vector, null);
-    assert.equal(out.reason, "http-404:Not Found");
-  });
-  await withFetch(async () => ({ ok: false, status: 429, text: async () => "" }), async () => {
-    const out = await embedTextDetailed(FULL, "x");
-    assert.equal(out.reason, "http-429", "空响应体不拼尾巴");
-  });
-  // 旧包装在这些场景全部 null，不抛
-  await withFetch(async () => ({ ok: false, status: 401, text: async () => "denied" }), async () => {
-    assert.equal(await embedText(FULL, "x"), null);
-  });
-});
-
-test("detailed: 超时与网络错误分型，不混为一谈", async () => {
-  await withFetch(async () => {
-    const err = new Error("socket hang up");
-    err.name = "TypeError";
-    throw err;
-  }, async () => {
-    const out = await embedTextDetailed(FULL, "x");
-    assert.match(out.reason, /^request-failed:network:socket hang up/);
-  });
-  await withFetch(async () => {
-    const err = new Error("The operation was aborted");
-    err.name = "TimeoutError";
-    throw err;
-  }, async () => {
-    const out = await embedTextDetailed(FULL, "x");
-    assert.match(out.reason, /^request-failed:timeout:/, "慢和不通是两种病");
-  });
-});
-
-test("detailed: 响应不是 JSON 与响应没有向量各自有名", async () => {
-  await withFetch(async () => ({ ok: true, json: async () => { throw new Error("bad"); } }), async () => {
-    const out = await embedTextDetailed(FULL, "x");
-    assert.equal(out.reason, "response-not-json");
-  });
-  await withFetch(async () => ({ ok: true, json: async () => ({ data: [] }) }), async () => {
-    const out = await embedTextDetailed(FULL, "x");
-    assert.equal(out.reason, "response-no-vector");
-  });
-});
-
-test("embedFor 回执账本带上可区分 reason（不再是统一的 no-vector）", async () => {
-  const receipts = [];
-  const embedder = createEmbedder({
-    store: { setEmbedding() {} },
-    settings: { getVectorConfig: () => FULL },
-    logger: { info() {}, warn() {} }
-  });
-  // embedReceipts 在账本上；rejection 已在 schedule() 内消化，这里直接等 schedule promise。
-  await withFetch(async () => ({ ok: false, status: 404, text: async () => "no route" }), async () => {
-    const r = await embedder.schedule({ id: "m1", title: "t", content: "c" });
-    assert.equal(r.status, "failed");
-    assert.equal(r.reason, "http-404:no route");
-  });
-  await withFetch(async () => ({ ok: true, json: async () => ({ data: [{ embedding: [1, 2, 3] }] }) }), async () => {
-    const r = await embedder.schedule({ id: "m2", title: "t", content: "c" });
-    assert.equal(r.status, "ok");
-    assert.equal(r.dim, 3);
-  });
-  const snap = embedder.embedReceipts();
-  assert.equal(snap.totals.failed, 1);
-  assert.equal(snap.totals.ok, 1);
-  assert.equal(snap.lastFailReason, "http-404:no route", "账本记的是分诊后的原因");
-});
+import test from "node:test";
+import assert from "node:assert/strict";
+import { embedText, embedTextDetailed, createEmbedder } from "../src/embedding.js";
+
+// distill-tx-embed-gap 的"坏了为什么看不出来"半边：embedText 此前把「配置缺」
+// 「网络挂」「超时」「HTTP 4xx/5xx」「响应不是 JSON」「响应没有向量」全部压成
+// null，回执账本只能统一写 embedding-request-returned-no-vector——分诊不可能。
+// embedTextDetailed 把失败模式拆开；embedText 保留旧 null 契约（调用方不变）。
+
+const FULL = {
+  enabled: true,
+  baseUrl: "https://api.example.com/v1",
+  apiKey: "sk-test",
+  model: "text-embedding-3-small"
+};
+
+async function withFetch(impl, fn) {
+  const original = globalThis.fetch;
+  globalThis.fetch = impl;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = original;
+  }
+}
+
+test("detailed: 成功时 reason 为 null，vector 与旧契约一致", async () => {
+  await withFetch(async () => ({ ok: true, json: async () => ({ data: [{ embedding: [1, 2, 3] }] }) }), async () => {
+    const out = await embedTextDetailed(FULL, "猫咪");
+    assert.deepEqual(out.vector, [1, 2, 3]);
+    assert.equal(out.reason, null);
+    // 旧包装的 null 契约不变
+    assert.deepEqual(await embedText(FULL, "猫咪"), [1, 2, 3]);
+  });
+});
+
+test("detailed: 配置缺失时逐字段点名，不伪装成网络故障", async () => {
+  assert.match((await embedTextDetailed({ ...FULL, model: "" }, "x")).reason, /^config-incomplete:model$/);
+  assert.match((await embedTextDetailed({ ...FULL, apiKey: "" }, "x")).reason, /^config-incomplete:apiKey$/);
+  assert.match((await embedTextDetailed({ ...FULL, baseUrl: "" }, "x")).reason, /^config-incomplete:baseUrl$/);
+  assert.match(await embedTextDetailed(FULL, "").then((o) => o.reason), /config-incomplete:text/);
+});
+
+test("detailed: HTTP 状态码进 reason（401 钥匙 / 404 路径 / 429 限流）", async () => {
+  await withFetch(async () => ({ ok: false, status: 404, text: async () => "Not Found" }), async () => {
+    const out = await embedTextDetailed(FULL, "x");
+    assert.equal(out.vector, null);
+    assert.equal(out.reason, "http-404:Not Found");
+  });
+  await withFetch(async () => ({ ok: false, status: 429, text: async () => "" }), async () => {
+    const out = await embedTextDetailed(FULL, "x");
+    assert.equal(out.reason, "http-429", "空响应体不拼尾巴");
+  });
+  // 旧包装在这些场景全部 null，不抛
+  await withFetch(async () => ({ ok: false, status: 401, text: async () => "denied" }), async () => {
+    assert.equal(await embedText(FULL, "x"), null);
+  });
+});
+
+test("detailed: 超时与网络错误分型，不混为一谈", async () => {
+  await withFetch(async () => {
+    const err = new Error("socket hang up");
+    err.name = "TypeError";
+    throw err;
+  }, async () => {
+    const out = await embedTextDetailed(FULL, "x");
+    assert.match(out.reason, /^request-failed:network:socket hang up/);
+  });
+  await withFetch(async () => {
+    const err = new Error("The operation was aborted");
+    err.name = "TimeoutError";
+    throw err;
+  }, async () => {
+    const out = await embedTextDetailed(FULL, "x");
+    assert.match(out.reason, /^request-failed:timeout:/, "慢和不通是两种病");
+  });
+});
+
+test("detailed: 响应不是 JSON 与响应没有向量各自有名", async () => {
+  await withFetch(async () => ({ ok: true, json: async () => { throw new Error("bad"); } }), async () => {
+    const out = await embedTextDetailed(FULL, "x");
+    assert.equal(out.reason, "response-not-json");
+  });
+  await withFetch(async () => ({ ok: true, json: async () => ({ data: [] }) }), async () => {
+    const out = await embedTextDetailed(FULL, "x");
+    assert.equal(out.reason, "response-no-vector");
+  });
+});
+
+test("embedFor 回执账本带上可区分 reason（不再是统一的 no-vector）", async () => {
+  const receipts = [];
+  const embedder = createEmbedder({
+    store: { setEmbedding() {} },
+    settings: { getVectorConfig: () => FULL },
+    logger: { info() {}, warn() {} }
+  });
+  // embedReceipts 在账本上；rejection 已在 schedule() 内消化，这里直接等 schedule promise。
+  await withFetch(async () => ({ ok: false, status: 404, text: async () => "no route" }), async () => {
+    const r = await embedder.schedule({ id: "m1", title: "t", content: "c" });
+    assert.equal(r.status, "failed");
+    assert.equal(r.reason, "http-404:no route");
+  });
+  await withFetch(async () => ({ ok: true, json: async () => ({ data: [{ embedding: [1, 2, 3] }] }) }), async () => {
+    const r = await embedder.schedule({ id: "m2", title: "t", content: "c" });
+    assert.equal(r.status, "ok");
+    assert.equal(r.dim, 3);
+  });
+  const snap = embedder.embedReceipts();
+  assert.equal(snap.totals.failed, 1);
+  assert.equal(snap.totals.ok, 1);
+  assert.equal(snap.lastFailReason, "http-404:no route", "账本记的是分诊后的原因");
+});