@modusensus/dsh-mneme 0.8.11 → 0.8.13

package/src/graph/anchoring.js

@@ -0,0 +1,180 @@
+// dsh-mneme/src/graph/anchoring.js
+// 图谱锚定层（issue #24 · 块1 Activation Anchoring）。
+import assert from "node:assert/strict";
+// 纯函数模块：把「查询命中实体的多路激活信号」归一化、合并成种子集、再沿
+// entity_relations 级联扩散。零数据库依赖——store 侧查询由调用方注入，
+// 本模块只做信号处理，便于单测与与其他召回通路（BM25/向量）同等对待。
+//
+// 设计输入来自 #24 合议 + heptaspirit serendipity-engine 实战（#24 评论）：
+//  - 归一化二分法：连续分（cos/PPR）走 min-max；匹配通路（精确/tag/别名）
+//    走离散级别，不用 min-max——布尔通路用 min-max 会把「中 1 个」和「中
+//    20 个」都拉平到 1.0，级别信息被压平。
+//  - 级联扩散加「跳数配额」：λ/θ 只管可及性，可见性由配额决定——直接按 hop
+//    深度打 0.5/0.3/0.2 权重，配桶内 round-robin，防深跳被 1-hop 完全压住。
+//  - graphSeedCap：防「多锚点命中 + 模糊通路」把种子集撑爆成整库。
+//  - 排序稳定：并列按实体 ID 破序（同输入两次结果不同会让 A/B 调参白做）。
+
+/** 匹配通路的离散级别（heptaspirit 建议：布尔/计数通路不用 min-max）。 */
+export const DISCRETE_LEVELS = Object.freeze({
+  exact: 1.0, // 名称精确含于查询（布尔 1.0）
+  title: 0.8, // 实体名匹配记忆标题（tag/别名层）
+  alias: 0.6,
+  tag: 0.4,   // tag 共现
+  substring: 0.2, // 子串命中（最弱，纯计数不级联）
+});
+
+/** 级联每跳的权重（跳数配额：1:2:3-hop = 0.5/0.3/0.2）。 */
+export const HOP_QUOTA = Object.freeze({ 1: 0.5, 2: 0.3, 3: 0.2 });
+
+/**
+ * 连续分 min-max 归一化（向量 cos 相似度、PPR 激活分等）。
+ * 输入 [] 或全同值时返回原样（无尺度可压平，防除零）。
+ */
+export function minMax(scores) {
+  const arr = Array.isArray(scores) ? scores : [];
+  if (arr.length === 0) return [];
+  let min = Infinity;
+  let max = -Infinity;
+  for (const v of arr) {
+    if (v < min) min = v;
+    if (v > max) max = v;
+  }
+  if (max - min < 1e-12) return arr.map(() => 1); // 平局视为满权
+  return arr.map((v) => (v - min) / (max - min));
+}
+
+/**
+ * 把一条检测通路的结果归一化成 0..1 的打分表。
+ * path 是离散通路名（exact/tag/...）→ 查 DISCRETE_LEVELS；是连续通路
+ * （continuous=true）→ min-max。返回 { byId: Map<id, score>, order: [id...] }。
+ */
+export function normalizePath(hits, { path = "exact", continuous = false } = {}) {
+  const ids = Array.isArray(hits) ? hits : [];
+  const byId = new Map();
+  if (continuous) {
+    const raw = ids.map((h) => (typeof h === "number" ? h : h?.score ?? 0));
+    const norm = minMax(raw);
+    ids.forEach((h, i) => {
+      const id = typeof h === "object" ? h.id : h;
+      byId.set(id, norm[i]);
+    });
+  } else {
+    const level = DISCRETE_LEVELS[path] ?? DISCRETE_LEVELS.substring;
+    for (const id of ids) byId.set(id, level);
+  }
+  return { byId, order: [...byId.keys()] };
+}
+
+/**
+ * 合并多路激活成种子集：每路先归一化（调用方负责通路分类），再累加。
+ * seedsCap 上限（graphSeedCap，默认 12）；封顶前按总分排序取前 N——保证
+ * 扩散的是活跃子图而非冷启动点爆整库。
+ * 返回 { id, name, score, paths: Set } 列表，按 score 降序、name 升序（稳定）。
+ */
+export function anchorSeeds({ paths = [], cap = 12 } = {}) {
+  const score = new Map();
+  const nameOf = new Map();
+  const pathSet = new Map();
+  for (const p of paths) {
+    for (const [id, s] of p.byId ?? []) {
+      score.set(id, (score.get(id) ?? 0) + s);
+      if (!pathSet.has(id)) pathSet.set(id, new Set());
+      pathSet.get(id).add(p.path ?? "?");
+      if (p.nameOf?.has?.(id)) nameOf.set(id, p.nameOf.get(id));
+    }
+  }
+  let seeds = [...score.entries()].map(([id, s]) => ({
+    id,
+    name: nameOf.get(id) ?? id,
+    score: s,
+    paths: pathSet.get(id) ?? new Set()
+  }));
+  seeds.sort((a, b) => b.score - a.score || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  if (cap > 0 && seeds.length > cap) seeds = seeds.slice(0, cap);
+  return seeds;
+}
+
+/**
+ * 级联扩散：从种子实体出发沿 adjacency 走 BFS，为每个可达实体贴最短深度。
+ * depth 上界默认 2（[1,3] 配置范围）。返回 Map<entityId, minDepth>——
+ * 调用方据此取 HOP_QUOTA[minDepth] 权重 + 桶内 round-robin（见 pickByHopQuota）。
+ * adjacency 由调用方提供（store.getEntityNeighbors(id) 或全量邻接矩阵），
+ * 本模块不感知存储。
+ */
+export function cascadeDepths({ seeds, adjacencyOf, maxDepth = 2 } = {}) {
+  const depths = new Map();
+  const idOfSeeds = (seeds ?? []).map((s) => (typeof s === "object" ? s.id : s));
+  const queue = [];
+  for (const id of idOfSeeds) {
+    if (!depths.has(id)) {
+      depths.set(id, 0);
+      queue.push([id, 0]);
+    }
+  }
+  for (let i = 0; i < queue.length; i++) {
+    const [id, d] = queue[i];
+    if (d >= maxDepth) continue;
+    let neighbors = [];
+    try {
+      neighbors = typeof adjacencyOf === "function" ? adjacencyOf(id) : (adjacencyOf?.get?.(id) ?? []);
+    } catch { /* single neighbor fetch failure: keep spreading from the rest */ }
+    for (const nb of neighbors) {
+      const nid = typeof nb === "object" ? nb.id : nb;
+      if (!nid || depths.has(nid)) continue;
+      depths.set(nid, d + 1);
+      queue.push([nid, d + 1]);
+    }
+  }
+  return depths;
+}
+
+/**
+ * 跳数配额选取：候选实体按深度分层，层内按（分，ID）稳定排序后取额度。
+ * quota 形如 { 1: 0.5, 2: 0.3, 3: 0.2 }——每层最多取 ceil(depthCap * quota[d]) 个，
+ * 桶内按 score 降序（并列按 ID）。返回 { ids, scoreOf, depthOf }。
+ * 这一步把「级联可及性」与「最终可见性」解耦（heptaspirit：λ/θ 只管前者）。
+ */
+export function pickByHopQuota({
+  depths = new Map(),
+  scoreOf = () => 0,
+  maxDepth = 2,
+  depthCap = 12
+} = {}) {
+  const buckets = new Map(); // depth -> [{id, score}]
+  for (const [id, d] of depths) {
+    if (d === 0 || d > maxDepth) continue;
+    const key = Math.min(d, 3);
+    if (!buckets.has(key)) buckets.set(key, []);
+    buckets.get(key).push({ id, score: scoreOf(id) ?? 0 });
+  }
+  const picked = [];
+  for (const [d, items] of buckets) {
+    items.sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const quota = HOP_QUOTA[d] ?? 0.2;
+    const n = Math.max(1, Math.floor(depthCap * quota));
+    picked.push(...items.slice(0, n).map((x) => x.id));
+  }
+  // 队内稳定序：按深度升序（1-hop 优先），保证可感知的扩散次序。
+  picked.sort((a, b) => (depths.get(a) - depths.get(b)) || (a < b ? -1 : a > b ? 1 : 0));
+  return { ids: picked, scoreOf, depthOf: depths };
+}
+
+// Lightweight self-check (ponytail: 非平凡逻辑留一个可运行断言)。
+export function _selfCheck() {
+  const exact = normalizePath(["e1", "e2"], { path: "exact" });
+  const tag = normalizePath(["e2", "e3"], { path: "tag" });
+  assert(exact.byId.get("e1") === 1.0 && exact.byId.get("e2") === 1.0, "exact level");
+  assert(tag.byId.get("e2") === 0.4 && tag.byId.get("e3") === 0.4, "tag level");
+  const seeds = anchorSeeds({ paths: [exact, tag], cap: 10 });
+  assert(seeds[0].id === "e2", "merged highest first"); // e2: 精确+tag = 1.4
+  assert(seeds[0].score >= 1.4 - 1e-9, "score accumulates");
+  const adj = new Map([
+    ["e2", ["n1", "n2"]],
+    ["n1", ["n2", "deep3"]],
+  ]);
+  const depths = cascadeDepths({ seeds, adjacencyOf: (id) => adj.get(id) ?? [], maxDepth: 2 });
+  assert(depths.get("n1") === 1 && depths.get("n2") === 1 && depths.get("deep3") === 2, "bfs depth");
+  const { ids } = pickByHopQuota({ depths, maxDepth: 2, depthCap: 12 });
+  assert(ids.includes("n1") && ids.includes("n2") && ids.includes("deep3"), "quota picks all");
+  return "anchoring self-check ok";
+}

package/src/guide.js

@@ -38,9 +38,21 @@ export const TOOL_GUIDE = {
     " Use this when the task depends on earlier decisions, preferences, or project history that is not already in context, " +
     "or to look for a newer memory behind one that seems stale. " +
     "Skip it for facts you can read directly from the repository.",
+  // 第二句（#249 第二批：「能力说明里没提 scope」）：TOOL_GUIDE.memory_save 此前只
+  // 讲「该不该写」，没讲「写给谁看」——而 memory_save 的 scope 参数是**必填面**，
+  // 漏填的后果是单向的。所以这里给的是一条判断规则而不是一句免责声明：不确定就别填
+  // （未标注 = 处处可见，NULL 恒可见，是安全的默认）；标了 scope 才在多 scope 检索里
+  // 付出代价。那句代价必须按实写：A2 软隔离是「他 scope 降权 ×0.5 但保留可见」
+  // （service.js），只有 A3 `strictScope`（默认关）才真的硬过滤。写「静默消失」既不
+  // 符合默认配置下的行为，也撞上「拒绝可解释、不静默丢弃」的口径（#254 验收第 2 条），
+  // 会让模型以为标注有它实际没有的隐私效果。
+  // 写进工具描述而不是总则：它是 memory_save 单工具的判据，总则那五条讲的是
+  // 「何时查 / 何时写 / 何时 no-op」，加第六条会把单工具语义抬成全局纪律。
   memory_save:
     " Save only durable, cross-session value (a preference, a decision with its rationale, an engineering constraint, " +
-    "a pitfall with its root cause). Trivial single-turn work does not belong here, and when unsure, do not save."
+    "a pitfall with its root cause). Trivial single-turn work does not belong here, and when unsure, do not save. " +
+    "If a memory only holds for one workspace or one agent, declare workspace_scope / agent_scope; otherwise leave both out. " +
+    "An unscoped memory is visible everywhere; a scoped one is filtered or downranked outside its scope."
 };
 
 /**

package/src/index.js

@@ -5,6 +5,8 @@ import { resolveDocumentDir } from "./document.js";
 import { createService } from "./service.js";
 // #254 写入准入（第一阶段只计量，不拦截）：见 src/write-admission.js 的文件头。
 import { createWriteAdmission } from "./write-admission.js";
+// #164 A2：写入边界的密钥 / PII 判据，注入给上面的写入准入。
+import { createSensitiveScan } from "./sensitive-scan.js";
 import { createTools } from "./tools.js";
 import { createInjector } from "./inject.js";
 import { createContinuityRescue } from "./continuity.js";
@@ -278,11 +280,17 @@ export const apply = (ctx, config) => {
   // 关掉，在无保留期的表里按写入频次增长是不能接受的）。
   //
   // sensitiveScan 是密钥 / PII 那一类判据的注入点。按 #254 验收第 4 条它是 #164 A2
-  // 的判据来源（A2 记在维护者排期里），所以本批不实现它，只把接口形状定在这里——
-  // 接上时只改这一行：
-  //   createWriteAdmission({ ..., sensitiveScan: createSensitiveScan({ config: cfg }) })
-  // 缺省 null 时第 1 级只跑空白 / 噪声两类判据，其余一切照旧。
-  const writeAdmission = createWriteAdmission({ store, config: cfg, logger: ctx.logger });
+  // 的判据来源，现在由 src/sensitive-scan.js 实现（维护者 09-28 把 A2 的认领转给
+  // 本侧）。这里只做接线：判据开不开由它自己的键 sensitiveScanEnabled 决定，工厂在
+  // 关时返回 null，闸门的行为就与 #332 合并时逐字段一致（那一版根本没有这个函数）；
+  // 命中之后是仅告警还是真拦，仍是 writeAdmission.enforce 的事（#164 口径：
+  // 默认仅告警、拦截 opt-in），判据不碰决策。
+  const writeAdmission = createWriteAdmission({
+    store,
+    config: cfg,
+    logger: ctx.logger,
+    sensitiveScan: createSensitiveScan({ config: cfg })
+  });
   const service = createService({ store, mirror, config: cfg, logger: ctx.logger, documentIndex, writeAdmission });
 
   // F-NEW-03: if the mirror sync failed last run (persisted dirty state), retry
@@ -502,6 +510,11 @@ export const apply = (ctx, config) => {
       logger: ctx.logger,
       semantic: { embedder, vectorIndex },
       lastRunAtSeed: store.lastDreamRunAt("auto"),
+      // Issue #89（基线半边）：阈值基线同样跨重启恢复——只恢复 lastRunAt 的话，
+      // 重启后的第一条写入仍会绕过阈值（库里记忆多于阈值时 overBase 恒成立）开跑
+      // 整轮。种子取上次成功轮的库规模，口径与运行期刷新一致；读不到时调度器退回
+      // 零基线（= 升级前行为）。
+      baselineSeed: store.lastDreamBaseline("auto"),
       // Issue #239（第 4 项）镜像到巩固：高峰期不做梦，顺延到最近的高峰结束时刻。
       peakHours: cfg.dreamPeakHours ?? "",
       peakMaxDeferMinutes: cfg.dreamPeakMaxDeferMinutes ?? 120,

package/src/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/src/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/src/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;
+}