vj-codegen 0.1.0

//! Queues, dynamic arrays and associative arrays (LRM 1800-2023 §7.5,
//! §7.8, §7.10).
//!
//! A variable of one of these types holds a 64-bit collection handle
//! (`sv_sim_sim::collections`): stored like a 2-state 64-bit integral (STATE
//! cell, frame slot, argument). Every operation goes through
//! `sv_rt_coll(op, handle, args)` (`sv_sim_runtime::collections_rt`); one
//! that changes the collection returns its new handle, which is stored back
//! into the variable (a value change, so `wait (q.size() > 0)` wakes).
//!
//! Collections are values: `b = a` copies (`Clone`, copy-on-write), and an
//! assignment frees the handle it overwrites (`Release`). An expression that
//! builds a new collection (`{q, x}`, `'{1, 2}`, `q[1:$]`, `new[n]`, a
//! function's result) yields a handle nobody else holds, used as is. A
//! collection can also be a field of an unpacked struct (or an element of a
//! fixed-size array held as bits): copying such a value copies each
//! collection in it ([`owned`]), and overwriting one frees them
//! ([`release_handles`]).
//!
//! A class handle (`sv_sim_sim::objects`, LRM 8.4) is an owning reference
//! too: every holder -- a variable, a struct field or fixed-array element, an
//! object's field, a collection element -- owns one count of the object, a
//! fresh value (`new`, `new obj`, a call result) transfers its count, and a
//! borrowed one is retained ([`owned`]) before the holder it overwrites is
//! released. A collection owns the handles of its direct class elements
//! (`Shape::obj`); a class handle nested in a struct element is
//! retained on insert and never released ([`Coll::leaky`]).
//!
//! An element travels as its stored bits in codegen's 4-state packed form
//! (`(unk << W) | val`), `ceil(2W / 64)` words; a key likewise (a string
//! key as its interned id).

use inkwell::AddressSpace;
use inkwell::IntPredicate;
use inkwell::module::Linkage;
use inkwell::types::StructType;
use inkwell::values::{IntValue, PointerValue};
use sv_lang::kinds::ExpressionKind;
use sv_lang::{Expression, KnownSystemName, Type};
use sv_sim_runtime::collections_rt::{CollOp, SV_RT_COLL_SYMBOL};
use sv_sim_sim::symid::SymbolUid;

use crate::error::LoweringError;
use crate::expr::{LowerCtx, LoweredValue, entry_alloca, lower_expr, store_to};
use crate::ops::OpBuilder;
use crate::types::TypeWidth;
use crate::value::{PackedValue, ValueRepr};

/// A collection type's element and key shape.
#[derive(Clone, Copy)]
pub(crate) struct Coll<'d> {
    pub elem: Type<'d>,
    /// The element's stored width.
    pub width: u32,
    /// Words per element (`ceil(2 * width / 64)`).
    pub words: u32,
    pub assoc: bool,
    pub queue: bool,
    /// A bounded queue's declared upper bound `N` of `[$:N]` (0: unbounded);
    /// it holds at most `N + 1` elements (LRM 1800-2023 §7.10.5).
    pub bound: u32,
    /// 0: unsigned integral key, 1: signed, 2: string.
    pub key_kind: u32,
    pub key_width: u32,
    /// The elements are class handles: a 64-bit unsigned element whose word
    /// 0 is the handle, and the collection owns one object reference per
    /// element (see `sv_sim_sim::collections`).
    pub obj: bool,
    /// The elements are structs (or fixed arrays) holding class handles. The
    /// runtime cannot see inside such an element, so the collection RETAINS
    /// every handle it is given ([`elem_value`]) and never releases them:
    /// the objects live as long as the program (a leak, never a premature
    /// free), and every read -- a `pop` included -- takes its own count.
    pub leaky: bool,
}

impl Coll<'_> {
    pub(crate) fn key_words(&self) -> u32 {
        (2 * self.key_width).div_ceil(64).max(1)
    }
}

/// `ty`'s collection shape, if it is a queue, dynamic or associative
/// array.
pub(crate) fn coll_of<'d>(ty: &Type<'d>) -> Option<Coll<'d>> {
    if !sv_sim_sim::state::storage::is_collection(ty) {
        return None;
    }
    let elem = ty.element_type()?;
    let obj = elem.is_class();
    // The runtime shape tracks only whole-element class handles; a tag-guarded
    // handle inside an element (a tagged union member) would be shared by
    // copies of the collection without a retain: refuse loudly.
    assert!(
        handle_offsets(&elem).iter().all(|s| s.guards.is_empty()),
        "a queue, dynamic or associative array whose elements are tagged unions with a class or collection member"
    );
    let leaky = !obj
        && handle_offsets(&elem)
            .iter()
            .any(|s| matches!(s.kind, HandleKind::Obj));
    let width = if obj { 64 } else { elem.value_width().max(1) };
    let assoc = ty.is_associative_array();
    let (key_kind, key_width) = if assoc {
        match ty.associative_index_type() {
            Some(k) if k.is_string() => (2, 64),
            // A class handle: a 64-bit unsigned key the array owns (kind 3).
            Some(k) if k.is_class() => (3, 64),
            Some(k) => (u32::from(k.is_signed()), k.value_width().max(1)),
            // `[*]`: any integral index, compared as an unsigned number.
            None => (0, 64),
        }
    } else {
        (0, 0)
    };
    Some(Coll {
        elem,
        width,
        words: (2 * width).div_ceil(64).max(1),
        assoc,
        queue: ty.is_queue(),
        bound: if ty.is_queue() {
            ty.queue_max_bound()
        } else {
            0
        },
        key_kind,
        key_width,
        obj,
        leaky,
    })
}

/// `e`'s collection shape, if its type is a collection.
pub(crate) fn coll_of_expr<'d>(e: &Expression<'d>) -> Option<Coll<'d>> {
    coll_of(&e.expr_type()?)
}

/// The operands of one `sv_rt_coll` call (the runtime's `CollArgs`).
#[derive(Default)]
pub(crate) struct Args<'ctx> {
    pub index: Option<IntValue<'ctx>>,
    pub index2: Option<IntValue<'ctx>>,
    pub h2: Option<IntValue<'ctx>>,
    pub val: Option<PointerValue<'ctx>>,
    pub dflt: Option<PointerValue<'ctx>>,
    pub key: Option<PointerValue<'ctx>>,
}

fn args_type<'ctx>(cx: &LowerCtx<'ctx, '_, '_>) -> StructType<'ctx> {
    let i32t = cx.ctx.i32_type();
    let i64t = cx.ctx.i64_type();
    let ptr = cx.ctx.ptr_type(AddressSpace::default());
    cx.ctx.struct_type(
        &[
            i32t.into(),
            i32t.into(),
            i32t.into(),
            i32t.into(),
            i32t.into(),
            i64t.into(),
            i64t.into(),
            i64t.into(),
            ptr.into(),
            ptr.into(),
            ptr.into(),
        ],
        false,
    )
}

/// `sv_rt_coll(op, h, &args)`.
pub(crate) fn call<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    c: &Coll,
    op: CollOp,
    h: IntValue<'ctx>,
    a: Args<'ctx>,
) -> IntValue<'ctx> {
    raw_call(
        cx,
        [
            c.words,
            u32::from(c.assoc),
            c.key_kind,
            c.key_width,
            u32::from(c.obj),
        ],
        op,
        h,
        a,
    )
}

/// [`call`] with the shape given as `[elem_words, assoc, key_kind,
/// key_width, obj]` (an operation that needs no element type, or zeros).
pub(crate) fn raw_call<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    shape: [u32; 5],
    op: CollOp,
    h: IntValue<'ctx>,
    a: Args<'ctx>,
) -> IntValue<'ctx> {
    let i32t = cx.ctx.i32_type();
    let i64t = cx.ctx.i64_type();
    let ptr = cx.ctx.ptr_type(AddressSpace::default());
    let st = args_type(cx);
    let f = cx
        .module
        .get_function(SV_RT_COLL_SYMBOL)
        .unwrap_or_else(|| {
            cx.module.add_function(
                SV_RT_COLL_SYMBOL,
                i64t.fn_type(&[i32t.into(), i64t.into(), ptr.into()], false),
                Some(Linkage::External),
            )
        });
    let buf = entry_alloca(cx, st, "coll_args");
    let fields: [inkwell::values::BasicValueEnum<'ctx>; 11] = [
        i32t.const_int(u64::from(shape[0]), false).into(),
        i32t.const_int(u64::from(shape[1]), false).into(),
        i32t.const_int(u64::from(shape[2]), false).into(),
        i32t.const_int(u64::from(shape[3]), false).into(),
        i32t.const_int(u64::from(shape[4]), false).into(),
        a.index.unwrap_or(i64t.const_zero()).into(),
        a.index2.unwrap_or(i64t.const_zero()).into(),
        a.h2.unwrap_or(i64t.const_zero()).into(),
        a.val.unwrap_or(ptr.const_null()).into(),
        a.dflt.unwrap_or(ptr.const_null()).into(),
        a.key.unwrap_or(ptr.const_null()).into(),
    ];
    for (i, v) in fields.into_iter().enumerate() {
        let p =
            cx.b.build_struct_gep(st, buf, i as u32, "coll_arg")
                .unwrap();
        cx.b.build_store(p, v).unwrap();
    }
    cx.b.build_call(
        f,
        &[
            i32t.const_int(op as u64, false).into(),
            h.into(),
            buf.into(),
        ],
        "coll_call",
    )
    .unwrap()
    .try_as_basic_value()
    .basic()
    .expect("sv_rt_coll returns a value")
    .into_int_value()
}

pub(crate) fn op<'a, 'ctx>(cx: &'a LowerCtx<'ctx, '_, '_>) -> OpBuilder<'a, 'ctx> {
    OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    }
}

/// `pv` in 4-state packed form (`i(2W)`), whatever `cx`'s representation.
pub(crate) fn four_state<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    pv: PackedValue<'ctx>,
) -> IntValue<'ctx> {
    if pv.repr == ValueRepr::FourState {
        return pv.llvm;
    }
    let o = op(cx);
    o.pack(
        o.lane_val(pv),
        o.lane_unk(pv),
        pv.width,
        ValueRepr::FourState,
        pv.signed,
    )
    .llvm
}

/// A 4-state packed `i(2W)` value as a `W`-bit value in `cx`'s
/// representation.
pub(crate) fn from_four_state<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    raw: IntValue<'ctx>,
    width: u32,
    signed: bool,
) -> PackedValue<'ctx> {
    let pv = PackedValue {
        llvm: raw,
        width,
        repr: ValueRepr::FourState,
        signed,
    };
    if cx.repr == ValueRepr::FourState {
        return pv;
    }
    let o = op(cx);
    o.pack(o.lane_val(pv), o.lane_unk(pv), width, cx.repr, signed)
}

/// A `words`-word buffer (in the entry block) holding the 4-state packed
/// `raw` (`i(2W)`).
pub(crate) fn words_buf<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    words: u32,
    raw: IntValue<'ctx>,
    name: &str,
) -> PointerValue<'ctx> {
    let o = op(cx);
    let ty = o.i_n(64 * words);
    let buf = entry_alloca(cx, ty, name);
    let bits = raw.get_type().get_bit_width();
    let v = if bits < 64 * words {
        cx.b.build_int_z_extend(raw, ty, "coll_zext").unwrap()
    } else if bits > 64 * words {
        cx.b.build_int_truncate(raw, ty, "coll_trunc").unwrap()
    } else {
        raw
    };
    cx.b.build_store(buf, v).unwrap();
    buf
}

/// The `2 * width`-bit packed value in `buf` (`words` words).
pub(crate) fn load_words<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    buf: PointerValue<'ctx>,
    words: u32,
    width: u32,
) -> IntValue<'ctx> {
    let o = op(cx);
    let all =
        cx.b.build_load(o.i_n(64 * words), buf, "coll_ld")
            .unwrap()
            .into_int_value();
    if 64 * words == 2 * width {
        all
    } else {
        cx.b.build_int_truncate(all, o.i_n(2 * width), "coll_elem")
            .unwrap()
    }
}

/// An element buffer holding `v` converted to the element type.
pub(crate) fn elem_buf<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    c: &Coll,
    v: LoweredValue<'ctx>,
) -> Result<PointerValue<'ctx>, LoweringError> {
    let pv = crate::real::to_storage(cx, v, c.width, "a >128-bit collection element")?;
    let pv = crate::select::fit_width(&op(cx), pv, c.width);
    Ok(words_buf(cx, c.words, four_state(cx, pv), "coll_val"))
}

/// The value of `e` as an element about to be INSERTED into a collection of
/// shape `c`: a class element is owned by the collection, so the value
/// carries its own object reference (`owned`), which the runtime's `Push`,
/// `Insert`, `Set`, `Store` and `SetDefault` take over.
pub(crate) fn elem_value<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    c: &Coll,
    e: Expression<'d>,
) -> Result<LoweredValue<'ctx>, LoweringError> {
    if c.obj || c.leaky || sv_sim_sim::state::storage::is_collection(&c.elem) {
        // (A collection element is a copy: the new element owns its own
        // handle, LRM 1800-2023 7.6.)
        owned(cx, e)
    } else if c.elem.is_unpacked_array()
        && !sv_sim_sim::state::storage::is_collection(&c.elem)
        && e.expr_type().is_some_and(|t| t.is_unpacked_array())
    {
        // A fixed-size array element: its packed row.
        Ok(LoweredValue::Packed(crate::arrays::pack_array_value(
            cx, e,
        )?))
    } else {
        lower_expr(cx, e)
    }
}

/// Takes the reference a class element pushed into a NEW collection of shape
/// `c` owns, when `v` is read from somewhere that keeps its own (an element
/// of another collection or array, as `find` and array-to-queue conversion
/// copy them). Nothing for a collection of anything but class handles.
pub(crate) fn retain_elem<'ctx>(cx: &LowerCtx<'ctx, '_, '_>, c: &Coll, v: LoweredValue<'ctx>) {
    if c.obj
        && let LoweredValue::Packed(pv) = v
    {
        crate::classes::retain_handle(cx, op(cx).lane_val(pv));
    }
}

/// A buffer holding the element type's default value.
pub(crate) fn default_buf<'ctx>(cx: &LowerCtx<'ctx, '_, '_>, c: &Coll) -> PointerValue<'ctx> {
    let d = crate::arrays::default_value(cx, &c.elem);
    let pv = PackedValue {
        llvm: d,
        width: c.width,
        repr: cx.repr,
        signed: c.elem.is_signed(),
    };
    words_buf(cx, c.words, four_state(cx, pv), "coll_dflt")
}

/// The element in `buf` as a value of the element type.
pub(crate) fn load_elem<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    c: &Coll,
    buf: PointerValue<'ctx>,
) -> LoweredValue<'ctx> {
    let raw = load_words(cx, buf, c.words, c.width);
    let pv = from_four_state(cx, raw, c.width, c.elem.is_signed());
    if c.elem.is_floating() {
        LoweredValue::Real(crate::real::bits_to_real(cx, pv))
    } else {
        LoweredValue::Packed(pv)
    }
}

/// A key buffer holding the value of `key` converted to the key type.
pub(crate) fn key_buf<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    c: &Coll,
    key: Expression<'d>,
) -> Result<PointerValue<'ctx>, LoweringError> {
    Ok(key_buf_checked(cx, c, key)?.0)
}

/// [`key_buf`] plus an `i1` that is set when the key has an x or z bit (an
/// invalid index, LRM 1800-2023 7.8.6).
pub(crate) fn key_buf_checked<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    c: &Coll,
    key: Expression<'d>,
) -> Result<(PointerValue<'ctx>, IntValue<'ctx>), LoweringError> {
    let v = lower_expr(cx, key)?;
    let pv = crate::real::to_storage(cx, v, c.key_width, "an associative array key")?;
    let pv = crate::select::fit_width(&op(cx), pv, c.key_width);
    let unk = op(cx).lane_unk(pv);
    let invalid =
        cx.b.build_int_compare(
            IntPredicate::NE,
            unk,
            unk.get_type().const_zero(),
            "key_invalid",
        )
        .unwrap();
    Ok((
        words_buf(cx, c.key_words(), four_state(cx, pv), "coll_key"),
        invalid,
    ))
}

/// The key in `buf` as a value of the key type.
pub(crate) fn load_key<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    c: &Coll,
    buf: PointerValue<'ctx>,
) -> PackedValue<'ctx> {
    let raw = load_words(cx, buf, c.key_words(), c.key_width);
    from_four_state(cx, raw, c.key_width, c.key_kind == 1)
}

/// The handle held by the collection-typed expression `e`.
pub(crate) fn handle_of<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: Expression<'d>,
) -> Result<IntValue<'ctx>, LoweringError> {
    let pv = lower_expr(cx, e)?.into_packed("a collection handle", &cx.fn_sym)?;
    let o = op(cx);
    let v = o.lane_val(pv);
    Ok(if pv.width == 64 {
        v
    } else {
        cx.b.build_int_z_extend_or_bit_cast(v, cx.ctx.i64_type(), "coll_h")
            .unwrap()
    })
}

/// `h` as a 64-bit 2-state value.
pub(crate) fn handle_value<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    h: IntValue<'ctx>,
) -> PackedValue<'ctx> {
    let o = op(cx);
    o.pack(h, cx.ctx.i64_type().const_zero(), 64, cx.repr, false)
}

/// Stores handle `h` into the collection-typed lvalue `target`.
pub(crate) fn set_handle<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    target: Expression<'d>,
    h: IntValue<'ctx>,
) -> Result<(), LoweringError> {
    store_to(cx, target, LoweredValue::Packed(handle_value(cx, h)))?;
    Ok(())
}

/// `h`, a write to queue `c`, with the elements beyond a bounded queue's
/// bound discarded and a warning issued (LRM 1800-2023 §7.10.5).
pub(crate) fn clamp_bound<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    c: &Coll,
    h: IntValue<'ctx>,
) -> IntValue<'ctx> {
    if c.bound == 0 {
        return h;
    }
    let keep = cx.ctx.i64_type().const_int(u64::from(c.bound) + 1, false);
    call(
        cx,
        c,
        CollOp::Truncate,
        h,
        Args {
            index: Some(keep),
            ..Args::default()
        },
    )
}

/// A void result (a method called as a statement).
pub(crate) fn void<'ctx>(cx: &LowerCtx<'ctx, '_, '_>) -> LoweredValue<'ctx> {
    let z = cx.ctx.bool_type().const_zero();
    LoweredValue::Packed(op(cx).pack(z, z, 1, cx.repr, false))
}

/// An `int` result.
pub(crate) fn int<'ctx>(cx: &LowerCtx<'ctx, '_, '_>, v: IntValue<'ctx>) -> LoweredValue<'ctx> {
    let o = op(cx);
    let i32t = cx.ctx.i32_type();
    let v =
        cx.b.build_int_truncate_or_bit_cast(v, i32t, "coll_int")
            .unwrap();
    LoweredValue::Packed(o.pack(v, i32t.const_zero(), 32, cx.repr, true))
}

/// An index expression as `i64` (an unknown index is -1, out of range),
/// with `$` meaning the last index of the collection `h`.
fn index_of<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    c: &Coll,
    h: IntValue<'ctx>,
    e: Expression<'d>,
) -> Result<IntValue<'ctx>, LoweringError> {
    index_of_known(cx, c, h, e).map(|(idx, _)| idx)
}

/// [`index_of`] plus the i1 "the index has no x/z bit" flag (an unknown
/// index reads as -1 in the value).
fn index_of_known<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    c: &Coll,
    h: IntValue<'ctx>,
    e: Expression<'d>,
) -> Result<(IntValue<'ctx>, IntValue<'ctx>), LoweringError> {
    let i64t = cx.ctx.i64_type();
    let size = call(cx, c, CollOp::Size, h, Args::default());
    let last =
        cx.b.build_int_sub(size, i64t.const_int(1, false), "coll_last")
            .unwrap();
    let saved = cx.unbounded.replace(Some(last));
    let v = lower_expr(cx, e);
    cx.unbounded.set(saved);
    let pv = v?.into_packed("a collection index", &cx.fn_sym)?;
    let o = op(cx);
    let val = o.lane_val(pv);
    let val = if pv.width >= 64 {
        cx.b.build_int_truncate_or_bit_cast(val, i64t, "coll_idx")
            .unwrap()
    } else if pv.signed {
        cx.b.build_int_s_extend(val, i64t, "coll_idx").unwrap()
    } else {
        cx.b.build_int_z_extend(val, i64t, "coll_idx").unwrap()
    };
    let unk = o.lane_unk(pv);
    let known =
        cx.b.build_int_compare(
            IntPredicate::EQ,
            unk,
            unk.get_type().const_zero(),
            "coll_known",
        )
        .unwrap();
    let idx =
        cx.b.build_select(known, val, i64t.const_all_ones(), "coll_index")
            .unwrap()
            .into_int_value();
    Ok((idx, known))
}

/// `$` inside a queue selector: the queue's last index.
pub(crate) fn lower_unbounded<'ctx>(cx: &LowerCtx<'ctx, '_, '_>) -> Option<LoweredValue<'ctx>> {
    cx.unbounded.get().map(|v| int(cx, v))
}

/// `c[i]` / `a[key]` read (`None` when `e` does not select from a
/// collection). A missing element reads the element type's default.
pub(crate) fn read_element<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: Expression<'d>,
) -> Option<Result<LoweredValue<'ctx>, LoweringError>> {
    read_element_with(cx, e, false)
}

/// [`read_element`] for a read the program wrote (an rvalue `a[k]`): reading
/// an associative array through an invalid (x/z) index or a nonexistent key
/// with no user-specified default also issues a warning (LRM 1800-2023
/// 7.8.6). The internal reads that merely fetch an element to modify it
/// (`m[k].f = v` allocates it, 7.8.7) use [`read_element`].
pub(crate) fn read_element_warning<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: Expression<'d>,
) -> Option<Result<LoweredValue<'ctx>, LoweringError>> {
    read_element_with(cx, e, true)
}

fn read_element_with<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: Expression<'d>,
    warn: bool,
) -> Option<Result<LoweredValue<'ctx>, LoweringError>> {
    let base = e.select_value()?;
    let c = coll_of_expr(&base)?;
    Some((|| {
        let sel = e.selector().ok_or_else(|| {
            LoweringError::unsupported_at("a collection select with no index", &cx.fn_sym)
        })?;
        let h = handle_of(cx, base)?;
        let val = entry_alloca(cx, op(cx).i_n(64 * c.words), "coll_out");
        let dflt = default_buf(cx, &c);
        if c.assoc {
            let key = key_buf(cx, &c, sel)?;
            let found = call(
                cx,
                &c,
                CollOp::Lookup,
                h,
                Args {
                    val: Some(val),
                    dflt: Some(dflt),
                    key: Some(key),
                    ..Args::default()
                },
            );
            // A nested collection element (`m[k].push_back(v)`, `z[i][j] = v`)
            // is also read to reach what is stored through it, which
            // allocates it (7.8.7): only a value read warns.
            if warn
                && !(sv_sim_sim::state::storage::is_collection(&c.elem)
                    || c.elem.is_unpacked_array())
            {
                let missing =
                    cx.b.build_int_compare(
                        IntPredicate::EQ,
                        found,
                        found.get_type().const_zero(),
                        "assoc_missing",
                    )
                    .unwrap();
                crate::stmt_shared::warning_if(
                    cx,
                    missing,
                    e.source_range().start,
                    "reading a nonexistent entry of an associative array or one with an invalid (x or z) index; the array type's default value is returned",
                )?;
            }
        } else {
            let i = index_of(cx, &c, h, sel)?;
            call(
                cx,
                &c,
                CollOp::Get,
                h,
                Args {
                    index: Some(i),
                    val: Some(val),
                    dflt: Some(dflt),
                    ..Args::default()
                },
            );
        }
        Ok(load_elem(cx, &c, val))
    })())
}

/// Element `pos` (`i64`) of the queue or dynamic array `arr` (handle
/// `h`), or its element type's default when out of range.
pub(crate) fn read_at<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    arr: Expression<'d>,
    h: IntValue<'ctx>,
    pos: IntValue<'ctx>,
) -> Result<LoweredValue<'ctx>, LoweringError> {
    let c = coll_of_expr(&arr)
        .ok_or_else(|| LoweringError::unsupported_at("a non-collection", &cx.fn_sym))?;
    Ok(read_at_coll(cx, &c, h, pos))
}

/// [`read_at`] for a collection known only by its shape (the elements of a
/// nested collection, `foreach (q[i, j])`).
pub(crate) fn read_at_coll<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    c: &Coll,
    h: IntValue<'ctx>,
    pos: IntValue<'ctx>,
) -> LoweredValue<'ctx> {
    let val = entry_alloca(cx, op(cx).i_n(64 * c.words), "coll_at");
    let dflt = default_buf(cx, c);
    call(
        cx,
        c,
        CollOp::Get,
        h,
        Args {
            index: Some(pos),
            val: Some(val),
            dflt: Some(dflt),
            ..Args::default()
        },
    );
    load_elem(cx, c, val)
}

/// The element at position `pos` (`i64`, in range) of the queue, dynamic or
/// associative array `h`, counting from its first element: an associative
/// array's positions run in ascending key order (LRM 1800-2023 7.9.1; the
/// order an unpacked array concatenation takes its elements in, 10.10).
pub(crate) fn read_pos<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    c: &Coll,
    h: IntValue<'ctx>,
    pos: IntValue<'ctx>,
) -> LoweredValue<'ctx> {
    if !c.assoc {
        return read_at_coll(cx, c, h, pos);
    }
    let val = entry_alloca(cx, op(cx).i_n(64 * c.words), "coll_at");
    let key = entry_alloca(cx, op(cx).i_n(64 * c.key_words()), "coll_at_key");
    call(
        cx,
        c,
        CollOp::EntryAt,
        h,
        Args {
            index: Some(pos),
            val: Some(val),
            key: Some(key),
            ..Args::default()
        },
    );
    load_elem(cx, c, val)
}

/// The size of the collection `h` of shape `c`.
pub(crate) fn size_of_handle<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    c: &Coll,
    h: IntValue<'ctx>,
) -> IntValue<'ctx> {
    call(cx, c, CollOp::Size, h, Args::default())
}

/// The value of `foreach` loop variable `var` (a process local) as an `i64`.
fn loop_index_i64<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    var: &sv_lang::Symbol<'d>,
) -> Result<IntValue<'ctx>, LoweringError> {
    let o = op(cx);
    let &(ptr, width, signed) = cx
        .locals
        .get(&var.uid())
        .ok_or_else(|| LoweringError::unsupported_at("foreach index has no frame slot", var))?;
    let v =
        cx.b.build_load(o.packed_type(width, cx.repr), ptr, "nest_idx")
            .unwrap()
            .into_int_value();
    let v = o.lane_val(PackedValue {
        llvm: v,
        width,
        repr: cx.repr,
        signed,
    });
    let i64t = cx.ctx.i64_type();
    Ok(if signed {
        cx.b.build_int_s_extend_or_bit_cast(v, i64t, "nest_idx64")
    } else {
        cx.b.build_int_z_extend_or_bit_cast(v, i64t, "nest_idx64")
    }
    .unwrap())
}

/// The element of `c` (handle `h`) at position `pos`, or for an associative
/// array (when `key` is given) the one stored under that key.
pub(crate) fn elem_at_coll<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    c: &Coll,
    h: IntValue<'ctx>,
    pos: IntValue<'ctx>,
    key: Option<PackedValue<'ctx>>,
) -> LoweredValue<'ctx> {
    match key {
        // An associative array's element is found by its key, not its position.
        Some(k) if c.assoc => {
            let val = entry_alloca(cx, op(cx).i_n(64 * c.words), "coll_at");
            let dflt = default_buf(cx, c);
            let kv = crate::select::fit_width(&op(cx), k, c.key_width);
            let kb = words_buf(cx, c.key_words(), four_state(cx, kv), "coll_key");
            call(
                cx,
                c,
                CollOp::Lookup,
                h,
                Args {
                    val: Some(val),
                    dflt: Some(dflt),
                    key: Some(kb),
                    ..Args::default()
                },
            );
            load_elem(cx, c, val)
        }
        _ => read_at_coll(cx, c, h, pos),
    }
}

/// The nested-collection element `c[pos]` as a handle plus its own shape,
/// when the elements of `c` are queues, dynamic or associative arrays.
/// `via` are fixed-size dimensions between `c` and the nested collection
/// (`int x[][2][$]`: each element of `x` is an array of two queues): the
/// loop variable and `(left, right)` bounds of each, outermost first.
pub(crate) fn child_coll_at<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    c: &Coll<'d>,
    h: IntValue<'ctx>,
    pos: IntValue<'ctx>,
    key: Option<PackedValue<'ctx>>,
    via: &[(sv_lang::Symbol<'d>, i32, i32)],
) -> Result<(Coll<'d>, IntValue<'ctx>), LoweringError> {
    let mut inner = c.elem;
    for _ in via {
        inner = inner.element_type().ok_or_else(|| {
            LoweringError::unsupported_at(
                "foreach fixed dimension of a non-array element",
                &cx.fn_sym,
            )
        })?;
    }
    let child = coll_of(&inner).ok_or_else(|| {
        LoweringError::unsupported_at(
            "foreach over a dimension that is not a queue, dynamic or associative array element \
             of the previous one",
            &cx.fn_sym,
        )
    })?;
    let elem = elem_at_coll(cx, c, h, pos, key);
    let pv = elem.into_packed("a nested collection handle", &cx.fn_sym)?;
    let mut v = op(cx).lane_val(pv);
    let i64t = cx.ctx.i64_type();
    if !via.is_empty() {
        // The element holds one 64-bit handle per combination of the fixed
        // indices, row-major from the lowest bound (as `handle_offsets`).
        let mut acc = i64t.const_zero();
        for (var, l, r) in via {
            let count = (i64::from(*l) - i64::from(*r)).unsigned_abs() + 1;
            let idx = loop_index_i64(cx, var)?;
            let lo = i64::from(*l.min(r));
            let row =
                cx.b.build_int_sub(idx, i64t.const_int(lo as u64, true), "via_row")
                    .unwrap();
            let scaled =
                cx.b.build_int_mul(acc, i64t.const_int(count, false), "via_scaled")
                    .unwrap();
            acc = cx.b.build_int_add(scaled, row, "via_acc").unwrap();
        }
        let bits =
            cx.b.build_int_mul(acc, i64t.const_int(64, false), "via_bits")
                .unwrap();
        let sh =
            cx.b.build_int_z_extend_or_bit_cast(bits, v.get_type(), "via_sh")
                .unwrap();
        v = cx.b.build_right_shift(v, sh, false, "via_shr").unwrap();
        v =
            cx.b.build_int_truncate_or_bit_cast(v, i64t, "via_h")
                .unwrap();
    }
    let ch =
        cx.b.build_int_z_extend_or_bit_cast(v, i64t, "coll_child_h")
            .unwrap();
    Ok((child, ch))
}

/// Where a collection handle sits inside a nested collection's element row.
struct FixedSlot<'ctx, 'd> {
    /// The select of the queue / dynamic / associative array element whose
    /// value is the row of handles (`m[k]` of `m[k][i]`).
    row: Expression<'d>,
    /// The handle's bit offset in the row (an `i64`).
    shift: IntValue<'ctx>,
    /// Whether every fixed index is in range.
    ok: IntValue<'ctx>,
}

/// [`FixedSlot`] of `e` = `m[k][i]`, where `m[k]` is an element of a queue,
/// dynamic or associative array that is itself a fixed-size array of queues,
/// dynamic or associative arrays (`int m[string][2][$]`); `None` when `e` is
/// not such a select. The row holds one 64-bit handle per combination of the
/// fixed indices, row-major from the lowest bound (as [`handle_offsets`]).
fn fixed_slot<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: Expression<'d>,
) -> Option<Result<FixedSlot<'ctx, 'd>, LoweringError>> {
    coll_of_expr(&e)?;
    let mut sels = Vec::new();
    let mut cur = e;
    while cur.kind() == ExpressionKind::ElementSelect {
        let base = cur.select_value()?;
        let t = base.expr_type()?;
        if !t.is_unpacked_array() || sv_sim_sim::state::storage::is_collection(&t) {
            break;
        }
        sels.push(cur);
        cur = base;
    }
    if sels.is_empty() || cur.kind() != ExpressionKind::ElementSelect {
        return None;
    }
    coll_of_expr(&cur.select_value()?)?;
    sels.reverse();
    Some((|| {
        let o = op(cx);
        let i64t = cx.ctx.i64_type();
        let mut ty = cur.expr_type().expect("typed select");
        let mut acc = i64t.const_zero();
        let mut ok = cx.ctx.bool_type().const_all_ones();
        for s in sels {
            let r = ty.fixed_unpacked_array_range();
            let (l, rr) = (i64::from(r.left), i64::from(r.right));
            let count = (l - rr).unsigned_abs() + 1;
            let sel = s.selector().ok_or_else(|| {
                LoweringError::unsupported_at("a select with no index", &cx.fn_sym)
            })?;
            let ipv = lower_expr(cx, sel)?.into_packed("an array index", &cx.fn_sym)?;
            let iv = o.lane_val(ipv);
            let idx = if ipv.signed {
                cx.b.build_int_s_extend_or_bit_cast(iv, i64t, "fic_idx")
            } else {
                cx.b.build_int_z_extend_or_bit_cast(iv, i64t, "fic_idx")
            }
            .unwrap();
            let norm =
                cx.b.build_int_sub(idx, i64t.const_int(l.min(rr) as u64, true), "fic_norm")
                    .unwrap();
            let inr =
                cx.b.build_int_compare(
                    IntPredicate::ULT,
                    norm,
                    i64t.const_int(count, false),
                    "fic_in",
                )
                .unwrap();
            ok = cx.b.build_and(ok, inr, "fic_ok").unwrap();
            let scaled =
                cx.b.build_int_mul(acc, i64t.const_int(count, false), "fic_scaled")
                    .unwrap();
            acc = cx.b.build_int_add(scaled, norm, "fic_acc").unwrap();
            ty = ty.element_type().ok_or_else(|| {
                LoweringError::unsupported_at("a select of a non-array", &cx.fn_sym)
            })?;
        }
        // An out-of-range index would shift out of the row: pin it to 0.
        let acc =
            cx.b.build_select(ok, acc, i64t.const_zero(), "fic_pin")
                .unwrap()
                .into_int_value();
        let shift =
            cx.b.build_int_mul(acc, i64t.const_int(64, false), "fic_bits")
                .unwrap();
        Ok(FixedSlot {
            row: cur,
            shift,
            ok,
        })
    })())
}

/// `m[k][i]` as a value: the handle of one collection of a fixed array of
/// collections held in an element of a queue, dynamic or associative array
/// (`int m[string][2][$]`). A fixed index out of range reads the null handle
/// (LRM 7.4.6). `None` when `e` is not such a select.
pub(crate) fn read_fixed_in_coll<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: Expression<'d>,
) -> Option<Result<LoweredValue<'ctx>, LoweringError>> {
    let slot = fixed_slot(cx, e)?;
    Some((|| {
        let slot = slot?;
        let row = read_element(cx, slot.row).ok_or_else(|| {
            LoweringError::unsupported_at("a nested collection row", &cx.fn_sym)
        })??;
        let pv = row.into_packed("a nested collection row", &cx.fn_sym)?;
        let i64t = cx.ctx.i64_type();
        let v = op(cx).lane_val(pv);
        let sh =
            cx.b.build_int_z_extend_or_bit_cast(slot.shift, v.get_type(), "fic_sh")
                .unwrap();
        let v = cx.b.build_right_shift(v, sh, false, "fic_shr").unwrap();
        let h =
            cx.b.build_int_truncate_or_bit_cast(v, i64t, "fic_h")
                .unwrap();
        let h =
            cx.b.build_select(slot.ok, h, i64t.const_zero(), "fic_sel")
                .unwrap()
                .into_int_value();
        Ok(LoweredValue::Packed(handle_value(cx, h)))
    })())
}

/// `m[k][i] = h` for the handle value `v` (a `push_back` on `m[k][i]` stores
/// the grown queue back): a read-modify-write of the row `m[k]`, which gains
/// the key when it is absent. An out-of-range fixed index leaves the row
/// unchanged. `None` when `lhs` is not such a select.
pub(crate) fn write_fixed_in_coll<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lhs: Expression<'d>,
    v: LoweredValue<'ctx>,
) -> Option<Result<(), LoweringError>> {
    let slot = fixed_slot(cx, lhs)?;
    Some((|| {
        let slot = slot?;
        let o = op(cx);
        let row = read_element(cx, slot.row).ok_or_else(|| {
            LoweringError::unsupported_at("a nested collection row", &cx.fn_sym)
        })??;
        let pv = row.into_packed("a nested collection row", &cx.fn_sym)?;
        let h = v.into_packed("a collection handle", &cx.fn_sym)?;
        let rv = o.lane_val(pv);
        let ty = rv.get_type();
        let sh =
            cx.b.build_int_z_extend_or_bit_cast(slot.shift, ty, "fic_wsh")
                .unwrap();
        let hv =
            cx.b.build_int_z_extend_or_bit_cast(o.lane_val(h), ty, "fic_wh")
                .unwrap();
        // The 64-bit slot being replaced.
        let low_word =
            cx.b.build_int_z_extend_or_bit_cast(cx.ctx.i64_type().const_all_ones(), ty, "fic_m")
                .unwrap();
        let hole = cx.b.build_left_shift(low_word, sh, "fic_slot").unwrap();
        let keep =
            cx.b.build_and(rv, cx.b.build_not(hole, "fic_nh").unwrap(), "fic_keep")
                .unwrap();
        let put = cx.b.build_left_shift(hv, sh, "fic_put").unwrap();
        let new = cx.b.build_or(keep, put, "fic_new").unwrap();
        let new =
            cx.b.build_select(slot.ok, new, rv, "fic_w")
                .unwrap()
                .into_int_value();
        let packed = o.pack(new, ty.const_zero(), pv.width, cx.repr, false);
        // An out-of-range fixed index writes nothing, and must not create an
        // associative key either (LRM 7.4.6, 7.8).
        guarded_by(cx, slot.ok, || {
            write_element(cx, slot.row, LoweredValue::Packed(packed)).unwrap_or_else(|| {
                Err(LoweringError::unsupported_at(
                    "a nested collection row write",
                    &cx.fn_sym,
                ))
            })
        })
    })())
}

/// Run `body` only when the `i1` `ok` holds (a branch around it).
pub(crate) fn guarded_by<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    ok: IntValue<'ctx>,
    body: impl FnOnce() -> Result<(), LoweringError>,
) -> Result<(), LoweringError> {
    let func = cx.b.get_insert_block().unwrap().get_parent().unwrap();
    let then_bb = cx.ctx.append_basic_block(func, "guard_then");
    let done_bb = cx.ctx.append_basic_block(func, "guard_done");
    cx.b.build_conditional_branch(ok, then_bb, done_bb).unwrap();
    cx.b.position_at_end(then_bb);
    let r = body();
    cx.b.build_unconditional_branch(done_bb).unwrap();
    cx.b.position_at_end(done_bb);
    r
}

/// Whether every constant-range index of the select chain `lhs` that
/// bottoms out at the collection element `elem` (`m[k][i].f[j]`) is within
/// its declared range, as an `i1`: a write through an out-of-range one is
/// ignored (LRM 7.4.6, 11.5.1) and must not create an associative key.
pub(crate) fn chain_in_range<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lhs: Expression<'d>,
    elem: Expression<'d>,
) -> Result<IntValue<'ctx>, LoweringError> {
    let o = op(cx);
    let i64t = cx.ctx.i64_type();
    let mut ok = cx.ctx.bool_type().const_all_ones();
    let mut cur = lhs;
    while cur.source_range() != elem.source_range() || cur.kind() != elem.kind() {
        let kind = cur.kind();
        if kind == ExpressionKind::MemberAccess {
            cur = cur.operand().ok_or_else(|| {
                LoweringError::unsupported_at("a member access with no base", &cx.fn_sym)
            })?;
            continue;
        }
        let base = cur
            .select_value()
            .ok_or_else(|| LoweringError::unsupported_at("a select with no base", &cx.fn_sym))?;
        if kind == ExpressionKind::ElementSelect
            && let Some(ty) = base.expr_type()
        {
            let r = if ty.is_unpacked_array() && !ty.is_dynamically_sized_array() {
                Some(ty.fixed_unpacked_array_range())
            } else if ty.is_packed_array() {
                Some(ty.packed_array_range())
            } else if ty.is_integral() && !ty.is_struct() && !ty.is_union() {
                Some(ty.bit_vector_range())
            } else {
                None
            };
            if let Some(r) = r {
                let sel = cur.selector().ok_or_else(|| {
                    LoweringError::unsupported_at("a select with no index", &cx.fn_sym)
                })?;
                let ipv = lower_expr(cx, sel)?.into_packed("an array index", &cx.fn_sym)?;
                let iv = o.lane_val(ipv);
                let idx = if ipv.signed {
                    cx.b.build_int_s_extend_or_bit_cast(iv, i64t, "pir_idx")
                } else {
                    cx.b.build_int_z_extend_or_bit_cast(iv, i64t, "pir_idx")
                }
                .unwrap();
                let lower = i64t.const_int(i64::from(r.lower()) as u64, true);
                let norm = cx.b.build_int_sub(idx, lower, "pir_n").unwrap();
                let inr =
                    cx.b.build_int_compare(
                        IntPredicate::ULT,
                        norm,
                        i64t.const_int(u64::from(r.width()), false),
                        "pir_in",
                    )
                    .unwrap();
                ok = cx.b.build_and(ok, inr, "pir_ok").unwrap();
            }
        }
        cur = base;
    }
    Ok(ok)
}

/// `c[i] = v` / `a[key] = v` (`None` when `lhs` does not select from a
/// collection): an out-of-range queue/dynamic-array write is ignored
/// (writing `q[$+1]` appends); an associative array gains the key.
pub(crate) fn write_element<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lhs: Expression<'d>,
    v: LoweredValue<'ctx>,
) -> Option<Result<(), LoweringError>> {
    if lhs.kind() != ExpressionKind::ElementSelect {
        return None;
    }
    let base = lhs.select_value()?;
    let c = coll_of_expr(&base)?;
    Some((|| {
        let sel = lhs.selector().ok_or_else(|| {
            LoweringError::unsupported_at("a collection select with no index", &cx.fn_sym)
        })?;
        let h = handle_of(cx, base)?;
        let val = elem_buf(cx, &c, v)?;
        let new = if c.assoc {
            let (key, invalid) = key_buf_checked(cx, &c, sel)?;
            // LRM 7.8.6: a write through an invalid index is ignored (the
            // runtime stores nothing) and a warning is issued.
            crate::stmt_shared::warning_if(
                cx,
                invalid,
                lhs.source_range().start,
                "writing an associative array through an invalid (x or z) index; the write is ignored",
            )?;
            call(
                cx,
                &c,
                CollOp::Store,
                h,
                Args {
                    val: Some(val),
                    key: Some(key),
                    ..Args::default()
                },
            )
        } else {
            let i = index_of(cx, &c, h, sel)?;
            let queue = cx.ctx.i64_type().const_int(u64::from(c.queue), false);
            call(
                cx,
                &c,
                CollOp::Set,
                h,
                Args {
                    index: Some(i),
                    index2: Some(queue),
                    val: Some(val),
                    ..Args::default()
                },
            )
        };
        set_handle(cx, base, new)
    })())
}

/// A `ref` formal bound to a queue / dynamic-array element (LRM 1800-2023
/// 13.5.2): where its runtime reference id lives, and the element's shape.
#[derive(Clone, Copy)]
pub struct ElemRefSlot<'ctx> {
    /// The frame temporary holding the reference id (0: no call open).
    pub id: PointerValue<'ctx>,
    pub id_width: u32,
    /// The formal's width / signedness (the element's).
    pub width: u32,
    pub signed: bool,
    /// Where the formal sits inside the element when the actual is a member
    /// or select of it (`f(q[i].m)`): the slots holding its bit offset and
    /// the element's width (0: the formal is the whole element). `None`: the
    /// reference is never part-bound (a process-level task's).
    pub part: Option<PartSlots<'ctx>>,
}

/// The offset / element-width slots of a part-bound `ref` formal (see
/// [`ElemRefSlot::part`]); both are 64-bit frame temporaries like the id.
#[derive(Clone, Copy)]
pub struct PartSlots<'ctx> {
    pub lo: PointerValue<'ctx>,
    pub elem_width: PointerValue<'ctx>,
}

/// A `ref` argument bound to element `lhs = c[i]` of a queue, dynamic array
/// or associative array (`c[key]`): opens a runtime reference to the element and returns
/// its id (an `i64`, 0 when `i` is outside `c`). The runtime keeps the
/// reference naming the same element across other elements' insert / delete,
/// and outdates it when the element is deleted or popped, the collection is
/// cleared, resized or assigned (`sv_sim_sim::collections::ref_open`).
pub(crate) fn open_ref<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lhs: Expression<'d>,
) -> Result<IntValue<'ctx>, LoweringError> {
    let base = lhs.select_value();
    let c = base.and_then(|b| coll_of_expr(&b));
    let (Some(base), Some(c), Some(sel)) = (base, c, lhs.selector()) else {
        return Err(LoweringError::unsupported_at(
            "a `ref` to something other than a queue or dynamic-array element (internal \
             invariant)",
            &cx.fn_sym,
        ));
    };
    let h = handle_of(cx, base)?;
    // A frozen constant would move to a new entry on its first change.
    let owned = call(cx, &c, CollOp::RefOwn, h, Args::default());
    set_handle(cx, base, owned)?;
    if c.assoc {
        let (key, invalid) = key_buf_checked(cx, &c, sel)?;
        let invalid =
            cx.b.build_int_z_extend(invalid, cx.ctx.i64_type(), "ref_key_invalid")
                .unwrap();
        return Ok(call(
            cx,
            &c,
            CollOp::RefOpen,
            owned,
            Args {
                index2: Some(invalid),
                key: Some(key),
                ..Args::default()
            },
        ));
    }
    let i = index_of(cx, &c, owned, sel)?;
    Ok(call(
        cx,
        &c,
        CollOp::RefOpen,
        owned,
        Args {
            index: Some(i),
            ..Args::default()
        },
    ))
}

/// A `ref` argument bound to a member or select of a queue / dynamic-array
/// element (`f(q[i].m)`, `f(d[i][3:0])`, LRM 1800-2023 13.5.2): the element
/// reference of [`open_ref`] plus where `lhs` sits inside the element, as
/// `(id, bit offset, element width)`, all `i64`. The callee reads and writes
/// that part through the reference ([`CollOp::RefGetPart`] / `RefPutPart`),
/// so the element is not copied in or out. An element reference that the
/// part select puts out of range is 0 (the holder keeps its own copy).
pub(crate) fn open_ref_part<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lhs: Expression<'d>,
    elem: Expression<'d>,
) -> Result<(IntValue<'ctx>, IntValue<'ctx>, IntValue<'ctx>), LoweringError> {
    let c = elem
        .select_value()
        .and_then(|b| coll_of_expr(&b))
        .ok_or_else(|| {
            LoweringError::unsupported_at(
                "a `ref` to a part of something other than a queue or dynamic-array element \
                 (internal invariant)",
                &cx.fn_sym,
            )
        })?;
    if c.assoc {
        return Err(LoweringError::unsupported_at(
            "a `ref` to a member or select of an associative-array element (pass the whole \
             element, or copy the member through a local)",
            &cx.fn_sym,
        ));
    }
    if !handle_offsets(&c.elem).is_empty() {
        return Err(LoweringError::unsupported_at(
            "a `ref` to a member of a queue or dynamic-array element that holds a handle",
            &cx.fn_sym,
        ));
    }
    // The part's offset comes from the ordinary lvalue path, run against a
    // scratch copy of the element (which it never stores into).
    let scratch = entry_alloca(cx, op(cx).packed_type(c.width, cx.repr), "ref_part_scratch");
    let saved = cx.coll_temp.replace(Some(scratch));
    let lv = crate::select::resolve_lvalue(cx, lhs, crate::select::RootMode::Shadow);
    cx.coll_temp.set(saved);
    let lv = lv?;
    if lv.edge.is_some() || lv.pad.is_some() {
        return Err(LoweringError::unsupported_at(
            "a `ref` to a select that straddles the edge of a queue or dynamic-array element",
            &cx.fn_sym,
        ));
    }
    let i64t = cx.ctx.i64_type();
    let id = open_ref(cx, elem)?;
    let id =
        cx.b.build_select(lv.bad, i64t.const_zero(), id, "ref_part_id")
            .unwrap()
            .into_int_value();
    // `lo` is as wide as the element (it may be narrower or wider than 64).
    let lo = if lv.lo.get_type().get_bit_width() > 64 {
        cx.b.build_int_truncate(lv.lo, i64t, "ref_part_lo")
    } else {
        cx.b.build_int_z_extend_or_bit_cast(lv.lo, i64t, "ref_part_lo")
    }
    .unwrap();
    Ok((id, lo, i64t.const_int(u64::from(c.width), false)))
}

/// Whether the `ref` actual `e` names storage a window reference can cover
/// ([`open_ref_window`]): a variable, a struct member or packed select of
/// one, or a class property (itself, or a member / select of it) -- never an
/// element of an unpacked array or a collection.
fn window_actual(e: Expression<'_>) -> bool {
    if crate::classes::is_class_field_lvalue(e) {
        return true;
    }
    let k = e.kind();
    if matches!(
        k,
        ExpressionKind::NamedValue | ExpressionKind::HierarchicalValue
    ) {
        return true;
    }
    if k == ExpressionKind::MemberAccess {
        return e.operand().is_some_and(window_actual);
    }
    // A conversion, an unpacked-array element, a call...: copy semantics.
    k == ExpressionKind::ElementSelect
        || k == ExpressionKind::RangeSelect
        // (a packed select's base; an unpacked array's row is not covered)
        && e.select_value()
            .is_some_and(|b| b.expr_type().is_some_and(|t| t.is_integral()) && window_actual(b))
}

/// A `ref` argument bound to a whole variable, a member or select of one, or a
/// class property (`f(s.n)`, `f(v[3:0])`, `f(obj.x)`, LRM 1800-2023 13.5.2):
/// a window reference (`sv_sim_sim::winref`) on the actual's root storage, as
/// `(id, bit offset, root width)`, all `i64`. The callee reads and writes the
/// part through the id, so a write it makes to the same storage by another
/// path (the module variable, the class handle, a nested call) is one
/// location with the formal. `None`: the actual is not such storage, or is
/// not exactly `width` bits (a conversion): the call then copies in and out.
/// A select the actual puts out of range gives id 0 (the holder keeps its own
/// copy).
pub(crate) fn open_ref_window<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lhs: Expression<'d>,
    width: u32,
) -> Option<(IntValue<'ctx>, IntValue<'ctx>, IntValue<'ctx>)> {
    use crate::select::{LvalueRoot, RootMode};
    if !window_actual(lhs) {
        return None;
    }
    let lv = crate::select::resolve_lvalue(cx, lhs, RootMode::Shadow).ok()?;
    if lv.edge.is_some()
        || lv.pad.is_some()
        || lv.width != width
        || crate::huge::is_image_width(lv.root_width)
    {
        return None;
    }
    let i64t = cx.ctx.i64_type();
    let two_state = u32::from(cx.repr == ValueRepr::TwoState);
    let shape = [1, 0, 0, 0, two_state];
    let id = match lv.root {
        LvalueRoot::Shadow { ptr } => {
            let addr = cx.b.build_ptr_to_int(ptr, i64t, "win_addr").unwrap();
            raw_call(
                cx,
                shape,
                CollOp::WinOpenMem,
                i64t.const_zero(),
                Args {
                    index: Some(addr),
                    ..Args::default()
                },
            )
        }
        LvalueRoot::Field { h, slot } => {
            let packed = (slot.offset as u64 & 0xffff_ffff) | ((slot.words as u64) << 32);
            raw_call(
                cx,
                shape,
                CollOp::WinOpenField,
                i64t.const_zero(),
                Args {
                    index: Some(h),
                    index2: Some(i64t.const_int(packed, false)),
                    ..Args::default()
                },
            )
        }
        _ => return None,
    };
    let id =
        cx.b.build_select(lv.bad, i64t.const_zero(), id, "ref_win_id")
            .unwrap()
            .into_int_value();
    let lo = if lv.lo.get_type().get_bit_width() > 64 {
        cx.b.build_int_truncate(lv.lo, i64t, "ref_win_lo")
    } else {
        cx.b.build_int_z_extend_or_bit_cast(lv.lo, i64t, "ref_win_lo")
    }
    .unwrap();
    Some((id, lo, i64t.const_int(u64::from(lv.root_width), false)))
}

/// The offset and element width the part-bound `ref` formal named by `e`
/// holds (zeros: a whole-element reference), to hand on with
/// [`held_ref_id`].
pub(crate) fn held_ref_part<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    e: Expression<'_>,
) -> (IntValue<'ctx>, IntValue<'ctx>) {
    let zero = cx.ctx.i64_type().const_zero();
    let slots = (|| {
        let sym = e.referenced_symbol()?;
        let (ptr, _, _) = *cx.locals.get(&sym.uid())?;
        cx.elem_refs.get(&ptr)?.part
    })();
    match slots {
        Some(p) => (load_slot64(cx, p.lo), load_slot64(cx, p.elem_width)),
        None => (zero, zero),
    }
}

/// The reference id the `ref` formal named by `e` holds (LRM 1800-2023
/// 13.5.2), to hand on to a nested call: `None` when `e` is no element-bound
/// `ref` formal of the enclosing subroutine.
pub(crate) fn held_ref_id<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    e: Expression<'_>,
) -> Option<IntValue<'ctx>> {
    if cx.elem_refs.is_empty() || !sv_sim_sim::symid::is_value_name(e.kind()) {
        return None;
    }
    let sym = e.referenced_symbol()?;
    let (ptr, _, _) = *cx.locals.get(&sym.uid())?;
    let r = cx.elem_refs.get(&ptr).copied()?;
    Some(load_ref_id(cx, &r))
}

/// The reference id stored in the 64-bit slot `slot` (see [`ElemRefSlot`]).
pub(crate) fn load_ref_slot<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    slot: PointerValue<'ctx>,
) -> IntValue<'ctx> {
    load_ref_id(
        cx,
        &ElemRefSlot {
            id: slot,
            id_width: 64,
            width: 1,
            signed: false,
            part: None,
        },
    )
}

fn load_ref_id<'ctx>(cx: &LowerCtx<'ctx, '_, '_>, r: &ElemRefSlot<'ctx>) -> IntValue<'ctx> {
    load_slot_of(cx, r.id, r.id_width)
}

/// The 64-bit frame temporary `slot` (a reference's offset / element width).
fn load_slot64<'ctx>(cx: &LowerCtx<'ctx, '_, '_>, slot: PointerValue<'ctx>) -> IntValue<'ctx> {
    load_slot_of(cx, slot, 64)
}

fn load_slot_of<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    slot: PointerValue<'ctx>,
    width: u32,
) -> IntValue<'ctx> {
    let o = op(cx);
    let pv = PackedValue {
        llvm: cx
            .b
            .build_load(o.packed_type(width, cx.repr), slot, "ref_id")
            .unwrap()
            .into_int_value(),
        width,
        repr: cx.repr,
        signed: false,
    };
    cx.b.build_int_z_extend_or_bit_cast(o.lane_val(pv), cx.ctx.i64_type(), "ref_id64")
        .unwrap()
}

/// The operation and operands that read / write the formal `r` through its
/// reference: the plain element operation, or (a part-bound formal) the part
/// operation with the offset (`index2`), the part width (`h`) and the
/// element's width (`h2`) loaded from the frame.
fn part_args<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    r: &ElemRefSlot<'ctx>,
    whole: CollOp,
    part: CollOp,
) -> (CollOp, IntValue<'ctx>, Args<'ctx>) {
    let i64t = cx.ctx.i64_type();
    let Some(p) = r.part else {
        return (whole, i64t.const_zero(), Args::default());
    };
    let a = Args {
        index2: Some(load_slot64(cx, p.lo)),
        h2: Some(load_slot64(cx, p.elem_width)),
        ..Args::default()
    };
    (part, i64t.const_int(u64::from(r.width), false), a)
}

fn ref_shape(words: u32) -> [u32; 5] {
    [words, 0, 0, 0, 0]
}

/// Before a read of the local `ptr`: when it is a `ref` formal bound to a
/// collection element, loads the element it names now into the local (an
/// outdated or closed reference leaves the local, the holder's own copy,
/// alone, 13.5.2). Nothing for any other local.
pub(crate) fn elem_ref_refresh<'ctx>(cx: &LowerCtx<'ctx, '_, '_>, ptr: PointerValue<'ctx>) {
    let Some(r) = cx.elem_refs.get(&ptr).copied() else {
        return;
    };
    refresh_slot(cx, &r, ptr);
}

/// [`elem_ref_refresh`] of the local `ptr` through the reference slots `r`.
pub(crate) fn refresh_slot<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    r: &ElemRefSlot<'ctx>,
    ptr: PointerValue<'ctx>,
) {
    let words = (2 * r.width).div_ceil(64).max(1);
    let cur = PackedValue {
        llvm: cx
            .b
            .build_load(op(cx).packed_type(r.width, cx.repr), ptr, "ref_cur")
            .unwrap()
            .into_int_value(),
        width: r.width,
        repr: cx.repr,
        signed: r.signed,
    };
    let buf = words_buf(cx, words, four_state(cx, cur), "ref_buf");
    let (op_, h, a) = part_args(cx, r, CollOp::RefGet, CollOp::RefGetPart);
    raw_call(
        cx,
        ref_shape(words),
        op_,
        h,
        Args {
            index: Some(load_ref_id(cx, r)),
            val: Some(buf),
            ..a
        },
    );
    let raw = load_words(cx, buf, words, r.width);
    let pv = from_four_state(cx, raw, r.width, r.signed);
    cx.b.build_store(ptr, pv.llvm).unwrap();
}

/// After a write to the local `ptr`: when it is a `ref` formal bound to a
/// collection element, puts the local into the element the reference names
/// (nothing once outdated: the callee's changes are not visible outside,
/// 13.5.2).
pub(crate) fn elem_ref_flush<'ctx>(cx: &LowerCtx<'ctx, '_, '_>, ptr: PointerValue<'ctx>) {
    let Some(r) = cx.elem_refs.get(&ptr).copied() else {
        return;
    };
    let words = (2 * r.width).div_ceil(64).max(1);
    let cur = PackedValue {
        llvm: cx
            .b
            .build_load(op(cx).packed_type(r.width, cx.repr), ptr, "ref_cur")
            .unwrap()
            .into_int_value(),
        width: r.width,
        repr: cx.repr,
        signed: r.signed,
    };
    let buf = words_buf(cx, words, four_state(cx, cur), "ref_buf");
    let (op_, h, a) = part_args(cx, &r, CollOp::RefPut, CollOp::RefPutPart);
    raw_call(
        cx,
        ref_shape(words),
        op_,
        h,
        Args {
            index: Some(load_ref_id(cx, &r)),
            val: Some(buf),
            ..a
        },
    );
}

/// The end of a `ref` call: closes the reference whose id `tptr` holds and
/// clears the slot.
pub(crate) fn close_ref<'ctx>(cx: &LowerCtx<'ctx, '_, '_>, tptr: PointerValue<'ctx>, twidth: u32) {
    let r = ElemRefSlot {
        id: tptr,
        id_width: twidth,
        width: 1,
        signed: false,
        part: None,
    };
    raw_call(
        cx,
        ref_shape(1),
        CollOp::RefClose,
        cx.ctx.i64_type().const_zero(),
        Args {
            index: Some(load_ref_id(cx, &r)),
            ..Args::default()
        },
    );
    cx.b.build_store(tptr, op(cx).packed_type(twidth, cx.repr).const_zero())
        .unwrap();
}

/// `c[i] <= v` where `c` is a queue or dynamic array held by a module
/// signal or a row of a module memory (`a[2][k] <= v`, `b[1][2][k] <= v`),
/// LRM 1800-2023 10.4.2, 7.10: `i` and `v` are evaluated now, the write is
/// staged (`sv_rt_nba_coll`) and lands in the NBA region in the collection
/// the variable holds *then*; an index outside it is ignored at that point
/// (a queue appends at `size`). `None` when `lhs` does not select from a
/// collection. An associative array's element is found by its key
/// (evaluated now; an invalid key writes nothing, 7.8.6), and a collection
/// element that is itself a collection takes a copy of the right side.
pub(crate) fn nba_element<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    handle: PointerValue<'ctx>,
    signals: &std::collections::HashMap<
        sv_sim_sim::symid::SymbolId,
        crate::process_lower::SignalSlot,
    >,
    lhs: Expression<'d>,
    rhs: Expression<'d>,
    delay: IntValue<'ctx>,
) -> Option<Result<(), LoweringError>> {
    use crate::select::{LvalueRoot, RootMode};
    if lhs.kind() != ExpressionKind::ElementSelect {
        return None;
    }
    let base = lhs.select_value()?;
    let c = coll_of_expr(&base)?;
    Some((|| {
        let sel = lhs.selector().ok_or_else(|| {
            LoweringError::unsupported_at("a collection select with no index", &cx.fn_sym)
        })?;
        // Where the collection's handle lives, and whether the outer
        // selects reach it at all (an out-of-range `a[k]` stages nothing).
        let lv = crate::select::resolve_lvalue(cx, base, RootMode::Signal(signals))?;
        let (slot, row, has_row) = match lv.root {
            LvalueRoot::Signal { slot } => (slot, cx.ctx.i64_type().const_zero(), 0u64),
            LvalueRoot::MemRow { info, row } => (info.slot, row, 1),
            _ => {
                return Err(LoweringError::unsupported_at(
                    "a nonblocking write into a collection that is not a module variable",
                    &cx.fn_sym,
                ));
            }
        };
        let ptr = cx.ctx.ptr_type(AddressSpace::default());
        // An associative array's element is found by key, evaluated now.
        let (i, key) = if c.assoc {
            (cx.ctx.i64_type().const_zero(), key_buf(cx, &c, sel)?)
        } else {
            let h = handle_of(cx, base)?;
            (index_of(cx, &c, h, sel)?, ptr.const_null())
        };
        // A whole nested-collection element takes a copy of the right side.
        let v = if coll_of(&c.elem).is_some() {
            assigned_value(cx, lhs, rhs)?
        } else {
            elem_value(cx, &c, rhs)?
        };
        let val = elem_buf(cx, &c, v)?;
        let i32t = cx.ctx.i32_type();
        let i64t = cx.ctx.i64_type();
        let name = crate::process_lower::SV_RT_NBA_COLL_SYMBOL;
        let f = cx.module.get_function(name).unwrap_or_else(|| {
            let fn_ty = cx.ctx.void_type().fn_type(
                &[
                    ptr.into(),
                    i32t.into(),
                    i64t.into(),
                    i32t.into(),
                    i64t.into(),
                    i32t.into(),
                    ptr.into(),
                    i32t.into(),
                    i64t.into(),
                    ptr.into(),
                    i32t.into(),
                    i32t.into(),
                ],
                false,
            );
            cx.module.add_function(name, fn_ty, Some(Linkage::External))
        });
        let func = cx.b.get_insert_block().unwrap().get_parent().unwrap();
        let stage_bb = cx.ctx.append_basic_block(func, "nba_coll_stage");
        let done_bb = cx.ctx.append_basic_block(func, "nba_coll_done");
        cx.b.build_conditional_branch(lv.bad, done_bb, stage_bb)
            .unwrap();
        cx.b.position_at_end(stage_bb);
        let flags = u64::from(c.queue) | (u64::from(c.obj) << 1);
        cx.b.build_call(
            f,
            &[
                handle.into(),
                i32t.const_int(u64::from(slot), false).into(),
                row.into(),
                i32t.const_int(has_row, false).into(),
                i.into(),
                i32t.const_int(flags, false).into(),
                val.into(),
                i32t.const_int(u64::from(c.words), false).into(),
                delay.into(),
                key.into(),
                i32t.const_int(u64::from(c.key_kind), false).into(),
                i32t.const_int(u64::from(c.key_width), false).into(),
            ],
            "rt_nba_coll_call",
        )
        .unwrap();
        cx.b.build_unconditional_branch(done_bb).unwrap();
        cx.b.position_at_end(done_bb);
        Ok(())
    })())
}

/// Whether evaluating `e` makes a new collection that nothing else holds.
fn is_fresh(e: &Expression<'_>) -> bool {
    matches!(
        e.kind(),
        ExpressionKind::Concatenation
            | ExpressionKind::SimpleAssignmentPattern
            | ExpressionKind::StructuredAssignmentPattern
            | ExpressionKind::ReplicatedAssignmentPattern
            | ExpressionKind::NewArray
            | ExpressionKind::RangeSelect
            | ExpressionKind::Call
            | ExpressionKind::EmptyArgument
    )
}

/// The collection value of `e` as a handle the caller now owns: a copy of
/// a stored collection, or the new collection `e` builds.
pub(crate) fn owned_value<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: Expression<'d>,
) -> Result<IntValue<'ctx>, LoweringError> {
    let mut e = e;
    // A queue <-> dynamic array conversion keeps the elements.
    while e.kind() == ExpressionKind::Conversion
        && let Some(inner) = e.operand()
        && coll_of_expr(&inner).is_some()
    {
        e = inner;
    }
    // A stream (`q = {<<8{x}}`): its bits, cut into elements.
    // `T'(v)` with a queue or dynamic-array `T` (LRM 6.24.3) reads back the
    // operand's stream the same way (a collection or fixed-array operand is
    // an element conversion, handled around this).
    if e.kind() == ExpressionKind::Conversion
        && (e.conversion_kind() == Some(2)
            || (e.conversion_kind() == Some(4)
                && e.conversion_operand().is_some_and(|i| {
                    coll_of_expr(&i).is_none()
                        && !i.expr_type().is_some_and(|t| t.is_unpacked_array())
                })))
        && let Some(c) = coll_of_expr(&e)
    {
        return crate::stream::stream_to_collection(cx, e, &c);
    }
    // A fixed-size array's elements, in index order.
    if e.kind() == ExpressionKind::Conversion
        && let Some(inner) = e.operand()
        && inner.expr_type().is_some_and(|t| t.is_unpacked_array())
        && let Some(c) = coll_of_expr(&e)
    {
        return crate::array_methods::gather_fixed(cx, &c, inner);
    }
    let h = handle_of(cx, e)?;
    if is_fresh(&e) {
        return Ok(h);
    }
    let c = coll_of_expr(&e).ok_or_else(|| {
        LoweringError::unsupported_at("a non-collection collection value", &cx.fn_sym)
    })?;
    Ok(call(cx, &c, CollOp::Clone, h, Args::default()))
}

/// [`owned_value`] as a stored value in `cx`'s representation (an input
/// argument, a local's initial value).
pub(crate) fn owned_arg<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: Expression<'d>,
) -> Result<IntValue<'ctx>, LoweringError> {
    let h = owned_value(cx, e)?;
    Ok(handle_value(cx, h).llvm)
}

/// The handle held by a stored collection value `v`.
fn stored_handle<'ctx>(cx: &LowerCtx<'ctx, '_, '_>, v: PackedValue<'ctx>) -> IntValue<'ctx> {
    let lane = op(cx).lane_val(v);
    if v.width == 64 {
        lane
    } else {
        cx.b.build_int_z_extend_or_bit_cast(lane, cx.ctx.i64_type(), "coll_h")
            .unwrap()
    }
}

/// A new collection that is a copy of the stored collection value `v` (of
/// collection type `ty`), as a stored value: what a static function hands
/// its caller while its own result variable keeps the original (LRM
/// 1800-2023 13.4.1, 6.21).
pub(crate) fn clone_stored<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    ty: &Type<'_>,
    v: PackedValue<'ctx>,
) -> Result<IntValue<'ctx>, LoweringError> {
    let c = coll_of(ty).ok_or_else(|| {
        LoweringError::unsupported_at("a non-collection collection value", &cx.fn_sym)
    })?;
    let h = call(cx, &c, CollOp::Clone, stored_handle(cx, v), Args::default());
    Ok(handle_value(cx, h).llvm)
}

/// `return e;` of a static function with a collection result: `e`'s value
/// becomes the (persistent) result variable at `slot`, the old collection
/// freed, and the caller gets a copy.
pub(crate) fn store_static_result<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    ty: &Type<'d>,
    slot: PointerValue<'ctx>,
    e: Expression<'d>,
) -> Result<IntValue<'ctx>, LoweringError> {
    let c = coll_of(ty).ok_or_else(|| {
        LoweringError::unsupported_at("a non-collection collection value", &cx.fn_sym)
    })?;
    let new = owned_value(cx, e)?;
    let new = clamp_bound(cx, &c, new);
    let stored = handle_value(cx, new);
    let old =
        cx.b.build_load(stored.llvm.get_type(), slot, "static_result_old")
            .unwrap()
            .into_int_value();
    let old_pv = PackedValue {
        llvm: old,
        ..stored
    };
    call(
        cx,
        &c,
        CollOp::Release,
        stored_handle(cx, old_pv),
        Args::default(),
    );
    cx.b.build_store(slot, stored.llvm).unwrap();
    clone_stored(cx, ty, stored)
}

/// The value `rhs` gives `lhs` in an assignment: `rhs`'s value, or for a
/// collection-typed `lhs` (or one holding collections) a copy (`lhs <= q`).
pub(crate) fn assigned_value<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lhs: Expression<'d>,
    rhs: Expression<'d>,
) -> Result<LoweredValue<'ctx>, LoweringError> {
    if coll_of_expr(&lhs).is_some() {
        let h = owned_value(cx, rhs)?;
        return Ok(LoweredValue::Packed(handle_value(cx, h)));
    }
    owned(cx, rhs)
}

/// What a reference-counted handle inside a stored value names.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub(crate) enum HandleKind {
    /// A queue, dynamic or associative array (`sv_rt_coll`).
    Coll,
    /// A class object (`sv_rt_obj`).
    Obj,
}

/// A condition on the stored value that makes a handle slot live: the
/// bits `[lsb, lsb + width)` equal `val` (the tag of a tagged union naming
/// the member that holds the handle, LRM 1800-2023 7.3.2).
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub(crate) struct TagGuard {
    pub lsb: u32,
    pub width: u32,
    pub val: u64,
}

/// One reference-counted handle inside a stored value: where it sits, what
/// it names, and the tag guards (outermost last) that must all hold for the
/// bits there to be a handle at all (empty: always).
#[derive(Clone, PartialEq, Eq, Debug)]
pub(crate) struct HandleSlot {
    pub off: u32,
    pub kind: HandleKind,
    pub guards: Vec<TagGuard>,
}

impl HandleSlot {
    fn at(off: u32, kind: HandleKind) -> Self {
        Self {
            off,
            kind,
            guards: Vec::new(),
        }
    }

    fn shifted(mut self, by: u32) -> Self {
        self.off += by;
        for g in &mut self.guards {
            g.lsb += by;
        }
        self
    }
}

/// The reference-counted handles inside the stored form of a value of type
/// `ty` (`sv_sim_sim::state::storage`): collection handles and class
/// handles, in its fields and elements, recursively. Empty for a type
/// holding none. The handles of a tagged union's members are guarded by
/// its tag (the members overlay each other).
pub(crate) fn handle_offsets(ty: &Type<'_>) -> Vec<HandleSlot> {
    use sv_sim_sim::state::storage;
    if storage::is_collection(ty) {
        return vec![HandleSlot::at(0, HandleKind::Coll)];
    }
    if ty.is_class() {
        return vec![HandleSlot::at(0, HandleKind::Obj)];
    }
    let mut out = Vec::new();
    if ty.is_unpacked_struct() {
        for f in ty.fields() {
            let (Some(fty), Some((lo, _))) =
                (f.value_type(), storage::field_slice(ty, f.field_index()))
            else {
                continue;
            };
            out.extend(
                handle_offsets(&fty)
                    .into_iter()
                    .map(|s| s.shifted(lo as u32)),
            );
        }
    } else if ty.is_unpacked_union() && ty.is_tagged_union() {
        let tag = storage::tagged_tag_slice(ty);
        for f in ty.fields() {
            let Some(fty) = f.value_type() else { continue };
            for mut s in handle_offsets(&fty) {
                if let Some((lsb, width)) = tag.filter(|&(_, w)| w > 0) {
                    s.guards.push(TagGuard {
                        lsb: lsb as u32,
                        width: width as u32,
                        val: u64::from(f.field_index()),
                    });
                }
                out.push(s);
            }
        }
    } else if ty.is_unpacked_array()
        && let Some(elem) = ty.element_type()
        && let Some(ew) = storage::storage_width(&elem)
    {
        let inner = handle_offsets(&elem);
        if !inner.is_empty() {
            for i in 0..ty.fixed_unpacked_array_range().width() {
                out.extend(inner.iter().cloned().map(|s| s.shifted(i * ew as u32)));
            }
        }
    }
    out
}

/// Replaces each handle at `offsets` in the stored value `pv` with
/// `f(handle, kind)`.
fn map_handles<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    pv: PackedValue<'ctx>,
    offsets: &[HandleSlot],
    f: &mut dyn FnMut(IntValue<'ctx>, HandleKind) -> IntValue<'ctx>,
) -> PackedValue<'ctx> {
    let o = op(cx);
    let ty = o.i_n(pv.width);
    let i64t = cx.ctx.i64_type();
    let mut val = o.lane_val(pv);
    for slot in offsets {
        let (off, kind) = (slot.off, slot.kind);
        let sh = ty.const_int(u64::from(off), false);
        let h = cx.b.build_right_shift(val, sh, false, "coll_fh").unwrap();
        let h = if pv.width > 64 {
            cx.b.build_int_truncate(h, i64t, "coll_fh64").unwrap()
        } else {
            cx.b.build_int_z_extend_or_bit_cast(h, i64t, "coll_fh64")
                .unwrap()
        };
        // A tag-guarded slot is a handle only while the tag names its
        // member (LRM 7.3.2); otherwise the bits are another member's value.
        // `f` runs on the null handle then (retain/release/clone of null are
        // no-ops) and its result is discarded.
        let live = slot
            .guards
            .iter()
            .fold(None, |acc: Option<IntValue<'ctx>>, g| {
                let w = ty;
                let tag =
                    cx.b.build_and(
                        cx.b.build_right_shift(
                            val,
                            w.const_int(u64::from(g.lsb), false),
                            false,
                            "coll_gt",
                        )
                        .unwrap(),
                        w.const_int((1u64 << g.width.min(63)) - 1, false),
                        "coll_gtm",
                    )
                    .unwrap();
                let hit =
                    cx.b.build_int_compare(
                        inkwell::IntPredicate::EQ,
                        tag,
                        w.const_int(g.val, false),
                        "coll_gtq",
                    )
                    .unwrap();
                Some(match acc {
                    Some(a) => cx.b.build_and(a, hit, "coll_gta").unwrap(),
                    None => hit,
                })
            });
        let h_in = match live {
            Some(l) => {
                cx.b.build_select(l, h, i64t.const_zero(), "coll_fgh")
                    .unwrap()
                    .into_int_value()
            }
            None => h,
        };
        let new = f(h_in, kind);
        let new = match live {
            Some(l) => {
                cx.b.build_select(l, new, h, "coll_fgn")
                    .unwrap()
                    .into_int_value()
            }
            None => new,
        };
        let new = if pv.width > 64 {
            cx.b.build_int_z_extend(new, ty, "coll_fnew").unwrap()
        } else {
            cx.b.build_int_truncate_or_bit_cast(new, ty, "coll_fnew")
                .unwrap()
        };
        let mask =
            cx.b.build_left_shift(
                cx.b.build_int_z_extend_or_bit_cast(i64t.const_all_ones(), ty, "coll_fm")
                    .unwrap(),
                sh,
                "coll_fmask",
            )
            .unwrap();
        let kept =
            cx.b.build_and(val, cx.b.build_not(mask, "coll_fkeep").unwrap(), "coll_fk")
                .unwrap();
        let placed = cx.b.build_left_shift(new, sh, "coll_fput").unwrap();
        val = cx.b.build_or(kept, placed, "coll_fset").unwrap();
    }
    o.pack(val, o.lane_unk(pv), pv.width, pv.repr, pv.signed)
}

/// Whether `e` builds a new value nobody else holds (a pattern, a function
/// result, `new`, a queue `pop`): its handles need no copy or retain. The
/// null literal holds nothing.
pub(crate) fn fresh(e: &Expression<'_>) -> bool {
    let mut e = *e;
    while e.kind() == ExpressionKind::Conversion
        && let Some(inner) = e.operand()
    {
        e = inner;
    }
    // A `pop_front`/`pop_back` hands the caller the reference the queue held.
    let pops = e.is_system_call() == Some(true)
        && e.system_subroutine().is_some_and(|s| {
            matches!(
                s.known_name_id(),
                KnownSystemName::PopBack | KnownSystemName::PopFront
            )
        })
        // A `leaky` queue keeps its own count (see [`Coll::leaky`]).
        && !e
            .operands()
            .first()
            .and_then(coll_of_expr)
            .is_some_and(|c| c.leaky);
    matches!(
        e.kind(),
        ExpressionKind::SimpleAssignmentPattern
            | ExpressionKind::StructuredAssignmentPattern
            | ExpressionKind::ReplicatedAssignmentPattern
            | ExpressionKind::TaggedUnion
            | ExpressionKind::NewClass
            | ExpressionKind::CopyClass
            | ExpressionKind::NullLiteral
    ) || (e.kind() == ExpressionKind::Call
        && (e.is_system_call() != Some(true) || pops)
        // `weak_reference::get()` returns a borrowed handle (no +1 to adopt).
        && !crate::classes::is_weak_get_call(&e))
}

/// `e`'s value as a copy the caller owns: a collection's handle copied, a
/// class handle retained, or each handle held by a struct or array value --
/// unless `e` builds a new value ([`fresh`]). The caller's value holds one
/// reference to every object it names, to be given to the variable, field or
/// element it is stored into (which releases what it held before).
pub(crate) fn owned<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: Expression<'d>,
) -> Result<LoweredValue<'ctx>, LoweringError> {
    if coll_of_expr(&e).is_some() {
        let h = owned_value(cx, e)?;
        return Ok(LoweredValue::Packed(handle_value(cx, h)));
    }
    // A fixed-size array stored whole as one element of a queue, dynamic or
    // associative array (`w[i] = a`, `m[k] = a`): its packed row, which
    // already carries its own references.
    if e.expr_type()
        .is_some_and(|t| crate::arrays::array_shape(&t).is_some())
    {
        return Ok(LoweredValue::Packed(crate::arrays::pack_array_value(
            cx, e,
        )?));
    }
    let v = lower_expr(cx, e)?;
    let offsets = e
        .expr_type()
        .map(|t| handle_offsets(&t))
        .unwrap_or_default();
    if offsets.is_empty() || fresh(&e) {
        return Ok(v);
    }
    let LoweredValue::Packed(pv) = v else {
        return Ok(v);
    };
    Ok(LoweredValue::Packed(retain_offsets(cx, pv, &offsets)))
}

/// A copy the caller owns of the stored value `pv` that some other holder
/// still names: each collection handle copied, each class handle retained.
fn retain_offsets<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    pv: PackedValue<'ctx>,
    offsets: &[HandleSlot],
) -> PackedValue<'ctx> {
    map_handles(cx, pv, offsets, &mut |h, kind| match kind {
        HandleKind::Coll => raw_call(cx, [1, 0, 0, 0, 0], CollOp::Clone, h, Args::default()),
        HandleKind::Obj => {
            crate::classes::retain_handle(cx, h);
            h
        }
    })
}

/// [`owned`] for a value already read out of a holder (an array element, a
/// collection element): the returned value carries its own reference to
/// every object and collection `pv` (of type `ty`) names -- the same
/// handles, each given one more count (a value holding none is returned
/// as is).
pub(crate) fn retain_stored<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    ty: &Type<'_>,
    pv: PackedValue<'ctx>,
) -> PackedValue<'ctx> {
    let offsets = handle_offsets(ty);
    if offsets.is_empty() {
        return pv;
    }
    retain_offsets(cx, pv, &offsets)
}

/// Whether storing to `lhs` releases what it held in the store itself (a
/// class property: `classes::store_field`; a collection element: the
/// runtime's `Set`/`Store`), so no separate release of the old value may run.
fn store_releases_itself(lhs: Expression<'_>) -> bool {
    crate::classes::is_class_field_lvalue(lhs)
        || (lhs.kind() == ExpressionKind::ElementSelect
            && lhs
                .select_value()
                .is_some_and(|b| coll_of_expr(&b).is_some()))
}

/// Frees the collections and releases the objects the plain-name assignment
/// target `lhs` holds (a variable of a handle, struct or array type), before
/// it is overwritten. Reading a name has no side effects, so it is safe to
/// read here and again in the store; any other target (an index expression
/// may have side effects, LRM 11.4.2) is stored with [`store_releasing`]
/// instead, which resolves it once. A target that releases its own old value
/// ([`store_releases_itself`]) is skipped.
pub(crate) fn release_old<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lhs: Expression<'d>,
) -> Result<(), LoweringError> {
    if !sv_sim_sim::symid::is_value_name(lhs.kind()) {
        return Err(LoweringError::unsupported_at(
            "internal: release_old on a target that is not a plain name",
            &cx.fn_sym,
        ));
    }
    if store_releases_itself(lhs) {
        return Ok(());
    }
    if let Some(t) = lhs.expr_type()
        && !handle_offsets(&t).is_empty()
    {
        let old = lower_expr(cx, lhs)?;
        release_handles(cx, &t, old);
    }
    Ok(())
}

/// Stores the owned `value` into the (non-name) target `lhs`, releasing the
/// handles the target held first. The target's address is resolved ONCE
/// (LRM 11.4.2: `fx[i++] = h` increments `i` once), and the release reads
/// the value at that same address -- never a second evaluation of `lhs`.
pub(crate) fn store_releasing<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lhs: Expression<'d>,
    value: LoweredValue<'ctx>,
) -> Result<LoweredValue<'ctx>, LoweringError> {
    let held = lhs
        .expr_type()
        .filter(|t| !handle_offsets(t).is_empty() && !store_releases_itself(lhs));
    let Some(t) = held else {
        return store_to(cx, lhs, value);
    };
    let mut release = |old: PackedValue<'ctx>| release_handles(cx, &t, LoweredValue::Packed(old));
    crate::expr::store_to_releasing(cx, lhs, value, Some(&mut release))
}

/// Releases the handles of type `t` held by the already-resolved array
/// element `r`, just before it is overwritten (the single-evaluation
/// counterpart of [`release_old`] for `fx[i++] = h`).
pub(crate) fn release_element<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    t: &Type<'_>,
    r: &crate::arrays::ElemRef<'ctx>,
) -> Result<(), LoweringError> {
    if handle_offsets(t).is_empty() {
        return Ok(());
    }
    let old = crate::arrays::read_element(cx, r)?;
    release_handles(cx, t, LoweredValue::Packed(old));
    Ok(())
}

/// Frees every collection and releases every object held by the value `v`
/// of type `ty` (a value about to be overwritten).
pub(crate) fn release_handles<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    ty: &Type<'_>,
    v: LoweredValue<'ctx>,
) {
    release_handles_of(cx, ty, v, false);
}

/// [`release_handles`], optionally only the objects (`objs_only`): the old
/// value of a class property cannot free its collections, since a method
/// like `push_back` stores the (possibly same) collection handle back.
pub(crate) fn release_handles_of<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    ty: &Type<'_>,
    v: LoweredValue<'ctx>,
    objs_only: bool,
) {
    let offsets = handle_offsets(ty);
    let LoweredValue::Packed(pv) = v else {
        return;
    };
    if offsets.is_empty() {
        return;
    }
    map_handles(cx, pv, &offsets, &mut |h, kind| {
        match kind {
            HandleKind::Coll if objs_only => {}
            HandleKind::Coll => {
                raw_call(cx, [1, 0, 0, 0, 0], CollOp::Release, h, Args::default());
            }
            HandleKind::Obj => crate::classes::release_handle(cx, h),
        }
        h
    });
}

/// `lhs = rhs` for a collection-typed `lhs`: the old collection is freed.
pub(crate) fn assign_whole<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lhs: Expression<'d>,
    rhs: Expression<'d>,
) -> Result<LoweredValue<'ctx>, LoweringError> {
    let c = coll_of_expr(&lhs)
        .ok_or_else(|| LoweringError::unsupported_at("a non-collection target", &cx.fn_sym))?;
    let new = owned_value(cx, rhs)?;
    let new = clamp_bound(cx, &c, new);
    if sv_sim_sim::symid::is_value_name(lhs.kind()) {
        let old = handle_of(cx, lhs)?;
        call(cx, &c, CollOp::Release, old, Args::default());
        set_handle(cx, lhs, new)?;
    } else {
        // An element of a fixed array of collections, a struct member: the
        // target's index may have side effects, so it is resolved once.
        store_releasing(cx, lhs, LoweredValue::Packed(handle_value(cx, new)))?;
    }
    Ok(LoweredValue::Packed(handle_value(cx, new)))
}

/// A collection-typed expression that builds a new collection
/// (concatenation, assignment pattern, `new[n]`, slice): its fresh handle.
/// `None` for anything else.
pub(crate) fn lower_constructor<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: Expression<'d>,
) -> Option<Result<LoweredValue<'ctx>, LoweringError>> {
    let c = coll_of_expr(&e)?;
    let kind = e.kind();
    let r = || -> Result<IntValue<'ctx>, LoweringError> {
        let i64t = cx.ctx.i64_type();
        let zero = i64t.const_zero();
        match kind {
            ExpressionKind::Concatenation => {
                let mut h = zero;
                for x in e.operands() {
                    let fixed_array = coll_of_expr(&x).is_none()
                        && !(c.elem.is_unpacked_array())
                        && x.expr_type().is_some_and(|t| t.is_unpacked_array());
                    if fixed_array {
                        // A fixed-size array operand contributes each of its
                        // elements in order (LRM 1800-2023 10.10).
                        if c.leaky {
                            return Err(LoweringError::unsupported_at(
                                "an array operand in a concatenation of structs holding class handles",
                                &cx.fn_sym,
                            ));
                        }
                        for v in crate::arrays::array_operand_elements(cx, x, &c.elem)? {
                            // The array keeps its own reference to a class
                            // element; the new queue takes one of its own.
                            retain_elem(cx, &c, LoweredValue::Packed(v));
                            let val = elem_buf(cx, &c, LoweredValue::Packed(v))?;
                            h = call(
                                cx,
                                &c,
                                CollOp::Push,
                                h,
                                Args {
                                    val: Some(val),
                                    ..Args::default()
                                },
                            );
                        }
                    } else if let Some(oc) = coll_of_expr(&x).filter(|o| o.assoc) {
                        // An associative array operand contributes its
                        // values in ascending key order (LRM 1800-2023 10.10
                        // "left-to-right order as they would appear in the
                        // array item itself"); the new queue takes its own
                        // reference to a class element.
                        let other = handle_of(cx, x)?;
                        let acc = entry_alloca(cx, i64t, "cat_assoc_acc");
                        cx.b.build_store(acc, h).unwrap();
                        let n = size_of_handle(cx, &oc, other);
                        let n =
                            cx.b.build_int_z_extend_or_bit_cast(n, i64t, "cat_n")
                                .unwrap();
                        crate::array_methods::each(cx, n, false, |pos, _| {
                            let v = read_pos(cx, &oc, other, pos);
                            retain_elem(cx, &c, v);
                            let val = elem_buf(cx, &c, v)?;
                            let cur =
                                cx.b.build_load(i64t, acc, "cat_h")
                                    .unwrap()
                                    .into_int_value();
                            let nh = call(
                                cx,
                                &c,
                                CollOp::Push,
                                cur,
                                Args {
                                    val: Some(val),
                                    ..Args::default()
                                },
                            );
                            cx.b.build_store(acc, nh).unwrap();
                            Ok(())
                        })?;
                        h =
                            cx.b.build_load(i64t, acc, "cat_h")
                                .unwrap()
                                .into_int_value();
                    } else if coll_of_expr(&x).is_some()
                        && !(sv_sim_sim::state::storage::is_collection(&c.elem)
                            && x.expr_type()
                                .is_some_and(|t| c.elem.is_assignment_compatible(&t)))
                    {
                        // (An item assignable to a collection element type is
                        // one element, LRM 1800-2023 10.10: `{a, b}` of
                        // `int a[$], b[$]` into `int qq[$][$]`.)
                        let other = handle_of(cx, x)?;
                        h = call(
                            cx,
                            &c,
                            CollOp::Append,
                            h,
                            Args {
                                h2: Some(other),
                                ..Args::default()
                            },
                        );
                    } else {
                        let v = elem_value(cx, &c, x)?;
                        let val = elem_buf(cx, &c, v)?;
                        h = call(
                            cx,
                            &c,
                            CollOp::Push,
                            h,
                            Args {
                                val: Some(val),
                                ..Args::default()
                            },
                        );
                    }
                }
                Ok(h)
            }
            // `'{key: value, ...}` of an associative array.
            ExpressionKind::StructuredAssignmentPattern => {
                let mut h = zero;
                if let Some(d) = e.structured_pattern_default_setter() {
                    // The `default:` setter keeps a bare string literal (the
                    // index setters get an implicit conversion), which would
                    // lower as its packed bytes and read back as "" (LRM
                    // 7.9.11: a nonexistent element reads the default).
                    let dv = if c.elem.is_string()
                        && d.kind() == ExpressionKind::StringLiteral
                        && let Some(s) = crate::strings::lower_string_expr(cx, d)?
                    {
                        LoweredValue::Str(s)
                    } else {
                        elem_value(cx, &c, d)?
                    };
                    let val = elem_buf(cx, &c, dv)?;
                    h = call(
                        cx,
                        &c,
                        CollOp::SetDefault,
                        h,
                        Args {
                            val: Some(val),
                            ..Args::default()
                        },
                    );
                }
                for setter in e.structured_pattern_index_setters() {
                    let key = key_buf(cx, &c, setter.index())?;
                    let val = elem_buf(cx, &c, elem_value(cx, &c, setter.expr())?)?;
                    h = call(
                        cx,
                        &c,
                        CollOp::Store,
                        h,
                        Args {
                            val: Some(val),
                            key: Some(key),
                            ..Args::default()
                        },
                    );
                }
                Ok(h)
            }
            ExpressionKind::SimpleAssignmentPattern
            | ExpressionKind::ReplicatedAssignmentPattern => {
                if c.assoc {
                    return Err(LoweringError::unsupported_at(
                        "an associative array assignment pattern",
                        &cx.fn_sym,
                    ));
                }
                let elems = e.pattern_elements();
                let reps = if kind == ExpressionKind::ReplicatedAssignmentPattern {
                    e.replicated_pattern_count()
                        .and_then(|n| n.constant_value())
                        .and_then(|v| v.as_i64())
                        .ok_or_else(|| {
                            LoweringError::unsupported_at(
                                "a non-constant replication count",
                                &cx.fn_sym,
                            )
                        })?
                } else {
                    1
                };
                let mut h = zero;
                for _ in 0..reps.max(0) {
                    for x in &elems {
                        let v = elem_value(cx, &c, *x)?;
                        let val = elem_buf(cx, &c, v)?;
                        h = call(
                            cx,
                            &c,
                            CollOp::Push,
                            h,
                            Args {
                                val: Some(val),
                                ..Args::default()
                            },
                        );
                    }
                }
                Ok(h)
            }
            ExpressionKind::NewArray => {
                let n = e.new_array_size().ok_or_else(|| {
                    LoweringError::unsupported_at("new[] with no size", &cx.fn_sym)
                })?;
                let n = lower_expr(cx, n)?.into_packed("a new[] size", &cx.fn_sym)?;
                let o = op(cx);
                let n = o.lane_val(n);
                let n =
                    cx.b.build_int_z_extend_or_bit_cast(n, i64t, "new_n")
                        .unwrap();
                let src = match e.new_array_init() {
                    Some(init) => handle_of(cx, init)?,
                    None => zero,
                };
                let dflt = default_buf(cx, &c);
                Ok(call(
                    cx,
                    &c,
                    CollOp::Resized,
                    zero,
                    Args {
                        index: Some(n),
                        h2: Some(src),
                        dflt: Some(dflt),
                        ..Args::default()
                    },
                ))
            }
            ExpressionKind::RangeSelect => {
                let base = e.select_value().ok_or_else(|| {
                    LoweringError::unsupported_at("a slice with no base", &cx.fn_sym)
                })?;
                let h = handle_of(cx, base)?;
                let (a, b) = slice_bounds(cx, &c, h, e)?;
                Ok(call(
                    cx,
                    &c,
                    CollOp::Slice,
                    h,
                    Args {
                        index: Some(a),
                        index2: Some(b),
                        ..Args::default()
                    },
                ))
            }
            _ => Err(LoweringError::unsupported_at(
                "not a collection constructor",
                &cx.fn_sym,
            )),
        }
    };
    if !matches!(
        kind,
        ExpressionKind::Concatenation
            | ExpressionKind::SimpleAssignmentPattern
            | ExpressionKind::ReplicatedAssignmentPattern
            | ExpressionKind::NewArray
    ) && !(kind == ExpressionKind::StructuredAssignmentPattern && c.assoc)
        && !(kind == ExpressionKind::RangeSelect
            && e.select_value().is_some_and(|b| coll_of_expr(&b).is_some()))
    {
        return None;
    }
    Some(r().map(|h| LoweredValue::Packed(handle_value(cx, h))))
}

/// A queue slice's `(first, last)` indices (`q[a:b]`, `q[a+:w]`,
/// `q[a-:w]`).
pub(crate) fn slice_bounds<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    c: &Coll,
    h: IntValue<'ctx>,
    e: Expression<'d>,
) -> Result<(IntValue<'ctx>, IntValue<'ctx>), LoweringError> {
    let left = e
        .range_left()
        .ok_or_else(|| LoweringError::unsupported_at("a slice with no left bound", &cx.fn_sym))?;
    let right = e
        .range_right()
        .ok_or_else(|| LoweringError::unsupported_at("a slice with no right bound", &cx.fn_sym))?;
    let (a, ka) = index_of_known(cx, c, h, left)?;
    let (r, kr) = index_of_known(cx, c, h, right)?;
    let one = cx.ctx.i64_type().const_int(1, false);
    let (a, b) = match e.range_selection_kind() {
        // `a +: w`: a .. a + w - 1.
        Some(1) => {
            let b = cx.b.build_int_add(a, r, "slice_hi").unwrap();
            (a, cx.b.build_int_sub(b, one, "slice_hi1").unwrap())
        }
        // `a -: w`: a - w + 1 .. a.
        Some(2) => {
            let lo = cx.b.build_int_sub(a, r, "slice_lo").unwrap();
            (cx.b.build_int_add(lo, one, "slice_lo1").unwrap(), a)
        }
        _ => (a, r),
    };
    // An x/z bound yields the empty queue (LRM 7.10.1): first 0, last -1.
    let known = cx.b.build_and(ka, kr, "slice_known").unwrap();
    let a =
        cx.b.build_select(known, a, cx.ctx.i64_type().const_zero(), "slice_a")
            .unwrap()
            .into_int_value();
    let b =
        cx.b.build_select(known, b, cx.ctx.i64_type().const_all_ones(), "slice_b")
            .unwrap()
            .into_int_value();
    Ok((a, b))
}

/// `a == b` / `a != b` on two collections (`None` for anything else).
pub(crate) fn lower_equality<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: Expression<'d>,
    negate: bool,
) -> Option<Result<LoweredValue<'ctx>, LoweringError>> {
    let l = e.left()?;
    let r = e.right()?;
    let c = coll_of_expr(&l)?;
    Some((|| {
        let a = handle_of(cx, l)?;
        let b = handle_of(cx, r)?;
        let eq = call(
            cx,
            &c,
            CollOp::Equal,
            a,
            Args {
                h2: Some(b),
                ..Args::default()
            },
        );
        let eq =
            cx.b.build_int_truncate(eq, cx.ctx.bool_type(), "coll_eq")
                .unwrap();
        let eq = if negate {
            cx.b.build_not(eq, "coll_ne").unwrap()
        } else {
            eq
        };
        let z = cx.ctx.bool_type().const_zero();
        Ok(LoweredValue::Packed(op(cx).pack(eq, z, 1, cx.repr, false)))
    })())
}

/// A built-in method of a collection (`q.push_back(v)`, `a.exists(k)`,
/// `$size(d)`, ...), or `None` when `e` is no such call.
pub(crate) fn lower_method<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    name: KnownSystemName,
    e: Expression<'d>,
) -> Option<Result<LoweredValue<'ctx>, LoweringError>> {
    use KnownSystemName as K;
    // LRM 20.7 `$dimensions`/`$unpacked_dimensions` depend on the type only:
    // they fold at elaboration (the CG-042 path), never a runtime call.
    if matches!(name, K::Dimensions | K::UnpackedDimensions) {
        return None;
    }
    // `$fread(q, fd)` takes a collection as an output argument; `crate::fileio`
    // lowers it.
    if name == K::FRead {
        return None;
    }
    let args = e.operands();
    let this = *args.first()?;
    let c = coll_of_expr(&this)?;
    let rest: Vec<Expression<'d>> = args[1..].to_vec();
    Some((|| {
        let h = handle_of(cx, this)?;
        let i64t = cx.ctx.i64_type();
        let size = || call(cx, &c, CollOp::Size, h, Args::default());
        let arg = |k: usize| {
            rest.get(k).copied().ok_or_else(|| {
                LoweringError::unsupported_at(
                    "a collection method is missing an argument",
                    &cx.fn_sym,
                )
            })
        };
        match name {
            K::Size | K::ArraySize | K::Num => Ok(int(cx, size())),
            // LRM 20.7: an associative array with an integral index (the
            // only kind the query functions accept) reports `$left` 0,
            // `$right` the highest possible index value, `$increment` -1,
            // and `$low`/`$high` the smallest/largest ALLOCATED index
            // ('x when empty).
            K::Left if c.assoc => Ok(int(cx, i64t.const_zero())),
            K::Increment if c.assoc => Ok(int(cx, i64t.const_all_ones())),
            K::Right if c.assoc => {
                let w = c.key_width.min(64);
                let bits = if c.key_kind == 1 { w - 1 } else { w };
                let max = if bits >= 64 {
                    u64::MAX
                } else {
                    (1u64 << bits) - 1
                };
                Ok(int(cx, i64t.const_int(max, false)))
            }
            K::Low | K::High if c.assoc => {
                let key = entry_alloca(cx, op(cx).i_n(64 * c.key_words()), "coll_lohi");
                let which = if name == K::Low {
                    CollOp::First
                } else {
                    CollOp::Last
                };
                let found = call(
                    cx,
                    &c,
                    which,
                    h,
                    Args {
                        key: Some(key),
                        ..Args::default()
                    },
                );
                let o = op(cx);
                let i32t = cx.ctx.i32_type();
                let kv = o.lane_val(load_key(cx, &c, key));
                let kv = if c.key_width < 32 {
                    if c.key_kind == 1 {
                        cx.b.build_int_s_extend(kv, i32t, "coll_k32").unwrap()
                    } else {
                        cx.b.build_int_z_extend(kv, i32t, "coll_k32").unwrap()
                    }
                } else {
                    cx.b.build_int_truncate_or_bit_cast(kv, i32t, "coll_k32")
                        .unwrap()
                };
                let hit =
                    cx.b.build_int_compare(IntPredicate::NE, found, i64t.const_zero(), "coll_lh")
                        .unwrap();
                let val =
                    cx.b.build_select(hit, kv, i32t.const_zero(), "coll_lv")
                        .unwrap()
                        .into_int_value();
                let unk =
                    cx.b.build_select(hit, i32t.const_zero(), i32t.const_all_ones(), "coll_lu")
                        .unwrap()
                        .into_int_value();
                Ok(LoweredValue::Packed(o.pack(val, unk, 32, cx.repr, true)))
            }
            // LRM 20.7: an associative array with an integral index reports
            // `$left` 0, `$right` the highest possible index value of the
            // index type, `$increment` -1, and `$low`/`$high` the smallest /
            // largest ALLOCATED index, `'x` when none is allocated.
            K::Left if c.assoc => Ok(int(cx, i64t.const_zero())),
            K::Increment if c.assoc => Ok(int(cx, i64t.const_all_ones())),
            K::Right if c.assoc => {
                let w = c.key_width.min(63);
                let max = if c.key_kind == 1 {
                    (1u64 << (w - 1)) - 1
                } else {
                    (1u64 << w) - 1
                };
                Ok(int(cx, i64t.const_int(max, false)))
            }
            K::Low | K::High if c.assoc => {
                let o = op(cx);
                let zero_key = o.i_n(2 * c.key_width).const_zero();
                let key = words_buf(cx, c.key_words(), zero_key, "coll_lowhigh_key");
                let which = if name == K::Low {
                    CollOp::First
                } else {
                    CollOp::Last
                };
                let found = call(
                    cx,
                    &c,
                    which,
                    h,
                    Args {
                        key: Some(key),
                        ..Args::default()
                    },
                );
                let hit =
                    cx.b.build_int_compare(IntPredicate::NE, found, i64t.const_zero(), "coll_hit")
                        .unwrap();
                let k = crate::select::fit_width(&o, load_key(cx, &c, key), 32);
                let i32t = cx.ctx.i32_type();
                let val =
                    cx.b.build_select(hit, o.lane_val(k), i32t.const_zero(), "coll_lh_v")
                        .unwrap()
                        .into_int_value();
                let unk =
                    cx.b.build_select(hit, o.lane_unk(k), i32t.const_all_ones(), "coll_lh_u")
                        .unwrap()
                        .into_int_value();
                Ok(LoweredValue::Packed(o.pack(val, unk, 32, cx.repr, true)))
            }
            K::Low | K::Left => Ok(int(cx, i64t.const_zero())),
            K::High | K::Right => {
                let last =
                    cx.b.build_int_sub(size(), i64t.const_int(1, false), "coll_high")
                        .unwrap();
                Ok(int(cx, last))
            }
            // LRM 20.7: `$increment` of a queue or dynamic array dimension is
            // -1 whatever its size (so `$low` is `$left` 0, `$high` `$right`).
            K::Increment => Ok(int(cx, i64t.const_all_ones())),
            K::PushBack | K::PushFront => {
                let val = elem_buf(cx, &c, elem_value(cx, &c, arg(0)?)?)?;
                let front = i64t.const_int(u64::from(name == K::PushFront), false);
                let new = call(
                    cx,
                    &c,
                    CollOp::Push,
                    h,
                    Args {
                        index: Some(front),
                        val: Some(val),
                        ..Args::default()
                    },
                );
                set_handle(cx, this, clamp_bound(cx, &c, new))?;
                Ok(void(cx))
            }
            K::PopBack | K::PopFront => {
                let val = entry_alloca(cx, op(cx).i_n(64 * c.words), "coll_pop");
                let dflt = default_buf(cx, &c);
                let front = i64t.const_int(u64::from(name == K::PopFront), false);
                let new = call(
                    cx,
                    &c,
                    CollOp::Pop,
                    h,
                    Args {
                        index: Some(front),
                        val: Some(val),
                        dflt: Some(dflt),
                        ..Args::default()
                    },
                );
                set_handle(cx, this, new)?;
                Ok(load_elem(cx, &c, val))
            }
            K::Insert => {
                let i = index_of(cx, &c, h, arg(0)?)?;
                let val = elem_buf(cx, &c, elem_value(cx, &c, arg(1)?)?)?;
                let new = call(
                    cx,
                    &c,
                    CollOp::Insert,
                    h,
                    Args {
                        index: Some(i),
                        val: Some(val),
                        ..Args::default()
                    },
                );
                set_handle(cx, this, clamp_bound(cx, &c, new))?;
                Ok(void(cx))
            }
            K::Delete => {
                let new = match rest.first() {
                    None => call(cx, &c, CollOp::Clear, h, Args::default()),
                    Some(&k) if c.assoc => {
                        let key = key_buf(cx, &c, k)?;
                        call(
                            cx,
                            &c,
                            CollOp::DeleteKey,
                            h,
                            Args {
                                key: Some(key),
                                ..Args::default()
                            },
                        )
                    }
                    Some(&k) => {
                        let i = index_of(cx, &c, h, k)?;
                        call(
                            cx,
                            &c,
                            CollOp::DeleteAt,
                            h,
                            Args {
                                index: Some(i),
                                ..Args::default()
                            },
                        )
                    }
                };
                set_handle(cx, this, new)?;
                Ok(void(cx))
            }
            K::Exists => {
                let key = key_buf(cx, &c, arg(0)?)?;
                Ok(int(
                    cx,
                    call(
                        cx,
                        &c,
                        CollOp::Exists,
                        h,
                        Args {
                            key: Some(key),
                            ..Args::default()
                        },
                    ),
                ))
            }
            K::First | K::Last | K::Next | K::Prev if c.assoc => {
                let target = arg(0)?;
                let key = key_buf(cx, &c, target)?;
                let which = match name {
                    K::First => CollOp::First,
                    K::Last => CollOp::Last,
                    K::Next => CollOp::Next,
                    _ => CollOp::Prev,
                };
                let found = call(
                    cx,
                    &c,
                    which,
                    h,
                    Args {
                        key: Some(key),
                        ..Args::default()
                    },
                );
                // The key variable changes only when a key was found.
                let f =
                    cx.b.get_insert_block()
                        .and_then(|bb| bb.get_parent())
                        .expect("lowering happens inside a function");
                let then_bb = cx.ctx.append_basic_block(f, "coll_found");
                let done_bb = cx.ctx.append_basic_block(f, "coll_found_done");
                let hit =
                    cx.b.build_int_compare(IntPredicate::NE, found, i64t.const_zero(), "coll_hit")
                        .unwrap();
                cx.b.build_conditional_branch(hit, then_bb, done_bb)
                    .unwrap();
                cx.b.position_at_end(then_bb);
                let k = load_key(cx, &c, key);
                if c.key_kind == 3 {
                    // A class-handle key lands in a handle variable that owns
                    // a reference (LRM 8.29): retain the new object, then
                    // release the one the variable named.
                    let old = handle_of(cx, target)?;
                    crate::classes::retain_handle(cx, op(cx).lane_val(k));
                    store_to(cx, target, LoweredValue::Packed(k))?;
                    crate::classes::release_handle(cx, old);
                } else {
                    store_to(cx, target, LoweredValue::Packed(k))?;
                }
                cx.b.build_unconditional_branch(done_bb).unwrap();
                cx.b.position_at_end(done_bb);
                Ok(int(cx, found))
            }
            _ => Err(LoweringError::unsupported_at(
                &format!("the array method {name:?} on a queue, dynamic or associative array"),
                &cx.fn_sym,
            )),
        }
    })())
}

/// The number of elements of the collection-typed `arr`, and its handle
/// (a `foreach` bound).
pub(crate) fn size_and_handle<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    arr: Expression<'d>,
) -> Result<(IntValue<'ctx>, IntValue<'ctx>), LoweringError> {
    let c = coll_of_expr(&arr).ok_or_else(|| {
        LoweringError::unsupported_at("foreach over a non-collection", &cx.fn_sym)
    })?;
    let h = handle_of(cx, arr)?;
    Ok((call(cx, &c, CollOp::Size, h, Args::default()), h))
}

/// The size of the queue / dynamic array that the enclosing `foreach`
/// indices `path` select from `arr` (`a[i][j]` for `foreach (a[i, j, k])`
/// over `int a[2][3][]`): a counted loop's bound for a suspending nested
/// `foreach` (`process::cfg::RepeatCount::NestedSize`). The indices are the
/// loop variables' current values (process locals). Leading fixed
/// dimensions select a row of `arr` (row-major); the collection dimensions
/// after them walk element handles (`child_coll_at`). An associative array
/// in the chain, or a fixed dimension after a collection one, is refused.
pub(crate) fn nested_handle<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    arr: Expression<'d>,
    path: &[sv_sim_sim::process::cfg::NestStep<'d>],
) -> Result<(Coll<'d>, IntValue<'ctx>), LoweringError> {
    let o = op(cx);
    let i64t = cx.ctx.i64_type();
    let index_of_var = |var: &sv_lang::Symbol<'d>| -> Result<IntValue<'ctx>, LoweringError> {
        let &(ptr, width, signed) = cx
            .locals
            .get(&var.uid())
            .ok_or_else(|| LoweringError::unsupported_at("foreach index has no frame slot", var))?;
        let v =
            cx.b.build_load(o.packed_type(width, cx.repr), ptr, "nest_idx")
                .unwrap()
                .into_int_value();
        let v = o.lane_val(PackedValue {
            llvm: v,
            width,
            repr: cx.repr,
            signed,
        });
        Ok(if signed {
            cx.b.build_int_s_extend_or_bit_cast(v, i64t, "nest_idx64")
        } else {
            cx.b.build_int_z_extend_or_bit_cast(v, i64t, "nest_idx64")
        }
        .unwrap())
    };
    let (mut c, mut h, rest) = if let Some(c) = coll_of_expr(&arr) {
        (c, handle_of(cx, arr)?, path)
    } else {
        let resolved = crate::arrays::resolve_array_ref(cx, arr)?;
        let elem = match &resolved {
            Some((_, shape)) => shape.elem,
            None => {
                // A class property or struct field: the whole array is one
                // packed value of 64-bit handle slots (`handle_offsets`).
                let mut t = arr.expr_type().ok_or_else(|| {
                    LoweringError::unsupported_at("foreach over an untyped array", &cx.fn_sym)
                })?;
                while t.is_unpacked_array() && !sv_sim_sim::state::storage::is_collection(&t) {
                    t = t.element_type().ok_or_else(|| {
                        LoweringError::unsupported_at("foreach over a non-array", &cx.fn_sym)
                    })?;
                }
                t
            }
        };
        let child = coll_of(&elem).ok_or_else(|| {
            LoweringError::unsupported_at("foreach over a non-collection", &cx.fn_sym)
        })?;
        let nfixed = path.iter().take_while(|s| s.fixed.is_some()).count();
        let mut acc = i64t.const_zero();
        for s in &path[..nfixed] {
            let (l, rr) = s.fixed.unwrap();
            let count = (i64::from(l) - i64::from(rr)).unsigned_abs() + 1;
            let idx = index_of_var(&s.var)?;
            let row_off =
                cx.b.build_int_sub(idx, i64t.const_int(l.min(rr) as u64, true), "nest_row")
                    .unwrap();
            let scaled =
                cx.b.build_int_mul(acc, i64t.const_int(count, false), "nest_scaled")
                    .unwrap();
            acc = cx.b.build_int_add(scaled, row_off, "nest_acc").unwrap();
        }
        let raw = if let Some((r, _)) = resolved {
            let row = cx.b.build_int_add(r.base, acc, "nest_rowp").unwrap();
            crate::arrays::load_raw(cx, r.backing, row, 64)?
        } else {
            let whole =
                lower_expr(cx, arr)?.into_packed("a fixed array of collections", &cx.fn_sym)?;
            let wv = o.lane_val(whole);
            let sh =
                cx.b.build_int_mul(acc, i64t.const_int(64, false), "nest_bits")
                    .unwrap();
            let sh =
                cx.b.build_int_z_extend_or_bit_cast(sh, wv.get_type(), "nest_sh")
                    .unwrap();
            let v = cx.b.build_right_shift(wv, sh, false, "nest_shr").unwrap();
            cx.b.build_int_truncate_or_bit_cast(v, i64t, "nest_raw")
                .unwrap()
        };
        let h = o.lane_val(PackedValue {
            llvm: raw,
            width: 64,
            repr: cx.repr,
            signed: false,
        });
        (child, h, &path[nfixed..])
    };
    let mut k = 0;
    while k < rest.len() {
        let s = &rest[k];
        if s.fixed.is_some() {
            return Err(LoweringError::unsupported_at(
                "foreach whose body waits over a fixed dimension that does not follow a queue, \
                 dynamic array or associative array",
                &cx.fn_sym,
            ));
        }
        // Fixed dimensions between this collection and the next one.
        let via: Vec<_> = rest[k + 1..]
            .iter()
            .map_while(|v| v.fixed.map(|(l, r)| (v.var, l, r)))
            .collect();
        // An associative array's variable holds a key, not a position.
        let (pos, key) = if c.assoc {
            (i64t.const_zero(), Some(var_value(cx, &s.var)?))
        } else {
            (index_of_var(&s.var)?, None)
        };
        (c, h) = child_coll_at(cx, &c, h, pos, key, &via)?;
        k += 1 + via.len();
    }
    Ok((c, h))
}

/// The size of the collection [`nested_handle`] reaches.
pub(crate) fn nested_size<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    arr: Expression<'d>,
    path: &[sv_sim_sim::process::cfg::NestStep<'d>],
) -> Result<IntValue<'ctx>, LoweringError> {
    let (c, h) = nested_handle(cx, arr, path)?;
    Ok(size_of_handle(cx, &c, h))
}

/// The current value of `foreach` loop variable `var` (a process local).
fn var_value<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    var: &sv_lang::Symbol<'d>,
) -> Result<PackedValue<'ctx>, LoweringError> {
    let &(ptr, width, signed) = cx
        .locals
        .get(&var.uid())
        .ok_or_else(|| LoweringError::unsupported_at("foreach index has no frame slot", var))?;
    let v =
        cx.b.build_load(op(cx).packed_type(width, cx.repr), ptr, "nest_key")
            .unwrap()
            .into_int_value();
    Ok(PackedValue {
        llvm: v,
        width,
        repr: cx.repr,
        signed,
    })
}

/// The key at position `pos` of the associative array of shape `c` (handle
/// `h`), as a value of its key type (a `foreach` loop variable).
pub(crate) fn key_at_coll<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    c: &Coll,
    h: IntValue<'ctx>,
    pos: IntValue<'ctx>,
) -> PackedValue<'ctx> {
    let key = entry_alloca(cx, op(cx).i_n(64 * c.key_words()), "coll_key_at");
    call(
        cx,
        c,
        CollOp::KeyAt,
        h,
        Args {
            index: Some(pos),
            key: Some(key),
            ..Args::default()
        },
    );
    load_key(cx, c, key)
}

/// The associative array `arr`'s first key (`next` false), or the key
/// after `cur` (`next`); `cur` when there is none.
pub(crate) fn assoc_step<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    arr: Expression<'d>,
    path: &[sv_sim_sim::process::cfg::NestStep<'d>],
    cur: PackedValue<'ctx>,
    next: bool,
) -> Result<PackedValue<'ctx>, LoweringError> {
    let (c, h) = if path.is_empty() {
        let c = coll_of_expr(&arr).ok_or_else(|| {
            LoweringError::unsupported_at("foreach over a non-collection", &cx.fn_sym)
        })?;
        (c, handle_of(cx, arr)?)
    } else {
        // An associative array nested in `arr` through the enclosing indices.
        nested_handle(cx, arr, path)?
    };
    let pv = crate::select::fit_width(&op(cx), cur, c.key_width);
    let key = words_buf(cx, c.key_words(), four_state(cx, pv), "coll_key");
    call(
        cx,
        &c,
        if next { CollOp::Next } else { CollOp::First },
        h,
        Args {
            key: Some(key),
            ..Args::default()
        },
    );
    Ok(load_key(cx, &c, key))
}

/// `%p` of the collection-typed `e`: its text (`'{1, 2}`, `'{"a":1}`).
pub(crate) fn format_pattern<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: Expression<'d>,
) -> Result<LoweredValue<'ctx>, LoweringError> {
    let c = coll_of_expr(&e)
        .ok_or_else(|| LoweringError::unsupported_at("%p of a non-collection", &cx.fn_sym))?;
    let h = handle_of(cx, e)?;
    format_handle(cx, &c, h)
}

/// [`format_pattern`] of the collection `h` of shape `c` (a struct field's).
pub(crate) fn format_handle<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    c: &Coll,
    h: IntValue<'ctx>,
) -> Result<LoweredValue<'ctx>, LoweringError> {
    let i64t = cx.ctx.i64_type();
    // An element that is itself a collection, struct, fixed array or class
    // handle: printed by the runtime from a type descriptor.
    if !(c.elem.is_integral() || c.elem.is_string() || c.elem.is_floating())
        || enum_desc_ok(&c.elem)
    {
        let mut desc = String::new();
        type_descriptor(cx, &c.elem, &mut desc)?;
        let desc = crate::process_lower::build_c_string_global(cx.ctx, cx.module, &desc, "pfmt_ty");
        let id = call(
            cx,
            c,
            CollOp::Format,
            h,
            Args {
                index: Some(i64t.const_int(u64::from(c.width), false)),
                val: Some(desc),
                ..Args::default()
            },
        );
        return Ok(LoweredValue::Str(crate::strings::StrValue { llvm: id }));
    }
    let mut flags = u64::from(c.elem.is_signed());
    if c.elem.is_string() {
        flags |= 2;
    } else if c.elem.is_floating() {
        flags |= if c.elem.bit_width() == 32 { 8 } else { 4 };
    }
    let id = call(
        cx,
        c,
        CollOp::Format,
        h,
        Args {
            index: Some(i64t.const_int(u64::from(c.width), false)),
            index2: Some(i64t.const_int(flags, false)),
            ..Args::default()
        },
    );
    Ok(LoweredValue::Str(crate::strings::StrValue { llvm: id }))
}

/// Whether `ty` is an enum that `%p` prints by member name through a
/// run-time descriptor (at most 32 bits, so the element is one word).
pub(crate) fn enum_desc_ok(ty: &Type<'_>) -> bool {
    ty.is_enum() && ty.value_width() <= 32
}

/// Appends to `out` the run-time `%p` descriptor of type `ty` (grammar: the
/// runtime's `Desc`): how a nested collection, struct or fixed array element
/// is split into its leaves when printed.
fn type_descriptor(
    cx: &LowerCtx<'_, '_, '_>,
    ty: &Type<'_>,
    out: &mut String,
) -> Result<(), LoweringError> {
    use std::fmt::Write;
    use sv_sim_sim::state::storage;
    let bad = |what: &str| {
        LoweringError::unsupported_at(&format!("%p of a collection element: {what}"), &cx.fn_sym)
    };
    if let Some(c) = coll_of(ty) {
        let _ = write!(out, "q{};{};", u32::from(c.assoc), c.width);
        return type_descriptor(cx, &c.elem, out);
    }
    if ty.is_class() {
        let _ = write!(out, "c{};", ty.as_symbol().name());
    } else if ty.is_string() {
        out.push('s');
    } else if ty.is_floating() {
        out.push(if ty.bit_width() == 32 { 'f' } else { 'r' });
    } else if enum_desc_ok(ty) {
        let w = ty.value_width();
        let mask = (1u64 << w) - 1;
        let members: Vec<_> = ty.enum_members().collect();
        let _ = write!(out, "e{w};{};{};", u32::from(ty.is_signed()), members.len());
        for m in &members {
            let cv = m.constant_value();
            let v = cv
                .as_ref()
                .and_then(|c| c.as_integer())
                .and_then(|i| i.as_i64())
                .ok_or_else(|| bad("an enum member with no constant value"))?;
            let _ = write!(out, "{};{};", m.name(), (v as u64) & mask);
        }
    } else if ty.is_integral() {
        let _ = write!(out, "i{};{};", ty.bit_width(), u32::from(ty.is_signed()));
    } else if ty.is_unpacked_union() && ty.is_tagged_union() {
        // `u<tag lo>;<tag w>;<n>;` then per member `<name>;<w>;[<desc>]`.
        let (tag_lo, tag_w) =
            storage::tagged_tag_slice(ty).ok_or_else(|| bad("a tagged union's tag"))?;
        let fields: Vec<_> = ty.fields().collect();
        let _ = write!(out, "u{tag_lo};{tag_w};{};", fields.len());
        for f in &fields {
            let fty = f.value_type().ok_or_else(|| bad("an untyped member"))?;
            if fty.is_void() {
                let _ = write!(out, "{};0;", f.name());
                continue;
            }
            let (_, w) =
                crate::select::field_window(Some(*ty), f).ok_or_else(|| bad("a member's shape"))?;
            let _ = write!(out, "{};{w};", f.name());
            type_descriptor(cx, &fty, out)?;
        }
    } else if storage::is_unpacked_aggregate(ty) {
        let fields: Vec<_> = ty.fields().collect();
        let shown = if ty.is_unpacked_union() {
            &fields[..fields.len().min(1)]
        } else {
            &fields[..]
        };
        let _ = write!(out, "t{};", shown.len());
        for f in shown {
            let (lo, w) =
                storage::field_slice(ty, f.field_index()).ok_or_else(|| bad("a field's shape"))?;
            let fty = f.value_type().ok_or_else(|| bad("an untyped field"))?;
            let _ = write!(out, "{lo};{w};{};", f.name());
            type_descriptor(cx, &fty, out)?;
        }
    } else if ty.is_unpacked_array() {
        let range = ty.fixed_unpacked_array_range();
        let elem = ty
            .element_type()
            .ok_or_else(|| bad("an array without elements"))?;
        let ew = storage::storage_width(&elem).ok_or_else(|| bad("an element's shape"))?;
        let _ = write!(
            out,
            "a{};{ew};{};",
            range.width(),
            u32::from(range.left > range.right)
        );
        type_descriptor(cx, &elem, out)?;
    } else {
        return Err(bad("an unsupported element type"));
    }
    Ok(())
}

/// The `c[i]` element of a queue or dynamic array that the assignment target
/// `lhs` writes only part of (`d[i][j]`, `q[i].f`, `d[i][3]`), or `None` when
/// `lhs` is not such a select chain (a whole element `c[i]` is
/// [`write_element`]'s).
pub(crate) fn partial_element_target<'d>(lhs: Expression<'d>) -> Option<Expression<'d>> {
    let mut cur = lhs;
    let mut first = true;
    loop {
        let kind = cur.kind();
        cur = if kind == ExpressionKind::ElementSelect || kind == ExpressionKind::RangeSelect {
            let base = cur.select_value()?;
            if kind == ExpressionKind::ElementSelect && coll_of_expr(&base).is_some() {
                return (!first).then_some(cur);
            }
            base
        } else if kind == ExpressionKind::MemberAccess {
            cur.operand()?
        } else {
            return None;
        };
        first = false;
    }
}