@modusensus/dsh-mneme 0.9.0 → 0.9.2

package/test/api-hardening.test.js

@@ -0,0 +1,173 @@
+// 2026-10 供应链与代码安全审计的回归锁（宿主内 API 面）。
+// 锁的是四件事，防的回归各写在各用例注释里：
+//   1. /export 不再对任何调用方开放（审计 P0：配了 apiToken 也照旧全库导出）
+//   2. /external-api 的 GET 与 PUT 同门（审计 P0：未鉴权 GET 会明文回吐 8790 的
+//      Bearer，而且顺手把 token 铸造进库——一条不需要凭证的写路径）
+//   3. list/search 的分页参数有上界（免鉴权读面 + 浏览器简单请求 = 廉价 DoS）
+//   4. readBody 不再无界累积（4 MiB 上限，超限走 400 而不是把内存交给调用方）
+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 { createApi } from "../src/api.js";
+import { createSettings } from "../src/settings.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 req(path, method = "GET", body = null) {
+  const r = new EventEmitter();
+  r.url = path;
+  r.method = method;
+  r.headers = {};
+  if (body !== null) {
+    process.nextTick(() => {
+      r.emit("data", Buffer.from(JSON.stringify(body)));
+      r.emit("end");
+    });
+  }
+  return r;
+}
+
+function setup(apiToken = "") {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const settings = createSettings(store.db);
+  const commands = { add: () => {}, remove: () => {}, list: () => [] };
+  const routes = [];
+  const ctx = { webServer: { register(route) { routes.push(route); return () => {}; } } };
+  createApi(ctx, service, settings, commands, null, undefined, apiToken);
+  return { store, service, routes, settings };
+}
+
+function handler(routes, path) {
+  return routes.find((r) => r.path === path);
+}
+
+test("/export 在配置 apiToken 后必须带 Bearer", async () => {
+  // 审计 P0：这条路由长期没有鉴权分支，即使配了 token 也把全库（含
+  // archived/forgotten 全字段）交给任何能打到端口的人。
+  const { routes, service } = setup("secret-token");
+  service.saveWithDedupe({ type: "preference", title: "甲", content: "内容甲" });
+  const route = handler(routes, "/api/dsh-mneme/export");
+
+  let res = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/export"), res);
+  assert.equal(res.statusCode, 401, "无 token → 401");
+  assert.equal(JSON.parse(res.body).error, "unauthorized");
+
+  res = new FakeRes();
+  const ok = req("/api/dsh-mneme/export?format=json");
+  ok.headers = { authorization: "Bearer secret-token" };
+  await route.handler(ok, res);
+  assert.equal(res.statusCode, 200, "带对 token → 200");
+  assert.equal(JSON.parse(res.body).count, 1);
+});
+
+test("/external-api 的 GET 与 PUT 同门，未鉴权不铸造 token", async () => {
+  // 两个回归一起锁：①未鉴权 GET 能把 8790 的 Bearer 明文读走；②那次 GET 还会
+  // 顺手 randomBytes 铸造并持久化一个 token——没有凭证的写路径。
+  const { routes, settings } = setup("secret-token");
+  const route = handler(routes, "/api/dsh-mneme/external-api");
+
+  const res = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/external-api"), res);
+  assert.equal(res.statusCode, 401);
+  assert.equal(settings.getExternalApi()?.token, undefined, "未鉴权请求不得铸造 token");
+
+  const ok = req("/api/dsh-mneme/external-api");
+  ok.headers = { authorization: "Bearer secret-token" };
+  const res2 = new FakeRes();
+  await route.handler(ok, res2);
+  assert.equal(res2.statusCode, 200);
+  assert.ok(JSON.parse(res2.body).config.token.length >= 16, "鉴权后照旧发 token");
+});
+
+test("list 的 limit 被上界钳制", async () => {
+  // 上界是防御：limit 直接进 SQL LIMIT，?limit=100000 会让一次免鉴权 GET 把
+  // 全库序列化出来（浏览器 <img> 就能触发）。
+  const { routes, service } = setup();
+  let seen = null;
+  const original = service.list;
+  service.list = (args) => { seen = args; return []; };
+  const res = new FakeRes();
+  await handler(routes, "/api/dsh-mneme/list").handler(req("/api/dsh-mneme/list?limit=100000"), res);
+  assert.equal(res.statusCode, 200);
+  assert.equal(seen.limit, 1000);
+  service.list = original;
+});
+
+test("search 的 topK 被上界钳制", async () => {
+  const { routes, service } = setup();
+  let seen = null;
+  const original = service.searchMemories;
+  service.searchMemories = (q, opts) => { seen = opts; return []; };
+  const res = new FakeRes();
+  await handler(routes, "/api/dsh-mneme/search").handler(req("/api/dsh-mneme/search?q=abc&topK=100000"), res);
+  assert.equal(res.statusCode, 200);
+  assert.equal(seen.topK, 200);
+  service.searchMemories = original;
+});
+
+function oversizedPost(path, method = "POST") {
+  const huge = Buffer.from("{\"content\":\"" + "x".repeat(5 * 1024 * 1024) + "\"}");
+  const r = new EventEmitter();
+  r.url = path;
+  r.method = method;
+  r.headers = {};
+  process.nextTick(() => { r.emit("data", huge); r.emit("end"); });
+  return r;
+}
+
+test("超大请求体回 413，且不落库", async () => {
+  // 4 MiB 上限。断言必须是**明确的 413**：旧写法只断言 notEqual(200)，而 /create
+  // 成功时回 201——一个真被写进去的超限请求也能让那条断言通过（评审指出的空断言）。
+  const { routes, service } = setup();
+  const before = service.all().length;
+  const res = new FakeRes();
+  await handler(routes, "/api/dsh-mneme/create").handler(oversizedPost("/api/dsh-mneme/create"), res);
+  assert.equal(res.statusCode, 413);
+  assert.equal(JSON.parse(res.body).error, "payload-too-large");
+  assert.equal(service.all().length, before, "超限请求不得留下任何记忆");
+});
+
+test("超限后又来 transport error，仍回 413 且不写库", async () => {
+  // readBody 的超限状态必须活过 error 分支：旧实现 error 时 resolve("")，
+  // 调用点只认 null，于是拿着空串继续走 → PUT /persona 把 "" 解析成 {}，
+  // 覆盖既有设置。这条锁的就是「413 发出去了，但后面的写入还在跑」。
+  const { routes, settings } = setup("secret-token");
+  settings.setRules(["别丢"]);
+  const huge = Buffer.from("x".repeat(5 * 1024 * 1024));
+  const r = new EventEmitter();
+  r.url = "/api/dsh-mneme/rules";
+  r.method = "PUT";
+  r.headers = { authorization: "Bearer secret-token" };
+  const res = new FakeRes();
+  const done = handler(routes, "/api/dsh-mneme/rules").handler(r, res);
+  process.nextTick(() => { r.emit("data", huge); r.emit("error", new Error("boom")); });
+  await done;
+  assert.equal(res.statusCode, 413);
+  assert.deepEqual(settings.getRules(), ["别丢"], "error 分支不得让空体落库");
+});
+
+test("超大请求体不会清空画像／规则", async () => {
+  // 这是最要命的一条：readBody 旧实现超限回空串 → parseBody 得到 {} →
+  // setProfile("") / setRules([]) 把既有内容静默清掉。413 必须在碰 store 之前。
+  const { routes, settings } = setup("secret-token");
+  settings.setProfile("原有画像");
+  settings.setRules(["原有规则"]);
+
+  for (const [path, method] of [["/api/dsh-mneme/profile", "PUT"], ["/api/dsh-mneme/rules", "PUT"]]) {
+    const res = new FakeRes();
+    const req = oversizedPost(path, method);
+    req.headers = { authorization: "Bearer secret-token" };
+    await handler(routes, path).handler(req, res);
+    assert.equal(res.statusCode, 413, path + " 超限应回 413");
+  }
+  assert.equal(settings.getProfile(), "原有画像", "超限请求不得清空画像");
+  assert.deepEqual(settings.getRules(), ["原有规则"], "超限请求不得清空规则");
+});

package/test/api.test.js

@@ -538,6 +538,63 @@ test("GET /api/dsh-mneme/semantic reports configured/coverage/degraded", async (
   assert.equal(noIndex.degraded, false);
 });
 
+// --- distill-tx-embed-gap 后续：/semantic 区分「有向量」与「可检索」 -----------
+
+test("GET /api/dsh-mneme/semantic reports per-dimension/per-model vector breakdown", async () => {
+  const { routes, store, service } = setup(undefined);
+  // 三种状态混进一个库：3 维 2 条、旧 4 维 1 条、不可解析 1 条；
+  // 模型出身 m1#aaa 一行、m2#bbb 一行、无出身两行。
+  const a = service.saveWithDedupe({ type: "preference", title: "同维A", content: "x" }).memory;
+  const b = service.saveWithDedupe({ type: "preference", title: "同维B", content: "x" }).memory;
+  const c = service.saveWithDedupe({ type: "preference", title: "旧维C", content: "x" }).memory;
+  const d = service.saveWithDedupe({ type: "preference", title: "坏D", content: "x" }).memory;
+  store.db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run(JSON.stringify([1, 2, 3]), a.id);
+  store.db.prepare("UPDATE memories SET embedding = ?, embedding_model = ? WHERE id = ?").run(JSON.stringify([1, 2, 3]), "m1#aaa", b.id);
+  store.db.prepare("UPDATE memories SET embedding = ?, embedding_model = ? WHERE id = ?").run(JSON.stringify([1, 2, 3, 4]), "m2#bbb", c.id);
+  store.db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run("not-json", d.id);
+
+  const sem = routes.find((r) => r.path === "/api/dsh-mneme/semantic");
+  const res = new FakeRes();
+  await sem.handler(req("/api/dsh-mneme/semantic"), res);
+  assert.equal(res.statusCode, 200);
+  const data = JSON.parse(res.body);
+
+  // 无 embedder → 无当前维度可比对：unsearchable 报 0、retrievable 报 null。
+  assert.equal(data.vectors.unsearchable, 0);
+  assert.equal(data.vectors.retrievable, null);
+  const dims = Object.fromEntries(data.vectors.byDimension.map((e) => [e.dimension, e.count]));
+  assert.equal(dims["3"], 2);
+  assert.equal(dims["4"], 1);
+  assert.equal(dims[null], 1, "unparseable vector counted under null");
+  const models = Object.fromEntries(data.vectors.byModel.map((e) => [e.model, e.count]));
+  assert.equal(models["m1#aaa"], 1);
+  assert.equal(models["m2#bbb"], 1);
+  assert.equal(models[null], 2, "rows without provenance counted under null");
+});
+
+test("GET /api/dsh-mneme/semantic counts stale-dimension rows as unsearchable with a matching embedder", async () => {
+  // 核心回归锁：库里掺一条错维向量，端点必须报出 unsearchable ≥ 1。
+  // 旧实现无论怎么混都只给 coverage，状态卡说不出「有向量但检索不到」。
+  const { routes, store, service } = setup({ name: "OpenAI", embed() {}, dimension: 3 });
+  const a = service.saveWithDedupe({ type: "preference", title: "同维", content: "x" }).memory;
+  const b = service.saveWithDedupe({ type: "preference", title: "错维", content: "x" }).memory;
+  store.db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run(JSON.stringify([1, 2, 3]), a.id);
+  store.db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run(JSON.stringify([1, 2, 3, 4, 5, 6, 7, 8]), b.id);
+  const sem = routes.find((r) => r.path === "/api/dsh-mneme/semantic");
+  const res = new FakeRes();
+  await sem.handler(req("/api/dsh-mneme/semantic"), res);
+  assert.equal(res.statusCode, 200);
+  const data = JSON.parse(res.body);
+  assert.equal(data.vectors.unsearchable, 1, "the 8-dim row is not searchable against a 3-dim embedder");
+  assert.equal(data.vectors.retrievable, 1, "the 3-dim row is searchable");
+  // coverage 走 semantic.vectorIndex.getStats（本测试未挂 → 0），所以「有向量的行」
+  // 用 byDimension 总和对照：两条都在「有向量」里，但只有一条可检索 —— 这正是
+  // unsearchable 必须存在的原因。
+  const embeddedRows = data.vectors.byDimension.reduce((s, e) => s + e.count, 0);
+  assert.equal(embeddedRows, 2, "both rows have vectors");
+  assert.equal(data.vectors.unsearchable, 1, "yet only one is retrievable");
+});
+
 // --- Bug8: llm-audit API (pagination + stats) --------------------------------
 
 test("GET /api/dsh-mneme/semantic/llm-audit returns paginated rows", async () => {
@@ -682,9 +739,15 @@ test("GET /api/dsh-mneme/features returns empty overrides and effective config d
   // 溯源：开关与保留期都在嵌套对象里，两个都进 NESTED_FLAG_PATHS））
   // v0.9.0 新增 actionPipelineEnabled（M.O. beta 门控；顶层扁平键，
   // 走 configFlagValue 默认分支，不需要 NESTED_FLAG_PATHS 条目）。
+  // v0.9.0 第二批新增 actionRunEnabled（M.O. 执行记账；同样顶层扁平键）。
+  // persona 页新增 personaEnabled（人格注入顶层总闸；顶层扁平键，同上）。
   // 计数锁钉的是「白名单键 ↔ config schema 成对」：schema 加了键而漏了白名单
   // （或反过来）时，effective 会静默少键/多键，面板读不到也报不出来。
-  assert.equal(Object.keys(data.effective).length, 59 + 3 + 2 + 1 + 2 + 2 + 2 + 1 + 1 + 1 + 2 + 1 + 2 + 1 + 3 + 2 + 2 + 1 + 1 + 1 + 1 + 2 + 1 + 2 + 1);
+  // issue #471 新增 scopeState.enabled/scopeState.enforce（政策轴作用域级可逆闸门；
+  // 两个都是嵌套对象子字段，都进 NESTED_FLAG_PATHS）。
+  // 合并 #451（人格页）后的真实计数：98（本批前）+ actionRunEnabled + personaEnabled = 99
+  // #471 再 + 2 = 101。
+  assert.equal(Object.keys(data.effective).length, 101);
   assert.equal(data.effective.dreamSkipInvalid, true);
   assert.equal(data.effective.allowCrossTypeMerge, false);
   assert.equal(data.effective.dreamMergeGuard, true);
@@ -692,6 +755,9 @@ test("GET /api/dsh-mneme/features returns empty overrides and effective config d
   // issue #380：注入前判定两级开关，默认全关（默认路径零行为变化）
   assert.equal(data.effective["preInjectGate.enabled"], false);
   assert.equal(data.effective["preInjectGate.enforce"], false);
+  // issue #471：政策轴作用域级可逆闸门，两级开关默认全关（默认路径零行为变化）
+  assert.equal(data.effective["scopeState.enabled"], false);
+  assert.equal(data.effective["scopeState.enforce"], false);
   assert.equal(data.effective.dreamMinIntervalMinutes, 0);
   assert.equal(data.effective.autoDreamFailureBackoff, false);
   assert.equal(data.effective.dreamMaxTokens, 131072);
@@ -721,6 +787,11 @@ test("GET /api/dsh-mneme/features returns empty overrides and effective config d
   // v0.9.0：M.O. beta 门控默认关——客户端 GET /features 必须能读到这个键
   // （读不到就静默不注册任何座位），且默认值必须是 false（beta opt-in）。
   assert.equal(data.effective.actionPipelineEnabled, false);
+  // v0.9.0 第二批：M.O. 执行记账同样默认关，且**是独立的一个键**——看图与写账
+  // 分开，避免「只想看图」的人不知不觉获得热路径上的写入能力。
+  assert.equal(data.effective.actionRunEnabled, false);
+  // 人格页（beta）：注入总闸默认关，effective 必须能读到（同 #254 坑形防线）。
+  assert.equal(data.effective.personaEnabled, false);
   // 新增字符串 / URL / 枚举键
   assert.equal(data.effective.localEmbedModel, "Xenova/bge-small-zh-v1.5");
   assert.equal(data.effective.ollamaBaseUrl, "http://localhost:11434");
@@ -747,6 +818,47 @@ test("GET /api/dsh-mneme/features returns empty overrides and effective config d
   assert.equal(data.effective.dreamCandidateMode, "window");
   assert.equal(data.effective.dreamCandidateMax, 0);
   assert.equal(data.effective.dreamCandidateMinSim, 0.85);
+  // #481：没有 overrides 时不存在「改了还没生效」的键，必须是空数组而不是缺字段
+  // ——面板按数组长度渲染提示条，字段缺失会让它渲染出 undefined.length 这类东西。
+  assert.ok(Array.isArray(data.pendingRestart), "pendingRestart must always be an array");
+  assert.deepEqual(data.pendingRestart, []);
+});
+
+test("GET /api/dsh-mneme/features reports only the overrides the frozen config has not picked up", async () => {
+  const { routes, settings } = setup(undefined, "", FLAGS_CFG);
+  const route = routes.find((r) => r.path === "/api/dsh-mneme/features");
+  // #481 实测现场：面板显示人格总闸「已开启」，人格段却不注入——因为开关在宿主
+  // 启动时合并进 cfg 并冻结，运行中改 kv 只是持久化。pendingRestart 就是把
+  // 「显式覆盖 ≠ 冻结值」这个落差报出来，否则用户只能靠反复试错发现。
+  settings.setFeatureFlags({
+    personaEnabled: true,                 // 冻结值 false → 待重启
+    autoDream: false,                     // 冻结值 true  → 待重启
+    "memoryQualityFilter.enabled": false, // 冻结值 true  → 待重启
+    distillMaxChars: 24000                // 与冻结值相同 → 不该报
+  });
+  const res = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/features"), res);
+  assert.equal(res.statusCode, 200);
+  const data = JSON.parse(res.body);
+  // 比的是集合而非顺序（顺序跟白名单分组走，不是契约的一部分）。
+  assert.deepEqual([...data.pendingRestart].sort(), ["autoDream", "memoryQualityFilter.enabled", "personaEnabled"]);
+  assert.ok(!data.pendingRestart.includes("distillMaxChars"),
+    "a key whose override equals the frozen value is not pending");
+  // effective 仍然是「运行时取什么值」= overrides 优先，不受本字段影响。
+  assert.equal(data.effective.personaEnabled, true);
+});
+
+test("GET /api/dsh-mneme/features cannot report pendingRestart without a frozen config", async () => {
+  // config 缺席（旧调用方直连、未传 cfg）时无从比较冻结值——返回空数组，不编造。
+  const { routes, settings } = setup(undefined);
+  settings.setFeatureFlags({ personaEnabled: true });
+  const route = routes.find((r) => r.path === "/api/dsh-mneme/features");
+  const res = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/features"), res);
+  assert.equal(res.statusCode, 200);
+  const data = JSON.parse(res.body);
+  assert.deepEqual(data.pendingRestart, []);
+  assert.equal(data.effective.personaEnabled, true, "effective still reports the override");
 });
 
 test("PUT /api/dsh-mneme/features round-trips, overrides effective and persists", async () => {
@@ -784,6 +896,9 @@ test("PUT /api/dsh-mneme/features round-trips nested, string, url and enum keys"
     // NESTED_FLAG_PATHS——否则 configFlagValue 落到顶层同名键上，effective 静默缺键）。
     "distillRecords.enabled": true,
     "distillRecords.retentionDays": 30,
+    // #471：政策轴的两个点号键往返——白名单与 NESTED_FLAG_PATHS 成对缺一即静默缺键。
+    "scopeState.enabled": true,
+    "scopeState.enforce": true,
     // #164 A2：顶层扁平键（不是对象子字段），与上面两个点号键走同一条往返；
     // 它的默认值断言在计数锁那一条里，这里钉的是「PUT 存进去、effective 读得回」。
     sensitiveScanEnabled: true,
@@ -805,6 +920,8 @@ test("PUT /api/dsh-mneme/features round-trips nested, string, url and enum keys"
     "preInjectGate.enforce": true,
     "distillRecords.enabled": true,
     "distillRecords.retentionDays": 30,
+    "scopeState.enabled": true,
+    "scopeState.enforce": true,
     sensitiveScanEnabled: true,
     embedProvider: "local",
     ollamaBaseUrl: "http://127.0.0.1:11434",
@@ -821,6 +938,9 @@ test("PUT /api/dsh-mneme/features round-trips nested, string, url and enum keys"
   assert.equal(data.effective["preInjectGate.enforce"], true);
   assert.equal(data.effective["distillRecords.enabled"], true);
   assert.equal(data.effective["distillRecords.retentionDays"], 30, "整数点号键也要读得回来");
+  // #471：政策轴两个点号键同款往返
+  assert.equal(data.effective["scopeState.enabled"], true);
+  assert.equal(data.effective["scopeState.enforce"], true);
   assert.equal(data.effective.sensitiveScanEnabled, true);
   assert.equal(data.effective.embedProvider, "local");
   assert.equal(data.effective.ollamaBaseUrl, "http://127.0.0.1:11434");
@@ -1863,3 +1983,92 @@ test("GET /api/dsh-mneme/inject-preview: returns last assembly snapshot (issue #
   assert.equal(res.statusCode, 404);
   injector(); // 快照是模块全局：用完即清，不污染后续用例
 });
+
+// --- /pipeline：观察旁挂能真的挂进投影（CodeRabbit #458 F1 的锁）--------------
+
+test("GET /api/dsh-mneme/pipeline 带观察旁挂：observationsById 真的进了投影而不是被 catch 吞掉", async () => {
+  // 锁 F1：ids 原本声明在账本分支的块级作用域里，旁挂块一引用就 ReferenceError，
+  // 被 catch 静默吞成「没有观察」——面板上一切正常，fix-step-tool 提议却永远少一类。
+  const { mkdtempSync, mkdirSync, writeFileSync, rmSync } = await import("node:fs");
+  const { tmpdir } = await import("node:os");
+  const { join } = await import("node:path");
+  const { saveObservations } = await import("../src/pipeline-observations.js");
+
+  const root = mkdtempSync(join(tmpdir(), "mo-api-f1-"));
+  try {
+    const project = join(root, "proj");
+    const pipeline = {
+      id: "demo-f1",
+      name: "演示F1",
+      project: "someone/repo",
+      version: 0,
+      status: "active",
+      done: "做完",
+      trigger: [{ kind: "phrase", value: "跑一下" }],
+      steps: [{
+        id: "S1",
+        phase: "做",
+        title: "跑测试",
+        when: "有人要跑",
+        do: "npm test",
+        who: "main",
+        tool: "npm test",
+        done: "测试全绿",
+        risk: "R0",
+        needs: [],
+        why: "没有它后面没得跑",
+        evidence: ["跑过"]
+      }]
+    };
+    // 项目层工作流（<project>/.mneme/pipelines/*.json）
+    mkdirSync(join(project, ".mneme", "pipelines"), { recursive: true });
+    writeFileSync(join(project, ".mneme", "pipelines", "demo-f1.json"), JSON.stringify(pipeline));
+    // 运行账：<project>/.mneme/pipelines/<id>.runs.jsonl（有账才走到旁挂分支）。
+    // 行形状走 normalizeRun 契约：run.at/by + step.at 全必填（时间不补默认）。
+    writeFileSync(
+      join(project, ".mneme", "pipelines", "demo-f1.runs.jsonl"),
+      JSON.stringify({ at: "2026-10-17T01:00:00.000Z", by: "main", steps: [{ id: "S1", at: "2026-10-17T01:00:00.000Z", skipped: false, detoured: false, refuted: false }] }) + "\n"
+    );
+    // 观察旁挂：<memoryDir>/observations/<项目键>/demo-f1.jsonl。项目键走 candidates.js
+    // 的 projectKey(projectRoot)（sha256 前 8 位 + 清洗名），与 api.js 同源——不能用
+    // 裸 observations/ 目录，那不是 api 侧会查的桶。
+    const { projectKey } = await import("../src/candidates.js");
+    const memoryDir = join(root, "memory");
+    const odir = join(memoryDir, "observations", projectKey(project));
+    const saved = saveObservations({
+      dir: odir,
+      pipelineId: "demo-f1",
+      confirmAt: "2026-10-17T02:00:00.000Z",
+      activities: [{ key: "git push", count: 2 }]
+    });
+    assert.equal(saved.ok, true);
+
+    const { routes } = setup(undefined, "", { memoryDir });
+    const route = routes.find((r) => r.path === "/api/dsh-mneme/pipeline");
+    const res = new FakeRes();
+    await route.handler(req(`/api/dsh-mneme/pipeline?id=demo-f1&project=${encodeURIComponent(project)}`), res);
+    assert.equal(res.statusCode, 200);
+    const data = JSON.parse(res.body);
+    const row = (data.available || []).find((r) => r.id === "demo-f1");
+    assert.ok(row, "工作流要出现在清单里");
+    assert.ok(data.pipeline, "选中投影要存在");
+    // F1 的直接断言：观察旁挂真的喂进了 suggestions 的判据（修复前 observationsById
+    // 恒为 {}——ReferenceError 被 catch 吞掉，观察永远空）。
+    // 观察里只写了 git push，而 S1 声明 tool=npm test 且账本确认走过 1 次 → 矛盾
+    // 成立，fix-step-tool 必须冒头（下方正向锁）；观察为空时它不该冒，那是
+    // pipeline.test.js 的判据锁。
+    // runsState 是账本健康度（RUNS_STATES: absent/empty/ok/partial/broken），
+    // 不是节点状态——账本一行合法 run 即为 ok。节点级 trusted 由 deriveState 管，
+    // 在 summarizePipeline 的 perNode 里，这里不重复锁。
+    assert.equal(row.runsState, "ok", "账本一行合法 run，健康度应是 ok");
+    // suggestions 在投影顶层（不在 pipeline 对象下）。
+    assert.ok(Array.isArray(data.suggestions), "投影必须带 suggestions 数组");
+    // 正向锁：观察里只有 git push、S1 声明 npm test 且确认走过 → fix-step-tool 必须冒头。
+    // F1 未修时 observationsById 恒为空，这条断言必挂——正是要抓的回归。
+    const fix = data.suggestions.find((s) => s.kind === "fix-step-tool");
+    assert.ok(fix, "观察进了判据（npm test 未见于观察）→ 必须有 fix-step-tool 提议");
+    assert.equal(fix.stepId, "S1");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/test/changelog-prep.test.js

@@ -18,18 +18,84 @@ const hasBareLf = (text) => /(^|[^\r])\n/.test(text);
 test("LF 输入：插入占位节，行尾保持 LF，旧内容原样保留", () => {
   const r = insertReleaseSection(LF_HEAD, "0.8.13", "2026-10-03");
   assert.equal(r.ok, true);
-  assert.ok(r.text.startsWith("# Changelog\n\n## [0.8.13] - 2026-10-03"), "插在标题之后");
+  assert.ok(r.text.startsWith("# Changelog\n\n## [0.8.13] - 2026-10-03"), "没有 [Unreleased] 时插在标题之后");
   assert.ok(r.text.includes("- （待填）"), "带 release.yml verify 要的占位节");
   assert.ok(r.text.includes("## [0.8.12] - 2026-10-01"), "旧内容不动");
   assert.equal(r.text.includes("\r\n"), false, "不该往 LF 文件里混 CRLF");
 });
 
-test("CRLF 输入：同样能插（原先这里静默 no-op —— 本模块存在的首要理由）", () => {
-  const r = insertReleaseSection(CRLF_HEAD, "0.8.13", "2026-10-03");
-  assert.equal(r.ok, true, "CRLF 检出上必须也能插入");
-  assert.notEqual(r.text, CRLF_HEAD, "绝不返回原文——那正是当初的假成功");
-  assert.ok(r.text.includes("## [0.8.13] - 2026-10-03"));
-  assert.equal(hasBareLf(r.text), false, "插入的内容也要用 CRLF，不混行尾");
+test("有 [Unreleased] 时插在它下面，不插在上面", () => {
+  // Keep a Changelog 的约定：未发布区在最上，新版本节排在它下面。
+  // 插反了会得到「[0.9.1] 在 [Unreleased] 之上」——v0.9.0 那次就是靠事后人工提交
+  // （77df0fb）掰回来的，机器算得对的事不该留给人补。
+  const src = "# Changelog\n\n## [Unreleased]\n\n## 🐛 修复\n\n- 攒着的条目\n\n## [0.9.0] - 2026-10-17\n\n- 旧版本\n";
+  const r = insertReleaseSection(src, "0.9.1", "2026-10-18");
+  assert.equal(r.ok, true);
+  assert.ok(
+    r.text.indexOf("## [Unreleased]") < r.text.indexOf("## [0.9.1] - 2026-10-18"),
+    "[Unreleased] 必须排在前面"
+  );
+  assert.ok(
+    r.text.indexOf("## [0.9.1] - 2026-10-18") < r.text.indexOf("## [0.9.0] - 2026-10-17"),
+    "新版本节又必须排在上一版之前"
+  );
+  assert.ok(r.text.includes("- 攒着的条目"), "[Unreleased] 里攒的条目不许丢");
+  assert.ok(r.text.includes("- 旧版本"), "旧版本节不许丢");
+  assert.equal(r.text.includes("\r\n"), false, "这组输入是 LF，不该混进 CRLF");
+});
+
+test("[Unreleased] 攒着条目时整段搬进新版本节，不留空占位节", () => {
+  // 原先只插一个「🐛 修复 / （待填）」占位，攒着的条目原地不动：发版后文件里同时存在
+  // 「新版本节是空的」和「旧条目还挂在 Unreleased 名下」，搬运这一步照样要人工补
+  // （v0.9.0 的 77df0fb 干的就是这件事）。搬位置不搬内容——原样移动、一个字不改。
+  const src =
+    "# Changelog\n\n## [Unreleased]\n\n## 🐛 修复\n\n- 条目甲\n- 条目乙\n\n## 🔐 安全\n\n- 条目丙\n\n## [0.9.0] - 2026-10-17\n\n- 旧版本\n";
+  const r = insertReleaseSection(src, "0.9.1", "2026-10-18");
+  assert.equal(r.ok, true);
+  assert.equal(r.moved, 3, "三条条目都要搬过去");
+  assert.equal(r.movedContent, true, "搬了正文与条目，两个字段都该为真");
+  assert.equal(r.text.includes("（待填）"), false, "搬了真条目就不该再留空占位");
+  // Unreleased 立刻接新版本节，中间不夹任何内容
+  assert.ok(r.text.startsWith("# Changelog\n\n## [Unreleased]\n\n## [0.9.1] - 2026-10-18\n\n## 🐛 修复\n\n- 条目甲"));
+  assert.ok(r.text.includes("## 🔐 安全\n\n- 条目丙"), "多个小节整体搬，小节结构不动");
+  assert.ok(r.text.indexOf("- 条目丙") < r.text.indexOf("## [0.9.0]"), "全都搬进新节里，不留一条挂在 Unreleased 名下");
+});
+
+test("[Unreleased] 正文非空但没有 `- ` 条目时，movedContent 仍为 true（moved 只是计数）", () => {
+  // 用 moved 当「有没有搬」的判据是错的：正文非空、但一条 `- ` 都没有时 moved 是 0，
+  // 入口会打印「占位节（[Unreleased] 本来是空的）」——而它显然不空。两个字段必须分开用。
+  const src = "# Changelog\n\n## [Unreleased]\n\n一段没有条目的说明正文。\n\n## [0.9.0] - 2026-10-17\n\n- 旧版本\n";
+  const r = insertReleaseSection(src, "0.9.1", "2026-10-18");
+  assert.equal(r.ok, true);
+  assert.equal(r.moved, 0, "没有 `- ` 开头的行为，条目数是 0");
+  assert.equal(r.movedContent, true, "但正文确实搬了，这个字段才是「有没有搬」的判据");
+  assert.ok(r.text.includes("一段没有条目的说明正文。"), "正文不许丢");
+  assert.equal(r.text.includes("（待填）"), false, "不该在搬了正文之后还留空占位");
+});
+
+test("[Unreleased] 首行是缩进代码块时保留前导空格（原样搬，不 trim）", () => {
+  // body.trim() 会把首行的四空格吃掉，Markdown 代码块降级成普通段落——
+  // 那就不是「整段搬、一个字不改」了。只许剥掉节边界上的空行。
+  const src = "# Changelog\n\n## [Unreleased]\n\n    npm run sync\n\n## [0.9.0] - 2026-10-17\n\n- 旧版本\n";
+  const r = insertReleaseSection(src, "0.9.1", "2026-10-18");
+  assert.equal(r.ok, true);
+  assert.ok(r.text.includes("\n    npm run sync\n"), "四空格缩进必须原样保留：\n" + JSON.stringify(r.text));
+});
+
+test("[Unreleased] 为空时插占位节，且不产生多余空行", () => {
+  const src = "# Changelog\r\n\r\n## [Unreleased]\r\n## [0.9.0] - 2026-10-17\r\n\r\n- x\r\n";
+  const r = insertReleaseSection(src, "0.9.1", "2026-10-18");
+  assert.equal(r.ok, true, "CRLF 检出上也要能插");
+  assert.equal(r.moved, 0, "Unreleased 是空的，没有可搬的");
+  assert.equal(r.movedContent, false, "Unreleased 空时才该走占位节分支");
+  assert.ok(
+    r.text.startsWith(
+      "# Changelog\r\n\r\n## [Unreleased]\r\n\r\n## [0.9.1] - 2026-10-18\r\n\r\n## 🐛 修复\r\n\r\n- （待填）\r\n\r\n## [0.9.0] - 2026-10-17\r\n"
+    ),
+    "空的 Unreleased 后面接占位节，再接上一版"
+  );
+  assert.equal(/\n\n\n/.test(r.text.replace(/\r\n/g, "\n")), false, "不许出三连空行");
+  assert.equal(hasBareLf(r.text), false);
 });
 
 test("带 BOM 的输入也能插（`^#` 匹配不到属同一类形状漂移）", () => {
@@ -57,4 +123,4 @@ test("detectEol：认两种行尾，无换行时按 LF 处理", () => {
   assert.equal(detectEol("a\nb"), "\n");
   assert.equal(detectEol("a\r\nb"), "\r\n");
   assert.equal(detectEol("a"), "\n");
-});
+});

package/test/cli-enums.test.js

@@ -0,0 +1,37 @@
+// CLI 枚举是手写字面量（bin/cli.mjs 是零依赖 HTTP 客户端，不 import 服务端
+// 模块），没有类型系统兜着，所以用一张文本锁把它钉在 store.TYPES 上。
+// 防的回归：2026-10 审计发现 MEMORY_TYPES 只有 5 个类型、SEARCH_MODES 缺
+// hybrid，结果是 add --type pitfall 与 search --mode hybrid 被客户端自己拒掉
+// ——服务端明明支持，客户端先说不。
+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";
+import { TYPES } from "../src/store.js";
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const cli = readFileSync(path.join(root, "bin", "cli.mjs"), "utf8");
+
+function literalArray(name) {
+  const m = cli.match(new RegExp("const " + name + " = \\[([^\\]]*)\\]"));
+  assert.ok(m, name + " 应从 bin/cli.mjs 里解析出来（改名就同步改这把锁）");
+  return [...m[1].matchAll(/'([^']+)'/g)].map((x) => x[1]);
+}
+
+test("cli MEMORY_TYPES 与 store.TYPES 的差值恰好是 document", () => {
+  const cliTypes = literalArray("MEMORY_TYPES");
+  // document 只能经 memory_register_document 铸造；放进 --type 会让用户得到一条
+  // 服务端 400。锁「差值恰好是 document」而不是「完全相等」，就是为了让这条
+  // 例外显式化：未来再加一个只能经专用接口铸造的类型，这里会红。
+  const expected = [...TYPES].filter((t) => t !== "document").sort();
+  assert.deepEqual(cliTypes.slice().sort(), expected);
+});
+
+test("cli SEARCH_MODES 覆盖 API 支持的全部召回模式", () => {
+  const modes = literalArray("SEARCH_MODES");
+  // 四种模式来自 src/api.js 的 /search mode 注释（auto/hybrid/vector/keyword）。
+  for (const mode of ["keyword", "vector", "auto", "hybrid"]) {
+    assert.ok(modes.includes(mode), "SEARCH_MODES 缺少 " + mode);
+  }
+});