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

package/test/route-policy.test.js

@@ -1,113 +1,113 @@
-// 路由鉴权的结构锁（2026-10 审计 P0 的修法验证）。
-// 这批用例锁的不是「某条路由要不要 token」，而是**鉴权不再靠人记得写**：
-//   1. 新路由漏声明 policy → createApi / register 直接抛（起不来，而不是静默开放）
-//   2. 同一路径重复登记 → 抛（防复制粘贴出两条同路径、其中一条没人管）
-//   3. 三种 policy 的运行时语义（open / token / token-write）
-//   4. 装配后的每条路由都带 policy，且 count() 与实际挂载数一致
-// 之所以不写「39 条路由 × 方法的权限矩阵」：缺声明这条已经是装配期错误，
-// 矩阵要抓的那类回归在结构上写不出来。
-import test from "node:test";
-import assert from "node:assert/strict";
-import { EventEmitter } from "node:events";
-import { createStore } from "../src/store.js";
-import { createService } from "../src/service.js";
-import { createSettings } from "../src/settings.js";
-import { createApi, createRouteRegistrar, ROUTE_POLICIES } from "../src/api.js";
-
-class FakeRes extends EventEmitter {
-  constructor() { super(); this.statusCode = 200; this.body = ""; }
-  writeHead(code, headers) { this.statusCode = code; this.headers = headers; return this; }
-  end(text) { this.body = text ?? ""; this.emit("end"); return this; }
-}
-
-function fakeWebServer(mounted) {
-  return { register(route) { mounted.push(route); return () => {}; } };
-}
-
-function req(method) {
-  const r = new EventEmitter();
-  r.url = "/x";
-  r.method = method;
-  r.headers = {};
-  return r;
-}
-
-function registrar(apiToken = "secret-token") {
-  const mounted = [];
-  const { register, count } = createRouteRegistrar(fakeWebServer(mounted), apiToken, []);
-  return { register, count, mounted };
-}
-
-test("漏声明 policy 的路由起不来（不是默认开放）", () => {
-  const { register } = registrar();
-  assert.throws(
-    () => register({ kind: "exact", path: "/api/dsh-mneme/nope", handler() {} }),
-    /必须声明 policy/
-  );
-  assert.throws(
-    () => register({ kind: "exact", path: "/api/dsh-mneme/nope", policy: "public", handler() {} }),
-    /必须声明 policy/
-  );
-});
-
-test("同一 kind+path 重复登记会抛", () => {
-  const { register } = registrar();
-  register({ kind: "exact", path: "/api/dsh-mneme/dup", policy: "open", handler() {} });
-  assert.throws(
-    () => register({ kind: "exact", path: "/api/dsh-mneme/dup", policy: "open", handler() {} }),
-    /重复登记/
-  );
-});
-
-test("open：配了 token 也放行", () => {
-  const { register, mounted } = registrar();
-  let called = 0;
-  register({ kind: "exact", path: "/api/dsh-mneme/open", policy: "open", handler() { called++; } });
-  const res = new FakeRes();
-  mounted[0].handler(req("GET"), res);
-  assert.equal(called, 1);
-  assert.equal(res.statusCode, 200);
-});
-
-test("token：任何方法都要 Bearer，handler 根本进不去", () => {
-  const { register, mounted } = registrar();
-  let called = 0;
-  register({ kind: "exact", path: "/api/dsh-mneme/gated", policy: "token", handler() { called++; } });
-  const denied = new FakeRes();
-  mounted[0].handler(req("GET"), denied);
-  assert.equal(denied.statusCode, 401);
-  assert.equal(called, 0);
-
-  const okReq = req("GET");
-  okReq.headers = { authorization: "Bearer secret-token" };
-  const ok = new FakeRes();
-  mounted[0].handler(okReq, ok);
-  assert.equal(called, 1);
-});
-
-test("token-write：GET 开放、POST 要 Bearer", () => {
-  const { register, mounted } = registrar();
-  let called = 0;
-  register({ kind: "exact", path: "/api/dsh-mneme/half", policy: "token-write", handler() { called++; } });
-  mounted[0].handler(req("GET"), new FakeRes());
-  assert.equal(called, 1, "GET 无 token 也放行");
-  const denied = new FakeRes();
-  mounted[0].handler(req("POST"), denied);
-  assert.equal(denied.statusCode, 401);
-  assert.equal(called, 1, "POST 无 token 不进 handler");
-});
-
-test("装配后每条路由都带 policy，count() 与实际挂载数一致", () => {
-  const store = createStore(":memory:");
-  const service = createService({ store, mirror: null, config: {} });
-  const settings = createSettings(store.db);
-  const mounted = [];
-  const ctx = { webServer: fakeWebServer(mounted) };
-  const api = createApi(ctx, service, settings, { add() {}, remove() {}, list: () => [] }, null, undefined, "secret-token");
-  assert.ok(mounted.length >= 30, "路由数异常：" + mounted.length);
-  for (const route of mounted) {
-    assert.ok(ROUTE_POLICIES.includes(route.policy), route.path + " 的 policy 非法：" + route.policy);
-    assert.equal(typeof route.handler, "function");
-  }
-  assert.equal(api.routes, mounted.length, "createApi 汇报的路由数必须等于实际挂载数");
-});
+// 路由鉴权的结构锁（2026-10 审计 P0 的修法验证）。
+// 这批用例锁的不是「某条路由要不要 token」，而是**鉴权不再靠人记得写**：
+//   1. 新路由漏声明 policy → createApi / register 直接抛（起不来，而不是静默开放）
+//   2. 同一路径重复登记 → 抛（防复制粘贴出两条同路径、其中一条没人管）
+//   3. 三种 policy 的运行时语义（open / token / token-write）
+//   4. 装配后的每条路由都带 policy，且 count() 与实际挂载数一致
+// 之所以不写「39 条路由 × 方法的权限矩阵」：缺声明这条已经是装配期错误，
+// 矩阵要抓的那类回归在结构上写不出来。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createSettings } from "../src/settings.js";
+import { createApi, createRouteRegistrar, ROUTE_POLICIES } from "../src/api.js";
+
+class FakeRes extends EventEmitter {
+  constructor() { super(); this.statusCode = 200; this.body = ""; }
+  writeHead(code, headers) { this.statusCode = code; this.headers = headers; return this; }
+  end(text) { this.body = text ?? ""; this.emit("end"); return this; }
+}
+
+function fakeWebServer(mounted) {
+  return { register(route) { mounted.push(route); return () => {}; } };
+}
+
+function req(method) {
+  const r = new EventEmitter();
+  r.url = "/x";
+  r.method = method;
+  r.headers = {};
+  return r;
+}
+
+function registrar(apiToken = "secret-token") {
+  const mounted = [];
+  const { register, count } = createRouteRegistrar(fakeWebServer(mounted), apiToken, []);
+  return { register, count, mounted };
+}
+
+test("漏声明 policy 的路由起不来（不是默认开放）", () => {
+  const { register } = registrar();
+  assert.throws(
+    () => register({ kind: "exact", path: "/api/dsh-mneme/nope", handler() {} }),
+    /必须声明 policy/
+  );
+  assert.throws(
+    () => register({ kind: "exact", path: "/api/dsh-mneme/nope", policy: "public", handler() {} }),
+    /必须声明 policy/
+  );
+});
+
+test("同一 kind+path 重复登记会抛", () => {
+  const { register } = registrar();
+  register({ kind: "exact", path: "/api/dsh-mneme/dup", policy: "open", handler() {} });
+  assert.throws(
+    () => register({ kind: "exact", path: "/api/dsh-mneme/dup", policy: "open", handler() {} }),
+    /重复登记/
+  );
+});
+
+test("open：配了 token 也放行", () => {
+  const { register, mounted } = registrar();
+  let called = 0;
+  register({ kind: "exact", path: "/api/dsh-mneme/open", policy: "open", handler() { called++; } });
+  const res = new FakeRes();
+  mounted[0].handler(req("GET"), res);
+  assert.equal(called, 1);
+  assert.equal(res.statusCode, 200);
+});
+
+test("token：任何方法都要 Bearer，handler 根本进不去", () => {
+  const { register, mounted } = registrar();
+  let called = 0;
+  register({ kind: "exact", path: "/api/dsh-mneme/gated", policy: "token", handler() { called++; } });
+  const denied = new FakeRes();
+  mounted[0].handler(req("GET"), denied);
+  assert.equal(denied.statusCode, 401);
+  assert.equal(called, 0);
+
+  const okReq = req("GET");
+  okReq.headers = { authorization: "Bearer secret-token" };
+  const ok = new FakeRes();
+  mounted[0].handler(okReq, ok);
+  assert.equal(called, 1);
+});
+
+test("token-write：GET 开放、POST 要 Bearer", () => {
+  const { register, mounted } = registrar();
+  let called = 0;
+  register({ kind: "exact", path: "/api/dsh-mneme/half", policy: "token-write", handler() { called++; } });
+  mounted[0].handler(req("GET"), new FakeRes());
+  assert.equal(called, 1, "GET 无 token 也放行");
+  const denied = new FakeRes();
+  mounted[0].handler(req("POST"), denied);
+  assert.equal(denied.statusCode, 401);
+  assert.equal(called, 1, "POST 无 token 不进 handler");
+});
+
+test("装配后每条路由都带 policy，count() 与实际挂载数一致", () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const settings = createSettings(store.db);
+  const mounted = [];
+  const ctx = { webServer: fakeWebServer(mounted) };
+  const api = createApi(ctx, service, settings, { add() {}, remove() {}, list: () => [] }, null, undefined, "secret-token");
+  assert.ok(mounted.length >= 30, "路由数异常：" + mounted.length);
+  for (const route of mounted) {
+    assert.ok(ROUTE_POLICIES.includes(route.policy), route.path + " 的 policy 非法：" + route.policy);
+    assert.equal(typeof route.handler, "function");
+  }
+  assert.equal(api.routes, mounted.length, "createApi 汇报的路由数必须等于实际挂载数");
+});

package/test/runtime-adopt.test.js

@@ -1,206 +1,206 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { existsSync, mkdirSync, mkdtempSync, symlinkSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { adoptRuntime, materializePackage, RUNTIME_MANIFEST_VERSION } from "../src/runtime/adopt.js";
-import { describePayload, nodeModulesDir, payloadDir, payloadId, runtimeManifestPath } from "../src/runtime/layout.js";
-import { readJsonSafe } from "../src/runtime/layout.js";
-
-// 收编（issue #131 / PR-A）：守住「老用户升级后本地嵌入不断」这条底线。
-// 关键判据是——源布局被如实镜像（含嵌套层）、同卷走硬链接、符号链接不跟随、
-// 产出的目录能通过结构检查。
-
-/** 造一份「像真的」源 node_modules：入口 + 三平台单包 + 平台分片 + 嵌套版本冲突。 */
-function makeSource({ withSymlink = false } = {}) {
-  const base = mkdtempSync(join(tmpdir(), "mneme-adopt-src-"));
-  const nm = join(base, "node_modules");
-  const write = (rel, body) => {
-    const full = join(nm, rel);
-    mkdirSync(join(full, ".."), { recursive: true });
-    writeFileSync(full, body);
-  };
-  const pkg = (rel, manifest) => write(join(rel, "package.json"), JSON.stringify(manifest));
-
-  pkg("@huggingface/transformers", {
-    name: "@huggingface/transformers",
-    version: "4.2.0",
-    dependencies: { "onnxruntime-node": "1.24.3", sharp: "^0.34.5" }
-  });
-  write("@huggingface/transformers/dist/transformers.node.mjs", "export const real = true;\n");
-
-  pkg("onnxruntime-node", { name: "onnxruntime-node", version: "1.24.3", dependencies: { "onnxruntime-common": "1.24.3" } });
-  write("onnxruntime-node/bin/napi-v6/win32/x64/onnxruntime.dll", "dll-bytes\n");
-  write("onnxruntime-node/bin/napi-v6/darwin/arm64/libonnxruntime.dylib", "dylib-bytes\n");
-
-  pkg("onnxruntime-common", { name: "onnxruntime-common", version: "1.24.3" });
-  write("onnxruntime-common/index.js", "export default 1;\n");
-
-  pkg("sharp", { name: "sharp", version: "0.34.5" });
-  write("sharp/index.js", "export default 2;\n");
-
-  if (withSymlink) write("sharp/linked.js", "export default 3;\n");
-
-  return { base, nm, write };
-}
-
-test("收编：镜像源布局（含嵌套层），并写出清单", () => {
-  const { nm } = makeSource();
-  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
-  const result = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
-
-  assert.equal(result.ok, true, result.reason);
-  assert.equal(result.payloadId, "transformers-4.2.0-node-win32-x64");
-  assert.equal(result.payloadDir, payloadDir(runtimeDir, payloadId({ version: "4.2.0", platform: "win32", arch: "x64" })));
-
-  const manifest = readJsonSafe(runtimeManifestPath(result.payloadDir));
-  assert.equal(manifest.manifestVersion, RUNTIME_MANIFEST_VERSION);
-  assert.equal(manifest.procedure, "adopted");
-  assert.equal(manifest.version, "4.2.0");
-  assert.ok(manifest.packages.some((p) => p.rel === "onnxruntime-node"));
-
-  // 收编产物必须能通过结构检查——这是「adopt 与 layout 契约一致」的整合判据。
-  const report = describePayload(result.payloadDir, { platform: "win32", arch: "x64" });
-  assert.equal(report.ok, true, `missing=${report.missing} reasons=${report.reasons}`);
-  assert.equal(report.manifest?.procedure, "adopted");
-});
-
-test("收编：同卷走硬链接（不额外占盘），且文件内容一致", () => {
-  const { nm } = makeSource();
-  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
-  const result = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
-
-  assert.equal(result.totals.files, result.totals.linked + result.totals.copied, "每个文件要么链接要么复制");
-  assert.ok(result.totals.linked > 0, `同卷应当走硬链接，实际 linked=${result.totals.linked} copied=${result.totals.copied}`);
-  assert.ok(result.totals.bytes > 0);
-  assert.equal(result.manifest.materialize.mode, "hardlink");
-  assert.equal(result.manifest.materialize.linkError, null, "没回退就不该有 linkError");
-
-  const copied = join(nodeModulesDir(result.payloadDir), "onnxruntime-node", "bin", "napi-v6", "win32", "x64", "onnxruntime.dll");
-  assert.equal(readJsonSafe(copied), undefined, "非 JSON 内容应当原样搬过来");
-});
-
-test("收编：硬链接不可用时回退复制，并把原因如实记进清单与 warnings", () => {
-  const { nm } = makeSource();
-  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
-  // 注入一个必定失败的 linkSync，覆盖「跨卷 / 权限不足」这类本机不可复现的环境差异。
-  const denyLink = () => {
-    const error = new Error("operation not permitted, link");
-    error.code = "EPERM";
-    throw error;
-  };
-  const result = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64", link: denyLink });
-
-  assert.equal(result.ok, true, result.reason);
-  assert.equal(result.totals.linked, 0);
-  assert.equal(result.totals.copied, result.totals.files);
-  assert.equal(result.manifest.materialize.mode, "copy");
-  assert.match(result.manifest.materialize.linkError, /EPERM/);
-  assert.equal(
-    result.manifest.warnings.filter((w) => w.includes("硬链接不可用")).length,
-    1,
-    "同一次收编只该记一条回退原因，不是每个文件记一条"
-  );
-  // 回退之后产物依然必须能通过结构检查——回退不能以正确性为代价。
-  assert.equal(describePayload(result.payloadDir, { platform: "win32", arch: "x64" }).ok, true);
-});
-
-test("收编：跳过嵌套 node_modules，避免把同一份包搬两遍", () => {
-  const { nm, write } = makeSource();
-  // 给入口包塞一个嵌套副本：闭包不会把它当作依赖，因此不该被搬进产物。
-  write("@huggingface/transformers/node_modules/orphan/index.js", "orphan\n");
-  write("@huggingface/transformers/node_modules/orphan/package.json", JSON.stringify({ name: "orphan", version: "1.0.0" }));
-
-  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
-  const result = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
-  assert.equal(result.ok, true, result.reason);
-
-  const orphan = join(nodeModulesDir(result.payloadDir), "@huggingface", "transformers", "node_modules", "orphan");
-  assert.equal(describePayload(result.payloadDir, { platform: "win32", arch: "x64" }).ok, true);
-  assert.equal(readJsonSafe(join(orphan, "package.json")), undefined, "不可达的嵌套包不该被搬进来");
-});
-
-test("收编：符号链接不跟随，记进 warnings（isolated 布局的来源会被如实暴露）", (t) => {
-  const { nm, write } = makeSource();
-  const real = join(nm, "sharp", "index.js");
-  const link = join(nm, "sharp", "linked.js");
-  try {
-    symlinkSync(real, link, "file");
-  } catch {
-    t.skip("当前环境不允许创建符号链接（Windows 需要开发者模式），跳过该断言");
-    return;
-  }
-  assert.ok(write);
-
-  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
-  const result = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
-  assert.equal(result.totals.symlinks, 1);
-  assert.ok(result.manifest.warnings.some((w) => w.includes("符号链接")));
-});
-
-test("收编：目标已存在时默认拒绝，overwrite 才覆盖", () => {
-  const { nm } = makeSource();
-  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
-  const first = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
-  assert.equal(first.ok, true);
-
-  const again = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
-  assert.equal(again.ok, false);
-  assert.match(again.reason, /目标已存在/);
-
-  const forced = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64", overwrite: true });
-  assert.equal(forced.ok, true);
-});
-
-test("收编：源里没有入口包时给出可读原因，不抛异常", () => {
-  const empty = mkdtempSync(join(tmpdir(), "mneme-adopt-empty-"));
-  mkdirSync(join(empty, "node_modules"), { recursive: true });
-  const result = adoptRuntime({ fromModulesDir: join(empty, "node_modules") });
-  assert.equal(result.ok, false);
-  assert.match(result.reason, /入口包不存在|入口包未解析到/);
-});
-
-test("materializePackage：统计文件与字节数，返回自身可测", () => {
-  const { base } = makeSource();
-  const src = join(base, "node_modules", "onnxruntime-common");
-  const dest = mkdtempSync(join(tmpdir(), "mneme-materialize-"));
-  const stats = materializePackage({ srcDir: src, destDir: join(dest, "pkg") });
-  assert.equal(stats.files, 2, "package.json + index.js");
-  assert.ok(stats.bytes > 0);
-  assert.equal(stats.symlinks, 0);
-});
-
-test("覆盖收编：先清空目标目录，否则硬链接全部退化成复制、残留文件也清不掉", () => {
-  const { nm } = makeSource();
-  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
-  const first = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
-  assert.equal(first.ok, true, first.reason);
-  assert.equal(first.manifest.materialize.mode, "hardlink");
-
-  // 只可能来自上一次收编的残留文件：覆盖时必须被清掉。
-  const stale = join(first.payloadDir, "stale-from-previous-run");
-  writeFileSync(stale, "stale\n");
-
-  const second = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64", overwrite: true });
-  assert.equal(second.ok, true, second.reason);
-  // 不清空目标目录的话，linkSync 对已存在的目标路径抛 EEXIST，每个文件都掉进复制分支：
-  // 物化方式会假报成 copy，warnings 会错说「硬链接不可用」，整份闭包真实占盘。
-  assert.equal(second.manifest.materialize.mode, "hardlink", "覆盖不该把硬链接降级成复制");
-  assert.equal(second.manifest.materialize.linkError, null);
-  assert.equal(existsSync(stale), false, "上一次收编的残留文件必须被清掉");
-});
-
-test("截断的闭包必须拒绝：宁可明确失败，也不要产出一份看起来可用的运行时", () => {
-  const { nm } = makeSource();
-  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
-  // 上限 1 个包，必然截断传递依赖。结构检查只看必需包/版本/入口，所以这种残缺 payload
-  // 本来会被判为可用、被 loader 选中，然后在 import 原生模块时才炸。
-  const result = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64", maxPackages: 1 });
-  assert.equal(result.ok, false);
-  assert.match(result.reason, /截断/);
-  assert.equal(
-    existsSync(payloadDir(runtimeDir, payloadId({ version: "4.2.0", platform: "win32", arch: "x64" }))),
-    false,
-    "拒绝时不该留下半份 payload"
-  );
-});
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { adoptRuntime, materializePackage, RUNTIME_MANIFEST_VERSION } from "../src/runtime/adopt.js";
+import { describePayload, nodeModulesDir, payloadDir, payloadId, runtimeManifestPath } from "../src/runtime/layout.js";
+import { readJsonSafe } from "../src/runtime/layout.js";
+
+// 收编（issue #131 / PR-A）：守住「老用户升级后本地嵌入不断」这条底线。
+// 关键判据是——源布局被如实镜像（含嵌套层）、同卷走硬链接、符号链接不跟随、
+// 产出的目录能通过结构检查。
+
+/** 造一份「像真的」源 node_modules：入口 + 三平台单包 + 平台分片 + 嵌套版本冲突。 */
+function makeSource({ withSymlink = false } = {}) {
+  const base = mkdtempSync(join(tmpdir(), "mneme-adopt-src-"));
+  const nm = join(base, "node_modules");
+  const write = (rel, body) => {
+    const full = join(nm, rel);
+    mkdirSync(join(full, ".."), { recursive: true });
+    writeFileSync(full, body);
+  };
+  const pkg = (rel, manifest) => write(join(rel, "package.json"), JSON.stringify(manifest));
+
+  pkg("@huggingface/transformers", {
+    name: "@huggingface/transformers",
+    version: "4.2.0",
+    dependencies: { "onnxruntime-node": "1.24.3", sharp: "^0.34.5" }
+  });
+  write("@huggingface/transformers/dist/transformers.node.mjs", "export const real = true;\n");
+
+  pkg("onnxruntime-node", { name: "onnxruntime-node", version: "1.24.3", dependencies: { "onnxruntime-common": "1.24.3" } });
+  write("onnxruntime-node/bin/napi-v6/win32/x64/onnxruntime.dll", "dll-bytes\n");
+  write("onnxruntime-node/bin/napi-v6/darwin/arm64/libonnxruntime.dylib", "dylib-bytes\n");
+
+  pkg("onnxruntime-common", { name: "onnxruntime-common", version: "1.24.3" });
+  write("onnxruntime-common/index.js", "export default 1;\n");
+
+  pkg("sharp", { name: "sharp", version: "0.34.5" });
+  write("sharp/index.js", "export default 2;\n");
+
+  if (withSymlink) write("sharp/linked.js", "export default 3;\n");
+
+  return { base, nm, write };
+}
+
+test("收编：镜像源布局（含嵌套层），并写出清单", () => {
+  const { nm } = makeSource();
+  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
+  const result = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
+
+  assert.equal(result.ok, true, result.reason);
+  assert.equal(result.payloadId, "transformers-4.2.0-node-win32-x64");
+  assert.equal(result.payloadDir, payloadDir(runtimeDir, payloadId({ version: "4.2.0", platform: "win32", arch: "x64" })));
+
+  const manifest = readJsonSafe(runtimeManifestPath(result.payloadDir));
+  assert.equal(manifest.manifestVersion, RUNTIME_MANIFEST_VERSION);
+  assert.equal(manifest.procedure, "adopted");
+  assert.equal(manifest.version, "4.2.0");
+  assert.ok(manifest.packages.some((p) => p.rel === "onnxruntime-node"));
+
+  // 收编产物必须能通过结构检查——这是「adopt 与 layout 契约一致」的整合判据。
+  const report = describePayload(result.payloadDir, { platform: "win32", arch: "x64" });
+  assert.equal(report.ok, true, `missing=${report.missing} reasons=${report.reasons}`);
+  assert.equal(report.manifest?.procedure, "adopted");
+});
+
+test("收编：同卷走硬链接（不额外占盘），且文件内容一致", () => {
+  const { nm } = makeSource();
+  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
+  const result = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
+
+  assert.equal(result.totals.files, result.totals.linked + result.totals.copied, "每个文件要么链接要么复制");
+  assert.ok(result.totals.linked > 0, `同卷应当走硬链接，实际 linked=${result.totals.linked} copied=${result.totals.copied}`);
+  assert.ok(result.totals.bytes > 0);
+  assert.equal(result.manifest.materialize.mode, "hardlink");
+  assert.equal(result.manifest.materialize.linkError, null, "没回退就不该有 linkError");
+
+  const copied = join(nodeModulesDir(result.payloadDir), "onnxruntime-node", "bin", "napi-v6", "win32", "x64", "onnxruntime.dll");
+  assert.equal(readJsonSafe(copied), undefined, "非 JSON 内容应当原样搬过来");
+});
+
+test("收编：硬链接不可用时回退复制，并把原因如实记进清单与 warnings", () => {
+  const { nm } = makeSource();
+  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
+  // 注入一个必定失败的 linkSync，覆盖「跨卷 / 权限不足」这类本机不可复现的环境差异。
+  const denyLink = () => {
+    const error = new Error("operation not permitted, link");
+    error.code = "EPERM";
+    throw error;
+  };
+  const result = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64", link: denyLink });
+
+  assert.equal(result.ok, true, result.reason);
+  assert.equal(result.totals.linked, 0);
+  assert.equal(result.totals.copied, result.totals.files);
+  assert.equal(result.manifest.materialize.mode, "copy");
+  assert.match(result.manifest.materialize.linkError, /EPERM/);
+  assert.equal(
+    result.manifest.warnings.filter((w) => w.includes("硬链接不可用")).length,
+    1,
+    "同一次收编只该记一条回退原因，不是每个文件记一条"
+  );
+  // 回退之后产物依然必须能通过结构检查——回退不能以正确性为代价。
+  assert.equal(describePayload(result.payloadDir, { platform: "win32", arch: "x64" }).ok, true);
+});
+
+test("收编：跳过嵌套 node_modules，避免把同一份包搬两遍", () => {
+  const { nm, write } = makeSource();
+  // 给入口包塞一个嵌套副本：闭包不会把它当作依赖，因此不该被搬进产物。
+  write("@huggingface/transformers/node_modules/orphan/index.js", "orphan\n");
+  write("@huggingface/transformers/node_modules/orphan/package.json", JSON.stringify({ name: "orphan", version: "1.0.0" }));
+
+  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
+  const result = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
+  assert.equal(result.ok, true, result.reason);
+
+  const orphan = join(nodeModulesDir(result.payloadDir), "@huggingface", "transformers", "node_modules", "orphan");
+  assert.equal(describePayload(result.payloadDir, { platform: "win32", arch: "x64" }).ok, true);
+  assert.equal(readJsonSafe(join(orphan, "package.json")), undefined, "不可达的嵌套包不该被搬进来");
+});
+
+test("收编：符号链接不跟随，记进 warnings（isolated 布局的来源会被如实暴露）", (t) => {
+  const { nm, write } = makeSource();
+  const real = join(nm, "sharp", "index.js");
+  const link = join(nm, "sharp", "linked.js");
+  try {
+    symlinkSync(real, link, "file");
+  } catch {
+    t.skip("当前环境不允许创建符号链接（Windows 需要开发者模式），跳过该断言");
+    return;
+  }
+  assert.ok(write);
+
+  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
+  const result = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
+  assert.equal(result.totals.symlinks, 1);
+  assert.ok(result.manifest.warnings.some((w) => w.includes("符号链接")));
+});
+
+test("收编：目标已存在时默认拒绝，overwrite 才覆盖", () => {
+  const { nm } = makeSource();
+  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
+  const first = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
+  assert.equal(first.ok, true);
+
+  const again = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
+  assert.equal(again.ok, false);
+  assert.match(again.reason, /目标已存在/);
+
+  const forced = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64", overwrite: true });
+  assert.equal(forced.ok, true);
+});
+
+test("收编：源里没有入口包时给出可读原因，不抛异常", () => {
+  const empty = mkdtempSync(join(tmpdir(), "mneme-adopt-empty-"));
+  mkdirSync(join(empty, "node_modules"), { recursive: true });
+  const result = adoptRuntime({ fromModulesDir: join(empty, "node_modules") });
+  assert.equal(result.ok, false);
+  assert.match(result.reason, /入口包不存在|入口包未解析到/);
+});
+
+test("materializePackage：统计文件与字节数，返回自身可测", () => {
+  const { base } = makeSource();
+  const src = join(base, "node_modules", "onnxruntime-common");
+  const dest = mkdtempSync(join(tmpdir(), "mneme-materialize-"));
+  const stats = materializePackage({ srcDir: src, destDir: join(dest, "pkg") });
+  assert.equal(stats.files, 2, "package.json + index.js");
+  assert.ok(stats.bytes > 0);
+  assert.equal(stats.symlinks, 0);
+});
+
+test("覆盖收编：先清空目标目录，否则硬链接全部退化成复制、残留文件也清不掉", () => {
+  const { nm } = makeSource();
+  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
+  const first = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
+  assert.equal(first.ok, true, first.reason);
+  assert.equal(first.manifest.materialize.mode, "hardlink");
+
+  // 只可能来自上一次收编的残留文件：覆盖时必须被清掉。
+  const stale = join(first.payloadDir, "stale-from-previous-run");
+  writeFileSync(stale, "stale\n");
+
+  const second = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64", overwrite: true });
+  assert.equal(second.ok, true, second.reason);
+  // 不清空目标目录的话，linkSync 对已存在的目标路径抛 EEXIST，每个文件都掉进复制分支：
+  // 物化方式会假报成 copy，warnings 会错说「硬链接不可用」，整份闭包真实占盘。
+  assert.equal(second.manifest.materialize.mode, "hardlink", "覆盖不该把硬链接降级成复制");
+  assert.equal(second.manifest.materialize.linkError, null);
+  assert.equal(existsSync(stale), false, "上一次收编的残留文件必须被清掉");
+});
+
+test("截断的闭包必须拒绝：宁可明确失败，也不要产出一份看起来可用的运行时", () => {
+  const { nm } = makeSource();
+  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
+  // 上限 1 个包，必然截断传递依赖。结构检查只看必需包/版本/入口，所以这种残缺 payload
+  // 本来会被判为可用、被 loader 选中，然后在 import 原生模块时才炸。
+  const result = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64", maxPackages: 1 });
+  assert.equal(result.ok, false);
+  assert.match(result.reason, /截断/);
+  assert.equal(
+    existsSync(payloadDir(runtimeDir, payloadId({ version: "4.2.0", platform: "win32", arch: "x64" }))),
+    false,
+    "拒绝时不该留下半份 payload"
+  );
+});