@furongjun1999/dsh-memory 0.6.1 → 0.7.1

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()` 临时目录内进行，不写工作区、不碰在役记忆库。
+
+**不适用条件**：本代校验不回答「哪一代更正确」（只回答盘面与进程是否同代，跨代一律重启）；
+不构成「所有延迟导入都能跑通」的完备证明；同一进程内改盘不会自动重载——这正是要重启的原因。
+
 ## 配置项
 
 | 字段 | 类型 | 默认值 | 说明 |

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#L2054) → [`_help_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1972) |
-| 验证态 / 双时间轴 / 履历（含冷路径队列；只读） | `cg(op=status)` | [`status`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2060) → [`_status_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1887) |
-| 三元组反查（派生边任意端 / 谓词 / 时间反查；只读） | `cg(op=edges)` | [`edges`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2063) → [`_edges_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1943) |
-| 理论检索（领域理论 / 方法论文） | `cg(op=theory)` | [`theory`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2066) → [`theory`](../../md_cg/theory.py) |
-| 记忆互链（节点间链接管理） | `cg(op=link)` | [`link`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2083) → [`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#L2199) → [`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#L2225) |
-| 读取（按 id / 召回 / 预算） | `cg(op=read)` | [`read`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2246) → [`refindex`](../../md_cg/refindex.py) |
-| 写入（含冲突检测 / 闸门 / 审核） | `cg(op=write)` | [`write`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2301) → [`writepipe`](../../md_cg/writepipe.py) |
-| 目标（写入 / 状态 / 清单） | `cg(op=goal)` | [`goal`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2309) |
-| 任务实体（登记 / 计划 / 状态 / 结果；done 无结果拒收） | `cg(op=task)` | [`task`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2328) → [`_task_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1985) |
-| 最近记忆（事件窗口） | `cg(op=recent)` | [`recent`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2331) |
-| 外部裁决回填（节点证据验证） | `cg(op=verify)` | [`verify`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2343) |
-| 审核队列（DEFER / 提案裁决） | `cg(op=review)` | [`review`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2348) |
-| 主动遗忘 / 恢复 | `cg(op=forget)` | [`forget`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2369) |
-| 保护（不可遗忘） | `cg(op=protect)` | [`protect`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2375) → [`_protect_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1194) |
-| 身份维度 | `cg(op=identity)` | [`identity`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2378) → [`_identity_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1222) |
-| 一致性检测 | `cg(op=consistency)` | [`consistency`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2381) → [`_consistency_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1273) |
-| 元认知（盲区聚合） | `cg(op=metacognition)` | [`metacognition`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2384) → [`_metacognition_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1302) |
-| 自我状态 | `cg(op=self_state)` | [`self_state`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2387) → [`_self_state_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1337) |
-| 演化（记忆结构演化） | `cg(op=evolution)` | [`evolution`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2390) → [`_evolution_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1472) |
-| 飞轮 / 自愈 | `cg(op=sustain)` | [`sustain`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2393) → [`_sustain_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1564) |
-| 洗脑 / 去污染 | `cg(op=scrub)` | [`scrub`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2396) → [`_scrub_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1673) |
-| 预测 / 因果门 | `cg(op=predict)` | [`predict`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2399) → [`_predict_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1399) |
-| 因果链 | `cg(op=causal)` | [`causal`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2402) → [`_causal_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1433) |
-| 白箱能力库（AEIS 能力显式调用） | `cg(op=whitebox)` | [`whitebox`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2405) → [`_whitebox_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L3078) |
-| 代码索引 | `cg(op=index_code)` | [`index_code`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2408) → [`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#L2452) → [`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#L2495) → [`_ref_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2978) |
-| 会话管理（多会话归属与过滤） | `cg(op=session)` | [`session`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2498) → [`_session_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2699) |
-| 导入落图 | `cg(op=ingest)` | [`ingest`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2501) → [`_ingest_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2778) |
-| 导出 | `cg(op=export)` | [`export`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2504) → [`_export_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2803) |
-| 维护 | `cg(op=maintain)` | [`maintain`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2507) → [`_maintain_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2825) |
-| 记忆固化 / 整理 | `cg(op=consolidate)` | [`consolidate`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2510) → [`_consolidate_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2903) |
-| 洞察 / 自主探索（信息差驱动） | `cg(op=insight)` | [`insight`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2513) → [`_insight_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2928) |
-| CCG 六要素编译（对话→候选→编外复核→落库） | `cg(op=ccg)` | [`ccg`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2516) → [`_ccg_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2523) |
+| 按需披露（投影后完整工具 / 参数文档即时取回） | `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#L2417) → [`_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#L2420) → [`_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#L2423) → [`_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#L2426) → [`_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#L2429) → [`_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#L2432) → [`_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#L2435) → [`_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#L2438) → [`_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#L2441) → [`_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#L2444) → [`_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#L2447) → [`_whitebox_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L3120) |
+| 代码索引 | `cg(op=index_code)` | [`index_code`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2450) → [`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#L2494) → [`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#L2537) → [`_ref_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L3020) |
+| 会话管理（多会话归属与过滤） | `cg(op=session)` | [`session`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2540) → [`_session_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2741) |
+| 导入落图 | `cg(op=ingest)` | [`ingest`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2543) → [`_ingest_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2820) |
+| 导出 | `cg(op=export)` | [`export`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2546) → [`_export_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2845) |
+| 维护 | `cg(op=maintain)` | [`maintain`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2549) → [`_maintain_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2867) |
+| 记忆固化 / 整理 | `cg(op=consolidate)` | [`consolidate`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2552) → [`_consolidate_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2945) |
+| 洞察 / 自主探索（信息差驱动） | `cg(op=insight)` | [`insight`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2555) → [`_insight_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2970) |
+| CCG 六要素编译（对话→候选→编外复核→落库） | `cg(op=ccg)` | [`ccg`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2558) → [`_ccg_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2565) |
 
 <!-- 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#L3101) |
-| 时间线 | `stg(op=timeline)` | [`timeline`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L3103) |
-| 锚点检索（时空窗口） | `stg(op=anchors)` | [`anchors`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L3110) |
-| 时空一致性 | `stg(op=consistency)` | [`consistency`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L3114) |
+| 两节点关系 | `stg(op=relation)` | [`relation`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L3150) |
+| 时间线 | `stg(op=timeline)` | [`timeline`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L3152) |
+| 锚点检索（时空窗口） | `stg(op=anchors)` | [`anchors`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L3159) |
+| 时空一致性 | `stg(op=consistency)` | [`consistency`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L3163) |
 
 <!-- FUNCMAP:END -->
 

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

@@ -8,13 +8,17 @@
 > `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
@@ -37,24 +41,56 @@ 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_unreachable.py` | 控制流终止语句之后的不可达代码（拦过 s5 负记忆段与 V21-4 通道 B 两族整段静默失效） | **无**（仅本地/发布链） |
 | 2 | `python scripts/check_publish_artifact.py` | 发布件内容政策（凭据 / 私有数据 / 隐私文本 / 非追踪件） | `publish-artifact-check.yml` |
-| 3 | `python scripts/cogmap_sync.py check` | 认知图行号投影与真源一致 | `cogmap-check.yml` |
-| 4 | `python scripts/link_check.py` | 全库 md 相对链接可达 | `cogmap-check.yml` |
-| 5 | `python scripts/workspace_index.py --check` | 工作区索引不陈化（第 18 条） | `workspace-index-check.yml` |
-| 6 | `python scripts/verify_discipline.py --allow-missing` | 纪律真源 ↔ 各端产物一致 | `discipline-check.yml` |
-| 7 | `python scripts/gate_rust_crate_test.py` | `cargo test` @ `rust/`（Rust 侧口径漂移的回归保障） | **无**（`hive-check.yml` 只跑 `hive/Cargo.toml`，`rust/` 至今零 CI） |
-| 8 | `python scripts/gate_rust_parity.py` | `scripts/rank_parity.py` 逐位对拍（Python `search_rrf` vs Rust `mdcg-eval --serve`） | **无** |
-
-> **依赖提示**：第 6 道经 `render_discipline` 解析 `docs/discipline/harnesses.yaml`，需要
+| 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、7、8 道**没有对应 CI workflow**——远端不跑、
+> **诚实边界（勿读成「CI 全兜底」）**：第 1、3、8、9 道**没有对应 CI workflow**——远端不跑、
 > 只有本地与 `npm publish` 会拦。Rust 侧的回归保障目前只存在于发布链这一处；
 > 若要远端兜底，须新增 workflow（`rust/**` 触发 + 装 cargo 工具链）。
 

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）。

package/docs/plans/stg/346/235/241/344/273/266/345/214/226/344/270/216/347/273/223/346/236/204/347/264/242/345/274/225_/350/256/276/350/256/241_v0.1.md

@@ -0,0 +1,124 @@
+# stg 条件化与结构索引 · 设计 v0.1
+
+> 立约动因（2026-10-03）：issue #52 判定成立并已在在役库复现（`stg.timeline(session=…)` 默认口径
+> count=25 且全为 `code_*`，条件命中的 204 条——含 15 条 `mem_*`——被排除在扫描面之外）。
+> 使用者当场定性与裁定：「**这又是理论和工程脱节**」「这个节点数限额是我自己提的……当时提的
+> 还附带了条件，遇到更多的检索节点，应该要**建立索引**，**明确检索条件**，和**不适用条件**，
+> 而**不是扩大节点数**」。
+>
+> 本稿＝该裁定的第 3 层落地设计（第 1、2 层「条件先行 + 截断可观测」另批实施中）。
+> 约束继承：`max_scan` 数值不得调大、不得默认全量；「倒排只可作候选内加速」（检索路径契约 §7）
+> 同样适用于本稿——stg 索引只做**条件维的收敛**，不替代认知路径。
+
+## 一、背景与定性
+
+**#52 的工程事实**（已实证）：`md_cg/stg.py::_scan` 按 `list(index["nodes"].items())[:max_scan]`
+在**条件过滤之前**做 id 字典序切片——限额被实现成「静默砍尾巴」，使用者当年附带的三件事
+（建立索引 / 明确检索条件 / 明确不适用条件）**一件未落地**。
+
+**定性（「理论/工程脱节」的第 n 次现身，同族形态谱）**：
+
+| # | 理论（已设计） | 工程（实际） | 处置 |
+|---|---|---|---|
+| 1 | S1–S6 逐级收敛（检索路径契约） | 认知结构入库但检索不调用（审计五偏差） | 已修（门控接线 issue #25 / C-8） |
+| 2 | 六要素全要素为检索面服务 | 验证方式/不适用条件两行未进默认检索 | 已修（0.7.0 §5.4） |
+| 3 | 限额＝「该建索引/细化条件」的压力信号 | 限额＝字典序切片（本项 #52） | **本稿 + 第 1、2 层** |
+
+共同主线（审计原文）：「认知结构被实现成『数据结构』而不是『计算路径』」；本项的变体是
+「**设计约束被实现成实现细节**」——5000 的语义是「超限该收敛」，工程把语义丢了、只剩数字。
+
+## 二、第 1、2 层（另批，不属本稿）
+
+条件过滤先于截断（「明确检索条件」落到实现）、截断可观测（`truncated` + 提示 + 近期优先兜底）。
+本稿设计以「第 1 层路径（全量快照遍历 + 条件过滤）」为**正确性基线**：索引路径必须与它逐位一致。
+
+## 三、第 3 层设计（本稿主体）
+
+### 3.1 目标形态
+
+契约 §2 在 stg 三接口上的落地：「触碰节点数从 N(全库) 降到 域内 ∩ 条件匹配 ∩ 邻域」——
+查询条件（session / layer / time_window）经**结构化倒排直取子集**，不再逐条遍历快照。
+
+### 3.2 索引形态（主案：装载期内存倒排 + 写路径增量维护）
+
+**主案**：不改任何磁盘格式，索引是**内存派生结构**：
+
+- **构建**：`MdCG._load_index()` 完成后的首次 stg 访问时，一次 O(N) 快照流生成三张表：
+  - `by_session: {sid | None: [ids]}`（`None` = 无会话归属，即 `unassigned` 兜底桶）；
+  - `by_layer: {layer: [ids]}`；
+  - `by_time: [(t, id)]`（有序，`t` 经既有 `trust.epoch_seconds` 归一；无有效时间戳的进 `_untimed`）。
+- **维护**：与既有桶计数**同一写钩**（`_set_index_entry` / `_remove_index_entry` 处增量增删）。
+- **不变量**：三张表恒为快照 keys 的划分（同源维护）；任一表缺失/代际不符 ⇒ **回退第 1 层全量遍历**
+  （安全降级且**可观测**，与 postings「宁可慢，不可丢召回」同纪律）。
+- **跨进程**：各进程装载时自建，无共享过期问题；多实例内存各持一份（1.7 万节点 ≈ 三张小表，可接受）。
+
+**备选（记录不采纳理由）**：
+- *快照内倒排*（`_index.json` 加段）：改最核心文件的 schema，装载/校验/compact/rebuild 全链兼容负担大；
+- *独立文件*（走 postings 的指纹+重建模式）：引入跨进程过期面与重建时机问题，而本索引的源数据
+  （快照字段）本就在内存——独立文件无增益。
+
+### 3.3 读侧直取
+
+- `timeline(session=X)`：`by_session[X]`（+ 既有的「x 会话不匹配」过滤语义逐位不变）→ 子集走既有排序链；
+- `anchors(time_window)`：`by_time` 区间截取（二分）→ 子集；
+- `consistency(layer)`：`by_layer[l]`；
+- 截断语义与第 1、2 层完全一致（`truncated` / 近期优先）——索引只改「取数面」，不改「语义面」。
+
+### 3.4 条件资格进 stg（「明确不适用条件」）
+
+- 复用 read 面唯一单点 `judge_qualification`：对 stg 返回条目做资格判定（生效条件命中 /
+  不适用条件拒绝 / 无从判定），结果随返回体带出（`qualification` 字段，语义与 read 面同口径）。
+- **首验形态：只上报不过滤**（行为零变化，`MDCG_STG_QUALIFY=1` 显式开）；
+  **次验形态（硬过滤，与 read 面同权）另立裁定**——因为 stg 的语义是「遍历视图」而非「召回 top-k」，
+  过滤改变视图完整性，需设计者拍板。
+
+### 3.5 flag 与回退（契约 §4 纪律）
+
+- `MDCG_STG_INDEX=1` 显式开；默认关时＝第 1 层路径。
+- **两条路径结果逐位一致**为等价性准入判据（同 postings 的「候选内加速、召回与全表一致」先例）。
+- 收敛读数（`meta` 分阶段计数：子集大小 vs 全量 N）供编外复核逐项核对。
+
+### 3.6 与既有机制的关系
+
+- **postings（词法 bigram）**：正交可叠加——词法先收词、stg 索引收条件维；
+- **桶（routing.bucket_dir，域级）**：正交；`route_key` 的 `observation_position` 一档与 layer/session 不同维；
+- **refindex（`_refindex.json`）**：形态参考，非复用对象。
+
+## 四、验收判据
+
+1. **等价性**：flag 开/关，三接口返回体（除 `meta` 计数）逐位一致（快照对比）；
+2. **收敛性**：`meta` 读数显示「实际遍历/触碰」从 N 降到子集（目标 ≤ 条件命中量级）；
+3. **不劣化**：既有 stg 套件 + 第 1、2 层新守卫全绿；在役对照（timeline(session) 的 count 与条目集）不改；
+4. **可观测**：索引命中/回退（表缺失/代际不符）均有 `meta` 计数与 reason；
+5. **守卫与定点变异**：索引增删钩、回退路径、等价性各有断言与变异自证。
+
+## 五、边界（不做的事）
+
+- 不改默认启用（先 flag，逐项验证，再讨论默认开启）；不改 `max_scan` 数值与第 1、2 层语义；
+- 不做 FTS 替代、不引入第二套时间/条件解析（复用 `trust.epoch_seconds` / `_view_session` / `judge_qualification` 单点）；
+- 不动写入侧磁盘语义（索引是内存派生 + 同钩维护）。
+
+## 六、待签收点（请逐条裁决）
+
+1. **索引形态主案**＝装载期内存倒排 + 写路径增量（备选两案的驳回理由见 §3.2）——可否？
+2. **路径等价为唯一准入**：flag 开/关逐位一致才准入——可否？
+3. **资格判定首验只上报不过滤**（`MDCG_STG_QUALIFY`），硬过滤另立裁定——可否？
+4. **`unassigned` 语义**：无会话节点在会话视图下**保持现状**（仅在 `session="*"` 等视图可见），索引化不得改变——确认？
+5. **同族归属**：`consistency.check` 的 `MAX_SCAN=200` 选面（字典序前 200 → 应改相关性/条件预筛）是否纳入本线第二实现批？
+
+## 七、排期
+
+设计稿签收 → 实施批（工作流：探针 → 实现 + 守卫 → 独立复核 → 容器双栈）→ 默认开关讨论 →
+随下次发版披露（若有默认面变化）。
+
+## 八、签收记录
+
+**2026-10-03 使用者签收**（原话：「同意此次设计。我们开始实施，来进行实测」）：
+
+- 待签收点 1（索引形态主案＝装载期内存倒排 + 写路径增量维护）：**同意**；
+- 待签收点 2（flag 开/关路径逐位等价为唯一准入）：**同意**；
+- 待签收点 3（资格判定首验只上报不过滤，`MDCG_STG_QUALIFY`；硬过滤另立裁定）：**同意**；
+- 待签收点 4（`unassigned` 语义保持现状，索引化不得改变）：**确认**；
+- 待签收点 5（同族 `consistency.check` 的 `MAX_SCAN=200` 选面）：**纳入本线第二实现批**（主体批不含；批间独立复核）。
+- **附加要求：实施后须实测**——在役库上的路径等价读数与遍历面收敛读数（本批报告中的「实测」节）。
+