@modusensus/dsh-mneme 0.7.30 → 0.7.32

package/test/runtime-loader.test.js

@@ -0,0 +1,237 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describeLocalRuntime, loadTransformers, publicRuntimeStatus, resolveRuntimeEntry } from "../src/runtime/loader.js";
+import { TRANSFORMERS_ENTRY, defaultRuntimeDir, payloadDir, payloadId } from "../src/runtime/layout.js";
+
+// 三层解析（issue #131 / PR-A）。这里守的是两条容易出错的承诺：
+//   ① 自管运行时优先，且能用绝对 file URL 真的加载起来；
+//   ② 降级路径不许静默 —— 「自管那份坏了」和「本机根本没有」必须能分辨。
+// 第 ② 层（宿主裸 specifier）是 PR-A 期间老用户不断线的保障，必须真的会退回去。
+
+/** 造一份结构合法的 payload。 */
+function makePayload(runtimeDir, { version = "4.2.0", platform = "win32", arch = "x64", withEntry = true } = {}) {
+  const dir = payloadDir(runtimeDir, payloadId({ version, platform, arch: "x64" }));
+  const write = (rel, body) => {
+    const full = join(dir, rel);
+    mkdirSync(join(full, ".."), { recursive: true });
+    writeFileSync(full, body);
+  };
+  for (const name of ["@huggingface/transformers", "onnxruntime-node", "sharp"]) {
+    write(join("node_modules", name, "package.json"), JSON.stringify({ name, version: name === "@huggingface/transformers" ? version : "1.0.0" }));
+  }
+  if (withEntry) write(TRANSFORMERS_ENTRY, "export const source = 'runtime';\n");
+  mkdirSync(join(dir, "node_modules", "onnxruntime-node", "bin", "napi-v6", platform, arch), { recursive: true });
+  return dir;
+}
+
+const emptyRuntime = () => mkdtempSync(join(tmpdir(), "mneme-loader-rt-"));
+
+test("第 ① 层：自管运行时可用时优先用它，并报出来源与 payloadId", async () => {
+  const runtimeDir = emptyRuntime();
+  const dir = makePayload(runtimeDir);
+  const loaded = await loadTransformers({
+    runtimeDir,
+    platform: "win32", arch: "x64",
+    importModule: async (specifier) => ({ loadedFrom: specifier })
+  });
+  assert.equal(loaded.source, "runtime");
+  assert.equal(loaded.payloadId, "transformers-4.2.0-node-win32-x64");
+  assert.equal(loaded.version, "4.2.0");
+  assert.ok(loaded.entryUrl.startsWith("file:///"), "必须是绝对 file URL，否则内部裸导入解析不到同目录的包");
+  // 断言「URL 反解回来就是那个入口文件」，而不是拿 URL 字符串去 includes 一个 OS 路径字符串：
+  // 后者会被 pathToFileURL 的百分号编码打败（路径含空格等字符时必误报，实测 CI Windows 上就挂了）。
+  assert.equal(
+    fileURLToPath(loaded.entryUrl),
+    join(dir, TRANSFORMERS_ENTRY),
+    `entryUrl=${loaded.entryUrl} dir=${dir}`
+  );
+});
+
+test("第 ② 层：没有自管运行时时退回宿主裸 specifier（PR-A 期间老用户靠这层不断线）", async () => {
+  const seen = [];
+  const loaded = await loadTransformers({
+    runtimeDir: emptyRuntime(),
+    importModule: async (specifier) => {
+      seen.push(specifier);
+      return { loadedFrom: specifier };
+    }
+  });
+  assert.equal(loaded.source, "host");
+  assert.deepEqual(seen, ["@huggingface/transformers"]);
+});
+
+test("降级不许静默：自管那份坏了要回调出来，同时仍然退到宿主", async () => {
+  const runtimeDir = emptyRuntime();
+  makePayload(runtimeDir);
+  const failures = [];
+  const loaded = await loadTransformers({
+    runtimeDir,
+    platform: "win32", arch: "x64",
+    onFailure: (m) => failures.push(m),
+    importModule: async (specifier) => {
+      if (specifier.startsWith("file:///")) throw new Error("Cannot find package 'onnxruntime-node'");
+      return { loadedFrom: "host" };
+    }
+  });
+  assert.equal(loaded.source, "host");
+  assert.equal(failures.length, 1);
+  assert.match(failures[0], /自管运行时 transformers-4.2.0-node-win32-x64 加载失败/);
+  assert.match(failures[0], /onnxruntime-node/);
+});
+
+test("第 ② 层版本门禁：宿主装到 v5 就不静默使用，落到第 ③ 层的可操作提示", async () => {
+  await assert.rejects(
+    () =>
+      loadTransformers({
+        runtimeDir: emptyRuntime(),
+        importModule: async () => ({ env: { version: "5.0.0" } })
+      }),
+    (error) => {
+      assert.equal(error.code, "MNEME_RUNTIME_UNAVAILABLE");
+      // transformers 把版本挂在 env 上（顶层没有 version，实测 4.2.0 的 Node 构建），
+      // 所以门禁两个位置都看；越界时那句原因要能被人看懂。
+      assert.match(error.message, /版本越界：5\.0\.0/);
+      return true;
+    }
+  );
+});
+
+test("第 ② 层版本门禁：区间内放行并报出版本；拿不到版本时不拦", async () => {
+  const inRange = await loadTransformers({
+    runtimeDir: emptyRuntime(),
+    importModule: async () => ({ env: { version: "4.2.0" } })
+  });
+  assert.equal(inRange.source, "host");
+  assert.equal(inRange.version, "4.2.0");
+
+  // 拿不到版本 = 无法判断，不拦：否则这层会对某些打包形态整体失效，
+  // 而它正是老用户收编完成前的不断线保障。
+  const unknown = await loadTransformers({
+    runtimeDir: emptyRuntime(),
+    importModule: async () => ({})
+  });
+  assert.equal(unknown.source, "host");
+  assert.equal(unknown.version, undefined);
+});
+
+test("第 ③ 层：两层都没有时给出可操作提示，并列出每一层为什么失败", async () => {
+  const runtimeDir = emptyRuntime();
+  makePayload(runtimeDir);
+  await assert.rejects(
+    () =>
+      loadTransformers({
+        runtimeDir,
+        platform: "win32", arch: "x64",
+        importModule: async (specifier) => {
+          throw new Error(specifier.startsWith("file:///") ? "payload broken" : "Cannot find module");
+        }
+      }),
+    (error) => {
+      assert.equal(error.code, "MNEME_RUNTIME_UNAVAILABLE");
+      assert.match(error.message, /本地推理运行时不可用/);
+      assert.match(error.message, /mneme-runtime\.mjs/, "提示要指向真实存在的入口，而不是一个不存在的子命令");
+      // 提示里给的入口脚本必须真的存在。这条踩过：提示指向了一个并不存在的子命令，
+      // 用户照着敲只会得到「command not found」，比不给提示更糟。
+      const script = /node "([^"]+mneme-runtime\.mjs)"/.exec(error.message);
+      assert.ok(script, "提示要带出入口脚本的绝对路径");
+      assert.ok(existsSync(script[1]), `提示指向的脚本不存在：${script[1]}`);
+      assert.match(error.message, /adopt --from/, "要给出可执行的下一步，而不是一句 module not found");
+      assert.match(error.message, /payload broken/, "自管那层的失败原因要带出来");
+      assert.match(error.message, /Cannot find module/, "宿主那层的失败原因也要带出来");
+      assert.equal(error.failures.length, 2);
+      return true;
+    }
+  );
+});
+
+test("resolveRuntimeEntry：跳过结构不合法的 payload，取到可用的那份；全不合规则返回 null", () => {
+  const runtimeDir = emptyRuntime();
+  makePayload(runtimeDir, { version: "4.2.0", withEntry: false }); // 缺入口 → 不合法
+  assert.equal(resolveRuntimeEntry({ runtimeDir, platform: "win32", arch: "x64" }), null, "结构不合法的不能被选中");
+
+  makePayload(runtimeDir, { version: "4.3.0" });
+  const picked = resolveRuntimeEntry({ runtimeDir, platform: "win32", arch: "x64" });
+  assert.equal(picked.payloadId, "transformers-4.3.0-node-win32-x64");
+  assert.equal(picked.version, "4.3.0");
+});
+
+test("resolveRuntimeEntry：运行时根目录不存在时返回 null（不是抛错）", () => {
+  assert.equal(resolveRuntimeEntry({ runtimeDir: join(tmpdir(), "mneme-nope-" + Date.now()), platform: "win32", arch: "x64" }), null);
+});
+
+test("publicRuntimeStatus：只放行白名单字段，绝对路径与原始错误一律不进 HTTP", () => {
+  // /api/dsh-mneme/semantic 是刻意不鉴权的只读端点。完整状态里有 runtimeDir（绝对路径）、
+  // hint（内嵌脚本绝对路径）以及 reason/reasons（原始错误文本里带完整文件路径），
+  // 发给任何能连上该端口的人就是信息泄漏（CWE-200）。用精确白名单守住这件事：
+  // 将来谁往里加字段，这条测试就会红。
+  const EXPECTED = ["functional", "integrity", "materialize", "payloadId", "procedure", "status", "version"];
+
+  const missing = describeLocalRuntime({ runtimeDir: join(tmpdir(), `mneme-secret-${Date.now()}`), platform: "win32", arch: "x64" });
+  const pubMissing = publicRuntimeStatus(missing);
+  assert.deepEqual(Object.keys(pubMissing).sort(), EXPECTED);
+  assert.equal(pubMissing.status, "missing");
+  // 完整状态里确实带着这些敏感字段 —— 否则这条测试就没在测东西。
+  assert.ok(missing.runtimeDir.startsWith(tmpdir()));
+  assert.ok(missing.hint.includes("mneme-runtime.mjs"));
+
+  const runtimeDir = emptyRuntime();
+  const dir = makePayload(runtimeDir);
+  writeFileSync(join(dir, "mneme-runtime.json"), JSON.stringify({ procedure: "adopted", materialize: { mode: "hardlink" } }));
+  const pubAvailable = publicRuntimeStatus(describeLocalRuntime({ runtimeDir, platform: "win32", arch: "x64" }));
+  assert.deepEqual(Object.keys(pubAvailable).sort(), EXPECTED);
+  assert.equal(pubAvailable.status, "available");
+  assert.equal(pubAvailable.payloadId, "transformers-4.2.0-node-win32-x64");
+  assert.equal(pubAvailable.procedure, "adopted");
+  assert.equal(pubAvailable.materialize, "hardlink");
+  // 整份投影里不能出现本机路径的任何形态。
+  const text = JSON.stringify(pubAvailable);
+  assert.equal(text.includes(runtimeDir), false);
+  assert.equal(text.includes(runtimeDir.replace(/\\/g, "/")), false);
+});
+
+test("describeLocalRuntime：可用时报出 payload 与来源，且不假装验过", () => {
+  const runtimeDir = emptyRuntime();
+  const dir = makePayload(runtimeDir);
+  // 收编来的 payload 会带一份清单，验证来源/物化方式确实被带出来。
+  writeFileSync(
+    join(dir, "mneme-runtime.json"),
+    JSON.stringify({ procedure: "adopted", materialize: { mode: "hardlink" } })
+  );
+  const report = describeLocalRuntime({ runtimeDir, platform: "win32", arch: "x64" });
+  assert.equal(report.status, "available");
+  assert.equal(report.payloadId, "transformers-4.2.0-node-win32-x64");
+  assert.equal(report.version, "4.2.0");
+  assert.equal(report.procedure, "adopted");
+  assert.equal(report.materialize, "hardlink");
+  // 结构检查是 GET 端点能负担的；功能验证要真加载原生模块跑推理，状态探针不做 ——
+  // 如实说「不知道」，而不是把「文件都在」说成「验过了」。
+  assert.equal(report.functional, "unknown");
+  assert.equal(report.integrity, "unverified");
+  assert.match(report.hint, /mneme-runtime\.mjs/);
+});
+
+test("describeLocalRuntime：没有 payload 时报 missing，而不是报坏掉", () => {
+  const report = describeLocalRuntime({ runtimeDir: emptyRuntime(), platform: "win32", arch: "x64" });
+  assert.equal(report.status, "missing");
+});
+
+test("describeLocalRuntime：有目录但缺件时报 broken 并点名缺了什么", () => {
+  const runtimeDir = emptyRuntime();
+  makePayload(runtimeDir, { withEntry: false });
+  const report = describeLocalRuntime({ runtimeDir, platform: "win32", arch: "x64" });
+  assert.equal(report.status, "broken");
+  assert.deepEqual(report.missing, [TRANSFORMERS_ENTRY]);
+});
+
+test("describeLocalRuntime：空 runtimeDir 走默认目录，不能把空串当相对路径", () => {
+  // 配置项 runtimeDir 的默认值就是空串。原样传下去 readdirSync("") 会失败，
+  // 「没配」会被误报成「坏了」—— 这条守的就是它。
+  const report = describeLocalRuntime({ runtimeDir: "  ", platform: "win32", arch: "x64" });
+  assert.equal(report.runtimeDir, defaultRuntimeDir());
+  assert.ok(isAbsolute(report.runtimeDir));
+  assert.notEqual(report.status, "unreadable");
+});

package/test/runtime-manifest.test.js

@@ -0,0 +1,158 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  COVERED_PLATFORMS,
+  build,
+  closureFromLockfile,
+  isExcluded,
+  nameOfPath,
+  packagesForPlatform,
+  relOfPath,
+  resolveCandidates
+} from "../scripts/build-runtime-manifest.mjs";
+import { REQUIRED_PACKAGES, payloadId } from "../src/runtime/layout.js";
+
+// PR-C 的清单层，守四件事：
+//   ① 剔除规则按**子树**生效 —— 只按包名会漏掉 onnxruntime-web/node_modules/... 这类嵌套条目，
+//      而那个位置根本不会被取回来（第一版真踩过）。
+//   ② 从 lockfile 解析依赖的走位正确（Node 的向上查找语义；嵌套重复版本就靠它）。
+//   ③ 清单**平台无关**：六个常见平台都能过滤出完整的必需包，并各拿到自己的平台二进制。
+//      这是「mac / linux 用户不会卡住」的唯一结构性保证 —— 我在本机没法真跑那些平台，
+//      至少要钉住「过滤之后是完整的」。
+//   ④ 已提交的清单必须就是生成器的输出：它随包发布，漂移了就等于发了一份错的哈希。
+
+const ROOT = fileURLToPath(new URL("..", import.meta.url));
+
+test("isExcluded：按包名与子树一起判定，嵌套条目不能漏", () => {
+  assert.equal(isExcluded({ name: "onnxruntime-web", rel: "onnxruntime-web" }), true);
+  // 这一条就是漏网的形态：包名不是被剔除的那个，但位置在被剔除包的子树里。
+  assert.equal(
+    isExcluded({ name: "onnxruntime-common", rel: "onnxruntime-web/node_modules/onnxruntime-common" }),
+    true
+  );
+  // 同名但位于别处（顶层那份）必须保留。
+  assert.equal(isExcluded({ name: "onnxruntime-common", rel: "onnxruntime-common" }), false);
+  assert.equal(isExcluded({ name: "onnxruntime-node", rel: "onnxruntime-node" }), false);
+});
+
+test("nameOfPath / relOfPath：取最后一段 node_modules 之后的部分", () => {
+  assert.equal(nameOfPath("node_modules/@huggingface/transformers"), "@huggingface/transformers");
+  assert.equal(nameOfPath("node_modules/a/node_modules/b"), "b");
+  assert.equal(relOfPath("node_modules/a/node_modules/b"), "a/node_modules/b");
+  assert.equal(relOfPath("node_modules/sharp"), "sharp");
+});
+
+test("resolveCandidates：按 Node 语义由近到远，最后兜底到根部", () => {
+  assert.deepEqual(resolveCandidates("node_modules/a", "x"), ["node_modules/a/node_modules/x", "node_modules/x"]);
+  assert.deepEqual(resolveCandidates("node_modules/a/node_modules/b", "x"), [
+    "node_modules/a/node_modules/b/node_modules/x",
+    "node_modules/a/node_modules/x",
+    "node_modules/x"
+  ]);
+});
+
+test("closureFromLockfile：被剔除包的（孤儿）依赖不会再进闭包", () => {
+  // 这正是第一版的真实缺陷：按包名剔除了 onnxruntime-web，却把它那 16 个传递依赖留在了清单里。
+  const lock = {
+    packages: {
+      "node_modules/@huggingface/transformers": {
+        version: "4.2.0",
+        integrity: "sha512-T",
+        dependencies: { dep: "^1.0.0" }
+      },
+      "node_modules/dep": { version: "1.0.0", integrity: "sha512-D", dependencies: { "onnxruntime-web": "^1.0.0" } },
+      "node_modules/onnxruntime-web": {
+        version: "1.0.0",
+        integrity: "sha512-W",
+        dependencies: { orphan: "^1.0.0", nested: "^1.0.0" }
+      },
+      "node_modules/onnxruntime-web/node_modules/nested": { version: "1.0.0", integrity: "sha512-N" },
+      "node_modules/orphan": { version: "1.0.0", integrity: "sha512-O" }
+    }
+  };
+  const { packages, missing } = closureFromLockfile(lock);
+  assert.deepEqual(packages.map((pkg) => pkg.rel), ["@huggingface/transformers", "dep"]);
+  assert.deepEqual(missing, [], "被剔除的包不该算成「解析不到」");
+});
+
+test("closureFromLockfile：解析不到的依赖如实记下来，不静默少一个包", () => {
+  const lock = {
+    packages: {
+      "node_modules/@huggingface/transformers": {
+        version: "4.2.0",
+        integrity: "sha512-T",
+        dependencies: { "does-not-exist": "^1.0.0" }
+      }
+    }
+  };
+  const { packages, missing } = closureFromLockfile(lock);
+  assert.deepEqual(packages.map((pkg) => pkg.rel), ["@huggingface/transformers"]);
+  assert.equal(missing.length, 1);
+  assert.match(missing[0], /does-not-exist/);
+});
+
+test("build：平台无关，六个常见平台都能过滤出完整的必需包与各自的平台二进制", () => {
+  const built = build();
+  assert.equal(built.manifestVersion, 2);
+  assert.equal(built.entry, "@huggingface/transformers");
+  assert.match(built.transformersVersion, /^\d+\.\d+\.\d+/);
+  assert.ok(built.packages.length > 40, `闭包太小：${built.packages.length}`);
+
+  for (const pkg of built.packages) {
+    assert.match(pkg.integrity, /^sha512-/, `${pkg.rel} 缺 sha512`);
+    assert.match(pkg.tarball, /^https:\/\//, `${pkg.rel} 的地址不可取`);
+    assert.equal(isExcluded(pkg), false, `${pkg.rel} 不该出现在清单里`);
+  }
+  const rels = built.packages.map((pkg) => pkg.rel);
+  assert.equal(new Set(rels).size, rels.length, "rel 有重复，落盘会互相覆盖");
+
+  for (const [platform, arch] of COVERED_PLATFORMS) {
+    const set = packagesForPlatform(built, platform, arch);
+    for (const required of REQUIRED_PACKAGES) {
+      assert.ok(
+        set.some((pkg) => pkg.rel === required),
+        `${platform}-${arch} 过滤后缺必需包 ${required}`
+      );
+    }
+    // 各平台必须拿到**自己**的 sharp 原生包，且不能混进别的平台的（否则下载器会拉错二进制）。
+    const native = set.filter((pkg) => pkg.name.startsWith("@img/sharp-"));
+    assert.ok(native.length > 0, `${platform}-${arch} 没有 sharp 平台包`);
+    for (const pkg of native) {
+      assert.ok((pkg.os ?? []).includes(platform), `${platform}-${arch} 混进了 ${pkg.rel}`);
+    }
+    // payloadId 由「版本 + 平台」算出来（v2 清单里不再存它）。
+    assert.equal(
+      payloadId({ version: built.transformersVersion, platform, arch }),
+      `transformers-4.2.0-node-${platform}-${arch}`
+    );
+  }
+});
+
+test("libc 过滤：确认 glibc 时剔掉 musl 变体，拿不到证据时一个都不剔", () => {
+  const built = build();
+  const all = packagesForPlatform(built, "linux", "x64");
+  const onGlibc = packagesForPlatform(built, "linux", "x64", "glibc");
+  const dropped = all.filter((pkg) => !onGlibc.includes(pkg));
+  // linux-x64 上那两套 musl 变体（sharp 与 libvips）就是这条过滤的全部收益，十几 MB。
+  assert.ok(dropped.length >= 2, `应当剔掉 musl 变体，实际剔了 ${dropped.length}`);
+  for (const pkg of dropped) assert.deepEqual(pkg.libc, ["musl"], `${pkg.rel} 不该被剔`);
+  // 必需包绝不能因 libc 被剔 —— 否则下载会在「缺必需包」处直接失败，用户拿不到出路。
+  for (const required of REQUIRED_PACKAGES) {
+    assert.ok(onGlibc.some((pkg) => pkg.rel === required), `确认 glibc 后缺必需包 ${required}`);
+  }
+  // 没有证据 = 与过滤前完全一致（默认路径必须是它）。
+  assert.deepEqual(packagesForPlatform(built, "linux", "x64", null), all);
+  // 别的平台没有 libc 变体，给不给证据都一样。
+  assert.deepEqual(
+    packagesForPlatform(built, "darwin", "arm64", "glibc"),
+    packagesForPlatform(built, "darwin", "arm64")
+  );
+});
+
+test("已提交的 runtime-manifest.json 就是生成器的输出（漂移 = 发布错的哈希）", () => {
+  const committed = JSON.parse(readFileSync(join(ROOT, "runtime-manifest.json"), "utf8"));
+  assert.deepEqual(committed, build(), "清单与 package-lock.json 不一致，请重跑 scripts/build-runtime-manifest.mjs");
+});

package/test/runtime-provision.test.js

@@ -0,0 +1,101 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { tmpdir } from "node:os";
+import { join, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { adoptHostRuntime, hostModulesDir, provisionRuntime } from "../src/runtime/provision.js";
+import { makeEmptyModules, makeSourceModules } from "./helpers/runtime-source.js";
+
+// PR-C：面板「一键收编」的服务层。守两件事：
+//   ① 源目录由插件自身路径推出 —— 面板不传参，也不把「从任意目录收编」变成对外能力；
+//   ② ok 必须同时看「结构完整」与「闭包无缺口」—— 与 CLI 退出码同一条判据，
+//      否则面板会把「入口一 import 就炸」的收编显示成成功。
+
+test("hostModulesDir：从插件自身位置往上三级就是宿主 node_modules", () => {
+  const fake = pathToFileURL(
+    join(tmpdir(), "proj", "node_modules", "@modusensus", "dsh-mneme", "lib", "api.js")
+  ).href;
+  assert.equal(hostModulesDir(fake), join(tmpdir(), "proj", "node_modules"));
+});
+
+test("adoptHostRuntime：源里没有入口包时返回失败结论，不抛异常（曾经抛 TypeError）", () => {
+  const src = makeEmptyModules();
+  const result = adoptHostRuntime({ hostModulesDir: src.nm, runtimeDir: src.runtimeDir });
+  assert.equal(result.ok, false);
+  assert.equal(result.status, "failed");
+  assert.match(result.reason, /入口包/);
+});
+
+test("adoptHostRuntime：闭包缺件必须 ok:false（结构通过不等于可用）", () => {
+  const src = makeSourceModules({ withMissingDep: true });
+  const result = adoptHostRuntime({ hostModulesDir: src.nm, runtimeDir: src.runtimeDir });
+  assert.equal(result.ok, false, JSON.stringify(result));
+  assert.equal(result.status, "incomplete");
+  assert.deepEqual(result.gaps, ["definitely-not-installed-pkg"]);
+  // 结构检查本身是通过的 —— 缺口只有闭包计划知道，这正是要守的那条缝。
+  assert.deepEqual(result.missing, []);
+  assert.equal(result.packages, 3);
+});
+
+test("adoptHostRuntime：闭包完整时报出结论与规模", () => {
+  const src = makeSourceModules();
+  const result = adoptHostRuntime({ hostModulesDir: src.nm, runtimeDir: src.runtimeDir });
+  assert.equal(result.ok, true, JSON.stringify(result));
+  assert.equal(result.status, "adopted");
+  assert.match(result.payloadId, /^transformers-4\.2\.0-node-/);
+  assert.equal(result.gaps.length, 0);
+  assert.equal(result.packages, 3);
+  assert.ok(result.files > 0 && result.bytes > 0);
+  assert.ok(["hardlink", "copy", "mixed"].includes(result.materialize), result.materialize);
+});
+
+test("adoptHostRuntime：目标已存在默认不覆盖，带 overwrite 才重建（面板据此区分「缺」与「坏」）", () => {
+  const src = makeSourceModules();
+  assert.equal(adoptHostRuntime({ hostModulesDir: src.nm, runtimeDir: src.runtimeDir }).ok, true);
+
+  const again = adoptHostRuntime({ hostModulesDir: src.nm, runtimeDir: src.runtimeDir });
+  assert.equal(again.ok, false);
+  assert.match(again.reason, /目标已存在/);
+
+  const forced = adoptHostRuntime({ hostModulesDir: src.nm, runtimeDir: src.runtimeDir, overwrite: true });
+  assert.equal(forced.ok, true, JSON.stringify(forced));
+});
+
+test("provisionRuntime：本机有可收编的源时走收编，不联网", async () => {
+  const src = makeSourceModules();
+  const result = await provisionRuntime({
+    hostModulesDir: src.nm,
+    runtimeDir: src.runtimeDir,
+    // 一旦它去下载就会命中这个必抛的 fetch —— 从而证明这次确实没有联网。
+    fetchImpl: () => {
+      throw new Error("不该联网");
+    }
+  });
+  assert.equal(result.ok, true, result.reason);
+  assert.equal(result.strategy, "adopt", "有源时应当走收编而不是下载");
+  assert.ok(result.packages > 0);
+});
+
+test("adoptHostRuntime：收编结果不完整时也必须带 reason（不能是 undefined）", () => {
+  const src = makeSourceModules({ withMissingDep: true });
+  const result = adoptHostRuntime({ hostModulesDir: src.nm, runtimeDir: src.runtimeDir });
+  assert.equal(result.ok, false);
+  assert.equal(result.status, "incomplete");
+  // 评审指出的正是这条：缺 reason 时，给用户的话会变成「收编失败：undefined」。
+  assert.match(result.reason, /收编结果不完整/);
+  assert.match(result.reason, /缺依赖/);
+});
+
+test("provisionRuntime：同一个目录的不同写法必须共用一把锁（否则仍会被并发写）", async () => {
+  const src = makeSourceModules();
+  // 尾部分隔符是最常见的等价写法（配置里手填、或别处 join 出来的形态）；
+  // 归一化之前它与 src.runtimeDir 是两个键，于是第二次会重跑一遍收编，
+  // 撞上「目标已存在」—— 用户看到的是「取件失败」，而不是接上正在进行的那次。
+  const sameDirOtherSpelling = src.runtimeDir + sep;
+  const [a, b] = await Promise.all([
+    provisionRuntime({ hostModulesDir: src.nm, runtimeDir: src.runtimeDir }),
+    provisionRuntime({ hostModulesDir: src.nm, runtimeDir: sameDirOtherSpelling })
+  ]);
+  assert.equal(a.ok, true, a.reason);
+  assert.equal(a, b, "等价路径应当复用同一次取件（同一个结论对象）");
+});

package/test/runtime-tarball.test.js

@@ -0,0 +1,82 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { gzipSync } from "node:zlib";
+import { sha512Base64, stripPackagePrefix, verifyIntegrity, walkTar, walkTgz } from "../src/runtime/tarball.js";
+import { tarFile, tarHeader, tarMeta, tarPax } from "./helpers/tar-builder.js";
+
+// PR-C 下载通道的归档读取层。这里是整条链里最该被单独守住的一块：它读的是别人产出的字节，
+// 一旦读错，我们就会把「缺文件/文件截断」的运行时当成完整的搬进 payload，而那种错误
+// 要到第一次 import 原生模块时才现形。
+//
+// 合成归档在测试里现造（不引 tar 库），另外单独用 npm pack 产出的真实 .tgz 做过一次交叉核对
+// （见 PR 描述里的验证记录）——合成归档只能证明读取器与规范一致，真实产物才能证明它与 npm 一致。
+
+const END = [Buffer.alloc(512), Buffer.alloc(512)];
+
+function collect(buffer) {
+  const seen = [];
+  const stats = walkTar(buffer, (entry) => seen.push([entry.path, entry.data.toString("utf8")]));
+  return { seen, stats };
+}
+
+test("walkTar：普通文件、目录、prefix 长路径、符号链接跳过、归档结束块都能处理", () => {
+  const archive = Buffer.concat([
+    ...tarFile("package/package.json", '{"name":"x"}\n'),
+    ...tarMeta("package/lib", "5"),
+    ...tarFile("api.js", "export const x = 1;\n", { prefix: "package/a/very/long/nested/path" }),
+    ...tarMeta("package/link", "2"),
+    ...END
+  ]);
+
+  const { seen, stats } = collect(archive);
+  assert.deepEqual(seen, [
+    ["package/package.json", '{"name":"x"}\n'],
+    ["package/a/very/long/nested/path/api.js", "export const x = 1;\n"]
+  ]);
+  assert.equal(stats.files, 2);
+  assert.equal(stats.bytes, Buffer.byteLength('{"name":"x"}\n') + Buffer.byteLength("export const x = 1;\n"));
+  // 符号链接不能假装搬过来了 —— 如实记下，让上层去判断要不要失败。
+  assert.equal(stats.skipped.length, 1);
+  assert.match(stats.skipped[0], /package\/link/);
+});
+
+test("walkTar：pax 的 path 覆盖下一条目（超过 ustar 字段长度的深层路径靠它）", () => {
+  const long = `package/${"d".repeat(120)}/${"e".repeat(120)}/file.js`;
+  const archive = Buffer.concat([...tarPax(long), ...tarFile("truncated-name", "ok\n"), ...END]);
+  const { seen } = collect(archive);
+  assert.deepEqual(seen.map(([p]) => p), [long]);
+});
+
+test("walkTar：没有结束块也能读完（registry 产物有，但别依赖它）", () => {
+  const { seen } = collect(Buffer.concat([...tarFile("package/a.txt", "a\n")]));
+  assert.deepEqual(seen, [["package/a.txt", "a\n"]]);
+});
+
+test("walkTgz：gzip 包装的归档走同一条路", () => {
+  const inner = Buffer.concat([...tarFile("package/package.json", "{}\n"), ...END]);
+  // 未压缩那份用 walkTar 读，压缩那份用 walkTgz 读，两者结论必须一致。
+  const plain = collect(inner).seen;
+  const viaGzip = [];
+  const stats = walkTgz(gzipSync(inner), (entry) => viaGzip.push([entry.path, entry.data.toString("utf8")]));
+  assert.deepEqual(viaGzip, plain);
+  assert.equal(stats.files, 1);
+});
+
+test("stripPackagePrefix：只去 npm 那一层前缀", () => {
+  assert.equal(stripPackagePrefix("package/lib/index.js"), "lib/index.js");
+  assert.equal(stripPackagePrefix("package"), "package");
+  assert.equal(stripPackagePrefix("lib/index.js"), "lib/index.js");
+});
+
+test("verifyIntegrity：只认 sha512，且不匹配就是不匹配", () => {
+  const good = Buffer.from("hello tarball");
+  const integrity = `sha512-${sha512Base64(good)}`;
+  assert.equal(verifyIntegrity(good, integrity), true);
+
+  const tampered = Buffer.from("hello tarbal!");
+  assert.equal(verifyIntegrity(tampered, integrity), false, "差一个字节也必须失败");
+  // 不认识的算法不能放行：那等于把「没校验」说成「校验通过」。
+  assert.equal(verifyIntegrity(good, "md5-YWJj"), false);
+  assert.equal(verifyIntegrity(good, ""), false);
+  assert.equal(verifyIntegrity(good, "sha512-"), false);
+});