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

JoinIR Design Map（現役の地図）

Status: SSOT（navigation）
Scope: JoinIR の「Loop/If を JoinIR 化して MIR に統合する」導線（検出→shape guard→lower→merge→契約検証）
Related:

• SSOT: docs/development/current/main/joinir-architecture-overview.md
• SSOT: docs/development/current/main/loop_pattern_space.md
• SSOT: docs/development/current/main/joinir-boundary-builder-pattern.md
• SSOT: docs/development/current/main/design/loop-canonicalizer.md

このドキュメントは Phase ログではなく、「JoinIR を触る人が迷子にならず、どこを直すべきかが一発で分かる」ための設計図（地図）です。
詳細な経緯・作業ログは docs/development/current/main/phases/ と docs/development/current/main/investigations/ に分離します。

役割分担（joinir-architecture-overview との分離）

このファイルは「実装導線の地図」の SSOT です（navigation SSOT）。
意味論・契約・不変条件の本文（normative）は docs/development/current/main/joinir-architecture-overview.md を SSOT とします。

使い分け:

• 「JoinIR が何を保証し、何を Fail-Fast で落とすべきか」→ joinir-architecture-overview.md
• 「どのファイルを触るべきか」「入口はどこか」「追加手順は？」→ この joinir-design-map.md
• 「経緯/ログ/切り分け」→ docs/development/current/main/phases/ と docs/development/current/main/investigations/

---

1枚図: レイヤー（AST → JoinIR → MIR → Backend）

flowchart LR
  A[AST] -->|Frontend lowering| J1[JoinIR (Structured)]
  J1 -->|Normalize / Shape guard| J2[JoinIR (Normalized)]
  J2 -->|JoinIR → MIR bridge| M1[MIR Module]
  M1 -->|Merge into host function| M2[MIR (in builder)]
  M2 --> B[Backend\n(VM / LLVM / Cranelift)]

  subgraph Frontend
    A
    J1
  end

  subgraph JoinIR Core
    J2
  end

  subgraph MIR Builder
    M1
    M2
  end

読み方:

• 「Loop/If の形が認識されない」: Pattern 検出（Feature/Kind）と shape guard を見る
• 「JoinIR は生成できるが統合で壊れる」: Merge（ValueId/PHI/ExitLine/Boundary）と契約検証を見る
• 「なぜこのエラータグが出たか」: ErrorTags（SSOT）を起点に呼び出し元へ辿る

---

“箱”の責務マップ（担当境界）

領域	役割（何を決めるか）	主な入口/箱（SSOT寄り）	主な出力	Fail-Fast（典型）
Pattern検出	ループ形を分類し、どの lowerer に渡すか決める	src/mir/builder/control_flow/joinir/patterns/router.rs, src/mir/builder/control_flow/joinir/patterns/ast_feature_extractor.rs, src/mir/loop_pattern_detection/mod.rs	LoopPatternKind / Pattern 選択	「分類不能」→ 明示的に Err（サイレントな非JoinIR退避は禁止）
shape guard	「この shape なら lower/merge 契約が成立する」を保証する	src/mir/join_ir/normalized/shape_guard.rs, src/mir/builder/control_flow/joinir/patterns/*_validator.rs	shape OK / 詳細診断	shape 不一致を握りつぶさず Err
lowering	JoinIR（Structured/Normalized）を生成する	src/mir/join_ir/lowering/mod.rs, src/mir/builder/control_flow/joinir/patterns/pattern*_*.rs	JoinModule	未対応の構造は error_tags::freeze(...) 等で Err
merge	JoinIR→MIR 変換後、ホスト関数に統合する	src/mir/builder/control_flow/joinir/patterns/conversion_pipeline.rs, src/mir/builder/control_flow/joinir/merge/mod.rs	ホスト MIR のブロック/ValueId 更新	ValueId 競合、ExitLine 未接続、PHI 破綻を Err
ExitMeta	「出口でどの carrier をどの host slot に戻すか」のメタ	src/mir/join_ir/lowering/carrier_info.rs, src/mir/builder/control_flow/joinir/merge/exit_line/meta_collector.rs	ExitMeta / exit_bindings	carrier 不整合（不足/過剰）を Err
CarrierInit	carrier 初期化の SSOT（FromHost/Const/LoopLocal）	src/mir/builder/control_flow/joinir/merge/carrier_init_builder.rs, src/mir/join_ir/lowering/carrier_info.rs	初期値 ValueId	初期化経路の分岐が散らばらない（SSOT を使う）
ErrorTags	エラータグ整形の SSOT（検索性・一貫性）	src/mir/join_ir/lowering/error_tags.rs	文字列タグ	文字列ハードコードを避け、タグを一元化

注:

• Pattern 検出は「関数名 by-name 分岐」に依存しない（構造で決める）。必要なら dev/診断限定のガードに閉じ込める。
• shape guard は「OK なら後工程が前提にできる契約」を固定する場所で、曖昧な許容をしない。

---

入口（コード側のエントリポイント）

Loop（builder 側の導線）

• Router（builder 入口）: src/mir/builder/control_flow/joinir/routing.rs
  • MirBuilder::try_cf_loop_joinir(...)（JoinIR ルートへ入る最初の関数）
  • MirBuilder::cf_loop_joinir_impl(...)（pattern router → legacy binding の順）
• Pattern router（テーブル駆動）: src/mir/builder/control_flow/joinir/patterns/router.rs
• Feature extraction: src/mir/builder/control_flow/joinir/patterns/ast_feature_extractor.rs
• Pattern 実体（代表）:
  • src/mir/builder/control_flow/joinir/patterns/pattern1_minimal.rs
  • src/mir/builder/control_flow/joinir/patterns/pattern2_with_break.rs
  • src/mir/builder/control_flow/joinir/patterns/pattern3_with_if_phi.rs
  • src/mir/builder/control_flow/joinir/patterns/pattern4_with_continue.rs
  • src/mir/builder/control_flow/joinir/patterns/pattern5_infinite_early_exit.rs
• 変換パイプライン（JoinIR→MIR→Merge の統一導線）:
  • src/mir/builder/control_flow/joinir/patterns/conversion_pipeline.rs
• Merge（統合の本体）: src/mir/builder/control_flow/joinir/merge/mod.rs
  • ExitLine: src/mir/builder/control_flow/joinir/merge/exit_line/mod.rs
  • Merge の契約検証（debug）: src/mir/builder/control_flow/joinir/merge/contract_checks.rs

JoinIR（IR/正規化/ブリッジ）

• JoinIR 定義・入口: src/mir/join_ir/mod.rs
• Normalized / shape guard: src/mir/join_ir/normalized/shape_guard.rs
• JoinIR → MIR bridge: src/mir/join_ir_vm_bridge/mod.rs

共通（診断とタグ）

• Trace（JoinIR ルートの統一トレース）: src/mir/builder/control_flow/joinir/trace.rs
• Error tags（SSOT）: src/mir/join_ir/lowering/error_tags.rs
• Loop Canonicalizer（前処理 SSOT）: src/mir/loop_canonicalizer/mod.rs
• ConditionOnly Derived Slot（Phase 93）: src/mir/join_ir/lowering/common/condition_only_emitter.rs

---

不変条件（Fail-Fast）

JoinIR を触るときは、次を破ったら「即エラーで止める」前提で設計・実装する。

形状（shape）

• Pattern は「認識できる shape だけ」を通し、曖昧な許容をしない。
• 形状が合わないときは Ok(None) で静かに進めない（非JoinIRへの退避を作らない）。
  • 例外: 明確な “routing” で「別 JoinIR 経路」を選ぶのは可（同一層内での選択）。

ValueId / PHI / Boundary の世界

• JoinIR 内部（JoinValueSpace 等）と host MIR builder の ValueId を混ぜない。
• Boundary は JoinIR↔host の橋渡し契約:
  • join_inputs と host_inputs の対応が明示される
  • Exit 側は “carrier 名” をキーにして reconnection される（ExitMeta/exit_bindings）
• PHI は「誰が確保するか」を固定し、衝突を許さない（PHI dst の予約・再利用禁止）。

ExitLine 契約

• ExitLine は「出口へ集約する」ための契約であり、未接続の経路を残さない。
• carrier/slot の不足・余剰・不整合は error_tags::exit_line_contract(...) 等で即エラーにする。

Allocator SSOT（Phase 135）

• 原則: すべての ValueId 発行は単一の allocator（ConditionContext.alloc_value）を経由する
• 禁止事項: ConditionLoweringBox / ExprLowerer での内部カウンタ使用
• 理由: JoinIR params (ValueId(1000+)) と衝突し、merge 時に header PHI dst を上書きする
• 検出: --verify で "Value %N defined multiple times" エラー
• 修正例: Phase 135 P0 - ConditionLoweringBox が &mut ConditionContext を受け取り、alloc_value を必ず使用

Boundary Injection SSA（Phase 135）

• 原則: condition_bindings は alias を許すが、注入 Copy の dst は重複させない
• Fail-Fast: 異なる source が同一 dst に来る場合は即座にエラー
• 理由: MIR SSA を破壊し、VM/LLVM で未定義動作を引き起こす
• 検出: joinir_inline_boundary_injector.rs の重複排除ロジック
• 修正例: Phase 135 P0 - Boundary Copy deduplication by dst

Box 実装チェックリスト

Box を新規実装・変更した際は以下を必ず確認：

1. ✅ --verify で契約違反が検出されるか（SSA 破綻・ValueId 衝突）
2. ✅ smoke test で退行が出ないか（phase132/133/135 など）
3. ✅ allocator を bypass していないか（ConditionContext.alloc_value を使っているか）
4. ✅ boundary injection で dst 重複を防いでいるか

---

追加手順チェックリスト（新しいループ形を飲み込む最小手順）

「新しいループ形」を JoinIR で扱えるようにするときの最小手順。

1. Fixture を追加（再現可能に固定）
   • apps/tests/ または apps/smokes/ に最小の .hako を追加（対象形が一目で分かるもの）
2. Pattern/feature を追加（検出）
   • src/mir/builder/control_flow/joinir/patterns/ast_feature_extractor.rs（必要なら feature 抽出を拡張）
   • src/mir/loop_pattern_detection/（分類/補助解析が必要ならここに追加）
3. shape guard を追加（契約の固定）
   • 形状・前提条件を validator として分離し、失敗は Err にする
4. lower を追加（JoinIR を生成）
   • 既存 pattern のコピーではなく、「今回の shape が要求する最小構成」にする
   • エラーは src/mir/join_ir/lowering/error_tags.rs を使いタグを固定する
5. merge/ExitLine を接続（契約が満たされるように）
   • carrier/ExitMeta/Boundary が揃っているか確認する
6. Tests を追加（仕様固定）
   • unit: pattern/validator/merge の局所テスト
   • smoke: tools/smokes/v2/ の profile に軽いケースを追加（quick を重くしない）
7. Docs を更新（地図を更新）
   • docs/development/current/main/loop_pattern_space.md（パターン空間に追記が必要なら）
   • docs/development/current/main/joinir-architecture-overview.md（箱/契約が増えたなら）
   • 本ファイル（入口・責務マップの更新）