@modusensus/dsh-mneme 0.11.0 → 0.13.0

package/test/forget-corrections.test.js

@@ -0,0 +1,70 @@
+// #532 选择性遗忘 × 事实更正的结构性回归锁。
+//
+// 现象（议题主楼）：更正两个事实 → 只忘一个 → 保留的那个答回更正前的旧值。
+// 根因是三段契约的接缝（docs/FORGET.md §1）：更正由蒸馏落成新行（三元组去重不
+// 命中、dream 冲突裁决阈值门控未运行）→ 旧行与新行之间没有持久失效关系 →
+// memory_forget 按行抑制，合流在同一行里的其他事实连带退出可见面，旧值行成了
+// 唯一幸存载体。
+//
+// 本文件锁两件事：
+//   ① 存储层合成轨迹（零 LLM）：两行并存、遗忘新行、旧行原样幸存——这是现象的
+//     存储层等价物。**机制修复落地时 ⑤ 的断言应当翻转**：更正行写入后旧行要么
+//     被记上失效关系、要么退出活跃面；注释里写明翻转条件，防止它被当成「永远
+//     该绿」的现状锁读。
+//   ② memory_forget 的工具描述必须带行粒度警示：模型无从得知「请求的语义粒度
+//     （一个事实）」与「工具的能力粒度（一行）」之间的落差，除非描述告诉它。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createTools } from "../src/tools.js";
+
+test("#532 合成轨迹：更正落新行、遗忘新行、旧行原样幸存（机制修复落地时 ⑤ 翻转）", () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  try {
+    // ① 原始陈述（对话 A 的蒸馏产物：颜色 + 时间合流一行）
+    const r1 = service.saveWithDedupe({
+      type: "preference", title: "纸模工具的收纳与整理",
+      content: "纸模工具放在雾蓝色收纳盒，每周三晚上八点整理一次", importance: 3
+    });
+    // ② 更正（对话 B：蒸馏器另起标题 → (type,title,scope) 三元组不命中 → 新行）
+    const r2 = service.saveWithDedupe({
+      type: "preference", title: "收纳盒颜色与整理时间的更正",
+      content: "收纳盒换成浅橙色，整理时间改为每周六上午九点", importance: 3
+    });
+    assert.notEqual(r1.memory.id, r2.memory.id, "标题不同 → 去重不命中，更正落成新行");
+    // ③ 结构断言：两行同时活跃，二者之间没有任何失效链接（本车道基线未含 #275
+    //   的 capacityStats，直接查列）
+    const activeCount = () => store.db.prepare("SELECT COUNT(*) AS n FROM memories WHERE forgotten = 0 AND archived = 0").get().n;
+    assert.equal(activeCount(), 2, "更正不淘汰旧行（dream 未运行的阈值下无失效关系）");
+    // ④ 「忘掉颜色」＝按行遗忘新值行（模型在可见行里看到的颜色载体）
+    service.setForget(r2.memory.id, true);
+    // ⑤ 现象复现：新值行退出可见面后，旧值行仍是唯一幸存载体——这正是 #532
+    //    「保留的更正事实答回旧值」的存储层等价物。机制修复（写侧更正失效关系 /
+    //    dream 触发前移，见 docs/FORGET.md §3）落地时翻转：旧行应被记上失效关系
+    //    或退出活跃面，断言改为不存在「幸存的旧值行」。
+    assert.equal(store.getById(r1.memory.id).forgotten, false, "旧行从未被任何机制波及（toRow 把列归一成 boolean）");
+    assert.match(store.getById(r1.memory.id).content, /每周三晚上八点/, "旧值仍在召回面");
+    // 被抑制的行可恢复（接口契约：行粒度遗忘不是删除）——恢复后两行回到并存
+    // 状态：失效关系的缺位不因遗忘/恢复而改变。
+    service.setForget(r2.memory.id, false);
+    assert.equal(activeCount(), 2);
+  } finally {
+    store.close();
+  }
+});
+
+test("memory_forget 的工具描述必须带行粒度警示（#532 对话 5 的模型误用直接对策）", () => {
+  const registered = [];
+  const ctx = { tools: { register(def) { registered.push(def); return () => {}; } } };
+  createTools(ctx, { getById: () => undefined }, {}, undefined);
+  const forget = registered.find((d) => d.name === "memory_forget");
+  assert.ok(forget, "memory_forget 必须注册");
+  // 锁「语义」不锁逐字：描述必须让模型知道抑制按行、合流事实连带退出、
+  // 请求只针对一个事实时先看行内容或拆分。防的回归是有人把描述改回
+  // 「只说单条抑制」，模型在「忘掉 X」请求下重新对合流行整条下手。
+  const desc = String(forget.description || "");
+  assert.match(desc, /per ROW/i, "描述必须写明抑制粒度是行");
+  assert.match(desc, /memory_update|inspect|say in your reply/i, "描述必须给出合流行下的替代动作");
+});

package/test/image-memory.test.js

@@ -0,0 +1,171 @@
+// Issue #611：图片记忆端到端——一张图真的走进蒸馏转录。
+//
+// 单元用例（attachment-text.test.js）只证明「块 → 文本」这一步是对的。这一份锁的是
+// 另一半：**collectMessages 真的会把它拼进发给模型的那条消息里**，并且这个数会落进
+// 审计 metadata。改动前三处 textOf 都返回空串，图-only 消息连一行都不会产出——所以
+// 这条用例在旧代码上必然红，这是它存在的理由。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createSummarizer } from "../src/summarize.js";
+
+function setup(over = {}) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const events = [];
+  const calls = [];
+  const ctx = {
+    on(name, fn) {
+      events.push({ name, fn });
+      return () => {};
+    },
+    llm: {
+      stream(options) {
+        calls.push(options);
+        const json = JSON.stringify([
+          { type: "history", title: "看过一张截图", content: "用户发了一张 1543x983 的截图并问数据对比", importance: 3 }
+        ]);
+        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" };
+        })();
+      }
+    }
+  };
+  const config = { autoSummarize: true, distillRateLimitIntervalMs: 0, ...over };
+  const summarizer = createSummarizer(ctx, service, config, {});
+  return { store, service, events, calls, summarizer };
+}
+
+function imageMessage(seq, text) {
+  const content = [];
+  if (text) content.push({ type: "text", text });
+  content.push({
+    type: "image",
+    attachment: {
+      attachmentId: "sha256:abc123",
+      mediaType: "image/png",
+      width: 1543,
+      height: 983,
+      name: "屏幕截图 2026-10-19 072000.png"
+    }
+  });
+  return { seq, type: "user/message", data: { source: { kind: "user" }, content } };
+}
+
+
+test("#611 图+文消息：蒸馏转录里同时有文字与图片占位", async () => {
+  const { events, calls } = setup();
+  const handler = events.find((e) => e.name === "session/event").fn;
+  const session = {
+    id: "s611-mixed",
+    requestHeader: () => ({ config: { provider: "deepseek", model: "deepseek-chat" } }),
+    events: [
+      imageMessage(1, "能有那种数据对比吗"),
+      { seq: 2, type: "turn/end" }
+    ]
+  };
+  await handler(session, { seq: 2, type: "turn/end" });
+
+  assert.equal(calls.length, 1, "这一窗应当发起一次蒸馏");
+  const transcript = calls[0].messages.find((m) => m.role === "user").content[0].text;
+  assert.ok(transcript.includes("能有那种数据对比吗"), "文字照旧进转录");
+  assert.ok(transcript.includes("[图:"), "图片必须留下占位，而不是消失");
+  assert.ok(transcript.includes("屏幕截图 2026-10-19 072000.png"), "文件名要能对上原始附件");
+  assert.ok(transcript.includes("1543x983"), "尺寸要留下");
+});
+
+test("#611 图-only 消息不再被整条丢弃（改动前窗口里一行都没有）", async () => {
+  const { events, calls } = setup();
+  const handler = events.find((e) => e.name === "session/event").fn;
+  const session = {
+    id: "s611-image-only",
+    requestHeader: () => ({ config: { provider: "deepseek", model: "deepseek-chat" } }),
+    events: [imageMessage(1, null), { seq: 2, type: "turn/end" }]
+  };
+  await handler(session, { seq: 2, type: "turn/end" });
+
+  assert.equal(calls.length, 1, "图-only 窗口现在也要蒸馏——旧版这里直接 noop");
+  const transcript = calls[0].messages.find((m) => m.role === "user").content[0].text;
+  assert.ok(transcript.includes("[图:"), "占位就是这一窗的全部可提炼内容");
+});
+
+test("#611 图片张数落进审计 metadata，off 档与静默丢弃可区分", async () => {
+  const { events, service } = setup();
+  const handler = events.find((e) => e.name === "session/event").fn;
+  const session = {
+    id: "s611-audit",
+    requestHeader: () => ({ config: { provider: "deepseek", model: "deepseek-chat" } }),
+    events: [
+      imageMessage(1, "第一张"),
+      imageMessage(2, "第二张"),
+      { seq: 3, type: "turn/end" }
+    ]
+  };
+  await handler(session, { seq: 3, type: "turn/end" });
+
+  const row = service.listLlmAudits().find((r) => r.status === "success");
+  assert.ok(row, "成功行要存在");
+  assert.equal(row.metadata?.imageCount, 2, "两张图必须被数出来");
+});
+
+test("#611 没有图时不写 imageCount（零行为变化）", async () => {
+  const { events, service } = setup();
+  const handler = events.find((e) => e.name === "session/event").fn;
+  const session = {
+    id: "s611-no-image",
+    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" }
+    ]
+  };
+  await handler(session, { seq: 2, type: "turn/end" });
+
+  const row = service.listLlmAudits().find((r) => r.status === "success");
+  assert.ok(row);
+  assert.equal(row.metadata?.imageCount, undefined, "没图就别写这个键，老档位逐字节不变");
+});
+test("#611 被挡掉的注入消息里的图不计入（CodeRabbit 2026-11-08 指出）", async () => {
+  // 计量的口径必须是「真正进了转录的图」，不是「窗口事件里出现过几张图」。
+  // 这条用例造一条带图的插件注入消息：它会被 publicTranscriptParts 整条挡掉
+  // （转录里没有它），所以 imageCount 不该把它算进去——否则审计会报「这窗有 1 张图」
+  // 而模型根本没看到这张图。
+  const { events, service, calls } = setup();
+  const handler = events.find((e) => e.name === "session/event").fn;
+  const injected = {
+    seq: 1,
+    type: "user/message",
+    data: {
+      source: { kind: "plugin:dsh-mneme", plugin: "dsh-mneme" },
+      content: [
+        { type: "text", text: "插件注入的机器内容" },
+        {
+          type: "image",
+          attachment: { attachmentId: "sha256:zzz", mediaType: "image/png", width: 10, height: 10, name: "不该被数.png" }
+        }
+      ]
+    }
+  };
+  const session = {
+    id: "s611-injected",
+    requestHeader: () => ({ config: { provider: "deepseek", model: "deepseek-chat" } }),
+    events: [
+      injected,
+      { seq: 2, type: "user/message", data: { source: { kind: "user" }, content: [{ type: "text", text: "真人的一句" }] } },
+      { seq: 3, type: "turn/end" }
+    ]
+  };
+  await handler(session, { seq: 3, type: "turn/end" });
+
+  assert.equal(calls.length, 1, "窗口里有真人文本，照常蒸馏");
+  const transcript = calls[0].messages.find((m) => m.role === "user").content[0].text;
+  assert.ok(transcript.includes("真人的一句"));
+  assert.ok(!transcript.includes("插件注入的机器内容"), "注入消息本来就不进转录");
+  const row = service.listLlmAudits().find((r) => r.status === "success");
+  assert.ok(row);
+  assert.equal(row.metadata?.imageCount, undefined, "被挡掉的注入消息里的图不该被数进去");
+});

package/test/inject-pin-explicit.test.js

@@ -0,0 +1,300 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+
+// #249 第二批（显式 pin）验收。判据从「类型是 constraint/preference」换成
+// 「用户亲手钉在 pinned_memories 里」。
+//
+// 为什么需要这一层：旧的类型口径把 1163 条 constraint/preference 全当成 pin，
+// 而 pin 预算最多 5 条，于是池子永远比预算大两个数量级——真正该每轮必进的
+// 「提交署名硬约束」「拒绝谄媚」在 200 行规则窗口里排 133 / 157 名，就算封顶
+// 和补位都修好也轮不到。根因是「type 就算 pin」这个隐含假设本身。
+//
+// 本文件按 Amarre 的验收清单逐条锁：
+//   ① 表空 → 回落旧类型口径（升级即等价，她钉第一条才切换）
+//   ② pin 一条**不在 200 行窗口内**的记忆仍能注入（补丁存在的理由本身）
+//   ③ pin 一条 **pattern** 类型能注入（写得最全的那版往往是 pattern）
+//   ④ pin 的行越权（strictScope 不通过）→ 不进块
+//   ⑤ pin 的行属暂停作用域 → 不进块
+//   ⑥ pinnedInjectBudget === 0 → shown=0 且注入序列与改前完全一致
+//   ⑦ 被 pin 的行 forgotten/archived → 不进块
+//
+// ②③ 的种子必须造 >200 条同 importance 的行，否则种子库窗口装得下、
+// 用例假绿——「窗口外」这件事根本没被造出来。
+
+function setup(config = {}) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config });
+  return { store, service };
+}
+
+const titlesOf = (list) => list.map((m) => m.title);
+
+// 造 n 条 importance=5 的普通条目。updated_at 递增，于是「最先造的」在
+// store.list 的 (importance DESC, updated_at DESC, id) 序里排在最后，
+// 200 行窗口装不下它——这就是「窗口外」的造法。
+function seedCrowd(service, n, prefix = "普通条目") {
+  const ids = [];
+  for (let i = 0; i < n; i++) {
+    const m = service.saveWithDedupe({
+      type: "decision",
+      title: `${prefix}${i}`,
+      content: `第 ${i} 条与 pin 无关的普通决定，用来把窗口撑满`,
+      importance: 5
+    }).memory;
+    ids.push(m.id);
+  }
+  return ids;
+}
+
+function saveOne(service, { type = "preference", title, content, importance = 5, extra = {} }) {
+  return service.saveWithDedupe({ type, title, content, importance, ...extra }).memory;
+}
+
+test("表空时回落旧类型口径：pattern 不会被当成 pin", () => {
+  // 升级后 pinned_memories 是空表。若此时直接改读表，她现有的「按类型挑 5 条」
+  // 会静默降到 0 条——所以空表必须回落旧口径，升级即等价。
+  const { store, service } = setup({ maxInjectedItems: 5, pinnedInjectBudget: 5, importanceThreshold: 3 });
+  seedCrowd(service, 10);
+  saveOne(service, { type: "preference", title: "旧口径偏好", content: "类型即 pin 的旧口径下它该进块" });
+  // pattern 是旧口径的反证：它写得最全，但不在 PINNED_MEMORY_TYPES 里，
+  // 表空时不得被当成 pin。
+  saveOne(service, { type: "pattern", title: "旧口径模式", content: "pattern 不在旧口径的 pin 类型里" });
+
+  assert.equal(store.countPinned(), 0, "前提：pin 表是空的");
+
+  const pinnedStats = {};
+  const selected = service.injectCandidates({ query: "与 pin 无关的问题", maxItems: 5, pinnedStats });
+
+  assert.equal(pinnedStats.source, "type-fallback", "空表必须标成 type-fallback");
+  assert.equal(pinnedStats.outsideWindow, 0, "回落口径只能从窗口里取，不该有窗口外补位");
+  assert.equal(pinnedStats.shown, 1, "旧口径下只有那一条 preference 算 pin");
+  assert.ok(titlesOf(selected).slice(0, 1).includes("旧口径偏好"), "旧口径的 pin 仍要前置");
+  assert.ok(!titlesOf(selected).includes("旧口径模式"), "表空时 pattern 不得被当成 pin");
+});
+
+test("pin 一条不在 200 行窗口内的记忆仍能注入", () => {
+  // 这是整个第二层存在的理由：i=5 的 1143 条里 943 条（83%）进不了 200 行窗口，
+  // 靠相关性排序永远轮不到「署名」「拒绝谄媚」这类稳定偏好。
+  const { store, service } = setup({ maxInjectedItems: 5, pinnedInjectBudget: 5, importanceThreshold: 3 });
+  // 必须先造 200+ 条同 importance 的行，否则窗口装得下、这条用例假绿。
+  const crowd = seedCrowd(service, 220);
+  // crowd[0] 最早造 → updated_at 最小 → 排在 220 条的最后 → 在 200 行窗口外。
+  const target = crowd[0];
+
+  // 先证明它真的在窗口外：不改 pin 时它进不了候选池。
+  const before = service.injectCandidates({ query: "与 pin 无关的问题", maxItems: 5, pinnedStats: {} });
+  assert.ok(
+    !before.some((m) => m.id === target),
+    "前提：未 pin 时这条在 200 行窗口外，进不了注入块"
+  );
+
+  store.pinMemory(target);
+  assert.equal(store.countPinned(), 1);
+
+  const pinnedStats = {};
+  const after = service.injectCandidates({ query: "与 pin 无关的问题", maxItems: 5, pinnedStats });
+
+  assert.equal(pinnedStats.source, "explicit", "表非空 → explicit 口径");
+  assert.equal(pinnedStats.outsideWindow, 1, "这条是点查补回来的，必须计入 outsideWindow");
+  assert.equal(pinnedStats.shown, 1, "窗口外的 pin 也要占一个 pin 槽");
+  assert.ok(after.some((m) => m.id === target), "pin 一条窗口外的记忆，它必须真的进块");
+  assert.ok(titlesOf(after).slice(0, 1).includes("普通条目0"), `pin 前置到块首：${titlesOf(after).join(" / ")}`);
+});
+
+test("pin 一条 pattern 类型能注入", () => {
+  // 语义去重扫出 10 组，内容最全的那版 8 组是 pattern（「带学铁律」449 字含
+  // 「一次一个概念块」，限类型就只能拿 141 字的 constraint 残缺版）。
+  // 所以 explicit 口径的 filter 里不能出现 PINNED_MEMORY_TYPES。
+  const { store, service } = setup({ maxInjectedItems: 5, pinnedInjectBudget: 5, importanceThreshold: 3 });
+  seedCrowd(service, 10);
+  const m = saveOne(service, { type: "pattern", title: "带学铁律全版", content: "一次只讲一个概念块，讲完停下等她回应" });
+  store.pinMemory(m.id);
+
+  const pinnedStats = {};
+  const selected = service.injectCandidates({ query: "与 pin 无关的问题", maxItems: 5, pinnedStats });
+
+  assert.equal(pinnedStats.source, "explicit");
+  assert.equal(pinnedStats.shown, 1, "pattern 被显式钉住就该进 pin 池");
+  assert.ok(titlesOf(selected).includes("带学铁律全版"), `pattern 类型的 pin 必须进块：${titlesOf(selected).join(" / ")}`);
+});
+
+test("pin 的行越权时不得进块（strictScope）", () => {
+  // pin 不是绕过闸门的通道：补位与点查都发生在 strictScope 之前，硬墙照旧生效。
+  const { store, service } = setup({
+    maxInjectedItems: 5,
+    pinnedInjectBudget: 5,
+    importanceThreshold: 3,
+    strictScope: true
+  });
+  seedCrowd(service, 10);
+  const m = saveOne(service, {
+    title: "越权偏好",
+    content: "只属于 proj-a 的偏好，不该泄进 proj-b 的注入块",
+    extra: { workspace_scope: "proj-a", workspace_scope_source: "explicit" }
+  });
+  store.pinMemory(m.id);
+
+  const pinnedStats = {};
+  const selected = service.injectCandidates({
+    query: "与 pin 无关的问题",
+    maxItems: 5,
+    scope: { agent_scope: null, workspace_scope: "proj-b" },
+    pinnedStats
+  });
+
+  assert.equal(pinnedStats.source, "explicit", "前提：确实走了 explicit 口径");
+  assert.equal(pinnedStats.shown, 0, "被 strictScope 挡下的行不能算成已 pin");
+  assert.ok(!titlesOf(selected).includes("越权偏好"), `越权 pin 不得进块：${titlesOf(selected).join(" / ")}`);
+});
+
+test("pin 的行属暂停作用域时不得进块（scopeState）", () => {
+  const { store, service } = setup({
+    maxInjectedItems: 5,
+    pinnedInjectBudget: 5,
+    importanceThreshold: 3,
+    scopeState: { enabled: true, enforce: true }
+  });
+  seedCrowd(service, 10);
+  const m = saveOne(service, {
+    title: "暂停域偏好",
+    content: "属于 proj-a 的偏好，而 proj-a 此刻被按下",
+    extra: { workspace_scope: "proj-a", workspace_scope_source: "explicit" }
+  });
+  store.pinMemory(m.id);
+  service.setScopeState({ dimension: "workspace", scope_value: "proj-a", state: "paused" });
+
+  const pinnedStats = {};
+  const selected = service.injectCandidates({ query: "与 pin 无关的问题", maxItems: 5, pinnedStats });
+
+  assert.equal(pinnedStats.source, "explicit");
+  assert.equal(pinnedStats.shown, 0, "被暂停闸拦下的行不能算成已 pin");
+  assert.ok(!titlesOf(selected).includes("暂停域偏好"), `暂停作用域的 pin 不得进块：${titlesOf(selected).join(" / ")}`);
+});
+
+test("pinnedInjectBudget=0 时表里有 pin 也不得改变注入序列", () => {
+  // 关闭态必须与改动前逐字节一致：预算 0 时整段不执行——不读表、不改 candidates。
+  const { store, service } = setup({ maxInjectedItems: 5, pinnedInjectBudget: 0, importanceThreshold: 3 });
+  seedCrowd(service, 10);
+  const m = saveOne(service, { title: "被钉但预算关闭", content: "预算 0 时它不该被前置" });
+  store.pinMemory(m.id);
+  assert.equal(store.countPinned(), 1, "前提：表里确实有 pin 行");
+
+  const pinnedStats = {};
+  const selected = service.injectCandidates({ query: "与 pin 无关的问题", maxItems: 5, pinnedStats });
+
+  assert.equal(pinnedStats.shown, 0, "预算 0 → pin 池关闭");
+  assert.equal(pinnedStats.source, undefined, "关闭态不该标口径");
+  assert.equal(pinnedStats.outsideWindow, 0);
+  assert.equal(selected.length, 5, "槽位数不变");
+  assert.ok(!titlesOf(selected).includes("被钉但预算关闭"), "关闭态下 pin 不得被前置");
+});
+
+test("被 pin 的行 forgotten/archived 后不得进块", () => {
+  // pin 不是复活通道：点查取回的行照样要过遗忘/归档判定。
+  const { store, service } = setup({ maxInjectedItems: 5, pinnedInjectBudget: 5, importanceThreshold: 3 });
+  seedCrowd(service, 10);
+  const forgotten = saveOne(service, { title: "钉过又遗忘", content: "钉住之后被遗忘，不该再进块" });
+  const archived = saveOne(service, { title: "钉过又归档", content: "钉住之后被归档，不该再进块" });
+  store.pinMemory(forgotten.id);
+  store.pinMemory(archived.id);
+  service.setForget(forgotten.id, true);
+  service.setArchived(archived.id, true);
+
+  const pinnedStats = {};
+  const selected = service.injectCandidates({ query: "与 pin 无关的问题", maxItems: 5, pinnedStats });
+
+  assert.equal(pinnedStats.shown, 0, "遗忘/归档的 pin 不得占槽");
+  assert.ok(!titlesOf(selected).includes("钉过又遗忘"), "遗忘的 pin 不得进块");
+  assert.ok(!titlesOf(selected).includes("钉过又归档"), "归档的 pin 不得进块");
+});
+
+// --- 判据：看「能用的」而不是「表里有几行」 ---------------------------------
+//
+// 下面三条是同一个 bug 的三个面：pin 行会在 memories 那边被归档 / 遗忘 / 硬删，
+// 而 pinned_memories 对这三种一无所知。若判据写成 countPinned() > 0，只要表里
+// 还剩一行（哪怕那一行早已归档），pinMode 就永远钉在 explicit、eligible 恒空
+// → pin 全灭且**永不回落**，无日志无报错。这正是这批改动要治的静默失败。
+
+function pinTargets(service, titles) {
+  return titles.map((title) => saveOne(service, { title, content: `${title} 的正文` }));
+}
+
+test("钉过的行被归档后：回落旧口径，而不是 pin 全灭", () => {
+  const { store, service } = setup({ maxInjectedItems: 5, pinnedInjectBudget: 5, importanceThreshold: 3 });
+  seedCrowd(service, 10);
+  const legacy = saveOne(service, { type: "preference", title: "旧口径仍该进", content: "类型口径下它每轮前置" });
+  const [pinned] = pinTargets(service, ["钉过又归档"]);
+  store.pinMemory(pinned.id);
+  service.setArchived(pinned.id, true);
+
+  const pinnedStats = {};
+  const selected = service.injectCandidates({ query: "与 pin 无关的问题", maxItems: 5, pinnedStats });
+
+  assert.equal(store.countPinned(), 1, "前提：表里还留着那一行（归档不会删 pin 行）");
+  assert.equal(pinnedStats.source, "fallback-none-usable", "钉过但一条都用不了 → 必须留痕，不能静默");
+  assert.ok(titlesOf(selected).includes("旧口径仍该进"), `archived 掉唯一 pin 后应回落类型口径：${titlesOf(selected).join(" / ")}`);
+  assert.ok(!titlesOf(selected).includes("钉过又归档"), "归档的 pin 不得复活");
+  assert.ok(legacy.id);
+});
+
+test("钉过的行被遗忘后：同样回落，而不是卡死", () => {
+  const { store, service } = setup({ maxInjectedItems: 5, pinnedInjectBudget: 5, importanceThreshold: 3 });
+  seedCrowd(service, 10);
+  saveOne(service, { type: "preference", title: "旧口径仍该进", content: "类型口径下它每轮前置" });
+  const [pinned] = pinTargets(service, ["钉过又遗忘"]);
+  store.pinMemory(pinned.id);
+  service.setForget(pinned.id, true);
+
+  const pinnedStats = {};
+  const selected = service.injectCandidates({ query: "与 pin 无关的问题", maxItems: 5, pinnedStats });
+
+  assert.equal(pinnedStats.source, "fallback-none-usable");
+  assert.ok(titlesOf(selected).includes("旧口径仍该进"), `forgotten 掉唯一 pin 后应回落类型口径：${titlesOf(selected).join(" / ")}`);
+  assert.ok(!titlesOf(selected).includes("钉过又遗忘"), "遗忘的 pin 不得复活");
+});
+
+test("钉过的行被硬删后：没有可用行就回落，孤儿行还会被清掉", () => {
+  const { store, service } = setup({ maxInjectedItems: 5, pinnedInjectBudget: 5, importanceThreshold: 3 });
+  seedCrowd(service, 10);
+  saveOne(service, { type: "preference", title: "旧口径仍该进", content: "类型口径下它每轮前置" });
+  const [pinned] = pinTargets(service, ["钉过又被删"]);
+  store.pinMemory(pinned.id);
+  service.remove(pinned.id);
+
+  // remove() 走的清理路径要顺带清掉 pin 行（防攒垃圾）；但即使没清，回落也必须
+  // 成立——判据看的是「能不能用」，不是「表里有没有」。
+  assert.equal(store.countPinned(), 0, "硬删记忆时要顺带清掉它的 pin 行，否则孤儿会越攒越多");
+
+  const pinnedStats = {};
+  const selected = service.injectCandidates({ query: "与 pin 无关的问题", maxItems: 5, pinnedStats });
+
+  assert.equal(pinnedStats.source, "type-fallback", "表被清空后就是「从没钉过」，走旧口径");
+  assert.ok(titlesOf(selected).includes("旧口径仍该进"), `全部 pin 失效后应回落类型口径：${titlesOf(selected).join(" / ")}`);
+});
+
+test("钉了多条、只有一部分还能用：留 explicit，只注入能用的那几条", () => {
+  // 关键取舍：不能因为「有 2 条归档」就整段回落到类型口径——那会突然冒出一批
+  // 她根本没钉过的条目，比少注入更糟。只要还有一条能用，口径就是 explicit。
+  const { store, service } = setup({ maxInjectedItems: 5, pinnedInjectBudget: 5, importanceThreshold: 3 });
+  seedCrowd(service, 10);
+  saveOne(service, { type: "preference", title: "不该冒出来的旧口径条目", content: "explicit 下它不该被当 pin" });
+  const [live, gone] = pinTargets(service, ["还活着的那条 pin", "已经归档的那条 pin"]);
+  store.pinMemory(live.id);
+  store.pinMemory(gone.id);
+  service.setArchived(gone.id, true);
+
+  const pinnedStats = {};
+  const selected = service.injectCandidates({ query: "与 pin 无关的问题", maxItems: 5, pinnedStats });
+
+  assert.equal(pinnedStats.source, "explicit", "还有一条能用 → 保持 explicit");
+  assert.equal(pinnedStats.shown, 1, "只注入能用的那一条");
+  assert.ok(titlesOf(selected).includes("还活着的那条 pin"), "能用的 pin 必须进块");
+  assert.ok(!titlesOf(selected).includes("已经归档的那条 pin"), "归档的 pin 不得进块");
+  assert.ok(
+    !titlesOf(selected).includes("不该冒出来的旧口径条目"),
+    "explicit 下不得回落类型口径——否则会冒出她没钉过的条目"
+  );
+  assert.ok(!titlesOf(selected).slice(0, 1).includes("不该冒出来的旧口径条目"));
+});