@modusensus/dsh-mneme 0.10.0 → 0.10.1

package/src/api.js

@@ -1438,7 +1438,57 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
             to: e.to_entity,
             relation_type: e.relation_type,
             memory_id: e.memory_id ?? null,
-            created_at: e.created_at
+            created_at: e.created_at,
+            // issue #24 块4：被动确认的复核要靠这两个字段——weight 是「用出来
+            // 的分」，source 决定它的起点（manual 1.0 / tag 0.3 / llm 0.4）。
+            // 少了它们，「这条边被抬过」在面板上根本看不出来。取不到时给
+            // 初值形状而不是 undefined，前端不必到处判空。
+            weight: e.weight ?? 1.0,
+            source: e.source ?? "manual"
+          }))
+        });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
+  // --- graph boosted relations: the review side of passive confirmation ---
+  // issue #24 块4（被动确认）的复核出口。正常触达即 bump 边权重是安静的设计，
+  // 但「抬过哪些边」必须能看见，否则「例外管理」只剩自动确认没有例外。
+  // 判据是 gain = 现权 − 该 source 初值 > 0（见 store.listBoostedRelations），
+  // 不另设记账表：抬升是唯一会改变检索形状的动作，它自己就是证据。
+  // 只读、挂在 /semantic/graph/ 前缀下（SECURITY.md 的开放读清单已含该通配）。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/semantic/graph/boosted-relations",
+    policy: "open",
+    handler(req, res) {
+      try {
+        const url = new URL(req.url, "http://localhost");
+        const limit = Math.max(1, Math.min(200, Number(url.searchParams.get("limit") ?? 100) || 100));
+        const rows = service.listBoostedRelations?.({ limit }) ?? [];
+        sendJson(res, 200, {
+          count: rows.length,
+          // 提示「这张表为什么可能为空」：被确认抬升的边只在图真的被用过之后
+          // 才出现，两个相关闸默认都关。面板据此说明而不是让人以为坏了。
+          // 必须两个闸同时开才算「会继续产生新提升」——touchRecalled 里
+          // passive = graphPassiveConfirm && graphWeightEnabled，只看前者会让面板
+          // 说「会自动提升」而实际上一条都不会抬（评审指出）。
+          passiveConfirmEnabled: config?.graphPassiveConfirm === true && config?.graphWeightEnabled === true,
+          items: rows.map((r) => ({
+            id: r.id,
+            from: r.from_entity,
+            to: r.to_entity,
+            from_name: r.from_name ?? null,
+            to_name: r.to_name ?? null,
+            relation_type: r.relation_type,
+            memory_id: r.memory_id ?? null,
+            created_at: r.created_at,
+            weight: r.weight,
+            base_weight: r.base_weight,
+            gain: r.gain,
+            source: r.source
           }))
         });
       } catch {

package/src/graph/anchoring.js

@@ -46,7 +46,12 @@ export function minMax(scores) {
 /**
  * 把一条检测通路的结果归一化成 0..1 的打分表。
  * path 是离散通路名（exact/tag/...）→ 查 DISCRETE_LEVELS；是连续通路
- * （continuous=true）→ min-max。返回 { byId: Map<id, score>, order: [id...] }。
+ * （continuous=true）→ min-max。返回 { path, byId: Map<id, score>, order }。
+ *
+ * issue #24 块1 补充：返回值带上 `path`。anchorSeeds 用它记「这个种子被哪几路
+ * 激活」（`seeds[i].paths`），复核时据此判断一条边是被精确名、Tag 桥接还是向量
+ * 拉进来的。此前只有 { byId, order }，`p.path ?? "?"` 把每一路都记成 "?"，
+ * 通路身份在合并那一步就丢了。连续通路调用方传 `path: "vector"`（cos 相似度）。
  */
 export function normalizePath(hits, { path = "exact", continuous = false } = {}) {
   const ids = Array.isArray(hits) ? hits : [];
@@ -62,7 +67,7 @@ export function normalizePath(hits, { path = "exact", continuous = false } = {})
     const level = DISCRETE_LEVELS[path] ?? DISCRETE_LEVELS.substring;
     for (const id of ids) byId.set(id, level);
   }
-  return { byId, order: [...byId.keys()] };
+  return { path, byId, order: [...byId.keys()] };
 }
 
 /**

package/src/service.js

@@ -560,16 +560,36 @@ export function createService({ store, mirror, config, onWrite, logger, document
    * 用出来的」延伸成检索信号：查询命中的不只有直接挂联，还有跳跃可达的活跃子图。
    * 邻居权重 = HOP_QUOTA[hop] × linked tier（attr 1.0 / relation 0.9），仍低于
    * 直达种子的满权，绝不喧宾夺主。
+   *
+   * #24 块1 补充（三路起点接线）：前半段只喂了 exact 一路，Tag 桥接与向量两路
+   * 能力在 anchoring.js 里却从未被调用。现补齐——
+   *   · exact：查询里出现实体名（布尔 1.0）；
+   *   · tag  ：查询词命中某条记忆的 tag，该记忆挂联的实体即种子（计数级别 0.4）;
+   *   · vector：查询向量近邻的记忆挂联的实体（cos 走 min-max，连续通路）。
+   * 三路在累加前各按自己的尺度归一化（离散级别 vs min-max），混加不会让高频
+   * Tag 淹没强向量命中。两路都是弱信号入口：任一路为空就少一路，全空则
+   * anchorSeeds 返回空、整个图轴让位（与加这两路之前的行为一致）。
+   * 三者共用 graphAnchoringEnabled 一个闸：默认关时仍是逐字节的 #219 单跳轴。
    */
-  function entityRecall(q, limit) {
+  function entityRecall(q, limit, { queryVector = null } = {}) {
     if (config?.entityRecallEnabled !== true) return [];
     try {
       const entities = store.findEntitiesMentionedIn(q);
-      if (!entities.length) return [];
+      // Tag 桥接与向量两路只服务锚定层：关锚定时不查（少两次库读，也守住
+      // 「关档行为逐字节不变」的承诺——见下方 if 分支）。
+      const anchoring = config?.graphAnchoringEnabled === true;
+      const tagEntities = anchoring && typeof store.findEntitiesByTags === "function"
+        ? (() => { try { return store.findEntitiesByTags(q); } catch { return []; } })()
+        : [];
+      // 早退只在**三路全无来源**时才成立。向量路的存在感恰恰在查询里没有实体名
+      // 的时候最大（「数据库迁移」说不出任何实体），若仍以「名字没命中」早退，
+      // 第二、三路就永远等不到自己被调用——接上了也等于没接。
+      const canVector = anchoring && Array.isArray(queryVector) && queryVector.length > 0 && !!vectorIndex;
+      if (!entities.length && !tagEntities.length && !canVector) return [];
       // 关闭锚定级联=逐字节复用 #219 单跳轴：种子裁剪/重排/截断全是 #24 新增的
       // 行为，默认关时一条都不许漏进旧路径（graphSeedCap 也只在开启后生效——
       // 无论 cap 调多小，关档时命中实体仍全量挂联）。
-      if (config?.graphAnchoringEnabled !== true) {
+      if (!anchoring) {
         const linked = store.getLinkedMemoryIds(entities.map((e) => e.id));
         if (!linked.size) return [];
         const hits = [];
@@ -581,9 +601,43 @@ export function createService({ store, mirror, config, onWrite, logger, document
         }
         return hits;
       }
-      // 锚定种子（精确名布尔通路——命名实体逻辑上是离散匹配，不参与 min-max）。
-      const exact = normalizePath(entities.map((e) => e.id), { path: "exact" });
-      const seeds = anchorSeeds({ paths: [exact], cap: config?.graphSeedCap ?? 12 });
+      // 三路激活信号，各自先归一化再累加（尺度不同，混加会让高频通路淹没强相关）。
+      const paths = [];
+      // 第一路：精确名（布尔通路——命名实体逻辑上是离散匹配，不参与 min-max）。
+      if (entities.length) {
+        paths.push(normalizePath(entities.map((e) => e.id), { path: "exact" }));
+      }
+      // 第二路：Tag 桥接（tag 共现，离散级别 0.4——比精确名弱、比子串强）。
+      if (tagEntities.length) {
+        paths.push(normalizePath(tagEntities.map((e) => e.id), { path: "tag" }));
+      }
+      // 第三路：向量（连续通路，cos 相似度走 min-max）。记忆 → 挂联实体反查，
+      // 同一实体被多条近邻记忆挂联时取最高分（一条更近的记忆就够证明相关）。
+      if (Array.isArray(queryVector) && queryVector.length && vectorIndex) {
+        try {
+          const near = vectorIndex.search(queryVector, { limit: limit * 2, threshold: 0 });
+          const bestOf = new Map();
+          for (const m of near) {
+            const score = m?.score ?? 0;
+            if (!(score > 0)) continue;
+            for (const eid of store.entityIdsForMemories([m.id])) {
+              if (!(bestOf.get(eid) >= score)) bestOf.set(eid, score);
+            }
+          }
+          if (bestOf.size) {
+            paths.push(normalizePath(
+              [...bestOf.entries()].map(([id, score]) => ({ id, score })),
+              { path: "vector", continuous: true }
+            ));
+          }
+        } catch { /* 向量路失败只是少一路，不拖垮整条图轴 */ }
+      }
+      if (!paths.length) return [];
+      // 激活分为 0 的种子不算种子：min-max 会把**连续通路里最弱的那条**压成 0，
+      // 可下游给种子挂联记忆的是固定满权 tier（1.0/0.9），不看种子自己的分数。
+      // 留着 0 分种子，等于让「这一路里最不像的那条」以最强的方式把记忆拉进池。
+      // 零分项在 anchorSeeds 里排最后，所以先取 cap 再滤掉不会浪费名额。
+      const seeds = anchorSeeds({ paths, cap: config?.graphSeedCap ?? 12 }).filter((s) => s.score > 0);
       if (!seeds.length) return [];
       // 0-hop 直达：挂联记忆按 tier 定分（attr 1.0 / relation 0.9）——与 #219
       // 单跳轴同分。MAX 语义：同一条记忆被多实体挂联时保留最高分。
@@ -939,6 +993,9 @@ export function createService({ store, mirror, config, onWrite, logger, document
     const keyword = rawKeyword.map((m) => ({ ...m, score: scoreKeyword(m, q), source: "keyword" }));
     const wantVector = mode === "vector" || mode === "hybrid" || (mode === "auto" && !!embedder);
     let vector = [];
+    // #24 块1：查询向量在这里算出来，图轴的向量起点要用同一份——再嵌一次既
+    // 多一次模型调用，也可能拿到不同的向量（本地模型带随机性时）。
+    let vectorQuery = null;
     if (wantVector && embedder) {
       try {
         // Legacy embedders expose embed(query); local ones expose embedSingle.
@@ -947,6 +1004,7 @@ export function createService({ store, mirror, config, onWrite, logger, document
           : embedder.embed.bind(embedder);
         const qv = await embedSingle(q);
         if (qv?.length) {
+          vectorQuery = qv;
           // Adaptive threshold (v0.5.0 1.2): the fetch runs at the loosest
           // branch floor so the head-gap rule can still re-admit the tail;
           // the final cutoff is computed against the fetched score
@@ -980,7 +1038,7 @@ export function createService({ store, mirror, config, onWrite, logger, document
     // mentioned entities pull their linked memories into the pool. Keyword
     // mode stays text-only per the mode contract, so the axis is skipped
     // there even when enabled.
-    const entity = mode === "keyword" ? [] : entityRecall(q, lim);
+    const entity = mode === "keyword" ? [] : entityRecall(q, lim, { queryVector: vectorQuery });
     // Entity axis shares BM25's backfill weight (we = wb) until #217 recall
     // data justifies a distinct entity weight.
 
@@ -1819,7 +1877,7 @@ export function createService({ store, mirror, config, onWrite, logger, document
     // 为空时兜底检索，避免注入路径双倍候选成本。
     if (config?.entityRecallEnabled === true && q) {
       try {
-        const graphHits = entityRecall(q, maxItems * 2);
+        const graphHits = entityRecall(q, maxItems * 2, { queryVector });
         if (graphHits.length) {
           const graphIds = new Set(graphHits.map((m) => m.id));
           candidates = [
@@ -2872,6 +2930,9 @@ export function createService({ store, mirror, config, onWrite, logger, document
     saveRelation: (r) => store.saveRelation(r),
     listEntities: (o) => store.listEntities(o),
     getRelations: (id) => store.getRelations(id),
+    // #24 块4 被动确认的复核出口：列出权重被 bump 抬过的边（gain = 现权 −
+    // 该 source 的初值）。纯读，不动权重——「看哪些边被用出来过」是人的动作。
+    listBoostedRelations: (o) => store.listBoostedRelations(o),
     // v0.7.0 实体热投影：实体热 = 关联记忆 heat 聚合（取 max）。无关联记忆
     // 或 heatEnabled=false 时返回 null；前端据此决定图谱节点大小/明暗。
     entityHeat: (entityId) => {

package/src/store.js

@@ -1647,6 +1647,11 @@ export function createStore(path) {
   // 解析成本可以忽略、又永远够不到那格上限，块数只随包条数线性增长。
   const DELETE_ID_CHUNK = 500;
 
+  // Tag 锚点的 IN 列表分块。比 DELETE_ID_CHUNK 多一层顾虑：那条语句只有一处 IN，
+  // 这条有**三处**（attrs / relations.from / relations.to）共用同一个记忆 id 集合，
+  // 所以单块占用的参数是 3×chunk。取 500 后最坏 1500 个参数，离 32766 仍有二十倍余量。
+  const TAG_ID_CHUNK = 500;
+
   /**
    * 整包退出（车道 C）。删空一个不存在的包是幂等的 0，不是错误——对方点第二次「收起
    * 这个包」与「收起一个从来没导入过的包」都该是这个答案；早退也不 bump generation：
@@ -3712,6 +3717,152 @@ export function createStore(path) {
     return { migrated, invalidated };
   }
 
+  /**
+   * Tag 桥接（issue #24 · 块1 三路起点里的第二路）：查询词命中某些记忆的 tag
+   * 时，那些记忆挂联的实体本身就是「这个查询正在谈的东西」——即使查询里没有
+   * 出现它们的名字。Tag 是 LLM 打的标签，比精确名松，但比向量具体，正好填在
+   * 二者之间。
+   *
+   * 匹配口径与 findEntitiesMentionedIn 对齐（JS 侧 toLowerCase，不受 SQLite
+   * 只折 ASCII 的限制）：把查询按空白与常见中英标点切词，任一词与某个 tag
+   * 全等即算命中（不做子串——tag 通常是短词，子串匹配会让「ai」命中「mail」）。
+   * 只认未归档未遗忘的行：一条已归档记忆的 tag 不该再拉出种子。
+   * 返回 {id, name}，按命中记忆数降序、名称升序（稳定）。
+   */
+  function findEntitiesByTags(text, { limit = 5 } = {}) {
+    const words = String(text ?? "")
+      .toLowerCase()
+      .split(/[\s,，、;；:：!！?？.。()（）[\]【】"'“”‘’/|]+/u)
+      .map((w) => w.trim())
+      .filter((w) => w.length >= 2);
+    if (!words.length) return [];
+    const rows = db.prepare(
+      `SELECT id, tags FROM memories WHERE archived = 0 AND forgotten = 0`
+    ).all();
+    const memHits = new Set();
+    for (const row of rows) {
+      const tags = parseTags(row.tags).map((t) => String(t).toLowerCase());
+      if (!tags.length) continue;
+      if (words.some((w) => tags.includes(w))) memHits.add(row.id);
+    }
+    if (!memHits.size) return [];
+    // 计数必须在 SQL 里做：entityIdsForMemories 返回的是 DISTINCT entity_id，
+    // 拿它反推「命中几条记忆」永远是 1，排序就静默失效了（评审抓到的正是这个）。
+    //
+    // 两个来源都要算：只读 entity_attrs 会漏掉「记忆只通过关系挂到实体上」的情况
+    // ——phaseRelations 只写 entity_relations.memory_id、不建 attr 行，于是仅由关系
+    // 关联的记忆对关系两端一个种子都生不出来。这与 getLinkedMemoryIds 的口径一致
+    // （那边 attr 与 relation 两端同样并列）。UNION 去重的是 (实体, 记忆) 对，
+    // 所以同一条记忆的多条关联记录不会把 via 抬高。
+    //
+    // 分块理由同 DELETE_ID_CHUNK：一条语句一行一个 `?`，撞上 SQLITE_MAX_VARIABLE_NUMBER
+    // （32766）会整笔抛错，而调用方 try/catch 兜底 → 静默丢掉整条 Tag 锚点。
+    // 这里每块绑 3×TAG_ID_CHUNK 个参数（三处 IN 列表），500 仍有二十倍余量。
+    const rowsByEntity = new Map();
+    const memoryIds = [...memHits];
+    for (let offset = 0; offset < memoryIds.length; offset += TAG_ID_CHUNK) {
+      const batch = memoryIds.slice(offset, offset + TAG_ID_CHUNK);
+      const marks = batch.map(() => "?").join(",");
+      const batchRows = db.prepare(
+        `SELECT hits.id AS id, e.name AS name, COUNT(DISTINCT hits.memory_id) AS via
+         FROM (
+           SELECT entity_id AS id, memory_id FROM entity_attrs
+             WHERE memory_id IN (${marks}) AND entity_id IS NOT NULL
+           UNION
+           SELECT from_entity AS id, memory_id FROM entity_relations
+             WHERE memory_id IN (${marks}) AND from_entity IS NOT NULL
+           UNION
+           SELECT to_entity AS id, memory_id FROM entity_relations
+             WHERE memory_id IN (${marks}) AND to_entity IS NOT NULL
+         ) hits JOIN entities e ON e.id = hits.id
+         GROUP BY hits.id`
+      ).all(...batch, ...batch, ...batch);
+      for (const row of batchRows) {
+        const prev = rowsByEntity.get(row.id);
+        // 各块的记忆集合互不相交，所以 via 直接相加就是全集的 DISTINCT 计数。
+        rowsByEntity.set(row.id, { id: row.id, name: row.name, via: (prev?.via ?? 0) + Number(row.via) });
+      }
+    }
+    const rows2 = [...rowsByEntity.values()];
+    if (!rows2.length) return [];
+    return rows2
+      .map((r) => ({ id: r.id, name: r.name, via: r.via }))
+      .sort((a, b) => b.via - a.via || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+      .slice(0, limit)
+      .map(({ id, name }) => ({ id, name }));
+  }
+
+  /**
+   * 按记忆批量反查实体 id（Tag 桥接用）。与 entitiesForMemory 的区别是「批量 +
+   * 带 id」：那边是面板详情页的单条展示（只要 name/type），这边要的是能直接
+   * 喂给 normalizePath 的 id 列表。同一 (记忆, 实体) 只出一次。
+   *
+   * 与 findEntitiesByTags 同口径：attr 行与关系两端并列。只读 entity_attrs 时，
+   * 一条只通过关系挂到实体上的记忆在向量路里也生不出种子（phaseRelations 不建 attr）。
+   */
+  function entityIdsForMemories(memoryIds) {
+    const ids = Array.isArray(memoryIds) ? memoryIds.filter(Boolean) : [];
+    if (!ids.length) return [];
+    const placeholders = ids.map(() => "?").join(",");
+    const rows = db.prepare(
+      `SELECT entity_id FROM entity_attrs
+         WHERE memory_id IN (${placeholders}) AND entity_id IS NOT NULL
+       UNION
+       SELECT from_entity AS entity_id FROM entity_relations
+         WHERE memory_id IN (${placeholders}) AND from_entity IS NOT NULL
+       UNION
+       SELECT to_entity AS entity_id FROM entity_relations
+         WHERE memory_id IN (${placeholders}) AND to_entity IS NOT NULL`
+    ).all(...ids, ...ids, ...ids);
+    return rows.map((r) => r.entity_id);
+  }
+
+  /**
+   * 被动确认的复核出口（issue #24 · 块4）：列出「权重已经被抬过」的边。
+   *
+   * 设计口径：被动确认本身是安静的——正常触达就 bump，不打扰人。要复核的恰恰
+   * 是「抬过的那些」，因为抬升是唯一会改变检索形状的动作。判据不看有没有被
+   * bump 过（那要额外记账），看权重是否高于该 source 的初值：RELATION_SOURCE_
+   * DEFAULTS 是建边时的起点，高出去的部分只能来自 bumpRelationWeight。
+   *
+   * 显式传过 weight 的边（manual 自带权重）会被算成「抬过」，这在语义上没错
+   * ——它确实不是初值——但它是人工意图，所以把 source 一起返回，面板自己决定
+   * 怎么标。整数比较用 gain > 0 而不是 >= 0，防浮点累加的 1e-17 噪声。
+   * 返回按 gain 降序、created_at 降序，附两侧实体名（面板不必再查一遍）。
+   */
+  function listBoostedRelations({ limit = 200, minGain = 0 } = {}) {
+    const { limit: lim } = sanitizePage(limit, 1, 200);
+    const rows = db.prepare(
+      `SELECT r.*, ef.name AS from_name, et.name AS to_name
+       FROM entity_relations r
+       LEFT JOIN entities ef ON ef.id = r.from_entity
+       LEFT JOIN entities et ON et.id = r.to_entity
+       ORDER BY r.weight DESC, r.created_at DESC`
+    ).all();
+    const out = [];
+    for (const row of rows) {
+      const src = row.source ?? "manual";
+      const base = Object.hasOwn(RELATION_SOURCE_DEFAULTS, src)
+        ? RELATION_SOURCE_DEFAULTS[src]
+        : 1.0;
+      const gain = (row.weight ?? 1.0) - base;
+      if (!(gain > minGain)) continue;
+      out.push({
+        ...toRelation(row),
+        from_name: row.from_name ?? null,
+        to_name: row.to_name ?? null,
+        base_weight: base,
+        gain
+      });
+    }
+    // 排序必须在算完 gain 之后做，不能交给 SQL 的 weight DESC：不同 source 的
+    // base 不同，weight 大不等于 gain 大（llm 边 0.95 / gain 0.55 会压过
+    // tag 边 0.90 / gain 0.60）。早先在循环里按 lim 提前 break 时，被截掉的
+    // 恰恰是 gain 更大的边——面板按 limit=100 取数，截断处正是最该看见的那几条。
+    out.sort((a, b) => b.gain - a.gain || String(b.created_at).localeCompare(String(a.created_at)));
+    return out.slice(0, lim);
+  }
+
   /** Relations where the entity appears on either side (from or to). */
   function getRelations(entityId) {
     return db.prepare(
@@ -4202,6 +4353,10 @@ export function createStore(path) {
     entitiesForMemory,
     findMemoriesByAttr,
     findEntitiesMentionedIn,
+    // #24 块1 第二路（Tag 桥接）与块4 复核出口。
+    findEntitiesByTags,
+    entityIdsForMemories,
+    listBoostedRelations,
     getLinkedMemoryIds,
     saveRelation,
     bumpRelationWeight,

package/test/client.test.js

@@ -2611,3 +2611,168 @@ test("memory drawer surfaces distillation provenance, both layers (issue #512)",
   assert.ok(clientSource.includes("/api/dsh-mneme/memory/provenance?id=") && clientSource.includes("setProvenance(null)"),
     "a failed read must clear the block instead of pretending there is no attribution");
 });
+
+// Issue #24 块4：被动确认让「正常触达」自动抬高边的权重——这是唯一会悄悄改变
+// 检索形状的写动作，所以它必须有一个能查的地方，否则「自动确认」与「没人看过的
+// 自动确认」在界面上没有区别。这里锁四件事：
+// ① 复核区读的是那条专用端点，而不是把 ego 的边自己过滤一遍（抬高量 gain 只有
+//    后端知道——它要和来源基线比对，前端手里只有当前 weight）；
+// ② 边侧卡必须同时显示 weight 和 source：只看 weight 会把「tag 边被抬到 0.5」
+//    误读成「比 manual 边弱」，而 0.3→0.5 恰恰是被用出来的证据；
+// ③ 闸关着时要说「闸关着」，而不是显示「还没有边被抬过」——后者让人以为系统
+//    在工作但没数据，前者才说明是开关没开；
+// ③c 空表文案也不能断言「从未抬过权」：端点只列「权重高于其来源基线」的边，
+//    一条人工边以 0.5 建立、被抬到 0.6 仍然低于基线 1.0，它确实被抬过却不在表里。
+//    文案只能描述「当前筛选结果为空」（评审第四轮指出）。
+// ④ 收起时不发请求（默认收起是刻意的：这是审计视角，不是日常视角）。
+test("entity graph surfaces the passive-confirmation review surface (issue #24)", () => {
+  for (const key of [
+    "memory.graph.boosted.title",
+    "memory.graph.boosted.hint",
+    "memory.graph.boosted.empty",
+    "memory.graph.boosted.loadFailed",
+    "memory.graph.boosted.gateOff",
+    "memory.graph.boosted.show",
+    "memory.graph.boosted.hide",
+    "memory.graph.boosted.gain",
+    "memory.graph.weight",
+    "memory.graph.source",
+    "memory.graph.src.manual",
+    "memory.graph.src.confirmed",
+    "memory.graph.src.tag",
+    "memory.graph.src.llm"
+  ]) {
+    const defined = clientSource.split(`"${key}":`).length - 1;
+    assert.equal(defined, 2, `i18n key ${key} must be defined exactly once in zh and once in en (got ${defined})`);
+  }
+
+  // ① 专用端点
+  assert.ok(clientSource.includes("/api/dsh-mneme/semantic/graph/boosted-relations?limit="),
+    "the review surface must read the boosted-relations endpoint");
+
+  // ② 边侧卡：weight 与 source 一起出现，且 source 走字典而不是直接上屏原词
+  assert.ok(clientSource.includes("memory.graph.weight\").replace(\"{w}\""),
+    "the edge side card must render the weight");
+  assert.ok(clientSource.includes("memory.graph.src.${selected.edge.source}"),
+    "the edge side card must localize the source, not print the raw enum");
+
+  // ③ 闸关与空表是两句不同的话。
+  // 断言必须落在「闸关分支之后的那一小段」而不是全文件 contains：gateOff 这个键
+  // 在字典定义里本来就有一次，全文件搜一遍，把渲染处换成 empty 也照样命中——
+  // 本条用例的首版变异自证就是这么翻车的。
+  const gateIdx = clientSource.indexOf("boosted.passiveConfirmEnabled !== true");
+  assert.ok(gateIdx > 0, "the off-gate branch must be driven by the server's passiveConfirmEnabled, not guessed");
+  const gateBranch = clientSource.slice(gateIdx, gateIdx + 700);
+  assert.ok(gateBranch.includes("memory.graph.boosted.gateOff"),
+    "a closed gate must say so instead of looking like an empty table");
+  // 闸关时既有的提升仍然要列出来（评审指出：关掉闸只表示今后不再自动抬，
+  // 隐藏整张表会让人永远没法复核已经发生过的提升）。
+  assert.ok(/off\s*&&\s*h\([^)]*gateOff/.test(gateBranch),
+    "the off-gate notice must be rendered alongside the list, not as a replacement for it");
+  assert.ok(gateBranch.includes("items.length === 0"),
+    "the empty-table copy must be decided by item count, independently of the gate");
+  // 空表提示本身也不能被闸门状态挡住：闸关且一条都没有时，光说「下面列的是此前
+  // 已经抬过的边」却不给任何行，读起来像这一屏坏了（评审第二轮指出）。
+  assert.ok(!/items\.length === 0\s*\?\s*\(!\s*off/.test(gateBranch),
+    "the empty-table copy must render even when the gate is closed");
+  assert.ok(!/off\s*\?[^:]*gateOff[^:]*:\s*\(boosted\.items/.test(gateBranch),
+    "the gate must not short-circuit the list branch");
+
+  // ③c 空表文案只描述「当前筛选为空」，不能断言「从未有边被抬过」：端点按
+  // gain > 0 筛，而 gain 是相对来源基线算的——manual 边 0.5→0.6 涨了，却仍低于
+  // 基线 1.0，不在表里。说「还没抬过」就是事实错误。
+  for (const lang of ["zh", "en"]) {
+    const re = new RegExp(`"memory\\.graph\\.boosted\\.empty": "([^"]*)"`, "g");
+    const all = [...clientSource.matchAll(re)].map((m) => m[1]);
+    assert.equal(all.length, 2, `empty copy must exist in both languages (${lang})`);
+    for (const copy of all) {
+      assert.ok(!/还没|从未|nothing raised|no edge has been raised/i.test(copy),
+        `empty copy must not claim nothing was ever raised: ${copy}`);
+      assert.ok(/筛选|filter|筛选下|只列|only edges/i.test(copy),
+        `empty copy must describe the current filter instead: ${copy}`);
+    }
+  }
+
+  // ③b 加载失败不能被说成「闸关」或「没有数据」——那会把接口故障误导成配置问题
+  const failIdx = clientSource.indexOf("boosted.error === true");
+  assert.ok(failIdx > 0, "the panel must distinguish a failed fetch from a closed gate");
+  assert.ok(clientSource.slice(failIdx, failIdx + 160).includes("memory.graph.boosted.loadFailed"),
+    "a failed fetch must render its own copy");
+
+  // ④ 收起时不取数
+  assert.ok(clientSource.includes("if (boostedOpen) loadBoosted();"),
+    "the review surface must not fetch while collapsed");
+});
+
+// issue #553：`MemoryDrawer` 用了 `provenance` / `setProvenance`，而那句 useState 却落在
+// 同文件的上一个组件 `EntityPanel` 里——于是打开任何一条记忆详情都会在渲染期抛
+// `ReferenceError: provenance is not defined`，整个 renderer 被带走（DSH 直接重启）。
+//
+// 这个形状不是笔误级别的，它躲得过三样东西：
+//   · 眼睛——两个组件隔了三千多行，同名的 useState 看起来完全正常；
+//   · 语法检查——`provenance` 是合法标识符，只是不在作用域里；
+//   · 现有用例——它们读的是源码字符串，从不执行组件。
+// 所以这里不锁某一个名字，而是把**每个组件里「调了 setter 却没有声明」**这件事整体扫一遍，
+// 才对得起「别再有人把 state 放进隔壁组件」这个意图。
+test("every client component declares the setters it calls (issue #553)", () => {
+  // 浏览器/宿主全局，不是 React state，不该被要求声明
+  const GLOBALS = new Set([
+    "setTimeout", "setInterval", "setImmediate", "setAnimationFrame",
+    "setState" // 子组件把 setter 当参数传下去时，形参名会命中，由 params 分支放行
+  ]);
+
+  const lines = clientSource.split("\n");
+  // 组件 = 缩进 4 空格的 function 声明（本文件所有 UI 组件都是这个形状）。
+  // 排除自身名字就叫 `setXxx` 的——那是普通的 setter 函数定义，不是组件
+  // （`openLibrary` / `setOverlayOpen` 就是一对模块级函数，后者调用自身是递归）。
+  const comps = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^    function ([A-Za-z_$][\w$]*)\s*\(([^)]*)\)\s*\{/);
+    if (!m || /^set[A-Z]/.test(m[1])) continue;
+    let end = lines.length;
+    for (let j = i + 1; j < lines.length; j++) {
+      if (/^    function /.test(lines[j]) || /^\s{0,3}(const|let|export|class) /.test(lines[j])) {
+        end = j;
+        break;
+      }
+    }
+    comps.push({ name: m[1], params: m[2], start: i + 1, text: lines.slice(i, end).join("\n") });
+  }
+  assert.ok(comps.length > 50, `expected the component scan to find many components, got ${comps.length}`);
+
+  const offenders = [];
+  // 模块作用域里已经存在同名绑定时不算越界（`openLibrary` 调 `setOverlayOpen` 就是这类：
+  // 后者是模块级的普通函数，不是 React setter，而且函数声明会提升，先调后声明也成立）。
+  // 整个 bundle 包在 `__ModuleLoader__.load({...})` 里，所以「模块顶层」= 缩进正好 4 空格。
+  const moduleScope = new Set();
+  for (const l of lines) {
+    if (!/^    \S/.test(l)) continue;
+    const f = l.match(/^    function\s+([A-Za-z_$][\w$]*)/);
+    if (f) moduleScope.add(f[1]);
+    const c = l.match(/^    (?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/);
+    if (c) moduleScope.add(c[1]);
+  }
+
+  for (const c of comps) {
+    const declared = new Set();
+    // const [x, setX] = ... / const setX = ...
+    for (const m of c.text.matchAll(/const\s*\[[^\]]*?,\s*(set[A-Za-z_$][\w$]*)\s*\]\s*=/g)) declared.add(m[1]);
+    for (const m of c.text.matchAll(/const\s+(set[A-Za-z_$][\w$]*)\s*=/g)) declared.add(m[1]);
+    // 形参：组件自身的、以及体内嵌套函数/箭头函数的形参——
+    // setter 经常这样往下传（`routeSelects(providerKey, modelKey, testState, setTestState, …)`）。
+    for (const m of c.params.matchAll(/(set[A-Za-z_$][\w$]*)/g)) declared.add(m[1]);
+    for (const m of c.text.matchAll(/\(([^()]*)\)\s*(?:=>|\{)/g)) {
+      for (const p of m[1].matchAll(/set[A-Za-z_$][\w$]*/g)) declared.add(p[0]);
+    }
+    // 调用点：setXxx( ——排除 obj.setXxx(
+    for (const m of c.text.matchAll(/(?<![.\w$])(set[A-Z][A-Za-z0-9_$]*)\s*\(/g)) {
+      const name = m[1];
+      if (GLOBALS.has(name) || declared.has(name) || moduleScope.has(name)) continue;
+      offenders.push(`${c.name} (line ${c.start}) calls ${name} without declaring it`);
+    }
+  }
+
+  assert.deepEqual(offenders, [],
+    "a setter must be declared in the component that calls it — a state hook placed in the "
+    + "neighbouring component compiles fine but throws ReferenceError at render time (#553)");
+});