CIE-Unified

MERGE_PLAN.md

  1# CIE-Unified 整合方案
  2
  3> 日期: 2026-03-31
  4> 决策依据: Branch A 6/8, Branch B 8/8 (同一 cie-datasets formal dataset)
  5> 策略: 方案 C — 核取 B，壳取 A
  6>
  7> 状态更新（2026-04-01）：
  8> `origin/integration/merge-plan @ fabbb69` 已完成 Phase 2.2（Kernel Sanity Gate）；
  9> `integration/phase2.3-sanity-cleanup` 已完成 Phase 2.3（validation/context/attention sanity cleanup），
 10> 并通过 quick gate、Phase 2.3 gate、broader regression gate、formal validation smoke。
 11> **Phase 3 尚未开始**；只有在 Phase 2.3 gates 全通过后，才允许进入 Phase 3。
 12
 13---
 14
 15## 0. 冻结点
 16
 17| 分支 | Commit | 状态 |
 18|------|--------|------|
 19| `branch-a/task04-validation-reporting` | `419ae8d` | 冻结，不再改 |
 20| `branch-b` | `c734288` | 冻结，不再改 |
 21| `review/branch-b-formal-dataset-strict-rerun` | `c110916` | 参考（B 的 strict rerun 验证） |
 22| `review/branch-a-formal-dataset-strict-rerun` | `273f416` | 参考（A 的 strict rerun 验证） |
 23
 24---
 25
 26## 1. 文件级合并计划
 27
 28### 核 — 取 Branch B
 29
 30这些文件直接从 `branch-b @ c734288` 复制，构成 runtime 内核：
 31
 32| 文件 | 来源 | 关键机制 |
 33|------|------|---------|
 34| `cie/graph.py` | **Branch B** | 非对称图（fwd_weight ≠ bwd_weight）、`laplacian_at()`、`asymmetry_at()`、`circulation()`、`convergence()` |
 35| `cie/dynamics.py` | **Branch B** | L_G φ 扩散 + soft clamp、自适应衰减 α(x)=α₀·(1-c)^β·(1/κ)、动态锚点阈值（10th percentile）、三级归巢、置信度自然衰减 |
 36| `cie/state.py` | **Branch B 为基底，吸收 A 的 Profile** | (φ,μ,J) 三元组、AttentionPool、Dirichlet K=3 置信度。**需要吸收 A 的 `SedimentationProfile` dataclass，但 Phase 3 应先 dual-write/并行观测，不直接替换 `experience_hits`。** |
 37| `cie/runtime.py` | **Branch B 为基底，吸收 A 的信号队列** | CIERuntime 六接口、action_release u=o·c·ε。**需要吸收 A 的 `PendingSignal` 机制，并在 Phase 2.1 删除旧直接 `_feedback_loop()` 路径，保证 feedback/emit 只走单一路径。** |
 38
 39### 壳 — 取 Branch A
 40
 41这些工程设施从 `branch-a @ 419ae8d` 移植到整合分支：
 42
 43| 设施 | 来源 | 说明 |
 44|------|------|------|
 45| `PendingSignal` 信号队列 | **Branch A** `cie/state.py` + `cie/runtime.py` | 将输入/反馈/回灌统一为信号对象排队，下一步 step 时消费。**目标是单路径收口：替换 Branch B 的直接 `_feedback_loop()` 调用，而不是与之并存。** |
 46| `SedimentationProfile` | **Branch A** `cie/state.py` | 每节点生命周期对象（stage, activation_hits, stable_steps, dormant_steps, resonance, candidate_score, merged_into）。**先并行观测/dual-write，再决定是否替换 Branch B 的 `experience_hits` 计数器。** |
 47| `cie/validation.py` | **Branch A** `cie/validation.py` | 476 行标准化验证框架，输出 JSON + Markdown 报告。需适配 Branch B 的 snapshot 字段 |
 48| 报告模板 | **Branch A** `reports/` 目录结构 | JSON schema + Markdown 自动生成 |
 49
 50### 不要的
 51
 52| 项目 | 原分支 | 原因 |
 53|------|--------|------|
 54| Branch A 的对称图 `graph.py` | A | 被 B 的非对称图替代 |
 55| Branch A 的 `confidence_proxy` | A | 被 B 的 Dirichlet 替代 |
 56| Branch A 的 age-based 衰减 | A | 被 B 的自适应衰减替代 |
 57| Branch B 的手写 `STAGE_REPORT.md` | B | 被 A 的 validation.py 自动报告替代 |
 58| Branch B 的直接 `_feedback_loop()` 回灌路径 | B | PendingSignal 落地后必须删除，避免与队列双通道并存导致重复应用 |
 59| 两边各自的魔法数字 | A+B | 统一为参数类 `CIEConfig` |
 60| Branch B 的 `HANDOFF.md` | B | 开发阶段文档，不进主干 |
 61
 62---
 63
 64## 2. 接口对齐
 65
 66Branch A 和 B 的六接口签名已基本一致（SPEC §5），需要统一的是内部实现路径：
 67
 68```
 69ingest(input, context, anchors)
 70  → 创建 external PendingSignal（来自 A 的模式）
 71  → 排入 state.pending_signals
 72  → 不再直接调用 legacy _feedback_loop()
 73
 74step(n)
 75  → 消费 pending_signals → _apply_signal()（A 的队列消费）
 76  → _propagate_activation()（B 的 L_G 扩散 + 激活传播）
 77  → _apply_homing()（B 的三级归巢）
 78  → _apply_decay()（B 的自适应衰减）
 79  → _refresh_sedimentation()（A 的 SedimentationProfile 检测 + B 的阈值）
 80  → _refresh_observability()
 81
 82emit()
 83  → action_release u=o·c·ε（B 的公式）
 84  → 创建 emit PendingSignal（A 的模式）
 85  → 不直接改写 runtime 状态
 86
 87commit_feedback(feedback)
 88  → 创建 feedback PendingSignal with polarity（A 的模式）
 89  → 包含 weaken_confidence（B 的 Dirichlet 衰减）
 90
 91snapshot_state()
 92  → 所有 SPEC §6 字段（A+B 已对齐）
 93
 94reset_session()
 95  → 清激活/注意力，保留 φ/ability_cores/anchors（B 的逻辑）
 96```
 97
 98**当前审核结论**：接口方向没错，但在 `423d812` 这一步里，PendingSignal 队列和旧直接 `_feedback_loop()` 仍然并存，Phase 2 只能视为“功能落地、尚未收口”。未完成 Phase 2.1 之前，不进入 Phase 3。
 99
100---
101
102## 3. 合并顺序
103
104**原则：先壳接核，不同时大改理论和工程外壳。**
105
106### Phase 1: 基底搭建（Day 1）
107
1081. 从 `branch-b @ c734288` 复制 `cie/graph.py`、`cie/dynamics.py`、`cie/state.py`、`cie/runtime.py`
1092. 跑 Branch B 的 42 项 pytest 套件确认基底不坏：
110   `python3 -m pytest tests/test_smoke.py tests/test_dynamics.py tests/test_comprehensive.py -q`
1113. 提交：`integration: 基底——Branch B runtime 核心`
112
113### Phase 2: 信号队列移植（Day 1-2）
114
1151. 从 Branch A 移植 `PendingSignal` dataclass 到 `cie/state.py`
1162. 改写 `runtime.py` 的 `ingest()`、`emit()`、`commit_feedback()` 使用信号队列
1173. 改写 `_feedback_loop()` 为 `_apply_signal()` 的队列消费，不保留并行的直接状态写入路径
1184. 先跑快速 gate：
119   `python3 -m pytest tests/test_smoke.py tests/test_dynamics.py -q`
1205. 提交：`integration: 信号队列——PendingSignal 替换直接调用`
121
122### Phase 2.1: 单路径收口 gate（Phase 3 前必须通过）
123
1241. 清理旧直接回灌路径，保证 `ingest()` / `emit()` / `commit_feedback()` 对反馈都只做 enqueue，不做第二条直接 apply
1252. 增加 exactly-once 回归检查，明确覆盖：
126   `emit()` 产生的回灌不会被 `ingest()` + `step()` 双重应用；
127   `commit_feedback()` 不会和旧 `_feedback_loop()` 叠加；
128   `PendingSignal` 是唯一反馈入口
1293. 通过快速 gate：
130   `python3 -m pytest tests/test_smoke.py tests/test_dynamics.py -q`
131   预期：`12 passed`
1324. 通过完整本地 gate：
133   `python3 -m pytest tests/test_smoke.py tests/test_dynamics.py tests/test_comprehensive.py -q`
134   预期：`42 passed`
1355. 明确 formal validation 是单独脚本 gate，不与上面的 pytest 口径混写：
136   `python3 tests/formal_validation.py`
1376. 只有 Phase 2.1 通过，后续实现才允许进入 Phase 3
138
139### Phase 2.2: Kernel Sanity Gate（已完成）
140
1411. 修正 Branch B 内核中 backward-weight 读取方向
1422. 确认 Dirichlet per-node wiring 不再退化成均匀先验占位
1433. 确认 context 参数已被 runtime 真实消费
1444. 补 attention ledger 的基础 sanity gate
1455. 通过 gate：`python3 -m pytest tests/test_kernel_sanity.py -q`
146
147### Phase 2.3: Validation / Context / Attention Sanity Cleanup（已完成）
148
1491. 修正 validation/test 层残留的 stale `get_bwd_weight(...)` 调用顺序
1502. 明确 context 语义：
151   `str` 按字符拆分；`list/tuple` 逐项消费；`dict` 稳定归一化；不支持类型显式报错
1523. 加强 attention ledger gate，覆盖 multi-step / decay / feedback / reset cleanup 场景
1534. 将 `tests/test_comprehensive.py` 与 `tests/formal_validation.py` 改成 repo-relative / env-aware 路径解析
1545. 通过 gate：
155   `python3 -m pytest tests/test_smoke.py tests/test_dynamics.py tests/test_exactly_once.py tests/test_kernel_sanity.py -q`
156   `python3 -m pytest tests/test_phase23_validation_sanity.py -q`
157   `python3 -m pytest tests/test_smoke.py tests/test_dynamics.py tests/test_exactly_once.py tests/test_kernel_sanity.py tests/test_comprehensive.py tests/test_phase23_validation_sanity.py -q`
158   `python3 tests/formal_validation.py`
1596. Phase 2.3 完成后，Phase 3 才允许开始；当前 **Phase 3 仍未开始**
160
161### Phase 3: 沉积 Profile 并行观测（未开始，Day 2）
162
1631. 从 Branch A 移植 `SedimentationProfile` dataclass 到 `cie/state.py`
1642. 保留 Branch B 的 `experience_hits` 作为已验证行为基线；先把 Profile 做成 dual-write / parallel observation
1653. 在 snapshot_state 中输出 Profile 信息与对照指标，比较 Profile 与 `experience_hits` 的行为对齐
1664. 跑测试确认沉积路径功能不退化；若不对齐，不替换 `experience_hits`
1675. 后续如需真正替换 `experience_hits`，必须在额外 gate 中证明行为保持一致后再做，不与本阶段绑定
1686. 提交：`integration: 沉积 Profile——dual-write 观察层`
169
170### Phase 4: 参数统一（Day 2）
171
1721. 创建 `cie/config.py`，把两边散落的魔法数字收集为 `CIEConfig` dataclass
1732. `CIERuntime.__init__` 接收 `config: CIEConfig`
1743. 提交：`integration: 参数统一——CIEConfig 替换魔法数字`
175
176### Phase 5: 验证框架移植（Day 3）
177
1781. 从 Branch A 移植 `cie/validation.py`
1792. 适配 Branch B 的 snapshot 字段（已基本对齐）
1803. 添加 Branch B 特有的检查项：非对称比、环流、Dirichlet 分化
1814. 跑 validation，生成 JSON + Markdown 报告
1825. 提交：`integration: 验证框架——validation.py 适配整合 runtime`
183
184### Phase 6: 正式数据集全量验证（Day 3）
185
1861. 用 `/Users/george/code/cie-datasets` 的 hydrated JSONL 跑完整 8 场景验证
1872. 生成正式报告
1883. 与 Branch A 6/8 和 Branch B 8/8 做三方对比
1894. 提交：`integration: 正式验证——cie-datasets 8 场景`
190
191---
192
193## 4. 验收标准
194
195整合完成后必须满足：
196
197| # | 标准 | 来源 |
198|---|------|------|
199| 1 | SPEC §9 全部 11 项 | LOCKED_IMPLEMENTATION_SPEC |
200| 2 | `python3 -m pytest tests/test_smoke.py tests/test_dynamics.py -q` 通过（当前口径应为 `12 passed`） | Phase 2 / 2.1 gate |
201| 3 | `python3 -m pytest tests/test_smoke.py tests/test_dynamics.py tests/test_comprehensive.py -q` 通过（当前口径应为 `42 passed`） | Branch B/integration pytest suite |
202| 4 | PendingSignal exactly-once 语义由回归测试证明；不存在旧 `_feedback_loop()` 直接路径与队列双通道并存 | Phase 2.1 gate |
203| 5 | Branch A 的壳层语义等价检查通过（原 18 项能力点适配后覆盖） | branch-a shell semantics |
204| 6 | cie-datasets 8 场景全 PASS；并明确这是 formal validation script gate，而不是 pytest 项数的一部分 | formal_validation |
205| 7 | phi 不超 ±10.1（soft clamp 保留） | 数值稳定性 |
206| 8 | 非对称比能涌现词结构 | word_emergence 验证 |
207| 9 | validation.py 自动生成 JSON + MD 报告 | 工程要求 |
208| 10 | 无魔法数字，全部在 CIEConfig 中 | 可维护性 |
209
210---
211
212## 5. 风险
213
214| 风险 | 影响 | 缓解 |
215|------|------|------|
216| PendingSignal 与旧 `_feedback_loop()` 双通道并存 | `emit()` / `ingest()` / `commit_feedback()` 可能重复应用反馈，污染已验证动态行为 | 先过 Phase 2.1：单路径收口 + exactly-once 回归测试，再继续 |
217| 过早用 SedimentationProfile 直接替换 `experience_hits` | 破坏 Branch B 已验证的沉积/能力核形成动态 | Phase 3 先 dual-write/并行观测，替换延后到额外 gate |
218| A 的 validation.py 假设 A 的 snapshot 格式 | 字段不匹配 | Phase 5 逐字段适配 |
219| “tests pass” 口径写得过于笼统 | 把 pytest gate 与 formal validation script gate 混为一谈，误导后续实施 | 在计划中固定命令和预期输出，不再只写泛化口号 |
220| 合并后数值行为微变 | 原有测试值不完全匹配 | 允许 ±5% 浮点容差，但 formal validation 仍需单独复核 |
221
222---
223
224## 6. 时间估计
225
226| Phase | 预计耗时 |
227|-------|---------|
228| Phase 1 基底 | 30 分钟 |
229| Phase 2 信号队列 | 2 小时 |
230| Phase 2.1 单路径 gate | 45 分钟 |
231| Phase 3 沉积 Profile（dual-write） | 2 小时 |
232| Phase 4 参数统一 | 1 小时 |
233| Phase 5 验证框架 | 1.5 小时 |
234| Phase 6 全量验证 | 1 小时 |
235| **总计** | **~8.75 小时** |
236
237---
238
239## 7. 决策记录
240
241**方案 C 落板依据：**
242
243| 事实 | 数据 |
244|------|------|
245| Branch B formal dataset | **8/8 PASS**（`c110916` strict rerun 独立复现） |
246| Branch A formal dataset | **6/8 PASS**（`273f416` strict rerun；初中数学 phi=12.07 超限，跨学科 phi=20.18 超限） |
247| Branch A raw 五本课本 | 8/10（更早轮次） |
248| Branch B 理论贴合 | 三核量 (o,c,ω) 全实现 |
249| Branch A 工程壳 | PendingSignal + SedimentationProfile + validation.py |
250
251**核取 B 的理由**：非对称图/L_G/Dirichlet/circulation 是 README 理论主线的忠实实现，丢掉等于放弃 CIE 核心；Branch A 在稳定性上也不如 B（两个场景 phi 超限）。
252
253**壳取 A 的理由**：信号队列模式比直接调用更规整；SedimentationProfile 比计数器更精细；validation.py 自动报告是工程必需品。
254
255**本次审核补充判断**：上述高层决策仍然成立，没有证据支持改成“核取 A”或“壳取 B”。需要修正的是实施顺序：当前必须先在 Phase 3 前补一个 Phase 2.1 gate，消除 PendingSignal 双路径风险；而 SedimentationProfile 应先 dual-write，再决定是否替换 `experience_hits`。
256
257**三方共识**：George（决策者）、ChatGPT（Branch A 开发者/审查者）、Claude（Branch B 开发者/审查者）均同意方案 C。