vj-codegen 0.1.0

//! Task S7 (`docs/superpowers/plans/2026-09-26-wave-A2-slice.md`; ledger
//! CG-125): the ONE place in this tree that owns an LLVM `Context`/`Module`
//! across the whole compile-lower-JIT pipeline and hands a caller back an
//! opaque [`CompiledPipeline`] -- never an `inkwell::context::Context`/
//! `Module`/`FunctionValue` of its own.
//!
//! **Why this file exists (AB-023/AB-024, `xtask/tests/dep_graph.rs`'s
//! `inkwell_and_llvm_sys_only_under_codegen`):** this workspace pins "no
//! crate other than `sv-sim-codegen` may depend on `inkwell`/`llvm-sys`
//! directly" as a permanent, CI-enforced architecture invariant. `sv-sim-bin`
//! (Task S7's own end-to-end `run` CLI) needs to construct an LLVM module,
//! lower every discovered process into it, JIT it, and bind the real
//! accessor/`nba_enqueue`/`sv_rt_*` symbols to real Rust function addresses --
//! every one of those steps touches `inkwell::context::Context`/`Module`/
//! `FunctionValue` directly. Rather than granting `sv-sim-bin` its own direct
//! `inkwell` dependency (which would violate AB-024 -- verified: this is
//! exactly what `xtask`'s own guard test caught the first time this task
//! tried that), this module is `sv-sim-codegen`'s own new, higher-level
//! entry point: it owns the `Context`/`Module`/`JitBackend` internally and
//! exposes only `sv_lang`/`sv_sim_abi`/plain-Rust types across its public
//! API.
//!
//! **Review fix (r1), Task 24 finding 1: migrated to `orc::JitBackend`.**
//! BINDING CORRECTION 4 required migrating this pipeline's JIT use to the
//! new ORC v2 `LLJIT`-backed [`crate::orc::JitBackend`] in the same task
//! that introduced it, keeping `sv-sim run` working -- this was not done in
//! the original submission (`build_pipeline` still built a legacy
//! `jit::Jit`/`ExecutionEngine`), which left CG-062/064/124's production
//! backend dead code reachable only from its own test file. This module now
//! does that migration:
//!
//! 1. build the `Context`/`Module` and lower every kernel into it, exactly
//!    as before;
//! 2. per BINDING CORRECTION 3 (the same rule that governs `session.rs`'s
//!    parallel per-rayon-worker lowering), serialize the finished, verified
//!    `Module` to LLVM bitcode -- `orc::JitBackend::add_module_from_bitcode`
//!    is the only supported way to hand a module to the new backend, and it
//!    parses each blob into its own fresh, freshly-owned `Context` on the
//!    other side;
//! 3. bind `RealBindings`' real accessor/`nba_enqueue`/`sv_rt_*` addresses
//!    via [`crate::orc::JitBackend::define_absolute_symbol`] -- the ORC
//!    equivalent of `jit::Jit::add_global_mapping` this review's finding 1
//!    also required adding, since ORC v2's `LLJIT` has no built-in
//!    "map this declared-but-undefined symbol to a raw address" call;
//! 4. add the bitcode module to the `JitBackend`.
//!
//! Because the `Module`/`Context` this function builds are fully consumed
//! (parsed once more, on ORC's side, from the serialized bitcode) rather
//! than kept alive behind the `JitBackend`, [`CompiledPipeline`] no longer
//! needs the old self-referential-struct/`'static`-transmute trick a
//! `Jit<'ctx>`-owning struct required: it holds a single, ordinary
//! `orc::JitBackend` with no lifetime parameter at all. `build_pipeline`'s
//! own `ctx`/`module` are therefore plain, non-`'static`, non-boxed local
//! values that drop normally when this function returns.
//!
//! **Reconciled at the wave-B integration merge (docs/LEDGER.md "JIT
//! pipeline"):** A2-part2 Task 4/9/11 added [`compile_to_object`] (the AOT
//! counterpart of [`build_pipeline`]), [`compile_design_kernels`] (the
//! `ProcessTemplateKey`-deduped, `ValueRepr`-parameterized entry point,
//! CG-009), and their shared [`side_tables_for_plans`]/[`canonical_ids_for`]
//! helpers on top of the LEGACY `jit::Jit`/`ExecutionEngine` path (this
//! crate did not yet have `orc::JitBackend` on the branch A2-part2 forked
//! from). Ported onto the ORC-based [`build_pipeline`] here, per BINDING
//! CORRECTION 4: [`compile_design_kernels`] now builds/binds/JITs exactly
//! the way [`build_pipeline`] does (verify, serialize to bitcode, drop
//! `ctx`/`module`, create an `orc::JitBackend`, `define_absolute_symbol`,
//! `add_module_from_bitcode`) instead of `Jit::from_module`/
//! `add_global_mapping` -- no `crate::jit::Jit` import remains in this file.
use std::collections::HashMap;
use std::path::Path;

use inkwell::context::Context;

use sv_lang::kinds::SymbolKind;
use sv_lang::{Design, Expression, MethodFlags, Symbol};
use sv_sim_sim::netlist::InstanceId;
use sv_sim_sim::process::ProcessInstanceId;
use sv_sim_sim::process::dedup::{ProcessTemplateKey, assign_process_instance_ids};
use sv_sim_sim::symid::SymbolId;

use crate::accessor::declare_accessor_fns;
use crate::aot::{AotBackend, emit_process_count_fn};
use crate::error::{CodegenError, LoweringError};
use crate::orc::JitBackend;
use crate::process_lower::{
    ProcessLoweringPlan, SignalSlot, build_process_side_table, emit_process_side_table,
    emit_process_table, lower_cont_assign_kernel_fn, lower_kernel_fn, lower_kernel_fn_with_repr,
};
use crate::value::ValueRepr;
use sv_sim_sim::sched::{ForkKernel, SpawnSpec, WaitTableEntry};

/// A fork branch's kernel name, frame word count and shared-variable map
/// (`crate::process_lower::BranchFrame`).
type ForkBranch = (String, u32, Vec<(u32, u32)>, Vec<(u32, String, u32)>);

/// R-run Task 2 (NL-034, `docs/superpowers/plans/2026-09-27-run-wiring.md`):
/// everything [`build_pipeline`] needs to lower one module-level continuous
/// assign (`module::DiscoveredContAssign`) into the shared module it builds
/// alongside `plans` -- the codegen-facing sibling of [`ProcessLoweringPlan`]
/// for a continuous assign, which has no `Segment`s/`FrameLayout` at all (see
/// `process_lower::lower_cont_assign_kernel_fn`'s own doc comment for why).
/// Built by `sv-sim-bin::run::run_design`, one entry per
/// `module::DiscoveredContAssign` across every elaborated instance, mirroring
/// how it builds one [`ProcessLoweringPlan`] per [`module::DiscoveredProcess`][
/// crate::module::DiscoveredProcess].
pub struct ContAssignLoweringSpec<'d> {
    pub fn_name: String,
    pub fn_sym: Symbol<'d>,
    pub assign_expr: Expression<'d>,
    /// `Some(net)` for a net declaration assignment, where `assign_expr` is
    /// only the RHS (`module::DiscoveredContAssign::net_target`).
    pub net_target: Option<Symbol<'d>>,
    pub signals: HashMap<SymbolId, SignalSlot>,
    /// The resolved net a driver of part of it (`assign y[1] = y[0];`) reads
    /// through: `signals` names the driver's own contribution cell for each
    /// such net (LRM 6.5), `read_signals` the net's resolved cell its
    /// right-hand side must read instead. Empty for a whole-net or
    /// unresolved target.
    pub read_signals: HashMap<SymbolId, SignalSlot>,
    /// `Some(site)`: the continuous driver of the `force` statement at
    /// source offset `site` (`crate::force`) -- `assign_expr` is that
    /// statement's assignment, re-forced while its force is in effect.
    pub force_site: Option<u64>,
    /// `Some(port)`: an output port connection -- `assign_expr` is slang's
    /// implicit `parent_lvalue = <port value>` assignment, whose right-hand
    /// side is empty; the value stored is `port`'s (the child's port
    /// variable, a foreign slot of the parent).
    pub port_source: Option<Symbol<'d>>,
    /// `true`: `net_target` is a module VARIABLE and `assign_expr` its
    /// non-constant initializer (`int z = f(y);`, `C h = new;`; LRM 6.8) --
    /// a one-shot kernel run at time zero, ahead of every procedural
    /// process, instead of the net-driving semantics of a `wire` initializer
    /// (`module::discover_variable_initializers`).
    pub var_init: bool,
    /// `Some(slot)`: a primitive input terminal that is an expression (LRM
    /// 28.3; `nand g(o, C, ~D)`) -- `assign_expr` is that expression alone
    /// and its value is stored, as wide as the expression, to the hidden
    /// cell `slot` (a foreign slot of this instance); the primitive reads it.
    pub hidden_target: Option<SignalSlot>,
}

/// One covergroup compiled for one module instance (`crate::covergroup`):
/// its kernels, named `covergroup::kernel_name(prefix, k)`, read `signals`.
pub struct CovergroupLoweringSpec<'d> {
    pub prefix: String,
    pub cg: Symbol<'d>,
    /// The design's dense index of the covergroup type (`covergroup::type_key`).
    pub type_index: u32,
    pub kernels: Vec<crate::covergroup::CovKernel<'d>>,
    /// `ref` formals and the variables they track (`covergroup::ref_bindings`).
    pub refs: Vec<(Symbol<'d>, Symbol<'d>)>,
    pub signals: HashMap<SymbolId, SignalSlot>,
    /// Sampling-event `iff` conditions, compiled as `covergroup::gate_name(prefix, i)`
    /// (a clocking block's too: its spec has `kernels` empty and `cg` the block).
    pub gates: Vec<Expression<'d>>,
    /// Sampling-event terms on an expression or select (`@(posedge v[1])`),
    /// `(expression, has an edge)`, compiled as `covergroup::event_value_name`.
    pub event_values: Vec<(Expression<'d>, bool)>,
}

/// R-run Task 10 (CG-061 reused, CG-042 untouched), review fix (r1):
/// everything [`build_pipeline`] needs to lower one ordinary (non-DPI) user
/// `function`/`task` into the shared module it builds -- built by
/// `sv-sim-bin::run::run_design` via `module::discover_called_subroutines`
/// (REACHABILITY-based, not a blanket per-instance-body enumeration -- see
/// that function's own doc comment), one entry per `module::
/// DiscoveredSubroutine` actually called, transitively, from some
/// discovered process's body or continuous assign's RHS, across the whole
/// design, mirroring how it already builds one [`ProcessLoweringPlan`]/
/// [`ContAssignLoweringSpec`] per discovered process/continuous-assign.
pub struct SubroutineLoweringSpec<'d> {
    pub sym: Symbol<'d>,
    /// The function is a user-defined nettype's resolution function (LRM
    /// 1800-2023 6.6.7): besides lowering it (and what it calls), emit its
    /// runtime-callable wrapper (`crate::nettype`).
    pub nettype_resolver: bool,
}

/// The real, `extern "C"`-callable function addresses a real
/// [`build_pipeline`] caller binds every emitted kernel's accessor-ABI/
/// `nba_enqueue`/`sv_rt_*` calls to (`usize`, from `some_fn as *const () as
/// usize` -- plain addresses, never an `inkwell` type, so no caller of this
/// struct needs `inkwell` in scope at all). Each field is `Option<usize>`:
/// `None` for a symbol this run's caller has no real binding for (never
/// attempted -- a design that lowers to zero processes at all declares none
/// of these symbols in the first place, so nothing needs binding).
#[derive(Clone, Copy, Debug, Default)]
pub struct RealBindings {
    pub get_scalar: Option<usize>,
    pub set_scalar: Option<usize>,
    pub get_wide: Option<usize>,
    pub set_wide: Option<usize>,
    /// R-run Task 13 (ST-024/ST-025/ST-114): `sv_get_mem_word`/
    /// `sv_set_mem_word` (`SlotClass::Memory`).
    pub get_mem_word: Option<usize>,
    pub set_mem_word: Option<usize>,
    pub nba_enqueue: Option<usize>,
    pub display: Option<usize>,
    pub write: Option<usize>,
    pub finish: Option<usize>,
    /// `disable fork;` (SC-125): `sv_rt_disable_fork`.
    pub disable_fork: Option<usize>,
    /// `disable f;` in a branch of fork `f`: `sv_rt_disable_fork_block`.
    pub disable_fork_block: Option<usize>,
    /// A cross-process/fork-sibling `disable <label>;` (LRM 9.6.2):
    /// `sv_rt_disable_named` (`sv_sim_sim::sched::real_sv_rt_disable_named`).
    pub disable_named: Option<usize>,
    /// A nonblocking write to a select / memory row / >64-bit signal:
    /// `sv_rt_nba_masked` (`sv_sim_sim::sched::real_sv_rt_nba_masked`).
    pub nba_masked: Option<usize>,
    /// A nonblocking event trigger (`->> e`): `sv_rt_nba_pulse`
    /// (`sv_sim_sim::sched::real_sv_rt_nba_pulse`).
    pub nba_pulse: Option<usize>,
    /// Brackets a clocking-block synchronous drive (LRM 14.16, Re-NBA):
    /// `sv_rt_reactive_drive` (`sv_sim_sim::sched::real_sv_rt_reactive_drive`).
    pub reactive_drive: Option<usize>,
    /// A nonblocking write of a collection element (`a[2][k] <= v`):
    /// `sv_rt_nba_coll` (`sv_sim_sim::sched::real_sv_rt_nba_coll`).
    pub nba_coll: Option<usize>,
    /// `$fscanf`/`$sscanf`/`$fgets`/`$fgetc`/`$ungetc`/`$ftell`
    /// (`crate::fileio`, `sv_sim_runtime::file_io_sink`).
    pub fscan: Option<usize>,
    pub sscan: Option<usize>,
    pub fgets: Option<usize>,
    pub fgetc: Option<usize>,
    pub ungetc: Option<usize>,
    pub ftell: Option<usize>,
    /// `$ferror(fd, str)`: `sv_rt_ferror` (`file_io_sink::real_sv_rt_ferror`).
    pub ferror: Option<usize>,
    /// `force`/`release`: `sv_rt_force`/`sv_rt_release`/`sv_rt_force_active`.
    pub force: Option<usize>,
    pub release: Option<usize>,
    pub force_active: Option<usize>,
    /// `force`/`release` of an unpacked-array element: `sv_rt_force_row`.
    pub force_row: Option<usize>,
    /// A run-time delay's ticks: `sv_rt_set_delay`
    /// (`sv_sim_sim::sched::real_sv_rt_set_delay`).
    pub set_delay: Option<usize>,
    /// Which wait term woke a kernel: `sv_rt_fired_term`
    /// (`sv_sim_sim::sched::real_sv_rt_fired_term`).
    pub fired_term: Option<usize>,
    /// Every wait term that matched before a kernel ran: `sv_rt_fired_mask`.
    pub fired_mask: Option<usize>,
    /// Whether the running process ended the run: `sv_rt_aborted`
    /// (`sv_sim_sim::sched::real_sv_rt_aborted`).
    pub aborted: Option<usize>,
    /// A shared variable's cell: `sv_rt_cell_alloc`
    /// (`sv_sim_sim::sched::real_sv_rt_cell_alloc`).
    pub cell_alloc: Option<usize>,
    /// A shared variable's store: `sv_rt_cell_store`
    /// (`sv_sim_sim::sched::real_sv_rt_cell_store`).
    pub cell_store: Option<usize>,
    /// Event controls on shared variables: `sv_rt_edge_snapshot` /
    /// `sv_rt_edge_check` (`sv_sim_sim::sched`).
    pub edge_snapshot: Option<usize>,
    pub edge_check: Option<usize>,
    /// Event-array element waits: `sv_rt_edge_load` / `sv_rt_set_fired_term`
    /// (`sv_sim_sim::sched`).
    pub edge_load: Option<usize>,
    pub set_fired_term: Option<usize>,
    /// A deferred assertion's action capture: `sv_rt_deferred_begin`/`_end`
    /// (`sv_sim_runtime::display_sink`).
    pub deferred_begin: Option<usize>,
    pub deferred_end: Option<usize>,
    /// A deferred assertion action that is a user subroutine call, queued to
    /// mature later: `sv_rt_deferred_call` (`sv_sim_runtime::display_sink`).
    pub deferred_call: Option<usize>,
    /// `$assertcontrol` and its convenience tasks, and the state query an
    /// immediate assertion makes before it runs: `sv_rt_assert_ctl(op, a0, a1, a2,
    /// a3, text)` (`sv_sim_sim::sched::assert_control::real_sv_rt_assert_ctl`).
    pub assert_ctl: Option<usize>,
    /// `$dumpvars`: `sv_rt_dump_vars(levels, scopes)`.
    pub dump_vars: Option<usize>,
    /// `$dumpon`/`$dumpoff`/`$dumpall`/`$dumplimit`: `sv_rt_dump_ctl(op, arg)`.
    pub dump_ctl: Option<usize>,
    /// `$dumpports` and its control tasks: `sv_rt_dump_ports(op, arg, scopes,
    /// file)`.
    pub dump_ports: Option<usize>,
    /// `$timeformat`: `sv_rt_timeformat(units, precision, suffix, width)`.
    pub timeformat: Option<usize>,
    /// `context` DPI imports: `sv_rt_dpi_set_scope(handle, scope_name)`.
    pub dpi_set_scope: Option<usize>,
    /// Around every DPI import call: `sv_rt_dpi_sync()`.
    pub dpi_sync: Option<usize>,
    /// A DPI export thunk's instance: `sv_rt_dpi_export_handle(c_name)`.
    pub dpi_export_handle: Option<usize>,
    /// Which variant of a DPI export: `sv_rt_dpi_export_variant(c_name)`.
    pub dpi_export_variant: Option<usize>,
    /// SV `string` operations (`sv_sim_runtime::strings_rt`).
    pub str_intern: Option<usize>,
    pub str_op: Option<usize>,
    pub str_cstr: Option<usize>,
    pub str_to_real: Option<usize>,
    pub str_from_real: Option<usize>,
    pub str_sformatf: Option<usize>,
    /// Queues, dynamic and associative arrays (`sv_sim_runtime::collections_rt`).
    pub coll: Option<usize>,
    /// Real math system functions: `sv_rt_real_math(op, a, b)`
    /// (`crate::real::MathOp`).
    pub real_math: Option<usize>,
    /// `$readmemh`/`$readmemb` in `sv-sim run`: `sv_rt_readmem_rows`.
    pub readmem_rows: Option<usize>,
    /// `$strobe`/`$monitor`/`$monitoron`/`$monitoroff` (end-of-timestep
    /// argument thunks -- see `process_lower::lower_postponed_display_call`).
    pub strobe_postponed: Option<usize>,
    pub monitor_start: Option<usize>,
    pub monitor_enable: Option<usize>,
    /// Task F2 (RT-043 partial): the real production body for
    /// `crate::expr::SV_RT_TIME_SYMBOL` (`$time`/`$stime`/`$realtime`) --
    /// `sv_sim_sim::sched::kernel_adapter::real_sv_rt_time`.
    pub time: Option<usize>,
    /// B-runtime Task 4 (RT-070/RT-162): the real production body for
    /// `sv_sim_runtime::fst::SV_RT_DUMPFILE_SYMBOL` (`$dumpfile`) --
    /// `sv_sim_runtime::fst::dump_control::real_sv_rt_dumpfile`.
    pub dumpfile: Option<usize>,
    /// B-runtime Task 4 (RT-070/RT-162): the real production body for
    /// `sv_sim_runtime::fst::SV_RT_DUMPFLUSH_SYMBOL` (`$dumpflush`) --
    /// `sv_sim_runtime::fst::dump_control::real_sv_rt_dumpflush`.
    pub dumpflush: Option<usize>,
    /// B-runtime Task 6 (RT-078/RT-079/RT-082): the real production body for
    /// `crate::expr::SV_RT_RANDOM_SYMBOL` (`$random`) --
    /// `sv_sim_runtime::random_sink::real_sv_rt_random`.
    pub random: Option<usize>,
    /// B-runtime Task 6 (RT-078/RT-080/RT-082): the real production body for
    /// `crate::expr::SV_RT_URANDOM_SYMBOL` (`$urandom`) --
    /// `sv_sim_runtime::random_sink::real_sv_rt_urandom`.
    pub urandom: Option<usize>,
    /// B-runtime Task 6 (RT-078/RT-081/RT-082): the real production body for
    /// `crate::expr::SV_RT_URANDOM_RANGE_SYMBOL` (`$urandom_range`) --
    /// `sv_sim_runtime::random_sink::real_sv_rt_urandom_range`.
    pub urandom_range: Option<usize>,
    /// Review fix r2 (blocking finding, RT-078/079): the real production
    /// body for `crate::expr::SV_RT_RANDOM_RESEED_SYMBOL` (`$random(seed)`'s
    /// explicit-seed form) -- `sv_sim_runtime::random::sv_rt_random_reseed`,
    /// bound directly (unlike `random`/`urandom`/`urandom_range` above, this
    /// call form needs no `RuntimeHost`-free ambient-state sink at all: it
    /// is already a pure function of the caller-supplied pointer alone).
    pub random_reseed: Option<usize>,
    /// Ditto, for `crate::expr::SV_RT_URANDOM_RESEED_SYMBOL` (`$urandom(seed)`)
    /// -- `sv_sim_runtime::random::sv_rt_urandom_reseed`.
    pub urandom_reseed: Option<usize>,
    /// `crate::expr::SV_RT_DIST_SYMBOL` (`$dist_*`) --
    /// `sv_sim_runtime::random::sv_rt_dist`, a pure function of its arguments.
    pub dist: Option<usize>,
    /// B-runtime Task 7 (RT-050/RT-051): the real production body for
    /// `sv_sim_runtime::file_io::SV_RT_FOPEN_SYMBOL` (`$fopen`) --
    /// `sv_sim_runtime::file_io_sink::real_sv_rt_fopen`.
    pub fopen: Option<usize>,
    /// The single-argument `$fopen(path)` (multichannel descriptor, LRM
    /// 21.3.1) -- `sv_sim_runtime::file_io_sink::real_sv_rt_fopen_mcd`.
    pub fopen_mcd: Option<usize>,
    /// `$system` (LRM 20.17) -- `sv_sim_runtime::file_io_sink::real_sv_rt_system`.
    pub system: Option<usize>,
    /// B-runtime Task 7 (RT-050/RT-052): the real production body for
    /// `sv_sim_runtime::file_io::SV_RT_FCLOSE_SYMBOL` (`$fclose`) --
    /// `sv_sim_runtime::file_io_sink::real_sv_rt_fclose`.
    pub fclose: Option<usize>,
    /// B-runtime Task 7 (RT-050/RT-053): the real production body for
    /// `sv_sim_runtime::file_io::SV_RT_FFLUSH_SYMBOL` (`$fflush`) --
    /// `sv_sim_runtime::file_io_sink::real_sv_rt_fflush`.
    pub fflush: Option<usize>,
    /// B-runtime Task 8 (RT-022/RT-054/RT-055): the real production body for
    /// `sv_sim_runtime::file_io::SV_RT_FWRITE_SYMBOL` (`$fwrite`) --
    /// `sv_sim_runtime::file_io_sink::real_sv_rt_fwrite`.
    pub fwrite: Option<usize>,
    /// B-runtime Task 8 (RT-022/RT-049/RT-054): the real production body for
    /// `sv_sim_runtime::file_io::SV_RT_FDISPLAY_SYMBOL` (`$fdisplay`) --
    /// `sv_sim_runtime::file_io_sink::real_sv_rt_fdisplay`.
    pub fdisplay: Option<usize>,
    /// B-runtime Task 8 (RT-056): the real production body for
    /// `sv_sim_runtime::file_io::SV_RT_FMONITOR_SYMBOL` (`$fmonitor`) --
    /// `sv_sim_runtime::file_io_sink::real_sv_rt_fmonitor`.
    pub fmonitor: Option<usize>,
    /// B-runtime Task 8 (RT-057): the real production body for
    /// `sv_sim_runtime::file_io::SV_RT_FSTROBE_SYMBOL` (`$fstrobe`) --
    /// `sv_sim_runtime::file_io_sink::real_sv_rt_fstrobe`.
    pub fstrobe: Option<usize>,
    /// B-runtime Task 9 (RT-061): the real production body for
    /// `sv_sim_runtime::file_io::SV_RT_FSEEK_SYMBOL` (`$fseek`) --
    /// `sv_sim_runtime::file_io_sink::real_sv_rt_fseek`.
    pub fseek: Option<usize>,
    /// B-runtime Task 9 (RT-063): the real production body for
    /// `sv_sim_runtime::file_io::SV_RT_FEOF_SYMBOL` (`$feof`) --
    /// `sv_sim_runtime::file_io_sink::real_sv_rt_feof`.
    pub feof: Option<usize>,
    /// B-runtime Task 11 (RT-074/RT-075/RT-077): the real production body
    /// for `sv_sim_runtime::plusargs::SV_RT_PLUSARGS_TEST_SYMBOL` (`$test$plusargs`) --
    /// `sv_sim_runtime::plusargs_sink::real_sv_rt_plusargs_test`.
    pub plusargs_test: Option<usize>,
    /// B-runtime Task 11 (RT-074/RT-076/RT-077): the real production body
    /// for `sv_sim_runtime::plusargs::SV_RT_PLUSARGS_VALUE_SYMBOL` (`$value$plusargs`) --
    /// `sv_sim_runtime::plusargs_sink::real_sv_rt_plusargs_value`.
    pub plusargs_value: Option<usize>,
    /// SD-B / T25: the real production body for
    /// `sv_sim_runtime::sdf_annotate::SV_RT_SDF_ANNOTATE_SYMBOL`
    /// (`$sdf_annotate`) -- `sv_sim_runtime::sdf_annotate::
    /// sv_rt_sdf_annotate`, which decodes the call and hands it to the
    /// host-installed applier (`sdf_annotate::install_applier`); it
    /// replaces B-runtime Task 16's (RT-166) abort-on-call stub.
    pub sdf_annotate: Option<usize>,
    /// SD-C / T28: the real production body for
    /// `sv_sim_runtime::specparam::SV_RT_SPECPARAM_VALUE_SYMBOL` -- the annotated value of a
    /// specparam an SDF `LABEL` replaced (LRM 32.4.3), NaN when nothing did. Left `None` the
    /// symbol is unresolved and a design that reads a specparam fails to link, loudly.
    pub specparam_value: Option<usize>,
    /// Classes plan Task 5: the object heap (`sv_sim_sim::objects`'s
    /// multiplexed ABI entry point) -- `sv_sim_runtime::objects_rt::
    /// sv_rt_obj`. Without an explicit binding here, this symbol's address
    /// is never taken by any Rust call site in this crate (every call into
    /// it is from LLVM-emitted IR, dynamically), so a sufficiently
    /// aggressive linker (confirmed live: `sv-sim-harness`'s own
    /// integration-test binaries, unlike `sv-sim-bin`'s CLI binary) dead-
    /// strips it, and the JIT's own symbol resolution then fails with
    /// "Symbols not found: [ sv_rt_obj ]" the first time a class's `new`/
    /// field access actually runs -- exactly the same reason every other
    /// LLVM-IR-only-called `sv_rt_*` symbol in this struct is bound this
    /// way.
    pub obj: Option<usize>,
    /// Covergroups: `sv_sim_runtime::covergroup_rt::sv_rt_cov`.
    pub cov: Option<usize>,
    /// A VPI-registered system task or function call
    /// (`crate::vpi_systf::SV_RT_VPI_SYSTF_SYMBOL`).
    pub vpi_systf: Option<usize>,
    /// VPI's dynamic-object probes (statements, frames,
    /// `crate::vpi_dyn::SV_RT_VPI_DYN_SYMBOL`); emitted only when a VPI
    /// library is loaded.
    pub vpi_dyn: Option<usize>,
    /// Classes plan Tasks 13/14: the built-in `process` class's multiplexed
    /// entry point, `sv_sim_runtime::process_class::sv_rt_process`. Bound for
    /// the same dead-strip reason as `obj`.
    pub process_class: Option<usize>,
    /// Classes plan Task 16: the built-in `weak_reference#(T)` class's
    /// multiplexed entry point, `sv_sim_runtime::weakref::sv_rt_weakref`.
    /// Bound for the same dead-strip reason as `obj`.
    pub weakref: Option<usize>,
    /// Classes plan Task 17: the built-in `semaphore` class's multiplexed
    /// entry point, `sv_sim_runtime::semaphore_rt::sv_rt_semaphore`. Bound for
    /// the same dead-strip reason as `obj`.
    pub semaphore: Option<usize>,
    /// The stochastic analysis tasks' (LRM 20.15) multiplexed entry point,
    /// `sv_sim_runtime::stoch_queue::sv_rt_stoch_q`.
    pub stoch_q: Option<usize>,
    /// `$countdrivers` (LRM D.2): `sv_rt_net_drivers`
    /// (`sv_sim_sim::sched::real_sv_rt_net_drivers`).
    pub net_drivers: Option<usize>,
    /// Classes plan Task 18: the built-in `mailbox` class's multiplexed entry
    /// point, `sv_sim_runtime::mailbox_rt::sv_rt_mailbox`. Bound for the same
    /// dead-strip reason as `obj`.
    pub mailbox: Option<usize>,
    /// Vectors wider than the narrow path's ceiling (`crate::huge`):
    /// `sv_sim_runtime::wide_rt::sv_rt_wide`. Left `None`, a design with such a
    /// vector fails to link, loudly.
    pub wide: Option<usize>,
    /// A huge module signal's process shadow (prime / mark / commit of its
    /// dirty window): `sv_sim_sim::sched::real_sv_rt_huge`. Left `None`, a
    /// design with such a signal fails to link, loudly.
    pub huge: Option<usize>,
    /// A procedural concurrent assertion's queue and action inputs:
    /// `sv_rt_proc_assert` / `sv_rt_assert_input`
    /// (`sv_sim_sim::sched::proc_assert`, 16.14.6).
    pub proc_assert: Option<usize>,
    pub assert_input: Option<usize>,
    /// `sv_rt_proc_assert_disable` (16.14.6.4).
    pub proc_assert_disable: Option<usize>,
    /// The instance a (foreign) slot belongs to: `sv_rt_slot_owner`
    /// (`sv_sim_sim::state::real_sv_rt_slot_owner`), the callee's handle of a
    /// hierarchical call into another instance.
    pub slot_owner: Option<usize>,
    /// Per-slot direct-read addresses of an instance: `sv_rt_inline_ptrs`
    /// (`sv_sim_sim::state::real_sv_rt_inline_ptrs`), JIT-lowered code only.
    pub inline_ptrs: Option<usize>,
}

impl RealBindings {
    /// `(symbol, address)` for every runtime symbol `module` declares that
    /// this binding set provides. A symbol never declared (e.g. no
    /// nonblocking assignment, so no `nba_enqueue`) or left `None` by the
    /// caller is skipped -- neither is an error.
    fn declared_in(&self, module: &inkwell::module::Module) -> Vec<(String, usize)> {
        self.table()
            .into_iter()
            .filter(|(name, _)| module.get_function(name).is_some())
            .filter_map(|(name, addr)| Some((name.to_owned(), addr?)))
            .collect()
    }

    /// Every runtime symbol a compiled kernel can call, in table order: the
    /// exports an AOT `.so` must define (`sv-sim-aot` exports one function
    /// per name; `aot_exports.rs` guards that in both directions).
    pub fn symbol_names() -> Vec<&'static str> {
        Self::default()
            .table()
            .into_iter()
            .map(|(n, _)| n)
            .collect()
    }

    /// The `(symbol, binding)` row of every runtime symbol.
    fn table(&self) -> [(&'static str, Option<usize>); 109] {
        // Exhaustive: a new binding field without a row here fails to compile.
        let RealBindings {
            get_scalar,
            set_scalar,
            get_wide,
            set_wide,
            get_mem_word,
            set_mem_word,
            nba_enqueue,
            display,
            write,
            finish,
            disable_fork,
            disable_fork_block,
            disable_named,
            nba_masked,
            nba_pulse,
            reactive_drive,
            nba_coll,
            fscan,
            sscan,
            fgets,
            fgetc,
            ungetc,
            ftell,
            ferror,
            force,
            release,
            force_active,
            force_row,
            set_delay,
            fired_term,
            fired_mask,
            aborted,
            cell_alloc,
            cell_store,
            edge_snapshot,
            edge_check,
            edge_load,
            set_fired_term,
            deferred_begin,
            deferred_end,
            deferred_call,
            assert_ctl,
            dump_vars,
            dump_ctl,
            dump_ports,
            timeformat,
            real_math,
            dpi_set_scope,
            dpi_sync,
            dpi_export_handle,
            dpi_export_variant,
            str_intern,
            str_op,
            str_cstr,
            str_to_real,
            str_from_real,
            str_sformatf,
            coll,
            readmem_rows,
            strobe_postponed,
            monitor_start,
            monitor_enable,
            time,
            dumpfile,
            dumpflush,
            random,
            urandom,
            urandom_range,
            random_reseed,
            urandom_reseed,
            dist,
            fopen,
            fopen_mcd,
            system,
            fclose,
            fflush,
            fwrite,
            fdisplay,
            fmonitor,
            fstrobe,
            fseek,
            feof,
            plusargs_test,
            plusargs_value,
            sdf_annotate,
            specparam_value,
            obj,
            cov,
            vpi_systf,
            vpi_dyn,
            process_class,
            weakref,
            semaphore,
            stoch_q,
            net_drivers,
            mailbox,
            wide,
            huge,
            proc_assert,
            assert_input,
            proc_assert_disable,
            slot_owner,
            inline_ptrs,
        } = *self;
        let table: [(&'static str, Option<usize>); 109] = [
            (crate::process_lower::SV_RT_SLOT_OWNER_SYMBOL, slot_owner),
            (crate::accessor::SV_RT_INLINE_PTRS_SYMBOL, inline_ptrs),
            (
                crate::dpi::SV_RT_DPI_EXPORT_TASK_CALL_SYMBOL,
                Some(sv_sim_sim::dpi_task::sv_rt_dpi_export_task_call as *const () as usize),
            ),
            (
                crate::dpi::SV_RT_DPI_EXPORT_TASK_ERROR_SYMBOL,
                Some(sv_sim_sim::dpi_task::sv_rt_dpi_export_task_error as *const () as usize),
            ),
            (
                crate::dpi::SV_RT_DPI_TASK_SCOPE_SYMBOL,
                Some(sv_sim_sim::dpi_task::sv_rt_dpi_task_scope as *const () as usize),
            ),
            (
                crate::dpi::SV_RT_DPI_FN_SCOPE_SYMBOL,
                Some(sv_sim_sim::dpi_task::sv_rt_dpi_fn_scope as *const () as usize),
            ),
            (
                crate::dpi::SV_RT_DPI_FN_DISABLE_SET_SYMBOL,
                Some(sv_sim_sim::dpi_task::sv_rt_dpi_fn_disable_set as *const () as usize),
            ),
            (
                crate::dpi::SV_RT_DPI_FN_DISABLE_INDEX_SYMBOL,
                Some(sv_sim_sim::dpi_task::sv_rt_dpi_fn_disable_index as *const () as usize),
            ),
            (crate::huge::SV_RT_HUGE_SYMBOL, huge),
            (crate::process_lower::SV_RT_ASSERT_CTL_SYMBOL, assert_ctl),
            (
                crate::process_lower::SV_RT_PROC_ASSERT_DISABLE_SYMBOL,
                proc_assert_disable,
            ),
            (crate::process_lower::SV_RT_PROC_ASSERT_SYMBOL, proc_assert),
            (
                crate::process_lower::SV_RT_ASSERT_INPUT_SYMBOL,
                assert_input,
            ),
            (sv_sim_abi::accessor::SV_GET_SCALAR_SYMBOL, get_scalar),
            (sv_sim_abi::accessor::SV_SET_SCALAR_SYMBOL, set_scalar),
            (sv_sim_abi::accessor::SV_GET_WIDE_SYMBOL, get_wide),
            (sv_sim_abi::accessor::SV_SET_WIDE_SYMBOL, set_wide),
            (sv_sim_abi::accessor::SV_GET_MEM_WORD_SYMBOL, get_mem_word),
            (sv_sim_abi::accessor::SV_SET_MEM_WORD_SYMBOL, set_mem_word),
            (sv_sim_abi::process::NBA_ENQUEUE_SYMBOL, nba_enqueue),
            (sv_sim_runtime::rtarg::SV_RT_DISPLAY_SYMBOL, display),
            (sv_sim_runtime::rtarg::SV_RT_WRITE_SYMBOL, write),
            (crate::process_lower::SV_RT_FINISH_SYMBOL, finish),
            (
                crate::process_lower::SV_RT_DISABLE_FORK_SYMBOL,
                disable_fork,
            ),
            (crate::process_lower::SV_RT_NBA_MASKED_SYMBOL, nba_masked),
            (crate::process_lower::SV_RT_NBA_PULSE_SYMBOL, nba_pulse),
            (
                crate::process_lower::SV_RT_REACTIVE_DRIVE_SYMBOL,
                reactive_drive,
            ),
            (crate::process_lower::SV_RT_NBA_COLL_SYMBOL, nba_coll),
            (
                crate::process_lower::SV_RT_DISABLE_FORK_BLOCK_SYMBOL,
                disable_fork_block,
            ),
            (
                crate::process_lower::SV_RT_DISABLE_NAMED_SYMBOL,
                disable_named,
            ),
            (crate::process_lower::SV_RT_SET_DELAY_SYMBOL, set_delay),
            (crate::process_lower::SV_RT_FIRED_TERM_SYMBOL, fired_term),
            (crate::process_lower::SV_RT_FIRED_MASK_SYMBOL, fired_mask),
            (crate::process_lower::SV_RT_ABORTED_SYMBOL, aborted),
            (crate::process_lower::SV_RT_CELL_ALLOC_SYMBOL, cell_alloc),
            (crate::process_lower::SV_RT_CELL_STORE_SYMBOL, cell_store),
            (
                crate::process_lower::SV_RT_EDGE_SNAPSHOT_SYMBOL,
                edge_snapshot,
            ),
            (crate::process_lower::SV_RT_EDGE_CHECK_SYMBOL, edge_check),
            (crate::process_lower::SV_RT_EDGE_LOAD_SYMBOL, edge_load),
            (
                crate::process_lower::SV_RT_SET_FIRED_TERM_SYMBOL,
                set_fired_term,
            ),
            (
                crate::process_lower::SV_RT_DEFERRED_BEGIN_SYMBOL,
                deferred_begin,
            ),
            (
                crate::process_lower::SV_RT_DEFERRED_END_SYMBOL,
                deferred_end,
            ),
            (
                crate::deferred_call::SV_RT_DEFERRED_CALL_SYMBOL,
                deferred_call,
            ),
            (crate::fileio::SV_RT_FSCAN_SYMBOL, fscan),
            (crate::fileio::SV_RT_SSCAN_SYMBOL, sscan),
            (crate::fileio::SV_RT_FGETS_SYMBOL, fgets),
            (crate::fileio::SV_RT_FGETC_SYMBOL, fgetc),
            (crate::fileio::SV_RT_UNGETC_SYMBOL, ungetc),
            (crate::fileio::SV_RT_FTELL_SYMBOL, ftell),
            (crate::fileio::SV_RT_FERROR_SYMBOL, ferror),
            (crate::force::SV_RT_FORCE_SYMBOL, force),
            (crate::force::SV_RT_RELEASE_SYMBOL, release),
            (crate::force::SV_RT_FORCE_ACTIVE_SYMBOL, force_active),
            (crate::force::SV_RT_FORCE_ROW_SYMBOL, force_row),
            (crate::process_lower::SV_RT_DUMP_VARS_SYMBOL, dump_vars),
            (crate::process_lower::SV_RT_DUMP_CTL_SYMBOL, dump_ctl),
            (crate::process_lower::SV_RT_DUMP_PORTS_SYMBOL, dump_ports),
            (sv_sim_runtime::timefmt::SV_RT_TIMEFORMAT_SYMBOL, timeformat),
            (crate::real::SV_RT_REAL_MATH_SYMBOL, real_math),
            (crate::dpi::SV_RT_DPI_SET_SCOPE_SYMBOL, dpi_set_scope),
            (crate::dpi::SV_RT_DPI_SYNC_SYMBOL, dpi_sync),
            (
                crate::dpi::SV_RT_DPI_EXPORT_HANDLE_SYMBOL,
                dpi_export_handle,
            ),
            (
                crate::dpi::SV_RT_DPI_EXPORT_VARIANT_SYMBOL,
                dpi_export_variant,
            ),
            (
                sv_sim_runtime::strings_rt::SV_RT_STR_INTERN_SYMBOL,
                str_intern,
            ),
            (sv_sim_runtime::strings_rt::SV_RT_STR_OP_SYMBOL, str_op),
            (sv_sim_runtime::collections_rt::SV_RT_COLL_SYMBOL, coll),
            (sv_sim_runtime::strings_rt::SV_RT_STR_CSTR_SYMBOL, str_cstr),
            (
                sv_sim_runtime::strings_rt::SV_RT_STR_TO_REAL_SYMBOL,
                str_to_real,
            ),
            (
                sv_sim_runtime::strings_rt::SV_RT_STR_FROM_REAL_SYMBOL,
                str_from_real,
            ),
            (
                sv_sim_runtime::strings_rt::SV_RT_STR_SFORMATF_SYMBOL,
                str_sformatf,
            ),
            (
                sv_sim_runtime::readmem::SV_RT_READMEM_ROWS_SYMBOL,
                readmem_rows,
            ),
            (
                crate::process_lower::SV_RT_STROBE_POSTPONED_SYMBOL,
                strobe_postponed,
            ),
            (
                crate::process_lower::SV_RT_MONITOR_START_SYMBOL,
                monitor_start,
            ),
            (
                crate::process_lower::SV_RT_MONITOR_ENABLE_SYMBOL,
                monitor_enable,
            ),
            (crate::expr::SV_RT_TIME_SYMBOL, time),
            (sv_sim_runtime::fst::SV_RT_DUMPFILE_SYMBOL, dumpfile),
            (sv_sim_runtime::fst::SV_RT_DUMPFLUSH_SYMBOL, dumpflush),
            (crate::expr::SV_RT_RANDOM_SYMBOL, random),
            (crate::expr::SV_RT_URANDOM_SYMBOL, urandom),
            (crate::expr::SV_RT_URANDOM_RANGE_SYMBOL, urandom_range),
            (crate::expr::SV_RT_RANDOM_RESEED_SYMBOL, random_reseed),
            (crate::expr::SV_RT_URANDOM_RESEED_SYMBOL, urandom_reseed),
            (crate::expr::SV_RT_DIST_SYMBOL, dist),
            (sv_sim_runtime::file_io::SV_RT_FOPEN_SYMBOL, fopen),
            (sv_sim_runtime::file_io::SV_RT_FOPEN_MCD_SYMBOL, fopen_mcd),
            (sv_sim_runtime::file_io::SV_RT_SYSTEM_SYMBOL, system),
            (sv_sim_runtime::file_io::SV_RT_FCLOSE_SYMBOL, fclose),
            (sv_sim_runtime::file_io::SV_RT_FFLUSH_SYMBOL, fflush),
            (sv_sim_runtime::file_io::SV_RT_FWRITE_SYMBOL, fwrite),
            (sv_sim_runtime::file_io::SV_RT_FDISPLAY_SYMBOL, fdisplay),
            (sv_sim_runtime::file_io::SV_RT_FMONITOR_SYMBOL, fmonitor),
            (sv_sim_runtime::file_io::SV_RT_FSTROBE_SYMBOL, fstrobe),
            (sv_sim_runtime::file_io::SV_RT_FSEEK_SYMBOL, fseek),
            (sv_sim_runtime::file_io::SV_RT_FEOF_SYMBOL, feof),
            (
                sv_sim_runtime::plusargs::SV_RT_PLUSARGS_TEST_SYMBOL,
                plusargs_test,
            ),
            (
                sv_sim_runtime::plusargs::SV_RT_PLUSARGS_VALUE_SYMBOL,
                plusargs_value,
            ),
            (
                sv_sim_runtime::sdf_annotate::SV_RT_SDF_ANNOTATE_SYMBOL,
                sdf_annotate,
            ),
            (
                sv_sim_runtime::specparam::SV_RT_SPECPARAM_VALUE_SYMBOL,
                specparam_value,
            ),
            (sv_sim_runtime::objects_rt::SV_RT_OBJ_SYMBOL, obj),
            (sv_sim_runtime::covergroup_rt::SV_RT_COV_SYMBOL, cov),
            (crate::vpi_systf::SV_RT_VPI_SYSTF_SYMBOL, vpi_systf),
            (crate::vpi_dyn::SV_RT_VPI_DYN_SYMBOL, vpi_dyn),
            (
                sv_sim_runtime::process_class::SV_RT_PROCESS_SYMBOL,
                process_class,
            ),
            (sv_sim_runtime::weakref::SV_RT_WEAKREF_SYMBOL, weakref),
            (
                sv_sim_runtime::semaphore_rt::SV_RT_SEMAPHORE_SYMBOL,
                semaphore,
            ),
            (sv_sim_runtime::stoch_queue::SV_RT_STOCH_Q_SYMBOL, stoch_q),
            ("sv_rt_net_drivers", net_drivers),
            (sv_sim_runtime::mailbox_rt::SV_RT_MAILBOX_SYMBOL, mailbox),
            (sv_sim_runtime::wide_rt::SV_RT_WIDE_SYMBOL, wide),
        ];
        table
    }
}

/// A timed DPI export task (LRM 35.7) compiled as a one-shot process kernel.
#[derive(Debug, Clone)]
pub struct ExportTaskInfo {
    /// The C identifier the task is exported under.
    pub c_name: String,
    /// Hierarchical path of the instance the task lives in.
    pub scope: String,
    /// Its kernel index, entry pc, frame size and formal slots.
    pub kernel: crate::process_lower::ExportTaskKernel,
    /// Its row in the fork table: the `SpawnSpec` that starts it, and the
    /// `export` index its C thunk passes to `sv_rt_dpi_export_task_call`.
    pub fork_row: u32,
}

/// The opaque, JIT-ready result of [`build_pipeline`]: owns the
/// `orc::JitBackend` this run's whole compile-lower-JIT pass built and added
/// its bitcode-serialized module to, exposing only
/// [`Self::get_process_fn`] (the frozen, `sv_lang`/`inkwell`-free ABI type
/// `sv_sim_abi::ProcessFn`) -- CG-125's own API, now backed by the
/// production ORC v2 JIT (review fix r1) rather than the legacy
/// `ExecutionEngine`.
///
/// No lifetime parameter, no boxed `Context`, no self-referential-struct
/// trick: `JitBackend::add_module_from_bitcode` parses its own fresh
/// `Context` on the other side of the bitcode blob and that `Context` has
/// no relationship to whichever one `build_pipeline` used to construct the
/// module in the first place (CG-064's own guarantee, re-used here rather
/// than re-derived).
pub struct CompiledPipeline {
    backend: JitBackend,
    /// The program's fork-child table (PR-085): every `fork ... join` site's
    /// branches, as `SpawnSpec`s whose `kernel` indexes `fork_branches`.
    fork_table: Vec<SpawnSpec>,
    /// Each fork-branch kernel, by `SpawnSpec::kernel`: `(mangled name, frame
    /// word count)`. Empty for a design with no fork/join.
    fork_branches: Vec<ForkBranch>,
    /// The program's multi-term wait table (`@*`, `@(a or b)`, wide/multi-
    /// signal `wait(expr)`): see `sv_sim_sim::sched::WaitTableEntry`.
    wait_table: Vec<WaitTableEntry>,
    /// `(C identifier, thunk symbol)` of every DPI export.
    dpi_exports: Vec<(String, String)>,
    /// `(C identifier, instance scope, variant)` of every exporting instance.
    dpi_export_variants: Vec<(String, String, u32)>,
    /// Every timed DPI export task, compiled as a fork-branch kernel (35.7).
    export_tasks: Vec<ExportTaskInfo>,
    /// Every static concurrent assertion (T29), with its compiled functions.
    assertions: Vec<crate::sva::emit::AssertionSpec>,
}

impl CompiledPipeline {
    /// The design's static concurrent assertions (`crate::sva::emit`).
    pub fn assertions(&self) -> &[crate::sva::emit::AssertionSpec] {
        &self.assertions
    }

    /// An assertion's row snapshot function (`{name}_snap`).
    pub fn assertion_snap(&self, name: &str) -> Option<crate::sva::emit::SnapFn> {
        // SAFETY: `crate::sva::emit` emits exactly this signature.
        unsafe { self.backend.get_fn(&format!("{name}_snap")) }
    }

    /// An assertion's leaf function `{name}_l{leaf}`.
    pub fn assertion_leaf(&self, name: &str, leaf: u32) -> Option<crate::sva::emit::LeafFn> {
        // SAFETY: `crate::sva::emit` emits exactly this signature.
        unsafe { self.backend.get_fn(&format!("{name}_l{leaf}")) }
    }

    /// The live-state form `{name}_lv{leaf}` of a leaf the engine evaluates on
    /// the live state that holds a sampled value function (16.12).
    pub fn assertion_live_leaf(&self, name: &str, leaf: u32) -> Option<crate::sva::emit::LeafFn> {
        // SAFETY: `crate::sva::emit` emits exactly this signature.
        unsafe { self.backend.get_fn(&format!("{name}_lv{leaf}")) }
    }

    /// An assertion's clock tick test `{name}_t{clock}`.
    pub fn assertion_tick(&self, name: &str, clock: u32) -> Option<crate::sva::emit::TickFn> {
        // SAFETY: `crate::sva::emit` emits exactly this signature.
        unsafe { self.backend.get_fn(&format!("{name}_t{clock}")) }
    }

    /// An assertion's `case` comparison `{name}_c{pair}`.
    pub fn assertion_case(&self, name: &str, pair: u32) -> Option<crate::sva::emit::CaseFn> {
        // SAFETY: `crate::sva::emit` emits exactly this signature.
        unsafe { self.backend.get_fn(&format!("{name}_c{pair}")) }
    }

    /// `(C identifier, instance scope, variant)` for every instance that
    /// exports a DPI subroutine (see `sv_rt_dpi_export_variant`).
    /// The timed DPI export tasks (35.7), compiled as fork-branch kernels.
    pub fn export_tasks(&self) -> &[ExportTaskInfo] {
        &self.export_tasks
    }

    pub fn dpi_export_variants(&self) -> &[(String, String, u32)] {
        &self.dpi_export_variants
    }

    /// `(C identifier, address)` of every DPI export's JIT'd thunk.
    pub fn dpi_export_thunks(&self) -> Result<Vec<(String, usize)>, LoweringError> {
        self.dpi_exports
            .iter()
            .map(|(c_name, thunk)| {
                self.get_global_ptr(thunk)
                    .map(|p| (c_name.clone(), p as usize))
                    .ok_or_else(|| LoweringError {
                        message: format!("JIT did not produce DPI export thunk `{thunk}`"),
                        at: "pipeline::CompiledPipeline::dpi_export_thunks".to_string(),
                    })
            })
            .collect()
    }

    /// The program's multi-term wait table, shared by every kernel process
    /// `sv-sim run` mints from this pipeline.
    pub fn wait_table(&self) -> std::sync::Arc<[WaitTableEntry]> {
        std::sync::Arc::from(self.wait_table.clone())
    }

    /// The program's fork-child table (see the field doc comment), shared by
    /// every kernel process `sv-sim run` mints from this pipeline.
    pub fn fork_table(&self) -> std::sync::Arc<[SpawnSpec]> {
        std::sync::Arc::from(self.fork_table.clone())
    }

    /// Resolves every fork-branch kernel to its JIT'd entry point, indexed by
    /// `SpawnSpec::kernel` -- what `CompiledKernelProcess::with_fork_kernels`
    /// needs to mint a `fork` branch's child process at run time.
    pub fn fork_kernels(&self) -> Result<std::sync::Arc<[Option<ForkKernel>]>, LoweringError> {
        self.fork_branches
            .iter()
            .map(|(name, frame_word_count, captures, disable_scopes)| {
                let kernel = self.get_process_fn(name).ok_or_else(|| LoweringError {
                    message: format!("JIT did not produce fork-branch kernel `{name}`"),
                    at: "pipeline::CompiledPipeline::fork_kernels".to_string(),
                })?;
                Ok(Some(ForkKernel {
                    kernel,
                    frame_word_count: *frame_word_count,
                    captures: std::sync::Arc::from(captures.as_slice()),
                    disable_scopes: std::sync::Arc::from(disable_scopes.as_slice()),
                }))
            })
            .collect()
    }

    /// CG-125: retrieves a compiled process kernel's callable function
    /// pointer by its mangled (LLVM) name -- `Some`/`None`, never a panic on
    /// an unknown name.
    pub fn get_process_fn(&self, mangled: &str) -> Option<sv_sim_abi::ProcessFn> {
        // SAFETY: `mangled` (per this function's own callers, e.g.
        // `sv-sim-bin`'s `run.rs`, and the `names` this same
        // `build_pipeline` call returned alongside this `CompiledPipeline`)
        // always names a kernel function `process_lower::lower_kernel_fn`
        // itself emitted with the frozen ARCHITECTURE §5 ABI signature
        // `extern "C" fn(SimHandle, *mut u8, u32) -> EvalResult` --
        // `sv_sim_abi::ProcessFn`'s own definition -- so `F = ProcessFn`
        // here is exactly the real, JIT-compiled function's ABI, never a
        // caller-supplied/unchecked type.
        unsafe { self.backend.get_fn(mangled) }
    }

    /// The JIT'd tick guard of a sampled-value call site (`crate::sampled`),
    /// by `sv_sim_sim::sva::sampled::guard_name`: 1 when the site's clocking
    /// event occurred in the time step that is ending.
    pub fn get_sampled_guard(
        &self,
        name: &str,
    ) -> Option<extern "C" fn(sv_sim_abi::SimHandle) -> u8> {
        // SAFETY: `crate::sampled::compile_site_guard` emits exactly this
        // signature (`i8 @name(ptr handle)`) under every `guard_name`.
        unsafe { self.backend.get_fn(name) }
    }

    /// The JIT'd wrapper of a nettype resolution function (`crate::nettype`),
    /// by its [`crate::nettype::resolver_symbol`].
    pub fn nettype_resolver(&self, symbol: &str) -> Option<crate::nettype::ResolverFn> {
        // SAFETY: `crate::nettype::emit_resolver` emits exactly this
        // signature (`void (i64, ptr)`) under every `resolver_symbol`.
        unsafe { self.backend.get_fn(symbol) }
    }

    /// The runtime address of the JIT'd data global `mangled` (its storage,
    /// not its value), or `None` for an unknown name. `JitBackend::get_fn`'s
    /// lookup resolves any named symbol -- for a global, that is the address
    /// of its backing storage.
    pub fn get_global_ptr(&self, mangled: &str) -> Option<*mut u8> {
        // SAFETY: `F = *mut u8` is pointer-sized, matching `get_fn`'s
        // contract; the returned value is the resolved address itself, never
        // called through.
        unsafe { self.backend.get_fn(mangled) }
    }
}

/// Lowers every plan in `plans` into ONE shared LLVM module (in
/// `plans`'/the returned first `Vec<String>`'s own order), binds `bindings`'
/// real function addresses to whichever of the accessor/`nba_enqueue`/
/// `sv_rt_*` symbols this run's kernels actually declared (checked
/// individually -- declaring `nba_enqueue`, for instance, only happens if at
/// least one plan contains a nonblocking assignment), and returns the
/// resulting [`CompiledPipeline`] plus each kernel's own mangled name,
/// index-aligned with `plans`.
///
/// B-runtime Task 15 (RT-007, "the missing pipeline wiring"): also lowers
/// every `export "DPI-C"` declaration `design` contains
/// ([`crate::dpi::lower_all_dpi_exports`]) into the SAME shared module, so a
/// real compiled design's export thunks are reachable by their own
/// unmangled `c_identifier` name through the returned [`CompiledPipeline`]'s
/// underlying `JitBackend`.
///
/// R-run Task 2 (NL-034) addition: `cont_assigns` lowers alongside `plans`
/// into the SAME shared module/JIT batch (so a continuous assign's kernel
/// call can be resolved via the SAME [`CompiledPipeline::get_process_fn`]
/// this function already returns), returning its own mangled names,
/// index-aligned with `cont_assigns`, as the third tuple element.
/// Deliberately NOT folded into `plans`/the first `Vec<String>`, and
/// deliberately NOT added to `emit_process_table`/`side_tables_for_plans`'s
/// per-process side-table: `sv-sim-bin::run::run_design` (this function's
/// only real caller) never reads either global -- it only ever calls
/// `CompiledPipeline::get_process_fn` by name -- and folding a continuous
/// assign's kernel into `plans`' own "index-aligned with the per-process
/// side-table" contract (`ProcessSideTable::canonical_process_id`'s own doc
/// comment) would mean renegotiating that contract for a second, unrelated
/// kernel category with no real consumer of its own yet.
///
/// R-run Task 10 (CG-061 reused, CG-042 untouched) addition: every
/// `SubroutineLoweringSpec` in `subroutines` is lowered into this SAME
/// shared module FIRST, before any process/continuous-assign kernel --
/// `func::lower_function_body`'s own body-lowering machinery, co-located
/// here rather than in `session.rs`'s separate per-`InstanceBody` module
/// (that pipeline is unrelated to `sv-sim run`) -- so a kernel's own
/// task/function call site (`expr.rs`'s generalized `Call` arm / `func.rs`'s
/// `lower_task_call`) always finds an already-DECLARED (and, once this
/// two-sub-pass loop finishes, DEFINED) `FunctionValue` via
/// `func::resolve_callee_fn`, never has to fall back to an `extern`
/// declaration for a subroutine this same pipeline run also owns. Every
/// subroutine is declared/defined directly under `func::
/// mangled_subroutine_name` -- the SAME name `resolve_callee_fn` derives at
/// a call site -- rather than under its plain SV name, because two
/// elaborated instances of the identical (unparameterized) module mangle to
/// the IDENTICAL name (`mangle_kernel`'s own `<param_hash>` is `0` for a
/// non-parameterized scope): deliberately DEDUPED (the `already declared`/
/// `already defined` checks below) rather than re-lowered a second time or
/// rejected as a collision, since an SV function/task has no per-instance
/// state of its own to distinguish two such calls -- lowering it twice
/// would just be redundant, not wrong, but LLVM would otherwise silently
/// rename the second `add_function` call to `<name>.1`, breaking
/// `resolve_callee_fn`'s own by-name lookup for the second instance's own
/// call sites.
///
/// Review fix (r2), Task 10 finding 1: this loop is now TWO sub-passes, not
/// one. Sub-pass 1 DECLARES every distinct mangled subroutine name (`func::
/// subroutine_fn_type` + `module.add_function`, no body) before sub-pass 2
/// lowers any body at all. Sub-pass 2 then fills each declaration in via
/// `func::lower_function_body`, reusing the EXACT `FunctionValue` sub-pass 1
/// created. Under the old single sub-pass scheme, a subroutine A's body,
/// lowered before a distinct, non-recursive callee B's own spec was reached
/// by this same loop, would forward-reference B through
/// `resolve_callee_fn`'s case 3 (a fresh, genuinely-cross-module `extern`
/// stub, since B wasn't lowered/renamed yet under either its plain or
/// mangled name) -- and when this loop later reached B's own spec, its
/// dedup check saw that mangled name already "present" (as that bodyless
/// stub) and skipped lowering B's real body for good, leaving B a dangling
/// `declare`-only function (a JIT symbol-resolution failure at `run`-time,
/// not caught by `module.verify()`, since a call to a declared-but-
/// undefined function is valid LLVM IR). Declaring every mangled name FIRST
/// means `resolve_callee_fn`'s case 2 (same shared module, by mangled name)
/// always finds B's real (eventually-defined) declaration instead, so case
/// 3's cross-module `extern` fallback is never reached for a subroutine
/// this same pipeline run owns.
pub fn build_pipeline<'d>(
    plans: &[ProcessLoweringPlan<'d>],
    cont_assigns: &[ContAssignLoweringSpec<'d>],
    subroutines: &[SubroutineLoweringSpec<'d>],
    classes: &[(sv_sim_sim::netlist::ClassTemplateId, Symbol<'d>)],
    covergroups: &[CovergroupLoweringSpec<'d>],
    design: &'d Design,
    bindings: RealBindings,
) -> Result<(CompiledPipeline, Vec<String>, Vec<String>), LoweringError> {
    let _direct = crate::accessor::DirectInlineGuard::enter(bindings.inline_ptrs.is_some());
    lower_design_module(
        plans,
        cont_assigns,
        subroutines,
        classes,
        covergroups,
        design,
        |_ctx, module, parts| {
            // The runtime symbols this run's kernels declared, with their
            // bindings (checked BEFORE the module is consumed into bitcode).
            let runtime_symbols = bindings.declared_in(&module);
            let dpi_symbols = crate::dpi::resolve_dpi_c_symbols(&parts.dpi_c_symbols)?;

            // BINDING CORRECTION 4: hand this run's finished module to the
            // production `orc::JitBackend` (never the legacy `jit::Jit`),
            // serialized to bitcode first (BINDING CORRECTION 3's "cross a
            // boundary only as bitcode" discipline; `JitBackend` requires it
            // structurally, since `add_module_from_bitcode` takes `&[u8]`).
            // Debugging aid: `SV_SIM_DUMP_IR=<path>` writes the design's LLVM
            // IR, as generated (before verification and JIT), to `<path>`.
            if let Some(path) = std::env::var_os("SV_SIM_DUMP_IR") {
                module.print_to_file(&path).map_err(|e| LoweringError {
                    message: format!("SV_SIM_DUMP_IR: {e}"),
                    at: "pipeline::build_pipeline".to_string(),
                })?;
            }
            let t_ver = crate::timing::start();
            module.verify().map_err(|e| LoweringError {
                message: format!("sv_sim_design module failed LLVM verify: {e}"),
                at: "pipeline::build_pipeline".to_string(),
            })?;
            crate::timing::end(t_ver, "module.verify", "");
            let t_bc = crate::timing::start();
            let bitcode = module.write_bitcode_to_memory().as_slice().to_vec();
            crate::timing::end(t_bc, "write bitcode", &format!("{} bytes", bitcode.len()));
            // The serialized bitcode is all the split needs: free the
            // lowered module now, or its IR (gigabytes on a UVM design)
            // stays resident through every parse and code generation below.
            drop(module);
            crate::orc::release_freed_memory();
            let t_jit = crate::timing::start();

            // `JitBackend::add_module_from_bitcode` parses the blob into its
            // OWN, freshly created `Context` (CG-064), so nothing below
            // depends on this function's `ctx`/`module` staying alive.
            let backend = JitBackend::new().map_err(|e| LoweringError {
                message: format!("failed to create JitBackend: {e}"),
                at: "pipeline::build_pipeline".to_string(),
            })?;
            for (name, addr) in runtime_symbols.iter().chain(&dpi_symbols) {
                backend.define_absolute_symbol(name, *addr)?;
            }
            backend
                .add_module_split(&bitcode)
                .map_err(|e| LoweringError::unsupported(&e.to_string(), "<jit>"))?;
            crate::timing::end(t_jit, "JIT backend setup + parallel codegen + link", "");

            Ok((
                CompiledPipeline {
                    backend,
                    fork_table: parts.fork_table,
                    fork_branches: parts.fork_branches,
                    wait_table: parts.wait_table,
                    dpi_exports: parts.dpi_exports,
                    dpi_export_variants: parts.dpi_export_variants,
                    export_tasks: parts.export_tasks,
                    assertions: parts.assertions,
                },
                parts.names,
                parts.cont_assign_names,
            ))
        },
    )
}

/// What [`lower_design_module`] hands its `finish` callback besides the
/// module: everything the lowering decided that is not in the IR itself.
pub struct LoweredParts {
    /// Each process kernel's mangled name, index-aligned with `plans`.
    pub names: Vec<String>,
    /// Each continuous assign's kernel name, index-aligned with `cont_assigns`.
    pub cont_assign_names: Vec<String>,
    pub fork_table: Vec<SpawnSpec>,
    /// `(mangled name, frame words, captures)` per fork-branch kernel.
    pub fork_branches: Vec<ForkBranch>,
    pub wait_table: Vec<WaitTableEntry>,
    pub dpi_exports: Vec<(String, String)>,
    pub dpi_export_variants: Vec<(String, String, u32)>,
    /// Every timed DPI export task, compiled as a fork-branch kernel (35.7).
    pub export_tasks: Vec<ExportTaskInfo>,
    pub assertions: Vec<crate::sva::emit::AssertionSpec>,
    /// The C symbols the design's DPI imports reference.
    pub dpi_c_symbols: Vec<String>,
    /// The runtime symbols ([`RealBindings::symbol_names`]) the lowered module
    /// calls (declared and used): what the design needs from its runtime.
    pub declared_runtime: Vec<&'static str>,
}

/// The lowering half of [`build_pipeline`], shared with the AOT path
/// ([`compile_design_to_object`]): lowers the whole design into one module and
/// hands it, still alive, to `finish`, which binds it (JIT) or writes it out
/// (AOT). One lowering, two consumers -- never a second divergent path.
#[allow(clippy::too_many_arguments)]
pub fn lower_design_module<'d, R>(
    plans: &[ProcessLoweringPlan<'d>],
    cont_assigns: &[ContAssignLoweringSpec<'d>],
    subroutines: &[SubroutineLoweringSpec<'d>],
    // Classes plan Task 5: every distinct class template reachable via a
    // `new()` site anywhere in the design (`netlist::collect_new_class_types`/
    // `assign_class_template_ids`, run ONCE by the caller -- `run.rs`/
    // `aot.rs` -- before this function, which never itself touches
    // `EvalSession`), paired with its own representative `Symbol`. Declared/
    // defined into this SAME shared module, before any process/subroutine/
    // cont-assign kernel below, exactly like `subroutines` already is -- see
    // [`build_pipeline`]'s doc comment on why every mangled name is declared
    // before any body is lowered.
    classes: &[(sv_sim_sim::netlist::ClassTemplateId, Symbol<'d>)],
    // Every covergroup of every instance (`crate::covergroup`): kernels
    // compiled after the subroutines (a kernel may call a function), and
    // the type index every `new`/method call site resolves against.
    covergroups: &[CovergroupLoweringSpec<'d>],
    // Read only by the B-runtime Task 15 DPI-export pass below (the
    // subroutine pre-pass calls `func::subroutine_fn_type`/`func::
    // lower_function_body`, neither of which takes a `&Design`).
    design: &'d Design,
    finish: impl for<'c> FnOnce(
        &'c Context,
        inkwell::module::Module<'c>,
        LoweredParts,
    ) -> Result<R, LoweringError>,
) -> Result<R, LoweringError> {
    let t_lower = crate::timing::start();
    let _abi_memo = crate::func::AbiMemoGuard::enter();
    let _uid_memo = sv_sim_sim::symid::UidMemoGuard::enter();
    let ctx = inkwell::context::Context::create();
    let module = ctx.create_module("sv_sim_design");
    let fns = declare_accessor_fns(&ctx, &module);
    // DPI import calls lowered below read their C identifiers from the
    // design's syntax and record the C symbols to bind.
    let dpi_scope = crate::dpi::DpiDesignScope::enter(design);
    // Classes plan Task 7: an explicit `super.method(...)` call (8.15) can
    // only be told apart from a bare, implicit-`this` sibling call by its
    // own source syntax (`classes::call_is_explicit_super`'s own doc
    // comment) -- held live for the same span `dpi_scope` is, since class
    // method bodies (the only place either call shape appears) are lowered
    // within that span.
    let design_syntax_scope = crate::classes::DesignSyntaxScope::enter(design);
    let _cov_scope = crate::covergroup::CovTypeScope::enter(
        covergroups
            .iter()
            .map(|c| (crate::covergroup::type_key(&c.cg), c.type_index))
            .collect(),
        crate::covergroup::block_target_names(covergroups.iter().map(|c| c.cg))?,
    );

    // Classes plan Task 5: one class sub-pass, BEFORE the subroutine
    // sub-pass below -- registers every class template's `ObjectLayout`
    // with the object heap (`crate::classes::register_template`, Task 3's
    // `objects::register_handle_fields` stub now wired to the real
    // computation) and notes its `ClassTemplateId` for `expr.rs`'s
    // `NewClass` arm to consult later in THIS SAME pass (`class_template_id_
    // of`'s own thread-local), then declares-then-defines every one of its
    // own methods and constructor (if any) under `func::
    // mangled_subroutine_name` -- the SAME two-sub-pass "declare every
    // name, then fill in every body" discipline `subroutines` below uses,
    // and for the identical reason: a method/constructor forward-
    // referencing another method of the SAME or a DIFFERENT already-
    // registered class must resolve via `cx.module.get_function`, never
    // fall through to a missing-declaration error.
    let mut method_specs: Vec<(Symbol<'d>, Symbol<'d>)> = Vec::new();
    // Class tasks that can suspend: never compiled (inlined into each
    // caller), but a virtual override of one is reached only through its
    // base's call site, so its body is a reachability root of its own
    // (LRM 8.20 and 13.4: it may call an ordinary function).
    let mut inlined_methods: Vec<Symbol<'d>> = Vec::new();
    // Classes plan Task 9: both class registries are per-compile state in
    // thread-locals keyed by specialization; a thread's earlier compile
    // must not leak into this one.
    crate::classes::reset_class_registries();
    let t_cls = crate::timing::start();
    for &(id, class_sym) in classes {
        let layout = crate::classes::register_template_in(id, class_sym, classes)?;
        let _ = layout; // consumed only for its registration side effect here.
        // A `std`-package intrinsic (`weak_reference`, ...) has no SV method
        // bodies to compile: its constructor and methods are runtime calls
        // (`classes::lower_new_weakref` / `lower_std_process_call`).
        if crate::classes::is_builtin_std_class(&class_sym).is_some() {
            continue;
        }
        let members = sv_sim_sim::netlist::classify_members(class_sym)
            .map_err(|e| LoweringError::unsupported_at(&format!("{e}"), &class_sym))?;
        if let Some(ctor) = members.ctor {
            method_specs.push((class_sym, ctor));
        }
        // Classes plan Task 6, Step 5 (8.24): a `MethodPrototype` member
        // (an `extern`-declared method) resolves to its real, out-of-block
        // implementation via `method_prototype_subroutine()` -- NOT
        // `method_prototype_first_extern_impl()`, the plan's own literal
        // text, verified live to be the WRONG accessor for this shape
        // (`classes::tests::extern_method_prototype_resolves_to_a_this_
        // bearing_subroutine`; that one is for an INTERFACE's modport-
        // implemented `extern` method, a different mechanism entirely).
        // `None` here means a genuinely unresolved prototype (a pure
        // virtual method with no implementation anywhere up to an abstract
        // class, 8.21 -- Task 7's own vtable-slot-only scope, not lowered
        // as an ordinary body at all) -- skipped, never force-lowered.
        //
        // Review fix (r1), Task 5 finding 1, narrowed by Task 6: a `static
        // function`/`static task` member still has no `this` variable
        // (8.10) after that resolution and is deliberately EXCLUDED from
        // this upfront, eager pass -- `func::resolve_callee_fn`'s own
        // lazy, call-site-driven `classes::resolve_or_lower_static_method`
        // declares/defines it ON FIRST ACTUAL CALL instead, so a static
        // method that is merely declared (and might read a not-yet-wired
        // construct, e.g. a static property -- Task 4/19's own deferred
        // codegen gap) never poisons the rest of the class's build, the
        // same "declared-but-uncalled must not poison the build" principle
        // this review fix established for instance methods.
        for m in members.methods {
            // Deliberately `if`, not a `match m.kind() { .. }` with a
            // continuing wildcard arm: this is a one-shape membership test
            // ("is this an unresolved extern prototype; if not, it is
            // already the real subroutine"), not an exhaustive
            // classification of `SymbolKind` -- `xtask lint-unimplemented`'s
            // Kind-typed-match heuristic (VF-069) cannot tell that shape
            // apart from a genuine silently-defaulted classification match
            // by syntax alone (confirmed live: this file's own first draft
            // of this exact line, written as a `match`, failed `cargo xtask
            // lint-unimplemented`'s real, full scanned scope), so this is
            // written to not be a `match` over `SymbolKind` at all -- the
            // same fix `classes.rs::is_class_field_lvalue`'s own doc
            // comment already applies to its own, identically-shaped
            // membership test.
            let m = if m.kind() == SymbolKind::MethodPrototype {
                match m.method_prototype_subroutine() {
                    Some(real) => real,
                    None => continue,
                }
            } else {
                m
            };
            if m.subroutine_this_var().is_none() {
                continue;
            }
            // A task that can suspend is never a compiled function: every
            // call to it is inlined into the calling process
            // (`process::cfg::CfgBuilder::inline_task_call`).
            if sv_sim_sim::process::cfg::subroutine_can_suspend(&m) {
                inlined_methods.push(m);
                continue;
            }
            method_specs.push((class_sym, m));
        }
    }
    // Classes plan Task 11: with every dense id noted, give each template the
    // ancestor-or-self set a class-handle `$cast` checks at run time.
    crate::classes::register_ancestor_closures(classes);
    crate::covergroup::register_derived_groups(classes);
    let _method_registry = crate::classes::register_method_names(&method_specs);
    for (_, method) in &method_specs {
        let mangled = crate::func::mangled_subroutine_name(method)?;
        if module.get_function(&mangled).is_some() {
            continue;
        }
        let (fn_ty, _is_void) = crate::classes::method_fn_type(&ctx, method, ValueRepr::FourState)?;
        module.add_function(&mangled, fn_ty, None);
    }
    // Classes plan Task 7 (§1.3 "Vtables"): every candidate concrete
    // implementation for every virtual-method slot anywhere in the design,
    // keyed for `classes::virtual_call_arms`'s own later call-site lookups
    // -- run once every method's mangled name has been DECLARED into the
    // module by the loop directly above (that is all `register_virtual_
    // impls` itself needs: `crate::func::mangled_subroutine_name` on each
    // resolved vtable slot, then a by-name lookup later at the call site),
    // and, critically, BEFORE the body-lowering loop directly below. A
    // class method/constructor's own BODY can itself contain a virtual
    // call site (the common "one object invokes a virtual method on
    // another, or on itself, from within its own method" OOP shape, 8.22);
    // that call site's `classes::virtual_call_arms` reads this registry
    // while THAT body is being lowered, so the registry must already be
    // populated before the first such body is lowered, not merely before
    // the first "process/subroutine/cont-assign kernel below" -- review
    // fix (r1), Task 7 finding 1: this call used to run AFTER the
    // body-lowering loop below, so every virtual call made from inside a
    // class method/constructor body silently resolved against an empty
    // registry (zero dispatch arms -> falls through to the merge block's
    // pre-stored default value, no error) while a virtual call from a
    // plain module-level function -- lowered later, by which point this
    // had already run -- worked. See `classes_vs_iverilog.rs`'s
    // `virtual_dispatch_from_class_method_matches_verilator_bit_for_bit`
    // and `virtual_dispatch_bare_this_from_declaring_class_matches_
    // verilator_bit_for_bit`, added for exactly this gap.
    crate::classes::register_virtual_impls(classes)?;
    crate::timing::end(
        t_cls,
        "lower: class registration",
        &format!("{} classes, {} methods", classes.len(), method_specs.len()),
    );
    let t_meth = crate::timing::start();
    for (class_sym, method) in &method_specs {
        let mangled = crate::func::mangled_subroutine_name(method)?;
        let fv = module.get_function(&mangled).ok_or_else(|| LoweringError {
            message: format!(
                "internal error: class method/constructor `{mangled}` was not pre-declared \
                 by the class sub-pass's own first sub-pass"
            ),
            at: "pipeline::build_pipeline".to_string(),
        })?;
        if fv.count_basic_blocks() > 0 {
            continue;
        }
        let t_one = crate::timing::start();
        crate::classes::lower_method_body(
            &ctx,
            &module,
            *class_sym,
            method,
            ValueRepr::FourState,
            fv,
        )?;
        crate::timing::record(t_one, &mangled, fv);
    }
    crate::timing::end(t_meth, "lower: class method bodies", "");

    // R-run Task 10: see this function's own doc comment for why every
    // subroutine is declared, THEN defined, under its mangled name before
    // any process/continuous-assign kernel below.
    //
    // Review fix (r2), Task 10 finding 1, sub-pass 1: declare every DISTINCT
    // mangled subroutine name -- no body yet -- so a forward reference from
    // ANY subroutine's body (lowered in sub-pass 2 below) always resolves to
    // one of these real, pipeline-owned declarations via `resolve_callee_fn`
    // case 2, never to a fresh, starving `extern` stub (case 3).
    // DPI exports: each exported subroutine, and everything it calls, is
    // lowered like a called one (C can reach it through its thunk).
    let mut sub_syms: Vec<Symbol<'d>> = subroutines.iter().map(|s| s.sym).collect();
    // One reachability set for every root below: each callee body is walked
    // once, not once per root (`discover_called_subroutines_seen`).
    let mut discovered = std::collections::HashSet::new();
    // A nettype resolution function is called by the simulator itself, so
    // everything it calls is lowered too (it is no process's reachability root).
    for spec in subroutines.iter().filter(|s| s.nettype_resolver) {
        if let Some(body) = sv_sim_sim::process::cfg::proc_body(&spec.sym) {
            sub_syms.extend(
                crate::module::discover_called_subroutines_seen(
                    [body.as_sem_node()],
                    &mut discovered,
                )
                .into_iter()
                .map(|d| d.sym),
            );
        }
    }
    // A virtual override is reached only through its base method's call site,
    // so no process root's walk enters its body: the ordinary subroutines it
    // calls are discovered from every class method body instead.
    for method in method_specs
        .iter()
        .map(|(_, m)| m)
        .chain(inlined_methods.iter())
    {
        if let Some(body) = sv_sim_sim::process::cfg::proc_body(method) {
            sub_syms.extend(
                crate::module::discover_called_subroutines_seen(
                    [body.as_sem_node()],
                    &mut discovered,
                )
                .into_iter()
                .map(|d| d.sym),
            );
        }
    }
    for export in design.dpi_exports() {
        let sub = export.subroutine();
        // A task that consumes time (35.7) is not a compiled function: it is
        // lowered below as a process kernel of its own. Its callees still are.
        if !sv_sim_sim::process::cfg::subroutine_can_suspend(&sub) {
            sub_syms.push(sub);
        }
        if let Some(body) = sv_sim_sim::process::cfg::proc_body(&sub) {
            sub_syms.extend(
                crate::module::discover_called_subroutines_seen(
                    [body.as_sem_node()],
                    &mut discovered,
                )
                .into_iter()
                .map(|d| d.sym),
            );
        }
    }
    for sym in &sub_syms {
        let mangled = crate::func::mangled_subroutine_name(sym)?;
        // Dedup: two elaborated instances of the identical (unparameterized)
        // module mangle to the IDENTICAL name (see this function's own doc
        // comment) -- only the first spec for a given mangled name declares
        // it here.
        if module.get_function(&mangled).is_some() {
            continue;
        }
        let (fn_ty, _is_void) =
            crate::func::subroutine_fn_type(&ctx, sym, ValueRepr::FourState, false)?;
        module.add_function(&mangled, fn_ty, None);
    }
    // Sub-pass 2: fill each declaration in with its real body, reusing the
    // EXACT `FunctionValue` sub-pass 1 declared (never a fresh
    // `add_function`) -- so every call site any OTHER subroutine's body
    // already resolved against (in this same sub-pass 2, via
    // `resolve_callee_fn` case 2) ends up calling a function that really
    // does get a body attached, not a permanently-dangling declaration.
    let t_sub = crate::timing::start();
    for sym in &sub_syms {
        let mangled = crate::func::mangled_subroutine_name(sym)?;
        // Guaranteed present: sub-pass 1 above declared every distinct
        // mangled name exactly once before this sub-pass started.
        let fv = module.get_function(&mangled).ok_or_else(|| LoweringError {
            message: format!(
                "internal error: subroutine `{mangled}` was not pre-declared \
                 by the pre-pass's own first sub-pass"
            ),
            at: "pipeline::build_pipeline".to_string(),
        })?;
        // Already defined: either a prior spec for this same mangled name
        // (the identical-unparameterized-module dedup case above), or --
        // in principle -- a body a callee's own forward reference somehow
        // already attached. Never re-lower a real definition a second time.
        if fv.count_basic_blocks() > 0 {
            continue;
        }
        let t_one = crate::timing::start();
        crate::func::lower_function_body(&ctx, &module, sym, ValueRepr::FourState, fv, None)?;
        crate::timing::record(t_one, &mangled, fv);
    }
    crate::timing::end(
        t_sub,
        "lower: subroutine bodies",
        &format!("{} subroutines", sub_syms.len()),
    );
    for spec in subroutines.iter().filter(|s| s.nettype_resolver) {
        crate::nettype::emit_resolver(&ctx, &module, &spec.sym)?;
    }

    // Covergroup kernels (`crate::covergroup`), one set per instance.
    for c in covergroups {
        crate::covergroup::compile_kernels(
            &ctx, &module, &fns, &c.signals, &c.cg, &c.prefix, &c.kernels, &c.refs,
        )?;
        crate::covergroup::compile_gates(
            &ctx, &module, &fns, &c.signals, &c.cg, &c.prefix, &c.gates,
        )?;
        crate::covergroup::compile_event_values(
            &ctx,
            &module,
            &fns,
            &c.signals,
            &c.cg,
            &c.prefix,
            &c.event_values,
        )?;
    }

    let t_kern = crate::timing::start();
    let mut names = Vec::with_capacity(plans.len());
    let mut kernel_fvs = Vec::with_capacity(plans.len());
    // PR-085: every process is compiled through the fork-aware entry point.
    // Fork-branch kernels go to their OWN table (`branch_fvs`, indexed by
    // `SpawnSpec::kernel`), never into `kernel_fvs`, so the process table and
    // side-table below stay index-aligned with `plans`. A process with no
    // fork/join site compiles exactly as `lower_kernel_fn` would.
    let mut branch_fvs = Vec::new();
    let mut fork_table = Vec::new();
    let mut branch_frames = Vec::new();
    let mut wait_table = Vec::new();
    // The compiled halves of every static concurrent assertion (T29). Before the
    // kernels: it records each assertion's attached subroutine calls (16.11) on
    // its plan, and the kernel dispatches them.
    let mut assertions = crate::sva::emit::emit_assertions(&ctx, &module, &fns, plans, design)?;
    for plan in plans {
        let fv = crate::process_lower::lower_kernel_fn_with_fork_branches(
            &ctx,
            &module,
            &fns,
            plan,
            ValueRepr::FourState,
            &mut branch_fvs,
            &mut fork_table,
            &mut branch_frames,
            &mut wait_table,
        )?;
        names.push(fv.get_name().to_str().unwrap().to_string());
        kernel_fvs.push(fv);
    }
    // LRM 35.7: each timed DPI export task, as a one-shot kernel with a frame of
    // its own, in the fork-branch table (so any process can mint it).
    let mut export_tasks: Vec<ExportTaskInfo> = Vec::new();
    for export in design.dpi_exports() {
        let sub = export.subroutine();
        if !sv_sim_sim::process::cfg::subroutine_can_suspend(&sub) {
            continue;
        }
        let body = sub.parent().ok_or_else(|| {
            LoweringError::unsupported_at("an exported subroutine outside any scope", &sub)
        })?;
        let signals = if body.kind() == SymbolKind::InstanceBody {
            crate::module::signal_slots_of(&body)?
        } else {
            HashMap::new()
        };
        let k = crate::process_lower::lower_export_task_kernel(
            &ctx,
            &module,
            &fns,
            &sub,
            signals,
            format!("sv_sim_export_task_{}", export_tasks.len()),
            ValueRepr::FourState,
            &mut branch_fvs,
            &mut fork_table,
            &mut branch_frames,
            &mut wait_table,
        )?;
        let fork_row = fork_table.len() as u32;
        fork_table.push(sv_sim_sim::sched::SpawnSpec {
            kernel: k.kernel,
            entry_pc: k.entry_pc,
            parent: 0,
            disable_name: Vec::new(),
        });
        export_tasks.push(ExportTaskInfo {
            c_name: export.c_identifier(),
            scope: body.hierarchical_path().trim_end_matches(".").to_owned(),
            kernel: k,
            fork_row,
        });
    }
    // LRM 16.11: each match-item call of a task that can suspend, as a one-shot
    // kernel of its own in the fork-branch table, which the assertion runner
    // spawns at every end point of the sequence.
    let mut spawn_kernels: Vec<(usize, u32, u32, u32, u32)> = Vec::new();
    for (ai, spec) in assertions.iter().enumerate() {
        let plan = &plans[spec.plan_index];
        let calls = plan.assertion_calls.borrow();
        for (k, site) in calls.iter().enumerate().filter(|(_, c)| c.spawns) {
            let k_out = crate::process_lower::lower_match_item_task_kernel(
                &ctx,
                &module,
                &fns,
                site,
                spec.captured.len(),
                plan.signals.clone(),
                format!("sv_sim_match_item_task_{}_{k}", spec.name),
                ValueRepr::FourState,
                &mut branch_fvs,
                &mut fork_table,
                &mut branch_frames,
                &mut wait_table,
            )?;
            spawn_kernels.push((
                ai,
                k as u32,
                k_out.kernel,
                k_out.frame_words,
                k_out.entry_pc,
            ));
        }
    }
    // One end-of-step tick guard per clocked sampled-value call site
    // (`crate::sampled`); `sv-sim-bin` finds them by `guard_name`.
    crate::sampled::emit_guards(&ctx, &module, &fns, plans, design)?;
    let mut fork_branches: Vec<ForkBranch> = branch_fvs
        .iter()
        .map(|fv| {
            (
                fv.get_name().to_str().unwrap().to_string(),
                0,
                Vec::new(),
                Vec::new(),
            )
        })
        .collect();
    for (idx, words, captures, scopes) in branch_frames {
        fork_branches[idx as usize].1 = words;
        fork_branches[idx as usize].2 = captures;
        fork_branches[idx as usize].3 = scopes;
    }
    for (ai, call, kernel, frame_words, entry_pc) in spawn_kernels {
        assertions[ai]
            .spawn_calls
            .push(crate::sva::emit::SpawnCallSpec {
                call,
                kernel: fork_branches[kernel as usize].0.clone(),
                frame_words,
                entry_pc,
            });
    }
    // PR-033: exercised for real (this run's own process table), even
    // though `CompiledPipeline::get_process_fn` is what a caller actually
    // dispatches through.
    if !kernel_fvs.is_empty() {
        emit_process_table(&ctx, &module, &kernel_fvs);
    }
    // Review fix (CG-101/102/103/104): the per-process side-table, index-
    // aligned with `plans` (this function's own "caller's elaboration-
    // derived process id order" contract, the same one `emit_process_table`
    // already relies on) -- see `side_tables_for_plans`'s own doc comment
    // for why `ProcessInstanceId(i)` is the REAL Task S5 value here, not a
    // stand-in.
    if !plans.is_empty() {
        emit_process_side_table(&ctx, &module, &side_tables_for_plans(plans));
    }
    // DPI export thunks (C -> SV), each running its exported subroutine in
    // the instance of the current `svScope`.
    // One thunk per distinct elaborated subroutine (mangled name) of each C
    // identifier; several get a dispatcher on the calling scope's instance.
    let mut dpi_exports = Vec::new();
    let mut dpi_export_variants = Vec::new();
    let mut timed_seen = 0usize;
    let mut by_c_name: std::collections::BTreeMap<String, Vec<(String, Vec<String>)>> =
        Default::default();
    for export in design.dpi_exports() {
        let sub = export.subroutine();
        let c_name = export.c_identifier();
        let timed = sv_sim_sim::process::cfg::subroutine_can_suspend(&sub);
        let mangled = if timed {
            // Every timed export is a variant of its own: its thunk names the
            // kernel (`export_tasks[k]`), which belongs to one instance.
            let k = timed_seen;
            timed_seen += 1;
            format!("<timed export task {k}>")
        } else {
            crate::func::mangled_subroutine_name(&sub)?
        };
        let body = sub.parent().ok_or_else(|| {
            LoweringError::unsupported_at("an exported subroutine outside any scope", &sub)
        })?;
        let variants = by_c_name.entry(c_name.clone()).or_default();
        let k = match variants.iter().position(|(m, _)| *m == mangled) {
            Some(k) => k,
            None => {
                let signals = if body.kind() == SymbolKind::InstanceBody {
                    crate::module::signal_slots_of(&body)?
                } else {
                    HashMap::new()
                };
                let thunk = format!(
                    "{}${}",
                    crate::dpi::dpi_export_thunk_name(&c_name),
                    variants.len()
                );
                if timed {
                    let k = timed_seen - 1;
                    crate::dpi::lower_dpi_export_task_thunk(
                        &ctx,
                        &module,
                        &export,
                        export_tasks[k].fork_row,
                        &export_tasks[k].kernel,
                        &thunk,
                    )?;
                } else {
                    crate::dpi::lower_dpi_export_thunk(
                        &ctx, &module, &fns, &export, &signals, &thunk,
                    )?;
                }
                variants.push((mangled, Vec::new()));
                variants.len() - 1
            }
        };
        let scope = body.hierarchical_path().trim_end_matches(".").to_owned();
        variants[k].1.push(scope.clone());
        dpi_export_variants.push((c_name, scope, k as u32));
    }
    for (c_name, variants) in &by_c_name {
        let thunks: Vec<String> = (0..variants.len())
            .map(|k| format!("{}${k}", crate::dpi::dpi_export_thunk_name(c_name)))
            .collect();
        crate::dpi::lower_dpi_export_dispatcher(&ctx, &module, c_name, &thunks)?;
        dpi_exports.push((c_name.clone(), crate::dpi::dpi_export_thunk_name(c_name)));
    }

    // R-run Task 2 (NL-034): every continuous assign's kernel, lowered
    // directly (see `lower_cont_assign_kernel_fn`'s own doc comment for why
    // this is not `lower_kernel_fn`/`ProcessLoweringPlan`-shaped) into the
    // SAME module -- see this function's own doc comment for why these
    // names are returned separately rather than merged into `names`/
    // `kernel_fvs` above.
    let mut cont_assign_names = Vec::with_capacity(cont_assigns.len());
    for spec in cont_assigns {
        let fv = lower_cont_assign_kernel_fn(&ctx, &module, &fns, spec)?;
        cont_assign_names.push(fv.get_name().to_str().unwrap().to_string());
    }

    crate::timing::end(
        t_kern,
        "lower: kernels (processes, assertions, DPI, cont-assigns)",
        &format!(
            "{} processes, {} cont-assigns",
            plans.len(),
            cont_assigns.len()
        ),
    );
    let dpi_c_symbols = dpi_scope.c_symbols();
    drop(dpi_scope);
    drop(design_syntax_scope);
    let declared_runtime: Vec<&'static str> = RealBindings::symbol_names()
        .into_iter()
        .filter(|name| {
            module.get_function(name).is_some_and(|f| {
                inkwell::values::BasicValue::get_first_use(&f.as_global_value().as_pointer_value())
                    .is_some()
            })
        })
        .collect();

    crate::timing::end(t_lower, "lower: total (all of lower_design_module)", "");
    crate::timing::report_module(&module);
    finish(
        &ctx,
        module,
        LoweredParts {
            names,
            cont_assign_names,
            fork_table,
            fork_branches,
            wait_table,
            dpi_exports,
            dpi_export_variants,
            export_tasks,
            assertions,
            dpi_c_symbols,
            declared_runtime,
        },
    )
}

/// Task 4 (A2-part2; ledger CG-127): the AOT counterpart of
/// [`build_pipeline`] -- lowers every plan in `plans` into ONE shared LLVM
/// module exactly as `build_pipeline` does (same `declare_accessor_fns`/
/// `lower_kernel_fn`/`emit_process_table` sequence -- never a second,
/// divergent lowering path), additionally emits the real `sim_process_count`
/// entry point (`crate::aot::emit_process_count_fn`, this task's own
/// addition), and writes the whole module to `out_obj` via
/// [`AotBackend::emit_object`] -- never exposing `Context`/`Module` to its
/// own caller (AB-024; mirrors `build_pipeline`'s "owns `inkwell` internally"
/// contract exactly, which is why `sv-sim-bin` can call this function without
/// ever depending on `inkwell` itself).
///
/// Unlike `build_pipeline`, this function needs no `'static`-lifetime-erasing
/// `transmute` trick: nothing here needs to keep the `Context`/`Module` alive
/// past this call (there is no `ExecutionEngine` retaining JIT-compiled code
/// that must outlive it) -- `ctx`/`module` are simply dropped once
/// `emit_object` has written `out_obj` to disk.
///
/// Returns each kernel's own mangled name (index-aligned with `plans`, same
/// as `build_pipeline`) plus the total process count baked into the emitted
/// `sim_process_count` function.
pub fn compile_to_object<'d>(
    plans: &[ProcessLoweringPlan<'d>],
    out_obj: &Path,
) -> Result<(Vec<String>, u32), CodegenError> {
    // A sampled value call's history is advanced by `sv-sim run`'s
    // end-of-step hook, which an AOT object does not have.
    if crate::sampled::plans_use_sampled_values(plans) {
        return Err(LoweringError::unsupported(
            "sampled value functions ($sampled/$rose/$fell/$stable/$changed/$past and the \
             *_gclk family) are not supported in AOT output; run the design with `sv-sim run`",
            "pipeline::compile_to_object",
        )
        .into());
    }
    crate::sva::emit::reject_static_assertions(plans, "pipeline::compile_to_object")?;
    let ctx = Context::create();
    let module = ctx.create_module("sv_sim_design");
    let fns = declare_accessor_fns(&ctx, &module);

    let mut names = Vec::with_capacity(plans.len());
    let mut kernel_fvs = Vec::with_capacity(plans.len());
    for plan in plans {
        let fv = lower_kernel_fn(&ctx, &module, &fns, plan)?;
        names.push(fv.get_name().to_str().unwrap().to_string());
        kernel_fvs.push(fv);
    }
    if !kernel_fvs.is_empty() {
        emit_process_table(&ctx, &module, &kernel_fvs);
    }
    if !plans.is_empty() {
        emit_process_side_table(&ctx, &module, &side_tables_for_plans(plans));
    }
    let count = kernel_fvs.len() as u32;
    emit_process_count_fn(&ctx, &module, count);

    AotBackend::for_host()?.emit_object(&module, out_obj)?;
    Ok((names, count))
}

/// The AOT counterpart of [`build_pipeline`] for a whole design: the SAME
/// [`lower_design_module`] lowering, then -- instead of binding the module to a
/// JIT -- embeds a [`sv_sim_sim::image::DesignImage`] in it and writes the
/// object to `out_obj`.
///
/// `base` carries what the planner knows (templates, instances, foreign slots,
/// X windows, tick exponent); `fill` runs once lowering has named every kernel
/// and adds the kernel table (interning each kernel's name via
/// `DesignImage::intern`). Fork-branch kernels, the fork table and the wait
/// table come from the lowering itself and are added here.
///
/// The object also defines `sim_process_count`, the image accessors
/// (`sv_sim_design_image_ptr/_len`), `SV_SIM_SYMBOL_TABLE` (one function
/// pointer per image symbol, index-aligned) and a load-time constructor that
/// hands them to `sv_sim_aot_register`. `with_main` (`build-aot --exe`) also
/// adds a real C `main` forwarding to `sv_sim_aot_main`
/// ([`crate::aot::emit_main_fn`]), so the SAME object a `.so` build would
/// produce can instead be linked as a standalone executable
/// ([`crate::aot::AotBackend::link_exe`]) -- never a second lowering path.
#[allow(clippy::too_many_arguments)]
pub fn compile_design_to_object<'d>(
    plans: &[ProcessLoweringPlan<'d>],
    cont_assigns: &[ContAssignLoweringSpec<'d>],
    subroutines: &[SubroutineLoweringSpec<'d>],
    classes: &[(sv_sim_sim::netlist::ClassTemplateId, Symbol<'d>)],
    covergroups: &[CovergroupLoweringSpec<'d>],
    design: &'d Design,
    base: sv_sim_sim::image::DesignImage,
    fill: impl FnOnce(&mut sv_sim_sim::image::DesignImage, &LoweredParts) -> Result<(), LoweringError>,
    with_main: bool,
    out_obj: &Path,
) -> Result<sv_sim_sim::image::DesignImage, CodegenError> {
    // A sampled value call's history and a concurrent assertion's engine run
    // from the image's verification section (`sv_sim_exec::verif`), so neither
    // is refused here (the single-module `compile_to_object` has no image and
    // still refuses both).
    let result: Result<sv_sim_sim::image::DesignImage, CodegenError> = lower_design_module(
        plans,
        cont_assigns,
        subroutines,
        classes,
        covergroups,
        design,
        |ctx, module, parts| {
            let mut image = base;
            fill(&mut image, &parts)?;
            image.fork_table = parts.fork_table.clone();
            image.wait_table = parts.wait_table.clone();
            for (name, frame_words, captures, disable_scopes) in &parts.fork_branches {
                let symbol = image.intern(name);
                image
                    .fork_branches
                    .push(sv_sim_sim::image::ForkBranchImage {
                        symbol,
                        frame_words: *frame_words,
                        captures: captures.clone(),
                        disable_scopes: disable_scopes.clone(),
                    });
            }
            let module = &module;
            emit_process_count_fn(ctx, module, parts.names.len() as u32);
            let bytes = image.encode();
            crate::aot::emit_image_globals(ctx, module, &bytes, &image.symbols)?;
            if with_main {
                crate::aot::emit_main_fn(ctx, module);
            }
            if let Some(path) = std::env::var_os("SV_SIM_DUMP_IR") {
                module.print_to_file(&path).map_err(|e| LoweringError {
                    message: format!("SV_SIM_DUMP_IR: {e}"),
                    at: "pipeline::compile_design_to_object".to_string(),
                })?;
            }
            module.verify().map_err(|e| LoweringError {
                message: format!("sv_sim_design module failed LLVM verify: {e}"),
                at: "pipeline::compile_design_to_object".to_string(),
            })?;
            Ok(AotBackend::for_host()
                .and_then(|b| b.emit_object(module, out_obj))
                .map(|()| image))
        },
    )?;
    result
}

/// Review fix (Task 9, CG-101 r2): assigns one [`ProcessInstanceId`] per
/// DISTINCT `netlist::InstanceId` appearing in `owning_instances`, via the
/// real [`assign_process_instance_ids`] (Task S5's own single source of
/// truth -- this is its first non-test caller in the whole tree), then
/// returns that id index-aligned with `owning_instances` itself (so two
/// entries sharing an owning instance always get the SAME
/// `ProcessInstanceId` back, never independently-derived values).
///
/// **The per-instance order handed to `assign_process_instance_ids` is each
/// instance's own first-appearance position in `owning_instances` --
/// deliberately NOT a second, independent walk of the design:**
/// `assign_process_instance_ids`'s own contract is "assigns
/// `ProcessInstanceId(0), ProcessInstanceId(1), ...` following input
/// order", where `order` is meant to be `NetlistView::registration_order()`.
/// Every real caller of this function builds its `plans`/`keyed_plans` list
/// by iterating `registration_order()` in an OUTER loop and that instance's
/// own processes in an INNER loop (`sv-sim-bin::run::run_design`'s own
/// nested loop, `build_aot_so`'s single-instance case) -- so a given
/// instance's first appearance in `owning_instances` always lands at
/// exactly the position `registration_order()` itself would put it at. This
/// reads that order back out of the already-real input rather than
/// re-deriving it, the same "consume, don't re-derive" discipline
/// `assign_process_instance_ids`'s own doc comment requires of ITS callers.
fn canonical_ids_for(owning_instances: &[InstanceId]) -> Vec<ProcessInstanceId> {
    let mut order: Vec<InstanceId> = Vec::new();
    let mut seen: std::collections::HashSet<InstanceId> = std::collections::HashSet::new();
    for &id in owning_instances {
        if seen.insert(id) {
            order.push(id);
        }
    }
    let ids = assign_process_instance_ids(&order);
    owning_instances.iter().map(|id| ids[id]).collect()
}

/// Review fix (Task 9, CG-101 r2; previously CG-101/102/103/104): builds one
/// [`crate::process_lower::ProcessSideTable`] per entry of `plans`,
/// index-aligned with it. `canonical_process_id` is derived by
/// [`canonical_ids_for`] from each plan's own [`ProcessLoweringPlan::
/// owning_instance`] -- **never** a raw per-plan-index `ProcessInstanceId`
/// (that was CG-101's own bug: `plans` is one entry per PROCESS, flattened
/// across every instance, so a per-plan index gives two processes of the
/// SAME instance two DIFFERENT ids, violating `ProcessSideTable::
/// canonical_process_id`'s own "never a second, independently-derived
/// identity" contract).
fn side_tables_for_plans<'d>(
    plans: &[ProcessLoweringPlan<'d>],
) -> Vec<crate::process_lower::ProcessSideTable> {
    let owning: Vec<InstanceId> = plans.iter().map(|p| p.owning_instance).collect();
    let canonical_ids = canonical_ids_for(&owning);
    plans
        .iter()
        .zip(canonical_ids)
        .map(|(plan, canonical_id)| build_process_side_table(plan, canonical_id))
        .collect()
}

/// CG-009 (A2-part2 Task 0): one DPI-import "thunk stub" -- a bare
/// placeholder record naming a DPI import this compilation unit's design
/// references, deliberately NOT a real C-ABI marshaling thunk. Full DPI
/// import/export marshaling (`docs/design/codegen.md` §7's byte-width/
/// pointer-class table, and its own named, still-open "DPI export thunks
/// unimplemented for packed args >32 bits and pointer returns" gap) and the
/// rollback-safety question ARCHITECTURE.md's own "DPI under speculation"
/// risk names are both explicitly out of this task's scope -- this exists
/// only so [`compile_design_kernels`]'s contract ("one kernel module plus
/// DPI thunk stubs per compilation unit") has something concrete to return
/// and count.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct DpiThunkStub {
    pub import_name: String,
}

/// Walks every top instance's own body members for a `Subroutine` symbol
/// carrying `MethodFlags::DPI_IMPORT` (`docs/design/codegen.md`'s own
/// documented frontend surface: "SubroutineSymbol formal arguments +
/// MethodFlags::{DPI_IMPORT,DPI_CONTEXT}") and returns one [`DpiThunkStub`]
/// per unique import name -- `Vec::new()` for a design with no DPI imports
/// at all (CG-009's own explicit negative case).
///
/// **Verified against pinned `sv-lang = "=0.1.9"`:** a free (non-class-
/// method) `Subroutine` symbol's DPI-import bit lives on
/// `Symbol::subroutine_flags()`, not `Symbol::method_prototype_flags()`
/// (that accessor is for interface-class method *prototypes* specifically
/// and reads back `MethodFlags::NONE` for a module-scope DPI import) --
/// checked empirically: `import "DPI-C" function int f(...);` inside a
/// module reports `subroutine_flags() == MethodFlags::DPI_IMPORT` and
/// `method_prototype_flags() == MethodFlags::NONE`.
pub fn dpi_thunk_stubs_for_design(design: &Design) -> Vec<DpiThunkStub> {
    let mut seen = std::collections::HashSet::new();
    let mut stubs = Vec::new();
    for inst in design.top_instances() {
        let Some(body) = inst.instance_body() else {
            continue;
        };
        for sym in sv_sim_sim::netlist::module_items(&body) {
            if sym.kind() != SymbolKind::Subroutine {
                continue;
            }
            if !sym.subroutine_flags().contains(MethodFlags::DPI_IMPORT) {
                continue;
            }
            let name = sym.name().to_string();
            if seen.insert(name.clone()) {
                stubs.push(DpiThunkStub { import_name: name });
            }
        }
    }
    stubs
}

/// CG-009's own public entry point: takes a per-plan [`ProcessTemplateKey`]
/// dedup key (`sv-sim-sim::process::dedup`, Task S5) alongside each
/// [`ProcessLoweringPlan`], plus one [`ValueRepr`] applied to the whole
/// compilation unit, and emits exactly one lowered kernel per UNIQUE key --
/// a second `keyed_plans` entry sharing an already-seen key reuses the first
/// entry's own lowered name in the returned `Vec<String>` (index-aligned
/// with `keyed_plans`) rather than lowering/emitting a second LLVM function
/// (PR-030's "two instances of the same key share one compiled kernel"
/// claim, exercised here at codegen's own public boundary). Also returns
/// [`dpi_thunk_stubs_for_design`]'s own stub list for `design`. Reuses
/// [`build_pipeline`]'s real lowering/JIT/binding machinery unchanged (the
/// same verify -> serialize-to-bitcode -> drop `ctx`/`module` -> create
/// `orc::JitBackend` -> bind -> `add_module_from_bitcode` sequence, ported
/// onto ORC at the wave-B integration merge -- see this file's own module
/// doc comment), via [`lower_kernel_fn_with_repr`] in place of
/// [`build_pipeline`]'s `lower_kernel_fn` call.
pub fn compile_design_kernels<'d>(
    design: &Design,
    keyed_plans: &[(ProcessTemplateKey, ProcessLoweringPlan<'d>)],
    value_repr: ValueRepr,
    bindings: RealBindings,
) -> Result<(CompiledPipeline, Vec<String>, Vec<DpiThunkStub>), LoweringError> {
    for (_, plan) in keyed_plans {
        crate::sva::emit::reject_static_assertions(
            std::slice::from_ref(plan),
            "pipeline::compile_design_kernels",
        )?;
    }
    let ctx = Context::create();
    let module = ctx.create_module("sv_sim_design");
    let fns = declare_accessor_fns(&ctx, &module);
    let dpi_scope = crate::dpi::DpiDesignScope::enter(design);

    let mut names: Vec<String> = Vec::with_capacity(keyed_plans.len());
    let mut kernel_fvs = Vec::new();
    let mut seen: std::collections::HashMap<ProcessTemplateKey, String> =
        std::collections::HashMap::new();
    for (key, plan) in keyed_plans {
        if let Some(existing_name) = seen.get(key) {
            names.push(existing_name.clone());
            continue;
        }
        let fv = lower_kernel_fn_with_repr(&ctx, &module, &fns, plan, value_repr)?;
        let name = fv.get_name().to_str().unwrap().to_string();
        seen.insert(key.clone(), name.clone());
        names.push(name);
        kernel_fvs.push(fv);
    }
    if !kernel_fvs.is_empty() {
        emit_process_table(&ctx, &module, &kernel_fvs);
    }
    // Review fix (Task 9, CG-101 r2; previously CG-101/102/103/104): one
    // side-table row per REAL process instance, `keyed_plans`' own order --
    // deliberately NOT `kernel_fvs` (which is deduped to one entry per
    // unique `ProcessTemplateKey`, PR-030 -- two instances of the same
    // template still each get their own `canonical_process_id`/write-set row
    // here, even though they share one compiled kernel function).
    // `canonical_process_id` comes from `canonical_ids_for`, grouped by each
    // plan's own `owning_instance` -- never a raw per-`keyed_plans`-index
    // `ProcessInstanceId(i)` (the same CG-101 bug `side_tables_for_plans` had:
    // two plans of the SAME owning instance must share one id).
    if !keyed_plans.is_empty() {
        let owning: Vec<InstanceId> = keyed_plans
            .iter()
            .map(|(_, plan)| plan.owning_instance)
            .collect();
        let canonical_ids = canonical_ids_for(&owning);
        let tables: Vec<crate::process_lower::ProcessSideTable> = keyed_plans
            .iter()
            .zip(canonical_ids)
            .map(|((_, plan), canonical_id)| build_process_side_table(plan, canonical_id))
            .collect();
        emit_process_side_table(&ctx, &module, &tables);
    }

    // The runtime symbols this run's kernels declared, with their bindings
    // (checked BEFORE the module is consumed into bitcode below).
    let runtime_symbols = bindings.declared_in(&module);
    let dpi_symbols = crate::dpi::resolve_dpi_c_symbols(&dpi_scope.c_symbols())?;
    drop(dpi_scope);

    // BINDING CORRECTION 4: the production `orc::JitBackend`, never the
    // legacy `jit::Jit` -- serialize to bitcode first (BINDING CORRECTION 3).
    module.verify().map_err(|e| LoweringError {
        message: format!("sv_sim_design module failed LLVM verify: {e}"),
        at: "pipeline::compile_design_kernels".to_string(),
    })?;
    let bitcode = module.write_bitcode_to_memory().as_slice().to_vec();
    drop(module);
    drop(ctx);
    crate::orc::release_freed_memory();

    let backend = JitBackend::new().map_err(|e| LoweringError {
        message: format!("failed to create JitBackend: {e}"),
        at: "pipeline::compile_design_kernels".to_string(),
    })?;
    for (name, addr) in runtime_symbols.iter().chain(&dpi_symbols) {
        backend.define_absolute_symbol(name, *addr)?;
    }

    backend
        .add_module_split(&bitcode)
        .map_err(|e| LoweringError::unsupported(&e.to_string(), "<jit>"))?;

    let stubs = dpi_thunk_stubs_for_design(design);
    Ok((
        CompiledPipeline {
            backend,
            fork_table: Vec::new(),
            fork_branches: Vec::new(),
            wait_table: Vec::new(),
            dpi_exports: Vec::new(),
            dpi_export_variants: Vec::new(),
            export_tasks: Vec::new(),
            assertions: Vec::new(),
        },
        names,
        stubs,
    ))
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::collections::HashMap as StdHashMap;
    use std::sync::atomic::{AtomicU32, Ordering};
    use sv_sim_sim::symid::SymbolUid;

    use sv_lang::kinds::SymbolKind;
    use sv_sim_sim::netlist::InstanceId;
    use sv_sim_sim::process::cfg::{ProcessLoopKind, build_cfg, lower_to_segments};
    use sv_sim_sim::process::liveness::compute_liveness;
    use sv_sim_sim::sched::{CompiledKernelProcess, CompiledProcess, ResumeArg, Suspend};

    use crate::frontend::compile_source;
    use crate::module::{SliceProcKind, build_comb_sensitivity_index, discover_processes};
    use crate::process_lower::{
        SignalSlot, SignalSlotClass, build_lowering_plan, find_named_value_symbol,
    };

    /// Records the last value `stub_set_scalar` was called with, so the
    /// test can verify a REAL execution round-trip (not merely that a
    /// lookup succeeded) -- `AtomicU32` rather than a wider type is enough
    /// since the design under test only ever assigns 1-bit `q`.
    static LAST_SET_SCALAR_VALUE: AtomicU32 = AtomicU32::new(u32::MAX);

    extern "C" fn stub_get_scalar(_h: sv_sim_abi::SimHandle, _slot: sv_sim_abi::SlotId) -> u128 {
        0
    }
    extern "C" fn stub_set_scalar(
        _h: sv_sim_abi::SimHandle,
        _slot: sv_sim_abi::SlotId,
        value: u128,
    ) {
        LAST_SET_SCALAR_VALUE.store(value as u32, Ordering::SeqCst);
    }

    /// `CompiledKernelProcess::resume` never calls into `ops` for this
    /// one-shot, no-suspend design, so a minimal no-op `SchedulerOps` is
    /// enough to drive it.
    struct NoOpSchedulerOps;
    impl sv_sim_sim::sched::SchedulerOps for NoOpSchedulerOps {
        fn now(&self) -> sv_sim_sim::sched::SchedTime {
            sv_sim_sim::sched::SchedTime { ticks: 0 }
        }
        fn current_region(&self) -> sv_sim_abi::Region {
            sv_sim_abi::Region::Active
        }
        fn stage_nba(
            &self,
            _cell: sv_sim_sim::state::StateCellId,
            _value: sv_sim_sim::state::FourStateValue,
            _source: u32,
        ) {
        }
        fn commit_blocking_write(
            &self,
            _cell: sv_sim_sim::state::StateCellId,
            _value: sv_sim_sim::state::FourStateValue,
        ) {
        }
        fn request_finish(&self, _code: i32) {}
        fn defer_io(
            &self,
            _at: sv_sim_sim::sched::SchedTime,
            _region: sv_sim_abi::Region,
            _cb: sv_sim_sim::sched::DeferredIoCallback,
        ) {
        }
        fn register_region_callback(
            &self,
            _region: sv_sim_abi::Region,
            _at: sv_sim_sim::sched::SchedTime,
            _cb: Box<dyn sv_sim_sim::sched::RegionCallback>,
        ) {
        }
    }

    /// Review fix (r1), Task 24 finding 1's own regression test: proves
    /// `build_pipeline` genuinely runs through the production
    /// `orc::JitBackend` (BINDING CORRECTION 4's migration requirement), not
    /// merely that a symbol lookup returns `Some`. Before the fix,
    /// `build_pipeline` still built the legacy `jit::Jit`/`ExecutionEngine`,
    /// whose lazy per-call symbol resolution tolerated the accessor
    /// functions `declare_accessor_fns` unconditionally declares staying
    /// unbound as long as the kernel was never actually *executed*; ORC v2's
    /// `LLJIT` links a whole module (and every external symbol it
    /// references) eagerly at first materialization, so this test both
    /// requires real `RealBindings` for `sv_get_scalar`/`sv_set_scalar` (as
    /// `sv-sim-bin::run` itself always supplies, per `run.rs`) and, unlike
    /// the pre-fix version of this test, actually INVOKES the returned
    /// kernel through `CompiledKernelProcess` and asserts on the value the
    /// stub accessor observed -- a build still using the legacy path, or an
    /// `orc::JitBackend` migration that silently dropped
    /// `define_absolute_symbol` binding, would fail this test (a dangling
    /// external-symbol link error or a kernel that never actually calls the
    /// bound `stub_set_scalar`), not merely leave a lookup returning `None`.
    #[test]
    fn build_pipeline_produces_a_callable_kernel_via_get_process_fn() {
        let design =
            compile_source("module m(output logic q); initial q = 1; endmodule\n").unwrap();
        let body = design
            .top_instances()
            .next()
            .unwrap()
            .instance_body()
            .unwrap();
        let proc_sym = body
            .members()
            .find(|s| s.kind() == SymbolKind::ProceduralBlock)
            .unwrap();
        let root = sv_sim_sim::process::cfg::proc_body(&proc_sym).unwrap();
        let cfg = build_cfg(&root, ProcessLoopKind::OneShot).unwrap();
        let frame = compute_liveness(&cfg).unwrap();
        let segments = lower_to_segments(&cfg, &frame);
        let q_sym = find_named_value_symbol(&segments, "q").unwrap();
        let mut signals: StdHashMap<sv_sim_sim::symid::SymbolId, SignalSlot> = StdHashMap::new();
        signals.insert(
            q_sym.uid(),
            SignalSlot {
                slot: 0,
                width: 1,
                signed: false,
                class: SignalSlotClass::Inline,
            },
        );
        let plan = build_lowering_plan(
            "proc_pipeline".to_string(),
            proc_sym,
            segments,
            frame,
            signals,
        );

        let bindings = RealBindings {
            get_scalar: Some(stub_get_scalar as *const () as usize),
            set_scalar: Some(stub_set_scalar as *const () as usize),
            ..RealBindings::default()
        };
        let (pipeline, names, cont_assign_names) =
            build_pipeline(&[plan], &[], &[], &[], &[], &design, bindings).unwrap();
        assert!(
            cont_assign_names.is_empty(),
            "no `ContAssignLoweringSpec` was passed, so no continuous-assign kernel name should \
             come back"
        );
        assert_eq!(names.len(), 1);
        let kernel = pipeline
            .get_process_fn(&names[0])
            .expect("the kernel this pipeline just lowered must be retrievable by its own name");
        assert!(pipeline.get_process_fn("not_a_real_name").is_none());

        // Actually run it -- proves the returned pointer is not merely
        // resolvable but genuinely callable machine code that reaches the
        // real, bound `stub_set_scalar` through the compiled accessor call.
        let mut proc =
            CompiledKernelProcess::new(kernel, 0, sv_sim_abi::SimHandle(std::ptr::null_mut()));
        let ops = NoOpSchedulerOps;
        let suspend = proc.resume(
            sv_sim_abi::SimHandle(std::ptr::null_mut()),
            ResumeArg::Start,
            &ops,
        );
        assert!(
            matches!(suspend, Suspend::Done),
            "the real kernel must run to completion, got {suspend:?}"
        );
        assert_eq!(
            LAST_SET_SCALAR_VALUE.load(Ordering::SeqCst),
            1,
            "the kernel's `initial q = 1;` must reach the real, bound stub_set_scalar with value 1"
        );
    }

    /// B-runtime Task 15 (RT-007, "the missing pipeline wiring"): the
    /// plan's own pipeline-wiring end-to-end proof -- a design with an
    /// `export "DPI-C"` function, compiled through THIS function (the real
    /// production entry point `sv-sim-bin::run.rs` itself calls), must
    /// expose a genuinely callable native-ABI thunk. Before this task,
    /// `build_pipeline` never called `crate::dpi::lower_all_dpi_exports` at
    /// all, so no real compiled design emitted a DPI export thunk regardless
    /// of `lower_dpi_export`'s own (already correct, already tested)
    /// per-class marshaling -- this test fails on that old code (the lookup
    /// below returns `None`, `expect` panics) and passes once `build_pipeline`
    /// lowers the export into its own module.
    ///
    /// Looks the thunk up with the SAME `JitBackend::get_fn` mechanism
    /// `CompiledPipeline::get_process_fn` already uses for kernel functions
    /// (mangled-name lookup), but with the thunk's own real native DPI-C ABI
    /// type (`extern "C" fn(i32, i32) -> i32` -- two by-value `int`
    /// arguments, `int` return, per `DpiParamClass::ByValueNarrow(32)`,
    /// CG-047) rather than `sv_sim_abi::ProcessFn` -- `c_add`'s thunk is not
    /// a process kernel and was never lowered as one. `CompiledPipeline`'s
    /// `backend` field is private to this module but visible from this
    /// child `tests` module, exactly like every other white-box test in this
    /// file.
    #[test]
    fn build_pipeline_lowers_a_real_dpi_export_thunk_callable_by_its_native_c_abi() {
        let design = compile_source(
            "module m;\n\
             function automatic int add(int a, int b);\n\
               return a + b;\n\
             endfunction\n\
             export \"DPI-C\" c_add = function add;\n\
             endmodule\n",
        )
        .unwrap();
        assert!(!design.diagnostics().has_errors());

        // No processes at all in this design -- `build_pipeline` must still
        // lower the export thunk into its module even with an empty `plans`
        // list (a design consisting of nothing but a DPI export/function
        // pair, e.g. a pure marshaling utility module, is a legitimate real
        // input).
        // `add` is automatic, so it touches no module signal (a static
        // function's formals would be the instance's) and its instance
        // handle is unused; any non-null one serves.
        extern "C" fn export_handle(_name: *const u8) -> *mut u8 {
            std::ptr::NonNull::dangling().as_ptr()
        }
        let bindings = RealBindings {
            dpi_export_handle: Some(export_handle as *const () as usize),
            ..RealBindings::default()
        };
        let (pipeline, names, _cont_assign_names) =
            build_pipeline(&[], &[], &[], &[], &[], &design, bindings).unwrap();
        assert!(
            names.is_empty(),
            "this design has no processes, so no kernel names are expected"
        );
        assert_eq!(
            pipeline.dpi_export_thunks().unwrap().len(),
            1,
            "one thunk for c_add"
        );

        // SAFETY: the thunk of `int add(int a, int b)` has the C ABI
        // `int (int, int)` (`crate::dpi::DpiCType`).
        let c_add: unsafe extern "C" fn(i32, i32) -> i32 = unsafe {
            pipeline
                .backend
                .get_fn(&crate::dpi::dpi_export_thunk_name("c_add"))
        }
        .expect("build_pipeline must have lowered and JIT-compiled the c_add DPI export thunk");
        // SAFETY: `c_add`'s signature was just asserted above to match its
        // real compiled type.
        let got = unsafe { c_add(3, 4) };
        assert_eq!(
            got, 7,
            "the real, pipeline-lowered DPI export thunk must be callable from outside SV and \
             correctly re-enter the kernel (RT-007's own literal acceptance wording)"
        );
    }

    /// Review fix (Task 9, CG-101 r2): reproduces the reviewer's exact
    /// counter.sv-shaped repro through the REAL production function
    /// `side_tables_for_plans` (the one `build_pipeline`/`compile_to_object`
    /// actually call), never `build_process_side_table` directly -- every
    /// pre-existing `crates/sv-sim-codegen/tests/side_table.rs` test calls
    /// `build_process_side_table` with a `canonical_process_id` the test
    /// harness itself already made consistent, bypassing this exact
    /// production derivation bug entirely. One elaborated instance
    /// (`InstanceId(9)`, shared by both plans below, exactly as
    /// `sv-sim-bin::run::run_design`'s nested loop shares one instance's
    /// `id` across every process it discovers from that instance's body),
    /// two processes (`initial` + `always_ff`, counter.sv's own fixture
    /// shape). Before this fix, `side_tables_for_plans` assigned
    /// `ProcessInstanceId(i)` off the flattened plan index, so this failed
    /// with `canonical_process_id == [0, 1]` instead of `[N, N]`.
    #[test]
    fn side_tables_for_plans_shares_one_canonical_id_per_owning_instance() {
        let src = std::fs::read_to_string(
            std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
                .join("../sv-sim-bin/tests/fixtures/counter.sv"),
        )
        .unwrap();
        let design = compile_source(&src).unwrap();
        let body = design
            .top_instances()
            .next()
            .unwrap()
            .instance_body()
            .unwrap();
        let comb_sensitivity = build_comb_sensitivity_index(&design).unwrap();
        let processes = discover_processes(&body, &comb_sensitivity).unwrap();
        assert_eq!(
            processes.len(),
            2,
            "counter.sv is documented as exactly 2 processes"
        );

        let owning_instance = InstanceId(9);
        let plans: Vec<_> = processes
            .into_iter()
            .enumerate()
            .map(|(i, proc)| {
                let root = sv_sim_sim::process::cfg::proc_body(&proc.sym).unwrap();
                // Exhaustive over `SliceProcKind` (a plain, non-`#[non_exhaustive]`
                // enum this crate owns, unlike the `sv-lang-kinds` AST `Kind`
                // enums) -- no wildcard arm, matching `frontend.rs::loop_kind_of`'s
                // own established mapping exactly, never a second, divergent one.
                let loop_kind = match proc.kind {
                    SliceProcKind::Initial
                    | SliceProcKind::AlwaysComb
                    | SliceProcKind::AlwaysLatch
                    | SliceProcKind::Final
                    | SliceProcKind::StaticAssertion => ProcessLoopKind::OneShot,
                    SliceProcKind::Always | SliceProcKind::AlwaysFF => ProcessLoopKind::Looping,
                };
                let cfg = build_cfg(&root, loop_kind).unwrap();
                let frame = compute_liveness(&cfg).unwrap();
                let segments = lower_to_segments(&cfg, &frame);
                let mut plan = build_lowering_plan(
                    format!("proc_{i}"),
                    proc.sym,
                    segments,
                    frame,
                    StdHashMap::new(),
                );
                // Both of counter.sv's processes belong to the SAME (this
                // fixture's only) elaborated instance -- exactly the
                // invariant `sv-sim-bin::run::run_design` upholds in
                // production by setting `plan.owning_instance = id` from
                // its own outer, per-instance loop.
                plan.owning_instance = owning_instance;
                plan
            })
            .collect();

        let tables = side_tables_for_plans(&plans);
        assert_eq!(tables.len(), 2);
        assert_eq!(
            tables[0].canonical_process_id, tables[1].canonical_process_id,
            "both of counter.sv's processes share ONE owning elaborated instance, so \
             side_tables_for_plans must give them the SAME canonical_process_id -- never \
             a raw per-plan index"
        );
    }

    /// Companion to the above, for `compile_design_kernels`'s own inline
    /// side-table construction (the `keyed_plans` path, PR-030's dedup):
    /// two `keyed_plans` entries sharing one `owning_instance` (even with
    /// DIFFERENT `ProcessTemplateKey`s, so neither is deduped away into the
    /// other's compiled kernel) must still get the SAME
    /// `canonical_process_id` via [`canonical_ids_for`].
    #[test]
    fn canonical_ids_for_groups_by_first_occurrence_of_each_owning_instance() {
        let a = InstanceId(3);
        let b = InstanceId(9);
        // Two processes of instance `a`, one of instance `b`, `b` appearing
        // between them -- `canonical_ids_for` must still give both `a`
        // entries the same id, distinct from `b`'s, regardless of `b`'s
        // interleaved position.
        let owning = [a, b, a];
        let ids = canonical_ids_for(&owning);
        assert_eq!(ids.len(), 3);
        assert_eq!(
            ids[0], ids[2],
            "both entries of instance `a` must share one id"
        );
        assert_ne!(ids[0], ids[1], "instance `b`'s id must differ from `a`'s");
    }
}