ccalc_engine/

exec.rs

use std::collections::HashMap;
use std::rc::Rc;

/// Parsed function body cache: body source string → pre-parsed, all-silent statements.
type BodyCache = HashMap<String, Rc<Vec<StmtEntry>>>;

/// Compiled bytecode cache for function bodies.
///
/// Key: body source string (same key as `BODY_CACHE`).
/// Value: `Some(chunk)` when compilation succeeded, `None` when the body has
/// constructs the compiler does not yet support (never retried).
type ChunkCache = HashMap<String, Option<Rc<crate::vm::Chunk>>>;

/// Cached entry for a leaf-function frame chunk.
struct FrameCacheEntry {
    chunk: Rc<crate::vm::Chunk>,
}

/// Compiled frame-optimised chunks keyed by body source string.
///
/// A `None` entry means compilation or leaf-eligibility failed — never retry.
type FrameChunkCache = HashMap<String, Option<FrameCacheEntry>>;

/// Expands a leading `~` to the user's home directory.
///
/// On Windows `USERPROFILE` is tried as a fallback for `HOME`. If neither is set the
/// string is returned unchanged.
fn expand_tilde(path: &str) -> String {
    if path == "~" || path.starts_with("~/") || path.starts_with("~\\") {
        let home = std::env::var("HOME")
            .or_else(|_| std::env::var("USERPROFILE"))
            .unwrap_or_default();
        if home.is_empty() {
            return path.to_string();
        }
        if path == "~" {
            home
        } else {
            format!("{}{}", home, &path[1..])
        }
    } else {
        path.to_string()
    }
}

use indexmap::IndexMap;
use ndarray::Array2;
use num_complex::Complex;

use crate::env::{Env, Value};
use crate::env::{load_workspace, save_workspace, save_workspace_vars};
use crate::eval::{
    Base, Expr, FormatMode, autoload_cache_insert, current_func_name, eval_with_io, format_complex,
    format_scalar, format_value_full, get_display_base, get_display_compact, get_display_fmt,
    global_declare, global_frame_pop, global_frame_push, global_get, global_init_if_absent,
    global_refresh_into_env, global_set, is_global, is_persistent, persistent_declare,
    persistent_frame_pop, persistent_frame_push, persistent_load, persistent_save,
    set_autoload_hook, set_display_ctx, set_eval_str_hook, set_fn_call_hook, set_last_err,
    set_nargout,
};
use crate::io::IoContext;
use crate::parser::{Stmt, StmtEntry, parse_stmts};

/// Maximum number of nested user-function calls before returning an error.
///
/// Prevents Rust-stack overflow on infinite recursion.  Set to 64 to stay
/// well within the default 8 MB Rust thread stack even in debug builds
/// (`call_user_function + vm_exec` each consume ~50–100 KB in debug mode due
/// to Rust's debug frame overhead; 64 levels × ~100 KB = ~6.4 MB headroom).
const MAX_CALL_DEPTH: u32 = 64;

thread_local! {
    /// Tracks the current script nesting depth to prevent infinite recursion via `run()`.
    static RUN_DEPTH: std::cell::Cell<u32> = const { std::cell::Cell::new(0) };

    /// Tracks the current user-function call depth to prevent infinite recursion.
    static CALL_DEPTH: std::cell::Cell<u32> = const { std::cell::Cell::new(0) };

    /// Stack of directories for currently executing scripts.
    ///
    /// When `run()`/`source()` starts executing a script, the script's parent directory is
    /// pushed here. `resolve_script_path` searches this stack (top-first) so that helper
    /// scripts can be referenced by bare name relative to the calling script's directory.
    static SCRIPT_DIR_STACK: std::cell::RefCell<Vec<std::path::PathBuf>> =
        const { std::cell::RefCell::new(Vec::new()) };

    /// Session search path — initialized from `config.toml` at startup.
    ///
    /// `addpath`/`rmpath` mutate this list for the current session; changes are never
    /// written back to `config.toml`. `resolve_script_path` searches here after CWD.
    static SESSION_PATH: std::cell::RefCell<Vec<std::path::PathBuf>> =
        const { std::cell::RefCell::new(Vec::new()) };

    /// Parse cache for named function bodies.
    ///
    /// Key: body source string (verbatim text between `function` and `end`).
    /// Value: pre-parsed, all-silent statement sequence.
    ///
    /// Populated on the first call to any function; subsequent calls with the
    /// same body string skip parsing entirely and reuse the shared `Rc`.
    /// Cache entries are never evicted — acceptable because the number of
    /// unique function bodies in a session is small.
    static BODY_CACHE: std::cell::RefCell<BodyCache> =
        std::cell::RefCell::new(HashMap::new());

    /// Compiled bytecode cache for named function bodies.
    ///
    /// Populated on the first successful compilation of a function body; `None`
    /// entries mark bodies whose compilation failed (no retry on future calls).
    static BODY_CHUNK_CACHE: std::cell::RefCell<ChunkCache> =
        std::cell::RefCell::new(HashMap::new());

    /// Frame-optimised chunk cache for leaf function bodies.
    ///
    /// A [`FrameCacheEntry`] is stored when `compile_fn_body` succeeds and the
    /// resulting chunk passes `is_leaf_fn`.  A `None` entry permanently disables
    /// the fast path for that body (non-leaf or compile failure).
    static BODY_FRAME_CACHE: std::cell::RefCell<FrameChunkCache> =
        std::cell::RefCell::new(HashMap::new());

    /// Scratch `Env` used exclusively by the Vec-frame fast path.
    ///
    /// Leaf functions never read from or write to `env` during execution, so
    /// this empty map is passed as the `env` parameter and is never touched.
    /// It is never accessed concurrently because leaf functions cannot recurse
    /// (empty `chunk.names` means no `CallUser`/`CallBuiltin`/`EvalExpr`).
    static LEAF_SCRATCH_ENV: std::cell::RefCell<crate::env::Env> =
        std::cell::RefCell::new(crate::env::Env::new());
}

/// RAII guard that restores `CALL_DEPTH` to `saved` when dropped.
///
/// Ensures the call depth counter is decremented on every exit path from
/// `call_user_function`, including early returns and `?`-propagated errors.
struct CallDepthGuard(u32);
impl Drop for CallDepthGuard {
    fn drop(&mut self) {
        CALL_DEPTH.with(|c| c.set(self.0));
    }
}

/// Recursively marks every statement in `stmts` (and all nested block bodies) as silent.
///
/// Function bodies must suppress all output — assignments, expressions, everything.
/// Because [`parse_stmts`] records the original semicolon flag per statement, a simple
/// `map(|(s,_)| (s, true))` only silences the top level.  Nested bodies inside `if`,
/// `for`, `while`, `switch`, `do..until`, and `try..catch` keep their original flags
/// and would still print.  This function walks the full statement tree.
fn silence_all(stmts: Vec<StmtEntry>) -> Vec<StmtEntry> {
    stmts
        .into_iter()
        .map(|(stmt, _, line)| {
            let stmt = match stmt {
                Stmt::If {
                    cond,
                    body,
                    elseif_branches,
                    else_body,
                } => Stmt::If {
                    cond,
                    body: silence_all(body),
                    elseif_branches: elseif_branches
                        .into_iter()
                        .map(|(c, b)| (c, silence_all(b)))
                        .collect(),
                    else_body: else_body.map(silence_all),
                },
                Stmt::For {
                    var,
                    range_expr,
                    body,
                } => Stmt::For {
                    var,
                    range_expr,
                    body: silence_all(body),
                },
                Stmt::While { cond, body } => Stmt::While {
                    cond,
                    body: silence_all(body),
                },
                Stmt::DoUntil { body, cond } => Stmt::DoUntil {
                    body: silence_all(body),
                    cond,
                },
                Stmt::Switch {
                    expr,
                    cases,
                    otherwise_body,
                } => Stmt::Switch {
                    expr,
                    cases: cases
                        .into_iter()
                        .map(|(v, b)| (v, silence_all(b)))
                        .collect(),
                    otherwise_body: otherwise_body.map(silence_all),
                },
                Stmt::TryCatch {
                    try_body,
                    catch_var,
                    catch_body,
                } => Stmt::TryCatch {
                    try_body: silence_all(try_body),
                    catch_var,
                    catch_body: silence_all(catch_body),
                },
                other => other,
            };
            (stmt, true, line)
        })
        .collect()
}

/// Returns a parsed, all-silent body for `body_source`, using the cache when possible.
///
/// "All-silent" means every [`StmtEntry`]'s `is_silent` flag is `true` — function bodies
/// never print output directly. The parse result is shared via `Rc` so that
/// repeated calls to the same function avoid both allocation and parsing work.
fn get_or_parse_body(body_source: &str) -> Result<Rc<Vec<StmtEntry>>, String> {
    BODY_CACHE.with(|cache| {
        let mut cache = cache.borrow_mut();
        if let Some(body) = cache.get(body_source) {
            return Ok(Rc::clone(body));
        }
        let stmts =
            parse_stmts(body_source).map_err(|e| format!("function body parse error: {e}"))?;
        let silent = silence_all(stmts);
        let rc = Rc::new(silent);
        cache.insert(body_source.to_string(), Rc::clone(&rc));
        Ok(rc)
    })
}

/// Appends ` near line N` to an error message if it does not already contain one.
///
/// `line == 0` means "no source location available" and is passed through unchanged.
fn annotate_line(e: String, line: usize) -> String {
    if line == 0 || e.contains("near line") {
        e
    } else {
        format!("{e} near line {line}")
    }
}

/// Strips a trailing ` near line N` suffix from an error message.
///
/// Used when storing an error in a `catch` variable — `e.message` should contain
/// the original message only, matching MATLAB/Octave semantics.
fn strip_near_line(s: String) -> String {
    if let Some(pos) = s.rfind(" near line ") {
        let after = &s[pos + " near line ".len()..];
        if !after.is_empty() && after.bytes().all(|b| b.is_ascii_digit()) {
            return s[..pos].to_string();
        }
    }
    s
}

/// Flow control signal returned by [`exec_stmts`].
///
/// Used to propagate `break`, `continue`, and `return` through nested block calls.
/// Loop implementations catch `Break`/`Continue`; function call implementation catches `Return`.
/// Uncaught signals at the top level are reported as errors.
pub enum Signal {
    /// `break` — exit the innermost enclosing loop immediately.
    Break,
    /// `continue` — skip the rest of the current iteration and advance to the next.
    Continue,
    /// `return` inside a named function — carries no value (outputs are read from env).
    Return,
}

/// Initialises exec-level hooks in `eval.rs` so that `eval_inner` can call user functions.
///
/// Must be called once at program startup before any evaluation takes place.
pub fn init() {
    set_fn_call_hook(call_user_function);
    set_autoload_hook(try_autoload);
    set_eval_str_hook(eval_str_impl);
}

/// Executes a code string against a snapshot clone of `env` and returns `ans`.
///
/// Used by `call_builtin` when `eval()` appears in expression context such as
/// `y = eval('2+2')`. Variable mutations inside the string do **not** propagate
/// back to the caller — use `eval()` as a standalone statement for that.
fn eval_str_impl(code: &str, env: &crate::env::Env) -> Result<crate::env::Value, String> {
    let mut env_clone = env.clone();
    env_clone
        .entry("ans".to_string())
        .or_insert(crate::env::Value::Scalar(0.0));
    let mut tmp_io = crate::io::IoContext::new();
    let fmt = get_display_fmt();
    let base = get_display_base();
    let compact = get_display_compact();
    let stmts = parse_stmts(code).map_err(|e| format!("eval: parse error: {e}"))?;
    exec_stmts(&stmts, &mut env_clone, &mut tmp_io, &fmt, base, compact)?;
    Ok(env_clone
        .get("ans")
        .cloned()
        .unwrap_or(crate::env::Value::Void))
}

/// Searches for `<name>.calc` or `<name>.m` on the session path and loads it.
///
/// Mirrors MATLAB/Octave autoload: when a function name is not found in the
/// environment, ccalc looks for a matching file on the path, loads its primary
/// function into the autoload cache, and returns `true` on success.
/// For package-qualified names (containing `.`), delegates to [`try_autoload_pkg`].
fn try_autoload(name: &str) -> bool {
    if name.contains('.') {
        return try_autoload_pkg(name);
    }
    let candidates = [format!("{name}.calc"), format!("{name}.m")];
    for candidate in &candidates {
        let Some(path) = resolve_script_path(candidate) else {
            continue;
        };
        let Ok(content) = std::fs::read_to_string(&path) else {
            continue;
        };
        let Ok(stmts) = parse_stmts(&content) else {
            continue;
        };
        if !matches!(stmts.first(), Some((Stmt::FunctionDef { .. }, _, _))) {
            continue;
        }
        let primary_name = match &stmts[0].0 {
            Stmt::FunctionDef { name, .. } => name.clone(),
            _ => continue,
        };
        let mut locals: IndexMap<String, Value> = IndexMap::new();
        for (stmt, _, _) in &stmts {
            if let Stmt::FunctionDef {
                name: n,
                outputs,
                params,
                body_source,
                doc,
            } = stmt
                && n != &primary_name
            {
                locals.insert(
                    n.clone(),
                    Value::Function(Box::new(crate::env::FunctionData {
                        outputs: outputs.clone(),
                        params: params.clone(),
                        body_source: body_source.clone(),
                        locals: IndexMap::new(),
                        doc: doc.clone(),
                    })),
                );
            }
        }
        if let Stmt::FunctionDef {
            outputs,
            params,
            body_source,
            doc,
            ..
        } = &stmts[0].0
        {
            autoload_cache_insert(
                primary_name,
                Value::Function(Box::new(crate::env::FunctionData {
                    outputs: outputs.clone(),
                    params: params.clone(),
                    body_source: body_source.clone(),
                    locals,
                    doc: doc.clone(),
                })),
            );
            return true;
        }
    }
    false
}

/// Searches for a package-qualified function and loads it into the autoload cache.
///
/// A qualified name like `"utils.my_func"` maps to `+utils/my_func.calc`.
/// Nested packages like `"utils.math.lerp"` map to `+utils/+math/lerp.calc`.
/// Searches SCRIPT_DIR_STACK → CWD → SESSION_PATH and caches under the qualified name.
fn try_autoload_pkg(qualified: &str) -> bool {
    let parts: Vec<&str> = qualified.split('.').collect();
    if parts.len() < 2 {
        return false;
    }
    let func_name = *parts.last().unwrap();
    let pkg_parts = &parts[..parts.len() - 1];

    // Build relative path prefix: +pkg1/+pkg2/...
    let mut rel_prefix = std::path::PathBuf::new();
    for pkg in pkg_parts {
        rel_prefix.push(format!("+{pkg}"));
    }

    let candidates = [
        rel_prefix.join(format!("{func_name}.calc")),
        rel_prefix.join(format!("{func_name}.m")),
    ];

    // Collect search directories: script dirs + CWD + session path.
    let mut search_dirs: Vec<std::path::PathBuf> = Vec::new();
    SCRIPT_DIR_STACK.with(|s| search_dirs.extend(s.borrow().iter().cloned()));
    search_dirs.push(std::path::PathBuf::from("."));
    SESSION_PATH.with(|s| search_dirs.extend(s.borrow().iter().cloned()));

    for dir in &search_dirs {
        for candidate in &candidates {
            let full = dir.join(candidate);
            let Ok(content) = std::fs::read_to_string(&full) else {
                continue;
            };
            let Ok(stmts) = parse_stmts(&content) else {
                continue;
            };
            if !matches!(stmts.first(), Some((Stmt::FunctionDef { .. }, _, _))) {
                continue;
            }
            let primary_name = match &stmts[0].0 {
                Stmt::FunctionDef { name, .. } => name.clone(),
                _ => continue,
            };
            let mut locals: IndexMap<String, Value> = IndexMap::new();
            for (stmt, _, _) in &stmts {
                if let Stmt::FunctionDef {
                    name: n,
                    outputs,
                    params,
                    body_source,
                    doc,
                } = stmt
                    && n != &primary_name
                {
                    locals.insert(
                        n.clone(),
                        Value::Function(Box::new(crate::env::FunctionData {
                            outputs: outputs.clone(),
                            params: params.clone(),
                            body_source: body_source.clone(),
                            locals: IndexMap::new(),
                            doc: doc.clone(),
                        })),
                    );
                }
            }
            if let Stmt::FunctionDef {
                outputs,
                params,
                body_source,
                doc,
                ..
            } = &stmts[0].0
            {
                autoload_cache_insert(
                    qualified.to_string(),
                    Value::Function(Box::new(crate::env::FunctionData {
                        outputs: outputs.clone(),
                        params: params.clone(),
                        body_source: body_source.clone(),
                        locals,
                        doc: doc.clone(),
                    })),
                );
                return true;
            }
        }
    }
    false
}

/// Push a script directory onto the search stack.
///
/// Call this before executing a top-level script file so that `run()`/`source()` calls
/// inside the script can find helper files by bare name relative to the script's directory.
/// Always paired with a matching `script_dir_pop`.
pub fn script_dir_push(dir: &std::path::Path) {
    SCRIPT_DIR_STACK.with(|s| s.borrow_mut().push(dir.to_path_buf()));
}

/// Pop the most recently pushed script directory from the search stack.
pub fn script_dir_pop() {
    SCRIPT_DIR_STACK.with(|s| s.borrow_mut().pop());
}

/// Initializes the session search path from the config `path` array.
///
/// Called once at startup (after loading `config.toml`). Each entry has `~` already
/// expanded by the caller.
pub fn session_path_init(paths: Vec<std::path::PathBuf>) {
    SESSION_PATH.with(|p| *p.borrow_mut() = paths);
}

/// Prepends (default) or appends a directory to the session search path.
///
/// If the same path is already present it is removed from its current position
/// before being re-inserted, so the path list contains no duplicates.
pub fn session_path_add(path: std::path::PathBuf, append: bool) {
    SESSION_PATH.with(|p| {
        let mut v = p.borrow_mut();
        v.retain(|e| e != &path);
        if append {
            v.push(path);
        } else {
            v.insert(0, path);
        }
    });
}

/// Removes a directory from the session search path (exact match).
pub fn session_path_remove(path: &std::path::Path) {
    SESSION_PATH.with(|p| p.borrow_mut().retain(|e| e.as_path() != path));
}

/// Returns a snapshot of the current session search path.
pub fn session_path_list() -> Vec<std::path::PathBuf> {
    SESSION_PATH.with(|p| p.borrow().clone())
}

/// Called by `eval_inner` whenever a user function (`Value::Function`) is invoked.
///
/// Executes the function body in an isolated scope containing only the parameters plus
/// any callable values (`Function`/`Lambda`) from the caller's environment, enabling
/// recursion and mutual recursion.
/// Multi-return: if the function has >1 output, returns `Value::Tuple`.
pub(crate) fn call_user_function(
    name: &str,
    func: &Value,
    args: &[Value],
    caller_env: &Env,
    io: &mut IoContext,
) -> Result<Value, String> {
    let Value::Function(fd) = func else {
        return Err("call_user_function: not a Function value".to_string());
    };
    // Depth guard: prevent infinite recursion from overflowing the Rust call stack.
    let depth = CALL_DEPTH.with(|c| c.get());
    if depth >= MAX_CALL_DEPTH {
        return Err(format!(
            "'{name}': maximum function call depth ({MAX_CALL_DEPTH}) exceeded"
        ));
    }
    CALL_DEPTH.with(|c| c.set(depth + 1));
    // Guard restores depth on every exit path (including early returns and ? propagation).
    let _depth_guard = CallDepthGuard(depth);
    let (outputs, params, body_source, locals) =
        (&fd.outputs, &fd.params, &fd.body_source, &fd.locals);

    // Push global and persistent tracking frames for this function call.
    global_frame_push();
    persistent_frame_push(name); // `name` is the function name from the call site

    // Check for varargin: last parameter is 'varargin' → variadic function.
    let has_varargin = params.last().is_some_and(|p| p == "varargin");
    let fixed_params = if has_varargin {
        &params[..params.len() - 1]
    } else {
        params.as_slice()
    };

    // Trim any trailing args beyond what the function declares.
    // The parser injects `ans` for empty `f()` calls; for 0-param functions
    // we must silently ignore it. For N-param functions, allow up to N+1
    // args before complaining (one implicit `ans` is always present).
    let effective_args = if args.len() > params.len() {
        if !has_varargin && args.len() > params.len() + 1 {
            return Err(format!(
                "Too many arguments: expected at most {}, got {}",
                params.len(),
                args.len()
            ));
        }
        if has_varargin {
            args
        } else {
            // Exactly 1 extra: the implicit `ans` — trim it.
            &args[..params.len()]
        }
    } else {
        args
    };

    // ── Vec-frame fast path (leaf functions only) ─────────────────────────────
    // Eligible when the body compiles via `compile_fn_body`, all params are
    // slotted, `chunk.names` is empty (no env access during execution), no
    // varargin/varargout, and no prior parse/compile failure for this body.
    if !has_varargin && outputs.last().is_none_or(|o| o != "varargout") {
        // Look up (or populate) the frame-chunk cache entry for this body.
        let cached = BODY_FRAME_CACHE.with(|cc| {
            cc.borrow()
                .get(body_source.as_str())
                .map(|e| e.as_ref().map(|entry| Rc::clone(&entry.chunk)))
        });

        let frame_chunk_opt: Option<Rc<crate::vm::Chunk>> = match cached {
            // Cache hit: Some(chunk) = leaf, None = known non-leaf/non-compilable.
            Some(rc_opt) => rc_opt,
            // Cache miss: try compile_fn_body and check leaf eligibility.
            None => {
                let rc_opt = get_or_parse_body(body_source)
                    .ok()
                    .and_then(|body| {
                        crate::vm::compile::compile_fn_body(&body, params, outputs).ok()
                    })
                    .and_then(|chunk| {
                        if crate::vm::compile::is_leaf_fn(&chunk) && chunk.n_params == params.len()
                        {
                            Some(Rc::new(chunk))
                        } else {
                            None
                        }
                    });
                BODY_FRAME_CACHE.with(|cc| {
                    let mut cache = cc.borrow_mut();
                    cache.insert(
                        body_source.to_string(),
                        rc_opt.as_ref().map(|rc| FrameCacheEntry {
                            chunk: Rc::clone(rc),
                        }),
                    );
                });
                rc_opt
            }
        };

        if let Some(chunk) = frame_chunk_opt {
            let fmt = get_display_fmt();
            let base = get_display_base();
            let compact = get_display_compact();

            // Build slot frame: params at slots 0..n_params (guaranteed by compile_fn_body).
            let mut frame = vec![Value::Void; chunk.slot_names.len()];
            for (i, arg) in effective_args.iter().take(params.len()).enumerate() {
                frame[i] = arg.clone();
            }

            // Execute against the shared scratch env (leaf functions never access env).
            let exec_result = LEAF_SCRATCH_ENV.with(|cell| {
                let mut scratch = cell.borrow_mut();
                crate::vm::exec::vm_exec_with_frame(
                    &chunk,
                    frame,
                    &mut scratch,
                    io,
                    &fmt,
                    base,
                    compact,
                )
            });

            // Pop frames regardless of result (mirrors the regular path).
            let (func_name_saved, persistent_names) = persistent_frame_pop();
            for var_name in &persistent_names {
                // Leaf functions cannot have persistent vars, but handle if present.
                if let Some(val) = LEAF_SCRATCH_ENV.with(|c| c.borrow().get(var_name).cloned()) {
                    persistent_save(&func_name_saved, var_name, val);
                }
            }
            global_frame_pop();

            let (signal, mut frame) = exec_result?;
            match signal {
                None | Some(Signal::Return) => {}
                Some(Signal::Break) => return Err("'break' outside loop".to_string()),
                Some(Signal::Continue) => return Err("'continue' outside loop".to_string()),
            }

            // Extract return values from the frame by slot index.
            if outputs.is_empty() {
                return Ok(Value::Void);
            }
            if outputs.len() == 1 {
                let out_slot = chunk.slot_names.iter().position(|n| n == &outputs[0]);
                return Ok(out_slot
                    .map(|s| std::mem::replace(&mut frame[s], Value::Void))
                    .unwrap_or(Value::Void));
            }
            let vals: Vec<Value> = outputs
                .iter()
                .map(|o| {
                    chunk
                        .slot_names
                        .iter()
                        .position(|n| n == o)
                        .map(|s| std::mem::replace(&mut frame[s], Value::Void))
                        .unwrap_or(Value::Void)
                })
                .collect();
            return Ok(Value::Tuple(vals));
        }
    }
    // ── End Vec-frame fast path — fall through to full-Env path ──────────────

    // Build isolated scope: seed imaginary unit and ans, then copy all callable
    // values (Function/Lambda) from the caller's environment so that recursion
    // and mutual recursion work correctly.
    let mut local_env = Env::new();
    local_env.insert("i".to_string(), Value::Complex(0.0, 1.0));
    local_env.insert("j".to_string(), Value::Complex(0.0, 1.0));
    local_env.insert("ans".to_string(), Value::Scalar(0.0));
    // Local helper functions from the same function file (MATLAB-style scoping).
    // These take priority and are always available regardless of the caller's env.
    for (fn_name, val) in locals.iter() {
        local_env.insert(fn_name.clone(), val.clone());
    }
    for (var_name, val) in caller_env.iter() {
        if matches!(val, Value::Function(_) | Value::Lambda(_)) {
            local_env.insert(var_name.clone(), val.clone());
        }
    }

    // Bind fixed parameters
    for (p, a) in fixed_params.iter().zip(effective_args.iter()) {
        local_env.insert(p.clone(), a.clone());
    }

    // If varargin, collect remaining args into a Cell
    if has_varargin {
        // Collect extra args beyond the fixed parameters into varargin.
        // User functions do not receive an injected `ans`; the arg list reflects
        // exactly what the caller passed.
        let extra: Vec<Value> = effective_args
            .get(fixed_params.len()..)
            .unwrap_or(&[])
            .to_vec();
        let varargin = Value::Cell(Box::new(extra));
        local_env.insert("varargin".to_string(), varargin);
    }

    let nargin = effective_args.len().min(params.len());
    local_env.insert("nargin".to_string(), Value::Scalar(nargin as f64));
    local_env.insert("nargout".to_string(), Value::Scalar(outputs.len() as f64));

    // Retrieve (or parse-and-cache) the function body.
    let body = get_or_parse_body(body_source)?;
    let fmt = get_display_fmt();
    let base = get_display_base();
    let compact = get_display_compact();

    // Try the compiled VM path (cached by body_source).
    let maybe_chunk: Option<Rc<crate::vm::Chunk>> = BODY_CHUNK_CACHE.with(|cc| {
        let mut cache = cc.borrow_mut();
        if let Some(entry) = cache.get(body_source) {
            return entry.clone();
        }
        let result: Option<Rc<crate::vm::Chunk>> = match crate::vm::compile::compile(&body) {
            Ok(chunk) => Some(Rc::new(chunk)),
            Err(_) => None,
        };
        cache.insert(body_source.to_string(), result.clone());
        result
    });

    let exec_result = if let Some(chunk) = maybe_chunk {
        crate::vm::exec::vm_exec(&chunk, &mut local_env, io, &fmt, base, compact)
    } else {
        exec_stmts(&body, &mut local_env, io, &fmt, base, compact)
    };

    // Save persistent variables before unwinding the frame (even on error).
    let (func_name_saved, persistent_names) = persistent_frame_pop();
    for var_name in &persistent_names {
        if let Some(val) = local_env.get(var_name) {
            persistent_save(&func_name_saved, var_name, val.clone());
        }
    }
    // Pop the global names frame.
    global_frame_pop();

    // Propagate any execution error after saving persistent state.
    match exec_result? {
        None | Some(Signal::Return) => {}
        Some(Signal::Break) => return Err("'break' outside loop".to_string()),
        Some(Signal::Continue) => return Err("'continue' outside loop".to_string()),
    }

    // Collect return values
    if outputs.is_empty() {
        return Ok(Value::Void);
    }

    // varargout: single output named 'varargout' — expand from cell
    if outputs.len() == 1 && outputs[0] == "varargout" {
        let cell = local_env
            .remove("varargout")
            .unwrap_or(Value::Cell(Box::default()));
        return match cell {
            Value::Cell(mut v) => {
                if v.is_empty() {
                    Ok(Value::Void)
                } else if v.len() == 1 {
                    Ok(v.remove(0))
                } else {
                    Ok(Value::Tuple(*v))
                }
            }
            other => Ok(other),
        };
    }

    if outputs.len() == 1 {
        return Ok(local_env.remove(&outputs[0]).unwrap_or(Value::Void));
    }
    let vals: Vec<Value> = outputs
        .iter()
        .map(|o| local_env.remove(o).unwrap_or(Value::Void))
        .collect();
    Ok(Value::Tuple(vals))
}

/// Dispatch a user-function call from the VM's [`Opcode::CallUser`] handler.
///
/// Fast path: if `name` is a [`Value::Function`] in `env`, calls it directly
/// via `call_user_function` (no intermediate AST round-trip).
///
/// Slow path: for lambdas, matrix indexing (variable shadows function name),
/// auto-loaded functions, builtins, and other callable values — falls back to
/// `eval_with_io` by temporarily binding args to env under synthetic key names.
/// This path is correct for all value types and handles autoload automatically.
pub(crate) fn dispatch_user_call_for_vm(
    name: &str,
    args: &[Value],
    env: &mut Env,
    io: &mut IoContext,
) -> Result<Value, String> {
    // Fast path: Function directly in env (the common case for hot loops).
    // Use matches! + get to avoid cloning the Box<FunctionData> — pass &Value directly.
    // Both `f: &Value` and `env: &Env` (caller_env) are immutable borrows; Rust allows it.
    if matches!(env.get(name), Some(Value::Function(_))) {
        let f = env.get(name).unwrap();
        return call_user_function(name, f, args, env, io);
    }
    // Non-function or absent: lambda, matrix indexing, autoload, builtin fallback.
    // eval_with_io handles all of these correctly.
    call_via_eval_with_args(name, args, env, io)
}

/// Evaluate `name(args)` by temporarily binding `args` to synthetic env keys and
/// calling `eval_with_io`.
///
/// Handles all callable types: autoloaded functions, builtins, lambdas, and matrix
/// indexing when a variable shadows a function name.  Used as the slow-path fallback
/// from `dispatch_user_call_for_vm` when the fast Function path is not applicable.
fn call_via_eval_with_args(
    name: &str,
    args: &[Value],
    env: &mut Env,
    io: &mut IoContext,
) -> Result<Value, String> {
    // Bind each arg to a synthetic env key to avoid interfering with user variables.
    let arg_keys: Vec<String> = (0..args.len()).map(|i| format!("__vm_cu_{i}__")).collect();
    let mut saved: Vec<(String, Option<Value>)> = Vec::with_capacity(args.len());
    for (key, val) in arg_keys.iter().zip(args.iter()) {
        saved.push((key.clone(), env.get(key.as_str()).cloned()));
        env.insert(key.clone(), val.clone());
    }
    // Build the call expression referencing the synthetic arg keys.
    let call_expr = crate::eval::Expr::Call(
        name.to_string(),
        arg_keys
            .iter()
            .map(|k| crate::eval::Expr::Var(k.clone()))
            .collect(),
    );
    let result = eval_with_io(&call_expr, env, io);
    // Restore env: remove synthetic keys or restore pre-existing values.
    for (key, saved_val) in saved {
        match saved_val {
            Some(v) => {
                env.insert(key, v);
            }
            None => {
                env.remove(&key);
            }
        }
    }
    result
}

/// Resolves a script filename to an existing path.
///
/// If `name` already has an extension, it is used verbatim.
/// Otherwise, `.calc` is tried first (native ccalc format), then `.m` (Octave/MATLAB compatibility).
/// The search is relative to the current working directory.
pub fn resolve_script_path(name: &str) -> Option<std::path::PathBuf> {
    // Build candidate base paths.
    //
    // MATLAB `private/` semantics: a `private/` sub-directory is visible only
    // to scripts/functions in its parent directory.  Therefore:
    //   • SCRIPT_DIR_STACK entries (the calling script's own directory) ARE
    //     allowed to search their `private/` sub-folder — checked first.
    //   • CWD and SESSION_PATH entries do NOT get a `private/` look-aside;
    //     they can only see files directly in those directories.
    let p = std::path::Path::new(name);
    let mut bases: Vec<std::path::PathBuf> = Vec::new();

    // Stacked script directories (most-recent first): private/ before the dir.
    SCRIPT_DIR_STACK.with(|stack| {
        for dir in stack.borrow().iter().rev() {
            bases.push(dir.join("private").join(p));
            bases.push(dir.join(p));
        }
    });

    // CWD-relative (no private/ look-aside).
    bases.push(p.to_path_buf());

    // Session search-path entries (no private/ look-aside).
    SESSION_PATH.with(|sp| {
        for dir in sp.borrow().iter() {
            bases.push(dir.join(p));
        }
    });

    for base in &bases {
        if base.extension().is_some() {
            if base.exists() {
                return Some(base.clone());
            }
            // Explicit extension given but not found — try next base.
            continue;
        }
        let with_calc = base.with_extension("calc");
        if with_calc.exists() {
            return Some(with_calc);
        }
        let with_m = base.with_extension("m");
        if with_m.exists() {
            return Some(with_m);
        }
    }
    None
}

/// Returns `true` if `val` is considered truthy by MATLAB `if`/`while` semantics.
///
/// - Scalar: nonzero and not NaN.
/// - Matrix: all elements nonzero and not NaN.
/// - Complex: either part nonzero.
/// - Str/StringObj: nonempty.
/// - Void: always false.
pub(crate) fn is_truthy(val: &Value) -> bool {
    match val {
        Value::Scalar(n) => *n != 0.0 && !n.is_nan(),
        Value::Matrix(m) => m.iter().all(|&x| x != 0.0 && !x.is_nan()),
        Value::Complex(re, im) => *re != 0.0 || *im != 0.0,
        Value::ComplexMatrix(m) => m.iter().all(|c| c.re != 0.0 || c.im != 0.0),
        Value::Str(s) | Value::StringObj(s) => !s.is_empty(),
        Value::Void => false,
        // Functions are truthy (they exist), but comparing them to 0 makes no sense.
        // Treat as truthy so that `if f` doesn't silently fail.
        Value::Lambda(_) | Value::Function(_) | Value::Tuple(_) => true,
        // A cell is truthy if nonempty.
        Value::Cell(v) => !v.is_empty(),
        // A struct / struct array is always truthy.
        Value::Struct(_) | Value::StructArray(_) => true,
        // Datetime/Duration are truthy when not NaT/zero.
        Value::DateTime(ts) => !ts.is_nan(),
        Value::Duration(s) => *s != 0.0,
        Value::DateTimeArray(v) | Value::DurationArray(v) => !v.is_empty(),
        // A map is truthy when nonempty.
        Value::Map(m) => !m.is_empty(),
    }
}

/// Prints a value to stdout with MATLAB-style formatting.
///
/// `label` is `Some("name")` for assignment output and `None` for expression output.
/// In expression context scalars/complex print without a label; matrices print `ans =`.
pub(crate) fn print_value(
    label: Option<&str>,
    val: &Value,
    fmt: &FormatMode,
    base: Base,
    compact: bool,
) {
    match val {
        Value::Void => {}
        Value::Scalar(n) => {
            if let Some(name) = label {
                println!("{name} = {}", format_scalar(*n, base, fmt));
            } else {
                println!("{}", format_scalar(*n, base, fmt));
            }
        }
        Value::Matrix(_) => {
            if let Some(full) = format_value_full(val, fmt) {
                let prefix = label.unwrap_or("ans");
                println!("{prefix} =");
                println!("{full}");
                if !compact {
                    println!();
                }
            }
        }
        Value::Complex(re, im) => {
            if let Some(name) = label {
                println!("{name} = {}", format_complex(*re, *im, fmt));
            } else {
                println!("{}", format_complex(*re, *im, fmt));
            }
        }
        Value::Str(s) | Value::StringObj(s) => {
            if let Some(name) = label {
                println!("{name} = {s}");
            } else {
                println!("{s}");
            }
        }
        Value::Lambda(_) => {
            if let Some(name) = label {
                println!("{name} = @<lambda>");
            } else {
                println!("@<lambda>");
            }
        }
        Value::Function(fd) => {
            let params_str = fd.params.join(", ");
            let out_str = match fd.outputs.len() {
                0 => String::new(),
                1 => format!("{} = ", fd.outputs[0]),
                _ => format!("[{}] = ", fd.outputs.join(", ")),
            };
            if let Some(name) = label {
                println!("{name} = @function {out_str}{name}({params_str})");
            } else {
                println!("@function {out_str}f({params_str})");
            }
        }
        Value::Tuple(vals) => {
            // Tuples are internal and shouldn't normally be displayed at the REPL level.
            // This can happen if a multi-output function is called without multi-assign.
            for (i, v) in vals.iter().enumerate() {
                print_value(label.map(|_| "ans").or(Some("ans")), v, fmt, base, compact);
                let _ = i;
            }
        }
        Value::ComplexMatrix(_) => {
            if let Some(full) = format_value_full(val, fmt) {
                let prefix = label.unwrap_or("ans");
                println!("{prefix} =");
                println!("{full}");
                if !compact {
                    println!();
                }
            }
        }
        Value::Cell(_) | Value::Struct(_) | Value::StructArray(_) => {
            if let Some(full) = format_value_full(val, fmt) {
                let prefix = label.unwrap_or("ans");
                println!("{prefix} =");
                println!("{full}");
                if !compact {
                    println!();
                }
            }
        }
        Value::DateTime(ts) => {
            let s = crate::datetime::format_datetime(*ts);
            if let Some(name) = label {
                println!("{name} = {s}");
            } else {
                println!("{s}");
            }
        }
        Value::Duration(secs) => {
            let s = crate::datetime::format_duration(*secs);
            if let Some(name) = label {
                println!("{name} = {s}");
            } else {
                println!("{s}");
            }
        }
        Value::DateTimeArray(_) | Value::DurationArray(_) => {
            if let Some(full) = format_value_full(val, fmt) {
                let prefix = label.unwrap_or("ans");
                println!("{prefix} =");
                println!("{full}");
                if !compact {
                    println!();
                }
            }
        }
        Value::Map(_) => {
            if let Some(full) = format_value_full(val, fmt) {
                let prefix = label.unwrap_or("ans");
                println!("{prefix} =");
                println!("{full}");
                if !compact {
                    println!();
                }
            }
        }
    }
}

/// Recursively sets a value at `path` inside a nested struct map.
///
/// Ownership-by-value approach: consumes the map, updates it, and returns the updated map.
/// Intermediate structs are created on demand if a path segment does not yet exist.
fn set_nested(
    mut map: IndexMap<String, Value>,
    path: &[String],
    val: Value,
) -> Result<IndexMap<String, Value>, String> {
    let (first, rest) = path.split_first().expect("set_nested: empty path");
    if rest.is_empty() {
        map.insert(first.clone(), val);
    } else {
        let inner = match map.shift_remove(first) {
            Some(Value::Struct(m)) => *m,
            None => IndexMap::new(),
            Some(other) => {
                map.insert(first.clone(), other);
                return Err(format!("'{first}' is not a struct"));
            }
        };
        let updated = set_nested(inner, rest, val)?;
        map.insert(first.clone(), Value::Struct(Box::new(updated)));
    }
    Ok(map)
}

/// Pre-register all top-level [`Stmt::FunctionDef`] nodes into `env`.
///
/// Implements MATLAB/Octave script hoisting semantics: called before execution
/// begins so helper functions defined anywhere in a script file are visible to
/// code that appears before them textually.  Only the immediate `stmts`
/// slice is scanned — function bodies are not descended into.
fn hoist_functions(stmts: &[StmtEntry], env: &mut Env) {
    for (stmt, _, _) in stmts {
        if let Stmt::FunctionDef {
            name,
            outputs,
            params,
            body_source,
            doc,
        } = stmt
        {
            env.insert(
                name.clone(),
                Value::Function(Box::new(crate::env::FunctionData {
                    outputs: outputs.clone(),
                    params: params.clone(),
                    body_source: body_source.clone(),
                    locals: IndexMap::new(),
                    doc: doc.clone(),
                })),
            );
        }
    }
}

/// Execute a top-level script block (REPL input, pipe/script mode, `eval()`).
///
/// Identical to [`exec_stmts`] but first calls `hoist_functions` so that
/// helper functions defined at the bottom of the script are visible to code
/// above them — matching MATLAB/Octave script semantics.
pub fn exec_script(
    stmts: &[StmtEntry],
    env: &mut Env,
    io: &mut IoContext,
    fmt: &FormatMode,
    base: Base,
    compact: bool,
) -> Result<Option<Signal>, String> {
    hoist_functions(stmts, env);
    exec_stmts(stmts, env, io, fmt, base, compact)
}

/// Execute a sequence of parsed statements, handling flow control signals.
///
/// Returns `Ok(None)` on normal completion, `Ok(Some(Signal::Break/Continue))`
/// when those flow-control statements escape a loop, or `Err(e)` on runtime error.
/// Loop implementations (`For`, `While`) catch `Break`/`Continue` internally;
/// a signal that reaches the top-level caller should be reported as an error.
pub fn exec_stmts(
    stmts: &[StmtEntry],
    env: &mut Env,
    io: &mut IoContext,
    fmt: &FormatMode,
    base: Base,
    compact: bool,
) -> Result<Option<Signal>, String> {
    // Fast pre-scan: check compilability with zero heap allocation.
    // This avoids the expensive Chunk-building + Expr-cloning that compile()
    // does before discovering an unsupported node deep inside a hot loop body.
    if crate::vm::compile::is_compilable(stmts) {
        match crate::vm::compile::compile(stmts) {
            Ok(chunk) => {
                return crate::vm::exec::vm_exec(&chunk, env, io, fmt, base, compact);
            }
            Err(crate::vm::CompileError::Unsupported) => {}
        }
    }

    // Propagate display settings to eval.rs so named function bodies can use them.
    set_display_ctx(fmt, base, compact);

    for (stmt, silent, stmt_line) in stmts {
        match stmt {
            Stmt::Assign(name, expr) => {
                set_nargout(1);
                let val = eval_with_io(expr, env, io).map_err(|e| annotate_line(e, *stmt_line))?;
                env.insert(name.clone(), val.clone());
                // Mirror to the shared global store when declared global in this scope.
                if is_global(name) {
                    global_set(name, val.clone());
                }
                // Write-through for persistent vars: recursive calls can see the update.
                if is_persistent(name) {
                    persistent_save(&current_func_name(), name, val.clone());
                }
                if !silent && !matches!(val, Value::Void) {
                    print_value(Some(name), &val, fmt, base, compact);
                }
            }

            Stmt::Global(names) => {
                for name in names {
                    global_declare(name);
                    global_init_if_absent(name);
                    // If the name was already assigned in local env, promote it to global.
                    // Otherwise restore the current global value into local env.
                    if let Some(local_val) = env.remove(name) {
                        global_set(name, local_val.clone());
                        env.insert(name.clone(), local_val);
                    } else if let Some(global_val) = global_get(name) {
                        env.insert(name.clone(), global_val);
                    }
                }
            }

            Stmt::Persistent(names) => {
                // Persistent is only meaningful inside a named function.
                // At the top level it is accepted and treated as a no-op.
                let func = current_func_name();
                for name in names {
                    persistent_declare(name);
                    if let Some(saved) = persistent_load(&func, name) {
                        // Subsequent call: restore the saved value.
                        env.insert(name.clone(), saved);
                    } else {
                        // First call: initialize to [] (empty matrix), matching MATLAB.
                        // This makes isempty(x) true so guards like
                        // `if isempty(x); x = 0; end` work correctly.
                        env.insert(
                            name.clone(),
                            Value::Matrix(Box::new(ndarray::Array2::zeros((0, 0)))),
                        );
                    }
                }
            }

            Stmt::Expr(expr) => {
                // Intercept addpath()/rmpath()/path() — mutate the session search path.
                if let Expr::Call(fn_name, args) = expr
                    && matches!(fn_name.as_str(), "addpath" | "rmpath" | "path")
                {
                    match fn_name.as_str() {
                        "addpath" => {
                            if args.is_empty() || args.len() > 2 {
                                return Err(
                                    "addpath: expects 1 or 2 arguments: addpath(dir) or addpath(dir, '-end')".to_string()
                                );
                            }
                            let path_val = eval_with_io(&args[0], env, io)?;
                            let path_str = match &path_val {
                                Value::Str(s) | Value::StringObj(s) => s.clone(),
                                _ => {
                                    return Err(
                                        "addpath: argument must be a string (directory path)"
                                            .to_string(),
                                    );
                                }
                            };
                            let append = if args.len() == 2 {
                                let flag_val = eval_with_io(&args[1], env, io)?;
                                match &flag_val {
                                    Value::Str(s) | Value::StringObj(s) if s == "-end" => true,
                                    Value::Str(_) | Value::StringObj(_) => {
                                        return Err(
                                            "addpath: second argument must be '-end' (to append) or omitted (to prepend)".to_string()
                                        );
                                    }
                                    _ => {
                                        return Err(
                                            "addpath: second argument must be a string '-end'"
                                                .to_string(),
                                        );
                                    }
                                }
                            } else {
                                false
                            };
                            let expanded = expand_tilde(&path_str);
                            let pb = std::path::PathBuf::from(&expanded);
                            session_path_add(pb, append);
                            if !silent {
                                for p in session_path_list() {
                                    println!("{}", p.display());
                                }
                            }
                        }
                        "rmpath" => {
                            if args.len() != 1 {
                                return Err("rmpath: expects exactly 1 argument".to_string());
                            }
                            let path_val = eval_with_io(&args[0], env, io)?;
                            let path_str = match &path_val {
                                Value::Str(s) | Value::StringObj(s) => s.clone(),
                                _ => {
                                    return Err(
                                        "rmpath: argument must be a string (directory path)"
                                            .to_string(),
                                    );
                                }
                            };
                            let expanded = expand_tilde(&path_str);
                            session_path_remove(std::path::Path::new(&expanded));
                        }
                        "path" => {
                            if !args.is_empty() {
                                return Err("path: takes no arguments".to_string());
                            }
                            if !silent {
                                let paths = session_path_list();
                                if paths.is_empty() {
                                    println!("(search path is empty)");
                                } else {
                                    for p in &paths {
                                        println!("{}", p.display());
                                    }
                                }
                            }
                        }
                        _ => unreachable!(),
                    }
                    continue;
                }

                // Intercept run()/source() — execute a script file in the current workspace.
                // Variables defined in the script persist in the caller's scope (MATLAB `run` semantics).
                if let Expr::Call(fn_name, args) = expr
                    && matches!(fn_name.as_str(), "run" | "source")
                    && args.len() == 1
                {
                    let path_val = eval_with_io(&args[0], env, io)?;
                    let filename = match &path_val {
                        Value::Str(s) | Value::StringObj(s) => s.clone(),
                        _ => {
                            return Err(format!("{fn_name}: argument must be a string (filename)"));
                        }
                    };
                    let script_path = resolve_script_path(&filename)
                        .ok_or_else(|| format!("{fn_name}: script not found: '{filename}'"))?;
                    let content = std::fs::read_to_string(&script_path).map_err(|e| {
                        format!("{fn_name}: cannot read '{}': {e}", script_path.display())
                    })?;
                    let depth = RUN_DEPTH.with(|d| d.get());
                    if depth >= 64 {
                        return Err(format!(
                            "{fn_name}: maximum script nesting depth (64) exceeded"
                        ));
                    }
                    RUN_DEPTH.with(|d| d.set(depth + 1));
                    // Push the script's directory so nested run()/source() calls resolve
                    // helper scripts relative to the calling script's location.
                    if let Some(dir) = script_path.parent() {
                        SCRIPT_DIR_STACK.with(|s| s.borrow_mut().push(dir.to_path_buf()));
                    }
                    let run_stmts = parse_stmts(&content).map_err(|e| {
                        format!("{fn_name}: parse error in '{}': {e}", script_path.display())
                    })?;

                    // MATLAB scoping: if EVERY statement is a function definition,
                    // treat it as a function file — expose only the primary function and
                    // bundle all helpers into its `locals` (invisible to the caller).
                    // A mixed script+function file (functions-at-top style) is NOT a
                    // function file; its script body must also execute.
                    let is_fn_file = !run_stmts.is_empty()
                        && run_stmts
                            .iter()
                            .all(|(s, _, _)| matches!(s, Stmt::FunctionDef { .. }));
                    let result = if is_fn_file {
                        let primary_name = match &run_stmts[0].0 {
                            Stmt::FunctionDef { name, .. } => name.clone(),
                            _ => unreachable!(),
                        };
                        let mut locals: IndexMap<String, Value> = IndexMap::new();
                        for (stmt, _, _) in &run_stmts {
                            if let Stmt::FunctionDef {
                                name,
                                outputs,
                                params,
                                body_source,
                                doc,
                            } = stmt
                                && name != &primary_name
                            {
                                locals.insert(
                                    name.clone(),
                                    Value::Function(Box::new(crate::env::FunctionData {
                                        outputs: outputs.clone(),
                                        params: params.clone(),
                                        body_source: body_source.clone(),
                                        locals: IndexMap::new(),
                                        doc: doc.clone(),
                                    })),
                                );
                            }
                        }
                        if let Stmt::FunctionDef {
                            outputs,
                            params,
                            body_source,
                            doc,
                            ..
                        } = &run_stmts[0].0
                        {
                            env.insert(
                                primary_name,
                                Value::Function(Box::new(crate::env::FunctionData {
                                    outputs: outputs.clone(),
                                    params: params.clone(),
                                    body_source: body_source.clone(),
                                    locals,
                                    doc: doc.clone(),
                                })),
                            );
                        }
                        Ok(None)
                    } else {
                        // Pre-load all local function defs so that forward references
                        // within the script work (MATLAB local-function semantics).
                        for (stmt, _, _) in run_stmts.iter() {
                            if let Stmt::FunctionDef {
                                name,
                                outputs,
                                params,
                                body_source,
                                doc,
                            } = stmt
                            {
                                env.insert(
                                    name.clone(),
                                    Value::Function(Box::new(crate::env::FunctionData {
                                        outputs: outputs.clone(),
                                        params: params.clone(),
                                        body_source: body_source.clone(),
                                        locals: IndexMap::new(),
                                        doc: doc.clone(),
                                    })),
                                );
                            }
                        }
                        exec_stmts(&run_stmts, env, io, fmt, base, compact)
                    };
                    SCRIPT_DIR_STACK.with(|s| s.borrow_mut().pop());
                    RUN_DEPTH.with(|d| d.set(depth));
                    // Propagate signals (return/break/continue) but do NOT early-return
                    // from exec_stmts — remaining statements in the outer script must run.
                    match result? {
                        None => {}
                        Some(sig) => return Ok(Some(sig)),
                    }
                    continue;
                }

                // Intercept eval(str) / eval(str, catch_str) — execute code in current workspace.
                // Variable assignments inside the string persist in the caller's scope,
                // matching MATLAB `eval` semantics. Uses the same RUN_DEPTH limit as run/source.
                if let Expr::Call(fn_name, args) = expr
                    && fn_name == "eval"
                    && (args.len() == 1 || args.len() == 2)
                {
                    let code_val = eval_with_io(&args[0], env, io)?;
                    let code_str = match code_val {
                        Value::Str(s) | Value::StringObj(s) => s,
                        _ => return Err("eval: argument must be a string".to_string()),
                    };
                    let depth = RUN_DEPTH.with(|d| d.get());
                    if depth >= 64 {
                        return Err("eval: maximum nesting depth (64) exceeded".to_string());
                    }
                    RUN_DEPTH.with(|d| d.set(depth + 1));
                    let run_result = (|| -> Result<Option<Signal>, String> {
                        let stmts = parse_stmts(&code_str)
                            .map_err(|e| format!("eval: parse error: {e}"))?;
                        exec_script(&stmts, env, io, fmt, base, compact)
                    })();
                    RUN_DEPTH.with(|d| d.set(depth));
                    match run_result {
                        Err(e) if args.len() == 2 => {
                            set_last_err(&e);
                            let catch_val = eval_with_io(&args[1], env, io)?;
                            let catch_str = match catch_val {
                                Value::Str(s) | Value::StringObj(s) => s,
                                _ => {
                                    return Err("eval: catch argument must be a string".to_string());
                                }
                            };
                            let catch_stmts = parse_stmts(&catch_str)
                                .map_err(|e| format!("eval: catch parse error: {e}"))?;
                            match exec_stmts(&catch_stmts, env, io, fmt, base, compact)? {
                                None => {}
                                Some(sig) => return Ok(Some(sig)),
                            }
                        }
                        Err(e) => return Err(e),
                        Ok(None) => {}
                        Ok(Some(sig)) => return Ok(Some(sig)),
                    }
                    continue;
                }

                // Intercept clear() / clear('x','y') — workspace variable removal.
                if let Expr::Call(fn_name, args) = expr
                    && fn_name == "clear"
                {
                    if args.is_empty() {
                        env.clear();
                    } else {
                        for arg in args {
                            let key = match arg {
                                Expr::StrLiteral(s) | Expr::StringObjLiteral(s) => s.clone(),
                                other => match eval_with_io(other, env, io)? {
                                    Value::Str(s) | Value::StringObj(s) => s,
                                    _ => continue,
                                },
                            };
                            env.remove(&key);
                        }
                    }
                    continue;
                }

                // Intercept remove(m, k) — in-place key removal from containers.Map.
                if let Expr::Call(fn_name, args) = expr
                    && fn_name == "remove"
                    && args.len() == 2
                    && let Expr::Var(map_name) = &args[0]
                {
                    let map_name = map_name.clone();
                    let key_val = eval_with_io(&args[1], env, io)
                        .map_err(|e| annotate_line(e, *stmt_line))?;
                    let key = match key_val {
                        Value::Str(s) | Value::StringObj(s) => s,
                        _ => {
                            return Err(annotate_line(
                                "remove: key must be a string".to_string(),
                                *stmt_line,
                            ));
                        }
                    };
                    match env.get_mut(&map_name) {
                        Some(Value::Map(map)) => {
                            map.shift_remove(&key);
                        }
                        Some(_) => {
                            return Err(annotate_line(
                                format!("remove: '{map_name}' is not a containers.Map"),
                                *stmt_line,
                            ));
                        }
                        None => {
                            return Err(annotate_line(
                                format!("remove: undefined variable '{map_name}'"),
                                *stmt_line,
                            ));
                        }
                    }
                    continue;
                }

                // Intercept format — update thread-local display context.
                if let Expr::Call(fn_name, args) = expr
                    && fn_name == "format"
                {
                    let arg = match args.first() {
                        Some(Expr::StrLiteral(s)) => s.as_str(),
                        None => "",
                        _ => "",
                    };
                    let new_fmt = match arg {
                        "" | "short" => FormatMode::Short,
                        "long" => FormatMode::Long,
                        "shorte" | "shortE" => FormatMode::ShortE,
                        "longe" | "longE" => FormatMode::LongE,
                        "shortg" | "shortG" => FormatMode::ShortG,
                        "longg" | "longG" => FormatMode::LongG,
                        "bank" => FormatMode::Bank,
                        "rat" => FormatMode::Rat,
                        "hex" => FormatMode::Hex,
                        "+" => FormatMode::Plus,
                        "compact" | "loose" => get_display_fmt(),
                        s => s
                            .parse::<usize>()
                            .map(FormatMode::Custom)
                            .unwrap_or_else(|_| get_display_fmt()),
                    };
                    let new_compact = match arg {
                        "compact" => true,
                        "loose" => false,
                        _ => get_display_compact(),
                    };
                    set_display_ctx(&new_fmt, base, new_compact);
                    continue;
                }

                // Intercept save()/load() — workspace persistence (same semantics as REPL).
                if let Expr::Call(fn_name, args) = expr
                    && matches!(fn_name.as_str(), "save" | "load" | "ws" | "wl")
                {
                    let is_save = matches!(fn_name.as_str(), "save" | "ws");
                    if is_save {
                        let (path_opt, var_names) = if args.is_empty() {
                            (None, vec![])
                        } else {
                            let path_val = eval_with_io(&args[0], env, io)?;
                            let path_str = match path_val {
                                Value::Str(s) | Value::StringObj(s) => s,
                                _ => return Err("save: path argument must be a string".to_string()),
                            };
                            let mut vars: Vec<String> = Vec::new();
                            for a in &args[1..] {
                                let v = eval_with_io(a, env, io)?;
                                match v {
                                    Value::Str(s) | Value::StringObj(s) => vars.push(s),
                                    _ => {
                                        return Err(
                                            "save: variable names must be strings".to_string()
                                        );
                                    }
                                }
                            }
                            (Some(path_str), vars)
                        };
                        let result = match &path_opt {
                            None => {
                                let home = std::env::var("HOME")
                                    .or_else(|_| std::env::var("USERPROFILE"))
                                    .unwrap_or_default();
                                let p = std::path::Path::new(&home)
                                    .join(".config")
                                    .join("ccalc")
                                    .join("workspace.toml");
                                save_workspace(env, &p)
                            }
                            Some(p) if var_names.is_empty() => {
                                save_workspace(env, std::path::Path::new(p))
                            }
                            Some(p) => {
                                let refs: Vec<&str> =
                                    var_names.iter().map(String::as_str).collect();
                                save_workspace_vars(env, std::path::Path::new(p), &refs)
                            }
                        };
                        if let Err(e) = result {
                            return Err(format!("save: {e}"));
                        }
                    } else {
                        // load
                        let loaded = if args.is_empty() {
                            let home = std::env::var("HOME")
                                .or_else(|_| std::env::var("USERPROFILE"))
                                .unwrap_or_default();
                            let p = std::path::Path::new(&home)
                                .join(".config")
                                .join("ccalc")
                                .join("workspace.toml");
                            load_workspace(&p)
                        } else {
                            let path_val = eval_with_io(&args[0], env, io)?;
                            let path_str = match path_val {
                                Value::Str(s) | Value::StringObj(s) => s,
                                _ => return Err("load: path argument must be a string".to_string()),
                            };
                            load_workspace(std::path::Path::new(&path_str))
                        };
                        match loaded {
                            Ok(ws) => env.extend(ws),
                            Err(e) => return Err(format!("load: {e}")),
                        }
                    }
                    continue;
                }

                let expr_label = if let Expr::Var(name) = expr {
                    Some(name.as_str())
                } else {
                    None
                };
                let val = eval_with_io(expr, env, io).map_err(|e| annotate_line(e, *stmt_line))?;
                env.insert("ans".to_string(), val.clone());
                if !silent && !matches!(val, Value::Void) {
                    print_value(expr_label, &val, fmt, base, compact);
                }
            }

            Stmt::If {
                cond,
                body,
                elseif_branches,
                else_body,
            } => {
                let cond_val =
                    eval_with_io(cond, env, io).map_err(|e| annotate_line(e, *stmt_line))?;
                let chosen: Option<&[StmtEntry]> = if is_truthy(&cond_val) {
                    Some(body)
                } else {
                    let mut found = None;
                    for (ei_cond, ei_body) in elseif_branches {
                        if is_truthy(
                            &eval_with_io(ei_cond, env, io)
                                .map_err(|e| annotate_line(e, *stmt_line))?,
                        ) {
                            found = Some(ei_body.as_slice());
                            break;
                        }
                    }
                    if found.is_none() {
                        found = else_body.as_deref();
                    }
                    found
                };
                if let Some(body_stmts) = chosen
                    && let Some(sig) = exec_stmts(body_stmts, env, io, fmt, base, compact)?
                {
                    return Ok(Some(sig));
                }
            }

            Stmt::For {
                var,
                range_expr,
                body,
            } => {
                let range_val =
                    eval_with_io(range_expr, env, io).map_err(|e| annotate_line(e, *stmt_line))?;
                let iter_cols: Vec<Value> = match range_val {
                    Value::Scalar(n) => vec![Value::Scalar(n)],
                    Value::Matrix(m) => {
                        let nrows = m.nrows();
                        let ncols = m.ncols();
                        (0..ncols)
                            .map(|j| {
                                if nrows == 1 {
                                    // Row vector: yield each element as a scalar
                                    Value::Scalar(m[[0, j]])
                                } else {
                                    // General matrix: yield each column as an M×1 matrix
                                    let mut col = Array2::zeros((nrows, 1));
                                    for i in 0..nrows {
                                        col[[i, 0]] = m[[i, j]];
                                    }
                                    Value::Matrix(Box::new(col))
                                }
                            })
                            .collect()
                    }
                    _ => return Err("'for' range must evaluate to a scalar or matrix".to_string()),
                };

                'for_loop: for col_val in iter_cols {
                    env.insert(var.clone(), col_val);
                    match exec_stmts(body, env, io, fmt, base, compact)? {
                        None => {}
                        Some(Signal::Break) => break 'for_loop,
                        Some(Signal::Continue) => continue 'for_loop,
                        Some(Signal::Return) => return Ok(Some(Signal::Return)),
                    }
                }
            }

            Stmt::While { cond, body } => loop {
                if !is_truthy(
                    &eval_with_io(cond, env, io).map_err(|e| annotate_line(e, *stmt_line))?,
                ) {
                    break;
                }
                match exec_stmts(body, env, io, fmt, base, compact)? {
                    None => {}
                    Some(Signal::Break) => break,
                    Some(Signal::Continue) => continue,
                    Some(Signal::Return) => return Ok(Some(Signal::Return)),
                }
            },

            Stmt::Break => return Ok(Some(Signal::Break)),
            Stmt::Continue => return Ok(Some(Signal::Continue)),

            // ── switch / case / otherwise / end ──────────────────────────────
            Stmt::Switch {
                expr,
                cases,
                otherwise_body,
            } => {
                let switch_val =
                    eval_with_io(expr, env, io).map_err(|e| annotate_line(e, *stmt_line))?;
                let mut matched = false;
                'switch_loop: for (case_exprs, case_body) in cases {
                    for case_expr in case_exprs {
                        let case_val = eval_with_io(case_expr, env, io)
                            .map_err(|e| annotate_line(e, *stmt_line))?;
                        // When the case expression is a Cell, check if switch_val
                        // matches any element of the cell (Phase 12.5c).
                        let is_match = if let Value::Cell(cell_elems) = &case_val {
                            cell_elems.iter().any(|elem| match (&switch_val, elem) {
                                (Value::Scalar(a), Value::Scalar(b)) => a == b,
                                _ => {
                                    let sv = match &switch_val {
                                        Value::Str(s) | Value::StringObj(s) => Some(s.as_str()),
                                        _ => None,
                                    };
                                    let cv = match elem {
                                        Value::Str(s) | Value::StringObj(s) => Some(s.as_str()),
                                        _ => None,
                                    };
                                    matches!((sv, cv), (Some(a), Some(b)) if a == b)
                                }
                            })
                        } else {
                            match (&switch_val, &case_val) {
                                (Value::Scalar(a), Value::Scalar(b)) => a == b,
                                _ => {
                                    let sv = match &switch_val {
                                        Value::Str(s) | Value::StringObj(s) => Some(s.as_str()),
                                        _ => None,
                                    };
                                    let cv = match &case_val {
                                        Value::Str(s) | Value::StringObj(s) => Some(s.as_str()),
                                        _ => None,
                                    };
                                    matches!((sv, cv), (Some(a), Some(b)) if a == b)
                                }
                            }
                        };
                        if is_match {
                            if let Some(sig) = exec_stmts(case_body, env, io, fmt, base, compact)? {
                                return Ok(Some(sig));
                            }
                            matched = true;
                            break 'switch_loop;
                        }
                    }
                }
                if !matched
                    && let Some(ob) = otherwise_body
                    && let Some(sig) = exec_stmts(ob, env, io, fmt, base, compact)?
                {
                    return Ok(Some(sig));
                }
            }

            // ── do...until ───────────────────────────────────────────────────
            Stmt::DoUntil { body, cond } => loop {
                match exec_stmts(body, env, io, fmt, base, compact)? {
                    Some(Signal::Break) => break,
                    Some(Signal::Continue) | None => {}
                    Some(Signal::Return) => return Ok(Some(Signal::Return)),
                }
                if is_truthy(
                    &eval_with_io(cond, env, io).map_err(|e| annotate_line(e, *stmt_line))?,
                ) {
                    break;
                }
            },

            // ── try / catch / end ────────────────────────────────────────────
            Stmt::TryCatch {
                try_body,
                catch_var,
                catch_body,
            } => match exec_stmts(try_body, env, io, fmt, base, compact) {
                Ok(None) => {}
                Ok(Some(sig)) => return Ok(Some(sig)),
                Err(msg) => {
                    let clean = strip_near_line(msg);
                    set_last_err(&clean);
                    if let Some(var) = catch_var {
                        let mut map = IndexMap::new();
                        map.insert("message".to_string(), Value::Str(clean));
                        env.insert(var.clone(), Value::Struct(Box::new(map)));
                    }
                    if let Some(sig) = exec_stmts(catch_body, env, io, fmt, base, compact)? {
                        return Ok(Some(sig));
                    }
                }
            },

            // ── function definition ──────────────────────────────────────────
            Stmt::FunctionDef {
                name,
                outputs,
                params,
                body_source,
                doc,
            } => {
                env.insert(
                    name.clone(),
                    Value::Function(Box::new(crate::env::FunctionData {
                        outputs: outputs.clone(),
                        params: params.clone(),
                        body_source: body_source.clone(),
                        locals: IndexMap::new(),
                        doc: doc.clone(),
                    })),
                );
            }

            // ── return ───────────────────────────────────────────────────────
            Stmt::Return => return Ok(Some(Signal::Return)),

            // ── cell element assignment ──────────────────────────────────────
            Stmt::CellSet(cell_name, idx_expr, val_expr) => {
                // Inject `end` so that c{end+1} works (end = current cell length).
                let cell_len = match env.get(cell_name) {
                    Some(Value::Cell(v)) => v.len(),
                    _ => 0,
                };
                let _owned_end;
                let env_end: &Env = if crate::eval::contains_end(idx_expr) {
                    _owned_end = write_env_with_end(env, cell_len);
                    &_owned_end
                } else {
                    env
                };
                let idx = eval_with_io(idx_expr, env_end, io)
                    .map_err(|e| annotate_line(e, *stmt_line))?;
                let rhs =
                    eval_with_io(val_expr, env, io).map_err(|e| annotate_line(e, *stmt_line))?;
                let i = match idx {
                    Value::Scalar(n) => n as isize,
                    _ => return Err(format!("{cell_name}{{}}: index must be a scalar integer")),
                };
                match env.get_mut(cell_name) {
                    Some(Value::Cell(v)) => {
                        if i < 1 {
                            return Err(format!(
                                "{cell_name}{{}}: index {i} out of range (1..{})",
                                v.len()
                            ));
                        }
                        let idx = (i - 1) as usize;
                        // Grow the cell if needed (MATLAB semantics: assigning beyond end grows it)
                        if idx >= v.len() {
                            v.resize(idx + 1, Value::Scalar(0.0));
                        }
                        v[idx] = rhs.clone();
                    }
                    Some(_) => {
                        return Err(format!(
                            "'{cell_name}' is not a cell array; use () for regular indexing"
                        ));
                    }
                    None => {
                        // Auto-create cell if not defined (MATLAB semantics)
                        if i < 1 {
                            return Err(format!("{cell_name}{{}}: index {i} must be >= 1"));
                        }
                        let idx = (i - 1) as usize;
                        let mut v = vec![Value::Scalar(0.0); idx + 1];
                        v[idx] = rhs.clone();
                        env.insert(cell_name.clone(), Value::Cell(Box::new(v)));
                    }
                }
                if !silent && let Some(val) = env.get(cell_name) {
                    print_value(Some(cell_name), val, fmt, base, compact);
                }
            }

            // ── struct field assignment ──────────────────────────────────────
            Stmt::FieldSet(base_name, path, rhs_expr) => {
                let rhs =
                    eval_with_io(rhs_expr, env, io).map_err(|e| annotate_line(e, *stmt_line))?;
                let root = match env.remove(base_name) {
                    Some(Value::Struct(m)) => *m,
                    None => IndexMap::new(),
                    Some(other) => {
                        env.insert(base_name.clone(), other);
                        return Err(format!("'{base_name}' is not a struct"));
                    }
                };
                let updated = set_nested(root, path, rhs)?;
                let struct_val = Value::Struct(Box::new(updated));
                if !silent {
                    print_value(Some(base_name), &struct_val, fmt, base, compact);
                }
                env.insert(base_name.clone(), struct_val);
            }

            // ── dynamic struct field assignment ──────────────────────────────
            Stmt::DynFieldSet(base_name, field_expr, rhs_expr) => {
                let field_val =
                    eval_with_io(field_expr, env, io).map_err(|e| annotate_line(e, *stmt_line))?;
                let field = match &field_val {
                    Value::Str(s) | Value::StringObj(s) => s.clone(),
                    _ => {
                        return Err(annotate_line(
                            "Dynamic field name must be a string".to_string(),
                            *stmt_line,
                        ));
                    }
                };
                let rhs =
                    eval_with_io(rhs_expr, env, io).map_err(|e| annotate_line(e, *stmt_line))?;
                let root = match env.remove(base_name) {
                    Some(Value::Struct(m)) => *m,
                    None => IndexMap::new(),
                    Some(other) => {
                        env.insert(base_name.clone(), other);
                        return Err(annotate_line(
                            format!("'{base_name}' is not a struct"),
                            *stmt_line,
                        ));
                    }
                };
                let mut updated = root;
                updated.insert(field, rhs);
                let struct_val = Value::Struct(Box::new(updated));
                if !silent {
                    print_value(Some(base_name), &struct_val, fmt, base, compact);
                }
                env.insert(base_name.clone(), struct_val);
            }

            // ── struct array element field assignment ────────────────────────
            Stmt::StructArrayFieldSet(base_name, idx_expr, path, rhs_expr) => {
                let rhs =
                    eval_with_io(rhs_expr, env, io).map_err(|e| annotate_line(e, *stmt_line))?;
                let idx_val =
                    eval_with_io(idx_expr, env, io).map_err(|e| annotate_line(e, *stmt_line))?;
                let idx = match &idx_val {
                    Value::Scalar(n) => {
                        let i = *n as isize;
                        if i < 1 {
                            return Err(format!(
                                "Struct array index must be a positive integer, got {n}"
                            ));
                        }
                        i as usize
                    }
                    _ => return Err("Struct array index must be a scalar integer".to_string()),
                };
                // Load or create the struct array
                let mut arr: Vec<IndexMap<String, Value>> = match env.remove(base_name) {
                    Some(Value::StructArray(v)) => *v,
                    // A scalar struct with no index yet — promote to 1-element array
                    Some(Value::Struct(m)) => vec![*m],
                    None => Vec::new(),
                    Some(other) => {
                        env.insert(base_name.clone(), other);
                        return Err(format!("'{base_name}' is not a struct array"));
                    }
                };
                // Grow the array if needed (fill with empty structs)
                while arr.len() < idx {
                    arr.push(IndexMap::new());
                }
                // Set the field(s) on element idx (1-based → 0-based)
                let elem = arr[idx - 1].clone();
                let updated_elem = set_nested(elem, path, rhs)?;
                arr[idx - 1] = updated_elem;
                let arr_val = Value::StructArray(Box::new(arr));
                if !silent {
                    print_value(Some(base_name), &arr_val, fmt, base, compact);
                }
                env.insert(base_name.clone(), arr_val);
            }

            // ── indexed assignment ────────────────────────────────────────────
            Stmt::IndexSet {
                name,
                indices,
                value,
            } => {
                let rhs = eval_with_io(value, env, io).map_err(|e| annotate_line(e, *stmt_line))?;
                // For persistent vars: refresh from the store before applying a partial
                // update so that values written by recursive calls are not overwritten.
                if is_persistent(name) {
                    let func = current_func_name();
                    if let Some(fresh) = persistent_load(&func, name) {
                        env.insert(name.clone(), fresh);
                    }
                }
                exec_index_set(name, indices, rhs, env, io)?;
                // Write-through: persist immediately so recursive callers see the update.
                if is_persistent(name)
                    && let Some(val) = env.get(name)
                {
                    persistent_save(&current_func_name(), name, val.clone());
                }
                if !silent && let Some(val) = env.get(name) {
                    print_value(Some(name), val, fmt, base, compact);
                }
            }

            // ── multi-assign ─────────────────────────────────────────────────
            Stmt::MultiAssign { targets, expr } => {
                set_nargout(targets.len());
                let val = eval_with_io(expr, env, io).map_err(|e| annotate_line(e, *stmt_line))?;
                let vals: Vec<Value> = match val {
                    Value::Tuple(v) => v,
                    other => vec![other],
                };
                for (i, target) in targets.iter().enumerate() {
                    if target == "~" {
                        continue; // discard output
                    }
                    let v = vals.get(i).cloned().unwrap_or(Value::Void);
                    env.insert(target.clone(), v.clone());
                    if !silent && !matches!(v, Value::Void) {
                        print_value(Some(target), &v, fmt, base, compact);
                    }
                }
            }
        }
    }
    // After all statements, refresh global vars in env from the global store.
    // This ensures that modifications made inside called functions (which write
    // to the global store) are visible in the current scope's environment.
    global_refresh_into_env(env);
    Ok(None)
}

// ── indexed assignment helper ──────────────────────────────────────────────

/// Resolved index positions (0-based) along one matrix dimension.
enum WriteIdx {
    /// `:` — all positions in the current dimension.
    All,
    /// Explicit 0-based positions (may exceed current size → grow).
    Positions(Vec<usize>),
}

/// Resolves one index expression to a `WriteIdx`.
///
/// Unlike the read-path `resolve_dim`, bounds checking is skipped so that
/// out-of-range indices can trigger array growth.  Logical-mask detection
/// (all-0/1 vector whose length equals `dim_size`) is supported.
fn resolve_write_dim(
    expr: &crate::eval::Expr,
    dim_size: usize,
    env: &Env,
    io: &mut IoContext,
) -> Result<WriteIdx, String> {
    if matches!(expr, crate::eval::Expr::Colon) {
        return Ok(WriteIdx::All);
    }
    let val = eval_with_io(expr, env, io)?;
    let floats: Vec<f64> = match val {
        Value::Scalar(n) => vec![n],
        Value::Complex(re, im) => {
            if im != 0.0 {
                return Err("Index must be real, not complex".to_string());
            }
            vec![re]
        }
        Value::Matrix(m) => {
            let total = m.nrows() * m.ncols();
            if m.nrows() > 1 && m.ncols() > 1 && total != dim_size {
                return Err("Index must be a scalar or vector, not a 2-D matrix".to_string());
            }
            // Collect in column-major order so mask positions align with linear indexing.
            if m.nrows() > 1 && m.ncols() > 1 {
                let mut v = Vec::with_capacity(total);
                for col in 0..m.ncols() {
                    for row in 0..m.nrows() {
                        v.push(m[[row, col]]);
                    }
                }
                v
            } else {
                m.iter().copied().collect()
            }
        }
        _ => return Err("Index must be numeric".to_string()),
    };
    // Logical mask: a 0/1 array whose element count matches dim_size.
    if dim_size > 0 && floats.len() == dim_size && floats.iter().all(|&f| f == 0.0 || f == 1.0) {
        let positions: Vec<usize> = floats
            .iter()
            .enumerate()
            .filter(|&(_, &f)| f == 1.0)
            .map(|(i, _)| i)
            .collect();
        return Ok(WriteIdx::Positions(positions));
    }
    // Numeric 1-based indices → 0-based (no upper-bound check — growth is handled by caller).
    let positions: Result<Vec<usize>, String> = floats
        .iter()
        .map(|&n| {
            let i = n.round() as i64;
            if i < 1 {
                return Err(format!("Index {i} must be >= 1"));
            }
            Ok(i as usize - 1)
        })
        .collect();
    Ok(WriteIdx::Positions(positions?))
}

/// Returns a clone of `env` with `end` set to `dim_size` as a `Value::Scalar`.
fn write_env_with_end(env: &Env, dim_size: usize) -> Env {
    let mut e = env.clone();
    e.insert("end".to_string(), Value::Scalar(dim_size as f64));
    e
}

/// Writes `rhs` into `name(indices...)` in `env`, growing the matrix if necessary.
///
/// Supports:
/// - 1 index: linear (column-major) indexing; grows row vectors / creates new ones.
/// - 2 indices: 2-D row/column indexing; grows the matrix in either dimension.
/// - Scalar RHS is broadcast to all selected positions.
/// - Logical mask indices (Phase 15d).
pub(crate) fn exec_index_set(
    name: &str,
    indices: &[crate::eval::Expr],
    rhs: Value,
    env: &mut Env,
    io: &mut IoContext,
) -> Result<(), String> {
    // Map key assignment: m('key') = val
    if indices.len() == 1 && matches!(env.get(name), Some(Value::Map(_))) {
        let key_val = eval_with_io(&indices[0], env, io)?;
        let key = match key_val {
            Value::Str(s) | Value::StringObj(s) => s,
            _ => return Err("Map key assignment requires a string key".to_string()),
        };
        match env.get_mut(name) {
            Some(Value::Map(map)) => {
                map.insert(key, rhs);
                return Ok(());
            }
            _ => unreachable!(),
        }
    }

    // If LHS is already ComplexMatrix or RHS introduces complex values, use the complex path.
    let needs_complex = matches!(env.get(name), Some(Value::ComplexMatrix(_)))
        || matches!(&rhs, Value::Complex(_, _) | Value::ComplexMatrix(_));

    if needs_complex {
        return exec_index_set_complex(name, indices, rhs, env, io);
    }

    match indices.len() {
        1 => {
            // Borrow env read-only to get matrix dimensions — no clone.
            let (total, nrows_hint, ncols_hint) = match env.get(name) {
                Some(Value::Matrix(m)) => (m.nrows() * m.ncols(), m.nrows(), m.ncols()),
                Some(Value::Scalar(_)) => (1, 1, 1),
                None | Some(Value::Void) => (0, 0, 0),
                Some(_) => {
                    return Err(format!(
                        "'{name}' is not a matrix; cannot use () indexed assignment"
                    ));
                }
            };

            // Resolve the index expression while env still contains `name`, so that
            // self-referential indices like A(A(1)) = v work correctly.
            let widx = {
                let _owned_end;
                let env_end: &Env = if crate::eval::contains_end(&indices[0]) {
                    _owned_end = write_env_with_end(env, total);
                    &_owned_end
                } else {
                    env
                };
                resolve_write_dim(&indices[0], total, env_end, io)?
            };

            // Determine which 0-based positions to write.
            let positions: Vec<usize> = match widx {
                WriteIdx::All => (0..total).collect(),
                WriteIdx::Positions(p) => p,
            };

            // Determine the RHS values to write (scalar broadcasts).
            let rhs_vals: Vec<f64> = match &rhs {
                Value::Scalar(n) => vec![*n; positions.len()],
                Value::Matrix(m) => {
                    let flat: Vec<f64> = m.iter().copied().collect();
                    if flat.len() != positions.len() {
                        return Err(format!(
                            "Assignment dimension mismatch: {} positions but {} values",
                            positions.len(),
                            flat.len()
                        ));
                    }
                    flat
                }
                _ => {
                    return Err(
                        "Indexed assignment: RHS must be a numeric scalar or matrix".to_string()
                    );
                }
            };

            // Find the required flat size after growth.
            let required = positions.iter().copied().max().map(|m| m + 1).unwrap_or(0);
            let required = required.max(total);

            // Determine output shape: keep original orientation when growing a vector.
            let (out_rows, out_cols) = if nrows_hint == 0 || ncols_hint == 0 {
                // Empty → default to row vector.
                (1, required)
            } else if nrows_hint == 1 {
                (1, required)
            } else if ncols_hint == 1 {
                (required, 1)
            } else if required > total {
                return Err("Cannot grow a 2-D matrix with linear indexing".to_string());
            } else {
                (nrows_hint, ncols_hint)
            };

            // Take ownership from env — moves the Array2 (pointer + metadata only),
            // avoiding the O(n) clone that would make repeated writes O(n²).
            let mut mat = match env.remove(name) {
                Some(Value::Matrix(m)) => *m,
                Some(Value::Scalar(n)) => Array2::from_elem((1, 1), n),
                None | Some(Value::Void) => Array2::zeros((0, 0)),
                Some(other) => {
                    env.insert(name.to_string(), other);
                    return Err(format!(
                        "'{name}' is not a matrix; cannot use () indexed assignment"
                    ));
                }
            };

            // Grow matrix if needed, preserving existing data at correct column-major positions.
            if required > total || out_rows != mat.nrows() || out_cols != mat.ncols() {
                let mut new_mat = Array2::<f64>::zeros((out_rows, out_cols));
                for old_p in 0..total {
                    let old_row = old_p % mat.nrows().max(1);
                    let old_col = old_p / mat.nrows().max(1);
                    let new_row = old_p % out_rows;
                    let new_col = old_p / out_rows;
                    if old_row < mat.nrows() && old_col < mat.ncols() {
                        new_mat[[new_row, new_col]] = mat[[old_row, old_col]];
                    }
                }
                mat = new_mat;
            }

            // Write values at column-major positions directly.
            for (&pos, &val) in positions.iter().zip(rhs_vals.iter()) {
                let row = pos % mat.nrows();
                let col = pos / mat.nrows();
                mat[[row, col]] = val;
            }

            let result = if mat.nrows() == 1 && mat.ncols() == 1 {
                Value::Scalar(mat[[0, 0]])
            } else {
                Value::Matrix(Box::new(mat))
            };
            env.insert(name.to_string(), result);
        }
        2 => {
            // Borrow env read-only to get matrix dimensions — no clone.
            let (nrows, ncols) = match env.get(name) {
                Some(Value::Matrix(m)) => (m.nrows(), m.ncols()),
                Some(Value::Scalar(_)) => (1, 1),
                None | Some(Value::Void) => (0, 0),
                Some(_) => {
                    return Err(format!(
                        "'{name}' is not a matrix; cannot use () indexed assignment"
                    ));
                }
            };

            // Resolve both index expressions while env still contains `name`.
            let (ridx, cidx) = {
                let _owned_r;
                let env_r: &Env = if crate::eval::contains_end(&indices[0]) {
                    _owned_r = write_env_with_end(env, nrows);
                    &_owned_r
                } else {
                    env
                };
                let _owned_c;
                let env_c: &Env = if crate::eval::contains_end(&indices[1]) {
                    _owned_c = write_env_with_end(env, ncols);
                    &_owned_c
                } else {
                    env
                };
                (
                    resolve_write_dim(&indices[0], nrows, env_r, io)?,
                    resolve_write_dim(&indices[1], ncols, env_c, io)?,
                )
            };

            let rows: Vec<usize> = match ridx {
                WriteIdx::All => (0..nrows.max(1)).collect(),
                WriteIdx::Positions(p) => p,
            };
            let cols: Vec<usize> = match cidx {
                WriteIdx::All => (0..ncols.max(1)).collect(),
                WriteIdx::Positions(p) => p,
            };

            let req_rows = rows
                .iter()
                .copied()
                .max()
                .map(|m| m + 1)
                .unwrap_or(0)
                .max(nrows);
            let req_cols = cols
                .iter()
                .copied()
                .max()
                .map(|m| m + 1)
                .unwrap_or(0)
                .max(ncols);

            // Collect RHS values.
            let n_sel = rows.len() * cols.len();
            let rhs_vals: Vec<f64> = match &rhs {
                Value::Scalar(n) => vec![*n; n_sel],
                Value::Matrix(m) => {
                    let flat: Vec<f64> = m.iter().copied().collect();
                    if flat.len() != n_sel {
                        return Err(format!(
                            "Assignment dimension mismatch: {}×{} = {} positions but {} values",
                            rows.len(),
                            cols.len(),
                            n_sel,
                            flat.len()
                        ));
                    }
                    flat
                }
                _ => {
                    return Err(
                        "Indexed assignment: RHS must be a numeric scalar or matrix".to_string()
                    );
                }
            };

            // Take ownership from env — moves the Array2, avoiding the O(n) clone.
            let mut mat = match env.remove(name) {
                Some(Value::Matrix(m)) => *m,
                Some(Value::Scalar(n)) => Array2::from_elem((1, 1), n),
                None | Some(Value::Void) => Array2::zeros((0, 0)),
                Some(other) => {
                    env.insert(name.to_string(), other);
                    return Err(format!(
                        "'{name}' is not a matrix; cannot use () indexed assignment"
                    ));
                }
            };

            // Grow matrix if needed (fill new cells with 0).
            if req_rows != nrows || req_cols != ncols {
                let mut new_mat = Array2::<f64>::zeros((req_rows, req_cols));
                for r in 0..nrows {
                    for c in 0..ncols {
                        new_mat[[r, c]] = mat[[r, c]];
                    }
                }
                mat = new_mat;
            }

            // Write values row-major over selected (row, col) pairs.
            let mut k = 0;
            for &r in &rows {
                for &c in &cols {
                    mat[[r, c]] = rhs_vals[k];
                    k += 1;
                }
            }

            let result = if mat.nrows() == 1 && mat.ncols() == 1 {
                Value::Scalar(mat[[0, 0]])
            } else {
                Value::Matrix(Box::new(mat))
            };
            env.insert(name.to_string(), result);
        }
        _ => return Err("Indexed assignment supports at most 2 indices".to_string()),
    }
    Ok(())
}

/// Complex-path indexed assignment: LHS is `ComplexMatrix` or RHS is `Complex`/`ComplexMatrix`.
///
/// A real `Matrix`/`Scalar` LHS is automatically upcast to `ComplexMatrix` when the RHS
/// introduces complex values (MATLAB/Octave semantics).
fn exec_index_set_complex(
    name: &str,
    indices: &[crate::eval::Expr],
    rhs: Value,
    env: &mut Env,
    io: &mut IoContext,
) -> Result<(), String> {
    /// Converts an RHS `Value` into a `Vec<Complex<f64>>` with `n_slots` elements.
    fn rhs_to_complex(rhs: &Value, n_slots: usize) -> Result<Vec<Complex<f64>>, String> {
        match rhs {
            Value::Scalar(n) => Ok(vec![Complex::new(*n, 0.0); n_slots]),
            Value::Complex(re, im) => Ok(vec![Complex::new(*re, *im); n_slots]),
            Value::Matrix(m) => {
                let flat: Vec<Complex<f64>> = m.iter().map(|&x| Complex::new(x, 0.0)).collect();
                if flat.len() != n_slots {
                    return Err(format!(
                        "Assignment dimension mismatch: {} positions but {} values",
                        n_slots,
                        flat.len()
                    ));
                }
                Ok(flat)
            }
            Value::ComplexMatrix(m) => {
                let flat: Vec<Complex<f64>> = m.iter().copied().collect();
                if flat.len() != n_slots {
                    return Err(format!(
                        "Assignment dimension mismatch: {} positions but {} values",
                        n_slots,
                        flat.len()
                    ));
                }
                Ok(flat)
            }
            _ => Err("Indexed assignment: RHS must be a numeric value".to_string()),
        }
    }

    /// Takes LHS from `env`, upcasting real types to `Array2<Complex<f64>>`.
    fn take_as_complex(name: &str, env: &mut Env) -> Result<Array2<Complex<f64>>, String> {
        match env.remove(name) {
            Some(Value::ComplexMatrix(m)) => Ok(*m),
            Some(Value::Matrix(m)) => Ok(m.mapv(|x| Complex::new(x, 0.0))),
            Some(Value::Scalar(n)) => Ok(Array2::from_elem((1, 1), Complex::new(n, 0.0))),
            None | Some(Value::Void) => Ok(Array2::zeros((0, 0))),
            Some(other) => {
                env.insert(name.to_string(), other);
                Err(format!(
                    "'{name}' is not a matrix; cannot use () indexed assignment"
                ))
            }
        }
    }

    match indices.len() {
        1 => {
            let (total, nrows_hint, ncols_hint) = match env.get(name) {
                Some(Value::ComplexMatrix(m)) => (m.nrows() * m.ncols(), m.nrows(), m.ncols()),
                Some(Value::Matrix(m)) => (m.nrows() * m.ncols(), m.nrows(), m.ncols()),
                Some(Value::Scalar(_)) => (1, 1, 1),
                None | Some(Value::Void) => (0, 0, 0),
                Some(_) => {
                    return Err(format!(
                        "'{name}' is not a matrix; cannot use () indexed assignment"
                    ));
                }
            };

            let widx = {
                let _owned_end;
                let env_end: &Env = if crate::eval::contains_end(&indices[0]) {
                    _owned_end = write_env_with_end(env, total);
                    &_owned_end
                } else {
                    env
                };
                resolve_write_dim(&indices[0], total, env_end, io)?
            };

            let positions: Vec<usize> = match widx {
                WriteIdx::All => (0..total).collect(),
                WriteIdx::Positions(p) => p,
            };

            let rhs_vals = rhs_to_complex(&rhs, positions.len())?;

            let required = positions.iter().copied().max().map(|m| m + 1).unwrap_or(0);
            let required = required.max(total);

            let (out_rows, out_cols) = if nrows_hint == 0 || ncols_hint == 0 || nrows_hint == 1 {
                (1, required)
            } else if ncols_hint == 1 {
                (required, 1)
            } else if required > total {
                return Err("Cannot grow a 2-D matrix with linear indexing".to_string());
            } else {
                (nrows_hint, ncols_hint)
            };

            let mut mat = take_as_complex(name, env)?;

            if required > total || out_rows != mat.nrows() || out_cols != mat.ncols() {
                let mut new_mat = Array2::<Complex<f64>>::zeros((out_rows, out_cols));
                for old_p in 0..total {
                    let old_row = old_p % mat.nrows().max(1);
                    let old_col = old_p / mat.nrows().max(1);
                    let new_row = old_p % out_rows;
                    let new_col = old_p / out_rows;
                    if old_row < mat.nrows() && old_col < mat.ncols() {
                        new_mat[[new_row, new_col]] = mat[[old_row, old_col]];
                    }
                }
                mat = new_mat;
            }

            for (&pos, &val) in positions.iter().zip(rhs_vals.iter()) {
                let row = pos % mat.nrows();
                let col = pos / mat.nrows();
                mat[[row, col]] = val;
            }

            env.insert(name.to_string(), Value::ComplexMatrix(Box::new(mat)));
        }
        2 => {
            let (nrows, ncols) = match env.get(name) {
                Some(Value::ComplexMatrix(m)) => (m.nrows(), m.ncols()),
                Some(Value::Matrix(m)) => (m.nrows(), m.ncols()),
                Some(Value::Scalar(_)) => (1, 1),
                None | Some(Value::Void) => (0, 0),
                Some(_) => {
                    return Err(format!(
                        "'{name}' is not a matrix; cannot use () indexed assignment"
                    ));
                }
            };

            let (ridx, cidx) = {
                let _owned_r;
                let env_r: &Env = if crate::eval::contains_end(&indices[0]) {
                    _owned_r = write_env_with_end(env, nrows);
                    &_owned_r
                } else {
                    env
                };
                let _owned_c;
                let env_c: &Env = if crate::eval::contains_end(&indices[1]) {
                    _owned_c = write_env_with_end(env, ncols);
                    &_owned_c
                } else {
                    env
                };
                (
                    resolve_write_dim(&indices[0], nrows, env_r, io)?,
                    resolve_write_dim(&indices[1], ncols, env_c, io)?,
                )
            };

            let rows: Vec<usize> = match ridx {
                WriteIdx::All => (0..nrows.max(1)).collect(),
                WriteIdx::Positions(p) => p,
            };
            let cols: Vec<usize> = match cidx {
                WriteIdx::All => (0..ncols.max(1)).collect(),
                WriteIdx::Positions(p) => p,
            };

            let req_rows = rows
                .iter()
                .copied()
                .max()
                .map(|m| m + 1)
                .unwrap_or(0)
                .max(nrows);
            let req_cols = cols
                .iter()
                .copied()
                .max()
                .map(|m| m + 1)
                .unwrap_or(0)
                .max(ncols);

            let n_sel = rows.len() * cols.len();
            let rhs_vals = rhs_to_complex(&rhs, n_sel)?;

            let mut mat = take_as_complex(name, env)?;

            if req_rows != nrows || req_cols != ncols {
                let mut new_mat = Array2::<Complex<f64>>::zeros((req_rows, req_cols));
                for r in 0..nrows {
                    for c in 0..ncols {
                        if r < mat.nrows() && c < mat.ncols() {
                            new_mat[[r, c]] = mat[[r, c]];
                        }
                    }
                }
                mat = new_mat;
            }

            let mut k = 0;
            for &r in &rows {
                for &c in &cols {
                    mat[[r, c]] = rhs_vals[k];
                    k += 1;
                }
            }

            env.insert(name.to_string(), Value::ComplexMatrix(Box::new(mat)));
        }
        _ => return Err("Indexed assignment supports at most 2 indices".to_string()),
    }
    Ok(())
}