vj-codegen 0.1.0

//! Declared-range-aware selects and general assignment targets.
//!
//! **Select geometry.** A packed value's bits are addressed through its
//! declared range, not its physical bit numbering: `logic [8:1] v; v[1]` is
//! physical bit 0, `logic [0:7] x; x[0]` is physical bit 7, and
//! `logic [3:0][7:0] w; w[2]` is the 8-bit element at physical bits 16..23.
//! [`SelectGeom`] carries the declared `[left:right]` range and element
//! width of the value being selected from; [`select_window`] turns an
//! `ElementSelect`/`RangeSelect` into a physical bit window `(lo, width)`
//! plus an "invalid" flag (unknown or out-of-range index: LRM 1800-2023
//! §11.5.1 -- a read yields X, a write is ignored).
//!
//! **Assignment targets.** [`resolve_lvalue`] walks an lvalue expression
//! (`q[3:0]`, `w[i][7:4]`, `s.field`, `mem[i][3]`, ...) down to its storage
//! root -- a shadow `alloca` in `cx.locals` or one memory row -- accumulating
//! the bit window it addresses inside that root. [`lower_assign_to`] then
//! does the read-modify-write, and splits a concatenation target
//! (`{a, b} = v`) into one write per operand.

use crate::types::TypeWidth;
use inkwell::IntPredicate;
use inkwell::values::{IntValue, PointerValue};
use sv_lang::kinds::ExpressionKind;
use sv_sim_sim::symid::SymbolUid;

use crate::error::LoweringError;
use crate::expr::{
    LowerCtx, MemorySignalInfo, RangeSelectionKindClass, classify_range_selection_kind, lower_expr,
    require_const_i64,
};
use crate::ops::OpBuilder;
use crate::value::{PackedValue, ValueRepr};

/// The declared `[left:right]` range of a packed value, in ELEMENTS of
/// `elem_width` bits (1 for a plain vector; the element type's width for a
/// multi-dimensional packed array). `right` is the least significant
/// element.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) struct SelectGeom {
    pub left: i64,
    pub right: i64,
    pub elem_width: u32,
}

impl SelectGeom {
    pub(crate) fn elems(self) -> i64 {
        (self.left - self.right).abs() + 1
    }
    pub(crate) fn descending(self) -> bool {
        self.left >= self.right
    }
    /// Physical element position (0 = least significant) of declared
    /// element index `i`.
    pub(crate) fn pos(self, i: i64) -> i64 {
        if self.descending() {
            i - self.right
        } else {
            self.right - i
        }
    }
    /// The canonical `[width-1:0]` bit vector.
    pub(crate) fn canonical(width: u32) -> Self {
        SelectGeom {
            left: i64::from(width) - 1,
            right: 0,
            elem_width: 1,
        }
    }
}

/// The select geometry of a value of type `ty` whose lowered width is
/// `width`. Falls back to [`SelectGeom::canonical`] when the type carries no
/// usable packed range (a packed struct/union, an enum over an implicit
/// range, a type-less expression) or when the type's own shape does not
/// account for exactly `width` bits.
pub(crate) fn geom_of(ty: Option<sv_lang::Type<'_>>, width: u32) -> SelectGeom {
    let Some(ty) = ty else {
        return SelectGeom::canonical(width);
    };
    if ty.is_packed_array() {
        let r = ty.packed_array_range();
        let ew = ty
            .element_type()
            .map(|e| e.value_width())
            .unwrap_or(1)
            .max(1);
        if u64::from(r.width()) * u64::from(ew) == u64::from(width) {
            return SelectGeom {
                left: i64::from(r.left),
                right: i64::from(r.right),
                elem_width: ew,
            };
        }
    }
    // A fixed-size unpacked array held as bits (a field of an unpacked
    // struct, `sv_sim_sim::state::storage`): its lowest index is stored
    // least significant, whatever the declared direction.
    if ty.is_unpacked_array()
        && !ty.is_dynamically_sized_array()
        && let Some(elem) = ty.element_type()
        && let Some(ew) = sv_sim_sim::state::storage::storage_width(&elem)
    {
        let r = ty.fixed_unpacked_array_range();
        if u64::from(r.width()) * ew == u64::from(width) {
            return SelectGeom {
                left: i64::from(r.upper()),
                right: i64::from(r.lower()),
                elem_width: ew as u32,
            };
        }
    }
    if ty.is_integral() && !ty.is_struct() && !ty.is_union() {
        let r = ty.bit_vector_range();
        if r.width() == width {
            return SelectGeom {
                left: i64::from(r.left),
                right: i64::from(r.right),
                elem_width: 1,
            };
        }
    }
    SelectGeom::canonical(width)
}

/// A physical bit window inside a `base_width`-bit value: `lo` is a
/// `base_width`-bit offset (only meaningful when `bad` is false), `width` the
/// window's bit count, `bad` an `i1` that is true for an unknown index or a
/// window lying entirely outside the base.
///
/// A multi-bit window that straddles an edge of the base (LRM 1800-2023
/// 11.5.1: "partially out of range") is NOT `bad`: `lo` is then clamped to
/// the nearest in-range window and `edge` says how the addressed bits sit
/// relative to it.
#[derive(Clone, Copy)]
pub(crate) struct Window<'ctx> {
    pub lo: IntValue<'ctx>,
    pub width: u32,
    pub bad: IntValue<'ctx>,
    pub edge: Option<Edge<'ctx>>,
    /// Set when the addressed window is WIDER than its base (a constant
    /// part-select such as `v[LogDepth-1:0]` = `[-1:0]` on a 1-bit `v`):
    /// `lo`/`width` are then just the in-range slice.
    pub pad: Option<Pad<'ctx>>,
}

/// An oversized part-select (LRM 1800-2023 11.5.1): `total` bits are
/// addressed, of which only the `Window`'s in-range slice exists in the base;
/// the slice sits `shift` bits above the addressed window's low end. Every
/// other addressed bit reads X (0 for a 2-state base) and ignores writes.
///
/// A variable-index oversized select (`a[i +: 4]` on a 2-bit `a`) has no
/// static slice: its `Window` covers the WHOLE base (`lo` 0) and `dynamic` is
/// the signed `i64` bit position of base bit 0 within the addressed window
/// (`shift` is then unused).
#[derive(Clone, Copy)]
pub(crate) struct Pad<'ctx> {
    pub total: u32,
    pub shift: u32,
    pub dynamic: Option<IntValue<'ctx>>,
}

/// How a window that straddles the edge of its base relates to the in-range
/// window at its (clamped) `lo`: addressed bit `k` is base bit
/// `lo + delta + k`, and only the bits set in `valid` are inside the base.
#[derive(Clone, Copy)]
pub(crate) struct Edge<'ctx> {
    /// Signed `i64` bit distance from the clamped `lo` to the addressed
    /// window's first bit (negative when it hangs off the low end).
    pub delta: IntValue<'ctx>,
    /// Mask (window width) of the addressed bits that lie inside the base.
    pub valid: IntValue<'ctx>,
}

/// `x` shifted by the non-negative `i64` amount `amt` (left or right), zero
/// when `amt` reaches `x`'s width (LLVM leaves such a shift undefined).
fn shift_by<'ctx>(
    op: &OpBuilder<'_, 'ctx>,
    x: IntValue<'ctx>,
    amt: IntValue<'ctx>,
    left: bool,
) -> IntValue<'ctx> {
    let ty = x.get_type();
    let i64t = op.ctx.i64_type();
    let over =
        op.b.build_int_compare(
            IntPredicate::UGE,
            amt,
            i64t.const_int(u64::from(ty.get_bit_width()), false),
            "edge_over",
        )
        .unwrap();
    let safe =
        op.b.build_select(over, i64t.const_zero(), amt, "edge_amt")
            .unwrap()
            .into_int_value();
    let amt_n =
        op.b.build_int_cast_sign_flag(safe, ty, false, "edge_amt_n")
            .unwrap();
    let shifted = if left {
        op.b.build_left_shift(x, amt_n, "edge_shl").unwrap()
    } else {
        op.b.build_right_shift(x, amt_n, false, "edge_shr").unwrap()
    };
    op.b.build_select(over, ty.const_zero(), shifted, "edge_sh")
        .unwrap()
        .into_int_value()
}

/// `x << d` for a signed `i64` `d >= 0`, `x >> -d` for `d < 0` (the opposite
/// when `left_when_positive` is false).
fn shift_signed<'ctx>(
    op: &OpBuilder<'_, 'ctx>,
    x: IntValue<'ctx>,
    d: IntValue<'ctx>,
    left_when_positive: bool,
) -> IntValue<'ctx> {
    let i64t = op.ctx.i64_type();
    let neg =
        op.b.build_int_compare(IntPredicate::SLT, d, i64t.const_zero(), "edge_neg")
            .unwrap();
    let flipped = op.b.build_int_neg(d, "edge_mag").unwrap();
    let mag =
        op.b.build_select(neg, flipped, d, "edge_abs")
            .unwrap()
            .into_int_value();
    let pos_way = shift_by(op, x, mag, left_when_positive);
    let neg_way = shift_by(op, x, mag, !left_when_positive);
    op.b.build_select(neg, neg_way, pos_way, "edge_dir")
        .unwrap()
        .into_int_value()
}

/// The mask (`n` bits) of the bits of an `n`-bit window whose first bit sits
/// at signed bit `start` of a `base_width`-bit value that lie inside it.
fn range_mask<'ctx>(
    op: &OpBuilder<'_, 'ctx>,
    start: IntValue<'ctx>,
    n: u32,
    base_width: u32,
) -> IntValue<'ctx> {
    let i64t = op.ctx.i64_type();
    let zero = i64t.const_zero();
    let missing_lo = {
        let neg = op.b.build_int_neg(start, "edge_miss_lo").unwrap();
        let below =
            op.b.build_int_compare(IntPredicate::SLT, start, zero, "edge_below")
                .unwrap();
        op.b.build_select(below, neg, zero, "edge_lo_n")
            .unwrap()
            .into_int_value()
    };
    let missing_hi = {
        let end =
            op.b.build_int_add(start, i64t.const_int(u64::from(n), false), "edge_end")
                .unwrap();
        let over =
            op.b.build_int_sub(
                end,
                i64t.const_int(u64::from(base_width), false),
                "edge_miss_hi",
            )
            .unwrap();
        let above =
            op.b.build_int_compare(
                IntPredicate::SGT,
                end,
                i64t.const_int(u64::from(base_width), false),
                "edge_above",
            )
            .unwrap();
        op.b.build_select(above, over, zero, "edge_hi_n")
            .unwrap()
            .into_int_value()
    };
    let ones = op.i_n(n).const_all_ones();
    op.and(
        shift_by(op, ones, missing_lo, true),
        shift_by(op, ones, missing_hi, false),
    )
}

/// The [`Edge`] of an `n`-bit window whose first addressed bit sits at the
/// signed `i64` bit `start` of a `base_width`-bit value, read through the
/// clamped in-range offset `lo` (an `i64`).
fn make_edge<'ctx>(
    op: &OpBuilder<'_, 'ctx>,
    lo: IntValue<'ctx>,
    start: IntValue<'ctx>,
    n: u32,
    base_width: u32,
) -> Edge<'ctx> {
    Edge {
        delta: op.b.build_int_sub(start, lo, "edge_delta").unwrap(),
        valid: range_mask(op, start, n, base_width),
    }
}

/// The window an `ElementSelect`/`RangeSelect` expression `e` addresses
/// inside a `base_width`-bit value with geometry `geom`.
pub(crate) fn select_window<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: sv_lang::Expression<'d>,
    base_width: u32,
    geom: SelectGeom,
) -> Result<Window<'ctx>, LoweringError> {
    let op = OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    match e.kind() {
        ExpressionKind::ElementSelect => {
            let idx_expr = e.selector().ok_or_else(|| {
                LoweringError::unsupported_at("bit-select missing index", &cx.fn_sym)
            })?;
            let idx = lower_expr(cx, idx_expr)?.into_packed(
                "bit-select index must itself lower to an integral value",
                &cx.fn_sym,
            )?;
            Ok(dynamic_window(&op, idx, 0, 1, geom, base_width))
        }
        ExpressionKind::RangeSelect => {
            let kind_ord = e.range_selection_kind().ok_or_else(|| {
                LoweringError::unsupported_at(
                    "part-select missing range_selection_kind",
                    &cx.fn_sym,
                )
            })?;
            let kind = classify_range_selection_kind(kind_ord)
                .map_err(|msg| LoweringError::unsupported_at(&msg, &cx.fn_sym))?;
            let left_expr = e.range_left().ok_or_else(|| {
                LoweringError::unsupported_at("part-select missing left bound", &cx.fn_sym)
            })?;
            let right_expr = e.range_right().ok_or_else(|| {
                LoweringError::unsupported_at("part-select missing right bound", &cx.fn_sym)
            })?;
            match kind {
                RangeSelectionKindClass::Simple => {
                    let l = require_const_i64(
                        left_expr,
                        "simple part-select left bound must be a compile-time constant",
                        &cx.fn_sym,
                    )?;
                    let r = require_const_i64(
                        right_expr,
                        "simple part-select right bound must be a compile-time constant",
                        &cx.fn_sym,
                    )?;
                    // A one-element base has no direction of its own: an
                    // ascending select (`[-1:0]`, slang accepts it on a
                    // `[0:0]` vector) puts its left index at the most
                    // significant end of the result.
                    let (pl, pr) = if geom.elems() == 1 && l < r {
                        (geom.right - l, geom.right - r)
                    } else {
                        (geom.pos(l), geom.pos(r))
                    };
                    let (lo_e, hi_e) = (pl.min(pr), pl.max(pr));
                    let count = hi_e - lo_e + 1;
                    let ew = i64::from(geom.elem_width);
                    if count > 0 && count.saturating_mul(ew) > i64::from(base_width) {
                        return oversize_window(cx, &op, lo_e, hi_e, geom, base_width);
                    }
                    let width = checked_window_width(cx, count, geom, base_width)?;
                    let in_range = lo_e >= 0 && hi_e < geom.elems();
                    // Entirely outside the base reads X / writes nothing;
                    // straddling an edge keeps the in-range bits (LRM 11.5.1).
                    let fully_out = hi_e < 0 || lo_e >= geom.elems();
                    if !in_range && !fully_out {
                        let i64t = cx.ctx.i64_type();
                        let clamped = lo_e.clamp(0, geom.elems() - count);
                        let lo = i64t.const_int((clamped * ew) as u64, true);
                        let start = i64t.const_int((lo_e * ew) as u64, true);
                        return Ok(Window {
                            lo: op.i_n(base_width).const_int((clamped * ew) as u64, false),
                            width,
                            bad: cx.ctx.bool_type().const_zero(),
                            edge: Some(make_edge(&op, lo, start, width, base_width)),
                            pad: None,
                        });
                    }
                    let lo_bits = if in_range { (lo_e * ew) as u64 } else { 0 };
                    Ok(Window {
                        lo: op.i_n(base_width).const_int(lo_bits, false),
                        width,
                        bad: cx.ctx.bool_type().const_int(u64::from(!in_range), false),
                        edge: None,
                        pad: None,
                    })
                }
                RangeSelectionKindClass::IndexedUp | RangeSelectionKindClass::IndexedDown => {
                    let count = require_const_i64(
                        right_expr,
                        "indexed part-select width must be a compile-time constant",
                        &cx.fn_sym,
                    )?;
                    if count <= 0 {
                        return Err(LoweringError::unsupported_at(
                            "indexed part-select with a non-positive width",
                            &cx.fn_sym,
                        ));
                    }
                    let oversize =
                        count.saturating_mul(i64::from(geom.elem_width)) > i64::from(base_width);
                    if !oversize {
                        checked_window_width(cx, count, geom, base_width)?;
                    }
                    let idx = lower_expr(cx, left_expr)?.into_packed(
                        "indexed part-select base must itself lower to an integral value",
                        &cx.fn_sym,
                    )?;
                    // `[b +: n]` covers indices b..b+n-1, `[b -: n]` covers
                    // b-n+1..b; the window's physical low end is whichever
                    // of those indices sits at the least significant end.
                    let up = kind == RangeSelectionKindClass::IndexedUp;
                    let low_delta = match (up, geom.descending()) {
                        (true, true) | (false, false) => 0,
                        (true, false) => count - 1,
                        (false, true) => -(count - 1),
                    };
                    if oversize {
                        return dynamic_oversize_window(
                            cx, &op, idx, low_delta, count, geom, base_width,
                        );
                    }
                    Ok(dynamic_window(&op, idx, low_delta, count, geom, base_width))
                }
            }
        }
        other => Err(LoweringError::unsupported_at(
            &format!("select_window called on a {other:?} expression"),
            &cx.fn_sym,
        )),
    }
}

/// The constant bit window `(lo, width)` that `e` -- a named value, or a chain
/// of element/part-selects with constant indices over one -- addresses inside
/// the named value's `base_width` bits, using the declared ranges at every
/// level exactly as [`select_window`] does (an element of a multi-dimensional
/// packed array is its whole element, a `[7:4]` vector is offset by 4).
/// `Err` names why the select is not a constant, in-range window.
pub fn constant_window(e: sv_lang::Expression<'_>, base_width: u32) -> Result<(u32, u32), String> {
    constant_window_skip(e, base_width, 0)
}

/// [`constant_window`] with the `skip` innermost selects (those applied
/// directly to the named value) treated as already resolved: `base_width` is
/// the width of THEIR result, not of the named value. An unpacked-array
/// net's element select is skipped this way to address bits inside the row.
pub fn constant_window_skip(
    e: sv_lang::Expression<'_>,
    base_width: u32,
    skip: usize,
) -> Result<(u32, u32), String> {
    fn depth(e: sv_lang::Expression<'_>) -> usize {
        match (e.kind(), e.select_value()) {
            (ExpressionKind::ElementSelect | ExpressionKind::RangeSelect, Some(b)) => 1 + depth(b),
            _ => 0,
        }
    }
    fn go(e: sv_lang::Expression<'_>, base_width: u32, skip: usize) -> Result<(u32, u32), String> {
        let kind = e.kind();
        if kind != ExpressionKind::ElementSelect && kind != ExpressionKind::RangeSelect {
            return Ok((0, base_width));
        }
        let base = e.select_value().ok_or("a select with no base value")?;
        // This select's own height above the named value
        // must exceed `skip` for it to be applied.
        if depth(e) <= skip {
            return Ok((0, base_width));
        }
        let (base_lo, base_bits) = go(base, base_width, skip)?;
        step(e, base, base_lo, base_bits)
    }
    go(e, base_width, skip)
}

fn step(
    e: sv_lang::Expression<'_>,
    base: sv_lang::Expression<'_>,
    base_lo: u32,
    base_bits: u32,
) -> Result<(u32, u32), String> {
    let kind = e.kind();
    let geom = geom_of(base.expr_type(), base_bits);
    let constant = |x: Option<sv_lang::Expression<'_>>, what: &str| -> Result<i64, String> {
        x.and_then(|x| x.constant_value())
            .and_then(|c| c.as_i64())
            .ok_or_else(|| format!("{what} is not a compile-time constant"))
    };
    // (least significant physical element, element count)
    let (pos, count) = if kind == ExpressionKind::ElementSelect {
        (geom.pos(constant(e.selector(), "the select index")?), 1)
    } else {
        let sel = classify_range_selection_kind(
            e.range_selection_kind()
                .ok_or("a part-select with no kind")?,
        )?;
        let left = constant(e.range_left(), "the part-select's left bound")?;
        let right = constant(e.range_right(), "the part-select's right bound")?;
        match sel {
            RangeSelectionKindClass::Simple => {
                let (pl, pr) = (geom.pos(left), geom.pos(right));
                (pl.min(pr), (pl - pr).abs() + 1)
            }
            RangeSelectionKindClass::IndexedUp | RangeSelectionKindClass::IndexedDown => {
                if right <= 0 {
                    return Err("an indexed part-select with a non-positive width".into());
                }
                let (a, b) = if sel == RangeSelectionKindClass::IndexedUp {
                    (left, left + right - 1)
                } else {
                    (left - right + 1, left)
                };
                (geom.pos(a).min(geom.pos(b)), right)
            }
        }
    };
    if pos < 0 || pos + count > geom.elems() {
        return Err("the select is outside the value's declared range".into());
    }
    let ew = u64::from(geom.elem_width);
    let lo = u64::from(base_lo) + pos as u64 * ew;
    Ok((lo as u32, (count as u64 * ew) as u32))
}

/// The window of a constant simple part-select `[lo_e..=hi_e]` (physical
/// element positions) that addresses MORE bits than its base holds: only the
/// in-range slice is read or written (LRM 11.5.1).
fn oversize_window<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    op: &OpBuilder<'_, 'ctx>,
    lo_e: i64,
    hi_e: i64,
    geom: SelectGeom,
    base_width: u32,
) -> Result<Window<'ctx>, LoweringError> {
    let ew = i64::from(geom.elem_width);
    let total = (hi_e - lo_e + 1).saturating_mul(ew);
    let total = u32::try_from(total).map_err(|_| {
        LoweringError::unsupported_at("part-select addressing more than 2^32 bits", &cx.fn_sym)
    })?;
    let (in_lo, in_hi) = (lo_e.max(0), hi_e.min(geom.elems() - 1));
    let fully_out = in_lo > in_hi;
    let (lo_bits, width, shift) = if fully_out {
        (0, 1, 0)
    } else {
        (
            in_lo * ew,
            ((in_hi - in_lo + 1) * ew) as u32,
            ((in_lo - lo_e) * ew) as u32,
        )
    };
    Ok(Window {
        lo: op.i_n(base_width).const_int(lo_bits as u64, false),
        width,
        bad: cx.ctx.bool_type().const_int(u64::from(fully_out), false),
        edge: None,
        pad: Some(Pad {
            total,
            shift,
            dynamic: None,
        }),
    })
}

/// The window of an indexed part-select `[i +: n]` / `[i -: n]` with a
/// variable `i` that addresses MORE bits than its base holds (LRM 1800-2023
/// 11.5.1): the window covers the whole base, positioned at runtime inside
/// the addressed `n * elem_width` bits ([`Pad::dynamic`]); the bits outside
/// the base read X and ignore writes, and an unknown `i` or a select that
/// misses the base entirely is `bad` (all X / no write).
fn dynamic_oversize_window<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    op: &OpBuilder<'_, 'ctx>,
    idx: PackedValue<'ctx>,
    low_delta: i64,
    count: i64,
    geom: SelectGeom,
    base_width: u32,
) -> Result<Window<'ctx>, LoweringError> {
    let total = u32::try_from(count.saturating_mul(i64::from(geom.elem_width))).map_err(|_| {
        LoweringError::unsupported_at("part-select addressing more than 2^32 bits", &cx.fn_sym)
    })?;
    // Same widening as `dynamic_window`: nothing below can overflow.
    let cw = idx.width.max(64) + 2;
    let cty = op.i_n(cw);
    let val = op.lane_val(idx);
    let ext = if idx.width == cw {
        val
    } else if idx.signed {
        op.b.build_int_s_extend(val, cty, "sel_idx_sext").unwrap()
    } else {
        op.b.build_int_z_extend(val, cty, "sel_idx_zext").unwrap()
    };
    let c = |v: i64| cty.const_int(v as u64, true);
    let low =
        op.b.build_int_add(ext, c(low_delta), "sel_low_index")
            .unwrap();
    // Position of the window's low element relative to the base's.
    let pos = if geom.descending() {
        op.b.build_int_sub(low, c(geom.right), "sel_pos").unwrap()
    } else {
        op.b.build_int_sub(c(geom.right), low, "sel_pos").unwrap()
    };
    let before =
        op.b.build_int_compare(IntPredicate::SLE, pos, c(-count), "sel_before")
            .unwrap();
    let past =
        op.b.build_int_compare(IntPredicate::SGE, pos, c(geom.elems()), "sel_past")
            .unwrap();
    let unk = op.lane_unk(idx);
    let unknown =
        op.b.build_int_compare(
            IntPredicate::NE,
            unk,
            unk.get_type().const_zero(),
            "sel_idx_unknown",
        )
        .unwrap();
    let missed = op.b.build_or(before, past, "sel_fully_out").unwrap();
    let bad = op.b.build_or(missed, unknown, "sel_bad").unwrap();
    // Base bit 0 sits at addressed bit `-pos * elem_width`; `pos` is within
    // (-count, elems) unless `bad`, so it fits an i64 after the select.
    let ew = c(i64::from(geom.elem_width));
    let shift = op.b.build_int_mul(pos, ew, "sel_start_bits").unwrap();
    let shift = op.b.build_int_neg(shift, "sel_pad_shift").unwrap();
    let shift =
        op.b.build_select(bad, c(0), shift, "sel_shift_safe")
            .unwrap()
            .into_int_value();
    let shift =
        op.b.build_int_cast_sign_flag(shift, cx.ctx.i64_type(), true, "sel_shift64")
            .unwrap();
    Ok(Window {
        lo: op.i_n(base_width).const_zero(),
        width: base_width,
        bad,
        edge: None,
        pad: Some(Pad {
            total,
            shift: 0,
            dynamic: Some(shift),
        }),
    })
}

pub(crate) fn checked_window_width(
    cx: &LowerCtx<'_, '_, '_>,
    count: i64,
    geom: SelectGeom,
    base_width: u32,
) -> Result<u32, LoweringError> {
    let bits = count as u64 * u64::from(geom.elem_width);
    if count <= 0 || bits > u64::from(base_width) {
        return Err(LoweringError::unsupported_at(
            "part-select wider than the value it selects from",
            &cx.fn_sym,
        ));
    }
    Ok(bits as u32)
}

/// The window of `count` elements whose least significant element has
/// declared index `idx + low_delta`.
fn dynamic_window<'ctx>(
    op: &OpBuilder<'_, 'ctx>,
    idx: PackedValue<'ctx>,
    low_delta: i64,
    count: i64,
    geom: SelectGeom,
    base_width: u32,
) -> Window<'ctx> {
    // Wide enough that the index (at its own signedness), the declared
    // bounds (i32) and the element scaling can never overflow.
    let cw = idx.width.max(64) + 2;
    let cty = op.i_n(cw);
    let val = op.lane_val(idx);
    let ext = if idx.width == cw {
        val
    } else if idx.signed {
        op.b.build_int_s_extend(val, cty, "sel_idx_sext").unwrap()
    } else {
        op.b.build_int_z_extend(val, cty, "sel_idx_zext").unwrap()
    };
    let c = |v: i64| cty.const_int(v as u64, true);
    let low =
        op.b.build_int_add(ext, c(low_delta), "sel_low_index")
            .unwrap();
    let pos = if geom.descending() {
        op.b.build_int_sub(low, c(geom.right), "sel_pos").unwrap()
    } else {
        op.b.build_int_sub(c(geom.right), low, "sel_pos").unwrap()
    };
    let below =
        op.b.build_int_compare(IntPredicate::SLT, pos, c(0), "sel_below")
            .unwrap();
    let above =
        op.b.build_int_compare(IntPredicate::SGT, pos, c(geom.elems() - count), "sel_above")
            .unwrap();
    let unk = op.lane_unk(idx);
    let unknown =
        op.b.build_int_compare(
            IntPredicate::NE,
            unk,
            unk.get_type().const_zero(),
            "sel_idx_unknown",
        )
        .unwrap();
    let width = (count as u32) * geom.elem_width;
    let ew = c(i64::from(geom.elem_width));
    // A single element is either in or out; a wider window may straddle an
    // edge, and then reads/writes just the bits that are in range.
    let edge_possible = count > 1;
    let oob = op.b.build_or(below, above, "sel_oob").unwrap();
    let fully_out = if edge_possible {
        let before =
            op.b.build_int_compare(IntPredicate::SLT, pos, c(1 - count), "sel_before")
                .unwrap();
        let past =
            op.b.build_int_compare(IntPredicate::SGE, pos, c(geom.elems()), "sel_past")
                .unwrap();
        op.b.build_or(before, past, "sel_fully_out").unwrap()
    } else {
        oob
    };
    let bad = op.b.build_or(fully_out, unknown, "sel_bad").unwrap();
    // The clamped (in-range) window position, in elements.
    let clamped = if edge_possible {
        let capped =
            op.b.build_select(above, c(geom.elems() - count), pos, "sel_cap")
                .unwrap()
                .into_int_value();
        op.b.build_select(below, c(0), capped, "sel_clamp")
            .unwrap()
            .into_int_value()
    } else {
        pos
    };
    let lo_c = op.b.build_int_mul(clamped, ew, "sel_lo_bits").unwrap();
    let lo_c =
        op.b.build_select(bad, c(0), lo_c, "sel_lo_safe")
            .unwrap()
            .into_int_value();
    // `lo_c` is nonnegative here; a base wider than it needs a zero
    // extension, not a (invalid, wider) truncation.
    let lo =
        op.b.build_int_cast_sign_flag(lo_c, op.i_n(base_width), false, "sel_lo")
            .unwrap();
    let edge = edge_possible.then(|| {
        let i64t = op.ctx.i64_type();
        let start = op.b.build_int_mul(pos, ew, "sel_start_bits").unwrap();
        let start =
            op.b.build_select(bad, c(0), start, "sel_start_safe")
                .unwrap()
                .into_int_value();
        let start64 =
            op.b.build_int_cast_sign_flag(start, i64t, true, "sel_start64")
                .unwrap();
        let lo64 =
            op.b.build_int_cast_sign_flag(lo_c, i64t, true, "sel_lo64")
                .unwrap();
        make_edge(op, lo64, start64, width, base_width)
    });
    Window {
        lo,
        width,
        bad,
        edge,
        pad: None,
    }
}

/// A select of a 2-state operand is itself 2-state: an out-of-range or
/// unknown-index read yields 0, not X (LRM 11.5.1). The window read marks
/// those bits X in the unknown lane of a 4-state-stored value; clear it when
/// the select expression's type has no X.
pub(crate) fn two_state_result<'ctx>(
    op: &OpBuilder<'_, 'ctx>,
    e: sv_lang::Expression<'_>,
    v: PackedValue<'ctx>,
) -> PackedValue<'ctx> {
    if v.repr == ValueRepr::TwoState || e.expr_type().is_none_or(|t| t.is_four_state()) {
        return v;
    }
    op.pack(
        op.lane_val(v),
        op.i_n(v.width).const_zero(),
        v.width,
        v.repr,
        v.signed,
    )
}

/// Reads `window` out of `base` (all X / 0 when the window is invalid; a
/// window straddling an edge of `base` keeps its in-range bits and reads X /
/// 0 for the rest).
pub(crate) fn read_window<'ctx>(
    op: &OpBuilder<'_, 'ctx>,
    base: PackedValue<'ctx>,
    window: Window<'ctx>,
) -> PackedValue<'ctx> {
    let core = op.part_select4(base, window.lo, window.bad, window.width);
    if let Some(pad) = window.pad {
        return pad_read(op, core, window.bad, pad, base.repr);
    }
    let Some(edge) = window.edge else {
        return core;
    };
    let v = shift_signed(op, op.lane_val(core), edge.delta, false);
    let u = shift_signed(op, op.lane_unk(core), edge.delta, false);
    let outside = op.not(edge.valid);
    let v = op.and(v, edge.valid);
    // A 2-state value has no X: its out-of-range bits read 0.
    let u = op.or(op.and(u, edge.valid), outside);
    let shifted = op.pack(v, u, window.width, base.repr, core.signed);
    op.select(
        window.bad,
        op.pack(
            op.i_n(window.width).const_zero(),
            op.i_n(window.width).const_all_ones(),
            window.width,
            base.repr,
            core.signed,
        ),
        shifted,
    )
}

/// The `pad.total`-bit value of an oversized window whose in-range slice is
/// `core`: the slice at `pad.shift`, X everywhere else (all X when `bad`).
fn pad_read<'ctx>(
    op: &OpBuilder<'_, 'ctx>,
    core: PackedValue<'ctx>,
    bad: IntValue<'ctx>,
    pad: Pad<'ctx>,
    repr: ValueRepr,
) -> PackedValue<'ctx> {
    let ty = op.i_n(pad.total);
    let at = ty.const_int(u64::from(pad.shift), false);
    let place = |lane: IntValue<'ctx>| {
        let wide = op.b.build_int_z_extend(lane, ty, "pad_ext").unwrap();
        match pad.dynamic {
            Some(d) => shift_signed(op, wide, d, true),
            None => op.b.build_left_shift(wide, at, "pad_shl").unwrap(),
        }
    };
    let slice = op.i_n(core.width).const_all_ones();
    let inside = place(slice);
    let v = place(op.lane_val(core));
    let u = op.or(place(op.lane_unk(core)), op.not(inside));
    let shifted = op.pack(v, u, pad.total, repr, core.signed);
    op.select(
        bad,
        op.pack(
            ty.const_zero(),
            ty.const_all_ones(),
            pad.total,
            repr,
            core.signed,
        ),
        shifted,
    )
}

/// What a write of `value` through `lv` must store into the clamped window
/// at `lv.lo`: for a window straddling an edge, `value` moved into place
/// and merged with `current` (the window's present contents) so that only
/// the in-range bits change; otherwise `value` unchanged.
fn merge_edge<'ctx>(
    op: &OpBuilder<'_, 'ctx>,
    current: PackedValue<'ctx>,
    edge: Option<Edge<'ctx>>,
    value: PackedValue<'ctx>,
) -> PackedValue<'ctx> {
    let Some(edge) = edge else {
        return value;
    };
    let (placed, mask) = edge_place(op, value, edge);
    let keep = op.not(mask);
    let v = op.or(op.and(op.lane_val(current), keep), op.lane_val(placed));
    let u = op.or(op.and(op.lane_unk(current), keep), op.lane_unk(placed));
    op.pack(v, u, value.width, value.repr, value.signed)
}

/// `value` shifted from the addressed window's coordinates into the clamped
/// window's, with every bit outside the base cleared, and the mask of the
/// bits it may change.
fn edge_place<'ctx>(
    op: &OpBuilder<'_, 'ctx>,
    value: PackedValue<'ctx>,
    edge: Edge<'ctx>,
) -> (PackedValue<'ctx>, IntValue<'ctx>) {
    let mask = shift_signed(op, edge.valid, edge.delta, true);
    let v = op.and(shift_signed(op, op.lane_val(value), edge.delta, true), mask);
    let u = op.and(shift_signed(op, op.lane_unk(value), edge.delta, true), mask);
    (op.pack(v, u, value.width, value.repr, value.signed), mask)
}

/// Where an assignment target's bits live.
#[derive(Clone, Copy)]
pub(crate) enum LvalueRoot<'ctx> {
    /// A local or primed external signal: its shadow `alloca`.
    Shadow { ptr: PointerValue<'ctx> },
    /// One row of a memory. `row` is only valid when the lvalue's `bad` is
    /// false (`mem_row_index`'s `valid` is folded into it).
    MemRow {
        info: MemorySignalInfo,
        row: IntValue<'ctx>,
    },
    /// A module-level signal's STATE slot itself (a nonblocking write's
    /// target: it is staged against the signal, never its shadow copy).
    Signal { slot: u32 },
    /// A class property (ledger XC-059): the object `h`'s field `slot`, one
    /// flat value read and written whole through the object heap. A write
    /// into part of it (`obj.a[i]`, `obj.s.f`, `obj.v[3:0]`) is a
    /// read-modify-write of that value.
    Field {
        h: IntValue<'ctx>,
        slot: sv_sim_sim::objects::FieldSlot,
    },
}

/// How [`resolve_lvalue`] resolves a plain name at the root of a target.
#[derive(Clone, Copy)]
pub(crate) enum RootMode<'a> {
    /// Blocking write: the name's shadow `alloca` in `cx.locals`.
    Shadow,
    /// Nonblocking write: the module-level signal itself.
    Signal(
        &'a std::collections::HashMap<
            sv_sim_sim::symid::SymbolId,
            crate::process_lower::SignalSlot,
        >,
    ),
}

/// A resolved assignment target: `width` bits at physical offset `lo`
/// (a `root_width`-bit value) of `root`, suppressed when `bad` is true.
#[derive(Clone, Copy)]
pub(crate) struct Lvalue<'ctx> {
    pub root: LvalueRoot<'ctx>,
    pub root_width: u32,
    pub root_signed: bool,
    pub lo: IntValue<'ctx>,
    pub width: u32,
    pub bad: IntValue<'ctx>,
    /// Set when the target straddles an edge of its root: `lo` is the
    /// clamped in-range window and only the bits in `valid` are written.
    pub edge: Option<Edge<'ctx>>,
    /// An oversized constant part-select target: see [`Pad`]. `width` is the
    /// in-range slice; the value assigned is `pad.total` bits.
    pub pad: Option<Pad<'ctx>>,
}

/// Resolves a non-concatenation lvalue expression to its storage root and
/// bit window; `mode` picks what a plain name at the root means.
pub(crate) fn resolve_lvalue<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: sv_lang::Expression<'d>,
    mode: RootMode<'_>,
) -> Result<Lvalue<'ctx>, LoweringError> {
    let op = OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    let no = cx.ctx.bool_type().const_zero();
    // A modport port with an expression (`output .z(lo)`, LRM 25.5.4) writes
    // that expression of the interface instance.
    if let Some(inner) = crate::expr::modport_expr_target(&e) {
        return resolve_lvalue(cx, inner, mode);
    }
    // A class property (named by `obj.f`, a bare `f` in a method, or as a
    // static): the root of everything written into it.
    if let Some((h, slot, ty)) = crate::classes::class_field_root(cx, e)? {
        let width = ty.value_width();
        return Ok(Lvalue {
            root: LvalueRoot::Field { h, slot },
            root_width: width,
            root_signed: ty.is_signed(),
            lo: op.i_n(width).const_zero(),
            width,
            bad: no,
            edge: None,
            pad: None,
        });
    }
    // `vif.m` at the root of a nested target, for the candidate being
    // resolved (`crate::vif::nested_lvalues`).
    if let Some(r) = crate::vif::picked_lvalue(cx, e, mode) {
        return r;
    }
    match e.kind() {
        ExpressionKind::NamedValue | ExpressionKind::HierarchicalValue => {
            let sym = e.referenced_symbol().ok_or_else(|| {
                LoweringError::unsupported_at("assignment lvalue unresolved name", &cx.fn_sym)
            })?;
            let (root, width, signed) = match mode {
                RootMode::Shadow => {
                    let (ptr, width, signed) = *cx.locals.get(&sym.uid()).ok_or_else(|| {
                        LoweringError::unsupported_at(
                            "assignment to a name that is neither a local nor a signal of this \
                             scope",
                            &sym,
                        )
                    })?;
                    (LvalueRoot::Shadow { ptr }, width, signed)
                }
                RootMode::Signal(signals) => {
                    // A select of an output clock variable (`cb.q[3:0] <= v`,
                    // LRM 14.16) writes the signal the clock variable names.
                    let sym = if sym.kind() == sv_lang::kinds::SymbolKind::ClockVar {
                        sym.initializer()
                            .and_then(|i| i.referenced_symbol())
                            .unwrap_or(sym)
                    } else {
                        sym
                    };
                    let info = signals.get(&sym.uid()).copied().ok_or_else(|| {
                        LoweringError::unsupported_at(
                            "nonblocking assignment to a process-local variable (only a \
                             module-level signal has an NBA staging target)",
                            &sym,
                        )
                    })?;
                    if matches!(
                        info.class,
                        crate::process_lower::SignalSlotClass::Memory { .. }
                    ) {
                        return Err(LoweringError::unsupported_at(
                            "nonblocking assignment to a whole memory (only element writes \
                             `mem[i] <= v` are supported)",
                            &sym,
                        ));
                    }
                    // Task 4b (`docs/superpowers/plans/2026-10-03-sdf.md`):
                    // a specify-path VARIABLE destination's nonblocking
                    // write is redirected to its own staging cell instead
                    // of the signal itself, exactly mirroring Task 4a's
                    // already-existing net-destination redirect (a
                    // delayed continuous assign's `ca.net_target` writing
                    // its own staging slot instead of the net) -- `info`'s
                    // own `width`/`signed` are kept (the redirect's own
                    // staging cell is allocated with the SAME width,
                    // `sv-sim-bin::specify::plan`'s own scope restriction),
                    // only the SLOT changes.
                    let slot = cx
                        .specify_dest
                        .get(&sym.uid())
                        .map_or(info.slot, |r| r.slot);
                    (LvalueRoot::Signal { slot }, info.width, info.signed)
                }
            };
            Ok(Lvalue {
                root,
                root_width: width,
                root_signed: signed,
                lo: op.i_n(width).const_zero(),
                width,
                bad: no,
                edge: None,
                pad: None,
            })
        }
        ExpressionKind::ElementSelect | ExpressionKind::RangeSelect => {
            let base_expr = e.select_value().ok_or_else(|| {
                LoweringError::unsupported_at("select lvalue missing base value", &cx.fn_sym)
            })?;
            // An element of a queue / dynamic array being written in part
            // (`d[i][j]`, `q[i].f`, `d[i][3]`): the root is the element's
            // shadow copy, written back by `store_to_releasing`.
            if e.kind() == ExpressionKind::ElementSelect
                && let Some(c) = crate::collections::coll_of_expr(&base_expr)
            {
                let Some(ptr) = cx.coll_temp.get() else {
                    return Err(LoweringError::unsupported_at(
                        "a nonblocking or reference write into part of a queue or dynamic-array \
                         element (use a blocking assignment)",
                        &cx.fn_sym,
                    ));
                };
                return Ok(Lvalue {
                    root: LvalueRoot::Shadow { ptr },
                    root_width: c.width,
                    root_signed: c.elem.is_signed(),
                    lo: op.i_n(c.width).const_zero(),
                    width: c.width,
                    bad: no,
                    edge: None,
                    pad: None,
                });
            }
            // LRM 7.10.1 queue / 7.5 dynamic-array slice as an assignment
            // target (`q[1:2] = '{..}`): not implemented; refuse by name
            // rather than fall through to a width mismatch.
            if e.kind() == ExpressionKind::RangeSelect
                && crate::collections::coll_of_expr(&base_expr).is_some()
            {
                return Err(LoweringError::unsupported_at(
                    "a slice of a queue or dynamic array as an assignment target (assign the \
                     elements individually)",
                    &cx.fn_sym,
                ));
            }
            // An unpacked-array element (`mem[i]`, `a[i][j]`, a local
            // array's element): the root is one row.
            if e.kind() == ExpressionKind::ElementSelect
                && let Some(r) = crate::arrays::resolve_element(cx, e)?
            {
                let bad = cx.b.build_not(r.valid, "arr_lv_bad").unwrap();
                let root = match r.backing {
                    crate::arrays::Backing::Memory(info) => LvalueRoot::MemRow { info, row: r.row },
                    crate::arrays::Backing::Local(base) => LvalueRoot::Shadow {
                        ptr: crate::arrays::local_row_ptr(cx, base, r.row, r.width),
                    },
                };
                return Ok(Lvalue {
                    root,
                    root_width: r.width,
                    root_signed: r.signed,
                    lo: op.i_n(r.width).const_zero(),
                    width: r.width,
                    bad,
                    edge: None,
                    pad: None,
                });
            }
            let inner = resolve_lvalue(cx, base_expr, mode)?;
            no_pad_base(cx, &inner)?;
            let geom = geom_of(base_expr.expr_type(), inner.width);
            let w = select_window(cx, e, inner.width, geom)?;
            Ok(nest(cx, inner, w))
        }
        ExpressionKind::MemberAccess => {
            let base_expr = e.operand().ok_or_else(|| {
                LoweringError::unsupported_at("member-access lvalue missing base", &cx.fn_sym)
            })?;
            let member = e.member_symbol().ok_or_else(|| {
                LoweringError::unsupported_at("member-access lvalue missing member", &cx.fn_sym)
            })?;
            let inner = resolve_lvalue(cx, base_expr, mode)?;
            no_pad_base(cx, &inner)?;
            let Some((off, fw)) = field_window(base_expr.expr_type(), &member)
                .filter(|(off, fw)| *fw > 0 && fw + off <= u64::from(inner.width))
            else {
                return Err(LoweringError::unsupported_at(
                    "assignment to a struct/union field that is not a slice of its base's \
                     stored bits",
                    &cx.fn_sym,
                ));
            };
            // LRM 11.9: writing a member of a tagged union whose tag names a
            // different member is a run-time error; the write is dropped.
            let mut bad = no;
            if let Some(base_ty) = base_expr.expr_type().filter(sv_lang::Type::is_tagged_union) {
                // A nonblocking target has no loadable shadow root: the tag is
                // checked against the union's value as it stands when the
                // statement executes (the check cannot wait for the NBA region).
                let union_value = if matches!(mode, RootMode::Signal(_)) {
                    lower_expr(cx, base_expr)?.into_packed(
                        "a tagged union nonblocking target must read as an integral value",
                        &cx.fn_sym,
                    )?
                } else {
                    let cur = load_root(cx, &inner)?;
                    read_window(
                        &op,
                        cur,
                        Window {
                            lo: inner.lo,
                            width: inner.width,
                            bad: inner.bad,
                            edge: inner.edge,
                            pad: None,
                        },
                    )
                };
                if let Some(miss) = crate::tagged::checked_member_window(
                    cx,
                    &base_ty,
                    union_value,
                    &member,
                    inner.bad,
                    e.source_range().start,
                )? {
                    bad = miss;
                }
            }
            let w = Window {
                lo: op.i_n(inner.width).const_int(off, false),
                width: fw as u32,
                bad,
                edge: None,
                pad: None,
            };
            Ok(nest(cx, inner, w))
        }
        other => Err(LoweringError::unsupported_at(
            &format!("assignment to a {other:?} lvalue is not supported"),
            &cx.fn_sym,
        )),
    }
}

/// `(lsb, width)` of struct/union field `member` within the stored bits of
/// a base of type `base_ty`: slang's own offset in a packed base, the flat
/// stored form's (`sv_sim_sim::state::storage`) in an unpacked one, whose
/// fields may be reals, strings or aggregates themselves.
pub(crate) fn field_window(
    base_ty: Option<sv_lang::Type<'_>>,
    member: &sv_lang::Symbol<'_>,
) -> Option<(u64, u64)> {
    use sv_sim_sim::state::storage;
    let base_ty = base_ty?;
    // Classes plan Task 5 defensive guard: `obj.field` on a CLASS base is
    // never a bit-packed slice of `obj`'s own 64-bit handle value --
    // `crate::classes::{read_field,try_write_field}` are the real class-
    // property read/write path, reached before any caller of this
    // function for an ordinary instance property (`is_instance_field`).
    // A caller that still reaches here with a class base (e.g. a static
    // property accessed through instance syntax, or a bit-select into a
    // class field, neither wired yet) must get the SAME loud "not a slice
    // of its base's stored bits" rejection every caller of this function
    // already gives a `None` -- never silently reinterpret the handle's
    // own raw bits as if they were field storage, which `field_ty.
    // is_integral()` below cannot by itself tell apart from a genuine
    // packed-struct field at the same declared width.
    if base_ty.is_class() {
        return None;
    }
    if storage::is_unpacked_aggregate(&base_ty) {
        return storage::field_slice(&base_ty, member.field_index());
    }
    let field_ty = member.value_type()?;
    field_ty
        .is_integral()
        .then(|| (member.field_bit_offset(), field_ty.bit_width()))
}

/// A constant sub-range of a variable's stored form that a `ref` port
/// actual names (IEEE 1800-2023 23.3.3.2): `width` bits from bit `lo` of
/// memory row `row` when the variable is an unpacked array, of the whole
/// slot otherwise.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct RefWindow {
    pub row: Option<u64>,
    pub lo: u64,
    pub width: u64,
}

/// Why an expression cannot be bound to a `ref` port as a window.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum RefActualError {
    /// An array index that is not a constant expression: the alias would
    /// have to move while the simulation runs.
    NonConstant,
    /// A packed bit/part-select, packed member or packed element: not a
    /// legal `ref` actual (13.5.2: only variables and members of unpacked
    /// structs and arrays).
    Packed,
    /// Anything else the alias mechanism does not implement.
    Unsupported(String),
}

/// The variable a `ref` port actual `e` names and the constant window of it
/// the actual selects (`None` for the whole variable): `s.f` of an unpacked
/// struct, `a[2]` / `m[1][2]` of an unpacked array (every dimension
/// indexed), and nestings such as `sa[1].f` or `s.inner.f`.
pub fn ref_actual_window<'d>(
    e: sv_lang::Expression<'d>,
) -> Result<(sv_lang::Expression<'d>, Option<RefWindow>), RefActualError> {
    use crate::types::TypeWidth;
    match e.kind() {
        ExpressionKind::NamedValue | ExpressionKind::HierarchicalValue => Ok((e, None)),
        ExpressionKind::MemberAccess => {
            let base = e.operand().ok_or_else(|| {
                RefActualError::Unsupported("a member access with no base".to_owned())
            })?;
            let member = e.member_symbol().ok_or_else(|| {
                RefActualError::Unsupported("a member access with no member".to_owned())
            })?;
            let base_ty = base.expr_type();
            if !base_ty
                .as_ref()
                .is_some_and(sv_sim_sim::state::storage::is_unpacked_aggregate)
            {
                return Err(RefActualError::Packed);
            }
            // The member's stored bits are a slice of the struct's row, not
            // a memory of rows: an array-typed `ref` port bound to it would
            // read and write the wrong storage (LRM 23.3.3.2 allows it).
            if member.value_type().is_some_and(|t| t.is_unpacked_array()) {
                return Err(RefActualError::Unsupported(
                    "a struct member that is itself an unpacked array".to_owned(),
                ));
            }
            let (root, inner) = ref_actual_window(base)?;
            let Some((off, width)) = field_window(base_ty, &member).filter(|(_, w)| *w > 0) else {
                return Err(RefActualError::Unsupported(
                    "a struct member that is not a slice of its struct's stored bits".to_owned(),
                ));
            };
            let window = match inner {
                Some(w) => RefWindow {
                    row: w.row,
                    lo: w.lo + off,
                    width,
                },
                None => RefWindow {
                    row: None,
                    lo: off,
                    width,
                },
            };
            Ok((root, Some(window)))
        }
        ExpressionKind::ElementSelect | ExpressionKind::RangeSelect => {
            // The chain of selects down to the array variable.
            let mut chain = Vec::new();
            let mut cur = e;
            while matches!(
                cur.kind(),
                ExpressionKind::ElementSelect | ExpressionKind::RangeSelect
            ) {
                let base = cur.select_value().ok_or_else(|| {
                    RefActualError::Unsupported("a select with no base".to_owned())
                })?;
                if !base.expr_type().is_some_and(|t| t.is_unpacked_array()) {
                    return Err(RefActualError::Packed);
                }
                chain.push(cur);
                cur = base;
            }
            chain.reverse();
            if !matches!(
                cur.kind(),
                ExpressionKind::NamedValue | ExpressionKind::HierarchicalValue
            ) {
                return Err(RefActualError::Unsupported(
                    "an element of an array that is itself a member or another select".to_owned(),
                ));
            }
            let shape = cur
                .expr_type()
                .as_ref()
                .and_then(crate::arrays::array_shape)
                .ok_or_else(|| {
                    RefActualError::Unsupported("a dynamically sized array element".to_owned())
                })?;
            if chain.len() != shape.dims.len() {
                return Err(RefActualError::Unsupported(
                    "a sub-array of a multi-dimensional unpacked array (name one element)"
                        .to_owned(),
                ));
            }
            let mut row = 0u64;
            for (k, sel) in chain.iter().enumerate() {
                if sel.kind() != ExpressionKind::ElementSelect {
                    return Err(RefActualError::Unsupported(
                        "a slice of an unpacked array".to_owned(),
                    ));
                }
                let idx = sel
                    .selector()
                    .and_then(|x| x.constant_value())
                    .and_then(|c| c.as_i64())
                    .ok_or(RefActualError::NonConstant)?;
                let (a, b) = shape.dims[k];
                let low = a.min(b);
                let size = (a - b).unsigned_abs() + 1;
                let off = idx - low;
                if off < 0 || off as u64 >= size {
                    return Err(RefActualError::Unsupported(format!(
                        "index {idx} is outside the array's bounds [{a}:{b}]"
                    )));
                }
                row += off as u64 * shape.stride(k);
            }
            let elem = shape.elem;
            if !(elem.is_integral()
                || elem.is_floating()
                || sv_sim_sim::state::storage::is_unpacked_aggregate(&elem))
            {
                return Err(RefActualError::Unsupported(
                    "an array element that is a string, class, chandle or collection".to_owned(),
                ));
            }
            Ok((
                cur,
                Some(RefWindow {
                    row: Some(row),
                    lo: 0,
                    width: u64::from(elem.value_width()),
                }),
            ))
        }
        other => Err(RefActualError::Unsupported(format!(
            "a {other:?} expression is not a variable"
        ))),
    }
}

/// Composes an inner window `w` (relative to `inner`'s own window) onto
/// `inner`.
/// A select or member of an oversized part-select target is not supported.
fn no_pad_base(cx: &LowerCtx<'_, '_, '_>, inner: &Lvalue<'_>) -> Result<(), LoweringError> {
    if inner.pad.is_some() {
        return Err(LoweringError::unsupported_at(
            "a select or member of a part-select that addresses bits outside its vector",
            &cx.fn_sym,
        ));
    }
    Ok(())
}

fn nest<'ctx>(cx: &LowerCtx<'ctx, '_, '_>, inner: Lvalue<'ctx>, w: Window<'ctx>) -> Lvalue<'ctx> {
    let op = OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    let rel = if inner.width == inner.root_width {
        w.lo
    } else {
        cx.b.build_int_z_extend(w.lo, op.i_n(inner.root_width), "lv_rel_lo")
            .unwrap()
    };
    let lo = cx.b.build_int_add(inner.lo, rel, "lv_lo").unwrap();
    let bad = cx.b.build_or(inner.bad, w.bad, "lv_bad").unwrap();
    // A window inside an inner window that itself straddles an edge of the
    // root: the offsets add, and a bit is writable only when it is inside
    // both the inner window and the root.
    let edge = match (inner.edge, w.edge) {
        (None, None) => None,
        (inner_edge, outer_edge) => {
            let i64t = cx.ctx.i64_type();
            let delta = match (inner_edge, outer_edge) {
                (Some(i), Some(o)) => cx.b.build_int_add(i.delta, o.delta, "lv_delta").unwrap(),
                (Some(e), None) | (None, Some(e)) => e.delta,
                (None, None) => i64t.const_zero(),
            };
            let valid = match (inner_edge, outer_edge) {
                (None, Some(o)) => o.valid,
                (Some(_), outer) => {
                    let lo64 =
                        cx.b.build_int_cast_sign_flag(lo, i64t, false, "lv_lo64")
                            .unwrap();
                    let start = cx.b.build_int_add(lo64, delta, "lv_start").unwrap();
                    let root = range_mask(&op, start, w.width, inner.root_width);
                    outer.map_or(root, |o| op.and(o.valid, root))
                }
                (None, None) => op.i_n(w.width).const_all_ones(),
            };
            Some(Edge { delta, valid })
        }
    };
    Lvalue {
        lo,
        width: w.width,
        bad,
        edge,
        pad: w.pad,
        ..inner
    }
}

/// Reads an lvalue root's current whole value (a memory row is read at row 0
/// when the access is invalid, so the accessor never sees a bad index).
pub(crate) fn load_root<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    lv: &Lvalue<'ctx>,
) -> Result<PackedValue<'ctx>, LoweringError> {
    let op = OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    let llvm = match lv.root {
        LvalueRoot::Shadow { ptr } => {
            crate::collections::elem_ref_refresh(cx, ptr);
            cx.b.build_load(op.packed_type(lv.root_width, cx.repr), ptr, "lv_root")
                .unwrap()
                .into_int_value()
        }
        LvalueRoot::Signal { .. } => {
            return Err(LoweringError::unsupported_at(
                "internal: a nonblocking target root has no loadable shadow",
                &cx.fn_sym,
            ));
        }
        LvalueRoot::Field { h, slot } => {
            return Ok(
                crate::classes::field_get_call(cx, h, slot, lv.root_width, lv.root_signed).0,
            );
        }
        LvalueRoot::MemRow { info, row } => {
            let accessor = mem_accessor(cx)?;
            let safe_row =
                cx.b.build_select(lv.bad, cx.ctx.i64_type().const_zero(), row, "lv_safe_row")
                    .unwrap()
                    .into_int_value();
            crate::accessor::build_get_mem_word(
                cx,
                accessor.fns,
                accessor.handle,
                info.slot,
                safe_row,
                info.elem_width,
            )
        }
    };
    Ok(PackedValue {
        llvm,
        width: lv.root_width,
        repr: cx.repr,
        signed: lv.root_signed,
    })
}

fn mem_accessor<'ctx, 'm>(
    cx: &LowerCtx<'ctx, '_, 'm>,
) -> Result<crate::expr::MemAccessorCtx<'ctx, 'm>, LoweringError> {
    cx.mem_accessor.ok_or_else(|| {
        LoweringError::unsupported_at(
            "memory write reached with no accessor context wired (LowerCtx::mem_accessor)",
            &cx.fn_sym,
        )
    })
}

/// The `lv.width` bits to insert at `lv.lo` of `root` for a write of `value`
/// through `lv`: `value` itself, or -- when `lv` straddles an edge of the
/// root -- the clamped window's present bits with only the in-range ones
/// replaced.
fn edge_value<'ctx>(
    op: &OpBuilder<'_, 'ctx>,
    root: PackedValue<'ctx>,
    lv: &Lvalue<'ctx>,
    value: PackedValue<'ctx>,
) -> PackedValue<'ctx> {
    if lv.edge.is_none() {
        return value;
    }
    let current = op.part_select4(root, lv.lo, lv.bad, lv.width);
    merge_edge(op, current, lv.edge, value)
}

/// Blocking write of `value` (exactly `lv.width` bits) into `lv`: a
/// read-modify-write of the root, skipped entirely when `lv.bad`.
pub(crate) fn store_lvalue<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    lv: &Lvalue<'ctx>,
    value: PackedValue<'ctx>,
) -> Result<(), LoweringError> {
    let op = OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    match lv.root {
        LvalueRoot::Shadow { ptr } => {
            let cur = load_root(cx, lv)?;
            let value = edge_value(&op, cur, lv, value);
            let merged = op.insert4(cur, lv.lo, lv.bad, value);
            let chosen = op.select(lv.bad, cur, merged);
            cx.b.build_store(ptr, chosen.llvm).unwrap();
            crate::expr::write_through_store(cx, ptr);
        }
        LvalueRoot::Signal { .. } => {
            return Err(LoweringError::unsupported_at(
                "internal: a blocking write resolved to a nonblocking target root",
                &cx.fn_sym,
            ));
        }
        LvalueRoot::Field { h, slot } => {
            let new = if lv.width == lv.root_width {
                value
            } else {
                let cur = load_root(cx, lv)?;
                let merged = op.insert4(cur, lv.lo, lv.bad, value);
                op.select(lv.bad, cur, merged)
            };
            // A null or stale object was reported when the target was
            // resolved ([`crate::classes::class_field_root`]); the store is
            // then a no-op, and an invalid index leaves the value alone.
            crate::classes::field_set_call(cx, h, slot, new);
        }
        LvalueRoot::MemRow { info, row } => {
            let accessor = mem_accessor(cx)?;
            let func = cx.b.get_insert_block().unwrap().get_parent().unwrap();
            let store_bb = cx.ctx.append_basic_block(func, "lv_mem_store");
            let done_bb = cx.ctx.append_basic_block(func, "lv_mem_done");
            cx.b.build_conditional_branch(lv.bad, done_bb, store_bb)
                .unwrap();
            cx.b.position_at_end(store_bb);
            let new_row = if lv.width == lv.root_width {
                value
            } else {
                let cur = load_root(cx, lv)?;
                let value = edge_value(&op, cur, lv, value);
                op.insert4(cur, lv.lo, lv.bad, value)
            };
            crate::accessor::build_set_mem_word(
                cx,
                accessor.fns,
                accessor.handle,
                info.slot,
                row,
                new_row.llvm,
                info.elem_width,
            );
            cx.b.build_unconditional_branch(done_bb).unwrap();
            cx.b.position_at_end(done_bb);
        }
    }
    Ok(())
}

/// The bit width an lvalue expression addresses (for splitting a
/// concatenation target), from its elaborated type.
pub(crate) fn lvalue_width<'d>(
    cx: &LowerCtx<'_, 'd, '_>,
    e: sv_lang::Expression<'d>,
) -> Result<u32, LoweringError> {
    e.expr_type()
        .map(|t| t.value_width())
        .filter(|w| *w > 0)
        .ok_or_else(|| {
            LoweringError::unsupported_at(
                "concatenation lvalue operand has no integral width",
                &cx.fn_sym,
            )
        })
}

/// Blocking assignment of `value` to the lvalue expression `lhs`, including
/// a concatenation target (`{a, b} = v`: the LAST operand receives the least
/// significant bits).
pub(crate) fn lower_assign_to<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lhs: sv_lang::Expression<'d>,
    value: PackedValue<'ctx>,
) -> Result<(), LoweringError> {
    // `s[i] = c` on a string rewrites the whole string.
    if crate::strings::assign_char(cx, lhs, value)? {
        return Ok(());
    }
    for_each_target(cx, lhs, value, RootMode::Shadow, &mut |lv, v| {
        store_lvalue(cx, &lv, v)
    })
}

/// [`lower_assign_to`] for a target holding reference-counted handles (a
/// class handle, a struct or array of them, a collection): the target is
/// resolved ONCE (LRM 1800-2023 11.4.2 -- a side-effecting index such as
/// `a[i++]` runs a single time per assignment), and the value it holds at
/// that address is handed to `release` just before `value` overwrites it. An
/// invalid access (out-of-range or unknown index) stores nothing and hands
/// `release` a zero (null) value, which frees nothing.
///
/// `lhs` is never a concatenation or stream here: no such target holds a
/// handle (the caller selects this path from the target's own type).
pub(crate) fn lower_assign_releasing<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lhs: sv_lang::Expression<'d>,
    value: PackedValue<'ctx>,
    release: &mut dyn FnMut(PackedValue<'ctx>),
) -> Result<(), LoweringError> {
    for_each_target(cx, lhs, value, RootMode::Shadow, &mut |lv, v| {
        let old = read_target(cx, &lv)?;
        release(old);
        store_lvalue(cx, &lv, v)
    })
}

/// Read-modify-write of a single select / field target (`x[i++] += 2`,
/// LRM 1800-2023 11.4.1: the target of `a op= b` is evaluated ONCE, so a
/// side-effecting index runs a single time). `lhs` is resolved once, `f` maps
/// the bits it holds (all zero when the access is invalid) to the value
/// stored back, resized to the target's width; returns the stored value.
/// `None` when `lhs` is a concatenation, stream or padded part-select (the
/// caller keeps its read-then-write path).
pub(crate) fn lower_modify_target<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lhs: sv_lang::Expression<'d>,
    f: &mut dyn FnMut(PackedValue<'ctx>) -> Result<PackedValue<'ctx>, LoweringError>,
) -> Result<Option<PackedValue<'ctx>>, LoweringError> {
    if !matches!(
        lhs.kind(),
        ExpressionKind::ElementSelect | ExpressionKind::RangeSelect | ExpressionKind::MemberAccess
    ) {
        return Ok(None);
    }
    let op = OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    // `vif.a[k++] += 2`: the target runs once; each candidate's part is
    // resolved, the selected one's bits are modified and stored back.
    if let Some(lvs) = crate::vif::nested_lvalues(cx, lhs, RootMode::Shadow) {
        let lvs = lvs?;
        if lvs.iter().any(|lv| lv.pad.is_some()) {
            return Ok(None);
        }
        let mut old: Option<PackedValue<'ctx>> = None;
        for lv in &lvs {
            let v = read_target(cx, lv)?;
            old = Some(match old {
                Some(prev) => op.select(lv.bad, prev, v),
                None => v,
            });
        }
        let old = old.ok_or_else(|| {
            LoweringError::unsupported_at("a virtual interface member target", &cx.fn_sym)
        })?;
        let new = fit_width(&op, f(old)?, lvs[0].width);
        for lv in &lvs {
            store_lvalue(cx, lv, new)?;
        }
        return Ok(Some(new));
    }
    let lv = resolve_lvalue(cx, lhs, RootMode::Shadow)?;
    if lv.pad.is_some() {
        return Ok(None);
    }
    let old = read_target(cx, &lv)?;
    let new = fit_width(&op, f(old)?, lv.width);
    store_lvalue(cx, &lv, new)?;
    Ok(Some(new))
}

/// The bits `lv` currently holds (all zero when the access is invalid).
fn read_target<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    lv: &Lvalue<'ctx>,
) -> Result<PackedValue<'ctx>, LoweringError> {
    let op = OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    let root = load_root(cx, lv)?;
    let window = Window {
        lo: lv.lo,
        width: lv.width,
        bad: lv.bad,
        edge: lv.edge,
        pad: lv.pad,
    };
    let read = read_window(&op, root, window);
    let zero_lane = op.i_n(read.width).const_zero();
    let zero = op.pack(zero_lane, zero_lane, read.width, cx.repr, read.signed);
    Ok(op.select(lv.bad, zero, read))
}

/// Nonblocking assignment of `value` to `lhs` (a select, struct field,
/// memory element, concatenation, or a >64-bit signal): each resolved
/// target is staged with `sv_rt_nba_masked` as `(slot, row, value, mask)`,
/// the new bits shifted into position -- evaluated now, applied in the NBA
/// region (`sched::notify::commit_nba`).
pub(crate) fn lower_nba_to<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    handle: PointerValue<'ctx>,
    signals: &std::collections::HashMap<
        sv_sim_sim::symid::SymbolId,
        crate::process_lower::SignalSlot,
    >,
    lhs: sv_lang::Expression<'d>,
    value: PackedValue<'ctx>,
    delay: IntValue<'ctx>,
) -> Result<(), LoweringError> {
    for_each_target(cx, lhs, value, RootMode::Signal(signals), &mut |lv, v| {
        stage_nba_masked(cx, handle, &lv, v, delay)
    })
}

/// The whole-row target of row `row` (in range) of module memory `info`,
/// `width` bits wide.
pub(crate) fn mem_row_lvalue<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    info: crate::expr::MemorySignalInfo,
    row: IntValue<'ctx>,
    width: u32,
    signed: bool,
) -> Lvalue<'ctx> {
    Lvalue {
        root: LvalueRoot::MemRow { info, row },
        root_width: width,
        root_signed: signed,
        lo: cx.ctx.i32_type().const_zero(),
        width,
        bad: cx.ctx.bool_type().const_zero(),
        edge: None,
        pad: None,
    }
}

/// Stages a nonblocking write of `value` (the element's full width) to row
/// `row` (in range) of module memory `info`.
pub(crate) fn stage_nba_row<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    handle: PointerValue<'ctx>,
    info: crate::expr::MemorySignalInfo,
    row: IntValue<'ctx>,
    value: PackedValue<'ctx>,
    delay: IntValue<'ctx>,
) -> Result<(), LoweringError> {
    let lv = mem_row_lvalue(cx, info, row, value.width, value.signed);
    stage_nba_masked(cx, handle, &lv, value, delay)
}

fn stage_nba_masked<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    handle: PointerValue<'ctx>,
    lv: &Lvalue<'ctx>,
    value: PackedValue<'ctx>,
    delay: IntValue<'ctx>,
) -> Result<(), LoweringError> {
    let op = OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    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, 1u64),
        LvalueRoot::Field { h, slot } => {
            return stage_nba_field(cx, h, slot, lv, value, delay);
        }
        LvalueRoot::Shadow { .. } => {
            return Err(LoweringError::unsupported_at(
                "internal: a nonblocking target resolved to a shadow root",
                &cx.fn_sym,
            ));
        }
    };
    let func = cx.b.get_insert_block().unwrap().get_parent().unwrap();
    let stage_bb = cx.ctx.append_basic_block(func, "nba_stage");
    let done_bb = cx.ctx.append_basic_block(func, "nba_done");
    cx.b.build_conditional_branch(lv.bad, done_bb, stage_bb)
        .unwrap();
    cx.b.position_at_end(stage_bb);

    let w = lv.root_width;
    let nwords = w.div_ceil(64);
    let store_ty = op.i_n(nwords * 64);
    let place = |lane: IntValue<'ctx>, name: &str| -> PointerValue<'ctx> {
        let wide =
            cx.b.build_int_z_extend_or_bit_cast(lane, store_ty, name)
                .unwrap();
        let lo =
            cx.b.build_int_z_extend_or_bit_cast(lv.lo, store_ty, "nba_lo")
                .unwrap();
        let shifted = cx.b.build_left_shift(wide, lo, name).unwrap();
        let ptr = crate::expr::entry_alloca(cx, store_ty, name);
        cx.b.build_store(ptr, shifted).unwrap();
        ptr
    };
    // A target straddling an edge of its root stages only the in-range bits.
    let (value, mask) = match lv.edge {
        Some(edge) => edge_place(&op, value, edge),
        None => (value, op.i_n(value.width).const_all_ones()),
    };
    let val_ptr = place(op.lane_val(value), "nba_val");
    let unk_ptr = place(op.lane_unk(value), "nba_unk");
    let mask_ptr = place(mask, "nba_mask");
    let i32_ty = cx.ctx.i32_type();
    let f = rt_nba_masked_fn(cx);
    cx.b.build_call(
        f,
        &[
            handle.into(),
            i32_ty.const_int(u64::from(slot), false).into(),
            row.into(),
            i32_ty.const_int(has_row, false).into(),
            val_ptr.into(),
            unk_ptr.into(),
            mask_ptr.into(),
            i32_ty.const_int(u64::from(nwords), false).into(),
            i32_ty.const_int(u64::from(w), false).into(),
            delay.into(),
        ],
        "rt_nba_masked_call",
    )
    .unwrap();
    cx.b.build_unconditional_branch(done_bb).unwrap();
    cx.b.position_at_end(done_bb);
    Ok(())
}

/// A nonblocking write of `value` into the class property at `slot` of object
/// `h` (LRM 1800-2023 10.4.2, 8.x): the bits (and the mask of those written)
/// are placed in the property's packed words now and merged in the NBA region,
/// the object kept alive until then (`ObjOp::FieldNba`). A null or stale `h`
/// stages nothing (the target's own check already reported it).
fn stage_nba_field<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    h: IntValue<'ctx>,
    slot: sv_sim_sim::objects::FieldSlot,
    lv: &Lvalue<'ctx>,
    value: PackedValue<'ctx>,
    delay: IntValue<'ctx>,
) -> Result<(), LoweringError> {
    let op = OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    let func = cx.b.get_insert_block().unwrap().get_parent().unwrap();
    let stage_bb = cx.ctx.append_basic_block(func, "nba_fld_stage");
    let done_bb = cx.ctx.append_basic_block(func, "nba_fld_done");
    cx.b.build_conditional_branch(lv.bad, done_bb, stage_bb)
        .unwrap();
    cx.b.position_at_end(stage_bb);
    let (value, mask) = match lv.edge {
        Some(edge) => edge_place(&op, value, edge),
        None => (value, op.i_n(value.width).const_all_ones()),
    };
    let zero = PackedValue {
        llvm: op.packed_type(lv.root_width, cx.repr).const_zero(),
        width: lv.root_width,
        repr: cx.repr,
        signed: lv.root_signed,
    };
    let no = cx.ctx.bool_type().const_zero();
    let val_root = op.insert4(zero, lv.lo, no, value);
    let mask_pv = op.pack(mask, mask, value.width, value.repr, false);
    let mask_root = op.insert4(zero, lv.lo, no, mask_pv);
    let i64t = cx.ctx.i64_type();
    let words = slot.words as u32;
    let buf = crate::expr::entry_alloca(cx, i64t.array_type(2 * words + 1), "nba_fld_buf");
    crate::classes::store_packed_words(cx, buf, val_root, words);
    // SAFETY: both offsets are inside the `2 * words + 1`-word buffer.
    let mask_ptr = unsafe {
        cx.b.build_in_bounds_gep(
            i64t,
            buf,
            &[i64t.const_int(u64::from(words), false)],
            "nba_fld_mask",
        )
        .unwrap()
    };
    crate::classes::store_packed_words(cx, mask_ptr, mask_root, words);
    let delay_ptr = unsafe {
        cx.b.build_in_bounds_gep(
            i64t,
            buf,
            &[i64t.const_int(u64::from(2 * words), false)],
            "nba_fld_delay",
        )
        .unwrap()
    };
    cx.b.build_store(delay_ptr, delay).unwrap();
    crate::classes::obj_call(
        cx,
        sv_sim_runtime::objects_rt::ObjOp::FieldNba,
        h,
        i64t.const_int(slot.offset as u64, false),
        i64t.const_int(slot.words as u64, false),
        buf,
    );
    cx.b.build_unconditional_branch(done_bb).unwrap();
    cx.b.position_at_end(done_bb);
    Ok(())
}

/// `void sv_rt_nba_masked(SimHandle, u32 slot, u64 row, u32 has_row,
/// u64* val, u64* unk, u64* mask, u32 nwords, u32 width, u64 delay)`,
/// fetched or declared in the module being lowered.
pub(crate) fn rt_nba_masked_fn<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
) -> inkwell::values::FunctionValue<'ctx> {
    let name = crate::process_lower::SV_RT_NBA_MASKED_SYMBOL;
    cx.module.get_function(name).unwrap_or_else(|| {
        let ptr = cx.ctx.ptr_type(inkwell::AddressSpace::default());
        let i32_ty = cx.ctx.i32_type();
        let i64_ty = cx.ctx.i64_type();
        let fn_ty = cx.ctx.void_type().fn_type(
            &[
                ptr.into(),
                i32_ty.into(),
                i64_ty.into(),
                i32_ty.into(),
                ptr.into(),
                ptr.into(),
                ptr.into(),
                i32_ty.into(),
                i32_ty.into(),
                i64_ty.into(),
            ],
            false,
        );
        cx.module
            .add_function(name, fn_ty, Some(inkwell::module::Linkage::External))
    })
}

/// Resolves `lhs` (splitting a concatenation: the LAST operand receives
/// the least significant bits of `value`) and calls `write` once per
/// resolved target with exactly that target's bits.
fn for_each_target<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lhs: sv_lang::Expression<'d>,
    value: PackedValue<'ctx>,
    mode: RootMode<'_>,
    write: &mut dyn FnMut(Lvalue<'ctx>, PackedValue<'ctx>) -> Result<(), LoweringError>,
) -> Result<(), LoweringError> {
    let op = OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    // `{<<n{a, b}} = v`: the unpacked bits of each operand.
    if lhs.kind() == ExpressionKind::Streaming {
        return crate::stream::unpack_stream(
            cx,
            lhs,
            value,
            &mut |operand, with, bits| {
                // `a with [..]`: the selected elements (LRM 1800-2023 11.4.14.4).
                if let Some(w) = with {
                    if matches!(mode, RootMode::Signal(_)) {
                        // Nonblocking: each selected in-range element reaches
                        // `write` as a memory-row target.
                        return crate::stream_with::unpack_with(
                            cx,
                            operand,
                            w,
                            bits,
                            &mut |row, v| {
                                let crate::arrays::Backing::Memory(info) = row.backing else {
                                    return Err(LoweringError::unsupported_at(
                                        "a nonblocking assignment to a local array",
                                        &cx.fn_sym,
                                    ));
                                };
                                crate::arrays::guarded(cx, row.valid, || {
                                    write(mem_row_lvalue(cx, info, row.base, v.width, v.signed), v)
                                })
                            },
                        );
                    }
                    return crate::stream_with::unpack(cx, operand, w, bits);
                }
                // A fixed unpacked array operand takes its elements' bits row by
                // row (LRM 1800-2023 11.4.14.4).
                if operand.expr_type().is_some_and(|t| {
                    t.is_unpacked_array() && !sv_sim_sim::state::storage::is_collection(&t)
                }) {
                    // Nonblocking: each row reaches `write` as a memory-row
                    // target (LRM 1800-2023 11.4.14.3 with 10.4.2).
                    if matches!(mode, RootMode::Signal(_)) {
                        return crate::arrays::write_array_rows_from_packed(
                            cx, operand, bits, write,
                        );
                    }
                    return crate::arrays::store_array_from_packed(cx, operand, bits);
                }
                for_each_target(cx, operand, bits, mode, write)
            },
            None,
        );
    }
    if lhs.kind() == ExpressionKind::Concatenation {
        let parts = lhs.operands();
        let widths = parts
            .iter()
            .map(|p| lvalue_width(cx, *p))
            .collect::<Result<Vec<_>, _>>()?;
        let total: u32 = widths.iter().sum();
        if total != value.width {
            return Err(LoweringError::unsupported_at(
                &format!(
                    "concatenation lvalue is {total} bits but the assigned value is {} bits",
                    value.width
                ),
                &cx.fn_sym,
            ));
        }
        let mut offset = 0u32;
        for (part, w) in parts.iter().zip(&widths).rev() {
            let slice = op.part_select4(
                value,
                op.i_n(value.width).const_int(u64::from(offset), false),
                cx.ctx.bool_type().const_zero(),
                *w,
            );
            for_each_target(cx, *part, slice, mode, write)?;
            offset += w;
        }
        return Ok(());
    }
    // `vif.m = v`: every candidate instance's `m`, all but the selected one
    // suppressed (`crate::vif`).
    if let Some(lvs) = crate::vif::lvalues(cx, lhs, mode) {
        for lv in lvs? {
            write(lv, fit_width(&op, value, lv.width))?;
        }
        return Ok(());
    }
    // `vif.m[i]`, `vif.m.f`, `vif.m[3:0]`: each candidate's part.
    if let Some(lvs) = crate::vif::nested_lvalues(cx, lhs, mode) {
        for lv in lvs? {
            write_one(cx, lv, value, write)?;
        }
        return Ok(());
    }
    let lv = resolve_lvalue(cx, lhs, mode)?;
    write_one(cx, lv, value, write)
}

/// Writes `value` to the resolved target `lv`, applying its pad / edge
/// handling (the tail of [`for_each_target`]).
fn write_one<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lv: Lvalue<'ctx>,
    value: PackedValue<'ctx>,
    write: &mut dyn FnMut(Lvalue<'ctx>, PackedValue<'ctx>) -> Result<(), LoweringError>,
) -> Result<(), LoweringError> {
    let op = OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    let addressed = lv.pad.map_or(lv.width, |p| p.total);
    if value.width != addressed {
        return Err(LoweringError::unsupported_at(
            &format!(
                "assigned value is {} bits but its target addresses {} bits (expected \
                 sv-lang's assignment-context Conversion to have equalized them)",
                value.width, addressed
            ),
            &cx.fn_sym,
        ));
    }
    // An oversized part-select keeps only its in-range slice of the value.
    let mut lv = lv;
    let value = match lv.pad {
        Some(Pad {
            total,
            dynamic: Some(d),
            ..
        }) => {
            // Variable-index oversize target: the base-wide window takes the
            // value's bits that land on it, and only those bits are written
            // (a write edge with no displacement).
            let ty = op.i_n(lv.width);
            let slice = |lane: IntValue<'ctx>| {
                let moved = shift_signed(&op, lane, d, false);
                cx.b.build_int_truncate(moved, ty, "pad_slice").unwrap()
            };
            let valid = slice(op.i_n(total).const_all_ones());
            lv.edge = Some(Edge {
                delta: cx.ctx.i64_type().const_zero(),
                valid,
            });
            op.pack(
                slice(op.lane_val(value)),
                slice(op.lane_unk(value)),
                lv.width,
                value.repr,
                value.signed,
            )
        }
        Some(pad) => op.part_select4(
            value,
            op.i_n(value.width).const_int(u64::from(pad.shift), false),
            cx.ctx.bool_type().const_zero(),
            lv.width,
        ),
        None => value,
    };
    write(lv, value)
}

/// `v` resized to `width` bits: truncated, or extended by its own signedness
/// (both planes, so an X sign bit extends as X) -- the implicit argument
/// conversion at an inlined task's binding.
pub(crate) fn fit_width<'ctx>(
    op: &OpBuilder<'_, 'ctx>,
    v: PackedValue<'ctx>,
    width: u32,
) -> PackedValue<'ctx> {
    if v.width == width {
        return v;
    }
    let ty = op.i_n(width);
    let lane = |x: IntValue<'ctx>, name: &str| -> IntValue<'ctx> {
        if width < v.width {
            op.b.build_int_truncate(x, ty, name).unwrap()
        } else if v.signed {
            op.b.build_int_s_extend(x, ty, name).unwrap()
        } else {
            op.b.build_int_z_extend(x, ty, name).unwrap()
        }
    };
    let val = lane(op.lane_val(v), "fit_v");
    let unk = lane(op.lane_unk(v), "fit_u");
    op.pack(val, unk, width, v.repr, v.signed)
}

/// Stores `value` into `sym`'s whole shadow copy (a net declaration
/// assignment's target), which must be exactly as wide.
pub(crate) fn store_whole<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    sym: &sv_lang::Symbol<'d>,
    value: PackedValue<'ctx>,
) -> Result<(), LoweringError> {
    let (ptr, width, _) = *cx.locals.get(&sym.uid()).ok_or_else(|| {
        LoweringError::unsupported_at("assignment target has no shadow copy", sym)
    })?;
    if value.width != width {
        return Err(LoweringError::unsupported_at(
            &format!(
                "assigned value is {} bits for a {width}-bit target",
                value.width
            ),
            sym,
        ));
    }
    cx.b.build_store(ptr, value.llvm).unwrap();
    crate::collections::elem_ref_flush(cx, ptr);
    Ok(())
}

/// The storage-root symbols an lvalue expression writes: `q` for `q[3:0]`,
/// `s` for `s.f`, both `a` and `b` for `{a, b}`, `mem` for `mem[i][3]`.
pub fn lvalue_root_symbols<'d>(e: sv_lang::Expression<'d>) -> Vec<sv_lang::Symbol<'d>> {
    let mut out = Vec::new();
    collect_roots(e, &mut out);
    out
}

fn collect_roots<'d>(e: sv_lang::Expression<'d>, out: &mut Vec<sv_lang::Symbol<'d>>) {
    // Only these four kinds can form (part of) an lvalue path; any other
    // kind has no storage root to report.
    let kind = e.kind();
    if let Some(inner) = crate::expr::modport_expr_target(&e) {
        // A modport port with an expression (LRM 25.5.4) writes its target.
        collect_roots(inner, out);
    } else if sv_sim_sim::symid::is_value_name(kind) {
        out.extend(e.referenced_symbol());
    } else if matches!(
        kind,
        ExpressionKind::ElementSelect | ExpressionKind::RangeSelect
    ) {
        if let Some(b) = e.select_value() {
            collect_roots(b, out);
        }
    } else if kind == ExpressionKind::MemberAccess {
        if let Some(b) = e.operand() {
            collect_roots(b, out);
        }
    } else if kind == ExpressionKind::Concatenation {
        for p in e.operands() {
            collect_roots(p, out);
        }
    }
}

#[cfg(test)]
mod tests {
    use super::SelectGeom;

    #[test]
    fn positions_follow_the_declared_direction() {
        let desc = SelectGeom {
            left: 8,
            right: 1,
            elem_width: 1,
        };
        assert_eq!(desc.pos(1), 0);
        assert_eq!(desc.pos(8), 7);
        let asc = SelectGeom {
            left: 0,
            right: 7,
            elem_width: 1,
        };
        assert_eq!(asc.pos(7), 0);
        assert_eq!(asc.pos(0), 7);
        assert_eq!(asc.elems(), 8);
    }
}