@modusensus/dsh-mneme 0.11.0 → 0.12.0

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

package/test/inject-pin-vector-crowd.test.js

@@ -0,0 +1,225 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createVectorIndex } from "../src/vector-index.js";
+
+// 回归（pin 池被向量路封顶饿死）：`injectCandidates` 里 hybrid 分支先把
+// `vectorIndex.search(qv, {limit: poolSize})` 的结果全量 push 进 merged，随后
+// `if (merged.length >= poolSize) break;` 在**pin 筛选之前**就封顶——生产
+// maxItems=5 → poolSize=10，向量路一次正好返回 10 条即 break，规则窗口里那些
+// constraint/preference 一条都进不了 candidates，pin 池只能从这 10 条里筛，
+// 命中几条纯看它们碰巧是什么类型。
+//
+// 代码注释向来自称「pin 不占 maxItems 名额」，实现里却把名额占掉了。实测真库
+// maxItems=5 时 pin shown 只有 2/5，补回后恒 5/5；maxItems=10（poolSize=20）
+// 时前后都是 5/5——所以修法不是多给名额，是把被向量路吃掉的 pin 候选补回来。
+//
+// 修法位置：不在 hybrid 分支之前提前摘（那样会绕过下面 strictScope 与
+// scopeState 两道闸门，而 :1907 的注释明确写着「pin 池 eligible 取自过滤之后的
+// 候选，顺带保证越权行进不了 pin」），而是在合并之后、闸门之前把被甩掉的 pin
+// 类行补回候选池尾部——闸门照旧作用其上。
+//
+// 本文件锁三件事：
+//   ① 向量路把 poolSize 填满时，pin 池照旧拿满预算（缺口本体）
+//   ② 补回的是规则窗口（items）里的 pin，与向量命中集无关——即使查询向量与
+//      pin 条目毫不相干，它们也能进块（这是 pin 的定义：每轮必进）
+//   ③ 预算关时行为逐字节不变
+
+function setup(config = {}) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config });
+  const vectorIndex = createVectorIndex({ store });
+  service.setVectorIndex(vectorIndex);
+  return { store, service, vectorIndex };
+}
+
+// 向量路上与查询完全同向的普通条目：正好填满 poolSize 个名额，且一条都不是 pin 类型。
+function seedVectorCrowd(service, vectorIndex, n) {
+  const ids = [];
+  for (let i = 0; i < n; i++) {
+    const m = service.saveWithDedupe({
+      type: "decision",
+      title: `决定条目${i}`,
+      content: `第 ${i} 条与查询同向的普通决定，不该占掉 pin 的名额`,
+      importance: 5
+    }).memory;
+    vectorIndex.saveEmbedding(m.id, [1, 0, 0]);
+    ids.push(m.id);
+  }
+  return ids;
+}
+
+// 与查询向量正交的 pin 条目：向量路永远检索不到它们，只能靠规则窗口进块。
+function seedPinnedPreferences(service, vectorIndex, n) {
+  const ids = [];
+  for (let i = 0; i < n; i++) {
+    const m = service.saveWithDedupe({
+      type: "preference",
+      title: `硬偏好${i}`,
+      content: `第 ${i} 条约束/偏好，每轮必进，与查询向量正交`,
+      importance: 5
+    }).memory;
+    vectorIndex.saveEmbedding(m.id, [0, 1, 0]);
+    ids.push(m.id);
+  }
+  return ids;
+}
+
+const titlesOf = (list) => list.map((m) => m.title);
+
+test("pin 池不被向量路封顶：poolSize 被填满时仍拿满 pinnedInjectBudget", () => {
+  // maxItems=5 → poolSize=10，与生产默认值一致；预算是 5，满额。
+  const { service, vectorIndex } = setup({
+    maxInjectedItems: 5,
+    pinnedInjectBudget: 5,
+    importanceThreshold: 3
+  });
+  seedVectorCrowd(service, vectorIndex, 10); // 正好 poolSize 条，全是 decision
+  seedPinnedPreferences(service, vectorIndex, 5);
+
+  const pinnedStats = {};
+  const selected = service.injectCandidates({
+    query: "随便问一个与偏好无关的问题",
+    maxItems: 5,
+    queryVector: [1, 0, 0],
+    pinnedStats
+  });
+
+  // 缺口本体的断言：修前这里是 0（向量路 10 条里一条 preference 都没有）。
+  assert.equal(pinnedStats.shown, 5, "pin 池必须拿满预算，不能被向量路的 poolSize 截断");
+  const pinnedTitles = titlesOf(selected).filter((t) => t.startsWith("硬偏好"));
+  assert.equal(pinnedTitles.length, 5, "5 条 pin 必须真的进块（不只是计数对）");
+  // pin 前置在块内：前 5 位必须全是 pin 条目（同 importance/updated_at 的
+  // 同批条目内部次序由 id 决定，不是本用例要锁的东西，故只断言集合）。
+  const head = titlesOf(selected).slice(0, 5);
+  assert.ok(head.every((t) => t.startsWith("硬偏好")), `pin 前置到块内排序之前：${head.join(" / ")}`);
+  assert.deepEqual([...head].sort(), [...pinnedTitles].sort(), "前 5 位就是那 5 条 pin");
+});
+
+test("pin 池取自规则窗口，不取自被封顶的 candidates", () => {
+  // 这条锁的是「怎么修」而不是「修没修」：向量路返回的 10 条与 pin 类型完全
+  // 不相交，若 eligible 仍从 candidates 过滤，pin 恒为 0——无论 poolSize 多大。
+  const { service, vectorIndex } = setup({
+    maxInjectedItems: 2,
+    pinnedInjectBudget: 2,
+    importanceThreshold: 3
+  });
+  seedVectorCrowd(service, vectorIndex, 4); // poolSize = maxItems*2 = 4，正好填满
+  seedPinnedPreferences(service, vectorIndex, 2);
+
+  const pinnedStats = {};
+  const selected = service.injectCandidates({
+    query: "另一个与偏好无关的问题",
+    maxItems: 2,
+    queryVector: [1, 0, 0],
+    pinnedStats
+  });
+
+  assert.equal(pinnedStats.shown, 2, "maxItems=2 时 pin 也要拿满 2 条");
+  const head = titlesOf(selected).slice(0, 2);
+  assert.ok(
+    head.every((t) => t.startsWith("硬偏好")),
+    `pin 从规则窗口取，与向量命中集无关：${head.join(" / ")}`
+  );
+});
+
+test("pin 池关闭时行为不变：pinnedInjectBudget=0 不得凭空引入偏好", () => {
+  // 关闭态必须与改动前逐字节一致——补回的 pin 只在预算 > 0 时发生，
+  // 预算关时 candidates 与改前完全一样。
+  const { service, vectorIndex } = setup({
+    maxInjectedItems: 5,
+    pinnedInjectBudget: 0,
+    importanceThreshold: 3
+  });
+  seedVectorCrowd(service, vectorIndex, 10);
+  seedPinnedPreferences(service, vectorIndex, 5);
+
+  const pinnedStats = {};
+  const selected = service.injectCandidates({
+    query: "又一个与偏好无关的问题",
+    maxItems: 5,
+    queryVector: [1, 0, 0],
+    pinnedStats
+  });
+
+  assert.equal(pinnedStats.shown, 0, "预算 0 → pin 池关闭");
+  assert.equal(selected.length, 5, "槽位数不变");
+  assert.ok(
+    titlesOf(selected).every((t) => t.startsWith("决定条目")),
+    "关闭态下 preference 不得被前置（顺序与改动前一致）"
+  );
+});
+
+// 安全底线：补回 pin 是在 strictScope 与 scopeState 两道闸门**之前**做的，
+// 所以这两道闸必须照旧能拦住被补回来的 pin 行。service.js 里那条位置纪律
+// （「pin 池 eligible 取自过滤之后的候选，顺带保证越权行进不了 pin」）就是靠
+// 这两条用例守住的——不然「补回」会顺带开一个越权口子。
+test("补回的 pin 仍受 strictScope 硬过滤：越权偏好不得因补回而进块", () => {
+  const { store, service, vectorIndex } = setup({
+    maxInjectedItems: 5,
+    pinnedInjectBudget: 5,
+    importanceThreshold: 3,
+    strictScope: true
+  });
+  seedVectorCrowd(service, vectorIndex, 10);
+  // 一条属于 proj-a 的偏好：调用方 scope 是 proj-b 时它必须进不来。
+  const m = service.saveWithDedupe({
+    type: "preference",
+    title: "越权偏好",
+    content: "只属于 proj-a 的偏好，不该泄进 proj-b 的注入块",
+    importance: 5,
+    workspace_scope: "proj-a",
+    workspace_scope_source: "explicit"
+  }).memory;
+  vectorIndex.saveEmbedding(m.id, [0, 1, 0]);
+
+  const pinnedStats = {};
+  const selected = service.injectCandidates({
+    query: "与偏好无关的问题",
+    maxItems: 5,
+    queryVector: [1, 0, 0],
+    scope: { agent_scope: null, workspace_scope: "proj-b" },
+    pinnedStats
+  });
+
+  assert.ok(
+    !titlesOf(selected).includes("越权偏好"),
+    `strictScope 必须挡住被补回的越权 pin：${titlesOf(selected).join(" / ")}`
+  );
+  assert.equal(pinnedStats.shown, 0, "被 scope 挡下的行不能算成已 pin");
+});
+
+test("补回的 pin 仍受 scopeState 拦截档约束：暂停作用域的偏好不得进块", () => {
+  const { service, vectorIndex } = setup({
+    maxInjectedItems: 5,
+    pinnedInjectBudget: 5,
+    importanceThreshold: 3,
+    scopeState: { enabled: true, enforce: true }
+  });
+  seedVectorCrowd(service, vectorIndex, 10);
+  const m = service.saveWithDedupe({
+    type: "preference",
+    title: "暂停域偏好",
+    content: "属于 proj-a 的偏好，而 proj-a 此刻被按下",
+    importance: 5,
+    workspace_scope: "proj-a",
+    workspace_scope_source: "explicit"
+  }).memory;
+  vectorIndex.saveEmbedding(m.id, [0, 1, 0]);
+  service.setScopeState({ dimension: "workspace", scope_value: "proj-a", state: "paused" });
+
+  const pinnedStats = {};
+  const selected = service.injectCandidates({
+    query: "与偏好无关的问题",
+    maxItems: 5,
+    queryVector: [1, 0, 0],
+    pinnedStats
+  });
+
+  assert.ok(
+    !titlesOf(selected).includes("暂停域偏好"),
+    `scopeState 拦截档必须挡住被补回的 pin：${titlesOf(selected).join(" / ")}`
+  );
+  assert.equal(pinnedStats.shown, 0, "被闸门拦下的行不能算成已 pin");
+});

package/test/persona-settings.test.js

@@ -165,3 +165,34 @@ test("personaEnabled is in the feature-flag boolean whitelist", () => {
   assert.throws(() => settings.setFeatureFlags({ notARealFlag: true }), TypeError);
   store.close();
 });
+
+test("strict 寻址：一张身份卡都没建时仍回落 default（#587 的例外）", () => {
+  // 两种处境必须分开：
+  //   A) 建了身份卡、只是没这一张 → strict 下不注入（见上一条用例，行为不变）
+  //   B) 一张身份卡都没建      → default 是用户手里唯一那张卡，strict 不许把它关死
+  // DS Bot 这类宿主里所有 bot 会话共用 agentPreset "standard"，用户按 bot 名字建卡
+  // 永远不命中，于是必然落进 B——此时按 none 处理等于把唯一那张卡静默废掉。
+  const { store, settings } = setup();
+  settings.setPersona({ name: "Amarre", enabled: true });
+  assert.deepEqual(settings.getPersona().byAgent, {}, "前提：byAgent 整体为空");
+  const { card, source } = resolvePersonaCard(settings, "standard", { strict: true });
+  assert.equal(source, "default", "一张卡都没建时严格寻址仍回落 default");
+  assert.equal(card.name, "Amarre");
+  // 建了任意一张身份卡之后，例外立即失效——兜底退回严格语义
+  settings.setPersonaFor("zephyr", { name: "泽菲尔", enabled: true });
+  assert.equal(resolvePersonaCard(settings, "standard", { strict: true }).source, "none");
+  // 而这张卡自己仍然命中
+  assert.equal(resolvePersonaCard(settings, "zephyr", { strict: true }).source, "byAgent");
+  store.close();
+});
+
+test("strict 寻址：身份卡存在但全被关掉，仍算「建过卡」——例外只看有没有键", () => {
+  // 例外判的是 byAgent 的键数，不是「有没有可用的卡」：一张 enabled=false 的卡
+  // 也算「用户已经做过分区」，此时不该再拿 default 去兜。这条锁住判据不会被
+  // 改成「有可用卡才算建过」，否则关掉唯一那张身份卡会重新落回 default。
+  const { store, settings } = setup();
+  settings.setPersona({ name: "Amarre", enabled: true });
+  settings.setPersonaFor("zephyr", { name: "泽菲尔", enabled: false });
+  assert.equal(resolvePersonaCard(settings, "standard", { strict: true }).source, "none");
+  store.close();
+});