scripting/

runtime.rs

//! Shared wasmtime primitives used by every host of nomiscript-compiled
//! modules: the entity-script `ScriptExecutor` and the rpc eval channel.
//!
//! Owns the engine config (WasmGC + epoch interruption + optional fuel),
//! the per-bytecode `Module` cache, the trap-classification helper, and the
//! `decode_eval_result` helper that walks the nomi-eval `(ref null any)`
//! return value into a structured [`EvalValue`]. Higher-level consumers
//! parameterize over the Store data type and assemble their own Linker on top.

use std::collections::HashMap;
use std::sync::{Arc, Mutex};

use thiserror::Error;
use uuid::Uuid;

use crate::checked_ref::CheckedAnyRef;
use wasmtime::{
    AnyRef, AsContextMut, Caller, Config, Engine, FieldType, Linker, Module, Mutability, Rooted,
    StorageType, Store, StructRef, StructRefPre, StructType, Val, ValType,
};

#[derive(Debug, Error)]
pub enum EngineError {
    #[error("engine config rejected: {0}")]
    Config(String),
    #[error("module cache lock poisoned")]
    CachePoisoned,
    #[error("module compilation failed: {0}")]
    Compile(String),
    #[error("module instantiation failed: {0}")]
    Instantiate(String),
    #[error("fuel configuration failed: {0}")]
    Fuel(String),
    #[error("missing export `{0}`")]
    MissingExport(String),
    #[error("fuel exhausted before completion")]
    OutOfFuel,
    #[error("epoch deadline reached before completion")]
    EpochInterrupt,
    /// `ConvertCommodity` raises this when no Price row links source
    /// and target in either direction. Lifted into a dedicated variant
    /// so clients can prompt the user to add a price row rather than
    /// guess from a generic trap message.
    #[error("no conversion: {0}")]
    NoConversion(String),
    /// A structured error raised in-guest, surfaced via the `__nomi_raise`
    /// host fn (`Err(wasmtime::Error::msg("__nomi_raise:CODE:MSG"))`). Two
    /// sources converge here (ADR-0026): a script `(error 'code "msg")`, and
    /// an engine error like a commodity mismatch — both `throw $nomi_error`
    /// in-guest, and the boundary wrapper around each host-invoked body
    /// catches an uncaught throw and bridges it to `__nomi_raise`. The
    /// classifier parses the marker prefix and surfaces the code symbol
    /// (`COMMODITY-MISMATCH`, a script's own symbol, …) onto the wire
    /// envelope's `:code` slot. Codes are reader-folded (upper-cased)
    /// symbols, not free-form strings.
    #[error("script raised {code}: {message}")]
    ScriptRaised { code: String, message: String },
    #[error("execution trapped: {0}")]
    Trap(String),
}

/// Marker prefix the `__nomi_raise` host fn embeds in its wasmtime
/// error message so the runtime classifier can recognise script-raised
/// errors before the unreachable-trap branch fires. Kept here so the
/// host-fn body and the classifier agree on the wire format.
pub const NOMI_RAISE_MARKER: &str = "__nomi_raise:";

/// Optional profiling strategy. JitDump is the Linux `perf record`
/// flow; it writes a `jit-<pid>.dump` file the OS-level profiler can
/// read. PerfMap is the simpler symbol-name-only Linux variant. Both
/// require the `wasmtime/profiling` cargo feature, which we pull in
/// via the `jitdump` feature flag on the scripting crate; non-Linux
/// builds should leave this as `None`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ProfilerStrategy {
    #[default]
    None,
    JitDump,
    PerfMap,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct EngineOpts {
    pub fuel: bool,
    pub profiler: ProfilerStrategy,
}

impl EngineOpts {
    #[must_use]
    pub const fn baseline() -> Self {
        Self {
            fuel: false,
            profiler: ProfilerStrategy::None,
        }
    }

    #[must_use]
    pub const fn with_fuel(mut self) -> Self {
        self.fuel = true;
        self
    }

    #[must_use]
    pub const fn with_profiler(mut self, strategy: ProfilerStrategy) -> Self {
        self.profiler = strategy;
        self
    }
}

impl Default for EngineOpts {
    fn default() -> Self {
        Self::baseline()
    }
}

pub fn build_engine(opts: EngineOpts) -> Result<Engine, EngineError> {
    let mut config = Config::new();
    config.wasm_gc(true);
    config.wasm_function_references(true);
    // Exception-handling proposal: `(error)` lowers to `throw $nomi_error`
    // and `(handler-case)` / `(unwind-protect)` lower to `try_table`
    // (Tier 3, ADR-0026). Engine traps (`OutOfFuel` / `EpochInterrupt`)
    // are not wasm exceptions, so they bypass `try_table` and keep the
    // per-Session deadline budget non-catchable.
    config.wasm_exceptions(true);
    config.epoch_interruption(true);
    if opts.fuel {
        config.consume_fuel(true);
    }
    match opts.profiler {
        ProfilerStrategy::None => {}
        ProfilerStrategy::JitDump => {
            config.profiler(wasmtime::ProfilingStrategy::JitDump);
        }
        ProfilerStrategy::PerfMap => {
            config.profiler(wasmtime::ProfilingStrategy::PerfMap);
        }
    }
    Engine::new(&config).map_err(|e| EngineError::Config(e.to_string()))
}

pub fn compile_module(engine: &Engine, bytes: &[u8]) -> Result<Module, EngineError> {
    Module::new(engine, bytes).map_err(|e| EngineError::Compile(e.to_string()))
}

pub fn compile_wat(engine: &Engine, source: &str) -> Result<Module, EngineError> {
    Module::new(engine, source).map_err(|e| EngineError::Compile(e.to_string()))
}

/// Per-engine bytecode cache keyed by the full module bytes. Cloning a
/// [`ModuleCache`] yields a handle into the same inner map; meant to be
/// shared between long-lived hosts (Session, ScriptExecutor) and any per-form
/// helpers that need the same cached compilation.
#[derive(Debug, Default, Clone)]
pub struct ModuleCache {
    inner: Arc<Mutex<HashMap<Vec<u8>, Module>>>,
}

impl ModuleCache {
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    pub fn get_or_compile(&self, engine: &Engine, bytecode: &[u8]) -> Result<Module, EngineError> {
        if let Some(module) = self.lookup(bytecode)? {
            return Ok(module);
        }
        let module = compile_module(engine, bytecode)?;
        self.store(bytecode, module.clone())?;
        Ok(module)
    }

    fn lookup(&self, bytecode: &[u8]) -> Result<Option<Module>, EngineError> {
        let guard = self.inner.lock().map_err(|_| EngineError::CachePoisoned)?;
        Ok(guard.get(bytecode).cloned())
    }

    fn store(&self, bytecode: &[u8], module: Module) -> Result<(), EngineError> {
        let mut guard = self.inner.lock().map_err(|_| EngineError::CachePoisoned)?;
        guard.insert(bytecode.to_vec(), module);
        Ok(())
    }

    pub fn is_empty(&self) -> Result<bool, EngineError> {
        let guard = self.inner.lock().map_err(|_| EngineError::CachePoisoned)?;
        Ok(guard.is_empty())
    }

    pub fn len(&self) -> Result<usize, EngineError> {
        let guard = self.inner.lock().map_err(|_| EngineError::CachePoisoned)?;
        Ok(guard.len())
    }
}

/// Classifies a [`wasmtime::Error`] thrown during execution into a typed
/// [`EngineError`]. Downcast to [`wasmtime::Trap`] handles the structured
/// fuel/epoch cases; everything else falls through as `Trap(message)`.
pub fn classify_runtime_error(err: &wasmtime::Error) -> EngineError {
    if let Some(trap) = err.downcast_ref::<wasmtime::Trap>() {
        match *trap {
            wasmtime::Trap::OutOfFuel => return EngineError::OutOfFuel,
            wasmtime::Trap::Interrupt => return EngineError::EpochInterrupt,
            _ => {}
        }
    }
    // Walk the error chain so host-fn `wasmtime::Error::msg("...")` causes
    // (e.g. "get-commodity: invalid uuid '...'") surface alongside the
    // wasmtime wrapper's "error while executing at wasm backtrace" header.
    // `err.to_string()` alone only renders the outermost wrapper, which
    // hides the diagnostic the host fn actually emitted.
    let mut combined = err.to_string();
    for cause in err.chain().skip(1) {
        combined.push_str(": ");
        combined.push_str(&cause.to_string());
    }
    // Script-raised errors must classify *before* the unreachable-trap
    // branch: `(error 'code "msg")` lowers to `__nomi_raise` returning
    // `Err(wasmtime::Error::msg("__nomi_raise:CODE:MSG"))`. Returning
    // `Err` from a host fn never trips `unreachable`, so ADR-0014's
    // single-unreachable invariant is preserved — but the chain walk
    // above stitches the host-fn message into `combined`, and the
    // marker prefix lets us recover the symbol/message without parsing
    // wasmtime's wrapper text.
    if let Some(raised) = parse_nomi_raise_marker(err) {
        return raised;
    }
    if combined.contains("convert-commodity: no Price row")
        || combined.contains("convert-commodity: inverse price has zero numerator")
    {
        return EngineError::NoConversion(combined);
    }
    EngineError::Trap(combined)
}

/// Walks the error chain for a `__nomi_raise:CODE:MSG` marker emitted by
/// the `__nomi_raise` host fn. Returns the structured `ScriptRaised`
/// variant when found, otherwise `None`. Searches the chain rather than
/// the combined string so script-raised codes survive intact even when
/// MSG itself contains literal `:` characters.
fn parse_nomi_raise_marker(err: &wasmtime::Error) -> Option<EngineError> {
    err.chain()
        .map(|cause| cause.to_string())
        .find_map(|cause_str| split_marker(&cause_str))
}

fn split_marker(text: &str) -> Option<EngineError> {
    let rest = text.strip_prefix(NOMI_RAISE_MARKER)?;
    let (code, message) = rest.split_once(':')?;
    Some(EngineError::ScriptRaised {
        code: code.to_string(),
        message: message.to_string(),
    })
}

/// Maps an `EngineError` to the `(code, message)` pair scripts and
/// batch consumers see when a script fails — code is a kebab-case
/// symbol (matching the wire envelope's `:code` slot for catch-each
/// cells and `server::script` per-tx reports), message is the
/// engine's own diagnostic string.
///
/// Engine-bound deadlines (`OutOfFuel`, `EpochInterrupt`) also have a
/// mapping here so callers that *do* want to surface them to scripts
/// (batch runners that don't care about catch-each's "engine deadlines
/// aren't catchable" rule) can. catch-each filters the deadlines out
/// before reaching this mapper.
#[must_use]
pub fn err_code_and_message(err: &EngineError) -> (String, String) {
    match err {
        EngineError::ScriptRaised { code, message } => (code.clone(), message.clone()),
        EngineError::NoConversion(msg) => ("no-conversion".to_string(), msg.clone()),
        EngineError::Trap(msg) => ("runtime".to_string(), msg.clone()),
        EngineError::Compile(msg) => ("compile".to_string(), msg.clone()),
        EngineError::Instantiate(msg) => ("runtime".to_string(), msg.clone()),
        EngineError::Fuel(msg) => ("runtime".to_string(), msg.clone()),
        EngineError::MissingExport(msg) => ("runtime".to_string(), msg.clone()),
        EngineError::Config(msg) => ("runtime".to_string(), msg.clone()),
        EngineError::CachePoisoned => (
            "runtime".to_string(),
            "module cache lock poisoned".to_string(),
        ),
        EngineError::OutOfFuel => ("runtime".to_string(), "fuel exhausted".to_string()),
        EngineError::EpochInterrupt => ("runtime".to_string(), "epoch deadline".to_string()),
    }
}

/// Allocates an ATOMIC `$commodity` value by re-entering the guest's exported
/// `commodity_new` with the four i64 components (numer, denom, commodity_hi,
/// commodity_lo). Since ADR-0028 E0 the `$commodity` struct carries a 5th
/// `(ref null $unit_term)` field; the host must NOT construct that ref-bearing
/// struct itself, so it delegates to the guest helper (which sets the term to
/// null = atomic) — the same re-entry pattern as `alloc_pair_chain` / the
/// entity allocators. Async because it calls back into the wasm instance.
pub async fn alloc_commodity_ref<T>(
    caller: &mut Caller<'_, T>,
    numer: i64,
    denom: i64,
    commodity_id: Uuid,
) -> wasmtime::Result<Rooted<StructRef>>
where
    T: Send,
{
    let commodity_new = caller
        .get_export("commodity_new")
        .and_then(|e| e.into_func())
        .ok_or_else(|| {
            wasmtime::Error::msg(
                "module missing 'commodity_new' export — host commodity allocation \
                 requires the nomiscript compiler skeleton's exported commodity_new",
            )
        })?;
    let (hi, lo) = commodity_id.as_u64_pair();
    let mut results = [Val::AnyRef(None)];
    commodity_new
        .call_async(
            caller.as_context_mut(),
            &[
                Val::I64(numer),
                Val::I64(denom),
                Val::I64(hi as i64),
                Val::I64(lo as i64),
            ],
            &mut results,
        )
        .await?;
    match &results[0] {
        Val::AnyRef(Some(any)) => any.checked_struct(caller.as_context_mut()),
        Val::AnyRef(None) => Err(wasmtime::Error::msg("commodity_new returned null")),
        _ => Err(wasmtime::Error::msg(
            "commodity_new returned non-anyref Val variant",
        )),
    }
}

/// Allocates a `$i8_array` wasm array holding `bytes` and returns a rooted
/// reference. Single allocation; callers can format UUID/name payloads into
/// a reused `Vec<u8>` and ship the bytes without an intermediate `String`.
/// Engine canonicalizes the i8 array type so the host-side allocation
/// matches the guest's `(array i8)` declaration in
/// `CompileContext::new_skeleton`.
pub fn alloc_string_ref<T>(
    caller: &mut Caller<'_, T>,
    bytes: &[u8],
) -> wasmtime::Result<Rooted<wasmtime::ArrayRef>> {
    let engine = caller.engine().clone();
    // Mutability must match the compiler's `register_type("i8_array")` field
    // declaration (mutable: true) — engine canonicalization compares the
    // mutability bit, so a `Const` array type would fail the guest's
    // `ref.cast (ref $i8_array)` even though the storage type matches.
    let ty = wasmtime::ArrayType::new(&engine, FieldType::new(Mutability::Var, StorageType::I8));
    let pre = wasmtime::ArrayRefPre::new(caller.as_context_mut(), ty);
    let vals: Vec<Val> = bytes.iter().map(|b| Val::I32(i32::from(*b))).collect();
    wasmtime::ArrayRef::new_fixed(caller.as_context_mut(), &pre, &vals)
}

/// Allocates a `$ratio` wasm struct (2 i64 fields: numer, denom). Mirrors
/// `alloc_commodity_ref` for the Ratio numeric stratum — used when a host
/// fn returns a typed Ratio without going through the synthesized
/// `ratio_new` wrap.
pub fn alloc_ratio_ref<T>(
    caller: &mut Caller<'_, T>,
    numer: i64,
    denom: i64,
) -> wasmtime::Result<Rooted<StructRef>> {
    let engine = caller.engine().clone();
    let ty = StructType::new(
        &engine,
        std::iter::repeat_n(
            FieldType::new(Mutability::Const, StorageType::ValType(ValType::I64)),
            2,
        ),
    )?;
    let pre = StructRefPre::new(caller.as_context_mut(), ty);
    StructRef::new(
        caller.as_context_mut(),
        &pre,
        &[Val::I64(numer), Val::I64(denom)],
    )
}

/// Allocates an entity wasm struct (`$account`, `$commodity_entity`, etc) by
/// re-entering the module's exported `alloc_<kind>` function. The host can't
/// freshly construct an entity `StructType` via `StructType::new` — fields
/// like `(ref null $i8_array)` reference concrete type indices that engine
/// canonicalization compares by identity, so any abstract `anyref`-typed
/// fresh declaration produces a structurally distinct (and uncastable) type.
/// Re-entry through the guest's own allocator (registered in
/// `CompileContext::register_entity_allocators`) sidesteps the issue: each
/// call returns a struct ref of the exact `$<kind>` type the subsequent
/// `ref.cast (ref $<kind>)` in the consuming form accepts.
///
/// Args are passed in declaration order matching the entity's struct
/// field layout (see `CompileContext::new_skeleton`).
pub async fn alloc_entity_via_export<T>(
    caller: &mut Caller<'_, T>,
    export_name: &str,
    args: &[Val],
) -> wasmtime::Result<Rooted<StructRef>>
where
    T: Send,
{
    let alloc = caller
        .get_export(export_name)
        .and_then(|e| e.into_func())
        .ok_or_else(|| {
            wasmtime::Error::msg(format!(
                "module missing '{export_name}' export — host entity allocation requires \
                 the nomiscript compiler skeleton's exported alloc_<kind> function"
            ))
        })?;
    let mut results = [Val::AnyRef(None)];
    alloc
        .call_async(caller.as_context_mut(), args, &mut results)
        .await?;
    let new_entity_any = match &results[0] {
        Val::AnyRef(any) => *any,
        _ => {
            return Err(wasmtime::Error::msg(format!(
                "{export_name} returned non-anyref Val variant"
            )));
        }
    };
    new_entity_any
        .ok_or_else(|| {
            wasmtime::Error::msg(format!(
                "{export_name} returned null when allocating entity"
            ))
        })?
        .checked_struct(caller.as_context_mut())
}

/// Reads a `$i8_array` arg ref into a Rust `String`. `None` is returned for
/// null refs (the wasm-level `(ref null $i8_array)` param's null state). The
/// underlying byte storage is i8 (mutable per `register_type("i8_array")`),
/// so each element is read via `array.get_u` semantics and assembled into a
/// `Vec<u8>` then UTF-8 validated. Non-UTF-8 bytes surface as a structured
/// trap rather than a silent replacement.
pub fn read_string_arg<T>(
    caller: &mut Caller<'_, T>,
    arg: Option<Rooted<wasmtime::ArrayRef>>,
) -> wasmtime::Result<Option<String>> {
    let Some(arr) = arg else {
        return Ok(None);
    };
    let len = arr.len(caller.as_context_mut())?;
    let mut bytes = Vec::with_capacity(len as usize);
    for i in 0..len {
        let val = arr.get(caller.as_context_mut(), i)?;
        let byte_i32 = val
            .i32()
            .ok_or_else(|| wasmtime::Error::msg("string arg element is not i32"))?;
        bytes.push(byte_i32 as u8);
    }
    String::from_utf8(bytes)
        .map(Some)
        .map_err(|err| wasmtime::Error::msg(format!("string arg is not valid UTF-8: {err}")))
}

/// Reads a `$commodity` arg ref into its (numer, denom, commodity_id)
/// components. Mirrors `read_string_arg` for the Commodity numeric stratum:
/// fields 0-1 are numer/denom, fields 2-3 are the UUID halves. `None`
/// returns for a null ref; bad shape surfaces as a structured trap.
pub fn read_commodity_arg<T>(
    caller: &mut Caller<'_, T>,
    arg: Option<Rooted<StructRef>>,
) -> wasmtime::Result<Option<(i64, i64, Uuid)>> {
    let Some(s) = arg else {
        return Ok(None);
    };
    let read_i64 = |c: &mut Caller<'_, T>, idx: usize| -> wasmtime::Result<i64> {
        let v = s.field(c.as_context_mut(), idx)?;
        v.i64()
            .ok_or_else(|| wasmtime::Error::msg(format!("commodity field {idx} is not i64")))
    };
    let numer = read_i64(caller, 0)?;
    let denom = read_i64(caller, 1)?;
    let hi = read_i64(caller, 2)?;
    let lo = read_i64(caller, 3)?;
    let raw = ((hi as u64 as u128) << 64) | (lo as u64 as u128);
    Ok(Some((numer, denom, Uuid::from_u128(raw))))
}

/// Reads a `$ratio` arg ref into its `(numer, denom)` components. `None`
/// returns for a null ref; a zero denominator is rejected as a structured trap
/// so callers never divide by zero. Mirrors `read_commodity_arg` for the
/// dimensionless Scalar stratum (a `draft-split` amount).
pub fn read_ratio_arg<T>(
    caller: &mut Caller<'_, T>,
    arg: Option<Rooted<StructRef>>,
) -> wasmtime::Result<Option<(i64, i64)>> {
    let Some(s) = arg else {
        return Ok(None);
    };
    let numer = s
        .field(caller.as_context_mut(), 0)?
        .i64()
        .ok_or_else(|| wasmtime::Error::msg("ratio field 0 (numer) is not i64"))?;
    let denom = s
        .field(caller.as_context_mut(), 1)?
        .i64()
        .ok_or_else(|| wasmtime::Error::msg("ratio field 1 (denom) is not i64"))?;
    if denom == 0 {
        return Err(wasmtime::Error::msg("ratio has zero denominator"));
    }
    Ok(Some((numer, denom)))
}

/// Reads a named String field from an entity struct arg, resolving the field's
/// slot index from [`nomiscript::entity_layout`] (the single source of struct
/// slot order). `None` returns for a null ref. Errors if the kind has no
/// layout, the named field is absent or non-String, or the slot is not an
/// `$i8_array`. This is how the draft natives read e.g. an account's `id`
/// (slot 0) from a `(get-account …)` entity ref passed as an argument.
pub fn read_entity_string_field<T>(
    caller: &mut Caller<'_, T>,
    arg: Option<Rooted<StructRef>>,
    kind: nomiscript::EntityKind,
    field_name: &str,
) -> wasmtime::Result<Option<String>> {
    let Some(s) = arg else {
        return Ok(None);
    };
    read_entity_string_field_ctx(caller.as_context_mut(), s, kind, field_name).map(Some)
}

/// Context-based core of [`read_entity_string_field`], split out so it is
/// unit-testable without a `Caller` (tests hold a bare `Store`). Resolves the
/// field's slot from the entity layout and reads it as an `$i8_array` string.
pub fn read_entity_string_field_ctx(
    mut store: impl AsContextMut,
    entity: Rooted<StructRef>,
    kind: nomiscript::EntityKind,
    field_name: &str,
) -> wasmtime::Result<String> {
    let layout = nomiscript::entity_layout(kind)
        .ok_or_else(|| wasmtime::Error::msg(format!("no entity layout for {kind:?}")))?;
    let idx = layout
        .fields
        .iter()
        .position(|f| f.name == field_name && f.kind == nomiscript::EntityFieldKind::String)
        .ok_or_else(|| {
            wasmtime::Error::msg(format!(
                "entity {kind:?} has no String field named '{field_name}'"
            ))
        })?;
    let arr = match entity.field(store.as_context_mut(), idx)? {
        Val::AnyRef(Some(any)) => any.checked_array(store.as_context_mut())?,
        _ => {
            return Err(wasmtime::Error::msg(format!(
                "entity {kind:?} field '{field_name}' (slot {idx}) is not an i8_array"
            )));
        }
    };
    let len = arr.len(store.as_context_mut())?;
    let mut bytes = Vec::with_capacity(len as usize);
    for i in 0..len {
        let byte = arr
            .get(store.as_context_mut(), i)?
            .i32()
            .ok_or_else(|| wasmtime::Error::msg("entity string element is not i32"))?;
        bytes.push(byte as u8);
    }
    String::from_utf8(bytes)
        .map_err(|err| wasmtime::Error::msg(format!("entity string field not utf-8: {err}")))
}

/// Folds an iterator of GC-ref elements into a `$pair` chain by re-entering
/// the wasm module via its exported `pair_new` function. Returns the chain
/// head, or `None` if the iterator is empty.
///
/// `$pair` is the self-recursive cell type (`{anyref car, ref null $pair
/// cdr}`) declared by `CompileContext::new_skeleton`. The host can't freshly
/// construct that StructType via `StructType::new` — the cdr field references
/// the type itself, which `StructType::new` doesn't model. Instead this
/// helper reaches into the module's own type system: `pair_new` is already
/// emitted by the compiler skeleton as `register_function("pair_new", ...)`
/// which adds it to the export table, so the host fn body can pull it from
/// `Caller::get_export` and invoke it per element. Each call produces a
/// `Rooted<StructRef>` of the exact `$pair` type that subsequent `ref.cast
/// (ref null $pair)` operations in the guest accept.
///
/// Items are folded right-to-left so the first element of the iterator
/// ends up at the chain head — `[a, b, c]` → `(a . (b . (c . nil)))`.
pub async fn alloc_pair_chain<T>(
    caller: &mut Caller<'_, T>,
    items: impl IntoIterator<Item = Rooted<AnyRef>>,
) -> wasmtime::Result<Option<Rooted<StructRef>>>
where
    T: Send,
{
    let pair_new = caller
        .get_export("pair_new")
        .and_then(|e| e.into_func())
        .ok_or_else(|| {
            wasmtime::Error::msg(
                "module missing 'pair_new' export — host pair allocation requires \
                 the nomiscript compiler skeleton's exported pair_new",
            )
        })?;

    let items: Vec<Rooted<AnyRef>> = items.into_iter().collect();
    let mut head: Option<Rooted<StructRef>> = None;
    for item in items.into_iter().rev() {
        let cdr_any = head.map(|p| p.to_anyref());
        let mut results = [Val::AnyRef(None)];
        pair_new
            .call_async(
                caller.as_context_mut(),
                &[Val::AnyRef(Some(item)), Val::AnyRef(cdr_any)],
                &mut results,
            )
            .await?;
        let new_pair_any = match &results[0] {
            Val::AnyRef(any) => *any,
            _ => {
                return Err(wasmtime::Error::msg(
                    "pair_new returned non-anyref Val variant",
                ));
            }
        };
        head = Some(
            new_pair_any
                .ok_or_else(|| {
                    wasmtime::Error::msg("pair_new returned null when chaining elements")
                })?
                .checked_struct(caller.as_context_mut())?,
        );
    }
    Ok(head)
}

/// Instantiates `module` against an empty linker and calls a zero-arg export
/// returning a single `i64`. Constraints (fuel cap, epoch deadline) come from
/// the caller-supplied `Store`.
pub fn call_i64_export<T>(
    engine: &Engine,
    store: &mut Store<T>,
    module: &Module,
    export: &str,
) -> Result<i64, EngineError> {
    let linker = Linker::<T>::new(engine);
    let instance = linker
        .instantiate(&mut *store, module)
        .map_err(|e| classify_runtime_error(&e))?;
    let func = instance
        .get_typed_func::<(), i64>(&mut *store, export)
        .map_err(|_| EngineError::MissingExport(export.to_string()))?;
    func.call(&mut *store, ())
        .map_err(|e| classify_runtime_error(&e))
}

/// Final value captured by an eval-mode module via the `nomi_capture_*` host
/// fns. Mirrors the subset of [`nomiscript::WasmType`] variants the compiler
/// emits as terminal stack types, plus a `Bytes` variant for native fns that
/// marshal compound data (server-command results via `scripting-format`,
/// chart SVGs, exported files, etc.). Cons/Vector/Closure/Struct still wait
/// for the GC migration.
#[derive(Debug, Clone, PartialEq)]
pub enum EvalValue {
    Nil,
    T,
    I32(i32),
    Ratio {
        numer: i64,
        denom: i64,
    },
    /// Commodity-bearing amount: rational + originating commodity uuid.
    /// Distinct from `Ratio` so cross-strata arithmetic is rejected by
    /// the compiler before any wire round-trip. Wire form via
    /// `format_value`: `(:commodity <ratio> :id "<uuid>")`.
    Commodity {
        numer: i64,
        denom: i64,
        commodity_hi: i64,
        commodity_lo: i64,
    },
    String(String),
    Bytes(Vec<u8>),
}

impl From<EvalValue> for nomiscript::Value {
    fn from(value: EvalValue) -> Self {
        match value {
            EvalValue::Nil => nomiscript::Value::Nil,
            EvalValue::T => nomiscript::Value::T,
            EvalValue::I32(n) => {
                nomiscript::Value::Number(nomiscript::Fraction::from_integer(i64::from(n)))
            }
            EvalValue::Ratio { numer, denom } => {
                nomiscript::Value::Number(nomiscript::Fraction::new(numer, denom))
            }
            EvalValue::Commodity {
                numer,
                denom,
                commodity_hi,
                commodity_lo,
            } => {
                // Reassemble the 16-byte uuid from the wasm-side (hi, lo)
                // i64 pair. Both halves get cast to u64 first so negative
                // i64 patterns don't sign-extend into bogus high bits.
                let raw = ((commodity_hi as u64 as u128) << 64) | (commodity_lo as u64 as u128);
                nomiscript::Value::Commodity {
                    amount: nomiscript::Fraction::new(numer, denom),
                    commodity_id: uuid::Uuid::from_u128(raw),
                }
            }
            EvalValue::String(s) => nomiscript::Value::String(s),
            EvalValue::Bytes(b) => nomiscript::Value::Bytes(b),
        }
    }
}

/// Decodes nomi-eval's anyref return value into an [`EvalValue`] using
/// the compile-time-known result type. `None` for the result_ty means
/// the form was empty / definition-only and the host should see
/// [`EvalValue::Nil`]. Numeric types (`I32`, `Ratio`, `Commodity`) and
/// `StringRef` decode directly. `PairRef` walks the chain, decoding
/// each car per its declared element type. `EntityRef` returns a
/// placeholder until a downstream consumer needs the structured
/// shape host-side. Takes any `AsContextMut` so it works with both
/// `&mut Store<T>` (sync test paths) and `&mut Caller<'_, T>` (async
/// host fn paths).
pub fn decode_eval_result(
    mut store: impl AsContextMut,
    value: Option<Rooted<AnyRef>>,
    result_ty: Option<nomiscript::WasmType>,
) -> wasmtime::Result<EvalValue> {
    let Some(ty) = result_ty else {
        return Ok(EvalValue::Nil);
    };
    // Reference-typed results can legitimately be null: empty
    // `pair<…>` from `list-accounts`, `Option<Rooted<…>>` returns
    // surfacing not-found / missing-string cases. Surface those as
    // `Nil` so consumers see an empty-shaped value rather than a
    // trap. Primitive (I32) returns can't be null and stay strict.
    let Some(any) = value else {
        return match ty {
            nomiscript::WasmType::I32 => Err(wasmtime::Error::msg(
                "nomi-eval returned null for declared result type i32",
            )),
            _ => Ok(EvalValue::Nil),
        };
    };
    decode_anyref(&mut store, any, ty)
}

/// An index result crosses nomi-eval as an `(n, 1)` ratio struct so all 32 bits
/// survive the anyref slot.
fn decode_index(mut store: impl AsContextMut, any: &Rooted<AnyRef>) -> wasmtime::Result<EvalValue> {
    let numer = any
        .checked_struct(&mut store)?
        .field(&mut store, 0)?
        .i64()
        .ok_or_else(|| wasmtime::Error::msg("index result field 0 (numer) is not i64"))?;
    i32::try_from(numer)
        .map(EvalValue::I32)
        .map_err(|_| wasmtime::Error::msg(format!("index result {numer} exceeds i32")))
}

fn decode_anyref(
    mut store: impl AsContextMut,
    any: Rooted<AnyRef>,
    ty: nomiscript::WasmType,
) -> wasmtime::Result<EvalValue> {
    use nomiscript::WasmType;
    match ty {
        WasmType::I32 => decode_index(&mut store, &any),
        WasmType::Bool => {
            // A boolean result is i31-boxed like an i32, but decodes to nil /
            // t (matches the const-fold path): 0 → Nil, nonzero → T.
            let i31 = any.checked_i31(&mut store)?;
            if i31.get_i32() == 0 {
                Ok(EvalValue::Nil)
            } else {
                Ok(EvalValue::T)
            }
        }
        WasmType::Ratio => {
            let s = any.checked_struct(&mut store)?;
            let numer = s
                .field(&mut store, 0)?
                .i64()
                .ok_or_else(|| wasmtime::Error::msg("ratio field 0 (numer) is not i64"))?;
            let denom = s
                .field(&mut store, 1)?
                .i64()
                .ok_or_else(|| wasmtime::Error::msg("ratio field 1 (denom) is not i64"))?;
            Ok(EvalValue::Ratio { numer, denom })
        }
        WasmType::Commodity => {
            let s = any.checked_struct(&mut store)?;
            let numer = s.field(&mut store, 0)?.i64().unwrap_or(0);
            let denom = s.field(&mut store, 1)?.i64().unwrap_or(1);
            // Field 4 is the unit term (ADR-0028). Null ⇒ ATOMIC single-currency
            // money (id in fields 2-3). An empty term ⇒ DIMENSIONLESS (money ÷
            // money, same currency) and decodes as a plain Number. A non-empty
            // (compound) term — e.g. money×money — has no host wire form yet.
            match s.field(&mut store, 4)? {
                Val::AnyRef(None) => {
                    let hi = s.field(&mut store, 2)?.i64().unwrap_or(0);
                    let lo = s.field(&mut store, 3)?.i64().unwrap_or(0);
                    Ok(EvalValue::Commodity {
                        numer,
                        denom,
                        commodity_hi: hi,
                        commodity_lo: lo,
                    })
                }
                Val::AnyRef(Some(term)) => {
                    let arr = term.checked_array(&mut store)?;
                    if arr.len(&mut store)? == 0 {
                        Ok(EvalValue::Ratio { numer, denom })
                    } else {
                        Err(wasmtime::Error::msg(
                            "compound commodity (e.g. money × money) has no host \
                             representation yet",
                        ))
                    }
                }
                _ => Err(wasmtime::Error::msg(
                    "commodity field 4 (unit term) is not a ref",
                )),
            }
        }
        WasmType::StringRef => {
            let arr = any.checked_array(&mut store)?;
            let len = arr.len(&mut store)?;
            let mut bytes = Vec::with_capacity(len as usize);
            for i in 0..len {
                let v = arr.get(&mut store, i)?;
                let byte = v
                    .i32()
                    .ok_or_else(|| wasmtime::Error::msg("string element is not i32"))?;
                bytes.push(byte as u8);
            }
            let s = String::from_utf8(bytes)
                .map_err(|err| wasmtime::Error::msg(format!("not valid utf-8: {err}")))?;
            Ok(EvalValue::String(s))
        }
        WasmType::PairRef(elem) => {
            let head = render_pair_as_string(&mut store, any, elem)?;
            Ok(EvalValue::String(head))
        }
        WasmType::EntityRef(kind) => {
            let entity = any.checked_struct(&mut store)?;
            Ok(EvalValue::String(render_entity(&mut store, entity, kind)?))
        }
        WasmType::Closure(_) => {
            let _ = any;
            Ok(EvalValue::String("<closure>".into()))
        }
        WasmType::AnyRef => {
            // Heterogeneous payload (catch-each result cells, etc.).
            // The host renderer cannot statically pick a decoder, so it
            // surfaces a placeholder; the script-side accessor natives
            // (`ok?` / `err-code` / etc.) are responsible for inspecting
            // the contents.
            let _ = any;
            Ok(EvalValue::String("<anyref>".into()))
        }
    }
}

/// Walks a `$pair` chain and renders it as a Lisp-style list-of-cars
/// textual form `( <car> <car> ... )`. Element decoding dispatches on
/// the compile-time PairElement so each car gets its proper formatter.
fn render_pair_as_string(
    mut store: impl AsContextMut,
    head_any: Rooted<AnyRef>,
    elem: nomiscript::PairElement,
) -> wasmtime::Result<String> {
    let mut out = String::from("(");
    let mut cur: Option<Rooted<StructRef>> = Some(head_any.checked_struct(&mut store)?);
    let mut first = true;
    while let Some(node) = cur {
        if !first {
            out.push(' ');
        }
        first = false;
        let car_val = node.field(&mut store, 0)?;
        let car_any = match car_val {
            Val::AnyRef(Some(a)) => a,
            Val::AnyRef(None) => {
                out.push_str("nil");
                let cdr_val = node.field(&mut store, 1)?;
                cur = match cdr_val {
                    Val::AnyRef(Some(a)) => Some(a.checked_struct(&mut store)?),
                    _ => None,
                };
                continue;
            }
            _ => {
                return Err(wasmtime::Error::msg("pair car is not anyref"));
            }
        };
        let car_str = render_car(&mut store, car_any, elem)?;
        out.push_str(&car_str);
        let cdr_val = node.field(&mut store, 1)?;
        cur = match cdr_val {
            Val::AnyRef(Some(a)) => Some(a.checked_struct(&mut store)?),
            _ => None,
        };
    }
    out.push(')');
    Ok(out)
}

fn render_car(
    mut store: impl AsContextMut,
    car_any: Rooted<AnyRef>,
    elem: nomiscript::PairElement,
) -> wasmtime::Result<String> {
    use nomiscript::PairElement;
    match elem {
        PairElement::I32 => {
            let i31 = car_any.checked_i31(&mut store)?;
            Ok(i31.get_i32().to_string())
        }
        PairElement::Bool => {
            // Shares the i31 car with I32, but renders as a truth value: 0 →
            // `nil`, nonzero → `t` (matching the bool/nil wire convention).
            let i31 = car_any.checked_i31(&mut store)?;
            Ok(if i31.get_i32() == 0 { "nil" } else { "t" }.to_string())
        }
        PairElement::Ratio => {
            let s = car_any.checked_struct(&mut store)?;
            let n = s.field(&mut store, 0)?.i64().unwrap_or(0);
            let d = s.field(&mut store, 1)?.i64().unwrap_or(1);
            if d == 1 {
                Ok(n.to_string())
            } else {
                Ok(format!("{n}/{d}"))
            }
        }
        PairElement::Commodity => {
            let s = car_any.checked_struct(&mut store)?;
            let n = s.field(&mut store, 0)?.i64().unwrap_or(0);
            let d = s.field(&mut store, 1)?.i64().unwrap_or(1);
            // Field 4 (unit term, ADR-0028) decides the wire form — SAME rules
            // as the top-level `decode_anyref` Commodity arm, so a compound
            // money riding a `$pair` cell can't slip through as id-zero atomic
            // money: null ⇒ atomic (id in fields 2-3), empty ⇒ dimensionless
            // Number, non-empty (compound) ⇒ error (no host wire form yet).
            match s.field(&mut store, 4)? {
                Val::AnyRef(None) => {
                    let hi = s.field(&mut store, 2)?.i64().unwrap_or(0);
                    let lo = s.field(&mut store, 3)?.i64().unwrap_or(0);
                    let raw = ((hi as u64 as u128) << 64) | (lo as u64 as u128);
                    let id = Uuid::from_u128(raw);
                    if d == 1 {
                        Ok(format!("(:commodity {n} :id \"{id}\")"))
                    } else {
                        Ok(format!("(:commodity {n}/{d} :id \"{id}\")"))
                    }
                }
                Val::AnyRef(Some(term)) => {
                    let arr = term.checked_array(&mut store)?;
                    if arr.len(&mut store)? == 0 {
                        Ok(if d == 1 {
                            n.to_string()
                        } else {
                            format!("{n}/{d}")
                        })
                    } else {
                        Err(wasmtime::Error::msg(
                            "compound commodity (e.g. money × money) has no host \
                             representation yet",
                        ))
                    }
                }
                _ => Err(wasmtime::Error::msg(
                    "commodity field 4 (unit term) is not a ref",
                )),
            }
        }
        PairElement::StringRef => {
            let arr = car_any.checked_array(&mut store)?;
            let len = arr.len(&mut store)?;
            let mut bytes = Vec::with_capacity(len as usize);
            for i in 0..len {
                let v = arr.get(&mut store, i)?;
                bytes.push(v.i32().unwrap_or(0) as u8);
            }
            let s = String::from_utf8(bytes).unwrap_or_else(|_| "<invalid-utf8>".into());
            Ok(nomiscript::format_value(&nomiscript::Value::String(s)))
        }
        PairElement::Entity(kind) => {
            let entity = car_any.checked_struct(&mut store)?;
            render_entity(&mut store, entity, kind)
        }
        PairElement::AnyRef => Ok("<anyref>".into()),
    }
}

/// Renders a typed entity struct as a readable plist —
/// `(:commodity :id "…" :symbol "USD" :name "US Dollar")` — by reading each
/// field at its `struct.get` slot per the single-source-of-truth
/// [`nomiscript::entity_layout`] (generated from `entity_registry.org`). Field
/// slot order in the layout matches the wasm struct exactly. A `Pair` field
/// renders as `()`-elided; the host has no element-type context to walk it.
fn render_entity(
    mut store: impl AsContextMut,
    entity: Rooted<StructRef>,
    kind: nomiscript::EntityKind,
) -> wasmtime::Result<String> {
    use nomiscript::EntityFieldKind;

    let Some(layout) = nomiscript::entity_layout(kind) else {
        // No field layout (e.g. Condition isn't a server entity).
        return Ok(format!("(:{kind:?})"));
    };
    let mut out = format!("(:{}", layout.label);
    for (slot, field) in layout.fields.iter().enumerate() {
        let rendered = match field.kind {
            EntityFieldKind::String => read_string_slot(&mut store, entity, slot)?,
            EntityFieldKind::Ratio => read_ratio_slot(&mut store, entity, slot)?,
            EntityFieldKind::I32 => entity
                .field(&mut store, slot)?
                .i32()
                .unwrap_or(0)
                .to_string(),
            EntityFieldKind::Pair => "(...)".to_string(),
        };
        out.push_str(&format!(" :{} {rendered}", field.name));
    }
    out.push(')');
    Ok(out)
}

/// Reads a `(ref null $i8_array)` string field at `slot`, rendered as a quoted
/// literal. A null/empty slot renders as `""`.
fn read_string_slot(
    mut store: impl AsContextMut,
    entity: Rooted<StructRef>,
    slot: usize,
) -> wasmtime::Result<String> {
    match entity.field(&mut store, slot)? {
        Val::AnyRef(Some(a)) => {
            let arr = a.checked_array(&mut store)?;
            let len = arr.len(&mut store)?;
            let mut bytes = Vec::with_capacity(len as usize);
            for i in 0..len {
                bytes.push(arr.get(&mut store, i)?.i32().unwrap_or(0) as u8);
            }
            let s = String::from_utf8(bytes).unwrap_or_else(|_| "<invalid-utf8>".into());
            Ok(nomiscript::format_value(&nomiscript::Value::String(s)))
        }
        _ => Ok("\"\"".to_string()),
    }
}

/// Reads a `(ref null $ratio)` field at `slot` (i64 numer/denom in slots 0/1 of
/// the ratio struct), rendered as `n` or `n/d`. A null slot renders as `0`.
fn read_ratio_slot(
    mut store: impl AsContextMut,
    entity: Rooted<StructRef>,
    slot: usize,
) -> wasmtime::Result<String> {
    match entity.field(&mut store, slot)? {
        Val::AnyRef(Some(a)) => {
            let s = a.checked_struct(&mut store)?;
            let n = s.field(&mut store, 0)?.i64().unwrap_or(0);
            let d = s.field(&mut store, 1)?.i64().unwrap_or(1);
            Ok(if d == 1 {
                n.to_string()
            } else {
                format!("{n}/{d}")
            })
        }
        _ => Ok("0".to_string()),
    }
}

#[cfg(test)]
mod tests;