vj-codegen 0.1.0

//! 4-state bitwise operators: AND / OR / XOR. Pure-Rust `ref4` truth-table
//! oracle (per-bit, matches `sv_lang::Bit`) plus the matching inkwell IR
//! lowering in `OpBuilder`. Formulas from ARCHITECTURE.md §6.1.
use std::num::NonZeroU32;

use inkwell::FloatPredicate;
use inkwell::builder::Builder;
use inkwell::context::Context;
use inkwell::module::{Linkage, Module};
use inkwell::values::{FunctionValue, IntValue, PointerValue};

use crate::value::{
    AnyValue, PackedValue, RealValue, ValueRepr, WIDE_THRESHOLD, WideValueRef, bit_to_aval_bval,
    const_svint, wide_limb_count,
};

/// The 64-bit mask covering limb `limb`'s meaningful bits for an operand of
/// total width `width` (CG-129's `svLogicVecVal` limb layout: every limb
/// but the last is a full 64 bits; the last limb may be partial, and any
/// higher limb than that has no meaningful bits at all). Shared by
/// `OpBuilder::{wide_add,wide_gather,wide_scatter}` so a value's
/// out-of-range high bits in the top (possibly-partial) limb never leak
/// into an unknown-detection test or an arithmetic/conversion result --
/// mirrors `lower_const_any`'s existing "stop at `width`, leave the rest
/// zero" per-bit loop, but as one reusable formula instead of a re-derived
/// inline bound in each caller.
fn limb_mask64(width: u32, limb: u32) -> u64 {
    let lo = limb * 64;
    if lo >= width {
        return 0;
    }
    let bits_in_limb = (width - lo).min(64);
    if bits_in_limb >= 64 {
        u64::MAX
    } else {
        (1u64 << bits_in_limb) - 1
    }
}

pub mod ref4 {
    use sv_lang::Bit;
    fn vu(b: Bit) -> (u8, u8) {
        match b {
            Bit::Zero => (0, 0),
            Bit::One => (1, 0),
            Bit::X => (0, 1),
            Bit::Z => (1, 1),
        }
    }
    fn bit(v: u8, u: u8) -> Bit {
        match 2 * (u & 1) + (v & 1) {
            0 => Bit::Zero,
            1 => Bit::One,
            2 => Bit::X,
            _ => Bit::Z,
        }
    }
    pub fn and(a: Bit, b: Bit) -> Bit {
        let ((va, ua), (vb, ub)) = (vu(a), vu(b));
        let dom0 = ((1 - ua) & (1 - va)) | ((1 - ub) & (1 - vb));
        let known = (1 - ua) & (1 - ub);
        bit((1 - dom0) & known & (va & vb), (1 - dom0) & (1 - known))
    }
    pub fn or(a: Bit, b: Bit) -> Bit {
        let ((va, ua), (vb, ub)) = (vu(a), vu(b));
        let dom1 = ((1 - ua) & va) | ((1 - ub) & vb);
        let known = (1 - ua) & (1 - ub);
        bit(
            dom1 | ((1 - dom1) & known & (va | vb)),
            (1 - dom1) & (1 - known),
        )
    }
    pub fn xor(a: Bit, b: Bit) -> Bit {
        let ((va, ua), (vb, ub)) = (vu(a), vu(b));
        let u = ua | ub;
        bit((1 - u) & (va ^ vb), u)
    }
    /// Unary NOT: `unk' = a_unk; val' = ~a_unk & ~a_val`. A Z bit (val=1,
    /// unk=1) must invert to X (unk=1), not to a spurious known bit -- the
    /// `& ~a_unk` term masks `val'` to 0 whenever the input is already
    /// unknown, so the `val'` bit computed for an unknown input is always
    /// discarded by `bit()`'s "unk wins" encoding, exactly like every other
    /// unk-dominant case here.
    pub fn not(a: Bit) -> Bit {
        let (va, ua) = vu(a);
        let up = ua;
        let vp = (1 - ua) & (1 - va);
        bit(vp, up)
    }
}

/// Whole-word (val,unk) reference oracle for ADD/DIV/SHL: any-unknown-bit
/// input -> all-X result (except SHL's amount, which is self-determined and
/// only forces all-X on its own unknown bits); DIV additionally guards a
/// zero (but known) divisor to all-X rather than modelling a hardware trap.
///
/// Corrected vs. plan: the plan's `shl` masked `amt.0 & mask(n)` and relied
/// on that mask alone to bound `s`, which is only right for `n <= s < 64`
/// and shifts a `u64` by `s >= 64` (a Rust panic in debug, platform-defined
/// in release) whenever `n == 64` and `s >= 64`. Explicitly clamp `s >= n`
/// to a zero result (mirrors the LRM: a known shift amount >= the operand
/// width yields a definite 0) before ever using it as a shift count.
pub mod ref4word {
    fn mask(n: u32) -> u64 {
        if n >= 64 { u64::MAX } else { (1u64 << n) - 1 }
    }
    pub fn add(n: u32, a: (u64, u64), b: (u64, u64)) -> (u64, u64) {
        let m = mask(n);
        if (a.1 | b.1) & m != 0 {
            return (0, m);
        }
        ((a.0.wrapping_add(b.0)) & m, 0)
    }
    pub fn div(n: u32, a: (u64, u64), b: (u64, u64)) -> (u64, u64) {
        let m = mask(n);
        if (a.1 | b.1) & m != 0 || (b.0 & m) == 0 {
            return (0, m);
        }
        ((a.0 / b.0) & m, 0)
    }

    pub fn sub(n: u32, a: (u64, u64), b: (u64, u64)) -> (u64, u64) {
        let m = mask(n);
        if (a.1 | b.1) & m != 0 {
            return (0, m);
        }
        (a.0.wrapping_sub(b.0) & m, 0)
    }
    pub fn mul(n: u32, a: (u64, u64), b: (u64, u64)) -> (u64, u64) {
        let m = mask(n);
        if (a.1 | b.1) & m != 0 {
            return (0, m);
        }
        (a.0.wrapping_mul(b.0) & m, 0)
    }
    pub fn neg(n: u32, a: (u64, u64)) -> (u64, u64) {
        let m = mask(n);
        if a.1 & m != 0 {
            return (0, m);
        }
        (0u64.wrapping_sub(a.0) & m, 0)
    }

    /// Sign-extend the low `n` bits of `v` (`n <= 64`) to a full `i64`.
    fn to_signed(v: u64, n: u32) -> i64 {
        let m = mask(n);
        let v = v & m;
        if n >= 64 {
            return v as i64;
        }
        let sign_bit = 1u64 << (n - 1);
        if v & sign_bit != 0 {
            (v | !m) as i64
        } else {
            v as i64
        }
    }
    /// Inverse of `to_signed`: truncate `v`'s two's-complement bit pattern
    /// down to `n` bits.
    fn from_signed(v: i64, n: u32) -> u64 {
        (v as u64) & mask(n)
    }
    /// The n-bit signed minimum (e.g. -128 for n=8), computed without
    /// overflowing `i64` arithmetic at n==64 (`-(i64::MIN)` itself
    /// overflows, so that width is handled directly).
    fn signed_min(n: u32) -> i64 {
        if n >= 64 {
            i64::MIN
        } else {
            -(1i64 << (n - 1))
        }
    }

    /// Signed-division reference oracle (`sv_lang::Type::is_signed() ==
    /// true` path): truncates toward zero (matches LLVM's `sdiv` and SV's
    /// `/` on signed operands, LRM 1800-2023 SS11.4 -- NOT floor division).
    /// Guards divide-by-zero to all-X, matching `div`. The n-bit-signed-MIN
    /// / -1 case is NOT forced to all-X: real simulators (iverilog,
    /// verilator both verified) wrap it to the dividend unchanged --
    /// `MIN / -1 == MIN` -- since that is the only representable result of
    /// two's-complement division overflow. `av / bv` is not used directly
    /// for that case because `i64::MIN / -1` itself overflows `i64`
    /// arithmetic (panics in debug Rust) whenever `n == 64`; the wrapped
    /// answer is just the original dividend bit pattern, so it's returned
    /// directly without going through signed division at all.
    pub fn sdiv(n: u32, a: (u64, u64), b: (u64, u64)) -> (u64, u64) {
        let m = mask(n);
        if (a.1 | b.1) & m != 0 {
            return (0, m);
        }
        let (av, bv) = (to_signed(a.0, n), to_signed(b.0, n));
        if bv == 0 {
            return (0, m);
        }
        if av == signed_min(n) && bv == -1 {
            return (a.0 & m, 0);
        }
        (from_signed(av / bv, n), 0)
    }

    /// `%` reference oracle, either signed or unsigned per `signed`. SV's
    /// `%` sign rule: the result's sign follows the DIVIDEND, not the
    /// divisor (LRM SS11.4) -- Rust's `%` on signed integers already
    /// truncates toward zero with that same sign convention, matching
    /// LLVM's `srem`. Guards divide-by-zero (both modes) to all-X. The
    /// signed MIN / -1 case is NOT forced to all-X: real simulators give
    /// `MIN % -1 == 0` (a real, known result), and `av % bv` is not used
    /// directly for it because `i64::MIN % -1` itself overflows `i64`
    /// arithmetic (panics in debug Rust) whenever `n == 64`.
    pub fn mod_(n: u32, a: (u64, u64), b: (u64, u64), signed: bool) -> (u64, u64) {
        let m = mask(n);
        if (a.1 | b.1) & m != 0 || (b.0 & m) == 0 {
            return (0, m);
        }
        if signed {
            let (av, bv) = (to_signed(a.0, n), to_signed(b.0, n));
            if av == signed_min(n) && bv == -1 {
                return (0, 0);
            }
            (from_signed(av % bv, n), 0)
        } else {
            ((a.0 & m) % (b.0 & m), 0)
        }
    }
    pub fn shl(n: u32, a: (u64, u64), amt: (u64, u64)) -> (u64, u64) {
        let m = mask(n);
        if amt.1 & m != 0 {
            return (0, m);
        }
        let s = amt.0 & m;
        if s >= n as u64 {
            return (0, 0);
        }
        (((a.0 << s) & m), ((a.1 << s) & m))
    }

    /// Logical `>>` reference oracle: val-lane and unk-lane shift right
    /// independently and zero-fill from the top -- same clamp/unknown-amount
    /// shape as `shl` (CG-029/CG-030/CG-032), mirrored for the opposite
    /// direction.
    pub fn lshr(n: u32, a: (u64, u64), amt: (u64, u64)) -> (u64, u64) {
        let m = mask(n);
        if amt.1 & m != 0 {
            return (0, m);
        }
        let s = amt.0 & m;
        if s >= n as u64 {
            return (0, 0);
        }
        (((a.0 & m) >> s), ((a.1 & m) >> s))
    }

    /// Arithmetic `>>>` reference oracle (the `a.signed == true` path; an
    /// unsigned operand's `>>>` is LRM-equivalent to `lshr` and is not
    /// modelled by a separate oracle -- see `OpBuilder::ashr4`'s doc
    /// comment). CG-031: each lane's vacated top bits fill with THAT LANE'S
    /// OWN sign bit independently -- `to_signed`/`from_signed` applied
    /// separately to the val word and the unk word (not the packed i(2N)
    /// blob, and not the value lane's sign reused for the unk lane) is
    /// exactly that per-lane replication. A known amount >= `n` shifts every
    /// original bit out, so the result becomes each lane's own sign bit
    /// replicated across the full width, computed the same way (shifting a
    /// lane's already-maximal own sign-extension is a no-op past the point
    /// every bit is already that sign).
    pub fn ashr(n: u32, a: (u64, u64), amt: (u64, u64)) -> (u64, u64) {
        let m = mask(n);
        if amt.1 & m != 0 {
            return (0, m);
        }
        let s = amt.0 & m;
        if s >= n as u64 {
            let vfull = if to_signed(a.0, n) < 0 { m } else { 0 };
            let ufull = if to_signed(a.1, n) < 0 { m } else { 0 };
            return (vfull, ufull);
        }
        let sv = to_signed(a.0, n) >> s;
        let su = to_signed(a.1, n) >> s;
        (from_signed(sv, n), from_signed(su, n))
    }

    /// Reduction-AND over the `n`-bit word `a = (val, unk)`: 0 if any lane is
    /// known-0 (dominant, exactly like binary AND's per-pair dom0 -- a
    /// known-0 lane anywhere makes the fold definite-0 even in the presence
    /// of other unknown lanes), else X if any lane is unknown, else 1 (every
    /// lane is known-1). Returned as a single-bit `(val, unk)` pair.
    pub fn reduce_and(n: u32, a: (u64, u64)) -> (u64, u64) {
        let m = mask(n);
        let (val, unk) = (a.0 & m, a.1 & m);
        let any_known0 = (!unk & !val) & m != 0;
        let any_unk = unk != 0;
        if any_known0 {
            (0, 0)
        } else if any_unk {
            (0, 1)
        } else {
            (1, 0)
        }
    }
    /// Reduction-OR: 1 if any lane is known-1 (dominant), else X if any lane
    /// is unknown, else 0 (every lane is known-0). Mirrors `reduce_and`.
    pub fn reduce_or(n: u32, a: (u64, u64)) -> (u64, u64) {
        let m = mask(n);
        let (val, unk) = (a.0 & m, a.1 & m);
        let any_known1 = (val & !unk) & m != 0;
        let any_unk = unk != 0;
        if any_known1 {
            (1, 0)
        } else if any_unk {
            (0, 1)
        } else {
            (0, 0)
        }
    }
    /// Reduction-XOR: X if any lane is unknown (X or Z propagates
    /// unconditionally, unlike AND/OR's dominant-0/1 short-circuit --
    /// there's no "dominant" value for parity), else the parity (XOR-fold)
    /// of the known val bits.
    pub fn reduce_xor(n: u32, a: (u64, u64)) -> (u64, u64) {
        let m = mask(n);
        if a.1 & m != 0 {
            return (0, 1);
        }
        let parity = (a.0 & m).count_ones() & 1;
        (parity as u64, 0)
    }

    /// Case equality (`===`, CG-130) whole-word oracle: exact bitwise
    /// identity over BOTH the value and unknown planes, always known.
    /// Mirrors `OpBuilder::caseeq4` bit-for-bit.
    pub fn caseeq(n: u32, a: (u64, u64), b: (u64, u64)) -> (u64, u64) {
        let m = mask(n);
        let eq = ((a.0 & m) == (b.0 & m)) && ((a.1 & m) == (b.1 & m));
        (u64::from(eq), 0)
    }

    /// Shared wildcard-match oracle. Two genuinely different modes, per
    /// `treat_x_as_wildcard`:
    ///
    /// - `false` (`casez`, symmetric): a Z on EITHER operand is always a
    ///   per-bit don't-care, X is compared literally on both sides, and the
    ///   result is always known (never X) -- verified against iverilog 12's
    ///   `casez` (a Z on the case *expression* itself does not block a
    ///   match; an X on either side does, and simply fails to match rather
    ///   than making the branch selection ambiguous).
    /// - `true` (`==?`/`!=?`/`inside`, CG-131, asymmetric): per IEEE
    ///   1800-2023 SS11.4.6, ONLY `b`'s (the right-hand operand's) X/Z bits
    ///   are wildcards. A bit where `b` is a determinate 0/1 and `a` is X/Z
    ///   is a genuine ambiguity, not a match: `a`'s real bit might resolve
    ///   either way, so it can't be forced to a boolean outcome -- unlike
    ///   `casez`, this mode's *result* can itself be X. Verified against
    ///   iverilog 12: `4'b10x1 ==? 4'b1011` (X on `a`, `b` fully known) ->
    ///   `x`; `4'b1011 ==? 4'b10x1` (X on `b`) -> `1`. Word-level reduction:
    ///   any bit with a definite literal mismatch makes the whole result a
    ///   definite 0 (dominant, same shape as `and4`'s dominant-0), else any
    ///   ambiguous bit makes it X, else it's a definite 1.
    ///
    /// Mirrors `OpBuilder::wildcard_match` bit-for-bit.
    pub fn wildcard_match(
        n: u32,
        a: (u64, u64),
        b: (u64, u64),
        treat_x_as_wildcard: bool,
    ) -> (u64, u64) {
        if !treat_x_as_wildcard {
            for i in 0..n {
                let (av, au) = ((a.0 >> i) & 1, (a.1 >> i) & 1);
                let (bv, bu) = ((b.0 >> i) & 1, (b.1 >> i) & 1);
                let a_is_z = au & av;
                let b_is_z = bu & bv;
                let dc = a_is_z | b_is_z;
                let literal_eq = (1 - (av ^ bv)) & (1 - (au ^ bu));
                if (dc | literal_eq) == 0 {
                    return (0, 0);
                }
            }
            return (1, 0);
        }

        let mut any_mismatch = false;
        let mut any_ambiguous = false;
        for i in 0..n {
            let (av, au) = ((a.0 >> i) & 1, (a.1 >> i) & 1);
            let (bv, bu) = ((b.0 >> i) & 1, (b.1 >> i) & 1);
            if bu == 1 {
                // b's bit is X or Z: always a wildcard, regardless of a.
                continue;
            }
            if au == 1 {
                // a's bit is X or Z but b's is a determinate 0/1: ambiguous.
                any_ambiguous = true;
            } else if av != bv {
                // both determinate and differ: a definite mismatch.
                any_mismatch = true;
            }
        }
        if any_mismatch {
            (0, 0)
        } else if any_ambiguous {
            (0, 1)
        } else {
            (1, 0)
        }
    }

    /// `casex` (`CaseStatementCondition::WildcardXOrZ`, Task 26 review fix
    /// r1) whole-word oracle: SYMMETRIC per IEEE 1800-2023 SS12.5 -- an X or
    /// Z at a given bit position on EITHER operand (not just `b`, unlike
    /// `wildcard_match`'s asymmetric `==?`/`inside` mode above) is a per-bit
    /// don't-care. Verified against iverilog 12: `casex (2'b1x)  2'b10:
    /// ...` matches, i.e. the case EXPRESSION's own X is a wildcard too, not
    /// only a case ITEM's. Always known (never X), mirroring `casez`'s
    /// (`wildcard_match(treat_x_as_wildcard: false)`) always-known shape --
    /// `casex` selects a branch or falls through, it has no 3-valued
    /// "result" of its own. Mirrors `OpBuilder::casex_match` bit-for-bit.
    pub fn casex_match(n: u32, a: (u64, u64), b: (u64, u64)) -> (u64, u64) {
        for i in 0..n {
            let (av, au) = ((a.0 >> i) & 1, (a.1 >> i) & 1);
            let (bv, bu) = ((b.0 >> i) & 1, (b.1 >> i) & 1);
            if au == 1 || bu == 1 {
                // Either side's bit is X or Z: always a wildcard,
                // regardless of the other operand.
                continue;
            }
            if av != bv {
                return (0, 0);
            }
        }
        (1, 0)
    }

    // --- Task 11 (CG-021): relational, loose-equality reference oracles.
    //
    // Formula (codegen.md; plan Task 11): relational -- any-operand-unknown
    // anywhere -> X (1-bit), else the natural signed/unsigned compare over
    // the raw `n`-bit words. Loose `==`/`!=` -- any-operand-unknown anywhere
    // -> X, UNLIKE `caseeq`/`===` above (which is never X, comparing both
    // planes bit-for-bit instead). This "any unknown -> X" shape is exactly
    // `add`/`div`/`sub`/... 's own any-unknown rule (see this module's doc
    // comment), just applied to a comparison instead of an arithmetic
    // result.

    /// Shared unsigned-compare reduction: any-unknown-bit-anywhere -> X
    /// (1-bit `(0,1)`), else `cmp` applied to the raw (masked) `n`-bit
    /// unsigned words.
    fn rel_unsigned(
        n: u32,
        a: (u64, u64),
        b: (u64, u64),
        cmp: impl Fn(u64, u64) -> bool,
    ) -> (u64, u64) {
        let m = mask(n);
        if (a.1 | b.1) & m != 0 {
            return (0, 1);
        }
        (u64::from(cmp(a.0 & m, b.0 & m)), 0)
    }
    /// Shared signed-compare reduction: same any-unknown gate as
    /// `rel_unsigned`, but `cmp` is applied to each operand's `to_signed`
    /// (two's-complement) interpretation.
    fn rel_signed(
        n: u32,
        a: (u64, u64),
        b: (u64, u64),
        cmp: impl Fn(i64, i64) -> bool,
    ) -> (u64, u64) {
        let m = mask(n);
        if (a.1 | b.1) & m != 0 {
            return (0, 1);
        }
        (u64::from(cmp(to_signed(a.0, n), to_signed(b.0, n))), 0)
    }

    pub fn ult(n: u32, a: (u64, u64), b: (u64, u64)) -> (u64, u64) {
        rel_unsigned(n, a, b, |x, y| x < y)
    }
    pub fn ule(n: u32, a: (u64, u64), b: (u64, u64)) -> (u64, u64) {
        rel_unsigned(n, a, b, |x, y| x <= y)
    }
    pub fn ugt(n: u32, a: (u64, u64), b: (u64, u64)) -> (u64, u64) {
        rel_unsigned(n, a, b, |x, y| x > y)
    }
    pub fn uge(n: u32, a: (u64, u64), b: (u64, u64)) -> (u64, u64) {
        rel_unsigned(n, a, b, |x, y| x >= y)
    }
    pub fn slt(n: u32, a: (u64, u64), b: (u64, u64)) -> (u64, u64) {
        rel_signed(n, a, b, |x, y| x < y)
    }
    pub fn sle(n: u32, a: (u64, u64), b: (u64, u64)) -> (u64, u64) {
        rel_signed(n, a, b, |x, y| x <= y)
    }
    pub fn sgt(n: u32, a: (u64, u64), b: (u64, u64)) -> (u64, u64) {
        rel_signed(n, a, b, |x, y| x > y)
    }
    pub fn sge(n: u32, a: (u64, u64), b: (u64, u64)) -> (u64, u64) {
        rel_signed(n, a, b, |x, y| x >= y)
    }

    /// Loose equality (`==`) whole-word oracle (LRM 11.4.5): 0 when some bit
    /// position is known in both operands and differs, else X when any bit
    /// is unknown, else 1 -- deliberately NOT `caseeq`'s "compare both
    /// planes" formula (this is the divergence `loose_eq_any_unknown_is_x`,
    /// tests/ops_relational.rs, guards).
    pub fn eq(n: u32, a: (u64, u64), b: (u64, u64)) -> (u64, u64) {
        let m = mask(n);
        let known = !(a.1 | b.1) & m;
        if (a.0 ^ b.0) & known != 0 {
            // A known-bit mismatch decides `==` as 0 (LRM 11.4.5).
            return (0, 0);
        }
        if (a.1 | b.1) & m != 0 {
            return (0, 1);
        }
        (1, 0)
    }
    /// Loose inequality (`!=`): boolean NOT of `eq`, X-preserving (an X
    /// input stays X, never flips to a crisp 0/1) -- mirrors how `!==`/`!=?`
    /// are lowered as `not4` of their positive form in `expr.rs`.
    pub fn neq(n: u32, a: (u64, u64), b: (u64, u64)) -> (u64, u64) {
        let (v, u) = eq(n, a, b);
        if u != 0 { (0, 1) } else { (1 - v, 0) }
    }
}

/// A dynamic select/insert on a base wider than this many bits goes through
/// a byte buffer instead of whole-width variable shifts (see
/// `OpBuilder::wide_dynamic`).
pub(crate) const WIDE_SELECT_BITS: u32 = 256;

/// The current function's entry-block `alloca` named exactly `name`,
/// created on first use and returned again to every later call site.
///
/// For scratch memory that is written and fully consumed within one
/// straight-line run of emitted code (no suspension point, no other user of
/// the same name in between): sharing one slot per `name` keeps the frame at
/// one buffer instead of one per call site, and creating it in the entry
/// block (never at the call site) keeps a call inside an SV loop from
/// growing the stack on every iteration. `name` must encode the type, since
/// the lookup is by name only.
pub(crate) fn shared_entry_alloca<'ctx, T: inkwell::types::BasicType<'ctx>>(
    ctx: &'ctx Context,
    b: &Builder<'ctx>,
    ty: T,
    name: &str,
) -> PointerValue<'ctx> {
    let func = b
        .get_insert_block()
        .and_then(|bb| bb.get_parent())
        .expect("lowering happens inside a function");
    let entry = func
        .get_first_basic_block()
        .expect("a function has an entry block");
    let mut cur = entry.get_first_instruction();
    while let Some(inst) = cur {
        if inst.get_opcode() != inkwell::values::InstructionOpcode::Alloca {
            break;
        }
        if inst
            .get_name()
            .is_some_and(|n| n.to_bytes() == name.as_bytes())
        {
            return PointerValue::try_from(inst).expect("alloca is a pointer");
        }
        cur = inst.get_next_instruction();
    }
    let tmp = ctx.create_builder();
    match entry.get_first_instruction() {
        Some(first) => tmp.position_before(&first),
        None => tmp.position_at_end(entry),
    }
    tmp.build_alloca(ty, name).unwrap()
}

/// Width from which `pack` / `lane_unk` move the val/unk halves through
/// memory instead of a zext/shl/or chain (compile time, not run time).
const WIDE_PACK_BITS: u32 = 1024;

pub struct OpBuilder<'a, 'ctx> {
    pub ctx: &'ctx Context,
    pub b: &'a Builder<'ctx>,
}
impl<'a, 'ctx> OpBuilder<'a, 'ctx> {
    // Corrected vs. plan: inkwell 0.10 (LLVM22) `Context::custom_width_int_type`
    // takes `NonZeroU32` and returns `Result<IntType, &'static str>`, not a
    // bare `u32` -> `IntType` (see value.rs / types.rs for the same fix).
    pub(crate) fn i_n(&self, w: u32) -> inkwell::types::IntType<'ctx> {
        self.ctx
            .custom_width_int_type(NonZeroU32::new(w).expect("zero-width int type"))
            .expect("custom_width_int_type")
    }
    pub fn lane_val(&self, v: PackedValue<'ctx>) -> IntValue<'ctx> {
        match v.repr {
            ValueRepr::TwoState => v.llvm,
            ValueRepr::FourState => self
                .b
                .build_int_truncate(v.llvm, self.i_n(v.width), "val")
                .unwrap(),
        }
    }
    pub fn lane_unk(&self, v: PackedValue<'ctx>) -> IntValue<'ctx> {
        match v.repr {
            ValueRepr::TwoState => self.i_n(v.width).const_zero(),
            ValueRepr::FourState if v.width >= WIDE_PACK_BITS && v.width.is_multiple_of(8) => {
                // The high half through memory, mirroring `pack`.
                let wide = self.i_n(v.width * 2);
                let ty = self.i_n(v.width);
                let buf =
                    shared_entry_alloca(self.ctx, self.b, wide, &format!("pack_tmp{}", v.width));
                self.b.build_store(buf, v.llvm).unwrap();
                self.b
                    .build_load(ty, self.byte_at(buf, v.width / 8), "unk")
                    .unwrap()
                    .into_int_value()
            }
            ValueRepr::FourState => {
                let sh = self
                    .b
                    .build_right_shift(
                        v.llvm,
                        self.i_n(v.width * 2).const_int(v.width as u64, false),
                        false,
                        "ushr",
                    )
                    .unwrap();
                self.b
                    .build_int_truncate(sh, self.i_n(v.width), "unk")
                    .unwrap()
            }
        }
    }
    /// `base` advanced by `bytes` bytes (little-endian host layout).
    fn byte_at(&self, base: PointerValue<'ctx>, bytes: u32) -> PointerValue<'ctx> {
        // SAFETY: callers pass half the byte size of the buffer's integer type.
        unsafe {
            self.b
                .build_in_bounds_gep(
                    self.ctx.i8_type(),
                    base,
                    &[self.ctx.i32_type().const_int(u64::from(bytes), false)],
                    "pack_hi",
                )
                .unwrap()
        }
    }
    pub fn pack(
        &self,
        val: IntValue<'ctx>,
        unk: IntValue<'ctx>,
        width: u32,
        repr: ValueRepr,
        signed: bool,
    ) -> PackedValue<'ctx> {
        match repr {
            ValueRepr::TwoState => PackedValue {
                llvm: val,
                width,
                repr,
                signed,
            },
            ValueRepr::FourState if width >= WIDE_PACK_BITS && width.is_multiple_of(8) => {
                // `(unk << width) | val` as two stores into one `i(2*width)`
                // temporary and a load: the shl/or chain on an
                // i(2*width) value costs the LLVM backend far more than
                // the two memory accesses (uvm_string_to_bits: i230400).
                let wide = self.i_n(width * 2);
                let buf = shared_entry_alloca(self.ctx, self.b, wide, &format!("pack_tmp{width}"));
                self.b.build_store(buf, val).unwrap();
                self.b
                    .build_store(self.byte_at(buf, width / 8), unk)
                    .unwrap();
                PackedValue {
                    llvm: self
                        .b
                        .build_load(wide, buf, "packed")
                        .unwrap()
                        .into_int_value(),
                    width,
                    repr,
                    signed,
                }
            }
            ValueRepr::FourState => {
                let wide = self.i_n(width * 2);
                let ve = self.b.build_int_z_extend(val, wide, "ve").unwrap();
                let ue = self.b.build_int_z_extend(unk, wide, "ue").unwrap();
                let ush = self
                    .b
                    .build_left_shift(ue, wide.const_int(width as u64, false), "ush")
                    .unwrap();
                PackedValue {
                    llvm: self.b.build_or(ve, ush, "packed").unwrap(),
                    width,
                    repr,
                    signed,
                }
            }
        }
    }
    /// The LLVM int type a `width`-bit value occupies under `repr`
    /// (`i(2*width)` for 4-state's `(unk << width) | val`, `i(width)` for
    /// 2-state).
    pub(crate) fn packed_type(&self, width: u32, repr: ValueRepr) -> inkwell::types::IntType<'ctx> {
        match repr {
            ValueRepr::FourState => self.i_n(width * 2),
            ValueRepr::TwoState => self.i_n(width),
        }
    }

    /// Whether a dynamic select/insert on a `base_width`-bit value takes the
    /// memory-window path (`wide_window_*`) instead of whole-width variable
    /// shifts. LLVM legalizes a variable shift of an `iN` far wider than a
    /// register into a cascade of selects whose cost grows super-linearly
    /// with `N` (a 1024-bit shift took >500 s in the JIT backend, a 256-bit
    /// one 2 s), so a wide base is addressed through a byte buffer and only
    /// a small window is ever shifted. A constant `lo` folds to a constant
    /// shift in the builder and never needs this.
    fn wide_dynamic(base_width: u32, lo: IntValue<'ctx>) -> bool {
        base_width > WIDE_SELECT_BITS && !lo.is_const()
    }

    /// `lo` as an `i64` bit offset (truncating a wider one; zero-extending a
    /// narrower one). Only used for offsets the caller has already
    /// classified: a bad one is replaced by 0 afterwards, and
    /// `window_byte_offset` clamps the byte offset again, so a stray huge
    /// value can never address outside the spill buffer.
    fn lo_as_i64(&self, lo: IntValue<'ctx>) -> IntValue<'ctx> {
        let i64t = self.ctx.i64_type();
        let w = lo.get_type().get_bit_width();
        if w < 64 {
            self.b.build_int_z_extend(lo, i64t, "wsel_lo64").unwrap()
        } else {
            self.b
                .build_int_truncate_or_bit_cast(lo, i64t, "wsel_lo64")
                .unwrap()
        }
    }

    /// The function's single spill buffer of `bytes` bytes, created in the
    /// entry block on first use and reused by every later call site. Reuse
    /// is sound because each use (`spill_packed` .. last read of the buffer)
    /// is emitted as one straight-line run with no other spill in between,
    /// and a per-call-site buffer would otherwise grow the frame by `bytes`
    /// per select in the function.
    fn spill_buffer(&self, bytes: u32) -> PointerValue<'ctx> {
        shared_entry_alloca(
            self.ctx,
            self.b,
            self.ctx.i8_type().array_type(bytes),
            &format!("wsel_buf_{bytes}"),
        )
    }

    /// Stores the `total_bits`-bit `v` (zero-extended to a whole number of
    /// bytes, plus `pad_bytes` of zero tail so a window starting in the last
    /// real byte stays inside the buffer) at the start of the spill buffer.
    /// The buffer is little-endian (asserted at the accessor module), so bit
    /// `i` of `v` is bit `i % 8` of byte `i / 8`. Returns the buffer pointer.
    fn spill_packed(
        &self,
        v: IntValue<'ctx>,
        total_bits: u32,
        pad_bytes: u32,
    ) -> PointerValue<'ctx> {
        let bytes = total_bits.div_ceil(8) + pad_bytes;
        let buf = self.spill_buffer(bytes);
        let ext = self
            .b
            .build_int_z_extend(v, self.i_n(bytes * 8), "wsel_spill")
            .unwrap();
        self.store_unaligned(buf, ext);
        buf
    }

    fn store_unaligned(&self, ptr: PointerValue<'ctx>, v: IntValue<'ctx>) {
        self.b
            .build_store(ptr, v)
            .unwrap()
            .set_alignment(1)
            .expect("store alignment");
    }

    fn load_unaligned(
        &self,
        ty: inkwell::types::IntType<'ctx>,
        ptr: PointerValue<'ctx>,
    ) -> IntValue<'ctx> {
        let v = self.b.build_load(ty, ptr, "wsel_ld").unwrap();
        inkwell::values::BasicValue::as_instruction_value(&v)
            .expect("a load is an instruction")
            .set_alignment(1)
            .expect("load alignment");
        v.into_int_value()
    }

    /// `ptr + byte_off` bytes. `byte_off` is always clamped by the caller to
    /// a value for which the whole window lies inside the buffer.
    fn byte_ptr(&self, ptr: PointerValue<'ctx>, byte_off: IntValue<'ctx>) -> PointerValue<'ctx> {
        // SAFETY: the callers derive `byte_off` from an offset already
        // checked (or clamped, see `window_byte_offset`) to be at most
        // `buffer_bytes - window_bytes`, so the result stays in bounds of
        // the spill buffer for the whole `window_bytes` access.
        unsafe {
            self.b
                .build_in_bounds_gep(self.ctx.i8_type(), ptr, &[byte_off], "wsel_p")
                .unwrap()
        }
    }

    /// The `i64` byte offset of the (not-bad) `i64` bit offset `pos`,
    /// clamped to `0..=max_byte_off`. The caller guarantees
    /// `pos <= max_byte_off * 8 + 7` when the result is used; the clamp makes
    /// the access memory-safe even when a caller's `bad` flag failed to
    /// exclude a stray offset (such a result is discarded by the caller
    /// either way).
    fn window_byte_offset(&self, pos: IntValue<'ctx>, max_byte_off: u64) -> IntValue<'ctx> {
        let i64t = self.ctx.i64_type();
        let off = self
            .b
            .build_right_shift(pos, i64t.const_int(3, false), false, "wsel_off")
            .unwrap();
        let over = self
            .b
            .build_int_compare(
                inkwell::IntPredicate::UGT,
                off,
                i64t.const_int(max_byte_off, false),
                "wsel_over",
            )
            .unwrap();
        self.b
            .build_select(over, i64t.const_zero(), off, "wsel_off_safe")
            .unwrap()
            .into_int_value()
    }

    /// Shifts `x` by `pos & 7` bits (right or left) as three conditional
    /// constant shifts (by 1, 2 and 4) so no variable-amount shift of a
    /// possibly wide window is ever emitted.
    fn shift_sub_byte(
        &self,
        x: IntValue<'ctx>,
        lo64: IntValue<'ctx>,
        left: bool,
    ) -> IntValue<'ctx> {
        let i64t = self.ctx.i64_type();
        let mut acc = x;
        for k in [1u64, 2, 4] {
            let bit = self
                .b
                .build_int_compare(
                    inkwell::IntPredicate::NE,
                    self.b
                        .build_and(lo64, i64t.const_int(k, false), "wsel_bit")
                        .unwrap(),
                    i64t.const_zero(),
                    "wsel_bit_set",
                )
                .unwrap();
            let amt = acc.get_type().const_int(k, false);
            let moved = if left {
                self.b.build_left_shift(acc, amt, "wsel_shl").unwrap()
            } else {
                self.b
                    .build_right_shift(acc, amt, false, "wsel_shr")
                    .unwrap()
            };
            acc = self
                .b
                .build_select(bit, moved, acc, "wsel_sh")
                .unwrap()
                .into_int_value();
        }
        acc
    }

    /// The bit count of `base`'s packed representation.
    fn packed_bits(base: PackedValue<'ctx>) -> u32 {
        match base.repr {
            ValueRepr::FourState => base.width * 2,
            ValueRepr::TwoState => base.width,
        }
    }

    /// `pos + base_width`, the bit position of the unk plane's copy of the
    /// bit at `pos` in the packed `(unk << width) | val` spill.
    fn unk_pos(&self, pos: IntValue<'ctx>, base_width: u32) -> IntValue<'ctx> {
        self.b
            .build_int_add(
                pos,
                self.ctx.i64_type().const_int(u64::from(base_width), false),
                "wsel_upos",
            )
            .unwrap()
    }

    /// The `out_width`-bit window at bit `pos` (an `i64`) of the spill
    /// buffer `buf`, which holds `data_bytes` meaningful bytes.
    fn read_window_bits(
        &self,
        buf: PointerValue<'ctx>,
        data_bytes: u32,
        pos: IntValue<'ctx>,
        out_width: u32,
    ) -> IntValue<'ctx> {
        let win_bytes = (out_width + 7).div_ceil(8);
        let off = self.window_byte_offset(pos, u64::from(data_bytes));
        let win = self.load_unaligned(self.i_n(win_bytes * 8), self.byte_ptr(buf, off));
        let shifted = self.shift_sub_byte(win, pos, false);
        self.b
            .build_int_truncate(shifted, self.i_n(out_width), "wsel_out")
            .unwrap()
    }

    /// Overwrites the `value_width` bits at bit `pos` (an `i64`) of the
    /// spill buffer `buf` (`data_bytes` meaningful bytes) with `value`, as a
    /// byte-window read-modify-write.
    fn insert_window_bits(
        &self,
        buf: PointerValue<'ctx>,
        data_bytes: u32,
        pos: IntValue<'ctx>,
        value: IntValue<'ctx>,
        value_width: u32,
    ) {
        let win_ty = self.i_n((value_width + 7).div_ceil(8) * 8);
        let off = self.window_byte_offset(pos, u64::from(data_bytes));
        let p = self.byte_ptr(buf, off);
        let old = self.load_unaligned(win_ty, p);
        let ones = self
            .b
            .build_int_z_extend(self.i_n(value_width).const_all_ones(), win_ty, "wsel_ones")
            .unwrap();
        let mask = self.shift_sub_byte(ones, pos, true);
        let ext = self
            .b
            .build_int_z_extend(value, win_ty, "wsel_val")
            .unwrap();
        let placed = self.shift_sub_byte(ext, pos, true);
        let merged = self.or(self.and(old, self.not(mask)), placed);
        self.store_unaligned(p, merged);
    }

    /// The val and unk windows of `out_width` bits at bit offset `lo` (an
    /// `i64`; valid, `lo + out_width <= base.width`, or 0 -- the caller
    /// substitutes 0 for a bad offset) of `base`, read through ONE spill of
    /// the packed value (val at bit 0, unk at bit `base.width`). Spilling
    /// the packed value once, instead of each lane separately, halves the
    /// number of huge-integer operations the backend has to legalize.
    fn wide_window_read(
        &self,
        base: PackedValue<'ctx>,
        lo: IntValue<'ctx>,
        out_width: u32,
    ) -> (IntValue<'ctx>, IntValue<'ctx>) {
        let total_bits = Self::packed_bits(base);
        let data_bytes = total_bits.div_ceil(8);
        let buf = self.spill_packed(base.llvm, total_bits, (out_width + 7).div_ceil(8));
        let wv = self.read_window_bits(buf, data_bytes, lo, out_width);
        let wu = match base.repr {
            ValueRepr::TwoState => self.i_n(out_width).const_zero(),
            ValueRepr::FourState => {
                self.read_window_bits(buf, data_bytes, self.unk_pos(lo, base.width), out_width)
            }
        };
        (wv, wu)
    }

    /// `base` with the window at bit offset `lo` (an `i64`, valid or 0, as
    /// for `wide_window_read`) replaced by `value` in both lanes, returned
    /// packed in `base`'s representation. `value.width <= base.width`.
    fn wide_window_insert(
        &self,
        base: PackedValue<'ctx>,
        lo: IntValue<'ctx>,
        value: PackedValue<'ctx>,
    ) -> IntValue<'ctx> {
        let total_bits = Self::packed_bits(base);
        let data_bytes = total_bits.div_ceil(8);
        let pad = (value.width + 7).div_ceil(8);
        let buf = self.spill_packed(base.llvm, total_bits, pad);
        self.insert_window_bits(buf, data_bytes, lo, self.lane_val(value), value.width);
        if base.repr == ValueRepr::FourState {
            self.insert_window_bits(
                buf,
                data_bytes,
                self.unk_pos(lo, base.width),
                self.lane_unk(value),
                value.width,
            );
        }
        let total = self.load_unaligned(self.i_n((data_bytes + pad) * 8), buf);
        self.b
            .build_int_truncate(total, self.i_n(total_bits), "wsel_ins")
            .unwrap()
    }

    /// `base` with bits `[lo, lo + value.width)` replaced by `value` (both
    /// lanes) -- the write-side twin of `part_select4`. `lo` is a
    /// `base.width`-bit offset; when `bad` is true the offset is not trusted
    /// (it is replaced by 0 so the shifts stay defined) and the caller is
    /// expected to discard the result.
    pub(crate) fn insert4(
        &self,
        base: PackedValue<'ctx>,
        lo: IntValue<'ctx>,
        bad: IntValue<'ctx>,
        value: PackedValue<'ctx>,
    ) -> PackedValue<'ctx> {
        let w = base.width;
        if Self::wide_dynamic(w, lo) {
            // The offset is narrowed to i64 BEFORE the `bad` select so the
            // select is a register op, not an `iN` one (see `wide_dynamic`).
            let safe_lo = self
                .b
                .build_select(
                    bad,
                    self.ctx.i64_type().const_zero(),
                    self.lo_as_i64(lo),
                    "ins_safe_lo",
                )
                .unwrap()
                .into_int_value();
            return PackedValue {
                llvm: self.wide_window_insert(base, safe_lo, value),
                width: w,
                repr: base.repr,
                signed: base.signed,
            };
        }
        let ty = self.i_n(w);
        let safe_lo = self
            .b
            .build_select(bad, ty.const_zero(), lo, "ins_safe_lo")
            .unwrap()
            .into_int_value();
        let ones = self.resize_unsigned(self.i_n(value.width).const_all_ones(), value.width, w);
        let mask = self.b.build_left_shift(ones, safe_lo, "ins_mask").unwrap();
        let keep = self.not(mask);
        let place = |lane: IntValue<'ctx>, name: &str| {
            let ext = self.resize_unsigned(lane, value.width, w);
            self.b.build_left_shift(ext, safe_lo, name).unwrap()
        };
        let nv = self.or(
            self.and(self.lane_val(base), keep),
            place(self.lane_val(value), "ins_v"),
        );
        let nu = self.or(
            self.and(self.lane_unk(base), keep),
            place(self.lane_unk(value), "ins_u"),
        );
        self.pack(nv, nu, w, base.repr, base.signed)
    }

    pub(crate) fn not(&self, x: IntValue<'ctx>) -> IntValue<'ctx> {
        self.b.build_not(x, "not").unwrap()
    }
    pub(crate) fn and(&self, x: IntValue<'ctx>, y: IntValue<'ctx>) -> IntValue<'ctx> {
        self.b.build_and(x, y, "and").unwrap()
    }
    pub(crate) fn or(&self, x: IntValue<'ctx>, y: IntValue<'ctx>) -> IntValue<'ctx> {
        self.b.build_or(x, y, "or").unwrap()
    }
    pub(crate) fn xor(&self, x: IntValue<'ctx>, y: IntValue<'ctx>) -> IntValue<'ctx> {
        self.b.build_xor(x, y, "xor").unwrap()
    }
    pub fn and4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vb, ub) = (self.lane_val(b), self.lane_unk(b));
        let dom0 = self.or(
            self.and(self.not(ua), self.not(va)),
            self.and(self.not(ub), self.not(vb)),
        );
        let known = self.and(self.not(ua), self.not(ub));
        let u = self.and(self.not(dom0), self.not(known));
        let v = self.and(self.and(self.not(dom0), known), self.and(va, vb));
        self.pack(v, u, a.width, a.repr, a.signed)
    }
    pub fn or4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vb, ub) = (self.lane_val(b), self.lane_unk(b));
        let dom1 = self.or(self.and(self.not(ua), va), self.and(self.not(ub), vb));
        let known = self.and(self.not(ua), self.not(ub));
        let u = self.and(self.not(dom1), self.not(known));
        let v = self.or(
            dom1,
            self.and(self.and(self.not(dom1), known), self.or(va, vb)),
        );
        self.pack(v, u, a.width, a.repr, a.signed)
    }
    pub fn xor4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vb, ub) = (self.lane_val(b), self.lane_unk(b));
        let u = self.or(ua, ub);
        let v = self.and(self.not(u), self.xor(va, vb));
        self.pack(v, u, a.width, a.repr, a.signed)
    }
    fn any_unknown(&self, ua: IntValue<'ctx>, ub: IntValue<'ctx>, w: u32) -> IntValue<'ctx> {
        let both = self.or(ua, ub);
        self.b
            .build_int_compare(
                inkwell::IntPredicate::NE,
                both,
                self.i_n(w).const_zero(),
                "anyunk",
            )
            .unwrap()
    }
    /// Whether any of `x`'s `w` bits is set, as an `i1`.
    fn nonzero(&self, x: IntValue<'ctx>, w: u32) -> IntValue<'ctx> {
        self.b
            .build_int_compare(inkwell::IntPredicate::NE, x, self.i_n(w).const_zero(), "nz")
            .unwrap()
    }
    fn all_x(&self, w: u32, repr: ValueRepr, signed: bool) -> PackedValue<'ctx> {
        self.pack(
            self.i_n(w).const_zero(),
            self.i_n(w).const_all_ones(),
            w,
            repr,
            signed,
        )
    }
    // Corrected vs. plan: the plan's `all_x` happened to double as the
    // LRM-correct 2-state div-by-zero result (0) only because `pack`'s
    // `TwoState` arm silently discards the `unk` argument -- not by
    // construction. Make the two cases (4-state div-by-zero -> X;
    // 2-state div-by-zero -> 0, since 2-state has no X to represent) each
    // independently correct rather than relying on that side effect, so a
    // future hardening of `pack`'s TwoState arm can't silently break this.
    fn zero_or_allx(&self, w: u32, repr: ValueRepr, signed: bool) -> PackedValue<'ctx> {
        match repr {
            ValueRepr::TwoState => self.pack(
                self.i_n(w).const_zero(),
                self.i_n(w).const_zero(),
                w,
                repr,
                signed,
            ),
            ValueRepr::FourState => self.all_x(w, repr, signed),
        }
    }
    // Task 10 (CG-041): exposed at crate visibility (not just this module) so
    // `expr.rs`'s ternary `?:` lowering can reuse this exact packed-select
    // primitive for its side-effect-free fast path -- selecting on the whole
    // packed `llvm` value at once (both the val and unk planes together, in
    // one `select` instruction) rather than two separate lane selects, which
    // is both simpler and is what keeps `ternary_pure_arms_lower_to_select_
    // not_br_phi`'s "zero new basic blocks" assertion true: a `build_select`
    // is a single SSA instruction, never a new `BasicBlock`.
    pub(crate) fn select(
        &self,
        c: IntValue<'ctx>,
        t: PackedValue<'ctx>,
        f: PackedValue<'ctx>,
    ) -> PackedValue<'ctx> {
        let s = self
            .b
            .build_select(c, t.llvm, f.llvm, "sel")
            .unwrap()
            .into_int_value();
        PackedValue {
            llvm: s,
            width: t.width,
            repr: t.repr,
            signed: t.signed,
        }
    }
    /// Zero-extend or truncate `v` (currently `from_w` bits wide) to `to_w`
    /// bits. Used for the shift-amount operand, which per IEEE 1800-2023 is
    /// self-determined (keeps its own natural width, independent of the
    /// shifted operand's width) unlike AND/OR/XOR/ADD/DIV's operands, which
    /// sv-lang equalizes via inserted `Conversion` nodes before lowering.
    pub(crate) fn resize_unsigned(
        &self,
        v: IntValue<'ctx>,
        from_w: u32,
        to_w: u32,
    ) -> IntValue<'ctx> {
        use std::cmp::Ordering;
        match from_w.cmp(&to_w) {
            Ordering::Equal => v,
            Ordering::Less => self
                .b
                .build_int_z_extend(v, self.i_n(to_w), "zext")
                .unwrap(),
            Ordering::Greater => self
                .b
                .build_int_truncate(v, self.i_n(to_w), "trunc")
                .unwrap(),
        }
    }
    pub fn add4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vb, ub) = (self.lane_val(b), self.lane_unk(b));
        let sum = self.b.build_int_add(va, vb, "sum").unwrap();
        let known = self.pack(
            sum,
            self.i_n(a.width).const_zero(),
            a.width,
            a.repr,
            a.signed,
        );
        self.select(
            self.any_unknown(ua, ub, a.width),
            self.all_x(a.width, a.repr, a.signed),
            known,
        )
    }
    /// `a - b`: same any-unknown-bit-\>all-X shape as `add4` (ARCHITECTURE.md
    /// / codegen.md SS2's "Arithmetic (+,-,*)" rule); the known-case wrapping
    /// two's-complement subtraction needs no separate signed/unsigned path
    /// (`sub`'s bit pattern is representation-agnostic -- only `/`/`%` care
    /// about `signed`, per Global Constraint 5's "no signed/unsigned
    /// confusion left silent" note, which scopes that requirement to
    /// div/mod specifically).
    pub fn sub4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vb, ub) = (self.lane_val(b), self.lane_unk(b));
        let diff = self.b.build_int_sub(va, vb, "diff").unwrap();
        let known = self.pack(
            diff,
            self.i_n(a.width).const_zero(),
            a.width,
            a.repr,
            a.signed,
        );
        self.select(
            self.any_unknown(ua, ub, a.width),
            self.all_x(a.width, a.repr, a.signed),
            known,
        )
    }
    /// `a * b`: same shape as `add4`/`sub4`. `build_int_mul` on a fixed-width
    /// `iN` already wraps mod 2^N, matching SV's wrapping multiply -- no
    /// extra masking needed (mirrors how `add4`'s `build_int_add` needs
    /// none).
    pub fn mul4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vb, ub) = (self.lane_val(b), self.lane_unk(b));
        let prod = self.b.build_int_mul(va, vb, "prod").unwrap();
        let known = self.pack(
            prod,
            self.i_n(a.width).const_zero(),
            a.width,
            a.repr,
            a.signed,
        );
        self.select(
            self.any_unknown(ua, ub, a.width),
            self.all_x(a.width, a.repr, a.signed),
            known,
        )
    }
    /// Unary `-a`: same any-unknown-\>all-X rule as the binary arithmetic
    /// ops, just with a single operand's own unk lane as the trigger.
    pub fn neg4(&self, a: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let negv = self.b.build_int_neg(va, "negv").unwrap();
        let known = self.pack(
            negv,
            self.i_n(a.width).const_zero(),
            a.width,
            a.repr,
            a.signed,
        );
        self.select(
            self.nonzero(ua, a.width),
            self.all_x(a.width, a.repr, a.signed),
            known,
        )
    }
    /// Guard both `va`/`vb` against a runtime-computed divisor value LLVM's
    /// `udiv`/`sdiv`/`urem`/`srem` treat as poison: a zero divisor (both
    /// modes), and -- for the signed instructions only -- the n-bit-signed
    /// MIN dividend divided/remaindered by -1 (LLVM LangRef: `sdiv`/`srem`
    /// are also poison on that overflow, not just on div-by-zero). Returns
    /// `(safe_divisor, bad)`: `safe_divisor` is never a value that would
    /// make the chosen instruction poison.
    ///
    /// `bad` only ever reflects the divide-by-zero case, NOT the signed
    /// MIN/-1 overflow: substituting the divisor with 1 in the overflow
    /// case already makes the underlying `sdiv`/`srem` instruction compute
    /// the exact LRM-correct wrapped answer with no poison --
    /// `MIN / 1 == MIN` (the two's-complement wrap div4/mod4's caller
    /// expects) and `MIN % 1 == 0`. Folding `overflow` into `bad` would
    /// make div4/mod4 discard that already-correct value in favor of
    /// all-X/0, which real simulators (iverilog, verilator) do not do:
    /// `(-128) / (-1) == -128` and `(-128) % (-1) == 0` at 8-bit width, not
    /// X. So only the true poison-hazard (division by a runtime zero) is
    /// reported as `bad`; the overflow case flows through `known`.
    fn safe_divisor(
        &self,
        va: IntValue<'ctx>,
        vb: IntValue<'ctx>,
        w: u32,
        signed: bool,
    ) -> (IntValue<'ctx>, IntValue<'ctx>) {
        let zero = self.i_n(w).const_zero();
        let one = self.i_n(w).const_int(1, false);
        let is0 = self
            .b
            .build_int_compare(inkwell::IntPredicate::EQ, vb, zero, "is0")
            .unwrap();
        let safe1 = self
            .b
            .build_select(is0, one, vb, "safe1")
            .unwrap()
            .into_int_value();
        if !signed {
            return (safe1, is0);
        }
        // n-bit signed MIN: high bit set, every other bit clear. Built in
        // LLVM IR (a runtime shift of a `1` constant by the LLVM constant
        // `w - 1`), not folded on the host with `1u64 << (w - 1)`: that
        // host shift is only valid for w <= 64 and panics (debug) / computes
        // garbage (release) for any wider signed operand, e.g. a
        // `logic signed [127:0]` division -- `w - 1` here is only ever used
        // as an LLVM constant *operand* (always < 2^32, so it never
        // overflows as a u64 argument to `const_int`), never as a host
        // shift amount.
        let min = self
            .b
            .build_left_shift(
                self.i_n(w).const_int(1, false),
                self.i_n(w).const_int((w - 1) as u64, false),
                "signmin",
            )
            .unwrap();
        let neg1 = self.i_n(w).const_all_ones();
        let is_min = self
            .b
            .build_int_compare(inkwell::IntPredicate::EQ, va, min, "ismin")
            .unwrap();
        let is_neg1 = self
            .b
            .build_int_compare(inkwell::IntPredicate::EQ, safe1, neg1, "isneg1")
            .unwrap();
        let overflow = self.and(is_min, is_neg1);
        let safe2 = self
            .b
            .build_select(overflow, one, safe1, "safe2")
            .unwrap()
            .into_int_value();
        // Only div-by-zero is "bad" -- see the doc comment above for why
        // `overflow` must NOT be folded in here.
        (safe2, is0)
    }
    /// SV `/`: LRM 1800-2023 SS11.4 -- signed operands truncate toward zero
    /// (LLVM `sdiv`'s own semantics, not floor division), unsigned operands
    /// divide the raw bit pattern (`udiv`). Per ARCHITECTURE.md's Codegen
    /// note (and the same "only ever consult `a`" pattern every other
    /// binary op here already follows), the operand's `signed`-ness is
    /// read from `a` -- slang's inserted `Conversion` nodes have already
    /// equalized `a`/`b`'s types before this lowers. Guarded against LLVM
    /// `udiv`/`sdiv` poison on divide-by-runtime-zero, matching CG-028's
    /// `result = select(b_val==0, TwoState?0:allX, any_unk?allX:real_div)`
    /// formula. The signed only MIN/-1 case is also poison for raw `sdiv`
    /// and so still needs `safe_divisor`'s divisor-substitution to avoid
    /// emitting poison, but it is NOT treated as "bad": substituting the
    /// divisor with 1 already yields the exact correct wrapped answer
    /// (`MIN / -1 == MIN`), so that case flows through as a real, known
    /// result rather than being forced to all-X/0 -- see `safe_divisor`'s
    /// doc comment.
    pub fn div4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vb, ub) = (self.lane_val(b), self.lane_unk(b));
        let zero = self.i_n(a.width).const_zero();
        let (safe, guard_bad) = self.safe_divisor(va, vb, a.width, a.signed);
        let q = if a.signed {
            self.b.build_int_signed_div(va, safe, "q").unwrap()
        } else {
            self.b.build_int_unsigned_div(va, safe, "q").unwrap()
        };
        let known = self.pack(q, zero, a.width, a.repr, a.signed);
        let bad = self
            .b
            .build_or(self.any_unknown(ua, ub, a.width), guard_bad, "bad")
            .unwrap();
        self.select(bad, self.zero_or_allx(a.width, a.repr, a.signed), known)
    }
    /// SV `%`: sign of the result follows the DIVIDEND, not the divisor
    /// (LRM SS11.4) -- exactly LLVM `srem`'s own convention, so no extra
    /// post-processing is needed beyond picking `srem` vs `urem` on
    /// `a.signed`. Guarded identically to `div4` (divide-by-zero both
    /// modes is "bad"; the signed MIN/-1 case only needs the
    /// divisor-substituted-to-1 `srem` to avoid poison -- it is a real,
    /// known result of 0, not all-X -- see `safe_divisor`'s doc comment).
    pub fn mod4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vb, ub) = (self.lane_val(b), self.lane_unk(b));
        let zero = self.i_n(a.width).const_zero();
        let (safe, guard_bad) = self.safe_divisor(va, vb, a.width, a.signed);
        let r = if a.signed {
            self.b.build_int_signed_rem(va, safe, "r").unwrap()
        } else {
            self.b.build_int_unsigned_rem(va, safe, "r").unwrap()
        };
        let known = self.pack(r, zero, a.width, a.repr, a.signed);
        let bad = self
            .b
            .build_or(self.any_unknown(ua, ub, a.width), guard_bad, "bad")
            .unwrap();
        self.select(bad, self.zero_or_allx(a.width, a.repr, a.signed), known)
    }
    // Corrected vs. plan: two fixes, both required for this to even build
    // for the general case (not just amt.width == a.width):
    //   1. The shift-amount operand is self-determined (IEEE 1800-2023): it
    //      keeps its own width, which need not equal `a.width`. Feeding
    //      differently-typed IntValues into one `build_left_shift`/`build_or`
    //      is an LLVM type mismatch (hard build failure), so the amount is
    //      resized to `a.width` for the actual shifts, while the
    //      known/unknown-amount check stays in the amount's own width.
    //   2. LLVM's `shl` is poison whenever the shift amount >= the
    //      operand's bit width, but a SV shift by a *known*, merely
    //      oversized amount must yield a definite 0 (not poison, not X).
    //      Compare the amount against `a.width` at the wider of the two
    //      widths (so a large amount can never wrap to a false "in range"
    //      value via truncation) and clamp to 0 before shifting.
    pub fn shl4(&self, a: PackedValue<'ctx>, amt: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vamt_raw, uamt) = (self.lane_val(amt), self.lane_unk(amt));

        let unkamt = self.any_unknown(uamt, self.i_n(amt.width).const_zero(), amt.width);

        let cmp_w = a.width.max(amt.width);
        let vamt_cmp = self.resize_unsigned(vamt_raw, amt.width, cmp_w);
        let oversize = self
            .b
            .build_int_compare(
                inkwell::IntPredicate::UGE,
                vamt_cmp,
                self.i_n(cmp_w).const_int(a.width as u64, false),
                "oversize",
            )
            .unwrap();

        let vamt_a = self.resize_unsigned(vamt_raw, amt.width, a.width);
        let safe_amt = self
            .b
            .build_select(oversize, self.i_n(a.width).const_zero(), vamt_a, "safe_amt")
            .unwrap()
            .into_int_value();

        let vsh = self.b.build_left_shift(va, safe_amt, "vshl").unwrap();
        let ush = self.b.build_left_shift(ua, safe_amt, "ushl").unwrap();
        let shifted = self.pack(vsh, ush, a.width, a.repr, a.signed);
        let zero_known = self.pack(
            self.i_n(a.width).const_zero(),
            self.i_n(a.width).const_zero(),
            a.width,
            a.repr,
            a.signed,
        );
        let in_range = self.select(oversize, zero_known, shifted);

        self.select(unkamt, self.all_x(a.width, a.repr, a.signed), in_range)
    }

    /// `a >> amt`: same lane-separate-extraction / self-determined-amount /
    /// oversize-clamp / unknown-amount-short-circuit shape as `shl4`
    /// (CG-029/CG-030/CG-032), zero-filling from the top instead of the
    /// bottom. Also the fallback body for `ashr4` on an unsigned operand
    /// (LRM `>>>` on unsigned == `>>` -- see `ashr4`'s doc comment).
    pub fn lshr4(&self, a: PackedValue<'ctx>, amt: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vamt_raw, uamt) = (self.lane_val(amt), self.lane_unk(amt));

        let unkamt = self.any_unknown(uamt, self.i_n(amt.width).const_zero(), amt.width);

        let cmp_w = a.width.max(amt.width);
        let vamt_cmp = self.resize_unsigned(vamt_raw, amt.width, cmp_w);
        let oversize = self
            .b
            .build_int_compare(
                inkwell::IntPredicate::UGE,
                vamt_cmp,
                self.i_n(cmp_w).const_int(a.width as u64, false),
                "oversize",
            )
            .unwrap();

        let vamt_a = self.resize_unsigned(vamt_raw, amt.width, a.width);
        let safe_amt = self
            .b
            .build_select(oversize, self.i_n(a.width).const_zero(), vamt_a, "safe_amt")
            .unwrap()
            .into_int_value();

        let vsh = self
            .b
            .build_right_shift(va, safe_amt, false, "vlshr")
            .unwrap();
        let ush = self
            .b
            .build_right_shift(ua, safe_amt, false, "ulshr")
            .unwrap();
        let shifted = self.pack(vsh, ush, a.width, a.repr, a.signed);
        let zero_known = self.pack(
            self.i_n(a.width).const_zero(),
            self.i_n(a.width).const_zero(),
            a.width,
            a.repr,
            a.signed,
        );
        let in_range = self.select(oversize, zero_known, shifted);

        self.select(unkamt, self.all_x(a.width, a.repr, a.signed), in_range)
    }

    /// `a >>> amt`: LRM 1800-2023 SS11.4.10 -- arithmetic right shift
    /// replicates the sign bit ONLY when the shifted operand is `signed`;
    /// on an unsigned operand `>>>` is *defined* to behave exactly like
    /// `>>` (zero-fill), regardless of the top bit's actual value. This
    /// dispatch is NOT something slang's AST already resolves: probing
    /// `Expression::binary_op()` on `a >>> b` for both an unsigned and a
    /// signed `logic [7:0]` operand shows both report
    /// `BinaryOp::ArithmeticShiftRight` identically (verified against the
    /// vendored sv-lang 0.1.9; also cross-checked against iverilog --
    /// `8'h80 >>> 4 == 8'b0000_1000`, zero-fill, not `8'b1111_1000`). So the
    /// signedness check lives here rather than being assumed away by the
    /// routing in `expr.rs`.
    ///
    /// For the signed path: same lane-separate-extraction /
    /// self-determined-amount / unknown-amount-short-circuit shape as
    /// `shl4`/`lshr4`, but each lane's vacated top bits fill with THAT
    /// LANE'S OWN sign bit independently (CG-031) -- `build_right_shift`
    /// with `sign_extend: true` on the val lane alone naturally replicates
    /// `va`'s own MSB, and applying the exact same shift to `ua` alone
    /// replicates `ua`'s own MSB, so an operand with an unknown (X/Z) MSB
    /// produces X-filled vacated bits rather than a spurious known 0/1 --
    /// this is exactly the bug the plan's own `shl4` doc comment describes
    /// for the analogous "shift the packed i(2N) blob directly" mistake, now
    /// avoided the same way for the opposite direction. A known,
    /// oversized amount shifts every original bit out; shifting by
    /// `a.width - 1` (never poison: `width - 1 < width`, and `width >= 1`
    /// always per `i_n`'s `NonZeroU32`) computes each lane's own full
    /// sign-fill directly from the same `sign_extend: true` shift, with no
    /// separate fill construction needed.
    pub fn ashr4(&self, a: PackedValue<'ctx>, amt: PackedValue<'ctx>) -> PackedValue<'ctx> {
        if !a.signed {
            return self.lshr4(a, amt);
        }
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vamt_raw, uamt) = (self.lane_val(amt), self.lane_unk(amt));

        let unkamt = self.any_unknown(uamt, self.i_n(amt.width).const_zero(), amt.width);

        let cmp_w = a.width.max(amt.width);
        let vamt_cmp = self.resize_unsigned(vamt_raw, amt.width, cmp_w);
        let oversize = self
            .b
            .build_int_compare(
                inkwell::IntPredicate::UGE,
                vamt_cmp,
                self.i_n(cmp_w).const_int(a.width as u64, false),
                "oversize",
            )
            .unwrap();

        let vamt_a = self.resize_unsigned(vamt_raw, amt.width, a.width);
        let safe_amt = self
            .b
            .build_select(oversize, self.i_n(a.width).const_zero(), vamt_a, "safe_amt")
            .unwrap()
            .into_int_value();

        let vsh = self
            .b
            .build_right_shift(va, safe_amt, true, "vashr")
            .unwrap();
        let ush = self
            .b
            .build_right_shift(ua, safe_amt, true, "uashr")
            .unwrap();
        let shifted = self.pack(vsh, ush, a.width, a.repr, a.signed);

        let full_shift = self.i_n(a.width).const_int((a.width - 1) as u64, false);
        let vfull = self
            .b
            .build_right_shift(va, full_shift, true, "vfull")
            .unwrap();
        let ufull = self
            .b
            .build_right_shift(ua, full_shift, true, "ufull")
            .unwrap();
        let fullfill = self.pack(vfull, ufull, a.width, a.repr, a.signed);

        let in_range = self.select(oversize, fullfill, shifted);

        self.select(unkamt, self.all_x(a.width, a.repr, a.signed), in_range)
    }

    /// Unary NOT: `unk' = a_unk; val' = ~a_unk & ~a_val` (ARCHITECTURE.md
    /// / codegen.md §2), applied bitwise across every lane in one pass --
    /// each lane's `val'`/`unk'` only depends on that same lane's own
    /// `val`/`unk`, so a single whole-word AND/NOT computes every lane's
    /// result at once, matching `ref4::not` lane-for-lane.
    pub fn not4(&self, a: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let up = ua;
        let vp = self.and(self.not(ua), self.not(va));
        self.pack(vp, up, a.width, a.repr, a.signed)
    }

    /// Reduction-AND (`&a`): 0 if any lane is known-0 (dominant), X if any
    /// remaining lane is unknown, else 1. Width-1 result. Mirrors
    /// `ref4word::reduce_and`.
    pub fn redand4(&self, a: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let known0 = self.and(self.not(ua), self.not(va));
        let any_known0 = self.nonzero(known0, a.width);
        let any_unk = self.nonzero(ua, a.width);
        let not_known0 = self.not(any_known0);
        let val1 = self.and(not_known0, self.not(any_unk));
        let unk1 = self.and(not_known0, any_unk);
        self.pack(val1, unk1, 1, a.repr, false)
    }
    /// Reduction-OR (`|a`): 1 if any lane is known-1 (dominant), X if any
    /// remaining lane is unknown, else 0. Width-1 result. Mirrors
    /// `ref4word::reduce_or`.
    pub fn redor4(&self, a: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let known1 = self.and(self.not(ua), va);
        let any_known1 = self.nonzero(known1, a.width);
        let any_unk = self.nonzero(ua, a.width);
        let val1 = any_known1;
        let unk1 = self.and(self.not(any_known1), any_unk);
        self.pack(val1, unk1, 1, a.repr, false)
    }
    /// XOR-fold (parity) of every bit of `v` down into bit 0, via
    /// Hillis-Steele shift-xor doubling (`ceil(log2(width))` steps): after
    /// each round `acc`'s bit `i` holds the XOR of an ever-doubling run of
    /// the original bits starting at `i`, so after the final round bit 0
    /// holds the XOR of all `width` original bits, for any `width` (power of
    /// two or not -- the out-of-range tail bits a right-shift pulls in are
    /// always zero-filled, never spurious).
    fn parity_bit(&self, v: IntValue<'ctx>, width: u32) -> IntValue<'ctx> {
        let mut acc = v;
        let mut shift = 1u32;
        while shift < width {
            let shifted = self
                .b
                .build_right_shift(
                    acc,
                    self.i_n(width).const_int(shift as u64, false),
                    false,
                    "pshr",
                )
                .unwrap();
            acc = self.xor(acc, shifted);
            shift *= 2;
        }
        self.b
            .build_int_truncate(acc, self.i_n(1), "parity")
            .unwrap()
    }
    /// Reduction-XOR (`^a`): X if any lane is unknown (unconditional --
    /// unlike AND/OR there is no dominant value for parity), else the
    /// parity of the known val bits. Width-1 result. Mirrors
    /// `ref4word::reduce_xor`.
    pub fn redxor4(&self, a: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let any_unk = self.nonzero(ua, a.width);
        let parity = self.parity_bit(va, a.width);
        let val1 = self
            .b
            .build_select(any_unk, self.i_n(1).const_zero(), parity, "redxor_val")
            .unwrap()
            .into_int_value();
        let unk1 = any_unk;
        self.pack(val1, unk1, 1, a.repr, false)
    }

    /// Logical NOT (`!a`, LRM 1800-2023 SS11.4.7, Task F1/CG-026): `1` when
    /// `a` is definitely zero, `0` when `a` has any definitely-1 bit, `x`
    /// otherwise (some X/Z bit and no known-1 bit). Reuses `redor4` (the
    /// reduction-OR helper) rather than a second truth table: `redor4`
    /// already computes exactly "is there a known-1 bit anywhere" (dominant)
    /// vs. "is there an unknown bit with no known-1 anywhere" (X) vs.
    /// "all known-0" (0) as a width-1 result, and `!a` is precisely the
    /// logical negation of that reduction -- `not4` on a width-1 operand
    /// applies its own per-lane formula (`unk' = a_unk; val' = ~a_unk &
    /// ~a_val`) to that single bit, which on a width-1 input is exactly the
    /// single-bit truth table `!` needs: known-1 -> known-0, known-0 ->
    /// known-1, X -> X (never a spurious known value, the exact CG-026
    /// regression this ledger row also names for `~`). `redor4` already
    /// forces the result width to 1 and unsigned, so the composed result is
    /// too (LRM: `!e` is always 1 bit, unsigned).
    pub fn lnot4(&self, a: PackedValue<'ctx>) -> PackedValue<'ctx> {
        self.not4(self.redor4(a))
    }

    // --- Task 6 (CG-130, CG-131, CG-132, CG-133): case equality, wildcard
    // equality, `inside`.

    /// Case equality (`===`) -- the exact CG-130 formula (codegen.md §2):
    /// pure bitwise identity over BOTH the value and unknown planes,
    /// `result = (a_val==b_val) && (a_unk==b_unk)`. Unlike every other
    /// comparison in this crate, the result is ALWAYS known (`unk=0`), even
    /// when either operand carries X/Z -- `===` asks "is this the exact
    /// same four-state bit pattern", which is itself a fully-determined
    /// question regardless of what that pattern actually is. `!==`
    /// (`BinaryOp::CaseInequality`) is lowered in `expr.rs` as a plain
    /// boolean NOT of this result (via `not4`, which reduces to a
    /// non-unk-carrying NOT since this result's own `unk` lane is always 0)
    /// rather than a second formula here.
    pub fn caseeq4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vb, ub) = (self.lane_val(b), self.lane_unk(b));
        let val_eq = self.not(self.xor(va, vb));
        let unk_eq = self.not(self.xor(ua, ub));
        let bitwise_eq = self.and(val_eq, unk_eq);
        let all_eq = self
            .b
            .build_int_compare(
                inkwell::IntPredicate::EQ,
                bitwise_eq,
                self.i_n(a.width).const_all_ones(),
                "caseeq",
            )
            .unwrap();
        self.pack(all_eq, self.i_n(1).const_zero(), 1, a.repr, false)
    }

    /// Task 10 (CG-008): the ternary `?:`'s own per-bit merge, used ONLY
    /// when the condition is ambiguous (LRM 1800-2023 SS11.4.11) -- a
    /// fundamentally different job from `is_definitely_true`'s "reduce
    /// condition to one crisp boolean" (CG-091: this stays width-preserving,
    /// never collapses to `i1`; see `is_definitely_true_is_a_distinct_
    /// function_from_ternary_merge`, tests/branch_reduction.rs). Per bit i:
    /// `result[i] = a[i]` when `a[i]` and `b[i]` are the IDENTICAL 4-state
    /// bit (both the val AND unk planes agree -- reusing `caseeq4`'s own
    /// per-bit "both planes agree" formula, just kept per-bit instead of
    /// word-reduced), else `result[i] = X`. Since this crate's `X` encoding
    /// is always `(val=0, unk=1)` (`value.rs::const_svint`'s convention),
    /// "else X" per bit is exactly `result_val[i] = same[i] & a_val[i]`
    /// (forced 0 off the `same` set) and `result_unk[i] = !same[i] |
    /// a_unk[i]` (forced 1 off the `same` set, and equal to `a`'s own unk
    /// bit -- 0 or 1 -- on it, which is correct since `a[i]==b[i]` there
    /// means `a` is the right answer when known; Table 11-20 maps the X/X
    /// and Z/Z cases to X, so an unknown agreeing bit is forced to X).
    pub fn ternary_merge4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vb, ub) = (self.lane_val(b), self.lane_unk(b));
        let val_eq = self.not(self.xor(va, vb));
        let unk_eq = self.not(self.xor(ua, ub));
        let same = self.and(val_eq, unk_eq);
        // Table 11-20: only identical KNOWN bits survive; z/z and x/x give x.
        let result_val = self.and(self.and(same, va), self.not(ua));
        let result_unk = self.or(self.not(same), ua);
        self.pack(result_val, result_unk, a.width, a.repr, a.signed)
    }

    /// Shared 4-state comparison primitive (CG-131) behind `==?`/`!=?`/
    /// `inside` (`treat_x_as_wildcard: true`) and `casez` (`treat_x_as_
    /// wildcard: false`, Task 26's first caller). Two genuinely different
    /// modes, verified against iverilog 12:
    ///
    /// - `false` (`casez`, symmetric): a Z on EITHER operand is always a
    ///   per-bit don't-care; an X on either operand is compared literally
    ///   (matches `caseeq4`'s "both val and unk planes must agree" rule at
    ///   that bit) -- so only another literal X at the exact same position
    ///   matches. The result is always known (never X): `casez` picks a
    ///   case-item branch or falls through to `default`, it does not have a
    ///   3-valued "result" of its own the way `==?` does.
    /// - `true` (`==?`/`!=?`/`inside`, CG-131, ASYMMETRIC -- IEEE
    ///   1800-2023 SS11.4.6): only `b`'s (the right-hand operand's) X/Z
    ///   bits are wildcards. `4'b1011 ==? 4'b10x1` (X on `b`) is `1`, but
    ///   `4'b10x1 ==? 4'b1011` (the same X, now on `a`) is `x`, not `1` --
    ///   a bit where `b` is a determinate 0/1 and `a` is X/Z is a genuine
    ///   ambiguity (`a`'s real bit might resolve either way), which can
    ///   make the *result itself* X, unlike the `casez` mode above. Per bit
    ///   (only reached when `b`'s bit is NOT a wildcard): `definite_
    ///   mismatch_i = a_known & (a != b)`; `ambiguous_i = !a_known` (i.e.
    ///   `a` is X/Z). Word-level reduction mirrors `and4`'s dominant-0
    ///   shape: any definite mismatch anywhere forces the whole result to a
    ///   definite 0 (dominant, since a real reason to not-match can't be
    ///   overridden by uncertainty elsewhere), else any ambiguous bit makes
    ///   it X, else it's a definite 1.
    pub fn wildcard_match(
        &self,
        a: PackedValue<'ctx>,
        b: PackedValue<'ctx>,
        treat_x_as_wildcard: bool,
    ) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vb, ub) = (self.lane_val(b), self.lane_unk(b));
        let w = a.width;

        if !treat_x_as_wildcard {
            let a_is_z = self.and(ua, va);
            let b_is_z = self.and(ub, vb);
            let dc = self.or(a_is_z, b_is_z);

            let val_eq = self.not(self.xor(va, vb));
            let unk_eq = self.not(self.xor(ua, ub));
            let literal_eq = self.and(val_eq, unk_eq);

            let match_mask = self.or(dc, literal_eq);
            let all_match = self
                .b
                .build_int_compare(
                    inkwell::IntPredicate::EQ,
                    match_mask,
                    self.i_n(w).const_all_ones(),
                    "wildmatch_z",
                )
                .unwrap();
            return self.pack(all_match, self.i_n(1).const_zero(), 1, a.repr, false);
        }

        let b_wild = ub;
        let a_known = self.not(ua);
        let eq = self.not(self.xor(va, vb));
        let definite_mismatch = self.and(self.not(b_wild), self.and(a_known, self.not(eq)));
        let ambiguous = self.and(self.not(b_wild), ua);

        let any_mismatch = self.nonzero(definite_mismatch, w);
        let any_ambiguous = self.nonzero(ambiguous, w);

        // `known1` doubles as the result's `val` lane: true exactly when
        // the whole comparison is a definite match, false in both the
        // definite-mismatch and the ambiguous case (matching every other
        // op in this file's "val=0 unless known-1" convention, e.g.
        // `and4`).
        let known1 = self.and(self.not(any_mismatch), self.not(any_ambiguous));
        let unk1 = self.and(self.not(any_mismatch), any_ambiguous);
        self.pack(known1, unk1, 1, a.repr, false)
    }

    /// `casex` (`CaseStatementCondition::WildcardXOrZ`, Task 26 review fix
    /// r1). NOT the same primitive `==?`/`inside`/`casez` share
    /// (`wildcard_match`): that formula is asymmetric (only `b`'s X/Z bits
    /// are wildcards), but IEEE 1800-2023 SS12.5's `casex` is SYMMETRIC -- an
    /// X or Z at a given bit position on EITHER the case expression (`a`) or
    /// a case item (`b`) is a per-bit don't-care. Verified against iverilog
    /// 12: `casex (2'b1x) 2'b10: ...` matches -- the SELECTOR's own X is a
    /// wildcard too, not only a label's. A bit is a wildcard whenever its
    /// unknown lane is set (`ua`/`ub`; this lane is 1 for both X and Z,
    /// distinguished only by the val lane, so testing it directly covers
    /// both without needing `casez`'s Z-only `and(u, v)` test). Per bit: a
    /// wildcard bit on either side always matches; otherwise (both operands
    /// determinate at that bit) the value bits must agree. Word-level
    /// reduction: `match_mask_i = wildcard_i | (va_i == vb_i)` -- when
    /// `wildcard_i` is true this is 1 regardless of the value bits (matches
    /// unconditionally); when false, both `ua_i` and `ub_i` are 0 so
    /// `va_i == vb_i` is exactly the literal per-bit comparison. Always
    /// known (never X), mirroring `casez`'s always-known shape -- `casex`
    /// selects a branch or falls through, it has no 3-valued "result" of its
    /// own. Mirrors `ref4word::casex_match` bit-for-bit.
    pub fn casex_match(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vb, ub) = (self.lane_val(b), self.lane_unk(b));
        let w = a.width;

        let wildcard = self.or(ua, ub);
        let val_eq = self.not(self.xor(va, vb));
        let match_mask = self.or(wildcard, val_eq);
        let all_match = self
            .b
            .build_int_compare(
                inkwell::IntPredicate::EQ,
                match_mask,
                self.i_n(w).const_all_ones(),
                "casex_match",
            )
            .unwrap();
        self.pack(all_match, self.i_n(1).const_zero(), 1, a.repr, false)
    }

    /// Wildcard equality (`==?`/`!=?`, CG-131): `==?` is exactly
    /// `wildcard_match(a, b, treat_x_as_wildcard: true)`'s asymmetric,
    /// genuinely 3-valued formula (see its doc comment) -- `!=?`
    /// (`BinaryOp::WildcardInequality`) is lowered in `expr.rs` as a
    /// boolean NOT of this result, mirroring `caseeq4`/`!==` (`not4`
    /// correctly propagates this result's X, unlike `caseeq4`'s
    /// always-known result which `not4` reduces to a plain NOT for).
    pub fn wildeq4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        self.wildcard_match(a, b, true)
    }

    /// `inside`-only (CG-132) X-propagating `>=`: single known-0/1 result,
    /// or X whenever either operand carries any unknown bit anywhere (the
    /// same "any unknown bit anywhere -> X" rule every arithmetic op in
    /// this file already follows, e.g. `add4`'s `any_unknown`-gated
    /// `all_x` fallback -- deliberately NOT a smarter bestcase/worstcase
    /// interval check: LRM 1800-2023 §11.4.5's relational operators are
    /// plainly X whenever any operand bit is unknown). Private: `inside`'s
    /// range-candidate lowering (`inside_range_candidate4`) is its only
    /// caller in this wave; Task 11 (CG-021) is expected to introduce this
    /// crate's general-purpose signed/unsigned relational operators under
    /// its own names, which may later subsume this.
    fn inside_ge4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vb, ub) = (self.lane_val(b), self.lane_unk(b));
        let pred = if a.signed {
            inkwell::IntPredicate::SGE
        } else {
            inkwell::IntPredicate::UGE
        };
        let cmp = self.b.build_int_compare(pred, va, vb, "ge").unwrap();
        let known = self.pack(cmp, self.i_n(1).const_zero(), 1, a.repr, false);
        self.select(
            self.any_unknown(ua, ub, a.width),
            self.all_x(1, a.repr, false),
            known,
        )
    }

    /// `inside`-only (CG-132) X-propagating `<=`. Mirrors `inside_ge4`.
    fn inside_le4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vb, ub) = (self.lane_val(b), self.lane_unk(b));
        let pred = if a.signed {
            inkwell::IntPredicate::SLE
        } else {
            inkwell::IntPredicate::ULE
        };
        let cmp = self.b.build_int_compare(pred, va, vb, "le").unwrap();
        let known = self.pack(cmp, self.i_n(1).const_zero(), 1, a.repr, false);
        self.select(
            self.any_unknown(ua, ub, a.width),
            self.all_x(1, a.repr, false),
            known,
        )
    }

    /// One `inside` (CG-132/CG-133) plain (non-range) candidate's
    /// contribution. IEEE 1800-2023 SS11.4.13 defines a plain candidate's
    /// contribution as exactly `x ==? item` (SS11.4.6) -- `x` (the tested
    /// expression) plays `wildcard_match`'s asymmetric `a` role and `item`
    /// (the set member) plays its `b` role, so `item`'s own X/Z bits are
    /// wildcards (a set member may legitimately contain don't-cares) while
    /// an X/Z bit in `x` at a position `item` pins to a determinate 0/1 is
    /// a genuine ambiguity. `wildcard_match`'s own result is now already
    /// exactly this genuinely 3-valued (0/1/X) per-candidate answer (see
    /// its doc comment's dominant-mismatch/else-ambiguous/else-match
    /// reduction) -- no separate ambiguity side-channel is needed on top of
    /// it. `expr.rs`'s `Inside` dispatch OR-reduces these (via `or4`)
    /// across every candidate (see also `inside_range_candidate4`).
    pub fn inside_plain_candidate4(
        &self,
        x: PackedValue<'ctx>,
        item: PackedValue<'ctx>,
    ) -> PackedValue<'ctx> {
        self.wildcard_match(x, item, true)
    }

    // --- Task 7 (CG-034, CG-035, CG-036, CG-038, CG-075): Conversion node
    // lowering (width extend/truncate, 4-state->2-state flatten, sign
    // reinterpretation).

    /// Width-extend `v` (currently `v.width` bits) to `to_width` bits
    /// (`to_width > v.width`) -- CG-035, BINDING CORRECTION 1: for `signed
    /// == true`, BOTH the value lane and the unknown lane sign-extend,
    /// each replicating its OWN original MSB (matches slang `SVInt::sext`,
    /// which sign-extends the whole four-state representation bit-for-bit,
    /// not just the numeric value -- an unknown top bit extends into MORE
    /// unknown bits, never a spuriously "known" fill; a known-negative
    /// operand's zero unk lane sign-extends to an all-zero unk lane, i.e.
    /// stays known). For `signed == false` (zero-extension), both lanes
    /// zero-extend (new high bits are 0 in both `val` and `unk`).
    pub fn extend4(&self, v: PackedValue<'ctx>, to_width: u32, signed: bool) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(v), self.lane_unk(v));
        let wide = self.i_n(to_width);
        let (ve, ue) = if signed {
            (
                self.b.build_int_s_extend(va, wide, "sext_v").unwrap(),
                self.b.build_int_s_extend(ua, wide, "sext_u").unwrap(),
            )
        } else {
            (
                self.b.build_int_z_extend(va, wide, "zext_v").unwrap(),
                self.b.build_int_z_extend(ua, wide, "zext_u").unwrap(),
            )
        };
        self.pack(ve, ue, to_width, v.repr, v.signed)
    }

    /// Width-truncate `v` to `to_width` bits (`to_width < v.width`),
    /// dropping high bits identically on both planes -- CG-035: truncation
    /// has no signedness dependence (unlike extension).
    pub fn truncate4(&self, v: PackedValue<'ctx>, to_width: u32) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(v), self.lane_unk(v));
        let narrow = self.i_n(to_width);
        let vt = self.b.build_int_truncate(va, narrow, "trunc_v").unwrap();
        let ut = self.b.build_int_truncate(ua, narrow, "trunc_u").unwrap();
        self.pack(vt, ut, to_width, v.repr, v.signed)
    }

    /// 4-state -> 2-state cast (CG-034): `known_val = val & ~unk`, computed
    /// BEFORE any width adjustment -- a Z bit (val=1,unk=1) must flatten to
    /// a definite 0, not a spurious 1 (the named bug: a raw truncate of
    /// just the value lane would keep that stray 1). Width is unchanged
    /// here; the unknown plane is forced to 0 (`v.repr` itself is left
    /// alone -- the packed representation stays whatever it already was,
    /// only its unk lane's *content* is zeroed).
    pub fn to_2state4(&self, v: PackedValue<'ctx>) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(v), self.lane_unk(v));
        let known_val = self.and(va, self.not(ua));
        self.pack(
            known_val,
            self.i_n(v.width).const_zero(),
            v.width,
            v.repr,
            v.signed,
        )
    }

    /// Task 8 (CG-037, BINDING CORRECTION 2): real -> int rounds to
    /// nearest, ties away from zero -- `slang::SVInt::fromDouble(bits,
    /// value, isSigned, round=true)` (verified against the vendored
    /// sv-lang 0.1.9 C++ source, `source/numeric/SVIntHelpers.h`'s
    /// `fromIEEE754`: a magnitude exactly at the halfway point rounds its
    /// magnitude UP, then the original sign is reapplied -- i.e. ties move
    /// away from zero, never to even). This is `$rtoi`'s DISTINCT,
    /// unimplemented, truncating sibling -- never share this function with
    /// a future `$rtoi` lowering (see `rtoi_is_a_distinct_unimplemented_
    /// path_not_the_conversion_node`, tests/real.rs).
    ///
    /// Implemented as `trunc_toward_zero(v + copysign(0.5, v))` via a
    /// genuine `fptosi`/`fptoui` instruction (never a bit-reinterpretation,
    /// per CG-037's acceptance): biasing by a signed half-ULP before
    /// truncating toward zero is arithmetically equivalent to slang's own
    /// mantissa-rounding algorithm for every finite value that fits in
    /// `to_width` bits, and is checked directly against the BINDING
    /// CORRECTION 2 cases (3.9->4, -3.9->-4, 2.5->3, -2.5->-3) in
    /// tests/real.rs.
    ///
    /// `signed` selects the destination LLVM instruction
    /// (`fptosi`/`fptoui`), taken from the Conversion node's own result
    /// type (`to_ty.is_signed()`), exactly the same "consult the
    /// destination, not the source" wiring `pack`'s caller already uses for
    /// this node. Review fix (r1, CG-037 finding 1): the prior version
    /// always emitted `fptosi` regardless of the destination's signedness.
    /// `fptosi`'s defined domain only covers the *signed* `to_width`-bit
    /// range, so for an unsigned destination (`int unsigned`, `logic
    /// [31:0]`, ...) any correctly-rounded value in the upper half of the
    /// unsigned range (>= 2^(to_width-1)) -- an entirely ordinary, in-range
    /// value, not an overflow -- was outside `fptosi`'s domain and LLVM
    /// defines that result as poison (verified: `int unsigned f(); return
    /// 3000000000.4;` folded to `ret i32 poison`, and a non-constant
    /// runtime repro of the same value returned the wrong 2147483648
    /// instead of 3000000000). `fptoui` is defined over the full unsigned
    /// `to_width`-bit range, so routing an unsigned destination there fixes
    /// it. The bias computation is unchanged (and reused as-is) for the
    /// unsigned path: real->unsigned conversion of a negative value is
    /// already a separate, already-poisonous case per this function's
    /// pre-existing NaN/Inf/overflow disclaimer below, so `fptoui` is never
    /// actually asked to convert a negative biased value on any input this
    /// function claims to support.
    ///
    /// Known, documented simplification (not covered by CG-037's acceptance
    /// or by any test in this task): unlike slang's own algorithm, `fptosi`/
    /// `fptoui` on a NaN/Inf operand or a finite magnitude too large for
    /// `to_width` bits is LLVM poison rather than slang's defined "clamp to
    /// 0" behavior. CG-037's ledger acceptance only names ordinary in-range
    /// values; a saturating conversion is left as a follow-up, not silently
    /// claimed here.
    // Review fix (r2, CG-037 findings 1 & 2): the prior version rounded via
    // `trunc_toward_zero(v + copysign(0.5, v))`, a classic double-rounding
    // bug -- the bias addition `v + 0.5` is itself an inexact f64/f32
    // operation and can round to the wrong side of an integer boundary for
    // a `v` whose fractional part is extremely close to (but strictly less
    // than) 0.5 (e.g. `v = 0.5 - f64::EPSILON/4`, ~0.49999999999999994,
    // which LRM 6.12.2 / slang's `SVInt::fromDouble` must round to 0 since
    // its exponent is below the "-1 => exactly 0.5" tie special case, but
    // the old code returned 1). Verified empirically: `v + 0.5` computed in
    // real IEEE-754 double arithmetic rounds to exactly `1.0`, so the old
    // `trunc(biased)` produced 1, off by one from the correct 0. This is
    // exactly the double-rounding trap this project's own institutional
    // memory already documents (`int'(v + 0.5)` double-rounds).
    //
    // Fixed algorithm never performs an inexact float addition as part of
    // the rounding *decision*:
    //   1. `trunc` = fptosi/fptoui(v) -- truncation toward zero. Already
    //      correct (no rounding: exact, or poison on the pre-existing
    //      disclaimed NaN/Inf/overflow domain), and still routed through
    //      the signed/unsigned-correct primitive per the r1 fix above (a
    //      `fptosi`/`fptoui` on `biased` used to be the only place that
    //      mattered; it's now `trunc`'s definition instead).
    //   2. `trunc_f` = int-to-float(trunc). Exact for every `trunc` this
    //      function actually has to round: any `v` large enough that
    //      `trunc` wouldn't round-trip exactly through the source float
    //      type has no fractional bits left at that magnitude either (`v`
    //      was already an exact integer at that ULP), so `frac` below is
    //      trivially 0 and no rounding decision is needed.
    //   3. `frac` = v - trunc_f. By Sterbenz's lemma this subtraction is
    //      *exact* (no rounding step at all) because `trunc_f` and `v`
    //      always satisfy `trunc_f/2 <= v <= 2*trunc_f` when they share a
    //      sign and `|v - trunc_f| < 1 <= |trunc_f|` -- which is exactly
    //      truncation's own guarantee -- and is trivially exact when
    //      `trunc_f == 0`.
    //   4. `|frac| >= 0.5` is an IEEE-754 float *comparison*, which is
    //      always exact (comparing two floats never rounds), so this
    //      decision matches slang's own mantissa-based algorithm bit for
    //      bit instead of going through a second lossy FP operation.
    //   5. Round away from zero by adding/subtracting exactly 1 (plain,
    //      exact integer arithmetic) from `trunc`, only when step 4 says
    //      to.
    pub fn round_real_to_int(
        &self,
        v: RealValue<'ctx>,
        to_width: u32,
        _signed: bool,
    ) -> IntValue<'ctx> {
        // Rounded in a signed i128 whatever the target, then truncated to
        // `to_width` (two's-complement wrap, as for an integer assignment):
        // `logic [7:0] v = -1.5` is 8'hFE, `logic [3:0] u = 300.2` is 12. A
        // direct `fptoui` into a narrow/unsigned target is LLVM poison for a
        // negative or out-of-range value.
        let fty = v.llvm.get_type();
        let ity = self.i_n(128);
        let zero = fty.const_float(0.0);
        let half = fty.const_float(0.5);
        let is_neg = self
            .b
            .build_float_compare(FloatPredicate::OLT, v.llvm, zero, "rti_is_neg")
            .unwrap();
        let trunc = self
            .b
            .build_float_to_signed_int(v.llvm, ity, "rti_trunc_s")
            .unwrap();
        let trunc_f = self
            .b
            .build_signed_int_to_float(trunc, fty, "rti_trunc_f_s")
            .unwrap();
        let frac = self.b.build_float_sub(v.llvm, trunc_f, "rti_frac").unwrap();
        let neg_frac = self.b.build_float_neg(frac, "rti_neg_frac").unwrap();
        let frac_is_neg = self
            .b
            .build_float_compare(FloatPredicate::OLT, frac, zero, "rti_frac_is_neg")
            .unwrap();
        let abs_frac = self
            .b
            .build_select(frac_is_neg, neg_frac, frac, "rti_abs_frac")
            .unwrap()
            .into_float_value();
        let should_round = self
            .b
            .build_float_compare(FloatPredicate::OGE, abs_frac, half, "rti_should_round")
            .unwrap();
        let one = ity.const_int(1, false);
        let neg_one = self.b.build_int_neg(one, "rti_neg_one").unwrap();
        let delta = self
            .b
            .build_select(is_neg, neg_one, one, "rti_delta")
            .unwrap()
            .into_int_value();
        let round_amt = self
            .b
            .build_select(should_round, delta, ity.const_zero(), "rti_round_amt")
            .unwrap()
            .into_int_value();
        let rounded = self
            .b
            .build_int_add(trunc, round_amt, "rti_rounded")
            .unwrap();
        match to_width.cmp(&128) {
            std::cmp::Ordering::Less => self
                .b
                .build_int_truncate(rounded, self.i_n(to_width), "rti_fit")
                .unwrap(),
            std::cmp::Ordering::Equal => rounded,
            std::cmp::Ordering::Greater => self
                .b
                .build_int_s_extend(rounded, self.i_n(to_width), "rti_fit")
                .unwrap(),
        }
    }

    /// One `inside` (CG-132/CG-133) range candidate's contribution:
    /// `lo <= x <= hi` via the X-propagating `inside_ge4`/`inside_le4`
    /// pair, ANDed through the existing 4-state `and4` -- already exactly
    /// 3-valued by construction (`and4`'s own dominant-0/else-X-if-
    /// ambiguous/else-1 rule), so no extra wrapping is needed. Exposed as
    /// its own method only so `expr.rs`'s `Inside` dispatch has one call
    /// per candidate kind, mirroring `inside_plain_candidate4`.
    pub fn inside_range_candidate4(
        &self,
        x: PackedValue<'ctx>,
        lo: PackedValue<'ctx>,
        hi: PackedValue<'ctx>,
    ) -> PackedValue<'ctx> {
        self.and4(self.inside_ge4(x, lo), self.inside_le4(x, hi))
    }

    /// `x inside {[a +/- b]}` / `{[a +%- b]}` (LRM 1800-2023 11.4.13): the
    /// range is `[a-t : a+t]` with `t = type(a)'(b)` (absolute) or
    /// `type(a)'(a*b/100.0)` (relative, the real product truncated toward
    /// zero), the two bounds swapped when `a-t > a+t` under `a`'s
    /// signedness. The relative product is formed in a width that cannot
    /// overflow and divided with a truncating `sdiv`, which equals the
    /// truncated real quotient. An unknown bit in `a` or `b` makes the match
    /// X, like any other ambiguous comparison.
    pub(crate) fn inside_tolerance_candidate4(
        &self,
        x: PackedValue<'ctx>,
        a: PackedValue<'ctx>,
        b: PackedValue<'ctx>,
        relative: bool,
    ) -> PackedValue<'ctx> {
        use std::cmp::Ordering;
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vb, ub) = (self.lane_val(b), self.lane_unk(b));
        let ext = |v: IntValue<'ctx>, from: u32, to: u32, signed: bool| -> IntValue<'ctx> {
            match from.cmp(&to) {
                Ordering::Equal => v,
                Ordering::Less if signed => self
                    .b
                    .build_int_s_extend(v, self.i_n(to), "tolsext")
                    .unwrap(),
                Ordering::Less => self
                    .b
                    .build_int_z_extend(v, self.i_n(to), "tolzext")
                    .unwrap(),
                Ordering::Greater => self
                    .b
                    .build_int_truncate(v, self.i_n(to), "toltrunc")
                    .unwrap(),
            }
        };
        let tol = if relative {
            let w = a.width + b.width + 1;
            let prod = self
                .b
                .build_int_mul(
                    ext(va, a.width, w, a.signed),
                    ext(vb, b.width, w, b.signed),
                    "tolmul",
                )
                .unwrap();
            let q = self
                .b
                .build_int_signed_div(prod, self.i_n(w).const_int(100, false), "tolpct")
                .unwrap();
            ext(q, w, a.width, false)
        } else {
            ext(vb, b.width, a.width, b.signed)
        };
        let l = self.b.build_int_sub(va, tol, "tollo").unwrap();
        let h = self.b.build_int_add(va, tol, "tolhi").unwrap();
        let pred = if a.signed {
            inkwell::IntPredicate::SGT
        } else {
            inkwell::IntPredicate::UGT
        };
        let swap = self.b.build_int_compare(pred, l, h, "tolswap").unwrap();
        let lo = self
            .b
            .build_select(swap, h, l, "tolmin")
            .unwrap()
            .into_int_value();
        let hi = self
            .b
            .build_select(swap, l, h, "tolmax")
            .unwrap()
            .into_int_value();
        let mk = |v: IntValue<'ctx>| {
            self.pack(
                ext(v, a.width, x.width, a.signed),
                self.i_n(x.width).const_zero(),
                x.width,
                x.repr,
                x.signed,
            )
        };
        let known = self.inside_range_candidate4(x, mk(lo), mk(hi));
        let unk = self
            .b
            .build_or(
                self.nonzero(ua, a.width),
                self.nonzero(ub, b.width),
                "tolunk",
            )
            .unwrap();
        self.select(unk, self.all_x(1, known.repr, false), known)
    }

    // --- Task 11 (CG-021): relational, loose-equality operators. `expr.rs`
    // dispatches `BinaryOp::{LessThan,LessThanEqual,GreaterThan,
    // GreaterThanEqual}` to the signed or unsigned pair below per the
    // signed threading from Task 4 (only `l.signed` is ever consulted --
    // the same "only ever consult the left/only operand" discipline every
    // other binary op in this file already follows, since slang's own
    // inserted `Conversion` nodes have already equalized `l`/`r`'s
    // signedness before this lowers).
    //
    // Formula (mirrors `ref4word::{ult,ule,ugt,uge,slt,sle,sgt,sge}`
    // above, bit-for-bit): any-operand-unknown-bit-anywhere -> X (1-bit),
    // else the natural signed/unsigned `build_int_compare` result. Deliberately
    // NOT the `inside_ge4`/`inside_le4` private helpers above (those are
    // scoped to `inside`'s own two fixed directions and are left
    // unrefactored per that pair's own doc comment, which already notes
    // this task "may later subsume" them -- not a requirement here).
    fn rel_cmp4(
        &self,
        a: PackedValue<'ctx>,
        b: PackedValue<'ctx>,
        pred: inkwell::IntPredicate,
    ) -> PackedValue<'ctx> {
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vb, ub) = (self.lane_val(b), self.lane_unk(b));
        let cmp = self.b.build_int_compare(pred, va, vb, "relcmp").unwrap();
        let known = self.pack(cmp, self.i_n(1).const_zero(), 1, a.repr, false);
        self.select(
            self.any_unknown(ua, ub, a.width),
            self.all_x(1, a.repr, false),
            known,
        )
    }
    /// Unsigned `<`.
    pub fn ult4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        self.rel_cmp4(a, b, inkwell::IntPredicate::ULT)
    }
    /// Unsigned `<=`.
    pub fn ule4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        self.rel_cmp4(a, b, inkwell::IntPredicate::ULE)
    }
    /// Unsigned `>`.
    pub fn ugt4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        self.rel_cmp4(a, b, inkwell::IntPredicate::UGT)
    }
    /// Unsigned `>=`.
    pub fn uge4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        self.rel_cmp4(a, b, inkwell::IntPredicate::UGE)
    }
    /// Signed `<`.
    pub fn slt4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        self.rel_cmp4(a, b, inkwell::IntPredicate::SLT)
    }
    /// Signed `<=`.
    pub fn sle4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        self.rel_cmp4(a, b, inkwell::IntPredicate::SLE)
    }
    /// Signed `>`.
    pub fn sgt4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        self.rel_cmp4(a, b, inkwell::IntPredicate::SGT)
    }
    /// Signed `>=`.
    pub fn sge4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        self.rel_cmp4(a, b, inkwell::IntPredicate::SGE)
    }

    /// Loose equality (`==`, CG-021, LRM 11.4.5): 0 when some bit position
    /// is known in both operands and differs (the relation is decided
    /// whatever the unknown bits are), else X when any bit is unknown, else
    /// 1 -- deliberately NOT `caseeq4`'s "compare both val and unk planes,
    /// always known" formula (that is `===`'s distinct rule, Task 6/CG-130).
    /// Mirrors `ref4word::eq`.
    pub fn eq4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        // LRM 11.4.5: the result is X only when the relation is ambiguous
        // because of unknown bits. A bit position where both operands are
        // known and differ already decides it: 0, whatever the unknown bits
        // elsewhere hold (Icarus agrees).
        let (va, ua) = (self.lane_val(a), self.lane_unk(a));
        let (vb, ub) = (self.lane_val(b), self.lane_unk(b));
        let both_known = self.not(self.or(ua, ub));
        let known_diff = self.and(self.xor(va, vb), both_known);
        let mismatch = self.nonzero(known_diff, a.width);
        let one = self.pack(
            self.i_n(1).const_int(1, false),
            self.i_n(1).const_zero(),
            1,
            a.repr,
            false,
        );
        let zero = self.pack(
            self.i_n(1).const_zero(),
            self.i_n(1).const_zero(),
            1,
            a.repr,
            false,
        );
        let ambiguous_or_equal = self.select(
            self.any_unknown(ua, ub, a.width),
            self.all_x(1, a.repr, false),
            one,
        );
        self.select(mismatch, zero, ambiguous_or_equal)
    }
    /// Loose inequality (`!=`, CG-021): boolean NOT of `eq4`, X-preserving
    /// (`not4` on a result whose `unk` lane may itself be 1 correctly
    /// propagates that X rather than flipping it to a crisp value) --
    /// mirrors how `!==`/`!=?` are lowered as `not4` of their positive form
    /// in `expr.rs`.
    pub fn neq4(&self, a: PackedValue<'ctx>, b: PackedValue<'ctx>) -> PackedValue<'ctx> {
        self.not4(self.eq4(a, b))
    }

    // --- Task 17 (CG-022): select / concatenation / replication -----------
    // Every primitive below is closed-form (shift/truncate/select over the
    // val/unk lanes, plus -- for `concat4`/`replicate4` -- a Rust-level loop
    // over the small, compile-time-fixed OPERAND count, never over bit
    // width): the emitted LLVM instruction count is independent of the
    // operand widths involved, the exact CG-022 acceptance
    // (`closed_form_no_bitwidth_loop_in_emitted_ir`, tests/select_concat.rs).

    /// The shared window-extraction primitive behind bit-select and every
    /// part-select form: extracts `out_width` contiguous bits starting at
    /// physical bit offset `lo` (a `base.width`-bit unsigned `IntValue`)
    /// from `base`'s own val/unk lanes, closed-form (shift + truncate).
    ///
    /// `lo_unknown` (an `i1`) folds in the "index/base itself contains an
    /// X/Z bit" failure mode, and an internal unsigned-overflow check folds
    /// in the "selected window falls partially or fully outside `base`'s
    /// range" failure mode -- LRM 1800-2023 SS11.5.1: both cases produce an
    /// all-X result for a 4-state `base` or an all-0 result for a 2-state
    /// one (`zero_or_allx`), never a partial/garbage read. Deliberately the
    /// SAME unsigned-wraparound idiom `shl4`/`lshr4` already use for an
    /// oversized runtime shift amount: `lo` arriving here already
    /// underflowed (e.g. `indexed_down_lo4` on a `base` smaller than
    /// `width - 1`) wraps to a huge unsigned value that the `UGT` compare
    /// below naturally classifies as out-of-range, with no separate
    /// negative-offset check needed.
    ///
    /// Internal invariant (callers -- `expr.rs`'s `ElementSelect`/
    /// `RangeSelect` arms -- must check this and return a `LoweringError`
    /// first, mirroring `pow4_call`'s own caller-checks-first discipline):
    /// `1 <= out_width <= base.width`.
    pub fn part_select4(
        &self,
        base: PackedValue<'ctx>,
        lo: IntValue<'ctx>,
        lo_unknown: IntValue<'ctx>,
        out_width: u32,
    ) -> PackedValue<'ctx> {
        assert!(
            out_width >= 1 && out_width <= base.width,
            "part_select4: out_width must be in 1..=base.width (callers must check this \
             and return a LoweringError first)"
        );
        let threshold = base.width - out_width;
        let oversize = self
            .b
            .build_int_compare(
                inkwell::IntPredicate::UGT,
                lo,
                self.i_n(base.width).const_int(threshold as u64, false),
                "select_oversize",
            )
            .unwrap();
        if Self::wide_dynamic(base.width, lo) {
            // Narrow the offset to i64 before the `oversize` select (a
            // register op instead of an `iN` one).
            let safe_lo = self
                .b
                .build_select(
                    oversize,
                    self.ctx.i64_type().const_zero(),
                    self.lo_as_i64(lo),
                    "select_safe_lo",
                )
                .unwrap()
                .into_int_value();
            let (wv, wu) = self.wide_window_read(base, safe_lo, out_width);
            let in_range = self.pack(wv, wu, out_width, base.repr, false);
            let bad = self.or(oversize, lo_unknown);
            return self.select(
                bad,
                self.zero_or_allx(out_width, base.repr, false),
                in_range,
            );
        }
        let safe_lo = self
            .b
            .build_select(
                oversize,
                self.i_n(base.width).const_zero(),
                lo,
                "select_safe_lo",
            )
            .unwrap()
            .into_int_value();
        let (va, ua) = (self.lane_val(base), self.lane_unk(base));
        let shifted_v = self
            .b
            .build_right_shift(va, safe_lo, false, "sel_v")
            .unwrap();
        let shifted_u = self
            .b
            .build_right_shift(ua, safe_lo, false, "sel_u")
            .unwrap();
        let trunc_v = self
            .b
            .build_int_truncate(shifted_v, self.i_n(out_width), "sel_v_t")
            .unwrap();
        let trunc_u = self
            .b
            .build_int_truncate(shifted_u, self.i_n(out_width), "sel_u_t")
            .unwrap();
        let in_range = self.pack(trunc_v, trunc_u, out_width, base.repr, false);
        let bad = self.or(oversize, lo_unknown);
        self.select(
            bad,
            self.zero_or_allx(out_width, base.repr, false),
            in_range,
        )
    }

    /// Does `idx`'s VALUE lane (compared at full, untruncated precision --
    /// `idx.width.max(limit_width)` bits, exactly `shl4`/`lshr4`'s own
    /// `cmp_w = a.width.max(amt.width)` idiom, see their doc comments)
    /// equal or exceed `limit`?
    ///
    /// This MUST run before any `resize_unsigned` of `idx`'s value down to
    /// a narrower width, because `resize_unsigned` truncates (never
    /// saturates) a too-wide value: a bare compare performed AFTER that
    /// truncation only ever sees the low bits, so it silently misclassifies
    /// any out-of-range index congruent to an in-range one mod
    /// `2^limit_width` (e.g. 256 into an 8-bit vector) as in-range.
    /// Comparing at the wider `idx.width` first keeps every high bit that
    /// truncation would otherwise discard in view for this one decision.
    fn index_value_ge(
        &self,
        idx: PackedValue<'ctx>,
        limit_width: u32,
        limit: u32,
    ) -> IntValue<'ctx> {
        let cmp_w = idx.width.max(limit_width);
        let idx_cmp = self.resize_unsigned(self.lane_val(idx), idx.width, cmp_w);
        self.b
            .build_int_compare(
                inkwell::IntPredicate::UGE,
                idx_cmp,
                self.i_n(cmp_w).const_int(limit as u64, false),
                "index_oob",
            )
            .unwrap()
    }

    /// `v[index]` (`ElementSelect`, CG-022): the 1-bit special case of
    /// `part_select4`, with `index`'s own (possibly wider/narrower, possibly
    /// X/Z-containing) value resized into `base.width`-bit space first.
    ///
    /// The resize alone would silently alias an out-of-range `index` value
    /// (`>= base.width`, e.g. 256 into an 8-bit `base`) back into range by
    /// truncation -- see `index_value_ge`'s doc comment -- so the
    /// full-precision `index_value_ge` check runs FIRST and is folded into
    /// `lo_unknown` here, ahead of the truncating resize. `part_select4`
    /// itself still guards the actual shift amount against poison via its
    /// own (truncated-space) oversize check regardless, so passing it the
    /// truncated `lo` unchanged is safe either way; only the RESULT
    /// (all-X vs. a plausible-looking real bit) depended on this check.
    pub fn bit_select4(
        &self,
        base: PackedValue<'ctx>,
        index: PackedValue<'ctx>,
    ) -> PackedValue<'ctx> {
        let oob = self.index_value_ge(index, base.width, base.width);
        let lo = self.resize_unsigned(self.lane_val(index), index.width, base.width);
        let lo_unknown = self.or(
            self.any_unknown(
                self.lane_unk(index),
                self.i_n(index.width).const_zero(),
                index.width,
            ),
            oob,
        );
        self.part_select4(base, lo, lo_unknown, 1)
    }

    /// `v[idx +: w]` (`RangeSelect` IndexedUp)'s physical low-bit offset
    /// (and its "unknown" flag), resized into `part_select4`'s own
    /// `base.width`-bit `lo` convention -- the window's low end IS `idx`
    /// itself.
    ///
    /// Same full-precision-before-truncation guard as `bit_select4`: `idx
    /// >= base_width` (checked via `index_value_ge`, which compares at
    /// `idx`'s own width when that is wider than `base_width`, never at the
    /// post-truncation `base_width` alone) is folded into `lo_unknown` so a
    /// too-wide `idx` can never alias into a plausible in-range offset via
    /// `resize_unsigned`'s truncation.
    pub fn indexed_up_lo4(
        &self,
        idx: PackedValue<'ctx>,
        base_width: u32,
    ) -> (IntValue<'ctx>, IntValue<'ctx>) {
        let oob = self.index_value_ge(idx, base_width, base_width);
        let lo = self.resize_unsigned(self.lane_val(idx), idx.width, base_width);
        let lo_unknown = self.or(
            self.any_unknown(
                self.lane_unk(idx),
                self.i_n(idx.width).const_zero(),
                idx.width,
            ),
            oob,
        );
        (lo, lo_unknown)
    }

    /// `v[idx -: w]` (`RangeSelect` IndexedDown)'s physical low-bit offset:
    /// `idx - (w - 1)`, computed entirely within `base_width` bits so an
    /// underflow (`idx < w - 1`) wraps to a huge unsigned value --
    /// `part_select4`'s own oversize check already classifies that as
    /// out-of-range, exactly like an oversized `shl4`/`lshr4` shift amount.
    ///
    /// That wraparound trick only catches an UNDERFLOW that occurs INSIDE
    /// `base_width`-bit space, though -- it says nothing about `idx` itself
    /// having a true value `>= base_width` that `resize_unsigned` would
    /// truncate away first (same failure mode as `bit_select4`/
    /// `indexed_up_lo4`). Guard that separately, at `idx`'s own full width,
    /// before the truncating resize.
    pub fn indexed_down_lo4(
        &self,
        idx: PackedValue<'ctx>,
        width_sel: u32,
        base_width: u32,
    ) -> (IntValue<'ctx>, IntValue<'ctx>) {
        let oob = self.index_value_ge(idx, base_width, base_width);
        let base_resized = self.resize_unsigned(self.lane_val(idx), idx.width, base_width);
        let sub_amt = self
            .i_n(base_width)
            .const_int((width_sel - 1) as u64, false);
        let lo = self
            .b
            .build_int_sub(base_resized, sub_amt, "idxdown_lo")
            .unwrap();
        let lo_unknown = self.or(
            self.any_unknown(
                self.lane_unk(idx),
                self.i_n(idx.width).const_zero(),
                idx.width,
            ),
            oob,
        );
        (lo, lo_unknown)
    }

    /// `{a, b, ...}` (CG-022): closed-form shift+or assembly, MSB-operand-
    /// first per SV ordering (`operands[0]` occupies the HIGHEST bits of the
    /// result -- the exact ordering a naive lane-`or`-without-correct-shift
    /// -amount implementation would get backwards). The result is always
    /// unsigned (LRM 1800-2023 SS11.4.13) and shares `operands[0]`'s own
    /// `repr` (every operand in a single lowering context shares the same
    /// ambient `ValueRepr` already).
    ///
    /// Internal invariant (callers must check this and return a
    /// `LoweringError` first): `operands` is non-empty.
    pub fn concat4(&self, operands: &[PackedValue<'ctx>]) -> PackedValue<'ctx> {
        assert!(
            !operands.is_empty(),
            "concat4: operands must be non-empty (callers must check this and return a \
             LoweringError first)"
        );
        let repr = operands[0].repr;
        let total_width: u32 = operands.iter().map(|o| o.width).sum();
        let wide = self.i_n(total_width);
        if total_width >= WIDE_PACK_BITS
            && operands
                .iter()
                .all(|o| o.width.is_multiple_of(8) && o.width > 0)
        {
            // Byte-aligned wide concat: store each operand at its byte offset
            // of one buffer per plane and load once, instead of an
            // O(operands * width) zext/shl/or chain (compile time).
            let four = repr == ValueRepr::FourState;
            let vbuf =
                shared_entry_alloca(self.ctx, self.b, wide, &format!("cat_v_buf{total_width}"));
            let ubuf =
                shared_entry_alloca(self.ctx, self.b, wide, &format!("cat_u_buf{total_width}"));
            let mut off = total_width;
            for o in operands {
                off -= o.width;
                self.b
                    .build_store(self.byte_at(vbuf, off / 8), self.lane_val(*o))
                    .unwrap();
                if four {
                    self.b
                        .build_store(self.byte_at(ubuf, off / 8), self.lane_unk(*o))
                        .unwrap();
                }
            }
            let v = self
                .b
                .build_load(wide, vbuf, "cat_v")
                .unwrap()
                .into_int_value();
            let u = if four {
                self.b
                    .build_load(wide, ubuf, "cat_u")
                    .unwrap()
                    .into_int_value()
            } else {
                wide.const_zero()
            };
            return self.pack(v, u, total_width, repr, false);
        }
        let mut acc_v = wide.const_zero();
        let mut acc_u = wide.const_zero();
        let mut offset = total_width;
        for o in operands {
            offset -= o.width;
            let ext_v = self
                .b
                .build_int_z_extend(self.lane_val(*o), wide, "cat_v_e")
                .unwrap();
            let ext_u = self
                .b
                .build_int_z_extend(self.lane_unk(*o), wide, "cat_u_e")
                .unwrap();
            let sh_v = self
                .b
                .build_left_shift(ext_v, wide.const_int(offset as u64, false), "cat_v_sh")
                .unwrap();
            let sh_u = self
                .b
                .build_left_shift(ext_u, wide.const_int(offset as u64, false), "cat_u_sh")
                .unwrap();
            acc_v = self.or(acc_v, sh_v);
            acc_u = self.or(acc_u, sh_u);
        }
        self.pack(acc_v, acc_u, total_width, repr, false)
    }

    /// `{n{x}}` (CG-022): `n` (a compile-time constant per LRM 1800-2023
    /// SS11.4.12) repetitions of `unit`, closed-form over the small,
    /// compile-time-fixed `n` -- exactly `concat4` of `unit` repeated `n`
    /// times.
    ///
    /// Internal invariant (callers must check this and return a
    /// `LoweringError` first): `count >= 1`.
    pub fn replicate4(&self, unit: PackedValue<'ctx>, count: u32) -> PackedValue<'ctx> {
        assert!(
            count >= 1,
            "replicate4: count must be >= 1 (callers must check this and return a \
             LoweringError first)"
        );
        let operands = vec![unit; count as usize];
        self.concat4(&operands)
    }

    // --- Task 12 (CG-134, CG-135, CG-136, CG-137): power (`**`) ------------

    /// Shared negative-exponent LRM rule (CG-137, 1800-2023 §11.4.9): given
    /// the exponent's sign is already known negative and its PARITY
    /// (`exp_is_odd`, an `i1` -- either an LLVM constant when the caller
    /// knows it at Rust build time, e.g. `pow4_const`, or a genuine runtime
    /// value, e.g. `get_or_build_ipow_fn`'s shared helper body, which is
    /// exactly why this takes an `IntValue` rather than a Rust `bool`: this
    /// one function's body is the ONLY place CG-137's arithmetic is
    /// implemented, reused verbatim by both the constant- and
    /// runtime-exponent paths rather than being independently
    /// re-implemented per call site), the result is `0` unless:
    /// - the base is (definitely) `0` -- LRM/slang `SVInt::pow`
    ///   (`source/numeric/SVInt.cpp`'s `lhsBits == 0` case): `0 ** -y` is
    ///   mathematically undefined, so it is all-X in 4-state mode, exactly
    ///   like this crate's own `div4`/`mod4` divide-by-runtime-zero rule
    ///   (codegen.md §2) -- `pack`'s `TwoState` arm discards the `unk` lane
    ///   entirely, so 2-state mode still degrades to the definite `0`
    ///   already computed below, matching `div4`/`mod4`'s own
    ///   2-state-vs-4-state split for this same "indeterminate" shape;
    /// - the base is `1` (-> `1`); or
    /// - -- only when `check_neg_one` (the base's own signedness, see
    ///   `pow4_const`/`pow4_call`'s doc comments) -- the base is `-1` (->
    ///   `1` if the exponent is even, `-1` if odd).
    ///
    /// Fully `select`-based over `base`'s own val/unk lanes (no branch, no
    /// call): any unknown bit in `base` still forces all-X, the one
    /// remaining "any-unknown-propagates" source once the exponent itself is
    /// already a definite value. `check_neg_one` gates the `base == -1`
    /// branch on whether `-1` is even a value the base's OWN declared
    /// signedness can represent -- an all-ones bit pattern on an UNSIGNED
    /// base is its maximum representable value (2^width - 1), never the
    /// integer -1, so that branch must not fire for it (mirrors
    /// `div4`/`mod4`'s "only ever consult the left/base operand's `signed`"
    /// discipline).
    fn pow_neg_exp_result(
        &self,
        base: PackedValue<'ctx>,
        exp_is_odd: IntValue<'ctx>,
        check_neg_one: bool,
    ) -> PackedValue<'ctx> {
        let width = base.width;
        let base_val = self.lane_val(base);
        let base_unk = self.lane_unk(base);
        let ty = self.i_n(width);
        let one = ty.const_int(1, false);
        let all_ones = ty.const_all_ones();
        let zero = ty.const_zero();
        let is_zero = self
            .b
            .build_int_compare(inkwell::IntPredicate::EQ, base_val, zero, "ipow_is_zero")
            .unwrap();
        let is_one = self
            .b
            .build_int_compare(inkwell::IntPredicate::EQ, base_val, one, "ipow_is_one")
            .unwrap();
        let neg1_result = self
            .b
            .build_select(exp_is_odd, all_ones, one, "ipow_neg1_result")
            .unwrap()
            .into_int_value();
        let neg_branch = if check_neg_one {
            let is_negone = self
                .b
                .build_int_compare(
                    inkwell::IntPredicate::EQ,
                    base_val,
                    all_ones,
                    "ipow_is_negone",
                )
                .unwrap();
            self.b
                .build_select(is_negone, neg1_result, zero, "ipow_negone_sel")
                .unwrap()
                .into_int_value()
        } else {
            zero
        };
        let final_val = self
            .b
            .build_select(is_one, one, neg_branch, "ipow_neg_result")
            .unwrap()
            .into_int_value();
        // `0 ** -y == x` (base known-zero, negative exponent): force the
        // KNOWN-base result itself to all-X in 4-state mode -- distinct from
        // (and additional to) the `nonzero(base_unk, ...)` guard just below,
        // which only catches an ALREADY-unknown base, never a definitely-
        // zero one. `pack`'s `TwoState` arm discards this `unk` lane, so
        // 2-state mode is unaffected (stays the definite `0` in `final_val`
        // above).
        let zero_base_unk = self
            .b
            .build_select(is_zero, all_ones, zero, "ipow_zero_base_unk")
            .unwrap()
            .into_int_value();
        let known = self.pack(final_val, zero_base_unk, width, base.repr, base.signed);
        self.select(
            self.nonzero(base_unk, width),
            self.all_x(width, base.repr, base.signed),
            known,
        )
    }

    /// CG-134: `**` with a compile-time-constant, DEFINITE (non-X/Z, fits in
    /// an `i64`) exponent -- exponentiation-by-squaring unrolled entirely at
    /// RUST BUILD TIME via a sequence of plain `build_int_mul` calls, so the
    /// emitted IR is a pure multiply chain with ZERO `call` instructions
    /// (`const_exponent_unrolls_no_call_instruction`) and zero runtime
    /// branches. The negative-exponent case (CG-137) is not a squaring
    /// shape at all -- the exponent is compile-time constant but the BASE
    /// can still be an arbitrary runtime value -- so it is delegated to
    /// `pow_neg_exp_result`, itself equally call-free/branch-free. The
    /// caller (`expr.rs`'s `BinaryOp::Power` arm) is the one place that
    /// decides whether a given `**` even reaches this function: it first
    /// tries `Expression::constant_value()` on the exponent operand and
    /// `SVInt::as_i64()` on the result, which already returns `None`
    /// (routing to `pow4_call` instead) whenever the constant has any
    /// unknown (X/Z) bit or doesn't fit in 64 bits -- so `exp` here is
    /// always a definite value, needing no unknown-check of its own; only
    /// `base`'s own unknown-ness is still a live concern.
    ///
    /// `exp == 0`: the squaring loop below never executes a multiply for
    /// this case, so an unknown `base` would NOT be caught by any
    /// individual `build_int_mul`'s neighboring unknown-check the way it
    /// is for `exp > 0` (each nonzero-exponent step's own multiply
    /// propagates an unknown `base` transitively) -- covered instead by the
    /// explicit top-level `select(any_unknown(base), all_x, known)` guard at
    /// the end of this function, mirroring `add4`/`mul4`/`div4`'s own
    /// top-level guard shape rather than relying on an incidental property
    /// of the loop.
    pub fn pow4_const(&self, base: PackedValue<'ctx>, exp: i64) -> PackedValue<'ctx> {
        if exp < 0 {
            let exp_is_odd = (exp & 1) != 0;
            let exp_is_odd_val = self.ctx.bool_type().const_int(exp_is_odd as u64, false);
            return self.pow_neg_exp_result(base, exp_is_odd_val, base.signed);
        }
        let width = base.width;
        let base_val = self.lane_val(base);
        let base_unk = self.lane_unk(base);
        let ty = self.i_n(width);
        let mut result = ty.const_int(1, false);
        let mut cur = base_val;
        let mut e = exp as u64;
        while e > 0 {
            if e & 1 == 1 {
                result = self.b.build_int_mul(result, cur, "ipow_step").unwrap();
            }
            e >>= 1;
            if e > 0 {
                cur = self.b.build_int_mul(cur, cur, "ipow_sq").unwrap();
            }
        }
        let known = self.pack(result, ty.const_zero(), width, base.repr, base.signed);
        self.select(
            self.nonzero(base_unk, width),
            self.all_x(width, base.repr, base.signed),
            known,
        )
    }

    /// Gets (if already declared in `module`, matching Task 21's future
    /// `EntityTag::Helper`-style "declare once, reuse" shape) or builds the
    /// shared `sv_ipow_{u,s}{width}` LLVM function used by `pow4_call`.
    /// Named/typed purely by `(width, signed)` -- see `pow4_call`'s doc
    /// comment for why that alone is enough for every caller's copy to be
    /// byte-identical (the `linkonce_odr` precondition).
    ///
    /// Operates ENTIRELY in this crate's canonical 4-state packed `i(2*
    /// width)` representation for `base`/the result, regardless of the
    /// ORIGINAL caller's `ValueRepr` (`pow4_call` converts at the call
    /// site) -- decouples the shared symbol from the whole-program 2-state/
    /// 4-state build-mode flag (ARCHITECTURE.md: "2-state mode: whole-
    /// program build-mode flag, one representation per compiled design"),
    /// so the same two symbol names (`sv_ipow_u{width}`/`sv_ipow_s{width}`)
    /// are correct and reusable regardless of which mode the whole design
    /// was compiled in.
    ///
    /// The exponent argument is a plain signed `i64` (`%exp_val`) plus a
    /// single `%exp_has_unknown` bit, NOT a packed value of its own width --
    /// `pow4_call` sign-/zero-extends the caller's actual exponent (per ITS
    /// OWN, independently-tracked signedness) to `i64` before the call, so
    /// this function's body can always treat `%exp_val` uniformly as signed
    /// without needing a second axis in its name (see `pow4_call`'s doc
    /// comment).
    ///
    /// Body, entirely `select`-based (no branches, matching this file's
    /// existing arithmetic-op style, e.g. `add4`/`div4`):
    /// 1. `abs_exp` = `|exp_val|` (64-bit unsigned magnitude, `select`ed on
    ///    `exp_val < 0`).
    /// 2. Exponentiation-by-squaring over `abs_exp`'s 64 bits, fully
    ///    unrolled into 64 static `select`+`mul` steps (a runtime bit of
    ///    `abs_exp` chooses whether each step's multiply is folded in) --
    ///    the dynamic-exponent analogue of `pow4_const`'s Rust-level
    ///    unrolling.
    /// 3. The CG-137 negative-exponent special case, via a direct call to
    ///    the SAME `pow_neg_exp_result` helper `pow4_const` uses (not a
    ///    second, independent reimplementation) -- its `exp_is_odd` param is
    ///    an `IntValue` precisely so this runtime-parity call site (`exp_val`
    ///    `%64`'s own low bit, which correctly reflects two's-complement
    ///    parity regardless of sign) and `pow4_const`'s Rust-`bool` call
    ///    site can share one body.
    /// 4. Select between 2/3 on `exp_val < 0`, then force the whole result
    ///    to all-X if `base_unk != 0`, `%exp_has_unknown`, or step 3's own
    ///    result already carries an unknown lane (its zero-base/negative-
    ///    exponent case) -- the general arithmetic any-unknown-propagates
    ///    rule (CG-135's acceptance).
    fn get_or_build_ipow_fn(
        &self,
        module: &Module<'ctx>,
        width: u32,
        exp_width: u32,
        signed: bool,
    ) -> FunctionValue<'ctx> {
        // An exponent of at most 64 bits arrives as an `i64` (the original
        // `sv_ipow_{u,s}{width}` shape). A wider one (LRM 11.4.3 leaves the
        // exponent self-determined, so `bit [199:0]` is ordinary) arrives at
        // its own width, in a `_e{exp_width}` variant.
        let wide_exp = exp_width > 64;
        let name = if wide_exp {
            format!(
                "sv_ipow_{}{}_e{}",
                if signed { "s" } else { "u" },
                width,
                exp_width
            )
        } else {
            format!("sv_ipow_{}{}", if signed { "s" } else { "u" }, width)
        };
        if let Some(f) = module.get_function(&name) {
            return f;
        }

        let packed_ty = self.i_n(width * 2);
        let i64_ty = if wide_exp {
            self.i_n(exp_width)
        } else {
            self.ctx.i64_type()
        };
        let bool_ty = self.ctx.bool_type();
        // Task 12 r2 review-finding fix: a 4th `i1` parameter,
        // `%exp_is_negative`, carries the CALLER's own (`pow4_call`,
        // computed from `exp.signed`) determination of whether `%exp_val`
        // should be treated as a negative exponent -- this function's body
        // must NOT re-derive that itself via a blind `icmp slt %exp_val, 0`
        // on the raw 64-bit pattern (see the doc comment below and
        // `pow4_call`'s call site for why that re-derivation is wrong for a
        // width==64 UNSIGNED exponent whose value has bit 63 set).
        let fn_ty = packed_ty.fn_type(
            &[
                packed_ty.into(),
                i64_ty.into(),
                bool_ty.into(),
                bool_ty.into(),
            ],
            false,
        );
        let f = module.add_function(&name, fn_ty, Some(Linkage::LinkOnceODR));

        // A fresh `Builder`/`OpBuilder`, NOT `self.b` -- `self` is scoped to
        // the CALLER's own function/insertion point (a different LLVM
        // `FunctionValue` entirely); building this helper's body must not
        // disturb the caller's builder position. `OpBuilder`'s methods only
        // ever need `ctx`/`b`, so a second, independent `OpBuilder` wrapping
        // this new `Builder` reuses `lane_val`/`lane_unk`/`pack`/`all_x`/
        // `nonzero`/`select` verbatim for this function's own body.
        let builder = self.ctx.create_builder();
        let entry = self.ctx.append_basic_block(f, "entry");
        builder.position_at_end(entry);
        let body = OpBuilder {
            ctx: self.ctx,
            b: &builder,
        };

        let base_packed = f.get_nth_param(0).unwrap().into_int_value();
        let exp_val = f.get_nth_param(1).unwrap().into_int_value();
        let exp_is_negative = f.get_nth_param(2).unwrap().into_int_value();
        let exp_has_unknown = f.get_nth_param(3).unwrap().into_int_value();

        let base_as_pv = PackedValue {
            llvm: base_packed,
            width,
            repr: ValueRepr::FourState,
            signed,
        };
        let base_val = body.lane_val(base_as_pv);
        let base_unk = body.lane_unk(base_as_pv);

        let ity = body.i_n(width);
        let zero = ity.const_zero();
        let one = ity.const_int(1, false);
        let all_ones = ity.const_all_ones();

        // Task 12 r2 review-finding fix: `exp_neg` is the CALLER-supplied
        // `%exp_is_negative` param verbatim, never re-derived here via
        // `icmp slt %exp_val, 0`. The old in-body derivation was wrong for a
        // width==64 UNSIGNED exponent whose raw bit pattern has bit 63 set
        // (a huge positive magnitude, e.g. >= 2^63): `%exp_val` alone has no
        // headroom left to also encode "treat me as unsigned", so re-reading
        // its top bit as a sign bit silently misrouted such a value through
        // the CG-137 negative-exponent branch. `pow4_call` computes
        // `%exp_is_negative` from `exp.signed` (a Rust-level, statically
        // known bool) instead, which can never be swayed by the runtime bit
        // pattern.
        let exp_neg = exp_is_negative;
        let neg_exp_val = builder.build_int_neg(exp_val, "ipow_exp_neg_mag").unwrap();
        let abs_exp = builder
            .build_select(exp_neg, neg_exp_val, exp_val, "ipow_abs_exp")
            .unwrap()
            .into_int_value();

        // Exponentiation-by-squaring, 64 static unrolled steps (one per
        // `abs_exp` bit -- `exp_val` is a plain `i64`, so 64 steps always
        // fully covers it regardless of `width`; fewer steps would silently
        // drop any exponent bit set at or above that smaller bound).
        let mut result = one;
        let mut cur = base_val;
        // A wide exponent needs only its low `min(exp_width, width)` bits:
        // an even base is 0 mod 2^width once the exponent reaches `width`,
        // and the odd residues form a group of order 2^(width-2), so the
        // bits at or above `width` never change the result.
        let steps: u64 = if wide_exp {
            u64::from(exp_width.min(width))
        } else {
            64
        };
        for i in 0..steps {
            let shifted = builder
                .build_right_shift(abs_exp, i64_ty.const_int(i, false), false, "ipow_sh")
                .unwrap();
            let bit = builder
                .build_and(shifted, i64_ty.const_int(1, false), "ipow_bit")
                .unwrap();
            let bit_set = builder
                .build_int_compare(
                    inkwell::IntPredicate::NE,
                    bit,
                    i64_ty.const_zero(),
                    "ipow_bit_set",
                )
                .unwrap();
            let mul_step = builder.build_int_mul(result, cur, "ipow_step").unwrap();
            result = builder
                .build_select(bit_set, mul_step, result, "ipow_step_sel")
                .unwrap()
                .into_int_value();
            if i != steps - 1 {
                cur = builder.build_int_mul(cur, cur, "ipow_sq").unwrap();
            }
        }
        // The dropped high exponent bits still matter for an even base: a
        // nonzero value up there means the exponent is >= 2^width >= width,
        // so the power is 0.
        if wide_exp && steps < u64::from(exp_width) {
            let high = builder
                .build_right_shift(abs_exp, i64_ty.const_int(steps, false), false, "ipow_high")
                .unwrap();
            let high_set = builder
                .build_int_compare(
                    inkwell::IntPredicate::NE,
                    high,
                    i64_ty.const_zero(),
                    "ipow_high_set",
                )
                .unwrap();
            let base_low = builder.build_and(base_val, one, "ipow_base_low").unwrap();
            let base_even = builder
                .build_int_compare(inkwell::IntPredicate::EQ, base_low, zero, "ipow_base_even")
                .unwrap();
            let zeroed = builder
                .build_and(high_set, base_even, "ipow_zeroed")
                .unwrap();
            result = builder
                .build_select(zeroed, zero, result, "ipow_high_sel")
                .unwrap()
                .into_int_value();
        }
        let pos_result = result;

        // CG-137 negative-exponent special case: delegate to the SAME
        // `pow_neg_exp_result` helper `pow4_const` uses, rather than an
        // independent re-implementation -- the one review-flagged gap this
        // crate must not repeat (two hand-written copies of one LRM rule,
        // only one of them under test). `exp_is_odd` is only known at
        // runtime here (unlike `pow4_const`'s Rust-level `bool`), which is
        // exactly why `pow_neg_exp_result` takes an `IntValue` `i1` rather
        // than a `bool`.
        let exp_is_odd = builder
            .build_int_truncate(exp_val, bool_ty, "ipow_exp_odd")
            .unwrap();
        let neg_case_pv = body.pow_neg_exp_result(base_as_pv, exp_is_odd, signed);
        let neg_case_val = body.lane_val(neg_case_pv);
        let neg_case_unk = body.lane_unk(neg_case_pv);

        let selected = builder
            .build_select(exp_neg, neg_case_val, pos_result, "ipow_selected")
            .unwrap()
            .into_int_value();
        let selected_unk = builder
            .build_select(exp_neg, neg_case_unk, zero, "ipow_selected_unk")
            .unwrap()
            .into_int_value();

        let base_has_unknown = body.nonzero(base_unk, width);
        // `selected_unk` carries `pow_neg_exp_result`'s own internal
        // "indeterminate" reasons (the CG-137 zero-base/negative-exponent
        // case, and its own base-unknown guard, both already folded in
        // above) -- ORed in alongside the general "either operand carries an
        // unknown bit" rule so a `pos_result`-path (non-negative exponent)
        // unknown base is still caught by `base_has_unknown` directly.
        let selected_has_unknown = body.nonzero(selected_unk, width);
        let any_unknown = builder
            .build_or(
                builder
                    .build_or(base_has_unknown, exp_has_unknown, "ipow_any_unknown_be")
                    .unwrap(),
                selected_has_unknown,
                "ipow_any_unknown",
            )
            .unwrap();
        let final_val = builder
            .build_select(any_unknown, zero, selected, "ipow_final_val")
            .unwrap()
            .into_int_value();
        let final_unk = builder
            .build_select(any_unknown, all_ones, zero, "ipow_final_unk")
            .unwrap()
            .into_int_value();

        let packed_result = body.pack(final_val, final_unk, width, ValueRepr::FourState, signed);
        builder.build_return(Some(&packed_result.llvm)).unwrap();

        // Internal-invariant check (mirrors `func.rs::lower_function`'s own
        // `f.verify()` guard on user-authored bodies) -- this body is
        // entirely generated by this function itself, so a verify failure
        // here is a codegen bug, not a user-input error; there is no
        // `LoweringError` plumbed through this non-`Result` API for it to
        // report through, so it is a loud, immediate `expect` rather than a
        // silently-accepted broken function.
        assert!(f.verify(true), "sv_ipow helper function failed LLVM verify");

        f
    }

    /// CG-135/CG-136: `**` with a non-compile-time-constant exponent --
    /// declares/reuses a shared `sv_ipow_{u,s}{width}` LLVM function in
    /// `module` (via `get_or_build_ipow_fn`) and emits a `call` to it,
    /// NEVER `llvm.pow` (CG-136's negative acceptance --
    /// `runtime_exponent_emits_sv_ipow_call_never_llvm_pow` asserts both
    /// halves: a `call` to a `sv_ipow_`-prefixed function exists, and no
    /// `llvm.pow` reference exists anywhere in the emitted IR).
    ///
    /// Cross-module linkage discipline (Task 12 plan note, resolving a
    /// blocking review finding): see `get_or_build_ipow_fn`'s doc comment --
    /// `linkonce_odr`, not `external`, so two independently-lowered Modules
    /// that both need `sv_ipow_{u,s}{width}` collapse into one definition
    /// under ORC v2 or a standard linker rather than conflicting
    /// (`two_modules_both_defining_sv_ipow_merge_without_duplicate_symbol_
    /// conflict`). This crate's Task 21 `EntityTag::Helper` machinery
    /// (not yet landed when this task runs) is deliberately not used: that
    /// mechanism is for symbols needing per-`CodegenSession` dedup
    /// bookkeeping because their body varies per call site, which does not
    /// apply here -- `sv_ipow_{u,s}{width}`'s body is fully determined by
    /// `(width, signed)` alone, so every worker's copy is genuinely
    /// byte-identical and `linkonce_odr` alone is sufficient.
    ///
    /// `signed` selects the function VARIANT by the BASE's own signedness
    /// (mirrors `div4`/`mod4`'s "only ever consult the left/base operand's
    /// `signed`" discipline) -- it gates whether the LRM `base == -1`
    /// special case (CG-137) is even checkable inside the shared body,
    /// exactly like `pow_neg_exp_result`'s `check_neg_one` parameter.
    /// `expr.rs`'s `BinaryOp::Power` arm always passes `base.signed` here.
    ///
    /// The EXPONENT's own, independent signedness (it is self-determined
    /// per LRM 1800-2023 and can genuinely differ from the base's --
    /// verified against iverilog 12: a base declared UNSIGNED still
    /// correctly honors a narrower SIGNED exponent's own negative value,
    /// rather than reinterpreting its bit pattern as a huge unsigned
    /// magnitude the way a context-determined/equalized operand would) is
    /// read directly off `exp.signed` HERE, at the call site, and folded
    /// into a single sign- or zero-extended `i64` argument before the call,
    /// PLUS (Task 12 r2 review-finding fix) an explicit `%exp_is_negative`
    /// `i1` computed from that same `exp.signed` -- never re-derived inside
    /// the shared helper by re-reading the `i64` argument's own top bit,
    /// which is ambiguous exactly at `exp.width == 64`: an UNSIGNED 64-bit
    /// exponent whose real value is >= 2^63 has its top bit set too, and a
    /// blind `icmp slt` would misread that huge positive magnitude as
    /// negative. See `get_or_build_ipow_fn`'s doc comment for the full
    /// argument. `exp`'s own width is capped at 64 bits here, matching this
    /// crate's existing P0 "<=64-bit" convention (`value.rs::const_svint`'s
    /// own assert) -- callers (`expr.rs`'s `BinaryOp::Power` arm) check this
    /// BEFORE calling in and return a `LoweringError` for a wider exponent
    /// type rather than ever reaching the `assert!` below, which exists only
    /// as a defensive internal invariant for this function's own direct
    /// callers, not as the user-facing error path.
    pub fn pow4_call(
        &self,
        module: &Module<'ctx>,
        base: PackedValue<'ctx>,
        exp: PackedValue<'ctx>,
        signed: bool,
    ) -> PackedValue<'ctx> {
        let f = self.get_or_build_ipow_fn(module, base.width, exp.width, signed);

        let base_packed4 = self.pack(
            self.lane_val(base),
            self.lane_unk(base),
            base.width,
            ValueRepr::FourState,
            base.signed,
        );

        let exp_val = self.lane_val(exp);
        let exp_unk = self.lane_unk(exp);
        let exp_has_unknown = self.nonzero(exp_unk, exp.width);
        let i64_ty = self.ctx.i64_type();
        let exp_val_ext = match exp.width.cmp(&64) {
            // A wider exponent is passed at its own width.
            std::cmp::Ordering::Greater => exp_val,
            std::cmp::Ordering::Equal => exp_val,
            std::cmp::Ordering::Less if exp.signed => self
                .b
                .build_int_s_extend(exp_val, i64_ty, "ipow_exp_sext")
                .unwrap(),
            std::cmp::Ordering::Less => self
                .b
                .build_int_z_extend(exp_val, i64_ty, "ipow_exp_zext")
                .unwrap(),
        };

        // Task 12 r2 review-finding fix: whether `exp_val_ext` represents a
        // NEGATIVE exponent is decided HERE, from `exp.signed` (a
        // Rust-level, statically known bool), not by the shared helper
        // re-reading `exp_val_ext`'s own top bit. That distinction only
        // matters at `exp.width == 64` (for width < 64 the sign-/zero-
        // extension above already guarantees the extended `i64`'s sign bit
        // agrees with the true signedness) -- an UNSIGNED 64-bit exponent is
        // never negative, full stop, regardless of whether its value has
        // bit 63 set, so this is a compile-time-constant-folded `false` for
        // that case rather than any runtime bit-pattern comparison.
        let exp_is_negative = if exp.signed {
            self.b
                .build_int_compare(
                    inkwell::IntPredicate::SLT,
                    exp_val_ext,
                    exp_val_ext.get_type().const_zero(),
                    "ipow_exp_is_negative",
                )
                .unwrap()
        } else {
            self.ctx.bool_type().const_zero()
        };

        let call = self
            .b
            .build_call(
                f,
                &[
                    base_packed4.llvm.into(),
                    exp_val_ext.into(),
                    exp_is_negative.into(),
                    exp_has_unknown.into(),
                ],
                "ipow_call",
            )
            .unwrap();
        let packed_result = call.try_as_basic_value().unwrap_basic().into_int_value();
        let result4 = PackedValue {
            llvm: packed_result,
            width: base.width,
            repr: ValueRepr::FourState,
            signed: base.signed,
        };
        match base.repr {
            ValueRepr::FourState => result4,
            // A genuinely 2-state `base`/`exp` (the whole-program build
            // mode, ARCHITECTURE.md) always produced an all-zero unk lane
            // into the call, so `result4`'s own unk lane is already
            // guaranteed all-zero too -- just re-pack the extracted value
            // lane back into a plain `iN` `TwoState` `PackedValue`, no
            // masking/flattening needed (unlike CG-034's `logic`->`bit`
            // cast, which must actively discard a REAL possible X/Z).
            ValueRepr::TwoState => self.pack(
                self.lane_val(result4),
                self.i_n(base.width).const_zero(),
                base.width,
                ValueRepr::TwoState,
                base.signed,
            ),
        }
    }

    // --- Task 15 (CG-016, CG-019, CG-129): wide value storage -------------
    //
    // A wide value's `WideValueRef` points at `limb_count` consecutive
    // `{aval: i64, bval: i64}` limbs on the stack (`svLogicVecVal`'s own
    // word layout per this task's ledger rows, least-significant limb
    // first). Modeled as `[limb_count x {i64, i64}]` so `wide_limb_ptr`'s
    // GEP does the least-significant-limb-first indexing arithmetic once,
    // shared by both the store and load sides.
    fn wide_limb_type(&self) -> inkwell::types::StructType<'ctx> {
        let i64t = self.ctx.i64_type();
        self.ctx.struct_type(&[i64t.into(), i64t.into()], false)
    }

    /// Allocates stack storage for a `WideValueRef` of `limb_count` limbs
    /// (CG-129's memory descriptor).
    pub fn wide_alloca(&self, limb_count: u32, name: &str) -> WideValueRef<'ctx> {
        assert!(limb_count > 0, "a wide value needs at least one limb");
        let arr_ty = self.wide_limb_type().array_type(limb_count);
        let base_ptr = crate::types::entry_alloca_in(self.b, arr_ty, name);
        WideValueRef {
            base_ptr,
            limb_count,
        }
    }

    fn wide_limb_ptr(&self, w: WideValueRef<'ctx>, idx: u32) -> PointerValue<'ctx> {
        assert!(
            idx < w.limb_count,
            "wide limb index {idx} out of range (limb_count={})",
            w.limb_count
        );
        let limb_ty = self.wide_limb_type();
        let arr_ty = limb_ty.array_type(w.limb_count);
        let idx0 = self.ctx.i32_type().const_zero();
        let idxn = self.ctx.i32_type().const_int(idx as u64, false);
        // SAFETY: `w.base_ptr` was produced by `wide_alloca` and always
        // points at exactly one live `[w.limb_count x {i64,i64}]` alloca;
        // `idx < w.limb_count` is asserted just above, so `[0, idx]` is an
        // in-bounds GEP into that same allocation (first index steps
        // through the pointer-to-array, second selects the element).
        unsafe {
            self.b
                .build_gep(arr_ty, w.base_ptr, &[idx0, idxn], "limb_ptr")
                .unwrap()
        }
    }

    /// Stores `(aval, bval)` into limb `idx` of `w`.
    pub fn wide_store_limb(
        &self,
        w: WideValueRef<'ctx>,
        idx: u32,
        aval: IntValue<'ctx>,
        bval: IntValue<'ctx>,
    ) {
        let limb_ty = self.wide_limb_type();
        let limb_ptr = self.wide_limb_ptr(w, idx);
        let aval_ptr = self
            .b
            .build_struct_gep(limb_ty, limb_ptr, 0, "aval_ptr")
            .unwrap();
        let bval_ptr = self
            .b
            .build_struct_gep(limb_ty, limb_ptr, 1, "bval_ptr")
            .unwrap();
        self.b.build_store(aval_ptr, aval).unwrap();
        self.b.build_store(bval_ptr, bval).unwrap();
    }

    /// Loads limb `idx` of `w` back out as `(aval, bval)`.
    pub fn wide_load_limb(
        &self,
        w: WideValueRef<'ctx>,
        idx: u32,
    ) -> (IntValue<'ctx>, IntValue<'ctx>) {
        let limb_ty = self.wide_limb_type();
        let limb_ptr = self.wide_limb_ptr(w, idx);
        let aval_ptr = self
            .b
            .build_struct_gep(limb_ty, limb_ptr, 0, "aval_ptr")
            .unwrap();
        let bval_ptr = self
            .b
            .build_struct_gep(limb_ty, limb_ptr, 1, "bval_ptr")
            .unwrap();
        let i64t = self.ctx.i64_type();
        let aval = self
            .b
            .build_load(i64t, aval_ptr, "aval")
            .unwrap()
            .into_int_value();
        let bval = self
            .b
            .build_load(i64t, bval_ptr, "bval")
            .unwrap()
            .into_int_value();
        (aval, bval)
    }

    // --- Task 16 (CG-138, CG-173, CG-020): wide arithmetic + narrow<->wide
    // gather/scatter ---------------------------------------------------
    //
    // Every wide computation is still expressed in narrow i(2N) SSA form
    // per limb (CG-138): `wide_add` decodes each limb's (aval,bval) plane
    // pair to (val,unk) via `value::{aval_bval_to_bit-equivalent
    // arithmetic}` (the `val = aval^bval, unk = bval` identity -- see
    // below), does the limb's arithmetic as a plain 64-bit narrow op with
    // an EXPLICIT carry-in/out threaded to the next limb, then re-encodes
    // back to (aval,bval) for storage. `wide_gather`/`wide_scatter` are the
    // general narrow<->wide bridge for any width <= WIDE_THRESHOLD (used
    // by `wide_add`'s tests directly, and by any future caller that needs
    // to hand a wide slice to a narrow-only operator or vice versa).
    //
    // (aval,bval) <-> (val,unk) identity, derived directly from
    // `value::{aval_bval_to_bit,bit_to_aval_bval}`'s truth table: `bval`
    // and `unk` are literally the same bit (Z and X are exactly the two
    // states where the narrow path's `unk` is 1, and `bval` is 1 for
    // exactly those two states too); `aval = val XOR unk` (Zero
    // val=0,unk=0,aval=0; One val=1,unk=0,aval=1; Z val=1,unk=1,aval=0; X
    // val=0,unk=1,aval=1 -- verified against both truth tables bit by bit).
    // So `val = aval XOR bval`, `unk = bval`, with no per-bit branching
    // needed -- a single XOR reversibly relates the two plane-pairs.

    /// CG-138: limb-by-limb 4-state ADD with an EXPLICIT carry threaded
    /// between limbs -- codegen owns this narrow<->wide translation, state
    /// owns only the storage format (this task's own ledger requirement
    /// text). Per the arithmetic any-unknown-bit rule already enforced by
    /// `add4` at narrow width (ARCHITECTURE.md / codegen.md §2's
    /// "Arithmetic (+,-,*)" rule), any unknown bit ANYWHERE across the
    /// whole `width`-bit operand -- not just within one limb -- forces the
    /// ENTIRE wide result (every limb) to all-X: the rule is operand-wide,
    /// never limb-independent (`wide_add_any_unknown_limb_forces_whole_
    /// value_all_x`, tests/wide_arith.rs, is the regression guard a naive
    /// per-limb-independent implementation would fail).
    ///
    /// `a`, `b` and `out` must each have exactly `wide_limb_count(width)`
    /// limbs (asserted).
    pub fn wide_add(
        &self,
        a: WideValueRef<'ctx>,
        b: WideValueRef<'ctx>,
        out: WideValueRef<'ctx>,
        width: u32,
    ) {
        let limb_count = wide_limb_count(width);
        assert_eq!(
            a.limb_count, limb_count,
            "wide_add: `a` limb_count mismatch"
        );
        assert_eq!(
            b.limb_count, limb_count,
            "wide_add: `b` limb_count mismatch"
        );
        assert_eq!(
            out.limb_count, limb_count,
            "wide_add: `out` limb_count mismatch"
        );

        let i64t = self.ctx.i64_type();
        let i65t = self.i_n(65);
        let bool_t = self.ctx.bool_type();

        // Pass 1: ripple the carry low-limb-first, and accumulate whether
        // ANY limb (masked to its meaningful bits) has an unknown bit
        // anywhere -- this flag is operand-wide, decided only once both
        // passes' limb loop has seen every limb, never per limb.
        let mut carry = i64t.const_zero();
        let mut any_unk = bool_t.const_zero();
        let mut sums: Vec<IntValue<'ctx>> = Vec::with_capacity(limb_count as usize);

        for limb in 0..limb_count {
            let (aval_a, bval_a) = self.wide_load_limb(a, limb);
            let (aval_b, bval_b) = self.wide_load_limb(b, limb);

            // (aval,bval) -> (val,unk): val = aval^bval, unk = bval (see
            // this block's header comment for the derivation).
            let val_a = self.xor(aval_a, bval_a);
            let unk_a = bval_a;
            let val_b = self.xor(aval_b, bval_b);
            let unk_b = bval_b;

            let mask = i64t.const_int(limb_mask64(width, limb), false);
            let unk_here = self.and(self.or(unk_a, unk_b), mask);
            let limb_has_unk = self.nonzero(unk_here, 64);
            any_unk = self.or(any_unk, limb_has_unk);

            // Explicit carry propagation (CG-138's exact acceptance): a
            // 65-bit add of val_a + val_b + carry_in; carry_out is bit 64
            // of that 65-bit sum, threaded into the next limb's carry_in --
            // NOT two independent 64-bit wraps with nothing threaded
            // between them (the bug this task must not reintroduce).
            let val_a65 = self.b.build_int_z_extend(val_a, i65t, "val_a65").unwrap();
            let val_b65 = self.b.build_int_z_extend(val_b, i65t, "val_b65").unwrap();
            let carry65 = self.b.build_int_z_extend(carry, i65t, "carry65").unwrap();
            let sum_ab = self.b.build_int_add(val_a65, val_b65, "sum_ab").unwrap();
            let sum65 = self.b.build_int_add(sum_ab, carry65, "sum65").unwrap();
            let sum64 = self.b.build_int_truncate(sum65, i64t, "sum64").unwrap();
            let carry_out65 = self
                .b
                .build_right_shift(sum65, i65t.const_int(64, false), false, "carry_out65")
                .unwrap();
            carry = self
                .b
                .build_int_truncate(carry_out65, i64t, "carry_out64")
                .unwrap();

            sums.push(sum64);
        }

        // Pass 2: now that `any_unk` reflects the WHOLE operand, write
        // every limb -- masked to `width`'s meaningful bits, beyond-width
        // bits always zero, matching `lower_const_any`'s own invariant.
        for (limb, &sum64) in sums.iter().enumerate() {
            let limb = limb as u32;
            let mask = i64t.const_int(limb_mask64(width, limb), false);
            let known_aval = self.and(sum64, mask);
            let known_bval = i64t.const_zero();
            // All-X (aval=bval=1 on every meaningful bit, per
            // `bit_to_aval_bval`'s `(1,1)->X`), masked to this limb.
            let out_aval = self
                .b
                .build_select(any_unk, mask, known_aval, "out_aval")
                .unwrap()
                .into_int_value();
            let out_bval = self
                .b
                .build_select(any_unk, mask, known_bval, "out_bval")
                .unwrap()
                .into_int_value();
            self.wide_store_limb(out, limb, out_aval, out_bval);
        }
    }

    /// CG-138: brings a wide (`WideValueRef`) value of `width <=
    /// WIDE_THRESHOLD` bits back into the narrow packed `i(2N)`
    /// representation (`PackedValue`) -- the inverse of `wide_scatter`.
    /// Converts each limb's (aval,bval) plane pair to (val,unk) and
    /// assembles them least-significant-limb-first into one `i(width)` val
    /// lane and one `i(width)` unk lane, then `pack`s them -- the "gather
    /// to narrow chunks" half of `wide_gather_scatter_roundtrips_all_four_
    /// states` (tests/wide_arith.rs).
    pub fn wide_gather(
        &self,
        w: WideValueRef<'ctx>,
        width: u32,
        repr: ValueRepr,
        signed: bool,
    ) -> PackedValue<'ctx> {
        assert!(
            width <= WIDE_THRESHOLD,
            "wide_gather: target width {width} must fit the narrow path (<= {WIDE_THRESHOLD})"
        );
        let limb_count = wide_limb_count(width);
        assert_eq!(w.limb_count, limb_count, "wide_gather: limb_count mismatch");

        let i64t = self.ctx.i64_type();
        let vt = self.i_n(width);
        let mut val_acc = vt.const_zero();
        let mut unk_acc = vt.const_zero();

        for limb in 0..limb_count {
            let (aval, bval) = self.wide_load_limb(w, limb);
            let mask = i64t.const_int(limb_mask64(width, limb), false);
            let aval_m = self.and(aval, mask);
            let bval_m = self.and(bval, mask);
            let val64 = self.xor(aval_m, bval_m);
            let unk64 = bval_m;

            let val_w = self.resize_unsigned(val64, 64, width);
            let unk_w = self.resize_unsigned(unk64, 64, width);

            let shift = limb * 64;
            let (val_shifted, unk_shifted) = if shift == 0 {
                (val_w, unk_w)
            } else {
                let sh = vt.const_int(shift as u64, false);
                (
                    self.b.build_left_shift(val_w, sh, "val_sh").unwrap(),
                    self.b.build_left_shift(unk_w, sh, "unk_sh").unwrap(),
                )
            };
            val_acc = self.or(val_acc, val_shifted);
            unk_acc = self.or(unk_acc, unk_shifted);
        }

        self.pack(val_acc, unk_acc, width, repr, signed)
    }

    /// CG-138: the inverse of `wide_gather` -- writes a narrow `PackedValue`
    /// (`v.width <= WIDE_THRESHOLD`) out into `w`'s limbs, converting each
    /// 64-bit (val,unk) chunk to the wide path's (aval,bval) polarity as it
    /// goes. `w.limb_count` must equal `wide_limb_count(v.width)`.
    pub fn wide_scatter(&self, v: PackedValue<'ctx>, w: WideValueRef<'ctx>) {
        let width = v.width;
        let limb_count = wide_limb_count(width);
        assert_eq!(
            w.limb_count, limb_count,
            "wide_scatter: limb_count mismatch"
        );

        let val = self.lane_val(v);
        let unk = self.lane_unk(v);
        let vt = self.i_n(width);
        let i64t = self.ctx.i64_type();

        for limb in 0..limb_count {
            let shift = limb * 64;
            let (val_shifted, unk_shifted) = if shift == 0 {
                (val, unk)
            } else {
                let sh = vt.const_int(shift as u64, false);
                (
                    self.b.build_right_shift(val, sh, false, "val_sh").unwrap(),
                    self.b.build_right_shift(unk, sh, false, "unk_sh").unwrap(),
                )
            };
            let val64 = self.resize_unsigned(val_shifted, width, 64);
            let unk64 = self.resize_unsigned(unk_shifted, width, 64);

            let mask = i64t.const_int(limb_mask64(width, limb), false);
            let val64m = self.and(val64, mask);
            let unk64m = self.and(unk64, mask);
            let aval = self.xor(val64m, unk64m);
            let bval = unk64m;

            self.wide_store_limb(w, limb, aval, bval);
        }
    }

    /// CG-016/CG-019/CG-129's dispatch point: lowers an `SVInt` constant to
    /// the narrow packed `i(2N)` representation when `width <=
    /// WIDE_THRESHOLD`, or to limb-array `WideValueRef` storage above it --
    /// the concrete thing `width_at_threshold_uses_narrow_path`/
    /// `width_above_threshold_uses_wide_path` (tests/wide_value.rs) exercise.
    /// Deviation from plan: kept as a standalone dispatch entry point
    /// (rather than folded into `lower_expr`, which is not among this
    /// task's `Files:` and has no wide-arithmetic consumer yet -- see
    /// `value.rs`'s `AnyValue` doc comment).
    ///
    /// `None` for a constant whose bits cannot be recovered past sv-lang's
    /// per-bit expansion cap (`sv_sim_sim::state::svint_bits`).
    pub fn lower_const_any(&self, v: &sv_lang::SVInt, repr: ValueRepr) -> Option<AnyValue<'ctx>> {
        let bits = sv_sim_sim::state::svint_bits(v)?;
        let width = v.bit_width();
        if width <= WIDE_THRESHOLD {
            return Some(AnyValue::Narrow(const_svint(self.ctx, v, repr)));
        }
        let limb_count = wide_limb_count(width);
        let w = self.wide_alloca(limb_count, "wide_const");
        let i64t = self.ctx.i64_type();
        for limb in 0..limb_count {
            let mut aval: u64 = 0;
            let mut bval: u64 = 0;
            for bit_in_limb in 0..64u32 {
                let idx = limb * 64 + bit_in_limb;
                if idx >= width {
                    break;
                }
                // IEEE 1800 `t_vpi_vecval`/`svLogicVecVal` polarity, via the
                // ONE shared conversion function (Task 16 / CG-173's
                // `value::bit_to_aval_bval` -- see that module's header
                // comment for the full derivation and why this is a
                // DIFFERENT plane-polarity than the narrow path's internal
                // (val,unk) pair below). Do NOT re-derive this match
                // inline; that duplication was review fix r1's bug.
                let (av, bv) = bit_to_aval_bval(bits[idx as usize]);
                if av {
                    aval |= 1u64 << bit_in_limb;
                }
                // 2-state has no unknown plane (mirrors `pack`'s TwoState
                // arm): `bval` stays 0 for every limb in that mode.
                if bv && repr == ValueRepr::FourState {
                    bval |= 1u64 << bit_in_limb;
                }
            }
            self.wide_store_limb(
                w,
                limb,
                i64t.const_int(aval, false),
                i64t.const_int(bval, false),
            );
        }
        Some(AnyValue::Wide(w))
    }
}

// --- Task 9 (CG-090, CG-091, CG-007): branch-condition reduction ----------

/// Branch-condition reduction (CG-090): `(unk_mask(v)==0) &&
/// (val_bits(v)!=0)` -- reduce-OR the unk lane, compare to 0, AND with
/// reduce-OR of the val lane compared to 0. ANY X/Z bit anywhere makes the
/// branch false, per CG-007's decision-record correction (an ambiguous
/// if/while/wait/&&/||/iff condition takes the else/false branch -- this is
/// spec-correct, not a bug, and must NOT be altered to mimic the ternary
/// `?:`'s bitwise per-bit X-merge).
///
/// A free function (not an `OpBuilder` method), per the plan's own naming,
/// since it needs no `OpBuilder` state beyond `ctx`/`b` -- every `if`/`&&`/
/// `||` branch-condition lowering site in this crate calls this ONE
/// implementation (CG-090's "no duplicate reimplementation"; `func.rs`'s
/// `Conditional` arm and `expr.rs`'s `LogicalAnd`/`LogicalOr` short-circuit
/// lowering are its only two call sites in this task -- `while`/`do-while`
/// is Task 26's; `wait()`/`iff` are deferred to wave A2, see the plan's
/// Task 9 scope note).
///
/// CG-091: deliberately NOT the same function the (not-yet-implemented,
/// Task 10) ternary `?:` operator's result computation will use -- that
/// needs a bitwise merge over BOTH evaluated arms (LRM 11.4.11), a
/// fundamentally different job from this one's "reduce to a single
/// definitely-true/not boolean" (see `is_definitely_true_is_a_distinct_
/// function_from_ternary_merge`, tests/branch_reduction.rs, which proves
/// this structurally: this function's return type is always a single `i1`
/// regardless of the operand's width, which a per-bit merge could never
/// share).
pub fn is_definitely_true<'ctx>(
    ctx: &'ctx Context,
    b: &Builder<'ctx>,
    v: PackedValue<'ctx>,
) -> IntValue<'ctx> {
    let op = OpBuilder { ctx, b };
    let unk = op.lane_unk(v);
    let val = op.lane_val(v);
    let unk_zero = b
        .build_int_compare(
            inkwell::IntPredicate::EQ,
            unk,
            op.i_n(v.width).const_zero(),
            "idt_unk_zero",
        )
        .unwrap();
    let val_nonzero = op.nonzero(val, v.width);
    b.build_and(unk_zero, val_nonzero, "idt_result").unwrap()
}

/// Task 10 (CG-039/CG-008): the ternary `?:`'s condition-side "definitely
/// false" test -- the mirror of `is_definitely_true` above, needed because
/// the ternary's three-way dispatch (definitely-true / definitely-false /
/// ambiguous) is NOT just `is_definitely_true`/`!is_definitely_true`: the
/// latter is also true for a genuinely ambiguous (X/Z-containing)
/// condition, which must take the THIRD (both-arms-evaluated-and-merged)
/// path, not the false-arm-only path. `unk==0 && val==0`, all lanes.
pub fn is_definitely_false<'ctx>(
    ctx: &'ctx Context,
    b: &Builder<'ctx>,
    v: PackedValue<'ctx>,
) -> IntValue<'ctx> {
    let op = OpBuilder { ctx, b };
    let unk = op.lane_unk(v);
    let val = op.lane_val(v);
    let unk_zero = b
        .build_int_compare(
            inkwell::IntPredicate::EQ,
            unk,
            op.i_n(v.width).const_zero(),
            "idf_unk_zero",
        )
        .unwrap();
    let val_zero = b
        .build_int_compare(
            inkwell::IntPredicate::EQ,
            val,
            op.i_n(v.width).const_zero(),
            "idf_val_zero",
        )
        .unwrap();
    b.build_and(unk_zero, val_zero, "idf_result").unwrap()
}

/// Task 10 review-fix (r3): the ternary `?:`'s condition-side "definitely
/// true" test, distinct from `is_definitely_true` above.
///
/// `is_definitely_true` (CG-090/CG-091, for if/while/&&/||'s CG-007 rule)
/// requires the WHOLE condition to be fully known before calling it true --
/// correct for that rule (an ambiguous if-condition takes the else branch),
/// but wrong for the ternary: per real 4-state Verilog semantics (LRM
/// 1800-2023 §11.4.11, verified directly against `iverilog 12`), a
/// condition with even one bit that is a KNOWN 1 selects the true arm
/// cleanly, regardless of X/Z bits elsewhere in the condition -- e.g.
/// `3'b1xx ? a : b` evaluates to a clean `a`, never the bitwise
/// `ternary_merge4` of both arms. Reusing `is_definitely_true` here made
/// `1xxx`-shaped conditions spuriously take the ambiguous merge path.
///
/// Formula: reduce-OR of `val & ~unk` (any bit that is a known 1) compared
/// nonzero -- NOT `unk==0 && val!=0`. `is_definitely_false` needs no
/// equivalent change: `unk==0 && val==0` (every bit definitely a known 0)
/// is already the correct "definitely false" test for both rules, and
/// matches `iverilog`'s output for `4'b1z00`/`4'b0x00`-shaped conditions.
pub fn ternary_is_definitely_true<'ctx>(
    ctx: &'ctx Context,
    b: &Builder<'ctx>,
    v: PackedValue<'ctx>,
) -> IntValue<'ctx> {
    let op = OpBuilder { ctx, b };
    let unk = op.lane_unk(v);
    let val = op.lane_val(v);
    let known_ones = op.and(val, op.not(unk));
    op.nonzero(known_ones, v.width)
}