@modusensus/dsh-mneme 0.8.4 → 0.8.5

package/lib/service.js

@@ -7,16 +7,30 @@ import { computeHeat } from "./heat.js";
 import { recallStats } from "./recall-stats.js";
 import { evaluateMemoryQuality } from "./quality-filter.js";
 import { applyDecisions } from "./dream/decisions.js";
+import { createDocumentRegistrar } from "./document.js";
+import { createOrganizer } from "./organize.js";
 import { createBM25Index } from "./search/bm25.js";
 import { adaptiveThreshold } from "./search/adaptive.js";
 
 const INJECT_TYPES = new Set(["preference", "project", "decision", "summary", "rejected_solution", "pitfall", "constraint"]);
 
+// document 摘要行（#230）：仅 documentMemoryEnabled 开启时进注入候选。独立
+// 集合而非常改共享 Set——INJECT_TYPES 本身是「类型可注入」的静态事实，flag
+// 是运行时状态，两者不能搅在一起。
+const INJECT_TYPES_WITH_DOCUMENT = new Set([...INJECT_TYPES, "document"]);
+
 // 编码记忆类型（codingRetrospect）：rejected_solution / pitfall / constraint
 // 只在编码任务时注入（防噪声污染其他业务），且编码场景下按 codingBoostFactor
 // 加权排序提前。
 const CODING_MEMORY_TYPES = new Set(["rejected_solution", "pitfall", "constraint"]);
 
+// pin 池类型（#249 第一批）：约束与偏好是「对谁都成立的边界」，需要逐字保真
+// 而不是相关性排序——它们与情景日志同池同速率摘要会被静默降级（立项依据）。
+// 注意 constraint 同时属于 CODING_MEMORY_TYPES，非编码任务里已被 codingGate
+// 滤掉，pin 池同样拿不到它；是否豁免该门控是待维护者拍板的口径问题，本批次
+// 不动既有门控（不放大行为面）。
+const PINNED_MEMORY_TYPES = new Set(["constraint", "preference"]);
+
 /**
  * 判断一段文本是否编码类任务（关键词匹配，codingRetrospect 读取侧门控）。
  * 纯函数，无副作用，便于单测。
@@ -39,8 +53,10 @@ const CONTENT_HISTORY_MAX = 20;
 
 // Issue #135 附属发现 2：质量过滤器写下的系统信号标签（「为什么被降权/归档」的
 // 唯一审计线索）。更新路径整组替换 tags 会把它们抹掉——更新时按此清单并集保留。
-// 清单必须与 quality-filter.js 的写入端对齐（6 个，含 type 自指的 self_referential）。
-const SIGNAL_TAGS = ["low_quality", "duplicate", "meta", "repetitive", "short_content", "self_referential"];
+// 清单必须与 quality-filter.js 的写入端对齐（6 个，含 type 自指的 self_referential）；
+// evidence_degraded 是 #230 注册端的求交标记（quality-filter 不写它，但同样
+// 不许被更新抹掉）。
+const SIGNAL_TAGS = ["low_quality", "duplicate", "meta", "repetitive", "short_content", "self_referential", "evidence_degraded"];
 
 // scopeKeyOf 已上提到 ./scope.js（v0.8.1，issue #170 第 2 步）：与 sleep 的跨
 // scope 配对共用同一把比较钥匙，避免两处定义漂移。
@@ -1110,6 +1126,13 @@ export function createService({ store, mirror, config, onWrite, logger }) {
    * @returns {{action: "created"|"merged", memory: object}}
    */
   function saveWithDedupe(memory) {
+    // #230 写入权分离：document 行只能经 registerDocument 铸造（注册校验 +
+    // doc_path + evidence 三样俱全）。通用保存路径（memory_save 工具 / MCP /
+    // standalone API / bootstrap）一律拒绝——防止绕过注册校验造出无指针无
+    // 回链的伪 document 行。与 updateMemory 的同款守卫构成双保险。
+    if (memory?.type === "document") {
+      throw new Error("type 'document' is minted only via registerDocument (summary + doc_path + evidence)");
+    }
     // Bug7: score quality once (after dedupe lookup, before write). Failures
     // inside the evaluator are impossible (pure function), but the write that
     // records the score must never fail the save — wrap defensively.
@@ -1301,8 +1324,13 @@ export function createService({ store, mirror, config, onWrite, logger }) {
    * lead the selection (up to maxItems*2 candidates) and the rule-based pick
    * fills + dedupes the remaining slots. Empty query / no cached recall /
    * hybridInject off → pure legacy rule-based selection.
+   *
+   * #249 第一批（B1 pin 池）：`pinnedInjectBudget` > 0 时，约束/偏好类先按相关性
+   * 取满独立预算、再从候选里摘除（于是轮换重排碰不到它们），由调用方前置到块
+   * 头。`pinnedStats` 是可选出参：回报实际 pin 条数与超预算未展示条数，不改变
+   * 本函数「返回数组」的既有契约。预算为 0 时整段不执行，行为逐字节不变。
    */
-  function injectCandidates({ query = "", maxItems = 5, threshold = 3, queryVector, scope = null, rotate = null, rotateWindow = 0 } = {}) {
+  function injectCandidates({ query = "", maxItems = 5, threshold = 3, queryVector, scope = null, rotate = null, rotateWindow = 0, pinnedStats = null } = {}) {
     const q = String(query ?? "").trim();
     // codingRetrospect 读取侧门控：编码记忆（rejected_solution / pitfall /
     // constraint）只在编码任务时注入，防噪声污染其他业务；编码任务时按
@@ -1321,11 +1349,19 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     const poolSize = rotateWindowN > 0
       ? Math.max(maxItems * 2, maxItems * (rotateWindowN + 1))
       : maxItems * 2;
+    // #230 拍板：注入档位合并设计（叙述条次优先档 + document 摘要行预算）。
+    // ①叙述条（source=narrative）从纯按需解禁进注入候选，落次优先档——但受
+    // 生成总闸 dreamNarrativeEnabled 约束（flag 关 = 该类行不再注入，存量行
+    // 仍可检索）；②document 摘要行同落次优先档，另有独立预算（见下方选取）。
+    const injectTypes = config?.documentMemoryEnabled === true ? INJECT_TYPES_WITH_DOCUMENT : INJECT_TYPES;
+    // #230 拍板：叙述条解禁进注入受生成总闸约束——门必须对全部候选路径一致
+    // （规则/向量/缓存/BM25），只锁规则路的话语义路仍会漏进 narrative 行。
+    const allowNarrative = config?.dreamNarrativeEnabled === true;
     const filtered = store.list({ limit: Math.max(200, poolSize), includeForgotten: false })
-      .filter((m) => !m.archived && INJECT_TYPES.has(m.type) && !m.forgotten &&
-        // 叙述条（#164 对齐）按需检索：source=narrative 的 per-topic 叙述不进
-        // 注入候选——常驻位只留给 dream 总览（source=dream）。
-        m.source !== "narrative" &&
+      .filter((m) => !m.archived && injectTypes.has(m.type) && !m.forgotten &&
+        // 叙述条：#228 落地为纯按需检索；#230 合并拍板解禁为次优先档注入
+        // （per-topic 叙述常驻位仍只留给 dream 总览 source=dream）。
+        (m.source !== "narrative" || allowNarrative) &&
         codingGate(m) &&
         (m.type === "summary" || m.type === "preference" || m.importance >= threshold));
     // #218 v1: heat 乘数——heatEnabled 时在优先级层内给 importance×quality 乘
@@ -1341,8 +1377,13 @@ export function createService({ store, mirror, config, onWrite, logger }) {
         // 编码记忆在编码任务时优先于普通 decision（与 preference 同级），
         // importance 乘 codingBoostFactor 加权（封顶 5，保持 importance 语义）。
         const priority = (m) => {
+          // #230：叙述条与 document 摘要行同为次优先档——蒸馏摘要（0）仍最
+          // 先，指针型聚合产物（1）先于普通 project/decision（2）。叙述条是
+          // type=summary，判 source 必须在判 type 之前。
+          if (m.source === "narrative") return 1;
           if (m.type === "summary") return 0;
           if (m.type === "preference") return 1;
+          if (m.type === "document") return 1;
           if (isCoding && CODING_MEMORY_TYPES.has(m.type)) return 1;
           return 2;
         };
@@ -1367,7 +1408,8 @@ export function createService({ store, mirror, config, onWrite, logger }) {
         try {
           const hits = vectorIndex.search(queryVector, { limit: poolSize, threshold: 0 });
           for (const m of hits) {
-            if (m && !m.archived && INJECT_TYPES.has(m.type) && !m.forgotten &&
+            if (m && !m.archived && injectTypes.has(m.type) && !m.forgotten &&
+              (m.source !== "narrative" || allowNarrative) &&
               codingGate(m) &&
               (m.type === "summary" || m.type === "preference" || m.importance >= threshold)) {
               semanticItems.push(m);
@@ -1377,7 +1419,8 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       }
       if (!semanticItems.length && lastSemanticRecall?.query === q && lastSemanticRecall.items?.length) {
         for (const m of lastSemanticRecall.items) {
-          if (m && !m.archived && INJECT_TYPES.has(m.type) && !m.forgotten && codingGate(m)) semanticItems.push(m);
+          if (m && !m.archived && injectTypes.has(m.type) && !m.forgotten &&
+            (m.source !== "narrative" || allowNarrative) && codingGate(m)) semanticItems.push(m);
         }
       }
       // Issue #198：首轮（无向量、无缓存召回）的同步兜底——BM25 词法召回领位。
@@ -1389,7 +1432,8 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       // 语义向量命中时本分支不参与，行为不变。
       if (!semanticItems.length) {
         for (const hit of bm25Recall(q, poolSize)) {
-          if (hit && !hit.archived && INJECT_TYPES.has(hit.type) && !hit.forgotten &&
+          if (hit && !hit.archived && injectTypes.has(hit.type) && !hit.forgotten &&
+            (hit.source !== "narrative" || allowNarrative) &&
             codingGate(hit) &&
             (hit.type === "summary" || hit.type === "preference" || hit.importance >= threshold)) {
             semanticItems.push(hit);
@@ -1434,6 +1478,20 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     if (config?.strictScope === true && scope) {
       candidates = candidates.filter((m) => isVisibleInScope(m, scope));
     }
+    // #249 第一批：B1 pin 池。取在相关性排序之后、轮换之前——取谁按此刻的候选
+    // 次序（即相关性次序），取到后从候选中摘除，于是下面的轮换重排碰不到它们
+    // （验收：pin 不参与跨轮轮换）。独立预算的两层意义：pin 既不占 maxItems
+    // 名额、也不被 document 预算截断，因此不会把当前任务需要的情景候选挤出去；
+    // 超预算的条数回报给调用方，在块内如实标注（绝不静默省略）。
+    const pinnedBudget = Math.max(0, Math.min(5, Math.floor(config?.pinnedInjectBudget ?? 0)));
+    // eligible 留到块外：未展示条数要等 general 槽选完才算得准（见 selected 之后）。
+    const eligible = pinnedBudget > 0 ? candidates.filter((m) => PINNED_MEMORY_TYPES.has(m.type)) : [];
+    let pinned = [];
+    if (pinnedBudget > 0 && eligible.length > 0) {
+      pinned = eligible.slice(0, pinnedBudget);
+      const pinnedIds = new Set(pinned.map((m) => m.id));
+      candidates = candidates.filter((m) => !pinnedIds.has(m.id));
+    }
     // Issue #205：注入位跨轮轮换。rotate = 最近 N 轮注入过的 id 集合（由注入层
     // 按会话维护并传入）：这些条目本轮不再优先——新鲜者前置（各自内部相对次序
     // 保持），不足时按原序回填，槽位数与 touchRecall 语义均不变。rotate 为空时
@@ -1442,8 +1500,58 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       const fresh = candidates.filter((m) => !rotate.has(m.id));
       if (fresh.length > 0) candidates = [...fresh, ...candidates.filter((m) => rotate.has(m.id))];
     }
-    const selected = candidates.slice(0, maxItems);
+    // #230 拍板：document 摘要行预算——次优先档内最多 documentInjectBudget
+    // 条，超预算的 document 行跳过、由后续候选补位（不占槽）。预算只约束
+    // 注入不约束检索：指针行价值在「按需读全文」，常驻注入若不设界就会把
+    // 注入块变成文档目录（#164 失败判据：批量把历史塞进上下文）。
+    const documentBudget = config?.documentInjectBudget ?? 2;
+    let documentSeen = 0;
+    const general = [];
+    for (const m of candidates) {
+      if (general.length >= maxItems) break;
+      if (m.type === "document") {
+        if (documentSeen >= documentBudget) continue;
+        documentSeen++;
+      }
+      general.push(m);
+    }
+    // #249 第一批：pin 前置到块内相关性排序之前（验收项），且不占 maxItems 名额。
+    // pinned 为空时 selected 就是 general 本身——关闭态与改动前逐字节一致。
+    const selected = pinned.length > 0 ? [...pinned, ...general] : general;
+    if (pinnedStats) {
+      // 「未展示」只数**真的没进块**的 pin 类条目：被 pin 预算挤下来的条目会回到
+      // 候选池，仍可能被 general 槽选中——那就是展示了。按 eligible - pinned 直接
+      // 相减会把它们也算成未展示，块头那一行于是虚报（评审实测：pref#2 已在块内，
+      // 仍报「另有 2 条未展示」）。所以统一按「有没有进 selected」判。
+      const shownIds = new Set(selected.map((m) => m.id));
+      pinnedStats.shown = pinned.length;
+      pinnedStats.suppressed = eligible.filter((m) => !shownIds.has(m.id)).length;
+    }
     touchRecalled(selected);
+    // #217 口径（2026-09-19 拍板）：注入是曝光型访问事件，与检索命中同表分账
+    // （mode='inject'，candidates 存实际注入集）。跟随 recallRecordDefault——
+    // 与检索侧同门，不设新配置键；heat 关闭时照写，留痕与消费解耦（两 issue
+    // 独立验收）。空选不记（没有访问发生）；记账失败不影响注入本身。
+    if ((config?.recallRecordDefault ?? true) && recallRecorder && selected.length > 0) {
+      try {
+        recallRecorder({
+          // recall_runs.query 是 NOT NULL（store.js:61）：注入是主动曝光、
+          // 没有查询词，用空串而非 null——SQLite 改列约束需重建表，不值得。
+          query: "",
+          mode: "inject",
+          topK: maxItems,
+          threshold: null,
+          candidates: selected.map((m) => ({
+            id: m.id,
+            title: m.title,
+            content: m.content,
+            score: m.score ?? null,
+            source: m.source ?? "keyword"
+          })),
+          createdAt: new Date().toISOString()
+        });
+      } catch { /* recall receipt is best effort */ }
+    }
     return selected;
   }
 
@@ -1604,7 +1712,10 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       ...(m.workspace_scope_source !== undefined ? { workspace_scope_source: m.workspace_scope_source } : {}),
       ...(m.scope_decided_at !== undefined ? { scope_decided_at: m.scope_decided_at } : {}),
       ...(m.sensitivity !== undefined ? { sensitivity: m.sensitivity } : {}),
-      ...(m.occurred_at !== undefined ? { occurred_at: m.occurred_at } : {})
+      ...(m.occurred_at !== undefined ? { occurred_at: m.occurred_at } : {}),
+      // #230：document 指针行的文件定位随行透出——「全文按需读」的入口就是
+      // 这个路径；普通行恒不带键，DTO 与 #230 前逐字节同形。
+      ...(m.doc_path !== undefined && m.doc_path !== null ? { doc_path: m.doc_path } : {})
     }));
   }
 
@@ -1889,6 +2000,12 @@ export function createService({ store, mirror, config, onWrite, logger }) {
   // 处置）共用的写路径：mirror 同步、写通知、嵌入调度全部同源，不能各写一份。
   function updateMemory(id, p, ctx = {}) {
     const old = store.getById(id);
+    // #230 写入权分离（与 saveWithDedupe 同款守卫）：document 行只能经
+    // registerDocument 铸造。既有 document 行的摘要修复（memory_update 改
+    // content/title——设计定案的更新通道）照常放行，type 不许改入 document。
+    if (p?.type === "document" && old?.type !== "document") {
+      throw new Error("type 'document' is minted only via registerDocument (summary + doc_path + evidence)");
+    }
     // Issue #135 附属发现 2：质量过滤器把「为什么被降权/归档」写在系统信号标签
     // 上（SIGNAL_TAGS，applyQualityDisposition 以并集写入），而这里整组替换
     // tags——任何带 tags 的更新都会抹掉这条唯一的审计线索（报告实测 150 条低分
@@ -1978,8 +2095,42 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     return updated;
   }
 
+  // document 型记忆注册（#230）：内聚块在 src/document.js（AGENTS.md 尺寸
+  // 约定，同 recallStats 先例），这里只做依赖注入 + barrel 出口，调用方零改动。
+  // 写后语只做重嵌入：镜像同步与写通知由 transaction 的 commit 路径统一执行
+  // （notifyWrite 在 txDepth>0 时 deferred 到 finally），这里再调就是双份。
+  const registerDocument = createDocumentRegistrar({
+    store,
+    config,
+    embedQuery,
+    pushContentHistory,
+    transaction,
+    finalize: (rows) => {
+      for (const row of rows) scheduleEmbed(row);
+    }
+  });
+
+  // agent 主动整理接口（#231）：dryRun 比对报告 → agent 判断 → apply 落库，筛除项
+  // 进归档不删，全程复用 dream_runs 的 receipt 语义（不新建审计面）。走
+  // saveWithDedupe 落库 = 复用常规写路径的镜像/通知语；重嵌入由 finalize 在事务
+  // 提交后补（事务里的 scheduleEmbed 被 txDepth 挡掉）——document 同款先例。
+  const { organize } = createOrganizer({
+    store,
+    embedQuery,
+    saveWithDedupe,
+    transaction,
+    finalize: (rows) => {
+      for (const row of rows) scheduleEmbed(row);
+    }
+  });
+
   return {
     saveWithDedupe,
+    registerDocument,
+    // agent 主动整理接口（#231）：内聚块在 src/organize.js，这里只做依赖注入 +
+    // barrel 出口。刻意不加 opt-in 开关（维护者口径：功能本体不做开关，与 #249
+    // 同批暴露时再定配置面），也不进工具列表——工具注册在 #249 那批。
+    organize,
     recoverMirror,
     getMirrorHealth,
     getMirrorState: () => store.getMirrorState(),
@@ -1988,6 +2139,8 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     toApiList,
     isVisibleInScope,
     transaction,
+    getDistillCursor: (sessionId) => store.getDistillCursor(sessionId),
+    setDistillCursor: (sessionId, lastSeq) => store.setDistillCursor(sessionId, lastSeq),
     enqueue,
     setDreamHook(fn) { dreamHook = fn; },
     setSleepHook(fn) { sleepHook = fn; },

package/lib/settings.js

@@ -43,6 +43,10 @@ const FEATURE_FLAG_BOOLEANS = [
   "autoInject",
   "autoSummarize",
   "hotMemoryEnabled",
+  // Issue #239 第 5 项：注入条数的查询自适应（确定性强则收缩注入条数，默认关）。
+  "injectUncertaintyAdaptive",
+  // Issue #249 第一批：能力说明（工具描述判断指引 + order 150 总则段，默认关）。
+  "injectGuidanceEnabled",
   "entityExtractionEnabled",
   // Issue #219：图召回轴——查询命中实体名时把挂联记忆并入检索融合池
   // （默认关；依赖实体抽取产出，lightMode 强制关闭）。
@@ -50,6 +54,9 @@ const FEATURE_FLAG_BOOLEANS = [
   // Issue #164：叙述条——dream 期间按 tag 主题簇合成叙述落库（source=
   // narrative，evidence 回链簇内记忆；按需检索不常驻注入；默认关）。
   "dreamNarrativeEnabled",
+  // Issue #230：document 型记忆——agent 产长文档的指针行（注册校验/摘要+
+  // doc_path 落库/C2 去重/supersede 记账；全文归 agent；默认关，lightMode 强制关）。
+  "documentMemoryEnabled",
   "codingRetrospect",
   "autoDream",
   "sleepModeEnabled",
@@ -78,6 +85,10 @@ const FEATURE_FLAG_BOOLEANS = [
   // Issue #17（v0.8.0 A3）：strictScope 硬过滤——他 scope 完全不可见（关闭时
   // 为 A2 软隔离：降权保留可见）。
   "strictScope",
+  // 工具暴露开关（v0.8.5）：记忆已每轮自动注入，memory_search/memory_archive
+  // 在慢/轻量模型上是多余往返，面板可关（默认关=行为不变）。
+  "disableMemorySearch",
+  "disableMemoryArchive",
   // 嵌套对象开关：config.js 里是 memoryQualityFilter / llmAudit 对象的 enabled
   // 子字段。kv 按点号键平铺存（"memoryQualityFilter.enabled": false），index.js
   // 合并时展开回嵌套对象，api.js 的 effective 从对象子字段取值。
@@ -97,12 +108,25 @@ const FEATURE_FLAG_INT_RANGES = {
   summarizeMinIntervalMinutes: [0, 10080],
   summarizeMaxEntriesPerRun: [0, 50],
   summarizeDedupeWindowHours: [0, 168],
+  // Issue #239：蒸馏零 LLM 预判（窗口最小字符数）与每会话 run 预算（0 = 零行为变化）。
+  summarizeMinWindowChars: [0, 100000],
+  summarizeMaxRunsPerSession: [0, 1000],
+  // Issue #239 第 4 项：高峰顺延上限（分钟，0 = 不设上限）。
+  summarizePeakMaxDeferMinutes: [0, 1440],
   // Issue #125：hybrid 候选量上限（0 = 复用 dreamMaxSnapshotSize）。
   dreamCandidateMax: [0, 5000],
   // Issue #164①：注入单条正文截断上限（默认 300 = 既有行为）。
   injectContentMaxChars: [60, 4000],
   // Issue #164：叙述条成簇门槛（共享同一 tag 的记忆数下限）。
-  dreamNarrativeMinCluster: [2, 20]
+  dreamNarrativeMinCluster: [2, 20],
+  // Issue #230：document 摘要行的注入预算（次优先档内最多几条指针行）。
+  documentInjectBudget: [1, 5],
+  // Issue #249 第一批：B1 pin 池（约束/偏好）的独立条数预算（0 = 关闭/现状）。
+  pinnedInjectBudget: [0, 5],
+  // Issue #257：sleep 冲突/模式阶段的 LLM 输出预算（原硬编码 2048，实测不足）。
+  sleepMaxTokens: [256, 131072],
+  // Issue #258：总览（dream_summarize）输入条数硬上限（0 = 不设上限）。
+  dreamSummaryMaxInputs: [0, 100000]
 };
 // 浮点开关的闭区间（与 config.js 的 z.number().min().max() 对齐）。与整数开关
 // 分开：面板的整数控件要求 Number.isInteger，而余弦相似度阈值必须允许小数。
@@ -125,8 +149,13 @@ const FEATURE_FLAG_STRINGS = [
   // 留空 = 用当前默认模型。
   "entityExtractionProvider",
   "entityExtractionModel",
+  // Issue #258：总览（dream_summarize）专用路由，留空 = 用巩固模型。
+  "dreamSummaryProvider",
+  "dreamSummaryModel",
   "localEmbedModel",
-  "ollamaModel"
+  "ollamaModel",
+  // Issue #239 第 4 项：高峰时段串（"09:00-18:00"，空串 = 关闭）。
+  "summarizePeakHours"
 ];
 // URL 字符串开关：trim 后必须为空或合法 http/https URL（new URL() 校验协议，
 // 拒绝其余协议——这是 SSRF 防线的一部分）。

package/lib/store.js

@@ -18,6 +18,7 @@ CREATE TABLE IF NOT EXISTS memories (
   last_accessed_at  TEXT,
   _full_content     TEXT,
   evidence    TEXT,
+  doc_path    TEXT,
   created_at  TEXT NOT NULL,
   updated_at  TEXT NOT NULL
 );
@@ -47,7 +48,7 @@ CREATE TABLE IF NOT EXISTS dream_runs (
   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', -- auto | sleep：睡眠周期的审计区分
+  run_type       TEXT NOT NULL DEFAULT 'auto', -- auto | sleep | organize：周期审计的类别区分
   skipped        TEXT                     -- JSON: degraded 轮被跳过的逐条明细（index/action/ids/error）
 );
 CREATE INDEX IF NOT EXISTS idx_dream_runs_created ON dream_runs(created_at);
@@ -196,6 +197,14 @@ CREATE TABLE IF NOT EXISTS llm_audit_logs (
 CREATE INDEX IF NOT EXISTS idx_llm_audit_timestamp ON llm_audit_logs(timestamp);
 CREATE INDEX IF NOT EXISTS idx_llm_audit_source ON llm_audit_logs(trigger_source);
 
+-- autoSummarize 的增量蒸馏游标：按 session.id 持久化最近一次成功消费的事件序。
+-- 游标是蒸馏窗口的恢复事实，不与 user_settings 或记忆内容混用。
+CREATE TABLE IF NOT EXISTS distill_cursors (
+  session_id TEXT PRIMARY KEY,
+  last_seq   INTEGER NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
 -- entity gene (v0.3.0): named entities mentioned across memories, with
 -- time-boxed attributes (valid_from → valid_until) and typed relations.
 -- Attributes follow the snapshot style: saveAttr invalidates the previous
@@ -268,7 +277,10 @@ CREATE TABLE IF NOT EXISTS mirror_state (
 // Exported for API-layer type validation (standalone API POST /memories and
 // the /status byType breakdown); the set itself stays the single source of
 // truth for what store.save accepts.
-export const TYPES = new Set(["preference", "project", "decision", "history", "summary", "pattern", "rejected_solution", "pitfall", "constraint"]);
+export const TYPES = new Set(["preference", "project", "decision", "history", "summary", "pattern", "rejected_solution", "pitfall", "constraint",
+  // #230：agent 产长文档的指针行（摘要 + doc_path + evidence）。铸造口唯一
+  // （registerDocument）——saveWithDedupe/updateMemory 另有守卫拒绝旁路铸造。
+  "document"]);
 
 // Epistemic status: what kind of evidence a memory rests on. Defaults to
 // 'subjective' so legacy rows (and rows without any signal) stay compatible.
@@ -400,6 +412,7 @@ function toRow(row) {
     source: row.source ?? undefined,
     content_history: parseJsonArray(row.content_history),
     evidence: parseJsonArray(row.evidence),
+    doc_path: row.doc_path ?? undefined,
     quality_score: row.quality_score !== null && row.quality_score !== undefined ? Number(row.quality_score) : undefined,
     epistemic_status: row.epistemic_status ?? "subjective",
     agent_scope: row.agent_scope ?? undefined,
@@ -674,6 +687,8 @@ export function createStore(path) {
   // 叙述条证据链（#164 对齐）：[{memory_id, op, at}] JSON 数组——叙述/模式类
   // 记忆回链其支撑原子记忆，写入前与候选集求交防模型捏造。
   addColumn("memories", "evidence", "ALTER TABLE memories ADD COLUMN evidence TEXT");
+  // #230：document 指针行的文件定位。只有 registerDocument 写它，普通行恒 NULL。
+  addColumn("memories", "doc_path", "ALTER TABLE memories ADD COLUMN doc_path TEXT");
   addColumn("memories", "epistemic_status", "ALTER TABLE memories ADD COLUMN epistemic_status TEXT NOT NULL DEFAULT 'subjective'");
   addColumn("memories", "content_history", "ALTER TABLE memories ADD COLUMN content_history TEXT");
   addColumn("memories", "quality_score", "ALTER TABLE memories ADD COLUMN quality_score REAL");
@@ -782,6 +797,37 @@ export function createStore(path) {
     return ts;
   }
 
+  /** 返回指定会话持久化的 autoSummarize 游标；不存在时返回 undefined。 */
+  function getDistillCursor(sessionId) {
+    if (typeof sessionId !== "string" || sessionId.length === 0) return undefined;
+    const row = db.prepare(
+      "SELECT session_id, last_seq, updated_at FROM distill_cursors WHERE session_id = ?"
+    ).get(sessionId);
+    return row
+      ? { session_id: row.session_id, last_seq: Number(row.last_seq), updated_at: row.updated_at }
+      : undefined;
+  }
+
+  /**
+   * 单调持久化会话游标。调用方若同时写入记忆，必须放在外层 SQLite 事务内。
+   */
+  function setDistillCursor(sessionId, lastSeq) {
+    if (typeof sessionId !== "string" || sessionId.length === 0) {
+      throw new TypeError("setDistillCursor: sessionId must be a non-empty string");
+    }
+    if (!Number.isSafeInteger(lastSeq)) {
+      throw new TypeError("setDistillCursor: lastSeq must be a safe integer");
+    }
+    db.prepare(`
+      INSERT INTO distill_cursors (session_id, last_seq, updated_at)
+      VALUES (?, ?, ?)
+      ON CONFLICT(session_id) DO UPDATE SET
+        last_seq = MAX(distill_cursors.last_seq, excluded.last_seq),
+        updated_at = excluded.updated_at
+    `).run(sessionId, lastSeq, nowIso());
+    return getDistillCursor(sessionId);
+  }
+
   function count(type, { minImportance = null, source = null, includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, updatedFrom = null, updatedTo = null, occurredFrom = null, occurredTo = null, visibility = null } = {}) {
     const clauses = [];
     const params = [];
@@ -863,7 +909,28 @@ export function createStore(path) {
     return toRow(row);
   }
 
+  // #230 写入权分离（存储层唯一铸造口，CodeRabbit 复核最终形态）：document
+  // 行只能经 saveDocument 铸造，通用 save 整类拒绝。doc_path 是任意调用方
+  // 都能捏造的字符串——「必带 doc_path」挡不住绕过注册校验（flag 闸 / 文件
+  // 存在 / 路径归一化 / evidence 可见性 / scope 匹配 / supersede 探测）的直
+  // 铸，必须整类拒绝；受控通道是独立方法而不是隐藏旗标（旗标可被载荷携带，
+  // 方法名在 DI 合同里可审计）。
   function save(memory) {
+    if (memory?.type === "document") {
+      throw new Error("document rows are minted only via store.saveDocument (registerDocument)");
+    }
+    return insertMemoryRow(memory);
+  }
+
+  function saveDocument(memory) {
+    // 指针行结构不变量：doc_path 是 document 的存在依据（无指针 = 死行）。
+    if (!(typeof memory?.doc_path === "string" && memory.doc_path.trim())) {
+      throw new Error("document rows are pointer rows: doc_path is required");
+    }
+    return insertMemoryRow(memory);
+  }
+
+  function insertMemoryRow(memory) {
     const id = memory.id ?? randomUUID();
     const type = memory.type;
     if (!TYPES.has(type)) throw new Error(`invalid memory type: ${type}`);
@@ -874,6 +941,7 @@ export function createStore(path) {
     const tags = JSON.stringify(memory.tags ?? []);
     const importance = Number.isInteger(memory.importance) ? memory.importance : 3;
     const evidence = Array.isArray(memory.evidence) ? JSON.stringify(memory.evidence) : null;
+    const docPath = typeof memory.doc_path === "string" && memory.doc_path.trim() ? memory.doc_path : null;
     const embedding = Array.isArray(memory.embedding) && memory.embedding.length
       ? JSON.stringify(memory.embedding)
       : null;
@@ -884,8 +952,8 @@ export function createStore(path) {
       : inferEpistemicStatus(memory);
     runAtomically(() => {
       db.prepare(
-        `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, source, content_history, quality_score, embedding, epistemic_status, agent_scope, workspace_scope, agent_scope_source, workspace_scope_source, scope_decided_at, sensitivity, occurred_at, evidence, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+        `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, source, content_history, quality_score, embedding, epistemic_status, agent_scope, workspace_scope, agent_scope_source, workspace_scope_source, scope_decided_at, sensitivity, occurred_at, evidence, doc_path, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
       ).run(
         id,
         type,
@@ -907,6 +975,7 @@ export function createStore(path) {
         normalizeScopeText(memory.sensitivity),
         normalizeOccurredAt(memory.occurred_at),
         evidence,
+        docPath,
         now,
         now
       );
@@ -924,6 +993,12 @@ export function createStore(path) {
     if (!existing) throw new Error(`memory not found: ${id}`);
     const type = patch.type ?? existing.type;
     if (!TYPES.has(type)) throw new Error(`invalid memory type: ${type}`);
+    // #230：type 不许改入/改出 document——铸造与退役都只经 registerDocument
+    // （摘要修复走同 type 的 content/title 更新，doc_path 不在本 UPDATE 的
+    // SET 里，天然保持不变）。
+    if ((existing.type === "document") !== (type === "document")) {
+      throw new Error("memory type cannot be changed to or from 'document' (registerDocument is the only mint path)");
+    }
     if (patch.tags !== undefined && !Array.isArray(patch.tags)) {
       throw new Error("tags must be an array");
     }
@@ -1015,6 +1090,11 @@ export function createStore(path) {
     if (!existing) throw new Error(`memory not found: ${id}`);
     const type = patch.type ?? existing.type;
     if (!TYPES.has(type)) throw new Error(`invalid memory type: ${type}`);
+    // 同 update：document 类型转换在这里同样封死（CAS 路径绕过 updateMemory
+    // 的 service 守卫，必须在存储层兜住）。
+    if ((existing.type === "document") !== (type === "document")) {
+      throw new Error("memory type cannot be changed to or from 'document' (registerDocument is the only mint path)");
+    }
     if (patch.tags !== undefined && !Array.isArray(patch.tags)) {
       throw new Error("tags must be an array");
     }
@@ -1135,11 +1215,15 @@ export function createStore(path) {
   // Live memories that have not been touched since `cutMs` (never-touched ones
   // fall back to created_at). Ordered by last access ascending — the coldest
   // first. Used by sleep phase 2 to pick archival-demotion candidates.
+  // #230: document pointer rows are excluded — they are heat-immune by design
+  // (λ=0) and their "unread" state is normal (full text lives outside the DB),
+  // so the cold scan must never demote/archive them for lacking access.
   function getUnrecalledSince(cutMs, { limit = 500 } = {}) {
     const cutIso = new Date(cutMs).toISOString();
     const rows = db.prepare(
       `SELECT * FROM memories
        WHERE forgotten = 0 AND archived = 0
+         AND type <> 'document'
          AND (last_accessed_at IS NULL OR last_accessed_at < ?)
        ORDER BY COALESCE(last_accessed_at, created_at) ASC, id
        LIMIT ?`
@@ -1147,13 +1231,20 @@ export function createStore(path) {
     return rows.map(toRow);
   }
 
-  function list({ type, limit = 50, offset = 0, order = "importance", includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, minImportance = null, source = null, updatedFrom = null, updatedTo = null, occurredFrom = null, occurredTo = null, visibility = null } = {}) {
+  function list({ type, excludeTypes = null, limit = 50, offset = 0, order = "importance", includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, minImportance = null, source = null, updatedFrom = null, updatedTo = null, occurredFrom = null, occurredTo = null, visibility = null } = {}) {
     const clauses = [];
     const params = [];
     if (type) {
       clauses.push("type = ?");
       params.push(type);
     }
+    // #230：整类排除必须在 LIMIT 之前做——sleep 的模式扫描池（limit 200 +
+    // sleepPatternMinMemories 门槛）若先截断后过滤，document 行一多就会把
+    // 普通记忆挤出窗口，池子被饿空。
+    if (Array.isArray(excludeTypes) && excludeTypes.length) {
+      clauses.push(`type NOT IN (${excludeTypes.map(() => "?").join(", ")})`);
+      params.push(...excludeTypes);
+    }
     // Optional server-side filters: importance floor and exact source match.
     // Both stay out of the query when unset so existing callers are unaffected.
     if (minImportance != null) {
@@ -1227,15 +1318,20 @@ export function createStore(path) {
         "(id IN (SELECT record_id FROM receipt_chain WHERE kind IN ('merge', 'update') AND verdict = 'live') OR source = 'dream')"
       );
     }
+    // limit == null = 无界（#230 注册器的精确 supersede 全量扫描用——同路径/
+    // 同标题判定不允许窗口截断）。其余调用传数字，走 sanitizePage 默认档。
+    const unbounded = limit == null;
     const { limit: lim, offset: off } = sanitizePage(limit, offset, 50);
     const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
     // "chrono" is pure newest-first — the stable order paged browsing (month
     // tree, infinite scroll) needs; importance ordering would interleave
     // months across pages.
     const orderBy = order === "chrono" ? "updated_at DESC, id DESC" : "importance DESC, updated_at DESC, id";
-    const rows = db.prepare(
-      `SELECT * FROM memories ${where} ORDER BY ${orderBy} LIMIT ? OFFSET ?`
-    ).all(...params, lim, off);
+    const rows = unbounded
+      ? db.prepare(`SELECT * FROM memories ${where} ORDER BY ${orderBy}`).all(...params)
+      : db.prepare(
+          `SELECT * FROM memories ${where} ORDER BY ${orderBy} LIMIT ? OFFSET ?`
+        ).all(...params, lim, off);
     return rows.map(toRow);
   }
 
@@ -2368,6 +2464,9 @@ export function createStore(path) {
     count,
     getById,
     save,
+    // document 唯一铸造口（#230 写入权分离）：registerDocument 专用，通用
+    // save/update/CAS 均拒绝 document 创建或类型转换。
+    saveDocument,
     update,
     compareAndUpdate,
     remove,
@@ -2401,6 +2500,8 @@ export function createStore(path) {
     getRecallEval,
     listRecallEvals,
     saveLlmAudit,
+    getDistillCursor,
+    setDistillCursor,
     listLlmAudits,
     countLlmAudits,
     getLlmAuditStats,