blue_lang_runtime/

pipeline.rs

//! The blue pipeline: **parse → check → erase → run**, in that order, once.
//!
//! The order is the whole reason this module exists. Each stage is available
//! separately for tools that want one, but the *default* path is a single
//! function, because two of the four orderings are silently wrong:
//!
//! - **Erase before check** discards every annotation, so a program with type
//!   errors passes. The checker sees `(define …)` and has nothing to check.
//! - **Run before check** reports a type error after the side effects.
//!
//! Neither fails loudly. Both produce a green run on a program that should
//! have been rejected. Leaving the order to each caller means every caller
//! is one reordering away from turning the type checker off — so the order
//! lives here, and callers ask for a *result*, not a sequence of steps.

use tatara_lisp::Sexp;
use tatara_lisp_eval::Value;

use blue_lang_check::{NameTable, Namespace};

use crate::erase::erase_types;
use crate::inputs::Inputs;
use crate::uses::Entry;

/// Why a run stopped short.
#[derive(Debug, thiserror::Error)]
pub enum RunError {
    #[error("parse error: {0}")]
    Parse(String),
    /// The check stage rejected the program — a type error, an unbound name,
    /// or any other error-severity rule in `blue_lang_check::RULES`. Carries
    /// every error, not just the first: a caller fixing one wants to see the
    /// rest. (The variant keeps its first name because it is public API on a
    /// released crate.)
    ///
    /// Each one is already rendered `file:line:col: message` against the file
    /// the offending form came from — which, in a program with imports, is
    /// frequently not the file the user named. The rendering happens here
    /// rather than at the consumer because here is where the file table exists;
    /// see `uses::ResolvedProgram::locate`.
    #[error("{} error(s) in the check stage:\n{}", .0.len(), .0.join("\n"))]
    Types(Vec<String>),
    /// **No longer reachable, and that is the point.** This reported "blue
    /// emitted a tree the reader could not read back" — a failure only a
    /// print-then-reparse hop could have. [`crate::lower_to_spanned`] deleted
    /// the hop, so there is nothing left to fail: the tree the evaluator gets
    /// IS the tree erasure produced, not a re-reading of its text.
    ///
    /// Kept rather than removed because it is public API on a released crate
    /// and a consumer may still match on it, per ★★ MODULARIZE, DON'T DELETE.
    /// It is retired, not orphaned — if a future stage ever serialises again
    /// it has a typed home. **Nothing constructs it today**; do not read its
    /// presence as evidence the pipeline can still fail this way.
    #[error("the emitted tatara-lisp could not be read back: {0}")]
    Lower(String),
    /// The program ran and raised.
    ///
    /// Rendered `file:line:col: message`, then the blue call stack the error
    /// unwound through, innermost first (`crate::observe::Fault`). The
    /// position is resolved against the file of the innermost frame's
    /// definition, so a raise inside a callee from another file names the
    /// callee's file and line; before the stack existed that case could only
    /// name the caller's file, with no position.
    #[error("runtime error: {0}")]
    Eval(Box<crate::observe::Fault>),
    /// A `use("name")` could not be resolved.
    ///
    /// Its own variant rather than folded into `Parse`, because the reader's
    /// next action is different: a parse error is in the source in front of
    /// them, an import error is in their packaging — a missing bidama, a
    /// BLUE_PATH that does not contain it, or no loader at all.
    #[error("import error: {0}")]
    Import(String),
}

impl RunError {
    /// The exit status a program that stopped here returns:
    /// [`crate::BREACH_EXIT`] for a capability breach, 1 for anything else.
    #[must_use]
    pub fn exit_status(&self) -> u8 {
        match self {
            RunError::Eval(fault) if fault.breach => crate::BREACH_EXIT,
            _ => 1,
        }
    }
}

/// What a run produced, plus what the checker did on the way.
#[derive(Debug)]
pub struct Run {
    pub value: Value,
    /// Nodes the type walk visited. Zero for a fully untyped program — this
    /// is what makes "no annotations, no analysis" a *measurement* rather
    /// than a claim.
    pub visited: usize,
    /// Declarations that carried an annotation.
    pub typed_decls: usize,
    /// Boundaries where typed code meets untyped code.
    pub seams: usize,
}

/// Parse blue source to tatara-lisp forms.
pub fn parse(src: &str) -> Result<Vec<Sexp>, RunError> {
    parse_with_depth(src, blue_lang_syntax::MAX_EXPR_DEPTH)
}

/// [`parse`] with the parser's nesting bound supplied by the caller.
///
/// The bound exists so a stack overflow — which `catch_unwind` cannot catch —
/// arrives as a typed `Err` instead. It is a *limit*, not a dialect: raising
/// it changes no program's meaning, which is exactly why it is safe to expose
/// as configuration (`blue-lang-cli`'s `config` module holds the rule).
pub fn parse_with_depth(src: &str, max_depth: usize) -> Result<Vec<Sexp>, RunError> {
    blue_lang_syntax::parse_program_with_depth(src, max_depth)
        .map_err(|e| RunError::Parse(e.to_string()))
}

/// [`parse_with_depth`] keeping **every node's** source span.
///
/// The door for anything that will report a position to a human. It exists here,
/// beside the spanless one, so a caller that wants spans still parses under the
/// CONFIGURED nesting bound — a separate `blue_lang_syntax` call would be the
/// second door `parse_with_depth`'s own docs exist to prevent, with
/// `max_expr_depth` true of some subcommands and not others.
pub fn parse_tree_with_depth(
    src: &str,
    max_depth: usize,
) -> Result<Vec<blue_lang_syntax::Spanned>, RunError> {
    blue_lang_syntax::parse_program_tree_with_depth(src, max_depth)
        .map_err(|e| RunError::Parse(e.to_string()))
}

/// [`parse`] keeping **every node's** source span.
///
/// The spanned twin of [`parse`], at the same default bound — the door for
/// anything downstream of a parse that will report a position, which since
/// `use` learned to carry file identity is every path through
/// [`run_in_surface`].
pub fn parse_tree(src: &str) -> Result<Vec<blue_lang_syntax::Spanned>, RunError> {
    parse_tree_with_depth(src, blue_lang_syntax::MAX_EXPR_DEPTH)
}

/// Run blue source with no build inputs.
pub fn run(src: &str) -> Result<Run, RunError> {
    run_with_inputs(src, Inputs::new())
}

/// Run blue source, giving the macro phase access to verified build inputs.
///
/// `inputs` is already verified — [`Inputs`] cannot hold bytes that do not match
/// their declared hash — so nothing here re-checks. The capability a macro gains
/// is exactly "these hashed bytes", never a path.
pub fn run_with_inputs(src: &str, inputs: Inputs) -> Result<Run, RunError> {
    run_with_loader(src, inputs, &crate::uses::NoLoader)
}

/// Run blue source with a loader, so `use("name")` can resolve.
///
/// Split from [`run_with_inputs`] rather than folded into it because loading a
/// package reads a filesystem, and this crate has a `wasm32-unknown-unknown`
/// consumer with zero host imports. The capability is injected by callers that
/// have it — `blue_lang_pkg::LoadPath` is the real one — and absent by default,
/// where a `use` is a typed error naming the package.
pub fn run_with_loader(
    src: &str,
    inputs: Inputs,
    loader: &dyn crate::uses::Loader,
) -> Result<Run, RunError> {
    run_in_surface(Entry::anonymous(src), inputs, loader, None)
}

/// Run blue source written in a `yakugo` surface.
///
/// The pack applies at PARSE time and nowhere else — by the time the checker
/// sees the program it is canonical, so every stage below is identical whatever
/// surface the author wrote in. That is what makes a surface a surface: it
/// changes how a program is spelled and nothing about how it runs.
///
/// `entry` carries the source AND the file it was read from, because a type
/// error has to be reported somewhere: a caller with a path should pass it, and
/// one without ([`Entry::anonymous`]) gets diagnostics that say so rather than
/// diagnostics that guess. Imported packages name themselves through the
/// loader either way.
///
/// # Errors
///
/// As [`run_with_loader`].
pub fn run_in_surface(
    entry: Entry<'_>,
    inputs: Inputs,
    loader: &dyn crate::uses::Loader,
    surface: Option<&blue_lang_syntax::yakugo::Yakugo>,
) -> Result<Run, RunError> {
    run_framed(entry, inputs, loader, surface, None)
}

/// [`run_in_surface`] held to `hold` when one is given: a host name it
/// withholds, written in the entry file, refuses the program before it runs,
/// and one reached through a bidama or a spawned process is a breach where it
/// is called; a provided capability's names reach its provider. `None` runs
/// with every capability.
///
/// # Errors
///
/// As [`run_with_loader`], and [`RunError::Types`] naming each host name the
/// entry file writes that `hold` withholds.
pub fn run_framed(
    entry: Entry<'_>,
    inputs: Inputs,
    loader: &dyn crate::uses::Loader,
    surface: Option<&blue_lang_syntax::yakugo::Yakugo>,
    hold: Option<&crate::Hold>,
) -> Result<Run, RunError> {
    run_framed_accounted(
        entry,
        inputs,
        loader,
        surface,
        hold,
        &crate::Account::default(),
    )
}

/// [`run_framed`] giving `account` of itself: the host calls the run and its
/// processes make, and the identities of what it runs (`crate::Account`).
///
/// # Errors
///
/// As [`run_framed`].
pub fn run_framed_accounted(
    entry: Entry<'_>,
    inputs: Inputs,
    loader: &dyn crate::uses::Loader,
    surface: Option<&blue_lang_syntax::yakugo::Yakugo>,
    hold: Option<&crate::Hold>,
    account: &crate::Account,
) -> Result<Run, RunError> {
    // The interpreter is built BEFORE the check stage, because it is the check
    // stage's name oracle: every builtin, macro and special form a program may
    // name is read off the interpreter that will run it, never off a list.
    // Building it is not a stage; nothing is evaluated until `eval_prepared`.
    let (mut interp, mut prepared) = prepared_on(entry, inputs, loader, surface)?;
    hold_to_frame(&mut interp, &mut prepared, hold, account)?;
    let value = evaluate_held(&mut interp, &prepared, hold, account)?;
    Ok(Run {
        value,
        visited: prepared.visited,
        typed_decls: prepared.typed_decls,
        seams: prepared.seams,
    })
}

/// A prepared program's top-level forms, then its `main`, held to
/// `max_alloc_bytes` ([`crate::memory`]), met with `hold`'s.
fn evaluate_held(
    interp: &mut tatara_lisp_eval::Interpreter<()>,
    prepared: &Prepared,
    hold: Option<&crate::Hold>,
    account: &crate::Account,
) -> Result<Value, RunError> {
    let bound = crate::execution_bounds_under(hold).max_alloc_bytes;
    let (outcome, over) = crate::memory::held_on(interp, bound, |interp| {
        let value = crate::timings::stage(crate::timings::Stage::Eval, || {
            eval_prepared(interp, prepared, &mut ())
        })?;
        Ok(crate::timings::stage(crate::timings::Stage::Main, || {
            call_main(interp, prepared, &mut ())
        })?
        .unwrap_or(value))
    });
    if let Some(steps) = &account.steps {
        steps.store(
            u64::try_from(interp.steps_spent()).unwrap_or(u64::MAX),
            std::sync::atomic::Ordering::Relaxed,
        );
    }
    refused_past(outcome, over)
}

/// `outcome`, or the memory refusal when the evaluation passed `over` and
/// still returned.
fn refused_past<T>(outcome: Result<T, RunError>, over: Option<u64>) -> Result<T, RunError> {
    match (outcome, over) {
        (Ok(_), Some(bound)) => Err(RunError::Eval(Box::new(crate::observe::Fault::unplaced(
            &crate::memory::refusal(bound),
            &[],
        )))),
        (outcome, _) => outcome,
    }
}

/// Bind `hold` into `interp` and its processes, with each scoped provider's
/// packages moved onto it (`Hold::rebind_scoped`); a withheld name the entry
/// file writes refuses the program before it runs. With an `account` that
/// identifies, the program's identities are deferred to it and the node is
/// attached again knowing them; without a hold or one, nothing changes.
fn hold_to_frame(
    interp: &mut tatara_lisp_eval::Interpreter<()>,
    prepared: &mut Prepared,
    hold: Option<&crate::Hold>,
    account: &crate::Account,
) -> Result<(), RunError> {
    if account.defer_identities(
        &prepared.program,
        std::sync::Arc::clone(&prepared.lowered),
        main_key(prepared),
    ) {
        let places = places_of(&prepared.program, &prepared.erased);
        account.places.defer(move || places);
    }
    let Some(hold) = hold else {
        if account.identify.is_some() {
            crate::attach_node_accounted(interp, None, account);
        }
        return Ok(());
    };
    let withheld = hold.rebind_scoped(&prepared.program, &mut prepared.erased);
    let escapes = entry_escapes(&prepared.program, &withheld, &|cap| {
        format!("this run does not allow; pass --allow {cap} to grant it")
    });
    if !escapes.is_empty() {
        return Err(RunError::Types(escapes));
    }
    hold.bind(interp, "this run's frame", &account.host_io);
    crate::attach_node_accounted(interp, Some(hold), account);
    Ok(())
}

/// Each key a top-level `define` of `program` binds (`erased`, one form per
/// top-level form), with the file it came from: what a crash trace turns a
/// breaching call's span into a file, line and column against. Each file's
/// text is shared by every key it defines.
fn places_of(
    program: &crate::uses::ResolvedProgram,
    erased: &[tatara_lisp::Spanned],
) -> std::collections::BTreeMap<String, blue_lang_proc::Source> {
    let files: Vec<blue_lang_proc::Source> = program
        .files()
        .iter()
        .map(|f| blue_lang_proc::Source {
            file: f
                .path
                .as_ref()
                .map_or_else(|| "<anonymous>".to_string(), |p| p.display().to_string()),
            text: std::sync::Arc::from(f.text.as_str()),
        })
        .collect();
    erased
        .iter()
        .enumerate()
        .filter_map(|(i, form)| {
            let key = blue_lang_proc::violation::defined_key(form)?;
            let source = files.get(program.owner_of(i)?.index())?;
            Some((key.to_string(), source.clone()))
        })
        .collect()
}

fn entry_escapes(
    program: &crate::uses::ResolvedProgram,
    refused: &[(&'static str, blue_lang_waku::Capability)],
    grant: &dyn Fn(&str) -> String,
) -> Vec<String> {
    use crate::uses::ResolvedProgram;
    let forms: Vec<tatara_lisp::Spanned> = program
        .forms()
        .iter()
        .enumerate()
        .filter(|(i, _)| program.owner_of(*i) == Some(ResolvedProgram::ENTRY))
        .map(|(_, f)| f.clone())
        .collect();
    let label = |name: &str| {
        refused
            .iter()
            .find(|(n, _)| *n == name)
            .map(|(_, c)| c.label())
    };
    blue_lang_waku::free_names(&forms, &|name| label(name).is_none())
        .into_iter()
        .filter_map(|name| {
            let cap = label(&name)?;
            let at = program
                .file(ResolvedProgram::ENTRY)
                .and_then(|f| f.path.clone())
                .map_or_else(|| "<entry>".to_string(), |p| p.display().to_string());
            Some(format!(
                "{at}: refused: `{name}` reaches the host ({cap}), which {}",
                grant(cap)
            ))
        })
        .collect()
}

/// The interpreter a program runs on, with `inputs` bound for its macros.
fn runtime(inputs: Inputs) -> tatara_lisp_eval::Interpreter<()> {
    let mut interp =
        crate::timings::stage(crate::timings::Stage::Runtime, crate::interpreter_hostless);
    crate::inputs::install_input_primitives(&mut interp, inputs);
    interp
}

/// [`runtime`], and the program prepared against that interpreter's names.
fn prepared_on(
    entry: Entry<'_>,
    inputs: Inputs,
    loader: &dyn crate::uses::Loader,
    surface: Option<&blue_lang_syntax::yakugo::Yakugo>,
) -> Result<(tatara_lisp_eval::Interpreter<()>, Prepared), RunError> {
    let interp = runtime(inputs);
    let builtins = crate::timings::stage(crate::timings::Stage::Names, || builtin_names(&interp));
    let prepared = prepare(entry, loader, surface, &builtins)?;
    Ok((interp, prepared))
}

/// A program past every stage before evaluation, kept as data: the tree
/// `def_hash` reads (`lowered`), the tree that runs (`erased`), one form per
/// top-level form of `program` in both, and the runtime key of the entry
/// file's `main`. What `blue bundle` seals into an appliance, and what
/// [`run_compiled`] evaluates with no loader and no checker.
pub struct Compiled {
    pub program: crate::uses::ResolvedProgram,
    pub lowered: Vec<tatara_lisp::Spanned>,
    pub erased: Vec<tatara_lisp::Spanned>,
    pub main: Option<String>,
}

/// Parse, resolve, check and erase `entry`, and stop before evaluation. Under
/// a `hold`, a host name the entry file writes that the hold withholds
/// refuses the program here, as [`run_framed`] refuses it before it runs.
///
/// # Errors
///
/// As [`run_framed`], with no runtime error: nothing is evaluated.
pub fn compile(
    entry: Entry<'_>,
    loader: &dyn crate::uses::Loader,
    surface: Option<&blue_lang_syntax::yakugo::Yakugo>,
    hold: Option<&crate::Hold>,
) -> Result<Compiled, RunError> {
    let (_, prepared) = prepared_on(entry, Inputs::new(), loader, surface)?;
    if let Some(hold) = hold {
        let escapes = entry_escapes(&prepared.program, &hold.withheld_host_names(), &|cap| {
            format!("this bundle's policy does not allow; declare allow(%i[{cap}]) in the project's Bluefile and run `blue lock`")
        });
        if !escapes.is_empty() {
            return Err(RunError::Types(escapes));
        }
    }
    let main = main_key(&prepared);
    let Prepared {
        program,
        lowered,
        erased,
        ..
    } = prepared;
    Ok(Compiled {
        program,
        lowered: std::sync::Arc::unwrap_or_clone(lowered),
        erased,
        main,
    })
}

/// Evaluate compiled forms under `hold`, then call `main` when one is named.
/// The hold is not optional: a compiled program has no ambient run. `who`
/// names the hold in a breach's message. Errors carry no position: the
/// forms carry no source.
///
/// # Errors
///
/// [`RunError::Eval`] when a form or `main` raises, a breach included
/// ([`crate::observe::Fault::breach`]).
pub fn run_compiled(
    erased: &[tatara_lisp::Spanned],
    main: Option<&str>,
    hold: &crate::Hold,
    who: &'static str,
) -> Result<Value, RunError> {
    let mut interp = runtime(Inputs::new());
    let account = crate::Account::default();
    hold.bind(&mut interp, who, &account.host_io);
    crate::attach_node_accounted(&mut interp, Some(hold), &account);
    let fault = |e: tatara_lisp_eval::EvalError| {
        RunError::Eval(Box::new(crate::observe::Fault::unplaced(
            &crate::memory::named(e),
            erased,
        )))
    };
    let bound = hold.execution_bounds().max_alloc_bytes;
    let (outcome, over) = crate::memory::held_on(&mut interp, bound, |interp| {
        let mut value = Value::Nil;
        for form in erased {
            value = interp.eval_top_form(form, &mut ()).map_err(fault)?;
        }
        if let Some(key) = main {
            let at = tatara_lisp::Span::synthetic();
            let call = tatara_lisp::Spanned::new(
                at,
                tatara_lisp::SpannedForm::List(vec![tatara_lisp::Spanned::new(
                    at,
                    tatara_lisp::SpannedForm::Atom(tatara_lisp::Atom::Symbol(key.to_string())),
                )]),
            );
            value = interp.eval_top_form(&call, &mut ()).map_err(fault)?;
        }
        Ok(value)
    });
    refused_past(outcome, over)
}

/// A run watched by a call observer, and the definitions the observer was
/// built over.
pub struct Observed {
    pub definitions: std::sync::Arc<crate::observe::Definitions>,
    /// The run itself: its value, or the error it stopped on.
    pub outcome: Result<Run, RunError>,
}

/// What a call observer is built from: the program past every stage before
/// evaluation, its tree before erasure (what `def_hash` reads) and after it
/// (what runs), and the definitions read off it.
pub struct Watched<'a> {
    pub definitions: &'a std::sync::Arc<crate::observe::Definitions>,
    pub program: &'a crate::uses::ResolvedProgram,
    pub lowered: &'a [tatara_lisp::Spanned],
    pub erased: &'a [tatara_lisp::Spanned],
}

/// [`run_in_surface`] with a call observer installed for the evaluation.
/// `watch` builds the observer once every stage before evaluation has
/// passed; the profiler, the tracer, coverage and the call memo are all built
/// this way (`crate::observe::Recorder`, `blue-lang-mondou`'s
/// `recall::Recall`).
///
/// # Errors
///
/// A parse, import or check error, which leaves nothing to run. A runtime
/// error is the [`Observed::outcome`], so what ran before it is still read.
pub fn run_observed(
    entry: Entry<'_>,
    inputs: Inputs,
    loader: &dyn crate::uses::Loader,
    surface: Option<&blue_lang_syntax::yakugo::Yakugo>,
    watch: impl FnOnce(&Watched<'_>) -> std::sync::Arc<dyn crate::observe::CallObserver>,
) -> Result<Observed, RunError> {
    run_observed_framed(entry, inputs, loader, surface, None, watch)
}

/// [`run_observed`] held to `frame` as [`run_framed`] holds a run.
///
/// # Errors
///
/// As [`run_observed`], and as [`run_framed`] for a host name the entry file
/// writes that `frame` does not grant.
pub fn run_observed_framed(
    entry: Entry<'_>,
    inputs: Inputs,
    loader: &dyn crate::uses::Loader,
    surface: Option<&blue_lang_syntax::yakugo::Yakugo>,
    hold: Option<&crate::Hold>,
    watch: impl FnOnce(&Watched<'_>) -> std::sync::Arc<dyn crate::observe::CallObserver>,
) -> Result<Observed, RunError> {
    run_observed_accounted(
        entry,
        inputs,
        loader,
        surface,
        hold,
        &crate::Account::default(),
        watch,
    )
}

/// [`run_observed_framed`] giving `account` of itself, as
/// [`run_framed_accounted`] does.
///
/// # Errors
///
/// As [`run_observed_framed`].
pub fn run_observed_accounted(
    entry: Entry<'_>,
    inputs: Inputs,
    loader: &dyn crate::uses::Loader,
    surface: Option<&blue_lang_syntax::yakugo::Yakugo>,
    hold: Option<&crate::Hold>,
    account: &crate::Account,
    watch: impl FnOnce(&Watched<'_>) -> std::sync::Arc<dyn crate::observe::CallObserver>,
) -> Result<Observed, RunError> {
    let (mut interp, mut prepared) = prepared_on(entry, inputs, loader, surface)?;
    hold_to_frame(&mut interp, &mut prepared, hold, account)?;
    let definitions = std::sync::Arc::new(crate::observe::Definitions::of(
        &prepared.program,
        &prepared.erased,
    ));
    interp.set_call_observer(Some(watch(&Watched {
        definitions: &definitions,
        program: &prepared.program,
        lowered: &prepared.lowered,
        erased: &prepared.erased,
    })));
    let outcome = evaluate_held(&mut interp, &prepared, hold, account).map(|value| Run {
        value,
        visited: prepared.visited,
        typed_decls: prepared.typed_decls,
        seams: prepared.seams,
    });
    interp.set_call_observer(None);
    Ok(Observed {
        definitions,
        outcome,
    })
}

/// A program past every stage before evaluation: parsed, its imports
/// resolved, type-checked and erased. What [`run_in_surface`] and
/// [`crate::hosted::load_hosted`] both evaluate, so the stage order this
/// module exists to own is written once for both.
pub(crate) struct Prepared {
    program: crate::uses::ResolvedProgram,
    lowered: std::sync::Arc<Vec<tatara_lisp::Spanned>>,
    erased: Vec<tatara_lisp::Spanned>,
    visited: usize,
    typed_decls: usize,
    seams: usize,
}

impl Prepared {
    /// The forms the evaluator will run: every file's, resolved and erased.
    pub(crate) fn erased(&self) -> &[tatara_lisp::Spanned] {
        &self.erased
    }

    /// The entry file's namespace.
    pub(crate) fn entry_namespace(&self) -> Namespace {
        let first = (0..self.program.forms().len())
            .find(|i| self.program.owner_of(*i) == Some(crate::uses::ResolvedProgram::ENTRY));
        match first {
            Some(i) => namespace_of(&self.program, i),
            None => match self
                .program
                .file(crate::uses::ResolvedProgram::ENTRY)
                .and_then(|f| f.package.clone())
            {
                Some(p) => Namespace::Bidama(p),
                None => Namespace::File(String::new()),
            },
        }
    }
}

/// Parse, resolve, check and erase, in that order.
///
/// `builtins` is the name table of the interpreter that will evaluate the
/// result ([`builtin_names`]); the check stage resolves the program's names
/// against it.
pub(crate) fn prepare(
    entry: Entry<'_>,
    loader: &dyn crate::uses::Loader,
    surface: Option<&blue_lang_syntax::yakugo::Yakugo>,
    builtins: &NameTable,
) -> Result<Prepared, RunError> {
    let mut program = parse_and_resolve(entry, loader, surface)?;

    // `test` blocks are declarations for the harness, not code to run.
    //
    // Dropped here rather than in `resolve_uses`, because `blue test` calls
    // the resolver and then NEEDS the entry file's blocks — so the two
    // callers want different things and the split has to live at this level.
    //
    // Without this, `blue run` on a file containing its own tests fails with
    // `unbound symbol: deftest`: every package in the bidama distribution
    // carries tests, so every one of them was unrunnable.
    //
    // Through `retain`, which drops each form's owner with it. A plain filter
    // over the forms alone would slide every later form onto the wrong file.
    program.retain(|f| !crate::uses::is_test_form(f));

    // CHECK, on the annotated tree — the only tree that has annotations.
    //
    // **On the REAL spanned tree, including every imported package's.** This
    // was the one caller that checked a spanless lift, because `resolve_uses`
    // flattened the entry file and its imports into one list and `Span` is a
    // byte range with no file identity — so a real span here would have
    // reported an imported package's error at that offset in the ENTRY file, a
    // precise-looking answer pointing at unrelated code.
    //
    // The fix is not a wider `Span` (that type is upstream, and its own docs
    // put file identity on the caller: spans "are meaningful only relative to
    // the string that produced them, which the caller is responsible for
    // holding onto"). blue holds onto it BESIDE the span, per top-level form —
    // see `uses::ResolvedProgram`.
    let (outcome, names) = crate::timings::stage(crate::timings::Stage::Check, || {
        check_stage(&program, builtins, false)
    });
    if !outcome.ok() {
        return Err(RunError::Types(
            outcome
                .errors()
                // `file:line:col: error[CODE]: message`, resolved against the
                // file the form actually came from, then its help line.
                .map(|d| render(&program, d))
                .collect(),
        ));
    }

    // ERASE, so the interpreter never sees a type — **on the spanned tree,
    // and back out as one.**
    //
    // This used to be `erase_types(&program.sexps())` followed by a
    // `lower_to_spanned` that stamped `Span::synthetic()` over every node, and
    // the comment here said carrying real positions through was "a larger
    // piece and is NOT built". It was not larger: erasure only ever DELETES
    // nodes — the single node it invents is the `define` replacing
    // `define-typed` — so there was never anything for a synthetic span to
    // stand in for. See `crate::erase`.
    //
    // No lowering step follows. The tree the evaluator receives IS the tree the
    // parser built, minus annotations, with the author's byte offsets intact.
    let (lowered, erased) = crate::timings::stage(crate::timings::Stage::Erase, || {
        let lowered = lower(&program, &names);
        let erased = erase_types(&lowered);
        (lowered, erased)
    });

    Ok(Prepared {
        program,
        lowered: std::sync::Arc::new(lowered),
        erased,
        visited: outcome.stats.visited,
        typed_decls: outcome.stats.typed_decls,
        seams: outcome.seams.len(),
    })
}

/// Parse the entry (in `surface`, if one is given) and splice in its imports.
pub(crate) fn parse_and_resolve(
    entry: Entry<'_>,
    loader: &dyn crate::uses::Loader,
    surface: Option<&blue_lang_syntax::yakugo::Yakugo>,
) -> Result<crate::uses::ResolvedProgram, RunError> {
    let forms = crate::timings::stage(crate::timings::Stage::Parse, || {
        let mut forms = match surface {
            Some(pack) => blue_lang_syntax::parse_program_tree_in(entry.text, pack)
                .map_err(|e| RunError::Parse(e.to_string()))?,
            None => loader
                .parse(entry.text)
                .map_err(|e| RunError::Parse(e.to_string()))?,
        };
        // Every `@doc` example is a `test` block of the entry file: checked with
        // the file's names, run by `blue test`, dropped by `run` with the others.
        if surface.is_none() {
            forms.extend(
                blue_lang_syntax::doc::doctests(entry.text)
                    .map_err(|e| RunError::Parse(e.to_string()))?,
            );
        }
        Ok::<_, RunError>(forms)
    })?;

    // RESOLVE imports first, so everything below sees ONE program.
    //
    // Before the check on purpose: imported code is type-checked at the point
    // its consumer imports it, rather than at whatever later moment its code
    // first runs. A package that does not typecheck should break its importer's
    // build, not their production run.
    //
    // One program, but not one FILE: the result records which file each
    // top-level form came from, which is what lets a diagnostic below name a
    // place instead of only a problem.
    crate::timings::stage(crate::timings::Stage::Resolve, || {
        crate::uses::resolve_uses(forms, entry, loader).map_err(RunError::Import)
    })
}

/// **The check stage**: every rule in `blue_lang_check::RULES`, over a
/// resolved program, with waivers applied.
///
/// One function, called by every door — `run`, the hosted loader, `blue test`
/// and `blue check` — so a rule added to the registry is enforced by all of
/// them at once. That is what makes an architecture rule a pipeline error
/// rather than an optional report: there is no door that skips it.
///
/// Warnings (unused bindings, unused waivers) are reported for the ENTRY
/// file only; an imported package's warnings belong to its author. Errors
/// are reported for every file, because an imported package with one is
/// broken for its importer.
pub(crate) fn check_stage(
    program: &crate::uses::ResolvedProgram,
    builtins: &NameTable,
    with_tests: bool,
) -> (blue_lang_check::Outcome, NameTable) {
    use crate::uses::ResolvedProgram;
    let forms = program.forms();
    let is_entry = |i: usize| program.owner_of(i) == Some(ResolvedProgram::ENTRY);

    // Rules B0003–B0005: the typing ladder.
    let mut outcome = blue_lang_check::check_program_in(forms, &|a, b| {
        program.owner_of(a) == program.owner_of(b)
    });
    outcome
        .diagnostics
        .extend(data_law_diagnostics(program, &is_entry));

    // Rules B0001–B0002: names. The program's own scopes come first (the
    // entry file, then each bidama in import order), then the interpreter's.
    let table = program_names(program, builtins);
    let whole = |i: usize| with_tests && is_entry(i);
    let (names, resolved) = blue_lang_check::names::check_names_whole(
        forms,
        &table,
        &|i| namespace_of(program, i),
        &is_entry,
        &whole,
    );
    let stored = program
        .file(ResolvedProgram::ENTRY)
        .is_some_and(|f| f.path.is_some());
    outcome.diagnostics.extend(names);
    outcome.stats.names_resolved = resolved;
    if stored {
        let script = program
            .file(ResolvedProgram::ENTRY)
            .is_some_and(|f| f.package.is_none());
        let found = blue_lang_check::form_rules::check(forms, &is_entry, script);
        let silenced: Vec<tatara_lisp::Span> = found
            .iter()
            .filter(|d| d.code == blue_lang_check::Code::B0038)
            .map(|d| d.span)
            .collect();
        outcome
            .diagnostics
            .retain(|d| !(d.code == blue_lang_check::Code::B0002 && silenced.contains(&d.span)));
        outcome.diagnostics.extend(found);
    }
    outcome
        .diagnostics
        .extend(blue_lang_check::contracts::check(
            forms,
            &table,
            &|i| namespace_of(program, i),
            &is_entry,
            &|i| {
                program
                    .owner_of(i)
                    .and_then(|f| program.file(f))
                    .map(|f| f.text.as_str())
            },
            crate::docs::signatures(),
        ));

    outcome.diagnostics.extend(doc_diagnostics(program));

    // Waivers, per file: B0007 for a malformed one, B0008 for one that
    // suppresses nothing.
    let mut waivers = Vec::new();
    for file in program.files() {
        let spans: Vec<(usize, tatara_lisp::Span)> = forms
            .iter()
            .enumerate()
            .filter(|(i, _)| program.owner_of(*i) == Some(file.id))
            .map(|(i, f)| (i, f.span))
            .collect();
        let (found, malformed) = blue_lang_check::waiver::collect(&file.text, &spans);
        waivers.extend(found);
        outcome.diagnostics.extend(malformed);
    }
    outcome.waived = blue_lang_check::waiver::apply(&mut outcome.diagnostics, waivers, &is_entry);
    if !stored {
        outcome.diagnostics.retain(|d| {
            !matches!(
                d.code,
                blue_lang_check::Code::B0023
                    | blue_lang_check::Code::B0036
                    | blue_lang_check::Code::B0037
                    | blue_lang_check::Code::B0067
                    | blue_lang_check::Code::B0061
                    | blue_lang_check::Code::B0062
                    | blue_lang_check::Code::B0063
            )
        });
    }
    let judge = blue_lang_check::evolution::FormJudge::from_env().unwrap_or_default();
    outcome
        .diagnostics
        .retain(|d| judge.reports(d.code, is_entry(d.top_level)));
    // A rule whose census has not reached zero is computed, and counted, but
    // not enforced: its findings move to `census` (see `RULES`' `ratchet`).
    let (enforced, census): (Vec<_>, Vec<_>) = std::mem::take(&mut outcome.diagnostics)
        .into_iter()
        .partition(|d| d.code.rule().active());
    outcome.diagnostics = enforced;
    outcome.census = census;
    outcome
        .diagnostics
        .sort_by_key(|d| (d.top_level, d.span.start, d.code));
    (outcome, table)
}

/// The documentation rules (B0056–B0060) over the entry file, when it is a
/// bidama's: a bidama is judged at its own check, as its form is; an importer
/// is not answerable for a dependency's documentation.
fn doc_diagnostics(program: &crate::uses::ResolvedProgram) -> Vec<blue_lang_check::Diagnostic> {
    use crate::uses::ResolvedProgram;
    let Some(file) = program.file(ResolvedProgram::ENTRY) else {
        return Vec::new();
    };
    let Some(package) = file.package.as_deref() else {
        return Vec::new();
    };
    let forms: Vec<(usize, &tatara_lisp::Spanned)> = program
        .forms()
        .iter()
        .enumerate()
        .filter(|(i, f)| {
            program.owner_of(*i) == Some(ResolvedProgram::ENTRY)
                && !blue_lang_syntax::doc::is_doctest(f)
        })
        .collect();
    let graph = file.path.as_deref().map(crate::doc_sources::graph_meanings);
    let meaning = |name: &str| {
        graph
            .as_ref()
            .and_then(|g| g.get(&(package.to_string(), name.to_string())).cloned())
    };
    let names_line = |name: &str| crate::docs::doc_of(name).map(|d| d.doc.to_string());
    blue_lang_check::doc_rules::check_file(
        &file.text,
        &forms,
        package,
        &blue_lang_check::doc_rules::Sources {
            meaning: &meaning,
            names_line: &names_line,
        },
    )
}

fn data_law_diagnostics(
    program: &crate::uses::ResolvedProgram,
    is_entry: &dyn Fn(usize) -> bool,
) -> Vec<blue_lang_check::Diagnostic> {
    use blue_lang_check::data_laws;
    let forms = program.forms();
    let fragments = data_laws::Fragments::collect(forms);
    let frontend = program.frontend();
    let mut out = Vec::new();
    let schema = match frontend.and_then(|f| f.table.as_ref()) {
        Some((label, text)) => match data_laws::Schema::read(text) {
            Ok(s) => Some(s),
            Err(why) => {
                if let Some((i, first)) = forms.iter().enumerate().find(|(i, _)| is_entry(*i)) {
                    out.push(
                        blue_lang_check::Diagnostic::new(
                            blue_lang_check::Code::B0050,
                            format!("the generated schema table {label} does not read: {why}"),
                            first.span,
                        )
                        .at_top_level(i)
                        .with_help("regenerate it: `nix run .#regen`"),
                    );
                }
                None
            }
        },
        None => None,
    };
    if fragments.is_empty() && schema.is_none() && !frontend.is_some_and(|f| f.view) {
        return out;
    }
    out.extend(data_laws::check(
        forms,
        &data_laws::Context {
            fragments: &fragments,
            schema: schema.as_ref(),
            is_entry,
            view: frontend.is_some_and(|f| f.view),
        },
    ));
    out
}

/// The whole name table the check stage resolves against: the program's
/// own scopes (each file and bidama, by namespace) followed by `builtins`.
///
/// **A top-level call to a builtin macro can define names**: `defflow(slug,
/// trim, downcase)` expands to `(define slug …)`, and nothing in the source
/// spells `define`. Such a call is expanded here, on a hostless fork, and what
/// its expansion defines is bound in the calling file's namespace. Only
/// BUILTIN macros are expanded: their bodies are the runtime's own
/// templates. A program's own `defmacro` is not run at check time — checking a
/// file (and an editor checking on every keystroke) must not execute the code
/// it checks — so names a program macro generates are not seen; none of the
/// corpus's macros generates one (measured 2026-09-29).
#[must_use]
pub fn program_names(program: &crate::uses::ResolvedProgram, builtins: &NameTable) -> NameTable {
    use blue_lang_check::Binding;
    let mut table = NameTable::new();
    table.add_program(program.forms(), |i| namespace_of(program, i));
    let builtin_macro = |head: &str| {
        builtins
            .scopes()
            .iter()
            .any(|s| s.namespace == Namespace::Macro && s.get(head).is_some())
    };
    let mut expander: Option<tatara_lisp_eval::Interpreter<()>> = None;
    for (i, form) in program.forms().iter().enumerate() {
        let Some(head) = form
            .as_list()
            .and_then(|items| items.first())
            .and_then(tatara_lisp::Spanned::as_symbol)
        else {
            continue;
        };
        if !builtin_macro(head) {
            continue;
        }
        let interp = expander.get_or_insert_with(crate::interpreter_hostless);
        // A failed expansion defines nothing here; the evaluator will report
        // it, with its position, when the form runs.
        let Ok(expanded) = interp.fully_expand(form, &mut ()) else {
            continue;
        };
        let nullary = blue_lang_syntax::scope::nullary_definition(&expanded);
        for (name, span, kind) in blue_lang_check::names::definitions_of(&expanded) {
            table.define(
                namespace_of(program, i),
                Binding {
                    nullary: nullary == Some(name.as_str()),
                    name,
                    kind,
                    span: Some(span),
                    top_level: Some(i),
                },
            );
        }
    }
    for scope in builtins.scopes() {
        table.push(scope.clone());
    }
    table.spell_bare_like(builtins);
    let form_file: Vec<usize> = (0..program.forms().len())
        .map(|i| program.owner_of(i).map_or(usize::MAX, |f| f.index()))
        .collect();
    let mut imports: std::collections::BTreeMap<usize, blue_lang_check::names::FileImports> =
        std::collections::BTreeMap::new();
    for (file, import) in program.imports() {
        let entry = imports.entry(file.index()).or_default();
        entry.add(&import.package, import.names.iter().map(|(n, _)| n.clone()));
        let at = import.span.start;
        entry.use_at = Some(entry.use_at.map_or(at, |a| a.min(at)));
    }
    // A FACADE — a bidama that defines nothing and `use`s others (zenbu) —
    // exists so a consumer can depend on "everything": `use("zenbu")` makes
    // every member's QUALIFIER reachable (`toukei::median`), never a bare
    // name. Followed to a fixpoint, so a facade of facades works too.
    let facade_uses =
        |pkg: &str,
         imports: &std::collections::BTreeMap<usize, blue_lang_check::names::FileImports>| {
            let defines = table.bidama(pkg).is_some_and(|s| !s.is_empty());
            if defines {
                return std::collections::BTreeSet::new();
            }
            program
                .files()
                .iter()
                .filter(|f| f.package.as_deref() == Some(pkg))
                .filter_map(|f| imports.get(&f.id.index()))
                .flat_map(|i| i.uses.iter().cloned())
                .collect::<std::collections::BTreeSet<String>>()
        };
    loop {
        let mut grew = false;
        let files: Vec<usize> = imports.keys().copied().collect();
        for f in files {
            let used: Vec<String> = imports[&f].uses.iter().cloned().collect();
            for p in used {
                for member in facade_uses(&p, &imports) {
                    if let Some(i) = imports.get_mut(&f) {
                        if i.uses.insert(member.clone()) {
                            i.via.insert(member, p.clone());
                            grew = true;
                        }
                    }
                }
            }
        }
        if !grew {
            break;
        }
    }
    let mut pkg_uses: std::collections::BTreeMap<String, std::collections::BTreeSet<String>> =
        std::collections::BTreeMap::new();
    for (file, import) in program.imports() {
        if let Some(p) = program.file(*file).and_then(|f| f.package.clone()) {
            pkg_uses
                .entry(p)
                .or_default()
                .insert(import.package.clone());
        }
    }
    table.attach_files(form_file, imports);
    table.attach_package_uses(pkg_uses);
    table.attach_needs(program.needs().clone());
    // Where each file lives and which distribution each bidama ships in: a
    // bridge reference (B0021) is an error inside the bidama's own
    // distribution and a warning outside it.
    let canonical = |p: &std::path::Path| {
        std::fs::canonicalize(p)
            .unwrap_or_else(|_| p.to_path_buf())
            .display()
            .to_string()
    };
    let mut file_paths = std::collections::BTreeMap::new();
    let mut pkg_roots = std::collections::BTreeMap::new();
    for f in program.files() {
        if let Some(path) = &f.path {
            file_paths.insert(f.id.index(), canonical(path));
            if let (Some(pkg), Some(root)) =
                (&f.package, path.parent().and_then(std::path::Path::parent))
            {
                pkg_roots
                    .entry(pkg.clone())
                    .or_insert_with(|| canonical(root));
            }
        }
    }
    table.attach_paths(file_paths, pkg_roots);
    let versions = program.versions().clone();
    table.apply_legacy(program.forms(), &|i| namespace_of(program, i), &|p| {
        versions.get(p).cloned()
    });
    table
}

/// The forms the evaluator runs, from a checked program: every `use`
/// declaration inert (`nil`, so each index still names its top-level form)
/// and every name at the key it runs under — the RESOLVED tree under
/// per-bidama namespaces (`blue_lang_check::names::Resolved::resolved_tree`).
///
/// A definition runs as `retsu/first` (a script's as `%root/f`), a
/// reference to it as the same key, and a builtin as its bare name. Keys
/// cannot collide across namespaces, so a bidama's `first` no longer
/// replaces the builtin for anyone who did not import it, and an importer's
/// `helper` no longer replaces a bidama's own: the runtime binds exactly what
/// the check stage resolved.
#[must_use]
pub fn lower(
    program: &crate::uses::ResolvedProgram,
    names: &NameTable,
) -> Vec<tatara_lisp::Spanned> {
    lower_with(program, names, true)
}

#[must_use]
pub fn lower_with(
    program: &crate::uses::ResolvedProgram,
    names: &NameTable,
    simplify_chains: bool,
) -> Vec<tatara_lisp::Spanned> {
    let mut resolved = blue_lang_check::names::resolve_program(program.forms(), names, &|i| {
        namespace_of(program, i)
    });
    let simplified = if simplify_chains {
        chain_simplified(program.forms(), &resolved)
    } else {
        None
    };
    let forms: &[tatara_lisp::Spanned] = simplified.as_deref().unwrap_or(program.forms());
    if simplified.is_some() {
        resolved =
            blue_lang_check::names::resolve_program(forms, names, &|i| namespace_of(program, i));
    }
    resolved
        .resolved_tree(forms, blue_lang_check::names::Rule::Namespaced)
        .into_iter()
        .zip(forms)
        .enumerate()
        .map(|(i, (resolved, written))| {
            if crate::uses::use_target(written).is_some()
                || blue_lang_syntax::scope::legacy_target(written).is_some()
            {
                tatara_lisp::Spanned::new(written.span, tatara_lisp::SpannedForm::Nil)
            } else {
                let file = program.owner_of(i).and_then(|id| program.file(id));
                match file {
                    Some(f) => locate_raises(&resolved, &raise_site(f)),
                    None => resolved,
                }
            }
        })
        .collect()
}

fn chain_simplified(
    forms: &[tatara_lisp::Spanned],
    resolved: &blue_lang_check::names::Resolved,
) -> Option<Vec<tatara_lisp::Spanned>> {
    let respell: std::collections::HashMap<usize, blue_lang_check::respell::Respelling> = resolved
        .respellings
        .iter()
        .filter(|(_, r)| matches!(r.respell, blue_lang_check::respell::Respell::Chain(_)))
        .cloned()
        .collect();
    if respell.is_empty() {
        return None;
    }
    let bare = std::collections::HashSet::new();
    let canon = Canon {
        bare: &bare,
        respell: &respell,
    };
    Some(forms.iter().map(|f| canon.form(f)).collect())
}

fn raise_site(file: &crate::uses::SourceFile) -> impl Fn(tatara_lisp::Span) -> String + '_ {
    move |span| {
        let (line, _) =
            blue_lang_syntax::Span::line_col(&file.text, span.start.min(file.text.len()));
        let shown = file
            .path
            .as_ref()
            .map_or_else(|| "<source>".to_string(), |p| p.display().to_string());
        format!("{shown}:{line}")
    }
}

fn locate_raises(
    form: &tatara_lisp::Spanned,
    site: &dyn Fn(tatara_lisp::Span) -> String,
) -> tatara_lisp::Spanned {
    use tatara_lisp::{Atom, Spanned, SpannedForm};
    let inner = match &form.form {
        SpannedForm::List(items) => {
            let mut out: Vec<Spanned> = items.iter().map(|i| locate_raises(i, site)).collect();
            let raising = items.first().and_then(Spanned::as_symbol) == Some("raise")
                && (3..=4).contains(&items.len());
            if raising {
                out[0] = Spanned::new(
                    items[0].span,
                    SpannedForm::Atom(Atom::Symbol(crate::errors::RAISE_AT.to_string())),
                );
                out.insert(
                    1,
                    Spanned::new(items[0].span, SpannedForm::Atom(Atom::Str(site(form.span)))),
                );
            }
            SpannedForm::List(out)
        }
        SpannedForm::Quote(_) | SpannedForm::Quasiquote(_) => return form.clone(),
        other => other.clone(),
    };
    Spanned::new(form.span, inner)
}

/// The namespace top-level form `i` of `program` defines into.
#[must_use]
pub fn namespace_of(program: &crate::uses::ResolvedProgram, i: usize) -> Namespace {
    let file = program.owner_of(i).and_then(|id| program.file(id));
    match file {
        Some(f) => match &f.package {
            Some(p) => Namespace::Bidama(p.clone()),
            None => Namespace::File(
                f.path
                    .as_ref()
                    .map_or_else(|| "<anonymous>".to_string(), |p| p.display().to_string()),
            ),
        },
        None => Namespace::File("<unknown file>".to_string()),
    }
}

/// Names only the test harness binds.
///
/// In scope for EVERY check, not only for test blocks. A bidama may carry a
/// test helper — a plain `def` that asserts, called only from its `test`
/// blocks (`heni`'s `hn_end_to_end` is one) — and every program importing that
/// bidama would otherwise be refused for a function it never calls. The
/// refusal would be scoped to the importer's whole program, not to the fault.
/// The cost, stated: an `assert` outside any test that `blue run` actually
/// reaches is caught at runtime (`blue-assert` is unbound there), not here.
///
/// `blue-lang-test` registers these on its own interpreter, and this crate
/// cannot depend on it (it depends on this one), so the list lives beside the
/// only name in it: the lowered `assert`, which `blue-lang-syntax` owns.
pub const HARNESS_NAMES: &[&str] = &[
    blue_lang_syntax::LOWERED_ASSERT,
    blue_lang_syntax::LOWERED_ASSERT_PANICS,
    blue_lang_syntax::LOWERED_TEST_META,
];

/// The check stage's builtin scopes, read off the interpreter that will run
/// the program: the test harness's names ([`HARNESS_NAMES`]), then its special
/// forms, its macros, and every value it binds — the last three in the order
/// the evaluator consults for a head.
///
/// Read from a live interpreter rather than a list, for the reason
/// `Interpreter::resolve_head` gives: a list is a second copy of the truth and
/// goes stale on the next installer that lands. An embedder's own
/// primitives are in scope here because the embedder installs them first.
#[must_use]
pub fn builtin_names<H: 'static>(interp: &tatara_lisp_eval::Interpreter<H>) -> NameTable {
    builtin_names_with(interp, &[])
}

#[must_use]
pub fn builtin_names_with<H: 'static>(
    interp: &tatara_lisp_eval::Interpreter<H>,
    host: &[crate::host_surface::HostName],
) -> NameTable {
    use blue_lang_check::{Binding, Scope, ScopeKind};
    use tatara_lisp_eval::HeadBinding;
    let mut special = Scope::new(Namespace::SpecialForm);
    let mut macros = Scope::new(Namespace::Macro);
    let mut values = Scope::new(Namespace::Builtin);
    // `reserved_head_names` reads the ROOT frame only, so a name installed on
    // a fork (the input primitives, on every `run`) is invisible to it; those
    // are asked about by name instead, which `resolve_head` answers through
    // every frame.
    let mut names: Vec<std::sync::Arc<str>> = interp.reserved_head_names().into_iter().collect();
    names.extend(
        crate::inputs::INPUT_PRIMITIVES
            .iter()
            .filter(|n| interp.resolve_head(n).is_some())
            .map(|n| std::sync::Arc::from(*n)),
    );
    for name in names {
        let (scope, kind) = match interp.resolve_head(&name) {
            Some(HeadBinding::SpecialForm) => (&mut special, ScopeKind::SpecialForm),
            Some(HeadBinding::Macro) => (&mut macros, ScopeKind::Macro),
            _ => (&mut values, ScopeKind::Value),
        };
        let nullary = kind == ScopeKind::Value
            && interp.lookup_global(&name).is_some_and(|v| {
                nullary_value(&v)
                    || (crate::docs::doc_of(&name).is_some_and(|d| d.signature == &*name)
                        && matches!(
                            v,
                            tatara_lisp_eval::Value::NativeFn(_)
                                | tatara_lisp_eval::Value::Closure(_)
                        ))
            });
        scope.bind(Binding {
            name: name.to_string(),
            kind,
            span: None,
            top_level: None,
            nullary,
        });
    }
    for h in host {
        values.bind(Binding {
            name: h.name.clone(),
            kind: ScopeKind::Value,
            span: None,
            top_level: None,
            nullary: h.nullary(),
        });
    }
    let mut table = NameTable::new();
    let mut harness = Scope::new(Namespace::Harness);
    for n in HARNESS_NAMES {
        harness.bind(Binding {
            name: (*n).to_string(),
            kind: ScopeKind::Value,
            span: None,
            top_level: None,
            nullary: false,
        });
    }
    table.push(harness);
    table.push(special);
    table.push(macros);
    table.push(values);
    table.spell_bare_only(
        crate::docs::NAMES
            .iter()
            .filter(|d| d.signature == d.name)
            .map(|d| d.name.to_string())
            .chain(host.iter().filter(|h| h.nullary()).map(|h| h.name.clone()))
            .collect(),
    );
    table
}

#[must_use]
pub fn nullary_value(value: &tatara_lisp_eval::Value) -> bool {
    match value {
        tatara_lisp_eval::Value::NativeFn(f) => {
            matches!(f.arity, tatara_lisp_eval::ffi::Arity::Exact(0))
        }
        tatara_lisp_eval::Value::Closure(c) => c.params.is_empty() && c.rest.is_none(),
        _ => false,
    }
}

/// A diagnostic as a person reads it: `file:line:col: error[B0001]: message`,
/// then an indented `help:` line when it has one, and a `fix:` line naming
/// the one command that applies blue's fixer for it.
#[must_use]
pub fn render(program: &crate::uses::ResolvedProgram, d: &blue_lang_check::Diagnostic) -> String {
    let head = d.to_string();
    let mut out = program.locate(d.top_level, d.span, &head).to_string();
    if let Some(help) = &d.help {
        out.push_str("\n  help: ");
        out.push_str(help);
    }
    let file = program
        .owner_of(d.top_level)
        .and_then(|id| program.file(id))
        .and_then(|f| f.path.as_ref());
    if let Some(cmd) =
        file.and_then(|p| blue_lang_check::evolution::fix_command(d, &p.display().to_string()))
    {
        out.push_str("\n  fix: ");
        out.push_str(&cmd);
    }
    out
}

/// What [`check_entry`] checks.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Checking {
    /// The program `blue run` would evaluate: test blocks dropped.
    Program,
    /// The program plus the entry file's test blocks, as `blue test` and
    /// `blue check` see it.
    WithTests,
}

/// A program through the check stage, with everything the stage found.
pub struct Checked {
    pub program: crate::uses::ResolvedProgram,
    pub outcome: blue_lang_check::Outcome,
    /// The name table the stage resolved against: every program scope, then
    /// the builtins. What an editor completes from.
    pub names: NameTable,
}

impl Checked {
    /// The forms an evaluator runs: [`lower`]ed, then erased — the tree
    /// `run` evaluates, for a door that brings its own evaluator (the VM).
    #[must_use]
    pub fn erased(&self) -> Vec<tatara_lisp::Spanned> {
        erase_types(&self.lowered())
    }

    /// The program [`lower`]ed: what [`Checked::erased`] erases, and the
    /// tree `def_hash` reads (`crate::Account::defer_identities`).
    #[must_use]
    pub fn lowered(&self) -> Vec<tatara_lisp::Spanned> {
        lower(&self.program, &self.names)
    }

    /// What `blue test` hands the harness: the program [`lower`]ed, spans
    /// projected away.
    #[must_use]
    pub fn evaluable(&self) -> Vec<tatara_lisp::Sexp> {
        lower(&self.program, &self.names)
            .iter()
            .map(tatara_lisp::Spanned::to_sexp)
            .collect()
    }

    /// Every non-local reference, resolved under both rules — today's flat
    /// one and per-bidama namespaces — and the resolved trees built from them
    /// (`blue ast --resolved`).
    #[must_use]
    pub fn resolve(&self) -> blue_lang_check::names::Resolved {
        blue_lang_check::names::resolve_program(self.program.forms(), &self.names, &|i| {
            namespace_of(&self.program, i)
        })
    }
}

impl Checked {
    #[must_use]
    pub fn call_explicit_forms(&self) -> Vec<tatara_lisp::Spanned> {
        self.resolve().call_explicit_tree(self.program.forms())
    }

    #[must_use]
    pub fn canonical_entry(&self, src: &str) -> Option<Vec<tatara_lisp::Spanned>> {
        use crate::uses::ResolvedProgram;
        let program = &self.program;
        let entry: Vec<&tatara_lisp::Spanned> = program
            .forms()
            .iter()
            .enumerate()
            .filter(|(i, _)| program.owner_of(*i) == Some(ResolvedProgram::ENTRY))
            .map(|(_, f)| f)
            .filter(|f| !blue_lang_syntax::doc::is_doctest(f))
            .collect();
        let written = blue_lang_syntax::parse_program_tree(src).ok()?;
        let same = written.len() == entry.len()
            && written
                .iter()
                .zip(&entry)
                .all(|(w, e)| w.to_sexp() == e.to_sexp() && w.span == e.span);
        if !same {
            return None;
        }
        let resolved = self.resolve();
        let bare: std::collections::HashSet<usize> = resolved
            .parenthesized_nullary_calls()
            .into_iter()
            .filter(|r| program.owner_of(r.top_level) == Some(ResolvedProgram::ENTRY))
            .map(blue_lang_check::names::Reference::node_address)
            .collect();
        let waived: Vec<tatara_lisp::Span> = self
            .outcome
            .waived
            .iter()
            .map(|w| w.diagnostic.span)
            .collect();
        let respell: std::collections::HashMap<usize, blue_lang_check::respell::Respelling> =
            resolved
                .respellings
                .iter()
                .filter(|(_, r)| !waived.contains(&r.span))
                .cloned()
                .collect();
        let canon = Canon {
            bare: &bare,
            respell: &respell,
        };
        let forms: Vec<tatara_lisp::Spanned> = entry.into_iter().map(|f| canon.form(f)).collect();
        let script = program
            .file(ResolvedProgram::ENTRY)
            .is_some_and(|f| f.package.is_none());
        let forms = if script {
            blue_lang_check::form_rules::without_prefix(&forms).unwrap_or(forms)
        } else {
            forms
        };
        let forms = blue_lang_check::form_rules::without_main_guard(&forms).unwrap_or(forms);
        Some(blue_lang_check::form_rules::eta_reduced(&forms).unwrap_or(forms))
    }
}

struct Canon<'a> {
    bare: &'a std::collections::HashSet<usize>,
    respell: &'a std::collections::HashMap<usize, blue_lang_check::respell::Respelling>,
}

impl Canon<'_> {
    fn form(&self, form: &tatara_lisp::Spanned) -> tatara_lisp::Spanned {
        use tatara_lisp::{Spanned, SpannedForm};
        let inner = match &form.form {
            SpannedForm::List(items) => match items.as_slice() {
                [head] if self.bare.contains(&(std::ptr::from_ref(head) as usize)) => {
                    return Spanned::new(form.span, head.form.clone());
                }
                [head, ..]
                    if self
                        .respell
                        .contains_key(&(std::ptr::from_ref(head) as usize)) =>
                {
                    let r = &self.respell[&(std::ptr::from_ref(head) as usize)];
                    let walked: Vec<Spanned> = items.iter().map(|i| self.form(i)).collect();
                    return blue_lang_check::respell::apply(form, &walked, r);
                }
                _ => SpannedForm::List(items.iter().map(|i| self.form(i)).collect()),
            },
            SpannedForm::Quote(i) => SpannedForm::Quote(Box::new(self.form(i))),
            SpannedForm::Quasiquote(i) => SpannedForm::Quasiquote(Box::new(self.form(i))),
            SpannedForm::Unquote(i) => SpannedForm::Unquote(Box::new(self.form(i))),
            SpannedForm::UnquoteSplice(i) => SpannedForm::UnquoteSplice(Box::new(self.form(i))),
            other => other.clone(),
        };
        Spanned::new(form.span, inner)
    }
}

/// Parse, resolve and CHECK, without running: the door for `blue check`,
/// `blue test` and the language server.
///
/// Returns every diagnostic, errors and warnings alike, rather than failing on
/// the first error: a reader fixing a file wants the whole list, and an agent
/// repairing one wants it in one pass. Whether errors stop anything is the
/// caller's decision — `blue test` refuses to run tests over a program with
/// one, exactly as `run` refuses to evaluate it.
///
/// The name oracle is the interpreter `blue run` would build: hostless plus
/// input primitives.
///
/// # Errors
///
/// A parse or import error, which leaves no program to check.
pub fn check_entry(
    entry: Entry<'_>,
    loader: &dyn crate::uses::Loader,
    surface: Option<&blue_lang_syntax::yakugo::Yakugo>,
    checking: Checking,
) -> Result<Checked, RunError> {
    let mut program = parse_and_resolve(entry, loader, surface)?;
    if checking == Checking::Program {
        program.retain(|f| !crate::uses::is_test_form(f));
    }
    let host = match entry.path {
        Some(path) => crate::host_surface::near(path)
            .map_err(|e| RunError::Import(e.to_string()))?
            .map(|s| s.functions)
            .unwrap_or_default(),
        None => Vec::new(),
    };
    let interp = runtime(Inputs::new());
    let builtins = crate::timings::stage(crate::timings::Stage::Names, || {
        builtin_names_with(&interp, &host)
    });
    let (outcome, names) = crate::timings::stage(crate::timings::Stage::Check, || {
        check_stage(&program, &builtins, checking == Checking::WithTests)
    });
    Ok(Checked {
        program,
        outcome,
        names,
    })
}

#[must_use]
pub fn spelling_code(spelling: blue_lang_syntax::Spelling) -> blue_lang_check::Code {
    use blue_lang_check::Code;
    use blue_lang_syntax::Spelling;
    match spelling {
        Spelling::LogicalSymbol => Code::B0025,
        Spelling::Unless => Code::B0026,
        Spelling::ElseIf => Code::B0027,
        Spelling::CallForm => Code::B0028,
        Spelling::KeywordRocket => Code::B0029,
        Spelling::ParameterList => Code::B0030,
        Spelling::OperatorSpelling => Code::B0031,
        Spelling::TrailingComma => Code::B0032,
        Spelling::NegatedComparison => Code::B0034,
        Spelling::ElseNil => Code::B0035,
        Spelling::TryCatch => Code::B0037,
        Spelling::Apply => Code::B0042,
        Spelling::MapPun => Code::B0046,
        Spelling::NilTest => Code::B0047,
        Spelling::NewlineEscape => Code::B0065,
        Spelling::Index => Code::B0066,
        Spelling::TestDeclaration => Code::B0068,
    }
}

#[must_use]
pub fn form_diagnostics(text: &str) -> Vec<blue_lang_check::Diagnostic> {
    match blue_lang_fmt::format_source_lossless(text) {
        Ok(formatted) => form_diagnostics_against(text, &formatted),
        Err(_) => Vec::new(),
    }
}

#[must_use]
pub fn form_diagnostics_against(text: &str, formatted: &str) -> Vec<blue_lang_check::Diagnostic> {
    use blue_lang_check::{Code, Diagnostic};
    if formatted.trim_end() == text.trim_end() {
        return Vec::new();
    }
    let help = "`blue fmt --write FILE` writes it; no compile door writes a file (`BLUE_LAYOUT=rewrite` restores formatting in place)";
    let mut out: Vec<Diagnostic> = blue_lang_syntax::spelling_notes(text)
        .unwrap_or_default()
        .into_iter()
        .map(|n| {
            let message = if n.canonical.is_empty() {
                format!("`{}` is not written", n.written)
            } else {
                format!("`{}` is written `{}`", n.written, n.canonical)
            };
            Diagnostic::new(spelling_code(n.spelling), message, n.span)
                .at_top_level(0)
                .with_help(help)
        })
        .collect();
    out.extend(
        literal_diagnostics(text)
            .into_iter()
            .map(|d| d.with_help(help)),
    );
    if out.is_empty() {
        let at = text
            .lines()
            .zip(formatted.lines())
            .position(|(a, b)| a != b)
            .unwrap_or_else(|| text.lines().count().min(formatted.lines().count()));
        let start: usize = text.lines().take(at).map(|l| l.len() + 1).sum();
        let start = start.min(text.len());
        let end = text[start..].find('\n').map_or(text.len(), |e| start + e);
        out.push(
            Diagnostic::new(
                Code::B0024,
                format!("line {} is not laid out as blue writes it", at + 1),
                tatara_lisp::Span::new(start, end),
            )
            .at_top_level(0)
            .with_help(help),
        );
    }
    out.sort_by_key(|d| (d.span.start, d.code));
    out
}

fn literal_diagnostics(text: &str) -> Vec<blue_lang_check::Diagnostic> {
    use blue_lang_syntax::{Atom, TokenKind};
    let Ok(toks) = blue_lang_syntax::lex(text) else {
        return Vec::new();
    };
    toks.iter()
        .filter_map(|t| {
            let atom = match &t.kind {
                TokenKind::Int(v) => Atom::Int(*v),
                TokenKind::Float(v) => Atom::Float(*v),
                TokenKind::Str(v) => Atom::Str(v.clone()),
                _ => return None,
            };
            let written = text.get(t.span.start..t.span.end)?;
            let canonical = blue_lang_fmt::render_literal(&atom);
            (written != canonical).then(|| {
                blue_lang_check::Diagnostic::new(
                    blue_lang_check::Code::B0033,
                    format!("`{written}` is written `{canonical}`"),
                    t.span,
                )
                .at_top_level(0)
            })
        })
        .collect()
}

/// A syntax error in `text` as a [`B0006`](blue_lang_check::Code::B0006)
/// diagnostic, so a tool reading `--format json` gets a parse failure in the
/// same shape as every other finding. `None` when `text` parses.
#[must_use]
pub fn syntax_diagnostic(text: &str) -> Option<blue_lang_check::Diagnostic> {
    let e = blue_lang_syntax::parse_program_tree(text).err()?;
    Some(
        blue_lang_check::Diagnostic::new(blue_lang_check::Code::B0006, e.message, e.span)
            .at_top_level(0),
    )
}

/// A runtime message as the author wrote the names in it: a definition runs
/// under its key (`retsu/first`, `%root/f`), and a message naming one in
/// backticks names it `retsu::first`, or `f` for the author's own script.
#[must_use]
pub fn display_keys(message: &str) -> String {
    let mut out = String::with_capacity(message.len());
    let mut parts = message.split('`');
    if let Some(first) = parts.next() {
        out.push_str(first);
    }
    for (i, part) in parts.enumerate() {
        out.push('`');
        // Odd pieces (0-based here) are inside backticks.
        if i % 2 == 0 {
            out.push_str(&crate::observe::display_key(part));
        } else {
            out.push_str(part);
        }
    }
    out
}

/// Evaluate a prepared program's top-level forms into `interp`, with `host`.
pub(crate) fn eval_prepared<H: 'static>(
    interp: &mut tatara_lisp_eval::Interpreter<H>,
    prepared: &Prepared,
    host: &mut H,
) -> Result<Value, RunError> {
    let Prepared {
        program, erased, ..
    } = prepared;

    // RUN, one top-level form at a time, **counting them**.
    //
    // This is literally the loop `Interpreter::eval_program` runs internally
    // (tatara-lisp-eval `eval.rs`) — unrolled here for exactly one reason: the
    // INDEX. `resolve_uses` flattens N files into one form list and a `Span` is
    // a byte range with no file identity, so an offset alone is ambiguous
    // across files — 66 means something in every one of them. The index is the
    // join key back to `ResolvedProgram`'s file table, and `eval_program`
    // consumes it internally and hands back only the error.
    //
    // The same key, the same renderer and the same file table the type errors
    // above already use. A runtime error was the one diagnostic in this
    // function still reporting a bare message.
    let mut value = Value::Nil;
    for (top_level, form) in erased.iter().enumerate() {
        value = interp.eval_top_form(form, host).map_err(|e| {
            // The message, its position and the blue call stack, read off the
            // frames the error unwound through (`observe::Fault`). The message
            // is `short_message` rather than upstream's `Display`, whose
            // trailing ` at {span}` is a bare byte range with no file, through
            // `messages::describe`, which names the function a wrong argument
            // count was called on.
            RunError::Eval(Box::new(crate::observe::Fault::of(
                program,
                erased,
                top_level,
                &crate::memory::named(e),
                &interp.take_trace(),
            )))
        })?;
    }
    Ok(value)
}

pub const MAIN: &str = "main";

#[must_use]
pub fn entry_main(program: &crate::uses::ResolvedProgram) -> Option<(usize, tatara_lisp::Span)> {
    use crate::uses::ResolvedProgram;
    let stored = program
        .file(ResolvedProgram::ENTRY)
        .is_some_and(|f| f.path.is_some());
    if !stored {
        return None;
    }
    program.forms().iter().enumerate().find_map(|(i, f)| {
        if program.owner_of(i) != Some(ResolvedProgram::ENTRY) {
            return None;
        }
        let items = f.as_list()?;
        let sig = items.get(1)?.as_list()?;
        let named_main = matches!(
            items.first().and_then(tatara_lisp::Spanned::as_symbol),
            Some("define" | "define-typed")
        ) && sig.len() == 1
            && sig[0].as_symbol() == Some(MAIN);
        named_main.then_some((i, sig[0].span))
    })
}

/// The entry's `main`: its top-level form, where it is named, and the key
/// a call to it is written with.
fn main_call(prepared: &Prepared) -> Option<(usize, tatara_lisp::Span, String)> {
    let (top_level, span) = entry_main(&prepared.program)?;
    let ns = namespace_of(&prepared.program, top_level);
    Some((top_level, span, blue_lang_check::names::key(&ns, MAIN)))
}

fn main_key(prepared: &Prepared) -> Option<String> {
    main_call(prepared).map(|(_, _, key)| key)
}

pub(crate) fn call_main<H: 'static>(
    interp: &mut tatara_lisp_eval::Interpreter<H>,
    prepared: &Prepared,
    host: &mut H,
) -> Result<Option<Value>, RunError> {
    let Some((top_level, span, key)) = main_call(prepared) else {
        return Ok(None);
    };
    let call = tatara_lisp::Spanned::new(
        span,
        tatara_lisp::SpannedForm::List(vec![tatara_lisp::Spanned::new(
            span,
            tatara_lisp::SpannedForm::Atom(tatara_lisp::Atom::Symbol(key)),
        )]),
    );
    interp.eval_top_form(&call, host).map(Some).map_err(|e| {
        RunError::Eval(Box::new(crate::observe::Fault::of(
            &prepared.program,
            &prepared.erased,
            top_level,
            &crate::memory::named(e),
            &interp.take_trace(),
        )))
    })
}

/// **A runtime error names a place.** The gates for the last stage that
/// reported a bare message.
///
/// Each fixture is sized so that resolving the failing span against ANY file
/// but the right one lands somewhere else — a different path and a different
/// line — so a green run here is evidence about the join and not about the
/// renderer being called at all.
///
/// **Each raise is an unbound name, WAIVED.** Since the check stage resolves
/// names (B0001), an unbound call no longer reaches the evaluator; these
/// fixtures need exactly that runtime raise, so each carries
/// `# waive B0001: …` above the definition holding it — the one escape hatch,
/// used for what it is for. The waiver adds a line above each failing call,
/// which is why the positions below are one line later than their red runs
/// (recorded against the unwaived fixtures) show.
#[cfg(test)]
mod position_tests {
    use super::*;
    use crate::uses::{Entry, Loader};
    use std::collections::BTreeMap;
    use std::path::Path;

    struct MemLoader(BTreeMap<&'static str, &'static str>);

    impl Loader for MemLoader {
        fn load(&self, name: &str) -> Result<Vec<(String, String)>, String> {
            self.0
                .get(name)
                .map(|s| vec![(format!("{name}.b"), (*s).to_owned())])
                .ok_or_else(|| format!("no bidama named \"{name}\""))
        }
    }

    /// A package whose OWN top-level code raises, deep inside a file that is
    /// deliberately taller than either of the other two.
    ///
    /// Byte 66 — where `kore_wa_sonzai_shinai` starts — is past the end of the
    /// entry file (30 bytes) and past the end of `kotae.b` (21 bytes). So the
    /// only file this span can honestly resolve against is this one, and the
    /// other two now refuse to answer rather than walking off their ends.
    const BAKUHATSU: &str = "\
def tsukawanai_a()
  1
end

def tsukawanai_b()
  2
end

# waive B0001: the fixture needs a raise at runtime
def bakuhatsu()
  kore_wa_sonzai_shinai()
end

bakuhatsu";

    const KOTAE: &str = "def kotae()\n  42\nend";

    /// The same failing call, but only ever reached by a CALLER in another
    /// file — the shape the call stack resolved (the last position test).
    const BAKUHATSU2: &str =
        "# waive B0001: a raise at runtime\ndef yobu()\n  kore_wa_sonzai_shinai()\nend";

    fn loader() -> MemLoader {
        MemLoader(BTreeMap::from([
            ("kotae", KOTAE),
            ("bakuhatsu", BAKUHATSU),
            ("bakuhatsu2", BAKUHATSU2),
        ]))
    }

    fn run_named(path: &str, src: &str) -> RunError {
        run_in_surface(
            Entry {
                path: Some(Path::new(path)),
                text: src,
            },
            Inputs::new(),
            &loader(),
            None,
        )
        .expect_err("the fixture must raise")
    }

    /// **The load-bearing gate: a raise inside an IMPORTED package reports the
    /// IMPORTED file's path and line.**
    ///
    /// Hand-computed. In `bakuhatsu.b` the failing call sits on line 11 at
    /// column 3, and the whole point of the fixture's height is that no other
    /// file in the program can produce that pair: the entry file has 2 lines
    /// and `kotae.b` has 3, so *any* mis-attribution is visible as a different
    /// path AND a different position, never as a coincidence.
    ///
    /// **Three red runs, one per edit this change makes** — each isolates a
    /// different half of the mechanism, which is what stops the gate being a
    /// tautology over "some renderer ran".
    ///
    /// 1. `eval_program` + `.map_err(|e| RunError::Eval(e.to_string()))`
    ///    restored (the pre-change code):
    ///    ```text
    ///    left:  "runtime error: unbound symbol: kore_wa_sonzai_shinai at 74..95"
    ///    right: "runtime error: bakuhatsu.b:10:3: unbound symbol `kore_wa_sonzai_shinai`"
    ///    ```
    ///    No place at all — the state this change is fixing — and the trailing
    ///    `at 74..95` is upstream's `Display`, an offset with no file, which is
    ///    why the loop renders `short_message` instead.
    ///
    /// 2. The loop kept, but `0` passed to `locate` in place of `top_level`:
    ///    ```text
    ///    left:  "runtime error: kotae.b: unbound symbol `kore_wa_sonzai_shinai`"
    ///    right: "runtime error: bakuhatsu.b:10:3: unbound symbol `kore_wa_sonzai_shinai`"
    ///    ```
    ///    **This is the one that proves the INDEX is load-bearing** rather than
    ///    the renderer: form 0 belongs to `kotae.b`, so the wrong file is named
    ///    — and named without a position, because the guard in `locate` sees
    ///    that byte 74 is not a range in a 21-byte file and declines to invent
    ///    one. A fixture with one imported package could not tell these apart.
    ///
    /// 3. `crate::lower_to_spanned(&crate::to_sexps(&erased))` reinstated
    ///    between erasure and the loop:
    ///    ```text
    ///    left:  "runtime error: bakuhatsu.b: unbound symbol `kore_wa_sonzai_shinai`"
    ///    right: "runtime error: bakuhatsu.b:10:3: unbound symbol `kore_wa_sonzai_shinai`"
    ///    ```
    ///    The right FILE with no position — which is exactly the shape of the
    ///    bug: the index survived the lift and every span did not.
    /// kotae loads first so bakuhatsu's forms do not start at index 0: the
    /// order is the fixture, and the waiver says so (B0015 wants them sorted).
    const TWO_IMPORTS: &str =
        "use(\"kotae\")\n# waive B0015: kotae loads first on purpose\nuse(\"bakuhatsu\")\n";

    #[test]
    fn a_raise_inside_an_imported_package_names_that_package() {
        let err = run_named("entry.b", TWO_IMPORTS);
        assert_eq!(
            err.to_string(),
            "runtime error: bakuhatsu.b:11:3: unbound symbol `kore_wa_sonzai_shinai`\n  \
             at bakuhatsu::bakuhatsu (bakuhatsu.b:11:3)\n  \
             at <top level> (bakuhatsu.b:14:1)"
        );
    }

    /// Anti-vacuity for the fixture itself: the position asserted above is a
    /// FACT ABOUT `bakuhatsu.b`, checked against the source text rather than
    /// against the thing that produced it.
    ///
    /// Without this, `11:3` is just a number that happened to come out of the
    /// code under test, and a change that moved every reported line by one
    /// would move this assertion with it.
    #[test]
    fn line_11_column_3_of_the_fixture_is_the_failing_call() {
        let line = BAKUHATSU.lines().nth(10).expect("line 11 exists");
        assert_eq!(line, "  kore_wa_sonzai_shinai()");
        assert_eq!(
            &line[2..],
            "kore_wa_sonzai_shinai()",
            "column 3 (1-indexed) is where the call starts"
        );
        // And the other two files cannot reach that far, which is what makes a
        // mis-attribution loud instead of plausible.
        let offset = BAKUHATSU.find("kore_wa_sonzai_shinai").expect("in fixture");
        assert!(
            offset > KOTAE.len(),
            "kotae.b could answer for byte {offset}"
        );
        assert!(
            offset > TWO_IMPORTS.len(),
            "the entry file could answer for byte {offset}"
        );
    }

    /// **The `FileId(0)` path: a raise in the ENTRY file reports the entry
    /// file.** The single-file case, which is every program that imports
    /// nothing — and the one where the index and the span cannot disagree.
    ///
    /// **Red run** (2026-08-12), `eval_program` +
    /// `.map_err(|e| RunError::Eval(e.to_string()))` restored:
    /// ```text
    /// left:  "runtime error: unbound symbol: nani_mo_nai at 17..28"
    /// right: "runtime error: honmono.b:5:1: unbound symbol `nani_mo_nai`"
    /// ```
    ///
    /// **Second red run**, `lower_to_spanned` reinstated after erasure — the
    /// one that isolates the SPAN half from the index half, since a
    /// single-file program cannot get its file wrong:
    /// ```text
    /// left:  "runtime error: honmono.b: unbound symbol `nani_mo_nai`"
    /// right: "runtime error: honmono.b:5:1: unbound symbol `nani_mo_nai`"
    /// ```
    #[test]
    fn a_raise_in_the_entry_file_names_the_entry_file() {
        let err = run_named(
            "honmono.b",
            "def f()\n  1\nend\n\n# waive B0001: a raise at runtime\nnani_mo_nai()\n",
        );
        assert_eq!(
            err.to_string(),
            "runtime error: honmono.b:6:1: unbound symbol `nani_mo_nai`"
        );
    }

    /// A raise from a form that came through the SURFACE-level erasure still
    /// reports a real position — the annotated path, where erasure rewrites
    /// the node rather than passing it through.
    ///
    /// Separate from the two above because the erasure rewrite is the only
    /// place a node is built rather than kept, and a synthetic span there
    /// would be invisible to a fixture whose failing form is untouched.
    ///
    /// **Red run** (2026-08-12), `lower_to_spanned` reinstated after erasure:
    /// ```text
    /// left:  "runtime error: chuu.b: unbound symbol `mada_nai`"
    /// right: "runtime error: chuu.b:2:3: unbound symbol `mada_nai`"
    /// ```
    #[test]
    fn a_raise_inside_an_annotated_def_still_names_its_line() {
        let err = run_named(
            "chuu.b",
            "# waive B0001: a raise at runtime\ndef f(a: Int) -> Int\n  mada_nai(a)\nend\n\nf(1)\n",
        );
        assert_eq!(
            err.to_string(),
            "runtime error: chuu.b:3:3: unbound symbol `mada_nai`\n  \
             at f (chuu.b:3:3)\n  \
             at <top level> (chuu.b:6:1)"
        );
    }

    /// **The limit this module used to state, closed by the call stack.**
    ///
    /// A top-level form in the entry file calls a function defined in an
    /// imported one, and the raise happens inside the callee. The executing
    /// form is the entry's and the span is the callee's bytes, so until the
    /// evaluator reported the frames an error unwound through, the best blue
    /// could do was name the caller's file with no position (the guard in
    /// `uses::ResolvedProgram::locate` refusing an offset it could not
    /// justify). The innermost frame's definition now names the file the
    /// offsets belong to, and the stack shows the call that led there.
    ///
    /// **Red run** (2026-10-10): `Fault::of` locating against the executing
    /// top-level form instead of the innermost frame's definition:
    /// ```text
    /// left:  "runtime error: yobidashi.b: unbound symbol `kore_wa_sonzai_shinai`\n  at bakuhatsu2::yobu (bakuhatsu2.b:3:3)\n  at <top level> (yobidashi.b:3:1)"
    /// ```
    /// The old answer, kept by the guard: the caller's file and no position.
    #[test]
    fn a_raise_in_a_callee_from_another_file_names_the_callees_file() {
        // The comment is padding, and load-bearing: `bakuhatsu2.b`'s failing
        // call starts at byte 47 (after its waiver line) and ends at 70, and
        // this file is 57 bytes, so the start is in range here and the end is
        // not — a mis-attribution would still be refused rather than placed.
        let err = run_named(
            "yobidashi.b",
            "use(\"bakuhatsu2\")\n# pad: 47's in range\nbakuhatsu2::yobu\n",
        );
        assert_eq!(
            err.to_string(),
            "runtime error: bakuhatsu2.b:3:3: unbound symbol `kore_wa_sonzai_shinai`\n  \
             at bakuhatsu2::yobu (bakuhatsu2.b:3:3)\n  \
             at <top level> (yobidashi.b:3:1)"
        );
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn int(src: &str) -> i64 {
        match run(src).unwrap_or_else(|e| panic!("{src:?}: {e}")).value {
            Value::Int(v) => v,
            other => panic!("{src:?} produced {other:?}"),
        }
    }

    /// **The sliding scale, as one assertion.** Annotating changes the
    /// analysis and nothing else.
    #[test]
    fn annotating_buys_analysis_and_changes_nothing_else() {
        let plain = run("def add(a, b)\n  a + b\nend\nadd(2, 3)").expect("plain");
        let typed = run("def add(a: Int, b: Int) -> Int\n  a + b\nend\nadd(2, 3)").expect("typed");

        assert!(matches!(plain.value, Value::Int(5)));
        assert!(
            matches!(typed.value, Value::Int(5)),
            "the annotated program must compute the same answer"
        );
        assert_eq!(plain.visited, 0, "no annotations means no analysis");
        assert!(
            typed.visited > 0,
            "an annotation must actually buy analysis, not just decorate"
        );
        assert_eq!(plain.typed_decls, 0);
        assert_eq!(typed.typed_decls, 1);
    }

    /// **Checking happens before erasure.** This is the test that catches the
    /// reordering: a program with a declared-type violation must be rejected,
    /// and it can only be rejected while the annotations still exist.
    #[test]
    fn a_type_error_is_reported_and_the_program_does_not_run() {
        let err = run("def add(a: Int, b: Int) -> Str\n  a + b\nend\nadd(1, 2)")
            .expect_err("a declared Str return from an Int body must be rejected");
        assert!(
            matches!(err, RunError::Types(ref d) if !d.is_empty()),
            "expected type diagnostics, got {err}"
        );
    }

    /// And the untyped version of the same program runs, so the rejection
    /// above is the annotation's doing rather than a parse failure.
    #[test]
    fn the_same_program_without_annotations_runs() {
        assert_eq!(int("def add(a, b)\n  a + b\nend\nadd(1, 2)"), 3);
    }

    #[test]
    fn a_parse_error_is_reported_as_one() {
        assert!(matches!(run("def (").unwrap_err(), RunError::Parse(_)));
    }

    /// Every stage reports in its own vocabulary, so a failure names which
    /// stage failed rather than surfacing as a generic error.
    #[test]
    fn a_runtime_error_is_reported_as_one() {
        let err = run("throw(error(\"boom\"))").expect_err("a raise");
        assert!(matches!(err, RunError::Eval(_)), "got {err}");
    }

    /// Stdlib and primitives are both reachable through the pipeline — the
    /// gap that made `6 % 3` fail.
    #[test]
    fn the_pipeline_reaches_both_runtime_layers() {
        assert_eq!(int("6 % 3"), 0);
        assert_eq!(int("7 % 3"), 1);
        assert_eq!(int("2 + 3 * 4"), 14);
    }

    /// **The deleted hop was a no-op on everything blue emits — so removing it
    /// is a swap, not a behaviour change.**
    ///
    /// The old lowering printed the erased tree and read it back through
    /// `tatara_lisp::read_spanned`. This walks a corpus and asserts the two
    /// paths land on the same tree, which is the equivalence the swap rests on.
    /// It is stated as a *measurement over this corpus*, not as a theorem:
    /// the round trip is not identity in general (that is precisely why it had
    /// to go), it merely happened to be identity for the bytes blue emits.
    #[test]
    fn the_deleted_round_trip_agreed_with_the_direct_lowering() {
        let corpus = [
            "def add(a, b)\n  a + b\nend\nadd(2, 3)",
            "def fact(n)\n  if n < 2\n    1\n  else\n    n * fact(n - 1)\n  end\nend\nfact(5)",
            "def f(a, b)\n  c = a + b\n  c * 2\nend\nf(1, 2)",
            "defmacro sq(e)\n  quote\n    unquote(e) * unquote(e)\n  end\nend\nsq(2 + 3)",
            "\"a string with spaces, a ( and a )\"",
            "def g(a: Int) -> Int\n  a + 1\nend\ng(1)",
            "6 % 3",
            "1.5 + 2.25",
        ];
        for src in corpus {
            // Projected to `Sexp` because that is what the deleted hop
            // operated on. Erasure itself no longer goes near it.
            let erased = crate::to_sexps(&erase_types(&parse_tree(src).expect("parse")));

            let direct: Vec<Sexp> = crate::lower_to_spanned(&erased)
                .iter()
                .map(tatara_lisp::Spanned::to_sexp)
                .collect();
            assert_eq!(direct, erased, "the direct lowering must be the identity");

            let text = erased
                .iter()
                .map(ToString::to_string)
                .collect::<Vec<_>>()
                .join("\n");
            let round_tripped: Vec<Sexp> = tatara_lisp::read_spanned(&text)
                .unwrap_or_else(|e| panic!("{src:?}: the old path could not read back: {e:?}"))
                .iter()
                .map(tatara_lisp::Spanned::to_sexp)
                .collect();
            assert_eq!(
                round_tripped, erased,
                "{src:?}: the old print-and-reparse path changed the tree"
            );
        }
    }

    /// Anti-vacuity for the test above: the round trip really is *not* the
    /// identity in general, so agreeing on the corpus was a property of what
    /// blue happens to emit rather than a property of the reader.
    ///
    /// **`Atom::Symbol`'s `Display` writes the name raw, with no escaping.**
    /// `Atom::Str` escapes and its docs explain at length why; the symbol arm
    /// is `f.write_str(s)`. So print-then-read is not inverse over the symbol
    /// domain, and the failure is *silent*: a symbol containing a space prints
    /// as two tokens, reads back as two symbols, and the result is a perfectly
    /// well-formed tree with a different meaning. No error, nothing to catch.
    ///
    /// Measured 2026-08-02 across the separators: `a b` and `x'y` come back
    /// `Ok` with a different tree; `x)y`, `x"y` and `x;y` come back `Err`;
    /// `x{y` and `x[y` DO round-trip at this level — those two are one symbol
    /// in and one symbol out, so the brace-fusion reported in tatara *source*
    /// is not what bites a printed tree. The silent pair is what makes this a
    /// miscompile class rather than a noisy one.
    #[test]
    fn the_round_trip_is_not_the_identity_in_general() {
        let tree = Sexp::List(vec![
            Sexp::Atom(tatara_lisp::Atom::Symbol("f".into())),
            Sexp::Atom(tatara_lisp::Atom::Symbol("a b".into())),
        ]);
        let text = tree.to_string();
        let back: Vec<Sexp> = tatara_lisp::read_spanned(&text)
            .expect("it reads back cleanly — that IS the problem")
            .iter()
            .map(tatara_lisp::Spanned::to_sexp)
            .collect();
        assert_ne!(
            back,
            vec![tree.clone()],
            "if print-then-read became inverse over symbols, the class would be \
             closed upstream and this test should be deleted rather than relaxed"
        );
        // …and the direct lowering is unaffected by any of it.
        let direct: Vec<Sexp> = crate::lower_to_spanned(std::slice::from_ref(&tree))
            .iter()
            .map(tatara_lisp::Spanned::to_sexp)
            .collect();
        assert_eq!(direct, vec![tree]);
    }
}

#[cfg(test)]
mod macro_tests {
    use super::*;

    fn int(src: &str) -> i64 {
        match run(src).unwrap_or_else(|e| panic!("{src:?}: {e}")).value {
            Value::Int(v) => v,
            other => panic!("{src:?} produced {other:?}"),
        }
    }

    /// **A blue macro expands and runs.** Tenet 2's surface, end to end.
    #[test]
    fn a_macro_expands_and_runs() {
        assert_eq!(
            int("defmacro double(x)\n  quote\n    unquote(x) + unquote(x)\n  end\nend\ndouble(21)"),
            42
        );
    }

    /// A macro receives *source forms*, not values — so it can duplicate its
    /// argument, which a function cannot do without re-evaluating it.
    #[test]
    fn a_macro_operates_on_syntax_not_values() {
        assert_eq!(
            int("defmacro sq(e)\n  quote\n    unquote(e) * unquote(e)\n  end\nend\nsq(2 + 3)"),
            25,
            "the argument form `2 + 3` must be substituted twice"
        );
    }

    /// **A runaway macro is a typed error, not a dead compiler.** This is the
    /// property that makes the metaprogramming surface safe to hand to a user.
    ///
    /// The assertion was `contains("expansion limit")` and now reads
    /// `contains("expansion")`, because the pipeline renders `short_message`
    /// rather than `Display`: upstream words the same fact as "exceeded 256
    /// expansion steps" instead of "exceeded the expansion limit of 256
    /// rewrites". The PROPERTY is unchanged and still asserted — the macro is
    /// named, and the failure is attributed to expansion rather than to
    /// evaluation. **This reword was the whole measured blast radius of that
    /// switch**, one test in the workspace.
    ///
    /// The number is deliberately NOT pinned. It is upstream's constant, this
    /// test owns none of it, and matching it would turn an upstream bump into
    /// a red run here that proves nothing about blue.
    ///
    /// The third clause is new capability rather than repair: the message now
    /// carries `<anonymous>:6:1`, so a runaway macro says WHERE it ran away.
    #[test]
    fn a_runaway_macro_fails_the_compilation_rather_than_the_process() {
        let err =
            run("defmacro forever(x)\n  quote\n    forever(unquote(x))\n  end\nend\nforever(1)")
                .expect_err("a self-referential macro must be rejected");
        let msg = err.to_string();
        assert!(
            msg.contains("forever") && msg.contains("expansion"),
            "the error must name the macro and the limit it hit: {msg}"
        );
        assert!(
            msg.contains("<anonymous>:6:1"),
            "and must place the call that ran away — line 6 is `forever(1)`: {msg}"
        );
    }
}

#[cfg(test)]
mod input_tests {
    use super::*;
    use crate::inputs::{Declaration, Inputs};

    /// A schema a macro will generate code from.
    const SCHEMA: &[u8] = b"3";

    fn with_schema(src: &str) -> Result<Run, RunError> {
        let hash = Inputs::hash_of(SCHEMA);
        let mut inputs = Inputs::new();
        inputs
            .bind(
                &Declaration {
                    name: "schema".to_string(),
                    hash,
                },
                SCHEMA.to_vec(),
            )
            .expect("bind");
        run_with_inputs(src, inputs)
    }

    fn decl_line() -> String {
        let mut s = String::from("definput(\"schema\", \"");
        s.push_str(&Inputs::hash_of(SCHEMA));
        s.push_str("\")\n");
        s
    }

    /// **A macro reads a declared build input.** This is §VI OPEN #6 closed —
    /// the spec names it as gating blue's whole "stronger than Ruby's
    /// metaprogramming" claim, because a macro that cannot read a schema cannot
    /// generate code from one.
    #[test]
    fn a_macro_can_read_a_declared_build_input() {
        let src = decl_line() + "input(\"schema\")";
        let out = with_schema(&src).expect("run");
        assert!(
            matches!(out.value, Value::Str(ref s) if &**s == "3"),
            "got {:?}",
            out.value
        );
    }

    /// **An undeclared input is an error, not a file read and not nil.**
    /// Returning nil is how a macro generates an empty table and nobody notices
    /// until runtime.
    #[test]
    fn an_undeclared_input_is_an_error() {
        let err = with_schema("input(\"not_declared\")").expect_err("must fail");
        let msg = err.to_string();
        assert!(msg.contains("not_declared"), "must name it: {msg}");
        assert!(msg.contains("definput"), "and say how to declare it: {msg}");
    }

    /// **There is no path-based read at all.** The capability is the absence of
    /// the primitive, not a check inside one — so this is an unbound symbol.
    ///
    /// Holds for the DEFAULT surface — the one every embedder gets. The `sys`
    /// cargo feature (CLI only) is the one declared exception: it is the
    /// operator's own trusted host surface, and is asserted in
    /// `sys_read_file_is_the_trusted_cli_only_exception` below.
    #[cfg(not(feature = "sys"))]
    #[test]
    fn there_is_no_ambient_file_read() {
        for attempt in [
            "read_file(\"/etc/passwd\")",
            "File(\"/etc/passwd\")",
            "slurp(\"/etc/passwd\")",
            "open(\"/etc/passwd\")",
        ] {
            let err = with_schema(attempt).expect_err("must not resolve");
            assert!(
                err.to_string().contains("unbound"),
                "{attempt} must be UNBOUND — a capability removed by absence, \
                 not guarded by a check: {err}"
            );
        }
    }

    /// With the `sys` feature compiled in, `read_file` IS bound — that is the
    /// point of the feature. The doctrine does not move: this is the operator's
    /// own machine (the CLI), not an embedder's sandbox. Pin the boundary so a
    /// future default-build change is heard, and assert that `input()` still
    /// works beside it.
    #[cfg(feature = "sys")]
    #[test]
    fn sys_read_file_is_the_trusted_cli_only_exception() {
        let err = with_schema("definitely_not_a_primitive(\"x\")").expect_err("must not resolve");
        assert!(err.to_string().contains("unbound"), "{err}");
        assert!(
            with_schema("read_file(\"/etc/passwd\")").is_ok(),
            "with `sys` on, read_file is the trusted CLI surface"
        );
        let out = with_schema("input(\"schema\")").expect("run");
        assert!(
            matches!(out.value, Value::Str(ref s) if &**s == "3"),
            "input() still binds beside the sys surface: {:?}",
            out.value
        );
    }

    /// Anti-vacuity: with no inputs supplied at all, even a declared name fails
    /// — so the success above is the binding's doing.
    #[test]
    fn a_declared_input_with_no_bytes_supplied_fails() {
        let src = decl_line() + "input(\"schema\")";
        assert!(run(&src).is_err(), "no bytes were supplied");
    }
}

#[cfg(test)]
mod tier2_tests {
    use super::*;
    use crate::inputs::{Declaration, Inputs};

    /// **The Tier-2 conversion §V.6.3 said was gated: a macro that emits real
    /// declarations FROM A SCHEMA.**
    ///
    /// `theory/BLUE.md` §VI OPEN #6 states the blocker plainly — "tenet 2
    /// installs a `NoLoader`, so a macro cannot read a schema — which gates
    /// every Tier-2 conversion in §V.6 and therefore blue's whole 'stronger than
    /// Ruby's metaprogramming' claim."
    ///
    /// Here the schema supplies a *value the generated code depends on*, read at
    /// expansion time. Ruby and Elixir can both do this — with the whole
    /// filesystem open. blue does it through a name bound to a content hash.
    #[test]
    fn a_macro_generates_code_from_a_schema() {
        let schema = b"7";
        let mut inputs = Inputs::new();
        inputs
            .bind(
                &Declaration {
                    name: "arity".to_string(),
                    hash: Inputs::hash_of(schema),
                },
                schema.to_vec(),
            )
            .expect("bind");

        // The macro reads the input at EXPANSION time and splices the value it
        // found into the code it emits.
        let mut src = String::from("definput(\"arity\", \"");
        src.push_str(&Inputs::hash_of(schema));
        src.push_str("\")\n");
        src.push_str(
            "defmacro from_schema()\n  quote\n    unquote(to_int(input(\"arity\")))\n  end\nend\n\
             from_schema() * 6",
        );

        let out = run_with_inputs(&src, inputs).expect("run");
        assert!(
            matches!(out.value, Value::Int(42)),
            "the schema's 7 must reach the generated code: got {:?}",
            out.value
        );
    }
}