@modusensus/dsh-mneme 0.8.16 → 0.9.1

package/test/release-notes.test.js

@@ -0,0 +1,240 @@
+// scripts/release-notes.mjs 的回归测试。
+//
+// 这段逻辑原先嵌在 .github/workflows/release.yml 的 node -e 里：改排版要动工作流本体、还写不了
+// 测试，而它产出的恰恰是 GitHub Release 的对外正文——最需要反复试排版的地方。抽成模块之后，
+// 形状必须被锁住，否则下次「顺手压缩一下」就会静默改变所有 Release 页的样子。
+//
+// 锁的是四条容易悄悄退化的性质：
+//   1. 分层而不是截断：标题 + 一句导语默认可见，其余折进 details，完整正文一条不丢；
+//   2. 导语与折叠块不重复：consumed 记错就会让同一句话出现两次；
+//   3. 导语不在未闭合的括号里断开，也不采用短到无法独立表意的首句；
+//   4. 找不到小节必须非零退出、不写正文——退回空正文就是假成功；
+//   5. 缩进续行跟着它所属的条目一起进折叠块，不散落到外面（老版本 CHANGELOG 里有 179 行）；
+//   6. 正文本身不长时整段就是导语，不许凭空加省略号（短正文里也常有逗号）。
+// 第 4 条走真进程（spawnSync）端到端：工作流只认退出码与 notes/body.md 这个文件。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { findSection, parseBullet, lede, renderNotes } from "../scripts/release-notes.mjs";
+
+const scriptPath = join(dirname(fileURLToPath(import.meta.url)), "..", "scripts", "release-notes.mjs");
+
+/** 括号深度：全角与半角都算。导语收尾时它必须是 0。 */
+function parenDepth(s) {
+  let d = 0;
+  for (const c of s) {
+    if (c === "\uFF08" || c === "(") d += 1;
+    else if (c === "\uFF09" || c === ")") d = Math.max(0, d - 1);
+  }
+  return d;
+}
+
+const SAMPLE = [
+  "# Changelog",
+  "",
+  "## [0.9.0] - 2026-10-17",
+  "",
+  "## \u{1F41B} 修复",
+  "",
+  "- **修掉一个能钉死宿主的轮询**：轮询器原先在没有新消息时也会整轮重建定时器，于是每收到一次心跳就多压一层等待队列，这在单次会话里看不出来，连续跑上几小时才会把宿主的事件循环拖到卡死，排查时表现为面板偶尔整片不刷新、日志里却什么异常都没有（这类问题最费时间，因为复现窗口很长，还得先怀疑是记忆库锁竞争），修法是把定时器提到循环外复用，并补一条回归用例锁住轮询次数。",
+  "",
+  "- **很短的一条**：两处水源在说谎。",
+  "",
+  "## [0.8.16] - 2026-10-12",
+  "",
+  "- 旧条目",
+].join("\n");
+
+test("findSection：取到该版小节，不含标题行，到下一个版本标题为止", () => {
+  const sec = findSection(SAMPLE, "0.9.0");
+  assert.ok(sec.startsWith("## \u{1F41B} 修复"), "小节从版本标题行之后开始");
+  assert.ok(sec.includes("修掉一个能钉死宿主的轮询"), "正文在里面");
+  assert.equal(sec.includes("[0.9.0]"), false, "不该带上版本标题行本身");
+  assert.equal(sec.includes("旧条目"), false, "到下一个 ## [ 为止");
+});
+
+test("findSection：找不到该版本返回 null（入口据此 exit 1）", () => {
+  assert.equal(findSection(SAMPLE, "9.9.9"), null);
+});
+
+test("findSection：版本号里的点被转义过，不会当成通配", () => {
+  const text = SAMPLE.replace("## [0.8.16] - 2026-10-12", "## [0x8x16] - 2026-10-12");
+  assert.equal(findSection(text, "0.8.16"), null, "点若被当通配就会误命中 0x8x16");
+});
+
+test("parseBullet：拆出标题与正文；非该形状返回 null 由调用方原样保留", () => {
+  assert.deepEqual(parseBullet("- **标题**：正文在这里"), { title: "标题", body: "正文在这里" });
+  assert.deepEqual(parseBullet("- **只有标题**"), { title: "只有标题", body: "" });
+  assert.equal(parseBullet("普通段落"), null);
+  assert.equal(parseBullet("- 没有粗体标题：正文"), null);
+});
+
+test("lede：cap 内第一个达标的句末标点处收尾，consumed 与导语等长", () => {
+  // 正文必须真的长于 cap：短于 cap 时整段就是导语（见下一条用例），那样根本走不到本分支。
+  const first = "这是一个足够长的句子，用来验证导语会在句末标点处停下来。";
+  const body = first + "后面还有别的内容，".repeat(20);
+  assert.ok(body.length > 150, "构造本身要求正文长于 cap");
+  const r = lede(body, 150);
+  assert.equal(r.lede, first);
+  assert.equal(r.consumed, r.lede.length, "consumed 必须等于导语长度，否则折叠块会错位或重复");
+});
+
+test("lede：首句短于 MIN_LEDE 时不采用（实测有条首句只有 8 字，离开上下文没信息）", () => {
+  const body = "两处水源在说谎。这个短句单独拿出来没有信息量，所以要继续往下取。";
+  const r = lede(body, 150);
+  assert.notEqual(r.lede, "两处水源在说谎。", "8 字的首句不该被当成导语");
+  assert.ok(r.lede.startsWith("两处水源在说谎。"), "仍从正文开头起，不能跳过首句");
+  assert.ok(r.lede.length > 8);
+});
+
+test("lede：软断点必须在括号平衡处 —— 不在未闭合的括号里切断", () => {
+  // 复刻 v0.9.0 实测切出来的坏例子：GET /external-api（明文回吐 Bearer，…
+  const body = "开放读清单里有 GET /external-api（明文回吐 Bearer，还会就地铸造 token），这条实测切在括号里最难看，所以专门钉住它。";
+  const naive = body.slice(0, 40).lastIndexOf("\uFF0C");
+  assert.equal(parenDepth(body.slice(0, naive)), 1, "构造本身要能触发规则：cap 内最后一个逗号在括号里");
+  const r = lede(body, 40);
+  assert.equal(parenDepth(r.lede), 0, "导语的括号必须闭合：" + r.lede);
+  assert.ok(r.lede.includes("token）"), "应越过括号再收尾：" + r.lede);
+});
+
+test("lede：落到软断点分支时，consumed 连标点一起吃进去 —— 折叠块不能以逗号开头", () => {
+  // 这条补的是 M4 类退化：软断点用省略号收尾时，若 consumed 只记到标点之前，折叠块就会以
+  // 「，」开头（读者点开看到的第一件事是一个孤零零的逗号）。句末标点分支不会暴露它，因为
+  // 那条分支把整句连同标点一起切走；只有刻意不写句末标点的正文才走得到这里。
+  const body = Array.from({ length: 12 }, (_, i) => "\u7B2C" + (i + 1) + "\u6BB5\u5185\u5BB9\u5199\u5F97\u6BD4\u8F83\u957F\u4E00\u4E9B\uFF0C").join("") + "\u6536\u5C3E\u3002";
+  const r = lede(body, 150);
+  assert.ok(r.lede.endsWith("\u2026"), "\u6CA1\u6709\u53E5\u672B\u6807\u70B9\u65F6\u7528\u7701\u7565\u53F7\u6536\u5C3E\uFF1A" + r.lede);
+  assert.equal(r.consumed, r.lede.length, "consumed \u5FC5\u987B\u7B49\u4E8E\u5BFC\u8BED\u957F\u5EA6");
+  const rest = body.slice(r.consumed);
+  assert.ok(rest.length > 0, "\u6784\u9020\u672C\u8EAB\u8981\u6C42\u8FD8\u6709\u5269\u4F59\u6B63\u6587\uFF0C\u5426\u5219\u6D4B\u4E0D\u5230");
+  assert.equal(rest.startsWith("\uFF0C"), false, "\u6298\u53E0\u5757\u4E0D\u80FD\u4EE5\u9017\u53F7\u5F00\u5934\uFF1A" + rest.slice(0, 12));
+});
+
+test("lede：正文本身比 cap 短时，整段就是导语，不加省略号也不越界", () => {
+  const body = "很短的一条正文，没有句末标点";
+  const r = lede(body, 150);
+  assert.equal(r.lede, body, "整段即导语");
+  assert.equal(r.lede.includes("\u2026"), false, "不该凭空加省略号说后面还有");
+  assert.equal(r.consumed, body.length, "consumed 不能超过正文长度");
+});
+
+test("lede：正文比 cap 短且以逗号结尾时，仍是整段导语 —— 不加省略号说「后面还有」", () => {
+  // 这条钉的是「短正文保护」的位置：它必须排在软断点搜索之前。原先守在函数末尾，短正文里
+  // 只要有个逗号就会被加省略号；逗号恰是最后一个字符时更荒唐——省略号后面什么也没有，
+  // 折叠块是空的。实测语料里 25 字的短条就被切成了这个样子。
+  const body = Array.from({ length: 4 }, () => "\u4E00\u4E8C\u4E09\u56DB\u4E94\u516D\u4E03\u516B\u4E5D\u5341").join("") + "\uFF0C";
+  const r = lede(body, 150);
+  assert.equal(r.lede, body, "整段即导语，不该被软断点截断");
+  assert.equal(r.lede.includes("\u2026"), false, "不该加省略号");
+  assert.equal(r.consumed, body.length, "consumed 要覆盖整段");
+  assert.equal(body.slice(r.consumed), "", "没有剩余正文可折 —— 折叠块必须为空");
+});
+
+test("renderNotes：标题 + 导语默认可见，其余折进 details，且导语不重复出现", () => {
+  // 正文要长于 cap，否则整段展开（没有可折的东西时，多一步点击毫无收益）。
+  const section =
+    "- **标题甲**：第一句要足够长，所以会被当作导语留下来并在此收尾。" +
+    "第二句只应该出现在折叠块里，不该在可见行重复。".repeat(12);
+  const out = renderNotes(section, { cap: 150 });
+  const [head, ...rest] = out.split("\n");
+  assert.ok(head.startsWith("- **标题甲** \u2014 "), "可见行是标题 + 导语：" + head);
+  const folded = rest.join("\n");
+  assert.ok(folded.includes("<details><summary>细节</summary>"), "剩余正文折进 details");
+  assert.ok(folded.includes("第二句只应该出现在折叠块里"), "细节里要有后半段");
+  assert.equal(folded.includes("第一句要足够长，所以会被当作导语留下来并在此收尾"), false, "导语不在折叠块里重复出现");
+});
+
+test("renderNotes：details 缩进两级且与正文之间空行 —— 否则内部 Markdown 不解析、视觉归属也断", () => {
+  const section =
+    "- **标题乙**：第一句要足够长，所以会被当作导语留下来并在此收尾。" +
+    "后面这句进折叠块。".repeat(20);
+  const lines = renderNotes(section).split("\n");
+  const open = lines.findIndex((l) => l.includes("<details"));
+  const close = lines.findIndex((l) => l.includes("</details"));
+  assert.notEqual(open, -1, "长子弹必须被折叠");
+  assert.ok(lines[open].startsWith("  <details"), "details 标签缩进两格：" + lines[open]);
+  assert.ok(lines[close].startsWith("  </details"), "闭合标签缩进两格：" + lines[close]);
+  assert.equal(lines[open + 1], "", "details 与正文之间必须空行，否则内部 Markdown 不解析");
+  assert.equal(lines[close - 1], "", "正文与闭合标签之间也要空行");
+  assert.ok(lines[open + 2].startsWith("  "), "折叠正文缩进两格：" + lines[open + 2]);
+});
+
+test("renderNotes：缩进续行随条目一起进 details，不散落到外面也不丢缩进", () => {
+  // CHANGELOG 里有 179 行缩进续行（0.8.6 / 0.8.7 / 0.8.12 等老版本集中出现）与 59 行
+  // "  - " 子列表。逐行 trim 的写法会把续行当成独立段落甩到条目的 details 外面，
+  // 子列表还会塌成平铺段落——读者看到的是「正文只有一句，剩下的莫名其妙散在下面」。
+  // 渲染的单位是条目，不是行。
+  // 首行刻意写得短且没有句末标点：这样"句末标点落在续行上"才可达，用例才能抓到
+  // "把续行拼回正文再切导语"这种写法——那种写法会把换行混进可见行。
+  const section = [
+    "- **标题丙**：首行很短",
+    "  这一句续行足够长，句末标点落在续行上，好让拼接式的导语切分会把换行混进可见行。",
+    "  这是续行二，属于上一条子弹。",
+    "  - 子列表项不应塌成段落",
+    "- **标题丁**：另起一条，用来确认块边界。",
+  ].join("\n");
+  const lines = renderNotes(section).split("\n");
+  const firstClose = lines.findIndex((l) => l.includes("</details"));
+  const secondHead = lines.findIndex((l) => l.includes("**标题丁**"));
+  assert.notEqual(firstClose, -1, "带续行的条目必须被折叠");
+  assert.ok(secondHead > firstClose, "第二条子弹应排在第一条的 details 之后，块边界不能串");
+  const folded = lines.slice(0, firstClose).join("\n");
+  assert.ok(folded.includes("这一句续行足够长"), "续行一在第一条的折叠块里");
+  assert.ok(folded.includes("这是续行二"), "续行二在第一条的折叠块里");
+  assert.ok(folded.includes("- 子列表项不应塌成段落"), "子列表在折叠块里且保留列表形状");
+  const outside = lines.slice(secondHead).join("\n");
+  assert.equal(outside.includes("这一句续行足够长"), false, "续行不该跑到下一条子弹那边");
+  const visible = lines.find((l) => l.includes("**标题丙**"));
+  assert.ok(visible.startsWith("- **标题丙** \u2014 "), "可见行仍是单行标题 + 导语：" + visible);
+  assert.equal(visible.includes("续行"), false, "续行不许挤进可见行，否则可见行撑成多行：" + visible);
+  // 这一条抓的是「把续行拼回正文再切导语」的写法：导语里混进换行后，可见行后面会多出一行
+  // 没有任何缩进的裸行，续行又散到了 details 外面。判别方法是看可见行之后紧跟什么——
+  // 正常只可能是 details 标签本身。
+  const headIdx = lines.indexOf(visible);
+  assert.ok(lines[headIdx + 1].startsWith("  <details"), "可见行之后必须直接是折叠块，不许有裸行：" + lines[headIdx + 1]);
+  assert.equal(visible.includes("\u2026"), false, "首行没有句末标点时，导语只能是首行本身，不该跨行取到续行的句号：" + visible);
+});
+
+test("renderNotes：分类小节原样保留，非子弹行不加工", () => {
+  const out = renderNotes("## \u{1F41B} 修复\n\n- 一条没有粗体标题的行\n");
+  assert.ok(out.includes("## \u{1F41B} 修复"), "小节标题原样保留");
+  assert.ok(out.includes("- 一条没有粗体标题的行"), "非 - **...** 形状原样保留");
+  assert.equal(out.includes("<details>"), false, "没拆出正文就不该有折叠块");
+});
+
+test("入口：真进程跑一遍，写出 notes/body.md，且 CHANGELOG 本体一个字不动", () => {
+  const root = mkdtempSync(join(tmpdir(), "mneme-release-notes-"));
+  mkdirSync(join(root, "dsh-mneme"), { recursive: true });
+  writeFileSync(join(root, "dsh-mneme", "CHANGELOG.md"), SAMPLE, "utf8");
+  const res = spawnSync(process.execPath, [scriptPath, "0.9.0"], { cwd: root, encoding: "utf8" });
+  assert.equal(res.status, 0, "退出码必须是 0：" + res.stderr);
+  const body = readFileSync(join(root, "notes", "body.md"), "utf8");
+  assert.ok(body.includes("## \u{1F41B} 修复"), "小节标题进了正文");
+  assert.ok(body.includes("<details>"), "长子弹被折叠");
+  assert.equal(readFileSync(join(root, "dsh-mneme", "CHANGELOG.md"), "utf8"), SAMPLE, "CHANGELOG 本体一个字不动");
+});
+
+test("入口：版本不存在时非零退出、不写正文（不许退回空正文假成功）", () => {
+  const root = mkdtempSync(join(tmpdir(), "mneme-release-notes-"));
+  mkdirSync(join(root, "dsh-mneme"), { recursive: true });
+  writeFileSync(join(root, "dsh-mneme", "CHANGELOG.md"), SAMPLE, "utf8");
+  const res = spawnSync(process.execPath, [scriptPath, "9.9.9"], { cwd: root, encoding: "utf8" });
+  assert.notEqual(res.status, 0, "找不到小节必须非零退出");
+  assert.match(
+    res.stderr,
+    /changelog section not found: 9\.9\.9/,
+    "要报出是哪一版找不到 —— 只靠非零退出码的话，脚本崩了也算通过（崩溃不是这条要防的东西，静默假成功才是）"
+  );
+  assert.equal(existsSync(join(root, "notes", "body.md")), false, "不该留下空正文");
+});
+
+test("入口：版本号格式不对时直接拒绝", () => {
+  const res = spawnSync(process.execPath, [scriptPath, "v1.2"], { encoding: "utf8" });
+  assert.notEqual(res.status, 0, "只接受 x.y.z");
+  assert.match(res.stderr, /usage: release-notes\.mjs/, "要说清用法，别静默退出");
+});

package/test/release-workflow.test.js

@@ -0,0 +1,93 @@
+// .github/workflows/release.yml 的作业依赖锁。
+//
+// 防的是一类「声明抢跑」：GitHub Release 是对外的「这个版本已发布」，registry 才是唯一事实。
+// 2026-10-12 修 Verify published version 假闸门（PR #419）时发现隔壁还有同一处豁口——release
+// job 只 needs [verify, test]，于是 publish 真失败（token 失效、registry 拒绝）时 Release 照样
+// 建出来：Release 页写着 v0.8.x，registry 上却没有，用户照 Release 装回的是上一个版本。
+//
+// 三条断言各锁一环，缺一环这类豁口就能重开：
+//   1. release 必须等 publish —— 否则「发不出去」和「发出去了」在 Release 页上同形；
+//   2. publish 必须含那道阻塞闸门（publish-gate.mjs）—— 否则 release 等的是一个不做校验的空壳，
+//      第 1 条形同虚设（改回 `npm view` 一次性查询同样会退回假绿）；
+//   3. release 仍要等 verify 与 test —— 免得为了修 1 顺手把版本/CHANGELOG 校验也绕过去。
+//
+// 工作流是 YAML，但为了三条断言引入 YAML 解析依赖不值得：这里只按缩进取作业块、读它自己的
+// needs 行。因此断言落在「内联列表形状」上（`needs: [a, b]`）——有人改成块状列表测试会红，
+// 那是真变化，值得人看一眼再改锁，而不是静默失效。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const workflowPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", ".github", "workflows", "release.yml");
+const workflow = readFileSync(workflowPath, "utf8");
+
+/** 取一个顶级 job（缩进 2 格的 `name:`）的整块文本，到下一个同级键或文件结尾。 */
+function jobBlock(name) {
+  const lines = workflow.split(/\r?\n/);
+  const start = lines.findIndex((line) => line === `  ${name}:`);
+  assert.notEqual(start, -1, `release.yml 里找不到 job ${name}`);
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^ {2}[A-Za-z0-9_-]+:\s*$/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end);
+}
+
+/** 读一个 job 块的 `needs:` 内联列表；没有 needs 行返回空数组。 */
+function needsOf(name) {
+  const line = jobBlock(name).find((l) => /^ {4}needs:\s*\[/.test(l));
+  if (!line) return [];
+  const inner = line.slice(line.indexOf("[") + 1, line.lastIndexOf("]"));
+  return inner.split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+test("release 等 publish：发布声明不许抢在真的发出去之前", () => {
+  const needs = needsOf("release");
+  assert.ok(
+    needs.includes("publish"),
+    `release 的 needs 必须含 publish（当前 [${needs.join(", ")}]）—— 否则 publish 失败时 Release 仍会建出来`
+  );
+});
+
+test("release 仍等 verify 与 test：修依赖顺序不该绕开版本与 CHANGELOG 校验", () => {
+  const needs = needsOf("release");
+  assert.ok(needs.includes("verify"), "release 必须等 verify（版本号与 CHANGELOG 小节）");
+  assert.ok(needs.includes("test"), "release 必须等 test");
+});
+
+test("publish 内必须跑阻塞闸门：release 等的是一个真做过校验的作业", () => {
+  // 只扫非注释行：publish job 的注释里刻意留了那行旧实现（说明它为什么是假绿），
+  // 那是文档不是代码——按整块扫会把文档当成复发。
+  const code = jobBlock("publish").filter((line) => !/^\s*#/.test(line)).join("\n");
+  assert.match(
+    code,
+    /node dsh-mneme\/scripts\/publish-gate\.mjs/,
+    "publish job 必须调用 publish-gate.mjs（拿不到版本就非零退出）"
+  );
+  assert.doesNotMatch(
+    code,
+    /echo "Published: \$\(npm view/,
+    "不要退回命令替换里的 npm view —— 失败不会让 set -e 退出，那是 v0.8.16 的假绿"
+  );
+});
+
+test("release 的正文抽取必须调模块，不许退回工作流内联脚本", () => {
+  // 原先这段是内联 node -e：改排版要动工作流本体、还没法写测试，而 Release 正文恰恰是最需要
+  // 反复试排版的东西。退回内联就等于退回「改了没人能验证」的状态，这条锁住它不再发生。
+  const code = jobBlock("release").filter((line) => !/^\s*#/.test(line)).join("\n");
+  assert.match(
+    code,
+    /node dsh-mneme\/scripts\/release-notes\.mjs/,
+    "release job 必须调用 release-notes.mjs（渲染有单测、本地可预览）"
+  );
+  assert.doesNotMatch(
+    code,
+    /node -e/,
+    "不要退回 node -e 内联脚本 —— 那段逻辑没有测试覆盖"
+  );
+});

package/test/route-policy.test.js

@@ -0,0 +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 汇报的路由数必须等于实际挂载数");
+});

package/test/scope-distill-stamp.test.js

@@ -0,0 +1,135 @@
+// 把 CodeRabbit 在 PR #434 上核出的三条钉死。
+// 前两条是「读起来对、跑起来错」的形态：注释写着 A，代码实际做 B。
+// 第三条是契约与实现的落差：文件头写着「任何异常都被吞掉」，但只吞了一半。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createScopeResolver } from "../src/scope.js";
+import { createSummarizer } from "../src/summarize.js";
+
+function summarizerHarness() {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const events = [];
+  const ctx = {
+    on(name, fn) { events.push({ name, fn }); return () => {}; },
+    llm: {
+      stream() {
+        const json = JSON.stringify([
+          { type: "decision", title: "选型", content: "确定用 node:sqlite", importance: 4 }
+        ]);
+        return (async function* () {
+          yield { type: "block-start", block: { type: "text" } };
+          yield { type: "text-delta", delta: json };
+          yield { type: "block-end", block: { type: "text" } };
+          yield { type: "finish", kind: "ok" };
+        })();
+      }
+    }
+  };
+  createSummarizer(ctx, service, {
+    autoSummarize: true,
+    scopeEnabled: true,
+    summarizeDedupeMode: "title",
+    summarizeDedupeWindowHours: 24,
+    summarizeMinIntervalMinutes: 0,
+    summarizeMaxRunsPerSession: 0,
+    distillRateLimitIntervalMs: 0
+  }, {});
+  return { store, service, handler: events.find((e) => e.name === "session/event").fn };
+}
+
+const SID = "s-scope-dedupe";
+
+function sessionOf(scope) {
+  return {
+    id: SID,
+    header: { agentPreset: scope, cwd: "C:\\work\\probe" },
+    requestHeader: () => ({ config: { provider: "deepseek", model: "deepseek-chat" } }),
+    events: [
+      { seq: 1, type: "user/message", data: { source: { kind: "user" }, content: [{ type: "text", text: "提问" }] } },
+      { seq: 2, type: "turn/end" }
+    ]
+  };
+}
+
+// 回归形状：scopeEnabled 与 summarizeDedupeMode 同开时，第二轮蒸馏会命中第一轮
+// 的行。findSessionDuplicate 的候选筛（type + source + 时间窗）不看 scope，真正
+// 决定并不并的是 saveWithDedupe 的 scopeMatches 门。调用方若用「命中就不传章」
+// 表达「不重贴」，新条目的 scope 会变成 null：与已带章的候选不等 → 门拒 → 回落
+// 新建，而那一行也是新行，同样该带章却没有章。结果是同题两行、一行 auto 一行
+// NULL——跨作用域隔离没做成，同题重复倒留下了。
+test("scope + dedupe: a scope-gate rejection still stamps the replacement row", async () => {
+  const { store, service, handler } = summarizerHarness();
+  // 同 source 的存量未标注行：正是 scopeEnabled 之前写下的那些行的形状。
+  service.saveWithDedupe({
+    type: "decision", title: "选型", content: "旧内容", source: `session:${SID}`, importance: 4
+  });
+
+  await handler(sessionOf("amarre"), { seq: 2, type: "turn/end" });
+
+  const rows = store.list({ limit: null });
+  assert.equal(rows.length, 2, "跨作用域不并入，存量行原样留着");
+  const stamped = rows.filter((r) => r.agent_scope === "amarre");
+  assert.equal(stamped.length, 1, "回落新建的那一行必须带章（它同样是新行）");
+  assert.equal(stamped[0].workspace_scope, "C:\\work\\probe", "两维都盖");
+});
+
+// 反向锁：同作用域同题照旧并入，且不新造行、不把既有行的来源升级成 explicit
+// （升级只在用户显式声明时发生，见 service.js 的 scopeUpgrade 分支）。
+test("scope + dedupe: a same-scope candidate still merges and keeps its source", async () => {
+  const { store, service, handler } = summarizerHarness();
+  service.saveWithDedupe({
+    type: "decision", title: "选型", content: "旧内容", source: `session:${SID}`,
+    importance: 4,
+    agent_scope: "amarre", agent_scope_source: "auto",
+    workspace_scope: "C:\\work\\probe", workspace_scope_source: "auto"
+  });
+
+  await handler(sessionOf("amarre"), { seq: 2, type: "turn/end" });
+
+  const rows = store.list({ limit: null });
+  assert.equal(rows.length, 1, "同作用域同题：并入而不是新造");
+  assert.equal(rows[0].agent_scope_source, "auto", "并入不把来源升级成 explicit");
+});
+
+// scope.js 文件头写着硬约束「任何异常都被吞掉」，但那条约束此前只覆盖了
+// session.header 的取得与 registry 查询——header 的**字段**读取裸着。宿主给出
+// 会抛错的 accessor 时（sessionOf / sessionKeyOf 就是为同一类宿主写的 try 包），
+// 异常会穿出解析器：蒸馏路径上一个窗口的记忆与游标一起丢，工具路径上是一次
+// memory_save 直接失败。锁的是「字段级读取也必须各自护住」。
+test("scope resolver: a throwing header accessor never escapes the resolver", () => {
+  const resolve = createScopeResolver({ ctx: {}, config: { scopeEnabled: true }, logger: {} });
+  const session = {
+    id: "s-throw",
+    get header() {
+      return {
+        get agentPreset() { throw new Error("host accessor exploded"); },
+        get cwd() { throw new Error("host accessor exploded"); }
+      };
+    }
+  };
+
+  let value = null;
+  assert.doesNotThrow(() => { value = resolve({ agent: { session } }); });
+  assert.deepEqual(value, { agent_scope: null, workspace_scope: null }, "取不到就落 NULL，不是抛出");
+});
+
+// 居中 sheet 是「宿主没有右栏服务」时的唯一完整视图入口（PipelineHeaderEntry 的
+// fallback）。它 portal 到 body，焦点默认留在 trigger 上，而挂在 sheet 元素上的
+// onKeyDown 既因没有 tabIndex 不被聚焦、也收不到外部键盘事件 —— Escape 于是不
+// 生效，键盘用户只剩 Tab 摸到关闭按钮一条路。这里锁住「焦点进得去、Esc 出得来」
+// 两件事都在；做法与 MemoryOverlay 一致（打开时 focus，Esc 挂在 window 上）。
+test("pipeline sheet fallback is keyboard reachable: focus moves in, Escape gets out", () => {
+  const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+  const src = readFileSync(join(root, "lib/client.js"), "utf8");
+
+  assert.match(src, /ref: sheetRef,\s*\n\s*tabIndex: -1,/, "sheet 必须可聚焦（否则 onKeyDown 收不到事件）");
+  assert.match(src, /if \(!sheetOpen\) return undefined;\s*\n\s*if \(sheetRef\.current\) sheetRef\.current\.focus\(\);/,
+    "打开时必须把焦点移进 sheet");
+  assert.match(src, /window\.addEventListener\("keydown", onKey\)/, "Escape 必须挂在 window 上收");
+});