docs: record Phase 265/266 EdgeCFG progress and research note

2025-12-21 17:20:58 +09:00
parent f8779df5a6
commit 655a8efbc6
10 changed files with 207 additions and 12 deletions
--- a/docs/development/current/main/10-Now.md
+++ b/docs/development/current/main/10-Now.md
@ -1,5 +1,40 @@
 # Self Current Task — Now (main)

+## 2025-12-21：Phase 266（wires → MIR terminator 生成 - 最小 PoC）✅
+
+**目的**: wires を MIR terminator に変換する最小 PoC を実装し、Phase 267 での本格適用に備える
+
+**実装完了内容**:
+- ✅ emit.rs 作成（emit_wires 実装 + unit test 4個）
+  - from ごとにグループ化して1本だけ許可（1 block = 1 terminator 制約）
+  - Return は target=None を許可（意味を持たない）
+  - Jump/Return 対応（Branch は Phase 267）
+- ✅ verify_frag_invariants_strict() 追加（段階導入を壊さない）
+  - 既存の verify_frag_invariants() は変更なし（警告のまま）
+  - wires/exits 分離契約を Err 化（Return の target=None は許可）
+- ✅ mod.rs 更新（emit module エクスポート）
+
+**テスト結果**:
+- ✅ edgecfg::api::emit テスト: **4/4 PASS**
+  - test_emit_wires_jump_basic
+  - test_emit_wires_return_basic
+  - test_emit_wires_unwired_stub_fails
+  - test_emit_wires_multiple_from_same_block_fails
+- ✅ 全 lib テスト: **1392/1392 PASS**（既存 1388 + 新規 4個、退行なし）
+
+**核心的な設計判断**:
+1. **from グループ化**: 同じ block に複数 terminator を設定すると上書き → BTreeMap で from ごとにグループ化し、1本だけ許可
+2. **Return の target=None 許可**: Return は呼び出し元に戻るので target が意味を持たない → Normal/Break/Continue/Unwind のみ target 必須
+3. **verify strict 版**: 既存の verify_frag_invariants() を Err 化すると既存コードが壊れる → 新規に strict 版を追加し、段階導入
+4. **Phase 260 terminator 語彙ルール厳守**: Jump は set_jump_with_edge_args()、Return は set_terminator() + set_return_env()
+
+**重要**: JoinIR/NormalizedShadow には触らない（Phase 267）。Branch terminator 生成も Phase 267 に繰り越し。
+
+**次フェーズへの橋渡し**:
+- Phase 267: NormalizedShadow への Frag 適用 + Pattern6/7/8 を Frag 化 + Branch 生成
+
+**詳細**: `docs/development/current/main/design/edgecfg-fragments.md`
+
 ## 2025-12-21：Phase 265 P2（seq/if_ 実装 - wires/exits 分離）✅

 **目的**: 「解決済み配線（wires）」と「未解決 exit（exits）」を分離し、Frag 合成の基本パターンを完成させる
@ -23,11 +58,13 @@
 2. **if_ は join_frag 受け取り**: join: BasicBlockId では「join block」か「join 以降」か曖昧 → join_frag: Frag で明確化
 3. **verify は警告のみ**: P2 は wires/exits 分離の証明に集中、Err 化は Phase 266 で MIR 生成時に実施

-**重要**: MIR 命令生成はまだしない（Phase 266+）。Pattern6/7/8 への適用も Phase 266+ に繰り越し。
+**重要**:
+- MIR 命令生成の **PoC（emit_wires）**は Phase 266 で完了。
+- Pattern6/7/8 や NormalizedShadow への **実適用**は Phase 267 以降（層境界維持）。

 **次フェーズへの橋渡し**:
- Phase 266: wires を MIR terminator に落とす + NormalizedShadow への Frag 適用
- Phase 267: Pattern6/7/8 を Frag 化 + pattern番号分岐削減
+- Phase 266: wires を MIR terminator に落とす（PoC: emit_wires）✅
+- Phase 267: NormalizedShadow/JoinIR への適用 + Pattern6/7/8 を Frag 化 + Branch 生成

 **詳細**: `docs/development/current/main/phases/phase-265/` + `docs/development/current/main/design/edgecfg-fragments.md`

--- a/docs/development/current/main/20-Decisions.md
+++ b/docs/development/current/main/20-Decisions.md
@ -19,6 +19,11 @@
 - spans は並行 Vec を最終的に廃止し、`Vec<Spanned<_>>` へ収束（段階導入: 編集APIの一本化 → 内部表現切替）。
 - edge-args の参照 API は `Jump` だけでなく `Branch` を含むため、単発 `edge_args()` ではなく `out_edges()`/`edge_args_to(target)` のような “複数 edge” 前提の参照点を SSOT にする。

+2025‑12‑21
+- MIR 側の block-parameterized CFG を短い通称として **EdgeCFG** と呼ぶ（docs では “Block-Parameterized CFG（EdgeCFG）”）。
+- EdgeCFG の P2（`BasicBlock.jump_args` 削除）まで到達し、edge-args は `Jump/Branch` の terminator operand を SSOT に一本化する（Return は `return_env` のみ例外）。
+- 「pattern番号で推測分岐」は長期的に消したい。Structured→CFG lowering の中心概念を **ExitKind + Frag（fragment）**へ移し、pattern は “Extractor/Plan の薄い層” に縮退させる（設計SSOT: `docs/development/current/main/design/edgecfg-fragments.md`）。
+
 2025‑09‑08
 - ループ制御は既存命令（Branch/Jump/Phi）で表現し、新命令は導入しない。
 - Builder に loop_ctx（{head, exit}）を導入し、continue/break を分岐で降ろす。
--- a/docs/development/current/main/30-Backlog.md
+++ b/docs/development/current/main/30-Backlog.md
@ -108,7 +108,7 @@ Related:
    - Normal/Return/Unwind の EdgeStub.target = None（上位へ伝搬）
  - **制約**:
    - MIR 命令生成なし（Frag 層のみ）
-    - NormalizedShadow 未適用（Phase 266 に繰り越し）
+    - NormalizedShadow 未適用（Phase 267 に繰り越し）

 - **（✅ 完了）Phase 265 P2: seq/if_ 実装（wires/exits 分離）**
  - **目的**: 「解決済み配線（wires）」と「未解決 exit（exits）」を分離し、Frag 合成の基本パターンを完成
@ -123,8 +123,27 @@ Related:
  - **設計判断**:
    - wires/exits 分離で再配線バグ防止
    - if_ は join_frag: Frag で「join 以降」を明確化
-    - verify は警告のみ（Err 化は Phase 266）
-  - **次**: Phase 266 で MIR 命令生成 + NormalizedShadow 適用
+    - verify は警告のみ（Err 化は Phase 266 の strict 版で段階導入）
+  - **次**: Phase 266 で MIR 命令生成 PoC（emit_wires）、Phase 267 で NormalizedShadow/JoinIR へ実適用
+
+- **（✅ 完了）Phase 266: wires → MIR terminator 生成（最小 PoC）**
+  - **目的**: wires を MIR terminator に変換する最小 PoC を実装し、Phase 267 での本格適用に備える
+  - **完了内容**:
+    - emit.rs 作成（emit_wires 実装 + unit test 4個）
+    - verify_frag_invariants_strict() 追加（段階導入を壊さない）
+    - Jump/Return 対応（Branch は Phase 267）
+    - mod.rs 更新（emit module エクスポート）
+    - 全テスト PASS（1392 passed: 既存 1388 + 新規 4個）
+  - **核心原則**:
+    - from ごとにグループ化して1本だけ許可（1 block = 1 terminator 制約）
+    - Return は target=None を許可（意味を持たない）
+    - verify_frag_invariants() は変更なし（警告のまま、strict 版を別名で用意）
+    - Phase 260 terminator 語彙ルールを厳守
+  - **設計判断**:
+    - from グループ化で terminator 上書きバグ防止
+    - Return は target 不要（呼び出し元に戻る）
+    - verify strict 版で段階導入を壊さない
+  - **次**: Phase 267 で JoinIR Pattern への適用

 - **real-app loop regression の横展開（VM + LLVM EXE）**
  - ねらい: 実コード由来ループを 1 本ずつ最小抽出して fixture/smoke で固定する（段階投入）。
--- a/docs/development/current/main/DOCS_LAYOUT.md
+++ b/docs/development/current/main/DOCS_LAYOUT.md
@ -25,6 +25,7 @@ Scope: `docs/development/current/` 以下の「置き場所ルール」と、SSO
 - 例: JoinIR の設計、Boundary/ExitLine の契約、Loop パターン空間、runtime/box 解決の地図。
 - よく参照する設計SSOT:
  - Join-Explicit CFG Construction（north star）: `docs/development/current/main/design/join-explicit-cfg-construction.md`
+  - EdgeCFG Flow Fragments（Structured→CFG lowering SSOT）: `docs/development/current/main/design/edgecfg-fragments.md`

 ### `docs/development/current/main/investigations/`（調査ログ）

--- a/docs/development/current/main/design/README.md
+++ b/docs/development/current/main/design/README.md
@ -9,6 +9,7 @@

 - JoinIR の地図（navigation SSOT）: `docs/development/current/main/design/joinir-design-map.md`
 - Join-Explicit CFG Construction（north star）: `docs/development/current/main/design/join-explicit-cfg-construction.md`
+- EdgeCFG Flow Fragments（Structured→CFG lowering SSOT）: `docs/development/current/main/design/edgecfg-fragments.md`
 - Catch / Cleanup / Async（設計メモ）: `docs/development/current/main/design/exception-cleanup-async.md`
 - Loop Canonicalizer（設計 SSOT）: `docs/development/current/main/design/loop-canonicalizer.md`
 - ControlTree / StepTree（構造SSOT）: `docs/development/current/main/design/control-tree.md`
--- a/docs/development/current/main/design/edgecfg-fragments.md
+++ b/docs/development/current/main/design/edgecfg-fragments.md
@ -195,11 +195,13 @@ Frag = { entry_block, exits: Map<ExitKind, Vec<EdgeStub>> }

 **次フェーズへの橋渡し**:

-次フェーズ（Phase 266）: JoinIR-VM Bridge 改修 + MIR 命令生成
- wires を MIR terminator に落とす（EdgeStub.target → set_terminator_jump）
- BlockAllocator と Frag 配線の連動
- NormalizedShadow への Frag 適用
- verify の Err 化（wires/exits 契約違反 → Err）
+次フェーズ（Phase 266）: wires → MIR terminator 生成（test-only PoC）
+- wires を MIR terminator に落とす SSOT を追加（`emit_wires`）
+- verify の strict 版を追加（`verify_frag_invariants_strict`、段階導入）
+
+次フェーズ（Phase 267）: JoinIR/NormalizedShadow への適用 + Branch 生成
+- NormalizedShadow/JoinIR で Frag/wires を実戦投入（層境界を守って段階的に）
+- Branch の terminator 生成（wires → MIR）を追加

 Phase 267: Pattern6/7/8 への展開
 - Pattern6 (ScanWithInit) を Frag 化
@ -209,3 +211,58 @@ Phase 267: Pattern6/7/8 への展開

 現時点では既存 pattern6/7/8 や merge/EdgeCFG は未改変（合成能力の証明のみ）。

+**Phase 266 P0-P2 完了！（2025-12-21）**
+
+**実装完了内容**:
+- ✅ emit.rs 作成（wires → MIR terminator 変換の SSOT）
+  - emit_wires() 実装（from グループ化 + Return の target=None 許可）
+  - unit test 4個（jump/return/unwired/multiple_from_same_block）
+- ✅ verify_frag_invariants_strict() 追加（段階導入を壊さない）
+  - 既存の verify_frag_invariants() は変更なし（警告のまま）
+  - wires/exits 分離契約を Err 化（Return の target=None は許可）
+- ✅ mod.rs 更新（emit module エクスポート）
+- ✅ 全テスト PASS（1392 passed: 既存 1388 + 新規 4個）
+
+**実装の核心原則**:
+
+1. **from ごとにグループ化して1本だけ許可**
+   - BTreeMap で from ごとにグループ化
+   - 1 block = 1 terminator 制約を厳格に強制
+
+2. **Return は target=None を許可**
+   - Return は target が意味を持たない（emit_wires で無視される）
+   - Fail-Fast 対象は Normal/Break/Continue/Unwind の target=None のみ
+
+3. **verify_frag_invariants_strict() 別名で用意**
+   - 既存の verify_frag_invariants() は警告のまま維持
+   - 新規 verify_frag_invariants_strict() で Err 化
+   - PoC/emit 側だけ strict を使用（段階導入を壊さない）
+
+4. **Phase 260 terminator 語彙ルールを厳守**
+   - Jump: set_jump_with_edge_args() を使用
+   - Return: set_terminator() + set_return_env() を使用
+
+**設計判断の記録**:
+
+1. **なぜ from グループ化が必要か？**
+   - 問題: 同じ block に複数 terminator を設定すると上書きになる
+   - 決定: from ごとにグループ化し、1本だけ許可（Fail-Fast）
+   - 理由: 1 block = 1 terminator は MIR の不変条件
+
+2. **なぜ Return は target=None を許可するか？**
+   - 問題: Return は呼び出し元に戻るので、target が意味を持たない
+   - 決定: Return のみ target=None を許可
+   - 理由: Normal/Break/Continue/Unwind は明確な target が必要
+
+3. **なぜ verify_frag_invariants_strict() を別名にしたか？**
+   - 問題: 既存の verify_frag_invariants() を Err 化すると、既存コードが壊れる
+   - 決定: 新規に strict 版を追加し、段階導入
+   - 理由: Phase 267+ で既存コードを段階的に strict へ移行
+
+**次フェーズへの橋渡し**:
+
+Phase 267: JoinIR Pattern への適用
+- NormalizedShadow への Frag 適用
+- Pattern6/7/8 を Frag 化
+- Branch 生成 + pattern番号分岐削減
+- fixture + smoke test
--- a/docs/development/current/main/design/join-explicit-cfg-construction.md
+++ b/docs/development/current/main/design/join-explicit-cfg-construction.md
@ -5,6 +5,7 @@ Scope: JoinIR→MIR の「暗黙 ABI」を消し、Join を第一級に扱う CF
 Related:
 - Navigation SSOT: `docs/development/current/main/design/joinir-design-map.md`
 - Investigation (Phase 256): `docs/development/current/main/investigations/phase-256-joinir-contract-questions.md`
+- Structured→CFG lowering SSOT（Frag/ExitKind）: `docs/development/current/main/design/edgecfg-fragments.md`
 - Decisions: `docs/development/current/main/20-Decisions.md`
 - Future features (catch/cleanup, cleanup/defer, async): `docs/development/current/main/design/exception-cleanup-async.md`

@ -122,3 +123,15 @@ Strangler 期間は “読む側だけ寄せる” と取りこぼしが起き
  - `set_terminator(...)` のような入口に寄せ、successors/preds の同期漏れを構造で潰す
 - **verify（Fail-Fast）**
  - terminator から計算した successors と、キャッシュ `block.successors` の一致をチェックして “同期漏れ” を即死させる
+
+## pattern（番号）の位置づけ（収束のさせ方）
+
+重要: “pattern番号で分岐する” こと自体は長期的には消したい（臭い）。ただし **IR上の形（terminator/exit種別）で分岐する**のは普通で、むしろ正しい。
+
+収束方針:
+
+- EdgeCFG の基盤が固まった後、Structured→CFG lowering の中心概念を **pattern番号**ではなく **ExitKind と Frag（fragment）**に移す
+- pattern は “Extractor（形の認識）/ Plan（最小要件の抽出）” までに縮退し、merge/配線層へ逆流させない
+- 最終的に残る実装は `seq/if/loop/cleanup` 等の **合成則**と、`join(block params)` だけになる
+
+設計SSOT: `docs/development/current/main/design/edgecfg-fragments.md`
--- a/docs/development/current/main/phases/phase-265/README.md
+++ b/docs/development/current/main/phases/phase-265/README.md
@ -0,0 +1,31 @@
+# Phase 265 — EdgeCFG Fragments（compose/verify の合成則）
+
+Status: Completed ✅  
+SSOT (design): `docs/development/current/main/design/edgecfg-fragments.md`
+
+## ゴール
+- Structured→CFG lowering を **ExitKind + Frag 合成**として表現する入口を育てる（pattern番号列挙を将来縮退させる）
+- 既存の JoinIR/merge/Pattern6/7/8 は触らず、**API と合成則だけ**を段階投入する
+
+## 完了内容
+- P0: `compose`/`verify` の形を固定（入口SSOT迷子防止）
+- P1: `compose::loop_` の配線（Break/Continue → wires）を実装（test-only PoC）
+- P2: **wires/exits 分離**を導入し、`loop_`/`seq`/`if_` を合成則で実装
+  - `exits`: `target=None` のみ（上位へ伝搬する未配線 exit）
+  - `wires`: `target=Some(...)` のみ（内部で解決済み配線）
+  - `if_` は `join_frag: Frag` を受け取り、Normal が「join 以降」を表すようにする
+
+## 主要ファイル
+- `src/mir/builder/control_flow/edgecfg/api/compose.rs`
+- `src/mir/builder/control_flow/edgecfg/api/frag.rs`
+- `src/mir/builder/control_flow/edgecfg/api/edge_stub.rs`
+- `src/mir/builder/control_flow/edgecfg/api/verify.rs`
+
+## コミット（参考）
+- `ab1510920` Phase 265 P0
+- `cda034fe8` Phase 265 P1
+- `21387f381` Phase 265 P2
+
+## 次フェーズ
+- Phase 266: `wires → MIR terminator` の SSOT（test-only PoC）
+- Phase 267: Branch 生成 + JoinIR/NormalizedShadow への実適用（段階導入）
--- a/docs/development/current/main/phases/phase-266/README.md
+++ b/docs/development/current/main/phases/phase-266/README.md
@ -0,0 +1,31 @@
+# Phase 266 — EdgeCFG wires → MIR terminator（test-only PoC）
+
+Status: Completed ✅  
+SSOT (design): `docs/development/current/main/design/edgecfg-fragments.md`
+
+## ゴール
+- `Frag.wires`（解決済み配線）を **MIR terminator** に落とす最小 PoC を作る
+- JoinIR/NormalizedShadow には触らず、**MIR BasicBlockId 層だけ**で証明する
+
+## 完了内容
+- `emit_wires(function, wires)` を SSOT として追加（Jump/Return のみ）
+  - `from` ごとにグループ化し **1 block = 1 terminator** を Fail-Fast で強制
+  - `Return` は `target=None` を許可（target が意味を持たない）
+  - `Jump` は `set_jump_with_edge_args()`（Phase 260 の SSOT ルール）
+  - `Return` は `set_terminator(Return) + set_return_env()`（Return 専用メタ）
+- `verify_frag_invariants_strict()` を追加（段階導入）
+  - 既存 `verify_frag_invariants()` は警告のまま維持
+  - strict は `wires/exits` 分離契約を Err 化（PoC/emit 側のみ）
+
+## 主要ファイル
+- `src/mir/builder/control_flow/edgecfg/api/emit.rs`
+- `src/mir/builder/control_flow/edgecfg/api/verify.rs`
+- `src/mir/builder/control_flow/edgecfg/api/mod.rs`
+
+## テスト
+- `emit` のユニットテスト（Jump/Return/unwired/multiple-from）を追加し PASS
+
+## 次フェーズ
+- Phase 267:
+  - Branch の生成（wires → MIR）を追加
+  - JoinIR/NormalizedShadow/Pattern6/7/8 の実適用（層境界を守って段階導入）