synth_backend/

arm_backend.rs

//! ARM Backend — wraps the instruction selector + optimizer + encoder as a Backend
//!
//! This is Synth's custom ARM compiler targeting Cortex-M (Thumb-2).
//! It's the only backend that supports per-rule formal verification (ASIL D path).

use crate::ArmEncoder;
use synth_core::backend::{
    Backend, BackendCapabilities, BackendError, CodeRelocation, CompilationResult, CompileConfig,
    CompiledFunction, LineMap, SafetyBounds,
};
use synth_core::target::{IsaVariant, TargetSpec};
use synth_core::wasm_decoder::DecodedModule;
use synth_core::wasm_op::WasmOp;
use synth_synthesis::{
    ArmInstruction, ArmOp, BoundsCheckConfig, InstructionSelector, OptimizationConfig,
    OptimizerBridge, RuleDatabase, validate_instructions,
};

/// ARM Cortex-M backend using Synth's custom compiler pipeline
pub struct ArmBackend;

impl ArmBackend {
    pub fn new() -> Self {
        Self
    }
}

impl Default for ArmBackend {
    fn default() -> Self {
        Self::new()
    }
}

impl Backend for ArmBackend {
    fn name(&self) -> &str {
        "arm"
    }

    fn capabilities(&self) -> BackendCapabilities {
        BackendCapabilities {
            produces_elf: false,
            supports_rule_verification: true,
            supports_binary_verification: true,
            is_external: false,
        }
    }

    fn supported_targets(&self) -> Vec<TargetSpec> {
        vec![
            TargetSpec::cortex_m3(),
            TargetSpec::cortex_m4(),
            TargetSpec::cortex_m4f(),
            TargetSpec::cortex_m7(),
            TargetSpec::cortex_m7dp(),
        ]
    }

    fn compile_module(
        &self,
        module: &DecodedModule,
        config: &CompileConfig,
    ) -> Result<CompilationResult, BackendError> {
        let exports: Vec<_> = module
            .functions
            .iter()
            .filter(|f| f.export_name.is_some())
            .collect();

        if exports.is_empty() {
            return Err(BackendError::CompilationFailed(
                "no exported functions found".into(),
            ));
        }

        let mut functions = Vec::new();
        for func in &exports {
            let name = func.export_name.clone().unwrap();
            // #359: copy THIS function's declared param widths into the config so
            // `compile_function` (which carries no function index) can refuse a
            // 64-bit param on the AAPCS stack-argument path. Cheap clone only when
            // a signature table is present and this function has a width entry —
            // otherwise reuse the shared config (every existing module unchanged).
            // #509: same per-function pattern for the blocktype-arity side-table
            // (value-carrying-branch lowering).
            let params = config
                .func_params_i64
                .get(func.index as usize)
                .filter(|p| !p.is_empty());
            // #457: THIS function's DECLARED param count (imports-first full
            // index), so the backend can cap the access-pattern inference that
            // mistook a read-before-write local for a param. `None` when the
            // driver supplied no arg-count table (hand-built modules).
            let declared_params = config.func_arg_counts.get(func.index as usize).copied();
            // GI-FPU-002 (#619/#369): THIS function's declared f32-param mask.
            let params_f32 = config
                .func_params_f32
                .get(func.index as usize)
                .filter(|p| !p.is_empty());
            // GI-FPU-002 phase 2 (#369): THIS function's declared f64-param
            // mask (hard-float targets decline f64 params loudly).
            let params_f64 = config
                .func_params_f64
                .get(func.index as usize)
                .filter(|p| !p.is_empty());
            // GI-FPU-002 phase 2 (#719/#369): THIS function's declared f32/f64
            // return flag, so the epilogue soundness guard fires on every driver
            // path (not only the CLI loops).
            let ret_f32 = config
                .func_ret_f32
                .get(func.index as usize)
                .copied()
                .unwrap_or(false);
            let ret_f64 = config
                .func_ret_f64
                .get(func.index as usize)
                .copied()
                .unwrap_or(false);
            // #1214: THIS function's declared-i64-local side-table. Guarded by
            // `.any(i64)`, not `!is_empty()` — every function with ANY declared
            // local (i32 included) has a non-empty vector, and that would
            // widen this memoization guard to nearly every function for no
            // reason; only a function that actually declares an i64 local
            // needs the extra clone.
            let declared_i64_locals = &func.declared_i64_locals;
            let func_config = if params.is_some()
                || params_f32.is_some()
                || params_f64.is_some()
                || !func.block_arity.is_empty()
                || declared_params.is_some()
                || ret_f32
                || ret_f64
                || declared_i64_locals.iter().any(|&b| b)
            {
                Some(CompileConfig {
                    current_func_params_i64: params.cloned().unwrap_or_default(),
                    current_func_params_f32: params_f32.cloned().unwrap_or_default(),
                    current_func_params_f64: params_f64.cloned().unwrap_or_default(),
                    current_func_ret_f32: ret_f32,
                    current_func_ret_f64: ret_f64,
                    current_func_block_arity: func.block_arity.clone(),
                    current_func_declared_i64_locals: declared_i64_locals.clone(),
                    current_func_param_count: declared_params,
                    ..config.clone()
                })
            } else {
                None
            };
            let cfg = func_config.as_ref().unwrap_or(config);
            let compiled = self.compile_function(&name, &func.ops, cfg)?;
            functions.push(compiled);
        }

        Ok(CompilationResult {
            functions,
            elf: None,
            backend_name: self.name().to_string(),
        })
    }

    fn compile_function(
        &self,
        name: &str,
        ops: &[WasmOp],
        config: &CompileConfig,
    ) -> Result<CompiledFunction, BackendError> {
        let (code, relocations, line_map, branch_map, final_instrs) =
            compile_wasm_to_arm(ops, config).map_err(BackendError::CompilationFailed)?;

        // #778: derive the SOUND static WCET intermediate from the final Thumb-2
        // stream. Only present for the Thumb-2 path; the core class (from the
        // triple) decides whether the bound is sound (M3/M4) or declined (M7).
        // Phase 2: any --wcet-hints entry for THIS function is verified (never
        // trusted) by the loop analyzer. Phase 3: the intermediate carries the
        // own-body cycles + direct call sites; the module driver composes it across
        // the call graph. `wcet` here is the SINGLE-FUNCTION view (unresolved direct
        // calls decline `call`) — a valid standalone answer, overwritten by the
        // composed result when the driver runs the second pass.
        let wcet_intermediate = final_instrs.as_ref().map(|instrs| {
            let hints = config
                .wcet_hints
                .as_ref()
                .and_then(|h| h.functions.get(name));
            let self_label = config.current_func_index.map(|i| format!("func_{i}"));
            crate::wcet::function_wcet_intermediate(
                name,
                instrs,
                &config.target.triple,
                hints,
                self_label.as_deref(),
            )
        });
        // The SINGLE-FUNCTION standalone view (unresolved direct calls decline
        // `call`). Kept as a per-function fallback for any consumer that reads a
        // lone `CompiledFunction` without running the module composer; the CLI
        // `--emit-wcet` path IGNORES this and composes `wcet_intermediate` across
        // the whole call graph instead (its result overwrites the report).
        // RQ-71-STACKDEPTH (#1341): the native-stack profile, from the SAME
        // final stream. Unconditional and cheap (one linear walk); the CLI
        // decides whether to report it. It is NOT gated on the WCET decline —
        // a data-dependent loop is WCET-unbounded and stack-bounded.
        let stack_frame = final_instrs
            .as_ref()
            .map(|instrs| crate::stack_depth::analyze_function(name, instrs));
        let wcet = final_instrs.map(|instrs| {
            let hints = config
                .wcet_hints
                .as_ref()
                .and_then(|h| h.functions.get(name));
            crate::wcet::function_wcet_with_hints(name, &instrs, &config.target.triple, hints)
        });

        Ok(CompiledFunction {
            name: name.to_string(),
            code,
            wasm_ops: ops.to_vec(),
            relocations,
            line_map,
            branch_map,
            wcet,
            wcet_intermediate,
            stack_frame,
        })
    }

    fn is_available(&self) -> bool {
        true // Always available — it's a library backend
    }
}

/// Count the number of function parameters by analyzing LocalGet patterns
/// RQ-58-MIRRORS (#242): was a private copy of the read-before-write param
/// heuristic, byte-equivalent to the other two backends'. Now the ONE shared
/// definition in `synth-core`, so a correction reaches every backend.
fn count_params(wasm_ops: &[WasmOp]) -> u32 {
    synth_core::count_params_heuristic(wasm_ops)
}

/// #457/#970: the parameter count the selector is given.
///
/// With a DECLARED count from the driver the bound is
/// `min(`[`synth_core::referenced_locals`]`(ops), declared)` — the highest
/// local index the body touches, clamped by the signature. That is exact in
/// both directions: the clamp stops a read-before-write NON-PARAM local (which
/// WASM zero-initializes) from being homed in an argument register and reading
/// caller garbage (#457), and taking the max over ALL accesses — writes as well
/// as reads — stops a PARAM from being demoted to a local.
///
/// The previous rule capped [`count_params`] (a READ-FIRST heuristic) with the
/// declared count, which got the second direction wrong: a param written on ONE
/// arm of an `if` is "written first" in linear op order, so it was demoted, and
/// because the demoted local's first access is a WRITE the #457 zero-init
/// skipped it too. The arm that does NOT write it then read an UNINITIALISED
/// frame slot — measured under unicorn with the sub-SP stack poisoned,
/// `cond_write_param(0, 42)` returned the poison word, i.e. previous-frame
/// bytes rather than 42 (#970; the aarch64 instance was #851).
///
/// `min` rather than a plain `declared` override preserves the leniency for a
/// body that only touches the first few of many declared params.
///
/// `None` (no declared signature: hand-built op streams, direct
/// `compile_function` callers) keeps the legacy pure inference — see the
/// residual documented on [`CompileConfig::current_func_param_count`].
fn effective_num_params(wasm_ops: &[WasmOp], config: &CompileConfig) -> u32 {
    match config.current_func_param_count {
        Some(declared) => synth_core::referenced_locals(wasm_ops).min(declared),
        None => count_params(wasm_ops),
    }
}

/// #539: fold the `i32.const 0; memory.grow m` idiom to `memory.size m`.
/// Moved to `synth_core::rewrite_memory_grow_zero` (#242, VCR-SEL-005) so the
/// ARM and RISC-V backends share ONE implementation and cannot drift; re-export
/// here keeps the existing `rewrite_memory_grow_zero(...)` call sites working.
use synth_core::rewrite_memory_grow_zero;

/// #509: does the op stream contain a `br`/`br_if`/`br_table` that CARRIES a
/// value — i.e. one targeting a result-typed block/if (forward edge with
/// results > 0) or a parameterized loop header (backward edge with loop
/// params > 0)?
///
/// The optimized path's wasm→IR lowering drops the carried value on such
/// edges (the taken arm returns the fall-through result — same class as the
/// #507 `br_table` drop, observed on `pick_br`/`pick_br_fall`), so — like
/// #507 — the shape is detected on the raw op stream and routed to the direct
/// selector, whose #509 designated-result-register lowering lands the value
/// correctly. `block_arity` is the decoder's ordinal blocktype-arity
/// side-table; when it is empty (hand-built op streams) every block reads as
/// void and this never fires, keeping the optimized path byte-identical for
/// every existing caller. Frozen-safe for the same reason as #507: the frozen
/// fixtures compile `--relocatable` (already direct), and no optimized-path
/// fixture branches to a result-typed block.
fn has_value_carrying_branch(wasm_ops: &[WasmOp], block_arity: &[(u8, u8)]) -> bool {
    // Open control constructs: (is_loop, params, results), innermost last.
    let mut open: Vec<(bool, u8, u8)> = Vec::new();
    let mut ctrl_ord = 0usize;
    // A branch edge carries a value when its target is a result-typed forward
    // join (block/if) or a parameterized loop header.
    let carries = |open: &[(bool, u8, u8)], depth: u32| -> bool {
        let Some(&(is_loop, params, results)) = open
            .len()
            .checked_sub(1 + depth as usize)
            .and_then(|i| open.get(i))
        else {
            return false; // function-level target — handled by Return lowering
        };
        if is_loop { params > 0 } else { results > 0 }
    };
    for op in wasm_ops {
        match op {
            WasmOp::Block | WasmOp::If => {
                let (p, r) = block_arity.get(ctrl_ord).copied().unwrap_or((0, 0));
                ctrl_ord += 1;
                open.push((false, p, r));
            }
            WasmOp::Loop => {
                let (p, r) = block_arity.get(ctrl_ord).copied().unwrap_or((0, 0));
                ctrl_ord += 1;
                open.push((true, p, r));
            }
            WasmOp::End => {
                open.pop(); // None only at the function-level end — harmless
            }
            WasmOp::Br(d) | WasmOp::BrIf(d) if carries(&open, *d) => return true,
            WasmOp::BrTable { targets, default }
                if targets
                    .iter()
                    .chain(std::iter::once(default))
                    .any(|d| carries(&open, *d)) =>
            {
                return true;
            }
            _ => {}
        }
    }
    false
}

/// Core compilation: WASM ops → ARM machine code bytes + relocations
///
/// Returns (code_bytes, relocations) where relocations record BL instructions
/// that target external symbols (e.g., `__meld_dispatch_import` for import calls).
type CompileArmOutput = (
    Vec<u8>,
    Vec<CodeRelocation>,
    LineMap,
    synth_core::backend::BranchMap,
    // #778: the SOUND static WCET result over the final Thumb-2 stream, computed
    // by `compile_function` (which knows the function name); `None` for the A32
    // path. Purely additive metadata — does not touch `code`.
    Option<Vec<synth_synthesis::ArmInstruction>>,
);

/// RQ-71-STACKDEPTH/#345: one deferred `LdrSym` — where its placeholder LDR
/// sits, and what word the pool must carry for it.
struct PendingLiteral {
    ldr_offset: u32,
    symbol: String,
    addend: i32,
}

/// RQ-72-ISLANDS (#345, cpetig via #1331): emit ONE constant island — the
/// pooled words, optionally preceded by a branch over them — and patch each
/// pending LDR's `imm12` in place.
///
/// SINGLE SOURCE for both placements. The inline island and the
/// end-of-function pool differ in exactly one thing: whether execution can
/// fall into the words. That is `branch_over`. Writing the patch arithmetic
/// twice is how the two would drift, which is the failure this repo's North
/// Star correction is about.
///
/// THE REFUSAL IS PRESERVED, DELIBERATELY. If a literal is out of range even
/// from here, this still returns the #345 error rather than patching a wrong
/// offset. Islands widen WHERE a pool may sit; they do not widen the Thumb-2
/// LDR-literal encoding, which is a 12-bit unsigned field and always will be.
fn emit_literal_pool(
    code: &mut Vec<u8>,
    relocations: &mut Vec<CodeRelocation>,
    pending: &[PendingLiteral],
    branch_over: Option<&ArmEncoder>,
) -> Result<(), String> {
    if pending.is_empty() {
        return Ok(());
    }
    // A mid-stream island sits in the instruction stream, so execution must be
    // carried over it. The end-of-function pool needs no branch: those bytes
    // are past the final return and are never reached.
    if let Some(enc) = branch_over {
        let n = pending.len();
        // The branch's own size decides the distance it must cover, and the
        // distance decides the size (B.N is 2 bytes, B.W is 4). Iterate to the
        // fixed point rather than assuming one — the same shape
        // `resolve_label_branches` already uses for label branches.
        let (bytes, _pad) = island_branch_over(code.len(), n, enc)?;
        code.extend_from_slice(&bytes);
    }
    // 4-byte align the pool start (Thumb-2 word loads require it, and
    // `Align(PC,4)` in the LDR-literal semantics assumes a word-aligned pool).
    while !code.len().is_multiple_of(4) {
        code.push(0x00);
    }
    // One distinct pooled word per LdrSym (no dedup: different sites carry
    // different addends, and the REL addend lives in the word).
    for lit in pending {
        let word_offset = code.len() as u32;

        // REL semantics: the linker computes `S + A`, where A is the in-place
        // value of the relocated word. Initialize the word to the addend so
        // the final loaded address is `symbol + addend`.
        code.extend_from_slice(&(lit.addend as u32).to_le_bytes());
        relocations.push(CodeRelocation {
            offset: word_offset,
            symbol: lit.symbol.clone(),
            kind: synth_core::backend::RelocKind::Abs32,
        });

        // Patch the placeholder `LDR.W rd,[pc,#imm12]`. Thumb-2 LDR (literal):
        // address = Align(PC,4) + imm12, with PC = ldr_offset + 4. The pool is
        // always after the LDR, so U=1 (already set in hw1 = 0xF8DF).
        let pc = lit.ldr_offset + 4;
        let aligned_pc = pc & !3u32;
        let imm12 = word_offset.wrapping_sub(aligned_pc);
        if word_offset < aligned_pc || imm12 > 0xFFF {
            return Err(format!(
                "LdrSym literal pool out of range (#345): imm12={} > 4095 \
                 for symbol {}",
                imm12, lit.symbol
            ));
        }
        let hw2_off = (lit.ldr_offset + 2) as usize;
        let mut hw2 = u16::from_le_bytes([code[hw2_off], code[hw2_off + 1]]);
        hw2 = (hw2 & 0xF000) | (imm12 as u16); // keep Rt, set imm12
        let hw2_bytes = hw2.to_le_bytes();
        code[hw2_off] = hw2_bytes[0];
        code[hw2_off + 1] = hw2_bytes[1];
    }
    Ok(())
}

fn compile_wasm_to_arm(
    wasm_ops: &[WasmOp],
    config: &CompileConfig,
) -> Result<CompileArmOutput, String> {
    // #1093: a PARAMETER-taking block type (`if`/`block`/`loop (param ..)`,
    // wasm multi-value) declines LOUDLY here — the single choke point BOTH
    // ARM codegen paths pass through, so neither the optimized route nor the
    // #197 direct route can reach the selectors' frame-entry stack
    // checkpoints, which cannot represent params consumed below them (the
    // `split_off` panic with an `else`; a silently-wrong false-path value
    // without one — see `find_param_block_type`). This is the aarch64
    // VCR-A64-CF-001 frame-open refusal ported, NOT multi-value support.
    // Checked on the driver's ORIGINAL stream, which is what the ordinal
    // side-table was built against. Empty side-table (hand-built op streams)
    // ⇒ never fires ⇒ byte-identical for every existing caller.
    //
    // RQ-64-MVLOWER (#1093): the guard is relaxed PER CONSTRUCT and PER PATH,
    // from the one policy in synth-core (`arm_param_block_lowering`), on the
    // configuration the #1097 oracle executes — `--relocatable`. The
    // self-contained image path keeps the full decline: no oracle leg
    // executes its images, so there is no evidence to relax on.
    let lowered = synth_core::arm_param_block_lowering(config.relocatable);
    if let Some((what, ord, arity)) = synth_core::find_unlowered_param_block_type(
        wasm_ops,
        &config.current_func_block_arity,
        lowered,
    ) {
        return Err(synth_core::param_block_decline_msg(
            if config.relocatable {
                "the ARM direct selector (--relocatable)"
            } else {
                "the ARM selector (self-contained image path — no #1097 oracle \
                 leg executes it)"
            },
            what,
            ord,
            arity,
        ));
    }
    // #539: `memory.grow(0)` must return the CURRENT page count, not the
    // fixed-memory `-1` sentinel — growing by zero pages can never fail (WASM
    // Core §4.4.7), so a guest doing `if (memory.grow(0) < 0) trap;` wrongly
    // faulted. Every lowering path emitted a delta-agnostic `-1`. `memory.grow(0)`
    // is semantically identical to `memory.size`, which the backend already
    // computes from the runtime memory-size register (R10 >> 16 = pages), so fold
    // the `i32.const 0; memory.grow` idiom to `memory.size` up front — backend-
    // and path-agnostic. A non-zero delta keeps `-1` (fixed memory genuinely
    // cannot grow); a runtime delta that happens to be 0 is the documented
    // follow-up.
    let rewritten = rewrite_memory_grow_zero(wasm_ops);
    // #494 phase 2b: the fact-spec guard-elision marks are keyed by op index
    // into the stream the DRIVER handed us. The memory.grow(0) fold above can
    // only shift indices AT OR AFTER a `memory.grow` — an op the fact-spec
    // walk never crosses (it stops at the first untracked op, so no mark can
    // follow one). Defense in depth: if the fold fired at all, drop the marks
    // loudly rather than risk keying a guard elision to the wrong op.
    //
    // VCR-MEM-004 (#901): scry's externally-proven bounds-guard marks ride the
    // SAME defensive gate for the SAME reason — they are op-index keyed, so an
    // index shift would strip the guard off the wrong access. They are unioned
    // with #494's certificate-discharged marks here (one consumption point,
    // two authorities; `CompileConfig` keeps them separate so the attestation
    // can say which one covered each site).
    let (fact_div_zero_elide, fact_div_ovf_elide, mem_bounds_elide): (
        &[usize],
        &[usize],
        Vec<usize>,
    ) = if rewritten.len() == wasm_ops.len() {
        let mut mem = config.fact_mem_bounds_elide.clone();
        mem.extend_from_slice(&config.proven_safe_mem_elide);
        mem.sort_unstable();
        mem.dedup();
        (&config.fact_div_zero_elide, &config.fact_div_ovf_elide, mem)
    } else {
        if !config.fact_div_zero_elide.is_empty()
            || !config.fact_div_ovf_elide.is_empty()
            || !config.fact_mem_bounds_elide.is_empty()
        {
            eprintln!(
                "fact-spec: DECLINE guard elision marks dropped — the                      memory.grow(0) fold shifted op indices (#494 defensive gate);                      general lowering emitted"
            );
        }
        if !config.proven_safe_mem_elide.is_empty() {
            eprintln!(
                "proven-safe: DECLINE {} bounds-guard elision mark(s) dropped — the \
                 memory.grow(0) fold shifted op indices, so the (func, pc) keys no longer \
                 name the accesses scry proved (VCR-MEM-004 defensive gate, #901); every \
                 guard is retained",
                config.proven_safe_mem_elide.len()
            );
        }
        (&[], &[], Vec::new())
    };
    let wasm_ops: &[WasmOp] = &rewritten;

    // #457: `count_params` INFERS the param count from access patterns (a local
    // whose first access is a read is assumed to be a param), so a
    // read-before-write NON-PARAM local — which WASM zero-initializes — was
    // indistinguishable from a param: it got homed in a parameter register and
    // read caller garbage instead of 0. The driver supplies the DECLARED count
    // (`current_func_param_count`, from the module's type section) to settle it.
    //
    // #970 (RQ-57-CONDPARAM): see [`effective_num_params`] for the bound and
    // why the read-first inference is not it.
    let inferred_params = count_params(wasm_ops);
    let num_params = effective_num_params(wasm_ops, config);
    // A read-before-write non-param local exists iff the ACCESS-PATTERN
    // inference overshot the declared count — the read-first rule can only
    // exceed it via a read-first index >= the declared count, which is exactly
    // such a local. (Unchanged by #970: `referenced >= inferred` always, so
    // `num_params < inferred_params` still holds iff `inferred > declared`;
    // stated directly here rather than left to that algebra.)
    let has_rbw_local = match config.current_func_param_count {
        Some(declared) => inferred_params > declared,
        None => false,
    };

    let bounds_config = match config.effective_safety_bounds() {
        SafetyBounds::None => BoundsCheckConfig::None,
        SafetyBounds::Mpu => BoundsCheckConfig::Mpu,
        SafetyBounds::Software => BoundsCheckConfig::Software,
        SafetyBounds::Mask => {
            // #651 (mirroring the RISC-V backend's compile-time decline):
            // index masking wraps `ea & (size-1)` — a modulo only when the
            // linear-memory size is a power of two. With a non-power-of-two
            // size the AND would silently REMAP in-bounds addresses (e.g.
            // 0x18000 & 0x2FFFF = 0x8000 for a 192 KiB memory). Decline
            // loudly rather than miscompile.
            //
            // RQ-57-SENTINEL (#953 sibling): `bytes == 0` used to be EXEMPT
            // from this check, because 0 was read as "unknown — plain
            // per-function path, no module context". But 0 is also exactly
            // what a module declaring `(memory 0)` produces, and for that
            // module the emitted guard (`SUB R12, R10, #1; AND addr, R12`,
            // R10 = 0 baked by the startup) computes `0 - 1 = 0xFFFFFFFF` —
            // an IDENTITY mask. Every access then executes unmasked at
            // `[R11 + addr]` for any 32-bit addr: an unbounded OOB read/write
            // in the mode whose purpose is bounding. Same sentinel/value
            // collision as #932/#953, third backend-mode instance.
            //
            // 0 now means what #953 made it mean everywhere: a zero-byte
            // memory. No mask can bound an access into a memory with no bytes
            // (wasm semantics: every access traps), and wrap-not-trap has
            // nothing to wrap into — refuse. Callers with no module context
            // must state the size (the #953 contract; the CLI single-function
            // path now threads the module's declared size for all backends).
            let bytes = config.linear_memory_bytes;
            if bytes == 0 {
                return Err("--safety-bounds mask: the linear memory has ZERO bytes \
                     (`(memory 0)`, or a driver that did not state the size) — \
                     every access is out of bounds and a mask cannot express a \
                     trap. Use --safety-bounds software (traps every access) \
                     or declare a non-zero memory (RQ-57-SENTINEL, #953)"
                    .to_string());
            }
            if !bytes.is_power_of_two() {
                return Err(format!(
                    "--safety-bounds mask requires a power-of-two linear-memory \
                     size, got {bytes} bytes — switch to --safety-bounds software \
                     for the deterministic check (#651)"
                ));
            }
            BoundsCheckConfig::Masking
        }
    };

    // The non-optimized (direct) instruction-selection path. Handles f32 via
    // VFP/FPU. Used directly when `--no-optimize` is set, and as the fallback
    // when the optimized path declines a module (see issue #120 below).
    //
    // VCR-RA-001 step 3b-lite (#242): a FRESH selector per attempt, with
    // `spill_on_exhaustion` set only on the retry — the first pass is the
    // unmodified default, so every function that compiles today is selected by
    // exactly the code that compiled it yesterday (bit-identity is structural,
    // not behavioural).
    // #1321: the allocator spill areas the direct selector reserved for the
    // attempt that actually produced the returned stream, as
    // `(frame_size, areas)`. Written only on a SUCCESSFUL selection, so after
    // the recovery ladder it holds the rung that won. Left `None` on the
    // optimized path, which supplies no layout — and `None` means "police every
    // offset", i.e. exactly today's behaviour.
    let selected_spill_areas: std::cell::RefCell<Option<(i32, Vec<std::ops::Range<i32>>)>> =
        std::cell::RefCell::new(None);
    // RQ-71-VFPALIAS (#881/#1069): the companion record — the PERMANENT frame
    // homes of frame-resident f32/f64 locals. Kept beside the spill areas rather
    // than folded into them because it is a different KIND of fact: the areas say
    // where the allocator's slots live, this says which offsets inside that same
    // pool are a wasm local's own home and carry no single-value obligation.
    let selected_vfp_frame_homes: std::cell::RefCell<Option<(i32, Vec<i32>)>> =
        std::cell::RefCell::new(None);
    let select_direct_attempt = |spill_on_exhaustion: bool,
                                 param_backing_on_exhaustion: bool,
                                 local_promote: bool,
                                 i64_spill_slots: Option<usize>,
                                 vfp_spill_on_exhaustion: bool,
                                 vfp_frame_home_locals: bool,
                                 vfp_wide_file: bool|
     -> Result<Vec<ArmInstruction>, synth_core::Error> {
        let db = RuleDatabase::with_standard_rules();
        let mut selector =
            InstructionSelector::with_bounds_check(db.rules().to_vec(), bounds_config);
        selector.set_target(config.target.fpu, &config.target.triple);
        if config.num_imports > 0 {
            selector.set_num_imports(config.num_imports);
        }
        // #195: plumb the callee argument-count tables so the direct selector can
        // marshal call arguments into R0–R3 per AAPCS.
        selector.set_func_arg_counts(
            config.func_arg_counts.clone(),
            config.type_arg_counts.clone(),
        );
        // #197: in relocatable host-link mode, emit direct `func_N` BLs for
        // imports (rewritten to the wasm field name by build_relocatable_elf)
        // instead of `__meld_dispatch_import`.
        selector.set_relocatable(config.relocatable);
        // #642: call_indirect guard inputs (compile-time table size for the
        // bounds guard + closed-world type verdicts). Without them, every
        // call_indirect lowering declines loudly.
        selector.set_call_indirect_guards(config.call_indirect_guards.clone());
        // #275: on the self-contained image path (NOT --relocatable) the R11
        // funcref-table dispatch is a silent miscompile — the region is only
        // populated by an external runtime, which a self-contained ELF does
        // not have, so the dispatch would read function pointers from
        // linear-memory data. Two outcomes:
        //  - the Thumb-2 `--cortex-m` image path (CLI-flagged: the builder
        //    that emits and patches the flash-resident funcref table will
        //    run) lowers call_indirect through that table, PC-relative,
        //    never via R11;
        //  - every OTHER self-contained configuration (A32/Cortex-R5, the
        //    simple-ELF builder, imports present) keeps the loud decline.
        // The host-linked (--relocatable) path keeps the guarded R11
        // dispatch: there a runtime places the table region at R11.
        let self_contained_table = config.self_contained_funcref_table
            && matches!(config.target.isa, IsaVariant::Thumb2 | IsaVariant::Thumb);
        selector
            .set_reject_self_contained_call_indirect(!config.relocatable && !self_contained_table);
        selector.set_self_contained_funcref_table(self_contained_table);
        // #237: native-pointer ABI — wasm statics become __synth_wasm_data-relative.
        selector.set_native_pointer_abi(config.native_pointer_abi, config.linear_memory_bytes);
        // VCR-MEM-002 phase 1 (#406): per-memory initial page counts — enables
        // the multi-memory arms (memory-0 lowering never reads it; empty ⇒
        // every multi-memory op declines loudly).
        selector.set_memory_pages(config.memory_pages.clone());
        // #311: i64 call results are register PAIRS — tag them.
        selector.set_result_types(config.func_ret_i64.clone(), config.type_ret_i64.clone());
        // #1210: per-function result COUNT (0 = void) — `func_ret_i64` alone
        // cannot tell a void callee from an i32-returning one.
        selector.set_func_result_counts(config.func_result_counts.clone());
        // #359: declared param widths of THIS function, so the AAPCS stack-arg
        // path can refuse 64-bit params (Ok-or-Err). Empty ⇒ assume i32.
        selector.set_params_i64(config.current_func_params_i64.clone());
        // GI-FPU-002 (#619/#369): declared f32-param mask — home hard-float f32
        // args in S0..S15 (AAPCS-VFP) instead of the R0..R3 integer path.
        selector.set_params_f32(config.current_func_params_f32.clone());
        // GI-FPU-002 phase 2 (#369): declared f64-param mask — hard-float
        // targets decline f64-param functions loudly (no D-register homing yet).
        selector.set_params_f64(config.current_func_params_f64.clone());
        // GI-FPU-002 phase 2 (#719/#369): THIS function's f32/f64 return flag, so
        // the epilogue loudly declines a float result reaching it in a core
        // register (never a silent integer R0 return where a caller reads S0/D0).
        selector.set_ret_float(config.current_func_ret_f32, config.current_func_ret_f64);
        // GI-FPU-002 phase 3 (#369): per-callee float-signature tables. `Call`
        // marshals the AAPCS-VFP boundary from these (float args into S0../D0..,
        // float results out of S0/D0); `CallIndirect` still declines a
        // float-returning static type loudly.
        selector.set_float_call_signatures(
            config.func_ret_f32.clone(),
            config.func_ret_f64.clone(),
            config.type_ret_f32.clone(),
            config.type_ret_f64.clone(),
            config.func_params_f32.clone(),
            config.func_params_f64.clone(),
        );
        // #509: blocktype-arity side-table of THIS function, so value-carrying
        // br/br_if/br_table land the carried value in the target block's
        // designated result register instead of dropping it. Empty ⇒ legacy
        // void-block lowering.
        selector.set_block_arity(config.current_func_block_arity.clone());
        // #1214: THIS function's declared-i64-local side-table — see
        // `compute_local_layout`'s use of it. Empty ⇒ exactly the prior
        // dataflow-only width inference.
        selector.set_declared_i64_locals(config.current_func_declared_i64_locals.clone());
        // Stack-pointer promotion is meaningful only under the native-pointer ABI;
        // gating here keeps every non-native compile (all frozen fixtures) on the
        // legacy R9 globals-table path, bit-identical.
        if config.native_pointer_abi
            && let Some((sp_idx, sp_init)) = config.stack_pointer_global
        {
            selector.set_native_pointer_stack(sp_idx, sp_init);
        }
        // #643: per-global slot widths — i64/f64 globals occupy 8-byte slots
        // (register-pair store/load) and shift every later global's offset.
        // Empty for i32-only modules ⇒ the legacy `idx * 4` layout, unchanged.
        selector.set_global_widths(config.global_widths.clone());
        selector.set_spill_on_exhaustion(spill_on_exhaustion);
        selector.set_param_backing_on_exhaustion(param_backing_on_exhaustion);
        // #881 (VCR-RA-004): VFP register-file spilling, set ONLY on the retry
        // after an attempt failed with a GI-FPU-002 exhaustion Err — functions
        // that compile without it keep byte-identical output by construction.
        selector.set_vfp_spill_on_exhaustion(vfp_spill_on_exhaustion);
        // #1069: LAST-resort residence lever — set ONLY by the final VFP
        // retry below, after the plain #881 rung also exhausted, so every
        // function that compiles through base path or plain rung is produced
        // by exactly yesterday's path (byte-identity is structural).
        selector.set_vfp_frame_home_locals(vfp_frame_home_locals);
        // RQ-67-VFPREACH (#1267): the AAPCS callee-saved VFP half.
        selector.set_vfp_wide_file(vfp_wide_file);
        // #587 pool-grow rung: a larger i64 spill-slot pool, set ONLY on the
        // retry after an attempt failed with the slot-pool-exhausted Err —
        // functions that compile with the default pool keep their frame
        // byte-identical by construction.
        if let Some(slots) = i64_spill_slots {
            selector.set_i64_spill_slots(slots);
        }
        // VCR-RA local promotion (#390, #242): keep eligible non-param i32 locals
        // in callee-saved registers instead of frame slots — the structural lever
        // toward native parity. DEFAULT-ON as of v0.14.0: gale's G474RE DWT gate
        // cleared it as a net win (gust_mix dissolved 58→50 cyc/call −14%, all 5
        // stack spill/reloads eliminated, correctness bit-identical over [0,2047],
        // 2.00×→1.72× vs LLVM). Escape hatch: `SYNTH_NO_LOCAL_PROMOTE=1` restores
        // the frame-slot path. Leaf-only / i32-only / ARM-only (see
        // compute_local_promotion); the leaf-only lift + i64 locals are follow-ons.
        // #474: `local_promote` is now a per-attempt parameter so the retry ladder
        // can drop promotion as an exhaustion-recovery rung (promotion pins r4-r8,
        // which on a dense function leaves the spill allocator with nothing to
        // free → the frame-slot path is the escape that restores compilability).
        selector.set_local_promote(local_promote);
        // #494 phase 2b: certificate-discharged div/rem trap-guard elision
        // marks (empty in every compile without SYNTH_FACT_SPEC + facts).
        selector
            .set_fact_div_guard_elisions(fact_div_zero_elide.to_vec(), fact_div_ovf_elide.to_vec());
        // #494 bounds-elision + VCR-MEM-004 (#901): per-site memory
        // bounds-guard marks, unioned above. Empty in every compile without
        // SYNTH_FACT_SPEC + facts or --proven-safe.
        selector.set_fact_mem_bounds_elisions(mem_bounds_elide.clone());
        let selected = selector.select_with_stack(wasm_ops, num_params);
        if selected.is_ok() {
            // #1321: only a SUCCESSFUL attempt's layout describes the stream we
            // return; a failed rung's frame is discarded with it.
            *selected_spill_areas.borrow_mut() = selector.frame_spill_areas().cloned();
            *selected_vfp_frame_homes.borrow_mut() = selector.vfp_frame_home_halves().cloned();
        }
        selected
    };
    let select_direct = || -> Result<Vec<ArmInstruction>, String> {
        const SINGLE_EXHAUSTION: &str = "all allocatable registers are live on the stack";
        const PAIR_EXHAUSTION: &str = "no consecutive pair of free registers for i64";
        const SLOT_EXHAUSTION: &str = "i64 spill-slot pool exhausted";
        // The full exhaustion-recovery ladder, parameterized on whether local
        // promotion is enabled. Each rung is reached only when the previous one
        // returned a recoverable register-exhaustion Err, so a function that
        // compiles on the first attempt is untouched by the later rungs. Returns
        // the result AND which rung produced it (for the #242 measurement below).
        let recovery_ladder =
            |promote: bool,
             i64_spill_slots: Option<usize>,
             vfp_spill: bool,
             vfp_frame: bool,
             vfp_wide: bool|
             -> (Result<Vec<ArmInstruction>, synth_core::Error>, &'static str) {
                let mut attempt = select_direct_attempt(
                    false,
                    false,
                    promote,
                    i64_spill_slots,
                    vfp_spill,
                    vfp_frame,
                    vfp_wide,
                );
                let mut rung = "base";
                // VCR-RA-001 step 3b-lite (#242): the i32 register-exhaustion
                // hard-fail is recoverable — retry with spill-on-exhaustion, which
                // reserves the spill area and spills the deepest stack value when
                // the pool is full.
                if let Err(e) = &attempt
                    && e.to_string().contains(SINGLE_EXHAUSTION)
                {
                    attempt = select_direct_attempt(
                        true,
                        false,
                        promote,
                        i64_spill_slots,
                        vfp_spill,
                        vfp_frame,
                        vfp_wide,
                    );
                    rung = "spill";
                }
                // VCR-RA-001 acceptance increment (#242): the i64 consecutive-PAIR
                // exhaustion is recoverable too — not by stack spilling (the pair
                // allocator already spills stack values, #171) but by frame-backing
                // the params (#204) so they stop pinning R0-R3, with spill kept on.
                if let Err(e) = &attempt
                    && e.to_string().contains(PAIR_EXHAUSTION)
                {
                    attempt = select_direct_attempt(
                        true,
                        true,
                        promote,
                        i64_spill_slots,
                        vfp_spill,
                        vfp_frame,
                        vfp_wide,
                    );
                    rung = "param-backing";
                }
                (attempt, rung)
            };
        // #474: local promotion (default-on since v0.14.0) is an OPTIMIZATION — it
        // must never be the reason a function fails to compile. Run the full ladder
        // with promotion first (so every function that compiles today is
        // bit-identical), and if it still ends in register exhaustion, fall back to
        // the promotion-off ladder (the v0.12.0 frame-slot lowering — exactly what
        // the `SYNTH_NO_LOCAL_PROMOTE=1` workaround does, now automatic). Promotion
        // pins r4-r8 for the locals; on a dense function that leaves the allocator
        // with nothing to free, so dropping it restores compilability. The fallback
        // is reached ONLY by functions that exhaust WITH promotion, so promotion-on
        // output is untouched by construction (frozen byte gate stays green).
        let promote = std::env::var("SYNTH_NO_LOCAL_PROMOTE").is_err();
        // RQ-69-FALCON (#1318): per-rung reporting, because the summary line
        // below CANNOT distinguish the two failures it is asked about. `rung`
        // is only assigned when an attempt SUCCEEDS, so a function that climbs
        // the whole ladder and exhausts every rung prints `rung=base
        // result=exhausted` — identical to one that never climbed at all. Worse,
        // the Err the caller finally reports is stage 2's, so a stage-3
        // (wide-file) failure is invisible even in the user-facing message:
        // #1318's `step` reports the #1069 slot-pool message while the wide-file
        // rung it also failed says nothing. Measured on the reporter's module
        // before this was written; reading the source was the only way to tell
        // which of the two had happened.
        //
        // Logging only, behind the same env var, so emitted bytes are unchanged
        // and the frozen byte gate is unaffected.
        let stats = std::env::var("SYNTH_RECOVERY_STATS").is_ok();
        // Every rung's Err, in attempt order (#1318). The ladder keeps the
        // EARLIER attempt's Err whenever a later rung also fails — stage 3
        // falls back to stage 2's `fh`, each pool-grow falls back to its
        // ungrown attempt — so the reporter of #1318 was told "spill-slot pool
        // exhausted" while the wall three of the four rungs actually hit was
        // the VSTR/VLDR [sp,#imm] window. Reporting the LAST rung's Err is no
        // better: the last rung attempted is the wide-file one, whose Err is
        // the pool message again. So report what was actually tried, deduped.
        // Control flow is untouched — every rung still runs exactly when it
        // ran before, and the substrings other code matches on are all still
        // present in the joined message.
        let tried: std::cell::RefCell<Vec<(String, String)>> = std::cell::RefCell::new(Vec::new());
        let note = |name: &str, r: &Result<Vec<ArmInstruction>, synth_core::Error>| {
            if let Err(e) = r {
                let m = e.to_string();
                let first = m.lines().next().unwrap_or("").to_string();
                tried.borrow_mut().push((name.to_string(), first));
            }
            if stats {
                match r {
                    Ok(_) => eprintln!("[recovery-stats]   tried rung={name} -> ok"),
                    Err(e) => {
                        let m = e.to_string();
                        let first = m
                            .lines()
                            .next()
                            .unwrap_or("")
                            .chars()
                            .take(140)
                            .collect::<String>();
                        eprintln!("[recovery-stats]   tried rung={name} -> exhausted: {first}");
                    }
                }
            }
        };
        // The full pre-#587 recovery sequence (promotion-on ladder, then the
        // #474 promotion-off fallback), parameterized on the pool size so the
        // pool-grow retry below reruns it verbatim.
        let full_sequence = |slots: Option<usize>,
                             vfp_spill: bool,
                             vfp_frame: bool,
                             vfp_wide: bool|
         -> (
            Result<Vec<ArmInstruction>, synth_core::Error>,
            &'static str,
            bool,
        ) {
            let (mut attempt, mut rung) =
                recovery_ladder(promote, slots, vfp_spill, vfp_frame, vfp_wide);
            let mut promotion_dropped = false;
            if promote
                && attempt
                    .as_ref()
                    .err()
                    .is_some_and(|e| e.to_string().contains("register exhaustion"))
            {
                let (rescued, off_rung) =
                    recovery_ladder(false, slots, vfp_spill, vfp_frame, vfp_wide);
                if rescued.is_ok() {
                    attempt = rescued;
                    rung = off_rung;
                    promotion_dropped = true;
                }
            }
            (attempt, rung, promotion_dropped)
        };
        let (mut attempt, mut rung, mut promotion_dropped) =
            full_sequence(None, false, false, false);
        // #587 pool-grow retry (the falcon func_60/func_73 remainder): the fixed
        // 8-slot i64 spill pool can exhaust while spilling is otherwise working —
        // an i64-dense function simply has more values simultaneously live than
        // the pool holds. Rerun the ENTIRE sequence (every rung, both promotion
        // modes) with the pool sized from a conservative operand-stack-depth
        // bound: the number of simultaneously spilled values can never exceed
        // the operand-stack depth, plus a few transient slots (the arg-move
        // cycle resolver and call-result parking each borrow one). The selector
        // clamps the request to its 12-bit-friendly cap; a function that still
        // exhausts stays an honest loud skip. Deliberately LAST — after the #474
        // promotion-off fallback — so any function that compiled yesterday
        // (through any rung or fallback) is produced by exactly yesterday's
        // path, byte-identical; the grown pool only ever fires for functions
        // whose every existing escape ended in the slot-pool Err.
        if attempt
            .as_ref()
            .err()
            .is_some_and(|e| e.to_string().contains(SLOT_EXHAUSTION))
        {
            let depth = synth_core::wasm_stack_check::max_depth_bound(wasm_ops) as usize;
            let (grown, _, grown_dropped) =
                full_sequence(Some(depth.saturating_add(4)), false, false, false);
            note("pool-grow", &grown);
            if grown.is_ok() {
                attempt = grown;
                rung = "pool-grow";
                promotion_dropped = grown_dropped;
            }
        }
        // #881 (VCR-RA-004): the GI-FPU-002 VFP register-file exhaustion is
        // recoverable too — retry the ENTIRE sequence with VFP spilling
        // enabled (the pre-op pressure guard spills the deepest segment-local
        // f32/f64 stack value into the shared spill area and reloads spilled
        // operands before their consumers). Deliberately LAST, after every
        // integer rung, so any function that compiled yesterday is produced
        // by exactly yesterday's path; the VFP rung only ever fires for
        // functions whose every existing escape ended in a GI-FPU-002
        // exhaustion Err (previously an unconditional loud skip). A VFP-
        // spilling function can in turn exhaust the shared slot pool — the
        // #587 pool-grow retry composes inside the rung.
        const VFP_S_EXHAUSTION: &str = "VFP register file exhausted";
        const VFP_D_EXHAUSTION: &str = "VFP D-register file exhausted";
        if attempt.as_ref().err().is_some_and(|e| {
            let msg = e.to_string();
            msg.contains(VFP_S_EXHAUSTION) || msg.contains(VFP_D_EXHAUSTION)
        }) {
            // Stage 1 — the plain #881 rung, exactly yesterday's path
            // (sequence, pool sizing and all): any function it rescues is
            // byte-identical to what it shipped yesterday, by construction.
            let (vfp, vfp_rung, vfp_dropped) = full_sequence(None, true, false, false);
            note("vfp-spill", &vfp);
            let (vfp, vfp_rung, vfp_dropped) = if vfp.as_ref().err().is_some_and(|e| {
                let msg = e.to_string();
                msg.contains(SLOT_EXHAUSTION) || msg.contains("spilling the VFP register file")
            }) {
                let depth = synth_core::wasm_stack_check::max_depth_bound(wasm_ops) as usize;
                let (grown, grown_rung, grown_dropped) =
                    full_sequence(Some(depth.saturating_add(4)), true, false, false);
                note("vfp-spill+pool-grow", &grown);
                if grown.is_ok() {
                    (grown, grown_rung, grown_dropped)
                } else {
                    (vfp, vfp_rung, vfp_dropped)
                }
            } else {
                (vfp, vfp_rung, vfp_dropped)
            };
            if vfp.is_ok() {
                attempt = vfp;
                rung = match vfp_rung {
                    "base" => "vfp-spill",
                    _ => "vfp-spill+int",
                };
                promotion_dropped = vfp_dropped;
            } else {
                // Stage 2 (#1069, RQ-60-VFPPRESSURE increment 2) — LAST
                // resort: the plain rung ALSO failed, i.e. the pressure is
                // not (only) operand-stack values but PINNED LOCAL HOMES,
                // which the #881 victim search rightly never touches (a home
                // lives for the function's extent). Rerun the entire
                // sequence with frame-homed overflow locals: a fresh
                // f32/f64 local whose home grant would pin above the S7/D3
                // cap lives in the frame from its first def. Reached ONLY by
                // functions that failed every prior escape, so nothing that
                // compiles today moves a byte.
                let (fh, fh_rung, fh_dropped) = full_sequence(None, true, true, false);
                note("vfp-frame-locals", &fh);
                let (fh, fh_rung, fh_dropped) = if fh.as_ref().err().is_some_and(|e| {
                    let msg = e.to_string();
                    // The frame-homed-local slot demand (a PERMANENT slot per
                    // frame-resident float local) is a third way the shared
                    // pool exhausts — its trigger substring is the selector's
                    // own pub const, not a second copy that could drift (the
                    // #881 substring-is-control-flow lesson, pinned red-first
                    // by the live24 fixture test).
                    msg.contains(SLOT_EXHAUSTION)
                        || msg.contains("spilling the VFP register file")
                        || msg.contains(
                            synth_synthesis::instruction_selector::VFP_FRAME_HOME_SLOT_EXHAUSTION,
                        )
                }) {
                    let depth = synth_core::wasm_stack_check::max_depth_bound(wasm_ops) as usize;
                    // Frame-homed locals hold their slots for the function's
                    // extent, OUTSIDE the operand-stack depth bound — size
                    // the grown pool for both. Distinct `local.set`/
                    // `local.tee` targets over-approximate the frame-homed
                    // local count; the selector clamps the request to its
                    // cap, and a function that still exhausts stays an
                    // honest loud skip.
                    let local_targets: std::collections::HashSet<u32> = wasm_ops
                        .iter()
                        .filter_map(|op| match op {
                            synth_synthesis::WasmOp::LocalSet(i)
                            | synth_synthesis::WasmOp::LocalTee(i) => Some(*i),
                            _ => None,
                        })
                        .collect();
                    let (grown, grown_rung, grown_dropped) = full_sequence(
                        Some(depth.saturating_add(local_targets.len()).saturating_add(4)),
                        true,
                        true,
                        false,
                    );
                    note(
                        &format!(
                            "vfp-frame-locals+pool-grow({})",
                            depth.saturating_add(local_targets.len()).saturating_add(4)
                        ),
                        &grown,
                    );
                    if grown.is_ok() {
                        (grown, grown_rung, grown_dropped)
                    } else {
                        (fh, fh_rung, fh_dropped)
                    }
                } else {
                    (fh, fh_rung, fh_dropped)
                };
                if fh.is_ok() {
                    attempt = fh;
                    rung = match fh_rung {
                        "base" => "vfp-frame-locals",
                        _ => "vfp-frame-locals+int",
                    };
                    promotion_dropped = fh_dropped;
                } else {
                    // Stage 3 (#1267, RQ-67-VFPREACH) — THE LAST RESORT, and the
                    // reach half of #1204's root shape. Every escape above has
                    // now ended in GI-FPU-002, so this function DECLINES today.
                    //
                    // It declines against HALF the register file: synth
                    // allocates S0-S15/D0-D7 because S16-S31/D8-D15 are AAPCS
                    // CALLEE-saved and, until this release, nothing could save
                    // them — VPUSH/VPOP did not exist in the encoder. Every FPU
                    // target synth supports actually has D0-D15 = S0-S31.
                    //
                    // Reached ONLY here, so a function that compiles today is
                    // produced by exactly today's path and cannot move a byte —
                    // the #881 rung discipline, measured over the corpus rather
                    // than asserted. The selector emits the VPUSH/VPOP pair and
                    // REFUSES functions with stack-passed params (#1273), so a
                    // failure here stays the honest loud decline it already was.
                    let (wide, wide_rung, wide_dropped) = full_sequence(None, true, true, true);
                    note("vfp-wide-file", &wide);
                    if wide.is_ok() {
                        attempt = wide;
                        rung = match wide_rung {
                            "base" => "vfp-wide-file",
                            _ => "vfp-wide-file+int",
                        };
                        promotion_dropped = wide_dropped;
                    } else {
                        attempt = fh;
                        promotion_dropped = fh_dropped;
                    }
                }
            }
        }
        // VCR-RA measurement (#242): log which recovery rung produced the result,
        // so the per-rung distribution across a corpus can be measured — the size
        // of the failure surface a verified allocator must subsume (see
        // scripts/repro/register_exhaustion_recovery_ladder.md). Logging only:
        // emitted bytes are unchanged, so the frozen byte gate is unaffected.
        if stats {
            // `rung` holds the last SUCCESSFUL rung; on total exhaustion it is
            // still "base", which said nothing about how far the ladder climbed
            // (#1318). Report it as `none` and let the per-rung lines above
            // carry the detail.
            let rung = if attempt.is_ok() { rung } else { "none" };
            eprintln!(
                "[recovery-stats] rung={rung}{} result={}",
                if promotion_dropped {
                    " promotion-off"
                } else {
                    ""
                },
                if attempt.is_ok() { "ok" } else { "exhausted" },
            );
        }
        attempt.map_err(|e| {
            // The kept Err first (so every substring any caller or test matches
            // on is exactly where it was), then the rungs that were tried and
            // what each one hit. Deduped by message: three rungs reporting one
            // wall should say so once, and name the three (#1318).
            let base = format!("instruction selection failed: {}", e);
            let rungs = tried.borrow();
            if rungs.len() < 2 {
                return base;
            }
            let mut by_msg: Vec<(String, Vec<String>)> = Vec::new();
            for (rung, msg) in rungs.iter() {
                match by_msg.iter_mut().find(|(m, _)| m == msg) {
                    Some((_, names)) => names.push(rung.clone()),
                    None => by_msg.push((msg.clone(), vec![rung.clone()])),
                }
            }
            let detail = by_msg
                .iter()
                .map(|(msg, names)| format!("{} -> {}", names.join(" + "), msg))
                .collect::<Vec<_>>()
                .join(" | ");
            format!("{base} [every recovery rung failed: {detail}]")
        })
    };

    // Instruction selection: optimized or direct.
    //
    // #197: `--relocatable` (host-link ET_REL) forces the direct selector. The
    // optimized path materializes an absolute linmem base (0x20000100) and does
    // not preserve caller-saved registers across calls — both wrong for a
    // host-linked object, where the linmem base arrives via `fp` at runtime and
    // callees follow AAPCS. `select_with_stack` (now i64-spill capable after
    // #171) handles fp-relative memory + caller-saved preservation correctly.
    //
    // #507: `br_table` is DROPPED during the optimized path's wasm→IR lowering
    // (`optimize_full`), so `ir_to_arm` never sees the dispatch — it emits the
    // arm bodies in fall-through sequence with no `cmp`/branch on the selector, a
    // SILENT miscompile (every input hits the last arm). The selector value isn't
    // even loaded. Because the drop happens before `ir_to_arm`, there's no `Err`
    // to fall back on; detect it on the raw wasm op stream here and force the
    // direct selector (`select_with_stack` lowers `br_table` correctly as a
    // cmp-chain — confirmed on the `--relocatable` path). Same honest-degradation
    // contract as the issue-#120 f32 decline: the function still compiles
    // correctly, just without IR-level optimization. Frozen-safe: the frozen
    // fixtures compile `--relocatable` (already direct), and no optimized-path
    // fixture (control_step, flight_algo) contains `br_table`.
    let has_br_table = wasm_ops
        .iter()
        .any(|op| matches!(op, WasmOp::BrTable { .. }));
    // #509: the optimized path also drops the value carried by a `br`/`br_if`
    // to a result-typed block (the taken edge returns the wrong arm's value —
    // same silent-miscompile class as the #507 br_table drop). Route the shape
    // to the direct selector, whose designated-result-register lowering (#509)
    // lands the carried value at the join. Never fires for void-block control
    // flow (all frozen/optimized fixtures), so those stay byte-identical.
    let has_value_carry = has_value_carrying_branch(wasm_ops, &config.current_func_block_arity);
    // #503-i64/#518: route any signature with a 64-bit (i64/f64) param to the
    // direct selector. The optimized path's param homing is width-naive — its
    // #518 decline covers only functions that READ an i64 param (an `I64Load`
    // from a param index), so a function that reads an i32 param whose AAPCS
    // home a preceding wide param SHIFTED (e.g. p1 of `(i64 i32)` lives in R2,
    // not R1; p3 of `(i64 i32 i32 i32)` lives on the stack, not in R3) was
    // silently miscompiled rather than falling back. The direct selector's
    // `aapcs_param_layout` homing handles every such shape (i64-param READS
    // already fell back to it via the ir_to_arm Err, so those functions emit
    // the same bytes as before). `num_params` counts read-first locals, so a
    // function that never touches any param keeps the optimized path.
    let has_wide_param = config
        .current_func_params_i64
        .iter()
        .take(num_params as usize)
        .any(|&w| w);
    // #782(b): a HARD-float (FPU) target passes f32 args in VFP S-registers
    // and returns floats in S0/D0 (AAPCS-VFP) — but the optimized path's
    // param/return homing is float-naive (integer R0..R3 args, R0 return). A
    // function whose ops ALL lower on the optimized path but whose SIGNATURE
    // carries a float — e.g. the pure value-pick
    // `(param f32 f32 i32) (result f32) select`, no float OP to trip the
    // issue-#120 ir_to_arm fallback — was silently compiled with the integer
    // ABI: callers marshal S0/S1, the body reads R0/R1. Route every
    // float-signature function to the direct selector (AAPCS-VFP homing, or
    // an honest decline). Soft-float targets (no FPU) keep the optimized
    // path: the integer treatment IS the ABI there — byte-identical. (f64
    // params already route direct via `has_wide_param`; this adds f32 params
    // and f32/f64 returns.)
    let has_float_sig = config.target.fpu.is_some()
        && (config.current_func_ret_f32
            || config.current_func_ret_f64
            || config
                .current_func_params_f32
                .iter()
                .take(num_params as usize)
                .any(|&f| f)
            || config
                .current_func_params_f64
                .iter()
                .take(num_params as usize)
                .any(|&f| f));
    // #494 phase 2b: div/rem guard-elision marks are consumed by the DIRECT
    // selector only — the optimized path's IR passes (const-fold/CSE/DCE)
    // renumber instructions, so an op-index-keyed mark cannot soundly survive
    // them. Route marked functions direct (the #507/#509 honest-degradation
    // pattern). Never fires without SYNTH_FACT_SPEC + facts + a discharged
    // obligation, so every existing compile keeps its path byte-identical.
    let has_fact_div_elide = !fact_div_zero_elide.is_empty()
        || !fact_div_ovf_elide.is_empty()
        // #494 bounds-elision + VCR-MEM-004 (#901): memory bounds-guard marks
        // are direct-selector keyed for the same reason (IR passes renumber
        // instructions). This is ALSO why the optimized path's
        // `push_software_bounds_guard` sites never need mark plumbing: a
        // marked function is routed away from that path entirely.
        || !mem_bounds_elide.is_empty();
    // #643: the optimized path's global lowering is width-naive — `GlobalGet`/
    // `GlobalSet` are single-word `[R9, idx*4]` accesses, which (a) silently
    // dropped the high word of every i64 global and (b) mis-address every
    // global whose offset an earlier wide (i64/f64) slot shifted. When the
    // module has any wide global, route every global-touching function to the
    // direct selector, whose type-aware summed layout pairs the access (or
    // declines loudly). Modules with only 4-byte globals — every existing
    // fixture — keep the optimized path byte-identical.
    let has_wide_global_module = config.global_widths.iter().any(|&w| w > 4);
    let has_global_access = has_wide_global_module
        && wasm_ops
            .iter()
            .any(|op| matches!(op, WasmOp::GlobalGet(_) | WasmOp::GlobalSet(_)));
    // VCR-VER-001 (#242): `post_exhaust` scopes the post-exhaustion cleanup
    // extensions to functions whose bytes the #580 spill-on-exhaustion
    // machinery actually shaped (bridge-reported). Everything else — the
    // direct path, non-exhausted optimized functions — stays byte-identical
    // flag-on (the `vcr_ver_001_gate_242` lock's contract).
    let (arm_instrs, post_exhaust) = if config.no_optimize
        || config.relocatable
        || has_br_table
        || has_value_carry
        || has_wide_param
        || has_float_sig
        || has_global_access
        || has_fact_div_elide
        // #457: route read-before-write non-param locals to the direct
        // selector, whose prologue zero-init lands the wasm-mandated 0.
        || has_rbw_local
    {
        if std::env::var("SYNTH_PATH_DEBUG").is_ok() {
            // RQ-65-PARITY (#197): name WHICH pre-gate predicate diverted the
            // function and which function it was, so the selector-parity
            // oracle can record every "only one path accepted this" case with
            // its reason instead of a bare count. The leading text is kept
            // verbatim — the #377/#1021 harnesses match on it.
            let reasons: Vec<&str> = [
                (config.no_optimize, "no-optimize"),
                (config.relocatable, "relocatable"),
                (has_br_table, "br-table"),
                (has_value_carry, "value-carry"),
                (has_wide_param, "wide-param"),
                (has_float_sig, "float-sig"),
                (has_global_access, "wide-global-access"),
                (has_fact_div_elide, "fact-elide"),
                (has_rbw_local, "rbw-local"),
            ]
            .iter()
            .filter(|(on, _)| *on)
            .map(|(_, name)| *name)
            .collect();
            eprintln!(
                "[path-debug] direct (pre-gate) func={} reasons={}",
                config
                    .current_func_index
                    .map_or("?".to_string(), |i| i.to_string()),
                reasons.join(",")
            );
        }
        (select_direct()?, false)
    } else {
        let opt_config = if config.loom_compat {
            OptimizationConfig::loom_compat()
        } else {
            OptimizationConfig::all()
        };

        let mut bridge = OptimizerBridge::with_config(opt_config);
        // #188: tell the bridge how many imports there are so it declines only
        // LOCAL calls (and leaves import calls on the optimized path, keeping
        // the #173 field-name relocation rewrite intact).
        bridge.set_num_imports(config.num_imports);
        // #543 Phase 2: thread the integrator-marked volatile DMA-window ranges
        // (`--volatile-segment <base>:<len>`) to the bridge's address-caching
        // levers — base-CSE (#468) excludes any access inside a marked range
        // from its fold set, and the bridge-level const-CSE declines wholesale
        // while any range is marked. Empty (the default) ⇒ byte-identical.
        bridge.set_volatile_segments(config.volatile_segments.clone());
        // #377: thread `--safety-bounds` to the bridge. Pre-fix the optimized
        // path ignored it — `software`/`mask` were SILENT NO-OPS on the path
        // that lowers the bulk of a flight loop's i32 loads/stores (byte-
        // identical to `none`, while the safety manifest claimed otherwise).
        // `Software` now emits the inline guard per access; `Masking` declines
        // memory-accessing functions to the direct selector; `None`/`Mpu` are
        // byte-identical to before.
        bridge.set_bounds_check(bounds_config);
        // #687: thread the absolute linear-memory base the optimized path
        // materializes. Defaults to 0x2000_0100 (byte-identical);
        // `--stack-layout=low` shifts it up by the reserved stack size so
        // const-address accesses follow the moved linear memory.
        bridge.set_linmem_base(config.linmem_base);
        // `ir_to_arm` now returns `Result` — an `Err` means the optimized path
        // hit an unmapped vreg (issue-#93-class). Treat it identically to an
        // `optimize_full` failure: fall back to the direct selector rather
        // than propagating, so the function still compiles correctly.
        match bridge
            .optimize_full(wasm_ops)
            .and_then(|(opt_ir, _cfg, _stats)| bridge.ir_to_arm(&opt_ir, num_params as usize))
        {
            Ok(arm_ops) => {
                if std::env::var("SYNTH_PATH_DEBUG").is_ok() {
                    eprintln!(
                        "[path-debug] optimized (ir_to_arm ok) func={}",
                        config
                            .current_func_index
                            .map_or("?".to_string(), |i| i.to_string())
                    );
                }
                (
                    arm_ops
                        .into_iter()
                        .map(|op| ArmInstruction {
                            op,
                            source_line: None,
                        })
                        .collect(),
                    bridge.spill_on_exhaust_fired(),
                )
            }
            // Issue #120: the optimized path declines modules it cannot lower
            // (notably scalar f32/f64 ops — the IR has no float opcodes). Fall
            // back to the direct instruction selector, which handles f32 via
            // VFP/FPU. This is honest degradation: the function still compiles
            // correctly, just without IR-level optimization.
            Err(e) => {
                if std::env::var("SYNTH_PATH_DEBUG").is_ok() {
                    eprintln!(
                        "[path-debug] direct (fallback: {e}) func={}",
                        config
                            .current_func_index
                            .map_or("?".to_string(), |i| i.to_string())
                    );
                }
                (select_direct()?, false)
            }
        }
    };

    // #257/#277: `mul`+`add`→`mla` fusion is intentionally NOT wired here.
    // The transform is correct and ready (`synth_synthesis::liveness::fuse_mul_add`,
    // fully tested), but it is **register-allocation-coupled**: over the current
    // greedy single-pass selector, folding `mul rM,..; add rD,rM,rX` → `mla`
    // extends the live ranges of the mul inputs to the mla point, and the added
    // pressure (extra moves/spills) costs more than the single-cycle MLA saves —
    // gale measured a +2 cyc on-target REGRESSION (flat_flight 255→257, G474RE)
    // even though it removes 2 instructions and the seam stays 0x07FDF307. So the
    // fusion stays unwired until the spill-aware allocator (VCR-RA-001) chooses
    // registers, at which point it becomes net-positive (per #272's plan and the
    // wiring design note). Lesson (#277): a register-pressure-affecting transform
    // needs an on-target/allocator-aware gate, not a byte-count gate, before it
    // can default on.

    // VCR-RA-001 const-CSE / rematerialization-avoidance (#209): moved to run
    // LAST, after the immediate-folds — see the apply_const_cse call below
    // (#242). Earlier it ran here (before range-realloc and the folds), which is
    // what let it grow gale's --relocatable `gust_mix` 90→92 B (#242 burndown,
    // 2026-06-26): retargeting a read defeated a *downstream* immediate-fold that
    // would otherwise have absorbed the constant. Running CSE-last makes those
    // foldable consts already-folded-and-gone, so CSE only ever touches genuinely
    // redundant materializations.

    // VCR-RA-001 RANGE RE-ALLOCATION (#209/#242, wiring step 3a) — the first
    // CONSEQUENTIAL allocator pass: re-colour each maximal straight-line
    // segment over the R0-R8 pool with value ranges as the allocation unit
    // (segment inputs + per-register live-outs pinned to their original
    // registers, reserved R9-R12/SP identity-assigned — each segment is
    // independently sound, no cross-segment liveness assumed). Renames
    // registers only: never adds, removes, or reorders instructions, so
    // labels/branch offsets are unaffected.
    //
    // DEFAULT-ON since v0.11.36: gale cleared the gate on-target (G474RE,
    // #209 2026-06-10) — flag-on output byte-identical to flag-off on
    // flat_flight/controller/control_step, fires on the filter family with
    // zero cycle delta and a small size win, all selfchecks green on silicon.
    // Opt out with `SYNTH_RANGE_REALLOC=0`; per-function stats with
    // `SYNTH_REALLOC_STATS=1`.
    //
    // The companion dead callee-saved-save elimination (gale's "next
    // consequential lever", same issue comment) then shrinks the prologue
    // `push {r4-r8,lr}` / epilogue `pop {r4-r8,pc}` to the callee-saved
    // registers the re-allocated body still touches (leaf-only,
    // SP-untouched, even-count-padded — see shrink_callee_saved_saves):
    // ~12 cycles of pure save/restore overhead removed on small leaves.
    let realloc_on = std::env::var("SYNTH_RANGE_REALLOC").map_or(true, |v| v != "0");
    let (arm_instrs, ran_realloc) = if realloc_on {
        use synth_synthesis::rules::Reg;
        const POOL: [Reg; 9] = synth_synthesis::reg_contract::ALLOCATABLE;
        // VCR-DEC-001 (epic #242, the North Star's first foothold): the
        // SYNTH_GRAPH_ALLOC graph-colouring allocator SPIKE. When enabled it
        // replaces STEP 1 of the re-allocation (the segment-based
        // `reallocate_function`) with a whole-function Chaitin/Briggs colouring
        // (`graph_alloc::reallocate`) built against the SAME acceptance oracle
        // (`validate_segment_rewrite` trace-equality); the later dead-frame /
        // callee-saved-prologue / shrink passes still run on its output, so a
        // value it homes in R4-R8 still gets its callee-saved push (the
        // invariant the unconditional VCR-RA-003 validator guards). It is
        // BOUNDED to whole straight-line functions and DECLINES (returns None)
        // to the shipping `reallocate_function` on any control flow, spill, or
        // unmodeled op — never a hard-fail. Flag-OFF (`SYNTH_GRAPH_ALLOC` unset)
        // never enters this branch, so the shipping bytes are byte-identical
        // (the GOLDEN trick — frozen fixtures unchanged). NO default flip: the
        // spike ships flag-off; the flip is a later, evidence-gated step.
        //
        // VCR-VER-001 (#242): on a function the spill-on-exhaustion machinery
        // shaped, the terminal segment gets relaxed live-out pinning (only
        // R0/R1 are observable past `bx lr` at this pre-prologue position) so
        // the colourer can lower R4-R8-homed tails into caller-saved R0-R3 —
        // shrinking the `push {r4-r8,lr}` the #580 exhaustion shapes pay for.
        // `post_exhaust == false` selects the shipping pass bit for bit.
        let (out, stats) = if synth_synthesis::graph_alloc::enabled() {
            // RQ-60-RACOST increment 2 (#242): the colourer prices every
            // colour choice in REAL-ENCODER bytes. The sizer is the same
            // encoder family the emit loop below constructs — Thumb-2 (with
            // the target's FPU) or A32 — asked per candidate instruction, so
            // there is no hand size table to drift (#936). On the fixed-width
            // A32 ISA every candidate ties and the cost model degenerates to
            // the identity hint (zero churn).
            let sizing_encoder =
                if matches!(config.target.isa, IsaVariant::Thumb2 | IsaVariant::Thumb) {
                    ArmEncoder::new_thumb2_with_fpu(config.target.fpu)
                } else {
                    ArmEncoder::new_arm32()
                };
            let enc = |op: &synth_synthesis::rules::ArmOp| {
                sizing_encoder.encode(op).ok().map(|b| b.len())
            };
            let stats_on = std::env::var("SYNTH_GRAPH_ALLOC_STATS").is_ok();
            match synth_synthesis::graph_alloc::reallocate(&arm_instrs, &POOL, &enc) {
                // SYNTH_GRAPH_ALLOC_FORCE (test seam, RQ-60-RACOST
                // increment 2): ship every validated candidate WITHOUT the
                // final-byte arbiter — the pre-arbiter behaviour. Used by
                // `vcr_dec_001_join_alloc_execution_differential.py` so the
                // unicorn-vs-wasmtime oracle executes the colourer's
                // proposals on EVERY reachable shape (call, i64-pair,
                // shift-expansion), not only the ones the arbiter lets ship —
                // an arbiter-declined candidate is still a candidate a future
                // change could promote, and the execution teeth must stay
                // ahead of that. Never set in production; the arbiter is the
                // shipping behaviour.
                Some(candidate)
                    if std::env::var("SYNTH_GRAPH_ALLOC_FORCE").is_ok_and(|v| v != "0") =>
                {
                    if stats_on {
                        eprintln!(
                            "[graph-alloc] whole-function colouring APPLIED \
                             (validated; FORCED — arbiter bypassed)"
                        );
                    }
                    (
                        candidate,
                        synth_synthesis::liveness::ReallocStats::default(),
                    )
                }
                Some(candidate) => {
                    // FINAL-BYTE ARBITER (RQ-60-RACOST increment 2). A
                    // colour-time cost model — however faithful its byte sizes
                    // — cannot price DOWNSTREAM PASS INTERACTIONS: measured on
                    // const_cse.wat::spill12, an identity-shaped colouring
                    // that merely PRESERVED the greedy allocator's register
                    // rotation defeated const-CSE's canonicalization and grew
                    // the function 148 -> 244 B (+96), with not one occurrence
                    // priced differently at colour time. So the candidate is
                    // sized through the REAL downstream pipeline
                    // (`finish_allocated_stream` — the exact passes the
                    // shipped stream runs, not a mirror) plus label resolution
                    // and the REAL encoder, against the shipping allocator's
                    // stream sized identically, and it ships only when it is
                    // STRICTLY smaller. A tie or a refusal keeps the shipping
                    // bytes — growth on an applied function is structurally
                    // impossible, which is exactly the wired
                    // vcr_dec_001_graph_alloc_differential no-growth
                    // assertion, promoted from a gate into a construction.
                    let ship = synth_synthesis::liveness::reallocate_function_post_exhaust(
                        &arm_instrs,
                        &POOL,
                        post_exhaust,
                    );
                    let size_of = |stream: &[synth_synthesis::ArmInstruction]| -> Option<usize> {
                        let finished = match finish_allocated_stream(
                            stream.to_vec(),
                            config,
                            post_exhaust,
                            true,
                            selected_spill_areas.borrow().as_ref(),
                            selected_vfp_frame_homes.borrow().as_ref(),
                        ) {
                            Ok(f) => f,
                            Err(e) => {
                                if stats_on {
                                    // The differential greps for the RA-003
                                    // hard-error string to detect a SHIPPED
                                    // violation; a candidate refused during
                                    // sizing is a decline, not a shipped
                                    // violation, so that marker is rewritten.
                                    let e = e.replace(
                                        "register-allocation validation FAILED",
                                        "register-allocation validation refused the candidate",
                                    );
                                    eprintln!(
                                        "[graph-alloc] arbiter: stream refused by the \
                                         pipeline/validators: {e}"
                                    );
                                }
                                return None;
                            }
                        };
                        let finished = if matches!(
                            config.target.isa,
                            IsaVariant::Thumb2 | IsaVariant::Thumb
                        ) {
                            resolve_label_branches(finished, &sizing_encoder).ok()?
                        } else {
                            finished
                        };
                        let mut total = 0usize;
                        let mut literals = 0usize;
                        for ins in &finished {
                            total += sizing_encoder.encode(&ins.op).ok()?.len();
                            if matches!(ins.op, synth_synthesis::rules::ArmOp::LdrSym { .. }) {
                                literals += 1;
                            }
                        }
                        if literals > 0 {
                            // The emit loop 4-aligns the literal pool and
                            // appends one word per LdrSym (no dedup — each
                            // site carries its own addend).
                            total += (4 - total % 4) % 4 + 4 * literals;
                        }
                        Some(total)
                    };
                    match (size_of(&candidate), size_of(&ship.0)) {
                        (Some(cand), Some(base)) if cand < base => {
                            if stats_on {
                                eprintln!(
                                    "[graph-alloc] whole-function colouring APPLIED \
                                     (validated; arbiter: {cand} B < shipping {base} B)"
                                );
                            }
                            (
                                candidate,
                                synth_synthesis::liveness::ReallocStats::default(),
                            )
                        }
                        (cand, base) => {
                            if stats_on {
                                eprintln!(
                                    "[graph-alloc] arbiter kept shipping bytes \
                                     (candidate {cand:?} B vs shipping {base:?} B) → \
                                     shipping reallocate_function"
                                );
                            }
                            ship
                        }
                    }
                }
                None => {
                    if stats_on {
                        eprintln!("[graph-alloc] DECLINED → shipping reallocate_function");
                    }
                    synth_synthesis::liveness::reallocate_function_post_exhaust(
                        &arm_instrs,
                        &POOL,
                        post_exhaust,
                    )
                }
            }
        } else {
            synth_synthesis::liveness::reallocate_function_post_exhaust(
                &arm_instrs,
                &POOL,
                post_exhaust,
            )
        };
        if std::env::var("SYNTH_REALLOC_STATS").is_ok() {
            eprintln!(
                "[range-realloc] {} segments: {} reallocated, {} declined ({} validator-rejected), {} need spill (step 4)",
                stats.segments,
                stats.reallocated,
                stats.declined,
                stats.validator_rejects,
                stats.needs_spill
            );
        }
        // VCR-VER-004 AUDIT (#242) — report-only, opt-in, never gating.
        //
        // The ABI observable-contract validator is a GATE on the flag-off
        // graph-colouring spike. This hook asks the same question of the
        // SHIPPING allocator's rewrite, so the answer is a MEASUREMENT rather
        // than a claim: how much of the shipping path can a value-level,
        // ABI-anchored check actually see today? Report-only DELIBERATELY —
        // making it gate here would risk a false rejection on the default
        // path, and the honest sequence is measure first, flip on evidence.
        // `SYNTH_ABI_CONTRACT_AUDIT=1` prints one verdict per function.
        if std::env::var_os("SYNTH_ABI_CONTRACT_AUDIT").is_some() {
            eprintln!(
                "[abi-contract-audit] {:?}",
                synth_synthesis::abi_contract::validate_abi_contract(&arm_instrs, &out)
            );
        }
        (out, true)
    } else {
        (arm_instrs, false)
    };
    // RQ-60-RACOST increment 2 (#242): every rewrite pass between the chosen
    // allocation and the encoder now lives in `finish_allocated_stream`, so
    // the SYNTH_GRAPH_ALLOC final-byte arbiter can size a candidate through
    // the REAL pipeline. Flag-off this is the exact pre-extraction sequence,
    // called once, in the same place.
    let arm_instrs = finish_allocated_stream(
        arm_instrs,
        config,
        post_exhaust,
        ran_realloc,
        selected_spill_areas.borrow().as_ref(),
        selected_vfp_frame_homes.borrow().as_ref(),
    )?;

    // Encode to binary — use Thumb-2 for Cortex-M targets
    let use_thumb2 = matches!(config.target.isa, IsaVariant::Thumb2 | IsaVariant::Thumb);

    let encoder = if use_thumb2 {
        ArmEncoder::new_thumb2_with_fpu(config.target.fpu)
    } else {
        ArmEncoder::new_arm32()
    };

    // RQ-72-ISLANDS (#345): the documented opt-out. With islands disabled the
    // pool is emitted exactly where it always was — one block at the end — so
    // the two legs of `litpool_islands_345_differential.py` are a real
    // differential and not two names for the same path. Read HERE, above the
    // fixed point, because the placement decision is now part of it.
    let islands_disabled = std::env::var_os("SYNTH_NO_LITPOOL_ISLANDS").is_some();

    // #202 / RQ-73-ISLANDPASS (#1331): resolve local label branches
    // (Bcc/B/Bhs/Blo) to byte-accurate offsets AND decide literal-island
    // placements, in ONE fixed point. `select_with_stack` emits branches as
    // label placeholders and never resolves them — without this they encode as
    // `bne.n #0` and land mid-instruction whenever a 32-bit Thumb-2 instruction
    // sits between the branch and its target (UsageFault on real hardware).
    // Only meaningful for Thumb-2 (the offset units are halfword/PC+4).
    //
    // `planned_islands` maps an instruction index to the number of pooled words
    // to flush immediately BEFORE it. The emit loop obeys it rather than
    // re-deciding, so the offsets branches were resolved against and the
    // offsets the stream actually gets are the same numbers by construction.
    let (arm_instrs, planned_islands) = if use_thumb2 {
        let (resolved, islands) =
            place_literal_islands_fixedpoint(arm_instrs, &encoder, !islands_disabled)?;
        // SC-5 (#740/#930): hard-gate every branch target onto the
        // instruction-start set of the final stream — both codegen paths
        // funnel through here. See `validate_branch_targets`.
        validate_branch_targets(&resolved, &encoder, !islands_disabled)?;
        (resolved, islands)
    } else {
        (arm_instrs, std::collections::BTreeMap::new())
    };

    // #778: capture the FINAL Thumb-2 instruction stream (post label-resolution,
    // the exact list the encode loop below consumes) so `compile_function` can
    // derive the sound WCET bound. Cheap clone; frozen-safe (the WCET walk is a
    // pure observation and never touches `code`). Only the Thumb-2 path — the A32
    // (Cortex-R5) cycle model is a follow-up.
    let final_instrs_for_wcet: Option<Vec<synth_synthesis::ArmInstruction>> = if use_thumb2 {
        Some(arm_instrs.clone())
    } else {
        None
    };

    let mut code = Vec::new();
    let mut relocations = Vec::new();

    // #345: literal-pool address loads. Each `LdrSym` was encoded as a placeholder
    // `LDR.W rd,[pc,#0]`; record where its instruction sits and what it loads so
    // we can append a pooled word (carrying the symbol address via R_ARM_ABS32)
    // and patch the PC-relative offset once the pool position is known.
    let mut pending_literals: Vec<PendingLiteral> = Vec::new();
    // RQ-73-ISLANDPASS (#1331): the span guard and its decline are GONE, and
    // their absence is the deliverable. v0.72 computed `branch_spans` in
    // PRE-ISLAND coordinates and refused any placement that separated a branch
    // from its target, because the branch offsets had already been baked. The
    // fixed point above resolves branches against ISLAND-INCLUSIVE positions,
    // so there is no stale coordinate system left to invalidate — a spanning
    // placement is now correct rather than refused.

    // VCR-DBG-001: per-instruction source map for DWARF `.debug_line`. Captured
    // here because `code.len()` immediately before `encode()` is the final
    // machine offset of the instruction within this function's `.text` — nothing
    // after the loop shifts earlier instructions (the literal pool is appended at
    // the end; the LDR patch below is in-place/length-preserving). Purely
    // additive: it does not touch `code`, so `.text` is byte-identical.
    let mut line_map: LineMap = Vec::new();
    // VCR-DEC-003 (#396): object-branch class per emitted instruction, parallel
    // to `line_map`. Cheap, additive, does not touch `code`.
    let mut branch_map: synth_core::backend::BranchMap = Vec::new();

    for (instr_index, instr) in arm_instrs.iter().enumerate() {
        // ORDER IS LOAD-BEARING, and getting it wrong was a SILENT MISCOMPILE.
        //
        // Encoding and the island decision happen FIRST, before anything below
        // records a `code.len()`. The v0.72 round-2 cold review found the
        // previous order — record, then encode, then maybe insert an island —
        // shifting the instruction forward by the island's size while its
        // ALREADY-RECORDED offset stayed put. Measured, both rc=0, on objects
        // v0.71 had refused loudly:
        //
        //   an `R_ARM_THM_CALL` recorded at 0x1014, which after the flush holds
        //   the island's own `b.n +8`; the real BL sits at 0x101c. The linker
        //   writes a BL over the branch-over and execution falls into a pooled
        //   address word as instructions.
        //
        //   an `LdrSym` whose `ldr_offset` pointed INTO the island, so the
        //   imm12 patch landed there and the real LDR kept imm12=0 — loading
        //   CODE as a pointer.
        //
        // Four sites record an offset (`Bl`, `MovwSym`, `MovtSym`, `LdrSym`)
        // and all four were wrong the same way. Hoisting the flush above them
        // makes `code.len()` FINAL for this instruction at every one.
        //
        // "A pool can never precede the LDR it serves" is PRESERVED, and is now
        // structural rather than arithmetic: this instruction's own `LdrSym` is
        // pushed BELOW, so `pending_literals` cannot contain it here.
        // Encode BEFORE deciding whether to flush, so the island trigger below
        // works from this instruction's EXACT size rather than an upper bound.
        // An over-estimate here would flush early (merely wasteful); an
        // under-estimate would let the 4 KB window close and patch a wrong
        // `imm12` — a MISCOMPILE, which is the defect #1341/#345 exist to
        // prevent. Knowing the real length removes the estimate entirely.
        let encoded = encoder
            .encode(&instr.op)
            .map_err(|e| format!("ARM encoding failed: {}", e))?;

        // RQ-72-ISLANDS (#345): flush the pool INLINE, before the window closes.
        //
        // WHY INLINE AND NOT A POST-PASS THAT INSERTS: `line_map` and
        // `branch_map` are (offset, _) PAIRS captured as `code.len()` just
        // below, so appending here leaves every later pair correct, while
        // inserting into an already-built `code` would silently desynchronise
        // all of them — and `.text` byte-identity on modules that need no
        // island would not notice.
        //
        // If `instr` is itself the `LdrSym` just pushed, its `ldr_offset`
        // equals `code.len()`, so the computed distance is ~0 and this cannot
        // fire before the LDR it serves. That is the ordering that would
        // otherwise place a pool BEFORE its own load.
        // RQ-73-ISLANDPASS (#1331): OBEY the plan, do not re-derive it. The
        // flush rule now lives in `island_walk`, which is also what the branch
        // offsets were resolved against. Deciding again here would be a second
        // source of truth for "where does a pool go", and the two could
        // disagree by exactly the amount that mis-targets every branch over the
        // placement — the v0.72 defect, reintroduced one layer up.
        if let Some(&planned_n) = planned_islands.get(&instr_index) {
            // DRIFT GUARD, and it is the reason obeying a plan is safe. The
            // walk predicted this flush would carry `planned_n` words; if the
            // emit loop has a different number pending, the two walks have
            // diverged and every offset resolved against the prediction is
            // wrong. Refuse rather than emit a stream nobody checked.
            if pending_literals.len() != planned_n {
                return Err(format!(
                    "literal-island plan drift (#1331): the fixed point placed an \
                     island of {} pooled word(s) before instruction {}, but {} \
                     literal(s) are pending there. Branch offsets were resolved \
                     against the plan, so emitting this stream would mis-target \
                     every branch spanning the placement.",
                    planned_n,
                    instr_index,
                    pending_literals.len()
                ));
            }
            emit_literal_pool(
                &mut code,
                &mut relocations,
                &pending_literals,
                Some(&encoder),
            )?;
            pending_literals.clear();
        }

        // Record a relocation for every BL: the encoder emits `bl #0` and
        // relies on a relocation to patch the target. This covers BOTH import
        // dispatch stubs (`__meld_*`, undefined externals) AND internal calls
        // (`func_N`, defined in this object). Previously only `__meld_*` was
        // recorded, so internal `BL func_N` calls were left as unpatched
        // `bl #0` placeholders branching to a garbage address (#167).
        if let ArmOp::Bl { label } = &instr.op {
            // #1040: the relocation type is ISA-STATE-dependent and this is the
            // only site that knows the state. An A32 (Cortex-R) `bl` is
            // R_ARM_CALL (28); a Thumb `bl` is R_ARM_THM_CALL (10). Emitting
            // the Thumb type for an A32 word made any consumer that trusts the
            // declared type patch Thumb halfwords into an ARM-state
            // instruction. Decided here rather than in the ELF emitter, where
            // `config.target` is no longer in scope and the ISA would have to
            // be re-derived — the shape that produced the bug.
            let kind = if config.target.isa == synth_core::target::IsaVariant::Arm32 {
                synth_core::backend::RelocKind::ArmCall
            } else {
                synth_core::backend::RelocKind::ThmCall
            };
            relocations.push(CodeRelocation {
                offset: code.len() as u32,
                symbol: label.clone(),
                kind,
            });
        }
        // #237: symbol-relative MOVW/MOVT (the `--native-pointer-abi` static-data
        // addressing). The encoder writes the addend in place; record the matching
        // R_ARM_MOVW_ABS_NC / R_ARM_MOVT_ABS so the linker adds the symbol address.
        if let ArmOp::MovwSym { symbol, .. } = &instr.op {
            relocations.push(CodeRelocation {
                offset: code.len() as u32,
                symbol: symbol.clone(),
                kind: synth_core::backend::RelocKind::MovwAbs,
            });
        }
        if let ArmOp::MovtSym { symbol, .. } = &instr.op {
            relocations.push(CodeRelocation {
                offset: code.len() as u32,
                symbol: symbol.clone(),
                kind: synth_core::backend::RelocKind::MovtAbs,
            });
        }
        // #345: defer the literal-pool word + reloc + offset patch to the
        // post-loop pass (the pool address is not yet known).
        if let ArmOp::LdrSym { symbol, addend, .. } = &instr.op {
            pending_literals.push(PendingLiteral {
                ldr_offset: code.len() as u32,
                symbol: symbol.clone(),
                addend: *addend,
            });
        }

        // The machine offset of this instruction is the current code length,
        // captured before the bytes are appended (and AFTER any island above,
        // so the recorded offset is where the instruction really lands).
        line_map.push((code.len() as u32, instr.source_line));
        branch_map.push((code.len() as u32, classify_arm_branch(&instr.op)));

        code.extend_from_slice(&encoded);
    }

    // #345: place any REMAINING literals at the end of this function's `.text`.
    // Gated on there being at least one un-flushed `LdrSym` — functions without
    // one are byte-identical to before (no trailing padding, so downstream
    // `func_offsets` are unchanged and the frozen differential fixtures stay
    // bit-for-bit equal). No branch is emitted: these bytes sit past the final
    // return and are never executed.
    if !pending_literals.is_empty() {
        if !use_thumb2 {
            return Err("LdrSym literal-pool addressing requires Thumb-2".to_string());
        }
        // RQ-73-ISLANDPASS (#1331): the `island_declined_for_branch` wrapper
        // that used to sit here is GONE. It explained that a placement had been
        // refused because it fell between a branch and its target, and ended
        // "serving this shape needs branch resolution and island placement in
        // one fixed point". That fixed point now exists, so the refusal it
        // described is unreachable and an explanation of it would be a false
        // statement. What remains is the genuine out-of-range case: a pool that
        // no placement can bring within the 12-bit window.
        emit_literal_pool(&mut code, &mut relocations, &pending_literals, None)?;
    }

    // RQ-73-ISLANDPASS (#1331): every planned island must have been emitted.
    // The plan is what branch offsets were resolved against, so a placement the
    // emit loop skipped leaves every branch over it pointing past bytes that
    // were never written. `instr_index` only ever advances, so a key beyond the
    // last instruction would be silently ignored without this.
    if let Some((&last, _)) = planned_islands.iter().next_back()
        && last >= arm_instrs.len()
    {
        return Err(format!(
            "literal-island plan drift (#1331): an island was planned before \
                 instruction {}, but the stream has only {} instruction(s).",
            last,
            arm_instrs.len()
        ));
    }

    Ok((
        code,
        relocations,
        line_map,
        branch_map,
        final_instrs_for_wcet,
    ))
}

/// RQ-60-RACOST increment 2 (#242): every rewrite pass between a CHOSEN
/// register allocation and the encoder, as ONE reusable sequence.
///
/// Extracted VERBATIM from `compile_wasm_to_arm` (pure code motion) so the
/// `SYNTH_GRAPH_ALLOC` final-byte arbiter can size a candidate allocation
/// through the REAL downstream pipeline — the same passes, in the same order,
/// reading the same flags — rather than through a hand-mirrored predicate of
/// them (the #936 drift class: a hand mirror of the encoder's offset-fold
/// threshold was UNSOUND at authoring; a hand mirror of eleven rewrite passes
/// would be worse). Flag-off behaviour is byte-identical: the shipping path
/// calls this exactly once, on the same stream, in the same place it always
/// ran.
///
/// `ran_realloc` selects the historical branch: the dead-frame /
/// callee-saved-prologue / shrink trio runs only downstream of the range
/// re-allocation lever (`SYNTH_RANGE_REALLOC` on), exactly as before the
/// extraction. Diagnostics inside (SYNTH_FUSE_STATS, SYNTH_SHADOW_ALLOC,
/// SYNTH_SPILL_REPORT) print once per CALL, so an arbiter sizing run repeats
/// them — measurement noise under two opt-in flags, never a byte change.
fn finish_allocated_stream(
    arm_instrs: Vec<synth_synthesis::ArmInstruction>,
    config: &CompileConfig,
    post_exhaust: bool,
    ran_realloc: bool,
    // #1321: `(frame_size, areas)` recorded by the direct selector for the
    // attempt that produced this stream — the frame regions that are genuinely
    // allocator SPILL slots. Used to scope VCR-RA-003's #331 check, and ONLY
    // after `frame_size` is re-proven against this stream (see the use site).
    // `None` on the optimized path and whenever no area was reserved.
    recorded_spill_areas: Option<&(i32, Vec<std::ops::Range<i32>>)>,
    // RQ-71-VFPALIAS (#881/#1069): the permanent VFP frame homes from that same
    // attempt, proven against this stream by the identical `frame_size` test.
    // `None` on the optimized path and whenever selection granted no home.
    recorded_vfp_frame_homes: Option<&(i32, Vec<i32>)>,
) -> Result<Vec<synth_synthesis::ArmInstruction>, String> {
    let arm_instrs = if ran_realloc {
        let out = arm_instrs;
        // VCR-RA-002 (#390, epic #242): eliminate a provably-dead stack frame
        // (`sub sp,#N`/`add sp,#N` reserved by `compute_local_layout` for locals
        // that promotion homed in registers, never accessed). Removing it saves
        // the two instructions AND restores the SP-untouched precondition that
        // `shrink_callee_saved_saves` requires — so it must run FIRST.
        // DEFAULT-ON (#242 flag audit flip-wave, #592 audit item): evidence
        // basis was the 2-path × repro-corpus sweep — 0 functions grow, 58
        // shrink (flight_seam controller_step 250→242 −8 / filter_step 180→168
        // −12, native_pointer frame_roundtrip 46→34 −12), locked by the
        // `dead_frame_elim_no_grow_corpus_242` cargo gate; execution
        // differentials re-run green on the new default bytes BEFORE the
        // frozen ARM anchors were re-pinned (leaf_dead_frame, flight_seam,
        // frame_slot_dce — see the flip PR). Escape hatch:
        // `SYNTH_DEAD_FRAME_ELIM=0` opts out and restores the pre-flip bytes
        // (CI-gated in `frozen_codegen_bytes.rs`).
        let out = if !std::env::var("SYNTH_DEAD_FRAME_ELIM").is_ok_and(|v| v == "0") {
            synth_synthesis::liveness::elide_dead_frame(&out).unwrap_or(out)
        } else {
            out
        };
        // #490 (epic #242): the optimized selector uses r4-r8 as scratch /
        // promoted locals but emits no prologue, silently clobbering a caller's
        // callee-saved registers. Add the missing `push {r4-r8,lr}` /
        // `pop {r4-r8,pc}` HERE — on the post-realloc body, where realloc has
        // lowered low-pressure r4-r8 scratch back to r0-r3, so a save is added
        // only for registers genuinely clobbered. `shrink_callee_saved_saves`
        // (next) then trims it to the used set. No-op on the direct path (it
        // already has its own prologue) and on callee-saved-free leaves.
        let out = synth_synthesis::liveness::ensure_callee_saved_prologue(&out);
        synth_synthesis::liveness::shrink_callee_saved_saves(&out).unwrap_or(out)
    } else {
        // Range-realloc off (`SYNTH_RANGE_REALLOC=0`): the optimized path still
        // must preserve the callee-saved registers it clobbers (#490). No shrink
        // (it is coupled to the realloc lever), so the conservative full save
        // stays — correct, just not minimised in this debug configuration.
        synth_synthesis::liveness::ensure_callee_saved_prologue(&arm_instrs)
    };
    // VCR-RA-001 SHADOW ALLOCATION (#209/#242): run the register allocator on
    // the selected stream and LOG what it finds — without changing a single
    // emitted byte. This is the measure-only bridge between the built analysis
    // layer and the eventual virtual-register wiring: it shows, per real
    // function, whether the allocator can colour it within the R0–R8 pool and
    // how much const-CSE / rematerialization headroom exists (#209). Enable with
    // `SYNTH_SHADOW_ALLOC=1`; off by default and side-effect-free either way.
    if std::env::var("SYNTH_SHADOW_ALLOC").is_ok() {
        use synth_synthesis::liveness::{
            AllocationOutcome, allocate_function, function_peak_pressure,
        };
        // R9 globals / R10 mem-size / R11 mem-base / R12 IP-scratch are reserved;
        // pin them above the 0..9 allocatable pool so the colourer keeps R0–R8.
        let precolored = std::collections::BTreeMap::from([
            (synth_synthesis::rules::Reg::R9, 9usize),
            (synth_synthesis::rules::Reg::R10, 10),
            (synth_synthesis::rules::Reg::R11, 11),
            (synth_synthesis::rules::Reg::R12, 12),
        ]);
        // True VALUE pressure (one node per value, not per reused physical reg):
        // a NeedsSpill with peak ≤ 9 is a SPURIOUS physical-register spill — the
        // function fits once virtually allocated.
        let peak = function_peak_pressure(&arm_instrs);
        match allocate_function(&arm_instrs, 9, &precolored) {
            AllocationOutcome::Allocated {
                remat_opportunities,
                coloring,
            } => eprintln!(
                "[shadow-alloc] OK: {} pregs coloured within R0-R8 pool, peak value-pressure {}, {} const-CSE/remat opportunities",
                coloring.len(),
                peak,
                remat_opportunities
            ),
            AllocationOutcome::NeedsSpill(s) => eprintln!(
                "[shadow-alloc] physical-graph would spill {:?}, but peak value-pressure is {} (≤9 ⇒ spurious; fits once virtually allocated)",
                s, peak
            ),
            AllocationOutcome::Declined => {
                eprintln!(
                    "[shadow-alloc] declined (unmodeled construct — calls/i64/fp/offset-branch)"
                )
            }
        }
    }

    // VCR-SEL-004 cmp→select → IT-block predication fusion (#242). The selector
    // lowers a `select` whose condition is a comparison to a *materialize then
    // re-test* sequence (`cmp a,b; SetCond D,c; cmp D,#0; movne dst,v1; moveq
    // dst,v2`); this collapses it onto the comparison's own flags — deleting the
    // `SetCond` and the `cmp D,#0` and retargeting the predicated moves to `c` /
    // `invert(c)` — yielding the textbook predicated clamp (`cmp a,b; movc dst,v1;
    // mov{!c} dst,v2`). −2 instructions per fused select. gale #428 measured this
    // as the #1 hot-path size/cycle lever on the gust_mix clamp chain.
    //
    // Run LATE: after range re-allocation (so the dead-D proof sees final register
    // identities) and before encode. Removal-only + rename-only ⇒ no spill
    // regression and labels/branch offsets are unaffected. Each fusion is proven
    // sound (flags reused only when nothing clobbers them in the window; the
    // boolean deleted only when provably dead) — see `fuse_cmp_select`.
    //
    // DEFAULT-ON as of v0.13.0 (#428): cmp→select fusion ships by default. The
    // byte-changing flip is validated by (a) the unicorn execution oracle that runs
    // the two-move `mov{invert(c)}` arm (cmp_select_two_move_differential.py), (b)
    // gale's gale_decider_diff 10,596-case sweep across all 8 verified primitives
    // (native ≡ flag-off ≡ flag-on = 0x88e73178d232bcf5), and (c) the named-anchor
    // differentials re-run with fusion ON — control_step still 0x00210A55, flat+
    // inlined flight_algo still 0x07FDF307 (results preserved; bytes deliberately
    // changed, re-frozen on this commit). Escape hatch: `SYNTH_NO_CMP_SELECT_FUSE=1`
    // reverts to the pre-fusion lowering. The on-silicon G474RE DWT no-regression
    // check is a tracked post-ship follow-up (gale owns it).
    let arm_instrs = if std::env::var("SYNTH_NO_CMP_SELECT_FUSE").is_err() {
        // The rewritten stream is identical to `fuse_cmp_select`'s 2-tuple form;
        // the extra `two_move` count is diagnostic only (the fusion census /
        // blast-radius datum — #7 made that arm reachable).
        let (out, fused, two_move) =
            synth_synthesis::liveness::fuse_cmp_select_with_stats(&arm_instrs);
        if std::env::var("SYNTH_FUSE_STATS").is_ok() {
            let in_place = fused - two_move;
            eprintln!(
                "[cmp-select-fuse] {fused} select(s) fused to predicated moves \
                 ({two_move} two-move, {in_place} in-place)"
            );
        }
        out
    } else {
        arm_instrs
    };

    // Perf lever 1 toward native parity (#390): redundant stack-reload elimination.
    // synth lowers every wasm local to a frame slot, so `local.set; local.get` emits
    // `str rX,[sp,#N]; … ; ldr rY,[sp,#N]`; when rX still holds the value the reload
    // (a ~2-cycle M4 load) becomes `mov rY,rX`. Removal-of-a-load + rename only ⇒ no
    // new instruction form and no label/offset change. DEFAULT-ON (#242 feature
    // loop): validated bit-identical RESULTS on every frozen anchor (control_step
    // 0x00210A55 13/13, flat+inlined flight_algo 0x07FDF307) with .text reduced on
    // the shipped --relocatable path, plus 8 unit tests + the frame_slot_dce
    // execution differential — the same gated path cmp→select took to default-on in
    // v0.13.0 (G474RE silicon confirms perf post-ship). Escape hatch:
    // `SYNTH_NO_STACK_FWD=1` restores the frame-resident bytes (frozen-old goldens).
    let stack_fwd = std::env::var("SYNTH_NO_STACK_FWD").is_err();
    let arm_instrs = if stack_fwd {
        let (out, fwd) = synth_synthesis::liveness::forward_stack_reloads(&arm_instrs);
        if std::env::var("SYNTH_FUSE_STATS").is_ok() {
            eprintln!("[stack-fwd] {fwd} stack reload(s) forwarded to register moves");
        }
        out
    } else {
        arm_instrs
    };

    // VCR-RA frame-slot DCE (#242): once `forward_stack_reloads` has turned the
    // reloads of a spill slot into register moves, the `str rX,[sp,#N]` that fed
    // them is a dead store — its slot is never loaded again. Remove it. Pairs
    // with (and only pays after) stack-reload forwarding, so it shares the flag.
    let arm_instrs = if stack_fwd {
        let (out, n) = synth_synthesis::liveness::eliminate_dead_frame_stores(&arm_instrs);
        if std::env::var("SYNTH_FUSE_STATS").is_ok() {
            eprintln!("[frame-slot-dce] {n} dead frame store(s) removed");
        }
        out
    } else {
        arm_instrs
    };

    // VCR-RA-001 spill re-choice (#242), two stages behind one flag.
    // Stage 1 (the #569 spike): slot-value forwarding BETWEEN reloads.
    // `forward_stack_reloads` (above) forwards only from a spill store's
    // SOURCE register, so when register pressure clobbers that source its
    // reloads survive; this stage tracks which registers provably still hold
    // a frame slot's value (through earlier reloads and reg-reg moves) and
    // turns reload #2..#n into a 1-cycle `mov` (or deletes it when the target
    // already holds the value). Stage 2 (the Belady re-choice): where NO
    // register still holds the value — the genuine-spill case, flat_flight's
    // peak-11 hot segment — the value was usually evicted while a dead
    // register existed; the clobbering def(s) are renamed onto a provably-dead
    // register (`spill_rechoice_segment`) so the value stays resident and the
    // reload dissolves outright. A dissolved reload can leave the feeding
    // store dead, so the frame-slot DCE sweep runs once more behind the same
    // flag. Per-segment commit gates: executable same-value-flow trace
    // equality, strict shrink, pool-pressure fit, sub-word/unknown-slot
    // conservatism (see `apply_spill_realloc` / `spill_rechoice_segment`).
    // Stage 3 (whole-function slot liveness): the segment-local DCE keeps a
    // store whose slot reaches function end ("reach-end ≠ dead" — it cannot
    // see other segments); `eliminate_unread_frame_stores` walks the whole
    // function (labels/branches/loops, SP-displacement tracked) and drops a
    // store whose slot NO reachable instruction can read — flat_flight's two
    // surviving stores (#576), completing Belady's 0-load side with a 0-store
    // side. Same flag: the three stages are one lever, flipped together.
    // DEFAULT-ON (#242 feature loop, the v0.14.0 local-promotion pattern):
    // Belady spilling ships by default. Evidence basis for the flip: three
    // landed flag-off increments (#569 forwarding, #576 Belady re-choice,
    // #579 whole-fn slot liveness), 40+ functions shrink / 0 grow across the
    // 68-fixture × 2-path sweep, per-segment executable value-trace equality
    // guards, and the unicorn-vs-wasmtime execution differentials re-run
    // green on the new default bytes (flat+inlined flight_algo 0x07FDF307,
    // const_cse, frame_slot_dce, spill_rung_581, r12_spill_496 — which covers
    // control_step_decide vs wasmtime; control_step's .text is byte-identical
    // under the flip) BEFORE the frozen goldens were re-pinned. Escape hatch:
    // `SYNTH_SPILL_REALLOC=0` is the OPT-OUT — it disables all three stages
    // and restores the pre-flip bytes (CI-gated by
    // `frozen_fixtures_spill_realloc_escape_hatch_restores_old_bytes`). Any
    // other value (or unset) runs the pass.
    // VCR-VER-001 post-exhaustion extensions (#242, the PR #659 verdict): with
    // `SYNTH_SPILL_ON_EXHAUST` active the #580 allocation-time Belady spill
    // keeps exhausted functions on the optimized path, and its slots present
    // shapes the shipping pass structurally cannot fire on (fresh-monotonic
    // slots defeat the overwrite-only DCE; the eviction store's source is
    // redefined immediately, defeating store→reload forwarding; R2/R3 are
    // never touched again, so the rename-target deadness proof declines them).
    // `post_exhaust` (bridge-scoped, see above) enables const
    // rematerialization of spilled constants, R2/R3 exit-dead rename targets,
    // and per-pair pressure commit — see `apply_spill_realloc_post_exhaust`.
    // Flag off (the default): `false` selects the shipping behavior bit for
    // bit.
    let arm_instrs = if !std::env::var("SYNTH_SPILL_REALLOC").is_ok_and(|v| v == "0") {
        let (out, n) =
            synth_synthesis::liveness::apply_spill_realloc_post_exhaust(&arm_instrs, post_exhaust);
        let (out, d) = synth_synthesis::liveness::eliminate_dead_frame_stores(&out);
        let (mut out, u) = synth_synthesis::liveness::eliminate_unread_frame_stores(&out);
        let (mut tn, mut td, mut tu) = (n, d, u);
        // Post-exhaustion only: iterate the triple to a bounded fixpoint. Each
        // dissolved spill pair frees registers and removes stores, exposing
        // rename windows and holder chains the previous iteration could not
        // prove — the allocation-time Belady slots (#580) routinely need two
        // or three rounds where the shipping single round suffices for the
        // default path's slots. Every iteration is individually gate-proven
        // (value-trace equality, pool pressure, strict shrink), so iterating
        // composes soundly; the bound keeps compile time deterministic.
        if post_exhaust {
            let mut progress = n + d + u > 0;
            for _ in 0..3 {
                if !progress {
                    break;
                }
                let (o, n) =
                    synth_synthesis::liveness::apply_spill_realloc_post_exhaust(&out, true);
                let (o, d) = synth_synthesis::liveness::eliminate_dead_frame_stores(&o);
                let (o, u) = synth_synthesis::liveness::eliminate_unread_frame_stores(&o);
                progress = n + d + u > 0;
                (tn, td, tu) = (tn + n, td + d, tu + u);
                out = o;
            }
            // The cleanup can leave the spill frame with zero surviving
            // accesses (every reload rematerialized/dissolved, every store
            // swept) — the balanced `sub sp,#K`/`add sp,#K` is then pure
            // overhead. `elide_dead_frame` proves that and removes the pair;
            // its early run (post-realloc) could not, because the spill
            // traffic was still in the stream at that point.
            out = synth_synthesis::liveness::elide_dead_frame(&out).unwrap_or(out);
        }
        if std::env::var("SYNTH_FUSE_STATS").is_ok() {
            eprintln!(
                "[spill-realloc] {tn} reload(s) forwarded/eliminated, {td} newly-dead frame store(s) removed, {tu} unread-slot store(s) removed"
            );
        }
        out
    } else {
        arm_instrs
    };

    // VCR-RA immediate-shift folding (#390, #242): a constant shift amount the
    // stack selector materialized into a scratch register (`movw rM,#C; lsl rD,rN,rM`)
    // folds to the immediate form (`lsl rD,rN,#C`), removing the dead `movw` — −1
    // instruction, −1 live register. Removal-only (offset-neutral before branch
    // resolution, like the dead-store pass). DEFAULT-ON as of v0.15.0: validated
    // bit-identical results + a net cycle win on the dissolved hot path (−2
    // cyc/call, .text 100→90 B on gust_mix). Escape hatch: `SYNTH_NO_IMM_SHIFT_FOLD=1`.
    let arm_instrs = if std::env::var("SYNTH_NO_IMM_SHIFT_FOLD").is_err() {
        let (out, folds) = synth_synthesis::liveness::fold_immediate_shifts(&arm_instrs);
        if std::env::var("SYNTH_FUSE_STATS").is_ok() {
            eprintln!(
                "[imm-shift-fold] {folds} register shift(s) folded to immediate, movw dropped"
            );
        }
        out
    } else {
        arm_instrs
    };

    // #686: elide the #682 mod-32 shift-amount mask (`and r12,rK,#31` before
    // every register-controlled i32 shl/shr) when the amount is STATICALLY
    // provable < 32 — a const amount folds to the immediate-shift form
    // (reduced mod 32, so >= 32 shrinks too), and an already-masked amount
    // (`rK = rX & c`, c < 32) drops the redundant re-mask. gale measured the
    // unconditional mask at ~12% cyc/call (+14 B) on gust_mix, whose Q8
    // fixed-point shifts are all constants (#686). The mask stays wherever
    // the bound is unproven — elision is an optimization, the mask is the
    // sound default (`liveness::elide_shift_masks` has the proof
    // obligations). Runs after `fold_immediate_shifts` (whose movw→shift
    // window the #682 mask intercepts, so it declines every masked const
    // shift) and before branch resolution (removal/rewrite-only ⇒
    // offset-neutral).
    //
    // DEFAULT-ON since v0.50.1 (opt-out via `SYNTH_SHIFT_MASK_ELIDE=0`; #846).
    // gale's gpio-thin driver regressed +44 B / +9% on synth 0.49 — its pin
    // bit-arithmetic (`pin & 31` then a register shift) emits the source
    // `and rN,#0x1f` IMMEDIATELY followed by the #682 mod-32 re-mask
    // `and r12,rN,#0x1f`; the second is provably redundant (Pattern B: an
    // operand produced by `and X,#c`, c<32, is already in [0,31]), so the
    // pass drops it. Flipping default-on is a deliberate byte-changing
    // refreeze: the elision also moves the frozen anchors (const-amount
    // shifts fold back to the immediate form) — control_step −20 B,
    // flight_seam −166 B, flight_seam_flat −168 B — all size DECREASES with
    // the mask soundly kept for every unproven amount. All differentials were
    // re-run on the new bytes and the goldens re-pinned (see #846 PR /
    // `frozen_codegen_bytes.rs`). `SYNTH_SHIFT_MASK_ELIDE=0` restores the
    // pre-flip bytes (opt-out gate in `shift_mask_elide_686.rs`).
    let arm_instrs = if std::env::var("SYNTH_SHIFT_MASK_ELIDE").is_ok_and(|v| v == "0") {
        arm_instrs
    } else {
        let (out, elisions) = synth_synthesis::liveness::elide_shift_masks(&arm_instrs);
        if std::env::var("SYNTH_FUSE_STATS").is_ok() {
            eprintln!(
                "[shift-mask-elide] {elisions} provably-<32 shift-amount mask(s) elided (#686)"
            );
        }
        out
    };

    // VCR-RA uxth/uxtb fold (#428, #242): `movw rM,#0xffff; and rD,rN,rM` →
    // `uxth rD,rN` (and the 0xff/uxtb form), removing the dead `movw` — −1
    // instruction, −1 live register per 16/8-bit mask. 0xffff/0xff are not Thumb-2
    // modified immediates so the selector materializes them into a register; the
    // dedicated zero-extend expresses the same masking inline. Removal-only +
    // rewrite-in-place (offset-neutral). DEFAULT-ON (#242 flag audit flip-wave,
    // #592 audit item): evidence basis was the 2-path × repro-corpus sweep —
    // 0 functions grow, 13 shrink (control_step 300→294 −6, gust_mix 38→32 −6,
    // uxth_fold pack 36→24 −12), locked by the `uxth_fold_no_grow_corpus_242`
    // cargo gate; execution differentials re-run green on the new default
    // bytes BEFORE the frozen ARM anchors were re-pinned (uxth_fold,
    // control_step — see the flip PR). Escape hatch: `SYNTH_UXTH_FOLD=0` opts
    // out and restores the pre-flip bytes (CI-gated in
    // `frozen_codegen_bytes.rs`).
    let arm_instrs = if !std::env::var("SYNTH_UXTH_FOLD").is_ok_and(|v| v == "0") {
        let (out, folds) = synth_synthesis::liveness::fold_uxth(&arm_instrs);
        if std::env::var("SYNTH_FUSE_STATS").is_ok() {
            eprintln!("[uxth-fold] {folds} mask-and folded to uxth/uxtb, movw dropped");
        }
        out
    } else {
        arm_instrs
    };

    // VCR-RA-001 const-CSE / rematerialization-avoidance (#209, #242). Drops a
    // `movw`/`mov #imm` that re-materializes a constant already resident in
    // another register and retargets the reads — every rewrite proven by the
    // liveness analysis. Runs LAST, after every immediate-fold (shift, uxth) and
    // range-realloc, but BEFORE branch resolution/encoding (it removes
    // instructions, shifting byte offsets). CSE-last is the #242 no-regression
    // fix: the folds have already absorbed every foldable constant, so CSE can no
    // longer defeat one (the gust_mix 90→92 mechanism). The pass additionally
    // size-guards each segment via the byte-estimator — it commits a segment's
    // rewrites only if they do not grow its estimated size — so a retarget that
    // would flip a 16-bit encoding to 32-bit (higher base register) is declined.
    // DEFAULT-ON (#242 flip-wave, the SYNTH_SPILL_REALLOC/SYNTH_BASE_CSE
    // template): const-CSE ships by default. The flip prerequisites recorded in
    // `const_cse_reduction_242.rs` were retired first — the bridge-level INLINE
    // aliasing (the alias-eviction spill-bijection hazard) was DELETED from
    // `optimizer_bridge::ir_to_arm`, so this post-hoc, liveness-proven pass is
    // the flag's ONLY effect. Evidence basis: 152 fixture×path corpus sweep — 0
    // functions grow (size-guarded per segment), 40 shrink (const_cse::spill12
    // 236→148 B), total −536 B — and the execution differentials re-run green
    // on the new default bytes BEFORE the frozen goldens were re-pinned
    // (const_cse, frame_slot_dce, flight_seam 0x07FDF307, spill_rung_581,
    // volatile_segment_543, control_step 0x00210A55). Escape hatch:
    // `SYNTH_CONST_CSE=0` is the OPT-OUT — it restores the pre-flip bytes
    // (CI-gated by `const_cse_escape_hatch_restores_old_bytes_242` and the
    // frozen-anchor escape-hatch gate). Any other value (or unset) runs the pass.
    //
    // #543 Phase 2: const-CSE declines WHOLESALE while any volatile DMA range
    // (`--volatile-segment`) is marked. At the ArmOp level a cached constant
    // cannot be classified as address-vs-data (a retargeted read may be a
    // memory-access base carrying a per-use immediate offset), so the
    // conservative stance for statically-unknown addressing is to decline every
    // aliasing rewrite — each constant is re-materialized at each occurrence,
    // the documented volatile contract (`CompileConfig::volatile_segments`).
    let arm_instrs = if !std::env::var("SYNTH_CONST_CSE").is_ok_and(|v| v == "0")
        && config.volatile_segments.is_empty()
    {
        let (out, removed) = synth_synthesis::liveness::apply_const_cse(&arm_instrs);
        if std::env::var("SYNTH_FUSE_STATS").is_ok() {
            eprintln!("[const-cse] {removed} redundant constant materialization(s) removed");
        }
        out
    } else {
        arm_instrs
    };

    // VCR-RA-001 spill-choice REPORT (#242): measure-only, like SYNTH_SHADOW_ALLOC.
    // Per straight-line segment, the frame-slot traffic actually emitted vs the
    // reload/store count a farthest-next-use (Belady) allocation over the R0-R8
    // pool would need — the measured headroom for the full spill-choice rewrite.
    // Printed on the FINAL stream (post all rewrite passes), so a flag-off run
    // reports the greedy baseline and a flag-on run reports what remains.
    if std::env::var("SYNTH_SPILL_REPORT").is_ok() {
        for seg in synth_synthesis::liveness::spill_choice_report(&arm_instrs, 9) {
            if seg.actual_reloads + seg.actual_spill_stores > 0 || seg.peak_pressure > 9 {
                eprintln!(
                    "[spill-report] seg@{} len={} peak={} actual={}ld+{}st belady(k=9)={}ld+{}st",
                    seg.start,
                    seg.len,
                    seg.peak_pressure,
                    seg.actual_reloads,
                    seg.actual_spill_stores,
                    seg.belady_reloads,
                    seg.belady_spill_stores
                );
            }
        }
    }

    // ISA feature gate: validate that all generated instructions are supported
    // by the target. This catches FPU instructions on no-FPU targets, double-precision
    // instructions on single-precision targets, etc.
    validate_instructions(&arm_instrs, config.target.fpu, &config.target.triple)
        .map_err(|e| format!("ISA validation failed: {}", e))?;

    // VCR-RA-003 (epic #242): UNCONDITIONAL per-compilation register-allocation
    // validation. The register allocator is the last major unverified codegen
    // component; this whole-function checker proves — by construction, on the
    // EXACT emitted stream about to be encoded — that the allocation preserves
    // FOUR invariants whose reference lives in the stream (or the ABI): (1)
    // callee-saved preservation (#490), (2) spill-slot non-aliasing (#331), and
    // — PHASE 2 (#49), extending past straight-line — (3) caller-saved
    // preservation across calls (a value in R2/R3/R12 live across a `bl` the
    // AAPCS boundary destroys), and (4) value availability across control-flow
    // joins (a live-in to a join must be defined on every incoming edge). It runs
    // on every ARM compile in the DEFAULT shipping build (NOT behind
    // `--features verify`; a verify-gated check would be dormant in exactly the
    // build that ships — the #757 / VCR-VER-003 lesson) and hard-errors the
    // compile on a VIOLATION. A `NotAttempted` verdict (the join check declines
    // on an unmodeled-CF function: numeric branch, `BrTable`, etc.) is NON-FATAL
    // — the compile proceeds; the other three invariants were still checked and
    // held. This is the decline>guess doctrine applied to the checker itself: it
    // never claims join coherence it cannot prove, but it also never blocks a
    // correct compile for a construct it simply doesn't model yet. Frozen-safe:
    // it emits nothing, so `.text` is byte-identical (proven by the frozen suite).
    // #1321: scope the #331 spill-slot check to the frame regions the allocator
    // actually hands out as spill slots — but ONLY while the record provably
    // still describes THIS stream. Between selection and here the stream passes
    // through re-allocation, dead-frame elimination and prologue shrink, any of
    // which can re-lay or remove the frame. A stale area list would narrow the
    // check over the wrong offsets — the silent weakening this lane exists to
    // avoid — so the areas are used only if the final stream still allocates
    // EXACTLY the frame they were computed for. On any mismatch (re-laid frame,
    // eliminated frame, optimized path, no record) we pass `None` and every
    // `[sp,#N]` offset is policed, bit for bit as before. The fix can go stale;
    // it cannot go wrong.
    // The staleness proof, shared by both records: this stream still allocates
    // EXACTLY the frame they were computed for. Factored into one closure so the
    // spill areas and the VFP frame homes cannot drift apart — they come from
    // the same selection and must stand or fall together.
    let frame_still_matches = |frame_size: &i32| {
        arm_instrs.iter().any(|ins| {
            matches!(
                &ins.op,
                synth_synthesis::rules::ArmOp::Sub {
                    rd: synth_synthesis::rules::Reg::SP,
                    rn: synth_synthesis::rules::Reg::SP,
                    op2: synth_synthesis::rules::Operand2::Imm(n),
                } if n == frame_size
            )
        })
    };
    let spill_areas: Option<&[std::ops::Range<i32>]> = match recorded_spill_areas {
        Some((frame_size, areas)) if frame_still_matches(frame_size) => Some(areas.as_slice()),
        _ => None,
    };
    // RQ-71-VFPALIAS (#881/#1069): same gate, same failure direction. A stale or
    // absent home set means the #881 twin polices every VFP `[sp,#N]` offset,
    // which is what it did before this narrowing existed.
    let vfp_frame_homes: Option<&[i32]> = match recorded_vfp_frame_homes {
        Some((frame_size, halves)) if frame_still_matches(frame_size) => Some(halves.as_slice()),
        _ => None,
    };
    match synth_synthesis::liveness::validate_final_allocation_in_areas_with_vfp_homes(
        &arm_instrs,
        spill_areas,
        vfp_frame_homes,
    ) {
        synth_synthesis::liveness::RaFinalVerdict::Violation(v) => {
            return Err(format!(
                "VCR-RA-003: register-allocation validation FAILED — {v:?}. \
                 The emitted stream violates a register-allocation invariant \
                 (callee-saved preservation #490 / spill-slot non-aliasing #331 \
                 / caller-saved-across-call / join-value-availability / the #881 \
                 VFP twins); this is a \
                 compiler bug, not a program error. Refusing to emit a \
                 miscompiled object."
            ));
        }
        // Loud honest decline (join reasoning skipped for an unmodeled-CF
        // function). Non-fatal — the straight-line / callee-saved / across-call
        // invariants still ran and held; only the across-JOIN availability
        // reasoning is skipped. Since the #819 redo the optimized path's
        // pre-resolved NUMERIC branches are modeled too (build_join_cfg_numeric
        // + the PRESERVED entry-availability discriminator), so this fires only
        // on genuinely unmodeled shapes: BrTable, computed Bx, mixed
        // label+numeric streams, off-boundary numeric targets.
        // Surfaced only under `SYNTH_RA003_VERBOSE` so a production compile stays
        // quiet: emitting it unconditionally would print on every branchy
        // optimized-path compile (new stderr noise phase 1 never produced), yet
        // it must remain observable on demand for the honest-scope audit.
        synth_synthesis::liveness::RaFinalVerdict::NotAttempted { reason } => {
            if std::env::var_os("SYNTH_RA003_VERBOSE").is_some() {
                eprintln!(
                    "VCR-RA-003: across-join validation NOT ATTEMPTED ({reason}) — \
                     straight-line / callee-saved / across-call invariants held; \
                     join-availability reasoning declined on this control-flow shape."
                );
            }
        }
        synth_synthesis::liveness::RaFinalVerdict::Consistent => {
            if std::env::var_os("SYNTH_RA003_VERBOSE").is_some() {
                eprintln!("VCR-RA-003: Consistent");
            }
        }
    }
    Ok(arm_instrs)
}

/// VCR-DEC-003 (#396): classify one emitted `ArmOp` into its object-level
/// control-flow role for the `synth-provenance-v1` map. Conditional branches are
/// the object decision points MC/DC must reconcile; `SelectMove` is the folded
/// (IT-block) predicated form the cmp→select fuse produces — a decision with no
/// branch.
fn classify_arm_branch(op: &ArmOp) -> synth_core::backend::BranchClass {
    use synth_core::backend::BranchClass;
    match op {
        ArmOp::Bcc { .. } | ArmOp::Bhs { .. } | ArmOp::Blo { .. } | ArmOp::BCondOffset { .. } => {
            BranchClass::CondBranch
        }
        ArmOp::B { .. } | ArmOp::BOffset { .. } => BranchClass::UncondBranch,
        ArmOp::SelectMove { .. } => BranchClass::Predicated,
        _ => BranchClass::Other,
    }
}

/// The branch-over for a literal island at `at`, and the alignment padding
/// after it. SINGLE SOURCE for the island's byte length (#1331).
///
/// `emit_literal_pool` needs the BYTES; `island_walk` needs the LENGTH before
/// any bytes exist. Both call this, so the "how big is an island" question has
/// exactly one answer. A second copy is what the v0.72 header means by drift.
///
/// The branch's own size decides the distance it must cover, and the distance
/// decides the size (B.N is 2 bytes, B.W is 4), so this iterates to its own
/// small fixed point rather than assuming one.
fn island_branch_over(at: usize, n: usize, enc: &ArmEncoder) -> Result<(Vec<u8>, usize), String> {
    let mut branch_len = 2usize;
    loop {
        let pad = (4 - ((at + branch_len) % 4)) % 4;
        let skip = branch_len + pad + 4 * n;
        // `BOffset` takes the halfword displacement (target - branch - 4)/2.
        // `at` is even at any Thumb instruction boundary and `branch_len` is
        // even, so `pad` is even and `skip` is even.
        let off = ((skip as i32) - 4) / 2;
        let e = enc
            .encode(&ArmOp::BOffset { offset: off })
            .map_err(|x| format!("island branch encoding failed: {}", x))?;
        if e.len() == branch_len {
            return Ok((e, pad));
        }
        branch_len = e.len();
        if branch_len > 4 {
            return Err(format!(
                "literal-pool island (#345): branch over {} pooled word(s) \
                 would need {} bytes, which is not a Thumb-2 B encoding",
                n, branch_len
            ));
        }
    }
}

/// One left-to-right walk that decides island placements AND the byte position
/// of every instruction, in the SAME coordinates (#1331).
///
/// An island only moves code that comes AFTER it, so placements can be decided
/// in a single pass: by the time this reaches instruction `i`, every island
/// before it is already counted in `pos`. That is why the outer fixed point
/// below iterates over BRANCH SIZES only — the island decision is not itself
/// circular, the branch encodings are.
///
/// The flush rule is the one the emit loop used to apply inline, moved here
/// unchanged: if the LAST pooled word would fall outside the 12-bit unsigned
/// `LDR(literal)` window measured from the FIRST pending LDR, the pool must be
/// flushed before this instruction.
///
/// Returns (position of each instruction, instruction index -> pooled words
/// flushed immediately before it).
fn island_walk(
    instrs: &[ArmInstruction],
    encoder: &ArmEncoder,
    enabled: bool,
) -> Result<(Vec<usize>, std::collections::BTreeMap<usize, usize>), String> {
    let mut positions = Vec::with_capacity(instrs.len());
    let mut islands = std::collections::BTreeMap::new();
    let mut pending: Vec<usize> = Vec::new();
    let mut pos: usize = 0;

    for (i, instr) in instrs.iter().enumerate() {
        let size = encoder
            .encode(&instr.op)
            .map_err(|e| format!("island-walk size probe failed: {}", e))?
            .len();

        if enabled && !pending.is_empty() {
            // Worst case if we DON'T flush now: this instruction lands, then a
            // branch (<= 4 B) and alignment (<= 3 B) precede the words. Same
            // arithmetic the emit loop used, in the same coordinates.
            let start = pos + size + 4;
            let pad = (4 - (start % 4)) % 4;
            let last_word = (start + pad + 4 * (pending.len() - 1)) as u32;
            let aligned_pc = ((pending[0] + 4) & !3usize) as u32;
            if last_word.saturating_sub(aligned_pc) > 0xFFF {
                let n = pending.len();
                let (b, pad2) = island_branch_over(pos, n, encoder)?;
                islands.insert(i, n);
                pos += b.len() + pad2 + 4 * n;
                pending.clear();
            }
        }

        positions.push(pos);
        // The LDR this instruction IS registers only AFTER the decision above,
        // exactly as the emit loop pushes it below the flush. That ordering is
        // what makes "a pool can never precede the LDR it serves" structural.
        if matches!(instr.op, ArmOp::LdrSym { .. }) {
            pending.push(pos);
        }
        pos += size;
    }
    Ok((positions, islands))
}

/// RQ-73-ISLANDPASS (#1331): ONE fixed point over branch offsets AND literal
/// island placement.
///
/// THE DEFECT THIS CLOSES. Branch offsets used to be byte-resolved BEFORE the
/// encode loop, and islands were then inserted DURING it. An island between a
/// branch and its target moves the target and not the branch, by exactly the
/// island's size. v0.72 could only REFUSE such placements (loudly, which was
/// right) — so a 4 KB+ function with any control flow spanning its pool did not
/// compile at all. That is cpetig's #1331.
///
/// WHY IT NEEDS A FIXED POINT AND NOT AN ADJUSTMENT. Islands change sizes,
/// which change positions, which change which branches need 32-bit encodings,
/// which change sizes again. That is LLVM's `ARMConstantIslandPass` shape.
/// Note what is and is NOT circular here: an island only moves code AFTER it,
/// so `island_walk` decides every placement in ONE left-to-right pass. The
/// iteration below exists for the BRANCH ENCODINGS, exactly as it always did —
/// the loop is unchanged in kind, it just now walks island-inclusive positions.
///
/// Returns the resolved stream and `instruction index -> pooled words to flush
/// immediately before it`. The emit loop CONSUMES that map instead of deciding
/// anything itself, which is what makes one answer rather than two.
fn place_literal_islands_fixedpoint(
    arm_instrs: Vec<ArmInstruction>,
    encoder: &ArmEncoder,
    islands_enabled: bool,
) -> Result<
    (
        Vec<ArmInstruction>,
        std::collections::BTreeMap<usize, usize>,
    ),
    String,
> {
    use std::collections::HashMap;
    use synth_synthesis::Condition;

    enum BKind {
        Cond(Condition),
        Uncond,
    }
    // Record each label branch ONCE — indices are stable across iterations.
    let mut branches: Vec<(usize, BKind, String)> = Vec::new();
    for (i, instr) in arm_instrs.iter().enumerate() {
        match &instr.op {
            ArmOp::Bcc { cond, label } => branches.push((i, BKind::Cond(*cond), label.clone())),
            ArmOp::Bhs { label } => branches.push((i, BKind::Cond(Condition::HS), label.clone())),
            ArmOp::Blo { label } => branches.push((i, BKind::Cond(Condition::LO), label.clone())),
            ArmOp::B { label } => branches.push((i, BKind::Uncond, label.clone())),
            _ => {}
        }
    }
    if branches.is_empty() {
        // No label branches, but islands may still be needed — a 4 KB+
        // straight-line function is exactly the #345 case. Walk once.
        let (_, islands) = island_walk(&arm_instrs, encoder, islands_enabled)?;
        return Ok((arm_instrs, islands));
    }

    let mut resolved = arm_instrs;
    let mut islands = std::collections::BTreeMap::new();
    // Sizes only grow (16→32-bit), so this converges quickly; cap for safety.
    // The cap is now load-bearing in a second way: with islands in the loop a
    // pathological oscillation is conceivable, and a NON-converging placement
    // must be a loud error rather than whatever the last iteration happened to
    // hold. `converged` below is that guard.
    let mut converged = false;
    for _ in 0..16 {
        // 1. Byte position of each instruction, ISLAND-INCLUSIVE. This is the
        //    whole change: the positions branches are resolved against are the
        //    ones the emitted stream will actually have.
        let (pos_usize, islands_now) = island_walk(&resolved, encoder, islands_enabled)?;
        let positions: Vec<i64> = pos_usize.iter().map(|&p| p as i64).collect();
        islands = islands_now;
        // 2. Label name -> byte position (owned keys so the borrow ends here).
        let mut labels: HashMap<String, i64> = HashMap::new();
        for (i, instr) in resolved.iter().enumerate() {
            if let ArmOp::Label { name } = &instr.op {
                labels.insert(name.clone(), positions[i]);
            }
        }
        // 3. Rewrite each branch to its byte-accurate offset.
        let mut changed = false;
        for (idx, kind, label) in &branches {
            // A label not defined locally is an EXTERNAL target (e.g.
            // `Trap_Handler` resolved by a relocation / the vector table). Leave
            // such branches as their placeholder for the existing relocation
            // path — only local control-flow labels are byte-resolved here.
            let Some(&target) = labels.get(label) else {
                continue;
            };
            // Encoder consumes the field as (target - branch - 4) / 2 halfwords.
            // Positions are always even, so this division is exact.
            let halfword_offset = ((target - positions[*idx] - 4) / 2) as i32;
            let new_op = match kind {
                BKind::Cond(c) => ArmOp::BCondOffset {
                    cond: *c,
                    offset: halfword_offset,
                },
                BKind::Uncond => ArmOp::BOffset {
                    offset: halfword_offset,
                },
            };
            if resolved[*idx].op != new_op {
                resolved[*idx].op = new_op;
                changed = true;
            }
        }
        if !changed {
            converged = true;
            break;
        }
    }
    if !converged {
        return Err(
            "literal-island placement (#1331) did not reach a fixed point in 16 \
             iterations — branch sizes and island positions are oscillating. \
             Refusing to emit a stream whose branch offsets were never stable."
                .to_string(),
        );
    }
    Ok((resolved, islands))
}

/// The pre-#1331 entry point, preserved for callers that only want branch
/// resolution. Delegates with islands OFF so there is ONE implementation of the
/// branch fixed point rather than two that can drift.
fn resolve_label_branches(
    arm_instrs: Vec<ArmInstruction>,
    encoder: &ArmEncoder,
) -> Result<Vec<ArmInstruction>, String> {
    Ok(place_literal_islands_fixedpoint(arm_instrs, encoder, false)?.0)
}

/// SC-5 branch-target boundary gate (#740, #930): every emitted branch target
/// must be a member of the instruction-start set of the final stream.
///
/// "Branch offset calculation shall account for Thumb instruction alignment
/// and variable instruction widths" (`safety/stpa/system-constraints.yaml`
/// SC-5). Thumb-2 mixes 16- and 32-bit encodings, so an off-by-one-halfword
/// target lands on the SECOND halfword of a wide instruction and the CPU
/// executes a halfword that was never an instruction — silent garbage, exit 0
/// (#930: the skipped `movw` left the `br_if` condition register at its reset
/// value). Both known escapes of that sentence were of this class: #740
/// (`B<cond>.W` T3 offset halved) and #930 (inner-block end label never
/// emitted, `b #0` placeholder). The encoder knows where every instruction
/// starts, so a target outside that set is a hard error here rather than
/// silent garbage on target.
///
/// Runs on the FINAL Thumb-2 stream for BOTH codegen paths — the direct
/// (`select_with_stack`, label branches byte-resolved above) and the optimized
/// (`optimizer_bridge`, numeric `BOffset`/`BCondOffset` pre-resolved inline) —
/// since both funnel through this encode pipeline. Two checks, jointly total
/// over local control flow:
///
/// 1. every numeric branch target is in the instruction-start set;
/// 2. no LOCAL (`.L`-prefixed) label branch survives unresolved — the resolver
///    deliberately skips labels it cannot find because an external target
///    (`Trap_Handler`, `func_N`) is legitimately absent and patched by
///    relocation, but a `.L` label is only ever defined in this same stream,
///    so an unresolved one is a dropped label (#930), not an external.
///
/// A32 (Cortex-R5) is fixed-width, so the mid-instruction class needs no gate
/// there (and its branches do not flow through the Thumb-2 resolver).
fn validate_branch_targets(
    instrs: &[ArmInstruction],
    encoder: &ArmEncoder,
    islands_enabled: bool,
) -> Result<(), String> {
    use std::collections::HashSet;

    // Byte position of each element (`Label` encodes to 0 bytes, so a label's
    // position is exactly the start of the instruction that follows it).
    //
    // RQ-73-ISLANDPASS (#1331): ISLAND-INCLUSIVE, via the same walk the branch
    // offsets were resolved against. This gate previously sized the stream
    // itself, island-free, and that is not a coordinate system the emitted
    // object ever has once a pool is placed inline — it FALSE-REJECTED a
    // correctly-resolved spanning branch ("targets 0x26c2, which is not an
    // instruction start"). A gate and the thing it gates must measure in the
    // same units; sharing `island_walk` is what guarantees they do.
    let (pos_usize, _) = island_walk(instrs, encoder, islands_enabled)?;
    let positions: Vec<i64> = pos_usize.iter().map(|&p| p as i64).collect();
    let starts: HashSet<i64> = positions.iter().copied().collect();

    for (i, instr) in instrs.iter().enumerate() {
        let offset = match &instr.op {
            ArmOp::BOffset { offset } => *offset,
            ArmOp::BCondOffset { offset, .. } => *offset,
            ArmOp::B { label }
            | ArmOp::Bcc { label, .. }
            | ArmOp::Bhs { label }
            | ArmOp::Blo { label }
                if label.starts_with(".L") =>
            {
                return Err(format!(
                    "SC-5 branch-target gate: local branch label '{}' is not \
                     defined anywhere in the emitted stream (branch at byte \
                     offset 0x{:x}). A `.L` label is only ever defined locally, \
                     so this is a dropped label (the #930 class) — the branch \
                     would encode as a `b #0` placeholder and land \
                     mid-instruction. Refusing to emit a miscompiled object.",
                    label, positions[i]
                ));
            }
            _ => continue,
        };
        // Thumb branch semantics: target = branch_pc + 4 + 2*offset.
        let target = positions[i] + 4 + 2 * offset as i64;
        if !starts.contains(&target) {
            return Err(format!(
                "SC-5 branch-target gate: branch at byte offset 0x{:x} targets \
                 0x{:x}, which is not an instruction boundary (instruction-start \
                 set violation — the target lands mid-instruction, the \
                 #740/#930 class). Refusing to emit a miscompiled object.",
                positions[i], target
            ));
        }
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use synth_synthesis::{Operand2, Reg};

    /// #539: `i32.const 0; memory.grow m` folds to `memory.size m`; other deltas
    /// (const non-zero, runtime) are left as `memory.grow` (→ the sound fixed-
    /// memory -1). Non-grow ops are untouched, so functions without the idiom are
    /// byte-identical.
    #[test]
    fn test_rewrite_memory_grow_zero_539() {
        // the idiom -> memory.size
        assert_eq!(
            rewrite_memory_grow_zero(&[WasmOp::I32Const(0), WasmOp::MemoryGrow(0)]),
            vec![WasmOp::MemorySize(0)]
        );
        // const non-zero delta: NOT folded
        assert_eq!(
            rewrite_memory_grow_zero(&[WasmOp::I32Const(2), WasmOp::MemoryGrow(0)]),
            vec![WasmOp::I32Const(2), WasmOp::MemoryGrow(0)]
        );
        // runtime delta (no preceding const): NOT folded
        assert_eq!(
            rewrite_memory_grow_zero(&[WasmOp::LocalGet(0), WasmOp::MemoryGrow(0)]),
            vec![WasmOp::LocalGet(0), WasmOp::MemoryGrow(0)]
        );
        // a bare const-0 not feeding a grow is untouched
        assert_eq!(
            rewrite_memory_grow_zero(&[WasmOp::I32Const(0), WasmOp::I32Add]),
            vec![WasmOp::I32Const(0), WasmOp::I32Add]
        );
        // fold is local: surrounding ops preserved, indices past the fold intact
        assert_eq!(
            rewrite_memory_grow_zero(&[
                WasmOp::LocalGet(0),
                WasmOp::I32Const(0),
                WasmOp::MemoryGrow(0),
                WasmOp::I32Add,
            ]),
            vec![WasmOp::LocalGet(0), WasmOp::MemorySize(0), WasmOp::I32Add]
        );
    }

    /// SC-5 (#740/#930): the branch-target boundary gate. Every emitted branch
    /// target must be a member of the instruction-start set of the final
    /// Thumb-2 stream; a `.L`-local label branch surviving unresolved is a
    /// dropped label. Red-first: both rejection arms were written against the
    /// exact #930 stream shape (a `b #0` placeholder whose pc+4 target falls
    /// on the second halfword of a 32-bit `movw`) and fail without the gate.
    #[test]
    fn test_validate_branch_targets_sc5_930() {
        let enc = ArmEncoder::new_thumb2();
        let ins = |op: ArmOp| ArmInstruction {
            op,
            source_line: None,
        };

        // 1. Boundary-valid stream: b over a wide movw onto the mov — OK.
        //    positions: 0 BOffset(2B), 2 Movw(4B), 6 Mov(2B)
        //    target = 0 + 4 + 2*1 = 6 = start of Mov.
        let good = vec![
            ins(ArmOp::BOffset { offset: 1 }),
            ins(ArmOp::Movw {
                rd: Reg::R3,
                imm16: 1,
            }),
            ins(ArmOp::Mov {
                rd: Reg::R0,
                op2: Operand2::Reg(Reg::R3),
            }),
        ];
        assert!(validate_branch_targets(&good, &enc, false).is_ok());

        // 2. The exact #930 shape: `b #0` (offset 0) -> target = pc+4 = 4,
        //    the SECOND halfword of the 4-byte movw spanning 2..6. Hard error.
        let mid = vec![
            ins(ArmOp::BOffset { offset: 0 }),
            ins(ArmOp::Movw {
                rd: Reg::R3,
                imm16: 1,
            }),
            ins(ArmOp::Mov {
                rd: Reg::R0,
                op2: Operand2::Reg(Reg::R3),
            }),
        ];
        let err = validate_branch_targets(&mid, &enc, false).unwrap_err();
        assert!(err.contains("SC-5"), "boundary violation names SC-5: {err}");
        assert!(err.contains("not an instruction boundary"), "{err}");

        // 3. Conditional form of the same violation.
        let mid_cond = vec![
            ins(ArmOp::BCondOffset {
                cond: synth_synthesis::Condition::NE,
                offset: 0,
            }),
            ins(ArmOp::Movw {
                rd: Reg::R3,
                imm16: 1,
            }),
            ins(ArmOp::Mov {
                rd: Reg::R0,
                op2: Operand2::Reg(Reg::R3),
            }),
        ];
        assert!(validate_branch_targets(&mid_cond, &enc, false).is_err());

        // 4. A `.L`-local label branch that was never resolved (the dropped
        //    end label, #930's mechanism) is a hard error even though it
        //    would encode as a well-formed placeholder.
        let dropped = vec![
            ins(ArmOp::B {
                label: ".Lblock_end_3".to_string(),
            }),
            ins(ArmOp::Movw {
                rd: Reg::R3,
                imm16: 1,
            }),
        ];
        let err = validate_branch_targets(&dropped, &enc, false).unwrap_err();
        assert!(err.contains(".Lblock_end_3"), "{err}");
        assert!(err.contains("dropped label"), "{err}");

        // 5. An EXTERNAL label branch (no `.L` prefix) is legitimately absent
        //    (patched via relocation / vector table) and must NOT trip the
        //    gate — the carve-out that used to swallow #930 stays for real
        //    externals only.
        let external = vec![
            ins(ArmOp::B {
                label: "Trap_Handler".to_string(),
            }),
            ins(ArmOp::Movw {
                rd: Reg::R3,
                imm16: 1,
            }),
        ];
        assert!(validate_branch_targets(&external, &enc, false).is_ok());

        // 6. Labels are zero-width: a target on a Label position is the start
        //    of the instruction that follows it — OK.
        let labeled = vec![
            ins(ArmOp::BOffset { offset: 1 }),
            ins(ArmOp::Movw {
                rd: Reg::R3,
                imm16: 1,
            }),
            ins(ArmOp::Label {
                name: ".Lend".to_string(),
            }),
            ins(ArmOp::Mov {
                rd: Reg::R0,
                op2: Operand2::Reg(Reg::R3),
            }),
        ];
        assert!(validate_branch_targets(&labeled, &enc, false).is_ok());
    }

    /// SC-5 (#930) end-to-end at the backend seam: the labels.wast `br_if2`
    /// shape — a `br_if` exiting an enclosing block from inside an `if`, its
    /// value operand a block-that-branches — must COMPILE (the pre-fix
    /// selector dropped the inner block's end label, which the SC-5 gate now
    /// turns into a hard error, so compile success proves the label was
    /// emitted) and every branch in the emitted bytes must land on an
    /// instruction boundary (re-derived from the encoded halfwords, not from
    /// the resolver's own bookkeeping).
    #[test]
    fn test_930_brif2_shape_compiles_and_targets_boundaries() {
        let backend = ArmBackend::new();
        let ops = vec![
            WasmOp::Block, // $l0 (result i32)
            WasmOp::I32Const(1),
            WasmOp::If,
            WasmOp::Block, // $l1 (result i32)
            WasmOp::I32Const(1),
            WasmOp::Br(0), // br $l1
            WasmOp::End,
            WasmOp::I32Const(1),
            WasmOp::BrIf(1), // br_if $l0
            WasmOp::Drop,
            WasmOp::End, // end if
            WasmOp::I32Const(0),
            WasmOp::End, // end $l0
            WasmOp::End,
        ];
        let config = CompileConfig::default();
        let func = backend
            .compile_function("t", &ops, &config)
            .expect("#930 shape must compile (SC-5 gate passes)");

        // Walk the encoded halfwords: collect instruction starts, then check
        // every narrow/wide B / B<cond> target is a member.
        let code = &func.code;
        let mut starts = std::collections::HashSet::new();
        let mut widths = Vec::new();
        let mut off = 0usize;
        while off + 2 <= code.len() {
            starts.insert(off as i64);
            let hw = u16::from_le_bytes([code[off], code[off + 1]]);
            let wide = (hw & 0xF800) >= 0xE800; // 0b11101/0b11110/0b11111
            widths.push((off, hw, wide));
            off += if wide { 4 } else { 2 };
        }
        for (off, hw, wide) in widths {
            let target = if !wide && (hw & 0xF800) == 0xE000 {
                // T2 B: imm11, halfwords
                let imm = ((hw & 0x7FF) as i32) << 21 >> 21;
                Some(off as i64 + 4 + 2 * imm as i64)
            } else if !wide && (hw & 0xF000) == 0xD000 && (hw & 0x0F00) < 0x0E00 {
                // T1 B<cond>: imm8, halfwords
                let imm = ((hw & 0xFF) as i32) << 24 >> 24;
                Some(off as i64 + 4 + 2 * imm as i64)
            } else {
                None
            };
            if let Some(t) = target {
                assert!(
                    starts.contains(&t),
                    "branch at 0x{off:x} (hw 0x{hw:04x}) targets 0x{t:x}, \
                     not an instruction boundary — the #930 miscompile shape"
                );
            }
        }
    }

    #[test]
    fn test_arm_backend_name() {
        let backend = ArmBackend::new();
        assert_eq!(backend.name(), "arm");
        assert!(backend.is_available());
    }

    #[test]
    fn test_arm_backend_capabilities() {
        let backend = ArmBackend::new();
        let caps = backend.capabilities();
        assert!(!caps.produces_elf);
        assert!(caps.supports_rule_verification);
        assert!(!caps.is_external);
    }

    #[test]
    fn test_compile_add_function() {
        let backend = ArmBackend::new();
        let ops = vec![WasmOp::LocalGet(0), WasmOp::LocalGet(1), WasmOp::I32Add];
        let config = CompileConfig::default();

        let result = backend.compile_function("add", &ops, &config);
        assert!(result.is_ok());

        let func = result.unwrap();
        assert_eq!(func.name, "add");
        assert!(!func.code.is_empty());
        assert_eq!(func.wasm_ops, ops);
    }

    /// VCR-DBG-001: the per-instruction source map must cover the function with
    /// monotonic, in-bounds machine offsets, and must not perturb the emitted
    /// code (it is captured at encode time, never serialized here).
    #[test]
    fn test_line_map_is_wellformed_dbg001() {
        let backend = ArmBackend::new();
        let ops = vec![
            WasmOp::LocalGet(0),
            WasmOp::LocalGet(1),
            WasmOp::I32Add,
            WasmOp::End,
        ];
        let config = CompileConfig::default();
        let func = backend.compile_function("add", &ops, &config).unwrap();

        // Non-empty, and the first instruction starts at machine offset 0.
        assert!(
            !func.line_map.is_empty(),
            "a non-trivial function captures a source map"
        );
        assert_eq!(func.line_map[0].0, 0, "first instruction at offset 0");

        // Offsets strictly increase by at least one ARM/Thumb instruction (>= 2
        // bytes) and every mapped offset lies inside the emitted `.text`.
        for w in func.line_map.windows(2) {
            assert!(w[1].0 > w[0].0, "instruction offsets strictly increase");
            assert!(
                w[1].0 - w[0].0 >= 2,
                "each ARM/Thumb instruction is >= 2 bytes"
            );
        }
        let last = func.line_map.last().unwrap().0 as usize;
        assert!(
            last < func.code.len(),
            "every mapped offset lies inside .text"
        );

        // The side-table is additive: recompiling is deterministic and the map is
        // consistent with that exact code (capturing it does not alter output).
        let again = backend.compile_function("add", &ops, &config).unwrap();
        assert_eq!(
            again.code, func.code,
            "compilation deterministic; map is additive"
        );
        assert_eq!(again.line_map, func.line_map);
    }

    #[test]
    fn test_count_params() {
        let ops = vec![WasmOp::LocalGet(0), WasmOp::LocalGet(1), WasmOp::I32Add];
        assert_eq!(count_params(&ops), 2);

        let no_params = vec![WasmOp::I32Const(5), WasmOp::I32Const(3), WasmOp::I32Add];
        assert_eq!(count_params(&no_params), 0);
    }

    /// #457: the declared param count caps the access-pattern inference. The
    /// repro shape `(param i32)(local i32) → p0 + local1` reads local 1 before
    /// any write, so `count_params` infers 2 — with the declared count (1) the
    /// local is reclassified onto the zero-inited frame path instead of being
    /// read from R1 (caller garbage).
    #[test]
    fn declared_param_count_caps_inference_457() {
        let ops = vec![
            WasmOp::LocalGet(0),
            WasmOp::LocalGet(1),
            WasmOp::I32Add,
            WasmOp::End,
        ];
        // The inference alone still says 2 (the misclassification this caps).
        assert_eq!(count_params(&ops), 2);

        let backend = ArmBackend::new();
        let inferred = backend
            .compile_function("rbw", &ops, &CompileConfig::default())
            .unwrap();
        let declared = backend
            .compile_function(
                "rbw",
                &ops,
                &CompileConfig {
                    current_func_param_count: Some(1),
                    ..CompileConfig::default()
                },
            )
            .unwrap();
        // The cap is consumed: the declared-count compile reclassifies local 1
        // and must emit different code than the param-misclassified one.
        assert_ne!(
            inferred.code, declared.code,
            "declared param count must reach the selector"
        );
        // The zero-init is present: a 16-bit Thumb `movs rN, #0`
        // (0x2000 | rd<<8 → LE bytes [0x00, 0x20+rd]) somewhere in the body.
        let has_movs_zero = declared
            .code
            .as_chunks::<2>()
            .0
            .iter()
            .any(|h| h[0] == 0x00 && (0x20..=0x27).contains(&h[1]));
        assert!(
            has_movs_zero,
            "declared-count compile must zero-init the read-before-write local; code: {:02x?}",
            declared.code
        );
        // A declared count that matches (or exceeds) the inference changes
        // nothing — byte-identity for every function without rbw locals.
        let matching = backend
            .compile_function(
                "rbw",
                &ops,
                &CompileConfig {
                    current_func_param_count: Some(2),
                    ..CompileConfig::default()
                },
            )
            .unwrap();
        assert_eq!(
            matching.code, inferred.code,
            "declared >= inferred must stay byte-identical"
        );
    }

    /// #970: a CONDITIONALLY-written param must stay a param.
    ///
    /// The read-first heuristic sees `LocalSet(1)` before any `LocalGet(1)` in
    /// LINEAR op order and demotes index 1 — even though the `if` means the
    /// write may not execute at all. `min(referenced, declared)` keeps it.
    /// The RED symptom this pins is not a wrong constant: the demoted local's
    /// first access is a WRITE, so the #457 zero-init skips it and the
    /// fall-through arm reads an UNINITIALISED frame slot (executed evidence:
    /// `scripts/repro/cond_write_param_970_arm_differential.py`).
    #[test]
    fn conditionally_written_param_stays_a_param_970() {
        // (param i32 i32): if (local.get 0) { local.set 1 = 5 }; local.get 1
        let ops = vec![
            WasmOp::LocalGet(0),
            WasmOp::If,
            WasmOp::I32Const(5),
            WasmOp::LocalSet(1),
            WasmOp::End,
            WasmOp::LocalGet(1),
            WasmOp::End,
        ];
        let declared = CompileConfig {
            current_func_param_count: Some(2),
            ..CompileConfig::default()
        };
        // The old rule: index 1 is written before it is read, so it is not
        // counted — this is the undercount that produced the miscompile.
        assert_eq!(
            count_params(&ops),
            1,
            "the read-first heuristic must still undercount (this is the defect)"
        );
        assert_eq!(
            effective_num_params(&ops, &declared),
            2,
            "a conditionally-written param must be counted as a param"
        );
        // The #457 direction is untouched: a genuine non-param local is still
        // clamped away by the declared count.
        let rbw = vec![
            WasmOp::LocalGet(0),
            WasmOp::LocalGet(1),
            WasmOp::I32Add,
            WasmOp::End,
        ];
        assert_eq!(
            effective_num_params(
                &rbw,
                &CompileConfig {
                    current_func_param_count: Some(1),
                    ..CompileConfig::default()
                }
            ),
            1,
            "#457: a read-before-write non-param local must NOT become a param"
        );
        // Leniency: a body touching only the first few of many declared params
        // still lowers with the small count (the selector homes at most 4 in
        // registers; `min` is what keeps this from becoming `declared`).
        assert_eq!(
            effective_num_params(
                &rbw,
                &CompileConfig {
                    current_func_param_count: Some(12),
                    ..CompileConfig::default()
                }
            ),
            2,
            "declared >> referenced must stay at the referenced count"
        );
        // No declared count: the legacy inference, unchanged (honest residual).
        assert_eq!(
            effective_num_params(&ops, &CompileConfig::default()),
            count_params(&ops)
        );
    }

    #[test]
    fn test_arm_backend_register() {
        let mut registry = synth_core::BackendRegistry::new();
        registry.register(Box::new(ArmBackend::new()));
        assert!(registry.get("arm").is_some());
        assert_eq!(registry.available().len(), 1);
    }

    #[test]
    fn test_compile_import_call_produces_relocations() {
        let backend = ArmBackend::new();
        // Simulate a WASM module where func index 0 is an import.
        // Call(0) should generate MOV R0, #0; BL __meld_dispatch_import
        let ops = vec![WasmOp::Call(0)];
        let config = CompileConfig {
            num_imports: 1,
            no_optimize: true, // Direct instruction selection to preserve Call semantics
            ..CompileConfig::default()
        };

        let result = backend.compile_function("caller", &ops, &config);
        assert!(result.is_ok());

        let func = result.unwrap();
        assert!(!func.code.is_empty());
        assert_eq!(func.relocations.len(), 1);
        assert_eq!(func.relocations[0].symbol, "__meld_dispatch_import");
        // The BL is the second instruction (after MOV R0, #0), so offset should be > 0
        assert!(func.relocations[0].offset > 0);
    }

    /// Regression test for #197: in `relocatable` mode, an import call must
    /// relocate against the direct `func_N` symbol (rewritten to the wasm field
    /// name by `build_relocatable_elf`), NOT `__meld_dispatch_import`. This is
    /// the ABI half of the #197 fix — without it, a host linker cannot resolve
    /// the call to the real kernel symbol (e.g. `k_spin_lock`).
    #[test]
    fn test_compile_relocatable_import_uses_direct_func_symbol_197() {
        let backend = ArmBackend::new();
        let ops = vec![WasmOp::Call(0)]; // func 0 is an import
        let config = CompileConfig {
            num_imports: 1,
            relocatable: true,
            ..CompileConfig::default()
        };

        let func = backend
            .compile_function("caller", &ops, &config)
            .expect("relocatable import call compiles");

        assert_eq!(func.relocations.len(), 1);
        assert_eq!(
            func.relocations[0].symbol, "func_0",
            "#197: relocatable import must relocate against func_0 (→ field name), not Meld dispatch"
        );
    }

    #[test]
    fn test_compile_no_imports_no_relocations() {
        let backend = ArmBackend::new();
        let ops = vec![WasmOp::LocalGet(0), WasmOp::LocalGet(1), WasmOp::I32Add];
        let config = CompileConfig::default();

        let func = backend.compile_function("add", &ops, &config).unwrap();
        assert!(func.relocations.is_empty());
    }

    /// Regression test for #167: a call to an INTERNAL function
    /// (index `>= num_imports`) must record a relocation against `func_{index}`.
    /// Before the fix, only `__meld_*` (import) BLs were relocated, so
    /// internal `BL func_N` was emitted as an unpatched `bl #0` branching
    /// to a garbage address — making the object non-linkable. This test
    /// would have caught that regression.
    #[test]
    fn test_compile_internal_call_produces_relocation_167() {
        let backend = ArmBackend::new();
        // num_imports = 1, so Call(2) is an INTERNAL call → `BL func_2`.
        let ops = vec![WasmOp::Call(2)];
        let config = CompileConfig {
            num_imports: 1,
            no_optimize: true,
            ..CompileConfig::default()
        };

        let func = backend
            .compile_function("caller", &ops, &config)
            .expect("internal call compiles");

        assert_eq!(
            func.relocations.len(),
            1,
            "an internal call must emit exactly one relocation (#167)"
        );
        assert_eq!(
            func.relocations[0].symbol, "func_2",
            "internal call must relocate against the callee's func_{{index}} symbol (#167)"
        );
    }

    // ─── Phase 1 safety-bounds plumbing for ARM ──────────────────────────

    #[test]
    fn arm_safety_bounds_mpu_emits_same_code_as_none() {
        // Mpu mode must not introduce any inline check on ARM — the MPU
        // handles faults via hardware. The encoded bytes for an i32.load
        // should be identical between None and Mpu.
        let backend = ArmBackend::new();
        let ops = vec![
            WasmOp::LocalGet(0),
            WasmOp::I32Load {
                offset: 0,
                align: 2,
            },
        ];
        let cfg_none = CompileConfig {
            no_optimize: true,
            ..Default::default()
        };
        let cfg_mpu = CompileConfig {
            no_optimize: true,
            safety_bounds: SafetyBounds::Mpu,
            ..Default::default()
        };
        let n = backend.compile_function("ld", &ops, &cfg_none).unwrap();
        let m = backend.compile_function("ld", &ops, &cfg_mpu).unwrap();
        assert_eq!(
            n.code, m.code,
            "Mpu and None should produce identical ARM bytes (Mpu relies on hardware)"
        );
    }

    #[test]
    fn arm_legacy_bounds_check_still_emits_software_check() {
        // Legacy CLI users with `--bounds-check` should keep getting the
        // software path even though the new SafetyBounds field defaults to None.
        let backend = ArmBackend::new();
        let ops = vec![
            WasmOp::LocalGet(0),
            WasmOp::I32Load {
                offset: 0,
                align: 2,
            },
        ];
        let cfg_legacy = CompileConfig {
            no_optimize: true,
            bounds_check: true,
            ..Default::default()
        };
        let cfg_software = CompileConfig {
            no_optimize: true,
            safety_bounds: SafetyBounds::Software,
            ..Default::default()
        };
        let l = backend.compile_function("ld", &ops, &cfg_legacy).unwrap();
        let s = backend.compile_function("ld", &ops, &cfg_software).unwrap();
        assert_eq!(
            l.code, s.code,
            "--bounds-check should produce the same bytes as --safety-bounds=software"
        );
    }

    /// #377: `--safety-bounds software` must be enforced on the OPTIMIZED path
    /// too. Pre-fix, `software` was byte-identical to `none` there (a silent
    /// no-op while the safety manifest claimed enforcement). The compiled
    /// bytes must now (a) differ from `none` and (b) contain the inline
    /// `CMP ip, sl` + `UDF` guard.
    #[test]
    fn arm_safety_bounds_software_enforced_on_optimized_path_377() {
        let backend = ArmBackend::new();
        // Dynamic-address store+load: the optimized path accepts this shape
        // (no calls, no i64 params, ≤4 params).
        let ops = vec![
            WasmOp::LocalGet(0),
            WasmOp::LocalGet(1),
            WasmOp::I32Store {
                offset: 4,
                align: 2,
            },
            WasmOp::LocalGet(0),
            WasmOp::I32Load {
                offset: 0,
                align: 2,
            },
        ];
        // no_optimize NOT set — this exercises the optimized path.
        let cfg_none = CompileConfig::default();
        let cfg_sw = CompileConfig {
            safety_bounds: SafetyBounds::Software,
            ..Default::default()
        };
        let n = backend.compile_function("st", &ops, &cfg_none).unwrap();
        let s = backend.compile_function("st", &ops, &cfg_sw).unwrap();
        assert_ne!(
            n.code, s.code,
            "#377: software bounds must CHANGE optimized-path codegen (was a silent no-op)"
        );
        // Thumb-2 `UDF #0` is 0xDE00 (LE bytes: 00 DE); the #752
        // wraparound-safe guard's borrow check `CMP sl, ip` (16-bit
        // high-reg form) is 0x45E2 (LE: E2 45). Both must appear — one
        // guard per access, traps inline.
        let has_udf = s.code.windows(2).any(|w| w == [0x00, 0xDE]);
        let has_cmp_sl_ip = s.code.windows(2).any(|w| w == [0xE2, 0x45]);
        assert!(has_udf, "#377: inline UDF trap missing from optimized path");
        assert!(
            has_cmp_sl_ip,
            "#377/#752: CMP sl, ip bounds borrow-check missing from optimized path"
        );
        // And `none` must contain NO UDF (the function has no other trap).
        assert!(
            !n.code.windows(2).any(|w| w == [0x00, 0xDE]),
            "none must not contain a UDF for this function"
        );
    }

    /// #377: `mpu` on the optimized path is codegen-passthrough — identical
    /// bytes to `none` on BOTH paths (hardware enforcement is target-level;
    /// synth does not emit MPU region programming — tracked separately in
    /// #377's fix-direction discussion). This pins path-parity for `mpu`.
    #[test]
    fn arm_safety_bounds_mpu_optimized_path_parity_377() {
        let backend = ArmBackend::new();
        let ops = vec![
            WasmOp::LocalGet(0),
            WasmOp::I32Load {
                offset: 0,
                align: 2,
            },
        ];
        let cfg_none = CompileConfig::default();
        let cfg_mpu = CompileConfig {
            safety_bounds: SafetyBounds::Mpu,
            ..Default::default()
        };
        let n = backend.compile_function("ld", &ops, &cfg_none).unwrap();
        let m = backend.compile_function("ld", &ops, &cfg_mpu).unwrap();
        assert_eq!(
            n.code, m.code,
            "Mpu and None must produce identical bytes on the optimized path too"
        );
    }

    /// #377: `mask` on the optimized path declines to the direct selector
    /// (honest degradation) — the compiled function must equal the
    /// `--no-optimize` masking bytes, i.e. the flag is honored, never dropped.
    #[test]
    fn arm_safety_bounds_mask_optimized_path_declines_to_direct_377() {
        let backend = ArmBackend::new();
        let ops = vec![
            WasmOp::LocalGet(0),
            WasmOp::LocalGet(1),
            WasmOp::I32Store {
                offset: 0,
                align: 2,
            },
        ];
        // RQ-57-SENTINEL: mask now requires a STATED non-zero power-of-two
        // size (0 = zero-byte memory = refused), so the test states one —
        // exactly what the #953 fix required of the rv32 driver test.
        let cfg_mask_opt = CompileConfig {
            safety_bounds: SafetyBounds::Mask,
            linear_memory_bytes: 64 * 1024,
            ..Default::default()
        };
        let cfg_mask_direct = CompileConfig {
            no_optimize: true,
            safety_bounds: SafetyBounds::Mask,
            linear_memory_bytes: 64 * 1024,
            ..Default::default()
        };
        let o = backend.compile_function("st", &ops, &cfg_mask_opt).unwrap();
        let d = backend
            .compile_function("st", &ops, &cfg_mask_direct)
            .unwrap();
        assert_eq!(
            o.code, d.code,
            "#377: mask on the optimized path must fall back to the direct selector's masking"
        );
    }

    /// RQ-57-SENTINEL (#953 sibling): `--safety-bounds mask` with a ZERO-byte
    /// linear memory must REFUSE at compile time. Before this fix, `bytes == 0`
    /// was exempt from the power-of-two gate ("0 means unknown"), and the
    /// emitted `SUB R12, R10, #1; AND` guard degenerated to an IDENTITY mask
    /// at runtime (R10 = 0 baked by the startup for a `(memory 0)` module):
    /// an unbounded OOB access in the mode whose purpose is bounding.
    /// Red-first: pre-fix this compile SUCCEEDED (verified on the v0.56.1
    /// tree: exit 0, `movw r10, #0x0` in the reset handler, AND-masked body).
    #[test]
    fn arm_safety_bounds_mask_zero_size_refused_rq57() {
        let backend = ArmBackend::new();
        let ops = vec![
            WasmOp::LocalGet(0),
            WasmOp::I32Load {
                offset: 0,
                align: 2,
            },
        ];
        let cfg = CompileConfig {
            safety_bounds: SafetyBounds::Mask,
            linear_memory_bytes: 0,
            ..Default::default()
        };
        let err = backend
            .compile_function("ld", &ops, &cfg)
            .expect_err("mask over a zero-byte memory must refuse, not emit an identity mask");
        let msg = format!("{err}");
        assert!(
            msg.contains("ZERO bytes"),
            "refusal must name the zero-byte cause, got: {msg}"
        );
    }

    // ========================================================================
    // ISA feature gate tests — ensure the compiler never emits unsupported
    // instructions for a given target
    // ========================================================================

    #[test]
    fn test_f32_rejected_on_cortex_m3_no_fpu() {
        let backend = ArmBackend::new();
        let ops = vec![WasmOp::F32Const(1.0), WasmOp::F32Const(2.0), WasmOp::F32Add];
        let config = CompileConfig {
            target: TargetSpec::cortex_m3(),
            no_optimize: true,
            ..CompileConfig::default()
        };

        let result = backend.compile_function("fadd", &ops, &config);
        assert!(
            result.is_err(),
            "f32 operations should fail on Cortex-M3 (no FPU)"
        );
    }

    #[test]
    fn test_f32_accepted_on_cortex_m4f() {
        let backend = ArmBackend::new();
        let ops = vec![WasmOp::F32Const(1.0), WasmOp::F32Const(2.0), WasmOp::F32Add];
        let config = CompileConfig {
            target: TargetSpec::cortex_m4f(),
            no_optimize: true,
            ..CompileConfig::default()
        };

        let result = backend.compile_function("fadd", &ops, &config);
        assert!(
            result.is_ok(),
            "f32 operations should succeed on Cortex-M4F, got: {:?}",
            result.unwrap_err()
        );
    }

    #[test]
    fn test_i32_works_on_all_targets() {
        let backend = ArmBackend::new();
        let ops = vec![WasmOp::LocalGet(0), WasmOp::LocalGet(1), WasmOp::I32Add];

        // Cortex-M3 (no FPU)
        let config_m3 = CompileConfig {
            target: TargetSpec::cortex_m3(),
            no_optimize: true,
            ..CompileConfig::default()
        };
        assert!(
            backend.compile_function("add", &ops, &config_m3).is_ok(),
            "i32 ops should work on Cortex-M3"
        );

        // Cortex-M4F (single FPU)
        let config_m4f = CompileConfig {
            target: TargetSpec::cortex_m4f(),
            no_optimize: true,
            ..CompileConfig::default()
        };
        assert!(
            backend.compile_function("add", &ops, &config_m4f).is_ok(),
            "i32 ops should work on Cortex-M4F"
        );

        // Cortex-M7DP (double FPU)
        let config_m7dp = CompileConfig {
            target: TargetSpec::cortex_m7dp(),
            no_optimize: true,
            ..CompileConfig::default()
        };
        assert!(
            backend.compile_function("add", &ops, &config_m7dp).is_ok(),
            "i32 ops should work on Cortex-M7DP"
        );
    }

    #[test]
    fn test_f32_rejected_on_cortex_m4_no_fpu() {
        // Cortex-M4 (without F suffix) has no FPU
        let backend = ArmBackend::new();
        let ops = vec![WasmOp::F32Const(1.5), WasmOp::F32Const(2.5), WasmOp::F32Mul];
        let config = CompileConfig {
            target: TargetSpec::cortex_m4(),
            no_optimize: true,
            ..CompileConfig::default()
        };

        let result = backend.compile_function("fmul", &ops, &config);
        assert!(
            result.is_err(),
            "f32 operations should fail on Cortex-M4 (no FPU)"
        );
    }

    // ========================================================================
    // Issue #120 — f32 ops in the optimized lowering path
    //
    // `OptimizerBridge::wasm_to_ir` has no handlers for f32/f64 ops, so a
    // value-producing float op fell through to `Opcode::Nop`, leaving a
    // downstream consumer with an unmapped vreg and tripping the PR #101
    // defensive panic in `ir_to_arm`. Customer reproducer: `compiler_builtins
    // float::div` and `gale_compute_ipi_mask` in the `falcon-rate-component`
    // module.
    //
    // Fix: `optimize_full` declines float modules with a typed `Err`;
    // `compile_wasm_to_arm` falls back to the non-optimized `select_with_stack`
    // path, which handles f32 via VFP/FPU. These tests use the *default*
    // (optimized) config — `no_optimize` is NOT set — which is the exact
    // configuration that panicked pre-fix.
    // ========================================================================

    /// RQ-65-DECLINE (#1208 / #1213 / #1205): a shape the optimized path
    /// used to lower WRONG must now reach the direct selector through the
    /// fallback, so the DEFAULT configuration is byte-identical to
    /// `--no-optimize` on it — the selector-parity property
    /// (`selector_parity_197_differential.py`), asserted at the unit level
    /// for one instance of each declined class.
    #[test]
    fn test_rq65_declined_shapes_default_equals_no_optimize() {
        let backend = ArmBackend::new();
        let cases: Vec<(&str, Vec<WasmOp>)> = vec![
            (
                "ld8u",
                vec![
                    WasmOp::LocalGet(0),
                    WasmOp::I64Load8U {
                        offset: 0,
                        align: 0,
                    },
                ],
            ),
            (
                "st16",
                vec![
                    WasmOp::LocalGet(0),
                    WasmOp::I64Const(7),
                    WasmOp::I64Store16 {
                        offset: 0,
                        align: 1,
                    },
                ],
            ),
            (
                "sel64",
                vec![
                    WasmOp::I64Const(1),
                    WasmOp::I64Const(0),
                    WasmOp::LocalGet(0),
                    WasmOp::Select,
                    WasmOp::I32WrapI64,
                ],
            ),
            (
                "vif",
                vec![
                    WasmOp::LocalGet(0),
                    WasmOp::LocalGet(1),
                    WasmOp::I32GtS,
                    WasmOp::If,
                    WasmOp::I32Const(7),
                    WasmOp::Else,
                    WasmOp::I32Const(9),
                    WasmOp::End,
                ],
            ),
        ];
        for (name, ops) in cases {
            let default = backend
                .compile_function(name, &ops, &CompileConfig::default())
                .unwrap_or_else(|e| {
                    panic!("{name}: default config must compile via the fallback: {e}")
                });
            let direct = backend
                .compile_function(
                    name,
                    &ops,
                    &CompileConfig {
                        no_optimize: true,
                        ..CompileConfig::default()
                    },
                )
                .unwrap_or_else(|e| panic!("{name}: --no-optimize must compile: {e}"));
            assert_eq!(
                default.code, direct.code,
                "{name}: the declined shape must be the direct selector's bytes"
            );
            assert!(default.code.len() > 2, "{name}: not the #1208 empty body");
        }
    }

    /// Pre-fix: this panicked with "vreg vN has no assigned ARM register and
    /// no spill slot" inside `ir_to_arm`. Post-fix: the optimized path declines
    /// the module and the backend falls back to direct selection, producing a
    /// non-empty f32.div lowering on a Cortex-M4F.
    #[test]
    fn test_issue120_f32_div_compiles_via_optimized_default() {
        let backend = ArmBackend::new();
        let ops = vec![WasmOp::LocalGet(0), WasmOp::LocalGet(1), WasmOp::F32Div];
        let config = CompileConfig {
            target: TargetSpec::cortex_m4f(),
            // no_optimize NOT set — this exercises the optimized path that
            // panicked in issue #120, then the fallback to direct selection.
            // GI-FPU-002: the f32 params must be declared so the direct
            // selector homes them in S0/S1 (AAPCS-VFP) rather than declining.
            current_func_params_f32: vec![true, true],
            ..CompileConfig::default()
        };

        let result = backend.compile_function("fdiv", &ops, &config);
        assert!(
            result.is_ok(),
            "f32.div must compile on Cortex-M4F via the optimized->direct \
             fallback (issue #120), got: {:?}",
            result.as_ref().err()
        );
        assert!(
            !result.unwrap().code.is_empty(),
            "f32.div must produce non-empty machine code"
        );
    }

    /// A spread of f32 ops, all through the optimized (default) config, must
    /// compile via the fallback on an FPU target without panicking.
    #[test]
    fn test_issue120_assorted_f32_ops_compile_via_optimized_default() {
        let backend = ArmBackend::new();
        let config = CompileConfig {
            target: TargetSpec::cortex_m4f(),
            // GI-FPU-002: declare the two f32 params for AAPCS-VFP homing.
            current_func_params_f32: vec![true, true],
            ..CompileConfig::default()
        };

        let cases: Vec<(&str, Vec<WasmOp>)> = vec![
            (
                "fadd",
                vec![WasmOp::LocalGet(0), WasmOp::LocalGet(1), WasmOp::F32Add],
            ),
            (
                "fmul",
                vec![WasmOp::LocalGet(0), WasmOp::LocalGet(1), WasmOp::F32Mul],
            ),
            (
                "fsub",
                vec![WasmOp::LocalGet(0), WasmOp::LocalGet(1), WasmOp::F32Sub],
            ),
        ];

        for (name, ops) in cases {
            let result = backend.compile_function(name, &ops, &config);
            assert!(
                result.is_ok(),
                "{name} must compile via the optimized->direct fallback \
                 (issue #120), got: {:?}",
                result.as_ref().err()
            );
            assert!(
                !result.unwrap().code.is_empty(),
                "{name} must produce non-empty machine code"
            );
        }
    }

    /// The fallback must still honor the ISA feature gate: f32 on a no-FPU
    /// target must fail cleanly (not panic) even on the optimized path.
    #[test]
    fn test_issue120_f32_div_rejected_on_no_fpu_via_optimized() {
        let backend = ArmBackend::new();
        let ops = vec![WasmOp::LocalGet(0), WasmOp::LocalGet(1), WasmOp::F32Div];
        let config = CompileConfig {
            target: TargetSpec::cortex_m3(),
            ..CompileConfig::default()
        };

        let result = backend.compile_function("fdiv", &ops, &config);
        assert!(
            result.is_err(),
            "f32.div must be rejected on Cortex-M3 (no FPU), not panic"
        );
    }

    /// #507: a `br_table` function compiled via the DEFAULT (optimized) config
    /// must produce the SAME bytes as the direct (`no_optimize`) selector —
    /// i.e. the optimized path declined it to direct, lowering the dispatch as a
    /// real cmp-chain instead of silently dropping it (which left all arms in
    /// fall-through). Pre-fix the two outputs differed (the optimized one had no
    /// selector compare). Execution correctness is gated by
    /// `scripts/repro/br_table_507_differential.py`.
    #[test]
    fn test_507_br_table_declines_to_direct() {
        let backend = ArmBackend::new();
        // dispatch(sel): br_table over 3 blocks, each storing a marker to mem[0].
        let ops = vec![
            WasmOp::Block,
            WasmOp::Block,
            WasmOp::Block,
            WasmOp::LocalGet(0),
            WasmOp::BrTable {
                targets: vec![0, 1, 2],
                default: 2,
            },
            WasmOp::End,
            WasmOp::I32Const(0),
            WasmOp::I32Const(10),
            WasmOp::I32Store {
                offset: 0,
                align: 2,
            },
            WasmOp::Return,
            WasmOp::End,
            WasmOp::I32Const(0),
            WasmOp::I32Const(20),
            WasmOp::I32Store {
                offset: 0,
                align: 2,
            },
            WasmOp::Return,
            WasmOp::End,
            WasmOp::I32Const(0),
            WasmOp::I32Const(30),
            WasmOp::I32Store {
                offset: 0,
                align: 2,
            },
        ];
        let opt = CompileConfig {
            target: TargetSpec::cortex_m4(),
            ..CompileConfig::default()
        };
        let direct = CompileConfig {
            target: TargetSpec::cortex_m4(),
            no_optimize: true,
            ..CompileConfig::default()
        };
        let a = backend
            .compile_function("dispatch", &ops, &opt)
            .expect("optimized-default must compile br_table (via decline)");
        let b = backend
            .compile_function("dispatch", &ops, &direct)
            .expect("direct must compile br_table");
        assert_eq!(
            a.code, b.code,
            "#507: optimized-default br_table output must be byte-identical to the \
             direct selector (i.e. declined to direct), not a dropped dispatch"
        );
    }

    /// Issue #94: end-to-end byte-size check for the canonical u64-packed
    /// FFI-return hi32 extract pattern. Compiles two near-identical
    /// functions — one with the optimized shift-by-32, one with a generic
    /// shift-by-7 — and asserts the optimized form is meaningfully smaller.
    #[test]
    fn test_issue94_hi32_extract_is_smaller_than_generic_shift() {
        let backend = ArmBackend::new();
        let config = CompileConfig {
            target: TargetSpec::cortex_m4f(),
            ..CompileConfig::default()
        };

        // #518: the i64 value must NOT come from an i64 PARAM — the optimized
        // path now declines i64-param functions to the direct selector (it homed
        // an i64 param in R4:R5 instead of R0:R1, a silent miscompile this test's
        // byte-size-only assertion masked). The canonical #94 case is a u64 from
        // an FFI return, not a param, anyway. Source the i64 from a sign-extended
        // i32 param (`extend_i32_s`): a runtime, non-constant-foldable i64 that
        // stays on the optimized path, so the shift-by-32 hi-extract peephole is
        // still exercised on CORRECT code.
        // Optimized path: `(i64.extend_i32_s (local.get 0)) >>> 32; wrap_i64`
        let ops_hi32 = vec![
            WasmOp::LocalGet(0), // i32 param in R0
            WasmOp::I64ExtendI32S,
            WasmOp::I64Const(32),
            WasmOp::I64ShrU,
            WasmOp::I32WrapI64,
        ];
        let func_hi32 = backend
            .compile_function("hi32_extract", &ops_hi32, &config)
            .unwrap();

        // Generic path: `... >>> 7; wrap_i64` — same shape, but the shift amount
        // is not a multiple of 32, so it falls through to the runtime shift.
        let ops_generic = vec![
            WasmOp::LocalGet(0),
            WasmOp::I64ExtendI32S,
            WasmOp::I64Const(7),
            WasmOp::I64ShrU,
            WasmOp::I32WrapI64,
        ];
        let func_generic = backend
            .compile_function("generic_shr", &ops_generic, &config)
            .unwrap();

        let bytes_hi32 = func_hi32.code.len();
        let bytes_generic = func_generic.code.len();
        println!(
            "\n[issue #94] hi32 extract: {} bytes (vs generic shift: {} bytes; saved {})",
            bytes_hi32,
            bytes_generic,
            bytes_generic.saturating_sub(bytes_hi32)
        );
        let hex: String = func_hi32
            .code
            .iter()
            .map(|b| format!("{:02x}", b))
            .collect::<Vec<_>>()
            .join(" ");
        println!("[issue #94] hi32 bytes: {}", hex);
        // We expect the optimized form to be at least 30 bytes smaller than
        // the generic 64-bit shift sequence. (Empirically: 14 vs 50 bytes.)
        assert!(
            bytes_hi32 + 30 <= bytes_generic,
            "issue #94: hi32 extract = {} bytes, generic shift = {} bytes; \
             expected optimized form to be at least 30 bytes smaller",
            bytes_hi32,
            bytes_generic,
        );
    }
}