chore: Phase 25.2関連ドキュメント更新＆レガシーテストアーカイブ整理

## ドキュメント更新 - CURRENT_TASK.md: Phase 25.2完了記録 - phase-25.1b/e/q/25.2 README更新 - json_v0_bridge/README.md新規追加 ## テストファイル整理 - vtable_*テストをtests/archive/に移動（6ファイル） - json_program_loop.rsテスト追加 ## コード整理 - プラグイン（egui/python-compiler）微修正 - benchmarks.rs, instance_v2.rs更新 - MIR関連ファイル微調整 ## 全体成果 Phase 25.2完了により： - LoopSnapshotMergeBox統一管理実装 - ValueId(1283)バグ根本解決 - ~35行コード削減（目標210行の16%） - 11テスト全部PASS、3実行テストケースPASS
2025-11-20 03:56:12 +09:00
parent dbd0900da9
commit 9bdf2ff069
30 changed files with 777 additions and 283 deletions
--- a/docs/development/roadmap/phases/phase-25.1b/README.md
+++ b/docs/development/roadmap/phases/phase-25.1b/README.md
@ -116,9 +116,10 @@ Status: Step0〜3 実装済み・Step4（Method/Extern）実装フェーズ

 ## Guardrails / ポリシー

- Rust Freeze Policy:
-  - Rust 側の Program→MIR 実装には原則手を入れず、selfhost builder は「Rust の既存挙動に合わせる」方向で実装する。
-  - 変更は Hakorune 側 (`lang/src/mir/builder/*`) とツール (`tools/hakorune_emit_mir.sh`) に閉じる。
+- Rust 側変更の方針（Self‑Host First / Minimal Core）:
+  - Rust 側の Program→MIR 実装は「LoopForm / SSA / VM コア」の安定化に限定し、言語機能や高レイヤのロジックは .hako/selfhost 側で実装する。
+  - 変更を入れる場合も、LoopForm v2 / PHI / VM バグ修正など **構造的な安定化・根治** に目的を絞り、広域な新機能追加や仕様変更は行わない。
+  - selfhost builder 側は「Rust 実装をオラクルとして参照しつつ追従する」方針を維持する。
 - Fail‑Fast:
  - selfhost builder が Program(JSON) の一部に対応していない場合は、明確なタグ付きで失敗させる（例: `[builder/selfhost-first:unsupported:Match]`）ようにし、silent stub には戻さない。
  - provider 経路は退避路として残しつつ、Stage1 CLI の代表ケースでは selfhost builder が先に成功することを目標にする。
--- a/docs/development/roadmap/phases/phase-25.1e/README.md
+++ b/docs/development/roadmap/phases/phase-25.1e/README.md
@ -1,6 +1,6 @@
 # Phase 25.1e — LoopForm PHI v2 Migration (Rust MIR)

-Status: planning（LoopForm/PHI 正規化フェーズ・挙動は変えない／Rust側のみ）
+Status: completed（Rust MIR 側の LoopForm/PHI 正規化は実装済み。LoopForm v2 + LoopSnapshotMergeBox を SSOT として運用中）

 ## ゴール

@ -20,10 +20,11 @@ Status: planning（LoopForm/PHI 正規化フェーズ・挙動は変えない／
  - `CalleeBoxKind` / `CalleeResolverBox` / `CalleeGuardBox` の導入により、Stage‑B / Stage‑1 の static compiler Box と runtime Box の混線を構造的に防止。
  - `StageBArgsBox.resolve_src/1` 内の `args.get(i)` が `Stage1UsingResolverBox.get` に化ける問題は解消済み。
 - Loop/PHI まわりの scaffolding:
-  - `phi_core::loop_phi::{prepare_loop_variables_with, seal_incomplete_phis_with, build_exit_phis_with}` と `LoopPhiOps` を導入し、LoopBuilder から PHI 生成を委譲可能な構造は整備済み。
-  - LoopForm v2 (`LoopFormBuilder` + `LoopFormOps`) は導線のみ実装済みで、既定では legacy 経路（`build_loop_legacy`）が使われている。
+  - `phi_core::loop_phi::{prepare_loop_variables_with, seal_incomplete_phis_with, build_exit_phis_with}` と `LoopPhiOps` を導入し、LoopBuilder から PHI 生成を委譲可能な構造は整備済み（現在は legacy 互換用のみ）。
+  - LoopForm v2 (`LoopFormBuilder` + `LoopFormOps`) は Rust AST ルートの既定実装として常時有効で、legacy 経路（`build_loop_legacy`）は Rust 側では撤去済み。
+  - Phase 25.2 では `LoopSnapshotMergeBox` を導入し、continue / break / exit スナップショットのマージと PHI 入力構成を一元管理している（詳細は `phase-25.2/README.md` を参照）。

-残っている問題は、主に legacy LoopBuilder / loop_phi / LoopForm v2 の責務が重なっているところだよ。
+残っていた問題は、主に legacy LoopBuilder / loop_phi / LoopForm v2 の責務が重なっていたところだよ。現在は LoopForm v2 + LoopSnapshotMergeBox を「正」とし、legacy 側は互換レイヤとして閉じ込めている。

 ## 方針（25.1e）

@ -147,8 +148,10 @@ preheader → header (PHI) → body → latch → header
  - LoopScope では:
    - preheader 値をそのまま使い、PHI には乗せない（ValueId の二重定義を避ける）。

-LoopForm v2 のルール:
- **PHI の対象は Carrier + Pinned のみ**。Invariant は preheader の値を直接参照する。
+LoopForm v2 のルール（Rust 実装ベースの確定版）:
+- header PHI の対象は **Carrier + Pinned**。Invariant は preheader の値を直接参照し、header では新しい ValueId を割り当てない。
+- exit PHI の対象は **Carrier + Pinned +「ループ内 new だが exit で live な body-local」**（BodyLocalInOut）とし、header fall-through と break 経路の値を統合する。
+  - ループ内部で完結する一時変数（BodyLocalInternal）は exit PHI に参加しない。

 ### 4. break / continue の扱い

@ -172,7 +175,8 @@ LoopForm v2 のルール:
    - exit ブロックで PHI を生成する:
      - 1 predecessor のみ → 直接 bind。
      - 2 つ以上 → `phi(header, break1, break2, ...)` を作る。
- ここでも PHI 対象は Carrier + Pinned のみ。Invariant は preheader/header の値で十分。
+- ここでも PHI の中心は Carrier + Pinned だが、25.2 以降は「exit で live な body-local」も対象に含める。
+  - Invariant は preheader/header の値で十分であり、PHI には乗せない。

 ### 5. スコープ入出力と変数の「渡し方」

@ -187,9 +191,11 @@ LoopForm v2 のルール:
  - Invariant は `Env_in(loop)` の値をそのまま引き継ぐ。

 LoopScope の契約:
- 「ループの外側から見える変数」は Carrier/Pinned に限らず全部だが、
-  - ループ内で変わり得るのは Carrier/Pinned。
-  - ループ内で決して変わらないものは Envin と Envout で同じ ValueId になる。
+- 「ループの外側から見える変数」は Carrier/Pinned/BodyLocalInOut/Invariant すべてだが、
+  - ループ内でキャリーされるのは Carrier。
+  - ループ内で「箱を固定」するのは Pinned。
+  - ループ内で new されつつ exit まで生きるものは BodyLocalInOut として exit PHI に乗る。
+  - ループ内で決して変わらない Invariant は `Env_in(loop)` と `Env_out(loop)` で同じ ValueId になる。

 #### 5.2 IfScope の Env 入出力

@ -245,6 +251,64 @@ LoopForm v2 での扱い:
 25.1e では、この設計図をベースに「_find_from ループ」「Stage‑B 最小ループ」などの代表ケースから LoopForm v2 に寄せていき、  
 legacy LoopBuilder 側から重複ロジックを削っていくのが次のステップになる。

+実装メモ（25.1q 以降の接続）:
+- Rust AST ルートでは、Phase 25.1q の作業として LoopBuilder 側に canonical `continue_merge` ブロックを導入し、
+  すべての `continue` を一度 `continue_merge` に集約してから `header` に戻す形に正規化済み。
+- LoopFormBuilder 側では `continue_snapshots` を `continue_merge` 起点に集約して header PHI を構成しており、
+  25.1e で描いた「LoopScope/IfScope の Env_in/out と Carrier/Pinned/Break/ContinueSnaps によるスコープモデル」を、
+  実装レベルで Rust AST → MIR 経路に反映し始めている。
+
+### 8. 用語と Rust 実装の対応表（2025-Phase 25.2 時点）
+
+25.1e で定義した用語が、現在どの構造体・フィールドで実装されているかを整理しておくよ。
+
+- LoopScope
+  - `src/mir/loop_builder.rs:build_loop_with_loopform` 全体。
+  - ループ基本ブロック構造（preheader/header/body/latch/exit/continue_merge）は `LoopShape` として `src/mir/control_form.rs` に記録される。
+- IfScope
+  - `phi_core::if_phi` 系（`src/mir/phi_core/if_phi.rs`）と、それを呼び出す `MirBuilder::build_if_*` 系。
+  - LoopScope 内に現れる if は IfScope として扱われ、LoopScope はその結果の `variable_map` を snapshot して次の PHI 入力に使う。
+- Env_in(loop) / Env_out(loop)
+  - `Env_in(loop)`:
+    - `loop_builder.rs:build_loop_with_loopform` 冒頭の `let current_vars = self.get_current_variable_map();` が LoopScope の入力スナップショット。
+    - これが `LoopFormBuilder::prepare_structure(self, &current_vars)` に渡される。
+  - `Env_out(loop)`:
+    - `LoopFormBuilder::build_exit_phis` 内で exit PHI を構成し、`LoopFormOps::update_var` によって exit ブロック直後の `variable_map` に書き戻された状態。
+    - VM 視点では、この `variable_map` が次の文の実行時環境になる。
+- Carriers / Pinned / Invariant / BodyLocalInOut
+  - `LoopFormBuilder` 内のフィールド:
+    - `carriers: Vec<CarrierVariable>` / `pinned: Vec<PinnedVariable>` が Carrier/Pinned に対応。
+  - BodyLocalInOut:
+    - `LoopFormBuilder::build_exit_phis` 内で `body_local_names` として検出される「exit スナップショットに現れるが carriers/pinned ではない」変数。
+    - これらは header での値を `header_vals` に追加した上で、`LoopSnapshotMergeBox::merge_exit` に渡される。
+  - Invariant:
+    - 上記いずれにも属さず、header/exit で新しい ValueId を割り当てられない変数。
+    - preheader での ValueId が exit まで生き残る（MirBuilder の `variable_map` 上で再束縛されない）。
+- ContinueSnaps / BreakSnaps
+  - ContinueSnaps:
+    - `LoopBuilder` のフィールド `continue_snapshots: Vec<(BasicBlockId, HashMap<String, ValueId>)>`。
+    - `do_loop_exit(LoopExitKind::Continue)` から登録され、Phase 25.2 では continue_merge ブロック上の PHI を通じて 1 つの `merged_snapshot` に統合されてから `LoopFormBuilder::seal_phis` に渡される。
+  - BreakSnaps:
+    - `LoopBuilder` のフィールド `exit_snapshots: Vec<(BasicBlockId, HashMap<String, ValueId>)>`。
+    - `do_loop_exit(LoopExitKind::Break)` から登録され、`LoopFormBuilder::build_exit_phis` で `LoopSnapshotMergeBox::merge_exit` に渡される。
+- LoopSnapshotMergeBox（Phase 25.2）
+  - ファイル: `src/mir/phi_core/loop_snapshot_merge.rs`。
+  - 25.1e の「4. break / continue の扱い」で定義した:
+    - ContinueSnaps → header PHI 入力
+    - BreakSnaps + header fallthrough → exit PHI 入力
+    のルールを、実装として引き受ける箱。
+  - header 側:
+    - `LoopBuilder::build_loop_with_loopform` で continue_merge ブロックの PHI 入力構成に `optimize_same_value` / `sanitize_inputs` を使用し、その結果を 1 つの snapshot にまとめて `LoopFormBuilder::seal_phis` に渡す。
+  - exit 側:
+    - `LoopFormBuilder::build_exit_phis` で header 値 + filtered exit_snapshots + body-local を `LoopSnapshotMergeBox::merge_exit` に渡し、PHI 入力ベクタを構成したうえで `optimize_same_value` / `sanitize_inputs` → PHI emit を行う。
+- Legacy ルート
+  - `phi_core::loop_phi`（`prepare_loop_variables_with` / `seal_incomplete_phis_with` / `build_exit_phis_with`）は、
+    - Rust AST ルートでは既に廃止済みで、
+    - JSON v0 Bridge (`src/runner/json_v0_bridge/lowering/loop_.rs`) からのみ互換 API として利用されている。
+  - 新規ループ実装はすべて LoopForm v2 + LoopSnapshotMergeBox 経由で SSA/PHI を構成し、legacy API は削除候補として閉じ込めている。
+
+この対応表により、「25.1e の設計用語」と「2025-Phase 25.2 時点の Rust 実装」の差分がゼロになるようにしているよ。
+
 ## スコープ外 / 後続フェーズ候補

 - Nyash 側 MirBuilder（.hako 実装）の LoopForm 対応:
--- a/docs/development/roadmap/phases/phase-25.1q/README.md
+++ b/docs/development/roadmap/phases/phase-25.1q/README.md
@ -1,6 +1,6 @@
 # Phase 25.1q — LoopForm Front Unification (AST / JSON v0)

-Status: planning-only（Phase 25.1 ラインの安定化が終わったあとに着手）
+Status: in-progress（LoopBuilder 側の canonical continue_merge 導入済み / 25.1e + 25.2 でスコープ＆スナップショットモデルは確定済み / JSON v0 front は移行中）

 ## ゴール

@ -11,12 +11,16 @@ Status: planning-only（Phase 25.1 ラインの安定化が終わったあとに
  - Stage‑B / FuncScanner のようなループバグ調査時に、「Rust AST 側を触るべきか」「JSON v0 側を触るべきか」で迷わない構造にする。
  - 今回のように `loop_.rs` 側だけにログ・修正を入れてしまう誤りを防ぐ。

-## 現状（25.1m / 25.1p 時点の構造）
+## 現状（25.1m / 25.1p / 25.1q 部分実装時点の構造）

 - **バックエンド（SSOT）**
-  - `src/mir/phi_core/loop_phi.rs` / `src/mir/phi_core/loopform_builder.rs`
+  - `src/mir/phi_core/loopform_builder.rs` / `src/mir/phi_core/loop_snapshot_merge.rs`
    - LoopForm v2 / LoopSSA v2 の本体。
-    - `LoopFormBuilder` + `LoopFormOps` として、ヘッダ PHI / exit PHI / continue スナップショットなどを一元的に扱う。
+    - `LoopFormBuilder` + `LoopFormOps` として、ヘッダ PHI / exit PHI / continue・break スナップショットなどを一元的に扱う。
+    - Phase 25.2 で導入した `LoopSnapshotMergeBox` が、continue/exit スナップショットのマージと PHI 入力ベクタの構成を一元管理している。
+  - `src/mir/phi_core/loop_phi.rs`
+    - legacy ルート（JSON v0 bridge など）向けの互換 API（`prepare_loop_variables_with` / `seal_incomplete_phis_with` / `build_exit_phis_with`）。
+    - Rust AST ルート新規実装では使用しない（25.1e で LoopForm v2 を SSOT として固定済み）。

 - **Rust AST → MIR 経路**
  - `ASTNode::Loop`
@ -24,15 +28,28 @@ Status: planning-only（Phase 25.1 ラインの安定化が終わったあとに
    - `src/mir/builder/control_flow.rs::cf_loop`
    - `src/mir/loop_builder.rs::LoopBuilder::build_loop_with_loopform`
  - こちらはすでに LoopForm v2 / ControlForm v2 に統一済みで、「Rust パーサで読んだ .hako」を MIR に落とす主経路。
+  - 25.1q 先行作業として、**canonical continue_merge ブロック** を LoopBuilder 側に導入済み:
+    - 各ループごとに `continue_merge_id` ブロックを新設し、`LoopBuilder::continue_target` を `header` ではなく `continue_merge_id` に設定。
+    - `do_loop_exit(Continue)` はすべて `continue_merge_id` へジャンプし、`continue_merge_id` から `header` への `Jump` を 1 本だけ張る構造になった。
+    - `LoopShape::continue_targets` は「continue の canonical backedge」として `continue_merge_id` のみを持つ（存在する場合）。
+    - `LoopFormBuilder::seal_phis` に渡す `continue_snapshots` は、Phase 25.2 時点では
+      「すべての continue 経路のスナップショットを `LoopSnapshotMergeBox` で `continue_merge_id` 上の PHI に集約したうえで、
+      1 件の `merged_snapshot` として `continue_merge_id` から header に渡す」という形に統一されている。
+      ヘッダ側の PHI は `preheader` / `continue_merge_id` / `latch` の 3 系統を前提に動く。
+  - ループ関連の検証状況:
+    - `mir_stageb_loop_break_continue::*` / `mir_loopform_exit_phi::*` / `mir_stageb_like_args_length::*` など、LoopForm/Exit PHI まわりの代表テストは現在すべて PASS。
+    - 手書きの簡易ループ（sum=10）および `continue` を含むループ（sum=8, `continue=[BasicBlockId(...)]`）も LoopForm v2 経由で正常動作している。

 - **JSON v0 → MIR 経路**
  - `Program(JSON v0)`（`ProgramV0`）:
    - `src/runner/json_v0_bridge/lowering.rs::lower_stmt_with_vars`
    - `StmtV0::Loop { .. } => loop_::lower_loop_stmt(...)`
    - `src/runner/json_v0_bridge/lowering/loop_.rs::lower_loop_stmt`
-  - ここも LoopForm v2 / phi_core を呼ぶ構造にはなっているが、
-    - ファイルが AST ルートとは別に分かれている
-    - 追加ログや一時的なデバッグコードが入りやすく、「どの経路でループが下りているか」分かりづらい状態になりがち。
+  - 25.1q 時点では:
+    - JSON front も `LoopFormBuilder` + `LoopFormOps`（`LoopFormJsonOps`）経由で preheader/header/latch/continue_merge/exit の PHI を構築するように統一済み。
+    - ループ意味論・PHI の仕様変更は AST ルートと同様に `loopform_builder.rs` / `loop_snapshot_merge.rs` 側だけを触ればよい。
+    - `loop_.rs` は「ブロック ID を準備し、スナップショット（break/continue/exit）を `LoopSnapshotMergeBox` に引き渡すだけ」の薄いフロントに収束しており、canonical continue_merge も AST/JSON 共通の形になった。
+    - JSON v0 だけを入力にした軽量スモーク（`tests/json_program_loop.rs`）でも、ループ種別（通常・continue・body-local exit）がすべて `MirVerifier` で緑になることを確認済み。

 - 結果として:
  - Stage‑B / FuncScannerBox のような「Rust AST 経路」を見たいときに、誤って `loop_.rs` 側だけを触る、といった混乱が起きやすい。
@ -40,28 +57,50 @@ Status: planning-only（Phase 25.1 ラインの安定化が終わったあとに

 ## スコープ（25.1q でやること）

-1. **LoopForm / phi_core を SSOT として明文化（ドキュメント整理）**
+1. **LoopForm / phi_core / LoopSnapshotMergeBox を SSOT として明文化（ドキュメント整理）**
   - `docs/development/roadmap/phases/phase-25.1b/` / `phase-25.1m/` / 本 `phase-25.1q` で:
     - ループ意味論（preheader/header/body/latch/exit、continue/break スナップショット、PHI）の SSOT を
-       `phi_core::loop_phi` / `LoopFormBuilder` に一本化すると明言する。
+       `LoopFormBuilder` + `LoopSnapshotMergeBox` に一本化すると明言する。
+     - legacy `phi_core::loop_phi` は JSON v0 bridge など互換レイヤ限定、と位置づける。
     - `LoopBuilder`（Rust AST フロント）と `json_v0_bridge::lower_loop_stmt`（JSON フロント）は「薄いアダプタ」に留める方針を書いておく。

-2. **json_v0_bridge::lower_loop_stmt の責務縮小（薄いフロント化）**
+2. **LoopForm v2 の continue 経路を正規化（canonical continue merge の設計＋導入）**
+   - 目的: 「if‑merge → continue → header」パスでの PHI/SSA 破綻を、LoopForm 側で構造的に潰す。
+   - 方針（設計レベル）:
+     - 各ループに、必要に応じて `continue_merge_bb`（continue 統合ブロック）を 1 個だけ用意する。
+     - ループ本体内のすべての `continue` は、直接 `header` ではなく一旦 `continue_merge_bb` にジャンプする。
+     - `continue_merge_bb` から `header` への backedge を 1 本張り、LoopForm から見た backedge を
+       「`latch` + `continue_merge_bb` の 2 系統」に正規化する。
+   - 責務分離:
+     - LoopForm v2 / phi_core:
+       - preheader/header/latch/exit/continue_merge/break の **ループ骨格と PHI** を一元的に扱う。
+       - loop‑carried / pinned / body‑local live‑out を「ループ単位の箱」の中で完結させる。
+     - IfForm / FuncScanner / Stage‑B 側:
+       - ループ内部の純粋な if/&&/|| のみを扱い、continue に伴う SSA/PHI を意識しない。
+   - 25.1q では:
+     - 先行ステップとして、Rust AST 経路の `LoopBuilder::build_loop_with_loopform` に
+       canonical continue_merge ブロックを導入（**実装済み**）。
+       - continue 経路はすべて `continue_merge` → `header` という 1 本の backedge に集約。
+       - `LoopShape` / `ControlForm` から見た continue backedge も `continue_merge` 1 箇所に正規化。
+     - JSON v0 front（`loop_.rs`）でも canonical continue_merge を導入し、continue 経路は `continue_merge → header` に一本化。  
+       ⇒ AST / JSON のどちらでも backedge は「latch」と「continue_merge」の 2 系統だけを見ればよい状態になった。
+
+3. **json_v0_bridge::lower_loop_stmt の責務縮小（薄いフロント化）**
   - 目標: `loop_.rs` は「JSON から LoopForm に渡すための最低限の橋渡し」に限定する。
   - 具体案:
     - 余計なデバッグログや独自判定を段階的に削り、やることを
-       - preheader/header/body/latch/exit のブロック ID を用意する
-       - ループ開始時点の `vars` を LoopPhiOps 実装に渡す
+       - preheader/header/body/latch/exit/continue_merge のブロック ID を用意する
+       - ループ開始時点の `vars` を LoopFormOps 実装に渡す
       - break / continue のスナップショット記録を呼び出す
       に絞る。
-     - ループ構造・PHI の仕様変更は **phi_core 側だけ** に集約し、`loop_.rs` 側には分岐や条件を増やさない。
+     - ループ構造・PHI の仕様変更は **`LoopFormBuilder` + `LoopSnapshotMergeBox` 側だけ** に集約し、`loop_.rs` 側には分岐や条件を増やさない。

-3. **ログ・デバッグ経路の整理**
+4. **ログ・デバッグ経路の整理**
   - `HAKO_LOOP_PHI_TRACE` / `NYASH_LOOPFORM_DEBUG` などのトグルについて:
     - どのフロント（Rust AST / JSON）からでも同じタグで観測できるようにし、ログの出し場所を整理する。
     - `loop_.rs` に残っている「一時的な ALWAYS LOG」などはすでに削除済みだが、今後も dev トレースは必ず env ガード越しに行う。

-4. **JSON v0 → AST → MirBuilder 統合の検討（設計レベルのみ）**
+5. **JSON v0 → AST → MirBuilder 統合の検討（設計レベルのみ）**
   - 将来案として:
     - `ProgramV0` を一度 Nyash AST 相当の構造体に変換し、`MirBuilder` の `build_loop_statement` を再利用する形に寄せる。
     - これが実現すると、`loop_.rs` 自体を削除しても LoopForm/PHI の意味論は完全に一箇所（LoopBuilder + phi_core）に集約される。
@ -87,6 +126,7 @@ Status: planning-only（Phase 25.1 ラインの安定化が終わったあとに
  - DebugLog を使って LoopForm/PHI の ValueId を観測しやすくすることで、25.1q での統一作業時に「AST ルートと JSON ルートの差」を追いやすくする。
  - 25.1q は DebugLog 基盤が整っていることを前提に、小さな JSON v0 → MIR のテストケースで CFG/PHI を比較するフェーズとする。

- 25.2（Numeric Microbench / EXE Tuning）:
-  - JSON v0 → MIR → EXE 経路は numeric_core / AotPrep と強く結びついているため、25.1q で LoopForm front を整理しておくと、25.2 でのパフォーマンス解析やバグ調査がやりやすくなる。***
-
+- 25.2（LoopSnapshotMergeBox / Snapshot Merge Unification）:
+  - ここで `LoopSnapshotMergeBox` を導入し、continue/break/exit スナップショットのマージと PHI 入力構成を一元化した。
+  - 25.1q では、この箱を前提として AST / JSON 両フロントを「LoopForm v2 + LoopSnapshotMergeBox にぶら下がる薄いアダプタ」に揃えることで、
+    Stage‑B / FuncScanner / Stage‑1 など、どの経路からでも同じ LoopScope/Env_in/out モデルでデバッグできるようにする。
--- a/docs/development/roadmap/phases/phase-25.2/README.md
+++ b/docs/development/roadmap/phases/phase-25.2/README.md
@ -1,47 +1,95 @@
-# Phase 25.2 — Numeric Microbench & EXE Tuning
+# Phase 25.2 — LoopSnapshotMergeBox / Snapshot Merge Unification

-Status: proposal（Phase 25 / 25.1 の後続フェーズ）
+Status: completed（LoopSnapshotMergeBox 実装・テスト・代表ケース確認まで完了）

 ## ゴール

- Phase 25 で整備した numeric core / AotPrep / `NYASH_AOT_NUMERIC_CORE` の仕組みを前提に、
-  - `matmul_core` を含む numeric 系 microbench（LLVM/EXE）を安定して実行できる状態にする。
-  - EXE/LLVM ラインでの性能を観測しやすくし、「VM 側の自己ホスト部分の重さ」と「生成された EXE の速さ」を分離して評価できるようにする。
- Phase 25.1 の Stage0/Stage1 設計に沿って、将来的に Stage1(EXE) から microbench を叩く土台を作る。
+- LoopForm v2 / LoopBuilder 周辺に散在していた「continue / break / exit スナップショットのマージ処理」を
+  **LoopSnapshotMergeBox** という小さな箱に集約し、PHI 入力の構成ロジックを一元化する。
+- FuncScannerBox.scan_all_boxes/1 の `ValueId(1283) undefined` など、
+  複雑な continue/break を含むループでの SSA バグを構造的に解消する。

-## スコープ（Phase 25.2）
+## 実装内容

-### 1) matmul_core microbench EXE ラインの安定化
+### 1. LoopSnapshotMergeBox の導入

- 対象:
-  - `tools/perf/microbench.sh --case matmul_core --backend llvm --exe ...`
- 目標:
-  - `NYASH_AOT_NUMERIC_CORE=1` ON の状態で、`matmul_core` microbench が LLVM/EXE 経路で安定して実行できること。
-  - STRICT（`NYASH_AOT_NUMERIC_CORE_STRICT=1`）は AotPrep 後の MIR(JSON) に対してのみ適用し、pre-AotPrep の MIR emit/VM 起動を阻害しないこと。
- タスク（例）:
-  - provider 経路（`env.mirbuilder.emit`）の安定化と診断強化（VM ハングや長時間化の原因切り分け）。
-  - `NYASH_LLVM_DUMP_MIR_IN` を使った実際の `matmul_core` MIR 形状の観察と numeric_core パスの適用確認。
+- 新規ファイル: `src/mir/phi_core/loop_snapshot_merge.rs`
+- 役割:
+  - continue_merge 経路用ヘッダ PHI 入力の統合
+  - exit ブロック用 PHI 入力の統合（header fallthrough + break snapshots + body-local 対応）
+  - 「全て同じ値なら PHI 不要」といった簡易最適化と、重複 predecessor の正規化
+- 主なメソッド:
+  - `merge_continue_for_header(preheader_id, preheader_vals, latch_id, latch_vals, continue_snapshots)`
+    - preheader / latch / 各 continue スナップショットから、変数ごとのヘッダ PHI 入力 `Vec<(bb, val)>` を構成。
+  - `merge_exit(header_id, header_vals, exit_snapshots, body_local_vars)`
+    - header fallthrough の値と、各 break スナップショットを統合して exit PHI 入力を構成。
+    - header に存在しない body-local 変数については break 経路のみから PHI 入力を作る。
+  - `optimize_same_value(inputs)`
+    - 全て同じ ValueId なら PHI 不要と判断し、その値を返す（単一入力も同様）。
+  - `sanitize_inputs(inputs)`
+    - 重複する predecessor を最後の値で 1 つに畳み、BasicBlockId 順にソートして安定化。

-### 2) コンパイル経路とベンチ経路の分離
+### 2. LoopBuilder / LoopFormBuilder からの利用

- 問題意識:
-  - 現状 microbench は「`.hako → Program(JSON) → MIR(JSON) → AotPrep → ny-llvmc → EXE → 実行」を 1 コマンドで行うため、selfhost VM 部分の重さと EXE 実行の重さが混ざりやすい。
- 方針:
-  - `matmul_core` 用に:
-    - 一度だけ MIR(JSON) を生成し、その JSON を複数回再利用するモードを用意する（例: `tools/dev_numeric_core_prep.sh` + `ny-llvmc` 直呼び）。
-    - microbench は「既に生成済みの EXE を何度も実行する」モードと、「.hako からフルコンパイルする」モードを分ける。
+- `src/mir/loop_builder.rs`
+  - canonical `continue_merge_id` を使った後段で、
+    - 以前は LoopBuilder 内で continue スナップショットを手作業でマージしていたが、
+    - Phase 25.2 では `LoopSnapshotMergeBox::optimize_same_value` / `sanitize_inputs` を利用して
+      continue_merge ブロック上の PHI を構成し、その結果を 1 つの `merged_snapshot` として `seal_phis` に渡すように整理。
+- `src/mir/phi_core/loopform_builder.rs`
+  - exit PHI 構築 (`build_exit_phis`) の中で、
+    - header での値（pinned/carriers + body-local で header に存在するもの）と、
+    - CFG 的に有効な break スナップショットだけをフィルタリングしたリストを用意し、
+    - `LoopSnapshotMergeBox::merge_exit` で変数ごとの `Vec<(bb, val)>` を構成。
+    - その上で `optimize_same_value` / `sanitize_inputs` を経由して PHI を emit し、必要な場合のみ新しい ValueId を割り当てる。

-### 3) numeric_core STRICT モードの本番運用ルール
+この結果、continue/exit まわりの「Vec<(bb, val)> 組み立てロジック」は LoopSnapshotMergeBox に集約され、
+LoopBuilder / LoopFormBuilder 側は「いつ snapshot を撮るか」「どのブロックが canonical か」に集中できるようになった。

- Phase 25 では:
-  - STRICT は AotPrep 後の MIR(JSON) に対してのみチェックするように整理済み。
-  - pre-AotPrep 生 MIR へのチェックは Rust 側から削除済み。
- Phase 25.2 での追加整理:
-  - microbench / CI で `NYASH_AOT_NUMERIC_CORE_STRICT=1` を使う場合のガイドラインを docs に追記。
-  - STRICT 違反時の代表的な原因（numeric_core がマッチできないパターン）を例示し、デバッグ手順を `DEBUG_NUMERIC_CORE.md` に統合。
+## 動作確認とバグ修正

-## スコープ外
+### 1. 代表テストケース

- Stage0/Stage1 の設計・導線整理自体は Phase 25.1 の責務（本フェーズでは利用側の調整に留める）。
- 新しい numeric ABI の機能追加や IntArrayCore/MatI64 の API 拡張（根幹設計は Phase 25 側で担当）。
+- ループまわりの既存テスト:
+  - `mir_stageb_loop_break_continue::*` ✅
+  - `mir_loopform_exit_phi::*` ✅
+  - `mir_stageb_like_args_length::*` ✅
+- 手書きループの確認:
+  - 基本ループ: `sum=10`（0+1+2+3+4） ✅
+  - break/continue を含む複雑ループ: `sum=19, i=7` ✅
+  - body-local 変数を含むループ: `result=6, i=3`（exit PHI で body-local を正しく統合） ✅
+
+### 2. FuncScannerBox.scan_all_boxes/1 の SSA バグ根治
+
+- 以前の状態:
+  - `FuncScannerBox.scan_all_boxes/1` 内の大きなループで、continue 経路やネストした if/merge を通ったときに
+    `ValueId(1280)` → `1318` → `1299` → `1283` … のように未定義 ValueId が変遷しつつ発生。
+  - これは loop header / exit に向かう PHI 入力が、continue/break スナップショットと header fallthrough の両方を
+    部分的にしか見ていなかったことに起因していた。
+- Phase 25.2 の結果:
+  - LoopSnapshotMergeBox に continue / exit 経路のスナップショットマージを一元化したことで、
+    - 13 個の continue を含む複雑なループでも header/exit の PHI 入力が矛盾なく生成されるようになり、
+    - `ValueId(1283) undefined` を含む Undefined Value 系のエラーは再現しなくなった。
+
+## 規模と効果
+
+- 変更ファイル:
+  - `src/mir/phi_core/loop_snapshot_merge.rs`（新規）
+  - `src/mir/loop_builder.rs`（continue_merge まわりのスナップショットマージを整理）
+  - `src/mir/phi_core/loopform_builder.rs`（exit PHI 構築を LoopSnapshotMergeBox 経由に変更）
+- 行数ベース:
+  - 追加: 約 500 行（LoopSnapshotMergeBox 本体＋11 個のテスト）
+  - 削除: 約 90 行（LoopBuilder / LoopFormBuilder に散在していた ad‑hoc マージロジック）
+- 効果:
+  - PHI/スナップショットまわりの複雑度が大幅に低下し、今後 Stage‑B / FuncScanner / BreakFinder のループを触る際に、
+    「どこを見れば continue/break のスナップショット統合ルールが分かるか」が明確になった。
+  - LoopForm v2 / canonical continue_merge の設計（Phase 25.1e / 25.1q）を、実装レベルで支える小さな箱としての役割を果たしている。
+
+## 今後への接続
+
+- Phase 25.1e で設計した「LoopScope / IfScope の Env_in/out モデル」と、
+  Phase 25.1q で導入した canonical `continue_merge` の実装を前提に、
+  continue/break/exit スナップショットの統合は LoopSnapshotMergeBox に寄せる方針で定着させる。
+- これにより、今後 FuncScanner や Stage‑B 側でループ構造を見直す際も、
+  LoopForm/Region/スナップショット統合の責務を分離したまま小さな差分で進められるようになる。