# EdgeCFG Flow Fragments（Frag / ExitKind）— Structured→CFG lowering SSOT

Status: Draft（design SSOT candidate）  
Last updated: 2025-12-21  

Related:
- North star（CFG/ABI）: `docs/development/current/main/design/join-explicit-cfg-construction.md`
- Catch/Cleanup/Async: `docs/development/current/main/design/exception-cleanup-async.md`

## 目的（なぜ必要？）

EdgeCFG（block-parameterized CFG / edge-args SSOT）が固まると、次に残る “泥沼” はここだけになる:

- **構造化制御（if/loop + catch/cleanup）→ CFG** の lowering で起きる **exit 配線問題**
- 「pattern番号で推測分岐」が増殖しやすい領域（長期的には消したい）

この文書は「pattern番号の列挙」を設計の中心にしないために、Structured→CFG の lowering を
**合成代数（fragment composition）**として SSOT 化する。

結論（本書の北極星）:

- “分岐の中心” は pattern番号ではなく **ExitKind** と **Frag（fragment）** に置く
- 値の合流は EdgeCFG の **block params + edge-args** で表し、PHI/推測/メタに逃げない
- pattern は「Extractor（形の認識）/ Plan（最小要件の抽出）」までに縮退し、merge/配線層へ逆流させない

## “フロー” は 2 層ある（混ぜると崩れる）

1. **CFG層（EdgeCFG / plumbing）**
   - terminator 語彙: `Jump/Branch/Return/Invoke`
   - edge-args: terminator operand が SSOT
   - out_edges の参照点が SSOT（複数 edge 前提）

2. **Structured→CFG lowering 層（flow composition）**
   - `if/loop/catch/cleanup/seq` を “Frag の合成” として書く
   - 難しさの本体は **exit（脱出）の種類** と **ネスト** と **合流**

## コア概念（最小の強い箱）

### ExitKind（脱出の種類を一次概念にする）

最低限の ExitKind:

- `Normal`（fallthrough）
- `Break(loop_id)` / `Continue(loop_id)`
- `Return`
- `Unwind`（Invoke.err / catch へ）
- `Cancel`（async の drop/cancel 用。今は予約）

### EdgeStub（未配線の脱出エッジ）

“どこへ飛ぶべきか未確定” な edge を表す。最終的に EdgeCFG の terminator edge に落ちる。

例（概念）:

- `from: BlockId`
- `kind: ExitKind`
- `args: EdgeArgs`（ターゲット params に対応する値。target が未確定でも “役割” はここで決める）

### Frag（fragment）

```text
Frag = { entry_block, exits: Map<ExitKind, Vec<EdgeStub>> }
```

- `entry_block`: 断片の入口
- `exits`: 断片から外へ出る未配線 edge の集合

## 合成則（pattern列挙を写像へ落とす）

### seq(a, b)

- `a.exits[Normal]` を `b.entry` へ接続する（edge-args を必要に応じて写像）
- それ以外の exit は上位へ伝搬する

### if(cond, t, e)

- header に `Branch(cond, t.entry, e.entry)` を置く
- `t.Normal` と `e.Normal` は join へ集める（必要なら join block params を作る）
- `Break/Continue/Return/Unwind` は上位へ伝搬

### loop(body)

- header / latch / after を組み、`Continue` を header に戻す
- `Break` を after へ出す
- `Return/Unwind` は上位へ伝搬

### cleanup(body, cleanup_block)（finally の後継）

狙い: “脱出 edge 正規化”

- body の全 exit（Normal/Break/Continue/Return/Unwind/Cancel）を cleanup 経由へリライトする
- cleanup 後に “元の exit” を再発射する（ExitTag + payload を block params で運ぶ）

重要: 例外 edge（Invoke.err）も漏れなく cleanup に寄せる。

## pattern は最終的に消える？（設計としての答え）

消える（実装の中心概念から降格する）。

- pattern番号は **回帰テスト名/症状ラベル**としては残して良い
- 実装の中心は `Frag/ExitKind/join(block params)` の合成則になる
- 各 pattern 実装は “Extractor（形の認識）→ Frag 合成呼び出し” の薄い層へ縮退する

## 実装の入口（SSOT API を先に作る）

目的: “どこを触ればいいか” を 1 箇所に固定し、推測・部分続行・場当たり分岐を減らす。

推奨の入口:

- `EdgeCFG` の plumbing API（既存）: `BasicBlock::out_edges()` 等
- Structured→CFG の入口 API（新規）: `Frag` / `ExitKind` / `compose::{seq, if_, loop_ , cleanup}` 等

物理配置（案）:

- `src/mir/builder/control_flow/edgecfg/api/`（または `.../joinir/api/` に併設してもよい）
  - `frag.rs` / `exit_kind.rs` / `compose.rs` / `patch.rs`

## verify（Fail-Fast の置き場所）

- **NormalizeBox 直後**: terminator 語彙固定・edge-args 長さ一致・cond付きJump禁止など “意味SSOT” を確定
- **merge直前**: boundary/ABI/edge-args の矛盾を即死させ “配線SSOT” を確定
- **--verify**: PHI predecessor / CFG cache 整合 / edge-args の長さ一致を常設

## 直近の導入ステップ（最小で始める）

1. `Frag/ExitKind/EdgeStub` の型を追加（docs+code 入口 SSOT）
2. `seq/if/loop` の合成だけ実装（cleanup/Invoke は後段）
3. 既存 pattern のうち 1 本だけ `Frag` 合成に寄せる（Pattern8 推奨）
4. 2 本目で再利用が見えたら "pattern番号での枝刈り" を削って合成側へ寄せる

## Loop に関する注意（JoinIR-only）

- `cf_loop` は JoinIR-only（Hard Freeze）。EdgeCFG の “loop 直適用” を急いで別経路に生やすと SSOT が割れる。
- loop の EdgeCFG 化は、まず **BasicBlockId 層で持っている箇所（Phase 268 の if_form のような場所）**から適用を進める。
- JoinIR 側の loop は Phase 270 で **fixture/smoke による SSOT 固定**を先に行い、壊れたら最小差分で直す。

補足（Phase 270）:
- Pattern1（simple_while_minimal）は test-only stub のため、一般ループの “基準” には使えない。
- Phase 270 では “最小の固定形” を Pattern9（AccumConstLoop）として追加し、後で Frag 合成側へ吸収される前提で橋渡しにする。

## Bridge patterns（撤去条件SSOT）

ここで言う “bridge pattern” は、既存の JoinIR ルートを壊さずに **最小の固定形を先に通す**ための一時パターン。
（例: Phase 270 の `Pattern9_AccumConstLoop`）

- 原則:
  - bridge pattern は **汎用化しない**（固定形SSOT + fixture/smoke で仕様を固定するだけ）。
  - 将来は `Frag/ExitKind` 合成側へ **吸収して削除**する前提で追加する。
- 撤去条件（最低限）:
  1. loop の EdgeCFG 実戦投入が 1 箇所以上済み（BasicBlockId 層で `Frag + emit_frag` を使っている）
  2. bridge pattern の fixture が “Frag 合成経路” で PASS する
  3. quick/integration の FAIL 位置が悪化しないことを確認済み
- 撤去手順（最小）:
  - router から bridge pattern を外す → fixture/smoke で PASS 維持 → ファイル削除

## 実装入口（コード SSOT）

**Phase 264 で入口API を作成完了**

- 物理配置: `src/mir/builder/control_flow/edgecfg/api/`
- コア型: `ExitKind`, `EdgeStub`, `Frag`
- 合成関数: `seq`, `if_`, `loop_`, `cleanup`（シグネチャのみ、中身TODO）
- 検証: `verify_frag_invariants`（空実装）

**Phase 265 P0 で最小実装完了**

- `compose::loop_()`: exit集合の分類実装（配線なし、P1以降）
- `verify_frag_invariants()`: 最小検証追加（デバッグガード付き）
- Pattern8適用: P0ではやらない（偽Frag回避、P1から実戦投入）

**Phase 265 P1: 配線ロジック実装完了**

**目的**: Frag/ExitKind が BasicBlockId 層で配線できることを証明

**実装完了内容**:
- EdgeStub に `target: Option<BasicBlockId>` 追加
- compose::loop_() が Continue → header, Break → after への配線を実行
- verify_frag_invariants() が配線契約を検証（デバッグモード）
- test-only PoC で配線の実証完了（5個のテスト）

**配線契約**:
- Continue(loop_id) の EdgeStub.target = Some(header)
- Break(loop_id) の EdgeStub.target = Some(after)
- Normal/Return/Unwind の EdgeStub.target = None（上位へ伝搬）

**Phase 265 P1 のスコープ**:
- ✅ Frag 層での配線ロジック
- ✅ BasicBlockId 層でのテスト証明
- ❌ MIR 命令生成（Phase 266+）
- ❌ NormalizedShadow/JoinIR層への適用（Phase 266+、JoinIR-VM Bridge 改修後）

**Phase 265 P2 完了！（2025-12-21）**

**実装完了内容**:
- ✅ Frag に `wires: Vec<EdgeStub>` フィールド追加
- ✅ wires/exits 分離設計確立
  - **exits**: target = None のみ（未配線、外へ出る exit）
  - **wires**: target = Some(...) のみ（配線済み、内部配線）
- ✅ loop_() を wires 対応に更新（Break/Continue → wires）
- ✅ seq(a, b) 実装完了（a.Normal → wires）
- ✅ if_(header, cond, t, e, join_frag) 実装完了（t/e.Normal → wires）
- ✅ verify_frag_invariants() に wires/exits 分離契約追加（警告のみ）
- ✅ 全テスト PASS（13個: frag 3個 + compose 9個 + verify 1個）

**設計判断の記録**:

1. **なぜ wires/exits を分離するか？**
   - 問題: 解決済み配線と未解決 exit を混ぜると、次の合成で内部配線が再度配線対象になる
   - 決定: wires/exits を分離し、不変条件を強化
   - 理由: 合成の意味が素直になり、Phase 266 で wires を MIR terminator に落とすだけ

2. **なぜ if_ は join_frag を受け取るか？**
   - 問題: join: BasicBlockId だと、if の Normal exit が「join block」か「join 以降」か曖昧
   - 決定: join_frag: Frag を受け取る
   - 理由: if の Normal exit = join 以降（join_frag.exits）が明確、PHI 生成の柔軟性確保

3. **なぜ verify は警告のみか？**
   - P2 の役割: wires/exits 分離の証明に集中（MIR 命令生成なし）
   - Phase 266 で MIR 生成時に verify を厳格化（target 違反 → 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 化
- Pattern7 (SplitScan) を Frag 化
- Pattern8 (BoolPredicateScan) を Frag 化
- 再利用性の確認（pattern番号分岐削減）

現時点では既存 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（P0完了）: Branch の第一級化（BranchStub + emit_frag）

- 目的: Frag に Branch を第一級で追加し、wires（Jump/Return）と同様に MIR terminator へ落とす入口を作る。
- 追加:
  - `BranchStub`（header→then/else の分岐を表現）
  - `Frag.branches: Vec<BranchStub>`（Branch 専用、wires と分離）
  - `emit_frag(function, frag)`（SSOT: `emit_wires` + `set_branch_with_edge_args`、1 block=1 terminator を Fail-Fast）
- スコープ:
  - ✅ BasicBlockId 層で unit test により PoC 証明
  - ❌ NormalizedShadow/JoinIR への実適用は Phase 268 に繰り越し（層境界維持）

詳細: `docs/development/current/main/phases/phase-267/README.md`

## Phase 268（完了）: if_form.rs への Frag 適用 + compose::if_ Entry Edge-args SSOT化

### P0: 最小適用（emission 層経由）

- 目的: EdgeCFG Fragment を "層を跨がずに" 実戦投入する
- 戦略: `if_form.rs` に直接 Frag 構築コードを書かず、`emission/branch.rs` に薄い入口関数 `emit_conditional_edgecfg()` を追加
- 理由:
  1. **層が綺麗**: Frag 構築ロジックを emission 層に閉じ込める
  2. **差分が小さい**: if_form.rs は API 呼び出し差し替えのみ（3箇所削除 + 1箇所追加）
  3. **デバッグ容易**: 層境界が明確で問題切り分けが簡単
- 実装:
  - emission/branch.rs に `emit_conditional_edgecfg()` 追加
  - if_form.rs の `emit_conditional()` + `emit_jump()` 2箇所を削除し、新規 API 呼び出しに置換
- テスト結果:
  - ✅ cargo build --release: 成功
  - ✅ cargo test --lib --release: 1444/1444 PASS
  - ✅ quick smoke: 45/46 PASS

### P1: compose::if_() Entry Edge-args SSOT化

- 目的: compose::if_() の then/else entry edge-args を呼び出し側 SSOT にし、TODO 削除（Phase 267 P2+ からの継続）
- **核心原則**: compose::if_() 内部で then/else entry edge-args を "勝手に空 Vec で生成" しない → 呼び出し側が明示的に渡す
- 実装:
  - compose::if_() シグネチャ変更: `if_(header, cond, t, then_entry_args, e, else_entry_args, join_frag)`
  - emission/branch.rs::emit_conditional_edgecfg() から空 EdgeArgs を then/else 両方に渡す
  - EdgeCFG テスト更新（compose.rs 2箇所、emit.rs 1箇所）
  - TODO コメント削除完了
- テスト結果:
  - ✅ cargo build --release: 成功
  - ✅ cargo test --lib --release: 1444/1444 PASS
  - ✅ quick smoke: 45/46 PASS

### アーキテクチャ

```
if_form.rs (MirBuilder 層)
  ↓ 呼び出し
emission/branch.rs::emit_conditional_edgecfg() (emission 層: 薄ラッパー)
  ↓ 内部で使用
Frag 構築 + compose::if_() + emit_frag() (EdgeCFG Fragment API)
  ↓ 最終的に呼び出し
set_branch_with_edge_args() / set_jump_with_edge_args() (Phase 260 SSOT)
```

詳細: `docs/development/current/main/phases/phase-268/README.md`

Phase 267: JoinIR Pattern への適用
- NormalizedShadow への Frag 適用
- Pattern6/7/8 を Frag 化
- Branch 生成 + pattern番号分岐削減
- fixture + smoke test