module types

import v3.flat

const export_c_reserved_words = {
    'auto':     true
    'break':    true
    'case':     true
    'char':     true
    'const':    true
    'continue': true
    'default':  true
    'do':       true
    'double':   true
    'else':     true
    'enum':     true
    'extern':   true
    'float':    true
    'for':      true
    'goto':     true
    'if':       true
    'inline':   true
    'int':      true
    'long':     true
    'register': true
    'restrict': true
    'return':   true
    'short':    true
    'signed':   true
    'sizeof':   true
    'static':   true
    'struct':   true
    'switch':   true
    'typedef':  true
    'union':    true
    'unsigned': true
    'void':     true
    'volatile': true
    'while':    true
}

const export_v3_reserved_c_symbols = {
    'i8':            true
    'i16':           true
    'i32':           true
    'i64':           true
    'u8':            true
    'byte':          true
    'u16':           true
    'u32':           true
    'u64':           true
    'bool':          true
    'voidptr':       true
    'int_literal':   true
    'float_literal': true
    'chan':          true
    'string':        true
    'array':         true
    'Array':         true
    'map':           true
    'mapnode':       true
    'DenseArray':    true
    'SortedMap':     true
    'Optional':      true
    'IError':        true
    'true':          true
    'false':         true
    'elem_size':     true
    'c_name':        true
}

const export_c_libc_collision_symbols = {
    'rint':  true
    'y0':    true
    'y1':    true
    'yn':    true
    'j0':    true
    'j1':    true
    'jn':    true
    'drem':  true
    'scalb': true
}

// tarr1 supports tarr1 handling for types.
fn tarr1(a Type) []Type {
    mut r := []Type{}
    r << a
    return r
}

// tarr2 supports tarr2 handling for types.
fn tarr2(a Type, b Type) []Type {
    mut r := []Type{}
    r << a
    r << b
    return r
}

// tarr3 supports tarr3 handling for types.
fn tarr3(a Type, b Type, c Type) []Type {
    mut r := []Type{}
    r << a
    r << b
    r << c
    return r
}

// unknown_type supports unknown type handling for types.
fn unknown_type(reason string) Type {
    return Type(Unknown{
        reason: reason
    })
}

// TypeError represents type error data used by types.
pub struct TypeError {
pub:
    msg  string
    kind TypeErrorKind
    node flat.NodeId
}

// TypeErrorKind lists type error kind values used by types.
pub enum TypeErrorKind {
    unknown_ident
    unknown_type
    unknown_fn
    unknown_field
    cannot_index
    if_branch_mismatch
    assignment_mismatch
    return_mismatch
    call_arg_mismatch
    condition_mismatch
    unhandled_node
    unsupported_generic
}

// CallInfo stores call info metadata used by types.
pub struct CallInfo {
pub:
    name                 string
    params               []Type
    return_type          Type
    has_receiver         bool
    is_variadic          bool
    is_c_variadic        bool
    params_known         bool
    has_implicit_veb_ctx bool
}

// LocalBinding represents local binding data used by types.
struct LocalBinding {
    name string
    typ  Type
}

// TypeCache represents type cache data used by types.
struct TypeCache {
mut:
    parse_enabled bool
    parse_entries map[string]Type
    c_entries     map[string]string
}

// TypeChecker represents type checker data used by types.
@[heap]
pub struct TypeChecker {
pub mut:
    a                      &flat.FlatAst = unsafe { nil }
    fn_ret_types           map[string]Type
    fn_param_types         map[string][]Type
    fn_ret_type_texts      map[string]string   // generic struct method key -> original return type text (e.g. `Box[T].clone` -> `Box[T]`)
    fn_param_type_texts    map[string][]string // generic struct method key -> original param type texts (receiver first)
    fn_type_files          map[string]string
    fn_type_modules        map[string]string
    fn_generic_params      map[string][]string
    fn_variadic            map[string]bool
    c_variadic_fns         map[string]bool
    fn_implicit_veb_ctx    map[string]bool
    structs                map[string][]StructField
    struct_generic_params  map[string][]string // generic struct base name -> type-param names (e.g. Vec4 -> [T])
    struct_field_c_abi_fns map[string]string
    // concrete `Box[int].method` -> substituted CallInfo for a method *value* on a
    // generic receiver. The open `Box[T].method` registration is gone by cgen time, so
    // the checker stashes the resolved signature here for gen_method_value_closure.
    generic_method_value_info  map[string]CallInfo
    params_structs             map[string]bool
    unions                     map[string]bool
    type_aliases               map[string]string
    type_alias_c_abi_fns       map[string]string
    sum_types                  map[string][]string
    enum_names                 map[string]bool
    enum_fields                map[string][]string
    flag_enums                 map[string]bool
    interface_names            map[string]bool
    interface_fields           map[string][]StructField
    interface_embeds           map[string][]string
    interface_abstract_methods map[string][]string // iface -> abstract (declared) method names

    c_globals               map[string]Type
    const_types             map[string]Type
    const_exprs             map[string]flat.NodeId
    const_modules           map[string]string
    const_files             map[string]string
    const_suffixes          map[string]string // dot-suffix -> full const key (O(1) lookup; '' if ambiguous)
    imports                 map[string]string // alias -> short module name
    file_imports            map[string]string
    file_selective_imports  map[string][]string
    file_modules            map[string]string
    file_scope              &Scope = unsafe { nil }
    cur_scope               &Scope = unsafe { nil }
    scope_pool              []&Scope
    scope_pool_index        int
    has_builtins            bool
    cur_module              string
    cur_file                string
    errors                  []TypeError
    resolved_call_names     []string // node_id -> resolved function name
    resolved_call_set       []bool
    resolved_fn_value_names []string // node_id -> resolved function value name
    resolved_fn_value_set   []bool
    statement_nodes         []bool
    // Methods used as *values* (`recv.method` passed as a callback), recorded per enclosing
    // function during semantic checking — which has full scope/type info, runs before
    // markused, and (unlike a call) routes a value-context selector through check_selector.
    // markused seeds these (keeping the wrapper-only method out of the dead-code pruner)
    // only when their enclosing function is reachable.
    method_values_by_fn map[int][]string // enclosing fn node id -> method-value `Type.method` keys
    // Local variables bound to a method value (`cb := c.report`) in the current function.
    // Such an alias shares the same per-site static receiver slot as the bare selector, so it
    // escapes (and corrupts other live callbacks) just like `return c.report`; the escape
    // checks below treat a reference to one of these locals as a method value. Reset per fn.
    method_value_locals map[string]bool
    // Scope depth at which each method-value local was marked, so a reassignment to a
    // non-method value only clears the marker when it dominates later uses (same-or-shallower
    // scope); a reassignment in a deeper conditional/loop scope keeps the maybe-method marker.
    method_value_local_depth      map[string]int
    cur_fn_node_id                int = -1
    expr_type_values              []Type // node_id -> complex/contextual resolved type
    expr_type_set                 []bool
    checking_nodes                []bool
    diagnose_unknown_calls        bool
    reject_unlowered_map_mutation bool
    reject_unsupported_generics   bool
    diagnostic_files              map[string]bool
    cur_fn_ret_type               Type = Type(void_)
    smartcasts                    map[string]Type
    selfhost                      bool
mut:
    type_cache &TypeCache = unsafe { nil }
}

// new creates a TypeChecker value for types.
pub fn TypeChecker.new(a &flat.FlatAst) TypeChecker {
    fs := new_scope(unsafe { nil })
    return TypeChecker{
        a:                          a
        fn_ret_types:               map[string]Type{}
        fn_param_types:             map[string][]Type{}
        fn_ret_type_texts:          map[string]string{}
        fn_param_type_texts:        map[string][]string{}
        fn_type_files:              map[string]string{}
        fn_type_modules:            map[string]string{}
        fn_generic_params:          map[string][]string{}
        fn_variadic:                map[string]bool{}
        c_variadic_fns:             map[string]bool{}
        fn_implicit_veb_ctx:        map[string]bool{}
        structs:                    map[string][]StructField{}
        struct_generic_params:      map[string][]string{}
        struct_field_c_abi_fns:     map[string]string{}
        generic_method_value_info:  map[string]CallInfo{}
        params_structs:             map[string]bool{}
        unions:                     map[string]bool{}
        type_aliases:               map[string]string{}
        type_alias_c_abi_fns:       map[string]string{}
        sum_types:                  map[string][]string{}
        enum_names:                 map[string]bool{}
        enum_fields:                map[string][]string{}
        flag_enums:                 map[string]bool{}
        interface_names:            map[string]bool{}
        interface_fields:           map[string][]StructField{}
        interface_embeds:           map[string][]string{}
        interface_abstract_methods: map[string][]string{}
        c_globals:                  map[string]Type{}
        const_types:                map[string]Type{}
        const_exprs:                map[string]flat.NodeId{}
        const_modules:              map[string]string{}
        const_files:                map[string]string{}
        const_suffixes:             map[string]string{}
        imports:                    map[string]string{}
        file_imports:               map[string]string{}
        file_selective_imports:     map[string][]string{}
        file_modules:               map[string]string{}
        file_scope:                 fs
        cur_scope:                  fs
        resolved_call_names:        []string{len: a.nodes.len}
        resolved_call_set:          []bool{len: a.nodes.len}
        resolved_fn_value_names:    []string{len: a.nodes.len}
        resolved_fn_value_set:      []bool{len: a.nodes.len}
        statement_nodes:            []bool{len: a.nodes.len}
        method_values_by_fn:        map[int][]string{}
        method_value_locals:        map[string]bool{}
        method_value_local_depth:   map[string]int{}
        expr_type_values:           []Type{len: a.nodes.len, init: Type(void_)}
        expr_type_set:              []bool{len: a.nodes.len}
        checking_nodes:             []bool{len: a.nodes.len}
        diagnostic_files:           map[string]bool{}
        smartcasts:                 map[string]Type{}
        type_cache:                 &TypeCache{
            parse_entries: map[string]Type{}
            c_entries:     map[string]string{}
        }
    }
}

// fork_for_parallel_transform returns a TypeChecker that shares all of `tc`'s
// read-only data (semantic maps and node-indexed cache arrays, which the transform
// pass only reads) but owns a fresh, private `type_cache` and a private AST view.
// During transform the only hidden mutation a TypeChecker performs through its `&`
// receiver is memoization into `type_cache` (parse_type / c_type); giving each
// worker its own cache makes concurrent use race-free without cloning the large
// semantic maps. `ast` must be the worker's own (cloned) FlatAst so that any
// expr_type lookup on a freshly-created node id indexes a valid array.
pub fn (tc &TypeChecker) fork_for_parallel_transform(ast &flat.FlatAst) &TypeChecker {
    mut forked := *tc
    forked.a = ast
    forked.type_cache = &TypeCache{
        parse_enabled: if tc.type_cache != unsafe { nil } {
            tc.type_cache.parse_enabled
        } else {
            false
        }
        parse_entries: map[string]Type{}
        c_entries:     map[string]string{}
    }
    return &forked
}

// reset_node_caches updates reset node caches state for types.
fn (mut tc TypeChecker) reset_node_caches(n int) {
    tc.resolved_call_names = []string{len: n}
    tc.resolved_call_set = []bool{len: n}
    tc.resolved_fn_value_names = []string{len: n}
    tc.resolved_fn_value_set = []bool{len: n}
    tc.statement_nodes = []bool{len: n}
    tc.expr_type_values = []Type{len: n, init: Type(void_)}
    tc.expr_type_set = []bool{len: n}
    tc.checking_nodes = []bool{len: n}
}

fn (mut tc TypeChecker) extend_node_caches(n int) {
    if n <= tc.resolved_call_names.len && n <= tc.resolved_fn_value_names.len
        && n <= tc.statement_nodes.len && n <= tc.expr_type_values.len && n <= tc.checking_nodes.len {
        return
    }
    extend_string_cache(mut tc.resolved_call_names, n)
    extend_bool_cache(mut tc.resolved_call_set, n)
    extend_string_cache(mut tc.resolved_fn_value_names, n)
    extend_bool_cache(mut tc.resolved_fn_value_set, n)
    extend_bool_cache(mut tc.statement_nodes, n)
    extend_type_cache(mut tc.expr_type_values, n)
    extend_bool_cache(mut tc.expr_type_set, n)
    extend_bool_cache(mut tc.checking_nodes, n)
}

fn extend_string_cache(mut values []string, n int) {
    if n > values.len {
        values << []string{len: n - values.len}
    }
}

fn extend_bool_cache(mut values []bool, n int) {
    if n > values.len {
        values << []bool{len: n - values.len}
    }
}

fn extend_type_cache(mut values []Type, n int) {
    if n > values.len {
        values << []Type{len: n - values.len, init: Type(void_)}
    }
}

// push_scope updates push scope state for TypeChecker.
pub fn (mut tc TypeChecker) push_scope() {
    tc.cur_scope = tc.reuse_scope(tc.cur_scope)
}

// pop_scope updates pop scope state for TypeChecker.
pub fn (mut tc TypeChecker) pop_scope() {
    if tc.cur_scope == unsafe { nil } {
        return
    }
    parent := tc.cur_scope.parent
    if parent == unsafe { nil } {
        return
    }
    if tc.scope_pool_index > 0 && tc.cur_scope == tc.scope_pool[tc.scope_pool_index - 1] {
        tc.scope_pool_index--
    }
    tc.cur_scope = parent
}

// reuse_scope supports reuse scope handling for TypeChecker.
fn (mut tc TypeChecker) reuse_scope(parent &Scope) &Scope {
    if tc.scope_pool_index < tc.scope_pool.len {
        mut scope := tc.scope_pool[tc.scope_pool_index]
        scope.reset(parent)
        tc.scope_pool_index++
        return scope
    }
    scope := new_scope(parent)
    tc.scope_pool << scope
    tc.scope_pool_index++
    return scope
}

// record_error supports record error handling for TypeChecker.
fn (mut tc TypeChecker) record_error(kind TypeErrorKind, msg string, node flat.NodeId) {
    if !tc.should_diagnose(node) {
        return
    }
    tc.errors << TypeError{
        msg:  msg
        kind: kind
        node: node
    }
}

fn (mut tc TypeChecker) record_error_unfiltered(kind TypeErrorKind, msg string, node flat.NodeId) {
    tc.errors << TypeError{
        msg:  msg
        kind: kind
        node: node
    }
}

fn (mut tc TypeChecker) record_unsupported_generic(msg string, node flat.NodeId) {
    if !tc.should_diagnose_unsupported_generic(node) {
        return
    }
    tc.errors << TypeError{
        msg:  msg
        kind: .unsupported_generic
        node: node
    }
}

// collect supports collect handling for TypeChecker.
pub fn (mut tc TypeChecker) collect(a &flat.FlatAst) {
    tc.a = a
    tc.file_scope = new_scope(unsafe { nil })
    tc.cur_scope = tc.file_scope
    tc.scope_pool_index = 0
    tc.reset_node_caches(a.nodes.len)
    tc.type_cache = &TypeCache{
        parse_entries: map[string]Type{}
        c_entries:     map[string]string{}
    }
    for node in a.nodes {
        if node.kind == .struct_decl && node.value == 'string' {
            tc.has_builtins = true
            break
        }
    }
    // Pass 1: collect type-level names (aliases, enums, sum types)
    for node in a.nodes {
        match node.kind {
            .file {
                tc.enter_file(node.value)
            }
            .module_decl {
                tc.enter_module(node.value)
            }
            .import_decl {
                tc.imports[node.typ] = node.value
                tc.file_imports[file_import_key(tc.cur_file, node.typ)] = node.value
                tc.register_selective_imports(node)
            }
            .enum_decl {
                qn := tc.qualify_name(node.value)
                tc.enum_names[qn] = true
                mut fields := []string{}
                for i in 0 .. node.children_count {
                    f := a.child_node(&node, i)
                    if f.kind == .enum_field {
                        fields << f.value
                    }
                }
                tc.enum_fields[qn] = fields
                if node.typ == 'flag' {
                    tc.flag_enums[qn] = true
                }
            }
            .struct_decl {
                qname := tc.qualify_name(node.value)
                if qname !in tc.structs {
                    tc.structs[qname] = []StructField{}
                }
                if node.generic_params.len > 0 {
                    tc.struct_generic_params[qname] = node.generic_params.clone()
                    if qname != node.value {
                        tc.struct_generic_params[node.value] = node.generic_params.clone()
                    }
                }
                if node.typ.contains('union') {
                    tc.unions[qname] = true
                }
                if node.typ.contains('params') {
                    tc.params_structs[qname] = true
                }
            }
            .type_decl {
                if node.children_count > 0 {
                    mut variants := []string{}
                    for i in 0 .. node.children_count {
                        v := a.child_node(&node, i)
                        variants << tc.qualify_name(v.value)
                    }
                    tc.sum_types[tc.qualify_name(node.value)] = variants
                } else if node.typ.len > 0 {
                    qname := tc.qualify_name(node.value)
                    tc.type_aliases[qname] = tc.qualify_type_text(node.typ)
                    if c_abi_fn := tc.c_abi_fn_ptr_type_from_text(node.typ) {
                        tc.type_alias_c_abi_fns[qname] = c_abi_fn
                    }
                    if tc.cur_module in ['', 'main', 'builtin'] && node.value !in tc.type_aliases {
                        tc.type_aliases[node.value] = tc.qualify_type_text(node.typ)
                        if c_abi_fn := tc.c_abi_fn_ptr_type_from_text(node.typ) {
                            tc.type_alias_c_abi_fns[node.value] = c_abi_fn
                        }
                    }
                }
            }
            .interface_decl {
                tc.interface_names[tc.qualify_name(node.value)] = true
            }
            else {}
        }
    }
    // Pass 2: collect struct fields, function signatures (type aliases now available)
    tc.type_cache.parse_enabled = true
    tc.cur_module = ''
    for node in a.nodes {
        match node.kind {
            .file {
                tc.enter_file(node.value)
            }
            .module_decl {
                tc.enter_module(node.value)
            }
            .fn_decl {
                qname := tc.qualify_fn_name(node.value)
                ret_type := tc.parse_type(node.typ)
                mut ptypes := []Type{}
                mut param_texts := []string{}
                mut is_variadic := false
                for i in 0 .. node.children_count {
                    child := a.child_node(&node, i)
                    if child.kind == .param {
                        if child.typ.starts_with('...') {
                            is_variadic = true
                        }
                        ptypes << tc.parse_type(child.typ)
                        param_texts << child.typ
                    }
                }
                needs_ctx := tc.fn_needs_implicit_veb_ctx(node)
                ptypes = tc.fn_param_types_with_implicit_veb_ctx(node, ptypes)
                tc.register_fn_signature(qname, ret_type, ptypes, is_variadic, needs_ctx)
                if tc.cur_module in ['', 'main', 'builtin'] && qname != node.value
                    && node.value !in tc.fn_param_types {
                    tc.register_fn_signature(node.value, ret_type, ptypes, is_variadic, needs_ctx)
                }
                // A generic struct method (`Box[T].clone`) keeps its original signature
                // TEXT: the parsed types collapse a non-concrete `Box[T]` to the bare base,
                // so a concrete call must re-substitute the type arguments from the text to
                // recover applications like the receiver type in the return position
                // (`Box[T]` -> `Box[int]`). Only such methods carry `[` in their key.
                if node.generic_params.len > 0 || node.value.contains('[') {
                    for name in [qname, node.value] {
                        tc.fn_ret_type_texts[name] = node.typ
                        tc.fn_param_type_texts[name] = param_texts.clone()
                        tc.fn_type_files[name] = tc.cur_file
                        tc.fn_type_modules[name] = tc.cur_module
                        if node.generic_params.len > 0 {
                            tc.fn_generic_params[name] = node.generic_params.clone()
                        }
                    }
                }
            }
            .struct_decl {
                mut fields := []StructField{}
                mut field_c_abi_fns := map[string]string{}
                for i in 0 .. node.children_count {
                    f := a.child_node(&node, i)
                    if f.kind != .field_decl {
                        continue
                    }
                    field_typ := if f.typ.len > 0 { f.typ } else { f.value }
                    mut typ := tc.parse_type(field_typ)
                    if f.value == field_typ {
                        typ = tc.resolve_known_field_type(field_typ, typ)
                    }
                    if c_abi_fn := tc.c_abi_fn_ptr_type_for_type_text(field_typ) {
                        field_c_abi_fns[f.value] = c_abi_fn
                    }
                    fields << StructField{
                        name: f.value
                        typ:  typ
                    }
                }
                qname := tc.qualify_name(node.value)
                tc.structs[qname] = fields
                for field_name, c_abi_fn in field_c_abi_fns {
                    tc.struct_field_c_abi_fns[struct_field_c_abi_key(qname, field_name)] = c_abi_fn
                }
                if node.typ.contains('union') {
                    tc.unions[qname] = true
                }
                if node.typ.contains('params') {
                    tc.params_structs[qname] = true
                }
            }
            .c_fn_decl {
                ret_type := tc.parse_type(node.typ)
                mut ptypes := []Type{}
                mut is_variadic := false
                for i in 0 .. node.children_count {
                    child := a.child_node(&node, i)
                    if child.kind == .param {
                        if child.typ.starts_with('...') {
                            is_variadic = true
                        }
                        ptypes << tc.parse_type(child.typ)
                    }
                }
                tc.register_fn_signature(node.value, ret_type, ptypes, is_variadic, false)
                if is_variadic {
                    tc.register_c_variadic_fn(node.value)
                }
                if !node.value.starts_with('C.') {
                    tc.register_fn_signature('C.${node.value}', ret_type, ptypes, is_variadic,
                        false)
                    if is_variadic {
                        tc.register_c_variadic_fn('C.${node.value}')
                    }
                }
            }
            .interface_decl {
                iface_name := tc.qualify_name(node.value)
                for i in 0 .. node.children_count {
                    f := a.child_node(&node, i)
                    if f.kind != .interface_field {
                        continue
                    }
                    if f.op == .dot {
                        mname := '${iface_name}.${f.value}'
                        mut absm := tc.interface_abstract_methods[iface_name] or { []string{} }
                        absm << f.value
                        tc.interface_abstract_methods[iface_name] = absm
                        tc.fn_ret_types[mname] = tc.parse_type(f.typ)
                        mut ptypes := []Type{}
                        mut is_variadic := false
                        ptypes << Type(Pointer{
                            base_type: Type(Interface{
                                name: iface_name
                            })
                        })
                        for j in 0 .. f.children_count {
                            child := a.child_node(f, j)
                            if child.kind == .param {
                                if child.typ.starts_with('...') {
                                    is_variadic = true
                                }
                                ptypes << tc.parse_type(child.typ)
                            }
                        }
                        tc.fn_param_types[mname] = ptypes
                        tc.fn_variadic[mname] = is_variadic
                    } else if f.typ.len > 0 {
                        mut fields := tc.interface_fields[iface_name] or { []StructField{} }
                        fields << StructField{
                            name: f.value
                            typ:  tc.parse_type(f.typ)
                        }
                        tc.interface_fields[iface_name] = fields
                    } else if f.value.len > 0 {
                        mut embeds := tc.interface_embeds[iface_name] or { []string{} }
                        embeds << tc.qualify_name(f.value)
                        tc.interface_embeds[iface_name] = embeds
                    }
                }
            }
            .global_decl {
                for i in 0 .. node.children_count {
                    f := a.child_node(&node, i)
                    if f.value.len > 0 && f.value.starts_with('C.') {
                        tc.c_globals[f.value] = tc.parse_type(f.typ)
                    } else if f.value.len > 0 {
                        mut ft := tc.parse_type(f.typ)
                        if ft is Void && f.children_count > 0 {
                            ft = tc.resolve_type(a.child(f, 0))
                        }
                        qname := tc.qualify_name(f.value)
                        tc.file_scope.insert(qname, ft)
                    }
                }
            }
            .const_decl {
                for i in 0 .. node.children_count {
                    f := a.child_node(&node, i)
                    if f.kind == .const_field && f.children_count > 0 {
                        qname := tc.qualify_name(f.value)
                        tc.const_types[qname] = unknown_type('pending const `${qname}`')
                        tc.const_exprs[qname] = a.child(f, 0)
                        tc.const_modules[qname] = tc.cur_module
                        tc.const_files[qname] = tc.cur_file
                    } else if f.kind == .const_field && f.typ.len > 0 {
                        qname := tc.qualify_name(f.value)
                        tc.const_types[qname] = tc.parse_type(f.typ)
                        tc.const_modules[qname] = tc.cur_module
                        tc.const_files[qname] = tc.cur_file
                    }
                }
            }
            else {}
        }
    }
    tc.resolve_const_types()
    tc.build_const_suffixes()
}

// build_const_suffixes maps every dot-delimited suffix of each const key to that
// key, so qualified const lookups resolve in O(1) instead of scanning all consts
// (with per-iteration string building) on every selector/ident in module code.
fn (mut tc TypeChecker) build_const_suffixes() {
    for key, _ in tc.const_types {
        mut i := 0
        for i < key.len {
            if key[i] == `.` {
                suffix := key[i + 1..]
                if existing := tc.const_suffixes[suffix] {
                    if existing != key {
                        tc.const_suffixes[suffix] = ''
                    }
                } else {
                    tc.const_suffixes[suffix] = key
                }
            }
            i++
        }
    }
}

// const_key_for_suffix returns the const key matching `.${name}` as a suffix,
// equivalent to scanning const_types for `key.ends_with('.' + name)` but O(1).
fn (tc &TypeChecker) const_key_for_suffix(name string) ?string {
    if key := tc.const_suffixes[name] {
        if key.len > 0 {
            return key
        }
    }
    return none
}

// resolve_const_types resolves resolve const types information for types.
fn (mut tc TypeChecker) resolve_const_types() {
    if tc.const_exprs.len == 0 {
        return
    }
    saved_module := tc.cur_module
    saved_file := tc.cur_file
    for _ in 0 .. tc.const_exprs.len {
        mut changed := false
        for name, expr_id in tc.const_exprs {
            tc.cur_module = tc.const_modules[name] or { '' }
            tc.cur_file = tc.const_files[name] or { '' }
            mut new_type := tc.resolve_type(expr_id)
            new_type = tc.const_type_from_initializer(name, new_type)
            if new_type is Unknown {
                continue
            }
            expr := tc.a.nodes[int(expr_id)]
            if new_type is ArrayFixed && expr.kind == .call {
                new_type = Type(Array{
                    elem_type: new_type.elem_type
                })
            }
            old_type := tc.const_types[name] or { Type(void_) }
            if old_type.name() != new_type.name() {
                tc.const_types[name] = new_type
                changed = true
            }
        }
        if !changed {
            break
        }
    }
    tc.cur_module = saved_module
    tc.cur_file = saved_file
}

// const_type_from_initializer converts const type from initializer data for types.
fn (tc &TypeChecker) const_type_from_initializer(name string, typ Type) Type {
    if typ !is Unknown {
        return typ
    }
    expr_id := tc.const_exprs[name] or { return typ }
    if int(expr_id) < 0 || int(expr_id) >= tc.a.nodes.len {
        return typ
    }
    expr := tc.a.nodes[int(expr_id)]
    if expr.kind != .call || expr.children_count == 0 {
        return typ
    }
    fn_node := tc.a.child_node(&expr, 0)
    if fn_node.kind != .ident || fn_node.value.len == 0 {
        return typ
    }
    mod_name := tc.const_modules[name] or { '' }
    mut candidates := []string{}
    if mod_name.len > 0 && mod_name != 'main' && mod_name != 'builtin' {
        candidates << '${mod_name}.${fn_node.value}'
    }
    candidates << fn_node.value
    candidates << c_name(fn_node.value)
    for candidate in candidates {
        if ret := tc.fn_ret_types[candidate] {
            return ret
        }
    }
    if fn_node.value == 'new_keywords_matcher_trie' {
        type_name := if mod_name.len > 0 && mod_name != 'main' && mod_name != 'builtin' {
            '${mod_name}.KeywordsMatcherTrie'
        } else {
            'KeywordsMatcherTrie'
        }
        return Type(Struct{
            name: type_name
        })
    }
    return typ
}

fn (tc &TypeChecker) const_type_for_name(name string) ?Type {
    qname := tc.qualify_name(name)
    if typ := tc.const_types[qname] {
        return tc.const_type_from_initializer(qname, typ)
    }
    if typ := tc.const_types[name] {
        return tc.const_type_from_initializer(name, typ)
    }
    return none
}

fn (tc &TypeChecker) const_type_for_selector(node flat.Node) ?Type {
    if node.kind != .selector || node.children_count == 0 {
        return none
    }
    base_node := tc.a.child_node(&node, 0)
    if base_node.kind != .ident {
        return none
    }
    resolved := tc.resolve_import_alias(base_node.value) or { base_node.value }
    qname := '${resolved}.${node.value}'
    if typ := tc.const_types[qname] {
        return tc.const_type_from_initializer(qname, typ)
    }
    if key := tc.const_key_for_suffix(qname) {
        typ := tc.const_types[key] or { unknown_type('unknown const `${key}`') }
        return tc.const_type_from_initializer(key, typ)
    }
    return none
}

// qualify_fn_name supports qualify fn name handling for TypeChecker.
pub fn (tc &TypeChecker) qualify_fn_name(name string) string {
    if tc.cur_module.len == 0 || tc.cur_module == 'main' || tc.cur_module == 'builtin' {
        return name
    }
    return '${tc.cur_module}.${name}'
}

// qualify_name supports qualify name handling for TypeChecker.
pub fn (tc &TypeChecker) qualify_name(name string) string {
    if tc.cur_module.len == 0 || tc.cur_module == 'main' || tc.cur_module == 'builtin' {
        return name
    }
    if name.starts_with('[]') {
        return '[]' + tc.qualify_name(name[2..])
    }
    if name.starts_with('[') {
        idx := name.index_u8(`]`)
        if idx > 0 {
            return name[..idx + 1] + tc.qualify_name(name[idx + 1..])
        }
    }
    if name.starts_with('map[') {
        bracket_end := find_matching_bracket(name, 3)
        key_str := name[4..bracket_end]
        val_str := name[bracket_end + 1..]
        return 'map[${tc.qualify_name(key_str)}]${tc.qualify_name(val_str)}'
    }
    if name.starts_with('&') {
        return '&' + tc.qualify_name(name[1..])
    }
    if name.starts_with('?') {
        return '?' + tc.qualify_name(name[1..])
    }
    if name.starts_with('!') {
        return '!' + tc.qualify_name(name[1..])
    }
    if name.contains('.') {
        return tc.resolve_imported_type_text(name)
    }
    if is_builtin_type_name(name) {
        return name
    }
    return tc.cur_module + '.' + name
}

// qualify_type_text supports qualify type text handling for TypeChecker.
fn (tc &TypeChecker) qualify_type_text(typ string) string {
    clean := typ.trim_space()
    if clean.len == 0 {
        return typ
    }
    if clean.starts_with('&') {
        return '&' + tc.qualify_type_text(clean[1..])
    }
    if clean.starts_with('mut ') {
        inner := tc.qualify_type_text(clean[4..])
        if inner.starts_with('&') {
            return inner
        }
        return '&' + inner
    }
    if clean.starts_with('shared ') {
        return 'shared ' + tc.qualify_type_text(clean[7..])
    }
    if clean.starts_with('atomic ') {
        return 'atomic ' + tc.qualify_type_text(clean[7..])
    }
    if clean.starts_with('?') {
        return '?' + tc.qualify_type_text(clean[1..])
    }
    if clean.starts_with('!') {
        return '!' + tc.qualify_type_text(clean[1..])
    }
    if clean.starts_with('...') {
        return '...' + tc.qualify_type_text(clean[3..])
    }
    if clean.starts_with('[]') {
        return '[]' + tc.qualify_type_text(clean[2..])
    }
    if clean.starts_with('map[') {
        bracket_end := find_matching_bracket(clean, 3)
        if bracket_end < clean.len {
            key := tc.qualify_type_text(clean[4..bracket_end])
            val := tc.qualify_type_text(clean[bracket_end + 1..])
            return 'map[${key}]${val}'
        }
    }
    if clean.starts_with('[') {
        bracket_end := find_matching_bracket(clean, 0)
        if bracket_end < clean.len {
            return clean[..bracket_end + 1] + tc.qualify_type_text(clean[bracket_end + 1..])
        }
    }
    if clean.starts_with('(') && clean.ends_with(')') && clean.contains(',') {
        mut parts := []string{}
        for part in split_params(clean[1..clean.len - 1]) {
            parts << tc.qualify_type_text(part)
        }
        return '(' + parts.join(', ') + ')'
    }
    if clean.starts_with('fn(') || clean.starts_with('fn (') {
        return tc.qualify_fn_type_text(clean)
    }
    bracket := clean.index_u8(`[`)
    if bracket > 0 {
        bracket_end := find_matching_bracket(clean, bracket)
        if bracket_end < clean.len {
            mut parts := []string{}
            for part in split_params(clean[bracket + 1..bracket_end]) {
                parts << tc.qualify_type_text(part)
            }
            return tc.qualify_name(clean[..bracket]) + '[' + parts.join(', ') + ']' +
                clean[bracket_end + 1..]
        }
    }
    return tc.qualify_name(clean)
}

// qualify_fn_type_text supports qualify fn type text handling for TypeChecker.
fn (tc &TypeChecker) qualify_fn_type_text(typ string) string {
    params_start := typ.index_u8(`(`) + 1
    mut depth := 1
    mut params_end := params_start
    for params_end < typ.len {
        if typ[params_end] == `(` {
            depth++
        } else if typ[params_end] == `)` {
            depth--
            if depth == 0 {
                break
            }
        }
        params_end++
    }
    params_str := typ[params_start..params_end]
    mut params := []string{}
    if params_str.trim_space().len > 0 {
        for part in split_params(params_str) {
            params << tc.qualify_type_text(normalize_fn_type_param_text(part))
        }
    }
    ret_str := typ[params_end + 1..].trim_space()
    if ret_str.len > 0 {
        return 'fn(${params.join(', ')}) ${tc.qualify_type_text(ret_str)}'
    }
    return 'fn(${params.join(', ')})'
}

// file_import_key supports file import key handling for types.
fn file_import_key(file string, alias string) string {
    return '${file}\n${alias}'
}

// enter_file supports enter file handling for TypeChecker.
fn (mut tc TypeChecker) enter_file(file string) {
    tc.cur_file = file
    tc.cur_module = tc.file_modules[file] or { '' }
}

// enter_module supports enter module handling for TypeChecker.
fn (mut tc TypeChecker) enter_module(name string) {
    tc.cur_module = name
    if tc.cur_file.len > 0 {
        tc.file_modules[tc.cur_file] = name
    }
}

fn (mut tc TypeChecker) register_selective_imports(node flat.Node) {
    if node.children_count == 0 {
        return
    }
    for i in 0 .. node.children_count {
        child_id := tc.a.child(&node, i)
        child := tc.a.nodes[int(child_id)]
        if child.kind != .ident {
            continue
        }
        key := file_import_key(tc.cur_file, child.value)
        if key in tc.file_selective_imports {
            tc.file_selective_imports[key] = []string{}
            tc.record_error_unfiltered(.unknown_fn, 'ambiguous selective import `${child.value}`',
                child_id)
            continue
        }
        mut candidates := []string{}
        path_name := '${node.value}.${child.value}'
        if path_name !in candidates {
            candidates << path_name
        }
        alias_name := '${node.typ}.${child.value}'
        if alias_name != path_name && alias_name !in candidates {
            candidates << alias_name
        }
        tc.file_selective_imports[key] = candidates
    }
}

// resolve_import_alias resolves resolve import alias information for types.
fn (tc &TypeChecker) resolve_import_alias(alias string) ?string {
    if mod := tc.file_imports[file_import_key(tc.cur_file, alias)] {
        return mod
    }
    return none
}

fn (tc &TypeChecker) resolve_selective_import_symbol(name string) ?string {
    candidates := tc.file_selective_imports[file_import_key(tc.cur_file, name)] or { return none }
    for candidate in candidates {
        if tc.fn_signature_known(candidate) {
            return candidate
        }
    }
    return none
}

fn (tc &TypeChecker) resolve_selective_import_type_symbol(name string) ?string {
    candidates := tc.file_selective_imports[file_import_key(tc.cur_file, name)] or { return none }
    for candidate in candidates {
        if tc.type_symbol_known(candidate) {
            return candidate
        }
    }
    return none
}

fn (tc &TypeChecker) type_symbol_known(name string) bool {
    return name in tc.type_aliases || name in tc.structs || name in tc.interface_names
        || name in tc.flag_enums || name in tc.enum_names || name in tc.sum_types
}

fn (tc &TypeChecker) type_from_known_symbol(name string) ?Type {
    if name in tc.type_aliases {
        return Type(Alias{
            name:      name
            base_type: tc.parse_type(tc.type_aliases[name])
        })
    }
    if name in tc.structs {
        return Type(Struct{
            name: name
        })
    }
    if name in tc.interface_names {
        return Type(Interface{
            name: name
        })
    }
    if name in tc.flag_enums {
        return Type(Enum{
            name:    name
            is_flag: true
        })
    }
    if name in tc.enum_names {
        return Type(Enum{
            name: name
        })
    }
    if name in tc.sum_types {
        return Type(SumType{
            name: name
        })
    }
    return none
}

fn (tc &TypeChecker) selective_import_symbol_is_ambiguous(name string) bool {
    candidates := tc.file_selective_imports[file_import_key(tc.cur_file, name)] or { return false }
    return candidates.len == 0
}

fn (tc &TypeChecker) resolve_imported_type_text(typ string) string {
    if !typ.contains('.') || typ.starts_with('C.') {
        return typ
    }
    dot := typ.index_u8(`.`)
    if dot <= 0 {
        return typ
    }
    alias := typ[..dot]
    if resolved := tc.resolve_import_alias(alias) {
        if resolved != alias {
            return resolved + typ[dot..]
        }
    }
    return typ
}

// has_active_import reports whether has active import applies in types.
fn (tc &TypeChecker) has_active_import(alias string) bool {
    return file_import_key(tc.cur_file, alias) in tc.file_imports
}

// register_fn_signature updates register fn signature state for types.
fn (mut tc TypeChecker) register_fn_signature(name string, ret_type Type, params []Type, is_variadic bool, implicit_veb_ctx bool) {
    tc.register_fn_name_alias(name, ret_type, params, is_variadic, implicit_veb_ctx)
    lowered_name := c_name(name)
    if lowered_name != name {
        tc.register_fn_name_alias(lowered_name, ret_type, params, is_variadic, implicit_veb_ctx)
    }
    if name.ends_with('.str') {
        receiver := name.all_before_last('.')
        legacy_name := '${receiver}_str'
        if !legacy_name.contains('.') {
            tc.register_fn_name_alias(legacy_name, ret_type, params, is_variadic, implicit_veb_ctx)
        }
    }
}

// register_fn_name_alias updates register fn name alias state for types.
fn (mut tc TypeChecker) register_fn_name_alias(name string, ret_type Type, params []Type, is_variadic bool, implicit_veb_ctx bool) {
    tc.fn_ret_types[name] = ret_type
    tc.fn_param_types[name] = params.clone()
    tc.fn_variadic[name] = is_variadic
    tc.fn_implicit_veb_ctx[name] = implicit_veb_ctx
}

fn (mut tc TypeChecker) register_c_variadic_fn(name string) {
    if name.len == 0 {
        return
    }
    tc.c_variadic_fns[name] = true
    lowered_name := c_name(name)
    if lowered_name != name {
        tc.c_variadic_fns[lowered_name] = true
    }
    if !name.starts_with('C.') {
        tc.c_variadic_fns['C.${name}'] = true
    }
}

// annotate_types performs a scope-aware walk over every function body, tracking
// local variable types as they are declared, and records complex/contextual
// expression types. This mirrors what the v2 transformer relies on: the type
// checker runs BEFORE the transformer and publishes per-expression types, so the
// transformer can own type-dependent lowering (string ops, `in` membership, ...)
// instead of the backend.
//
// It uses a single flat scope per function (an over-approximation: a local stays
// visible after its block ends), which is harmless for type lookup since variable
// names are effectively unique within a function.
pub fn (mut tc TypeChecker) annotate_types() {
    tc.annotate_types_with_used(map[string]bool{})
}

// annotate_types_with_used annotates only functions that can be emitted when
// `used_fns` is non-empty. This mirrors transform/cgen pruning and avoids
// resolving types in dead, untransformed function bodies after markused.
pub fn (mut tc TypeChecker) annotate_types_with_used(used_fns map[string]bool) {
    tc.extend_node_caches(tc.a.nodes.len)
    tc.cur_module = ''
    for node in tc.a.nodes {
        if node.kind == .file {
            tc.enter_file(node.value)
        } else if node.kind == .module_decl {
            tc.enter_module(node.value)
        } else if node.kind == .fn_decl {
            if !tc.should_annotate_fn(node, used_fns) {
                continue
            }
            tc.cur_scope = tc.file_scope
            tc.push_scope()
            for pi in 0 .. node.children_count {
                p := tc.a.child_node(&node, pi)
                if p.kind == .param && p.value.len > 0 {
                    tc.cur_scope.insert(p.value, tc.parse_type(p.typ))
                }
            }
            tc.insert_implicit_veb_ctx(node)
            for i in 0 .. node.children_count {
                child := tc.a.child_node(&node, i)
                if child.kind != .param {
                    tc.annotate_node(tc.a.child(&node, i))
                }
            }
            tc.pop_scope()
        }
    }
}

fn (tc &TypeChecker) should_annotate_fn(node flat.Node, used_fns map[string]bool) bool {
    if used_fns.len == 0 {
        return true
    }
    qname := checker_qualified_fn_name(tc.cur_module, node.value)
    if qname in tc.a.export_fn_names || tc.fn_needs_implicit_veb_ctx(node) {
        return true
    }
    if node.value in used_fns {
        return true
    }
    if qname in used_fns {
        return true
    }
    cname := c_name(qname)
    if cname != qname && cname in used_fns {
        return true
    }
    return false
}

fn checker_qualified_fn_name(mod string, name string) string {
    if mod.len == 0 || mod == 'main' || mod == 'builtin' {
        return name
    }
    return '${mod}.${name}'
}

// annotate_node supports annotate node handling for TypeChecker.
fn (mut tc TypeChecker) annotate_node(id flat.NodeId) {
    if int(id) < 0 {
        return
    }
    node := tc.a.nodes[int(id)]
    match node.kind {
        .decl_assign {
            // children are interleaved pairs [lhs0, rhs0, lhs1, rhs1, ...].
            // Multi-return (`a, b := f()`) yields an odd count; we only insert
            // locals for clean pairs and skip MultiReturn rhs values.
            mut i := 0
            for i + 1 < node.children_count {
                lhs_id := tc.a.child(&node, i)
                rhs_id := tc.a.child(&node, i + 1)
                tc.annotate_node(rhs_id)
                lhs := tc.a.nodes[int(lhs_id)]
                if lhs.kind == .ident && lhs.value.len > 0 {
                    mut typ := Type(void_)
                    if node.children_count == 2 && node.typ.len > 0 {
                        typ = tc.parse_type(node.typ)
                        tc.annotate_expected_expr(rhs_id, typ)
                    } else {
                        typ = tc.resolve_type(rhs_id)
                    }
                    if typ !is MultiReturn && typ !is Void {
                        tc.cur_scope.insert(lhs.value, typ)
                        tc.remember_expr_type(lhs_id, typ)
                    }
                }
                i += 2
            }
            return
        }
        .for_in_stmt {
            tc.annotate_for_in(id, node)
            return
        }
        .assign, .selector_assign, .index_assign {
            tc.annotate_assign_expected_exprs(node)
        }
        .struct_init {
            tc.annotate_struct_init_expected_exprs(node)
        }
        .call {
            tc.annotate_call_expected_exprs(id, node)
        }
        else {}
    }

    tc.remember_expr_type(id, tc.resolve_type(id))
    for i in 0 .. node.children_count {
        tc.annotate_node(tc.a.child(&node, i))
    }
}

fn (mut tc TypeChecker) annotate_expected_expr(id flat.NodeId, expected Type) {
    if _ := fn_type_from_type(expected) {
        _ = tc.resolve_expr(id, expected)
    }
}

fn (mut tc TypeChecker) annotate_assign_expected_exprs(node flat.Node) {
    if node.children_count < 2 {
        return
    }
    mut i := 0
    for i + 1 < node.children_count {
        lhs_id := tc.a.child(&node, i)
        rhs_id := tc.a.child(&node, i + 1)
        lhs_type := tc.resolve_lvalue_type(lhs_id)
        tc.annotate_expected_expr(rhs_id, lhs_type)
        i += 2
    }
}

fn (mut tc TypeChecker) annotate_struct_init_expected_exprs(node flat.Node) {
    init_type := tc.parse_type(node.value)
    init_struct := struct_type_from_type(init_type) or { return }
    init_name := init_struct.name
    fields := tc.structs[init_name] or { []StructField{} }
    for i in 0 .. node.children_count {
        field := tc.a.child_node(&node, i)
        if field.kind != .field_init || field.children_count == 0 {
            continue
        }
        value_id := tc.a.child(field, 0)
        mut expected := Type(void_)
        if field.value.len > 0 {
            expected = tc.struct_field_type(init_name, field.value) or { Type(void_) }
        } else if i < fields.len {
            expected = fields[i].typ
        }
        tc.annotate_expected_expr(value_id, expected)
    }
}

fn (mut tc TypeChecker) annotate_call_expected_exprs(id flat.NodeId, node flat.Node) {
    info0 := tc.resolve_call_info(id, node) or { return }
    info := tc.specialized_plain_generic_call_info(node, info0)
    if info.name.len > 0 && !is_array_dsl_call_name(info.name) {
        tc.remember_resolved_call(id, info.name)
    }
    if !info.params_known || info.params.len == 0 {
        return
    }
    mut field_init_args := 0
    for i in 1 .. node.children_count {
        if tc.a.child_node(&node, i).kind == .field_init {
            field_init_args++
        }
    }
    collapsed := if field_init_args > 0 { 1 } else { 0 }
    recv_extra := if info.has_receiver { 1 } else { 0 }
    actual_count := node.children_count - 1 - field_init_args + collapsed + recv_extra
    ctx_count := if info.has_implicit_veb_ctx { 1 } else { 0 }
    ctx_omitted := ctx_count > 0 && actual_count < info.params.len
    for i in 1 .. node.children_count {
        raw_arg := tc.a.child_node(&node, i)
        arg_id := tc.call_arg_value(tc.a.child(&node, i))
        if raw_arg.kind == .field_init {
            tc.annotate_params_field_expected_expr(arg_id, raw_arg.value, info)
            continue
        }
        arg_shift := if ctx_omitted { ctx_count } else { 0 }
        param_idx := (if info.has_receiver { i } else { i - 1 }) + arg_shift
        if info.is_c_variadic && param_idx >= c_variadic_fixed_param_count(info) {
            continue
        }
        if param_idx >= info.params.len {
            continue
        }
        expected := tc.call_arg_expected_type(info, param_idx)
        tc.annotate_expected_expr(arg_id, expected)
    }
}

fn (tc &TypeChecker) call_arg_expected_type(info CallInfo, param_idx int) Type {
    expected := info.params[param_idx]
    if info.is_variadic && param_idx == info.params.len - 1 && expected is Array {
        return array_elem_type(expected)
    }
    return expected
}

fn (mut tc TypeChecker) annotate_params_field_expected_expr(arg_id flat.NodeId, field_name string, info CallInfo) {
    if field_name.len == 0 {
        return
    }
    for param in info.params {
        clean := unwrap_pointer(param)
        if clean is Struct {
            if expected := tc.struct_field_type(clean.name, field_name) {
                tc.annotate_expected_expr(arg_id, expected)
                return
            }
        }
    }
}

// annotate_for_in supports annotate for in handling for TypeChecker.
fn (mut tc TypeChecker) annotate_for_in(_id flat.NodeId, node flat.Node) {
    header := node.value.int()
    if header < 3 || node.children_count < 3 {
        return
    }
    key_id := tc.a.child(&node, 0)
    val_id := tc.a.child(&node, 1)
    container_id := tc.a.child(&node, 2)
    tc.annotate_node(container_id)
    has_val := int(val_id) >= 0
    if header == 4 {
        tc.insert_loop_var(key_id, tc.range_loop_var_type(container_id))
        tc.annotate_node(tc.a.child(&node, 3))
    } else {
        clean := unwrap_pointer(tc.resolve_type(container_id))
        if clean is Array {
            if has_val {
                tc.insert_loop_var(key_id, Type(int_))
                tc.insert_loop_var(val_id, clean.elem_type)
            } else {
                tc.insert_loop_var(key_id, clean.elem_type)
            }
        } else if clean is ArrayFixed {
            if has_val {
                tc.insert_loop_var(key_id, Type(int_))
                tc.insert_loop_var(val_id, clean.elem_type)
            } else {
                tc.insert_loop_var(key_id, clean.elem_type)
            }
        } else if clean is Map {
            if has_val {
                tc.insert_loop_var(key_id, clean.key_type)
                tc.insert_loop_var(val_id, clean.value_type)
            } else {
                tc.insert_loop_var(key_id, clean.value_type)
            }
        } else if clean is String {
            if has_val {
                tc.insert_loop_var(key_id, Type(int_))
                tc.insert_loop_var(val_id, Type(u8_))
            } else {
                tc.insert_loop_var(key_id, Type(u8_))
            }
        } else if elem_type := iterator_for_in_elem_type(clean) {
            if has_val {
                tc.insert_loop_var(key_id, Type(int_))
                tc.insert_loop_var(val_id, elem_type)
            } else {
                tc.insert_loop_var(key_id, elem_type)
            }
        } else {
            container := tc.a.nodes[int(container_id)]
            if container.kind == .range {
                tc.insert_loop_var(key_id, tc.range_loop_var_type(tc.a.child(&container, 0)))
            }
        }
    }
    for i in header .. node.children_count {
        tc.annotate_node(tc.a.child(&node, i))
    }
}

fn iterator_for_in_elem_type(typ Type) ?Type {
    name := typ.name()
    if name == 'RunesIterator' || name == 'builtin.RunesIterator' {
        return Type(rune_)
    }
    return none
}

fn (tc &TypeChecker) range_loop_var_type(low_id flat.NodeId) Type {
    low_type := tc.resolve_type(low_id)
    if fn_param_unalias_type(low_type).is_integer() {
        return low_type
    }
    return Type(int_)
}

// insert_loop_var updates insert loop var state for types.
fn (mut tc TypeChecker) insert_loop_var(id flat.NodeId, typ Type) {
    if int(id) < 0 {
        return
    }
    v := tc.a.nodes[int(id)]
    if v.kind == .ident && v.value.len > 0 {
        tc.cur_scope.insert(v.value, typ)
        tc.remember_expr_type(id, typ)
    }
}

// expr_type returns the resolved type recorded for a node during annotate_types.
pub fn (tc &TypeChecker) expr_type(id flat.NodeId) ?Type {
    if int(id) >= 0 {
        node := tc.a.nodes[int(id)]
        if node.kind == .call && node.typ.len > 0 && node.typ !in ['int', 'array', 'map', 'unknown'] {
            return tc.parse_type(node.typ)
        }
    }
    if t := tc.resolved_call_type(id) {
        return t
    }
    if t := tc.cached_expr_type(id) {
        return t
    }
    return none
}

// resolved_call_type supports resolved call type handling for TypeChecker.
fn (tc &TypeChecker) resolved_call_type(id flat.NodeId) ?Type {
    if int(id) < 0 {
        return none
    }
    node := tc.a.nodes[int(id)]
    if node.kind != .call {
        return none
    }
    if t := tc.cached_expr_type(id) {
        return t
    }
    if name := tc.cached_resolved_call(id) {
        if t := tc.fn_ret_types[name] {
            return t
        }
    }
    return none
}

// cached_expr_type supports cached expr type handling for TypeChecker.
fn (tc &TypeChecker) cached_expr_type(id flat.NodeId) ?Type {
    idx := int(id)
    if idx >= 0 && idx < tc.expr_type_set.len && tc.expr_type_set[idx] {
        return tc.expr_type_values[idx]
    }
    return none
}

// cached_resolved_call supports cached resolved call handling for TypeChecker.
fn (tc &TypeChecker) cached_resolved_call(id flat.NodeId) ?string {
    idx := int(id)
    if idx >= 0 && idx < tc.resolved_call_set.len && tc.resolved_call_set[idx] {
        return tc.resolved_call_names[idx]
    }
    return none
}

// resolved_call_name returns the checker-resolved function name for a call node.
pub fn (tc &TypeChecker) resolved_call_name(id flat.NodeId) ?string {
    return tc.cached_resolved_call(id)
}

// resolved_fn_value_name returns the checker-resolved function name for a function value node.
pub fn (tc &TypeChecker) resolved_fn_value_name(id flat.NodeId) ?string {
    idx := int(id)
    if idx >= 0 && idx < tc.resolved_fn_value_set.len && tc.resolved_fn_value_set[idx] {
        return tc.resolved_fn_value_names[idx]
    }
    return none
}

// resolve_fn_value_name_for_expected resolves and records a function value in an expected FnType context.
fn (mut tc TypeChecker) resolve_fn_value_name_for_expected(id flat.NodeId, expected Type) ?string {
    if name := tc.resolved_fn_value_name(id) {
        return name
    }
    if int(id) < 0 || int(id) >= tc.a.nodes.len {
        return none
    }
    node := tc.a.nodes[int(id)]
    if tc.fn_value_shadowed_by_value(node) {
        return none
    }
    key := tc.fn_value_match_key(node, expected) or { return none }
    tc.remember_resolved_fn_value_chain(id, key)
    return key
}

// remember_resolved_call supports remember resolved call handling for TypeChecker.
fn (mut tc TypeChecker) remember_resolved_call(id flat.NodeId, name string) {
    idx := int(id)
    if idx < 0 {
        return
    }
    if idx >= tc.resolved_call_names.len {
        tc.extend_node_caches(tc.a.nodes.len)
    }
    if idx < tc.resolved_call_names.len {
        tc.resolved_call_names[idx] = name
        tc.resolved_call_set[idx] = true
    }
}

// remember_resolved_fn_value records the exact function declaration used by a function value.
fn (mut tc TypeChecker) remember_resolved_fn_value(id flat.NodeId, name string) {
    idx := int(id)
    if idx < 0 {
        return
    }
    if idx >= tc.resolved_fn_value_names.len {
        tc.extend_node_caches(tc.a.nodes.len)
    }
    if idx < tc.resolved_fn_value_names.len {
        tc.resolved_fn_value_names[idx] = name
        tc.resolved_fn_value_set[idx] = true
    }
}

fn (mut tc TypeChecker) remember_resolved_fn_value_chain(id flat.NodeId, name string) {
    tc.remember_resolved_fn_value(id, name)
    if int(id) < 0 || int(id) >= tc.a.nodes.len {
        return
    }
    node := tc.a.nodes[int(id)]
    if node.kind in [.cast_expr, .paren, .expr_stmt] && node.children_count > 0 {
        tc.remember_resolved_fn_value_chain(tc.a.child(&node, 0), name)
    }
}

// register_synth_type records the type of a generated or transformed node.
pub fn (mut tc TypeChecker) register_synth_type(id flat.NodeId, typ Type) {
    tc.remember_expr_type(id, typ)
}

// remember_expr_type supports remember expr type handling for TypeChecker.
fn (mut tc TypeChecker) remember_expr_type(id flat.NodeId, typ Type) {
    if int(id) < 0 {
        return
    }
    kind := if int(id) < tc.a.nodes.len { tc.a.nodes[int(id)].kind } else { flat.NodeKind.empty }
    if should_cache_expr_type(kind, typ) {
        idx := int(id)
        if idx >= tc.expr_type_values.len {
            tc.extend_node_caches(tc.a.nodes.len)
        }
        if idx < tc.expr_type_values.len {
            tc.expr_type_values[idx] = typ
            tc.expr_type_set[idx] = true
        }
    }
}

// should_cache_expr_type reports whether should cache expr type applies in types.
fn should_cache_expr_type(kind flat.NodeKind, typ Type) bool {
    if typ is Void || typ is Unknown {
        return false
    }
    if typ is Array || typ is ArrayFixed || typ is Map || typ is Pointer || typ is FnType
        || typ is OptionType || typ is ResultType || typ is Struct || typ is Interface
        || typ is Enum || typ is SumType || typ is Alias || typ is MultiReturn {
        return true
    }
    kind_id := int(kind)
    return kind_id != 1 && kind_id != 2 && kind_id != 3 && kind_id != 4 && kind_id != 5
        && kind_id != 28
}

// check_semantics validates check semantics state for types.
pub fn (mut tc TypeChecker) check_semantics() {
    tc.check_export_attrs()
    tc.cur_module = ''
    tc.cur_file = ''
    for i, node in tc.a.nodes {
        match node.kind {
            .file {
                tc.enter_file(node.value)
            }
            .module_decl {
                tc.enter_module(node.value)
            }
            .struct_decl {
                tc.check_decl_type_strings(flat.NodeId(i), node)
                tc.check_struct_field_defaults(node)
            }
            .type_decl, .interface_decl {
                tc.check_decl_type_strings(flat.NodeId(i), node)
            }
            .enum_decl {
                tc.check_enum_field_values(node)
            }
            .const_decl {
                tc.check_const_field_values(node)
            }
            .fn_decl {
                tc.check_decl_type_strings(flat.NodeId(i), node)
                tc.cur_fn_ret_type = tc.parse_type(node.typ)
                tc.cur_fn_node_id = i
                tc.method_value_locals = map[string]bool{}
                tc.method_value_local_depth = map[string]int{}
                tc.push_scope()
                for pi in 0 .. node.children_count {
                    p := tc.a.child_node(&node, pi)
                    if p.kind == .param && p.value.len > 0 {
                        tc.cur_scope.insert(p.value, tc.parse_type(p.typ))
                    }
                }
                tc.insert_implicit_veb_ctx(node)
                tc.check_fn_body(node)
                tc.cur_fn_node_id = -1
                is_disabled_stub := node.value in tc.a.disabled_fns
                if tc.cur_fn_ret_type !is Unknown
                    && !type_allows_implicit_return(tc.cur_fn_ret_type)
                    && !tc.fn_body_definitely_returns(node) && !is_disabled_stub
                    && tc.should_diagnose(flat.NodeId(i)) {
                    tc.record_error(.return_mismatch,
                        'missing return at end of function `${node.value}`; expected `${tc.cur_fn_ret_type.name()}`',
                        flat.NodeId(i))
                }
                tc.pop_scope()
                tc.cur_fn_ret_type = Type(void_)
            }
            .c_fn_decl {
                if tc.reject_unsupported_generics {
                    tc.check_decl_type_strings(flat.NodeId(i), node)
                }
            }
            else {}
        }

        _ = i
    }
}

fn (mut tc TypeChecker) check_export_attrs() {
    mut natural_symbols := map[string]string{}
    synthetic_main_reserved := tc.has_synthetic_c_entry_main()
    mut cur_module := ''
    for node in tc.a.nodes {
        match node.kind {
            .file {
                tc.enter_file(node.value)
                cur_module = tc.cur_module
            }
            .module_decl {
                cur_module = node.value
                tc.enter_module(node.value)
            }
            .fn_decl {
                qname := export_qualified_fn_name(cur_module, node.value)
                natural_symbol := export_natural_c_symbol(cur_module, node.value)
                natural_symbols[natural_symbol] = qname
            }
            else {}
        }
    }
    mut export_symbols := map[string]string{}
    cur_module = ''
    for i, node in tc.a.nodes {
        match node.kind {
            .file {
                tc.enter_file(node.value)
                cur_module = tc.cur_module
            }
            .module_decl {
                cur_module = node.value
                tc.enter_module(node.value)
            }
            .fn_decl {
                qname := export_qualified_fn_name(cur_module, node.value)
                export_name := tc.a.export_fn_names[qname] or { continue }
                if export_name.len == 0 {
                    tc.record_error_unfiltered(.unsupported_generic,
                        'empty export name for `${qname}`', flat.NodeId(i))
                    continue
                }
                if !is_valid_export_c_name(export_name) {
                    tc.record_error_unfiltered(.unsupported_generic,
                        'invalid export name `${export_name}` for `${qname}`', flat.NodeId(i))
                }
                if synthetic_main_reserved && export_name == 'main' {
                    tc.record_error_unfiltered(.unsupported_generic,
                        'export name `main` for `${qname}` collides with synthetic entry point `main`',
                        flat.NodeId(i))
                }
                if node.generic_params.len > 0 {
                    tc.record_error_unfiltered(.unsupported_generic,
                        'generic function `${qname}` cannot be exported', flat.NodeId(i))
                }
                for pi in 0 .. node.children_count {
                    p := tc.a.child_node(&node, pi)
                    if p.kind == .param && (p.value.len == 0 || p.typ.len == 0) {
                        tc.record_error_unfiltered(.unsupported_generic,
                            'exported function `${qname}` must name all parameters', flat.NodeId(i))
                    }
                }
                if existing := export_symbols[export_name] {
                    if existing != qname {
                        tc.record_error_unfiltered(.unsupported_generic,
                            'duplicate export name `${export_name}` for `${qname}` and `${existing}`',
                            flat.NodeId(i))
                    }
                } else {
                    export_symbols[export_name] = qname
                }
                if existing := natural_symbols[export_name] {
                    tc.record_error_unfiltered(.unsupported_generic,
                        'export name `${export_name}` for `${qname}` collides with `${existing}`',
                        flat.NodeId(i))
                }
            }
            else {}
        }
    }
}

fn (tc &TypeChecker) has_synthetic_c_entry_main() bool {
    if tc.has_c_test_harness_main() {
        return true
    }
    if tc.has_main_module_fn_main() {
        return false
    }
    return tc.has_c_top_level_main()
}

fn (tc &TypeChecker) has_main_module_fn_main() bool {
    mut cur_module := ''
    for node in tc.a.nodes {
        match node.kind {
            .file {
                cur_module = ''
            }
            .module_decl {
                cur_module = node.value
            }
            .fn_decl {
                if node.value == 'main' && (cur_module.len == 0 || cur_module == 'main') {
                    return true
                }
            }
            else {}
        }
    }
    return false
}

fn (tc &TypeChecker) has_c_test_harness_main() bool {
    for file_idx, file_node in tc.a.nodes {
        if file_idx < tc.a.user_code_start || file_node.kind != .file || file_node.value.len == 0 {
            continue
        }
        if !tc.is_selected_input_file(file_node.value) {
            continue
        }
        module_name := tc.top_level_file_module_name(file_node)
        if is_c_backend_test_file(file_node.value)
            && (module_name.len == 0 || module_name == 'main') {
            return true
        }
    }
    return false
}

fn (tc &TypeChecker) has_c_top_level_main() bool {
    for file_idx, file_node in tc.a.nodes {
        if !tc.should_emit_c_top_level_file(file_idx, file_node) {
            continue
        }
        for i in 0 .. file_node.children_count {
            child_id := tc.a.child(&file_node, i)
            if int(child_id) < tc.a.user_code_start {
                continue
            }
            if tc.is_c_top_level_stmt(child_id) {
                return true
            }
        }
    }
    return false
}

fn (tc &TypeChecker) should_emit_c_top_level_file(file_idx int, file_node flat.Node) bool {
    if file_idx < tc.a.user_code_start || file_node.kind != .file || file_node.children_count == 0 {
        return false
    }
    module_name := tc.top_level_file_module_name(file_node)
    return module_name.len == 0 || module_name == 'main'
}

fn (tc &TypeChecker) top_level_file_module_name(file_node flat.Node) string {
    if module_name := tc.file_modules[file_node.value] {
        return module_name
    }
    for i in 0 .. file_node.children_count {
        child := tc.a.child_node(&file_node, i)
        if child.kind == .module_decl {
            return child.value
        }
    }
    return ''
}

fn (tc &TypeChecker) is_c_top_level_stmt(id flat.NodeId) bool {
    if int(id) < 0 {
        return false
    }
    node := tc.a.nodes[int(id)]
    return match node.kind {
        .expr_stmt, .assign, .decl_assign, .selector_assign, .index_assign, .for_stmt,
        .for_in_stmt, .if_expr, .match_stmt, .assert_stmt, .defer_stmt {
            true
        }
        .block, .comptime_if {
            for i in 0 .. node.children_count {
                if tc.is_c_top_level_stmt(tc.a.child(&node, i)) {
                    return true
                }
            }
            false
        }
        else {
            false
        }
    }
}

fn (tc &TypeChecker) is_selected_input_file(file string) bool {
    return tc.diagnostic_files.len == 0 || tc.diagnostic_files[file]
}

fn is_c_backend_test_file(path string) bool {
    file := path.all_after_last('/').all_after_last('\\')
    if file.ends_with('_test.v') || file.ends_with('_test.c.v') {
        return true
    }
    if !file.ends_with('.v') {
        return false
    }
    base := file[..file.len - 2]
    if !base.contains('.') {
        return false
    }
    return base.all_after_last('.') == 'c' && base.all_before_last('.').ends_with('_test')
}

fn export_qualified_fn_name(module_name string, name string) string {
    if module_name.len == 0 || module_name == 'main' || module_name == 'builtin' {
        return name
    }
    return '${module_name}.${name}'
}

fn export_natural_c_symbol(module_name string, name string) string {
    if module_name == 'builtin' && name == 'free' {
        return 'v_free'
    }
    if module_name.len > 0 && module_name != 'main' && module_name != 'builtin' {
        return c_name('${module_name}.${name}')
    }
    if name == 'free' {
        return 'v_free'
    }
    if name == 'exit' {
        return 'v_exit'
    }
    if name in export_c_libc_collision_symbols {
        return 'v_${name}'
    }
    return c_name(name)
}

fn is_valid_export_c_name(name string) bool {
    if name.len == 0 {
        return false
    }
    if name in export_c_reserved_words {
        return false
    }
    if name in export_v3_reserved_c_symbols {
        return false
    }
    first := name[0]
    if !((first >= `a` && first <= `z`) || (first >= `A` && first <= `Z`) || first == `_`) {
        return false
    }
    for i in 1 .. name.len {
        c := name[i]
        if (c >= `a` && c <= `z`) || (c >= `A` && c <= `Z`) || (c >= `0` && c <= `9`) || c == `_` {
            continue
        }
        return false
    }
    return true
}

fn (mut tc TypeChecker) insert_implicit_veb_ctx(node flat.Node) {
    if !tc.fn_needs_implicit_veb_ctx(node) {
        return
    }
    tc.cur_scope.insert('ctx', tc.implicit_veb_ctx_type())
}

fn (tc &TypeChecker) fn_param_types_with_implicit_veb_ctx(node flat.Node, params []Type) []Type {
    if !tc.fn_needs_implicit_veb_ctx(node) {
        return params
    }
    insert_idx := tc.fn_implicit_veb_ctx_insert_index(node)
    mut result := []Type{cap: params.len + 1}
    for i, param in params {
        if i == insert_idx {
            result << tc.implicit_veb_ctx_type()
        }
        result << param
    }
    if insert_idx >= params.len {
        result << tc.implicit_veb_ctx_type()
    }
    return result
}

fn (tc &TypeChecker) implicit_veb_ctx_type() Type {
    return tc.parse_type('mut Context')
}

fn (tc &TypeChecker) fn_needs_implicit_veb_ctx(node flat.Node) bool {
    return tc.fn_returns_veb_result(node) && tc.fn_has_receiver_param(node)
        && !tc.fn_receiver_type_is_context(node) && !tc.fn_has_param(node, 'ctx')
        && tc.type_name_known_in_current_module('Context')
}

fn (tc &TypeChecker) fn_implicit_veb_ctx_insert_index(node flat.Node) int {
    if tc.fn_has_receiver_param(node) {
        return 1
    }
    return 0
}

fn (tc &TypeChecker) fn_has_receiver_param(node flat.Node) bool {
    if !node.value.contains('.') || node.children_count == 0 {
        return false
    }
    first := tc.a.child_node(&node, 0)
    if first.kind != .param || first.typ.len == 0 {
        return false
    }
    receiver := node.value.all_before_last('.').all_after_last('.')
    param_type := first.typ.trim_left('&').all_after_last('.')
    return receiver == param_type
}

fn (tc &TypeChecker) fn_receiver_type_is_context(node flat.Node) bool {
    if !tc.fn_has_receiver_param(node) {
        return false
    }
    first := tc.a.child_node(&node, 0)
    return first.typ.trim_left('&').all_after_last('.') == 'Context'
}

fn (tc &TypeChecker) fn_has_param(node flat.Node, name string) bool {
    for i in 0 .. node.children_count {
        p := tc.a.child_node(&node, i)
        if p.kind == .param && p.value == name {
            return true
        }
    }
    return false
}

fn (tc &TypeChecker) fn_returns_veb_result(node flat.Node) bool {
    if node.typ == 'veb.Result' {
        return true
    }
    ret := tc.parse_type(node.typ)
    return ret.name() == 'veb.Result'
}

// check_fn_body validates check fn body state for types.
fn (mut tc TypeChecker) check_fn_body(node flat.Node) {
    saved_smartcasts := clone_smartcasts(tc.smartcasts)
    defer {
        tc.smartcasts = clone_smartcasts(saved_smartcasts)
    }
    for i in 0 .. node.children_count {
        child_id := tc.a.child(&node, i)
        child := tc.a.child_node(&node, i)
        if child.kind == .param {
            continue
        }
        tc.check_stmt_node(child_id)
        tc.apply_post_if_exit_smartcasts(child_id)
    }
}

// check_decl_type_strings validates check decl type strings state for types.
fn (mut tc TypeChecker) check_decl_type_strings(node_id flat.NodeId, node flat.Node) {
    generic_params := tc.infer_decl_generic_params(node)
    if node.kind == .struct_decl {
        if node.typ.contains('generic') && tc.reject_unsupported_generics {
            tc.record_unsupported_generic('unsupported generic struct `${node.value}`', node_id)
        }
    } else {
        if node.generic_params.len > 0 && tc.reject_unsupported_generics {
            tc.record_unsupported_generic('unsupported generic declaration `${node.value}`',
                node_id)
        }
        tc.check_type_string_for_unsupported_generics(node.typ, node_id, generic_params)
    }
    for i in 0 .. node.children_count {
        child_id := tc.a.child(&node, i)
        if int(child_id) < 0 {
            continue
        }
        child := tc.a.nodes[int(child_id)]
        tc.check_type_string_for_unsupported_generics(child.typ, child_id, generic_params)
        if node.kind == .type_decl && child.value.len > 0 {
            tc.check_type_string_for_unsupported_generics(child.value, child_id, generic_params)
        }
        for j in 0 .. child.children_count {
            grandchild_id := tc.a.child(&child, j)
            if int(grandchild_id) < 0 {
                continue
            }
            grandchild := tc.a.nodes[int(grandchild_id)]
            tc.check_type_string_for_unsupported_generics(grandchild.typ, grandchild_id,
                generic_params)
        }
    }
}

fn (tc &TypeChecker) infer_decl_generic_params(node flat.Node) map[string]bool {
    mut params := map[string]bool{}
    for name in node.generic_params {
        params[name] = true
    }
    tc.collect_generic_receiver_params(node, mut params)
    return params
}

fn (tc &TypeChecker) collect_generic_receiver_params(node flat.Node, mut params map[string]bool) {
    if node.kind != .fn_decl && node.kind != .c_fn_decl {
        return
    }
    if !node.value.contains('.') {
        return
    }
    if node.children_count == 0 {
        return
    }
    receiver_id := tc.a.child(&node, 0)
    if int(receiver_id) < 0 {
        return
    }
    receiver := tc.a.nodes[int(receiver_id)]
    if receiver.kind != .param {
        return
    }
    receiver_type := receiver.typ.trim_left('&')
    if receiver_type != node.value.all_before_last('.') {
        return
    }
    mut counts := map[string]int{}
    if !tc.collect_generic_param_candidates(receiver.typ, mut counts) {
        return
    }
    for name, _ in counts {
        params[name] = true
    }
}

fn (tc &TypeChecker) collect_generic_param_candidates(typ string, mut counts map[string]int) bool {
    clean := typ.trim_space()
    if clean.len == 0 {
        return false
    }
    if clean.starts_with('&') || clean.starts_with('?') || clean.starts_with('!') {
        return tc.collect_generic_param_candidates(clean[1..], mut counts)
    }
    if clean.starts_with('shared ') {
        return tc.collect_generic_param_candidates(clean[7..], mut counts)
    }
    if clean.starts_with('...') {
        return tc.collect_generic_param_candidates(clean[3..], mut counts)
    }
    if clean.starts_with('[]') {
        return tc.collect_generic_param_candidates(clean[2..], mut counts)
    }
    if clean.starts_with('map[') {
        mut found_context := false
        bracket_end := find_matching_bracket(clean, 3)
        if bracket_end < clean.len {
            if tc.collect_generic_param_candidates(clean[4..bracket_end], mut counts) {
                found_context = true
            }
            if tc.collect_generic_param_candidates(clean[bracket_end + 1..], mut counts) {
                found_context = true
            }
        }
        return found_context
    }
    if clean.starts_with('[') {
        idx := clean.index_u8(`]`)
        if idx > 0 {
            return tc.collect_generic_param_candidates(clean[idx + 1..], mut counts)
        }
        return false
    }
    if clean.starts_with('(') && clean.ends_with(')') {
        mut found_context := false
        for part in split_params(clean[1..clean.len - 1]) {
            if tc.collect_generic_param_candidates(part, mut counts) {
                found_context = true
            }
        }
        return found_context
    }
    if clean.starts_with('fn(') || clean.starts_with('fn (') {
        mut found_context := false
        params_start := clean.index_u8(`(`) + 1
        mut depth := 1
        mut params_end := params_start
        for params_end < clean.len {
            if clean[params_end] == `(` {
                depth++
            } else if clean[params_end] == `)` {
                depth--
                if depth == 0 {
                    break
                }
            }
            params_end++
        }
        if params_end < clean.len {
            for part in split_params(clean[params_start..params_end]) {
                trimmed := part.trim_space()
                parts := trimmed.split(' ')
                param_type := if parts.len >= 2 { parts[parts.len - 1] } else { trimmed }
                if tc.collect_generic_param_candidates(param_type, mut counts) {
                    found_context = true
                }
            }
            if tc.collect_generic_param_candidates(clean[params_end + 1..], mut counts) {
                found_context = true
            }
        }
        return found_context
    }
    if generic_type_application(clean) {
        bracket := clean.index_u8(`[`)
        bracket_end := find_matching_bracket(clean, bracket)
        if bracket_end < clean.len {
            for part in split_params(clean[bracket + 1..bracket_end]) {
                tc.collect_generic_param_candidates(part, mut counts)
            }
        }
        return true
    }
    if is_bare_generic_param(clean) && !tc.type_name_known(clean) {
        counts[clean] = (counts[clean] or { 0 }) + 1
    }
    return false
}

// check_type_string_for_unsupported_generics
// validates helper state for types.
fn (mut tc TypeChecker) check_type_string_for_unsupported_generics(typ string, node_id flat.NodeId, generic_params map[string]bool) {
    clean := typ.trim_space()
    if clean.len == 0 {
        return
    }
    if clean in ['generic', 'params', 'union'] {
        return
    }
    if clean.starts_with('&') || clean.starts_with('?') || clean.starts_with('!') {
        tc.check_type_string_for_unsupported_generics(clean[1..], node_id, generic_params)
        return
    }
    if clean.starts_with('shared ') {
        tc.check_type_string_for_unsupported_generics(clean[7..], node_id, generic_params)
        return
    }
    if clean == 'thread' || clean == 'chan' {
        return
    }
    if clean.starts_with('thread ') {
        // `thread T` is a thread handle; only its element type T needs checking.
        tc.check_type_string_for_unsupported_generics(clean[7..], node_id, generic_params)
        return
    }
    if clean.starts_with('chan ') {
        tc.check_type_string_for_unsupported_generics(clean[5..], node_id, generic_params)
        return
    }
    if clean.starts_with('...') {
        tc.check_type_string_for_unsupported_generics(clean[3..], node_id, generic_params)
        return
    }
    if clean.starts_with('[]') {
        tc.check_type_string_for_unsupported_generics(clean[2..], node_id, generic_params)
        return
    }
    if clean.starts_with('map[') {
        bracket_end := find_matching_bracket(clean, 3)
        if bracket_end < clean.len {
            tc.check_type_string_for_unsupported_generics(clean[4..bracket_end], node_id,
                generic_params)
            tc.check_type_string_for_unsupported_generics(clean[bracket_end + 1..], node_id,
                generic_params)
        }
        return
    }
    if clean.starts_with('[') {
        idx := clean.index_u8(`]`)
        if idx > 0 {
            tc.check_type_string_for_unsupported_generics(clean[idx + 1..], node_id, generic_params)
        }
        return
    }
    if clean.starts_with('(') && clean.ends_with(')') {
        for part in split_params(clean[1..clean.len - 1]) {
            tc.check_type_string_for_unsupported_generics(part, node_id, generic_params)
        }
        return
    }
    if clean.starts_with('fn(') || clean.starts_with('fn (') {
        tc.check_fn_type_string_for_unsupported_generics(clean, node_id, generic_params)
        return
    }
    if generic_type_application(clean) {
        if tc.reject_unsupported_generics {
            tc.record_unsupported_generic('unsupported generic type application `${clean}`',
                node_id)
            return
        }
        bracket := clean.index_u8(`[`)
        bracket_end := find_matching_bracket(clean, bracket)
        base := clean[..bracket].trim_space()
        if should_check_named_type(base) && !tc.type_name_known(base) {
            tc.record_error(.unknown_type, 'unknown type `${base}`', node_id)
        }
        if bracket_end < clean.len {
            for part in split_params(clean[bracket + 1..bracket_end]) {
                tc.check_type_string_for_unsupported_generics(part, node_id, generic_params)
            }
        }
        return
    }
    if is_bare_generic_param(clean) && !tc.type_name_known(clean) {
        if tc.reject_unsupported_generics {
            tc.record_unsupported_generic('unsupported generic type parameter `${clean}`', node_id)
            return
        }
        if clean in generic_params {
            return
        }
    }
    if should_check_named_type(clean) && !tc.type_name_known(clean) {
        tc.record_error(.unknown_type, 'unknown type `${clean}`', node_id)
    }
}

// check_fn_type_string_for_unsupported_generics
// validates helper state for types.
fn (mut tc TypeChecker) check_fn_type_string_for_unsupported_generics(typ string, node_id flat.NodeId, generic_params map[string]bool) {
    params_start := typ.index_u8(`(`) + 1
    mut depth := 1
    mut params_end := params_start
    for params_end < typ.len {
        if typ[params_end] == `(` {
            depth++
        } else if typ[params_end] == `)` {
            depth--
            if depth == 0 {
                break
            }
        }
        params_end++
    }
    if params_end >= typ.len {
        return
    }
    for part in split_params(typ[params_start..params_end]) {
        trimmed := part.trim_space()
        parts := trimmed.split(' ')
        param_type := if parts.len >= 2 { parts[parts.len - 1] } else { trimmed }
        tc.check_type_string_for_unsupported_generics(param_type, node_id, generic_params)
    }
    ret := typ[params_end + 1..].trim_space()
    tc.check_type_string_for_unsupported_generics(ret, node_id, generic_params)
}

// generic_type_application supports generic type application handling for types.
fn generic_type_application(typ string) bool {
    _, _, ok := generic_type_application_parts(typ)
    return ok
}

fn (tc &TypeChecker) generic_args_are_concrete(args []string) bool {
    for arg in args {
        if tc.type_text_has_generic_placeholder(arg) {
            return false
        }
    }
    return true
}

fn (tc &TypeChecker) type_text_has_generic_placeholder(typ string) bool {
    clean := typ.trim_space()
    if is_bare_generic_param(clean) {
        return !tc.is_known_type_text(clean)
    }
    if clean.starts_with('&') {
        return tc.type_text_has_generic_placeholder(clean[1..])
    }
    if clean.starts_with('mut ') {
        return tc.type_text_has_generic_placeholder(clean[4..])
    }
    if clean.starts_with('?') || clean.starts_with('!') {
        return tc.type_text_has_generic_placeholder(clean[1..])
    }
    if clean.starts_with('...') {
        return tc.type_text_has_generic_placeholder(clean[3..])
    }
    if clean.starts_with('[]') {
        return tc.type_text_has_generic_placeholder(clean[2..])
    }
    if clean.starts_with('map[') {
        bracket_end := find_matching_bracket(clean, 3)
        if bracket_end < clean.len {
            return tc.type_text_has_generic_placeholder(clean[4..bracket_end])
                || tc.type_text_has_generic_placeholder(clean[bracket_end + 1..])
        }
    }
    if clean.starts_with('[') {
        bracket_end := find_matching_bracket(clean, 0)
        if bracket_end < clean.len {
            return tc.type_text_has_generic_placeholder(clean[bracket_end + 1..])
        }
    }
    _, args, ok := generic_type_application_parts(clean)
    if ok {
        for arg in args {
            if tc.type_text_has_generic_placeholder(arg) {
                return true
            }
        }
    }
    return false
}

fn generic_type_application_parts(typ string) (string, []string, bool) {
    if typ.starts_with('[') || !typ.contains('[') {
        return '', []string{}, false
    }
    bracket := typ.index_u8(`[`)
    bracket_end := find_matching_bracket(typ, bracket)
    if bracket <= 0 || bracket_end <= bracket {
        return '', []string{}, false
    }
    inner := typ[bracket + 1..bracket_end].trim_space()
    if is_fixed_array_len_text(inner) {
        return '', []string{}, false
    }
    return typ[..bracket], split_params(inner), true
}

// is_fixed_array_len_text reports whether a postfix `Base[inner]` bracket holds a fixed-array
// length rather than a generic type argument. `ArrayFixed.name()` renders the length as a decimal
// (`u8[16]`), a non-decimal literal (`u8[0x10]`), or the source length expression (`u8[segs + 1]`);
// a generic argument is always a type, never a number or arithmetic expression. Recognising all
// three keeps such a postfix name parsing as a fixed array (e.g. when `[]thread T.wait()` recovers
// the spawned return type) instead of a bogus generic application.
fn is_fixed_array_len_text(inner string) bool {
    s := inner.trim_space()
    if s.len == 0 {
        return false
    }
    // A fixed-array length is a single integer expression; a comma means the brackets hold a
    // generic argument LIST (`Pair[int, &Node]`), not a length. Without this an `&` (or `-`)
    // that merely leads a later pointer type argument would be read as a length operator.
    if s.contains(',') {
        return false
    }
    if v_int_literal_value(s) != none {
        return true
    }
    for i in 0 .. s.len {
        c := s[i]
        if c in [`+`, `*`, `/`, `%`, `|`, `^`, `<`, `>`] {
            return true
        }
        // A leading `-`/`&` is a negative literal / pointer-type argument; elsewhere they are the
        // subtraction / bitwise-and operators of a length expression.
        if (c == `-` || c == `&`) && i > 0 {
            return true
        }
    }
    return false
}

// is_decimal_int_literal reports whether is decimal int literal applies in types.
fn is_decimal_int_literal(s string) bool {
    if s.len == 0 {
        return false
    }
    for i in 0 .. s.len {
        if s[i] < `0` || s[i] > `9` {
            return false
        }
    }
    return true
}

// v_int_literal_value parses a complete V integer literal — decimal, hex (`0x`), octal
// (`0o`), or binary (`0b`), with optional `_` digit separators — to its value. Returns
// none when `s` is not a whole integer literal (a const name, an expression, etc.), so
// const-length folding accepts `0xF & 6` / `[0b1100 >> 1]int`, not just decimal text.
fn v_int_literal_value(s string) ?int {
    if s.len == 0 {
        return none
    }
    t := s.replace('_', '')
    if t.len == 0 {
        return none
    }
    mut base := 10
    mut digits := t
    if t.len >= 2 && t[0] == `0` {
        c := t[1]
        if c == `x` || c == `X` {
            base = 16
            digits = t[2..]
        } else if c == `o` || c == `O` {
            base = 8
            digits = t[2..]
        } else if c == `b` || c == `B` {
            base = 2
            digits = t[2..]
        }
    }
    if digits.len == 0 {
        return none
    }
    mut value := 0
    for ch in digits {
        mut d := 0
        if ch >= `0` && ch <= `9` {
            d = int(ch - `0`)
        } else if ch >= `a` && ch <= `f` {
            d = int(ch - `a`) + 10
        } else if ch >= `A` && ch <= `F` {
            d = int(ch - `A`) + 10
        } else {
            return none
        }
        if d >= base {
            return none
        }
        value = value * base + d
    }
    return value
}

// is_bare_generic_param reports whether is bare generic param applies in types.
fn is_bare_generic_param(typ string) bool {
    return typ.len == 1 && typ[0] >= `A` && typ[0] <= `Z`
}

fn generic_param_index(name string) int {
    return match name {
        'T', 'A', 'K', 'X' { 0 }
        'U', 'B', 'V', 'Y' { 1 }
        'C', 'W', 'Z' { 2 }
        else { 0 }
    }
}

fn generic_placeholder_from_unknown(typ Unknown) ?string {
    start := typ.reason.index_u8(`\``)
    if start < 0 {
        return none
    }
    end := typ.reason[start + 1..].index_u8(`\``)
    if end < 0 {
        return none
    }
    name := typ.reason[start + 1..start + 1 + end]
    if !is_bare_generic_param(name) {
        return none
    }
    return name
}

fn (tc &TypeChecker) resolve_known_field_type(type_name string, fallback Type) Type {
    qname := tc.qualify_name(type_name)
    if qname in tc.structs {
        return Type(Struct{
            name: qname
        })
    }
    if type_name in tc.structs {
        return Type(Struct{
            name: type_name
        })
    }
    if qname in tc.interface_names {
        return Type(Interface{
            name: qname
        })
    }
    if type_name in tc.interface_names {
        return Type(Interface{
            name: type_name
        })
    }
    if qname in tc.type_aliases {
        return Type(Alias{
            name:      qname
            base_type: tc.parse_type(tc.type_aliases[qname])
        })
    }
    if type_name in tc.type_aliases {
        return Type(Alias{
            name:      type_name
            base_type: tc.parse_type(tc.type_aliases[type_name])
        })
    }
    return fallback
}

// type_name_known returns type name known data for TypeChecker.
fn (tc &TypeChecker) type_name_known(typ string) bool {
    if is_builtin_type_name(typ) || typ == 'unknown' || typ.starts_with('C.') {
        return true
    }
    qtyp := tc.qualify_name(typ)
    if !typ.contains('.') {
        if resolved := tc.resolve_selective_import_type_symbol(typ) {
            return tc.type_symbol_known(resolved)
        }
    }
    return typ in tc.type_aliases || qtyp in tc.type_aliases || typ in tc.structs
        || qtyp in tc.structs || typ in tc.interface_names || qtyp in tc.interface_names
        || typ in tc.enum_names || qtyp in tc.enum_names || typ in tc.sum_types
        || qtyp in tc.sum_types
}

fn (tc &TypeChecker) type_name_known_in_current_module(typ string) bool {
    qtyp := tc.qualify_name(typ)
    return qtyp in tc.type_aliases || qtyp in tc.structs || qtyp in tc.interface_names
        || qtyp in tc.enum_names || qtyp in tc.sum_types
}

// should_check_named_type reports whether should check named type applies in types.
fn should_check_named_type(typ string) bool {
    if typ.len == 0 {
        return false
    }
    for i in 0 .. typ.len {
        c := typ[i]
        if !((c >= `a` && c <= `z`) || (c >= `A` && c <= `Z`)
            || (c >= `0` && c <= `9`) || c == `_` || c == `.`) {
            return false
        }
    }
    return true
}

// check_struct_field_defaults validates check struct field defaults state for types.
fn (mut tc TypeChecker) check_struct_field_defaults(node flat.Node) {
    for i in 0 .. node.children_count {
        field := tc.a.child_node(&node, i)
        if field.kind != .field_decl || field.children_count == 0 {
            continue
        }
        default_id := tc.a.child(field, 0)
        expected := tc.parse_type(field.typ)
        tc.check_node(default_id)
        actual := tc.resolve_expr(default_id, expected)
        if !tc.type_compatible(actual, expected) {
            tc.type_mismatch(.assignment_mismatch,
                'cannot initialize field `${field.value}` with `${actual.name()}`; expected `${expected.name()}`',
                default_id)
        }
    }
}

// check_enum_field_values validates check enum field values state for types.
fn (mut tc TypeChecker) check_enum_field_values(node flat.Node) {
    for i in 0 .. node.children_count {
        field := tc.a.child_node(&node, i)
        if field.kind != .enum_field || field.children_count == 0 {
            continue
        }
        value_id := tc.a.child(field, 0)
        tc.check_node(value_id)
        value_type := tc.resolve_type(value_id)
        if value_type is Unknown {
            continue
        }
        if !value_type.is_integer() {
            tc.type_mismatch(.assignment_mismatch,
                'enum field `${field.value}` value must be integer, not `${value_type.name()}`',
                value_id)
        }
    }
}

// check_const_field_values validates check const field values state for types.
fn (mut tc TypeChecker) check_const_field_values(node flat.Node) {
    for i in 0 .. node.children_count {
        field := tc.a.child_node(&node, i)
        if field.kind != .const_field || field.children_count == 0 {
            continue
        }
        tc.check_node(tc.a.child(field, 0))
    }
}

// fn_body_definitely_returns supports fn body definitely returns handling for TypeChecker.
fn (tc &TypeChecker) fn_body_definitely_returns(node flat.Node) bool {
    for i in 0 .. node.children_count {
        child_id := tc.a.child(&node, i)
        child := tc.a.child_node(&node, i)
        if child.kind == .param {
            continue
        }
        if tc.stmt_definitely_returns(child_id) {
            return true
        }
    }
    return false
}

fn type_allows_implicit_return(typ Type) bool {
    if typ is Void {
        return true
    }
    if typ is OptionType {
        return typ.base_type is Void
    }
    if typ is ResultType {
        return typ.base_type is Void
    }
    return false
}

// valid_node_id supports valid node id handling for TypeChecker.
fn (tc &TypeChecker) valid_node_id(id flat.NodeId) bool {
    return int(id) >= 0 && tc.a != unsafe { nil } && int(id) < tc.a.nodes.len
}

// stmt_definitely_returns supports stmt definitely returns handling for TypeChecker.
fn (tc &TypeChecker) stmt_definitely_returns(id flat.NodeId) bool {
    if !tc.valid_node_id(id) {
        return false
    }
    node := tc.a.nodes[int(id)]
    match node.kind {
        .return_stmt {
            return true
        }
        .block {
            for i in 0 .. node.children_count {
                if tc.stmt_definitely_returns(tc.a.child(&node, i)) {
                    return true
                }
            }
            return false
        }
        .if_expr {
            if node.children_count < 3 {
                return false
            }
            return tc.stmt_definitely_returns(tc.a.child(&node, 1))
                && tc.stmt_definitely_returns(tc.a.child(&node, 2))
        }
        .match_stmt {
            if node.children_count < 2 {
                return false
            }
            mut has_else := false
            for i in 1 .. node.children_count {
                branch := tc.a.child_node(&node, i)
                if branch.kind != .match_branch {
                    return false
                }
                if branch.value == 'else' {
                    has_else = true
                }
                if !tc.match_branch_definitely_returns(branch) {
                    return false
                }
            }
            return has_else || tc.match_without_else_exhaustive_enum_returns(node)
        }
        else {
            return false
        }
    }
}

// match_covers_all_enum_variants reports whether a `match` over an enum subject
// lists every variant of that enum (so it is exhaustive without an `else`).
fn (tc &TypeChecker) match_covers_all_enum_variants(node flat.Node) bool {
    if node.children_count < 2 {
        return false
    }
    subject_type := unwrap_pointer(tc.resolve_type(tc.a.child(&node, 0)))
    mut enum_name := ''
    if subject_type is Enum {
        enum_name = subject_type.name
    } else {
        return false
    }
    // A `[flag]` enum value can hold combined or zero bits (`.read | .write`, `0`) that
    // no single-field branch covers, so listing every field is NOT exhaustive — such a
    // match needs an explicit `else`.
    if enum_name in tc.flag_enums {
        return false
    }
    all_fields := tc.enum_fields[enum_name] or { return false }
    if all_fields.len == 0 {
        return false
    }
    mut covered := map[string]bool{}
    for i in 1 .. node.children_count {
        branch := tc.a.child_node(&node, i)
        if branch.kind != .match_branch {
            return false
        }
        if branch.value == 'else' {
            return true
        }
        n_conds := branch.value.int()
        for j in 0 .. n_conds {
            cond := tc.a.child_node(branch, j)
            if cond.kind == .enum_val {
                covered[cond.value.all_after_last('.')] = true
            }
        }
    }
    for f in all_fields {
        if f !in covered {
            return false
        }
    }
    return true
}

// match_branch_definitely_returns
// supports helper handling in types.
fn (tc &TypeChecker) match_branch_definitely_returns(branch &flat.Node) bool {
    body_start := if branch.value == 'else' { 0 } else { branch.value.int() }
    for i in body_start .. branch.children_count {
        if tc.stmt_definitely_returns(tc.a.child(branch, i)) {
            return true
        }
    }
    return false
}

fn (tc &TypeChecker) match_without_else_exhaustive_enum_returns(node flat.Node) bool {
    subject_type := unwrap_pointer(tc.resolve_type(tc.a.child(&node, 0)))
    if subject_type is Enum {
        enum_name := tc.resolve_enum_name(subject_type.name) or { subject_type.name }
        if subject_type.is_flag || enum_name in tc.flag_enums {
            return false
        }
        fields := tc.enum_fields[enum_name] or { return false }
        if fields.len == 0 {
            return false
        }
        mut covered := map[string]bool{}
        for i in 1 .. node.children_count {
            branch := tc.a.child_node(&node, i)
            if branch.kind != .match_branch || branch.value == 'else' {
                return false
            }
            n_conds := branch.value.int()
            if n_conds <= 0 || n_conds > branch.children_count {
                return false
            }
            for j in 0 .. n_conds {
                cond := tc.a.child_node(branch, j)
                field := tc.match_enum_condition_field(cond, enum_name) or { return false }
                covered[field] = true
            }
        }
        for field in fields {
            if field !in covered {
                return false
            }
        }
        return true
    }
    return false
}

fn (tc &TypeChecker) match_enum_condition_field(cond &flat.Node, enum_name string) ?string {
    match cond.kind {
        .enum_val {
            field := cond.value.all_after_last('.')
            if tc.enum_value_matches(cond.value, enum_name) {
                return field
            }
        }
        .selector {
            if typ := tc.enum_selector_type(cond) {
                if typ is Enum {
                    cond_enum_name := tc.resolve_enum_name(typ.name) or { typ.name }
                    if cond_enum_name == enum_name && tc.enum_has_field(enum_name, cond.value) {
                        return cond.value
                    }
                }
            }
        }
        else {}
    }

    return none
}

// node_kind_id supports node kind id handling for types.
fn node_kind_id(node flat.Node) int {
    mut kind_id := node.kind_id
    if kind_id == 0 && int(node.kind) != 0 {
        kind_id = int(node.kind)
    }
    return kind_id
}

// check_node validates check node state for types.
fn (mut tc TypeChecker) check_node(id flat.NodeId) {
    idx := int(id)
    if idx < 0 {
        return
    }
    if idx >= tc.checking_nodes.len {
        tc.extend_node_caches(tc.a.nodes.len)
    }
    if idx < tc.checking_nodes.len {
        if tc.checking_nodes[idx] {
            return
        }
        tc.checking_nodes[idx] = true
        defer {
            tc.checking_nodes[idx] = false
        }
    }
    node := tc.a.nodes[idx]
    kind_id := node_kind_id(node)
    if kind_id == 1 || kind_id == 2 || kind_id == 3 || kind_id == 4 || kind_id == 5 || kind_id == 28
        || kind_id == 29 {
        return
    }
    if kind_id == 45 {
        tc.check_block(node)
        return
    }
    if node.kind == .comptime_if {
        tc.check_comptime_if(id, node)
        return
    }
    if kind_id == 46 {
        tc.check_for_stmt(node)
        return
    }
    if kind_id == 47 {
        tc.check_for_in_stmt(node)
        return
    }
    if kind_id == 41 {
        tc.check_decl_assign(id, node)
        return
    }
    if kind_id == 40 || kind_id == 42 || kind_id == 43 {
        tc.check_assign(id, node)
        return
    }
    if kind_id == 44 {
        tc.check_return(id, node)
        return
    }
    if kind_id == 12 {
        tc.check_call(id, node)
        return
    }
    if kind_id == 21 {
        tc.check_fn_literal(node)
        return
    }
    if kind_id == 32 {
        tc.check_lambda_expr(node)
        return
    }
    if kind_id == 15 {
        tc.check_if_expr(id, node)
        return
    }
    if kind_id == 22 {
        tc.check_or_expr(node)
        return
    }
    if kind_id == 50 {
        tc.check_match_stmt(id, node)
        return
    }
    if kind_id == 37 {
        tc.check_is_expr(id, node)
        return
    }
    if kind_id == 10 {
        tc.check_postfix(id, node)
        return
    }
    if kind_id == 16 || kind_id == 26 {
        tc.check_struct_init(id, node)
        return
    }
    if kind_id == 13 {
        tc.check_selector(id, node)
        return
    }
    if kind_id == 14 {
        tc.check_index(id, node)
        return
    }
    if kind_id == 7 {
        tc.check_ident(id, node)
        return
    }
    if node.kind == .array_init {
        tc.check_array_init(node)
        return
    }
    if node.kind == .select_stmt {
        tc.check_select_stmt(node)
        return
    }
    // A method value stored in a container escapes the single-use guarantee of its per-site
    // static receiver, so reject `[obj.method]` / `arr << obj.method` / `{'k': obj.method}`.
    if node.kind == .array_literal {
        for i in 0 .. node.children_count {
            tc.reject_stored_method_value(tc.a.child(&node, i))
            tc.reject_stored_capturing_fn_literal(tc.a.child(&node, i))
        }
    } else if node.kind == .map_init {
        // children alternate key, value, key, value, ...; check the value positions.
        for j := 1; j < node.children_count; j += 2 {
            tc.reject_stored_method_value(tc.a.child(&node, j))
            tc.reject_stored_capturing_fn_literal(tc.a.child(&node, j))
        }
    } else if node.kind == .infix && node.op == .left_shift && node.children_count >= 2 {
        if unwrap_pointer(tc.resolve_type(tc.a.child(&node, 0))) is Array {
            tc.reject_stored_method_value(tc.a.child(&node, 1))
            tc.reject_stored_capturing_fn_literal(tc.a.child(&node, 1))
        }
    }

    for i in 0 .. node.children_count {
        tc.check_node(tc.a.child(&node, i))
    }
}

fn (mut tc TypeChecker) check_comptime_if(_id flat.NodeId, node flat.Node) {
    take_then := tc.comptime_type_condition_value(node.value) or { return }
    branch_index := if take_then { 0 } else { 1 }
    if branch_index >= node.children_count {
        return
    }
    tc.check_node(tc.a.child(&node, branch_index))
}

fn (mut tc TypeChecker) comptime_type_condition_value(cond string) ?bool {
    clean := comptime_condition_strip_outer_parens(cond)
    if clean == 'true' {
        return true
    }
    if clean == 'false' {
        return false
    }
    or_idx := comptime_condition_top_level_index(clean, '||')
    if or_idx >= 0 {
        left := tc.comptime_type_condition_value(clean[..or_idx]) or { return none }
        if left {
            return true
        }
        return tc.comptime_type_condition_value(clean[or_idx + 2..])
    }
    and_idx := comptime_condition_top_level_index(clean, '&&')
    if and_idx >= 0 {
        left := tc.comptime_type_condition_value(clean[..and_idx]) or { return none }
        if !left {
            return false
        }
        return tc.comptime_type_condition_value(clean[and_idx + 2..])
    }
    for op in [' !is ', ' is '] {
        op_idx := comptime_condition_top_level_index(clean, op)
        if op_idx >= 0 {
            left := clean[..op_idx].trim_space()
            right := clean[op_idx + op.len..].trim_space()
            matches := tc.comptime_type_matches(left, right) or { return none }
            return if op == ' is ' { matches } else { !matches }
        }
    }
    if clean.starts_with('!') {
        value := tc.comptime_type_condition_value(clean[1..]) or { return none }
        return !value
    }
    return none
}

fn (mut tc TypeChecker) comptime_type_matches(actual string, expected string) ?bool {
    clean_actual := actual.trim_space()
    clean_expected := expected.trim_space()
    if clean_actual.len == 0 || clean_expected.len == 0
        || (is_bare_generic_param(clean_actual) && !tc.type_name_known(clean_actual)) {
        return none
    }
    actual_type := tc.comptime_type_match_type(clean_actual)
    normalized := actual_type.name()
    match clean_expected {
        '$array' {
            return actual_type is Array || actual_type is ArrayFixed
        }
        '$map' {
            return actual_type is Map
        }
        '$function' {
            return actual_type is FnType
        }
        '$option' {
            return actual_type is OptionType
        }
        '$int' {
            return actual_type.is_integer()
        }
        '$float' {
            return actual_type.is_float()
        }
        '$struct' {
            return normalized in tc.structs
        }
        '$enum' {
            return normalized in tc.enum_names
        }
        '$alias' {
            return clean_actual in tc.type_aliases
                || tc.qualify_name(clean_actual) in tc.type_aliases
        }
        '$sumtype' {
            return normalized in tc.sum_types
        }
        '$interface' {
            return normalized in tc.interface_names
        }
        else {}
    }

    expected_type := tc.comptime_type_match_type(clean_expected)
    return normalized == expected_type.name()
}

fn (mut tc TypeChecker) comptime_type_match_type(type_text string) Type {
    typ := tc.parse_type(type_text)
    if typ is Alias {
        return typ.base_type
    }
    return typ
}

fn comptime_condition_matching_paren(s string, start int) int {
    mut paren_depth := 0
    mut bracket_depth := 0
    for i in start .. s.len {
        match s[i] {
            `(` {
                paren_depth++
            }
            `)` {
                paren_depth--
                if paren_depth == 0 && bracket_depth == 0 {
                    return i
                }
            }
            `[` {
                bracket_depth++
            }
            `]` {
                bracket_depth--
            }
            else {}
        }
    }
    return s.len
}

fn comptime_condition_strip_outer_parens(cond string) string {
    mut clean := cond.trim_space()
    for clean.len >= 2 && clean.starts_with('(') {
        end := comptime_condition_matching_paren(clean, 0)
        if end != clean.len - 1 {
            break
        }
        clean = clean[1..clean.len - 1].trim_space()
    }
    return clean
}

fn comptime_condition_top_level_index(s string, needle string) int {
    if needle.len == 0 || s.len < needle.len {
        return -1
    }
    mut paren_depth := 0
    mut bracket_depth := 0
    for i := 0; i <= s.len - needle.len; i++ {
        match s[i] {
            `(` {
                paren_depth++
            }
            `)` {
                if paren_depth > 0 {
                    paren_depth--
                }
            }
            `[` {
                bracket_depth++
            }
            `]` {
                if bracket_depth > 0 {
                    bracket_depth--
                }
            }
            else {}
        }

        if paren_depth == 0 && bracket_depth == 0 && s[i..].starts_with(needle) {
            return i
        }
    }
    return -1
}

// check_select_stmt validates a `select { ... }` statement. A receive branch
// `val := <-ch` binds `val` (the channel's element type) in the branch body's
// scope; other branches (sends, bare conditions, `else`) are checked as-is.
fn (mut tc TypeChecker) check_select_stmt(node flat.Node) {
    for i in 0 .. node.children_count {
        branch_id := tc.a.child(&node, i)
        if !tc.valid_node_id(branch_id) {
            continue
        }
        branch := tc.a.nodes[int(branch_id)]
        if branch.kind != .select_branch {
            tc.check_node(branch_id)
            continue
        }
        tc.push_scope()
        mut body_start := 0
        if branch.value == 'recv' && branch.children_count >= 2 {
            // children[0] = bound var ident, children[1] = `<-ch` receive expr.
            var_id := tc.a.child(&branch, 0)
            recv_id := tc.a.child(&branch, 1)
            tc.check_node(recv_id)
            elem_type := tc.resolve_type(recv_id)
            if tc.valid_node_id(var_id) {
                var_node := tc.a.nodes[int(var_id)]
                if var_node.kind == .ident && var_node.value.len > 0 {
                    tc.cur_scope.insert(var_node.value, elem_type)
                }
            }
            body_start = 2
        }
        tc.check_statement_sequence(branch, body_start, false)
        tc.pop_scope()
    }
}

// check_array_init validates an `[]T{len: ..., init: ...}` initializer. The `init:`
// expression may reference the magic `index` variable (the current element index),
// so it is checked in a scope where `index` is bound to an int.
fn (mut tc TypeChecker) check_array_init(node flat.Node) {
    for i in 0 .. node.children_count {
        child_id := tc.a.child(&node, i)
        child := tc.a.nodes[int(child_id)]
        if child.kind == .field_init && child.value == 'init' {
            if child.children_count > 0 {
                tc.reject_stored_method_value(tc.a.child(&child, 0))
                tc.reject_stored_capturing_fn_literal(tc.a.child(&child, 0))
            }
            tc.push_scope()
            tc.cur_scope.insert('index', Type(int_))
            tc.check_node(child_id)
            tc.pop_scope()
        } else {
            tc.check_node(child_id)
        }
    }
}

// check_or_expr validates check or expr state for types.
fn (mut tc TypeChecker) check_or_expr(node flat.Node) {
    if node.children_count == 0 {
        return
    }
    inner_id := tc.a.child(&node, 0)
    tc.check_node(inner_id)
    if node.children_count < 2 || node.value in ['!', '?'] {
        return
    }
    tc.push_scope()
    tc.cur_scope.insert('err', tc.parse_type('IError'))
    tc.check_branch_node(tc.a.child(&node, 1), true)
    tc.pop_scope()
}

// check_fn_literal validates check fn literal state for types.
fn (mut tc TypeChecker) check_fn_literal(node flat.Node) {
    saved_ret := tc.cur_fn_ret_type
    tc.cur_fn_ret_type = tc.parse_type(node.typ)
    tc.push_scope()
    for i in 0 .. node.children_count {
        child := tc.a.child_node(&node, i)
        if child.kind == .param && child.value.len > 0 {
            tc.cur_scope.insert(child.value, tc.parse_type(child.typ))
        }
    }
    for i in 0 .. node.children_count {
        child_id := tc.a.child(&node, i)
        child := tc.a.nodes[int(child_id)]
        if child.kind == .param || child.kind == .ident {
            continue
        }
        tc.check_stmt_node(child_id)
    }
    tc.pop_scope()
    tc.cur_fn_ret_type = saved_ret
}

// check_lambda_expr validates check lambda expr state for types.
fn (mut tc TypeChecker) check_lambda_expr(node flat.Node) {
    if node.children_count == 0 {
        return
    }
    tc.push_scope()
    for i in 0 .. node.children_count - 1 {
        child := tc.a.child_node(&node, i)
        if child.kind == .ident && child.value.len > 0 {
            tc.cur_scope.insert(child.value, unknown_type('lambda parameter `${child.value}`'))
        }
    }
    tc.check_node(tc.a.child(&node, node.children_count - 1))
    tc.pop_scope()
}

// check_block validates check block state for types.
fn (mut tc TypeChecker) check_block(node flat.Node) {
    tc.push_scope()
    tc.check_statement_sequence(node, 0, false)
    tc.pop_scope()
}

// check_for_stmt validates check for stmt state for types.
fn (mut tc TypeChecker) check_for_stmt(node flat.Node) {
    tc.push_scope()
    if node.children_count > 0 {
        init_id := tc.a.child(&node, 0)
        if int(init_id) >= 0 {
            tc.check_node(init_id)
        }
    }
    if node.children_count > 1 {
        cond_id := tc.a.child(&node, 1)
        if int(cond_id) >= 0 {
            tc.check_bool_condition(cond_id)
        }
    }
    if node.children_count > 2 {
        post_id := tc.a.child(&node, 2)
        if int(post_id) >= 0 {
            tc.check_node(post_id)
        }
    }
    for i in 3 .. node.children_count {
        tc.check_stmt_node(tc.a.child(&node, i))
    }
    tc.pop_scope()
}

// check_for_in_stmt validates check for in stmt state for types.
fn (mut tc TypeChecker) check_for_in_stmt(node flat.Node) {
    header := node.value.int()
    if header < 3 || node.children_count < 3 {
        return
    }
    tc.push_scope()
    key_id := tc.a.child(&node, 0)
    val_id := tc.a.child(&node, 1)
    container_id := tc.a.child(&node, 2)
    tc.check_node(container_id)
    has_val := int(val_id) >= 0
    if header == 4 {
        tc.insert_loop_var(key_id, tc.range_loop_var_type(container_id))
        tc.check_node(tc.a.child(&node, 3))
    } else {
        clean := unwrap_pointer(tc.resolve_type(container_id))
        if clean is Array {
            if has_val {
                tc.insert_loop_var(key_id, Type(int_))
                tc.insert_loop_var(val_id, clean.elem_type)
            } else {
                tc.insert_loop_var(key_id, clean.elem_type)
            }
        } else if clean is ArrayFixed {
            if has_val {
                tc.insert_loop_var(key_id, Type(int_))
                tc.insert_loop_var(val_id, clean.elem_type)
            } else {
                tc.insert_loop_var(key_id, clean.elem_type)
            }
        } else if clean is Map {
            if has_val {
                tc.insert_loop_var(key_id, clean.key_type)
                tc.insert_loop_var(val_id, clean.value_type)
            } else {
                tc.insert_loop_var(key_id, clean.value_type)
            }
        } else if clean is String {
            if has_val {
                tc.insert_loop_var(key_id, Type(int_))
                tc.insert_loop_var(val_id, Type(u8_))
            } else {
                tc.insert_loop_var(key_id, Type(u8_))
            }
        } else if elem_type := iterator_for_in_elem_type(clean) {
            if has_val {
                tc.insert_loop_var(key_id, Type(int_))
                tc.insert_loop_var(val_id, elem_type)
            } else {
                tc.insert_loop_var(key_id, elem_type)
            }
        } else {
            container := tc.a.nodes[int(container_id)]
            if container.kind == .range {
                tc.insert_loop_var(key_id, tc.range_loop_var_type(tc.a.child(&container, 0)))
            } else if tc.should_diagnose(container_id) {
                tc.record_error(.cannot_index, 'cannot iterate over `${clean.name()}`',
                    container_id)
            }
        }
    }
    for i in header .. node.children_count {
        tc.check_stmt_node(tc.a.child(&node, i))
    }
    tc.pop_scope()
}

// check_decl_assign validates check decl assign state for types.
fn (mut tc TypeChecker) check_decl_assign(id flat.NodeId, node flat.Node) {
    if node.children_count == 0 {
        return
    }
    if tc.check_multi_return_decl_assign(id, node) {
        return
    }
    mut i := 0
    for i + 1 < node.children_count {
        lhs_id := tc.a.child(&node, i)
        rhs_id := tc.a.child(&node, i + 1)
        tc.check_node(rhs_id)
        mut rhs_type := tc.decl_assign_inferred_type(rhs_id)
        mut expected := rhs_type
        if node.children_count == 2 && node.typ.len > 0 {
            expected = tc.parse_type(node.typ)
            rhs_type = tc.resolve_expr(rhs_id, expected)
            if !tc.type_compatible(rhs_type, expected) {
                tc.type_mismatch(.assignment_mismatch,
                    'cannot assign `${rhs_type.name()}` to `${expected.name()}`', id)
            }
        }
        tc.insert_decl_lhs(lhs_id, expected)
        tc.track_method_value_local(lhs_id, rhs_id)
        tc.reject_stored_capturing_fn_literal(rhs_id)
        i += 2
    }
}

// cur_scope_depth returns the number of enclosing scopes (the current scope's parent-chain
// length), used to tell a dominating top-level reassignment from one nested in a branch/loop.
fn (tc &TypeChecker) cur_scope_depth() int {
    mut d := 0
    mut s := tc.cur_scope
    for s != unsafe { nil } {
        d++
        s = s.parent
    }
    return d
}

// track_method_value_local records (or clears) a local variable bound to a method value, so a
// later `return cb` / `arr << cb` aliasing the same per-site static receiver is rejected as an
// escape just like the bare `return c.report`.
fn (mut tc TypeChecker) track_method_value_local(lhs_id flat.NodeId, rhs_id flat.NodeId) {
    if int(lhs_id) < 0 {
        return
    }
    lhs := tc.a.nodes[int(lhs_id)]
    if lhs.kind != .ident || lhs.value.len == 0 || lhs.value == '_' {
        return
    }
    if tc.expr_is_method_value(rhs_id) {
        tc.method_value_locals[lhs.value] = true
        tc.method_value_local_depth[lhs.value] = tc.cur_scope_depth()
    } else if lhs.value in tc.method_value_locals {
        // Reassigned to a non-method-value. Only clear the marker when this reassignment
        // dominates later uses — at the same or a shallower scope than where the local was
        // marked. A reassignment in a deeper conditional/loop scope does not run on every path
        // (`mut cb := c.report; if x { cb = plain }; return cb`), so the local may still hold the
        // method value; keep the maybe-method marker and let the later escape be rejected.
        marked_depth := tc.method_value_local_depth[lhs.value] or { 0 }
        if tc.cur_scope_depth() <= marked_depth {
            tc.method_value_locals.delete(lhs.value)
            tc.method_value_local_depth.delete(lhs.value)
        }
    }
}

fn (mut tc TypeChecker) decl_assign_inferred_type(rhs_id flat.NodeId) Type {
    if int(rhs_id) < 0 || int(rhs_id) >= tc.a.nodes.len {
        return unknown_type('missing declaration initializer')
    }
    rhs := tc.a.nodes[int(rhs_id)]
    if rhs.kind == .cast_expr && rhs.value.len > 0 {
        typ := tc.parse_type(rhs.value)
        if typ is Alias {
            return typ
        }
    }
    if typ := tc.infer_fn_value_decl_type(rhs_id) {
        return typ
    }
    return tc.resolve_type(rhs_id)
}

fn (mut tc TypeChecker) infer_fn_value_decl_type(rhs_id flat.NodeId) ?Type {
    if int(rhs_id) < 0 || int(rhs_id) >= tc.a.nodes.len {
        return none
    }
    rhs := tc.a.nodes[int(rhs_id)]
    if tc.fn_value_shadowed_by_value(rhs) {
        return none
    }
    key := tc.fn_value_key(rhs) or { return none }
    typ := tc.fn_type_from_key(key) or { return none }
    tc.remember_resolved_fn_value_chain(rhs_id, key)
    tc.register_synth_type(rhs_id, typ)
    return typ
}

fn (tc &TypeChecker) fn_value_shadowed_by_value(node flat.Node) bool {
    match node.kind {
        .ident {
            return tc.name_bound_as_value(node.value)
        }
        .selector {
            return tc.selector_base_bound_as_value(node)
        }
        .cast_expr, .paren, .expr_stmt {
            if node.children_count == 0 {
                return false
            }
            return tc.fn_value_shadowed_by_value(tc.a.child_node(&node, 0))
        }
        else {
            return false
        }
    }
}

// lvalue_is_local_var reports whether an assignment target is safe to receive a method value:
// the blank discard `_` (stores nothing) or a plain function-local variable bound under its bare
// name in the current scope. Non-local storage (a struct field `h.cb`, an array/map element
// `cbs[i]`, or a module-level global, which lives in file_scope under its qualified name and so
// misses a bare lookup) is not. A method value may alias a local (tracked for a later escape) but
// must not be stored into anything that outlives the call site.
fn (tc &TypeChecker) lvalue_is_local_var(lhs_id flat.NodeId) bool {
    if int(lhs_id) < 0 {
        return false
    }
    lhs := tc.a.nodes[int(lhs_id)]
    if lhs.kind != .ident || lhs.value.len == 0 {
        return false
    }
    if lhs.value == '_' {
        return true
    }
    return tc.cur_scope.lookup(lhs.value) != none
}

fn (tc &TypeChecker) selector_base_bound_as_value(node flat.Node) bool {
    if node.children_count == 0 {
        return false
    }
    base := tc.a.child_node(&node, 0)
    match base.kind {
        .ident {
            return tc.name_bound_as_value(base.value)
        }
        .selector {
            return tc.selector_base_bound_as_value(base)
        }
        .cast_expr, .paren, .expr_stmt {
            if base.children_count == 0 {
                return false
            }
            return tc.fn_value_shadowed_by_value(tc.a.child_node(base, 0))
        }
        else {
            return false
        }
    }
}

fn (tc &TypeChecker) name_bound_as_value(name string) bool {
    if name.len == 0 {
        return false
    }
    if typ := tc.cur_scope.lookup(name) {
        return typ !is Void
    }
    if typ := tc.file_scope.lookup(name) {
        return typ !is Void
    }
    return false
}

// check_multi_return_decl_assign validates check multi return decl assign state for types.
fn (mut tc TypeChecker) check_multi_return_decl_assign(id flat.NodeId, node flat.Node) bool {
    if node.children_count < 3 {
        return false
    }
    rhs_id := tc.a.child(&node, 1)
    rhs_type := tc.resolve_type(rhs_id)
    rhs_type_name := rhs_type.name()
    if rhs_type is MultiReturn {
        tc.check_node(rhs_id)
        lhs_ids := tc.multi_assign_lhs_ids(node)
        if lhs_ids.len != rhs_type.types.len {
            if tc.should_diagnose(id) {
                tc.record_error(.assignment_mismatch,
                    'multi-return assignment mismatch: ${lhs_ids.len} variables but `${rhs_type_name}` has ${rhs_type.types.len} values',
                    id)
            }
            return true
        }
        for i, lhs_id in lhs_ids {
            tc.insert_decl_lhs(lhs_id, rhs_type.types[i])
        }
        return true
    }
    return false
}

// multi_assign_lhs_ids supports multi assign lhs ids handling for TypeChecker.
fn (tc &TypeChecker) multi_assign_lhs_ids(node flat.Node) []flat.NodeId {
    mut lhs_ids := []flat.NodeId{}
    if node.children_count > 0 {
        lhs_ids << tc.a.child(&node, 0)
    }
    for i in 2 .. node.children_count {
        lhs_ids << tc.a.child(&node, i)
    }
    return lhs_ids
}

// insert_decl_lhs updates insert decl lhs state for types.
fn (mut tc TypeChecker) insert_decl_lhs(lhs_id flat.NodeId, typ Type) {
    if int(lhs_id) < 0 || typ is Void {
        return
    }
    lhs := tc.a.nodes[int(lhs_id)]
    if lhs.kind == .ident && lhs.value.len > 0 {
        tc.cur_scope.insert(lhs.value, typ)
        tc.register_synth_type(lhs_id, typ)
    }
}

// check_assign validates check assign state for types.
fn (mut tc TypeChecker) check_assign(id flat.NodeId, node flat.Node) {
    if node.children_count < 2 {
        return
    }
    if node.kind == .index_assign && tc.reject_unlowered_map_mutation
        && tc.index_assign_lhs_is_map(node) {
        if tc.should_diagnose(id) {
            tc.record_error(.assignment_mismatch,
                'internal compiler error: unlowered map index assignment reached post-transform checker',
                id)
        }
        for i := 1; i < node.children_count; i += 2 {
            tc.check_node(tc.a.child(&node, i))
        }
        return
    }
    if tc.check_multi_return_assign(id, node) {
        return
    }
    mut i := 0
    for i + 1 < node.children_count {
        lhs_id := tc.a.child(&node, i)
        rhs_id := tc.a.child(&node, i + 1)
        lhs_type := tc.resolve_lvalue_type(lhs_id)
        tc.check_node(rhs_id)
        rhs_type := tc.resolve_expr(rhs_id, lhs_type)
        if !tc.type_compatible(rhs_type, lhs_type) {
            tc.type_mismatch(.assignment_mismatch,
                'cannot assign `${rhs_type.name()}` to `${lhs_type.name()}`', id)
        }
        if node.kind in [.assign, .selector_assign, .index_assign] {
            if tc.expr_is_method_value(rhs_id) && !tc.lvalue_is_local_var(lhs_id) {
                // Storing a method value into a struct field (`h.cb = ..`), an array/map element
                // (`cbs[i] = ..`), or a global lets it outlive the per-site static `_mvctx_N`
                // receiver slot, which the next evaluation of the same site overwrites — so every
                // stored callback would use the last receiver. Reject it like the other escapes.
                tc.reject_stored_method_value(rhs_id)
            } else {
                tc.track_method_value_local(lhs_id, rhs_id)
            }
            tc.reject_stored_capturing_fn_literal(rhs_id)
        }
        i += 2
    }
}

// index_assign_lhs_is_map supports index assign lhs is map handling for TypeChecker.
fn (tc &TypeChecker) index_assign_lhs_is_map(node flat.Node) bool {
    if node.children_count == 0 {
        return false
    }
    lhs_id := tc.a.child(&node, 0)
    if int(lhs_id) < 0 {
        return false
    }
    lhs := tc.a.nodes[int(lhs_id)]
    if lhs.kind != .index || lhs.children_count < 2 {
        return false
    }
    base_type := unwrap_pointer(tc.resolve_type(tc.a.child(&lhs, 0)))
    return base_type is Map
}

// check_multi_return_assign validates check multi return assign state for types.
fn (mut tc TypeChecker) check_multi_return_assign(id flat.NodeId, node flat.Node) bool {
    if node.children_count < 3 {
        return false
    }
    rhs_id := tc.a.child(&node, 1)
    rhs_type := tc.resolve_type(rhs_id)
    rhs_type_name := rhs_type.name()
    if rhs_type is MultiReturn {
        tc.check_node(rhs_id)
        lhs_ids := tc.multi_assign_lhs_ids(node)
        if lhs_ids.len != rhs_type.types.len {
            if tc.should_diagnose(id) {
                tc.record_error(.assignment_mismatch,
                    'multi-return assignment mismatch: ${lhs_ids.len} variables but `${rhs_type_name}` has ${rhs_type.types.len} values',
                    id)
            }
            return true
        }
        for i, lhs_id in lhs_ids {
            lhs_type := tc.resolve_lvalue_type(lhs_id)
            if !tc.type_compatible(rhs_type.types[i], lhs_type) {
                tc.type_mismatch(.assignment_mismatch,
                    'cannot