cljrs_runtime/interp/

special.rs

//! Special form evaluators.

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

use crate::builtins::form::{
    expand_pairs, expand_reader_conds, expand_reader_conds_cow, form_to_value, resolve_auto_forms,
    select_reader_cond,
};
use crate::env::env::{Env, RequireRefer, RequireSpec};
use crate::env::error::{EvalError, EvalResult};
use crate::env::loader::load_ns;
use crate::interp::destructure::bind_pattern;
use crate::interp::eval::{eval, eval_body, is_special_form};
use cljrs_gc::GcPtr;
use cljrs_reader::Form;
use cljrs_reader::form::FormKind;
use cljrs_value::error::ExceptionInfo;
use cljrs_value::{
    CljxFn, CljxFnArity, CljxFuture, FutureState, Keyword, MapValue, Protocol, ProtocolMethod,
    ReferClojureFilter, TypeHint, Value, ValueError,
};

/// Dispatch to the right special-form handler.
pub fn eval_special(head: &str, args: &[Form], env: &mut Env) -> EvalResult {
    crate::env::policy::check_special(head)?;
    match head {
        "def" => eval_def(args, env),
        "fn*" | "fn" => eval_fn(args, env),
        "if" => eval_if(args, env),
        "do" => eval_body(args, env),
        "let*" | "let" => eval_let(args, env),
        "loop*" | "loop" => eval_loop(args, env),
        "recur" => eval_recur(args, env),
        "quote" => eval_quote(args, env),
        "var" => eval_var(args, env),
        "set!" => eval_set_bang(args, env),
        "throw" => eval_throw(args, env),
        "try" => eval_try(args, env),
        "defn" => eval_defn(args, env, false),
        "defn-" => eval_defn(args, env, true),
        "defmacro" => eval_defmacro(args, env),
        "defonce" => eval_defonce(args, env),
        "and" => eval_and(args, env),
        "or" => eval_or(args, env),
        "." => Err(EvalError::Runtime("interop not yet implemented".into())),
        "ns" => eval_ns(args, env),
        "require" => eval_require(args, env),
        "letfn" => eval_letfn(args, env),
        "in-ns" => eval_in_ns(args, env),
        "alias" => eval_alias(args, env),
        "protocol*" => eval_protocol_star(args, env),
        "deftype*" => eval_deftype_star(args, env),
        "load-file" => eval_load_file(args, env),
        "binding" => eval_binding(args, env),
        "with-out-str" => eval_with_out_str(args, env),
        "await" => eval_await(args, env),
        _ => unreachable!("unknown special form: {head}"),
    }
}

// ── def ───────────────────────────────────────────────────────────────────────

fn eval_def(args: &[Form], env: &mut Env) -> EvalResult {
    let target = parse_def(args, env)?;
    let val = match target.value_form {
        Some(form) => {
            // Under no-gc: def value expressions go to the StaticArena since the
            // Var must outlive all scratch regions.
            #[cfg(feature = "no-gc")]
            let _static_ctx = cljrs_gc::alloc_ctx::StaticCtxGuard::new();
            eval(form, env)?
        }
        None => Value::Nil,
    };
    intern_def(target, val, env)
}

/// A parsed `(def name "doc"? value?)`: everything but the value itself.
///
/// Public, together with [`parse_def`] and [`intern_def`], so the async
/// evaluator (`cljrs-async`) can evaluate `value_form` with a yielding
/// evaluator and still share the rest of `def`.
pub struct DefTarget<'a> {
    pub name: String,
    /// Metadata from `^meta` on the name and the docstring, merged.
    pub meta: Option<Value>,
    /// The value expression; `None` for `(def name)`.
    pub value_form: Option<&'a Form>,
}

/// Parse the name, metadata and docstring of a `def` without evaluating its
/// value expression. `^{...}` metadata on the name *is* evaluated here.
pub fn parse_def<'a>(args: &'a [Form], env: &mut Env) -> EvalResult<DefTarget<'a>> {
    if args.is_empty() {
        return Err(EvalError::Runtime("def requires a name".into()));
    }
    let (name, meta_opt) = extract_def_name(&args[0], env)?;
    // Optional docstring: (def name "docstring" value)
    let (docstring, val_idx) = if args.len() > 2
        && let FormKind::Str(s) = &args[1].kind
    {
        (Some(s.clone()), 2)
    } else {
        (None, 1)
    };
    Ok(DefTarget {
        name,
        meta: merge_meta(meta_opt, docstring.as_deref().map(doc_meta)),
        value_form: args.get(val_idx),
    })
}

/// Intern `val` under a parsed `def` target in the current namespace.
pub fn intern_def(target: DefTarget<'_>, val: Value, env: &mut Env) -> EvalResult {
    let var = env
        .globals
        .intern(&env.current_ns, Arc::from(target.name.as_str()), val);
    if let Some(meta_val) = target.meta {
        var.get().set_meta(meta_val);
    }
    Ok(Value::Var(var))
}

/// The already-bound var a `defonce` named `name` would leave untouched, if
/// any.
pub fn defonce_existing(name: &str, env: &Env) -> Option<Value> {
    env.globals
        .lookup_var(&env.current_ns, name)
        .filter(|var| var.get().is_bound())
        .map(Value::Var)
}

/// Build a `{:doc "..."}` metadata map fragment for a docstring.
fn doc_meta(doc: &str) -> Value {
    Value::Map(MapValue::empty().assoc(
        Value::keyword(Keyword::parse("doc")),
        Value::string(doc.to_string()),
    ))
}

fn private_meta() -> Value {
    Value::Map(
        MapValue::empty().assoc(Value::keyword(Keyword::parse("private")), Value::Bool(true)),
    )
}

/// Build a `{:arglists ([x] [x y & more])}` metadata fragment from a
/// `Value::Fn`/`Value::Macro`'s parsed arities. `skip` elides leading fixed
/// params that aren't part of the public signature (defmacro's implicit
/// `&form`/`&env`).
fn arglists_meta(fn_val: &Value, skip: usize) -> Option<Value> {
    let arities = match fn_val {
        Value::Fn(f) => &f.get().arities,
        Value::Macro(f) => &f.get().arities,
        _ => return None,
    };
    let lists: Vec<Value> = arities
        .iter()
        .map(|a| {
            let mut syms: Vec<Value> = a
                .params
                .iter()
                .skip(skip)
                .map(|p| Value::symbol(cljrs_value::Symbol::simple(p.as_ref())))
                .collect();
            if let Some(rest) = &a.rest_param {
                syms.push(Value::symbol(cljrs_value::Symbol::simple("&")));
                syms.push(Value::symbol(cljrs_value::Symbol::simple(rest.as_ref())));
            }
            Value::Vector(GcPtr::new(cljrs_value::PersistentVector::from_iter(syms)))
        })
        .collect();
    Some(Value::Map(MapValue::empty().assoc(
        Value::keyword(Keyword::parse("arglists")),
        Value::Vector(GcPtr::new(cljrs_value::PersistentVector::from_iter(lists))),
    )))
}

/// Extract the def name and optional metadata from the name form.
fn extract_def_name(form: &Form, env: &mut Env) -> EvalResult<(String, Option<Value>)> {
    match &form.kind {
        FormKind::Symbol(s) => Ok((s.clone(), None)),
        // `^:a ^:b x` nests `Meta` forms; unwrap all, outer mark winning.
        FormKind::Meta(meta_form, inner) => {
            let meta_val = compile_meta_form(meta_form, env)?;
            let (name, inner_meta) = extract_def_name(inner, env)?;
            Ok((name, merge_meta(inner_meta, Some(meta_val))))
        }
        _ => Err(EvalError::Runtime("def name must be a symbol".into())),
    }
}

/// Expand a metadata shorthand form into a map value, evaluating the general
/// case (`^{:x (+ 1 2)}` → `{:x 3}`).
///
/// The shorthand table itself lives in [`crate::builtins::form`] and is shared
/// with the quoted position, which differs only in resolving that general case
/// as data instead.
pub fn compile_meta_form(meta: &Form, env: &mut Env) -> EvalResult<Value> {
    crate::builtins::form::expand_meta_annotation(meta, &mut |f| eval(f, env))
}

// ── fn* ───────────────────────────────────────────────────────────────────────

fn eval_fn(args: &[Form], env: &mut Env) -> EvalResult {
    // Peel any leading `^meta` wrappers, e.g. `(fn ^:async [..] ..)` or
    // `(fn ^:async name [..] ..)`, recording whether `:async` was requested.
    let mut is_async = false;
    let peeled: Vec<Form>;
    let args: &[Form] = if matches!(args.first().map(|f| &f.kind), Some(FormKind::Meta(..))) {
        let (metas, head) = args[0].peel_meta();
        is_async |= metas.iter().any(|m| m.requests_async());
        peeled = std::iter::once(head.clone())
            .chain(args[1..].iter().cloned())
            .collect();
        &peeled
    } else {
        args
    };

    let mut idx = 0;
    let mut name: Option<Arc<str>> = None;

    // Optional name.
    if let Some(FormKind::Symbol(s)) = args.first().map(|f| &f.kind)
        && !is_special_form(s)
    {
        name = Some(Arc::from(s.as_str()));
        idx = 1;
    }

    let rest = &args[idx..];
    if rest.is_empty() {
        return Err(EvalError::Runtime("fn* requires params and body".into()));
    }

    // A `^hint` on the params vector or on an arity clause is advisory — the
    // structural shape is the form underneath it.
    let arities = match &rest[0].unmeta().kind {
        FormKind::Vector(_) => {
            // Single arity: (fn* [params] body...)
            vec![parse_arity(&rest[0], &rest[1..])?]
        }
        FormKind::List(_) => {
            // Multi-arity: (fn* ([params] body...) ...)
            rest.iter()
                .map(|arity_form| {
                    if let Some(forms) = arity_form.as_list() {
                        if forms.is_empty() {
                            return Err(EvalError::Runtime("arity clause requires params".into()));
                        }
                        parse_arity(&forms[0], &forms[1..])
                    } else {
                        Err(EvalError::Runtime("expected arity clause (list)".into()))
                    }
                })
                .collect::<EvalResult<Vec<_>>>()?
        }
        _ => {
            return Err(EvalError::Runtime(
                "fn* expects vector or arity clauses".into(),
            ));
        }
    };

    // Capture closed-over locals.
    let (closed_over_names, closed_over_vals) = env.all_local_bindings();

    let mut cljrs_fn = CljxFn::new(
        name.clone(),
        arities,
        closed_over_names,
        closed_over_vals,
        false,
        Arc::clone(&env.current_ns),
    );
    cljrs_fn.is_async = is_async;

    env.on_fn_defined(&cljrs_fn);

    // Eagerly lower each arity to IR if the compiler is ready.
    //eager_lower_fn(&cljrs_fn, env);

    let mut ptr = GcPtr::new(cljrs_fn);
    // For named anonymous functions (fn g ...), store a back-pointer so that
    // the self-reference returned from the body is pointer-equal to the outer
    // binding — required for `(= f (f))` to be `true`.
    if ptr.get().name.is_some() {
        let self_clone = ptr.clone();
        ptr.get_mut().self_ptr = Some(self_clone);
    }
    Ok(Value::Fn(ptr))
}

/// Parse one arity: params-form and body forms.
pub fn parse_arity(params_form: &Form, body: &[Form]) -> EvalResult<CljxFnArity> {
    let Some(param_forms) = params_form.as_vector() else {
        return Err(EvalError::Runtime(
            "fn arity params must be a vector".into(),
        ));
    };

    let mut params: Vec<Arc<str>> = Vec::new();
    let mut param_hints: Vec<Option<TypeHint>> = Vec::new();
    let mut rest_param: Option<Arc<str>> = None;
    let mut rest_hint: Option<TypeHint> = None;
    let mut destructure_params: Vec<(usize, Form)> = Vec::new();
    let mut destructure_rest: Option<Form> = None;
    let mut saw_amp = false;

    for p in param_forms {
        // Peel a leading `^hint` (e.g. `^long x`, `^doubles a`) from the param,
        // resolving the `:tag` to a primitive `TypeHint`.  Unknown / non-primitive
        // tags resolve to `None` and are simply ignored (Clojure treats them as
        // advisory).  The unwrapped form keeps the existing symbol/destructure
        // handling unchanged.
        let (hint, p) = peel_param_hint(p);
        match &p.kind {
            FormKind::Symbol(s) if s == "&" => {
                saw_amp = true;
            }
            FormKind::Symbol(s) => {
                if saw_amp {
                    rest_param = Some(Arc::from(s.as_str()));
                    rest_hint = hint;
                    break;
                } else {
                    params.push(Arc::from(s.as_str()));
                    param_hints.push(hint);
                }
            }
            // Destructuring patterns: vectors and maps
            FormKind::Vector(_) | FormKind::Map(_) => {
                if saw_amp {
                    let gensym = format!("__destructure_rest_{}", params.len());
                    rest_param = Some(Arc::from(gensym.as_str()));
                    destructure_rest = Some(p.clone());
                    break;
                } else {
                    let idx = params.len();
                    let gensym = format!("__destructure_{idx}");
                    params.push(Arc::from(gensym.as_str()));
                    // Destructured params can't be primitive-tagged.
                    param_hints.push(None);
                    destructure_params.push((idx, p.clone()));
                }
            }
            _ => {
                return Err(EvalError::Runtime(
                    "fn params must be symbols, vectors, or maps".into(),
                ));
            }
        }
    }

    let body = desugar_pre_post_conditions(body);

    Ok(CljxFnArity {
        params,
        rest_param,
        body,
        destructure_params,
        destructure_rest,
        ir_arity_id: crate::interp::arity::fresh_arity_id(),
        param_hints,
        rest_hint,
    })
}

/// Desugar a `:pre`/`:post` conditions map at the head of a function body.
///
/// Clojure binds `%` to the return value inside `:post` conditions. This
/// transforms the raw body forms into equivalent assertion code so the
/// interpreter does not need to handle conditions separately at call time.
///
/// Input body (simplified):
/// ```text
/// [{:pre [(pos? x)] :post [(pos? %)]} (inc x)]
/// ```
/// Output body:
/// ```text
/// [(assert (pos? x))
///  (let* [% (inc x)]
///    (assert (pos? %))
///    %)]
/// ```
fn desugar_pre_post_conditions(body: &[Form]) -> Vec<Form> {
    let first = match body.first() {
        Some(f) => f,
        None => return body.to_vec(),
    };

    let entries = match first.as_map() {
        Some(entries) => entries,
        None => return body.to_vec(),
    };

    let mut pre_conds: Vec<Form> = Vec::new();
    let mut post_conds: Vec<Form> = Vec::new();
    let mut has_conditions = false;

    for chunk in entries.chunks(2) {
        if chunk.len() < 2 {
            break;
        }
        let (key, val) = (&chunk[0], &chunk[1]);
        match &key.kind {
            FormKind::Keyword(k) if k == "pre" => {
                if let FormKind::Vector(conds) = &val.kind {
                    pre_conds.extend_from_slice(conds);
                    has_conditions = true;
                }
            }
            FormKind::Keyword(k) if k == "post" => {
                if let FormKind::Vector(conds) = &val.kind {
                    post_conds.extend_from_slice(conds);
                    has_conditions = true;
                }
            }
            _ => {}
        }
    }

    if !has_conditions {
        return body.to_vec();
    }

    let real_body = &body[1..]; // strip the conditions map
    let span = first.span.clone();
    let mut new_body: Vec<Form> = Vec::new();

    // Emit (assert cond) for each :pre condition.
    for cond in &pre_conds {
        new_body.push(make_assert_call(cond, &span));
    }

    if post_conds.is_empty() {
        new_body.extend_from_slice(real_body);
    } else {
        // Wrap real body in (let* [% <body>] (assert post-cond)... %)
        // so that % refers to the return value inside :post conditions.
        let percent = Form::new(FormKind::Symbol("%".to_string()), span.clone());

        let body_expr = if real_body.len() == 1 {
            real_body[0].clone()
        } else {
            let mut do_forms = vec![Form::new(FormKind::Symbol("do".to_string()), span.clone())];
            do_forms.extend_from_slice(real_body);
            Form::new(FormKind::List(do_forms), span.clone())
        };

        let binding_vec = Form::new(
            FormKind::Vector(vec![percent.clone(), body_expr]),
            span.clone(),
        );

        let mut let_forms = vec![
            Form::new(FormKind::Symbol("let*".to_string()), span.clone()),
            binding_vec,
        ];
        for cond in &post_conds {
            let_forms.push(make_assert_call(cond, &span));
        }
        let_forms.push(percent);

        new_body.push(Form::new(FormKind::List(let_forms), span));
    }

    new_body
}

/// Build `(assert <cond>)` as a Form node.
fn make_assert_call(cond: &Form, span: &cljrs_types::span::Span) -> Form {
    Form::new(
        FormKind::List(vec![
            Form::new(FormKind::Symbol("assert".to_string()), span.clone()),
            cond.clone(),
        ]),
        span.clone(),
    )
}

/// Peel a `^hint` wrapper off a parameter form, returning the resolved
/// primitive [`TypeHint`] (if the tag is a recognized primitive) together with
/// the unwrapped inner form.  A param with no metadata returns `(None, form)`.
fn peel_param_hint(p: &Form) -> (Option<TypeHint>, &Form) {
    if let FormKind::Meta(meta, inner) = &p.kind {
        let hint = tag_name_of_meta(meta).and_then(|n| TypeHint::from_tag(&n));
        // Recurse in case of stacked metadata; the innermost form is the param.
        let (inner_hint, inner_form) = peel_param_hint(inner);
        (hint.or(inner_hint), inner_form)
    } else {
        (None, p)
    }
}

/// Extract the bare tag name from a `^meta` form: `^long` (symbol shorthand) or
/// `^{:tag long}` (explicit map).  Strips any namespace from the tag symbol.
fn tag_name_of_meta(meta: &Form) -> Option<Arc<str>> {
    match &meta.kind {
        // `^long x` — the metadata is a bare symbol naming the tag.
        FormKind::Symbol(s) => Some(strip_tag_ns(s)),
        // `^{:tag long} x` — pull the `:tag` entry out of the map literal.
        FormKind::Map(entries) => entries.chunks(2).find_map(|kv| {
            let is_tag = matches!(&kv[0].kind, FormKind::Keyword(k) if k == "tag");
            if !is_tag {
                return None;
            }
            match kv.get(1).map(|f| &f.kind) {
                Some(FormKind::Symbol(s)) => Some(strip_tag_ns(s)),
                Some(FormKind::Str(s)) => Some(strip_tag_ns(s)),
                _ => None,
            }
        }),
        _ => None,
    }
}

/// Strip a namespace prefix from a tag name (`clojure.core/long` → `long`).
fn strip_tag_ns(s: &str) -> Arc<str> {
    match s.rfind('/') {
        Some(pos) if pos + 1 < s.len() => Arc::from(&s[pos + 1..]),
        _ => Arc::from(s),
    }
}

// ── if ────────────────────────────────────────────────────────────────────────

fn eval_if(args: &[Form], env: &mut Env) -> EvalResult {
    if args.is_empty() {
        return Err(EvalError::Runtime("if requires a test".into()));
    }
    let test = eval(&args[0], env)?;
    let truthy = !matches!(test, Value::Nil | Value::Bool(false));
    if truthy {
        if args.len() > 1 {
            eval(&args[1], env)
        } else {
            Ok(Value::Nil)
        }
    } else if args.len() > 2 {
        eval(&args[2], env)
    } else {
        Ok(Value::Nil)
    }
}

// ── let* ──────────────────────────────────────────────────────────────────────

fn eval_let(args: &[Form], env: &mut Env) -> EvalResult {
    let bindings = match args.first().and_then(|f| f.as_vector()) {
        Some(v) => expand_pairs(v)
            .map_err(|_| EvalError::Runtime("let* binding vector must have even length".into()))?
            .into_owned(),
        None => return Err(EvalError::Runtime("let* requires a binding vector".into())),
    };

    let body = &args[1..];

    // Detect assoc/conj chains that can be virtualized.
    let chains = crate::interp::virtualize::detect_let_chains(&bindings);
    let virtualizable_chains = find_virtualizable_chains(&chains, &bindings, body);

    env.push_frame();

    let pairs: Vec<_> = bindings.chunks(2).collect();
    let mut i = 0;
    while i < pairs.len() {
        // Check if this binding starts a virtualizable chain.
        if let Some(chain) = virtualizable_chains.iter().find(|c| c.start == i) {
            match eval_virtualized_chain(chain, &pairs, env) {
                Ok(()) => {
                    i += chain.len;
                    continue;
                }
                Err(e) => {
                    env.pop_frame();
                    return Err(e);
                }
            }
        }

        // Normal evaluation.
        let pair = pairs[i];
        let val = match eval(&pair[1], env) {
            Ok(v) => v,
            Err(e) => {
                env.pop_frame();
                return Err(e);
            }
        };
        if let Err(e) = bind_pattern(&pair[0], val, env) {
            env.pop_frame();
            return Err(e);
        }
        i += 1;
    }

    let result = eval_body(body, env);
    env.pop_frame();
    result
}

/// Filter chains to only those that are safe to virtualize.
///
/// A chain is safe if no intermediate binding is used outside the chain
/// (i.e., it's only used as the collection argument of the next step).
fn find_virtualizable_chains<'a>(
    chains: &'a [crate::interp::virtualize::LetChain],
    bindings: &[Form],
    body: &[Form],
) -> Vec<&'a crate::interp::virtualize::LetChain> {
    chains
        .iter()
        .filter(|chain| {
            // Check that no intermediate (all except the last) is used in body
            // or in other bindings outside the chain.
            for j in chain.start..(chain.start + chain.len - 1) {
                let name = match &bindings[j * 2].kind {
                    FormKind::Symbol(s) => s.as_str(),
                    _ => return false,
                };
                if crate::interp::virtualize::binding_used_in_body(name, body) {
                    return false;
                }
                if crate::interp::virtualize::binding_used_in_other_bindings(
                    name,
                    bindings,
                    chain.start,
                    chain.len,
                ) {
                    return false;
                }
            }
            true
        })
        .collect()
}

/// Evaluate an assoc/conj chain using transient operations.
///
/// Instead of creating N intermediate persistent collections, we:
/// 1. Evaluate the root collection (first arg of the first assoc/conj)
/// 2. Convert to transient
/// 3. Apply each assoc!/conj! mutably
/// 4. Convert back to persistent
/// 5. Bind only the final name (and intermediate names point to intermediate
///    transient values for correctness, though they shouldn't be used).
fn eval_virtualized_chain(
    chain: &crate::interp::virtualize::LetChain,
    pairs: &[&[Form]],
    env: &mut Env,
) -> Result<(), EvalError> {
    use crate::builtins::transients::{
        builtin_assoc_bang, builtin_conj_bang, builtin_persistent_bang, builtin_transient,
    };

    // Step 1: Evaluate the root collection (first arg of the first call).
    let first_pair = pairs[chain.start];
    let first_expr_forms = match &first_pair[1].kind {
        FormKind::List(forms) => forms,
        _ => unreachable!("chain detection ensures this is a list"),
    };
    let root_collection = eval(&first_expr_forms[1], env)?;

    // Step 2: Convert to transient.
    let mut transient = match builtin_transient(std::slice::from_ref(&root_collection)) {
        Ok(t) => t,
        Err(_) => {
            // Collection doesn't support transients (e.g., sorted map).
            // Fall back to normal evaluation for the whole chain.
            return eval_chain_normally(chain, pairs, env);
        }
    };

    // Step 3: Apply each chain operation using transient mutation.
    for j in 0..chain.len {
        let pair_idx = chain.start + j;
        let pair = pairs[pair_idx];
        let expr_forms = match &pair[1].kind {
            FormKind::List(forms) => forms,
            _ => unreachable!(),
        };

        // Evaluate the non-collection arguments.
        let mut args = vec![transient.clone()];
        for arg_form in expr_forms.iter().skip(2) {
            args.push(eval(arg_form, env)?);
        }

        // Apply the transient operation.
        transient = match chain.ops[j] {
            crate::interp::virtualize::ChainOpKind::Assoc => {
                builtin_assoc_bang(&args).map_err(|e| EvalError::Runtime(e.to_string()))?
            }
            crate::interp::virtualize::ChainOpKind::Conj => {
                builtin_conj_bang(&args).map_err(|e| EvalError::Runtime(e.to_string()))?
            }
        };

        // Bind intermediate names to a placeholder (they shouldn't be used,
        // but we need them in the env for structural correctness).
        // Only the last binding gets the persistent result.
        if j < chain.len - 1 {
            let name = match &pair[0].kind {
                FormKind::Symbol(s) => s.clone(),
                _ => unreachable!(),
            };
            // Bind to nil as placeholder — intermediates are verified as unused.
            env.bind(Arc::from(name.as_str()), Value::Nil);
        }
    }

    // Step 4: Convert back to persistent.
    let persistent =
        builtin_persistent_bang(&[transient]).map_err(|e| EvalError::Runtime(e.to_string()))?;

    // Step 5: Bind the final name.
    let last_pair = pairs[chain.start + chain.len - 1];
    bind_pattern(&last_pair[0], persistent, env)?;

    Ok(())
}

/// Fallback: evaluate a chain using normal persistent operations.
fn eval_chain_normally(
    chain: &crate::interp::virtualize::LetChain,
    pairs: &[&[Form]],
    env: &mut Env,
) -> Result<(), EvalError> {
    for j in 0..chain.len {
        let pair_idx = chain.start + j;
        let pair = pairs[pair_idx];
        let val = eval(&pair[1], env)?;
        bind_pattern(&pair[0], val, env)?;
    }
    Ok(())
}

// ── loop* / recur ─────────────────────────────────────────────────────────────

pub fn eval_loop(args: &[Form], env: &mut Env) -> EvalResult {
    let bindings = match args.first().and_then(|f| f.as_vector()) {
        Some(v) => expand_pairs(v)
            .map_err(|_| EvalError::Runtime("loop* binding vector must have even length".into()))?
            .into_owned(),
        None => return Err(EvalError::Runtime("loop* requires a binding vector".into())),
    };

    let body = &args[1..];

    // Separate pattern forms and initial values.
    let patterns: Vec<Form> = bindings.iter().step_by(2).cloned().collect();
    let mut current_vals: Vec<Value> = Vec::new();

    // Evaluate initial values.
    for i in (1..bindings.len()).step_by(2) {
        current_vals.push(eval(&bindings[i], env)?);
    }

    loop {
        // Root current_vals so they survive GC — they're not yet bound in env.
        let _vals_root = crate::env::gc_roots::root_values(&current_vals);

        // GC safepoint on every loop iteration so tight recur loops
        // don't starve the collector.
        crate::env::gc_roots::gc_safepoint(env);

        // Under no-gc: push a fresh scratch region for this iteration.
        // Intermediates allocated in the body land here and are freed
        // after the iteration ends.
        #[cfg(feature = "no-gc")]
        let mut scratch = cljrs_gc::alloc_ctx::ScratchGuard::new();

        // Under GC: scope this iteration's heap allocations in a fresh alloc
        // frame.  Every value the body allocates is rooted (via ALLOC_ROOTS)
        // only until this frame drops at the end of the iteration; the
        // intermediates — and the previous iteration's now-dead recur values —
        // then become collectable, instead of being pinned for the lifetime of
        // the enclosing top-level form.  `result` (the return value or recur
        // values) is moved out before the frame drops and is re-rooted at the
        // top of the next iteration (`root_values`) or by the caller during
        // return unwinding; no GC safepoint runs in the interval, exactly as
        // the IR/JIT dispatch seam relies on (see `crate::tiered::apply`).
        #[cfg(not(feature = "no-gc"))]
        let _iter_frame = cljrs_gc::push_alloc_frame();

        env.push_frame();
        for (pat, val) in patterns.iter().zip(current_vals.iter()) {
            if let Err(e) = bind_pattern(pat, val.clone(), env) {
                env.pop_frame();
                return Err(e);
            }
        }

        // Under no-gc: pop scratch before tail expression so the return value
        // or recur args are allocated in the enclosing scope's context.
        #[cfg(not(feature = "no-gc"))]
        let result = eval_body_recur(body, env);
        #[cfg(feature = "no-gc")]
        let result = eval_body_with_scratch_loop(body, &mut scratch, env);

        env.pop_frame();
        // scratch / _iter_frame drop at the end of the iteration (after the
        // match below), freeing this iteration's intermediates.

        match result {
            Ok(v) => return Ok(v),
            Err(EvalError::Recur(new_vals)) => {
                if new_vals.len() != patterns.len() {
                    return Err(EvalError::Arity {
                        name: "recur".into(),
                        expected: patterns.len().to_string(),
                        got: new_vals.len(),
                    });
                }
                // new_vals were evaluated in the caller's context (scratch was
                // popped before the tail form), so they survive the reset.
                current_vals = new_vals;
            }
            Err(e) => return Err(e),
        }
    }
}

fn eval_recur(args: &[Form], env: &mut Env) -> EvalResult {
    let vals: Vec<Value> = args
        .iter()
        .map(|f| eval(f, env))
        .collect::<EvalResult<_>>()?;
    Err(EvalError::Recur(vals))
}

/// Eval body forms, propagating Recur without catching it.
pub fn eval_body_recur(body: &[Form], env: &mut Env) -> EvalResult {
    let mut result = Value::Nil;
    for form in body {
        result = eval(form, env)?;
    }
    Ok(result)
}

/// Under `no-gc`: eval loop body with scratch-region semantics.
///
/// Evaluates all non-tail forms inside the scratch region, then pops the
/// scratch before the tail (return/recur) expression so it lands in the
/// caller's context.
#[cfg(feature = "no-gc")]
fn eval_body_with_scratch_loop(
    body: &[Form],
    scratch: &mut cljrs_gc::alloc_ctx::ScratchGuard,
    env: &mut Env,
) -> EvalResult {
    if body.is_empty() {
        scratch.pop_for_return();
        return Ok(Value::Nil);
    }
    for form in &body[..body.len() - 1] {
        eval(form, env)?;
    }
    scratch.pop_for_return();
    eval(&body[body.len() - 1], env)
}

// ── quote ─────────────────────────────────────────────────────────────────────

fn eval_quote(args: &[Form], env: &Env) -> EvalResult {
    match args.first() {
        // `::kw` and an auto-resolved map's symbol keys resolve against the
        // reading namespace even under quote - the JVM resolves them at read
        // time, before quote can see them.
        Some(f) => form_to_value(&resolve_auto_forms(f, env)?),
        None => Err(EvalError::Runtime("quote requires an argument".into())),
    }
}

// ── var ───────────────────────────────────────────────────────────────────────

fn eval_var(args: &[Form], env: &mut Env) -> EvalResult {
    let sym = match args.first().map(|f| &f.kind) {
        Some(FormKind::Symbol(s)) => s.clone(),
        _ => return Err(EvalError::Runtime("var requires a symbol".into())),
    };
    let parsed = cljrs_value::Symbol::parse(&sym);
    let ns: Arc<str> = env.resolve_ns_or_current(parsed.namespace.as_deref());
    let name = parsed.name.as_ref();
    env.globals
        .lookup_var_in_ns(&ns, name)
        .map(Value::Var)
        .ok_or_else(|| EvalError::UnboundSymbol(sym))
}

// ── set! ──────────────────────────────────────────────────────────────────────

fn eval_set_bang(args: &[Form], env: &mut Env) -> EvalResult {
    let target = args
        .first()
        .ok_or_else(|| EvalError::Runtime("set! requires a target".into()))?;
    let val = if args.len() > 1 {
        eval(&args[1], env)?
    } else {
        Value::Nil
    };
    match &target.kind {
        FormKind::Symbol(sym) => set_bang_symbol(sym, val, env),
        _ => match set_bang_field_target(target) {
            Some((field, inst_form)) => {
                let inst = eval(inst_form, env)?;
                set_type_instance_field(&inst, field, val)
            }
            None => Err(set_bang_target_error()),
        },
    }
}

/// `(set! sym val)` for an already-evaluated `val`: a mutable deftype field in
/// scope, else the thread-local binding of the var `sym` names, else its root.
pub fn set_bang_symbol(sym: &str, val: Value, env: &mut Env) -> EvalResult {
    // A bare unqualified name inside a deftype method may be one of its
    // mutable fields; only if not does it fall through to var logic.
    if !sym.contains('/')
        && let Some(v) = try_set_mutable_field(env, sym, &val)?
    {
        return Ok(v);
    }
    let parsed = cljrs_value::Symbol::parse(sym);
    let ns = parsed.namespace.as_deref().unwrap_or(&env.current_ns);
    let var = env
        .globals
        .lookup_var_in_ns(ns, &parsed.name)
        .ok_or_else(|| EvalError::UnboundSymbol(sym.to_string()))?;
    // Prefer updating the thread-local binding if one exists.
    if !crate::env::dynamics::set_thread_local(&var, val.clone()) {
        var.get().bind(val.clone());
    }
    Ok(val)
}

/// For a `(set! (.-field inst) v)` target, the field name and the `inst`
/// form; `None` for any other non-symbol target.
pub fn set_bang_field_target(target: &Form) -> Option<(&str, &Form)> {
    match &target.kind {
        FormKind::List(parts) if parts.len() == 2 => match &parts[0].kind {
            FormKind::Symbol(op) if op.starts_with(".-") => Some((&op[2..], &parts[1])),
            _ => None,
        },
        _ => None,
    }
}

/// The error for a `set!` target that is neither a symbol nor `(.-field inst)`.
pub fn set_bang_target_error() -> EvalError {
    EvalError::Runtime("set! requires a symbol or (.-field inst) target".into())
}

/// If `sym` names a mutable field of the `__deftype_self__` instance in scope,
/// update its cell AND refresh the in-scope local snapshot, returning the new
/// value. `None` when `sym` is not such a field, so `set!` falls through to var
/// logic.
fn try_set_mutable_field(env: &mut Env, sym: &str, val: &Value) -> EvalResult<Option<Value>> {
    let Some(Value::TypeInstance(ti)) = env.lookup_local_frames(DEFTYPE_SELF) else {
        return Ok(None);
    };
    let Some(atom) = ti.get().mutable.clone() else {
        return Ok(None);
    };
    let key = Value::keyword(cljrs_value::Keyword::simple(sym));
    let Value::Map(map) = atom.get().deref() else {
        return Ok(None);
    };
    if map.get(&key).is_none() {
        return Ok(None);
    }
    atom.get().reset(Value::Map(map.assoc(key, val.clone())));
    // Keep the method's local snapshot consistent for later reads.
    env.bind(Arc::from(sym), val.clone());
    Ok(Some(val.clone()))
}

/// Set a mutable field on an explicit instance: `(set! (.-field inst) v)`.
pub fn set_type_instance_field(inst: &Value, field: &str, val: Value) -> EvalResult {
    let Value::TypeInstance(ti) = inst else {
        return Err(EvalError::Runtime(format!(
            "set! (.-{field} …): target is not a type instance"
        )));
    };
    let atom = ti.get().mutable.clone().ok_or_else(|| {
        EvalError::Runtime(format!("set! (.-{field} …): type has no mutable fields"))
    })?;
    let key = Value::keyword(cljrs_value::Keyword::simple(field));
    let map = match atom.get().deref() {
        Value::Map(m) => m,
        _ => MapValue::empty(),
    };
    if map.get(&key).is_none() {
        return Err(EvalError::Runtime(format!(
            "set!: {field} is not a mutable field"
        )));
    }
    atom.get().reset(Value::Map(map.assoc(key, val.clone())));
    Ok(val)
}

// ── throw ─────────────────────────────────────────────────────────────────────

fn eval_throw(args: &[Form], env: &mut Env) -> EvalResult {
    let val = match args.first() {
        Some(f) => eval(f, env)?,
        None => Value::Nil,
    };
    Err(throw_value(val))
}

/// The error `(throw val)` raises for an already-evaluated `val`.
///
/// Wraps non-error values in an ExceptionInfo so try/catch always sees a
/// Value::Error and ex-message / ex-data work uniformly inside the handler.
pub fn throw_value(val: Value) -> EvalError {
    let val = match val {
        Value::Error(_) => val,
        other => {
            let msg = format!("{}", other);
            Value::Error(GcPtr::new(ExceptionInfo::new(
                ValueError::Other(msg.clone()),
                msg,
                None,
                None,
            )))
        }
    };
    EvalError::Thrown(val)
}

// ── try ───────────────────────────────────────────────────────────────────────

/// A catch clause: `(catch Type binding body...)`.
///
/// Public so the async evaluator (`cljrs-async`) can reuse `parse_try_args` to
/// build a yielding `try`/`catch`.
pub struct CatchClause<'a> {
    pub type_sym: &'a str,
    pub binding: &'a str,
    pub body: &'a [Form],
}

/// Convert a non-Thrown EvalError into a `Value::Error` so it can be bound
/// inside a catch clause and inspected with `ex-message` / `ex-data`.
///
/// Public so the async evaluator can convert errors the same way `try` does.
pub fn eval_error_to_value(err: &EvalError) -> Value {
    let msg = err.to_string();
    Value::Error(GcPtr::new(ExceptionInfo::new(
        ValueError::Other(msg.clone()),
        msg,
        None,
        None,
    )))
}

/// Test whether the type symbol on a `(catch <Type> e ...)` clause matches a
/// thrown value. Type names are matched by their last `.`-separated segment so
/// fully-qualified names like `java.lang.Exception` work as well as bare ones.
pub fn catch_type_matches(type_name: &str, val: &Value) -> bool {
    let short = type_name.rsplit('.').next().unwrap_or(type_name);
    match short {
        // Catch-all (matches any value, error or not — back-compat).
        // `:default` is the ClojureScript universal catch keyword; it arrives
        // here as the keyword's name ("default") via `parse_try_args`.
        "Object" | "Exception" | "Throwable" | "Error" | "default" => true,
        // ExceptionInfo only matches actual ex-info / Exception values.
        "ExceptionInfo" => matches!(val, Value::Error(_)),
        _ => false,
    }
}

fn eval_try(args: &[Form], env: &mut Env) -> EvalResult {
    let (body, catches, fin_body) = parse_try_args(args);

    let mut result = eval_body(body, env);

    // Handle catch: never intercept Recur (loop trampoline signal).
    let err_opt = match std::mem::replace(&mut result, Ok(Value::Nil)) {
        Ok(v) => {
            result = Ok(v);
            None
        }
        Err(EvalError::Recur(args)) => {
            result = Err(EvalError::Recur(args));
            None
        }
        Err(EvalError::GasExhausted) => {
            result = Err(EvalError::GasExhausted);
            None
        }
        Err(other) => Some(other),
    };

    if let Some(err) = err_opt {
        let thrown_val = match err {
            EvalError::Thrown(v) => v,
            ref other => eval_error_to_value(other),
        };
        let mut handled = false;
        for c in &catches {
            if catch_type_matches(c.type_sym, &thrown_val) {
                env.push_frame();
                env.bind(Arc::from(c.binding), thrown_val.clone());
                result = eval_body(c.body, env);
                env.pop_frame();
                handled = true;
                break;
            }
        }
        if !handled {
            // No matching catch — re-throw.
            result = Err(EvalError::Thrown(thrown_val));
        }
    }

    // Always run finally.  Its normal (Ok) value is discarded — `try` returns
    // the body/catch result — but an exception thrown from `finally` supersedes
    // the pending result or exception (matching JVM/Clojure semantics).
    if !fin_body.is_empty() {
        eval_body(fin_body, env)?;
    }

    result
}

/// The class name or `:default` keyword naming what a `catch` clause catches.
fn catch_target(f: &Form) -> Option<&str> {
    f.as_symbol().or_else(|| f.as_keyword())
}

/// Split try args into (body, catch clauses, finally body).
///
/// Public so the async evaluator can parse `try` forms identically.
pub fn parse_try_args(args: &[Form]) -> (&[Form], Vec<CatchClause<'_>>, &[Form]) {
    let mut body_end = args.len();
    let mut catches: Vec<CatchClause<'_>> = Vec::new();
    let mut fin_body: &[Form] = &[];

    for (i, form) in args.iter().enumerate() {
        if let Some(parts) = form.as_list()
            && let Some(s) = parts.first().and_then(|f| f.as_symbol())
        {
            if s == "catch" {
                if i < body_end {
                    body_end = i;
                }
                // The catch type may be a symbol (`Throwable`, `java.lang.Exception`),
                // the ClojureScript `:default` catch-all keyword, or a reader
                // conditional `#?(:rust Exception :clj ...)` whose selected branch
                // resolves to one of those.
                let type_sym = match parts.get(1) {
                    Some(f) => match catch_target(f) {
                        Some(name) => name,
                        None => match &f.unmeta().kind {
                            FormKind::ReaderCond {
                                splicing: false,
                                clauses,
                            } => match select_reader_cond(clauses).and_then(catch_target) {
                                Some(name) => name,
                                None => continue,
                            },
                            _ => continue,
                        },
                    },
                    None => continue,
                };
                let binding = match parts.get(2).and_then(|f| f.as_symbol()) {
                    Some(s) => s,
                    None => continue,
                };
                catches.push(CatchClause {
                    type_sym,
                    binding,
                    body: &parts[3..],
                });
                continue;
            }
            if s == "finally" {
                if i < body_end {
                    body_end = i;
                }
                fin_body = &parts[1..];
                continue;
            }
        }
    }

    (&args[..body_end], catches, fin_body)
}

// ── defn ──────────────────────────────────────────────────────────────────────

pub fn eval_defn(args: &[Form], env: &mut Env, private: bool) -> EvalResult {
    // The name may carry reader metadata, e.g. `(defn ^:async fetch ...)`.
    let name_form = args
        .first()
        .ok_or_else(|| EvalError::Runtime("defn requires a symbol name".into()))?;
    let (name_metas, name_sym) = name_form.peel_meta();
    let (name, mut is_async) = match &name_sym.kind {
        FormKind::Symbol(s) => (s.clone(), name_metas.iter().any(|m| m.requests_async())),
        _ => return Err(EvalError::Runtime("defn name must be a symbol".into())),
    };
    // Optional docstring and/or metadata map after the name.
    // Valid orderings: (defn name body...), (defn name "doc" body...),
    // (defn name {:meta ...} body...), (defn name "doc" {:meta ...} body...).
    let mut rest_start = 1;
    let mut docstring: Option<String> = None;
    if rest_start < args.len()
        && let Some(s) = args[rest_start].as_string()
    {
        docstring = Some(s.to_string());
        rest_start += 1;
    }
    let mut attr_meta: Option<Value> = None;
    if rest_start < args.len() && args[rest_start].as_map().is_some() {
        // An attr-map such as `{:async true}` can also request async dispatch.
        is_async |= args[rest_start].requests_async();
        attr_meta = Some(eval(&args[rest_start], env)?);
        rest_start += 1;
    }
    // Build (fn* name ...)
    let mut fn_args = vec![Form::new(
        FormKind::Symbol(name.to_string()),
        args[0].span.clone(),
    )];
    fn_args.extend_from_slice(&args[rest_start..]);
    // Under no-gc: the Fn object must live in the StaticArena since the Var
    // intern outlives all scratch regions.
    #[cfg(feature = "no-gc")]
    let _static_ctx = cljrs_gc::alloc_ctx::StaticCtxGuard::new();
    let mut fn_val = eval_fn(&fn_args, env)?;
    if is_async && let Value::Fn(ref mut f) = fn_val {
        f.get_mut().is_async = true;
    }
    let var = env
        .globals
        .intern(&env.current_ns, Arc::from(name.as_str()), fn_val.clone());
    let mut meta = attr_meta;
    if let Some(doc) = &docstring {
        meta = merge_meta(meta, Some(doc_meta(doc)));
    }
    meta = merge_meta(meta, arglists_meta(&fn_val, 0));
    if private {
        meta = merge_meta(meta, Some(private_meta()));
    }
    if let Some(meta_val) = meta {
        var.get().set_meta(meta_val);
    }
    Ok(Value::Var(var))
}

// ── defmacro ──────────────────────────────────────────────────────────────────

/// Prepend `&form` and `&env` Form symbols to an arity form's parameter vector.
///
/// Handles:
/// - Single-arity vector `[params...]` → `[&form &env params...]`
/// - Multi-arity clause list `([params...] body...)` → `([&form &env params...] body...)`
fn prepend_macro_params(form: &Form) -> Form {
    let span = form.span.clone();
    match &form.unmeta().kind {
        FormKind::Vector(params) => {
            let mut new_params = vec![
                Form::new(FormKind::Symbol("&form".to_string()), span.clone()),
                Form::new(FormKind::Symbol("&env".to_string()), span.clone()),
            ];
            new_params.extend_from_slice(params);
            Form::new(FormKind::Vector(new_params), span)
        }
        FormKind::List(forms) => {
            // Arity clause: ([params...] body...) — prepend to first element (params vector).
            if let Some(first) = forms.first() {
                let new_params_form = prepend_macro_params(first);
                let mut new_forms = vec![new_params_form];
                new_forms.extend_from_slice(&forms[1..]);
                Form::new(FormKind::List(new_forms), span)
            } else {
                form.clone()
            }
        }
        _ => form.clone(),
    }
}

fn eval_defmacro(args: &[Form], env: &mut Env) -> EvalResult {
    // The name may carry reader metadata, e.g. `(defmacro ^:private foo ...)`,
    // possibly stacked (`^:a ^:b foo`).
    let mut current = args
        .first()
        .ok_or_else(|| EvalError::Runtime("defmacro requires a symbol at position 0".into()))?
        .clone();
    let mut name_meta: Option<Value> = None;
    while let FormKind::Meta(meta_form, inner) = current.kind {
        let meta_val = compile_meta_form(&meta_form, env)?;
        name_meta = merge_meta(name_meta, Some(meta_val));
        current = *inner;
    }
    let name = match &current.kind {
        FormKind::Symbol(s) => s.clone(),
        _ => {
            return Err(EvalError::Runtime(
                "defmacro requires a symbol at position 0".into(),
            ));
        }
    };

    let mut rest_start = 1;
    let mut docstring: Option<String> = None;
    if rest_start < args.len()
        && let FormKind::Str(s) = &args[rest_start].kind
    {
        docstring = Some(s.clone());
        rest_start += 1;
    }
    let mut attr_meta = None;
    if rest_start < args.len() && matches!(args[rest_start].kind, FormKind::Map(_)) {
        attr_meta = Some(eval(&args[rest_start], env)?);
        rest_start += 1;
    }
    // Prepend implicit &form and &env params to each arity.
    let mut fn_args = vec![Form::new(
        FormKind::Symbol(name.to_string()),
        args[0].span.clone(),
    )];
    for form in &args[rest_start..] {
        fn_args.push(prepend_macro_params(form));
    }
    // Under no-gc: the Macro object must live in the StaticArena since the Var
    // intern outlives all scratch regions.
    #[cfg(feature = "no-gc")]
    let _static_ctx = cljrs_gc::alloc_ctx::StaticCtxGuard::new();
    let fn_val = eval_fn(&fn_args, env)?;

    // Convert Fn → Macro by setting is_macro = true.
    let macro_val = match fn_val {
        Value::Fn(f) => {
            let mut mfn = f.get().clone();
            mfn.is_macro = true;
            Value::Macro(GcPtr::new(mfn))
        }
        other => other,
    };

    let var = env
        .globals
        .intern(&env.current_ns, Arc::from(name.as_str()), macro_val.clone());
    let mut meta = merge_meta(name_meta, attr_meta);
    if let Some(doc) = &docstring {
        meta = merge_meta(meta, Some(doc_meta(doc)));
    }
    // Skip the implicit &form/&env params when showing the macro's signature.
    meta = merge_meta(meta, arglists_meta(&macro_val, 2));
    if let Some(m) = meta {
        var.get().set_meta(m);
    }
    Ok(Value::Var(var))
}

// ── defonce ───────────────────────────────────────────────────────────────────

fn eval_defonce(args: &[Form], env: &mut Env) -> EvalResult {
    if args.is_empty() {
        return Err(EvalError::Runtime("defonce requires a name".into()));
    }
    // Share `def`'s name extraction so a metadata-carrying symbol such as
    // `(defonce ^:private registry (atom {}))` is accepted here too.
    let (name, _meta) = extract_def_name(&args[0], env)?;
    // If already bound, return immediately.
    if let Some(var) = defonce_existing(&name, env) {
        return Ok(var);
    }
    eval_def(args, env)
}

// ── and / or ──────────────────────────────────────────────────────────────────

fn eval_and(args: &[Form], env: &mut Env) -> EvalResult {
    let mut result = Value::Bool(true);
    for form in args {
        result = eval(form, env)?;
        if matches!(result, Value::Nil | Value::Bool(false)) {
            return Ok(result);
        }
    }
    Ok(result)
}

fn eval_or(args: &[Form], env: &mut Env) -> EvalResult {
    let mut last = Value::Nil;
    for form in args {
        last = eval(form, env)?;
        if !matches!(last, Value::Nil | Value::Bool(false)) {
            return Ok(last);
        }
    }
    Ok(last)
}

// ── require ───────────────────────────────────────────────────────────────────

fn eval_require(args: &[Form], env: &mut Env) -> EvalResult {
    for arg in args {
        let val = eval(arg, env)?;
        let spec = parse_require_spec_val(val).map_err(EvalError::Runtime)?;
        load_ns(env.globals.clone(), &spec, &env.current_ns)?;
    }
    Ok(Value::Nil)
}

/// Parse a `RequireSpec` from an already-evaluated `Value`.
/// Accepts: `'some.ns`, `['some.ns :as alias]`, `['some.ns :refer [syms]]`,
/// `['some.ns :refer :all]`, and versioned forms like `'some.ns@abc1234` or
/// `['some.ns@abc1234 :as alias]`.
fn parse_require_spec_val(val: Value) -> Result<RequireSpec, String> {
    match val {
        Value::Symbol(s) => {
            let sym = s.get();
            Ok(RequireSpec {
                ns: sym.name.clone(),
                version: sym.version.clone(),
                alias: None,
                refer: RequireRefer::None,
            })
        }
        Value::Vector(v) => {
            let items: Vec<Value> = v.get().iter().cloned().collect();
            if items.is_empty() {
                return Err("require spec vector must not be empty".into());
            }
            let (ns, version) = match &items[0] {
                Value::Symbol(s) => {
                    let sym = s.get();
                    (sym.name.clone(), sym.version.clone())
                }
                other => {
                    return Err(format!(
                        "require spec: first element must be a symbol, got {}",
                        other.type_name()
                    ));
                }
            };
            let mut alias = None;
            let mut refer = RequireRefer::None;
            let mut i = 1;
            while i < items.len() {
                match &items[i] {
                    Value::Keyword(k) if k.get().name.as_ref() == "as" => {
                        i += 1;
                        alias = Some(match items.get(i) {
                            Some(Value::Symbol(s)) => s.get().name.clone(),
                            _ => return Err("require :as expects a symbol".into()),
                        });
                    }
                    Value::Keyword(k) if k.get().name.as_ref() == "refer" => {
                        i += 1;
                        refer = match items.get(i) {
                            Some(Value::Keyword(k2)) if k2.get().name.as_ref() == "all" => {
                                RequireRefer::All
                            }
                            Some(Value::Vector(rv)) => {
                                let names: Vec<Arc<str>> = rv
                                    .get()
                                    .iter()
                                    .map(|v| match v {
                                        Value::Symbol(s) => Ok(s.get().name.clone()),
                                        other => Err(format!(
                                            "require :refer expects symbols, got {}",
                                            other.type_name()
                                        )),
                                    })
                                    .collect::<Result<_, _>>()?;
                                RequireRefer::Named(names)
                            }
                            _ => {
                                return Err(
                                    "require :refer expects :all or a vector of symbols".into()
                                );
                            }
                        };
                    }
                    other => {
                        return Err(format!(
                            "require spec: unexpected option {}",
                            other.type_name()
                        ));
                    }
                }
                i += 1;
            }
            Ok(RequireSpec {
                ns,
                version,
                alias,
                refer,
            })
        }
        other => Err(format!(
            "require expects a symbol or vector, got {}",
            other.type_name()
        )),
    }
}

/// The form a require-spec element denotes: a reader conditional resolves to
/// its selected branch, `None` when no branch matches this platform. Any other
/// form is itself.
fn spec_element(form: &Form) -> Option<&Form> {
    match &form.kind {
        FormKind::ReaderCond { clauses, .. } => select_reader_cond(clauses),
        _ => Some(form),
    }
}

/// Parse a `RequireSpec` from a raw `Form` (unevaluated, used in `ns` macro).
/// Also handles versioned namespace symbols such as `my.ns@abc1234`.
///
/// Public so the AOT compiler can establish an entry namespace from the same
/// parse `eval_ns` uses. A second implementation there would drift: it already
/// did, dropping `:refer` and `@version` from structurally emitted requires.
pub fn parse_require_spec_form(form: &Form) -> Result<RequireSpec, String> {
    match &form.kind {
        FormKind::Symbol(s) => {
            let sym = cljrs_value::Symbol::parse(s);
            Ok(RequireSpec {
                ns: sym.name.clone(),
                version: sym.version.clone(),
                alias: None,
                refer: RequireRefer::None,
            })
        }
        FormKind::Vector(items) => {
            if items.is_empty() {
                return Err("require spec vector must not be empty".into());
            }
            let head = spec_element(&items[0]).ok_or_else(|| {
                "require spec: no reader-conditional branch matched for the namespace".to_string()
            })?;
            let (ns, version) = match &head.kind {
                FormKind::Symbol(s) => {
                    let sym = cljrs_value::Symbol::parse(s);
                    (sym.name.clone(), sym.version.clone())
                }
                _ => return Err("require spec: first element must be a symbol".into()),
            };
            let mut alias = None;
            let mut refer = RequireRefer::None;
            let mut i = 1;
            while i < items.len() {
                // An option whose conditional selects nothing is dropped; the
                // namespace slot above cannot be, so it errors instead.
                let Some(item) = spec_element(&items[i]) else {
                    i += 1;
                    continue;
                };
                match &item.kind {
                    FormKind::Keyword(k) if k == "as" => {
                        i += 1;
                        alias = Some(match items.get(i).map(|f| &f.kind) {
                            Some(FormKind::Symbol(s)) => Arc::from(s.as_str()),
                            _ => return Err("require :as expects a symbol".into()),
                        });
                    }
                    FormKind::Keyword(k) if k == "refer" => {
                        i += 1;
                        refer = match items.get(i).map(|f| &f.kind) {
                            Some(FormKind::Keyword(k2)) if k2 == "all" => RequireRefer::All,
                            Some(FormKind::Vector(rv)) => {
                                let names: Vec<Arc<str>> = rv
                                    .iter()
                                    .map(|f| match &f.kind {
                                        FormKind::Symbol(s) => Ok(Arc::from(s.as_str())),
                                        _ => Err("require :refer expects symbols".to_string()),
                                    })
                                    .collect::<Result<_, _>>()?;
                                RequireRefer::Named(names)
                            }
                            _ => return Err("require :refer expects :all or a vector".into()),
                        };
                    }
                    _ => return Err(format!("require spec: unexpected form at position {i}")),
                }
                i += 1;
            }
            Ok(RequireSpec {
                ns,
                version,
                alias,
                refer,
            })
        }
        _ => Err("require spec must be a symbol or vector".into()),
    }
}

// ── ns ────────────────────────────────────────────────────────────────────────

/// Extract the ns name and optional metadata from the `ns` macro's name form.
/// Handles plain symbols and `^meta` shorthand / map forms, e.g.
/// `(ns ^{:doc "..."} my.ns ...)` or `(ns ^:no-doc my.ns ...)`.
fn extract_ns_name_form(form: Option<&Form>, env: &mut Env) -> EvalResult<(String, Option<Value>)> {
    let mut current = form
        .ok_or_else(|| EvalError::Runtime("ns requires a symbol at position 0".into()))?
        .clone();
    let mut meta_acc: Option<Value> = None;
    while let FormKind::Meta(meta_form, inner) = current.kind {
        let meta_val = compile_meta_form(&meta_form, env)?;
        meta_acc = merge_meta(meta_acc, Some(meta_val));
        current = *inner;
    }
    match &current.kind {
        FormKind::Symbol(s) => Ok((s.clone(), meta_acc)),
        _ => Err(EvalError::Runtime(
            "ns requires a symbol at position 0".into(),
        )),
    }
}

/// Merge two optional metadata maps, with `overlay` entries taking
/// precedence over `base` entries (matching Clojure's `(merge base overlay)`).
fn merge_meta(base: Option<Value>, overlay: Option<Value>) -> Option<Value> {
    match (base, overlay) {
        (None, None) => None,
        (Some(b), None) => Some(b),
        (None, Some(o)) => Some(o),
        (Some(Value::Map(b)), Some(Value::Map(o))) => {
            let mut merged = b;
            for (k, v) in o.iter() {
                merged = merged.assoc(k.clone(), v.clone());
            }
            Some(Value::Map(merged))
        }
        (_, Some(o)) => Some(o),
    }
}

/// Parse the body of a `(:refer-clojure ...)` clause into the filter applied
/// to the automatic `clojure.core` refer.  Accepts `:exclude`, `:only` and
/// `:rename`, each once, in any order.
fn parse_refer_clojure_clause(items: &[Form]) -> Result<ReferClojureFilter, String> {
    let mut filter = ReferClojureFilter::default();
    let items = expand_reader_conds(items);
    let mut i = 0;
    while i < items.len() {
        let FormKind::Keyword(k) = &items[i].kind else {
            return Err(":refer-clojure expects keyword options (:exclude, :only, :rename)".into());
        };
        let arg = items
            .get(i + 1)
            .ok_or_else(|| format!(":refer-clojure :{k} expects a value"))?;
        match k.as_str() {
            "exclude" => filter.exclude = symbol_name_set(arg, "exclude")?,
            "only" => filter.only = Some(symbol_name_set(arg, "only")?),
            "rename" => {
                let FormKind::Map(entries) = &arg.kind else {
                    return Err(":refer-clojure :rename expects a map".into());
                };
                if entries.len() % 2 != 0 {
                    return Err(":refer-clojure :rename expects an even-sized map".into());
                }
                for pair in entries.chunks(2) {
                    match (&pair[0].kind, &pair[1].kind) {
                        (FormKind::Symbol(from), FormKind::Symbol(to)) => {
                            filter
                                .rename
                                .insert(Arc::from(from.as_str()), Arc::from(to.as_str()));
                        }
                        _ => {
                            return Err(
                                ":refer-clojure :rename expects symbol keys and values".into()
                            );
                        }
                    }
                }
            }
            other => return Err(format!(":refer-clojure does not support :{other}")),
        }
        i += 2;
    }
    Ok(filter)
}

/// Read a vector of symbols (an `:exclude`/`:only` list) as a set of names.
fn symbol_name_set(form: &Form, opt: &str) -> Result<HashSet<Arc<str>>, String> {
    let FormKind::Vector(items) = &form.kind else {
        return Err(format!(":refer-clojure :{opt} expects a vector of symbols"));
    };
    expand_reader_conds(items)
        .iter()
        .map(|f| match &f.kind {
            FormKind::Symbol(sym) => Ok(Arc::from(sym.as_str())),
            _ => Err(format!(":refer-clojure :{opt} expects symbols")),
        })
        .collect()
}

fn eval_ns(args: &[Form], env: &mut Env) -> EvalResult {
    let (name, name_meta) = extract_ns_name_form(args.first(), env)?;
    env.globals.get_or_create_ns(&name);
    env.current_ns = Arc::from(name.as_str());
    // Auto-refer clojure.core (Clojure default behaviour).
    if name != "clojure.core" {
        env.globals.refer_core(&name);
    }
    sync_star_ns(env);

    // Optional docstring, then optional attr-map, before reference clauses.
    let mut rest = &args[1..];
    if matches!(rest.first().map(|f| &f.kind), Some(FormKind::Str(_))) {
        rest = &rest[1..];
    }
    let mut attr_meta = None;
    if matches!(rest.first().map(|f| &f.kind), Some(FormKind::Map(_))) {
        attr_meta = Some(eval(&rest[0], env)?);
        rest = &rest[1..];
    }

    if let Some(m) = merge_meta(name_meta, attr_meta) {
        let ns_ptr = env.globals.get_or_create_ns(&env.current_ns);
        ns_ptr.get().set_meta(m);
    }

    // `:refer-clojure` first: it narrows the automatic core refer done above,
    // and an explicit `:require ... :refer` below must be able to override it.
    // Re-evaluating an `ns` form without the clause clears a filter left by an
    // earlier evaluation, restoring the full core refer.
    //
    // More than one `:refer-clojure` clause is not meaningful, so the last one
    // wins rather than accumulating.  (Clojure runs each clause as a separate
    // `refer` call, where a second clause silently *re-adds* what the first
    // excluded; there is no reading of that under which both clauses do what
    // they say.)
    let mut refer_clojure = None;
    for clause in rest {
        if let FormKind::List(items) = &clause.kind
            && matches!(items.first().map(|f| &f.kind), Some(FormKind::Keyword(k)) if k == "refer-clojure")
        {
            refer_clojure =
                Some(parse_refer_clojure_clause(&items[1..]).map_err(EvalError::Runtime)?);
        }
    }
    if name != "clojure.core" {
        env.globals
            .set_refer_clojure_filter(&name, refer_clojure)
            .map_err(EvalError::Runtime)?;
    }

    for clause in rest {
        if let FormKind::List(items) = &clause.kind {
            match items.first().map(|f| &f.kind) {
                Some(FormKind::Keyword(k)) if k == "require" => {
                    // Expand reader conditionals among require specs
                    let expanded = expand_reader_conds(&items[1..]);
                    for spec_form in &expanded {
                        let spec =
                            parse_require_spec_form(spec_form).map_err(EvalError::Runtime)?;
                        load_ns(env.globals.clone(), &spec, &name)?;
                    }
                }
                // `:refer-clojure` was handled in the pass above; other clauses
                // (`:use`, `:import`) — skip for now.
                _ => {}
            }
        }
    }

    let ns_ptr = env.globals.get_or_create_ns(&env.current_ns);
    Ok(Value::Namespace(ns_ptr))
}

// ── load-file ─────────────────────────────────────────────────────────────────

fn eval_load_file(args: &[Form], env: &mut Env) -> EvalResult {
    if args.is_empty() {
        return Err(EvalError::Runtime(
            "load-file requires a path argument".into(),
        ));
    }
    let path_val = eval(&args[0], env)?;
    let path = match &path_val {
        Value::Str(s) => s.get().clone(),
        v => {
            return Err(EvalError::Runtime(format!(
                "load-file: expected string, got {}",
                v.type_name()
            )));
        }
    };
    let src = std::fs::read_to_string(&path)
        .map_err(|e| EvalError::Runtime(format!("load-file: {e}")))?;
    let mut parser = cljrs_reader::Parser::new(src, path.clone());
    let forms = parser
        .parse_all()
        .map_err(|e| EvalError::Runtime(format!("load-file parse error: {e}")))?;
    let mut result = Value::Nil;
    for form in forms {
        let _alloc_frame = cljrs_gc::push_alloc_frame();
        result = eval(&form, env)?;
    }
    Ok(result)
}

// ── letfn ─────────────────────────────────────────────────────────────────────

fn eval_letfn(args: &[Form], env: &mut Env) -> EvalResult {
    push_letfn_frame(args, env)?;
    let result = eval_body(&args[1..], env);
    env.pop_frame();
    result
}

/// Push a local frame binding every fn of `(letfn [fns…] body…)`, mutually
/// visible. On success the caller evaluates the body and pops the frame; on
/// error the frame has already been popped.
///
/// Public so the async evaluator can run the body with a yielding evaluator.
pub fn push_letfn_frame(args: &[Form], env: &mut Env) -> EvalResult<()> {
    // (letfn [(f [params] body...) ...] body...)
    //
    // Three passes, because a closure here captures VALUES, not cells:
    // `eval_fn` snapshots `env.all_local_bindings()`, so a name bound after the
    // closure was built is invisible to it forever. Binding each fn as it was
    // built therefore gave letfn `let`-like sequential scope — a backward
    // reference resolved, a forward one or a mutual pair raised "unbound
    // symbol", which defeats the only reason letfn exists.
    let bindings = match args.first().and_then(|f| f.as_vector()) {
        Some(v) => expand_reader_conds_cow(v).into_owned(),
        None => return Err(EvalError::Runtime("letfn requires a binding vector".into())),
    };

    env.push_frame();

    // Pass 1: bind every name to nil, so the pass-2 snapshot CONTAINS all of
    // them. A capture list cannot grow after the fact; it can only be corrected.
    for binding in &bindings {
        if let Some(parts) = binding.as_list() {
            if parts.is_empty() {
                continue;
            }
            let Some(name) = parts[0].as_symbol() else {
                env.pop_frame();
                return Err(EvalError::Runtime(
                    "letfn binding name must be a symbol".into(),
                ));
            };
            env.bind(Arc::from(name), Value::Nil);
        }
    }

    // Pass 2: build the closures. Each captures the real value of any sibling
    // already built and nil for the rest.
    let mut built: Vec<(Arc<str>, Value)> = Vec::new();
    for binding in &bindings {
        if let Some(parts) = binding.as_list() {
            if parts.is_empty() {
                continue;
            }
            // parts[0] is the name, so eval_fn sees this as a NAMED fn and wires
            // up its self-reference; pass 3 handles every other direction.
            let fn_val = match eval_fn(parts, env) {
                Ok(v) => v,
                Err(e) => {
                    env.pop_frame();
                    return Err(e);
                }
            };
            let name: Arc<str> = match parts[0].as_symbol() {
                Some(s) => Arc::from(s),
                None => unreachable!("pass 1 rejected every non-symbol name"),
            };
            env.bind(Arc::clone(&name), fn_val.clone());
            built.push((name, fn_val));
        }
    }

    // Pass 3: replace the nil placeholders each closure captured with the
    // sibling it actually names. This is what makes the scope MUTUAL rather
    // than sequential, and it necessarily builds a reference cycle between
    // co-recursive fns — which is inherent to letfn, not an artifact here.
    for (_, fn_val) in &built {
        if let Value::Fn(ptr) = fn_val {
            let mut ptr = ptr.clone();
            let f = ptr.get_mut();
            for i in 0..f.closed_over_names.len() {
                let captured = f.closed_over_names[i].clone();
                if let Some((_, real)) = built.iter().find(|(n, _)| *n == captured) {
                    f.closed_over_vals[i] = real.clone();
                }
            }
        }
    }

    Ok(())
}

// ── in-ns ─────────────────────────────────────────────────────────────────────

fn eval_in_ns(args: &[Form], env: &mut Env) -> EvalResult {
    // (in-ns 'foo.bar)
    if args.is_empty() {
        return Err(EvalError::Runtime("in-ns requires a namespace name".into()));
    }
    let ns_val = eval(&args[0], env)?;
    let ns_name = extract_ns_name(&ns_val)?;
    env.globals.get_or_create_ns(&ns_name);
    env.globals.refer_core(&ns_name);
    env.current_ns = Arc::from(ns_name.as_str());
    sync_star_ns(env);
    let ns_ptr = env.globals.get_or_create_ns(&env.current_ns);
    Ok(Value::Namespace(ns_ptr))
}

// ── alias ─────────────────────────────────────────────────────────────────────

fn eval_alias(args: &[Form], env: &mut Env) -> EvalResult {
    // (alias 'short 'some.long.ns)
    if args.len() < 2 {
        return Err(EvalError::Runtime(
            "alias requires alias-sym and namespace-sym".into(),
        ));
    }
    let alias_val = eval(&args[0], env)?;
    let ns_val = eval(&args[1], env)?;

    let alias_name = extract_ns_name(&alias_val)?;
    let full_ns = extract_ns_name(&ns_val)?;

    let ns_ptr = env.globals.get_or_create_ns(&env.current_ns);
    let mut aliases = ns_ptr.get().aliases.lock().unwrap();
    aliases.insert(Arc::from(alias_name.as_str()), Arc::from(full_ns.as_str()));
    Ok(Value::Nil)
}

/// Extract a namespace-name string from a Value::Symbol, Value::Str, or Value::Keyword.
fn extract_ns_name(v: &Value) -> EvalResult<String> {
    match v {
        Value::Symbol(s) => {
            // Use the full name (e.g. "clojure.core").
            Ok(s.get().name.as_ref().to_string())
        }
        Value::Str(s) => Ok(s.get().clone()),
        Value::Keyword(k) => Ok(k.get().name.as_ref().to_string()),
        other => Err(EvalError::Runtime(format!(
            "expected a symbol or string for namespace name, got {}",
            other.type_name()
        ))),
    }
}

// ── protocol* ─────────────────────────────────────────────────────────────────

/// Read a `{:name "m" :min-arity n :variadic b}` map into a `ProtocolMethod`.
fn protocol_method_of(spec: &Value) -> EvalResult<ProtocolMethod> {
    let Value::Map(m) = spec.unwrap_meta() else {
        return Err(EvalError::Runtime(format!(
            "protocol* method spec must be a map, got {}",
            spec.type_name()
        )));
    };
    let field = |k: &str| m.get(&Value::keyword(Keyword::simple(k)));
    let name: Arc<str> = match field("name") {
        Some(Value::Str(s)) => Arc::from(s.get().as_str()),
        Some(Value::Symbol(s)) => Arc::from(s.get().name.as_ref()),
        Some(Value::Keyword(k)) => Arc::from(k.get().name.as_ref()),
        _ => {
            return Err(EvalError::Runtime(
                "protocol* method spec needs a :name".into(),
            ));
        }
    };
    let min_arity = match field("min-arity") {
        Some(Value::Long(n)) if n >= 0 => n as usize,
        _ => 1,
    };
    let variadic = !matches!(
        field("variadic"),
        None | Some(Value::Nil) | Some(Value::Bool(false))
    );
    Ok(ProtocolMethod {
        name,
        min_arity,
        variadic,
    })
}

/// `(protocol* Name method-specs extend-via-metadata?)` — mint a protocol.
///
/// `method-specs` evaluates to a sequence of `{:name :min-arity :variadic}`
/// maps. The protocol is created in the CURRENT namespace, which is the whole
/// reason this stays a special form: `Protocol.ns` is what qualifies a method
/// name for extend-via-metadata dispatch, and a builtin fn cannot see the
/// environment. The protocol is returned, not interned — `defprotocol` is the
/// Clojure macro that `def`s it along with a dispatch fn per method.
fn eval_protocol_star(args: &[Form], env: &mut Env) -> EvalResult {
    if args.len() < 2 {
        return Err(EvalError::Runtime(
            "protocol* requires a name and method specs".into(),
        ));
    }
    // Name metadata belongs on the var `defprotocol` binds, not here.
    let (name, _) = require_sym_meta(args, 0, "protocol*", env)?;
    let specs = crate::interp::eval::eval(&args[1], env)?;
    let specs: Vec<Value> = match specs.unwrap_meta() {
        Value::Vector(v) => v.get().iter().cloned().collect(),
        Value::Nil => Vec::new(),
        v => {
            return Err(EvalError::Runtime(format!(
                "protocol* method specs must be a vector, got {}",
                v.type_name()
            )));
        }
    };
    let methods = specs
        .iter()
        .map(protocol_method_of)
        .collect::<EvalResult<Vec<_>>>()?;
    let extend_via_metadata = match args.get(2) {
        Some(f) => !matches!(
            crate::interp::eval::eval(f, env)?,
            Value::Nil | Value::Bool(false)
        ),
        None => false,
    };
    let proto = Protocol::new(
        Arc::from(name.as_str()),
        env.current_ns.clone(),
        methods,
        extend_via_metadata,
    );
    Ok(Value::Protocol(GcPtr::new(proto)))
}

/// Build a `CljxFn` from the tail of a method-impl list: `(name [params] body...)`.
/// `parts[0]` is the method name symbol (ignored here — caller handles it).
/// `parts[1]` is the params vector.
/// `parts[2..]` is the body.
/// Bring a defrecord's FIELDS into scope in a method body, as
/// `(let* [f (:f this) ...] body...)`.
///
/// The bare field symbol is the idiomatic form — `(mutable? [_] (valid-sha? sha))`
/// — and it read as an unbound symbol, because a method impl is built as an
/// ordinary fn whose only bindings are its own params. Clojure compiles the
/// fields as instance fields of the generated class, so they are simply in
/// scope.
///
/// A field whose name a PARAM already takes is skipped: the param shadows the
/// field in Clojure, and binding it here would shadow the param instead.
/// Returns None when there is nothing to bind, or when the first param is not
/// a plain symbol (a destructured `this` has no name to read the fields from).
fn synth_field_scope(
    params_form: &Form,
    fields: &[Arc<str>],
    mutable_fields: &[Arc<str>],
    body: &[Form],
) -> Option<Vec<Form>> {
    let param_forms = match &params_form.kind {
        FormKind::Vector(v) => v,
        _ => return None,
    };
    let this_name = match param_forms.first().map(|f| &f.kind) {
        Some(FormKind::Symbol(s)) => s.clone(),
        _ => return None,
    };
    let param_names: Vec<&str> = param_forms
        .iter()
        .filter_map(|f| match &f.kind {
            FormKind::Symbol(s) => Some(s.as_str()),
            _ => None,
        })
        .collect();

    let span = params_form.span.clone();
    let is_mut = |name: &str| mutable_fields.iter().any(|m| m.as_ref() == name);
    let mut bindings: Vec<Form> = Vec::new();
    for field in fields {
        if param_names.contains(&field.as_ref()) {
            continue;
        }
        bindings.push(Form::new(FormKind::Symbol(field.to_string()), span.clone()));
        // A mutable field reads through `(.-field this)` — the live cell; an
        // immutable one through `(:field this)` — the field map. Both snapshot
        // at method entry; `set!` refreshes the local for later reads.
        let accessor = if is_mut(field) {
            FormKind::List(vec![
                Form::new(FormKind::Symbol(format!(".-{field}")), span.clone()),
                Form::new(FormKind::Symbol(this_name.clone()), span.clone()),
            ])
        } else {
            FormKind::List(vec![
                Form::new(FormKind::Keyword(field.to_string()), span.clone()),
                Form::new(FormKind::Symbol(this_name.clone()), span.clone()),
            ])
        };
        bindings.push(Form::new(accessor, span.clone()));
    }
    // With mutable fields present, bind a hidden handle to `this` so `set!` can
    // find the instance whose cell to update.
    if !mutable_fields.is_empty() {
        bindings.push(Form::new(
            FormKind::Symbol(DEFTYPE_SELF.to_string()),
            span.clone(),
        ));
        bindings.push(Form::new(FormKind::Symbol(this_name.clone()), span.clone()));
    }
    if bindings.is_empty() {
        return None;
    }

    let mut let_forms = vec![
        Form::new(FormKind::Symbol("let*".to_string()), span.clone()),
        Form::new(FormKind::Vector(bindings), span.clone()),
    ];
    let_forms.extend_from_slice(body);
    Some(vec![Form::new(FormKind::List(let_forms), span)])
}

fn build_impl_fn(
    parts: &[Form],
    fields: &[Arc<str>],
    mutable_fields: &[Arc<str>],
    env: &mut Env,
) -> EvalResult<Value> {
    if parts.len() < 2 {
        return Err(EvalError::Runtime(
            "protocol method impl requires params and body".into(),
        ));
    }
    // parts[1] should be the params vector.
    let params_form = &parts[1];
    let body = &parts[2..];
    let scoped;
    let body: &[Form] = if fields.is_empty() {
        body
    } else {
        match synth_field_scope(params_form, fields, mutable_fields, body) {
            Some(v) => {
                scoped = v;
                &scoped
            }
            None => body,
        }
    };
    let arity = parse_arity(params_form, body)?;
    let (closed_over_names, closed_over_vals) = env.all_local_bindings();
    let fn_name: Option<Arc<str>> = parts[0].as_symbol().map(Arc::from);
    let cljrs_fn = CljxFn::new(
        fn_name,
        vec![arity],
        closed_over_names,
        closed_over_vals,
        false,
        Arc::clone(&env.current_ns),
    );
    Ok(Value::Fn(GcPtr::new(cljrs_fn)))
}

// ── binding ───────────────────────────────────────────────────────────────────

fn eval_binding(args: &[Form], env: &mut Env) -> EvalResult {
    let pairs = match args.first().and_then(|f| f.as_vector()) {
        Some(v) => expand_pairs(v)
            .map_err(|_| EvalError::Runtime("binding vector must have even count".into()))?
            .into_owned(),
        None => return Err(EvalError::Runtime("binding requires a vector".into())),
    };

    let mut frame: HashMap<usize, Value> = HashMap::new();
    for pair in pairs.chunks(2) {
        let Some(sym_str) = pair[0].as_symbol() else {
            return Err(EvalError::Runtime("binding targets must be symbols".into()));
        };
        let parsed = cljrs_value::Symbol::parse(sym_str);
        let ns_part: Arc<str> = env.resolve_ns_or_current(parsed.namespace.as_deref());
        let var_ptr = env
            .globals
            .lookup_var_in_ns(&ns_part, &parsed.name)
            .ok_or_else(|| EvalError::UnboundSymbol(sym_str.to_string()))?;
        let val = eval(&pair[1], env)?;
        frame.insert(crate::env::dynamics::var_key_of(&var_ptr), val);
    }

    let _guard = crate::env::dynamics::push_frame(frame);
    eval_body(&args[1..], env)
    // _guard drops here → pop_frame()
}

// ── deftype / defrecord shared construction ─────────────────────────────────────

/// Hidden `let*` binding a `deftype` method body carries when the type has
/// mutable fields: a handle to `this`, so `set!` can locate the instance whose
/// interior-mutable cell to update.
const DEFTYPE_SELF: &str = "__deftype_self__";

/// Does a field's `^meta` mark it `^:unsynchronized-mutable` or
/// `^:volatile-mutable`? Instances are single-threaded here, so the two are
/// treated identically — only whether the field is mutable at all matters.
fn meta_form_is_mutable(meta: &Form) -> bool {
    let is_mut_kw = |k: &str| k == "unsynchronized-mutable" || k == "volatile-mutable";
    match &meta.kind {
        FormKind::Keyword(k) => is_mut_kw(k),
        FormKind::Map(entries) => entries.chunks(2).any(|kv| {
            matches!(&kv[0].kind, FormKind::Keyword(k) if is_mut_kw(k))
                && !matches!(
                    kv.get(1).map(|f| &f.kind),
                    None | Some(FormKind::Bool(false)) | Some(FormKind::Nil)
                )
        }),
        // Metadata that reached this form through a macro is QUOTED: it is
        // already a value, and re-analysing it would resolve its contents as
        // code (see `value_to_form`). A field vector written in source arrives
        // unquoted; one a macro emitted arrives quoted. Both describe the same
        // field, so both have to be read.
        FormKind::Quote(inner) => meta_form_is_mutable(inner),
        _ => false,
    }
}

/// A single field spec: its name and whether it is mutable.
fn field_spec_of(form: &Form) -> Option<(Arc<str>, bool)> {
    match &form.kind {
        FormKind::Symbol(s) => Some((Arc::from(s.as_str()), false)),
        FormKind::Meta(meta, inner) => {
            let here = meta_form_is_mutable(meta);
            field_spec_of(inner).map(|(name, inner_mut)| (name, inner_mut || here))
        }
        _ => None,
    }
}

/// Parse a `deftype` `[field ...]` vector into `(name, mutable?)` specs.
fn parse_field_specs(form: &Form, ctx: &str) -> EvalResult<Vec<(Arc<str>, bool)>> {
    // `as_vector` reports the shape under any `^meta`, so a marker on the
    // vector itself — `(defrecord R ^:marker [x])` — stays transparent.
    let Some(fields) = form.as_vector() else {
        return Err(EvalError::Runtime(format!(
            "{ctx} requires a field vector as second arg"
        )));
    };
    fields
        .iter()
        .map(|f| {
            field_spec_of(f)
                .ok_or_else(|| EvalError::Runtime(format!("{ctx} field names must be symbols")))
        })
        .collect()
}

// ── deftype* (defrecord / deftype are bootstrap macros over it) ─────────────────

/// The irreducible datatype primitive: mint a type tag and register method impls
/// against it, with the fields in scope in each body and mutable fields backed by
/// live cells. It does NOT synthesise constructors or intern the type symbol —
/// that sugar lives in the `deftype` bootstrap macro (`->T`, `(def T 'T)`), which
/// is what makes deftype a particular case of a Clojure macro over this form.
fn eval_deftype_star(args: &[Form], env: &mut Env) -> EvalResult {
    // (deftype* TypeName [field ...] Proto (method [this] body) ...)
    if args.len() < 2 {
        return Err(EvalError::Runtime(
            "deftype* requires a name and field vector".into(),
        ));
    }
    // Type metadata (e.g. ^:private) has no var to hold it; unwrapped so the
    // name reads, and deliberately not applied anywhere it would not belong.
    let (type_name, _) = require_sym_meta(args, 0, "deftype*", env)?;
    let type_tag: Arc<str> = Arc::from(type_name.as_str());

    let specs = parse_field_specs(&args[1], "deftype*")?;
    let field_names: Vec<Arc<str>> = specs.iter().map(|(n, _)| n.clone()).collect();
    let mutable_names: Vec<Arc<str>> = specs
        .iter()
        .filter(|(_, m)| *m)
        .map(|(n, _)| n.clone())
        .collect();

    // Register protocol/interface method impls, with the fields in scope in
    // each body — same machinery as defrecord/reify. Mutable fields read
    // through the live cell and are writable with `set!`.
    register_impls_for_tag(&type_tag, &args[2..], &field_names, &mutable_names, env)?;
    // Return the minted tag so a caller (e.g. the `reify` macro) can feed it
    // straight to `make-type-instance` — a single dataflow source for the tag,
    // rather than a second textual reference that a gensym could desync.
    Ok(Value::string(type_name))
}

// ── register_impls_for_tag ────────────────────────────────────────────────────

/// Resolve a protocol NAME symbol in an impl position (extend-type, extend-protocol,
/// reify/defrecord), honouring the current namespace's `:require :as` aliases and
/// fully-qualified names — not just an unqualified lookup in the current ns.
///
/// `(defrecord R [] mp/IThing (-do [_] ...))` failed with "mp/IThing is not a
/// protocol" even though the protocol was loaded and (resolve 'mini.proto/IThing)
/// was truthy: the old code looked up the whole string "mp/IThing" as an intern of
/// the CURRENT ns, where it is neither interned nor referred. A qualified protocol
/// symbol must resolve through its own namespace, exactly as `eval` resolves any
/// other qualified symbol.
fn resolve_protocol_sym(env: &Env, s: &str) -> Option<GcPtr<Protocol>> {
    let parsed = cljrs_value::Symbol::parse(s);
    let val = match parsed.namespace.as_deref() {
        Some(ns_part) => {
            let ns = env.resolve_ns_part(ns_part);
            env.globals.lookup_in_ns(&ns, &parsed.name)
        }
        None => env.globals.lookup_in_ns(&env.current_ns, s),
    };
    match val {
        Some(Value::Protocol(p)) => Some(p),
        _ => None,
    }
}

/// Parse `Proto (method [params] body) ...` segments and register them under `type_tag`.
/// Shared by `defrecord` and `reify`.
fn register_impls_for_tag(
    type_tag: &Arc<str>,
    forms: &[Form],
    fields: &[Arc<str>],
    mutable_fields: &[Arc<str>],
    env: &mut Env,
) -> EvalResult<()> {
    let mut current_proto: Option<GcPtr<cljrs_value::Protocol>> = None;

    for form in forms {
        match &form.unmeta().kind {
            FormKind::Symbol(s) => match resolve_protocol_sym(env, s) {
                Some(p) => current_proto = Some(p),
                None => {
                    return Err(EvalError::Runtime(format!(
                        "reify/defrecord: {} is not a protocol",
                        s
                    )));
                }
            },
            FormKind::List(parts) => {
                let proto = current_proto.as_ref().ok_or_else(|| {
                    EvalError::Runtime("reify/defrecord: method impl before protocol name".into())
                })?;
                if parts.is_empty() {
                    continue;
                }
                let method_name: Arc<str> = match parts[0].as_symbol() {
                    Some(s) => Arc::from(s),
                    None => continue,
                };
                let fn_val = build_impl_fn(parts, fields, mutable_fields, env)?;
                let mut impls = proto.get().impls.lock().unwrap();
                impls
                    .entry(type_tag.clone())
                    .or_default()
                    .insert(method_name, fn_val);
                drop(impls);
                cljrs_value::bump_protocol_generation();
            }
            _ => {}
        }
    }
    Ok(())
}

// ── helpers ───────────────────────────────────────────────────────────────────

/// Update the root binding of `*ns*` in `clojure.core` to the current namespace.
/// Called whenever `env.current_ns` changes (ns, in-ns, standard_env setup).
pub fn sync_star_ns(env: &mut Env) {
    if let Some(star_ns_var) = env.globals.lookup_var("clojure.core", "*ns*") {
        let ns_ptr = env.globals.get_or_create_ns(&env.current_ns);
        star_ns_var.get().bind(Value::Namespace(ns_ptr));
    }
}

/// The symbol at `idx`, unwrapping any `^meta` wrapper, together with the
/// metadata it carried.
///
/// `(defprotocol ^:private Driver ...)` reads as `Meta(:private, Symbol("Driver"))`,
/// so matching `FormKind::Symbol` alone rejects a form Clojure accepts. malli's
/// `malli.impl.regex` opens with five such protocols, which made all of malli
/// unloadable.
///
/// The metadata is RETURNED rather than discarded: dropping it would trade a
/// loud error for a silent loss of `^:private`, and callers that intern a var
/// attach it there.
fn require_sym_meta(
    args: &[Form],
    idx: usize,
    form_name: &str,
    env: &mut Env,
) -> EvalResult<(String, Option<Value>)> {
    fn peel(form: &Form, env: &mut Env) -> EvalResult<Option<(String, Option<Value>)>> {
        match &form.kind {
            FormKind::Symbol(s) => Ok(Some((s.clone(), None))),
            // `^:a ^:b x` nests Meta forms; unwrap all, outer mark winning.
            FormKind::Meta(meta_form, inner) => {
                let meta_val = compile_meta_form(meta_form, env)?;
                match peel(inner, env)? {
                    Some((name, inner_meta)) => {
                        Ok(Some((name, merge_meta(inner_meta, Some(meta_val)))))
                    }
                    None => Ok(None),
                }
            }
            _ => Ok(None),
        }
    }
    let err = || EvalError::Runtime(format!("{form_name} requires a symbol at position {idx}"));
    match args.get(idx) {
        Some(form) => peel(form, env)?.ok_or_else(err),
        None => Err(err()),
    }
}

// ── with-out-str ──────────────────────────────────────────────────────────────

fn eval_with_out_str(body: &[Form], env: &mut Env) -> EvalResult {
    crate::builtins::builtins::push_output_capture();
    let result = eval_body(body, env);
    let captured = crate::builtins::builtins::pop_output_capture().unwrap_or_default();
    // Propagate errors but still pop the capture buffer
    result?;
    Ok(Value::string(captured))
}

// ── await ─────────────────────────────────────────────────────────────────────

/// Blocking deref in sync context; yielding deref in async context.
///
/// When `cljrs-async` is loaded, `eval_async` intercepts `await` forms before
/// the sync evaluator reaches this handler, so this path is only taken in
/// non-async (sync) code. It blocks the OS thread until the future/promise
/// resolves — equivalent to `(deref val)`.
fn eval_await(args: &[Form], env: &mut Env) -> EvalResult {
    if args.is_empty() {
        return Err(EvalError::Runtime("await requires one argument".into()));
    }
    let val = eval(&args[0], env)?;
    match val {
        Value::Future(f) => {
            let mut guard = f.get().state.lock().unwrap();
            loop {
                match &*guard {
                    FutureState::Done(v) => {
                        f.get().mark_observed();
                        return Ok(v.clone());
                    }
                    FutureState::Failed(v) => {
                        f.get().mark_observed();
                        return Err(EvalError::Thrown(v.clone()));
                    }
                    FutureState::GasExhausted => {
                        f.get().mark_observed();
                        return Err(EvalError::GasExhausted);
                    }
                    FutureState::Cancelled => {
                        return Err(EvalError::Thrown(CljxFuture::cancelled_error()));
                    }
                    FutureState::Running => {
                        guard = f.get().cond.wait(guard).unwrap();
                    }
                }
            }
        }
        Value::Promise(p) => Ok(p.get().deref_blocking()),
        other => Ok(other),
    }
}