@modusensus/dsh-mneme 0.8.15 → 0.8.16

package/test/api.test.js

@@ -676,8 +676,11 @@ test("GET /api/dsh-mneme/features returns empty overrides and effective config d
   // issue #339 新增 dreamMergeGuard、
   // issue #218/E5 新增 injectHeatEnabled、
   // issue #164 A2 新增 sensitiveScanEnabled（顶层扁平键，走 configFlagValue 默认分支）、
-  // issue #380 新增 preInjectGate.enabled/preInjectGate.enforce（注入前判定两级开关））
-  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);
+  // issue #380 新增 preInjectGate.enabled/preInjectGate.enforce（注入前判定两级开关）、
+  // #135 成本审计派生新增 dreamMaxMergePerRun（单轮 merge 决策上限））
+  // issue #399 新增 distillRecords.enabled/distillRecords.retentionDays（蒸馏原文留存 +
+  // 溯源：开关与保留期都在嵌套对象里，两个都进 NESTED_FLAG_PATHS））
+  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);
   assert.equal(data.effective.dreamSkipInvalid, true);
   assert.equal(data.effective.allowCrossTypeMerge, false);
   assert.equal(data.effective.dreamMergeGuard, true);
@@ -688,6 +691,7 @@ test("GET /api/dsh-mneme/features returns empty overrides and effective config d
   assert.equal(data.effective.dreamMinIntervalMinutes, 0);
   assert.equal(data.effective.autoDreamFailureBackoff, false);
   assert.equal(data.effective.dreamMaxTokens, 131072);
+  assert.equal(data.effective.dreamMaxMergePerRun, 40);
   assert.equal(data.effective.sleepProvider, "");
   assert.equal(data.effective.sleepModel, "");
   assert.equal(data.effective.autoInject, true);
@@ -706,6 +710,10 @@ test("GET /api/dsh-mneme/features returns empty overrides and effective config d
   assert.equal(data.effective["writeAdmission.enforce"], false);
   // #164 A2：密钥/PII 判据自己的闸，同样默认关（#332 的行为逐字节保留）。
   assert.equal(data.effective.sensitiveScanEnabled, false);
+  // #399：蒸馏原文留存默认关（这是一份对话原文副本，不该由升级默认打开），
+  // 保留期默认 90 天（与 llmAudit.retentionDays 同款）。
+  assert.equal(data.effective["distillRecords.enabled"], false);
+  assert.equal(data.effective["distillRecords.retentionDays"], 90);
   // 新增字符串 / URL / 枚举键
   assert.equal(data.effective.localEmbedModel, "Xenova/bge-small-zh-v1.5");
   assert.equal(data.effective.ollamaBaseUrl, "http://localhost:11434");
@@ -763,6 +771,10 @@ test("PUT /api/dsh-mneme/features round-trips nested, string, url and enum keys"
     // #380：同款点号键往返——白名单与 NESTED_FLAG_PATHS 成对缺一即静默缺键。
     "preInjectGate.enabled": true,
     "preInjectGate.enforce": true,
+    // #399：布尔与整数范围两类点号键都往返一次（retentionDays 是 int，同样必须进
+    // NESTED_FLAG_PATHS——否则 configFlagValue 落到顶层同名键上，effective 静默缺键）。
+    "distillRecords.enabled": true,
+    "distillRecords.retentionDays": 30,
     // #164 A2：顶层扁平键（不是对象子字段），与上面两个点号键走同一条往返；
     // 它的默认值断言在计数锁那一条里，这里钉的是「PUT 存进去、effective 读得回」。
     sensitiveScanEnabled: true,
@@ -782,6 +794,8 @@ test("PUT /api/dsh-mneme/features round-trips nested, string, url and enum keys"
     "writeAdmission.enforce": true,
     "preInjectGate.enabled": true,
     "preInjectGate.enforce": true,
+    "distillRecords.enabled": true,
+    "distillRecords.retentionDays": 30,
     sensitiveScanEnabled: true,
     embedProvider: "local",
     ollamaBaseUrl: "http://127.0.0.1:11434",
@@ -796,6 +810,8 @@ test("PUT /api/dsh-mneme/features round-trips nested, string, url and enum keys"
   // #380：往返回来的覆盖值压过 bundle 配置默认
   assert.equal(data.effective["preInjectGate.enabled"], true);
   assert.equal(data.effective["preInjectGate.enforce"], true);
+  assert.equal(data.effective["distillRecords.enabled"], true);
+  assert.equal(data.effective["distillRecords.retentionDays"], 30, "整数点号键也要读得回来");
   assert.equal(data.effective.sensitiveScanEnabled, true);
   assert.equal(data.effective.embedProvider, "local");
   assert.equal(data.effective.ollamaBaseUrl, "http://127.0.0.1:11434");
@@ -1162,6 +1178,13 @@ test("GET /api/dsh-mneme/conflicts joins both sides of unresolved conflicts", as
   );
   assert.equal(data.items[0].memory_a.archived, false);
   assert.equal(data.items[0].memory_b.archived, false);
+  // 裁决依据（冲突窗可读性报障）：两侧必须带新旧时间戳，否则面板只能显示
+  // A 方/B 方两个标签，用户没有客观依据判断该留哪条。
+  for (const key of ["memory_a", "memory_b"]) {
+    assert.equal(typeof data.items[0][key].created_at, "string", `${key} must carry created_at`);
+    assert.equal(typeof data.items[0][key].updated_at, "string", `${key} must carry updated_at`);
+    assert.ok(!Number.isNaN(Date.parse(data.items[0][key].updated_at)), `${key}.updated_at must parse`);
+  }
   // 幽灵侧容忍缺失
   service.saveConflictPending({ memory_a: a.id, memory_b: "ghost-id", reason: "对方已删" });
   const res2 = new FakeRes();

package/test/client.test.js

@@ -600,9 +600,12 @@ test("explorer chrome aligns with the host design system", () => {
     /\.mneme-vtab\.mneme-active::after/.test(clientSource),
     "active sub-tabs use the host underline treatment"
   );
+  // #178：这里原本直接断言宿主品牌蓝。宿主蓝在浅色画布上只有 4.23:1，对 13px
+  // 正文不足 AA，所以面板改用自己的语义色层 --mneme-accent（同一条宿主 token
+  // 往 label-primary 方向混 15%），换肤仍跟随宿主。意图不变：激活态是品牌蓝。
   assert.ok(
-    clientSource.includes(".mneme-vtab.mneme-active{color:var(--dsw-alias-state-business-primary)}"),
-    "active sub-tab text must turn the host brand blue"
+    clientSource.includes(".mneme-vtab.mneme-active{color:var(--mneme-accent)}"),
+    "active sub-tab text must turn the host brand blue (via the panel accent layer)"
   );
   assert.equal(
     /\.mneme-xmain\{[^}]*border:1px/.test(clientSource),
@@ -664,6 +667,48 @@ test("heat badges render from the /list projection and self-hide when off", () =
   );
 });
 
+// Token 去向三屏（#412）：前端只拿 by_day 的稀疏行渲染两种时间尺度，三个坑
+// 都在这一层，且都是「不报错但图错了」的静默失效，所以锁形状而非锁行为：
+// ① 柱状图必须补连续 7 天——by_day 是 GROUP BY 的稀疏结果，直接映射会缺列；
+// ② 热力图的 56 格必须来自独立的 days=56 请求——复用 days=7 的响应会让 56 格
+//    里 48 格恒 0（图看着正常，其实只有一周有数据）；
+// ③ 开合不能挂在 details 上——details 的 onClick 会连折叠区子卡片的点击一起
+//    吃掉（preventDefault 拦掉冒泡的激活事件），必须挂 summary。
+test("token flow: 7-day bars pad to a continuous week, heatmap uses its own 56-day window", () => {
+  // ① 连续 7 天：右端对齐今天 UTC，缺日填 0
+  assert.ok(
+    /Array\.from\(\{ length: 7 \}/.test(clientSource),
+    "the 7-day bars must be generated as a fixed 7-slot array, not mapped straight off by_day"
+  );
+  assert.ok(
+    /rawDayMap\.get\(key\) \?\? 0/.test(clientSource),
+    "missing days must fill 0 so the x-axis stays a continuous week"
+  );
+  // stats 为 null（未到）与 {}（已知为空）必须分开：前者不画柱，后者补零
+  assert.ok(
+    /const rawDays = stats && Array\.isArray\(stats\.by_day\) \? stats\.by_day : null;/.test(clientSource),
+    "an unloaded response must stay null, else the loading state paints 7 zero bars"
+  );
+  // ② 热力图独立 56 天窗口
+  assert.ok(
+    clientSource.includes('llm-audit/stats?days=56'),
+    "the heatmap must issue its own days=56 request"
+  );
+  assert.ok(
+    /heatStats && Array\.isArray\(heatStats\.by_day\)/.test(clientSource),
+    "the heatmap must read heatStats.by_day, not stats.by_day"
+  );
+  // ③ 开合挂 summary，不挂 details
+  assert.ok(
+    !/className: "mneme-legacy",\s*\n\s*open: legacyOpen,\s*\n\s*onClick/.test(clientSource),
+    "the click handler must not sit on <details>: it swallows clicks from child cards"
+  );
+  assert.ok(
+    /h\("summary", \{ onClick: \(e\) => \{ e\.preventDefault\(\); setLegacyOpen\(!legacyOpen\); \} \}/.test(clientSource),
+    "the toggle must be bound on <summary>, the native disclosure handle"
+  );
+});
+
 // 巩固/睡眠模型路由 UI：下拉数据来自宿主侧已注册适配器（/llm-providers，
 // 云端插件侧端点），「测试连通性」走 POST /test-model 真实最小调用。旧后端
 // 端点 404 时必须回退纯文本输入——前端自门控，不挡旧版本。
@@ -1217,6 +1262,313 @@ test("mcp card: mount snippet is copyable and token-keyed to the external API",
     assert.ok(occurrences >= 2, `i18n key ${key} must exist in both zh and en (got ${occurrences})`);
   }
 });
+// --- #400 冲突裁决窗可读性（报障原话：窗口太小又不能放大，完全对比不了内容，只好
+// 两个都删或胡乱选一个）---
+// 锁四件事：展开切换存在且默认收起（折叠态仍走 140 字预览，既有布局不回归）；
+// 展开态渲染未截断全文并去掉 diff 的行数钳制；判读依据行（类型/重要度/字数/
+// 新旧 + 单侧复制）在位；窄容器降级单列。缺任何一条，报障就复发。
+test("conflict queue: expandable full text with decision metadata", () => {
+  assert.ok(clientSource.includes('"memory.status.conflictQueue.expand"'), "collapsed state must offer 展开全文");
+  assert.ok(clientSource.includes('"memory.status.conflictQueue.collapse"'), "expanded state must offer 收起全文");
+  assert.ok(clientSource.includes('"aria-expanded": open'), "the toggle must expose aria-expanded");
+  assert.ok(/open \? \(s\.content \|\| ""\) : \(s\.content \|\| ""\)\.slice\(0, 140\)/.test(clientSource),
+    "collapsed keeps the 140-char preview while expanded must render untruncated content");
+  assert.ok(clientSource.includes("mneme-conflict-diff--full"), "expanded diff must drop the 4-line clamp");
+  // 展开态高度上限必须与视口无关：宿主可能把面板放进零高视口（隐藏 webview /
+  // 后台页），那时 vh 会算成 0px，「展开全文」直接看不见字——肉眼验收实测踩过。
+  assert.ok(clientSource.includes("max-height:28em"), "expanded height cap must be viewport-independent");
+  assert.equal(/\.mneme-conflict-(diff--full|text)\{[^}]*\d+vh/.test(clientSource), false,
+    "conflict expand rules must not use vh");
+  assert.ok(clientSource.includes('"memory.status.conflictQueue.chars"'), "each side must show its length");
+  assert.ok(clientSource.includes('"memory.status.conflictQueue.updated"'), "each side must show which one is newer");
+  assert.ok(clientSource.includes("copySide"), "each side must be copyable for external comparison");
+  assert.ok(clientSource.includes("@container (max-width:560px){.mneme-conflict-pair{grid-template-columns:1fr}}"),
+    "a narrow panel must fall back to one column instead of two unreadable halves");
+  for (const key of [
+    "memory.status.conflictQueue.expand",
+    "memory.status.conflictQueue.collapse",
+    "memory.status.conflictQueue.copySide",
+    "memory.status.conflictQueue.copiedSide",
+    "memory.status.conflictQueue.importance",
+    "memory.status.conflictQueue.chars",
+    "memory.status.conflictQueue.updated",
+    "memory.status.conflictQueue.created"
+  ]) {
+    const occurrences = clientSource.split(`"${key}"`).length - 1;
+    assert.ok(occurrences >= 2, `i18n key ${key} must exist in both zh and en (got ${occurrences})`);
+  }
+});
+
+// #386 第 5 条：面板手动新增记忆。这一块最容易悄悄退化——菜单项被删掉、弹层被
+// 从树里摘掉、或者表单又长回 scope/sensitivity 输入框（那会绕开详情抽屉的「放宽
+// 可见性」二次确认），面板表面上看不出坏，只是入口没了。所以既锁「入口存在」，
+// 也锁「入口真的挂在树上」。
+test("panel can create a memory by hand: menu entry wired to the dialog", () => {
+  // 入口在「更多操作」菜单里，且菜单项真的调用 setCreateOpen(true)——只断言文案
+  // 存在的话，把 onClick 摘掉测试照样绿。
+  assert.ok(clientSource.includes('"memory.explorer.newMemory"'), "menu entry label must exist");
+  assert.ok(/role: "menuitem", onClick: \(\) => \{ setCreateOpen\(true\); setMenuOpen\(false\); \}/.test(clientSource),
+    "the menu item must actually open the create dialog");
+  assert.ok(clientSource.includes("const [createOpen, setCreateOpen] = useState(false)"),
+    "the dialog needs its own open state");
+  // 弹层必须挂在树上并接上回调：onCreated 同时刷新列表与选中新行（并入既有条目时
+  // 返回的 id 是被并入那一行，也该滚进视野）。
+  assert.ok(/createOpen && h\(CreateDialog, \{/.test(clientSource), "the dialog must be mounted conditionally");
+  assert.ok(/onCreated: \(d\) => \{ setReloadKey\(\(k\) => k \+ 1\); if \(d && d\.id\) setSelectedId\(d\.id\); \}/.test(clientSource),
+    "creating must refresh the list and select the resulting row");
+  // 打后端的路由是 /create，不是 standalone 的 /memories：面板与工具必须走同一条
+  // saveWithDedupe 路径，否则「同标题并入」的提示在面板上会失灵。
+  assert.ok(clientSource.includes('apiFetch("/api/dsh-mneme/create"'),
+    "the dialog must post to the panel create route");
+  assert.ok(/d\.action === "merged" \? t\("memory\.explorer\.newMerged"\) : t\("memory\.explorer\.newCreated"\)/.test(clientSource),
+    "merged and created are different facts and must be reported differently");
+  // 弹层源码切片：下面「表单里有什么 / 没有什么」的断言一律在这段上做。在整包上做
+  // 等于没锁——这些字段名在 bundle 里到处都是，`clientSource.includes("title")` 恒真。
+  const dialogStart = clientSource.indexOf("function CreateDialog");
+  const dialogEnd = clientSource.indexOf("function MemoryExplorer", dialogStart);
+  assert.ok(dialogStart >= 0 && dialogEnd > dialogStart, "CreateDialog must be findable in the bundle");
+  const dialogSource = clientSource.slice(dialogStart, dialogEnd);
+  // 表单字段与 memory_save 工具对齐，且锁的是**真实请求体写法**：多一个字段（比如
+  // scope/sensitivity）这段就匹配不上，少一个 trim 也匹配不上。锁裸字段名会恒真。
+  assert.match(dialogSource,
+    /JSON\.stringify\(\{\s*type,\s*title: title\.trim\(\),\s*content: content\.trim\(\),\s*importance,\s*tags: tags\.split\(","\)\.map\(\(s\) => s\.trim\(\)\)\.filter\(Boolean\)\s*\}\)/,
+    "the create request body must carry exactly type/title/content/importance/tags");
+  // 成功路径**不得**重置 busy：提示要停 900ms 才关窗，这期间按钮若重新可点，第二次
+  // 同 type+title 会落进同一行并把正文再追加一遍（service 走 appendContent），一次
+  // 误触就写坏一条记忆。所以全弹层只允许 catch 那条路重置 busy。
+  assert.equal(dialogSource.split("setBusy(false)").length - 1, 1,
+    "only the error path may reset busy; the success path must stay disabled until the dialog closes");
+  assert.match(dialogSource, /\.catch\(\(\) => \{ setBusy\(false\); setErr\(t\("memory\.explorer\.newFailed"\)\); \}\)/,
+    "the single busy reset must be the error path");
+  // 按钮文案同理：成功后 busy 仍为 true，若只看 busy，写入早就完成了按钮还写着「保存
+  // 中…」——既骗用户又和旁边那行「已新建」自相矛盾。msg 一置上就切回正常文案。
+  assert.match(dialogSource, /busy && !msg \? t\("memory\.explorer\.newSaving"\) : t\("memory\.explorer\.newConfirm"\)/,
+    "once the write succeeded the button must stop claiming it is still saving");
+  assert.equal(/newScope|sensitivity/.test(dialogSource), false,
+    "the create form must not offer scope/sensitivity: that path bypasses the widen-confirm guard");
+  // document 不在类型下拉里：铸造口唯一（registerDocument，#230），后端也会 400。
+  assert.equal(dialogSource.includes('"document"'), false,
+    "document rows are minted only via registerDocument and must not be offered here");
+  // 类型白名单与 src/tools.js 的 memory_save enum 逐字一致（缺一个就会有人点进去才被拒）。
+  for (const k of ["preference", "project", "decision", "history", "rejected_solution", "pitfall", "constraint"]) {
+    assert.ok(dialogSource.includes(`"${k}"`), `type option ${k} must be offered`);
+  }
+  // 前端空值拦截只是省一次往返，服务端校验才是权威——但两者都得在，否则空标题会
+  // 一路发出去再弹一个 400 给用户看。
+  assert.ok(dialogSource.includes('if (!title.trim()) { setErr(t("memory.explorer.newNoTitle")); return; }'),
+    "empty title must be caught before the round trip");
+  assert.ok(dialogSource.includes('if (!content.trim()) { setErr(t("memory.explorer.newNoContent")); return; }'),
+    "empty body must be caught before the round trip");
+  // 十四个新键必须中英成对（与上面那条全局锁同口径，这里列出名字便于定位）。
+  for (const key of [
+    "memory.explorer.newMemory",
+    "memory.explorer.newTitle",
+    "memory.explorer.newHint",
+    "memory.explorer.newType",
+    "memory.explorer.newTitlePlaceholder",
+    "memory.explorer.newContentPlaceholder",
+    "memory.explorer.newTagsPlaceholder",
+    "memory.explorer.newConfirm",
+    "memory.explorer.newSaving",
+    "memory.explorer.newCreated",
+    "memory.explorer.newMerged",
+    "memory.explorer.newFailed",
+    "memory.explorer.newNoTitle",
+    "memory.explorer.newNoContent"
+  ]) {
+    const occurrences = clientSource.split(`"${key}"`).length - 1;
+    assert.ok(occurrences >= 2, `i18n key ${key} must exist in both zh and en (got ${occurrences})`);
+  }
+});
+// --- issue #386 第 4 条：存储回收卡（dry-run 预估 + 两步确认执行）---
+// 这是「不可逆的内容丢弃」在面板上的唯一入口，所以锁的不是「有没有这张卡」，而是三条
+// 不变量：执行必须两步、POST 必须逐字带确认门、VACUUM 失败不得渲染成干净的成功。
+// 所有断言都做在**卡片切片**上：路由串/dryRun/confirm 这些字面量在整包里到处都是，
+// 在 clientSource 上做 includes 恒真、等于没锁（#408 评审踩过的坑）。
+const maintCardSource = () => {
+  const start = clientSource.indexOf("function MaintenanceCard");
+  const end = clientSource.indexOf("function MirrorHealthCard", start);
+  assert.ok(start >= 0 && end > start, "MaintenanceCard must be findable in the bundle (切片锚点变了？)");
+  return clientSource.slice(start, end);
+};
+
+test("maintenance card: i18n keys are bilingual and the section is really rendered", () => {
+  for (const key of [
+    "memory.status.sec.maintenance",
+    "memory.status.maint",
+    "memory.status.maint.freelist",
+    "memory.status.maint.plannedInputs",
+    "memory.status.maint.plannedEmbeddings",
+    "memory.status.maint.window",
+    "memory.status.maint.windowUnit",
+    "memory.status.maint.windowLabel",
+    "memory.status.maint.reestimate",
+    "memory.status.maint.reestimating",
+    "memory.status.maint.stale",
+    "memory.status.maint.vacuum",
+    "memory.status.maint.vacuumHint",
+    "memory.status.maint.execute",
+    "memory.status.maint.confirm",
+    "memory.status.maint.running",
+    "memory.status.maint.cancel",
+    "memory.status.maint.confirmHint",
+    "memory.status.maint.badWindow",
+    "memory.status.maint.failed",
+    "memory.status.maint.done",
+    "memory.status.maint.size",
+    "memory.status.maint.reclaimed",
+    "memory.status.maint.clearedInputs",
+    "memory.status.maint.clearedEmbeddings",
+    "memory.status.maint.receipt",
+    "memory.status.maint.receiptNone",
+    "memory.status.maint.duration",
+    "memory.status.maint.vacuumRan",
+    "memory.status.maint.vacuumOff",
+    "memory.status.maint.vacuumFailed",
+    "memory.status.maint.vacuumFailedHint"
+  ]) {
+    // 数的是**字典行**（`"key": "` 顶格成行），不是裸字符串出现次数。裸数会把调用点
+    // 一起算进来：`t("...maint.done")` 在卡片里本来就有一次，删掉一整行英文译文之后
+    // 「字典 zh 行 + 调用点」照样凑够 2——锁恒真，就是这么漏的（本条第一版被 M1 变异
+    // 抓出来了）。行首锚定后，少一侧译文就只剩 1。
+    const entries = clientSource.match(new RegExp(`^\\s*"${key.replace(/\./g, "\\.")}"\\s*:\\s*"`, "gm"));
+    const count = entries ? entries.length : 0;
+    assert.equal(count, 2, `i18n key ${key} must appear as exactly one dictionary line per language (got ${count})`);
+  }
+  // 分区键只在字典里躺着不算加分区：必须真的渲染出「维护」这段扫读锚点。
+  assert.ok(clientSource.includes('h("div", { className: "mneme-statushead" }, t("memory.status.sec.maintenance"))'),
+    "the maintenance section head must render from the dictionary key");
+});
+
+test("maintenance card: the reclaim route is the in-process one, not the standalone data plane", () => {
+  const src = maintCardSource();
+  // 走 /api/dsh-mneme/... 这条 in-process 路由：它才有 requireAuth + 与 CLI 同一条
+  // reclaim 实现。写成 standalone 数据面的路径会绕开面板身份的鉴权口径。
+  assert.equal(src.split('"/api/dsh-mneme/maintenance/reclaim"').length - 1, 1,
+    "the card must name the in-process reclaim route exactly once (via its path constant)");
+  // 预估走 GET 且把窗口作为查询参数带上；粘在按钮上——键入即发会让数字在半截输入时跳。
+  assert.ok(src.includes("`${RECLAIM_PATH}?olderThanDays=${days}`"),
+    "re-estimating must GET the route with the current window as a query parameter");
+  assert.equal(src.split("onClick: estimate").length - 1, 1,
+    "only the re-estimate button may trigger an estimate (no request per keystroke)");
+  assert.ok(src.includes('onChange: (e) => setDays(e.target.value)'),
+    "typing in the window field must only update local state");
+});
+
+test("maintenance card: execution carries the verbatim dryRun:false + confirm:true gate", () => {
+  const src = maintCardSource();
+  // 逐字锁请求体：多一个字段、少一个空格、把 Number(days) 换成裸 days 都匹配不上。
+  // 锁裸字段名（dryRun/confirm）会恒真——它们在这段源码里各自还有别的出现位置。
+  assert.match(src,
+    /JSON\.stringify\(\{ dryRun: false, confirm: true, olderThanDays: Number\(days\), vacuum \}\)/,
+    "the executing body must be exactly dryRun:false + confirm:true + olderThanDays + vacuum");
+  // 全卡只有一处能改库：确认门之外的任何一次 POST 都是「第一次点就真清了」。
+  assert.equal(src.split('method: "POST"').length - 1, 1, "the card must issue exactly one POST");
+  assert.equal(src.split("dryRun: false").length - 1, 1, "exactly one mutating body may exist");
+  // 窗口非法时不得发请求：0 在服务端是「清掉全部快照」，畸形输入绝不能静默落进最坏解释。
+  assert.ok(src.includes('if (!/^\\d+$/.test(days)) { setError(t("memory.status.maint.badWindow")); setArmed(false); return; }'),
+    "a non-numeric window must be rejected locally before any round trip");
+  // 上界同样在本地拦：/^\d+$/ 放得过 1e20 与 400 位数字（后者化成 Infinity），后端
+  // 会回 400，但那时用户只看到一句「回收失败」，分不清是窗口不合法还是网络问题。
+  assert.match(src, /const MAX_WINDOW_DAYS = 3650;/,
+    "the card must carry the same upper bound as the backend");
+  assert.ok(src.includes('if (Number(days) > MAX_WINDOW_DAYS) { setError(t("memory.status.maint.badWindow")); setArmed(false); return; }'),
+    "an out-of-range window must be rejected locally, before any round trip");
+});
+
+test("maintenance card: 'no receipt' does not claim a single cause", () => {
+  // writeReceipt 返回 null 有两种成因：审计被关（config.llmAudit.enabled === false），
+  // 或回执写库失败（saveLlmAudit 抛错，只 warn）。旧文案「无（审计未启用）」把第二种
+  // 情况说成第一种——而这行出现在不可逆操作的结果区，用户会照它去对账。
+  for (const wording of [
+    '"memory.status.maint.receiptNone": "未记录（审计未启用或回执写入失败）"',
+    '"memory.status.maint.receiptNone": "Not recorded (audit disabled or receipt write failed)"'
+  ]) {
+    assert.ok(clientSource.includes(wording),
+      `the missing-receipt wording must name both causes: ${wording}`);
+  }
+});
+
+test("maintenance card: no window.confirm — the host webview cannot be relied on for it", () => {
+  const src = maintCardSource();
+  assert.equal(/window\.confirm/.test(src), false,
+    "window.confirm is not reliably available in the host webview; the in-card confirm state is the gate");
+  assert.equal(/(^|[^.\w])confirm\s*\(/.test(src), false,
+    "no blocking confirm() call may exist in the card (the confirm state is a rendered branch)");
+  assert.ok(src.includes("mneme-btndangerconfirm"),
+    "the armed state must use the repo's existing danger-confirm styling");
+});
+
+test("maintenance card: mounted in the status view under the maintenance section", () => {
+  // 组件存在但没挂上树 = 用户永远看不到，正是这条 issue 报的缺口。
+  const panelStart = clientSource.indexOf("function StatusPanel");
+  const panelEnd = clientSource.indexOf("function ", clientSource.indexOf("h(WorkbenchSection", panelStart));
+  assert.ok(panelStart >= 0 && panelEnd > panelStart, "StatusPanel must be findable in the bundle");
+  const panel = clientSource.slice(panelStart, panelEnd);
+  assert.ok(panel.includes("h(MaintenanceCard, { t })"),
+    "the status panel must render the maintenance card");
+  assert.ok(panel.includes('t("memory.status.sec.maintenance")'),
+    "the card must sit under the maintenance section head, not loose in the grid");
+});
+
+test("maintenance card: success state exists only behind the confirm gate", () => {
+  const src = maintCardSource();
+  // 第一次点只能「武装」，不得直连执行：默认态是红描边钮（mneme-btndanger），只有武装
+  // 后的实心红确认钮（mneme-btndangerconfirm）才允许调用 execute。
+  assert.match(src, /mneme-btndangerconfirm"[\s\S]{0,200}?onClick: execute/,
+    "only the armed danger-confirm button may fire the mutating call");
+  assert.match(src, /mneme-btndanger"[\s\S]{0,200}?onClick: \(\) => setArmed\(true\)/,
+    "the first click must only arm the confirm state, never execute");
+  assert.equal(src.split("onClick: execute").length - 1, 1,
+    "the executing click must have exactly one entry point in the card");
+  // 非 2xx 必须先 return，成功态才能写在它之后——否则失败也会渲染成成功。
+  const guard = src.indexOf("if (!r.ok) {");
+  const success = src.indexOf("setResult(r.body)");
+  assert.ok(guard >= 0 && success > guard,
+    "a non-2xx response must return before the success report is written");
+  assert.equal(src.split("setResult(r.body)").length - 1, 1,
+    "the success report must be written exactly once, from the confirmed call");
+  // 窗口改过却没重新估算时，确认态里摆出来的会是上一次的数字——对不可逆动作来说这是最坏
+  // 的一种错位，所以那种状态下执行钮必须是禁用的。
+  assert.ok(src.includes("const stale = !report || String(report.olderThanDays) !== days;"),
+    "an estimate that no longer matches the input must be detectable");
+  assert.match(src, /disabled: running \|\| loading \|\| estimating \|\| stale/,
+    "the run button must stay disabled while the estimate is stale");
+});
+
+// VACUUM 失败 ≠ 成功（契约 §5 的硬要求）。清理的两个 UPDATE 各自提交且不可逆，VACUUM
+// 只负责把文件缩回去；把半成功渲染成成功，用户会以为白清了一次。这条锁住那个三元分支，
+// 防止未来被「简化」成只看 dryRun/receipt。
+test("maintenance card: a failed VACUUM is reported, never rendered as a clean success", () => {
+  const src = maintCardSource();
+  assert.ok(src.includes("const vacuumError = rv.error == null ? null : String(rv.error);"),
+    "vacuum.error is string|null and must be read as the failure signal it is");
+  assert.match(src, /vacuumError \? t\("memory\.status\.maint\.vacuumFailed"\) : t\("memory\.status\.maint\.done"\)/,
+    "a non-null vacuum.error must replace the success headline");
+  assert.ok(src.includes('t("memory.status.maint.vacuumFailedHint")'),
+    "the failed state must state that the reclaim already happened, is irreversible, and that a rerun is idempotent");
+  // receipt 也要露面：不可逆动作没有回执号，出事时无法对账。锁的是**取值表达式**而不是
+  // 行标签——`t("...maint.receipt")` 只是左侧那行文案，把右侧渲染删空它照样在，锁标签
+  // 等于没锁（M12 变异验证过）。
+  assert.match(src, /result\.receipt == null \? t\("memory\.status\.maint\.receiptNone"\) : String\(result\.receipt\)/,
+    "the receipt value must be rendered (id when present, an explicit 'not recorded' when absent)");
+});
+
+test("maintenance card: VACUUM defaults to off and a failed run is reported verbatim", () => {
+  const src = maintCardSource();
+  // VACUUM 会短暂独占数据库（别的进程此时写入会 SQLITE_BUSY），它是**可选**动作，
+  // 默认必须关着——默认开等于每次回收都替用户独占一次库。契约 §5 的硬要求。
+  assert.ok(src.includes("const [vacuum, setVacuum] = useState(false);"),
+    "VACUUM must default to off");
+  // 非 2xx 必须把服务端给的 error 串如实带出来：只说「失败」，现场就分不清是 400 的
+  // confirm-required 还是 500 的 internal。
+  assert.ok(src.includes('setResultError(`${t("memory.status.maint.failed")} · ${(r.body && r.body.error) || `HTTP ${r.status}`}`);'),
+    "a non-2xx response must surface the server's own error string, not a bare 'failed'");
+  // 执行成功后必须复位确认态：否则下一次点击落在已武装的分支上，一步就把不可逆动作
+  // 放出去，两步确认名存实亡。
+  assert.match(src, /setResult\(r\.body\);\s*setArmed\(false\);/,
+    "the confirm state must be reset on the success path");
+});
 // 面板 bundle 在本文件里只被当**文本**读（上面的断言全是正则/字符串包含），
 // 而仓库的 CI 里没有任何一步**解析**它：于是重复声明这类语法错误能一路绿灯进
 // 主干，后果却是整个面板加载失败（__ModuleLoader__ 拿到的模块一执行就抛