@modusensus/dsh-mneme 0.8.11 → 0.8.13

package/lib/inject.js

@@ -274,9 +274,14 @@ export function createInjector(ctx, service, settings, config) {
     // 日志抢同一份预算后被降级」正是本议题要修的结构缺陷。单条仍有硬顶
     // （PINNED_CONTENT_MAX），超出照旧带截断提示，不静默。
     const pinnedCount = Math.max(0, Math.min(candidates.length, pinnedStats?.shown ?? 0));
+    // #24 块3：图召回线索行（graphHint）——引导语插在第一个线索行之前（保持块头
+    // 语义：先声明「这些不是事实」）。线索行自身按 graphHintLine 渲染（线索/ 前缀
+    // 区别于普通记忆行）。
+    let graphSeen = 0;
     for (let i = 0; i < candidates.length; i++) {
       const m = candidates[i];
       const pinned = i < pinnedCount;
+      if (m.graphHint === true) graphSeen++;
       // Epistemic trust (v0.4.5): when enabled, measured observations are
       // flagged so the agent can weigh them above guesses/opinions.
       const verified = config.trustEpistemicWeighting === true && m.epistemic_status === "observation"
@@ -284,7 +289,13 @@ export function createInjector(ctx, service, settings, config) {
         : "";
       const title = STR.entryTitle[language](m.title, m.importance);
       const content = injectMemory(m, pinned ? PINNED_CONTENT_MAX : maxContent);
-      const full = STR.entryLine[language](m.type, verified, title, content);
+      const full = m.graphHint === true
+        ? STR.graphHintLine[language](m.type, title, content)
+        : STR.entryLine[language](m.type, verified, title, content);
+      // 线索行引导语插在第一个线索行之前（保持块头语义：先声明「这些不是事实」）。
+      if (m.graphHint === true && graphSeen === 1) {
+        lines.push(STR.graphHintHeader[language]);
+      }
       if (pinned) {
         // pin 不扣块预算（上面那条设计注释的落地）：pin 一条就够击穿 MAX_BLOCK
         // （PINNED_CONTENT_MAX 2000 > MAX_BLOCK 1500），照扣会把 budget 压成负数，
@@ -363,8 +374,9 @@ export function createInjector(ctx, service, settings, config) {
         const query = lastUserQuery(ctx);
         if (query) prefetchQueryVector(query);
         const queryVector = queryVectorCache.get(query);
-        // v0.8.0 A3：scope 随请求解析（strict 开启时 injectCandidates 内硬过滤；
-        // flag 关闭时解析器返回 null，注入行为不变）。
+        // v0.8.0 A3：scope 随请求解析（解析器恒返回对象，身份取不到时两维为
+        // null）；硬过滤与软加权的门控都在 injectCandidates 内——strict 看
+        // strictScope，软加权看 scopeEnabled 且至少一维可解析（issue #339）。
         const scope = resolveSessionScope(ctx);
         // Issue #205：跨轮轮换——最近 N 个查询轮次注入过的 id 本轮不再优先。
         const sessionId = ctx?.agent?.session?.id ?? "_";

package/lib/lang.js

@@ -81,6 +81,16 @@ export const STR = {
     zh: (n) => `〔约束/偏好类另有 ${n} 条未展示〕`,
     en: (n) => `[${n} more constraint/preference entries not shown]`
   },
+  // Issue #24 块3：图召回线索行的引导语——正向声明「链路信息非事实断言」，
+  // 防 LLM 单次消费把桥接召回当有依据的事实回头扩散（幻觉诱导）。
+  graphHintHeader: {
+    zh: "[检索线索] 以下为实体图搜索的链路信息，仅供定位参考，非事实断言：",
+    en: "[Retrieval hints] Entity-graph link trails below are navigation aids, not factual assertions:"
+  },
+  graphHintLine: {
+    zh: (type, title, content) => `- [线索/${type}] ${title}：${content}`,
+    en: (type, title, content) => `- [hint/${type}] ${title}: ${content}`
+  },
   userSettingsHeader: {
     zh: "[用户设置] 来自 dsh-mneme 的用户画像与规则：",
     en: "[User settings] Profile and rules from dsh-mneme:"

package/lib/sensitive-scan.js

@@ -0,0 +1,209 @@
+// #164 A2：写入边界的密钥 / PII 判据。判据来源是 #164 A2（维护者 09-28 把认领转给
+// 本侧），消费方是 #254 的写入准入——`write-admission.js` 从 #332 起就留了
+// `sensitiveScan` 注入点，本模块是那个占位的实现。
+//
+// 为什么判据独立成文件、不写进 write-admission.js：判据的归属是 #164 A2，闸门的归属
+// 是 #254。闸门只消费 `{kind, label}`（deny 面已在 #332 定死），判据自己既不认识
+// 「会话预算」也不认识 `llm_audit_logs`——换一个判据（比如将来接更重的 PII 分类器）
+// 只换注入的那一行。写入边界的另外两个出口（autoSummarize / dream 输出）要复用同一份
+// 判据时也直接 import 本模块的 `scanSensitive`，不必各写一套形状。
+//
+// 三条判据口径（前两条是 #254 已定的硬约束，第三条是本模块自己的）：
+//
+// 1. 零 LLM、纯确定性。写入路径在最上游，这里多花的时间会乘上每一次写入；EdgeMem
+//    （2609.05553）那句「能不用模型判定就不用」说的就是这一层。
+//
+// 2. 假阳率由负样本定。`test/helpers/write-admission-samples.js` 的 12 条负样本是
+//    #332 就配好的验收面，维护者把话说死了：「同一套负样本原样跑，抓错任何一条就不
+//    算落地」。所以本模块的形状是**先认形状再认关键词**——纯关键词匹配在那组负样本
+//    上全军覆没（「把 API key 放进环境变量」这类讨论句里一个凭据值都没有）。
+//
+// 3. 报最严重的那一类（`kind` 落审计）。同一个字符串可能同时像两类（`sk_live_` 前缀
+//    既是 Stripe 的形状、也能被通用的 `sk-` 规则吃下），所以规则表按「越具体越靠前」
+//    排，命中即返回。密钥在前、PII 在后：两者误杀面差一个量级（密钥串出现在正常项目
+//    记忆里就是事故，邮箱 / 手机号完全可能是正当内容），同时命中时报更严重的那一类。
+//    `kind` 是稳定判据键（不是展示文案），enforce 打开前先按它看分布，将来要按类放行
+//    也只改策略、不动判据。
+//
+// 已知边界（都是「宁漏不误杀」的取舍，不是遗漏）：
+//   - 只扫文本（title / content / tags）。不扫路径、id、时间戳这类元数据字段——它们
+//     由系统生成，不是用户写进来的内容，扫它们只会引入假阳。
+//   - 中文关键词（密码 / 令牌）不认。补进去会让「密码必须脱敏后再入库」这类讨论句
+//     命中，而那正是负样本 group 的形状。要覆盖中文赋值得先设计「关键词语种 × 值形状」
+//     的两维判据，不在本批。
+//   - 手机号只认大陆移动号段（1[3-9] + 9 位），固定电话与带国家码的写法不认。宽一位
+//     就会把长度相近的订单号 / 内部编号吃进来，而 PII 这一档的误杀面已经比密钥大一档。
+//   - 银行卡号加 Luhn 校验：`0000000000000000`、`4111111111111112` 这类形状对但校验
+//     不过的串不报。少了这道校验，任何 16 位数字串（订单号、时间戳拼接）都会命中。
+//   - 身份证同样加校验位（GB 11643 / ISO 7064 MOD 11-2）：位数对但校验不过的 18 位
+//     数字串不报。原先只有银行卡有校验、身份证没有，结果是 18 位纯数字先被身份证规则
+//     命中，反倒绕过银行卡那条的 Luhn。
+//
+// 归一化：这里**不**用 content-hash.js 的 normalizeForHash。那套口径（NFKC → 小写 →
+// 去标点）是为「只差格式的两条写入是否同一件事」定的，判据要的是原串的形状——大小写
+// 是密钥 alphabet 的一部分（`AKIA` 与 `akia` 不是同一个值），去掉 `-` / `_` 会把 JWT
+// 与 Slack token 的分段结构一起折没。两个口径别互换。
+
+/** 判据命中的返回形状（与 `createWriteAdmission` 的 sensitiveScan 契约一致）。 */
+// kind 是稳定键、label 是给人看的一行说明；两者都落 llm_audit_logs 的
+// metadata.deny，所以别在其中塞运行时的值（命中的凭据本身绝不落盘 / 不回显）。
+const SECRET_RULES = [
+  { kind: "aws_access_key", label: "AWS access key id", re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/ },
+  // AWS 的 secret access key 没有前缀，只能靠赋值键认：`AWS_SECRET_ACCESS_KEY` /
+  // `aws_secret_access_key` 这个键名是它的形状。最早的一批 `secret` 关键词规则被
+  // 「必须在赋值号前」的位置要求挡在外面（多词键里 `secret` 后面跟的是 `_`，不是
+  // `:`/`=`），所以它得单独一条。40 位下限取 AWS 官方密钥的固定长度。
+  {
+    kind: "aws_secret_key",
+    label: "AWS secret access key",
+    // 键名不分大小写，所以挂 `/i` 而不是行内修饰符组 `(?i:...)`：后者是 ES2025 语法，
+    // CI 矩阵里的 Node 22 直接抛 SyntaxError（本文件其余规则也没有用它的）。
+    // 值那一半本来就是 `[A-Za-z0-9/+=]`，带上 `/i` 不改变大小写敏感度。
+    re: /(?:aws[_-]?secret[_-]?access[_-]?key)\s*[:=]\s*["']?([A-Za-z0-9/+=]{40})(?![A-Za-z0-9/+=])/i
+  },
+  { kind: "github_token", label: "GitHub token", re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}\b/ },
+  { kind: "slack_token", label: "Slack token", re: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/ },
+  // PEM 头是明文私钥的确定标志，带不带正文都一样判——`BEGIN` 与 `PRIVATE KEY` 之间
+  // 可能有 `RSA` / `EC` / `OPENSSH`，所以中间那段是 [A-Z ]*。
+  { kind: "private_key", label: "PEM private key", re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
+  { kind: "jwt", label: "JSON Web Token", re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/ },
+  // scheme 与 userinfo 两段都加上界。scheme 那段的 `*` 作用在含 `.` 的字符类上，
+  // 一条长点分串（包名 / 路径 / 版本链）里每个起点都要一路回溯到结尾才发现没有
+  // `://` → 与 email 同源的 O(n²)（实测 120KB 对抗串里这条占 4.1 秒）。
+  // URL scheme 名本就短、`user:password` 也不会长到 64，上界只钉住回溯面，
+  // 真实连接串一条不少。
+  { kind: "connection_string", label: "credentials in URL", re: /\b[a-z][a-z0-9+.-]{0,31}:\/\/[^\s/:@]{1,64}:[^\s/:@]{6,}@/ },
+  // Stripe 排在通用 `sk-` 之前：`sk_live_…` 两条规则都吃，先到的那条决定 kind。
+  // 只认 sk_live_（生产密钥）：sk_test_ 是公开测试密钥，报它是纯误杀。
+  { kind: "stripe_key", label: "Stripe secret key", re: /\bsk_live_[A-Za-z0-9]{16,}\b/ },
+  { kind: "npm_token", label: "npm auth token", re: /_authToken\s*=\s*[A-Za-z0-9_-]{20,}/ },
+  // 下限 24 而不是 20：这是一条纯收紧、不动语料读数的加固——OpenAI 的 key 没有校验
+  // 位，前缀 + 长度是唯一形状，20 位会把更长的假阳性面留在表里。`sk-` 后面跟短串的
+  // 赋值句仍会被赋值型那条认下（那是**对的**：值长了 8 位以上就该报）。
+  { kind: "openai_key", label: "OpenAI API key", re: /\bsk-(?:proj-)?[A-Za-z0-9_-]{24,}\b/ },
+  {
+    // 赋值型：最常见的一类，也是负样本组（占位符 / 环境变量 / 模板变量 / 只提关键词）
+    // 的主要靶子。判据是「关键词 + 赋值号 + 右边真的是个值的形状」，值本身不校验
+    // alphabet——凭据值没有通用形状，能通用的只有「它不像占位符」。
+    kind: "assigned_secret",
+    label: "assigned credential literal",
+    // 左边界不能把 `_` 排除在外：环境变量名正是拿 `_` 当分隔符，排除它会让
+    // `DB_PASSWORD=` / `MY_API_KEY=` / `MYSQL_PASSWORD=` 整类漏放（只有恰好落在
+    // 行首的 `API_KEY=` 能中）。放宽后 #332 那套 26 条语料（含 12 条负样本）全绿，
+    // 说明原写法不是语料换来的取舍。挡误杀的是下面那道占位符守卫，不是这个边界。
+    re: /(?:^|[^A-Za-z0-9])(?:password|passwd|pwd|secret|api[_-]?key|token)\b\s*[:=]\s*["']?([^\s"']{8,})/i,
+    // 占位符守卫：右边是尖括号占位、shell / 模板变量、环境变量读取、或一串 x / * / …
+    // 时不算命中。少这道守卫，`password: <redacted>` 与 `token: ${TOKEN}` 都会被报，
+    // 而它们正是「配置里该怎么写」的示例文本。
+    guard: (value) => !/^(?:<[^>]*>|\$\{|\$[A-Z_]+$|process\.env|redacted|xx+|\*+|\u2026)/i.test(value)
+  }
+];
+
+const PII_RULES = [
+  {
+    kind: "email",
+    label: "email address",
+    // 先看 TLD 再看 `@`：反过来的 `(?:[A-Za-z]{2,}\.)+[A-Za-z]{2,}` 对
+    // `a@b.c.d.e` 这类可以回溯出指数条路径。
+    // local part 的 `+` 必须加上界。该字符类含 `.`，所以一条长点分串（包名 / 路径 /
+    // 版本链）后跟一个 `@` 时，每个起点都要重扫到那个 `@` 才失败 → 整体 O(n²)。
+    // 实测 120KB 对抗串 23.5 秒里这条占 18.6 秒，34KB 点分链要 0.6 秒；本判据在写入
+    // 路径上同步跑，等于把写入阻塞住。64 是 RFC 5321 给 local part 的上限，加上界
+    // 不缩检测面——放弃的只是长于 64 的非法形状。
+    re: /\b[A-Za-z0-9._%+-]{1,64}@(?:[A-Za-z0-9-]+\.)+[A-Za-z]{2,}\b/
+  },
+  { kind: "cn_mobile", label: "mainland mobile number", re: /(?<!\d)1[3-9]\d{9}(?!\d)/ },
+  { kind: "cn_id_card", label: "mainland ID number", re: /(?<![0-9A-Za-z])\d{17}[\dXx](?![0-9A-Za-z])/, cnId: true },
+  { kind: "bank_card", label: "payment card number", re: /(?<!\d)(?:\d{13,19})(?!\d)/, luhn: true }
+];
+
+/**
+ * Luhn（模 10）校验。银行卡号这一档只靠位数与首字符形状会把所有 13–19 位数字串
+ * 都吃进来，而项目记忆里长度差不多的数字串（订单号、拼接的时间戳）很常见；校验位
+ * 是卡号自带的、零成本的第二道形状。负样本里没有卡号形状的串，这道校验是防未列举
+ * 的那一类（同时它也不影响正样本：4111111111111111 是 Luhn 通过的公开测试卡号）。
+ * @param {string} value 归一后的数字串（可能含分隔符）
+ */
+function passesLuhn(value) {
+  const digits = value.replace(/\D/g, "");
+  if (digits.length < 13 || digits.length > 19) return false;
+  let sum = 0;
+  let double = false;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let d = digits.charCodeAt(i) - 48;
+    if (double) {
+      d *= 2;
+      if (d > 9) d -= 9;
+    }
+    sum += d;
+    double = !double;
+  }
+  return sum % 10 === 0;
+}
+
+// 大陆身份证校验位（GB 11643 / ISO 7064 MOD 11-2）。与银行卡的 Luhn 同理：18 位
+// 数字串在项目记忆里很常见（订单号、内部编号、拼接时间戳），位数这个形状拦不住它们，
+// 而校验位是身份证自带的、零成本的第二道形状。权重序列与余数映射都是标准值，别改。
+const CN_ID_WEIGHTS = [7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2];
+const CN_ID_CODES = "10X98765432";
+/** @param {string} value 命中串（17 位数字 + 校验位，校验位可为 X） */
+function passesCnId(value) {
+  if (!/^\d{17}[\dXx]$/.test(value)) return false;
+  let sum = 0;
+  for (let i = 0; i < 17; i++) sum += Number(value[i]) * CN_ID_WEIGHTS[i];
+  return CN_ID_CODES[sum % 11] === value[17].toUpperCase();
+}
+
+/**
+ * 扫一段文本里的密钥 / PII。命中返回 `{kind, label}`、未命中返回 null，不抛。
+ *
+ * 只认第一处命中（按规则表顺序 = 严重度顺序）。一次写入里出现第二条凭据时不再报——
+ * deny 面只记判据类别，报多条只是把同一件事写几遍。
+ * @param {unknown} value
+ * @returns {{kind: string, label: string}|null}
+ */
+export function scanSensitive(value) {
+  const text = typeof value === "string" ? value : String(value ?? "");
+  if (!text) return null;
+  for (const rule of [...SECRET_RULES, ...PII_RULES]) {
+    const match = text.match(rule.re);
+    if (!match) continue;
+    // 守卫只看捕获组：没有捕获组的规则天然没有守卫。
+    if (rule.guard && !rule.guard(match[1] ?? "")) continue;
+    if (rule.luhn && !passesLuhn(match[0])) continue;
+    if (rule.cnId && !passesCnId(match[0])) continue;
+    return { kind: rule.kind, label: rule.label };
+  }
+  return null;
+}
+
+/**
+ * 判据的两种调用面，共用同一份规则表：
+ *   `scanSensitive(text)`           — 任意文本，给写入边界之外的消费方（autoSummarize /
+ *                                     dream 输出）直接调；它们手里是文本，不是记忆行。
+ *   `createSensitiveScan({config})` — `write-admission.js` 的 `sensitiveScan` 契约，
+ *                                     入参是记忆对象、返回 `{kind, label}` 或 null。
+ *
+ * 开关在工厂里判一次：`sensitiveScanEnabled` 关时返回 null，闸门侧连函数都拿不到，
+ * 于是「第 1 级只跑空白 / 噪声」这条路与 #332 合并时**逐字段一致**（那一版根本没有
+ * 这个函数）。反过来，本键开着也不会自己去扫：唯一的调用点是闸门的 firstLevelHit，
+ * 而闸门要 `writeAdmission.enabled` 打开才走第 1 级判据。所以两个键是「闸门」与
+ * 「闸门内这一批判据」的关系，不是互为子开关——任一个关着，A2 都不产生任何判定。
+ * 分成两个键是为了能单独观察 A2 的命中分布（空白 / 噪声与密钥 / PII 的误杀面差一个
+ * 量级），不是为了让它能脱离闸门独立生效。
+ *
+ * @param {{config?: object}} [deps]
+ * @returns {((memory: object) => ({kind: string, label: string}|null))|null}
+ */
+export function createSensitiveScan({ config } = {}) {
+  if (config?.sensitiveScanEnabled !== true) return null;
+  const scan = (memory) => {
+    const text = [memory?.title, memory?.content, ...(Array.isArray(memory?.tags) ? memory.tags : [])]
+      .filter((s) => typeof s === "string")
+      .join("\n");
+    return scanSensitive(text);
+  };
+  // 工厂只认「开 / 关」；enforce 由 write-admission 决定（命中即 deny 还是仅告警），
+  // 判据自己不碰决策——那一步在闸门里。两层分开就能先开检测看分布、再开拦截。
+  return scan;
+}

package/lib/service.js

@@ -11,6 +11,7 @@ import { createDocumentRegistrar } from "./document.js";
 import { createOrganizer } from "./organize.js";
 import { createBM25Index } from "./search/bm25.js";
 import { adaptiveThreshold } from "./search/adaptive.js";
+import { anchorSeeds, normalizePath, cascadeDepths, HOP_QUOTA } from "./graph/anchoring.js";
 
 const INJECT_TYPES = new Set(["preference", "project", "decision", "summary", "rejected_solution", "pitfall", "constraint"]);
 
@@ -358,6 +359,22 @@ export function createService({ store, mirror, config, onWrite, logger, document
     }
   }
 
+  /**
+   * v0.8.0 A3（issue #17）strictScope 硬过滤的**唯一实现**。三处共用：融合池、
+   * `entity:` 与 `attr:` 两条前缀路。
+   *
+   * 抽成单一实现是为了让「过滤点写在哪」不再漂移——那两条前缀路在 searchMemories
+   * 的入口就 return（见那里的路由块），早于融合池那道过滤，曾经整条绕过硬墙；三处
+   * 各写一份判断，只会让下一个新增通路再漏一次（同 #349 把阈值口径收进
+   * activeStoreSize 的理由：两处各写一份过滤条件，漂移只在某条路径上显形）。
+   *
+   * strictScope 关（默认）或 scope 解析不到时原样返回：行为与改动前逐字节一致。
+   */
+  function gateByScope(rows, scope) {
+    if (config?.strictScope !== true || !scope) return rows;
+    return rows.filter((m) => isVisibleInScope(m, scope));
+  }
+
   /**
    * Search for memories attached to a named entity (v0.3.0 Phase 3).
    * 合并优先级：entity_attrs.memory_id 精确关联 = 1.0 > 关键词提及 = 0.7；
@@ -365,23 +382,34 @@ export function createService({ store, mirror, config, onWrite, logger, document
    * @param {string} entityName
    * @param {object} [options]
    * @param {number} [options.topK=20]
+   * @param {object|null} [options.scope] 当前会话 scope，供 strictScope 闸门使用
    * @returns {any[]}
    */
-  function searchByEntity(entityName, { topK = 20 } = {}) {
+  function searchByEntity(entityName, { topK = 20, scope = null } = {}) {
     const entity = store.findEntityByName(entityName);
     if (!entity) return [];
     const attrs = store.getCurrentAttrs(entity.id);
     const memoryIds = [...new Set(attrs.map((a) => a.memory_id).filter(Boolean))];
     const attrHits = memoryIds.map((id) => store.getById(id)).filter(Boolean);
-    const keywordHits = store.search(entityName, { limit: topK });
+    // 关键词这一路的窗口取两倍：闸门在截断之前生效，出局的候选会让位，窗口按最终条数
+    // 取就会不够（与融合路给向量检索取 lim * 2 同一个理由）。没有候选被闸掉时结果与
+    // 取 topK 逐字节一致——多出来的是排在后面的低分候选，进不了 topK。
+    const keywordHits = store.search(entityName, { limit: topK * 2 });
     const merged = new Map();
     for (const mem of attrHits) merged.set(mem.id, { ...mem, _source: "entity_attr", _score: 1.0 });
     for (const mem of keywordHits) {
       if (!merged.has(mem.id)) merged.set(mem.id, { ...mem, _source: "keyword", _score: 0.7 });
     }
-    const hits = Array.from(merged.values()).sort((a, b) => b._score - a._score).slice(0, topK);
-    touchRecalled(hits);
-    return hits;
+    // 先过闸、再截 topK：反过来做的话，出局的候选会占掉名额、可见的补不进来——topK=1
+    // 而首位出局时直接返回空数组。排序本身不动，只是把闸门插在截断之前，与融合池那条
+    // 路同序（那边也是先 filter 后 slice）。
+    const ranked = Array.from(merged.values()).sort((a, b) => b._score - a._score);
+    const visible = gateByScope(ranked, scope).slice(0, topK);
+    // 闸门还必须在 touchRecalled **之前**：放在后面的话，一次越权检索照样会给出局的
+    // 行刷回温时钟，并在被动确认开启时 bump 它们的关联边——命中反馈落到了调用方
+    // 本不该看见的行上。
+    touchRecalled(visible);
+    return visible;
   }
 
   /**
@@ -391,17 +419,19 @@ export function createService({ store, mirror, config, onWrite, logger, document
    * @param {string | undefined} value
    * @param {object} [options]
    * @param {number} [options.topK=20]
+   * @param {object|null} [options.scope] 当前会话 scope，供 strictScope 闸门使用
    * @returns {any[]}
    */
-  function searchByAttr(key, value, { topK = 20 } = {}) {
+  function searchByAttr(key, value, { topK = 20, scope = null } = {}) {
     if (!key) return [];
     // value 可能为 undefined（attr:key 无 = 值）：归一为空串后交给
     // store.findMemoriesByAttr —— 空 value 契约 = 返回该 attr_key 的全部
     // 当前有效记忆（v0.3.0，store.js 已实现）。
     const rows = store.findMemoriesByAttr(key, value ?? "");
-    const hits = rows.slice(0, topK);
-    touchRecalled(hits);
-    return hits;
+    // 同 searchByEntity：先过闸再截 topK，且闸门在 touchRecalled 之前。
+    const visible = gateByScope(rows, scope).slice(0, topK);
+    touchRecalled(visible);
+    return visible;
   }
 
   /**
@@ -448,30 +478,92 @@ export function createService({ store, mirror, config, onWrite, logger, document
   }
 
   /**
-   * Graph fourth recall path (issue #219). When the query text mentions a
-   * known entity name, memories linked to that entity (attrs + relations)
-   * join the fusion pool as a confirm/backfill signal — same standing as
-   * BM25, never dominating the semantic ranking. Tier scores: attr-linked
-   * 1.0 (direct evidence, same source searchByEntity trusts) > relation
-   * edge 0.9. Archived/forgotten rows never participate. Failures degrade
-   * to [] — a recall booster, never a correctness gate (same contract as
-   * bm25Recall).
+   * Graph fourth recall path (issue #219 → #24 块1 锚定层). When the query text
+   * mentions a known entity name, memories linked to that entity (attrs +
+   * relations) join the fusion pool as a confirm/backfill signal — same standing
+   * as BM25, never dominating the semantic ranking. Tier scores: attr-linked
+   * 1.0 (direct evidence, same source searchByEntity trusts) > relation edge
+   * 0.9. Archived/forgotten rows never participate. Failures degrade to [] —
+   * a recall booster, never a correctness gate (same contract as bm25Recall).
+   *
+   * #24 升级（graphAnchoringEnabled）：命中实体作为锚定种子，沿 entity_relations
+   * 级联扩散邻居（默认深度 2），邻居挂联的记忆以 hop 配额权重参与——把「关系是
+   * 用出来的」延伸成检索信号：查询命中的不只有直接挂联，还有跳跃可达的活跃子图。
+   * 邻居权重 = HOP_QUOTA[hop] × linked tier（attr 1.0 / relation 0.9），仍低于
+   * 直达种子的满权，绝不喧宾夺主。
    */
   function entityRecall(q, limit) {
     if (config?.entityRecallEnabled !== true) return [];
     try {
       const entities = store.findEntitiesMentionedIn(q);
       if (!entities.length) return [];
-      const linked = store.getLinkedMemoryIds(entities.map((e) => e.id));
-      if (!linked.size) return [];
-      const hits = [];
-      for (const [id, tier] of linked) {
-        const row = store.getById(id);
-        if (!row || row.archived || row.forgotten) continue;
-        hits.push({ ...row, score: tier === "attr" ? 1.0 : 0.9, source: "entity" });
-        if (hits.length >= limit * 2) break;
+      // 关闭锚定级联=逐字节复用 #219 单跳轴：种子裁剪/重排/截断全是 #24 新增的
+      // 行为，默认关时一条都不许漏进旧路径（graphSeedCap 也只在开启后生效——
+      // 无论 cap 调多小，关档时命中实体仍全量挂联）。
+      if (config?.graphAnchoringEnabled !== true) {
+        const linked = store.getLinkedMemoryIds(entities.map((e) => e.id));
+        if (!linked.size) return [];
+        const hits = [];
+        for (const [id, tier] of linked) {
+          const row = store.getById(id);
+          if (!row || row.archived || row.forgotten) continue;
+          hits.push({ ...row, score: tier === "attr" ? 1.0 : 0.9, source: "entity" });
+          if (hits.length >= limit * 2) break;
+        }
+        return hits;
       }
-      return hits;
+      // 锚定种子（精确名布尔通路——命名实体逻辑上是离散匹配，不参与 min-max）。
+      const exact = normalizePath(entities.map((e) => e.id), { path: "exact" });
+      const seeds = anchorSeeds({ paths: [exact], cap: config?.graphSeedCap ?? 12 });
+      if (!seeds.length) return [];
+      // 0-hop 直达：挂联记忆按 tier 定分（attr 1.0 / relation 0.9）——与 #219
+      // 单跳轴同分。MAX 语义：同一条记忆被多实体挂联时保留最高分。
+      const scored = new Map();
+      const push = (memId, score) => {
+        if (scored.has(memId) && scored.get(memId) >= score) return;
+        const row = store.getById(memId);
+        if (!row || row.archived || row.forgotten) return;
+        scored.set(memId, score);
+      };
+      const seedLinked = store.getLinkedMemoryIds(seeds.map((s) => s.id));
+      for (const [memId, tier] of seedLinked) {
+        push(memId, tier === "attr" ? 1.0 : 0.9);
+      }
+      // 级联：沿 entity_relations 走 BFS，邻居挂联的记忆以 hop 配额权重补位——
+      // 不覆盖种子直达分（MAX 语义保证），只填「种子里没有但邻居可达」的槽。
+      const seedIds = seeds.map((s) => s.id);
+      const adjacency = store.getEntityNeighbors(seedIds);
+      const depths = cascadeDepths({
+        seeds,
+        // 逐节点懒取邻居：初次查询只带种子那一层的邻接，BFS 走到 1-hop 节点时
+        // 必须按需再拉一层，否则 >1 跳永远拿到空邻居、graphCascadeDepth≥2 形同
+        // 虚设。节点数随图度数增长，热路径上以 graphCascadeDepth≤3 为天然上界，
+        // 真遇到大图再考虑查询配额。
+        adjacencyOf: (id) => {
+          if (!adjacency.has(id)) adjacency.set(id, store.getEntityNeighbors([id]).get(id) ?? []);
+          return adjacency.get(id);
+        },
+        maxDepth: config?.graphCascadeDepth ?? 2
+      });
+      let neighborsSeen = 0;
+      const neighborCap = (config?.graphSeedCap ?? 12) * HOP_QUOTA[1]; // 1-hop 配额即为邻居总量上界
+      for (const [nid, hop] of depths) {
+        if (hop < 1) continue;
+        if (neighborsSeen >= Math.max(1, Math.floor(neighborCap))) break;
+        neighborsSeen++;
+        const neighborLinked = store.getLinkedMemoryIds([nid]);
+        for (const [memId, tier] of neighborLinked) {
+          const tierW = tier === "attr" ? 1.0 : 0.9;
+          push(memId, HOP_QUOTA[Math.min(hop, 3)] * tierW);
+        }
+      }
+      const hits = [...scored.entries()]
+        .map(([id, score]) => {
+          const row = store.getById(id);
+          return { ...row, score, source: "entity" };
+        })
+        .sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+      return hits.slice(0, limit * 2);
     } catch {
       return [];
     }
@@ -530,11 +622,28 @@ export function createService({ store, mirror, config, onWrite, logger, document
    * on the hot recall path). A touch failure must never break search/inject.
    */
   function touchRecalled(memories) {
-    if (config?.heatEnabled === false || !Array.isArray(memories) || memories.length === 0) return;
+    if (!Array.isArray(memories) || memories.length === 0) return;
+    // heatEnabled=false 只关 touchLastAccess 的热度消费（既有语义），但 #24
+    // 块4 被动确认独立于 heat——graphPassiveConfirm 开时照常 bump 关联边。
+    // graphWeightEnabled 是块2 立的演化总闸：它关着时任何触达都不该改边权，被动
+    // 确认只是它底下的一个通道（后续块还会接别的确认通道），两键同开才 bump，
+    // 否则单开通道键就等于绕过「演化默认关」的承诺。
+    // 两条路径都 best-effort，失败绝不阻断检索/注入。
+    const heatOn = config?.heatEnabled !== false;
+    const passive = config?.graphPassiveConfirm === true && config?.graphWeightEnabled === true;
+    const delta = config?.graphWeightDelta ?? 0.1;
     for (const m of memories) {
       if (!m?.id) continue;
       try {
-        store.touchLastAccess(m.id);
+        if (heatOn) store.touchLastAccess(m.id);
+        if (passive) {
+          // 正常触达=对该记忆挂联关系边的被动确认；bump 只加不减封顶 1.0，
+          // 自激回路由封顶天然遏制。「仅异常路径暴露给用户复核」的确认记录
+          // 侧在此落地，复核 UI 留后续块。
+          for (const rel of store.getRelationsByMemory(m.id)) {
+            store.bumpRelationWeight(rel.id, delta);
+          }
+        }
       } catch { /* touch is best effort */ }
     }
   }
@@ -816,9 +925,7 @@ export function createService({ store, mirror, config, onWrite, logger, document
     // （区别于 A2 的降权保留可见）；未标注行与命中行保留。strict 与 A2 加权
     // 叠加：过滤后剩下的命中行仍吃加成。scope 未传（flag 关）或完全解析不到
     // 时跳过——identity 为空的对象（{null,null}）按 fail-closed 过滤。
-    if (config.strictScope === true && scope) {
-      merged = merged.filter((m) => isVisibleInScope(m, scope));
-    }
+    merged = gateByScope(merged, scope);
     // v0.8.0 A2：occurred_at 时间过滤——在融合池上先滤再 dedup/slice，rerank
     // 只看窗内候选，topK 槽位不被窗外行占用。
     const occurredBounds = updatedAtBounds(occurredFrom, occurredTo);
@@ -1427,6 +1534,14 @@ export function createService({ store, mirror, config, onWrite, logger, document
       ? new Map(filtered.map((m) => [m.id, computeHeat(m, Date.now(), config)]))
       : null;
     const heatOf = (m) => (heatMap ? heatMap.get(m.id) ?? 1 : 1);
+    // v0.8.x（issue #339 / E7 实测）：A2 软加权补齐到注入通道。此前 ×0.5/×1.25
+    // 只作用于 searchMemories——E7 考卷里「explicit 标注 + 软档」的注入集与无标注
+    // 逐条相同（80/80），主泄露面上软档形同虚设。门控与检索侧同款：scopeEnabled
+    // 且当前会话至少一维可解析；strictScope 硬过滤在下方先行，硬墙开启时被滤行
+    // 不会到这里被二次降权。未激活时乘 1，排序与改动前逐字节一致。
+    const softScopeActive = config?.scopeEnabled === true && scope != null &&
+      Boolean(scope.agent_scope || scope.workspace_scope);
+    const scopeMultOf = (m) => (softScopeActive ? scopeMultiplier(m, scope) : 1);
     const items = filtered.sort((a, b) => {
         // 编码记忆在编码任务时优先于普通 decision（与 preference 同级），
         // importance 乘 codingBoostFactor 加权（封顶 5，保持 importance 语义）。
@@ -1447,8 +1562,11 @@ export function createService({ store, mirror, config, onWrite, logger, document
             : m.importance;
         const pa = priority(a);
         const pb = priority(b);
+        // 软加权乘在层内数值积上（priority 档位不动）：foreign ×0.5 后压不过
+        // 同档自己行——E7 的同 importance 档设计正是这个场景。
         return pa - pb ||
-          (effImportance(b) * qualityWeight(b) * heatOf(b)) - (effImportance(a) * qualityWeight(a) * heatOf(a));
+          (effImportance(b) * qualityWeight(b) * heatOf(b) * scopeMultOf(b)) -
+          (effImportance(a) * qualityWeight(a) * heatOf(a) * scopeMultOf(a));
       });
     let candidates = items;
     if (config.hybridInject !== false && q) {
@@ -1493,6 +1611,13 @@ export function createService({ store, mirror, config, onWrite, logger, document
             semanticItems.push(hit);
           }
         }
+        // issue #339（CodeRabbit review on #350）：首轮 BM25 兜底领跑合并池，
+        // 而 selectiveInject 相似度重排要等查询向量就绪才执行——软加权必须
+        // 在这里就位，否则 foreign 命中绕过降权直接占注入位。
+        if (softScopeActive) {
+          semanticItems.sort((a, b) =>
+            (b.score ?? 0) * scopeMultOf(b) - (a.score ?? 0) * scopeMultOf(a));
+        }
       }
       if (semanticItems.length) {
         const seen = new Set();
@@ -1523,7 +1648,13 @@ export function createService({ store, mirror, config, onWrite, logger, document
         const hits = vectorIndex.search(queryVector, { limit: 200, threshold: 0 });
         const sim = new Map(hits.map((m) => [m.id, m.score ?? 0]));
         if (sim.size) {
-          candidates = [...candidates].sort((a, b) => (sim.get(b.id) ?? -1) - (sim.get(a.id) ?? -1));
+          // 软加权作用在真实 sim 上；未命中的规则候选保持 -1 沉底（缺失项
+          // 乘乘数会让 foreign 缺失项反而排到自己的缺失项之上，故不乘）。
+          const scopedSim = (m) => {
+            const s = sim.get(m.id);
+            return s === undefined ? -1 : s * scopeMultOf(m);
+          };
+          candidates = [...candidates].sort((a, b) => scopedSim(b) - scopedSim(a));
         }
       } catch { /* topic re-rank unavailable: keep rule-based order */ }
     }
@@ -1532,6 +1663,26 @@ export function createService({ store, mirror, config, onWrite, logger, document
     if (config?.strictScope === true && scope) {
       candidates = candidates.filter((m) => isVisibleInScope(m, scope));
     }
+    // #24 块3：图召回候选打标。entityRecall 只在 entityRecallEnabled 开启时
+    // 有产出，这里为命中者贴 graphHint 标签——注入侧据此（a）graphInjectHint
+    // 开=标成 [检索线索] 前缀的线索行（独立预算），（b）关=线索行只参与排序
+    // 不改变注入块（保守档）。与检索侧共用同一图闸：块1 #341 把 entityRecall
+    // 升级成级联后，注入侧自动吃到同样的扩散信号，无需再改。只在语义/规则候选
+    // 为空时兜底检索，避免注入路径双倍候选成本。
+    if (config?.entityRecallEnabled === true && q) {
+      try {
+        const graphHits = entityRecall(q, maxItems * 2);
+        if (graphHits.length) {
+          const graphIds = new Set(graphHits.map((m) => m.id));
+          candidates = [
+            ...candidates.map((m) => graphIds.has(m.id) ? { ...m, graphHint: true } : m),
+            ...graphHits
+              .filter((m) => !candidates.some((c) => c.id === m.id))
+              .map((m) => ({ ...m, graphHint: true }))
+          ];
+        }
+      } catch { /* graph hint is best-effort */ }
+    }
     // #249 第一批：B1 pin 池。取在相关性排序之后、轮换之前——取谁按此刻的候选
     // 次序（即相关性次序），取到后从候选中摘除，于是下面的轮换重排碰不到它们
     // （验收：pin 不参与跨轮轮换）。独立预算的两层意义：pin 既不占 maxItems
@@ -1539,7 +1690,10 @@ export function createService({ store, mirror, config, onWrite, logger, document
     // 超预算的条数回报给调用方，在块内如实标注（绝不静默省略）。
     const pinnedBudget = Math.max(0, Math.min(5, Math.floor(config?.pinnedInjectBudget ?? 0)));
     // eligible 留到块外：未展示条数要等 general 槽选完才算得准（见 selected 之后）。
-    const eligible = pinnedBudget > 0 ? candidates.filter((m) => PINNED_MEMORY_TYPES.has(m.type)) : [];
+    // graphHint 行不进 pin 池：pin 是「每轮必进的约束/偏好」，而线索行按定义是
+    // 「链路信息、非事实断言」，且 pin 长在候选池遍历之前——不排除的话，保守档
+    // （graphInjectHint 关）也能从 pin 侧把它放回注入块，线索开关就被绕过去了。
+    const eligible = pinnedBudget > 0 ? candidates.filter((m) => PINNED_MEMORY_TYPES.has(m.type) && m.graphHint !== true) : [];
     let pinned = [];
     if (pinnedBudget > 0 && eligible.length > 0) {
       pinned = eligible.slice(0, pinnedBudget);
@@ -1560,9 +1714,23 @@ export function createService({ store, mirror, config, onWrite, logger, document
     // 注入块变成文档目录（#164 失败判据：批量把历史塞进上下文）。
     const documentBudget = config?.documentInjectBudget ?? 2;
     let documentSeen = 0;
+    // #24 块3：图线索行（graphHint）按独立预算 graphInjectBudget 进块；所谓
+    // 独立=既不受 document 预算约束、也不挤占 maxItems 槽位。graphInjectHint
+    // 关（默认保守档）时线索行**不进注入块**——它们只参与候选池排序（对融合无
+    // 影响，因为候选池生成的唯一用途就是注入），桥接信号不污染常驻文本；开时
+    // 才作为 [检索线索] 前缀行进入。与 document/pin 同构：预算只约束注入。
+    const hintOpen = config?.graphInjectHint === true;
+    let graphSeen = 0;
+    const graphBudget = hintOpen ? Math.max(0, Math.floor(config?.graphInjectBudget ?? 1)) : 0;
     const general = [];
     for (const m of candidates) {
-      if (general.length >= maxItems) break;
+      if (m.graphHint === true) {
+        if (!hintOpen) continue;      // 保守档：线索只排序不进块
+        if (graphSeen >= graphBudget) continue; // 独立预算内放行
+        graphSeen++;
+      } else if (general.length >= maxItems) {
+        break; // 普通候选受 maxItems 槽位上界
+      }
       if (m.type === "document") {
         if (documentSeen >= documentBudget) continue;
         documentSeen++;