ViperC/App/lib/core/Handles/HandlesFor.vp

import t, c
from stdint import *
import ast
import llvmlite
import memhub
import string
import stdio
import viperlib
import lib.core.Handles.HandlesBase as HandlesBase
import lib.core.Handles.HandlesTranslator as HT
import lib.core.Handles.HandlesVar as HandlesVar
import lib.core.Handles.HandlesExpr as HandlesExpr
import lib.core.Handles.HandlesBody as HandlesBody
import lib.core.Handles.HandlesType as HandlesType
import lib.core.Handles.HandlesExprCall as HandlesExprCall
import lib.core.Handles.HandlesStruct as HandlesStruct


# ============================================================
# HandlesFor - for 循环语句处理（P6 对象化后的委托层）
#
# NewForHandle 工厂已迁移为 lib.core.Gen.StmtGenMixin 的方法
# （ForHandle 类保留：trans.ForH 的类型，由 HandlesTranslator.
# _init_state 经 NewForHandle 委托创建）。
#
# 支持 for i in range(start, stop, step) 模式:
#   %i = alloca i32
#   store i32 start, i32* %i
#   br label %cond
# cond:
#   %cur = load i32, i32* %i
#   %cmp = icmp slt i32 %cur, stop
#   br i1 %cmp, label %body, label %end
# body:
#   ... body ...
#   br label %incr
# incr:
#   %cur2 = load i32, i32* %i
#   %next = add i32 %cur2, step
#   store i32 %next, i32* %i
#   br label %cond
# end:
# ============================================================


# ============================================================
# 全局 gen 单例（模块级镜像，同 HandlesStruct 模式）
#
# 由 BuildPipeline/main 在 gen 创建后调用 set_global_gen 注入。
# 委托函数用本地 _g_gen（cast 成 Generator 类型）调
# StmtGenMixin 方法，避免函数体 import 包模块与类/模块名歧义。
# ============================================================
_g_gen: t.CVoid | t.CPtr = None


# ============================================================
# 序列迭代源类型码（for x in ... / enumerate / zip 迭代源分类）
#   RANGE: range(start, stop, step)
#   STR:   字符串（常量或 str 变量）
#   LIST:  list[T] 容器（按 __count__ + __data__ 迭代）
# ============================================================
SEQ_KIND_RANGE: t.CDefine = 1
SEQ_KIND_STR: t.CDefine = 2
SEQ_KIND_LIST: t.CDefine = 3


def set_global_gen(gen: t.CVoid | t.CPtr) -> None:
    """注入全局 gen 单例（BuildPipeline/main 调用）"""
    global _g_gen
    _g_gen = gen


@t.NoVTable
class ForHandle(HandlesBase.Mixin):
    """for 循环语句处理器：继承 Mixin 获得 Trans 回指针"""

    def __init__(self, trans: HT.Translator | t.CPtr):
        self.Trans = trans

    # ============================================================
    # Handle - 处理 for 语句，返回新增变量数
    # ============================================================
    def Handle(self, node: ast.AST | t.CPtr) -> int:
        """翻译 for i in range(...) 循环语句"""
        if node is None:
            return 0

        trans: HT.Translator | t.CPtr = self.Trans
        pool: memhub.MemBuddy | t.CPtr = trans.Pool
        builder: llvmlite.IRBuilder | t.CPtr = trans._cur_builder
        func: llvmlite.Function | t.CPtr = trans._cur_func

        if builder is None or func is None:
            return 0

        for_node: ast.For | t.CPtr = (ast.For | t.CPtr)(node)

        # 1. 获取循环变量（Name 单变量 / Tuple 多变量）
        target: ast.AST | t.CPtr = for_node.target
        if target is None:
            return 0
        tk: int = target.kind()
        if tk != ast.ASTKind.Name and tk != ast.ASTKind.Tuple:
            return 0
        var_name: str = None
        if tk == ast.ASTKind.Name:
            target_nm: ast.Name | t.CPtr = (ast.Name | t.CPtr)(target)
            var_name = target_nm.id
            if var_name is None:
                return 0

        # 2. 解析迭代器：支持 range() 和指针迭代
        iter_node: ast.AST | t.CPtr = for_node.iter
        if iter_node is None:
            return 0

        # 检查是否是 range() 调用
        is_range_iter: int = 0
        if iter_node.kind() == ast.ASTKind.Call:
            call_pre: ast.Call | t.CPtr = (ast.Call | t.CPtr)(iter_node)
            fn_pre: str = HandlesExpr.get_func_name(call_pre.func)
            if fn_pre is not None:
                if string.strcmp(fn_pre, "range") == 0:
                    is_range_iter = 1
                elif string.strcmp(fn_pre, "enumerate") == 0 or string.strcmp(fn_pre, "zip") == 0:
                    pass  # 多变量迭代，在下方非 range 分支处理
                else:
                    err_msg: str = pool.alloc(256)
                    if err_msg is not None:
                        viperlib.snprintf(err_msg, 256, "仅支持 range()/enumerate()/zip() 或指针迭代，got call '%s'", fn_pre)
                        HandlesType.fatal_error(iter_node, err_msg)
                    HandlesType.fatal_error(iter_node, "仅支持 range()/enumerate()/zip() 或指针迭代")

        # 非范围迭代：走指针/数组/列表字面量/容器/多变量迭代路径
        if is_range_iter == 0:
            # 列表字面量：按元素顺序迭代（for x in [1, 2, 3]）
            if iter_node.kind() == ast.ASTKind.List:
                return self._handle_list_literal_iter(for_node, var_name, iter_node)
            # enumerate(x)：for i, v in enumerate(x)（多变量迭代）
            if iter_node.kind() == ast.ASTKind.Call:
                call_mi: ast.Call | t.CPtr = (ast.Call | t.CPtr)(iter_node)
                fn_mi: str = HandlesExpr.get_func_name(call_mi.func)
                if fn_mi is not None and string.strcmp(fn_mi, "enumerate") == 0:
                    if tk != ast.ASTKind.Tuple:
                        HandlesType.fatal_error(iter_node, "enumerate 迭代需要两个循环变量 (for i, v in enumerate(x))")
                    tup_ie: ast.Tuple | t.CPtr = (ast.Tuple | t.CPtr)(target)
                    t1_buf_ie: bytes = pool.alloc(128)
                    t2_buf_ie: bytes = pool.alloc(128)
                    if t1_buf_ie is None or t2_buf_ie is None:
                        return 0
                    t1_buf_ie[0] = '\0'
                    t2_buf_ie[0] = '\0'
                    if self._extract_tuple_names(tup_ie, t1_buf_ie, t2_buf_ie) == 0:
                        HandlesType.fatal_error(iter_node, "enumerate 迭代变量必须是简单名称")
                    return self._handle_enumerate_iter(for_node, t1_buf_ie, t2_buf_ie, call_mi)
                if fn_mi is not None and string.strcmp(fn_mi, "zip") == 0:
                    if tk != ast.ASTKind.Tuple:
                        HandlesType.fatal_error(iter_node, "zip 迭代需要两个循环变量 (for a, b in zip(...))")
                    tup_iz: ast.Tuple | t.CPtr = (ast.Tuple | t.CPtr)(target)
                    t1_buf_iz: bytes = pool.alloc(128)
                    t2_buf_iz: bytes = pool.alloc(128)
                    if t1_buf_iz is None or t2_buf_iz is None:
                        return 0
                    t1_buf_iz[0] = '\0'
                    t2_buf_iz[0] = '\0'
                    if self._extract_tuple_names(tup_iz, t1_buf_iz, t2_buf_iz) == 0:
                        HandlesType.fatal_error(iter_node, "zip 迭代变量必须是简单名称")
                    return self._handle_zip_iter(for_node, t1_buf_iz, t2_buf_iz, call_mi)
            # list[T] 容器变量：按 __count__ 动态长度迭代
            if iter_node.kind() == ast.ASTKind.Name and trans is not None:
                nm_lst: ast.Name | t.CPtr = (ast.Name | t.CPtr)(iter_node)
                if nm_lst.id is not None:
                    ve_lst: HandlesVar.VarEntry | t.CPtr = HandlesVar.lookup_var_entry(
                        trans.SymTab, nm_lst.id)
                    if ve_lst is not None and ve_lst.AnnotClassName is not None:
                        # dict 容器变量：按 __count__/__keys__ 布局迭代（__iter__ 协议内联）
                        if string.strstr(ve_lst.AnnotClassName, "dict") is not None:
                            lst_val: llvmlite.Value | t.CPtr = HandlesExpr.translate_value(
                                builder, pool, trans.Module, iter_node,
                                trans._funcs, trans._func_count, trans)
                            if lst_val is not None and lst_val.Ty is not None \
                                    and HandlesExpr.is_ptr_type(lst_val.Ty) != 0:
                                return self._handle_dict_iter(for_node, var_name, lst_val)
                        if string.strstr(ve_lst.AnnotClassName, "list") is not None:
                            lst_val: llvmlite.Value | t.CPtr = HandlesExpr.translate_value(
                                builder, pool, trans.Module, iter_node,
                                trans._funcs, trans._func_count, trans)
                            if lst_val is not None and lst_val.Ty is not None \
                                    and HandlesExpr.is_ptr_type(lst_val.Ty) != 0:
                                return self._handle_list_iter(for_node, var_name, lst_val)
            # OOP iter 协议：迭代源是类对象且类有 __iter__/__next__ 方法 →
            # 走 __iter__/__next__ 调用迭代（对齐 TPC HandlesFor.py L142-166
            # _HandleForIterLlvm）。dict/list 是内置泛型容器已在上方内联处理。
            ov_val: llvmlite.Value | t.CPtr = HandlesExpr.translate_value(
                builder, pool, trans.Module, iter_node,
                trans._funcs, trans._func_count, trans)
            if ov_val is not None and ov_val.Ty is not None \
                    and HandlesExpr.is_ptr_type(ov_val.Ty) != 0:
                ov_st: llvmlite.LLVMType | t.CPtr = HandlesStruct.get_struct_type_from_value(
                    ov_val)
                if ov_st is not None:
                    ov_cn: str = HandlesStruct.get_class_name_by_type(pool, ov_st)
                    if ov_cn is not None:
                        oi_lookup: str = pool.alloc(128)
                        if oi_lookup is not None:
                            viperlib.snprintf(oi_lookup, 128, "%s.__iter__", ov_cn)
                            oi_fn: llvmlite.Function | t.CPtr = HandlesExprCall.find_func_in_module(
                                trans.Module, oi_lookup)
                            if oi_fn is not None:
                                on_lookup: str = pool.alloc(128)
                                if on_lookup is not None:
                                    viperlib.snprintf(on_lookup, 128, "%s.__next__", ov_cn)
                                    on_fn: llvmlite.Function | t.CPtr = HandlesExprCall.find_func_in_module(
                                        trans.Module, on_lookup)
                                    if on_fn is not None:
                                        return self._handle_oop_iter(
                                            for_node, var_name, ov_cn, ov_val)
            # 其它不支持的字面量：fast-fail 显式报错，
            # 避免 translate_value 触发 list[T] 特化崩溃或语义歧义。
            ik: int = iter_node.kind()
            if ik == ast.ASTKind.Constant:
                cn_ik: ast.Constant | t.CPtr = (ast.Constant | t.CPtr)(iter_node)
                if cn_ik.const_kind != ast.CONST_STR:
                    HandlesType.fatal_error(
                        iter_node,
                        "for 迭代不支持该常量（仅支持字符串、数组、列表字面量、range()）")
            elif ik == ast.ASTKind.Dict or ik == ast.ASTKind.Set or ik == ast.ASTKind.Tuple \
                 or ik == ast.ASTKind.SetComp or ik == ast.ASTKind.DictComp:
                HandlesType.fatal_error(
                    iter_node,
                    "for 迭代不支持字典/集合/元组字面量，请使用 range()、t.CArray 数组或列表字面量")
            return self._handle_ptr_iter(for_node, var_name)

        call: ast.Call | t.CPtr = (ast.Call | t.CPtr)(iter_node)

        # 3. 解析 range 参数: range(stop) / range(start, stop) / range(start, stop, step)
        args: list[ast.AST | t.CPtr] | t.CPtr = call.args
        if args is None:
            return 0
        arg_count: t.CSizeT = len(args)

        i32_ty: llvmlite.LLVMType | t.CPtr = llvmlite.Int32(pool)
        start_val: llvmlite.Value | t.CPtr = llvmlite.const_int32(pool, 0)
        stop_val: llvmlite.Value | t.CPtr = None
        step_val: llvmlite.Value | t.CPtr = llvmlite.const_int32(pool, 1)

        if arg_count == 0:
            # fail-fast: range 无参数，立即终止
            HandlesType.fatal_error(call, "range 需要至少一个参数", "SyntaxError")
        elif arg_count == 1:
            stop_val = HandlesExpr.translate_value(
                builder, pool, trans.Module, args.get(0),
                trans._funcs, trans._func_count, trans)
            if stop_val is None:
                # fail-fast: range 参数翻译失败
                HandlesType.fatal_error(args.get(0), "range 参数翻译失败", "TypeError")
        elif arg_count >= 2:
            start_val = HandlesExpr.translate_value(
                builder, pool, trans.Module, args.get(0),
                trans._funcs, trans._func_count, trans)
            if start_val is None:
                # fail-fast: range 参数翻译失败
                HandlesType.fatal_error(args.get(0), "range 参数翻译失败", "TypeError")
            stop_val = HandlesExpr.translate_value(
                builder, pool, trans.Module, args.get(1),
                trans._funcs, trans._func_count, trans)
            if stop_val is None:
                # fail-fast: range 参数翻译失败
                HandlesType.fatal_error(args.get(1), "range 参数翻译失败", "TypeError")
            if arg_count >= 3:
                step_val = HandlesExpr.translate_value(
                    builder, pool, trans.Module, args.get(2),
                    trans._funcs, trans._func_count, trans)
                if step_val is None:
                    # fail-fast: range 参数翻译失败
                    HandlesType.fatal_error(args.get(2), "range 参数翻译失败", "TypeError")
        # step 为负数字面量时循环条件反转（对齐 TPC HandlesFor.py L86-94）：
        #   range(a, b, -1) → i > stop；range(a, b, +1) → i < stop。
        #   TPC 仅识别负数字面量（UnaryOp USub 常量 / 负常量）；变量 step 保守按正。
        #   修复 _find_provider 的 range(top-1, -1, -1) 循环体不执行（i < -1 恒假）。
        step_neg_const: int = 0
        if arg_count >= 3:
            step_arg_node: ast.AST | t.CPtr = args.get(2)
            if step_arg_node is not None:
                skn: int = step_arg_node.kind()
                if skn == ast.ASTKind.UnaryOp:
                    uop_r: ast.UnaryOp | t.CPtr = (ast.UnaryOp | t.CPtr)(step_arg_node)
                    if uop_r.op == ast.OpKind.USub and uop_r.operand is not None:
                        if uop_r.operand.kind() == ast.ASTKind.Constant:
                            uoc_r: ast.Constant | t.CPtr = (ast.Constant | t.CPtr)(uop_r.operand)
                            if uoc_r.int_val > 0:
                                step_neg_const = 1
                elif skn == ast.ASTKind.Constant:
                    skc_r: ast.Constant | t.CPtr = (ast.Constant | t.CPtr)(step_arg_node)
                    if skc_r.int_val < 0:
                        step_neg_const = 1

        # 4. 创建/查找循环变量 alloca
        var_alloca: llvmlite.Value | t.CPtr = HandlesVar.lookup_var(
            trans.SymTab, var_name)
        new_vars: int = 0
        if var_alloca is None:
            var_alloca = HandlesVar._alloca_at_entry(builder, i32_ty)
            if HandlesVar.define_var(
                    trans.SymTab, var_name, var_alloca) == 0:
                new_vars = 1

        # 获取循环变量的实际元素类型（alloca 是指针类型，需解引用 Pointee）
        # 当循环变量已声明为 i64（如 t.CSizeT），使用 i64 而非硬编码 i32
        # 避免 load i32, i64* / store i32, i64* 类型不匹配
        loop_var_ty: llvmlite.LLVMType | t.CPtr = i32_ty
        if var_alloca is not None and var_alloca.Ty is not None:
            match var_alloca.Ty:
                case llvmlite.LLVMType.Ptr(pointee_ty):
                    if pointee_ty is not None:
                        loop_var_ty = pointee_ty
        loop_var_bits: int = HandlesExpr.get_llvm_type_bits(loop_var_ty)

        # 5. 存储初始值 (类型对齐: start_val 可能是 i32/i64，需对齐到 loop_var_ty)
        init_val: llvmlite.Value | t.CPtr = start_val
        if start_val is not None and start_val.Ty is not None:
            start_bits: int = HandlesExpr.get_llvm_type_bits(start_val.Ty)
            if start_bits != 0 and start_bits != loop_var_bits:
                if start_bits < loop_var_bits:
                    init_val = llvmlite.build_sext(builder, start_val, loop_var_ty)
                else:
                    init_val = llvmlite.build_trunc(builder, start_val, loop_var_ty)
        llvmlite.build_store(builder, init_val, var_alloca)

        # 6. 创建基本块: cond / body / incr / end（使用 trans._label_counter，不与 SSA 名共享）
        cnt: int = trans._label_counter
        trans._label_counter = cnt + 1

        name_buf: str = pool.alloc(32)
        viperlib.snprintf(name_buf, 32, "for.cond.%d", cnt)
        cond_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        viperlib.snprintf(name_buf, 32, "for.body.%d", cnt)
        body_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        viperlib.snprintf(name_buf, 32, "for.incr.%d", cnt)
        incr_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        viperlib.snprintf(name_buf, 32, "for.end.%d", cnt)
        end_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        # 7. 跳转到 cond 块
        llvmlite.build_br(builder, cond_bb)

        # 8. cond 块: load i, icmp slt i, stop, cond_br body/end
        llvmlite.position_at_end(builder, cond_bb)
        cur_i: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, loop_var_ty, var_alloca)
        # 类型对齐: stop_val 可能是 i64 (如 range(strlen(s)))，需将 cur_i 提升到 stop_val 类型
        cmp_lhs: llvmlite.Value | t.CPtr = cur_i
        cmp_rhs: llvmlite.Value | t.CPtr = stop_val
        if stop_val is not None and stop_val.Ty is not None:
            stop_bits: int = HandlesExpr.get_llvm_type_bits(stop_val.Ty)
            cur_bits: int = HandlesExpr.get_llvm_type_bits(cur_i.Ty)
            if stop_bits != 0 and cur_bits != 0 and stop_bits != cur_bits:
                if cur_bits < stop_bits:
                    cmp_lhs = llvmlite.build_sext(builder, cur_i, stop_val.Ty)
                else:
                    # 循环变量位宽 > stop 位宽（如 t.CSizeT 循环变量 + range(i32)）：
                    # 应把 cur_i 截断到 stop_val 类型（低向高才 sext/zext，高向低用
                    # trunc）。原实现反了——把小的 stop_val trunc 到大的 loop_var_ty，
                    # 生成 `trunc i32 to i64` 扩宽非法 IR，llc 报
                    # "invalid cast opcode for cast from 'i32' to 'i64'"
                    # （VpiReader.vp range(arg_count) 追加86 根因）。
                    cmp_lhs = llvmlite.build_trunc(builder, cur_i, stop_val.Ty)
        # step 为负时条件反转：i > stop（ICMP_SGT）；正/缺省 step 保持 i < stop
        range_cmp_op: int = llvmlite.ICMP_SLT
        if step_neg_const != 0:
            range_cmp_op = llvmlite.ICMP_SGT
        cond_i1: llvmlite.Value | t.CPtr = llvmlite.build_icmp(
            builder, range_cmp_op, cmp_lhs, cmp_rhs)
        llvmlite.build_cond_br(builder, cond_i1, body_bb, end_bb)

        # 9. body 块: 翻译循环体，跳到 incr
        llvmlite.position_at_end(builder, body_bb)

        # 保存旧循环上下文，设置 break/continue 目标
        old_break: llvmlite.BasicBlock | t.CPtr = trans._break_bb
        old_continue: llvmlite.BasicBlock | t.CPtr = trans._continue_bb
        trans._break_bb = end_bb
        trans._continue_bb = incr_bb

        body: list[ast.AST | t.CPtr] | t.CPtr = for_node.children
        if body is not None:
            body_count: t.CSizeT = len(body)
            for bi in range(body_count):
                stmt: ast.AST | t.CPtr = body.get(bi)
                if stmt is not None:
                    HandlesBody.translate_stmt(trans, stmt)

        # 恢复旧循环上下文
        trans._break_bb = old_break
        trans._continue_bb = old_continue

        if llvmlite.builder_cur_block_is_terminated(builder) == 0:
            llvmlite.build_br(builder, incr_bb)

        # 10. incr 块: i = i + step, 跳回 cond
        llvmlite.position_at_end(builder, incr_bb)
        cur_i2: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, loop_var_ty, var_alloca)
        # 类型对齐: step_val 可能是 i32/i64，需对齐到 loop_var_ty 与 cur_i2 类型一致
        incr_step: llvmlite.Value | t.CPtr = step_val
        if step_val is not None and step_val.Ty is not None:
            step_bits: int = HandlesExpr.get_llvm_type_bits(step_val.Ty)
            cur2_bits: int = HandlesExpr.get_llvm_type_bits(cur_i2.Ty)
            if step_bits != 0 and cur2_bits != 0 and step_bits != cur2_bits:
                if step_bits > cur2_bits:
                    incr_step = llvmlite.build_trunc(builder, step_val, loop_var_ty)
                else:
                    incr_step = llvmlite.build_sext(builder, step_val, loop_var_ty)
        next_i: llvmlite.Value | t.CPtr = llvmlite.build_add(builder, cur_i2, incr_step)
        llvmlite.build_store(builder, next_i, var_alloca)
        llvmlite.build_br(builder, cond_bb)

        # 11. 定位到 end 块
        llvmlite.position_at_end(builder, end_bb)
        # 追加90：for 循环正常结束路径 br 到 end_bb → merge 恒可达（需正常收尾）
        trans._ctrl_merge_reachable = 1
        return new_vars

    # ============================================================
    # _handle_ptr_iter - 指针迭代: for x in ptr:
    #   遍历指针，依赖隐式 index，直到解引用为空（null 终止符）
    #
    # 生成 IR 结构:
    #   %idx = alloca i32
    #   store i32 0, i32* %idx
    #   br label %cond
    # cond:
    #   %i = load i32, i32* %idx
    #   %ep = getelementptr elem_ty, ptr_ty %ptr, i32 %i
    #   %ev = load elem_ty, elem_ty* %ep
    #   %null = icmp eq elem_ty %ev, 0
    #   br i1 %null, label %end, label %body
    # body:
    #   store elem_ty %ev, elem_ty* %var
    #   ... 循环体 ...
    #   br label %incr
    # incr:
    #   %next = add i32 %i, 1
    #   store i32 %next, i32* %idx
    #   br label %cond
    # end:
    # ============================================================
    def _handle_ptr_iter(self, for_node: ast.For | t.CPtr,
                         var_name: str) -> int:
        """指针迭代: for x in ptr: 直到解引用为空"""
        trans: HT.Translator | t.CPtr = self.Trans
        pool: memhub.MemBuddy | t.CPtr = trans.Pool
        builder: llvmlite.IRBuilder | t.CPtr = trans._cur_builder
        func: llvmlite.Function | t.CPtr = trans._cur_func

        # 翻译迭代器表达式，获取指针值
        ptr_val: llvmlite.Value | t.CPtr = HandlesExpr.translate_value(
            builder, pool, trans.Module, for_node.iter,
            trans._funcs, trans._func_count, trans)
        if ptr_val is None:
            HandlesType.fatal_error(for_node, "指针迭代: 无法翻译迭代器表达式")

        # 检查迭代器类型
        if HandlesExpr.is_ptr_type(ptr_val.Ty) == 0:
            # 数组迭代：for k in arr（定长数组按长度迭代，元素可为任意类型）
            if HandlesExpr.is_array_type(ptr_val.Ty) != 0:
                return self._handle_array_iter(for_node, var_name, ptr_val)
            HandlesType.fatal_error(for_node, "指针迭代: 迭代器不是指针类型")

        # 获取元素类型
        elem_ty: llvmlite.LLVMType | t.CPtr = ptr_val.Ty.Pointee
        if elem_ty is None:
            HandlesType.fatal_error(for_node, "指针迭代: 无法获取元素类型")

        # 元素类型是数组（Ptr([N x T])，如 t.CArray 变量退化指针）：
        # load 出数组值后走数组迭代（按长度，非 null 终止）
        if HandlesExpr.is_array_type(elem_ty) != 0:
            arr_v2: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, elem_ty, ptr_val)
            if arr_v2 is not None:
                return self._handle_array_iter(for_node, var_name, arr_v2)

        # 元素类型必须是整数（用于 icmp eq 0 检查 null 终止符）
        elem_bits: int = HandlesExpr.get_llvm_type_bits(elem_ty)
        if elem_bits == 0:
            HandlesType.fatal_error(for_node, "指针迭代: 元素类型不是整数，无法检查 null 终止符")

        i32_ty: llvmlite.LLVMType | t.CPtr = llvmlite.Int32(pool)

        # 创建循环变量 alloca（存储元素值）
        var_alloca: llvmlite.Value | t.CPtr = HandlesVar.lookup_var(
            trans.SymTab, var_name)
        new_vars: int = 0
        if var_alloca is None:
            var_alloca = HandlesVar._alloca_at_entry(builder, elem_ty)
            if HandlesVar.define_var(
                    trans.SymTab, var_name, var_alloca) == 0:
                new_vars = 1

        # 创建隐式 index 变量，初始为 0
        idx_alloca: llvmlite.Value | t.CPtr = HandlesVar._alloca_at_entry(builder, i32_ty)
        llvmlite.build_store(builder, llvmlite.const_int32(pool, 0), idx_alloca)

        # 创建基本块: cond / body / incr / end
        cnt: int = trans._label_counter
        trans._label_counter = cnt + 1

        name_buf: str = pool.alloc(32)
        viperlib.snprintf(name_buf, 32, "ptr.cond.%d", cnt)
        cond_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        viperlib.snprintf(name_buf, 32, "ptr.body.%d", cnt)
        body_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        viperlib.snprintf(name_buf, 32, "ptr.incr.%d", cnt)
        incr_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        viperlib.snprintf(name_buf, 32, "ptr.end.%d", cnt)
        end_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        # 跳转到 cond
        llvmlite.build_br(builder, cond_bb)

        # cond 块: load index, GEP, load elem, icmp eq 0
        llvmlite.position_at_end(builder, cond_bb)
        cur_idx: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, i32_ty, idx_alloca)
        elem_ptr: llvmlite.Value | t.CPtr = llvmlite.build_gep(
            builder, elem_ty, ptr_val, cur_idx)
        cur_elem: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, elem_ty, elem_ptr)
        null_val: llvmlite.Value | t.CPtr = llvmlite.const_int(pool, elem_bits, 0)
        is_null: llvmlite.Value | t.CPtr = llvmlite.build_icmp(
            builder, llvmlite.ICMP_EQ, cur_elem, null_val)
        llvmlite.build_cond_br(builder, is_null, end_bb, body_bb)

        # body 块: store elem to var, 翻译循环体
        llvmlite.position_at_end(builder, body_bb)
        llvmlite.build_store(builder, cur_elem, var_alloca)

        # 保存旧循环上下文，设置 break/continue 目标
        old_break: llvmlite.BasicBlock | t.CPtr = trans._break_bb
        old_continue: llvmlite.BasicBlock | t.CPtr = trans._continue_bb
        trans._break_bb = end_bb
        trans._continue_bb = incr_bb

        body: list[ast.AST | t.CPtr] | t.CPtr = for_node.children
        if body is not None:
            body_count: t.CSizeT = len(body)
            for bi in range(body_count):
                stmt: ast.AST | t.CPtr = body.get(bi)
                if stmt is not None:
                    HandlesBody.translate_stmt(trans, stmt)

        # 恢复旧循环上下文
        trans._break_bb = old_break
        trans._continue_bb = old_continue

        if llvmlite.builder_cur_block_is_terminated(builder) == 0:
            llvmlite.build_br(builder, incr_bb)

        # incr 块: index++, br cond
        llvmlite.position_at_end(builder, incr_bb)
        one_val: llvmlite.Value | t.CPtr = llvmlite.const_int32(pool, 1)
        next_idx: llvmlite.Value | t.CPtr = llvmlite.build_add(builder, cur_idx, one_val)
        llvmlite.build_store(builder, next_idx, idx_alloca)
        llvmlite.build_br(builder, cond_bb)

        # 定位到 end 块
        llvmlite.position_at_end(builder, end_bb)
        # 追加90：for 循环正常结束路径 br 到 end_bb → merge 恒可达（需正常收尾）
        trans._ctrl_merge_reachable = 1
        return new_vars

    # ============================================================
    # _handle_array_iter - 数组迭代: for x in arr:
    #   定长数组按长度迭代（元素可为任意类型，不做 null 终止符检查）
    #
    # 数组值是数组类型而非指针（如局部 t.CArray 修复后），
    # 先拷到临时 alloca 获得地址，再按 [0, N) 迭代。
    #
    # 生成 IR 结构:
    #   %tmp = alloca [N x elem_ty]
    #   store [N x elem_ty] %arr_val, [N x elem_ty]* %tmp
    #   %idx = alloca i32 ; store 0
    #   br %cond
    # cond:
    #   %i = load i32, i32* %idx
    #   %c = icmp slt i32 %i, N
    #   br i1 %c, %body, %end
    # body:
    #   %ep = getelementptr [N x elem_ty], [N x elem_ty]* %tmp, i32 0, i32 %i
    #   %ev = load elem_ty, elem_ty* %ep
    #   store elem_ty %ev, elem_ty* %var
    #   ... 循环体 ...
    #   br %incr
    # incr:
    #   %n = add i32 %i, 1 ; store %n ; br %cond
    # end:
    # ============================================================
    def _handle_array_iter(self, for_node: ast.For | t.CPtr,
                           var_name: str,
                           array_val: llvmlite.Value | t.CPtr) -> int:
        """数组迭代: for x in arr: 按数组长度迭代"""
        trans: HT.Translator | t.CPtr = self.Trans
        pool: memhub.MemBuddy | t.CPtr = trans.Pool
        builder: llvmlite.IRBuilder | t.CPtr = trans._cur_builder
        func: llvmlite.Function | t.CPtr = trans._cur_func

        # 解析数组类型 [N x elem_ty]
        arr_ty: llvmlite.LLVMType | t.CPtr = array_val.Ty
        elem_ty: llvmlite.LLVMType | t.CPtr = None
        elem_count: int = 0
        match arr_ty:
            case llvmlite.LLVMType.Array(et, n):
                elem_ty = et
                elem_count = n
        if elem_ty is None or elem_count <= 0:
            HandlesType.fatal_error(for_node, "数组迭代: 无法解析数组类型")

        # 数组值 → 临时 alloca（数组值不是指针，需拷贝后 GEP 迭代）
        arr_tmp: llvmlite.Value | t.CPtr = llvmlite.build_alloca(builder, arr_ty)
        if arr_tmp is None:
            HandlesType.fatal_error(for_node, "数组迭代: 临时存储分配失败")
        llvmlite.build_store(builder, array_val, arr_tmp)

        i32_ty: llvmlite.LLVMType | t.CPtr = llvmlite.Int32(pool)

        # 循环变量 alloca（存储元素值）
        var_alloca: llvmlite.Value | t.CPtr = HandlesVar.lookup_var(
            trans.SymTab, var_name)
        new_vars: int = 0
        if var_alloca is None:
            var_alloca = HandlesVar._alloca_at_entry(builder, elem_ty)
            if HandlesVar.define_var(
                    trans.SymTab, var_name, var_alloca) == 0:
                new_vars = 1

        # 隐式 index 变量，初始为 0
        idx_alloca: llvmlite.Value | t.CPtr = HandlesVar._alloca_at_entry(builder, i32_ty)
        llvmlite.build_store(builder, llvmlite.const_int32(pool, 0), idx_alloca)

        # 基本块: cond / body / incr / end
        cnt: int = trans._label_counter
        trans._label_counter = cnt + 1

        name_buf: str = pool.alloc(32)
        viperlib.snprintf(name_buf, 32, "arr.cond.%d", cnt)
        cond_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        viperlib.snprintf(name_buf, 32, "arr.body.%d", cnt)
        body_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        viperlib.snprintf(name_buf, 32, "arr.incr.%d", cnt)
        incr_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        viperlib.snprintf(name_buf, 32, "arr.end.%d", cnt)
        end_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        llvmlite.build_br(builder, cond_bb)

        # cond 块: load index, icmp slt idx, elem_count
        llvmlite.position_at_end(builder, cond_bb)
        cur_idx: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, i32_ty, idx_alloca)
        count_val: llvmlite.Value | t.CPtr = llvmlite.const_int32(pool, elem_count)
        in_bounds: llvmlite.Value | t.CPtr = llvmlite.build_icmp(
            builder, llvmlite.ICMP_SLT, cur_idx, count_val)
        llvmlite.build_cond_br(builder, in_bounds, body_bb, end_bb)

        # body 块: GEP(0, idx) → load elem → store to var → 循环体
        llvmlite.position_at_end(builder, body_bb)
        elem_ptr: llvmlite.Value | t.CPtr = llvmlite.build_gep_array(
            builder, arr_ty, elem_ty, arr_tmp, cur_idx)
        cur_elem: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, elem_ty, elem_ptr)
        llvmlite.build_store(builder, cur_elem, var_alloca)

        old_break: llvmlite.BasicBlock | t.CPtr = trans._break_bb
        old_continue: llvmlite.BasicBlock | t.CPtr = trans._continue_bb
        trans._break_bb = end_bb
        trans._continue_bb = incr_bb

        body: list[ast.AST | t.CPtr] | t.CPtr = for_node.children
        if body is not None:
            body_count: t.CSizeT = len(body)
            for bi in range(body_count):
                stmt: ast.AST | t.CPtr = body.get(bi)
                if stmt is not None:
                    HandlesBody.translate_stmt(trans, stmt)

        trans._break_bb = old_break
        trans._continue_bb = old_continue

        if llvmlite.builder_cur_block_is_terminated(builder) == 0:
            llvmlite.build_br(builder, incr_bb)

        # incr 块: index++
        llvmlite.position_at_end(builder, incr_bb)
        one_val: llvmlite.Value | t.CPtr = llvmlite.const_int32(pool, 1)
        next_idx: llvmlite.Value | t.CPtr = llvmlite.build_add(builder, cur_idx, one_val)
        llvmlite.build_store(builder, next_idx, idx_alloca)
        llvmlite.build_br(builder, cond_bb)

        # 定位到 end 块
        llvmlite.position_at_end(builder, end_bb)
        # 追加90：for 循环正常结束路径 br 到 end_bb → merge 恒可达（需正常收尾）
        trans._ctrl_merge_reachable = 1
        return new_vars

    # ============================================================
    # _handle_list_literal_iter - 列表字面量迭代: for x in [a, b, c]:
    #   把列表字面量转成定长数组值，再复用数组迭代（按长度迭代）。
    #
    # 元素类型取第一个元素的值类型，其余元素 coerce 到该类型。
    # ============================================================
    def _handle_list_literal_iter(self, for_node: ast.For | t.CPtr,
                                  var_name: str,
                                  list_node: ast.AST | t.CPtr) -> int:
        """列表字面量迭代: for x in [a, b, c]: 按元素顺序迭代"""
        trans: HT.Translator | t.CPtr = self.Trans
        pool: memhub.MemBuddy | t.CPtr = trans.Pool
        builder: llvmlite.IRBuilder | t.CPtr = trans._cur_builder

        lst: ast.List | t.CPtr = (ast.List | t.CPtr)(list_node)
        if lst is None or lst.elts is None:
            HandlesType.fatal_error(for_node, "列表字面量迭代: 空列表")
        elts: list[ast.AST | t.CPtr] | t.CPtr = lst.elts
        elts_count: t.CSizeT = len(elts)
        if elts_count <= 0:
            HandlesType.fatal_error(for_node, "列表字面量迭代: 空列表")

        # 翻译第一个元素，确定元素类型
        first_el: ast.AST | t.CPtr = elts.get(0)
        first_val: llvmlite.Value | t.CPtr = HandlesExpr.translate_value(
            builder, pool, trans.Module, first_el,
            trans._funcs, trans._func_count, trans)
        if first_val is None or first_val.Ty is None:
            HandlesType.fatal_error(first_el, "列表字面量迭代: 无法确定元素类型")
        elem_ty: llvmlite.LLVMType | t.CPtr = first_val.Ty

        # 构建 [N x elem_ty] 数组值：临时 alloca 逐元素写入后 load
        arr_ty: llvmlite.LLVMType | t.CPtr = llvmlite.Array(pool, elem_ty, elts_count)
        tmp_alloca: llvmlite.Value | t.CPtr = llvmlite.build_alloca(builder, arr_ty)
        if tmp_alloca is None:
            HandlesType.fatal_error(for_node, "列表字面量迭代: 临时数组分配失败")
        first_ptr: llvmlite.Value | t.CPtr = llvmlite.build_gep_array(
            builder, arr_ty, elem_ty, tmp_alloca, llvmlite.const_int32(pool, 0))
        if first_ptr is not None:
            llvmlite.build_store(builder, first_val, first_ptr)
        # 写其余元素（coerce 到 elem_ty）
        i: t.CSizeT = 1
        while i < elts_count:
            el_node: ast.AST | t.CPtr = elts.get(i)
            el_val: llvmlite.Value | t.CPtr = HandlesExpr.translate_value(
                builder, pool, trans.Module, el_node,
                trans._funcs, trans._func_count, trans)
            if el_val is not None:
                el_val = HandlesExpr.coerce_to_type(builder, el_val, elem_ty, el_node)
                el_ptr: llvmlite.Value | t.CPtr = llvmlite.build_gep_array(
                    builder, arr_ty, elem_ty, tmp_alloca,
                    llvmlite.const_int32(pool, i))
                if el_ptr is not None:
                    llvmlite.build_store(builder, el_val, el_ptr)
            i += 1
        # load 回数组值，复用数组迭代
        arr_val: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, arr_ty, tmp_alloca)
        if arr_val is None:
            HandlesType.fatal_error(for_node, "列表字面量迭代: 数组加载失败")
        return self._handle_array_iter(for_node, var_name, arr_val)

    # ============================================================
    # _handle_list_iter - list[T] 容器迭代: for v in lst:
    #   按 __count__ 动态长度迭代（元素任意类型，不做 null 终止符检查）
    #
    # list 结构布局 (6 字段 × 8 字节):
    #   __data__(0) __count__(8) __capacity__(16) __pool__(24)
    #   __elem_size__(32) __iter_index__(40)
    #
    # 生成 IR 结构:
    #   %count = load __count__
    #   %idx = alloca i64 ; store 0
    #   br %cond
    # cond:
    #   %i = load i64, %idx
    #   %c = icmp slt i64 %i, %count
    #   br i1 %c, %body, %end
    # body:
    #   %data = load __data__ (i8*)
    #   %es = load __elem_size__ (i64)
    #   %off = mul i64 %i, %es
    #   %addr = getelementptr i8, i8* %data, i64 %off
    #   %el = load i8*, i8** %addr
    #   store i8* %el, i8** %var
    #   ... 循环体 ...
    #   br %incr
    # incr:
    #   %n = add i64 %i, 1 ; store ; br %cond
    # end:
    # ============================================================
    def _handle_list_iter(self, for_node: ast.For | t.CPtr,
                          var_name: str,
                          list_val: llvmlite.Value | t.CPtr) -> int:
        """list[T] 容器迭代: for v in lst: 按 __count__ 动态长度迭代"""
        trans: HT.Translator | t.CPtr = self.Trans
        pool: memhub.MemBuddy | t.CPtr = trans.Pool
        builder: llvmlite.IRBuilder | t.CPtr = trans._cur_builder
        func: llvmlite.Function | t.CPtr = trans._cur_func

        i64_ty: llvmlite.LLVMType | t.CPtr = llvmlite.Int64(pool)
        i8_ty: llvmlite.LLVMType | t.CPtr = llvmlite.Int8(pool)
        i8_ptr_ty: llvmlite.LLVMType | t.CPtr = llvmlite.Ptr(pool, i8_ty)

        # 读取 __count__ (偏移 8, GEP index 1)
        cnt_ptr: llvmlite.Value | t.CPtr = llvmlite.build_gep(
            builder, i64_ty, list_val, llvmlite.const_int64(pool, 1))
        if cnt_ptr is None:
            HandlesType.fatal_error(for_node, "list 迭代: 无法定位 __count__")
        count_val: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, i64_ty, cnt_ptr)

        # 循环变量 alloca（元素类型 i8*，与 list.get 内联一致）
        var_alloca: llvmlite.Value | t.CPtr = HandlesVar.lookup_var(
            trans.SymTab, var_name)
        new_vars: int = 0
        if var_alloca is None:
            var_alloca = HandlesVar._alloca_at_entry(builder, i8_ptr_ty)
            if HandlesVar.define_var(
                    trans.SymTab, var_name, var_alloca) == 0:
                new_vars = 1

        # 隐式 index 变量 (i64，与 __count__ 类型对齐)
        idx_alloca: llvmlite.Value | t.CPtr = HandlesVar._alloca_at_entry(builder, i64_ty)
        llvmlite.build_store(builder, llvmlite.const_int64(pool, 0), idx_alloca)

        # 基本块: cond / body / incr / end
        cnt: int = trans._label_counter
        trans._label_counter = cnt + 1

        name_buf: str = pool.alloc(32)
        viperlib.snprintf(name_buf, 32, "lst.cond.%d", cnt)
        cond_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        viperlib.snprintf(name_buf, 32, "lst.body.%d", cnt)
        body_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        viperlib.snprintf(name_buf, 32, "lst.incr.%d", cnt)
        incr_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        viperlib.snprintf(name_buf, 32, "lst.end.%d", cnt)
        end_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        llvmlite.build_br(builder, cond_bb)

        # cond 块: load index, icmp slt idx, count
        llvmlite.position_at_end(builder, cond_bb)
        cur_idx: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, i64_ty, idx_alloca)
        in_bounds: llvmlite.Value | t.CPtr = llvmlite.build_icmp(
            builder, llvmlite.ICMP_SLT, cur_idx, count_val)
        llvmlite.build_cond_br(builder, in_bounds, body_bb, end_bb)

        # body 块: __data__ + idx*__elem_size__ → load 元素 → store to var
        llvmlite.position_at_end(builder, body_bb)
        dpp: llvmlite.Value | t.CPtr = llvmlite.build_gep(
            builder, i64_ty, list_val, llvmlite.const_int64(pool, 0))
        data_ptr: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, i8_ptr_ty, dpp)
        epp: llvmlite.Value | t.CPtr = llvmlite.build_gep(
            builder, i64_ty, list_val, llvmlite.const_int64(pool, 4))
        esize: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, i64_ty, epp)
        offset: llvmlite.Value | t.CPtr = llvmlite.build_mul(builder, cur_idx, esize)
        elem_addr: llvmlite.Value | t.CPtr = llvmlite.build_gep(
            builder, i8_ty, data_ptr, offset)
        cur_elem: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, i8_ptr_ty, elem_addr)
        llvmlite.build_store(builder, cur_elem, var_alloca)

        # 保存旧循环上下文，设置 break/continue 目标
        old_break: llvmlite.BasicBlock | t.CPtr = trans._break_bb
        old_continue: llvmlite.BasicBlock | t.CPtr = trans._continue_bb
        trans._break_bb = end_bb
        trans._continue_bb = incr_bb

        body: list[ast.AST | t.CPtr] | t.CPtr = for_node.children
        if body is not None:
            body_count: t.CSizeT = len(body)
            for bi in range(body_count):
                stmt: ast.AST | t.CPtr = body.get(bi)
                if stmt is not None:
                    HandlesBody.translate_stmt(trans, stmt)

        trans._break_bb = old_break
        trans._continue_bb = old_continue

        if llvmlite.builder_cur_block_is_terminated(builder) == 0:
            llvmlite.build_br(builder, incr_bb)

        # incr 块: index++
        llvmlite.position_at_end(builder, incr_bb)
        one_val: llvmlite.Value | t.CPtr = llvmlite.const_int64(pool, 1)
        next_idx: llvmlite.Value | t.CPtr = llvmlite.build_add(builder, cur_idx, one_val)
        llvmlite.build_store(builder, next_idx, idx_alloca)
        llvmlite.build_br(builder, cond_bb)

        # 定位到 end 块
        llvmlite.position_at_end(builder, end_bb)
        # 追加90：for 循环正常结束路径 br 到 end_bb → merge 恒可达（需正常收尾）
        trans._ctrl_merge_reachable = 1
        return new_vars

    def _handle_dict_iter(self, for_node: ast.For | t.CPtr,
                          var_name: str,
                          dict_val: llvmlite.Value | t.CPtr) -> int:
        """dict 容器迭代: for key in d: 按 __count__/__keys__ 布局迭代

        _dict.vp 布局（8 字节槽）：__keys__@0, __values__@1, __count__@2,
        __capacity__@3, __mbuddy__@4, __iter_index__@5。
        __iter__ 协议（__iter__ 重置 iter_index + __next__ 取 key）内联为
        循环：iter_idx < __count__ → key = __keys__[iter_idx]。
        """
        trans: HT.Translator | t.CPtr = self.Trans
        pool: memhub.MemBuddy | t.CPtr = trans.Pool
        builder: llvmlite.IRBuilder | t.CPtr = trans._cur_builder
        func: llvmlite.Function | t.CPtr = trans._cur_func

        i64_ty: llvmlite.LLVMType | t.CPtr = llvmlite.Int64(pool)
        i8_ty: llvmlite.LLVMType | t.CPtr = llvmlite.Int8(pool)
        i8_ptr_ty: llvmlite.LLVMType | t.CPtr = llvmlite.Ptr(pool, i8_ty)

        # 读取 __count__（槽 2，字节偏移 16）
        cnt_ptr: llvmlite.Value | t.CPtr = llvmlite.build_gep(
            builder, i64_ty, dict_val, llvmlite.const_int64(pool, 2))
        if cnt_ptr is None:
            HandlesType.fatal_error(for_node, "dict 迭代: 无法定位 __count__")
        count_val: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, i64_ty, cnt_ptr)

        # 循环变量 alloca（元素类型 i8*，与 dict.__next__ 返回 str 一致）
        var_alloca: llvmlite.Value | t.CPtr = HandlesVar.lookup_var(
            trans.SymTab, var_name)
        new_vars: int = 0
        if var_alloca is None:
            var_alloca = HandlesVar._alloca_at_entry(builder, i8_ptr_ty)
            if HandlesVar.define_var(
                    trans.SymTab, var_name, var_alloca) == 0:
                new_vars = 1

        # 隐式 index 变量 (i64，与 __count__ 类型对齐)
        idx_alloca: llvmlite.Value | t.CPtr = HandlesVar._alloca_at_entry(builder, i64_ty)
        llvmlite.build_store(builder, llvmlite.const_int64(pool, 0), idx_alloca)

        # 基本块: cond / body / incr / end
        cnt: int = trans._label_counter
        trans._label_counter = cnt + 1

        name_buf: str = pool.alloc(32)
        viperlib.snprintf(name_buf, 32, "dict.cond.%d", cnt)
        cond_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        viperlib.snprintf(name_buf, 32, "dict.body.%d", cnt)
        body_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        viperlib.snprintf(name_buf, 32, "dict.incr.%d", cnt)
        incr_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        viperlib.snprintf(name_buf, 32, "dict.end.%d", cnt)
        end_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        llvmlite.build_br(builder, cond_bb)

        # cond 块: load index, icmp slt idx, count
        llvmlite.position_at_end(builder, cond_bb)
        cur_idx: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, i64_ty, idx_alloca)
        in_bounds: llvmlite.Value | t.CPtr = llvmlite.build_icmp(
            builder, llvmlite.ICMP_SLT, cur_idx, count_val)
        llvmlite.build_cond_br(builder, in_bounds, body_bb, end_bb)

        # body 块: __keys__ + idx*8 → load key (i8*) → store to var
        llvmlite.position_at_end(builder, body_bb)
        kpp: llvmlite.Value | t.CPtr = llvmlite.build_gep(
            builder, i64_ty, dict_val, llvmlite.const_int64(pool, 0))
        keys_ptr: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, i8_ptr_ty, kpp)
        eight_val: llvmlite.Value | t.CPtr = llvmlite.const_int64(pool, 8)
        key_offset: llvmlite.Value | t.CPtr = llvmlite.build_mul(builder, cur_idx, eight_val)
        key_addr: llvmlite.Value | t.CPtr = llvmlite.build_gep(
            builder, i8_ty, keys_ptr, key_offset)
        cur_key: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, i8_ptr_ty, key_addr)
        llvmlite.build_store(builder, cur_key, var_alloca)

        # 保存旧循环上下文，设置 break/continue 目标
        old_break: llvmlite.BasicBlock | t.CPtr = trans._break_bb
        old_continue: llvmlite.BasicBlock | t.CPtr = trans._continue_bb
        trans._break_bb = end_bb
        trans._continue_bb = incr_bb

        body: list[ast.AST | t.CPtr] | t.CPtr = for_node.children
        if body is not None:
            body_count: t.CSizeT = len(body)
            for bi in range(body_count):
                stmt: ast.AST | t.CPtr = body.get(bi)
                if stmt is not None:
                    HandlesBody.translate_stmt(trans, stmt)

        trans._break_bb = old_break
        trans._continue_bb = old_continue

        if llvmlite.builder_cur_block_is_terminated(builder) == 0:
            llvmlite.build_br(builder, incr_bb)

        # incr 块: index++
        llvmlite.position_at_end(builder, incr_bb)
        one_val: llvmlite.Value | t.CPtr = llvmlite.const_int64(pool, 1)
        next_idx: llvmlite.Value | t.CPtr = llvmlite.build_add(builder, cur_idx, one_val)
        llvmlite.build_store(builder, next_idx, idx_alloca)
        llvmlite.build_br(builder, cond_bb)

        # 定位到 end 块
        llvmlite.position_at_end(builder, end_bb)
        # 追加90：for 循环正常结束路径 br 到 end_bb → merge 恒可达（需正常收尾）
        trans._ctrl_merge_reachable = 1
        return new_vars

    # ============================================================
    # _handle_oop_iter - OOP 迭代协议: for x in obj:
    #   obj 的类有 __iter__/__next__ 方法时调用协议迭代
    #   （对齐 TPC HandlesFor.py _HandleForIterLlvm L599-663）
    #
    # 生成 IR 结构:
    #   %it = call {Class}.__iter__(obj)
    #   %flag = alloca i1 ; store 0
    #   br %cond
    # cond:
    #   store 0, %flag
    #   %v = call {Class}.__next__(%it, %flag)
    #   %stop = load i1, %flag
    #   br i1 %stop==0, %body, %end
    # body:
    #   store %v, %var
    #   ... 循环体 ...
    #   br %step
    # step:
    #   br %cond
    # end:
    #
    # __next__ 的隐藏参数 __stop_iter_flag__（i1*）由 ClassGenMixin
    # _translate_method 注入，raise StopIteration 时置 1（translate_raise）；
    # VpiReader stub 声明同步该参数（_inject_method_declare）。
    # ============================================================
    def _handle_oop_iter(self, for_node: ast.For | t.CPtr,
                         var_name: str,
                         class_name: str,
                         obj_val: llvmlite.Value | t.CPtr) -> int:
        """OOP iter 协议: for x in obj: 调用 __iter__/__next__ 迭代"""
        trans: HT.Translator | t.CPtr = self.Trans
        pool: memhub.MemBuddy | t.CPtr = trans.Pool
        builder: llvmlite.IRBuilder | t.CPtr = trans._cur_builder
        func: llvmlite.Function | t.CPtr = trans._cur_func
        mod: llvmlite.LLVMModule | t.CPtr = trans.Module

        if builder is None or func is None or mod is None:
            return 0
        if obj_val is None or obj_val.Ty is None:
            HandlesType.fatal_error(for_node, "OOP 迭代: 迭代源对象类型未知")
        if HandlesExpr.is_ptr_type(obj_val.Ty) == 0:
            HandlesType.fatal_error(for_node, "OOP 迭代: 迭代源对象不是指针类型")

        # 1. 查找 {Class}.__iter__ 并调用，得到迭代器
        iter_lookup: str = pool.alloc(128)
        if iter_lookup is None:
            return 0
        viperlib.snprintf(iter_lookup, 128, "%s.__iter__", class_name)
        iter_fn: llvmlite.Function | t.CPtr = HandlesExprCall.find_func_in_module(
            mod, iter_lookup)
        if iter_fn is None:
            HandlesType.fatal_error(
                for_node, f"OOP 迭代: 类 '{class_name}' 没有 __iter__ 方法")
        iter_ret_ty: llvmlite.LLVMType | t.CPtr = llvmlite.function_get_ret_ty(iter_fn)
        iter_fn_name: str = llvmlite.function_get_name(iter_fn)
        if iter_ret_ty is None or iter_fn_name is None:
            return 0
        # self 参数按 __iter__ 首参类型对齐（stub 声明 self 可能是 i8*）
        iter_self: llvmlite.Value | t.CPtr = obj_val
        iter_first: llvmlite.Param | t.CPtr = llvmlite.function_get_param_head(iter_fn)
        if iter_first is not None:
            iter_self_ty: llvmlite.LLVMType | t.CPtr = llvmlite.param_get_ty(iter_first)
            if iter_self_ty is not None:
                iter_self = llvmlite.build_bitcast(builder, obj_val, iter_self_ty)
        if iter_self is None:
            return 0
        iter_self.Next = None
        iter_result: llvmlite.Value | t.CPtr = llvmlite.build_call(
            builder, iter_fn_name, iter_self, 1, iter_ret_ty, 0)
        if iter_result is None:
            return 0

        # 2. 查找 {Class}.__next__（带隐藏 __stop_iter_flag__ i1* 参数）
        next_lookup: str = pool.alloc(128)
        if next_lookup is None:
            return 0
        viperlib.snprintf(next_lookup, 128, "%s.__next__", class_name)
        next_fn: llvmlite.Function | t.CPtr = HandlesExprCall.find_func_in_module(
            mod, next_lookup)
        if next_fn is None:
            HandlesType.fatal_error(
                for_node, f"OOP 迭代: 类 '{class_name}' 没有 __next__ 方法")
        next_ret_ty: llvmlite.LLVMType | t.CPtr = llvmlite.function_get_ret_ty(next_fn)
        next_fn_name: str = llvmlite.function_get_name(next_fn)
        if next_ret_ty is None or next_fn_name is None:
            return 0

        # 3. 循环变量 alloca（元素类型 = __next__ 返回类型）
        var_alloca: llvmlite.Value | t.CPtr = HandlesVar.lookup_var(
            trans.SymTab, var_name)
        new_vars: int = 0
        if var_alloca is None:
            var_alloca = HandlesVar._alloca_at_entry(builder, next_ret_ty)
            if var_alloca is not None:
                if HandlesVar.define_var(
                        trans.SymTab, var_name, var_alloca) == 0:
                    new_vars = 1

        # 4. stop flag alloca（i1，初始 0）
        i1_ty: llvmlite.LLVMType | t.CPtr = llvmlite.Int1(pool)
        flag_alloca: llvmlite.Value | t.CPtr = llvmlite.build_alloca(builder, i1_ty)
        if flag_alloca is None:
            return 0
        flag_zero: llvmlite.Value | t.CPtr = llvmlite.ConstInt(pool, i1_ty, 0, "0")
        if flag_zero is not None:
            llvmlite.build_store(builder, flag_zero, flag_alloca)

        # 5. 创建基本块: cond / body / step / end
        cnt: int = trans._label_counter
        trans._label_counter = cnt + 1
        name_buf: str = pool.alloc(32)
        viperlib.snprintf(name_buf, 32, "oop.cond.%d", cnt)
        cond_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)
        viperlib.snprintf(name_buf, 32, "oop.body.%d", cnt)
        body_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)
        viperlib.snprintf(name_buf, 32, "oop.step.%d", cnt)
        step_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)
        viperlib.snprintf(name_buf, 32, "oop.end.%d", cnt)
        end_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)
        if cond_bb is None or body_bb is None or step_bb is None or end_bb is None:
            return 0

        llvmlite.build_br(builder, cond_bb)

        # 6. cond 块: 重置 flag → 调 __next__(iter, flag) → 检查 flag 判结束
        llvmlite.position_at_end(builder, cond_bb)
        if flag_zero is not None:
            llvmlite.build_store(builder, flag_zero, flag_alloca)
        # __next__ 参数 1：迭代器（按首参类型 bitcast）
        next_self: llvmlite.Value | t.CPtr = iter_result
        next_first: llvmlite.Param | t.CPtr = llvmlite.function_get_param_head(next_fn)
        if next_first is not None:
            next_self_ty: llvmlite.LLVMType | t.CPtr = llvmlite.param_get_ty(next_first)
            if next_self_ty is not None and iter_result.Ty is not None:
                next_self = llvmlite.build_bitcast(builder, iter_result, next_self_ty)
        if next_self is None:
            return 0
        # 参数链表: arg1(iter).Next = arg2(flag)；flag 独立 null 结尾防自链接
        next_self.Next = flag_alloca
        flag_alloca.Next = None
        next_val: llvmlite.Value | t.CPtr = llvmlite.build_call(
            builder, next_fn_name, next_self, 2, next_ret_ty, 0)
        if next_val is None:
            return 0
        stop_val: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, i1_ty, flag_alloca)
        if stop_val is None:
            return 0
        flag_zero2: llvmlite.Value | t.CPtr = llvmlite.ConstInt(pool, i1_ty, 0, "0")
        continue_i1: llvmlite.Value | t.CPtr = None
        if flag_zero2 is not None:
            continue_i1 = llvmlite.build_icmp(
                builder, llvmlite.ICMP_EQ, stop_val, flag_zero2)
        if continue_i1 is None:
            return 0
        llvmlite.build_cond_br(builder, continue_i1, body_bb, end_bb)

        # 7. body 块: store 元素 → 翻译循环体 → br step
        llvmlite.position_at_end(builder, body_bb)
        if var_alloca is not None:
            llvmlite.build_store(builder, next_val, var_alloca)
        old_break: llvmlite.BasicBlock | t.CPtr = trans._break_bb
        old_continue: llvmlite.BasicBlock | t.CPtr = trans._continue_bb
        trans._break_bb = end_bb
        trans._continue_bb = step_bb
        body: list[ast.AST | t.CPtr] | t.CPtr = for_node.children
        if body is not None:
            body_count: t.CSizeT = len(body)
            for bi in range(body_count):
                stmt: ast.AST | t.CPtr = body.get(bi)
                if stmt is not None:
                    HandlesBody.translate_stmt(trans, stmt)
        trans._break_bb = old_break
        trans._continue_bb = old_continue
        if llvmlite.builder_cur_block_is_terminated(builder) == 0:
            llvmlite.build_br(builder, step_bb)

        # 8. step 块 → cond；定位到 end 块
        llvmlite.position_at_end(builder, step_bb)
        llvmlite.build_br(builder, cond_bb)
        llvmlite.position_at_end(builder, end_bb)
        # 追加90：for 循环正常结束路径 br 到 end_bb → merge 恒可达（需正常收尾）
        trans._ctrl_merge_reachable = 1
        return new_vars

    # ============================================================
    # 多变量迭代（enumerate / zip）
    #
    # 支持迭代源: range(start, stop, step) / 字符串(常量|变量) / list[T]
    # enumerate(x) → for i, v in enumerate(x)：i 为序号，v 为元素
    # zip(a, b)    → for x, y in zip(a, b)：任一源耗尽即终止
    # ============================================================

    def _extract_tuple_names(self, tup: ast.Tuple | t.CPtr,
                             out1: str | t.CPtr, out2: str | t.CPtr) -> int:
        """从 Tuple target 提取前两个 Name 变量名，写入 out1/out2，成功返回 1"""
        if tup is None or tup.elts is None or out1 is None or out2 is None:
            return 0
        elts: list[ast.AST | t.CPtr] | t.CPtr = tup.elts
        n: t.CSizeT = len(elts)
        if n < 2:
            return 0
        e0: ast.AST | t.CPtr = elts.get(0)
        e1: ast.AST | t.CPtr = elts.get(1)
        if e0 is None or e1 is None:
            return 0
        if e0.kind() != ast.ASTKind.Name or e1.kind() != ast.ASTKind.Name:
            return 0
        n0: ast.Name | t.CPtr = (ast.Name | t.CPtr)(e0)
        n1: ast.Name | t.CPtr = (ast.Name | t.CPtr)(e1)
        if n0.id is None or n1.id is None:
            return 0
        string.strcpy(out1, n0.id)
        string.strcpy(out2, n1.id)
        return 1

    def _seq_kind(self, src: ast.AST | t.CPtr) -> int:
        """判断迭代源类型: SEQ_KIND_RANGE / STR / LIST，不支持返回 0"""
        if src is None:
            return 0
        k: int = src.kind()
        if k == ast.ASTKind.Call:
            cl_s: ast.Call | t.CPtr = (ast.Call | t.CPtr)(src)
            fn_s: str = HandlesExpr.get_func_name(cl_s.func)
            if fn_s is not None and string.strcmp(fn_s, "range") == 0:
                return SEQ_KIND_RANGE
            return 0
        if k == ast.ASTKind.Constant:
            cn_s: ast.Constant | t.CPtr = (ast.Constant | t.CPtr)(src)
            if cn_s is not None and cn_s.const_kind == ast.CONST_STR:
                return SEQ_KIND_STR
            return 0
        if k == ast.ASTKind.Name:
            nm_s: ast.Name | t.CPtr = (ast.Name | t.CPtr)(src)
            if nm_s.id is not None and self.Trans is not None:
                ve_s: HandlesVar.VarEntry | t.CPtr = HandlesVar.lookup_var_entry(
                    self.Trans.SymTab, nm_s.id)
                if ve_s is not None and ve_s.AnnotClassName is not None:
                    if string.strstr(ve_s.AnnotClassName, "list") is not None:
                        return SEQ_KIND_LIST
            return SEQ_KIND_STR
        return 0

    def _handle_enumerate_iter(self, for_node: ast.For | t.CPtr,
                               t1: str, t2: str,
                               call: ast.Call | t.CPtr) -> int:
        """enumerate 迭代: for i, v in enumerate(x)"""
        if call is None or call.args is None:
            return 0
        cargs: list[ast.AST | t.CPtr] | t.CPtr = call.args
        if len(cargs) < 1:
            HandlesType.fatal_error(for_node, "enumerate 需要至少一个参数")
        return self._build_seq_loop(for_node, t1, t2, cargs.get(0), None, 1)

    def _handle_zip_iter(self, for_node: ast.For | t.CPtr,
                         t1: str, t2: str,
                         call: ast.Call | t.CPtr) -> int:
        """zip 迭代: for a, b in zip(x, y)"""
        if call is None or call.args is None:
            # fail-fast: zip 参数缺失
            HandlesType.fatal_error(call, "zip 参数缺失", "SyntaxError")
        cargs: list[ast.AST | t.CPtr] | t.CPtr = call.args
        if len(cargs) < 2:
            HandlesType.fatal_error(for_node, "zip 需要至少两个参数")
        return self._build_seq_loop(for_node, t1, t2, cargs.get(0), cargs.get(1), 2)

    def _build_seq_loop(self, for_node: ast.For | t.CPtr,
                        t1: str, t2: str,
                        src1: ast.AST | t.CPtr,
                        src2: ast.AST | t.CPtr,
                        n_srcs: int) -> int:
        """生成序列迭代循环（enumerate: n_srcs=1 / zip: n_srcs=2）

        循环变量 alloca 自动创建或复用；元素类型由源类型决定
        （RANGE→i32, STR→i8, LIST→i8*）。索引内部统一 i64。
        """
        trans: HT.Translator | t.CPtr = self.Trans
        pool: memhub.MemBuddy | t.CPtr = trans.Pool
        builder: llvmlite.IRBuilder | t.CPtr = trans._cur_builder
        func: llvmlite.Function | t.CPtr = trans._cur_func

        i32_ty: llvmlite.LLVMType | t.CPtr = llvmlite.Int32(pool)
        i64_ty: llvmlite.LLVMType | t.CPtr = llvmlite.Int64(pool)
        i8_ty: llvmlite.LLVMType | t.CPtr = llvmlite.Int8(pool)
        i8_ptr_ty: llvmlite.LLVMType | t.CPtr = llvmlite.Ptr(pool, i8_ty)

        # ---- 源 1 准备 ----
        kind1: int = self._seq_kind(src1)
        if kind1 == 0:
            HandlesType.fatal_error(for_node, "序列迭代: 源 1 类型不支持")
        r1_start: llvmlite.Value | t.CPtr = None
        r1_stop: llvmlite.Value | t.CPtr = None
        r1_step: llvmlite.Value | t.CPtr = None
        s1_ptr: llvmlite.Value | t.CPtr = None
        l1_count: llvmlite.Value | t.CPtr = None
        l1_data: llvmlite.Value | t.CPtr = None
        l1_esize: llvmlite.Value | t.CPtr = None
        elem1_ty: llvmlite.LLVMType | t.CPtr = i8_ptr_ty
        if kind1 == SEQ_KIND_RANGE:
            elem1_ty = i32_ty
            r1_start = llvmlite.const_int64(pool, 0)
            r1_step = llvmlite.const_int64(pool, 1)
            r1_stop = llvmlite.const_int64(pool, 0)
            # 先赋中间变量再取 args（cast 链式属性访问会推断错字段偏移）
            call_src1: ast.Call | t.CPtr = (ast.Call | t.CPtr)(src1)
            cargs1: list[ast.AST | t.CPtr] | t.CPtr = call_src1.args
            if cargs1 is not None:
                n1: t.CSizeT = len(cargs1)
                if n1 >= 1:
                    sv: llvmlite.Value | t.CPtr = HandlesExpr.translate_value(
                        builder, pool, trans.Module, cargs1.get(0),
                        trans._funcs, trans._func_count, trans)
                    if sv is None:
                        # fail-fast: range 参数翻译失败
                        HandlesType.fatal_error(cargs1.get(0), "range 参数翻译失败", "TypeError")
                    r1_stop = HandlesExpr.coerce_to_type(builder, sv, i64_ty, cargs1.get(0))
                if n1 >= 2:
                    sv2: llvmlite.Value | t.CPtr = HandlesExpr.translate_value(
                        builder, pool, trans.Module, cargs1.get(1),
                        trans._funcs, trans._func_count, trans)
                    if sv2 is None:
                        # fail-fast: range 参数翻译失败
                        HandlesType.fatal_error(cargs1.get(1), "range 参数翻译失败", "TypeError")
                    r1_start = HandlesExpr.coerce_to_type(builder, sv2, i64_ty, cargs1.get(1))
                if n1 >= 3:
                    sv3: llvmlite.Value | t.CPtr = HandlesExpr.translate_value(
                        builder, pool, trans.Module, cargs1.get(2),
                        trans._funcs, trans._func_count, trans)
                    if sv3 is None:
                        # fail-fast: range 参数翻译失败
                        HandlesType.fatal_error(cargs1.get(2), "range 参数翻译失败", "TypeError")
                    r1_step = HandlesExpr.coerce_to_type(builder, sv3, i64_ty, cargs1.get(2))
        elif kind1 == SEQ_KIND_STR:
            elem1_ty = i8_ty
            s1_ptr = HandlesExpr.translate_value(
                builder, pool, trans.Module, src1,
                trans._funcs, trans._func_count, trans)
            if s1_ptr is None:
                HandlesType.fatal_error(for_node, "序列迭代: 字符串源翻译失败")
        elif kind1 == SEQ_KIND_LIST:
            elem1_ty = i8_ptr_ty
            l1_obj: llvmlite.Value | t.CPtr = HandlesExpr.translate_value(
                builder, pool, trans.Module, src1,
                trans._funcs, trans._func_count, trans)
            if l1_obj is None or l1_obj.Ty is None \
                    or HandlesExpr.is_ptr_type(l1_obj.Ty) == 0:
                HandlesType.fatal_error(for_node, "序列迭代: list 源不是指针类型")
            l1_count = llvmlite.build_load(builder, i64_ty,
                llvmlite.build_gep(builder, i64_ty, l1_obj, llvmlite.const_int64(pool, 1)))
            l1_data = llvmlite.build_load(builder, i8_ptr_ty,
                llvmlite.build_gep(builder, i64_ty, l1_obj, llvmlite.const_int64(pool, 0)))
            l1_esize = llvmlite.build_load(builder, i64_ty,
                llvmlite.build_gep(builder, i64_ty, l1_obj, llvmlite.const_int64(pool, 4)))

        # ---- 源 2 准备（zip）----
        kind2: int = 0
        elem2_ty: llvmlite.LLVMType | t.CPtr = elem1_ty
        s2_ptr: llvmlite.Value | t.CPtr = None
        l2_count: llvmlite.Value | t.CPtr = None
        l2_data: llvmlite.Value | t.CPtr = None
        l2_esize: llvmlite.Value | t.CPtr = None
        r2_start: llvmlite.Value | t.CPtr = None
        r2_stop: llvmlite.Value | t.CPtr = None
        r2_step: llvmlite.Value | t.CPtr = None
        if n_srcs >= 2:
            kind2 = self._seq_kind(src2)
            if kind2 == 0:
                HandlesType.fatal_error(for_node, "序列迭代: 源 2 类型不支持")
            if kind2 == SEQ_KIND_RANGE:
                elem2_ty = i32_ty
                r2_start = llvmlite.const_int64(pool, 0)
                r2_step = llvmlite.const_int64(pool, 1)
                r2_stop = llvmlite.const_int64(pool, 0)
                # 先赋中间变量再取 args（cast 链式属性访问会推断错字段偏移）
                call_src2: ast.Call | t.CPtr = (ast.Call | t.CPtr)(src2)
                cargs2: list[ast.AST | t.CPtr] | t.CPtr = call_src2.args
                if cargs2 is not None:
                    n2: t.CSizeT = len(cargs2)
                    if n2 >= 1:
                        svz: llvmlite.Value | t.CPtr = HandlesExpr.translate_value(
                            builder, pool, trans.Module, cargs2.get(0),
                            trans._funcs, trans._func_count, trans)
                        if svz is None:
                            # fail-fast: range 参数翻译失败
                            HandlesType.fatal_error(cargs2.get(0), "range 参数翻译失败", "TypeError")
                        r2_stop = HandlesExpr.coerce_to_type(builder, svz, i64_ty, cargs2.get(0))
                    if n2 >= 2:
                        svz2: llvmlite.Value | t.CPtr = HandlesExpr.translate_value(
                            builder, pool, trans.Module, cargs2.get(1),
                            trans._funcs, trans._func_count, trans)
                        if svz2 is None:
                            # fail-fast: range 参数翻译失败
                            HandlesType.fatal_error(cargs2.get(1), "range 参数翻译失败", "TypeError")
                        r2_start = HandlesExpr.coerce_to_type(builder, svz2, i64_ty, cargs2.get(1))
                    if n2 >= 3:
                        svz3: llvmlite.Value | t.CPtr = HandlesExpr.translate_value(
                            builder, pool, trans.Module, cargs2.get(2),
                            trans._funcs, trans._func_count, trans)
                        if svz3 is None:
                            # fail-fast: range 参数翻译失败
                            HandlesType.fatal_error(cargs2.get(2), "range 参数翻译失败", "TypeError")
                        r2_step = HandlesExpr.coerce_to_type(builder, svz3, i64_ty, cargs2.get(2))
            elif kind2 == SEQ_KIND_STR:
                elem2_ty = i8_ty
                s2_ptr = HandlesExpr.translate_value(
                    builder, pool, trans.Module, src2,
                    trans._funcs, trans._func_count, trans)
                if s2_ptr is None:
                    HandlesType.fatal_error(for_node, "序列迭代: 字符串源 2 翻译失败")
            elif kind2 == SEQ_KIND_LIST:
                elem2_ty = i8_ptr_ty
                l2_obj: llvmlite.Value | t.CPtr = HandlesExpr.translate_value(
                    builder, pool, trans.Module, src2,
                    trans._funcs, trans._func_count, trans)
                if l2_obj is None or l2_obj.Ty is None \
                        or HandlesExpr.is_ptr_type(l2_obj.Ty) == 0:
                    HandlesType.fatal_error(for_node, "序列迭代: list 源 2 不是指针类型")
                l2_count = llvmlite.build_load(builder, i64_ty,
                    llvmlite.build_gep(builder, i64_ty, l2_obj, llvmlite.const_int64(pool, 1)))
                l2_data = llvmlite.build_load(builder, i8_ptr_ty,
                    llvmlite.build_gep(builder, i64_ty, l2_obj, llvmlite.const_int64(pool, 0)))
                l2_esize = llvmlite.build_load(builder, i64_ty,
                    llvmlite.build_gep(builder, i64_ty, l2_obj, llvmlite.const_int64(pool, 4)))

        # ---- 循环变量 alloca ----
        # t1: enumerate → 序号 (i32)；zip → 源 1 元素
        t1_alloca: llvmlite.Value | t.CPtr = HandlesVar.lookup_var(trans.SymTab, t1)
        new_vars: int = 0
        if t1_alloca is None:
            if n_srcs == 1:
                t1_alloca = HandlesVar._alloca_at_entry(builder, i32_ty)
            else:
                t1_alloca = HandlesVar._alloca_at_entry(builder, elem1_ty)
            if t1_alloca is not None:
                if HandlesVar.define_var(trans.SymTab, t1, t1_alloca) == 0:
                    new_vars += 1
        # t2: 源 2 元素（enumerate 时 = 源 1 元素）
        t2_alloca: llvmlite.Value | t.CPtr = HandlesVar.lookup_var(trans.SymTab, t2)
        if t2_alloca is None:
            t2_alloca = HandlesVar._alloca_at_entry(builder, elem2_ty)
            if t2_alloca is not None:
                if HandlesVar.define_var(trans.SymTab, t2, t2_alloca) == 0:
                    new_vars += 1

        # 隐式 index 变量 (i64)
        idx_alloca: llvmlite.Value | t.CPtr = HandlesVar._alloca_at_entry(builder, i64_ty)
        llvmlite.build_store(builder, llvmlite.const_int64(pool, 0), idx_alloca)

        # 基本块: cond / body / incr / end
        cnt: int = trans._label_counter
        trans._label_counter = cnt + 1

        name_buf: str = pool.alloc(32)
        viperlib.snprintf(name_buf, 32, "seq.cond.%d", cnt)
        cond_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        viperlib.snprintf(name_buf, 32, "seq.body.%d", cnt)
        body_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        viperlib.snprintf(name_buf, 32, "seq.incr.%d", cnt)
        incr_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        viperlib.snprintf(name_buf, 32, "seq.end.%d", cnt)
        end_bb: llvmlite.BasicBlock | t.CPtr = llvmlite.create_block(pool, func, name_buf)

        llvmlite.build_br(builder, cond_bb)

        # cond 块: 源 1 done 检查（zip 需源 2 也 done）
        llvmlite.position_at_end(builder, cond_bb)
        cur_idx: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, i64_ty, idx_alloca)
        done1: llvmlite.Value | t.CPtr = None
        if kind1 == SEQ_KIND_RANGE:
            done1 = llvmlite.build_icmp(builder, llvmlite.ICMP_SLT, cur_idx, r1_stop)
        elif kind1 == SEQ_KIND_STR:
            ch_ptr1: llvmlite.Value | t.CPtr = llvmlite.build_gep(builder, i8_ty, s1_ptr, cur_idx)
            ch1: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, i8_ty, ch_ptr1)
            zero1: llvmlite.Value | t.CPtr = llvmlite.const_int(pool, 8, 0)
            done1 = llvmlite.build_icmp(builder, llvmlite.ICMP_NE, ch1, zero1)
        elif kind1 == SEQ_KIND_LIST:
            done1 = llvmlite.build_icmp(builder, llvmlite.ICMP_SLT, cur_idx, l1_count)
        cont: llvmlite.Value | t.CPtr = done1
        if n_srcs >= 2:
            done2: llvmlite.Value | t.CPtr = None
            if kind2 == SEQ_KIND_RANGE:
                done2 = llvmlite.build_icmp(builder, llvmlite.ICMP_SLT, cur_idx, r2_stop)
            elif kind2 == SEQ_KIND_STR:
                ch_ptr2: llvmlite.Value | t.CPtr = llvmlite.build_gep(builder, i8_ty, s2_ptr, cur_idx)
                ch2: llvmlite.Value | t.CPtr = llvmlite.build_load(builder, i8_ty, ch_ptr2)
                zero2: llvmlite.Value | t.CPtr = llvmlite.const_int(pool, 8, 0)
                done2 = llvmlite.build_icmp(builder, llvmlite.ICMP_NE, ch2, zero2)
            elif kind2 == SEQ_KIND_LIST:
                done2 = llvmlite.build_icmp(builder, llvmlite.ICMP_SLT, cur_idx, l2_count)
            cont = llvmlite.build_and(builder, done1, done2)
        llvmlite.build_cond_br(builder, cont, body_bb, end_bb)

        # body 块: 获取元素 → store → 循环体
        llvmlite.position_at_end(builder, body_bb)
        # 源 1 元素
        v1: llvmlite.Value | t.CPtr = None
        if kind1 == SEQ_KIND_RANGE:
            step1: llvmlite.Value | t.CPtr = llvmlite.build_mul(builder, cur_idx, r1_step)
            v1 = llvmlite.build_add(builder, r1_start, step1)
        elif kind1 == SEQ_KIND_STR:
            ch_ptr1b: llvmlite.Value | t.CPtr = llvmlite.build_gep(builder, i8_ty, s1_ptr, cur_idx)
            v1 = llvmlite.build_load(builder, i8_ty, ch_ptr1b)
        elif kind1 == SEQ_KIND_LIST:
            off1: llvmlite.Value | t.CPtr = llvmlite.build_mul(builder, cur_idx, l1_esize)
            addr1: llvmlite.Value | t.CPtr = llvmlite.build_gep(builder, i8_ty, l1_data, off1)
            v1 = llvmlite.build_load(builder, i8_ptr_ty, addr1)
        # store t1 / t2
        if t1_alloca is not None and t1_alloca.Ty is not None:
            t1_ty: llvmlite.LLVMType | t.CPtr = t1_alloca.Ty.Pointee
            if n_srcs == 1:
                # enumerate: t1 = 序号（trunc i64 → i32）
                idx32: llvmlite.Value | t.CPtr = llvmlite.build_trunc(builder, cur_idx, i32_ty)
                llvmlite.build_store(builder, idx32, t1_alloca)
                if t2_alloca is not None and t2_alloca.Ty is not None and v1 is not None:
                    t2_ty: llvmlite.LLVMType | t.CPtr = t2_alloca.Ty.Pointee
                    v1c: llvmlite.Value | t.CPtr = HandlesExpr.coerce_to_type(builder, v1, t2_ty, src1)
                    llvmlite.build_store(builder, v1c, t2_alloca)
            else:
                if v1 is not None:
                    v1c: llvmlite.Value | t.CPtr = HandlesExpr.coerce_to_type(builder, v1, t1_ty, src1)
                    llvmlite.build_store(builder, v1c, t1_alloca)
                # 源 2 元素 → t2
                v2: llvmlite.Value | t.CPtr = None
                if kind2 == SEQ_KIND_RANGE:
                    step2: llvmlite.Value | t.CPtr = llvmlite.build_mul(builder, cur_idx, r2_step)
                    v2 = llvmlite.build_add(builder, r2_start, step2)
                elif kind2 == SEQ_KIND_STR:
                    ch_ptr2b: llvmlite.Value | t.CPtr = llvmlite.build_gep(builder, i8_ty, s2_ptr, cur_idx)
                    v2 = llvmlite.build_load(builder, i8_ty, ch_ptr2b)
                elif kind2 == SEQ_KIND_LIST:
                    off2: llvmlite.Value | t.CPtr = llvmlite.build_mul(builder, cur_idx, l2_esize)
                    addr2: llvmlite.Value | t.CPtr = llvmlite.build_gep(builder, i8_ty, l2_data, off2)
                    v2 = llvmlite.build_load(builder, i8_ptr_ty, addr2)
                if t2_alloca is not None and t2_alloca.Ty is not None and v2 is not None:
                    t2_ty2: llvmlite.LLVMType | t.CPtr = t2_alloca.Ty.Pointee
                    v2c: llvmlite.Value | t.CPtr = HandlesExpr.coerce_to_type(builder, v2, t2_ty2, src2)
                    llvmlite.build_store(builder, v2c, t2_alloca)

        # 保存旧循环上下文，设置 break/continue 目标
        old_break: llvmlite.BasicBlock | t.CPtr = trans._break_bb
        old_continue: llvmlite.BasicBlock | t.CPtr = trans._continue_bb
        trans._break_bb = end_bb
        trans._continue_bb = incr_bb

        body: list[ast.AST | t.CPtr] | t.CPtr = for_node.children
        if body is not None:
            body_count: t.CSizeT = len(body)
            for bi in range(body_count):
                stmt: ast.AST | t.CPtr = body.get(bi)
                if stmt is not None:
                    HandlesBody.translate_stmt(trans, stmt)

        trans._break_bb = old_break
        trans._continue_bb = old_continue

        if llvmlite.builder_cur_block_is_terminated(builder) == 0:
            llvmlite.build_br(builder, incr_bb)

        # incr 块: index++
        llvmlite.position_at_end(builder, incr_bb)
        one_val: llvmlite.Value | t.CPtr = llvmlite.const_int64(pool, 1)
        next_idx: llvmlite.Value | t.CPtr = llvmlite.build_add(builder, cur_idx, one_val)
        llvmlite.build_store(builder, next_idx, idx_alloca)
        llvmlite.build_br(builder, cond_bb)

        # 定位到 end 块
        llvmlite.position_at_end(builder, end_bb)
        # 追加90：for 循环正常结束路径 br 到 end_bb → merge 恒可达（需正常收尾）
        trans._ctrl_merge_reachable = 1
        return new_vars


# ============================================================
# NewForHandle - 工厂函数（委托到 gen.NewForHandle）
# ============================================================
def NewForHandle(pool: memhub.MemBuddy | t.CPtr,
                 trans: HT.Translator | t.CPtr) -> ForHandle | t.CPtr:
    """创建 ForHandle 实例（委托到 gen.NewForHandle）"""
    import lib.core.Gen.Generator as Generator
    g: Generator.Generator | t.CPtr = (Generator.Generator | t.CPtr)(t.CVoid(_g_gen, t.CPtr))
    if g is not None:
        return g.NewForHandle(pool, trans)
    return None