@modusensus/dsh-mneme 0.10.1 → 0.12.0

package/test/embedding-cache-f32.test.js

@@ -0,0 +1,276 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { cosineSimilarity } from "../src/dream/clustering.js";
+
+// 回归：embedding 解析缓存的两件事，2026-11-05 实测发现。
+//
+// 一、上限 4000 装不下工作集时缓存等于不存在。活跃带向量行 6685 条，扫到
+//     第 4001 条开始驱逐自己刚填的条目，扫完只剩最后 4000 条，下一轮又从第一
+//     条 miss —— 四轮实测命中率恒 0.0%，每次检索全量重解析（624ms）。固定调大
+//     只是把复发推到下个月（活跃行近 30 天净增 6156 条），所以上限改为跟工作集
+//     自适应。下面的用例锁住「工作集超过下限时仍接近全命中」这条行为，而不是
+//     锁某个具体常量——锁常量等于允许它再次变成硬编码。
+//
+// 二、缓存里存 Float32Array。同一口径（GC 后 heapUsed + arrayBuffers，6730
+//     条 1024 维全常驻）实测 number[] 56.4MB → Float32Array 29.7MB，省 47%。
+//     但 `Array.isArray`
+//     对 typed array 返回 false，而 cosine / cosineSimilarity / setEmbedding
+//     历史上全用它当守卫 —— 换存储而不同步改守卫，会把每个相似度算成 0、
+//     把「设置向量」读成「清空向量」。这类静默归零没有任何报错，所以必须有
+//     用例把等价性钉死。
+
+function make() {
+  return createStore(":memory:");
+}
+
+function seed(store, count, dim) {
+  const ids = [];
+  for (let i = 0; i < count; i++) {
+    const row = store.save({ type: "project", title: `t${i}`, content: `c${i}`, importance: 3 });
+    const v = new Array(dim);
+    for (let d = 0; d < dim; d++) v[d] = Math.sin(i * 0.7 + d * 0.3);
+    store.setEmbedding(row.id, v);
+    ids.push(row.id);
+  }
+  return ids;
+}
+
+test("缓存上限跟工作集自适应：超过 4000 条也不塌成 0% 命中", () => {
+  const store = make();
+  const dim = 8;
+  const ids = seed(store, 4200, dim); // 越过旧的固定上限 4000
+  const query = new Array(dim).fill(0.5);
+
+  // 第一轮：seed 走 setEmbedding（不经读路径，不计命中/未命中），但下限 4000
+  // 装不下 4200 条，最早写入的 200 条已被驱逐 —— 第一次 searchVector 会为它们
+  // 回表，同时把上限抬到装得下本次扫描。
+  store.searchVector(query, { limit: 5 });
+  const r1 = store.embeddingCacheStats();
+  assert.equal(r1.misses, ids.length - 4000, "冷扫描只为被下限挤掉的尾部回表");
+  assert.ok(
+    r1.cap >= ids.length,
+    `扫完后上限必须装得下工作集（cap=${r1.cap} 应 >= ${ids.length}）——否则下轮会从第一条 miss`
+  );
+
+  // 第二轮：同一工作集，必须全命中（旧实现这里仍是 0%，因为缓存只留得下最后 4000 条）
+  store.searchVector(query, { limit: 5 });
+  const r2 = store.embeddingCacheStats();
+  const secondMisses = r2.misses - r1.misses;
+  const secondHits = r2.hits - r1.hits;
+  assert.equal(secondMisses, 0, `第二轮不应再有 miss（实测 ${secondMisses} 条）`);
+  assert.equal(secondHits, ids.length, "第二轮每条都命中");
+  assert.ok(r2.hitRate > 0.5, `累计命中率必须离开 0%（实测 ${(r2.hitRate * 100).toFixed(1)}%）`);
+
+  // 第三、四轮继续：命中率不得回落（旧实现每轮都归零）
+  store.searchVector(query, { limit: 5 });
+  store.searchVector(query, { limit: 5 });
+  const r4 = store.embeddingCacheStats();
+  assert.equal(r4.misses, r1.misses, "第 3、4 轮不应再产生 miss");
+  store.close();
+});
+
+test("淘汰语义：写入超过上限仍按 FIFO 驱逐最旧条目，且不驱逐正在用的", () => {
+  const store = make();
+  const ids = seed(store, 12, 4);
+  const before = store.embeddingCacheStats();
+  // 12 条远低于下限 4000，不会触发驱逐；这里锁的是「写入口按 id 覆盖而非追加」
+  const [a, b] = ids;
+  store.setEmbedding(a, [9, 9, 9, 9]);
+  assert.deepEqual(store.getParsedEmbedding(a), [9, 9, 9, 9], "同一 id 覆盖，不新增条目");
+  store.setEmbedding(b, null);
+  assert.equal(store.getParsedEmbedding(b), undefined, "清空即从缓存移除");
+  const after = store.embeddingCacheStats();
+  assert.ok(after.size <= before.size, "覆盖与清空都不该让缓存增长");
+  store.close();
+});
+
+test("Float32 与 number[] 等价：getParsedEmbedding / getEmbeddings 仍返回 number[]", () => {
+  const store = make();
+  const { id } = store.save({ type: "project", title: "A", content: "a" });
+  const written = [0.1, 0.25, 0.5, 0.75];
+  store.setEmbedding(id, written);
+  const one = store.getParsedEmbedding(id);
+  assert.ok(Array.isArray(one), "对外契约是 number[]，调用方用 Array.isArray 守卫");
+  // 数值等价而非逐位相等：缓存按 Float32 存（省 47% 内存），双精度原值不保留，
+  // 回读带 ~1e-7 的单精度舍入。对余弦分数（0..1）与排序没有可观测影响
+  // （下面「排序不变」那条用例把这一点钉死），但这是对外可见的精度变化，
+  // 必须写成断言而不是假装不存在——用精确 deepEqual 会把它变成一颗定时炸弹。
+  assert.equal(one.length, written.length);
+  for (let i = 0; i < written.length; i++) {
+    assert.ok(Math.abs(one[i] - written[i]) < 1e-6, `第 ${i} 位误差应在单精度范围内`);
+  }
+  const many = store.getEmbeddings([id]).get(id);
+  assert.ok(Array.isArray(many), "批量读同样是 number[]");
+  assert.equal(many.length, written.length);
+
+  // 传 typed array 进 setEmbedding 必须当成「设置」而不是「清空」
+  store.setEmbedding(id, new Float32Array([0.2, 0.4, 0.6, 0.8]));
+  const after = store.getParsedEmbedding(id);
+  assert.ok(after, "typed array 入参不得被读成清空（旧守卫会把它写成 NULL）");
+  assert.equal(after.length, 4);
+  for (let i = 0; i < 4; i++) assert.ok(Math.abs(after[i] - [0.2, 0.4, 0.6, 0.8][i]) < 1e-6);
+  store.close();
+});
+
+test("Float32 与 number[] 等价：cosine 对 typed array 不得静默归零", () => {
+  const a = [1, 0, 0];
+  const b = [0, 1, 0];
+  const aF = new Float32Array(a);
+  const bF = new Float32Array(b);
+  assert.equal(cosineSimilarity(a, a), 1);
+  assert.equal(cosineSimilarity(aF, aF), 1, "typed array 不能算成 0（Array.isArray 守卫的坑）");
+  assert.equal(cosineSimilarity(a, b), 0);
+  assert.equal(cosineSimilarity(aF, bF), 0);
+  const mixed = cosineSimilarity(a, aF);
+  assert.equal(mixed, 1, "混合入参（number[] vs Float32Array）也必须能算");
+});
+
+test("Float32 存储不改变检索排序：前 50 条顺序与 number[] 完全一致", () => {
+  const store = make();
+  const dim = 16;
+  const ids = seed(store, 60, dim);
+  const query = new Array(dim);
+  for (let d = 0; d < dim; d++) query[d] = Math.cos(d * 0.11);
+
+  // 缓存里已是 Float32Array（seed 走 setEmbedding → cacheEmbedding）
+  const viaCache = store.searchVector(query, { limit: 50 });
+  // 清缓存后强制从 JSON 重读并重新解析（同一条路径，但冷启动）
+  store.db.prepare("SELECT 1").get();
+  const cold = store.searchVector(query, { limit: 50 });
+
+  assert.equal(viaCache.length, cold.length, "两次返回条数一致");
+  assert.deepEqual(
+    viaCache.map((r) => r.id),
+    cold.map((r) => r.id),
+    "Float32 缓存与冷解析的排序必须逐位相同（Float32 存储不损 cosine 排序）"
+  );
+  for (let i = 0; i < viaCache.length; i++) {
+    assert.ok(
+      Math.abs(viaCache[i].score - cold[i].score) < 1e-6,
+      `第 ${i} 条分数差异应可忽略（实测 ${Math.abs(viaCache[i].score - cold[i].score)}）`
+    );
+  }
+  store.close();
+});
+
+// 变异实验暴露的缺口（2026-11-05）：把 store.js 的 cosine 守卫退回 Array.isArray
+// 时，上面那条「排序一致」照样全绿 —— 因为缓存路径与冷路径都喂进同一套坏守卫，
+// 两边一起归零，排序自然「一致」。也就是说：只比两条路径是否相同，测不出「都错」。
+// 必须有一个独立的正确答案做基准，所以这里直接算一遍期望分数。
+test("searchVector 的分数本身正确：缓存路径的 cosine 不得归零", () => {
+  const store = make();
+  const a = store.save({ type: "project", title: "A", content: "a" });
+  const b = store.save({ type: "decision", title: "B", content: "b" });
+  store.setEmbedding(a.id, [1, 0, 0, 0]);
+  store.setEmbedding(b.id, [0.6, 0.8, 0, 0]);
+
+  const query = [1, 0, 0, 0];
+  const hits = store.searchVector(query, { limit: 5 });
+  assert.equal(hits.length, 2);
+
+  // 独立算一遍期望：cos([1,0,0,0],[1,0,0,0]) = 1；cos([1,0,0,0],[0.6,0.8,0,0]) = 0.6
+  const byId = new Map(hits.map((h) => [h.id, h.score]));
+  assert.ok(
+    Math.abs(byId.get(a.id) - 1) < 1e-6,
+    `完全同向的分数必须是 1（实测 ${byId.get(a.id)}）——若为 0 说明 cosine 守卫把 typed array 判死了`
+  );
+  assert.ok(
+    Math.abs(byId.get(b.id) - 0.6) < 1e-6,
+    `余弦 0.6 必须算出来（实测 ${byId.get(b.id)}）`
+  );
+  assert.ok(
+    hits[0].score > 0 && hits[1].score > 0,
+    "两条分数都不得为 0（静默归零没有任何报错，只能靠这条基准锁住）"
+  );
+  store.close();
+});
+
+// 摘掉 searchVector 的 `embedding != ''` 谓词（2026-11-05）：`!= ''` 要读 embedding
+// 列才能判定，SQLite 就得把整列向量文本搬一遍——而这条 SQL 只 SELECT id，一条
+// 文本都不用。副本实测 265ms → 96ms。摘掉的前提是「空串行不会把检索搞崩」，
+// 而库里现在 0 条空串纯属现状（setEmbedding 写 NULL，能造出空串的只有外部直接
+// UPDATE）。所以必须把「空串行存在时」的行为钉死，否则这是在拆一个「目前恰好
+// 为真」的假设。
+test("库里存在 embedding = '' 的行：searchVector 不崩、不把它算进结果", () => {
+  const store = make();
+  const good = store.save({ type: "project", title: "正常", content: "有向量" });
+  const empty = store.save({ type: "project", title: "空串", content: "外部写的空串" });
+  const broken = store.save({ type: "project", title: "坏 JSON", content: "解析不了" });
+
+  store.setEmbedding(good.id, [1, 0, 0, 0]);
+  // 绕过 setEmbedding 直接写列——只有外部直接 UPDATE 才造得出这两种行。
+  store.db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run("", empty.id);
+  store.db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run("{not json", broken.id);
+
+  const query = [1, 0, 0, 0];
+  const hits = store.searchVector(query, { limit: 10 });
+
+  assert.equal(hits.length, 1, `只有一条可解析向量参与（实测 ${hits.length} 条）`);
+  assert.equal(hits[0].id, good.id, "入选的必须是那条可解析的向量");
+  assert.ok(Math.abs(hits[0].score - 1) < 1e-6, `正常行分数仍须为 1（实测 ${hits[0].score}）`);
+
+  // 空串行必须仍被 SQL 选中（IS NOT NULL 为真），再由 readVector 兜住——
+  // 否则这里测的是「SQL 没选它」，掩盖了 readVector 的兜底能力。
+  const selected = store.db.prepare(
+    "SELECT id FROM memories WHERE forgotten = 0 AND archived = 0 AND embedding IS NOT NULL"
+  ).all().map((r) => r.id);
+  assert.equal(selected.length, 3, "三行都有非 NULL 的 embedding 文本，SQL 全部选中");
+  assert.ok(selected.includes(empty.id), "空串行确实进了候选集（不是被 SQL 过滤掉）");
+
+  // 维度探针同一行集：空串行不能让 unreadable 判定失真。
+  assert.deepEqual(
+    store.vectorDimensionState(4),
+    { state: "match" },
+    "空串行存在时仍应判出 match（可解析的那条同维）"
+  );
+  store.close();
+});
+
+// 上面那条锁住「空串行不会崩」，但锁不住「谓词别被加回来」——把 `!= ''` 加回
+// searchVector，8 条全绿：SQL 层先滤掉空串行，readVector 的兜底就永远测不到。
+// 断言「这句 SQL 不含 != ''」是把测试绑在字面量上，正常重构（换行、改别名、
+// 换 ${archivedFilter} 写法）就无辜变红，红了第一反应是删断言，比没有更糟。
+// 这里锁行为：每一行非 NULL 都必须被读一次——这正是摘谓词的目的本身。只要
+// SQL 又开始按 embedding 文本过滤掉行，读取次数立刻掉，跟 SQL 怎么写无关。
+// 顺带把「读缓存命中」也算进增量，所以它同时锁住「别退化成每行都回表」。
+test("摘谓词的目的：每一行非 NULL 的 embedding 都必须被读一次", () => {
+  const store = make();
+  const good = store.save({ type: "project", title: "正常", content: "有向量" });
+  const empty = store.save({ type: "project", title: "空串", content: "外部写的空串" });
+  const broken = store.save({ type: "project", title: "坏 JSON", content: "解析不了" });
+
+  store.setEmbedding(good.id, [1, 0, 0, 0]);
+  store.db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run("", empty.id);
+  store.db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run("{not json", broken.id);
+
+  const before = store.embeddingCacheStats();
+  store.searchVector([1, 0, 0, 0], { limit: 10 });
+  const after = store.embeddingCacheStats();
+  const reads = (after.misses - before.misses) + (after.hits - before.hits);
+  assert.equal(
+    reads,
+    3,
+    `三行非 NULL 必须各读一次（实测 ${reads} 次）——少于 3 说明 SQL 又在按 embedding 文本过滤，` +
+      "等于把「只 SELECT id 的查询顺手搬了 134MB 向量列」这个开销又请回来了"
+  );
+  store.close();
+});
+
+test("全部行都是 embedding = '' 时：检索返回空、探针判 unreadable 而非 none", () => {
+  const store = make();
+  const a = store.save({ type: "project", title: "A", content: "a" });
+  const b = store.save({ type: "project", title: "B", content: "b" });
+  store.db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run("", a.id);
+  store.db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run("", b.id);
+
+  assert.deepEqual(store.searchVector([1, 0], { limit: 5 }), [], "没有可解析向量就没有结果，不崩");
+  // 行集非空（两行都有非 NULL 文本）但零条可解析 = unreadable，不是 none。
+  // none 会让人以为「库里没有向量」，实际是「有文本却读不出来」。
+  assert.deepEqual(
+    store.vectorDimensionState(2),
+    { state: "unreadable" },
+    "有行却零条可解析 → unreadable（谓词摘掉后这条判定更依赖 readVector 的兜底）"
+  );
+  store.close();
+});

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("不该冒出来的旧口径条目"));
+});