@modusensus/dsh-mneme 0.8.4 → 0.8.6

package/lib/config.js

@@ -24,6 +24,31 @@ export const Config = z.object({
   // 同一事实 6 小时铸出 28+ 条。阀门交给用户按需拧，升级本身不改行为。
   summarizeMinIntervalMinutes: z.natural().min(0).max(10080).default(0),
   summarizeMaxEntriesPerRun: z.natural().min(0).max(50).default(0),
+  // Issue #239（成本感知级联第一级）：蒸馏前的零 LLM 预判——窗口内可蒸馏文本
+  // 不足此字符数时直接跳过 LLM 调用（0 = 关闭，行为与现状逐字节一致）。判定
+  // 纯规则、无模型参与；被挡下的窗口照常消费游标（否则每个 turn/end 都会重新
+  // 评估同一段短文本），并留一行 status='skipped' 审计，error_message 写明原因
+  // ——「这一窗为什么没蒸馏」必须可观测，否则阀门等于黑盒。
+  summarizeMinWindowChars: z.natural().min(0).max(100000).default(0),
+  // Issue #239（有界检查点）：同一会话最多发起多少次蒸馏（0 = 不限，等同现状）。
+  // 只统计真正发起过 LLM 调用的 run——被预判挡下的窗口不占预算，否则阀门会把
+  // 额度浪费在零成本窗口上。计数是进程内 per-session（与最小间隔闸门同生命
+  // 周期），宿主重启即清零，与 #229 的游标持久化是两件事。
+  summarizeMaxRunsPerSession: z.natural().min(0).max(1000).default(0),
+  // Issue #239（第 4 项，错峰队列）：高峰期蒸馏顺延。空串 = 关闭，行为与现状逐
+  // 字节一致。取值是本地时间的时段列表（逗号分隔，支持跨零点），可带**星期前缀**
+  // （可省；ISO 1=周一…7=周日，也认 mon..sun；省略 = 每天）：
+  //   "09:00-18:00"                      每天 09:00-18:00
+  //   "mon-fri 08:00-12:00,14:00-18:00"  工作日两段（按高峰计费的供应商即此形态）
+  //   "sat,sun 23:00-06:00"              周末跨零点段
+  // 命中高峰时：不调 LLM、不消费游标（窗口继续累积，留到非高峰一次性蒸馏——批量
+  // 比逐轮碎蒸更省），登记一行 status='skipped' / error_message='peak-hours' 审计，
+  // 并按下面的上限择时补跑。任一写法非法则整串按「未配置」处理：排程是省钱
+  // 手段，绝不该因为写错格式把蒸馏停掉。
+  summarizePeakHours: z.string().default(""),
+  // 高峰顺延上限（分钟，0 = 不设上限）：到点仍处高峰就照常跑，避免整天高峰把蒸馏
+  // 饿死。默认 120 分钟。仅在上面的时段串非空时生效。
+  summarizePeakMaxDeferMinutes: z.natural().min(0).max(1440).default(120),
   // 落库前去重档位：off（默认，等同现状）/ title（零成本，仅拦完全同名）/
   // vector（复用已有 embedding 列做同会话语义近邻，无 LLM 调用）。
   summarizeDedupeMode: z.union([z.const("off"), z.const("title"), z.const("vector")]).default("off"),
@@ -47,6 +72,25 @@ export const Config = z.object({
   // 默认 300 = 与既有行为一致。
   injectContentMaxChars: z.natural().min(60).max(4000).default(300),
   importanceThreshold: z.natural().min(1).max(5).default(3),
+  // Issue #239（第 5 项）：注入条数的查询自适应（默认关）。确定性强的话题收缩注入
+  // 条数（减半、下限 1），模糊话题（回指/时间线索，或极短查询）维持
+  // maxInjectedItems 上限——只做**单向收缩**，绝不越过用户配置的上限；判据只看
+  // 查询本身，不做额外检索（先探针检索等于白付一次 fuseRecall）。
+  injectUncertaintyAdaptive: z.boolean().default(false),
+  // #249（第一批）：能力说明——「怎么用记忆」的判断指引。落两个零注入成本的
+  // 位：①`memory_search` / `memory_save` 的工具描述补一句判断指引（工具描述是
+  // 常驻文本，不进每轮上下文）；②一段 order 150 的系统提示段（一次性、同会话
+  // 内不随轮次变化，因此不作废前缀缓存），只讲总则（优先序、何时查、何时写、
+  // 何时 no-op）。默认关：关闭时工具描述与提示段与既有行为逐字节一致。
+  injectGuidanceEnabled: z.boolean().default(false),
+  // #249（第一批）：B1 pin 池预算——约束/偏好类注入条目的独立小上限。约束与
+  // 偏好被静默降级是本议题的立项核心（同类知识与情景日志同池同速率摘要，实测
+  // 一轮压缩后仅保 53%、五轮 10%），故这两类不进相关性竞争、不参与跨轮轮换、
+  // 逐字保真（仅受超大条目的硬顶保护，截断仍带提示）并排在块内排序之前。
+  // 独立预算的意义：pin 不占 maxInjectedItems 名额，不会把当前任务需要的情景
+  // 候选挤出预算（另一种「批量塞历史」）。0（默认）= 关闭，注入块构成与既有
+  // 行为逐字节一致；超出预算的条数在块内如实标注未展示条数，绝不静默。
+  pinnedInjectBudget: z.natural().min(0).max(5).default(0),
   // 编码记忆蒸馏（codingRetrospect，opt-in，默认关）。开启时，turn/end 蒸馏
   // 额外提取三类编码专属记忆：rejected_solution（被否决方案）/ pitfall（踩坑）/
   // constraint（工程约束）。蒸馏上下文为整轮完整对话（用户输入 → 助手思考/回答
@@ -135,6 +179,17 @@ export const Config = z.object({
   ]).default("window"),
   // hybrid 的候选总量上限；0 = 复用 dreamMaxSnapshotSize（不迁移，需要时显式覆盖）。
   dreamCandidateMax: z.natural().min(0).max(5000).default(0),
+  // Issue #258：总览（dream_summarize）独立路由。consolidate 有 dreamMaxSnapshotSize
+  // 窗口、总览原为全库无界——两者对 ctx 的需求差 4 倍以上却强制共用 dream 路由，
+  // dreamProvider 指向小 ctx 模型时总览当场 CONTEXT_WINDOW_EXCEEDED（实测 120,969
+  // tokens > 32,768），指向大 ctx 模型则 consolidate 的卸载收益归零。未配置 = 回落
+  // dream 路由，行为逐字节不变。
+  dreamSummaryProvider: z.string().default("").description("记忆总览（dream_summarize）专用模型服务商，留空用巩固模型。总览输入为全库（或 dreamSummaryMaxInputs 上限），ctx 需求远大于 consolidation，建议大 ctx 模型（issue #258）。"),
+  dreamSummaryModel: z.string().default("").description("记忆总览（dream_summarize）专用模型，留空用巩固模型；总览输入随库增长，建议大 ctx 非思考模型（issue #258）。"),
+  // Issue #258：总览输入条数硬上限。0 = 不设上限（历史行为，库增长可能撑爆小
+  // ctx 模型）；>0 时按 updated_at 倒序保留最新的 N 条（与 consolidate 窗口同一
+  // 排序口径）。总览是常驻叙述而非逐条巩固，限输入只影响口径脚注里的条数。
+  dreamSummaryMaxInputs: z.natural().min(0).max(100000).default(0),
   // hybrid 判"高相似"的阈值；0.85 与 sleep normal 档对齐——两个模块对"高相似"
   // 保持同一个定义。
   dreamCandidateMinSim: z.number().min(0.5).max(0.99).default(0.85),
@@ -145,6 +200,14 @@ export const Config = z.object({
   dreamNarrativeEnabled: z.boolean().default(false),
   // 成簇门槛：共享同一 tag 的记忆 ≥ 此值才合成叙述条。
   dreamNarrativeMinCluster: z.natural().min(2).max(20).default(3),
+  // document 型记忆（#164/#230，opt-in）：agent 产长文档的指针行——注册校验
+  // （文件存在 + 路径合法 + evidence 求交）、摘要 + doc_path 落库、C2 比对
+  // 去重、supersede 记账。全文归 agent，管线零触碰；默认关=行为与此前一致；
+  // lightMode 强制关闭。
+  documentMemoryEnabled: z.boolean().default(false),
+  // document 摘要行的注入预算（#230 拍板）：次优先档内最多注入的 document
+  // 行数，超预算跳过由后续候选补位。只约束注入，不约束检索。
+  documentInjectBudget: z.natural().min(1).max(5).default(2),
   // 隐式 keep（v0.4.4）：LLM 未提及的 snapshot 记忆自动补 {action:"keep"}，
   // 避免"未覆盖即全拒"白白浪费整轮 run。设为 false 时保留旧的严格校验
   // （未覆盖即拒绝整单）。
@@ -185,6 +248,18 @@ export const Config = z.object({
   localEmbedDimension: z.natural().default(512),
   localEmbedDevice: z.union([z.const("cpu"), z.const("gpu")]).default("cpu"),
   localEmbedBatchSize: z.natural().min(1).max(64).default(8),
+  // 本地嵌入的池化方式（**bug 修复，不是新能力**）：BGE 系是按 CLS 池化训练的——
+  // 模型自带的 `1_Pooling/config.json` 明确写着 `pooling_mode_cls_token: true` /
+  // `pooling_mode_mean_tokens: false`，官方 README 也是「select the last hidden state of
+  // the first token」+ L2 normalize；而 transformers.js 的 `feature-extraction` 默认 mean。
+  // ⇒ 此前本地嵌入对 BGE 系一直用错池化：**不报错、只是向量系统性偏差**，检索质量静默受损。
+  // 'auto' = 按模型族判定（BGE → cls，其余 → mean，未受影响的模型行为不变）；也可显式钉住。
+  // ⚠️ 池化决定向量空间，改它会改变 modelHash（见 local-embedder.js），既有索引会被判失配并重建。
+  localEmbedPooling: z.union([
+    z.const("auto"),
+    z.const("cls"),
+    z.const("mean")
+  ]).default("auto"),
 
   // Ollama embedder.
   ollamaBaseUrl: z.string().default("http://localhost:11434"),
@@ -388,6 +463,12 @@ export const Config = z.object({
     z.const("high"),
     z.const("none")
   ]).description("同 dreamReasoningEffort：sleep 各阶段 LLM 的推理档位，未配置 = 自动取模型支持的最低档；显式 'none' = 不发送字段、用服务商自带默认。"),
+  // Issue #257：sleep 冲突/模式两阶段的输出预算（原硬编码 2048）。实测默认档
+  // 每对裁决约 90 token、24 对 2097——2048 恰好压在边界（53 次运行 48 败）；
+  // full 档六分支实测约 290 token/对、24 对 6967，2048 必然截断。默认 8192
+  // 覆盖实测峰值（候选对按「每记忆至多一对」去重，饱和在 ~25 对、不随库无限
+  // 增长）；流式计费按实际用量，不按上限。
+  sleepMaxTokens: z.natural().min(256).max(131072).default(8192).description("sleep 冲突消解与模式发现阶段的 LLM 输出预算上限（token）。原为硬编码 2048，sleepActionSet=full 实测需约 7000 导致裁决被截断而整轮失败；流式计费按实际用量，调大不增加成本。"),
 
   // --- epistemic trust: memory source credibility (v0.4.5) -----------------
   // Distinguish memories by source: observation (measured / witnessed),
@@ -419,11 +500,18 @@ export const Config = z.object({
   }).default({}),
 
   // --- LLM audit trail (Bug8) ------------------------------------------------
-  // Records every background LLM call (autoDream consolidation + summary,
-  // autoSummarize compression) into llm_audit_logs: tokens, duration, status
-  // and which trigger produced it. Failures are recorded as status=error and
-  // never block the feature. retentionDays bounds the table: older rows are
-  // purged on boot.
+  // Records every background LLM call into llm_audit_logs: tokens, duration,
+  // status and which trigger produced it. Failures are recorded as
+  // status='error' and never block the feature. retentionDays bounds the table:
+  // older rows are purged on boot.
+  //
+  // Covered trigger_source values: autoDream (consolidation + summary),
+  // autoSummarize (compression), sleep (conflict + pattern) and entityExtract
+  // (issue #250 — the last two were structurally missing the hook, not a
+  // deliberate narrowing). entityExtract runs on every memory write, so row
+  // growth scales with write volume; retentionDays caps the ceiling but not the
+  // rate. If that turns out too fast, sample by operation_type or give it a
+  // separate retention — do not add a second gate: this flag is the single one.
   llmAudit: z.object({
     enabled: z.boolean().default(true),
     retentionDays: z.natural().min(1).max(3650).default(90)
@@ -481,6 +569,17 @@ export const Config = z.object({
   // recall_runs 滚动清理保留天数。
   recallRetentionDays: z.natural().min(1).max(3650).default(90),
 
+  // --- tool exposure: 慢模型/轻量模型的工具往返节流（v0.8.5）----------------
+  // 跨会话记忆已由 inject.js 每轮自动注入系统提示词，memory_search 只用于
+  // 「注入里没有、需要深挖」的补充检索；memory_archive 是隐藏/恢复条目的整理
+  // 操作，正常会话里很少需要。轻量模型对「何时该用工具」判断弱，容易每轮
+  // 顺手调一遍——每次工具调用都是一次串行往返（生成参数→执行→回填→再生成），
+  // 在慢模型上会被放大成明显卡顿。这两个开关允许直接隐藏对应工具（默认全
+  // 开=行为不变），隐藏后模型根本看不到它，也就不会调。也走 feature_flags
+  // 白名单，面板可启停=线上回滚开关。
+  disableMemorySearch: z.boolean().default(false),
+  disableMemoryArchive: z.boolean().default(false),
+
   // --- scope: v0.8.0 A1 存储层（issue #17）--------------------------------
   // 总开关默认关：关闭时写入不标注 scope、去重维持 (type, title) 现状，行为
   // 逐字节不变。开启后 memory_save 写入 agent_scope（session header 的
@@ -515,6 +614,8 @@ const LIGHT_MODE_OFF = [
   "entityRecallEnabled",
   // 轻量模式不开叙述条（额外 LLM 调用；#164 对齐，opt-in）。
   "dreamNarrativeEnabled",
+  // 轻量模式不开 document 指针行（#230，opt-in：注册/注入/检索增强全随闸）。
+  "documentMemoryEnabled",
   // 轻量模式不开热计算（heat 属于重型增强；关掉后 sleep 降级也退回纯时间分层）。
   "heatEnabled"
 ];

package/lib/document.js

@@ -0,0 +1,221 @@
+// dsh-mneme/src/document.js
+// document 型记忆注册（issue #230，口径基线 = #164 设计稿评审线）：agent 产
+// 长文档的指针行铸造口。写入权分离——全文归 agent（管线对文件零读零写零改），
+// 管线只做四件事：注册校验（文件存在 + 路径合法 + evidence 求交）、摘要 +
+// doc_path 落库（库里只存这三样）、C2 vector 档比对去重、supersede 记账
+// （出新版 = 新摘要行 supersede 旧行，旧文件不删，content_history 可追溯）。
+//
+// 独立成模块（AGENTS.md 尺寸约定，同 recallStats 先例）：service.js 已过
+// 2000 行参考线，这里只依赖注入 service 内部件，barrel 出口在 service.js，
+// 调用方零改动。防绕过三层兜底：service 两条业务守卫（saveWithDedupe /
+// updateMemory）+ 存储层唯一铸造口（store.saveDocument，通用 save/update/
+// CAS 整类拒绝 document）——注册是唯一铸造口。
+
+import { statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+import { scopeKeyOf } from "./scope.js";
+import { cosineSimilarity } from "./dream/clustering.js";
+
+// C2 vector 档阈值（#164 拍板 0.92，与 findSessionDuplicate 的 vector 档同源）。
+// 刻意不做 24h 时间窗：那个窗是会话去重的「近邻界」（findSessionDuplicate 注释），
+// 不是相似度语义本身；document 版本更新天然跨天/跨周，套窗会把一周后重注册的
+// 新版判成「无近重复」，留下两行活跃摘要漂移——supersede 探测必须全时段。
+const DOCUMENT_MIN_SIM = 0.92;
+const CANDIDATE_LIMIT = 200;
+
+// 追加到被取代行正文的指针注记。刻意不带语言分支：id 是跨语言稳定键（用户
+// 对 tag/章节名建议用英文同理——指针性内容不翻译）；可追溯链 = 注记里的新行
+// id + 旧行 content_history 里的旧摘要（source=superseded）。
+const supersededByPointer = (id) => `\n\n[superseded by ${id}]`;
+
+/**
+ * Build the document registrar. Injected deps are service.js closure members
+ * (store / embedQuery / transaction / finalize) so this module stays free of
+ * service-internal wiring; `finalize` is the single write epilogue (mirror
+ * sync + notify + re-embed) so callers never duplicate it.
+ *
+ * @returns {(payload: object) => Promise<object>}
+ *   `{ action: "created"|"superseded", memory, superseded?, evidence_kept,
+ *      evidence_dropped, degraded }`
+ * @throws flag 关 / 路径非法或文件缺失 / title 或 summary 为空 / evidence 全部
+ *   捏造 / 仅 vector 近重复（疑似重复外档，交 agent 裁决而不是静默二选一）。
+ */
+export function createDocumentRegistrar({ store, config, embedQuery, pushContentHistory, transaction, finalize }) {
+  return async function registerDocument(payload, { hiddenEvidenceIds = [] } = {}) {
+    // opt-in 总闸（#230 对齐 #228 形态）：关 = 注册入口整体不存在，错误信息
+    // 指回配置键，agent 能准确转告用户去开。
+    if (config?.documentMemoryEnabled !== true) {
+      throw new Error("document memory is disabled (documentMemoryEnabled)");
+    }
+
+    // --- 1. 路径合法 + 文件存在 --------------------------------------------
+    // 只认展开 ~ 后的绝对路径：相对路径依赖进程 cwd，注册时的 cwd 与读取时
+    // 的 cwd 不保证一致，指针必须自带完整定位。校验存在 + 常规文件 + 非空——
+    // 空文件/被截断成 0 字节是「文字结构意外破坏」的最早信号，注册时拦住
+    // 而不是落一条死指针（回退路径：agent 修好文件后重注册，同 path/title
+    // 自动 supersede 旧行）。
+    const rawPath = String(payload?.path ?? "").trim();
+    if (!rawPath) throw new Error("registerDocument: path is required");
+    // 只展开 ~ / ~/（~user 形式拒收为普通相对路径走 isAbsolute 拦截——不猜测
+    // 其他用户的 home，错展开比报错更糟）。
+    const isTilde = rawPath === "~" || rawPath.startsWith("~/") || rawPath.startsWith("~\\");
+    const absolute = isTilde ? resolve(homedir(), rawPath.slice(2)) : rawPath;
+    if (!isAbsolute(absolute)) {
+      throw new Error(`registerDocument: path must be absolute (got "${rawPath}")`);
+    }
+    // 所有绝对路径统一 resolve 归一化（. / .. / 重复分隔符）——归一化不做的话，
+    // D:\a\.\b.md 与 D:\a\b.md 会被判成两个路径，同文件绕过 same-path
+    // supersede，留下双活跃指针。realpathSync 刻意不用：符号链接合并会改写
+    // agent 提交的路径字面量，指针的可读性比追符号链更重要。
+    const expanded = resolve(absolute);
+    let stat = null;
+    try { stat = statSync(expanded); } catch { /* missing/unreadable → null */ }
+    if (!stat?.isFile() || stat.size <= 0) {
+      throw new Error(`registerDocument: document file not found or empty: ${expanded}`);
+    }
+
+    // --- 2. evidence 求交（sleep.js 扫描集求交同款语义）---------------------
+    // 引用的原子条必须真实存在且未归档（归档行已被降级，不再为新鲜 document
+    // 背书）。红线 4 宽容形态：合法子集落库 + evidence_degraded 系统标记；
+    // 提供了 evidence 但全军覆没 = 捏造信号，整单拒绝，agent 修正后重试。
+    const wanted = [...new Set(
+      (Array.isArray(payload?.evidence) ? payload.evidence : [])
+        .map((id) => String(id ?? "").trim())
+        .filter(Boolean)
+    )];
+    // strictScope（tools 层传入，#170 复核项 4 同款）：调用者 scope 看不见的
+    // 行按「不存在」处理——不得为跨 scope id 建立引用（存在性泄漏），与
+    // unknown/archived 同落 dropped，evidence_kept/dropped 计数保持诚实。
+    const hidden = new Set((Array.isArray(hiddenEvidenceIds) ? hiddenEvidenceIds : []).map((id) => String(id)));
+    const kept = [];
+    const dropped = [];
+    for (const id of wanted) {
+      const row = hidden.has(id) ? null : store.getById(id);
+      (row && !row.archived ? kept : dropped).push(id);
+    }
+    if (wanted.length > 0 && kept.length === 0) {
+      throw new Error(
+        `registerDocument: all ${wanted.length} evidence ids are unknown, archived or out of scope — fabricated evidence is rejected`
+      );
+    }
+
+    const title = String(payload?.title ?? "").trim();
+    if (!title) throw new Error("registerDocument: title is required");
+    const summary = String(payload?.summary ?? "").trim();
+    if (!summary) throw new Error("registerDocument: summary is required");
+
+    // --- 3. supersede 目标探测（三层）---------------------------------------
+    // 同 doc_path / 同标题 = agent 显式的「出新版」意图 → supersede；仅 vector
+    // 近重复而路径标题都不同 = 疑似重复外档 → 拒绝并指路。C2×C1 硬线：比对
+    // 不得越过矛盾裁决替 agent 二选一——改既有行还是归档后重注册，判断权留在
+    // agent 手里。去重键带 scope（scopeKeyOf）：跨作用域永不互判（防泄漏，与
+    // saveWithDedupe 的 scopeMatches 同口径）。
+    const scopeMatches = (m) =>
+      scopeKeyOf(m.agent_scope) === scopeKeyOf(payload?.agent_scope) &&
+      scopeKeyOf(m.workspace_scope) === scopeKeyOf(payload?.workspace_scope) &&
+      scopeKeyOf(m.sensitivity) === scopeKeyOf(payload?.sensitivity);
+    const samePath = (a, b) => {
+      if (!a || !b) return false;
+      // Windows 文件系统大小写不敏感：比较前归一，否则 C:\a.md 与 c:\A.md
+      // 会被判成两个版本。
+      const norm = (p) => (process.platform === "win32" ? String(p).toLowerCase() : String(p));
+      return norm(a) === norm(b);
+    };
+    // 精确层（同路径/同标题）必须全量扫描、不允许窗口截断：>200 行活跃
+    // document 时，窗口外的同路径旧版漏检会留下双活跃版本——supersede 判定
+    // 是正确性要求，不是性能优化对象。vector 档比对保留 CANDIDATE_LIMIT
+    // （getEmbeddings + 两两 cosine 才是有界对象）。
+    const scopeMatched = store
+      .list({ type: "document", limit: null })
+      .filter((m) => scopeMatches(m));
+    const explicitTarget = scopeMatched.find((m) => samePath(m.doc_path, expanded))
+      ?? scopeMatched.find((m) => m.title.trim() === title);
+    if (!explicitTarget) {
+      // vector 档：embedder 不可用/向量缺失一律跳过——去重是增强不是写入依赖
+      // （findSessionDuplicate 同原则）。probe 用 title+summary，与行向量
+      // （同两段拼接 embed）同构。
+      const candidates = scopeMatched.slice(0, CANDIDATE_LIMIT);
+      try {
+        const vecs = store.getEmbeddings(candidates.map((m) => m.id));
+        if (vecs.size) {
+          const probe = await embedQuery([title, summary].filter(Boolean).join("\n"));
+          if (probe) {
+            let best = null;
+            for (const m of candidates) {
+              const v = vecs.get(m.id);
+              if (!v) continue; // 无向量的既有行不参与比对（无信号 = 不判定）
+              const sim = cosineSimilarity(probe, v);
+              if (sim >= DOCUMENT_MIN_SIM && (!best || sim > best.sim)) best = { m, sim };
+            }
+            if (best) {
+              throw new Error(
+                `registerDocument: summary is a near duplicate (C2 >= ${DOCUMENT_MIN_SIM}, sim ${best.sim.toFixed(3)}) ` +
+                `of document row ${best.m.id} "${best.m.title}" — update that row via memory_update, or archive it ` +
+                `before registering a separate document`
+              );
+            }
+          }
+        }
+      } catch (e) {
+        // 近重复拒绝是业务结果，原样上抛；embedder 故障吞掉回落（只做路径/标题层）。
+        if (e instanceof Error && e.message.startsWith("registerDocument:")) throw e;
+      }
+    }
+
+    // --- 4. 落库 + supersede 记账（同事务）----------------------------------
+    // 新摘要行：库里只存 summary + doc_path + evidence（+ scope 标注），旧文件
+    // 零触碰。supersede：旧行 content_history 存旧摘要（source=superseded）、
+    // 正文追加指向新行的注记、归档（降可及性可复活，无物理删除）。
+    const userTags = (Array.isArray(payload?.tags) ? payload.tags : [])
+      .map((t) => String(t ?? "").trim())
+      .filter(Boolean);
+    const tags = [...new Set([...userTags, ...(dropped.length ? ["evidence_degraded"] : [])])];
+    const result = transaction(() => {
+      // saveDocument 是存储层唯一 document 铸造口（通用 save/update/CAS 拒绝
+      // document——CodeRabbit 复核 #8/#882）：registerDocument 传入的 doc_path
+      // 已过归一化与文件校验。
+      const created = store.saveDocument({
+        type: "document",
+        title,
+        content: summary,
+        tags,
+        importance: Number.isInteger(payload?.importance)
+          ? Math.min(5, Math.max(1, payload.importance))
+          : 3,
+        source: payload?.source ?? "tool",
+        evidence: kept,
+        doc_path: expanded,
+        // sensitivity 进 supersede 匹配键（scopeKeyOf 第三维）：不落库的话，
+        // 首注册带 sensitivity、重注册同键会在匹配时判成两 scope，旧版漏检。
+        ...(payload?.sensitivity !== undefined ? { sensitivity: payload.sensitivity } : {}),
+        ...(payload?.agent_scope !== undefined
+          ? { agent_scope: payload.agent_scope, agent_scope_source: payload.agent_scope_source }
+          : {}),
+        ...(payload?.workspace_scope !== undefined
+          ? { workspace_scope: payload.workspace_scope, workspace_scope_source: payload.workspace_scope_source }
+          : {})
+      });
+      let superseded;
+      const loser = explicitTarget ? store.getById(explicitTarget.id) : null;
+      if (loser && !loser.archived) {
+        store.update(loser.id, {
+          content: `${loser.content}${supersededByPointer(created.id)}`,
+          content_history: pushContentHistory(loser, "superseded")
+        });
+        store.setArchived(loser.id, true);
+        superseded = store.getById(loser.id);
+      }
+      return { created, superseded };
+    });
+    finalize(result.superseded ? [result.created, result.superseded] : [result.created]);
+    return {
+      action: result.superseded ? "superseded" : "created",
+      memory: result.created,
+      ...(result.superseded ? { superseded: result.superseded } : {}),
+      evidence_kept: kept.length,
+      evidence_dropped: dropped.length,
+      degraded: dropped.length > 0
+    };
+  };
+}

package/lib/dream/sleep.js

@@ -49,12 +49,22 @@ function parseJsonArray(text) {
   }
 }
 
-/** Same stream consumption contract as dream.js. */
-async function streamText(ctx, options, onStreamError) {
+/**
+ * Same stream consumption contract as dream.js.
+ *
+ * `onUsage`（optional, issue #250）receives any usage chunk for token accounting.
+ * dream.js 那份一直有它；sleep 这份副本没有，导致 conflict / pattern 两条链路的
+ * token 从未进 llm_audit_logs（面板因此只看到 autoDream 与 autoSummarize）。
+ */
+async function streamText(ctx, options, onUsage, onStreamError) {
   if (!ctx?.llm?.stream) return undefined;
   let text = "";
   for await (const chunk of ctx.llm.stream(options)) {
     if (chunk.type === "text-delta" && typeof chunk.text === "string") text += chunk.text;
+    // DSH 的 StreamChunk 契约把用量嵌在 chunk.usage（TokenUsage：inputTokens /
+    // outputTokens / totalTokens）；兼容直接平铺在 chunk 上的旧形态。归一放在
+    // 这里，调用侧的 reporter 只需认平铺形状——与 dream.js:239 同一处理。
+    if (chunk.type === "usage" && typeof onUsage === "function") onUsage(chunk.usage ?? chunk);
     if (chunk.type === "finish" && (chunk.reason?.kind === "error" || chunk.reason?.kind === "aborted")) {
       // Same rc.1 error-as-finish-chunk behavior as dream.js — surface the
       // cause instead of discarding it.
@@ -67,6 +77,79 @@ async function streamText(ctx, options, onStreamError) {
   return text;
 }
 
+/**
+ * Issue #250：给 sleep 的一条 LLM 调用记一笔 llm_audit_logs（token / 时长 / 状态 /
+ * 触发源）。与 dream.js 的 runAuditedLlm 同口径但各自独立一份——dream 那两个
+ * checker 的调用形状绑定着它自己的排程细节，硬抽共享抽象只会收敛回 dream 的形态。
+ *
+ * 记账是 best-effort：写审计行失败只 warn，绝不反噬 sleep 本体（CONTRIBUTING 的
+ * fail-safe 硬约定）。`body(reportUsage)` 负责真实消费流，usage chunk 经
+ * reportUsage 上报。
+ *
+ * 审计诚实性：流被中止/报错时 body 返回 undefined，记 status='error'；流式成功但
+ * 输出不可用时 `spec.auditError` 给出原因，同样记 error——否则同一轮调用会在
+ * 「phase 报 failed」与「audit 报 success」之间自相矛盾（CONTRIBUTING 的审计诚实性
+ * 硬约定）。`auditError` 必须是**纯判据函数**：调用方的控制流不能依赖它的副作用，
+ * 因为审计关闭时这里整段早退、钩子根本不会被调用（dream 正是那样踩的，见 PR 正文）。
+ */
+async function auditedSleepLlm(ctx, service, config, logger, spec, body) {
+  if (config?.llmAudit?.enabled === false || typeof service?.saveLlmAudit !== "function") {
+    return body(() => {});
+  }
+  const startedAt = Date.now();
+  const timestamp = new Date(startedAt).toISOString();
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let status = "success";
+  let errorMessage = null;
+  try {
+    const result = await body((usage) => {
+      if (!usage) return;
+      const i = usage.input_tokens ?? usage.inputTokens ?? usage.prompt_tokens ?? usage.promptTokens;
+      const o = usage.output_tokens ?? usage.outputTokens ?? usage.completion_tokens ?? usage.completionTokens;
+      if (Number.isFinite(i)) inputTokens = i;
+      if (Number.isFinite(o)) outputTokens = o;
+    });
+    if (result === undefined) {
+      status = "error";
+      const streamErr = typeof spec.streamError === "function" ? String(spec.streamError() ?? "") : "";
+      errorMessage = streamErr ? `llm stream aborted or errored (${streamErr})` : "llm stream aborted or errored";
+    } else if (typeof spec.auditError === "function") {
+      // 流式成功但输出不可用，仍然是一次失败的调用——记 error，不与调用方的
+      // failed 返回值打架。
+      const message = spec.auditError(result);
+      if (message) {
+        status = "error";
+        errorMessage = message;
+      }
+    }
+    return result;
+  } catch (error) {
+    status = "error";
+    errorMessage = String(error?.message ?? error);
+    throw error;
+  } finally {
+    try {
+      service.saveLlmAudit({
+        timestamp,
+        trigger_source: spec.triggerSource,
+        operation_type: spec.operationType,
+        model_id: spec.modelId,
+        input_tokens: inputTokens,
+        output_tokens: outputTokens,
+        total_tokens: inputTokens + outputTokens,
+        cost_usd: 0,
+        duration_ms: Date.now() - startedAt,
+        status,
+        error_message: errorMessage,
+        related_memory_ids: spec.relatedMemoryIds ?? []
+      });
+    } catch (auditError) {
+      logger?.warn?.(`dsh-mneme sleep: llm audit write failed: ${String(auditError)}`);
+    }
+  }
+}
+
 /** LLM route (Issue #25): explicit sleepProvider/Model wins, then the dream
  *  route as a shared explicit fallback, then the agent default model. Sleep
  *  can pin a cheaper model for its bulk passes without disturbing the dream
@@ -106,7 +189,7 @@ async function phaseConflicts(ctx, service, config, logger, runId, semantic = nu
   }
   const strictness = config.sleepConflictStrictness ?? "normal";
   const threshold = CONFLICT_THRESHOLDS[strictness] ?? CONFLICT_THRESHOLDS.normal;
-  const memories = service.all().filter((m) => !m.archived && !m.forgotten && m.type !== "summary");
+  const memories = service.all().filter((m) => !m.archived && !m.forgotten && m.type !== "summary" && m.type !== "document");
   if (memories.length < 2) return { status: "skipped", reason: "too few memories" };
   if (signal?.aborted) return { status: "aborted", reason: "user activity" };
 
@@ -232,17 +315,29 @@ async function phaseConflicts(ctx, service, config, logger, runId, semantic = nu
   const conflictPrompt = actionSet === "full" ? STR.prompts.conflictFull[language] : STR.prompts.conflict[language];
   const runConflict = (withEffort) => {
     conflictStreamFailure = "";
-    return streamText(ctx, {
+    return auditedSleepLlm(ctx, service, config, logger, {
+      triggerSource: "sleep",
+      operationType: "sleep_conflict",
+      modelId: `${route.provider}:${route.model}`,
+      // 候选对的双方 id：面板的活动流用 related_memory_ids 解析「沉淀条数」。
+      relatedMemoryIds: samePairs.flatMap((p) => [p.a.id, p.b.id]),
+      streamError: () => conflictStreamFailure,
+      // 纯判据：输出里没有 JSON 数组 ⇒ 这轮是失败的调用，审计记 error。**不要**把
+      // 解析结果存进闭包给下面的控制流用——审计关闭时 auditedSleepLlm 整段早退、
+      // 这个钩子不会被调用，控制流会跟着失效（dream 的既有坑）。代价是审计开启时
+      // 多解析一次，换来两条路径彻底解耦。
+      auditError: (text) => (parseJsonArray(text) ? null : "no json array in llm output")
+    }, (reportUsage) => streamText(ctx, {
     provider: route.provider,
     model: route.model,
     purpose: "sleep-conflict",
-    maxTokens: 2048,
+    maxTokens: config.sleepMaxTokens ?? 2048,
     ...(withEffort && sleepEffort ? { reasoningEffort: sleepEffort } : {}),
     messages: [
       { role: "system", content: [{ type: "text", text: conflictPrompt }], source: { kind: "plugin", plugin: "dsh-mneme" } },
       { role: "user", content: [{ type: "text", text: listText }], source: { kind: "plugin", plugin: "dsh-mneme" } }
     ]
-  }, (reason) => { conflictStreamFailure = describeStreamFailure(reason); });
+  }, reportUsage, (reason) => { conflictStreamFailure = describeStreamFailure(reason); }));
   };
   const text = await withEffortFallback(ctx, sleepEffort, () => runConflict(true), () => runConflict(false), () => conflictStreamFailure);
   if (text === undefined) {
@@ -368,8 +463,10 @@ async function phasePatterns(ctx, service, config, logger, runId, signal = null)
   const route = resolveSleepRoute(ctx, config, logger);
   if (!route) return { status: "skipped", reason: "no llm route" };
   const limit = config.sleepPatternMinMemories ?? 100;
+  // #230：document 在查询层排除（excludeTypes）而不是截断后过滤——LIMIT 200
+  // 先生效的话，指针行一多就会把普通记忆挤出扫描窗，池子饿到门槛以下。
   const memories = service
-    .list({ limit: 200, includeForgotten: false })
+    .list({ limit: 200, includeForgotten: false, excludeTypes: ["document"] })
     .filter((m) => !m.archived && m.type !== "summary" && m.type !== "pattern")
     .sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1))
     .slice(0, limit);
@@ -383,17 +480,26 @@ async function phasePatterns(ctx, service, config, logger, runId, signal = null)
   let patternStreamFailure = "";
   const runPattern = (withEffort) => {
     patternStreamFailure = "";
-    return streamText(ctx, {
+    return auditedSleepLlm(ctx, service, config, logger, {
+      triggerSource: "sleep",
+      operationType: "sleep_pattern",
+      modelId: `${route.provider}:${route.model}`,
+      // 本轮扫描的记忆 id：与 dream 的 relatedMemoryIds 同义，供面板解析沉淀条数。
+      relatedMemoryIds: memories.map((m) => m.id),
+      streamError: () => patternStreamFailure,
+      // 纯判据，同 conflict 阶段：不把解析结果存进闭包供控制流使用。
+      auditError: (text) => (parseJsonArray(text) ? null : "no json array in llm output")
+    }, (reportUsage) => streamText(ctx, {
     provider: route.provider,
     model: route.model,
     purpose: "sleep-pattern",
-    maxTokens: 2048,
+    maxTokens: config.sleepMaxTokens ?? 2048,
     ...(withEffort && sleepEffort ? { reasoningEffort: sleepEffort } : {}),
     messages: [
       { role: "system", content: [{ type: "text", text: STR.prompts.pattern[language].replace("N", String(maxPatterns)) }], source: { kind: "plugin", plugin: "dsh-mneme" } },
       { role: "user", content: [{ type: "text", text: listText }], source: { kind: "plugin", plugin: "dsh-mneme" } }
     ]
-  }, (reason) => { patternStreamFailure = describeStreamFailure(reason); });
+  }, reportUsage, (reason) => { patternStreamFailure = describeStreamFailure(reason); }));
   };
   const text = await withEffortFallback(ctx, sleepEffort, () => runPattern(true), () => runPattern(false), () => patternStreamFailure);
   if (text === undefined) {
@@ -505,6 +611,9 @@ function deriveStatus(phases) {
  */
 export async function runSleep(ctx, service, config, logger, semantic = null, signal = null) {
   const runId = randomUUID();
+  // Issue #89：开跑时刻——审计行 created_at 的基准（= 冷却种子），run 耗时
+  // （LLM 各 phase）不应计入重启后的冷却窗口。
+  const sleepStartedAt = Date.now();
   const phases = {};
   const attempt = async (name, fn) => {
     if (signal?.aborted) return; // user resumed activity — stop before next phase
@@ -541,6 +650,9 @@ export async function runSleep(ctx, service, config, logger, semantic = null, si
   try {
     service.saveDreamRun({
       id: runId,
+      // Issue #89：审计行记开跑时刻而非完成时刻——run 耗时（含 LLM 各 phase）
+      // 不该计入重启后的 sleep 冷却种子。
+      created_at: new Date(sleepStartedAt).toISOString(),
       status,
       provider: route?.provider,
       model: route?.model,
@@ -580,10 +692,14 @@ export function createSleepScheduler({
   onRun = null,
   now = () => Date.now(),
   setTimeoutFn = setTimeout,
-  clearTimeoutFn = clearTimeout
+  clearTimeoutFn = clearTimeout,
+  // Issue #89 同族：冷却时刻由调用方从 dream_runs 审计表恢复（run_type='sleep'）——
+  // 内存变量进程重启即归零，冷却闸对新实例放行 → 重启后立即进入 sleep 冷却盲区。
+  // 测试注入 0（默认）即保持旧行为。
+  lastRunAtSeed = 0
 }) {
   let lastWriteAt = now();
-  let lastRunAt = 0;
+  let lastRunAt = lastRunAtSeed;
   let running = false;
   let disposed = false;
   let idleTimer = null;