@furongjun1999/dsh-memory 0.6.0 → 0.7.0

package/docs/mdcg/README/350/257/246/347/273/206/347/211/210_v0.4.10.md

@@ -559,6 +559,94 @@ npm install && npm run build     # 构建插件本身（tsc → lib/）
 
 完整示例见 [`cordis.yml.example`](../../dsh/cordis.yml.example)。
 
+### ♻️ 升级后须重启长驻 MCP 进程（代校验 · `generation`）
+
+> **运维前提（一句话）**：**代码换代 ⇒ 重启常驻 MCP 进程**。本条不是「可选优化」，是使用前提。
+
+#### 根因（已定因，第 4 条条件层）
+
+灵枢的大脑（`md_cg`）以 **stdio 长驻进程**形态接入（`python -m md_cg.mcp_server`），而
+CPython 只在模块**首次导入**时读盘：此后进程一直用内存里的模块对象。与此同时，`md_cg`
+内有**大量写在函数体内的延迟导入**（AST 实测函数内跨模块相对导入 328 处；其中相当一部分
+是**为避开循环导入**才写在函数里的）。
+
+两者叠加 ⇒ **升级后跨代混用**：升级**前**已载入的模块停留在旧代，升级**后**才被惰性导入
+的模块是新代，同一个进程里两代并存。实测症状（0.6.1 发版轮）：
+
+```
+cg 写入返回 ImportError: cannot import name 'mint_auto_id' from 'md_cg.mdcg'
+```
+
+而此刻**盘面完全正常**——新解释器导入同一模块成功、`md_cg/mdcg.py` 里就是
+`def mint_auto_id(...)`。也就是说：**报错点（延迟导入被执行的那一刻）离根因（进程停在旧代）
+很远**，不重启的话重试多少次都一样。
+
+#### 自检：对运行中的 serve 调 `cg(op=info)`
+
+响应里以**纯增量**方式多出五个键（既有键名/键值/嵌套结构一字未动），字段表如下
+（真源＝`md_cg/generation.py` 的 `generation.report()`）：
+
+| 键 | 类型 | 含义 |
+|---|---|---|
+| `code_generation` | string | 本进程**启动那一刻**的代码指纹前 12 位（＝进程实际持有的那一代） |
+| `disk_generation` | string \| null | **此刻盘面**上代码的指纹前 12 位；盘面读不到时为 `null` |
+| `stale_on_disk` | bool | 两者不同 ⇒ 磁盘代码已换代（`true`） |
+| `restart_required` | bool | 是否需要重启本进程（与 `stale_on_disk` 同真值） |
+| `hint` | string | 中文一句话处置指引（`stale_on_disk` 为真时给出「重启常驻 MCP 进程」） |
+
+判读：`stale_on_disk: true` 即「**这个进程停在旧代上**，盘面已经是新代」——重启即可。
+
+**指纹口径**（`generation.fingerprint()`）：对 `md_cg/**/*.py`（跳过 `__pycache__` 与
+`test_*.py`）按**排序后的（相对路径, 文件字节）**算 sha256，取十六进制串。用**内容哈希**
+而不是 `mtime`/`size`：打包 / 解压 / 校验回写造成的「无改动重写」会变 mtime 而不变内容，
+用 mtime 会**假报换代**、把使用者引向无谓的重启。开销（本机实测）：指纹实际只读
+**197 个非 `test_` 的 `.py`，约 10ms/次**；即使对全量 418 个 `.py` / 约 11.7 MB 做同类
+内容哈希也只需约 17ms——因此可以挂在每次 `op=info` 上。
+
+#### 启动闸：延迟导入自检（`verify_delegations()`）
+
+服务**真正开始服务之前**（`md_cg/mcp_server.py::main()` 内，非模块顶层——顶层调用会与
+函数内延迟导入的避环设计冲突），对盘面上每个「函数内相对导入」逐项做「**导入目标模块 →
+取名字**」（`importlib.import_module` 对已加载模块直接返回内存实例，所以查的是**本进程实际
+持有的那个模块**）。判定三分：
+
+| 形态 | 判定 | 处置 |
+|---|---|---|
+| 目标模块可导入、但**没有这个名字** | **致命** | 抛 `GenerationError`：拒绝启动（非零退出），stderr 点名**目标子模块 + 名字 + 引用处** |
+| 名字是**包内子模块名**而该子模块不在盘面 | 非致命 | 记入 `unavailable`（`whitebox_kb/aeis_core` 的「身体/世界模型」面就属此类：其 docstring 明写「不带走…缺失即自动降级」） |
+| **目标模块本身**不在盘面 / 导入失败 | 非致命 | 记入 `unavailable`（外部可选模块未装） |
+
+启动 stderr 会打一行读数：`代校验：延迟导入 N 项 / 目标模块 M 个 / 已解析 K 项 / 可选缺失 J 项 · 代 <12位>`。
+于是「半升级」（引用方已是新代、被引用模块还是旧代或缺文件）会在**启动期**就暴露，而不是等到
+某次写入才以 `ImportError` 的面目炸出来。注意这条自检**只查名字存在性**：不执行被导入者、
+不校验签名与行为，也不覆盖 `import x.y` 绝对导入与 `importlib.import_module("…")` 字符串形态。
+
+#### 处置
+
+**重启常驻 MCP 进程即可，记忆数据无损**：
+
+- DSH 侧：重启 DSH（或刷新 Web UI，让插件重拉大脑子进程）；
+- 其它宿主（CodeBuddy / ZCode / Codex CLI / Claude Code 等）：重连该 MCP server。
+
+盘面真源（认知图 md）一个字都没动——重启只是让进程**重新只读一代代码**。**不做热重载**：
+热重载会与函数内延迟导入的避环设计冲突，还会把已加载模块的类身份打散。
+
+#### 守卫（改这条链路必须跑）
+
+```bash
+python -X utf8 -m md_cg.test_generation_guard      # 退出码 0 ＝ 全绿
+```
+
+五项：①对当前树（逐字节临时副本）`verify_delegations()` 全绿并打印委托项数/目标模块数；
+②定点变异（临时副本里把 `mdcg.py` 的 `mint_auto_id` 定义改名）必须抛 `GenerationError`
+且消息逐字点名 `md_cg.mdcg` + `mint_auto_id`；③改一个源文件后 `is_stale()` 必须为
+`True`、恢复后必须为 `False`；④AST 断言 `generation.verify_delegations(` 的调用不在
+`mcp_server.py` 模块顶层；⑤`cg(op=info)` 键集对拍（五个新键齐备、既有 18 键一字未动）。
+守卫全程在 `tempfile.mkdtemp()` 临时目录内进行，不写工作区、不碰在役记忆库。
+
+**不适用条件**：本代校验不回答「哪一代更正确」（只回答盘面与进程是否同代，跨代一律重启）；
+不构成「所有延迟导入都能跑通」的完备证明；同一进程内改盘不会自动重载——这正是要重启的原因。
+
 ## 配置项
 
 | 字段 | 类型 | 默认值 | 说明 |
@@ -598,6 +686,12 @@ npm install && npm run build     # 构建插件本身（tsc → lib/）
 
 - `user/message`（仅 `source.kind === 'user'` 的真实用户消息）→ `MdcgClient.remember()`（`mdcg_remember(gated=true)`，importance 0.6，落层 contextual，tags `dsh`）
 - 插件注入的系统上下文（AGENTS.md、文件变更通知等 `kind: 'plugin'`）**不写入**，防止记忆噪音
+- **来源判定：子代理委派不写成本人记忆**（H1，2026-09-30）——两条判据，**都是「字段在场且取值匹配才拦」**：
+  - **会话级**（`SessionHeader`）：`origin === 'subagent'` 或 `delegationDepth > 0` ⇒ 该**子会话整条**的自动记忆都拦掉（不写、也不发起语义召回）。拦点取在会话事件回调的**最前面**，因此子代理会话也不会刷掉 `lastSession`（否则顶层会话的自动召回会拿子代理的会话去读）。
+  - **消息级**（`MessageSourceMap`）：`source.form === 'relay'`（DSH 类型面注释原文「A message another agent addressed to this one」）⇒ 该条不写，判据先于既有的 `kind !== 'user'`（不把委派判定押在 `source.kind` 单点上——若委派指令以子会话首轮提示形态进入，其 `source.kind` 就是 `'user'`，与真人输入不可分，只有会话级判据能拦）。
+  - **默认行为（显式声明）**：判据命中时**默认拦**（委派指令不是用户的长期记忆）；**字段缺失时默认放行**（不做半吊子猜测，宁可多记，不可因宿主字段缺失而静默丢真人记忆）——`header` 缺失 / 非对象、`delegationDepth` 不是数字或 ≤0、`origin` 是别的值、`source` 无 `form`，一律不拦且不报错。字段来源只在 DSH 类型面成立：`@deepseek-ai/dsh-session` 的 `types.d.ts`（`origin` / `delegationDepth`）与 `@deepseek-ai/dsh-llm` 的 `message.d.ts`（`ContextForm` 的 `'relay'`）。
+  - ⚠️ **未验证项（如实标注，勿读成「已验证委派会被拦住」）**：本机未装 DSH harness，**真实宿主是否真给子代理子会话写 `origin` / `delegationDepth`**、**委派消息是否真带 `form: 'relay'`** 这两点**只在类型面成立、未在真实会话事件上观测过**。守卫证明的是「判据在场即拦、缺失即不拦」这一可机械判定的性质（`test/h1-source-filter.test.ts`），不是真实委派行为已被观测。
+  - **已知仍可能漏的形态**（不扩大判据范围，如实记录）：若宿主既不写 `origin` / `delegationDepth`、也不给委派消息标 `form: 'relay'`，而委派指令以子会话**首轮用户提示**进入，则该条在消息面上与真人输入不可分、会话面上也没有信号 ⇒ **当前判据拦不住**（只能等宿主补齐字段）。
 - **去重 / 遗忘由 md_cg 主动遗忘闸门负责**（`mdcg_remember(gated=true)` → `MdCG.remember_gated`）：三问 → 四态 ACCEPT 落盘 / MERGE 并入既有（= 去重强化，不新增节点）/ DROP 低熵 / DEFER 待定，四种结果都写 `_forgetting.jsonl` 可审计
 - **写入通道为何走 `mdcg_remember` 而非 `cg(op=write)`**：`cg(op=write)` 先过 `audit.audit(content_kind)` —— 未声明 `content_kind`（且未配置 `MDCG_POLICY_FILE`）时恒判 BLINDSPOT/DEFER，**只进审核队列、永不落盘**；即便声明了 `content_kind`，还要再过一致性检查与 `gated` 三问四态。**落盘的充要条件是最终判定 ACCEPT**（MERGE 并入既有、DROP/DEFER/REJECT 均不新增落盘点）。插件自动记忆选 `mdcg_remember(gated=true)`，即绕开 `cg(op=write)` 的 audit 前置门、直接进入三问四态。详见「本轮修复与验证 ②」
 - **记忆以 md 文档落盘**（`mdcg.root`，默认用户级 `~/.dsh/.dsh-memory/data/mdcg`；旧版包内 `data/mdcg` 由首启一次性**复制**接手，见 `src/lib/datapath.ts` 的 `migrateLegacyData()`）；⚠️ **写权限默认关闭**——不配凭据时以只读 guest 运行：读 / 召回 / 时间线照常，写入不落盘（插件启动会告警）。打开方式见配置表 `env.MDCG_TOKEN`
@@ -606,6 +700,12 @@ npm install && npm run build     # 构建插件本身（tsc → lib/）
   - **快照去重语义（改注入方式前必读）**：注入块落在 `assembly.contexts` 里，宿主会把它渲染成一段「运行时上下文快照」，并**按渲染后的整段文本去重**——文本与上一份已提交的快照相同则不提交任何东西，不同才在会话里 `append` 一条 `user/message`（append 语义，旧快照不会被替换或移除）。
   - 因此本插件**每步都照旧 push**，内容没变也不跳过：跳过会让渲染文本在「有块 / 无块」之间跳变，反而每步各追加一份（实测 ~250 tok/份），长会话里每请求 `inject` 会随步数线性涨到 30k+ tok。
   - 压缩归档后的自愈交给宿主：宿主检测到上一份快照已被替换掉（`retained` 置空）时会重新投影当前快照，注入块自然跟着回来——不需要插件自己数步数做强制刷新。
+  - **读侧会话过滤值与写侧同尺**（H2，2026-09-30）：自动召回传给 `stg(op=timeline, session=…)` 的会话值，会先过**与写侧同一个** `_normalize_session`（单点消费：`md_cg/stg.py::_view_session`，真源仍是 `md_cg/mcp_server.py::_normalize_session`，**不重写实现**）——写侧落盘时已把 DSH 形态的会话 id 归一（`session-<uuid4>` 在会话根下**不存在**时落 `anonymous`；根不可读则 fail-soft 保原值），读侧若拿**未归一的原值**做等值比较，就会出现「同一条记忆写进去查不出」（实测 `stg(op=timeline, session=<原值>)` 恒 `count=0`，换 `session='anonymous'` 才命中）。修复只作用于「具体会话值」这一态：缺省 / `""` / `"*"` 三态语义逐位不变（跨会话视图），返回体的 `session` 回带**归一后**的生效值。守卫与端到端断言：`md_cg/test_h2_session_view_norm.py`（`python -m md_cg.test_h2_session_view_norm`）。
+  - ⚠️ **不属于本项的错位面**：`cg` 侧读路径（`search` / `recall` / `cg(op=read)`）的请求 `session` 走身份判定（issue #35 定稿「身份不可自报」，`MdCGSecure._candidates` 传 `session=None`），**不经** `_view_session`——两者不是同一个过滤，不得互相「对齐」（对齐即等于开一条按请求 session 读 private 的越权通道）。
+  - ⚠️ **残余边界（如实标注）**：部署侧用 `MDCG_SESSION` / `DSH_SESSION_ID` 把会话固定在进程 env 时，**写侧归属由 env 决定**、请求声明被否决（既有「来源优先级」语义，见 `_declared_session`），此时插件若仍拿宿主会话 id 去读本会话视图，归一后是 `anonymous` 而落盘是 env 值 ⇒ 该形态下仍读不到本会话写入；此类部署的本会话视图应传 env 会话 id（或不传，走跨会话视图）。这一条是既有「来源优先级」语义的推论，**不在本次修复范围**。
+  - **插件侧两处会话槽收口**（H2③，2026-09-30）：
+    - 宿主**未给会话标识**时，写入不再是「留空」——留空会让 md_cg 的 `Principal.__init__` 生成**进程级随机** `sess_*` 兜底桶（`md_cg/security.py:117`）：一个进程内所有无标识会话共用一桶、跨进程对不上、审计上不可辨认。改为**显式 `unassigned`** 常量：跨进程一致、可辨认、可审计，且不是伪造的宿主会话 id（非 DSH 形态，`_normalize_session` 原样采用）。要读这个桶：`stg(op=timeline, session="unassigned")`。
+    - T4 的语义召回**显式带会话槽**：调用形态由 `recall(q, 3)` 改为等价的 `read(q, {k: 3, session})`（同一条 MCP 出口 `cg(op=read)`，见 `src/lib/mdcg_client.ts` 的 recall → read）。此前不传 session，靠服务端「cg 读路径丢弃请求 session」侥幸不串台；一旦读侧归一化在召回链路上生效，不传就等价于**跨会话（全库）召回**。带上它不构成越权：cg 读路径的 session 是归因/视图维度，不参与任何授权（issue #35 定稿）。守卫：`test/h1-source-filter.test.ts` 的 E1/E2 与 `test/session-attribution.test.ts` ①②。
 
 ## 🛟 DSH 看门狗（scripts/）
 

package/docs/mdcg//345/212/237/350/203/275/350/260/203/347/224/250/346/230/240/345/260/204/350/241/250_v0.1.md

@@ -41,42 +41,42 @@ MCP stdio：md_cg/mcp_server.py
 
 | 功能 | 显式调用 | 代码位置（点击直达源码行） |
 |---|---|---|
-| 按需披露（投影后完整工具 / 参数文档即时取回） | `cg(op=help)` | [`help`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1955) → [`_help_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1874) |
-| 验证态 / 双时间轴 / 履历（含冷路径队列；只读） | `cg(op=status)` | [`status`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1961) → [`_status_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1789) |
-| 三元组反查（派生边任意端 / 谓词 / 时间反查；只读） | `cg(op=edges)` | [`edges`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1964) → [`_edges_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1845) |
-| 理论检索（领域理论 / 方法论文） | `cg(op=theory)` | [`theory`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1967) → [`theory`](../../md_cg/theory.py) |
-| 记忆互链（节点间链接管理） | `cg(op=link)` | [`link`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1984) → [`evidence`](../../md_cg/evidence.py) → [`links`](../../md_cg/links.py) → [`provenance`](../../md_cg/provenance.py) → [`security`](../../md_cg/security.py) → [`signer`](../../md_cg/signer.py) |
-| 服务信息 / 健康 | `cg(op=info)` | [`info`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2100) → [`audit`](../../md_cg/audit.py) → [`links`](../../md_cg/links.py) → [`nodefile`](../../md_cg/nodefile.py) → [`theory`](../../md_cg/theory.py) |
-| 路由：意图→知识+建议能力 | `cg(op=route)` | [`route`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2117) |
-| 读取（按 id / 召回 / 预算） | `cg(op=read)` | [`read`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2138) → [`refindex`](../../md_cg/refindex.py) |
-| 写入（含冲突检测 / 闸门 / 审核） | `cg(op=write)` | [`write`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2174) → [`writepipe`](../../md_cg/writepipe.py) |
-| 目标（写入 / 状态 / 清单） | `cg(op=goal)` | [`goal`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2182) |
-| 任务实体（登记 / 计划 / 状态 / 结果；done 无结果拒收） | `cg(op=task)` | [`task`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2201) → [`_task_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1887) |
-| 最近记忆（事件窗口） | `cg(op=recent)` | [`recent`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2204) |
-| 外部裁决回填（节点证据验证） | `cg(op=verify)` | [`verify`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2216) |
-| 审核队列（DEFER / 提案裁决） | `cg(op=review)` | [`review`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2221) |
-| 主动遗忘 / 恢复 | `cg(op=forget)` | [`forget`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2242) |
-| 保护（不可遗忘） | `cg(op=protect)` | [`protect`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2248) → [`_protect_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1130) |
-| 身份维度 | `cg(op=identity)` | [`identity`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2251) → [`_identity_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1158) |
-| 一致性检测 | `cg(op=consistency)` | [`consistency`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2254) → [`_consistency_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1209) |
-| 元认知（盲区聚合） | `cg(op=metacognition)` | [`metacognition`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2257) → [`_metacognition_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1238) |
-| 自我状态 | `cg(op=self_state)` | [`self_state`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2260) → [`_self_state_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1273) |
-| 演化（记忆结构演化） | `cg(op=evolution)` | [`evolution`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2263) → [`_evolution_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1408) |
-| 飞轮 / 自愈 | `cg(op=sustain)` | [`sustain`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2266) → [`_sustain_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1500) |
-| 洗脑 / 去污染 | `cg(op=scrub)` | [`scrub`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2269) → [`_scrub_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1609) |
-| 预测 / 因果门 | `cg(op=predict)` | [`predict`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2272) → [`_predict_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1335) |
-| 因果链 | `cg(op=causal)` | [`causal`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2275) → [`_causal_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1369) |
-| 白箱能力库（AEIS 能力显式调用） | `cg(op=whitebox)` | [`whitebox`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2278) → [`_whitebox_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2921) |
-| 代码索引 | `cg(op=index_code)` | [`index_code`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2281) → [`refindex`](../../md_cg/refindex.py) → [`security`](../../md_cg/security.py) |
-| 文档索引 | `cg(op=index_doc)` | [`index_doc`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2318) → [`refindex`](../../md_cg/refindex.py) → [`security`](../../md_cg/security.py) |
-| 引用 / 反向引用 | `cg(op=ref)` | [`ref`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2358) → [`_ref_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2841) |
-| 会话管理（多会话归属与过滤） | `cg(op=session)` | [`session`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2361) → [`_session_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2562) |
-| 导入落图 | `cg(op=ingest)` | [`ingest`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2364) → [`_ingest_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2641) |
-| 导出 | `cg(op=export)` | [`export`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2367) → [`_export_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2666) |
-| 维护 | `cg(op=maintain)` | [`maintain`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2370) → [`_maintain_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2688) |
-| 记忆固化 / 整理 | `cg(op=consolidate)` | [`consolidate`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2373) → [`_consolidate_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2766) |
-| 洞察 / 自主探索（信息差驱动） | `cg(op=insight)` | [`insight`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2376) → [`_insight_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2791) |
-| CCG 六要素编译（对话→候选→编外复核→落库） | `cg(op=ccg)` | [`ccg`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2379) → [`_ccg_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2386) |
+| 按需披露（投影后完整工具 / 参数文档即时取回） | `cg(op=help)` | [`help`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2078) → [`_help_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1996) |
+| 验证态 / 双时间轴 / 履历（含冷路径队列；只读） | `cg(op=status)` | [`status`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2084) → [`_status_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1911) |
+| 三元组反查（派生边任意端 / 谓词 / 时间反查；只读） | `cg(op=edges)` | [`edges`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2087) → [`_edges_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1967) |
+| 理论检索（领域理论 / 方法论文） | `cg(op=theory)` | [`theory`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2090) → [`theory`](../../md_cg/theory.py) |
+| 记忆互链（节点间链接管理） | `cg(op=link)` | [`link`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2107) → [`evidence`](../../md_cg/evidence.py) → [`links`](../../md_cg/links.py) → [`provenance`](../../md_cg/provenance.py) → [`security`](../../md_cg/security.py) → [`signer`](../../md_cg/signer.py) |
+| 服务信息 / 健康 | `cg(op=info)` | [`info`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2223) → [`audit`](../../md_cg/audit.py) → [`generation`](../../md_cg/generation.py) → [`links`](../../md_cg/links.py) → [`nodefile`](../../md_cg/nodefile.py) → [`theory`](../../md_cg/theory.py) |
+| 路由：意图→知识+建议能力 | `cg(op=route)` | [`route`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2264) |
+| 读取（按 id / 召回 / 预算） | `cg(op=read)` | [`read`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2285) → [`refindex`](../../md_cg/refindex.py) |
+| 写入（含冲突检测 / 闸门 / 审核） | `cg(op=write)` | [`write`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2340) → [`writepipe`](../../md_cg/writepipe.py) |
+| 目标（写入 / 状态 / 清单） | `cg(op=goal)` | [`goal`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2348) |
+| 任务实体（登记 / 计划 / 状态 / 结果；done 无结果拒收） | `cg(op=task)` | [`task`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2367) → [`_task_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2009) |
+| 最近记忆（事件窗口） | `cg(op=recent)` | [`recent`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2370) |
+| 外部裁决回填（节点证据验证） | `cg(op=verify)` | [`verify`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2382) |
+| 审核队列（DEFER / 提案裁决） | `cg(op=review)` | [`review`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2387) |
+| 主动遗忘 / 恢复 | `cg(op=forget)` | [`forget`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2408) |
+| 保护（不可遗忘） | `cg(op=protect)` | [`protect`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2414) → [`_protect_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1206) |
+| 身份维度 | `cg(op=identity)` | [`identity`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2417) → [`_identity_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1234) |
+| 一致性检测 | `cg(op=consistency)` | [`consistency`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2420) → [`_consistency_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1285) |
+| 元认知（盲区聚合） | `cg(op=metacognition)` | [`metacognition`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2423) → [`_metacognition_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1314) |
+| 自我状态 | `cg(op=self_state)` | [`self_state`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2426) → [`_self_state_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1349) |
+| 演化（记忆结构演化） | `cg(op=evolution)` | [`evolution`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2429) → [`_evolution_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1484) |
+| 飞轮 / 自愈 | `cg(op=sustain)` | [`sustain`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2432) → [`_sustain_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1576) |
+| 洗脑 / 去污染 | `cg(op=scrub)` | [`scrub`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2435) → [`_scrub_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1697) |
+| 预测 / 因果门 | `cg(op=predict)` | [`predict`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2438) → [`_predict_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1411) |
+| 因果链 | `cg(op=causal)` | [`causal`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2441) → [`_causal_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1445) |
+| 白箱能力库（AEIS 能力显式调用） | `cg(op=whitebox)` | [`whitebox`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2444) → [`_whitebox_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L3117) |
+| 代码索引 | `cg(op=index_code)` | [`index_code`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2447) → [`refindex`](../../md_cg/refindex.py) → [`security`](../../md_cg/security.py) |
+| 文档索引 | `cg(op=index_doc)` | [`index_doc`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2491) → [`refindex`](../../md_cg/refindex.py) → [`security`](../../md_cg/security.py) |
+| 引用 / 反向引用 | `cg(op=ref)` | [`ref`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2534) → [`_ref_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L3017) |
+| 会话管理（多会话归属与过滤） | `cg(op=session)` | [`session`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2537) → [`_session_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2738) |
+| 导入落图 | `cg(op=ingest)` | [`ingest`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2540) → [`_ingest_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2817) |
+| 导出 | `cg(op=export)` | [`export`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2543) → [`_export_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2842) |
+| 维护 | `cg(op=maintain)` | [`maintain`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2546) → [`_maintain_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2864) |
+| 记忆固化 / 整理 | `cg(op=consolidate)` | [`consolidate`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2549) → [`_consolidate_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2942) |
+| 洞察 / 自主探索（信息差驱动） | `cg(op=insight)` | [`insight`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2552) → [`_insight_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2967) |
+| CCG 六要素编译（对话→候选→编外复核→落库） | `cg(op=ccg)` | [`ccg`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2555) → [`_ccg_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2562) |
 
 <!-- FUNCMAP:END -->
 
@@ -95,10 +95,10 @@ MCP stdio：md_cg/mcp_server.py
 
 | 功能 | 显式调用 | 代码位置（点击直达源码行） |
 |---|---|---|
-| 两节点关系 | `stg(op=relation)` | [`relation`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2944) |
-| 时间线 | `stg(op=timeline)` | [`timeline`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2946) |
-| 锚点检索（时空窗口） | `stg(op=anchors)` | [`anchors`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2953) |
-| 时空一致性 | `stg(op=consistency)` | [`consistency`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2957) |
+| 两节点关系 | `stg(op=relation)` | [`relation`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L3140) |
+| 时间线 | `stg(op=timeline)` | [`timeline`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L3142) |
+| 锚点检索（时空窗口） | `stg(op=anchors)` | [`anchors`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L3149) |
+| 时空一致性 | `stg(op=consistency)` | [`consistency`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L3153) |
 
 <!-- FUNCMAP:END -->
 

package/docs/mdcg//345/217/221/345/270/203/351/227/250/347/246/201/351/223/276_v0.1.md

@@ -3,13 +3,22 @@
 > **背景**：第三方验证 v17 报告（§5.6）指出一个结构性窗口——**门禁写好了却不接进发布链，等于没有**。
 > 仓库已有 5 道门禁脚本，但 `prepublishOnly` 只挂 3 步，`cogmap_sync.py check` 等未接入；
 > 同一失效模式因此在 2026-09-15 与 v17（`4e2a9fc`）复发两次。
+>
+> **2026-09-30 更新（v0.6.1 发版核验）**：门禁链已由 5 条扩至 **8 条腿**——接入
+> `check_unreachable.py`（死代码扫描）与两条 **Rust 腿**（`gate_rust_crate_test.py` /
+> `gate_rust_parity.py`，批次 91 的 R-7「门禁转正」）。下表逐条与本机 `package.json`
+> 的 `scripts.gate` 实读对齐，不是复述历史文档。
+>
+> **2026-10-01 更新（出货面冒烟腿转正）**：门禁链再由 **8 条扩至 9 条腿**——新增
+> `check_publish_smoke.py`（出货面冒烟：pack → 空沙箱真装 → 从装好的目录真启动 MCP →
+> 真发 `initialize` + `tools/list`）。下表同样按 `scripts.gate` 实读对齐。
 
 ## 三层防线
 
 | 层 | 触发 | 跑什么 | 行为 |
 |---|---|---|---|
 | 本地 pre-commit | `git commit` | `python scripts/cogmap_sync.py build` | **自动重挂**行号，并把两份投影文档一并暂存 |
-| 发布链 | `npm publish` | `prepublishOnly`：build → test → **`npm run gate`**（五道门禁，见下） | 任一步失败即阻断发布 |
+| 发布链 | `npm publish` | `prepublishOnly`：build → test → **`npm run gate`**（九道门禁，见下） | 任一步失败即阻断发布 |
 | CI | push / PR | `cogmap-check.yml`：`cogmap_sync.py check` + `link_check.py` | 远端兜底红灯 |
 
 ## 为什么本地钩子跑 build 而不是 check
@@ -32,20 +41,59 @@ git config core.hooksPath scripts/git-hooks
 
 ## 发布门禁清单（`npm run gate`）
 
-`prepublishOnly` 在 build + test 之后调用 `npm run gate`，五道门禁与 CI 同形：
+`prepublishOnly` 在 build + test 之后调用 `npm run gate`，九道门禁与 CI **同形但不完全同覆盖**：
 
 | # | 命令 | 守什么 | 对应 CI |
 |---|---|---|---|
-| 1 | `python scripts/check_publish_artifact.py` | 发布件内容政策（凭据 / 私有数据 / 隐私文本 / 非追踪件） | `publish-artifact-check.yml` |
-| 2 | `python scripts/cogmap_sync.py check` | 认知图行号投影与真源一致 | `cogmap-check.yml` |
-| 3 | `python scripts/link_check.py` | 全库 md 相对链接可达 | `cogmap-check.yml` |
-| 4 | `python scripts/workspace_index.py --check` | 工作区索引不陈化（第 18 条） | `workspace-index-check.yml` |
-| 5 | `python scripts/verify_discipline.py --allow-missing` | 纪律真源 ↔ 各端产物一致 | `discipline-check.yml` |
-
-> **依赖提示**：第 5 道经 `render_discipline` 解析 `docs/discipline/harnesses.yaml`，需要
+| 1 | `python scripts/check_unreachable.py` | 控制流终止语句之后的不可达代码（拦过 s5 负记忆段与 V21-4 通道 B 两族整段静默失效） | **无**（仅本地/发布链） |
+| 2 | `python scripts/check_publish_artifact.py` | 发布件内容政策（凭据 / 私有数据 / 隐私文本 / 非追踪件） | `publish-artifact-check.yml` |
+| 3 | `python scripts/check_publish_smoke.py` | **出货面冒烟**：真 pack → 空沙箱真装 → 从装好的目录真启动 MCP → 真发 `initialize` + `tools/list`，断言工具面 == 缺省面 `['cg','stg']` | **无**（仅本地/发布链） |
+| 4 | `python scripts/cogmap_sync.py check` | 认知图行号投影与真源一致 | `cogmap-check.yml` |
+| 5 | `python scripts/link_check.py` | 全库 md 相对链接可达 | `cogmap-check.yml` |
+| 6 | `python scripts/workspace_index.py --check` | 工作区索引不陈化（第 18 条） | `workspace-index-check.yml` |
+| 7 | `python scripts/verify_discipline.py --allow-missing` | 纪律真源 ↔ 各端产物一致 | `discipline-check.yml` |
+| 8 | `python scripts/gate_rust_crate_test.py` | `cargo test` @ `rust/`（Rust 侧口径漂移的回归保障） | **无**（`hive-check.yml` 只跑 `hive/Cargo.toml`，`rust/` 至今零 CI） |
+| 9 | `python scripts/gate_rust_parity.py` | `scripts/rank_parity.py` 逐位对拍（Python `search_rrf` vs Rust `mdcg-eval --serve`） | **无** |
+
+> **第 3 道的位序不是随意的**：它紧跟第 2 道（同为「发布件面」），且**必须在第 4 道
+> `cogmap_sync.py check` 之前**——前者的 `npm pack` 会触发 `prepare`（= 本仓的 `tsc` 构建，
+> 会重写 `lib/`），越靠近链首越能让「包面自检」与「包已定形」两件事挨着发生；塞在链尾则
+> 成了跑完一圈 Rust 之后才验包，失败反馈距离最远。位序由
+> `scripts/test_publish_smoke_guard.py` 的 C2 断言钉死（挪到链尾即红）。
+
+### 为什么需要第 3 道（同类缺陷已漏两次）
+
+第 1–9 道里的**任何一道都拦不住「仓库里在、包里不在」**：第 2 道 `check_publish_artifact`
+扫的是**包内件的内容政策**（凭据 / 私有数据 / 隐私 / 非追踪）——一个必要件**整体缺席**时
+它没有任何可扫的对象，照样 VERDICT=PASS。实测两次同族事故：
+
+- **#38**：`scripts/` 与 `hive/` 整目录未被 `files` 收录（源码树工具在包里不存在）；
+- **issue #48**（0.6.1）：仓根 `utf8_boot.py` 未被 `files` 收录 ⇒ 装机后
+  `python -m md_cg.mcp_server` 在 `from utf8_boot import ensure_utf8` 处 ModuleNotFoundError，
+  **装机即挂**（修法= `files` 加 `utf8_boot.py`，提交 `52677077`；修完之后**仍无任何机器检查
+  能拦住同类**，本道即该缺口的机器化收口）。
+
+第 3 道的判据面（`S0`–`S6`，名字即机器读面，详见 `scripts/check_publish_smoke.py`）：S1 出货清单**点名**
+含仓根 `utf8_boot.py`（缺则打印「修法：files 加 utf8_boot.py」）、S2/S3 装好的目录里点名
+`utf8_boot.py` 与 `md_cg/mcp_server.py`、S4 真握手拿到 `serverInfo`、S5 `tools` **等于**
+缺省面 `['cg','stg']`、S6 策略来源来自**包内** `data/policy.json`（只记录不判负）。
+沙箱缺省 `tempfile.mkdtemp()`（跑完清理）；env `MDCG_GATE_SANDBOX_DIR` 给定时改用该目录并
+**保留不删**（便于人工复核）。npm 解析复用 `check_publish_artifact.resolve_npm()` 单点
+（Windows 命中 `npm.cmd`，不经 `cmd /c`）；探不到 npm 即 fail-closed 退出码 1，**不静默 SKIP**。
+
+> **诚实边界（第 3 道不覆盖什么）**：不覆盖 DSH 桥侧（`dsh/` 插件与 MCP 客户端的接线）、
+> 不覆盖真实 DSH 安装路径（装的是空沙箱里的 `node_modules`）、不覆盖 peer 依赖解析
+> （安装加 `--legacy-peer-deps` 跳过 peer）、不覆盖 `MDCG_MCP_SURFACE=full` 的多工具面
+> （只测缺省面）、不覆盖 TypeScript 侧 `lib/` 的运行时行为。
+
+> **依赖提示**：第 7 道经 `render_discipline` 解析 `docs/discipline/harnesses.yaml`，需要
 > **PyYAML**（CI 里显式 `python -m pip install pyyaml`）。本机缺 PyYAML 时 gate 会硬失败——
 > 那是门禁正常工作，装依赖即可，不是误报。
 
+> **诚实边界（勿读成「CI 全兜底」）**：第 1、3、8、9 道**没有对应 CI workflow**——远端不跑、
+> 只有本地与 `npm publish` 会拦。Rust 侧的回归保障目前只存在于发布链这一处；
+> 若要远端兜底，须新增 workflow（`rust/**` 触发 + 装 cargo 工具链）。
+
 发布前可单独跑 `npm run gate` 自检。
 
 ## 不适用条件

package/docs/mdcg//347/201/265/346/236/242/350/256/260/345/277/206/345/212/250/350/257/215/345/215/217/350/256/256_v1.0-draft.md

@@ -30,7 +30,9 @@ DSH 内建基元 / 第三方客户端）**各自实现客户端而不必读源
 
 `ok` 与 `committed` **分离**是本协议对客户端最有价值的一条：它表达
 「**闸门行为 ≠ 工具故障**」——`ok=True, committed=False` 是校验闸门正常短路
-（REJECT / DEFER / 冲突），**重试同样结果**，客户端不应重试而应读 `hint`。
+（REJECT / DEFER / 冲突），客户端不应重试而应读 `hint`；`hint` 再区分
+**不可修正**（政策违规，「重试同样结果」）与**可修正**（缺必需要素，按清单补齐后重写，
+见 §4.3）。
 
 ## 3 动词总览
 
@@ -72,7 +74,10 @@ DSH 内建基元 / 第三方客户端）**各自实现客户端而不必读源
 | `gate_hard_reject` | 契约缺失硬拒（依赖声明闸 E050/E051） | 三键 + `gate`, `error`, `hint` | `missing`, `verdict` |
 | `gate_gated` | 主动遗忘闸（`gated=true`） | 三键 + `gate`, `verdict` | `consistency`, `moved_to`, `propagation` |
 
-`hint` 的语义固定为：**闸门正常行为、不是工具故障、重试同样结果**（并给出下一步 op）。
+`hint` 的语义固定为：**闸门正常行为、不是工具故障**（并给出下一步 op）。分型见下——
+「重试同样结果」只适用于**不可修正**的拒收（命中禁止规则＝内容政策违规）；**缺必需要素**
+（CCG 六要素不全，由规则库 `required` / `required_kinds` 定义）是**可修正**的拒收：
+hint 列出缺失清单与「补齐后重写即可」，`verdict.detail.missing` 给出结构化清单。
 
 ### 4.4 `forget`
 

package/docs/mdcg//347/235/241/347/234/240/345/221/250/346/234/237_/350/277/220/347/273/264/345/211/215/346/217/220/344/270/216/347/273/264/346/212/244/346/214/207/345/215/227_v1.0.md

@@ -0,0 +1,183 @@
+# 睡眠周期 · 运维前提与维护指南（v1.0）
+
+> **这一页回答一件事：开了睡眠周期之后，你的记忆库多了什么、在哪里、怎么维护、怎么关、怎么退。**
+> 依据：`docs/plans/睡眠与自迭代_功能优化设计_v0.4.md`（规格冻结版）§四 / §4.7。
+> 使用者裁定（2026-10-01，第三轮）：「进行登记，让用户知道怎么维护记忆」。
+
+---
+
+## 一、睡眠周期是什么（一句话）
+
+灵枢的**自迭代**（八步闭环的第 5 固化 / 6 记录 / 8 方向性自检）与**睡眠整理**合成一条周期引擎：在**睡眠时段**内，用**一个副本**做归纳 / 升层 / 巩固 / 权重与索引重建，完成后**周期性合并**回主库，并**留下修改历史**。
+
+**为什么用副本**：整理期间主库的**真源面**（八个层目录下的 `.md`）逐字节不变——长驻进程（serve / 蜂巢 / 会话）继续正常读写，整理结果只在合并那一刻以**受闸门约束**的方式落回。
+
+---
+
+## 二、版本库在哪里（唯一的"新增物"）
+
+| 项 | 位置 | 说明 |
+|---|---|---|
+| **版本库（git 目录）** | `<state_root>/sleep/lib.git` | **在数据根之外**。用 `git --git-dir` 显式指定，**不在你的记忆库里放 `.git`** |
+| **影子工作树** | `<state_root>/sleep/shadow` | 整理实际发生的地方；每轮以 `git worktree` 建在分支 `sleep/<时间戳>` 上 |
+| **台账** | `<state_root>/sleep/` 下的轮次记录 | 每轮九步的逐步读数、语义差异集 Δ、冲突清单 |
+
+**版本库只覆盖真源面**：那八个层目录下的 `.md`。以下**结构性进不去**（用显式路径白名单而非 ignore 面保证）：
+`_keys.json`（密钥信封）· `_access.log` · `_index.json` · `_index_log/` · `*.tmp`（临时件）· `*.lock`（锁件）。
+⇒ **密钥与运行态从设计上就不可达**，不是"记得排除"。
+
+---
+
+## 三、维护动作（你要知道的四条）
+
+### 1. 看历史
+
+```bash
+git --git-dir=<state_root>/sleep/lib.git --work-tree=<root> log --oneline
+```
+
+一条睡眠周期 = **两个提交**：先是**内容提交**（语义重放落主库的那一刻，台账里记作 `round_commit`），随后是 `--no-ff` 的**合并提交**（只记拓扑，其树与内容提交同）。
+
+### 2. 看某一轮改了什么
+
+```bash
+git --git-dir=<state_root>/sleep/lib.git --work-tree=<root> show <round_commit>
+```
+
+逐节点的 before/after 另有 `_maintain.jsonl` 同族留痕（与权重重算共用一套）。
+
+### 3. 回退（**只提供 `revert`**）
+
+```bash
+git --git-dir=<state_root>/sleep/lib.git --work-tree=<root> revert <round_commit>
+```
+
+**要 revert 的是该轮的「内容提交」**（台账 `phases.merge.round_commit`）——合并提交只是拓扑记录，对它 `revert -m 1` 对内容零影响（git 会报 nothing added to commit）。
+
+**裁定（第三轮）：只给 `revert`，不提供 `reset --hard`。** 理由：`revert` 出一个**新提交**——历史不丢、可追、可再次审计；`reset --hard` 会抹掉历史，与「留下修改历史」的裁定相反。
+回退是**显式发起**的动作，睡眠周期**永不自动回退**。
+
+### 4. 冲突怎么处理
+
+合并阶段若发现**主库与影子改了同一个 id**（或命中保护闸 / tombstone 闸 / 生命周期闸），该项**挂起**：**不自动解决**、**不写入主库**，出一个冲突清单等人处理（与蜂巢工作记忆 `hive/wm.py` 的既有裁决同款：冲突手交人工）。
+
+> 一句话：**git 只做记录者，准入由仓内既有闸门裁决**。所以「合并成功」不等于"git 没冲突"，而是"过了语义四闸"。
+
+---
+
+## 四、开关与可调项（全部可调）
+
+| env | 缺省 | 语义 |
+|---|---|---|
+| `MDCG_SLEEP` | `1`（开） | 睡眠周期总开关；设 `0` 即整条周期不再启动 |
+| `MDCG_SLEEP_INTERVAL` | `3600` | 周期（秒），缺省一小时一次 |
+| `MDCG_SLEEP_WINDOW` | `23:00-07:00` | **睡眠时段**（本地时间）；**支持跨午夜**；留空 = 全时段；**窗口外只记账、不迭代** |
+| `MDCG_SLEEP_MERGE` | `auto` | 合并策略：`auto`（自动执行四阶段）/ `ask`（合并前询问）/ `never`（只留副本不合并）。**`auto` 下冲突仍挂起** |
+| `MDCG_SLEEP_GITDIR` | 空 | 覆盖版本库位置（缺省 `state_root()/sleep/lib.git`） |
+| `MDCG_SLEEP_SHADOW` | 空 | 覆盖影子工作树位置（缺省 `state_root()/sleep/shadow`） |
+| `MDCG_SLEEP_SCRUB_APPLY` | `0` | 第④步「去污染实改」的闸门；**缺省只盘点不落盘** |
+| `MDCG_TEMPORAL_GAMMA` | `ln2/30天` | 时间邻近度的衰减率（半衰期 30 天，与既有 `links.py` 同刻度）；可调 |
+| `MDCG_CHAIN_TYPES` | 空 | **因果路沿哪些边类型扩散**（逗号分隔，大小写不敏感）。留空 = 缺省集 `causal,sequential,applies_to`。**这一项决定因果路在语料库上有没有东西可走**：从文档/叙事语料切出来的节点只有 `reference` 与父章节结构边，**没有 causal 边**，所以对这种库要显式设成 `MDCG_CHAIN_TYPES=reference,part_of`（或含 `sequential`）——否则因果路恒空。只接受 `chain.EDGE_WEIGHTS` 里已登记的类型，未登记形态会被剔除并回落缺省集 |
+| `MDCG_SUSTAIN` | `1` | 常驻自维持循环总开关（睡眠周期挂在它上面） |
+
+> **整条关掉**：`MDCG_SLEEP=0`；**连常驻循环一起关**：`MDCG_SUSTAIN=0`。
+
+---
+
+## 五、自动的边界（哪些永不自动）
+
+| 动作 | 可自动 | 依据 |
+|---|---|---|
+| 归纳 / 升层 / 权重重算 / 索引重建 | ✅ | 确定性、可预演、可回滚；索引是派生物 |
+| 去污染**实改** | ⚠ 缺省关（`MDCG_SLEEP_SCRUB_APPLY=0`） | 在副本上可放行，合并前可复核 |
+| **任何依赖 LLM 的固化** | ❌ **永不自动** | 依赖 LLM 的动作交人工另批 |
+| **任何不可回滚的删除** | ❌ **永不自动** | 五环承诺：遗忘只能由显式 `cg(op=forget)` 发起 |
+| 方向性自检 | ✅ 只产**记录** | 理论纪律：自检结果**不自动触发修改** |
+
+**「合并前可复核」在缺省配置下由什么保证**：缺省 `MDCG_SLEEP_MERGE=auto` 会在**同一轮**内把已过闸的改动一并落主库，所以严格的「合并前人工看一眼」窗口只由 `MDCG_SLEEP_MERGE=ask` 提供。另外**去污染实改缺省就是关的**（`MDCG_SLEEP_SCRUB_APPLY=0`），所以缺省配置下最具侵入性的那一档根本不会落盘——要用它，请显式开启并配 `ask` 档。
+
+**窗口值写错了会怎样**：`MDCG_SLEEP_WINDOW` **留空**＝全时段（这是唯一的显式全时段入口）；**非法形态**（例如 `23:00-99:99`）按同表 `INTERVAL`/`MERGE` 的既有回落口径**回落缺省 `23:00-07:00`**——不会因为打错字而变成全天迭代。
+
+---
+
+## 六、健康读数（每轮都留）
+
+每轮睡眠在台账里留：①盘点候选数 ②本轮语义差异集 Δ 的大小 ③过了四闸多少、挂起多少 ④是否空轮（候选 0 ⇒ 只记账不动手）⑤九步逐步读数（未接线的步骤显式标 `skipped`）。
+
+`cg(op=sustain, action=status)` 可看到最近几轮。
+
+---
+
+## 七、前提一句话总结
+
+> 睡眠周期会在 `<state_root>/sleep/lib.git` 建一个**只覆盖真源面**的版本库，用它做**副本迭代 + 周期合并**，合并准入走仓内既有语义闸门（不是 git 的文本合并），回退只给 `revert`，冲突挂起等人处理。**密钥与运行态结构性进不去这个版本库。**
+
+---
+
+## 八、P2 / P4 落地后的检索与权重变化（2026-10-01 · 发版披露）
+
+> 依据：`docs/plans/睡眠与自迭代_功能优化设计_v0.4.md` §5.1–§5.4 / §七。
+> **这一节是「默认检索读数变了」的对外说明**——改动前基线与改动后读数见
+> `scripts/p2p4_probe.py`（同一命令在改前 worktree 与改后工作区各跑一次）。
+
+### 1. 六要素后两行进默认检索（§5.4）
+
+`# 验证方式`（后置条件词）与 `# 不适用条件`（拒绝域词）现在进**索引条目**
+（`postcondition_terms` / `rejection_terms`，与 `time_window` 同款「免读文件」扁指标量），
+并进**默认检索路径**：
+
+- 问「**怎么验证的 / 用什么方法证明**」或查询词命中验证手段 ⇒ 召回声明了该手段的节点；
+- 问「**什么条件下不适用 / 何时不适用**」⇒ 召回**声明了拒绝域**的节点，结果卡带
+  `boundary_hit` 标记（`meta.boundary` 里有独立计数）；
+- **普通问句下拒绝域仍不作召回键**（反例命中只由资格判定处置）——灵敏度一字不动。
+
+**拒绝域双语义**：边界命中（`boundary_hit`）与资格 `REJECT` 是**两件事**，
+分开计数、分开呈现；「问它什么时候不适用」不会把节点自己打成 REJECT。
+
+**口径提醒（务必知道）**：`mdcg_recall` 的缺省**融合口径是 `max`**（因因果路缺省进路），
+这影响**所有**默认召回调用，**与库里有没有边无关**；要 `sum`（经典 RRF 求和）请显式传
+`fusion="sum"`。（这是设计稿 §6.2 的既定口径，本批**补披露**，行为未变。）
+
+### 2. 权重刷新与衰减进主分数（§七）
+
+检索分数现在是：`score ← score × cred_factor(γ, Δt) × refresh(访问计数)`。
+
+| env | 缺省 | 语义 |
+|---|---|---|
+| `MDCG_FRESHNESS` | `1`（开） | 刷新/衰减乘子总开关；**设 `0` 即回到改动前口径**（与既有部署逐位一致，是「可回退」的第一道闸） |
+| `MDCG_FRESHNESS_NOW` | 空 | 参照时刻（unix 秒）。**只为守卫/探针的确定性**；留空 = 系统时钟 |
+| `MDCG_TEMPORAL_GAMMA` | `ln2/30天` | 衰减率（与时间路同一读取点） |
+
+三条必须知道的语义：
+
+1. **老记忆会被降权**（这正是「召回被旧的历史记忆干扰」的处置）：未被调用的记忆按
+   `ln2/30 天` 半衰期衰减，下限 `0.001`（floor，不会归零到不可召回）；被经常调用的
+   记忆按 AEIS `consolidate_cycle` 的既有门槛刷新（`access_count % 10 == 0` 且
+   `last_access > 0` 才 +1%）。
+2. **保护线不会被衰减穿过**：受保护节点（`importance ≥ 0.70`）的衰减乘子有下界
+   `0.70 / importance` ⇒ `importance × 乘子 ≥ 0.70` 恒成立，节点不会因衰减
+   **自动失去保护**。
+3. **不可遗忘 ≠ 不可覆盖；降级不是删除**：`freshness.recalc(apply=True)` 只写
+   `freshness_weight` 与 `freshness_state="degraded"` 标记，**从不删节点**；要跨层
+   降级走既有 `_move_layer`（内含 `protect.guard_move`，受保护节点需显式 `override`）。
+
+**粒度说明（本批的一处取舍）**：Δt 以**整日**为粒度（向下取整）。理由：γ 的单位本来
+就是「天」；仓内有「同查询两轮结果逐位一致 / 可复算」的硬纪律，不量化则分数会随
+系统时钟逐轮微变；量化后两侧（Python / Rust）在同一「天」桶上恒同值。量化损失上界 =
+γ × 1 天 ≈ 2.3%。
+
+**回滚（三件套，与权重重算同款）**：预演 `freshness.recalc(apply=False)` →
+逐节点 before/after 落 `_maintain.jsonl`（`action="freshness"`）→
+反向 `freshness.rollback(batch=...)`。AEIS 侧**没有**预演与回滚，这是移植时的净增。
+
+### 3. 读侧语言面的已知边界（**不要**把对拍 10/10 当成已对齐）
+
+| 侧 | 缺省路集 | 说明 |
+|---|---|---|
+| Python | **6 路**：lexical / bucket / entity / graph / chain / temporal | 生产读面 |
+| Rust | **4 路**：lexical / bucket / entity / graph | 评测/嵌入读面，**尚未**实现 chain/temporal 与六要素后两行索引键 |
+
+`scripts/rank_parity.py` 现在仍报 10/10，**只因其语料无 edges / 无时间参数 /
+无六要素后两行声明**（缺省差异在这类语料上不可观测）——它是「两侧同口径下逐位一致」
+的证据，**不是**「两侧已对齐」的证据。P4 乘子的两侧逐位对拍另配了**有判别力**的夹具
+（同分不同龄的节点，见 `md_cg/test_p4_freshness.py` 的 G12）。