@furongjun1999/dsh-memory 0.4.8 → 0.4.10

package/docs/mdcg//344/273/243/347/240/201/350/257/204/345/256/241/344/270/216/346/235/241/344/273/266/345/214/226/346/263/250/351/207/212_/345/245/221/347/272/246_v0.1.md

@@ -0,0 +1,82 @@
+---
+name: 代码评审与条件化注释_契约_v0.1
+overview: Phase 0 契约裁决：功能生效条件与索引元条件字段分家；render 三分区与人工优先；补写规范、门禁口径与已知代价面。作为四环全部改动的唯一权威。
+状态: 生效（Phase 0 产出 · 2026-09-17）
+关联计划: docs/mdcg/全库代码评审与条件化注释_计划_v0.1.md
+---
+
+# 代码评审与条件化注释 · 契约 v0.1
+
+> 本文件是 Phase 0 的裁决产出（计划 `contract-adr`），作为「全库代码评审 → 补条件化注释 → 进认知图索引 → 自动维护」四环全部改动的**唯一权威**。
+> 与代码真源冲突时以真源为准，并回改本文件（防术语双写法漂移）。
+
+## 一、判定单（designer-perspective · 强制调用）
+
+```
+[判定单]
+条件空间：观测位置=全局（设计者位置，跨文件/跨检索面） | 观测工具=源码级逐行取证 + 机械断言 | 时间窗口=Phase 0（2026-09-17，重索引前） | 存在约束=公开仓（注释随仓公开，第14条双清单）；不改 judge_qualification 判定序、不改 region_hash
+白箱三问：依据=计划 §2.1/§2.2 逐行取证 + md_cg/test_p26_refindex.py L212-231 与 L249-258 既有断言（现场实读） | 条件=md_cg 认知图对代码条目做资格判定、且检索侧取首个匹配 | 错后=回滚=还原 codeindex.render 并重索引（既有已落盘正文不追溯）
+裁决：ACCEPT（render 三分区 + 合成区去生效条件）；对「同批全量重索引」→ DEFER
+依据：行序压制为机械可判事实（合成行在源码注释之前且字段同名，mdcos._ccg_field 取首匹配）；索引元条件与功能前置条件语义互斥（backfill.py 既有先例：清洗真实库 109 条弱等价行）
+缺失维度：条件边界——真实库既有 2930 条代码节点的资格降级代价未被原计划评估（见 §四）
+验证路径：md_cg/test_codeindex.py（行序/零重名/诚实缺证据/幂等/截断）+ test_p26_refindex 重对齐 + md_cg 全组回归与改动前基线对照 + 蜂巢确定性执行留痕
+关注信号：本契约不触发追溯重写；Phase 2 铺量前必须获 q-0/q-1/q-2 裁决
+```
+
+## 二、字段分工（术语真源）
+
+| 字段 | 承载语义 | 来源 | 可否合成 |
+|---|---|---|---|
+| `生效条件` | **功能前置条件** precondition：这段代码在何种输入/状态下正确 | 人工/源码声明（源码 CCG 注释） | **否**（合成即冒充） |
+| `索引元条件` | 条目在何处/何时/以何工具可被观测到 | 机械推导（`codeindex.condition_space` 四槽） | 是（唯一来源） |
+| `位置` | 索引坐标（path:lineno-end、lang、precise） | 机械推导 | 是 |
+| frontmatter `condition_space` | 四槽结构化值（与正文 `索引元条件` 同一纯函数） | 机械推导 | 是 |
+
+真源常量：`nodefile.INDEX_META_MARK`（= `索引元条件`）与 `nodefile.is_ccg_mark`（零重名机械判据）。
+
+四条硬约束：
+
+1. 合成区字段名与 `nodefile.CCG_MARKS` 的交集 = 空集；
+2. `生效条件` 行只可能来自源码声明，`render` 永不合成该字段；
+3. 同名字段冲突时**人工优先**（源码区置首 → `_ccg_field` 取首个匹配 → 确定性可复算）；
+4. 不动 `region_hash`、不动 `judge_qualification` 判定序、`skip_matcher` 无参行为逐字不变。
+
+## 三、补写规范（环二输入口径）
+
+1. 只写**功能生效条件**，不写索引元条件：写「入参 path 为已存在的本地文件」，不写「源文件存在于本地仓」。
+2. 落点在**两个窗口**之一，按源文件**物理行序**合并（靠前者胜出 = 检索侧取首匹配的确定性序）：
+   - **leading**：定义行**紧邻上方**的连续 `#` 注释（`codeindex._leading_comments` 口径，遇空行即断）；
+   - **body**：定义行**紧邻下方**、函数体首个语句之前的 `#` 注释（`codeindex._body_comments` 口径，**唯一真源**）。
+   既有白箱单元库 **104+ 处**用的是 body 窗口（例：`whitebox_kb/wisdom/python_code_units.py` 模板 `def tokenize(src):` 下一行即 `# 生效条件：…`）；`verifier._ccg_block` 已收敛为委托 `codeindex._body_comments`（2026-09-17 裁决 A，消除历史悬空引用）。
+3. 六要素齐全才过门槛；`生效条件` 缺一即 BLINDSPOT（缺证据 → 补写，不许省略或用「常用条件默认省略」掩盖）。
+4. 公开仓约束：补写内容随仓公开，须过第 14 条「内容政策 + 隐私脱敏」双清单；含敏感/隐私者只入私有库（AEIS）。
+
+## 四、已知代价面（必须显式知情）
+
+- **改造前实测**：本机认知图真源（仓外私有库 `<brain-root>`）有 **2930** 条 `code_` 节点，其正文含合成 `生效条件`（实为索引元条件），故资格判定为 **DEFER**。
+  原计划 §九-2 称「代码节点当前恒定被判 BLINDSPOT」，与实测不符——**该前提已修正**（本契约相对计划的重要事实更正）。
+- **改造后**：`render` 不再合成 `生效条件` → 源码未补注释的条目 = 缺证据 = **BLINDSPOT**。
+- **影响面**：不追溯。既有 2930 条节点的正文已落盘，只有**重索引**（`index_code`，尤其非增量）或源文件变更触发重写时才翻转。
+- **为何仍应接受**：改造前的 DEFER 建立在一个**语义错误的生效条件**上（计划 §2.2 的病根：「补了注释」与「没补」不可区分）。未补 = BLINDSPOT 是诚实信号，由环二补注释闸门（`GATE_MIN_PASS_RATE=0.90`）逐步补回。
+- **回滚路径**：还原 `codeindex.render` 后重索引即可回到 DEFER；已落盘的旧正文不自动回退（写路径可退，历史不可逆）。
+
+## 五、门禁口径（Phase 0 验收）
+
+| 项 | 判据 | 断言位置 |
+|---|---|---|
+| 行序压制已修 | 源码 `生效条件` 置首、逐字保留，`_ccg_field` 取到人工值 | test_codeindex ② / test_p26 §4 |
+| 补注释 = 有效 | 源码声明后 `ccg_completeness.complete == True` | test_codeindex ② |
+| 未补 = 诚实缺证据 | `complete == False` 且**恰缺** `生效条件` | test_codeindex ② / test_p26 §5 |
+| 字段零重名 | 合成区用到的 CCG 字段名 = 其余五要素 | test_codeindex ③ |
+| 载体两窗口 | body 窗口注释被抽取、两窗口按物理序合并、`verifier` 与唯一真源逐字等价 | test_codeindex ⑦ |
+| 幂等/确定性 | `render` 两次逐字节相同；`index_dir` 两次条目序一致 | test_codeindex ⑤⑥ |
+| 既有契约不回归 | `condition_space` 四槽/全时窗、`extract` 分派、`region_hash` 12 位 | test_codeindex ④⑤ |
+| 回归 | md_cg 全组回归与**改动前基线**对照（既有失败不改判） | 蜂巢确定性执行留痕（spec/result） |
+
+## 六、不适用条件
+
+- 不适用于知识/文档节点（本契约只管代码条目的注释与资格判定）。
+- 不改 `judge_qualification` 判定序与 `region_hash`；扩面（`.ts`/`.ps1`/`.yml`）属既有计划缺口 E，只声明不扩面。
+- q-0（注释落点）/ q-1（首期范围）/ q-2（评审方式）未获使用者裁决前，不得进入 Phase 2 铺量。
+- 本契约不授权追溯重写既有节点正文，也不代替第 5 条验证纪律与第 17 条蜂巢派发。
+- JS/TS 弱提取当前**只收 leading 窗口**（body 窗口未纳入）——属诚实边界而非缺陷，扩面须另行取证。