vj-codegen 0.1.0

//! Task 30 (`docs/superpowers/plans/2026-09-23-wave-A-codegen.md`; ledger
//! CG-043 (partial), CG-044, CG-046 (partial), CG-108): `$display`/`$write`/
//! `$strobe`/`$monitor` statement lowering to the frozen
//! `sv_sim_runtime::rtarg::RtArg` ABI, for the ordinary (non-suspending)
//! leaf-function/statement-lowering pipeline -- `func.rs`'s
//! `StatementKind::ExpressionStatement` arm routes a recognized
//! display-family system call here, BEFORE `expr.rs`'s generic `Call` arm
//! (which only knows CG-042's constant-foldable type-query subset and would
//! otherwise reject `$display` et al. with a named "CG-043's scope" error --
//! see that arm's own doc comment).
//!
//! **Deviation from the plan (discovered implementing this task):** the
//! process-CFG lowering pipeline (`process_lower.rs`, landed by a different,
//! already-merged track -- "A2-slice" Task S6, CG-045) already implements an
//! equivalent `$display`/`$write` lowering (`lower_display_write_call`)
//! against the same frozen `RtArg` shape, for ITS OWN pipeline (CFG
//! segments + `SimHandle`). This task's own `Files:` list does not name
//! `process_lower.rs`, and touching a file another concurrently-running
//! track owns risks a collision at integration time, so this module does
//! NOT refactor that file to share code with it -- the `RtArg` LLVM
//! struct-type mirror and the C-string-global builder are therefore
//! necessarily duplicated here rather than factored into one shared helper.
//! Both copies are independently pinned against the same real
//! `sv_sim_runtime::rtarg::RtArg` type (see
//! `rtarg_llvm_struct_size_and_align_match_rust_repr_c_exactly` below), so a
//! future drift in either would fail loudly, not silently diverge.
//!
//! **Deviation from the plan's literal `rtarg_llvm_type` field list**: the
//! plan (written before this track's base commit) describes an 8-field
//! `RtArg` (`kind, bit_width, narrow, wide_aval, wide_bval, wide_words,
//! str_ptr, str_len`). The REAL, already-committed `sv_sim_runtime::rtarg::
//! RtArg` (landed ancestor commits `4140ec5`/`7d19fbe`) has 10 fields --
//! `kind, bit_width, is_signed, narrow, real, wide_aval, wide_bval,
//! wide_words, str_ptr, str_len` (`size_of::<RtArg>() == 80`,
//! `align_of::<RtArg>() == 16`) -- adding an `is_signed: bool` (RT-044) and
//! a `real: f64` lane (`RtArgKind::Real`, RT-043) the plan's draft predates.
//! This module builds against the REAL, frozen shape.
//!
//! **Deviation from the plan's literal `push_rtarg_for_value` signature**:
//! the plan describes branching on `value::AnyValue`'s two shape variants
//! (`Narrow`/`Wide`). The actual value type `lower_expr` (`expr.rs`)
//! produces is `LoweredValue` (`Packed`/`Real`/`Wide` -- three variants,
//! Task 8's `real` support postdates `AnyValue`'s design). This module's
//! `push_rtarg_for_value` therefore branches on `LoweredValue`'s three shape
//! variants instead -- still satisfying CG-044's structural guarantee (no
//! branch on argument position or format-directive content, only on the
//! argument's own value SHAPE). `LoweredValue::Real`/`LoweredValue::Wide`
//! are out of this task's own scope (not named by CG-043/CG-044/CG-046/
//! CG-108's acceptance text, and not exercised by any test this task's plan
//! specifies): each is a named, loud `LoweringError`, never silently
//! mismarshaled as a `Narrow4State` and never a panic.
//!
//! **`LoweredValue::Packed` is only marshaled up to a 64-bit *declared*
//! width, review-fixed (r2):** the frozen ABI's `RtArgKind::Narrow4State`
//! boundary is on the SV *declared* width (`PackedValue::width`), per
//! ARCHITECTURE.md §6.2's "hard 64-bit boundary" and
//! `sv_sim_runtime::display::reposition_narrow`'s own documented/asserted
//! `width <= 64` invariant -- NOT on `pv.llvm`'s packed LLVM representation
//! width, which r1 of this fix mistakenly guarded on instead.
//! `pv.llvm`'s own packed LLVM int width is not bounded by 128 for a
//! FourState value: under `ValueRepr::FourState` a width-N value packs into
//! one `i(2N)` int (`value.rs`), and N itself is only bounded by
//! `WIDE_THRESHOLD` (128), so a FourState argument whose SV declared width
//! is in `(64, 128]` produces a packed int wider than `RtArg::narrow`'s 128
//! bits -- guarding on the packed width happened to reject this case too.
//! But under `ValueRepr::TwoState`, `pv.llvm`'s packed width equals the
//! declared width exactly (`store_narrow_rtarg`'s own doc comment: "a plain
//! `i(N)` value-only int under `TwoState`"), so a TwoState argument with
//! declared width in `(64, 128]` sails past a `packed_bits > 128` check
//! and would silently lower as an ABI-violating `Narrow4State` RtArg with
//! `bit_width` above 64. `push_rtarg_for_value`'s `Packed` arm therefore
//! checks `pv.width` (not `pv.llvm`'s bit width) before ever calling
//! `store_narrow_rtarg`/`zext_to_i128`, and returns a named `LoweringError`
//! for both reprs alike (mirroring `LoweredValue::Wide`'s existing
//! treatment), rather than emitting a `zext` LLVM cannot verify or a
//! `Narrow4State` RtArg the runtime's own `debug_assert!` would trip on.
//!
//! **B-runtime Task 12 review fix (r1), blocking finding:** this module's
//! `DisplayFamily::Monitor` arm was left building the OLD, wave-A-frozen
//! three-argument `(fmt, args, nargs)` call after B-runtime Task 12
//! (`docs/superpowers/plans/2026-09-27-wave-B-runtime.md`) changed
//! `sv_sim_runtime::monitor::sv_rt_monitor`'s own real, exported ABI to
//! FOUR arguments (`id: MonitorId, fmt, args, nargs`) -- a genuine
//! ABI-corrupting bug for the one real, live caller of that symbol left in
//! this crate (Task 12's own `Files:` list named this exact arm for
//! updating and it was never done). `lower_display_family_call` now
//! rejects `DisplayFamily::Monitor` with a named `LoweringError` instead of
//! building the mismatched call -- see that function's own doc comment for
//! the full reasoning and for why option (a), minting a real per-call-site
//! `MonitorId`, is deferred rather than built here (it needs a
//! monotonic-counter scheme that stays correct across `session.rs`'s
//! rayon-parallel per-`InstanceBody` workers, a substantially larger,
//! cross-file change than this review-fix pass's scope).
use inkwell::AddressSpace;
use inkwell::builder::Builder;
use inkwell::context::Context;
use inkwell::module::{Linkage, Module};
use inkwell::types::StructType;
use inkwell::values::{BasicValue as _, FunctionValue, IntValue, PointerValue};

use sv_lang::KnownSystemName;
use sv_lang::kinds::{ExpressionKind, SymbolKind};

use sv_sim_runtime::file_io::{
    SV_RT_FCLOSE_SYMBOL, SV_RT_FDISPLAY_SYMBOL, SV_RT_FFLUSH_SYMBOL, SV_RT_FMONITOR_SYMBOL,
    SV_RT_FSTROBE_SYMBOL, SV_RT_FWRITE_SYMBOL,
};
use sv_sim_runtime::fst::{SV_RT_DUMPFILE_SYMBOL, SV_RT_DUMPFLUSH_SYMBOL};
use sv_sim_runtime::rtarg::{
    SV_RT_DISPLAY_SYMBOL, SV_RT_MONITOR_SYMBOL, SV_RT_STROBE_SYMBOL, SV_RT_WRITE_SYMBOL,
};
use sv_sim_runtime::sdf_annotate::SV_RT_SDF_ANNOTATE_SYMBOL;

use crate::error::LoweringError;
use crate::expr::{LowerCtx, LoweredValue, lower_expr};
use crate::types::int_type;
use crate::value::PackedValue;

/// The four `$display`-family groups the frozen ABI names one symbol per
/// (`rtarg.rs`'s `SV_RT_*_SYMBOL` constants) -- deliberately coarse: every
/// radix-suffixed variant (`$displayh`, `$writeo`, ...) of a family routes
/// to that SAME family's one symbol (see the scope note on
/// `classify_display_family` below).
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum DisplayFamily {
    Display,
    Write,
    Strobe,
    Monitor,
}

/// Maps a `KnownSystemName` to its `DisplayFamily`, or `None` for anything
/// else (every other system call, including CG-042's type-query family and
/// the not-yet-implemented rest of CG-043's breadth). Confirmed against the
/// vendored `sv-lang` 0.1.9 `system_subroutine_kinds.rs` source (Task 1's
/// cross-check discipline) before writing this match: `Display`/`DisplayB`/
/// `DisplayO`/`DisplayH` (discriminants 136-139), `Write`/`WriteB`/`WriteO`/
/// `WriteH` (140-143), `Strobe`/`StrobeB`/`StrobeO`/`StrobeH` (144-147),
/// `Monitor`/`MonitorB`/`MonitorO`/`MonitorH` (148-151).
///
/// Deliberately coarse (documented, not a silent gap): the frozen ABI has
/// exactly one symbol per family regardless of the radix suffix -- `%h`/
/// `%o`/`%b`'s default-radix behavior for arguments with no explicit format
/// directive is runtime's own job (CG-108: format-directive interpretation
/// never happens in this crate), not something the SYMBOL choice encodes.
pub fn classify_display_family(name: KnownSystemName) -> Option<DisplayFamily> {
    use KnownSystemName::{
        Display, DisplayB, DisplayH, DisplayO, Monitor, MonitorB, MonitorH, MonitorO, Strobe,
        StrobeB, StrobeH, StrobeO, Write, WriteB, WriteH, WriteO,
    };
    match name {
        Display | DisplayB | DisplayO | DisplayH => Some(DisplayFamily::Display),
        Write | WriteB | WriteO | WriteH => Some(DisplayFamily::Write),
        Strobe | StrobeB | StrobeO | StrobeH => Some(DisplayFamily::Strobe),
        Monitor | MonitorB | MonitorO | MonitorH => Some(DisplayFamily::Monitor),
        _ => None,
    }
}

/// The frozen ABI's own symbol constant for a family -- re-exported
/// verbatim (never re-typed as a local string literal), so a rename on the
/// runtime side is a compile error here, not silent drift.
pub fn display_family_symbol(f: DisplayFamily) -> &'static str {
    match f {
        DisplayFamily::Display => SV_RT_DISPLAY_SYMBOL,
        DisplayFamily::Write => SV_RT_WRITE_SYMBOL,
        DisplayFamily::Strobe => SV_RT_STROBE_SYMBOL,
        DisplayFamily::Monitor => SV_RT_MONITOR_SYMBOL,
    }
}

/// Mirrors `sv_sim_runtime::rtarg::RtArg`'s `#[repr(C)]` layout field-for-
/// field, in its exact declared field order -- LLVM's default (non-packed)
/// struct layout inserts the same natural-alignment padding Rust's
/// `repr(C)` does on this project's one real target, so this type's ABI
/// size/alignment must match `RtArg`'s own exactly (pinned by
/// `rtarg_llvm_struct_size_and_align_match_rust_repr_c_exactly`,
/// `tests/systask_display.rs`).
pub fn rtarg_llvm_type<'ctx>(ctx: &'ctx Context) -> StructType<'ctx> {
    let i32_ty = ctx.i32_type();
    let i8_ty = ctx.i8_type();
    let i128_ty = ctx.i128_type();
    let f64_ty = ctx.f64_type();
    let ptr_ty = ctx.ptr_type(AddressSpace::default());
    ctx.struct_type(
        &[
            i32_ty.into(),  // kind: RtArgKind
            i32_ty.into(),  // bit_width
            i8_ty.into(),   // is_signed
            i128_ty.into(), // narrow
            f64_ty.into(),  // real
            ptr_ty.into(),  // wide_aval
            ptr_ty.into(),  // wide_bval
            i32_ty.into(),  // wide_words
            ptr_ty.into(),  // str_ptr
            i32_ty.into(),  // str_len
        ],
        false,
    )
}

/// Zero-extends `v` up to `i128` -- a no-op when `v` is already `i128`
/// (`width == 64`'s width-tight `i(2*64) == i128` packing; LLVM's
/// `build_int_z_extend` between two equal-width int types is a builder
/// error, not a silent no-op).
fn zext_to_i128<'ctx>(ctx: &'ctx Context, b: &Builder<'ctx>, v: IntValue<'ctx>) -> IntValue<'ctx> {
    if v.get_type().get_bit_width() == 128 {
        v
    } else {
        b.build_int_z_extend(v, ctx.i128_type(), "rtarg_narrow_zext")
            .unwrap()
    }
}

/// Stores one `RtArgKind::Narrow4State` element's fields into `elem_ptr`
/// (an `rtarg_llvm_type` array element inside a private, per-call
/// `alloca`'d array). `pv.llvm` is already codegen's own width-tight
/// `i(2N)` packing under `FourState` repr (`value.rs`: "Per-bit lane
/// 2*unk+val matches sv_lang::Bit"), or a plain `i(N)` value-only int under
/// `TwoState` -- either way, zero-extending it directly up to `i128` places
/// the raw value bits at exactly `RtArg::narrow`'s own documented offset
/// (`rtarg.rs`: "packed i(2N)"), with the (absent, in `TwoState`) unknown
/// lane implicitly all-zero above it -- exactly 2-state's "unk hard-wired
/// to 0" convention, with NO extra instruction needed to force it.
pub(crate) fn store_narrow_rtarg<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    rtarg_ty: StructType<'ctx>,
    elem_ptr: PointerValue<'ctx>,
    pv: PackedValue<'ctx>,
) {
    let ctx = cx.ctx;
    let b = &cx.b;
    let i32_ty = ctx.i32_type();
    let i8_ty = ctx.i8_type();
    let f64_ty = ctx.f64_type();
    let ptr_ty = ctx.ptr_type(AddressSpace::default());

    let field = |idx: u32, name: &str| b.build_struct_gep(rtarg_ty, elem_ptr, idx, name).unwrap();

    // RtArgKind::Narrow4State == 0 (rtarg.rs).
    b.build_store(field(0, "rtarg_kind"), i32_ty.const_int(0, false))
        .unwrap();
    b.build_store(
        field(1, "rtarg_width"),
        i32_ty.const_int(u64::from(pv.width), false),
    )
    .unwrap();
    b.build_store(
        field(2, "rtarg_signed"),
        i8_ty.const_int(u64::from(pv.signed), false),
    )
    .unwrap();
    let narrow = zext_to_i128(ctx, b, pv.llvm);
    b.build_store(field(3, "rtarg_narrow"), narrow).unwrap();
    b.build_store(field(4, "rtarg_real"), f64_ty.const_float(0.0))
        .unwrap();
    b.build_store(field(5, "rtarg_wide_aval"), ptr_ty.const_null())
        .unwrap();
    b.build_store(field(6, "rtarg_wide_bval"), ptr_ty.const_null())
        .unwrap();
    b.build_store(field(7, "rtarg_wide_words"), i32_ty.const_int(0, false))
        .unwrap();
    b.build_store(field(8, "rtarg_str_ptr"), ptr_ty.const_null())
        .unwrap();
    b.build_store(field(9, "rtarg_str_len"), i32_ty.const_int(0, false))
        .unwrap();
}

/// R-run Task 13 (self-contained follow-on to ST-009/AB-050/CG-163's own
/// accessor dispatch): `RtArgKind::Wide4State` marshaling for a `$display`/
/// `$write` argument whose SV declared width is `> 64` -- `wide_vectors.sv`'s
/// own acceptance ("`$display("%h", a)` for a 128-bit `a`") needs this, not
/// just the accessor-ABI read/write dispatch `prime_external_signals`/
/// `flush_external_signals` gained above; `sv_sim_runtime::display::
/// coerce_rt_arg`'s own `RtArgKind::Wide4State` arm (runtime-side formatting)
/// already exists and needs no change here -- only this codegen-side
/// marshaling half was missing. Splits `pv.llvm` into `width.div_ceil(64)`
/// `(aval,bval)` `u64` word pairs on two fresh stack arrays (mirrors
/// `accessor.rs`'s own `build_packed_to_wideview` private helper -- a
/// different call site, feeding `RtArg`'s own three wide fields directly
/// instead of a `WideView` byval argument, so not reused verbatim, but the
/// same word-splitting arithmetic), handling BOTH `ValueRepr`s the same way
/// [`store_narrow_rtarg`]'s own `zext_to_i128` does: under `FourState`,
/// `pv.llvm` is `(unk << width) | val`, `2*width` bits wide, split by
/// mask+shift; under `TwoState`, `pv.llvm` IS the value plane (`width` bits),
/// with `unk` hard-wired to all-zero (this crate's own "2-state's unk
/// hard-wired to 0" convention, generalized to the wide tier).
pub(crate) fn store_wide_rtarg<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    rtarg_ty: StructType<'ctx>,
    elem_ptr: PointerValue<'ctx>,
    pv: PackedValue<'ctx>,
) {
    let ctx = cx.ctx;
    let b = &cx.b;
    let i32_ty = ctx.i32_type();
    let i8_ty = ctx.i8_type();
    let i64_ty = ctx.i64_type();
    let f64_ty = ctx.f64_type();
    let ptr_ty = ctx.ptr_type(AddressSpace::default());
    let width = pv.width;
    let n_words = width.div_ceil(64);
    let val_ty = int_type(ctx, width);

    let llvm_bits = pv.llvm.get_type().get_bit_width();
    let (val_part, unk_part) = if llvm_bits == width {
        (pv.llvm, val_ty.const_zero())
    } else {
        debug_assert_eq!(
            llvm_bits,
            width.checked_mul(2).expect("width*2 overflow"),
            "a wide $display argument's packed LLVM width must be either `width` (TwoState) \
             or `2*width` (FourState)"
        );
        let packed_ty = pv.llvm.get_type();
        let width_const = packed_ty.const_int(u64::from(width), false);
        let low_mask = b
            .build_right_shift(
                packed_ty.const_all_ones(),
                width_const,
                false,
                "rtarg_wide_low_mask",
            )
            .unwrap();
        let val_part_wide = b
            .build_and(pv.llvm, low_mask, "rtarg_wide_val_part_wide")
            .unwrap();
        let shifted = b
            .build_right_shift(pv.llvm, width_const, false, "rtarg_wide_shift")
            .unwrap();
        let unk_part_wide = b
            .build_and(shifted, low_mask, "rtarg_wide_unk_part_wide")
            .unwrap();
        let val_part = b
            .build_int_truncate(val_part_wide, val_ty, "rtarg_wide_val_part")
            .unwrap();
        let unk_part = b
            .build_int_truncate(unk_part_wide, val_ty, "rtarg_wide_unk_part")
            .unwrap();
        (val_part, unk_part)
    };

    let arr_ty = i64_ty.array_type(n_words);
    let aval_alloca = crate::types::entry_alloca_in(b, arr_ty, "rtarg_wide_aval_arr");
    let bval_alloca = crate::types::entry_alloca_in(b, arr_ty, "rtarg_wide_bval_arr");
    let idx0 = i32_ty.const_zero();
    for i in 0..n_words {
        let shift = val_ty.const_int(u64::from(i) * 64, false);
        let val_word_wide = b
            .build_right_shift(val_part, shift, false, "rtarg_wide_val_word_wide")
            .unwrap();
        let unk_word_wide = b
            .build_right_shift(unk_part, shift, false, "rtarg_wide_unk_word_wide")
            .unwrap();
        let val_word = b
            .build_int_truncate(val_word_wide, i64_ty, "rtarg_wide_val_word")
            .unwrap();
        let unk_word = b
            .build_int_truncate(unk_word_wide, i64_ty, "rtarg_wide_unk_word")
            .unwrap();
        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.
        let aval_word_ptr = unsafe {
            b.build_gep(
                arr_ty,
                aval_alloca,
                &[idx0, idxn],
                "rtarg_wide_aval_word_ptr",
            )
            .unwrap()
        };
        let bval_word_ptr = unsafe {
            b.build_gep(
                arr_ty,
                bval_alloca,
                &[idx0, idxn],
                "rtarg_wide_bval_word_ptr",
            )
            .unwrap()
        };
        // `RtArg`'s wide planes are IEEE aval/bval (the runtime decodes them
        // via `LogicValueView`), not codegen's val/unk: aval = val ^ unk
        // (see `accessor::build_wideview_to_packed`'s identical conversion).
        let aval_word = b
            .build_xor(val_word, unk_word, "rtarg_wide_aval_word")
            .unwrap();
        b.build_store(aval_word_ptr, aval_word).unwrap();
        b.build_store(bval_word_ptr, unk_word).unwrap();
    }

    let field = |idx: u32, name: &str| b.build_struct_gep(rtarg_ty, elem_ptr, idx, name).unwrap();
    // RtArgKind::Wide4State == 1 (sv_sim_runtime::rtarg).
    b.build_store(field(0, "rtarg_kind"), i32_ty.const_int(1, false))
        .unwrap();
    b.build_store(
        field(1, "rtarg_width"),
        i32_ty.const_int(u64::from(width), false),
    )
    .unwrap();
    b.build_store(
        field(2, "rtarg_signed"),
        i8_ty.const_int(u64::from(pv.signed), false),
    )
    .unwrap();
    b.build_store(field(3, "rtarg_narrow"), ctx.i128_type().const_zero())
        .unwrap();
    b.build_store(field(4, "rtarg_real"), f64_ty.const_float(0.0))
        .unwrap();
    b.build_store(field(5, "rtarg_wide_aval"), aval_alloca)
        .unwrap();
    b.build_store(field(6, "rtarg_wide_bval"), bval_alloca)
        .unwrap();
    b.build_store(
        field(7, "rtarg_wide_words"),
        i32_ty.const_int(u64::from(n_words), false),
    )
    .unwrap();
    b.build_store(field(8, "rtarg_str_ptr"), ptr_ty.const_null())
        .unwrap();
    b.build_store(field(9, "rtarg_str_len"), i32_ty.const_int(0, false))
        .unwrap();
}

/// A vector wider than `WIDE_THRESHOLD` bits (a memory image,
/// `crate::huge`): `RtArgKind::Wide4State` (1) with the image converted to
/// IEEE aval/bval planes in two frame arrays (`sv_rt_wide` `ToPlanes`).
pub(crate) fn store_huge_rtarg<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    rtarg_ty: StructType<'ctx>,
    elem_ptr: PointerValue<'ctx>,
    h: crate::huge::HugeValue<'ctx>,
) {
    let ctx = cx.ctx;
    let b = &cx.b;
    let i32_ty = ctx.i32_type();
    let ptr_ty = ctx.ptr_type(AddressSpace::default());
    let n_words = h.width.div_ceil(64);
    let arr_ty = ctx.i64_type().array_type(n_words);
    let aval = crate::types::entry_alloca_in(b, arr_ty, "rtarg_huge_aval_arr");
    let bval = crate::types::entry_alloca_in(b, arr_ty, "rtarg_huge_bval_arr");
    crate::huge::push_planes(cx, h, aval, bval);
    crate::huge::release(h.ptr);
    let field = |idx: u32, name: &str| b.build_struct_gep(rtarg_ty, elem_ptr, idx, name).unwrap();
    // RtArgKind::Wide4State == 1 (sv_sim_runtime::rtarg).
    b.build_store(field(0, "rtarg_kind"), i32_ty.const_int(1, false))
        .unwrap();
    b.build_store(
        field(1, "rtarg_width"),
        i32_ty.const_int(u64::from(h.width), false),
    )
    .unwrap();
    b.build_store(
        field(2, "rtarg_signed"),
        ctx.i8_type().const_int(u64::from(h.signed), false),
    )
    .unwrap();
    b.build_store(field(3, "rtarg_narrow"), ctx.i128_type().const_zero())
        .unwrap();
    b.build_store(field(4, "rtarg_real"), ctx.f64_type().const_float(0.0))
        .unwrap();
    b.build_store(field(5, "rtarg_wide_aval"), aval).unwrap();
    b.build_store(field(6, "rtarg_wide_bval"), bval).unwrap();
    b.build_store(
        field(7, "rtarg_wide_words"),
        i32_ty.const_int(u64::from(n_words), false),
    )
    .unwrap();
    b.build_store(field(8, "rtarg_str_ptr"), ptr_ty.const_null())
        .unwrap();
    b.build_store(field(9, "rtarg_str_len"), i32_ty.const_int(0, false))
        .unwrap();
}

/// A real argument: `RtArgKind::Real` (3) with the value in `real`.
pub(crate) fn store_real_rtarg<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    rtarg_ty: StructType<'ctx>,
    elem_ptr: PointerValue<'ctx>,
    rv: crate::value::RealValue<'ctx>,
) {
    let ctx = cx.ctx;
    let b = &cx.b;
    let i32_ty = ctx.i32_type();
    let ptr_ty = ctx.ptr_type(AddressSpace::default());
    let field = |idx: u32, name: &str| b.build_struct_gep(rtarg_ty, elem_ptr, idx, name).unwrap();
    b.build_store(field(0, "rtarg_kind"), i32_ty.const_int(3, false))
        .unwrap();
    b.build_store(field(1, "rtarg_width"), i32_ty.const_int(64, false))
        .unwrap();
    b.build_store(field(2, "rtarg_signed"), ctx.i8_type().const_int(1, false))
        .unwrap();
    b.build_store(field(3, "rtarg_narrow"), ctx.i128_type().const_zero())
        .unwrap();
    b.build_store(field(4, "rtarg_real"), crate::real::as_f64(cx, rv.llvm))
        .unwrap();
    b.build_store(field(5, "rtarg_wide_aval"), ptr_ty.const_null())
        .unwrap();
    b.build_store(field(6, "rtarg_wide_bval"), ptr_ty.const_null())
        .unwrap();
    b.build_store(field(7, "rtarg_wide_words"), i32_ty.const_int(0, false))
        .unwrap();
    b.build_store(field(8, "rtarg_str_ptr"), ptr_ty.const_null())
        .unwrap();
    b.build_store(field(9, "rtarg_str_len"), i32_ty.const_int(0, false))
        .unwrap();
}

/// This function's ONLY branch is on `LoweredValue`'s shape (`Packed`/
/// `Real`/`Wide`) -- never on argument position, never on any
/// `%`-directive character read from the format string -- the exact CG-044
/// structural guarantee (`rtarg_marshaling_does_not_switch_on_argument_
/// semantic_meaning`, `tests/systask_display.rs`, source-scans this
/// function's own text for exactly that).
fn push_rtarg_for_value<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    rtarg_ty: StructType<'ctx>,
    elem_ptr: PointerValue<'ctx>,
    val: LoweredValue<'ctx>,
) -> Result<(), LoweringError> {
    match val {
        LoweredValue::Packed(pv) => {
            // The frozen ABI's actual boundary is on the SV *declared*
            // width (`pv.width`), not on `pv.llvm`'s packed LLVM
            // representation width -- review-fixed (r2), see this module's
            // header doc comment for the r1 regression this closes.
            // ARCHITECTURE.md §6.2: "hard 64-bit boundary: inline packed
            // u128 ... for bit_width <= 64; separate aval/bval Vec<u64>
            // planes for wider". `sv-sim-runtime`'s own
            // `display::reposition_narrow` documents (and
            // `debug_assert!`s) that `width <= 64` always holds for
            // `RtArgKind::Narrow4State`.
            //
            // Under `ValueRepr::FourState`, codegen packs a width-N value
            // into one `i(2N)` int (`value.rs`'s "Per-bit lane 2*unk+val"
            // packing), so `pv.llvm`'s bit width is `2 * pv.width` and a
            // declared width above 64 bits already overflows
            // `RtArg::narrow`'s 128 bits -- checking `packed_bits > 128`
            // happened to reject this case too. But under
            // `ValueRepr::TwoState` (`store_narrow_rtarg`: "a plain `i(N)`
            // value-only int under `TwoState`"), `pv.llvm`'s bit width
            // equals `pv.width` exactly, so a TwoState argument with
            // declared width in `(64, 128]` packs into a <=128-bit LLVM
            // int, sails past a `packed_bits > 128` check, and would
            // lower as a `Narrow4State` RtArg with `bit_width` above the
            // ABI's 64-bit ceiling -- silently violating the same
            // invariant `LoweringError::unsupported_at` below is meant to
            // enforce. Guard on `pv.width` itself -- before ever reaching
            // `store_narrow_rtarg` -- so both reprs are rejected on the
            // same declared-width boundary.
            // A declared width above 64 bits needs `RtArgKind::Wide4State`
            // (`RtArg::narrow` holds at most a 64-bit value's two planes).
            if pv.width > 64 {
                store_wide_rtarg(cx, rtarg_ty, elem_ptr, pv);
            } else {
                store_narrow_rtarg(cx, rtarg_ty, elem_ptr, pv);
            }
            Ok(())
        }
        LoweredValue::Str(s) => {
            crate::strings::store_str_rtarg(cx, rtarg_ty, elem_ptr, s);
            Ok(())
        }
        LoweredValue::Real(rv) => {
            store_real_rtarg(cx, rtarg_ty, elem_ptr, rv);
            Ok(())
        }
        LoweredValue::Huge(h) => {
            store_huge_rtarg(cx, rtarg_ty, elem_ptr, h);
            Ok(())
        }
        LoweredValue::Wide(_) => Err(LoweringError::unsupported_at(
            "a >WIDE_THRESHOLD-bit (wide, limb-array) $display-family argument \
             is out of Task 30's scope (RtArgKind::Wide4State's separate \
             wide_aval/wide_bval array marshaling is not implemented by this \
             crate)",
            &cx.fn_sym,
        )),
    }
}

/// CG-046: forwards the format-string `Expression` as a compile-time
/// constant when it is a `StringLiteral` (the literal half this task
/// implements); any other `ExpressionKind` in the format position is a
/// named `LoweringError` (the dynamic/non-literal half, which needs general
/// SV `string`-type value lowering that does not exist anywhere in this
/// crate -- see this task's own Deferred-section entry), NEVER silently
/// treated as a constant and never a panic.
pub(crate) fn lower_format_expr<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    mut fmt: sv_lang::Expression<'_>,
) -> Result<PointerValue<'ctx>, LoweringError> {
    // B-runtime Task 4 (RT-070/RT-162): a string-literal argument bound to a
    // formally `string`-typed parameter (`$dumpfile`'s single argument, this
    // function's newest caller) arrives here wrapped in an implicit
    // `Conversion` node -- verified this session against a real compiled
    // `$dumpfile("x.fst")` call. `$display`-family format strings (this
    // function's original, still-only-other caller) are never wrapped this
    // way in practice, so this loop is a no-op for them; looping (not
    // unwrapping exactly once) costs nothing and never silently stops one
    // layer short of the real literal.
    while fmt.kind() == ExpressionKind::Conversion {
        fmt = fmt.conversion_operand().ok_or_else(|| {
            LoweringError::unsupported_at("format-string conversion missing operand", &cx.fn_sym)
        })?;
    }
    if fmt.kind() != ExpressionKind::StringLiteral {
        return Ok(crate::strings::c_str(cx, dynamic_format_string(cx, fmt)?));
    }
    let text = fmt.string_literal_value().ok_or_else(|| {
        LoweringError::unsupported_at(
            "$display-family format-string literal has no resolvable text",
            &cx.fn_sym,
        )
    })?;
    Ok(build_c_string_global(
        cx.ctx,
        cx.module,
        &text,
        "display_fmt",
    ))
}

/// A format that is a string value (not a literal), evaluated at run time.
fn dynamic_format_string<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    fmt: sv_lang::Expression<'_>,
) -> Result<crate::strings::StrValue<'ctx>, LoweringError> {
    // A string value as the format: its bytes at run time.
    // An integral character string (LRM 6.16: `reg [8*N-1:0]`, or a
    // concatenation such as `{"work/", name}`) is a legal string
    // argument too (LRM 21.3.1 `$fopen`'s filename, 21.2.1 format).
    // A variable slang types as an `ArbitrarySymbol` (`$dumpports`'s file
    // name operand) has the symbol's type.
    let ty = if fmt.kind() == ExpressionKind::ArbitrarySymbol {
        fmt.referenced_symbol().and_then(|s| s.value_type())
    } else {
        fmt.expr_type()
    };
    if ty.is_some_and(|t| t.is_string() || t.is_integral()) {
        let v = crate::expr::lower_expr(cx, fmt)?;
        // `lower_expr` types by the expression, which an `ArbitrarySymbol`
        // lacks: a `string` variable then arrives as its 64-bit id.
        let v = match v {
            LoweredValue::Packed(pv)
                if fmt.kind() == ExpressionKind::ArbitrarySymbol
                    && ty.is_some_and(|t| t.is_string()) =>
            {
                LoweredValue::Str(crate::strings::from_storage(cx, pv))
            }
            v => v,
        };
        return crate::strings::to_string(cx, v);
    }
    Err(LoweringError::unsupported_at(
        &format!(
            "a format argument that is neither a string literal nor a string value (a {:?} expression)",
            fmt.kind()
        ),
        &cx.fn_sym,
    ))
}

/// A `$display`-family argument list as one format and the values it
/// consumes (LRM 1800-2023 §21.2.1). Arguments are read left to right: a
/// string literal that no pending specifier consumes is format text (its
/// specifiers consume the arguments after it, `%m` becomes the call's
/// scope); any other argument no specifier consumes prints in the task's
/// default radix (`%d`, or `%h`/`%b`/`%o` for the `h`/`b`/`o` variants; a
/// string as `%s`, a real as `%#g`), and an empty argument prints a space.
/// A leading string-typed argument that is not a literal is a format
/// evaluated at run time. The assembled format is checked at compile time.
pub(crate) fn display_format_and_values<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    args: &[sv_lang::Expression<'d>],
    call: sv_lang::Expression<'d>,
) -> Result<(PointerValue<'ctx>, Vec<LoweredValue<'ctx>>), LoweringError> {
    display_format_and_values_flagged(cx, args, call).map(|(f, v, _)| (f, v))
}

/// `true` for a bare `$time`/`$stime`/`$realtime` call (peeled of
/// conversions): the arguments LRM 21.2.3 exempts from `$monitor`'s
/// change detection.
fn is_time_call(mut e: sv_lang::Expression<'_>) -> bool {
    while e.kind() == ExpressionKind::Conversion {
        match e.conversion_operand() {
            Some(inner) => e = inner,
            None => break,
        }
    }
    e.kind() == ExpressionKind::Call
        && e.system_subroutine().is_some_and(|s| {
            matches!(
                s.known_name_id(),
                KnownSystemName::Time | KnownSystemName::STime | KnownSystemName::RealTime
            )
        })
}

/// [`display_format_and_values`] plus, per returned value, whether it is a
/// `$time`/`$stime`/`$realtime` argument (`$monitor` ignores those, LRM 21.2.3).
pub(crate) fn display_format_and_values_flagged<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    args: &[sv_lang::Expression<'d>],
    call: sv_lang::Expression<'d>,
) -> Result<(PointerValue<'ctx>, Vec<LoweredValue<'ctx>>, Vec<bool>), LoweringError> {
    let peel = |mut e: sv_lang::Expression<'d>| {
        while e.kind() == ExpressionKind::Conversion {
            match e.conversion_operand() {
                Some(inner) => e = inner,
                None => break,
            }
        }
        e
    };
    let value = |e: sv_lang::Expression<'d>| -> Result<LoweredValue<'ctx>, LoweringError> {
        let lit = peel(e);
        if lit.kind() == ExpressionKind::StringLiteral {
            let text = lit.string_literal_value().unwrap_or_default();
            // The empty literal `""` is the 8-bit value 8'h00 (LRM 5.9), so
            // `%s` of it prints the NUL byte as a space, not nothing.
            // A literal holding a NUL byte is likewise an integral value
            // (`%s` prints each NUL as a space, `%x` keeps the zero bytes);
            // a string value would silently drop them (ivtest string13).
            if !text.is_empty() && !text.as_bytes().contains(&0) {
                return Ok(LoweredValue::Str(crate::strings::literal(
                    cx,
                    text.as_bytes(),
                )));
            }
        }
        lower_expr(cx, e)
    };
    let radix = call
        .system_subroutine()
        .map(|s| s.name())
        .and_then(|n| n.chars().last())
        .filter(|c| matches!(c, 'b' | 'h' | 'o'))
        .unwrap_or('d');
    if let Some(&first) = args.first()
        && peel(first).kind() != ExpressionKind::StringLiteral
        && first.expr_type().is_some_and(|t| t.is_string())
    {
        let mut fmt = None;
        // `%v` through a run-time format (LRM 21.2.1.5): the specifier cannot
        // be tagged at compile time, so each argument that is a tracked net
        // rides in a trailer appended to the format string, which the runtime
        // matches to a key-less `%v` by argument position
        // (`sv_sim_runtime::fmt::DYN_STRENGTH_MARK`). Only built when
        // the design shows strengths at all.
        let mut trailer = String::new();
        for (i, &a) in args[1..].iter().enumerate() {
            if let Some((key, off)) = net_strength_key(peel(a)) {
                trailer.push_str(&format!("{i}:{key:x}@{off};"));
            } else if reads_net(a) && net_strength_segs(peel(a)).is_some() {
                // Tracked, but only a constant-format `%v` can print it.
                trailer.push_str(&format!("{i}:!;"));
            } else if reads_net(a) && is_net_select(peel(a)) {
                trailer.push_str(&format!("{i}:!;"));
            }
        }
        // The default specifier of each argument, for those the run-time
        // format leaves unconsumed (LRM 21.2.1.2).
        let mut extras = String::new();
        if args.len() > 1 {
            extras.push(sv_sim_runtime::fmt::DYN_EXTRA_MARK);
            for &a in &args[1..] {
                let ty = a.expr_type();
                extras.push(
                    if a.kind() == ExpressionKind::EmptyArgument
                        || ty.is_some_and(|t| t.is_string())
                    {
                        's'
                    } else if ty.is_some_and(|t| t.is_floating()) {
                        'g'
                    } else {
                        radix
                    },
                );
            }
        }
        if !trailer.is_empty() {
            trailer.insert(0, sv_sim_runtime::fmt::DYN_STRENGTH_MARK);
        }
        let tail = format!("{extras}{trailer}");
        if !tail.is_empty() {
            let s = dynamic_format_string(cx, peel(first))?;
            let t = crate::strings::literal(cx, tail.as_bytes());
            let cat = crate::strings::str_op(
                cx,
                sv_sim_sim::strings::StrOp::Concat,
                s.llvm,
                t.llvm,
                cx.ctx.i64_type().const_zero(),
            );
            fmt = Some(crate::strings::c_str(
                cx,
                crate::strings::StrValue { llvm: cat },
            ));
        }
        let fmt = match fmt {
            Some(f) => f,
            None => lower_format_expr(cx, first)?,
        };
        // An empty argument prints a space (LRM 21.2.1.4): a one-space string
        // value, which no run-time specifier mistakes for data it must keep.
        let values = args[1..]
            .iter()
            .map(|&a| {
                if a.kind() == ExpressionKind::EmptyArgument {
                    Ok(LoweredValue::Str(crate::strings::literal(cx, b" ")))
                } else {
                    value(a)
                }
            })
            .collect::<Result<Vec<_>, _>>()?;
        let flags = args[1..].iter().map(|&a| is_time_call(a)).collect();
        return Ok((fmt, values, flags));
    }
    let scope_sym = call.system_call_scope().unwrap_or(cx.fn_sym);
    let scope = sv_sim_sim::process::cfg::shown_path(&scope_sym);
    let (time_unit, _) = crate::timescale::unit_and_precision(&scope_sym);
    let bad_format = |text: &str, err: sv_sim_runtime::fmt::FormatError| {
        LoweringError::unsupported_at(&format!("format string {text:?}: {err:?}"), &cx.fn_sym)
    };
    let mut text = String::new();
    let mut values = Vec::new();
    let mut pending = 0usize;
    // Where the current format piece starts in `text`, and how many of its
    // argument specifiers are already bound (an expanded `%p` of an
    // aggregate binds one per leaf).
    let mut piece_start = 0usize;
    let mut bound = 0usize;
    let mut flags: Vec<bool> = Vec::new();
    let mut prev_time = false;
    for &a in args {
        // Every value pushed by the previous operand inherits its flag.
        flags.resize(values.len(), prev_time);
        prev_time = is_time_call(a);
        if a.kind() == ExpressionKind::EmptyArgument {
            text.push(' ');
            continue;
        }
        let lit = peel(a);
        if pending == 0 && lit.kind() == ExpressionKind::StringLiteral {
            let piece = sv_sim_runtime::fmt::tag_time_unit(
                &sv_sim_runtime::fmt::substitute_scope(
                    &lit.string_literal_value().unwrap_or_default(),
                    &scope,
                    &library_cell(&scope_sym, &scope),
                ),
                time_unit,
            );
            pending = sv_sim_runtime::fmt::count_args(&piece).map_err(|e| bad_format(&piece, e))?;
            piece_start = text.len();
            bound = 0;
            text.push_str(&piece);
            continue;
        }
        // A queue / dynamic / associative array (`%p`, or no specifier): its
        // pattern text, rendered at run time, printed with `%s`.
        if crate::collections::coll_of_expr(&a).is_some() {
            let v = crate::collections::format_pattern(cx, a)?;
            if pending > 0 {
                pending -= 1;
                let specs = sv_sim_runtime::fmt::arg_specs(&text[piece_start..])
                    .map_err(|e| bad_format(&text, e))?;
                let spec = specs[bound];
                if spec.specifier != 'p' {
                    return Err(LoweringError::unsupported_at(
                        &format!(
                            "a queue, dynamic or associative array printed with %{} (only %p \
                             prints one)",
                            spec.specifier
                        ),
                        &cx.fn_sym,
                    ));
                }
                text.replace_range(piece_start + spec.start..piece_start + spec.end, "%s");
            } else {
                text.push_str("%s");
            }
            bound += 1;
            values.push(v);
            continue;
        }
        // A class handle printed with `%p` (LRM 21.2.1.7): `null`, or the
        // pattern of the object's properties, rendered at run time and
        // printed with `%s` (`classes::format_object`). Any other specifier
        // prints the handle's number like any other integral value.
        if pending > 0
            && let Some(ty) = a.expr_type()
            && ty.is_class()
        {
            let specs = sv_sim_runtime::fmt::arg_specs(&text[piece_start..])
                .map_err(|e| bad_format(&text, e))?;
            let spec = specs[bound];
            if spec.specifier == 'p' {
                let pv = lower_expr(cx, a)?.into_packed("a class handle argument", &cx.fn_sym)?;
                let h = crate::ops::OpBuilder {
                    ctx: cx.ctx,
                    b: &cx.b,
                }
                .lane_val(pv);
                let h =
                    cx.b.build_int_z_extend_or_bit_cast(h, cx.ctx.i64_type(), "p_obj")
                        .unwrap();
                pending -= 1;
                text.replace_range(piece_start + spec.start..piece_start + spec.end, "%s");
                bound += 1;
                values.push(crate::classes::format_object(cx, ty, h)?);
                continue;
            }
        }
        // An enum printed with `%p` (LRM 21.2.1.7): its member name.
        if pending > 0
            && let Some(ty) = a.expr_type()
            && ty.is_enum()
            && crate::types::TypeWidth::value_width(&ty) <= 64
        {
            let specs = sv_sim_runtime::fmt::arg_specs(&text[piece_start..])
                .map_err(|e| bad_format(&text, e))?;
            let spec = specs[bound];
            if spec.specifier == 'p' {
                let pv = lower_expr(cx, a)?.into_packed("an enum argument", &cx.fn_sym)?;
                if let Some(s) = crate::sysfunc::enum_pattern_text(cx, &ty, pv)? {
                    pending -= 1;
                    text.replace_range(piece_start + spec.start..piece_start + spec.end, "%s");
                    bound += 1;
                    values.push(s);
                    continue;
                }
            }
        }
        // An unpacked struct/union (`%p`, or no specifier): its assignment
        // pattern, one singular `%p` per leaf field, spliced into the format.
        let fixed_array = |t: &sv_lang::Type| {
            t.is_unpacked_array() && !sv_sim_sim::state::storage::is_collection(t)
        };
        // A packed struct prints as an assignment pattern too, but only under
        // `%p` (LRM 21.2.1.6); `%d`/`%h`/... take it as its equivalent vector.
        let pk_p = |ty: &sv_lang::Type| -> bool {
            pending > 0
                && ty.is_struct()
                && !ty.is_unpacked_struct()
                && sv_sim_runtime::fmt::arg_specs(&text[piece_start..])
                    .ok()
                    .and_then(|s| s.get(bound).map(|s| s.specifier == 'p'))
                    .unwrap_or(false)
        };
        if let Some(ty) = a.expr_type()
            && (sv_sim_sim::state::storage::is_unpacked_aggregate(&ty)
                || fixed_array(&ty)
                || pk_p(&ty))
        {
            let mut pattern = String::new();
            let mut leaves = Vec::new();
            // A fixed-size array variable: its elements, read one by one.
            let stored = if fixed_array(&ty) {
                match crate::arrays::array_target(cx, a)? {
                    Some(t) => Some(t),
                    None => crate::arrays::array_call_value(cx, a)?,
                }
            } else {
                None
            };
            if let Some((r, shape)) = stored {
                array_pattern(cx, &r, &shape, 0, 0, &mut pattern, &mut leaves)?;
            } else {
                let v =
                    lower_expr(cx, a)?.into_packed("an aggregate display argument", &cx.fn_sym)?;
                aggregate_pattern(cx, &ty, v, &mut pattern, &mut leaves)?;
            }
            if pending > 0 {
                pending -= 1;
                let specs = sv_sim_runtime::fmt::arg_specs(&text[piece_start..])
                    .map_err(|e| bad_format(&text, e))?;
                let spec = specs[bound];
                if spec.specifier != 'p' {
                    return Err(LoweringError::unsupported_at(
                        &format!(
                            "an unpacked struct/union printed with %{} (only %p prints one)",
                            spec.specifier
                        ),
                        &cx.fn_sym,
                    ));
                }
                text.replace_range(piece_start + spec.start..piece_start + spec.end, &pattern);
            } else {
                text.push_str(&pattern);
            }
            bound += leaves.len();
            values.extend(leaves);
            continue;
        }
        bound += 1;
        // The index arguments of a `%v` operand's dynamic selects, which
        // follow the operand in the argument list.
        let mut hidden: Vec<sv_lang::Expression<'d>> = Vec::new();
        if pending > 0 {
            pending -= 1;
            // `%v` (LRM 21.2.1.5) of a net: tag the specifier with the net's
            // key so the runtime prints the strengths its resolver records
            // (`sv_sim_exec::nets`). A select/concatenation of nets has no
            // strength record: refused by name rather than printed strong. A
            // constant bit/part select of a net reads its slice of the record.
            let specs = sv_sim_runtime::fmt::arg_specs(&text[piece_start..])
                .map_err(|e| bad_format(&text, e))?;
            if specs.get(bound - 1).is_some_and(|s| s.specifier == 'v') {
                if let Some((key, off)) = net_strength_key(lit) {
                    let tagged = sv_sim_runtime::fmt::tag_strength_key(
                        &text[piece_start..],
                        bound - 1,
                        key,
                        off,
                    );
                    text.truncate(piece_start);
                    text.push_str(&tagged);
                } else if let Some((segs, idx)) = net_strength_segs(lit) {
                    let tagged = sv_sim_runtime::fmt::tag_strength_segs(
                        &text[piece_start..],
                        bound - 1,
                        &segs,
                    );
                    text.truncate(piece_start);
                    text.push_str(&tagged);
                    hidden = idx;
                } else if reads_net(a) {
                    return Err(LoweringError::unsupported_at(
                        "%v of an expression over nets other than a whole net, a bit/part \
                         select of a packed net, or a concatenation of those (an unpacked-array \
                         net element with a non-constant index keeps no strengths)",
                        &cx.fn_sym,
                    ));
                }
            }
        } else {
            let ty = a.expr_type();
            text.push_str(if ty.is_some_and(|t| t.is_string()) {
                "%s"
            } else if ty.is_some_and(|t| t.is_floating()) {
                "%#g"
            } else {
                match radix {
                    'b' => "%b",
                    'h' => "%h",
                    'o' => "%o",
                    _ => "%d",
                }
            });
        }
        values.push(value(a)?);
        for ix in hidden {
            values.push(value(ix)?);
        }
    }
    if pending > 0 {
        return Err(LoweringError::unsupported_at(
            &format!("format string {text:?} has {pending} more specifier(s) than arguments"),
            &cx.fn_sym,
        ));
    }
    flags.resize(values.len(), prev_time);
    Ok((
        build_c_string_global(cx.ctx, cx.module, &text, "display_fmt"),
        values,
        flags,
    ))
}

/// The strength-registry key of `e` (already peeled of conversions) when it
/// names a whole net or a constant, in-range bit/part select of one, with the
/// net bit the operand's bit 0 is: what `%v` of it prints from.
pub(crate) fn net_strength_key(e: sv_lang::Expression<'_>) -> Option<(u64, u32)> {
    // The selects over the net, outermost first.
    let mut sels = Vec::new();
    let mut base = e;
    while matches!(
        base.kind(),
        ExpressionKind::ElementSelect | ExpressionKind::RangeSelect
    ) {
        sels.push(base);
        base = base.select_value()?;
    }
    if !sv_sim_sim::symid::is_value_name(base.kind()) {
        return None;
    }
    let sym = base.referenced_symbol()?;
    if sym.kind() != SymbolKind::Net {
        return None;
    }
    let uid = sv_sim_sim::symid::SymbolUid::uid(&sym).key_string();
    let net_ty = base.expr_type()?;
    if net_ty.is_unpacked_array() {
        // An element of an unpacked-array net (LRM 6.6.7: each element is a
        // net of its own): one record per element, under the key of its row
        // (storage order, as `sv_sim_bin::nets::net_rows`). Every unpacked
        // index must be constant; the selects over the element are a packed
        // bit/part select of it.
        let mut dims = Vec::new();
        let mut ty = net_ty;
        while ty.is_unpacked_array() {
            let r = ty.fixed_unpacked_array_range();
            dims.push((i64::from(r.left), i64::from(r.right)));
            ty = ty.element_type()?;
        }
        let mut row = 0i64;
        let mut elem = None;
        for (k, &(l, r)) in dims.iter().enumerate() {
            let sel = *sels.get(sels.len().checked_sub(k + 1)?)?;
            if sel.kind() != ExpressionKind::ElementSelect {
                return None;
            }
            let i = sel
                .selector()?
                .constant_value()
                .as_ref()
                .and_then(sv_lang::ConstantValue::as_integer)
                .and_then(sv_lang::SVInt::as_i64)?;
            let n = (l - r).abs() + 1;
            // Declaration-order position `p`; a descending `[l:r]` stores it
            // at `n - 1 - p`.
            let p = if l <= r { i - l } else { l - i };
            if !(0..n).contains(&p) {
                return None;
            }
            row = row * n + if l <= r { p } else { n - 1 - p };
            elem = Some(sel);
        }
        let elem = elem?;
        let packed_selects = sels.len() - dims.len();
        let off = if packed_selects == 0 {
            0
        } else {
            let width = crate::types::TypeWidth::value_width(&elem.expr_type()?);
            crate::select::constant_window_skip(e, width, dims.len())
                .ok()?
                .0
        };
        return Some((
            sv_sim_runtime::fmt::strength_key(&format!("{uid}[{row}]")),
            off,
        ));
    }
    let off = if sels.is_empty() {
        0
    } else {
        let width = crate::types::TypeWidth::value_width(&net_ty);
        crate::select::constant_window(e, width).ok()?.0
    };
    Some((sv_sim_runtime::fmt::strength_key(&uid), off))
}

/// Whether `e` is a select of something (a packed net's bit/part select or an
/// unpacked-array net's element).
fn is_net_select(e: sv_lang::Expression<'_>) -> bool {
    matches!(
        e.kind(),
        ExpressionKind::ElementSelect | ExpressionKind::RangeSelect | ExpressionKind::Concatenation
    )
}

/// The segments a `%v` of `e` (peeled of conversions) is made of, most
/// significant first, and the index expressions of its dynamic bit-selects
/// (one hidden argument each): `e` a concatenation of nets, constant
/// selects, dynamic bit-selects of packed nets and net-free operands (which
/// drive at strong), or itself a dynamic bit-select. `None` for anything else.
fn net_strength_segs<'d>(
    e: sv_lang::Expression<'d>,
) -> Option<(
    Vec<sv_sim_runtime::fmt::StrengthSeg>,
    Vec<sv_lang::Expression<'d>>,
)> {
    use sv_sim_runtime::fmt::{SegAt, StrengthSeg};
    fn peel_conv(mut e: sv_lang::Expression<'_>) -> sv_lang::Expression<'_> {
        while e.kind() == ExpressionKind::Conversion {
            match e.conversion_operand() {
                Some(inner) => e = inner,
                None => break,
            }
        }
        e
    }
    fn walk<'d>(
        e: sv_lang::Expression<'d>,
        segs: &mut Vec<StrengthSeg>,
        idx: &mut Vec<sv_lang::Expression<'d>>,
    ) -> Option<()> {
        let e = peel_conv(e);
        let width = crate::types::TypeWidth::value_width(&e.expr_type()?) as usize;
        if width == 0 {
            return Some(());
        }
        if e.kind() == ExpressionKind::Concatenation {
            for op in e.operands() {
                walk(op, segs, idx)?;
            }
            return Some(());
        }
        if let Some((key, off)) = net_strength_key(e) {
            segs.push(StrengthSeg {
                at: SegAt::Net {
                    key,
                    off: off as usize,
                },
                width,
            });
        } else if !reads_net(e) {
            segs.push(StrengthSeg {
                at: SegAt::Strong,
                width,
            });
        } else if let Some((key, desc, right, ix)) = dynamic_bit_select(e) {
            segs.push(StrengthSeg {
                at: SegAt::Dyn { key, desc, right },
                width: 1,
            });
            idx.push(ix);
        } else {
            return None;
        }
        Some(())
    }
    let (mut segs, mut idx) = (Vec::new(), Vec::new());
    walk(e, &mut segs, &mut idx)?;
    // A lone whole-net or constant-select operand is the plain `'k'` tag's.
    (!segs.is_empty()).then_some((segs, idx))
}

/// `e` as a bit-select `net[i]` of a packed net (one level, any index): the
/// net's key, whether its range descends, its right bound and the index.
fn dynamic_bit_select<'d>(
    e: sv_lang::Expression<'d>,
) -> Option<(u64, bool, i64, sv_lang::Expression<'d>)> {
    if e.kind() != ExpressionKind::ElementSelect {
        return None;
    }
    let base = e.select_value()?;
    if !sv_sim_sim::symid::is_value_name(base.kind()) {
        return None;
    }
    let sym = base.referenced_symbol()?;
    if sym.kind() != SymbolKind::Net {
        return None;
    }
    let ty = base.expr_type().filter(|t| !t.is_unpacked_array())?;
    let width = crate::types::TypeWidth::value_width(&ty);
    let geom = crate::select::geom_of(Some(ty), width);
    if geom.elem_width != 1 {
        return None;
    }
    Some((
        sv_sim_runtime::fmt::strength_key(&sv_sim_sim::symid::SymbolUid::uid(&sym).key_string()),
        geom.descending(),
        geom.right,
        e.selector()?,
    ))
}

/// Whether `e` reads any net.
fn reads_net(e: sv_lang::Expression<'_>) -> bool {
    let mut stack = vec![e.as_sem_node()];
    while let Some(n) = stack.pop() {
        if let Some(x) = n.as_expression()
            && sv_sim_sim::symid::is_value_name(x.kind())
            && x.referenced_symbol()
                .is_some_and(|s| s.kind() == SymbolKind::Net)
        {
            return true;
        }
        stack.extend(n.children());
    }
    false
}

/// `%p` of the fixed-size array `r` (shape `shape`, from dimension `k` on,
/// starting at row `base`): `'{e0, e1, ...}` in declared order (left bound
/// first), nested per dimension, each element a singular `%p` leaf (an
/// unpacked struct element its own pattern).
fn array_pattern<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    r: &crate::arrays::ArrayRef<'ctx>,
    shape: &crate::arrays::ArrayShape<'_>,
    k: usize,
    base: u64,
    text: &mut String,
    leaves: &mut Vec<LoweredValue<'ctx>>,
) -> Result<(), LoweringError> {
    let (left, right) = shape.dims[k];
    let size = (left - right).unsigned_abs() + 1;
    let stride: u64 = shape.dims[k + 1..]
        .iter()
        .map(|(l, r)| (l - r).unsigned_abs() + 1)
        .product();
    let low = left.min(right);
    text.push_str("'{");
    for n in 0..size {
        if n > 0 {
            text.push_str(", ");
        }
        let idx = if left <= right {
            left + n as i64
        } else {
            left - n as i64
        };
        let row = base + (idx - low) as u64 * stride;
        if k + 1 < shape.dims.len() {
            array_pattern(cx, r, shape, k + 1, row, text, leaves)?;
            continue;
        }
        let elem = &shape.elem;
        let at =
            cx.b.build_int_add(r.base, cx.ctx.i64_type().const_int(row, false), "p_row")
                .unwrap();
        let e = crate::arrays::ElemRef {
            backing: r.backing,
            row: at,
            valid: r.valid,
            width: crate::types::TypeWidth::value_width(elem),
            signed: elem.is_signed(),
            default: crate::arrays::default_value(cx, elem),
        };
        let v = crate::arrays::read_element(cx, &e)?;
        if sv_sim_sim::state::storage::is_unpacked_aggregate(elem)
            || crate::collections::coll_of(elem).is_some()
        {
            aggregate_pattern(cx, elem, v, text, leaves)?;
            continue;
        }
        if elem.is_class() {
            text.push_str("%s");
            let h = crate::ops::OpBuilder {
                ctx: cx.ctx,
                b: &cx.b,
            }
            .lane_val(v);
            leaves.push(crate::classes::format_object(cx, *elem, h)?);
            continue;
        }
        if let Some(s) = crate::sysfunc::enum_pattern_text(cx, elem, v)? {
            text.push_str("%s");
            leaves.push(s);
            continue;
        }
        text.push_str("%p");
        leaves.push(if elem.is_string() {
            LoweredValue::Str(crate::strings::from_storage(cx, v))
        } else if elem.is_floating() {
            LoweredValue::Real(crate::real::bits_to_real(cx, v))
        } else {
            LoweredValue::Packed(v)
        });
    }
    text.push('}');
    Ok(())
}

/// `%p` of the stored bits `v` of an unpacked struct/union (or of an array
/// field of one) of type `ty`: its assignment pattern (`'{a:%p, b:'{...}}`,
/// LRM 1800-2023 §21.2.1.7) appended to `text`, with a singular `%p` per
/// leaf whose values -- sliced out of `v` and read back as their own kind
/// of value -- are appended to `leaves`. A union shows its first member.
pub(crate) fn aggregate_pattern<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    ty: &sv_lang::Type<'_>,
    v: PackedValue<'ctx>,
    text: &mut String,
    leaves: &mut Vec<LoweredValue<'ctx>>,
) -> Result<(), LoweringError> {
    use sv_sim_sim::state::storage;
    let op = crate::ops::OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    let shape_err =
        || LoweringError::unsupported_at("an aggregate display argument's shape", &cx.fn_sym);
    let slice = |lo: u64, w: u64, signed: bool| PackedValue {
        signed,
        ..op.part_select4(
            v,
            op.i_n(v.width).const_int(lo, false),
            cx.ctx.bool_type().const_zero(),
            w as u32,
        )
    };
    // A queue, dynamic or associative array field: its handle's pattern.
    if let Some(c) = crate::collections::coll_of(ty) {
        let h = op.lane_val(v);
        let h = if v.width > 64 {
            cx.b.build_int_truncate(h, cx.ctx.i64_type(), "p_coll")
                .unwrap()
        } else {
            cx.b.build_int_z_extend_or_bit_cast(h, cx.ctx.i64_type(), "p_coll")
                .unwrap()
        };
        text.push_str("%s");
        leaves.push(crate::collections::format_handle(cx, &c, h)?);
        return Ok(());
    }
    if ty.is_unpacked_union() && ty.is_tagged_union() {
        return crate::tagged::print_pattern(cx, ty, v, text, leaves);
    }
    if storage::is_unpacked_aggregate(ty) {
        text.push_str("'{");
        let fields: Vec<_> = ty.fields().collect();
        let shown = if ty.is_unpacked_union() {
            &fields[..fields.len().min(1)]
        } else {
            &fields[..]
        };
        for (i, f) in shown.iter().enumerate() {
            if i > 0 {
                text.push_str(", ");
            }
            let (lo, w) = storage::field_slice(ty, f.field_index()).ok_or_else(shape_err)?;
            let fty = f.value_type().ok_or_else(shape_err)?;
            text.push_str(f.name());
            text.push(':');
            aggregate_pattern(cx, &fty, slice(lo, w, fty.is_signed()), text, leaves)?;
        }
        text.push('}');
    } else if ty.is_unpacked_array() {
        let range = ty.fixed_unpacked_array_range();
        let elem = ty.element_type().ok_or_else(shape_err)?;
        let ew = storage::storage_width(&elem).ok_or_else(shape_err)?;
        text.push_str("'{");
        // Declared order, left bound first; the lowest index is stored
        // least significant.
        for k in 0..i64::from(range.width()) {
            if k > 0 {
                text.push_str(", ");
            }
            let idx = if range.left <= range.right {
                i64::from(range.left) + k
            } else {
                i64::from(range.left) - k
            };
            let pos = (idx - i64::from(range.lower())) as u64;
            aggregate_pattern(
                cx,
                &elem,
                slice(pos * ew, ew, elem.is_signed()),
                text,
                leaves,
            )?;
        }
        text.push('}');
    } else if ty.is_class() {
        // A class handle member or element: expanded one level, like a
        // direct operand (`classes::format_object`).
        let h = op.lane_val(v);
        let h =
            cx.b.build_int_z_extend_or_bit_cast(h, cx.ctx.i64_type(), "p_obj")
                .unwrap();
        text.push_str("%s");
        leaves.push(crate::classes::format_object(cx, *ty, h)?);
    } else if ty.is_struct() && !ty.is_unpacked_struct() {
        // A packed struct: named elements over its equivalent vector
        // (LRM 21.2.1.6); a field may itself be an enum or a packed struct.
        text.push_str("'{");
        for (i, f) in ty.fields().enumerate() {
            if i > 0 {
                text.push_str(", ");
            }
            let (lo, w) = storage::field_slice(ty, f.field_index()).ok_or_else(shape_err)?;
            let fty = f.value_type().ok_or_else(shape_err)?;
            text.push_str(f.name());
            text.push(':');
            aggregate_pattern(cx, &fty, slice(lo, w, fty.is_signed()), text, leaves)?;
        }
        text.push('}');
    } else if let Some(s) = crate::sysfunc::enum_pattern_text(cx, ty, v)? {
        text.push_str("%s");
        leaves.push(s);
    } else {
        text.push_str("%p");
        leaves.push(if ty.is_floating() {
            LoweredValue::Real(crate::real::bits_to_real(cx, v))
        } else if ty.is_string() {
            LoweredValue::Str(crate::strings::from_storage(cx, v))
        } else {
            LoweredValue::Packed(v)
        });
    }
    Ok(())
}

/// The `library.cell` binding of the module instance a system call's scope
/// belongs to, for `%l` (LRM 1800-2023 33.7, 21.2.1.5): the library its
/// definition was compiled into (`work` unless a library map says otherwise,
/// 33.3.1) and its declaring definition's name, else the top segment of the
/// hierarchical path.
fn library_cell(scope_sym: &sv_lang::Symbol<'_>, scope: &str) -> String {
    let cell = scope_sym
        .declaring_definition()
        .map(|d| d.name().to_string())
        .unwrap_or_else(|| scope.split('.').next().unwrap_or(scope).to_string());
    let lib = scope_sym
        .declaring_definition()
        .and_then(|d| d.source_library())
        .or_else(|| scope_sym.source_library())
        .map_or_else(|| "work".to_string(), |l| l.name());
    format!("{lib}.{cell}")
}

/// A `$display`-family format argument of `call`: a string literal is
/// checked at compile time (an unknown specifier is a lowering error, not a
/// mid-simulation failure) and gets its `%m` replaced by the call's
/// hierarchical scope and its `%l` by the library binding (LRM 1800-2023
/// §21.2.1.5); a string value is used as is ([`lower_format_expr`]).
pub(crate) fn lower_display_format<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    fmt: sv_lang::Expression<'_>,
    call: sv_lang::Expression<'_>,
) -> Result<PointerValue<'ctx>, LoweringError> {
    let mut lit = fmt;
    while lit.kind() == ExpressionKind::Conversion {
        match lit.conversion_operand() {
            Some(inner) => lit = inner,
            None => break,
        }
    }
    let Some(text) = (lit.kind() == ExpressionKind::StringLiteral)
        .then(|| lit.string_literal_value())
        .flatten()
    else {
        return lower_format_expr(cx, fmt);
    };
    let scope_sym = call.system_call_scope().unwrap_or(cx.fn_sym);
    let (time_unit, _) = crate::timescale::unit_and_precision(&scope_sym);
    let shown = sv_sim_sim::process::cfg::shown_path(&scope_sym);
    let text = sv_sim_runtime::fmt::tag_time_unit(
        &sv_sim_runtime::fmt::substitute_scope(&text, &shown, &library_cell(&scope_sym, &shown)),
        time_unit,
    );
    sv_sim_runtime::fmt::check_format(&text).map_err(|err| {
        LoweringError::unsupported_at(&format!("format string {text:?}: {err:?}"), &cx.fn_sym)
    })?;
    Ok(build_c_string_global(
        cx.ctx,
        cx.module,
        &text,
        "display_fmt",
    ))
}

/// Builds a private, constant, NUL-terminated LLVM global holding `s`'s
/// UTF-8 bytes -- the frozen ABI's `SvRtDisplayFn`-family shape takes a bare
/// `*const c_char`, not a `(ptr, len)` pair.
pub(crate) fn build_c_string_global<'ctx>(
    ctx: &'ctx Context,
    module: &Module<'ctx>,
    s: &str,
    name: &str,
) -> PointerValue<'ctx> {
    let mut bytes = s.as_bytes().to_vec();
    bytes.push(0);
    let i8_ty = ctx.i8_type();
    let const_bytes: Vec<IntValue<'ctx>> = bytes
        .iter()
        .map(|byte| i8_ty.const_int(u64::from(*byte), false))
        .collect();
    let arr = i8_ty.const_array(&const_bytes);
    let global = module.add_global(arr.get_type(), None, name);
    global.set_initializer(&arr);
    global.set_constant(true);
    global.set_linkage(Linkage::Private);
    global.as_pointer_value()
}

/// Fetches (or, on first use in this `Module`, declares) the `extern "C"`
/// shim function for `family` -- `void sv_rt_<family>(const char *fmt,
/// const RtArg *args, uint32_t nargs)`, matching `SvRtDisplayFn`'s C
/// signature (`rtarg.rs`) exactly. A caller lowering several `$display`-
/// family statements into one shared `Module` must not re-declare the same
/// symbol twice -- `Module::get_function` first, matching
/// `process_lower.rs::fetch_or_declare_sys_call_fns`'s identical
/// fetch-or-declare discipline for the same symbol family.
pub(crate) fn fetch_or_declare_display_family_fn<'ctx>(
    ctx: &'ctx Context,
    module: &Module<'ctx>,
    family: DisplayFamily,
) -> FunctionValue<'ctx> {
    let symbol = display_family_symbol(family);
    module.get_function(symbol).unwrap_or_else(|| {
        let ptr_ty = ctx.ptr_type(AddressSpace::default());
        let i32_ty = ctx.i32_type();
        let void_ty = ctx.void_type();
        let fn_ty = void_ty.fn_type(&[ptr_ty.into(), ptr_ty.into(), i32_ty.into()], false);
        module.add_function(symbol, fn_ty, Some(Linkage::External))
    })
}

/// The Task 30 entry point: `func.rs`'s `StatementKind::ExpressionStatement`
/// arm routes a recognized `$display`-family `Call` expression here
/// (`classify_display_family(sub.known_name_id())` returned `Some`), BEFORE
/// ever reaching `expr.rs`'s generic `Call` arm.
///
/// Reads `call`'s operands via `Expression::operands()` (`call.operands()`
/// -- the same accessor `func.rs::lower_task_call` already uses for an
/// ordinary task/function call's argument list); operand 0 is the format
/// expression (CG-046), every remaining operand is an ordinary data
/// argument lowered through `lower_expr` and marshaled into a private,
/// stack-allocated `RtArg` array (CG-044) before one `call` to the family's
/// frozen ABI symbol (CG-043's "a call instruction ... never inline
/// logic").
pub fn lower_display_family_call<'ctx, 'd, 'm>(
    cx: &LowerCtx<'ctx, 'd, 'm>,
    call: sv_lang::Expression<'d>,
    family: DisplayFamily,
) -> Result<(), LoweringError> {
    // Review fix (r1), blocking finding on B-runtime Task 12: bare `$monitor`
    // is rejected here, loudly, BEFORE any IR (not even the format-string
    // global) is emitted. `sv_sim_runtime::monitor::sv_rt_monitor`'s real,
    // exported `extern "C"` symbol now takes FOUR arguments (`id:
    // MonitorId, fmt, args, nargs`) -- `id` is a stable, per-call-site
    // identity RT-036's dirty-tracking dedup needs (see that module's own
    // doc comment) -- but no codegen infrastructure anywhere in this crate
    // mints a `MonitorId` per call site yet (the same gap `$dumpvars`/
    // `$fmonitor` already have -- `sv_sim_runtime::monitor`'s own top-level
    // doc comment, "Deviation: `$fmonitor`'s ABI"). `fetch_or_declare_
    // display_family_fn`/the call-emission code below this guard build the
    // OLD, frozen-at-wave-A three-argument `(fmt, args, nargs)` shape for
    // every `DisplayFamily` member alike; emitting that shape against
    // `sv_rt_monitor`'s new four-argument signature would silently corrupt
    // every argument the runtime reads (the callee would read `id` from
    // bits the caller placed as `fmt`, `fmt` from what the caller placed as
    // `args`, and so on) the moment a `function automatic` body calling
    // `$monitor` is compiled and JIT/AOT-executed through this pipeline --
    // exactly the class of bug this crate's correctness posture forbids.
    // Rejecting it here (rather than reverting `sv_rt_monitor`'s own ABI, or
    // silently building the mismatched call) keeps both sides of the ABI
    // boundary self-consistent: a named, loud `LoweringError` today, in
    // place of a mismatched call, until a monotonic, per-call-site
    // `MonitorId`-minting scheme (scoped correctly across
    // `session.rs`'s rayon-parallel per-`InstanceBody` workers, whose
    // separately-built `Module`s are later merged -- see that file's own
    // module doc comment) actually exists. `$display`/`$write`/`$strobe`
    // are unaffected: `sv_rt_display`/`sv_rt_write`/`sv_rt_strobe` all kept
    // their original three-argument shape (`sv_sim_runtime::monitor`'s own
    // "`sv_rt_strobe`/`sv_rt_fstrobe` keep their existing bare signatures --
    // no id needed" note), so only `DisplayFamily::Monitor` is rejected.
    if family == DisplayFamily::Monitor {
        return Err(LoweringError::unsupported_at(
            "bare $monitor cannot be lowered by this (func.rs leaf-function) \
             pipeline yet: sv_rt_monitor's real, exported ABI now takes a \
             leading MonitorId argument (B-runtime Task 12, RT-036/RT-047), \
             but no codegen infrastructure exists anywhere in this crate to \
             mint a stable, per-call-site MonitorId -- emitting the old \
             three-argument (fmt, args, nargs) call this function builds for \
             every other DisplayFamily member would silently corrupt every \
             argument sv_rt_monitor reads, rather than a mismatched call. \
             $display/$write/$strobe are unaffected (their runtime symbols \
             kept their original three-argument shape)",
            &cx.fn_sym,
        ));
    }
    let operands = call.operands();
    let (fmt_ptr, arg_values) = display_format_and_values(cx, &operands, call)?;

    let rt_fn = fetch_or_declare_display_family_fn(cx.ctx, cx.module, family);
    let rtarg_ty = rtarg_llvm_type(cx.ctx);
    let (args_ptr, nargs_const) = build_rtarg_array(cx, rtarg_ty, arg_values)?;
    cx.b.build_call(
        rt_fn,
        &[fmt_ptr.into(), args_ptr.into(), nargs_const.into()],
        "rt_display_call",
    )
    .unwrap();
    Ok(())
}

/// Marshals `arg_values` into a private, per-call, 16-byte-aligned
/// `alloca`'d `RtArg` array (CG-044) and returns `(args_ptr, nargs)` ready to
/// splice straight into a `build_call`'s argument list -- the ONE shared
/// implementation [`lower_display_family_call`] and
/// [`lower_fdisplay_family_call`] both use (this project's own "duplicate
/// pure-function eval diverges" lesson, applied to this marshaling step
/// rather than duplicating it a second time within this same file).
/// `args_ptr` is `ptr_ty.const_null()` when `arg_values` is empty -- the
/// frozen ABI's own "no arguments" convention every `$display`-family/
/// `$fwrite`-family symbol shares.
pub(crate) fn build_rtarg_array<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    rtarg_ty: StructType<'ctx>,
    arg_values: Vec<LoweredValue<'ctx>>,
) -> Result<(PointerValue<'ctx>, IntValue<'ctx>), LoweringError> {
    let ptr_ty = cx.ctx.ptr_type(AddressSpace::default());
    let n = arg_values.len() as u32;
    let args_ptr = if n == 0 {
        ptr_ty.const_null()
    } else {
        let arr_ty = rtarg_ty.array_type(n);
        let arr_ptr = crate::types::entry_alloca_in(&cx.b, arr_ty, "rtargs");
        // Force real 16-byte alignment: `build_alloca` sizes/aligns off
        // this `Module`'s own (unset, generic) `DataLayout`, which gives
        // `i128` only an 8-byte ABI alignment there, not the 16 bytes
        // `sv_sim_runtime::rtarg::RtArg`'s own `align_of::<RtArg>() == 16`
        // assertion requires on this project's real x86_64 target -- see
        // `process_lower.rs`'s identical note on this exact issue.
        if let Some(instr) = arr_ptr.as_instruction_value() {
            instr
                .set_alignment(16)
                .expect("alloca instruction accepts an explicit alignment");
        }
        let i32_ty = cx.ctx.i32_type();
        for (i, val) in arg_values.into_iter().enumerate() {
            // SAFETY: `arr_ptr` is a private, per-call `alloca` this
            // function itself just created above; `i` is in-bounds by
            // construction (`arr_ty`'s element count is exactly
            // `arg_exprs.len()`, and this loop runs exactly that many
            // times).
            let elem_ptr = unsafe {
                cx.b.build_gep(
                    arr_ty,
                    arr_ptr,
                    &[
                        i32_ty.const_int(0, false),
                        i32_ty.const_int(i as u64, false),
                    ],
                    "rtarg_elem",
                )
                .unwrap()
            };
            push_rtarg_for_value(cx, rtarg_ty, elem_ptr, val)?;
        }
        arr_ptr
    };
    let nargs_const = cx.ctx.i32_type().const_int(u64::from(n), false);
    Ok((args_ptr, nargs_const))
}

/// B-runtime Task 4 (`docs/superpowers/plans/2026-09-27-wave-B-runtime.md`;
/// ledger RT-070, RT-162): the two `$dumpfile`/`$dumpvars`-family members
/// this task gives a `systask.rs` recognizer arm to. **Deliberately only
/// these two, not the other five** (`$dumpvars`/`$dumpon`/`$dumpoff`/
/// `$dumpall`/`$dumplimit`) -- see `sv_sim_runtime::fst::dump_control`'s own
/// module doc for the full reasoning: those five route through a
/// `RuntimeHost` nothing in `sv_sim_bin::run_design` installs today, so
/// giving them a recognizer arm (and hence a real call site in a compiled
/// kernel) would make that kernel `std::process::abort()` on its very first
/// call, which is strictly worse than the loud, existing "unsupported
/// system call" `LoweringError` it gets today by staying unrecognized.
/// `$dumpfile`/`$dumpflush` carry no such risk (their production bodies,
/// `sv_sim_runtime::fst::dump_control::real_sv_rt_dumpfile`/
/// `real_sv_rt_dumpflush`, are `RuntimeHost`-free), so they alone are wired
/// all the way through here and in `sv-sim-bin::run.rs`'s JIT mapping.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum DumpControlCall {
    DumpFile,
    DumpFlush,
}

/// Maps a `KnownSystemName` to its [`DumpControlCall`], or `None` for
/// anything else -- confirmed against the vendored `sv-lang` 0.1.9
/// `system_subroutine_kinds.rs` source (this crate's own established
/// cross-check discipline, `classify_display_family`'s own doc comment)
/// before writing this match: `DumpFile` (190), `DumpFlush` (195).
pub fn classify_dump_control_call(name: KnownSystemName) -> Option<DumpControlCall> {
    use KnownSystemName::{DumpFile, DumpFlush};
    match name {
        DumpFile => Some(DumpControlCall::DumpFile),
        DumpFlush => Some(DumpControlCall::DumpFlush),
        _ => None,
    }
}

/// Fetches (or, on first use in this `Module`, declares) the `extern "C"`
/// shim function for a dump-control call -- `void sv_rt_dumpfile(const char
/// *path, const char *src)` or `void sv_rt_dumpflush(void)`, matching
/// `sv_sim_runtime::fst::dump_control`'s real production symbols exactly.
/// Mirrors [`fetch_or_declare_display_family_fn`]'s identical
/// fetch-or-declare discipline for the same reason (a caller lowering
/// several dump-control statements into one shared `Module` must not
/// re-declare the same symbol twice).
fn fetch_or_declare_dump_control_fn<'ctx>(
    ctx: &'ctx Context,
    module: &Module<'ctx>,
    symbol: &str,
    has_path_arg: bool,
) -> FunctionValue<'ctx> {
    module.get_function(symbol).unwrap_or_else(|| {
        let void_ty = ctx.void_type();
        let fn_ty = if has_path_arg {
            let ptr_ty = ctx.ptr_type(AddressSpace::default());
            void_ty.fn_type(&[ptr_ty.into(), ptr_ty.into()], false)
        } else {
            void_ty.fn_type(&[], false)
        };
        module.add_function(symbol, fn_ty, Some(Linkage::External))
    })
}

/// The Task 4 entry point for `$dumpfile`/`$dumpflush`: `func.rs`'s
/// `StatementKind::ExpressionStatement` arm routes a recognized dump-control
/// `Call` expression here (`classify_dump_control_call(sub.known_name_id())`
/// returned `Some`), exactly like [`lower_display_family_call`]'s own
/// routing point.
///
/// `$dumpfile`'s single operand is forwarded through [`lower_format_expr`]
/// unchanged -- reused verbatim (never re-derived) since it already
/// implements exactly the needed "constant string-literal argument, named
/// loud error otherwise" contract (CG-046's own literal-only scope note
/// applies here identically: a dynamic, non-literal `$dumpfile` path is out
/// of this task's scope). `$dumpflush` takes no operand at all.
pub fn lower_dump_control_call<'ctx, 'd, 'm>(
    cx: &LowerCtx<'ctx, 'd, 'm>,
    call: sv_lang::Expression<'d>,
    which: DumpControlCall,
) -> Result<(), LoweringError> {
    match which {
        DumpControlCall::DumpFile => {
            let operands = call.operands();
            // The file name is optional (LRM 21.7.1.1): "dump.vcd" is the
            // dumper's default.
            let Some(path_expr) = operands.first() else {
                return Ok(());
            };
            let path_ptr = lower_format_expr(cx, *path_expr)?;
            let rt_fn =
                fetch_or_declare_dump_control_fn(cx.ctx, cx.module, SV_RT_DUMPFILE_SYMBOL, true);
            // The argument's source text rides along for `$version`
            // (LRM 21.7.2.3: a variable or expression appears unevaluated).
            let src_text = sv_sim_sim::process::cfg::source_text_range(path_expr.source_range())
                .unwrap_or_default();
            let src_ptr =
                cx.b.build_global_string_ptr(&src_text, "dumpfile_src")
                    .unwrap()
                    .as_pointer_value();
            cx.b.build_call(
                rt_fn,
                &[path_ptr.into(), src_ptr.into()],
                "rt_dumpfile_call",
            )
            .unwrap();
        }
        DumpControlCall::DumpFlush => {
            let rt_fn =
                fetch_or_declare_dump_control_fn(cx.ctx, cx.module, SV_RT_DUMPFLUSH_SYMBOL, false);
            cx.b.build_call(rt_fn, &[], "rt_dumpflush_call").unwrap();
        }
    }
    Ok(())
}

/// B-runtime Task 7 (RT-050 open/close/flush clause, RT-051, RT-052, RT-053,
/// RT-065): the two void-returning members of the file-I/O family this task
/// gives a `systask.rs`/`func.rs` recognizer arm -- `$fclose`/`$fflush`,
/// mirroring [`DumpControlCall`]'s own "void call, statement position" shape
/// exactly. This covers the leaf `function`/`task`-body pipeline
/// (`func.rs`); `process_lower.rs`'s own, separately-maintained segment
/// pipeline (the one `sv_sim_bin::run_design`'s real `initial`/`always`
/// process bodies actually go through -- see that file's own module doc for
/// why the two pipelines have historically stayed independent
/// implementations rather than sharing one) gets its own matching arm.
/// (`$fopen` itself is a system FUNCTION whose return value feeds ordinary
/// SV expression evaluation, so it is dispatched from `expr.rs`'s `Call` arm
/// instead, alongside `$random`/`$time` -- see `expr::lower_fopen_call`'s
/// own doc comment for why.)
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum FileIoVoidCall {
    FClose,
    FFlush,
}

/// Maps a `KnownSystemName` to its [`FileIoVoidCall`], or `None` for
/// anything else -- confirmed against the vendored `sv-lang` 0.1.9
/// `system_subroutine_kinds.rs` source (this crate's own established
/// cross-check discipline, `classify_display_family`'s own doc comment)
/// before writing this match: `FClose` (70), `FFlush` (76).
pub fn classify_file_io_void_call(name: KnownSystemName) -> Option<FileIoVoidCall> {
    use KnownSystemName::{FClose, FFlush};
    match name {
        FClose => Some(FileIoVoidCall::FClose),
        FFlush => Some(FileIoVoidCall::FFlush),
        _ => None,
    }
}

/// Fetches (or, on first use in this `Module`, declares) the `extern "C"`
/// shim function for `$fclose`/`$fflush` -- `void sv_rt_fclose(int32_t fd)`/
/// `void sv_rt_fflush(int32_t fd)`, matching `sv_sim_runtime::file_io`'s real
/// production symbols exactly. Mirrors [`fetch_or_declare_dump_control_fn`]'s
/// identical fetch-or-declare discipline just above.
fn fetch_or_declare_file_io_void_fn<'ctx>(
    ctx: &'ctx Context,
    module: &Module<'ctx>,
    symbol: &str,
) -> FunctionValue<'ctx> {
    module.get_function(symbol).unwrap_or_else(|| {
        let void_ty = ctx.void_type();
        let i32_ty = ctx.i32_type();
        let fn_ty = void_ty.fn_type(&[i32_ty.into()], false);
        module.add_function(symbol, fn_ty, Some(Linkage::External))
    })
}

/// The Task 7 entry point for `$fclose`/`$fflush` in the leaf `function`/
/// `task`-body pipeline: `func.rs`'s `StatementKind::ExpressionStatement`
/// arm routes a recognized file-I/O void call here, exactly like
/// [`lower_dump_control_call`]'s own routing point. Unlike `$dumpfile`'s
/// path argument (a compile-time string literal), `$fclose`/`$fflush`'s
/// MCD-bitmask argument is a genuine runtime value by construction -- an MCD
/// only ever exists as `$fopen`'s own runtime return value (RT-051) -- so
/// this lowers it through the ordinary dynamic `lower_expr` path (mirroring
/// `expr.rs`'s own `$urandom_range` `hi`/`lo` handling), never
/// `constant_value()`. `$fflush()`'s own zero-argument form (LRM: "flush
/// every open file") defaults to the constant `0`, matching `sv_rt_fflush`'s
/// own documented "fd == 0 flushes every open file" convention; `$fclose`
/// has no such zero-argument form and is a named error without one.
pub fn lower_file_io_void_call<'ctx, 'd, 'm>(
    cx: &LowerCtx<'ctx, 'd, 'm>,
    call: sv_lang::Expression<'d>,
    which: FileIoVoidCall,
) -> Result<(), LoweringError> {
    let operands = call.operands();
    let fd_i32 = match operands.first() {
        Some(fd_expr) => {
            let pv = lower_expr(cx, *fd_expr)?.into_packed(
                "$fclose/$fflush's fd argument must be an integral value",
                &cx.fn_sym,
            )?;
            let op = crate::ops::OpBuilder {
                ctx: cx.ctx,
                b: &cx.b,
            };
            crate::expr::packed_to_plain_i32(&op, pv)
        }
        None if which == FileIoVoidCall::FFlush => cx.ctx.i32_type().const_zero(),
        None => {
            return Err(LoweringError::unsupported_at(
                "$fclose requires an fd argument",
                &cx.fn_sym,
            ));
        }
    };
    let symbol = match which {
        FileIoVoidCall::FClose => SV_RT_FCLOSE_SYMBOL,
        FileIoVoidCall::FFlush => SV_RT_FFLUSH_SYMBOL,
    };
    let rt_fn = fetch_or_declare_file_io_void_fn(cx.ctx, cx.module, symbol);
    cx.b.build_call(rt_fn, &[fd_i32.into()], "rt_file_io_void_call")
        .unwrap();
    Ok(())
}

/// B-runtime Task 8 (`docs/superpowers/plans/2026-09-27-wave-B-runtime.md`;
/// ledger RT-022, RT-049, RT-054, RT-055, RT-056, RT-057): `$fwrite`/
/// `$fdisplay`/`$fmonitor`/`$fstrobe` -- the file-I/O siblings of
/// [`DisplayFamily`], mirroring its own "one frozen ABI symbol per family,
/// deliberately coarse across radix suffixes" shape exactly, with one
/// structural difference: every member's frozen ABI signature (`crate::
/// file_io::write`'s doc comment) prepends an `fd: i32` MCD-bitmask argument
/// before the shared `(fmt, args, nargs)` shape -- a genuine runtime value
/// (an MCD only ever exists as `$fopen`'s own runtime return value, RT-051),
/// never a compile-time constant, so it is lowered through the ordinary
/// dynamic `lower_expr` path exactly like [`lower_file_io_void_call`]'s own
/// `fd` argument.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum FDisplayFamily {
    FWrite,
    FDisplay,
    FStrobe,
    FMonitor,
}

/// Maps a `KnownSystemName` to its [`FDisplayFamily`], or `None` for
/// anything else -- confirmed against the vendored `sv-lang` 0.1.9
/// `system_subroutine_kinds.rs` source (this crate's own established
/// cross-check discipline, `classify_display_family`'s own doc comment)
/// before writing this match: `FDisplay`/`FDisplayB`/`FDisplayO`/
/// `FDisplayH` (152-155), `FWrite`/`FWriteB`/`FWriteO`/`FWriteH` (156-159),
/// `FStrobe`/`FStrobeB`/`FStrobeO`/`FStrobeH` (160-163), `FMonitor`/
/// `FMonitorB`/`FMonitorO`/`FMonitorH` (164-167).
pub fn classify_fdisplay_family(name: KnownSystemName) -> Option<FDisplayFamily> {
    use KnownSystemName::{
        FDisplay, FDisplayB, FDisplayH, FDisplayO, FMonitor, FMonitorB, FMonitorH, FMonitorO,
        FStrobe, FStrobeB, FStrobeH, FStrobeO, FWrite, FWriteB, FWriteH, FWriteO,
    };
    match name {
        FWrite | FWriteB | FWriteO | FWriteH => Some(FDisplayFamily::FWrite),
        FDisplay | FDisplayB | FDisplayO | FDisplayH => Some(FDisplayFamily::FDisplay),
        FStrobe | FStrobeB | FStrobeO | FStrobeH => Some(FDisplayFamily::FStrobe),
        FMonitor | FMonitorB | FMonitorO | FMonitorH => Some(FDisplayFamily::FMonitor),
        _ => None,
    }
}

/// The frozen ABI's own symbol constant for an [`FDisplayFamily`] member --
/// re-exported verbatim (never re-typed as a local string literal), mirrors
/// [`display_family_symbol`]'s identical role.
pub fn fdisplay_family_symbol(f: FDisplayFamily) -> &'static str {
    match f {
        FDisplayFamily::FWrite => SV_RT_FWRITE_SYMBOL,
        FDisplayFamily::FDisplay => SV_RT_FDISPLAY_SYMBOL,
        FDisplayFamily::FStrobe => SV_RT_FSTROBE_SYMBOL,
        FDisplayFamily::FMonitor => SV_RT_FMONITOR_SYMBOL,
    }
}

/// Fetches (or, on first use in this `Module`, declares) the `extern "C"`
/// shim function for `family` -- `void sv_rt_f<family>(int32_t fd, const
/// char *fmt, const RtArg *args, uint32_t nargs)`, matching `crate::
/// file_io::write`'s real production symbols exactly. Mirrors
/// [`fetch_or_declare_display_family_fn`]'s identical fetch-or-declare
/// discipline for the same reason.
fn fetch_or_declare_fdisplay_family_fn<'ctx>(
    ctx: &'ctx Context,
    module: &Module<'ctx>,
    family: FDisplayFamily,
) -> FunctionValue<'ctx> {
    let symbol = fdisplay_family_symbol(family);
    module.get_function(symbol).unwrap_or_else(|| {
        let i32_ty = ctx.i32_type();
        let ptr_ty = ctx.ptr_type(AddressSpace::default());
        let void_ty = ctx.void_type();
        let fn_ty = void_ty.fn_type(
            &[i32_ty.into(), ptr_ty.into(), ptr_ty.into(), i32_ty.into()],
            false,
        );
        module.add_function(symbol, fn_ty, Some(Linkage::External))
    })
}

/// The Task 8 entry point: `func.rs`'s `StatementKind::ExpressionStatement`
/// arm routes a recognized `$fwrite`-family `Call` expression here
/// (`classify_fdisplay_family(sub.known_name_id())` returned `Some`), BEFORE
/// ever reaching `expr.rs`'s generic `Call` arm -- exactly like
/// [`lower_display_family_call`]'s own routing point.
///
/// Operand 0 is the MCD-bitmask `fd` expression (a genuine runtime value,
/// [`lower_file_io_void_call`]'s own dynamic-`lower_expr` treatment); operand
/// 1 is the format expression (CG-046); every remaining operand is an
/// ordinary data argument, marshaled exactly like
/// [`lower_display_family_call`]'s own (shared via [`build_rtarg_array`],
/// never re-derived a second time).
pub fn lower_fdisplay_family_call<'ctx, 'd, 'm>(
    cx: &LowerCtx<'ctx, 'd, 'm>,
    call: sv_lang::Expression<'d>,
    family: FDisplayFamily,
) -> Result<(), LoweringError> {
    let operands = call.operands();
    let (fd_expr, rest) = operands.split_first().ok_or_else(|| {
        LoweringError::unsupported_at("$fwrite-family call has no fd argument", &cx.fn_sym)
    })?;
    let fd_pv = lower_expr(cx, *fd_expr)?.into_packed(
        "$fwrite-family's fd argument must be an integral value",
        &cx.fn_sym,
    )?;
    let op = crate::ops::OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    let fd_i32 = crate::expr::packed_to_plain_i32(&op, fd_pv);

    let (fmt_ptr, arg_values) = display_format_and_values(cx, rest, call)?;

    let rt_fn = fetch_or_declare_fdisplay_family_fn(cx.ctx, cx.module, family);
    let rtarg_ty = rtarg_llvm_type(cx.ctx);
    let (args_ptr, nargs_const) = build_rtarg_array(cx, rtarg_ty, arg_values)?;
    cx.b.build_call(
        rt_fn,
        &[
            fd_i32.into(),
            fmt_ptr.into(),
            args_ptr.into(),
            nargs_const.into(),
        ],
        "rt_fdisplay_call",
    )
    .unwrap();
    Ok(())
}

/// SD-B / T25 (`docs/superpowers/plans/2026-10-03-sdf.md`): the real
/// `$sdf_annotate(sdf_file [, module_instance [, config_file [, log_file
/// [, mtm_spec [, scale_factors [, scale_type]]]]]])` call (IEEE 1800-2023
/// §32.9, Syntax 32-1) -- it replaces B-runtime Task 16's (RT-166)
/// hard-error dispatcher. ONE lowering shared by both pipelines: `func.rs`'s
/// `StatementKind::ExpressionStatement` arm (the leaf-function pipeline) and
/// `process_lower.rs`'s `KnownSystemName::SdfAnnotate` arm (the CFG-segment
/// pipeline) both run on the same [`LowerCtx`], so unlike `$display` there is
/// no reason to maintain two copies.
///
/// Emits `void sv_rt_sdf_annotate(const char *file, const char *scope, const
/// char *config, const char *log, const char *mtm, const char *scale_factors,
/// const char *scale_type)` (`sv_sim_runtime::sdf_annotate`). The pointers are
/// in Syntax 32-1 order; an omitted option is a null pointer, and `scope` is
/// never null: LRM 32.9 makes an omitted `module_instance` "the module
/// containing the call", so that instance's hierarchical path is baked in
/// here, at compile time, rather than recovered by the runtime (which has no
/// notion of the calling process's scope). A `module_instance` is an
/// instance symbol (`ArbitrarySymbol`, as `$dumpvars`' scope operands are); its
/// path -- including an array element's `m.ua[1]` -- is baked the same way.
///
/// The string operands (`sdf_file`, `config_file`, ...) are LRM 32.9 "string
/// literal, string data type, or an expression that evaluates to a string",
/// the same shape [`lower_format_expr`] accepts plus an integral value
/// (an `integral` character string, LRM 6.16), converted by `strings::
/// to_string`. A string value's C pointer is interned by the string runtime
/// and stays valid for the process lifetime, so the runtime may keep it.
/// A real operand is a named `LoweringError`.
///
/// Only TRAILING operands can be omitted: slang rejects an empty argument in
/// the middle of this call's argument list (it makes the call an `Invalid`
/// statement), so `$sdf_annotate("f", , "cfg")` never reaches this function;
/// an `EmptyArgument` that does is treated as absent all the same. Zero
/// operands, or more than seven, is a named `LoweringError` (slang diagnoses
/// the over-long call itself in normal compilation; this keeps the contract
/// loud for any path that reaches here anyway).
/// One lowered `$sdf_annotate` call, as `sv-sim build-aot` needs it: the seven arguments of
/// `sv_rt_sdf_annotate` when every one is a literal.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SdfCallSite {
    /// `sdf_file`; `None` when it is not a string literal.
    pub file: Option<String>,
    /// The hierarchical path of the annotation scope (always known at lowering).
    pub scope: String,
    /// `config_file`, `log_file`, `mtm_spec`, `scale_factors`, `scale_type`: `Some(None)` when
    /// omitted, `Some(Some(text))` for a literal, `None` for anything else.
    pub options: [Option<Option<String>>; 5],
}

thread_local! {
    static SDF_SITES: std::cell::RefCell<Vec<SdfCallSite>> =
        const { std::cell::RefCell::new(Vec::new()) };
}

fn record_sdf_site(
    file: Option<Option<String>>,
    scope: String,
    options: [Option<Option<String>>; 5],
) {
    let file = file.flatten();
    SDF_SITES.with(|s| {
        s.borrow_mut().push(SdfCallSite {
            file,
            scope,
            options,
        });
    });
}

/// Forgets the call sites lowered so far (a build starts with none).
pub fn clear_sdf_sites() {
    SDF_SITES.with(|s| s.borrow_mut().clear());
}

/// The `$sdf_annotate` call sites lowered since [`clear_sdf_sites`], in lowering order.
pub fn take_sdf_sites() -> Vec<SdfCallSite> {
    SDF_SITES.with(|s| std::mem::take(&mut *s.borrow_mut()))
}

pub(crate) fn lower_sdf_annotate_call<'ctx, 'd, 'm>(
    cx: &LowerCtx<'ctx, 'd, 'm>,
    call: sv_lang::Expression<'d>,
) -> Result<(), LoweringError> {
    let operands = call.operands();
    if operands.is_empty() || operands.len() > 7 {
        return Err(LoweringError::unsupported_at(
            &format!(
                "$sdf_annotate takes 1 to 7 arguments (sdf_file[, module_instance[, config_file\
                 [, log_file[, mtm_spec[, scale_factors[, scale_type]]]]]]), got {}",
                operands.len()
            ),
            &cx.fn_sym,
        ));
    }
    let present = |k: usize| {
        operands
            .get(k)
            .copied()
            .filter(|a| a.kind() != ExpressionKind::EmptyArgument)
    };
    let ptr_ty = cx.ctx.ptr_type(AddressSpace::default());
    let null = ptr_ty.const_null();
    // The string operand `k` as a C-string pointer, or null when omitted.
    let string_arg = |k: usize, what: &str| -> Result<PointerValue<'ctx>, LoweringError> {
        let Some(mut arg) = present(k) else {
            return Ok(null);
        };
        while arg.kind() == ExpressionKind::Conversion {
            arg = arg.conversion_operand().ok_or_else(|| {
                LoweringError::unsupported_at(
                    &format!("$sdf_annotate {what} argument: conversion missing operand"),
                    &cx.fn_sym,
                )
            })?;
        }
        if arg.kind() == ExpressionKind::StringLiteral {
            let text = arg.string_literal_value().ok_or_else(|| {
                LoweringError::unsupported_at(
                    &format!("$sdf_annotate {what} argument: string literal has no text"),
                    &cx.fn_sym,
                )
            })?;
            return Ok(build_c_string_global(
                cx.ctx,
                cx.module,
                &text,
                "sdf_annotate_arg",
            ));
        }
        let ty = arg.expr_type();
        if !ty
            .as_ref()
            .is_some_and(|t| t.is_string() || t.is_integral())
        {
            return Err(LoweringError::unsupported_at(
                &format!(
                    "$sdf_annotate {what} argument must be a string literal, a string, or an \
                     integral character string"
                ),
                &cx.fn_sym,
            ));
        }
        let s = crate::strings::to_string(cx, lower_expr(cx, arg)?)?;
        Ok(crate::strings::c_str(cx, s))
    };
    let file = string_arg(0, "sdf_file")?;
    // What a built image needs of this call site: its arguments when all are literals.
    let literal = |k: usize| -> Option<Option<String>> {
        let Some(mut arg) = present(k) else {
            return Some(None);
        };
        while arg.kind() == ExpressionKind::Conversion {
            arg = arg.conversion_operand()?;
        }
        (arg.kind() == ExpressionKind::StringLiteral)
            .then(|| arg.string_literal_value())
            .flatten()
            .map(Some)
    };
    let scope = match present(1) {
        Some(inst) => {
            let sym = inst
                .arbitrary_symbol()
                .or_else(|| inst.referenced_symbol())
                .filter(|s| s.kind() == SymbolKind::Instance)
                .ok_or_else(|| {
                    LoweringError::unsupported_at(
                        "$sdf_annotate module_instance argument must name a module instance",
                        &cx.fn_sym,
                    )
                })?;
            sv_sim_sim::process::cfg::shown_path(&sym)
        }
        None => {
            // The instance containing the call: the nearest enclosing
            // `InstanceBody` of the call's scope.
            let mut scope = call.system_call_scope().unwrap_or(cx.fn_sym);
            while scope.kind() != SymbolKind::InstanceBody {
                match scope.parent() {
                    Some(p) => scope = p,
                    None => {
                        return Err(LoweringError::unsupported_at(
                            "$sdf_annotate outside any module instance has no default scope",
                            &cx.fn_sym,
                        ));
                    }
                }
            }
            sv_sim_sim::process::cfg::shown_path(&scope)
        }
    };
    let scope_text = scope.clone();
    let scope = build_c_string_global(cx.ctx, cx.module, &scope, "sdf_annotate_scope");
    let config = string_arg(2, "config_file")?;
    let log = string_arg(3, "log_file")?;
    let mtm = string_arg(4, "mtm_spec")?;
    let scale_factors = string_arg(5, "scale_factors")?;
    let scale_type = string_arg(6, "scale_type")?;
    record_sdf_site(
        literal(0),
        scope_text,
        [literal(2), literal(3), literal(4), literal(5), literal(6)],
    );
    let rt_fn = cx
        .module
        .get_function(SV_RT_SDF_ANNOTATE_SYMBOL)
        .unwrap_or_else(|| {
            cx.module.add_function(
                SV_RT_SDF_ANNOTATE_SYMBOL,
                cx.ctx.void_type().fn_type(&[ptr_ty.into(); 7], false),
                Some(Linkage::External),
            )
        });
    cx.b.build_call(
        rt_fn,
        &[
            file.into(),
            scope.into(),
            config.into(),
            log.into(),
            mtm.into(),
            scale_factors.into(),
            scale_type.into(),
        ],
        "rt_sdf_annotate_call",
    )
    .unwrap();
    // A call that could not annotate at all ends the run (`sv_sim_runtime::sdf_annotate`'s
    // failure policy, through the same finish `$fatal` uses): nothing after it may execute.
    crate::stmt_shared::leave_if_aborted(cx)?;
    Ok(())
}