@modusensus/dsh-mneme 0.8.6 → 0.8.8

package/test/document.test.js

@@ -8,7 +8,7 @@ import { mkdtemp, writeFile, rm } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { createStore } from "../src/store.js";
-import { createService } from "../src/service.js";
+import { createService, PINNED_MEMORY_TYPES } from "../src/service.js";
 import { createDocumentRegistrar } from "../src/document.js";
 import { MEMORY_ITEM_SCHEMA } from "../src/tools.js";
 import { TYPE_DECAY_DEFAULTS } from "../src/heat.js";
@@ -30,7 +30,7 @@ async function makeDocDir() {
 }
 
 /** 单元级 registrar：注入假 embedQuery，隔离 vector 档行为。 */
-function makeRegistrar(store, config = {}, embedQuery = async () => null) {
+function makeRegistrar(store, config = {}, embedQuery = async () => null, { pinnedTypes = PINNED_MEMORY_TYPES } = {}) {
   const finalized = [];
   const register = createDocumentRegistrar({
     store,
@@ -42,7 +42,9 @@ function makeRegistrar(store, config = {}, embedQuery = async () => null) {
       ...(Array.isArray(existing?.content_history) ? existing.content_history : [])
     ].slice(0, 20),
     transaction: (fn) => fn(),
-    finalize: (rows) => finalized.push(...rows)
+    finalize: (rows) => finalized.push(...rows),
+    // #275 拍板 5：service.js 注入的 #249 逐字保真池（这里同款注入，保持行为一致）
+    pinnedTypes
   });
   return { register, finalized };
 }
@@ -147,6 +149,152 @@ test("evidence intersection: valid subset kept, unknown dropped + degraded tag,
   }
 });
 
+// ============================ 升格吸收的 evidence 归档（#275 拍板 5，同事务）
+
+// 拍板原文：registerDocument 成功后同一事务把 absorbed 的 evidence 行翻 archived
+// （可恢复、审计全留），带 opt-out；pinned（constraint / preference）永不自动归档；
+// supersede 的 loser 行同样翻 archived（后者本来就是本模块既有行为，这里一并锁住）。
+
+test("absorbed evidence rows are archived with the document; pinned rows are exempt", async () => {
+  const { store, service, close } = makeService({ documentMemoryEnabled: true });
+  const { writeDoc, cleanup } = await makeDocDir();
+  try {
+    const pinned = service.saveWithDedupe({ type: "constraint", title: "C", content: "边界条件" }).memory;
+    const decision = service.saveWithDedupe({ type: "decision", title: "D", content: "一个决定" }).memory;
+    const p = await writeDoc("absorb.md");
+
+    const res = await service.registerDocument({
+      path: p, title: "Absorb", summary: "summary", evidence: [pinned.id, decision.id]
+    });
+
+    assert.equal(res.evidence_kept, 2, "引用本身照旧全留下：doc 行的 evidence 数组是正向链");
+    assert.equal(res.evidence_archived, 1, "只有非 pinned 的那条被动");
+    const after = service.getById(decision.id);
+    assert.equal(after.archived, true, "被吸收的行退出活跃面（「21 行不是 1 行」）");
+    assert.equal(after.content, "一个决定", "只翻标志位：内容与审计全留（可恢复）");
+    assert.equal(service.getById(pinned.id).archived, false, "#249 的逐字保真池，升格不能绕过");
+    assert.equal(store.list().some((m) => m.id === decision.id), false, "默认面不再列出吸收行");
+  } finally {
+    cleanup();
+    close();
+  }
+});
+
+test("archiveEvidence: false（工具侧 keep_evidence_active）保留吸收行的活跃面", async () => {
+  const { service, close } = makeService({ documentMemoryEnabled: true });
+  const { writeDoc, cleanup } = await makeDocDir();
+  try {
+    const d = service.saveWithDedupe({ type: "decision", title: "D", content: "c" }).memory;
+    const res = await service.registerDocument(
+      { path: await writeDoc("optout.md"), title: "OptOut", summary: "s", evidence: [d.id] },
+      { archiveEvidence: false }
+    );
+    assert.equal(res.evidence_kept, 1);
+    assert.equal(res.evidence_archived, 0, "opt-out 时不归档");
+    assert.equal(service.getById(d.id).archived, false);
+  } finally {
+    cleanup();
+    close();
+  }
+});
+
+test("re-registering a document whose evidence was absorbed keeps the references", async () => {
+  // 这条防的是「补丁把常规路径打坏」：吸收行一旦归档，重注册同一份文档（出新版）
+  // 时同一批 evidence 会全落 dropped，进而撞上捏造判据——最常规的路径反而报错。
+  const { service, close } = makeService({ documentMemoryEnabled: true });
+  const { writeDoc, cleanup } = await makeDocDir();
+  try {
+    const d = service.saveWithDedupe({ type: "decision", title: "D", content: "c" }).memory;
+    const p = await writeDoc("ver.md");
+    const first = await service.registerDocument({ path: p, title: "Ver", summary: "v1", evidence: [d.id] });
+    assert.equal(first.evidence_archived, 1);
+
+    const second = await service.registerDocument({ path: p, title: "Ver", summary: "v2", evidence: [d.id] });
+    assert.equal(second.action, "superseded");
+    assert.deepEqual(second.memory.evidence, [d.id], "吸收行仍为它所属的那份文档背书");
+    assert.equal(second.evidence_kept, 1);
+    assert.equal(second.degraded, false, "不误报成捏造证据");
+    // 认回是窄口径的：已归档行只为**吸收它的那份**文档背书。别的文档（新注册、无
+    // 同名目标）拿它当证据，照旧走既有的捏造判据——不因为这条补丁放宽。
+    const other = await writeDoc("other.md");
+    await assert.rejects(
+      () => service.registerDocument({ path: other, title: "Other", summary: "s", evidence: [d.id] }),
+      /fabricated evidence is rejected/
+    );
+  } finally {
+    cleanup();
+    close();
+  }
+});
+
+test("registrar without the pinned pool wiring archives nothing (fail-safe)", async () => {
+  // 拿不到 pinned 集合就不做这一步：宁可少做，也不能把保真池当普通行收走。
+  const store = createStore(":memory:");
+  const { writeDoc, cleanup } = await makeDocDir();
+  try {
+    const d = store.save({ type: "decision", title: "D", content: "c" });
+    const { register } = makeRegistrar(store, { documentMemoryEnabled: true }, async () => null, { pinnedTypes: null });
+    const res = await register({ path: await writeDoc("noset.md"), title: "NoSet", summary: "s", evidence: [d.id] });
+    assert.equal(res.evidence_archived, 0);
+    assert.equal(store.getById(d.id).archived, false);
+  } finally {
+    cleanup();
+    store.close();
+  }
+});
+
+test("自有生命周期的类型不被吸收：document 行保持活跃，同 path 的 supersede 链不断", async () => {
+  // 回归点（单盲审查 H1）：把另一份 document 行当 evidence 时，若照普通行吸收，它会
+  // 被静默归档——走不到 loser 分支（没有 [superseded by] 指针与 content_history），
+  // 而 supersede 探测只看活跃行，于是重注册同 path 会再铸一行、同一个文件留下两行。
+  const { store, service, close } = makeService({ documentMemoryEnabled: true });
+  const { writeDoc, cleanup } = await makeDocDir();
+  try {
+    const pA = await writeDoc("a.md");
+    const docA = (await service.registerDocument({ path: pA, title: "DocA", summary: "v1" })).memory;
+    const docB = await service.registerDocument({
+      path: await writeDoc("b.md"), title: "DocB", summary: "grounded in A", evidence: [docA.id]
+    });
+    assert.equal(docB.evidence_archived, 0, "document 行不参与吸收");
+    assert.equal(service.getById(docA.id).archived, false, "被引用不改变它的活跃状态");
+
+    const again = await service.registerDocument({ path: pA, title: "DocA", summary: "v2" });
+    assert.equal(again.action, "superseded", "指针行仍能被 supersede 探测看到");
+    assert.equal(again.superseded.id, docA.id);
+    assert.ok(again.superseded.content.includes(again.memory.id), "旧行拿到 [superseded by] 指针");
+    assert.equal(store.all().filter((m) => m.doc_path === pA).length, 2, "同一 path 一行新版 + 一行带指针的旧版，没有多余的第三行");
+  } finally {
+    cleanup();
+    close();
+  }
+});
+
+test("自有生命周期的类型不被吸收：summary（dream 总览）保持活跃，不会被当成不存在重铸", async () => {
+  // 回归点：summary 按 source 身份去重（dream 总览）且按注入档位常驻。被吸收归档后
+  // 去重候选集（store.list 默认排除归档）看不到它 → 下一次做梦会再铸一行同源总览。
+  const { service, close } = makeService({ documentMemoryEnabled: true });
+  const { writeDoc, cleanup } = await makeDocDir();
+  try {
+    const digest = service.saveWithDedupe({
+      type: "summary", title: "当前项目状态", content: "resident digest", source: "dream", importance: 5
+    }).memory;
+    const res = await service.registerDocument({
+      path: await writeDoc("with-digest.md"), title: "DocW", summary: "s", evidence: [digest.id]
+    });
+    assert.equal(res.evidence_archived, 0, "summary 不参与吸收");
+    assert.equal(service.getById(digest.id).archived, false);
+
+    const again = service.saveWithDedupe({
+      type: "summary", title: "当前项目状态", content: "resident digest v2", source: "dream", importance: 5
+    });
+    assert.equal(again.action, "merged", "下一次做梦仍认得出这行，不会铸出第二行同源总览");
+    assert.equal(again.memory.id, digest.id);
+  } finally {
+    cleanup();
+    close();
+  }
+});
+
 // ============================================================ supersede 记账（DoD 2）
 
 test("re-registering the same path supersedes: old row archived + traceable, file untouched", async () => {

package/test/dream-failure-backoff.test.js

@@ -0,0 +1,173 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createDreamScheduler } from "../src/dream.js";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+
+// Issue #292：autoDream 同会话内连续失败退避（autoDreamFailureBackoff，opt-in）。
+//
+// 这些用例锁的是「调度器节流语义」，不是实现细节——防的回归是：
+//   ① 退避闸失效/写反 → 恒定失败的模型（#135 空体面）按 dreamMinIntervalMinutes
+//      的固定节奏连发刷配额（#89 只挡了间隔内重试，间隔本身不会变长）；
+//   ② 成功后连败计数不清零 → 模型恢复正常后仍被旧失败拖着重试推迟（巩固变相停摆）；
+//   ③ 30 分钟封顶失效 → 指数无限翻倍，一整天都不再巩固；
+//   ④ 默认关路径被顺手改掉 → 未 opt-in 用户的重试间隔漂移（默认关 = 行为与
+//      现状逐字节一致的承诺）；
+//   ⑤ 0 基数被偷偷补了间隔 → 未配 dreamMinIntervalMinutes 的用户开退避即被限流
+//      （文档口径：基数 0 时本键不自己产生间隔）。
+//
+// 时钟与定时器全部注入（同 test/dream-peak-hours.test.js 的房型）：「失败 → 推迟
+// → 放行」才能被确定性覆盖，也不在 CI 上留真实等待。退避从上次开跑（lastRunAt）
+// 起算：失败 run 本就占用基数间隔（#89 现状，lastRunAt 在开跑时刷新），退避放大
+// 的是同一道闸，不新增状态面。
+function dreamSetup() {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  return { store, service };
+}
+
+function fakeClock(startMs) {
+  let nowMs = startMs;
+  const timers = [];
+  let seq = 1;
+  return {
+    now: () => nowMs,
+    setNow: (v) => { nowMs = v; },
+    timers,
+    setTimeoutFn: (fn, delay) => { const t = { id: seq++, at: nowMs + delay, fn }; timers.push(t); return t.id; },
+    clearTimeoutFn: (id) => { const i = timers.findIndex((t) => t.id === id); if (i >= 0) timers.splice(i, 1); }
+  };
+}
+
+const T0 = new Date(2026, 8, 27, 10, 0, 0, 0).getTime();
+
+/**
+ * 触发一次并等 run 真正落完：断言闸门这次是放行的、恰好挂了一个 delayMs=0 的
+ * 执行定时器，点火后用 setImmediate 冲掉 startRun 的 Promise 链（纯微任务冲刷，
+ * 不留真实等待）。失败路径下 baseline 不刷新，同一份写入可持续触发。
+ */
+async function runOnce(clock, dream, service) {
+  assert.equal(dream.maybeSchedule(service), true, "前置：阈值已过、间隔闸放行");
+  const ts = clock.timers.splice(0);
+  assert.equal(ts.length, 1, "前置：恰好挂了一个执行定时器");
+  ts[0].fn();
+  await new Promise((r) => setImmediate(r));
+}
+
+test("默认关：失败后重试间隔与现状一致（基数，不翻倍）", async () => {
+  const { store, service } = dreamSetup();
+  const clock = fakeClock(T0);
+  let runs = 0;
+  const dream = createDreamScheduler({
+    onRun: async () => { runs++; return { ok: false, error: "llm failed" }; },
+    thresholdCount: 1, thresholdChars: 0, delayMs: 0, minIntervalMs: 100,
+    failureBackoff: false, // 显式默认值：锁「默认关 = 行为逐字节不变」
+    logger: { warn: () => {} },
+    now: clock.now, setTimeoutFn: clock.setTimeoutFn, clearTimeoutFn: clock.clearTimeoutFn
+  });
+  service.saveWithDedupe({ type: "project", title: "a", content: "x" });
+  await runOnce(clock, dream, service); // 失败一次：失败 run 占用基数间隔（#89 现状）
+  assert.equal(runs, 1);
+  clock.setNow(T0 + 50);
+  assert.equal(dream.maybeSchedule(service), false, "基数间隔内照旧跳过");
+  clock.setNow(T0 + 100);
+  assert.equal(dream.maybeSchedule(service), true, "关键：基数间隔一到即放行——不翻倍");
+  store.close();
+});
+
+test("开启：连续失败 2 次 → 第 3 次触发被指数推迟", async () => {
+  const { store, service } = dreamSetup();
+  const clock = fakeClock(T0);
+  let runs = 0;
+  const dream = createDreamScheduler({
+    onRun: async () => { runs++; return { ok: false, error: "empty body" }; },
+    thresholdCount: 1, thresholdChars: 0, delayMs: 0, minIntervalMs: 100,
+    failureBackoff: true,
+    logger: { warn: () => {} },
+    now: clock.now, setTimeoutFn: clock.setTimeoutFn, clearTimeoutFn: clock.clearTimeoutFn
+  });
+  service.saveWithDedupe({ type: "project", title: "a", content: "x" });
+  await runOnce(clock, dream, service); // 败 1：effective = 100 × 2^1 = 200
+  assert.equal(runs, 1);
+  clock.setNow(T0 + 100);
+  assert.equal(dream.maybeSchedule(service), false, "关键：基数到点不放行（现状会在 +100 放行）");
+  clock.setNow(T0 + 200);
+  await runOnce(clock, dream, service); // 败 2：effective = 100 × 2^2 = 400
+  assert.equal(runs, 2);
+  clock.setNow(T0 + 200 + 300);
+  assert.equal(dream.maybeSchedule(service), false, "关键：2 次连败后 400ms 内不放行");
+  clock.setNow(T0 + 200 + 400);
+  assert.equal(dream.maybeSchedule(service), true, "自上次开跑起满 400ms 才放行第 3 次");
+  store.close();
+});
+
+test("成功一次后计数清零、间隔恢复基数", async () => {
+  const { store, service } = dreamSetup();
+  const clock = fakeClock(T0);
+  let failNext = true;
+  const dream = createDreamScheduler({
+    onRun: async () => ({ ok: !failNext }),
+    thresholdCount: 1, thresholdChars: 0, delayMs: 0, minIntervalMs: 100,
+    failureBackoff: true,
+    logger: { warn: () => {} },
+    now: clock.now, setTimeoutFn: clock.setTimeoutFn, clearTimeoutFn: clock.clearTimeoutFn
+  });
+  service.saveWithDedupe({ type: "project", title: "a", content: "x" });
+  await runOnce(clock, dream, service); // 败 1：effective = 200
+  clock.setNow(T0 + 100);
+  assert.equal(dream.maybeSchedule(service), false, "前置：退避确实在挡（基数到点不放行）");
+  clock.setNow(T0 + 200);
+  failNext = false;
+  await runOnce(clock, dream, service); // 成功：连败清零、baseline 刷新为当前库量
+  service.saveWithDedupe({ type: "project", title: "b", content: "y" }); // 补过刷新后的阈值
+  clock.setNow(T0 + 300); // 距上次开跑 +100 = 基数
+  assert.equal(dream.maybeSchedule(service), true, "关键：成功清零后基数即放行（未清零要等 +400）");
+  store.close();
+});
+
+test("cap：连败 10 次 → 推迟量封顶 30 分钟（未封顶需等约 34 小时）", async () => {
+  const { store, service } = dreamSetup();
+  const clock = fakeClock(T0);
+  const BASE = 2 * 60000; // 2 分钟基数：2^10 × 基数 ≈ 34h，30 分钟封顶必被触发
+  let runs = 0;
+  const dream = createDreamScheduler({
+    onRun: async () => { runs++; return { ok: false }; },
+    thresholdCount: 1, thresholdChars: 0, delayMs: 0, minIntervalMs: BASE,
+    failureBackoff: true,
+    logger: { warn: () => {} },
+    now: clock.now, setTimeoutFn: clock.setTimeoutFn, clearTimeoutFn: clock.clearTimeoutFn
+  });
+  service.saveWithDedupe({ type: "project", title: "a", content: "x" });
+  let lastFailAt = T0;
+  for (let i = 1; i <= 10; i++) {
+    if (i > 1) {
+      const wait = Math.min(BASE * 2 ** (i - 1), 30 * 60000); // 与实现同一口径的期望间隔
+      clock.setNow(lastFailAt + wait);
+    }
+    await runOnce(clock, dream, service);
+    lastFailAt = clock.now();
+  }
+  assert.equal(runs, 10);
+  clock.setNow(lastFailAt + 30 * 60000 - 1);
+  assert.equal(dream.maybeSchedule(service), false, "关键：封顶后 30 分钟内仍不放行");
+  clock.setNow(lastFailAt + 30 * 60000);
+  assert.equal(dream.maybeSchedule(service), true, "封顶生效：恰好 30 分钟放行，不再随失败数翻倍");
+  store.close();
+});
+
+test("基数为 0 时退避不自己产生间隔（需先配 dreamMinIntervalMinutes）", async () => {
+  const { store, service } = dreamSetup();
+  const clock = fakeClock(T0);
+  const dream = createDreamScheduler({
+    onRun: async () => ({ ok: false }),
+    thresholdCount: 1, thresholdChars: 0, delayMs: 0, minIntervalMs: 0,
+    failureBackoff: true,
+    logger: { warn: () => {} },
+    now: clock.now, setTimeoutFn: clock.setTimeoutFn, clearTimeoutFn: clock.clearTimeoutFn
+  });
+  service.saveWithDedupe({ type: "project", title: "a", content: "x" });
+  await runOnce(clock, dream, service); // 失败一次
+  clock.setNow(T0);
+  assert.equal(dream.maybeSchedule(service), true, "关键：0 基数无闸可翻倍，开退避也不限流");
+  store.close();
+});

package/test/dream-peak-hours.test.js

@@ -0,0 +1,194 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createDreamScheduler } from "../src/dream.js";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+
+// Issue #239（第 4 项，错峰队列）镜像到巩固：dreamPeakHours / dreamPeakMaxDeferMinutes。
+//
+// 这些用例锁的是「排程语义」，不是实现细节——它们防的回归是：
+//   ① 错峰闸门被写反/失效 → 高峰期又开始做梦（省钱能力静默消失）；
+//   ② 顺延路径把 skip 做成静默 → 用户看到「不再巩固了」却查不出原因；
+//   ③ 顺延没有上限 → 长高峰（如全天）把巩固永久饿死；
+//   ④ 非法时段串被当成「全天高峰」→ 一个笔误把功能整个停掉；
+//   ⑤ dispose 漏清顺延定时器 → 进程关掉后仍触发一次巩固。
+//
+// 时钟与定时器全部注入（同 src/dream/sleep.js 的房型）：排程不绑死真实时钟，
+// 「高峰顺延 → 非高峰补跑」才能被确定性覆盖，也不会在 CI 上留下真实等待。
+function dreamSetup() {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  return { store, service };
+}
+
+/** 本地墙钟时间：用本地时区构造，getHours() 在 ubuntu/windows CI 上都等于入参。 */
+function at(hour, minute = 0) {
+  return new Date(2026, 5, 15, hour, minute, 0, 0).getTime();
+}
+
+function fakeClock(startMs) {
+  let nowMs = startMs;
+  const timers = [];
+  let seq = 1;
+  return {
+    now: () => nowMs,
+    setNow: (v) => { nowMs = v; },
+    timers,
+    setTimeoutFn: (fn, delay) => { const t = { id: seq++, at: nowMs + delay, fn }; timers.push(t); return t.id; },
+    clearTimeoutFn: (id) => { const i = timers.findIndex((t) => t.id === id); if (i >= 0) timers.splice(i, 1); }
+  };
+}
+
+/** 造出「超过阈值」的写入量（thresholdCount=2）。 */
+function fill(service, n = 2) {
+  for (let i = 0; i < n; i++) service.saveWithDedupe({ type: "project", title: `m${i}`, content: "x".repeat(50) });
+}
+
+test("dreamPeakHours: 命中高峰不调模型，登记 skip 审计并顺延", () => {
+  const { store, service } = dreamSetup();
+  const clock = fakeClock(at(10, 0)); // 本地 10:00，落在 09:00-18:00 内
+  let runs = 0;
+  const audits = [];
+  const dream = createDreamScheduler({
+    onRun: async () => { runs++; return { ok: true }; },
+    thresholdCount: 2, thresholdChars: 5000, delayMs: 0,
+    peakHours: "09:00-18:00",
+    peakMaxDeferMinutes: 0, // 不设上限：顺延应落在真正的高峰结束时刻
+    now: clock.now, setTimeoutFn: clock.setTimeoutFn, clearTimeoutFn: clock.clearTimeoutFn,
+    auditPeakSkip: (info) => audits.push(info)
+  });
+  fill(service);
+  assert.equal(dream.maybeSchedule(service), false, "高峰内不排「马上跑」");
+  assert.equal(runs, 0, "高峰内绝不调 LLM");
+  assert.equal(audits.length, 1, "skip 必须留痕，否则「为什么不再巩固」不可观测");
+  assert.equal(audits[0].count, 2, "审计带上窗口里积了多少（阈值继续累积，不是丢弃）");
+  assert.equal(clock.timers.length, 1, "挂了一个顺延定时器");
+  assert.equal(clock.timers[0].at, at(18, 0), "顺延到最近的高峰结束时刻");
+  store.close();
+});
+
+test("dreamPeakHours: 顺延到点后补跑（非高峰真的会跑）", async () => {
+  const { store, service } = dreamSetup();
+  const clock = fakeClock(at(10, 0));
+  let runs = 0;
+  const dream = createDreamScheduler({
+    onRun: async () => { runs++; return { ok: true }; },
+    thresholdCount: 2, thresholdChars: 5000, delayMs: 0,
+    peakHours: "09:00-18:00",
+    now: clock.now, setTimeoutFn: clock.setTimeoutFn, clearTimeoutFn: clock.clearTimeoutFn,
+    auditPeakSkip: () => {}
+  });
+  fill(service);
+  dream.maybeSchedule(service);
+  const deferred = clock.timers[0];
+  clock.setNow(deferred.at); // 走到 18:00
+  await deferred.fn();
+  assert.equal(runs, 1, "出高峰后补跑一次");
+  store.close();
+});
+
+test("dreamPeakHours: 重复触发不叠加顺延定时器", () => {
+  const { store, service } = dreamSetup();
+  const clock = fakeClock(at(10, 0));
+  let audits = 0;
+  const dream = createDreamScheduler({
+    onRun: async () => ({ ok: true }),
+    thresholdCount: 2, thresholdChars: 5000, delayMs: 0,
+    peakHours: "09:00-18:00",
+    now: clock.now, setTimeoutFn: clock.setTimeoutFn, clearTimeoutFn: clock.clearTimeoutFn,
+    auditPeakSkip: () => { audits++; }
+  });
+  fill(service);
+  dream.maybeSchedule(service);
+  dream.maybeSchedule(service); // 顺延期间又来一次写入触发
+  assert.equal(clock.timers.length, 1, "同一时刻只有一个顺延定时器");
+  assert.equal(audits, 1, "不重复刷审计行");
+  store.close();
+});
+
+test("dreamPeakMaxDeferMinutes: 上限截断后到点照跑，长高峰不饿死巩固", async () => {
+  const { store, service } = dreamSetup();
+  const clock = fakeClock(at(10, 0));
+  let runs = 0;
+  const dream = createDreamScheduler({
+    onRun: async () => { runs++; return { ok: true }; },
+    thresholdCount: 2, thresholdChars: 5000, delayMs: 0,
+    peakHours: "00:00-23:59", // 全天高峰：不设上限就会顺延到 23:59
+    peakMaxDeferMinutes: 120,
+    now: clock.now, setTimeoutFn: clock.setTimeoutFn, clearTimeoutFn: clock.clearTimeoutFn,
+    auditPeakSkip: () => {}
+  });
+  fill(service);
+  dream.maybeSchedule(service);
+  const t = clock.timers[0];
+  assert.equal(t.at, at(12, 0), "被上限截断到 120 分钟后（而不是等到 23:59）");
+  clock.setNow(t.at);
+  await t.fn();
+  assert.equal(runs, 1, "截断放行：仍在高峰也照跑，避免无限顺延");
+  store.close();
+});
+
+test("dreamPeakHours: 非法时段串按「未配置」处理（宁可不省，也不能误停）", async () => {
+  const { store, service } = dreamSetup();
+  const clock = fakeClock(at(10, 0));
+  let runs = 0;
+  let audits = 0;
+  const dream = createDreamScheduler({
+    onRun: async () => { runs++; return { ok: true }; },
+    thresholdCount: 2, thresholdChars: 5000, delayMs: 0,
+    peakHours: "10:00-99:00", // 非法：解析失败必须回落成「关闭」
+    now: clock.now, setTimeoutFn: clock.setTimeoutFn, clearTimeoutFn: clock.clearTimeoutFn,
+    auditPeakSkip: () => { audits++; }
+  });
+  fill(service);
+  assert.equal(dream.maybeSchedule(service), true, "非法串 = 未配置 → 走原有触发路径");
+  assert.equal(audits, 0, "不写 skip 审计");
+  const t = clock.timers[0];
+  clock.setNow(t.at);
+  await t.fn();
+  assert.equal(runs, 1, "巩固照常进行");
+  store.close();
+});
+
+test("dreamPeakHours: 非高峰时段不受影响（行为与现状一致）", async () => {
+  const { store, service } = dreamSetup();
+  const clock = fakeClock(at(20, 0)); // 本地 20:00，在 09:00-18:00 之外
+  let runs = 0;
+  const dream = createDreamScheduler({
+    onRun: async () => { runs++; return { ok: true }; },
+    thresholdCount: 2, thresholdChars: 5000, delayMs: 5,
+    peakHours: "09:00-18:00",
+    now: clock.now, setTimeoutFn: clock.setTimeoutFn, clearTimeoutFn: clock.clearTimeoutFn,
+    auditPeakSkip: () => { throw new Error("非高峰不该写 skip 审计"); }
+  });
+  fill(service);
+  assert.equal(dream.maybeSchedule(service), true, "非高峰照常排程");
+  const t = clock.timers[0];
+  assert.equal(t.at, at(20, 0) + 5, "走的是 delayMs 的「马上跑」路径，不是顺延路径");
+  clock.setNow(t.at);
+  await t.fn();
+  assert.equal(runs, 1);
+  store.close();
+});
+
+test("dreamPeakHours: dispose 清掉顺延定时器，进程关闭后不再触发巩固", async () => {
+  const { store, service } = dreamSetup();
+  const clock = fakeClock(at(10, 0));
+  let runs = 0;
+  const dream = createDreamScheduler({
+    onRun: async () => { runs++; return { ok: true }; },
+    thresholdCount: 2, thresholdChars: 5000, delayMs: 0,
+    peakHours: "09:00-18:00",
+    now: clock.now, setTimeoutFn: clock.setTimeoutFn, clearTimeoutFn: clock.clearTimeoutFn,
+    auditPeakSkip: () => {}
+  });
+  fill(service);
+  dream.maybeSchedule(service);
+  const t = clock.timers[0];
+  await dream.dispose();
+  assert.equal(clock.timers.length, 0, "顺延定时器已清");
+  clock.setNow(t.at);
+  await t.fn(); // 模拟「定时器已经进了事件队列，清不掉」的那一帧
+  assert.equal(runs, 0, "disposed 守卫拦住补跑");
+  store.close();
+});

package/test/inject-parent-gate.test.js

@@ -0,0 +1,106 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createInjector } from "../src/inject.js";
+import { createSettings, FEATURE_FLAG_SPEC } from "../src/settings.js";
+import { createTools } from "../src/tools.js";
+import { Config, INJECT_CHILD_FLAGS, applyLightModePreset, injectChildEnabled } from "../src/config.js";
+
+// 回归（issue #249 第二批）：注入形态的父／子开关。
+// 父 = autoInject（既有挂载总闸，默认开）；子项按 #249 §10 的判据分档——是否
+// 引入新的注入时机／新表面／额外成本。只修正既有位的能力说明随父生效，本批
+// 默认值由关翻到开（显式产品决定，见 CHANGELOG）；父关 = 子项一律不生效，
+// 但子项的持久值保留（父关是「不生效」，不是「重置用户配置」）。
+//
+// 能力说明有两个落点：系统提示段住在注入器内（父关时注入器根本不挂载，天然
+// 不生效），工具描述住在注入器之外，是父闸唯一会漏的地方——本文件用真实工具
+// 描述钉住它。
+
+const CHILDREN = Object.values(INJECT_CHILD_FLAGS).flat();
+const GUIDE_TOOLS = ["memory_search", "memory_save"];
+
+function injectorSections(config) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config });
+  const sections = [];
+  const ctx = {
+    systemPrompt: {
+      context() { return () => {}; },
+      section(def) { sections.push(def); return () => {}; }
+    }
+  };
+  createInjector(ctx, service, createSettings(store.db), config);
+  return sections;
+}
+
+function toolDescriptions(config) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const registered = [];
+  const ctx = { tools: { register(def) { registered.push(def); return () => {}; } } };
+  createTools(ctx, service, config, null);
+  return new Map(registered.map((t) => [t.name, t.description]));
+}
+
+test("#249 第二批：解析后的默认配置里能力说明是开的", () => {
+  assert.equal(Config({}).injectGuidanceEnabled, true, "基础档默认开（随父生效）");
+  // 轻量档不因这次翻转多付常驻提示成本：预设把它压回 false。
+  assert.equal(applyLightModePreset({ lightMode: true }).injectGuidanceEnabled, false);
+});
+
+test("#249 第二批：父关时子项在两个落点上都不生效", () => {
+  assert.equal(injectorSections({ autoInject: true, injectGuidanceEnabled: true }).length, 1, "父开 → 注册提示段");
+  assert.equal(injectorSections({ autoInject: false, injectGuidanceEnabled: true }).length, 0, "父关 → 不注册提示段");
+
+  const plain = toolDescriptions({ injectGuidanceEnabled: false });
+  const guided = toolDescriptions({ autoInject: true, injectGuidanceEnabled: true });
+  const gated = toolDescriptions({ autoInject: false, injectGuidanceEnabled: true });
+  for (const name of GUIDE_TOOLS) {
+    assert.notEqual(guided.get(name), plain.get(name), `${name}：子项开 → 描述补了判断指引`);
+    assert.equal(gated.get(name), plain.get(name), `${name}：父关 → 描述逐字节回到未开状态`);
+  }
+});
+
+test("#249 第二批：闸门只认显式关掉的父，子项自己缺省即关", () => {
+  const key = "injectGuidanceEnabled";
+  assert.equal(injectChildEnabled({ [key]: true }, key), true, "父未出现 → 只按子项判");
+  assert.equal(injectChildEnabled({}, key), false, "子项未开");
+  assert.equal(injectChildEnabled({ autoInject: false, [key]: true }, key), false, "父显式关 → 子不生效");
+  assert.equal(injectChildEnabled({ autoInject: false, [key]: false }, key), false);
+});
+
+test("#249 第二批：父关只停用，不改写子项的持久值", () => {
+  const store = createStore(":memory:");
+  const settings = createSettings(store.db);
+  settings.setFeatureFlags({ autoInject: false, injectGuidanceEnabled: true });
+  const stored = settings.getFeatureFlags();
+  assert.equal(stored.autoInject, false);
+  assert.equal(stored.injectGuidanceEnabled, true, "父关不是重置用户配置");
+  assert.equal(injectChildEnabled(stored, "injectGuidanceEnabled"), false, "值留着，当下不生效");
+  settings.setFeatureFlags({ autoInject: true });
+  assert.equal(injectChildEnabled(settings.getFeatureFlags(), "injectGuidanceEnabled"), true, "重开父开关恢复上次选择");
+});
+
+test("#249 第二批：面板的父子关系与后端同源（漏一处就静默消失）", () => {
+  const client = readFileSync(new URL("../lib/client.js", import.meta.url), "utf8");
+  // 渲染点：子项靠 flagRow 展开。只断言「声明与文案出现过」是恒真检查——把
+  // 2236 行改回 g.items.map(boolRow)，子项既不在 group.core 的 items 里、也不经
+  // flagRow 渲染，面板上彻底消失，而字符串断言全绿。这一条才是那道门。
+  assert.ok(/g\.items\.map\(flagRow\)/.test(client), "分组渲染必须走 flagRow，否则子项不渲染");
+  const children = client.match(/const FEATURE_CHILDREN = (\{[^}]*\})/)?.[1] ?? "";
+  assert.ok(children.includes("autoInject"), "面板未声明父开关 autoInject");
+  const core = client.match(/\{ key: "group\.core", items: \[([^\]]*)\]/)?.[1] ?? "";
+  for (const child of CHILDREN) {
+    assert.ok(children.includes(`"${child}"`), `面板 FEATURE_CHILDREN 漏了 ${child}`);
+    assert.ok(!core.includes(`"${child}"`), `${child} 同时在 items 与 FEATURE_CHILDREN 里，会被渲染两次`);
+    // 双语文案：与 test/client.test.js 的路由键同款计数（zh + en 各一份 = 2）。
+    const named = client.split(`"memory.features.${child}"`).length - 1;
+    const hinted = client.split(`"memory.features.${child}.hint"`).length - 1;
+    assert.ok(named >= 2, `${child} 的文案要中英各一份（got ${named}）`);
+    assert.ok(hinted >= 2, `${child} 的提示要中英各一份（got ${hinted}）`);
+    // 白名单：面板给的开关必须真能写进 kv，否则点了只会拿到 400。
+    assert.ok(FEATURE_FLAG_SPEC.booleans.includes(child), `${child} 不在 settings 白名单里`);
+  }
+});