earthsci-ast 0.6.0

//! JSON parsing and schema validation for ESM files

use crate::{EsmFile, error::EsmError};
// The §6.4 operator-model placeholder, taken from the scoping walker that
// treats it as a global sentinel rather than re-spelled here, so the scoping
// rule and the load-time rejection of a binder that shadows it cannot drift.
use crate::flatten::VAR_PLACEHOLDER;
use jsonschema::error::ValidationErrorKind;
use jsonschema::{Draft, JSONSchema};
use serde_json::Value;
use std::collections::HashSet;
use std::sync::OnceLock;

/// Library version supported by this implementation (major, minor, patch),
/// derived from [`crate::SCHEMA_VERSION`] so the two can never drift. Files
/// with a major version mismatch are rejected per the version compatibility
/// rules in esm-libraries-spec §8.
fn library_version() -> (u32, u32, u32) {
    crate::diagnostic::parse_semver(crate::SCHEMA_VERSION)
        .expect("SCHEMA_VERSION is a valid major.minor.patch string")
}

/// Bundled ESM JSON Schema
const ESM_SCHEMA_JSON: &str = include_str!("esm-schema.json");

/// Get the compiled JSON schema (cached for performance).
///
/// The bundled schema declares Draft 2020-12, for which `jsonschema` disables
/// format validation by default. We explicitly opt in so that `format:
/// "date-time"` (and other `format` keywords in the schema) actually reject
/// malformed strings — this is required for cross-language parity with Julia
/// and Python, which both enforce format validation.
fn get_schema() -> &'static JSONSchema {
    static SCHEMA: OnceLock<JSONSchema> = OnceLock::new();
    SCHEMA.get_or_init(|| {
        JSONSchema::options()
            .with_draft(Draft::Draft202012)
            .should_validate_formats(true)
            .compile(get_schema_value())
            .expect("Bundled schema should compile successfully")
    })
}

/// The parsed (but uncompiled) schema `Value`, cached. Needed by
/// [`collect_schema_errors`] to navigate `oneOf`/`anyOf` branch sub-schemas and
/// resolve `$ref`s when descending past the shallow composition error the
/// `jsonschema` crate reports (it does not surface a failed branch's own
/// sub-errors).
fn get_schema_value() -> &'static Value {
    static SCHEMA_VALUE: OnceLock<Value> = OnceLock::new();
    SCHEMA_VALUE.get_or_init(|| {
        serde_json::from_str(ESM_SCHEMA_JSON).expect("Bundled schema should be valid JSON")
    })
}

/// Load and parse an ESM file from JSON string
///
/// This function performs both JSON parsing and schema validation.
/// It will throw an error for malformed JSON or schema violations.
///
/// # Arguments
///
/// * `json_str` - The JSON string to parse
///
/// # Returns
///
/// * `Ok(EsmFile)` - Successfully parsed and validated ESM file
/// * `Err(EsmError)` - Parse error or schema validation error
///
/// # Examples
///
/// ```rust
/// use earthsci_ast::load_string;
///
/// let json = r#"
/// {
///   "esm": "1.0.0",
///   "metadata": {
///     "name": "test_model"
///   },
///   "models": {
///     "simple": {
///       "variables": {},
///       "equations": []
///     }
///   }
/// }
/// "#;
///
/// let esm_file = load_string(json).expect("Failed to load ESM file");
/// assert_eq!(esm_file.esm, "1.0.0");
/// ```
pub fn load_string(json_str: &str) -> Result<EsmFile, EsmError> {
    load_string_with_options(json_str, &LoadOptions::default())
}

/// Load and parse an ESM document that is ALREADY parsed as a
/// [`serde_json::Value`] — the same document a `.esm` file holds, just
/// already decoded. Runs the identical pipeline [`load_string`] runs
/// (subsystem-ref resolution, version gates, schema validation, §9.7
/// template machinery, typed deserialization).
pub fn load_document(document: &Value) -> Result<EsmFile, EsmError> {
    load_document_with_options(document, &LoadOptions::default())
}

/// [`load_document`] with explicit [`LoadOptions`] (base path for relative
/// refs, loader-API metaparameter bindings; esm-spec §9.7.6).
pub fn load_document_with_options(
    document: &Value,
    options: &LoadOptions,
) -> Result<EsmFile, EsmError> {
    load_value(document.clone(), options)
}

/// [`load_document_with_options`], consuming the document.
pub(crate) fn load_document_owned(
    document: Value,
    options: &LoadOptions,
) -> Result<EsmFile, EsmError> {
    load_value(document, options)
}

/// Options controlling how [`load_string_with_options`] /
/// [`load_document_with_options`] / [`load_path_with_options`] parse an ESM
/// file (esm-spec §9.7).
#[derive(Debug, Clone, Default)]
pub struct LoadOptions {
    /// Directory anchoring relative subsystem refs and
    /// `expression_template_imports` refs (esm-spec §9.7.2). Defaults to the
    /// current working directory for string / document input; `load_path` uses the
    /// file's own directory.
    pub base_path: Option<std::path::PathBuf>,

    /// Loader-API metaparameter bindings for the ROOT document (esm-spec
    /// §9.7.6 binding site 4): name → integer. Already-closed edge bindings
    /// win; API bindings beat `default`s. Binding a name the document does
    /// not declare raises `template_import_unknown_name`.
    pub metaparameters: std::collections::BTreeMap<String, i64>,
}

/// Load and parse an ESM file from a JSON string with explicit
/// [`LoadOptions`] (base path for relative refs, loader-API metaparameter
/// bindings; esm-spec §9.7.6).
pub fn load_string_with_options(
    json_str: &str,
    options: &LoadOptions,
) -> Result<EsmFile, EsmError> {
    let json_value: Value = serde_json::from_str(json_str).map_err(EsmError::JsonParse)?;
    load_value(json_value, options)
}

/// The pipeline shared by every `load_*` entry point, over an
/// already-decoded document. Split out so a path, a JSON string and a
/// pre-parsed `Value` cannot drift apart: `load` used to be ONE function
/// whose `&str` meant JSON text here and a FILE PATH in Julia and Go, with
/// no type error anywhere to catch the difference.
fn load_value(json_value: Value, options: &LoadOptions) -> Result<EsmFile, EsmError> {
    let mut json_value = json_value;

    // esm 1.1.0: rewrite the deprecated `aggregate` op spelling to the
    // canonical `faq` at the wire boundary, ahead of every other pass, so the
    // version gates, the schema, the typed tree and `emit` all see exactly one
    // tag (docs/content/rfcs/faq-node-rename.md).
    let authored = prepare_document_ops_scanned(&mut json_value)?;

    let base = options.base_path.clone().unwrap_or_else(|| {
        std::env::current_dir().unwrap_or_else(|_| std::path::PathBuf::from("."))
    });

    // The metaparameter names every document this one MOUNTS declares (§4.7,
    // either mount form, transitively). It widens the §9.7.6 site-4 check below:
    // a loader-API binding — which is how a discovered §8.9.4 `extent` arrives —
    // may name a metaparameter the LEAF declares and this document has no reason
    // to restate. The edge forwards it into the leaf's own close, so the name is
    // meaningful; only a name NO document in the assembly declares is the typo
    // the check exists to catch.
    //
    // Collected HERE, not at the site-4 check itself: this binding resolves refs
    // BEFORE the root's template machinery (Python is the other way round), so
    // by the time `resolve_template_machinery` runs, the `{ref}` mount entries
    // this walk reads have already been consumed and inlined.
    //
    // Guarded: the widening can only matter when the load carries loader-API
    // bindings or the document declares an `extent`. A document with neither
    // pays no extra ref reads — which also keeps a mounted file from being read
    // twice on the ordinary path.
    let mount_declared = if !options.metaparameters.is_empty()
        || crate::template_imports::document_declares_an_extent(&json_value)
    {
        crate::template_imports::collect_mount_declared_metaparameters(&json_value, &base)
    } else {
        std::collections::BTreeSet::new()
    };

    // esm-spec §8.9.4, statically: an `extent` naming a metaparameter nobody
    // declares is refused HERE rather than when the source is finally sampled at
    // build, so `esm validate` catches the typo. It runs BEFORE ref resolution,
    // on the AUTHORED tree: a mount CONSUMES the leaf's `metaparameters`
    // (§9.7.6 site 3), so after inlining neither the declaration nor the `{ref}`
    // stub that leads to it is still there to judge by.
    crate::template_imports::check_data_source_extents(&json_value, &base, &mount_declared)
        .map_err(|e| EsmError::SchemaValidation(e.to_string()))?;

    // Resolve any subsystem refs before schema validation, per spec section
    // 2.1b. Callers that load from a known file path should use `load_path`,
    // which uses the file's own directory as the base. The loader-API
    // metaparameters are threaded so a §4.7 subsystem-edge binding EXPRESSION
    // (`NTGT = NX*NY`, esm-spec §9.7.6 site 3) folds against the root document's
    // closed metaparameter environment (defaults overlaid with the API
    // bindings) at the mount.
    // The §4.7 contributions are STAGED here, not merged: the content is spliced
    // in now (the root's own §9.7 machinery has to lower through it), but its
    // `index_sets` do not join the registry until the root has CLOSED — §9.7.6
    // site 3, "subsystem refs resolve post-close". They are applied just below,
    // immediately after `resolve_template_machinery_scoped`.
    let staged_index_sets = crate::ref_loading::resolve_subsystem_refs_with_metaparameters(
        &mut json_value,
        &base,
        &options.metaparameters,
    )
    .map_err(|e| EsmError::SchemaValidation(e.to_string()))?;

    // esm-spec §8.2.1: resolve every `data_sources[*].source` location against
    // this document's own directory. AFTER ref resolution, because a referenced
    // component file's `data_sources` block is hoisted into this document by the
    // pass above — those entries were already anchored on THEIR file's directory
    // there, and this pass is idempotent, so both anchors land correctly.
    // Rewriting the raw document means the typed `DataSourceLocation`, the
    // ingest providers and `emit` all see one resolved form and none of them
    // needs a base directory.
    crate::data_source_urls::resolve_data_source_urls(&mut json_value, &base)
        .map_err(|e| EsmError::SchemaValidation(e.to_string()))?;

    // v0.4.0 expression_templates / apply_expression_template are rejected
    // when the file declares esm < 0.4.0 (RFC §5.4 spec-version gate).
    crate::lower_expression_templates::reject_expression_templates_pre_v04(&json_value)
        .map_err(|e| EsmError::SchemaValidation(e.to_string()))?;

    // v0.8.0 §9.7 constructs (expression_template_imports, top-level
    // expression_templates, metaparameters) are rejected when the file
    // declares esm < 0.8.0 (esm-spec §9.6.5).
    crate::template_imports::reject_template_imports_pre_v08(&json_value)
        .map_err(|e| EsmError::SchemaValidation(e.to_string()))?;

    // Top-level `expression_templates` beside a component payload is a
    // template-library payload no component can see (esm-spec §9.7.1).
    crate::template_imports::reject_impure_template_library(&json_value)
        .map_err(|e| EsmError::SchemaValidation(e.to_string()))?;

    // The top-level `solver` block arrives at esm 1.1.0; a file declaring an
    // earlier version that carries one is rejected (esm-spec §2.2.4).
    crate::solver::reject_solver_pre_v11(&json_value).map_err(
        |e: crate::diagnostic::DiagnosticError| EsmError::SchemaValidation(e.to_string()),
    )?;

    // `solver.external` arrives at esm 1.3.0, and a `${` in it is never
    // expanded (esm-spec §2.2.4, §2.2.6). Only the ROOT's block is read: a
    // mounted leaf's `solver` block does not cross the mount edge (§4.7).
    // `solver.time_span` likewise arrives at esm 1.3.0 and must describe an
    // interval (§2.2.7); its check runs after the `${` refusal, root-only.
    crate::solver::reject_solver_external_pre_v13(&json_value)
        .and_then(|()| crate::solver::reject_solver_time_span_pre_v13(&json_value))
        .and_then(|()| crate::solver::reject_solver_external_unresolved(&json_value))
        .and_then(|()| crate::solver::reject_solver_time_span_invalid(&json_value))
        .map_err(|e: crate::diagnostic::DiagnosticError| {
            EsmError::SchemaValidation(e.to_string())
        })?;

    // Declared `units` on a `const` node arrive at esm 1.2.0 (esm-spec §4.8.5).
    // Ref resolution is the one step since the authored walk that can add
    // nodes; without a mount it added none, and the walk's answer stands.
    let const_units = if authored.mounts {
        crate::units::reject_const_units_pre_v12(&json_value)
    } else {
        crate::units::reject_const_units_pre_v12_found(&json_value, || authored.op_with_units)
    };
    const_units.map_err(|e: crate::diagnostic::DiagnosticError| {
        EsmError::SchemaValidation(e.to_string())
    })?;

    // Validate against schema
    validate_schema(&json_value)?;

    // esm-spec §9.7.10 form B: fold any coupling-entry injection map into its
    // target components' own `expression_template_imports` BEFORE resolution,
    // so the ordinary import resolver + §9.6.3 fixpoint lower the named
    // target under the assembler-chosen discretization. The injection map is
    // consumed here (does not survive parse → emit); target diagnostics
    // (`template_inject_target_*`) surface as load errors. (Form A is threaded
    // through the subsystem-ref pass in `ref_loading::resolve_value` above.)
    crate::template_imports::apply_scope_injections(&mut json_value, &[])
        .map_err(|e| EsmError::SchemaValidation(e.to_string()))?;

    // Resolve esm-spec §9.7 machinery — template-library imports
    // (depth-first post-order, per-edge metaparameter instantiation),
    // index_sets merge, metaparameter close+fold — before structural
    // validation and the §9.6.3 fixpoint, so validators run on the folded,
    // expanded form (esm-spec §9.6.4 / §9.7.6).
    if let Some(resolved) = crate::template_imports::resolve_template_machinery_scoped(
        &json_value,
        &base,
        &options.metaparameters,
        &mount_declared,
        false,
    )
    .map_err(|e| EsmError::SchemaValidation(e.to_string()))?
    {
        json_value = resolved;
    }

    // esm-spec §4.7 "Index-set merge", the deferred half: the root has now
    // closed and folded its own `index_sets`, so the staged mount contributions
    // merge against a registry of concrete sizes, each folded against the same
    // closed environment first. Before structural validation, which needs the
    // complete registry.
    let closed_env =
        crate::ref_loading::root_metaparameter_env(&json_value, &options.metaparameters);
    crate::ref_loading::apply_staged_index_sets(&mut json_value, staged_index_sets, &closed_env)
        .map_err(|e| EsmError::SchemaValidation(e.to_string()))?;

    // Post-schema structural + semantic checks (version compatibility,
    // cross-field format rules, reference integrity, cyclic coupling) — the
    // things JSON Schema cannot express. Mirrors Python / Julia so that
    // cross-language conformance agrees.
    validate_structural_json(&json_value)?;

    // Lower `apply_expression_template` ops at load time (esm-spec §9.6.4
    // Option B, RFC out-of-line-expression-templates). This pass now PRESERVES
    // surviving (non-eager) references and each component's
    // `expression_templates` block (they travel into emit, §9.6.4 rule 5).
    // A document with no template machinery is left unchanged by this pass and
    // the two after it (enum lowering finds nothing to lower without an `enum`
    // node), so the template scan's walk also looks for `enum` nodes and
    // reserved binders, which are then not walked for again.
    let mut reserved = ReservedIndexScan::new(&json_value);
    let mut has_enum_ops = false;
    let (has_templates, scanned_whole) =
        crate::lower_expression_templates::lower_expression_templates_visiting(
            &mut json_value,
            &mut |path, value| {
                has_enum_ops |= crate::lower_enums::is_enum_node(value);
                reserved.visit(path, value);
            },
        )
        .map_err(|e| EsmError::SchemaValidation(e.to_string()))?;
    let reserved = (scanned_whole && !has_enum_ops).then_some(reserved);

    // The typed IR / build path (simulate, flatten, graph, …) is Expand-at-build
    // (RFC out-of-line-expression-templates §7.7): expand every surviving
    // reference here so downstream consumers see the fully expanded Option-A
    // image — numeric results stay bit-identical, and the typed structs never
    // see an `apply_expression_template` node or an `expression_templates` block.
    // Capture the per-component registries first: `expand` removes the blocks,
    // and `flatten` needs them to build the step-4 merged `template_registry`.
    // A document with no template machinery has nothing to expand; `expand`
    // would walk it only to find that out.
    let component_templates =
        crate::lower_expression_templates::capture_component_templates(&json_value);
    if has_templates {
        crate::lower_expression_templates::expand(&mut json_value)
            .map_err(|e| EsmError::SchemaValidation(e.to_string()))?;
    } else {
        crate::lower_expression_templates::strip_component_template_blocks(&mut json_value);
    }

    // Lower `enum`-op nodes to `const` integers using the file's `enums`
    // block (esm-spec §4.5 / §9.3). Mirrors the Julia / Python load-time
    // pass so that downstream consumers never see enum strings.
    crate::lower_enums::lower_enums_raw_scanned(&mut json_value, has_enum_ops || !scanned_whole)
        .map_err(|e| EsmError::SchemaValidation(e.to_string()))?;

    // Reject a `faq` binder that shadows a globally-scoped name (the
    // independent variable, `_var`). Runs HERE, on the fully lowered form, so a
    // binder a §9.6/§9.7 template body introduced is caught with the authored
    // ones. See `reject_reserved_index_symbols` for why this is a rejection
    // rather than a shadowing rule.
    match reserved {
        Some(scan) => scan.finish(),
        None => reject_reserved_index_symbols(&json_value),
    }
    .map_err(|e| EsmError::StructuralValidation(e.to_string()))?;

    // Deserialize into our types. The interning scope makes every
    // structurally repeated operator subtree share ONE allocation as it is
    // built (see `crate::intern`): the §9.7-expanded document deserializes
    // bottom-up, so duplicates are collapsed before they can accumulate —
    // this is where the load-phase peak used to live (~978 MiB of typed AST
    // for `simpleclimate.esm` at the production grid; ~6 MiB deduplicated).
    let mut esm_file: EsmFile = {
        let _intern = crate::intern::InternScope::new();
        serde_json::from_value(json_value).map_err(EsmError::JsonParse)?
    };
    esm_file.component_templates = component_templates;
    // esm-spec §2.2: an EMPTY `solver` block normalizes to absence at load.
    esm_file.solver = crate::solver::normalize_empty(esm_file.solver.take());
    // esm-spec §10.10 / §4.7: relative `coupling_import` refs resolve against
    // THIS document's directory, which flatten would otherwise never learn. Only
    // an explicit base is recorded; a string load without one leaves flatten's
    // own `base_path` in charge.
    if options.base_path.is_some() {
        esm_file.coupling_import_base = Some(base.to_string_lossy().into_owned());
    }
    // esm-spec §2.2.6: the anchor `solver_external_location` resolves a relative
    // `solver.external` against — the file's directory, the explicit base, or
    // the working directory of a string load. Recorded on EVERY load and made
    // absolute now, so a later change of working directory cannot move it.
    esm_file.document_base = crate::solver::absolute_directory(&base);

    Ok(esm_file)
}

/// Load an ESM file from a filesystem path.
///
/// Reads the file, resolves any subsystem references relative to the file's
/// directory, validates against the schema, and deserializes into an
/// [`EsmFile`].
pub fn load_path<P: AsRef<std::path::Path>>(path: P) -> Result<EsmFile, EsmError> {
    load_path_with_options(path, &std::collections::BTreeMap::new())
}

/// Load an ESM file from a filesystem path, binding the root document's open
/// metaparameters at the loader API (esm-spec §9.7.6 binding site 4). The
/// file's own directory anchors relative subsystem and template-import refs.
pub fn load_path_with_options<P: AsRef<std::path::Path>>(
    path: P,
    metaparameters: &std::collections::BTreeMap<String, i64>,
) -> Result<EsmFile, EsmError> {
    let path = path.as_ref();
    let json_str = std::fs::read_to_string(path).map_err(|e| EsmError::FileRead {
        path: path.display().to_string(),
        source: e,
    })?;

    let base = path
        .parent()
        .map(|p| p.to_path_buf())
        .unwrap_or_else(|| std::path::PathBuf::from("."));
    let options = LoadOptions {
        base_path: Some(base),
        metaparameters: metaparameters.clone(),
    };
    load_string_with_options(&json_str, &options)
}

/// Validate a JSON value against the ESM schema
///
/// This performs schema validation only. The JSON is assumed to be valid.
///
/// # Arguments
///
/// * `json_value` - The JSON value to validate
///
/// # Returns
///
/// * `Ok(())` - JSON passes schema validation
/// * `Err(EsmError::SchemaValidation)` - Schema validation errors
pub fn validate_schema(json_value: &Value) -> Result<(), EsmError> {
    let schema = get_schema();
    // A valid document is the common case, and answering only whether it is
    // valid skips assembling an error for every failed `oneOf` / `anyOf`
    // branch on the way; the errors are collected only for a document that
    // fails.
    if schema.is_valid(json_value) {
        return Ok(());
    }
    let validation_result = schema.validate(json_value);

    match validation_result {
        Ok(_) => Ok(()),
        Err(errors) => {
            let error_messages: Vec<String> = errors.map(|error| error.to_string()).collect();
            Err(EsmError::SchemaValidation(error_messages.join("; ")))
        }
    }
}

/// Map a `jsonschema` [`ValidationErrorKind`] to the STANDARD JSON-Schema
/// keyword that failed, so the cross-language conformance wire format uses the
/// same vocabulary as AJV / Python `jsonschema` (CONFORMANCE_SPEC.md §7.1.2)
/// rather than a library-specific spelling.
fn schema_keyword_for_kind(kind: &ValidationErrorKind) -> &'static str {
    use ValidationErrorKind as K;
    match kind {
        K::AdditionalItems { .. } => "additionalItems",
        K::AdditionalProperties { .. } => "additionalProperties",
        K::AnyOf => "anyOf",
        // A regex that blew its backtrack budget failed the `pattern` keyword.
        K::BacktrackLimitExceeded { .. } => "pattern",
        K::Constant { .. } => "const",
        K::Contains => "contains",
        K::ContentEncoding { .. } => "contentEncoding",
        K::ContentMediaType { .. } => "contentMediaType",
        K::Custom { .. } => "custom",
        K::Enum { .. } => "enum",
        K::ExclusiveMaximum { .. } => "exclusiveMaximum",
        K::ExclusiveMinimum { .. } => "exclusiveMinimum",
        K::FalseSchema => "false",
        K::FileNotFound { .. } => "$ref",
        K::Format { .. } => "format",
        K::FromUtf8 { .. } => "contentEncoding",
        K::Utf8 { .. } => "format",
        K::JSONParse { .. } => "$ref",
        K::InvalidReference { .. } => "$ref",
        K::InvalidURL { .. } => "format",
        K::MaxItems { .. } => "maxItems",
        K::Maximum { .. } => "maximum",
        K::MaxLength { .. } => "maxLength",
        K::MaxProperties { .. } => "maxProperties",
        K::MinItems { .. } => "minItems",
        K::Minimum { .. } => "minimum",
        K::MinLength { .. } => "minLength",
        K::MinProperties { .. } => "minProperties",
        K::MultipleOf { .. } => "multipleOf",
        K::Not { .. } => "not",
        K::OneOfMultipleValid | K::OneOfNotValid => "oneOf",
        K::Pattern { .. } => "pattern",
        K::PropertyNames { .. } => "propertyNames",
        K::Required { .. } => "required",
        K::Schema => "schema",
        K::Type { .. } => "type",
        K::UnevaluatedProperties { .. } => "unevaluatedProperties",
        K::UniqueItems => "uniqueItems",
        K::UnknownReferenceScheme { .. } => "$ref",
        K::Resolver { .. } => "$ref",
    }
}

/// Maximum `oneOf`/`anyOf` branch-descent depth. Deep enough for the ESM
/// schema's real nesting (document → model → variable/equation → expression),
/// bounded so a self-referential `$ref` (e.g. `Expression`) cannot recurse
/// without end.
const SCHEMA_DESCENT_CAP: usize = 16;

/// Validate `json_value` against the ESM schema and return **one
/// [`SchemaError`] per violation** (CONFORMANCE_SPEC.md §7.1.2), instead of the
/// single `"; "`-joined blob [`validate_schema`] produces for the load path.
///
/// Each record carries the RFC-6901 JSON Pointer of the offending node (the
/// document root is the empty string `""`) and the standard JSON-Schema
/// keyword that failed, so the cross-language comparator can match pinned
/// `(keyword, path)` tuples. An empty vec means the document is schema-valid.
///
/// The `jsonschema` crate reports a failed `oneOf`/`anyOf`/`$ref` only as a
/// SHALLOW composition error at the branch point — it does not surface the
/// sub-schema errors that explain WHY the branch failed (AJV, the reference,
/// does). Since the ESM schema wraps every component in
/// `additionalProperties: { oneOf: [{$ref: …}, {$ref: SubsystemRef}] }` and
/// nests further `oneOf`s inside, that would hide almost every pinned error
/// behind a `oneOf` at `/models/X`. To recover them, each composition error is
/// descended: every branch sub-schema is compiled standalone and re-validated
/// against the offending instance subtree, and its (recursively descended)
/// errors are emitted with absolute instance paths. Extra errors are harmless
/// (the comparator is a required-subset), so all branches are explored.
pub fn collect_schema_errors(json_value: &Value) -> Vec<crate::validate::SchemaError> {
    let root = get_schema_value();
    let defs = root.get("$defs");
    let mut out = Vec::new();
    let mut cache: std::collections::HashMap<String, Option<JSONSchema>> =
        std::collections::HashMap::new();
    // The top level reuses the pre-compiled full schema; branches below compile
    // on demand.
    let summaries = match get_schema().validate(json_value) {
        Ok(()) => Vec::new(),
        Err(errors) => summarize_errors(errors),
    };
    handle_schema_errors(
        root, defs, &mut cache, root, json_value, "", &summaries, 0, &mut out,
    );
    // Dedup identical (path, keyword, message) records the branch sweep can
    // produce when several branches fail the same way.
    let mut seen = std::collections::HashSet::new();
    out.retain(|e| seen.insert((e.path.clone(), e.keyword.clone(), e.message.clone())));
    out
}

/// Owned summary of a single `jsonschema` error, so the compiled sub-schema (and
/// its `cache` borrow) can be dropped before the branch descent recurses.
struct ErrSummary {
    instance_path: String,
    schema_path: String,
    keyword: String,
    message: String,
    is_composition: bool,
}

/// Project a validation-error iterator to owned [`ErrSummary`]s.
fn summarize_errors<'a>(
    errors: impl Iterator<Item = jsonschema::ValidationError<'a>>,
) -> Vec<ErrSummary> {
    errors
        .map(|error| ErrSummary {
            instance_path: error.instance_path.to_string(),
            schema_path: error.schema_path.to_string(),
            keyword: schema_keyword_for_kind(&error.kind).to_string(),
            message: error.to_string(),
            is_composition: matches!(
                error.kind,
                ValidationErrorKind::OneOfNotValid
                    | ValidationErrorKind::OneOfMultipleValid
                    | ValidationErrorKind::AnyOf
            ),
        })
        .collect()
}

/// Emit each summarized error, or — for a `oneOf`/`anyOf` composition failure —
/// descend every branch sub-schema and emit its own (recursively descended)
/// errors instead. `nav_schema` is the concrete schema fragment the errors'
/// `schema_path`s are relative to; `instance` is the value validated against it
/// and `base` the absolute instance-pointer prefix of that value.
#[allow(clippy::too_many_arguments)]
fn handle_schema_errors(
    root: &Value,
    defs: Option<&Value>,
    cache: &mut std::collections::HashMap<String, Option<JSONSchema>>,
    nav_schema: &Value,
    instance: &Value,
    base: &str,
    summaries: &[ErrSummary],
    depth: usize,
    out: &mut Vec<crate::validate::SchemaError>,
) {
    for s in summaries {
        let abs_path = format!("{base}{}", s.instance_path);

        // Always emit the error itself. For a composition failure this is the
        // shallow `oneOf`/`anyOf` record — some pins want exactly that (e.g. the
        // root `anyOf` when a document declares no systems), and the comparator
        // is a required-subset so the deeper branch errors added below only help.
        out.push(crate::validate::SchemaError {
            path: abs_path.clone(),
            message: s.message.clone(),
            keyword: s.keyword.clone(),
        });

        // Then descend a composition failure so the sub-schema errors that
        // explain WHY every branch failed surface too (the crate reports only
        // the shallow composition error; AJV — the reference — reports these).
        if s.is_composition && depth < SCHEMA_DESCENT_CAP {
            let segments = schema_path_segments(&s.schema_path);
            if let Some(branches) =
                resolve_schema_at(root, nav_schema, &segments).and_then(|c| c.as_array())
            {
                let sub_instance = if s.instance_path.is_empty() {
                    instance
                } else {
                    instance.pointer(&s.instance_path).unwrap_or(instance)
                };
                for branch in branches {
                    let branch_schema = follow_refs(root, branch);
                    // Validate the offending subtree against this branch and
                    // summarize its errors; the `cache` borrow ends here so the
                    // recursion below is free to re-borrow it.
                    let sub_summaries =
                        validate_and_summarize(cache, defs, branch_schema, sub_instance);
                    handle_schema_errors(
                        root,
                        defs,
                        cache,
                        branch_schema,
                        sub_instance,
                        &abs_path,
                        &sub_summaries,
                        depth + 1,
                        out,
                    );
                }
            }
        }
    }
}

/// Compile `branch_schema` standalone (via [`compile_branch`]) and summarize its
/// errors against `instance`. The compiled schema — and thus the `cache` borrow
/// — is released on return, freeing the caller to recurse.
fn validate_and_summarize(
    cache: &mut std::collections::HashMap<String, Option<JSONSchema>>,
    defs: Option<&Value>,
    branch_schema: &Value,
    instance: &Value,
) -> Vec<ErrSummary> {
    match compile_branch(cache, defs, branch_schema) {
        Some(compiled) => match compiled.validate(instance) {
            Ok(()) => Vec::new(),
            Err(errors) => summarize_errors(errors),
        },
        None => Vec::new(),
    }
}

/// Split a schema-path JSON Pointer (`/properties/models/.../oneOf`) into its
/// unescaped chunks for [`resolve_schema_at`].
fn schema_path_segments(pointer: &str) -> Vec<String> {
    pointer
        .split('/')
        .skip(1) // leading empty chunk before the first '/'
        .map(|c| c.replace("~1", "/").replace("~0", "~"))
        .collect()
}

/// Resolve `$ref`s until `value` is a concrete (non-`$ref`) schema node.
fn follow_refs<'a>(root: &'a Value, mut value: &'a Value) -> &'a Value {
    let mut guard = 0;
    while let Some(reference) = value.get("$ref").and_then(|r| r.as_str()) {
        guard += 1;
        if guard > SCHEMA_DESCENT_CAP {
            break;
        }
        match resolve_local_ref(root, reference) {
            Some(target) => value = target,
            None => break,
        }
    }
    value
}

/// Resolve a local `#/…` JSON-Pointer `$ref` against the schema document.
fn resolve_local_ref<'a>(root: &'a Value, reference: &str) -> Option<&'a Value> {
    let pointer = reference.strip_prefix('#')?;
    if pointer.is_empty() {
        Some(root)
    } else {
        root.pointer(pointer)
    }
}

/// Navigate `schema_path` segments into `start`, transparently resolving any
/// `$ref` crossed along the way (mirroring how the crate's resolved
/// `schema_path` traverses `$ref` boundaries), returning the node the pointer
/// addresses (e.g. the `oneOf` array).
fn resolve_schema_at<'a>(
    root: &'a Value,
    start: &'a Value,
    segments: &[String],
) -> Option<&'a Value> {
    let mut cur = follow_refs(root, start);
    for seg in segments {
        cur = follow_refs(root, cur);
        cur = match cur {
            Value::Object(_) => cur.get(seg)?,
            Value::Array(arr) => arr.get(seg.parse::<usize>().ok()?)?,
            _ => return None,
        };
    }
    Some(follow_refs(root, cur))
}

/// Compile a branch sub-schema standalone (with the document `$defs` injected so
/// its internal `$ref`s resolve), memoized by the branch's JSON text. `None` if
/// the fragment cannot be compiled.
fn compile_branch<'c>(
    cache: &'c mut std::collections::HashMap<String, Option<JSONSchema>>,
    defs: Option<&Value>,
    branch_schema: &Value,
) -> Option<&'c JSONSchema> {
    let key = branch_schema.to_string();
    cache
        .entry(key)
        .or_insert_with(|| {
            let mut wrapper = branch_schema.clone();
            if let (Some(obj), Some(defs)) = (wrapper.as_object_mut(), defs) {
                obj.entry("$defs").or_insert_with(|| defs.clone());
            }
            JSONSchema::options()
                .with_draft(Draft::Draft202012)
                .should_validate_formats(true)
                .compile(&wrapper)
                .ok()
        })
        .as_ref()
}

// ============================================================================
// Post-schema structural / semantic validation
// ============================================================================
//
// JSON Schema can enforce shape, type, and pattern rules, but a handful of
// semantic rules in esm-libraries-spec §3.2 fall outside what Draft 2020-12
// can express. The checks in this section mirror Python's `_validate_structural`
// and Julia's validator so that a fixture that fails in one language fails
// in all three, per §2.1a cross-language parity.
//
// RELATIONSHIP TO `crate::validate` / `crate::structural`: this is the
// LOAD-TIME stack — it runs on raw JSON inside `load_string()`, gates whether a file
// parses at all, and its String messages are pinned cross-binding. The typed
// stack (`validate()` → structural.rs/coupling.rs) runs on demand over the
// deserialized `EsmFile` and reports structured `StructuralError`s. Several
// rules intentionally exist in BOTH layers (event variable references,
// discrete-parameter declarations, circular model dependencies): this layer
// rejects files that must not load; the typed layer re-checks documents that
// were constructed or edited in memory and never passed through `load_string()`.
// If you change a shared rule, change it in both layers (and the sibling
// bindings).

/// Reject any `faq` binder that SHADOWS the document's independent
/// variable (esm-spec §11.3: `domain.independent_variable`, default `"t"`) or
/// the §6.4 operator placeholder `_var` — diagnostic `reserved_index_symbol`.
///
/// Both names are IMPLICITLY DECLARED in every model's expression scope
/// (§4.9.1), and every consumer in this crate resolves them by name BEFORE it
/// consults the loop bindings: `simulate_array/eval.rs::lookup_variable` and
/// `lookup_array_ref`, `vectorized.rs::eval_vec_variable`, the two `tape/lower.rs`
/// sites, `units.rs`, `simulate/resolve.rs`, and the scoping walkers
/// `flatten.rs::namespace_expr_scoped` / `scope_template_body`
/// (`if name == "t" || name == VAR_PLACEHOLDER || bound.contains(name)`). A
/// `ranges` key or `output_idx` entry spelled with one of those names therefore
/// declares a loop the body can never address: every read of the symbol inside
/// the node evaluates to the simulation TIME (or to the operand placeholder)
/// instead of the loop index.
///
/// **Why this is a rejection and not a shadowing rule.** Making the binder win
/// would mean inverting that precedence at all nine sites here and in every
/// peer binding, and it would still leave the node unable to mention the
/// independent variable at all — a `faq` body that reads `t` for a
/// forcing term is ordinary, and inside such a node `t` would silently become
/// an index. Rejecting costs nothing an author wants: an index symbol is the
/// author's free choice (§4.3.1), so the fix is to spell it anything else.
///
/// What the shadowing did before this check existed is exactly what
/// CONFORMANCE_SPEC §5.5.8 forbids for the same reason it forbids an
/// unresolvable key column — a SILENT no-op. A `join.on` key column resolves
/// against the node's own `ranges` (`join.rs::resolve_side`), so the shadowed
/// symbol resolved fine at BUILD time and then addressed the wrong thing at
/// EVAL time: with a data-column key the gate admitted nothing and the
/// `sum_product` reduction returned 0 with no error and no warning, and with a
/// `const`-array key the lowered `code_lookup` indexed the constant key table
/// with the time value and raised the misleading
/// `E_TREEWALK_CONSTARRAY_OOB: const array 'left_key' index 0 out of range 1..3`.
/// Regression fixtures: `tests/fixtures/reserved_index_symbol/`.
///
/// An `integral`'s `var` (`int_var`) is deliberately NOT checked: `∫f dt` binds
/// the independent variable because it IS integrating over it, which is the
/// authored form §4.2 documents, not a shadow of it.
///
/// Runs on the fully-lowered raw JSON (after §9.7 import resolution, the §9.6.3
/// fixpoint and template expansion), so a binder introduced by a template BODY
/// is caught alongside an authored one.
pub(crate) fn reject_reserved_index_symbols(
    json_value: &Value,
) -> Result<(), crate::diagnostic::DiagnosticError> {
    let mut scan = ReservedIndexScan::new(json_value);
    crate::json_visit::visit_values(json_value, &mut |path, value| scan.visit(path, value));
    scan.finish()
}

/// [`reject_reserved_index_symbols`] as a visitor, so the walk can be shared:
/// [`ReservedIndexScan::visit`] every value of the document in pre-order, then
/// [`ReservedIndexScan::finish`].
pub(crate) struct ReservedIndexScan {
    independent: String,
    /// `(path, field, symbol, role)` for every offending binder, in document
    /// order, as the message lists them.
    offenders: Vec<String>,
}

impl ReservedIndexScan {
    pub(crate) fn new(json_value: &Value) -> Self {
        let independent = json_value
            .get("domain")
            .and_then(|d| d.get("independent_variable"))
            .and_then(Value::as_str)
            .unwrap_or("t")
            .to_string();
        ReservedIndexScan {
            independent,
            offenders: Vec::new(),
        }
    }

    pub(crate) fn visit(&mut self, path: &crate::json_visit::JsonPath<'_>, value: &Value) {
        let Some(obj) = value.as_object() else {
            return;
        };
        // An Expression NODE: the only place these two fields carry meaning.
        let Some(op) = crate::json_visit::small_get(obj, "op").and_then(Value::as_str) else {
            return;
        };
        let independent = self.independent.as_str();
        let reserved = |name: &str| -> Option<&'static str> {
            if name == independent {
                Some("the document's independent variable")
            } else if name == VAR_PLACEHOLDER {
                Some("the §6.4 operator placeholder")
            } else {
                None
            }
        };
        // A symbol that is BOTH an `output_idx` entry and a `ranges` key of the
        // same node is one mistake, so it is reported once, under `ranges`.
        let offenders = &mut self.offenders;
        let mut seen: Vec<&str> = Vec::new();
        let mut record = |field: &str, sym: &str, role: &str| {
            offenders.push(format!(
                "`{op}` node at {path} binds '{sym}' as an index symbol ({field}), \
                 but '{sym}' is {role}"
            ));
        };
        if let Some(ranges) = crate::json_visit::small_get(obj, "ranges").and_then(Value::as_object)
        {
            for key in ranges.keys() {
                if let Some(role) = reserved(key) {
                    seen.push(key);
                    record("a `ranges` key", key, role);
                }
            }
        }
        if let Some(output_idx) =
            crate::json_visit::small_get(obj, "output_idx").and_then(Value::as_array)
        {
            for entry in output_idx.iter().filter_map(Value::as_str) {
                if let Some(role) = reserved(entry)
                    && !seen.contains(&entry)
                {
                    record("an `output_idx` entry", entry, role);
                }
            }
        }
    }

    pub(crate) fn finish(self) -> Result<(), crate::diagnostic::DiagnosticError> {
        if self.offenders.is_empty() {
            return Ok(());
        }
        let independent = self.independent;
        Err(crate::diagnostic::err(
            crate::diagnostic::codes::RESERVED_INDEX_SYMBOL,
            format!(
                "{}. Both '{independent}' (esm-spec §11.3) and '{VAR_PLACEHOLDER}' (§6.4) are \
                 implicitly declared in every model's expression scope (§4.9.1) and are resolved \
                 by name before the loop bindings, so a binder spelled with one of them declares \
                 a loop its body can never address — the reads inside the node see the \
                 independent variable's value instead of the index, silently (CONFORMANCE_SPEC \
                 §5.5.8 forbids the same silence for an unresolvable `join.on` key column). \
                 Rename the index symbol: an index symbol is the author's free choice \
                 (esm-spec §4.3.1)",
                self.offenders.join("; ")
            ),
        ))
    }
}

/// Run every post-schema structural check, collecting errors and returning
/// `EsmError::StructuralValidation` if any check fires.
fn validate_structural_json(json_value: &Value) -> Result<(), EsmError> {
    let mut errors: Vec<String> = Vec::new();

    if let Some(obj) = json_value.as_object() {
        check_version_compatibility(obj, &mut errors);
        check_metadata_formats(obj, &mut errors);
        check_data_loader_temporal_durations(obj, &mut errors);
        check_coupling_references(obj, &mut errors);
        check_circular_model_dependencies_typed(json_value, &mut errors);
        check_event_variable_references(obj, &mut errors);
        check_reaction_stoichiometries(obj, &mut errors);
    }

    if errors.is_empty() {
        Ok(())
    } else {
        Err(EsmError::StructuralValidation(format!(
            "Structural validation failed: {}",
            errors.join("; ")
        )))
    }
}

/// Reject files whose major version does not match this library.
///
/// The schema already enforces the `\d+\.\d+\.\d+` pattern; this check runs
/// after that and rejects mismatched major versions with the standardized
/// message string the Julia / Python libraries use.
fn check_version_compatibility(obj: &serde_json::Map<String, Value>, errors: &mut Vec<String>) {
    let Some(ver) = obj.get("esm").and_then(|v| v.as_str()) else {
        return;
    };
    let Some((major, _, _)) = crate::diagnostic::parse_semver(ver) else {
        return;
    };
    let supported_major = library_version().0;
    if major != supported_major {
        errors.push(format!(
            "Unsupported major version {major}. This library supports major version {supported_major} only."
        ));
    }
}

/// Reject reaction stoichiometries that are not positive finite numbers.
///
/// JSON Schema already enforces `"type": "number", "exclusiveMinimum": 0`, but
/// JSON cannot encode NaN / ±Infinity — if upstream tooling produces such a
/// value, or a numeric encoding overflows to Infinity, we surface the error
/// here rather than silently accepting it downstream.
fn check_reaction_stoichiometries(obj: &serde_json::Map<String, Value>, errors: &mut Vec<String>) {
    let Some(reaction_systems) = obj.get("reaction_systems").and_then(|v| v.as_object()) else {
        return;
    };
    for (rs_name, rs_val) in reaction_systems {
        let Some(rs_obj) = rs_val.as_object() else {
            continue;
        };
        let Some(reactions) = rs_obj.get("reactions").and_then(|v| v.as_array()) else {
            continue;
        };
        for (r_idx, r_val) in reactions.iter().enumerate() {
            let Some(r_obj) = r_val.as_object() else {
                continue;
            };
            for side in ["substrates", "products"] {
                let Some(entries) = r_obj.get(side).and_then(|v| v.as_array()) else {
                    continue;
                };
                for (e_idx, e_val) in entries.iter().enumerate() {
                    let Some(e_obj) = e_val.as_object() else {
                        continue;
                    };
                    let Some(stoich) = e_obj.get("stoichiometry") else {
                        continue;
                    };
                    let path = format!(
                        "reaction_systems/{rs_name}/reactions[{r_idx}]/{side}[{e_idx}]/stoichiometry"
                    );
                    match stoich.as_f64() {
                        Some(v) if v.is_finite() && v > 0.0 => {}
                        Some(v) if !v.is_finite() => {
                            errors.push(format!("{path}: stoichiometry must be finite, got {v}"));
                        }
                        Some(v) => {
                            errors.push(format!("{path}: stoichiometry must be positive, got {v}"));
                        }
                        None => {
                            errors.push(format!("{path}: stoichiometry must be a number"));
                        }
                    }
                }
            }
        }
    }
}

/// Validate ISO 8601 dates, URLs, and DOIs in the metadata block, and reject
/// empty strings for those fields.
fn check_metadata_formats(obj: &serde_json::Map<String, Value>, errors: &mut Vec<String>) {
    let Some(md) = obj.get("metadata").and_then(|v| v.as_object()) else {
        return;
    };

    for field in ["created", "modified"] {
        if let Some(val) = md.get(field).and_then(|v| v.as_str())
            && !is_iso8601_datetime(val)
        {
            errors.push(format!(
                "metadata/{field}: '{val}' is not a valid ISO 8601 date"
            ));
        }
    }

    if let Some(refs) = md.get("references").and_then(|v| v.as_array()) {
        for (i, r) in refs.iter().enumerate() {
            let Some(r_obj) = r.as_object() else { continue };

            if let Some(url) = r_obj.get("url").and_then(|v| v.as_str()) {
                if url.is_empty() {
                    errors.push(format!(
                        "metadata/references[{i}]/url: empty string is not a valid URL"
                    ));
                } else if !is_valid_url(url) {
                    errors.push(format!(
                        "metadata/references[{i}]/url: '{url}' is not a valid URL"
                    ));
                }
            }

            if let Some(doi) = r_obj.get("doi").and_then(|v| v.as_str()) {
                if doi.is_empty() {
                    errors.push(format!(
                        "metadata/references[{i}]/doi: empty string is not a valid DOI"
                    ));
                } else if !is_valid_doi(doi) {
                    errors.push(format!(
                        "metadata/references[{i}]/doi: '{doi}' is not a valid DOI format"
                    ));
                }
            }

            if let Some(citation) = r_obj.get("citation").and_then(|v| v.as_str())
                && citation.is_empty()
            {
                errors.push(format!(
                    "metadata/references[{i}]/citation: empty citation string is not allowed"
                ));
            }
        }
    }
}

/// Any duration string inside `data_loader.temporal` (`file_period` or
/// `frequency`), if present, must be a valid ISO 8601 duration. The schema
/// types these as `string` but does not enforce the grammar.
fn check_data_loader_temporal_durations(
    obj: &serde_json::Map<String, Value>,
    errors: &mut Vec<String>,
) {
    let Some(loaders) = obj.get("data_sources").and_then(|v| v.as_object()) else {
        return;
    };
    for (dname, dv) in loaders {
        let Some(d) = dv.as_object() else { continue };
        let Some(temporal) = d.get("temporal").and_then(|v| v.as_object()) else {
            continue;
        };
        for field in ["file_period", "frequency"] {
            if let Some(res) = temporal.get(field).and_then(|v| v.as_str())
                && !res.is_empty()
                && !is_iso8601_duration(res)
            {
                errors.push(format!(
                    "data_sources/{dname}/temporal/{field}: '{res}' is not a valid ISO 8601 duration"
                ));
            }
        }
    }
}

/// Every system named by a coupling entry, read off the RAW JSON.
///
/// The typed [`crate::structural::coupled_system_names`] is the same rule, but
/// these two load-time checks run BEFORE the document is typed, so the set has
/// to be recovered from the untyped tree. See that function for why a coupled
/// system's checks relax.
fn coupled_system_names_raw(obj: &serde_json::Map<String, Value>) -> HashSet<String> {
    let mut coupled = HashSet::new();
    let mut add = |name: &str| {
        if name.is_empty() {
            return;
        }
        coupled.insert(name.to_string());
        if let Some((root, _)) = name.split_once('.') {
            coupled.insert(root.to_string());
        }
    };
    for entry in obj
        .get("coupling")
        .and_then(|v| v.as_array())
        .into_iter()
        .flatten()
    {
        for key in ["from", "to"] {
            if let Some(s) = entry.get(key).and_then(|v| v.as_str()) {
                add(s);
            }
        }
        for s in entry
            .get("systems")
            .and_then(|v| v.as_array())
            .into_iter()
            .flatten()
            .filter_map(|v| v.as_str())
        {
            add(s);
        }
    }
    coupled
}

/// In a coupling-library file (esm-spec §10.9) a coupling edge's system-naming
/// segments name declared ROLES, not systems: the library holds no models, so
/// resolving them against a symbol table would reject every well-formed library.
/// §10.9 suspends that resolution and requires the top-level segment at every
/// §10.10.2 occurrence site to name a declared role instead
/// (`coupling_edge_unknown_role`), which is the same check `coupling_imports`
/// runs when the library is imported — the shared `collect_role_segments` walk
/// is what keeps the two sites from drifting apart.
fn check_coupling_role_references(
    obj: &serde_json::Map<String, Value>,
    coupling: &[Value],
    errors: &mut Vec<String>,
) {
    let roles: std::collections::HashSet<&str> = obj
        .get("coupling_roles")
        .and_then(|v| v.as_object())
        .map(|o| o.keys().map(String::as_str).collect())
        .unwrap_or_default();
    for (i, c) in coupling.iter().enumerate() {
        if !c.is_object() {
            continue;
        }
        let mut unknown: Vec<String> = crate::coupling_imports::collect_role_segments(c)
            .into_iter()
            .filter(|seg| !roles.contains(seg.as_str()))
            .collect();
        unknown.sort();
        for seg in unknown {
            errors.push(format!(
                "coupling[{i}]: edge references '{seg}', which is not a declared role \
                 (esm-spec §10.9: a coupling library's refs name a role in `coupling_roles`)"
            ));
        }
    }
}

/// `coupling[].from` and `coupling[].to` must point to variables declared
/// somewhere in the file. We only enforce `from`, matching Python's lenient
/// handling of `to` (variable_map can introduce target vars).
fn check_coupling_references(obj: &serde_json::Map<String, Value>, errors: &mut Vec<String>) {
    let Some(coupling) = obj.get("coupling").and_then(|v| v.as_array()) else {
        return;
    };
    // A coupling library's refs are role-scoped, not system-scoped (esm-spec
    // §10.9); `coupling_roles` is the sole positive identifier of the kind.
    if crate::coupling_imports::is_coupling_library_obj(obj) {
        check_coupling_role_references(obj, coupling, errors);
        return;
    }
    let tables = build_symbol_tables(obj);

    for (i, c) in coupling.iter().enumerate() {
        let Some(cobj) = c.as_object() else { continue };
        let Some(from_ref) = cobj.get("from").and_then(|v| v.as_str()) else {
            continue;
        };
        if !from_ref.contains('.') {
            continue;
        }
        let dot_count = from_ref.chars().filter(|ch| *ch == '.').count();
        if dot_count > 1 {
            // Subsystem-nested ref — only verify top-level system exists.
            let top = from_ref.split('.').next().unwrap_or("");
            if !tables.all_systems.contains(top) {
                errors.push(format!(
                    "coupling[{i}]/from: reference '{from_ref}' to undefined system '{top}'"
                ));
            }
            continue;
        }
        let (system, var) = from_ref.split_once('.').unwrap();
        if !tables.all_systems.contains(system) {
            errors.push(format!(
                "coupling[{i}]/from: reference '{from_ref}' to undefined system '{system}'"
            ));
            continue;
        }
        if !tables.has_variable(system, var) {
            errors.push(format!(
                "coupling[{i}]/from: reference '{from_ref}' — variable '{var}' not provided by '{system}'"
            ));
        }
    }
}

/// Detect cycles in model-to-model dependency edges by delegating WHOLE-RULE to
/// the typed `crate::structural::check_circular_dependencies_in_models` — the
/// SAME edge-building + shared-DFS the typed `validate()` pass runs — instead of
/// re-deriving the edge set over raw JSON (deferred knot #2, completing the
/// prior wave that already delegated only the cycle SEARCH).
///
/// The load-time gate needs only the binary reject decision; the pinned
/// `(circular_dependency, /models)` record is recovered from `validate()` in the
/// conformance runner, so this is verdict-invariant: no currently-loading
/// document carries a model cycle (else `validate()` would already class it
/// invalid), and the one rejected fixture (`circular_coupling.esm`) is caught
/// identically. Deserializing to `EsmFile` here is safe — schema validation has
/// already passed at this point; a document that fails to type (e.g. an
/// unlowered template node) carries no model cycle in the corpus, so skipping it
/// cannot miss a rejection.
///
/// Deserializes THROUGH a borrow of the document (`&Value` is itself a
/// `Deserializer`) rather than `from_value(json_value.clone())`. This runs
/// AFTER §9.7 template-import resolution, so `json_value` is the fully expanded
/// document — orders of magnitude larger than the authored file — and the clone
/// was a full deep copy of it that existed only to be consumed by the very next
/// line and dropped. Same typed result, same verdict; one fewer copy of the
/// expanded AST.
fn check_circular_model_dependencies_typed(json_value: &Value, errors: &mut Vec<String>) {
    use serde::Deserialize as _;
    // An edge joins two DIFFERENT models (a model's reference into itself or
    // its own subsystems is not one), so with fewer than two there is no
    // cycle to find, and no reason to deserialize the whole document for it.
    let n_models = json_value
        .get("models")
        .and_then(|m| m.as_object())
        .map_or(0, |m| m.len());
    if n_models < 2 {
        return;
    }
    let Ok(esm_file) = EsmFile::deserialize(json_value) else {
        return;
    };
    let Some(models) = esm_file.models.as_ref() else {
        return;
    };
    let mut typed_errors: Vec<crate::validate::StructuralError> = Vec::new();
    crate::structural::check_circular_dependencies_in_models(models, &mut typed_errors);
    for e in typed_errors {
        // Preserve the load-time wording — the string must name a "cycle" and
        // list the participating models — by reading the cycle path back off the
        // typed error's `details`.
        let cycle = e
            .details
            .get("cycle")
            .and_then(|v| v.as_array())
            .map(|arr| {
                arr.iter()
                    .filter_map(|v| v.as_str())
                    .collect::<Vec<_>>()
                    .join(" -> ")
            })
            .unwrap_or_default();
        errors.push(format!("circular reference (cycle) detected: {cycle}"));
    }
}

/// Every variable referenced by an event — either on the LHS of an
/// `affects` equation or inside a condition / trigger expression — must be
/// declared in the host model's `variables` map. Applies to both continuous
/// and discrete events. Mirrors Python's `_check_event_references` and
/// Julia's equivalent to keep cross-language error codes aligned per spec
/// §2.1a (error code: `EventVarUndeclared`).
fn check_event_variable_references(obj: &serde_json::Map<String, Value>, errors: &mut Vec<String>) {
    let Some(models) = obj.get("models").and_then(|v| v.as_object()) else {
        return;
    };

    // Names declared as document-level template metaparameters (esm-spec §9.7).
    // They fold to integer constants during `apply_expression_template`
    // lowering, so a metaparameter name reached through an unlowered node's
    // `bindings` (which `collect_variable_refs` descends, running BEFORE that
    // lowering) is NOT an undeclared model variable. Excluding them here keeps
    // the newly-widened walk from raising a false `EventVarUndeclared`.
    let metaparameters: std::collections::HashSet<&str> = obj
        .get("metaparameters")
        .and_then(|v| v.as_object())
        .map(|m| m.keys().map(String::as_str).collect())
        .unwrap_or_default();

    let coupled = coupled_system_names_raw(obj);

    for (mname, mv) in models {
        let Some(m) = mv.as_object() else { continue };
        let Some(vars) = m.get("variables").and_then(|v| v.as_object()) else {
            continue;
        };
        let mut declared: std::collections::HashSet<&str> =
            vars.keys().map(String::as_str).collect();

        // The §6.4 operator placeholder. In an operator-composed / coupled model
        // `_var` stands for each matching state variable of the system this one
        // is composed with, and it is substituted at composition — so an event
        // affect that ASSIGNS to it is legal, exactly as an equation that
        // differentiates it is. Reporting `_var` as an undeclared event variable
        // while the very same document's equations are exempt from the reference
        // check is internally inconsistent, and it rejected the valid
        // tests/valid/full_coupled.esm. Credited only for a COUPLED model, so a
        // genuinely undeclared event target is still caught everywhere else.
        if coupled.contains(mname.as_str()) {
            declared.insert("_var");
        }

        // Continuous events: affects[].lhs must be declared; conditions[] expr
        // bare variable refs must be declared.
        if let Some(events) = m.get("continuous_events").and_then(|v| v.as_array()) {
            for (ei, event) in events.iter().enumerate() {
                let Some(event_obj) = event.as_object() else {
                    continue;
                };
                if let Some(affects) = event_obj.get("affects").and_then(|v| v.as_array()) {
                    for (ai, affect) in affects.iter().enumerate() {
                        if let Some(lhs) = affect.get("lhs").and_then(|v| v.as_str())
                            && !lhs.contains('.')
                            && !declared.contains(lhs)
                        {
                            errors.push(format!(
                                "models/{mname}/continuous_events[{ei}]/affects[{ai}]/lhs: \
                                 undeclared variable '{lhs}'"
                            ));
                        }
                    }
                }
                if let Some(conditions) = event_obj.get("conditions").and_then(|v| v.as_array()) {
                    for (ci, cond) in conditions.iter().enumerate() {
                        let mut refs: Vec<String> = Vec::new();
                        collect_variable_refs(cond, &mut refs);
                        for r in refs {
                            if r.contains('.') || metaparameters.contains(r.as_str()) {
                                continue;
                            }
                            if !declared.contains(r.as_str()) {
                                errors.push(format!(
                                    "models/{mname}/continuous_events[{ei}]/conditions[{ci}]: \
                                     undeclared variable '{r}'"
                                ));
                            }
                        }
                    }
                }
            }
        }

        // Discrete events: affects[].lhs, plus trigger.expression if of type `condition`.
        if let Some(events) = m.get("discrete_events").and_then(|v| v.as_array()) {
            for (ei, event) in events.iter().enumerate() {
                let Some(event_obj) = event.as_object() else {
                    continue;
                };
                if let Some(affects) = event_obj.get("affects").and_then(|v| v.as_array()) {
                    for (ai, affect) in affects.iter().enumerate() {
                        if let Some(lhs) = affect.get("lhs").and_then(|v| v.as_str())
                            && !lhs.contains('.')
                            && !declared.contains(lhs)
                        {
                            errors.push(format!(
                                "models/{mname}/discrete_events[{ei}]/affects[{ai}]/lhs: \
                                 undeclared variable '{lhs}'"
                            ));
                        }
                    }
                }
                if let Some(trigger) = event_obj.get("trigger").and_then(|v| v.as_object())
                    && trigger.get("type").and_then(|v| v.as_str()) == Some("condition")
                    && let Some(expression) = trigger.get("expression")
                {
                    let mut refs: Vec<String> = Vec::new();
                    collect_variable_refs(expression, &mut refs);
                    for r in refs {
                        if r.contains('.') || metaparameters.contains(r.as_str()) {
                            continue;
                        }
                        if !declared.contains(r.as_str()) {
                            errors.push(format!(
                                "models/{mname}/discrete_events[{ei}]/trigger/expression: \
                                 undeclared variable '{r}'"
                            ));
                        }
                    }
                }
            }
        }
    }
}

// ---- structural helpers ---------------------------------------------------

/// Collect every bare `Expr::Variable`-style string out of an expression tree.
///
/// Descends EXACTLY the expression-bearing operator-node fields visited by the
/// typed walker [`crate::types::ExpressionNode::for_each_child`], enumerated
/// here through the shared [`crate::types::EXPR_ARRAY_CHILD_KEYS`] /
/// [`EXPR_SCALAR_CHILD_KEYS`](crate::types::EXPR_SCALAR_CHILD_KEYS) /
/// [`EXPR_MAP_CHILD_KEYS`](crate::types::EXPR_MAP_CHILD_KEYS) constants so the
/// raw-JSON and typed traversals cannot drift: `args`, `values`, `lower`,
/// `upper`, `expr`, `filter`, `key`, `axes`, and `bindings`. This ensures
/// references hidden in aggregate bodies, filter predicates, integral bounds,
/// grouping `key`s, table-lookup `axes`, and template `bindings` are not
/// missed. Non-expression metadata keys (`ranges`, `output_idx`, `regions`, …)
/// are deliberately not descended: their strings are index symbols and set
/// names, not variable references.
///
/// This runs at LOAD time, BEFORE `apply_expression_template` lowering — it
/// feeds `check_event_variable_references`.
/// It therefore also collects the argument strings inside a `bindings` map and
/// any bound index symbols inside a `key`/body. A caller that flags bare
/// undeclared names (`check_event_variable_references`) must exclude names that
/// are not model variables at this point — notably template metaparameters,
/// which fold to constants during lowering — rather than relying on this
/// collector to omit them (see the metaparameter guard there).
fn collect_variable_refs(expr: &Value, out: &mut Vec<String>) {
    match expr {
        Value::String(s) => out.push(s.clone()),
        Value::Object(obj) => {
            for key in crate::types::EXPR_ARRAY_CHILD_KEYS {
                if let Some(items) = obj.get(key).and_then(|v| v.as_array()) {
                    for a in items {
                        collect_variable_refs(a, out);
                    }
                }
            }
            for key in crate::types::EXPR_SCALAR_CHILD_KEYS {
                if let Some(child) = obj.get(key) {
                    collect_variable_refs(child, out);
                }
            }
            for key in crate::types::EXPR_MAP_CHILD_KEYS {
                if let Some(map) = obj.get(key).and_then(|v| v.as_object()) {
                    for child in map.values() {
                        collect_variable_refs(child, out);
                    }
                }
            }
        }
        Value::Array(arr) => {
            for a in arr {
                collect_variable_refs(a, out);
            }
        }
        _ => {}
    }
}

struct SymbolTables {
    /// Names of all top-level systems (models + reaction_systems + data_sources).
    all_systems: std::collections::HashSet<String>,
    /// Per-system: the set of variable names declared in that system.
    per_system: std::collections::HashMap<String, std::collections::HashSet<String>>,
}

impl SymbolTables {
    fn has_variable(&self, system: &str, var: &str) -> bool {
        self.per_system
            .get(system)
            .map(|s| s.contains(var))
            .unwrap_or(false)
    }
}

/// Collect the keys of a component's `variables` object as a set of names,
/// yielding an empty set when the field is absent or not an object.
fn variable_keys(node: &Value) -> std::collections::HashSet<String> {
    node.as_object()
        .and_then(|o| o.get("variables"))
        .and_then(|v| v.as_object())
        .map(|vs| vs.keys().cloned().collect())
        .unwrap_or_default()
}

fn build_symbol_tables(obj: &serde_json::Map<String, Value>) -> SymbolTables {
    let mut all_systems: std::collections::HashSet<String> = std::collections::HashSet::new();
    let mut per_system: std::collections::HashMap<String, std::collections::HashSet<String>> =
        std::collections::HashMap::new();

    if let Some(models) = obj.get("models").and_then(|v| v.as_object()) {
        for (name, m) in models {
            all_systems.insert(name.clone());
            per_system.insert(name.clone(), variable_keys(m));
        }
    }

    if let Some(rsystems) = obj.get("reaction_systems").and_then(|v| v.as_object()) {
        for (name, rs) in rsystems {
            all_systems.insert(name.clone());
            let mut set: std::collections::HashSet<String> = std::collections::HashSet::new();
            if let Some(rso) = rs.as_object() {
                if let Some(sp) = rso.get("species").and_then(|v| v.as_object()) {
                    set.extend(sp.keys().cloned());
                }
                if let Some(params) = rso.get("parameters").and_then(|v| v.as_object()) {
                    set.extend(params.keys().cloned());
                }
            }
            per_system.insert(name.clone(), set);
        }
    }

    if let Some(loaders) = obj.get("data_sources").and_then(|v| v.as_object()) {
        for (name, d) in loaders {
            all_systems.insert(name.clone());
            per_system.insert(name.clone(), variable_keys(d));
        }
    }

    // Operators are also addressable by name (scoped refs may point into
    // their config.subsystems) so they count as top-level systems for
    // reference-existence checks, matching Python / Julia.
    if let Some(operators) = obj.get("operators").and_then(|v| v.as_object()) {
        for name in operators.keys() {
            all_systems.insert(name.clone());
            per_system.entry(name.clone()).or_default();
        }
    }

    SymbolTables {
        all_systems,
        per_system,
    }
}

// ---- lightweight format validators ---------------------------------------

/// Accept `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS[.fff][Z|±HH:MM]`.
fn is_iso8601_datetime(s: &str) -> bool {
    let bytes = s.as_bytes();
    if bytes.len() < 10 {
        return false;
    }
    // Date portion
    if !(bytes[0].is_ascii_digit()
        && bytes[1].is_ascii_digit()
        && bytes[2].is_ascii_digit()
        && bytes[3].is_ascii_digit()
        && bytes[4] == b'-'
        && bytes[5].is_ascii_digit()
        && bytes[6].is_ascii_digit()
        && bytes[7] == b'-'
        && bytes[8].is_ascii_digit()
        && bytes[9].is_ascii_digit())
    {
        return false;
    }
    if bytes.len() == 10 {
        return true;
    }
    // Must have T separator next
    if bytes[10] != b'T' {
        return false;
    }
    // Time portion HH:MM:SS
    if bytes.len() < 19
        || !(bytes[11].is_ascii_digit()
            && bytes[12].is_ascii_digit()
            && bytes[13] == b':'
            && bytes[14].is_ascii_digit()
            && bytes[15].is_ascii_digit()
            && bytes[16] == b':'
            && bytes[17].is_ascii_digit()
            && bytes[18].is_ascii_digit())
    {
        return false;
    }
    let mut idx = 19;
    // Optional fractional seconds
    if idx < bytes.len() && bytes[idx] == b'.' {
        idx += 1;
        let start = idx;
        while idx < bytes.len() && bytes[idx].is_ascii_digit() {
            idx += 1;
        }
        if idx == start {
            return false;
        }
    }
    // Timezone (optional)
    if idx == bytes.len() {
        return true;
    }
    if bytes[idx] == b'Z' {
        return idx + 1 == bytes.len();
    }
    if bytes[idx] == b'+' || bytes[idx] == b'-' {
        // ±HH:MM or ±HHMM
        let rest = &bytes[idx + 1..];
        return (rest.len() == 5
            && rest[0].is_ascii_digit()
            && rest[1].is_ascii_digit()
            && rest[2] == b':'
            && rest[3].is_ascii_digit()
            && rest[4].is_ascii_digit())
            || (rest.len() == 4 && rest.iter().all(|b| b.is_ascii_digit()));
    }
    false
}

/// Accept `^https?://[^\s/$.?#].[^\s]*$` — the loose URL shape Python uses.
fn is_valid_url(s: &str) -> bool {
    let lowered = s.to_ascii_lowercase();
    if !(lowered.starts_with("http://") || lowered.starts_with("https://")) {
        return false;
    }
    let scheme_len = if lowered.starts_with("https://") {
        8
    } else {
        7
    };
    let after = &s[scheme_len..];
    if after.is_empty() {
        return false;
    }
    // Must have at least one dot in the host section before any path separator.
    let host_end = after.find('/').unwrap_or(after.len());
    let host = &after[..host_end];
    if host.is_empty() || !host.contains('.') {
        return false;
    }
    !s.chars().any(|c| c.is_whitespace())
}

/// Accept `^10\.\d{4,9}/[^\s]+$` — the DOI shape defined by CrossRef.
fn is_valid_doi(s: &str) -> bool {
    let Some(rest) = s.strip_prefix("10.") else {
        return false;
    };
    let Some(slash) = rest.find('/') else {
        return false;
    };
    let registrant = &rest[..slash];
    let suffix = &rest[slash + 1..];
    if !(4..=9).contains(&registrant.len()) || !registrant.bytes().all(|b| b.is_ascii_digit()) {
        return false;
    }
    !suffix.is_empty() && !suffix.chars().any(|c| c.is_whitespace())
}

/// Accept the ISO 8601 duration shape Python enforces: `P` followed by an
/// optional date part (`\d+Y`, `\d+M`, `\d+W`, `\d+D`) and an optional time
/// part introduced by `T` (`\d+H`, `\d+M`, `\d+(\.\d+)?S`). Must have at
/// least one component.
fn is_iso8601_duration(s: &str) -> bool {
    let mut chars = s.chars().peekable();
    if chars.next() != Some('P') {
        return false;
    }
    let mut any_component = false;

    // Date components before T
    while let Some(&c) = chars.peek() {
        if c == 'T' {
            break;
        }
        if !c.is_ascii_digit() {
            return false;
        }
        // consume digits
        while let Some(&d) = chars.peek() {
            if d.is_ascii_digit() {
                chars.next();
            } else {
                break;
            }
        }
        match chars.next() {
            Some('Y') | Some('M') | Some('W') | Some('D') => {
                any_component = true;
            }
            _ => return false,
        }
    }

    if chars.peek() == Some(&'T') {
        chars.next();
        while let Some(&c) = chars.peek() {
            if !c.is_ascii_digit() {
                return false;
            }
            while let Some(&d) = chars.peek() {
                if d.is_ascii_digit() {
                    chars.next();
                } else {
                    break;
                }
            }
            // Optional fractional seconds — only valid before the final `S`
            if chars.peek() == Some(&'.') {
                chars.next();
                let mut had_digit = false;
                while let Some(&d) = chars.peek() {
                    if d.is_ascii_digit() {
                        chars.next();
                        had_digit = true;
                    } else {
                        break;
                    }
                }
                if !had_digit {
                    return false;
                }
                if chars.next() != Some('S') {
                    return false;
                }
                any_component = true;
                break;
            }
            match chars.next() {
                Some('H') | Some('M') | Some('S') => {
                    any_component = true;
                }
                _ => return false,
            }
        }
    }

    any_component && chars.next().is_none()
}

/// Rewrite every deprecated expression-node `op` spelling to its canonical tag,
/// in place, and warn once for the document.
///
/// The one alias is `aggregate` → `faq` (esm 1.1.0,
/// `docs/content/rfcs/faq-node-rename.md`). Normalizing at the wire boundary is
/// what lets the rest of the crate recognize exactly one spelling: nothing
/// downstream of the loader — [`crate::faq::is_faq_op`] included — ever sees the
/// alias, and a document authored with `aggregate` is upgraded exactly once, on
/// its first load.
///
/// The older `arrayop` spelling is NOT normalized: it was removed at esm 0.8.0
/// and is rejected like any other unknown non-rewrite-target op.
pub(crate) fn prepare_document_ops(value: &mut serde_json::Value) -> Result<(), EsmError> {
    prepare_document_ops_scanned(value).map(|_| ())
}

/// What [`prepare_document_ops_scanned`]'s walk also noted about the authored
/// document, for a later pass that would otherwise walk it again.
pub(crate) struct AuthoredFacts {
    /// The path of the first object, in pre-order, with both an `op` and a
    /// `units` key (what [`crate::units::reject_const_units_pre_v12`] looks for).
    pub(crate) op_with_units: Option<String>,
    /// Whether any object has a `ref` or a `subsystems` key: without one,
    /// subsystem ref resolution has nothing to splice in.
    pub(crate) mounts: bool,
}

/// [`prepare_document_ops`], returning the [`AuthoredFacts`] its walk noted.
pub(crate) fn prepare_document_ops_scanned(
    value: &mut serde_json::Value,
) -> Result<AuthoredFacts, EsmError> {
    // The three steps below read and rewrite `op` tags, so they share ONE walk
    // over the document: it finds the first `arrayop` node, the first
    // AUTHORED `faq` node (looked for only when the declared version is below
    // 1.1.0, the one case the gate can fire), and rewrites every `aggregate`
    // node, in pre-order. On an error the rewritten document is discarded, so
    // the error is the one the steps would report taken one at a time.
    let faq_too_old = value
        .get("esm")
        .and_then(|v| v.as_str())
        .and_then(crate::diagnostic::parse_semver)
        .is_some_and(|(major, minor, _)| (major, minor) < (1, 1));
    let esm_declared = value
        .get("esm")
        .and_then(|v| v.as_str())
        .map(str::to_string);
    let mut scan = OpScan {
        want_faq: faq_too_old,
        ..OpScan::default()
    };
    scan_document_ops(value, &crate::json_visit::JsonPath::Root(""), &mut scan);
    let facts = AuthoredFacts {
        op_with_units: scan.op_with_units.take(),
        mounts: scan.mounts,
    };
    // 1. `arrayop` was REMOVED at 0.8.0 — rejected by name, before anything else.
    if let Some(path) = scan.removed {
        return Err(EsmError::SchemaValidation(format!(
            "removed_op at {path}: `\"op\": \"arrayop\"` was removed at esm 0.8.0 and is not a \
             deprecated alias; use `\"op\": \"faq\"` (the Functional Aggregate Query node). \
             See docs/content/rfcs/faq-node-rename.md."
        )));
    }
    // 2. Version gate, on the AUTHORED form. `faq` arrives at esm 1.1.0, so a
    //    document that spells it while declaring less is rejected — the same
    //    rule the top-level `solver` block follows (esm-spec §2.2.4). The walk
    //    judged each node BEFORE rewriting it on purpose: `aggregate` IS the
    //    pre-1.1.0 spelling, so a 1.0.0 document carrying the alias is legal
    //    and must not be caught by this gate.
    if let Some(path) = scan.faq
        && let Some(esm) = esm_declared
    {
        return Err(EsmError::SchemaValidation(format!(
            "faq_version_too_old at {path}: the `faq` op arrives at esm 1.1.0; file \
             declares {esm}. Use `\"op\": \"aggregate\"` (the deprecated pre-1.1.0 \
             spelling) or raise the declared version. \
             See docs/content/rfcs/faq-node-rename.md."
        )));
    }
    // 3. The alias was normalized by the walk; raise the declared version with
    //    it so the upgraded document is self-consistent (a floor, never a
    //    downgrade).
    let n = scan.rewritten;
    if n > 0 {
        raise_esm_floor_to_v11(value);
    }
    if n > 0 {
        let plural = if n == 1 { "node was" } else { "nodes were" };
        eprintln!(
            "warning: deprecated_op_alias: `\"op\": \"aggregate\"` is the pre-1.1.0 spelling \
             of `\"op\": \"faq\"` (Functional Aggregate Query); {n} {plural} normalized on \
             load. The alias is REMOVED at esm 2.0.0 — re-emit this document to migrate it \
             (docs/content/rfcs/faq-node-rename.md)."
        );
    }
    Ok(facts)
}

/// What [`scan_document_ops`] found.
#[derive(Default)]
struct OpScan {
    /// Look for authored `faq` nodes at all.
    want_faq: bool,
    /// The path of the first `"op": "arrayop"` node. `arrayop` is REMOVED,
    /// not deprecated: without this check it is a perfectly well-formed
    /// identifier and would fall into the OPEN rewrite-target tier (esm-spec
    /// §4.2), loading silently and failing only much later as an
    /// `unlowered_operator`.
    removed: Option<String>,
    /// The path of the first `"op": "faq"` node as authored.
    faq: Option<String>,
    /// `aggregate` nodes rewritten to `faq`.
    rewritten: usize,
    /// See [`AuthoredFacts`].
    op_with_units: Option<String>,
    mounts: bool,
}

/// Pre-order walk (the root included, a container before its elements, array
/// elements in index order, object entries in map order): record the first
/// `arrayop` node's path and, when asked, the first authored `faq` node's,
/// and rewrite each `"op": "aggregate"` to `"op": "faq"`. A removed op ends
/// the walk, since the document is then rejected.
fn scan_document_ops(
    value: &mut serde_json::Value,
    at: &crate::json_visit::JsonPath<'_>,
    scan: &mut OpScan,
) {
    use crate::json_visit::JsonPath;
    match value {
        serde_json::Value::Object(map) => {
            let op = crate::json_visit::small_get(map, "op");
            if scan.op_with_units.is_none()
                && op.is_some()
                && crate::json_visit::small_get(map, "units").is_some()
            {
                scan.op_with_units = Some(at.to_string());
            }
            scan.mounts |= crate::json_visit::small_get(map, "ref").is_some()
                || crate::json_visit::small_get(map, "subsystems").is_some();
            match op.and_then(|v| v.as_str()) {
                Some("arrayop") => {
                    scan.removed = Some(at.to_string());
                    return;
                }
                Some("faq") if scan.want_faq && scan.faq.is_none() => {
                    scan.faq = Some(at.to_string());
                }
                Some("aggregate") => {
                    map.insert(
                        "op".to_string(),
                        serde_json::Value::String("faq".to_string()),
                    );
                    scan.rewritten += 1;
                }
                _ => {}
            }
            for (k, v) in map.iter_mut() {
                scan_document_ops(v, &JsonPath::Key(at, k), scan);
                if scan.removed.is_some() {
                    return;
                }
            }
        }
        serde_json::Value::Array(items) => {
            for (i, v) in items.iter_mut().enumerate() {
                scan_document_ops(v, &JsonPath::Index(at, i), scan);
                if scan.removed.is_some() {
                    return;
                }
            }
        }
        _ => {}
    }
}

/// Raise a document's declared `esm` to 1.1.0 when it sits below that floor.
///
/// Normalizing `aggregate` to `faq` would otherwise produce a document that
/// spells a 1.1.0 construct while declaring an older version — precisely what
/// the gate above rejects. The stamp is a FLOOR: a document already at or above
/// 1.1.0 keeps its own version.
fn raise_esm_floor_to_v11(value: &mut serde_json::Value) {
    let below = value
        .get("esm")
        .and_then(|v| v.as_str())
        .and_then(crate::diagnostic::parse_semver)
        .is_some_and(|(major, minor, _)| (major, minor) < (1, 1));
    if below && let Some(obj) = value.as_object_mut() {
        obj.insert(
            "esm".to_string(),
            serde_json::Value::String("1.1.0".to_string()),
        );
    }
}

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

    /// The one walk of `prepare_document_ops` reports what its three steps
    /// did taken one at a time: the first `arrayop` anywhere wins over an
    /// earlier authored `faq`, the version gate names the first authored
    /// `faq` (never a rewritten `aggregate`), and every `aggregate` is
    /// rewritten.
    #[test]
    fn prepare_document_ops_reports_as_its_steps_did() {
        use serde_json::json;
        let run = |mut v: Value| {
            prepare_document_ops(&mut v)
                .map(|()| v)
                .map_err(|e| e.to_string())
        };
        let e =
            run(json!({"esm": "1.0.0", "a": {"op": "faq"}, "b": [{"op": "x"}, {"op": "arrayop"}]}))
                .unwrap_err();
        assert!(e.contains("removed_op at /b/1:"), "{e}");
        let e = run(json!({"esm": "1.0.0", "a": {"op": "aggregate", "args": [{"op": "faq"}]}, "b": {"op": "faq"}}))
            .unwrap_err();
        assert!(e.contains("faq_version_too_old at /a/args/0:"), "{e}");
        assert!(e.contains("file declares 1.0.0"), "{e}");
        let v =
            run(json!({"esm": "1.0.0", "a": {"op": "aggregate", "args": [{"op": "aggregate"}]}}))
                .unwrap();
        assert_eq!(
            v,
            json!({"esm": "1.1.0", "a": {"op": "faq", "args": [{"op": "faq"}]}})
        );
        let v = run(json!({"esm": "1.1.0", "a": {"op": "faq"}})).unwrap();
        assert_eq!(v, json!({"esm": "1.1.0", "a": {"op": "faq"}}));
    }

    #[test]
    fn test_load_minimal_model() {
        let json = r#"
        {
          "esm": "1.0.0",
          "metadata": {
            "name": "test_model"
          },
          "models": {
            "simple": {
              "variables": {},
              "equations": []
            }
          }
        }
        "#;

        let result = load_string(json);
        assert!(result.is_ok());

        let esm_file = result.unwrap();
        assert_eq!(esm_file.esm, "1.0.0");
        assert!(esm_file.models.is_some());
    }

    #[test]
    fn test_load_invalid_json() {
        let json = r#"{ invalid json }"#;
        let result = load_string(json);
        assert!(result.is_err());
        match result.unwrap_err() {
            EsmError::JsonParse(_) => {} // Expected
            _ => panic!("Expected JsonParse error"),
        }
    }

    #[test]
    fn test_load_missing_esm_version() {
        let json = r#"
        {
          "metadata": {
            "name": "test_model"
          },
          "models": {}
        }
        "#;

        let result = load_string(json);
        assert!(result.is_err());
        match result.unwrap_err() {
            EsmError::SchemaValidation(_) => {} // Expected
            _ => panic!("Expected SchemaValidation error"),
        }
    }

    #[test]
    fn test_load_malformed_esm_version() {
        let json = r#"
        {
          "esm": "not-a-version",
          "metadata": {
            "name": "test_model"
          },
          "models": {}
        }
        "#;

        let result = load_string(json);
        assert!(result.is_err());
        match result.unwrap_err() {
            EsmError::SchemaValidation(_) => {} // Expected
            _ => panic!("Expected SchemaValidation error"),
        }
    }

    #[test]
    fn test_load_missing_content() {
        let json = r#"
        {
          "esm": "1.0.0",
          "metadata": {
            "name": "test_model"
          }
        }
        "#;

        let result = load_string(json);
        assert!(result.is_err());
        match result.unwrap_err() {
            EsmError::SchemaValidation(_) => {} // Expected
            _ => panic!("Expected SchemaValidation error"),
        }
    }

    #[test]
    fn test_round_trip() {
        use crate::to_json;

        let json = r#"
        {
          "esm": "1.0.0",
          "metadata": {
            "name": "test_model"
          },
          "models": {
            "simple": {
              "variables": {},
              "equations": []
            }
          }
        }
        "#;

        // Load the JSON
        let esm_file = load_string(json).expect("Failed to load ESM file");

        // Save it back to JSON
        let serialized_json = to_json(&esm_file).expect("Failed to save ESM file");

        // Load it again
        let round_trip_file =
            load_string(&serialized_json).expect("Failed to load round-trip ESM file");

        // Verify the structure is preserved
        assert_eq!(esm_file.esm, round_trip_file.esm);
        assert_eq!(esm_file.metadata.name, round_trip_file.metadata.name);
        assert!(esm_file.models.is_some());
        assert!(round_trip_file.models.is_some());

        let models1 = esm_file.models.as_ref().unwrap();
        let models2 = round_trip_file.models.as_ref().unwrap();
        assert_eq!(models1.len(), models2.len());
        assert!(models1.contains_key("simple"));
        assert!(models2.contains_key("simple"));
    }
}