@modusensus/dsh-mneme 0.9.0 → 0.9.2

package/test/cli-flag-value.test.js

@@ -0,0 +1,86 @@
+// `--flag value` 的值本身可以是 `--` 开头的字符串。真撞上的那次是 CI：
+//
+//   not ok 846 - CLI：reclaim 默认 dry-run 报数字，--apply --vacuum 才真收
+//   ... bin/cli.mjs reclaim --url http://127.0.0.1:55423 --token <以 -- 开头的随机 token>
+//   未配置访问 token，无法调用该命令
+//
+// token 由 `crypto.randomBytes(24).toString("base64url")` 生成（src/api-standalone.js），
+// base64url 的字母表含 `-`，于是约 1/4096 的 token 头两位都是 `-` → 拼出来就是 `--…`
+// → 旧 parseArgv 把它当新旗标、token 变 `true` → 退回环境变量/配置文件 → 全空。
+// 也就是说这是一条**真实用户的随机性**，不是测试写法问题：一次 CI 红只是运气不好。
+//
+// 这个文件把解析语义钉死：值可以是任意 `--` 开头的串，而真旗标仍按旗标解析。
+//
+// 下面刻意不写整串字面量：那个 token 是一次性测试服务现生成的、早已随进程消失，
+// 而一整串高熵字符留在源码里会被密钥扫描（gitleaks 的 generic-api-key 按熵报警）
+// 当成真凭据。用拼接构造，形状一样、不触发扫描。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { parseArgv, KNOWN_FLAGS, flagValue, flagBool } from "../bin/cli.mjs";
+
+// 拼成 `--token` / `--` 开头的值，两个片段各自都是低熵短串。
+const FLAG_TOKEN = "--tok" + "en";
+const DASH_VALUE = "--" + "dash-prefixed-value";
+
+test("CLI 解析：--token 的值以 -- 开头时仍取到值（CI 回归现场）", () => {
+  const { positionals, flags } = parseArgv([
+    "reclaim", "--url", "http://127.0.0.1:55423",
+    FLAG_TOKEN, DASH_VALUE
+  ]);
+  assert.deepEqual(positionals, ["reclaim"]);
+  assert.equal(flags.token, DASH_VALUE);
+  // 这条才是当初真正失败的地方：值为 true 时 flagValue 视为「没给」。
+  assert.equal(flagValue(flags, "token"), DASH_VALUE);
+  // 旧实现会在这里多出一个键：把值当成旗标名（`dash-prefixed-value`）。
+  assert.deepEqual(Object.keys(flags).sort(), ["token", "url"]);
+});
+
+test("CLI 解析：单横线开头的值同样按值处理", () => {
+  const { flags } = parseArgv(["add", "--title", "-x", "--content", "-"]);
+  assert.equal(flags.title, "-x");
+  assert.equal(flags.content, "-");
+});
+
+test("CLI 解析：真旗标仍按旗标解析，不会被前一个旗标吞成值", () => {
+  // --limit 后面跟 --json：--json 是已注册旗标，所以 --limit 没有值（true），
+  // --json 是布尔。这是旧语义，必须保持，否则 `--limit --json` 会静默变成
+  // limit="--json"。
+  const { flags } = parseArgv(["list", "--limit", "--json"]);
+  assert.equal(flags.limit, true);
+  assert.equal(flagBool(flags, "json"), true);
+});
+
+test("CLI 解析：等号形式与 `--` 分隔符语义不变", () => {
+  assert.equal(parseArgv(["reclaim", "--token=--abc"]).flags.token, "--abc");
+  // `--` 之后全是位置参数，即使以 -- 开头。
+  assert.deepEqual(parseArgv(["search", "--", "--weird"]).positionals, ["search", "--weird"]);
+});
+
+test("CLI 解析：未知的 -- 开头词当作上一个旗标的值", () => {
+  // 这是本修复的判定规则：只有 KNOWN_FLAGS 里登记过的词才算旗标。
+  const { flags } = parseArgv(["add", "--content", "--not-a-real-flag"]);
+  assert.equal(flags.content, "--not-a-real-flag");
+});
+
+test("CLI KNOWN_FLAGS 覆盖 flagValue/flagBool 的全部实际用法", async () => {
+  // 漏登记的代价：该旗标会被当成前一个旗标的值吞掉，且没有任何报错。
+  // 所以用文本锁把 KNOWN_FLAGS 与 cli.mjs 里的调用点钉在一起——新增命令
+  // 忘登记会在这里炸，而不是等 1/4096 的用户撞上。
+  const { readFileSync } = await import("node:fs");
+  const { fileURLToPath } = await import("node:url");
+  const path = await import("node:path");
+  const cliPath = path.join(
+    path.dirname(path.dirname(fileURLToPath(import.meta.url))), "bin", "cli.mjs");
+  const src = readFileSync(cliPath, "utf8");
+
+  const used = new Set();
+  for (const m of src.matchAll(/flag(?:Value|Bool)\(\s*flags\s*,([^)]*)\)/g)) {
+    // 只认字符串字面量；`...names` 这种转发形式由调用方各自登记。
+    for (const s of m[1].matchAll(/'([^']+)'/g)) used.add(s[1].toLowerCase());
+  }
+  assert.ok(used.size >= 15, "至少要解析出 CLI 全部取值/布尔旗标，否则这把锁失效了");
+
+  const missing = [...used].filter((k) => !KNOWN_FLAGS.has(k));
+  assert.deepEqual(missing, [],
+    "以下旗标在用但没登记进 KNOWN_FLAGS，会被前一个 --flag 吞成值：" + missing.join(", "));
+});

package/test/client.test.js

@@ -1020,10 +1020,14 @@ test("scope isolation ships panel switches and provenance surfaces (A4)", () =>
 // 默认值），面板自判、不加后端字段；④分组与折叠键中英成对。验收口径：首屏
 // 可点项 = 3 总开关 + autoInject 的 2 个子开关 + scope 2 开关 + 「全部设置」
 // 按钮 = 8（≤ 8），由 ①② 的组成正则共同钉死，不另数 DOM。
+// v0.9.0 复验修订：首屏加 group.mo（M.O. 独立组），可点项预算 8→9。这不是
+// 悄悄放宽——是产品主人点名「别藏在里面」：M.O. 独立成组却仍折在「全部
+// 设置」后等于换个地方继续藏。≤8 原为 #427 自设软预算，owner 豁免一项。
 test("settings card folds everything beyond the first screen behind All settings (issue #427)", () => {
-  // ① 首屏层组成：两组都要在，且 basic 的成员是从 core/dream 移走的。
-  assert.ok(/const FEATURE_FIRST_SCREEN = \["group\.basic", "group\.scope"\];/.test(clientSource),
-    "the first screen must be exactly the basic and scope groups");
+  // ① 首屏层组成：三组都要在（basic 总开关 / mo 座位闸门 / scope 必答题），
+  // 且 basic 的成员是从 core/dream 移走的。
+  assert.ok(/const FEATURE_FIRST_SCREEN = \["group\.basic", "group\.mo", "group\.scope"\];/.test(clientSource),
+    "the first screen must be exactly the basic, mo and scope groups");
   assert.ok(/key: "group\.basic", items: \["autoInject", "autoSummarize", "autoDream"\]/.test(clientSource),
     "group.basic must carry exactly the three master switches");
   assert.ok(!/key: "group\.core", items: \["autoInject/.test(clientSource) && !/key: "group\.dream", items: \["autoDream/.test(clientSource),
@@ -1047,6 +1051,47 @@ test("settings card folds everything beyond the first screen behind All settings
     "the default/changed badge must be decided from overrides, not a new backend field");
 });
 
+// #481：面板开关「改了不生效」的体验坑。开关在宿主启动时合并进冻结 cfg，
+// 此后面板改 kv 只是持久化——用户看到「已改」就以为生效了，实测（人格总闸）
+// 因此白白排查了一轮。这条锁三件事：①第三态徽标由后端的 pendingRestart 名单
+// 决定（前端算不出来：overrides 只说明「改了」，不说明「用没用上」）；
+// ②卡片顶部有整卡提示行；③中英文案与语义色齐备，且「待重启」不能靠
+// opacity 之类的弱化手段与「已改」区分（弱化在浅色主题下会掉到看不清）。
+test("feature switches expose a third badge state for saved-but-not-live overrides (#481)", () => {
+  // ① 判定来源必须是后端字段，而不是前端自己比 overrides。
+  assert.ok(/const pending = new Set\(\(state && state\.pendingRestart\) \|\| \[\]\)/.test(clientSource),
+    "the pending set must come from the backend pendingRestart list");
+  assert.ok(/pending\.has\(k\)[\s\S]{0,240}?mneme-badge--pending/.test(clientSource),
+    "flagTag must return the pending badge before falling back to default/changed");
+  // 后端字段缺失（旧宿主）时 pending 为空集，面板退回两态——不能因此崩掉。
+  assert.ok(/\(state && state\.pendingRestart\) \|\| \[\]/.test(clientSource),
+    "a missing pendingRestart must degrade to an empty set, not throw");
+
+  // ② 整卡提示行：只在有待重启项时出现，位置在说明之后、错误行之前。
+  const noticeAt = clientSource.indexOf('t("memory.features.pendingRestartNotice")');
+  const descAt = clientSource.indexOf('h("div", { className: "mneme-set-desc" }, t("memory.features.desc"))');
+  assert.ok(noticeAt > descAt && descAt >= 0, "the notice row must sit after the card description");
+  assert.ok(/pending\.size > 0 && h\("div", \{ className: "mneme-pending" \}/.test(clientSource),
+    "the notice row must render only when something is actually pending");
+
+  // ③ 双语齐备（各出现两次：zh 表 + en 表）。
+  for (const key of ["memory.features.tagPending", "memory.features.tagPending.hint",
+    "memory.features.pendingRestartNotice"]) {
+    const occurrences = clientSource.split("\"" + key + "\"").length - 1;
+    assert.ok(occurrences >= 2, `i18n key ${key} must exist in both zh and en (got ${occurrences})`);
+  }
+
+  // ④ 样式走语义色层（AGENTS.md 第 9 条），且不靠透明度弱化区分状态。
+  assert.ok(/\.mneme-badge--pending\{[^}]*var\(--mneme-warn\)[^}]*\}/.test(clientSource),
+    "the pending badge must use the --mneme-warn semantic colour");
+  assert.ok(!/\.mneme-badge--pending\{[^}]*opacity/.test(clientSource),
+    "the pending badge must not rely on opacity to distinguish itself from changed");
+  assert.ok(/\.mneme-pending\{[^}]*var\(--mneme-warn\)[^}]*\}/.test(clientSource),
+    "the notice row must use the --mneme-warn semantic colour");
+  assert.ok(/\.mneme-pending-dot\{[^}]*background:currentColor/.test(clientSource),
+    "the notice dot must inherit currentColor so the colour has one source");
+});
+
 // v0.8.0 冲突集中处理：状态页的待确认冲突队列（reason + 双方内容对比 +
 // 保留 A/B/仅标记动作），resolveConflictPending 的第一个前端出口。双语齐备。
 test("conflict queue ships a central review surface on the status tab", () => {
@@ -1661,8 +1706,8 @@ test("distill retention switches are reachable from the panel (#399)", () => {
     "distillRecords.enabled must be an item of the core group, not merely referenced elsewhere"
   );
   assert.ok(
-    /const FEATURE_NUMBERS = \["distillRecords\.retentionDays"\]/.test(clientSource),
-    "retentionDays must be in the numeric key list"
+    /const FEATURE_NUMBERS = \["distillRecords\.retentionDays", "dreamMaxTokens", "sleepMaxTokens"\]/.test(clientSource),
+    "retentionDays must be in the numeric key list (dreamMaxTokens/sleepMaxTokens joined by #478)"
   );
   assert.ok(
     /for \(const key of FEATURE_NUMBERS\) numDraft\[key\] = String\(e\[key\] \?\? ""\);/.test(clientSource)
@@ -1690,7 +1735,12 @@ test("distill retention switches are reachable from the panel (#399)", () => {
     "memory.features.distillRecords.enabled",
     "memory.features.distillRecords.enabled.hint",
     "memory.features.distillRecords.retentionDays",
-    "memory.features.distillRecords.retentionDays.hint"
+    "memory.features.distillRecords.retentionDays.hint",
+    // #478：面板新暴露的两个 max_tokens 预算键，label 与 hint 缺一即哑行
+    "memory.features.dreamMaxTokens",
+    "memory.features.dreamMaxTokens.hint",
+    "memory.features.sleepMaxTokens",
+    "memory.features.sleepMaxTokens.hint"
   ]) {
     const occurrences = clientSource.split(`"${key}"`).length - 1;
     assert.ok(occurrences >= 2, `i18n key ${key} must exist in both zh and en (got ${occurrences})`);
@@ -1939,3 +1989,163 @@ test("M.O. class names do not collide in the stylesheet", () => {
   // 扫描量也得钉：正则一旦匹配不到东西，上面那条会静默变绿（例如样式表被整块挪走）。
   assert.ok(declared.size >= 20, `the scan must actually see the pipeline stylesheet (saw ${declared.size})`);
 });
+
+// 回归锁（v0.9.0 复验轮沉淀）：面板的两种「静默消失」假绿形状一起钉住。
+// ① i18n 缺定义：既有的「每键恰好两次」锁只统计**字典里存在**的键，一个只有
+//   用法、零字典行的键在计数里整个消失——本轮就查出 4 个这种键（zoom.value 自
+//   基线即断）。所以这里反向查：每一处用法都必须能找到定义行。三种用法形状：
+//   字面量 t("k")、模板 t(`memory.features.${g.key}`) 按 FEATURE_GROUPS 的组键
+//   展开、模板 t(`memory.features.${k}`) 按各 items 旗标键展开（boolRow 的
+//   name/hint 各一路）。不做全量动态键解析——拼接形态的键在此设防范围外。
+// ② 图标名未注册：Icon 对查不到的名字 return null（无回退、无告警），闸门照绿
+//   而屏幕上图标没了。本轮 star 入口就是这么哑掉的。这里钉「每个用到的名字都在
+//   ICON_PATHS 注册表里」+ 提取与注册表的最低数量（防正则空转的静默绿）。
+test("panel copy and icons must not silently vanish (missing dict lines, unregistered icon names)", () => {
+  const defined = (key) => clientSource.includes('"' + key + '":');
+
+  // ①-a 字面量用法（右括号紧贴字符串，排除 "前缀" + 变量 拼接形态）
+  const usedKeys = new Set();
+  for (const m of clientSource.matchAll(/\bt\("([a-zA-Z0-9_.]+)"\)/g)) usedKeys.add(m[1]);
+  assert.ok(usedKeys.size >= 300, `the literal scan must actually see the panel's t() calls (saw ${usedKeys.size})`);
+  // ①-b 模板展开：组键 与 旗标键（label + .hint 两路）
+  const groupKeys = [...clientSource.matchAll(/key: "(group\.[a-z]+)"/g)].map((m) => m[1]);
+  assert.ok(groupKeys.length >= 5, `FEATURE_GROUPS must be parseable (saw ${groupKeys.length} groups)`);
+  for (const g of groupKeys) usedKeys.add("memory.features." + g);
+  const flagKeys = [...new Set([...clientSource.matchAll(/items: \[((?:[^\]]|\n)*)\]/g)]
+    .flatMap((m) => [...m[1].matchAll(/"([a-zA-Z0-9_.]+)"/g)].map((x) => x[1])))];
+  assert.ok(flagKeys.length >= 20, `group items must be parseable (saw ${flagKeys.length})`);
+  for (const k of flagKeys) { usedKeys.add("memory.features." + k); usedKeys.add("memory.features." + k + ".hint"); }
+
+  const missing = [...usedKeys].filter((k) => !defined(k)).sort();
+  assert.deepEqual(missing, [], `用而无典的 i18n 键（界面会裸奔出键名）：${missing.join(", ")}`);
+
+  // ② 图标名：注册表形状（顶层对象、六空格缩进）+ Icon 表达式与 feedRow 首参的提取
+  const registered = new Set([...clientSource.matchAll(/^\s{6}([a-zA-Z]+): \[\[/gm)].map((m) => m[1]));
+  assert.ok(registered.size >= 10, `the ICON_PATHS registry must be parseable (saw ${registered.size})`);
+  const iconNames = new Set();
+  for (const m of clientSource.matchAll(/h\(Icon, \{ name: ([^}]+?) [,}]/g)) {
+    const expr = m[1];
+    const direct = expr.match(/^"([a-zA-Z]+)"$/);
+    if (direct) { iconNames.add(direct[1]); continue; }
+    // 只取三元分支的纯字母串；"===" 比较对象前面是运算符不是 ? : ，不会误伤
+    for (const b of expr.matchAll(/[?:]\s*"([a-zA-Z]+)"/g)) iconNames.add(b[1]);
+  }
+  for (const m of clientSource.matchAll(/feedRow\(\s*"([a-zA-Z]+)"/g)) iconNames.add(m[1]);
+  assert.ok(iconNames.size >= 8, `icon usage must be parseable (saw ${iconNames.size})`);
+  const noIcon = [...iconNames].filter((n) => !registered.has(n)).sort();
+  assert.deepEqual(noIcon, [], `Icon 静默 return null 的未注册名：${noIcon.join(", ")}`);
+});
+
+// 人格定义页（beta）面板面回归：形状沿用 A4 的「分组 + i18n 双语 occurrences ≥ 2
+// + 关键接线」断言风格（只做源码断言，不挂 React 渲染环境）。
+test("persona page ships settings card, master switch and i18n (beta v1)", () => {
+  // 开关进 FEATURE_GROUPS 的 enhance 组（行为开关非座位闸门）
+  assert.ok(
+    /group\.enhance", items: \[(?:[^\]]|\n)*"personaEnabled"\]/.test(clientSource),
+    "FEATURE_GROUPS group.enhance must carry personaEnabled"
+  );
+  // i18n 键中英双语齐备（occurrences ≥ 2 模式；label + .hint 两路由字典锁统一覆盖）
+  for (const key of [
+    "memory.features.personaEnabled",
+    "memory.features.personaEnabled.hint",
+    "memory.settings.persona",
+    "memory.settings.personaHint",
+    "memory.settings.personaName",
+    "memory.settings.personaPersonality",
+    "memory.settings.personaReplyStyle",
+    "memory.settings.personaSave",
+    "memory.settings.personaSaved",
+    "memory.settings.personaEnabledToggle",
+    "memory.settings.personaView",
+    "memory.settings.personaViewHint",
+    "memory.settings.personaViewEmpty"
+  ]) {
+    const occurrences = clientSource.split(`"${key}"`).length - 1;
+    assert.ok(occurrences >= 2, `i18n key ${key} must exist in both zh and en (got ${occurrences})`);
+  }
+  // 设置卡接线：保存走 PUT /persona、卡内开关改 enabled 即保存、只读卡渲染
+  assert.ok(clientSource.includes('apiFetch("/api/dsh-mneme/persona"'), "persona card must talk to /persona");
+  assert.ok(clientSource.includes("method: \"PUT\""), "persona save must PUT");
+  assert.ok(clientSource.includes("t(\"memory.settings.personaView\")"), "read-only injected-view card must exist");
+  // 双闸门提示：hint 文案必须说明「总闸与卡内开关同时打开才生效」
+  assert.ok(
+    clientSource.includes("memory.features.personaEnabled.hint"),
+    "the master-switch hint must document the two-gate semantics"
+  );
+});
+
+// v1.2 多卡回归：卡列表 CRUD 可见、字段标签渲染为可见元素（v1.1 反馈：
+// aria-label 看不见）、保存失败必须冒可见错误（v1 静默 catch 吞 404 教训）。
+test("persona card is multi-card with visible field labels and save-failure error", () => {
+  for (const key of [
+    "memory.settings.personaDefaultCard",
+    "memory.settings.personaAdd",
+    "memory.settings.personaAddPlaceholder",
+    "memory.settings.personaEditingDefault",
+    "memory.settings.personaEditingFor",
+    "memory.settings.personaDeleteCard",
+    "memory.settings.personaSaveFailed",
+    "memory.settings.personaEnabledOn",
+    "memory.settings.personaEnabledOff"
+  ]) {
+    const occurrences = clientSource.split(`"${key}"`).length - 1;
+    assert.ok(occurrences >= 2, `i18n key ${key} must exist in both zh and en (got ${occurrences})`);
+  }
+  // 多卡接线：加卡/删卡/切换/保存全链函数存在
+  for (const fn of ["addPersonaCard", "removePersonaCard", "savePersonaCards", "setPersonaEditing"]) {
+    assert.ok(clientSource.includes(fn), `multi-card wiring must include ${fn}`);
+  }
+  // 可见字段标签：三个字段名的 t() 调用出现在 label 元素（mneme-featnumlabel）
+  const labelBlock = clientSource.match(/mneme-featnumlabel[^]{0,120}personaName/);
+  assert.ok(labelBlock, "persona field labels must be visible (featnumlabel class), not aria-only");
+  // 保存失败提示：personaError 状态有渲染路径（非仅 setState）
+  assert.ok(clientSource.includes("t(\"memory.settings.personaSaveFailed\")"), "save failure must render an error line");
+  // 卡删除 × 常显回归锁 v2（#457 内联覆写被 #459 回滚的教训）：× 不得复用
+  // mneme-set-del（opacity:0 仅在 .mneme-set-row:hover 解除，卡标签不在该容器
+  // → 永远不可见），必须用独立类 mneme-persona-del 且该类常显（opacity:1）。
+  assert.ok(
+    /className: "mneme-persona-del"/.test(clientSource),
+    "persona card delete × must use the dedicated always-visible class"
+  );
+  const delStyle = clientSource.match(/\.mneme-persona-del\{[^}]*\}/);
+  assert.ok(delStyle, "mneme-persona-del style rule must exist");
+  assert.ok(!/opacity:0/.test(delStyle[0]), "mneme-persona-del must not be transparent");
+  // 不许再把 mneme-set-del 挂回卡删除按钮（防 #457 式修法回归）；直接锁按钮
+  // 的 className 值（onClick 前最近的 className 属性，注释文字不参与）。
+  const delBtn = clientSource.match(/className: "([^"]+)"[\s\S]{0,300}?onClick: \(\) => removePersonaCard\(id\)/);
+  assert.ok(delBtn, "card delete button wiring must exist");
+  assert.strictEqual(delBtn[1], "mneme-persona-del", "card delete × must use mneme-persona-del, not mneme-set-del");
+});
+
+// 回归锁（复验实测踩中）：面板「检测更新」的状态名必须与后端 classify
+// （src/version-check.js）逐字对齐。此前前端误写 "latest"/"up_to_date"（后端
+// 从未返回过），检测成功也掉进 error 兜底——按钮永远报「检测失败」。
+// 这条缝两端各有测试（version-check.test.js 测 classify、面板测试测渲染），
+// 但契约本身没人管。锁三件事：①前端比较的字面量是后端真实返回值；②后端
+// classify 的返回集合没有前端漏接的成员；③apiFetch 的路由路径与后端注册一致。
+test("update-check status names match the backend classify contract verbatim", () => {
+  const vcSource = readFileSync(join(root, "src/version-check.js"), "utf8");
+  // ① 后端 classify 的全部返回字面量
+  const backendStatuses = new Set(
+    [...vcSource.matchAll(/return "([a-z-]+)";/g)].map((m) => m[1])
+  );
+  assert.ok(backendStatuses.has("up-to-date") && backendStatuses.has("outdated") && backendStatuses.has("ahead") && backendStatuses.has("unknown"),
+    `classify must return the known status set (saw ${[...backendStatuses].join(", ")})`);
+  // ② 前端 checkResultText 比较的每个状态名都必须 ∈ 后端集合（防再发明新名）
+  const iStart = clientSource.indexOf("function checkResultText");
+  assert.ok(iStart > 0, "checkResultText must exist");
+  // 函数块取到下一个同级 function 声明为止：indexOf("}") 会切在首个 if 的
+  // 右括号，比较分支被截断成 1 个（2026-10-17 实测）。
+  const iEnd = clientSource.slice(iStart).search(/\n {6}function /);
+  const block = clientSource.slice(iStart, iEnd > 0 ? iStart + iEnd : undefined);
+  const compared = [...block.matchAll(/updateInfo\.status === "([a-zA-Z_-]+)"/g)].map((m) => m[1]);
+  assert.ok(compared.length >= 2, `the panel must compare real statuses (saw ${compared.length})`);
+  const unknown = [...new Set(compared)].filter((s) => !backendStatuses.has(s));
+  assert.deepEqual(unknown, [], `前端比较了后端不会返回的状态名（检测成功也会显示失败）：${unknown.join(", ")}`);
+  // ③ 路由契约：前端 fetch 的路径必须与后端注册的 exact path 一致
+  assert.ok(clientSource.includes('apiFetch("/api/dsh-mneme/version-check")'),
+    "the panel must call the registered version-check route");
+  const apiSource = readFileSync(join(root, "src/api.js"), "utf8");
+  assert.ok(apiSource.includes('path: "/api/dsh-mneme/version-check"'),
+    "the backend must register the version-check route");
+});

package/test/distill-tx-embed-gap.test.js

@@ -0,0 +1,110 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+
+// ============================================================ distill-tx-embed-gap
+// 回归锁：此前 scheduleEmbed 在 txDepth>0 时首行直接 return（注释写 deferred，
+// 实际 transaction() 从不补跑）——与 #372 的实体抽取是同一个 bug 模板，只是受害者
+// 换成了嵌入：自动蒸馏（summarize 全部走 service.transaction）写入的 session:* 行
+// 100% 拿不到向量，语义检索对这批行永远失明。照 #372 的修复模板改为入队、提交后
+// 补跑、回滚截断。五把锁与 test/entities.test.js 的 #372 锁一一对应，锁的是
+// 「commit 才补跑、回滚绝不补跑」这个契约本身——任何一侧改回丢弃或回滚也补跑，
+// 这里当场红。
+
+function makeService(config = {}) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config });
+  return { store, service };
+}
+
+// 8 维定值向量；schedule 分支同步写回（语义同真实 embedder：调度即含写回），
+// 让整条链路确定性、无异步漂移。embedSingle 仅供 ready-gate/embedSingle 分支
+// 的调用方使用，本文件的锁都走 schedule 分支。
+function makeEmbedder(store, embedded) {
+  return {
+    schedule(memory) {
+      embedded.push(memory.id);
+      store.setEmbedding(memory.id, new Array(8).fill(0.5), "fake-model-hash");
+    },
+    embedSingle: async () => new Array(8).fill(0.5),
+  };
+}
+
+test("distill-tx: embedding queued inside transaction is written exactly once after commit", () => {
+  const { store, service } = makeService();
+  const embedded = [];
+  service.setEmbedder(makeEmbedder(store, embedded));
+  const r = service.transaction(() =>
+    service.saveWithDedupe({ type: "preference", title: "事务内创建", content: "x" })
+  );
+  const id = r.memory.id;
+  // 提交后补跑恰一次：向量非空、维度等于 embedder 输出（8 维）
+  assert.deepEqual(embedded, [id], "drain fires exactly once, after commit");
+  const row = store.db.prepare("SELECT embedding FROM memories WHERE id = ?").get(id);
+  const vec = JSON.parse(row.embedding);
+  assert.equal(vec.length, 8, "vector dimension equals embedder output");
+  store.close();
+});
+
+test("distill-tx: nothing schedules while txDepth > 0 (queued, not dropped, not immediate)", () => {
+  const { store, service } = makeService();
+  const embedded = [];
+  service.setEmbedder(makeEmbedder(store, embedded));
+  service.transaction(() => {
+    service.saveWithDedupe({ type: "preference", title: "事务内观察", content: "x" });
+    // 事务内此刻不得触发（排进队列而不是丢弃，也不是立即跑）
+    assert.equal(embedded.length, 0, "no embedding while txDepth > 0");
+  });
+  assert.equal(embedded.length, 1, "queued entry drains after commit");
+  store.close();
+});
+
+test("distill-tx: rolled-back transaction never embeds rolled-back rows", () => {
+  const { store, service } = makeService();
+  const embedded = [];
+  service.setEmbedder(makeEmbedder(store, embedded));
+  assert.throws(() => {
+    service.transaction(() => {
+      service.saveWithDedupe({ type: "preference", title: "会被回滚", content: "x" });
+      throw new Error("boom");
+    });
+  }, /boom/);
+  assert.equal(embedded.length, 0, "no embedding against rolled-back rows");
+  assert.equal(store.count(), 0, "row itself rolled back");
+  store.close();
+});
+
+// 与 #372 复审补锁同构：内层回滚截断只丢内层条目，外层提交 drain 外层条目。
+test("distill-tx: inner rollback drops only inner entries; outer commit drains the rest", () => {
+  const { store, service } = makeService();
+  const embedded = [];
+  service.setEmbedder(makeEmbedder(store, embedded));
+  const ids = [];
+  service.transaction(() => {
+    ids.push(service.saveWithDedupe({ type: "preference", title: "外层A", content: "x" }).memory.id);
+    try {
+      service.transaction(() => {
+        service.saveWithDedupe({ type: "preference", title: "内层回滚", content: "x" });
+        throw new Error("inner boom");
+      });
+    } catch { /* 内层回滚，外层继续 */ }
+    ids.push(service.saveWithDedupe({ type: "preference", title: "外层B", content: "x" }).memory.id);
+  });
+  assert.deepEqual(embedded.sort(), ids.sort(), "inner rolled-back row never embedded; outer rows drain once");
+  assert.equal(store.count(), 2);
+  store.close();
+});
+
+test("distill-tx: no unbounded cap — large transaction drains every entry", () => {
+  const { store, service } = makeService();
+  const embedded = [];
+  service.setEmbedder(makeEmbedder(store, embedded));
+  service.transaction(() => {
+    for (let i = 0; i < 150; i++) {
+      service.saveWithDedupe({ type: "preference", title: `批量${i}`, content: "x" });
+    }
+  });
+  assert.equal(embedded.length, 150, "no silent drop at any queue cap");
+  store.close();
+});

package/test/docs-config-keys.test.js

@@ -0,0 +1,65 @@
+// 「CONFIGURATION.md 是全键参考」这句声明需要一条闸门，否则它会慢慢变成谎话：
+// 2026-10 审计实测有 11 个 schema 键（graph 组 8 个、sensitiveScanEnabled、
+// injectTimePrefix、actionPipelineEnabled）在文档与双 README 里一个字都没有，
+// 而它们里有安全开关。锁法：从 Config({}) 的默认值深挖叶子键，要求每个键名
+// （或它的父路径，用于 heatTypeDecay 这类整表描述）在文档里出现。
+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 { Config } from "../src/config.js";
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const doc = readFileSync(path.join(root, "docs", "CONFIGURATION.md"), "utf8");
+const cfgSrc = readFileSync(path.join(root, "src", "config.js"), "utf8");
+
+function leafKeys(obj, prefix) {
+  const out = [];
+  for (const [k, v] of Object.entries(obj)) {
+    const p = prefix ? prefix + "." + k : k;
+    if (v && typeof v === "object" && !Array.isArray(v)) { out.push(...leafKeys(v, p)); continue; }
+    out.push({ path: p, leaf: k, parent: prefix || "" });
+  }
+  return out;
+}
+
+// 父路径回退是给「整表说明」用的例外，白名单写死在这里而不是「任何父路径都
+// 放行」——否则往 writeAdmission 里加个子键，只要文档提到 writeAdmission 就过，
+// 测试原本要防的漏键会静默复发（评审指出的漏洞）。新增例外必须显式加一行。
+const PARENT_ONLY_OK = new Set(["heatTypeDecay"]);
+
+test("CONFIGURATION.md 覆盖 schema 的每一个键", () => {
+  const keys = leafKeys(Config({}), "");
+  assert.ok(keys.length > 150, "键枚举失败会静默返回 0 项，先锁下限");
+  const missing = keys.filter((k) => {
+    // 完整路径优先（"writeAdmission.enabled"），其次才是显式白名单里的整表父路径。
+    if (doc.includes(k.path)) return false;
+    if (k.parent && PARENT_ONLY_OK.has(k.parent) && doc.includes(k.parent)) return false;
+    // 表里写的是裸键名也认（绝大多数顶层键就是这么写的）。
+    return !doc.includes(k.leaf);
+  });
+  assert.deepEqual(missing.map((m) => m.path), []);
+});
+
+// lightMode 清单是有边界的一节：整份文档 grep 会让「删掉清单里的某一行」照样
+// 通过（图谱表里还留着同名键），测试要盯的漏项就藏在那个缝里。
+function lightSection(text) {
+  const start = text.indexOf("lightMode 强制关闭清单");
+  assert.ok(start >= 0, "文档里应有「lightMode 强制关闭清单」一节");
+  const rest = text.slice(start);
+  const end = rest.indexOf("预设只是默认值");
+  return end > 0 ? rest.slice(0, end) : rest;
+}
+
+test("LIGHT_MODE_OFF 的每一项都写进了文档的轻量档清单", () => {
+  // LIGHT_MODE_OFF 没有导出，只能解析源码文本；先锁解析结果的长度，防止
+  // 正则失配时这个用例变成「空数组 ⊂ 文档」的永真断言。
+  const m = cfgSrc.match(/const LIGHT_MODE_OFF = \[([\s\S]*?)\];/);
+  assert.ok(m, "LIGHT_MODE_OFF 应从 src/config.js 中解析出来");
+  const names = [...m[1].matchAll(/"([^"]+)"/g)].map((x) => x[1]);
+  assert.ok(names.length >= 20, "解析到 " + names.length + " 项，少于预期的 21 项");
+  const section = lightSection(doc);
+  const missing = names.filter((n) => !section.includes(n));
+  assert.deepEqual(missing, []);
+});

package/test/dream-maxtokens-fallback.test.js

@@ -0,0 +1,132 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { withMaxTokensFallback, parseMaxTokensCap, MAX_TOKENS_REJECT_RE } from "../src/dream.js";
+
+// Issue #478：dreamMaxTokens 默认 131072 原样发给 OpenAI 兼容网关，很多网关硬
+// 上限更小（实测 dream_runs 180 连败的报错："max_tokens 不能超过 65536"），
+// 400 直接拒、推理没开始。本套锁两件事：上限提取认得出显式上限、认不出时不猜；
+// withMaxTokensFallback 在 stream（result===undefined + getStreamError）与
+// throw 两条路径上都按提取到的上限降级重试恰一次，AbortError 永不被降级吞掉。
+
+function makeLogger() {
+  const warns = [];
+  return { warns, logger: { warn: (...a) => warns.push(a.join(" ")), info() {}, error() {} } };
+}
+
+test("parseMaxTokensCap: 显式上限认得出（中/英/符号三种说法）", () => {
+  assert.equal(parseMaxTokensCap("max_tokens 不能超过 65536"), 65536);
+  assert.equal(parseMaxTokensCap("Maximum value is 65536"), 65536);
+  assert.equal(parseMaxTokensCap("max_tokens must be at most 32768"), 32768);
+  assert.equal(parseMaxTokensCap("max_tokens <= 8192"), 8192);
+  assert.equal(parseMaxTokensCap("max_tokens 不得超过 4096"), 4096);
+});
+
+test("parseMaxTokensCap: 认不出显式上限时返回 null，绝不猜", () => {
+  // 只有请求值、没有上限值——把 131072 误当上限会让重试原样再炸一次
+  assert.equal(parseMaxTokensCap("max_tokens 131072 is too large for this model"), null);
+  assert.equal(parseMaxTokensCap("bad request"), null);
+  assert.equal(parseMaxTokensCap(""), null);
+  assert.equal(parseMaxTokensCap(null), null);
+});
+
+test("MAX_TOKENS_REJECT_RE: 命中 max_tokens/maxTokens 两种写法，不误伤无关报错", () => {
+  assert.ok(MAX_TOKENS_REJECT_RE.test("max_tokens 不能超过 65536"));
+  assert.ok(MAX_TOKENS_REJECT_RE.test("maxTokens exceed limit"));
+  assert.ok(!MAX_TOKENS_REJECT_RE.test("reasoning effort unsupported"));
+});
+
+test("withMaxTokensFallback: stream 路径（undefined + getStreamError）按上限降级重试恰一次", async () => {
+  const { logger, warns } = makeLogger();
+  const ctx = { logger };
+  const calls = [];
+  const attempt = async (tokens) => {
+    calls.push(tokens);
+    // 第一次发大值 → 网关拒收折叠成 undefined；重试用 65536 → 成功
+    return tokens > 65536 ? undefined : `ok@${tokens}`;
+  };
+  const out = await withMaxTokensFallback(ctx, 131072, attempt, () =>
+    "400 max_tokens 不能超过 65536");
+  assert.equal(out, "ok@65536");
+  assert.deepEqual(calls, [131072, 65536], "大值先发，拒收后按上限重试");
+  assert.equal(warns.length, 1, "降级必须留痕");
+  assert.match(warns[0], /131072.*65536/);
+});
+
+test("withMaxTokensFallback: throw 路径同样降级，AbortError 永远直通", async () => {
+  const { logger } = makeLogger();
+  const ctx = { logger };
+  // throw 路径：第一次抛 400，重试成功
+  const calls = [];
+  const out = await withMaxTokensFallback(ctx, 131072, async (tokens) => {
+    calls.push(tokens);
+    if (tokens > 65536) throw new Error("invalid max_tokens: max_tokens 不能超过 65536");
+    return `ok@${tokens}`;
+  }, () => "");
+  assert.equal(out, "ok@65536");
+  assert.deepEqual(calls, [131072, 65536]);
+
+  // AbortError：即使消息里带 max_tokens 字样也绝不触发重试（取消意图不可吞）
+  const abort = new Error("max_tokens rejected during dispose");
+  abort.name = "AbortError";
+  const abCalls = [];
+  await assert.rejects(
+    withMaxTokensFallback(ctx, 131072, async (tokens) => { abCalls.push(tokens); throw abort; }, () => ""),
+    /dispose/
+  );
+  assert.deepEqual(abCalls, [131072], "AbortError 不重试");
+});
+
+test("withMaxTokensFallback: 无上限可提取或上限不小于当前值时不重试", async () => {
+  const { logger } = makeLogger();
+  const ctx = { logger };
+  // 报错只有请求值没有上限 → 不猜，原样 undefined 返回
+  let calls = 0;
+  const out1 = await withMaxTokensFallback(ctx, 131072, async () => { calls++; return undefined; }, () =>
+    "max_tokens 131072 is too large for this model");
+  assert.equal(out1, undefined);
+  assert.equal(calls, 1, "认不出上限就不重试");
+
+  // 上限 >= 当前值（报错自相矛盾）→ 不重试，throw 路径原样抛
+  const boom = new Error("max_tokens 不能超过 131072");
+  await assert.rejects(
+    withMaxTokensFallback(ctx, 131072, async () => { throw boom; }, () => ""),
+    (e) => e === boom,
+    "cap >= maxTokens 时不重试且原样抛"
+  );
+});
+
+test("withMaxTokensFallback: 无关报错不触发重试（stream 与 throw 双路径）", async () => {
+  const { logger } = makeLogger();
+  const ctx = { logger };
+  let calls = 0;
+  const out = await withMaxTokensFallback(ctx, 131072, async () => { calls++; return undefined; }, () =>
+    "reasoning effort UNSUPPORTED_REASONING_EFFORT");
+  assert.equal(out, undefined);
+  assert.equal(calls, 1);
+
+  await assert.rejects(
+    withMaxTokensFallback(ctx, 131072, async () => { throw new Error("quota exhausted"); }, () => ""),
+    /quota exhausted/
+  );
+});
+
+// 接线锁：单测绿不代表真接上了。#478 的第一次实现只挂了 dream 侧三个点，
+// sleep.js 两处仍原样发 config.sleepMaxTokens，而面板 hint 已对外承诺
+// 「超上限同样自动降级」——这种「函数有、没人用」的缺口只靠行为测试抓不到。
+test("接线锁：dreamMaxTokens/sleepMaxTokens 的五个使用点全部包在 withMaxTokensFallback 里", async () => {
+  const { readFile } = await import("node:fs/promises");
+  const srcDir = new URL("../src/", import.meta.url);
+  const files = { "dream.js": await readFile(new URL("dream.js", srcDir), "utf8"), "dream/sleep.js": await readFile(new URL("dream/sleep.js", srcDir), "utf8") };
+  for (const [name, source] of Object.entries(files)) {
+    // 任何一处还把 config.dreamMaxTokens/sleepMaxTokens 直接当 maxTokens 发，就是漏接线。
+    assert.ok(
+      !/maxTokens:\s*config\.(dream|sleep)MaxTokens/.test(source),
+      `${name}: still passes config.*MaxTokens straight into maxTokens — wrap it in withMaxTokensFallback`
+    );
+  }
+  // 五个调用点：dream 三条（叙述/巩固/摘要）+ sleep 两条（冲突/模式）。
+  const dreamHits = files["dream.js"].match(/withMaxTokensFallback\(ctx, config\.dreamMaxTokens/g) ?? [];
+  const sleepHits = files["dream/sleep.js"].match(/withMaxTokensFallback\(ctx, config\.sleepMaxTokens/g) ?? [];
+  assert.equal(dreamHits.length, 3, `dream.js must wrap all 3 dreamMaxTokens sites (got ${dreamHits.length})`);
+  assert.equal(sleepHits.length, 2, `dream/sleep.js must wrap both sleepMaxTokens sites (got ${sleepHits.length})`);
+});