@modusensus/dsh-mneme 0.8.16 → 0.9.1

package/test/store-write-path-columns.test.js

@@ -0,0 +1,191 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, writeFileSync, existsSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createMirror } from "../src/mirror.js";
+
+// 回归（issue #430）：写路径上的全表物化。此前每一次业务写都要走两处
+// all() + 逐行 toRow（27 字段 + 三次 JSON.parse）：
+//   1. 质量过滤的近重复判定只要最近 20 条 content，却先物化整库再 slice(0,20)
+//      （5k 行实测 100ms 级 → 本批换成单列有界查询后 0.06ms 级）；
+//   2. syncMirror 先物化整库再逐行 filter 掉 archived/forgotten/document。
+// 本批修复：store 新增单列有界读 recentContents()；list() 两条分支的 SELECT *
+// 换成显式列清单（memoryColumns，排除 embedding）；syncMirror 改走 list 的无界
+// 档 + SQL 侧过滤。下面四条锁不测墙钟（CI 矩阵 ubuntu+windows × node 22/24 并行，
+// 计时断言不稳），锁的是「谁被物化」这个形状本身。
+
+function make(over = {}) {
+  const store = createStore(":memory:");
+  return { store, config: { memoryQualityFilter: { enabled: true }, ...over } };
+}
+
+test("#430: recentContents mirrors the all() prefix it replaced", () => {
+  const { store } = make();
+  for (let i = 0; i < 25; i += 1) {
+    store.save({ type: "project", title: `t${i}`, content: `c${i}`, importance: 3 });
+  }
+  // 旧写法：all().slice(0, 20).map((m) => m.content ?? "")。集合锁与逐位锁都要：
+  // 一旦把 ORDER BY 丢掉（或反向），只要 LIMIT 不低于表行数，取到的行一个不少、
+  // 只是顺序全反过来，集合锁抓不到这类回归（变异检验证实，见 PR 讨论）。
+  // 逐位比较在此安全：store.js 的 per-instance 单调时间戳守卫保证同一实例内
+  // updated_at 严格递增，故这几行的先后关系是确定的。
+  const expected = store.all().slice(0, 20).map((m) => m.content ?? "");
+  const actual = store.recentContents(20);
+  assert.equal(actual.length, 20);
+  assert.deepEqual(actual, expected, "same 20 contents in the same order as the old prefix");
+  assert.deepEqual([...actual].sort(), [...expected].sort(), "same 20 contents as the old prefix (order-agnostic backstop)");
+  assert.equal(store.recentContents().length, 20, "default limit is 20");
+  assert.equal(store.recentContents(3).length, 3);
+  // sanitizePage 口径：0 / 负数 / 非整数落回默认值，而不是 SQLite 里 LIMIT 无界
+  assert.equal(store.recentContents(0).length, 20, "limit 0 falls back to the default, never unbounded");
+  assert.equal(store.recentContents(-1).length, 20);
+  assert.equal(store.recentContents(undefined).length, 20);
+  // 口径与 all() 一致：不过滤 archived（近重复判定要连归档内容一起看）
+  const { id } = store.save({ type: "project", title: "旧", content: "归档正文", importance: 3 });
+  store.setArchived(id, true);
+  assert.ok(store.recentContents(20).includes("归档正文"), "archived rows still take part in near-duplicate detection");
+  // 空库不炸
+  const fresh = createStore(":memory:");
+  assert.deepEqual(fresh.recentContents(20), []);
+  store.close();
+  fresh.close();
+});
+
+test("#430: list() projects columns and never leaks embedding", () => {
+  const { store } = make();
+  const { id } = store.save({ type: "project", title: "带向量", content: "正文", importance: 3 });
+  store.setEmbedding(id, [1, 0, 0]);
+  for (const opts of [{ limit: 50 }, { limit: null }, { order: "chrono", limit: 10 }, { type: "project", limit: null }]) {
+    const rows = store.list(opts);
+    assert.ok(rows.length > 0, `list(${JSON.stringify(opts)}) returned rows`);
+    for (const row of rows) {
+      assert.equal("embedding" in row, false, `embedding never leaks into list rows (${JSON.stringify(opts)})`);
+      assert.equal(typeof row.content, "string", "content still projected");
+    }
+  }
+  store.close();
+});
+
+test("#430: the write path reads explicit, bounded columns (no SELECT *, no embedding)", () => {
+  const { store } = make();
+  store.save({ type: "project", title: "带向量", content: "正文", importance: 3 });
+  // 语句级探针（不测墙钟）：SELECT * 会把全表最重的 embedding 列拖进内存再被
+  // toRow 丢掉，且无界档实测 5k 行 263ms → 117ms。这里直接看发出去的 SQL——
+  // 将来谁把列投影改回 SELECT *（或手工把 embedding 加回清单），本锁立刻转红，
+  // 而「行里没有 embedding」那条锁抓不到这种回归（toRow 本就不输出向量）。
+  const seen = [];
+  const orig = store.db.prepare.bind(store.db);
+  store.db.prepare = (sql) => { seen.push(String(sql)); return orig(sql); };
+  const listSql = seen.length;
+  store.list({ limit: 50 });
+  store.list({ limit: null });
+  store.list({ type: "project", limit: 10, order: "chrono" });
+  const probed = seen.length - listSql;
+  assert.ok(probed >= 3, `expected three distinct list queries, saw ${probed}`);
+  for (const sql of seen) {
+    assert.ok(!/SELECT\s+\*/i.test(sql), `write path must project explicit columns: ${sql}`);
+    assert.ok(!/\bembedding\b/.test(sql), `write path must not read the embedding column: ${sql}`);
+  }
+  // 质量过滤那条单列读同样要探：它一旦退回 SELECT *，多读的正是全表最重的列。
+  seen.length = 0;
+  store.recentContents(20);
+  assert.equal(seen.length, 1, "recentContents issues exactly one query");
+  assert.ok(!/SELECT\s+\*/i.test(seen[0]), `recentContents must read one column: ${seen[0]}`);
+  assert.ok(!/\bembedding\b/.test(seen[0]), "recentContents must not read the embedding column");
+  assert.match(seen[0], /\bLIMIT\b/i, `recentContents must stay bounded: ${seen[0]}`);
+  store.close();
+});
+
+test("#430: quality filter reads recent contents without materializing the table", () => {
+  const { store, config } = make();
+  // 抛错探针（先例 audit.test.js:182、mirror-dirty.test.js:383）：写路径一旦再退回
+  // all()，本用例立刻失败，而不是等到某个 profile 上再被观测到。
+  store.all = () => { throw new Error("write path must not materialize the whole table"); };
+  const service = createService({ store, mirror: null, config });
+  const base = "今天下午去操场跑步三圈然后回来洗澡";
+  const first = service.saveWithDedupe({ type: "history", title: "记录A", content: base });
+  assert.equal(first.action, "created");
+  const second = service.saveWithDedupe({ type: "history", title: "记录B", content: `${base}${base}${base}` });
+  const row = store.getById(second.memory.id);
+  assert.equal(row.archived, true, "near-duplicate still archived");
+  assert.ok(row.tags.includes("low_quality"), "low_quality tag still added");
+  assert.ok(row.quality_score < 30, `score still below the archive threshold: ${row.quality_score}`);
+});
+
+test("#430: syncMirror covers the active set without materializing it", () => {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-430-"));
+  try {
+    const { store, config } = make();
+    const mirror = createMirror(dir);
+    // 先按正常路径写一次，把镜像文件建起来
+    const seed = createService({ store, mirror, config });
+    const a = store.save({ type: "project", title: "活跃项目", content: "项目正文", importance: 3 });
+    store.save({ type: "preference", title: "偏好", content: "偏好正文", importance: 3 });
+    const hidden = store.save({ type: "project", title: "归档项目", content: "归档正文", importance: 3 });
+    store.setArchived(hidden.id, true);
+    const held = store.save({ type: "project", title: "遗忘项目", content: "遗忘正文", importance: 3 });
+    store.setForget(held.id, true);
+    seed.saveWithDedupe({ type: "project", title: "触发同步", content: "第一次触发同步的正文，长度足够不触发短内容规则", importance: 3 });
+
+    // 写路径不得再出现全表物化
+    store.all = () => { throw new Error("syncMirror must not materialize the whole table"); };
+    const svc = createService({ store, mirror, config });
+    const res = svc.saveWithDedupe({ type: "project", title: "第二次触发", content: "第二次触发同步的正文，内容与上一句不同以免被判近重复", importance: 3 });
+    assert.equal(res.action, "created");
+    assert.equal(res.memory.archived, false, "quality filter left it active (mirror only renders active rows)");
+
+    const text = readFileSync(join(dir, "projects.md"), "utf8");
+    assert.ok(text.includes(a.id), "active row still rendered");
+    assert.ok(text.includes(res.memory.id), "new row still rendered");
+    assert.ok(!text.includes("归档项目"), "archived row stays out");
+    assert.ok(!text.includes("遗忘项目"), "forgotten row stays out");
+    assert.ok(readFileSync(join(dir, "preferences.md"), "utf8").includes("偏好正文"), "sibling type rendered");
+    store.close();
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("#430: the document gate is decided in SQL, before anything is rendered", () => {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-430-doc-"));
+  try {
+    const { store, config } = make({ memoryQualityFilter: { enabled: true }, documentMemoryEnabled: false });
+    const mirror = createMirror(dir);
+    const svc = createService({ store, mirror, config });
+    // 真 document 行：doc_path 只能经 store.saveDocument 铸造（通用 save 整类拒绝）。
+    // 这条用例必须让库里真的有 document 行——上一版用例库里一行都没有，
+    // 「闸关时不渲染 document」就无法与「根本没见过 document」区分（变异检验漏网）。
+    const doc = store.saveDocument({
+      type: "document",
+      title: "指针文档",
+      content: "文档摘要正文，长度足够",
+      doc_path: "docs/pointer.md",
+      importance: 3
+    });
+    svc.saveWithDedupe({ type: "project", title: "项目", content: "项目正文，长度足够绕开短内容归档规则", importance: 3 });
+    const docPath = mirror.filePath("document");
+    // 闸关（#296 第二批默认）：有真指针行也不许渲染出 documents.md
+    assert.equal(existsSync(docPath), false, "documents.md stays absent while the gate is off");
+    // 陈旧视图必须被删掉：不留一个「看着还在、其实已关」的视图
+    writeFileSync(docPath, "陈旧视图", "utf8");
+    svc.saveWithDedupe({ type: "project", title: "再写一条", content: "再写一条正文，与上一条正文互不相似", importance: 3 });
+    assert.equal(existsSync(docPath), false, "stale documents.md pruned while the gate is off");
+    assert.equal(existsSync(join(dir, "index.md")), false, "index.md pruned while the gate is off");
+    assert.ok(readFileSync(join(dir, "projects.md"), "utf8").includes("项目正文"), "sibling type still rendered");
+    // 反向：闸开时同一份指针行确实会渲染（证明上面那条断言有判别力，而不是
+    // 因为 document 行从没进入过渲染集），关回去再必须删掉。
+    config.documentMemoryEnabled = true;
+    svc.saveWithDedupe({ type: "project", title: "闸开", content: "闸开后的正文，与前面几条互不相似", importance: 3 });
+    assert.ok(existsSync(docPath), "documents.md rendered while the gate is on");
+    assert.ok(readFileSync(docPath, "utf8").includes(doc.id), "pointer row is what gets rendered");
+    config.documentMemoryEnabled = false;
+    svc.saveWithDedupe({ type: "project", title: "闸关回去", content: "闸关回去后的正文，同样互不相似", importance: 3 });
+    assert.equal(existsSync(docPath), false, "documents.md pruned again once the gate flips back off");
+    store.close();
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/test/summarize.test.js

@@ -3,6 +3,9 @@ import assert from "node:assert/strict";
 import { mkdtempSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
+import { DatabaseSync } from "node:sqlite";
+import { Context } from "@deepseek-ai/cordis";
+import * as mneme from "../src/index.js";
 import { createStore } from "../src/store.js";
 import { createService } from "../src/service.js";
 import { createSummarizer, parseSummaryJson, parsePeakSpec, isInPeakWindow, nextOffPeakAt } from "../src/summarize.js";
@@ -1637,3 +1640,176 @@ test("issue#399: enabled=false (the default) writes nothing at all", async () =>
   assert.equal(countRows(store, "SELECT count(*) AS c FROM memory_provenance"), 0);
   assert.equal(store.count(), 2, "记忆写入照旧");
 });
+// ── 蒸馏留存：开关从「设置面」一路走到「盘上有行」 ──────────────────────────────
+//
+// 上面 #399 那五条锁的是 summarize.js 内部的行为，它们把 config 直接递给
+// createSummarizer。真实链路上，config 不来自测试也不来自 bundle：它由 index.js
+// 在**启动时**把 kv（feature_flags，面板 PUT /api/dsh-mneme/features 写的就是它）
+// 合并进 cfg 得到，再交给 createSummarizer。中间两环——设置面写入与启动期
+// 合并——一条测试都没覆盖过，而它们正是「distill_records 行数开始增长」这条
+// 验收判据的唯一通路：开关没写进 kv，或者写进了但装配时没被读出来，盘上就永远
+// 是 0 行，而 summarize.js 内部的五条锁照样全绿。
+//
+// 所以这两条不在 createSummarizer 层造 config，而是起一个最小宿主（真实 cordis
+// Context + 六个服务位），让 ctx.plugin(mneme, …) 走完 index.js 的装配：
+//   ① kv 写开 → 装配 → 派发 turn/end → 原文与溯源链接都落盘；
+//   ② 同一个装配但 kv 一个键都不写（默认态）→ 两表 0 行，记忆写入照旧。
+// 第二条守的是反面：装配默认不许把 opt-in 的开关私自打开。
+
+/** 最小宿主：六个服务位按 webServer-optional.test.js 的形状提供。 */
+function minimalHost() {
+  const ctx = new Context();
+  ctx.provide("tools", { register() { return () => {}; } });
+  ctx.provide("commands", { register() { return () => {}; } });
+  ctx.provide("systemPrompt", { context() { return () => {}; } });
+  ctx.provide("agentDefaultModel", { currentSelection() { return { provider: "mock", model: "mock" }; } });
+  ctx.provide("llm", {
+    async *stream() {
+      yield { type: "block-start", block: { type: "text" } };
+      yield {
+        type: "text-delta",
+        delta: JSON.stringify([
+          { type: "decision", title: "选型", content: "确定用 node:sqlite", importance: 4 },
+          { type: "preference", title: "语言", content: "用户喜欢中文交流", importance: 5 }
+        ])
+      };
+      yield { type: "block-end", block: { type: "text" } };
+      yield { type: "finish", kind: "ok" };
+    }
+  });
+  ctx.provide("webServer", { register() { return () => {}; } });
+  return ctx;
+}
+
+/** 盘上的三张表：装配前后各查一次，才知道行是谁写的。 */
+function readTables(dbPath) {
+  const db = new DatabaseSync(dbPath);
+  const count = (table) => db.prepare(`SELECT count(*) AS c FROM ${table}`).get().c;
+  const out = {
+    records: count("distill_records"),
+    provenance: count("memory_provenance"),
+    memories: count("memories")
+  };
+  out.rows = db.prepare("SELECT session_id, seq, role, text FROM distill_records ORDER BY seq").all();
+  db.close();
+  return out;
+}
+
+/** 装配 + 派发 turn/end + 拆掉装配（不给宿主留开着的手柄）。 */
+async function bootAndDistill(config, session) {
+  const ctx = minimalHost();
+  const fiber = ctx.plugin(mneme, config);
+  await fiber;
+  // ctx.parallel 会等所有监听器跑完；summarize.js 的监听器 return 了这次写入的
+  // promise（summarize.js 的 session/event 订阅处明写「Return the summarization
+  // promise so awaiters observe the writes」），所以并行派发完就是写完了。
+  await ctx.parallel("session/event", session, { seq: 2, type: "turn/end" });
+  await fiber.dispose();
+}
+
+test("distill records grow from the settings face all the way to disk", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "mneme-distill-on-"));
+  const dbPath = join(dir, "memory.db");
+  try {
+    // 第一环：用产品自己的设置面写 kv，等价于面板 PUT /api/dsh-mneme/features。
+    const seed = createStore(dbPath);
+    const merged = createSettings(seed.db).setFeatureFlags({ "distillRecords.enabled": true });
+    assert.equal(merged["distillRecords.enabled"], true, "开关必须先真的落进 kv");
+    assert.equal(readTables(dbPath).records, 0, "开之前盘上一行都没有");
+    seed.close();
+
+    // 第二环 + 第三环：装配时 bundle 说关、kv 说开，合并取 kv；然后真跑一次蒸馏。
+    await bootAndDistill(
+      { memoryDir: dir, distillRecords: { enabled: false }, distillRateLimitIntervalMs: 0 },
+      recordsSession("s-distill-on", [userMessage("这句话该落进 distill_records", 1), { seq: 2, type: "turn/end" }])
+    );
+
+    const after = readTables(dbPath);
+    assert.equal(after.records, 1, "装配读过 kv 之后，原文必须真的落盘");
+    assert.equal(after.rows[0].session_id, "s-distill-on");
+    assert.equal(after.rows[0].seq, 1);
+    assert.equal(after.rows[0].role, "user");
+    assert.match(after.rows[0].text, /该落进 distill_records/, "落盘的是公开正文原文");
+    assert.equal(after.memories, 2, "记忆照常写入，留存是叠加不是替换");
+    assert.equal(after.provenance, 2, "每条新记忆各落一条回指链接");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("the same assembly writes nothing when the flag was never set", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "mneme-distill-off-"));
+  const dbPath = join(dir, "memory.db");
+  try {
+    // 连 createStore 都不预先起：一个全新的库就是「从没碰过设置面」的真实形态。
+    await bootAndDistill(
+      { memoryDir: dir, distillRateLimitIntervalMs: 0 },
+      recordsSession("s-distill-off", [userMessage("默认态：不该有原文落盘", 1), { seq: 2, type: "turn/end" }])
+    );
+
+    const after = readTables(dbPath);
+    assert.equal(after.records, 0, "opt-in 的开关不许被装配私自打开");
+    assert.equal(after.provenance, 0);
+    assert.equal(after.memories, 2, "关的只是留存，蒸馏本身照常");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+
+// v0.9.0（M.O. 项目记忆）：机器提炼是写入量的绝大多数，而它此前一个作用域字段都不带
+// ——全库带 scope 的行不足 3%，且全部来自 memory_save 那条工具路径。这组用例钉住
+// 「蒸馏写入也盖章」这件事：值取 session.header（agentPreset + cwd），闸门与工具路径
+// 同一把（scopeEnabled），来源一律 'auto'（auto 不构成硬墙，只吃软加权，见
+// test/scope-strict.test.js 的 "auto and legacy rows are NOT hard walls" 用例，
+// 2026-10-13 在 :41-54）。
+function scopedSession(id, header) {
+  const session = {
+    id,
+    requestHeader: () => ({ config: { provider: "deepseek", model: "deepseek-chat" } }),
+    events: [userMessage("继续"), { seq: 2, type: "turn/end" }]
+  };
+  if (header !== undefined) session.header = header;
+  return session;
+}
+
+test("v0.9.0: scopeEnabled 开时蒸馏写入盖 auto 章（agent=agentPreset、workspace=header.cwd）", async () => {
+  const { events, store } = setup({ scopeEnabled: true });
+  const session = scopedSession("mo-scope", { agentPreset: "amarre", cwd: "C:\\work\\dsh-mneme" });
+  await eventHandler(events)(session, { seq: 2, type: "turn/end" });
+
+  const rows = store.list({ limit: null });
+  assert.equal(rows.length, 2, "两个条目都落库");
+  for (const row of rows) {
+    assert.equal(row.agent_scope, "amarre", "agent 维取自 session.header.agentPreset");
+    assert.equal(row.agent_scope_source, "auto", "来源必须标 auto：显式声明才会构成硬过滤");
+    assert.equal(row.workspace_scope, "C:\\work\\dsh-mneme", "workspace 维取自 session.header.cwd");
+    assert.equal(row.workspace_scope_source, "auto");
+  }
+});
+
+test("v0.9.0: 解析不出身份时照样标 auto、值落 NULL（与「从未标注」可区分）", async () => {
+  const { events, store } = setup({ scopeEnabled: true });
+  // 无 header、无 workspaceRegistry（mock ctx 只有 on/llm）：正是老会话/测试环境的形状。
+  await eventHandler(events)(scopedSession("mo-scope-anon"), { seq: 2, type: "turn/end" });
+
+  for (const row of store.list({ limit: null })) {
+    assert.equal(row.agent_scope, undefined);
+    assert.equal(row.workspace_scope, undefined);
+    // 关键区别：*_source='auto' 说明「自动标注跑过但没解析出值」，NULL 值才等于全局可见。
+    assert.equal(row.agent_scope_source, "auto");
+    assert.equal(row.workspace_scope_source, "auto");
+  }
+});
+
+test("v0.9.0: scopeEnabled 关时蒸馏写入一个 scope 字段都不加（老行为不变）", async () => {
+  const { events, store } = setup({});
+  await eventHandler(events)(scopedSession("mo-scope-off", { agentPreset: "amarre", cwd: "C:\\work\\dsh-mneme" }), { seq: 2, type: "turn/end" });
+
+  for (const row of store.list({ limit: null })) {
+    assert.equal(row.agent_scope, undefined);
+    assert.equal(row.agent_scope_source, undefined);
+    assert.equal(row.workspace_scope, undefined);
+    assert.equal(row.workspace_scope_source, undefined);
+  }
+});

package/test/supersede-state-tracking.test.js

@@ -337,10 +337,10 @@ test("supersede 后注入语义候选池（向量命中 / 语义缓存）不得
   const { store, service, legacy, current } = await supersededFixture({ embedder: semanticEmbedder() });
   service.setVectorIndex(leakyVectorIndex(store));
 
-  // 先填一次语义缓存：新查询的首帧 render 没有 queryVector（src/inject.js:327
-  // 的预取是异步 .then），只能吃 lastSemanticRecall。真实检索不会吐归档行，
-  // 是上面的假索引在源侧失守。填缓存的这一刻已经是 supersede 之后，所以缓存
-  // 条目里 loser 的 archived 是 true。
+  // 先填一次语义缓存：新查询的首帧 render 没有 queryVector（src/inject.js 的
+  // prefetchQueryVector 预取是异步 .then，2026-10-14 在 :296），只能吃
+  // lastSemanticRecall。真实检索不会吐归档行，是上面的假索引在源侧失守。填缓存
+  // 的这一刻已经是 supersede 之后，所以缓存条目里 loser 的 archived 是 true。
   const cached = await service.searchMemories(QUERY, { mode: "vector", useRerank: false, recordRecall: false });
   const cachedOld = cached.find((r) => r.id === legacy.id);
   // 夹具自检：确认缓存里确实躺着带 archived 标记的旧值，否则 (e) 是空压。

package/test/tools.test.js

@@ -8,6 +8,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { createTools } from "../src/tools.js";
 import { TRANSFORMERS_ENTRY, defaultModelCacheDir, payloadDir, payloadId } from "../src/runtime/layout.js";
+import { hostModulesDir } from "../src/runtime/provision.js";
 
 function setup(embedder, config = {}) {
   const store = createStore(":memory:");
@@ -370,7 +371,21 @@ test("memory_runtime：status 只读且带代价说明；两条来源都不可
   const provision = await tool.execute({ action: "provision" });
   assert.deepEqual(validateJsonSchemaValue(tool.output.schema, provision), []);
   assert.equal(provision.status, "failed");
-  assert.match(provision.reason, /收编失败|下载失败/);
+  // #323：车道（junction node_modules）里这条用例报过一次红，红的是下面那句「半份 payload」，
+  // 但变的是**环境**不是产品。所以把这条用例赖以成立的前提显式钉在这里：
+  // hostModulesDir 是 import.meta.url 的 4 级上溯，只有装入布局
+  // （<profile>/node_modules/@modusensus/dsh-mneme/src/tools.js → <profile>/node_modules）
+  // 才指向真的 node_modules；仓库根与车道布局下它落到仓库父目录 / <repo>\.worktrees，
+  // 于是收编在**计划阶段**就因「入口包不存在」零写入地失败——根本没走到物化分支，残留无从产生。
+  // （「物化到一半要清干净」由 runtime-adopt.test.js / runtime-download.test.js 的注入式用例负责，不靠这里。）
+  // 若有人改了目录层级、让源目录变成真的 node_modules，这一条会先红并把推导出的路径打出来，
+  // 而不是让「半份 payload」背一个看不懂的锅。
+  const source = hostModulesDir(new URL("../src/tools.js", import.meta.url).href);
+  assert.match(
+    provision.reason,
+    /收编失败：入口包不存在/,
+    `本用例的前提是「${source} 里没有可收编的 payload」；源目录换了形状，收编就会真的走物化分支（issue #323）`
+  );
   assert.equal(existsSync(runtimeDir) ? readdirSync(runtimeDir).length : 0, 0, "失败后不该留下半份 payload");
 });
 

package/test/workflow-guards.test.js

@@ -0,0 +1,156 @@
+// 工作流配置的回归锁：安全扫描、发布权限、发版准备的注入面不能悄悄退回。
+// 锁的都是「配置漂移」——CI 配置没有类型检查，改错了照样绿。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const repoRoot = path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))));
+
+test("security.yml 的 osv-scanner 保持 fail-on-vuln: true", () => {
+  // 2026-10 审计：这里原本是 false（纯提醒，PR 上永远是绿的）。改回 false 就等于
+  // 「有已知漏洞也不红」，而测试目录原本没有任何东西会察觉这件事。
+  const yml = readFileSync(path.join(repoRoot, ".github", "workflows", "security.yml"), "utf8");
+  assert.match(yml, /fail-on-vuln:\s*true/, "osv-scanner 必须保持 fail-on-vuln: true");
+  assert.doesNotMatch(yml, /fail-on-vuln:\s*false/, "不得退回只上传 SARIF 不拦的档位");
+});
+
+// 剥掉整行注释再断言：注释里会**描述**「id-token: write 该发给谁」，
+// 直接对全文 grep 会被自己写的说明文字骗过（第一版就栽在这里）。
+function codeOnly(yml) {
+  return yml.split(/\r?\n/).filter((l) => !/^\s*#/.test(l)).join("\n");
+}
+
+// 按缩进切出单个 job 的文本块：工作流顶层是 0 缩进，job 名是 2 缩进。
+// 只做文本切片不做完整 YAML 解析——仓库零依赖，为一条断言引 yaml 解析器不划算。
+function jobBlock(yml, name) {
+  const lines = codeOnly(yml).split(/\r?\n/);
+  const start = lines.findIndex((l) => l === "  " + name + ":");
+  assert.ok(start >= 0, "找不到 job: " + name);
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^  [A-Za-z0-9_-]+:$/.test(lines[i])) { end = i; break; }
+  }
+  return lines.slice(start, end).join("\n");
+}
+
+test("release.yml 的 provenance 权限只发给 publish，不发给工作流顶层", () => {
+  // 三件事分开断言，因为「全文件 grep id-token: write」会被两种错误都骗过：
+  //   ①有人把 id-token 提到工作流顶层（verify/test 也拿到 OIDC 能力）
+  //   ②有人把 publish 的权限删了但别的 job 还有（provenance 会失败）
+  const yml = readFileSync(path.join(repoRoot, ".github", "workflows", "release.yml"), "utf8");
+  assert.match(yml, /npm publish[^\n]*--provenance/, "publish 必须带 --provenance");
+
+  // YAML 允许把顶层键写成 "jobs": 或 'jobs':，那也是合法的工作流。
+  // 只匹配裸 jobs: 会在那种写法下把整个文件当成 head，于是 publish 里合法的
+  // id-token 被误判成「顶层声明」——失败方向是误红不是漏检，但假红会磨损这条锁。
+  const head = codeOnly(yml).split(/\r?\n(?=["']?jobs["']?:\s*$)/m)[0];
+  assert.doesNotMatch(head, /id-token:/, "工作流顶层不得声明 id-token（会泄漏给所有 job）");
+
+  const publish = jobBlock(yml, "publish");
+  assert.match(publish, /id-token:\s*write/, "publish job 需要 id-token: write");
+  assert.doesNotMatch(publish, /contents:\s*write/, "publish 只读代码，不需要 contents: write");
+
+  const release = jobBlock(yml, "release");
+  assert.match(release, /contents:\s*write/, "release job 建 Release 需要 contents: write");
+});
+
+// 把每个 `run: |` 块的正文切出来。要断言的是「脚本正文里没有模板展开」，
+// 而 run 块之外（env、with、name）出现 ${{ }} 是正常且必需的。
+function runBlocks(yml) {
+  const lines = codeOnly(yml).split(/\r?\n/);
+  const blocks = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^(\s*)run:\s*\|\s*$/.exec(lines[i]);
+    if (!m) continue;
+    const indent = m[1].length;
+    let j = i + 1;
+    for (; j < lines.length; j++) {
+      const line = lines[j];
+      if (!line.trim()) continue;
+      if (line.match(/^\s*/)[0].length <= indent) break;
+    }
+    blocks.push(lines.slice(i + 1, j).join("\n"));
+    i = j - 1;
+  }
+  return blocks;
+}
+
+test("release-prep.yml 的版本号走 env 注入，不内插进 run 脚本", () => {
+  // 2026-10 审计：zizmor 对 `--head "release-prep/${{ inputs.version }}"` 报 template-injection
+  // （模板展开可能带进攻击者可控的代码）。虽然上游 Validate 已用 ^[0-9]+\.[0-9]+\.[0-9]+$ 卡过格式，
+  // 但这里让扫描器看清「值不经过 shell 重解析」比让它推理上游校验够不够严便宜得多。
+  // 退回内插不会有任何测试变红，所以在这里锁住。
+  const yml = readFileSync(path.join(repoRoot, ".github", "workflows", "release-prep.yml"), "utf8");
+  assert.match(yml, /VERSION:\s*\$\{\{\s*inputs\.version\s*\}\}/, "版本号必须先进 env 再进脚本");
+  const blocks = runBlocks(yml);
+  assert.ok(blocks.length >= 3, "至少应切出 Validate / Count tests / Create PR 三个 run 块，实际 " + blocks.length);
+  for (const block of blocks) {
+    assert.doesNotMatch(block, /\$\{\{/, "run 脚本正文里不得出现模板展开：" + block.slice(0, 120));
+  }
+});
+
+test("release-prep.yml 与 badge:sync 用同一个记账口径（套件总数，不是通过数）", () => {
+  // v0.8.11 徽章漂移的同类失效：两条路径各有一套口径时，谁都不知道该信哪个数。
+  // 徽章报的是 CI（ubuntu）口径——平台条件跳过的用例在 pass 里不计、在 tests 里计入，
+  // 于是从一台有跳过条件的机器上跑发版准备，会写进一个比 badge:sync 小 1 的徽章，
+  // 而且它进 PR 时 CI 是绿的（徽章只出现在文档里，没有测试会去比对它）。
+  const yml = readFileSync(path.join(repoRoot, ".github", "workflows", "release-prep.yml"), "utf8");
+  const blocks = runBlocks(yml);
+  const countBlock = blocks.find((b) => /node --test/.test(b));
+  assert.ok(countBlock, "应当能切出跑测试的那个 run 块");
+  assert.ok(countBlock.includes("tests [0-9]+"), "计数必须取 tests N（与 sync-test-badge.mjs 同口径）");
+  assert.ok(!countBlock.includes("pass [0-9]+"), "不得退回 pass N：那是另一套记账口径");
+});
+
+test("发版准备的两份人写清单都点出跨 minor 要挪 SECURITY.md 支持版本表", () => {
+  // 跨 minor 时 security-doc.test.js 会红，而那时人往往已经忘了这张表——工作流开的 PR
+  // 就是最后一道能把话说清楚的时机。commit-msg 与 pr-body 是两份独立的文本，
+  // 少一份就等于一半的路径上没有提示（reviewer 只看 PR 正文，git log 只看提交信息）。
+  const yml = readFileSync(path.join(repoRoot, ".github", "workflows", "release-prep.yml"), "utf8");
+  const hits = yml.match(/SECURITY\.md 中英两张支持版本表/g) || [];
+  assert.equal(hits.length, 2, "commit message 与 PR 正文各要有一条，实际 " + hits.length);
+});
+
+test("release-prep.yml 的重跑守卫：已有 PR 不动分支，只覆盖机器产出", () => {
+  // 2026-10-18 实测：工作流 8 步里前 7 步全成功，最后一步 git push 被
+  // "! [rejected] release-prep/0.9.1 -> release-prep/0.9.1 (fetch first)" 打回——
+  // 上一次运行已经把同名分支推上去了。不可重入的代价不是「重跑失败」这么轻：
+  // 人会以为流程坏了，转去手工发版，整套自动化就此被绕开。
+  //
+  // 但「能重跑」不能退化成「无条件 force push」：分支上可能已经有人补过 CHANGELOG
+  // 条目，那正是这套流程留给人的那部分工作，覆盖掉比不能重跑更糟。所以守卫分三档：
+  // 有进行中的 PR → 什么都不动；顶端是机器产出且没有 PR → 按重跑覆盖；其他 → 停下要人看。
+  const yml = readFileSync(path.join(repoRoot, ".github", "workflows", "release-prep.yml"), "utf8");
+  const blocks = runBlocks(yml);
+  const pushBlock = blocks.find((b) => /git push/.test(b));
+  assert.ok(pushBlock, "应当能切出含 git push 的那个 run 块");
+
+  const prLookup = pushBlock.indexOf('--state open');
+  const pushAt = pushBlock.indexOf("git push");
+  assert.ok(prLookup > 0, "重跑前必须查有没有进行中的 PR（gh pr list --state open）");
+  assert.ok(prLookup < pushAt, "查 PR 必须发生在 push 之前");
+
+  // 三档判定：没有 PR 才继续；继续时顶端提交必须是本工作流生成的。
+  assert.ok(pushBlock.includes("--force-with-lease="), "重跑覆盖必须用 --force-with-lease（锁住 fetch 到的 SHA）");
+  assert.ok(!/git push[^\n]*--force(?!-with-lease)/.test(pushBlock), "不得退回无条件 --force");
+  // 断言的是那个 if 本身，不是变量名：变量名留在 case 里、判定被删掉，
+  // 只查 includes("MACHINE_TAIL") 照样绿（第一版就是这么漏的）。
+  assert.match(pushBlock, /if \[ "\$MACHINE_TAIL" != "yes" \]; then/, "必须有「顶端不是机器产出就停下」的那道判定");
+});
+
+test("release-prep.yml 开 PR 失败时给的是可行动的报错，不是裸 GraphQL 报错", () => {
+  // 第二个真因（2026-10-18 实测）：仓库级开关 can_approve_pull_request_reviews=false，
+  // job 里写 pull-requests: write 覆盖不了它，最后一步报
+  // "GitHub Actions is not permitted to create or approve pull requests"。
+  // 这个开关在**组织层**默认关着时仓库层根本改不动（gh api 返回 409 Conflict），
+  // 所以要让人一眼看出该去哪里开、开完能不能直接重跑。
+  const yml = readFileSync(path.join(repoRoot, ".github", "workflows", "release-prep.yml"), "utf8");
+  // 只在**可执行部分**里找：这几句话在注释里也出现过（注释是在解释为什么），
+  // 对全文 grep 会被自己写的说明文字骗过——报错文案被删干净了照样绿。
+  const code = codeOnly(yml);
+  assert.match(code, /not permitted to create or approve pull requests/, "报错文案要点名这个具体的 GitHub 报错，人才搜得到");
+  assert.match(code, /Settings → Actions → General/, "必须写清去哪个设置页开");
+  assert.match(code, /Allow GitHub Actions to create and approve pull requests/, "必须写清要打开的那个开关叫什么");
+});