synth_core/

wasm_decoder.rs

//! WASM Binary Decoder - Converts wasmparser operators to WasmOp sequences
//!
//! This module bridges the gap between parsed WASM binaries and any backend.
//! It extracts function bodies and converts wasmparser operators to our internal WasmOp format.

use crate::wasm_op::WasmOp;
use anyhow::{Context, Result};
use std::collections::HashMap;
use wasmparser::{ExternalKind, Parser, Payload};

/// Kind of a WASM import
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ImportKind {
    /// Imported function with type index
    Function(u32),
    /// Imported memory
    Memory,
    /// Imported table
    Table,
    /// Imported global
    Global,
}

/// A WASM import entry with full metadata
#[derive(Debug, Clone)]
pub struct ImportEntry {
    /// Module name (e.g., "wasi:cli/stdout" or "env")
    pub module: String,
    /// Field name (e.g., "write" or "memory")
    pub name: String,
    /// Import kind and associated data
    pub kind: ImportKind,
    /// Index of this import within its kind (e.g., function import index)
    pub index: u32,
}

/// WASM linear memory specification
#[derive(Debug, Clone)]
pub struct WasmMemory {
    /// Memory index
    pub index: u32,
    /// Initial size in pages (64KB each)
    pub initial_pages: u32,
    /// Maximum size in pages (if specified)
    pub max_pages: Option<u32>,
    /// Whether memory is shared (requires threads proposal)
    pub shared: bool,
}

/// A WASM global's declaration — its initial value and mutability (#237).
/// Needed so the native-pointer ABI can recognize a global whose initializer is
/// a linear-memory address (e.g. `$__stack_pointer = 65536`) and make it
/// `__synth_wasm_data`-relative, rather than reading it from an R9 globals table
/// the self-contained drop-in object can't rely on.
#[derive(Debug, Clone)]
pub struct WasmGlobal {
    /// Global index (defined globals; imported globals are not counted here).
    pub index: u32,
    /// The `i32.const` initializer value (other init exprs decode to `None`).
    pub init_i32: Option<i32>,
    /// Whether the global is mutable.
    pub mutable: bool,
}

impl WasmMemory {
    /// Get initial size in bytes
    pub fn initial_bytes(&self) -> u32 {
        self.initial_pages * 65536
    }

    /// Get maximum size in bytes (or initial if not specified)
    pub fn max_bytes(&self) -> u32 {
        self.max_pages.unwrap_or(self.initial_pages) * 65536
    }
}

/// Decoded WASM module with functions and memory
#[derive(Debug, Clone)]
pub struct DecodedModule {
    /// Decoded functions
    pub functions: Vec<FunctionOps>,
    /// Linear memories
    pub memories: Vec<WasmMemory>,
    /// Data segments (offset, data) for memory initialization
    pub data_segments: Vec<(u32, Vec<u8>)>,
    /// Import entries (module name, field name, kind)
    pub imports: Vec<ImportEntry>,
    /// Number of imported functions (for distinguishing import calls from local calls)
    pub num_imported_funcs: u32,
    /// AAPCS integer-argument count per function, indexed by the *full* WASM
    /// function index (imported functions first, then locally-defined ones).
    /// Used by the backend to marshal call arguments into R0–R3 (issue #195).
    /// Counts every parameter as one slot (i64/f64 over-counted — see the
    /// backend's `set_func_arg_counts` scope note).
    pub func_arg_counts: Vec<u32>,
    /// AAPCS integer-argument count per *function type*, indexed by type index.
    /// Used by `call_indirect`, whose callee arg count comes from the static
    /// type index (issue #195).
    pub type_arg_counts: Vec<u32>,
    /// #311: whether each *function* (full index, imports first) returns i64 —
    /// the call lowering must tag the result as a register PAIR (r0:r1) or the
    /// hi half is invisible to liveness and the next constant clobbers it.
    pub func_ret_i64: Vec<bool>,
    /// #311: whether each *function type* returns i64 (for `call_indirect`).
    pub type_ret_i64: Vec<bool>,
    /// #359: declared parameter widths per *function* (full index, imports
    /// first): `func_params_i64[f][k]` is true when param `k` is i64/f64. The
    /// AAPCS stack-argument path needs the declared widths — op-stream inference
    /// can't see an unused i64 param that still shifts the incoming-stack layout.
    pub func_params_i64: Vec<Vec<bool>>,
    /// Defined globals with their initializers (#237). Empty if the module has
    /// no global section. Used by the native-pointer ABI to make a global whose
    /// initializer is a linear-memory address (e.g. `$__stack_pointer`)
    /// self-contained rather than table-relative.
    pub globals: Vec<WasmGlobal>,
    /// Function indices that populate any table via an element segment (#275).
    /// These are the possible `call_indirect` targets — a function reached only
    /// through the table is invisible to direct-`call` reachability, so the
    /// whole-graph closure must treat every table entry as reachable once any
    /// reachable function performs a `call_indirect`. Empty for modules with no
    /// element section (every leaf/direct-call module), keeping output identical.
    pub elem_func_indices: Vec<u32>,
    /// VCR-PERF-002 Phase 1 (#494): proven invariants from loom's `wsc.facts`
    /// custom section, keyed by `(function index, value id)` — see
    /// `docs/design/wsc-facts-encoding.md` (schema v1) and
    /// [`crate::wsc_facts::parse_wsc_facts`]. FAIL-SAFE by contract (loom#231
    /// Q4): a missing/unparseable section or unknown version yields the empty
    /// vec, unknown fact kinds are skipped — never a decode error. Phase 1 is
    /// ingestion only: NO codegen path consumes these yet, so emitted bytes
    /// are unchanged whether or not a module carries the section.
    pub wsc_facts: Vec<crate::wsc_facts::WscFact>,
}

/// Decode a WASM binary and extract functions, memory, and data segments
pub fn decode_wasm_module(wasm_bytes: &[u8]) -> Result<DecodedModule> {
    let mut functions = Vec::new();
    let mut memories = Vec::new();
    let mut data_segments = Vec::new();
    let mut globals: Vec<WasmGlobal> = Vec::new();
    let mut imports = Vec::new();
    let mut func_index = 0u32;
    let mut num_imported_funcs = 0u32;
    let mut export_names: HashMap<u32, String> = HashMap::new();
    // #195: per-type AAPCS arg count (indexed by type index) and per-function
    // arg count (indexed by full function index: imports first, then locals).
    let mut type_arg_counts: Vec<u32> = Vec::new();
    let mut func_arg_counts: Vec<u32> = Vec::new();
    let mut type_ret_i64: Vec<bool> = Vec::new();
    let mut func_ret_i64: Vec<bool> = Vec::new();
    // #359: declared param widths per type / per function (full index).
    let mut type_params_i64: Vec<Vec<bool>> = Vec::new();
    let mut func_params_i64: Vec<Vec<bool>> = Vec::new();
    // #509: (param_count, result_count) per type index, for FuncType blocktypes.
    let mut type_block_arity: Vec<(u8, u8)> = Vec::new();
    let mut elem_func_indices: Vec<u32> = Vec::new();
    // #394 Tier-1.x: function index → developer-facing name from the wasm
    // `name` custom section (function-names subsection). Applied to
    // `FunctionOps.debug_name` after the parse loop — the custom section
    // conventionally trails the code section, so the entries are not yet
    // available when each `CodeSectionEntry` is decoded.
    let mut name_section_names: HashMap<u32, String> = HashMap::new();
    // VCR-PERF-002 Phase 1 (#494): facts from loom's `wsc.facts` custom
    // section. `None` until (and unless) the first such section is seen —
    // duplicates are ignored (one prover, one section; encoding doc rule).
    let mut wsc_facts: Option<Vec<crate::wsc_facts::WscFact>> = None;

    for payload in Parser::new(0).parse_all(wasm_bytes) {
        let payload = payload.context("Failed to parse WASM payload")?;

        match payload {
            Payload::TypeSection(reader) => {
                // Record the parameter count of each function type so calls can
                // marshal the right number of arguments (issue #195).
                for rec_group in reader {
                    let rec_group = rec_group.context("Failed to parse type")?;
                    for sub_ty in rec_group.types() {
                        // #509: blocktype arity per type index (saturated u8 —
                        // >255 params/results is far beyond anything the
                        // selector supports anyway, and the selector declines
                        // rather than trusting a saturated count).
                        type_block_arity.push(match &sub_ty.composite_type.inner {
                            wasmparser::CompositeInnerType::Func(f) => (
                                u8::try_from(f.params().len()).unwrap_or(u8::MAX),
                                u8::try_from(f.results().len()).unwrap_or(u8::MAX),
                            ),
                            _ => (u8::MAX, u8::MAX),
                        });
                        let (count, ret_i64, params_i64) = match &sub_ty.composite_type.inner {
                            wasmparser::CompositeInnerType::Func(func_ty) => (
                                func_ty.params().len() as u32,
                                func_ty
                                    .results()
                                    .first()
                                    .is_some_and(|t| *t == wasmparser::ValType::I64),
                                // #359: i64/f64 params occupy 8 bytes / a register
                                // pair under AAPCS. f32/f64 are not in scope for the
                                // stack-arg path (refused), but mark both 64-bit
                                // float and i64 so the guard catches them.
                                func_ty
                                    .params()
                                    .iter()
                                    .map(|t| {
                                        matches!(
                                            t,
                                            wasmparser::ValType::I64 | wasmparser::ValType::F64
                                        )
                                    })
                                    .collect::<Vec<bool>>(),
                            ),
                            _ => (0, false, Vec::new()),
                        };
                        type_arg_counts.push(count);
                        type_ret_i64.push(ret_i64);
                        type_params_i64.push(params_i64);
                    }
                }
            }
            Payload::ImportSection(reader) => {
                // wasmparser 0.221+ groups imports (the "compact imports"
                // proposal): the section reader yields `Imports` groups, each of
                // which may expand to several `Import`s. `into_imports()`
                // flattens groups back to individual `Import`s (preserving the
                // module/name/ty fields), keeping the per-import loop intact.
                for import in reader.into_imports() {
                    let import = import.context("Failed to parse import")?;
                    let (kind, idx) = match import.ty {
                        wasmparser::TypeRef::Func(type_idx) => {
                            let idx = num_imported_funcs;
                            num_imported_funcs += 1;
                            // Record the imported function's arg count at its
                            // full function index (imports come first).
                            func_arg_counts
                                .push(type_arg_counts.get(type_idx as usize).copied().unwrap_or(0));
                            func_ret_i64.push(
                                type_ret_i64
                                    .get(type_idx as usize)
                                    .copied()
                                    .unwrap_or(false),
                            );
                            func_params_i64.push(
                                type_params_i64
                                    .get(type_idx as usize)
                                    .cloned()
                                    .unwrap_or_default(),
                            );
                            (ImportKind::Function(type_idx), idx)
                        }
                        wasmparser::TypeRef::Memory(_) => (ImportKind::Memory, 0),
                        wasmparser::TypeRef::Table(_) => (ImportKind::Table, 0),
                        wasmparser::TypeRef::Global(_) => (ImportKind::Global, 0),
                        _ => continue,
                    };
                    imports.push(ImportEntry {
                        module: import.module.to_string(),
                        name: import.name.to_string(),
                        kind,
                        index: idx,
                    });
                }
            }
            Payload::FunctionSection(reader) => {
                // Each entry gives the type index of a locally-defined function,
                // in order. Their full function indices follow the imports, so
                // appending to `func_arg_counts` keeps it indexed by full index
                // (issue #195).
                for ty in reader {
                    let type_idx = ty.context("Failed to parse function type index")?;
                    func_arg_counts
                        .push(type_arg_counts.get(type_idx as usize).copied().unwrap_or(0));
                    func_ret_i64.push(
                        type_ret_i64
                            .get(type_idx as usize)
                            .copied()
                            .unwrap_or(false),
                    );
                    func_params_i64.push(
                        type_params_i64
                            .get(type_idx as usize)
                            .cloned()
                            .unwrap_or_default(),
                    );
                }
            }
            Payload::MemorySection(reader) => {
                for (idx, memory) in reader.into_iter().enumerate() {
                    let mem = memory.context("Failed to parse memory")?;
                    memories.push(WasmMemory {
                        index: idx as u32,
                        initial_pages: mem.initial as u32,
                        max_pages: mem.maximum.map(|m| m as u32),
                        shared: mem.shared,
                    });
                }
            }
            Payload::GlobalSection(reader) => {
                // #237: capture each defined global's i32 initializer + mutability.
                // The init is a const expr; we only decode a leading `i32.const`
                // (the shape `$__stack_pointer`/data-layout globals use). Anything
                // else (global.get, f32/f64, etc.) records `init_i32: None` and is
                // left to the table-relative path.
                for (idx, global) in reader.into_iter().enumerate() {
                    let global = global.context("Failed to parse global")?;
                    let mut init_i32 = None;
                    let mut ops = global.init_expr.get_operators_reader();
                    if let Ok(wasmparser::Operator::I32Const { value }) = ops.read() {
                        init_i32 = Some(value);
                    }
                    globals.push(WasmGlobal {
                        index: idx as u32,
                        init_i32,
                        mutable: global.ty.mutable,
                    });
                }
            }
            Payload::DataSection(reader) => {
                for data in reader {
                    let data = data.context("Failed to parse data segment")?;
                    if let wasmparser::DataKind::Active {
                        memory_index: 0,
                        offset_expr,
                    } = data.kind
                    {
                        let mut ops = offset_expr.get_operators_reader();
                        if let Ok(wasmparser::Operator::I32Const { value }) = ops.read() {
                            data_segments.push((value as u32, data.data.to_vec()));
                        }
                    }
                }
            }
            Payload::ElementSection(reader) => {
                // #275: collect every function index that initializes a table.
                // These are the `call_indirect` targets the direct-call closure
                // cannot see; `reachable_from_exports` unions them in when a
                // reachable function does a `call_indirect`. Both element forms
                // are handled: a flat function-index list, and the const-expr
                // form whose `ref.func` entries name the functions.
                for elem in reader {
                    let elem = elem.context("Failed to parse element segment")?;
                    match elem.items {
                        wasmparser::ElementItems::Functions(funcs) => {
                            for f in funcs {
                                elem_func_indices
                                    .push(f.context("Failed to parse element func index")?);
                            }
                        }
                        wasmparser::ElementItems::Expressions(_, exprs) => {
                            for expr in exprs {
                                let expr = expr.context("Failed to parse element expr")?;
                                for op in expr.get_operators_reader() {
                                    if let wasmparser::Operator::RefFunc { function_index } =
                                        op.context("Failed to parse element op")?
                                    {
                                        elem_func_indices.push(function_index);
                                    }
                                }
                            }
                        }
                    }
                }
            }
            Payload::ExportSection(exports) => {
                for export in exports {
                    let export = export.context("Failed to parse export")?;
                    if export.kind == ExternalKind::Func {
                        export_names.insert(export.index, export.name.to_string());
                    }
                }
            }
            Payload::CodeSectionEntry(body) => {
                let (ops, op_offsets, block_arity, unsupported) =
                    decode_function_body(&body, &type_block_arity)?;
                let actual_index = num_imported_funcs + func_index;
                let export_name = export_names.get(&actual_index).cloned();

                functions.push(FunctionOps {
                    index: actual_index,
                    export_name,
                    debug_name: None, // filled from the `name` section after the loop
                    ops,
                    op_offsets,
                    unsupported,
                    block_arity,
                });
                func_index += 1;
            }
            Payload::CustomSection(c) => {
                // #394 Tier-1.x: the wasm `name` custom section.
                if let wasmparser::KnownCustom::Name(reader) = c.as_known() {
                    parse_name_section_func_names(reader, &mut name_section_names);
                }
                // VCR-PERF-002 Phase 1 (#494): loom's `wsc.facts` section.
                // `parse_wsc_facts` is TOTAL (fail-safe skew, loom#231 Q4):
                // any malformed payload decodes to the empty fact list WITH a
                // stderr diagnostic, never an error — facts are optional
                // accelerators and must not be able to change a compilation
                // outcome. First section wins.
                if c.name() == crate::wsc_facts::WSC_FACTS_SECTION_NAME && wsc_facts.is_none() {
                    let parsed = crate::wsc_facts::parse_wsc_facts(c.data());
                    if let Some(reason) = &parsed.section_ignored {
                        eprintln!(
                            "warning: ignoring unparseable `wsc.facts` custom section \
                             ({reason}) — facts are optional accelerators, compilation \
                             is unaffected (#494 fail-safe skew rule)"
                        );
                    } else if parsed.records_skipped > 0 {
                        eprintln!(
                            "warning: skipped {} unknown/undecodable `wsc.facts` \
                             record(s) (likely a newer loom emitter); {} known fact(s) \
                             kept, compilation is unaffected (#494 fail-safe skew rule)",
                            parsed.records_skipped,
                            parsed.facts.len()
                        );
                    }
                    wsc_facts = Some(parsed.facts);
                }
            }
            _ => {}
        }
    }

    apply_name_section(&mut functions, &name_section_names);

    Ok(DecodedModule {
        functions,
        memories,
        data_segments,
        imports,
        num_imported_funcs,
        func_arg_counts,
        type_arg_counts,
        func_ret_i64,
        type_ret_i64,
        func_params_i64,
        globals,
        elem_func_indices,
        wsc_facts: wsc_facts.unwrap_or_default(),
    })
}

/// Parse the function-names subsection of a wasm `name` custom section into
/// `out` (function index → developer-facing name, e.g.
/// `core::panicking::panic_fmt::h...`). Best-effort by design: the section is
/// DEBUG METADATA only, so a malformed entry is skipped rather than failing the
/// compile — no codegen path depends on it (#394 Tier-1.x).
fn parse_name_section_func_names(
    reader: wasmparser::NameSectionReader<'_>,
    out: &mut HashMap<u32, String>,
) {
    for subsection in reader.into_iter().flatten() {
        if let wasmparser::Name::Function(map) = subsection {
            for naming in map.into_iter().flatten() {
                out.insert(naming.index, naming.name.to_string());
            }
        }
    }
}

/// Fill each function's `debug_name` from the `name`-section map (keyed by the
/// FULL function index, imports first — the same index space `FunctionOps.index`
/// uses). A function without an entry keeps `None` (⇒ `func_N` downstream).
fn apply_name_section(functions: &mut [FunctionOps], names: &HashMap<u32, String>) {
    if names.is_empty() {
        return;
    }
    for f in functions {
        f.debug_name = names.get(&f.index).cloned();
    }
}

/// Decode a WASM binary and extract all function bodies as WasmOp sequences
pub fn decode_wasm_functions(wasm_bytes: &[u8]) -> Result<Vec<FunctionOps>> {
    let mut functions = Vec::new();
    let mut func_index = 0u32;
    let mut num_imported_funcs = 0u32;
    let mut export_names: HashMap<u32, String> = HashMap::new();
    let mut name_section_names: HashMap<u32, String> = HashMap::new();
    // #509: (param_count, result_count) per type index, for FuncType blocktypes.
    let mut type_block_arity: Vec<(u8, u8)> = Vec::new();

    for payload in Parser::new(0).parse_all(wasm_bytes) {
        let payload = payload.context("Failed to parse WASM payload")?;

        match payload {
            Payload::TypeSection(reader) => {
                // #509: the blocktype-arity side-table needs the type section
                // for `BlockType::FuncType(i)` lookups (the wasm binary format
                // places types before code, so the table is complete before any
                // `CodeSectionEntry` is decoded).
                for rec_group in reader {
                    let rec_group = rec_group.context("Failed to parse type")?;
                    for sub_ty in rec_group.types() {
                        type_block_arity.push(match &sub_ty.composite_type.inner {
                            wasmparser::CompositeInnerType::Func(f) => (
                                u8::try_from(f.params().len()).unwrap_or(u8::MAX),
                                u8::try_from(f.results().len()).unwrap_or(u8::MAX),
                            ),
                            _ => (u8::MAX, u8::MAX),
                        });
                    }
                }
            }
            Payload::ImportSection(imports) => {
                // wasmparser 0.221+ compact-imports grouping — flatten groups
                // to individual imports (see the ImportSection handler above).
                for import in imports.into_imports() {
                    let import = import.context("Failed to parse import")?;
                    if matches!(import.ty, wasmparser::TypeRef::Func(_)) {
                        num_imported_funcs += 1;
                    }
                }
            }
            Payload::ExportSection(exports) => {
                for export in exports {
                    let export = export.context("Failed to parse export")?;
                    if export.kind == ExternalKind::Func {
                        export_names.insert(export.index, export.name.to_string());
                    }
                }
            }
            Payload::CodeSectionEntry(body) => {
                let (ops, op_offsets, block_arity, unsupported) =
                    decode_function_body(&body, &type_block_arity)?;
                let actual_index = num_imported_funcs + func_index;
                let export_name = export_names.get(&actual_index).cloned();

                functions.push(FunctionOps {
                    index: actual_index,
                    export_name,
                    debug_name: None, // filled from the `name` section after the loop
                    ops,
                    op_offsets,
                    unsupported,
                    block_arity,
                });
                func_index += 1;
            }
            Payload::CustomSection(c) => {
                // #394 Tier-1.x: the wasm `name` custom section.
                if let wasmparser::KnownCustom::Name(reader) = c.as_known() {
                    parse_name_section_func_names(reader, &mut name_section_names);
                }
            }
            _ => {}
        }
    }

    apply_name_section(&mut functions, &name_section_names);

    Ok(functions)
}

/// Decoded function with its WasmOp sequence
#[derive(Debug, Clone)]
pub struct FunctionOps {
    /// Function index in the module (includes imported functions)
    pub index: u32,
    /// Export name if this function is exported
    pub export_name: Option<String>,
    /// #394 Tier-1.x: the function's developer-facing name from the wasm `name`
    /// custom section (function-names subsection), e.g.
    /// `core::panicking::panic_fmt::h6651313c3e2c6c2f` — present for INTERNAL
    /// (non-exported) functions too, unlike `export_name`. DEBUG METADATA only:
    /// consumed by the `--debug-line` `DW_TAG_subprogram` emit (name priority:
    /// name-section > export name > `func_N`); no codegen or symbol-table path
    /// reads it, so emitted `.text`/`.symtab` are unchanged (frozen-safe).
    /// `None` when the module has no `name` section or no entry for this index.
    pub debug_name: Option<String>,
    /// The WASM operations in this function body
    pub ops: Vec<WasmOp>,
    /// VCR-DBG-001 step 1 (#394): module-relative wasm byte offset of each op in
    /// `ops` (same index → same op). This is the address space DWARF-for-wasm
    /// `.debug_line` keys on, so it is the bridge from synth's op-index
    /// `source_line` to the input wasm's DWARF (wasm-offset → source). PURELY
    /// ADDITIVE metadata: no codegen path reads it, so emitted `.text` is
    /// unchanged and the frozen fixtures stay bit-identical. Empty until consumed
    /// by the DWARF emitter (Tier 1).
    pub op_offsets: Vec<u32>,
    /// `Some(reason)` when the body contained a value-affecting operator the
    /// decoder cannot lower (e.g. scalar f32/f64 — #369, bulk-memory
    /// memory.copy/fill). Such an op would otherwise be silently *dropped*
    /// (`convert_operator` → `None`), leaving the operand stack wrong and the
    /// function a silent miscompile. The compile path LOUD-SKIPS a flagged
    /// function (diagnostic + symbol absent → link error names it) instead —
    /// the #180/#185 "unsupported op must Err, never silently continue"
    /// contract. `None` once every op decoded or was intentionally ignorable
    /// (Nop/Unreachable).
    pub unsupported: Option<String>,
    /// #509: blocktype arity side-table — `(param_count, result_count)` of the
    /// k-th `Block`/`Loop`/`If` op in `ops`, in order of appearance.
    /// ORDINAL-keyed, not op-index-keyed, on purpose: the backend may rewrite
    /// the op stream before selection (e.g. the #539 `i32.const 0; memory.grow`
    /// → `memory.size` fold), which shifts op indices but never adds/removes
    /// control ops, so the ordinal stays aligned. `BlockType::Empty → (0,0)`,
    /// `ValType → (0,1)`, `FuncType(i) →` counts from the type section
    /// (saturated to u8; an unresolvable type index records `(u8::MAX,
    /// u8::MAX)` so the selector declines loudly instead of miscompiling).
    /// This is what lets the direct selector land a value carried by
    /// `br`/`br_if`/`br_table` in the target block's designated result
    /// register instead of dropping it — `WasmOp::Block/Loop/If` stay bare
    /// unit variants (zero ripple through the backends' match sites), and an
    /// empty table (hand-built op streams in unit tests) keeps the legacy
    /// void-block lowering.
    pub block_arity: Vec<(u8, u8)>,
}

/// #509: `(param_count, result_count)` of a wasm blocktype, for the
/// [`FunctionOps::block_arity`] side-table. `type_block_arity` is the type
/// section's per-type-index counts (needed for the `FuncType` form); a missing
/// entry saturates to `(u8::MAX, u8::MAX)` so downstream declines loudly.
fn blocktype_arity(bt: &wasmparser::BlockType, type_block_arity: &[(u8, u8)]) -> (u8, u8) {
    match bt {
        wasmparser::BlockType::Empty => (0, 0),
        wasmparser::BlockType::Type(_) => (0, 1),
        wasmparser::BlockType::FuncType(i) => type_block_arity
            .get(*i as usize)
            .copied()
            .unwrap_or((u8::MAX, u8::MAX)),
    }
}

/// The per-function payload [`decode_function_body`] extracts: `(ops,
/// op_offsets, block_arity, unsupported)` — see the matching
/// [`FunctionOps`] fields for each component's contract.
type DecodedBody = (Vec<WasmOp>, Vec<u32>, Vec<(u8, u8)>, Option<String>);

/// Decode a single function body to WasmOp sequence.
///
/// Returns the ops plus `Some(reason)` if any operator was a value-affecting
/// op the decoder cannot lower (so the function must be loud-skipped, #369 —
/// not silently miscompiled by dropping the op).
fn decode_function_body(
    body: &wasmparser::FunctionBody,
    type_block_arity: &[(u8, u8)],
) -> Result<DecodedBody> {
    let mut ops = Vec::new();
    // VCR-DBG-001 step 1: parallel to `ops` — the module-relative wasm byte
    // offset of each emitted op (the DWARF-for-wasm address space). Captured via
    // the offset-aware reader; pushed only when an op is pushed, so indices stay
    // aligned with `ops`. Additive metadata, no codegen consumer ⇒ frozen-safe.
    let mut op_offsets = Vec::new();
    // #509: ordinal blocktype-arity side-table — one entry per Block/Loop/If in
    // `ops` order (see `FunctionOps::block_arity`).
    let mut block_arity: Vec<(u8, u8)> = Vec::new();
    let mut unsupported: Option<String> = None;

    let ops_reader = body.get_operators_reader()?;
    for item in ops_reader.into_iter_with_offsets() {
        let (op, offset) = item.context("Failed to read operator")?;

        if let Some(wasm_op) = convert_operator(&op) {
            // #509: capture the blocktype arity BEFORE the enum flattens it away
            // (`WasmOp::Block/Loop/If` are unit variants by design).
            if let wasmparser::Operator::Block { blockty }
            | wasmparser::Operator::Loop { blockty }
            | wasmparser::Operator::If { blockty } = &op
            {
                block_arity.push(blocktype_arity(blockty, type_block_arity));
            }
            ops.push(wasm_op);
            op_offsets.push(offset as u32);
        } else if unsupported.is_none() && !is_intentionally_ignored(&op) {
            // The op was DROPPED by `convert_operator` (`_ => None`) and is not
            // an intentional no-op (Nop/Unreachable) — record it so the
            // function is loud-skipped rather than silently miscompiled (#369).
            unsupported = Some(format!("{op:?}"));
        }
    }

    Ok((ops, op_offsets, block_arity, unsupported))
}

/// Operators that `convert_operator` returns `None` for *on purpose* — they
/// carry no value-affecting semantics for our backend, so dropping them is
/// correct (NOT a silent miscompile). Everything else that decodes to `None`
/// is an unsupported op that must loud-skip its function (#369).
fn is_intentionally_ignored(op: &wasmparser::Operator) -> bool {
    use wasmparser::Operator::*;
    matches!(op, Nop | Unreachable)
}

/// Convert a wasmparser Operator to our WasmOp enum
fn convert_operator(op: &wasmparser::Operator) -> Option<WasmOp> {
    use wasmparser::Operator::*;

    match op {
        // Constants
        I32Const { value } => Some(WasmOp::I32Const(*value)),

        // i32 Arithmetic
        I32Add => Some(WasmOp::I32Add),
        I32Sub => Some(WasmOp::I32Sub),
        I32Mul => Some(WasmOp::I32Mul),
        I32DivS => Some(WasmOp::I32DivS),
        I32DivU => Some(WasmOp::I32DivU),
        I32RemS => Some(WasmOp::I32RemS),
        I32RemU => Some(WasmOp::I32RemU),

        // i64 Constants
        I64Const { value } => Some(WasmOp::I64Const(*value)),

        // i64 Arithmetic
        I64Add => Some(WasmOp::I64Add),
        I64Sub => Some(WasmOp::I64Sub),
        I64Mul => Some(WasmOp::I64Mul),
        I64DivS => Some(WasmOp::I64DivS),
        I64DivU => Some(WasmOp::I64DivU),
        I64RemS => Some(WasmOp::I64RemS),
        I64RemU => Some(WasmOp::I64RemU),

        // i64 Bitwise
        I64And => Some(WasmOp::I64And),
        I64Or => Some(WasmOp::I64Or),
        I64Xor => Some(WasmOp::I64Xor),
        I64Shl => Some(WasmOp::I64Shl),
        I64ShrS => Some(WasmOp::I64ShrS),
        I64ShrU => Some(WasmOp::I64ShrU),
        I64Rotl => Some(WasmOp::I64Rotl),
        I64Rotr => Some(WasmOp::I64Rotr),
        I64Clz => Some(WasmOp::I64Clz),
        I64Ctz => Some(WasmOp::I64Ctz),
        I64Popcnt => Some(WasmOp::I64Popcnt),
        I64Extend8S => Some(WasmOp::I64Extend8S),
        I64Extend16S => Some(WasmOp::I64Extend16S),
        I64Extend32S => Some(WasmOp::I64Extend32S),
        // i32<->i64 width conversions. Previously UNMAPPED → silently dropped,
        // which left an i32 value as a 64-bit operand with a garbage high half
        // (harmless when a following `i64.shl 32` discards it, but a latent
        // miscompile for extend-then-arithmetic, and it breaks width-correct
        // register allocation). (#204)
        I64ExtendI32U => Some(WasmOp::I64ExtendI32U),
        I64ExtendI32S => Some(WasmOp::I64ExtendI32S),
        I32WrapI64 => Some(WasmOp::I32WrapI64),

        // i64 Comparison
        I64Eqz => Some(WasmOp::I64Eqz),
        I64Eq => Some(WasmOp::I64Eq),
        I64Ne => Some(WasmOp::I64Ne),
        I64LtS => Some(WasmOp::I64LtS),
        I64LtU => Some(WasmOp::I64LtU),
        I64LeS => Some(WasmOp::I64LeS),
        I64LeU => Some(WasmOp::I64LeU),
        I64GtS => Some(WasmOp::I64GtS),
        I64GtU => Some(WasmOp::I64GtU),
        I64GeS => Some(WasmOp::I64GeS),
        I64GeU => Some(WasmOp::I64GeU),

        // Bitwise
        I32And => Some(WasmOp::I32And),
        I32Or => Some(WasmOp::I32Or),
        I32Xor => Some(WasmOp::I32Xor),
        I32Shl => Some(WasmOp::I32Shl),
        I32ShrS => Some(WasmOp::I32ShrS),
        I32ShrU => Some(WasmOp::I32ShrU),
        I32Rotl => Some(WasmOp::I32Rotl),
        I32Rotr => Some(WasmOp::I32Rotr),
        I32Clz => Some(WasmOp::I32Clz),
        I32Ctz => Some(WasmOp::I32Ctz),
        I32Popcnt => Some(WasmOp::I32Popcnt),
        I32Extend8S => Some(WasmOp::I32Extend8S),
        I32Extend16S => Some(WasmOp::I32Extend16S),

        // Comparison
        I32Eqz => Some(WasmOp::I32Eqz),
        I32Eq => Some(WasmOp::I32Eq),
        I32Ne => Some(WasmOp::I32Ne),
        I32LtS => Some(WasmOp::I32LtS),
        I32LtU => Some(WasmOp::I32LtU),
        I32LeS => Some(WasmOp::I32LeS),
        I32LeU => Some(WasmOp::I32LeU),
        I32GtS => Some(WasmOp::I32GtS),
        I32GtU => Some(WasmOp::I32GtU),
        I32GeS => Some(WasmOp::I32GeS),
        I32GeU => Some(WasmOp::I32GeU),

        // Memory
        I32Load { memarg } => Some(WasmOp::I32Load {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),
        I32Store { memarg } => Some(WasmOp::I32Store {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),
        // #372: full-width i64 load/store. The selector already lowers these to
        // a lo/hi i32 register-pair access (`generate_i64_load/store_with_bounds_check`,
        // reusing the #171 pair regalloc) — only the decoder arm was missing, so
        // `i64.load`/`i64.store` fell through `_ => None` and (since v0.11.46)
        // loud-skipped their function. The narrow forms (I64Load8.. / I64Store32)
        // were already decoded below.
        I64Load { memarg } => Some(WasmOp::I64Load {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),
        I64Store { memarg } => Some(WasmOp::I64Store {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),

        // Sub-word loads (i32)
        I32Load8S { memarg } => Some(WasmOp::I32Load8S {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),
        I32Load8U { memarg } => Some(WasmOp::I32Load8U {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),
        I32Load16S { memarg } => Some(WasmOp::I32Load16S {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),
        I32Load16U { memarg } => Some(WasmOp::I32Load16U {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),

        // Sub-word stores (i32)
        I32Store8 { memarg } => Some(WasmOp::I32Store8 {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),
        I32Store16 { memarg } => Some(WasmOp::I32Store16 {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),

        // Local/Global
        LocalGet { local_index } => Some(WasmOp::LocalGet(*local_index)),
        LocalSet { local_index } => Some(WasmOp::LocalSet(*local_index)),
        LocalTee { local_index } => Some(WasmOp::LocalTee(*local_index)),
        GlobalGet { global_index } => Some(WasmOp::GlobalGet(*global_index)),
        GlobalSet { global_index } => Some(WasmOp::GlobalSet(*global_index)),

        // Control flow
        Block { .. } => Some(WasmOp::Block),
        Loop { .. } => Some(WasmOp::Loop),
        Br { relative_depth } => Some(WasmOp::Br(*relative_depth)),
        BrIf { relative_depth } => Some(WasmOp::BrIf(*relative_depth)),
        // br_table: indexed multi-way branch. Previously UNMAPPED → silently
        // dropped, so the selector never emitted the index dispatch and control
        // fell straight into the first table arm — every br_table behaved as if
        // it always took target 0 (gale's binary-sem WAKE path never fired). The
        // jump-table relative depths + default depth are preserved in order.
        BrTable { targets } => {
            let default = targets.default();
            let tgts: Vec<u32> = targets.targets().filter_map(Result::ok).collect();
            Some(WasmOp::BrTable {
                targets: tgts,
                default,
            })
        }
        Return => Some(WasmOp::Return),
        Call { function_index } => Some(WasmOp::Call(*function_index)),
        CallIndirect {
            type_index,
            table_index,
            ..
        } => Some(WasmOp::CallIndirect {
            type_index: *type_index,
            table_index: *table_index,
        }),

        // End is needed for control flow pattern matching
        End => Some(WasmOp::End),

        // Nop/Unreachable - skip these
        Nop | Unreachable => None,

        // Drop is needed for br_if pattern matching
        Drop => Some(WasmOp::Drop),

        // Select
        Select => Some(WasmOp::Select),

        // If/Else - simplified handling
        If { .. } => Some(WasmOp::If),
        Else => Some(WasmOp::Else),

        // i64 sub-word loads
        I64Load8S { memarg } => Some(WasmOp::I64Load8S {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),
        I64Load8U { memarg } => Some(WasmOp::I64Load8U {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),
        I64Load16S { memarg } => Some(WasmOp::I64Load16S {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),
        I64Load16U { memarg } => Some(WasmOp::I64Load16U {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),
        I64Load32S { memarg } => Some(WasmOp::I64Load32S {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),
        I64Load32U { memarg } => Some(WasmOp::I64Load32U {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),

        // i64 sub-word stores
        I64Store8 { memarg } => Some(WasmOp::I64Store8 {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),
        I64Store16 { memarg } => Some(WasmOp::I64Store16 {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),
        I64Store32 { memarg } => Some(WasmOp::I64Store32 {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),

        // Memory management
        MemorySize { mem, .. } => Some(WasmOp::MemorySize(*mem)),
        MemoryGrow { mem, .. } => Some(WasmOp::MemoryGrow(*mem)),

        // Bulk memory (#374). The backend supports a single linear memory
        // (memory 0); any non-zero memory index falls through to `_ => None` and
        // loud-skips the function (GI-FPU-001 honesty contract) rather than
        // miscompiling a multi-memory copy. memory.copy reads dst/src memories;
        // memory.fill one. The selector lowers these to a bounds-checked byte
        // loop (see select_with_stack).
        MemoryCopy {
            dst_mem: 0,
            src_mem: 0,
        } => Some(WasmOp::MemoryCopy),
        MemoryFill { mem: 0 } => Some(WasmOp::MemoryFill),

        // ========================================================================
        // v128 SIMD operations (WASM SIMD proposal, 0xFD prefix)
        // ========================================================================
        V128Const { value } => {
            let mut bytes = [0u8; 16];
            bytes.copy_from_slice(value.bytes());
            Some(WasmOp::V128Const(bytes))
        }
        V128Load { memarg } => Some(WasmOp::V128Load {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),
        V128Store { memarg } => Some(WasmOp::V128Store {
            offset: memarg.offset as u32,
            align: memarg.align as u32,
        }),

        // v128 bitwise
        V128And => Some(WasmOp::V128And),
        V128Or => Some(WasmOp::V128Or),
        V128Xor => Some(WasmOp::V128Xor),
        V128Not => Some(WasmOp::V128Not),
        V128AndNot => Some(WasmOp::V128AndNot),

        // i8x16
        I8x16Add => Some(WasmOp::I8x16Add),
        I8x16Sub => Some(WasmOp::I8x16Sub),
        I8x16Neg => Some(WasmOp::I8x16Neg),
        I8x16Eq => Some(WasmOp::I8x16Eq),
        I8x16Ne => Some(WasmOp::I8x16Ne),
        I8x16LtS => Some(WasmOp::I8x16LtS),
        I8x16LtU => Some(WasmOp::I8x16LtU),
        I8x16GtS => Some(WasmOp::I8x16GtS),
        I8x16GtU => Some(WasmOp::I8x16GtU),
        I8x16LeS => Some(WasmOp::I8x16LeS),
        I8x16LeU => Some(WasmOp::I8x16LeU),
        I8x16GeS => Some(WasmOp::I8x16GeS),
        I8x16GeU => Some(WasmOp::I8x16GeU),
        I8x16Splat => Some(WasmOp::I8x16Splat),
        I8x16ExtractLaneS { lane } => Some(WasmOp::I8x16ExtractLaneS(*lane)),
        I8x16ExtractLaneU { lane } => Some(WasmOp::I8x16ExtractLaneU(*lane)),
        I8x16ReplaceLane { lane } => Some(WasmOp::I8x16ReplaceLane(*lane)),
        I8x16Shuffle { lanes } => Some(WasmOp::I8x16Shuffle(*lanes)),
        I8x16Swizzle => Some(WasmOp::I8x16Swizzle),

        // i16x8
        I16x8Add => Some(WasmOp::I16x8Add),
        I16x8Sub => Some(WasmOp::I16x8Sub),
        I16x8Mul => Some(WasmOp::I16x8Mul),
        I16x8Neg => Some(WasmOp::I16x8Neg),
        I16x8Eq => Some(WasmOp::I16x8Eq),
        I16x8Ne => Some(WasmOp::I16x8Ne),
        I16x8LtS => Some(WasmOp::I16x8LtS),
        I16x8LtU => Some(WasmOp::I16x8LtU),
        I16x8GtS => Some(WasmOp::I16x8GtS),
        I16x8GtU => Some(WasmOp::I16x8GtU),
        I16x8LeS => Some(WasmOp::I16x8LeS),
        I16x8LeU => Some(WasmOp::I16x8LeU),
        I16x8GeS => Some(WasmOp::I16x8GeS),
        I16x8GeU => Some(WasmOp::I16x8GeU),
        I16x8Splat => Some(WasmOp::I16x8Splat),
        I16x8ExtractLaneS { lane } => Some(WasmOp::I16x8ExtractLaneS(*lane)),
        I16x8ExtractLaneU { lane } => Some(WasmOp::I16x8ExtractLaneU(*lane)),
        I16x8ReplaceLane { lane } => Some(WasmOp::I16x8ReplaceLane(*lane)),

        // i32x4
        I32x4Add => Some(WasmOp::I32x4Add),
        I32x4Sub => Some(WasmOp::I32x4Sub),
        I32x4Mul => Some(WasmOp::I32x4Mul),
        I32x4Neg => Some(WasmOp::I32x4Neg),
        I32x4Eq => Some(WasmOp::I32x4Eq),
        I32x4Ne => Some(WasmOp::I32x4Ne),
        I32x4LtS => Some(WasmOp::I32x4LtS),
        I32x4LtU => Some(WasmOp::I32x4LtU),
        I32x4GtS => Some(WasmOp::I32x4GtS),
        I32x4GtU => Some(WasmOp::I32x4GtU),
        I32x4LeS => Some(WasmOp::I32x4LeS),
        I32x4LeU => Some(WasmOp::I32x4LeU),
        I32x4GeS => Some(WasmOp::I32x4GeS),
        I32x4GeU => Some(WasmOp::I32x4GeU),
        I32x4Splat => Some(WasmOp::I32x4Splat),
        I32x4ExtractLane { lane } => Some(WasmOp::I32x4ExtractLane(*lane)),
        I32x4ReplaceLane { lane } => Some(WasmOp::I32x4ReplaceLane(*lane)),

        // i64x2
        I64x2Add => Some(WasmOp::I64x2Add),
        I64x2Sub => Some(WasmOp::I64x2Sub),
        I64x2Mul => Some(WasmOp::I64x2Mul),
        I64x2Neg => Some(WasmOp::I64x2Neg),
        I64x2Eq => Some(WasmOp::I64x2Eq),
        I64x2Ne => Some(WasmOp::I64x2Ne),
        I64x2LtS => Some(WasmOp::I64x2LtS),
        I64x2GtS => Some(WasmOp::I64x2GtS),
        I64x2LeS => Some(WasmOp::I64x2LeS),
        I64x2GeS => Some(WasmOp::I64x2GeS),
        I64x2Splat => Some(WasmOp::I64x2Splat),
        I64x2ExtractLane { lane } => Some(WasmOp::I64x2ExtractLane(*lane)),
        I64x2ReplaceLane { lane } => Some(WasmOp::I64x2ReplaceLane(*lane)),

        // f32x4
        F32x4Add => Some(WasmOp::F32x4Add),
        F32x4Sub => Some(WasmOp::F32x4Sub),
        F32x4Mul => Some(WasmOp::F32x4Mul),
        F32x4Div => Some(WasmOp::F32x4Div),
        F32x4Abs => Some(WasmOp::F32x4Abs),
        F32x4Neg => Some(WasmOp::F32x4Neg),
        F32x4Sqrt => Some(WasmOp::F32x4Sqrt),
        F32x4Eq => Some(WasmOp::F32x4Eq),
        F32x4Ne => Some(WasmOp::F32x4Ne),
        F32x4Lt => Some(WasmOp::F32x4Lt),
        F32x4Le => Some(WasmOp::F32x4Le),
        F32x4Gt => Some(WasmOp::F32x4Gt),
        F32x4Ge => Some(WasmOp::F32x4Ge),
        F32x4Splat => Some(WasmOp::F32x4Splat),
        F32x4ExtractLane { lane } => Some(WasmOp::F32x4ExtractLane(*lane)),
        F32x4ReplaceLane { lane } => Some(WasmOp::F32x4ReplaceLane(*lane)),

        // Other operators not yet supported
        _ => None,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_decode_simple_add() {
        let wat = r#"
            (module
                (func (export "add") (param i32 i32) (result i32)
                    local.get 0
                    local.get 1
                    i32.add
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");

        assert_eq!(functions.len(), 1);
        assert_eq!(functions[0].index, 0);
        assert_eq!(functions[0].export_name, Some("add".to_string()));
        assert_eq!(
            functions[0].ops,
            vec![
                WasmOp::LocalGet(0),
                WasmOp::LocalGet(1),
                WasmOp::I32Add,
                WasmOp::End
            ]
        );
    }

    /// #204 regression: `i64.extend_i32_u`, `i64.extend_i32_s` and
    /// `i32.wrap_i64` must DECODE (they were previously unmapped → silently
    /// dropped by `convert_operator`, leaving an i32 value as a 64-bit operand
    /// with a garbage high half — the root cause of gale's miscompiled
    /// `(new_count << 32)` pack). The decoder must surface all three.
    #[test]
    fn test_decode_i64_i32_width_conversions() {
        let wat = r#"
            (module
                (func (export "conv") (param i32 i64) (result i32)
                    local.get 0
                    i64.extend_i32_u
                    local.get 0
                    i64.extend_i32_s
                    i64.add
                    local.get 1
                    i64.add
                    i32.wrap_i64
                )
            )
        "#;
        let wasm = wat::parse_str(wat).expect("parse");
        let functions = decode_wasm_functions(&wasm).expect("decode");
        let ops = &functions[0].ops;
        assert!(
            ops.contains(&WasmOp::I64ExtendI32U),
            "i64.extend_i32_u must decode (not be dropped): {ops:?}"
        );
        assert!(
            ops.contains(&WasmOp::I64ExtendI32S),
            "i64.extend_i32_s must decode (not be dropped): {ops:?}"
        );
        assert!(
            ops.contains(&WasmOp::I32WrapI64),
            "i32.wrap_i64 must decode (not be dropped): {ops:?}"
        );
    }

    /// #204 WAKE-path regression: `br_table` must DECODE (it was unmapped in
    /// `convert_operator` → silently dropped, so the selector emitted no index
    /// dispatch and every `br_table` fell through to target 0 — gale's binary
    /// semaphore never took its WAKE branch). Targets + default are preserved.
    #[test]
    fn test_decode_br_table() {
        let wat = r#"
            (module
                (func (export "bt") (param i32) (result i32)
                    (block (block (block
                        local.get 0
                        br_table 2 0 1 2)
                      i32.const 30 return)
                      i32.const 20 return)
                    i32.const 10))
        "#;
        let wasm = wat::parse_str(wat).expect("parse");
        let functions = decode_wasm_functions(&wasm).expect("decode");
        let bt = functions[0]
            .ops
            .iter()
            .find_map(|o| match o {
                WasmOp::BrTable { targets, default } => Some((targets.clone(), *default)),
                _ => None,
            })
            .expect("br_table must decode (not be dropped)");
        assert_eq!(bt.0, vec![2, 0, 1], "br_table targets preserved in order");
        assert_eq!(bt.1, 2, "br_table default preserved");
    }

    #[test]
    fn test_decode_arithmetic() {
        let wat = r#"
            (module
                (func (export "calc") (result i32)
                    i32.const 5
                    i32.const 3
                    i32.mul
                    i32.const 2
                    i32.add
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");

        assert_eq!(functions.len(), 1);
        assert_eq!(functions[0].export_name, Some("calc".to_string()));
        assert_eq!(
            functions[0].ops,
            vec![
                WasmOp::I32Const(5),
                WasmOp::I32Const(3),
                WasmOp::I32Mul,
                WasmOp::I32Const(2),
                WasmOp::I32Add,
                WasmOp::End,
            ]
        );
    }

    #[test]
    fn test_decode_multi_function_module() {
        let wat = r#"
            (module
                (func $helper)
                (func (export "add") (param i32 i32) (result i32)
                    local.get 0
                    local.get 1
                    i32.add
                )
                (func (export "sub") (param i32 i32) (result i32)
                    local.get 0
                    local.get 1
                    i32.sub
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");

        assert_eq!(functions.len(), 3);
        assert_eq!(functions[0].index, 0);
        assert_eq!(functions[0].export_name, None);
        assert_eq!(functions[1].index, 1);
        assert_eq!(functions[1].export_name, Some("add".to_string()));
        assert_eq!(functions[2].index, 2);
        assert_eq!(functions[2].export_name, Some("sub".to_string()));
    }

    #[test]
    fn test_decode_module_with_imports() {
        let wat = r#"
            (module
                (import "env" "log" (func $log (param i32)))
                (import "env" "memory" (memory 1))
                (func (export "run") (param i32)
                    local.get 0
                    call 0
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT");
        let module = decode_wasm_module(&wasm).expect("Failed to decode");

        // Should have 2 imports (1 func, 1 memory)
        assert_eq!(module.imports.len(), 2);
        assert_eq!(module.num_imported_funcs, 1);

        // First import is the function
        assert_eq!(module.imports[0].module, "env");
        assert_eq!(module.imports[0].name, "log");
        assert!(matches!(module.imports[0].kind, ImportKind::Function(_)));

        // Second import is memory
        assert_eq!(module.imports[1].module, "env");
        assert_eq!(module.imports[1].name, "memory");
        assert_eq!(module.imports[1].kind, ImportKind::Memory);

        // Should have 1 local function (index 1, because import is index 0)
        assert_eq!(module.functions.len(), 1);
        assert_eq!(module.functions[0].index, 1);
        assert_eq!(module.functions[0].export_name, Some("run".to_string()));
    }

    #[test]
    fn test_find_function_by_export_name() {
        let wat = r#"
            (module
                (func $helper)
                (func (export "add") (param i32 i32) (result i32)
                    local.get 0
                    local.get 1
                    i32.add
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");

        let add_func = functions
            .iter()
            .find(|f| f.export_name.as_deref() == Some("add"))
            .expect("Should find 'add' function");

        assert_eq!(add_func.index, 1);
        assert!(add_func.ops.contains(&WasmOp::I32Add));
    }

    #[test]
    fn test_decode_subword_loads() {
        let wat = r#"
            (module
                (memory 1)
                (func (export "test") (param i32) (result i32)
                    local.get 0
                    i32.load8_u
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");

        assert_eq!(functions.len(), 1);
        assert!(functions[0].ops.contains(&WasmOp::I32Load8U {
            offset: 0,
            align: 0,
        }));
    }

    #[test]
    fn test_decode_subword_stores() {
        let wat = r#"
            (module
                (memory 1)
                (func (export "test") (param i32 i32)
                    local.get 0
                    local.get 1
                    i32.store8
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");

        assert_eq!(functions.len(), 1);
        assert!(functions[0].ops.contains(&WasmOp::I32Store8 {
            offset: 0,
            align: 0,
        }));
    }

    #[test]
    fn test_decode_memory_size_grow() {
        let wat = r#"
            (module
                (memory 1)
                (func (export "test") (result i32)
                    memory.size
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");

        assert_eq!(functions.len(), 1);
        assert!(functions[0].ops.contains(&WasmOp::MemorySize(0)));
    }

    #[test]
    fn test_decode_memory_grow() {
        let wat = r#"
            (module
                (memory 1)
                (func (export "test") (param i32) (result i32)
                    local.get 0
                    memory.grow
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");

        assert_eq!(functions.len(), 1);
        assert!(functions[0].ops.contains(&WasmOp::MemoryGrow(0)));
    }

    #[test]
    fn test_decode_bulk_memory_374() {
        // #374: memory.copy / memory.fill on the single linear memory decode to
        // the new WasmOp variants (was `_ => None` -> loud-skip).
        let wat = r#"
            (module
                (memory 1)
                (func (export "cpy") (param i32 i32 i32)
                    local.get 0 local.get 1 local.get 2 memory.copy)
                (func (export "fil") (param i32 i32 i32)
                    local.get 0 local.get 1 local.get 2 memory.fill)
            )
        "#;
        let wasm = wat::parse_str(wat).expect("Failed to parse WAT");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");
        assert_eq!(functions.len(), 2);
        assert!(functions[0].ops.contains(&WasmOp::MemoryCopy));
        assert!(functions[1].ops.contains(&WasmOp::MemoryFill));
        // Neither function is flagged unsupported (they now lower).
        assert!(functions[0].unsupported.is_none());
        assert!(functions[1].unsupported.is_none());
    }

    #[test]
    fn test_decode_i64_subword_loads() {
        let wat = r#"
            (module
                (memory 1)
                (func (export "test") (param i32) (result i64)
                    local.get 0
                    i64.load8_s
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");

        assert_eq!(functions.len(), 1);
        assert!(functions[0].ops.contains(&WasmOp::I64Load8S {
            offset: 0,
            align: 0,
        }));
    }

    #[test]
    fn test_decode_all_subword_memory_ops() {
        // Test that all sub-word operations are decoded from WAT
        let wat = r#"
            (module
                (memory 1)
                (func (export "test") (param i32)
                    ;; i32 sub-word loads
                    local.get 0
                    i32.load8_s
                    drop
                    local.get 0
                    i32.load8_u
                    drop
                    local.get 0
                    i32.load16_s
                    drop
                    local.get 0
                    i32.load16_u
                    drop

                    ;; i32 sub-word stores
                    local.get 0
                    i32.const 42
                    i32.store8
                    local.get 0
                    i32.const 42
                    i32.store16

                    ;; i64 sub-word loads
                    local.get 0
                    i64.load8_s
                    drop
                    local.get 0
                    i64.load8_u
                    drop
                    local.get 0
                    i64.load16_s
                    drop
                    local.get 0
                    i64.load16_u
                    drop
                    local.get 0
                    i64.load32_s
                    drop
                    local.get 0
                    i64.load32_u
                    drop

                    ;; i64 sub-word stores
                    local.get 0
                    i64.const 42
                    i64.store8
                    local.get 0
                    i64.const 42
                    i64.store16
                    local.get 0
                    i64.const 42
                    i64.store32
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");

        assert_eq!(functions.len(), 1);
        let ops = &functions[0].ops;

        // Verify i32 sub-word ops are present
        assert!(ops.iter().any(|o| matches!(o, WasmOp::I32Load8S { .. })));
        assert!(ops.iter().any(|o| matches!(o, WasmOp::I32Load8U { .. })));
        assert!(ops.iter().any(|o| matches!(o, WasmOp::I32Load16S { .. })));
        assert!(ops.iter().any(|o| matches!(o, WasmOp::I32Load16U { .. })));
        assert!(ops.iter().any(|o| matches!(o, WasmOp::I32Store8 { .. })));
        assert!(ops.iter().any(|o| matches!(o, WasmOp::I32Store16 { .. })));

        // Verify i64 sub-word ops are present
        assert!(ops.iter().any(|o| matches!(o, WasmOp::I64Load8S { .. })));
        assert!(ops.iter().any(|o| matches!(o, WasmOp::I64Load8U { .. })));
        assert!(ops.iter().any(|o| matches!(o, WasmOp::I64Load16S { .. })));
        assert!(ops.iter().any(|o| matches!(o, WasmOp::I64Load16U { .. })));
        assert!(ops.iter().any(|o| matches!(o, WasmOp::I64Load32S { .. })));
        assert!(ops.iter().any(|o| matches!(o, WasmOp::I64Load32U { .. })));
        assert!(ops.iter().any(|o| matches!(o, WasmOp::I64Store8 { .. })));
        assert!(ops.iter().any(|o| matches!(o, WasmOp::I64Store16 { .. })));
        assert!(ops.iter().any(|o| matches!(o, WasmOp::I64Store32 { .. })));
    }

    #[test]
    fn test_decode_simd_i32x4_add() {
        let wat = r#"
            (module
                (func (export "add_v128") (param v128 v128) (result v128)
                    local.get 0
                    local.get 1
                    i32x4.add
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT with SIMD");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");

        assert_eq!(functions.len(), 1);
        assert!(
            functions[0].ops.contains(&WasmOp::I32x4Add),
            "Should decode i32x4.add: {:?}",
            functions[0].ops
        );
    }

    #[test]
    fn test_decode_simd_v128_const() {
        let wat = r#"
            (module
                (func (export "const_v128") (result v128)
                    v128.const i32x4 1 2 3 4
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT with SIMD");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");

        assert_eq!(functions.len(), 1);
        assert!(
            functions[0]
                .ops
                .iter()
                .any(|o| matches!(o, WasmOp::V128Const(_))),
            "Should decode v128.const: {:?}",
            functions[0].ops
        );
    }

    #[test]
    fn test_decode_simd_v128_load_store() {
        let wat = r#"
            (module
                (memory 1)
                (func (export "load_store") (param i32)
                    local.get 0
                    v128.load
                    local.get 0
                    v128.store
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT with SIMD");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");

        assert_eq!(functions.len(), 1);
        let ops = &functions[0].ops;
        assert!(
            ops.iter().any(|o| matches!(o, WasmOp::V128Load { .. })),
            "Should decode v128.load"
        );
        assert!(
            ops.iter().any(|o| matches!(o, WasmOp::V128Store { .. })),
            "Should decode v128.store"
        );
    }

    #[test]
    fn test_decode_simd_bitwise_ops() {
        let wat = r#"
            (module
                (func (export "bitwise") (param v128 v128) (result v128)
                    local.get 0
                    local.get 1
                    v128.and
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT with SIMD");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");

        assert_eq!(functions.len(), 1);
        assert!(functions[0].ops.contains(&WasmOp::V128And));
    }

    #[test]
    fn test_decode_simd_splat() {
        let wat = r#"
            (module
                (func (export "splat") (param i32) (result v128)
                    local.get 0
                    i32x4.splat
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT with SIMD");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");

        assert_eq!(functions.len(), 1);
        assert!(functions[0].ops.contains(&WasmOp::I32x4Splat));
    }

    #[test]
    fn test_decode_simd_extract_lane() {
        let wat = r#"
            (module
                (func (export "extract") (param v128) (result i32)
                    local.get 0
                    i32x4.extract_lane 2
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT with SIMD");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");

        assert_eq!(functions.len(), 1);
        assert!(
            functions[0].ops.contains(&WasmOp::I32x4ExtractLane(2)),
            "Should decode i32x4.extract_lane 2"
        );
    }

    #[test]
    fn test_decode_simd_f32x4_arithmetic() {
        let wat = r#"
            (module
                (func (export "f32x4_add") (param v128 v128) (result v128)
                    local.get 0
                    local.get 1
                    f32x4.add
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT with SIMD");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");

        assert_eq!(functions.len(), 1);
        assert!(functions[0].ops.contains(&WasmOp::F32x4Add));
    }

    #[test]
    fn test_369_scalar_float_op_flags_function_unsupported_not_dropped() {
        // #369: a scalar f32/f64 op the decoder can't lower must FLAG the
        // function (-> loud skip), never be silently dropped (which left a
        // `mov r0,r1` wrong-value stub). A pure-integer function stays clean.
        let wat = r#"
            (module
                (func (export "fadd") (param f32 f32) (result f32)
                    local.get 0 local.get 1 f32.add)
                (func (export "iadd") (param i32 i32) (result i32)
                    local.get 0 local.get 1 i32.add))
        "#;
        let wasm = wat::parse_str(wat).expect("parse");
        let functions = decode_wasm_functions(&wasm).expect("decode");
        let fadd = functions
            .iter()
            .find(|f| f.export_name.as_deref() == Some("fadd"))
            .unwrap();
        let iadd = functions
            .iter()
            .find(|f| f.export_name.as_deref() == Some("iadd"))
            .unwrap();
        assert!(
            fadd.unsupported.is_some(),
            "f32.add must flag the function unsupported (loud-skip), got {:?}",
            fadd.unsupported
        );
        assert!(
            fadd.unsupported.as_deref().unwrap().contains("F32Add"),
            "diagnostic should name the op: {:?}",
            fadd.unsupported
        );
        assert!(
            iadd.unsupported.is_none(),
            "a pure-integer function must NOT be flagged: {:?}",
            iadd.unsupported
        );
    }

    #[test]
    fn test_decode_simd_multiple_ops() {
        let wat = r#"
            (module
                (func (export "simd_ops") (param v128 v128 v128) (result v128)
                    ;; (a + b) * c
                    local.get 0
                    local.get 1
                    i32x4.add
                    local.get 2
                    i32x4.mul
                )
            )
        "#;

        let wasm = wat::parse_str(wat).expect("Failed to parse WAT with SIMD");
        let functions = decode_wasm_functions(&wasm).expect("Failed to decode");

        assert_eq!(functions.len(), 1);
        let ops = &functions[0].ops;
        assert!(ops.contains(&WasmOp::I32x4Add));
        assert!(ops.contains(&WasmOp::I32x4Mul));
    }

    /// VCR-DBG-001 step 1 (#394): the decoder records a module-relative wasm byte
    /// offset per emitted op — the DWARF-for-wasm address space that bridges
    /// synth's op-index `source_line` to the input wasm's `.debug_line`. Purely
    /// additive metadata (no codegen consumer ⇒ frozen fixtures byte-identical,
    /// verified separately); this test pins the structural invariants.
    #[test]
    fn test_decode_records_aligned_increasing_op_offsets_dbg001() {
        let wat = r#"
            (module
                (func (export "f") (param i32 i32) (result i32)
                    local.get 0
                    local.get 1
                    i32.add
                    i32.const 7
                    i32.mul))
        "#;
        let wasm = wat::parse_str(wat).expect("parse WAT");
        let functions = decode_wasm_functions(&wasm).expect("decode");
        let f = &functions[0];

        // One offset per emitted op, index-aligned with `ops`.
        assert_eq!(
            f.op_offsets.len(),
            f.ops.len(),
            "op_offsets must be parallel to ops"
        );
        assert!(!f.op_offsets.is_empty());

        // Byte offsets are strictly increasing through the body (each op consumes
        // at least one byte) and module-relative (well past the header).
        assert!(
            f.op_offsets.windows(2).all(|w| w[1] > w[0]),
            "wasm byte offsets must strictly increase: {:?}",
            f.op_offsets
        );
        assert!(
            f.op_offsets[0] >= 8,
            "module-relative offset is past the 8-byte wasm header"
        );
    }

    /// #237: the decoder captures a global's `i32.const` initializer + mutability,
    /// so the native-pointer ABI can recognize the stack-pointer global.
    #[test]
    fn test_decode_captures_global_initializer() {
        let wat = r#"
            (module
                (memory 2)
                (global $__stack_pointer (mut i32) (i32.const 65536))
                (global $immutable_const i32 (i32.const 7))
                (func (export "f") (result i32) global.get 0)
            )
        "#;
        let wasm = wat::parse_str(wat).expect("Failed to parse WAT");
        let module = decode_wasm_module(&wasm).expect("Failed to decode");

        assert_eq!(module.globals.len(), 2, "both globals captured");
        let sp = &module.globals[0];
        assert_eq!(sp.index, 0);
        assert_eq!(sp.init_i32, Some(65536), "stack-pointer init captured");
        assert!(sp.mutable, "stack pointer is mutable");
        let c = &module.globals[1];
        assert_eq!(c.init_i32, Some(7));
        assert!(!c.mutable, "second global is immutable");
    }

    /// #509: the decoder records `(param_count, result_count)` for every
    /// `Block`/`Loop`/`If`, ordinal-keyed in op order, covering all three
    /// blocktype encodings: `Empty → (0,0)`, `ValType → (0,1)`, and
    /// `FuncType(i) →` counts from the type section (here a multi-result
    /// block, which wat encodes as a functype blocktype).
    #[test]
    fn test_decode_records_block_arity_side_table_509() {
        let wat = r#"
            (module
                (func (export "f") (param i32) (result i32)
                    (block (result i32)
                        (block (nop))
                        (local.get 0)
                        (if (result i32)
                            (then (i32.const 1))
                            (else (i32.const 2)))))
                (func (export "g") (result i32)
                    (block (result i32 i32)
                        (i32.const 1) (i32.const 2))
                    i32.add)
                (func (export "h") (param i32) (result i32)
                    (local.get 0)
                    (loop (param i32) (result i32))))
        "#;
        let wasm = wat::parse_str(wat).expect("parse WAT");

        // Both decode entry points must produce the same side-table.
        for functions in [
            decode_wasm_functions(&wasm).expect("decode"),
            decode_wasm_module(&wasm).expect("decode").functions,
        ] {
            // f: Block(result i32), Block(void), If(result i32) — in op order.
            assert_eq!(
                functions[0].block_arity,
                vec![(0, 1), (0, 0), (0, 1)],
                "f: ValType/Empty/ValType blocktypes"
            );
            // g: one multi-result block via a FuncType blocktype.
            assert_eq!(
                functions[1].block_arity,
                vec![(0, 2)],
                "g: functype blocktype result count from the type section"
            );
            // h: a parameterized loop — the input arity is what a br to the
            // header would carry (the #509 loud-decline discriminator).
            assert_eq!(
                functions[2].block_arity,
                vec![(1, 1)],
                "h: loop params captured"
            );
        }
    }
}