vj-codegen 0.1.0

//! Function lowering: a leaf `function automatic` (integral args + integral
//! return) becomes one LLVM function -- entry block, alloca+store each
//! argument into `locals`, lower the body's statements, verify.
//!
//! Task 26 (CG-121): `lower_stmt` is now `pub` and exhaustively dispatches
//! the whole procedural-statement surface named by CG-121's acceptance --
//! `if`/`case` (all three comparison modes)/`for`/`while`/`do-while`/
//! `foreach`/`repeat`/a block/a blocking assignment/a task call -- falling
//! through to a named `LoweringError` (never a panic, never a silent no-op)
//! for anything still out of scope (`forever` with no `disable`/`break`
//! escape, `case ... inside`, more-than-one-dimension `foreach`, ...).
//!
//! Deviation from the plan (discovered implementing this task): `lower_stmt`
//! now needs `&mut LowerCtx` rather than `&LowerCtx` -- a `for` loop with a
//! declared loop variable (`for (int i = 0; ...)`) and a `foreach` loop's own
//! iterator variable both introduce a brand-new `locals` entry mid-lowering,
//! which an immutable borrow can't do. `lower_expr` (`expr.rs`) keeps its
//! existing `&LowerCtx` signature unchanged (Rust's built-in `&mut T -> &T`
//! coercion makes every existing call site still compile unchanged).
//!
//! Task 27 (CG-172): `wait fork`/`disable fork`/`wait_order(...)` each get
//! their own distinct `StatementKind` arm below, hard-erroring with a
//! construct-specific message at compile time (fork/join semantics are
//! unresolved in this crate) -- never falling through the generic
//! `other =>` arm indistinguishably from any other unhandled kind.
use crate::types::TypeWidth;
use std::collections::HashMap;
use sv_sim_sim::symid::SymbolUid;

use inkwell::context::Context;
use inkwell::module::{Linkage, Module};
use inkwell::types::FunctionType;
use inkwell::values::{FunctionValue, PointerValue};

use sv_lang::MethodFlags;
use sv_lang::kinds::{ExpressionKind, StatementKind, SymbolKind};

use crate::error::LoweringError;
use crate::expr::{LowerCtx, LoweredValue, lower_expr};
use crate::mangle::{self, EntityTag};
use crate::ops::OpBuilder;
use crate::stmt_shared::{
    current_block_and_fn, current_block_terminated, lower_case, lower_do_while_loop,
    lower_for_loop, lower_foreach_loop, lower_forever_loop, lower_loop_jump, lower_repeat_loop,
    lower_while_loop,
};
use crate::types::lower_type;
use crate::value::{PackedValue, ValueRepr};

// Deviation from plan (discovered running this task, not in the preflight
// corrections): the plan wrote `sym: &sv_lang::Symbol<'ctx>`, reusing the
// LLVM context lifetime for the sv-lang design lifetime too. That forces
// the caller's `Design` local to live as long as the `Context`/`Module`
// locals -- concretely, `cargo test` fails with "`d` does not live long
// enough" the moment `ctx`, `module`, and `d` are three independent local
// bindings (exactly Task 8's own test). Give the sv-lang side its own `'d`,
// matching the `LowerCtx<'ctx, 'd>` split in `expr.rs`.
/// Computes the LLVM function TYPE (and whether `sym` is a void subroutine)
/// for `sym` -- the pure signature half of what [`lower_function`] used to
/// do in one shot, extracted (R-run Task 10 review fix r2, finding 1) so
/// `pipeline::build_pipeline`'s subroutine pre-pass can DECLARE every
/// subroutine's signature (`module.add_function(<mangled>, fn_ty, None)`)
/// under its final mangled name in a first sub-pass, before lowering any
/// body in a second sub-pass. That ordering is what makes a same-pipeline
/// forward reference (subroutine A's body, lowered in the second sub-pass,
/// calling a distinct subroutine B whose own body hasn't been lowered yet)
/// resolve -- via `func::resolve_callee_fn`'s case 2 (same shared module, by
/// mangled name) -- to the SAME `FunctionValue` the second sub-pass will
/// later fill a body into, rather than falling through to
/// `resolve_callee_fn`'s case 3 (a fresh, genuinely-cross-module `extern`
/// declaration): under the OLD single-pass scheme, that case-3 stub was
/// created under B's own mangled name before the pre-pass ever reached B's
/// own spec, so the pre-pass's own dedup check (`module.get_function(&
/// mangled).is_some()`) saw that name already "present" and skipped
/// lowering B's body for good, leaving B a dangling `declare`-only function
/// (JIT symbol resolution failure, not caught by `module.verify()`, since a
/// call to a declared-but-undefined function is valid LLVM IR).
///
/// Kept `pub(crate)` (used only by [`lower_function`], `pipeline.rs` and
/// `classes.rs`, not a public API surface of its own).
///
/// Classes plan Task 5 (§1.3): `receiver` is `true` for a class method
/// (`classes::method_fn_type` passes `true`; every pre-existing caller --
/// an ordinary, non-method subroutine -- passes `false`, unchanged
/// behavior). When `true`, the LLVM signature gains one leading `i64`
/// parameter (the receiver object handle) before every SV argument/hidden
/// ABI parameter this function already computes -- [`lower_function_body`]'s
/// own `this_var` parameter is what actually reads it back out at index 0
/// and stores it into `locals`.
pub(crate) fn subroutine_fn_type<'ctx, 'd>(
    ctx: &'ctx Context,
    sym: &sv_lang::Symbol<'d>,
    repr: ValueRepr,
    receiver: bool,
) -> Result<(FunctionType<'ctx>, bool), LoweringError> {
    // Corrected vs. plan: `subroutine_arguments()` returns a plain, single-
    // pass `impl Iterator<Item = Symbol<'d>>`, not a Vec/slice -- it has no
    // `&args` `IntoIterator` impl and can't be iterated twice. Collect it
    // once so both this pass and [`lower_function_body`]'s own alloca/store
    // pass can each iterate it independently.
    let args: Vec<sv_lang::Symbol<'d>> = sym.subroutine_arguments().collect();

    // R-run Task 10: a VOID subroutine (a `task` with no return value at
    // all) is `subroutine_return_type().is_some_and(|t| t.is_void())` --
    // NOT `None` (corrected vs. an earlier draft of this task: sv-lang
    // still hands back `Some(<void Type>)` for a task, never `None`;
    // `Type::is_void()` is the real signal `lower_type` itself has no arm
    // for at all -- it only ever produces an `Int`/`Float` `LoweredType`).
    // A `function`, per LRM 1800-2023 §13.4.1, always declares a NON-void
    // return type (the implicit default is a 1-bit `logic`). Task 10's own
    // target fixture (`function_task.sv`'s `show` task) needs this: a void
    // task lowers to a real `void`-returning LLVM function instead of an
    // unconditional rejection.
    let ret_sv = sym.subroutine_return_type();
    let is_void_return = ret_sv.as_ref().is_none_or(sv_lang::Type::is_void);

    let ptr_ty = ctx.ptr_type(inkwell::AddressSpace::default());
    let mut param_tys = Vec::new();
    if receiver {
        param_tys.push(ctx.i64_type().into());
    }
    for a in &args {
        let t = a
            .value_type()
            .ok_or_else(|| LoweringError::unsupported_at("arg has no type", a))?;
        if is_by_reference(a) || crate::arrays::array_shape(&t).is_some() {
            // output / inout / ref, and every unpacked array: a pointer to
            // the caller's temporary.
            param_tys.push(ptr_ty.into());
        } else if crate::huge::is_image_type(&t) {
            // Wider than an LLVM integer: a pointer to the caller's copy.
            param_tys.push(ptr_ty.into());
        } else {
            param_tys.push(lower_type(ctx, &t, repr)?.into_basic_metadata_type_enum());
        }
    }
    let abi = subroutine_abi(sym);
    for _ in &abi.signals {
        param_tys.push(ptr_ty.into());
    }
    if abi.needs_handle {
        param_tys.push(ptr_ty.into());
    }
    // An unpacked-array result is written through a trailing pointer to
    // the caller's temporary; the LLVM function returns nothing.
    // A result wider than an LLVM integer is written the same way, as an image.
    let returns_array =
        array_result(sym).is_some() || ret_sv.as_ref().is_some_and(crate::huge::is_image_type);
    if returns_array {
        param_tys.push(ptr_ty.into());
    }

    let fn_ty = if is_void_return || returns_array {
        ctx.void_type().fn_type(&param_tys, false)
    } else {
        lower_type(ctx, ret_sv.as_ref().unwrap(), repr)?.fn_type(&param_tys, false)
    };
    Ok((fn_ty, is_void_return || returns_array))
}

/// Lowers `sym`'s BODY into an already-declared `f` (its LLVM type must
/// already match [`subroutine_fn_type`]'s own -- true both for
/// [`lower_function`]'s own immediately-preceding `add_function` call and
/// for `pipeline::build_pipeline`'s subroutine pre-pass, which declares `f`
/// via that exact same `subroutine_fn_type` call before ever reaching this
/// function). Extracted from [`lower_function`] (R-run Task 10 review fix
/// r2, finding 1) so the pre-pass can attach a body to the SAME
/// `FunctionValue` object every same-pipeline caller's call site already
/// resolved against (`func::resolve_callee_fn`'s case 2), instead of
/// `lower_function` creating an unrelated, freshly-`add_function`-ed
/// `FunctionValue` under a different name that a caller's already-emitted
/// `call` instruction has no way to retarget.
/// Classes plan Task 5 (§1.3): `this_var` is `Some(<class_this_var()>)` for
/// a class method (`classes::lower_method_body` passes it; every
/// pre-existing caller passes `None`, unchanged behavior) -- `f` must then
/// already have been declared via [`subroutine_fn_type`]`(.., receiver:
/// true)`, with its own leading `i64` receiver parameter. This function
/// reads that parameter back out of `f.get_nth_param(0)` and stores it into
/// `locals` under `this_var`'s own key, so the ordinary `NamedValue` arm
/// (`expr.rs`) that already reads any other `locals` entry transparently
/// handles a bare `this` read with no code of its own -- every OTHER
/// `get_nth_param` index below is shifted by one (`base`) to skip over this
/// extra leading parameter.
pub(crate) fn lower_function_body<'ctx, 'd>(
    ctx: &'ctx Context,
    module: &Module<'ctx>,
    sym: &sv_lang::Symbol<'d>,
    repr: ValueRepr,
    f: FunctionValue<'ctx>,
    this_var: Option<sv_lang::Symbol<'d>>,
) -> Result<FunctionValue<'ctx>, LoweringError> {
    let base: u32 = u32::from(this_var.is_some());
    let args: Vec<sv_lang::Symbol<'d>> = sym.subroutine_arguments().collect();
    let ret_sv = sym.subroutine_return_type();
    let ret_array = array_result(sym);
    let ret_image = ret_sv.as_ref().is_some_and(crate::huge::is_image_type);
    let is_void_return =
        ret_sv.as_ref().is_none_or(sv_lang::Type::is_void) || ret_array.is_some() || ret_image;

    let b = ctx.create_builder();
    b.position_at_end(ctx.append_basic_block(f, "entry"));

    let mut locals = HashMap::new();
    let mut out_inits: Vec<sv_lang::Symbol<'d>> = Vec::new();
    for (i, a) in args.iter().enumerate() {
        let t = a
            .value_type()
            .ok_or_else(|| LoweringError::unsupported_at("arg has no type", a))?;
        // An event handle is passed by value only (LRM 1800-2023 15.5.5.1).
        if t.is_event() && a.formal_argument_direction() != sv_lang::ArgumentDirection::In {
            return Err(LoweringError::unsupported_at(
                "an output, inout or ref event argument (events are passed by value, \
                 LRM 1800-2023 15.5.5.1; only input event arguments are supported)",
                a,
            ));
        }
        // Task 8 (CG-037) scope note: a `real`-typed function ARGUMENT is
        // deliberately not implemented by this task -- `locals` (and
        // `expr.rs`'s `NamedValue` arm that reads it) only ever holds an
        // integral slot's (width, signed) metadata, which has no meaning
        // for a float. CG-037's acceptance is int<->real *Conversion node*
        // lowering (a literal or an already-lowered integral/real
        // sub-expression), not real-typed parameter passing, so this is a
        // named, loud `LoweringError` here rather than a panic from an
        // `into_int_value()` call on what would actually be a `FloatValue`.
        if t.is_floating() && !is_by_reference(a) {
            // A real formal is stored like a real variable: its IEEE bits
            // (`crate::real`).
            let width = t.value_width();
            let param = f.get_nth_param(base + i as u32).unwrap().into_float_value();
            let bits_ty = crate::types::int_type(ctx, width);
            let bits = b
                .build_bit_cast(param, bits_ty, "real_arg_bits")
                .unwrap()
                .into_int_value();
            let slot_ty = storage_type(ctx, width, repr);
            let bits = b
                .build_int_z_extend_or_bit_cast(bits, slot_ty, "real_arg_slot")
                .unwrap();
            let slot = b.build_alloca(slot_ty, a.name()).unwrap();
            b.build_store(slot, bits).unwrap();
            locals.insert(a.uid(), (slot, width, false));
            continue;
        }
        // An unpacked-array formal: the caller's temporary (a fresh copy
        // for an input, so it is used in place either way).
        if let Some(shape) = crate::arrays::array_shape(&t) {
            let ptr = f
                .get_nth_param(base + i as u32)
                .unwrap()
                .into_pointer_value();
            locals.insert(
                a.uid(),
                (ptr, shape.elem.value_width(), shape.elem.is_signed()),
            );
            if a.formal_argument_direction() == sv_lang::ArgumentDirection::Out {
                out_inits.push(*a);
            }
            continue;
        }
        // Corrected vs. plan: `Type::bit_width()` returns `u64`, not `u32`
        // (distinct from `SVInt::bit_width() -> u32`, which value.rs already
        // treats as u32 correctly). Cast before storing in `locals`.
        let width = t.value_width();
        // A vector wider than an LLVM integer: an image the caller copied
        // for this call (an input) or its own temporary (`output`/`inout`).
        if crate::huge::is_image_type(&t) {
            crate::huge::require_images(repr, a)?;
            let ptr = f
                .get_nth_param(base + i as u32)
                .unwrap()
                .into_pointer_value();
            locals.insert(a.uid(), (ptr, width, t.is_signed()));
            if a.formal_argument_direction() == sv_lang::ArgumentDirection::Out {
                out_inits.push(*a);
            }
            continue;
        }
        if is_by_reference(a) {
            // The caller's temporary, used in place; an `output` starts at
            // its type's default (LRM 1800-2023 §13.5.1).
            let ptr = f
                .get_nth_param(base + i as u32)
                .unwrap()
                .into_pointer_value();
            locals.insert(a.uid(), (ptr, width, t.is_signed()));
            if a.formal_argument_direction() == sv_lang::ArgumentDirection::Out {
                out_inits.push(*a);
            }
            continue;
        }
        let slot = b
            .build_alloca(lower_type(ctx, &t, repr)?.into_basic_type_enum(), a.name())
            .unwrap();
        b.build_store(
            slot,
            f.get_nth_param(base + i as u32).unwrap().into_int_value(),
        )
        .unwrap();
        locals.insert(a.uid(), (slot, width, t.is_signed()));
    }

    // Classes plan Task 5 (§1.3): the receiver parameter, if any -- `this`
    // reads lower through the ordinary `NamedValue`-on-`locals` path with no
    // code of their own, exactly like every other `locals` entry.
    if let Some(tv) = this_var {
        // Sized like any 64-bit local under `repr` (a four-state local is
        // value then unknown plane): a bare `this` read loads the full
        // `storage_type`, which would run past a plain i64 slot and read
        // stack garbage as the unknown plane (`this == h` was `x`).
        let slot = b.build_alloca(storage_type(ctx, 64, repr), "this").unwrap();
        let recv = f.get_nth_param(0).unwrap().into_int_value();
        let recv = if repr == ValueRepr::FourState {
            b.build_int_z_extend(recv, storage_type(ctx, 64, repr), "this_zext")
                .unwrap()
        } else {
            recv
        };
        b.build_store(slot, recv).unwrap();
        locals.insert(tv.uid(), (slot, 64, false));
    }

    // A static subroutine's formals are static variables (LRM 1800-2023
    // §13.3, §6.21): the instance's signals, reached below like any other.
    // Their incoming values (and, for `output`/`inout`/`ref`, the caller's
    // temporaries) are kept here to move into and out of those signals.
    let static_formals: Vec<(sv_lang::Symbol<'d>, inkwell::values::PointerValue<'_>, u32)> = args
        .iter()
        .filter(|a| sv_sim_sim::netlist::is_static_procedural_var(a))
        .filter_map(|a| locals.get(&a.uid()).map(|&(p, w, _)| (*a, p, w)))
        .collect();
    // Hidden parameters (`SubroutineAbi`): the caller's shadow copy of each
    // module signal this subroutine touches, then the instance handle.
    let abi = subroutine_abi(sym);
    for (k, sig) in abi.signals.iter().enumerate() {
        let t = sig
            .value_type()
            .ok_or_else(|| LoweringError::unsupported_at("module signal has no type", sig))?;
        let ptr = f
            .get_nth_param(base + (args.len() + k) as u32)
            .unwrap()
            .into_pointer_value();
        locals.insert(sig.uid(), (ptr, t.value_width(), t.is_signed()));
    }
    let accessor_fns = crate::accessor::accessor_fns_of(module)
        .unwrap_or_else(|| crate::accessor::declare_accessor_fns(ctx, module));
    let (mem_signals, mem_accessor) = if abi.needs_handle {
        let handle = f
            .get_nth_param(base + (args.len() + abi.signals.len()) as u32)
            .unwrap()
            .into_pointer_value();
        // (A checker's function is laid out in the instance holding the checker.)
        let scope = sv_sim_sim::netlist::enclosing_instance_body(sym)
            .or_else(|| sym.parent())
            .ok_or_else(|| {
                LoweringError::unsupported_at("subroutine has no enclosing module", sym)
            })?;
        let slots = crate::module::signal_slots_of(&scope)?;
        (
            crate::process_lower::mem_signals_of(&slots),
            Some(crate::expr::MemAccessorCtx {
                handle,
                fns: &accessor_fns,
            }),
        )
    } else {
        (HashMap::new(), None)
    };

    // Declared locals (and a non-void function's implicit result variable,
    // assignable as `f = ...`): an automatic local lives in an `alloca`
    // initialized on every call; a static one (the default lifetime of a
    // module-level `function`/`task` without `automatic`, LRM 1800-2023
    // §13.3.1) lives in one module global, initialized on the first call
    // only. A static local is therefore shared by every instance of the
    // declaring module (the LRM gives each instance its own copy).
    let decls = subroutine_locals(sym);
    let mut auto_inits: Vec<sv_lang::Symbol<'d>> = Vec::new();
    let mut static_inits: Vec<sv_lang::Symbol<'d>> = Vec::new();
    for (k, local) in decls.iter().enumerate() {
        // Classes plan Task 5: a class method's own implicit `this`
        // variable is ALSO a direct `SymbolKind::Variable` member of the
        // method's own scope (`subroutine_locals`'s `take` closure has no
        // way to tell it apart from a genuinely user-declared local), so
        // without this check it would reach this loop's own `!is_
        // integral() && ...` type gate below and fail loudly as "a class/
        // dynamic-array/... subroutine local is not supported" -- `this`
        // is never an ordinary local; it is bound separately, just above
        // this loop, from `this_var`/parameter 0 directly.
        if this_var.is_some_and(|tv| tv.uid() == local.uid()) {
            continue;
        }
        // An instance's static local is a signal (a hidden parameter above).
        if sv_sim_sim::netlist::is_static_procedural_var(local) {
            continue;
        }
        let t = local
            .value_type()
            .ok_or_else(|| LoweringError::unsupported_at("local has no type", local))?;
        // A fixed-size unpacked array: its rows, contiguous
        // (`crate::arrays`); the local's entry names the element width.
        let array = crate::arrays::array_shape(&t);
        if array.is_none()
            && !t.is_integral()
            && !t.is_floating()
            && !t.is_string()
            && !sv_sim_sim::state::storage::is_unpacked_aggregate(&t)
            && !sv_sim_sim::state::storage::is_collection(&t)
            && !t.is_class()
            && !t.is_chandle()
            && !t.is_virtual_interface()
            && !t.is_event()
        {
            // A `chandle` local is its 64-bit pointer bits, like a class
            // handle (LRM 6.14); anything else still refused names its type.
            return Err(LoweringError::unsupported_at(
                &format!(
                    "a subroutine local of type `{}` is not supported",
                    t.to_sv_string()
                ),
                local,
            ));
        }
        let (width, signed, llvm_ty): (u32, bool, inkwell::types::BasicTypeEnum<'_>) = match &array
        {
            // An automatic event array: one 64-bit event id per element
            // (the elements of `event` are zero-width, LRM 15.5).
            Some(_) if sv_sim_sim::state::event_pool::event_count(&t).is_some() => (
                64,
                false,
                storage_type(ctx, 64, repr)
                    .array_type(sv_sim_sim::state::event_pool::event_count(&t).unwrap_or(0))
                    .into(),
            ),
            Some(shape) => (
                shape.elem.value_width(),
                shape.elem.is_signed(),
                crate::arrays::row_type(ctx, &shape.elem, repr)
                    .array_type(shape.rows() as u32)
                    .into(),
            ),
            // A class event is the 64-bit id of a runtime event object.
            None if t.is_event() => (64, false, storage_type(ctx, 64, repr).into()),
            None if crate::huge::is_image_type(&t) => {
                crate::huge::require_images(repr, local)?;
                (
                    t.value_width(),
                    t.is_signed(),
                    crate::huge::image_storage_type(ctx, t.value_width()).into(),
                )
            }
            None => (
                t.value_width(),
                t.is_signed(),
                storage_type(ctx, t.value_width(), repr).into(),
            ),
        };
        let ptr = if local.variable_lifetime() == sv_lang::VariableLifetime::Static {
            let g = module.add_global(
                llvm_ty,
                None,
                &format!(
                    "{}.static.{}.{k}",
                    f.get_name().to_string_lossy(),
                    local.name()
                ),
            );
            g.set_linkage(inkwell::module::Linkage::Internal);
            g.set_initializer(&llvm_ty.const_zero());
            static_inits.push(*local);
            g.as_pointer_value()
        } else {
            // A block's automatic variables are initialized on entry to it.
            if !sv_sim_sim::process::cfg::is_automatic_block_var(local) {
                auto_inits.push(*local);
            }
            b.build_alloca(llvm_ty, local.name()).unwrap()
        };
        locals.insert(local.uid(), (ptr, width, signed));
    }
    // The result variable (`f = ...`) of an integral, real or string function; a
    // real one holds its IEEE bits like any real variable.
    let return_var = if is_void_return
        || !ret_sv.as_ref().is_some_and(|t| {
            t.is_integral()
                || t.is_floating()
                || t.is_string()
                || t.is_class()
                || sv_sim_sim::state::storage::is_unpacked_aggregate(t)
                || sv_sim_sim::state::storage::is_collection(t)
        }) {
        None
    } else {
        sym.subroutine_return_val_var()
    };
    if let Some(rv) = return_var {
        let t = ret_sv.as_ref().expect("non-void has a return type");
        let width = t.value_width();
        // A static function's implicit result variable is static too
        // (LRM 1800-2023 6.21, 13.4.1): it keeps its value across calls and
        // is initialized on the first call only.
        // Handle-valued results (string, collection, class) still return
        // their handle by ownership transfer, so they stay per-call.
        // A collection result is kept too (ivtest sv_queue_function1): the
        // caller gets a copy of it.
        let is_static_fn =
            (t.is_integral() || t.is_floating() || sv_sim_sim::state::storage::is_collection(t))
                && sym.subroutine_default_lifetime() == Some(sv_lang::VariableLifetime::Static);
        let ptr = if is_static_fn {
            let llvm_ty = storage_type(ctx, width, repr);
            let g = module.add_global(
                llvm_ty,
                None,
                &format!("{}.static.retval", f.get_name().to_string_lossy()),
            );
            g.set_linkage(inkwell::module::Linkage::Internal);
            g.set_initializer(&llvm_ty.const_zero());
            static_inits.push(rv);
            g.as_pointer_value()
        } else {
            auto_inits.push(rv);
            b.build_alloca(storage_type(ctx, width, repr), "retval")
                .unwrap()
        };
        locals.insert(rv.uid(), (ptr, width, t.is_signed()));
    }
    // A function result wider than an LLVM integer is the caller's image
    // (a static function's result is not kept across calls).
    if ret_image && let Some(rv) = sym.subroutine_return_val_var() {
        let t = ret_sv.as_ref().expect("non-void has a return type");
        crate::huge::require_images(repr, sym)?;
        let ptr = f
            .get_last_param()
            .expect("an image-valued function has a result pointer")
            .into_pointer_value();
        locals.insert(rv.uid(), (ptr, t.value_width(), t.is_signed()));
        auto_inits.push(rv);
    }
    // An array-valued function's result variable is the caller's temporary.
    if let Some(shape) = &ret_array
        && let Some(rv) = sym.subroutine_return_val_var()
    {
        let ptr = f
            .get_last_param()
            .expect("an array-valued function has a result pointer")
            .into_pointer_value();
        locals.insert(
            rv.uid(),
            (ptr, shape.elem.value_width(), shape.elem.is_signed()),
        );
        auto_inits.push(rv);
    }

    // LRM 1800-2023 13.5.2: a `ref` formal's temporary carries the id of the
    // element reference the caller opened (see `takes_elem_refs`).
    let mut elem_refs: HashMap<_, crate::collections::ElemRefSlot<'ctx>> = HashMap::new();
    if takes_elem_refs(sym) {
        for a in args.iter().filter(|a| is_elem_ref_formal(a)) {
            let Some(&(ptr, width, signed)) = locals.get(&a.uid()) else {
                continue;
            };
            let pair = elem_ref_pair_ty(ctx, width, repr);
            let field = |i, name| b.build_struct_gep(pair, ptr, i, name).unwrap();
            elem_refs.insert(
                ptr,
                crate::collections::ElemRefSlot {
                    id: field(1, "elem_ref_id"),
                    id_width: 64,
                    width,
                    signed,
                    part: Some(crate::collections::PartSlots {
                        lo: field(2, "elem_ref_lo"),
                        elem_width: field(3, "elem_ref_ew"),
                    }),
                },
            );
        }
    }
    let mut cx = LowerCtx {
        ctx,
        b,
        repr,
        locals,
        fn_sym: *sym,
        module,
        // Module memories are reached through the hidden handle parameter
        // (see `SubroutineAbi`).
        mem_signals,
        mem_accessor,
        lvalue_ref: Default::default(),
        deferred_start: Default::default(),
        unbounded: Default::default(),
        coll_temp: Default::default(),
        iter: Default::default(),
        loop_exits: Default::default(),
        block_exits: Default::default(),
        write_through: None,
        cells: Default::default(),
        copy_out: Default::default(),
        ctor_this: Default::default(),
        decl_scale: Default::default(),
        inline_this: Default::default(),
        end_flags: Default::default(),
        // Task 4b: a function/task body can never name a specify-path
        // destination (LRM 30.4.1 restricts one to a module member written
        // by a procedural block) -- a true no-op here, not a narrowing.
        specify_dest: Default::default(),
        elem_refs,
    };
    for (formal, temp, width) in &static_formals {
        let Some(&(signal, _, _)) = cx.locals.get(&formal.uid()) else {
            continue;
        };
        if signal == *temp {
            continue;
        }
        let t = formal
            .value_type()
            .ok_or_else(|| LoweringError::unsupported_at("arg has no type", formal))?;
        let llvm_ty: inkwell::types::BasicTypeEnum<'_> = match crate::arrays::array_shape(&t) {
            Some(shape) => crate::arrays::local_array_type(ctx, &shape, repr).into(),
            None if crate::huge::is_image_width(*width) => {
                crate::huge::image_storage_type(ctx, *width).into()
            }
            None => storage_type(ctx, *width, repr).into(),
        };
        let size = inkwell::types::BasicType::size_of(&llvm_ty).expect("a sized storage type");
        let dir = formal.formal_argument_direction();
        if dir != sv_lang::ArgumentDirection::Out {
            cx.b.build_memcpy(signal, 8, *temp, 8, size).unwrap();
        }
        if is_by_reference(formal) {
            cx.copy_out.push((signal, *temp, size));
        }
    }
    // Automatic locals holding a class handle or collection (LRM 8.4, 7.5):
    // null on entry, so a block's not-yet-entered variable or an early
    // `return` releases nothing, and released at every exit ([`release_locals`]).
    let owned_locals = owned_handle_locals(&cx, &decls, this_var);
    for local in &owned_locals {
        let (ptr, width, _) = cx.locals[&local.uid()];
        cx.b.build_store(ptr, storage_type(ctx, width, repr).const_zero())
            .unwrap();
    }
    for local in out_inits.iter().chain(&auto_inits) {
        init_local(&cx, local)?;
    }
    if !static_inits.is_empty() {
        // First-call guard for the static locals' initializers.
        let flag = module.add_global(
            ctx.bool_type(),
            None,
            &format!("{}.static_init_done", f.get_name().to_string_lossy()),
        );
        flag.set_linkage(inkwell::module::Linkage::Internal);
        flag.set_initializer(&ctx.bool_type().const_zero());
        let done =
            cx.b.build_load(ctx.bool_type(), flag.as_pointer_value(), "static_done")
                .unwrap()
                .into_int_value();
        let init_bb = ctx.append_basic_block(f, "static_init");
        let body_bb = ctx.append_basic_block(f, "body");
        cx.b.build_conditional_branch(done, body_bb, init_bb)
            .unwrap();
        cx.b.position_at_end(init_bb);
        for local in &static_inits {
            init_local(&cx, local)?;
        }
        cx.b.build_store(flag.as_pointer_value(), ctx.bool_type().const_all_ones())
            .unwrap();
        cx.b.build_unconditional_branch(body_bb).unwrap();
        cx.b.position_at_end(body_bb);
    }
    // VPI (37.43): this activation is a frame, its automatic variables now
    // created and initialized.
    let frame_site = if crate::vpi_dyn::enabled() {
        let automatic = |v: &sv_lang::Symbol<'d>| {
            !sv_sim_sim::netlist::is_static_procedural_var(v)
                && v.variable_lifetime() != sv_lang::VariableLifetime::Static
        };
        // 37.15 detail 1: a `ref` formal is a ref obj of the frame, not one of
        // its variables.
        let mut vars: Vec<sv_lang::Symbol<'d>> = args
            .iter()
            .copied()
            .filter(|a| {
                a.formal_argument_direction() != sv_lang::ArgumentDirection::Ref && automatic(a)
            })
            .collect();
        vars.extend(
            decls
                .iter()
                .copied()
                .filter(|l| this_var.is_none_or(|tv| tv.uid() != l.uid()) && automatic(l)),
        );
        if let Some(rv) = sym.subroutine_return_val_var()
            && cx.locals.contains_key(&rv.uid())
            && sym.subroutine_default_lifetime() == Some(sv_lang::VariableLifetime::Automatic)
        {
            vars.push(rv);
        }
        crate::vpi_dyn::emit_frame_enter(
            &cx,
            sym,
            &vars,
            &crate::vpi_dyn::ref_formal_placeholders(&cx, sym),
        )
    } else {
        None
    };
    let block_handle = cx
        .mem_accessor
        .as_ref()
        .filter(|_| crate::covergroup::is_block_target(sym))
        .map(|m| m.handle);
    if let Some(h) = block_handle {
        sync_subroutine_writes(&cx)?;
        crate::covergroup::emit_block_event(&cx, h, false)?;
    }
    let body = sv_sim_sim::process::cfg::proc_body(sym)
        .ok_or_else(|| LoweringError::unsupported_at("no body", sym))?;
    if this_var.is_some() {
        // LRM 1800-2023 8.17: a constructor declaring `default` calls
        // `super.new(default)` first.
        crate::classes::emit_implicit_default_super(&cx)?;
    }
    lower_stmt(&mut cx, body)?;
    // A function that falls off its end returns its result variable.
    if let Some(rv) = return_var
        && !current_block_terminated(&cx)
    {
        let (ptr, width, signed) = cx.locals[&rv.uid()];
        let ret_ty = ret_sv.as_ref().unwrap();
        let loaded =
            cx.b.build_load(storage_type(ctx, width, repr), ptr, "retval_ld")
                .unwrap()
                .into_int_value();
        if ret_ty.is_floating() {
            let pv = PackedValue {
                llvm: loaded,
                width,
                repr,
                signed,
            };
            let rv = crate::real::bits_to_real(&cx, pv);
            let v = fit_float_return(&cx, rv.llvm);
            copy_out_formals(&cx);
            cx.b.build_return(Some(&v)).unwrap();
        } else if sv_sim_sim::state::storage::is_collection(ret_ty)
            && sym.subroutine_default_lifetime() == Some(sv_lang::VariableLifetime::Static)
        {
            let pv = PackedValue {
                llvm: loaded,
                width,
                repr,
                signed,
            };
            let copy = crate::collections::clone_stored(&cx, ret_ty, pv)?;
            copy_out_formals(&cx);
            cx.b.build_return(Some(&copy)).unwrap();
        } else {
            copy_out_formals(&cx);
            cx.b.build_return(Some(&loaded)).unwrap();
        }
    }

    // R-run Task 10: a void subroutine's body can fall off its own end with
    // no explicit `return;` on every path at all (`function_task.sv`'s own
    // `show` task: its whole body is a single `$display(...);` statement) --
    // the builder's current block is then still unterminated, which LLVM's
    // verifier rejects outright. Insert the implicit `ret void` here. A
    // NON-void subroutine reaching this point unterminated is a genuine
    // "not every path returns a value" SV violation this task does not
    // newly diagnose -- `f.verify(true)` below already catches it (as an
    // LLVM verification failure), exactly the pre-Task-10 behavior.
    if is_void_return && !current_block_terminated(&cx) {
        copy_out_formals(&cx);
        cx.b.build_return(None).unwrap();
    }
    // A by-value input formal owns the count its caller retained for it
    // (`owned`/`owned_arg` at the call site, LRM 13.5.1): released like a local.
    let mut released = owned_locals;
    released.extend(owned_handle_formals(&cx, &args));
    release_locals_before_returns(&cx, f, &released);
    if let Some(site) = frame_site {
        crate::vpi_dyn::emit_frame_exits_before_returns(&cx, f, site);
    }
    // 19.3 `@@(end f)`: before every return, after the body's last write.
    if let Some(h) = block_handle {
        let rets: Vec<_> = f
            .get_basic_block_iter()
            .filter_map(|bb| bb.get_terminator())
            .filter(|t| t.get_opcode() == inkwell::values::InstructionOpcode::Return)
            .collect();
        for t in rets {
            cx.b.position_before(&t);
            sync_subroutine_writes(&cx)?;
            crate::covergroup::emit_block_event(&cx, h, true)?;
        }
    }

    if f.verify(true) {
        Ok(f)
    } else {
        Err(LoweringError {
            message: "function failed LLVM verify".into(),
            at: sym.hierarchical_path(),
        })
    }
}

/// Whether a call from `caller` to `callee` must run in the callee package's
/// own state rather than the caller's instance (LRM 10.6, 26.2): `callee` is a
/// package subroutine that goes through the instance handle for a
/// `force`/`assign` ([`SubroutineAbi::forces`]) -- its targets are package
/// variables, which only the package's state holds -- and the caller is not in
/// that same package. The runner registers the package's foreign slot under
/// the callee's symbol (`run.rs`, `foreign_references`), exactly as for a
/// hierarchical call into another instance.
pub fn package_handle_callee(callee: &sv_lang::Symbol<'_>, caller: &sv_lang::Symbol<'_>) -> bool {
    let Some(pkg) = sv_sim_sim::netlist::enclosing_package(callee) else {
        return false;
    };
    callee.kind() == sv_lang::kinds::SymbolKind::Subroutine
        && subroutine_abi(callee).forces
        && sv_sim_sim::netlist::enclosing_package(caller).is_none_or(|p| p.uid() != pkg.uid())
}

/// The hidden part of a user subroutine's ABI, after its SV arguments: one
/// pointer parameter per module-level signal it (transitively, through the
/// subroutines it calls) reads or writes -- the CALLER's shadow copy, which
/// the caller's segment primes before and flushes after, exactly like its
/// own reads/writes of that signal -- then, if it touches a module memory,
/// the instance `SimHandle` (memory rows go through the accessor ABI).
#[derive(Clone)]
pub(crate) struct SubroutineAbi<'d> {
    /// Non-memory module signals, in hierarchical-path order.
    pub signals: Vec<sv_lang::Symbol<'d>>,
    /// The subset of `signals` it may write.
    pub written: std::collections::HashSet<sv_sim_sim::symid::SymbolId>,
    /// Whether it reads or writes a module memory, or [`Self::syncs_state`].
    pub needs_handle: bool,
    /// Whether it (or a subroutine it calls) samples a covergroup or signals
    /// a block event (19.3): the module signals it writes are committed to
    /// STATE first, through the instance handle.
    pub syncs_state: bool,
    /// Whether it (or a subroutine it calls) executes a `force`/`assign`/
    /// `release`/`deassign` (10.6; implies [`Self::syncs_state`]).
    pub forces: bool,
    /// The module memories it reads or writes (through the instance handle),
    /// and the subset it may write.
    pub memories: Vec<sv_lang::Symbol<'d>>,
    pub memories_written: std::collections::HashSet<sv_sim_sim::symid::SymbolId>,
}

/// `force`/`assign`/`release`/`deassign` inside a function or task body
/// (LRM 1800-2023 10.6): the write goes through the instance handle like the
/// same statement in a process. A forced/assigned expression that reads module
/// signals is tracked by a continuous driver (`force::force_drivers`) that
/// `run.rs` adds per called subroutine, as it does per process body; one that
/// reads the subroutine's own arguments or locals is a named refusal rather
/// than a one-shot snapshot.
fn lower_subroutine_force<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    s: &sv_lang::Statement<'d>,
) -> Result<(), LoweringError> {
    let handle = cx.mem_accessor.as_ref().map(|m| m.handle).ok_or_else(|| {
        LoweringError::unsupported_at(
            "a force/assign/release/deassign in a subroutine without an instance handle",
            &cx.fn_sym,
        )
    })?;
    if s.kind() == StatementKind::ProceduralAssign
        && let Some(r) = s.expressions().into_iter().next().and_then(|a| a.right())
        && r.constant_value().is_none()
    {
        // The driver that keeps the target following the right-hand side is
        // a continuous assignment of the owning instance (`run.rs`, one per
        // statement): it can read module signals but not the subroutine's own
        // arguments or locals, which only exist during the call.
        let mut stack = vec![r.as_sem_node()];
        while let Some(n) = stack.pop() {
            if let Some(e) = n.as_expression()
                && let Some(x) = e.referenced_symbol()
            {
                // A module-level signal is tracked by the owning instance's
                // driver.
                if !is_module_level_signal(&x)
                    && matches!(x.kind(), SymbolKind::Variable | SymbolKind::FormalArgument)
                {
                    return Err(LoweringError::unsupported_at(
                        "a force/assign inside a subroutine whose right-hand side reads \
                         one of the subroutine's own arguments or locals (the forced value \
                         must track it continuously, LRM 10.6.2, but it only exists during \
                         the call)",
                        &cx.fn_sym,
                    ));
                }
            }
            stack.extend(sv_sim_sim::process::cfg::live_children(&n));
        }
    }
    let scope = sv_sim_sim::netlist::enclosing_instance_body(&cx.fn_sym)
        .or_else(|| cx.fn_sym.parent())
        .ok_or_else(|| {
            LoweringError::unsupported_at("subroutine has no enclosing module", &cx.fn_sym)
        })?;
    let slots = crate::module::signal_slots_of(&scope)?;
    // Blocking writes made so far in the body reach STATE first, so the force
    // lands on top of them (a process already writes through).
    sync_subroutine_writes(cx)?;
    if s.kind() != StatementKind::ProceduralAssign {
        return crate::force::lower_procedural_deassign(cx, handle, &slots, *s);
    }
    crate::force::lower_procedural_assign(cx, handle, &slots, *s)?;
    // The forced target's shadow (the caller's copy) then reads the forced
    // value, not what it held before.
    let mem = cx.mem_accessor.as_ref().expect("checked above");
    let mut targets: Vec<_> = s
        .expressions()
        .into_iter()
        .next()
        .and_then(|a| a.left())
        .into_iter()
        .collect();
    while let Some(t) = targets.pop() {
        if t.kind() == ExpressionKind::Concatenation {
            targets.extend(t.operands());
            continue;
        }
        for r in crate::select::lvalue_root_symbols(t) {
            let (Some(info), Some(&(ptr, _, _))) = (slots.get(&r.uid()), cx.locals.get(&r.uid()))
            else {
                continue;
            };
            if matches!(
                info.class,
                crate::process_lower::SignalSlotClass::Memory { .. }
            ) {
                continue;
            }
            let wt = crate::expr::WriteThrough {
                handle: mem.handle,
                fns: mem.fns,
                signals: HashMap::from([(
                    ptr,
                    (
                        info.slot,
                        info.width,
                        info.class == crate::process_lower::SignalSlotClass::Wide,
                    ),
                )]),
                reload: Default::default(),
            };
            crate::expr::reload_from_state(cx, &wt, ptr);
        }
    }
    Ok(())
}

/// A nonblocking assignment inside a function or task body (LRM 1800-2023
/// 10.4.2): the right-hand side is evaluated now and the write is staged for
/// the NBA region through the instance handle [`SubroutineAbi`] passes in
/// (`needs_handle`), exactly like the same statement in a process.
pub(crate) fn lower_subroutine_nba<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: sv_lang::Expression<'d>,
) -> Result<LoweredValue<'ctx>, LoweringError> {
    let handle = cx.mem_accessor.as_ref().map(|m| m.handle).ok_or_else(|| {
        LoweringError::unsupported_at(
            "a nonblocking assignment (<=) outside a process or a subroutine with an instance handle",
            &cx.fn_sym,
        )
    })?;
    let scope = sv_sim_sim::netlist::enclosing_instance_body(&cx.fn_sym)
        .or_else(|| cx.fn_sym.parent())
        .ok_or_else(|| {
            LoweringError::unsupported_at("subroutine has no enclosing module", &cx.fn_sym)
        })?;
    let slots = crate::module::signal_slots_of(&scope)?;
    let nba_fn = cx
        .module
        .get_function(sv_sim_abi::process::NBA_ENQUEUE_SYMBOL)
        .unwrap_or_else(|| crate::process_lower::declare_nba_enqueue(cx.ctx, cx.module));
    crate::process_lower::lower_nonblocking_assignment(cx, handle, &slots, nba_fn, e)?;
    let z = cx.ctx.bool_type().const_zero();
    Ok(LoweredValue::Packed(
        OpBuilder {
            ctx: cx.ctx,
            b: &cx.b,
        }
        .pack(z, z, 1, cx.repr, false),
    ))
}

/// The shape of `sym`'s result when it is an unpacked array.
pub(crate) fn array_result<'d>(sym: &sv_lang::Symbol<'d>) -> Option<crate::arrays::ArrayShape<'d>> {
    sym.subroutine_return_type()
        .as_ref()
        .and_then(crate::arrays::array_shape)
}

/// Calls the array-valued user function `call` into a fresh local
/// temporary and returns the temporary.
pub(crate) fn lower_array_call<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    call: sv_lang::Expression<'d>,
) -> Result<inkwell::values::PointerValue<'ctx>, LoweringError> {
    // Through a virtual interface: every arm fills one temporary.
    if let Some(r) = crate::vif::call_arms(cx, call) {
        let (arms, merge) = r?;
        let callee = call.call_subroutine().ok_or_else(|| {
            LoweringError::unsupported_at("an array value from a non-user call", &cx.fn_sym)
        })?;
        let shape = array_result(&callee).ok_or_else(|| {
            LoweringError::unsupported_at(
                "a call used as an array value does not return an unpacked array",
                &cx.fn_sym,
            )
        })?;
        let temp = crate::expr::entry_alloca(
            cx,
            crate::arrays::local_array_type(cx.ctx, &shape, cx.repr),
            "vif_call_array",
        );
        for (callee, bb) in arms {
            cx.b.position_at_end(bb);
            let t = lower_array_call_of(cx, callee, call)?;
            let ty = crate::arrays::local_array_type(cx.ctx, &shape, cx.repr);
            let v = cx.b.build_load(ty, t, "vif_arr").unwrap();
            cx.b.build_store(temp, v).unwrap();
            cx.b.build_unconditional_branch(merge).unwrap();
        }
        cx.b.position_at_end(merge);
        return Ok(temp);
    }
    let callee = user_callee(&call).ok_or_else(|| {
        LoweringError::unsupported_at("an array value from a non-user call", &cx.fn_sym)
    })?;
    lower_array_call_of(cx, callee, call)
}

/// [`lower_array_call`] of `call` to `callee`.
fn lower_array_call_of<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    callee: sv_lang::Symbol<'d>,
    call: sv_lang::Expression<'d>,
) -> Result<inkwell::values::PointerValue<'ctx>, LoweringError> {
    let shape = array_result(&callee).ok_or_else(|| {
        LoweringError::unsupported_at(
            "a call used as an array value does not return an unpacked array",
            &cx.fn_sym,
        )
    })?;
    let callee_fn = resolve_callee_fn(cx, callee)?;
    let (mut llvm_args, copy_backs) = lower_call_args(cx, &callee, call)?;
    let temp = crate::expr::entry_alloca(
        cx,
        crate::arrays::local_array_type(cx.ctx, &shape, cx.repr),
        "call_array",
    );
    llvm_args.push(temp.into());
    if llvm_args.len() != callee_fn.count_params() as usize {
        return Err(LoweringError::unsupported_at(
            "array-valued function call argument count does not match the callee's \
             declared parameter count",
            &cx.fn_sym,
        ));
    }
    cx.b.build_call(callee_fn, &llvm_args, "array_fn_call")
        .unwrap();
    if sv_sim_sim::process::cfg::subroutine_can_abort(&callee) {
        crate::stmt_shared::leave_if_aborted(cx)?;
    }
    commit_callee_writes(cx, &callee);
    if crate::dpi::reaches_context_import(&callee) {
        crate::dpi::reload_shadows(cx);
    }
    copy_back_outputs(cx, copy_backs)?;
    Ok(temp)
}

/// Commits to STATE the module signals a call of `callee` may have written
/// through the caller's shadows, in a process that writes through (see
/// [`crate::expr::WriteThrough`]): a blocking write made inside a subroutine
/// is as visible to other processes as one made in the process itself, and a
/// later shadow reload (a VPI probe, a context DPI call) must not lose it.
pub(crate) fn commit_callee_writes(cx: &LowerCtx<'_, '_, '_>, callee: &sv_lang::Symbol<'_>) {
    if cx.write_through.is_none() {
        return;
    }
    let abi = subroutine_abi(callee);
    for sig in abi
        .signals
        .iter()
        .filter(|s| abi.written.contains(&s.uid()))
    {
        if let Some(&(ptr, _, _)) = cx.locals.get(&sig.uid()) {
            crate::expr::write_through_store(cx, ptr);
        }
    }
}

/// The write-through table over the shadows of the module signals the
/// subroutine being lowered writes ([`sync_subroutine_writes`], force/release
/// re-reads), `None` when it has no instance handle or does not
/// [`SubroutineAbi::syncs_state`].
fn subroutine_write_through<'ctx, 'a>(
    cx: &'a LowerCtx<'ctx, '_, '_>,
) -> Result<Option<crate::expr::WriteThrough<'ctx, 'a>>, LoweringError> {
    if cx.write_through.is_some() || cx.fn_sym.kind() != sv_lang::kinds::SymbolKind::Subroutine {
        return Ok(None);
    }
    let Some(mem) = &cx.mem_accessor else {
        return Ok(None);
    };
    let abi = subroutine_abi(&cx.fn_sym);
    if !abi.syncs_state {
        return Ok(None);
    }
    let scope = sv_sim_sim::netlist::enclosing_instance_body(&cx.fn_sym)
        .or_else(|| cx.fn_sym.parent())
        .ok_or_else(|| {
            LoweringError::unsupported_at("subroutine has no enclosing module", &cx.fn_sym)
        })?;
    let slots = crate::module::signal_slots_of(&scope)?;
    let signals = abi
        .signals
        .iter()
        .filter(|s| abi.written.contains(&s.uid()))
        .filter_map(|s| {
            let info = slots.get(&s.uid())?;
            if matches!(
                info.class,
                crate::process_lower::SignalSlotClass::Memory { .. }
            ) {
                return None;
            }
            let &(ptr, _, _) = cx.locals.get(&s.uid())?;
            Some((
                ptr,
                (
                    info.slot,
                    info.width,
                    info.class == crate::process_lower::SignalSlotClass::Wide,
                ),
            ))
        })
        .collect::<HashMap<_, _>>();
    Ok(Some(crate::expr::WriteThrough {
        handle: mem.handle,
        fns: mem.fns,
        signals,
        reload: Default::default(),
    }))
}

/// Commits to STATE the module signals the subroutine being lowered
/// (`cx.fn_sym`) may have written through its caller's shadows, when it
/// [`SubroutineAbi::syncs_state`]: a covergroup sample (19.8) or block event
/// (19.3) reads STATE, and a blocking write made before it in the subroutine
/// must be seen (a process already writes through, see
/// [`crate::expr::WriteThrough`]).
pub(crate) fn sync_subroutine_writes(cx: &LowerCtx<'_, '_, '_>) -> Result<(), LoweringError> {
    let Some(wt) = subroutine_write_through(cx)? else {
        return Ok(());
    };
    // In slot order: a map walk would make two builds of one design differ.
    let mut order: Vec<_> = wt
        .signals
        .iter()
        .map(|(&p, &(s, w, _))| (s, w, p))
        .collect();
    order.sort_by_key(|&(slot, _, _)| slot);
    for (slot, width, ptr) in order {
        if crate::huge::is_huge_width(width) {
            let i64t = cx.ctx.i64_type();
            crate::huge::rt_mark(
                cx,
                wt.handle,
                slot,
                width,
                i64t.const_zero(),
                i64t.const_int(u64::from(width), false),
            );
        }
        crate::expr::commit_shadow(cx, &wt, ptr);
    }
    Ok(())
}

/// A `const ref` formal (LRM 13.5.2): bound by reference but read-only.
pub(crate) fn is_const_ref(formal: &sv_lang::Symbol<'_>) -> bool {
    formal.formal_argument_direction() == sv_lang::ArgumentDirection::Ref
        && formal
            .variable_flags()
            .contains(sv_lang::VariableFlags::CONST)
}

/// An `output`/`inout`/`ref` formal: passed as a pointer to a caller-owned
/// temporary, which the caller copies back into the actual after the call.
pub(crate) fn is_by_reference(formal: &sv_lang::Symbol<'_>) -> bool {
    formal.formal_argument_direction() != sv_lang::ArgumentDirection::In
}

/// A `ref` formal of a packed or real type: the kind that can be bound to a
/// queue / dynamic-array / associative-array element (LRM 1800-2023 13.5.2).
pub(crate) fn is_elem_ref_formal(formal: &sv_lang::Symbol<'_>) -> bool {
    formal.formal_argument_direction() == sv_lang::ArgumentDirection::Ref
        && formal.value_type().is_some_and(|t| {
            (t.is_integral() || t.is_floating())
                && crate::arrays::array_shape(&t).is_none()
                && !crate::huge::is_image_type(&t)
        })
}

/// Whether the compiled subroutine `sub` carries a live element reference for
/// each of its [`is_elem_ref_formal`] formals (LRM 1800-2023 13.5.2): the
/// caller then hands each such formal's temporary with a trailing reference
/// id (`elem_ref_pair_ty`), and the body refreshes / flushes the formal
/// through it. That only matters when the body can change a collection (or
/// run code that can) while the reference is held, so a body that names no
/// collection and calls nothing keeps the plain copy-in / copy-out and the
/// code it always had.
pub(crate) fn takes_elem_refs(sub: &sv_lang::Symbol<'_>) -> bool {
    if !sub.subroutine_arguments().any(|a| is_elem_ref_formal(&a)) {
        return false;
    }
    let Some(body) = sv_sim_sim::process::cfg::proc_body(sub) else {
        return false;
    };
    // A static subroutine's formals are the instance's signals (not the
    // caller's temporaries): only a body that can change a collection counts.
    let names_shared_storage = !sub
        .subroutine_arguments()
        .any(|a| sv_sim_sim::netlist::is_static_procedural_var(&a));
    let mut stack = vec![body.as_sem_node()];
    stack.extend(
        subroutine_locals(sub)
            .iter()
            .filter_map(|l| l.initializer())
            .map(|i| i.as_sem_node()),
    );
    while let Some(n) = stack.pop() {
        if let Some(e) = n.as_expression()
            && ((e.kind() == ExpressionKind::Call && e.is_system_call() != Some(true))
                || e.kind() == ExpressionKind::NewClass
                || e.expr_type()
                    .is_some_and(|t| sv_sim_sim::state::storage::is_collection(&t)))
        {
            return true;
        }
        if names_shared_storage
            && n.as_expression()
                .is_some_and(|e| names_shared_storage_node(&e))
        {
            return true;
        }
        stack.extend(sv_sim_sim::process::cfg::live_children(&n));
    }
    false
}

/// Whether `n` names a variable the caller's `ref` actual may be (a module
/// or package variable, a class property): a body that touches one while it
/// holds a `ref` to it must see a single location with the formal (LRM
/// 1800-2023 13.5.2; [`crate::collections::open_ref_window`]).
fn names_shared_storage_node(e: &sv_lang::Expression<'_>) -> bool {
    matches!(
        e.kind(),
        ExpressionKind::NamedValue | ExpressionKind::HierarchicalValue
    ) && e.referenced_symbol().is_some_and(|s| {
        s.kind() == SymbolKind::ClassProperty
            || (s.kind() != SymbolKind::FormalArgument && is_module_level_signal(&s))
    })
}

/// The caller temporary of an element-capable `ref` formal: the formal's
/// value, then the runtime reference id (0: bound to something else), then
/// (a `ref` to a member / select of an element, `f(q[i].m)`) the part's bit
/// offset in the element and the element's width (0: the whole element).
fn elem_ref_pair_ty(ctx: &Context, width: u32, repr: ValueRepr) -> inkwell::types::StructType<'_> {
    ctx.struct_type(
        &[
            storage_type(ctx, width, repr).into(),
            storage_type(ctx, 64, repr).into(),
            storage_type(ctx, 64, repr).into(),
            storage_type(ctx, 64, repr).into(),
        ],
        false,
    )
}

/// True when `sym` is a variable/net of a module (or package) body -- not a local of any
/// subroutine or block between it and that body.
fn is_module_level_signal(sym: &sv_lang::Symbol<'_>) -> bool {
    // A checker's output formal is a variable of the checker (LRM 17.3).
    if sv_sim_sim::netlist::checker_output_of(sym).is_some() {
        return true;
    }
    // A modport port (`b.d` through a `bus.tgt b` port) names its interface
    // instance's own variable or net: a module-level signal.
    if sym.kind() == SymbolKind::ModportPort {
        return sym
            .modport_port_internal_symbol()
            .is_some_and(|s| is_module_level_signal(&s));
    }
    if !matches!(sym.kind(), SymbolKind::Variable | SymbolKind::Net) {
        return false;
    }
    // A static variable of an instance's procedural code has its STATE slot.
    if sv_sim_sim::netlist::is_static_procedural_var(sym) {
        return true;
    }
    let mut cur = sym.parent();
    while let Some(p) = cur {
        let kind = p.kind();
        // A checker's own variable is state of the instance hosting it
        // (LRM 17.3: `module_items` flattens its body into that instance).
        if kind == SymbolKind::InstanceBody
            || kind == SymbolKind::CheckerInstanceBody
            || kind == SymbolKind::Package
            || kind == SymbolKind::CompilationUnit
        {
            return true;
        }
        if kind == SymbolKind::Subroutine || kind == SymbolKind::StatementBlock {
            return false;
        }
        cur = p.parent();
    }
    false
}

/// The subroutines a user call can reach: its callee, or for a call through
/// a virtual interface every candidate instance's own (`crate::vif`).
pub(crate) fn user_callees<'d>(e: &sv_lang::Expression<'d>) -> Vec<sv_lang::Symbol<'d>> {
    // `new` runs every class level's constructor from the root down (LRM
    // 8.7), including a base constructor no source call names (a derived
    // class with an implicit or defaulted `new`), so each is a callee.
    if e.kind() == ExpressionKind::NewClass && e.new_class_is_super_class() != Some(true) {
        let mut out = Vec::new();
        let mut level = e.expr_type().map(|t| t.canonical());
        while let Some(t) = level {
            if !t.is_class() {
                break;
            }
            out.extend(t.class_constructor());
            level = t.class_base();
        }
        return out;
    }
    match sv_sim_sim::netlist::vif::call_targets(e) {
        Some((_, targets)) => targets.into_iter().flatten().collect(),
        // An interface `extern` method: every module-side implementation.
        None => sv_sim_sim::netlist::itf::call_callees(e)
            .into_iter()
            .filter(|c| !c.subroutine_flags().contains(MethodFlags::DPI_IMPORT))
            .collect(),
    }
}

/// The callee of a user (non-system, non-DPI) subroutine call expression: an
/// interface `extern` method's is its module-side implementation (LRM 25.7).
pub(crate) fn user_callee<'d>(e: &sv_lang::Expression<'d>) -> Option<sv_lang::Symbol<'d>> {
    if e.kind() != ExpressionKind::Call || e.is_system_call() == Some(true) {
        return None;
    }
    let callee = sv_sim_sim::netlist::itf::call_target(e)?;
    if callee.subroutine_flags().contains(MethodFlags::DPI_IMPORT) {
        return None;
    }
    Some(callee)
}

/// The module-level signals and memories that calls in `e` (to user
/// subroutines, transitively) read without writing: a continuous
/// assignment's value changes when any of them does (LRM 10.3: "whenever the
/// value of the right-hand side changes"), so they are part of its
/// sensitivity even though they are not operands of the expression.
pub fn callee_reads(e: &sv_lang::Expression<'_>) -> Vec<sv_sim_sim::symid::SymbolId> {
    let mut out = Vec::new();
    for callee in user_callees(e) {
        let abi = subroutine_abi(&callee);
        for sig in abi.signals {
            if !abi.written.contains(&sig.uid()) {
                out.push(sig.uid());
            }
        }
        for mem in abi.memories {
            if !abi.memories_written.contains(&mem.uid()) {
                out.push(mem.uid());
            }
        }
    }
    out
}

/// Whether `sym` (or a subroutine it calls) forces/assigns ([`SubroutineAbi::forces`]).
pub fn subroutine_forces(sym: &sv_lang::Symbol<'_>) -> bool {
    subroutine_abi(sym).forces
}

/// Whether a call to `sym` passes its instance's handle (a module memory, a
/// covergroup sample or a block event: [`SubroutineAbi::needs_handle`]).
pub fn subroutine_needs_handle(sym: &sv_lang::Symbol<'_>) -> bool {
    subroutine_abi(sym).needs_handle
}

/// Computes `sym`'s [`SubroutineAbi`] (walking its body and, transitively,
/// every user subroutine it calls; recursion terminates via a visited set).
pub(crate) fn subroutine_abi<'d>(sym: &sv_lang::Symbol<'d>) -> SubroutineAbi<'d> {
    let (mut abi, virt) = compute_abi_static(sym);
    // A call through a base handle may run any override: while a pipeline with
    // classes is lowering, the hidden parameters of every same-named method
    // (transitively, `build_group_abis`) are part of this subroutine's.
    for name in &virt {
        if let Some(g) = GROUP_ABI.with(|c| c.borrow().get(name).cloned()) {
            // SAFETY: the table lives only while the design the symbols borrow
            // from does (`classes::MethodRegistryGuard`).
            let g = unsafe { std::mem::transmute::<SubroutineAbi<'static>, SubroutineAbi<'d>>(g) };
            merge_abi(&mut abi, &g);
        }
    }
    abi
}

/// [`subroutine_abi`] for a CALLER that dispatches `callee` itself: a call to a
/// virtual (or `pure virtual`) method may run any override of that name
/// (LRM 8.20), so the caller must hold every shadow they take. A method body's
/// own ABI already folds the group of each virtual name it CALLS; a process
/// segment that calls the method directly (an inlined task body) needs the
/// callee's own name folded too.
pub(crate) fn dispatch_abi<'d>(callee: &sv_lang::Symbol<'d>) -> SubroutineAbi<'d> {
    let mut abi = subroutine_abi(callee);
    let dispatched = if callee.kind() == SymbolKind::MethodPrototype {
        let f = callee.method_prototype_flags();
        f.contains(MethodFlags::VIRTUAL) || f.contains(MethodFlags::PURE)
    } else {
        callee.subroutine_flags().contains(MethodFlags::VIRTUAL)
            && (callee.subroutine_this_var().is_some()
                || callee.subroutine_flags().contains(MethodFlags::PURE))
    };
    if dispatched
        && let Some(g) = GROUP_ABI.with(|c| c.borrow().get(&callee.name().to_string()).cloned())
    {
        // SAFETY: see `subroutine_abi`.
        let g = unsafe { std::mem::transmute::<SubroutineAbi<'static>, SubroutineAbi<'d>>(g) };
        merge_abi(&mut abi, &g);
    }
    abi
}

thread_local! {
    static GROUP_ABI: std::cell::RefCell<
        std::collections::HashMap<String, SubroutineAbi<'static>>,
    > = std::cell::RefCell::new(std::collections::HashMap::new());
}

/// Empties the per-name override ABIs.
pub(crate) fn clear_group_abis() {
    GROUP_ABI.with(|c| c.borrow_mut().clear());
}

/// Folds `from`'s hidden parameters into `into`.
fn merge_abi<'d>(into: &mut SubroutineAbi<'d>, from: &SubroutineAbi<'d>) {
    // The lists stay in hierarchical-path order; re-sort (one path build per
    // element) only when something was added.
    let merge = |into: &mut Vec<sv_lang::Symbol<'d>>, from: &[sv_lang::Symbol<'d>]| {
        let mut have: std::collections::HashSet<_> = into.iter().map(symbol_identity).collect();
        let before = into.len();
        for s in from {
            if have.insert(symbol_identity(s)) {
                into.push(*s);
            }
        }
        if into.len() != before {
            into.sort_by_cached_key(|s| s.hierarchical_path());
        }
    };
    merge(&mut into.signals, &from.signals);
    merge(&mut into.memories, &from.memories);
    into.written.extend(from.written.iter().cloned());
    into.memories_written
        .extend(from.memories_written.iter().cloned());
    into.needs_handle |= from.needs_handle;
    into.syncs_state |= from.syncs_state;
    into.forces |= from.forces;
}

/// Computes, once per pipeline run, the [`subroutine_abi`] contribution of
/// each virtual-method name: the union over every compiled method of that name
/// of its own hidden parameters and (to a fixpoint) of the names it calls
/// virtually.
pub(crate) fn build_group_abis<'d>(methods: &[sv_lang::Symbol<'d>]) {
    use std::collections::{BTreeSet, HashMap};
    let mut group: HashMap<String, SubroutineAbi<'d>> = HashMap::new();
    let mut deps: HashMap<String, BTreeSet<String>> = HashMap::new();
    for m in methods {
        let name = m.name().to_string();
        let (abi, virt) = compute_abi_static(m);
        match group.get_mut(&name) {
            Some(g) => merge_abi(g, &abi),
            None => {
                group.insert(name.clone(), abi);
            }
        }
        deps.entry(name).or_default().extend(virt);
    }
    loop {
        let mut changed = false;
        let names: Vec<String> = group.keys().cloned().collect();
        for name in names {
            let before = (
                group[&name].signals.len(),
                group[&name].memories.len(),
                group[&name].written.len(),
                group[&name].needs_handle,
            );
            for dep in deps.get(&name).cloned().unwrap_or_default() {
                if dep == name {
                    continue;
                }
                if let Some(d) = group.get(&dep).cloned() {
                    merge_abi(group.get_mut(&name).unwrap(), &d);
                }
            }
            let g = &group[&name];
            if before
                != (
                    g.signals.len(),
                    g.memories.len(),
                    g.written.len(),
                    g.needs_handle,
                )
            {
                changed = true;
            }
        }
        if !changed {
            break;
        }
    }
    GROUP_ABI.with(|c| {
        let mut c = c.borrow_mut();
        c.clear();
        for (k, v) in group {
            // SAFETY: see `subroutine_abi`.
            c.insert(k, unsafe {
                std::mem::transmute::<SubroutineAbi<'d>, SubroutineAbi<'static>>(v)
            });
        }
    });
}

type StaticAbi<'d> = (SubroutineAbi<'d>, std::collections::BTreeSet<String>);

type AbiMemo = std::collections::HashMap<(usize, usize), StaticAbi<'static>>;

thread_local! {
    /// While a design lowers ([`AbiMemoGuard`]): each subroutine's
    /// [`compute_abi_static`] by symbol identity (address + compilation).
    /// The walk is transitive over every callee and `uid()` builds a
    /// hierarchical path per visit, so recomputing it per call site made
    /// `import uvm_pkg::*` spend most of its compile in here.
    static ABI_MEMO: std::cell::RefCell<Option<AbiMemo>> = const { std::cell::RefCell::new(None) };
}

/// Enables the [`compute_abi_static`] memo for one design lowering; the
/// memo holds lifetime-erased symbols, so it is dropped with the guard.
pub(crate) struct AbiMemoGuard;

impl AbiMemoGuard {
    pub(crate) fn enter() -> Self {
        ABI_MEMO.with(|m| *m.borrow_mut() = Some(AbiMemo::new()));
        AbiMemoGuard
    }
}

impl Drop for AbiMemoGuard {
    fn drop(&mut self) {
        ABI_MEMO.with(|m| *m.borrow_mut() = None);
    }
}

use sv_sim_sim::symid::symbol_identity;

fn compute_abi_static<'d>(sym: &sv_lang::Symbol<'d>) -> StaticAbi<'d> {
    let key = symbol_identity(sym);
    let hit = ABI_MEMO.with(|m| m.borrow().as_ref().and_then(|m| m.get(&key).cloned()));
    if let Some(h) = hit {
        // SAFETY: the memo lives only while the design the symbols borrow from
        // does (`AbiMemoGuard`).
        return unsafe { std::mem::transmute::<StaticAbi<'static>, StaticAbi<'d>>(h) };
    }
    let r = compute_abi_static_uncached(sym);
    ABI_MEMO.with(|m| {
        if let Some(m) = m.borrow_mut().as_mut() {
            // SAFETY: see above.
            m.insert(key, unsafe {
                std::mem::transmute::<StaticAbi<'d>, StaticAbi<'static>>(r.clone())
            });
        }
    });
    r
}

fn compute_abi_static_uncached<'d>(sym: &sv_lang::Symbol<'d>) -> StaticAbi<'d> {
    let mut virt_names: std::collections::BTreeSet<String> = std::collections::BTreeSet::new();
    let mut signals: Vec<sv_lang::Symbol<'d>> = Vec::new();
    let mut seen = std::collections::HashSet::new();
    let mut written = std::collections::HashSet::new();
    let mut needs_handle = false;
    let mut syncs_state = false;
    let mut forces = false;
    let mut memories: Vec<sv_lang::Symbol<'d>> = Vec::new();
    let mut memory_seen = std::collections::HashSet::new();
    let mut visited = std::collections::HashSet::new();
    let mut work = vec![*sym];
    while let Some(sub) = work.pop() {
        if !visited.insert(sub.uid()) {
            continue;
        }
        // Its static formals (its own and those of every subroutine it calls,
        // transitively: LRM 13.3, 6.21): set by every call, so the caller
        // must hand the callee a shadow of each.
        for formal in sub.subroutine_arguments() {
            if sv_sim_sim::netlist::is_static_procedural_var(&formal) {
                if seen.insert(formal.uid()) {
                    signals.push(formal);
                }
                written.insert(formal.uid());
            }
        }
        // A derived constructor runs its base class's constructor (LRM 8.7,
        // 8.17), also when no source `super.new(...)` names it (`new(default)`,
        // an implicit call): what that one reaches is reached here too.
        if sub.subroutine_flags().contains(MethodFlags::CONSTRUCTOR)
            && let Some(base_ctor) = sub
                .parent()
                .and_then(|c| c.as_type())
                .and_then(|t| t.class_base())
                .and_then(|b| b.class_constructor())
        {
            work.push(base_ctor);
        }
        let Some(body) = sv_sim_sim::process::cfg::proc_body(&sub) else {
            continue;
        };
        // 19.3 block events: a covergroup samples STATE when it begins or ends.
        if crate::covergroup::is_block_target(&sub) {
            syncs_state = true;
        }
        // An automatic `event` local is a row of the module's event pool,
        // reached through the instance handle (LRM 15.5).
        if subroutine_locals(&sub).iter().any(|l| {
            l.value_type()
                .as_ref()
                .and_then(sv_sim_sim::state::event_pool::event_count)
                .is_some()
        }) {
            needs_handle = true;
        }
        let mut stack = vec![body.as_sem_node()];
        // A local's declaration initializer is no child of the body's
        // `VariableDeclaration` statement: `automatic int t = sig;` reads `sig`.
        stack.extend(
            subroutine_locals(&sub)
                .iter()
                .filter_map(|l| l.initializer())
                .map(|i| i.as_sem_node()),
        );
        while let Some(n) = stack.pop() {
            // 19.3: a named block a covergroup's block event names.
            if n.as_statement().is_some_and(|st| {
                st.kind() == StatementKind::Block
                    && st
                        .block_symbol()
                        .is_some_and(|b| crate::covergroup::is_block_target(&b))
            }) {
                syncs_state = true;
            }
            // 16.4.1: a deferred assertion whose action calls a user task or void function
            // makes that call when its report matures, from a thunk that reads the instance's
            // STATE (`deferred_call`), so the subroutine holds the instance handle.
            if let Some(st) = n.as_statement()
                && st.kind() == StatementKind::ImmediateAssertion
                && st.is_deferred_assertion() == Some(true)
                && [
                    st.immediate_assertion_if_true(),
                    st.immediate_assertion_if_false(),
                ]
                .into_iter()
                .flatten()
                .any(|a| crate::deferred_call::action_call(&a).is_some())
            {
                needs_handle = true;
            }
            // 10.6: a `force`/`assign`/`release`/`deassign` goes through the
            // instance handle and re-reads the shadow of its target.
            if let Some(st) = n.as_statement()
                && matches!(
                    st.kind(),
                    StatementKind::ProceduralAssign | StatementKind::ProceduralDeassign
                )
            {
                // The target of a `force`/`release` is deliberately never
                // marked written: a net re-resolves later, and committing its
                // shadow at return would turn the forced value into a plain
                // write that outlives the release. The force reloads the
                // shadow itself ([`lower_subroutine_force`]).
                syncs_state = true;
                forces = true;
                if let Some(a) = st.expressions().into_iter().next()
                    && a.kind() == ExpressionKind::Assignment
                {
                    stack.extend(
                        a.left()
                            .into_iter()
                            .chain(a.right())
                            .map(|e| e.as_sem_node()),
                    );
                    continue;
                }
            }
            if let Some(e) = n.as_expression() {
                if sv_sim_sim::symid::is_value_name(e.kind())
                    && let Some(r) = e.referenced_symbol()
                    && is_module_level_signal(&r)
                {
                    // A memory goes through the instance handle; a queue,
                    // dynamic or associative array is its 64-bit handle,
                    // shadowed like any other signal.
                    if r.value_type().is_some_and(|t| {
                        t.is_unpacked_array() && !sv_sim_sim::state::storage::is_collection(&t)
                    }) {
                        needs_handle = true;
                        if memory_seen.insert(r.uid()) {
                            memories.push(r);
                        }
                    } else if seen.insert(r.uid()) {
                        signals.push(r);
                    }
                }
                // 16.9.11: `s.triggered` of a sequence instance reads its
                // watcher cell through the instance handle.
                if sv_sim_sim::sva::endpoint::watched_call(&e).is_some() {
                    needs_handle = true;
                }
                // 16.9.3: a sampled value function reads the subroutine's own
                // hidden history cells (`sampled::lower`) through the handle.
                if e.kind() == ExpressionKind::Call
                    && matches!(sv_sim_sim::sva::sampled::decode(e), Ok(Some(_)))
                {
                    needs_handle = true;
                }
                // 19.8 `sample()` reads STATE: the writes made so far are
                // committed first (`sync_subroutine_writes`).
                if crate::covergroup::is_sample_call(&e) {
                    syncs_state = true;
                }
                // 17.4: a checker function's `$inferred_disable` reads the
                // `default disable iff` signal of its instantiation scope.
                if e.kind() == ExpressionKind::Call
                    && e.call_subroutine_name().as_deref() == Some("$inferred_disable")
                    && let Ok(Some(Some((r, _)))) =
                        crate::sva::emit::resolve_checker_inferred_disable(&sub)
                    && is_module_level_signal(&r)
                    && seen.insert(r.uid())
                {
                    signals.push(r);
                }
                // `vif.m`: every candidate instance's `m` (`crate::vif`).
                for r in sv_sim_sim::netlist::vif::member_targets(&e)
                    .into_iter()
                    .flatten()
                    .flatten()
                {
                    if seen.insert(r.uid()) {
                        signals.push(r);
                    }
                }
                // 21.2.2/21.2.3: `$strobe`/`$monitor` hand the scheduler a
                // thunk keyed by the instance handle.
                if e.kind() == ExpressionKind::Call
                    && e.is_system_call() == Some(true)
                    && e.system_subroutine().is_some_and(|s| {
                        matches!(
                            crate::systask::classify_display_family(s.known_name_id()),
                            Some(
                                crate::systask::DisplayFamily::Strobe
                                    | crate::systask::DisplayFamily::Monitor
                            )
                        )
                    })
                {
                    needs_handle = true;
                }
                // 10.4.2: a nonblocking assignment stages through the instance
                // handle; its target is not written in the shadow copy.
                let nonblocking =
                    e.kind() == ExpressionKind::Assignment && e.is_nonblocking() == Some(true);
                if nonblocking {
                    needs_handle = true;
                }
                let target = if nonblocking {
                    None
                } else if e.kind() == ExpressionKind::Assignment {
                    e.left()
                } else if e.kind() == ExpressionKind::UnaryOp
                    && matches!(
                        e.unary_op(),
                        Some(
                            sv_lang::UnaryOp::Preincrement
                                | sv_lang::UnaryOp::Predecrement
                                | sv_lang::UnaryOp::Postincrement
                                | sv_lang::UnaryOp::Postdecrement
                        )
                    )
                {
                    e.operand()
                } else {
                    None
                };
                // A method of a queue / dynamic / associative array may
                // change it (`q.push_back(x)` stores a new handle).
                if e.kind() == ExpressionKind::Call
                    && e.is_system_call() == Some(true)
                    && let Some(this) = e.operands().first()
                    && this
                        .expr_type()
                        .is_some_and(|t| sv_sim_sim::state::storage::is_collection(&t))
                {
                    for r in crate::select::lvalue_root_symbols(*this) {
                        if is_module_level_signal(&r) {
                            written.insert(r.uid());
                        }
                    }
                }
                if let Some(t) = target {
                    for r in crate::select::lvalue_root_symbols(t) {
                        if is_module_level_signal(&r) {
                            written.insert(r.uid());
                        }
                    }
                    for r in sv_sim_sim::netlist::vif::member_targets(&t)
                        .into_iter()
                        .flatten()
                        .flatten()
                    {
                        written.insert(r.uid());
                    }
                }
                for callee in user_callees(&e) {
                    // A call through a base handle may run any override.
                    let proto = callee.kind() == SymbolKind::MethodPrototype;
                    if (proto && {
                        let f = callee.method_prototype_flags();
                        f.contains(MethodFlags::VIRTUAL) || f.contains(MethodFlags::PURE)
                    }) || (callee.subroutine_flags().contains(MethodFlags::VIRTUAL)
                            // A `pure virtual` declaration has no body and so
                            // no implicit `this` variable, but is dispatched.
                            && (callee.subroutine_this_var().is_some()
                                || callee.subroutine_flags().contains(MethodFlags::PURE)))
                    {
                        virt_names.insert(callee.name().to_string());
                    }
                    work.push(callee);
                }
            }
            stack.extend(sv_sim_sim::process::cfg::live_children(&n));
        }
    }
    signals.sort_by_cached_key(|s| s.hierarchical_path());
    memories.sort_by_cached_key(|s| s.hierarchical_path());
    let memories_written = written
        .iter()
        .filter(|id| memory_seen.contains(*id))
        .cloned()
        .collect();
    written.retain(|id| seen.contains(id));
    (
        SubroutineAbi {
            signals,
            written,
            needs_handle: needs_handle || syncs_state,
            syncs_state,
            forces,
            memories,
            memories_written,
        },
        virt_names,
    )
}

/// The LLVM storage type of a `width`-bit variable under `repr` (a real is
/// stored as its IEEE bits, like any integral value).
fn storage_type(ctx: &Context, width: u32, repr: ValueRepr) -> inkwell::types::IntType<'_> {
    crate::types::int_type(
        ctx,
        if repr == ValueRepr::FourState {
            width * 2
        } else {
            width
        },
    )
}

/// `f` converted to the current function's float return type (`f32` for a
/// `shortreal` function).
fn fit_float_return<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    f: inkwell::values::FloatValue<'ctx>,
) -> inkwell::values::FloatValue<'ctx> {
    let ret =
        cx.b.get_insert_block()
            .and_then(|bb| bb.get_parent())
            .and_then(|func| func.get_type().get_return_type());
    let f = crate::real::as_f64(cx, f);
    match ret {
        Some(inkwell::types::BasicTypeEnum::FloatType(t)) if t == cx.ctx.f32_type() => {
            cx.b.build_float_trunc(f, cx.ctx.f32_type(), "ret_shortreal")
                .unwrap()
        }
        _ => f,
    }
}

/// One `output`/`inout`/`ref` argument's copy-back after a call: the
/// actual's lvalue expression and the temporary the callee wrote.
pub(crate) struct CopyBack<'ctx, 'd> {
    lvalue: sv_lang::Expression<'d>,
    /// The right side slang bound to the actual (`actual = <formal>`): the
    /// implicit conversion from the formal's type to the actual's (LRM
    /// 13.5), applied by the copy-back when the two types differ.
    rhs: Option<sv_lang::Expression<'d>>,
    /// The formal's own type, for the conversion's source value.
    formal_ty: Option<sv_lang::Type<'d>>,
    temp: inkwell::values::PointerValue<'ctx>,
    width: u32,
    signed: bool,
    /// The formal's shape when it is an unpacked array.
    array: Option<crate::arrays::ArrayShape<'d>>,
    /// A `ref` formal bound to a collection element (LRM 1800-2023 13.5.2):
    /// the callee wrote through the live reference, so there is no copy-back
    /// (an outdated reference's changes must not reach the collection).
    /// `Some(slot)` also closes the reference this call opened.
    elem_ref: Option<ElemRefCall<'ctx>>,
}

/// How a call's element-bound `ref` argument ends (see [`CopyBack::elem_ref`]).
#[derive(Clone, Copy)]
pub(crate) enum ElemRefCall<'ctx> {
    /// The call opened the reference held in this slot.
    Opened(PointerValue<'ctx>),
    /// The actual is itself a reference formal of the caller: its id (stored
    /// in this slot) was handed on, and the caller's own call closes it.
    Passed(PointerValue<'ctx>),
    /// The call opened a window reference (`open_ref_window`) on the actual's
    /// storage: its id / offset / root-width slots. The callee may have
    /// changed the storage by another path after it last touched the formal,
    /// so the temporary is re-read from the window before the actual is
    /// stored.
    Window {
        id: PointerValue<'ctx>,
        lo: PointerValue<'ctx>,
        ew: PointerValue<'ctx>,
        width: u32,
        signed: bool,
    },
}

/// Lowers a user subroutine call's arguments -- SV arguments (a temporary's
/// address for each by-reference formal) followed by [`SubroutineAbi`]'s
/// hidden ones -- returning them with the copy-backs to run after the call.
pub(crate) fn lower_call_args<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    callee: &sv_lang::Symbol<'d>,
    call: sv_lang::Expression<'d>,
) -> Result<
    (
        Vec<inkwell::values::BasicMetadataValueEnum<'ctx>>,
        Vec<CopyBack<'ctx, 'd>>,
    ),
    LoweringError,
> {
    let op = OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    let formals: Vec<sv_lang::Symbol<'d>> = callee.subroutine_arguments().collect();
    let mut actuals = call.operands();
    // `vif.t(...)`: the call's first operand is the virtual interface
    // (`crate::vif::call_arms` picked `callee`), not an argument.
    //
    // Classes plan Task 5 deviation (found running this task's own
    // fixtures, not a hypothetical): `call_this_class()` is `Some` for a
    // virtual-interface modport task/function call too -- not ONLY a real
    // class method call, despite its own doc comment's narrower "a class
    // method call" framing. `obj.method(...)`'s first operand is likewise
    // the receiver `obj` (`crate::classes::build_method_call` prepends the
    // already-lowered receiver HANDLE as `lower_call_args`'s caller's own
    // separate, first LLVM argument; it must not also appear here as an
    // ordinary SV argument) -- a single `||`, never two independent `if`s
    // each removing an element, so a vif call (which satisfies BOTH
    // checks) never has its first operand removed twice.
    if sv_sim_sim::netlist::vif::call_targets(&call).is_some() || call.call_this_class().is_some() {
        actuals.remove(0);
    }
    if formals.len() != actuals.len() {
        return Err(LoweringError::unsupported_at(
            "subroutine call argument count does not match the callee's formal count",
            &cx.fn_sym,
        ));
    }
    let mut out = Vec::new();
    let mut copy_backs = Vec::new();
    let actuals_all = actuals.clone();
    for (formal, actual) in formals.iter().zip(actuals) {
        // An unpacked array: a temporary copy of the actual (left unset for
        // an `output`, which the callee initializes).
        if let Some(shape) = formal
            .value_type()
            .as_ref()
            .and_then(crate::arrays::array_shape)
        {
            let lvalue = if actual.kind() == ExpressionKind::Assignment {
                actual.left().ok_or_else(|| {
                    LoweringError::unsupported_at("output argument with no target", &cx.fn_sym)
                })?
            } else {
                actual
            };
            let ty = crate::arrays::local_array_type(cx.ctx, &shape, cx.repr);
            let temp = crate::expr::entry_alloca(cx, ty, "arg_array");
            if formal.formal_argument_direction() != sv_lang::ArgumentDirection::Out {
                // The temporary is uninitialised memory: the copy takes its
                // own reference to each class handle (the callee may drop
                // its elements; the actual keeps its own, LRM 13.5) and
                // there is nothing to release.
                crate::arrays::assign_array_into_fresh(
                    cx,
                    crate::arrays::ArrayRef::whole(cx, crate::arrays::Backing::Local(temp)),
                    &shape,
                    lvalue,
                )?;
            }
            out.push(temp.into());
            if is_by_reference(formal) {
                copy_backs.push(CopyBack {
                    lvalue,
                    rhs: None,
                    formal_ty: None,
                    temp,
                    width: shape.elem.value_width(),
                    signed: shape.elem.is_signed(),
                    array: Some(shape),
                    elem_ref: None,
                });
            }
            continue;
        }
        if !is_by_reference(formal) && formal.value_type().is_some_and(|t| t.is_floating()) {
            let rv = lower_expr(cx, actual)?
                .into_real("a non-real value passed to a real formal", &cx.fn_sym)?;
            let f = crate::real::as_f64(cx, rv.llvm);
            let f = if formal.value_type().is_some_and(|t| t.bit_width() == 32) {
                cx.b.build_float_trunc(f, cx.ctx.f32_type(), "shortreal_arg")
                    .unwrap()
            } else {
                f
            };
            out.push(f.into());
            continue;
        }
        // A queue / dynamic / associative array input: the callee gets its
        // own copy.
        if !is_by_reference(formal)
            && formal
                .value_type()
                .is_some_and(|t| sv_sim_sim::state::storage::is_collection(&t))
        {
            let h = crate::collections::owned_arg(cx, actual)?;
            out.push(inkwell::values::BasicMetadataValueEnum::from(h));
            continue;
        }
        if let Some(t) = formal.value_type()
            && crate::huge::is_image_type(&t)
        {
            if is_by_reference(formal) {
                // An image temporary the callee works on in place; an
                // `inout` starts as a copy of the actual (an `output` is
                // initialised by the callee), and the copy-back stores it.
                let lvalue = if actual.kind() == ExpressionKind::Assignment {
                    actual.left().ok_or_else(|| {
                        LoweringError::unsupported_at("output argument with no target", &cx.fn_sym)
                    })?
                } else {
                    actual
                };
                let width = t.value_width();
                let temp = if formal.formal_argument_direction() == sv_lang::ArgumentDirection::Out
                {
                    crate::huge::result_image(cx, width)?
                } else {
                    crate::huge::pass_by_value(cx, lvalue, width)?
                };
                out.push(temp.into());
                copy_backs.push(CopyBack {
                    lvalue,
                    rhs: None,
                    formal_ty: Some(t),
                    temp,
                    width,
                    signed: t.is_signed(),
                    array: None,
                    elem_ref: None,
                });
                continue;
            }
            out.push(crate::huge::pass_by_value(cx, actual, t.value_width())?.into());
            continue;
        }
        if !is_by_reference(formal) {
            let width = formal.value_type().map(|t| t.value_width()).unwrap_or(0);
            let pv = crate::real::to_storage(
                cx,
                crate::collections::owned(cx, actual)?,
                width,
                "a >128-bit subroutine call argument",
            )?;
            out.push(inkwell::values::BasicMetadataValueEnum::from(pv.llvm));
            continue;
        }
        // slang binds an output/inout actual as `actual = <formal>`.
        let lvalue = if actual.kind() == ExpressionKind::Assignment {
            actual.left().ok_or_else(|| {
                LoweringError::unsupported_at("output argument with no target", &cx.fn_sym)
            })?
        } else {
            actual
        };
        let t = formal
            .value_type()
            .ok_or_else(|| LoweringError::unsupported_at("formal has no type", formal))?;
        // Only an inlined task or void function copies an event handle back
        // (`events::copy_out_formal`, LRM 1800-2023 15.5.5.1).
        if t.is_event() && formal.formal_argument_direction() != sv_lang::ArgumentDirection::In {
            return Err(LoweringError::unsupported_at(
                "an output, inout or ref event argument of a value-returning function (events \
                 are passed by handle, LRM 1800-2023 15.5.5.1; supported for tasks and void \
                 functions)",
                formal,
            ));
        }
        let width = t.value_width();
        // LRM 1800-2023 13.5.2: a `ref` to a collection element is the element
        // itself for the whole call. The temporary then carries the id of the
        // reference opened here (or the caller's own, when the actual is a
        // reference formal passed on); the callee reads and writes through it.
        let slotted = takes_elem_refs(callee) && is_elem_ref_formal(formal);
        let (temp, id_slot) = if slotted {
            let pair = elem_ref_pair_ty(cx.ctx, width, cx.repr);
            let base = crate::expr::entry_alloca(cx, pair, "arg_ref");
            let id = cx.b.build_struct_gep(pair, base, 1, "arg_ref_id").unwrap();
            let lo = cx.b.build_struct_gep(pair, base, 2, "arg_ref_lo").unwrap();
            let ew = cx.b.build_struct_gep(pair, base, 3, "arg_ref_ew").unwrap();
            (base, Some((id, lo, ew)))
        } else {
            (
                crate::expr::entry_alloca(cx, op.packed_type(width, cx.repr), "arg_ref"),
                None,
            )
        };
        let mut elem_ref = None;
        if formal.formal_argument_direction() != sv_lang::ArgumentDirection::Out {
            let cur = crate::real::to_storage(
                cx,
                crate::expr::read_modify_target(cx, lvalue)?,
                width,
                "a >128-bit inout argument",
            )?;
            // LRM 13.5: the copy-in is an assignment, so an actual of another
            // width truncates or extends (by the actual's sign) to the formal.
            let cur = crate::select::fit_width(&op, cur, width);
            cx.b.build_store(temp, cur.llvm).unwrap();
        }
        if let Some((id_slot, lo_slot, ew_slot)) = id_slot {
            let i64t = cx.ctx.i64_type();
            let (mut lov, mut ewv) = (i64t.const_zero(), i64t.const_zero());
            let idv = if let Some(elem) = part_bound_element(lvalue) {
                elem_ref = Some(ElemRefCall::Opened(id_slot));
                let (id, lo, ew) = crate::collections::open_ref_part(cx, lvalue, elem)?;
                (lov, ewv) = (lo, ew);
                id
            } else if lvalue.kind() == ExpressionKind::ElementSelect
                && lvalue
                    .select_value()
                    .and_then(|b| b.expr_type())
                    .is_some_and(|t| t.is_dynamically_sized_array() || t.is_associative_array())
            {
                elem_ref = Some(ElemRefCall::Opened(id_slot));
                crate::collections::open_ref(cx, lvalue)?
            } else if let Some(held) = crate::collections::held_ref_id(cx, lvalue) {
                elem_ref = Some(ElemRefCall::Passed(id_slot));
                (lov, ewv) = crate::collections::held_ref_part(cx, lvalue);
                held
            } else if !t.is_floating()
                && let Some((id, lo, ew)) = crate::collections::open_ref_window(cx, lvalue, width)
            {
                elem_ref = Some(ElemRefCall::Window {
                    id: id_slot,
                    lo: lo_slot,
                    ew: ew_slot,
                    width,
                    signed: t.is_signed(),
                });
                (lov, ewv) = (lo, ew);
                id
            } else {
                i64t.const_zero()
            };
            let idv = op.pack(idv, op.i_n(64).const_zero(), 64, cx.repr, false);
            cx.b.build_store(id_slot, idv.llvm).unwrap();
            for (slot, v) in [(lo_slot, lov), (ew_slot, ewv)] {
                let v = op.pack(v, op.i_n(64).const_zero(), 64, cx.repr, false);
                cx.b.build_store(slot, v.llvm).unwrap();
            }
        }
        out.push(temp.into());
        // A `const ref` formal (16.6) is never written by the callee: the copy-in
        // above is the whole binding and the actual is left alone.
        if is_const_ref(formal) {
            continue;
        }
        copy_backs.push(CopyBack {
            lvalue,
            rhs: if actual.kind() == ExpressionKind::Assignment {
                actual.right()
            } else {
                None
            },
            formal_ty: Some(t),
            temp,
            width,
            signed: t.is_signed(),
            array: None,
            elem_ref,
        });
    }
    append_hidden_args(cx, callee, &mut out)?;
    // 37.15 detail 1: the call's `ref` bindings, for the callee's frame.
    crate::vpi_dyn::emit_ref_bind(cx, callee, &actuals_all);
    Ok((out, copy_backs))
}

/// Appends [`SubroutineAbi`]'s hidden arguments (the module signals and
/// instance handle the callee reaches) to `out`; shared by every call site,
/// including an implicit base-constructor call that has no call expression.
pub(crate) fn append_hidden_args<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    callee: &sv_lang::Symbol<'d>,
    out: &mut Vec<inkwell::values::BasicMetadataValueEnum<'ctx>>,
) -> Result<(), LoweringError> {
    let op = OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    let abi = subroutine_abi(callee);
    for sig in &abi.signals {
        // A static callee's input formal is rewritten from the actual by every
        // call (16.6: it preserves no state), so a caller that does not hold
        // the callee's instance state (a concurrent assertion's leaf) passes a
        // scratch slot.
        if !cx.locals.contains_key(&sig.uid())
            && sig.kind() == SymbolKind::FormalArgument
            && (sig.formal_argument_direction() == sv_lang::ArgumentDirection::In
                || is_const_ref(sig))
            && let Some(t) = sig.value_type()
            && t.is_integral()
            && !crate::huge::is_huge_width(t.value_width())
        {
            let ty = op.packed_type(t.value_width(), cx.repr);
            let scratch = crate::expr::entry_alloca(cx, ty, "static_formal_scratch");
            cx.b.build_store(scratch, ty.const_zero()).unwrap();
            out.push(scratch.into());
            continue;
        }
        let (ptr, _, _) = *cx.locals.get(&sig.uid()).ok_or_else(|| {
            LoweringError::unsupported_at(
                &format!(
                    "call to `{}` reaches module signal `{}`, which this caller cannot see \
                     (a call from another module?)",
                    callee.name(),
                    sig.name()
                ),
                &cx.fn_sym,
            )
        })?;
        // The callee writes a huge signal through this shadow without knowing
        // which window it touched: the whole signal is dirty, or the caller's
        // commit (which sends only dirty windows to STATE) would drop the
        // write and no reader of the signal would ever see it.
        if abi.written.contains(&sig.uid())
            && let Some(wt) = &cx.write_through
            && let Some(&(slot, width, _)) = wt.signals.get(&ptr)
            && crate::huge::is_huge_width(width)
        {
            let i64t = cx.ctx.i64_type();
            crate::huge::rt_mark(
                cx,
                wt.handle,
                slot,
                width,
                i64t.const_zero(),
                i64t.const_int(u64::from(width), false),
            );
        }
        out.push(ptr.into());
    }
    if abi.needs_handle {
        // The handle passed is the caller's instance: a hierarchical call into
        // another instance (`u1.f()`) would read and write that instance's
        // memories (and signal its block events) in the wrong one.
        let accessor = cx.mem_accessor.ok_or_else(|| {
            LoweringError::unsupported_at(
                "call to a subroutine that uses a module memory from a context without an \
                 instance handle",
                &cx.fn_sym,
            )
        })?;
        // LRM 23.6: the callee runs in its own instance, so its memories and
        // block events are that instance's. A call within one instance passes
        // the caller's handle; a hierarchical call into another passes the
        // instance owning the foreign slot the runner registered under the
        // callee's symbol (`mem_signals`, see `foreign_references`).
        let other_instance = matches!((
            sv_sim_sim::netlist::enclosing_instance_body(callee),
            sv_sim_sim::netlist::enclosing_instance_body(&cx.fn_sym),
        ), (Some(theirs), Some(ours)) if theirs.uid() != ours.uid())
            || package_handle_callee(callee, &cx.fn_sym);
        if other_instance {
            let Some(info) = cx.mem_signals.get(&callee.uid()) else {
                return Err(LoweringError::unsupported_at(
                    &format!(
                        "hierarchical call to `{}` in another instance, which uses a module \
                         memory or samples a covergroup there, from a context that cannot \
                         reach that instance",
                        callee.name()
                    ),
                    &cx.fn_sym,
                ));
            };
            let ptr_ty = cx.ctx.ptr_type(inkwell::AddressSpace::default());
            let i32t = cx.ctx.i32_type();
            let f = cx
                .module
                .get_function(crate::process_lower::SV_RT_SLOT_OWNER_SYMBOL)
                .unwrap_or_else(|| {
                    cx.module.add_function(
                        crate::process_lower::SV_RT_SLOT_OWNER_SYMBOL,
                        ptr_ty.fn_type(&[ptr_ty.into(), i32t.into()], false),
                        None,
                    )
                });
            let owner =
                cx.b.build_call(
                    f,
                    &[
                        accessor.handle.into(),
                        i32t.const_int(u64::from(info.slot), false).into(),
                    ],
                    "callee_instance",
                )
                .unwrap()
                .try_as_basic_value();
            out.push(owner.unwrap_basic().into());
        } else {
            out.push(accessor.handle.into());
        }
    }
    Ok(())
}

/// Runs a call's output/inout copy-backs (see [`lower_call_args`]).
pub(crate) fn copy_back_outputs<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    copy_backs: Vec<CopyBack<'ctx, 'd>>,
) -> Result<(), LoweringError> {
    for cb in copy_backs {
        match cb.elem_ref {
            Some(ElemRefCall::Opened(slot)) => {
                crate::collections::close_ref(cx, slot, 64);
                continue;
            }
            // A window reference: the usual copy-back then stores the
            // window's current value into the actual (committing the
            // caller's signal when the callee only wrote through the formal).
            Some(ElemRefCall::Window {
                id,
                lo,
                ew,
                width,
                signed,
            }) => {
                crate::collections::refresh_slot(
                    cx,
                    &crate::collections::ElemRefSlot {
                        id,
                        id_width: 64,
                        width,
                        signed,
                        part: Some(crate::collections::PartSlots { lo, elem_width: ew }),
                    },
                    cb.temp,
                );
                crate::collections::close_ref(cx, id, 64);
            }
            // The actual is a reference formal of the caller: when it holds a
            // live reference the callee wrote through it; when it holds none
            // (id 0: the caller's own actual is a plain variable) the usual
            // copy-back writes the caller's formal.
            Some(ElemRefCall::Passed(slot)) => {
                let id = crate::collections::load_ref_slot(cx, slot);
                let none =
                    cx.b.build_int_compare(
                        inkwell::IntPredicate::EQ,
                        id,
                        cx.ctx.i64_type().const_zero(),
                        "ref_unbound",
                    )
                    .unwrap();
                let f = cx.b.get_insert_block().unwrap().get_parent().unwrap();
                let run = cx.ctx.append_basic_block(f, "copy_back");
                let done = cx.ctx.append_basic_block(f, "copy_back_done");
                cx.b.build_conditional_branch(none, run, done).unwrap();
                cx.b.position_at_end(run);
                copy_back_one(cx, cb)?;
                cx.b.build_unconditional_branch(done).unwrap();
                cx.b.position_at_end(done);
                continue;
            }
            None => {}
        }
        copy_back_one(cx, cb)?;
    }
    Ok(())
}

/// One argument's copy-back (see [`copy_back_outputs`]).
fn copy_back_one<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    cb: CopyBack<'ctx, 'd>,
) -> Result<(), LoweringError> {
    let op = OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    if let Some(shape) = &cb.array {
        let Some((dst, dst_shape)) = crate::arrays::array_target(cx, cb.lvalue)? else {
            // A class property or unpacked-struct field array has no row
            // storage: store the temporary's rows as the member's flat
            // value (LRM 13.5 copy-out, 7.4, 8.5).
            if shape.rows() <= crate::arrays::MAX_UNROLLED_ROWS
                && crate::collections::handle_offsets(&shape.elem).is_empty()
                && matches!(
                    cb.lvalue.kind(),
                    ExpressionKind::MemberAccess | ExpressionKind::NamedValue
                )
            {
                let src =
                    crate::arrays::ArrayRef::whole(cx, crate::arrays::Backing::Local(cb.temp));
                let i64t = cx.ctx.i64_type();
                let mut rows = (0..shape.rows())
                    .map(|r| {
                        crate::arrays::load_row(cx, &src, i64t.const_int(r, false), &shape.elem)
                    })
                    .collect::<Result<Vec<_>, _>>()?;
                rows.reverse();
                let packed = op.concat4(&rows);
                crate::expr::store_to(cx, cb.lvalue, crate::expr::LoweredValue::Packed(packed))?;
                return Ok(());
            }
            return Err(LoweringError::unsupported_at(
                "an array output argument whose actual is neither an array variable nor a \
                 class property / struct field",
                &cx.fn_sym,
            ));
        };
        crate::arrays::copy_array(
            cx,
            dst,
            &dst_shape,
            crate::arrays::ArrayRef::whole(cx, crate::arrays::Backing::Local(cb.temp)),
            shape,
        )?;
        return Ok(());
    }
    if crate::huge::is_image_width(cb.width) {
        crate::expr::store_to(
            cx,
            cb.lvalue,
            crate::expr::LoweredValue::Huge(crate::huge::HugeValue {
                ptr: cb.temp,
                width: cb.width,
                signed: cb.signed,
            }),
        )?;
        crate::huge::release(cb.temp);
        return Ok(());
    }
    let llvm =
        cx.b.build_load(op.packed_type(cb.width, cx.repr), cb.temp, "arg_ref_out")
            .unwrap()
            .into_int_value();
    let value = PackedValue {
        llvm,
        width: cb.width,
        repr: cx.repr,
        signed: cb.signed,
    };
    // The actual's type differs from the formal's (width, signedness,
    // real <-> integral, 2- <-> 4-state): slang bound `actual =
    // Conversion(<formal>)`, which the copy-back lowers with the formal's
    // value standing in for the reference.
    if let (Some(rhs), Some(fty), Some(lty)) = (cb.rhs, cb.formal_ty, cb.lvalue.expr_type())
        && rhs.kind() == ExpressionKind::Conversion
        && (fty.is_floating() != lty.is_floating()
            || (lty.is_integral()
                && (fty.value_width() != lty.value_width()
                    || fty.is_signed() != lty.is_signed()
                    || fty.is_four_state() != lty.is_four_state())))
    {
        let formal = if fty.is_floating() {
            crate::expr::LoweredValue::Real(crate::real::bits_to_real(cx, value))
        } else {
            crate::expr::LoweredValue::Packed(value)
        };
        let saved = cx.lvalue_ref.replace(Some(formal));
        let converted = crate::expr::lower_expr(cx, rhs);
        cx.lvalue_ref.set(saved);
        crate::expr::store_to(cx, cb.lvalue, converted?)?;
        return Ok(());
    }
    // LRM 13.5: the copy-out is an assignment, so a formal of another
    // width than the actual truncates or extends (by the formal's sign).
    let value = match cb.lvalue.expr_type() {
        Some(t) if t.is_integral() => crate::select::fit_width(&op, value, t.value_width()),
        _ => value,
    };
    // An element of a queue / dynamic / associative array as the actual
    // (`f(m[k])`): a whole-element store through the collection, which
    // allocates a nonexistent associative entry (LRM 1800-2023 7.8.7).
    if cb.lvalue.kind() == ExpressionKind::ElementSelect
        && cb
            .lvalue
            .select_value()
            .and_then(|b| crate::collections::coll_of_expr(&b))
            .is_some_and(|c| crate::collections::handle_offsets(&c.elem).is_empty())
        && let Some(done) = crate::collections::write_element(
            cx,
            cb.lvalue,
            crate::expr::LoweredValue::Packed(value),
        )
    {
        done?;
        return Ok(());
    }
    // A member or select of such an element (`f(q[i].m)`) read-modify-writes
    // the element (LRM 7.10.2).
    if crate::collections::partial_element_target(cb.lvalue).is_some() {
        crate::expr::store_to(cx, cb.lvalue, crate::expr::LoweredValue::Packed(value))?;
        return Ok(());
    }
    crate::select::lower_assign_to(cx, cb.lvalue, value)?;
    Ok(())
}

/// The `q[i]` element of a non-associative queue / dynamic array of plain
/// values that the `ref` actual `e` names a member or select of
/// (`f(q[i].m)`, `f(d[i][3:0])`): the reference is then the element's plus
/// the part's offset (`collections::open_ref_part`).
fn part_bound_element<'d>(e: sv_lang::Expression<'d>) -> Option<sv_lang::Expression<'d>> {
    let elem = crate::collections::partial_element_target(e)?;
    let c = crate::collections::coll_of_expr(&elem.select_value()?)?;
    (!c.assoc && crate::collections::handle_offsets(&c.elem).is_empty()).then_some(elem)
}

/// Every variable a subroutine declares -- in its own scope or any nested
/// `begin`/`end` block -- excluding its arguments and its implicit result
/// variable, in declaration (pre-order) order.
fn subroutine_locals<'d>(sym: &sv_lang::Symbol<'d>) -> Vec<sv_lang::Symbol<'d>> {
    let ret_id = sym.subroutine_return_val_var().map(|r| r.uid());
    let mut out: Vec<sv_lang::Symbol<'d>> = Vec::new();
    let mut seen = std::collections::HashSet::new();
    let mut take = |m: sv_lang::Symbol<'d>, out: &mut Vec<sv_lang::Symbol<'d>>| {
        if m.kind() == SymbolKind::Variable && Some(m.uid()) != ret_id && seen.insert(m.uid()) {
            out.push(m);
        }
    };
    for m in sym.members() {
        take(m, &mut out);
    }
    if let Some(body) = sv_sim_sim::process::cfg::proc_body(sym) {
        let mut stack = vec![body.as_sem_node()];
        while let Some(n) = stack.pop() {
            if let Some(s) = n.as_statement() {
                for block in sv_sim_sim::process::cfg::block_scopes(&s) {
                    for m in block.members() {
                        take(m, &mut out);
                    }
                }
            }
            let mut kids = sv_sim_sim::process::cfg::live_children(&n);
            kids.reverse();
            stack.extend(kids);
        }
        // The `matches` pattern variables (LRM 12.6), declared by no block.
        for v in sv_sim_sim::patterns::pattern_vars(body.as_sem_node()) {
            if seen.insert(v.uid()) {
                out.push(v);
            }
        }
    }
    out
}

/// The automatic locals of a subroutine that own a class handle or a
/// collection (directly or inside an unpacked struct): the ones released when
/// the call returns. Fixed-size arrays, `this`, static variables and `matches`
/// pattern variables (which hold no count of their own) are not among them.
fn owned_handle_locals<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    decls: &[sv_lang::Symbol<'d>],
    this_var: Option<sv_lang::Symbol<'d>>,
) -> Vec<sv_lang::Symbol<'d>> {
    let pattern: std::collections::HashSet<_> = sv_sim_sim::process::cfg::proc_body(&cx.fn_sym)
        .map(|b| {
            sv_sim_sim::patterns::pattern_vars(b.as_sem_node())
                .iter()
                .map(|v| v.uid())
                .collect()
        })
        .unwrap_or_default();
    decls
        .iter()
        .copied()
        .filter(|l| {
            this_var.is_none_or(|tv| tv.uid() != l.uid())
                && !pattern.contains(&l.uid())
                && l.variable_lifetime() != sv_lang::VariableLifetime::Static
                && !sv_sim_sim::netlist::is_static_procedural_var(l)
                && cx.locals.contains_key(&l.uid())
                && l.value_type().is_some_and(|t| {
                    crate::arrays::array_shape(&t).is_none()
                        && !crate::collections::handle_offsets(&t).is_empty()
                })
        })
        .collect()
}

/// The by-value (`input`) formals of a subroutine that hold a class handle or
/// a collection: each owns one count the caller took for it, released when
/// the call returns (LRM 13.5.1). Unlike [`owned_handle_locals`] they are
/// never zeroed on entry -- they arrive holding the argument.
fn owned_handle_formals<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    args: &[sv_lang::Symbol<'d>],
) -> Vec<sv_lang::Symbol<'d>> {
    args.iter()
        .copied()
        .filter(|a| {
            !is_by_reference(a)
                && cx.locals.contains_key(&a.uid())
                && a.value_type().is_some_and(|t| {
                    crate::arrays::array_shape(&t).is_none()
                        && !crate::collections::handle_offsets(&t).is_empty()
                })
        })
        .collect()
}

/// Releases what the owned handle locals hold (an automatic variable ends
/// with the call, LRM 6.21), just before every `ret` of `f`. A `return` of a
/// local hands its count to the caller and zeroes the slot first, so it
/// releases nothing here.
fn release_locals_before_returns<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    f: FunctionValue<'ctx>,
    locals: &[sv_lang::Symbol<'d>],
) {
    if locals.is_empty() {
        return;
    }
    let rets: Vec<_> = f
        .get_basic_block_iter()
        .filter_map(|bb| bb.get_terminator())
        .filter(|t| t.get_opcode() == inkwell::values::InstructionOpcode::Return)
        .collect();
    for t in rets {
        cx.b.position_before(&t);
        for local in locals {
            release_local(cx, local);
        }
    }
}

/// Releases the handles `local` holds, as an overwrite of it would.
fn release_local<'ctx, 'd>(cx: &LowerCtx<'ctx, 'd, '_>, local: &sv_lang::Symbol<'d>) {
    let (ptr, width, signed) = cx.locals[&local.uid()];
    let Some(t) = local.value_type() else { return };
    let old =
        cx.b.build_load(storage_type(cx.ctx, width, cx.repr), ptr, "local_old")
            .unwrap()
            .into_int_value();
    let pv = PackedValue {
        llvm: old,
        width,
        repr: cx.repr,
        signed,
    };
    crate::collections::release_handles(cx, &t, LoweredValue::Packed(pv));
}

/// A `return` of the automatic local `e` moves its count to the caller:
/// null the slot so the exit-time release finds nothing.
fn move_out_local<'ctx, 'd>(cx: &LowerCtx<'ctx, 'd, '_>, e: sv_lang::Expression<'d>) {
    let Some(v) = e.referenced_symbol() else {
        return;
    };
    let is_arg = cx.fn_sym.subroutine_arguments().any(|a| a.uid() == v.uid());
    let is_result = cx
        .fn_sym
        .subroutine_return_val_var()
        .is_some_and(|r| r.uid() == v.uid());
    let holds = v
        .value_type()
        .is_some_and(|t| !crate::collections::handle_offsets(&t).is_empty());
    if holds
        && !is_arg
        && !is_result
        && let Some(&(ptr, width, _)) = cx.locals.get(&v.uid())
    {
        cx.b.build_store(ptr, storage_type(cx.ctx, width, cx.repr).const_zero())
            .unwrap();
    }
}

/// Stores `local`'s starting value: its declaration initializer, or its
/// type's default (0 for 2-state, all-X for 4-state).
fn init_local<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    local: &sv_lang::Symbol<'d>,
) -> Result<(), LoweringError> {
    if crate::class_events::init_local(cx, local)? {
        return Ok(());
    }
    // An automatic `event` (or event array) of a function is a row of the
    // body's event pool, like a task local (LRM 15.5).
    if crate::events::is_pool_event_var(cx, local) {
        return crate::events::init_event_var(cx, local);
    }
    let (ptr, width, signed) = cx.locals[&local.uid()];
    if let Some(shape) = local
        .value_type()
        .as_ref()
        .and_then(crate::arrays::array_shape)
    {
        return crate::arrays::init_array_var(cx, ptr, &shape, local.initializer());
    }
    // A vector wider than an LLVM integer is an image.
    if let Some(t) = local.value_type()
        && crate::huge::is_image_type(&t)
    {
        return match local.initializer() {
            Some(init) => crate::huge::store_expr_to_image(cx, local, init),
            None => crate::huge::init_image(cx, ptr, width, t.is_four_state()),
        };
    }
    let value = match local.initializer() {
        // A queue / dynamic / associative array starts as a copy.
        Some(init)
            if local
                .value_type()
                .is_some_and(|t| sv_sim_sim::state::storage::is_collection(&t)) =>
        {
            crate::collections::owned_arg(cx, init)?
        }
        Some(init) => {
            let v = crate::real::to_storage(
                cx,
                crate::collections::owned(cx, init)?,
                width,
                "a >128-bit local initializer",
            )?;
            if v.width != width {
                return Err(LoweringError::unsupported_at(
                    &format!(
                        "local initializer is {} bits for a {width}-bit variable",
                        v.width
                    ),
                    local,
                ));
            }
            v.llvm
        }
        None => {
            let ty = local
                .value_type()
                .ok_or_else(|| LoweringError::unsupported_at("local has no type", local))?;
            let _ = signed;
            crate::arrays::default_value(cx, &ty)
        }
    };
    cx.b.build_store(ptr, value).unwrap();
    Ok(())
}

pub fn lower_function<'ctx, 'd>(
    ctx: &'ctx Context,
    module: &Module<'ctx>,
    _design: &sv_lang::Design,
    sym: &sv_lang::Symbol<'d>,
    repr: ValueRepr,
) -> Result<FunctionValue<'ctx>, LoweringError> {
    let (fn_ty, _is_void_return) = subroutine_fn_type(ctx, sym, repr, false)?;
    let f = module.add_function(sym.name(), fn_ty, None);
    lower_function_body(ctx, module, sym, repr, f, None)
}

/// Whether a `disable label;` statement sits anywhere in `s`'s subtree.
fn contains_disable(s: &sv_lang::Statement<'_>) -> bool {
    let mut stack = vec![s.as_sem_node()];
    while let Some(n) = stack.pop() {
        if n.as_statement()
            .is_some_and(|c| c.kind() == StatementKind::Disable)
        {
            return true;
        }
        stack.extend(sv_sim_sim::process::cfg::live_children(&n));
    }
    false
}

pub fn lower_stmt<'ctx, 'd, 'm>(
    cx: &mut LowerCtx<'ctx, 'd, 'm>,
    s: sv_lang::Statement<'d>,
) -> Result<(), LoweringError> {
    // A statement slang demoted to `Invalid` (a dead `if`/`case` arm it could
    // not bind, LRM 12.4/12.5) lowers as its real live statement.
    let s = sv_sim_sim::process::cfg::unwrap_invalid(s);
    // VPI `cbStmt` (Table 38-6): before the statement executes.
    crate::vpi_dyn::emit_entry_probe(cx, &s);
    match s.kind() {
        StatementKind::List | StatementKind::Block => {
            // Its automatic variables are initialized on entry (LRM
            // 1800-2023 §6.21).
            for var in sv_sim_sim::process::cfg::block_automatic_vars(&s, false) {
                // A loop re-enters the block: what the variable held from the
                // last pass ends with that pass (zero on the first).
                if var.value_type().is_some_and(|t| {
                    crate::arrays::array_shape(&t).is_none()
                        && !crate::collections::handle_offsets(&t).is_empty()
                }) && cx.locals.contains_key(&var.uid())
                {
                    release_local(cx, &var);
                }
                init_local(cx, &var)?;
            }
            // A named block with a `disable` in it is left through an exit
            // block (LRM 9.6.2); `disable name;` branches there.
            let exit = s
                .block_symbol()
                .map(|b| b.name().to_string())
                .filter(|n| !n.is_empty() && contains_disable(&s))
                .map(|name| {
                    let (_, f) = current_block_and_fn(cx)?;
                    let bb = cx.ctx.append_basic_block(f, "disable_exit");
                    cx.block_exits.push((name, bb));
                    Ok::<_, LoweringError>(bb)
                })
                .transpose()?;
            // 19.3 `@@(begin blk)` of a named block a covergroup names.
            let blk_event = s
                .block_symbol()
                .filter(crate::covergroup::is_block_target)
                .zip(cx.mem_accessor.as_ref().map(|m| m.handle));
            if let Some((b, h)) = &blk_event {
                sync_subroutine_writes(cx)?;
                crate::covergroup::emit_block_event_of(cx, *h, b, false)?;
            }
            for child in sv_sim_sim::process::cfg::live_statements(&s) {
                // Review fix (r1): if a prior sibling statement already left
                // the builder's current block terminated -- e.g. a two-way-
                // terminating `if (c) return 1; else return 2;` (both
                // branches return, so the `if`'s own merge block is emitted
                // as `unreachable`) -- every following sibling statement is
                // genuinely unreachable dead code per SV's own semantics
                // (legal, iverilog-accepted: `if (c) return 1; else return
                // 2; return 3;` never executes the trailing `return 3;`).
                // Lowering must stop here instead of appending more
                // instructions after that block's terminator, which LLVM's
                // verifier rejects outright ("Terminator found in the middle
                // of a basic block!") -- see
                // `dead_code_after_two_way_terminating_if_does_not_fail_
                // lowering`, tests/branch_reduction.rs.
                if current_block_terminated(cx) {
                    break;
                }
                lower_stmt(cx, child)?;
            }
            if let Some(bb) = exit {
                cx.block_exits.pop();
                if !current_block_terminated(cx) {
                    cx.b.build_unconditional_branch(bb).unwrap();
                }
                cx.b.position_at_end(bb);
            }
            if let Some((b, h)) = &blk_event
                && !current_block_terminated(cx)
            {
                sync_subroutine_writes(cx)?;
                crate::covergroup::emit_block_event_of(cx, *h, b, true)?;
            }
            Ok(())
        }
        // `disable blk;` of an enclosing named block of this subroutine (LRM
        // 1800-2023 §9.6.2): leave it, like `break` leaves a loop. Any other
        // target (the subroutine itself, another process's block) is not
        // lowered in a compiled function.
        StatementKind::Disable => {
            let label = sv_sim_sim::process::cfg::disable_label(&s)
                .map_err(|e| LoweringError::unsupported_at(&e.to_string(), &cx.fn_sym))?;
            // `disable <deferred assertion label>` (16.4.4).
            if crate::process_lower::lower_deferred_disable(cx, &label)? {
                return Ok(());
            }
            // A void function disabling a block outside itself (LRM 9.6.2: the
            // block is its caller's, or its caller's caller's): the function
            // ends and the call site that reaches the block leaves it
            // (`SwitchOn::FnDisable`; C code in between sees the disabled
            // state, 35.9). A non-void function has no result to return
            // early with, so it stays refused.
            if !cx.block_exits.iter().any(|(n, _)| *n == label)
                && sv_sim_sim::process::cfg::is_function_disable_label(&label)
                && cx
                    .fn_sym
                    .subroutine_return_type()
                    .is_none_or(|t| t.is_void())
            {
                let rt = cx
                    .module
                    .get_function(crate::dpi::SV_RT_DPI_FN_DISABLE_SET_SYMBOL)
                    .unwrap_or_else(|| {
                        cx.module.add_function(
                            crate::dpi::SV_RT_DPI_FN_DISABLE_SET_SYMBOL,
                            cx.ctx.void_type().fn_type(
                                &[cx.ctx.ptr_type(inkwell::AddressSpace::default()).into()],
                                false,
                            ),
                            None,
                        )
                    });
                let name =
                    cx.b.build_global_string_ptr(&label, "fn_disable_label")
                        .unwrap()
                        .as_pointer_value();
                cx.b.build_call(rt, &[name.into()], "").unwrap();
                copy_out_formals(cx);
                cx.b.build_return(None).unwrap();
                return Ok(());
            }
            let &(_, bb) = cx
                .block_exits
                .iter()
                .rev()
                .find(|(n, _)| *n == label)
                .ok_or_else(|| {
                    LoweringError::unsupported_at(
                        &format!(
                            "`disable {label};` in a function whose target is not an \
                             enclosing named block of the function"
                        ),
                        &cx.fn_sym,
                    )
                })?;
            cx.b.build_unconditional_branch(bb).unwrap();
            Ok(())
        }
        // The declared variable itself is set up at subroutine entry
        // (`subroutine_locals` + `init_local`).
        StatementKind::VariableDeclaration => Ok(()),
        // `;` (LRM 1800-2023 §12.3: a null statement).
        StatementKind::Empty => Ok(()),
        StatementKind::Return => {
            // R-run Task 10: a bare `return;` (no expression) is legal only
            // inside a VOID subroutine (a `task` with no return value -- the
            // LRM requires a `function`'s own `return` to always carry a
            // value) and lowers directly to `ret void`. This is Task 10's
            // own scope, not a pre-existing gap this task papers over: the
            // pre-Task-10 code rejected EVERY bare `return;` unconditionally
            // ("void return in P0"), because no task/void-returning
            // subroutine could reach `lower_stmt` at all before this task's
            // `lower_function` accepted a `None` return type in the first
            // place.
            let e = match s.expr() {
                Some(e) => e,
                None => {
                    copy_out_formals(cx);
                    cx.b.build_return(None).unwrap();
                    return Ok(());
                }
            };
            // A result wider than an LLVM integer: stored to the result image.
            if cx
                .fn_sym
                .subroutine_return_type()
                .is_some_and(|t| crate::huge::is_image_type(&t))
                && let Some(rv) = cx.fn_sym.subroutine_return_val_var()
            {
                crate::huge::store_expr_to_image(cx, &rv, e)?;
                copy_out_formals(cx);
                cx.b.build_return(None).unwrap();
                return Ok(());
            }
            // An array-valued function: the value goes to its result
            // variable (the caller's temporary).
            if let Some(shape) = array_result(&cx.fn_sym)
                && let Some(rv) = cx.fn_sym.subroutine_return_val_var()
            {
                let (ptr, _, _) = cx.locals[&rv.uid()];
                crate::arrays::assign_array(
                    cx,
                    crate::arrays::ArrayRef::whole(cx, crate::arrays::Backing::Local(ptr)),
                    &shape,
                    e,
                )?;
                copy_out_formals(cx);
                cx.b.build_return(None).unwrap();
                return Ok(());
            }
            // A queue / dynamic / associative array result: the caller gets
            // its own collection -- this call's automatic local as is (it
            // is never used again), anything else a copy.
            if cx
                .fn_sym
                .subroutine_return_type()
                .is_some_and(|t| sv_sim_sim::state::storage::is_collection(&t))
            {
                // A static function keeps its result variable.
                if cx.fn_sym.subroutine_default_lifetime()
                    == Some(sv_lang::VariableLifetime::Static)
                    && let Some(rv) = cx.fn_sym.subroutine_return_val_var()
                    && let Some(t) = cx.fn_sym.subroutine_return_type()
                {
                    let (slot, _, _) = cx.locals[&rv.uid()];
                    let v = crate::collections::store_static_result(cx, &t, slot, e)?;
                    copy_out_formals(cx);
                    cx.b.build_return(Some(&v)).unwrap();
                    return Ok(());
                }
                let local = sv_sim_sim::symid::is_value_name(e.kind())
                    && e.referenced_symbol().is_some_and(|v| {
                        v.kind() == SymbolKind::Variable
                            && v.variable_lifetime() == sv_lang::VariableLifetime::Automatic
                    });
                let v = if local {
                    let v = lower_expr(cx, e)?
                        .into_packed("a collection result", &cx.fn_sym)?
                        .llvm;
                    move_out_local(cx, e);
                    v
                } else if let Some(c) = cx
                    .fn_sym
                    .subroutine_return_type()
                    .and_then(|t| crate::collections::coll_of(&t))
                {
                    // A bounded-queue result discards the elements beyond
                    // its bound (LRM 1800-2023 §7.10.5), as an assignment
                    // to the queue would.
                    let h = crate::collections::owned_value(cx, e)?;
                    let h = crate::collections::clamp_bound(cx, &c, h);
                    crate::collections::handle_value(cx, h).llvm
                } else {
                    crate::collections::owned_arg(cx, e)?
                };
                copy_out_formals(cx);
                cx.b.build_return(Some(&v)).unwrap();
                return Ok(());
            }
            // Task 8 (CG-037): `lower_expr` now returns either an integral
            // `PackedValue` or a floating `RealValue` -- `build_return`
            // takes `&dyn BasicValue`, which both `IntValue` and
            // `FloatValue` implement, so route through the common
            // `BasicValueEnum` rather than assuming `.llvm` is always an
            // `IntValue` (`RealValue`'s `.llvm` is a `FloatValue`).
            // A struct holding collections or a class handle: the caller
            // gets its own reference unless this is an automatic local's
            // (never used again, so its reference moves to the caller). A
            // method's own `this` is a `Variable` too, but it holds no
            // reference of its own to give away.
            let this_uid = cx.fn_sym.subroutine_this_var().map(|t| t.uid());
            let automatic_local = sv_sim_sim::symid::is_value_name(e.kind())
                && e.referenced_symbol().is_some_and(|v| {
                    v.kind() == SymbolKind::Variable
                        && v.variable_lifetime() == sv_lang::VariableLifetime::Automatic
                        && Some(v.uid()) != this_uid
                });
            let value = if automatic_local {
                let v = lower_expr(cx, e)?;
                move_out_local(cx, e);
                v
            } else {
                crate::collections::owned(cx, e)?
            };
            let v = match value {
                LoweredValue::Packed(p) => inkwell::values::BasicValueEnum::from(p.llvm),
                LoweredValue::Str(s) => {
                    inkwell::values::BasicValueEnum::from(crate::strings::as_packed(cx, s).llvm)
                }
                LoweredValue::Real(r) => {
                    inkwell::values::BasicValueEnum::from(fit_float_return(cx, r.llvm))
                }
                // Review fix r2 (CG-016/CG-019/CG-129): a >WIDE_THRESHOLD-bit
                // `return` expression now reaches this match as
                // `LoweredValue::Wide` instead of panicking inside
                // `const_svint` before it ever got here. Returning a wide
                // (limb-array) value BY VALUE from a function is a distinct
                // ABI question (how a `WideValueRef`'s stack storage crosses
                // a `ret` boundary) that no task in this wave has designed
                // yet -- out of Task 15's scope, same as wide arithmetic
                // (Task 16). A named, loud `LoweringError` here, never a
                // panic and never a silent narrow truncation of the value.
                LoweredValue::Wide(_) | LoweredValue::Huge(_) => {
                    return Err(LoweringError::unsupported_at(
                        "return of a >WIDE_THRESHOLD-bit wide value (no wide \
                         function-return ABI exists yet)",
                        &cx.fn_sym,
                    ));
                }
            };
            copy_out_formals(cx);
            cx.b.build_return(Some(&v)).unwrap();
            Ok(())
        }
        // Task 9 (CG-090, CG-007) / Task 26 (CG-121): a plain expression used
        // as a statement -- either a scalar `=` assignment (`expr.rs`'s
        // `Assignment` arm handles the store; the produced value is
        // discarded, only the side effect matters at statement position), a
        // system call (routed on into `lower_expr`'s own `Call` arm, which
        // stays restricted to the CG-042/CG-043 subset it already handles),
        // or (new in Task 26) a bare user task/function call, which
        // `lower_expr`'s `Call` arm deliberately still rejects outright (see
        // that arm's own doc comment: "non-system-function call ... out of
        // Task 13's/CG-042's scope") -- so a task call is intercepted HERE,
        // before ever reaching `lower_expr`, and routed to `lower_task_call`
        // instead.
        StatementKind::ExpressionStatement => {
            let e = s.expr().ok_or_else(|| {
                LoweringError::unsupported_at("expression statement missing expr", &cx.fn_sym)
            })?;
            if e.kind() == ExpressionKind::Call && e.is_system_call() == Some(false) {
                return lower_task_call(cx, e);
            }
            // Task 30 (CG-043 partial, CG-044, CG-046 partial, CG-108): a
            // `$display`/`$write`/`$strobe`/`$monitor` system call is
            // intercepted HERE, before ever reaching `expr.rs`'s generic
            // `Call` arm -- that arm only knows CG-042's constant-foldable
            // type-query subset and would otherwise reject every one of
            // these with a named "runtime-behavior system call ... is
            // CG-043's scope" error (see that arm's own doc comment, which
            // names this exact routing point).
            // `$info`/`$warning`/`$error`/`$fatal` (LRM 1800-2023 §20.10) and
            // `$finish`/`$stop` in a subroutine: lowered as in a process. The
            // runtime reaches the scheduler through the running process, so
            // no handle is needed.
            if e.kind() == ExpressionKind::Call
                && e.is_system_call() == Some(true)
                && let Some(sub) = e.system_subroutine()
            {
                let which = sub.known_name_id();
                use sv_lang::KnownSystemName as K;
                if matches!(
                    which,
                    K::Info | K::Warning | K::Error | K::Fatal | K::Finish | K::Stop
                ) {
                    let sys_fns =
                        crate::process_lower::fetch_or_declare_sys_call_fns(cx.ctx, cx.module);
                    let handle = cx
                        .ctx
                        .ptr_type(inkwell::AddressSpace::default())
                        .const_null();
                    if matches!(which, K::Finish | K::Stop) {
                        crate::process_lower::lower_finish_call(cx, handle, &sys_fns, e, which)?;
                    } else {
                        crate::process_lower::lower_severity_call(cx, handle, &sys_fns, e, which)?;
                    }
                    // Nothing after `$finish`/`$stop`/`$fatal` runs.
                    if matches!(which, K::Finish | K::Stop | K::Fatal) {
                        let (_, f) = current_block_and_fn(cx)?;
                        crate::stmt_shared::leave_now(cx, f);
                        let rest = cx.ctx.append_basic_block(f, "after_finish");
                        cx.b.position_at_end(rest);
                    }
                    return Ok(());
                }
            }
            if e.kind() == ExpressionKind::Call
                && e.is_system_call() == Some(true)
                && let Some(sub) = e.system_subroutine()
                && sub.known_name_id() == sv_lang::KnownSystemName::PrintTimeScale
            {
                let display = crate::systask::fetch_or_declare_display_family_fn(
                    cx.ctx,
                    cx.module,
                    crate::systask::DisplayFamily::Display,
                );
                crate::process_lower::lower_printtimescale_call(cx, display, e)?;
                return Ok(());
            }
            if e.kind() == ExpressionKind::Call
                && e.is_system_call() == Some(true)
                && let Some(sub) = e.system_subroutine()
                && let Some(family) = crate::systask::classify_display_family(sub.known_name_id())
            {
                // `$strobe`/`$monitor` in a subroutine (LRM 21.2.2, 21.2.3):
                // as in a process, a per-call-site thunk reads the module
                // signals at the end of the timestep, through the instance
                // handle. A subroutine local is a named error there (it is
                // gone when the thunk runs).
                use crate::systask::DisplayFamily as F;
                if matches!(family, F::Strobe | F::Monitor) {
                    let handle = cx.mem_accessor.as_ref().map(|m| m.handle).ok_or_else(|| {
                        LoweringError::unsupported_at(
                            "$strobe/$monitor in a subroutine without an instance handle",
                            &cx.fn_sym,
                        )
                    })?;
                    let scope = sv_sim_sim::netlist::enclosing_instance_body(&cx.fn_sym)
                        .or_else(|| cx.fn_sym.parent())
                        .ok_or_else(|| {
                            LoweringError::unsupported_at(
                                "subroutine has no enclosing module",
                                &cx.fn_sym,
                            )
                        })?;
                    let slots = crate::module::signal_slots_of(&scope)?;
                    let which = if family == F::Strobe {
                        crate::process_lower::PostponedDisplay::Strobe
                    } else {
                        crate::process_lower::PostponedDisplay::Monitor
                    };
                    return crate::process_lower::lower_postponed_display_call(
                        cx, handle, &slots, e, which,
                    );
                }
                crate::systask::lower_display_family_call(cx, e, family)?;
                return Ok(());
            }
            // B-runtime Task 4 (RT-070/RT-162): `$dumpfile`/`$dumpflush` --
            // intercepted here for the exact same reason and at the exact
            // same point as the `$display`-family arm immediately above
            // (before `expr.rs`'s generic `Call` arm, which knows nothing
            // about either). See `systask.rs::DumpControlCall`'s own doc
            // comment for why only these two of the seven `$dump*` tasks get
            // a recognizer arm this wave.
            if e.kind() == ExpressionKind::Call
                && e.is_system_call() == Some(true)
                && let Some(sub) = e.system_subroutine()
                && let Some(which) = crate::systask::classify_dump_control_call(sub.known_name_id())
            {
                crate::systask::lower_dump_control_call(cx, e, which)?;
                return Ok(());
            }
            // B-runtime Task 7 (RT-050/051/052/053/065/069): `$fclose`/
            // `$fflush` -- intercepted here for the exact same reason and at
            // the exact same point as the `$dumpfile`/`$dumpflush` arm
            // immediately above (`$fopen` itself is dispatched from
            // `expr.rs`'s `Call` arm instead, since it is a system FUNCTION
            // whose return value feeds ordinary SV expression evaluation --
            // see `crate::expr::lower_fopen_call`'s own doc comment).
            if e.kind() == ExpressionKind::Call
                && e.is_system_call() == Some(true)
                && let Some(sub) = e.system_subroutine()
                && let Some(which) = crate::systask::classify_file_io_void_call(sub.known_name_id())
            {
                crate::systask::lower_file_io_void_call(cx, e, which)?;
                return Ok(());
            }
            // B-runtime Task 8 (RT-022/RT-049/RT-054/RT-055/RT-056/RT-057):
            // `$fwrite`/`$fdisplay`/`$fmonitor`/`$fstrobe` -- intercepted
            // here for the exact same reason and at the exact same point as
            // the `$display`-family arm above (`systask.rs::FDisplayFamily`'s
            // own doc comment).
            if e.kind() == ExpressionKind::Call
                && e.is_system_call() == Some(true)
                && let Some(sub) = e.system_subroutine()
                && let Some(family) = crate::systask::classify_fdisplay_family(sub.known_name_id())
            {
                crate::systask::lower_fdisplay_family_call(cx, e, family)?;
                return Ok(());
            }
            // SD-B / T25: `$sdf_annotate` -- intercepted here for the exact
            // same reason and at the exact same point as every arm above
            // (before `expr.rs`'s generic `Call` arm, which knows nothing
            // about it). See `systask.rs::lower_sdf_annotate_call`.
            if e.kind() == ExpressionKind::Call
                && e.is_system_call() == Some(true)
                && let Some(sub) = e.system_subroutine()
                && sub.known_name_id() == sv_lang::KnownSystemName::SdfAnnotate
            {
                crate::systask::lower_sdf_annotate_call(cx, e)?;
                return Ok(());
            }
            // `$cast(dest, src);` as a task (LRM 6.24.2): a failed cast is a
            // run-time error, not a result of 0 (`sysfunc::lower_cast_stmt`).
            if e.kind() == ExpressionKind::Call
                && e.is_system_call() == Some(true)
                && let Some(sub) = e.system_subroutine()
                && sub.known_name_id() == sv_lang::KnownSystemName::Cast
            {
                return crate::sysfunc::lower_cast_stmt(cx, e);
            }
            crate::huge::discard(lower_expr(cx, e)?);
            Ok(())
        }
        // Task 9 (CG-090, CG-007): `if`/`else` -- CG-090's `if` branch-
        // condition site. `is_definitely_true` (not a per-bit X-merge, per
        // CG-091/CG-007) reduces the condition to a single `i1`, which
        // drives a genuine `br`+then/else/merge-block control-flow shape
        // (never a `select`-style value blend -- an `if`'s two branches are
        // full statement lists with their own side effects, not values to
        // merge). Task 26 (CG-121): an `else if` chain needs no new code --
        // `else_branch()` recurses back into this very same arm whenever the
        // else clause is itself another `Conditional` statement, exactly
        // like any other nested statement.
        StatementKind::Conditional => {
            crate::stmt_shared::lower_if(cx, s, &mut |cx, s| lower_stmt(cx, s))
        }
        // R-run Task 4 (CG-095/CG-096/CG-121/PR-009): `case`/`casex`/`casez`
        // -- the branch/CFG-construction logic now lives in
        // `stmt_shared::lower_case`, shared with `process_lower.rs`'s
        // segment-statement dispatcher. `func.rs`'s own leaf-lowering (a
        // `case` arm's/`default:`'s own statement) is supplied back via the
        // `recurse` callback, which is exactly this same `lower_stmt`.
        // A constant selector over arms one of which slang demoted to `Invalid` (a
        // statically dead arm): only the matching arm can run (LRM 12.5).
        StatementKind::Case => match sv_sim_sim::process::cfg::constant_case_live_arm(&s) {
            Some(Some(arm)) => lower_stmt(cx, arm),
            Some(None) => Ok(()),
            None => lower_case(cx, s, &mut |cx, s| lower_stmt(cx, s)),
        },
        StatementKind::PatternCase => {
            crate::stmt_shared::lower_pattern_case(cx, s, &mut |cx, s| lower_stmt(cx, s))
        }
        StatementKind::RandCase => {
            crate::stmt_shared::lower_randcase(cx, s, &mut |cx, s| lower_stmt(cx, s))
        }
        // R-run Task 4: `while` -- see `stmt_shared::lower_while_loop`.
        StatementKind::WhileLoop => lower_while_loop(cx, s, &mut |cx, s| lower_stmt(cx, s)),
        // R-run Task 4: `do`/`while` -- see `stmt_shared::lower_do_while_loop`.
        StatementKind::DoWhileLoop => lower_do_while_loop(cx, s, &mut |cx, s| lower_stmt(cx, s)),
        // R-run Task 4: `for` -- see `stmt_shared::lower_for_loop`.
        StatementKind::ForLoop => lower_for_loop(cx, s, &mut |cx, s| lower_stmt(cx, s)),
        // R-run Task 4: `repeat` -- see `stmt_shared::lower_repeat_loop`.
        StatementKind::RepeatLoop => lower_repeat_loop(cx, s, &mut |cx, s| lower_stmt(cx, s)),
        StatementKind::ForeachLoop => lower_foreach_loop(cx, s, &mut |cx, s| lower_stmt(cx, s)),
        StatementKind::ForeverLoop => lower_forever_loop(cx, s, &mut |cx, s| lower_stmt(cx, s)),
        StatementKind::Break => lower_loop_jump(cx, true),
        StatementKind::Continue => lower_loop_jump(cx, false),
        // An immediate assertion in a subroutine body (LRM 1800-2023 §16.3)
        // lowers as in a process; its actions are subroutine statements.
        // A deferred one whose action calls a user task or void function queues the call for
        // the report's maturation (16.4.1): its thunk runs in the instance the subroutine
        // belongs to, whose handle the subroutine holds (`compute_abi_static`).
        StatementKind::ImmediateAssertion => {
            let sys_fns = crate::process_lower::fetch_or_declare_sys_call_fns(cx.ctx, cx.module);
            let slots = match (&cx.mem_accessor, s.is_deferred_assertion() == Some(true)) {
                (Some(_), true) => sv_sim_sim::netlist::enclosing_instance_body(&cx.fn_sym)
                    .or_else(|| cx.fn_sym.parent())
                    .map(|scope| crate::module::signal_slots_of(&scope))
                    .transpose()?,
                _ => None,
            };
            let handle = cx.mem_accessor.as_ref().map(|m| m.handle);
            let env = match (handle, slots.as_ref()) {
                (Some(handle), Some(signals)) => {
                    Some(crate::deferred_call::DeferredEnv { handle, signals })
                }
                _ => None,
            };
            crate::process_lower::lower_immediate_assertion(
                cx,
                &sys_fns,
                &s,
                env.as_ref(),
                &mut |cx, a| lower_stmt(cx, *a),
            )
        }
        // Task 27 (CG-172): `wait fork`/`disable fork`/`wait_order(...)` are
        // recognized as their own distinct `StatementKind` arms (AST-coverage
        // completeness) but hard-error at COMPILE time with a construct-
        // specific, diagnosable message -- fork/join semantics (the
        // sub-process set these three statements all operate over) are
        // unresolved in this crate (ARCHITECTURE.md §6.4 "Open sub-problems
        // (flagged): fork/join ... is unresolved"). CG-172's acceptance is
        // explicit that these must NEVER fall through the generic `other =>`
        // arm below, indistinguishable from any other unhandled kind -- each
        // gets its own arm and its own named message so a caller (or a test)
        // can tell exactly which of the three it hit, not just "some
        // unsupported statement".
        StatementKind::WaitFork => Err(LoweringError::unsupported_at(
            "wait fork (fork/join unresolved, see ARCHITECTURE.md §6.4 open \
             sub-problems)",
            &cx.fn_sym,
        )),
        StatementKind::DisableFork => Err(LoweringError::unsupported_at(
            "disable fork (fork/join unresolved, see ARCHITECTURE.md §6.4 \
             open sub-problems)",
            &cx.fn_sym,
        )),
        StatementKind::WaitOrder => Err(LoweringError::unsupported_at(
            "wait_order (fork/join unresolved, see ARCHITECTURE.md §6.4 open \
             sub-problems)",
            &cx.fn_sym,
        )),
        // R-run Task 10 (CG-154, explicitly out of this task's own scope): a
        // `#delay`/`@event` timing-control statement (`Timed`) or a
        // `wait(expr)` statement (`Wait`) inside a subroutine's own body is a
        // genuine SUSPEND POINT -- the LRM forbids a `function` from ever
        // containing one at all (1800-2023 §13.4.1), so this arm is only ever
        // reachable from a `task`'s own body. Task 10's whole procedural-
        // call ABI (this file's `lower_task_call`, `expr.rs`'s generalized
        // `Call` arm) only handles an AUTOMATIC, NON-SUSPENDING call -- a
        // suspending call site would itself need to become a suspend point in
        // the CALLER's own CFG, machinery that does not exist yet (CG-154,
        // open/unsettled per every research pass that has touched it --
        // `docs/superpowers/plans/2026-09-27-run-wiring.md` Task 10's own
        // scope-restriction note). A named, loud `LoweringError` naming
        // CG-154 explicitly -- never a panic, and never the generic,
        // indistinguishable "statement kind Timed"/"statement kind Wait"
        // fallthrough the `other =>` arm below would otherwise give it.
        StatementKind::EventTrigger => {
            let target = s.expressions().into_iter().next().ok_or_else(|| {
                LoweringError::unsupported_at("an event trigger with no target", &cx.fn_sym)
            })?;
            if s.is_nonblocking_trigger() != Some(true)
                && crate::class_events::is_class_event(target)
            {
                return crate::expr::lower_event_trigger(cx, target);
            }
            Err(LoweringError::unsupported_at(
                "statement kind EventTrigger in a subroutine body",
                &cx.fn_sym,
            ))
        }
        StatementKind::ProceduralAssign | StatementKind::ProceduralDeassign => {
            lower_subroutine_force(cx, &s)
        }
        StatementKind::Timed => Err(LoweringError::unsupported_at(
            "a task body containing a timing-control statement (delay/event \
             control) is a suspend point this crate's automatic, \
             non-suspending task/function-call ABI does not support -- \
             CG-154 (open/unsettled)",
            &cx.fn_sym,
        )),
        StatementKind::Wait => Err(LoweringError::unsupported_at(
            "a task body containing a wait(expr) statement is a suspend \
             point this crate's automatic, non-suspending task/function-call \
             ABI does not support -- CG-154 (open/unsettled)",
            &cx.fn_sym,
        )),
        other => Err(LoweringError::unsupported_at(
            &format!("statement kind {other:?}"),
            &cx.fn_sym,
        )),
    }
}

/// [`mangle::param_binding_hash`] of `scope`, or -- for an `InstanceBody`
/// (whose `parameters()` is empty; only its `Instance` has them) -- of the
/// instance it was elaborated for. Two instances of one module with different
/// parameter values are two bodies with the same `parent.name()`; without this
/// their subroutines (which fold the parameters as constants) collided on one
/// mangled name and the first body's copy served both (LRM 23.10).
fn body_param_hash(scope: &sv_lang::Symbol) -> u64 {
    match scope.instance_body_parent_instance() {
        Some(inst) => mangle::param_binding_hash(&inst),
        None => mangle::param_binding_hash(scope),
    }
}

/// R-run Task 10 (CG-061): the mangled LLVM name a value-producing caller
/// (`expr.rs`'s generalized `Call` arm) and this pipeline's own subroutine
/// pre-pass (`pipeline::build_pipeline`, which renames the `FunctionValue`
/// `lower_function` returns to exactly this name before lowering any process
/// kernel) both derive for `sym` -- computed in exactly ONE place so the two
/// stay in sync by construction, never by convention. Mirrors
/// [`resolve_callee_fn`]'s own pre-Task-10 cross-module-fallback shape
/// exactly: `<def>` is `sym`'s enclosing scope's own `name()`,
/// `<param_hash>` is `mangle::param_binding_hash` of that same scope (`0`
/// for a non-`Instance` scope, matching that function's own documented
/// default), `<local>` is `sym.name()`.
pub(crate) fn mangled_subroutine_name(sym: &sv_lang::Symbol) -> Result<String, LoweringError> {
    let parent = sym.parent().ok_or_else(|| {
        LoweringError::unsupported_at(
            "subroutine has no resolvable enclosing scope to mangle a name against",
            sym,
        )
    })?;
    // Classes plan Task 9 (8.25): `Box#(int)::get` and `Box#(string)::get`
    // (and `Outer1::Inner::dbl` / `Outer2::Inner::dbl`, and `p1::Foo::get` /
    // `p2::Foo::get`) share `parent.name()` and `sym.name()`, and
    // `param_binding_hash` is `0` for a non-`Instance` scope -- so EVERY class
    // scope folds its [`class_specialization_key`] into the `param_hash`
    // field, the one the mangler already documents as "two calls that differ
    // only in `param_hash` always produce two distinct strings" (CG-058). The
    // key carries the class definition's hierarchical uid, so two plain,
    // non-generic, non-nested classes of the same name declared in different
    // packages (LRM 8.2/26.3: a class name is scoped by its declaring
    // package) stay distinct too.
    let param_hash = if parent.kind() == sv_lang::kinds::SymbolKind::ClassType {
        use std::hash::{Hash, Hasher};
        let key = parent
            .as_type()
            .map(sv_sim_sim::netlist::class_specialization_key)
            .ok_or_else(|| {
                LoweringError::unsupported_at(
                    "class scope has no type to key a mangled name on",
                    sym,
                )
            })?;
        let mut hasher = std::collections::hash_map::DefaultHasher::new();
        key.hash(&mut hasher);
        hasher.finish()
    } else if sv_sim_sim::netlist::itf::is_extern_impl(sym) {
        // An exported interface method reaches the signals of the interface
        // and of its own instance by hidden pointer parameters ordered by
        // their hierarchical paths, which differ between two instances of
        // one module: each instance's definition is its own function.
        use std::hash::{Hash, Hasher};
        let mut hasher = std::collections::hash_map::DefaultHasher::new();
        sym.hierarchical_path().hash(&mut hasher);
        hasher.finish()
    } else if parent.kind() == sv_lang::kinds::SymbolKind::GenerateBlock {
        // Every iteration of `for (genvar i ...) begin : g ... end` names its
        // block `g` and has no instance parameters, so `g[0].f` and `g[1].f`
        // would share one mangled name -- and one body that sees only the
        // last iteration's genvar (LRM 27.4: each iteration's genvar is its
        // own constant). The path from the enclosing module body (the part
        // that is the same for two instances of one module) keeps them apart.
        use std::hash::{Hash, Hasher};
        let mut scope = parent;
        while let Some(up) = scope.parent() {
            if !matches!(
                up.kind(),
                sv_lang::kinds::SymbolKind::GenerateBlock
                    | sv_lang::kinds::SymbolKind::GenerateBlockArray
            ) {
                break;
            }
            scope = up;
        }
        let full = parent.hierarchical_path();
        let outer = scope
            .parent()
            .map(|p| p.hierarchical_path())
            .unwrap_or_default();
        let rel = full.strip_prefix(outer.as_str()).unwrap_or(full.as_str());
        let mut hasher = std::collections::hash_map::DefaultHasher::new();
        rel.hash(&mut hasher);
        // The block's localparams may derive from the module's parameters.
        scope
            .parent()
            .map(|p| body_param_hash(&p))
            .hash(&mut hasher);
        hasher.finish()
    } else {
        body_param_hash(&parent)
    };
    Ok(mangle::mangle_kernel(
        parent.name(),
        param_hash,
        EntityTag::Kernel,
        sym.name(),
    ))
}

/// Resolves a callee `Symbol` (an ordinary, already-frontend-verified
/// non-DPI SV function/task) to a `FunctionValue` in `cx.module` -- shared by
/// [`lower_task_call`] (a bare, statement-position call) and, since R-run
/// Task 10, `expr.rs`'s generalized `Call` arm (a value-producing,
/// expression-position call). Three ways, tried in order:
///
/// 1. same-module, by plain SV name (exactly how `lower_function` names the
///    function it just built -- `session.rs::lower_instance_body_in` calls
///    `lower_function` for every sibling `Subroutine` in the SAME `Module`
///    before either one's body is lowered, so a same-module callee lowered
///    THAT way is always already present under that name);
/// 2. same shared module, but under Task 10's own [`mangled_subroutine_name`]
///    (`pipeline::build_pipeline`'s subroutine pre-pass renames every
///    subroutine it lowers to exactly this name, so a caller in that SAME
///    shared module finds it here instead of falling all the way through to
///    an unnecessary `extern` re-declaration);
/// 3. genuinely cross-module: a fresh `extern` declaration under that same
///    mangled-name scheme -- CG-061's "no direct Module merging at lowering
///    time" acceptance, exactly mirroring
///    `cross_module_call_resolves_via_mangled_extern_declaration`
///    (`tests/mangle.rs`)'s own "declare it `extern` under the SAME mangled
///    name in the CALLER's Module, never copy/merge the callee's Module"
///    shape.
///
/// Deviation from the plan's unqualified "Task 21's mangled name" (discovered
/// implementing CG-121's original task): the real pipeline
/// (`session.rs::lower_instance_body_in`) does not itself mangle same-module
/// kernel names -- it calls `module.add_function(sym.name(), ...)` directly,
/// so `mangle_kernel` has no design-wide "the definitive symbol table" role
/// to consult for a genuinely cross-Module lookup. Case 3 below reconstructs
/// the mangled name from what IS available on `callee` today (its enclosing
/// scope, via [`mangled_subroutine_name`]). Full design-wide parameterized-
/// instance cross-module linking (resolving which ELABORATED instance a call
/// crosses into) is Task 21/23's dedup-cache concern, genuinely out of this
/// function's scope.
pub(crate) fn resolve_callee_fn<'ctx, 'd, 'm>(
    cx: &LowerCtx<'ctx, 'd, 'm>,
    callee: sv_lang::Symbol<'d>,
) -> Result<FunctionValue<'ctx>, LoweringError> {
    // Classes plan Task 6 (§1.4/8.10/8.23): `Class::static_method()` (no
    // receiver, `call_this_class()` is `None` at every one of this
    // function's three callers' own call sites) -- tried first, before
    // either of the two ordinary same-module name lookups just below,
    // since a static class method's mangled name could otherwise collide
    // with -- and be shadowed by -- an unrelated plain subroutine case 1
    // happens to find first under the SAME plain SV name. See `classes::
    // resolve_or_lower_static_method`'s own doc comment for why this is
    // lazy (call-site-driven) rather than an upfront pass.
    if let Some(f) = crate::classes::resolve_or_lower_static_method(cx, callee)? {
        return Ok(f);
    }
    if let Some(f) = cx.module.get_function(callee.name()) {
        return Ok(f);
    }
    let mangled = mangled_subroutine_name(&callee)?;
    if let Some(f) = cx.module.get_function(&mangled) {
        return Ok(f);
    }
    // R-run Task 10 review fix (discovered implementing this task, not a
    // pre-Task-10 regression): a void `task`'s `subroutine_return_type()`
    // is `Some(<void Type>)`, never `None` (same correction as
    // `lower_function`'s own `is_void_return`, above) -- the original
    // `.ok_or_else` here could never actually fire for a genuinely void
    // callee; it would instead reach `lower_type` and fail with the
    // generic, undiagnosable "non-integral type void" instead of this
    // function's own documented, named rejection.
    // (A void callee declares as a `void`-returning function, exactly as the
    // pipeline declares it: `subroutine_fn_type` covers it, so a class method
    // calling an interface task through a virtual interface resolves too.)
    let (fn_ty, _) = subroutine_fn_type(cx.ctx, &callee, cx.repr, false)?;
    Ok(cx
        .module
        .add_function(&mangled, fn_ty, Some(Linkage::External)))
}

/// Task 26 (CG-121): a bare task/function call used as a statement (no
/// captured return value) -- `func.rs`'s `ExpressionStatement` arm routes
/// here for any `Call` expression that is NOT a system call (a system call
/// stays on `lower_expr`'s own, separately-scoped `Call` arm).
///
/// Resolves the callee via [`resolve_callee_fn`] (R-run Task 10, extracted
/// from this function's own original inline resolution logic into its own
/// function, shared with `expr.rs`'s generalized `Call` arm -- see that
/// function's own doc comment for the full same-module/mangled/extern
/// three-way resolution shape; this function's own behavior is unchanged by
/// the extraction).
///
/// `pub(crate)` (R-run Task 10): `process_lower.rs::lower_segment_statement`'s
/// own `ExpressionStatement` arm routes a bare task/function call the SAME
/// way (a real procedural-block/process body, unlike a leaf `function`'s own
/// body, reaches THAT dispatcher, not this file's `lower_stmt`) -- see its
/// own call site for why: `function_task.sv`'s `show(sq(7))` is an
/// `initial` block's own statement, so without this it never reached
/// `lower_task_call` at all, only `expr.rs`'s generalized `Call` arm (which
/// rejects a void callee outright -- a call used as an expression VALUE must
/// have one).
pub(crate) fn lower_task_call<'ctx, 'd, 'm>(
    cx: &mut LowerCtx<'ctx, 'd, 'm>,
    call: sv_lang::Expression<'d>,
) -> Result<(), LoweringError> {
    // Classes plan Task 5 (§1.4 step 2): `obj.method(args);` used as a
    // statement -- tried before every other call-site resolution below.
    // Deviation (found running this task's own fixtures): `call_this_
    // class()` is ALSO `Some` for a virtual-interface modport task/
    // function call, not only a real class method call (despite its own
    // doc comment's narrower framing) -- `vif::call_targets` is checked
    // FIRST and excludes that case, so a vif call still falls through to
    // the vif dispatch immediately below, exactly as before this task.
    // A covergroup's predefined methods (19.8).
    if crate::covergroup::lower_call(cx, call)?.is_some() {
        return Ok(());
    }
    // The built-in `process` class (Task 13): `p.kill();`, `p.await();`, ...
    // (a value-returning method called as a statement drops its value).
    if let crate::classes::ProcessCall::Lowered(_) =
        crate::classes::lower_std_process_call(cx, call)?
    {
        return Ok(());
    }
    let not_vif_call = sv_sim_sim::netlist::vif::call_targets(&call).is_none();
    if not_vif_call && let Some(recv) = call.call_this_class() {
        return crate::classes::lower_method_task_call(cx, Some(recv), call);
    }
    // Review fix (r2), Task 6 finding 1: `super.method(...)` (LRM 8.15) and
    // a bare, implicit-`this` sibling-method call ALSO have no `this`-
    // bearing receiver expression for `call_this_class()` to give back
    // (slang resolves both the same way it resolves `Class::method()` --
    // see `classes::resolve_implicit_this_instance_method`'s own doc
    // comment) even though the call DOES have a live receiver, the CURRENT
    // object -- tried here, still before the vif/mangled/extern fallback
    // below, with no receiver expression at all (`None`): `classes::
    // lower_method_task_call` resolves it via `current_this_handle`
    // instead.
    if not_vif_call
        && let Some(callee) = call.call_subroutine()
        && crate::classes::resolve_implicit_this_instance_method(callee)?.is_some()
    {
        return crate::classes::lower_method_task_call(cx, None, call);
    }
    if sv_sim_sim::netlist::itf::is_vif_extern_call(&call) {
        return Err(LoweringError::unsupported_at(
            &sv_sim_sim::netlist::itf::vif_extern_message(&call),
            &cx.fn_sym,
        ));
    }
    // Through a virtual interface: the selected instance's own task.
    if let Some(r) = crate::vif::call_arms(cx, call) {
        let (arms, merge) = r?;
        for (callee, bb) in arms {
            cx.b.position_at_end(bb);
            lower_task_call_of(cx, callee, call)?;
            cx.b.build_unconditional_branch(merge).unwrap();
        }
        cx.b.position_at_end(merge);
        return Ok(());
    }
    // An interface `extern` method (LRM 25.7): each module-side
    // implementation in turn (an `extern forkjoin` task's, 25.7.5, that never
    // suspends: the process CFG handles the rest).
    if let Some(targets) = sv_sim_sim::netlist::itf::call_extern_targets(&call) {
        if targets.impls.is_empty() {
            return Err(LoweringError::unsupported_at(
                "a call to an extern forkjoin task no module implements, outside a process body",
                &cx.fn_sym,
            ));
        }
        for imp in targets.impls {
            lower_task_call_of(cx, imp, call)?;
        }
        return Ok(());
    }
    let callee = call.call_subroutine().ok_or_else(|| {
        LoweringError::unsupported_at("task/function call missing its callee symbol", &cx.fn_sym)
    })?;
    lower_task_call_of(cx, callee, call)
}

/// [`lower_task_call`] of `call` to `callee`.
fn lower_task_call_of<'ctx, 'd, 'm>(
    cx: &mut LowerCtx<'ctx, 'd, 'm>,
    callee: sv_lang::Symbol<'d>,
    call: sv_lang::Expression<'d>,
) -> Result<(), LoweringError> {
    // A DPI import has no SV body: it is a direct C call, never
    // `resolve_callee_fn`'s SV-subroutine path.
    if callee.subroutine_flags().contains(MethodFlags::DPI_IMPORT) {
        crate::dpi::lower_dpi_import_call(cx, &callee, call)?;
        crate::stmt_shared::leave_if_aborted(cx)?;
        return Ok(());
    }
    if array_result(&callee).is_some() {
        lower_array_call_of(cx, callee, call)?;
        return Ok(());
    }
    let callee_fn = resolve_callee_fn(cx, callee)?;
    let (mut llvm_args, copy_backs) = lower_call_args(cx, &callee, call)?;
    // A result wider than an LLVM integer is written to an image; discarded.
    let discarded = match callee.subroutine_return_type() {
        Some(t) if crate::huge::is_image_type(&t) => {
            let img = crate::huge::result_image(cx, t.value_width())?;
            llvm_args.push(img.into());
            Some(img)
        }
        _ => None,
    };
    if llvm_args.len() != callee_fn.count_params() as usize {
        return Err(LoweringError::unsupported_at(
            "task/function call argument count does not match the callee's \
             declared parameter count",
            &cx.fn_sym,
        ));
    }
    cx.b.build_call(callee_fn, &llvm_args, "task_call").unwrap();
    if let Some(img) = discarded {
        crate::huge::release(img);
    }
    if sv_sim_sim::process::cfg::subroutine_can_abort(&callee) {
        crate::stmt_shared::leave_if_aborted(cx)?;
    }
    commit_callee_writes(cx, &callee);
    if crate::dpi::reaches_context_import(&callee) {
        crate::dpi::reload_shadows(cx);
    }
    copy_back_outputs(cx, copy_backs)
}

/// Copies a static subroutine's `output`/`inout`/`ref` formals (their
/// signals) to the caller's temporaries, just before a return.
fn copy_out_formals(cx: &LowerCtx<'_, '_, '_>) {
    for &(signal, temp, size) in &cx.copy_out {
        cx.b.build_memcpy(temp, 8, signal, 8, size).unwrap();
    }
}