hakorune/docs/development/roadmap/phases/phase-25.1f

Phase 25.1f — ControlForm（Loop/If 共通ビュー）& Stage‑B ハーネス準備

Status: planning（設計＋観測レイヤ追加／挙動は変えない）

ゴール

• LoopForm v2（ループ）と If まわり（phi_core::if_phi）に対して、制御構造の共通ビュー ControlForm を用意する。
• すでに導入済みの Conservative PHI Box（If/Loop 用 SSA/PHI ロジック）を、
  • ループ専用／If 専用でバラバラに持つのではなく、
  • ControlForm を単一の SSOT（Single Source of Truth）として参照する方向に寄せる。
• Stage‑B 最小ハーネスや Stage‑1 Resolver など、「複雑な if + loop」を含む経路で、
  • ループと条件分岐の形を 構造として観測・検証できる足場 を整える（いきなり本番導線は切り替えない）。

※ このフェーズでは Rust の挙動は変えず、「制御構造の箱（LoopShape / IfShape）＋ ControlForm の定義」と、 デバッグ／テスト用の観測導線（トレース）までに留める。

背景（25.1d / 25.1e までの位置づけ）

• 25.1d:
  • Rust MIR ビルダーの SSA/PHI バグ（ValueId 二重定義／non‑dominating use／undefined Value）を、
    小さな Rust テスト（mir_*_verifies）で炙り出して修正済み。
  • CalleeBoxKind / BoxCompilationContext によって Stage‑B / Stage‑1 の静的 Box とランタイム Box の混線も構造的に解消。
• 25.1e:
  • ループの PHI 生成の SSOT を LoopForm v2 + phi_core に寄せ、
    • Exit PHI、break/continue、pinned/carrier/invariant 変数を整理。
  • Conservative PHI Box（If/Loop 両方で「安全側に倒す PHI 生成」を行い、不要な PHI は将来の削除で最適化する方針）を実装。
  • Stage‑1 UsingResolver 系テストと Program v0 PHI スモーク、Stage‑B 風ループテストはすべて緑。

ここまでで「LoopForm v2 + Conservative PHI」の根本バグはだいたい取り切れたが、

• PHI ロジックが If 用と Loop 用で散在している。
• Stage‑B ハーネス側で「どの loop/if がどう組み合わさっているか」を横断的に眺める手段がまだ弱い。

→ 25.1f では、Loop / If を一段上から包む ControlForm レイヤを定義し、Stage‑B ハーネスに進む前準備として構造を固める。

方針 — ControlForm / Shape の設計

型と場所

• 新規モジュール案:
  • src/mir/control_form.rs
• 基本構造:
  • LoopShape:
    • preheader: BasicBlockId
    • header: BasicBlockId
    • body: BasicBlockId（代表 body ブロック）
    • latch: BasicBlockId
    • exit: BasicBlockId
    • continue_targets: Vec<BasicBlockId>
    • break_targets: Vec<BasicBlockId>
  • IfShape:
    • cond_block: BasicBlockId
    • then_block: BasicBlockId
    • else_block: Option<BasicBlockId>
    • merge_block: BasicBlockId
  • ControlKind:
    • Loop(LoopShape) / If(IfShape)（将来 Switch / Match も追加可能な余地だけ確保）
  • ControlForm:
    • entry: BasicBlockId（構造全体の入口）
    • exits: Vec<BasicBlockId>（構造を抜けた先のブロック群）
    • kind: ControlKind

生成パス（from_loop / from_if）

• LoopForm → ControlForm:
  • 既存の LoopForm v2（LoopFormBuilder が返す構造）から LoopShape を構築し、
  • ControlForm::from_loop(loop_form: &LoopForm) で共通ビューに変換する。
  • entry = preheader, exits = [exit] というルールで統一。
• If 用:
  • 既存の phi_core::if_phi / builder 側の if lowering から、必要な情報をまとめた薄い IfForm（もしくは IfShape 直構築）を定義。
  • ControlForm::from_if(if_form: &IfForm) で共通ビューに変換。
  • entry = cond_block, exits = [merge_block] を基本とし、将来 else if や switch なども扱える形で設計。

Invariant / Debug 用の Trait

• 25.1f では「挙動を変えない」ため、ControlForm 自体は 観測・検証専用 として設計する:
  • debug_dump(&self):
    • Loop / If の各ブロック ID を一括でログ出力し、Stage‑1 / Stage‑B テストから CFG の形を視覚的に確認できるようにする。
  • CfgLike トレイト（任意）:
    • fn has_edge(&self, from: BasicBlockId, to: BasicBlockId) -> bool;
    • fn predecessors_len(&self, block: BasicBlockId) -> usize;
    • LoopShape::debug_validate<C: CfgLike>(&self, cfg: &C) などを #[cfg(debug_assertions)] で用意し、 Loop/If の形が想定どおりかを assert できるようにする。

タスク粒度（25.1f TODO）

F‑1: ControlForm / Shape の設計ドキュメント

• 本 README で:
  • LoopShape / IfShape / ControlKind / ControlForm の責務とフィールドを明文化。
  • LoopForm v2 との対応関係（preheader/header/latch/exit/continue/break）を図解レベルで通るところまで整理。
• 25.1e の LoopForm 仕様（Carrier/Pinned/Invariant / break/continue / exit PHI）と整合していることを確認。

F‑2: Rust 側のスケルトン実装（導線のみ）

• src/mir/control_form.rs を追加し、以下のみ実装:
  • 型定義（LoopShape / IfShape / ControlKind / ControlForm）。
  • ControlForm::from_loop(&LoopForm) / ControlForm::from_if(&IfForm) の雛形。
  • debug_dump() と debug_validate()（#[cfg(debug_assertions)] 前提、もしくはテスト専用）。
• 既存のビルダー/PHI ロジックは まだ ControlForm を使わない:
  • 25.1e で安定した Conservative PHI 実装を壊さないため、Phase 25.1f では「観測オンリー」に留める。

F‑3: Stage‑1 / Stage‑B テストへの観測フック

• 対象テスト:
  • src/tests/mir_stage1_using_resolver_verify.rs 系（Stage‑1 UsingResolver の min/full）。
  • Stage‑B 風ループ／Program v0 PHI スモーク（mir_loopform_exit_phi.rs / mir_stageb_loop_break_continue.rs / tools/smokes/v2/...）。
• 方針:
  • NYASH_CONTROL_FORM_TRACE=1 などの dev フラグが立っているときだけ、
    • LoopForm v2 から ControlForm を生成し、
    • debug_dump() で構造をトレースログに出す。
  • これにより、Stage‑B ハーネスを組む前に「実際にどんな Loop/If 形が発生しているか」を CFG レベルで確認できる。

F‑4: Conservative PHI との接続計画（設計のみ）

• 25.1e で実装した Conservative PHI Box（If/Loop）のロジックを整理し、将来像を設計として固定する:
  • 目標: merge_modified_at_merge_with / LoopForm v2 Exit PHI 生成などを、
    • ControlForm ベースの API で呼べるようにする（例: build_phi_for_control(form: &ControlForm, ...)）。
  • 25.1f では:
    • どの関数をどこまで ControlForm 受けにするか、
    • 既存 API との互換性をどう保つか、 を README 上で設計するところまで。
  • 実際の実装切り替え（PHI ロジックを ControlForm ベースに差し替える）は、Stage‑B ハーネスと合わせて 別フェーズ（25.1g または 25.2 以降） に送る。

F‑5: Stage‑B ハーネスへの橋渡し準備

• Stage‑B 最小ハーネス（tools/test_stageb_min.sh / lang/src/compiler/tests/stageb_min_sample.hako）における:
  • ループパターン（skip_ws などの単純ループ、複数 break/continue を含むループ）。
  • if + loop のネスト構造。 を洗い出し、LoopForm v2 + IfShape + ControlForm ですべて表現できることを確認する。
• 将来のタスク（このフェーズでは設計のみ）:
  • Stage‑B ハーネスの SSA/PHI 検証を ControlForm 経由で行う Rust テストをどう設計するかをまとめる。
  • Stage‑B 側の .hako LoopSSA（lang/src/compiler/builder/ssa/loopssa.hako）が、LoopForm v2 / ControlForm の設計と齟齬を起こさないように、必要な制約・前提条件を明記する。

F‑6: .hako 側 ControlFormBox（Layer 2 の箱）定義

• 目的:
  • Rust 側 LoopShape / IfShape / ControlForm に対応する Hakorune 実装版の箱 を用意し、
    Stage‑B / LoopSSA が Rust と同じモデルでループ/if を扱えるようにする。
  • 将来の LoopSSA 実装は、この箱経由で構造を受け取ることを前提に設計する。
• 現行構文版（Layer 2）:
  • ファイル案: lang/src/shared/mir/control_form_box.hako
  • 定義案（BlockId は現状 i64/IntegerBox で表現）:

    static box ControlFormBox {
      kind_name: StringBox           // "loop" or "if"
      entry: IntegerBox              // BasicBlockId 相当
      exits: ArrayBox                // of IntegerBox (BlockId)
    
      // Loop fields (kind_name == "loop" の時のみ有効)
      loop_preheader: IntegerBox
      loop_header: IntegerBox
      loop_body: IntegerBox
      loop_latch: IntegerBox
      loop_exit: IntegerBox
    
      // If fields (kind_name == "if" の時のみ有効)
      if_cond: IntegerBox
      if_then: IntegerBox
      if_else: IntegerBox
      if_merge: IntegerBox
    
      birth(kind) {
        me.kind_name = kind
        me.exits = new ArrayBox()
      }
    
      is_loop() {
        return me.kind_name == "loop"
      }
    
      is_if() {
        return me.kind_name == "if"
      }
    }
    

  • 対応表（Rust ↔ .hako）:
    • Rust LoopShape.preheader/header/body/latch/exit
      ↔ Hako loop_preheader/loop_header/loop_body/loop_latch/loop_exit
    • Rust IfShape.cond_block/then_block/else_block/merge_block
      ↔ Hako if_cond/if_then/if_else/if_merge
    • Rust ControlForm.entry/exits
      ↔ Hako entry / exits（exits は BlockId の配列）
• 将来構文版（Layer 3 の理想形・variant 導入前提）:
  • 将来の Nyash variant 構文が入ったら、ControlKind を enum 的に表現し、

    box ControlKind {
      variant Loop { preheader: BlockIdBox, header: BlockIdBox, ... }
      variant If   { cond_block: BlockIdBox, then_block: BlockIdBox, ... }
    }
    
    static box ControlFormBox {
      kind: ControlKind
      entry: BlockIdBox
      exits: ArrayBox
    }
    

    のような形に寄せる（現段階では設計メモのみ）。
• 25.1f でのスコープ:
  • control_form_box.hako に上記 Layer 2 版 ControlFormBox を実装する。
  • ただし Stage‑B / LoopSSA からはまだ使用しない（コンパイルが通る最小限の実装＋将来用の箱）。
  • Stage‑B LoopSSA 統合（ControlFormBox を実際に使って JSON v0→MIR を整理する）は、次フェーズに回す。

移行ステップ（Option A → B → C のロードマップ）

このフェーズ（25.1f）では、あくまで Option A = 観測レイヤーの完成 までをスコープにするよ。その上で、将来の B/C も含めて合意しておきたい移行順序はこうだよ:

1. Option A: 観測レイヤーを完璧にする（Phase 25.1f）

   • Rust:
     • LoopShape / IfShape / ControlForm 実装済み。
     • LoopBuilder から LoopForm v2 / lower_if_in_loop の出口で ControlForm::Loop/If を生成して debug_dump 済み。
     • NYASH_CONTROL_FORM_TRACE は「未設定=ON, 0/false=OFF」のヘルパーに統一済み。
   • .hako:
     • ControlFormBox（kind_name + loop_* / if_* + entry/exits）の箱だけ定義（まだ未使用）。
   • テスト/スモーク:
     • mir_stage1_using_resolver_* / mir_loopform_exit_phi.rs / mir_stageb_loop_break_continue.rs / tools/test_stageb_min.sh を回しつつ、 ControlForm トレースが panic せずに構造ログだけを出すことを確認する。

2. Option B: Conservative PHI ↔ ControlForm の統合（別フェーズ: 25.1g 想定）

   • ねらい:
     • いま merge_modified_at_merge_with（If）や LoopForm v2 Exit PHI が直接 BlockId/ValueId を持っている部分を、 ControlForm 経由で読めるように段階的に寄せていく。
   • 方針:
     • まず If から（ControlKind::If）→ ループ Exit PHI（ControlKind::Loop）の順に小さく進める。
     • 各ステップごとに:
       • 対応するテスト（Stage‑1 / Program v0 / Stage‑B 風）＋ test_stageb_min.sh を回し、
         SSA/PHI の赤ログが増えていないことを確認しながら移行する。
   • 注意:
     • これは 25.1f のスコープ外。Phase 25.1g（仮）として小さな差分に分割しながら実装する。

3. Option C: LoopBuilder/If 降下の ControlForm ベース正規化（さらに後ろのフェーズ）

   • ねらい:
     • 最終的には「LoopBuilder/If 降下がまず ControlForm を組み立てる」スタイルに寄せ、
       Conservative PHI / LoopSSA / .hako 側 LoopSSA が同じ ControlForm を揃って見る状態にする。
   • 規模:
     • 数百行単位のリファクタになるため、Phase 25.2 以降（Selfhost/Stage‑B の安定を見ながら）に分割してやる。
   • ガード:
     • 各ステップで代表スモーク（Stage‑1 / Stage‑B / Program v0 / test_stageb_min.sh）を流しながら進める。
     • NYASH_CONTROL_FORM_TRACE と .hako ControlFormBox を使って、常に「形」が崩れていないかを観測できるようにしておく。

このフェーズ（25.1f）は「Option A をやり切って足場を固める」ことに専念し、その上で 25.1g 以降で Option B/C に進む、というロードマップで進めるよ。

このフェーズで「やらないこと」

• if を loop に書き換えるような、意味論レベルの正規化は 行わない:
  • If は IfShape、Loop は LoopShape として、それぞれの形を尊重する。
• Stage‑B ハーネス本体の導入・既存パイプラインの切り替え:
  • test_stageb_min.sh の経路変更や .hako コンパイラ側の LoopSSA 実装変更は、25.1f では触らず、
    ControlForm の設計と観測レイヤ整備が完了してから別フェーズで扱う。
• Conservative PHI ロジックの大規模リライト:
  • 25.1e で安定させた If/Loop PHI 実装を、いきなり ControlForm ベースに書き換えることはしない。
  • まずは「どう書き換えるのが構造的に美しいか」を、このフェーズの README に設計として落とす。