earthsci-ast 0.6.0

//! inline_tests — the §6.6.5-capable inline-test runner over the
//! vectorized array simulation pathway (the Rust mirror of the Julia
//! binding's `inline_tests.jl` and the Python `inline_tests.py`).
//!
//! NOTE: this is PRODUCT code, not Rust test code — the runner for tests
//! embedded in ESM model files. The filename mirrors the sibling bindings'
//! modules (cross-binding naming parity), which is why a "tests"-named file
//! lives in `src/` and is exported from the crate root.
//!
//! A PDE model's inline tests (esm-spec §6.6.5) assert REDUCTIONS of a
//! spatial field — `reduce: L2_error | Linf_error` against a `reference`,
//! or the pure collapsers `integral | mean | max | min` — or point-sample it
//! via `coords`. This module drives the official
//! [`crate::problem::esm_problem`] / [`crate::problem::solve`] pipeline (the
//! `simulate_array` runtime) and collapses fields per assertion.
//!
//! Cross-binding pinned conventions (identical in the Julia / Python / Rust
//! bindings; the esm-spec leaves these open, so determinism requires
//! pinning):
//!
//! 1. `coords` point-sampling — coords values are positions in INDEX space
//!    (1-based, fractional allowed) along the named interval index sets;
//!    sampling picks the NEAREST grid index, with exact half-way ties
//!    rounding DOWN toward the lower index (`idx = ceil(c - 1/2)`). Keys
//!    must name the asserted field's index sets; a strict subset pins only
//!    when every remaining dimension has exactly one sample; the resolved
//!    index must lie in `1..=size`. Mutually exclusive with `reduce`.
//! 2. `integral` reduce — the uniform-cell Riemann sum under a UNIT total
//!    domain measure per axis: `integral = Σ field / N_cells = mean(field)`.
//!    Authors of non-unit physical domains must scale the expectation until
//!    the spec grows a measure concept. This is exactly the measure
//!    convention under which the relative-L2 reduction is measure-free (the
//!    per-cell measure cancels between numerator and denominator).
//! 3. `from_file` references — `{type: "from_file", path, format?}`: `path`
//!    resolves relative to the .esm file's directory (the
//!    [`run_inline_tests_with_base_dir`] `base_dir`; [`run_inline_tests`] resolves
//!    against the working directory); the default and only v1 `format` is
//!    "json" — a row-major nested JSON array exactly matching the field's
//!    shape (validated; mismatch is a clear error). The loaded array is used
//!    exactly like an evaluated inline reference in the error-norm
//!    reductions.
//!
//! Public surface (1:1 with the Julia / Python references):
//!
//! - [`evaluate_cellwise`] — official per-cell evaluation of an array-valued
//!   build-time expression (grid geometry / §6.6.5 analytic references)
//!   through the same array evaluator the simulator uses for
//!   coordinate-expression `ic` seeding.
//! - [`field_reduce`] — the §6.6.5 reduction semantics (relative L2,
//!   absolute Linf, mean/max/min).
//! - [`state_cells`] — (cell-index-tuple, state-row) pairs of one array
//!   state, sorted by cell tuple.
//! - [`run_inline_tests`] — run every inline test of the selected
//!   component(s) of one loaded document; returns per-assertion results
//!   carrying the ACTUAL reduction values (conformance runners record these).
//! - [`run_inline_tests_paths`] + [`InlineTestOptions`] — the corpus entry:
//!   many documents by path, with a per-document options callback so that
//!   site-specific policy (a stiff-solver map, an initial-condition seed)
//!   stays with the caller.
//!
//! `models` and `reaction_systems` alike are run: the schema gives both the
//! same `tests` member (esm-spec §6.6).
//!
//! This entry was called `run_inline_tests` until it grew the ability to run a
//! whole corpus. The name was always too narrow — the §6.6.5 spatial
//! reductions are one assertion FORM, and the same runner has always executed
//! the plain pointwise assertions of an ODE document through the same body —
//! so it is now `run_inline_tests`, with no deprecated alias (the old spelling
//! is exactly the misunderstanding the rename exists to remove).

use std::borrow::Cow;
use std::cell::OnceCell;
use std::collections::{HashMap, HashSet};
use std::path::{Path, PathBuf};

use serde::Serialize;

use crate::problem::{EsmProblem, ProblemOptions, esm_problem, solve};
use crate::simulate::{Solution, SolveOptions};

/// The build-time data providers one inline-test BUILD consumes, produced on
/// demand.
///
/// A factory rather than a set because [`crate::problem::ProblemOptions`] takes
/// its `build_providers` BY VALUE: one shared vector would be moved out by the
/// first build and missing from the second. Called once per BUILD, so a
/// document whose tests share a [`BuildKey`] reads its `data_sources` once
/// rather than once per test. `Err` carries a message naming what could not be
/// constructed; it is recorded as an assertion ERROR, never ignored.
///
/// See [`run_inline_tests_with_providers`].
#[cfg(not(target_arch = "wasm32"))]
pub type BuildProviderFactory<'a> =
    dyn Fn() -> Result<Vec<(String, Box<dyn crate::prepare::PrepareProvider>)>, String> + 'a;

/// The wasm32 build has no build pipeline (`crate::prepare` is native-only), so
/// there is no provider contract to satisfy: a factory passed here is refused,
/// and every assertion of a test that needs one is recorded as an ERROR.
#[cfg(target_arch = "wasm32")]
pub type BuildProviderFactory<'a> = dyn Fn() -> Result<(), String> + 'a;

/// Qualify a test's override keys with the component that OWNS the test.
///
/// esm-spec §6.6.2 keys `parameter_overrides` / `initial_conditions` by LOCAL
/// name — local to the ENCLOSING component, since a test "exercises one model in
/// isolation" (§6.6). The runner hands them to `esm_problem`, which resolves against
/// the WHOLE flattened document, where that locality is gone: two mounted
/// components that each declare a `T` flatten to `M1.T` / `M2.T`, and the bare
/// `T` in `M2`'s test is then AMBIGUOUS document-wide even though it is
/// unambiguous where it was written.
///
/// So re-attach the scope the runner still knows: a key whose `<model>.<key>`
/// form names a real variable of the flattened system is rewritten to it. A key
/// that does not (already qualified, a scoped reference the prefix would double
/// up, or simply wrong) passes through untouched, so the build reports on it
/// exactly as it would have.
///
/// This is what makes the runner's answer differ from handing the authored map
/// to the build raw and letting bare-name resolution find it. The scoped
/// spelling is fully qualified, which is an EXACT hit under the forward,
/// longest-dotted-suffix resolution of esm-spec §6.6.2 rule 2 — so the two
/// rules agree here rather than compete, and the scoped one additionally
/// survives a document where a sibling component declares the same bare name.
/// A seed supplied by an [`InlineTestOptions`] is merged onto the authored map
/// before this runs, so it is keyed and scoped by the same rule.
fn scope_to_component(
    overrides: Option<&HashMap<String, InlineValue>>,
    model_name: &str,
    file: &EsmFile,
) -> HashMap<String, InlineValue> {
    let Some(overrides) = overrides.filter(|m| !m.is_empty()) else {
        return HashMap::new();
    };
    let Ok(flat) = crate::flatten::flatten(file) else {
        return overrides.clone(); // let the build report the real failure
    };
    overrides
        .iter()
        .map(|(k, v)| {
            let qualified = format!("{model_name}.{k}");
            let known = flat.parameters.contains_key(&qualified)
                || flat.state_variables.contains_key(&qualified);
            if known {
                return (qualified, v.clone());
            }
            // An `operator_compose` renaming match may have DELETED the very
            // name this component's test keys on (esm-libraries-spec §4.7.1
            // step 4): `Sink.O3` folded onto `Chem.ozone` leaves the scoped
            // spelling naming nothing, and the key then falls through as a bare
            // local that resolves to nothing document-wide -- dropped in
            // SILENCE, so the state runs from the survivor's declared default
            // and the test still returns a verdict (CONFORMANCE_SPEC §5.35).
            match flat.metadata.merged_variable_renames.get(&qualified) {
                Some(survivor) => (survivor.clone(), v.clone()),
                None => (k.clone(), v.clone()),
            }
        })
        .collect()
}

/// The caller-supplied override SEEDS of one document, laid beneath every
/// test's own maps.
///
/// Empty for the four `&EsmFile` entry points, which take no seeds; filled
/// from an [`InlineTestOptions`] by [`run_inline_tests_paths`].
#[derive(Clone, Debug, Default)]
struct InlineTestSeeds {
    parameter_overrides: HashMap<String, InlineValue>,
    initial_conditions: HashMap<String, InlineValue>,
    /// WHICH compiler builds each test's right-hand side (API_SPEC §5.8).
    /// Loop-invariant context like the seeds beside it: it comes from one
    /// [`InlineTestOptions`] for the whole document, so it does not enter the
    /// build memo's [`BuildKey`].
    compiler: Option<crate::problem::Compiler>,
}

impl InlineTestSeeds {
    /// Lay `seed` under a test's `authored` map: the document is authoritative
    /// about its own test, so an authored key wins and the seed only supplies
    /// what the document left unsaid.
    ///
    /// The merge happens BEFORE [`scope_to_component`], so a seed key and an
    /// authored key naming the same variable collide on the one spelling.
    /// Merging afterwards would instead hand the build both `T` and `M.T` —
    /// two keys designating one parameter, with two values.
    fn lay_under(
        &self,
        seed: &HashMap<String, InlineValue>,
        authored: Option<&HashMap<String, InlineValue>>,
    ) -> Option<HashMap<String, InlineValue>> {
        if seed.is_empty() {
            return authored.cloned();
        }
        let mut out = seed.clone();
        if let Some(authored) = authored {
            for (k, v) in authored {
                out.insert(k.clone(), v.clone());
            }
        }
        Some(out)
    }
}

use crate::simulate_array::{BuildInspection, Value, eval_buildtime_field};
use crate::types::{
    AssertionReference, EsmFile, Expr, FromFileReference, IndexSet, InlineValue, Model, Tolerance,
};

/// esm-spec §6.6.4: the default relative tolerance when neither the
/// assertion, its test, nor the model declares one (same constant as the
/// Julia run_tests reference).
pub const DEFAULT_REL_TOL: f64 = 1e-6;

/// Outcome of one §6.6.5 inline-test assertion evaluated through the
/// simulation pathway. `actual` is the computed reduction value (`None` when
/// the simulation or reduction itself failed); `message` carries the diff or
/// error text for non-passing results. Field-for-field identical to the
/// Julia `AssertionResult` / Python `AssertionResult`, and
/// `Serialize`-able so conformance runners can record it directly.
#[derive(Debug, Clone, Serialize)]
pub struct AssertionResult {
    /// Owning model name.
    pub model: String,
    /// The inline test's `id`.
    pub test_id: String,
    /// 1-based position of the assertion within the test.
    pub assertion_idx: usize,
    /// Asserted variable name.
    pub variable: String,
    /// Assertion time.
    pub time: f64,
    /// The §6.6.5 `reduce` kind (`None` for a scalar point sample).
    pub reduce: Option<String>,
    /// Expected scalar value.
    pub expected: f64,
    /// Computed reduction value (`None` on simulation/reduction failure).
    pub actual: Option<f64>,
    /// Resolved relative tolerance (esm-spec §6.6.4 precedence).
    pub rtol: f64,
    /// Resolved absolute tolerance (esm-spec §6.6.4 precedence).
    pub atol: f64,
    /// Whether the assertion passed.
    pub passed: bool,
    /// Diff or error text for non-passing results (empty when passed).
    pub message: String,
    /// The document this row is about: the path it was loaded from, or `""`
    /// for a document handed to the runner as an already-loaded [`EsmFile`],
    /// which has no path to carry.
    ///
    /// [`run_inline_tests_paths`] walks a directory or a list of documents and
    /// CONCATENATES their rows, so without this a corpus run could report a
    /// failure without saying which document failed — while a LOAD failure
    /// named its path all along (in `model`), making the two halves of one run
    /// inconsistent with each other. The Julia and Python bindings carry the
    /// same field under the same name.
    pub file: String,
}

/// Evaluate an array-valued expression (elementwise ops over array-producing
/// `faq`/`makearray` nodes — e.g. a grid-geometry template expanded by
/// a §9.7 import, or a §6.6.5 analytic `reference`) at each 1-based integer
/// cell of `cells`, returning one `f64` per cell.
///
/// This is the public entry to the same build-time machinery the simulator
/// uses to seed coordinate-expression `ic` fields
/// ([`crate::simulate_array::eval_buildtime_field`]).
///
/// STATE references are not in scope. Model PARAMETERS (load-time constants)
/// ARE: pass their resolved values as `params` (name → value, e.g. a build's
/// [`BuildInspection::params`]) and a parameter-dependent expression resolves
/// (esm-spec §6.6.5). A scalar (const-folded) result broadcasts. Mirrors the
/// Julia `evaluate_cellwise` / Python `evaluate_cellwise` 1:1.
///
/// Always the reference evaluator, whatever compiler built the model: the
/// runner calls this for an assertion's analytic `reference`, which is the
/// test's oracle rather than the model, and so is outside the compiler's
/// refusal. The same kind of expression seeding a model's `ic` is the model's,
/// and is exercised and gated at construction instead
/// ([`crate::problem::esm_problem`]).
pub fn evaluate_cellwise(
    expr: &Expr,
    cells: &[Vec<i64>],
    index_sets: &HashMap<String, IndexSet>,
    params: &HashMap<String, f64>,
) -> Result<Vec<f64>, String> {
    let value = eval_buildtime_field(expr, index_sets, params).map_err(|e| e.to_string())?;
    match value {
        Value::Scalar(s) => Ok(vec![s; cells.len()]),
        Value::Array(arr) => {
            let mut out = Vec::with_capacity(cells.len());
            for cell in cells {
                if cell.len() != arr.ndim() {
                    return Err(format!(
                        "evaluate_cellwise: cell {cell:?} has {} indices but the field has ndim={}",
                        cell.len(),
                        arr.ndim()
                    ));
                }
                let mut idx = Vec::with_capacity(cell.len());
                for (d, &c) in cell.iter().enumerate() {
                    if c < 1 || (c as usize) > arr.shape()[d] {
                        return Err(format!(
                            "evaluate_cellwise: cell {cell:?} is outside the field's shape {:?}",
                            arr.shape()
                        ));
                    }
                    idx.push((c - 1) as usize);
                }
                out.push(arr[ndarray::IxDyn(&idx)]);
            }
            Ok(out)
        }
    }
}

/// Whether `name` occurs FREE in `expr`: as a variable reference not bound by
/// an enclosing `faq` / `makearray` loop symbol (`output_idx`,
/// a `ranges` key) or an `integral`'s integration variable. A node that binds
/// `name` shadows it for its whole subtree.
fn mentions_free(expr: &Expr, name: &str) -> bool {
    match expr {
        Expr::Variable(v) => v == name,
        Expr::Operator(node) => {
            let binds = node
                .output_idx
                .as_ref()
                .is_some_and(|ix| ix.iter().any(|s| s == name))
                || node.ranges.as_ref().is_some_and(|r| r.contains_key(name))
                || node.int_var.as_deref() == Some(name);
            !binds && node.any_child(&mut |c| mentions_free(c, name))
        }
        Expr::Number(_) | Expr::Integer(_) => false,
    }
}

/// The independent (time) variable, as an expression spells it.
const TIME_VARIABLE: &str = "t";

/// The refusal for a §6.6.5 analytic `reference` that mentions `t`.
///
/// esm-spec §6.6.5 says what a reference may read: the asserted field's
/// DIMENSION NAMES, free, plus the model's PARAMETERS. The independent variable
/// is neither. It is not rejected by the evaluator either, because a reference
/// is evaluated by the BUILD-TIME cellwise evaluator, whose time slot is
/// `0.0` — so a reference of `t` used to answer with the expression at the
/// start of the span and report a plausible wrong number, in all three
/// executing bindings at once. Refusing names the mistake instead.
///
/// The text is BYTE-IDENTICAL in Julia (`_REFERENCE_MENTIONS_TIME`) and Python
/// (`REFERENCE_MENTIONS_TIME`); the three bindings must reject the same
/// document with the same sentence.
pub(crate) const REFERENCE_MENTIONS_TIME: &str = "inline `reference` mentions `t`, which esm-spec §6.6.5 does not admit: a reference's free variables are the field's dimension names, and its other names are the model's parameters. A reference is evaluated at build time, where the independent variable has no value, so `t` would silently read 0 rather than the asserted time.";

/// esm-spec §6.6.5: an inline `reference`'s free variables are the domain
/// DIMENSION NAMES. For a field shaped over index sets those are the asserted
/// variable's `shape` entries, each bound at every grid point to the 1-based
/// position along its axis — the same index space `coords` reads
/// (convention 1) — so `index(zc, lev)` reads the cell's coordinate from a
/// geometry array and `sin(pi * (x - 0.5) / N)` is the cell-centre analytic
/// form, with no explicit gather. A reference that mentions a dimension name
/// FREE is turned into the whole field by wrapping it in a `faq` whose
/// output indices ARE the dimension names (in shape order, each ranging over
/// its index set); one that mentions none — a literal, a parameter expression,
/// or a `faq` that already produces the field under its own loop
/// symbols — is returned untouched, so nothing that evaluated before evaluates
/// differently. Mirrors the Julia / Python `bind_dimension_names`.
///
/// "Nothing that evaluated before evaluates differently" holds only because a
/// dimension name the BUILD-TIME SCOPE ALREADY BINDS is rejected here: wrapping
/// would silently shadow that other meaning with the cell's index — the same
/// expression, a different number, no diagnostic. One name meaning two things in
/// one scope is an ill-formed document, so it is a fault. esm-spec §6.6.5 makes
/// the clash scope the WHOLE build-time scope, in two halves:
///
/// * `scope` — the scalar parameter scope (flattened names plus their
///   unambiguous dotted-suffix aliases, [`param_scope_with_aliases`]); and
/// * `arrays` — the build-time ARRAY names ([`array_scope_names`] over a
///   [`BuildInspection`](crate::simulate_array::BuildInspection)'s
///   `setup_arrays`), likewise with bare aliases.
///
/// The array half is what keeps the three bindings on one rule: Julia hands its
/// cellwise evaluator the build's `const_arrays`, so an array named after a
/// shape index set is a name a reference could already read there, and a guard
/// that checked only the parameter half would let Julia rebind it to the cell
/// index in silence while Python and Rust merely wrapped (issue #226).
///
/// The INDEPENDENT VARIABLE is rejected here for the same reason and in the
/// same words as in Julia and Python — see [`REFERENCE_MENTIONS_TIME`].
pub fn bind_dimension_names(
    expr: &Expr,
    dims: &[String],
    scope: &HashMap<String, f64>,
    arrays: &HashSet<String>,
) -> Result<Expr, String> {
    // esm-spec §6.6.5 names what a reference may read, and `t` is not on the
    // list. Reaching the evaluator with it is not an error there — the
    // build-time evaluator has a time slot and it holds `0.0` — so before this
    // check every binding answered a `t`-dependent reference with its value at
    // the start of the span and reported a plausible wrong number. A reference
    // whose FIELD is shaped over an index set actually named `t` is a
    // different statement: there `t` IS a dimension name, §6.6.5 admits it,
    // and it binds to the cell index below.
    if !dims.iter().any(|d| d == TIME_VARIABLE) && mentions_free(expr, TIME_VARIABLE) {
        return Err(REFERENCE_MENTIONS_TIME.to_string());
    }
    let mentioned: Vec<&String> = dims.iter().filter(|d| mentions_free(expr, d)).collect();
    if mentioned.is_empty() {
        return Ok(expr.clone());
    }
    if let Some(clash) = mentioned
        .iter()
        .find(|d| scope.contains_key(d.as_str()) || arrays.contains(d.as_str()))
    {
        let kind = if scope.contains_key(clash.as_str()) {
            "a parameter"
        } else {
            "a build-time array"
        };
        return Err(format!(
            "inline `reference` mentions '{clash}', which is both a dimension of the \
             asserted field and a name the build-time scope already binds ({kind}). \
             esm-spec §6.6.5 binds a free dimension name to the cell's 1-based \
             position, which would shadow it. Rename one of them, or gather \
             explicitly with `aggregate(i from {clash}; …)`."
        ));
    }
    let ranges: serde_json::Map<String, serde_json::Value> = dims
        .iter()
        .map(|d| (d.clone(), serde_json::json!({ "from": d })))
        .collect();
    // Reported, not asserted: `run_inline_tests` records a per-assertion failure
    // message for every error this returns, and `bind_dimension_names` is `pub`,
    // so an `Expr` built programmatically (a non-finite `Expr::Number`, say)
    // must not abort the whole run through a panicking `expect`.
    let wrapped = serde_json::json!({
        "op": "faq",
        "args": [],
        "output_idx": dims,
        "ranges": ranges,
        "expr": serde_json::to_value(expr)
            .map_err(|e| format!("inline `reference` could not be serialized: {e}"))?,
    });
    serde_json::from_value(wrapped).map_err(|e| {
        format!("inline `reference` could not be wrapped in a dimension-name gather: {e}")
    })
}

/// Collapse a spatial field to the scalar a §6.6.5 `reduce` assertion
/// compares (esm-spec §6.6.5); semantics identical to the Julia / Python
/// references:
///
/// - `"L2_error"`  — `‖actual − reference‖₂ / ‖reference‖₂` (relative L2 over
///   the domain; requires `reference`).
/// - `"Linf_error"` — `max |actual − reference|` (absolute supremum norm;
///   requires `reference`).
/// - `"integral"` — the uniform-cell Riemann sum under a UNIT total domain
///   measure per axis: `Σ field / N_cells`, i.e. exactly `mean`. This is the
///   pinned cross-binding convention (the same measure convention under which
///   the relative-L2 reduction is measure-free); non-unit physical domains
///   must be scaled by the author until the spec grows a measure concept.
/// - `"mean" | "max" | "min"` — pure collapsers of `actual`.
pub fn field_reduce(kind: &str, actual: &[f64], reference: Option<&[f64]>) -> Result<f64, String> {
    match kind {
        "L2_error" | "Linf_error" => {
            let r = reference
                .ok_or_else(|| format!("field_reduce: `{kind}` requires a reference field"))?;
            if r.len() != actual.len() {
                return Err(format!(
                    "field_reduce: actual has {} cells but reference has {}",
                    actual.len(),
                    r.len()
                ));
            }
            if kind == "L2_error" {
                let refnorm = r.iter().map(|v| v * v).sum::<f64>().sqrt();
                if refnorm == 0.0 {
                    return Err("field_reduce: L2_error reference has zero norm".to_string());
                }
                let diffnorm = actual
                    .iter()
                    .zip(r.iter())
                    .map(|(a, b)| (a - b) * (a - b))
                    .sum::<f64>()
                    .sqrt();
                Ok(diffnorm / refnorm)
            } else {
                Ok(actual
                    .iter()
                    .zip(r.iter())
                    .map(|(a, b)| (a - b).abs())
                    .fold(0.0f64, f64::max))
            }
        }
        "mean" | "integral" => {
            if actual.is_empty() {
                return Err("field_reduce: empty field".to_string());
            }
            Ok(actual.iter().sum::<f64>() / actual.len() as f64)
        }
        "max" => {
            if actual.is_empty() {
                return Err("field_reduce: empty field".to_string());
            }
            Ok(actual.iter().copied().fold(f64::NEG_INFINITY, f64::max))
        }
        "min" => {
            if actual.is_empty() {
                return Err("field_reduce: empty field".to_string());
            }
            Ok(actual.iter().copied().fold(f64::INFINITY, f64::min))
        }
        other => Err(format!("field_reduce: unsupported reduce kind '{other}'")),
    }
}

/// Split an element name of the form `stem[1,2,…]` into `(stem, cell)`;
/// `None` for a scalar name (no bracketed all-integer suffix).
fn parse_cell_name(name: &str) -> Option<(&str, Vec<i64>)> {
    let open = name.rfind('[')?;
    let inner = name.strip_suffix(']')?.get(open + 1..)?;
    if inner.is_empty() {
        return None;
    }
    let mut cell = Vec::new();
    for part in inner.split(',') {
        if part.is_empty() || !part.bytes().all(|b| b.is_ascii_digit()) {
            return None;
        }
        cell.push(part.parse::<i64>().ok()?);
    }
    Some((&name[..open], cell))
}

/// Collect the (cell-index-tuple, row) pairs of one array state from the
/// simulation's element names (`element_names[row]` is the name of state row
/// `row`, e.g. `"Heat.u[3]"`). Flattening prefixes element names with the
/// owning model, and a coupled build may reuse the same bare array name across
/// components (`M1.u`, `M2.u`); to avoid mixing every model's cells into one
/// field, the model-qualified stem wins — an exact `model.variable` /
/// bare-`variable` stem match first, then a bare-suffix fallback reached only
/// when no exact stem exists (a bare-keyed single-model build). This is the
/// array analog of [`scalar_slot`]'s qualified-first two-pass resolution.
/// Sorted by cell tuple so callers get a deterministic pairing.
pub fn state_cells(
    element_names: &[String],
    variable: &str,
    model: &str,
) -> Vec<(Vec<i64>, usize)> {
    let qualified = format!("{model}.{variable}");
    // Two passes mirroring `scalar_slot`: gather exact model-qualified /
    // exact-bare stem matches, and only fall back to the bare-suffix stems when
    // no exact stem matched. A single pass that unions both would splice every
    // sibling model's `u` cells into one field on a shared bare name.
    let mut exact: Vec<(Vec<i64>, usize)> = Vec::new();
    let mut fallback: Vec<(Vec<i64>, usize)> = Vec::new();
    for (row, name) in element_names.iter().enumerate() {
        let Some((stem, cell)) = parse_cell_name(name) else {
            continue;
        };
        if stem == qualified || stem == variable {
            exact.push((cell, row));
        } else if stem.split_once('.').map(|(_, b)| b).unwrap_or(stem) == variable {
            fallback.push((cell, row));
        }
    }
    let mut out = if exact.is_empty() { fallback } else { exact };
    out.sort_by(|a, b| a.0.cmp(&b.0));
    out
}

/// Row of a SCALAR state / scalar OBSERVED by model-qualified name (preferred)
/// or bare name; `None` if absent.
///
/// Flattening qualifies every element with its owning model (`"arrh.k"`), and a
/// coupled build routinely reuses the same bare observed name across sibling
/// components — several reaction-rate coefficients all named `k`. So the
/// model-qualified name MUST win: a bare-name match alone returns the first `k`
/// in layout order (`M1.k`) for every model's `k` assertion, reading the wrong
/// component's value. We therefore do two passes — an exact qualified /
/// exact-bare match first, then a bare-suffix fallback (reached only when the
/// qualified element is absent, e.g. a bare-keyed single-model build). Mirrors
/// the Python `_scalar_slot` two-pass semantics.
fn scalar_slot(
    element_names: &[String],
    variable: &str,
    model: &str,
    renames: &HashMap<String, String>,
) -> Option<usize> {
    let qualified = format!("{model}.{variable}");
    // Pass 1: exact model-qualified or exact bare match.
    for (row, name) in element_names.iter().enumerate() {
        if name == &qualified || name == variable {
            return Some(row);
        }
    }
    // Pass 2: bare-suffix fallback, reached only when no exact match exists.
    for (row, name) in element_names.iter().enumerate() {
        let bare = name.split_once('.').map(|(_, b)| b).unwrap_or(name);
        if bare == variable {
            return Some(row);
        }
    }
    // Pass 3: a name an `operator_compose` renaming match DELETED. A test is
    // written against the component that owns it, and a merge can fold that
    // component's state onto another's -- the quantity the assertion names
    // still exists, under the survivor's spelling. LAST, so a live row always
    // wins: resolution may never shadow a variable the flattened system really
    // has (CONFORMANCE_SPEC §5.35).
    let survivor = renames.get(&qualified).or_else(|| renames.get(variable))?;
    element_names.iter().position(|name| name == survivor)
}

/// esm-spec §6.6.4, resolved PER FIELD over FOUR levels: assertion > test >
/// model > the implementation default. Each of `rel` and `abs` independently
/// takes its value from the innermost level that declares it; the default
/// supplies `rel = 1e-6` and no `abs` bound to whatever is still undeclared
/// after the three document levels. Identical to the Julia
/// `_resolve_tolerance` reference and the Python `_resolve_tolerance`. Returns
/// `(rtol, atol)`.
///
/// The merge is per-field and NOT wholesale. A level that declares only `abs`
/// does not mask an outer level's `rel`: with a model `{rel: 1e-6}` and an
/// assertion `{abs: 1e-9}` the resolved pair is `(1e-6, 1e-9)`, not
/// `(0, 1e-9)`. Returning the first `Some` block whole — what this did before
/// #228 — ran such an assertion with NO relative bound at all, silently
/// dropping a tolerance its author declared one level up.
///
/// **Absent vs zero.** A field is absent when the key is missing or JSON-null
/// (the schema admits only a number, so `null` is non-conforming input treated
/// as absent); only an absent field falls through. An explicit `0` is a
/// DECLARATION — "no bound of this kind" — and stops the fallthrough, the
/// default included. That distinction carries the whole rule: the recurrence
/// fixtures pin exactness with a model-level `{rel: 0, abs: 0}`
/// (CONFORMANCE_SPEC §5.19), and `rel: 0` is how a document says "this
/// absolute bound and nothing else" now that the default is not terminal.
///
/// **The implementation default is the FOURTH LEVEL** of the same per-field
/// merge, not a fallback reached only when levels 1-3 are silent. An assertion
/// declaring only `{abs: 1e-4}` therefore resolves to `rel = 1e-6`, not
/// `rel = 0`.
pub fn resolve_tolerance(
    model_tol: Option<&Tolerance>,
    test_tol: Option<&Tolerance>,
    assertion_tol: Option<&Tolerance>,
) -> (f64, f64) {
    let levels = [assertion_tol, test_tol, model_tol];
    let first =
        |pick: fn(&Tolerance) -> Option<f64>| levels.iter().copied().flatten().find_map(pick);
    let rel = first(|t| t.rel);
    let atol = first(|t| t.abs);
    (rel.unwrap_or(DEFAULT_REL_TOL), atol.unwrap_or(0.0))
}

/// The esm-spec §6.6.3 pass predicate — `actual == expected`, or both values
/// FINITE and `|a − e| ≤ max(atol, rtol·max(|a|, |e|))` — the same predicate
/// the Julia / Python `run_inline_tests` use (see also CONFORMANCE_SPEC §5.20).
/// This is Julia `isapprox`.
///
/// **The relative bound is SYMMETRIC** in `actual` and `expected`: its scale is
/// `max(|a|, |e|)`, the larger of the two magnitudes, not `|e|` alone. §6.6.3
/// used to state both readings at once — the normative box gave an
/// `|expected|`-only denominator while the finiteness rationale further down
/// that same section reasoned from `max(|inf|, |expected|)` — and this
/// function was written against the second. EarthSciML/EarthSciAST#193 settled
/// the spec as symmetric, so the two now agree and this line is normative
/// rather than merely conventional. The verdicts differ only inside
/// `rtol*|e| < |a − e| <= rtol*|a|`, which needs an overshoot
/// (`|actual| > |expected|`) of order `rtol`;
/// `relative_bound_is_symmetric_in_actual_and_expected` pins that seam.
///
/// **Finiteness is judged BEFORE tolerance**, and that clause is not a
/// corollary of the bound — it contradicts it. With `actual = ±inf` both sides
/// of `|actual − expected| ≤ max(atol, rtol·max(|actual|, |expected|))` are
/// `inf`, so the comparison held for EVERY finite `expected`: an assertion on
/// an overflowed product, a division by a zero denominator or a `log(0)`
/// reported PASS whatever it expected, and a document that computed nothing
/// meaningful would go green. NaN does not have the problem (every IEEE-754
/// comparison with NaN is false), so the rule matters for infinities. Julia's
/// `isapprox` behaves the same way:
/// `x == y || (isfinite(x) && isfinite(y) && …)`.
///
/// `actual == expected` keeps the one case a non-finite value legitimately
/// matches: the SAME infinity, with the same sign. A `.esm` document cannot
/// spell an infinite `expected` (JSON has no infinite literal), so within a
/// document the rule reduces to "a non-finite actual always fails"; the
/// equality clause governs an API caller. It also keeps the zero-tolerance
/// exact-equality mode, and `-0.0 == 0.0` under IEEE-754, so a signed zero is
/// unaffected.
pub fn check_assertion(actual: f64, expected: f64, rtol: f64, atol: f64) -> bool {
    if actual == expected {
        return true;
    }
    if !actual.is_finite() || !expected.is_finite() {
        return false;
    }
    if rtol == 0.0 && atol == 0.0 {
        // Exact-equality mode; the equality above already answered it.
        return false;
    }
    (actual - expected).abs() <= f64::max(atol, rtol * f64::max(actual.abs(), expected.abs()))
}

/// Index of the saved output time matching `t` to within
/// `1e-9 · max(1, |t|)`; `Err` when the trajectory holds no such sample.
fn time_index(times: &[f64], t: f64) -> Result<usize, String> {
    let mut best: Option<(usize, f64)> = None;
    for (i, &tv) in times.iter().enumerate() {
        let d = (tv - t).abs();
        if best.map(|(_, bd)| d < bd).unwrap_or(true) {
            best = Some((i, d));
        }
    }
    let (i, d) = best.ok_or_else(|| format!("no saved state at t={t} (empty trajectory)"))?;
    if d <= 1e-9 * f64::max(1.0, t.abs()) {
        Ok(i)
    } else {
        Err(format!("no saved state at t={t} (nearest {})", times[i]))
    }
}

/// Build-time scalar-parameter scope for §6.6.5 cellwise references, as the
/// component that OWNS the test writes names.
///
/// [`BuildInspection::params`] is keyed by the FLATTENED parameter name
/// (`"M.k"`, `"M.sub.g"`) — matching a resolved observed expression, which
/// flattening qualifies. A test author's analytic `reference`, though, spells a
/// name the way the owning component's own EQUATIONS spell it: BARE (`"k"`) for
/// the component's own parameter, and by the MOUNT NAME (`"sub.g"`) for one
/// reached through a subsystem mount. So the scope binds, in decreasing
/// precedence:
///
/// 1. the flattened key VERBATIM;
/// 2. every key under `owner.`, stripped of that prefix — the owning
///    component's own namespace, which is what its equations resolve against.
///    `owner` is the component the test belongs to (a scoped assertion's target
///    component, per [`resolve_asserted_name`]), so `M.sub.g` is `sub.g` here
///    even in a document where five OTHER components each mount a `sub` of
///    their own. This is the same re-attachment [`scope_to_component`] performs
///    on an override key, and it is what issue #408 was missing: `wrf.g`
///    resolved in every equation of a coupling and in `parameter_overrides`,
///    but not in a `reference`, where only `<Model>.wrf.g` worked — a spelling
///    a mount edge does NOT rewrite, so it pins a component to being mounted
///    under its own model name;
/// 3. every GLOBALLY unambiguous dotted suffix (`"M.sub.g"` → `"sub.g"`,
///    `"g"`), the alias set esm-spec §6.6.2 rule 3 gives an override key. This
///    is what lets a test name a parameter the owner does not own, and it
///    subsumes the bare-tail alias this function bound before.
///
/// A suffix carried by two or more flattened names is AMBIGUOUS and binds
/// nothing at step 3 — the flattened key stays authoritative and such a
/// reference must qualify further (step 2 still reaches the owner's own, which
/// is unambiguous by construction: flattened keys are unique, so their
/// owner-relative remainders are too). A name that is neither is UNBOUND, which
/// is what keeps a typo (`sub.gg`) an error rather than a silent zero.
///
/// The suffix enumeration is the override resolver's own
/// [`dotted_suffixes`](crate::simulate::override_keys::dotted_suffixes), shared
/// rather than re-derived so the two positions cannot drift apart again.
/// Mirrors the Julia / Python `param_scope_with_aliases`.
fn param_scope_with_aliases(params: &HashMap<String, f64>, owner: &str) -> HashMap<String, f64> {
    use crate::simulate::override_keys::dotted_suffixes;
    let mut out: HashMap<String, f64> = params.clone();
    // (2) The owner's own namespace, as its equations spell it.
    let prefix = format!("{owner}.");
    for (k, v) in params {
        if let Some(rest) = k.strip_prefix(prefix.as_str()) {
            out.entry(rest.to_string()).or_insert(*v);
        }
    }
    // (3) Globally unambiguous dotted suffixes.
    let mut counts: HashMap<&str, usize> = HashMap::new();
    for k in params.keys() {
        for suffix in dotted_suffixes(k) {
            *counts.entry(suffix).or_insert(0) += 1;
        }
    }
    for (k, v) in params {
        for suffix in dotted_suffixes(k) {
            if counts.get(suffix) == Some(&1) && !out.contains_key(suffix) {
                out.insert(suffix.to_string(), *v);
            }
        }
    }
    out
}

/// The ARRAY half of the §6.6.5 build-time clash scope: every name the build's
/// array registries bind, plus each one's UNAMBIGUOUS bare alias — the same
/// alias rule [`param_scope_with_aliases`] applies to the scalar half, and the
/// rule under which a flattened `M.table` is readable as `table`. Takes any
/// number of name iterators (a [`BuildInspection`]'s `setup_arrays`, and in the
/// other bindings its `const_arrays` too), so a binding that keeps its build
/// arrays in more than one registry passes all of them. Mirrors the Julia
/// `_array_scope_names` / Python `_array_scope_names`.
pub(crate) fn array_scope_names<'a>(
    registries: impl IntoIterator<Item = &'a str>,
) -> HashSet<String> {
    let names: HashSet<String> = registries.into_iter().map(|s| s.to_string()).collect();
    let mut counts: HashMap<&str, usize> = HashMap::new();
    for n in &names {
        let bare = n.rsplit('.').next().unwrap_or(n.as_str());
        if bare != n.as_str() {
            *counts.entry(bare).or_insert(0) += 1;
        }
    }
    let mut out = names.clone();
    for n in &names {
        let bare = n.rsplit('.').next().unwrap_or(n.as_str());
        if bare != n.as_str() && counts.get(bare) == Some(&1) {
            out.insert(bare.to_string());
        }
    }
    out
}

/// A §6.6.5 assertion may target an ARRAY OBSERVED (e.g. a rule output
/// surfaced "for direct assertion", like the MPAS `div_flux`) rather than a
/// state: an observed carries no ODE slot, so its field is read from the
/// [`BuildInspection`]'s `setup_arrays` — the STATE-FREE observed arrays the
/// run materialized through the official observed machinery.
///
/// This source stays STATE-FREE-only: a state- or time-dependent observed is
/// absent from `setup_arrays` by construction, and this returns `None` for it.
/// That is no longer the end of the assertion, though — the runner REQUESTS such
/// an observed (`assertion_observed_requests`), the array runtime emits it as
/// one row per cell, and the assertion reads those rows through `state_cells`
/// before ever reaching here. So a `None` from this function means "not a field
/// the BUILD carries", not "unassertable".
///
/// Cells are enumerated from the declared shape's interval index sets, in sorted
/// (lexicographic) order. Returns `(field, cells)` or `None` when the variable
/// is not such an observed.
fn observed_field(
    file: &EsmFile,
    model_name: &str,
    variable: &str,
    insp: &BuildInspection,
    index_sets: &HashMap<String, IndexSet>,
) -> Option<(Vec<f64>, Vec<Vec<i64>>)> {
    let model = model_at(file, model_name)?;
    let v = model.variables.get(variable)?;
    // OBSERVED is derived from the equations (esm-spec §6.3.1), not declared.
    if !crate::classification::Classification::of(&model).is_observed(variable) {
        return None;
    }
    let shape = v.shape.as_ref()?;
    if shape.is_empty() {
        return None;
    }
    let mut exts: Vec<usize> = Vec::with_capacity(shape.len());
    for s in shape {
        let iset = index_sets.get(s)?;
        if iset.kind != "interval" {
            return None;
        }
        exts.push(usize::try_from(iset.size?).ok()?);
    }
    let arr = build_field(insp, file, model_name, variable)?;
    if arr.ndim() != exts.len()
        || arr
            .shape()
            .iter()
            .zip(&exts)
            .any(|(have, want)| have < want)
    {
        return None;
    }
    // Lexicographically ordered 1-based cell tuples (row-major enumeration is
    // lexicographic), matching the Julia reference's sorted CartesianIndices.
    let total: usize = exts.iter().product();
    let mut cells: Vec<Vec<i64>> = Vec::with_capacity(total);
    let mut cur = vec![1i64; exts.len()];
    for _ in 0..total {
        cells.push(cur.clone());
        for d in (0..exts.len()).rev() {
            if (cur[d] as usize) < exts[d] {
                cur[d] += 1;
                break;
            }
            cur[d] = 1;
        }
    }
    let field: Vec<f64> = cells
        .iter()
        .map(|c| {
            let idx: Vec<usize> = c.iter().map(|&i| (i - 1) as usize).collect();
            arr[ndarray::IxDyn(&idx)]
        })
        .collect();
    Some((field, cells))
}

/// The spellings under which a build may key the elements of the component at
/// `owner`. A COUPLED document is flattened across its components, so every
/// element carries the whole component path (`Host.Leaf.key`); a document with a
/// single top-level component is built from that component alone, so its
/// elements are keyed model-locally and a mounted one carries only the path
/// BELOW the root (`Mid.Leaf.key`). The mount-relative spelling is offered ONLY
/// for that single-component shape: in a coupled document its head is a SIBLING
/// top-level component's name, and reading a row under it would answer an
/// assertion with a different component's value.
fn owner_spellings(file: &EsmFile, owner: &str) -> Vec<String> {
    let mut out = vec![owner.to_string()];
    let tops = file.models.as_ref().map_or(0, |m| m.len())
        + file.reaction_systems.as_ref().map_or(0, |r| r.len());
    if tops == 1
        && let Some((_, below_root)) = owner.split_once('.')
    {
        out.push(below_root.to_string());
    }
    out
}

/// The field the build materialized for `variable` of the component at
/// `model_name`, under whichever spelling the build keyed it by
/// ([`owner_spellings`]). The BARE name is a fourth candidate only for an
/// UNSCOPED component: a single-model build keeps that model's own names bare,
/// while for a mounted component a bare hit belongs to the root, not to it.
fn build_field<'a>(
    insp: &'a BuildInspection,
    file: &EsmFile,
    model_name: &str,
    variable: &str,
) -> Option<&'a ndarray::ArrayD<f64>> {
    for m in owner_spellings(file, model_name) {
        if let Some(arr) = insp.setup_arrays.get(&format!("{m}.{variable}")) {
            return Some(arr);
        }
    }
    if model_name.contains('.') {
        return None;
    }
    insp.setup_arrays.get(variable)
}

/// The trajectory row of the SCALAR `variable` of the component at `owner`,
/// matched only under a spelling that component can own ([`owner_spellings`]),
/// then through a merge rename. Used for a SCOPED assertion, where
/// [`scalar_slot`]'s bare-name fallbacks would reach a row belonging to another
/// component entirely.
fn scoped_scalar_slot(
    element_names: &[String],
    spellings: &[String],
    variable: &str,
    renames: &HashMap<String, String>,
) -> Option<usize> {
    for m in spellings {
        let qualified = format!("{m}.{variable}");
        if let Some(row) = element_names.iter().position(|n| *n == qualified) {
            return Some(row);
        }
    }
    let survivor = renames.get(&format!("{}.{variable}", spellings[0]))?;
    element_names.iter().position(|n| n == survivor)
}

/// The cells of the ARRAY `variable` of the component at `owner`, matched only
/// under a spelling that component can own. The scoped twin of
/// [`state_cells`], whose bare-suffix fallback would splice another component's
/// cells into the field.
fn scoped_state_cells(
    element_names: &[String],
    spellings: &[String],
    variable: &str,
) -> Vec<(Vec<i64>, usize)> {
    for m in spellings {
        let qualified = format!("{m}.{variable}");
        let mut out: Vec<(Vec<i64>, usize)> = element_names
            .iter()
            .enumerate()
            .filter_map(|(row, name)| {
                let (stem, cell) = parse_cell_name(name)?;
                (stem == qualified).then_some((cell, row))
            })
            .collect();
        if !out.is_empty() {
            out.sort_by(|a, b| a.0.cmp(&b.0));
            return out;
        }
    }
    Vec::new()
}

/// A §6.6.3 POINTWISE assertion's value when the variable has no trajectory
/// row: the STATE-FREE SCALAR OBSERVED of that name, read from the
/// [`BuildInspection`]'s materialized fields. The 0-D twin of
/// [`observed_field`], with the same two guards — the variable must be an
/// OBSERVED (derived from the equations, esm-spec §6.3.1, never a state or a
/// parameter) and its field must be one the build actually materialized — so a
/// variable the build never bound is `None`, and the caller reports it, rather
/// than reading a plausible zero out of an unbound slot.
///
/// Declared 0-D only. An array-shaped variable's field belongs to
/// [`observed_field`], which enumerates its cells; a pointwise assertion on one
/// is ill-formed per §6.6.5 and must not silently collapse to its first cell.
/// Both key spellings are accepted, because the two field maps are keyed
/// differently: the build pipeline by the selected model's own variable name,
/// the state-free static evaluation by the flattened one.
fn scalar_observed(
    file: &EsmFile,
    model_name: &str,
    variable: &str,
    insp: &BuildInspection,
) -> Option<f64> {
    let model = model_at(file, model_name)?;
    let v = model.variables.get(variable)?;
    if v.shape.as_ref().is_some_and(|s| !s.is_empty()) {
        return None;
    }
    if !crate::classification::Classification::of(&model).is_observed(variable) {
        return None;
    }
    let arr = build_field(insp, file, model_name, variable)?;
    // A 0-D field is stored rank-0 or as a single cell; anything else is not
    // this variable's field and is not guessed at.
    if arr.len() != 1 {
        return None;
    }
    arr.iter().next().copied()
}

/// The asserted variable's declared spatial shape (ordered index-set names).
/// `Err` when the variable is missing or scalar — a `coords` assertion is
/// ill-formed on a 0-D variable per esm-spec §6.6.5 (identical to the Julia
/// reference's `_variable_shape`).
fn variable_shape(file: &EsmFile, model_name: &str, variable: &str) -> Result<Vec<String>, String> {
    let model =
        model_at(file, model_name).ok_or_else(|| format!("model '{model_name}' not found"))?;
    let v = model
        .variables
        .get(variable)
        .ok_or_else(|| format!("variable '{variable}' is not declared in model '{model_name}'"))?;
    match &v.shape {
        Some(shape) if !shape.is_empty() => Ok(shape.clone()),
        _ => Err(format!(
            "`coords` requires a spatially-shaped variable; '{variable}' is scalar"
        )),
    }
}

/// Resolve a §6.6.5 `coords` map to a concrete 1-based cell tuple over
/// `shape` (the field's ordered index-set names), per the pinned
/// cross-binding convention: coords values are positions in INDEX space
/// (1-based, fractional allowed) along interval index sets; sampling =
/// nearest grid index with exact half-way ties rounding DOWN
/// (`idx = ceil(c - 1/2)`). A strict subset of dimensions may be pinned only
/// when every remaining dimension is singleton (identical to the Julia
/// reference's `_coords_cell`).
fn coords_cell(
    coords: &HashMap<String, f64>,
    shape: &[String],
    index_sets: &HashMap<String, IndexSet>,
) -> Result<Vec<i64>, String> {
    for k in coords.keys() {
        if !shape.iter().any(|s| s == k) {
            return Err(format!(
                "`coords` names unknown dimension '{k}' (field dimensions: {})",
                shape.join(", ")
            ));
        }
    }
    let mut cell = Vec::with_capacity(shape.len());
    for s in shape {
        let size = index_sets
            .get(s)
            .filter(|iset| iset.kind == "interval")
            .and_then(|iset| iset.size)
            .ok_or_else(|| {
                format!(
                    "`coords` sampling requires interval index sets with a \
                     declared size; '{s}' is not one"
                )
            })?;
        match coords.get(s) {
            Some(&c) => {
                let idx = (c - 0.5).ceil() as i64; // nearest index; exact ties round DOWN
                if idx < 1 || idx > size {
                    return Err(format!(
                        "`coords` position {c} along '{s}' resolves to index \
                         {idx}, outside 1..{size}"
                    ));
                }
                cell.push(idx);
            }
            None => {
                if size != 1 {
                    return Err(format!(
                        "`coords` leaves dimension '{s}' unpinned with {size} \
                         samples; a strict subset pins only when every \
                         remaining dimension is singleton"
                    ));
                }
                cell.push(1);
            }
        }
    }
    Ok(cell)
}

/// Walk a row-major nested JSON array to the value at 1-based `cell`,
/// validating each level's extent against `exts` (the field's per-dimension
/// extents). The full Cartesian cell sweep visits every node, so ragged or
/// mis-sized payloads always surface a shape-mismatch error.
fn nested_at(data: &serde_json::Value, cell: &[i64], exts: &[usize]) -> Result<f64, String> {
    let mut node = data;
    for (d, &i) in cell.iter().enumerate() {
        let arr = node.as_array().ok_or_else(|| {
            format!(
                "from_file reference shape mismatch along dimension {}: \
                 expected a nested array of length {}",
                d + 1,
                exts[d]
            )
        })?;
        if arr.len() != exts[d] {
            return Err(format!(
                "from_file reference shape mismatch along dimension {}: \
                 expected length {}, found {}",
                d + 1,
                exts[d],
                arr.len()
            ));
        }
        node = &arr[(i - 1) as usize];
    }
    node.as_f64().ok_or_else(|| {
        format!(
            "from_file reference shape mismatch at cell [{}]: expected a number",
            cell.iter()
                .map(|c| c.to_string())
                .collect::<Vec<_>>()
                .join(",")
        )
    })
}

/// Load a `{type: "from_file", path, format?}` reference (esm-spec §6.6.5)
/// as the per-cell reference field over `cell_tuples`, per the pinned
/// cross-binding convention: `path` resolves relative to `base_dir` (the
/// .esm file's directory; `None` resolves against the working directory);
/// the default and only v1 `format` is "json" — a row-major nested array
/// exactly matching the field's shape (identical to the Julia reference's
/// `_from_file_reference`).
fn from_file_reference(
    ff: &FromFileReference,
    base_dir: Option<&Path>,
    cell_tuples: &[Vec<i64>],
) -> Result<Vec<f64>, String> {
    let fmt = ff
        .format
        .as_deref()
        .map(str::to_lowercase)
        .unwrap_or_else(|| "json".to_string());
    if fmt != "json" {
        return Err(format!(
            "from_file reference format '{fmt}' is not supported (v1 supports \"json\" only)"
        ));
    }
    let p = Path::new(&ff.path);
    let resolved = if p.is_absolute() {
        p.to_path_buf()
    } else {
        base_dir.unwrap_or_else(|| Path::new(".")).join(p)
    };
    if !resolved.is_file() {
        return Err(format!(
            "from_file reference file not found: {}",
            resolved.display()
        ));
    }
    let text = std::fs::read_to_string(&resolved)
        .map_err(|e| format!("from_file reference read failed: {e}"))?;
    let data: serde_json::Value = serde_json::from_str(&text)
        .map_err(|e| format!("from_file reference is not valid JSON: {e}"))?;
    if cell_tuples.is_empty() {
        return Err("from_file reference: field has no cells".to_string());
    }
    let nd = cell_tuples[0].len();
    let exts: Vec<usize> = (0..nd)
        .map(|d| {
            cell_tuples
                .iter()
                .map(|c| c[d].max(0) as usize)
                .max()
                .unwrap_or(0)
        })
        .collect();
    cell_tuples
        .iter()
        .map(|c| nested_at(&data, c, &exts))
        .collect()
}

/// A component a dotted component path names (esm-spec §4.6).
enum ComponentAt<'a> {
    /// A top-level model (borrowed) or a mounted subsystem (read out of the
    /// JSON the typed document keeps it as).
    Model(Box<Cow<'a, Model>>),
    ReactionSystem(&'a crate::types::ReactionSystem),
}

impl ComponentAt<'_> {
    fn has_subsystem(&self, name: &str) -> bool {
        let subs = match self {
            Self::Model(m) => m.subsystems.as_ref(),
            Self::ReactionSystem(r) => r.subsystems.as_ref(),
        };
        subs.is_some_and(|s| s.contains_key(name))
    }
}

/// The component a dotted component PATH names, or `None` (esm-spec §4.6): the
/// first segment is a top-level `models` / `reaction_systems` key and each later
/// one a key of its parent's `subsystems`. A mounted entry is read by the array
/// compiler's own [`crate::simulate_array::parse_subsystem_model`], so the two
/// shapes a resolved mount takes (the referenced file's whole document, or a
/// bare model) and an unresolved `{"ref": …}` (which ends the walk) are
/// classified exactly as the build classifies them. Identical to the Julia and
/// Python `_component_at`.
fn component_at<'a>(file: &'a EsmFile, path: &str) -> Option<ComponentAt<'a>> {
    let mut segs = path.split('.');
    let head = segs.next()?;
    let mut cur = match file.models.as_ref().and_then(|ms| ms.get(head)) {
        Some(m) => ComponentAt::Model(Box::new(Cow::Borrowed(m))),
        None => ComponentAt::ReactionSystem(file.reaction_systems.as_ref()?.get(head)?),
    };
    for seg in segs {
        let subs = match &cur {
            ComponentAt::Model(m) => m.subsystems.as_ref(),
            ComponentAt::ReactionSystem(r) => r.subsystems.as_ref(),
        }?;
        let (model, _) = crate::simulate_array::parse_subsystem_model(seg, subs.get(seg)?).ok()?;
        cur = ComponentAt::Model(Box::new(Cow::Owned(model)));
    }
    Some(cur)
}

/// The MODEL a dotted component path names, or `None` for a reaction system or
/// a path that names nothing.
fn model_at<'a>(file: &'a EsmFile, path: &str) -> Option<Cow<'a, Model>> {
    match component_at(file, path)? {
        ComponentAt::Model(m) => Some(*m),
        ComponentAt::ReactionSystem(_) => None,
    }
}

/// Split an assertion's `variable` into `(owner component path, local name)`.
///
/// The schema documents `Assertion.variable` as a local name OR a scoped
/// reference, and it resolves by the rule flatten's namespacing already applies
/// to the same string in the same component's equations: a dotted name whose
/// HEAD is a subsystem key of the asserting component is relative to it
/// (`Leaf.u` in `Host` with a `Leaf` subsystem is `Host.Leaf.u`); any other
/// dotted name is document-absolute (§4.6). Every per-component lookup then runs
/// against the owner, so a mounted leaf's state, observed and declared shape are
/// read from the leaf.
///
/// A bare name, or a dotted one that walks to no component, is returned
/// unchanged against `model_name`, and the caller reports it exactly as before.
/// Identical to the Julia and Python `_resolve_asserted_name`.
fn resolve_asserted_name<'v>(
    file: &EsmFile,
    model_name: &str,
    variable: &'v str,
) -> (String, &'v str) {
    let Some((prefix, local)) = variable.rsplit_once('.') else {
        return (model_name.to_string(), variable);
    };
    let head = prefix.split('.').next().unwrap_or(prefix);
    let owner = if component_at(file, model_name).is_some_and(|c| c.has_subsystem(head)) {
        format!("{model_name}.{prefix}")
    } else {
        prefix.to_string()
    };
    if component_at(file, &owner).is_none() {
        return (model_name.to_string(), variable);
    }
    (owner, local)
}

/// Evaluate one assertion against a solved trajectory; `Err` carries the
/// reason text (recorded verbatim into the result's `message`).
fn eval_assertion(
    sol: &Solution,
    assertion: &crate::types::ModelTestAssertion,
    model_name: &str,
    index_sets: &HashMap<String, IndexSet>,
    file: &EsmFile,
    insp: &BuildInspection,
    base_dir: Option<&Path>,
) -> Result<f64, String> {
    let ti = time_index(&sol.time, assertion.time)?;
    // A scoped `variable` reads the component it names (schema
    // `Assertion.variable`); every lookup below runs against that owner.
    let (owner, variable) = resolve_asserted_name(file, model_name, &assertion.variable);
    // A scoped name is read ONLY under a spelling the component it names can
    // own; the bare-name fallbacks that serve an unscoped assertion would reach
    // a same-named row of another component (`tests/conformance/
    // scoped_assertion_variable/fixtures/shadowed_dynamic_field.esm`).
    let scoped = owner != model_name;
    let spellings = owner_spellings(file, &owner);
    let model_name = owner.as_str();
    if assertion.coords.is_some() && assertion.reduce.is_some() {
        return Err("`coords` and `reduce` are mutually exclusive".to_string());
    }
    if assertion.coords.is_none() && assertion.reduce.is_none() {
        let slot = if scoped {
            scoped_scalar_slot(
                &sol.state_variable_names,
                &spellings,
                variable,
                &sol.metadata.merged_variable_renames,
            )
        } else {
            scalar_slot(
                &sol.state_variable_names,
                variable,
                model_name,
                &sol.metadata.merged_variable_renames,
            )
        };
        if let Some(slot) = slot {
            return Ok(sol.state[slot][ti]);
        }
        // No trajectory row: a STATE-FREE SCALAR OBSERVED, read from the
        // fields the build materialized — the 0-D twin of the array branch
        // below, and the answer for a document with nothing to integrate at
        // all (an ingesting one, whose whole content IS its build-time
        // observed graph: `solve` legitimately refuses it and the trajectory
        // carries no rows).
        return scalar_observed(file, model_name, variable, insp).ok_or_else(|| {
            format!(
                "scalar state or state-free scalar observed '{}' not found \
                 (the build materialized neither)",
                assertion.variable
            )
        });
    }
    // `coords` validation runs BEFORE field materialization so a coords
    // assertion on a scalar variable fails with the §6.6.5 coords-specific
    // message (identical to the Julia reference).
    let coords_target = match &assertion.coords {
        Some(coords) => {
            let shape = variable_shape(file, model_name, variable)?;
            Some(coords_cell(coords, &shape, index_sets)?)
        }
        None => None,
    };
    let cells = if scoped {
        scoped_state_cells(&sol.state_variable_names, &spellings, variable)
    } else {
        state_cells(&sol.state_variable_names, variable, model_name)
    };
    let (field, cell_tuples): (Vec<f64>, Vec<Vec<i64>>) = if !cells.is_empty() {
        (
            cells.iter().map(|(_, row)| sol.state[*row][ti]).collect(),
            cells.iter().map(|(c, _)| c.clone()).collect(),
        )
    } else {
        // No ODE slots: try a state-free ARRAY OBSERVED (a rule output
        // asserted directly, §6.6.5).
        observed_field(file, model_name, variable, insp, index_sets).ok_or_else(|| {
            format!(
                "array state '{}' has no cells in var_map",
                assertion.variable
            )
        })?
    };
    if let Some(target) = coords_target {
        let pos = cell_tuples
            .iter()
            .position(|c| *c == target)
            .ok_or_else(|| {
                format!(
                    "no grid sample at cell [{}] of '{}'",
                    target
                        .iter()
                        .map(|c| c.to_string())
                        .collect::<Vec<_>>()
                        .join(","),
                    assertion.variable
                )
            })?;
        return Ok(field[pos]);
    }
    let reduce = assertion
        .reduce
        .as_ref()
        .expect("reduce is set on the non-coords array path");
    let reference = match &assertion.reference {
        None => None,
        Some(AssertionReference::Expression(expr)) => {
            // The analytic reference is the TEST'S oracle — the expected value
            // an assertion compares the model against — not an evaluation of
            // the model, so it is evaluated by the reference evaluator under
            // every compiler and is outside the compiler's refusal
            // (esm-libraries-spec §2.5.10 governs what the compiler evaluates
            // for the Problem). Serving it from the compiler under test would
            // let a compiler grade its own answer.
            //
            // Model parameters (load-time constants) are in scope for a §6.6.5
            // analytic reference; state is not. `insp.params` carries the
            // build's resolved scalar params. The field's dimension names are
            // in scope too, bound per cell (`bind_dimension_names`).
            let scope = param_scope_with_aliases(&insp.params, model_name);
            // The ARRAY half of the §6.6.5 clash scope: the three bindings must
            // reject the same documents, and Julia's cellwise evaluator reads
            // build arrays by name, so an array named after a shape index set
            // is a clash there and must be one here too (issue #226).
            let arrays = array_scope_names(insp.setup_arrays.keys().map(String::as_str));
            let dims = variable_shape(file, model_name, variable).unwrap_or_default();
            let bound = bind_dimension_names(expr, &dims, &scope, &arrays)?;
            Some(evaluate_cellwise(&bound, &cell_tuples, index_sets, &scope)?)
        }
        Some(AssertionReference::FromFile(ff)) => {
            Some(from_file_reference(ff, base_dir, &cell_tuples)?)
        }
    };
    field_reduce(reduce, &field, reference.as_deref())
}

/// esm-spec §9.7.10 form C: build a throwaway [`EsmFile`] in which component
/// `model_name` has the test's `imports` (raw §9.7.2 entries) appended to its
/// own `expression_template_imports`, so the ordinary import resolver + §9.6.3
/// fixpoint lower its rewrite-targets under the test-chosen discretization. The
/// persisted `file` is never mutated. When `source_path` is `Some`, the raw base
/// is re-read from it (relative `ref`s resolve against its directory); otherwise
/// it is re-serialized from the loaded `file` (`base_dir` anchors the injected
/// `ref`s). This is what lets one test suite exercise a discretization-agnostic
/// PDE leaf under several schemes with no conflict between tests. Mirrors the
/// Julia reference (`inline_tests.jl` `_ephemeral_injected_file`).
pub fn ephemeral_injected_file(
    file: &EsmFile,
    source_path: Option<&Path>,
    model_name: &str,
    imports: &[serde_json::Value],
    base_dir: &Path,
) -> Result<EsmFile, crate::EsmError> {
    let mut raw: serde_json::Value = match source_path {
        Some(p) => {
            let s = std::fs::read_to_string(p).map_err(|e| {
                crate::EsmError::SchemaValidation(format!("failed to read {}: {e}", p.display()))
            })?;
            serde_json::from_str(&s).map_err(crate::EsmError::JsonParse)?
        }
        None => serde_json::to_value(file).map_err(crate::EsmError::JsonParse)?,
    };
    let mut injected = false;
    if let Some(root) = raw.as_object_mut() {
        for kind in ["models", "reaction_systems"] {
            let Some(comps) = root.get_mut(kind).and_then(|v| v.as_object_mut()) else {
                continue;
            };
            let Some(comp) = comps.get_mut(model_name).and_then(|v| v.as_object_mut()) else {
                continue;
            };
            let mut base: Vec<serde_json::Value> = comp
                .get("expression_template_imports")
                .and_then(|v| v.as_array())
                .cloned()
                .unwrap_or_default();
            base.extend(imports.iter().cloned());
            comp.insert(
                "expression_template_imports".to_string(),
                serde_json::Value::Array(base),
            );
            injected = true;
            break;
        }
    }
    if !injected {
        return Err(crate::EsmError::SchemaValidation(format!(
            "component '{model_name}' not found for per-test injection (esm-spec §9.7.10)"
        )));
    }
    let text = serde_json::to_string(&raw).map_err(crate::EsmError::JsonParse)?;
    let options = crate::parse::LoadOptions {
        base_path: Some(base_dir.to_path_buf()),
        metaparameters: std::collections::BTreeMap::new(),
    };
    crate::parse::load_string_with_options(&text, &options)
}

/// The [`SolveOptions::output_observed`] request one test needs: the OBSERVED
/// variables its assertions read, in both the local and the model-qualified
/// spelling, deduplicated in first-seen order.
///
/// esm-spec §6.6.5 admits ANY shaped variable in a `coords` / `reduce`
/// assertion, so both ranks are requested here:
///
/// * a POINTWISE assertion (neither `coords` nor `reduce`) reads a 0-D
///   observed, which has no ODE slot and becomes one trajectory row;
/// * a `coords` / `reduce` assertion reads an ARRAY observed, which the array
///   runtime emits as one row per cell when — and only when — it is REQUESTED
///   (`append_observed_trajectories`). Without the request a STATE-DEPENDENT
///   array observed was unassertable: it is absent from the build inspection's
///   `setup_arrays` by construction (only the state-free ones hoist there), so
///   [`observed_field`] could not answer it either and every such assertion
///   errored with "has no cells in var_map".
///
/// Kept to exactly what will be read, because naming something here is not
/// free: a requested array observed joins the output-node dependency cone. So a
/// declared variable that is NOT an observed — a state, whose row the
/// trajectory already carries, or a parameter — is left out, and so is one
/// whose declared rank does not match the assertion form. A name this component
/// does not declare at all is kept as a best effort: its class is not knowable
/// here, and a name resolving to no observed is dropped downstream. A scoped
/// reference is classified against the component it names
/// (`resolve_asserted_name`).
fn assertion_observed_requests(
    file: &EsmFile,
    model_name: &str,
    t: &crate::types::ModelTest,
) -> Vec<String> {
    let own = model_at(file, model_name);
    let own_class = own
        .as_deref()
        .map(crate::classification::Classification::of);
    let mut out: Vec<String> = Vec::new();
    for a in &t.assertions {
        let (owner, local) = resolve_asserted_name(file, model_name, &a.variable);
        let scoped = if owner == model_name {
            None
        } else {
            model_at(file, &owner)
        };
        let scoped_class = scoped
            .as_deref()
            .map(crate::classification::Classification::of);
        let (model, class) = if owner == model_name {
            (own.as_deref(), own_class.as_ref())
        } else {
            (scoped.as_deref(), scoped_class.as_ref())
        };
        // A `coords` / `reduce` assertion reads a FIELD, a pointwise one a
        // scalar; the declared rank must match the form that reads it.
        let wants_array = a.coords.is_some() || a.reduce.is_some();
        if let Some(v) = model.and_then(|m| m.variables.get(local)) {
            let is_array = v.shape.as_ref().is_some_and(|s| !s.is_empty());
            if is_array != wants_array {
                continue;
            }
            if !class.is_some_and(|c| c.is_observed(local)) {
                continue;
            }
        } else if wants_array {
            // An undeclared name can only be resolved downstream, and the
            // array form has a cheaper answer available: a scoped reference is
            // read through `state_cells` / `observed_field` as before.
            continue;
        }
        // A SCOPED name is requested only under a spelling its owner can hold
        // ([`owner_spellings`]); the raw `a.variable` is relative to the
        // asserting component and names nothing the build knows.
        let spellings: Vec<String> = if owner == model_name {
            vec![a.variable.clone(), format!("{model_name}.{}", a.variable)]
        } else {
            owner_spellings(file, &owner)
                .into_iter()
                .map(|m| format!("{m}.{local}"))
                .collect()
        };
        for spelling in spellings {
            if !out.contains(&spelling) {
                out.push(spelling);
            }
        }
    }
    out
}

/// Record `message` as an ERROR verdict for EVERY assertion of `t`.
///
/// A failure that happens BEFORE any assertion can be evaluated — the per-test
/// discretization injection, or the document's data ingest — belongs to the
/// whole test, and reporting it once per assertion is what keeps the summary's
/// assertion count equal to the number of assertions the document declares
/// however the test failed.
fn push_test_error(
    results: &mut Vec<AssertionResult>,
    source: &str,
    model_name: &str,
    t: &crate::types::ModelTest,
    tolerance: Option<&Tolerance>,
    message: &str,
) {
    for (i, a) in t.assertions.iter().enumerate() {
        let (rtol, atol) = resolve_tolerance(tolerance, t.tolerance.as_ref(), a.tolerance.as_ref());
        results.push(AssertionResult {
            model: model_name.to_string(),
            test_id: t.id.clone(),
            assertion_idx: i + 1,
            variable: a.variable.clone(),
            time: a.time,
            reduce: a.reduce.clone(),
            expected: a.expected,
            actual: None,
            rtol,
            atol,
            passed: false,
            message: message.to_string(),
            file: source.to_string(),
        });
    }
}

/// The empty trajectory a BUILD-ONLY document is asserted against: the asserted
/// times, no state rows, and a successful retcode.
///
/// A document with no differential equations has nothing to integrate, so
/// `solve` correctly refuses it. Its answers are the build pipeline's
/// materialized fields, which `eval_assertion` reaches through the no-ODE-slot
/// branch — that branch needs a `Solution` only for the time index, which is
/// exactly what this carries.
fn build_only_solution(times: Vec<f64>) -> Solution {
    Solution {
        time: times,
        state: Vec::new(),
        state_variable_names: Vec::new(),
        retcode: crate::simulate::ReturnCode::Success,
        metadata: crate::simulate::SolutionMetadata {
            alg: "build".to_string(),
            ..Default::default()
        },
    }
}

/// The observeds of `model` whose value is a function of `t` — DIRECTLY,
/// because the defining body mentions the independent variable free, or
/// TRANSITIVELY, because it reads one that does.
///
/// Used by [`unevaluable_time_dependent_assertion`] to tell a field the build
/// materialized once, at `tspan.0`, and which is therefore the answer at every
/// time, apart from one whose value moves and whose build-time materialization
/// is only the answer at the start of the span.
///
/// Only `y ~ f(…)` definitions are walked ([`crate::classification::LhsForm`]
/// calls that shape `Bare`): an ODE state is not read from a build field at
/// all, and an implicit constraint defines no single name.
#[cfg_attr(target_arch = "wasm32", allow(dead_code))]
fn time_dependent_observeds(model: &Model) -> std::collections::BTreeSet<String> {
    let bodies: Vec<(String, &Expr)> = model
        .equations
        .iter()
        .filter_map(|eq| match crate::classification::lhs_form(&eq.lhs) {
            crate::classification::LhsForm::Bare(name) => Some((name, &eq.rhs)),
            _ => None,
        })
        .collect();
    let mut dependent: std::collections::BTreeSet<String> = std::collections::BTreeSet::new();
    // Fixpoint over the read-graph. Each pass adds at least one name or stops,
    // so it runs at most `bodies.len() + 1` times.
    loop {
        let before = dependent.len();
        for (name, body) in &bodies {
            if dependent.contains(name) {
                continue;
            }
            if mentions_free(body, TIME_VARIABLE)
                || dependent.iter().any(|d| mentions_free(body, d))
            {
                dependent.insert(name.clone());
            }
        }
        if dependent.len() == before {
            return dependent;
        }
    }
}

/// The refusal for an assertion this runner cannot answer on a document with
/// **nothing to integrate** whose observeds the array runtime materialized at
/// BUILD time — `None` when every assertion of `t` is answerable.
///
/// The build evaluates a state-free field once, at `tspan.0`. For a field that
/// is not a function of `t` that single value IS the answer at every asserted
/// time, and [`build_only_solution`] serves it. For one that IS a function of
/// `t`, it is the answer only at the start of the span.
///
/// The ordinary answer for a state-free document is
/// [`crate::problem::static_observed_graph`], which evaluates the observed
/// graph at each asserted time and needs none of this. This guard covers what
/// is left: a document with nothing to integrate whose observeds are not a
/// scalar graph — a shaped or data-ingesting one, whose content IS its
/// build-time fields. Answering a `t`-dependent assertion out of those fields
/// would report the value at `tspan.0` for a question asked at another time,
/// which is exactly the outcome issue #406 is about, so it is refused by name
/// instead.
#[cfg_attr(target_arch = "wasm32", allow(dead_code))]
fn unevaluable_time_dependent_assertion(
    file: &EsmFile,
    model_name: &str,
    t: &crate::types::ModelTest,
) -> Option<String> {
    let t0 = t.time_span.start;
    let mut per_owner: HashMap<String, std::collections::BTreeSet<String>> = HashMap::new();
    for a in &t.assertions {
        if (a.time - t0).abs() <= 1e-9 * f64::max(1.0, t0.abs()) {
            continue;
        }
        let (owner, variable) = resolve_asserted_name(file, model_name, &a.variable);
        let dependent = per_owner.entry(owner.clone()).or_insert_with(|| {
            model_at(file, &owner)
                .map(|m| time_dependent_observeds(&m))
                .unwrap_or_default()
        });
        if dependent.contains(variable) {
            return Some(format!(
                "'{}' is a function of `t`, and this document has nothing to integrate: \
                 its fields were materialized once, at t = {t0}, so this test's assertion \
                 on it at t = {} cannot be answered. Assert it at t = {t0}, or give the \
                 model a differential equation so the observed is carried along a \
                 trajectory (esm-spec §6.6.3; issue #406)",
                a.variable, a.time
            ));
        }
    }
    None
}

/// The times a document with **nothing to integrate** is evaluated at: the
/// asserted times that lie inside the declared span, plus the span's own
/// endpoints.
///
/// esm-spec §6.6.3 constrains an assertion's `time` to
/// `[time_span.start, time_span.end]`. An INTEGRATED document enforces that
/// incidentally — the trajectory stops at the span's end, so an assertion past
/// it reports `no saved state at t=… (nearest …)` — and Python's runner, which
/// samples a dense grid over the span, reports the same for a static document.
/// A static evaluation has no such boundary of its own: evaluating the observed
/// graph at whatever number the assertion names would answer `t = 100` on a
/// span of `[0, 1]` and report a PASS, which is the plausible-wrong-number
/// outcome issue #406 is about reached one road further on, and it would put
/// this binding on a different verdict from Python for one document.
///
/// The span's endpoints are kept whatever the assertions say, for two reasons:
/// the refusal then names the span (`nearest 1`) instead of an empty
/// trajectory, and a test whose assertions are ALL out of span — or which has
/// no assertions at all — still produces a well-formed evaluation rather than
/// falling through to the integrator this function exists to keep a state-free
/// document away from.
fn static_evaluation_times(saveat: &[f64], start: f64, end: f64) -> Vec<f64> {
    let (lo, hi) = if start <= end {
        (start, end)
    } else {
        (end, start)
    };
    let mut out: Vec<f64> = saveat
        .iter()
        .copied()
        .filter(|t| *t >= lo && *t <= hi)
        .collect();
    out.push(lo);
    out.push(hi);
    out.sort_by(f64::total_cmp);
    out.dedup();
    out
}

/// The §6.6 answer for a document with **nothing to integrate**: its observed
/// graph evaluated once per asserted time, laid out as a trajectory so the
/// ordinary assertion machinery reads it unchanged.
///
/// This is the path `esm simulate` already takes — a document with no
/// differential equations is EVALUATED rather than solved (`✓ Static
/// evaluation complete: N field(s)`) — reached here through the primitive that
/// command's own static path runs, the array runtime's stateless evaluation
/// ([`crate::problem::evaluate_static_observeds_over`]).
/// Before issue #406 the runner had no such branch: it handed the compiled,
/// STATE-FREE right-hand side to diffsol, which reported "Exceeded maximum
/// number of nonlinear solver failures (51) at time = 0" for a document that
/// `simulate` evaluates perfectly well. A model that simulates could not be
/// tested, and the diagnostic named the nonlinear solver rather than the real
/// condition.
///
/// A SHAPED state-free document is not answered here
/// ([`crate::problem::static_observed_graph`] is `None` for it): its answers
/// are the fields its build materialized.
///
/// **Why one evaluation PER TIME rather than one at `t = 0`.** esm-spec §6.6.3
/// defines an assertion's `time` as "Simulation time at which to evaluate the
/// assertion; must lie in `[time_span.start, time_span.end]`" — it constrains
/// the value, it does not restrict it to the span's start, and it says
/// *evaluate*, not *integrate to*. An algebraic document is still a function of
/// `t`; the diurnal solar-geometry component that found this bug is nothing
/// else. Evaluating the whole span's assertions at `t = 0` would answer a
/// question the author did not ask, and Python's runner — which has never had
/// this defect — already answers `a*t` at `t = 5` with `10`, so refusing the
/// assertion instead would put two bindings on different answers for one
/// document, which §6.6 does not admit.
///
/// `None` when the problem has a state vector: then it integrates, and
/// [`solve`] produces the answer.
#[cfg(not(target_arch = "wasm32"))]
fn static_trajectory(prob: &EsmProblem, times: &[f64]) -> Option<Result<Solution, String>> {
    // Whether this path applies is a property of the DOCUMENT, not of `t`, so
    // the graph is resolved once and evaluated per time. Once it has resolved,
    // a later failure is an evaluation failure and is REPORTED: falling back to
    // `solve` there would hand a state-free right-hand side to the integrator
    // and report a nonlinear-solver failure instead, which is the substitution
    // this function exists to remove.
    let graph = crate::problem::static_observed_graph(prob)?;
    if times.is_empty() {
        return None;
    }
    let rows = match crate::problem::evaluate_static_observeds_over(prob, &graph, times) {
        Ok(rows) => rows,
        Err(e) => return Some(Err(format!("simulate failed: {e}"))),
    };
    let (state_variable_names, state): (Vec<String>, Vec<Vec<f64>>) = rows.into_iter().unzip();
    Some(Ok(Solution {
        time: times.to_vec(),
        state,
        state_variable_names,
        retcode: crate::simulate::ReturnCode::Success,
        // The same `alg` the CLI's own static evaluation reports, so the two
        // spellings of this path are one word in a result.
        metadata: crate::simulate::SolutionMetadata {
            alg: "static".to_string(),
            ..Default::default()
        },
    }))
}

/// On wasm32 the array runtime's state-free evaluation is native-only, so a
/// document with nothing to integrate goes to [`solve`] instead.
#[cfg(target_arch = "wasm32")]
fn static_trajectory(_prob: &EsmProblem, _times: &[f64]) -> Option<Result<Solution, String>> {
    None
}

/// Everything ONE inline test's BUILD depends on, within one
/// [`run_model_tests`] call.
///
/// Derived by reading the loop body rather than by listing plausible fields.
/// The build is `esm_problem(run_file, tspan, popts)`, and inside a single call
/// to [`run_model_tests`] the document (`file`), the component (`model_name`),
/// the `base_dir` and the provider FACTORY are all fixed. What a test can vary
/// is therefore exactly four things:
///
/// * `expression_template_imports` — the only input [`ephemeral_injected_file`]
///   reads off the test, hence the only thing that can make `run_file` differ
///   from `file`;
/// * `time_span` — passed straight through as the problem's `tspan` (and, via
///   `tspan.0`, the CONST-provider sample time);
/// * `parameter_overrides` → [`ProblemOptions::p`];
/// * `initial_conditions` → [`ProblemOptions::u0`].
///
/// Every other `ProblemOptions` field the loop sets is loop-invariant:
/// `inspect: true`, `compile` chosen solely from `build_providers.is_some()`,
/// `build_pipeline` likewise, and `..Default::default()` for the rest
/// (`model_name: None`, no metaparameters, no `base_path`, no callbacks, no
/// run-time `providers`, no `const_arrays`, no `sample_time`).
///
/// A test's `assertions` and `tolerance` are deliberately ABSENT: they feed the
/// SOLVE (`saveat`, `output_observed`) and the assertion check, never the
/// build. That is why the solve is still run per test even on a memo hit —
/// only the build is reused.
///
/// Bindings are keyed by their JSON spelling, which is conservative in the safe
/// direction: an identical spelling is the same value and so the same build,
/// while two spellings of one value (`0.0` / `-0.0`, or a differently-nested
/// array) merely miss and rebuild.
///
/// `None` and `Some({})` collapse to the same empty binding list because
/// [`scope_to_component`] already maps both to an empty map.
#[derive(PartialEq)]
struct BuildKey {
    imports: Vec<serde_json::Value>,
    tspan: (u64, u64),
    p: Vec<(String, String)>,
    u0: Vec<(String, String)>,
}

impl BuildKey {
    fn of(t: &crate::types::ModelTest) -> Self {
        // A binding's value is either a scalar or inline array data (esm-spec
        // §6.6.2), so the key carries its JSON spelling rather than one f64's
        // bits. `serde_json` renders an f64 with the shortest round-tripping
        // form, so two keys compare equal exactly when the values do.
        fn bindings(m: Option<&HashMap<String, InlineValue>>) -> Vec<(String, String)> {
            let mut v: Vec<(String, String)> = m
                .map(|m| {
                    m.iter()
                        .map(|(k, x)| (k.clone(), serde_json::to_string(x).unwrap_or_default()))
                        .collect()
                })
                .unwrap_or_default();
            v.sort();
            v
        }
        BuildKey {
            imports: t.expression_template_imports.clone(),
            tspan: (t.time_span.start.to_bits(), t.time_span.end.to_bits()),
            p: bindings(t.parameter_overrides.as_ref()),
            u0: bindings(t.initial_conditions.as_ref()),
        }
    }
}

/// What building one test's problem produced — reusable by the next test whose
/// [`BuildKey`] matches.
enum Built {
    /// The problem to solve.
    Problem(Box<EsmProblem>),
    /// Every assertion of the test is an ERROR carrying this message: the
    /// per-test discretization injection failed, or the document's
    /// `data_sources` could not be read, so the numbers were never available.
    TestError(String),
    /// `esm_problem` itself failed; reported exactly as a solve failure is.
    BuildFailed(String),
}

/// The `(p, u0, compiler)` a test's problem was built from: the scalar
/// parameter overrides and the scalar initial conditions, on the canonical
/// SciML channels, and the compiler the caller named. Kept so a build can be
/// redone from exactly the same bindings ([`build_pipeline_fields`]) — the
/// compiler included, because a retry on a compiler the caller did not name
/// would answer the test from an evaluation that compiler never gated.
type RetryBindings = (
    HashMap<String, f64>,
    HashMap<String, f64>,
    Option<crate::problem::Compiler>,
);

/// The fields one build MATERIALIZED, in the order they were produced: the
/// `(name, array)` pairs `observed_field` reads back
/// ([`build_pipeline_fields`]).
type BuiltFields = Vec<(String, ndarray::ArrayD<f64>)>;

/// The memoised build of one model's tests: the key it was built for, the
/// ephemeral document (if the key called for one), its index sets, and the
/// result.
struct BuiltModel {
    key: BuildKey,
    /// `None` when the test declared no `expression_template_imports` and so
    /// ran against `file` as loaded.
    ephemeral: Option<EsmFile>,
    index_sets: Option<HashMap<String, IndexSet>>,
    built: Built,
    /// The `(p, u0)` this problem was built from, kept so the build can be
    /// REDONE with the build pipeline on if — and only if — nothing else can
    /// answer the test ([`build_pipeline_fields`]).
    ///
    /// `None` when the document ingests `data_sources`: that build asks for
    /// the pipeline itself, so there is nothing to retry.
    #[cfg_attr(target_arch = "wasm32", allow(dead_code))]
    retry_bindings: Option<RetryBindings>,
    /// What that retry produced, computed at most ONCE per [`BuildKey`]
    /// ([`BuiltModel::retry_fields`]).
    #[cfg_attr(target_arch = "wasm32", allow(dead_code))]
    retry_fields: OnceCell<Option<BuiltFields>>,
}

impl BuiltModel {
    /// The fields a build with the pipeline on materializes for the tests that
    /// share this [`BuildKey`] — the LAST-RESORT answer
    /// ([`build_pipeline_fields`]) — computed on first demand and then reused.
    ///
    /// A whole second document build per test is what the reuse is for: the
    /// retry sits inside the per-test loop, so a document with N tests that
    /// all reach the dead end would otherwise pay N builds where one answers
    /// all N. Reuse is sound because every input to the retry is fixed by the
    /// key: `tspan` and the `(p, u0)` bindings are what the key IS
    /// ([`BuildKey`]), and `run_file` is this `BuiltModel`'s own `ephemeral`.
    ///
    /// A retry that FAILS caches its failure, as `None`. That is not a cached
    /// success: the caller finds no fields and reports the diagnostic `solve`
    /// gave THIS test, which is the property issue #432's fix rests on. Nor is
    /// it retried — a build that fails for the key fails for every test
    /// sharing it, and a second whole-document build is too expensive to spend
    /// on learning that again.
    #[cfg(not(target_arch = "wasm32"))]
    fn retry_fields(&self, run_file: &EsmFile, tspan: (f64, f64)) -> Option<&BuiltFields> {
        self.retry_fields
            .get_or_init(|| build_pipeline_fields(run_file, tspan, self.retry_bindings.as_ref()))
            .as_ref()
    }
}

/// Partition an override map into `(scalars, document-channel values)` — the
/// two value shapes esm-spec §6.6.2 admits for a `parameter_overrides` /
/// `initial_conditions` entry, plus the keys `shaped` claims for the document
/// channel whatever their own value shape (a shaped parameter, whose scalar is
/// a §6.3 broadcast the scalar `p` vector cannot carry).
fn split_inline_arrays(
    overrides: HashMap<String, InlineValue>,
    shaped: impl Fn(&str) -> bool,
) -> (HashMap<String, f64>, HashMap<String, InlineValue>) {
    let mut scalars = HashMap::new();
    let mut arrays = HashMap::new();
    for (k, v) in overrides {
        match v.as_scalar() {
            Some(x) if !shaped(&k) => {
                scalars.insert(k, x);
            }
            _ => {
                arrays.insert(k, v);
            }
        }
    }
    (scalars, arrays)
}

/// The NAMES of the model a (possibly dot-qualified) override key resolves
/// against and of the key's LOCAL variable within it. `None` when no model of
/// `file` declares it.
fn resolve_override_target(file: &EsmFile, key: &str) -> Option<(String, String)> {
    let models = file.models.as_ref()?;
    // Longest dotted prefix that names a model wins, so `M.sub.p` binds
    // `sub.p` inside `M` rather than a bare `p` anywhere.
    let mut split: Option<(String, String)> = None;
    let mut best = 0usize;
    for (mname, model) in models.iter() {
        if let Some(rest) = key.strip_prefix(&format!("{mname}."))
            && mname.len() > best
            && model.variables.contains_key(rest)
        {
            best = mname.len();
            split = Some((mname.clone(), rest.to_string()));
        }
    }
    split.or_else(|| {
        models
            .iter()
            .find(|(_, m)| m.variables.contains_key(key))
            .map(|(n, _)| (n.clone(), key.to_string()))
    })
}

/// The model a (possibly dot-qualified) override key names, plus the key's
/// LOCAL variable name within it. `None` when no model of `file` declares it.
fn locate_override_target<'a>(file: &'a mut EsmFile, key: &str) -> Option<(&'a mut Model, String)> {
    // Resolve the (model, local name) pair against an IMMUTABLE view first, so
    // the single mutable borrow below is the one the caller keeps.
    let target = resolve_override_target(file, key)?;
    let model = file.models.as_mut()?.get_mut(&target.0)?;
    Some((model, target.1))
}

/// True iff `key` names a SHAPED parameter of `file`.
///
/// A shaped parameter's value lives on the document's own array channel
/// whatever its VALUE shape, because esm-spec §6.3 gives a scalar on a shaped
/// variable the broadcast meaning — one value over every element — which the
/// positional scalar `p` vector cannot carry. So an override of one is bound by
/// [`bind_array_parameters`] rather than split off as a `p` entry.
fn names_shaped_parameter(file: &EsmFile, key: &str) -> bool {
    let Some((mname, local)) = resolve_override_target(file, key) else {
        return false;
    };
    file.models
        .as_ref()
        .and_then(|ms| ms.get(&mname))
        .and_then(|m| m.variables.get(&local))
        .is_some_and(|v| {
            v.var_type == crate::types::VariableType::Parameter
                && v.shape.as_ref().is_some_and(|s| !s.is_empty())
        })
}

/// Write each SHAPED parameter override onto the run document as that
/// parameter's `default` (esm-spec §6.6.2: an override supplies the value the
/// declared default would otherwise supply). The value is inline array data or
/// a scalar; §6.3 gives both the same channel on a shaped variable.
///
/// `file` is the EPHEMERAL run instance, never the persisted document, so this
/// is a per-run binding and not an edit. The array compile then lowers the
/// shaped parameter into its `const` observed
/// ([`crate::simulate_array`]'s `lower_inline_array_parameters`), which is where
/// a scalar is broadcast and the declared-shape check reports a mismatch.
fn bind_array_parameters(
    file: &mut EsmFile,
    arrays: &HashMap<String, InlineValue>,
) -> Result<(), String> {
    let mut keys: Vec<&String> = arrays.keys().collect();
    keys.sort();
    for key in keys {
        let value = &arrays[key];
        let Some((model, local)) = locate_override_target(file, key) else {
            return Err(format!(
                "parameter_overrides: unknown parameter '{key}' — this document declares no such \
                 variable. esm-spec §6.6.2 keys parameter_overrides by LOCAL parameter name."
            ));
        };
        let var = model
            .variables
            .get_mut(&local)
            .expect("locate_override_target returned a declared name");
        if var.var_type != crate::types::VariableType::Parameter {
            return Err(format!(
                "parameter_overrides: '{key}' is an unknown, not a parameter (esm-spec §6.6.2)"
            ));
        }
        var.default = Some(value.clone());
    }
    Ok(())
}

/// Expand each INLINE ARRAY initial condition into one `u0` entry per grid cell.
///
/// The state vector is keyed by ELEMENT name (`u[1]`, `u[2,3]`, … — 1-based,
/// column-major over the declared shape), so a whole profile becomes that many
/// scalar entries and needs no new channel. The authored array is ROW-major
/// (JSON nesting order), so each cell's value is read at its own multi-index
/// rather than by position — the two orders coincide only in rank 1.
///
/// A scalar entry already present for the same element WINS: it was authored
/// per-element and is the more specific binding.
fn expand_array_initial_conditions(
    file: &EsmFile,
    arrays: &HashMap<String, InlineValue>,
    u0: &mut HashMap<String, f64>,
) -> Result<(), String> {
    let index_sets: HashMap<String, IndexSet> = file
        .index_sets
        .clone()
        .unwrap_or_default()
        .into_iter()
        .collect();
    let mut keys: Vec<&String> = arrays.keys().collect();
    keys.sort();
    for key in keys {
        let (shape, values) = arrays[key]
            .to_dense()
            .map_err(|e| format!("initial_conditions[{key}]: {e} (esm-spec §6.3)"))?;
        let declared = declared_extents(file, key, &index_sets);
        if let Some(want) = declared.as_ref()
            && *want != shape
        {
            return Err(format!(
                "initial_conditions[{key}]: inline array data has shape {shape:?}, which does not \
                 match the declared shape {want:?} (esm-spec §6.6.2 — the array MUST match the \
                 variable's declared shape after metaparameter folding)"
            ));
        }
        if shape.is_empty() {
            return Err(format!(
                "initial_conditions[{key}]: inline array data was supplied for a 0-D state; only a \
                 SHAPED unknown takes a nested array (esm-spec §6.6.2)"
            ));
        }
        for (flat, value) in values.iter().enumerate() {
            // Row-major decode: the authored nesting's own order.
            let mut rest = flat;
            let mut multi = vec![0usize; shape.len()];
            for d in (0..shape.len()).rev() {
                multi[d] = rest % shape[d];
                rest /= shape[d];
            }
            let idx = multi
                .iter()
                .map(|i| (i + 1).to_string())
                .collect::<Vec<_>>()
                .join(",");
            u0.entry(format!("{key}[{idx}]")).or_insert(*value);
        }
    }
    Ok(())
}

/// The integer extents of the variable `key` names, resolved from its declared
/// `shape` against the document's index-set registry. `None` when the variable
/// or an axis does not resolve — the caller then accepts the array as authored
/// and lets the build report any real mismatch.
fn declared_extents(
    file: &EsmFile,
    key: &str,
    index_sets: &HashMap<String, IndexSet>,
) -> Option<Vec<usize>> {
    let models = file.models.as_ref()?;
    let local = key.rsplit('.').next().unwrap_or(key);
    let var = models
        .iter()
        .find_map(|(_, m)| m.variables.get(key).or_else(|| m.variables.get(local)))?;
    let shape = var.shape.as_ref()?;
    let mut out = Vec::with_capacity(shape.len());
    for axis in shape {
        let set = index_sets.get(axis)?;
        let size = match set.kind.as_str() {
            "interval" => usize::try_from(set.size?).ok()?,
            "categorical" => set.members.as_ref()?.len(),
            _ => return None,
        };
        out.push(size);
    }
    Some(out)
}

/// Build one test's problem — the body that used to be inline in
/// [`run_model_tests`]'s loop, lifted out so the loop can skip it on a
/// [`BuildKey`] hit.
fn build_for_test(
    key: BuildKey,
    file: &EsmFile,
    model_name: &str,
    t: &crate::types::ModelTest,
    base_dir: Option<&Path>,
    build_providers: Option<&BuildProviderFactory<'_>>,
    seeds: &InlineTestSeeds,
) -> BuiltModel {
    // esm-spec §9.7.10 form C: a test that injects a discretization runs
    // against an EPHEMERAL instance of this component with the test's
    // imports appended to its scope and its rewrite-targets lowered; the
    // persisted `file` is untouched. A test with no injection runs against
    // the file as loaded.
    let (ephemeral, index_sets) = if t.expression_template_imports.is_empty() {
        (None, None)
    } else {
        match ephemeral_injected_file(
            file,
            None,
            model_name,
            &t.expression_template_imports,
            base_dir.unwrap_or_else(|| Path::new(".")),
        ) {
            Ok(f) => {
                let is: HashMap<String, IndexSet> = f
                    .index_sets
                    .clone()
                    .unwrap_or_default()
                    .into_iter()
                    .collect();
                (Some(f), Some(is))
            }
            Err(e) => {
                return BuiltModel {
                    key,
                    ephemeral: None,
                    index_sets: None,
                    built: Built::TestError(format!(
                        "per-test discretization injection failed: {e}"
                    )),
                    retry_bindings: None,
                    retry_fields: OnceCell::new(),
                };
            }
        }
    };
    let mut ephemeral = ephemeral;
    let run_file: &EsmFile = ephemeral.as_ref().unwrap_or(file);

    let seeded_params = seeds.lay_under(&seeds.parameter_overrides, t.parameter_overrides.as_ref());
    let seeded_ics = seeds.lay_under(&seeds.initial_conditions, t.initial_conditions.as_ref());
    let params = scope_to_component(seeded_params.as_ref(), model_name, run_file);
    let ics = scope_to_component(seeded_ics.as_ref(), model_name, run_file);
    // Split each override map by the channel that can carry it (esm-spec
    // §6.6.2). A scalar goes on the canonical SciML `p` / `u0` channel
    // unchanged; a whole column needs one that can hold it:
    //
    //   * a shaped PARAMETER's value is written onto an EPHEMERAL copy of the
    //     run document as that parameter's `default`, which the array compile
    //     then lowers into its `const` observed ([`lower_inline_array_parameters`]).
    //     The persisted document is untouched — this is the same ephemeral
    //     instance a §9.7.10 discretization injection runs against. EVERY
    //     override of a shaped parameter takes this route, scalar included: §6.3
    //     makes a scalar on a shaped variable a BROADCAST over the whole grid,
    //     which is what the lowering materializes and what the one-f64 `p` slot
    //     cannot express;
    //   * a shaped UNKNOWN's profile is expanded into one `u0` entry per grid
    //     cell (`u[1]`, `u[2]`, …), the element names the state vector is keyed
    //     by, so no new initial-condition channel is needed at all. A scalar `u0`
    //     entry stays a scalar: the state vector's per-cell seeding already
    //     broadcasts it.
    let (scalar_params, array_params) =
        split_inline_arrays(params, |k| names_shaped_parameter(run_file, k));
    let (scalar_ics, array_ics) = split_inline_arrays(ics, |_| false);
    if !array_params.is_empty() {
        let mut owned = ephemeral.take().unwrap_or_else(|| file.clone());
        if let Err(e) = bind_array_parameters(&mut owned, &array_params) {
            return BuiltModel {
                key,
                ephemeral: None,
                index_sets: None,
                built: Built::BuildFailed(format!("simulate failed: {e}")),
                retry_bindings: None,
                retry_fields: OnceCell::new(),
            };
        }
        ephemeral = Some(owned);
    }
    let run_file: &EsmFile = ephemeral.as_ref().unwrap_or(file);
    let mut u0 = scalar_ics;
    if !array_ics.is_empty()
        && let Err(e) = expand_array_initial_conditions(run_file, &array_ics, &mut u0)
    {
        return BuiltModel {
            key,
            ephemeral,
            index_sets,
            built: Built::BuildFailed(format!("simulate failed: {e}")),
            retry_bindings: None,
            retry_fields: OnceCell::new(),
        };
    }
    // Kept so the build can be REDONE with the build pipeline
    // ([`build_pipeline_fields`]); two small maps, against a build either of
    // them feeds. Only when there are no data-source providers — that branch
    // asks for the pipeline itself, just below.
    let retry_bindings = build_providers
        .is_none()
        .then(|| (scalar_params.clone(), u0.clone(), seeds.compiler));
    // Only the native provider branch below writes to it.
    #[cfg_attr(target_arch = "wasm32", allow(unused_mut))]
    let mut popts = ProblemOptions {
        p: scalar_params,
        u0,
        inspect: true,
        rhs: crate::problem::Rhs::Always,
        compiler: seeds.compiler,
        ..Default::default()
    };
    // The document's own `data_sources`, ingested (esm-spec §8.9). A
    // failure here is NOT a solve failure and must not be reported as one:
    // it means the numbers the test asserts on were never read, so every
    // assertion of this test is an ERROR naming the source.
    #[cfg(target_arch = "wasm32")]
    if build_providers.is_some() {
        return BuiltModel {
            key,
            ephemeral,
            index_sets,
            built: Built::TestError(
                "data-source providers need the build pipeline, which is native-only".to_string(),
            ),
            retry_bindings,
            retry_fields: OnceCell::new(),
        };
    }
    #[cfg(not(target_arch = "wasm32"))]
    if let Some(make) = build_providers {
        match make() {
            Ok(provs) => {
                popts.build_providers = provs;
                popts.build_pipeline = true;
                // `Always` on a document with no differential equations
                // compiles a right-hand side that has nothing to integrate.
                // With the build pipeline bound, that document's whole
                // content IS its build-time observed graph, so let the
                // backend fall out of the document (`Auto`) and read the
                // fields the build materialized.
                popts.rhs = crate::problem::Rhs::Auto;
            }
            Err(e) => {
                return BuiltModel {
                    key,
                    ephemeral,
                    index_sets,
                    built: Built::TestError(e),
                    retry_bindings: None,
                    retry_fields: OnceCell::new(),
                };
            }
        }
    }
    let tspan = (t.time_span.start, t.time_span.end);
    let built = match esm_problem(run_file, tspan, popts) {
        Ok(p) => Built::Problem(Box::new(p)),
        Err(e) => Built::BuildFailed(format!("simulate failed: {e}")),
    };
    BuiltModel {
        key,
        ephemeral,
        index_sets,
        built,
        retry_bindings,
        retry_fields: OnceCell::new(),
    }
}

// Whole-document builds `build_pipeline_fields` has started on this thread.
// What it exists to pin is that the last-resort retry is paid once per
// `BuildKey` and not once per test (`BuiltModel::retry_fields`).
//
// Per THREAD, not per process: the test harness gives each test its own
// thread, so a test reads only its own builds however many run beside it.
#[cfg(test)]
thread_local! {
    static BUILD_PIPELINE_BUILDS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
}

/// Build `run_file` ONE MORE TIME with the BUILD PIPELINE on, and hand back
/// the fields it materialized — the LAST RESORT for a test nothing else could
/// answer.
///
/// A SHAPED state-free document takes the ARRAY runtime under
/// `Rhs::Always` and carries no scalar observed graph, so
/// [`static_trajectory`] cannot serve it; when `solve` then refuses it too —
/// `Exceeded maximum number of nonlinear solver failures (51) at time = 0`,
/// issue #406's own diagnostic, on a document `esm simulate` evaluates without
/// complaint — the fields a build materializes are the only answer left, and
/// they are the ones `esm simulate` reports (`ProblemOptions::build_pipeline`,
/// read back through `observed_field`).
///
/// **Called only after the ordinary paths have failed** (issue #432). These
/// fields are not interchangeable with what `solve` returns: a build
/// materializes them ONCE, at `tspan.0`, through a different evaluator from
/// the one `solve` runs, so handing them back in preference to an answer the
/// array runtime already produced substitutes a value that is right only for a
/// quantity which does not move — silently, since nothing in the result says
/// where it came from — and charges every test a second whole-document build
/// besides. Answering from these fields is what a runner does when it has
/// nothing else, never in preference to an answer it already has.
///
/// `Rhs::Always` is kept: the compile is what still refuses a construct no
/// evaluator supports, in the `unsupported_construct` vocabulary esm-spec
/// §9.6.6 asks for. A rebuild that fails, or that materializes nothing, hands
/// back `None` and the caller reports the solve failure it already had —
/// this is an attempt to answer more, never a new way to fail.
///
/// Native-only: on wasm32 there is no build pipeline (`crate::prepare` is
/// native-only), and the runner arm that retries is compiled out with it.
#[cfg(not(target_arch = "wasm32"))]
fn build_pipeline_fields(
    run_file: &EsmFile,
    tspan: (f64, f64),
    bindings: Option<&RetryBindings>,
) -> Option<BuiltFields> {
    let (p, u0, compiler) = bindings?;
    let popts = ProblemOptions {
        p: p.clone(),
        u0: u0.clone(),
        inspect: true,
        rhs: crate::problem::Rhs::Always,
        build_pipeline: true,
        compiler: *compiler,
        ..Default::default()
    };
    #[cfg(test)]
    BUILD_PIPELINE_BUILDS.with(|n| n.set(n.get() + 1));
    let prob = esm_problem(run_file, tspan, popts).ok()?;
    let fields: BuiltFields = prob
        .observed_fields()
        .iter()
        .map(|(k, v)| (k.clone(), v.clone()))
        .collect();
    (!fields.is_empty()).then_some(fields)
}

/// Run every inline test of one COMPONENT, appending per-assertion results.
///
/// Takes the component's `tests` and `tolerance` rather than a `&Model`,
/// because esm-spec §6.6 hangs `tests` off `reaction_systems` too and both
/// drive this one body — the document is flattened either way, and a species
/// becomes an ordinary state.
///
/// `test_filter`, when given, selects the tests to RUN by the same
/// `id.contains(needle)` predicate the CLI's `--filter` used to apply to the
/// finished result rows. Applying it here is what makes the flag skip WORK
/// rather than only narrow the report; the surviving rows are identical either
/// way, because a result's `test_id` is always its test's `id`.
///
/// The build is memoised across CONSECUTIVE tests that share a [`BuildKey`]
/// (see there for how the key was derived and why it is complete). One slot,
/// not a map: a slot keeps at most one built problem — and its materialized
/// build fields — alive at a time, and over this project's documents the
/// consecutive form costs 47 builds against a full map's 44, for 200 tests.
/// The memo cannot change an answer it does not also change without it: the
/// key is compared exactly, the build is a pure function of the key plus the
/// loop-invariant context above, and the solve still runs per test.
///
/// The caller's `seeds` are part of that loop-invariant context: they come from
/// one [`InlineTestOptions`] for the whole DOCUMENT and so are constant across
/// the tests this loop memoises over. That is why they need not enter the
/// [`BuildKey`] — a key hit within one call is a hit under the same seeds.
// Ten parameters against clippy's seven. They are the loop-invariant context
// the build memo keys on, described above; bundling them into a struct would
// move the same values behind one more name without making any of them
// optional.
#[allow(clippy::too_many_arguments)]
fn run_component_tests(
    file: &EsmFile,
    source: &str,
    model_name: &str,
    tests: &[crate::types::ModelTest],
    tolerance: Option<&Tolerance>,
    index_sets: &HashMap<String, IndexSet>,
    opts: &SolveOptions,
    base_dir: Option<&Path>,
    build_providers: Option<&BuildProviderFactory<'_>>,
    test_filter: Option<&str>,
    seeds: &InlineTestSeeds,
    results: &mut Vec<AssertionResult>,
) {
    let mut memo: Option<BuiltModel> = None;
    for t in tests {
        if test_filter.is_some_and(|needle| !t.id.contains(needle)) {
            continue;
        }
        let key = BuildKey::of(t);
        if !memo.as_ref().is_some_and(|m| m.key == key) {
            // Drop the previous build BEFORE the next one is constructed, so
            // the slot never holds two documents' worth of materialized fields.
            drop(memo.take());
            memo = Some(build_for_test(
                key,
                file,
                model_name,
                t,
                base_dir,
                build_providers,
                seeds,
            ));
        }
        let cached = memo.as_ref().expect("just built");
        let run_file: &EsmFile = cached.ephemeral.as_ref().unwrap_or(file);
        let run_index_sets: &HashMap<String, IndexSet> =
            cached.index_sets.as_ref().unwrap_or(index_sets);
        if let Built::TestError(msg) = &cached.built {
            push_test_error(results, source, model_name, t, tolerance, msg);
            continue;
        }

        let mut times: Vec<f64> = t.assertions.iter().map(|a| a.time).collect();
        times.sort_by(f64::total_cmp);
        times.dedup();
        let mut run_opts = opts.clone();
        run_opts.saveat = Some(times);
        // esm-spec §6.6.3 / §6.6.5: an assertion reads an OBSERVED, and an
        // observed has no ODE slot. The array runtime exposes every 0-D
        // observed as a trajectory row unasked, but an ARRAY-valued one only
        // when it is REQUESTED. So the runner names them — exactly the
        // observeds this test's assertions read, at the rank the assertion
        // form reads them, and nothing else. Without this a STATE-DEPENDENT
        // array observed would be unassertable (the build inspection hoists
        // only the state-free ones).
        for name in assertion_observed_requests(run_file, model_name, t) {
            // Additive: a caller's own request stands.
            if !run_opts.output_observed.contains(&name) {
                run_opts.output_observed.push(name);
            }
        }
        // Build-observability sink: assertions on ARRAY OBSERVEDS (no ODE
        // slot) read their state-free materialized field from here
        // (`observed_field`).
        //
        // Build observability is now a CONSTRUCTION-time seam
        // (`ProblemOptions::inspect`), not a `&mut BuildInspection` threaded
        // through the run — the same move that gave `observed_field` one arity
        // in every binding.
        let mut insp = BuildInspection::default();
        let sim = match &cached.built {
            // Handled above; the `continue` there is the only exit.
            Built::TestError(msg) => Err(msg.clone()),
            Built::BuildFailed(msg) => Err(msg.clone()),
            Built::Problem(prob) => {
                // The build pipeline's own products, which `observed_field`
                // reads back for a §6.6.5 array assertion. Taken BEFORE the
                // solve so a state-free document — whose `solve` is a legitimate
                // `NotDynamic` — still answers its assertions.
                #[cfg_attr(target_arch = "wasm32", allow(unused_mut))]
                let mut fields: BuiltFields = prob
                    .observed_fields()
                    .iter()
                    .map(|(k, v)| (k.clone(), v.clone()))
                    .collect();
                // Re-arm the state a FRESHLY BUILT problem is in. Construction
                // leaves `inspection` empty, `solve` fills it only on the array
                // backend, and `take_inspection` DRAINS it — so without this a
                // reused problem would hand the second test whatever the first
                // left behind rather than what a rebuild would have produced.
                // A no-op on the first use of a build.
                prob.reset_inspection();
                let saveat = run_opts.saveat.clone().unwrap_or_default();
                // A document with NOTHING TO INTEGRATE is evaluated, not
                // solved — the path `esm simulate` has always taken and this
                // runner did not (issue #406). Checked BEFORE `solve`, because
                // the runner builds with `Rhs::Always` (so that a construct
                // no evaluator supports is still refused at build time, in the
                // `unsupported_construct` vocabulary §9.6.6 asks for) and a
                // forced right-hand side over an empty state vector reaches the
                // integrator rather than reporting `NotDynamic`.
                // Restricted to the declared span (esm-spec §6.6.3): a static
                // evaluation would otherwise answer an assertion at a time the
                // document never covers, which no integrating path admits and
                // Python's runner refuses.
                let static_times =
                    static_evaluation_times(&saveat, t.time_span.start, t.time_span.end);
                match static_trajectory(prob, &static_times) {
                    Some(result) => result,
                    None => match solve(prob, &run_opts) {
                        Ok(sol) => Ok(sol),
                        // A document with no ODEs never integrates; its answers
                        // are the build's, evaluated at the asserted times.
                        Err(crate::simulate::SimulateError::NotDynamic { .. }) => {
                            Ok(build_only_solution(saveat.clone()))
                        }
                        // Nothing to integrate, and no compiled observed graph
                        // to evaluate: the ARRAY runtime, which is what a
                        // SHAPED state-free document takes under
                        // `Rhs::Always`. What `solve` just reported is
                        // "Exceeded maximum number of nonlinear solver failures
                        // (51) at time = 0" — it handed a right-hand side over
                        // an empty state vector to the integrator — which is
                        // the diagnostic issue #406 was filed about, on a
                        // document `esm simulate` evaluates without complaint.
                        // Answer from the fields a BUILD materializes instead,
                        // except where that would substitute the value at
                        // `tspan.0` for a quantity that moves, which is refused
                        // by name rather than answered.
                        //
                        // LAST RESORT, and only here (issue #432): a retry is
                        // what a runner does when it has NO answer, never in
                        // preference to one it already has. Ahead of `solve`
                        // this arm substitutes a second build's fields for the
                        // array runtime's answers — a `min` reduction reads
                        // back its identity element, a tendency moves — and
                        // charges every test a whole extra build for the
                        // substitution.
                        // Native-only, like the evaluations it answers from.
                        #[cfg(not(target_arch = "wasm32"))]
                        Err(e) if crate::problem::has_nothing_to_integrate(prob) => {
                            // Whatever the refused solve latched is not an
                            // answer; the fields below are. Without this reset
                            // a half-filled `setup_arrays` would shadow them,
                            // because the merge below is `or_insert`.
                            prob.reset_inspection();
                            // The fields this build already carries (a
                            // data-ingesting document). Else, under a strict
                            // compiler, the ones this problem's OWN compiled
                            // model evaluates over its empty state — the tape
                            // under `native` — because a pipeline rebuild would
                            // answer through the reference evaluator, which is
                            // the route such a compiler refuses to take. Else
                            // the ones a build with the pipeline on can
                            // materialize, on the same compiler: at most ONE
                            // such build per `BuildKey`, however many of its
                            // tests reach here (`BuiltModel::retry_fields`).
                            if fields.is_empty()
                                && seeds.compiler.unwrap_or_default().is_strict()
                                && let Some(f) = crate::problem::stateless_fields(prob)
                            {
                                fields = f;
                            }
                            if fields.is_empty()
                                && let Some(f) = cached
                                    .retry_fields(run_file, (t.time_span.start, t.time_span.end))
                            {
                                fields = f.clone();
                            }
                            // With no fields there is nothing to answer from,
                            // and `solve`'s own diagnostic is the honest one:
                            // it is what raises an evaluator FAULT
                            // (`E_TREEWALK_RECUR_UNAVAILABLE` for an unguarded
                            // recurrence self-read, `tests/
                            // recurrence_causal_self_reference.rs`) for a
                            // document that is genuinely broken.
                            if fields.is_empty() {
                                Err(format!("simulate failed: {e}"))
                            } else {
                                match unevaluable_time_dependent_assertion(run_file, model_name, t)
                                {
                                    Some(message) => Err(message),
                                    None => Ok(build_only_solution(saveat)),
                                }
                            }
                        }
                        Err(e) => Err(format!("simulate failed: {e}")),
                    },
                }
                .inspect(|_sol| {
                    insp = prob.take_inspection();
                    for (k, v) in fields {
                        insp.setup_arrays.entry(k).or_insert(v);
                    }
                })
            }
        }
        // A truncated or unstable run is a solve failure, not an assertion
        // failure: without this the trajectory simply stops short and every
        // assertion past the stop reports `no saved state at t=…`, naming the
        // symptom rather than the cause. Same check, same message shape as the
        // Julia binding's `_engine_setup`.
        .and_then(|sol| {
            if sol.retcode.is_success() {
                Ok(sol)
            } else {
                Err(format!("solver retcode {}", sol.retcode))
            }
        });
        for (i, a) in t.assertions.iter().enumerate() {
            let (rtol, atol) =
                resolve_tolerance(tolerance, t.tolerance.as_ref(), a.tolerance.as_ref());
            let outcome = match &sim {
                Err(msg) => Err(msg.clone()),
                Ok(sol) => eval_assertion(
                    sol,
                    a,
                    model_name,
                    run_index_sets,
                    run_file,
                    &insp,
                    base_dir,
                )
                .map_err(|msg| format!("assertion evaluation failed: {msg}")),
            };
            let (actual, passed, message) = match outcome {
                Err(msg) => (None, false, msg),
                Ok(actual) => {
                    let ok = check_assertion(actual, a.expected, rtol, atol);
                    let msg = if ok {
                        String::new()
                    } else {
                        format!(
                            "actual={actual} expected={} (rtol={rtol}, atol={atol})",
                            a.expected
                        )
                    };
                    (Some(actual), ok, msg)
                }
            };
            results.push(AssertionResult {
                model: model_name.to_string(),
                test_id: t.id.clone(),
                assertion_idx: i + 1,
                variable: a.variable.clone(),
                time: a.time,
                reduce: a.reduce.clone(),
                expected: a.expected,
                actual,
                rtol,
                atol,
                passed,
                message,
                file: source.to_string(),
            });
        }
    }
}

/// Run every inline test (esm-spec §6.6, including the §6.6.5 PDE
/// assertions) of the selected model(s) of `file` through the official
/// simulation pathway ([`crate::problem::esm_problem`] /
/// [`crate::problem::solve`], the array runtime), and return one
/// [`AssertionResult`] per assertion — carrying the ACTUAL reduction
/// value alongside pass/fail, so conformance harnesses can record and
/// cross-compare the numbers.
///
/// Per test: simulate over the test's `time_span` (with its
/// `initial_conditions` / `parameter_overrides` applied and `opts` pinning
/// the solver family and tolerances; the assertion times become the sampled
/// `saveat`); then per assertion the asserted variable's field is read
/// at the assertion time and either point-sampled per its `coords`
/// (positions in 1-based INDEX space; nearest grid index, exact ties
/// rounding DOWN — the pinned cross-binding convention) or collapsed per its
/// `reduce` (error norms evaluate the `reference` — an analytic expression
/// cellwise via [`evaluate_cellwise`], or a `{type: "from_file", path,
/// format?}` JSON snapshot resolved against the working directory; use
/// [`run_inline_tests_with_base_dir`] to anchor at the .esm file's directory).
/// An assertion with neither `coords` nor `reduce` samples a scalar state.
/// Mirrors the Julia binding's `run_inline_tests` 1:1 (tolerances per §6.6.4;
/// the pass predicate is Julia `isapprox`). Models iterate in sorted name
/// order for deterministic output.
pub fn run_inline_tests(
    file: &EsmFile,
    model_name: Option<&str>,
    opts: &SolveOptions,
) -> Vec<AssertionResult> {
    run_inline_tests_with_base_dir(file, model_name, opts, None)
}

/// [`run_inline_tests`] with an explicit `base_dir` anchoring `from_file`
/// reference paths (esm-spec §6.6.5, pinned convention: relative to the .esm
/// file's directory). `None` resolves relative paths against the working
/// directory — callers that loaded the document from a path should pass that
/// path's parent, matching the Julia / Python bindings' default.
pub fn run_inline_tests_with_base_dir(
    file: &EsmFile,
    model_name: Option<&str>,
    opts: &SolveOptions,
    base_dir: Option<&Path>,
) -> Vec<AssertionResult> {
    run_inline_tests_with_providers(file, model_name, opts, base_dir, None)
}

/// [`run_inline_tests_with_base_dir`] with the document's `data_sources` actually
/// INGESTED (esm-spec §8.9).
///
/// A document whose parameters carry `update: {kind: "data", …}` reads its
/// numbers off disk. Nothing in this crate opens a file on its own — the
/// build-time provider contract [`crate::prepare::PrepareProvider`] is supplied
/// by the CALLER, and a runner that supplies none evaluates the document
/// against every data-fed parameter's `default`. That is a silent wrong answer,
/// not a missing feature, which is why this entry point exists and why
/// `build_providers` returning `Err` is recorded as an assertion ERROR naming
/// the source rather than swallowed.
///
/// `build_providers` is a FACTORY, not a set: [`crate::problem::ProblemOptions`]
/// takes its providers by value, so the runner needs a fresh set for every
/// problem it builds. It is called **once per BUILD** — which is once per test
/// only for tests that differ in their [`BuildKey`]; consecutive tests that
/// share a build share the one provider set that built it, and a document whose
/// tests all share a key reads its `data_sources` once rather than once per
/// test. It is called only for a model that actually declares tests, and (with
/// `test_filter`) only for tests that were selected.
///
/// With providers bound, construction runs the deterministic build pipeline and
/// its materialized fields answer §6.6.5 array assertions directly. A document
/// with no differential equations is testable without integrating: `solve`
/// reports [`crate::SimulateError::NotDynamic`], and the
/// assertions are evaluated against the build's own products at the asserted
/// times.
pub fn run_inline_tests_with_providers(
    file: &EsmFile,
    model_name: Option<&str>,
    opts: &SolveOptions,
    base_dir: Option<&Path>,
    build_providers: Option<&BuildProviderFactory<'_>>,
) -> Vec<AssertionResult> {
    run_inline_tests_filtered(file, model_name, opts, base_dir, build_providers, None)
}

/// [`run_inline_tests_with_providers`] restricted to the tests whose `id` CONTAINS
/// `test_filter`.
///
/// The selection happens BEFORE anything is built or solved, which is the whole
/// point: a caller that narrows to one test of a document should pay for one
/// test of a document. The surviving rows are identical to filtering the
/// returned `Vec` by `test_id`, because a result's `test_id` is always its
/// test's `id` on every path — the assertion rows and the whole-test ERROR rows
/// alike.
///
/// `None` runs every test, and is what the three unfiltered entry points pass.
pub fn run_inline_tests_filtered(
    file: &EsmFile,
    model_name: Option<&str>,
    opts: &SolveOptions,
    base_dir: Option<&Path>,
    build_providers: Option<&BuildProviderFactory<'_>>,
    test_filter: Option<&str>,
) -> Vec<AssertionResult> {
    run_inline_tests_seeded(
        file,
        None,
        model_name,
        opts,
        base_dir,
        build_providers,
        test_filter,
        &InlineTestSeeds::default(),
    )
}

/// [`run_inline_tests_filtered`] driven by a whole [`InlineTestOptions`] — the
/// entry a CALLER with one loaded document and a full set of knobs wants.
///
/// The four positional entry points above grew one argument at a time and
/// cannot express the two newest knobs, the override seeds and the COMPILER
/// (API_SPEC §5.8). A sixth positional arity for each would be the wrong
/// answer; `InlineTestOptions` already names every knob, and
/// [`run_inline_tests_paths`] already takes it — this is the same options
/// record against a document the caller has already loaded.
///
/// `opts.base_dir` is used as given: unlike [`run_inline_tests_paths`], there
/// is no path here to fall back to, so a caller with `from_file` references
/// must set it.
pub fn run_inline_tests_with_options(
    file: &EsmFile,
    opts: &InlineTestOptions,
    build_providers: Option<&BuildProviderFactory<'_>>,
) -> Vec<AssertionResult> {
    run_inline_tests_seeded(
        file,
        None,
        opts.model_name.as_deref(),
        &opts.solve,
        opts.base_dir.as_deref(),
        build_providers,
        opts.test_filter.as_deref(),
        &InlineTestSeeds {
            parameter_overrides: opts.parameter_overrides.clone(),
            initial_conditions: opts.initial_conditions.clone(),
            compiler: opts.compiler,
        },
    )
}

/// [`run_inline_tests_filtered`] with the caller's override SEEDS — the one
/// thing the four `&EsmFile` entry points cannot express and
/// [`run_inline_tests_paths`] can.
///
/// Both kinds of test-bearing component run here: `models` first, then
/// `reaction_systems`, each in sorted name order for deterministic output. The
/// schema gives `reaction_systems` the same `tests` / `tolerance` members it
/// gives `models` (esm-spec §6.6), and this runner iterated `models` alone
/// until issue #194 — so a chemical mechanism's assertions were neither run nor
/// reported, which is the silent half of a coverage gap: a component that
/// produced no rows is indistinguishable in the result list from one that was
/// never looked at.
#[allow(clippy::too_many_arguments)]
fn run_inline_tests_seeded(
    file: &EsmFile,
    source: Option<&Path>,
    model_name: Option<&str>,
    opts: &SolveOptions,
    base_dir: Option<&Path>,
    build_providers: Option<&BuildProviderFactory<'_>>,
    test_filter: Option<&str>,
    seeds: &InlineTestSeeds,
) -> Vec<AssertionResult> {
    let mut results = Vec::new();

    // Every row of this document's run names the document, so a BATCH's rows
    // can be told apart (`AssertionResult::file`). A document handed over
    // already parsed has no path, and its rows carry the empty string — the
    // same convention as the Julia and Python bindings.
    let source: String = source.map(|p| p.display().to_string()).unwrap_or_default();

    // Lower `table_lookup` ONCE for the whole run (esm-spec §9.5.3).
    // `esm_problem` lowers its own copy, which covers everything it compiles —
    // but this runner also evaluates §6.6.5 analytic `reference` expressions
    // itself, outside any problem build, so those would otherwise be the one
    // position where an authored `table_lookup` still reached an evaluator.
    // A document that will not lower is passed through UNCHANGED and refused
    // by the build, in the vocabulary this runner already reports.
    let lowered = crate::lower_table_lookup::lowered_copy(file);
    let file: &EsmFile = lowered.as_ref().unwrap_or(file);
    let index_sets: HashMap<String, IndexSet> = file
        .index_sets
        .clone()
        .unwrap_or_default()
        .into_iter()
        .collect();

    // (name, tests, tolerance) for every test-bearing component, models first.
    let mut components: Vec<(&String, &Vec<crate::types::ModelTest>, Option<&Tolerance>)> =
        Vec::new();
    if let Some(models) = &file.models {
        let mut names: Vec<&String> = models.keys().collect();
        names.sort();
        for name in names {
            let m = &models[name];
            if let Some(tests) = m.tests.as_ref() {
                components.push((name, tests, m.tolerance.as_ref()));
            }
        }
    }
    if let Some(systems) = &file.reaction_systems {
        let mut names: Vec<&String> = systems.keys().collect();
        names.sort();
        for name in names {
            let rs = &systems[name];
            if let Some(tests) = rs.tests.as_ref() {
                components.push((name, tests, rs.tolerance.as_ref()));
            }
        }
    }

    for (name, tests, tolerance) in components {
        if let Some(selected) = model_name
            && selected != name.as_str()
        {
            continue;
        }
        run_component_tests(
            file,
            &source,
            name,
            tests,
            tolerance,
            &index_sets,
            opts,
            base_dir,
            build_providers,
            test_filter,
            seeds,
            &mut results,
        );
    }
    results
}

/// Per-document overrides for [`run_inline_tests_paths`], returned by its
/// `options_for` callback.
///
/// This record exists so that site-specific policy stays at the site. A CI gate
/// over a model corpus routinely carries basename-keyed tables — a
/// stiff-solver map, an initial-condition seed for the documents whose tests do
/// not state one — and each of those is a reason the gate could not call the
/// library entry and re-implemented esm-spec §6.6 instead. One callback absorbs
/// all of them without this module learning anything about the corpus.
///
/// `initial_conditions` / `parameter_overrides` are SEEDS: they are laid
/// BENEATH each test's own maps, so a test that states a value keeps it and a
/// test that is silent gets the caller's. They are merged with the test's map
/// before [`scope_to_component`] runs, and so are keyed and resolved exactly
/// like a test's own keys — which is what makes the precedence well defined.
///
/// `base_dir` left `None` defaults to the document's own parent directory,
/// which is what anchors a §6.6.5 `from_file` reference at the `.esm` file
/// rather than at the process's working directory.
///
/// There is deliberately no `cse` field: unlike the Python binding, this
/// crate's problem builder exposes no common-subexpression knob — its CSE is
/// unconditional internal machinery — and a field that silently did nothing
/// would be worse than its absence.
#[derive(Clone, Default)]
pub struct InlineTestOptions {
    /// Run only this component of the document (`None` runs every one).
    pub model_name: Option<String>,
    /// Solver family and tolerances for this document.
    pub solve: SolveOptions,
    /// Directory anchoring `from_file` reference paths; `None` uses the
    /// document's own parent.
    pub base_dir: Option<PathBuf>,
    /// Run only the tests whose `id` CONTAINS this needle.
    pub test_filter: Option<String>,
    /// Initial-condition seed, laid beneath each test's own map.
    pub initial_conditions: HashMap<String, InlineValue>,
    /// Parameter-override seed, laid beneath each test's own map.
    pub parameter_overrides: HashMap<String, InlineValue>,
    /// WHICH compiler builds each test's right-hand side (API_SPEC §5.8's
    /// closed vocabulary). `None` is [`crate::Compiler::Native`], and `native`
    /// is strict — a document the tape cannot lower fails its tests with the
    /// refusal rather than running on a slower path.
    pub compiler: Option<crate::problem::Compiler>,
}

impl std::fmt::Debug for InlineTestOptions {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("InlineTestOptions")
            .field("model_name", &self.model_name)
            .field("solve", &self.solve)
            .field("base_dir", &self.base_dir)
            .field("test_filter", &self.test_filter)
            .field("initial_conditions", &self.initial_conditions.len())
            .field("parameter_overrides", &self.parameter_overrides.len())
            .field("compiler", &self.compiler)
            .finish()
    }
}

/// Every `.esm` document under `dir`, recursively, SORTED — a result list whose
/// order depends on the filesystem is not comparable between two runs, let
/// alone between two machines.
fn esm_files_under(dir: &Path) -> Vec<PathBuf> {
    let mut out = Vec::new();
    let mut stack = vec![dir.to_path_buf()];
    while let Some(d) = stack.pop() {
        let Ok(entries) = std::fs::read_dir(&d) else {
            continue;
        };
        for entry in entries.flatten() {
            let path = entry.path();
            if path.is_dir() {
                stack.push(path);
            } else if path.extension().is_some_and(|e| e == "esm") {
                out.push(path);
            }
        }
    }
    out.sort();
    out
}

/// The one ERROR row a document that could not be LOADED contributes to a run.
///
/// A corpus run must not lose a file to one bad document, and must not lose it
/// SILENTLY either — a document that vanishes from the result list is
/// indistinguishable from one that passed. So the failure becomes a row, the
/// way every other failure in this runner becomes a row.
///
/// The path goes in `file`, where every other row of the run now carries its
/// document too. It ALSO stays in `model`, where it has been since this row
/// existed: that predates the `file` field and is what a caller reading these
/// rows today looks at — including this crate's own `esm test` summary. The
/// Python binding keeps both for the same reason.
fn load_failure_result(path: &Path, message: String) -> AssertionResult {
    AssertionResult {
        model: path.display().to_string(),
        test_id: "<load>".to_string(),
        assertion_idx: 0,
        variable: String::new(),
        time: f64::NAN,
        reduce: None,
        expected: f64::NAN,
        actual: None,
        rtol: 0.0,
        atol: 0.0,
        passed: false,
        message: format!("load failed: {message}"),
        file: path.display().to_string(),
    }
}

/// Run the inline tests of every document in `paths`, asking `options_for` for
/// each document's options.
///
/// This is the corpus entry: it takes PATHS rather than a loaded [`EsmFile`],
/// because the thing a caller varies per document — the solver, the tolerances,
/// an initial-condition seed — is keyed by the document, and a caller that had
/// to load each file itself to get at that would be back to writing the loop
/// this function is. A `paths` entry that is a DIRECTORY expands to the `.esm`
/// files under it, recursively and sorted; results are concatenated in that
/// order.
///
/// A document that fails to load contributes one ERROR row naming the path and
/// the run continues, so one unreadable file cannot cost the run every other
/// file's verdicts. `options_for` is consulted BEFORE the load, so it is asked
/// about the unreadable file too and wants a default rather than a panic.
///
/// What stays with the CALLER, deliberately: per-file process isolation and
/// memory limits, JUnit emission, summary formatting, and root discovery. A
/// library should not impose a process model.
pub fn run_inline_tests_paths(
    paths: &[impl AsRef<Path>],
    options_for: &dyn Fn(&Path) -> InlineTestOptions,
) -> Vec<AssertionResult> {
    let mut documents: Vec<PathBuf> = Vec::new();
    for p in paths {
        let p = p.as_ref();
        if p.is_dir() {
            documents.extend(esm_files_under(p));
        } else {
            documents.push(p.to_path_buf());
        }
    }
    let mut results = Vec::new();
    for path in documents {
        let opts = options_for(&path);
        let file = match crate::parse::load_path(&path) {
            Ok(f) => f,
            Err(e) => {
                results.push(load_failure_result(&path, e.to_string()));
                continue;
            }
        };
        // A `from_file` reference is anchored at the .esm file's own directory
        // unless the caller says otherwise — the pinned cross-binding
        // convention, and the same default the Julia and Python entries apply.
        let base_dir = opts
            .base_dir
            .clone()
            .or_else(|| path.parent().map(Path::to_path_buf));
        let seeds = InlineTestSeeds {
            parameter_overrides: opts.parameter_overrides.clone(),
            initial_conditions: opts.initial_conditions.clone(),
            compiler: opts.compiler,
        };
        results.extend(run_inline_tests_seeded(
            &file,
            Some(&path),
            opts.model_name.as_deref(),
            &opts.solve,
            base_dir.as_deref(),
            None,
            opts.test_filter.as_deref(),
            &seeds,
        ));
    }
    results
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::parse::load_string;
    use crate::simulate::Alg;
    use crate::types::ExpressionNode;
    use serde_json::json;

    const N: i64 = 8;

    /// Cell-center coordinates x_i = (i - 1/2)/N over the `x` index set —
    /// the §9.7 grid-geometry aggregate shape (post-import expansion).
    fn x_coord_aggregate() -> serde_json::Value {
        json!({
            "op": "faq", "args": [], "output_idx": ["i"],
            "ranges": {"i": {"from": "x"}},
            "expr": {"op": "*",
                     "args": [{"op": "-", "args": ["i", 0.5]},
                              {"op": "/", "args": [1, N]}]},
        })
    }

    fn cos_pi_x() -> serde_json::Value {
        json!({"op": "cos",
               "args": [{"op": "*",
                         "args": [std::f64::consts::PI, x_coord_aggregate()]}]})
    }

    /// A lifted field decay model du_i/dt = -u_i seeded by the coordinate
    /// expression ic(u) = cos(pi x_i); exact solution e^{-t} cos(pi x_i).
    /// (The same document the Python port's tests are built on.)
    fn decay_doc() -> serde_json::Value {
        let idx = json!({"op": "index", "args": ["u", "i"]});
        json!({
            "esm": "1.1.0",
            "metadata": {"name": "pde_inline_decay"},
            "index_sets": {"x": {"kind": "interval", "size": N}},
            "models": {"M": {
                "variables": {
                    "u": {"type": "unknown", "units": "1", "shape": ["x"]},
                },
                "equations": [
                    {"lhs": {"op": "ic", "args": ["u"]}, "rhs": cos_pi_x()},
                    {"lhs": {"op": "faq", "args": [], "output_idx": ["i"],
                             "ranges": {"i": [1, N]},
                             "expr": {"op": "D", "args": [idx], "wrt": "t"}},
                     "rhs": {"op": "faq", "args": [], "output_idx": ["i"],
                             "ranges": {"i": [1, N]},
                             "expr": {"op": "*", "args": [-1, idx]}}},
                ],
                "tests": [{
                    "id": "decay",
                    "time_span": {"start": 0.0, "end": 1.0},
                    "assertions": [
                        {"variable": "u", "time": 0.0, "expected": 0.0,
                         "tolerance": {"abs": 1e-12}, "reduce": "L2_error",
                         "reference": cos_pi_x()},
                        {"variable": "u", "time": 1.0, "expected": 0.0,
                         "tolerance": {"abs": 1e-8}, "reduce": "L2_error",
                         "reference": {"op": "*",
                                       "args": [{"op": "exp", "args": [-1]},
                                                cos_pi_x()]}},
                        {"variable": "u", "time": 1.0, "expected": 0.0,
                         "tolerance": {"abs": 1e-9}, "reduce": "mean"},
                    ],
                }],
            }},
        })
    }

    fn tight_opts() -> SolveOptions {
        SolveOptions {
            alg: Alg::Erk,
            reltol: Some(1e-12),
            abstol: Some(1e-14),
            ..Default::default()
        }
    }

    #[test]
    fn assertion_reduce_reference_parse_and_roundtrip() {
        let file = load_string(&decay_doc().to_string()).expect("decay doc loads");
        let models = file.models.as_ref().unwrap();
        let a = &models["M"].tests.as_ref().unwrap()[0].assertions[0];
        assert_eq!(a.reduce.as_deref(), Some("L2_error"));
        assert!(a.coords.is_none());
        match a.reference.as_ref().expect("reference parsed") {
            AssertionReference::Expression(expr) => match expr.as_ref() {
                Expr::Operator(node) => assert_eq!(node.op, "cos"),
                other => panic!("expected operator reference, got {other:?}"),
            },
            other => panic!("expected inline-expression reference, got {other:?}"),
        }
        // Round-trip: the §6.6.5 keys serialize back; the pure-collapser
        // form still omits `reference`.
        let ser = serde_json::to_value(&file).expect("serializes");
        let asserts = &ser["models"]["M"]["tests"][0]["assertions"];
        assert_eq!(asserts[0]["reduce"], "L2_error");
        assert_eq!(asserts[0]["reference"]["op"], "cos");
        assert_eq!(asserts[2]["reduce"], "mean");
        assert!(asserts[2].get("reference").is_none());
    }

    #[test]
    fn assertion_from_file_reference_roundtrips_verbatim() {
        let mut doc = decay_doc();
        doc["models"]["M"]["tests"][0]["assertions"][0]["reference"] =
            json!({"type": "from_file", "path": "ref.nc", "format": "netcdf"});
        let file = load_string(&doc.to_string()).expect("from_file reference parses");
        let models = file.models.as_ref().unwrap();
        let a = &models["M"].tests.as_ref().unwrap()[0].assertions[0];
        match a.reference.as_ref().expect("reference parsed") {
            AssertionReference::FromFile(ff) => {
                assert_eq!(ff.ref_type, "from_file");
                assert_eq!(ff.path, "ref.nc");
                assert_eq!(ff.format.as_deref(), Some("netcdf"));
            }
            other => panic!("expected from_file reference, got {other:?}"),
        }
        let ser = serde_json::to_value(&file).expect("serializes");
        assert_eq!(
            ser["models"]["M"]["tests"][0]["assertions"][0]["reference"],
            json!({"type": "from_file", "path": "ref.nc", "format": "netcdf"})
        );
    }

    #[test]
    fn evaluate_cellwise_grid_geometry() {
        let file = load_string(&decay_doc().to_string()).expect("decay doc loads");
        let models = file.models.as_ref().unwrap();
        let a = &models["M"].tests.as_ref().unwrap()[0].assertions[0];
        let Some(AssertionReference::Expression(expr)) = &a.reference else {
            panic!("expected inline reference");
        };
        let index_sets: HashMap<String, IndexSet> =
            file.index_sets.clone().unwrap().into_iter().collect();
        let cells: Vec<Vec<i64>> = (1..=N).map(|i| vec![i]).collect();
        let no_params: HashMap<String, f64> = HashMap::new();
        let vals = evaluate_cellwise(expr, &cells, &index_sets, &no_params).expect("evaluates");
        for (i, v) in (1..=N).zip(&vals) {
            let want = (std::f64::consts::PI * (i as f64 - 0.5) / N as f64).cos();
            assert!((v - want).abs() < 1e-15, "cell {i}: {v} vs {want}");
        }
        // A const-folding scalar broadcasts.
        let two = Expr::operator(ExpressionNode {
            op: "+".to_string(),
            args: vec![Expr::Integer(1), Expr::Integer(1)],
            ..Default::default()
        });
        assert_eq!(
            evaluate_cellwise(&two, &cells, &index_sets, &no_params).unwrap(),
            vec![2.0; N as usize]
        );
    }

    #[test]
    fn field_reduce_semantics() {
        let actual = [1.0, 2.0, 3.0];
        let reference = [1.0, 2.0, 5.0];
        let l2 = field_reduce("L2_error", &actual, Some(&reference)).unwrap();
        assert!((l2 - 2.0 / 30.0f64.sqrt()).abs() < 1e-15);
        assert_eq!(
            field_reduce("Linf_error", &actual, Some(&reference)).unwrap(),
            2.0
        );
        assert_eq!(field_reduce("mean", &actual, None).unwrap(), 2.0);
        assert_eq!(field_reduce("max", &actual, None).unwrap(), 3.0);
        assert_eq!(field_reduce("min", &actual, None).unwrap(), 1.0);
        assert!(field_reduce("L2_error", &actual, None).is_err()); // reference required
        assert!(field_reduce("L2_error", &actual, Some(&[0.0, 0.0, 0.0])).is_err()); // zero norm
        assert!(field_reduce("wat", &actual, None).is_err()); // unknown kind
    }

    /// The §6.6.5 build-time scalar scope reads a flattened parameter the way
    /// the OWNING component's equations spell it: under the owner-relative
    /// remainder of the flattened key, and under every globally unambiguous
    /// dotted suffix of it (issue #408). `P.sub.g` is therefore readable as
    /// `P.sub.g`, `sub.g` and `g`; before the fix the middle one — the spelling
    /// the model's own EQUATIONS use, and the only one a mount edge rewrites —
    /// was the one that was missing.
    #[test]
    fn param_scope_aliases_every_unambiguous_dotted_suffix() {
        let params: HashMap<String, f64> =
            [("P.sub.g".to_string(), 2.0), ("P.k".to_string(), 1.0)].into();
        let scope = param_scope_with_aliases(&params, "P");
        for (name, want) in [
            ("P.sub.g", 2.0),
            ("sub.g", 2.0),
            ("g", 2.0),
            ("P.k", 1.0),
            ("k", 1.0),
        ] {
            assert_eq!(scope.get(name), Some(&want), "{name} must be in scope");
        }
        assert_eq!(scope.len(), 5, "no name beyond those five: {scope:?}");

        // Two mounts of one subsystem, and the test belongs to NEITHER: the
        // suffixes `sub.g` / `g` are carried by both, so neither binds and a
        // reference meaning one of them must qualify. An ambiguous alias
        // silently picking a side is the failure this guards.
        let ambiguous: HashMap<String, f64> =
            [("A.sub.g".to_string(), 1.0), ("B.sub.g".to_string(), 2.0)].into();
        let scope = param_scope_with_aliases(&ambiguous, "C");
        assert_eq!(scope.len(), 2, "only the flattened names: {scope:?}");
        assert!(!scope.contains_key("sub.g"));
        assert!(!scope.contains_key("g"));

        // …but the OWNER's own `sub.g` is never ambiguous, however many
        // siblings mount a `sub` of their own. This is the coupling-document
        // shape of issue #408, where the globally-ambiguous suffix rule alone
        // still left `wrf.g` unbound.
        let owned = param_scope_with_aliases(&ambiguous, "A");
        assert_eq!(owned.get("sub.g"), Some(&1.0));
        assert_eq!(
            param_scope_with_aliases(&ambiguous, "B").get("sub.g"),
            Some(&2.0)
        );

        // A real flattened name is never shadowed by another name's alias.
        let shadowing: HashMap<String, f64> =
            [("A.sub.g".to_string(), 1.0), ("sub.g".to_string(), 7.0)].into();
        assert_eq!(
            param_scope_with_aliases(&shadowing, "A").get("sub.g"),
            Some(&7.0)
        );

        // A name that is neither the owner's own nor a globally unambiguous
        // suffix is bound by nothing: the typo `sub.gg` stays unbound, which is
        // what keeps it an ERROR downstream rather than a silent value.
        assert!(!param_scope_with_aliases(&params, "P").contains_key("sub.gg"));

        // The owner-relative rule reaches a BARE tail too, and that widens the
        // §6.6.5 clash scope: `x` is the tail of two flattened names, so the
        // old globally-unambiguous-tail rule bound it for NOBODY, whereas the
        // owner's own `x` is unambiguous and is now in scope. A reference that
        // mentions a dimension named `x` free therefore now collides with it
        // (`bind_dimension_names`) where before it was silently wrapped.
        let tails: HashMap<String, f64> =
            [("P.x".to_string(), 1.0), ("R.x".to_string(), 2.0)].into();
        assert_eq!(param_scope_with_aliases(&tails, "P").get("x"), Some(&1.0));
        assert_eq!(param_scope_with_aliases(&tails, "R").get("x"), Some(&2.0));
        assert!(!param_scope_with_aliases(&tails, "Q").contains_key("x"));
    }

    /// Pinned cross-binding convention: `integral` is the uniform-cell
    /// Riemann sum under a UNIT total domain measure per axis — Σ field /
    /// N_cells, exactly `mean` (NOT the bare sum).
    #[test]
    fn field_reduce_integral_is_unit_measure_mean() {
        let f = [1.0, 2.0, 3.0];
        assert_eq!(field_reduce("integral", &f, None).unwrap(), 2.0);
        assert_eq!(
            field_reduce("integral", &f, None).unwrap(),
            field_reduce("mean", &f, None).unwrap()
        );
        let g: Vec<f64> = (1..=8).map(|i| (i as f64 - 0.5) / 8.0).collect();
        assert_eq!(field_reduce("integral", &g, None).unwrap(), 0.5);
        assert!(field_reduce("integral", &[], None).is_err());
    }

    #[test]
    fn state_cells_matching_and_order() {
        let names: Vec<String> = ["M.v[1]", "w", "wat", "M.u[1]", "M.u[2]", "x[oops]"]
            .iter()
            .map(|s| s.to_string())
            .collect();
        // Reorder rows so numeric cell sorting is observable: u[10] before u[2].
        let names2: Vec<String> = ["M.u[2]", "M.u[1]", "M.u[10]", "M.v[1]", "w"]
            .iter()
            .map(|s| s.to_string())
            .collect();
        let cells = state_cells(&names2, "u", "M");
        assert_eq!(
            cells,
            vec![(vec![1], 1), (vec![2], 0), (vec![10], 2)] // numeric cell order
        );
        assert_eq!(state_cells(&names2, "u", "Other"), cells); // bare-stem match
        assert_eq!(state_cells(&names, "w", "M"), vec![]); // scalars never match
        assert_eq!(state_cells(&names, "x", "M"), vec![]); // non-integer suffix
        assert_eq!(scalar_slot(&names, "w", "M", &HashMap::new()), Some(1));
    }

    #[test]
    fn tolerance_precedence_and_isapprox_semantics() {
        let model_tol = Tolerance {
            rel: Some(1e-2),
            abs: None,
        };
        let test_tol = Tolerance {
            rel: None,
            abs: Some(1e-3),
        };
        let assertion_tol = Tolerance {
            rel: Some(1e-6),
            abs: Some(1e-9),
        };
        assert_eq!(
            resolve_tolerance(Some(&model_tol), Some(&test_tol), Some(&assertion_tol)),
            (1e-6, 1e-9)
        );
        // PER FIELD (§6.6.4): the test declares only `abs`, so the model's
        // `rel` survives. This returned `(0.0, 1e-3)` before #228 — the test's
        // block won wholesale and the model's relative bound vanished.
        assert_eq!(
            resolve_tolerance(Some(&model_tol), Some(&test_tol), None),
            (1e-2, 1e-3)
        );
        assert_eq!(resolve_tolerance(Some(&model_tol), None, None), (1e-2, 0.0));
        assert_eq!(resolve_tolerance(None, None, None), (DEFAULT_REL_TOL, 0.0));
        // The implementation default is the FOURTH LEVEL of the same per-field
        // merge, not a fallback reached only when levels 1-3 are silent: an
        // `abs`-only block still takes `rel = 1e-6` from it.
        let abs_only = Tolerance {
            abs: Some(1e-4),
            rel: None,
        };
        assert_eq!(
            resolve_tolerance(None, None, Some(&abs_only)),
            (DEFAULT_REL_TOL, 1e-4)
        );
        assert_eq!(
            resolve_tolerance(Some(&abs_only), None, None),
            (DEFAULT_REL_TOL, 1e-4)
        );
        // ... and `rel: 0` is the only way to opt out of it. An explicit zero
        // is a DECLARATION, so it stops the fallthrough at the default too.
        let abs_only_exact = Tolerance {
            abs: Some(1e-4),
            rel: Some(0.0),
        };
        assert_eq!(
            resolve_tolerance(None, None, Some(&abs_only_exact)),
            (0.0, 1e-4)
        );
        // A declared outer `rel` still beats the default, however far out.
        let outer_rel = Tolerance {
            abs: None,
            rel: Some(1e-3),
        };
        assert_eq!(
            resolve_tolerance(Some(&outer_rel), None, Some(&abs_only)),
            (1e-3, 1e-4)
        );
        // Julia isapprox: |a-e| <= max(atol, rtol*max(|a|,|e|)).
        assert!(check_assertion(1.0000009, 1.0, 1e-6, 0.0));
        assert!(!check_assertion(1.000002, 1.0, 1e-6, 0.0));
        assert!(check_assertion(0.0, 1e-10, 0.0, 1e-9));
        assert!(check_assertion(2.0, 2.0, 0.0, 0.0)); // exact-equality mode
        assert!(!check_assertion(2.0, 2.0000001, 0.0, 0.0));
    }

    /// esm-spec §6.6.3: the relative bound is SYMMETRIC in `actual` and
    /// `expected` — its scale is `max(|actual|, |expected|)`, the larger of the
    /// two magnitudes, NOT `|expected|` alone.
    ///
    /// §6.6.3 used to state both readings: the normative box (and the schema's
    /// `Tolerance` description) gave the `|expected|`-only denominator while
    /// the finiteness rationale further down the same section reasoned from
    /// `max(|inf|, |expected|)`. All three executing bindings implemented the
    /// symmetric one; EarthSciML/EarthSciAST#193 settled the spec as symmetric.
    ///
    /// Their VERDICTS disagree only inside `rtol*|e| < |a − e| <= rtol*|a|`,
    /// which needs an overshoot (`|actual| > |expected|`) whose margin is
    /// itself of order `rtol`. Everywhere else `max(|a|, |e|) == |e|` or the
    /// difference falls on the same side of both bounds, which is why the
    /// divergence went unnoticed: every pre-existing tolerance case in every
    /// binding gets the same verdict under both readings, and the
    /// `assertion_nonfinite` category compares verdicts on non-finite actuals.
    /// Reverting `check_assertion` to the `|expected|` denominator must turn
    /// this red.
    #[test]
    fn relative_bound_is_symmetric_in_actual_and_expected() {
        // The discriminator: the symmetric scale is 1.6, not 1.0.
        //   symmetric:  0.6 <= 0.5 * max(1.6, 1.0) = 0.8  -> PASS
        //   |expected|: 0.6 <= 0.5 * 1.0           = 0.5  -> FAIL
        assert!(check_assertion(1.6, 1.0, 0.5, 0.0));
        // Past the symmetric bound too, so both readings agree again.
        assert!(!check_assertion(3.0, 1.0, 0.5, 0.0));

        // Symmetry as the property, not just the one case: swapping the
        // arguments cannot change the verdict. Under an `|expected|`-only
        // denominator the first pair below disagrees with itself reversed.
        for (a, e) in [(1.6, 1.0), (1.0, 1.6), (3.0, 1.0), (1.0, 3.0), (-2.0, -1.2)] {
            assert_eq!(
                check_assertion(a, e, 0.5, 0.0),
                check_assertion(e, a, 0.5, 0.0),
                "verdict must not depend on argument order: ({a}, {e})"
            );
        }

        // No epsilon floor, and none permitted: the bound is a product, not a
        // quotient, so `expected == 0` needs no protection. It reads
        // `|a| <= rel*|a|`, which a nonzero actual clears only at `rel >= 1` —
        // a purely relative tolerance says nothing about how close to zero is
        // close enough.
        assert!(!check_assertion(1.0, 0.0, 0.5, 0.0));
        assert!(check_assertion(1.0, 0.0, 1.0, 0.0));
        assert!(check_assertion(1.0, 0.0, 0.0, 1.0)); // an `abs` bound spells it
        assert!(check_assertion(0.0, 0.0, 0.0, 0.0)); // exact-equality clause

        // Zero ACTUAL against a nonzero expected — the mirror of the case
        // above. Here the symmetric scale IS `|e|`, so both readings agree; it
        // is pinned because the other one-sided reading (scale by `|actual|`
        // alone) would make the bound zero and reject every inexact match.
        assert!(!check_assertion(0.0, 1.0, 0.5, 0.0));
        assert!(check_assertion(0.0, 1.0, 1.0, 0.0));

        // OPPOSITE SIGNS. `rel >= 1` is vacuous only for a pair that shares a
        // sign; across a sign change the bound still bites, which is why
        // §6.6.3 says `rel >= 1` is not a substitute for an `abs` bound at
        // `expected == 0`.
        assert!(!check_assertion(1.0, -1.0, 1.0, 0.0));
        assert!(check_assertion(-1.0, 1.0, 2.0, 0.0));

        // NON-FINITE actuals. The symmetric scale is precisely what makes the
        // finiteness clause load-bearing: `|inf − e| <= rel*max(inf, |e|)` is
        // `inf <= inf`, so the bound ALONE would pass every expected value
        // (§6.6.3; the `assertion_nonfinite` category, CONFORMANCE_SPEC §5.20).
        assert!(!check_assertion(f64::INFINITY, 1.0, 0.5, 0.0));
        assert!(!check_assertion(f64::NEG_INFINITY, 1.0, 0.5, 0.0));
        assert!(!check_assertion(f64::NAN, 1.0, 0.5, 0.0));
        // The SAME infinity matches through the equality clause; opposite ones
        // do not.
        assert!(check_assertion(f64::INFINITY, f64::INFINITY, 0.5, 0.0));
        assert!(!check_assertion(f64::INFINITY, f64::NEG_INFINITY, 0.5, 0.0));

        // abs/rel interaction, both directions. An `abs` bound never narrows
        // what `rel` already admits — the predicate takes the MAX of the two —
        // so a tiny `abs` must not turn the overshoot case red:
        assert!(check_assertion(1.6, 1.0, 0.5, 1e-12));
        // and `abs` admits what the symmetric `rel` rejects (same inputs as the
        // `!check_assertion(3.0, 1.0, 0.5, 0.0)` rejection above):
        assert!(check_assertion(3.0, 1.0, 0.5, 2.5));
    }

    /// Cross-language conformance: esm-spec §6.6.4 tolerance RESOLUTION
    /// (CONFORMANCE_SPEC §5.21).
    ///
    /// The shared cases live in `tests/conformance/tolerance_resolution/`
    /// (repo root); the Julia runner (`conformance_tolerance_resolution_test.jl`)
    /// and the Python runner (`test_tolerance_resolution_conformance.py`) gate
    /// the same file. The category is DATA-ONLY — resolution is a pure function
    /// of the declared `{abs?, rel?}` blocks — so it carries no `.esm` fixture,
    /// no integrator and no numeric golden, and it lives here as a unit test
    /// rather than under `tests/` because it needs nothing from the crate but
    /// this one private-ish function.
    ///
    /// The defect it closes (#228): all three bindings returned the first
    /// `Some` block WHOLE and defaulted its missing field to 0, so a model
    /// `{rel: 1e-6}` plus an assertion `{abs: 1e-9}` resolved to `(0, 1e-9)`
    /// and the assertion ran with no relative bound at all. No other
    /// conformance tier could see it: every fixture in every other category
    /// declares exactly one tolerance block, and one block merges identically
    /// whether the rule is per-field or wholesale.
    #[test]
    fn tolerance_resolution_conformance_manifest() {
        use serde_json::Value;

        let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("../../tests/conformance/tolerance_resolution/manifest.json");
        let text = std::fs::read_to_string(&path)
            .unwrap_or_else(|e| panic!("read {}: {e}", path.display()));
        let m: Value = serde_json::from_str(&text).expect("parse manifest");

        assert_eq!(m["category"], "tolerance_resolution");
        // Data-only: pinning an integrator here would be a category error.
        assert!(m["integrators"].is_null());
        let cases = m["cases"].as_array().expect("cases array");
        assert!(cases.len() >= 15, "thin tier: {} cases", cases.len());

        // A manifest `levels` entry: a missing key and an explicit JSON `null`
        // both mean ABSENT and both become `None`; a `0` is a declared bound
        // and must survive as `Some(0.0)`.
        fn tolerance(block: &Value) -> Option<Tolerance> {
            if block.is_null() {
                return None;
            }
            let field = |name: &str| block.get(name).and_then(Value::as_f64);
            Some(Tolerance {
                abs: field("abs"),
                rel: field("rel"),
            })
        }

        // The pre-#228 rule, kept as the thing the new one must never be
        // tighter than: the first declared block won wholesale and its missing
        // field became 0.
        fn wholesale(
            model: Option<&Tolerance>,
            test: Option<&Tolerance>,
            assertion: Option<&Tolerance>,
        ) -> (f64, f64) {
            match [assertion, test, model].into_iter().flatten().next() {
                Some(c) => (c.rel.unwrap_or(0.0), c.abs.unwrap_or(0.0)),
                None => (DEFAULT_REL_TOL, 0.0),
            }
        }

        let mut changed = 0usize;
        for case in cases {
            let id = case["id"].as_str().expect("case id");
            let levels = &case["levels"];
            let model = tolerance(&levels["model"]);
            let test = tolerance(&levels["test"]);
            let assertion = tolerance(&levels["assertion"]);

            let got = resolve_tolerance(model.as_ref(), test.as_ref(), assertion.as_ref());
            let want = (
                case["resolved"]["rel"].as_f64().expect("resolved.rel"),
                case["resolved"]["abs"].as_f64().expect("resolved.abs"),
            );
            assert_eq!(got, want, "{id}: {}", case["note"]);

            // Monotonicity: per field the merged value can only come from a
            // level the wholesale rule ignored, so no bound ever tightens and
            // no assertion can flip pass -> fail under this change.
            let old = wholesale(model.as_ref(), test.as_ref(), assertion.as_ref());
            assert!(got.0 >= old.0 && got.1 >= old.1, "{id} tightened");
            let flag = case["changed_by_228"].as_bool().expect("changed_by_228");
            assert_eq!(old != got, flag, "{id}: changed_by_228 is stale");
            changed += usize::from(flag);
        }
        assert!(changed >= 5, "tier does not exercise the change: {changed}");
    }

    /// esm-spec §6.6.3: finiteness is judged BEFORE tolerance. Without the
    /// guard `|inf − e| ≤ max(atol, rtol·max(inf, |e|))` is `inf ≤ inf`, and an
    /// infinite actual passed against every expected value.
    #[test]
    fn check_assertion_judges_finiteness_before_tolerance() {
        let inf = f64::INFINITY;
        let nan = f64::NAN;
        for (rtol, atol) in [(1e-9, 0.0), (0.0, 1e300), (1e-9, 1e300), (0.0, 0.0)] {
            assert!(!check_assertion(inf, 42.0, rtol, atol));
            assert!(!check_assertion(inf, -5.0, rtol, atol));
            assert!(!check_assertion(inf, 0.0, rtol, atol));
            assert!(!check_assertion(inf, f64::MAX, rtol, atol));
            assert!(!check_assertion(-inf, -42.0, rtol, atol));
            assert!(!check_assertion(nan, 0.0, rtol, atol));
            assert!(!check_assertion(nan, nan, rtol, atol));
            // A finite actual against an infinite expectation fails too.
            assert!(!check_assertion(1e300, inf, rtol, atol));
            // The one legitimate non-finite match: the same infinity.
            assert!(check_assertion(inf, inf, rtol, atol));
            assert!(check_assertion(-inf, -inf, rtol, atol));
            assert!(!check_assertion(inf, -inf, rtol, atol));
            assert!(!check_assertion(-inf, inf, rtol, atol));
        }
        // Signed zero is IEEE-equal, at every tolerance.
        assert!(check_assertion(-0.0, 0.0, 0.0, 0.0));
        assert!(check_assertion(-0.0, 0.0, 1e-9, 0.0));
    }

    /// esm-spec §6.6.3, finding F6: a component whose variables are ALL scalars
    /// and whose equations are all algebraic has no state vector, and its
    /// assertion used to ERROR with `scalar state 'answer' not found`.
    /// Declaring one array-shaped variable anywhere in the same component made
    /// the identical assertion pass, because the model then took the array
    /// runtime, which exposes 0-D observeds as trajectory rows. Nothing about
    /// an algebraic scalar depends on an array being nearby.
    #[test]
    fn scalar_only_component_is_assertable() {
        let doc = json!({
            "esm": "1.1.0",
            "metadata": {"name": "scalar_only"},
            "models": {"ScalarOnly": {
                "variables": {
                    "input": {"type": "parameter", "units": "1", "default": 21.0},
                    "answer": {"type": "unknown", "units": "1"},
                },
                "equations": [
                    {"lhs": "answer", "rhs": {"op": "*", "args": [2.0, "input"]}},
                ],
                "tests": [{
                    "id": "algebraic_scalar",
                    "time_span": {"start": 0.0, "end": 0.0},
                    "assertions": [
                        {"variable": "answer", "time": 0.0, "expected": 42.0,
                         "tolerance": {"rel": 1e-12}},
                    ],
                }],
            }},
        });
        let file = load_string(&doc.to_string()).expect("scalar-only doc loads");
        let results = run_inline_tests(&file, Some("ScalarOnly"), &tight_opts());
        assert_eq!(results.len(), 1);
        assert!(results[0].passed, "{}", results[0].message);
        assert_eq!(results[0].actual, Some(42.0));

        // ...and the value is JUDGED, not merely produced: the same document
        // with a wrong expectation must FAIL rather than error.
        let mut wrong = doc.clone();
        wrong["models"]["ScalarOnly"]["tests"][0]["assertions"][0]["expected"] = json!(41.0);
        let file = load_string(&wrong.to_string()).expect("doc loads");
        let results = run_inline_tests(&file, Some("ScalarOnly"), &tight_opts());
        assert!(!results[0].passed);
        assert_eq!(results[0].actual, Some(42.0));
        assert!(
            results[0].message.contains("actual=42"),
            "a wrong expectation must be a FAIL naming the value, got: {}",
            results[0].message
        );
    }

    /// The same hole in a component that DOES integrate: a scalar observed of a
    /// scalar ODE model has no state slot either, and the runner now asks the
    /// observed graph for it. The state assertion beside it is the control.
    #[test]
    fn scalar_observed_of_an_ode_component_is_assertable() {
        let doc = json!({
            "esm": "1.1.0",
            "metadata": {"name": "scalar_ode_observed"},
            "models": {"M": {
                "variables": {
                    "u": {"type": "unknown", "units": "1", "default": 1.0},
                    "k": {"type": "parameter", "units": "1/s", "default": 0.5},
                    "twice": {"type": "unknown", "units": "1"},
                },
                "equations": [
                    {"lhs": {"op": "D", "args": ["u"], "wrt": "t"},
                     "rhs": {"op": "*", "args": [-1.0, {"op": "*", "args": ["k", "u"]}]}},
                    {"lhs": "twice", "rhs": {"op": "*", "args": [2.0, "u"]}},
                ],
                "tests": [{
                    "id": "observed_along_the_trajectory",
                    "time_span": {"start": 0.0, "end": 1.0},
                    "assertions": [
                        {"variable": "u", "time": 0.0, "expected": 1.0,
                         "tolerance": {"rel": 1e-9}},
                        {"variable": "twice", "time": 0.0, "expected": 2.0,
                         "tolerance": {"rel": 1e-9}},
                        {"variable": "twice", "time": 1.0,
                         "expected": 1.2130613194252668,
                         "tolerance": {"rel": 1e-8}},
                    ],
                }],
            }},
        });
        let file = load_string(&doc.to_string()).expect("ode doc loads");
        let results = run_inline_tests(&file, Some("M"), &tight_opts());
        assert_eq!(results.len(), 3);
        for r in &results {
            assert!(
                r.passed,
                "{}#{}: {}",
                r.variable, r.assertion_idx, r.message
            );
        }
        // 2*exp(-0.5): the observed is read at the RIGHT time, not held at t=0.
        let late = results[2].actual.expect("actual");
        assert!(
            (late - 2.0 * (-0.5f64).exp()).abs() <= 1e-8,
            "observed at t=1 is {late}"
        );
    }

    /// A ZERO-LENGTH time span on a component that INTEGRATES: the run's whole
    /// answer is its initial state, and nothing is integrated to reach it.
    ///
    /// esm-spec §6.6.2 names this shape — "the instantaneous-derivative test
    /// shape (observed tendencies asserted at `time: 0`)" — §6.6 constrains an
    /// assertion's `time` only to lie in `[time_span.start, time_span.end]`,
    /// which `0` does in `[0, 0]`, and the schema's `TimeSpan` carries no
    /// `end > start` rule. Twenty-three corpus documents author it; twenty-two
    /// are STATIC, so `solve` answers `NotDynamic` and the runner reads the
    /// build. The twenty-third, `tests/valid/units_propagation.esm`, integrates
    /// — and diffsol's `set_stop_time` refused the interval with "Stop time is
    /// at the current state time", failing all ten of its assertions on a
    /// complaint about having nothing to do while Julia and Python both
    /// evaluated it.
    #[test]
    fn a_zero_length_time_span_answers_from_the_initial_state() {
        // Same model as `scalar_observed_of_an_ode_component_is_assertable`,
        // whose `{start: 0, end: 1}` run is the moving control for this one.
        let model = json!({
            "variables": {
                "u": {"type": "unknown", "units": "1", "default": 1.0},
                "k": {"type": "parameter", "units": "1/s", "default": 0.5},
                "twice": {"type": "unknown", "units": "1"},
            },
            "equations": [
                {"lhs": {"op": "D", "args": ["u"], "wrt": "t"},
                 "rhs": {"op": "*", "args": [-1.0, {"op": "*", "args": ["k", "u"]}]}},
                {"lhs": "twice", "rhs": {"op": "*", "args": [2.0, "u"]}},
            ],
            "tests": [{
                "id": "at_the_initial_state",
                "time_span": {"start": 0.0, "end": 0.0},
                "assertions": [
                    // The STATE, at its initial value — the control that says
                    // the run happened at all.
                    {"variable": "u", "time": 0.0, "expected": 1.0,
                     "tolerance": {"rel": 1e-12}},
                    // And the OBSERVED computed from it, which is what a
                    // document writes this shape for.
                    {"variable": "twice", "time": 0.0, "expected": 2.0,
                     "tolerance": {"rel": 1e-12}},
                ],
            }],
        });
        let doc = json!({
            "esm": "1.1.0",
            "metadata": {"name": "zero_length_span"},
            "models": {"M": model},
        });
        let file = load_string(&doc.to_string()).expect("doc loads");
        let results = run_inline_tests(&file, Some("M"), &tight_opts());
        assert_eq!(results.len(), 2);
        for r in &results {
            assert!(
                r.passed,
                "{}#{}: {}",
                r.variable, r.assertion_idx, r.message
            );
        }
        assert_eq!(results[0].actual, Some(1.0));
        assert_eq!(results[1].actual, Some(2.0));

        // The guard keys on the INTERVAL being empty, not on the clock reading
        // zero: an empty span anywhere on the axis answers from the state the
        // run starts in, which for `t0 = 2` is still the declared default.
        let mut shifted = doc.clone();
        shifted["models"]["M"]["tests"][0]["time_span"] = json!({"start": 2.0, "end": 2.0});
        shifted["models"]["M"]["tests"][0]["assertions"][0]["time"] = json!(2.0);
        shifted["models"]["M"]["tests"][0]["assertions"][1]["time"] = json!(2.0);
        let file = load_string(&shifted.to_string()).expect("shifted doc loads");
        let results = run_inline_tests(&file, Some("M"), &tight_opts());
        assert_eq!(results.len(), 2);
        for r in &results {
            assert!(
                r.passed,
                "{}#{}: {}",
                r.variable, r.assertion_idx, r.message
            );
        }
        assert_eq!(results[1].actual, Some(2.0));

        // And a NON-empty span is untouched — `set_stop_time` still runs on
        // exactly the intervals it always accepted, and the trajectory moves.
        let mut moving = doc.clone();
        moving["models"]["M"]["tests"][0]["time_span"] = json!({"start": 0.0, "end": 1.0});
        moving["models"]["M"]["tests"][0]["assertions"][1]["time"] = json!(1.0);
        moving["models"]["M"]["tests"][0]["assertions"][1]["expected"] = json!(1.2130613194252668);
        moving["models"]["M"]["tests"][0]["assertions"][1]["tolerance"] = json!({"rel": 1e-8});
        let file = load_string(&moving.to_string()).expect("moving doc loads");
        let results = run_inline_tests(&file, Some("M"), &tight_opts());
        assert_eq!(results.len(), 2);
        for r in &results {
            assert!(
                r.passed,
                "{}#{}: {}",
                r.variable, r.assertion_idx, r.message
            );
        }
    }

    /// An unbound scalar must be DIAGNOSABLE, not a plausible zero: a pointwise
    /// assertion on a name the build materialized nothing for is an ERROR
    /// naming the variable.
    #[test]
    fn an_unmaterialized_scalar_assertion_is_an_error_not_a_zero() {
        let doc = json!({
            "esm": "1.1.0",
            "metadata": {"name": "scalar_missing"},
            "models": {"ScalarOnly": {
                "variables": {
                    "input": {"type": "parameter", "units": "1", "default": 21.0},
                    "answer": {"type": "unknown", "units": "1"},
                },
                "equations": [
                    {"lhs": "answer", "rhs": {"op": "*", "args": [2.0, "input"]}},
                ],
                "tests": [{
                    "id": "no_such_variable",
                    "time_span": {"start": 0.0, "end": 0.0},
                    "assertions": [
                        {"variable": "ghost", "time": 0.0, "expected": 0.0},
                    ],
                }],
            }},
        });
        let file = load_string(&doc.to_string()).expect("doc loads");
        let results = run_inline_tests(&file, Some("ScalarOnly"), &tight_opts());
        assert_eq!(results.len(), 1);
        assert!(!results[0].passed);
        assert_eq!(
            results[0].actual, None,
            "a missing scalar must not report a value"
        );
        assert!(
            results[0].message.contains("ghost"),
            "the diagnostic must name the variable, got: {}",
            results[0].message
        );
    }

    #[test]
    fn run_inline_tests_decay_field() {
        let file = load_string(&decay_doc().to_string()).expect("decay doc loads");
        let results = run_inline_tests(&file, Some("M"), &tight_opts());
        assert_eq!(
            results.iter().map(|r| r.assertion_idx).collect::<Vec<_>>(),
            vec![1, 2, 3]
        );
        // t=0: the ic seeding IS the reference — identical evaluation
        // machinery on both sides, so the diff is exactly zero.
        assert!(results[0].passed, "t=0: {}", results[0].message);
        assert!(results[0].actual.unwrap() < 1e-14);
        // t=1: integrator-level error only.
        assert!(results[1].passed, "t=1: {}", results[1].message);
        assert!(results[1].actual.unwrap() < 1e-8);
        assert!(results[2].passed, "mean: {}", results[2].message);
        assert!(results[2].actual.unwrap().abs() < 1e-9);
        assert!(
            results
                .iter()
                .all(|r| matches!(r.reduce.as_deref(), Some("L2_error") | Some("mean")))
        );
        assert!(
            results
                .iter()
                .all(|r| r.model == "M" && r.test_id == "decay")
        );
    }

    /// esm-spec §6.6.5: the free variables of an inline `reference` are the
    /// field's DIMENSION NAMES, bound per cell to the 1-based index position.
    /// The analytic cell-centre form, a table lookup by the dimension name, the
    /// explicit gather, and a gather that REBINDS the dimension name as its own
    /// loop symbol must all read the same field.
    #[test]
    fn reference_binds_the_field_dimension_names() {
        let free_x = json!({"op": "cos", "args": [{"op": "*", "args": [
            std::f64::consts::PI,
            {"op": "/", "args": [{"op": "-", "args": ["x", 0.5]}, N]}]}]});
        let table: Vec<f64> = (1..=N)
            .map(|i| (std::f64::consts::PI * (i as f64 - 0.5) / N as f64).cos())
            .collect();
        let mut doc = decay_doc();
        doc["models"]["M"]["tests"][0]["assertions"] = json!([
            {"variable": "u", "time": 0.0, "expected": 0.0,
             "tolerance": {"abs": 1e-12}, "reduce": "L2_error", "reference": free_x},
            {"variable": "u", "time": 0.0, "expected": 0.0,
             "tolerance": {"abs": 1e-12}, "reduce": "Linf_error",
             "reference": {"op": "index", "args": [
                 {"op": "const", "args": [], "value": table}, "x"]}},
            {"variable": "u", "time": 0.0, "expected": 0.0,
             "tolerance": {"abs": 1e-12}, "reduce": "L2_error",
             "reference": {"op": "faq", "args": [], "output_idx": ["x"],
                           "ranges": {"x": {"from": "x"}}, "expr": free_x}},
            {"variable": "u", "time": 1.0, "expected": 0.0,
             "tolerance": {"abs": 1e-8}, "reduce": "L2_error",
             "reference": {"op": "*", "args": [{"op": "exp", "args": [-1]}, free_x]}},
        ]);
        let file = load_string(&doc.to_string()).expect("doc loads");
        let results = run_inline_tests(&file, Some("M"), &tight_opts());
        assert_eq!(results.len(), 4);
        for r in &results {
            assert!(r.passed, "assertion #{}: {}", r.assertion_idx, r.message);
        }
    }

    /// esm-spec §6.6.5 names what an analytic `reference` may read — the
    /// asserted field's DIMENSION NAMES, free, and the model's PARAMETERS —
    /// and `t` is neither.
    ///
    /// The build-time evaluator does not reject it: its time slot holds `0.0`,
    /// so a reference of `t` used to answer with the expression at the start of
    /// the span and report a plausible wrong number, in Rust, Julia and Python
    /// alike. FREE mention is the test, so a binder's own loop symbol is
    /// untouched, and so is a field whose declared `shape` names an index set
    /// called `t` — there `t` IS a dimension name.
    #[test]
    fn bind_dimension_names_rejects_a_free_time_variable() {
        let parse = |v: serde_json::Value| -> Expr { serde_json::from_value(v).unwrap() };
        let no_params: HashMap<String, f64> = HashMap::new();
        let no_arrays: HashSet<String> = HashSet::new();
        let free_t = parse(json!({"op": "*", "args": [1.0, "t"]}));
        let dims = vec!["x".to_string()];
        let err = bind_dimension_names(&free_t, &dims, &no_params, &no_arrays)
            .expect_err("`t` is not admissible in a reference");
        assert_eq!(err, REFERENCE_MENTIONS_TIME);
        assert!(err.contains("mentions `t`"), "{err}");
        assert!(err.contains("§6.6.5"), "{err}");
        // Refused on an UNSHAPED target too — the check runs before the
        // no-dimensions exit, so a reference of `t` is never evaluated.
        assert_eq!(
            bind_dimension_names(&free_t, &[], &no_params, &no_arrays)
                .expect_err("still not admissible"),
            REFERENCE_MENTIONS_TIME
        );
        // A field shaped over an index set NAMED `t`: §6.6.5 admits it as a
        // dimension name, so it WRAPS rather than refusing.
        let t_dims = vec!["t".to_string()];
        let Expr::Operator(node) = bind_dimension_names(&free_t, &t_dims, &no_params, &no_arrays)
            .expect("`t` is this field's dimension name")
        else {
            panic!("expected a faq wrapper");
        };
        assert_eq!(node.op, "faq");
        // A binder's own loop symbol is not a free mention.
        let bound = parse(json!({"op": "faq", "args": [], "output_idx": ["t"],
                                 "ranges": {"t": {"from": "x"}},
                                 "expr": {"op": "*", "args": [1.0, "t"]}}));
        assert_eq!(
            bind_dimension_names(&bound, &dims, &no_params, &no_arrays).expect("rebound"),
            bound
        );
    }

    #[test]
    fn bind_dimension_names_wraps_only_a_free_mention() {
        let dims = vec!["x".to_string()];
        let scope: HashMap<String, f64> = HashMap::from([("k".to_string(), 2.0)]);
        let parse = |v: serde_json::Value| -> Expr { serde_json::from_value(v).unwrap() };
        let no_arrays: HashSet<String> = HashSet::new();
        let bind = |e: &Expr, d: &[String]| {
            bind_dimension_names(e, d, &scope, &no_arrays).expect("no clash")
        };
        // No mention: untouched.
        let lit = parse(json!({"op": "*", "args": [2.0, "k"]}));
        assert_eq!(bind(&lit, &dims), lit);
        // Free mention: wrapped in an aggregate over the dimension names.
        let free = parse(json!({"op": "+", "args": ["x", 1]}));
        let Expr::Operator(node) = bind(&free, &dims) else {
            panic!("expected an aggregate wrapper");
        };
        assert_eq!(node.op, "faq");
        assert_eq!(node.output_idx.as_deref(), Some(&["x".to_string()][..]));
        assert_eq!(node.expr.as_deref(), Some(&free));
        // Bound mention (the gather rebinds `x`): untouched.
        let bound = parse(json!({"op": "faq", "args": [], "output_idx": ["x"],
                                 "ranges": {"x": {"from": "x"}},
                                 "expr": {"op": "+", "args": ["x", 1]}}));
        assert_eq!(bind(&bound, &dims), bound);
        // An integral's variable is a binder too.
        let integ = parse(
            json!({"op": "integral", "args": [{"op": "*", "args": [2, "x"]}],
                                 "var": "x", "lower": 0, "upper": 1}),
        );
        assert_eq!(bind(&integ, &dims), integ);
        // A `wrt` is a differentiation TARGET, not a free read of the scope.
        let deriv = parse(json!({"op": "D", "args": ["u"], "wrt": "x"}));
        assert_eq!(bind(&deriv, &dims), deriv);
        // Empty dims: untouched.
        assert_eq!(bind(&free, &[]), free);
    }

    /// A dimension name the parameter scope ALSO binds is a fault, not a silent
    /// rebinding: wrapping would shadow the parameter with the cell index, so
    /// the same reference that used to read the parameter would quietly return
    /// a different number. One name, two meanings, one scope — ill-formed.
    #[test]
    fn bind_dimension_names_rejects_a_dimension_that_shadows_a_parameter() {
        let dims = vec!["x".to_string()];
        let parse = |v: serde_json::Value| -> Expr { serde_json::from_value(v).unwrap() };
        let scope: HashMap<String, f64> = HashMap::from([("x".to_string(), 3.0)]);
        let free = parse(json!({"op": "+", "args": ["x", 1]}));
        let no_arrays: HashSet<String> = HashSet::new();
        let err =
            bind_dimension_names(&free, &dims, &scope, &no_arrays).expect_err("clash is a fault");
        assert!(err.contains("'x'"), "{err}");
        assert!(err.contains("a parameter"), "{err}");
        // A reference that does not mention it is unaffected — the clash only
        // matters where the wrap would actually rebind the name.
        let lit = parse(json!({"op": "*", "args": [2.0, "k"]}));
        assert_eq!(
            bind_dimension_names(&lit, &dims, &scope, &no_arrays).expect("no mention"),
            lit
        );
        // And a gather that rebinds `x` itself keeps working.
        let bound = parse(json!({"op": "faq", "args": [], "output_idx": ["x"],
                                 "ranges": {"x": {"from": "x"}},
                                 "expr": {"op": "+", "args": ["x", 1]}}));
        assert_eq!(
            bind_dimension_names(&bound, &dims, &scope, &no_arrays).expect("rebound"),
            bound
        );
    }

    /// esm-spec §6.6.5's clash scope is the WHOLE build-time scope, not the
    /// parameter half of it (issue #226). A build ARRAY named after a shape
    /// index set — an array `lev` over the index set `lev` — is a name a
    /// reference could already read, so wrapping it would rebind it to the
    /// cell's 1-based index: the same expression, a different number, no
    /// diagnostic. `array_scope_names` supplies the flattened names AND their
    /// unambiguous bare aliases, so `M.lev` clashes as `lev` too.
    #[test]
    fn bind_dimension_names_rejects_a_dimension_a_build_array_binds() {
        let dims = vec!["lev".to_string()];
        let parse = |v: serde_json::Value| -> Expr { serde_json::from_value(v).unwrap() };
        let no_params: HashMap<String, f64> = HashMap::new();
        let free = parse(json!({"op": "index", "args": ["table", "lev"]}));
        for names in [vec!["lev"], vec!["M.lev"]] {
            let arrays = array_scope_names(names.iter().copied());
            let err = bind_dimension_names(&free, &dims, &no_params, &arrays)
                .expect_err("clash is a fault");
            assert!(err.contains("'lev'"), "{err}");
            assert!(err.contains("a build-time array"), "{err}");
        }
        // An AMBIGUOUS bare alias is not in scope under either spelling, so it
        // does not clash — the same rule `param_scope_with_aliases` applies.
        let ambiguous = array_scope_names(["A.lev", "B.lev"]);
        assert!(!ambiguous.contains("lev"));
        let wrapped = bind_dimension_names(&free, &dims, &no_params, &ambiguous)
            .expect("no unambiguous alias, no clash");
        let Expr::Operator(node) = wrapped else {
            panic!("expected an aggregate wrapper");
        };
        assert_eq!(node.op, "faq");
        // A reference that does not mention the name is unaffected, and so is a
        // gather that rebinds it as its own loop symbol.
        let arrays = array_scope_names(["lev"]);
        let lit = parse(json!({"op": "*", "args": [2.0, "k"]}));
        assert_eq!(
            bind_dimension_names(&lit, &dims, &no_params, &arrays).expect("no mention"),
            lit
        );
        let bound = parse(json!({"op": "faq", "args": [], "output_idx": ["lev"],
                                 "ranges": {"lev": {"from": "lev"}},
                                 "expr": {"op": "index", "args": ["table", "lev"]}}));
        assert_eq!(
            bind_dimension_names(&bound, &dims, &no_params, &arrays).expect("rebound"),
            bound
        );
    }

    /// esm-spec §4.6 / §6.6.2: inside model `P`, `P.sub.g` is the fully
    /// qualified spelling of the mounted subsystem parameter the single-model
    /// array build carries as `sub.g`. It must resolve in an EQUATION and as a
    /// `parameter_overrides` key, in every spelling (`P.sub.g`, `sub.g`, `g`).
    #[test]
    fn self_qualified_subsystem_reference_and_override_spellings() {
        let mut doc = decay_doc();
        doc["models"]["P"] = doc["models"]["M"].take();
        doc["models"].as_object_mut().unwrap().remove("M");
        doc["models"]["P"]["subsystems"] = json!({"sub": {"variables": {
            "g": {"type": "parameter", "units": "1", "default": 9.81}}, "equations": []}});
        doc["models"]["P"]["variables"]["gg"] = json!({"type": "unknown", "units": "1"});
        doc["models"]["P"]["equations"]
            .as_array_mut()
            .unwrap()
            .push(json!({"lhs": "gg", "rhs": "P.sub.g"}));
        let assert_gg = |want: f64| json!([{"variable": "gg", "time": 0.0, "expected": want, "tolerance": {"rel": 1e-12}}]);
        doc["models"]["P"]["tests"] = json!([
            {"id": "default", "time_span": {"start": 0.0, "end": 1.0},
             "assertions": assert_gg(9.81)},
            {"id": "qualified", "time_span": {"start": 0.0, "end": 1.0},
             "parameter_overrides": {"P.sub.g": 1.5}, "assertions": assert_gg(1.5)},
            {"id": "relative", "time_span": {"start": 0.0, "end": 1.0},
             "parameter_overrides": {"sub.g": 2.5}, "assertions": assert_gg(2.5)},
            {"id": "bare", "time_span": {"start": 0.0, "end": 1.0},
             "parameter_overrides": {"g": 3.5}, "assertions": assert_gg(3.5)},
        ]);
        let file = load_string(&doc.to_string()).expect("doc loads");
        let results = run_inline_tests(&file, Some("P"), &tight_opts());
        assert_eq!(results.len(), 4);
        for r in &results {
            assert!(r.passed, "test {}: {}", r.test_id, r.message);
        }

        // esm-spec §6.6.2 rule 2 validates the LEADING segments: `Q` names no
        // component or subsystem, so the key is rejected instead of being
        // suffix-matched down onto `sub.g` and quietly driving it.
        doc["models"]["P"]["tests"] = json!([
            {"id": "typo", "time_span": {"start": 0.0, "end": 1.0},
             "parameter_overrides": {"Q.sub.g": 1.5}, "assertions": assert_gg(1.5)},
        ]);
        let file = load_string(&doc.to_string()).expect("doc loads");
        let results = run_inline_tests(&file, Some("P"), &tight_opts());
        assert_eq!(results.len(), 1);
        assert!(!results[0].passed, "a typo'd qualifier must not resolve");
    }

    #[test]
    fn run_inline_tests_reports_failing_assertion_with_actual() {
        let mut doc = decay_doc();
        // An impossible expectation: the decayed field cannot still match
        // its initial state at t=1 to 1e-12.
        doc["models"]["M"]["tests"][0]["assertions"] = json!([
            {"variable": "u", "time": 1.0, "expected": 0.0,
             "tolerance": {"abs": 1e-12}, "reduce": "L2_error",
             "reference": cos_pi_x()},
        ]);
        let file = load_string(&doc.to_string()).expect("doc loads");
        let results = run_inline_tests(&file, Some("M"), &tight_opts());
        assert_eq!(results.len(), 1);
        let r = &results[0];
        assert!(!r.passed);
        let want = 1.0 - (-1.0f64).exp();
        let actual = r.actual.expect("actual recorded on failure");
        assert!(
            (actual - want).abs() <= 1e-6 * want,
            "actual {actual} vs {want}"
        );
        assert!(r.message.contains("actual="));
    }

    #[test]
    fn coordinate_expression_ic_seeds_grid() {
        // The §11.4.1 case-3 seeding path in isolation: u(0) = cos(pi x_i).
        let file = load_string(&decay_doc().to_string()).expect("decay doc loads");
        let mut opts = tight_opts();
        opts.saveat = Some(vec![0.0]);
        let sol = crate::problem::esm_problem(
            &file,
            (0.0, 1.0),
            crate::problem::ProblemOptions {
                p: HashMap::new().clone(),
                u0: HashMap::new().clone(),
                rhs: crate::problem::Rhs::Always,
                ..Default::default()
            },
        )
        .and_then(|prob| crate::problem::solve(&prob, &opts))
        .expect("simulates");
        let cells = state_cells(&sol.state_variable_names, "u", "M");
        assert_eq!(cells.len(), N as usize);
        for (cell, row) in &cells {
            let want = (std::f64::consts::PI * (cell[0] as f64 - 0.5) / N as f64).cos();
            let got = sol.state[*row][0];
            assert!((got - want).abs() < 1e-15, "cell {cell:?}: {got} vs {want}");
        }
    }

    /// §6.6.5 assertions may target an ARRAY OBSERVED directly (a rule output
    /// surfaced "for direct assertion", like the MPAS `div_flux` max/min).
    /// Two sources, and the runner must answer from BOTH: a STATE-FREE
    /// observed's field is read from the BuildInspection's materialized setup
    /// arrays, while a STATE-DEPENDENT one (`h = u + 1`) is emitted by the
    /// array runtime as cell rows because the runner REQUESTS it — never a
    /// stale build-time snapshot, always the value at the asserted time.
    fn observed_assert_doc() -> serde_json::Value {
        let g = json!({"op": "faq", "args": [], "output_idx": ["i"],
                       "ranges": {"i": {"from": "x"}},
                       "expr": {"op": "*", "args": ["i", "i"]}});
        let h = json!({"op": "faq", "args": ["u"], "output_idx": ["i"],
                       "ranges": {"i": {"from": "x"}},
                       "expr": {"op": "+",
                                "args": [{"op": "index", "args": ["u", "i"]}, 1]}});
        json!({
            "esm": "1.1.0",
            "metadata": {"name": "observed_assertions"},
            "index_sets": {"x": {"kind": "interval", "size": 3}},
            "models": {"M": {
                "variables": {
                    "u": {"type": "unknown", "units": "1", "shape": ["x"]},
                    "g": {"type": "unknown", "units": "1", "shape": ["x"]},
                    "h": {"type": "unknown", "units": "1", "shape": ["x"]},
                },
                "equations": [
                {"lhs": "g", "rhs": g},
                {"lhs": "h", "rhs": h},
                    {"lhs": {"op": "ic", "args": ["u"]}, "rhs": 0.0},
                    {"lhs": {"op": "D", "args": ["u"], "wrt": "t"}, "rhs": 0.0},
                ],
                "tests": [{
                    "id": "obs",
                    "time_span": {"start": 0.0, "end": 1.0},
                    "assertions": [
                        {"variable": "g", "time": 1.0, "expected": 9.0,
                         "tolerance": {"abs": 1e-12}, "reduce": "max"},
                        {"variable": "g", "time": 1.0, "expected": 1.0,
                         "tolerance": {"abs": 1e-12}, "reduce": "min"},
                        {"variable": "h", "time": 1.0, "expected": 1.0,
                         "tolerance": {"abs": 1e-12}, "reduce": "max"},
                        {"variable": "h", "time": 1.0, "expected": 1.0,
                         "tolerance": {"abs": 1e-12}, "coords": {"x": 2}},
                        {"variable": "nope", "time": 1.0, "expected": 0.0,
                         "tolerance": {"abs": 1e-12}, "reduce": "max"},
                    ],
                }],
            }},
        })
    }

    #[test]
    fn array_observed_assertions_evaluate_directly() {
        let file = load_string(&observed_assert_doc().to_string()).expect("doc loads");
        let results = run_inline_tests(&file, Some("M"), &tight_opts());
        assert_eq!(results.len(), 5);
        // g = [1, 4, 9] (index arithmetic, exact) is STATE-FREE: max and min
        // pass with the exact reductions recorded.
        assert!(results[0].passed, "g max: {}", results[0].message);
        assert_eq!(results[0].actual, Some(9.0));
        assert!(results[1].passed, "g min: {}", results[1].message);
        assert_eq!(results[1].actual, Some(1.0));
        // h = u + 1 reads the state, so its field exists only on the
        // trajectory: with `u` held at 0 it is [1, 1, 1] at every time, and
        // both the reduce and the coords form must read it there. esm-spec
        // §6.6.5 admits any shaped variable in these forms; before this it
        // errored with "has no cells in var_map" because only the state-free
        // observeds reach a build inspection.
        assert!(results[2].passed, "h max: {}", results[2].message);
        assert_eq!(results[2].actual, Some(1.0));
        assert!(results[3].passed, "h at x=2: {}", results[3].message);
        assert_eq!(results[3].actual, Some(1.0));
        // A name that is no variable of the component at all still errors —
        // the request list is a best effort, never an invention.
        assert!(!results[4].passed);
        assert!(
            results[4].message.contains("has no cells in var_map"),
            "unexpected message: {}",
            results[4].message
        );
        assert_eq!(results[4].actual, None);
    }

    // -----------------------------------------------------------------------
    // §6.6.5 coords point-sampling (pinned convention: 1-based INDEX space,
    // nearest grid index, exact half-way ties round DOWN)
    // -----------------------------------------------------------------------

    fn coords_assert(coords: serde_json::Value, time: f64, expected: f64) -> serde_json::Value {
        json!({"variable": "u", "time": time, "expected": expected,
               "tolerance": {"abs": 1e-9}, "coords": coords})
    }

    fn decay_doc_with(assertions: serde_json::Value) -> serde_json::Value {
        let mut doc = decay_doc();
        doc["models"]["M"]["tests"][0]["assertions"] = assertions;
        doc
    }

    #[test]
    fn run_inline_tests_coords_sampling_nearest_ties_down() {
        let u = |i: f64| (std::f64::consts::PI * (i - 0.5) / N as f64).cos();
        let mut doc = decay_doc_with(json!([
            coords_assert(json!({"x": 3}), 0.0, u(3.0)),
            coords_assert(json!({"x": 3.5}), 0.0, u(3.0)), // tie → lower index 3
            coords_assert(json!({"x": 2.5}), 0.0, u(2.0)), // tie → 2
            coords_assert(json!({"x": 5.6}), 0.0, u(6.0)), // nearest → 6
            coords_assert(json!({"x": 8.5}), 0.0, u(8.0)), // tie at top edge → 8
        ]));
        doc["models"]["M"]["tests"][0]["assertions"]
            .as_array_mut()
            .unwrap()
            .push({
                let mut a = coords_assert(json!({"x": 3}), 1.0, (-1.0f64).exp() * u(3.0));
                a["tolerance"] = json!({"abs": 1e-8});
                a
            });
        let file = load_string(&doc.to_string()).expect("doc loads");
        let results = run_inline_tests(&file, Some("M"), &tight_opts());
        assert_eq!(results.len(), 6);
        for r in &results {
            assert!(r.passed, "assertion {}: {}", r.assertion_idx, r.message);
            assert!(r.reduce.is_none());
        }
        assert_eq!(results[0].actual, results[1].actual);
    }

    #[test]
    fn run_inline_tests_coords_validation_rejections() {
        let file = load_string(
            &decay_doc_with(json!([
                coords_assert(json!({"y": 1.0}), 0.0, 0.0),
                coords_assert(json!({"x": 0.4}), 0.0, 0.0), // → index 0
                coords_assert(json!({"x": 8.6}), 0.0, 0.0), // → index 9
            ]))
            .to_string(),
        )
        .expect("doc loads");
        let results = run_inline_tests(&file, Some("M"), &tight_opts());
        assert_eq!(results.len(), 3);
        for r in &results {
            assert!(!r.passed);
            assert_eq!(r.actual, None);
        }
        assert!(results[0].message.contains("names unknown dimension 'y'"));
        assert!(results[1].message.contains("outside 1..8"));
        assert!(results[1].message.contains("resolves to index 0"));
        assert!(results[2].message.contains("resolves to index 9"));
    }

    #[test]
    fn run_inline_tests_coords_on_scalar_variable_rejected() {
        // coords on a scalar (0-D) variable is ill-formed per §6.6.5.
        let doc = json!({
            "esm": "1.1.0",
            "metadata": {"name": "scalar_coords"},
            "models": {"M": {
                "variables": {"z": {"type": "unknown", "units": "1", "default": 1.0}},
                "equations": [
                    {"lhs": {"op": "D", "args": ["z"], "wrt": "t"}, "rhs": 0.0}],
                "tests": [{
                    "id": "scalar",
                    "time_span": {"start": 0.0, "end": 1.0},
                    "assertions": [{"variable": "z", "time": 1.0, "expected": 1.0,
                                    "tolerance": {"abs": 1e-9},
                                    "coords": {"x": 1.0}}],
                }],
            }},
        });
        let file = load_string(&doc.to_string()).expect("doc loads");
        let results = run_inline_tests(&file, Some("M"), &tight_opts());
        assert_eq!(results.len(), 1);
        assert!(!results[0].passed);
        assert!(
            results[0]
                .message
                .contains("requires a spatially-shaped variable"),
            "unexpected message: {}",
            results[0].message
        );
    }

    #[test]
    fn coords_and_reduce_are_mutually_exclusive_at_load() {
        let doc = decay_doc_with(json!([
            {"variable": "u", "time": 0.0, "expected": 0.0,
             "coords": {"x": 1}, "reduce": "mean"},
        ]));
        assert!(load_string(&doc.to_string()).is_err(), "schema must reject");
    }

    /// du_ij/dt = 1 with u(0) = 0, so u(t) = t everywhere: pins the
    /// strict-subset rule — pinning only `x` is legal iff `y` is singleton.
    fn doc_2d(ny: i64) -> serde_json::Value {
        let idx = json!({"op": "index", "args": ["u", "i", "j"]});
        let ranges = json!({"i": [1, 4], "j": [1, ny]});
        json!({
            "esm": "1.1.0",
            "metadata": {"name": "pde_inline_2d"},
            "index_sets": {"x": {"kind": "interval", "size": 4},
                           "y": {"kind": "interval", "size": ny}},
            "models": {"M": {
                "variables": {"u": {"type": "unknown", "units": "1",
                                    "shape": ["x", "y"]}},
                "equations": [
                    {"lhs": {"op": "ic", "args": ["u"]}, "rhs": 0.0},
                    {"lhs": {"op": "faq", "args": [],
                             "output_idx": ["i", "j"], "ranges": ranges,
                             "expr": {"op": "D", "args": [idx], "wrt": "t"}},
                     "rhs": {"op": "faq", "args": [],
                             "output_idx": ["i", "j"], "ranges": ranges,
                             "expr": 1.0}},
                ],
                "tests": [{
                    "id": "subset",
                    "time_span": {"start": 0.0, "end": 1.0},
                    "assertions": [{"variable": "u", "time": 1.0,
                                    "expected": 1.0,
                                    "tolerance": {"abs": 1e-8},
                                    "coords": {"x": 2}}],
                }],
            }},
        })
    }

    #[test]
    fn coords_strict_subset_requires_singleton_remainder() {
        let ok_file = load_string(&doc_2d(1).to_string()).expect("doc loads");
        let ok = run_inline_tests(&ok_file, Some("M"), &tight_opts());
        assert_eq!(ok.len(), 1);
        assert!(ok[0].passed, "{}", ok[0].message);
        assert!((ok[0].actual.unwrap() - 1.0).abs() < 1e-8);

        let bad_file = load_string(&doc_2d(3).to_string()).expect("doc loads");
        let bad = run_inline_tests(&bad_file, Some("M"), &tight_opts());
        assert_eq!(bad.len(), 1);
        assert!(!bad[0].passed);
        assert!(
            bad[0]
                .message
                .contains("leaves dimension 'y' unpinned with 3 samples"),
            "unexpected message: {}",
            bad[0].message
        );
    }

    // -----------------------------------------------------------------------
    // §6.6.5 from_file references (pinned convention: path relative to the
    // .esm file's directory / explicit base_dir; v1 format json — row-major
    // nested array in field shape)
    // -----------------------------------------------------------------------

    fn from_file_assert(reference: serde_json::Value, reduce: &str) -> serde_json::Value {
        json!({"variable": "u", "time": 0.0, "expected": 0.0,
               "tolerance": {"abs": 1e-12}, "reduce": reduce,
               "reference": reference})
    }

    fn ic_cos_values() -> Vec<f64> {
        (1..=N)
            .map(|i| (std::f64::consts::PI * (i as f64 - 0.5) / N as f64).cos())
            .collect()
    }

    #[test]
    fn from_file_reference_happy_path() {
        let dir = tempfile::tempdir().expect("tempdir");
        std::fs::write(
            dir.path().join("ref.json"),
            serde_json::to_string(&ic_cos_values()).unwrap(),
        )
        .unwrap();
        let doc = decay_doc_with(json!([
            from_file_assert(json!({"type": "from_file", "path": "ref.json"}), "L2_error"),
            from_file_assert(
                json!({"type": "from_file", "path": "ref.json", "format": "json"}),
                "Linf_error"
            ),
        ]));
        let file = load_string(&doc.to_string()).expect("doc loads");
        let results =
            run_inline_tests_with_base_dir(&file, Some("M"), &tight_opts(), Some(dir.path()));
        assert_eq!(results.len(), 2);
        // Identical evaluation machinery seeded the ic, so the diff is 0.
        for r in &results {
            assert!(r.passed, "assertion {}: {}", r.assertion_idx, r.message);
            assert_eq!(r.actual, Some(0.0));
        }
    }

    #[test]
    fn from_file_reference_shape_mismatch() {
        let dir = tempfile::tempdir().expect("tempdir");
        let vals = ic_cos_values();
        std::fs::write(
            dir.path().join("short.json"),
            serde_json::to_string(&vals[..7]).unwrap(),
        )
        .unwrap();
        let file = load_string(
            &decay_doc_with(json!([from_file_assert(
                json!({"type": "from_file", "path": "short.json"}),
                "L2_error"
            )]))
            .to_string(),
        )
        .expect("doc loads");
        let r =
            &run_inline_tests_with_base_dir(&file, Some("M"), &tight_opts(), Some(dir.path()))[0];
        assert!(!r.passed);
        assert!(
            r.message
                .contains("shape mismatch along dimension 1: expected length 8, found 7"),
            "unexpected message: {}",
            r.message
        );

        // Deeper nesting than the field's rank.
        let nested: Vec<Vec<f64>> = vals.iter().map(|&v| vec![v]).collect();
        std::fs::write(
            dir.path().join("deep.json"),
            serde_json::to_string(&nested).unwrap(),
        )
        .unwrap();
        let file = load_string(
            &decay_doc_with(json!([from_file_assert(
                json!({"type": "from_file", "path": "deep.json"}),
                "L2_error"
            )]))
            .to_string(),
        )
        .expect("doc loads");
        let r =
            &run_inline_tests_with_base_dir(&file, Some("M"), &tight_opts(), Some(dir.path()))[0];
        assert!(!r.passed);
        assert!(
            r.message.contains("expected a number"),
            "unexpected message: {}",
            r.message
        );
    }

    #[test]
    fn from_file_reference_missing_file_and_format() {
        let dir = tempfile::tempdir().expect("tempdir");
        let file = load_string(
            &decay_doc_with(json!([from_file_assert(
                json!({"type": "from_file", "path": "nope.json"}),
                "L2_error"
            )]))
            .to_string(),
        )
        .expect("doc loads");
        let r =
            &run_inline_tests_with_base_dir(&file, Some("M"), &tight_opts(), Some(dir.path()))[0];
        assert!(!r.passed);
        assert!(
            r.message.contains("file not found"),
            "unexpected message: {}",
            r.message
        );

        std::fs::write(dir.path().join("ref.json"), "[1,2,3,4,5,6,7,8]").unwrap();
        let file = load_string(
            &decay_doc_with(json!([from_file_assert(
                json!({"type": "from_file", "path": "ref.json", "format": "netcdf"}),
                "L2_error"
            )]))
            .to_string(),
        )
        .expect("doc loads");
        let r =
            &run_inline_tests_with_base_dir(&file, Some("M"), &tight_opts(), Some(dir.path()))[0];
        assert!(!r.passed);
        assert!(
            r.message.contains("format 'netcdf' is not supported"),
            "unexpected message: {}",
            r.message
        );
    }

    // -----------------------------------------------------------------------
    // Shared executable fixture (identical input across the three bindings)
    // -----------------------------------------------------------------------

    #[test]
    fn shared_fixture_pde_inline_assertions_exec() {
        let fixture = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("../../tests/spatial/pde_inline_assertions_exec.esm");
        assert!(fixture.is_file(), "missing shared fixture {fixture:?}");
        let text = std::fs::read_to_string(&fixture).expect("fixture reads");
        let file = load_string(&text).expect("fixture loads");
        let results =
            run_inline_tests_with_base_dir(&file, Some("M"), &tight_opts(), fixture.parent());
        assert_eq!(results.len(), 7);
        for r in &results {
            assert!(r.passed, "assertion {}: {}", r.assertion_idx, r.message);
        }
        // The two tie-sampling coords assertions hit the SAME cell.
        assert_eq!(results[0].actual, results[1].actual);
        // integral == mean == 0 for the symmetric cosine field.
        assert!(results[4].actual.unwrap().abs() < 1e-12);
        // from_file error norms are ~0 against the committed exact snapshot.
        assert!(results[5].actual.unwrap() < 1e-12);
        assert!(results[6].actual.unwrap() < 1e-12);
    }

    /// Two coupled components, each with a scalar observed `k = a·T` and a
    /// trivial spatial state `x`. The bare name `k` is shared across `M1` and
    /// `M2` — flattening qualifies them `M1.k` / `M2.k` and the array runtime
    /// exposes both scalar observeds on the trajectory (a size-1 spatial state
    /// routes the coupled file through that runtime). `M1` (a=2) is laid out
    /// first, so `M1.k` precedes `M2.k`.
    fn scalar_observed_coupled_doc() -> serde_json::Value {
        let comp = |a: f64, tests: serde_json::Value| -> serde_json::Value {
            let idx = json!({"op": "index", "args": ["x", "i"]});
            json!({
                "variables": {
                    "T": {"type": "parameter", "units": "K", "default": 10.0},
                    "a": {"type": "parameter", "units": "1", "default": a},
                    "x": {"type": "unknown", "units": "1", "shape": ["s"]},
                    "k": {"type": "unknown", "units": "1"},
                },
                "equations": [
                {"lhs": "k", "rhs": {"op": "*", "args": ["a", "T"]}},
                    {"lhs": {"op": "ic", "args": ["x"]}, "rhs": 0.0},
                    {"lhs": {"op": "faq", "args": [], "output_idx": ["i"],
                             "ranges": {"i": [1, 1]},
                             "expr": {"op": "D", "args": [idx], "wrt": "t"}},
                     "rhs": {"op": "faq", "args": [], "output_idx": ["i"],
                             "ranges": {"i": [1, 1]}, "expr": 0.0}},
                ],
                "tests": tests,
            })
        };
        json!({
            "esm": "1.1.0",
            "metadata": {"name": "scalar_observed_param_override"},
            "index_sets": {"s": {"kind": "interval", "size": 1}},
            "models": {
                // M1 (a=2) is laid out first, so its `k` shadows M2's under a
                // bare-name-only slot match — the exact bug this guards.
                "M1": comp(2.0, json!([])),
                "M2": comp(5.0, json!([
                    {"id": "t_lo", "time_span": {"start": 0.0, "end": 1.0},
                     "parameter_overrides": {"M2.T": 10.0},
                     "assertions": [{"variable": "k", "time": 1.0,
                                     "expected": 50.0,
                                     "tolerance": {"rel": 1e-9}}]},
                    {"id": "t_hi", "time_span": {"start": 0.0, "end": 1.0},
                     "parameter_overrides": {"M2.T": 20.0},
                     "assertions": [{"variable": "k", "time": 1.0,
                                     "expected": 100.0,
                                     "tolerance": {"rel": 1e-9}}]},
                ])),
            },
        })
    }

    /// Regression for the cross-binding scalar-observed slot-resolution bug
    /// (mirror of the Python `test_run_inline_tests_scalar_observed_tracks_
    /// parameter_overrides`). Each of M2's two tests overrides its own `T`, so
    /// a correct runner reads `M2.k = 5·T` (50, then 100) — distinct per test.
    /// The pre-fix single-pass `scalar_slot` returned the FIRST bare-`k` slot
    /// (`M1.k = 2·T = 20`) for every M2 assertion, so both tests read 20 and
    /// failed; the qualified-first two-pass resolver reads `M2.k`.
    #[test]
    fn run_inline_tests_scalar_observed_tracks_parameter_overrides() {
        let file = load_string(&scalar_observed_coupled_doc().to_string()).expect("doc loads");
        let results = run_inline_tests(&file, Some("M2"), &tight_opts());
        let by_id: HashMap<&str, &AssertionResult> =
            results.iter().map(|r| (r.test_id.as_str(), r)).collect();
        assert_eq!(by_id.len(), 2, "expected the two M2 tests");
        let lo = by_id["t_lo"].actual.expect("t_lo actual recorded");
        let hi = by_id["t_hi"].actual.expect("t_hi actual recorded");
        // Each override must flow through to M2.k = 5·T, distinct per test —
        // not M1.k (= 2·T = 20) and not a single shared value.
        assert!(
            (lo - 50.0).abs() <= 1e-9 * 50.0,
            "t_lo actual {lo}, want 50"
        );
        assert!(
            (hi - 100.0).abs() <= 1e-9 * 100.0,
            "t_hi actual {hi}, want 100"
        );
        assert_ne!(lo, hi);
        assert!(
            results.iter().all(|r| r.passed),
            "{:?}",
            results
                .iter()
                .map(|r| (r.test_id.clone(), r.message.clone()))
                .collect::<Vec<_>>()
        );
    }

    // -----------------------------------------------------------------
    // Issue #194: reaction-system coverage and the per-document options hook
    // -----------------------------------------------------------------

    /// A first-order decay written as a REACTION SYSTEM: A → B at rate k·[A],
    /// so A(t) = e^{-kt} and B(t) = 1 − e^{-kt} exactly.
    ///
    /// `reaction_systems` carries the same `tests` member `models` does
    /// (esm-spec §6.6), and this runner iterated `models` alone until issue
    /// #194 — so every assertion of a chemical mechanism was skipped, and
    /// skipped SILENTLY, since a component that produced no rows is
    /// indistinguishable in the result list from one that was never looked at.
    fn reaction_decay_doc() -> serde_json::Value {
        json!({
            "esm": "1.1.0",
            "metadata": {"name": "inline_test_reaction_system"},
            "reaction_systems": {"Decay": {
                "species": {
                    "A": {"units": "mol/mol", "default": 1.0},
                    "B": {"units": "mol/mol", "default": 0.0},
                },
                "parameters": {"k": {"units": "1/s", "default": 1.0}},
                "reactions": [{
                    "id": "R1",
                    "substrates": [{"species": "A", "stoichiometry": 1}],
                    "products": [{"species": "B", "stoichiometry": 1}],
                    "rate": "k",
                }],
                "tests": [{
                    "id": "decays",
                    "time_span": {"start": 0.0, "end": 1.0},
                    "assertions": [
                        {"variable": "A", "time": 1.0,
                         "expected": std::f64::consts::E.recip(),
                         "tolerance": {"rel": 1e-6}},
                        {"variable": "B", "time": 1.0,
                         "expected": 1.0 - std::f64::consts::E.recip(),
                         "tolerance": {"rel": 1e-6}},
                    ],
                }],
            }},
        })
    }

    #[test]
    fn run_inline_tests_covers_reaction_systems() {
        let file = load_string(&reaction_decay_doc().to_string()).expect("doc loads");
        let results = run_inline_tests(&file, None, &tight_opts());
        // Two assertions, both from a component that is NOT a `models` entry.
        assert_eq!(results.len(), 2, "{results:?}");
        assert!(results.iter().all(|r| r.model == "Decay"));
        assert_eq!(
            results
                .iter()
                .map(|r| r.variable.as_str())
                .collect::<Vec<_>>(),
            vec!["A", "B"]
        );
        assert!(
            results.iter().all(|r| r.passed),
            "{:?}",
            results
                .iter()
                .map(|r| (r.variable.clone(), r.message.clone()))
                .collect::<Vec<_>>()
        );
    }

    /// `D(y)/dt = T` from `y(0) = 0`, so `y(1) = T` exactly whatever `T` is.
    /// The assertion's `expected` is therefore a direct read-out of the `T` the
    /// run actually used — which is what makes it a probe for where an override
    /// came from.
    fn ramp_doc(expected: f64, test_overrides: Option<serde_json::Value>) -> serde_json::Value {
        let mut test = json!({
            "id": "ramp",
            "time_span": {"start": 0.0, "end": 1.0},
            "assertions": [{"variable": "y", "time": 1.0,
                            "expected": expected, "tolerance": {"rel": 1e-9}}],
        });
        if let Some(ov) = test_overrides {
            test["parameter_overrides"] = ov;
        }
        json!({
            "esm": "1.1.0",
            "metadata": {"name": "ramp"},
            "models": {"M": {
                "variables": {
                    "T": {"type": "parameter", "units": "1", "default": 1.0},
                    "y": {"type": "unknown", "units": "1", "default": 0.0},
                },
                "equations": [{"lhs": {"op": "D", "args": ["y"], "wrt": "t"}, "rhs": "T"}],
                "tests": [test],
            }},
        })
    }

    fn write_doc(dir: &Path, name: &str, doc: &serde_json::Value) {
        std::fs::write(dir.join(name), doc.to_string()).expect("fixture written");
    }

    /// The issue's key ask: site policy lives in the CALLER. Two documents in
    /// one directory, each needing a different parameter, and one callback that
    /// knows which is which — with nothing document-specific reaching this
    /// module.
    #[test]
    fn run_inline_tests_paths_consults_options_for_per_document() {
        let dir = tempfile::tempdir().expect("tempdir");
        write_doc(dir.path(), "a.esm", &ramp_doc(3.0, None));
        write_doc(dir.path(), "b.esm", &ramp_doc(7.0, None));

        let options_for = |path: &Path| {
            let seed = match path.file_name().and_then(|n| n.to_str()) {
                Some("a.esm") => 3.0,
                _ => 7.0,
            };
            InlineTestOptions {
                solve: tight_opts(),
                parameter_overrides: HashMap::from([("T".to_string(), InlineValue::Scalar(seed))]),
                ..Default::default()
            }
        };
        // A DIRECTORY expands to the .esm files under it, sorted.
        let results = run_inline_tests_paths(&[dir.path()], &options_for);
        assert_eq!(results.len(), 2, "{results:?}");
        assert!((results[0].actual.expect("a actual") - 3.0).abs() <= 1e-9 * 3.0);
        assert!((results[1].actual.expect("b actual") - 7.0).abs() <= 1e-9 * 7.0);
        assert!(results.iter().all(|r| r.passed), "{results:?}");

        // Without the seeds both documents run at T's default of 1.0 and both
        // assertions fail — so the callback is load-bearing, not decorative.
        let bare = run_inline_tests_paths(&[dir.path()], &|_p| InlineTestOptions {
            solve: tight_opts(),
            ..Default::default()
        });
        assert!(bare.iter().all(|r| !r.passed), "{bare:?}");
    }

    /// A seed supplies what the document left unsaid; it never overrules what
    /// the document said. The test names `T = 5` and the caller seeds
    /// `T = 99`, so `y(1)` must be 5.
    #[test]
    fn run_inline_tests_paths_seed_yields_to_the_tests_own_override() {
        let dir = tempfile::tempdir().expect("tempdir");
        write_doc(
            dir.path(),
            "seeded.esm",
            &ramp_doc(5.0, Some(json!({"T": 5.0}))),
        );
        let results = run_inline_tests_paths(&[dir.path()], &|_p| InlineTestOptions {
            solve: tight_opts(),
            parameter_overrides: HashMap::from([("T".to_string(), InlineValue::Scalar(99.0))]),
            ..Default::default()
        });
        assert_eq!(results.len(), 1, "{results:?}");
        let actual = results[0].actual.expect("actual recorded");
        assert!(
            (actual - 5.0).abs() <= 1e-9 * 5.0,
            "actual {actual}, want 5"
        );
        assert!(results[0].passed, "{}", results[0].message);
    }

    /// One bad file must not cost a corpus run every other file's verdicts —
    /// and must not vanish either, which would be indistinguishable from a
    /// pass.
    #[test]
    fn run_inline_tests_paths_records_an_unreadable_document_as_a_row() {
        let dir = tempfile::tempdir().expect("tempdir");
        write_doc(dir.path(), "good.esm", &ramp_doc(1.0, None));
        std::fs::write(dir.path().join("bad.esm"), "{ not json").expect("bad fixture");
        let results = run_inline_tests_paths(&[dir.path()], &|_p| InlineTestOptions {
            solve: tight_opts(),
            ..Default::default()
        });
        assert_eq!(results.len(), 2, "{results:?}");
        let load_row = results
            .iter()
            .find(|r| r.test_id == "<load>")
            .expect("a <load> row for the unreadable document");
        assert!(load_row.model.ends_with("bad.esm"), "{}", load_row.model);
        assert!(!load_row.passed);
        assert!(
            load_row.message.contains("load failed"),
            "{}",
            load_row.message
        );
        let good = results
            .iter()
            .find(|r| r.test_id == "ramp")
            .expect("the good document still ran");
        assert!(good.passed, "{}", good.message);
    }

    /// Mirrors the Julia testset "a batch's rows name the document they came
    /// from". Results from a multi-document run were indistinguishable: every
    /// row carried the same `model` / `test_id` and nothing naming the
    /// document, so a corpus sweep could report a failure without saying which
    /// file failed — while a LOAD failure named its path, making the two halves
    /// of one run inconsistent with each other.
    #[test]
    fn run_inline_tests_paths_rows_name_the_document_they_came_from() {
        let dir = tempfile::tempdir().expect("tempdir");
        write_doc(dir.path(), "a.esm", &ramp_doc(3.0, Some(json!({"T": 3.0}))));
        write_doc(dir.path(), "b.esm", &ramp_doc(7.0, Some(json!({"T": 7.0}))));
        let opts = |_p: &Path| InlineTestOptions {
            solve: tight_opts(),
            ..Default::default()
        };

        let results = run_inline_tests_paths(&[dir.path()], &opts);
        assert_eq!(results.len(), 2, "{results:?}");
        assert!(results.iter().all(|r| r.passed), "{results:?}");
        // Two rows that are otherwise identical — same component, same test id,
        // same assertion index — are told apart by their document alone.
        assert_eq!(results[0].model, results[1].model);
        assert_eq!(results[0].test_id, results[1].test_id);
        let a = &results[0];
        let b = &results[1];
        assert_eq!(Path::new(&a.file), dir.path().join("a.esm"));
        assert_eq!(Path::new(&b.file), dir.path().join("b.esm"));
        assert!((a.actual.expect("a actual") - 3.0).abs() <= 1e-9 * 3.0);
        assert!((b.actual.expect("b actual") - 7.0).abs() <= 1e-9 * 7.0);

        // An unreadable document in the same batch still contributes its own
        // named row rather than ending the run — and names itself in `file`,
        // the field every other row of the batch now uses, as well as in
        // `model`, where it always has.
        std::fs::write(dir.path().join("broken.esm"), "{ not json").expect("bad fixture");
        let mixed = run_inline_tests_paths(&[dir.path()], &opts);
        let load_row = mixed
            .iter()
            .find(|r| r.test_id == "<load>")
            .expect("a <load> row for the unreadable document");
        assert_eq!(Path::new(&load_row.file), dir.path().join("broken.esm"));
        assert_eq!(load_row.model, load_row.file);
        assert!(!load_row.passed);
        assert!(
            mixed
                .iter()
                .any(|r| Path::new(&r.file) == dir.path().join("a.esm") && r.passed),
            "{mixed:?}"
        );
    }

    /// A document handed over ALREADY PARSED has no path, so its rows carry the
    /// empty string rather than inventing one — the same convention as the
    /// Julia and Python bindings.
    #[test]
    fn an_already_loaded_document_leaves_the_row_file_empty() {
        let file = load_string(&decay_doc().to_string()).expect("decay doc loads");
        let results = run_inline_tests(&file, None, &tight_opts());
        assert!(!results.is_empty());
        assert!(results.iter().all(|r| r.file.is_empty()), "{results:?}");
    }

    /// The LAST-RESORT retry is paid ONCE PER [`BuildKey`], not once per test.
    ///
    /// A SHAPED state-free document reaches the dead end this branch answers:
    /// `static_trajectory` cannot serve it (the array runtime carries no
    /// scalar observed graph), `solve` refuses it, and the only answer left is
    /// a second whole-document build with the pipeline on. That retry lives
    /// inside the per-test loop, so without the memo on `BuiltModel` a
    /// document with N such tests would pay N whole-document builds for one
    /// set of fields that answers all N.
    ///
    /// The three tests below share a `BuildKey` — no imports, one span, no
    /// overrides — and the fourth differs only in its span, which the key
    /// covers. Two builds, not four, and not one: a key that changed must
    /// still rebuild, because the fields are materialized at `tspan.0`.
    ///
    /// Under the interpreter, which is where the retry is still the route: a
    /// strict compiler answers from the problem's own compiled model first
    /// (`a_strict_compiler_answers_a_shaped_static_document_from_its_own_model`).
    #[test]
    fn the_last_resort_retry_is_built_once_per_build_key() {
        let test = |id: &str, end: f64| {
            json!({
                "id": id,
                "time_span": {"start": 0.0, "end": end},
                "tolerance": {"rel": 1e-9, "abs": 1e-11},
                "assertions": [
                    {"variable": "g", "time": 0.0, "coords": {"x": 2},
                     "expected": 4.0},
                    // Away from `tspan.0`, so the solve this document cannot
                    // survive is actually attempted: over an empty state
                    // vector a span the integrator never has to step across
                    // succeeds trivially, and the dead end is never reached.
                    {"variable": "g", "time": end / 2.0, "coords": {"x": 2},
                     "expected": 4.0},
                ],
            })
        };
        let doc = json!({
            "esm": "1.1.0",
            "metadata": {"name": "ShapedStatic", "license": "MIT",
                         "description": "state-free, shaped, time-invariant"},
            "index_sets": {"x": {"kind": "interval", "size": 3}},
            "models": {"ShapedStatic": {
                "variables": {
                    "a": {"type": "parameter", "units": "1", "default": 2.0},
                    "g": {"type": "unknown", "units": "1", "shape": ["x"]},
                },
                "equations": [
                    {"lhs": "g",
                     "rhs": {"op": "faq", "args": [], "output_idx": ["i"],
                             "ranges": {"i": {"from": "x"}},
                             "expr": {"op": "*", "args": ["a", "i"]}}},
                ],
                "tests": [
                    test("one", 10.0),
                    test("two", 10.0),
                    test("three", 10.0),
                    test("another_span", 20.0),
                ],
            }},
        });
        let file = load_string(&doc.to_string()).expect("document loads");
        let before = BUILD_PIPELINE_BUILDS.with(std::cell::Cell::get);
        let results = run_inline_tests_with_options(
            &file,
            &InlineTestOptions {
                compiler: Some(crate::problem::Compiler::Interpreter),
                ..Default::default()
            },
            None,
        );
        let builds = BUILD_PIPELINE_BUILDS.with(std::cell::Cell::get) - before;
        // Non-vacuity: every test must actually have reached the dead end and
        // been answered from the retry's fields. A document answered some
        // other way would report zero builds and pass the count trivially.
        assert_eq!(results.len(), 8, "{results:?}");
        for r in &results {
            assert!(
                r.passed,
                "{}: {} (actual {:?})",
                r.test_id, r.message, r.actual
            );
        }
        assert_eq!(
            builds, 2,
            "four tests over two `BuildKey`s must pay two whole-document \
             builds: one per key, reused by the tests sharing it"
        );
    }

    /// A shaped state-free document with a running sum beside its field —
    /// `cum[i] = Σ_{j ≤ i} g[j]`, a prefix scan the build pipeline's reference
    /// evaluator sweeps cell by cell.
    fn shaped_static_with_cumulative() -> serde_json::Value {
        json!({
            "esm": "1.1.0",
            "metadata": {"name": "ShapedStaticCumulative", "license": "MIT",
                         "description": "state-free, shaped, with a running sum"},
            "index_sets": {"x": {"kind": "interval", "size": 3}},
            "models": {"ShapedStaticCumulative": {
                "variables": {
                    "a": {"type": "parameter", "units": "1", "default": 2.0},
                    "g": {"type": "unknown", "units": "1", "shape": ["x"]},
                    "cum": {"type": "unknown", "units": "1", "shape": ["x"]},
                },
                "equations": [
                    {"lhs": "g",
                     "rhs": {"op": "faq", "args": [], "output_idx": ["i"],
                             "ranges": {"i": {"from": "x"}},
                             "expr": {"op": "*", "args": ["a", "i"]}}},
                    {"lhs": "cum",
                     "rhs": {"op": "faq", "args": [], "output_idx": ["i"],
                             "ranges": {"i": {"from": "x"}, "j": {"from": "x"}},
                             "filter": {"op": "<=", "args": ["j", "i"]},
                             "expr": {"op": "index", "args": ["g", "j"]}}},
                ],
                "tests": [{
                    "id": "values",
                    "time_span": {"start": 0.0, "end": 10.0},
                    "tolerance": {"rel": 1e-9, "abs": 1e-11},
                    "assertions": [
                        {"variable": "g", "time": 5.0, "coords": {"x": 2},
                         "expected": 4.0},
                        {"variable": "cum", "time": 5.0, "coords": {"x": 3},
                         "expected": 12.0},
                    ],
                }],
            }},
        })
    }

    /// Under `native`, a shaped state-free document is answered from the
    /// problem's OWN compiled model — the tape — and never from a pipeline
    /// rebuild through the reference evaluator (issue #484), so no retry is
    /// built at all.
    #[test]
    fn a_strict_compiler_answers_a_shaped_static_document_from_its_own_model() {
        let file = load_string(&shaped_static_with_cumulative().to_string()).expect("loads");
        let before = BUILD_PIPELINE_BUILDS.with(std::cell::Cell::get);
        let results = run_inline_tests_with_options(
            &file,
            &InlineTestOptions {
                compiler: Some(crate::problem::Compiler::Native),
                ..Default::default()
            },
            None,
        );
        let builds = BUILD_PIPELINE_BUILDS.with(std::cell::Cell::get) - before;
        assert_eq!(results.len(), 2, "{results:?}");
        for r in &results {
            assert!(
                r.passed,
                "{}: {} (actual {:?})",
                r.variable, r.message, r.actual
            );
        }
        assert_eq!(builds, 0, "native must not fall back to a pipeline rebuild");
    }

    /// The retry carries the caller's compiler (issue #484), whatever the
    /// default is. Asked directly, the interpreter's retry sweeps `cum` cell by
    /// cell and a strict compiler's lowers it on the tape; both answer, bit for
    /// bit the same.
    #[test]
    fn the_pipeline_retry_is_built_on_the_named_compiler() {
        let file = load_string(&shaped_static_with_cumulative().to_string()).expect("loads");
        let bindings = |c| Some((HashMap::new(), HashMap::new(), Some(c)));
        let interp = build_pipeline_fields(
            &file,
            (0.0, 10.0),
            bindings(crate::problem::Compiler::Interpreter).as_ref(),
        );
        assert!(
            interp
                .as_ref()
                .is_some_and(|f| f.iter().any(|(k, _)| k == "cum")),
            "{interp:?}"
        );
        let native = build_pipeline_fields(
            &file,
            (0.0, 10.0),
            bindings(crate::problem::Compiler::Native).as_ref(),
        );
        let bits = |f: &Option<Vec<(String, ndarray::ArrayD<f64>)>>| -> Vec<u64> {
            f.as_ref()
                .and_then(|f| f.iter().find(|(k, _)| k == "cum"))
                .map(|(_, a)| a.iter().map(|x| x.to_bits()).collect())
                .unwrap_or_default()
        };
        assert!(!bits(&native).is_empty(), "{native:?}");
        assert_eq!(bits(&native), bits(&interp));
    }
}