@modusensus/dsh-mneme 0.13.0 → 0.14.0-beta.2

package/docs/CONTINUITY.md

@@ -1,139 +1,139 @@
-# dsh-mneme 压缩边缘抢救（issue #249 N3）
-
-- **日期**：2026-09-24
-- **状态**：✅ 已实现（opt-in，默认关）
-- **范围**：上下文即将被宿主压缩前，抢救「正在做什么」，让它活过这次压缩
-- **相关文档**：[存储与回收](STORAGE.md)（同批的 #275 第一批） · [语义增强](SEMANTIC.md)
-
-## 1. 问题
-
-宿主的压缩摘要器只看对话里的内容：压缩时它按固定字段模板重建对话（Current Work /
-Next Step / Critical Context 等），**系统提示段里的东西不进这次重建**。所以任何"只放在
-提示段里的工作状态"，一过压缩就等于没写过。
-
-## 2. 形态：必须双落点
-
-| 落点 | 去处 | 为什么不能省 |
-|---|---|---|
-| ① 落提案 | `continuity_proposals` 表（`src/store.js`） | 脱离对话独立存活；注入失败/被跳过也不丢工作状态 |
-| ② 追加消息 | 序列末尾一条 `user/message`（`source: {kind: "plugin", plugin: "dsh-mneme"}`） | 这是唯一能进宿主摘要器重建范围的落点 |
-
-落库先于注入。落点顺序由宿主契约保证：压缩插件在自己那一步先压缩、再 `return next()`，
-所以我们在 `agent/pre-step` 拿到 `next()` 结果时压缩事件已落库；而我们返回的
-`decision.messages` 由宿主在本步末尾以 `surfaceOp: "append"` 追加，晚于压缩的
-`surfaceOp: "replace"`——追加物天然在压缩之后、靠近序列末尾。
-
-注入文本是**结构化快照**（统一前缀 + 三行固定字段，整条 ≤900 字符），不是 §6.3 那种
-≤160B 的单行提醒——那条上限约束的是"一句话提醒"，不约束固定字段的快照；字段内部的换行
-仍会被压平成空格，保证它仍是一条消息。**判重按当前表面**（`session.surface.nodes`），
-不按全量日志：被一次压缩折叠出表面的旧快照还在 append-only 日志里，照日志判重会让这次
-该补的注入静默跳过。
-
-## 3. 触发
-
-**不自定阈值**，就是订阅宿主真的压缩（都在宿主的事件白名单里）。理由：「压缩边缘」由宿主
-定义，我们再校准一份阈值参数只会与之漂移，还多一份没人维护的旋钮。
-
-**但「发过压缩事件」不等于「这段历史真的被折叠了」**：宿主的压缩插件在**每一步**都会试一次
-（`agent/pre-step` 里的 `compactIfNeeded`），而代理层（如 billion-context）会拒掉原生压缩。
-一次失败的尝试什么都没折叠，不需要抢救 —— 按「试过就救」记账，触发器就退化成「每步一次」。
-所以只认**内容真的被移除过**的三种事件（判定在 `src/continuity.js` 的 `isCompactionEdge`）：
-
-| 事件 | 算不算边缘 | 为什么 |
-|---|---|---|
-| `compaction/summary` | ✅ | 宿主压缩成功才落（`dsh-compaction-basic` 的 `commitCompactionBody`） |
-| `compaction/prune` | ✅ | 宿主把超预算的旧 tool/result 折叠出表面 —— 「表面真的变短了」最直接的证据 |
-| `compaction/end` **不带 error** | ✅ | 成功路的收尾 |
-| `compaction/end` **带 error** | ❌ | 成败两条路都发这个事件，失败路额外带 `error`；整笔事务失败 |
-| `compaction/start` | ❌ | 只是开锁标记（「有人试过」） |
-
-本机实测（2026-10-14，两个长会话、12,000+ 事件，原生压缩被 100% 拒绝）：按 `start|summary|end`
-记账置位 1,287 / 2,895 次，改成「真落地」后降到 39 / 161 次。
-
-DSH 没有 in-memory 消息改写钩子，所以本机制一律是「注入 + 序号引用寻址」，**不改写
-历史消息本体**。
-
-## 4. 字段与抽取口径
-
-固定三字段（不用自由散文），全程不调模型、纯确定性抽取（`src/continuity.js`）：
-
-| 字段 | 来源 | 截断 |
-|---|---|---|
-| `current_work` | 最近一条**真实** `user/message`（插件注入与子代理上报不算用户指令） | 头部 200 字符 |
-| `next_step` | 最近一条 `assistant/message` | **尾部** 200 字符（下一步活在末尾那句里） |
-| `open_questions` | 恒 `null` | —— |
-
-「哪些问题还没解决」判不出就是判不出，硬猜会给出似是而非的字段；空字段在注入文本里
-如实标 `(none)`。这个字段留给转正通道与人工补。
-
-字段名以 #249 §6.2 为准（`current_work` / `next_step` / `open_questions`）。§4.4 里的
-Current Work / Next Step / Critical Context 是**宿主压缩模板**的字段名，不是这张表的列名
-（规格里两处用词不同，实现取 §6.2）。
-
-## 5. 存储与生命周期
-
-```
-continuity_proposals(id, session_id, kind, current_work, next_step, open_questions,
-                     status, edge_seq, created_at, updated_at)
-UNIQUE (session_id, kind)   -- 「同一会话同一类只留一条」：再次触发是刷新，不是新增
-```
-
-- `kind`：`compaction-edge`（一次会话里这一类只留一条）。
-- `status`：`pending`（本批唯一写入态）→ 未来 `promoted` / `discarded`（转正通道与
-  #254 的二次确认共用一套，阶段二才打开）。
-- **队列满则弃新**（`MAX_CONTINUITY_PENDING = 200`）：达上限丢掉本次触发，而不是淘汰
-  旧行——旧行是别的会话还没转正的工作状态，用「更近的边缘」把它挤掉是反的。满队列
-  不影响已有行的刷新。
-- 丢弃会**留痕**（`agent/pre-step` 监听器 `logger.warn`）：弃新属于"静默失效"，不报出来
-  的话 §8 的触发率口径会把它算成"没触发"。
-- **本批没有回收路径**：`status` 只写 `pending`，`maintenance`/`reclaim` 不碰这张表，
-  所以 200 是上限——满了之后新会话不再落行，直到转正通道打开（阶段二）。判定是进程内的
-  （先查计数再写），两个宿主共用同一 `memoryDir` 时可能各自都看到未满，实际越过 200 条。
-- `edge_seq` 记最近一次触发的压缩事件序号，是「实际触发率」的证据。
-- 落库失败只告警、不抛：可选插件的故障不该把宿主的这一步变成失败，而注入那一半不依赖
-  库，照做。
-
-指标口径（#249 §8 要求触发率/采纳率可统计）：实际触发率 = 提案行数；采纳率 =
-`promoted` / 全部。两者都是就地读表，不需要额外打点。
-
-## 6. 开关
-
-| 层级 | 键 | 默认 |
-|---|---|---|
-| 父 | `autoInject` | 开（既有总闸） |
-| 子 | `continuityRescueEnabled` | **关**（引入新注入表面，按 #249 §10 判据独立成键） |
-
-父关则子不生效（`injectChildEnabled`）；轻量档默认置关（`applyLightModePreset`
-把它算进 `LIGHT_MODE_OFF`），但那只是默认值——装配时按「用户开关 > 轻量预设 >
-bundle 配置」合并，用户在面板里显式勾选仍然赢。面板落点在 `lib/client.js`
-的 `FEATURE_CHILDREN` / `FEATURE_GROUPS`（该文件无 src 对应物），跨文件关系由
-`test/inject-parent-gate.test.js` 逐个断言钉住。
-
-## 7. 降级路径（不要求宿主加接口）
-
-宿主若不提供可挂钩的压缩前时机，双落点里的 ② 就没有触发者。这时**不算失败**：把规则
-写成持久规则交给 agent 自判（`src/guide.js` 的 `CONTINUITY_TOOL_RULE`，挂在
-`memory_save` 的工具描述尾部——常驻文本、零注入成本，只在子开关开启时出现）。
-
-本批**不做宿主能力探测**（没有可靠的探测口，宿主也没有暴露"有没有压缩前时机"这个事实），
-所以子开关打开时这条规则就常驻，与 ② 并存——两者不是互斥的备选，而是同一个开关下的两层：
-② 在宿主真的压缩时自动生效，持久规则在 agent 自己判断"上下文要炸了"时兜底。
-
-## 8. 已知坑
-
-- **判重只能做到「同一份文本不追加第二次」**。没有改写钩子，就不能删掉表面里已经存在
-  的那条旧快照；内容一变就是新的一份（旧的那份随宿主压缩自然消失）。这是形态上限，
-  不是实现偷懒。
-- **注入物不得变成记忆**：追加消息用 `source.kind = "plugin"`，`summarize.js` 的
-  `collectMessages` 会跳过它——否则注入物会被下一轮蒸馏成记忆，形成自我强化。
-- **`open_questions` 恒 null** 是刻意留白，不是没实现。
-
-## 9. 验收锚点
-
-`test/continuity.test.js` 逐条锁形态（不是锁文案）：抽取口径（头/尾方向、插件消息跳过、
-插件消息是最后一条 `user/message` 时仍被跳过）、渲染（统一前缀、单行、`none`、整条上限）、
-唯一键刷新（`created_at` 不动、幂等 UPSERT）、队列满弃新且不影响刷新、丢弃留痕、
-pre-step 双落点与一次性消费、同文本不重复追加（按当前表面）、被折叠出表面的旧注入要补、
-落库失败不打断宿主的一步、`reject` 放行且不消费边缘、缺 session 不抛、dispose 后不再动作、
-默认关 + 父关不生效 + 轻量档压掉 + 降级规则只在开启时进描述、门控不调模型（静态锁）、
-存量库重开即建表。
+# dsh-mneme 压缩边缘抢救（issue #249 N3）
+
+- **日期**：2026-09-24
+- **状态**：✅ 已实现（opt-in，默认关）
+- **范围**：上下文即将被宿主压缩前，抢救「正在做什么」，让它活过这次压缩
+- **相关文档**：[存储与回收](STORAGE.md)（同批的 #275 第一批） · [语义增强](SEMANTIC.md)
+
+## 1. 问题
+
+宿主的压缩摘要器只看对话里的内容：压缩时它按固定字段模板重建对话（Current Work /
+Next Step / Critical Context 等），**系统提示段里的东西不进这次重建**。所以任何"只放在
+提示段里的工作状态"，一过压缩就等于没写过。
+
+## 2. 形态：必须双落点
+
+| 落点 | 去处 | 为什么不能省 |
+|---|---|---|
+| ① 落提案 | `continuity_proposals` 表（`src/store.js`） | 脱离对话独立存活；注入失败/被跳过也不丢工作状态 |
+| ② 追加消息 | 序列末尾一条 `user/message`（`source: {kind: "plugin", plugin: "dsh-mneme"}`） | 这是唯一能进宿主摘要器重建范围的落点 |
+
+落库先于注入。落点顺序由宿主契约保证：压缩插件在自己那一步先压缩、再 `return next()`，
+所以我们在 `agent/pre-step` 拿到 `next()` 结果时压缩事件已落库；而我们返回的
+`decision.messages` 由宿主在本步末尾以 `surfaceOp: "append"` 追加，晚于压缩的
+`surfaceOp: "replace"`——追加物天然在压缩之后、靠近序列末尾。
+
+注入文本是**结构化快照**（统一前缀 + 三行固定字段，整条 ≤900 字符），不是 §6.3 那种
+≤160B 的单行提醒——那条上限约束的是"一句话提醒"，不约束固定字段的快照；字段内部的换行
+仍会被压平成空格，保证它仍是一条消息。**判重按当前表面**（`session.surface.nodes`），
+不按全量日志：被一次压缩折叠出表面的旧快照还在 append-only 日志里，照日志判重会让这次
+该补的注入静默跳过。
+
+## 3. 触发
+
+**不自定阈值**，就是订阅宿主真的压缩（都在宿主的事件白名单里）。理由：「压缩边缘」由宿主
+定义，我们再校准一份阈值参数只会与之漂移，还多一份没人维护的旋钮。
+
+**但「发过压缩事件」不等于「这段历史真的被折叠了」**：宿主的压缩插件在**每一步**都会试一次
+（`agent/pre-step` 里的 `compactIfNeeded`），而代理层（如 billion-context）会拒掉原生压缩。
+一次失败的尝试什么都没折叠，不需要抢救 —— 按「试过就救」记账，触发器就退化成「每步一次」。
+所以只认**内容真的被移除过**的三种事件（判定在 `src/continuity.js` 的 `isCompactionEdge`）：
+
+| 事件 | 算不算边缘 | 为什么 |
+|---|---|---|
+| `compaction/summary` | ✅ | 宿主压缩成功才落（`dsh-compaction-basic` 的 `commitCompactionBody`） |
+| `compaction/prune` | ✅ | 宿主把超预算的旧 tool/result 折叠出表面 —— 「表面真的变短了」最直接的证据 |
+| `compaction/end` **不带 error** | ✅ | 成功路的收尾 |
+| `compaction/end` **带 error** | ❌ | 成败两条路都发这个事件，失败路额外带 `error`；整笔事务失败 |
+| `compaction/start` | ❌ | 只是开锁标记（「有人试过」） |
+
+本机实测（2026-10-14，两个长会话、12,000+ 事件，原生压缩被 100% 拒绝）：按 `start|summary|end`
+记账置位 1,287 / 2,895 次，改成「真落地」后降到 39 / 161 次。
+
+DSH 没有 in-memory 消息改写钩子，所以本机制一律是「注入 + 序号引用寻址」，**不改写
+历史消息本体**。
+
+## 4. 字段与抽取口径
+
+固定三字段（不用自由散文），全程不调模型、纯确定性抽取（`src/continuity.js`）：
+
+| 字段 | 来源 | 截断 |
+|---|---|---|
+| `current_work` | 最近一条**真实** `user/message`（插件注入与子代理上报不算用户指令） | 头部 200 字符 |
+| `next_step` | 最近一条 `assistant/message` | **尾部** 200 字符（下一步活在末尾那句里） |
+| `open_questions` | 恒 `null` | —— |
+
+「哪些问题还没解决」判不出就是判不出，硬猜会给出似是而非的字段；空字段在注入文本里
+如实标 `(none)`。这个字段留给转正通道与人工补。
+
+字段名以 #249 §6.2 为准（`current_work` / `next_step` / `open_questions`）。§4.4 里的
+Current Work / Next Step / Critical Context 是**宿主压缩模板**的字段名，不是这张表的列名
+（规格里两处用词不同，实现取 §6.2）。
+
+## 5. 存储与生命周期
+
+```
+continuity_proposals(id, session_id, kind, current_work, next_step, open_questions,
+                     status, edge_seq, created_at, updated_at)
+UNIQUE (session_id, kind)   -- 「同一会话同一类只留一条」：再次触发是刷新，不是新增
+```
+
+- `kind`：`compaction-edge`（一次会话里这一类只留一条）。
+- `status`：`pending`（本批唯一写入态）→ 未来 `promoted` / `discarded`（转正通道与
+  #254 的二次确认共用一套，阶段二才打开）。
+- **队列满则弃新**（`MAX_CONTINUITY_PENDING = 200`）：达上限丢掉本次触发，而不是淘汰
+  旧行——旧行是别的会话还没转正的工作状态，用「更近的边缘」把它挤掉是反的。满队列
+  不影响已有行的刷新。
+- 丢弃会**留痕**（`agent/pre-step` 监听器 `logger.warn`）：弃新属于"静默失效"，不报出来
+  的话 §8 的触发率口径会把它算成"没触发"。
+- **本批没有回收路径**：`status` 只写 `pending`，`maintenance`/`reclaim` 不碰这张表，
+  所以 200 是上限——满了之后新会话不再落行，直到转正通道打开（阶段二）。判定是进程内的
+  （先查计数再写），两个宿主共用同一 `memoryDir` 时可能各自都看到未满，实际越过 200 条。
+- `edge_seq` 记最近一次触发的压缩事件序号，是「实际触发率」的证据。
+- 落库失败只告警、不抛：可选插件的故障不该把宿主的这一步变成失败，而注入那一半不依赖
+  库，照做。
+
+指标口径（#249 §8 要求触发率/采纳率可统计）：实际触发率 = 提案行数；采纳率 =
+`promoted` / 全部。两者都是就地读表，不需要额外打点。
+
+## 6. 开关
+
+| 层级 | 键 | 默认 |
+|---|---|---|
+| 父 | `autoInject` | 开（既有总闸） |
+| 子 | `continuityRescueEnabled` | **关**（引入新注入表面，按 #249 §10 判据独立成键） |
+
+父关则子不生效（`injectChildEnabled`）；轻量档默认置关（`applyLightModePreset`
+把它算进 `LIGHT_MODE_OFF`），但那只是默认值——装配时按「用户开关 > 轻量预设 >
+bundle 配置」合并，用户在面板里显式勾选仍然赢。面板落点在 `lib/client.js`
+的 `FEATURE_CHILDREN` / `FEATURE_GROUPS`（该文件无 src 对应物），跨文件关系由
+`test/inject-parent-gate.test.js` 逐个断言钉住。
+
+## 7. 降级路径（不要求宿主加接口）
+
+宿主若不提供可挂钩的压缩前时机，双落点里的 ② 就没有触发者。这时**不算失败**：把规则
+写成持久规则交给 agent 自判（`src/guide.js` 的 `CONTINUITY_TOOL_RULE`，挂在
+`memory_save` 的工具描述尾部——常驻文本、零注入成本，只在子开关开启时出现）。
+
+本批**不做宿主能力探测**（没有可靠的探测口，宿主也没有暴露"有没有压缩前时机"这个事实），
+所以子开关打开时这条规则就常驻，与 ② 并存——两者不是互斥的备选，而是同一个开关下的两层：
+② 在宿主真的压缩时自动生效，持久规则在 agent 自己判断"上下文要炸了"时兜底。
+
+## 8. 已知坑
+
+- **判重只能做到「同一份文本不追加第二次」**。没有改写钩子，就不能删掉表面里已经存在
+  的那条旧快照；内容一变就是新的一份（旧的那份随宿主压缩自然消失）。这是形态上限，
+  不是实现偷懒。
+- **注入物不得变成记忆**：追加消息用 `source.kind = "plugin"`，`summarize.js` 的
+  `collectMessages` 会跳过它——否则注入物会被下一轮蒸馏成记忆，形成自我强化。
+- **`open_questions` 恒 null** 是刻意留白，不是没实现。
+
+## 9. 验收锚点
+
+`test/continuity.test.js` 逐条锁形态（不是锁文案）：抽取口径（头/尾方向、插件消息跳过、
+插件消息是最后一条 `user/message` 时仍被跳过）、渲染（统一前缀、单行、`none`、整条上限）、
+唯一键刷新（`created_at` 不动、幂等 UPSERT）、队列满弃新且不影响刷新、丢弃留痕、
+pre-step 双落点与一次性消费、同文本不重复追加（按当前表面）、被折叠出表面的旧注入要补、
+落库失败不打断宿主的一步、`reject` 放行且不消费边缘、缺 session 不抛、dispose 后不再动作、
+默认关 + 父关不生效 + 轻量档压掉 + 降级规则只在开启时进描述、门控不调模型（静态锁）、
+存量库重开即建表。

package/docs/DAEMON.md

@@ -1,57 +1,57 @@
-# dsh-mneme 独立服务(daemon)
-
-`dsh-mneme-serve`:在 DSH 宿主之外把 mneme 跑成一个常驻数据面。#363(Mneme Bridge)确立的方向——第三方集成需要长期挂载,而 DSH 不必一直开着;这是官方推荐姿势,lib 直挂的 embedded 模式降级为无网兜底。
-
-## 1. 职责边界
-
-daemon 是**数据面**,不是第二个宿主:
-
-- **有**:存储(SQLite)、检索(关键词 + BM25 + 向量,`/search` 统一召回,与宿主共用 `src/semantic.js` 同一套装配)、注入候选(`/context`,issue #370,与宿主注入管线同一份 `injectCandidates`)、镜像同步与人改合并、`/maintenance/reclaim`、`/share`(记忆分享包,纯读,见 [SHARE.md](SHARE.md))、`/receive` 与 `/receive/undo`(吃包入库与整包退出,车道 C;写的是**本机自己的库**,与 `/share` 同一条 4 MiB 入站上限)、`/bootstrap`、recall_runs 检索/注入回执。
-- **没有(第一期,无 LLM)**:巩固(autoDream)、蒸馏(autoSummarize)、实体抽取、sleep、注入/工具/面板路由。前两者是**结构性缺失**而非开关——daemon 装配里没有 LLM 句柄,巩固只属于 DSH 宿主进程。这就是 daemon 与宿主「单写者」的机械保证(AGENTS.md externalApi/autoDream 单侧纪律的 daemon 版),不依赖用户自觉。
-- **收包在 daemon 上付的是什么**:一个事务里逐条先查 `share_external_id` 再 `store.save`,嵌入随最外层 COMMIT 排空(`--embed local` 时真打向量,`off` 时只落结构),镜像重渲染照 daemon 自己那条回灌路走。**实体一个都不建**——不是 daemon 缺 LLM 才不建,车道 C 对外来行本来就不做抽取(有向量、无实体,实体与图检索看不见它们),宿主侧同样如此。成本的量级读数见 [SHARE.md](SHARE.md)「收侧」那一节实测。
-
-与宿主装配(`src/index.js` apply)的关系:`src/serve.js` 只搬数据面那一半,每步注释锚定 index.js 来源行号;刻意不抽公共装配函数(apply 其余环节与宿主 ctx 纠缠,防御段纪律「最后动或不动」)。装配漂移风险由 `test/serve-bin.test.js` 的多进程共存用例兜底(两进程真开同一个库互写互读)。
-
-## 2. 对外接口
-
-路由面 = `src/api-standalone.js` 全表(health/status/profile/rules/memories 读写/`/memory/provenance`(记忆级 / 会话级溯源读出口,#421+#524)/search/context/share/receive(含 `/receive/undo`)/maintenance/bootstrap),鉴权同源(Bearer + timingSafeEqual,`GET /health` 免鉴权)。daemon 自身零新路由;#370 的 `/context` 落在 api-standalone 工厂里,宿主外部访问与 daemon 自动同享(参数、scope 语义与 recall_runs 注入分账见包 README 路由表)。daemon 侧唯一自有选项是 `strictPort`(见 §4)。
-
-`/memory/provenance` 的开关门(#509 评审整改):这个面返回蒸馏窗口的**逐条会话原文**,所以它吃 `distillRecords.enabled`——与写侧 `src/summarize.js:988` 同一枚开关、同一个判据表达式(读侧唯一一份在 `src/provenance-http.js` 的 `isDistillRecordsEnabled`)。关着时回 `409 {"error":"distill-records-disabled"}`,不是 404(本端点刻意不就「这条记忆是否存在」作断言:未知 id 是 200 + 空 windows),也不是 503(那是「装配没接线」,`src/index.js:589-591` 立的可区分性原则)。状态码阶梯:`401` 无 token → `400` 缺参(`missing-id` / `ambiguous-id` / `invalid-limit`) → `409` 功能关了 → `503` 装配没接线(按方向判) → `200`。
-
-两个读方向共用同一条路径(#524 补上方向 2):`?id=<memoryId>` 是「这条记忆派生自哪些窗口」,`?sessionId=<sid>` 是「这个会话蒸出了哪些窗口」;两个主键**互斥**,都缺与都给都回 400(择一等于让调用方发一个自己也不知道会读哪个主键的请求,而两边的结果形状不同)。方向 2 必须带 `limit`(默认 20、上限 100)——按会话读是这张脸里天然最容易放大的方向,一个会话几十个窗口、每个窗口都是整段逐字原文,不限量就是「按会话导出全量转录」,与 `/export` 同量级只是换了形状;撞上限时答复带 `truncated: true`,少了这个读数,被截断的答复与「本来就这么少」逐字节相同。方向 2 的窗口按 `(session_id, seq_start, seq_end)` 合并成一行 `GROUP BY`,带 `link_count`——一条蒸馏窗口通常产出多条记忆,逐链接返回会让「这个会话蒸了几次」被重复行淹没。daemon 读的是**面板持久化的开关**(`serve.js` 把 `feature_flags` 里的 `distillRecords.enabled` 展开进 cfg,与宿主 `index.js:217-233` 同款),与宿主共用同一个 memory.db、同一份 kv——所以用户在面板里开着,daemon 这一面就读得到。
-
-`/memory/provenance` 的响应形状(#512):窗口在 `session_id/seq_start/seq_end/created_at/records` 之外另带 `distill_run_id / run_type / trigger_source / run_status`(读不到整轮归因时整组 `null`,不从区间或时间戳反推),答复级再带 `mints[]`(行级归因:这条记忆出生自哪一轮 dream/sleep)。归因元数据不受 `distillRecords.enabled` 约束——它不含任何会话正文,所以开关关着时这个端点照旧 409,但库里那两张表仍在记账。
-
-残留不对称要知道:daemon 结构上看不到宿主的 **bundle config**(第一期不吃宿主 config schema),所以「只写在部署侧 bundle 配置里打开、从没在面板点过」的用户,宿主认、daemon 不认——daemon 会对每个请求回 409。这不是故障,是 daemon 装配面的已知边界;要让 daemon 也认,去面板里把开关显式打开一次(面板的「待重启」提示同样适用:开关是启动快照,改完要重启才生效)。
-
-`/context` 的档位信号(#383):响应多一个 `tier`(`full` 语义档 / `degraded` 规则档 / `unknown` 语义路未启用或判不出来,fail-closed),**具体降级原因只在 stderr**——`dsh-mneme: /context degraded to the rule tier (<reason>)`,不进响应体。原因是给运维的读数,六值互不吞并(成例「修法不同就分开」):`embed-unavailable` 无可用接口(embedder 对象在、缺 `embedSingle`/`embed`,修适配器)/ `embed-empty` 空向量 / `embed-timeout` 挂起 / `embed-error` 抛错 / `embed-dimension` 维度不符(有向量但没有一条与查询同维,修法是重建索引)/ `no-embedder` 压根没装配 embedder(`--embed off` / lightMode / 宿主未装配,**预期态不是故障**,修法是把嵌装扮上或开起来)。`tier` 是给调用方的读数,两套消费者分开;六值的唯一真源是 `src/api-standalone.js` 的 `CONTEXT_DEGRADE_REASONS`,契约测试从它派生。`unknown` 之下(维度探针没跑成 / 有行却一条向量都读不出来)另有一行 `dsh-mneme: /context tier left unknown: <what>`,**不是**那六值的一员(`tier` 不是 degraded,没有降级原因可记),运维程序不要按原因枚举解析它——没有它,调用方对 unknown 的策略是「不告警」时,一次真实的判档故障会整个消失。`no-embedder` 不并进 `embed-unavailable` 是故意的:那两者共用「语义路没通」的结果,但一个是适配器坏了(异常)、一个是语义路没开(设计内常态),并成一个值会让按 `embed-unavailable` 告警的面板对每个轻量模式安装报警;用词则与宿主面 `/api/dsh-mneme/semantic` 的 `reason` 对齐(那边是另一套枚举、另一个消费者,别顺手统一)。这里最值得盯的是 `embed-dimension`:嵌入接口一切正常,但库里是旧维度向量,`searchVector` 直接跳过、不抛错,召回静默退回关键词档——修法是重建索引,不是查端点。判档有成本:`q` 非空且装了 embedder 时一次 `/context` 会真起一次查询嵌入(一次往返 + `embedTimeoutMs` 窗口),维度探针本身是**按匹配短路的存在性判据**(有没有一条活跃向量与查询同维,不是 `LIMIT 1` 读一行——混合维度库里那会抽错维误报 degraded、首条损坏又会漏报 full):一次无 `LIMIT` 的全 id 扫描 + 短路解析,同维度健康库只解析 1 个向量,只有要报 degraded 时才走完全表;不复用 `/health`(它只回 `{ok:true}`)也不做全表扫。
-
-CLI:
-
-```bash
-dsh-mneme-serve [--memory-dir <dir>] [--port <n>] [--host <addr>] [--embed <provider>]
-```
-
-- `memoryDir`:CLI > env `DSH_MNEME_MEMORY_DIR` > `~/.dsh/memory`(与宿主 config.js 同默认,支持前导 `~`)。
-- `--embed`:语义检索提供方。`local`(默认:自管 runtime 与嵌入模型缺失时**自动取件**,download 档,约 200MB;失败降级关键词并打可操作日志)| `ollama` | `openai`(读宿主面板存的 vector-config)| `off`(纯关键词 + BM25)。取件来源可用 env 换道:`DSH_MNEME_RUNTIME_DIR`(自管 runtime 目录)、`DSH_MNEME_RUNTIME_TARBALL_DIR`(离线 .tgz 目录,优先于联网)、`DSH_MNEME_RUNTIME_MIRROR`(registry 镜像前缀)。
-- port/host 解析链与宿主「外部访问」一致:显式参数 > kv `external_api` 持久值 > 默认 8790 / 127.0.0.1。
-- token 与 DSH 面板 / CLI **共用同一份**(kv `external_api`,首次启动自动生成并持久化)——三方零配置互通。
-- 安全:daemon 使用明文 HTTP,不提供原生 TLS。指定非回环 `--host` 时,请勿直接把服务暴露给不可信网络;远程访问请走 TLS 终止代理或 SSH 隧道。
-- stdout 只在就绪时打一行 `dsh-mneme-serve listening on http://host:port (pid N)`(机器可读,脚本/测试解析端口用);日志全走 stderr。
-- SIGINT/SIGTERM 优雅收库后 exit 0;Windows 强杀由 WAL 回放兜底。
-
-## 3. 内部文件
-
-- `src/serve.js` — `createServeRuntime({memoryDir, port, host, logger, strictPort, embed, embedder, reranker})`:装配链 createStore → createSettings → createMirror → createService(最小 config)→ recoverMirror → 人改镜像合并闭包 → vectorIndex + semantic → recall recorder → createMaintenance → createStandaloneApi(带 `embedder: embedder ?? semantic?.embedder ?? null`,供 `/context` 查询嵌入),每步锚定 index.js 行号。返回 `{api, store, service, settings, maintenance, semantic, tokenExisted, dispose}`;第三方可 import 它自行托管生命周期(bin 只是薄壳),`embedder/reranker` 参数供注入自管嵌入。
-- `src/semantic.js` — embedder/reranker 装配 + boot 自动回填,**纯搬移自 index.js**(PR2),宿主与 daemon 共用同一份;`backfillMissingEmbeddings` 经 index.js barrel 再出口(测试照旧从 index.js import)。
-- `bin/dsh-mneme-serve.mjs` — CLI 壳。独立成 bin 而非 cli.mjs 子命令:CONTRIBUTING 禁止给 cli.mjs 加 import;命名循 dsh-mneme-mcp 先例。
-- `src/api-standalone.js` 的 `strictPort` 选项 — daemon 自己引入的唯一数据面改动,默认关闭(daemon 侧显式传 true)。#370 起该工厂另增 `/context` 路由与可选 `embedder` 注入,宿主外部访问同享。
-
-## 4. 已知坑
-
-1. **端口互斥,二选一**:daemon 与 DSH 的「外部访问」抢同一个默认端口。daemon 侧 strictPort 报错退出;反方向( daemon 先占 8790,DSH 后开外部访问)宿主侧会**静默顺延**到下一端口(宿主旁路的多实例恢复语义,api-standalone.js listenWithRetry)——面板显示的端口会变,别当 bug 报。
-2. **双进程写并发**:与 DSH 同时运行是设计内场景(WAL + busy_timeout 先序,store.js createStore)。但 `saveWithDedupe` 的 (type,title,scope) 去重是先查后写、库层无 UNIQUE 约束,两进程并发写同一三元组有极小概率产生重复条目——已知限制,勿当强保证宣传(要不要加 UNIQUE 索引属 schema 防御段,单独决策)。
-3. **镜像双写竞态**:daemon 与宿主都会渲镜像 .md;可再生物,失败由 recoverMirror 自愈,极端并发下单文件可能短暂脏,下次同步覆盖。
-4. **版本偏斜**:库迁移是幂等加法式(PRAGMA 检查 + ALTER),旧代码读新 schema 一般无碍,但该组合无人测过——daemon 与插件请同版本升级。
-5. **第一期不吃宿主配置**:daemon 不加载 config schema(schemastery 是宿主 peer 依赖),面板/feature_flags 对它不生效;它只有 CLI 参数 + 上述固定最小 config(`language: zh`、document 子系统关闭;语义键默认值逐键锚定 config.js,见 `src/serve.js` 的 `daemonSemanticCfg`)。`--embed local` 首次启动会自动取件 runtime + 模型(均有日志);取件/嵌入失败统一降级关键词 + BM25,不影响读写。
-6. **验收锚点**:`test/serve.test.js`(in-process 全链路 + token 复用 + recall_runs 回执 + 注入假 embedder 的向量轴锁)、`test/serve-bin.test.js`(真子进程 + 多进程互写互读)、`test/standalone-api.test.js` 的 strictPort 用例(busy → reject,默认路径仍顺延)、`test/reindex-backfill.test.js`(semantic 纯搬移后宿主行为不变)。
+# dsh-mneme 独立服务(daemon)
+
+`dsh-mneme-serve`:在 DSH 宿主之外把 mneme 跑成一个常驻数据面。#363(Mneme Bridge)确立的方向——第三方集成需要长期挂载,而 DSH 不必一直开着;这是官方推荐姿势,lib 直挂的 embedded 模式降级为无网兜底。
+
+## 1. 职责边界
+
+daemon 是**数据面**,不是第二个宿主:
+
+- **有**:存储(SQLite)、检索(关键词 + BM25 + 向量,`/search` 统一召回,与宿主共用 `src/semantic.js` 同一套装配)、注入候选(`/context`,issue #370,与宿主注入管线同一份 `injectCandidates`)、镜像同步与人改合并、`/maintenance/reclaim`、`/share`(记忆分享包,纯读,见 [SHARE.md](SHARE.md))、`/receive` 与 `/receive/undo`(吃包入库与整包退出,车道 C;写的是**本机自己的库**,与 `/share` 同一条 4 MiB 入站上限)、`/bootstrap`、recall_runs 检索/注入回执。
+- **没有(第一期,无 LLM)**:巩固(autoDream)、蒸馏(autoSummarize)、实体抽取、sleep、注入/工具/面板路由。前两者是**结构性缺失**而非开关——daemon 装配里没有 LLM 句柄,巩固只属于 DSH 宿主进程。这就是 daemon 与宿主「单写者」的机械保证(AGENTS.md externalApi/autoDream 单侧纪律的 daemon 版),不依赖用户自觉。
+- **收包在 daemon 上付的是什么**:一个事务里逐条先查 `share_external_id` 再 `store.save`,嵌入随最外层 COMMIT 排空(`--embed local` 时真打向量,`off` 时只落结构),镜像重渲染照 daemon 自己那条回灌路走。**实体一个都不建**——不是 daemon 缺 LLM 才不建,车道 C 对外来行本来就不做抽取(有向量、无实体,实体与图检索看不见它们),宿主侧同样如此。成本的量级读数见 [SHARE.md](SHARE.md)「收侧」那一节实测。
+
+与宿主装配(`src/index.js` apply)的关系:`src/serve.js` 只搬数据面那一半,每步注释锚定 index.js 来源行号;刻意不抽公共装配函数(apply 其余环节与宿主 ctx 纠缠,防御段纪律「最后动或不动」)。装配漂移风险由 `test/serve-bin.test.js` 的多进程共存用例兜底(两进程真开同一个库互写互读)。
+
+## 2. 对外接口
+
+路由面 = `src/api-standalone.js` 全表(health/status/profile/rules/memories 读写/`/memory/provenance`(记忆级 / 会话级溯源读出口,#421+#524)/search/context/share/receive(含 `/receive/undo`)/maintenance/bootstrap),鉴权同源(Bearer + timingSafeEqual,`GET /health` 免鉴权)。daemon 自身零新路由;#370 的 `/context` 落在 api-standalone 工厂里,宿主外部访问与 daemon 自动同享(参数、scope 语义与 recall_runs 注入分账见包 README 路由表)。daemon 侧唯一自有选项是 `strictPort`(见 §4)。
+
+`/memory/provenance` 的开关门(#509 评审整改):这个面返回蒸馏窗口的**逐条会话原文**,所以它吃 `distillRecords.enabled`——与写侧 `src/summarize.js:988` 同一枚开关、同一个判据表达式(读侧唯一一份在 `src/provenance-http.js` 的 `isDistillRecordsEnabled`)。关着时回 `409 {"error":"distill-records-disabled"}`,不是 404(本端点刻意不就「这条记忆是否存在」作断言:未知 id 是 200 + 空 windows),也不是 503(那是「装配没接线」,`src/index.js:589-591` 立的可区分性原则)。状态码阶梯:`401` 无 token → `400` 缺参(`missing-id` / `ambiguous-id` / `invalid-limit`) → `409` 功能关了 → `503` 装配没接线(按方向判) → `200`。
+
+两个读方向共用同一条路径(#524 补上方向 2):`?id=<memoryId>` 是「这条记忆派生自哪些窗口」,`?sessionId=<sid>` 是「这个会话蒸出了哪些窗口」;两个主键**互斥**,都缺与都给都回 400(择一等于让调用方发一个自己也不知道会读哪个主键的请求,而两边的结果形状不同)。方向 2 必须带 `limit`(默认 20、上限 100)——按会话读是这张脸里天然最容易放大的方向,一个会话几十个窗口、每个窗口都是整段逐字原文,不限量就是「按会话导出全量转录」,与 `/export` 同量级只是换了形状;撞上限时答复带 `truncated: true`,少了这个读数,被截断的答复与「本来就这么少」逐字节相同。方向 2 的窗口按 `(session_id, seq_start, seq_end)` 合并成一行 `GROUP BY`,带 `link_count`——一条蒸馏窗口通常产出多条记忆,逐链接返回会让「这个会话蒸了几次」被重复行淹没。daemon 读的是**面板持久化的开关**(`serve.js` 把 `feature_flags` 里的 `distillRecords.enabled` 展开进 cfg,与宿主 `index.js:217-233` 同款),与宿主共用同一个 memory.db、同一份 kv——所以用户在面板里开着,daemon 这一面就读得到。
+
+`/memory/provenance` 的响应形状(#512):窗口在 `session_id/seq_start/seq_end/created_at/records` 之外另带 `distill_run_id / run_type / trigger_source / run_status`(读不到整轮归因时整组 `null`,不从区间或时间戳反推),答复级再带 `mints[]`(行级归因:这条记忆出生自哪一轮 dream/sleep)。归因元数据不受 `distillRecords.enabled` 约束——它不含任何会话正文,所以开关关着时这个端点照旧 409,但库里那两张表仍在记账。
+
+残留不对称要知道:daemon 结构上看不到宿主的 **bundle config**(第一期不吃宿主 config schema),所以「只写在部署侧 bundle 配置里打开、从没在面板点过」的用户,宿主认、daemon 不认——daemon 会对每个请求回 409。这不是故障,是 daemon 装配面的已知边界;要让 daemon 也认,去面板里把开关显式打开一次(面板的「待重启」提示同样适用:开关是启动快照,改完要重启才生效)。
+
+`/context` 的档位信号(#383):响应多一个 `tier`(`full` 语义档 / `degraded` 规则档 / `unknown` 语义路未启用或判不出来,fail-closed),**具体降级原因只在 stderr**——`dsh-mneme: /context degraded to the rule tier (<reason>)`,不进响应体。原因是给运维的读数,六值互不吞并(成例「修法不同就分开」):`embed-unavailable` 无可用接口(embedder 对象在、缺 `embedSingle`/`embed`,修适配器)/ `embed-empty` 空向量 / `embed-timeout` 挂起 / `embed-error` 抛错 / `embed-dimension` 维度不符(有向量但没有一条与查询同维,修法是重建索引)/ `no-embedder` 压根没装配 embedder(`--embed off` / lightMode / 宿主未装配,**预期态不是故障**,修法是把嵌装扮上或开起来)。`tier` 是给调用方的读数,两套消费者分开;六值的唯一真源是 `src/api-standalone.js` 的 `CONTEXT_DEGRADE_REASONS`,契约测试从它派生。`unknown` 之下(维度探针没跑成 / 有行却一条向量都读不出来)另有一行 `dsh-mneme: /context tier left unknown: <what>`,**不是**那六值的一员(`tier` 不是 degraded,没有降级原因可记),运维程序不要按原因枚举解析它——没有它,调用方对 unknown 的策略是「不告警」时,一次真实的判档故障会整个消失。`no-embedder` 不并进 `embed-unavailable` 是故意的:那两者共用「语义路没通」的结果,但一个是适配器坏了(异常)、一个是语义路没开(设计内常态),并成一个值会让按 `embed-unavailable` 告警的面板对每个轻量模式安装报警;用词则与宿主面 `/api/dsh-mneme/semantic` 的 `reason` 对齐(那边是另一套枚举、另一个消费者,别顺手统一)。这里最值得盯的是 `embed-dimension`:嵌入接口一切正常,但库里是旧维度向量,`searchVector` 直接跳过、不抛错,召回静默退回关键词档——修法是重建索引,不是查端点。判档有成本:`q` 非空且装了 embedder 时一次 `/context` 会真起一次查询嵌入(一次往返 + `embedTimeoutMs` 窗口),维度探针本身是**按匹配短路的存在性判据**(有没有一条活跃向量与查询同维,不是 `LIMIT 1` 读一行——混合维度库里那会抽错维误报 degraded、首条损坏又会漏报 full):一次无 `LIMIT` 的全 id 扫描 + 短路解析,同维度健康库只解析 1 个向量,只有要报 degraded 时才走完全表;不复用 `/health`(它只回 `{ok:true}`)也不做全表扫。
+
+CLI:
+
+```bash
+dsh-mneme-serve [--memory-dir <dir>] [--port <n>] [--host <addr>] [--embed <provider>]
+```
+
+- `memoryDir`:CLI > env `DSH_MNEME_MEMORY_DIR` > `~/.dsh/memory`(与宿主 config.js 同默认,支持前导 `~`)。
+- `--embed`:语义检索提供方。`local`(默认:自管 runtime 与嵌入模型缺失时**自动取件**,download 档,约 200MB;失败降级关键词并打可操作日志)| `ollama` | `openai`(读宿主面板存的 vector-config)| `off`(纯关键词 + BM25)。取件来源可用 env 换道:`DSH_MNEME_RUNTIME_DIR`(自管 runtime 目录)、`DSH_MNEME_RUNTIME_TARBALL_DIR`(离线 .tgz 目录,优先于联网)、`DSH_MNEME_RUNTIME_MIRROR`(registry 镜像前缀)。
+- port/host 解析链与宿主「外部访问」一致:显式参数 > kv `external_api` 持久值 > 默认 8790 / 127.0.0.1。
+- token 与 DSH 面板 / CLI **共用同一份**(kv `external_api`,首次启动自动生成并持久化)——三方零配置互通。
+- 安全:daemon 使用明文 HTTP,不提供原生 TLS。指定非回环 `--host` 时,请勿直接把服务暴露给不可信网络;远程访问请走 TLS 终止代理或 SSH 隧道。
+- stdout 只在就绪时打一行 `dsh-mneme-serve listening on http://host:port (pid N)`(机器可读,脚本/测试解析端口用);日志全走 stderr。
+- SIGINT/SIGTERM 优雅收库后 exit 0;Windows 强杀由 WAL 回放兜底。
+
+## 3. 内部文件
+
+- `src/serve.js` — `createServeRuntime({memoryDir, port, host, logger, strictPort, embed, embedder, reranker})`:装配链 createStore → createSettings → createMirror → createService(最小 config)→ recoverMirror → 人改镜像合并闭包 → vectorIndex + semantic → recall recorder → createMaintenance → createStandaloneApi(带 `embedder: embedder ?? semantic?.embedder ?? null`,供 `/context` 查询嵌入),每步锚定 index.js 行号。返回 `{api, store, service, settings, maintenance, semantic, tokenExisted, dispose}`;第三方可 import 它自行托管生命周期(bin 只是薄壳),`embedder/reranker` 参数供注入自管嵌入。
+- `src/semantic.js` — embedder/reranker 装配 + boot 自动回填,**纯搬移自 index.js**(PR2),宿主与 daemon 共用同一份;`backfillMissingEmbeddings` 经 index.js barrel 再出口(测试照旧从 index.js import)。
+- `bin/dsh-mneme-serve.mjs` — CLI 壳。独立成 bin 而非 cli.mjs 子命令:CONTRIBUTING 禁止给 cli.mjs 加 import;命名循 dsh-mneme-mcp 先例。
+- `src/api-standalone.js` 的 `strictPort` 选项 — daemon 自己引入的唯一数据面改动,默认关闭(daemon 侧显式传 true)。#370 起该工厂另增 `/context` 路由与可选 `embedder` 注入,宿主外部访问同享。
+
+## 4. 已知坑
+
+1. **端口互斥,二选一**:daemon 与 DSH 的「外部访问」抢同一个默认端口。daemon 侧 strictPort 报错退出;反方向( daemon 先占 8790,DSH 后开外部访问)宿主侧会**静默顺延**到下一端口(宿主旁路的多实例恢复语义,api-standalone.js listenWithRetry)——面板显示的端口会变,别当 bug 报。
+2. **双进程写并发**:与 DSH 同时运行是设计内场景(WAL + busy_timeout 先序,store.js createStore)。但 `saveWithDedupe` 的 (type,title,scope) 去重是先查后写、库层无 UNIQUE 约束,两进程并发写同一三元组有极小概率产生重复条目——已知限制,勿当强保证宣传(要不要加 UNIQUE 索引属 schema 防御段,单独决策)。
+3. **镜像双写竞态**:daemon 与宿主都会渲镜像 .md;可再生物,失败由 recoverMirror 自愈,极端并发下单文件可能短暂脏,下次同步覆盖。
+4. **版本偏斜**:库迁移是幂等加法式(PRAGMA 检查 + ALTER),旧代码读新 schema 一般无碍,但该组合无人测过——daemon 与插件请同版本升级。
+5. **第一期不吃宿主配置**:daemon 不加载 config schema(schemastery 是宿主 peer 依赖),面板/feature_flags 对它不生效;它只有 CLI 参数 + 上述固定最小 config(`language: zh`、document 子系统关闭;语义键默认值逐键锚定 config.js,见 `src/serve.js` 的 `daemonSemanticCfg`)。`--embed local` 首次启动会自动取件 runtime + 模型(均有日志);取件/嵌入失败统一降级关键词 + BM25,不影响读写。
+6. **验收锚点**:`test/serve.test.js`(in-process 全链路 + token 复用 + recall_runs 回执 + 注入假 embedder 的向量轴锁)、`test/serve-bin.test.js`(真子进程 + 多进程互写互读)、`test/standalone-api.test.js` 的 strictPort 用例(busy → reject,默认路径仍顺延)、`test/reindex-backfill.test.js`(semantic 纯搬移后宿主行为不变)。