elly_core/

eval.rs

//! Naive tree-walking evaluator for the first Elly subset.
//!
//! Uses call-by-value evaluation. Environments are persistent linked lists of
//! bindings shared via `Rc` for efficient closure capture.

use alloc::boxed::Box;
use alloc::rc::Rc;
use alloc::vec::Vec;

use rpds::{HashTrieMap, Vector};

use crate::ast::{recur_body, Captures, Expr, ModuleData, Pattern, Text};
use crate::builtins;

pub use crate::builtins::Builtin;
pub use crate::eval_env::{Ctx, Env, EnvNode, EnvRef};
use crate::eval_match::match_pattern;
pub use crate::value::{HostCall, HostFn, ObjectData, Value};

/// Evaluates the `__main` body of a module instance in its own environment.
/// Returns `Ok(None)` if no body is declared (e.g., a library).
///
/// This implements "runnable" module semantics: [`crate::load_module`] instantiates
/// modules without evaluating their bodies, ensuring `__main` is only executed
/// when explicitly targeted by a runner.
///
/// The body executes in the instance's [`Module`](EnvNode::Module) terminal.
/// As it is not a member, it has no reserved ID. Non-module instances raise
/// `.not_a_module`. Result interpretation is handled by the runner; see
/// `docs/done/2026-08-14_elly-run.md`.
pub fn eval_main(instance: &Value, ctx: &Ctx) -> Result<Option<Value>, Raised> {
    let Value::Module(home) = instance else {
        return Err(Raised::symbol("not_a_module"));
    };
    let EnvNode::Module { data, .. } = &**home else {
        unreachable!("a module value always holds a module terminal")
    };
    let Some(body) = data.body() else {
        return Ok(None);
    };
    let result = eval_env(body, &Env::from_ref(home.clone()), ctx)?;
    Ok(Some(result))
}

/// Value unwinding through the single error channel (see `docs/elly-spec.md`).
///
/// - `Error(v)`: Genuine failure (host abort or `__Err.raise v`). Propagates
///   past `__match`.
/// - `NoMatch(v)`: Pattern refutation from `match_pattern`. Only `__match` catches
///   this, falling through to its fallback. Other boundaries treat it as `Error(v)`,
///   surfacing the original error `v`.
///
/// Kinds are distinguished by construction; user code can only raise `Error`,
/// preventing forged `NoMatch` signals.
#[derive(Debug, Clone)]
pub enum Raised {
    /// A genuine error, propagated by `__match`.
    Error(Value),
    /// A pattern refutation carrying the original error it decays to when uncaught.
    NoMatch(Value),
}

impl Raised {
    /// carrying `tag` (stored without its dot) as the *original* error it stands for.
    /// `__match` catches it and falls through; uncaught, it decays to `.tag`.
    pub(crate) fn no_match(tag: &'static str) -> Raised {
        Raised::NoMatch(Value::Symbol(Text::from_static(tag)))
    }

    /// Raise one of the host-failure symbol tags (stored without its leading dot) as
    /// a genuine `Error`. The tag is a `'static` literal, so it becomes a
    /// zero-cost borrowed [`Text`] via `from_static`.
    pub(crate) fn symbol(tag: &'static str) -> Raised {
        Raised::Error(Value::Symbol(Text::from_static(tag)))
    }

    /// Returns the carried payload regardless of the `Raised` kind.
    pub fn value(&self) -> &Value {
        match self {
            Raised::Error(v) | Raised::NoMatch(v) => v,
        }
    }

    /// Consumes the `Raised` value into its payload.
    pub fn into_value(self) -> Value {
        match self {
            Raised::Error(v) | Raised::NoMatch(v) => v,
        }
    }
}

/// Evaluate an expression in the empty environment.
///
/// The [`Ctx`] threaded through evaluation carries the per-runtime **unique-id
/// source**: each `&`-abstraction stamps its closure with the next id, giving
/// callables an identity for equality/order.
pub fn eval(expr: &Expr) -> Result<Value, Raised> {
    let ctx = Ctx::new();
    eval_env(expr, &Env::EMPTY, &ctx)
}

/// Apply a value to a single argument — the public entry point behind a host's
/// "call this value" surface (e.g. the Python bindings' `elly.Fun.__call__`).
///
/// This is the same application step the evaluator uses internally (`apply_n`
/// with one argument): a closure call, list projection, or one step toward
/// saturating a builtin. Since values are `'static`-owned, `f` and `arg` may come
/// from different programs. A fresh [`Ctx`] is used, mirroring [`eval`], so any
/// closures minted while running the application are stamped from its id source.
/// Use [`apply_with`] to apply under a context whose ids continue an earlier
/// one's.
pub fn apply(f: &Value, arg: Value) -> Result<Value, Raised> {
    apply_with(f, arg, &Ctx::new())
}

/// Applies a value to a single argument using a caller-supplied [`Ctx`].
/// This ensures identities minted by the call continue the provided context's
/// ID source rather than restarting at zero. Required for hosts that manage
/// callables across multiple `apply` calls to avoid ID collisions.
pub fn apply_with(f: &Value, arg: Value, ctx: &Ctx) -> Result<Value, Raised> {
    apply1(f.clone(), arg, ctx)
}

/// Evaluates an expression in a given environment and context.
/// Public entry point for host evaluation (e.g., `elly.Env.eval`).
pub fn eval_env(expr: &Expr, env: &Env, ctx: &Ctx) -> Result<Value, Raised> {
    match expr {
        // Resolved reference: look up value by index.
        Expr::Local { index, .. } => Ok(env.lookup(*index)),
        // Resolver ensures all names are rewritten to `Expr::Local` before evaluation.
        Expr::Name(n) => unreachable!("unresolved name {:?} reached eval", n),
        // Module sibling reference (see [`mod_item`]).
        Expr::ModItem { index, depth, .. } => mod_item(env, *index, *depth, ctx),
        // Home-module leaf (see [`home_leaf`]).
        Expr::Home { leaf, depth } => env.home_leaf(*leaf, *depth),
        // Recursive binding group (see [`recur`]).
        Expr::Recur(r) => recur(r, env, ctx),
        // Block evaluation (see [`eval_block`]). Outlined to optimize I-cache.
        Expr::Block(clauses) => eval_block(clauses, env, ctx),
        // Builtin operation. 0-arity builtins execute immediately; others return
        // a `Builtin` awaiting arguments.
        Expr::Builtin(op) => {
            if op.arity() == 0 {
                builtins::invoke(*op, &[], ctx)
            } else {
                // Avoid `with_capacity` to prevent unnecessary allocations during
                // curried application cloning.
                Ok(Value::Builtin {
                    op: *op,
                    args: Vec::new(),
                })
            }
        }
        Expr::Int(n) => Ok(Value::from_bigint_ref(n)),
        Expr::Symbol(s) => Ok(Value::Symbol(s.clone())),
        // String handles are shared and pre-decoded.
        Expr::Str(s) => Ok(Value::Str(s.clone())),
        Expr::Unit => Ok(Value::Unit),
        Expr::List(elems) => {
            let mut vs = Vector::new();
            for e in elems {
                let elem = eval_env(e, env, ctx)?;
                vs.push_back_mut(elem);
            }
            Ok(Value::List(vs))
        }
        // Map literal: evaluate keys and values in source order. Later entries
        // with the same key overwrite previous ones.
        Expr::Map(entries) => {
            let mut m = HashTrieMap::new();
            for (k, v) in entries {
                let kv = eval_env(k, env, ctx)?;
                let vv = eval_env(v, env, ctx)?;
                m.insert_mut(kv, vv);
            }
            Ok(Value::Map(m))
        }
        // Closure creation: captures free variables according to the resolution plan.
        // `Captures::Chain` shares the environment; `Captures::Frame` creates a new frame.
        Expr::Abs(code) => {
            let env = match &code.captures {
                Captures::Chain => env.clone(),
                Captures::Frame(plan) => env.capture_env(plan, ctx),
                Captures::Unresolved => unreachable!("unresolved abstraction reached eval"),
            };
            Ok(Value::Closure {
                id: ctx.next_id(),
                code: Rc::clone(code),
                applied: 0,
                env,
            })
        }
        // Call-by-value application. Callee and arguments are evaluated strictly
        // left-to-right. Small arities (≤ 4) are handled on the stack to avoid
        // heap allocation for the argument buffer.
        Expr::App(items) => {
            let callee = eval_env(&items[0], env, ctx)?;
            let arg_exprs = &items[1..];
            match arg_exprs {
                [a] => {
                    let arg = eval_env(a, env, ctx)?;
                    apply1(callee, arg, ctx)
                }
                [a, b] => {
                    let va = eval_env(a, env, ctx)?;
                    let vb = eval_env(b, env, ctx)?;
                    apply_n(callee, &[va, vb], ctx)
                }
                [a, b, c] => {
                    let va = eval_env(a, env, ctx)?;
                    let vb = eval_env(b, env, ctx)?;
                    let vc = eval_env(c, env, ctx)?;
                    apply_n(callee, &[va, vb, vc], ctx)
                }
                [a, b, c, d] => {
                    let va = eval_env(a, env, ctx)?;
                    let vb = eval_env(b, env, ctx)?;
                    let vc = eval_env(c, env, ctx)?;
                    let vd = eval_env(d, env, ctx)?;
                    apply_n(callee, &[va, vb, vc, vd], ctx)
                }
                _ => {
                    let mut argv: Vec<Value> = Vec::with_capacity(arg_exprs.len());
                    for a in arg_exprs {
                        argv.push(eval_env(a, env, ctx)?);
                    }
                    apply_n(callee, &argv, ctx)
                }
            }
        }
        // Subject is evaluated once, then arms are tried in order.
        Expr::Case { subject, cases } => {
            let subj = eval_env(subject, env, ctx)?;
            run_arms(&subj, cases, env, ctx)
        }
    }
}

/// Tries case arms in order. `NoMatch` refutations fall through; other errors propagate.
/// If no arms match, `.no_match` is raised.
#[inline(never)]
fn run_arms(
    subj: &Value,
    cases: &[(Pattern, Expr)],
    env: &Env,
    ctx: &Ctx,
) -> Result<Value, Raised> {
    for (pat, body) in cases {
        match match_pattern(pat, subj, env.clone(), ctx) {
            // Not released explicitly: only 0.05% of node deaths happen here, and
            // holding the result across a release grows this recursive frame.
            Ok(arm_env) => return eval_env(body, &arm_env, ctx),
            Err(Raised::NoMatch(_)) => continue,
            Err(e) => return Err(e),
        }
    }
    Err(Raised::no_match("no_match"))
}

/// Specialized path for single-argument application. Used by the call spine,
/// fold builtins, and match clauses. Binds one parameter, produces a partial
/// closure, gathers a builtin argument, or projects a list.
pub(crate) fn apply1(fv: Value, av: Value, ctx: &Ctx) -> Result<Value, Raised> {
    match fv {
        Value::Closure {
            code, applied, env, ..
        } => {
            let start = applied as usize;
            // Bind argument and extend environment.
            let call_env = match_pattern(&code.head[start], &av, env, ctx)?;
            if start + 1 < code.head.len() {
                // Return partial closure with updated applied count and environment.
                return Ok(Value::Closure {
                    id: ctx.next_id(),
                    code,
                    applied: applied + 1,
                    env: call_env,
                });
            }
            let result = eval_env(&code.body, &call_env, ctx);
            ctx.release(call_env);
            result
        }
        Value::Builtin {
            op,
            args: mut gathered,
        } => {
            // Unary builtins saturate from the stack.
            if gathered.is_empty() && op.arity() == 1 {
                return builtins::invoke(op, &[av], ctx);
            }
            gathered.push(av);
            if gathered.len() == op.arity() {
                builtins::invoke(op, &gathered, ctx)
            } else {
                Ok(Value::Builtin { op, args: gathered })
            }
        }
        Value::HostFn {
            code,
            args: gathered,
        } => {
            if gathered.is_empty() && code.arity == 1 {
                return (code.f)(&[av], ctx);
            }
            let gathered = extended(&gathered, &[av]);
            if gathered.len() == code.arity {
                (code.f)(&gathered, ctx)
            } else {
                Ok(Value::HostFn {
                    code,
                    args: gathered,
                })
            }
        }
        // Materialize item when a module is applied to a symbol.
        Value::Module(home) => match av {
            Value::Symbol(s) => materialize(&Env::from_ref(home), &s, ctx),
            _ => Err(Raised::symbol("not_applicable")),
        },
        // Dispatch via prototype for all other types.
        fv => receiver(fv, &av, &[], ctx),
    }
}

/// Applies a value to multiple arguments. Handles closures (multi-parameter
/// matching), builtins (gather until saturation), and list projections.
/// Over-application results loop onto the returned value.
///
/// Arguments are evaluated strictly left-to-right before matching patterns
/// left-to-right, ensuring evaluation errors surface before pattern refutations.
/// See `docs/done/2026-08-02_perf-less-currying.md` §3.
fn apply_n(mut fv: Value, mut args: &[Value], ctx: &Ctx) -> Result<Value, Raised> {
    while !args.is_empty() {
        match fv {
            // Matches arguments against remaining patterns left-to-right.
            // If arguments are exhausted, returns a partial closure with a fresh ID.
            // Otherwise, executes the body and loops leftover arguments onto the result.
            // Pattern misses raise `NoMatch`.
            Value::Closure {
                code, applied, env, ..
            } => {
                let start = applied as usize;
                let remaining = code.head.len() - start;
                let take = remaining.min(args.len());
                // Thread the env through each parameter match, consing bindings
                // onto the closure's captured (or partially-applied) env.
                let mut call_env = env;
                for (pat, arg) in code.head[start..start + take].iter().zip(&args[..take]) {
                    call_env = match_pattern(pat, arg, call_env, ctx)?;
                }
                if take < remaining {
                    // Partial: no body runs yet; mint a fresh identity.
                    return Ok(Value::Closure {
                        id: ctx.next_id(),
                        code,
                        applied: applied + take as u8,
                        env: call_env,
                    });
                }
                let result = eval_env(&code.body, &call_env, ctx);
                ctx.release(call_env);
                fv = result?;
                args = &args[take..];
            }
            // Gathers arguments and invokes once saturated, looping leftovers onto the result.
            // If the argument spine satisfies the arity immediately, it invokes directly
            // from the slice to avoid `Value::Builtin` allocation.
            Value::Builtin {
                op,
                args: mut gathered,
            } => {
                let arity = op.arity();
                if gathered.is_empty() && args.len() >= arity {
                    fv = builtins::invoke(op, &args[..arity], ctx)?;
                    args = &args[arity..];
                } else {
                    let take = (arity - gathered.len()).min(args.len());
                    gathered.extend(args[..take].iter().cloned());
                    if gathered.len() < arity {
                        return Ok(Value::Builtin { op, args: gathered });
                    }
                    fv = builtins::invoke(op, &gathered, ctx)?;
                    args = &args[take..];
                }
            }
            // Similar gather-and-fire loop as builtins, dispatching via the host callback.
            Value::HostFn {
                code,
                args: gathered,
            } => {
                let arity = code.arity;
                if gathered.is_empty() && args.len() >= arity {
                    fv = (code.f)(&args[..arity], ctx)?;
                    args = &args[arity..];
                } else {
                    let take = (arity - gathered.len()).min(args.len());
                    let gathered = extended(&gathered, &args[..take]);
                    if gathered.len() < arity {
                        return Ok(Value::HostFn {
                            code,
                            args: gathered,
                        });
                    }
                    fv = (code.f)(&gathered, ctx)?;
                    args = &args[take..];
                }
            }
            // Materializes an item when applied to a symbol; leftovers loop onto the result.
            Value::Module(home) => {
                match &args[0] {
                    Value::Symbol(s) => fv = materialize(&Env::from_ref(home), s, ctx)?,
                    _ => return Err(Raised::symbol("not_applicable")),
                }
                args = &args[1..];
            }
            // Dispatches by passing the entire remaining argument spine to the
            // method in one call (see [`receiver`]).
            fv => return receiver(fv, &args[0], &args[1..], ctx),
        }
    }
    Ok(fv)
}

/// Concatenates `prefix` and `more` into a single allocation.
/// Used by [`Value::HostFn`] for efficient argument gathering during partial application.
fn extended(prefix: &[Value], more: &[Value]) -> Box<[Value]> {
    let mut all = Vec::with_capacity(prefix.len() + more.len());
    all.extend_from_slice(prefix);
    all.extend_from_slice(more);
    all.into_boxed_slice()
}

/// Returns the prototype of a value. Objects use their own prototype; others
/// use the corresponding builtin module, providing a nominal type for all values.
///
/// Iotas resolve to their declaring module, allowing them to be treated as
/// objects of that module. Callables (closures, builtins, host functions)
/// resolve to `__Fun`.
pub(crate) fn proto_of(v: &Value, ctx: &Ctx) -> Value {
    match v {
        Value::Object(obj) => obj.proto(),
        Value::Iota { home, .. } => Value::Module(home.clone()),
        Value::I64(_) | Value::BigInt(_) => ctx.builtin_module(Builtin::Int),
        Value::Symbol(_) => ctx.builtin_module(Builtin::Sym),
        Value::Str(_) => ctx.builtin_module(Builtin::Str),
        Value::Unit => ctx.builtin_module(Builtin::Unit),
        Value::List(_) => ctx.builtin_module(Builtin::List),
        Value::Map(_) => ctx.builtin_module(Builtin::Map),
        Value::Closure { .. } | Value::Builtin { .. } | Value::HostFn { .. } => {
            ctx.builtin_module(Builtin::Fun)
        }
        Value::Module(_) => ctx.builtin_module(Builtin::Mod),
    }
}

/// Whether `value`'s prototype is the module `expr` names — the general form of an
/// `as <Proto>` pattern, where [`ProtoRef::Kind`] is the compiled one. A reference
/// that is not a module raises `.not_a_module`: it is a mistake about the pattern
/// rather than about the subject, so it is a real error and not a refutation.
///
/// Outlined for the reason [`receiver`] is: `match_pattern` is on every call's
/// path, and its arms pay for each other's code size.
#[inline(never)]
pub(crate) fn proto_is(expr: &Expr, value: &Value, env: &Env, ctx: &Ctx) -> Result<bool, Raised> {
    let expected = eval_env(expr, env, ctx)?;
    if !matches!(expected, Value::Module(_)) {
        return Err(Raised::symbol("not_a_module"));
    }
    Ok(proto_of(value, ctx) == expected)
}

/// Resolves a module sibling reference by walking to the home module and
/// materializing the item at `index`.
///
/// The index is assigned during resolution against the module's sorted table,
/// enabling direct slice access. Only module-item bodies contain `ModItem`,
/// and they always run under a `Module` home terminal, which is found by
/// walking through captured frames.
///
/// Outlined to maintain I-cache residency of `eval_env`.
///
/// If the index is past the item table, it is treated as an iota, which is
/// derived as a pair of the terminal and position.
///
/// `depth` specifies how many terminals to skip to find the owning module.
/// A `recur` group nested in a module body adds a terminal to the chain, requiring
/// a skip for the enclosing module's items.
#[inline(never)]
fn mod_item(env: &Env, index: u32, depth: u32, ctx: &Ctx) -> Result<Value, Raised> {
    let (env, home, data, id_base) = env
        .find_module(depth)
        .ok_or_else(|| Raised::symbol("no_module"))?;
    let Some(body) = data.item(index) else {
        // Handle iotas: derived from terminal identity and index.
        let index = index - data.len() as u32;
        if data.iota(index).is_none() {
            return Err(Raised::symbol("missing_property"));
        }
        return Ok(Value::Iota {
            home: home.clone(),
            index,
        });
    };
    materialize_body(body, env, id_base, index, ctx)
}

/// Evaluates a `recur` group by creating a `Module` terminal over the
/// current environment and executing the body.
///
/// This is instantiation with a cons-shaped frame, avoiding copies by
/// sharing the lexical environment. ID blocks are reserved per evaluation,
/// ensuring different activations of the same `recur` group have distinct
/// item identities. Bindings are materialized on reference.
#[inline(never)]
fn recur(group: &Rc<ModuleData>, env: &Env, ctx: &Ctx) -> Result<Value, Raised> {
    let home = EnvRef::new(EnvNode::Module {
        id_base: ctx.reserve_ids(group.len() as u64),
        data: Rc::clone(group),
        frame: env.clone(),
    });
    eval_env(recur_body(group), &Env::from_ref(home), ctx)
}

/// Evaluates a block by threading the environment through clauses.
/// Bindings extend the environment for subsequent clauses; other clauses
/// execute for effect. The value of the final clause is returned.
fn eval_block(clauses: &[(Option<Pattern>, Expr)], env: &Env, ctx: &Ctx) -> Result<Value, Raised> {
    let Some((last, leading)) = clauses.split_last() else {
        return Ok(Value::Unit);
    };
    let mut env = env.clone();
    for clause in leading {
        match clause {
            (Some(pat), value) => {
                let v = eval_env(value, &env, ctx)?;
                env = match_pattern(pat, &v, env, ctx)?;
            }
            (None, value) => {
                eval_env(value, &env, ctx)?;
            }
        }
    }
    match last {
        (None, value) => {
            let result = eval_env(value, &env, ctx);
            ctx.release(env);
            result
        }
        (Some(pat), value) => {
            let v = eval_env(value, &env, ctx)?;
            ctx.release(match_pattern(pat, &v, env, ctx)?);
            Ok(v)
        }
    }
}

/// Instantiates a compiled module, creating its [`Module`](EnvNode::Module)
/// terminal and returning it as a [`Value::Module`].
///
/// This assigns the module an identity (fresh `Rc`) and reserves its ID block
/// so items can be stamped with stable IDs (see `materialize_body`).
///
/// `frame` provides outer values against [`ModuleData::frame_names`]. A length
/// mismatch raises `.module_arity`. The frame is stored as a flat [`Frame`](EnvNode::Frame),
/// though `recur` may build the terminal directly.
pub fn instantiate(data: Rc<ModuleData>, frame: &[Value], ctx: &Ctx) -> Result<Value, Raised> {
    if frame.len() != data.frame_names().len() {
        return Err(Raised::symbol("module_arity"));
    }
    let id_base = ctx.reserve_ids(data.len() as u64);
    let frame = if frame.is_empty() {
        Env::EMPTY
    } else {
        Env::EMPTY.frame(Box::from(frame))
    };
    Ok(Value::Module(EnvRef::new(EnvNode::Module {
        data,
        id_base,
        frame,
    })))
}

/// Evaluates an item's body in its module terminal. This is the common
/// path for [`mod_item`] and [`materialize`].
///
/// Literal abstraction bodies are built directly with the item's reserved
/// ID (`id_base + index`), ensuring multiple accesses produce equal closures.
/// This avoids `eval_env` dispatch and `Ctx` counter writes for performance.
///
/// Only function definitions claim the item's identity. Forwarded callables
/// retain their original identity, while data items or nested closures are
/// processed via `eval_env`.
#[inline]
fn materialize_body(
    body: &Expr,
    env: &Env,
    id_base: u64,
    index: u32,
    ctx: &Ctx,
) -> Result<Value, Raised> {
    if let Expr::Abs(code) = body {
        let env1 = match &code.captures {
            Captures::Chain => env.clone(),
            Captures::Frame(plan) => env.capture_env(plan, ctx),
            Captures::Unresolved => unreachable!("unresolved abstraction reached eval"),
        };
        return Ok(Value::Closure {
            id: id_base + index as u64,
            code: Rc::clone(code),
            applied: 0,
            env: env1,
        });
    }
    eval_env(body, env, ctx)
}

/// Materializes the item named `name` from the module object `home`.
/// Binary-searches for the index and evaluates the body in the terminal.
/// Uses the object's own node as the terminal to avoid environment allocation.
/// Raises `.missing_property` if the name is absent.
fn materialize(env: &Env, name: &Text, ctx: &Ctx) -> Result<Value, Raised> {
    let (moddata, id_base) = env
        .as_module()
        .expect("a module object always holds a module terminal");
    let index = moddata
        .index_of(name)
        .ok_or_else(|| Raised::symbol("missing_property"))?;
    let body = moddata.item(index).expect("index_of returned a live index");
    materialize_body(body, env, id_base, index, ctx)
}

/// Applies a receiver to a symbol. This is the dispatch path for all non-callable,
/// non-module values. The symbol identifies a member of the receiver's prototype,
/// and the receiver is passed as an argument. [`proto_of`] ensures this is total.
///
/// List projection takes precedence: numeric symbols on lists project indices.
/// Other symbols dispatch to `__List`.
///
/// Non-symbol arguments raise `.not_applicable`.
///
/// Outlined to maintain I-cache residency in `apply1` and `apply_n`.
#[inline(never)]
fn receiver(this: Value, name: &Value, rest: &[Value], ctx: &Ctx) -> Result<Value, Raised> {
    let Value::Symbol(s) = name else {
        return Err(Raised::symbol("not_applicable"));
    };
    if let Value::List(elems) = &this {
        if is_index(s) {
            let projected = project(elems, s)?;
            return apply_n(projected, rest, ctx);
        }
    }
    let proto = if let Value::Object(obj) = &this {
        obj.proto.clone()
    } else if let Value::Module(home) = proto_of(&this, ctx) {
        home
    } else {
        unreachable!("a prototype is always a module value")
    };
    dispatch(proto, this, s, rest, ctx)
}

/// Dispatches a method by materializing `name` from `proto` and applying it
/// to the receiver and any remaining arguments.
///
/// Example: `x .m a b` is equivalent to `(materialize (proto of x) .m) x a b`.
///
/// The lookup is a binary search over the item table, ensuring locals are private.
/// Arguments are handled similarly to the call spine in `eval_env`, with small
/// arities processed on the stack.
fn dispatch(
    proto: EnvRef,
    this: Value,
    name: &Text,
    rest: &[Value],
    ctx: &Ctx,
) -> Result<Value, Raised> {
    let method = materialize(&Env::from_ref(proto), name, ctx)?;
    match rest {
        [] => apply1(method, this, ctx),
        [a] => apply_n(method, &[this, a.clone()], ctx),
        [a, b] => apply_n(method, &[this, a.clone(), b.clone()], ctx),
        [a, b, c] => apply_n(method, &[this, a.clone(), b.clone(), c.clone()], ctx),
        _ => {
            let mut all: Vec<Value> = Vec::with_capacity(rest.len() + 1);
            all.push(this);
            all.extend_from_slice(rest);
            apply_n(method, &all, ctx)
        }
    }
}

/// Whether `sym` (a symbol's text, stored without its dot) is a **projection**
/// index — all ASCII digits, so `.0` and `.12` are projections while `.get` and
/// `.size` are member names. The two spaces are disjoint by shape, which is what
/// lets a list carry both (see [`receiver`]).
fn is_index(sym: &str) -> bool {
    !sym.is_empty() && sym.bytes().all(|b| b.is_ascii_digit())
}

/// Projects the element at index `sym` from a list.
fn project(elems: &Vector<Value>, sym: &str) -> Result<Value, Raised> {
    let idx: usize = sym.parse().map_err(|_| Raised::symbol("bad_projection"))?;
    elems
        .get(idx)
        .cloned()
        .ok_or_else(|| Raised::symbol("projection_out_of_range"))
}