@modusensus/dsh-mneme 0.8.1 → 0.8.3

package/test/llm-message-source.test.js

@@ -0,0 +1,177 @@
+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";
+import { createSummarizer } from "../src/summarize.js";
+import { runSleep } from "../src/dream/sleep.js";
+import { extractEntities } from "../src/entities/extractor.js";
+import { createVectorIndex } from "../src/vector-index.js";
+
+// 回归：dsh-llm 的消息契约要求每条消息带 source。provider 适配器会直接读
+// message.source.kind 来区分用户内容与工具结果（例如
+// @mars-sea/dsh-commandcode-provider 的 messagesToCC），缺字段时请求在序列化
+// 阶段就抛 "Cannot read properties of undefined (reading 'kind')"，四条 LLM 管线
+// （dream / sleep / summarize / entity extraction）全军覆没、耗时 0ms。
+// 这里用同等严格的桩驱动真实管线，任何新加的消息漏了 source 都会失败。
+function assertMessageSources(options) {
+  for (const message of options.messages ?? []) {
+    assert.equal(
+      message.source?.kind,
+      "plugin",
+      `LLM 消息缺 source（provider 会抛 TypeError）: ${message.role} / ${String(message.content?.[0]?.text ?? "").slice(0, 40)}`
+    );
+  }
+}
+
+const logger = { warn: () => {}, info: () => {} };
+
+function makeService() {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  return { store, service };
+}
+
+// dsh-llm chunk 形状与真实 provider 对齐：文本增量 + 终止 chunk。
+function reply(text, finish = { reason: { kind: "stop" } }) {
+  return (async function* () {
+    yield { type: "text-delta", index: 0, text };
+    yield { type: "finish", ...finish };
+  })();
+}
+
+// ---------------------------------------------------------------- dream
+
+test("dream: consolidation and summary messages carry source", async () => {
+  const { store, service } = makeService();
+  service.saveWithDedupe({ type: "project", title: "主题01", content: "规范内容", importance: 5 });
+  service.saveWithDedupe({ type: "project", title: "主题01·变体", content: "旧变体", importance: 3 });
+
+  const calls = [];
+  const ctx = {
+    logger,
+    agentDefaultModel: { currentSelection: () => ({ provider: "mock", model: "source-model" }) },
+    llm: {
+      async *stream(options) {
+        calls.push(options);
+        assertMessageSources(options);
+        const userText = options.messages.find((m) => m.role === "user")?.content?.[0]?.text ?? "";
+        yield* reply(userText.startsWith("id=") ? "[]" : "记忆库总览：已巩固。");
+      }
+    }
+  };
+
+  const dream = createDreamScheduler({ onRun: () => Promise.resolve({ ok: true, skipped: true }) });
+  const run = await dream.runDream(ctx, service, {});
+  assert.equal(run.ok, true, "dream run succeeds against the strict provider stub");
+  assert.ok(calls.some((c) => c.purpose === "compaction"), "consolidation called the LLM");
+  assert.ok(calls.length >= 2, "consolidation + summary both called");
+  store.close();
+});
+
+// ---------------------------------------------------------------- summarize
+
+test("summarize: distilled transcript and prompt messages carry source", async () => {
+  const { store, service } = makeService();
+  const events = [];
+  const calls = [];
+  const ctx = {
+    on(name, fn) {
+      events.push({ name, fn });
+      return () => {};
+    },
+    logger,
+    llm: {
+      stream(options) {
+        calls.push(options);
+        assertMessageSources(options);
+        return reply("[]", { kind: "ok" });
+      }
+    }
+  };
+  createSummarizer(ctx, service, { autoSummarize: true });
+
+  const handler = events.find((e) => e.name === "session/event").fn;
+  const session = {
+    id: "s-source",
+    requestHeader: () => ({ config: { provider: "mock", model: "source-model" } }),
+    events: [
+      { type: "user/message", data: { source: { kind: "user" }, content: [{ type: "text", text: "帮我选型" }] } },
+      { seq: 2, type: "turn/end" }
+    ]
+  };
+  await handler(session, { seq: 2, type: "turn/end" });
+
+  assert.equal(calls.length, 1, "summarization called the LLM");
+  store.close();
+});
+
+// ---------------------------------------------------------------- sleep
+
+test("sleep: conflict and pattern messages carry source", async () => {
+  const { store, service } = makeService();
+  const vectorIndex = createVectorIndex({ store });
+  const embedder = {
+    embedSingle: async () => [1, 0, 0],
+    embed: async () => [1, 0, 0],
+    schedule: () => {},
+    modelHash: "mock#1",
+    dimension: 3
+  };
+  service.setEmbedder(embedder);
+  service.setVectorIndex(vectorIndex);
+  // 冲突候选要在向量索引里真有向量（同 sleep.test.js 的 seedConflictPair）；
+  // 同时给 pattern 阶段留下 2 条素材。
+  const a = service.saveWithDedupe({ type: "project", title: "主题X", content: "内容A 关于主题X", importance: 3 }).memory;
+  const b = service.saveWithDedupe({ type: "project", title: "主题X副本", content: "内容B 关于主题X", importance: 3 }).memory;
+  vectorIndex.saveEmbedding(a.id, [1, 0, 0]);
+  vectorIndex.saveEmbedding(b.id, [1, 0, 0]);
+
+  const calls = [];
+  const ctx = {
+    logger,
+    agentDefaultModel: { currentSelection: () => ({ provider: "mock", model: "sleep-model" }) },
+    llm: {
+      async *stream(options) {
+        calls.push(options);
+        assertMessageSources(options);
+        yield* reply("[]");
+      }
+    }
+  };
+  const config = {
+    sleepModeEnabled: true,
+    sleepIdleMinutes: 5,
+    sleepMinIntervalHours: 8,
+    sleepConflictStrictness: "normal",
+    sleepArchiveDays: 30,
+    sleepCompressDays: 90,
+    sleepPatternMinMemories: 2,
+    sleepMaxPatternPerRun: 3
+  };
+  const result = await runSleep(ctx, service, config, logger, { embedder, vectorIndex }, null);
+
+  assert.ok(calls.some((c) => c.purpose === "sleep-conflict"), "conflict phase called the LLM");
+  assert.ok(calls.some((c) => c.purpose === "sleep-pattern"), "pattern phase called the LLM");
+  assert.ok(result.runId, "sleep run produced a receipt");
+  store.close();
+});
+
+// ---------------------------------------------------------------- entity extraction
+
+test("entity extraction: messages handed to the llm adapter carry source", async () => {
+  const { store, service } = makeService();
+  const memory = service.saveWithDedupe({ type: "project", title: "协作", content: "Alpha 与 Beta 一起干活", importance: 3 }).memory;
+
+  const calls = [];
+  const callLLM = async (messages) => {
+    calls.push(messages);
+    assertMessageSources({ messages });
+    return "[]";
+  };
+
+  await extractEntities(memory, { store, config: {}, callLLM, logger });
+
+  assert.equal(calls.length, 1, "extraction called the LLM adapter");
+  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/reranker-single-logit.test.js

@@ -0,0 +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();
+});

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");
+});
+

package/test/skip-invalid-restore.test.js

@@ -151,17 +151,19 @@ test("validateDecisions skipInvalid: conflict without a distinct winner/loser is
 
 // ------------------------------------------------------- skipInvalid 与全局闸门
 
-test("validateDecisions skipInvalid: valid subset below the coverage floor still rejects the whole batch", () => {
+test("validateDecisions skipInvalid: valid subset below the coverage floor degrades (Issue #104 方向 1)", () => {
   const snap = makeSnap(["p", "j", "x"]);
   const decisions = [
     { action: "archive", ids: ["p"], reason: "stale" },
     { action: "merge", ids: ["p", "j"], keepSource: "p", title: "跨类型", content: "m", importance: 4 }
   ];
-  const { ok, errors, skipped } = validateDecisions(decisions, snap, { skipInvalid: true });
-  assert.equal(ok, false, "skip does not bypass the coverage floor");
+  const { ok, errors, skipped, coverageShortfall } = validateDecisions(decisions, snap, { skipInvalid: true });
+  assert.equal(ok, true, "valid subset applies — shortfall degrades instead of rejecting");
+  assert.deepEqual(errors, []);
   assert.equal(skipped.length, 1);
-  assert.ok(errors.some((e) => e.includes("coverage")), "coverage error present");
-  assert.equal(decisions.length, 2, "rejected batch left untouched (splice only on the success path)");
+  assert.match(String(coverageShortfall), /coverage/, "shortfall reason surfaced for audit");
+  // claimed {p} = 1/3 = 33% < 50%；j/x 隐式 keep 补齐
+  assert.deepEqual(decisions.map((d) => d.action), ["archive", "keep", "keep"]);
 });
 
 test("validateDecisions skipInvalid: updates skipped for other reasons do not count toward the update cap", () => {