hakorune/docs/development/current/main/phases/phase-286/README.md

Phase 286: JoinIR Line Absorption（JoinIR→CorePlan/Frag 収束）

Status: In Progress (P0, P1, P2, P3, 286C-2 COMPLETE)

Goal

移行期間に残っている「2本の lowering」を、構造で 1 本に収束させる。

• Plan line（Pattern6/7）: CorePlan → Frag(compose) → emit_frag() が SSOT
• JoinIR line（Pattern1–5,9）: JoinIR → bridge → merge が SSOT

Phase 286 では JoinIR line を “第2の lowerer” として放置せず、Plan/Frag SSOT へ吸収する道筋を固定する。

Why（なぜ今）

• return のような「大きな出口語彙」は、責務が分散すると実装場所が揺れて事故りやすい
• 移行期間の弱点は「同じASTでも経路により意味論が割れる可能性がある」こと
• pattern を溶かしていく思想の最後の壁が “JoinIR line の残存” になりやすい

SSOT（Phase 286 で守る憲法）

• SSOT=extract（Phase 282）: 検出は extract の成功でのみ決める。pattern_kind は O(1) safety valve のみ。
• CFG/terminator SSOT（Phase 280/281）: Frag + compose::* + emit_frag() が唯一の terminator 生成点。
• Fail-Fast: close-but-unsupported を Ok(None) で黙殺しない（silent reroute 禁止）。

Responsibility Map（どこを触るか）

• JoinIR line の共通入口（現状）:
  • src/mir/builder/control_flow/joinir/patterns/conversion_pipeline.rs
  • src/mir/join_ir_vm_bridge/bridge.rs
  • src/mir/builder/control_flow/joinir/merge/mod.rs
• Plan/Frag SSOT（収束先）:
  • src/mir/builder/control_flow/plan/*
  • src/mir/builder/control_flow/edgecfg/api/compose.rs
  • src/mir/builder/control_flow/edgecfg/api/emit.rs

Scope（提案）

P0（docs-only）✅ COMPLETE (2025-12-25)

完了内容:

• SSOT ドキュメント作成: docs/development/current/main/design/joinir-plan-frag-ssot.md を作成
• 8章構成で固定:
  1. Scope / Non-goals - 対象範囲の明確化
  2. 用語（Terms） - JoinIR line, Plan, Frag, Boundary, ExitKind, Freeze point, SSOT の定義
  3. 責務（Responsibilities） - Planが決めること・決めないこと / Fragが保持すること・保持しないこと
  4. 禁止事項（Prohibitions） - Planでの実行・名前解決・最適化・ルール実装の禁止 等
  5. 凍結点（Freeze Points） - PlanFreeze / BoundaryFreeze / ValueIdAllocate / MergeComplete
  6. 不変条件（Invariants / Fail-Fast） - Plan段階(V1-V7) / Boundary段階(B1-B2, C1-C2) / Merge段階(M1-M4)
  7. 2本コンパイラ根治の合流点 - 共通パス・分岐点・差分許容場所/非許容場所
  8. デバッグ導線 - NYASH_CLI_VERBOSE, HAKO_JOINIR_DEBUG, NYASH_TRACE_VARMAP 等

重要な設計決定:

• JoinIR line を AST → MIR 全体ではなく、「(Pattern detection/Plan) → (Frag+Boundary) → (MIR merge) の限定されたパイプライン」として定義
• 禁止事項の「例外なし」表現を削除し、「診断専用の扱い（debugタグ付き・既定OFF）」という運用ルールに変更
• ValueId 100-999 固定範囲を「host ValueId と衝突しない領域」という原則に変更（具体数値は実装詳細として注記）

成果物:

• docs/development/current/main/design/joinir-plan-frag-ssot.md (新規)
• コード変更なし（docs-only）

P1 (contract_checks 導入 + 実バグ修正) ✅ COMPLETE (2025-12-25)

完了内容:

• contract_checks.rs に検証関数追加: verify_boundary_contract_at_creation()
  • B1検証: join_inputs が Param 領域にあること
  • C2検証: condition_bindings が Param 領域にあること
• merge/mod.rs に検証呼び出し追加: merge開始時にFail-Fast検証
• 実バグ3件修正: Pattern2/4/5 で alloc_local() を誤って使っていた箇所を alloc_param() に修正

成果物:

• src/mir/builder/control_flow/joinir/merge/contract_checks.rs (変更)
• src/mir/builder/control_flow/joinir/merge/mod.rs (変更)
• src/mir/join_ir/lowering/loop_with_break_minimal.rs (変更)
• src/mir/join_ir/lowering/loop_with_continue_minimal.rs (変更)
• src/mir/builder/control_flow/joinir/patterns/pattern5_infinite_early_exit.rs (変更)

発見された問題:

• 各 pattern の lowering で関数パラメータに alloc_local() を使っていた（本来は alloc_param()）
• これにより join_inputs に Local ValueId (1000+) が混入し、検証エラーになっていた

改善の示唆（Post-P1 Polish 実施済み）:

• API名の曖昧さが誤用を招いていたため、alloc_join_param() / alloc_join_local() の導入が検討されている
• エラーメッセージの「原因特定」強化として context パラメータの追加が検討されている

Post-P1 Polish 追加 (2025-12-25):

• 新API追加: JoinValueSpace::alloc_join_param() / alloc_join_local() （薄いラッパー）
• エラーメッセージ改善: verify_boundary_contract_at_creation() に context: &str パラメータ追加
• docs反映: SSOTドキュメントに脚注形式で数値記載、新API使用の明記

P2（PoC）✅ COMPLETE (2025-12-26)

完了内容:

• Pattern4 (Loop with Continue) を Plan/Frag SSOT に移行
  • DomainPlan::Pattern4Continue 追加
  • PlanNormalizer::normalize_pattern4_continue() 実装（phi_bindings によるAST抽出ベース）
  • Router integration（Plan line routing → legacy fallback）

成果物:

• apps/tests/phase286_pattern4_frag_poc.hako (最小fixture: single continue)
• tools/smokes/v2/profiles/integration/apps/phase286_pattern4_frag_poc.sh (integration smoke)
• src/mir/builder/control_flow/plan/mod.rs (Pattern4ContinuePlan struct追加)
• src/mir/builder/control_flow/joinir/patterns/extractors/pattern4.rs (extract_pattern4_plan追加)
• src/mir/builder/control_flow/joinir/patterns/router.rs (Plan routing追加)
• src/mir/builder/control_flow/plan/normalizer.rs (normalize_pattern4_continue + phi_bindings)

重要な設計決定:

• phi_bindings: lower_*_ast関数でPHI dstを優先参照（variable_mapの初期値ではなく）
• 2-step branching + header PHI merge: NO Select instruction（CoreEffectPlanにない）
• carrier passthrough: Add 0 不要、carrier_current をそのままPHI入力に渡す

検証結果:

• Integration test: phase286_pattern4_frag_poc.sh PASS (output: 6)
• Regression test: quick smoke 154 PASS, 0 FAILED

Pattern2 調査結果（別タスク化）:

• break経路の値再接続が複雑（after_bbにPHI必要）
• 詳細: pattern2-deferred.md

P2.1（PoC）✅ COMPLETE (2025-12-26)

完了内容:

• Pattern1 (SimpleWhile) を Plan/Frag SSOT に移行
  • DomainPlan::Pattern1SimpleWhile 追加
  • PlanNormalizer::normalize_pattern1_simple_while() 実装（phi_bindings によるPHI dst優先参照）
  • Router integration（Plan line routing → legacy fallback）

検証結果:

• Integration test: phase286_pattern1_frag_poc PASS (return: 3)
• Regression test: quick smoke 154 PASS, 0 FAILED

P2.2 (hygiene: extractor重複排除 + router小整理) ✅ COMPLETE (2025-12-26)

完了内容:

• extractor helper化: extract_loop_increment_plan を common_helpers.rs に統一
  • Pattern1/Pattern4 が呼ぶだけに変更（重複排除 ~25行）
• router helper化: lower_via_plan() を追加し Pattern6/7/4/1 で共用
  • 3行パターン（normalize→verify→lower）を1関数に集約（ボイラープレート削減 ~40行）

成果物:

• src/mir/builder/control_flow/joinir/patterns/extractors/common_helpers.rs (変更)
• src/mir/builder/control_flow/joinir/patterns/extractors/pattern1.rs (変更)
• src/mir/builder/control_flow/joinir/patterns/extractors/pattern4.rs (変更)
• src/mir/builder/control_flow/joinir/patterns/router.rs (変更)

検証結果:

• Regression test: quick smoke 154 PASS
• Pattern1 PoC: PASS, Pattern4 PoC: PASS

P3 (error context enrichment) ✅ COMPLETE (2025-12-25)

完了内容:

• P2: host_fn をエラーコンテキストに追加（関数名での特定を容易に）
• P3: join-side 情報（continuation数・boundaryサマリ）をエラーコンテキストに追加
  • [conts=X exits=Y conds=Z] 形式のサマリを追加
  • 固定キー名で解析容易に

成果物:

• src/mir/builder/control_flow/joinir/merge/mod.rs (変更)
• 最終エラーフォーマット: [merge_joinir_mir_blocks host=X join=Y [conts=A exits=B conds=C]]

286C-2 (instruction_rewriter.rs 箱化) ✅ COMPLETE (2025-12-25)

完了内容:

• instruction_rewriter.rs の箱化・意味論不変: 1400行ファイルに責務リストコメントを追加し、4つの箱モジュールを抽出
  • InstructionFilterBox: Skip判定ロジック（純粋関数）
    • should_skip_copy_overwriting_phi() - CopyがPHI dstを上書きするか判定
    • should_skip_function_name_const() - Const String（関数名）のスキップ判定
    • should_skip_boundary_input_const() - Boundary input Constのスキップ判定
  • ReturnConverterBox: Return→Jump変換ヘルパー
    • should_keep_return() - 非スキップ可能継続のReturn保持判定
    • remap_return_value() - Return値のremapヘルパー
  • TailCallDetectorBox: テイルコール検出ヘルパー
    • is_recursive_call() - 再帰呼び出し判定
    • is_loop_entry_call() - ループエントリ呼び出し判定
    • should_skip_param_binding() - パラメータ束縛スキップ判定
    • call_type_description() - 呼び出しタイプの説明文字列取得
  • ParameterBindingBox: パラメータ束縛ヘルパー
    • should_skip_phi_param() - PHI dstパラメータのスキップ判定
    • carrier_param_count() - キャリアパラメータ数取得
    • has_more_carrier_args() - キャリア引数残確認
    • carrier_arg_index() - キャリア引数インデックス計算

成果物:

• src/mir/builder/control_flow/joinir/merge/rewriter/instruction_filter_box.rs (新規)
• src/mir/builder/control_flow/joinir/merge/rewriter/return_converter_box.rs (新規)
• src/mir/builder/control_flow/joinir/merge/rewriter/tail_call_detector_box.rs (新規)
• src/mir/builder/control_flow/joinir/merge/rewriter/parameter_binding_box.rs (新規)
• src/mir/builder/control_flow/joinir/merge/instruction_rewriter.rs (変更: 責務リストコメント追加 + 箱使用)
• src/mir/builder/control_flow/joinir/merge/rewriter/mod.rs (変更: モジュール追加)

注意点:

• 意味論は完全不変（既存のinlineロジックを箱関数呼び出しに置換）
• ファイル行数は1454行に増加（コメント・import追加により）
• 核ロジックは main loop に密結合しているため、完全な分離にはさらなるリファクタリングが必要
• スモークテスト: 既存FAILなし（1件のemit失敗は本変更と無関係）

Acceptance（P0）

• 2本の lowering が “設計として” どこで 1 本に収束するかが明文化されている
• Phase 284（Return）/ Phase 285（GC）と矛盾しない