hakorune/docs/development/current/main/joinir-architecture-overview.md

JoinIR Architecture Overview (2025‑12‑08)

このドキュメントは、JoinIR ライン全体（Loop/If lowering, ExitLine, Boundary, 条件式 lowering）の 「箱」と「契約」を横串でまとめた設計図だよ。selfhost / JsonParser / hako_check など、 どの呼び出し元から見てもここを見れば「JoinIR 層の責務と流れ」が分かるようにしておく。

変更があったら、Phase ドキュメントではなく このファイルを随時更新する 方針。

---

1. 不変条件（Invariants）

JoinIR ラインで守るべきルールを先に書いておくよ：

1. JoinIR 内部は JoinIR ValueId だけ

   • JoinIR lowering が発行する JoinInst の ValueId は、すべて alloc_value() で割り当てるローカル ID。
   • Rust/MIR 側の ValueId（builder.variable_map に入っている ID）は、JoinIR には直接持ち込まない。

2. host ↔ join の橋渡しは JoinInlineBoundary 系だけ

   • host から JoinIR への入力（ループ変数 / 条件専用変数）は
     • JoinInlineBoundary.join_inputs + host_inputs
     • JoinInlineBoundary.condition_bindings（ConditionBinding） だけで接続する。
   • 出力（キャリアの出口）は JoinInlineBoundary.exit_bindings に一本化する。

3. LoopHeader PHI を SSA の単一源泉にする

   • ループ変数とキャリアは LoopHeaderPhiBuilder/LoopHeaderPhiInfo でヘッダ PHI を作り、これを「現在値」の SSOT にする。
   • exit 用の PHI も組むが、変数再接続や expr_result 収集はヘッダ PHI を経由して行う（SSA‑undef 防止）。

4. 式としての戻り値とキャリア更新を分離する

   • 「ループが式として値を返す」ケース（例: let r = loop_min_while(...)）の出口は exit_phi_builder が扱う。
   • 「ループが状態更新だけする」ケース（例: trim の start/end）の出口は ExitLine（ExitMeta / ExitBinding / ExitLineReconnector） だけが扱う。

5. ループ制御 vs 条件式の分離

   • ループの「形」（Pattern1–4, LoopFeatures）は control-flow 専用の箱が担当。
   • 条件式（i < len && (ch == " " || ch == "\t") 等）は BoolExprLowerer / condition_to_joinir が担当し、 ループパターンは boolean ValueId だけを受け取る。

6. Fail‑Fast

   • JoinIR が対応していないループパターン / if パターンは、必ず [joinir/freeze] 等で明示的にエラーにする。
   • LoopBuilder 等へのサイレントフォールバックは禁止。

---

2. 主な箱と責務

2.1 Loop 構造・検出ライン

• LoopFeatures / LoopPatternKind / router

  • ファイル:
    • src/mir/loop_pattern_detection.rs
    • src/mir/builder/control_flow/joinir/patterns/router.rs
    • src/mir/builder/control_flow/joinir/patterns/ast_feature_extractor.rs
  • 責務:
    • AST から break/continue/if‑else PHI などの特徴を抽出（ast_feature_extractor）。
    • classify(&LoopFeatures) で Pattern1–4 に分類し、テーブル駆動の LOOP_PATTERNS でルーティング。
    • ルータ順序は P4(continue) → P3(if‑phi) → P1(simple) → P2(break) で固定（優先度フィールドはデバッグ用）。

• Pattern Lowerers (Pattern1–4)

  • ファイル例:
    • pattern1_minimal.rs（Simple while）
    • pattern2_with_break.rs（break 付き / Trim 昇格パスを含む）
    • pattern3_with_if_phi.rs（if‑phi キャリア）
    • pattern4_with_continue.rs（continue を Select で表現）
  • 責務:
    • LoopScopeShape / AST / LoopFeatures を入力として JoinIR の JoinModule を構築。
    • JoinFragmentMeta{ expr_result, exit_meta } を返し、出口情報を ExitLine に渡す。
    • host/MIR の ValueId は一切扱わない（JoinIR ローカルの ValueId のみ）。

• Scope / Env Builders

  • loop_scope_shape_builder.rs: ループ本体ローカルの収集、LoopScopeShape 統一生成。
  • condition_env_builder.rs: 条件専用変数の環境と ConditionBinding を一括構築。

• CommonPatternInitializer (Phase 33-22)

  • ファイル: src/mir/builder/control_flow/joinir/patterns/common_init.rs
  • 責務:
    • 全 Pattern 共通の初期化ロジック統一化（ループ変数抽出 + CarrierInfo 構築）。
    • 全パターンで boundary.loop_var_name を確実に設定し、SSA‑undef を防ぐ。

• JoinIRConversionPipeline (Phase 33-22)

  • ファイル: src/mir/builder/control_flow/joinir/patterns/conversion_pipeline.rs
  • 責務:
    • JoinIR → MIR 変換フロー統一化（JoinModule → MirModule → merge_joinir_mir_blocks）。
    • JoinIR/MIR の関数数・ブロック数をログ出力し、全パターンが同じ入口でマージする。

2.2 条件式ライン（式の箱）

• BoolExprLowerer / condition_to_joinir

  • ファイル:
    • src/mir/join_ir/lowering/bool_expr_lowerer.rs
    • src/mir/join_ir/lowering/condition_to_joinir.rs
  • 責務:
    • 通常の if/while 条件を MIR Compare/BinOp/UnaryOp へ lowering。
    • ループ lowerer 用の「AST 条件 → JoinIR Compute 命令列」を ConditionEnv とセットで構築。

• ConditionEnv/ConditionBinding + ConditionEnvBuilder

  • ファイル:
    • src/mir/join_ir/lowering/condition_env.rs
    • src/mir/builder/control_flow/joinir/patterns/condition_env_builder.rs
  • 責務:
    • 変数名→JoinIR ValueId の環境を組み立て、host↔join の橋渡しを ConditionBinding に明示する。
    • Pattern 2 では break 条件の全変数をスキャンし、JoinInlineBoundary.condition_bindings に渡す。

• LoopConditionScopeBox（Phase 170-D 実装済み）

  • ファイル: src/mir/loop_pattern_detection/loop_condition_scope.rs
  • 責務:
    • 条件式の各変数を LoopParam / OuterLocal / LoopBodyLocal に分類。
    • 関数パラメータ誤分類バグは condition_var_analyzer.rs の修正で解消済み（OuterLocal として扱う）。

• LoopBodyCarrierPromoter（Phase 171-C-2 実装済み）

  • ファイル: src/mir/loop_pattern_detection/loop_body_carrier_promoter.rs
  • 責務:
    • LoopBodyLocal を Trim パターンとして bool キャリアへ昇格（substring + equality 連鎖を検出）。
    • 昇格成功 → CarrierInfo に統合し Pattern 2/4 へ橋渡し。昇格失敗は Fail‑Fast。
    • Pattern 2 は安全な Trim なら実際に前処理（substring 生成 + 空白比較の初期化）を emit してから JoinIR lowering。
    • Pattern 4 は Trim 昇格が起きた場合はガード付きでエラーにし、未実装を明示（Fail‑Fast）。
  • 汎用性:
    • Phase 173 で _skip_whitespace（JsonParser）が Trim パターンで動作確認済み。
    • Phase 174 で _parse_string 最小化版（終端クォート検出）でも動作確認済み。
    • → 空白文字以外の文字比較ループにも対応可能（TrimLoopHelper の汎用性実証）。

• ContinueBranchNormalizer / LoopUpdateAnalyzer

  • ファイル:
    • src/mir/join_ir/lowering/continue_branch_normalizer.rs
    • src/mir/join_ir/lowering/loop_update_analyzer.rs
  • 責務:
    • else-continue を then-continue へ正規化し、Select ベースの continue を簡潔にする。
    • ループ本体で実際に更新されるキャリアだけを抽出（Pattern 4 で不要キャリアを排除）。

2.3 キャリア / Exit / Boundary ライン

• CarrierInfo / LoopUpdateAnalyzer

  • ファイル:
    • src/mir/join_ir/lowering/carrier_info.rs
    • src/mir/join_ir/lowering/loop_update_analyzer.rs
  • 責務:
    • ループで更新される変数（carrier）を検出し、UpdateExpr を保持。
    • Pattern 4 では実際に更新されるキャリアだけを残す。

• ExitMeta / JoinFragmentMeta

  • ファイル: carrier_info.rs
  • 責務:
    • JoinIR lowerer が出口の JoinIR ValueId を記録（expr_result とキャリアを明確に分離）。

• LoopHeader PHI Builder

  • ファイル:
    • src/mir/builder/control_flow/joinir/merge/loop_header_phi_info.rs
    • loop_header_phi_builder.rs
  • 責務:
    • ループ変数とキャリアの PHI をヘッダブロックに生成し、entry/latch の 2 入力で SSA を確立。
    • instruction_rewriter が latch 側を埋めた後に finalize して挿入する。

• JoinInlineBoundary

  • ファイル: src/mir/join_ir/lowering/inline_boundary.rs
  • 主フィールド:
    • join_inputs / host_inputs：ループパラメータの橋渡し
    • condition_bindings：条件専用変数の橋渡し（JoinIR ValueId を明示）
    • exit_bindings：キャリア出口の橋渡し（carrier 名を明示）
    • expr_result / loop_var_name：expr result / ヘッダ PHI 生成用のメタ情報
  • 責務:
    • 「host ↔ JoinIR」の境界情報の SSOT。各パターン lowerer がここに全て詰めてから merge する。

• BoundaryInjector

  • ファイル: src/mir/builder/joinir_inline_boundary_injector.rs
  • 責務:
    • join_inputs と condition_bindings を entry block に Copy で注入し、JoinIR ローカル ID と host ID を接続。

• ExitLine (ExitMetaCollector / ExitLineReconnector / ExitLineOrchestrator)

  • ファイル:
    • src/mir/builder/control_flow/joinir/merge/exit_line/mod.rs
    • exit_line/meta_collector.rs
    • exit_line/reconnector.rs
  • 責務:
    • ExitMeta から exit_bindings を構築（Collector）。
    • 変数再接続はヘッダ PHI の dst を使って builder.variable_map を更新（Reconnector）。
    • expr 用の PHI には一切触れない（carrier 専用ライン）。

• JoinInlineBoundaryBuilder（Phase 200-2 / Phase 201 完了）

  • ファイル: src/mir/join_ir/lowering/inline_boundary_builder.rs
  • 責務:
    • JoinInlineBoundary の構築を Builder パターンで統一化。
    • フィールド直書きの散乱を防ぎ、inputs/outputs/condition_bindings/exit_bindings/loop_var_name/expr_result の設定を fluent API で実施。
    • Phase 201 で Pattern1/2/3/4 全てに適用完了（境界情報組み立てを 1 箇所に集約）。

• JoinIRVerifier（Phase 200-3 追加）

  • ファイル: src/mir/builder/control_flow/joinir/merge/mod.rs（debug_assertions 専用関数）
  • 責務:
    • LoopHeader PHI / ExitLine 契約をデバッグビルドで検証する門番。
    • verify_loop_header_phis(): loop_var_name がある場合にヘッダ PHI が存在するか確認。
    • verify_exit_line(): exit_bindings が exit block に対応しているか確認。
    • verify_joinir_contracts(): merge_joinir_mir_blocks() の最後で全契約を一括チェック。
    • release ビルドでは完全に除去される（#[cfg(debug_assertions)]）。

2.4 expr result ライン（式としての戻り値）

• exit_phi_builder

  • ファイル: src/mir/builder/control_flow/joinir/merge/exit_phi_builder.rs
  • 責務:
    • JoinIR fragment が expr_result を持つときに exit ブロックへ PHI を生成。
    • carrier_inputs も受け取り exit ブロックに PHI を作るが、再接続の SSOT は LoopHeader PHI（ExitLine はヘッダ PHI を使用）。

• InstructionRewriter

  • ファイル: instruction_rewriter.rs
  • 責務:
    • continuation 関数（k_exit）をスキップし、Return → exit ブロック Jump に変換。
    • JoinFragmentMeta.expr_result と exit_bindings をヘッダ PHI 経由で収集し、exit_phi_inputs / carrier_inputs を復活させた（SSA‑undef 修正済み）。
    • tail call を Branch/Jump に書き換えつつ、LoopHeaderPhiInfo に latch 入力を記録する。

---

3. JoinIR → MIR 統合の全体フロー

1. Pattern router が AST/LoopFeatures から Pattern1–4 を選択し、各 lowerer が (JoinModule, JoinFragmentMeta) を生成。
2. JoinInlineBoundary が:
   • ループ入力（join_inputs/host_inputs）
   • 条件変数（condition_bindings）
   • キャリア出口（exit_bindings） を保持。
3. merge_joinir_mir_blocks が（マルチ関数対応）:
   • 全関数の BlockID を再割り当て（block_allocator）し、ValueId はパラメータを除外して収集。
   • Boundary の condition/exit Bindings の JoinIR ValueId も remap 対象に追加。
   • LoopHeader PHI を生成（loop_header_phi_builder）し、latch 側は instruction_rewriter が埋める。
   • instruction_rewriter で関数をマージしつつ Call→Jump に変換、k_exit 関数はスキップ。
   • BoundaryInjector で entry block に Copy を注入（join_inputs + condition_bindings）。
   • Header PHI を finalize → exit_phi_builder で expr_result/carrier の exit PHI を構築。
   • ExitLineOrchestrator がヘッダ PHI dst を使って variable_map を更新。
   • host の現在ブロックから JoinIR entry へ jump を張り、exit ブロックに切り替える。

この全体フローの詳細は src/mir/builder/control_flow/joinir/merge/mod.rs と phase-189-multi-function-mir-merge/README.md を参照。

---

4. selfhost / .hako JoinIR Frontend との関係

JoinIR は Rust 側だけでなく、将来的に .hako selfhost コンパイラ側でも生成・解析される予定だよ：

• .hako 側の JsonParser/分析箱は、Program JSON / MIR JSON v1 を読んで JoinIR/MIR を解析する。
• Rust 側 JoinIR ラインの設計変更（特に ValueId/ExitLine/Boundary 周り）は、 必ずこのファイルを更新してから .hako 側にも段階的に反映する方針。

「JoinIR の仕様」「箱の責務」「境界の契約」は、このファイルを SSOT として運用していく。

---

5. 関連ドキュメント

• docs/development/current/main/10-Now.md
  • 全体の「いまどこ」を短くまとめたダッシュボード。
• docs/private/roadmap2/phases/phase-180-joinir-unification-before-selfhost/README.md
  • JoinIR 統一フェーズ全体のロードマップと進捗。
• 各 Phase 詳細:
  • 185–188: Strict mode / LoopBuilder 削除 / Pattern1–4 基盤
  • 189–193: Multi-function merge / Select bridge / ExitLine 箱化
  • 171–172 / 33‑10/13: ConditionEnv, ConditionBinding, JoinFragmentMeta, ExitLineRefactor 等
• docs/development/current/main/loop_pattern_space.md
  • JoinIR ループパターン空間の整理メモ。
    どの軸（継続条件 / break / continue / PHI / 条件変数スコープ / 更新パターン）でパターンを分けるか、
    そして P1–P4 / Trim(P5) の位置づけと、今後追加候補のパターン一覧がまとまっている。