refactor(joinir): make jump_args layout explicit (Phase 256)

docs/development/current/main/design/README.md

@@ -8,6 +8,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`
 - Loop Canonicalizer（設計 SSOT）: `docs/development/current/main/design/loop-canonicalizer.md`
 - ControlTree / StepTree（構造SSOT）: `docs/development/current/main/design/control-tree.md`
 - Normalized ExprLowerer（式の一般化 SSOT）: `docs/development/current/main/design/normalized-expr-lowering.md`

docs/development/current/main/design/join-explicit-cfg-construction.md

@@ -0,0 +1,68 @@
+# Join-Explicit CFG Construction
+
+Status: SSOT（design goal）  
+Scope: JoinIR→MIR の「暗黙 ABI」を消し、Join を第一級に扱う CFG へ収束させる北極星（north star）。  
+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`
+- Decisions: `docs/development/current/main/20-Decisions.md`
+
+## Goal（最終形）
+
+“Join-Explicit CFG Construction” を目指す。
+
+- `Jump/continuation/params/edge-args` を **第一級（explicit）**として扱う
+- JoinIR↔MIR 間の **暗黙 ABI（順序/長さ/名前/役割）** をなくす（SSOT を 1 箇所に封印）
+- 変換は「意味の解釈」ではなく「写像（mapping）」に縮退する
+
+## Non-Goals（いまはやらない）
+
+- JoinIR を即座に削除する（まずは ABI/Contract で SSOT を固める）
+- PHI を全面廃止して block params に置換する一括リファクタ（段階導入）
+
+## 現状の問題（Phase 256 で露出した型）
+
+- `jump_args` / `exit_bindings` / `entry.params` / `boundary.join_inputs` が “だいたい同じ順序” を前提にしており、ズレると SSA/dominance が破綻する
+- `expr_result` と LoopState carrier が同一 ValueId になり得るが、legacy “expr_result slot” 推測で offset がずれて誤配線になる
+- `jump_args` が IR の外側メタ扱いだと、DCE/最適化が “use” を見落としやすい
+- spans が並行 Vec だと、パスが 1 箇所でも取りこぼすと SPAN MISMATCH になる
+
+## 移行戦略（段階導入 / Strangler）
+
+原則:
+- **移行を先に固定**し、機能追加は「新契約に乗るものだけ」併走する（旧経路に新機能を足さない）
+- 既定挙動を変えない（必要なら dev-only の診断ガードで観測）
+
+### Stage 1（短期）: JoinIR を “ABI/Contract 付き Normalized SSOT” にする
+
+狙い: 推測をなくし、順序/役割の SSOT を 1 箇所へ寄せる。
+
+- boundary に `jump_args_layout` のような **layout SSOT** を持たせ、collector/rewriter が推測しない
+- `JoinInst::Jump` を terminator 語彙として正規化（cond 付きは `Branch` へ寄せる）
+- continuation の識別は **ID SSOT**（String は debug/serialize のみに縮退）
+
+受け入れ:
+- `--verify` が PASS（SSA/dominance/PHI/ExitLine の契約違反が消える）
+- 直撃回帰テスト（`expr_result == carrier` 等）が固定される
+
+### Stage 2（中期）: MIR を “edge-args を terminator operand に持つ CFG” に寄せる
+
+狙い: `jump_args` を “意味データ” として IR に埋め込み、DCE/CFG が自然に追える形へ収束する。
+
+- `jump_args` を BasicBlock 外メタから terminator operand へ寄せる（段階導入: 互換フィールド併存→移行）
+- spans は `Vec<Spanned<_>>` へ（API で不変条件を守る）
+
+受け入れ:
+- `jump_args` 由来の use が最適化で消えない（テストで固定）
+- SPAN MISMATCH が構造的に起きない
+
+### Stage 3（長期）: JoinIR と MIR の境界を薄くし、必要なら JoinIR を builder へ降格
+
+狙い: “bridge/merge が意味解釈する余地” を最小化し、一本の CFG 語彙に収束させる。
+
+- JoinIR を SSOT IR として残すか、builder DSL として降格するかは、この段階で再判断する
+
+## 実務ルール（Phase 中の運用）
+
+- 新パターン/新機能は「新しい Contract で記述できる場合のみ」追加する
+- Contract の導入中は “機能追加より SSOT 固め” を優先する（泥沼デバッグの再発防止）

docs/development/current/main/design/joinir-design-map.md

@@ -85,6 +85,15 @@ flowchart LR
 
 ---
 
+## North Star: Join-Explicit CFG Construction
+
+JoinIR/MIR 間に生える “暗黙 ABI（順序/長さ/名前/役割）” を減らし、Join を第一級として扱う CFG へ収束させる。
+
+SSOT（設計目標）:
+- `docs/development/current/main/design/join-explicit-cfg-construction.md`
+
+---
+
 ## “箱”の責務マップ（担当境界）
 
 | 領域 | 役割（何を決めるか） | 主な入口/箱（SSOT寄り） | 主な出力 | Fail-Fast（典型） |