hakorune/src/mir/builder/control_flow/mod.rs

//! Control-flow entrypoints (if/loop/try/throw) centralized here.
//!
//! This module is being modularized in phases:
//! - Phase 1: Debug utilities (debug.rs) ✅
//! - Phase 2: Pattern lowerers (joinir/patterns/) ✅
//! - Phase 3: JoinIR routing (joinir/routing.rs) ✅
//! - Phase 4-19: Additional modularization (future)

use super::{Effect, EffectMask, MirInstruction, ValueId};
use crate::ast::ASTNode;

// Phase 1: Debug utilities
pub(in crate::mir::builder) mod debug;

// Phase 2: JoinIR integration (patterns)
pub(in crate::mir::builder) mod joinir;

impl super::MirBuilder {
    /// Control-flow: block
    pub(super) fn cf_block(&mut self, statements: Vec<ASTNode>) -> Result<ValueId, String> {
        // identical to build_block; kept here for future policy hooks
        self.build_block(statements)
    }

    /// Control-flow: if
    ///
    /// # Phase 124: JoinIR-Only (hako_check専用化完了)
    ///
    /// If statements are now always routed through the canonical lowering path
    /// (lower_if_form), which internally uses JoinIR-based PHI generation.
    ///
    /// Phase 123 の環境変数による分岐は削除済み。
    pub(super) fn cf_if(
        &mut self,
        condition: ASTNode,
        then_branch: ASTNode,
        else_branch: Option<ASTNode>,
    ) -> Result<ValueId, String> {
        // Phase 124: JoinIR-only path (環境変数分岐削除)
        // lower_if_form は JoinIR ベースの PHI 生成を使用
        self.lower_if_form(condition, then_branch, else_branch)
    }

    /// Control-flow: loop
    ///
    /// # Phase 49: JoinIR Frontend Mainline Integration
    ///
    /// This is the unified entry point for all loop lowering. Specific functions
    /// are routed through JoinIR Frontend instead of the traditional LoopBuilder path
    /// when enabled via dev flags (Phase 49) or Core policy (Phase 80):
    ///
    /// - Core ON (`joinir_core_enabled()`): print_tokens / ArrayExt.filter はまず JoinIR Frontend を試す
    /// - Dev フラグ（既存）:
    ///   - `HAKO_JOINIR_PRINT_TOKENS_MAIN=1`: JsonTokenizer.print_tokens/0
    ///   - `HAKO_JOINIR_ARRAY_FILTER_MAIN=1`: ArrayExtBox.filter/2
    ///
    /// Note: Arity does NOT include implicit `me` receiver.
    pub(super) fn cf_loop(
        &mut self,
        condition: ASTNode,
        body: Vec<ASTNode>,
    ) -> Result<ValueId, String> {
        // Phase 49/80: Try JoinIR Frontend route for mainline targets
        if let Some(result) = self.try_cf_loop_joinir(&condition, &body)? {
            return Ok(result);
        }

        if std::env::var("NYASH_LOOPFORM_DEBUG").is_ok() {
            eprintln!("[cf_loop] CALLED from somewhere");
            eprintln!("[cf_loop] Current stack (simulated): check build_statement vs build_expression_impl");
        }

        // Phase 186: LoopBuilder Hard Freeze - Legacy path disabled
        // Phase 187-2: LoopBuilder module removed - all loops must use JoinIR
        return Err(format!(
            "[joinir/freeze] Loop lowering failed: JoinIR does not support this pattern, and LoopBuilder has been removed.\n\
             Function: {}\n\
             Hint: This loop pattern is not supported. All loops must use JoinIR lowering.",
            self.current_function.as_ref().map(|f| f.signature.name.as_str()).unwrap_or("<unknown>")
        ));
    }

    /// Phase 49: Try JoinIR Frontend for mainline integration
    ///
    /// Returns `Ok(Some(value))` if the current function should use JoinIR Frontend,
    /// `Ok(None)` to fall through to the legacy LoopBuilder path.
    ///
    /// # Phase 49-4: Multi-target support
    ///
    /// Targets are enabled via separate dev flags:
    /// - `HAKO_JOINIR_PRINT_TOKENS_MAIN=1`: JsonTokenizer.print_tokens/0
    /// - `HAKO_JOINIR_ARRAY_FILTER_MAIN=1`: ArrayExtBox.filter/2
    ///
    /// Note: Arity in function names does NOT include implicit `me` receiver.
    /// - Instance method `print_tokens()` → `/0` (no explicit params)
    /// - Static method `filter(arr, pred)` → `/2` (two params)

    /// Phase 49-3.2: Merge JoinIR-generated MIR blocks into current_function
    ///
    /// # Phase 189: Multi-Function MIR Merge
    ///
    /// This merges JoinIR-generated blocks by:
    /// 1. Remapping all block IDs across ALL functions to avoid conflicts
    /// 2. Remapping all value IDs across ALL functions to avoid conflicts
    /// 3. Adding all blocks from all functions to current_function
    /// 4. Jumping from current_block to the entry block
    /// 5. Converting Return → Jump to exit block for all functions
    ///
    /// **Multi-Function Support** (Phase 189):
    /// - Pattern 1 (Simple While) generates 3 functions: entry + loop_step + k_exit
    /// - All functions are flattened into current_function with global ID remapping
    /// - Single exit block receives all Return instructions from all functions
    ///
    /// # Phase 188-Impl-3: JoinInlineBoundary Support
    ///
    /// When `boundary` is provided, injects Copy instructions at the entry block
    /// to connect host ValueIds to JoinIR local ValueIds:
    ///
    /// ```text
    /// entry_block:
    ///   // Injected by boundary
    ///   ValueId(100) = Copy ValueId(4)  // join_input → host_input
    ///   // Original JoinIR instructions follow...
    /// ```
    ///
    /// This enables clean separation: JoinIR uses local IDs (0,1,2...),
    /// host uses its own IDs, and Copy instructions bridge the gap.
    ///
    /// # Returns
    ///
    /// Returns `Ok(Some(exit_phi_id))` if the merged JoinIR functions have return values
    /// that were collected into an exit block PHI. さらに、`boundary` に
    /// host_outputs が指定されている場合は、exit PHI の結果をホスト側の
    /// SSA スロットへ再接続する（variable_map 内の ValueId を更新する）。
    fn merge_joinir_mir_blocks(
        &mut self,
        mir_module: &crate::mir::MirModule,
        boundary: Option<&crate::mir::join_ir::lowering::inline_boundary::JoinInlineBoundary>,
        debug: bool,
    ) -> Result<Option<ValueId>, String> {
        use crate::mir::{BasicBlock, BasicBlockId, MirInstruction, ValueId};
        use std::collections::HashMap;
        // Phase 189: Use new ID remapper Box
        use super::joinir_id_remapper::JoinIrIdRemapper;

        if debug {
            eprintln!(
                "[cf_loop/joinir] merge_joinir_mir_blocks called with {} functions",
                mir_module.functions.len()
            );
        }

        // Phase 189: Create ID remapper for ValueId/BlockId translation
        let mut remapper = JoinIrIdRemapper::new();

        // Phase 189: Map function names to their entry blocks (for Call→Jump conversion)
        let mut function_entry_map: HashMap<String, BasicBlockId> = HashMap::new();

        // 1. Allocate new block IDs for ALL functions (Phase 189)
        // DETERMINISM FIX: Sort functions by name to ensure consistent iteration order
        if debug {
            eprintln!("[cf_loop/joinir] Phase 189: Allocating block IDs for all functions");
        }
        let mut functions: Vec<_> = mir_module.functions.iter().collect();
        functions.sort_by_key(|(name, _)| name.as_str());
        for (func_name, func) in functions {
            if debug {
                eprintln!("[cf_loop/joinir]   Function: {}", func_name);
            }
            // DETERMINISM FIX: Sort blocks by ID to ensure consistent iteration order
            let mut blocks: Vec<_> = func.blocks.iter().collect();
            blocks.sort_by_key(|(id, _)| id.0);
            for (old_block_id, _) in blocks {
                let new_block_id = self.block_gen.next();
                // Use remapper to store composite key mapping
                remapper.set_block(func_name.clone(), *old_block_id, new_block_id);
                if debug {
                    eprintln!(
                        "[cf_loop/joinir]   Block remap: {}:{:?} → {:?}",
                        func_name, old_block_id, new_block_id
                    );
                }
            }
            // Map function entry blocks for Call→Jump conversion
            let entry_block_new = remapper.get_block(func_name, func.entry_block)
                .ok_or_else(|| format!("Entry block not found for {}", func_name))?;
            function_entry_map.insert(func_name.clone(), entry_block_new);
            if debug {
                eprintln!(
                    "[cf_loop/joinir]   Entry map: {} → {:?}",
                    func_name, entry_block_new
                );
            }
        }

        // 2. Create exit block for Return conversion (single for all functions)
        let exit_block_id = self.block_gen.next();
        if debug {
            eprintln!("[cf_loop/joinir]   Exit block: {:?}", exit_block_id);
        }

        // 3. Collect all ValueIds used across ALL functions (Phase 189)
        // Also build a map of ValueId → function name for Call→Jump conversion
        // Phase 188-Impl-3: Also collect function parameters for tail call conversion
        if debug {
            eprintln!("[cf_loop/joinir] Phase 189: Collecting value IDs from all functions");
        }
        let mut used_values: std::collections::BTreeSet<ValueId> =
            std::collections::BTreeSet::new();
        let mut value_to_func_name: HashMap<ValueId, String> = HashMap::new();
        let mut function_params: HashMap<String, Vec<ValueId>> = HashMap::new();

        for (func_name, func) in &mir_module.functions {
            // Phase 188-Impl-3: Collect function parameters for tail call conversion
            function_params.insert(func_name.clone(), func.params.clone());

            for block in func.blocks.values() {
                // Phase 189: Use remapper to collect values
                let block_values = remapper.collect_values_in_block(block);
                used_values.extend(block_values);

                // Phase 189: Track Const String instructions that define function names
                for inst in &block.instructions {
                    if let MirInstruction::Const { dst, value } = inst {
                        if let crate::mir::types::ConstValue::String(s) = value {
                            if function_entry_map.contains_key(s) {
                                value_to_func_name.insert(*dst, s.clone());
                                // Phase 189 FIX: Also add to used_values so it gets remapped!
                                // Without this, subsequent instructions referencing dst will fail
                                used_values.insert(*dst);
                                if debug {
                                    eprintln!(
                                        "[cf_loop/joinir]   Found function name constant: {:?} = '{}'",
                                        dst, s
                                    );
                                }
                            }
                        }
                    }
                }
            }
            // Also collect parameter ValueIds
            for param in &func.params {
                used_values.insert(*param);
            }
        }

        // 4. Allocate new ValueIds for all collected values
        for old_value in used_values {
            let new_value = self.next_value_id();
            remapper.set_value(old_value, new_value);
            if debug {
                eprintln!(
                    "[cf_loop/joinir]   Value remap: {:?} → {:?}",
                    old_value, new_value
                );
            }
        }

        // 5. Merge ALL functions (Phase 189: iterate over all, not just first)
        // DETERMINISM FIX: Sort functions by name to ensure consistent iteration order
        if debug {
            eprintln!("[cf_loop/joinir] Phase 189: Merging {} functions", mir_module.functions.len());
        }
        // Phase 189: Iterate over both names and functions (need name for composite keys)
        let mut functions_merge: Vec<_> = mir_module.functions.iter().collect();
        functions_merge.sort_by_key(|(name, _)| name.as_str());

        // Phase 189 FIX: Build set of boundary join_inputs to skip their Const initializers
        // When BoundaryInjector provides values via Copy, entry function shouldn't also set them via Const
        let boundary_input_set: std::collections::HashSet<ValueId> = boundary
            .map(|b| b.join_inputs.iter().copied().collect())
            .unwrap_or_default();
        let entry_func_name = functions_merge.first().map(|(name, _)| name.as_str());

        // Phase 189-Fix: Collect return values from JoinIR functions for exit PHI
        // Each Return → Jump conversion records (from_block, return_value) here
        let mut exit_phi_inputs: Vec<(BasicBlockId, ValueId)> = Vec::new();

        for (func_name, func) in functions_merge {
            if debug {
                eprintln!(
                    "[cf_loop/joinir]   Merging function '{}' with {} blocks, entry={:?}",
                    func_name,
                    func.blocks.len(),
                    func.entry_block
                );
            }

            // Build a local block map for this function (for remap_instruction compatibility)
            let mut local_block_map: HashMap<BasicBlockId, BasicBlockId> = HashMap::new();
            for old_block_id in func.blocks.keys() {
                let new_block_id = remapper.get_block(func_name, *old_block_id)
                    .ok_or_else(|| format!("Block {:?} not found for {}", old_block_id, func_name))?;
                local_block_map.insert(*old_block_id, new_block_id);
            }

            // Clone and remap all blocks from this function
            // DETERMINISM FIX: Sort blocks by ID to ensure consistent iteration order
            let mut blocks_merge: Vec<_> = func.blocks.iter().collect();
            blocks_merge.sort_by_key(|(id, _)| id.0);
            for (old_block_id, old_block) in blocks_merge {
                // Use remapper to get correct mapping for this function's block
                let new_block_id = remapper.get_block(func_name, *old_block_id)
                    .ok_or_else(|| format!("Block {:?} not found for {}", old_block_id, func_name))?;
                let mut new_block = BasicBlock::new(new_block_id);

                // Remap instructions (Phase 189: Convert inter-function Calls to control flow)
                let mut found_tail_call = false;
                let mut tail_call_target: Option<(BasicBlockId, Vec<ValueId>)> = None;

                // DEBUG: Print block being processed
                if debug {
                    eprintln!("[cf_loop/joinir] === Processing block {:?} (from func '{}') ===", old_block_id, func_name);
                    eprintln!("[cf_loop/joinir]   Original block has {} instructions:", old_block.instructions.len());
                    for (idx, inst) in old_block.instructions.iter().enumerate() {
                        eprintln!("[cf_loop/joinir]     [{}] {:?}", idx, inst);
                    }
                    eprintln!("[cf_loop/joinir]   Original block terminator: {:?}", old_block.terminator);
                }

                // Phase 189 FIX: Check if this is entry function's entry block (for boundary input skipping)
                let is_entry_func_entry_block = entry_func_name == Some(func_name.as_str())
                    && *old_block_id == func.entry_block;

                // First pass: Process all instructions, identify tail calls
                for inst in &old_block.instructions {
                    // Phase 189: Skip Const String instructions that define function names
                    if let MirInstruction::Const { dst, value } = inst {
                        if let crate::mir::types::ConstValue::String(_) = value {
                            if value_to_func_name.contains_key(dst) {
                                if debug {
                                    eprintln!("[cf_loop/joinir]   Skipping function name const: {:?}", inst);
                                }
                                continue; // Skip this instruction
                            }
                        }
                        // Phase 189 FIX: Skip Const instructions in entry function's entry block
                        // that initialize boundary inputs. BoundaryInjector provides these values via Copy.
                        if is_entry_func_entry_block && boundary_input_set.contains(dst) {
                            if debug {
                                eprintln!("[cf_loop/joinir]   Skipping boundary input const (replaced by BoundaryInjector Copy): {:?}", inst);
                            }
                            continue; // Skip - BoundaryInjector will provide the value
                        }
                    }

                    // Phase 189: Detect tail calls and save parameters
                    if let MirInstruction::Call { func, args, .. } = inst {
                        if let Some(func_name) = value_to_func_name.get(func) {
                            if let Some(&target_block) = function_entry_map.get(func_name) {
                                // This is a tail call - save info and skip the Call instruction itself
                                let remapped_args: Vec<ValueId> = args
                                    .iter()
                                    .map(|&v| remapper.get_value(v).unwrap_or(v))
                                    .collect();
                                tail_call_target = Some((target_block, remapped_args));
                                found_tail_call = true;

                                if debug {
                                    eprintln!(
                                        "[cf_loop/joinir]   Detected tail call to '{}' (args={:?}), will convert to Jump",
                                        func_name, args
                                    );
                                }
                                continue; // Skip the Call instruction itself
                            }
                        }
                    }

                    // Process regular instructions - Phase 189: Use remapper.remap_instruction() + manual block remapping
                    let remapped = remapper.remap_instruction(inst);

                    // Phase 189 FIX: Manual block remapping for Branch/Phi (JoinIrIdRemapper doesn't know func_name)
                    let remapped_with_blocks = match remapped {
                        MirInstruction::Branch { condition, then_bb, else_bb } => {
                            MirInstruction::Branch {
                                condition,
                                then_bb: local_block_map.get(&then_bb).copied().unwrap_or(then_bb),
                                else_bb: local_block_map.get(&else_bb).copied().unwrap_or(else_bb),
                            }
                        }
                        MirInstruction::Phi { dst, inputs, type_hint: None } => {
                            MirInstruction::Phi {
                                dst,
                                inputs: inputs.iter().map(|(bb, val)| {
                                    (local_block_map.get(bb).copied().unwrap_or(*bb), *val)
                                }).collect(),
                                type_hint: None,
                            }
                        }
                        other => other,
                    };

                    if debug {
                        match inst {
                            MirInstruction::BoxCall { .. } => {
                                eprintln!("[cf_loop/joinir]   Adding BoxCall to block {:?}: {:?}", new_block_id, inst);
                            }
                            _ => {}
                        }
                    }

                    new_block.instructions.push(remapped_with_blocks);
                }

                // DEBUG: Print what was added to the block after first pass
                if debug {
                    eprintln!("[cf_loop/joinir]   After first pass, new_block has {} instructions", new_block.instructions.len());
                    for (idx, inst) in new_block.instructions.iter().enumerate() {
                        eprintln!("[cf_loop/joinir]     [{}] {:?}", idx, inst);
                    }
                }

                // Second pass: Insert parameter bindings for tail calls
                // Phase 188-Impl-3: Use actual parameter ValueIds from target function
                if let Some((target_block, args)) = tail_call_target {
                    if debug {
                        eprintln!(
                            "[cf_loop/joinir]   Inserting param bindings for tail call to {:?}",
                            target_block
                        );
                    }

                    // Find the target function name from the target_block
                    // We need to reverse-lookup the function name from the entry block
                    let mut target_func_name: Option<String> = None;
                    for (fname, &entry_block) in &function_entry_map {
                        if entry_block == target_block {
                            target_func_name = Some(fname.clone());
                            break;
                        }
                    }

                    if let Some(target_func_name) = target_func_name {
                        if let Some(target_params) = function_params.get(&target_func_name) {
                            // Insert Copy instructions for parameter binding
                            for (i, arg_val_remapped) in args.iter().enumerate() {
                                if i < target_params.len() {
                                    let param_val_original = target_params[i];
                                    if let Some(param_val_remapped) = remapper.get_value(param_val_original) {
                                        new_block.instructions.push(MirInstruction::Copy {
                                            dst: param_val_remapped,
                                            src: *arg_val_remapped,
                                        });

                                        if debug {
                                            eprintln!(
                                                "[cf_loop/joinir]     Param binding: arg {:?} → param {:?}",
                                                arg_val_remapped, param_val_remapped
                                            );
                                        }
                                    }
                                }
                            }
                        }
                    }

                    // Set terminator to Jump
                    new_block.terminator = Some(MirInstruction::Jump {
                        target: target_block,
                    });

                    // DEBUG: Print final state after adding parameter bindings
                    if debug {
                        eprintln!("[cf_loop/joinir]   After adding param bindings, new_block has {} instructions", new_block.instructions.len());
                        for (idx, inst) in new_block.instructions.iter().enumerate() {
                            eprintln!("[cf_loop/joinir]     [{}] {:?}", idx, inst);
                        }
                    }
                }
                new_block.instruction_spans = old_block.instruction_spans.clone();

                if debug {
                    eprintln!("[cf_loop/joinir]   Span sync: new_block.instructions.len()={}, old_block.instruction_spans.len()={}, new_block.instruction_spans.len()={}",
                        new_block.instructions.len(),
                        old_block.instruction_spans.len(),
                        new_block.instruction_spans.len()
                    );
                }

                // Remap terminator (convert Return → Jump to exit) if not already set by tail call
                if !found_tail_call {
                    if let Some(ref term) = old_block.terminator {
                        let remapped_term = match term {
                            MirInstruction::Return { value } => {
                                // Convert Return to Jump to exit block
                                // All functions return to same exit block (Phase 189)
                                // Phase 189-Fix: Add Copy instruction to pass return value to exit PHI
                                if let Some(ret_val) = value {
                                    let remapped_val = remapper.get_value(*ret_val).unwrap_or(*ret_val);
                                    if debug {
                                        eprintln!(
                                            "[cf_loop/joinir]   Return({:?}) → Jump to exit",
                                            remapped_val
                                        );
                                    }
                                    // Collect (from_block, return_value) for exit PHI generation
                                    exit_phi_inputs.push((new_block_id, remapped_val));
                                }
                                MirInstruction::Jump {
                                    target: exit_block_id,
                                }
                            }
                            MirInstruction::Jump { target } => {
                                // Phase 189 FIX: Remap block ID for Jump
                                MirInstruction::Jump {
                                    target: local_block_map.get(target).copied().unwrap_or(*target),
                                }
                            }
                            MirInstruction::Branch { condition, then_bb, else_bb } => {
                                // Phase 189 FIX: Remap block IDs AND condition ValueId for Branch
                                MirInstruction::Branch {
                                    condition: remapper.remap_value(*condition),
                                    then_bb: local_block_map.get(then_bb).copied().unwrap_or(*then_bb),
                                    else_bb: local_block_map.get(else_bb).copied().unwrap_or(*else_bb),
                                }
                            }
                            _ => remapper.remap_instruction(term),
                        };
                        new_block.terminator = Some(remapped_term);
                    }
                }

                // Phase 189 FIX: Ensure instruction_spans matches instructions length
                // The original spans may not cover all instructions after remapping/adding
                // (PHI instructions, tail call parameter bindings, etc.)
                let inst_count = new_block.instructions.len();
                let span_count = new_block.instruction_spans.len();
                if inst_count > span_count {
                    // Use a default span for the extra instructions
                    let default_span = new_block.instruction_spans.last()
                        .copied()
                        .unwrap_or_else(crate::ast::Span::unknown);
                    new_block.instruction_spans.resize(inst_count, default_span);
                } else if inst_count < span_count {
                    // Truncate spans to match instructions
                    new_block.instruction_spans.truncate(inst_count);
                }

                // Add block to current function
                if let Some(ref mut current_func) = self.current_function {
                    current_func.add_block(new_block);
                }
            }
        }

        // Phase 188-Impl-3: Inject Copy instructions for boundary inputs using BoundaryInjector
        if let Some(boundary) = boundary {
            use super::joinir_inline_boundary_injector::BoundaryInjector;

            // Get entry function's entry block (first function by convention)
            let (entry_func_name, entry_func) = mir_module
                .functions
                .iter()
                .next()
                .ok_or("JoinIR module has no functions")?;
            let entry_block_remapped = remapper.get_block(entry_func_name, entry_func.entry_block)
                .ok_or_else(|| format!("Entry block not found for {}", entry_func_name))?;

            // Create HashMap from remapper for BoundaryInjector (temporary adapter)
            let mut value_map_for_injector = HashMap::new();
            for join_in in &boundary.join_inputs {
                if let Some(remapped) = remapper.get_value(*join_in) {
                    value_map_for_injector.insert(*join_in, remapped);
                }
            }

            // Use BoundaryInjector to inject Copy instructions
            if let Some(ref mut current_func) = self.current_function {
                BoundaryInjector::inject_boundary_copies(
                    current_func,
                    entry_block_remapped,
                    boundary,
                    &value_map_for_injector,
                    debug,
                )?;
            }
        }

        // 6. Create exit block with PHI for return values from JoinIR functions
        // Phase 189-Fix: Generate exit PHI if there are multiple return values
        let exit_phi_result_id = if let Some(ref mut func) = self.current_function {
            let mut exit_block = BasicBlock::new(exit_block_id);

            // Phase 189-Fix: If we collected return values, create a PHI in exit block
            // This merges all return values from JoinIR functions into a single value
            let phi_result = if !exit_phi_inputs.is_empty() {
                // Allocate a new ValueId for the PHI result
                let phi_dst = self.value_gen.next();
                exit_block.instructions.push(MirInstruction::Phi {
                    dst: phi_dst,
                    inputs: exit_phi_inputs.clone(),
                    type_hint: None,
                });
                exit_block.instruction_spans.push(crate::ast::Span::unknown());
                if debug {
                    eprintln!(
                        "[cf_loop/joinir]   Exit block PHI: {:?} = phi {:?}",
                        phi_dst, exit_phi_inputs
                    );
                }
                Some(phi_dst)
            } else {
                None
            };

            func.add_block(exit_block);
            if debug {
                eprintln!("[cf_loop/joinir]   Created exit block: {:?}", exit_block_id);
            }
            phi_result
        } else {
            None
        };

        // Phase 190: Use explicit LoopExitBinding to reconnect exit PHI to variable_map
        // Each binding explicitly names the carrier variable and maps exit PHI to it.
        if let Some(phi_result) = exit_phi_result_id {
            if let Some(ref boundary) = boundary {
                // Phase 190: Use exit_bindings for explicit carrier naming
                // This eliminates ambiguity about which variable is being updated
                for binding in &boundary.exit_bindings {
                    // Find the variable in variable_map that matches the binding's host_slot
                    for (var_name, vid) in self.variable_map.iter_mut() {
                        if *vid == binding.host_slot {
                            *vid = phi_result;
                            if debug {
                                eprintln!(
                                    "[cf_loop/joinir] Phase 190: Reconnected exit PHI {:?} to variable_map['{}'] (carrier: {})",
                                    phi_result, var_name, binding.carrier_name
                                );
                            }
                            // Validate carrier name matches
                            if var_name != &binding.carrier_name && debug {
                                eprintln!(
                                    "[cf_loop/joinir] WARNING: Carrier name mismatch: expected '{}', found '{}'",
                                    binding.carrier_name, var_name
                                );
                            }
                        }
                    }
                }

                // Phase 190: Backward compatibility - also check deprecated host_outputs
                #[allow(deprecated)]
                if !boundary.host_outputs.is_empty() && debug {
                    eprintln!(
                        "[cf_loop/joinir] WARNING: Using deprecated host_outputs. Migrate to exit_bindings."
                    );
                }
            }
        }

        // 7. Jump from current block to entry function's entry block
        // Entry function is first function by convention
        let (entry_func_name, entry_func) = mir_module
            .functions
            .iter()
            .next()
            .ok_or("JoinIR module has no functions")?;
        // Use remapper to get entry block mapping
        let entry_block = remapper.get_block(entry_func_name, entry_func.entry_block)
            .ok_or_else(|| format!("Entry block not found for {}", entry_func_name))?;
        if debug {
            eprintln!("[cf_loop/joinir]   Entry function name: {}", entry_func_name);
            eprintln!("[cf_loop/joinir]   Entry function's entry_block (JoinIR local): {:?}", entry_func.entry_block);
            eprintln!("[cf_loop/joinir]   Entry block (remapped): {:?}", entry_block);
            eprintln!("[cf_loop/joinir]   Current block before emit_jump: {:?}", self.current_block);
            eprintln!("[cf_loop/joinir]   Jumping to entry block: {:?}", entry_block);
        }
        crate::mir::builder::emission::branch::emit_jump(self, entry_block)?;
        if debug {
            eprintln!("[cf_loop/joinir]   After emit_jump, current_block: {:?}", self.current_block);
        }

        // 8. Switch to exit block for subsequent code
        self.start_new_block(exit_block_id)?;

        if debug {
            eprintln!(
                "[cf_loop/joinir] Phase 189: Merge complete: {} functions merged, continuing from {:?}",
                mir_module.functions.len(),
                exit_block_id
            );
            // DEBUG: Check bb0's terminator after merge
            if let Some(ref func) = self.current_function {
                if let Some(bb0) = func.get_block(BasicBlockId(0)) {
                    eprintln!("[cf_loop/joinir]   bb0 terminator after merge: {:?}", bb0.terminator);
                }
                // DEBUG: Check bb9's PHI after merge (PHI merge block)
                if let Some(bb9) = func.get_block(BasicBlockId(9)) {
                    let phi_count = bb9.instructions.iter().filter(|i| matches!(i, MirInstruction::Phi { .. })).count();
                    eprintln!("[cf_loop/joinir]   bb9 after merge: {} instructions, {} PHI", bb9.instructions.len(), phi_count);
                    for (idx, inst) in bb9.instructions.iter().take(3).enumerate() {
                        eprintln!("[cf_loop/joinir]     bb9[{}]: {:?}", idx, inst);
                    }
                }
            }
        }

        Ok(exit_phi_result_id)
    }

    // Phase 189: collect_values_in_block/collect_values_in_instruction removed
    // These functions are now provided by JoinIrIdRemapper::collect_values_in_block()

    // Phase 189: remap_joinir_instruction/remap_instruction removed
    // These functions are now provided by JoinIrIdRemapper::remap_instruction()

    /// Control-flow: try/catch/finally
    pub(super) fn cf_try_catch(
        &mut self,
        try_body: Vec<ASTNode>,
        catch_clauses: Vec<crate::ast::CatchClause>,
        finally_body: Option<Vec<ASTNode>>,
    ) -> Result<ValueId, String> {
        if std::env::var("NYASH_BUILDER_DISABLE_TRYCATCH")
            .ok()
            .as_deref()
            == Some("1")
        {
            let try_ast = ASTNode::Program {
                statements: try_body,
                span: crate::ast::Span::unknown(),
            };
            let result = self.build_expression(try_ast)?;
            return Ok(result);
        }

        let try_block = self.block_gen.next();
        let catch_block = self.block_gen.next();
        let finally_block = if finally_body.is_some() {
            Some(self.block_gen.next())
        } else {
            None
        };
        let exit_block = self.block_gen.next();

        // Snapshot deferred-return state
        let saved_defer_active = self.return_defer_active;
        let saved_defer_slot = self.return_defer_slot;
        let saved_defer_target = self.return_defer_target;
        let saved_deferred_flag = self.return_deferred_emitted;
        let saved_in_cleanup = self.in_cleanup_block;
        let saved_allow_ret = self.cleanup_allow_return;
        let saved_allow_throw = self.cleanup_allow_throw;

        let ret_slot = self.next_value_id();
        self.return_defer_active = true;
        self.return_defer_slot = Some(ret_slot);
        self.return_deferred_emitted = false;
        self.return_defer_target = Some(finally_block.unwrap_or(exit_block));

        if let Some(catch_clause) = catch_clauses.first() {
            if std::env::var("NYASH_DEBUG_TRYCATCH").ok().as_deref() == Some("1") {
                eprintln!(
                    "[BUILDER] Emitting catch handler for {:?}",
                    catch_clause.exception_type
                );
            }
            let exception_value = self.next_value_id();
            self.emit_instruction(MirInstruction::Catch {
                exception_type: catch_clause.exception_type.clone(),
                exception_value,
                handler_bb: catch_block,
            })?;
        }

        // Enter try block
        crate::mir::builder::emission::branch::emit_jump(self, try_block)?;
        self.start_new_block(try_block)?;
        let try_ast = ASTNode::Program {
            statements: try_body,
            span: crate::ast::Span::unknown(),
        };
        let _try_result = self.build_expression(try_ast)?;
        if !self.is_current_block_terminated() {
            let next_target = finally_block.unwrap_or(exit_block);
            crate::mir::builder::emission::branch::emit_jump(self, next_target)?;
        }

        // Catch block
        self.start_new_block(catch_block)?;
        if std::env::var("NYASH_DEBUG_TRYCATCH").ok().as_deref() == Some("1") {
            eprintln!("[BUILDER] Enter catch block {:?}", catch_block);
        }
        if let Some(catch_clause) = catch_clauses.first() {
            let catch_ast = ASTNode::Program {
                statements: catch_clause.body.clone(),
                span: crate::ast::Span::unknown(),
            };
            self.build_expression(catch_ast)?;
        }
        if !self.is_current_block_terminated() {
            let next_target = finally_block.unwrap_or(exit_block);
            crate::mir::builder::emission::branch::emit_jump(self, next_target)?;
        }

        // Finally
        let mut cleanup_terminated = false;
        if let (Some(finally_block_id), Some(finally_statements)) = (finally_block, finally_body) {
            self.start_new_block(finally_block_id)?;
            self.in_cleanup_block = true;
            self.cleanup_allow_return = crate::config::env::cleanup_allow_return();
            self.cleanup_allow_throw = crate::config::env::cleanup_allow_throw();
            self.return_defer_active = false; // do not defer inside cleanup

            let finally_ast = ASTNode::Program {
                statements: finally_statements,
                span: crate::ast::Span::unknown(),
            };
            self.build_expression(finally_ast)?;
            cleanup_terminated = self.is_current_block_terminated();
            if !cleanup_terminated {
                crate::mir::builder::emission::branch::emit_jump(self, exit_block)?;
            }
            self.in_cleanup_block = false;
        }

        // Exit block
        self.start_new_block(exit_block)?;
        let result = if self.return_deferred_emitted && !cleanup_terminated {
            self.emit_instruction(MirInstruction::Return {
                value: Some(ret_slot),
            })?;
            crate::mir::builder::emission::constant::emit_void(self)
        } else {
            crate::mir::builder::emission::constant::emit_void(self)
        };

        // Restore context
        self.return_defer_active = saved_defer_active;
        self.return_defer_slot = saved_defer_slot;
        self.return_defer_target = saved_defer_target;
        self.return_deferred_emitted = saved_deferred_flag;
        self.in_cleanup_block = saved_in_cleanup;
        self.cleanup_allow_return = saved_allow_ret;
        self.cleanup_allow_throw = saved_allow_throw;

        Ok(result)
    }

    /// Phase 188-Impl-2: Extract loop variable name from condition
    ///
    /// For `i < 3`, extracts `i`.
    /// For `arr.length() > 0`, extracts `arr`.
    ///
    /// This is a minimal implementation that handles simple comparison patterns.
    fn extract_loop_variable_from_condition(&self, condition: &ASTNode) -> Result<String, String> {
        use crate::ast::BinaryOperator;

        match condition {
            ASTNode::BinaryOp {
                operator, left, ..
            } if matches!(
                operator,
                BinaryOperator::Less
                    | BinaryOperator::Greater
                    | BinaryOperator::LessEqual
                    | BinaryOperator::GreaterEqual
            ) =>
            {
                // Binary comparison: extract variable from left side
                match &**left {
                    ASTNode::Variable { name, .. } => Ok(name.clone()),
                    _ => Err(format!(
                        "[cf_loop/pattern1] Cannot extract loop variable from condition: {:?}",
                        condition
                    )),
                }
            }
            _ => Err(format!(
                "[cf_loop/pattern1] Unsupported loop condition pattern: {:?}",
                condition
            )),
        }
    }

    /// Control-flow: throw
    pub(super) fn cf_throw(&mut self, expression: ASTNode) -> Result<ValueId, String> {
        if self.in_cleanup_block && !self.cleanup_allow_throw {
            return Err("throw is not allowed inside cleanup block (enable NYASH_CLEANUP_ALLOW_THROW=1 to permit)".to_string());
        }
        if std::env::var("NYASH_BUILDER_DISABLE_THROW").ok().as_deref() == Some("1") {
            let v = self.build_expression(expression)?;
            self.emit_instruction(MirInstruction::ExternCall {
                dst: None,
                iface_name: "env.debug".to_string(),
                method_name: "trace".to_string(),
                args: vec![v],
                effects: EffectMask::PURE.add(Effect::Debug),
            })?;
            return Ok(v);
        }
        let exception_value = self.build_expression(expression)?;
        self.emit_instruction(MirInstruction::Throw {
            exception: exception_value,
            effects: EffectMask::PANIC,
        })?;
        Ok(exception_value)
    }
}