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