bop-lang 0.3.0

#[cfg(feature = "no_std")]
use alloc::{format, string::{String, ToString}, vec, vec::Vec};

use alloc_import::collections::BTreeMap;

#[cfg(not(feature = "no_std"))]
use std as alloc_import;
#[cfg(feature = "no_std")]
use alloc as alloc_import;

#[cfg(feature = "no_std")]
use alloc::rc::Rc;

#[cfg(not(feature = "no_std"))]
use std::rc::Rc;

use core::cell::RefCell;

use crate::builtins::{
    self, error, error_at, error_fatal_with_hint, error_with_hint, error_with_hint_at,
};
use crate::error::BopError;
use crate::lexer::StringPart;
use crate::methods;
use crate::ops;
use crate::parser::*;
use crate::value::{BopFn, EnumPayload, FnBody, Value};
use crate::{BopHost, BopLimits};

/// What the tree-walker stores for each imported module once it
/// has been loaded. Cached by dot-joined path so the same module
/// imported twice in one `run` only evaluates once.
///
/// `Loading` is the in-progress sentinel; if an import request
/// sees a module already in this state it's a circular import and
/// halts with a clear error.
enum ImportSlot {
    Loading,
    Loaded(ModuleBindings),
}

#[derive(Clone)]
struct ModuleBindings {
    /// `(name, value)` pairs for every top-level `let` in the
    /// module (fns are handled separately — they also need to
    /// land in `self.functions` so cross-fn calls within the
    /// module resolve).
    bindings: Vec<(String, Value)>,
    /// Top-level `fn` declarations, keyed by name. The importer
    /// registers each both in its `self.functions` table
    /// (for nested call resolution) and as a scope binding
    /// (so the fn is also usable as a first-class value).
    fn_decls: Vec<(String, FnDef)>,
    /// Struct type declarations the module introduces, already
    /// qualified with their full identity `(module_path,
    /// type_name)`. The importer copies these into its own
    /// `struct_defs` without rewriting keys, so type identity
    /// stays pinned to the declaring module across the import
    /// boundary.
    struct_defs: Vec<((String, String), Vec<String>)>,
    /// Enum type declarations, qualified the same way as
    /// `struct_defs` above.
    enum_defs: Vec<((String, String), Vec<crate::parser::VariantDecl>)>,
    /// User methods the module declared, keyed by the *full
    /// type identity* of the receiver. `((module_path,
    /// type_name), method_name, fn_def)` — the importer merges
    /// these directly into its own `methods` table.
    methods: Vec<((String, String), String, FnDef)>,
}

type ImportCache = Rc<RefCell<alloc_import::collections::BTreeMap<String, ImportSlot>>>;

const MAX_CALL_DEPTH: usize = 64;

// `try` unwinds via `BopError::try_return_signal` — a proper
// sentinel with `is_try_return = true` rather than the older
// magic-string approach. The value travels on
// `Evaluator::pending_try_return` so the `BopError` itself
// doesn't need to carry a `Value` (which would introduce a
// module cycle between `bop::error` and `bop::value`).

// ─── Control flow signals ──────────────────────────────────────────────────

enum Signal {
    None,
    Break,
    Continue,
    Return(Value),
}

#[derive(Clone)]
struct FnDef {
    params: Vec<String>,
    body: Vec<Stmt>,
}

// ─── Evaluator ─────────────────────────────────────────────────────────────

pub struct Evaluator<'h, H: BopHost> {
    scopes: Vec<BTreeMap<String, Value>>,
    functions: BTreeMap<String, FnDef>,
    /// Module this evaluator is running. Used to tag newly
    /// declared types with the module they live in, so two
    /// modules that declare `struct Color { ... }` produce
    /// distinct types rather than colliding by name. `<root>`
    /// for the top-level program, the dot-joined module path
    /// for a sub-evaluator loading a `use`'d module.
    current_module: String,
    /// User-defined struct types, keyed by their full identity
    /// `(module_path, type_name)` — the same pair the runtime
    /// values carry. Two modules declaring the same struct name
    /// coexist at different keys with independently-validated
    /// field lists.
    struct_defs: BTreeMap<(String, String), Vec<String>>,
    /// User-defined enum types, same `(module_path, type_name)`
    /// keying scheme as [`Self::struct_defs`].
    enum_defs: BTreeMap<(String, String), Vec<VariantDecl>>,
    /// User-defined methods. Outer key is the *full type
    /// identity* `(module_path, type_name)`; inner key is the
    /// method name. Methods receive the receiver as their first
    /// parameter (conventionally `self`). Dispatch looks up the
    /// receiver's own `(module_path, type_name)` so a method
    /// declared for `paint.Color` isn't accidentally called on
    /// `other.Color`.
    methods: BTreeMap<(String, String), BTreeMap<String, FnDef>>,
    /// Per-scope bare-name → module_path bindings for types
    /// *and* module aliases. Parallels `scopes`: a declared
    /// type or an aliased `use` binds `name → module_path` in
    /// the current scope. Bare-name lookup (`Color::Red`,
    /// `m.Color::Red`) walks this stack inside-out. `<builtin>`
    /// types (`Result`, `RuntimeError`) are seeded into scope
    /// 0 at evaluator construction so they're visible
    /// everywhere.
    ///
    /// Unlike `scopes`, this stack is *preserved* across
    /// function calls — type identity follows lexical scoping
    /// at the module level, so a `fn` declared inside the root
    /// program can still match patterns against types + aliases
    /// that were visible at its declaration site. Function
    /// bodies push a fresh frame on entry so any locally-
    /// declared types are discarded on return; module-scope
    /// entries below stay put.
    type_bindings: Vec<BTreeMap<String, String>>,
    /// Module-level aliases `m → Rc<BopModule>`, populated by
    /// aliased `use` statements. Separate from `scopes` so
    /// aliases remain reachable from inside function bodies
    /// (where `self.scopes` is fresh per call). Field access /
    /// method dispatch on `m.foo` falls back to this map when
    /// `m` isn't a local binding.
    module_aliases: BTreeMap<String, Rc<crate::value::BopModule>>,
    host: &'h mut H,
    steps: u64,
    call_depth: usize,
    limits: BopLimits,
    rand_state: u64,
    /// Shared across nested evaluators so recursive imports see
    /// the same cache — every sub-evaluator inherits the parent's
    /// `Rc` clone in `new_nested`.
    imports: ImportCache,
    /// Paths already injected into *this* evaluator's scope (not
    /// shared with sub-evaluators). Re-importing the same path at
    /// the same level is a no-op — matches Python's `import x;
    /// import x` behaviour.
    imported_here: alloc_import::collections::BTreeSet<String>,
    /// Set by `try` when it sees an `Err(...)` variant and wants
    /// the enclosing fn to early-return with that value. The
    /// expression that raised stuffs the value here and returns
    /// a sentinel `BopError`; the fn-call wrapper detects the
    /// sentinel, takes the value, and converts it to
    /// `Signal::Return`. Always `None` outside the narrow
    /// unwinding window.
    pending_try_return: Option<Value>,
    /// Non-fatal runtime warnings accumulated during execution —
    /// currently only `use`-time name-shadowing events (glob
    /// imports bringing in a name that's already bound). Read
    /// after `run()` returns via [`Self::take_warnings`].
    runtime_warnings: Vec<crate::error::BopWarning>,
}

impl<'h, H: BopHost> Evaluator<'h, H> {
    pub fn new(host: &'h mut H, limits: BopLimits) -> Self {
        crate::memory::bop_memory_init(limits.max_memory);
        let (struct_defs, enum_defs, builtin_bindings) = seed_builtin_types();
        Self {
            scopes: vec![BTreeMap::new()],
            functions: BTreeMap::new(),
            current_module: String::from(crate::value::ROOT_MODULE_PATH),
            struct_defs,
            enum_defs,
            methods: BTreeMap::new(),
            type_bindings: vec![builtin_bindings],
            module_aliases: BTreeMap::new(),
            host,
            steps: 0,
            call_depth: 0,
            limits,
            rand_state: 0,
            imports: Rc::new(RefCell::new(alloc_import::collections::BTreeMap::new())),
            imported_here: alloc_import::collections::BTreeSet::new(),
            pending_try_return: None,
            runtime_warnings: Vec::new(),
        }
    }

    /// Build a sub-evaluator for loading a module — inherits the
    /// parent's import cache, memory ceiling, and step budget, but
    /// runs with a fresh scope stack so module code can't see the
    /// importer's locals. `module_path` is the dot-joined name the
    /// module is being loaded under; types it declares tag their
    /// runtime values with this path.
    fn new_for_module(
        host: &'h mut H,
        limits: BopLimits,
        imports: ImportCache,
        module_path: String,
    ) -> Self {
        let (struct_defs, enum_defs, builtin_bindings) = seed_builtin_types();
        Self {
            scopes: vec![BTreeMap::new()],
            functions: BTreeMap::new(),
            current_module: module_path,
            struct_defs,
            enum_defs,
            methods: BTreeMap::new(),
            type_bindings: vec![builtin_bindings],
            module_aliases: BTreeMap::new(),
            host,
            steps: 0,
            call_depth: 0,
            limits,
            rand_state: 0,
            imports,
            imported_here: alloc_import::collections::BTreeSet::new(),
            pending_try_return: None,
            runtime_warnings: Vec::new(),
        }
    }

    pub fn run(mut self, stmts: &[Stmt]) -> Result<(), BopError> {
        let result = self.exec_block(stmts);
        #[cfg(not(feature = "no_std"))]
        {
            // Surface any runtime warnings accumulated during the
            // run (currently: glob-import shadowing). They land on
            // stderr with the standard `warning:` prefix so
            // terminal users see them — no public API change
            // needed. Embedders that want structured access can
            // use `run_with_warnings` (future) or implement their
            // own evaluation loop.
            for w in &self.runtime_warnings {
                eprintln!("warning: {}", w.message);
            }
        }
        match result? {
            Signal::Break => {
                return Err(error(0, "break used outside of a loop"));
            }
            Signal::Continue => {
                return Err(error(0, "continue used outside of a loop"));
            }
            _ => {}
        }
        Ok(())
    }

    fn tick(&mut self, line: u32) -> Result<(), BopError> {
        self.steps += 1;
        if self.steps > self.limits.max_steps {
            // Fatal — `try_call` must not swallow this, or the
            // sandbox invariant breaks.
            return Err(error_fatal_with_hint(
                line,
                "Your code took too many steps (possible infinite loop)",
                "Check your loops — make sure they have a condition that eventually stops them.",
            ));
        }
        if crate::memory::bop_memory_exceeded() {
            return Err(error_fatal_with_hint(
                line,
                "Memory limit exceeded",
                "Your code is using too much memory. Check for large strings or arrays growing in loops.",
            ));
        }
        self.host.on_tick()?;
        Ok(())
    }

    // ─── Scope ─────────────────────────────────────────────────────

    fn push_scope(&mut self) {
        self.scopes.push(BTreeMap::new());
        // Type bindings parallel the value scopes — same push /
        // pop rhythm keeps `use`-injected type names stack-scoped.
        self.type_bindings.push(BTreeMap::new());
    }

    fn pop_scope(&mut self) {
        self.scopes.pop();
        self.type_bindings.pop();
    }

    /// Resolve a type reference to the module it was declared
    /// in. `namespace` is the explicit qualifier (from
    /// `m.Color::Red`) or `None` for bare names. For bare names
    /// the scope stack is walked inside-out; for namespaced
    /// references the alias is resolved via
    /// `validate_namespaced_type` and its backing module path
    /// returned. Returns `None` when no matching type is visible.
    fn resolve_type_ref(&self, namespace: Option<&str>, type_name: &str) -> Option<String> {
        resolve_type_in(
            &self.scopes,
            &self.type_bindings,
            &self.module_aliases,
            namespace,
            type_name,
        )
    }

    /// Record a type declaration in the current module.
    /// Registers `(current_module, name)` in the appropriate
    /// table and binds the bare name in the current scope so
    /// subsequent references resolve to *this* module's version.
    /// Same-shape redeclarations in the same module are a no-op;
    /// different-shape ones error.
    fn bind_local_type(&mut self, name: &str) {
        if let Some(top) = self.type_bindings.last_mut() {
            top.insert(name.to_string(), self.current_module.clone());
        }
    }

    fn define(&mut self, name: String, value: Value) {
        if let Some(scope) = self.scopes.last_mut() {
            scope.insert(name, value);
        }
    }

    fn get_var(&self, name: &str) -> Option<&Value> {
        for scope in self.scopes.iter().rev() {
            if let Some(val) = scope.get(name) {
                return Some(val);
            }
        }
        None
    }

    fn set_var(&mut self, name: &str, value: Value) -> bool {
        for scope in self.scopes.iter_mut().rev() {
            if scope.contains_key(name) {
                scope.insert(name.to_string(), value);
                return true;
            }
        }
        false
    }

    // ─── "Did you mean?" candidate collectors ─────────────────
    //
    // Every name the user could reasonably have meant, gathered
    // into a single list so `bop::suggest::did_you_mean` picks
    // the closest match. Separate methods for the "ident used
    // as a value" and "ident called as a function" paths since
    // the reachable sets differ (builtins are callable but
    // aren't scope values).

    /// Names reachable when an identifier is used as a value:
    /// any local from the enclosing scopes plus any top-level
    /// fn declaration (fns are first-class — `let g = some_fn`
    /// works, so they count as value-like).
    fn value_candidates_hint(&self, target: &str) -> Option<String> {
        let mut candidates: Vec<String> = Vec::new();
        for scope in &self.scopes {
            for k in scope.keys() {
                candidates.push(k.clone());
            }
        }
        for name in self.functions.keys() {
            candidates.push(name.clone());
        }
        crate::suggest::did_you_mean(target, candidates)
    }

    /// Names reachable in a call position: user fns, core
    /// builtins, plus `try_call`. Host builtins stay with the
    /// host's own `function_hint()` path — embedders often want
    /// to list theirs differently.
    fn callable_candidates_hint(&self, target: &str) -> Option<String> {
        let mut candidates: Vec<String> =
            self.functions.keys().cloned().collect();
        for builtin in crate::suggest::CORE_CALLABLE_BUILTINS {
            candidates.push((*builtin).to_string());
        }
        crate::suggest::did_you_mean(target, candidates)
    }

    // ─── Statements ────────────────────────────────────────────────

    fn exec_block(&mut self, stmts: &[Stmt]) -> Result<Signal, BopError> {
        for stmt in stmts {
            let signal = self.exec_stmt(stmt)?;
            match signal {
                Signal::None => {}
                other => return Ok(other),
            }
        }
        Ok(Signal::None)
    }

    fn exec_stmt(&mut self, stmt: &Stmt) -> Result<Signal, BopError> {
        self.tick(stmt.line)?;

        match &stmt.kind {
            StmtKind::Let { name, value, is_const: _ } => {
                let val = self.eval_expr(value)?;
                self.define(name.clone(), val);
                Ok(Signal::None)
            }

            StmtKind::Assign { target, op, value } => {
                let new_val = self.eval_expr(value)?;
                self.exec_assign(target, op, new_val, stmt.line)?;
                Ok(Signal::None)
            }

            StmtKind::If {
                condition,
                body,
                else_ifs,
                else_body,
            } => {
                if self.eval_expr(condition)?.is_truthy() {
                    self.push_scope();
                    let sig = self.exec_block(body)?;
                    self.pop_scope();
                    return Ok(sig);
                }
                for (elif_cond, elif_body) in else_ifs {
                    if self.eval_expr(elif_cond)?.is_truthy() {
                        self.push_scope();
                        let sig = self.exec_block(elif_body)?;
                        self.pop_scope();
                        return Ok(sig);
                    }
                }
                if let Some(else_body) = else_body {
                    self.push_scope();
                    let sig = self.exec_block(else_body)?;
                    self.pop_scope();
                    return Ok(sig);
                }
                Ok(Signal::None)
            }

            StmtKind::While { condition, body } => {
                loop {
                    self.tick(stmt.line)?;
                    if !self.eval_expr(condition)?.is_truthy() {
                        break;
                    }
                    self.push_scope();
                    let sig = self.exec_block(body)?;
                    self.pop_scope();
                    match sig {
                        Signal::Break => break,
                        Signal::Continue => continue,
                        Signal::Return(v) => return Ok(Signal::Return(v)),
                        Signal::None => {}
                    }
                }
                Ok(Signal::None)
            }

            StmtKind::Repeat { count, body } => {
                let n = match self.eval_expr(count)? {
                    Value::Int(n) => n,
                    Value::Number(n) => n as i64,
                    other => {
                        return Err(error(
                            stmt.line,
                            format!("repeat needs a number, but got {}", other.type_name()),
                        ));
                    }
                };
                for _ in 0..n.max(0) {
                    self.tick(stmt.line)?;
                    self.push_scope();
                    let sig = self.exec_block(body)?;
                    self.pop_scope();
                    match sig {
                        Signal::Break => break,
                        Signal::Continue => continue,
                        Signal::Return(v) => return Ok(Signal::Return(v)),
                        Signal::None => {}
                    }
                }
                Ok(Signal::None)
            }

            StmtKind::ForIn {
                var,
                iterable,
                body,
            } => {
                let val = self.eval_expr(iterable)?;
                // Fast path for the three built-in iterables:
                // materialise up-front and loop over the Vec
                // directly, skipping the method-dispatch cost of
                // the iterator protocol. Semantically identical
                // to `for x in v.iter()` for these types.
                if matches!(
                    &val,
                    Value::Array(_) | Value::Str(_) | Value::Dict(_)
                ) {
                    let mut val = val;
                    let items: Vec<Value> = match &mut val {
                        Value::Array(arr) => arr.take(),
                        Value::Str(s) => s
                            .chars()
                            .map(|c| Value::new_str(c.to_string()))
                            .collect(),
                        Value::Dict(d) => d
                            .iter()
                            .map(|(k, _)| Value::new_str(k.clone()))
                            .collect(),
                        _ => unreachable!(),
                    };
                    for item in items {
                        self.tick(stmt.line)?;
                        self.push_scope();
                        self.define(var.clone(), item);
                        let sig = self.exec_block(body)?;
                        self.pop_scope();
                        match sig {
                            Signal::Break => break,
                            Signal::Continue => continue,
                            Signal::Return(v) => return Ok(Signal::Return(v)),
                            Signal::None => {}
                        }
                    }
                    return Ok(Signal::None);
                }
                // Protocol path: anything else must either be an
                // iterator already (Value::Iter, or a user value
                // with a `.next()` method that returns
                // `Iter::Next/Done`) or an iterable — a value
                // whose `.iter()` method returns an iterator.
                // Primitives and callables that don't fit get a
                // clean "can't iterate over X" error instead of
                // a raw "no such method" surface from the
                // dispatcher below.
                let iterator = match &val {
                    Value::Iter(_) | Value::Struct(_) | Value::EnumVariant(_) => {
                        // Ask the value for an iterator. User
                        // structs typically implement `iter` to
                        // return either a built-in iterator or
                        // themselves.
                        self.call_method_full(&val, "iter", Vec::new(), stmt.line)?
                    }
                    other => {
                        return Err(error(
                            stmt.line,
                            crate::error_messages::cant_iterate_over(
                                other.type_name(),
                            ),
                        ));
                    }
                };
                loop {
                    self.tick(stmt.line)?;
                    let next_val =
                        self.call_method_full(&iterator, "next", Vec::new(), stmt.line)?;
                    let item = match unwrap_iter_result(&next_val) {
                        Some(IterStep::Next(v)) => v,
                        Some(IterStep::Done) => break,
                        None => {
                            return Err(error(
                                stmt.line,
                                format!(
                                    "`.next()` on a `for` iterator must return `Iter::Next(v)` or `Iter::Done`, got {}",
                                    next_val.inspect()
                                ),
                            ));
                        }
                    };
                    self.push_scope();
                    self.define(var.clone(), item);
                    let sig = self.exec_block(body)?;
                    self.pop_scope();
                    match sig {
                        Signal::Break => break,
                        Signal::Continue => continue,
                        Signal::Return(v) => return Ok(Signal::Return(v)),
                        Signal::None => {}
                    }
                }
                Ok(Signal::None)
            }

            StmtKind::FnDecl { name, params, body } => {
                self.functions.insert(
                    name.clone(),
                    FnDef {
                        params: params.clone(),
                        body: body.clone(),
                    },
                );
                Ok(Signal::None)
            }

            StmtKind::MethodDecl {
                type_name,
                method_name,
                params,
                body,
            } => {
                // Methods belong to a *specific* type identity —
                // `fn Color.area(self)` inside module `paint`
                // registers under `(paint, Color)` and doesn't
                // leak to `other.Color`. If the named type isn't
                // declared in this module, that's an error at
                // parse/emit consistency — fall back to the
                // current module as the owner.
                let type_key = (self.current_module.clone(), type_name.clone());
                self.methods
                    .entry(type_key)
                    .or_default()
                    .insert(
                        method_name.clone(),
                        FnDef {
                            params: params.clone(),
                            body: body.clone(),
                        },
                    );
                Ok(Signal::None)
            }

            StmtKind::Return { value } => {
                let val = match value {
                    Some(expr) => self.eval_expr(expr)?,
                    None => Value::None,
                };
                Ok(Signal::Return(val))
            }

            StmtKind::Break => Ok(Signal::Break),
            StmtKind::Continue => Ok(Signal::Continue),

            StmtKind::Use { path, items, alias } => {
                self.exec_import(
                    path,
                    items.as_deref(),
                    alias.as_deref(),
                    stmt.line,
                )?;
                Ok(Signal::None)
            }

            StmtKind::StructDecl { name, fields } => {
                // Reject duplicate field names at decl time so
                // downstream code doesn't have to re-check. Walker,
                // VM, and AOT all assume unique fields per struct.
                let mut seen = alloc_import::collections::BTreeSet::new();
                for f in fields {
                    if !seen.insert(f.clone()) {
                        return Err(error(
                            stmt.line,
                            format!("Struct `{}` has duplicate field `{}`", name, f),
                        ));
                    }
                }
                // Type identity is `(current_module, name)` —
                // two different modules declaring the same name
                // coexist because their keys differ. A redecl
                // *in the same module* is a no-op when the shape
                // matches (mirrors the same-module idempotency
                // rule for re-imports) and a clash otherwise.
                let key = (self.current_module.clone(), name.clone());
                if let Some(existing) = self.struct_defs.get(&key) {
                    if existing == fields {
                        self.bind_local_type(name);
                        return Ok(Signal::None);
                    }
                    return Err(error(
                        stmt.line,
                        format!("Struct `{}` is already declared", name),
                    ));
                }
                self.struct_defs.insert(key, fields.clone());
                self.bind_local_type(name);
                Ok(Signal::None)
            }

            StmtKind::EnumDecl { name, variants } => {
                let key = (self.current_module.clone(), name.clone());
                if let Some(existing) = self.enum_defs.get(&key) {
                    // Same rule as `StructDecl` above — a
                    // same-module same-shape redeclaration is a
                    // no-op, anything else is a clash.
                    if variants_equivalent(existing, variants) {
                        self.bind_local_type(name);
                        return Ok(Signal::None);
                    }
                    return Err(error(
                        stmt.line,
                        format!("Enum `{}` is already declared", name),
                    ));
                }
                let mut seen_variants = alloc_import::collections::BTreeSet::new();
                for v in variants {
                    if !seen_variants.insert(v.name.clone()) {
                        return Err(error(
                            stmt.line,
                            format!(
                                "Enum `{}` has duplicate variant `{}`",
                                name, v.name
                            ),
                        ));
                    }
                    if let VariantKind::Struct(fields) | VariantKind::Tuple(fields) =
                        &v.kind
                    {
                        let mut seen_fields = alloc_import::collections::BTreeSet::new();
                        for f in fields {
                            if !seen_fields.insert(f.clone()) {
                                return Err(error(
                                    stmt.line,
                                    format!(
                                        "Enum variant `{}::{}` has duplicate field `{}`",
                                        name, v.name, f
                                    ),
                                ));
                            }
                        }
                    }
                }
                self.enum_defs.insert(key, variants.clone());
                self.bind_local_type(name);
                Ok(Signal::None)
            }

            StmtKind::ExprStmt(expr) => {
                self.eval_expr(expr)?;
                Ok(Signal::None)
            }
        }
    }

    /// Execute a `use` statement.
    ///
    /// Four shapes are dispatched from the parser:
    ///
    /// - `use foo`                 — glob: inject all public
    ///   (non-`_`-prefixed) exports into the caller's scope.
    ///   Name collisions emit a `BopWarning` and the first
    ///   binding wins (already-present beats newcomer).
    /// - `use foo.{a, b}`          — selective: inject only the
    ///   listed names. Missing names raise a clear error. Names
    ///   that start with `_` are accepted when listed
    ///   explicitly (the selective form is how you opt-in to
    ///   private bindings).
    /// - `use foo as m`            — aliased: every export
    ///   (including `_`-prefixed) hangs off a `Value::Module`
    ///   bound as `m`. Access via `m.binding` or
    ///   `m.Type { ... }` / `m.Type::Variant(...)`.
    /// - `use foo.{a, b} as m`     — selective + aliased: same
    ///   filtering, and the resulting module only exposes the
    ///   listed names.
    ///
    /// Struct / enum / method declarations from the imported
    /// module still register globally on every form — types
    /// are first-come-first-served across the engine. Conflicts
    /// there produce the same "clashes with existing" error as
    /// before. (Qualified type names that genuinely disambiguate
    /// same-named types across modules are a future extension.)
    fn exec_import(
        &mut self,
        path: &str,
        items: Option<&[String]>,
        alias: Option<&str>,
        line: u32,
    ) -> Result<(), BopError> {
        // Idempotent at the glob injection site: re-importing a
        // module already applied is a no-op. Aliased / selective
        // forms don't enter this cache — they always run, because
        // the same module imported with different shapes can
        // legitimately produce different scope effects.
        let is_plain_glob = items.is_none() && alias.is_none();
        if is_plain_glob && self.imported_here.contains(path) {
            return Ok(());
        }

        let bindings = self.load_module(path, line)?;

        // Types always register under their *full identity*
        // `(module_path, type_name)`. That means two modules
        // declaring `struct Color { ... }` with different fields
        // coexist at different registry keys — no clash. Same-
        // identity reinsertion is a no-op; same key + different
        // shape would mean the same module got loaded twice with
        // a different source, which we treat as a hard error.
        for (key, fields) in &bindings.struct_defs {
            if let Some(existing) = self.struct_defs.get(key) {
                if existing == fields {
                    continue;
                }
                return Err(error(
                    line,
                    format!(
                        "Type `{}` from `{}` reloaded with different fields",
                        key.1, key.0
                    ),
                ));
            }
            self.struct_defs.insert(key.clone(), fields.clone());
        }
        for (key, variants) in &bindings.enum_defs {
            if let Some(existing) = self.enum_defs.get(key) {
                if variants_equivalent(existing, variants) {
                    continue;
                }
                return Err(error(
                    line,
                    format!(
                        "Type `{}` from `{}` reloaded with different variants",
                        key.1, key.0
                    ),
                ));
            }
            self.enum_defs.insert(key.clone(), variants.clone());
        }
        for (type_key, method_name, fn_def) in &bindings.methods {
            let slot = self.methods.entry(type_key.clone()).or_default();
            slot.insert(method_name.clone(), fn_def.clone());
        }

        // Figure out which name-value pairs to surface based on
        // the (items, alias) combination. Fn declarations and
        // plain `let` bindings are threaded together so the
        // caller-visible order matches the module's declaration
        // order.
        let mut exports: Vec<(String, Value)> =
            Vec::with_capacity(bindings.fn_decls.len() + bindings.bindings.len());
        let mut fn_entries: Vec<(String, FnDef)> =
            Vec::with_capacity(bindings.fn_decls.len());
        for (name, fn_def) in &bindings.fn_decls {
            let value = Value::new_fn(
                fn_def.params.clone(),
                Vec::new(),
                fn_def.body.clone(),
                Some(name.clone()),
            );
            exports.push((name.clone(), value));
            fn_entries.push((name.clone(), fn_def.clone()));
        }
        for (name, value) in &bindings.bindings {
            exports.push((name.clone(), value.clone()));
        }

        // Selective filter: restrict to the listed names.
        // Missing names error loudly — a silent skip would make
        // typos hard to spot.
        if let Some(list) = items {
            let available: alloc_import::collections::BTreeSet<&str> =
                exports.iter().map(|(k, _)| k.as_str()).collect();
            for wanted in list {
                if !available.contains(wanted.as_str())
                    && !bindings
                        .struct_defs
                        .iter()
                        .any(|((_, n), _)| n == wanted)
                    && !bindings
                        .enum_defs
                        .iter()
                        .any(|((_, n), _)| n == wanted)
                {
                    return Err(error(
                        line,
                        format!(
                            "`{}` isn't exported from `{}` (selective import)",
                            wanted, path
                        ),
                    ));
                }
            }
            let listed: alloc_import::collections::BTreeSet<String> =
                list.iter().cloned().collect();
            exports.retain(|(k, _)| listed.contains(k));
            fn_entries.retain(|(k, _)| listed.contains(k));
        }

        // Figure out which of the module's types the caller
        // should see *by bare name*. The selective form picks
        // exactly the listed names; the glob form takes
        // everything public; the aliased form never binds bare
        // names (the alias is the only way in).
        let module_type_names: Vec<String> = bindings
            .struct_defs
            .iter()
            .map(|((_, n), _)| n.clone())
            .chain(bindings.enum_defs.iter().map(|((_, n), _)| n.clone()))
            .collect();
        let exposed_types: Vec<String> = match items {
            Some(list) => module_type_names
                .into_iter()
                .filter(|n| list.iter().any(|i| i == n))
                .collect(),
            None => module_type_names
                .into_iter()
                .filter(|n| !crate::naming::is_private(n))
                .collect(),
        };

        if let Some(alias_name) = alias {
            // Aliased form: build a `Value::Module` and bind it
            // under the alias. The module carries its bindings
            // (let + fn) and the names of declared types so
            // namespaced constructors like `m.Entity { ... }`
            // can verify they're reaching for something the
            // module actually exports.
            if self
                .scopes
                .last()
                .map(|s| s.contains_key(alias_name))
                .unwrap_or(false)
                || self.functions.contains_key(alias_name)
            {
                return Err(error(
                    line,
                    format!(
                        "`{}` is already bound — can't use it as a module alias",
                        alias_name
                    ),
                ));
            }
            // Fn entries imported via alias also register in
            // `self.functions` so `m.foo()` (which lowers to
            // `Value::Fn` lookup in the module) and `foo()`
            // (bare call, never reaches the alias) stay
            // consistent when the module itself has sibling fn
            // calls inside its own body. Selective + alias:
            // only the listed fns register.
            for (name, fn_def) in fn_entries {
                if !self.functions.contains_key(&name) {
                    self.functions.insert(name, fn_def);
                }
            }
            let module_rc = Rc::new(crate::value::BopModule {
                path: path.to_string(),
                bindings: exports,
                types: exposed_types,
            });
            // Bind the alias three ways:
            //   1. as a Value::Module in the current value
            //      scope (for `m.helper(x)` style calls that
            //      happen directly at the callsite);
            //   2. in `module_aliases` so it survives the
            //      fresh-scope reset at function boundaries and
            //      stays reachable for field access inside fns;
            //   3. in `type_bindings` so patterns + construction
            //      can resolve `m.Type` inside function bodies
            //      without needing the Value::Module in value
            //      scope.
            self.define(
                alias_name.to_string(),
                Value::Module(Rc::clone(&module_rc)),
            );
            self.module_aliases
                .insert(alias_name.to_string(), Rc::clone(&module_rc));
            if let Some(scope) = self.type_bindings.last_mut() {
                scope.insert(alias_name.to_string(), path.to_string());
            }
        } else {
            // Glob / selective without alias — flat injection.
            // Privacy: glob-only drops `_`-prefixed names.
            // Selective lets the user reach into private
            // bindings explicitly.
            let skip_private = items.is_none();
            for (name, fn_def) in fn_entries {
                if skip_private && crate::naming::is_private(&name) {
                    continue;
                }
                if self
                    .scopes
                    .last()
                    .map(|s| s.contains_key(&name))
                    .unwrap_or(false)
                    || self.functions.contains_key(&name)
                {
                    self.runtime_warnings.push(crate::error::BopWarning::at(
                        format!(
                            "`{}` from `{}` shadowed by an existing binding — the first definition wins",
                            name, path
                        ),
                        line,
                    ));
                    continue;
                }
                self.functions.insert(name, fn_def);
            }
            for (name, value) in exports {
                if skip_private && crate::naming::is_private(&name) {
                    continue;
                }
                if self
                    .scopes
                    .last()
                    .map(|s| s.contains_key(&name))
                    .unwrap_or(false)
                {
                    self.runtime_warnings.push(crate::error::BopWarning::at(
                        format!(
                            "`{}` from `{}` shadowed by an existing binding — the first definition wins",
                            name, path
                        ),
                        line,
                    ));
                    continue;
                }
                self.define(name, value);
            }
            // Bind the bare type names in the current scope's
            // type_bindings so subsequent `Color::Red` /
            // `Color { ... }` resolves to the module the name
            // came from. Shadowing here is silent (same as
            // values): first definition wins. Types without an
            // explicit bare binding remain reachable through
            // the alias form only.
            for tn in &exposed_types {
                let already_bound = self
                    .type_bindings
                    .last()
                    .map(|s| s.contains_key(tn))
                    .unwrap_or(false);
                if already_bound {
                    continue;
                }
                if let Some(scope) = self.type_bindings.last_mut() {
                    scope.insert(tn.clone(), path.to_string());
                }
            }
        }

        if is_plain_glob {
            self.imported_here.insert(path.to_string());
        }
        Ok(())
    }

    /// Resolve and evaluate a module, caching the result. Returns
    /// the module's exported bindings.
    fn load_module(&mut self, path: &str, line: u32) -> Result<ModuleBindings, BopError> {
        // Fast path: already loaded.
        {
            let cache = self.imports.borrow();
            if let Some(ImportSlot::Loaded(bindings)) = cache.get(path) {
                return Ok(bindings.clone());
            }
            if let Some(ImportSlot::Loading) = cache.get(path) {
                return Err(error(
                    line,
                    format!("Circular import: module `{}` is still loading", path),
                ));
            }
        }

        // Ask the host for source.
        let source = match self.host.resolve_module(path) {
            Some(Ok(s)) => s,
            Some(Err(e)) => return Err(e),
            None => {
                return Err(error(
                    line,
                    format!("Module `{}` not found", path),
                ));
            }
        };

        // Mark in-progress before we start evaluating so a
        // circular import surfaces as a clean error.
        self.imports
            .borrow_mut()
            .insert(path.to_string(), ImportSlot::Loading);

        let result = self.evaluate_module(path, &source, line);

        match result {
            Ok(bindings) => {
                self.imports
                    .borrow_mut()
                    .insert(path.to_string(), ImportSlot::Loaded(bindings.clone()));
                Ok(bindings)
            }
            Err(e) => {
                // Drop the Loading marker so a subsequent, non-
                // broken context could retry.
                self.imports.borrow_mut().remove(path);
                Err(e)
            }
        }
    }

    /// Parse and walk a module source in a fresh scope, returning
    /// its top-level bindings as a `ModuleBindings`. Reuses the
    /// parent evaluator's host, limits, and import cache.
    /// `module_path` is the dot-joined name the importer used —
    /// the sub-evaluator tags its own declared types with this
    /// path so runtime values keep a stable identity across the
    /// import boundary.
    fn evaluate_module(
        &mut self,
        module_path: &str,
        source: &str,
        line: u32,
    ) -> Result<ModuleBindings, BopError> {
        let _ = line;
        let stmts = crate::parse(source)?;
        let imports = Rc::clone(&self.imports);
        let limits = self.limits.clone();
        let mut sub = Evaluator::new_for_module(
            self.host,
            limits,
            imports,
            module_path.to_string(),
        );
        // Run the module body to top — errors propagate as-is.
        match sub.exec_block(&stmts)? {
            Signal::Return(_) | Signal::None => {}
            Signal::Break => {
                return Err(error(0, "break used outside of a loop"));
            }
            Signal::Continue => {
                return Err(error(0, "continue used outside of a loop"));
            }
        }
        // Collect top-level `let` bindings from the module's
        // one remaining scope. Fns are handled separately so
        // the importer can register them in `self.functions`
        // as well as in the scope (see `exec_import`).
        let mut bindings: Vec<(String, Value)> = Vec::new();
        if let Some(top_scope) = sub.scopes.into_iter().next() {
            for (k, v) in top_scope {
                bindings.push((k, v));
            }
        }
        let fn_decls: Vec<(String, FnDef)> =
            sub.functions.into_iter().collect();
        // Type decls and methods transfer with their full
        // identity. Engine builtins (`<builtin>` module path)
        // are seeded into every evaluator anyway, so we filter
        // those out here to avoid duplicating them in the
        // importer's merge step.
        let builtin_mp = crate::value::BUILTIN_MODULE_PATH;
        let struct_defs: Vec<((String, String), Vec<String>)> = sub
            .struct_defs
            .into_iter()
            .filter(|((mp, _), _)| mp != builtin_mp)
            .collect();
        let enum_defs: Vec<((String, String), Vec<crate::parser::VariantDecl>)> = sub
            .enum_defs
            .into_iter()
            .filter(|((mp, _), _)| mp != builtin_mp)
            .collect();
        let mut methods: Vec<((String, String), String, FnDef)> = Vec::new();
        for (type_key, by_method) in sub.methods {
            for (method_name, fn_def) in by_method {
                methods.push((type_key.clone(), method_name, fn_def));
            }
        }
        Ok(ModuleBindings {
            bindings,
            fn_decls,
            struct_defs,
            enum_defs,
            methods,
        })
    }

    /// Validate `ns.Type` — the caller wrote `ns.Type { ... }`
    /// or `ns.Type::Variant(...)`. `ns` must be a
    /// `Value::Module` in scope, and `Type` must appear in that
    /// module's list of exported type names. The return is
    /// `Ok(())` for now because types still register under their
    /// bare names globally; once qualified type names land, this
    /// is where we translate `ns.Type` into its qualified form.
    fn validate_namespaced_type(
        &self,
        ns: &str,
        type_name: &str,
        line: u32,
    ) -> Result<(), BopError> {
        // Prefer the local value scope so a shadowing binding
        // (`let p = 3` after `use paint as p`) is caught — but
        // fall back to the evaluator-level alias map so
        // namespaced references inside function bodies still
        // resolve.
        if let Some(v) = self.get_var(ns) {
            let module = match v {
                Value::Module(m) => m,
                _ => {
                    return Err(error(
                        line,
                        format!(
                            "`{}` is a {}, not a module alias — can't reach `{}` through it",
                            ns,
                            v.type_name(),
                            type_name
                        ),
                    ));
                }
            };
            if !module.types.iter().any(|t| t == type_name) {
                return Err(error(
                    line,
                    format!(
                        "`{}` isn't a type exported from `{}`",
                        type_name, module.path
                    ),
                ));
            }
            return Ok(());
        }
        if let Some(module) = self.module_aliases.get(ns) {
            if !module.types.iter().any(|t| t == type_name) {
                return Err(error(
                    line,
                    format!(
                        "`{}` isn't a type exported from `{}`",
                        type_name, module.path
                    ),
                ));
            }
            return Ok(());
        }
        Err(error(
            line,
            format!("`{}` isn't a module alias in scope", ns),
        ))
    }

    fn eval_enum_construct(
        &mut self,
        namespace: Option<&str>,
        type_name: &str,
        variant: &str,
        payload: &VariantPayload,
        line: u32,
    ) -> Result<Value, BopError> {
        // Resolve the type reference to its full
        // `(module_path, type_name)` identity before validating
        // the variant shape. `namespace` means the source wrote
        // `ns.Type::Variant(...)`; bare means we look the name up
        // in the current scope's type bindings.
        let module_path = match namespace {
            Some(ns) => {
                self.validate_namespaced_type(ns, type_name, line)?;
                // validate_namespaced_type guaranteed the alias
                // is a Module and the type is in its exports —
                // pick up the module path for the full identity.
                self.resolve_type_ref(Some(ns), type_name)
                    .unwrap_or_else(|| self.current_module.clone())
            }
            None => self
                .resolve_type_ref(None, type_name)
                .ok_or_else(|| {
                    error(line, crate::error_messages::enum_not_declared(type_name))
                })?,
        };
        let key = (module_path.clone(), type_name.to_string());
        let variants = self.enum_defs.get(&key).ok_or_else(|| {
            error(line, crate::error_messages::enum_not_declared(type_name))
        })?
        .clone();
        let decl = variants.iter().find(|v| v.name == variant).ok_or_else(|| {
            let msg = crate::error_messages::enum_has_no_variant(type_name, variant);
            let names = variants.iter().map(|v| v.name.as_str());
            match crate::suggest::did_you_mean(variant, names) {
                Some(hint) => error_with_hint(line, msg, hint),
                None => error(line, msg),
            }
        })?
        .clone();

        match (&decl.kind, payload) {
            (VariantKind::Unit, VariantPayload::Unit) => Ok(Value::new_enum_unit(
                module_path,
                type_name.to_string(),
                variant.to_string(),
            )),
            (VariantKind::Tuple(fields), VariantPayload::Tuple(args)) => {
                if args.len() != fields.len() {
                    return Err(error(
                        line,
                        format!(
                            "`{}::{}` expects {} argument{}, but got {}",
                            type_name,
                            variant,
                            fields.len(),
                            if fields.len() == 1 { "" } else { "s" },
                            args.len()
                        ),
                    ));
                }
                let mut items = Vec::with_capacity(args.len());
                for arg in args {
                    items.push(self.eval_expr(arg)?);
                }
                Ok(Value::new_enum_tuple(
                    module_path,
                    type_name.to_string(),
                    variant.to_string(),
                    items,
                ))
            }
            (VariantKind::Struct(decl_fields), VariantPayload::Struct(provided)) => {
                let mut seen = alloc_import::collections::BTreeSet::new();
                let mut provided_map: BTreeMap<String, Value> = BTreeMap::new();
                for (fname, fexpr) in provided {
                    if !seen.insert(fname.clone()) {
                        return Err(error(
                            line,
                            format!(
                                "Field `{}` specified twice in `{}::{}`",
                                fname, type_name, variant
                            ),
                        ));
                    }
                    if !decl_fields.iter().any(|d| d == fname) {
                        return Err(error(
                            line,
                            crate::error_messages::variant_has_no_field(
                                type_name, variant, fname,
                            ),
                        ));
                    }
                    provided_map.insert(fname.clone(), self.eval_expr(fexpr)?);
                }
                let mut values: Vec<(String, Value)> =
                    Vec::with_capacity(decl_fields.len());
                for decl_field in decl_fields {
                    match provided_map.remove(decl_field) {
                        Some(v) => values.push((decl_field.clone(), v)),
                        None => {
                            return Err(error(
                                line,
                                format!(
                                    "Missing field `{}` in `{}::{}` construction",
                                    decl_field, type_name, variant
                                ),
                            ));
                        }
                    }
                }
                Ok(Value::new_enum_struct(
                    module_path,
                    type_name.to_string(),
                    variant.to_string(),
                    values,
                ))
            }
            (VariantKind::Unit, _) => Err(error(
                line,
                format!(
                    "Variant `{}::{}` takes no payload",
                    type_name, variant
                ),
            )),
            (VariantKind::Tuple(_), _) => Err(error(
                line,
                format!(
                    "Variant `{}::{}` expects positional arguments `(…)`",
                    type_name, variant
                ),
            )),
            (VariantKind::Struct(_), _) => Err(error(
                line,
                format!(
                    "Variant `{}::{}` expects named fields `{{ … }}`",
                    type_name, variant
                ),
            )),
        }
    }

    fn exec_assign(
        &mut self,
        target: &AssignTarget,
        op: &AssignOp,
        new_val: Value,
        line: u32,
    ) -> Result<(), BopError> {
        match target {
            AssignTarget::Variable(name) => {
                let final_val = match op {
                    AssignOp::Eq => new_val,
                    _ => {
                        let current = self
                            .get_var(name)
                            .ok_or_else(|| {
                                error(line, format!("Variable `{}` doesn't exist yet", name))
                            })?
                            .clone();
                        self.apply_compound_op(&current, op, &new_val, line)?
                    }
                };
                if !self.set_var(name, final_val) {
                    return Err(error_with_hint(
                        line,
                        format!("Variable `{}` doesn't exist yet", name),
                        format!("Use `let` to create a new variable: let {} = ...", name),
                    ));
                }
                Ok(())
            }
            AssignTarget::Index { object, index } => {
                let idx = self.eval_expr(index)?;
                let val_to_set = match op {
                    AssignOp::Eq => new_val,
                    _ => {
                        let obj = self.eval_expr(object)?;
                        let current = ops::index_get(&obj, &idx, line)?;
                        self.apply_compound_op(&current, op, &new_val, line)?
                    }
                };
                if let ExprKind::Ident(name) = &object.kind {
                    let mut obj = self
                        .get_var(name)
                        .ok_or_else(|| {
                            error(line, format!("Variable `{}` doesn't exist", name))
                        })?
                        .clone();
                    ops::index_set(&mut obj, &idx, val_to_set, line)?;
                    self.set_var(name, obj);
                    Ok(())
                } else {
                    Err(error(
                        line,
                        "Can only assign to indexed variables (like `arr[0] = val`)",
                    ))
                }
            }
            AssignTarget::Field { object, field } => {
                // Support assignment into a named struct field.
                // Only bare-`Ident` objects are assignable — the
                // writeback goes through `set_var`, so chains like
                // `foo().x = 1` or `arr[0].x = 1` aren't
                // supported yet (matches index-assign behaviour).
                let name = match &object.kind {
                    ExprKind::Ident(n) => n.clone(),
                    _ => {
                        return Err(error(
                            line,
                            "Can only assign to fields of named variables (like `p.x = val`)",
                        ));
                    }
                };
                let mut obj = self
                    .get_var(&name)
                    .ok_or_else(|| {
                        error(line, format!("Variable `{}` doesn't exist", name))
                    })?
                    .clone();
                let val_to_set = match op {
                    AssignOp::Eq => new_val,
                    _ => {
                        let current = match &obj {
                            Value::Struct(s) => s.field(field).cloned().ok_or_else(|| {
                                error(
                                    line,
                                    crate::error_messages::struct_has_no_field(
                                        s.type_name(),
                                        field,
                                    ),
                                )
                            })?,
                            other => {
                                return Err(error(
                                    line,
                                    crate::error_messages::cant_assign_field(
                                        field,
                                        other.type_name(),
                                    ),
                                ));
                            }
                        };
                        self.apply_compound_op(&current, op, &new_val, line)?
                    }
                };
                match &mut obj {
                    Value::Struct(s) => {
                        let struct_type = s.type_name().to_string();
                        if !s.set_field(field, val_to_set) {
                            return Err(error(
                                line,
                                crate::error_messages::struct_has_no_field(&struct_type, field),
                            ));
                        }
                    }
                    other => {
                        return Err(error(
                            line,
                            crate::error_messages::cant_assign_field(
                                field,
                                other.type_name(),
                            ),
                        ));
                    }
                }
                self.set_var(&name, obj);
                Ok(())
            }
        }
    }

    fn apply_compound_op(
        &self,
        left: &Value,
        op: &AssignOp,
        right: &Value,
        line: u32,
    ) -> Result<Value, BopError> {
        match op {
            AssignOp::Eq => Ok(right.clone()),
            AssignOp::AddEq => ops::add(left, right, line),
            AssignOp::SubEq => ops::sub(left, right, line),
            AssignOp::MulEq => ops::mul(left, right, line),
            AssignOp::DivEq => ops::div(left, right, line),
            AssignOp::ModEq => ops::rem(left, right, line),
        }
    }

    // ─── Expressions ───────────────────────────────────────────────

    fn eval_expr(&mut self, expr: &Expr) -> Result<Value, BopError> {
        match &expr.kind {
            ExprKind::Int(n) => Ok(Value::Int(*n)),
            ExprKind::Number(n) => Ok(Value::Number(*n)),
            ExprKind::Str(s) => Ok(Value::new_str(s.clone())),
            ExprKind::Bool(b) => Ok(Value::Bool(*b)),
            ExprKind::None => Ok(Value::None),

            ExprKind::StringInterp(parts) => {
                let mut result = String::new();
                for part in parts {
                    match part {
                        StringPart::Literal(s) => result.push_str(s),
                        StringPart::Variable(name) => {
                            let val = self
                                .get_var(name)
                                .ok_or_else(|| {
                                    error_at(expr.line, expr.column, crate::error_messages::variable_not_found(name))
                                })?
                                .clone();
                            result.push_str(&format!("{}", val));
                        }
                    }
                }
                Ok(Value::new_str(result))
            }

            ExprKind::Ident(name) => {
                // Lexical lookup first — matches the intuition that
                // `let x = ...` locally shadows everything else.
                if let Some(v) = self.get_var(name) {
                    return Ok(v.clone());
                }
                // Fall back to named `fn` declarations so they can
                // be passed around as first-class values. The
                // synthesised `Value::Fn` carries `self_name` so
                // recursive lookups inside the body still resolve
                // through `self.functions` (see `call_bop_fn`).
                if let Some(f) = self.functions.get(name) {
                    return Ok(Value::new_fn(
                        f.params.clone(),
                        Vec::new(),
                        f.body.clone(),
                        Some(name.to_string()),
                    ));
                }
                // Typo? Offer a "did you mean" hint if something
                // close is visible in the current scope / fn
                // registry. Falls back to the original "did you
                // forget `let`" when no candidate is similar
                // enough.
                let hint = self
                    .value_candidates_hint(name)
                    .unwrap_or_else(|| "Did you forget to create it with `let`?".to_string());
                Err(error_with_hint_at(
                    expr.line,
                    expr.column,
                    crate::error_messages::variable_not_found(name),
                    hint,
                ))
            }

            ExprKind::BinaryOp { left, op, right } => {
                // Short-circuit for && and ||
                if matches!(op, BinOp::And) {
                    let lval = self.eval_expr(left)?;
                    if !lval.is_truthy() {
                        return Ok(Value::Bool(false));
                    }
                    let rval = self.eval_expr(right)?;
                    return Ok(Value::Bool(rval.is_truthy()));
                }
                if matches!(op, BinOp::Or) {
                    let lval = self.eval_expr(left)?;
                    if lval.is_truthy() {
                        return Ok(Value::Bool(true));
                    }
                    let rval = self.eval_expr(right)?;
                    return Ok(Value::Bool(rval.is_truthy()));
                }

                let lval = self.eval_expr(left)?;
                let rval = self.eval_expr(right)?;
                self.binary_op(&lval, op, &rval, expr.line)
            }

            ExprKind::UnaryOp { op, expr: inner } => {
                let val = self.eval_expr(inner)?;
                match op {
                    UnaryOp::Neg => ops::neg(&val, expr.line),
                    UnaryOp::Not => Ok(ops::not(&val)),
                }
            }

            ExprKind::Call { callee, args } => {
                let mut eval_args = Vec::new();
                for arg in args {
                    eval_args.push(self.eval_expr(arg)?);
                }
                if let ExprKind::Ident(name) = &callee.kind {
                    // Lexical callable first: if the name is bound
                    // to a `Value::Fn` in the current scope, call
                    // it. A bound non-callable is an explicit
                    // error — "shadowing a builtin with a number
                    // then calling it" should fail loudly, not
                    // silently dispatch to the builtin.
                    if let Some(v) = self.get_var(name).cloned() {
                        return self.call_value(v, eval_args, expr.line, Some(name));
                    }
                    // Otherwise fall through to the original
                    // name-based dispatch (builtins → host → named
                    // fns). This is what keeps `print(x)` /
                    // `range(n)` / `my_user_fn(x)` working.
                    return self.call_function(name, eval_args, expr.line);
                }
                // Non-Ident callee: evaluate the expression; it
                // must produce a `Value::Fn`.
                let callee_val = self.eval_expr(callee)?;
                self.call_value(callee_val, eval_args, expr.line, None)
            }

            ExprKind::Lambda { params, body } => {
                let captures = self.snapshot_captures();
                Ok(Value::new_fn(
                    params.clone(),
                    captures,
                    body.clone(),
                    None,
                ))
            }

            ExprKind::MethodCall {
                object,
                method,
                args,
            } => {
                let mut eval_args = Vec::new();
                for arg in args {
                    eval_args.push(self.eval_expr(arg)?);
                }
                let obj_val = self.eval_expr(object)?;

                // `m.foo(args)` on a module alias: this parsed as
                // a `MethodCall`, but there's no struct/enum
                // receiver — `m` is a `Value::Module` whose
                // `foo` export is a callable value. Look it up,
                // then treat the result as a regular value call.
                //
                // The common methods (`type`, `to_str`,
                // `inspect`) still win over export lookup, so
                // `m.type()` returns `"module"` instead of
                // complaining that `type` isn't exported.
                if let Value::Module(m) = &obj_val {
                    if let Some(result) =
                        methods::common_method(&obj_val, method, &eval_args, expr.line)?
                    {
                        return Ok(result.0);
                    }
                    if let Some((_, v)) = m.bindings.iter().find(|(k, _)| k == method) {
                        let callee = v.clone();
                        return self.call_value(callee, eval_args, expr.line, Some(method));
                    }
                    return Err(error(
                        expr.line,
                        format!(
                            "`{}` isn't exported from `{}`",
                            method, m.path
                        ),
                    ));
                }

                // User-defined method dispatch comes first — any
                // user method registered against the receiver's
                // *full* type identity `(module_path, type_name)`
                // wins over built-in methods of the same name.
                // Enums dispatch on the enum's type, not the
                // variant's, so all variants of `paint.Shape`
                // share `fn Shape.area(self)` from the paint
                // module. A method declared for `paint.Shape`
                // deliberately does not fire on `other.Shape`.
                let type_key: Option<(String, String)> = match &obj_val {
                    Value::Struct(s) => Some((
                        s.module_path().to_string(),
                        s.type_name().to_string(),
                    )),
                    Value::EnumVariant(e) => Some((
                        e.module_path().to_string(),
                        e.type_name().to_string(),
                    )),
                    _ => None,
                };
                if let Some(key) = type_key {
                    let user = self
                        .methods
                        .get(&key)
                        .and_then(|ms| ms.get(method))
                        .cloned();
                    if let Some(m) = user {
                        if m.params.len() != eval_args.len() + 1 {
                            return Err(error(
                                expr.line,
                                format!(
                                    "`{}.{}` expects {} argument{} (including `self`), but got {}",
                                    key.1,
                                    method,
                                    m.params.len(),
                                    if m.params.len() == 1 { "" } else { "s" },
                                    eval_args.len() + 1
                                ),
                            ));
                        }
                        // Prepend receiver as the first parameter
                        // (`self` by convention).
                        let mut full_args = Vec::with_capacity(eval_args.len() + 1);
                        full_args.push(obj_val);
                        full_args.extend(eval_args);
                        let bop_fn = Rc::new(BopFn {
                            params: m.params,
                            captures: Vec::new(),
                            body: FnBody::Ast(m.body),
                            self_name: None,
                        });
                        return self.call_bop_fn(&bop_fn, full_args, expr.line);
                    }
                }

                // Callable-taking Result methods — `r.map(f)`,
                // `r.map_err(f)`, `r.and_then(f)`. These need the
                // evaluator's call primitive to invoke `f`, which
                // `call_method` doesn't have access to, so they
                // dispatch inline before the pure `call_method`
                // fall-through. Receiver must be the built-in
                // Result; user enums named `Result` don't qualify.
                if methods::is_builtin_result(&obj_val) {
                    if let Some(kind) = methods::is_result_callable_method(method) {
                        return self.call_result_callable_method(
                            &obj_val,
                            kind,
                            method,
                            eval_args,
                            expr.line,
                        );
                    }
                }

                let (ret, mutated) = self.call_method(&obj_val, method, &eval_args, expr.line)?;

                if methods::is_mutating_method(method) {
                    if let ExprKind::Ident(name) = &object.kind {
                        if let Some(new_obj) = mutated {
                            self.set_var(name, new_obj);
                        }
                    }
                }
                Ok(ret)
            }

            ExprKind::Index { object, index } => {
                let obj = self.eval_expr(object)?;
                let idx = self.eval_expr(index)?;
                ops::index_get(&obj, &idx, expr.line)
            }

            ExprKind::FieldAccess { object, field } => {
                let obj = self.eval_expr(object)?;
                match &obj {
                    Value::Struct(s) => s.field(field).cloned().ok_or_else(|| {
                        let msg =
                            crate::error_messages::struct_has_no_field(s.type_name(), field);
                        // Suggest from the struct's own declared
                        // field list — `p.z` when `Point` has `x`
                        // and `y` should point to `x`/`y`.
                        let field_names: Vec<&str> =
                            s.fields().iter().map(|(k, _)| k.as_str()).collect();
                        match crate::suggest::did_you_mean(field, field_names) {
                            Some(hint) => error_with_hint_at(expr.line, expr.column, msg, hint),
                            None => error_at(expr.line, expr.column, msg),
                        }
                    }),
                    Value::EnumVariant(e) => e.field(field).cloned().ok_or_else(|| {
                        error(
                            expr.line,
                            crate::error_messages::variant_has_no_field(
                                e.type_name(),
                                e.variant(),
                                field,
                            ),
                        )
                    }),
                    Value::Module(m) => {
                        // `alias.name` — look up an export in the
                        // aliased module.
                        if let Some((_, v)) = m.bindings.iter().find(|(k, _)| k == field) {
                            return Ok(v.clone());
                        }
                        if m.types.iter().any(|t| t == field) {
                            // Types aren't first-class values; the
                            // parser should have taken the namespaced
                            // struct-lit / variant-ctor path
                            // already. Reaching a FieldAccess here
                            // means the user wrote `m.Type` in a
                            // value-returning position.
                            return Err(error_with_hint(
                                expr.line,
                                format!("`{}` in `{}` is a type, not a value", field, m.path),
                                format!(
                                    "construct through the alias: `{}.{} {{ ... }}` or `{}.{}::Variant(...)`",
                                    m.path.split('.').last().unwrap_or(&m.path),
                                    field,
                                    m.path.split('.').last().unwrap_or(&m.path),
                                    field,
                                ),
                            ));
                        }
                        Err(error(
                            expr.line,
                            format!(
                                "`{}` isn't exported from `{}`",
                                field, m.path
                            ),
                        ))
                    }
                    other => Err(error(
                        expr.line,
                        crate::error_messages::cant_read_field(field, other.type_name()),
                    )),
                }
            }

            ExprKind::EnumConstruct {
                namespace,
                type_name,
                variant,
                payload,
            } => self.eval_enum_construct(
                namespace.as_deref(),
                type_name,
                variant,
                payload,
                expr.line,
            ),

            ExprKind::StructConstruct {
                namespace,
                type_name,
                fields,
            } => {
                let module_path = match namespace {
                    Some(ns) => {
                        self.validate_namespaced_type(ns, type_name, expr.line)?;
                        self.resolve_type_ref(Some(ns), type_name)
                            .unwrap_or_else(|| self.current_module.clone())
                    }
                    None => self
                        .resolve_type_ref(None, type_name)
                        .ok_or_else(|| {
                            error(
                                expr.line,
                                crate::error_messages::struct_not_declared(type_name),
                            )
                        })?,
                };
                let key = (module_path.clone(), type_name.clone());
                let decl_fields = self.struct_defs.get(&key).ok_or_else(|| {
                    error(
                        expr.line,
                        crate::error_messages::struct_not_declared(type_name),
                    )
                })?
                .clone();
                // Enforce exactly-this-field-set at construction:
                // no duplicates, no unknown fields, no missing
                // fields. The per-field loops below produce the
                // specific messages the tests assert on.
                let mut seen = alloc_import::collections::BTreeSet::new();
                let mut values: Vec<(String, Value)> =
                    Vec::with_capacity(decl_fields.len());
                // Evaluate provided fields by name, then emit them
                // in *declaration* order so the `Value::Struct`'s
                // field list is stable across construction sites.
                let mut provided: BTreeMap<String, Value> = BTreeMap::new();
                for (fname, fexpr) in fields {
                    if !seen.insert(fname.clone()) {
                        return Err(error(
                            expr.line,
                            format!(
                                "Field `{}` specified twice in `{}` construction",
                                fname, type_name
                            ),
                        ));
                    }
                    if !decl_fields.iter().any(|d| d == fname) {
                        let msg = crate::error_messages::struct_has_no_field(type_name, fname);
                        let err = match crate::suggest::did_you_mean(
                            fname,
                            decl_fields.iter().map(|s| s.as_str()),
                        ) {
                            Some(hint) => error_with_hint_at(expr.line, expr.column, msg, hint),
                            None => error_at(expr.line, expr.column, msg),
                        };
                        return Err(err);
                    }
                    provided.insert(fname.clone(), self.eval_expr(fexpr)?);
                }
                for decl in &decl_fields {
                    match provided.remove(decl) {
                        Some(v) => values.push((decl.clone(), v)),
                        None => {
                            return Err(error(
                                expr.line,
                                format!(
                                    "Missing field `{}` in `{}` construction",
                                    decl, type_name
                                ),
                            ));
                        }
                    }
                }
                Ok(Value::new_struct(module_path, type_name.clone(), values))
            }

            ExprKind::Array(elements) => {
                let mut items = Vec::new();
                for elem in elements {
                    items.push(self.eval_expr(elem)?);
                }
                Ok(Value::new_array(items))
            }

            ExprKind::Dict(entries) => {
                let mut result = Vec::new();
                for (key, value_expr) in entries {
                    let val = self.eval_expr(value_expr)?;
                    result.push((key.clone(), val));
                }
                Ok(Value::new_dict(result))
            }

            ExprKind::IfExpr {
                condition,
                then_expr,
                else_expr,
            } => {
                if self.eval_expr(condition)?.is_truthy() {
                    self.eval_expr(then_expr)
                } else {
                    self.eval_expr(else_expr)
                }
            }

            ExprKind::Match { scrutinee, arms } => self.eval_match(scrutinee, arms, expr.line),

            ExprKind::Try(inner) => self.eval_try(inner, expr.line),
        }
    }

    /// `try` expression handler. Evaluates the inner expression,
    /// matches the conventional Result-shape (any enum variant
    /// named `Ok` or `Err`), and either unwraps `Ok` or stashes
    /// the `Err` value into `pending_try_return` so the enclosing
    /// `call_bop_fn` can convert it to `Signal::Return`.
    ///
    /// Top-level `try` on `Err` (call_depth == 0) surfaces as a
    /// real runtime error — there's no enclosing fn to return
    /// from, and the roadmap explicitly rejects the idea of
    /// swallowing it silently.
    fn eval_try(&mut self, inner: &Expr, line: u32) -> Result<Value, BopError> {
        let value = self.eval_expr(inner)?;
        // An earlier `try` in `inner` might have already fired —
        // e.g. `try try foo()` — in which case we just keep
        // propagating without poking at the unwound value.
        if self.pending_try_return.is_some() {
            return Ok(Value::None);
        }
        match &value {
            Value::EnumVariant(ev) if ev.variant() == "Ok" => {
                // Extract the single payload for `Ok(v)`, or fall
                // back to `none` for `Ok` used as a unit variant.
                match ev.payload() {
                    EnumPayload::Tuple(items) if items.len() == 1 => Ok(items[0].clone()),
                    EnumPayload::Unit => Ok(Value::None),
                    EnumPayload::Tuple(items) => Err(error(
                        line,
                        format!(
                            "try: Ok variant must carry exactly one value, got {}",
                            items.len()
                        ),
                    )),
                    EnumPayload::Struct(_) => Err(error(
                        line,
                        "try: Ok variant must carry a single positional value, not named fields",
                    )),
                }
            }
            Value::EnumVariant(ev) if ev.variant() == "Err" => {
                if self.call_depth == 0 {
                    return Err(error_with_hint(
                        line,
                        "try encountered Err at top-level",
                        "Wrap the calling code in a fn, or use `match` to handle both arms explicitly.",
                    ));
                }
                self.pending_try_return = Some(value);
                // Sentinel error whose only job is to unwind up
                // to the nearest `call_bop_fn`, which converts
                // it back into a `Signal::Return`. The `is_try_return`
                // flag on `BopError` is the only thing that
                // matters — line is kept for debug clarity;
                // message is unused.
                Err(BopError::try_return_signal(line))
            }
            other => Err(error(
                line,
                format!(
                    "try expected a Result-shaped value (Ok/Err variant), got {}",
                    other.type_name()
                ),
            )),
        }
    }

    fn eval_match(
        &mut self,
        scrutinee: &Expr,
        arms: &[MatchArm],
        line: u32,
    ) -> Result<Value, BopError> {
        let value = self.eval_expr(scrutinee)?;
        for arm in arms {
            let mut bindings: Vec<(String, Value)> = Vec::new();
            // Resolve patterns' type references through the
            // walker's current scope. Capturing the three scope
            // tables as immutable slices / refs keeps the
            // closure free of the mutable-self borrow we need
            // right after for `push_scope` + binding injection.
            let scopes = &self.scopes;
            let type_bindings = &self.type_bindings;
            let module_aliases = &self.module_aliases;
            let resolver = |ns: Option<&str>, tn: &str| -> Option<String> {
                resolve_type_in(scopes, type_bindings, module_aliases, ns, tn)
            };
            if !pattern_matches(&arm.pattern, &value, &mut bindings, &resolver) {
                continue;
            }
            // Pattern matched — open a fresh scope, bind every
            // captured name, evaluate the guard (in that scope).
            self.push_scope();
            for (name, v) in bindings {
                self.define(name, v);
            }
            let guard_ok = match &arm.guard {
                Some(g) => self.eval_expr(g)?.is_truthy(),
                None => true,
            };
            if !guard_ok {
                self.pop_scope();
                continue;
            }
            let result = self.eval_expr(&arm.body);
            self.pop_scope();
            return result;
        }
        Err(error(
            line,
            "No match arm matched the scrutinee",
        ))
    }

    // ─── Binary operations ─────────────────────────────────────────

    fn binary_op(
        &self,
        left: &Value,
        op: &BinOp,
        right: &Value,
        line: u32,
    ) -> Result<Value, BopError> {
        match op {
            BinOp::Add => ops::add(left, right, line),
            BinOp::Sub => ops::sub(left, right, line),
            BinOp::Mul => ops::mul(left, right, line),
            BinOp::Div => ops::div(left, right, line),
            BinOp::Mod => ops::rem(left, right, line),
            BinOp::Eq => Ok(ops::eq(left, right)),
            BinOp::NotEq => Ok(ops::not_eq(left, right)),
            BinOp::Lt => ops::lt(left, right, line),
            BinOp::Gt => ops::gt(left, right, line),
            BinOp::LtEq => ops::lt_eq(left, right, line),
            BinOp::GtEq => ops::gt_eq(left, right, line),
            BinOp::And | BinOp::Or => unreachable!("handled in eval_expr"),
        }
    }

    // ─── Function calls ────────────────────────────────────────────

    /// Collapse the current scope stack into a flat list of
    /// `(name, value)` pairs — the snapshot used as a lambda's
    /// captures. Inner scopes shadow outer ones, so the resulting
    /// list is deduplicated by name with the innermost binding
    /// winning.
    fn snapshot_captures(&self) -> Vec<(String, Value)> {
        let mut flat = BTreeMap::new();
        for scope in &self.scopes {
            for (k, v) in scope {
                flat.insert(k.clone(), v.clone());
            }
        }
        flat.into_iter().collect()
    }

    /// Call a value directly. Non-`Value::Fn` payloads are an
    /// explicit "not callable" error — this is the safety net for
    /// `let x = 5; x(1)` and friends.
    ///
    /// `name_hint` is the Ident text when the callee was a bare
    /// name, used only for error messages. Non-Ident callees pass
    /// `None`.
    fn call_value(
        &mut self,
        callee: Value,
        args: Vec<Value>,
        line: u32,
        name_hint: Option<&str>,
    ) -> Result<Value, BopError> {
        match &callee {
            Value::Fn(f) => {
                let f = Rc::clone(f);
                drop(callee);
                self.call_bop_fn(&f, args, line)
            }
            other => match name_hint {
                Some(n) => Err(error(
                    line,
                    format!(
                        "`{}` is a {}, not a function",
                        n,
                        other.type_name()
                    ),
                )),
                None => Err(error(
                    line,
                    crate::error_messages::cant_call_a(other.type_name()),
                )),
            },
        }
    }

    /// Shared call path for every `Value::Fn` — the body of both
    /// `let f = fn(...) {...}; f(x)` and the reified version of
    /// `fn name(...) {...}; name(x)` come through here.
    fn call_bop_fn(
        &mut self,
        func: &Rc<BopFn>,
        args: Vec<Value>,
        line: u32,
    ) -> Result<Value, BopError> {
        let body = match &func.body {
            FnBody::Ast(stmts) => stmts,
            FnBody::Compiled(_) => {
                return Err(error(
                    line,
                    "This function was compiled for another engine and can't be run in the tree-walker",
                ));
            }
        };
        if args.len() != func.params.len() {
            let name = func.self_name.as_deref().unwrap_or("fn");
            return Err(error(
                line,
                format!(
                    "`{}` expects {} argument{}, but got {}",
                    name,
                    func.params.len(),
                    if func.params.len() == 1 { "" } else { "s" },
                    args.len()
                ),
            ));
        }

        if self.call_depth >= MAX_CALL_DEPTH {
            return Err(error_with_hint(
                line,
                "Too many nested function calls (possible infinite recursion)",
                "Check that your recursive function has a base case that stops calling itself.",
            ));
        }

        // A function call gets a fresh scope stack: no outer
        // locals leak in. Captures and parameters seed the new
        // scope; self-reference via `self_name` lets recursive
        // lambdas see themselves.
        //
        // `type_bindings` is NOT reset — types and module
        // aliases declared at module scope need to be visible
        // inside nested fn bodies for construction + pattern
        // matching to work. We push a fresh frame so any
        // type decl inside the fn body still ends up scoped to
        // that fn and vanishes on return.
        self.call_depth += 1;
        let saved_scopes = core::mem::replace(&mut self.scopes, vec![BTreeMap::new()]);
        self.type_bindings.push(BTreeMap::new());

        // Captures go in first so parameters shadow them on
        // collision (matches the lexical snapshot semantics).
        for (name, value) in &func.captures {
            self.define(name.clone(), value.clone());
        }
        if let Some(self_name) = &func.self_name {
            // Make the reified `fn name` value visible inside its
            // own body so `fn fib(n) { return fib(n-1) ... }`
            // works without a special "named fn" path.
            self.define(self_name.clone(), Value::Fn(Rc::clone(func)));
        }
        for (param, arg) in func.params.iter().zip(args) {
            self.define(param.clone(), arg);
        }

        let result = self.exec_block(body);
        self.scopes = saved_scopes;
        self.type_bindings.pop();
        self.call_depth -= 1;

        // `try` unwinds as a sentinel `BopError`; the call
        // boundary trades that error for the stashed value and
        // treats it as a normal return. Any other error
        // propagates as usual. Always clears
        // `pending_try_return` so a leftover can't contaminate
        // a later call.
        match result {
            Ok(sig) => match sig {
                Signal::Return(val) => Ok(val),
                Signal::Break => Err(error(line, "break used outside of a loop")),
                Signal::Continue => Err(error(line, "continue used outside of a loop")),
                Signal::None => Ok(Value::None),
            },
            Err(err) => {
                // Check the dedicated `is_try_return` flag
                // instead of inspecting the message — a flag
                // can't collide with a user-authored error
                // that happens to spell the same bytes.
                if err.is_try_return {
                    if let Some(val) = self.pending_try_return.take() {
                        return Ok(val);
                    }
                }
                Err(err)
            }
        }
    }

    /// Implement the `try_call(f)` builtin.
    ///
    /// Takes a zero-arg callable `f` and invokes it. On a clean
    /// return, yields `Result::Ok(value)`. On a **non-fatal**
    /// `BopError`, yields `Result::Err(RuntimeError { message,
    /// line })` — both values are constructed directly by
    /// `bop::builtins::make_try_call_ok` / `_err`, so they
    /// work even in programs that never declared `Result` or
    /// `RuntimeError` themselves.
    ///
    /// Fatal errors (resource-limit violations — see
    /// `BopError::is_fatal`) bypass the wrap and propagate
    /// unchanged, preserving the sandbox invariant.
    fn builtin_try_call(
        &mut self,
        args: Vec<Value>,
        line: u32,
    ) -> Result<Value, BopError> {
        if args.len() != 1 {
            return Err(error(
                line,
                format!(
                    "`try_call` expects 1 argument, but got {}",
                    args.len()
                ),
            ));
        }
        let callable = args.into_iter().next().unwrap();
        let func = match &callable {
            Value::Fn(f) => Rc::clone(f),
            other => {
                return Err(error(
                    line,
                    format!(
                        "`try_call` expects a function, got {}",
                        other.type_name()
                    ),
                ));
            }
        };
        drop(callable);
        match self.call_bop_fn(&func, Vec::new(), line) {
            Ok(value) => Ok(builtins::make_try_call_ok(value)),
            Err(err) => {
                if err.is_fatal {
                    Err(err)
                } else {
                    Ok(builtins::make_try_call_err(&err))
                }
            }
        }
    }

    fn call_function(
        &mut self,
        name: &str,
        args: Vec<Value>,
        line: u32,
    ) -> Result<Value, BopError> {
        // 1. Global builtins. The short list: anything variadic
        // (`print`), a collection constructor (`range`), session-
        // stateful (`rand`), or inherently takes a callable
        // (`try_call`). Every other global builtin that used to
        // live here is now a method on the receiver's type —
        // see `methods::common_method` and `methods::numeric_method`.
        match name {
            "range" => return builtins::builtin_range(&args, line, &mut self.rand_state),
            "rand" => return builtins::builtin_rand(&args, line, &mut self.rand_state),
            "print" => {
                let message = args
                    .iter()
                    .map(|a| format!("{}", a))
                    .collect::<Vec<_>>()
                    .join(" ");
                self.host.on_print(&message);
                return Ok(Value::None);
            }
            "try_call" => return self.builtin_try_call(args, line),
            "panic" => return builtins::builtin_panic(&args, line),
            _ => {}
        }

        // 2. Host-provided builtins
        if let Some(result) = self.host.call(name, &args, line) {
            return result;
        }

        // 3. User-defined functions — synthesise a transient
        // `BopFn` and delegate to the shared call path. This keeps
        // the behaviour of `fn name` declarations and `Value::Fn`
        // values identical, including self-reference semantics.
        let func = self.functions.get(name).cloned().ok_or_else(|| {
            // Preference order: "did you mean" suggestion first
            // (most specific to the user's typo), then the
            // host's generic function hint (embedder-specific
            // tips like "available host functions: …"), then a
            // bare error.
            if let Some(hint) = self.callable_candidates_hint(name) {
                error_with_hint(
                    line,
                    crate::error_messages::function_not_found(name),
                    hint,
                )
            } else {
                let host_hint = self.host.function_hint();
                if host_hint.is_empty() {
                    error(line, crate::error_messages::function_not_found(name))
                } else {
                    error_with_hint(
                        line,
                        crate::error_messages::function_not_found(name),
                        host_hint,
                    )
                }
            }
        })?;

        let bop_fn = Rc::new(BopFn {
            params: func.params,
            captures: Vec::new(),
            body: FnBody::Ast(func.body),
            self_name: Some(name.to_string()),
        });
        self.call_bop_fn(&bop_fn, args, line)
    }

    // ─── Methods ───────────────────────────────────────────────────

    /// Full method dispatch: user methods win, then common,
    /// then type-specific (via [`Self::call_method`]). This is
    /// what call sites outside the `MethodCall` arm (for-loop
    /// iterator protocol, future trait-like uses) want — the
    /// normal `MethodCall` path inlines the same logic.
    fn call_method_full(
        &mut self,
        obj: &Value,
        method: &str,
        args: Vec<Value>,
        line: u32,
    ) -> Result<Value, BopError> {
        // User-method dispatch first — matches MethodCall's
        // priority so `fn MyType.iter(self)` wins over any
        // built-in method of the same name.
        let type_key: Option<(String, String)> = match obj {
            Value::Struct(s) => Some((
                s.module_path().to_string(),
                s.type_name().to_string(),
            )),
            Value::EnumVariant(e) => Some((
                e.module_path().to_string(),
                e.type_name().to_string(),
            )),
            _ => None,
        };
        if let Some(key) = type_key {
            let user = self
                .methods
                .get(&key)
                .and_then(|ms| ms.get(method))
                .cloned();
            if let Some(m) = user {
                if m.params.len() != args.len() + 1 {
                    return Err(error(
                        line,
                        format!(
                            "`{}.{}` expects {} argument{} (including `self`), but got {}",
                            key.1,
                            method,
                            m.params.len(),
                            if m.params.len() == 1 { "" } else { "s" },
                            args.len() + 1
                        ),
                    ));
                }
                let mut full_args = Vec::with_capacity(args.len() + 1);
                full_args.push(obj.clone());
                full_args.extend(args);
                let bop_fn = Rc::new(BopFn {
                    params: m.params,
                    captures: Vec::new(),
                    body: FnBody::Ast(m.body),
                    self_name: None,
                });
                return self.call_bop_fn(&bop_fn, full_args, line);
            }
        }
        // Fall through to the built-in dispatch.
        let (ret, _mutated) = self.call_method(obj, method, &args, line)?;
        Ok(ret)
    }

    fn call_method(
        &self,
        obj: &Value,
        method: &str,
        args: &[Value],
        line: u32,
    ) -> Result<(Value, Option<Value>), BopError> {
        // `type` / `to_str` / `inspect` work on every value.
        // Try the shared dispatcher first so we don't have to
        // duplicate those three names across every type-
        // specific method table.
        if let Some(result) = methods::common_method(obj, method, args, line)? {
            return Ok(result);
        }
        // Built-in Result combinators (`is_ok`, `is_err`,
        // `unwrap`, `expect`, `unwrap_or`). Callable-taking
        // variants (`map`, `map_err`, `and_then`) are dispatched
        // one level up in the MethodCall arm so they can invoke
        // the user callable via `call_value`.
        if methods::is_builtin_result(obj) {
            if let Some(v) = methods::result_method(obj, method, args, line)? {
                return Ok((v, None));
            }
        }
        match obj {
            Value::Array(arr) => methods::array_method(arr, method, args, line),
            Value::Str(s) => methods::string_method(s, method, args, line),
            Value::Dict(entries) => methods::dict_method(entries, method, args, line),
            Value::Int(_) | Value::Number(_) => {
                methods::numeric_method(obj, method, args, line)
            }
            Value::Bool(_) => methods::bool_method(obj, method, args, line),
            Value::Iter(_) => methods::iter_method(obj, method, args, line),
            _ => Err(error(
                line,
                crate::error_messages::no_such_method(obj.type_name(), method),
            )),
        }
    }

    /// Handle `r.map(f)`, `r.map_err(f)`, `r.and_then(f)` for a
    /// built-in `Result` receiver. Factored out of the
    /// `MethodCall` arm so the evaluator / VM / AOT can keep the
    /// same shape.
    fn call_result_callable_method(
        &mut self,
        receiver: &Value,
        kind: methods::ResultCallableKind,
        method: &str,
        args: Vec<Value>,
        line: u32,
    ) -> Result<Value, BopError> {
        use crate::builtins::expect_args;
        use methods::{make_result_err, make_result_ok, ResultCallableKind};
        expect_args(method, &args, 1, line)?;
        let callable = args.into_iter().next().expect("expect_args ensured len = 1");
        let variant_info = match receiver {
            Value::EnumVariant(e) => e,
            _ => return Err(error(line, "Result method called on non-Result")),
        };
        let payload = match variant_info.payload() {
            crate::value::EnumPayload::Tuple(items) if items.len() == 1 => items[0].clone(),
            // Unreachable for the built-in shape, but keep the
            // error clean rather than panicking.
            _ => {
                return Err(error(
                    line,
                    format!("malformed Result::{} payload", variant_info.variant()),
                ));
            }
        };
        let is_ok = variant_info.variant() == "Ok";
        match kind {
            ResultCallableKind::Map => {
                if is_ok {
                    let new_value = self.call_value(callable, vec![payload], line, Some(method))?;
                    Ok(make_result_ok(new_value))
                } else {
                    // Err passes through unchanged. Rebuild it so
                    // the caller sees the same type identity —
                    // matches the pure-Bop combinator's behaviour.
                    Ok(make_result_err(payload))
                }
            }
            ResultCallableKind::MapErr => {
                if !is_ok {
                    let new_value = self.call_value(callable, vec![payload], line, Some(method))?;
                    Ok(make_result_err(new_value))
                } else {
                    Ok(make_result_ok(payload))
                }
            }
            ResultCallableKind::AndThen => {
                if is_ok {
                    // `f` is expected to return a Result; we
                    // surface whatever it returns verbatim. A
                    // match on the returned shape at the call
                    // site catches misuse.
                    self.call_value(callable, vec![payload], line, Some(method))
                } else {
                    Ok(make_result_err(payload))
                }
            }
        }
    }
}

// ─── Pattern matching ──────────────────────────────────────────────
//
// `pattern_matches` returns true if `value` fits `pattern`, filling
// `bindings` with every `Binding` name along the way. On a partial
// match it's the caller's responsibility to discard the bindings
// — `eval_match` does this by only consuming them after the match
// + guard both succeed.

/// Destructured view of an `Iter::Next(v) | Iter::Done` result.
/// Returned by [`unwrap_iter_result`] so the for-loop can bind
/// the payload cleanly without repeating the pattern-match.
enum IterStep {
    Next(Value),
    Done,
}

/// Inspect a value returned from an iterator's `.next()` method.
/// Returns `Some(step)` when the value is a well-formed
/// `Iter::Next(v)` / `Iter::Done` (built-in or not), or `None`
/// when it doesn't match so the caller can raise a clear error.
fn unwrap_iter_result(v: &Value) -> Option<IterStep> {
    let e = match v {
        Value::EnumVariant(e) => e,
        _ => return None,
    };
    if e.type_name() != "Iter" {
        return None;
    }
    match (e.variant(), e.payload()) {
        ("Next", crate::value::EnumPayload::Tuple(items)) if items.len() == 1 => {
            Some(IterStep::Next(items[0].clone()))
        }
        ("Done", crate::value::EnumPayload::Unit) => Some(IterStep::Done),
        _ => None,
    }
}

/// Seed a fresh evaluator's type tables with the engine-wide
/// builtin types (`Result`, `RuntimeError`). The shapes come from
/// `crate::builtins` so walker / VM / AOT can never drift out of
/// sync — they all read the same source.
///
/// Returns:
/// - struct_defs keyed by `(module_path, type_name)` with the
///   builtin registered under `<builtin>`;
/// - enum_defs keyed the same way;
/// - a bare-name → module_path map seeded with entries for every
///   builtin, so the program's outermost scope can resolve
///   bare `Result::Ok(...)` and `RuntimeError { ... }` without
///   an explicit `use`.
fn seed_builtin_types() -> (
    BTreeMap<(String, String), Vec<String>>,
    BTreeMap<(String, String), Vec<VariantDecl>>,
    BTreeMap<String, String>,
) {
    use crate::value::BUILTIN_MODULE_PATH;
    let mut struct_defs: BTreeMap<(String, String), Vec<String>> = BTreeMap::new();
    let mut enum_defs: BTreeMap<(String, String), Vec<VariantDecl>> = BTreeMap::new();
    let mut type_bindings: BTreeMap<String, String> = BTreeMap::new();
    struct_defs.insert(
        (String::from(BUILTIN_MODULE_PATH), String::from("RuntimeError")),
        crate::builtins::builtin_runtime_error_fields(),
    );
    type_bindings.insert(
        String::from("RuntimeError"),
        String::from(BUILTIN_MODULE_PATH),
    );
    enum_defs.insert(
        (String::from(BUILTIN_MODULE_PATH), String::from("Result")),
        crate::builtins::builtin_result_variants(),
    );
    type_bindings.insert(
        String::from("Result"),
        String::from(BUILTIN_MODULE_PATH),
    );
    enum_defs.insert(
        (String::from(BUILTIN_MODULE_PATH), String::from("Iter")),
        crate::builtins::builtin_iter_variants(),
    );
    type_bindings.insert(
        String::from("Iter"),
        String::from(BUILTIN_MODULE_PATH),
    );
    (struct_defs, enum_defs, type_bindings)
}

/// True when two enum declarations describe the same runtime
/// shape. Strictly looser than `PartialEq` on `Vec<VariantDecl>`:
/// tuple variants compare by *arity* only (their payload field
/// names are positional stubs with no runtime meaning), while
/// struct variants still require matching field names. Same for
/// the outer variant ordering — positional.
///
/// Used by the "redeclare-same-shape" rules so a user program
/// that declares `enum Result { Ok(v), Err(e) }` is compatible
/// with the engine's builtin `enum Result { Ok(value), Err(error) }`.
fn variants_equivalent(a: &[VariantDecl], b: &[VariantDecl]) -> bool {
    if a.len() != b.len() {
        return false;
    }
    for (va, vb) in a.iter().zip(b.iter()) {
        if va.name != vb.name {
            return false;
        }
        match (&va.kind, &vb.kind) {
            (VariantKind::Unit, VariantKind::Unit) => {}
            (VariantKind::Tuple(fa), VariantKind::Tuple(fb)) => {
                if fa.len() != fb.len() {
                    return false;
                }
            }
            (VariantKind::Struct(fa), VariantKind::Struct(fb)) => {
                if fa != fb {
                    return false;
                }
            }
            _ => return false,
        }
    }
    true
}

/// Walk a pair of scope stacks to resolve a source-level type
/// reference — the same logic as
/// [`Evaluator::resolve_type_ref`], but free-standing so the
/// pattern matcher can be called with a borrow of the
/// evaluator's tables without needing the evaluator itself.
/// Returns `None` if the name isn't in scope.
///
/// `module_aliases` is the persistent map of aliased `use`
/// modules so namespaced references (`m.Color`) resolve even
/// inside function bodies, where `scopes` no longer contains
/// `m` (the function call stack is reset per-call).
pub fn resolve_type_in(
    value_scopes: &[BTreeMap<String, Value>],
    type_scopes: &[BTreeMap<String, String>],
    module_aliases: &BTreeMap<String, Rc<crate::value::BopModule>>,
    namespace: Option<&str>,
    type_name: &str,
) -> Option<String> {
    if let Some(ns) = namespace {
        // First: look the alias up in value scopes (catches
        // locally-bound modules, if any). Then fall back to
        // the evaluator-level alias map so function bodies can
        // reach module-level aliases even when their own value
        // scope is empty.
        for scope in value_scopes.iter().rev() {
            if let Some(Value::Module(m)) = scope.get(ns) {
                if m.types.iter().any(|t| t == type_name) {
                    return Some(m.path.clone());
                }
                return None;
            }
        }
        if let Some(m) = module_aliases.get(ns) {
            if m.types.iter().any(|t| t == type_name) {
                return Some(m.path.clone());
            }
        }
        return None;
    }
    for scope in type_scopes.iter().rev() {
        if let Some(mp) = scope.get(type_name) {
            return Some(mp.clone());
        }
    }
    None
}

/// Resolver that turns a source-level type reference — optional
/// namespace plus bare name (`m.Color` vs plain `Color`) — into
/// the declaring module's path. Pattern matching threads this
/// through so a pattern like `Color::Red` only matches values
/// whose module identity agrees with the current scope's binding
/// of `Color`.
///
/// Returning `None` means "no type with this name is visible in
/// the calling scope" — the matcher treats that as a mismatch
/// rather than a fallback, to avoid silently matching a
/// same-named type from a different module.
pub type TypeResolveFn<'a> = &'a dyn Fn(Option<&str>, &str) -> Option<String>;

/// Attempt to match `pattern` against `value`. On success, appends
/// any captured `(name, Value)` bindings to `bindings` and returns
/// `true`; on failure, returns `false` and leaves `bindings` in an
/// undefined state — it's the caller's responsibility to discard it.
///
/// `resolver` is consulted whenever a pattern names a user type
/// (`Pattern::Struct` or `Pattern::EnumVariant`) so the matcher
/// can compare the value's full identity `(module_path,
/// type_name)` against the source-level reference.
///
/// Exported so other engines (the bytecode VM, AOT transpiler)
/// can run the exact same structural matcher as the tree-walker
/// without re-implementing the rules.
pub fn pattern_matches(
    pattern: &Pattern,
    value: &Value,
    bindings: &mut Vec<(String, Value)>,
    resolver: TypeResolveFn<'_>,
) -> bool {
    match pattern {
        Pattern::Wildcard => true,
        Pattern::Binding(name) => {
            bindings.push((name.clone(), value.clone()));
            true
        }
        Pattern::Literal(lit) => match (lit, value) {
            (LiteralPattern::Int(a), Value::Int(b)) => a == b,
            (LiteralPattern::Number(a), Value::Number(b)) => a == b,
            // Cross-type numeric literal patterns — same rule
            // as `values_equal`: `match 1 { 1.0 => ... }` and
            // `match 1.0 { 1 => ... }` both match.
            (LiteralPattern::Int(a), Value::Number(b)) => (*a as f64) == *b,
            (LiteralPattern::Number(a), Value::Int(b)) => *a == (*b as f64),
            (LiteralPattern::Str(a), Value::Str(b)) => a.as_str() == b.as_str(),
            (LiteralPattern::Bool(a), Value::Bool(b)) => a == b,
            (LiteralPattern::None, Value::None) => true,
            _ => false,
        },
        Pattern::EnumVariant {
            namespace,
            type_name,
            variant,
            payload,
        } => {
            let ev = match value {
                Value::EnumVariant(e) => e,
                _ => return false,
            };
            // Full identity check: resolve the pattern's type
            // reference to a module path, then compare against
            // the value's own module path.
            let expected_mp = match resolver(namespace.as_deref(), type_name) {
                Some(mp) => mp,
                None => return false,
            };
            if ev.module_path() != expected_mp.as_str()
                || ev.type_name() != type_name.as_str()
                || ev.variant() != variant.as_str()
            {
                return false;
            }
            match (payload, ev.payload()) {
                (VariantPatternPayload::Unit, crate::value::EnumPayload::Unit) => true,
                (
                    VariantPatternPayload::Tuple(pats),
                    crate::value::EnumPayload::Tuple(items),
                ) => {
                    if pats.len() != items.len() {
                        return false;
                    }
                    for (p, v) in pats.iter().zip(items.iter()) {
                        if !pattern_matches(p, v, bindings, resolver) {
                            return false;
                        }
                    }
                    true
                }
                (
                    VariantPatternPayload::Struct { fields, rest },
                    crate::value::EnumPayload::Struct(entries),
                ) => {
                    match_struct_fields(fields, *rest, entries, bindings, resolver)
                }
                _ => false,
            }
        }
        Pattern::Struct {
            namespace,
            type_name,
            fields,
            rest,
        } => {
            let st = match value {
                Value::Struct(s) => s,
                _ => return false,
            };
            let expected_mp = match resolver(namespace.as_deref(), type_name) {
                Some(mp) => mp,
                None => return false,
            };
            if st.module_path() != expected_mp.as_str()
                || st.type_name() != type_name.as_str()
            {
                return false;
            }
            match_struct_fields(fields, *rest, st.fields(), bindings, resolver)
        }
        Pattern::Array { elements, rest } => {
            let items = match value {
                Value::Array(arr) => arr,
                _ => return false,
            };
            match rest {
                None => {
                    if elements.len() != items.len() {
                        return false;
                    }
                    for (p, v) in elements.iter().zip(items.iter()) {
                        if !pattern_matches(p, v, bindings, resolver) {
                            return false;
                        }
                    }
                    true
                }
                Some(rest_kind) => {
                    if items.len() < elements.len() {
                        return false;
                    }
                    for (i, p) in elements.iter().enumerate() {
                        if !pattern_matches(p, &items[i], bindings, resolver) {
                            return false;
                        }
                    }
                    if let ArrayRest::Named(name) = rest_kind {
                        let tail: Vec<Value> =
                            items[elements.len()..].iter().cloned().collect();
                        bindings.push((name.clone(), Value::new_array(tail)));
                    }
                    true
                }
            }
        }
        Pattern::Or(alts) => {
            for alt in alts {
                let mut attempt: Vec<(String, Value)> = Vec::new();
                if pattern_matches(alt, value, &mut attempt, resolver) {
                    bindings.extend(attempt);
                    return true;
                }
            }
            false
        }
    }
}

fn match_struct_fields(
    fields: &[(String, Pattern)],
    rest: bool,
    entries: &[(String, Value)],
    bindings: &mut Vec<(String, Value)>,
    resolver: TypeResolveFn<'_>,
) -> bool {
    // Every declared field-pattern must find its value in the
    // struct. `rest` just relaxes the requirement that *every*
    // value's key must appear in the pattern — non-rest patterns
    // may still leave fields unmatched, which is fine: the walker
    // matches named-field lookup semantics, not whole-shape
    // destructuring.
    let _ = rest;
    for (fname, pat) in fields {
        let value = match entries.iter().find(|(k, _)| k == fname) {
            Some((_, v)) => v,
            None => return false,
        };
        if !pattern_matches(pat, value, bindings, resolver) {
            return false;
        }
    }
    true
}

// ─── REPL session ──────────────────────────────────────────────────
//
// `Evaluator` itself is a one-shot: `Evaluator::new(host, limits)` +
// `eval.run(stmts)` + drop. That's the right shape for running a
// complete program from top to bottom. REPL workloads need the
// opposite: fresh *input* evaluated against *accumulated* state.
//
// `ReplSession` owns every Evaluator field that should survive
// across inputs — scopes, functions, user types, method tables,
// import caches, module aliases, rng state. The ephemeral
// per-run fields (host, step counter, call depth, the try-
// return sentinel slot, transient warnings) stay on the
// temporary `Evaluator` that the session spins up for each
// `eval` call.
//
// The session model also handles REPL-specific niceties:
//
//   - Bare expression statements at the end of an input yield
//     their value back to the caller, so the REPL can echo it.
//     `let x = 5` returns None; `x + 1` returns Some(Value).
//   - Scope depth is normalised back to the root on each
//     `eval` — if an earlier input errored mid-block, we
//     don't leave half-pushed scopes lying around for the next
//     input to trip over.

/// Persistent state for an interactive REPL session. Build
/// once with [`Self::new`], then call [`Self::eval`] for each
/// fresh line / block the user types. State carried across
/// calls: every `let` / `const` / `fn` / `struct` / `enum` /
/// method declaration, every `use`'d module's bindings and
/// aliases, the global rng seed, and the import cache.
///
/// A `ReplSession` is not a sandboxing boundary — embedders
/// that want a fresh identity between inputs should construct
/// a new session. Resource limits (steps, memory) are supplied
/// per `eval` call since they reset each time.
pub struct ReplSession {
    scopes: Vec<BTreeMap<String, Value>>,
    functions: BTreeMap<String, FnDef>,
    current_module: String,
    struct_defs: BTreeMap<(String, String), Vec<String>>,
    enum_defs: BTreeMap<(String, String), Vec<VariantDecl>>,
    methods: BTreeMap<(String, String), BTreeMap<String, FnDef>>,
    type_bindings: Vec<BTreeMap<String, String>>,
    module_aliases: BTreeMap<String, Rc<crate::value::BopModule>>,
    imports: ImportCache,
    imported_here: alloc_import::collections::BTreeSet<String>,
    rand_state: u64,
}

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

impl ReplSession {
    /// Build a fresh session. Type tables are pre-seeded with
    /// the engine builtins (`Result`, `RuntimeError`) so
    /// `Result::Ok(...)` resolves without an explicit `use`.
    pub fn new() -> Self {
        let (struct_defs, enum_defs, builtin_bindings) = seed_builtin_types();
        Self {
            scopes: vec![BTreeMap::new()],
            functions: BTreeMap::new(),
            current_module: String::from(crate::value::ROOT_MODULE_PATH),
            struct_defs,
            enum_defs,
            methods: BTreeMap::new(),
            type_bindings: vec![builtin_bindings],
            module_aliases: BTreeMap::new(),
            imports: Rc::new(RefCell::new(
                alloc_import::collections::BTreeMap::new(),
            )),
            imported_here: alloc_import::collections::BTreeSet::new(),
            rand_state: 0,
        }
    }

    /// Look up a binding by name. Convenience for tests and
    /// embedders that want to peek at the session's state
    /// between `eval` calls — e.g. checking that `let x = 5`
    /// actually stuck.
    pub fn get(&self, name: &str) -> Option<Value> {
        for scope in self.scopes.iter().rev() {
            if let Some(v) = scope.get(name) {
                return Some(v.clone());
            }
        }
        None
    }

    /// Every currently-bound name in the root scope, sorted.
    /// Handy for REPL introspection commands (`:vars`) and
    /// for tab-completers that want to stay honest about
    /// what's actually in scope rather than guessing from
    /// observed tokens.
    pub fn binding_names(&self) -> Vec<String> {
        let mut names: Vec<String> = self
            .scopes
            .first()
            .map(|s| s.keys().cloned().collect())
            .unwrap_or_default();
        for name in self.functions.keys() {
            names.push(name.clone());
        }
        names.sort();
        names.dedup();
        names
    }

    /// Parse `source` and run its statements against this
    /// session's accumulated state.
    ///
    /// If the last statement is a bare expression
    /// (`ExprStmt`), the session evaluates it and returns its
    /// value as `Ok(Some(v))` so the REPL can echo the
    /// result. Every other shape — `let x = ...`, `fn foo`,
    /// `struct`, `use`, loops — returns `Ok(None)`.
    ///
    /// Partial failure semantics: if an earlier statement
    /// errors, the session's state reflects whatever ran
    /// before the failure. That matches what a user would
    /// expect from an interactive prompt.
    pub fn eval<H: BopHost>(
        &mut self,
        source: &str,
        host: &mut H,
        limits: &BopLimits,
    ) -> Result<Option<Value>, BopError> {
        let stmts = crate::parse(source)?;
        self.run_stmts(&stmts, host, limits)
    }

    /// Like [`Self::eval`] but takes an already-parsed AST.
    /// Useful when the caller has already run a
    /// `parse_with_warnings` pass and wants to surface
    /// warnings before executing.
    pub fn run_stmts<H: BopHost>(
        &mut self,
        stmts: &[Stmt],
        host: &mut H,
        limits: &BopLimits,
    ) -> Result<Option<Value>, BopError> {
        // If the last stmt is a bare expression we strip it
        // off, run the rest, and then evaluate it as an
        // expression so we can return its value. Anything
        // else runs as a normal statement block.
        let (tail_expr, body) = match stmts.last().map(|s| &s.kind) {
            Some(StmtKind::ExprStmt(_)) => {
                let (last, rest) = stmts.split_last().unwrap();
                let expr = match &last.kind {
                    StmtKind::ExprStmt(e) => e.clone(),
                    _ => unreachable!(),
                };
                (Some(expr), rest)
            }
            _ => (None, stmts),
        };

        // Spin up a temporary Evaluator around the session's
        // state. We hand off each field by `mem::take` /
        // `clone` of the Rc so the Evaluator owns working
        // copies; at the end we unconditionally write the
        // (possibly-mutated) state back so partial failures
        // still persist whatever changes happened before the
        // error.
        let mut eval = self.take_evaluator(host, limits.clone());
        let result: Result<Option<Value>, BopError> = (|| {
            let sig = eval.exec_block(body)?;
            match sig {
                Signal::Break => return Err(error(0, "break used outside of a loop")),
                Signal::Continue => {
                    return Err(error(0, "continue used outside of a loop"));
                }
                _ => {}
            }
            match tail_expr {
                Some(expr) => Ok(Some(eval.eval_expr(&expr)?)),
                None => Ok(None),
            }
        })();
        // Surface any warnings accumulated on this run
        // (currently: glob-import shadowing). Stderr delivery
        // matches `Evaluator::run`; embedders that want
        // structured access can call `eval` via a custom host
        // and take warnings out through that path.
        #[cfg(not(feature = "no_std"))]
        {
            for w in &eval.runtime_warnings {
                eprintln!("warning: {}", w.message);
            }
        }
        self.put_evaluator(eval);
        result
    }

    /// Internal: move the session's state into a fresh
    /// Evaluator. `host` and `limits` are the ephemeral
    /// per-run bits.
    fn take_evaluator<'h, H: BopHost>(
        &mut self,
        host: &'h mut H,
        limits: BopLimits,
    ) -> Evaluator<'h, H> {
        Evaluator {
            scopes: core::mem::take(&mut self.scopes),
            functions: core::mem::take(&mut self.functions),
            current_module: core::mem::take(&mut self.current_module),
            struct_defs: core::mem::take(&mut self.struct_defs),
            enum_defs: core::mem::take(&mut self.enum_defs),
            methods: core::mem::take(&mut self.methods),
            type_bindings: core::mem::take(&mut self.type_bindings),
            module_aliases: core::mem::take(&mut self.module_aliases),
            imports: Rc::clone(&self.imports),
            imported_here: core::mem::take(&mut self.imported_here),
            rand_state: self.rand_state,
            host,
            steps: 0,
            call_depth: 0,
            limits,
            pending_try_return: None,
            runtime_warnings: Vec::new(),
        }
    }

    /// Internal: move the Evaluator's state back into the
    /// session. Also normalises scope depth back to the root
    /// so a mid-block error doesn't leave leftover pushed
    /// scopes hanging around for the next input.
    fn put_evaluator<'h, H: BopHost>(&mut self, eval: Evaluator<'h, H>) {
        let mut scopes = eval.scopes;
        if scopes.len() > 1 {
            scopes.truncate(1);
        }
        if scopes.is_empty() {
            scopes.push(BTreeMap::new());
        }
        let mut type_bindings = eval.type_bindings;
        if type_bindings.len() > 1 {
            type_bindings.truncate(1);
        }
        if type_bindings.is_empty() {
            // Re-seed so builtins stay visible.
            let (_, _, builtins) = seed_builtin_types();
            type_bindings.push(builtins);
        }
        self.scopes = scopes;
        self.functions = eval.functions;
        self.current_module = eval.current_module;
        self.struct_defs = eval.struct_defs;
        self.enum_defs = eval.enum_defs;
        self.methods = eval.methods;
        self.type_bindings = type_bindings;
        self.module_aliases = eval.module_aliases;
        self.imported_here = eval.imported_here;
        self.rand_state = eval.rand_state;
        // `imports` is shared via `Rc` — nothing to do; the
        // cache the Evaluator wrote into is the same one the
        // session holds.
    }
}