@modusensus/dsh-mneme 0.8.14 → 0.8.16

package/test/graph-api.test.js

@@ -1,175 +1,175 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { EventEmitter } from "node:events";
-import { createStore } from "../src/store.js";
-import { createService } from "../src/service.js";
-import { createApi } from "../src/api.js";
-import { createSettings } from "../src/settings.js";
-
-// Ego-graph read API (graph panel P1). The routes under test:
-//   GET /api/dsh-mneme/semantic/graph/ego?entity=&depth=&limit=
-//   GET /api/dsh-mneme/semantic/graph/entity-attrs?entity=
-// Both are read-only: they must stay reachable without an apiToken, exactly
-// like list/search/semantic.
-
-class FakeRes extends EventEmitter {
-  constructor() { super(); this.statusCode = 200; this.body = ""; }
-  writeHead(code, headers) { this.statusCode = code; this.headers = headers; return this; }
-  end(text) { this.body = text ?? ""; this.emit("end"); return this; }
-}
-
-function req(path) {
-  const r = new EventEmitter();
-  r.url = path;
-  r.method = "GET";
-  r.headers = {};
-  return r;
-}
-
-function setup(apiToken = "") {
-  const store = createStore(":memory:");
-  const service = createService({ store, mirror: null, config: {} });
-  const settings = createSettings(store.db);
-  const commands = { add: () => {}, remove: () => {}, list: () => [] };
-  const routes = [];
-  const ctx = { webServer: { register(route) { routes.push(route); return () => {}; } } };
-  createApi(ctx, service, settings, commands, null, undefined, apiToken);
-  return { store, service, routes };
-}
-
-function graphRoute(routes, path) {
-  return routes.find((r) => r.path === path);
-}
-
-function buildChain(service, names, linkType = "related_to") {
-  // names → entities; each consecutive pair gets one relation. Returns a
-  // name→entity map so tests can assert on ids.
-  const map = new Map();
-  for (const n of names) map.set(n, service.createEntity({ name: n, type: "concept" }));
-  for (let i = 0; i < names.length - 1; i++) {
-    service.saveRelation({
-      from_entity: map.get(names[i]).id,
-      to_entity: map.get(names[i + 1]).id,
-      relation_type: linkType
-    });
-  }
-  return map;
-}
-
-test("ego route is registered and open without apiToken", async () => {
-  const { routes } = setup("secret-token");
-  const ego = graphRoute(routes, "/api/dsh-mneme/semantic/graph/ego");
-  const attrs = graphRoute(routes, "/api/dsh-mneme/semantic/graph/entity-attrs");
-  assert.ok(ego, "ego route must be registered");
-  assert.ok(attrs, "entity-attrs route must be registered");
-  // read-only: no 401 even with a token configured
-  const res = new FakeRes();
-  await ego.handler(req("/api/dsh-mneme/semantic/graph/ego"), res);
-  assert.equal(res.statusCode, 400, "missing param is a 400, not a 401");
-});
-
-test("ego depth 1 returns root + direct neighbors with distances", async () => {
-  const { routes, service } = setup();
-  const map = buildChain(service, ["A", "B", "C"]);
-  const route = graphRoute(routes, "/api/dsh-mneme/semantic/graph/ego");
-  const res = new FakeRes();
-  await route.handler(req("/api/dsh-mneme/semantic/graph/ego?entity=A&depth=1"), res);
-  assert.equal(res.statusCode, 200);
-  const data = JSON.parse(res.body);
-  assert.equal(data.root.name, "A");
-  assert.equal(data.nodes.length, 2, "root + B only (C is 2 hops)");
-  assert.equal(data.edges.length, 1);
-  const b = data.nodes.find((n) => n.name === "B");
-  assert.equal(b.distance, 1);
-  assert.equal(data.nodes.find((n) => n.name === "A").distance, 0);
-  // edge shape: ids + relation_type, memory_id nullable
-  const edge = data.edges[0];
-  assert.ok(edge.id && edge.from && edge.to);
-  assert.equal(edge.relation_type, "related_to");
-  assert.equal(edge.memory_id, null);
-});
-
-test("ego depth 2 includes 2-hop nodes, not 3-hop", async () => {
-  const { routes, service } = setup();
-  buildChain(service, ["A", "B", "C", "D"]);
-  const route = graphRoute(routes, "/api/dsh-mneme/semantic/graph/ego");
-  const res = new FakeRes();
-  await route.handler(req("/api/dsh-mneme/semantic/graph/ego?entity=A&depth=2"), res);
-  const data = JSON.parse(res.body);
-  const names = data.nodes.map((n) => n.name).sort();
-  assert.deepEqual(names, ["A", "B", "C"], "D is 3 hops away and must be excluded");
-  assert.equal(data.nodes.find((n) => n.name === "C").distance, 2);
-  assert.equal(data.edges.length, 2);
-});
-
-test("ego respects limit and keeps only in-graph edges", async () => {
-  const { routes, service } = setup();
-  const map = buildChain(service, ["A", "B", "C"]);
-  const route = graphRoute(routes, "/api/dsh-mneme/semantic/graph/ego");
-  const res = new FakeRes();
-  await route.handler(req("/api/dsh-mneme/semantic/graph/ego?entity=A&depth=2&limit=2"), res);
-  const data = JSON.parse(res.body);
-  assert.equal(data.nodes.length, 2, "limit caps node count");
-  assert.equal(data.edges.length, 1, "edges to cut nodes are dropped");
-});
-
-test("ego reports 404 for unknown entity and 400 without entity", async () => {
-  const { routes } = setup();
-  const route = graphRoute(routes, "/api/dsh-mneme/semantic/graph/ego");
-  let res = new FakeRes();
-  await route.handler(req("/api/dsh-mneme/semantic/graph/ego?entity=ghost"), res);
-  assert.equal(res.statusCode, 404);
-  assert.equal(JSON.parse(res.body).error, "entity-not-found");
-  res = new FakeRes();
-  await route.handler(req("/api/dsh-mneme/semantic/graph/ego"), res);
-  assert.equal(res.statusCode, 400);
-  assert.equal(JSON.parse(res.body).error, "missing-entity");
-});
-
-test("entity-attrs returns current valid attrs only", async () => {
-  const { routes, service } = setup();
-  const mem = service.saveWithDedupe({ type: "project", title: "t", content: "c" });
-  const entity = service.createEntity({ name: "X", type: "technology" });
-  service.saveAttr({ entity_id: entity.id, attr_key: "version", attr_value: "1", memory_id: mem.id, confidence: 0.9 });
-  // a second save of the same key invalidates the first: only one row stays valid
-  service.saveAttr({ entity_id: entity.id, attr_key: "version", attr_value: "2", memory_id: mem.id, confidence: 0.8 });
-  const route = graphRoute(routes, "/api/dsh-mneme/semantic/graph/entity-attrs");
-  const res = new FakeRes();
-  await route.handler(req("/api/dsh-mneme/semantic/graph/entity-attrs?entity=X"), res);
-  assert.equal(res.statusCode, 200);
-  const data = JSON.parse(res.body);
-  assert.equal(data.entity.name, "X");
-  assert.equal(data.attrs.length, 1);
-  assert.equal(data.attrs[0].value, "2", "latest valid attr wins");
-  assert.equal(data.attrs[0].confidence, 0.8);
-  // unknown / missing entity
-  let r2 = new FakeRes();
-  await route.handler(req("/api/dsh-mneme/semantic/graph/entity-attrs?entity=nope"), r2);
-  assert.equal(r2.statusCode, 404);
-  r2 = new FakeRes();
-  await route.handler(req("/api/dsh-mneme/semantic/graph/entity-attrs"), r2);
-  assert.equal(r2.statusCode, 400);
-});
-
-test("ego 2-hop over 100+ nodes stays under 50ms (spec §7)", async () => {
-  const { routes, service } = setup();
-  // star-of-stars: hub → 20 spokes, each spoke → 5 leaves = 121 nodes, 120 edges
-  const hub = service.createEntity({ name: "hub", type: "project" });
-  for (let i = 0; i < 20; i++) {
-    const spoke = service.createEntity({ name: `spoke-${i}`, type: "technology" });
-    service.saveRelation({ from_entity: hub.id, to_entity: spoke.id, relation_type: "uses" });
-    for (let j = 0; j < 5; j++) {
-      const leaf = service.createEntity({ name: `leaf-${i}-${j}`, type: "concept" });
-      service.saveRelation({ from_entity: spoke.id, to_entity: leaf.id, relation_type: "related_to" });
-    }
-  }
-  const route = graphRoute(routes, "/api/dsh-mneme/semantic/graph/ego");
-  const res = new FakeRes();
-  const start = process.hrtime.bigint();
-  await route.handler(req("/api/dsh-mneme/semantic/graph/ego?entity=hub&depth=2&limit=100"), res);
-  const ms = Number(process.hrtime.bigint() - start) / 1e6;
-  const data = JSON.parse(res.body);
-  assert.equal(data.nodes.length, 100, "limit caps the traversal");
-  assert.ok(data.edges.length > 0);
-  assert.ok(ms < 50, `2-hop query took ${ms.toFixed(1)}ms, spec budget is 50ms`);
-});
+import test from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createApi } from "../src/api.js";
+import { createSettings } from "../src/settings.js";
+
+// Ego-graph read API (graph panel P1). The routes under test:
+//   GET /api/dsh-mneme/semantic/graph/ego?entity=&depth=&limit=
+//   GET /api/dsh-mneme/semantic/graph/entity-attrs?entity=
+// Both are read-only: they must stay reachable without an apiToken, exactly
+// like list/search/semantic.
+
+class FakeRes extends EventEmitter {
+  constructor() { super(); this.statusCode = 200; this.body = ""; }
+  writeHead(code, headers) { this.statusCode = code; this.headers = headers; return this; }
+  end(text) { this.body = text ?? ""; this.emit("end"); return this; }
+}
+
+function req(path) {
+  const r = new EventEmitter();
+  r.url = path;
+  r.method = "GET";
+  r.headers = {};
+  return r;
+}
+
+function setup(apiToken = "") {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const settings = createSettings(store.db);
+  const commands = { add: () => {}, remove: () => {}, list: () => [] };
+  const routes = [];
+  const ctx = { webServer: { register(route) { routes.push(route); return () => {}; } } };
+  createApi(ctx, service, settings, commands, null, undefined, apiToken);
+  return { store, service, routes };
+}
+
+function graphRoute(routes, path) {
+  return routes.find((r) => r.path === path);
+}
+
+function buildChain(service, names, linkType = "related_to") {
+  // names → entities; each consecutive pair gets one relation. Returns a
+  // name→entity map so tests can assert on ids.
+  const map = new Map();
+  for (const n of names) map.set(n, service.createEntity({ name: n, type: "concept" }));
+  for (let i = 0; i < names.length - 1; i++) {
+    service.saveRelation({
+      from_entity: map.get(names[i]).id,
+      to_entity: map.get(names[i + 1]).id,
+      relation_type: linkType
+    });
+  }
+  return map;
+}
+
+test("ego route is registered and open without apiToken", async () => {
+  const { routes } = setup("secret-token");
+  const ego = graphRoute(routes, "/api/dsh-mneme/semantic/graph/ego");
+  const attrs = graphRoute(routes, "/api/dsh-mneme/semantic/graph/entity-attrs");
+  assert.ok(ego, "ego route must be registered");
+  assert.ok(attrs, "entity-attrs route must be registered");
+  // read-only: no 401 even with a token configured
+  const res = new FakeRes();
+  await ego.handler(req("/api/dsh-mneme/semantic/graph/ego"), res);
+  assert.equal(res.statusCode, 400, "missing param is a 400, not a 401");
+});
+
+test("ego depth 1 returns root + direct neighbors with distances", async () => {
+  const { routes, service } = setup();
+  const map = buildChain(service, ["A", "B", "C"]);
+  const route = graphRoute(routes, "/api/dsh-mneme/semantic/graph/ego");
+  const res = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/semantic/graph/ego?entity=A&depth=1"), res);
+  assert.equal(res.statusCode, 200);
+  const data = JSON.parse(res.body);
+  assert.equal(data.root.name, "A");
+  assert.equal(data.nodes.length, 2, "root + B only (C is 2 hops)");
+  assert.equal(data.edges.length, 1);
+  const b = data.nodes.find((n) => n.name === "B");
+  assert.equal(b.distance, 1);
+  assert.equal(data.nodes.find((n) => n.name === "A").distance, 0);
+  // edge shape: ids + relation_type, memory_id nullable
+  const edge = data.edges[0];
+  assert.ok(edge.id && edge.from && edge.to);
+  assert.equal(edge.relation_type, "related_to");
+  assert.equal(edge.memory_id, null);
+});
+
+test("ego depth 2 includes 2-hop nodes, not 3-hop", async () => {
+  const { routes, service } = setup();
+  buildChain(service, ["A", "B", "C", "D"]);
+  const route = graphRoute(routes, "/api/dsh-mneme/semantic/graph/ego");
+  const res = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/semantic/graph/ego?entity=A&depth=2"), res);
+  const data = JSON.parse(res.body);
+  const names = data.nodes.map((n) => n.name).sort();
+  assert.deepEqual(names, ["A", "B", "C"], "D is 3 hops away and must be excluded");
+  assert.equal(data.nodes.find((n) => n.name === "C").distance, 2);
+  assert.equal(data.edges.length, 2);
+});
+
+test("ego respects limit and keeps only in-graph edges", async () => {
+  const { routes, service } = setup();
+  const map = buildChain(service, ["A", "B", "C"]);
+  const route = graphRoute(routes, "/api/dsh-mneme/semantic/graph/ego");
+  const res = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/semantic/graph/ego?entity=A&depth=2&limit=2"), res);
+  const data = JSON.parse(res.body);
+  assert.equal(data.nodes.length, 2, "limit caps node count");
+  assert.equal(data.edges.length, 1, "edges to cut nodes are dropped");
+});
+
+test("ego reports 404 for unknown entity and 400 without entity", async () => {
+  const { routes } = setup();
+  const route = graphRoute(routes, "/api/dsh-mneme/semantic/graph/ego");
+  let res = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/semantic/graph/ego?entity=ghost"), res);
+  assert.equal(res.statusCode, 404);
+  assert.equal(JSON.parse(res.body).error, "entity-not-found");
+  res = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/semantic/graph/ego"), res);
+  assert.equal(res.statusCode, 400);
+  assert.equal(JSON.parse(res.body).error, "missing-entity");
+});
+
+test("entity-attrs returns current valid attrs only", async () => {
+  const { routes, service } = setup();
+  const mem = service.saveWithDedupe({ type: "project", title: "t", content: "c" });
+  const entity = service.createEntity({ name: "X", type: "technology" });
+  service.saveAttr({ entity_id: entity.id, attr_key: "version", attr_value: "1", memory_id: mem.id, confidence: 0.9 });
+  // a second save of the same key invalidates the first: only one row stays valid
+  service.saveAttr({ entity_id: entity.id, attr_key: "version", attr_value: "2", memory_id: mem.id, confidence: 0.8 });
+  const route = graphRoute(routes, "/api/dsh-mneme/semantic/graph/entity-attrs");
+  const res = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/semantic/graph/entity-attrs?entity=X"), res);
+  assert.equal(res.statusCode, 200);
+  const data = JSON.parse(res.body);
+  assert.equal(data.entity.name, "X");
+  assert.equal(data.attrs.length, 1);
+  assert.equal(data.attrs[0].value, "2", "latest valid attr wins");
+  assert.equal(data.attrs[0].confidence, 0.8);
+  // unknown / missing entity
+  let r2 = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/semantic/graph/entity-attrs?entity=nope"), r2);
+  assert.equal(r2.statusCode, 404);
+  r2 = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/semantic/graph/entity-attrs"), r2);
+  assert.equal(r2.statusCode, 400);
+});
+
+test("ego 2-hop over 100+ nodes stays under 50ms (spec §7)", async () => {
+  const { routes, service } = setup();
+  // star-of-stars: hub → 20 spokes, each spoke → 5 leaves = 121 nodes, 120 edges
+  const hub = service.createEntity({ name: "hub", type: "project" });
+  for (let i = 0; i < 20; i++) {
+    const spoke = service.createEntity({ name: `spoke-${i}`, type: "technology" });
+    service.saveRelation({ from_entity: hub.id, to_entity: spoke.id, relation_type: "uses" });
+    for (let j = 0; j < 5; j++) {
+      const leaf = service.createEntity({ name: `leaf-${i}-${j}`, type: "concept" });
+      service.saveRelation({ from_entity: spoke.id, to_entity: leaf.id, relation_type: "related_to" });
+    }
+  }
+  const route = graphRoute(routes, "/api/dsh-mneme/semantic/graph/ego");
+  const res = new FakeRes();
+  const start = process.hrtime.bigint();
+  await route.handler(req("/api/dsh-mneme/semantic/graph/ego?entity=hub&depth=2&limit=100"), res);
+  const ms = Number(process.hrtime.bigint() - start) / 1e6;
+  const data = JSON.parse(res.body);
+  assert.equal(data.nodes.length, 100, "limit caps the traversal");
+  assert.ok(data.edges.length > 0);
+  assert.ok(ms < 50, `2-hop query took ${ms.toFixed(1)}ms, spec budget is 50ms`);
+});

package/test/graph-inject-budget.test.js

@@ -1,104 +1,104 @@
-// issue #24 块3 关联提示防幻觉（graphInjectHint / graphInjectBudget）测试。
-// 覆盖：图候选打标 graphHint / 保守档（默认关）线索行不进注入块 / 开档受独立
-// 预算 graphInjectBudget 约束且不挤占 maxItems / [检索线索] 引导语与线索行文本。
-import test from "node:test";
-import assert from "node:assert/strict";
-import { createStore } from "../src/store.js";
-import { createService } from "../src/service.js";
-import { STR, langOf } from "../src/lang.js";
-
-function setup(config = {}) {
-  const store = createStore(":memory:");
-  const service = createService({ store, mirror: null, config });
-  return { store, service };
-}
-
-function linkEntityMem(store, service, { name, title, content, key = "k", value = "v", type = "technology" }) {
-  const mem = service.saveWithDedupe({ type: "project", title, content, importance: 3 }).memory;
-  let ent = store.findEntityByName(name);
-  if (!ent) ent = store.createEntity({ name, type });
-  store.saveAttr({ entity_id: ent.id, attr_key: key, attr_value: value, memory_id: mem.id });
-  return mem;
-}
-
-test("graphHint candidates are tagged when entityRecallEnabled, and do NOT enter the block by default (conservative)", () => {
-  const { store, service } = setup({ entityRecallEnabled: true, maxInjectedItems: 5 });
-  // 一条与查询无关的普通记忆（避免规则路占用），一条实体挂联记忆。
-  linkEntityMem(store, service, {
-    name: "PostgreSQL", title: "数据库迁移", content: "主库切换完成，复制延迟归零"
-  });
-  service.saveWithDedupe({ type: "decision", title: "无关决策", content: "今天天气不错", importance: 4 });
-  const selected = service.injectCandidates({ maxItems: 5, query: "PostgreSQL" });
-  // 保守档默认 graphInjectHint=false：图线索行被 general 选取跳过——
-  // 候选池里能查到 graphHint 标记，但注入终集会排除它。
-  assert.ok(selected.every((m) => m.graphHint !== true), "conservative: no graph hint rows in the injected set");
-});
-
-test("graphInjectHint=true admits graph hint rows under independent budget", () => {
-  const { store, service } = setup({
-    entityRecallEnabled: true, maxInjectedItems: 5, graphInjectHint: true, graphInjectBudget: 2
-  });
-  // 两条实体挂联记忆（都命中查询实体），一条普通规则记忆。
-  linkEntityMem(store, service, { name: "PostgreSQL", title: "数据库迁移", content: "主库切换完成", key: "k1" });
-  linkEntityMem(store, service, { name: "PostgreSQL", title: "连接池调优", content: "PgBouncer 配置", key: "k2" });
-  service.saveWithDedupe({ type: "decision", title: "无关决策", content: "其他内容", importance: 5 });
-  const selected = service.injectCandidates({ maxItems: 5, query: "PostgreSQL" });
-  const hints = selected.filter((m) => m.graphHint === true);
-  assert.equal(hints.length, 2, "both graph hint rows fit within budget 2");
-  // 普通规则记忆仍在（graph 行不挤占 maxItems 槽）。
-  assert.ok(selected.some((m) => !m.graphHint), "non-graph rows still present");
-  store.close();
-});
-
-test("graphInjectBudget caps graph hint rows even when more match the query", () => {
-  const { store, service } = setup({
-    entityRecallEnabled: true, maxInjectedItems: 10, graphInjectHint: true, graphInjectBudget: 1
-  });
-  // 三条候选实体挂联记忆，预算只有 1。
-  for (const i of [1, 2, 3]) {
-    linkEntityMem(store, service, { name: "PostgreSQL", title: `PG 记录 ${i}`, content: `内容 ${i}`, key: `k${i}` });
-  }
-  const selected = service.injectCandidates({ maxItems: 10 });
-  const hints = selected.filter((m) => m.graphHint === true);
-  assert.ok(hints.length <= 1, `budget 1 caps at 1, got ${hints.length}`);
-  store.close();
-});
-
-test("graphHint=false (default) + entityRecallEnabled returns zero candidate set change (conservative = sorting only)", () => {
-  const { store, service } = setup({ entityRecallEnabled: true, maxInjectedItems: 5 });
-  // 仅实体挂联记忆，保守档下不该有任何候选进块。
-  linkEntityMem(store, service, { name: "PostgreSQL", title: "数据库迁移", content: "主库切换完成" });
-  const selected = service.injectCandidates({ maxItems: 5, query: "PostgreSQL 现状" });
-  assert.equal(selected.filter((m) => m.graphHint).length, 0);
-  store.close();
-});
-
-test("[检索线索] 引导语与线索行文本渲染正确（zh/en 双语）", () => {
-  assert.ok(STR.graphHintHeader.zh.includes("检索线索"));
-  assert.ok(STR.graphHintHeader.zh.includes("非事实断言"));
-  assert.ok(STR.graphHintHeader.en.includes("Retrieval hints"));
-  assert.ok(STR.graphHintHeader.en.toLowerCase().includes("not factual"));
-  const lineZh = STR.graphHintLine.zh("entity", "某某", "内容");
-  assert.ok(lineZh.startsWith("- [线索/entity]"));
-  const lineEn = STR.graphHintLine.en("technology", "Foo", "bar");
-  assert.ok(lineEn.startsWith("- [hint/technology]"));
-});
-
-// ---- 复审回归 ---------------------------------------------------------------
-
-// 保守档（graphInjectHint 关）下线索行不许从 pin 池侧漏进注入块：pin 池取自打标
-// 之后、又不占 maxItems 名额，pin 若不排除 graphHint 行，「图召回 + 约束型记忆」
-// 就会在默认关档下照常进常驻注入文本，把线索开关整个绕过去。
-test("conservative mode: a graph hint row cannot leak in via the pin pool", () => {
-  const { store, service } = setup({ entityRecallEnabled: true, maxInjectedItems: 5, pinnedInjectBudget: 1 });
-  // 约束型记忆 + 命中查询实体：同时是 pin 候选与图线索候选（最坏交叉）。
-  const mem = service.saveWithDedupe({
-    type: "constraint", title: "部署约束", content: "生产环境不许直接改库", importance: 4
-  }).memory;
-  const ent = store.createEntity({ name: "PostgreSQL", type: "technology" });
-  store.saveAttr({ entity_id: ent.id, attr_key: "k", attr_value: "v", memory_id: mem.id });
-
-  const selected = service.injectCandidates({ maxItems: 5, query: "PostgreSQL" });
-  assert.equal(selected.filter((m) => m.graphHint === true).length, 0, "hint rows stay out while graphInjectHint is off");
-  store.close();
+// issue #24 块3 关联提示防幻觉（graphInjectHint / graphInjectBudget）测试。
+// 覆盖：图候选打标 graphHint / 保守档（默认关）线索行不进注入块 / 开档受独立
+// 预算 graphInjectBudget 约束且不挤占 maxItems / [检索线索] 引导语与线索行文本。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { STR, langOf } from "../src/lang.js";
+
+function setup(config = {}) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config });
+  return { store, service };
+}
+
+function linkEntityMem(store, service, { name, title, content, key = "k", value = "v", type = "technology" }) {
+  const mem = service.saveWithDedupe({ type: "project", title, content, importance: 3 }).memory;
+  let ent = store.findEntityByName(name);
+  if (!ent) ent = store.createEntity({ name, type });
+  store.saveAttr({ entity_id: ent.id, attr_key: key, attr_value: value, memory_id: mem.id });
+  return mem;
+}
+
+test("graphHint candidates are tagged when entityRecallEnabled, and do NOT enter the block by default (conservative)", () => {
+  const { store, service } = setup({ entityRecallEnabled: true, maxInjectedItems: 5 });
+  // 一条与查询无关的普通记忆（避免规则路占用），一条实体挂联记忆。
+  linkEntityMem(store, service, {
+    name: "PostgreSQL", title: "数据库迁移", content: "主库切换完成，复制延迟归零"
+  });
+  service.saveWithDedupe({ type: "decision", title: "无关决策", content: "今天天气不错", importance: 4 });
+  const selected = service.injectCandidates({ maxItems: 5, query: "PostgreSQL" });
+  // 保守档默认 graphInjectHint=false：图线索行被 general 选取跳过——
+  // 候选池里能查到 graphHint 标记，但注入终集会排除它。
+  assert.ok(selected.every((m) => m.graphHint !== true), "conservative: no graph hint rows in the injected set");
+});
+
+test("graphInjectHint=true admits graph hint rows under independent budget", () => {
+  const { store, service } = setup({
+    entityRecallEnabled: true, maxInjectedItems: 5, graphInjectHint: true, graphInjectBudget: 2
+  });
+  // 两条实体挂联记忆（都命中查询实体），一条普通规则记忆。
+  linkEntityMem(store, service, { name: "PostgreSQL", title: "数据库迁移", content: "主库切换完成", key: "k1" });
+  linkEntityMem(store, service, { name: "PostgreSQL", title: "连接池调优", content: "PgBouncer 配置", key: "k2" });
+  service.saveWithDedupe({ type: "decision", title: "无关决策", content: "其他内容", importance: 5 });
+  const selected = service.injectCandidates({ maxItems: 5, query: "PostgreSQL" });
+  const hints = selected.filter((m) => m.graphHint === true);
+  assert.equal(hints.length, 2, "both graph hint rows fit within budget 2");
+  // 普通规则记忆仍在（graph 行不挤占 maxItems 槽）。
+  assert.ok(selected.some((m) => !m.graphHint), "non-graph rows still present");
+  store.close();
+});
+
+test("graphInjectBudget caps graph hint rows even when more match the query", () => {
+  const { store, service } = setup({
+    entityRecallEnabled: true, maxInjectedItems: 10, graphInjectHint: true, graphInjectBudget: 1
+  });
+  // 三条候选实体挂联记忆，预算只有 1。
+  for (const i of [1, 2, 3]) {
+    linkEntityMem(store, service, { name: "PostgreSQL", title: `PG 记录 ${i}`, content: `内容 ${i}`, key: `k${i}` });
+  }
+  const selected = service.injectCandidates({ maxItems: 10 });
+  const hints = selected.filter((m) => m.graphHint === true);
+  assert.ok(hints.length <= 1, `budget 1 caps at 1, got ${hints.length}`);
+  store.close();
+});
+
+test("graphHint=false (default) + entityRecallEnabled returns zero candidate set change (conservative = sorting only)", () => {
+  const { store, service } = setup({ entityRecallEnabled: true, maxInjectedItems: 5 });
+  // 仅实体挂联记忆，保守档下不该有任何候选进块。
+  linkEntityMem(store, service, { name: "PostgreSQL", title: "数据库迁移", content: "主库切换完成" });
+  const selected = service.injectCandidates({ maxItems: 5, query: "PostgreSQL 现状" });
+  assert.equal(selected.filter((m) => m.graphHint).length, 0);
+  store.close();
+});
+
+test("[检索线索] 引导语与线索行文本渲染正确（zh/en 双语）", () => {
+  assert.ok(STR.graphHintHeader.zh.includes("检索线索"));
+  assert.ok(STR.graphHintHeader.zh.includes("非事实断言"));
+  assert.ok(STR.graphHintHeader.en.includes("Retrieval hints"));
+  assert.ok(STR.graphHintHeader.en.toLowerCase().includes("not factual"));
+  const lineZh = STR.graphHintLine.zh("entity", "某某", "内容");
+  assert.ok(lineZh.startsWith("- [线索/entity]"));
+  const lineEn = STR.graphHintLine.en("technology", "Foo", "bar");
+  assert.ok(lineEn.startsWith("- [hint/technology]"));
+});
+
+// ---- 复审回归 ---------------------------------------------------------------
+
+// 保守档（graphInjectHint 关）下线索行不许从 pin 池侧漏进注入块：pin 池取自打标
+// 之后、又不占 maxItems 名额，pin 若不排除 graphHint 行，「图召回 + 约束型记忆」
+// 就会在默认关档下照常进常驻注入文本，把线索开关整个绕过去。
+test("conservative mode: a graph hint row cannot leak in via the pin pool", () => {
+  const { store, service } = setup({ entityRecallEnabled: true, maxInjectedItems: 5, pinnedInjectBudget: 1 });
+  // 约束型记忆 + 命中查询实体：同时是 pin 候选与图线索候选（最坏交叉）。
+  const mem = service.saveWithDedupe({
+    type: "constraint", title: "部署约束", content: "生产环境不许直接改库", importance: 4
+  }).memory;
+  const ent = store.createEntity({ name: "PostgreSQL", type: "technology" });
+  store.saveAttr({ entity_id: ent.id, attr_key: "k", attr_value: "v", memory_id: mem.id });
+
+  const selected = service.injectCandidates({ maxItems: 5, query: "PostgreSQL" });
+  assert.equal(selected.filter((m) => m.graphHint === true).length, 0, "hint rows stay out while graphInjectHint is off");
+  store.close();
 });