@modusensus/dsh-mneme 0.8.2 → 0.8.3

package/src/service.js

@@ -1235,7 +1235,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
    * fills + dedupes the remaining slots. Empty query / no cached recall /
    * hybridInject off → pure legacy rule-based selection.
    */
-  function injectCandidates({ query = "", maxItems = 5, threshold = 3, queryVector, scope = null } = {}) {
+  function injectCandidates({ query = "", maxItems = 5, threshold = 3, queryVector, scope = null, rotate = null, rotateWindow = 0 } = {}) {
     const q = String(query ?? "").trim();
     // codingRetrospect 读取侧门控：编码记忆（rejected_solution / pitfall /
     // constraint）只在编码任务时注入，防噪声污染其他业务；编码任务时按
@@ -1246,7 +1246,15 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     // (quality_score null) count as 100 (weight 1), so legacy stores keep their
     // exact summary>preference>importance ordering.
     const qualityWeight = (m) => (m.quality_score != null ? m.quality_score / 100 : 1);
-    const items = store.list({ limit: 200, includeForgotten: false })
+    // Issue #205 补测：候选池必须比轮换窗口大——窗口 N 需要 maxItems×(N+1) 张
+    // 不同的牌，池子只有 maxItems×2 时窗口一开就被吃光、只剩回填（重复率的
+    // 结构性下限由池子大小决定）。无轮换时保持既有 maxItems×2 不变；规则路
+    // 的 200 条上限同样给轮换让路（上限翻倍也只是多读一次 SQL LIMIT）。
+    const rotateWindowN = Number.isInteger(rotateWindow) && rotateWindow > 0 ? rotateWindow : 0;
+    const poolSize = rotateWindowN > 0
+      ? Math.max(maxItems * 2, maxItems * (rotateWindowN + 1))
+      : maxItems * 2;
+    const items = store.list({ limit: Math.max(200, poolSize), includeForgotten: false })
       .filter((m) => !m.archived && INJECT_TYPES.has(m.type) && !m.forgotten &&
         codingGate(m) &&
         (m.type === "summary" || m.type === "preference" || m.importance >= threshold))
@@ -1277,7 +1285,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       const semanticItems = [];
       if (Array.isArray(queryVector) && queryVector.length && vectorIndex) {
         try {
-          const hits = vectorIndex.search(queryVector, { limit: maxItems * 2, threshold: 0 });
+          const hits = vectorIndex.search(queryVector, { limit: poolSize, threshold: 0 });
           for (const m of hits) {
             if (m && !m.archived && INJECT_TYPES.has(m.type) && !m.forgotten &&
               codingGate(m) &&
@@ -1300,7 +1308,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       // 足以把当前话题顶到前排；门控与向量路径一致（含 importance 阈值）。
       // 语义向量命中时本分支不参与，行为不变。
       if (!semanticItems.length) {
-        for (const hit of bm25Recall(q, maxItems * 2)) {
+        for (const hit of bm25Recall(q, poolSize)) {
           if (hit && !hit.archived && INJECT_TYPES.has(hit.type) && !hit.forgotten &&
             codingGate(hit) &&
             (hit.type === "summary" || hit.type === "preference" || hit.importance >= threshold)) {
@@ -1318,10 +1326,10 @@ export function createService({ store, mirror, config, onWrite, logger }) {
         };
         for (const m of semanticItems) {
           push(m);
-          if (merged.length >= maxItems * 2) break;
+          if (merged.length >= poolSize) break;
         }
         for (const m of items) {
-          if (merged.length >= maxItems * 2) break;
+          if (merged.length >= poolSize) break;
           push(m);
         }
         candidates = merged;
@@ -1346,6 +1354,14 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     if (config?.strictScope === true && scope) {
       candidates = candidates.filter((m) => isVisibleInScope(m, scope));
     }
+    // Issue #205：注入位跨轮轮换。rotate = 最近 N 轮注入过的 id 集合（由注入层
+    // 按会话维护并传入）：这些条目本轮不再优先——新鲜者前置（各自内部相对次序
+    // 保持），不足时按原序回填，槽位数与 touchRecall 语义均不变。rotate 为空时
+    // 行为与既有排序完全一致。
+    if (rotate && rotate.size > 0 && candidates.length > 0) {
+      const fresh = candidates.filter((m) => !rotate.has(m.id));
+      if (fresh.length > 0) candidates = [...fresh, ...candidates.filter((m) => rotate.has(m.id))];
+    }
     const selected = candidates.slice(0, maxItems);
     touchRecalled(selected);
     return selected;

package/src/settings.js

@@ -52,6 +52,7 @@ const FEATURE_FLAG_BOOLEANS = [
   "selectiveInjectEnabled",
   "searchSemanticDedup",
   "rerankEnabled",
+  "resilientModelDownload",
   "adaptiveThresholdEnabled",
   "reflectionUpdateEnabled",
   "reflectionFailureTracking",

package/test/api.test.js

@@ -644,17 +644,18 @@ test("GET /api/dsh-mneme/features returns empty overrides and effective config d
   assert.equal(res.statusCode, 200);
   const data = JSON.parse(res.body);
   assert.deepEqual(data.overrides, {});
-  // effective 覆盖全部 51 个白名单键（含 v0.7.20 heatEnabled、Issue #89 新增
+  // effective 覆盖全部 52 个白名单键（含 v0.7.20 heatEnabled、Issue #89 新增
   // dreamSkipInvalid/allowCrossTypeMerge/dreamMinIntervalMinutes、面板可调的
   // dreamMaxTokens、睡眠路由 sleepProvider/sleepModel、PR1 新增的
   // recallFusion/signalTransparency、issue #109 新增的实体抽取路由
   // entityExtractionProvider/entityExtractionModel/entityExtractionReasoning、
   // issue #127 新增的 summarize 五键、issue #126 新增的 sleepActionSet，
   // 以及 issue #125 新增的候选集三键、issue #17（v0.8.0 A1/A3）新增的
-  // scopeEnabled/strictScope），未覆盖时取 bundle 配置的解析默认值；
+  // scopeEnabled/strictScope、issue #194 新增的 resilientModelDownload），
+  // 未覆盖时取 bundle 配置的解析默认值；
   // dreamProvider/dreamModel 无 schema 默认值（Config({}) 解析为 undefined），
-  // 不编造给前端 → 53 - 2 = 51
-  assert.equal(Object.keys(data.effective).length, 51);
+  // 不编造给前端 → 54 - 2 = 52
+  assert.equal(Object.keys(data.effective).length, 52);
   assert.equal(data.effective.dreamSkipInvalid, true);
   assert.equal(data.effective.allowCrossTypeMerge, false);
   assert.equal(data.effective.dreamMinIntervalMinutes, 0);

package/test/inject-rotation.test.js

@@ -0,0 +1,161 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createVectorIndex } from "../src/vector-index.js";
+import { createInjector } from "../src/inject.js";
+import { createSettings } from "../src/settings.js";
+
+// 回归（issue #205）：注入位跨轮轮换。长会话（几十上百轮、注入位有限）中
+// 同一批条目在相邻轮次反复出现——报告者 15.5 小时实测 86 次注入 93% 重复，
+// 库总览一条 43/43 块全勤。新配置 injectRotationTurns（默认 0 = 关闭）：
+// 同一条记忆在最近 N 个「不同用户查询」轮次注入过后，本轮不再优先——
+// 新鲜者前置、不足按原序回填（槽位数不变）；同一查询的重复渲染（工具轮）
+// 不推进窗口；会话边界自动重置。
+
+function setup(configOver = {}) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const settings = createSettings(store.db);
+  const contexts = [];
+  const ctx = {
+    systemPrompt: {
+      context(def) {
+        contexts.push(def);
+        return () => {};
+      }
+    }
+  };
+  const config = { maxInjectedItems: 2, importanceThreshold: 3, ...configOver };
+  createInjector(ctx, service, settings, config);
+  // 注入块是 contexts[0]（memory），user-settings 是 contexts[1]
+  const render = (sessionId, query) => contexts[0].text({
+    agent: { session: { id: sessionId, snapshotEvents: () => query ? [
+      { type: "user/message", data: { source: { kind: "user" }, content: [{ type: "text", text: query }] } }
+    ] : [] } }
+  });
+  const titles = (text) => [...text.matchAll(/- \[([^\]]+)\] ([^（(]*)/g)].map((m) => m[2].trim());
+  return { store, service, render, titles };
+}
+
+function seedMemories(service, n = 4) {
+  const saved = [];
+  for (let i = 0; i < n; i++) {
+    saved.push(service.saveWithDedupe({
+      type: "preference",
+      title: `偏好条目${i}`,
+      content: `第 ${i} 条独立的用户偏好内容，主题互不相同`,
+      importance: 5
+    }).memory);
+  }
+  return saved;
+}
+
+test("#205: default (rotation off) repeats the same entries across turns", () => {
+  const { store, service, render, titles } = setup({});
+  seedMemories(service, 4);
+  const turn1 = titles(render("s1", "第一个问题"));
+  const turn2 = titles(render("s1", "第二个问题"));
+  assert.equal(turn1.length, 2);
+  assert.deepEqual(turn1, turn2, "rotation off → same entries repeat (current behavior)");
+  store.close();
+});
+
+test("#205: rotation=1 swaps out previously injected entries, slots stay full", () => {
+  const { store, service, render, titles } = setup({ injectRotationTurns: 1 });
+  seedMemories(service, 4);
+  const turn1 = titles(render("s1", "第一个问题"));
+  const turn2 = titles(render("s1", "第二个问题"));
+  assert.equal(turn2.length, 2, "slots stay full");
+  for (const t of turn1) {
+    assert.ok(!turn2.includes(t), `previously injected "${t}" must rotate out`);
+  }
+  store.close();
+});
+
+test("#205: entry becomes eligible again after leaving the window", () => {
+  const { store, service, render, titles } = setup({ injectRotationTurns: 1 });
+  seedMemories(service, 4);
+  const turn1 = titles(render("s1", "q1"));
+  const turn2 = titles(render("s1", "q2")); // window = [q1] → turn1 条目被换下
+  const turn3 = titles(render("s1", "q3")); // window = [q2] → turn1 条目重新有资格
+  for (const t of turn2) assert.ok(!turn3.includes(t), `"${t}" (injected at turn2) rotates out at turn3`);
+  for (const t of turn1) assert.ok(turn3.includes(t), `"${t}" (turn1) is fresh again at turn3`);
+  store.close();
+});
+
+test("#205: repeated renders within the same query do not advance the window", () => {
+  const { store, service, render, titles } = setup({ injectRotationTurns: 1 });
+  seedMemories(service, 4);
+  const turn1a = titles(render("s1", "q1"));
+  const turn1b = titles(render("s1", "q1")); // 同一查询：工具调用轮，不推进
+  assert.deepEqual(turn1a, turn1b, "same query renders identically (window not advanced)");
+  const turn2 = titles(render("s1", "q2"));
+  for (const t of turn1a) assert.ok(!turn2.includes(t), "rotation happens on the next query only");
+  store.close();
+});
+
+test("#205: a new session starts fresh", () => {
+  const { store, service, render, titles } = setup({ injectRotationTurns: 1 });
+  seedMemories(service, 4);
+  const turn1 = titles(render("s1", "q1"));
+  const other = titles(render("s2", "q1")); // 新会话：历史为空
+  assert.deepEqual(other, turn1, "session boundary resets rotation history");
+  store.close();
+});
+
+test("#205: backfill keeps slots full when fresh candidates run out", () => {
+  const { store, service, render, titles } = setup({ injectRotationTurns: 1 });
+  seedMemories(service, 2); // 候选恰等于槽位
+  const turn1 = titles(render("s1", "q1"));
+  const turn2 = titles(render("s1", "q2"));
+  assert.equal(turn2.length, 2, "stale entries backfill when nothing fresh remains");
+  assert.deepEqual(turn1, turn2, "no fresh candidates → original selection returned");
+  store.close();
+});
+
+// 回归（issue #205 补测，报告者读码发现）：轮换窗口需要 maxItems×(N+1) 张
+// 不同的牌，但候选池各有硬上限——语义路径截在 maxItems×2、合并层也是
+// maxItems×2。池子只有十来张时，窗口一开就把池子吃光、只剩回填：重复率的
+// 结构性下限由池子大小决定，轮换本身越不出箱子。修复：rotateWindow > 0 时
+// 池子按 maxItems×(N+1) 扩容（语义检索、bm25、合并层三处同步），无轮换时
+// 保持既有上限不变。旧测试样本（4 条记忆 + 注入位 2 = 恰好 maxItems×2）
+// 正好测不到这个边界——本用例刻意用 8 条 + 窗口 2 压过旧上限。
+test("#205 补测: semantic pool grows with the rotation window (no forced repeats)", () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const vectorIndex = createVectorIndex({ store });
+  service.setVectorIndex(vectorIndex);
+  const ids = [];
+  for (let i = 0; i < 8; i++) {
+    const theta = i * 0.1; // 角度递增 → 与 query [1,0,0] 的余弦严格递减
+    const m = service.saveWithDedupe({
+      type: "preference",
+      title: `条目${i}`,
+      content: `第 ${i} 条，主题互不相同`,
+      importance: 5
+    }).memory;
+    vectorIndex.saveEmbedding(m.id, [Math.cos(theta), Math.sin(theta), 0]);
+    ids.push(m.id);
+  }
+
+  const call = (rotate, rotateWindow) => service.injectCandidates({
+    query: "q",
+    queryVector: [1, 0, 0],
+    maxItems: 2,
+    threshold: 3,
+    rotate,
+    rotateWindow
+  }).map((m) => m.id);
+
+  const turn1 = call(null, 2);
+  assert.deepEqual(turn1, [ids[0], ids[1]], "baseline: top-2 by cosine");
+  const turn2 = call(new Set(turn1), 2);
+  assert.deepEqual(turn2, [ids[2], ids[3]], "window 1: next two fresh");
+  // 窗口 2 = 前两轮的并集（真实流程里注入层会把最近 N 轮的 id 合成一个集合）
+  const turn3 = call(new Set([...turn1, ...turn2]), 2);
+  // 旧上限（maxItems×2 = 4）下池子只有 m0..m3，第三轮 fresh 为空 → 只能回填
+  // m0/m1（强制重复）。池子扩到 6 后，m4/m5 仍在箱内可被轮换换上来。
+  assert.deepEqual(turn3, [ids[4], ids[5]], "window 2: pool grew with the window, no forced repeat");
+  store.close();
+});

package/test/local-embedder.test.js

@@ -59,6 +59,26 @@ test("LocalEmbedder init loads via injected engineFactory with cache_dir", async
   assert.equal(seen.options.device, "cpu");
 });
 
+test("LocalEmbedder init threads resilientModelDownload and logger to engineFactory", async () => {
+  // issue #194：开关与 logger 要能走到 defaultPipelineLoader（那里据此挂 env.fetch），
+  // 但不能混进 pipelineOptions 污染 transformers 的选项。
+  let seen = null;
+  const loader = async (_task, _model, options) => {
+    seen = options;
+    return makeFakeExtractor(512);
+  };
+  const logger = { info() {}, warn() {} };
+  const on = new LocalEmbedder({ cacheDir: "/tmp/model-cache", engineFactory: loader, resilientModelDownload: true, logger });
+  await on.init();
+  assert.equal(seen.resilientModelDownload, true);
+  assert.equal(seen.logger, logger);
+
+  seen = null;
+  const off = new LocalEmbedder({ engineFactory: loader });
+  await off.init();
+  assert.equal(seen.resilientModelDownload, false, "直连构造不显式给 true = 保持现状");
+});
+
 test("LocalEmbedder embed returns [n, dim] with mean pooling and chunking", async () => {
   const calls = [];
   const e = new LocalEmbedder({

package/test/runtime-model-fetch.test.js

@@ -0,0 +1,348 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { createHash } from "node:crypto";
+import { existsSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createResilientFetch, installResilientFetch } from "../src/runtime/model-fetch.js";
+
+// 模型文件取件层（issue #194）。transformers.js 下载几百 MB～1GB 的模型文件时，
+// undici socket 中途被重置（TypeError: terminated）会让整份下载作废重来；报告者实测
+// `curl -C -` 能稳定完成，说明服务端支持 Range。整条链都在本地 http 服务器上测：
+// 断流、续传、退避重试、进度百分比 —— 不依赖外网。
+
+/** 内容有变化的字节（0..250 循环）：任何丢块 / 重复块都会在逐字节比对里现形。 */
+function makeBody(size) {
+  const body = Buffer.alloc(size);
+  for (let i = 0; i < size; i++) body[i] = i % 251;
+  return body;
+}
+
+/**
+ * 只服务内存里那份字节的服务器。
+ * - `cutFirst`：该 URL 的首次请求只发一半就掐断（等 30ms 再 destroy，保证客户端真的收到过字节）；
+ * - `ignoreRange`：无视 Range 头，永远从 0 回全量 200 —— 逼出「续传被拒就从头再来」；
+ * - `seen` 记录收到的 Range 头与请求数。
+ */
+async function serve(files, { cutFirst = null, ignoreRange = false } = {}) {
+  const seen = { rangeHeader: null, requests: 0 };
+  let cutDone = false;
+  const server = createServer((req, res) => {
+    seen.requests++;
+    const body = files[req.url];
+    if (body === undefined) {
+      res.writeHead(404).end();
+      return;
+    }
+    const range = req.headers.range;
+    if (typeof range === "string") seen.rangeHeader = range;
+    const start = ignoreRange ? 0 : Number(/bytes=(\d+)-/.exec(range ?? "")?.[1] ?? 0);
+
+    if (cutFirst === req.url && !cutDone && start === 0) {
+      cutDone = true;
+      res.writeHead(200, {
+        "Content-Length": String(body.length),
+        ETag: '"immutable-etag"'
+      });
+      res.write(body.subarray(0, Math.floor(body.length / 2)));
+      // 立刻 destroy 会在客户端读到任何字节之前就断掉，那样就测不到「带着已收字节续传」。
+      setTimeout(() => res.destroy(), 30);
+      return;
+    }
+    if (start > 0) {
+      const rest = body.subarray(start);
+      res.writeHead(206, {
+        "Content-Range": `bytes ${start}-${body.length - 1}/${body.length}`,
+        ETag: '"immutable-etag"'
+      });
+      res.end(rest);
+      return;
+    }
+    res.writeHead(200, { "Content-Length": String(body.length), ETag: '"immutable-etag"' });
+    res.end(body);
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  return { server, base, seen, close: () => new Promise((resolve) => server.close(resolve)) };
+}
+
+function partDirFor() {
+  return mkdtempSync(join(tmpdir(), "mneme-mfetch-"));
+}
+
+function testFetcher(partDir, opts = {}) {
+  return createResilientFetch({ partDir, retryDelayMs: 1, idleTimeoutMs: 5000, ...opts });
+}
+
+test("model-fetch：中途 terminated 后用 Range 续传，最终字节与源逐字节一致", async () => {
+  const body = makeBody(65536);
+  const srv = await serve({ "/model.onnx": body }, { cutFirst: "/model.onnx" });
+  const dir = partDirFor();
+  try {
+    const fetchImpl = testFetcher(dir);
+    const res = await fetchImpl(`${srv.base}/model.onnx`);
+    assert.equal(res.status, 200, "对 transformers.js 必须以 200 形态出现（hub 会把非 200 当失败）");
+    const received = Buffer.from(await res.arrayBuffer());
+    assert.ok(received.equals(body), "续传拼出的字节必须与源完全一致");
+    // 关键证据：第二次请求带了 Range —— 是续传，不是从头再来。
+    assert.match(String(srv.seen.rangeHeader), /^bytes=\d+-$/, `续传请求应当带 Range，实际=${srv.seen.rangeHeader}`);
+  } finally {
+    await srv.close();
+  }
+});
+
+test("model-fetch：每次失败都带中断百分比；重试耗尽时错误信息说清断在哪", async () => {
+  const body = makeBody(100000);
+  // 服务器掐在固定位置：每次请求都只发 30% 就断。
+  const server = createServer((_req, res) => {
+    res.writeHead(200, { "Content-Length": String(body.length), ETag: '"x"' });
+    res.write(body.subarray(0, 30000));
+    setTimeout(() => res.destroy(), 20);
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  const dir = partDirFor();
+  try {
+    const events = [];
+    const fetchImpl = testFetcher(dir, { attempts: 2, onEvent: (e) => events.push(e) });
+    await assert.rejects(
+      () => fetchImpl(`${base}/big.bin`),
+      /中断于|30%/,
+      "最终错误必须带中断位置，让用户能区分网络问题与磁盘问题"
+    );
+    const fail = events.filter((e) => e.type === "fail");
+    assert.ok(fail.length >= 1, "每次失败都应发 fail 事件");
+    assert.equal(fail.at(-1).percent, 30, `断在 30%%（30000/100000），实际=${fail.at(-1).percent}`);
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+  }
+});
+
+test("model-fetch：If-Range 失配（服务端内容已换）时回 200，断点作废整份重来，不产出拼接损坏", async () => {
+  const v1 = makeBody(65536);
+  const v2 = Buffer.from(v1.map((b) => (b + 7) % 251));
+  let broken = false;
+  const server = createServer((req, res) => {
+    const range = Number(/bytes=(\d+)-/.exec(req.headers.range ?? "")?.[1] ?? 0);
+    // If-Range 与当前内容不符（或没带）：真实服务器会回 200 全量 —— 内容换过了。
+    if (req.headers["if-range"] !== undefined && req.headers["if-range"] !== '"v2"') {
+      broken = true;
+      res.writeHead(200, { "Content-Length": String(v2.length), ETag: '"v2"' });
+      res.end(v2);
+      return;
+    }
+    if (range > 0 && !broken) {
+      res.writeHead(206, {
+        "Content-Range": `bytes ${range}-${v1.length - 1}/${v1.length}`,
+        ETag: '"v1"'
+      });
+      res.end(v1.subarray(range));
+      return;
+    }
+    if (!broken) {
+      res.writeHead(200, { "Content-Length": String(v1.length), ETag: '"v1"' });
+      res.write(v1.subarray(0, Math.floor(v1.length / 2)));
+      setTimeout(() => res.destroy(), 30);
+      return;
+    }
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  const dir = partDirFor();
+  try {
+    const events = [];
+    const fetchImpl = testFetcher(dir, { attempts: 2, onEvent: (e) => events.push(e) });
+    const res = await fetchImpl(`${base}/model.onnx`);
+    const body = Buffer.from(await res.arrayBuffer());
+    assert.ok(events.some((e) => e.type === "restart" && e.reason === "range-rejected"), "应发 range-rejected 重来事件");
+    assert.ok(body.equals(v2), "最终字节必须是新内容整份，而不是 v1 断点拼 v2 的损坏物");
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+  }
+});
+
+test("model-fetch：服务器续传位置与断点对不上时清掉断点重来（拼错比失败更糟）", async () => {
+  const body = makeBody(65536);
+  let cutDone = false;
+  const server = createServer((req, res) => {
+    const range = req.headers.range;
+    if (typeof range === "string") {
+      // 故意回一个与断点无关的 206（从 0 开始）：客户端必须识别出偏移不一致。
+      res.writeHead(206, { "Content-Range": `bytes 0-${body.length - 1}/${body.length}`, ETag: '"x"' });
+      res.end(body);
+      return;
+    }
+    if (!cutDone) {
+      cutDone = true;
+      res.writeHead(200, { "Content-Length": String(body.length), ETag: '"x"' });
+      res.write(body.subarray(0, 30000));
+      setTimeout(() => res.destroy(), 20);
+      return;
+    }
+    res.writeHead(200, { "Content-Length": String(body.length), ETag: '"x"' });
+    res.end(body);
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  const dir = partDirFor();
+  try {
+    const events = [];
+    const fetchImpl = testFetcher(dir, { attempts: 3, onEvent: (e) => events.push(e) });
+    const res = await fetchImpl(`${base}/model.onnx`);
+    const received = Buffer.from(await res.arrayBuffer());
+    assert.ok(events.some((e) => e.type === "restart" && e.reason === "offset-mismatch"));
+    assert.ok(received.equals(body), "重置后重新下载的整份字节必须正确");
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+  }
+});
+
+test("model-fetch：416（断点越过文件末尾）时重置断点重试，而不是把重试次数烧完", async () => {
+  const body = makeBody(65536);
+  const server = createServer((req, res) => {
+    const start = Number(/bytes=(\d+)-/.exec(req.headers.range ?? "")?.[1] ?? -1);
+    if (start >= body.length) {
+      // 诚实的 416：Range 起点越过源文件末尾（断点来自被替换前的旧文件）。
+      res.writeHead(416, { "Content-Range": `bytes */${body.length}` });
+      res.end();
+      return;
+    }
+    if (start > 0) {
+      res.writeHead(206, { "Content-Range": `bytes ${start}-${body.length - 1}/${body.length}`, ETag: '"x"' });
+      res.end(body.subarray(start));
+      return;
+    }
+    res.writeHead(200, { "Content-Length": String(body.length), ETag: '"x"' });
+    res.end(body);
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  const url = `${base}/model.onnx`;
+  const dir = partDirFor();
+  try {
+    // 预置一份比源文件还大的断点（70000 > 65536）+ 它的 etag。
+    const partPath = join(dir, createHash("sha256").update(url).digest("hex"));
+    writeFileSync(partPath, Buffer.alloc(70000, 1));
+    writeFileSync(`${partPath}.meta`, '"old"\n');
+    const events = [];
+    const fetchImpl = testFetcher(dir, { attempts: 2, onEvent: (e) => events.push(e) });
+    const res = await fetchImpl(url);
+    const received = Buffer.from(await res.arrayBuffer());
+    assert.ok(events.some((e) => e.type === "restart" && e.reason === "range-not-satisfiable"));
+    assert.ok(received.equals(body), "重置后重新下载的整份字节必须正确");
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+  }
+});
+
+test("model-fetch：连接僵死时被空闲看门狗掐断并重试，而不是永远挂着", async () => {
+  const body = makeBody(65536);
+  let stalled = false;
+  const server = createServer((_req, res) => {
+    if (!stalled) {
+      stalled = true;
+      res.writeHead(200, { "Content-Length": String(body.length) });
+      res.write(body.subarray(0, 10));
+      return; // 永远不 end：僵死的 socket。
+    }
+    res.writeHead(200, { "Content-Length": String(body.length) });
+    res.end(body);
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  const dir = partDirFor();
+  try {
+    const events = [];
+    const started = Date.now();
+    const fetchImpl = testFetcher(dir, { attempts: 2, idleTimeoutMs: 150, retryDelayMs: 1, onEvent: (e) => events.push(e) });
+    const res = await fetchImpl(`${base}/model.onnx`);
+    const received = Buffer.from(await res.arrayBuffer());
+    assert.ok(Date.now() - started < 5000, "应当被看门狗及时掐断，而不是挂住");
+    assert.ok(events.some((e) => e.type === "fail" && /空闲/.test(e.error)), `失败事件应写明空闲超时，实际=${events.map((e) => e.error)}`);
+    assert.ok(received.equals(body));
+  } finally {
+    server.closeAllConnections();
+    await new Promise((resolve) => server.close(resolve));
+  }
+});
+
+test("model-fetch：服务端干净地提前关流（字节没给够）被查出并续传补齐", async () => {
+  const body = makeBody(100000);
+  const server = createServer((req, res) => {
+    const range = Number(/bytes=(\d+)-/.exec(req.headers.range ?? "")?.[1] ?? 0);
+    if (range > 0) {
+      res.writeHead(206, { "Content-Range": `bytes ${range}-${body.length - 1}/${body.length}`, ETag: '"x"' });
+      res.end(body.subarray(range));
+      return;
+    }
+    res.writeHead(200, { "Content-Length": String(body.length), ETag: '"x"' });
+    res.end(body.subarray(0, 30000)); // 声明 100000 只给 30000，然后"正常"结束。
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  const dir = partDirFor();
+  try {
+    const fetchImpl = testFetcher(dir, { attempts: 2 });
+    const res = await fetchImpl(`${base}/model.onnx`);
+    const received = Buffer.from(await res.arrayBuffer());
+    assert.ok(received.equals(body), "缺的字节要从断点补齐");
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+  }
+});
+
+test("model-fetch：非 GET 与抢不到锁的请求原样直通，不落盘、不带 Range", async () => {
+  const dir = partDirFor();
+  const calls = [];
+  const stub = (input, init) => {
+    calls.push({ input: String(input), init: init ?? null });
+    return new Response("raw", { status: 200, headers: { "content-length": "3" } });
+  };
+  const fetchImpl = testFetcher(dir, { fetchImpl: stub });
+  await fetchImpl("https://example.com/meta", { method: "HEAD" });
+  // 锁名与被测实现一致：<sha256(url)>.lock；新鲜的锁 = 别的进程正在写。
+  const url = "https://example.com/model.onnx";
+  const locked = join(dir, `${createHash("sha256").update(url).digest("hex")}.lock`);
+  writeFileSync(locked, "9999");
+  await fetchImpl(url);
+  assert.equal(calls.length, 2, "两个请求都应直通底层 fetch");
+  assert.equal(calls[0].init.method, "HEAD");
+  assert.equal(calls[1].init, null, "直通不应改写调用参数");
+  assert.deepEqual(readdirSync(dir), [`${createHash("sha256").update(url).digest("hex")}.lock`], "直通不该产生断点文件");
+  rmSync(locked, { force: true });
+});
+
+test("model-fetch：响应体消费完后断点文件、meta 与锁都清理干净", async () => {
+  const body = makeBody(65536);
+  const srv = await serve({ "/model.onnx": body }, { cutFirst: "/model.onnx" });
+  const dir = partDirFor();
+  try {
+    const fetchImpl = testFetcher(dir);
+    const res = await fetchImpl(`${srv.base}/model.onnx`);
+    await res.arrayBuffer(); // 消费完 = 下游（FileCache.put）拿完字节了。
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(readdirSync(dir).length, 0, `断点目录应已清空，实际=${readdirSync(dir)}`);
+  } finally {
+    await srv.close();
+  }
+});
+
+test("installResilientFetch：开关关 = env 一字不动；开 = env.fetch 换成弹性实现", async () => {
+  const envOff = {};
+  assert.equal(installResilientFetch(envOff, { enabled: false }), false);
+  assert.equal(envOff.fetch, undefined, "关闭时不许碰 env（默认保持现状的出口）");
+  assert.equal(installResilientFetch(null, { enabled: true }), false, "env 缺席时不安装");
+
+  const cacheRoot = mkdtempSync(join(tmpdir(), "mneme-install-"));
+  const envOn = {};
+  assert.equal(installResilientFetch(envOn, { enabled: true, cacheDir: cacheRoot, fetchImpl: () => new Response("x") }), true);
+  assert.equal(typeof envOn.fetch, "function");
+  assert.ok(existsSync(join(cacheRoot, ".mneme-partial")), "断点目录建在模型缓存旁");
+
+  // 装上的 fetch 是能干活的：小文件直通下载 + 返回规范 200。
+  const res = await envOn.fetch("https://example.com/tiny.bin");
+  assert.equal(res.status, 200);
+  assert.equal(await res.text(), "x");
+});
+