@furongjun1999/dsh-memory 0.5.1 → 0.6.1

package/docs/eval/P1b2_/350/257/273/351/235/242/344/273/243/351/231/205/344/277/256/345/244/215_v1.0.md

@@ -0,0 +1,124 @@
+# P1b-2 修复报告：读面缓存代际——常驻进程索引跨进程写入不可见（v1.0）
+
+- **日期**：2026-09-26
+- **缺陷编号**：P1b-2（DSH 端在役复验 dsh_restart_recheck_20260926 定性）
+- **改动面**：`md_cg/mdcg.py`、`md_cg/mdcos.py`、`md_cg/mcp_server.py` 三改 + `md_cg/test_index_crossprocess_reload.py` 一加（git diff --stat：3 files changed, +90/-7；未 commit，由编排会话负责）
+- **行号口径**：本报告全部 path:line 经报告会话读码逐一核对；与修复会话材料有出入的 3 处已按读码实测修正并在「三、修复」末尾的核对注记中标明。
+
+---
+
+## 一、缺陷与证据链（DSH 端在役复验时间戳锁死证据）
+
+**缺陷**：MdCG 常驻进程的索引只在启动时装载一次，此后 read/get/search 全走内存态——其它进程（典型：review_cli，autoflush=1）写入对常驻进程**不可见**。
+
+**证据链（DSH 端在役复验，探针 dsh_restart_recheck_20260926，时间戳锁死）**：
+
+| 时刻 | 事件 |
+|---|---|
+| 22:13:16 | 常驻进程启动装载索引快照：14135 节点 |
+| 22:14:37 | review_cli（autoflush=1）写入探针节点 |
+| 22:14:43 | 磁盘 `_index.json` 已含探针（写侧落盘成功） |
+| 同一常驻进程 | `read` 探针 → **null**（读面不可见——病灶） |
+| 旁路新起进程 | `read` 探针 → 命中（新进程装载时读盘即得） |
+
+**关键反差**：写侧账本是平的（盘面有、新进程能读），唯独**常驻进程**的内存态停留在启动代——这不是写入丢失，是**读面代际停滞**。
+
+## 二、根因（启动装载一次 + 批次39 指纹仅在装载时）
+
+1. **架构根因**：`MdCG.__init__` 仅启动时调一次 `_load_index()`（mdcg.py:939），此后 `self.index` 常驻内存，读路径（`get`/`search`/`search_rrf`/`list_goals`）不再碰盘——他进程写快照对常驻进程永不生效。
+2. **演进根因**：批次39 为 issue #33 加的 `_index.json` 指纹校验（`fp = idx.get("_fingerprint")` 与 `_dir_fingerprint()` 比对，mdcg.py:973-974；修前行号 966-967）**也在 `_load_index` 内部**——它防的是「快照写入后盘面有增删」的陈旧快照误信，只在启动装载那一瞬间执行一次，不防「进程存活期间盘面变化」。
+3. 二者叠加：指纹校验给了「索引新鲜」的错觉，实际保鲜窗口只有启动瞬间；DSH 复验链中 22:14:43 的盘面真相到不了 22:13:16 装载的常驻进程。
+
+## 三、修复
+
+**【机制】**（mdcg.py）
+
+- **:946**（`__init__` 装载后）：`self._index_sig = self._index_signature()`——记录装载时的文件签名作基线。
+- **:992-1004** 新增 `_index_signature()`：`os.stat(index_path)` 取 `(st_mtime_ns, st_size)` 二元组（微秒级、无 open 无解析）；文件不存在或 stat 抛 `OSError` 时返回 `None` 静默——签名探测绝不阻塞读。`(mtime_ns, size)` 在 NTFS 100ns / ext4 ns 粒度下足以识别「他进程写快照」；`None→非 None` 同样可判（他进程首次落快照）。
+- **:1006-1047** 新增 `_maybe_reload_index()`：签名对比（相等含双侧 None → 返回 False 零开销）；变化才调 `_load_index()` 重载（`OSError/ValueError` 静默放弃、沿用旧内存态——重载失败不阻塞读）；重载后把 `self._dirty` 重放回新索引（`None`=tombstone pop，与 `_load_index` 日志重放同语义）并重算 buckets——本实例未 flush 的写入不因重载从检索面消失；顺带失效 hotcache（默认关）与 readcache（默认开）两个旧索引代派生缓存。
+- **:1139-1141** `compact_index` 写快照后主动刷签名；**:1308-1309** `rebuild_index` 同——**自写不自载**（防止把自己的 compact/rebuild 误判为他进程写入而做无谓重载循环）。
+- **flush 无改动**：flush 只在 `FileLock` 下向 `_index_log` 追加分片、不改 `_index.json`（mdcg.py:1145 def，:1153-1164 追加临界区），签名不变——自身写入/落账**永不**触发重载，正合适。
+
+**【接线清单（读码定案，5 处，写路径不接）】**
+
+| # | 位置 | 覆盖链 |
+|---|---|---|
+| 1 | mdcg.py:2054 `list_goals` | op=goal list/active 链（MdCGOS.list_goals 走 super 同源） |
+| 2 | mdcg.py:2319 `get` | op=read node_id 链；MdCGSecure.get（mdcos.py:4027-4031，读隔离判定后 `super().get`）同源覆盖 |
+| 3 | mdcg.py:2523 基类 `search` | 空查询早退后、读索引前 |
+| 4 | mdcos.py:767 `MdCGOS.search`（:745 def） | 生产检索 + op=route 链（mcp_server.py:2117-2119 `if op == "route":` → `cg.search(...)`） |
+| 5 | mdcos.py:1315 `MdCGOS.search_rrf` | 置于热路径 query 缓存查询（`hc = _hc.get(self)`，mdcos.py:1322）**之前**——旧索引代缓存命中会静默错答；op=read budget_tokens→recall→search_rrf 链同覆盖 |
+
+写路径一律不接（写入面经 `_dirty`/flush 自有账本，接了反而引入自重载循环）。
+
+**【maintain reload（显式探活面）】**
+
+- mdcos.py:2689-2698 `MAINTAIN_ACTIONS` 登记 `"reload"`（:2690）；
+- mdcos.py:2752-2755 maintain 分派 reload 分支：`return {"ok": True, "op": "maintain", "action": "reload", "reloaded": bool(self._maybe_reload_index())}`（:2754）——签名未变时是零开销 stat + False，幂等；
+- mdcos.py:2735 契约注释（生效条件）：reload 只触发 `_maybe_reload_index`；
+- mcp_server.py:2688-2698 `_maintain_call` 文档面：action 枚举补 reload，标注只读档（「reload 读面代际刷新 → 不额外拦截」），免 admin 天然放行。
+
+**【红守卫】** `md_cg/test_index_crossprocess_reload.py`（新增，run_tests.py 的 `glob("md_cg/test_*.py")` 发现机制自动纳入 CI——scripts/run_tests.py:45；跳过规则 `_SKIPS` 在 :139-146，本守卫不在跳过清单）。守卫六组，全部临时库 + 哑主密钥（进程内 `os.environ['MDCG_MASTER_KEY']='ab'*32` 先行 :134，子进程同哑密钥 :95，`tempfile.mkdtemp` :138/:182/:196/:248，rmtree 清理 :291）。
+
+**before / after**
+
+- **修复前**：`MdCG.__init__` 仅启动调一次 `_load_index`（mdcg.py:939 旧行），此后 read/get/search 全走内存态；复验证据链（第一节）写侧落盘成功、同常驻进程 read null、旁路新进程可读。
+- **修复后**：读路径入口每调用一次 stat（微秒级）对比签名，他进程写快照（compact/rebuild，典型在 close）即触发重载 + 日志重放，写入/删除（tombstone）对常驻进程可见；自身 flush/写入/compact/rebuild 全程零真实重载（自写不自载）。
+- **守卫红转绿实测**：同解释器双实例（临时库+哑密钥），B 实例 add+close 落快照后——A 禁用 reload 时 read null（修前病灶形态）→ 恢复后 read/search 命中；C 实例 forget+close 后 A read 归 null（tombstone 可见）；goal=list 经 list_goals 可见；maintain action=reload 幂等探活（未变 False / 他写后 True 且读面立即可见）；旁路子进程 READ 1 0（修前已绿，钉住盘面账本）。
+- **性能粗测**：接线态 vs 重载桩空转态——修复会话实测 157.4µs/读 vs 140.7µs/读（增幅 ~11.9%，即一次 stat 摊入 ~150µs 的 get；断言上界 ×3+30µs 内通过）；报告会话复跑 164.0µs/读 vs 149.0µs/读（增幅 10.1%，同断言通过）。
+
+**semantics_note（语义边界，如实）**
+
+1. **探测面边界**：签名只盯 `_index.json`——他进程**仅追加分片日志、尚未写新快照**（存活写方未 close/rebuild）不在自动探测面内。这正合适：自身 flush 也是纯日志追加，签名不变故零自重载循环；DSH 复验链中 review_cli 退出即 close→compact 落快照，落在探测面内。此类场景可用 maintain action=reload 显式探活（显式 reload 的真重载同样走 `_load_index` 的快照+日志全量口径，日志记录仍须快照重写才并入）。
+2. **mtime 粒度**：NTFS 100ns 粒度下同 tick 同尺寸的两次快照写入理论上可能漏检一次，下次任何签名变化自愈（启发式哨兵的诚实边界）。
+3. **重载保留本实例未 flush 写入**：`_dirty` 重放回新索引（None=tombstone pop，与 `_load_index` 日志重放同语义）并重算 buckets——`_stage` 双写 index+_dirty 的「检索看得到未落盘写入」语义不变。
+4. **派生缓存失效**：重载成功时顺带失效 hotcache（默认关）与 readcache（默认开）——旧索引代的 query 结果与同 path 重写的解析产物不陈旧化；重载是稀疏事件，不构成热路径开销。
+5. **未接线的读面（读码盘点）**：op=edges（provenance.all_edges→index_edges）、protect action=check（mcp_server.py:1142-1146 直读 `cg.index`）、service_info/insight/stats（mcp_server.py:3074-3079 `len(cg.index["nodes"])`）等低频读面仍走启动快照——高频面（get/search/search_rrf/route/recall/list_goals）已全覆盖，低频面如需可后续按同款单行接入。
+6. **stat 成本 vs 常驻不可见取舍**：无跨进程写入时每次读多一次 `os.stat`（实测 ~11-16µs 量级，占 get 的 ~11%，search 毫秒级面摊薄至 <1%），换得跨进程写入可见——读热路径无重载（重载仅在签名变化时发生，重载成本=一次 `_load_index`，与进程重启装载同量级但免去重启）。
+
+**核对注记（报告会话读码实测 vs 修复会话材料的 3 处修正）**
+
+| 材料 | 实测（本报告采用） |
+|---|---|
+| `MdCGSecure.get:4075` | **mdcos.py:4027-4031**（`MdCGSecure` 类在 mdcos.py:3655 起，不在 mdcg.py；:4075 附近实为 forget 区） |
+| `_maintain_call` 2689-2692 | **mcp_server.py:2688-2698**（def 在 :2688，reload 只读档说明在 docstring :2689-2698） |
+| 批次39 指纹校验 mdcg.py:966-967 | 修复插入后位移为 **mdcg.py:973-974**（报告第一节/第二节按修后行号引用，旧号在括注保留） |
+
+## 四、验证（守卫红转绿 + 全量回归 + 门禁）
+
+**本会话（报告员）实际复跑**（cmd：`python -X utf8`，工作目录仓库根）：
+
+| 检查 | 命令 | 结果 |
+|---|---|---|
+| 新守卫 | `python -X utf8 -m md_cg.test_index_crossprocess_reload` | **PASS=21 FAIL=0**（六组全绿：红转绿/旁路子进程/自身写入零重载+自写不自载/maintain reload/goal 链路/性能粗测；⑥性能 接线态 164.0µs vs 桩 149.0µs、增幅 10.1%，上界 ×3+30µs 通过） |
+| ask 点名回归① | `python -X utf8 -m md_cg.test_readcache_prodpath` | **PASS 12 / FAIL 0** |
+| ask 点名回归② | `python -X utf8 -m md_cg.test_index_durability` | **PASS=16 FAIL=0** |
+| 改动面核对 | `git diff --stat` | mcp_server.py 4 行、mdcg.py 77 行、mdcos.py 16 行——合计 **3 files changed, 90 insertions(+), 7 deletions(-)**，与材料一致，未 commit |
+
+**修复会话记录（材料转录，本会话未复跑、如实标注来源）**：
+
+- 点名回归：`test_p2` 通过 37/失败 0。
+- 扩面（均 0 失败）：`test_p2_mcp` 64 通过、`test_readcache_default_on` PASS 10、`test_readcache_precise_inval` PASS 23、`test_i28_hotcache_prodpath` ALL OK 8 项、`test_snapshot_autoclose` PASS=10/FAIL=0、`test_review_cli_visibility` PASS=10/FAIL=0、`test_p30_maintain` 55 通过、`test_p32_backfill` 59 通过、`test_p36_kp_align` PASS=34/FAIL=0。
+- 全量：`python -X utf8 scripts/run_tests.py md_cg --jobs 4 --timeout 600`（后台运行）→ **exit 0，"===== SUMMARY 161/161 通过，3 跳过（依赖缺失/平台不符）====="**；经 `--list` 核对发现 164 目标含 `test_index_crossprocess_reload`，跳过 3 项均为 `_SKIPS` 数据面依赖（test_p44_md_whitebox / test_md_access_parity / test_wisdom_md_store，与 scripts/run_tests.py:139-146 清单一致），与新守卫无关。
+
+## 五、DSH 端复验指引（探针 dsh_restart_recheck_20260926）
+
+修复部署后，探针应立即可读——**无需重启在役进程**：
+
+1. **新起进程**：装载时经 `_load_index`（快照+日志全量口径）天然并入，探针直接可见。
+2. **常驻旧进程**（修复前启动、仍持 22:13:16 旧内存态）：二选一——
+   - 调一次 `cg(op="maintain", action="reload")`：签名对比必变（review_cli 退出即 close→compact 落了新快照）→ 真重载 → 探针立即可见，返回 `"reloaded": true`；再调一次返回 `false`（幂等探活）；
+   - 或待其自然重启，重启后装载即含探针。
+3. **注意语义边界①**：若某存活写方只追加了分片日志、尚未写新快照，maintain reload 的真重载也读不到该增量——日志记录须快照重写才并入。DSH 复验链的 review_cli 已退出（close→compact 已落快照），不受此限。
+
+## 六、纪律合规声明
+
+1. **实验隔离**：全部测试/守卫运行于 `tempfile.mkdtemp` 临时库 + 哑主密钥（进程内 `os.environ['MDCG_MASTER_KEY']='ab'*32` 先行，子进程 env 同哑密钥），绝不触真实 `~/.mdcg` 令牌库（守卫源码 md_cg/test_index_crossprocess_reload.py:56/:95/:134/:291 可复核）。
+2. **在役面零接触**：DSH 在役库与探针 dsh_restart_recheck_20260926 本会话未触碰（仅读代码与跑临时库测试）；在役复验按第五节指引执行。
+3. **临时产物清理**：本会话运行守卫产生的 `p1b2_*` 临时目录已清理归零（清理前 8 个 → 清理后 0，已实测复核）；`clivis_*` 8 个系批次57 遗留、非本会话产物，按材料注记未动。
+4. **版本管理**：未 git commit（编排会话负责）；工作区改动面 = 三改一加，与本报告第一节改动面记录一致。
+5. **报告口径**：本报告不写本机绝对路径；所有 path:line 经本会话读码核对；本会话实跑的检查与修复会话材料转录的检查在第四节分列注明来源，无任何未实跑检查被报告为已通过。
+
+---
+
+*报告员（工程报告撰写）· 2026-09-26 · P1b-2 v1.0*