shape-jit 0.3.0

//! MIR-to-Cranelift IR compiler (JIT v2).
//!
//! Compiles directly from Shape's MIR (Mid-level IR) to Cranelift IR,
//! preserving CFG structure, ownership semantics (Move/Copy/Drop),
//! liveness, and storage plans that are lost in the bytecode encoding.
//!
//! # Architecture
//!
//! ```text
//! AST → MIR (existing) → BorrowAnalysis + Liveness + StoragePlan (existing)
//!                      → MirToIR (this module) → Cranelift IR → native code
//! ```
//!
//! # Key differences from BytecodeToIR
//!
//! - **1:1 block mapping**: MIR BasicBlocks map directly to Cranelift blocks
//! - **Ownership-aware**: Move nulls the source, Copy retains, Drop releases
//! - **~7 statement kinds** vs ~100 bytecode opcodes
//! - **Explicit Drop points**: Scope cleanup from MIR, not heuristic

mod blocks;
pub mod bounds_elision;
mod conversions;
mod ownership;
mod places;
mod rvalues;
mod statements;
mod terminators;
pub(crate) mod types;
pub(crate) mod v2_array;
pub(crate) mod v2_field;
pub(crate) mod v2_int;
pub(crate) mod v2_refcount;
pub(crate) mod v2_string;
pub(crate) mod v2_typed_map;

// Heavy execution-path tests — gated behind the `deep-tests` feature.
// Each test calls JITExecutor::execute_program, which JIT-compiles ~118
// stdlib functions via MirToIR. Running them on the default Tier 1 path
// at n-cpu parallelism makes the shape-jit test binary slow enough to
// miss the summary line and racy enough to SIGILL in the JIT code cache.
// See `just test-deep` to run.
#[cfg(all(test, feature = "deep-tests"))]
mod integration_tests;

#[cfg(all(test, feature = "deep-tests"))]
mod v2_array_tests;

// Re-gated post-W11 reopen verification: with principled arc_retain/
// release (W11-jit-new-array), the SIGABRT source for these tests is
// confirmed to be `ffi/control/mod.rs:171::jit_call_value` whose body
// is `todo!("phase-2c §2.7.10/Q11 + §2.7.11/Q12: JIT-side kinded
// value-call ABI rebuild")` — NOT a retain/release issue. The
// closure-dispatch tests exercise the §2.7.11 / Q12 value-call ABI
// (callee/args kind-stamping) which is W11-jit-carrier-conversion's
// territory; the W11-jit-new-array charter is limited to the array
// FFI surface + arc_retain/release. Re-enable when the kinded
// value-call ABI lands at `ffi/control/mod.rs:171`.
#[cfg(all(test, feature = "deep-tests"))]
mod closure_dispatch_regression_tests;

// Phase 4b Round 5c-2-α jit-shortcircuit-eager soundness fix regression
// tests (v0.3-gating per supervisor ratify 2026-05-19; sister-class to
// LANG-9-spin-3-first VM/JIT divergence). Pin the t25 reproducer +
// divzero / chained / nested short-circuit cases against the MIR-layer
// short-circuit lowering at `crates/shape-vm/src/mir/lowering/expr.rs`
// `lower_short_circuit_and_or`. Gated behind `deep-tests` per the
// `closure_dispatch_regression_tests` precedent (full JIT pipeline
// invocation; non-trivial compile time per test).
#[cfg(all(test, feature = "deep-tests"))]
mod short_circuit_regression_tests;

// Phase 4b Round 5c-2-α jit-ref-param-chain-stamp regression tests
// (ADR-006 §2.7.13 + §2.7.5; supervisor ratify 2026-05-19). Gated
// behind `deep-tests` for the same reason as
// `closure_dispatch_regression_tests` above — `JITExecutor::execute_program`
// JIT-compiles the stdlib on every test, so default-parallelism CI runs
// would race the JIT code cache.
#[cfg(all(test, feature = "deep-tests"))]
mod ref_param_regression_tests;

// γ-CP4 jit-makefieldref regression tests (ADR-006 §2.7.13 + §2.3;
// v0.3-gating NO-KNOWN-INCORRECTNESS). Pin the JIT codegen for
// `MakeFieldRef` — `&`/`&mut` references projecting into a typed-object
// field — against the field-address path in `rvalues.rs::Rvalue::Borrow`
// + `places.rs::emit_typed_field_address`. Sister-class to
// `ref_param_regression_tests` (the `Place::Local` ref-param chain).
// Gated behind `deep-tests` for the same reason: `JITExecutor::
// execute_program` JIT-compiles the stdlib on every test.
#[cfg(all(test, feature = "deep-tests"))]
mod field_ref_regression_tests;
// v0.3 γ-CP3 jit-array-builder regression tests. Pin the array-spread +
// destructure-rest reproducers against the honest surface-and-stop fix
// (MIR slice-shape lowering of `...rest` + `emit_v2_array_aggregate`
// heap-pointer-operand rejection). Gated behind `deep-tests` for the
// same reason as the sibling regression modules above.
#[cfg(all(test, feature = "deep-tests"))]
mod array_builder_regression_tests;
// v0.3 γ-CP9 jit-groupby-surface regression tests. Pin the array
// `groupBy` / `count` / `group` reproducers against the honest
// surface-and-stop fix (`try_emit_v2_array_method` compile-stage `Err`
// + the `jit_call_method` defense-in-depth closure-arg guard). Gated
// behind `deep-tests` for the same reason as the sibling regression
// modules above — `JITExecutor::execute_program` JIT-compiles the
// stdlib on every test.
#[cfg(all(test, feature = "deep-tests"))]
mod groupby_surface_regression_tests;

// γ-CP5 jit-typedarray-ptr regression tests (v0.3-gating
// NO-KNOWN-INCORRECTNESS). Pin two JIT bugs un-masked by the Family-α
// TypedArray fix: 7a — `Place::Index` codegen on a `Place::Field` base
// (`b.items[i]` for a struct field of type `Array<int>`) must use the
// v2 `TypedArray` layout (data@8/len@16), recognised via the
// schema-derived `field_array_elem_kinds` map; 7b — `jit_call_value`
// must retain each heap-typed closure capture (kind-driven
// `KindedSlot::clone`) before handing it to `jit_trampoline_call_closure`,
// which builds a fresh `OwnedClosureBlock` whose `Drop` releases each
// capture. Gated behind `deep-tests` for the same reason as
// `field_ref_regression_tests`: `JITExecutor::execute_program`
// JIT-compiles the stdlib on every test.
#[cfg(all(test, feature = "deep-tests"))]
mod typedarray_ptr_regression_tests;

// v0.3 WS-7 jit-array-param-fix regression tests (v0.3-gating
// NO-KNOWN-INCORRECTNESS). Pin the SIGSEGV crash where a named function
// with an UNANNOTATED array parameter, indexed `xs[i]`, crashed in JIT
// mode once tier-compiled — even on a valid in-bounds access. Root cause:
// the inferred pass-by-reference optimization marked the param as a
// reference (callee auto-deref) while the JIT/MIR caller passed the heap
// pointer by value. Gated behind `deep-tests` for the same reason as
// `typedarray_ptr_regression_tests`: `JITExecutor::execute_program`
// JIT-compiles the stdlib on every test.
#[cfg(all(test, feature = "deep-tests"))]
mod jit_array_param_regression_tests;

use cranelift::codegen::ir::{FuncRef, StackSlot};
use cranelift::prelude::*;
use std::collections::{HashMap, HashSet};
use std::sync::Arc;

use crate::ffi_refs::FFIFuncRefs;
use shape_value::v2::closure_layout::ClosureLayout;
use shape_value::v2::struct_layout::FieldKind;
use shape_value::v2::ConcreteType;
use shape_vm::bytecode::MirFunctionData;
use shape_vm::mir::types::*;
use shape_vm::type_tracking::NativeKind;

/// Session 2: side-table entry for a non-escaping stack closure call.
///
/// Carries the function_id, per-capture byte offset, and per-capture
/// Cranelift type recorded at `emit_stack_closure` time. The indirect
/// `Call` terminator consults this when the callee operand resolves to
/// a slot in `MirToIR::stack_closure_call_info` and emits a direct
/// `user_func_refs[function_id]` call with captures loaded from the
/// stack slot instead of routing through the `jit_call_value` FFI.
#[derive(Debug, Clone)]
pub(crate) struct StackClosureCallInfo {
    /// Target function_id (matches the `StackClosure.function_id` field).
    pub(crate) function_id: u16,
    /// Per-capture byte offset inside the `StackSlot`.
    pub(crate) capture_offsets: Vec<i32>,
    /// Per-capture native Cranelift type (F64 / I64 / I32 / I16 / I8 / Bool).
    pub(crate) capture_types: Vec<cranelift::prelude::Type>,
}

/// MIR-to-Cranelift IR compiler.
///
/// Each instance compiles a single MIR function. Reuses the JIT's existing
/// FFI infrastructure (250+ function references) and type mapping.
pub struct MirToIR<'a, 'b> {
    /// Cranelift function builder.
    pub(crate) builder: &'a mut FunctionBuilder<'b>,
    /// JITContext pointer (passed as first function parameter).
    pub(crate) ctx_ptr: Value,
    /// FFI function references (arc_retain, arc_release, print, etc.).
    pub(crate) ffi: FFIFuncRefs,
    /// The caller's entry block (already created, with function params).
    /// MIR bb0 maps to this block instead of creating a new one.
    pub(crate) entry_block: Block,

    // ── Block mapping ──────────────────────────────────────────────
    /// MIR BasicBlockId → Cranelift Block.
    pub(crate) block_map: HashMap<BasicBlockId, Block>,

    // ── Local variables ────────────────────────────────────────────
    /// MIR SlotId → Cranelift Variable.
    pub(crate) locals: HashMap<SlotId, Variable>,
    /// Type info for each local slot (from MIR's LocalTypeInfo).
    pub(crate) local_types: Vec<LocalTypeInfo>,
    /// Frame descriptor slot kinds (from bytecode Function.frame_descriptor),
    /// enriched by MIR-level type inference. `None` per slot means the
    /// inference pass left the kind undetermined — codegen consumers
    /// surface-and-stop on `None` per ADR-006 §2.7.7 (no deleted
    /// `NativeKind::Unknown` placeholder).
    pub(crate) slot_kinds: Vec<Option<NativeKind>>,
    /// v2: Per-slot fully-resolved `ConcreteType` from the bytecode compiler's
    /// `function_local_concrete_types` / `top_level_local_concrete_types`
    /// side-tables. Used by the v2 typed-array codegen path. Empty when the
    /// bytecode compiler did not populate the side-table — callers fall back
    /// to the legacy NaN-boxed path.
    pub(crate) concrete_types: Vec<ConcreteType>,
    /// Next Cranelift variable index.
    pub(crate) next_var: usize,

    // ── MIR data ───────────────────────────────────────────────────
    /// The MIR function being compiled.
    pub(crate) mir: &'a MirFunction,
    /// Borrow analysis (for ownership decisions).
    pub(crate) mir_data: &'a MirFunctionData,
    /// String table for resolving StringId constants.
    pub(crate) strings: &'a [String],
    /// Function name → index mapping for resolving Call terminators.
    pub(crate) function_indices: &'a HashMap<String, u16>,

    // ── Direct call support ─────────────────────────────────────────
    /// Function index → Cranelift FuncRef for direct calls (bypasses FFI).
    pub(crate) user_func_refs: HashMap<u16, FuncRef>,
    /// Function index → arity for call validation.
    pub(crate) user_func_arities: HashMap<u16, u16>,

    // ── Borrow support ──────────────────────────────────────────────
    /// MIR SlotId → (Cranelift StackSlot, Cranelift Type) for references
    /// created by `Rvalue::Borrow`. After calls, all referenced locals are
    /// reloaded from their stack slots using the recorded native type.
    ///
    /// R4.2F: the type is tracked so `reload_referenced_locals` can issue a
    /// native-width `stack_load` that matches both the `stack_store` width
    /// and the declared variable type. Non-native slot kinds map to I64 via
    /// `cranelift_type_for_slot`, collapsing to the legacy 8-byte cell.
    pub(crate) ref_stack_slots: HashMap<SlotId, (StackSlot, Type)>,
    /// Mapping from field name to byte offset within a TypedObject.
    pub(crate) field_byte_offsets: HashMap<String, u16>,

    /// W12-jit-binop-after-heap-read-kind-tracker (ADR-006 §2.7.5
    /// stamp-at-compile-time): field-name → `NativeKind` map populated
    /// by the producer-side MIR walk (`infer_field_native_kinds` in
    /// `types.rs`). Every `StatementKind::ObjectStore { operands,
    /// field_names, .. }` stamps each named operand's MIR-inferred kind
    /// here, threading the producer's kind classification across the
    /// `Place::Field` projection at consumer sites — specifically the
    /// `Rvalue::BinaryOp` lowering in `rvalues.rs`, which needs proven
    /// operand kinds at compile time per CLAUDE.md "Forbidden code"
    /// (runtime tag_bits dispatch deleted with the W-series IC).
    ///
    /// Keying by field name (not `FieldIdx` or `StructLayoutId`) mirrors
    /// the existing `field_byte_offsets` discipline; both maps have the
    /// same structural caveat ("last-writer-wins on name collision
    /// across distinct struct types") but cover every load-bearing
    /// cluster-0 smoke. A schema-aware `(StructLayoutId, FieldIdx) →
    /// NativeKind` registry is the principled long-term shape — out of
    /// scope for this sub-cluster.
    ///
    /// Populated once at `MirToIR::new_with_closure_layouts` time so
    /// the kind is available for cross-block field reads, mirroring how
    /// `slot_kinds` is computed pre-codegen via `infer_slot_kinds`.
    pub(crate) field_native_kinds: HashMap<String, NativeKind>,

    /// γ-CP5 7a (jit-typedarray-ptr): field-name → v2 typed-array
    /// **element** `NativeKind` for struct fields declared `Array<T>`
    /// with a scalar element `T`.
    ///
    /// `field_native_kinds` (above) collapses every `Array<T>` field to
    /// `NativeKind::Ptr(HeapKind::TypedArray)` — the element type is
    /// erased. The v2 `Place::Index` fast path (`v2_typed_array_elem_kind`
    /// in `v2_array.rs`) needs the element kind to pick the inline
    /// `v2_array_get` codegen (v2 layout: data@8 / len@16) instead of the
    /// legacy `inline_array_get` (v1 layout: data@+0 / len@+8 past an
    /// 8-byte header). Without it a `b.items[i]` access where `items` is
    /// a struct field of type `Array<int>` falls through to the v1 path
    /// and reads the wrong element offset.
    ///
    /// Keyed by field name, matching the `field_byte_offsets` /
    /// `field_native_kinds` discipline (same "last-writer-wins on name
    /// collision across distinct struct types" caveat — benign for the
    /// single-receiver-type field reads this fast path serves).
    ///
    /// Per ADR-006 §2.7.5 producer-side stamp: derived from the canonical
    /// `TypeSchemaRegistry` `FieldType::Array(elem)` declaration at
    /// `populate_field_byte_offsets_from_schemas` time — a compile-time
    /// index, not a runtime decode.
    pub(crate) field_array_elem_kinds: HashMap<String, NativeKind>,

    // ── Closure Spec Phase E: stack-allocated closures ──────────────
    /// Slots that hold a non-escaping closure value, per the MIR
    /// storage plan's `non_escaping_closure_slots`. When a
    /// `StatementKind::ClosureCapture` targets a slot in this set,
    /// codegen allocates a Cranelift `StackSlot` shaped like
    /// `StackClosure { function_id: u32, type_id: u32, captures... }`
    /// instead of calling `jit_make_closure`. Cranelift's SROA then
    /// eliminates the slot when Phase C has inlined the closure body
    /// and the env pointer is dead.
    pub(crate) non_escaping_closure_slots: HashSet<SlotId>,
    /// MIR SlotId → Cranelift `StackSlot` backing a non-escaping
    /// closure. Populated on `ClosureCapture`. Used by drop/release
    /// paths to skip `arc_release` on stack-resident closure handles
    /// and by other consumers that need to know the slot is stack-resident.
    pub(crate) stack_closure_slots: HashMap<SlotId, StackSlot>,

    /// Session 2: per-slot stack-closure call metadata captured alongside
    /// `stack_closure_slots`. When an indirect `Call` whose `func` operand
    /// resolves to a slot in this map dispatches the closure, the
    /// terminator can bypass `jit_call_value` entirely — the function_id
    /// and capture byte offsets/Cranelift types are baked into codegen.
    ///
    /// This closes the hole where a stack closure's callee bits are a raw
    /// stack pointer (no NaN-box tag, no `HK_CLOSURE` header) that the
    /// FFI dispatcher can't recognise — the fix is to not dispatch through
    /// the FFI at all when the JIT itself built the closure.
    pub(crate) stack_closure_call_info:
        HashMap<SlotId, StackClosureCallInfo>,

    // ── Phase 4b Round 5c-2-α jit-ref-param-chain-stamp ────────────
    /// Param slots whose source-declaration carries a reference borrow kind
    /// (`&x` / `&mut x`). Populated at JIT compile-entry from
    /// `mir.param_reference_kinds`. Read/write/null sites for these slots
    /// auto-dispatch through the cell-indirection path (load/store at the
    /// referent address) instead of the slot's raw local variable.
    ///
    /// ADR-006 §2.7.13 ref-chain stamp + §2.7.5 producer-side stamp:
    /// MIR-lowering at `crates/shape-vm/src/mir/lowering/mod.rs:617-628`
    /// classifies reference parameters as `LocalTypeInfo::NonCopy` and
    /// records `param_reference_kinds[i] = Some(BorrowKind::*)` but does NOT
    /// emit `Place::Deref` projections for the body's `x = x + 1` style
    /// reads/writes — the slot is treated as if it held the referenced
    /// value directly (`crates/shape-vm/src/mir/lowering/expr.rs:24-25`
    /// returns `Place::Local(slot)` for `Expr::Identifier`, and
    /// `crates/shape-vm/src/mir/lowering/stmt.rs:307` assigns to
    /// `Place::Local(slot)` on identifier-target assignments).
    ///
    /// The BYTECODE compile path handles this orthogonally by emitting
    /// `DerefLoad` / `DerefStore` against the ref-slot at
    /// `compiler/expressions/identifiers.rs:219-221` (read) and the
    /// assignment lowering (write). The W14.2-G4 close at
    /// `compiler/functions.rs:1331-1390` further fixes a producer-side
    /// kind-stamping race on the bytecode side. The JIT-MIR consumer was
    /// never updated to honor reference semantics — calling
    /// `bump(&a); print(a)` returns the un-mutated `a` because the JIT
    /// reads the slot's raw pointer bits, adds 1, and writes the result
    /// back into the same local slot (never touching the caller's cell).
    ///
    /// W14.2-G4 was VM-only by composition: the `tools/shape-test`
    /// harness's `BytecodeExecutor` (`tools/shape-test/src/shape_test.rs:
    /// 237`) runs every assertion via the bytecode interpreter — JIT
    /// divergence is not surfaced. The empirical W15.2-F SURFACE at HEAD
    /// `989b18d6` and supervisor ratify 2026-05-19 promote this to
    /// v0.3-gating soundness.
    ///
    /// Sister-class to LANG-9-spin-3-first / W14.2-E SURFACE-A. The fix
    /// site here mirrors the bytecode-compiler's ref-slot handling shape:
    /// reads auto-deref, writes auto-deref, no NEW cell allocation for
    /// re-borrowing `&x` of an existing ref-param.
    pub(crate) ref_param_slots: HashSet<SlotId>,

    // ── Closure Spec Phase H1: heap-allocated closure codegen ──────
    /// Map from closure body `function_id` to its `ClosureLayout`.
    /// When present, `emit_heap_closure` uses the layout to emit inline
    /// Cranelift code that allocates a `TypedClosureHeader`-shaped block
    /// and writes captures at their natural-width offsets, replacing the
    /// legacy `jit_make_closure` FFI call. Absent entries fall back to
    /// the FFI path (e.g. when loading a cached program from disk, which
    /// doesn't carry layout metadata).
    pub(crate) closure_function_layouts: HashMap<u16, Arc<ClosureLayout>>,

    // ── Track A.1D.2: OwnedMutable capture side-table ──────────────
    /// Local slots whose Cranelift variable holds the raw `*mut ValueWord`
    /// bits of an `OwnedMutable` capture cell (allocated by
    /// `jit_alloc_owned_mut_cell` in `emit_heap_closure`). For a closure
    /// compiled under this `MirToIR`, the leading `N` entries of
    /// `MirFunction::param_slots` correspond to captures in the same
    /// order as `ClosureLayout::capture_kinds`; each slot whose
    /// `capture_storage_kind(i) == OwnedMutable` is recorded here.
    ///
    /// Effects on the lowering pipeline:
    /// - `read_place(Local(s))` emits `load.i64 [cell_ptr, 0]` (matches
    ///   the interpreter's `op_load_owned_mutable_capture` fresh read).
    /// - `write_place(Local(s), v)` emits `store.i64 v, [cell_ptr, 0]`
    ///   (matches the interpreter's `op_store_owned_mutable_capture`
    ///   fresh write — no old-value release, no retain).
    /// - `null_place` / `release_old_value_if_heap` / `emit_drop` all
    ///   early-return for these slots: the cell pointer bits must
    ///   survive for the entire frame so every read/write finds the
    ///   right box, and the box is reclaimed exactly once by
    ///   `release_typed_closure`'s `Box::from_raw` loop (see
    ///   `ClosureLayout::owned_mutable_capture_mask`, A.1A).
    ///
    /// Empty when the function being compiled is not a closure body,
    /// or has no OwnedMutable captures — non-closure functions then
    /// behave identically to pre-A.1D.2.
    ///
    /// Wave C.2: the value carries the `FieldKind` of the cell's interior
    /// payload (from `ClosureLayout::capture_inner_kind`). The Cranelift
    /// codegen for `read_place` / `write_place` dispatches on this kind
    /// to select the matching per-FieldKind FFI helper
    /// (`jit_read_owned_mut_cell_<kind>` / `jit_write_owned_mut_cell_<kind>`),
    /// so values cross the cell boundary as native Cranelift types
    /// (i64/f64/i32/...) instead of NaN-boxed ValueWord bits.
    pub(crate) owned_mutable_capture_slots: HashMap<SlotId, FieldKind>,

    // ── Track A.1E: Shared capture side-table ─────────────────────
    /// Local slots whose Cranelift variable holds the raw
    /// `*const SharedCell` bits of a `Shared` capture cell (retained via
    /// `jit_arc_shared_retain` in `emit_heap_closure`). Structurally
    /// parallel to `owned_mutable_capture_slots`: the leading `N`
    /// entries of `MirFunction::param_slots` are captures, and each slot
    /// whose `capture_storage_kind(i) == Shared` is recorded here.
    ///
    /// Effects on the lowering pipeline:
    /// - `read_place(Local(s))` emits the inline lock fast path (CAS
    ///   state byte 0→1 with `Acquire` ordering; on failure, call
    ///   `jit_shared_lock_contended`), then `load.i64 [cell_ptr,
    ///   SHARED_CELL_VALUE_OFFSET]`, then inline unlock fast path
    ///   (CAS 1→0 with `Release` ordering; on failure, call
    ///   `jit_shared_unlock_contended`). Matches the interpreter's
    ///   `op_load_shared_capture` handler semantics (take mutex, clone
    ///   inner bits, drop guard).
    /// - `write_place(Local(s), v)` emits the same lock fast path,
    ///   then `store.i64 v, [cell_ptr, SHARED_CELL_VALUE_OFFSET]`,
    ///   then the unlock fast path. Matches
    ///   `op_store_shared_capture` (take mutex, write, drop guard).
    /// - `null_place` / `release_old_value_if_heap` / `emit_drop` all
    ///   early-return for these slots: the Arc pointer bits must
    ///   survive for the entire frame so every read/write finds the
    ///   right cell, and the share is reclaimed exactly once by
    ///   `release_typed_closure`'s `Arc::from_raw` loop (see
    ///   `ClosureLayout::shared_capture_mask`, A.1A).
    ///
    /// Mutually exclusive with `owned_mutable_capture_slots` per the
    /// `ClosureLayout` invariant (the three capture-kind masks are
    /// disjoint). Empty when the function being compiled is not a
    /// closure body, or has no Shared captures.
    ///
    /// Wave C.2: like `owned_mutable_capture_slots`, the value carries
    /// the inner `FieldKind` so the Cranelift load/store after the
    /// inline `emit_shared_lock` dispatches to the correct native
    /// width at `[cell_ptr + SHARED_CELL_VALUE_OFFSET]`. We keep the
    /// inline lock/unlock — only the per-kind direct load/store is
    /// per-FieldKind — to avoid double-locking through the
    /// `read_shared_cell_<kind>` FFI on the JIT hot path.
    pub(crate) shared_capture_slots: HashMap<SlotId, FieldKind>,

    // ── Session 1 Commit 3: outer-scope Shared-cell slot side-table ─
    /// Local slots whose `BindingStorageClass` is `SharedCow` — i.e.
    /// outer-scope `var` bindings that escape into a closure and hence
    /// get promoted to `Arc<SharedCell>` storage by the bytecode
    /// compiler (`AllocSharedLocal` on promotion;
    /// `Load/StoreSharedLocal` on every subsequent access;
    /// `DropSharedLocal` at scope exit — see
    /// `shape-vm/src/executor/variables/mod.rs`).
    ///
    /// MIR doesn't reflect that promotion directly — it emits plain
    /// `Assign(Local(s), ...)` and `Drop(Local(s))` on the slot — so
    /// the JIT must recognise SharedCow slots via this side-table and
    /// dispatch read/write/drop to the lock-gated + Arc-lifecycle
    /// lowering path.
    ///
    /// Effects on the lowering pipeline:
    /// - `initialize_shared_local_slots` (called once at the start of
    ///   `compile`) allocates a fresh `Arc<SharedCell>` per slot via
    ///   `jit_alloc_shared_cell(NONE_BITS)` and stores the pointer
    ///   bits into the slot's Cranelift variable.
    /// - `read_place(Local(s))` emits the inline lock-gated
    ///   `load.i64 [cell_ptr + SHARED_CELL_VALUE_OFFSET]` (same lowering
    ///   as `shared_capture_slots` — see
    ///   `emit_shared_lock`/`emit_shared_unlock`).
    /// - `write_place(Local(s), v)` emits the matching lock-gated
    ///   store.
    /// - `emit_drop(Local(s))` calls `jit_arc_shared_release` to
    ///   consume the slot's strong share.
    /// - `compile_operand_for_shared_capture` (new) emits a raw
    ///   pointer read — bypassing the lock — so `ClosureCapture`
    ///   operands install the outer cell pointer into the closure's
    ///   Shared capture slot without locking.
    ///
    /// Disjoint from `owned_mutable_capture_slots` and
    /// `shared_capture_slots` — those are leading-capture param slots
    /// of a closure BODY; `shared_local_slots` is a declaring-scope
    /// slot in the outer function.
    pub(crate) shared_local_slots: HashSet<SlotId>,

    // ── JIT-side back-patch for unresolved ClosurePlaceholder ──────
    /// Per-placeholder function_id, populated at construction by scanning the
    /// MIR in block/statement order. Each entry corresponds to a
    /// `ClosurePlaceholder` assign that the bytecode compiler's back-patcher
    /// did NOT replace with `Function(name)` — typically because
    /// `closure_function_ids` got cleared by a monomorphization-triggered
    /// `compile_function` call before the top-level-MIR patching ran.
    ///
    /// When `compile_constant(MirConstant::ClosurePlaceholder)` is invoked,
    /// we pop the head of this queue (via `next_closure_placeholder_idx`)
    /// and NaN-box the corresponding function id so the stack carries a
    /// proper `TAG_FUNCTION` bit pattern instead of literal 0. Without this
    /// the JIT's `jit_call_value` sees `0x0` for a no-capture closure and
    /// bails out with "callee is neither function nor closure", which is
    /// the root cause of the gated `parity_array_map/filter/reduce`
    /// failures.
    ///
    /// Empty for MIRs that have no unresolved placeholders, for closure
    /// bodies themselves (their `ClosureCapture` statements carry the
    /// resolved `function_id` directly), and for functions whose
    /// back-patching already succeeded.
    pub(crate) closure_placeholder_fids: Vec<u16>,
    /// Cursor into `closure_placeholder_fids`. Incremented once per call to
    /// `compile_constant(ClosurePlaceholder)`. Statement visit order during
    /// `compile_body` matches the scan order used by
    /// `scan_closure_placeholder_fids`, so this is a stable pairing.
    pub(crate) next_closure_placeholder_idx: std::cell::Cell<usize>,
    /// Bounds-check elision plan: pairs `(arr_slot, iv_slot)` for which
    /// `Place::Index(Local(arr), Operand::*(Local(iv)))` accesses can skip
    /// the inline bounds check. Populated by callers via
    /// `set_bounds_elision_plan` after running
    /// `bounds_elision::analyze(mir)`. Empty by default — falls back to
    /// the bounds-checked path, preserving the v2_array_tests OOB
    /// zero-default semantics.
    pub(crate) bounds_elision: bounds_elision::BoundsElisionPlan,

    // ── V3-S6c JIT method-monomorph routing side-table ─────────────
    /// ADR-006 §2.7.5 V3-S6c-jit-method-monomorph-routing (PATH α-prime
    /// per supervisor 2026-05-15 ratification): the V3-S6b side-table
    /// `BytecodeProgram.monomorphized_method_call_sites` cloned into the
    /// JIT MirToIR so the Call-terminator compile path can re-route
    /// `MirConstant::Method` Call terminators to direct Cranelift FuncRef
    /// calls via `user_func_refs[specialized_idx]`. Key is
    /// `(call_site_span, caller_function_id)` where `caller_function_id`
    /// is the bytecode compiler's `self.current_function` at
    /// `try_monomorphize_method_call` success (matches the JIT-side
    /// `caller_function_id` field below).
    ///
    /// Empty when the bytecode compiler did not specialize any method
    /// call (no generic method calls in the program, or all monomorph
    /// attempts bailed). JIT falls through to the existing
    /// `jit_call_method` trampoline path for any miss — preserves V3-S6b
    /// baseline behaviour.
    pub(crate) monomorphized_method_call_sites:
        HashMap<(shape_ast::ast::span::Span, Option<usize>), usize>,

    /// V3-S6c routing: the caller function id used as the second
    /// component of the `monomorphized_method_call_sites` composite key.
    /// `None` for top-level (`__main__`) code per the same convention
    /// the bytecode compiler uses (`self.current_function == None` when
    /// compiling top-level statements). For user functions, this is the
    /// post-monomorphization specialized FunctionId (matches the
    /// `func_idx: usize` passed to `compile_function_with_user_funcs` at
    /// `compiler/program.rs:236`).
    pub(crate) caller_function_id: Option<usize>,

    /// ADR-006 §2.7.5 W10 jit-call-method-user-trait-fix (2026-05-17):
    /// per-binop/unop-site operator-trait-dispatch side-table cloned from
    /// `BytecodeProgram.operator_trait_dispatch_sites`. Consumed by
    /// `compile_rvalue`'s `Rvalue::BinaryOp` / `Rvalue::UnaryOp` arms to
    /// re-emit the bytecode-time trait-dispatch as a method-call
    /// equivalent. Keyed by the statement span (matches MIR lowering's
    /// `expr.span()`). Empty when the program has no user-type operator
    /// overloading — JIT falls through to the existing typed-arith /
    /// typed-cmp / unop lowering paths.
    pub(crate) operator_trait_dispatch_sites:
        HashMap<shape_ast::ast::span::Span, (String, u16)>,
}

/// Result of MIR preflight check.
pub struct MirPreflightResult {
    /// Whether this function can be compiled via MirToIR.
    pub can_compile: bool,
    /// Reasons why compilation is not possible (empty if can_compile is true).
    pub blockers: Vec<String>,
}

/// Check if a function's MIR can be compiled by MirToIR.
///
/// Returns detailed preflight results. Functions with unsupported MIR
/// features (async, closures, complex places) fall back to BytecodeToIR.
pub fn preflight(mir_data: &MirFunctionData) -> MirPreflightResult {
    let mut blockers = Vec::new();

    for block in &mir_data.mir.blocks {
        for stmt in &block.statements {
            match &stmt.kind {
                StatementKind::Assign(place, rvalue) => {
                    if !is_simple_place(place) {
                        blockers.push(format!(
                            "complex place in assignment at {:?}",
                            stmt.span
                        ));
                    }
                    match rvalue {
                        // W15.2-LANG-5 (Phase 4b, 2026-05-18). MIR-level
                        // marker for `Pattern::Typed` arms in `match`
                        // expressions. JIT codegen is not yet wired
                        // (`compile_rvalue` surfaces-and-stops on this
                        // variant); preflight rejects so the W12 fall-
                        // through routes the program to the bytecode
                        // interpreter, which compiles typed patterns via
                        // `OpCode::TypeCheck` in
                        // `compiler/patterns/checking.rs`. ADR-006 §2.7.5
                        // producer-side classification: the annotation is
                        // carried verbatim from `ast::Pattern::Typed`.
                        Rvalue::TypePatternTest { type_annotation, .. } => {
                            blockers.push(format!(
                                "TypePatternTest (W15.2-LANG-5): \
                                 `Pattern::Typed` codegen pending, \
                                 annotation = {:?} at {:?}",
                                type_annotation, stmt.span
                            ));
                        }
                        // W15.2-LANG-1 (Phase 4b, 2026-05-18). MIR-level
                        // marker for non-trinity (user-defined) `Pattern::
                        // Constructor` arms in `match` expressions
                        // (e.g. `match Color::Red { Color::Red => ..., ...
                        // }`). JIT codegen is not yet wired (`compile_rvalue`
                        // surfaces-and-stops on this variant); preflight
                        // rejects so the W12 fall-through routes the program
                        // to the bytecode interpreter, which compiles user-
                        // defined enum patterns via the typed-object
                        // discriminant check at `compile_typed_enum_pattern_
                        // check` in `compiler/patterns/checking.rs`
                        // (emits `GetFieldTyped(__variant, I64)` +
                        // `PushConst(variant_id)` + `EqInt`). ADR-006
                        // §2.7.5 producer-side classification: the
                        // (enum_name, variant_name) pair is carried verbatim
                        // from `ast::Pattern::Constructor`. Mirrors the
                        // LANG-5 `TypePatternTest` precedent.
                        Rvalue::EnumDiscriminantTest {
                            enum_name,
                            variant_name,
                            ..
                        } => {
                            blockers.push(format!(
                                "EnumDiscriminantTest (W15.2-LANG-1): \
                                 user-defined `Pattern::Constructor` codegen \
                                 pending, enum = {:?}, variant = {:?} at {:?}",
                                enum_name, variant_name, stmt.span
                            ));
                        }
                        // R8 W9 G.2 Step 2 Bucket 2 EnumPayload SURFACE
                        // (ADR-006 §2.7.14 / §2.7.17, supervisor 2026-05-25).
                        // `Rvalue::EnumPayload { variant: Ok|Err|Some_ }`
                        // is the MIR-level marker for the payload binder in
                        // `Pattern::Constructor` arms like `Ok(path)`,
                        // `Some(p)`, `Err(m)`. The JIT codegen at
                        // `compile_rvalue` calls `jit_arc_*_payload` which
                        // casts the operand bits to `*const ResultData` /
                        // `*const OptionData`; when the operand is the
                        // return slot of a user-defined fn whose return
                        // shape doesn't actually carry the strict
                        // `Arc<ResultData>` / `Arc<OptionData>` carrier
                        // (i.e. the §2.7.17 receiver-recovery soundness rule
                        // is violated at the call-site producer because the
                        // return-kind track threads an `Arc<HeapValue>`
                        // pointer instead), the cast is UB and produces
                        // either silent-wrong-output (e.g. Result<int,int>
                        // payload `42` returning `8589934634` — the i64
                        // overlapped by a neighbouring slot's bits) or a
                        // SIGSEGV (e.g. `Result<string,string>` payload
                        // dereferencing a HeapValue::String through a
                        // `*const ResultData` layout offset). Empirically
                        // observed at HEAD on Option<string> → Result<string,
                        // string> match-destruct (deterministic ec=139
                        // SIGSEGV) and Result<int,int> match-destruct
                        // (deterministic silent-wrong-output).
                        //
                        // Mirrors the W15.2-LANG-5 / LANG-1 preflight
                        // precedent above + R8 W7 G.5 HashMap key-kind +
                        // R8 W8 Cluster A imported-const-inline / aliased-
                        // CoW typed-array-push surface-and-stop. Whole-
                        // program deopt via W12 `[jit-fallback]` routes the
                        // program to the bytecode interpreter where the
                        // EnumPayload Rvalue is compiled to opcodes that
                        // dispatch on the actual carrier shape (not the
                        // JIT's strict `Arc<*Data>` cast). Root-cause fix
                        // — extending §2.7.17 receiver-recovery to the
                        // user-fn return-kind boundary so the producer at
                        // the call-site stamps the strict carrier per
                        // ADR-006 §2.7.5 — is v0.4 per
                        // `docs/v0.3-close-summary.md` §5.16 JIT-lowering
                        // followup workstream.
                        Rvalue::EnumPayload { variant, .. } => {
                            blockers.push(format!(
                                "EnumPayload (R8 W9 G.2 Step 2 Bucket 2): \
                                 `Pattern::Constructor` payload binder \
                                 (`Ok(_)` / `Err(_)` / `Some(_)`) codegen \
                                 has receiver-recovery soundness gap at the \
                                 user-fn return-kind boundary per ADR-006 \
                                 \u{a7}2.7.17; whole-program deopt via W12 \
                                 `[jit-fallback]` routes to the bytecode \
                                 interpreter (which compiles EnumPayload via \
                                 the kind-aware opcode dispatch). \
                                 variant = {:?} at {:?}. Tracked v0.4 per \
                                 `docs/v0.3-close-summary.md` \u{a7}5.16 \
                                 JIT-lowering followup workstream.",
                                variant, stmt.span
                            ));
                        }
                        // BinaryOp, UnaryOp, Use, Clone, Borrow, Aggregate,
                        // EnumTest are supported
                        _ => {}
                    }
                }
                StatementKind::Drop(place) => {
                    if !is_simple_place(place) {
                        blockers.push(format!("complex place in drop at {:?}", stmt.span));
                    }
                }
                StatementKind::TaskBoundary(_, _) => {
                    // TaskBoundary is a borrow-checker annotation — no-op at codegen time.
                }
                StatementKind::ClosureCapture { function_id, .. } => {
                    // ClosureCapture is supported when function_id has been patched
                    if function_id.is_none() {
                        blockers.push("ClosureCapture missing function_id".to_string());
                    }
                }
                _ => {}
            }
        }

        match &block.terminator.kind {
            TerminatorKind::Goto(_)
            | TerminatorKind::SwitchBool { .. }
            | TerminatorKind::Return
            | TerminatorKind::Unreachable => {}
            TerminatorKind::Call { .. } => {
                // Call terminators are now supported via FFI dispatch.
            }
        }
    }

    MirPreflightResult {
        can_compile: blockers.is_empty(),
        blockers,
    }
}

/// Check if a Place is supported by MirToIR.
/// Supports arbitrary nesting of Local, Field, and Index.
/// Only Deref (references) is unsupported.
fn is_simple_place(place: &Place) -> bool {
    match place {
        Place::Local(_) => true,
        Place::Field(inner, _) | Place::Index(inner, _) => is_simple_place(inner),
        Place::Deref(inner) => is_simple_place(inner),
    }
}

impl<'a, 'b> MirToIR<'a, 'b> {
    /// Create a new MIR-to-IR compiler.
    ///
    /// `entry_block` is the Cranelift block already created by the caller
    /// (with function parameters appended). MIR bb0 maps to this block.
    pub fn new(
        builder: &'a mut FunctionBuilder<'b>,
        ctx_ptr: Value,
        ffi: FFIFuncRefs,
        mir_data: &'a MirFunctionData,
        slot_kinds: Vec<Option<NativeKind>>,
        strings: &'a [String],
        entry_block: Block,
        function_indices: &'a HashMap<String, u16>,
        user_func_refs: HashMap<u16, FuncRef>,
        user_func_arities: HashMap<u16, u16>,
    ) -> Self {
        Self::new_with_concrete_types(
            builder,
            ctx_ptr,
            ffi,
            mir_data,
            slot_kinds,
            Vec::new(),
            strings,
            entry_block,
            function_indices,
            user_func_refs,
            user_func_arities,
        )
    }

    /// Same as `new` but also accepts a per-slot `ConcreteType` vector for
    /// the v2 typed-array fast path. Empty vec → legacy NaN-boxed behaviour.
    pub fn new_with_concrete_types(
        builder: &'a mut FunctionBuilder<'b>,
        ctx_ptr: Value,
        ffi: FFIFuncRefs,
        mir_data: &'a MirFunctionData,
        slot_kinds: Vec<Option<NativeKind>>,
        concrete_types: Vec<ConcreteType>,
        strings: &'a [String],
        entry_block: Block,
        function_indices: &'a HashMap<String, u16>,
        user_func_refs: HashMap<u16, FuncRef>,
        user_func_arities: HashMap<u16, u16>,
    ) -> Self {
        Self::new_with_closure_layouts(
            builder,
            ctx_ptr,
            ffi,
            mir_data,
            slot_kinds,
            concrete_types,
            strings,
            entry_block,
            function_indices,
            user_func_refs,
            user_func_arities,
            HashMap::new(),
        )
    }

    /// Closure-spec Phase H1 constructor: also accepts a
    /// `function_id → ClosureLayout` map so `emit_heap_closure` can lay out
    /// captures for escaping closures without going through the
    /// `jit_make_closure` FFI. Passing an empty map degrades gracefully to
    /// the legacy FFI path (same behaviour as `new_with_concrete_types`).
    pub fn new_with_closure_layouts(
        builder: &'a mut FunctionBuilder<'b>,
        ctx_ptr: Value,
        ffi: FFIFuncRefs,
        mir_data: &'a MirFunctionData,
        slot_kinds: Vec<Option<NativeKind>>,
        concrete_types: Vec<ConcreteType>,
        strings: &'a [String],
        entry_block: Block,
        function_indices: &'a HashMap<String, u16>,
        user_func_refs: HashMap<u16, FuncRef>,
        user_func_arities: HashMap<u16, u16>,
        closure_function_layouts: HashMap<u16, Arc<ClosureLayout>>,
    ) -> Self {
        let local_types = mir_data.mir.local_types.clone();
        // Slot-numbering correction: the bytecode compiler's
        // `FrameDescriptor.slots` and the MIR's local slots use different
        // numbering. MIR reserves `SlotId(0)` for the implicit return
        // value (`__mir_return`) and numbers parameters starting at 1;
        // the bytecode compiler puts the first parameter at slot 0 with
        // no implicit return slot. Seeding MirToIR with bytecode
        // frame_descriptor kinds thus misaligns every slot by +1. In the
        // worst case this declares MIR's return slot with the bytecode
        // param's `NativeKind`, so a `return 7.0` write gets narrowed
        // (e.g. `F64 → Bool` via `ireduce`) and corrupts the return value.
        // Regression case: `fn get_val(flag: bool) -> number? { if flag
        // { return 7.0 } return None }` declared MIR slot 0 as `Bool`
        // because the bytecode put `flag` at index 0; writing the `7.0`
        // F64 through `ensure_kind(_, Bool)` truncated to 0 and
        // `None ?? 42.0` then evaluated to 42.0 for every branch.
        //
        // Until the two tables share a slot-numbering convention, drop
        // the bytecode seed and rely on MIR-level inference only.
        let _ = slot_kinds;
        // ADR-006 §2.7.7 / §2.7.11 kind-source seed: when the bytecode
        // compiler has populated `concrete_types[slot]` with a precise
        // `ConcreteType`, project it to `NativeKind` for the parallel-kind
        // track. This is the load-bearing kind source for closure-bearing
        // slots returned from function calls (e.g. `let add3 =
        // make_adder(3)` where `make_adder` returns
        // `Function<(int), int>` / `ConcreteType::Closure`), which
        // `infer_slot_kinds` alone cannot derive from MIR-observable
        // statements.
        let concrete_seed: Vec<Option<NativeKind>> = concrete_types
            .iter()
            .map(|ct| types::native_kind_from_concrete_type(ct))
            .collect();
        // ADR-006 §2.7.5 producing-site classification: pass the per-
        // slot `ConcreteType` map into the inference so two projections
        // both work end-to-end —
        //
        // (1) W12-jit-binop-after-heap-read-kind-tracker (Round 5A):
        // `Place::Field` reads stamp the destination kind from the
        // FIELD's kind, not the base struct's heap kind (drives the
        // Smoke 3 `p.x + p.y` int-add).
        //
        // (2) W12-jit-print-kind (Round 5C): `Place::Index` reads off
        // typed-array slots stamp the destination kind from the
        // element kind, not the array's pointer kind — same source the
        // JIT codegen-side `place_native_kind` /
        // `v2_typed_array_elem_kind` projection uses. Without this seed
        // `print(xs[0])` on `xs: Array<int>` falls into the kind-blind
        // print decoder.
        let slot_kinds = types::infer_slot_kinds_with_concrete(
            &mir_data.mir,
            &concrete_seed,
            &concrete_types,
        );
        // Phase E: pull the set of non-escaping closure slots out of the MIR
        // storage plan so `ClosureCapture` lowering can pick the stack-slot
        // fast path. Slots absent from this set fall back to the legacy
        // `jit_make_closure` FFI path (Phase H will delete that).
        let non_escaping_closure_slots =
            mir_data.storage_plan.non_escaping_closure_slots.clone();

        // Session 1 Commit 3: scan `storage_plan` for outer-scope
        // local slots that actually get promoted to
        // `Arc<SharedCell>` storage at runtime. The bytecode
        // compiler emits `AllocSharedLocal` ONLY when a slot is
        // captured by a closure AND gets the Shared capture kind —
        // not for every SharedCow slot. The `SHAPE_V2_VAR_SHAREDCOW`
        // default classifies every `var` binding as SharedCow even
        // when it never escapes, so we cannot use the storage class
        // alone.
        //
        // The authoritative signal is `slot_semantics[slot]
        // .escape_status == Captured` AND
        // `slot_classes[slot] == SharedCow`. Captured-by-closure +
        // SharedCow is the exact condition under which the bytecode
        // compiler emits `AllocSharedLocal` (see
        // `expressions/closures.rs`'s `is_shared_local_slot` arm).
        //
        // Param slots (captures) are further excluded because they
        // are governed by the capture-side-tables
        // `owned_mutable_capture_slots` / `shared_capture_slots`.
        //
        // cell-identity #1: the storage-plan scan alone is NOT
        // sufficient. The MIR's storage planner classifies a slot's
        // ownership from `binding_semantics`, and on some pipelines
        // a `var` binding arrives at the planner as
        // `BindingOwnershipClass::OwnedImmutable` rather than
        // `Flexible` — so Rule 1b (`SHAPE_V2_VAR_SHAREDCOW` +
        // Flexible → SharedCow) does not fire and the slot lands as
        // `Direct` / `LocalMutablePtr` even though the bytecode
        // emits the `AllocSharedLocal` lifecycle against it. The
        // second scan below covers the gap by picking up every slot
        // that is an operand of a `ClosureCapture` whose layout
        // declares a `CaptureKind::Shared` capture at that position.
        use shape_vm::type_tracking::{BindingStorageClass, EscapeStatus};
        let param_slot_set: HashSet<SlotId> =
            mir_data.mir.param_slots.iter().copied().collect();
        let mut shared_local_slots: HashSet<SlotId> = HashSet::new();
        for (slot, class) in &mir_data.storage_plan.slot_classes {
            if !matches!(class, BindingStorageClass::SharedCow) {
                continue;
            }
            if param_slot_set.contains(slot) {
                continue;
            }
            // Only slots captured by a closure get the cell
            // promotion at the bytecode level. A `var` that never
            // escapes into a closure stays plain-valued in the
            // interpreter — the JIT must match that semantics or
            // diverge from the interpreter's view of the same slot.
            let is_captured = mir_data
                .storage_plan
                .slot_semantics
                .get(slot)
                .map(|sem| matches!(sem.escape_status, EscapeStatus::Captured))
                .unwrap_or(false);
            if !is_captured {
                continue;
            }
            shared_local_slots.insert(*slot);
        }

        // cell-identity #1: augment `shared_local_slots` by scanning
        // `ClosureCapture` statements whose `function_id` resolves to a
        // `ClosureLayout` with `CaptureKind::Shared` captures. The MIR
        // storage planner sometimes classifies `var` bindings as
        // `LocalMutablePtr` (not `SharedCow`) when the ownership class
        // for the slot is stored as `OwnedImmutable` in the MIR's
        // `binding_semantics` table, so the storage-plan scan above
        // misses them. The bytecode compiler still emits `AllocSharedLocal`
        // / `LoadSharedLocal` / `StoreSharedLocal` / `DropSharedLocal`
        // for those slots — and the closure body's JIT compilation
        // treats its capture param slot as `shared_capture_slots`
        // (it expects a `*const SharedCell` pointer). If the declaring
        // frame's JIT doesn't allocate an `Arc<SharedCell>` and doesn't
        // lock-gated route reads/writes through it, the closure gets a
        // plain scalar bit pattern as its "cell pointer" — and the
        // closure's first `jit_arc_shared_retain` on that value
        // segfaults. Driving the side-table off the layout's
        // `CaptureKind::Shared` mask closes the gap: any slot that is
        // an operand of a Shared capture in a call to a layout-carrying
        // function is promoted to the Arc<SharedCell> lowering path.
        use shape_value::v2::closure_layout::CaptureKind;
        use shape_vm::mir::types::{Operand as MirOperand, Place as MirPlace, StatementKind};
        for block in &mir_data.mir.blocks {
            for stmt in &block.statements {
                let StatementKind::ClosureCapture {
                    operands,
                    function_id,
                    ..
                } = &stmt.kind
                else {
                    continue;
                };
                let Some(fid) = *function_id else {
                    continue;
                };
                let Some(layout) = closure_function_layouts.get(&fid) else {
                    continue;
                };
                for (i, op) in operands.iter().enumerate() {
                    if i >= layout.capture_count() {
                        break;
                    }
                    if !matches!(layout.capture_storage_kind(i), CaptureKind::Shared) {
                        continue;
                    }
                    let root = match op {
                        MirOperand::Copy(p)
                        | MirOperand::Move(p)
                        | MirOperand::MoveExplicit(p) => match p {
                            MirPlace::Local(s) => Some(*s),
                            _ => None,
                        },
                        MirOperand::Constant(_) => None,
                    };
                    if let Some(slot) = root {
                        if param_slot_set.contains(&slot) {
                            // Capture-side slot: handled by the
                            // `shared_capture_slots` side-table via
                            // `register_owned_mutable_capture_slots`.
                            continue;
                        }
                        shared_local_slots.insert(slot);
                    }
                }
            }
        }

        // JIT-side fallback for unresolved `ClosurePlaceholder` constants.
        // See the `closure_placeholder_fids` doc-comment on `MirToIR` for
        // why this is needed; in short, monomorphization's `compile_function`
        // clears `closure_function_ids` in the bytecode compiler before the
        // top-level MIR back-patching runs, so some placeholders leak into
        // the MIR we receive. This scan produces the same pairing the
        // bytecode's back-patcher would have, keyed on MIR traversal order.
        let closure_placeholder_fids =
            scan_closure_placeholder_fids(&mir_data.mir, function_indices);

        // W12-jit-binop-after-heap-read-kind-tracker (ADR-006 §2.7.5):
        // pre-pass the MIR for every `StatementKind::ObjectStore` and
        // record each named operand's inferred kind. This makes
        // `Place::Field(_, field_idx)` reads available with a proven
        // kind at JIT compile time, so the downstream `Rvalue::BinaryOp`
        // lowering picks the typed inline arithmetic path instead of
        // surfacing `compile_binop_dynamic_arith`. Pre-pass placement
        // (rather than during `compile_statement`) makes the kind
        // available for cross-block field reads, mirroring how
        // `infer_slot_kinds` and the §2.7.5 conduit's
        // `infer_top_level_concrete_types_from_mir` already work.
        let field_native_kinds =
            types::infer_field_native_kinds(&mir_data.mir, &slot_kinds);

        // Phase 4b Round 5c-2-α jit-ref-param-chain-stamp (ADR-006 §2.7.13
        // ref-chain stamp + §2.7.5 producer-side stamp; supervisor ratify
        // 2026-05-19). Populate `ref_param_slots` from MIR-lowering's
        // `param_reference_kinds` — entries with `Some(BorrowKind::_)` are
        // reference parameters whose slot holds the BORROWED CELL ADDRESS
        // (allocated by `Rvalue::Borrow` in the caller's frame), NOT the
        // referenced value directly. Read/write sites for these slots
        // dispatch through the cell-indirection path; see
        // `read_place` / `write_place` / `null_place` and the
        // `Rvalue::Borrow` short-circuit in `rvalues.rs`.
        let ref_param_slots: HashSet<SlotId> = mir_data
            .mir
            .param_slots
            .iter()
            .zip(mir_data.mir.param_reference_kinds.iter())
            .filter_map(|(slot, kind)| kind.as_ref().map(|_| *slot))
            .collect();

        Self {
            builder,
            ctx_ptr,
            ffi,
            entry_block,
            block_map: HashMap::new(),
            locals: HashMap::new(),
            local_types,
            slot_kinds,
            concrete_types,
            next_var: 0,
            mir: &mir_data.mir,
            mir_data,
            strings,
            function_indices,
            user_func_refs,
            user_func_arities,
            ref_stack_slots: HashMap::new(),
            field_byte_offsets: HashMap::new(),
            field_native_kinds,
            field_array_elem_kinds: HashMap::new(),
            non_escaping_closure_slots,
            stack_closure_slots: HashMap::new(),
            stack_closure_call_info: HashMap::new(),
            closure_function_layouts,
            owned_mutable_capture_slots: HashMap::new(),
            shared_capture_slots: HashMap::new(),
            shared_local_slots,
            closure_placeholder_fids,
            next_closure_placeholder_idx: std::cell::Cell::new(0),
            bounds_elision: bounds_elision::BoundsElisionPlan::default(),
            // V3-S6c: side-table + caller-id default empty/None; populated
            // by `set_monomorph_routing_context` from the JIT compile
            // orchestration layer (`compiler/program.rs` per-function path +
            // `compiler/strategy.rs` top-level path).
            monomorphized_method_call_sites: HashMap::new(),
            caller_function_id: None,
            // W10 jit-call-method-user-trait-fix: operator-trait-dispatch
            // side-table default empty; populated by
            // `set_operator_trait_dispatch_sites` from the JIT orchestration
            // layer. Empty is sound — JIT falls through to typed-arith/cmp
            // lowering identically to pre-W10 behaviour.
            operator_trait_dispatch_sites: HashMap::new(),
            ref_param_slots,
        }
    }

    /// W10 jit-call-method-user-trait-fix (2026-05-17): install the
    /// bytecode compiler's `operator_trait_dispatch_sites` side-table so
    /// `compile_rvalue`'s `Rvalue::BinaryOp` / `Rvalue::UnaryOp` arms can
    /// re-emit user-type operator overloading as a method call. Sibling
    /// of `set_monomorph_routing_context` — same threading pattern.
    pub fn set_operator_trait_dispatch_sites(
        &mut self,
        sites: HashMap<shape_ast::ast::span::Span, (String, u16)>,
    ) {
        self.operator_trait_dispatch_sites = sites;
    }

    /// V3-S6c JIT method-monomorph routing: install the bytecode compiler's
    /// `monomorphized_method_call_sites` side-table + the caller function
    /// id used for the `(span, caller_function_id)` composite key. Callers
    /// normally clone `program.monomorphized_method_call_sites` and pass
    /// the post-monomorphization `func_idx: usize` (per-function path) or
    /// `None` (top-level path). An empty map / `None` caller is sound —
    /// every Method-call falls through to the existing `jit_call_method`
    /// trampoline path, preserving V3-S6b baseline behaviour.
    pub fn set_monomorph_routing_context(
        &mut self,
        sites: HashMap<(shape_ast::ast::span::Span, Option<usize>), usize>,
        caller_function_id: Option<usize>,
    ) {
        self.monomorphized_method_call_sites = sites;
        self.caller_function_id = caller_function_id;
    }

    /// Install a precomputed bounds-elision plan so `Place::Index` codegen
    /// can skip the inline bounds check on trusted access pairs.
    ///
    /// Callers normally invoke `bounds_elision::analyze(&mir_data.mir)` and
    /// pass the result here. Leaving the plan empty (the default) is
    /// always sound — every access falls back to the bounds-checked path,
    /// matching pre-elision behaviour and preserving the v2_array_tests
    /// OOB zero-default semantics.
    pub fn set_bounds_elision_plan(&mut self, plan: bounds_elision::BoundsElisionPlan) {
        self.bounds_elision = plan;
    }

    /// W14.2-E-followup-jit-trait-method-arity-soundness fix (SURFACE-A2,
    /// 2026-05-19, v0.3-gating SOUNDNESS BUG): pre-populate
    /// `field_byte_offsets` from the program's `type_schema_registry` for
    /// every field name visible in this function's MIR `field_name_table`.
    ///
    /// **Background.** The existing `field_byte_offsets` map is populated
    /// only by `StatementKind::ObjectStore` walks at codegen time
    /// (`mir_compiler/statements.rs:243`). Trait-impl method bodies (and
    /// generally any function that READS fields but does not CONSTRUCT
    /// typed objects) never emit `ObjectStore`, so the map stays empty
    /// and `try_resolve_field_byte_offset` returns `None`. Field reads
    /// then fall through to the `jit_get_prop(obj_bits, key_bits)` FFI
    /// (`places.rs:899-906`), whose `heap_kind(obj_bits)` discriminator
    /// (`ffi/value_ffi.rs:331-336`) requires `is_heap(bits)` — i.e.
    /// `is_tagged(bits) && get_tag(bits) == TAG_HEAP_BITS`. Under ADR-006
    /// §2.7.5 the JIT typed-object allocator (`jit_typed_object_alloc` at
    /// `ffi/typed_object/allocation.rs:83`) returns raw `Box::into_raw`
    /// pointers without NaN-box tag bits, so `is_heap` always returns
    /// false and `jit_get_prop` returns `TAG_NULL` for a TypedObject
    /// receiver — the empirical garbage NaN-bits at the
    /// `vm_trait_method_self_field_access_n0` reproducer.
    ///
    /// **Fix.** Use the program-wide schema registry to map each field
    /// name in the MIR to its position in the carrying schema. The JIT
    /// data layout (`typed_object_alloc(schema_id, field_count * 8)`)
    /// uses 8-byte slots per field regardless of declared field type, so
    /// `byte_offset = field_index * 8`. Same shape as the existing
    /// ObjectStore-walk at `statements.rs:243`.
    ///
    /// **Discriminator caveat.** This shares the "last-writer-wins on
    /// name collision across distinct struct types" caveat documented at
    /// `field_native_kinds`'s comment (mod.rs:170-180). For impl method
    /// bodies the receiver is one specific struct type, so the collision
    /// is benign in practice; the principled schema-aware
    /// `(StructLayoutId, FieldIdx) → offset` registry remains the
    /// long-term shape per that comment's "out of scope" note. The W12-
    /// jit-binop-after-heap-read-kind-tracker invariant is preserved:
    /// when a function contains both ObjectStore (local-populate at
    /// statements.rs:243) AND field reads on different types, the
    /// schema-pre-pass runs FIRST (here, at MirToIR construction time)
    /// and the local ObjectStore-walk overwrites for the constructed
    /// type — matching the existing single-name single-offset contract.
    ///
    /// Per ADR-006 §2.7.5 producer-side stamp: schema field positions
    /// are stamped at AST→bytecode-compile time (the canonical schema
    /// registry); the JIT's `field_byte_offsets` is a derived index, not
    /// a runtime decode.
    pub fn populate_field_byte_offsets_from_schemas(
        &mut self,
        registry: &shape_runtime::type_schema::TypeSchemaRegistry,
    ) {
        use shape_runtime::type_schema::FieldType;
        // Collect every field name referenced in this function's MIR.
        let referenced_names: std::collections::HashSet<&str> = self
            .mir
            .field_name_table
            .values()
            .map(|s| s.as_str())
            .collect();

        // Schema FieldType → NativeKind projection. Mirrors the JIT
        // slot encoding for typed-object fields: every field occupies an
        // 8-byte slot regardless of the declared field width, so the
        // NativeKind classification follows the field's declared type
        // (Int64 for `int` / I64, Float64 for `number` / F64, Bool for
        // `bool`, String for `string`, etc.). Width-specific integers
        // project to Int64 since they are stored as raw i64 bits in the
        // 8-byte JIT slot (the alignment-clamped layout at
        // `mir_compiler/statements.rs:233`).
        fn field_type_to_native_kind(ft: &FieldType) -> Option<shape_value::NativeKind> {
            use shape_value::NativeKind;
            match ft {
                FieldType::F64 => Some(NativeKind::Float64),
                FieldType::I64 => Some(NativeKind::Int64),
                FieldType::Bool => Some(NativeKind::Bool),
                FieldType::String => Some(NativeKind::String),
                // Width-specific ints project to Int64 in the JIT slot —
                // they are stored as raw i64 bits per the typed-object
                // 8-byte slot encoding.
                FieldType::I8
                | FieldType::U8
                | FieldType::I16
                | FieldType::U16
                | FieldType::I32
                | FieldType::U32
                | FieldType::U64 => Some(NativeKind::Int64),
                FieldType::Timestamp => Some(NativeKind::Int64),
                // Object/Array/Decimal/Any/HashMap/Set: not projected —
                // leave as None so the downstream consumer falls back to
                // the existing surface-and-stop / FFI dispatch path. The
                // principled projection for nested-object fields
                // requires a typed pointer kind that the JIT-side
                // carrier discipline (`Ptr(HeapKind::TypedObject)`) does
                // not yet thread through schema-recovered reads (W10
                // jit-playbook §5). W17.3-4.1 adds HashMap/Set to the
                // same None-fallback shape as Array/Option — runtime
                // dispatch + JIT typed-pointer-kind threading for the
                // new containers lands at W17.3-4.3.
                FieldType::Object(_)
                | FieldType::Array(_)
                | FieldType::Option(_)
                | FieldType::Decimal
                | FieldType::Any
                | FieldType::HashMap { .. }
                | FieldType::Set(_) => None,
            }
        }

        // γ-CP5 7a (jit-typedarray-ptr): project the *element* type of a
        // scalar `Array<T>` field declaration into the matching v2
        // typed-array element `NativeKind`. Mirrors
        // `mir_compiler/types.rs::elem_slot_kind_for_concrete` (which
        // operates on `ConcreteType`); here the source is the schema's
        // declared `FieldType`. Non-scalar element types
        // (`Object`/`Array`/`Option`/`Any`) and `Decimal` return `None`
        // — those need heap-element carrier discipline the inline
        // `v2_array_get` fast path does not provide, so the consumer
        // falls back to the legacy NaN-boxed array path. `String`
        // elements likewise return `None`: `Array<string>` reads through
        // the v2-raw `*const StringObj` carrier need a retain-on-read
        // that the scalar `v2_array_get` does not emit.
        fn array_elem_to_native_kind(ft: &FieldType) -> Option<shape_value::NativeKind> {
            use shape_value::NativeKind;
            let FieldType::Array(elem) = ft else {
                return None;
            };
            match elem.as_ref() {
                FieldType::F64 => Some(NativeKind::Float64),
                FieldType::I64 | FieldType::Timestamp => Some(NativeKind::Int64),
                FieldType::Bool => Some(NativeKind::Bool),
                FieldType::I8 | FieldType::U8 => Some(NativeKind::Int8),
                FieldType::I16 | FieldType::U16 => Some(NativeKind::Int16),
                FieldType::I32 | FieldType::U32 => Some(NativeKind::Int32),
                FieldType::U64 => Some(NativeKind::UInt64),
                FieldType::String
                | FieldType::Decimal
                | FieldType::Object(_)
                | FieldType::Array(_)
                | FieldType::Option(_)
                | FieldType::Any
                // W17.3-4.1 — HashMap<K, V> / Set<T> elements are
                // not scalar element types; fall back to legacy
                // NaN-boxed array path (matches Array/Option shape).
                | FieldType::HashMap { .. }
                | FieldType::Set(_) => None,
            }
        }

        // Walk every registered schema; map name → position (i*8).
        // Existing `field_byte_offsets` / `field_native_kinds` entries
        // from the local ObjectStore-walk (statements.rs:243 +
        // `infer_field_native_kinds` at types.rs:1534, populated at
        // construction / codegen time) take precedence — we only insert
        // when absent so the local-walk's per-constructor stamp wins on
        // collision.
        for type_name in registry.type_names().collect::<Vec<_>>() {
            let Some(schema) = registry.get(type_name) else {
                continue;
            };
            for (i, field) in schema.fields.iter().enumerate() {
                if !referenced_names.contains(field.name.as_str()) {
                    continue;
                }
                // 8-byte JIT slot offsets per `typed_object_alloc(
                // schema_id, field_count * 8)` at
                // `mir_compiler/statements.rs:233`.
                let byte_off = (i as u16) * 8;
                self.field_byte_offsets
                    .entry(field.name.clone())
                    .or_insert(byte_off);
                // Per ADR-006 §2.7.5 producer-side stamp: project the
                // schema's declared FieldType into the matching
                // NativeKind so `place_native_kind(Place::Field(...))`
                // can return a precise kind for impl-method-body field
                // reads. The downstream `compile_rvalue::BinaryOp`
                // picker reads this kind via `operand_slot_kind` →
                // `place_native_kind` → `field_native_kinds.get(name)`
                // (see `mir_compiler/rvalues.rs:496-516`) to select the
                // typed inline arithmetic path (`compile_binop_int64` /
                // `compile_binop_f64`) instead of surfacing
                // `compile_binop_dynamic_arith`. Without this stamp
                // `self.value * 2` in an impl method body falls into
                // the dynamic-arith surface-and-stop arm — the empirical
                // SURFACE-A2 garbage NaN-bits root cause.
                if let Some(kind) = field_type_to_native_kind(&field.field_type) {
                    self.field_native_kinds
                        .entry(field.name.clone())
                        .or_insert(kind);
                }
                // γ-CP5 7a: stamp the v2 typed-array element kind for
                // scalar `Array<T>` fields so `v2_typed_array_elem_kind`
                // can recognise a `Place::Field` base and emit the v2
                // inline `v2_array_get` codegen (v2 layout data@8/len@16).
                if let Some(elem_kind) = array_elem_to_native_kind(&field.field_type) {
                    self.field_array_elem_kinds
                        .entry(field.name.clone())
                        .or_insert(elem_kind);
                }
            }
        }
    }

    /// Track A.1D.2: register the leading capture param slots that back
    /// an `OwnedMutable` capture cell for the closure body currently being
    /// compiled.
    ///
    /// `captures_count` is the number of leading entries in
    /// `MirFunction::param_slots` that correspond to closure captures
    /// (the caller ABI stores captures before user params: `[ctx_ptr,
    /// capture_0..N, user_param_0..M]`). `layout` is the
    /// `ClosureLayout` for this function's `function_id`, so
    /// `layout.capture_storage_kind(i)` reports the per-capture
    /// `CaptureKind`. Slots whose kind is `OwnedMutable` are flagged —
    /// `read_place` and `write_place` then emit a pointer-deref load /
    /// store through the raw `*mut ValueWord` bits, matching the A.1B
    /// interpreter handlers.
    ///
    /// Also patches `self.slot_kinds` for each capture param slot using
    /// the layout's `capture_types[i]`. Closure params are untyped at
    /// the bytecode compiler level (see `compile_expr_closure` in
    /// `expressions/closures.rs` — capture params are synthesised with
    /// `type_annotation: None`), so MIR-level inference leaves them
    /// `Unknown`. Without per-capture kinds the `Rvalue::BinaryOp`
    /// lowering falls through to the dynamic-binop path, which
    /// unconditionally errors out (see `compile_binop` at
    /// `rvalues.rs::~411`). Patching the slot kind here lets the
    /// typed binop pickers (`compile_binop_int64`, `compile_binop_f64`,
    /// etc.) engage for `x + 1`-style closure-body arithmetic. For
    /// OwnedMutable slots, `read_place` always emits `load.i64` through
    /// the cell — the kind informs the binop picker about the inner
    /// value's representation (NaN-boxed int, NaN-boxed float, etc.),
    /// not the width of the slot itself.
    ///
    /// No-op for non-closure functions (`captures_count == 0`) and for
    /// closures whose layout marks every capture as `Immutable`. A.1E
    /// extends this registration to populate `shared_capture_slots`
    /// alongside `owned_mutable_capture_slots`; both side-tables are
    /// parallel in structure but drive different lowering paths (see
    /// their doc-comments on `MirToIR`).
    pub fn register_owned_mutable_capture_slots(
        &mut self,
        captures_count: u16,
        layout: &ClosureLayout,
    ) {
        use shape_value::v2::closure_layout::CaptureKind;
        let captures_count = captures_count as usize;
        if captures_count == 0 {
            return;
        }
        // Defensive: the layout must have a capture_kinds entry per
        // declared capture. A mismatch indicates a compiler bug upstream
        // (e.g. the layout was minted against a different signature); we
        // clamp to the smaller of the two so no out-of-bounds panics
        // slip into release builds.
        let len = captures_count.min(layout.capture_kinds.len());
        for (i, &param_slot) in self
            .mir
            .param_slots
            .iter()
            .take(len)
            .enumerate()
        {
            let capture_kind = layout.capture_storage_kind(i);
            let is_cell_capture = matches!(
                capture_kind,
                CaptureKind::OwnedMutable | CaptureKind::Shared
            );
            if !is_cell_capture {
                continue;
            }
            // Wave C.2: capture the cell's interior FieldKind alongside
            // the slot id so `read_place`/`write_place` can pick the
            // matching per-kind FFI helper instead of NaN-boxing through
            // the legacy ValueWord-bits path.
            let inner_kind = layout.capture_inner_kind(i);
            match capture_kind {
                CaptureKind::OwnedMutable => {
                    self.owned_mutable_capture_slots
                        .insert(param_slot, inner_kind);
                }
                CaptureKind::Shared => {
                    self.shared_capture_slots.insert(param_slot, inner_kind);
                }
                CaptureKind::Immutable => unreachable!(),
            }
            // Propagate the layout's known concrete type onto the
            // slot kind vector so `Rvalue::BinaryOp` lowering can
            // pick the typed arithmetic path. Only patch when the
            // slot was previously `Unknown`; a non-Unknown kind
            // from the bytecode frame descriptor wins. Same
            // treatment applies to OwnedMutable and Shared — in
            // both cases `read_place` returns an I64 ValueWord-
            // shaped value and the downstream binop picker keys on
            // the kind, not the cell-pointer width itself.
            if let Some(concrete) = layout.capture_types.get(i) {
                if let Some(kind) = types::elem_slot_kind_for_concrete(concrete) {
                    let idx = param_slot.0 as usize;
                    if idx < self.slot_kinds.len() && self.slot_kinds[idx].is_none() {
                        self.slot_kinds[idx] = Some(kind);
                    }
                }
            }
        }
    }

    /// Compile the MIR function to Cranelift IR.
    ///
    /// Returns Ok(()) on success. The actual return instructions are emitted
    /// by compile_terminator for TerminatorKind::Return blocks.
    /// Full compilation: create blocks, declare locals, initialize, compile body.
    /// Used when the caller hasn't set up blocks/locals externally.
    pub fn compile(&mut self) -> Result<(), String> {
        self.create_blocks();
        self.declare_locals();
        // Session 1 Commit 3: eagerly materialise Arc<SharedCell>s for
        // every SharedCow local slot. No-op when the set is empty.
        self.initialize_shared_local_slots();
        self.compile_body()
    }

    /// Compile the MIR function body (blocks already created, locals already declared).
    /// Called after the caller has optionally stored function params to local variables.
    /// `param_count` indicates how many leading slots are function params (skip init).
    pub fn compile_body(&mut self) -> Result<(), String> {
        // Cluster-2 closure-wave-F tracing-crate migration (2026-05-16):
        // replaces SHAPE_JIT_MIR_TRACE env-var. CLI selector is
        // `--trace-jit=shape_jit::mir=trace`. The enabled-check gates the
        // entire MIR-walk so feature-OFF builds skip the iteration cost.
        if tracing::enabled!(target: "shape_jit::mir", tracing::Level::TRACE) {
            for (bi, block) in self.mir.blocks.iter().enumerate() {
                tracing::trace!(
                    target: "shape_jit::mir",
                    bb = bi,
                    stmts = block.statements.len(),
                    term = ?block.terminator.kind,
                    "mir-trace block",
                );
                for (si, stmt) in block.statements.iter().enumerate() {
                    tracing::trace!(
                        target: "shape_jit::mir",
                        bb = bi,
                        s = si,
                        stmt = ?stmt.kind,
                        "mir-trace statement",
                    );
                }
            }
        }
        for block_idx in 0..self.mir.blocks.len() {
            let block = &self.mir.blocks[block_idx];
            let cl_block = self.block_map[&block.id];

            // bb0 is the caller's entry block — already switched to and sealed.
            // For other blocks, switch to the new block.
            if block_idx != 0 {
                self.builder.switch_to_block(cl_block);
            }

            // DON'T initialize locals here — the caller has already:
            // 1. Called declare_locals() (all vars declared)
            // 2. Stored function params to their slots (params have real values)
            // Cranelift's SSA handles undefined variables as 0/default.

            // Compile statements.
            for stmt in &block.statements {
                self.compile_statement(stmt)?;
            }

            // Compile terminator.
            self.compile_terminator(&block.terminator)?;
        }

        // Seal all blocks after all code is emitted. Sealing before all
        // predecessors are known causes Cranelift assertion failures.
        self.builder.seal_all_blocks();

        Ok(())
    }

    /// Reload all locals that have been borrowed via Rvalue::Borrow.
    ///
    /// After a function call, the callee may have mutated values through
    /// shared references. We conservatively reload all referenced locals
    /// from their StackSlots to keep Cranelift variables in sync.
    ///
    /// R4.2F: stack cells are now native-sized/aligned (matching the root
    /// local's Cranelift type), so `stack_load` directly produces a value
    /// of the declared variable's type — no NaN-box unboxing needed.
    pub(crate) fn reload_referenced_locals(&mut self) {
        let refs: Vec<_> = self
            .ref_stack_slots
            .iter()
            .map(|(&slot_id, &(stack_slot, cl_ty))| (slot_id, stack_slot, cl_ty))
            .collect();
        for (slot_id, stack_slot, cl_ty) in refs {
            let reloaded = self.builder.ins().stack_load(cl_ty, stack_slot, 0);
            if let Some(&var) = self.locals.get(&slot_id) {
                self.builder.def_var(var, reloaded);
            }
        }
    }
}

pub(crate) mod v2_call_abi;

/// Reconstruct the bytecode compiler's back-patch pairing for unresolved
/// `ClosurePlaceholder` constants in a MIR function, keyed on statement
/// traversal order.
///
/// # Why this exists
///
/// The bytecode compiler's `closure_function_ids` vector — the list of
/// `("__closure_N", function_id)` pairs used to patch
/// `MirConstant::ClosurePlaceholder` into `MirConstant::Function(name)` —
/// is cleared by `compile_function` (see
/// `shape-vm/src/compiler/functions.rs:510`). Monomorphization triggered
/// during a top-level call (e.g. `arr.map(|x| x*2)`) goes through
/// `ensure_monomorphic_function` → `compile_function`, clearing the
/// vector even though the top-level MIR's back-patching hasn't yet run.
/// The result: any no-capture closure literal in top-level code leaks
/// into the top-level MIR as a raw `ClosurePlaceholder`.
///
/// The downstream effect is that `compile_constant` lowers the
/// placeholder to a literal `iconst 0`, the callsite pushes `0x0` as the
/// callee, and `jit_call_value` BAILs with "callee is neither function
/// nor closure". The gated `parity_array_map/filter/reduce` tests all
/// hit this exact path.
///
/// # Scan semantics
///
/// Mirrors the bytecode compiler's loop in
/// `functions.rs::compile_function` (and the top-level analogue in
/// `compiler_impl_reference_model.rs`): walk every block's statement
/// list; a `ClosureCapture` with a resolved `function_id` "claims" the
/// immediately-following `ClosurePlaceholder` (which the patcher rewrites
/// to `Nop`), so the placeholder does NOT need independent resolution.
/// An unpaired placeholder consumes the next `__closure_<idx>` name.
///
/// # Name-to-id lookup
///
/// We can't consult `closure_function_ids` from the JIT, but
/// `function_indices` (built from `BytecodeProgram::functions`) has every
/// `__closure_N` entry in the same global ordering the bytecode compiler
/// assigned. Looking up `__closure_<idx>` directly produces the correct
/// function_id for each unpaired placeholder, in the same sequence the
/// unpatched back-patcher would have produced.
///
/// # Graceful degradation
///
/// If the lookup misses (e.g. a malformed program where `__closure_<idx>`
/// is absent), we push `u16::MAX` as a sentinel. `compile_constant`'s
/// fallback path then emits the legacy `iconst 0` so behaviour is no
/// worse than before this scan.
fn scan_closure_placeholder_fids(
    mir: &shape_vm::mir::types::MirFunction,
    function_indices: &std::collections::HashMap<String, u16>,
) -> Vec<u16> {
    use shape_vm::mir::types::{MirConstant, Operand, Rvalue, StatementKind};

    let mut result: Vec<u16> = Vec::new();
    let mut closure_idx: u32 = 0;
    let mut has_capture = false;
    for block in &mir.blocks {
        for stmt in &block.statements {
            let is_placeholder = matches!(
                &stmt.kind,
                StatementKind::Assign(
                    _,
                    Rvalue::Use(Operand::Constant(MirConstant::ClosurePlaceholder))
                )
            );
            if is_placeholder {
                if has_capture {
                    // Paired with a preceding ClosureCapture — the
                    // bytecode back-patcher would have turned this into
                    // a Nop. compile_constant still receives the
                    // placeholder for this slot (the patched MIR would
                    // not), so we record u16::MAX and let the fallback
                    // iconst(0) fire; ClosureCapture's function_id
                    // drives the actual closure allocation in
                    // `emit_heap_closure` / `emit_stack_closure`, and
                    // the subsequent Assign(slot, placeholder) is a
                    // dead store that write_place discards.
                    result.push(u16::MAX);
                    has_capture = false;
                } else {
                    let name = format!("__closure_{}", closure_idx);
                    let fid = function_indices.get(&name).copied().unwrap_or(u16::MAX);
                    result.push(fid);
                    closure_idx = closure_idx.saturating_add(1);
                }
                continue;
            }
            if let StatementKind::ClosureCapture {
                function_id: Some(_),
                ..
            } = &stmt.kind
            {
                // The bytecode patcher consumes one closure_id for the
                // capture itself — advance the counter so the unpaired
                // placeholder counter stays aligned with the compiler's.
                closure_idx = closure_idx.saturating_add(1);
                has_capture = true;
            }
        }
    }
    result
}