codex@macbookpro
·
2026-04-01
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> `feat/phase2.4-kernel-math-cleanup` 已完成 Phase 2.4（weighted-degree normalization + net-flow circulation），
12> 并通过 quick gate、Phase 2.4 gate、broader regression gate、formal validation smoke。
13> **Phase 3 尚未开始**；只有在 Phase 2.4 gates 全通过后，才允许进入 Phase 3，
14> 且仍保持 **dual-write first, replacement later**。
15
16---
17
18## 0. 冻结点
19
20| 分支 | Commit | 状态 |
21|------|--------|------|
22| `branch-a/task04-validation-reporting` | `419ae8d` | 冻结，不再改 |
23| `branch-b` | `c734288` | 冻结，不再改 |
24| `review/branch-b-formal-dataset-strict-rerun` | `c110916` | 参考（B 的 strict rerun 验证） |
25| `review/branch-a-formal-dataset-strict-rerun` | `273f416` | 参考（A 的 strict rerun 验证） |
26
27---
28
29## 1. 文件级合并计划
30
31### 核 — 取 Branch B
32
33这些文件直接从 `branch-b @ c734288` 复制，构成 runtime 内核：
34
35| 文件 | 来源 | 关键机制 |
36|------|------|---------|
37| `cie/graph.py` | **Branch B** | 非对称图（fwd_weight ≠ bwd_weight）、`laplacian_at()`、`asymmetry_at()`、`circulation()`、`convergence()` |
38| `cie/dynamics.py` | **Branch B** | L_G φ 扩散 + soft clamp、自适应衰减 α(x)=α₀·(1-c)^β·(1/κ)、动态锚点阈值（10th percentile）、三级归巢、置信度自然衰减 |
39| `cie/state.py` | **Branch B 为基底，吸收 A 的 Profile** | (φ,μ,J) 三元组、AttentionPool、Dirichlet K=3 置信度。**需要吸收 A 的 `SedimentationProfile` dataclass，但 Phase 3 应先 dual-write/并行观测，不直接替换 `experience_hits`。** |
40| `cie/runtime.py` | **Branch B 为基底，吸收 A 的信号队列** | CIERuntime 六接口、action_release u=o·c·ε。**需要吸收 A 的 `PendingSignal` 机制，并在 Phase 2.1 删除旧直接 `_feedback_loop()` 路径，保证 feedback/emit 只走单一路径。** |
41
42### 壳 — 取 Branch A
43
44这些工程设施从 `branch-a @ 419ae8d` 移植到整合分支：
45
46| 设施 | 来源 | 说明 |
47|------|------|------|
48| `PendingSignal` 信号队列 | **Branch A** `cie/state.py` + `cie/runtime.py` | 将输入/反馈/回灌统一为信号对象排队，下一步 step 时消费。**目标是单路径收口：替换 Branch B 的直接 `_feedback_loop()` 调用，而不是与之并存。** |
49| `SedimentationProfile` | **Branch A** `cie/state.py` | 每节点生命周期对象（stage, activation_hits, stable_steps, dormant_steps, resonance, candidate_score, merged_into）。**先并行观测/dual-write，再决定是否替换 Branch B 的 `experience_hits` 计数器。** |
50| `cie/validation.py` | **Branch A** `cie/validation.py` | 476 行标准化验证框架，输出 JSON + Markdown 报告。需适配 Branch B 的 snapshot 字段 |
51| 报告模板 | **Branch A** `reports/` 目录结构 | JSON schema + Markdown 自动生成 |
52
53### 不要的
54
55| 项目 | 原分支 | 原因 |
56|------|--------|------|
57| Branch A 的对称图 `graph.py` | A | 被 B 的非对称图替代 |
58| Branch A 的 `confidence_proxy` | A | 被 B 的 Dirichlet 替代 |
59| Branch A 的 age-based 衰减 | A | 被 B 的自适应衰减替代 |
60| Branch B 的手写 `STAGE_REPORT.md` | B | 被 A 的 validation.py 自动报告替代 |
61| Branch B 的直接 `_feedback_loop()` 回灌路径 | B | PendingSignal 落地后必须删除，避免与队列双通道并存导致重复应用 |
62| 两边各自的魔法数字 | A+B | 统一为参数类 `CIEConfig` |
63| Branch B 的 `HANDOFF.md` | B | 开发阶段文档，不进主干 |
64
65---
66
67## 2. 接口对齐
68
69Branch A 和 B 的六接口签名已基本一致（SPEC §5），需要统一的是内部实现路径：
70
71```
72ingest(input, context, anchors)
73 → 创建 external PendingSignal（来自 A 的模式）
74 → 排入 state.pending_signals
75 → 不再直接调用 legacy _feedback_loop()
76
77step(n)
78 → 消费 pending_signals → _apply_signal()（A 的队列消费）
79 → _propagate_activation()（B 的 L_G 扩散 + 激活传播）
80 → _apply_homing()（B 的三级归巢）
81 → _apply_decay()（B 的自适应衰减）
82 → _refresh_sedimentation()（A 的 SedimentationProfile 检测 + B 的阈值）
83 → _refresh_observability()
84
85emit()
86 → action_release u=o·c·ε（B 的公式）
87 → 创建 emit PendingSignal（A 的模式）
88 → 不直接改写 runtime 状态
89
90commit_feedback(feedback)
91 → 创建 feedback PendingSignal with polarity（A 的模式）
92 → 包含 weaken_confidence（B 的 Dirichlet 衰减）
93
94snapshot_state()
95 → 所有 SPEC §6 字段（A+B 已对齐）
96
97reset_session()
98 → 清激活/注意力，保留 φ/ability_cores/anchors（B 的逻辑）
99```
100
101**当前审核结论**：接口方向没错，但在 `423d812` 这一步里，PendingSignal 队列和旧直接 `_feedback_loop()` 仍然并存，Phase 2 只能视为“功能落地、尚未收口”。未完成 Phase 2.1 之前，不进入 Phase 3。
102
103---
104
105## 3. 合并顺序
106
107**原则：先壳接核，不同时大改理论和工程外壳。**
108
109### Phase 1: 基底搭建（Day 1）
110
1111. 从 `branch-b @ c734288` 复制 `cie/graph.py`、`cie/dynamics.py`、`cie/state.py`、`cie/runtime.py`
1122. 跑 Branch B 的 42 项 pytest 套件确认基底不坏：
113 `python3 -m pytest tests/test_smoke.py tests/test_dynamics.py tests/test_comprehensive.py -q`
1143. 提交：`integration: 基底——Branch B runtime 核心`
115
116### Phase 2: 信号队列移植（Day 1-2）
117
1181. 从 Branch A 移植 `PendingSignal` dataclass 到 `cie/state.py`
1192. 改写 `runtime.py` 的 `ingest()`、`emit()`、`commit_feedback()` 使用信号队列
1203. 改写 `_feedback_loop()` 为 `_apply_signal()` 的队列消费，不保留并行的直接状态写入路径
1214. 先跑快速 gate：
122 `python3 -m pytest tests/test_smoke.py tests/test_dynamics.py -q`
1235. 提交：`integration: 信号队列——PendingSignal 替换直接调用`
124
125### Phase 2.1: 单路径收口 gate（Phase 3 前必须通过）
126
1271. 清理旧直接回灌路径，保证 `ingest()` / `emit()` / `commit_feedback()` 对反馈都只做 enqueue，不做第二条直接 apply
1282. 增加 exactly-once 回归检查，明确覆盖：
129 `emit()` 产生的回灌不会被 `ingest()` + `step()` 双重应用；
130 `commit_feedback()` 不会和旧 `_feedback_loop()` 叠加；
131 `PendingSignal` 是唯一反馈入口
1323. 通过快速 gate：
133 `python3 -m pytest tests/test_smoke.py tests/test_dynamics.py -q`
134 预期：`12 passed`
1354. 通过完整本地 gate：
136 `python3 -m pytest tests/test_smoke.py tests/test_dynamics.py tests/test_comprehensive.py -q`
137 预期：`42 passed`
1385. 明确 formal validation 是单独脚本 gate，不与上面的 pytest 口径混写：
139 `python3 tests/formal_validation.py`
1406. 只有 Phase 2.1 通过，后续实现才允许进入 Phase 3
141
142### Phase 2.2: Kernel Sanity Gate（已完成）
143
1441. 修正 Branch B 内核中 backward-weight 读取方向
1452. 确认 Dirichlet per-node wiring 不再退化成均匀先验占位
1463. 确认 context 参数已被 runtime 真实消费
1474. 补 attention ledger 的基础 sanity gate
1485. 通过 gate：`python3 -m pytest tests/test_kernel_sanity.py -q`
149
150### Phase 2.3: Validation / Context / Attention Sanity Cleanup（已完成）
151
1521. 修正 validation/test 层残留的 stale `get_bwd_weight(...)` 调用顺序
1532. 明确 context 语义：
154 `str` 按字符拆分；`list/tuple` 逐项消费；`dict` 稳定归一化；不支持类型显式报错
1553. 加强 attention ledger gate，覆盖 multi-step / decay / feedback / reset cleanup 场景
1564. 将 `tests/test_comprehensive.py` 与 `tests/formal_validation.py` 改成 repo-relative / env-aware 路径解析
1575. 通过 gate：
158 `python3 -m pytest tests/test_smoke.py tests/test_dynamics.py tests/test_exactly_once.py tests/test_kernel_sanity.py -q`
159 `python3 -m pytest tests/test_phase23_validation_sanity.py -q`
160 `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`
161 `python3 tests/formal_validation.py`
1626. Phase 2.3 完成后，Phase 3 才允许开始；当前 **Phase 3 仍未开始**
163
164### Phase 2.4: Kernel Math Cleanup（已完成）
165
1661. 将 `diffuse_phi()` 的归一化从未加权邻居数改为加权度，避免高权重稠密区被错误压扁
1672. 将 `circulation()` 从单向路径权重求和改为逐边净流 `Σ(W(u,v) - W(v,u))`
1683. 新增 `tests/test_phase24_kernel_math.py`，覆盖：
169 weighted-degree normalization、
170 symmetric cycle net-flow≈0、
171 asymmetric cycle directionality、
172 Phase 2.2 kernel primitives regression
1734. 通过 gate：
174 `python3 -m pytest tests/test_smoke.py tests/test_dynamics.py tests/test_exactly_once.py tests/test_kernel_sanity.py tests/test_phase23_validation_sanity.py -q`
175 `python3 -m pytest tests/test_phase24_kernel_math.py -q`
176 `python3 -m pytest tests/test_smoke.py tests/test_dynamics.py tests/test_exactly_once.py tests/test_kernel_sanity.py tests/test_phase23_validation_sanity.py tests/test_comprehensive.py tests/test_phase24_kernel_math.py -q`
177 `python3 tests/formal_validation.py`
1785. 只有在 Phase 2.4 gates 全通过后，Phase 3 才允许开始；当前 **Phase 3 仍未开始**
179
180### Phase 3: 沉积 Profile 并行观测（未开始，Day 2）
181
1821. 从 Branch A 移植 `SedimentationProfile` dataclass 到 `cie/state.py`
1832. 保留 Branch B 的 `experience_hits` 作为已验证行为基线；先把 Profile 做成 dual-write / parallel observation
1843. 在 snapshot_state 中输出 Profile 信息与对照指标，比较 Profile 与 `experience_hits` 的行为对齐
1854. 跑测试确认沉积路径功能不退化；若不对齐，不替换 `experience_hits`
1865. 后续如需真正替换 `experience_hits`，必须在额外 gate 中证明行为保持一致后再做，不与本阶段绑定
1876. 提交：`integration: 沉积 Profile——dual-write 观察层`
188
189### Phase 4: 参数统一（Day 2）
190
1911. 创建 `cie/config.py`，把两边散落的魔法数字收集为 `CIEConfig` dataclass
1922. `CIERuntime.__init__` 接收 `config: CIEConfig`
1933. 提交：`integration: 参数统一——CIEConfig 替换魔法数字`
194
195### Phase 5: 验证框架移植（Day 3）
196
1971. 从 Branch A 移植 `cie/validation.py`
1982. 适配 Branch B 的 snapshot 字段（已基本对齐）
1993. 添加 Branch B 特有的检查项：非对称比、环流、Dirichlet 分化
2004. 跑 validation，生成 JSON + Markdown 报告
2015. 提交：`integration: 验证框架——validation.py 适配整合 runtime`
202
203### Phase 6: 正式数据集全量验证（Day 3）
204
2051. 用 `/Users/george/code/cie-datasets` 的 hydrated JSONL 跑完整 8 场景验证
2062. 生成正式报告
2073. 与 Branch A 6/8 和 Branch B 8/8 做三方对比
2084. 提交：`integration: 正式验证——cie-datasets 8 场景`
209
210---
211
212## 4. 验收标准
213
214整合完成后必须满足：
215
216| # | 标准 | 来源 |
217|---|------|------|
218| 1 | SPEC §9 全部 11 项 | LOCKED_IMPLEMENTATION_SPEC |
219| 2 | `python3 -m pytest tests/test_smoke.py tests/test_dynamics.py -q` 通过（当前口径应为 `12 passed`） | Phase 2 / 2.1 gate |
220| 3 | `python3 -m pytest tests/test_smoke.py tests/test_dynamics.py tests/test_comprehensive.py -q` 通过（当前口径应为 `42 passed`） | Branch B/integration pytest suite |
221| 4 | PendingSignal exactly-once 语义由回归测试证明；不存在旧 `_feedback_loop()` 直接路径与队列双通道并存 | Phase 2.1 gate |
222| 5 | Branch A 的壳层语义等价检查通过（原 18 项能力点适配后覆盖） | branch-a shell semantics |
223| 6 | cie-datasets 8 场景全 PASS；并明确这是 formal validation script gate，而不是 pytest 项数的一部分 | formal_validation |
224| 7 | phi 不超 ±10.1（soft clamp 保留） | 数值稳定性 |
225| 8 | 非对称比能涌现词结构 | word_emergence 验证 |
226| 9 | validation.py 自动生成 JSON + MD 报告 | 工程要求 |
227| 10 | 无魔法数字，全部在 CIEConfig 中 | 可维护性 |
228
229---
230
231## 5. 风险
232
233| 风险 | 影响 | 缓解 |
234|------|------|------|
235| PendingSignal 与旧 `_feedback_loop()` 双通道并存 | `emit()` / `ingest()` / `commit_feedback()` 可能重复应用反馈，污染已验证动态行为 | 先过 Phase 2.1：单路径收口 + exactly-once 回归测试，再继续 |
236| 过早用 SedimentationProfile 直接替换 `experience_hits` | 破坏 Branch B 已验证的沉积/能力核形成动态 | Phase 3 先 dual-write/并行观测，替换延后到额外 gate |
237| A 的 validation.py 假设 A 的 snapshot 格式 | 字段不匹配 | Phase 5 逐字段适配 |
238| “tests pass” 口径写得过于笼统 | 把 pytest gate 与 formal validation script gate 混为一谈，误导后续实施 | 在计划中固定命令和预期输出，不再只写泛化口号 |
239| 合并后数值行为微变 | 原有测试值不完全匹配 | 允许 ±5% 浮点容差，但 formal validation 仍需单独复核 |
240
241---
242
243## 6. 时间估计
244
245| Phase | 预计耗时 |
246|-------|---------|
247| Phase 1 基底 | 30 分钟 |
248| Phase 2 信号队列 | 2 小时 |
249| Phase 2.1 单路径 gate | 45 分钟 |
250| Phase 3 沉积 Profile（dual-write） | 2 小时 |
251| Phase 4 参数统一 | 1 小时 |
252| Phase 5 验证框架 | 1.5 小时 |
253| Phase 6 全量验证 | 1 小时 |
254| **总计** | **~8.75 小时** |
255
256---
257
258## 7. 决策记录
259
260**方案 C 落板依据：**
261
262| 事实 | 数据 |
263|------|------|
264| Branch B formal dataset | **8/8 PASS**（`c110916` strict rerun 独立复现） |
265| Branch A formal dataset | **6/8 PASS**（`273f416` strict rerun；初中数学 phi=12.07 超限，跨学科 phi=20.18 超限） |
266| Branch A raw 五本课本 | 8/10（更早轮次） |
267| Branch B 理论贴合 | 三核量 (o,c,ω) 全实现 |
268| Branch A 工程壳 | PendingSignal + SedimentationProfile + validation.py |
269
270**核取 B 的理由**：非对称图/L_G/Dirichlet/circulation 是 README 理论主线的忠实实现，丢掉等于放弃 CIE 核心；Branch A 在稳定性上也不如 B（两个场景 phi 超限）。
271
272**壳取 A 的理由**：信号队列模式比直接调用更规整；SedimentationProfile 比计数器更精细；validation.py 自动报告是工程必需品。
273
274**本次审核补充判断**：上述高层决策仍然成立，没有证据支持改成“核取 A”或“壳取 B”。需要修正的是实施顺序：当前必须先在 Phase 3 前补一个 Phase 2.1 gate，消除 PendingSignal 双路径风险；而 SedimentationProfile 应先 dual-write，再决定是否替换 `experience_hits`。
275
276**三方共识**：George（决策者）、ChatGPT（Branch A 开发者/审查者）、Claude（Branch B 开发者/审查者）均同意方案 C。