@modusensus/dsh-mneme 0.7.31 → 0.8.0

package/test/dream.test.js

@@ -27,6 +27,56 @@ test("unknown id rejects whole list", () => {
   assert.ok(errors.some((e) => e.includes("zzz")));
 });
 
+// --- Issue #135: 唯一前缀解析 -------------------------------------------------
+// 模型常把 36 位 UUID 回填成前缀（报告实测 78/78 个 8 位前缀都能唯一对应窗口内
+// 真实记忆，且 few-shot 示例的 "m1"/"m2" 占位符在诱导这种缩写）。校验前的唯一
+// 前缀解析把它们还原成完整 id，而不是逐条 unknown id 后被覆盖率闸整单拒绝。
+
+test("Issue #135: unique short prefixes resolve to full ids (ids + keepSource)", () => {
+  const idA = "f77a0d17-2586-41fe-a789-d69f4d1cee83";
+  const idB = "bc17c9ed-e84c-4b9f-bc36-48f8e9a6b3e0";
+  const snap = snapshot([idA, idB]);
+  const decisions = [
+    { action: "merge", ids: ["f77a0d17", "bc17c9ed"], title: "合并", content: "合并后的内容", importance: 4, keepSource: "f77a0d17" }
+  ];
+  const { ok, errors, resolvedShortIds } = validateDecisions(decisions, snap);
+  assert.equal(ok, true, JSON.stringify(errors));
+  assert.equal(resolvedShortIds, 3, "two ids + keepSource resolved");
+  assert.deepEqual(decisions[0].ids, [idA, idB], "ids rewritten in place");
+  assert.equal(decisions[0].keepSource, idA, "keepSource rewritten");
+});
+
+test("Issue #135: conflict winner/loser short prefixes resolve", () => {
+  const idA = "f77a0d17-2586-41fe-a789-d69f4d1cee83";
+  const idB = "bc17c9ed-e84c-4b9f-bc36-48f8e9a6b3e0";
+  const snap = snapshot([idA, idB]);
+  const decisions = [{ action: "conflict", winner: "f77a0d17", loser: "bc17c9ed", reason: "内容矛盾" }];
+  const { ok, errors, resolvedShortIds } = validateDecisions(decisions, snap);
+  assert.equal(ok, true, JSON.stringify(errors));
+  assert.equal(resolvedShortIds, 2);
+  assert.equal(decisions[0].winner, idA, "winner rewritten");
+  assert.equal(decisions[0].loser, idB, "loser rewritten");
+});
+
+test("Issue #135: ambiguous prefix stays unresolved and reports unknown id", () => {
+  const snap = snapshot([
+    "aaaaaaaa-1111-4111-8111-111111111111",
+    "aaaaaaaa-2222-4222-8222-222222222222"
+  ]);
+  const { ok, errors, resolvedShortIds } = validateDecisions([{ action: "archive", ids: ["aaaaaaaa"] }], snap);
+  assert.equal(ok, false);
+  assert.equal(resolvedShortIds, 0, "ambiguous prefix is never guessed");
+  assert.ok(errors.some((e) => e.includes("unknown id")), JSON.stringify(errors));
+});
+
+test("Issue #135: unmatched prefix is left for the validator to report", () => {
+  const snap = snapshot(["f77a0d17-2586-41fe-a789-d69f4d1cee83"]);
+  const { ok, errors, resolvedShortIds } = validateDecisions([{ action: "archive", ids: ["deadbeef"] }], snap);
+  assert.equal(ok, false);
+  assert.equal(resolvedShortIds, 0, "no match means no rewrite");
+  assert.ok(errors.some((e) => e.includes("deadbeef")), JSON.stringify(errors));
+});
+
 test("invalid action rejects", () => {
   const snap = snapshot(["a"]);
   const { ok } = validateDecisions([{ action: "explode", ids: ["a"] }], snap);
@@ -486,6 +536,36 @@ test("runDream fails safe on invalid decisions", async () => {
   store.close();
 });
 
+test("Issue #135: failed validation persists { _validationFailed, errors, skipped } into the run row", async () => {
+  const { store, service } = dreamSetup();
+  const saved = service.saveWithDedupe({ type: "preference", title: "语言", content: "中文" });
+  let calls = 0;
+  const ctx = {
+    llm: {
+      stream: async function* () {
+        calls++;
+        yield { type: "text-delta", text: calls === 1 ? JSON.stringify([{ action: "archive", ids: ["deadbeef"] }]) : "summary" };
+        yield { type: "finish", reason: { kind: "ok" } };
+      }
+    },
+    logger: { warn: () => {}, info: () => {} }
+  };
+  const dream = createDreamScheduler({ thresholdCount: 1, thresholdChars: 0, delayMs: 0 });
+  const result = await dream.runDream(ctx, service, { dreamProvider: "deepseek", dreamModel: "deepseek-chat" });
+  assert.equal(result.ok, false, "coverage gate rejects (0% explicit coverage)");
+  assert.ok(Array.isArray(result.decisions) && result.decisions[0]?._validationFailed === true,
+    "failure result carries the validation detail");
+  assert.ok(result.decisions[0].skipped.some((s) => s.error.includes("deadbeef")),
+    "skipped keeps the per-item reason");
+  // 落库验证：dream_runs.decisions 不再是 NULL，事后可离线定位失败原因。
+  const run = store.getDreamRun(result.runId);
+  assert.ok(run?.decisions?.[0]?._validationFailed === true, "detail persisted in dream_runs.decisions");
+  assert.ok(run.decisions[0].skipped.length >= 1);
+  const lang = store.getById(saved.memory.id);
+  assert.equal(lang.archived, false, "unknown-id decision must not touch real memories");
+  store.close();
+});
+
 // --- item ①: CAS guard against concurrent edits ----------------------------
 
 test("applyDecisions CAS: merge onto a concurrently-edited target is skipped as a conflict, not applied", () => {
@@ -1029,6 +1109,49 @@ test("issue#89: dream run with a skipped invalid decision lands the valid subset
   store.close();
 });
 
+// Issue #104（跟进 #137 失败路径）：degraded（合法子集已应用）轮的跳过明细此前只进
+// logger.warn，splice 之后就地从 decisions 里消失，落库的已是幸存列表——离线回放
+// dream_runs 无法判断被跳的是跨类型 merge、update 保护期还是 unknown id。这里断言
+// 明细进了独立的 skipped 列（而非内联进 decisions），且携带可定位的逐条原因。
+test("issue#104: degraded run persists the skipped decision detail into dream_runs.skipped", async () => {
+  const { store, service } = dreamSetup();
+  const a = service.saveWithDedupe({ type: "project", title: "旧A", content: "过时A" }).memory;
+  const b = service.saveWithDedupe({ type: "project", title: "旧B", content: "过时B" }).memory;
+  const pref = service.saveWithDedupe({ type: "preference", title: "语言", content: "中文" }).memory;
+  const c = service.saveWithDedupe({ type: "project", title: "旧C", content: "过时C" }).memory;
+  const ctx = {
+    logger: { warn: () => {}, info: () => {} },
+    llm: {
+      async *stream(options) {
+        const userText = options.messages.find((m) => m.role === "user")?.content?.[0]?.text ?? "";
+        if (userText.startsWith("id=")) {
+          // 一条跨类型 merge（非法 → 跳过）+ 两条合法 archive（显式覆盖 2/4，过 50% 下限）
+          yield { type: "text-delta", index: 0, text: JSON.stringify([
+            { action: "merge", ids: [pref.id, a.id], keepSource: pref.id, title: "跨类型", content: "不应合并", importance: 4 },
+            { action: "archive", ids: [b.id], reason: "stale" },
+            { action: "archive", ids: [c.id], reason: "stale" }
+          ]) };
+        } else {
+          yield { type: "text-delta", index: 0, text: "记忆库总览：degraded 轮的跳过明细可从审计行回放。" };
+        }
+        yield { type: "finish", reason: { kind: "stop" } };
+      }
+    }
+  };
+  const dream = createDreamScheduler({ thresholdCount: 1, thresholdChars: 0, delayMs: 0 });
+  const result = await dream.runDream(ctx, service, { dreamProvider: "mock", dreamModel: "mock-model" });
+  assert.equal(result.status, "degraded", "run degrades on the skipped decision");
+  // 落库验证：skipped 列不再是 NULL，逐条带 index/action/error，事后无需重跑即可定位成因。
+  const run = store.getDreamRun(result.runId);
+  assert.ok(Array.isArray(run?.skipped) && run.skipped.length === 1, "skipped detail persisted in dream_runs.skipped");
+  assert.equal(run.skipped[0].index, 0, "the skipped entry is the cross-type merge");
+  assert.equal(run.skipped[0].action, "merge");
+  assert.match(run.skipped[0].error, /multiple types/, "per-item skip reason is kept");
+  // 独立字段，不污染按「决策数组」消费 decisions 的下游读者。
+  assert.ok(!run.decisions.some((d) => d && d._skipped !== undefined), "decisions stays free of inline markers");
+  store.close();
+});
+
 test("issue#89: dreamSkipInvalid:false restores the whole-batch strict rejection", async () => {
   const { store, service } = dreamSetup();
   const a = service.saveWithDedupe({ type: "project", title: "旧A", content: "过时A" }).memory;
@@ -1076,3 +1199,52 @@ test("issue#89: minIntervalMs throttles re-triggering regardless of run outcome"
   assert.equal(dream.maybeSchedule(service), true, "interval elapsed → eligible again (baseline unmoved by failure)");
   store.close();
 });
+
+// --- Issue #126：新动作（supersede / differentiate）在 dream 路径也必须产 receipt ---
+// buildRecordReceipts 此前只认 merge/conflict/update，新动作会静默不产 receipt，让
+// receipt_chain 留洞。dream 的 consolidation prompt 虽然不含这两个动作，但校验器
+// 的 ACTIONS 是共用的——模型自由发挥（或将来把动作集扩到 dream）时审计不能丢。
+
+test("issue#126: a supersede decision on the dream path produces a supersede receipt", async () => {
+  const { store, service } = dreamSetup();
+  const oldMem = service.saveWithDedupe({ type: "project", title: "方案 v1", content: "用 pm2 常驻" }).memory;
+  const newMem = service.saveWithDedupe({ type: "project", title: "方案 v2", content: "改用 systemd" }).memory;
+  const ctx = mockCtx({
+    onConsolidation: () => JSON.stringify([
+      { action: "supersede", winner: newMem.id, loser: oldMem.id, reason: "版本演进" }
+    ])
+  });
+  const dream = createDreamScheduler({ thresholdCount: 1, thresholdChars: 0, delayMs: 0 });
+  const result = await dream.runDream(ctx, service, { dreamProvider: "mock", dreamModel: "mock-model" });
+  assert.equal(result.status, "ok", "supersede applied and the summary landed");
+  assert.equal(store.getById(oldMem.id).archived, true, "older entry archived");
+  assert.equal(store.getById(newMem.id).content, "改用 systemd", "winner body untouched");
+  const receipts = store.listReceipts();
+  const supersedeReceipt = receipts.find((r) => r.kind === "supersede");
+  assert.ok(supersedeReceipt, "supersede receipt lands in receipt_chain");
+  assert.equal(supersedeReceipt.record_id, oldMem.id, "receipt records the superseded side");
+  assert.equal(supersedeReceipt.winner_id, newMem.id);
+  assert.equal(supersedeReceipt.loser_id, oldMem.id);
+  store.close();
+});
+
+test("issue#126: a differentiate decision on the dream path produces one receipt per entry", async () => {
+  const { store, service } = dreamSetup();
+  const a = service.saveWithDedupe({ type: "project", title: "内网端口", content: "内网走 22" }).memory;
+  const b = service.saveWithDedupe({ type: "project", title: "外网端口", content: "外网映射 2222" }).memory;
+  const ctx = mockCtx({
+    onConsolidation: () => JSON.stringify([
+      { action: "differentiate", ids: [a.id, b.id], distinctions: ["内网直连", "外网映射"] }
+    ])
+  });
+  const dream = createDreamScheduler({ thresholdCount: 1, thresholdChars: 0, delayMs: 0 });
+  const result = await dream.runDream(ctx, service, { dreamProvider: "mock", dreamModel: "mock-model" });
+  assert.equal(result.status, "ok", "differentiate applied and the summary landed");
+  assert.equal(store.getById(a.id).archived, false, "neither side is archived");
+  assert.equal(store.getById(b.id).archived, false);
+  const receipts = store.listReceipts().filter((r) => r.kind === "differentiate");
+  assert.equal(receipts.length, 2, "one receipt per differentiated entry");
+  assert.deepEqual(receipts.map((r) => r.record_id).sort(), [a.id, b.id].sort());
+  assert.ok(receipts.every((r) => r.count_before === 1 && r.count_after === 1), "no count change for differentiate");
+  store.close();
+});

package/test/embedding-ready.test.js

@@ -0,0 +1,196 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createEmbedder } from "../src/embedding.js";
+
+// issue #135: the legacy OpenAI-compatible embedder is an object literal with no
+// async init, so api.js's generic `"ready" in embedder` branch used to fall
+// through to "assume usable" — the status card stayed green while baseUrl /
+// apiKey / model were all empty and not a single vector could be produced
+// ("绿色假阳性"). These tests pin the real predicate and the getter semantics.
+
+const FULL = {
+  enabled: true,
+  baseUrl: "https://api.example.com/v1",
+  apiKey: "sk-test",
+  model: "text-embedding-3-small"
+};
+
+/** Build the embedder against a settings double + a recording store. */
+function make(cfg, { live = false } = {}) {
+  const writes = [];
+  const box = { cfg };
+  const embedder = createEmbedder({
+    store: { setEmbedding: (id, vector) => writes.push({ id, vector }) },
+    settings: { getVectorConfig: () => (live ? box.cfg : cfg) },
+    logger: { info() {}, warn() {} }
+  });
+  return { embedder, writes, box };
+}
+
+test("#135 legacy OpenAI embedder reports ready/configured from the config", () => {
+  const { embedder } = make(FULL);
+  assert.equal(embedder.ready, true, "fully configured → ready");
+  assert.equal(embedder.configured, true);
+
+  // Any of the four fields missing → not configured. `enabled` flips to false,
+  // the rest are blanked (the shape the settings panel leaves behind when the
+  // user never filled the vector section in).
+  for (const key of ["enabled", "baseUrl", "apiKey", "model"]) {
+    const broken = { ...FULL, [key]: key === "enabled" ? false : "" };
+    const { embedder: e } = make(broken);
+    assert.equal(e.configured, false, `blank ${key} → not configured`);
+    assert.equal(e.ready, false, `blank ${key} → not ready`);
+  }
+
+  // Defensive: a settings double returning {} (or nothing) must not throw.
+  assert.equal(make({}).embedder.ready, false);
+  assert.equal(make(undefined).embedder.ready, false);
+});
+
+test("#135 ready/configured are live getters, not boot-time snapshots", () => {
+  // The panel writes vector-config through settings; the legacy embedder reads
+  // it per call (same as embed()), so fixing the config must not need a restart.
+  const { embedder, box } = make(FULL, { live: true });
+  assert.equal(embedder.ready, true);
+  box.cfg = { ...FULL, apiKey: "" };
+  assert.equal(embedder.ready, false, "getter re-reads the live config");
+  assert.equal(embedder.configured, false);
+  box.cfg = FULL;
+  assert.equal(embedder.ready, true, "…and recovers once the config is complete");
+});
+
+test("#135 unconfigured embedder never reaches the network", async () => {
+  const { embedder, writes } = make({ ...FULL, apiKey: "" });
+  // A real fetch here would go out with an empty bearer token.
+  assert.equal(await embedder.embed("hello"), null);
+  assert.equal(await embedder.embedSingle("hello"), null);
+
+  embedder.schedule({ id: "m1", title: "t", content: "c" });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.deepEqual(writes, [], "schedule() must not store an embedding");
+
+  // A memory without an id is a no-op (never a store write with undefined id).
+  embedder.schedule(null);
+  embedder.schedule({});
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.deepEqual(writes, []);
+});
+
+test("#135 unconfigured embedder reports no model fingerprint or dimension", () => {
+  const { embedder } = make(FULL);
+  assert.equal(embedder.name, "OpenAI", "explicit name for the status card");
+  assert.equal(embedder.dimension, undefined, "no dimension before a first embed");
+  // model#hex — same fingerprint format the local embedders use.
+  assert.match(embedder.modelHash, /^text-embedding-3-small#[0-9a-f]+$/);
+  assert.equal(make({ ...FULL, model: "" }).embedder.modelHash, undefined);
+  assert.equal(make({ ...FULL, enabled: false }).embedder.modelHash, undefined);
+});
+
+// ── 覆盖补齐：embed 成功/降级、embedSingle 兜底、reindexMissing、schedule 成功路径 ──
+
+/** 临时替换全局 fetch（embedText 直接调它），fn 结束后恢复。 */
+async function withFetch(impl, fn) {
+  const original = globalThis.fetch;
+  globalThis.fetch = impl;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = original;
+  }
+}
+
+const okResponse = (embedding) => ({
+  ok: true,
+  json: async () => ({ data: [{ embedding }] })
+});
+
+test("embed: 完整配置时走真实 fetch，成功返回向量并记下维度", async () => {
+  const { embedder } = make(FULL);
+  await withFetch(async () => okResponse([1, 2, 3, 4]), async () => {
+    const vec = await embedder.embed("猫咪");
+    assert.deepEqual(vec, [1, 2, 3, 4]);
+    assert.equal(embedder.dimension, 4, "成功嵌入后记下维度供指纹用");
+  });
+});
+
+test("embed: 网络失败 / 非 2xx / 响应不可用都降级为 null，不抛", async () => {
+  const { embedder } = make(FULL);
+  await withFetch(async () => { throw new Error("ECONNREFUSED"); }, async () => {
+    assert.equal(await embedder.embed("x"), null);
+  });
+  await withFetch(async () => ({ ok: false }), async () => {
+    assert.equal(await embedder.embed("x"), null);
+  });
+  await withFetch(async () => ({ ok: true, json: async () => { throw new Error("bad json"); } }), async () => {
+    assert.equal(await embedder.embed("x"), null);
+  });
+  await withFetch(async () => ({ ok: true, json: async () => ({ data: [] }) }), async () => {
+    assert.equal(await embedder.embed("x"), null, "空 data 数组不可用");
+  });
+});
+
+test("embedSingle: embed 缺失时兜底返回 null（统一旧接口契约）", async () => {
+  const { embedder } = make(FULL);
+  assert.equal(await embedder.embedSingle.call({}, "x"), null, "无 embed 方法时返回 null 而非抛错");
+});
+
+test("reindexMissing: 逐行回填并统计 indexed/skipped，有成功才记模型指纹", async () => {
+  let markCalls = 0;
+  const rows = [{ id: "m1", title: "t1", content: "c1" }, { id: "m2", title: "t2", content: "c2" }];
+  const writes = [];
+  const embedder = createEmbedder({
+    store: {
+      setEmbedding: (id, v) => writes.push({ id, v }),
+      needsEmbedding: () => rows
+    },
+    settings: { getVectorConfig: () => FULL },
+    vectorIndex: { markModel: () => { markCalls++; } }
+  });
+  let call = 0;
+  await withFetch(async () => okResponse([call++, 0]), async () => {
+    const result = await embedder.reindexMissing(50);
+    assert.equal(result.indexed, 2);
+    assert.equal(result.skipped, 0);
+    assert.equal(writes.length, 2);
+    assert.equal(markCalls, 1, "有成功回填才记模型指纹");
+  });
+});
+
+test("reindexMissing: 未启用时直接返回 0/0，不碰 store", async () => {
+  const { embedder } = make({ ...FULL, enabled: false });
+  const result = await embedder.reindexMissing(50);
+  assert.deepEqual(result, { indexed: 0, skipped: 0 });
+});
+
+test("reindexMissing: 嵌入失败的行走 skipped，不算 indexed", async () => {
+  const writes = [];
+  const embedder = createEmbedder({
+    store: {
+      setEmbedding: (id, v) => writes.push({ id, v }),
+      needsEmbedding: () => [{ id: "m1", title: "t", content: "c" }]
+    },
+    settings: { getVectorConfig: () => FULL }
+  });
+  await withFetch(async () => ({ ok: false }), async () => {
+    const result = await embedder.reindexMissing(50);
+    assert.equal(result.indexed, 0);
+    assert.equal(result.skipped, 1, "嵌入失败的行走 skipped，不算 indexed");
+  });
+});
+
+test("schedule: 嵌入成功时写入 store 并记 info 日志（embedFor 成功路径）", async () => {
+  const writes = [];
+  let logged = 0;
+  const embedder = createEmbedder({
+    store: { setEmbedding: (id, v) => writes.push({ id, v }) },
+    settings: { getVectorConfig: () => FULL },
+    logger: { info: () => { logged++; }, warn() {} },
+    vectorIndex: { markModel() {} }
+  });
+  await withFetch(async () => okResponse([0.1, 0.2]), async () => {
+    embedder.schedule({ id: "m9", title: "t", content: "c" });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+  assert.equal(writes.length, 1);
+  assert.equal(logged, 1, "成功嵌入记一行 info 日志");
+});

package/test/helpers/runtime-source.js

@@ -0,0 +1,60 @@
+// test/helpers/runtime-source.js
+// 共享的「可收编源」夹具：CLI（scripts/mneme-runtime.mjs 的 adopt）与面板服务层
+// （src/runtime/adopt-service.js）两处的测试要造同一棵树。放这里是为了不让两份漂移 ——
+// 尤其是闭包必须能解出 onnxruntime-node / sharp，否则测的就不是「收编」这件事了。
+
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/** 结构检查点名到「平台 + 架构」，所以夹具必须用本机平台，否则 CI 上必挂。 */
+function writeNativeDir(nm) {
+  mkdirSync(join(nm, "onnxruntime-node", "bin", "napi-v6", process.platform, process.arch), { recursive: true });
+}
+
+/**
+ * 造一个最小可收编的 `<tmp>/node_modules`。
+ *
+ * transformers 必须把 onnxruntime-node / sharp 声明成自己的依赖，闭包计划才会收它们；
+ * 否则 payload 里不会有这两个包，结构检查会因为「缺必需包」失败，测的就不是收编了。
+ *
+ * `withMissingDep: true` 时再声明一个装不上的必需依赖：planClosure 会记一条 gap，
+ * 而 describePayload 只看那三个必需包 —— 这正是「结构说通过、闭包其实缺件」的场景。
+ * @param {{withMissingDep?: boolean}} [opts] - 选项。
+ * @returns {{base: string, nm: string, runtimeDir: string}} 临时根、源 node_modules、空白目标目录。
+ */
+export function makeSourceModules({ withMissingDep = false } = {}) {
+  const base = mkdtempSync(join(tmpdir(), "mneme-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 dependencies = {
+    "onnxruntime-node": "^1.24.3",
+    sharp: "^0.34.5",
+    ...(withMissingDep ? { "definitely-not-installed-pkg": "^1.0.0" } : {})
+  };
+  write(
+    "@huggingface/transformers/package.json",
+    JSON.stringify({ name: "@huggingface/transformers", version: "4.2.0", dependencies })
+  );
+  write("@huggingface/transformers/dist/transformers.node.mjs", "export const x = 1;\n");
+  write("onnxruntime-node/package.json", JSON.stringify({ name: "onnxruntime-node", version: "1.24.3" }));
+  write("sharp/package.json", JSON.stringify({ name: "sharp", version: "0.34.5" }));
+  writeNativeDir(nm);
+  return { base, nm, runtimeDir: mkdtempSync(join(tmpdir(), "mneme-dst-")) };
+}
+
+/**
+ * 空源：连 transformers 都没有。这是「profile 里根本没装」或 `--from` 指错目录时的真实输入，
+ * 也是曾经抛 TypeError 的那条路径。
+ * @returns {{base: string, nm: string, runtimeDir: string}}
+ */
+export function makeEmptyModules() {
+  const base = mkdtempSync(join(tmpdir(), "mneme-empty-"));
+  const nm = join(base, "node_modules");
+  mkdirSync(nm, { recursive: true });
+  return { base, nm, runtimeDir: mkdtempSync(join(tmpdir(), "mneme-dst-")) };
+}

package/test/helpers/tar-builder.js

@@ -0,0 +1,80 @@
+// test/helpers/tar-builder.js
+// 共享的 tar 造件器：tarball 读取层与取件层的测试都要造归档，放这里免得两份漂移。
+// 只造真东西（POSIX ustar 布局 + 正确的校验和），不引 tar 库 —— 那正是被测代码要回避的依赖。
+
+import { gzipSync } from "node:zlib";
+
+/** 一个 ustar 头块；字段布局照 POSIX，校验和按规范先按空格算再写回。 */
+export function tarHeader({ name = "", prefix = "", size = 0, type = "0" }) {
+  const header = Buffer.alloc(512);
+  header.write(name, 0, 100, "utf8");
+  header.write("0000644\0", 100, 8, "utf8");
+  header.write("0000000\0", 108, 8, "utf8");
+  header.write("0000000\0", 116, 8, "utf8");
+  header.write(`${size.toString(8).padStart(11, "0")}\0`, 124, 12, "utf8");
+  header.write("00000000000\0", 136, 12, "utf8");
+  header.write("        ", 148, 8, "utf8");
+  header.write(type, 156, 1, "utf8");
+  header.write("ustar\0", 257, 6, "utf8");
+  header.write("00", 263, 2, "utf8");
+  header.write(prefix, 345, 155, "utf8");
+  let sum = 0;
+  for (const byte of header) sum += byte;
+  header.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148, 8, "utf8");
+  return header;
+}
+
+/** 普通文件条目（数据按 512 对齐补齐）。 */
+export function tarFile(name, body, { prefix = "" } = {}) {
+  const data = Buffer.from(body, "utf8");
+  const padded = Buffer.alloc(Math.ceil(data.length / 512) * 512);
+  data.copy(padded);
+  return [tarHeader({ name, prefix, size: data.length, type: "0" }), padded];
+}
+
+/** 目录（"5"）/ 符号链接（"2"）等无数据条目。 */
+export function tarMeta(name, type) {
+  return [tarHeader({ name, size: 0, type })];
+}
+
+/** pax 扩展头：载荷是 `长度 path=值\n`。 */
+export function tarPax(path) {
+  const record = Buffer.from(`path=${path}\n`, "utf8");
+  const line = `${record.length + String(record.length).length} path=${path}\n`;
+  return [tarHeader({ name: "PaxHeaders/x", size: Buffer.byteLength(line), type: "x" }), padTo512(Buffer.from(line, "utf8"))];
+}
+
+/** 补齐到 512 的整数倍。 */
+export function padTo512(buffer) {
+  if (buffer.length % 512 === 0) return buffer;
+  const padded = Buffer.alloc(Math.ceil(buffer.length / 512) * 512);
+  buffer.copy(padded);
+  return padded;
+}
+
+/** 两个全零块 = 归档结束。 */
+export const END_BLOCKS = [Buffer.alloc(512), Buffer.alloc(512)];
+
+/**
+ * 造一份 .tgz。`entries` 每项：
+ *   { path, body }       普通文件（自动加 `package/` 前缀，除非 path 已含它）
+ *   { path, type }       目录/符号链接等（type 是 ustar 的 typeflag 字符）
+ *   { paxPath }          pax 头，覆盖下一条目的路径
+ * @param {Array<object>} entries - 条目。
+ * @param {{prefix?: string|null, end?: boolean}} [opts] - 前缀（默认 package/）、是否追加结束块。
+ * @returns {Buffer} gzip 后的归档。
+ */
+export function makeTgz(entries, { prefix = "package/", end = true } = {}) {
+  const blocks = [];
+  for (const entry of entries) {
+    if (entry.paxPath !== undefined) {
+      blocks.push(...tarPax(prefix === null ? entry.paxPath : `${prefix}${entry.paxPath}`));
+      continue;
+    }
+    const path = prefix === null || entry.path.startsWith(prefix) ? entry.path : `${prefix}${entry.path}`;
+    if (entry.type !== undefined) blocks.push(...tarMeta(path, entry.type));
+    else blocks.push(...tarFile(path, entry.body ?? ""));
+  }
+  if (end) blocks.push(...END_BLOCKS);
+  return gzipSync(Buffer.concat(blocks));
+}