@modusensus/dsh-mneme 0.8.11 → 0.8.13

package/test/baseline-persist.test.js

@@ -0,0 +1,248 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DatabaseSync } from "node:sqlite";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createDreamScheduler } from "../src/dream.js";
+
+// 回归（issue #89 基线半边）：阈值基线 baseline{count,chars} 只活在调度器闭包里，
+// 进程重启归零。库里记忆远多于阈值时，重启后第一条写入（更新类写入同样计入
+// notifyWrite）就让 overBase 成立，绕过阈值开跑一整轮巩固——0.8.11 实测四次重启
+// 分别只新增 6/7/0/8 条记忆（阈值 10 条 / 5000 字符），每轮约 16 万 tokens。
+// #291 只持久化了 lastRunAt（时间闸门那半边），本文件锁另一半：
+//   1. lastDreamBaseline 只认「成功轮落下的完整基线」，按 run_type 隔离；
+//   2. 播种后重启不再绕过阈值——同库同写入的无种子对照组仍触发，锁的正是这个差异；
+//   3. 播种不妨碍阈值正常累积（计数长到 +10 仍然触发）；
+//   4. runDream 成功轮把基线落库并回给调度器（进程内刷新与跨重启播种同一份数字）；
+//   5. 老库两列由幂等迁移补上，存量行认不出基线 → 退回零基线（升级前行为）。
+
+/** 与阈值判定同口径的活跃库规模（测试侧独立实现，避免与被测代码共用一份过滤条件）。 */
+function activeSize(store) {
+  const rows = store.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document");
+  return {
+    count: rows.length,
+    chars: rows.reduce((sum, m) => sum + m.title.length + m.content.length, 0)
+  };
+}
+
+function seedMemories(service, n, tag = "a") {
+  // 标题必须全局唯一：saveWithDedupe 的去重键是 type+title+scope，同名会被合并成
+  // 同一条（条数不增长），「累计到阈值」的断言就会假失败。
+  for (let i = 0; i < n; i++) {
+    service.saveWithDedupe({ type: "history", title: `${tag}-${i}`, content: "x".repeat(300), importance: 3 });
+  }
+}
+
+test("issue#89: store.lastDreamBaseline reads the last baseline-advancing run only", () => {
+  const store = createStore(":memory:");
+  assert.equal(store.lastDreamBaseline(), null, "empty trail → null (never ran)");
+  // 非 ok 轮不推进基线（既有语义）→ 不落这两列，播种端必须无视它
+  store.saveDreamRun({ status: "failed", snapshot_hash: "h0", input_count: 1, receipt: "r0", created_at: "2026-09-30T10:00:00.000Z", run_type: "auto" });
+  assert.equal(store.lastDreamBaseline("auto"), null, "failed run carries no baseline");
+  store.saveDreamRun({ status: "ok", snapshot_hash: "h1", input_count: 1, receipt: "r1", created_at: "2026-09-30T10:01:00.000Z", run_type: "auto", store_count: 4, store_chars: 400 });
+  assert.deepEqual(store.lastDreamBaseline("auto"), { count: 4, chars: 400 });
+  // sleep/organize 的轮次不参与 auto 的阈值判定
+  store.saveDreamRun({ status: "ok", snapshot_hash: "h2", input_count: 1, receipt: "r2", created_at: "2026-09-30T10:02:00.000Z", run_type: "sleep", store_count: 9, store_chars: 900 });
+  assert.deepEqual(store.lastDreamBaseline("auto"), { count: 4, chars: 400 }, "sleep rows are filtered out of the auto baseline");
+  assert.deepEqual(store.lastDreamBaseline("sleep"), { count: 9, chars: 900 });
+  // 半个基线（只有条数没有字符数）写入侧就该拒绝：否则阈值会按 0 字符起算
+  store.saveDreamRun({ status: "ok", snapshot_hash: "h3", input_count: 1, receipt: "r3", created_at: "2026-09-30T10:03:00.000Z", run_type: "auto", store_count: 7 });
+  assert.deepEqual(store.lastDreamBaseline("auto"), { count: 4, chars: 400 }, "half a baseline is not accepted");
+  store.close();
+});
+
+test("issue#89: a seeded baseline survives a restart — the first write no longer bypasses the threshold", async () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  seedMemories(service, 12); // 条数与字符数都远超阈值（12 ≥ 10 条）
+  // 上一进程的成功轮把「当时的库规模」落进审计表，然后进程重启：
+  const size = activeSize(store);
+  store.saveDreamRun({
+    status: "ok", snapshot_hash: "h", input_count: 1, receipt: "r",
+    created_at: new Date(Date.now() - 10).toISOString(), run_type: "auto",
+    store_count: size.count, store_chars: size.chars
+  });
+  const opts = { onRun: async () => ({ ok: false }), thresholdCount: 10, thresholdChars: 5000, delayMs: 0, logger: { warn: () => {} } };
+  const seeded = createDreamScheduler({ ...opts, baselineSeed: store.lastDreamBaseline("auto") });
+  assert.equal(seeded.maybeSchedule(service), false, "seeded baseline blocks the first write after restart");
+  // 对照组：同一个库、同一次写入，没有种子就是被修掉的那个缺陷。若哪天播种被忽略，
+  // 上面那条断言会与这条同真同假——所以两条必须成对存在。
+  const unseeded = createDreamScheduler(opts);
+  assert.equal(unseeded.maybeSchedule(service), true, "without the seed the threshold is bypassed (the defect this test locks)");
+  await unseeded.dispose(); // 清掉 0ms 待跑计时器，别让对照组真开跑
+  store.close();
+});
+
+test("issue#89: a seeded baseline still lets the threshold accumulate", async () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  seedMemories(service, 12);
+  const dream = createDreamScheduler({
+    onRun: async () => ({ ok: false }), thresholdCount: 10, thresholdChars: 5000, delayMs: 0,
+    baselineSeed: activeSize(store), logger: { warn: () => {} }
+  });
+  seedMemories(service, 5, "b");
+  assert.equal(dream.maybeSchedule(service), false, "half the threshold is not enough");
+  seedMemories(service, 5, "c"); // 累计 +10 条
+  assert.equal(dream.maybeSchedule(service), true, "the threshold still fires once the store grew by it");
+  await dream.dispose();
+  store.close();
+});
+
+test("issue#89: the run-reported baseline is what the scheduler keeps (single source of truth)", async () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  seedMemories(service, 12);
+  const reported = { count: 50, chars: 50000 };
+  const dream = createDreamScheduler({
+    onRun: async () => ({ ok: true, baseline: reported }),
+    thresholdCount: 10, thresholdChars: 5000, delayMs: 0, logger: { warn: () => {} }
+  });
+  assert.equal(dream.maybeSchedule(service), true, "no seed yet → the first run is allowed");
+  await new Promise((r) => setTimeout(r, 10)); // 让 run 收尾并刷新基线
+  // 运行后再长 15 条：若调度器改用「现场计算」的基线（12），这里会触发；用 run
+  // 自报的 50 则不触发。这条差异就是「审计行与内存基线同一份数字」的锁。
+  seedMemories(service, 15, "grow");
+  assert.equal(dream.maybeSchedule(service), false, "the persisted-reported baseline governs, not the live store size");
+  await dream.dispose();
+  store.close();
+});
+
+test("issue#89: an ok run persists its post-run store size; a failed run persists none", async () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const a = service.saveWithDedupe({ type: "project", title: "旧1", content: "第一段内容" });
+  const b = service.saveWithDedupe({ type: "project", title: "旧2", content: "第二段内容" });
+  const dream = createDreamScheduler({ thresholdCount: 1, thresholdChars: 0, delayMs: 0, logger: { warn: () => {} } });
+
+  // 失败轮（无路由）：不能留下任何基线——否则重启播种会拿到一个「没推进过」的假基线
+  const failed = await dream.runDream({ llm: { stream: async function* () {} }, logger: { warn: () => {} } }, service, {});
+  assert.equal(failed.ok, false, "no route → failed run");
+  assert.equal(failed.baseline, undefined, "failed run reports no baseline");
+  assert.equal(store.lastDreamBaseline("auto"), null, "failed run persists no baseline");
+
+  // 成功轮：落库的数字 = 本轮结束后的活跃库规模（合并已归档一方，summary 不计入）
+  let calls = 0;
+  const ctx = {
+    llm: {
+      stream: async function* () {
+        calls++;
+        const text = calls === 1
+          ? JSON.stringify([{ action: "merge", ids: [a.memory.id, b.memory.id], title: "合并标题", content: "合并后的内容", importance: 4, keepSource: a.memory.id }])
+          : "记忆库总览摘要文本";
+        yield { type: "text-delta", text };
+        yield { type: "finish", reason: { kind: "ok" } };
+      }
+    },
+    logger: { warn: () => {} }
+  };
+  const ok = await dream.runDream(ctx, service, { dreamProvider: "deepseek", dreamModel: "deepseek-chat" });
+  assert.equal(ok.ok, true, "run with decisions + summary is ok");
+  const expected = activeSize(store);
+  assert.deepEqual(ok.baseline, expected, "the run reports the post-run store size");
+  assert.deepEqual(store.lastDreamBaseline("auto"), expected, "the audit row carries the same numbers");
+  store.close();
+});
+
+test("issue#89: legacy dream_runs gains the baseline columns on open (idempotent ALTER)", () => {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-baseline-migrate-"));
+  const dbPath = join(dir, "legacy.db");
+  try {
+    const legacy = new DatabaseSync(dbPath);
+    legacy.exec(`CREATE TABLE dream_runs (
+      id TEXT PRIMARY KEY, created_at TEXT NOT NULL, status TEXT NOT NULL, error TEXT,
+      provider TEXT, model TEXT, snapshot_hash TEXT NOT NULL, input_count INTEGER NOT NULL,
+      input TEXT, decisions TEXT, outcome TEXT, applied INTEGER NOT NULL DEFAULT 0,
+      summary_stored INTEGER NOT NULL DEFAULT 0, receipt TEXT NOT NULL,
+      policy_epoch INTEGER NOT NULL DEFAULT 0, run_type TEXT NOT NULL DEFAULT 'auto', skipped TEXT
+    );`);
+    legacy.prepare(
+      `INSERT INTO dream_runs (id, created_at, status, snapshot_hash, input_count, applied, summary_stored, receipt)
+       VALUES ('legacy', '2026-09-30T10:00:00.000Z', 'ok', 'h', 1, 0, 0, 'r')`
+    ).run();
+    legacy.close();
+
+    const store = createStore(dbPath);
+    const cols = store.db.prepare("PRAGMA table_info(dream_runs)").all().map((c) => c.name);
+    assert.ok(cols.includes("store_count") && cols.includes("store_chars"), "baseline columns added to legacy db");
+    // 存量行两列皆 NULL：反推不出「那轮结束时库有多大」，认不出就不认——退回零基线
+    assert.equal(store.lastDreamBaseline("auto"), null, "legacy rows carry no baseline");
+    store.close();
+
+    const again = createStore(dbPath); // 二次打开：ALTER 幂等，不抛 duplicate column
+    assert.equal(again.lastDreamBaseline("auto"), null);
+    again.close();
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("issue#89: an unusable seed is treated as no baseline at all", () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  seedMemories(service, 12);
+  const opts = { onRun: async () => ({ ok: false }), thresholdCount: 10, thresholdChars: 5000, delayMs: 0, logger: { warn: () => {} } };
+  // 库里的持久化值可能是老库的 NULL、或手工改坏的库：半个基线（只有条数）若被当成
+  // 「12 条 0 字符」，阈值会按 0 字符起算——比不认还糟。非法种子一律退回零基线。
+  for (const bad of [{ count: 12 }, { chars: 2000 }, { count: -1, chars: 2000 }, { count: 1.5, chars: 10 }, "nope"]) {
+    const sched = createDreamScheduler({ ...opts, baselineSeed: bad });
+    assert.equal(sched.maybeSchedule(service), true, `unusable seed ${JSON.stringify(bad)} falls back to the zero baseline`);
+    sched.dispose();
+  }
+  store.close();
+});
+
+test("issue#89: a failing baseline read never breaks the run nor fakes a baseline", async () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const a = service.saveWithDedupe({ type: "project", title: "旧1", content: "第一段内容" });
+  // finish 阶段读库失败（关库 / IO 故障）：必须不反噬巩固本身（审计行照写），也不
+  // 写一个猜出来的基线（落 NULL → 下次重启退回零基线，而不是拿假基线抬高阈值）。
+  // 故障点在「总览出文本之后」才武装：runDream 前面还要读两次库（候选集与总览输入），
+  // 过早抛错会把整轮打成 failed，验的就不是收尾取证这条路了。
+  const realAll = service.all.bind(service);
+  let armed = false;
+  let calls = 0;
+  service.all = () => {
+    if (armed) throw new Error("store closed");
+    return realAll();
+  };
+  const ctx = {
+    llm: {
+      stream: async function* () {
+        if (calls++ === 0) {
+          yield { type: "text-delta", text: JSON.stringify([{ action: "keep", ids: [a.memory.id] }]) };
+        } else {
+          armed = true;
+          yield { type: "text-delta", text: "记忆库总览摘要文本" };
+        }
+        yield { type: "finish", reason: { kind: "ok" } };
+      }
+    },
+    logger: { warn: () => {} }
+  };
+  const dream = createDreamScheduler({ thresholdCount: 1, thresholdChars: 0, delayMs: 0, logger: { warn: () => {} } });
+  const ok = await dream.runDream(ctx, service, { dreamProvider: "deepseek", dreamModel: "deepseek-chat" });
+  assert.equal(ok.ok, true, "the run still completes when the baseline read fails");
+  assert.equal(ok.baseline, undefined, "no made-up baseline is reported");
+  assert.ok(store.listDreamRuns({ limit: 1 })[0], "the audit row is still written");
+  assert.equal(store.listDreamRuns({ limit: 1 })[0].store_count, undefined, "the audit row carries no baseline");
+  store.close();
+});
+
+// --- CodeRabbit 在 #291 上的同类要求：index.js 的 seed 是单行无分支接线，仓库没有
+// 插件级挂载 harness（apply 需要完整宿主 ctx），改为源码级锁——删掉该注入行即红。
+// import 用 URL 相对本文件解析，不依赖测试进程 CWD。
+const indexSrc = readFileSync(fileURLToPath(new URL("../src/index.js", import.meta.url)), "utf8");
+
+test("issue#89: index.js wires the dream baseline seed from the audit trail", () => {
+  assert.match(
+    indexSrc,
+    /baselineSeed:\s*store\.lastDreamBaseline\("auto"\)/,
+    "dream scheduler must seed its threshold baseline from dream_runs (run_type='auto') — remove this line and the restart-bypass returns"
+  );
+});

package/test/dream.test.js

@@ -1306,3 +1306,78 @@ test("issue#258: dreamSummaryMaxInputs caps summary inputs to the newest N (0 =
   assert.match(overview().content, /整理后 5 条/, "uncapped run covers the whole library");
   store.close();
 });
+
+// --- issue #339 / E8 考卷：merge 护栏（dreamMergeGuard，opt-in）---------------
+// E8 实测巩固损耗里 10/26 条被丢约束已归位 guarded 类型仍被 merge 吃掉——
+// archive 护栏只挡 archive 不挡 merge。开启后被合并对象命中 ARCHIVE_GUARDED_TYPES
+// 的 merge 决策走与 archive 护栏同款通道：skipInvalid 时 skipped、严格时整单拒绝。
+
+test("validateDecisions mergeGuard: guarded-type merge is skipped under skipInvalid", () => {
+  const snap = new Map([
+    ["c1", { id: "c1", type: "constraint", title: "预算", content: "$12,400", importance: 4, archived: false, forgotten: false }],
+    ["c2", { id: "c2", type: "constraint", title: "预算(疑似重复)", content: "$12,450", importance: 4, archived: false, forgotten: false }],
+    ["h1", { id: "h1", type: "history", title: "旧事", content: "内容", importance: 3, archived: false, forgotten: false }],
+    ["h2", { id: "h2", type: "history", title: "旧事(近似)", content: "内容2", importance: 3, archived: false, forgotten: false }]
+  ]);
+  const decisions = [
+    { action: "merge", ids: ["c1", "c2"], keepSource: "c1", title: "预算合并", content: "$12,400 上下", importance: 4 },
+    { action: "merge", ids: ["h1", "h2"], keepSource: "h1", title: "旧事合并", content: "合并内容", importance: 3 }
+  ];
+  const { ok, skipped } = validateDecisions(decisions, snap, { skipInvalid: true, mergeGuard: true });
+  assert.equal(ok, true, "history merge survives, guarded merge skipped");
+  assert.equal(skipped.length, 1);
+  assert.match(skipped[0].error, /dreamMergeGuard/, "skip reason names the guard");
+  assert.match(skipped[0].error, /constraint/, "skip reason names the guarded type");
+  // guarded merge 被 splice 掉，history merge 与两条隐式 keep 存活。
+  assert.deepEqual(decisions.map((d) => d.action), ["merge", "keep", "keep"]);
+  assert.ok(decisions.some((d) => d.action === "keep" && d.ids.includes("c1")), "c1 auto-kept");
+});
+
+test("validateDecisions mergeGuard: strict mode rejects the whole batch", () => {
+  const guardedSnap = new Map([
+    ["g1", { id: "g1", type: "pitfall", title: "坑", content: "内容", importance: 3, archived: false, forgotten: false }],
+    ["g2", { id: "g2", type: "pitfall", title: "坑2", content: "内容2", importance: 3, archived: false, forgotten: false }]
+  ]);
+  const strict = validateDecisions(
+    [{ action: "merge", ids: ["g1", "g2"], keepSource: "g1", title: "t", content: "c" }],
+    guardedSnap,
+    { skipInvalid: false, mergeGuard: true }
+  );
+  assert.equal(strict.ok, false, "strict mode rejects guarded merge");
+  assert.ok(strict.errors.some((e) => /dreamMergeGuard/.test(e)));
+});
+
+test("validateDecisions mergeGuard: non-guarded types unaffected, guard off = legacy behavior", () => {
+  const snap = new Map([
+    ["c1", { id: "c1", type: "constraint", title: "预算", content: "$12,400", importance: 4, archived: false, forgotten: false }],
+    ["c2", { id: "c2", type: "constraint", title: "预算(疑似重复)", content: "$12,450", importance: 4, archived: false, forgotten: false }]
+  ]);
+  const decisions = [{ action: "merge", ids: ["c1", "c2"], keepSource: "c1", title: "预算合并", content: "合并", importance: 4 }];
+  // guard 关 = 现行为（merge 照常通过）。
+  assert.equal(validateDecisions(decisions, snap, { skipInvalid: true }).ok, true);
+  // guard 开但类型非 guarded（history 用 snapshot 默认 type=project 亦非 guarded）。
+  const plainSnap = snapshot(["x", "y"]);
+  assert.equal(
+    validateDecisions(
+      [{ action: "merge", ids: ["x", "y"], keepSource: "x", title: "t", content: "c" }],
+      plainSnap,
+      { skipInvalid: true, mergeGuard: true }
+    ).ok,
+    true,
+    "non-guarded merge passes under guard"
+  );
+});
+
+test("validateDecisions archive guard: long-retention type without duplicate/outdated rationale is skipped (prior gap)", () => {
+  const snap = new Map([
+    ["c", { id: "c", type: "constraint", title: "预算", content: "$12,400", importance: 4, archived: false, forgotten: false }],
+    ["p", { id: "p", type: "project", title: "项目", content: "内容", importance: 3, archived: false, forgotten: false }]
+  ]);
+  const { ok, skipped } = validateDecisions([
+    { action: "archive", ids: ["c"], reason: "keeps the store tidy" },
+    { action: "archive", ids: ["p"], reason: "outdated" }
+  ], snap, { skipInvalid: true });
+  assert.equal(ok, true, "project archive with stale rationale survives");
+  assert.equal(skipped.length, 1, "constraint archive without rationale skipped");
+  assert.match(skipped[0].error, /long-retention type/);
+});

package/test/graph-anchoring.test.js

@@ -0,0 +1,185 @@
+// issue #24 块1 图谱锚定层（graphAnchoringEnabled）测试。
+// 覆盖：默认关=单跳轴行为逐字节不变 / 开=级联扩散邻居挂联记忆进融合池 /
+// 邻居分 = hop 配额 × tier（attr 1.0 > relation 0.9）/ 种子直达分不被邻居覆盖 /
+// 级联深度上界 / graphSeedCap 收敛邻居总量 / 空关系表降级 / lightMode 关闭配置。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { HOP_QUOTA } from "../src/graph/anchoring.js";
+
+function makeService(config = {}) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config });
+  return { store, service };
+}
+
+function putMemory(store, service, { type = "project", title, content, importance = 3 }) {
+  return service.saveWithDedupe({ type, title, content, importance }).memory;
+}
+
+function linkAttr(store, service, { entityName, memory, key = "k", value = "v", type = "technology" }) {
+  let entity = store.findEntityByName(entityName);
+  if (!entity) entity = store.createEntity({ name: entityName, type });
+  store.saveAttr({ entity_id: entity.id, attr_key: key, attr_value: value, memory_id: memory.id });
+  return entity;
+}
+
+function linkRelation(store, { from, to, relType = "related", memoryId, type = "technology" }) {
+  const a = store.findEntityByName(from) ?? store.createEntity({ name: from, type });
+  const b = store.findEntityByName(to) ?? store.createEntity({ name: to, type });
+  store.saveRelation({ from_entity: a.id, to_entity: b.id, relation_type: relType, memory_id: memoryId });
+}
+
+// ============================================================ 默认关（回归红线）
+
+test("graphAnchoringEnabled=false (default): neighbor-linked memory NOT recalled, seed-only preserved", async () => {
+  const { store, service } = makeService({ entityRecallEnabled: true });
+  // 种子实体 PostgreSQL 挂一条记忆；关系边连到 PgBouncer（不挂记忆）。
+  const seedMem = putMemory(store, service, { title: "数据库迁移", content: "主库切换完成" });
+  linkAttr(store, service, { entityName: "PostgreSQL", memory: seedMem, key: "version", value: "16" });
+  // 邻居实体 + 它自己挂的记忆：必须不被默认关猜中。
+  const neighborMem = putMemory(store, service, { title: "连接池笔记", content: "PgBouncer 池调优记录" });
+  const neigh = linkAttr(store, service, { entityName: "PgBouncer", memory: neighborMem, key: "mode", value: "pool" });
+  // 关系：PostgreSQL —uses→ PgBouncer（种子 → 邻居），不直接挂 seedMem。
+  const a = store.findEntityByName("PostgreSQL");
+  linkRelation(store, { from: a.name, to: neigh.name, relType: "uses", memoryId: seedMem.id });
+
+  const rows = await service.searchMemories("PostgreSQL 现状", { mode: "auto" });
+  const ids = rows.map((r) => r.id);
+  assert.ok(ids.includes(seedMem.id), "seed-linked memory present");
+  assert.ok(!ids.includes(neighborMem.id), "neighbor memory absent when anchoring off");
+});
+
+// ============================================================ 开：级联扩散
+
+test("graphAnchoringEnabled=true: neighbor-linked memory joins via cascade, seed keeps full tier score", async () => {
+  const { store, service } = makeService({ entityRecallEnabled: true, graphAnchoringEnabled: true });
+  const seedMem = putMemory(store, service, { title: "数据库迁移", content: "主库切换完成" });
+  linkAttr(store, service, { entityName: "PostgreSQL", memory: seedMem, key: "version", value: "16" });
+  const neighborMem = putMemory(store, service, { title: "连接池笔记", content: "PgBouncer 池调优记录" });
+  const neigh = linkAttr(store, service, { entityName: "PgBouncer", memory: neighborMem, key: "mode", value: "pool" });
+  const a = store.findEntityByName("PostgreSQL");
+  linkRelation(store, { from: a.name, to: neigh.name, relType: "uses", memoryId: seedMem.id });
+
+  // hybrid blend 走加权合算，便于精确断言 entity 轴分（blend: + we·score）。
+  const rows = await service.searchMemories("PostgreSQL 现状", { mode: "hybrid" });
+  const ids = rows.map((r) => r.id);
+  assert.ok(ids.includes(seedMem.id), "seed memory present");
+  assert.ok(ids.includes(neighborMem.id), "neighbor memory present via cascade");
+  // 种子 attr 1.0 × we(0.3) = 0.3；邻居 attr 1.0 × HOP_QUOTA[1](0.5) × we = 0.15。
+  const seedRow = rows.find((r) => r.id === seedMem.id);
+  const nbRow = rows.find((r) => r.id === neighborMem.id);
+  assert.ok(Math.abs(seedRow.score - 0.3) < 1e-9, "seed keeps full tier score");
+  assert.ok(Math.abs(nbRow.score - 0.3 * HOP_QUOTA[1]) < 1e-9, "neighbor hop-weighted");
+});
+
+test("cascade respects hop-quota ordering: 1-hop neighbors score above 2-hop", async () => {
+  const { store, service } = makeService({ entityRecallEnabled: true, graphAnchoringEnabled: true });
+  const seedMem = putMemory(store, service, { title: "根服务", content: "服务 A 上线" });
+  linkAttr(store, service, { entityName: "ServiceA", memory: seedMem, key: "env", value: "prod" });
+  const hop1Mem = putMemory(store, service, { title: "链路一", content: "ServiceB 依赖记录" });
+  const hop2Mem = putMemory(store, service, { title: "链路二", content: "ServiceC 间接关联" });
+  const b = linkAttr(store, service, { entityName: "ServiceB", memory: hop1Mem, key: "tier", value: "edge" });
+  const c = linkAttr(store, service, { entityName: "ServiceC", memory: hop2Mem, key: "tier", value: "leaf" });
+  const a = store.findEntityByName("ServiceA");
+  // A—B 关系（hop1）；B—C 关系（hop2）。
+  linkRelation(store, { from: a.name, to: b.name, relType: "depends", memoryId: hop1Mem.id });
+  linkRelation(store, { from: b.name, to: c.name, relType: "depends", memoryId: hop2Mem.id });
+
+  const rows = await service.searchMemories("ServiceA", { mode: "auto" });
+  const ids = rows.map((r) => r.id);
+  assert.ok(ids.includes(hop1Mem.id) && ids.includes(hop2Mem.id), "both hops recalled");
+  const h1 = rows.find((r) => r.id === hop1Mem.id);
+  const h2 = rows.find((r) => r.id === hop2Mem.id);
+  assert.ok(h1.score > h2.score, `1-hop (${h1.score}) scores above 2-hop (${h2.score})`);
+});
+
+test("empty relation table degrades cleanly (still returns seed memories)", async () => {
+  const { store, service } = makeService({ entityRecallEnabled: true, graphAnchoringEnabled: true });
+  const seedMem = putMemory(store, service, { title: "独立条", content: "单独存在" });
+  linkAttr(store, service, { entityName: "Standalone", memory: seedMem, key: "k", value: "v" });
+  const rows = await service.searchMemories("Standalone", { mode: "auto" });
+  assert.ok(rows.some((r) => r.id === seedMem.id), "seed memory survives with no relations");
+});
+
+// ============================================================ 配置与配额
+
+test("graphSeedCap bounds neighbor expansion (small cap cuts deeper hops)", async () => {
+  const { store, service } = makeService({
+    entityRecallEnabled: true, graphAnchoringEnabled: true, graphSeedCap: 1, graphCascadeDepth: 3
+  });
+  const seedMem = putMemory(store, service, { title: "根", content: "入口" });
+  const hop1Mem = putMemory(store, service, { title: "一层", content: "近邻" });
+  const hop2Mem = putMemory(store, service, { title: "二层", content: "远邻" });
+  const b = linkAttr(store, service, { entityName: "NodeB", memory: hop1Mem, key: "k", value: "v" });
+  const c = linkAttr(store, service, { entityName: "NodeC", memory: hop2Mem, key: "k", value: "v" });
+  const a = store.findEntityByName("入口占位"); // 无；用 NodeA
+  const nodeA = store.createEntity({ name: "NodeA", type: "technology" });
+  store.saveRelation({ from_entity: nodeA.id, to_entity: b.id, relation_type: "x", memory_id: seedMem.id });
+  store.saveRelation({ from_entity: b.id, to_entity: c.id, relation_type: "x", memory_id: hop1Mem.id });
+
+  const rows = await service.searchMemories("NodeA", { mode: "auto" });
+  const ids = rows.map((r) => r.id).sort();
+  // cap=1 → 配额 floor(1*0.5)=0 → max(1,…) 兜底只进 1 个 1-hop；2-hop 进不来。
+  assert.ok(ids.includes(hop1Mem.id), "1-hop fits within cap");
+  assert.ok(!ids.includes(hop2Mem.id), "2-hop cut by small cap");
+});
+
+test("the anchoring pure module is self-checked", () => {
+  // 模块自带 _selfCheck 已在模块加载时断言；这里再锚定导出契约，防重构断链。
+  assert.ok(typeof HOP_QUOTA[1] === "number" && HOP_QUOTA[1] > HOP_QUOTA[2]);
+});
+
+// ---- #24 复审回归（review findings 逐条落锁）--------------------------------
+
+// 关档逐字节复用 #219 单跳轴：graphSeedCap 只在锚定开启后生效。种子裁剪若漏进
+// 关档路径，cap=1 时第二个命中实体整支挂联记忆都会消失——这条专门钉死它。
+test("anchoring off: graphSeedCap does not cap the legacy single-hop axis", async () => {
+  const { store, service } = makeService({ entityRecallEnabled: true, graphSeedCap: 1 });
+  const memA = putMemory(store, service, { title: "迁移记录", content: "主库切换完成" });
+  const memB = putMemory(store, service, { title: "池化记录", content: "连接池调优" });
+  linkAttr(store, service, { entityName: "Alpha", memory: memA, key: "k", value: "v" });
+  linkAttr(store, service, { entityName: "Beta", memory: memB, key: "k", value: "v" });
+
+  const rows = await service.searchMemories("Alpha Beta", { mode: "auto" });
+  const ids = rows.map((r) => r.id);
+  assert.ok(ids.includes(memA.id), "first seed-linked memory present");
+  assert.ok(ids.includes(memB.id), "second seed-linked memory must survive when anchoring is off");
+});
+
+// 级联要真走出 >1 跳：邻接若只带种子那一层，2-hop 实体挂联的记忆根本不进池。
+// 本地图上 2-hop 记忆只经 AnchorC 可达（两条关系行的 memory_id 都留空，堵死
+// 「1-hop 关系行旁路」），所以这条能红着抓回归。
+test("cascade reaches 2 hops (lazy per-node adjacency, deeper hop weighted lower)", async () => {
+  const { store, service } = makeService({
+    entityRecallEnabled: true, graphAnchoringEnabled: true, graphCascadeDepth: 2
+  });
+  const seedMem = putMemory(store, service, { title: "根服务", content: "入口记录" });
+  const hop2Mem = putMemory(store, service, { title: "远环", content: "间接可达" });
+  const a = linkAttr(store, service, { entityName: "AnchorA", memory: seedMem, key: "k", value: "v" });
+  const c = linkAttr(store, service, { entityName: "AnchorC", memory: hop2Mem, key: "k", value: "v" });
+  const b = store.createEntity({ name: "AnchorB", type: "technology" });
+  store.saveRelation({ from_entity: a.id, to_entity: b.id, relation_type: "x" });
+  store.saveRelation({ from_entity: b.id, to_entity: c.id, relation_type: "x" });
+
+  const rows = await service.searchMemories("AnchorA", { mode: "hybrid" });
+  const ids = rows.map((r) => r.id);
+  assert.ok(ids.includes(seedMem.id), "seed memory present");
+  assert.ok(ids.includes(hop2Mem.id), "2-hop linked memory reached via cascade");
+  const h2 = rows.find((r) => r.id === hop2Mem.id);
+  assert.ok(Math.abs(h2.score - 0.3 * HOP_QUOTA[2]) < 1e-9, `2-hop keeps hop-quota weighting, got ${h2.score}`);
+  store.close();
+});
+
+// 邻接查询两个 IN 组都要绑定：关系方向写成 X→种子 时，种子同样应看到 X 是它的
+// 邻居（只绑第一组时这类行整批消失，级联方向性丢失）。
+test("getEntityNeighbors sees both directions of a relation", () => {
+  const store = createStore(":memory:");
+  const a = store.createEntity({ name: "Seed", type: "technology" });
+  const b = store.createEntity({ name: "Other", type: "technology" });
+  store.saveRelation({ from_entity: b.id, to_entity: a.id, relation_type: "x" });
+  const nb = store.getEntityNeighbors([a.id]);
+  assert.deepEqual(nb.get(a.id), [b.id], "seed must see the reverse-direction neighbor");
+  store.close();
+});

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

@@ -0,0 +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();
+});