vj-codegen 0.2.0

//! Accessor-ABI call emission (CG-160, CG-163, CG-093, AB-050).
//!
//! Declares `vj_abi::accessor`'s `extern "C"` fn-pointer ABI
//! (`sv_get_scalar`/`sv_set_scalar`/`sv_get_wide`/`sv_set_wide`) as LLVM
//! function declarations in a `Module`, attributed `alwaysinline` (AB-050:
//! LTO/JIT eliminates the call overhead while STATE keeps the freedom to
//! re-layout without breaking already-compiled kernels -- ARCHITECTURE.md
//! §7 item 1's reconciliation), and builds the narrow-scalar read/write call
//! sequences that reposition between the accessor's FIXED `val`-low-64/
//! `unk`-high-64 `u128` layout and codegen's own width-tight `i(2N)` packing
//! (`vj_abi::accessor`'s doc comment; `value.rs`'s `const_svint` for the
//! `(unk << width) | val` convention the two layouts coincide on only at
//! `width == 64`).
//!
//! **CG-093's negative half** (no raw `getelementptr` against the shared
//! arena): every accessor call this module builds passes the `SimHandle`
//! parameter straight through to the declared `extern "C"` function as an
//! opaque pointer argument -- it is never `getelementptr`'d, never
//! dereferenced directly. The shared state arena is reachable exclusively
//! through these four calls.
//!
//! Deviation from the plan text: the plan's "matching
//! `vj_abi::accessor::{sv_get_scalar_inline,...}`'s naming convention
//! documented there" line does not match the real crate -- those
//! `*_inline` wrapper fns live in `vj-sim::state::accessor_impl` (the
//! STATE-side half of ARCHITECTURE §7 item 1's resolution), not in
//! `vj_abi::accessor`, which exports only the plain `extern "C"` fn
//! type aliases and the `SV_*_SYMBOL` name constants. This module declares
//! the plain (non-`_inline`) symbol names -- `vj_abi::accessor::
//! SV_GET_SCALAR_SYMBOL` etc. -- since those are the actual link-time/
//! JIT-global-mapping symbol names a real STATE implementation (or a test
//! double) must be bound to; using the exported constants directly (rather
//! than hardcoded string literals) keeps this file and `vj_abi` from
//! ever silently drifting apart on the name.
use inkwell::AddressSpace;
use inkwell::attributes::{Attribute, AttributeLoc};
use inkwell::builder::Builder;
use inkwell::context::Context;
use inkwell::module::{Linkage, Module};
use inkwell::types::{AnyType, IntType, StructType};
use inkwell::values::{BasicValue, FunctionValue, IntValue, PointerValue};

use vj_abi::accessor::{
    SV_GET_MEM_WORD_SYMBOL, SV_GET_SCALAR_SYMBOL, SV_GET_WIDE_SYMBOL, SV_SET_MEM_WORD_SYMBOL,
    SV_SET_SCALAR_SYMBOL, SV_SET_WIDE_SYMBOL,
};

use crate::expr::LowerCtx;

/// The four accessor-ABI functions declared into an LLVM `Module`, matching
/// `vj_abi::accessor`'s `SvGetScalarFn`/`SvSetScalarFn`/`SvGetWideFn`/
/// `SvSetWideFn` signatures exactly. Fields are private: this module's own
/// `build_get_scalar`/`build_set_scalar` (and any future wide-value-path
/// sibling) are the only things that ever call them directly. A test
/// wanting to inspect one of the four declared functions looks it up on the
/// `Module` by its `vj_abi::accessor::SV_*_SYMBOL` name instead of
/// reaching into this struct.
pub struct AccessorFns<'ctx> {
    get_scalar: FunctionValue<'ctx>,
    set_scalar: FunctionValue<'ctx>,
    get_wide: FunctionValue<'ctx>,
    set_wide: FunctionValue<'ctx>,
    /// R-run Task 13 (ST-024/ST-114): `sv_get_mem_word`/`sv_set_mem_word`
    /// (`SlotClass::Memory`), addressed by a caller-supplied runtime
    /// `row_index` -- see [`build_get_mem_word`]/[`build_set_mem_word`].
    get_mem_word: FunctionValue<'ctx>,
    set_mem_word: FunctionValue<'ctx>,
}

/// The accessor declarations [`declare_accessor_fns`] already added to
/// `module` (it always declares all six together), for code that emits a
/// second function into the same module -- e.g. a `$strobe`/`$monitor`
/// argument thunk -- without redeclaring (LLVM would rename a duplicate).
/// `None` if `declare_accessor_fns` was never called on `module`.
pub fn accessor_fns_of<'ctx>(module: &Module<'ctx>) -> Option<AccessorFns<'ctx>> {
    Some(AccessorFns {
        get_scalar: module.get_function(SV_GET_SCALAR_SYMBOL)?,
        set_scalar: module.get_function(SV_SET_SCALAR_SYMBOL)?,
        get_wide: module.get_function(SV_GET_WIDE_SYMBOL)?,
        set_wide: module.get_function(SV_SET_WIDE_SYMBOL)?,
        get_mem_word: module.get_function(SV_GET_MEM_WORD_SYMBOL)?,
        set_mem_word: module.get_function(SV_SET_MEM_WORD_SYMBOL)?,
    })
}

impl<'ctx> AccessorFns<'ctx> {
    /// R-run Task 13: the `(handle, fns)` pair `expr.rs`'s `ElementSelect`/
    /// `Assignment` arms need to reach [`build_get_mem_word`]/
    /// [`build_set_mem_word`] for a `SlotClass::Memory` external signal --
    /// exposed as a small `Copy` accessor (never the whole private struct)
    /// so `LowerCtx::mem_accessor` can carry a `&AccessorFns<'ctx>` reference
    /// without this module handing out its two other, still-private
    /// `FunctionValue`s.
    pub fn get_mem_word(&self) -> FunctionValue<'ctx> {
        self.get_mem_word
    }

    /// The `sv_set_mem_word` twin of [`AccessorFns::get_mem_word`].
    pub fn set_mem_word(&self) -> FunctionValue<'ctx> {
        self.set_mem_word
    }
}

/// `ctx.custom_width_int_type` corrected for a non-generic width (mirrors
/// `value.rs`/`types.rs`'s own private `int_type` helper -- kept as a small,
/// separate copy rather than exposing theirs, since neither is on this
/// module's `Files:` list and this is the only place in this file that needs
/// it).
fn int_type(ctx: &Context, w: u32) -> IntType<'_> {
    ctx.custom_width_int_type(std::num::NonZeroU32::new(w).expect("zero-width int type"))
        .expect("custom_width_int_type")
}

fn alwaysinline_attr(ctx: &Context) -> Attribute {
    let kind_id = Attribute::get_named_enum_kind_id("alwaysinline");
    debug_assert_ne!(
        kind_id, 0,
        "\"alwaysinline\" must be a recognized LLVM enum attribute name"
    );
    ctx.create_enum_attribute(kind_id, 0)
}

/// Declares the four accessor-ABI functions in `module`, each attributed
/// `alwaysinline` (AB-050).
///
/// `sv_get_scalar`/`sv_set_scalar` (`SlotClass::Inline`, this slice's only
/// exercised slot class): `(SimHandle, SlotId) -> u128` / `(SimHandle,
/// SlotId, u128)`. `SimHandle` (a `#[repr(transparent)]` wrapper around a
/// bare `*mut c_void`) lowers to an opaque `ptr`; `SlotId` (a
/// `#[repr(transparent)]` `u32`) lowers to `i32`; the fixed-layout `u128`
/// payload lowers to `i128` -- exactly the shape a SysV-ABI `extern "C" fn(
/// SimHandle, SlotId) -> u128` already returns in the `rax:rdx` register
/// pair (16 bytes, INTEGER,INTEGER classification), so no `sret` is needed
/// here.
///
/// `sv_get_wide`/`sv_set_wide` (`SlotClass::Wide`, out of this slice's
/// scope -- declared for `AccessorFns`'s shape and future callers, not
/// built/called by any function in this file): `WideView` is 24 bytes
/// (`{aval: *mut u64, bval: *mut u64, word_count: u32}`, padded to 8-byte
/// alignment), which SysV classifies MEMORY (too large for the two-register
/// INTEGER,INTEGER case `u128`/pointer-pair values get) -- returned via a
/// hidden `sret` pointer parameter and passed by value via `byval`,
/// matching how `rustc`'s own `extern "C"` ABI lowering for a struct this
/// size actually codegens on this target.
pub fn declare_accessor_fns<'ctx>(ctx: &'ctx Context, module: &Module<'ctx>) -> AccessorFns<'ctx> {
    let ptr_ty = ctx.ptr_type(AddressSpace::default());
    let i32_ty = ctx.i32_type();
    let i64_ty = ctx.i64_type();
    let i128_ty = ctx.i128_type();
    let void_ty = ctx.void_type();
    let wide_view_ty = wide_view_llvm_type(ctx);

    let attr = alwaysinline_attr(ctx);

    let get_scalar_ty = i128_ty.fn_type(&[ptr_ty.into(), i32_ty.into()], false);
    let get_scalar =
        module.add_function(SV_GET_SCALAR_SYMBOL, get_scalar_ty, Some(Linkage::External));
    get_scalar.add_attribute(AttributeLoc::Function, attr);

    let set_scalar_ty = void_ty.fn_type(&[ptr_ty.into(), i32_ty.into(), i128_ty.into()], false);
    let set_scalar =
        module.add_function(SV_SET_SCALAR_SYMBOL, set_scalar_ty, Some(Linkage::External));
    set_scalar.add_attribute(AttributeLoc::Function, attr);

    // sv_get_wide(handle: ptr, slot: i32) -> WideView, returned via a
    // hidden `sret` pointer parameter (param 0) -- WideView's 24 bytes are
    // SysV-MEMORY-classified, never returned in registers.
    let get_wide_ty = void_ty.fn_type(&[ptr_ty.into(), ptr_ty.into(), i32_ty.into()], false);
    let get_wide = module.add_function(SV_GET_WIDE_SYMBOL, get_wide_ty, Some(Linkage::External));
    get_wide.add_attribute(AttributeLoc::Function, attr);
    let sret_kind_id = Attribute::get_named_enum_kind_id("sret");
    get_wide.add_attribute(
        AttributeLoc::Param(0),
        ctx.create_type_attribute(sret_kind_id, wide_view_ty.as_any_type_enum()),
    );

    // sv_set_wide(handle: ptr, slot: i32, value: WideView) -- `value`
    // (param 2) passed `byval`, the SysV-MEMORY-classified-parameter
    // sibling of `sv_get_wide`'s `sret` return.
    let set_wide_ty = void_ty.fn_type(&[ptr_ty.into(), i32_ty.into(), ptr_ty.into()], false);
    let set_wide = module.add_function(SV_SET_WIDE_SYMBOL, set_wide_ty, Some(Linkage::External));
    set_wide.add_attribute(AttributeLoc::Function, attr);
    let byval_kind_id = Attribute::get_named_enum_kind_id("byval");
    set_wide.add_attribute(
        AttributeLoc::Param(2),
        ctx.create_type_attribute(byval_kind_id, wide_view_ty.as_any_type_enum()),
    );

    // R-run Task 13 (ST-024/ST-114): `sv_get_mem_word`/`sv_set_mem_word` --
    // the `sv_get_wide`/`sv_set_wide` shape above, plus one extra `i64`
    // `row_index` parameter (`vj_abi::accessor::SvGetMemWordFn`/
    // `SvSetMemWordFn`'s own `u64` argument), addressing one row of a
    // `SlotClass::Memory` array. `row_index` is param 2 on the get side
    // (after the sret pointer and `handle`) and param 3 on the set side
    // (after `handle`/`slot`, before the byval `WideView`).
    let get_mem_word_ty = void_ty.fn_type(
        &[ptr_ty.into(), ptr_ty.into(), i32_ty.into(), i64_ty.into()],
        false,
    );
    let get_mem_word = module.add_function(
        SV_GET_MEM_WORD_SYMBOL,
        get_mem_word_ty,
        Some(Linkage::External),
    );
    get_mem_word.add_attribute(AttributeLoc::Function, attr);
    get_mem_word.add_attribute(
        AttributeLoc::Param(0),
        ctx.create_type_attribute(sret_kind_id, wide_view_ty.as_any_type_enum()),
    );

    let set_mem_word_ty = void_ty.fn_type(
        &[ptr_ty.into(), i32_ty.into(), i64_ty.into(), ptr_ty.into()],
        false,
    );
    let set_mem_word = module.add_function(
        SV_SET_MEM_WORD_SYMBOL,
        set_mem_word_ty,
        Some(Linkage::External),
    );
    set_mem_word.add_attribute(AttributeLoc::Function, attr);
    set_mem_word.add_attribute(
        AttributeLoc::Param(3),
        ctx.create_type_attribute(byval_kind_id, wide_view_ty.as_any_type_enum()),
    );

    AccessorFns {
        get_scalar,
        set_scalar,
        get_wide,
        set_wide,
        get_mem_word,
        set_mem_word,
    }
}

/// The LLVM struct shape `vj_abi::accessor::WideView` lowers to (`{aval:
/// ptr, bval: ptr, word_count: i32}`, matching `#[repr(C)]`'s own field
/// order/padding for this exact field-type sequence on this target) -- the
/// one place this shape is built, shared by [`declare_accessor_fns`] (for
/// the `sret`/`byval` type attributes) and every `build_get_wide`/
/// `build_set_wide`/`build_get_mem_word`/`build_set_mem_word` call below
/// (for the sret/byval alloca each one builds), so the two can never drift
/// apart on the struct's exact shape.
fn wide_view_llvm_type(ctx: &Context) -> StructType<'_> {
    let ptr_ty = ctx.ptr_type(AddressSpace::default());
    let i32_ty = ctx.i32_type();
    ctx.struct_type(&[ptr_ty.into(), ptr_ty.into(), i32_ty.into()], false)
}

/// Resizes `v` (a `src_bits`-wide `IntValue`) to exactly `dst_ty`
/// (`dst_bits`-wide): truncates when narrowing (or when the widths are
/// equal -- `TruncOrBitCast` degrades to a plain bitcast in that case),
/// zero-extends when widening. Shared by `build_get_scalar` (i64 ->
/// `i(2*width)`) and `build_set_scalar` (`i(2*width)` -> i64) -- the two
/// directions of the exact same "does this int need to grow or shrink"
/// question, decided once here rather than re-derived at each call site.
fn resize<'ctx>(
    b: &Builder<'ctx>,
    v: IntValue<'ctx>,
    src_bits: u32,
    dst_ty: IntType<'ctx>,
    dst_bits: u32,
    name: &str,
) -> IntValue<'ctx> {
    if dst_bits <= src_bits {
        b.build_int_truncate_or_bit_cast(v, dst_ty, name).unwrap()
    } else {
        b.build_int_z_extend_or_bit_cast(v, dst_ty, name).unwrap()
    }
}

/// `(1 << width) - 1`, saturating at `u64::MAX` for `width >= 64` (this
/// accessor is `SlotClass::Inline`-only, so `width` never legitimately
/// exceeds 64, but this stays total rather than panicking/shifting by 64 --
/// UB for a `u64` shift -- if a future caller ever passes exactly 64).
fn low_bits_mask(width: u32) -> u64 {
    if width >= 64 {
        u64::MAX
    } else {
        (1u64 << width) - 1
    }
}

/// Emits a call to `sv_get_scalar(handle, slot)` and repositions its FIXED
/// `val`-low-64/`unk`-high-64 `u128` result into codegen's own width-tight
/// `i(2*width)` packing (`(unk << width) | val`) -- CG-163/AB-050's read
/// side. `width` must be the `SlotClass::Inline` signal's real bit width
/// (`<= 64`, this slice's only supported slot class); the returned
/// `IntValue` has LLVM type `i(2*width)`, ready to feed the same
/// `PackedValue`-consuming code every other narrow value already goes
/// through.
pub fn build_get_scalar<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    fns: &AccessorFns<'ctx>,
    handle: PointerValue<'ctx>,
    slot: u32,
    width: u32,
) -> IntValue<'ctx> {
    debug_assert!(
        (1..=64).contains(&width),
        "sv_get_scalar is SlotClass::Inline-only: width must be 1..=64, got {width}"
    );
    let raw = build_get_scalar_raw(cx, fns, handle, slot);
    build_fixed_to_packed(cx, raw, width)
}

/// `const u128 *const *sv_rt_inline_ptrs(SimHandle)`: per-slot direct-read
/// addresses of an instance (`vj_sim::state::real_sv_rt_inline_ptrs`).
pub const SV_RT_INLINE_PTRS_SYMBOL: &str = "sv_rt_inline_ptrs";

thread_local! {
    /// Set while a design lowers for the JIT with `sv_rt_inline_ptrs` bound
    /// ([`DirectInlineGuard`]): primed `Inline` signals are then loaded
    /// straight from the arena. AOT keeps the accessor call, which its LTO
    /// inlines (`accessor_inlining`).
    static DIRECT_INLINE: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
}

/// Enables direct `Inline` loads ([`build_get_scalar_raw_direct`]) for one
/// design lowering when `on`.
pub(crate) struct DirectInlineGuard;

impl DirectInlineGuard {
    pub(crate) fn enter(on: bool) -> Self {
        DIRECT_INLINE.with(|d| d.set(on));
        DirectInlineGuard
    }
}

impl Drop for DirectInlineGuard {
    fn drop(&mut self) {
        DIRECT_INLINE.with(|d| d.set(false));
    }
}

/// Whether the design being lowered reads `Inline` signals directly.
pub(crate) fn direct_inline_enabled() -> bool {
    DIRECT_INLINE.with(std::cell::Cell::get)
}

/// The per-slot address table of `handle`'s instance: one call that replaces
/// a `sv_get_scalar` call per `Inline` signal read afterwards. Valid for the
/// rest of the kernel call (nothing allocates arena words while one runs).
pub fn build_inline_ptr_table<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    handle: PointerValue<'ctx>,
) -> PointerValue<'ctx> {
    let ptr_ty = cx.ctx.ptr_type(AddressSpace::default());
    let f = cx
        .module
        .get_function(SV_RT_INLINE_PTRS_SYMBOL)
        .unwrap_or_else(|| {
            cx.module.add_function(
                SV_RT_INLINE_PTRS_SYMBOL,
                ptr_ty.fn_type(&[ptr_ty.into()], false),
                None,
            )
        });
    cx.b.build_call(f, &[handle.into()], "inline_ptrs")
        .unwrap()
        .try_as_basic_value()
        .unwrap_basic()
        .into_pointer_value()
}

/// [`build_get_scalar_raw`] through `table` ([`build_inline_ptr_table`]): a
/// load of the slot's arena cell when the table has one, the accessor call
/// (a windowed alias, LRM 23.3.3.2 `ref` select) when it is null. The same
/// `u128` either way.
pub fn build_get_scalar_raw_direct<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    fns: &AccessorFns<'ctx>,
    handle: PointerValue<'ctx>,
    table: PointerValue<'ctx>,
    slot: u32,
) -> IntValue<'ctx> {
    let ctx = cx.ctx;
    let b = &cx.b;
    let ptr_ty = ctx.ptr_type(AddressSpace::default());
    let i64_ty = ctx.i64_type();
    let entry = unsafe {
        b.build_gep(
            ptr_ty,
            table,
            &[i64_ty.const_int(u64::from(slot), false)],
            "inline_ptr_ent",
        )
    }
    .unwrap();
    let cell = b
        .build_load(ptr_ty, entry, "inline_ptr")
        .unwrap()
        .into_pointer_value();
    let is_null = b.build_is_null(cell, "inline_ptr_null").unwrap();
    let func = b.get_insert_block().unwrap().get_parent().unwrap();
    let fast_bb = ctx.append_basic_block(func, "get_direct");
    let slow_bb = ctx.append_basic_block(func, "get_accessor");
    let join_bb = ctx.append_basic_block(func, "get_join");
    b.build_conditional_branch(is_null, slow_bb, fast_bb)
        .unwrap();
    b.position_at_end(fast_bb);
    let load = b
        .build_load(ctx.i128_type(), cell, "inline_direct")
        .unwrap();
    load.as_instruction_value()
        .unwrap()
        .set_alignment(16)
        .unwrap();
    let direct = load.into_int_value();
    b.build_unconditional_branch(join_bb).unwrap();
    b.position_at_end(slow_bb);
    let slow = build_get_scalar_raw(cx, fns, handle, slot);
    b.build_unconditional_branch(join_bb).unwrap();
    b.position_at_end(join_bb);
    let phi = b.build_phi(ctx.i128_type(), "inline_val").unwrap();
    phi.add_incoming(&[(&direct, fast_bb), (&slow, slow_bb)]);
    phi.as_basic_value().into_int_value()
}

/// The `Inline` reads of one priming point (a segment, a guard, a continuous
/// assignment): direct through one `sv_rt_inline_ptrs` table when the design
/// lowers for the JIT and there are at least two of them (one call plus a load
/// each beats a call each), else the accessor call. The table is built at the
/// first read, which dominates the rest of the straight-line prime.
pub(crate) struct InlineReads<'ctx> {
    direct: bool,
    table: Option<PointerValue<'ctx>>,
}

impl<'ctx> InlineReads<'ctx> {
    pub(crate) fn new(inline_reads: usize) -> Self {
        InlineReads {
            direct: direct_inline_enabled() && inline_reads >= 2,
            table: None,
        }
    }

    /// [`build_get_scalar`], direct when enabled.
    pub(crate) fn get(
        &mut self,
        cx: &LowerCtx<'ctx, '_, '_>,
        fns: &AccessorFns<'ctx>,
        handle: PointerValue<'ctx>,
        slot: u32,
        width: u32,
    ) -> IntValue<'ctx> {
        if !self.direct {
            return build_get_scalar(cx, fns, handle, slot, width);
        }
        let table = *self
            .table
            .get_or_insert_with(|| build_inline_ptr_table(cx, handle));
        let raw = build_get_scalar_raw_direct(cx, fns, handle, table, slot);
        build_fixed_to_packed(cx, raw, width)
    }
}

/// The accessor's FIXED-layout `u128` of an Inline slot (`val` in the low 64
/// bits, `unk` in the high 64), un-repacked: what the SVA engine's signal rows
/// hold.
pub fn build_get_scalar_raw<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    fns: &AccessorFns<'ctx>,
    handle: PointerValue<'ctx>,
    slot: u32,
) -> IntValue<'ctx> {
    let slot_const = cx.ctx.i32_type().const_int(u64::from(slot), false);
    cx.b.build_call(
        fns.get_scalar,
        &[handle.into(), slot_const.into()],
        "sv_get_scalar_call",
    )
    .unwrap()
    .try_as_basic_value()
    .unwrap_basic()
    .into_int_value()
}

/// The repack half of [`build_get_scalar`]: a FIXED-layout accessor `u128`
/// (`val` in the low 64 bits, `unk` in the high 64, whatever the width) to
/// codegen's width-tight `(unk << width) | val` packing of LLVM type
/// `i(2*width)`. Factored out so a value read from somewhere other than the
/// accessor call (the SVA engine's captured signal rows) repacks identically.
pub fn build_fixed_to_packed<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    raw: IntValue<'ctx>,
    width: u32,
) -> IntValue<'ctx> {
    let ctx = cx.ctx;
    let b = &cx.b;
    let i64_ty = ctx.i64_type();
    let i128_ty = ctx.i128_type();
    let sixty_four = i128_ty.const_int(64, false);

    // raw's low 64 bits = val, high 64 bits = unk (the FIXED accessor
    // layout, independent of `width`) -- never a `<< width` split, which is
    // exactly the bug `vj-sim::state`'s own
    // `four_state_narrow_at_width_8_uses_fixed_64_offset_not_width_offset`
    // regression test exists to catch.
    let val64 = b.build_int_truncate(raw, i64_ty, "acc_get_val64").unwrap();
    let raw_hi = b
        .build_right_shift(raw, sixty_four, false, "acc_get_raw_hi")
        .unwrap();
    let unk64 = b
        .build_int_truncate(raw_hi, i64_ty, "acc_get_unk64")
        .unwrap();

    let mask = i64_ty.const_int(low_bits_mask(width), false);
    let val_masked = b.build_and(val64, mask, "acc_get_val_masked").unwrap();
    let unk_masked = b.build_and(unk64, mask, "acc_get_unk_masked").unwrap();

    let packed_bits = width.checked_mul(2).expect("width*2 overflow");
    let packed_ty = int_type(ctx, packed_bits);
    let val_ext = resize(b, val_masked, 64, packed_ty, packed_bits, "acc_get_val_ext");
    let unk_ext = resize(b, unk_masked, 64, packed_ty, packed_bits, "acc_get_unk_ext");
    let width_const = packed_ty.const_int(u64::from(width), false);
    let unk_shifted = b
        .build_left_shift(unk_ext, width_const, "acc_get_unk_shifted")
        .unwrap();
    b.build_or(val_ext, unk_shifted, "acc_get_packed").unwrap()
}

/// The write-side repositioning half of `build_set_scalar` (CG-163/AB-050),
/// factored out so Task S4's nonblocking-assignment lowering
/// (`vj-codegen::process_lower`) can reuse the exact same FIXED-layout
/// packing when it calls `nba_enqueue` instead of `sv_set_scalar` (PR-065/
/// PR-066: the ABI's `value: u128` parameter uses this same FIXED layout on
/// both call sites, never codegen's own width-tight packing). Splits `value`
/// (LLVM type `i(2*width)`, codegen's width-tight `(unk << width) | val`
/// packing) into the accessor ABI's FIXED `val`-low-64/`unk`-high-64 `u128`.
pub fn reposition_width_tight_to_fixed<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    value: IntValue<'ctx>,
    width: u32,
) -> IntValue<'ctx> {
    debug_assert!(
        (1..=64).contains(&width),
        "the accessor ABI is SlotClass::Inline-only: width must be 1..=64, got {width}"
    );
    let ctx = cx.ctx;
    let b = &cx.b;

    let packed_bits = width.checked_mul(2).expect("width*2 overflow");
    let packed_ty = int_type(ctx, packed_bits);
    let mask = packed_ty.const_int(low_bits_mask(width), false);

    let val_part = b.build_and(value, mask, "acc_set_val_part").unwrap();
    let width_const = packed_ty.const_int(u64::from(width), false);
    let shifted = b
        .build_right_shift(value, width_const, false, "acc_set_shift")
        .unwrap();
    let unk_part = b.build_and(shifted, mask, "acc_set_unk_part").unwrap();

    let i64_ty = ctx.i64_type();
    let val64 = resize(b, val_part, packed_bits, i64_ty, 64, "acc_set_val64");
    let unk64 = resize(b, unk_part, packed_bits, i64_ty, 64, "acc_set_unk64");

    let i128_ty = ctx.i128_type();
    let val128 = b
        .build_int_z_extend(val64, i128_ty, "acc_set_val128")
        .unwrap();
    let unk128 = b
        .build_int_z_extend(unk64, i128_ty, "acc_set_unk128")
        .unwrap();
    let sixty_four = i128_ty.const_int(64, false);
    // The FIXED layout: unk goes at bits [64:127], never at bit `width` --
    // the inverse of build_get_scalar's own `<< width`-vs-`<< 64` split.
    let unk_shifted = b
        .build_left_shift(unk128, sixty_four, "acc_set_unk_shifted")
        .unwrap();
    b.build_or(val128, unk_shifted, "acc_set_fixed").unwrap()
}

/// The inverse of [`build_get_scalar`]: splits `value` (LLVM type
/// `i(2*width)`, codegen's width-tight `(unk << width) | val` packing)
/// back into the accessor ABI's FIXED `val`-low-64/`unk`-high-64 `u128` and
/// calls `sv_set_scalar(handle, slot, value)` -- CG-163/AB-050's write
/// side.
pub fn build_set_scalar<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    fns: &AccessorFns<'ctx>,
    handle: PointerValue<'ctx>,
    slot: u32,
    value: IntValue<'ctx>,
    width: u32,
) {
    let fixed = reposition_width_tight_to_fixed(cx, value, width);
    let slot_const = cx.ctx.i32_type().const_int(u64::from(slot), false);
    cx.b.build_call(
        fns.set_scalar,
        &[handle.into(), slot_const.into(), fixed.into()],
        "sv_set_scalar_call",
    )
    .unwrap();
}

// --- R-run Task 13 (ST-009/AB-050/CG-163/ST-024/ST-114): the wide
// (`SlotClass::Wide`) and memory-word (`SlotClass::Memory`) accessor-call
// builders `build_get_scalar`/`build_set_scalar` above never provided --
// `wide_vectors.sv`'s 128-bit signal and `unpacked_array.sv`'s unpacked
// array both crashed `accessor.rs`'s own `debug_assert!` (this file's
// pre-Task-13 module doc comment: "`sv_get_wide`/`sv_set_wide` ... declared
// for `AccessorFns`'s shape and future callers, not built/called by any
// function in this file"). Both tiers share one `WideView`-repositioning
// core below (`build_wideview_to_packed`/`build_packed_to_wideview`),
// parameterized by an `Option<IntValue>` `row_index` (`None` for
// `sv_get_wide`/`sv_set_wide`'s two-argument shape, `Some(row)` for
// `sv_get_mem_word`/`sv_set_mem_word`'s three-argument shape) so the two
// accessor tiers' near-identical SoA-word-plane repositioning logic is
// written exactly once. ------------------------------------------------

/// Calls `get_fn(sret, handle, slot[, row_index])` and loads the pointers to
/// the returned [`vj_abi::accessor::WideView`]'s `aval` and `bval` word
/// planes.
/// A state slot the accessor call addresses: a constant, or (an event of the
/// pool the handle names, `events::group`) a value chosen at run time.
#[derive(Clone, Copy)]
pub enum Slot<'ctx> {
    Const(u32),
    /// An `i32` slot index.
    Dyn(IntValue<'ctx>),
}

impl From<u32> for Slot<'_> {
    fn from(slot: u32) -> Self {
        Slot::Const(slot)
    }
}

impl<'ctx> Slot<'ctx> {
    fn value(self, ctx: &'ctx inkwell::context::Context) -> IntValue<'ctx> {
        match self {
            Slot::Const(s) => ctx.i32_type().const_int(u64::from(s), false),
            Slot::Dyn(v) => v,
        }
    }
}

fn call_get_view<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    get_fn: FunctionValue<'ctx>,
    handle: PointerValue<'ctx>,
    slot: impl Into<Slot<'ctx>>,
    row_index: Option<IntValue<'ctx>>,
) -> (PointerValue<'ctx>, PointerValue<'ctx>) {
    let ctx = cx.ctx;
    let b = &cx.b;
    let wide_view_ty = wide_view_llvm_type(ctx);
    // An entry-block slot shared by every call site: a call inside an SV
    // loop is a back-edge within one activation, so a call-site `alloca`
    // would grow the stack on every iteration.
    let sret_alloca = crate::ops::shared_entry_alloca(ctx, b, wide_view_ty, "wideview_sret");
    let slot_const = slot.into().value(ctx);
    match row_index {
        Some(idx) => b
            .build_call(
                get_fn,
                &[
                    sret_alloca.into(),
                    handle.into(),
                    slot_const.into(),
                    idx.into(),
                ],
                "wideview_get_call",
            )
            .unwrap(),
        None => b
            .build_call(
                get_fn,
                &[sret_alloca.into(), handle.into(), slot_const.into()],
                "wideview_get_call",
            )
            .unwrap(),
    };

    let ptr_ty = ctx.ptr_type(AddressSpace::default());
    let aval_field = b
        .build_struct_gep(wide_view_ty, sret_alloca, 0, "wideview_aval_field")
        .unwrap();
    let bval_field = b
        .build_struct_gep(wide_view_ty, sret_alloca, 1, "wideview_bval_field")
        .unwrap();
    let aval_ptr = b
        .build_load(ptr_ty, aval_field, "wideview_aval_ptr")
        .unwrap()
        .into_pointer_value();
    let bval_ptr = b
        .build_load(ptr_ty, bval_field, "wideview_bval_ptr")
        .unwrap()
        .into_pointer_value();
    (aval_ptr, bval_ptr)
}

/// Shared read-side core for [`build_get_wide`]/[`build_get_mem_word`]:
/// calls `get_fn(sret, handle, slot[, row_index])`, then repositions the
/// returned [`vj_abi::accessor::WideView`]'s `width.div_ceil(64)`-word
/// `aval`/`bval` SoA planes into codegen's own width-tight `i(2*width)`
/// packed representation (`(unk << width) | val`) -- the wide-tier
/// generalization of `build_get_scalar`'s FIXED-64/64-to-width-tight
/// repositioning, from exactly one 64-bit word pair to `n_words` of them.
/// `width` may be `<= 64` (a narrow `SlotClass::Memory` row, per
/// `sv_get_mem_word`'s own doc comment: "a narrow-row memory's element comes
/// back as a one-word `WideView`") or `> 64` (`SlotClass::Wide`, or a wide
/// memory row); this shared core places no restriction on it -- each public
/// wrapper below documents its own caller-facing width contract.
fn build_wideview_to_packed<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    get_fn: FunctionValue<'ctx>,
    handle: PointerValue<'ctx>,
    slot: impl Into<Slot<'ctx>>,
    row_index: Option<IntValue<'ctx>>,
    width: u32,
) -> IntValue<'ctx> {
    let ctx = cx.ctx;
    let b = &cx.b;
    let n_words = width.div_ceil(64);
    let (aval_ptr, bval_ptr) = call_get_view(cx, get_fn, handle, slot, row_index);

    let i64_ty = ctx.i64_type();
    let val_ty = int_type(ctx, width);
    if width > crate::ops::WIDE_SELECT_BITS {
        return gather_planes_via_memory(cx, aval_ptr, bval_ptr, width);
    }
    let mut val_acc = val_ty.const_zero();
    let mut unk_acc = val_ty.const_zero();
    for i in 0..n_words {
        let idx_const = i64_ty.const_int(u64::from(i), false);
        // SAFETY: `get_fn`'s own accessor-ABI contract (`sv_get_wide`/
        // `sv_get_mem_word`, `vj_abi::accessor`) guarantees `aval`/
        // `bval` point at (at least) `n_words == width.div_ceil(64)`
        // contiguous, valid `u64` words for this slot/row's own width --
        // this loop never indexes past that bound.
        let aval_word_ptr = unsafe {
            b.build_gep(i64_ty, aval_ptr, &[idx_const], "wideview_aval_word_ptr")
                .unwrap()
        };
        let bval_word_ptr = unsafe {
            b.build_gep(i64_ty, bval_ptr, &[idx_const], "wideview_bval_word_ptr")
                .unwrap()
        };
        let aval_word = b
            .build_load(i64_ty, aval_word_ptr, "wideview_aval_word")
            .unwrap()
            .into_int_value();
        let bval_word = b
            .build_load(i64_ty, bval_word_ptr, "wideview_bval_word")
            .unwrap()
            .into_int_value();
        // STATE's wide planes are IEEE aval/bval (0=(0,0) 1=(1,0) Z=(0,1)
        // X=(1,1)); codegen's packed lanes are val/unk (X=(0,1) Z=(1,1)).
        // val = aval ^ bval, unk = bval -- the same X/Z swap DPI marshaling
        // applies. (Treating the planes as val/unk directly swapped X and Z
        // inside expressions: `z === 'z` was 0.)
        let val_word = b
            .build_xor(aval_word, bval_word, "wideview_val_word")
            .unwrap();
        let aval_ext = resize(b, val_word, 64, val_ty, width, "wideview_aval_ext");
        let bval_ext = resize(b, bval_word, 64, val_ty, width, "wideview_bval_ext");
        let shift = val_ty.const_int(u64::from(i) * 64, false);
        let aval_shifted = b
            .build_left_shift(aval_ext, shift, "wideview_aval_shifted")
            .unwrap();
        let bval_shifted = b
            .build_left_shift(bval_ext, shift, "wideview_bval_shifted")
            .unwrap();
        val_acc = b
            .build_or(val_acc, aval_shifted, "wideview_val_acc")
            .unwrap();
        unk_acc = b
            .build_or(unk_acc, bval_shifted, "wideview_unk_acc")
            .unwrap();
    }

    let packed_bits = width.checked_mul(2).expect("width*2 overflow");
    let packed_ty = int_type(ctx, packed_bits);
    let val_wide = resize(
        b,
        val_acc,
        width,
        packed_ty,
        packed_bits,
        "wideview_val_wide",
    );
    let unk_wide = resize(
        b,
        unk_acc,
        width,
        packed_ty,
        packed_bits,
        "wideview_unk_wide",
    );
    let width_const = packed_ty.const_int(u64::from(width), false);
    let unk_shifted = b
        .build_left_shift(unk_wide, width_const, "wideview_unk_shifted")
        .unwrap();
    b.build_or(val_wide, unk_shifted, "wideview_packed")
        .unwrap()
}

/// Sets `inst`'s alignment to `align` bytes (a load/store through an array
/// of `u64` words is only 8-aligned, while the natural alignment of a wide
/// `iN` is larger).
fn set_align(inst: inkwell::values::InstructionValue<'_>, align: u32) {
    inst.set_alignment(align).expect("power-of-two alignment");
}

/// [`build_wideview_to_packed`]'s accumulation loop for a wide signal
/// (`width > WIDE_SELECT_BITS`), linear in `width` instead of quadratic.
///
/// Or-ing `n_words` shifted full-width `iN` terms costs `n_words` operations
/// on `n_words`-word integers, so the emitted DAG grows with `width^2` and
/// LLVM's backend (whose scheduler is itself superlinear in block size) needs
/// minutes for a few thousand bits. Instead each word is stored to a
/// `[n_words x i64]` scratch array and the whole array is loaded back as one
/// `iN` (little-endian layout: word `i` holds bits `64*i..64*i+64`); the
/// partial top word's bits above `width` fall outside the loaded `iN`.
fn gather_planes_via_memory<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    aval_ptr: PointerValue<'ctx>,
    bval_ptr: PointerValue<'ctx>,
    width: u32,
) -> IntValue<'ctx> {
    const _: () = assert!(cfg!(target_endian = "little"));
    let ctx = cx.ctx;
    let b = &cx.b;
    let n_words = width.div_ceil(64);
    let i64_ty = ctx.i64_type();
    let i32_ty = ctx.i32_type();
    let val_ty = int_type(ctx, width);
    let arr_ty = i64_ty.array_type(n_words);
    // Whole-word widths: both planes land in ONE `[2*n_words x i64]` buffer
    // (val words, then unk words) and the packed `(unk << width) | val` is a
    // single `i(2*width)` load, with no shl/or over the doubled width.
    let fused = width.is_multiple_of(64);
    let (val_buf, unk_buf) = if fused {
        let buf = crate::ops::shared_entry_alloca(
            ctx,
            b,
            i64_ty.array_type(2 * n_words),
            &format!("wideview_packed_buf_{n_words}"),
        );
        // SAFETY: the buffer holds `2 * n_words` words; `n_words` is in bounds.
        let hi = unsafe {
            b.build_in_bounds_gep(
                i64_ty,
                buf,
                &[i64_ty.const_int(u64::from(n_words), false)],
                "wideview_unk_half",
            )
            .unwrap()
        };
        (buf, hi)
    } else {
        (
            crate::ops::shared_entry_alloca(ctx, b, arr_ty, &format!("wideview_val_buf_{n_words}")),
            crate::ops::shared_entry_alloca(ctx, b, arr_ty, &format!("wideview_unk_buf_{n_words}")),
        )
    };
    for i in 0..n_words {
        let idx_const = i64_ty.const_int(u64::from(i), false);
        let idx0 = i32_ty.const_zero();
        let idxn = i32_ty.const_int(u64::from(i), false);
        // SAFETY: `get_fn`'s accessor-ABI contract guarantees `aval`/`bval`
        // hold at least `n_words == width.div_ceil(64)` valid `u64` words,
        // and `i < n_words`.
        let (aval_word_ptr, bval_word_ptr) = unsafe {
            (
                b.build_gep(i64_ty, aval_ptr, &[idx_const], "wideview_aval_word_ptr")
                    .unwrap(),
                b.build_gep(i64_ty, bval_ptr, &[idx_const], "wideview_bval_word_ptr")
                    .unwrap(),
            )
        };
        // SAFETY: `val_buf`/`unk_buf` are `[n_words x i64]` allocas and
        // `i < n_words`, so `[0, i]` is an in-bounds array GEP.
        let (val_slot, unk_slot) = unsafe {
            (
                b.build_gep(arr_ty, val_buf, &[idx0, idxn], "wideview_val_slot")
                    .unwrap(),
                if fused {
                    b.build_gep(i64_ty, unk_buf, &[idx_const], "wideview_unk_slot")
                        .unwrap()
                } else {
                    b.build_gep(arr_ty, unk_buf, &[idx0, idxn], "wideview_unk_slot")
                        .unwrap()
                },
            )
        };
        let aval_word = b
            .build_load(i64_ty, aval_word_ptr, "wideview_aval_word")
            .unwrap()
            .into_int_value();
        let bval_word = b
            .build_load(i64_ty, bval_word_ptr, "wideview_bval_word")
            .unwrap()
            .into_int_value();
        // val = aval ^ bval, unk = bval (see `build_wideview_to_packed`).
        let val_word = b
            .build_xor(aval_word, bval_word, "wideview_val_word")
            .unwrap();
        b.build_store(val_slot, val_word).unwrap();
        b.build_store(unk_slot, bval_word).unwrap();
    }
    if fused {
        let v = b
            .build_load(int_type(ctx, width * 2), val_buf, "wideview_packed")
            .unwrap();
        set_align(
            inkwell::values::BasicValue::as_instruction_value(&v)
                .expect("a load is an instruction"),
            8,
        );
        return v.into_int_value();
    }
    let load_plane = |buf: PointerValue<'ctx>, name: &str| {
        let v = b.build_load(val_ty, buf, name).unwrap();
        set_align(
            inkwell::values::BasicValue::as_instruction_value(&v)
                .expect("a load is an instruction"),
            8,
        );
        v.into_int_value()
    };
    let val_acc = load_plane(val_buf, "wideview_val_acc");
    let unk_acc = load_plane(unk_buf, "wideview_unk_acc");

    let packed_bits = width.checked_mul(2).expect("width*2 overflow");
    let packed_ty = int_type(ctx, packed_bits);
    let val_wide = resize(
        b,
        val_acc,
        width,
        packed_ty,
        packed_bits,
        "wideview_val_wide",
    );
    let unk_wide = resize(
        b,
        unk_acc,
        width,
        packed_ty,
        packed_bits,
        "wideview_unk_wide",
    );
    let width_const = packed_ty.const_int(u64::from(width), false);
    let unk_shifted = b
        .build_left_shift(unk_wide, width_const, "wideview_unk_shifted")
        .unwrap();
    b.build_or(val_wide, unk_shifted, "wideview_packed")
        .unwrap()
}

/// [`build_packed_to_wideview`]'s word-splitting loop for a wide signal
/// (`width > WIDE_SELECT_BITS`): stores `val_part ^ unk_part` (the IEEE aval
/// plane) and `unk_part` (bval) into the two `[n_words x i64]` arrays as
/// whole zero-extended integers, instead of one full-width shift+truncate
/// per word (quadratic in `width`; see [`gather_planes_via_memory`]).
fn scatter_planes_via_memory<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    val_part: IntValue<'ctx>,
    unk_part: IntValue<'ctx>,
    width: u32,
    aval_arr: PointerValue<'ctx>,
    bval_arr: PointerValue<'ctx>,
) {
    const _: () = assert!(cfg!(target_endian = "little"));
    let b = &cx.b;
    let n_words = width.div_ceil(64);
    let padded_bits = n_words * 64;
    let padded_ty = int_type(cx.ctx, padded_bits);
    let aval = b
        .build_xor(val_part, unk_part, "wideview_set_aval")
        .unwrap();
    for (plane, arr, name) in [
        (aval, aval_arr, "wideview_set_aval_pad"),
        (unk_part, bval_arr, "wideview_set_bval_pad"),
    ] {
        let ext = resize(b, plane, width, padded_ty, padded_bits, name);
        set_align(b.build_store(arr, ext).unwrap(), 8);
    }
}

/// Shared write-side core for [`build_set_wide`]/[`build_set_mem_word`]: the
/// inverse of [`build_wideview_to_packed`] -- splits `value` (LLVM type
/// `i(2*width)`, codegen's width-tight packing) into `width.div_ceil(64)`
/// `(aval,bval)` `u64` word pairs, stores them into two fresh stack arrays,
/// assembles a [`vj_abi::accessor::WideView`] pointing at them, and calls
/// `set_fn(handle, slot[, row_index], &view)` (byval).
fn build_packed_to_wideview<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    set_fn: FunctionValue<'ctx>,
    handle: PointerValue<'ctx>,
    slot: impl Into<Slot<'ctx>>,
    row_index: Option<IntValue<'ctx>>,
    value: IntValue<'ctx>,
    width: u32,
) {
    let ctx = cx.ctx;
    let b = &cx.b;
    let n_words = width.div_ceil(64);
    let i64_ty = ctx.i64_type();
    let i32_ty = ctx.i32_type();
    let val_ty = int_type(ctx, width);
    let packed_bits = width.checked_mul(2).expect("width*2 overflow");
    let packed_ty = int_type(ctx, packed_bits);

    let width_const = packed_ty.const_int(u64::from(width), false);
    // The low-`width`-bits mask within a `packed_bits`-wide type, built via
    // an in-type logical right shift of all-ones by `width` (== `packed_bits
    // - width`) rather than a `u64` literal -- `packed_bits` can exceed 64
    // (a >32-bit-row memory), so `IntType::const_int`'s `u64` payload alone
    // cannot represent this mask for every width this function must support.
    let low_mask = b
        .build_right_shift(
            packed_ty.const_all_ones(),
            width_const,
            false,
            "wideview_set_low_mask",
        )
        .unwrap();
    let val_part_wide = b
        .build_and(value, low_mask, "wideview_set_val_part_wide")
        .unwrap();
    let shifted = b
        .build_right_shift(value, width_const, false, "wideview_set_shift")
        .unwrap();
    let unk_part_wide = b
        .build_and(shifted, low_mask, "wideview_set_unk_part_wide")
        .unwrap();
    let val_part = resize(
        b,
        val_part_wide,
        packed_bits,
        val_ty,
        width,
        "wideview_set_val_part",
    );
    let unk_part = resize(
        b,
        unk_part_wide,
        packed_bits,
        val_ty,
        width,
        "wideview_set_unk_part",
    );

    let arr_ty = i64_ty.array_type(n_words);
    // Entry-block scratch shared by every call site (see
    // `crate::ops::shared_entry_alloca`): `set_fn` copies the words out
    // before returning, so the next call site may reuse the same arrays.
    let aval_alloca = crate::ops::shared_entry_alloca(
        ctx,
        b,
        arr_ty,
        &format!("wideview_set_aval_arr_{n_words}"),
    );
    let bval_alloca = crate::ops::shared_entry_alloca(
        ctx,
        b,
        arr_ty,
        &format!("wideview_set_bval_arr_{n_words}"),
    );
    let idx0 = i32_ty.const_zero();
    let loop_words = if width > crate::ops::WIDE_SELECT_BITS {
        scatter_planes_via_memory(cx, val_part, unk_part, width, aval_alloca, bval_alloca);
        0
    } else {
        n_words
    };
    for i in 0..loop_words {
        let shift = val_ty.const_int(u64::from(i) * 64, false);
        let val_word_wide = b
            .build_right_shift(val_part, shift, false, "wideview_set_val_word_wide")
            .unwrap();
        let unk_word_wide = b
            .build_right_shift(unk_part, shift, false, "wideview_set_unk_word_wide")
            .unwrap();
        let val_word = resize(b, val_word_wide, width, i64_ty, 64, "wideview_set_val_word");
        let unk_word = resize(b, unk_word_wide, width, i64_ty, 64, "wideview_set_unk_word");
        let idxn = i32_ty.const_int(u64::from(i), false);
        // SAFETY: `aval_alloca`/`bval_alloca` are fresh `[n_words x i64]`
        // allocas this function itself just built; `i < n_words` by loop
        // construction, so `[0, i]` is an in-bounds GEP into that same
        // allocation (mirrors `ops.rs::OpBuilder::wide_limb_ptr`'s identical
        // two-index array-GEP pattern).
        let aval_word_ptr = unsafe {
            b.build_gep(
                arr_ty,
                aval_alloca,
                &[idx0, idxn],
                "wideview_set_aval_word_ptr",
            )
            .unwrap()
        };
        let bval_word_ptr = unsafe {
            b.build_gep(
                arr_ty,
                bval_alloca,
                &[idx0, idxn],
                "wideview_set_bval_word_ptr",
            )
            .unwrap()
        };
        // Inverse of `build_wideview_to_packed`'s conversion: IEEE aval =
        // val ^ unk, bval = unk.
        let aval_word = b
            .build_xor(val_word, unk_word, "wideview_set_aval_word")
            .unwrap();
        b.build_store(aval_word_ptr, aval_word).unwrap();
        b.build_store(bval_word_ptr, unk_word).unwrap();
    }

    call_set_view(
        cx,
        set_fn,
        handle,
        slot,
        row_index,
        aval_alloca,
        bval_alloca,
        n_words,
    );
}

/// Assembles a [`vj_abi::accessor::WideView`] over the `n_words`-word
/// `aval`/`bval` planes and calls `set_fn(handle, slot[, row_index], &view)`.
#[allow(clippy::too_many_arguments)]
fn call_set_view<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    set_fn: FunctionValue<'ctx>,
    handle: PointerValue<'ctx>,
    slot: impl Into<Slot<'ctx>>,
    row_index: Option<IntValue<'ctx>>,
    aval_alloca: PointerValue<'ctx>,
    bval_alloca: PointerValue<'ctx>,
    n_words: u32,
) {
    let ctx = cx.ctx;
    let b = &cx.b;
    let i32_ty = ctx.i32_type();
    let wide_view_ty = wide_view_llvm_type(ctx);
    let view_alloca = crate::ops::shared_entry_alloca(ctx, b, wide_view_ty, "wideview_set_view");
    let aval_field = b
        .build_struct_gep(wide_view_ty, view_alloca, 0, "wideview_set_aval_field")
        .unwrap();
    let bval_field = b
        .build_struct_gep(wide_view_ty, view_alloca, 1, "wideview_set_bval_field")
        .unwrap();
    let wc_field = b
        .build_struct_gep(wide_view_ty, view_alloca, 2, "wideview_set_wc_field")
        .unwrap();
    b.build_store(aval_field, aval_alloca).unwrap();
    b.build_store(bval_field, bval_alloca).unwrap();
    b.build_store(wc_field, i32_ty.const_int(u64::from(n_words), false))
        .unwrap();

    let slot_const = slot.into().value(ctx);
    match row_index {
        Some(idx) => b
            .build_call(
                set_fn,
                &[
                    handle.into(),
                    slot_const.into(),
                    idx.into(),
                    view_alloca.into(),
                ],
                "wideview_set_call",
            )
            .unwrap(),
        None => b
            .build_call(
                set_fn,
                &[handle.into(), slot_const.into(), view_alloca.into()],
                "wideview_set_call",
            )
            .unwrap(),
    };
}

/// R-run Task 13 (ST-009/AB-050/CG-163): reads a `SlotClass::Wide` external
/// signal (`64 < width <= WIDE_THRESHOLD`, codegen's own `value::
/// WIDE_THRESHOLD`) via `sv_get_wide` -- the wide-tier sibling of
/// [`build_get_scalar`], for a signal too wide for the `SlotClass::
/// Inline`-only accessor tier.
pub fn build_get_wide<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    fns: &AccessorFns<'ctx>,
    handle: PointerValue<'ctx>,
    slot: u32,
    width: u32,
) -> IntValue<'ctx> {
    debug_assert!(
        width > 64,
        "build_get_wide is for SlotClass::Wide (width > 64); use build_get_scalar for width <= 64, got {width}"
    );
    build_wideview_to_packed(cx, fns.get_wide, handle, slot, None, width)
}

/// The `sv_set_wide` write-side twin of [`build_get_wide`].
pub fn build_set_wide<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    fns: &AccessorFns<'ctx>,
    handle: PointerValue<'ctx>,
    slot: u32,
    value: IntValue<'ctx>,
    width: u32,
) {
    debug_assert!(
        width > 64,
        "build_set_wide is for SlotClass::Wide (width > 64); use build_set_scalar for width <= 64, got {width}"
    );
    build_packed_to_wideview(cx, fns.set_wide, handle, slot, None, value, width);
}

/// Reads a signal wider than the narrow path's ceiling (`crate::huge`) into
/// the PK image at `dst` (`ceil(2 * width / 64)` words).
pub fn build_get_huge<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    fns: &AccessorFns<'ctx>,
    handle: PointerValue<'ctx>,
    slot: u32,
    width: u32,
    dst: PointerValue<'ctx>,
) {
    get_huge_view(cx, fns.get_wide, handle, slot, None, width, dst);
}

/// [`build_get_huge`] for row `row_index` (an `i64`, in range) of a
/// `SlotClass::Memory` array whose rows are wider than the narrow path's
/// ceiling (LRM 1800-2023 6.9.1).
pub fn build_get_mem_huge<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    fns: &AccessorFns<'ctx>,
    handle: PointerValue<'ctx>,
    slot: u32,
    row_index: IntValue<'ctx>,
    width: u32,
    dst: PointerValue<'ctx>,
) {
    get_huge_view(
        cx,
        fns.get_mem_word(),
        handle,
        slot,
        Some(row_index),
        width,
        dst,
    );
}

fn get_huge_view<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    get_fn: FunctionValue<'ctx>,
    handle: PointerValue<'ctx>,
    slot: u32,
    row_index: Option<IntValue<'ctx>>,
    width: u32,
    dst: PointerValue<'ctx>,
) {
    let (aval_ptr, bval_ptr) = call_get_view(cx, get_fn, handle, slot, row_index);
    crate::huge::call_wide(
        cx,
        vj_runtime::wide_rt::WideOp::FromPlanes,
        dst,
        aval_ptr,
        bval_ptr,
        [u64::from(width), 0, 0, 0],
    );
}

/// The `sv_set_wide` write-side twin of [`build_get_huge`]: commits the PK
/// image at `src`.
pub fn build_set_huge<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    fns: &AccessorFns<'ctx>,
    handle: PointerValue<'ctx>,
    slot: u32,
    width: u32,
    src: PointerValue<'ctx>,
) {
    set_huge_view(cx, fns.set_wide, handle, slot, None, width, src);
}

/// The write-side twin of [`build_get_mem_huge`].
pub fn build_set_mem_huge<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    fns: &AccessorFns<'ctx>,
    handle: PointerValue<'ctx>,
    slot: u32,
    row_index: IntValue<'ctx>,
    width: u32,
    src: PointerValue<'ctx>,
) {
    set_huge_view(
        cx,
        fns.set_mem_word(),
        handle,
        slot,
        Some(row_index),
        width,
        src,
    );
}

fn set_huge_view<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    set_fn: FunctionValue<'ctx>,
    handle: PointerValue<'ctx>,
    slot: u32,
    row_index: Option<IntValue<'ctx>>,
    width: u32,
    src: PointerValue<'ctx>,
) {
    let ctx = cx.ctx;
    let n_words = width.div_ceil(64);
    let arr_ty = ctx.i64_type().array_type(n_words);
    let aval = crate::ops::shared_entry_alloca(
        ctx,
        &cx.b,
        arr_ty,
        &format!("wideview_set_aval_arr_{n_words}"),
    );
    let bval = crate::ops::shared_entry_alloca(
        ctx,
        &cx.b,
        arr_ty,
        &format!("wideview_set_bval_arr_{n_words}"),
    );
    crate::huge::call_wide(
        cx,
        vj_runtime::wide_rt::WideOp::ToPlanes,
        aval,
        src,
        bval,
        [u64::from(width), 0, 0, 0],
    );
    call_set_view(cx, set_fn, handle, slot, row_index, aval, bval, n_words);
}

/// R-run Task 13 (ST-024): reads one addressed row (`row_index`, an `i64`
/// `IntValue` -- `sv_get_mem_word`'s own `u64` ABI argument) of a
/// `SlotClass::Memory` array via `sv_get_mem_word`, for `elem_width`, the
/// row's own per-element bit width (may be `<= 64` or `> 64` -- `state.md`'s
/// own "works uniformly for narrow- and wide-per-row memories" contract).
pub fn build_get_mem_word<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    fns: &AccessorFns<'ctx>,
    handle: PointerValue<'ctx>,
    slot: impl Into<Slot<'ctx>>,
    row_index: IntValue<'ctx>,
    elem_width: u32,
) -> IntValue<'ctx> {
    debug_assert_eq!(
        row_index.get_type().get_bit_width(),
        64,
        "row_index must be the accessor ABI's own i64 (u64) type"
    );
    build_wideview_to_packed(
        cx,
        fns.get_mem_word(),
        handle,
        slot,
        Some(row_index),
        elem_width,
    )
}

/// The `sv_set_mem_word` write-side twin of [`build_get_mem_word`] (ST-025/
/// ST-114).
pub fn build_set_mem_word<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    fns: &AccessorFns<'ctx>,
    handle: PointerValue<'ctx>,
    slot: impl Into<Slot<'ctx>>,
    row_index: IntValue<'ctx>,
    value: IntValue<'ctx>,
    elem_width: u32,
) {
    debug_assert_eq!(
        row_index.get_type().get_bit_width(),
        64,
        "row_index must be the accessor ABI's own i64 (u64) type"
    );
    build_packed_to_wideview(
        cx,
        fns.set_mem_word(),
        handle,
        slot,
        Some(row_index),
        value,
        elem_width,
    );
}