unluac 1.2.0

//! 这个文件承载 structured body lowering 里的分支恢复细节。
//!
//! `body.rs` 里既有 region 主循环，也有各种 branch/value-merge/loop-control 的细分
//! 恢复逻辑。把后者单独拆出来，是为了让“主流程如何行走 block”与“某个分支具体怎么
//! 降”分开维护；后面继续打磨 branch merge 或 continue/break 语义时，不需要在一个
//! 超大文件里来回跳转。
//!
//! 当一个 header 同时拥有 SC (ShortCircuit) 值合流候选和 BranchValueMerge
//! 候选时，SC 只处理一个 result_reg 的 phi，而 BVM 认领了其余 phi。SC 系列
//! 快捷路径（conditional_reassign / statement_value_merge / value_merge）消费
//! 整个分支结构后，BVM 的 phi 就会因无人物化而丢失。为此：
//! - value_merge / conditional_reassign 路径在检测到 BVM 共存时退让给普通分支，
//!   让 BVM 通过 target_overrides 处理自身 phi，SC phi 则在 merge block 恢复。
//! - statement_value_merge 路径在 SC 表达式生成后，以 SC 树结构为骨架为 BVM
//!   phi 构建 Decision 表达式。
//!
//! 例子：SC 覆盖 r4 → `x and (y and 2 or 3) or 6`，BVM 覆盖 r3 →
//! 普通分支路径产出 `if x then ... end` 中的条件赋值。

use super::*;

use crate::cfg::DefId;

impl<'a, 'b> StructuredBodyLowerer<'a, 'b> {
    pub(super) fn lower_branch(
        &mut self,
        block: BlockRef,
        stop: Option<BlockRef>,
        stmts: &mut Vec<HirStmt>,
        target_overrides: &BTreeMap<TempId, HirLValue>,
    ) -> Option<Option<BlockRef>> {
        if let Some(next) =
            self.try_lower_conditional_reassign_branch(block, stop, stmts, target_overrides)
        {
            return Some(next);
        }

        if let Some(next) =
            self.try_lower_statement_value_merge_branch(block, stop, stmts, target_overrides)
        {
            return Some(next);
        }

        if let Some(next) = self.try_lower_value_merge_branch(block, stop, stmts, target_overrides)
        {
            return Some(next);
        }

        if let Some(next) =
            self.try_lower_loop_continue_branch(block, stop, stmts, target_overrides)
        {
            return Some(next);
        }

        if let Some(next) = self.try_lower_loop_break_branch(block, stop, stmts, target_overrides) {
            return Some(next);
        }

        if let Some(escape_target) = self.cross_structure_escape_target(block) {
            return self.lower_cross_structure_escape_branch(
                block,
                escape_target,
                stop,
                stmts,
                target_overrides,
            );
        }

        stmts.extend(self.lower_block_prefix(block, true, target_overrides)?);

        let short_plan = self.try_build_short_circuit_plan(block, stop)?;
        let plan = short_plan.or_else(|| self.build_plain_branch_plan(block))?;

        for header in &plan.consumed_headers {
            self.visited.insert(*header);
        }

        let branch_stop =
            self.branch_stop_for_region(block, plan.then_entry, plan.else_entry, plan.merge, stop);
        let branch_target_overrides = self
            .branch_value_merges_by_header
            .contains_key(&block)
            .then(|| {
                self.branch_value_target_overrides(block, target_overrides)
            });
        if let Some(branch_target_overrides) = branch_target_overrides.as_ref() {
            stmts.extend(self.branch_value_preserved_entry_stmts(block, branch_target_overrides));
        }
        let then_target_overrides = branch_target_overrides
            .as_ref()
            .map(|branch_target_overrides| {
                self.branch_value_then_target_overrides(block, branch_target_overrides)
            })
            .unwrap_or_else(|| target_overrides.clone());
        let else_target_overrides = branch_target_overrides
            .as_ref()
            .map(|branch_target_overrides| {
                self.branch_value_else_target_overrides(block, branch_target_overrides)
            })
            .unwrap_or_else(|| target_overrides.clone());
        let then_block = self.lower_region(plan.then_entry, branch_stop, &then_target_overrides)?;
        let else_block = match plan.else_entry {
            Some(else_entry) => {
                Some(self.lower_region(else_entry, branch_stop, &else_target_overrides)?)
            }
            // IfThen 无 else 臂时，不再为 merge block 上的 phi 生成隐式 else 赋值。
            // 这些 phi 会在 merge block 的 lower_block_prefix 中由 idom 兜底统一
            // 物化（idom 对于 IfThen 就是 header，值与隐式 else 赋值完全一致），
            // 避免双重物化导致冗余临时变量、多余引用和无意义 else 分支。
            None => None,
        };
        stmts.push(branch_stmt({
            let mut cond = plan.cond;
            rewrite_expr_temps(&mut cond, &temp_expr_overrides(target_overrides));
            cond
        }, then_block, else_block));
        self.install_stop_boundary_value_merge_override(block, branch_stop, target_overrides);
        for header in &plan.consumed_headers {
            let branch_value_overrides = if *header == block {
                branch_target_overrides
                    .clone()
                    .unwrap_or_else(|| target_overrides.clone())
            } else {
                self.branch_value_target_overrides(*header, target_overrides)
            };
            self.install_branch_value_merge_overrides(*header, &branch_value_overrides);
        }

        // 当普通分支路径处理了一个 header，而该 header 同时拥有 SC 值合流候选
        // 时（SC 由于 BVM 共存而退让到了这里），需要把 header 加入
        // merge_allowed_blocks。这样 merge block 的 lower_phi_materialization
        // 才能在 SC 恢复时识别 header 内的 temp 为"安全可引用"，正确恢复
        // SC phi 的值表达式。
        if let Some(sc) = value_merge_candidate_by_header(self.lowering, block)
            && let ShortCircuitExit::ValueMerge(sc_merge) = sc.exit
            && branch_stop == Some(sc_merge)
        {
            self.merge_allowed_blocks
                .entry(sc_merge)
                .or_default()
                .insert(block);
        }

        match branch_stop {
            Some(next) if next == self.lowering.cfg.exit_block => Some(None),
            Some(next) => Some(Some(next)),
            None => Some(None),
        }
    }

    fn try_lower_conditional_reassign_branch(
        &mut self,
        block: BlockRef,
        stop: Option<BlockRef>,
        stmts: &mut Vec<HirStmt>,
        target_overrides: &BTreeMap<TempId, HirLValue>,
    ) -> Option<Option<BlockRef>> {
        let short = value_merge_candidate_by_header(self.lowering, block)?;
        let ShortCircuitExit::ValueMerge(merge) = short.exit else {
            return None;
        };
        // merge 恰好就是当前 region 的 stop 时，后面不会再真正进入 merge block。
        // 这类情况下如果继续走“先跳过分支、再靠 merge 点物化 phi”的快捷路径，
        // loop-carried/branch-carried 的写回就会直接丢掉。这里宁可退回普通 branch
        // lowering，让两臂里的赋值在当前结构里显式发生，也不把边界语义悄悄吞掉。
        if Some(merge) == stop {
            return None;
        }

        // 与 try_lower_value_merge_branch 同理：SC 系列快捷路径只处理一个
        // result_reg，BVM 认领的其他 phi 会因分支结构被消费而孤立。
        if let Some(bvm) = self.branch_value_merges_by_header.get(&block)
            && bvm
                .values
                .iter()
                .any(|v| Some(v.phi_id) != short.result_phi_id)
        {
            return None;
        }

        let plan = build_conditional_reassign_plan(self.lowering, block)?;

        if let Some(stop) = stop
            && stop != merge
            && short.blocks.contains(&stop)
        {
            return None;
        }

        // try_lower_statement_value_merge_branch 处的同类守卫：条件重赋值同样把
        // phi temp 直接内联进语句，跳过了 apply_loop_rewrites，当 entry_defs
        // 被 loop state 接管时，写入会被遗漏。
        if value_merge_defs_are_overridden(self.lowering, short, target_overrides) {
            return None;
        }

        stmts.extend(self.lower_block_prefix(block, true, target_overrides)?);
        self.visited.insert(block);
        self.visited.extend(value_merge_skipped_blocks(short));
        self.overrides.suppress_phi(plan.phi_id);

        stmts.push(assign_stmt(
            vec![HirLValue::Temp(plan.target_temp)],
            vec![plan.init_value],
        ));
        stmts.push(branch_stmt(
            plan.cond,
            HirBlock {
                stmts: vec![assign_stmt(
                    vec![HirLValue::Temp(plan.target_temp)],
                    vec![plan.assigned_value],
                )],
            },
            None,
        ));

        Some(Some(plan.merge))
    }

    fn try_lower_statement_value_merge_branch(
        &mut self,
        block: BlockRef,
        stop: Option<BlockRef>,
        stmts: &mut Vec<HirStmt>,
        target_overrides: &BTreeMap<TempId, HirLValue>,
    ) -> Option<Option<BlockRef>> {
        let short = value_merge_candidate_by_header(self.lowering, block)?;
        let ShortCircuitExit::ValueMerge(merge) = short.exit else {
            return None;
        };
        if Some(merge) == stop {
            return None;
        }
        let allowed_blocks = BTreeSet::from([block]);
        if recover_short_value_merge_expr_with_allowed_blocks(self.lowering, short, &allowed_blocks)
            .is_some()
        {
            return None;
        }

        if let Some(stop) = stop
            && stop != merge
            && short.blocks.contains(&stop)
        {
            return None;
        }

        // 短路值合流的 lower_value_merge_leaf 不会传递 target_overrides 给
        // lower_block_prefix，导致循环 state plan 或外层 BVM 的写入重定向被跳过。
        // 如果值合流涉及的 def（含 entry_defs 和 leaf 的 value_incomings）中有任何
        // 一个被 target_overrides 接管，应退让给普通分支降级。
        if value_merge_defs_are_overridden(self.lowering, short, target_overrides) {
            return None;
        }

        let target_temp = *self
            .lowering
            .bindings
            .phi_temps
            .get(short.result_phi_id?.index())?;
        let mut short_stmts = self.lower_block_prefix(block, true, target_overrides)?;
        short_stmts.extend(
            self.lower_value_merge_node(short, short.entry, target_temp, true)?
                .stmts,
        );

        self.visited.insert(block);
        self.visited.extend(value_merge_skipped_blocks(short));
        self.overrides.suppress_phi(short.result_phi_id?);
        stmts.extend(short_stmts);

        // SC 值合流只处理了 result_phi 对应的一个寄存器。如果同一 header 下还有
        // BranchValueMerge 认领的其他 phi，它们的分支结构已被 SC 消费——正常
        // 分支路径不会再运行。这里利用 SC 的树结构，为每个孤立的 BVM phi 构建
        // 平行的 Decision 表达式，避免这些 phi 因无人物化而丢失。
        if let Some(bvm) = self.branch_value_merges_by_header.get(&block) {
            for value in &bvm.values {
                if Some(value.phi_id) == short.result_phi_id {
                    continue;
                }
                if let Some(decision_expr) =
                    self.build_secondary_value_merge_decision(short, value.reg)
                {
                    let bvm_temp = self.lowering.bindings.phi_temps[value.phi_id.index()];
                    stmts.push(assign_stmt(
                        vec![HirLValue::Temp(bvm_temp)],
                        vec![decision_expr],
                    ));
                    self.overrides.suppress_phi(value.phi_id);
                }
            }
        }

        Some(Some(merge))
    }

    fn try_lower_value_merge_branch(
        &mut self,
        block: BlockRef,
        stop: Option<BlockRef>,
        stmts: &mut Vec<HirStmt>,
        target_overrides: &BTreeMap<TempId, HirLValue>,
    ) -> Option<Option<BlockRef>> {
        let short = value_merge_candidate_by_header(self.lowering, block)?;
        let ShortCircuitExit::ValueMerge(merge) = short.exit else {
            return None;
        };
        // 注意：merge == stop 时仍然允许值合流消费分支结构块。调用方的循环会在
        // current == stop 时自然 break，不会再尝试进入 merge block。
        // merge block 的 block_prefix（含值合流 phi 物化）由外层调用方显式处理，
        // 例如 numeric-for body 会在 region 返回后单独 lower continue_block 的 prefix。

        // SC 值合流只处理一个 result_reg。如果同一 header 下 BranchValueMerge
        // 还认领了其他 phi，SC 消费分支结构后那些 phi 就无人物化。此时退让给
        // 普通分支路径：BVM 通过 target_overrides 处理自己的 phi，SC 的 phi 则
        // 在 merge block 的 lower_phi_materialization 中恢复。
        if let Some(bvm) = self.branch_value_merges_by_header.get(&block)
            && bvm
                .values
                .iter()
                .any(|v| Some(v.phi_id) != short.result_phi_id)
        {
            return None;
        }

        let allowed_blocks = BTreeSet::from([block]);
        let recovery = recover_short_value_merge_expr_recovery_with_allowed_blocks(
            self.lowering,
            short,
            &allowed_blocks,
        )?;

        if let Some(stop) = stop
            && stop != merge
            && short.blocks.contains(&stop)
        {
            return None;
        }

        if recovery.consumes_header_subject() {
            self.overrides
                .suppress_instrs(consumed_value_merge_subject_instrs(self.lowering, block));
        }
        stmts.extend(self.lower_block_prefix(block, true, target_overrides)?);
        self.visited.insert(block);
        self.visited.extend(value_merge_skipped_blocks(short));
        self.merge_allowed_blocks
            .entry(merge)
            .or_default()
            .insert(block);
        Some(Some(merge))
    }

    fn try_lower_loop_break_branch(
        &mut self,
        block: BlockRef,
        _stop: Option<BlockRef>,
        stmts: &mut Vec<HirStmt>,
        target_overrides: &BTreeMap<TempId, HirLValue>,
    ) -> Option<Option<BlockRef>> {
        // 多出口 loop 里最常见、也最值得先吃掉的形状是“主体继续跑，另一臂经 cleanup pad
        // 直接离开循环”。这里不把这类 pad 留给 fallback，而是在 HIR 里直接恢复成 break，
        // 这样后面的 AST/readability 就不用再对着 `close + jump` 反推源码意图。
        let loop_context = self.active_loops.last()?.clone();
        let candidate = *self.branch_by_header.get(&block)?;
        let break_exit = candidate.merge.filter(|merge| {
            loop_context.break_exits.contains_key(merge)
                || *merge == loop_context.post_loop
                || Some(*merge) == loop_context.downstream_post_loop
        })?;
        let break_block = if break_exit == loop_context.post_loop
            || Some(break_exit) == loop_context.downstream_post_loop
        {
            // 当 break 路径上存在中间块（如 `found = {i,j}; break`），需要提取
            // 中间块的指令前缀到 break 之前，避免丢失赋值等副作用。
            // 仅处理 else_entry 直跳 break_exit 的单块线性情形。
            let pad_stmts = if let Some(else_entry) =
                candidate.else_entry.filter(|e| *e != break_exit)
            {
                let is_direct_jump = self.block_terminator(else_entry).is_some_and(|(_, instr)| {
                    if let LowInstr::Jump(jump) = instr {
                        let target = self.lowering.cfg.instr_to_block[jump.target.index()];
                        target == break_exit
                            || Some(target) == loop_context.downstream_post_loop
                    } else {
                        false
                    }
                });
                if is_direct_jump {
                    self.lower_block_prefix(else_entry, false, target_overrides)
                        .inspect(|_| {
                            self.visited.insert(else_entry);
                        })
                } else {
                    None
                }
            } else {
                None
            };
            let mut stmts = pad_stmts.unwrap_or_default();
            stmts.push(HirStmt::Break);
            HirBlock { stmts }
        } else {
            loop_context.break_exits[&break_exit].clone()
        };
        // break 臂之外的那一臂，很多时候只是继续执行当前 loop body，最后再回到
        // continue target。如果这里一口气把它降到 break pad 的出口，repeat/for 的
        // loop tail 就会被一起吞进去，随后整片 region 只能 fallback。这里优先把
        // 非 break 臂截到当前 loop 的 continue target；只有确实没有这条稳定回路时，
        // 才继续沿用 break exit 作为边界。
        let body_stop = loop_context
            .continue_target
            .filter(|target| {
                *target != break_exit && self.lowering.cfg.can_reach(candidate.then_entry, *target)
            })
            .or(Some(break_exit));
        let then_block = self.lower_region(candidate.then_entry, body_stop, target_overrides)?;
        let mut cond = self.lower_candidate_cond(block, candidate)?;
        rewrite_expr_temps(&mut cond, &temp_expr_overrides(target_overrides));

        stmts.extend(self.lower_block_prefix(block, true, target_overrides)?);
        self.visited.insert(block);
        if break_exit != loop_context.post_loop
            && Some(break_exit) != loop_context.downstream_post_loop
        {
            self.visited.insert(break_exit);
        }

        if body_stop == Some(break_exit)
            && break_block.stmts.last() == Some(&HirStmt::Break)
            && then_block.stmts == break_block.stmts[..break_block.stmts.len() - 1]
        {
            stmts.extend(then_block.stmts);
            stmts.push(branch_stmt(
                cond.negate(),
                HirBlock {
                    stmts: vec![HirStmt::Break],
                },
                None,
            ));
            return Some(None);
        }

        if then_block.stmts.is_empty() {
            stmts.push(branch_stmt(cond.negate(), break_block, None));
        } else {
            stmts.push(branch_stmt(cond, then_block, Some(break_block)));
        }

        match body_stop {
            Some(next) if next == break_exit => Some(None),
            Some(next) if next == self.lowering.cfg.exit_block => Some(None),
            Some(next) => Some(Some(next)),
            None => Some(None),
        }
    }

    fn cross_structure_escape_target(&self, block: BlockRef) -> Option<BlockRef> {
        let loop_context = self.active_loops.last()?;
        let candidate = self.branch_by_header.get(&block).copied()?;
        let merge = candidate.merge?;
        let continue_target = loop_context.continue_target?;

        // 这类形状常见于 `if cond then goto after_outer_loop end`：
        // 分支的一臂仍然沿当前 loop 继续跑，另一臂却直接跳到当前 loop 之外更远的 merge。
        // 如果这里继续把它硬恢复成普通 `if-then`，缺席的那一臂会被误当成
        // “自然回到当前 region 的 stop”，最终把跨层 `goto` 偷偷降成错误的 loop fallthrough。
        //
        // 对这种跨层退出，当前 structured HIR 没有等价的 `break/continue` 语义可承载；
        // 与其在局部生成半真半假的结构，不如让整片 proto 退回显式 label/goto 形态，
        // 由更保守但语义直观的 fallback 接手。
        if candidate.else_entry.is_some()
            || merge == loop_context.post_loop
            || Some(merge) == loop_context.downstream_post_loop
            || loop_context.break_exits.contains_key(&merge)
        {
            return None;
        }

        let loop_candidate = self.loop_by_header.get(&loop_context.header).copied()?;
        if loop_candidate.blocks.contains(&merge) {
            return None;
        }

        (candidate.then_entry == continue_target
            || self
                .lowering
                .cfg
                .can_reach(candidate.then_entry, continue_target))
        .then_some(merge)
    }

    fn lower_cross_structure_escape_branch(
        &mut self,
        block: BlockRef,
        escape_target: BlockRef,
        _stop: Option<BlockRef>,
        stmts: &mut Vec<HirStmt>,
        target_overrides: &BTreeMap<TempId, HirLValue>,
    ) -> Option<Option<BlockRef>> {
        let loop_context = self.active_loops.last()?.clone();
        let continue_target = loop_context.continue_target?;
        let candidate = *self.branch_by_header.get(&block)?;

        let mut keep_cond = self.lower_candidate_cond(block, candidate)?;
        rewrite_expr_temps(&mut keep_cond, &temp_expr_overrides(target_overrides));

        stmts.extend(self.lower_block_prefix(block, true, target_overrides)?);
        self.visited.insert(block);

        let escape_block = self.lower_escape_edge(block, escape_target, target_overrides)?;
        let continue_block = if candidate.then_entry == continue_target {
            HirBlock::default()
        } else {
            self.lower_region(
                candidate.then_entry,
                Some(continue_target),
                target_overrides,
            )?
        };
        let continue_else = (!continue_block.stmts.is_empty()).then_some(continue_block);
        stmts.push(branch_stmt(
            keep_cond.negate(),
            escape_block,
            continue_else,
        ));

        Some(Some(continue_target))
    }

    fn try_lower_loop_continue_branch(
        &mut self,
        block: BlockRef,
        stop: Option<BlockRef>,
        stmts: &mut Vec<HirStmt>,
        target_overrides: &BTreeMap<TempId, HirLValue>,
    ) -> Option<Option<BlockRef>> {
        // continue-like requirement 既可能来自未来 dialect 的显式 continue，也可能只是
        // 当前循环内部一条“提前回到 continue target”的控制边。这里只在它确实是当前
        // active loop 的本地语义时才吸收；否则宁可保持 fallback，也不把跨结构跳转误判成 continue。
        let loop_context = self.active_loops.last()?.clone();
        let continue_target = loop_context.continue_target?;
        let branch_points_to_continue =
            self.branch_by_header.get(&block).is_some_and(|candidate| {
                candidate.then_entry == continue_target
                    || candidate.else_entry == Some(continue_target)
                    || candidate.merge == Some(continue_target)
            });
        if !loop_context.continue_sources.contains(&block) && !branch_points_to_continue {
            return None;
        }

        let candidate = *self.branch_by_header.get(&block)?;
        if candidate.then_entry != continue_target
            && candidate.else_entry != Some(continue_target)
            && candidate.merge != Some(continue_target)
        {
            return None;
        }
        if self
            .non_continue_entry_for_continue_candidate(candidate, continue_target)
            .is_some_and(|entry| self.entry_is_direct_loop_break(entry, &loop_context))
        {
            return None;
        }
        let mut continue_cond = self.lower_branch_cond_for_target(block, continue_target)?;
        rewrite_expr_temps(&mut continue_cond, &temp_expr_overrides(target_overrides));
        let prefer_natural_fallthrough = self.prefer_natural_fallthrough_over_continue(
            block,
            candidate,
            continue_target,
            &loop_context,
        );
        let then_target_overrides =
            self.branch_entry_target_overrides(block, Some(candidate.then_entry), target_overrides);

        stmts.extend(self.lower_block_prefix(block, true, target_overrides)?);
        self.visited.insert(block);

        if let Some(break_exit) = candidate
            .merge
            .filter(|merge| loop_context.break_exits.contains_key(merge))
        {
            self.visited.insert(break_exit);
            stmts.push(branch_stmt(
                continue_cond.negate(),
                loop_context.break_exits[&break_exit].clone(),
                None,
            ));
            return Some(None);
        }

        let continue_block = HirBlock {
            stmts: vec![HirStmt::Continue],
        };
        if let Some(else_entry) = candidate.else_entry {
            let non_continue_entry = if candidate.then_entry == continue_target {
                else_entry
            } else {
                candidate.then_entry
            };
            if let Some(break_block) = loop_context.break_exits.get(&non_continue_entry) {
                self.visited.insert(non_continue_entry);
                // 当前 branch 本身如果没有“主动提前跳到 continue target”的证据，
                // 那它更像 loop tail 上的“否则 break”判定：继续这一臂只是自然回到
                // 下一轮，不应该硬提升成显式 `continue`。否则像 Lua 5.1 这种没有
                // `continue` / `goto` 的 target dialect 会被我们平白制造出无法落地的语义。
                if prefer_natural_fallthrough {
                    stmts.push(branch_stmt(
                        continue_cond.negate(),
                        break_block.clone(),
                        None,
                    ));
                    return Some(None);
                }
                let stmt = if candidate.then_entry == continue_target {
                    branch_stmt(continue_cond, continue_block, Some(break_block.clone()))
                } else {
                    branch_stmt(
                        continue_cond.negate(),
                        break_block.clone(),
                        Some(continue_block),
                    )
                };
                stmts.push(stmt);
                return Some(None);
            }

            if prefer_natural_fallthrough {
                let non_continue_target_overrides = self.branch_entry_target_overrides(
                    block,
                    Some(non_continue_entry),
                    target_overrides,
                );
                let non_continue_block = self.lower_region(
                    non_continue_entry,
                    Some(continue_target),
                    &non_continue_target_overrides,
                )?;
                stmts.push(branch_stmt(
                    continue_cond.negate(),
                    non_continue_block,
                    None,
                ));
                return Some(Some(continue_target));
            }

            let branch_stop = self.branch_stop_for_region(
                block,
                candidate.then_entry,
                candidate.else_entry,
                candidate.merge,
                stop,
            );
            let non_continue_target_overrides = self.branch_entry_target_overrides(
                block,
                Some(non_continue_entry),
                target_overrides,
            );
            let non_continue_block = self.lower_region(
                non_continue_entry,
                branch_stop,
                &non_continue_target_overrides,
            )?;
            let stmt = if candidate.then_entry == continue_target {
                branch_stmt(continue_cond, continue_block, Some(non_continue_block))
            } else {
                branch_stmt(
                    continue_cond.negate(),
                    non_continue_block,
                    Some(continue_block),
                )
            };
            stmts.push(stmt);
            return match branch_stop {
                Some(next) if next == self.lowering.cfg.exit_block => Some(None),
                Some(next) => Some(Some(next)),
                None => Some(None),
            };
        }

        if candidate.then_entry == continue_target {
            // `if cond then continue end` 这类分支在 CFG 里会表现成“显式 continue 臂 +
            // 隐式 merge 臂”。这里把 merge 臂显式降成 else block，避免 loop body 因为
            // “只有 then、没有 else” 被迫整片 fallback。
            let non_continue_entry = candidate.merge?;
            if self.prefer_natural_fallthrough_over_continue(
                block,
                candidate,
                continue_target,
                &loop_context,
            ) {
                let non_continue_block =
                    self.lower_region(non_continue_entry, stop, target_overrides)?;
                stmts.push(branch_stmt(
                    continue_cond.negate(),
                    non_continue_block,
                    None,
                ));
                return Some(None);
            }
            let non_continue_block =
                self.lower_region(non_continue_entry, stop, target_overrides)?;
            stmts.push(branch_stmt(
                continue_cond,
                continue_block,
                Some(non_continue_block),
            ));
            return Some(None);
        }

        if candidate.merge == Some(continue_target) {
            // `if cond then body end` 这类 loop-tail guard 在 CFG 里会表现成
            // “显式一臂 + 隐式 merge”，而 merge 正好就是当前 loop 的 continue target。
            // 这种形状本质上是“条件满足时执行 body，否则自然落回 loop latch”，
            // 并不需要显式 `continue`。如果这里仍然强行提升成 `if ... then continue else ... end`，
            // Lua 5.1 这类没有 `continue` / `goto` 的 dialect 就会被我们凭空制造出
            // 无法落地的语义。
            // 这里虽然 merge 臂本身只是自然落回 continue target，但 header 上若已经有
            // branch-value merge，就仍然需要把“执行 body 的那一臂”接回共享状态槽位。
            // 否则 arm 内新算出来的 carried 值只会停留在 branch-local temp 上，等不到
            // continue target 就已经丢掉了写回。
            let non_continue_block = self.lower_region(
                candidate.then_entry,
                Some(continue_target),
                &then_target_overrides,
            )?;
            stmts.push(branch_stmt(
                continue_cond.negate(),
                non_continue_block,
                None,
            ));
            return Some(Some(continue_target));
        }

        let merge = candidate.merge.or(stop)?;
        stmts.push(branch_stmt(continue_cond, continue_block, None));
        if merge == self.lowering.cfg.exit_block {
            Some(None)
        } else {
            Some(Some(merge))
        }
    }

    fn prefer_natural_fallthrough_over_continue(
        &self,
        block: BlockRef,
        candidate: &BranchCandidate,
        continue_target: BlockRef,
        loop_context: &ActiveLoopContext,
    ) -> bool {
        if candidate.merge == Some(continue_target) {
            return false;
        }
        let Some(non_continue_entry) =
            self.non_continue_entry_for_continue_candidate(candidate, continue_target)
        else {
            return false;
        };
        // 当 structure 层的 goto 分析没有把该 block 标记为 continue source 时，
        // 说明这条指向 continue_target 的边完全可以被结构化 branch 自然吸收
        // （比如 `if cond then body end` 的隐式落回到循环头），不需要提升为显式
        // continue。只有 goto 分析确认了 unstructured continue-like 的 block 才
        // 需要后续的 terminal-exit / break-funnel 判定。
        if !loop_context.continue_sources.contains(&block) {
            return true;
        }
        // 只有当非 continue 臂本身就是 terminal exit，且从 CFG 上根本到不了当前
        // continue target 时，才能确定它是“提前结束本轮/本函数”的 guard 分支。
        // 像 repeat 里的 break funnel 虽然最终也可能不回到 continue target，但它本身
        // 仍然是一个需要继续展开的控制块，不能在这里过早压平成 guard-return。
        if matches!(
            self.block_terminator(non_continue_entry),
            Some((_instr_ref, LowInstr::Return(_) | LowInstr::TailCall(_)))
        ) && !self
            .lowering
            .cfg
            .can_reach(non_continue_entry, continue_target)
        {
            return true;
        }

        self.entry_is_break_funnel_to_continue(
            non_continue_entry,
            continue_target,
            loop_context,
            &mut BTreeSet::new(),
        )
    }

    fn non_continue_entry_for_continue_candidate(
        &self,
        candidate: &BranchCandidate,
        continue_target: BlockRef,
    ) -> Option<BlockRef> {
        if candidate.then_entry == continue_target {
            candidate.else_entry.or(candidate.merge)
        } else if candidate.else_entry == Some(continue_target) {
            Some(candidate.then_entry)
        } else {
            None
        }
    }

    fn entry_is_break_funnel_to_continue(
        &self,
        entry: BlockRef,
        continue_target: BlockRef,
        loop_context: &ActiveLoopContext,
        visited: &mut BTreeSet<BlockRef>,
    ) -> bool {
        if !visited.insert(entry) {
            return false;
        }
        if self.entry_is_direct_loop_break(entry, loop_context) {
            return true;
        }

        let Some(candidate) = self.branch_by_header.get(&entry).copied() else {
            return false;
        };
        let Some(non_continue_entry) =
            self.non_continue_entry_for_continue_candidate(candidate, continue_target)
        else {
            return false;
        };

        self.entry_is_break_funnel_to_continue(
            non_continue_entry,
            continue_target,
            loop_context,
            visited,
        )
    }

    fn entry_is_direct_loop_break(
        &self,
        entry: BlockRef,
        loop_context: &ActiveLoopContext,
    ) -> bool {
        loop_context.break_exits.contains_key(&entry)
            || entry == loop_context.post_loop
            || Some(entry) == loop_context.downstream_post_loop
    }

    fn lower_value_merge_node(
        &self,
        short: &ShortCircuitCandidate,
        node_ref: ShortCircuitNodeRef,
        target_temp: TempId,
        prefix_emitted: bool,
    ) -> Option<HirBlock> {
        let node = short.nodes.get(node_ref.index())?;
        let mut stmts = Vec::new();

        if !prefix_emitted {
            stmts.extend(self.lower_block_prefix(node.header, true, &BTreeMap::new())?);
        }

        let cond = lower_short_circuit_subject(self.lowering, node.header)?;
        let truthy =
            self.lower_value_merge_target(short, node.header, &node.truthy, target_temp)?;
        let falsy = self.lower_value_merge_target(short, node.header, &node.falsy, target_temp)?;
        stmts.push(branch_stmt(cond, truthy, Some(falsy)));

        Some(HirBlock { stmts })
    }

    fn branch_entry_target_overrides(
        &self,
        header: BlockRef,
        entry: Option<BlockRef>,
        target_overrides: &BTreeMap<TempId, HirLValue>,
    ) -> BTreeMap<TempId, HirLValue> {
        let Some(entry) = entry else {
            return target_overrides.clone();
        };
        let Some(candidate) = self.branch_by_header.get(&header).copied() else {
            return target_overrides.clone();
        };

        if entry == candidate.then_entry {
            return self.branch_value_then_target_overrides(header, target_overrides);
        }
        if Some(entry) == candidate.else_entry {
            return self.branch_value_else_target_overrides(header, target_overrides);
        }

        target_overrides.clone()
    }

    fn lower_value_merge_target(
        &self,
        short: &ShortCircuitCandidate,
        current_header: BlockRef,
        target: &ShortCircuitTarget,
        target_temp: TempId,
    ) -> Option<HirBlock> {
        match target {
            ShortCircuitTarget::Node(next_ref) => {
                self.lower_value_merge_node(short, *next_ref, target_temp, false)
            }
            ShortCircuitTarget::Value(block) => {
                self.lower_value_merge_leaf(short, current_header, *block, target_temp)
            }
            ShortCircuitTarget::TruthyExit | ShortCircuitTarget::FalsyExit => None,
        }
    }

    fn lower_value_merge_leaf(
        &self,
        short: &ShortCircuitCandidate,
        current_header: BlockRef,
        block: BlockRef,
        target_temp: TempId,
    ) -> Option<HirBlock> {
        let mut stmts = if block == current_header {
            Vec::new()
        } else {
            self.lower_block_prefix(block, false, &BTreeMap::new())?
        };
        let value = if block == current_header
            && header_subject_is_value_carrier(self.lowering, current_header, short.result_reg)
        {
            // Truthiness 测试在 result_reg 上：subject 运行时值即保留值。
            lower_short_circuit_subject(self.lowering, block)?
        } else {
            lower_materialized_value_leaf_expr(self.lowering, short, block)?
        };
        stmts.push(assign_stmt(vec![HirLValue::Temp(target_temp)], vec![value]));

        Some(HirBlock { stmts })
    }

    /// 以 SC 的树结构为骨架，对一个不由 SC 覆盖的寄存器构建 Decision 表达式。
    ///
    /// 在每个叶子节点处读取该寄存器的 block 出口值，用与 SC 相同的分支条件
    /// 串联成一棵嵌套决策树。例子：SC 树为 `x and (y and 2 or 3) or 6` 只
    /// 覆盖 r4；对于 r3（叶子值 #2→1, #3→4, #4→5），这里会产出
    /// `Decision(x ? Decision(y ? 1 : 4) : 5)` 赋值到 r3 的 phi temp。
    fn build_secondary_value_merge_decision(
        &self,
        short: &ShortCircuitCandidate,
        reg: Reg,
    ) -> Option<HirExpr> {
        let mut nodes = Vec::new();
        self.build_secondary_decision_node(short, short.entry, reg, &mut nodes)?;
        Some(HirExpr::Decision(Box::new(HirDecisionExpr {
            entry: HirDecisionNodeRef(0),
            nodes,
        })))
    }

    fn build_secondary_decision_node(
        &self,
        short: &ShortCircuitCandidate,
        node_ref: ShortCircuitNodeRef,
        reg: Reg,
        nodes: &mut Vec<HirDecisionNode>,
    ) -> Option<HirDecisionNodeRef> {
        let node = short.nodes.get(node_ref.index())?;
        let my_ref = HirDecisionNodeRef(nodes.len());
        // 先占位，后续填充 test/truthy/falsy
        nodes.push(HirDecisionNode {
            id: my_ref,
            test: HirExpr::Nil,
            truthy: HirDecisionTarget::CurrentValue,
            falsy: HirDecisionTarget::CurrentValue,
        });

        let cond = lower_short_circuit_subject(self.lowering, node.header)?;
        let truthy =
            self.build_secondary_decision_target(short, &node.truthy, reg, nodes)?;
        let falsy =
            self.build_secondary_decision_target(short, &node.falsy, reg, nodes)?;

        nodes[my_ref.index()].test = cond;
        nodes[my_ref.index()].truthy = truthy;
        nodes[my_ref.index()].falsy = falsy;
        Some(my_ref)
    }

    fn build_secondary_decision_target(
        &self,
        short: &ShortCircuitCandidate,
        target: &ShortCircuitTarget,
        reg: Reg,
        nodes: &mut Vec<HirDecisionNode>,
    ) -> Option<HirDecisionTarget> {
        match target {
            ShortCircuitTarget::Node(next_ref) => {
                let node_ref =
                    self.build_secondary_decision_node(short, *next_ref, reg, nodes)?;
                Some(HirDecisionTarget::Node(node_ref))
            }
            ShortCircuitTarget::Value(block) => {
                let value = expr_for_reg_at_block_exit(self.lowering, *block, reg);
                Some(HirDecisionTarget::Expr(value))
            }
            ShortCircuitTarget::TruthyExit | ShortCircuitTarget::FalsyExit => None,
        }
    }

    fn install_stop_boundary_value_merge_override(
        &mut self,
        header: BlockRef,
        branch_stop: Option<BlockRef>,
        target_overrides: &BTreeMap<TempId, HirLValue>,
    ) {
        let Some(merge) = branch_stop else {
            return;
        };
        let Some(short) = value_merge_candidate_by_header(self.lowering, header) else {
            return;
        };
        let ShortCircuitExit::ValueMerge(short_merge) = short.exit else {
            return;
        };
        if short_merge != merge {
            return;
        }

        let Some(phi_id) = short.result_phi_id else {
            return;
        };
        let Some(reg) = short.result_reg else {
            return;
        };
        let Some(expr) = shared_target_expr_from_overrides(self.lowering, short, target_overrides)
        else {
            return;
        };

        self.replace_phi_with_entry_expr(merge, phi_id, reg, expr);
    }
}

/// 如果值合流候选的 entry_defs 中有任一 def 的 temp 已被 target_overrides 接管，
/// 说明该 def 的写入经由循环 state plan 被重定向到了 state 变量。此时如果仍走
/// SC value-merge 的快捷路径，lower_value_merge_leaf 会用空 override map 调用
/// lower_block_prefix，导致 state 写入重定向被跳过。
/// 检查值型短路候选内是否有被 target_overrides 接管的 def。
///
/// 包含两类来源：
/// 1. `entry_defs`——从 SC 外部流入的初始值，作为值合流某条路径的"保留原值"语义；
/// 2. `value_incomings` 中的 leaf defs——SC 内部叶子块写入 result_reg 的具体值。
///
/// 当外层 BVM 通过 target_overrides 要求将这些 def 的写入重定向到合并 temp 时，
/// SC 快捷路径因为不会传递 target_overrides 给叶子展开逻辑，会导致重定向写入丢失。
/// 此时应退让给普通分支降级，在 apply_loop_rewrites / BVM 管道中正确路由。
fn value_merge_defs_are_overridden(
    lowering: &ProtoLowering<'_>,
    short: &ShortCircuitCandidate,
    target_overrides: &BTreeMap<TempId, HirLValue>,
) -> bool {
    if target_overrides.is_empty() {
        return false;
    }
    let is_overridden = |def: &DefId| {
        lowering
            .bindings
            .fixed_temps
            .get(def.index())
            .is_some_and(|temp| target_overrides.contains_key(temp))
    };
    short.entry_defs.iter().any(is_overridden)
        || short
            .value_incomings
            .iter()
            .any(|inc| inc.defs.iter().any(is_overridden))
}