@earthsciml/ast 0.1.1

package/dist/esm/index.d.ts

@@ -0,0 +1,4758 @@
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+/**
+ * EarthSciML Serialization Format (v1.0.0) — a language-agnostic JSON format for Earth system model components, their composition, and runtime configuration. v1.0.0 is a clean break with no deprecation path and no compatibility shims (docs/content/rfcs/unified-variable-model.md): the five declared variable types collapse to TWO. `unknown` is a quantity the solver solves for — its behavior is given by EQUATIONS and never by a field on the variable — and `parameter` is a quantity supplied to the solver, carrying a number or a `distribution` plus an optional `update` block saying when and from what it refreshes. Removed: `state` and `observed` (with the `expression` field — an observed variable becomes an unknown plus a bare-variable-LHS equation); `brownian` (with `noise_kind` / `correlation_group` — a noise source is a parameter with a `distribution` and `update.kind: "wiener"`, correlated noise being ONE vector-valued parameter whose distribution carries a `cov` matrix, which closes the gap the 0.x schema explicitly deferred); `discrete` (with `refresh` and the `RefreshTrigger` def — a refreshing input is a parameter with a `schedule` / `data` / `remesh` update); the `discrete_parameters` event lists and the event `functional_affect` (parameter mutation moves onto the parameter itself as a `condition` / `crossing` update carrying an `expression`, a `from` binding, or a `handler`; events now affect UNKNOWNS only); and the `data_loaders` COMPONENT kind together with `DataLoader.variables` (top-level `data_sources` is now a pure registry of ingest configuration — source, temporal, select, record_filter, extent, reader_options, determinism — that parameters draw from via `update.from`; a data source is no longer a coupling endpoint, a subsystem, or a scoped-name path root). Everything the solver needs is DERIVED rather than declared — which unknowns are ODE states, observed, or algebraic, and which parameters are Brownian, discrete, sampled, or constant — and every binding exposes the same classification functions to derive it (esm-spec §6.3.1). v0.9.0 changes no on-disk shape: it replaces the Option A (always-expanded) template round-trip with Option B (reference-preserving; esm-spec §9.6.4, docs/content/rfcs/out-of-line-expression-templates.md). Template references survive load and parse-then-emit; emit materializes each component's referenced templates into its `expression_templates` registry (authored entries first in authored order, materialized entries after in lexicographic UTF-8 name order; registry keys may be dotted post-rename names); eager references (target-bearing, esm-spec §9.6.4 rule 3) still expand at load, so no rewrite-target op survives inside a reference; `emit ∘ load` is a byte-wise fixed point; emitted documents carrying surviving references or materialized registries declare `esm: 0.9.0` or later. v0.8.0 is a clean break that removes all bespoke spatial-grid machinery in favor of expressing grid geometry directly with the unified Functional Aggregate Query (`aggregate`) IR (RFC semiring-faq-unified-ir), and retains no backward-compatibility shims. Removed: the top-level `grids`, `staggering_rules`, and `discretizations` blocks; the `Grid` / `GridExtent` / `GridMetricArray` / `GridMetricGenerator` / `GridConnectivity` / `GridCRS` defs; the entire stencil-template discretization rule grammar (`Discretization`, `DiscretizationVariant`, `MultiOutputStencilRule`, `DiscretizationRef`, `GridDiscretizationDescriptor`, and the `Rule` / `PatternNode` / `NeighborSelector` / `StencilEntry` / `RuleBinding` / `BoundaryPolicy` / `BoundaryPolicySpec` / `GhostWidth` / `GhostVarDecl` / `RuleRegion` / `RuleGuard` machinery, including `Equation.region`); all regridding configuration (`Model.regrid`, `RegridSpec`, `Interface.regridding`); the `Domain.spatial` / `SpatialDimension` / `CoordinateTransform` geometry block and the deprecated domain-level `boundary_conditions`; the `DataLoader.grid` / `DataLoader.mesh` descriptors and the `DataLoaderMesh` def; and the `grid_discretization_descriptor` document kind with its `grid_refs` test/example fields. Grid geometry — coordinates, extents, spacing, CRS parameters, connectivity, and metric arrays — is now ordinary data: loaded from a `data_loaders` primitive or declared as variables/parameters, with topology and metrics constructed declaratively as `aggregate` FAQs (the `intersect_polygon` kernel leaf remains for polygon clipping). Iteration domains are declared once in the document-scoped `index_sets` registry. Regridding is expressed as an ordinary coupling expression between two variables. Earlier additive features are retained: the `integral` AST op (PIDEs), array-or-single `plots.y`, sampled `function_tables` + `table_lookup`, in-file `expression_templates` + `apply_expression_template`, and the closed `enums` + `fn` / `enum` ops. The template-library RFC (docs/content/rfcs/template-library-imports.md; esm-spec §9.7) adds cross-file template sharing at esm 0.8.0: template-library files (top-level `expression_templates`), ordered `expression_template_imports` with §4.7 reference semantics, and load-time integer `metaparameters` admissible in `index_sets` sizes, `aggregate` dense ranges, and `makearray` regions — all resolved and folded at load, before validation and before the §9.6.3 rewrite fixpoint.
+ */
+type ESMFormat = ESMFormat1 & ESMFormat2;
+type ESMFormat1 = {
+    [k: string]: unknown;
+};
+/**
+ * A variable in a model — either an `unknown` the solver solves for, or a `parameter` supplied to it. There is no third kind. Everything the solver additionally needs to know is DERIVED: whether an unknown is an ODE state, an observed quantity, or an algebraic one follows from the EQUATIONS, and whether a parameter is Brownian, discrete, sampled, or constant follows from its `distribution` and `update` (esm-spec §6.3.1).
+ */
+type ModelVariable$1 = ModelVariable1 & {
+    /**
+     * unknown = a quantity the solver solves for; its behavior is stated by the model's `equations` and NOWHERE else. parameter = a quantity supplied to the solver, whose value is `default` or a `distribution`, optionally refreshed by an `update`. A checker MUST NOT infer an unknown's role from anything but the equations: an unknown under `D(·, t)` on some equation LHS is an ODE state, one with a bare-variable LHS is observed (eliminable), and one constrained only implicitly (`H*H*SO4 ~ Ksp`) is algebraic.
+     */
+    type: "unknown" | "parameter";
+    units?: string;
+    /**
+     * For an unknown, its initial value at t=0. For a parameter, its constant value — mutually exclusive with `distribution`, which draws the value instead.
+     */
+    default?: number;
+    /**
+     * Units of the default value, if different from the declared units field. When present, validators flag a unit_inconsistency error if these do not match the declared units (including dimensionally incompatible cases like K vs kg, and same-dimension mismatches like K vs degC). Default is the same as `units`.
+     */
+    default_units?: string;
+    description?: string;
+    /**
+     * Arrayed-variable shape: ordered list of index-set names drawn from the document-scoped `index_sets` registry. Omitted or null indicates a scalar. REQUIRED for a parameter whose `update` is `schedule`, `data`, or `remesh` — such a parameter is a buffer whose extent is fixed at setup and refilled on a discrete cadence, so its extent must be known ahead of time (RFC semiring-faq-unified-ir §6.1); an empty array is a valid (scalar) shape.
+     */
+    shape?: string[];
+    /**
+     * Optional free-form placement tag for a staggered quantity (e.g., "cell_center", "edge_normal", "x_face", "vertex"). Advisory metadata only; the index set a quantity lives on is given by `shape`. Omitted indicates no explicit placement.
+     */
+    location?: string;
+    /**
+     * Parameter-only: draw this parameter's value from a distribution instead of fixing it at `default`. Mutually exclusive with `default`. With no `update` it is drawn ONCE at setup (uncertainty quantification / ensembles); with `update.kind: "wiener"` it is redrawn every step with √dt scaling (a stochastic process, which makes the model an SDE).
+     */
+    distribution?: {
+        [k: string]: unknown;
+    } | {
+        kind: "uniform";
+        low: number | [number, ...number[]];
+        high: number | [number, ...number[]];
+    };
+    /**
+     * Parameter-only: when this parameter refreshes and what it refreshes from. Absent means it never changes after setup.
+     */
+    update?: ParameterUpdate$1 | [
+        ParameterUpdate$1 & {
+            [k: string]: unknown;
+        },
+        ParameterUpdate$1 & {
+            [k: string]: unknown;
+        },
+        ...(ParameterUpdate$1 & {
+            [k: string]: unknown;
+        })[]
+    ];
+};
+type ModelVariable1 = {
+    [k: string]: unknown;
+};
+/**
+ * Declares WHEN a parameter refreshes and WHAT it refreshes from. A parameter with no `update` is a constant (or, with a `distribution`, is sampled once at setup). Six kinds. `wiener` is a driving stochastic process and takes no value form — it resamples the parameter's own `distribution`. The other five each take EXACTLY ONE value form: an `expression`, a `from` binding to a data source, or a registered `handler`. Together they subsume three constructs the 0.x format kept apart: the `brownian` variable type (now `wiener`), the `discrete` type with its `RefreshTrigger` (now `schedule` / `data` / `remesh`), and the `discrete_parameters` event lists with their `functional_affect` (now `condition` / `crossing`). This is also the sole seed of the DISCRETE cadence class in the dependency-partition pass (RFC semiring-faq-unified-ir §6.1): without it such inputs would be mis-seeded as CONST (never refresh) or CONTINUOUS (recompute every step).
+ */
+type ParameterUpdate$1 = {
+    kind: "wiener";
+} | {
+    [k: string]: unknown;
+};
+/**
+ * Mathematical expression: a number literal, a variable/parameter reference string, or an operator node.
+ */
+type Expression = number | string | ExpressionNode;
+/**
+ * An operation in the expression AST.
+ */
+type ExpressionNode = ExpressionNode1 & {
+    /**
+     * Operator name. TWO TIERS (esm-spec §4.2). (1) The CLOSED evaluable-core set — every binding's evaluator implements each one directly: `+ - * / ^`, the comparisons/booleans (`> < >= <= == != and or not`), the elementary functions (`exp log log10 sqrt abs sign sin cos tan asin acos atan atan2 sinh cosh tanh asinh acosh atanh min max floor ceil`), `ifelse`, the calculus form-ops `D` and `ic` (structural / equation-LHS use only), `Pre`, `true`, and the array/query ops (`aggregate makearray index broadcast reshape transpose concat skolem rank argmin argmax intersect_polygon polygon_intersection_area fn enum const table_lookup apply_expression_template`). (2) The OPEN rewrite-target tier — ANY other identifier: a spatial `D` on a right-hand side, the optional sugar ops `grad`/`div`/`laplacian`/`integral`, or a user op such as `godunov_hamiltonian`. A rewrite-target op carries NO evaluator implementation and MUST be eliminated by a rewrite rule (§9.6) before evaluation. Loading is permissive — a file MAY load with rewrite-target ops still present (e.g. a coupling/scoping example that never simulates) — but one reaching evaluation/compilation without being lowered is rejected with `unlowered_operator`. The `pattern` only rejects malformed strings — it does NOT enforce membership in the core set, so the open tier stays expressible. The evaluable-core set is the ONLY set the format privileges.
+     */
+    op: string;
+    /**
+     * Stable node identity (RFC semiring-faq-unified-ir §6.1): an optional, author-assigned identifier that makes this expression node addressable as a vertex in the inter-node dependency DAG the partition pass walks. Its primary use is to be the referent of a derived index set: an `index_sets` entry of kind "derived" names, via `from_faq`, the index-set-producing `aggregate` node that materializes it — and it names it by this id. When present it MUST be unique among the expression nodes of its model; the build-time reference-resolution pass errors on a duplicate id and on a `from_faq` that names no node. Absent ⇒ the node is addressed only by its structural path and cannot be the target of a `from_faq`. Purely additive: a file using no `id` validates and resolves exactly as before.
+     */
+    id?: string;
+    /**
+     * Optional author assertion on this node's cadence class, checked by the dependency-partition pass (RFC semiring-faq-unified-ir §6.1; CONFORMANCE_SPEC.md §5.7). A diagnostic/test hook ONLY — it changes no semantics. The pass derives every node's class from the data-dependency DAG (`class(node) = max` over inputs; `const ⊏ discrete ⊏ continuous`); when `expect_cadence` is present the pass errors if the DERIVED class disagrees with it. "const" = never changes, folded into the artifact (parameter / literal); "discrete" = changes only at discrete events, recomputed by the per-event handler (a `discrete` variable, e.g. loaded met / reloadable mesh); "continuous" = changes every step, evaluated in the hot per-step tree (integrated state `u`, or an explicit continuous-`t` forcing). Absent ⇒ no assertion. Purely additive: a file using no `expect_cadence` validates and partitions exactly as before.
+     */
+    expect_cadence?: "const" | "discrete" | "continuous";
+    /**
+     * Operand list. For most ops these are sub-expressions. Array ops use args for the input array operands (aggregate, broadcast, index, reshape, transpose, concat). makearray has no natural args and uses an empty array. For `D` (esm-spec §4.2 "Arity of `D`"): `args[0]` is always the differentiated operand; a STRUCTURAL `D` (`wrt` "t", or `wrt` absent) is strictly unary, while a REWRITE-TARGET `D` (spatial `wrt`) MAY carry an unbounded number of TRAILING AUXILIARY OPERANDS after `args[0]` — the per-face boundary/halo data a discretization rule binds and consumes (§9.6.8). Trailing operands carry NO evaluator semantics and no per-position meaning assigned by this format; they are matched positionally by the consuming rule.
+     *
+     * @minItems 0
+     */
+    args: Expression[];
+    /**
+     * Differentiation variable for the `D` op: the time variable `t` (structural, equation-LHS use) OR a spatial axis (e.g. "x", "lon"). Absent means `t`. A `D` with a spatial `wrt`, or any `D` appearing in a right-hand-side expression position, is a rewrite-target (esm-spec §9.6.8): it MUST be lowered to a stencil by a discretization rule before evaluation, else `unlowered_operator`. `wrt` also fixes this node's ARITY (esm-spec §4.2 "Arity of `D`"): `wrt` "t" (or absent) is STRICTLY UNARY, enforced by the `D` clause of this object's `allOf`; a spatial `wrt` MAY carry unbounded trailing auxiliary operands in `args[1..]`.
+     */
+    wrt?: string;
+    /**
+     * Scalar field naming a spatial axis (e.g. "x", "y", "z"). Carried by rewrite-target differential-operator sugar (`grad`/`div`/`laplacian`) and admissible on any open-tier rewrite-target op; it is an ordinary axis-naming scalar field with NO privileged status. A `dim` value names a spatial coordinate STRUCTURALLY, independent of the enclosing `op` (esm-spec §4.9.1), and confers no dimensional rule on its op (the op's dimension is UNDETERMINABLE until lowered, §4.8.3/§4.8.4). PREFER `D` with `wrt` set to the axis. Custom rewrite-target ops MAY instead carry scheme parameters in `attrs`.
+     */
+    dim?: string;
+    /**
+     * Optional named scalar attributes for an OPEN rewrite-target op (esm-spec §4.2). Mirrors the role of the fixed `dim`/`side`/`wrt`/`var` slots that core ops use, but is open: a custom op (e.g. `godunov_hamiltonian`) carries its scheme parameters here. In a rewrite rule's `match`, an `attrs.<key>` whose value is a bare param name binds that param to the matched literal (esm-spec §9.6.1). Evaluable-core ops MUST NOT use `attrs`.
+     */
+    attrs?: {
+        [k: string]: unknown;
+    };
+    /**
+     * Integration variable for the integral operator: the name of the spatial dimension being integrated over (e.g., "x").
+     */
+    var?: string;
+    /**
+     * Mathematical expression: a number literal, a variable/parameter reference string, or an operator node.
+     */
+    lower?: Expression;
+    /**
+     * Mathematical expression: a number literal, a variable/parameter reference string, or an operator node.
+     */
+    upper?: Expression;
+    /**
+     * For aggregate: the result's index signature. Each entry is either a string (a symbolic index variable like "i", "j") or the integer 1 (a literal singleton dimension for reshape/broadcast). Mirrors SymbolicUtils.ArrayOp.output_idx.
+     */
+    output_idx?: (string | 1)[];
+    /**
+     * Mathematical expression: a number literal, a variable/parameter reference string, or an operator node.
+     */
+    expr?: Expression;
+    /**
+     * For aggregate: the reduction operator applied to any index symbol that appears in expr but not in output_idx. Default is "+". This names only the ⊕ operator; it is a shorthand retained for files that omit "semiring" (⊕ = reduce, ⊗ = "*"). When "semiring" is present it supersedes "reduce".
+     */
+    reduce?: "+" | "*" | "max" | "min";
+    /**
+     * For aggregate: the named semiring (⊕, ⊗) that parameterizes the reduction (RFC semiring-faq-unified-ir §5.1). A closed, exhaustive registry — adding a semiring is a spec change, not a per-file extension. Absent ⇒ "sum_product", which reproduces today's einsum / sum-of-products semantics exactly (the strict-superset promise). The ⊕ operator, the ⊗ operator, and BOTH identity elements (the value of an empty ⊕-reduction and an empty ⊗-product) are fixed by the registry table and MUST NOT be written into the file: sum_product (+,0;×,1), max_product (max,-∞;×,1), min_sum (min,+∞;+,0), max_sum (max,-∞;+,0), bool_and_or (∨,false;∧,true).
+     */
+    semiring?: "sum_product" | "max_product" | "min_sum" | "max_sum" | "bool_and_or";
+    /**
+     * For aggregate: optional map from index symbol name to the range it iterates over. Each value is EITHER (a) a dense integer tuple — a 2-element array [start, stop] (unit step) or a 3-element array [start, step, stop], as today, mirroring SymbolicUtils.ArrayOp.ranges — entries MAY be metaparameter expressions folded to concrete integers at load (esm-spec §9.7.6); OR (b) a reference to a declared index set (RFC semiring-faq-unified-ir §5.2): an object { "from": <index_sets key> }, optionally with "of": [parent index names] for a ragged / dependent inner set (e.g. the edges of cell "i"). Indices not present are inferred from the domain / operand shapes at runtime.
+     */
+    ranges?: {
+        [k: string]: [MetaparameterExpression, MetaparameterExpression] | [MetaparameterExpression, MetaparameterExpression, MetaparameterExpression] | {
+            /**
+             * Name of a declared index set: a key in the document-scoped top-level index_sets registry. The resolver MUST error on an undeclared name; no implicit interval is inferred, so a typo cannot silently become an empty set.
+             */
+            from: string;
+            /**
+             * Parent index name(s) for a ragged / dependent inner set: the members enumerated depend on these outer indices (e.g. { "from": "edges_of_cell", "of": ["i"] } iterates the edges of cell i).
+             */
+            of?: string[];
+        };
+    };
+    /**
+     * For aggregate: optional value-equality combination of factors by key columns — an inner equi-join (RFC semiring-faq-unified-ir §5.3), subsuming ESI join and making connectivity gathers first-class. Each entry is a join clause whose "on" lists one or more key-column pairs [left, right]; a ⊗-product term is contributed only for index combinations whose key columns are equal on EVERY listed pair, and an unmatched row contributes the additive identity (the empty ⊕-reduction value), adding nothing under any semiring. Inner-only — there is no outer/left variant; many-to-many is defined, not an error (m·n product terms, each a ⊗-term into the enclosing ⊕-reduction); key columns must be exact-equality types (integer IDs or categorical members compared by Unicode code point) — floating-point join keys are forbidden. Absent ⇒ factors combine only by shared index name (positional einsum), exactly as today.
+     */
+    join?: ({
+        [k: string]: unknown;
+    } | {
+        [k: string]: unknown;
+    })[];
+    /**
+     * Mathematical expression: a number literal, a variable/parameter reference string, or an operator node.
+     */
+    filter?: Expression;
+    /**
+     * For aggregate: when true, the node has set semantics (dedup) and is index-set-producing — it materializes a data-derived index set rather than an array (RFC semiring-faq-unified-ir §5.5). Only meaningful under the `bool_and_or` semiring (the relational specialization, §5.1); combined with `key`, it enumerates the unique Skolem terms (e.g. the unique edges discovered from a face→vertex relation) and exposes the result as a `kind:"derived"` index set (§5.2) that a downstream geometric aggregate consumes. The output order is fixed by the normative determinism rules (§5.7): sort by the total tuple order, then drop adjacent duplicates — never first-seen / insertion order. Absent ⇒ false (ordinary array-producing reduction), exactly as today.
+     */
+    distinct?: boolean;
+    /**
+     * Mathematical expression: a number literal, a variable/parameter reference string, or an operator node.
+     */
+    key?: Expression;
+    /**
+     * Optional documentary relation tag for a skolem node (e.g. "edge", "bin", "pair"). Does NOT affect the emitted key; the key components are the node's args.
+     */
+    label?: string;
+    /**
+     * For the arg-witness reducers `argmin` / `argmax` (RFC semiring-faq-unified-ir §5.7 rule 6): names the contracted `ranges` index symbol whose value (a 1-based generator id) is RETURNED at the optimum. The op reduces its `expr` body (a declarative scalar FAQ, e.g. a squared-distance metric) over the inner `ranges` candidate domain — optionally pruned by a bin-Skolem `join` / `filter` — and emits the witnessing INDEX rather than the reduced value: `assign[i] = argmin_g dist(point_i, gen_g)`, the nearest-generator assignment. NET-NEW because the closed semiring registry (§5.1) returns values and the value-invention primitives distinct/skolem/rank (§5.5) return sets — neither returns the arg. Materialized at build time as an integer per-element buffer (CONST/DISCRETE cadence, like the §A.8 bin-Skolem `:map` buffers; a CONTINUOUS arg-witness is rejected by §5.7 guard 2). The NORMATIVE tie-break is the SMALLEST arg (smallest generator id): equal `expr` values resolve to the lower index, making the buffer byte-identical across bindings (§5.7). REQUIRED on `argmin` / `argmax`; ignored on any other op. An empty candidate set is an error (no index witnesses the optimum).
+     */
+    arg?: string;
+    /**
+     * For the `intersect_polygon` and `polygon_intersection_area` geometry-kernel leaf ops (RFC semiring-faq-unified-ir §8.1 / Appendix B; CONFORMANCE_SPEC.md §5.8.4): the geometry interpretation under which the two operand polygons are clipped, and the part of the op's contract that makes its tolerance-based conformance comparable. "planar": Cartesian/flat clipping (Sutherland–Hodgman / Foster–Hormann) — straight edges in the coordinate plane; wrong at the poles and across the antimeridian, valid only for a small projected patch. "spherical": great-circle edges on the unit sphere (the ConservativeRegridding.jl / GeometryOps.jl / S2 default for lon-lat earth meshes) — the correct model for global regridding. "geodesic": ellipsoidal-geodesic edges. Great-circle-edge assumption: under "spherical"/"geodesic" every edge — including a lon-lat edge running along a parallel, which is a small circle, not a great circle — is modelled as a great-circle geodesic, so a coarse polar cell carries a real area error (~4% for a 30° cell next to the pole, growing with the square of the cell's longitude width; RFC §B.4 / §5.8.4). The per-binding kernels offer an opt-in densification of parallel edges into short great-circle segments (`densify_parallel_edges`) to reduce it; it is off by default, so default clip behaviour is unchanged. REQUIRED on every `intersect_polygon` / `polygon_intersection_area` node (the op carries no default — the manifold must be declared, never inferred). Two bindings' clip results may be compared ONLY under the same declared manifold; the flag itself is matched EXACTLY across bindings (it is a discrete label, not a tolerance-based quantity). Meaningful only for `intersect_polygon` and `polygon_intersection_area`; ignored on any other op. TEMPLATE PARAMETERIZATION (esm-spec §9.6.1 / §9.6.3 constraint 5): inside an `expression_templates` entry's `body`, this field MAY carry a declared template-parameter name — a bare string outside the closed set — as a scalar-field substitution site, so the schema admits any string here. The closed set {planar, spherical, geodesic} is enforced on the EXPANDED form per §9.6.4: bindings MUST reject, at post-expansion validation, any `intersect_polygon` / `polygon_intersection_area` node whose `manifold` is not a member of the closed set.
+     */
+    manifold?: (("planar" | "spherical" | "geodesic") | string) & string;
+    /**
+     * For makearray: list of sub-region boxes of the output array. Each region is an array of [start, stop] pairs, one per output dimension. The nth region is filled with the nth entry of values. Overlapping regions are permitted; later regions overwrite earlier ones. Bound pairs MAY be metaparameter expressions folded to concrete integers at load (esm-spec §9.7.6). Mirrors SymbolicUtils.ArrayMaker.regions.
+     */
+    regions?: [
+        [
+            MetaparameterExpression,
+            MetaparameterExpression
+        ],
+        ...[MetaparameterExpression, MetaparameterExpression][]
+    ][];
+    /**
+     * For makearray: list of expressions, one per entry in regions. Each value may be a scalar expression (broadcast across the region) or an array-valued expression whose shape matches the region (excluding singleton dimensions). Mirrors SymbolicUtils.ArrayMaker.values.
+     */
+    values?: Expression[];
+    /**
+     * For reshape: the target shape. Each entry is either an integer (a concrete length) or a string (a symbolic dimension reference).
+     *
+     * @minItems 1
+     */
+    shape?: [number | string, ...(number | string)[]];
+    /**
+     * For transpose: optional axis permutation. A list of 0-based axis indices giving the new order. If omitted, the matrix-transpose convention is used (reverse axes).
+     */
+    perm?: number[];
+    /**
+     * For concat: the 0-based axis along which to concatenate the operand arrays. All operands must have identical shape on every other axis.
+     */
+    axis?: number;
+    /**
+     * For broadcast: the name of the scalar operator to apply element-wise to the operands in args (esm-spec.md §4.3.4). `{op: 'broadcast', fn: F, args: A}` means exactly what `{op: F, args: A}` means, applied element-wise — so a ONE-operand broadcast applies `fn` UNARILY (`broadcast(fn:'-',[x])` is `-x`), and MUST NOT be treated as the identity on its operand. The value MUST be an ExpressionNode op name drawn from the closed SCALAR subset — the pointwise ops: arithmetic (`+ - * / ^ neg`), elementary functions (`exp log ln log10 sqrt abs sign floor ceil sin cos tan asin acos atan sinh cosh tanh asinh acosh atanh atan2 min max`), comparisons (`== != < <= > >=`), logical connectives (`and or not`), and `ifelse`. It may NOT name a non-pointwise op (`aggregate makearray index broadcast reshape transpose concat fn D ic Pre const true enum table_lookup apply_expression_template skolem rank distinct argmin argmax intersect_polygon polygon_intersection_area`), and `args.length` MUST satisfy the named operator's §4.2 arity. Bindings MUST reject a violation — including an absent `fn`, for which there is no default — with diagnostic 'invalid_broadcast_fn'; loading MUST fail. This is a VALUE constraint the schema deliberately does not enum-enforce, for the same reason `op` and the closed-registry `name` are not enum-enforced: the admissible set is fixed by the file's declared `esm` version, and the check must also cover arity, which a schema `enum` cannot express.
+     */
+    fn?: string;
+    /**
+     * For fn: the dotted module path of a function in the closed function registry (esm-spec.md §9.2). The set of valid names is fixed by the spec version; bindings MUST reject unknown names with diagnostic 'unknown_closed_function'. v0.3.0 set: datetime.year, datetime.month, datetime.day, datetime.hour, datetime.minute, datetime.second, datetime.day_of_year, datetime.julian_day, datetime.is_leap_year, interp.searchsorted, interp.linear, interp.bilinear. For apply_expression_template: the id of an `expression_templates` entry declared in the same component (esm-spec.md §9.6 / docs/rfcs/ast-expression-templates.md). Bindings MUST reject references to undeclared template names at file-load time with diagnostic 'apply_expression_template_unknown_template'.
+     */
+    name?: string;
+    /**
+     * For const: the inline literal value carried by this expression node (any JSON number, integer, or nested array thereof; `args` MUST be empty). For the 'bc' op with kind 'constant'/'dirichlet': the boundary value — a number, a parameter/variable-reference string, or an Expression AST node.
+     */
+    value?: {
+        [k: string]: unknown;
+    };
+    /**
+     * For table_lookup: the id of the function_tables entry to evaluate. Bindings MUST reject references to undeclared tables at file-load time with diagnostic 'table_lookup_unknown_table'.
+     */
+    table?: string;
+    /**
+     * For table_lookup: a map from axis name (matching one of the referenced table's `axes[].name` entries) to the scalar input expression supplying that coordinate at evaluation time. Every axis declared on the table MUST appear as a key; extra keys are rejected with 'table_lookup_axis_name_mismatch'. `args` MUST be empty for a table_lookup node — the per-axis expressions live here.
+     */
+    axes?: {
+        [k: string]: Expression;
+    };
+    /**
+     * For table_lookup: which output of a multi-output table to return. Either a non-negative integer (0-based index into the leading data dimension) or a string (an entry in the table's `outputs` array). Single-output tables MAY omit this field (defaults to 0). Out-of-range or unknown-name selectors are rejected with 'table_lookup_output_out_of_range'.
+     */
+    output?: number | string;
+    /**
+     * For apply_expression_template: a map from each parameter name declared by the referenced template to the Expression bound to that parameter. Every entry of the template's `params` MUST appear as a key; extra keys are rejected at load time with diagnostic 'apply_expression_template_bindings_mismatch'. Values may be numeric literals, variable name references (strings), or arbitrary Expression ASTs (full subtrees). `args` MUST be empty for an apply_expression_template node — the parameter values live here.
+     */
+    bindings?: {
+        [k: string]: Expression;
+    };
+};
+type ExpressionNode1 = {
+    [k: string]: unknown;
+};
+/**
+ * A load-time integer expression over metaparameters (esm-spec §9.7.6): an integer literal, a declared metaparameter name, or `{op: +|-|*|/, args: [...]}` over metaparameter expressions (unary `-` allowed). Folded to a concrete integer at load with exact 64-bit arithmetic; `/` MUST divide exactly and overflow is an error (`metaparameter_type_error`). Admissible in structural integer sites (`index_sets` interval `size`, `aggregate` dense `ranges` tuple entries, `makearray` `regions` bound pairs) AND as an import-edge / subsystem-edge binding VALUE, whose free names resolve in the importing document's metaparameter scope.
+ */
+type MetaparameterExpression = number | string | {
+    op: "+" | "-" | "*" | "/";
+    /**
+     * @minItems 1
+     */
+    args: [MetaparameterExpression, ...MetaparameterExpression[]];
+};
+/**
+ * Trigger specification for a discrete event.
+ */
+type DiscreteEventTrigger = {
+    type: "condition";
+    expression: Expression;
+} | {
+    type: "periodic";
+    /**
+     * Interval in simulation time units.
+     */
+    interval: number;
+    /**
+     * Offset from t=0 for the first firing.
+     */
+    initial_offset?: number;
+} | {
+    type: "preset_times";
+    /**
+     * Array of simulation times at which to fire.
+     *
+     * @minItems 1
+     */
+    times: [number, ...number[]];
+};
+/**
+ * One native axis of a `DataLoaderSelect`. The vocabulary is shared with the projection-pushdown gate template (CONFORMANCE_SPEC §5.5): "all" keeps the axis whole; `fixed` takes one index and DROPS the axis; `range` takes a half-open strided window and keeps it; `gated_by` names a `derived` index set whose value-invention members become the axis, which DEFERS the fetch until those members exist.
+ */
+type DataSourceSelectAxis = "all" | {
+    /**
+     * A single 0-based native index.
+     */
+    fixed: number | [number];
+} | {
+    range: {
+        /**
+         * Inclusive first index (default 0). A string names a `metaparameters` entry and resolves to its default.
+         */
+        start?: number | string;
+        /**
+         * Exclusive last index. A string names a `metaparameters` entry and resolves to its default, so a prefix is declared in the model's own terms (`W[0:N_SRC]`) rather than as a repeated literal that can drift from the index set sized by the same metaparameter.
+         */
+        stop: number | string;
+        /**
+         * Stride (default 1; MUST be >= 1).
+         */
+        step?: number | string;
+    };
+} | {
+    /**
+     * Name of a `kind: "derived"` index set. The axis becomes that set's materialised members in canonical (sorted) member order (CONFORMANCE_SPEC §5.5, Hook 2), so only the rows the model can reach are ever read.
+     */
+    gated_by: string;
+};
+/**
+ * A single scalar check against a model variable at a specific (variable, time) point. PDE-aware variants pin a spatial point via `coords`, or reduce the field to a scalar via `reduce` (domain-integral, mean, max, min, or error-norm). `coords` and `reduce` are mutually exclusive; if neither is given the assertion is pointwise and only valid on a 0-D component. Error-norm reductions (L2_error, Linf_error) require `reference`.
+ */
+type Assertion = Assertion1 & {
+    /**
+     * Name of the variable or species to check. Use the local name (e.g., "O3") or a scoped reference relative to this component (e.g., "subsystem.X").
+     */
+    variable: string;
+    /**
+     * Simulation time at which to evaluate the assertion. Must lie within [time_span.start, time_span.end].
+     */
+    time: number;
+    /**
+     * Expected scalar value of the variable at the given time.
+     */
+    expected?: number;
+    tolerance?: Tolerance2;
+    /**
+     * Spatial-point evaluation: map from a spatial index-set / dimension name (e.g., "x", "lon") to the numeric coordinate at which to sample the field. All keys MUST be names of index sets the field is defined over. Mutually exclusive with `reduce`.
+     */
+    coords?: {
+        [k: string]: number;
+    };
+    /**
+     * Domain reduction: collapse the spatial field to a single scalar before comparison. `integral`/`mean`/`max`/`min` are pure reductions; `L2_error`/`Linf_error` require a `reference` solution and compute ||u_actual - u_reference||_norm. Mutually exclusive with `coords`.
+     */
+    reduce?: "integral" | "mean" | "max" | "min" | "L2_error" | "Linf_error";
+    /**
+     * Reference (analytic or precomputed) solution required by error-norm reductions. Either an inline Expression evaluated over the component's domain coordinates, or a from_file shape pointing at a precomputed snapshot.
+     */
+    reference?: Expression | {
+        type: "from_file";
+        path: string;
+        format?: string;
+    };
+};
+type Assertion1 = {
+    [k: string]: unknown;
+} & {
+    [k: string]: unknown;
+} & {
+    [k: string]: unknown;
+} & {
+    [k: string]: unknown;
+};
+/**
+ * One axis of a parameter sweep: exactly one of values or range must be given.
+ */
+type SweepDimension = {
+    /**
+     * Name of the parameter to vary (local to this component).
+     */
+    parameter: string;
+    /**
+     * Enumerated values to use for this axis.
+     *
+     * @minItems 1
+     */
+    values?: [number, ...number[]];
+    range?: SweepRange;
+} & SweepDimension1;
+type SweepDimension1 = {
+    [k: string]: unknown;
+} | {
+    [k: string]: unknown;
+};
+/**
+ * A plot specification associated with an analysis. Only structural information is recorded — axes, series selection, and value reductions. Styling (colors, fonts, legends, themes) is the viewer's concern. PDE-aware plot types `field_slice` and `field_snapshot` visualize spatial fields at a fixed time; `x` (and `y` for snapshots) name domain dimensions, the variable value becomes the y / color channel, and any non-plotted spatial dimension MUST be pinned in `pinned_coords`.
+ */
+type Plot = Plot1 & {
+    /**
+     * Identifier unique within this analysis's plots array.
+     */
+    id: string;
+    type: "line" | "scatter" | "heatmap" | "field_slice" | "field_snapshot";
+    description?: string;
+    x: PlotAxis;
+    /**
+     * Y-axis specification. May be a single PlotAxis, or an array of PlotAxis for inline multi-series line/scatter plots (alternative to the `series` field for the common case of plotting several variables against a shared x-axis).
+     */
+    y: PlotAxis | [PlotAxis, ...PlotAxis[]];
+    value?: PlotValue;
+    /**
+     * Multiple named series for line or scatter plots. Ignored for heatmap and field plots.
+     */
+    series?: PlotSeries[];
+    /**
+     * Required for field_slice and field_snapshot: simulation time at which to extract the spatial field. Must lie within the analysis's time_span.
+     */
+    at_time?: number;
+    /**
+     * Required for field_slice and field_snapshot when the component domain has more spatial dimensions than the plot's spatial axes (1 for field_slice, 2 for field_snapshot). Maps each non-plotted spatial dimension name to the numeric coordinate at which to slice. Keys MUST be names of dimensions in component.domain.spatial that are not used by `x` (or `y` for field_snapshot).
+     */
+    pinned_coords?: {
+        [k: string]: number;
+    };
+    /**
+     * Optional iso-levels to overlay as contour lines on a field plot (field_slice / field_snapshot / heatmap). Each number is a value of the plotted field at which to draw a contour line — e.g. [0] draws the zero level-set front. Purely a viewer overlay; ignored for line/scatter.
+     */
+    contours?: number[];
+};
+type Plot1 = {
+    [k: string]: unknown;
+} & {
+    [k: string]: unknown;
+} & {
+    [k: string]: unknown;
+};
+/**
+ * A reaction-system parameter — rate constant, temperature, photolysis rate. Carries the same value machinery as a model `parameter`: a fixed `default`, or a `distribution`, with an optional `update` saying when it refreshes.
+ */
+type Parameter = Parameter1 & {
+    units?: string;
+    default?: number;
+    /**
+     * Units of the default value, if different from the declared units field. See ModelVariable.default_units for semantics.
+     */
+    default_units?: string;
+    description?: string;
+    /**
+     * Arrayed-variable shape: ordered list of index-set names drawn from the document-scoped `index_sets` registry. Omitted or null indicates a scalar. REQUIRED for a parameter whose `update` is `schedule`, `data`, or `remesh` — such a parameter is a buffer whose extent is fixed at setup and refilled on a discrete cadence, so its extent must be known ahead of time (RFC semiring-faq-unified-ir §6.1); an empty array is a valid (scalar) shape.
+     */
+    shape?: string[];
+    /**
+     * Draw this parameter's value from a distribution instead of fixing it at `default`. Mutually exclusive with `default`.
+     */
+    distribution?: {
+        [k: string]: unknown;
+    } | {
+        kind: "uniform";
+        low: number | [number, ...number[]];
+        high: number | [number, ...number[]];
+    };
+    /**
+     * When this parameter refreshes and what it refreshes from.
+     */
+    update?: ParameterUpdate$1 | [
+        ParameterUpdate$1 & {
+            [k: string]: unknown;
+        },
+        ParameterUpdate$1 & {
+            [k: string]: unknown;
+        },
+        ...(ParameterUpdate$1 & {
+            [k: string]: unknown;
+        })[]
+    ];
+};
+type Parameter1 = {
+    [k: string]: unknown;
+};
+/**
+ * A single coupling rule connecting models or reaction systems. A `data_sources` entry is not a component and cannot appear as a coupling endpoint; external data enters through a parameter's `update`.
+ */
+type CouplingEntry = CouplingOperatorCompose | CouplingCouple | CouplingVariableMap | CouplingCallback | CouplingEvent | CouplingImport;
+/**
+ * Translation target: a simple variable reference string or an object with var and factor.
+ */
+type TranslateTarget = string | {
+    var: string;
+    factor?: number;
+};
+/**
+ * Replace a parameter in one system with a variable from another.
+ */
+type CouplingVariableMap = CouplingVariableMap1 & {
+    type: "variable_map";
+    /**
+     * Source variable (scoped reference, e.g., "GEOSFP.T").
+     */
+    from: string;
+    /**
+     * Target parameter (scoped reference, e.g., "SuperFast.T").
+     */
+    to: string;
+    /**
+     * How the mapping is applied: one of the named transforms, or an Expression evaluated on the source value(s) in the flattened coupled system's scope (spec §8.6/§10.4/§10.5 — the regridding form; the expression must reference the entry's `from` variable via a fully-scoped reference and may reference any other in-scope variable, e.g. build-once overlap weights in the receiving component; `apply_expression_template` invocations are legal and resolve at load per §9.6.4 — eager references expand, the rest survive and denote their expansion). The Expression form is an operator node: the degenerate bare-reference and literal Expression spellings are not admissible here (the named string transforms already cover bare replacement, and the string space is reserved for them).
+     */
+    transform: ("param_to_var" | "identity" | "additive" | "multiplicative" | "conversion_factor") | ExpressionNode;
+    /**
+     * Scaling coefficient applied by a scaling transform (additive, multiplicative, conversion_factor). Not permitted with param_to_var, identity, or an Expression transform, which replace/assign/compute without a separate scaling slot.
+     */
+    factor?: number;
+    /**
+     * Strategy for mapping between 0D and spatial systems.
+     */
+    lifting?: "pointwise" | "broadcast" | "mean" | "integral";
+    /**
+     * Map from a target system referenced by this coupling entry to the template-library imports registered into THAT component's template scope (esm-spec §9.7.10) — assembler-chosen discretization for a PDE component as it is wired into the assembly. Each key MUST name a model/reaction-system this entry references (template_inject_target_unknown otherwise; the `variable_map` reference fields are `from`/`to`); a key resolving to neither a model nor a reaction system is template_inject_target_not_component -- which from 1.0.0 is also how a key naming a `data_sources` entry is reported, since a data source is not a component and the separate template_inject_target_is_loader code is retired. Values use the §9.7.2 entry shape. Load-time only; consumed by the §9.6.3 fixpoint; does not survive parse→emit.
+     */
+    expression_template_imports?: {
+        [k: string]: TemplateImport[];
+    };
+    description?: string;
+};
+type CouplingVariableMap1 = {
+    [k: string]: unknown;
+};
+/**
+ * Cross-system event involving variables from multiple coupled systems.
+ */
+type CouplingEvent = CouplingEvent1 & {
+    type: "event";
+    /**
+     * Whether this is a continuous or discrete event.
+     */
+    event_type: "continuous" | "discrete";
+    /**
+     * Human-readable identifier.
+     */
+    name?: string;
+    /**
+     * Condition expressions (zero-crossing for continuous, boolean for discrete).
+     */
+    conditions?: Expression[];
+    /**
+     * Trigger specification for a discrete event.
+     */
+    trigger?: {
+        type: "condition";
+        expression: Expression;
+    } | {
+        type: "periodic";
+        /**
+         * Interval in simulation time units.
+         */
+        interval: number;
+        /**
+         * Offset from t=0 for the first firing.
+         */
+        initial_offset?: number;
+    } | {
+        type: "preset_times";
+        /**
+         * Array of simulation times at which to fire.
+         *
+         * @minItems 1
+         */
+        times: [number, ...number[]];
+    };
+    /**
+     * Affect equations. Required unless functional_affect is used.
+     */
+    affects: AffectEquation[];
+    affect_neg?: null | AffectEquation[];
+    root_find?: "left" | "right" | "all";
+    reinitialize?: boolean;
+    /**
+     * Map from a target system referenced by this coupling entry to the template-library imports registered into THAT component's template scope (esm-spec §9.7.10) — assembler-chosen discretization for a PDE component as it is wired into the assembly. Each key MUST name a model/reaction-system this entry references (template_inject_target_unknown otherwise); a key resolving to neither a model nor a reaction system is template_inject_target_not_component -- which from 1.0.0 is also how a key naming a `data_sources` entry is reported, since a data source is not a component and the separate template_inject_target_is_loader code is retired. Values use the §9.7.2 entry shape. Load-time only; consumed by the §9.6.3 fixpoint; does not survive parse→emit.
+     */
+    expression_template_imports?: {
+        [k: string]: TemplateImport[];
+    };
+    description?: string;
+};
+type CouplingEvent1 = {
+    [k: string]: unknown;
+} & {
+    [k: string]: unknown;
+};
+/**
+ * A named index set (RFC semiring-faq-unified-ir §5.2): the declaration shape for an iteration domain referenced from an `aggregate` range via { "from": <name> }. Covers grid axes and categorical dimensions under one shape. Exactly one of four kinds, each requiring its own fields.
+ */
+type IndexSet = IndexSet1 & {
+    /**
+     * Which of the four index-set forms this entry is. "interval": a dense [1..size] grid axis. "categorical": an explicit enumeration of members. "derived": a data-derived set materialized from an index-set-producing node (a `distinct` `aggregate`, or an `intersect_polygon` ring leaf whose clipped ring has a data-dependent vertex count, §8.1). "ragged": a per-parent (dependent) inner set backed by CSR offsets/values factors.
+     */
+    kind: "interval" | "categorical" | "derived" | "ragged";
+    /**
+     * A load-time integer expression over metaparameters (esm-spec §9.7.6): an integer literal, a declared metaparameter name, or `{op: +|-|*|/, args: [...]}` over metaparameter expressions (unary `-` allowed). Folded to a concrete integer at load with exact 64-bit arithmetic; `/` MUST divide exactly and overflow is an error (`metaparameter_type_error`). Admissible in structural integer sites (`index_sets` interval `size`, `aggregate` dense `ranges` tuple entries, `makearray` `regions` bound pairs) AND as an import-edge / subsystem-edge binding VALUE, whose free names resolve in the importing document's metaparameter scope.
+     */
+    size?: number | string | {
+        op: "+" | "-" | "*" | "/";
+        /**
+         * @minItems 1
+         */
+        args: [MetaparameterExpression, ...MetaparameterExpression[]];
+    };
+    /**
+     * categorical: the explicit enumeration of members (e.g. county FIPS codes, fuel types). Required when kind is "categorical".
+     */
+    members?: unknown[];
+    /**
+     * derived: the id of the index-set-producing node (RFC §5.5) that materializes this set, named by its `id`. Usually an `aggregate` node (`distinct: true`) — e.g. the unique edges discovered from a face→vertex relation. It MAY also be an `intersect_polygon` geometry-kernel leaf (RFC §8.1): the clipped overlap ring it returns has a data-dependent number of vertices, so the ring's vertex set is exactly such a derived index set, and `polygon_area` is then an ordinary `sum_product` FAQ over it. Required when kind is "derived".
+     */
+    from_faq?: string;
+    /**
+     * derived: name of the buffer that receives the surviving member key per invented position (CONFORMANCE_SPEC §5.5, Hook 1) — fed back as a `const` factor so an aggregate ranging over the compact derived axis can gather the full-grid rows that axis selects. That is what downstream aggregates do; it is not a claim about ORIENTATION — an aggregate that reduces OVER the compact axis, and one whose overlap-gate envelope factors are themselves such gathers, gather exactly the same way (CONFORMANCE_SPEC §5.5.7). OPTIONAL, and only meaningful when kind is "derived" and `from_faq` names an overlap-gated `distinct` aggregate. Pairs with a provider axis marked `gated_by: "<this set>"`, which is DEFERRED past value-invention and then fetched with a Selection built from the materialised members in sorted order (the `gated_select` pushdown).
+     */
+    member_factor?: string;
+    /**
+     * ragged: the parent index-set name(s) this inner set depends on (e.g. ["cells"] for the edges of each cell). Required when kind is "ragged".
+     */
+    of?: string[];
+    /**
+     * ragged: name of the keyed factor giving |set(i)| for each parent tuple — the per-parent length / CSR offsets (e.g. MPAS nEdgesOnCell). Required when kind is "ragged".
+     */
+    offsets?: string;
+    /**
+     * ragged: name of the keyed factor giving the member at (i, k) for k in 1…|set(i)| — the flattened CSR member array (e.g. edgesOnCell). Required when kind is "ragged".
+     */
+    values?: string;
+};
+type IndexSet1 = {
+    [k: string]: unknown;
+};
+/**
+ * One entry of the document-scoped `coordinates` registry (RFC streaming-output-sinks §8): marks an existing data array (or an inline literal vector) as a physical coordinate and attaches CF metadata. Exactly one of `source` (reference an existing array by name) or `values` (inline literal) MUST be present. The coordinate's shape/dimensions come from its source, so no per-axis attachment is needed; the writer resolves CF role (dimension vs auxiliary) from that shape.
+ */
+type Coordinate = {
+    /**
+     * Name of an existing data array — a model unknown or parameter (including one fed from a `data_sources` entry) — supplying this coordinate's values. Referenced by name exactly as a ragged `IndexSet` references its `offsets`/`values` factors. Mutually exclusive with `values`. The array's declared shape (its ordered index-set dimensions) IS the coordinate's shape: 1-D monotonic over a grid axis → CF dimension coordinate; 1-D over a shared dimension (e.g. `lat(cells)`) or 2-D (`lat(y,x)`) → CF auxiliary coordinate.
+     */
+    source?: string;
+    /**
+     * Inline literal 1-D coordinate vector for the simple rectilinear case, mirroring `FunctionTableAxis.values` (finite floats). Mutually exclusive with `source`. Use `source` for anything not a plain 1-D literal (unstructured/curvilinear coordinates live in data arrays).
+     *
+     * @minItems 1
+     */
+    values?: [number, ...number[]];
+    /**
+     * CF standard name (e.g. "latitude", "longitude", "air_pressure"). Emitted verbatim as the coordinate variable's `standard_name` attribute.
+     */
+    standard_name?: string;
+    /**
+     * CF/UDUNITS units string (e.g. "degrees_north", "degrees_east", "Pa"). Emitted as the coordinate variable's `units` attribute. Advisory at load time (no unit checking), matching `FunctionTableAxis.units`.
+     */
+    units?: string;
+    /**
+     * Optional CF axis role for a rectilinear dimension coordinate. Set it ONLY for a 1-D monotonic dimension coordinate; omit it for auxiliary coordinates (unstructured/curvilinear), which have no single axis. Emitted as the `axis` attribute.
+     */
+    axis?: "X" | "Y" | "Z" | "T";
+} & Coordinate1;
+type Coordinate1 = {
+    [k: string]: unknown;
+};
+interface ESMFormat2 {
+    /**
+     * Format version string (semver).
+     */
+    esm: string;
+    metadata: Metadata;
+    /**
+     * ODE-based model components, keyed by unique identifier. Each component may be defined inline or included by reference to an external ESM file containing exactly one top-level model (esm-spec.md §4.7).
+     */
+    models?: {
+        [k: string]: Model$1 | SubsystemRef;
+    };
+    /**
+     * Reaction network components, keyed by unique identifier. Each component may be defined inline or included by reference to an external ESM file containing exactly one top-level reaction system (esm-spec.md §4.7).
+     */
+    reaction_systems?: {
+        [k: string]: ReactionSystem | SubsystemRef;
+    };
+    /**
+     * Document-scoped registry of external data sources, keyed by name. A data source is INGEST CONFIGURATION, not a component: it says where bytes live and how to decode, slice, and filter them, and it exposes no variables of its own. A model consumes one by declaring a parameter whose `update` names the source and binds a `file_variable` from it. The shared parts stay here because their guarantees are source-wide and cannot be stated per-parameter: `record_filter` computes the surviving-record mask ONCE and applies it to every parameter drawing from this source, which is what makes it impossible for two columns of one points table to fall out of alignment, and `extent` binds ONE metaparameter from that single shared record count.
+     */
+    data_sources?: {
+        [k: string]: DataSource;
+    };
+    /**
+     * File-local symbol-to-positive-integer mappings used by the 'enum' AST op to make categorical lookups cross-binding-portable. Each entry is an enum name; its value is an object mapping symbolic names (strings) to positive integers. Two .esm files may declare an enum of the same name with different mappings; enums are file-local and never merged across files. See esm-spec.md §9.3.
+     */
+    enums?: {
+        [k: string]: EnumDeclaration;
+    };
+    /**
+     * Composition and coupling rules.
+     */
+    coupling?: CouplingEntry[];
+    domain?: Domain;
+    /**
+     * Component-scoped sampled function tables (v0.4.0). Each entry declares ordered named axes plus a literal nested-array data block, optionally tagged with output names; the `table_lookup` AST op references a table by id, supplies a per-axis input-coordinate expression map, and selects which output to return. Tables are syntactic sugar over `interp.linear` / `interp.bilinear` / `index`: a `table_lookup` MUST be bit-equivalent to the equivalent inline-const lookup. See esm-spec.md §9.5 and docs/rfcs/sampled-tables.md.
+     */
+    function_tables?: {
+        [k: string]: FunctionTable;
+    };
+    /**
+     * Document-scoped registry of named index sets (RFC semiring-faq-unified-ir §5.2), keyed by name — the single, document-level declaration site for every iteration domain (grid axes, categorical dimensions, data-derived sets) shared by all models in the document. An `aggregate` range references one by name as { "from": <name> }. Each entry is an interval (dense axis), categorical enumeration, data-derived set, or ragged / dependent inner set. A reference resolves by name to exactly one entry; resolvers MUST error on an undeclared name.
+     */
+    index_sets?: {
+        [k: string]: IndexSet;
+    };
+    /**
+     * Document-scoped, OPTIONAL registry of coordinate variables (RFC streaming-output-sinks §8), keyed by name. Purely additive: a document without it validates and emits exactly as before (bare integer axes). Each entry marks an existing data array — a model unknown or parameter referenced BY NAME (including a parameter fed from a `data_sources` entry) (exactly as a ragged `IndexSet` references its `offsets`/`values` factors), or an inline literal `values` vector — as a physical coordinate and attaches CF metadata (`standard_name`, `units`, optional `axis`). The coordinate's SHAPE is read from its source, so it is NOT attached to any single axis: this is the CF coordinate data model, covering rectilinear (1-D monotonic → CF dimension coordinate), unstructured (1-D over a shared dimension → CF auxiliary coordinate) and curvilinear (2-D `lat(y,x)`/`lon(y,x)` → auxiliary coordinate) grids under one rule. A streaming writer derives each data variable's CF `coordinates` attribute mechanically: every coordinate whose source DIMENSIONS (by identity, NOT by length) are a subset of the data variable's dimensions applies to it.
+     */
+    coordinates?: {
+        [k: string]: Coordinate;
+    };
+    /**
+     * Top-level rewrite rules / templates — the payload of a template-library file (esm-spec §9.7.1). Only valid in a library file (which carries no models/reaction_systems/data_loaders/coupling/domain, `template_import_not_library` when imported otherwise); component-local templates stay inside their model/reaction_system (§9.6.1). Arrives at esm 0.8.0 (`template_import_version_too_old`).
+     */
+    expression_templates?: {
+        [k: string]: ExpressionTemplate;
+    };
+    /**
+     * Ordered imports of template-library files at document top level — only valid in a library file layering on other libraries (esm-spec §9.7.2). Models and reaction systems carry their own `expression_template_imports` field.
+     */
+    expression_template_imports?: TemplateImport[];
+    metaparameters?: Metaparameters;
+    /**
+     * Coupling-library formal component roles (esm-spec §10.9). Present only in a coupling-library file, which pairs it with a role-scoped `coupling` array and declares no models/reaction_systems/data_loaders/domain/index_sets/metaparameters/expression_templates (enforced by the resolver as `coupling_library_illegal_payload`). Presence of this key is the sole positive identifier of the coupling-library file kind. Each entry is a role descriptor carrying an optional human-readable `description`; roles are formal parameters (names, not types), bound to actual components at a `coupling_import` (esm-spec §10.10).
+     */
+    coupling_roles?: {
+        [k: string]: {
+            description?: string;
+        };
+    };
+}
+/**
+ * Authorship, provenance, and description.
+ */
+interface Metadata {
+    /**
+     * Short identifier for the model configuration.
+     */
+    name: string;
+    description?: string;
+    authors?: string[];
+    license?: string;
+    /**
+     * ISO 8601 creation timestamp. The pattern duplicates `format: date-time` because `format` is an annotation, not an assertion, in JSON Schema — validators ignore it unless separately configured, so the pattern is what makes the constraint portable across bindings.
+     */
+    created?: string;
+    /**
+     * ISO 8601 last-modified timestamp.
+     */
+    modified?: string;
+    tags?: string[];
+    references?: Reference[];
+    /**
+     * Diagnostic stamped by discretize(): whether the resolved system is a pure ODE or a DAE (RFC §12).
+     */
+    system_class?: "ode" | "dae";
+    /**
+     * Diagnostic stamped by discretize(): algebraic-equation accounting (RFC §12).
+     */
+    dae_info?: {
+        algebraic_equation_count?: number;
+        per_model?: {
+            [k: string]: number;
+        };
+        [k: string]: unknown;
+    };
+    /**
+     * Diagnostic stamped by discretize(): identifies the source document this was discretized from (RFC §12).
+     */
+    discretized_from?: {
+        /**
+         * The metadata.name of the source document.
+         */
+        name?: string;
+        [k: string]: unknown;
+    };
+    /**
+     * Reserved extension point for downstream-catalog machine-readable metadata (e.g. the EarthSciDiscretizations rule-library catalog). Free-form JSON: the schema validates only that this is an object. The core spec NEVER interprets, validates, or transforms its contents — core tooling MUST NOT assign meaning to them and MUST preserve them across parse → emit like any other metadata field. Downstream catalogs define and version their own conventions inside it (esm-spec §3).
+     */
+    x_esd?: {
+        [k: string]: unknown;
+    };
+}
+/**
+ * Academic citation or data source reference.
+ */
+interface Reference {
+    /**
+     * DOI in the standard `10.<registrant>/<suffix>` form.
+     */
+    doi?: string;
+    citation?: string;
+    /**
+     * Absolute URI. The pattern duplicates `format: uri` because `format` is an annotation, not an assertion, in JSON Schema.
+     */
+    url?: string;
+    notes?: string;
+}
+/**
+ * An ODE system — a fully specified set of time-dependent equations.
+ */
+interface Model$1 {
+    reference?: Reference;
+    /**
+     * All variables, keyed by name.
+     */
+    variables: {
+        [k: string]: ModelVariable$1;
+    };
+    /**
+     * Array of {lhs, rhs} equation objects.
+     */
+    equations: Equation[];
+    /**
+     * Equations that hold only at t=0 (not dynamically). Used by models whose initialization requires solving an auxiliary system before time-stepping begins (e.g. aerosol equilibrium, plume rise). Each entry is a {lhs, rhs} equation evaluated/solved at t=0.
+     */
+    initialization_equations?: Equation[];
+    /**
+     * Initial-guess seeds for nonlinear solvers during initialization, keyed by variable name. Values are Expression graphs (numbers, strings, or ExpressionNode).
+     */
+    guesses?: {
+        [k: string]: Expression;
+    };
+    /**
+     * Discriminates the MTK system type this model maps to. Defaults to 'ode' (time-stepping). 'nonlinear' for algebraic-only systems (no time derivative; e.g. aerosol equilibrium, Mogi). 'sde' when any parameter carries a `wiener` update. 'pde' for models whose equations contain a SPATIAL DERIVATIVE -- a `D` whose `wrt` is present and is not 't', or one of the `grad`/`div`/`laplacian` sugar ops. Note this is a property of the EQUATIONS, not of the `domain` block: v0.8.0 removed `Domain.spatial`, so `domain` carries nothing spatial and the older 'spatial domain plus differential operators' wording named a test no binding could perform. From 1.0.0 this field is a DECLARATION of something the equations and parameter updates already determine: bindings expose a `system_kind` classifier that derives it, use the derivation when this field is absent, and report `system_kind_mismatch` when a present field contradicts it. Derivation order is sde, then pde, then nonlinear, then ode (esm-spec 6.3.1): a steady-state PDE has no time derivative and must not fall through to 'nonlinear', while a model that is both stochastic and spatial assembles as an SDE because there is no SPDESystem constructor.
+     */
+    system_kind?: "ode" | "nonlinear" | "sde" | "pde";
+    discrete_events?: DiscreteEvent[];
+    continuous_events?: ContinuousEvent[];
+    /**
+     * Named child subsystems, keyed by unique identifier. A subsystem is a child model, or a reference to an external file containing exactly one. Enables hierarchical model composition. Variables in subsystems are referenced via dot notation: "ParentModel.ChildModel.var". Each subsystem can be defined inline or included by reference via a local file path or URL. A `data_sources` entry is NOT a component and cannot be a subsystem: a model reaches external data through a parameter whose `update` names the source.
+     */
+    subsystems?: {
+        [k: string]: Model$1 | DataSource | SubsystemRef;
+    };
+    tolerance?: Tolerance;
+    /**
+     * Inline validation tests that exercise this model in isolation. Each test specifies initial conditions, parameter overrides, a time span, and scalar assertions at specific (variable, time) points.
+     */
+    tests?: Test[];
+    /**
+     * Inline illustrative analyses of how to run this model. Each analysis specifies initial state, parameters, a time span, an optional parameter sweep, and plot specifications.
+     */
+    analyses?: Analysis[];
+    /**
+     * Component-scoped in-file Expression-AST templates (v0.4.0; docs/rfcs/ast-expression-templates.md). Each entry names a fixed Expression body with parameter substitution slots; `apply_expression_template` AST nodes elsewhere in this component reference the entry by key with per-parameter bindings. Templates are component-local: declarations here are visible only within this model's expression positions. A body MAY reference other match-less in-scope templates as a statically-checked acyclic DAG — no cycles, no recursion (esm-spec §9.7.3). From esm 0.9.0 the round-trip is Option B (reference-preserving, esm-spec §9.6.4): references survive load and parse-then-emit and denote their expansion (`Expand`); eager (target-bearing) references still expand at load; emit materializes referenced templates into this registry — authored entries first in authored order, then materialized entries in lexicographic UTF-8 name order; keys may be dotted post-rename names. Pre-0.9.0 loaders expanded every reference at load (Option A) and emitted the expanded form.
+     */
+    expression_templates?: {
+        [k: string]: ExpressionTemplate;
+    };
+    /**
+     * Ordered imports of template-library files into this component's template scope (esm-spec §9.7.2). Imported templates join the §9.6.3 effective declaration order ahead of local declarations (§9.7.4).
+     */
+    expression_template_imports?: TemplateImport[];
+}
+/**
+ * An equation: lhs = rhs (or lhs ~ rhs in MTK notation).
+ */
+interface Equation {
+    lhs: Expression;
+    rhs: Expression;
+    _comment?: string;
+}
+/**
+ * Fires when a boolean condition is true at end of a timestep, or at preset/periodic times. Maps to MTK SymbolicDiscreteCallback. An event may affect UNKNOWNS ONLY: from 1.0.0 a parameter carries its own `update` block, so there is no `discrete_parameters` list and no `functional_affect` here — a handler only ever wrote parameters, and now lives on the parameter it writes.
+ */
+interface DiscreteEvent {
+    /**
+     * Human-readable identifier.
+     */
+    name?: string;
+    trigger: DiscreteEventTrigger;
+    /**
+     * Affect equations. Every LHS MUST name an unknown (`event_affects_parameter` otherwise).
+     */
+    affects: AffectEquation[];
+    /**
+     * Whether to reinitialize the system after the event.
+     */
+    reinitialize?: boolean;
+    description?: string;
+}
+/**
+ * An affect equation in an event: lhs is the target variable (string), rhs is an expression.
+ */
+interface AffectEquation {
+    /**
+     * Target variable name (value after the event).
+     */
+    lhs: string;
+    /**
+     * Mathematical expression: a number literal, a variable/parameter reference string, or an operator node.
+     */
+    rhs: Expression;
+}
+/**
+ * Fires when a condition expression crosses zero (root-finding). Maps to MTK SymbolicContinuousCallback. An event may affect UNKNOWNS ONLY; a parameter that changes on a zero crossing declares `update: {kind: "crossing", …}` on itself instead.
+ */
+interface ContinuousEvent {
+    /**
+     * Human-readable identifier.
+     */
+    name?: string;
+    /**
+     * Expressions that trigger the event when they cross zero.
+     *
+     * @minItems 1
+     */
+    conditions: [Expression, ...Expression[]];
+    /**
+     * Affect equations applied on positive-going zero crossings (or both directions if affect_neg is absent). Empty array for pure detection. Every LHS MUST name an unknown (`event_affects_parameter` otherwise).
+     */
+    affects: AffectEquation[];
+    /**
+     * Separate affects for negative-going zero crossings. If null or absent, affects is used for both directions.
+     */
+    affect_neg?: null | AffectEquation[];
+    /**
+     * Root-finding direction.
+     */
+    root_find?: "left" | "right" | "all";
+    /**
+     * Whether to reinitialize the system after the event.
+     */
+    reinitialize?: boolean;
+    description?: string;
+}
+/**
+ * A named external data source reduced to pure I/O: it locates, reads, decodes, slices, and filters bytes on disk. It performs no reprojection and no regridding, and — from 1.0.0 — it exposes no variables and is NOT a component. It cannot be a coupling endpoint, a subsystem, or a scoped-name path root; a model consumes it by declaring a parameter whose `update` names this source and binds one of its `file_variable`s. Grid geometry a source reads (coordinates, connectivity, metric arrays) arrives as ordinary parameters and is transformed downstream by `aggregate` FAQs and coupling expressions. Authentication and algorithm-specific tuning are runtime-only and not part of the schema.
+ */
+interface DataSource {
+    /**
+     * Structural kind of the dataset: 'grid' (gridded array source), 'points' (scattered point/station source), or 'static' (time-invariant source). Grid geometry the source reads — coordinates, connectivity, metric arrays — arrives as ordinary parameters bound to its `file_variable`s and is consumed by `aggregate` FAQs downstream; it needs no special descriptor. Scientific role (emissions, meteorology, elevation, ...) is not schema-validated and belongs in metadata.tags.
+     */
+    kind: "grid" | "points" | "static";
+    source: DataSourceLocation;
+    temporal?: DataSourceTemporal;
+    determinism?: DataSourceDeterminism;
+    /**
+     * Format-specific DECODE options, passed through to the format reader verbatim (EarthSciIO calls them `reader_kwargs`): the zip `member_glob` and `skip_header_row` of an FF10 inventory, a GeoTIFF band naming, and so on. They say how bytes become an array, never what the array means — no remap, no unit conversion, no filtering (those are `variables`, `unit_conversion` and `record_filter`). A key the bound reader does not recognise MUST be an error, so a mis-spelled option cannot silently decode something else.
+     */
+    reader_options?: {
+        [k: string]: unknown;
+    };
+    select?: DataSourceSelect;
+    record_filter?: DataSourceRecordFilter;
+    extent?: DataSourceExtent;
+    reference?: Reference;
+    /**
+     * Free-form metadata about the data source. The "tags" field (array of strings) is conventional for expressing scientific role (e.g. "emissions", "reanalysis") and is not schema-validated.
+     */
+    metadata?: {
+        tags?: string[];
+        [k: string]: unknown;
+    };
+}
+/**
+ * File discovery configuration. Describes how to locate data files at runtime via URL templates with date/variable substitutions.
+ */
+interface DataSourceLocation {
+    /**
+     * Jinja-style URL template with substitutions. Supported: {date:<strftime>} (e.g. {date:%Y%m%d}), {var}, {sector}, {species}. Custom substitutions are allowed and the runtime must accept and pass them through.
+     */
+    url_template: string;
+    /**
+     * Ordered fallback URL templates. Runtime tries each in order, first is primary. Follows the same substitution grammar as url_template.
+     */
+    mirrors?: string[];
+}
+/**
+ * Temporal coverage and record layout for a data source.
+ */
+interface DataSourceTemporal {
+    /**
+     * ISO 8601 datetime — first timestamp available from this source.
+     */
+    start?: string;
+    /**
+     * ISO 8601 datetime — last timestamp available from this source.
+     */
+    end?: string;
+    /**
+     * ISO 8601 duration describing how much time one file covers (e.g., "P1D", "P1M", "PT3H").
+     */
+    file_period?: string;
+    /**
+     * ISO 8601 duration describing spacing between samples within a file.
+     */
+    frequency?: string;
+    /**
+     * Number of time records per file. "auto" means read from file at runtime.
+     */
+    records_per_file?: number | "auto";
+    /**
+     * Name of the time coordinate variable in the file. Used when records_per_file is absent or "auto". If both static declarations (records_per_file + frequency) and time_variable are present, the static declaration wins and time_variable is a fallback.
+     */
+    time_variable?: string;
+    /**
+     * How many time records the source returns per query time — pure I/O; the source does NOT interpolate. Absent or 1 (default): the single at-or-before record, time axis dropped (piecewise-constant between ticks). 2: the two records bracketing the current time (floor + successor), returned with the time axis kept at length 2 so a downstream model can interpolate in time (e.g. linearly). Only 1 and 2 are supported; higher-order temporal stencils are future work. Contrast records_per_file (records IN one file).
+     */
+    records_per_sample?: 1 | 2;
+}
+/**
+ * Reproducibility contract a binary-format loader advertises to bindings. A binding that cannot honor the declared endian / float_format / integer_width MUST reject the file at load rather than silently reinterpreting bytes.
+ */
+interface DataSourceDeterminism {
+    /**
+     * Byte order of on-wire numeric fields.
+     */
+    endian?: "little" | "big";
+    /**
+     * Floating-point format of metric fields.
+     */
+    float_format?: "ieee754_single" | "ieee754_double";
+    /**
+     * Integer width (in bits) of connectivity fields.
+     */
+    integer_width?: 32 | 64;
+}
+/**
+ * A per-axis selection of what the source DELIVERS from an on-disk array — one entry per NATIVE array dimension, in native dims order. Declared on a source (the default for every parameter drawing from it) or on a single parameter's `from` binding (which overrides the source's). Two parameters of one source MAY read the same `file_variable` under different selections, which is how a full-grid field and a prefix of it are both declared instead of one being sliced by the caller. The selection is defined over the axis the loader DELIVERS, so it follows any `record_filter`: `range 0..200` on a filtered points table is the first 200 SURVIVING records. Whether a binding pushes it down to the reader (fetching only what it keeps) or applies it after the read is an optimization; the two MUST agree exactly.
+ */
+interface DataSourceSelect {
+    /**
+     * One selector per native array dimension, in native dims order.
+     *
+     * @minItems 1
+     */
+    axes: [DataSourceSelectAxis, ...DataSourceSelectAxis[]];
+}
+/**
+ * Which records of a `points` source are DELIVERED. The surviving mask is computed ONCE for the source and applied to every parameter drawing from it, so its columns can never fall out of alignment, and the surviving count is the source's `extent`. A record is dropped when any `require_finite` variable is non-finite at it, or when a `codes` map with `unmapped: "drop"` does not recognise its value.
+ */
+interface DataSourceRecordFilter {
+    /**
+     * `file_variable` names whose value must be finite for a record to survive. (Pre-1.0.0 this named loader variable names; a source has no variables of its own now, so it names the file's.) A point with no coordinate cannot be placed and a row with no annual total cannot be weighted; dropping it is a declaration about the source, rather than a NaN travelling into the model to surface as an empty result later.
+     *
+     * @minItems 1
+     */
+    require_finite?: [string, ...string[]];
+}
+/**
+ * Binds the source's DELIVERED record count to a metaparameter, for a source whose extent is not knowable until it is read. A binding samples such a source BEFORE it closes metaparameters (esm-spec §9.7.6 site 4), so an index set declared `size: "N_REC"` is sized by the data itself and no caller counts rows and passes the number in. Every parameter drawing from the source MUST agree on the count — that agreement is also the alignment check.
+ */
+interface DataSourceExtent {
+    /**
+     * Name of the `metaparameters` entry it binds. Declare that entry with a `default` (conventionally 0) so the document still validates and loads standalone.
+     */
+    metaparameter: string;
+}
+/**
+ * A reference to an external ESM file containing a model or reaction system definition. The ref field can be a relative or absolute local file path, or an HTTP/HTTPS URL. Relative paths are resolved relative to the directory of the referencing file.
+ */
+interface SubsystemRef {
+    /**
+     * Local file path or URL pointing to an ESM file. The referenced file must contain exactly one top-level model or reaction system (unless `model` / `reaction_system` selects one of several), which is used as the subsystem definition (esm-spec.md §4.7).
+     */
+    ref: string;
+    /**
+     * Optional model selector. When the referenced file defines more than one top-level model, names which one to splice in. Omit for single-model files. Lets a multi-model component library (e.g. an ESD regridder file holding several kernels) be referenced by one of its models.
+     */
+    model?: string;
+    /**
+     * Optional reaction-system selector. When the referenced file defines more than one top-level reaction system, names which one to splice in. Omit for single-reaction-system files. The reaction-system analogue of `model`, used when a top-level `reaction_systems` entry is a `{ref}` stub (esm-spec.md §4.7).
+     */
+    reaction_system?: string;
+    /**
+     * Bindings closing the referenced document's metaparameters (esm-spec §9.7.6 site 3). Each value is a metaparameter expression over the MOUNTING document's metaparameters (an integer literal, or e.g. `NX*NY`), folded to a concrete integer at the mount.
+     */
+    bindings?: {
+        [k: string]: MetaparameterExpression;
+    };
+    /**
+     * Template-library imports registered into the REFERENCED component's template scope (esm-spec §9.7.10) — assembler-chosen discretization for a mounted PDE component, without editing the leaf file. Same entry shape as §9.7.2; target implicit (this edge mounts one component). Load-time only; consumed by the §9.6.3 fixpoint; does not survive parse→emit.
+     */
+    expression_template_imports?: TemplateImport[];
+}
+/**
+ * One entry of `expression_template_imports` (esm-spec §9.7.2): imports the templates (and index_sets / open metaparameters) of a template-library file. `ref` uses the §4.7 reference formats (relative path, absolute path, or URL), resolved at load before validation with canonical-path cycle detection (`template_import_cycle`). `only` filters which template names become visible to the importer (`template_import_unknown_name` for unknown names). `bindings` closes the target document's open metaparameters to integers at this edge (esm-spec §9.7.6); metaparameters left unbound are re-exported into the importing document's scope. `prefix` / `rename` namespace the surviving exported names (templates after `only`, index sets, still-open metaparameters) into the importer's vocabulary, applied transitively through every occurrence inside the imported declarations; `rebind` rewrites free variable names (keyed factors and other free names in template bodies) at the same point (esm-spec §9.7.7). Renaming happens after this edge's `bindings` instantiation and `only` filtering and before the §9.7.4/§9.7.5 merge, so the same file imported under different renames registers as distinct instances while identical edges dedupe. Identifier grammar, unknown-name, and collision checks are resolver-level (`template_import_rename_invalid`, `template_import_rename_unknown_name`, `template_import_rebind_unknown_name`, `template_import_rename_collision`).
+ */
+interface TemplateImport {
+    /**
+     * Path or URL of a template-library file, per the §4.7 reference-format table.
+     */
+    ref: string;
+    /**
+     * Template names to import; absent = all.
+     *
+     * @minItems 1
+     */
+    only?: [string, ...string[]];
+    /**
+     * Bindings closing the target document's metaparameters at this edge (esm-spec §9.7.6 site 1). Each value is a metaparameter expression over the importing document's metaparameters; a value with still-open names is carried symbolically and folds at the importer's close.
+     */
+    bindings?: {
+        [k: string]: MetaparameterExpression;
+    };
+    /**
+     * Namespace prefix: every surviving exported name without an explicit `rename` entry is renamed to `<prefix>.<name>` (esm-spec §9.7.7). Grammar (resolver-enforced): dotted identifier segments [A-Za-z_][A-Za-z0-9_]*.
+     */
+    prefix?: string;
+    /**
+     * Explicit renames, exported name → importer-visible name; entries override `prefix`. Keys must name a surviving export (`template_import_rename_unknown_name`); targets are dotted identifiers (esm-spec §9.7.7).
+     */
+    rename?: {
+        [k: string]: string;
+    };
+    /**
+     * Free-name rebinding, free name → replacement variable name (e.g. areaCell → meshA.areaCell): rewrites free variable names occurring in the imported template bodies/matches and ragged index-set offsets/values factors. Keys must occur free in the surviving declarations (`template_import_rebind_unknown_name`) (esm-spec §9.7.7).
+     */
+    rebind?: {
+        [k: string]: string;
+    };
+}
+/**
+ * Model-level default numerical tolerance for tests, used when a test or assertion does not provide its own.
+ */
+interface Tolerance {
+    /**
+     * Absolute tolerance: |actual - expected| <= abs.
+     */
+    abs?: number;
+    /**
+     * Relative tolerance: |actual - expected| / max(|expected|, epsilon) <= rel.
+     */
+    rel?: number;
+}
+/**
+ * An inline validation test for the enclosing model or reaction system. Defines the run configuration (initial conditions, parameter overrides, time span) and the scalar assertions that must hold.
+ */
+interface Test {
+    /**
+     * Identifier unique within this component's tests array.
+     */
+    id: string;
+    /**
+     * Human-readable description of what this test verifies.
+     */
+    description?: string;
+    /**
+     * Initial-value overrides for unknowns, keyed by variable name (local to this component). Values not listed fall back to the variable's declared default.
+     */
+    initial_conditions?: {
+        [k: string]: number;
+    };
+    /**
+     * Parameter overrides, keyed by parameter name (local to this component). Values not listed fall back to the parameter's declared default.
+     */
+    parameter_overrides?: {
+        [k: string]: number;
+    };
+    time_span: TimeSpan;
+    tolerance?: Tolerance1;
+    /**
+     * Template-library imports registered into the ENCLOSING component's template scope for THIS run only (esm-spec §9.7.10 / §6.6) — lets a discretization-agnostic PDE component's inline tests run under a per-test discretization chosen without editing the leaf. Same entry shape as §9.7.2; target implicit (the enclosing component). Execution-time (ephemeral per-run build); authored per-run configuration, so it DOES survive parse→emit (peer of parameter_overrides / tolerance).
+     */
+    expression_template_imports?: TemplateImport[];
+    /**
+     * Scalar (variable, time) checks that define the pass/fail criterion of the test.
+     *
+     * @minItems 1
+     */
+    assertions: [Assertion, ...Assertion1[]];
+}
+/**
+ * Simulation time interval expressed in the component's time units.
+ */
+interface TimeSpan {
+    start: number;
+    end: number;
+}
+/**
+ * Test-level default tolerance applied to all assertions in this test that do not override it.
+ */
+interface Tolerance1 {
+    /**
+     * Absolute tolerance: |actual - expected| <= abs.
+     */
+    abs?: number;
+    /**
+     * Relative tolerance: |actual - expected| / max(|expected|, epsilon) <= rel.
+     */
+    rel?: number;
+}
+/**
+ * Per-assertion tolerance override. If present, this takes precedence over the test-level and model-level defaults.
+ */
+interface Tolerance2 {
+    /**
+     * Absolute tolerance: |actual - expected| <= abs.
+     */
+    abs?: number;
+    /**
+     * Relative tolerance: |actual - expected| / max(|expected|, epsilon) <= rel.
+     */
+    rel?: number;
+}
+/**
+ * An inline illustrative analysis of how to run the enclosing component. Defines the run configuration and one or more plots derived from the result.
+ */
+interface Analysis {
+    /**
+     * Identifier unique within this component's analyses array.
+     */
+    id: string;
+    /**
+     * Human-readable description of what this analysis illustrates.
+     */
+    description?: string;
+    /**
+     * Initial state for this analysis run. Either (legacy) a flat map of scalar overrides keyed by state-variable name, or the esm-spec §11.4 discriminated union: {type:"per_variable", values:{name:number}} for scalar ICs, or {type:"expression", values:{name:<expression>}} for closed-form spatial FIELD initial conditions (per-cell coordinate expressions). Field ICs may also be declared with `ic` equations in the model.
+     */
+    initial_state?: {
+        [k: string]: number;
+    } | {
+        type: "per_variable" | "expression";
+        /**
+         * For type=per_variable each value is a scalar number; for type=expression each value is an expression AST (a closed-form per-cell field over the state's index sets).
+         */
+        values: {
+            [k: string]: unknown;
+        };
+    };
+    /**
+     * Parameter overrides, keyed by parameter name (local to this component).
+     */
+    parameters?: {
+        [k: string]: number;
+    };
+    time_span: TimeSpan;
+    parameter_sweep?: ParameterSweep;
+    /**
+     * Plot specifications derived from this analysis's run(s).
+     */
+    plots?: Plot[];
+    /**
+     * Template-library imports registered into the ENCLOSING component's template scope for THIS run only (esm-spec §9.7.10 / §6.7) — lets a discretization-agnostic PDE component's inline analyses run under a per-run discretization chosen without editing the leaf. Same entry shape as §9.7.2; target implicit (the enclosing component). Execution-time (ephemeral per-run build); authored per-run configuration, so it DOES survive parse→emit (peer of parameters / parameter_sweep).
+     */
+    expression_template_imports?: TemplateImport[];
+}
+/**
+ * Optional parameter sweep. When present, the analysis represents a family of runs (one per Cartesian combination) rather than a single trajectory.
+ */
+interface ParameterSweep {
+    /**
+     * Sweep combination strategy. Currently only cartesian (full Cartesian product) is supported.
+     */
+    type: "cartesian";
+    /**
+     * @minItems 1
+     */
+    dimensions: [SweepDimension, ...SweepDimension1[]];
+}
+/**
+ * Generated range; mutually exclusive with values.
+ */
+interface SweepRange {
+    start: number;
+    stop: number;
+    count: number;
+    /**
+     * Spacing: linear = evenly spaced between start and stop; log = logarithmically spaced (start and stop must be strictly positive).
+     */
+    scale?: "linear" | "log";
+}
+/**
+ * Axis specification: any unknown, parameter name, or swept parameter may be used.
+ */
+interface PlotAxis {
+    /**
+     * Variable or parameter name (local to this component or scoped within a subsystem).
+     */
+    variable: string;
+    /**
+     * Human-readable axis label. Viewers should fall back to the variable name if omitted.
+     */
+    label?: string;
+}
+/**
+ * Required for heatmap; defines the color channel. Ignored for line/scatter. For field_snapshot, the variable plotted as the color channel (use `value.variable`); `at_time` and `reduce` are ignored — the field is sampled at `at_time` declared on the plot.
+ */
+interface PlotValue {
+    /**
+     * Variable whose trajectory is reduced to a scalar per run.
+     */
+    variable: string;
+    /**
+     * Specific simulation time at which to sample the variable.
+     */
+    at_time?: number;
+    /**
+     * Time-reduction applied to the trajectory: max/min/mean over the run, time integral, or the final value at time_span.end.
+     */
+    reduce?: "max" | "min" | "mean" | "integral" | "final";
+}
+/**
+ * A single named series for multi-series line or scatter plots.
+ */
+interface PlotSeries {
+    name: string;
+    variable: string;
+}
+/**
+ * A single in-file rewrite rule / Expression-AST template (esm-spec §9.6 / docs/rfcs/ast-expression-templates.md). The `params` are metavariables; the `body` is the replacement Expression AST in which parameter occurrences are written as bare parameter-name strings. The template is applied in one of two ways. (1) WITHOUT `match`: it is invoked explicitly by name through an `apply_expression_template` node, whose `bindings` supply each parameter's AST. (2) WITH `match`: it is an auto-applied rewrite rule — `match` is a pattern Expression in which parameters are wildcards (a parameter in an operand/`args` position binds to the matched sub-AST; a parameter in a scalar field such as `dim`/`side` binds to the matched literal), and the rule fires wherever the pattern structurally matches a node. This unifies variable substitution (a bare-metavar `match`), named-template expansion (no `match`), and rewrite-target-op lowering (an operator `match` like `{op:'D', args:['f'], wrt:'x'}` → an `aggregate`/`makearray` stencil). Either way the `body` is instantiated by pure structural substitution of the bound metavariables — no evaluation, no metaprogramming. Rewriting is an outermost-first, priority-ordered, bounded-fixpoint load-time process (esm-spec §9.6.3): each pass is a pre-order walk that fires, at each node, the matching rule of highest `priority` (ties broken by declaration order); passes repeat to a fixpoint or until MAX_REWRITE_PASSES=64, at which point a non-converging rule set is rejected with diagnostic 'rewrite_rule_nonterminating'. A rewrite-target op (esm-spec §4.2) surviving the fixpoint into an evaluation position is rejected with diagnostic 'unlowered_operator'. A `body` MAY contain `apply_expression_template` nodes referencing other match-less in-scope templates (declared locally or imported, esm-spec §9.7.2); these are checked at registration time as a statically-checked acyclic DAG (cycles rejected with 'apply_expression_template_recursive_body'; chains deeper than MAX_TEMPLATE_EXPANSION_DEPTH=32 rejected with 'template_body_expansion_too_deep'); from esm 0.9.0 they are preserved uninlined and denote their expansion (Option B, esm-spec §9.6.4; pre-0.9.0 loaders inlined them here by pure substitution). `match` patterns MUST NOT contain `apply_expression_template` nodes. An optional `where` block adds static match-scoping constraints on the captured parameters (declared-shape/index-set scoping, filtered before priority selection — see the `where` property and esm-spec §9.6.1).
+ */
+interface ExpressionTemplate {
+    /**
+     * Ordered list of parameter (metavariable) names. MUST be unique within this template; MAY be empty (a zero-parameter template is a named constant fragment, common in library files). Each name occurs zero or more times inside `body` and (when present) `match`; for an explicitly-invoked template every name MUST also appear as a key in every `apply_expression_template.bindings` referencing it.
+     *
+     * @minItems 0
+     */
+    params: string[];
+    /**
+     * Mathematical expression: a number literal, a variable/parameter reference string, or an operator node.
+     */
+    match?: Expression;
+    /**
+     * Optional static match-scoping constraints for an auto-applied (`match`) rule (esm-spec §9.6.1; docs/rfcs/match-pattern-scoping-constraints.md). Keys are declared `params`; each value is a constraint object — the v1 vocabulary is exactly one kind, `shape`: an ordered list of index-set names as spelled in the CONSUMING document's merged index_sets registry (esm-spec §9.7.5, composing with import-edge index-set renaming). After the pattern structurally matches, the rule is eligible only if every constrained parameter bound to a BARE variable reference whose declaration in the enclosing component carries exactly that `shape` (same names, same order); a compound sub-AST, literal, scoped reference, undeclared name, or scalar fails the constraint. Evaluation is fully static — declared shapes at lowering time, never runtime values — and is part of match ELIGIBILITY: it filters BEFORE the §9.6.3 priority/declaration-order selection, so a constraint-excluded rule is simply a non-matching rule at that node. A constraint naming an index set absent from the consuming document's registry is rejected at rule registration with 'template_constraint_unknown_index_set'; a constrained rule that never fires is NOT an error (an un-lowered rewrite-target op is caught by the ordinary 'unlowered_operator' gate). Admissible only alongside `match` (else 'apply_expression_template_invalid_declaration').
+     */
+    where?: {
+        [k: string]: {
+            /**
+             * @minItems 1
+             */
+            shape: [string, ...string[]];
+        };
+    };
+    /**
+     * Selection precedence for an auto-applied (`match`) rule (esm-spec §9.6.3). When more than one rule matches a node, the highest `priority` wins; ties break by declaration order. This lets a compound-term rule (Godunov / WENO / flux-limited) out-rank the plain per-derivative rule so it fires on the whole compound before the inner derivatives are lowered. Ignored when `match` is absent. Absent ⇒ 0.
+     */
+    priority?: number;
+    /**
+     * Mathematical expression: a number literal, a variable/parameter reference string, or an operator node.
+     */
+    body: Expression;
+    description?: string;
+}
+/**
+ * A reaction network — declarative representation of chemical or biological reactions.
+ */
+interface ReactionSystem {
+    reference?: Reference;
+    /**
+     * Named reactive species.
+     */
+    species: {
+        [k: string]: Species;
+    };
+    /**
+     * Named parameters (rate constants, temperature, photolysis rates, etc.).
+     */
+    parameters: {
+        [k: string]: Parameter;
+    };
+    /**
+     * Array of reaction definitions.
+     *
+     * @minItems 1
+     */
+    reactions: [Reaction, ...Reaction[]];
+    /**
+     * Additional algebraic or ODE constraints.
+     */
+    constraint_equations?: Equation[];
+    discrete_events?: DiscreteEvent[];
+    continuous_events?: ContinuousEvent[];
+    /**
+     * Named child reaction systems (subsystems), keyed by unique identifier. Enables hierarchical system composition. Variables in subsystems are referenced via dot notation: "ParentSystem.ChildSystem.species". Each subsystem can be defined inline or included by reference via a local file path or URL.
+     */
+    subsystems?: {
+        [k: string]: ReactionSystem | SubsystemRef;
+    };
+    tolerance?: Tolerance3;
+    /**
+     * Inline validation tests that exercise this reaction system in isolation. Each test specifies initial conditions, parameter overrides, a time span, and scalar assertions at specific (species/variable, time) points.
+     */
+    tests?: Test[];
+    /**
+     * Inline illustrative analyses of how to run this reaction system. Each analysis specifies initial state, parameters, a time span, an optional parameter sweep, and plot specifications.
+     */
+    analyses?: Analysis[];
+    /**
+     * Component-scoped in-file Expression-AST templates (v0.4.0; docs/rfcs/ast-expression-templates.md). Each entry names a fixed Expression body with parameter substitution slots; `apply_expression_template` AST nodes elsewhere in this component (typically inside `reactions[*].rate`) reference the entry by key with per-parameter bindings. Templates are component-local: declarations here are visible only within this reaction system's expression positions. A body MAY reference other match-less in-scope templates as a statically-checked acyclic DAG — no cycles, no recursion (esm-spec §9.7.3). From esm 0.9.0 the round-trip is Option B (reference-preserving, esm-spec §9.6.4): references survive load and parse-then-emit and denote their expansion (`Expand`); eager (target-bearing) references still expand at load; emit materializes referenced templates into this registry — authored entries first in authored order, then materialized entries in lexicographic UTF-8 name order; keys may be dotted post-rename names. Pre-0.9.0 loaders expanded every reference at load (Option A) and emitted the expanded form.
+     */
+    expression_templates?: {
+        [k: string]: ExpressionTemplate;
+    };
+    /**
+     * Ordered imports of template-library files into this component's template scope (esm-spec §9.7.2). Imported templates join the §9.6.3 effective declaration order ahead of local declarations (§9.7.4).
+     */
+    expression_template_imports?: TemplateImport[];
+}
+/**
+ * A reactive species in a reaction system.
+ */
+interface Species {
+    units?: string;
+    default?: number;
+    /**
+     * Units of the default value, if different from the declared units field. See ModelVariable.default_units for semantics.
+     */
+    default_units?: string;
+    description?: string;
+    /**
+     * When true, the species participates in reactions as a reactant/product but its concentration is held fixed (no ODE integration) — a reservoir species. Maps to Catalyst's @species [isconstantspecies=true]. Absent or false means an ordinary state species with an ODE.
+     */
+    constant?: boolean;
+}
+/**
+ * A single reaction in a reaction system.
+ */
+interface Reaction {
+    /**
+     * Unique reaction identifier (e.g., "R1").
+     */
+    id: string;
+    name?: string;
+    /**
+     * Array of {species, stoichiometry} or null for source reactions (∅ → X).
+     */
+    substrates: null | [StoichiometryEntry, ...StoichiometryEntry[]];
+    /**
+     * Array of {species, stoichiometry} or null for sink reactions (X → ∅).
+     */
+    products: null | [StoichiometryEntry, ...StoichiometryEntry[]];
+    /**
+     * Mathematical expression: a number literal, a variable/parameter reference string, or an operator node.
+     */
+    rate: Expression;
+    reference?: Reference;
+}
+/**
+ * A species with its stoichiometric coefficient in a reaction. Coefficients MUST be positive and finite (NaN / ±Infinity are rejected at parse time). Fractional values are supported to preserve fidelity with atmospheric-chemistry mechanisms whose products include non-integer yields (e.g. `0.87 CH2O`, `1.86 CH3O2`). Integer values remain valid — they are a subset of the permitted number range.
+ */
+interface StoichiometryEntry {
+    species: string;
+    stoichiometry: number;
+}
+/**
+ * System-level default numerical tolerance for tests, used when a test or assertion does not provide its own.
+ */
+interface Tolerance3 {
+    /**
+     * Absolute tolerance: |actual - expected| <= abs.
+     */
+    abs?: number;
+    /**
+     * Relative tolerance: |actual - expected| / max(|expected|, epsilon) <= rel.
+     */
+    rel?: number;
+}
+/**
+ * A file-local enum mapping symbolic names to positive integers (esm-spec.md §9.3). Within a single enum, integer values MUST be unique. Across enums, values MAY collide (each enum is its own namespace). Bindings resolve enum-op nodes at load time before evaluating expressions.
+ */
+interface EnumDeclaration {
+    [k: string]: number;
+}
+/**
+ * Match LHS time derivatives and add RHS terms together.
+ */
+interface CouplingOperatorCompose {
+    type: "operator_compose";
+    /**
+     * The two systems to compose.
+     *
+     * @minItems 2
+     * @maxItems 2
+     */
+    systems: [string, string];
+    /**
+     * Variable mappings when LHS variables don't have matching names.
+     */
+    translate?: {
+        [k: string]: TranslateTarget;
+    };
+    /**
+     * Strategy for mapping between 0D and spatial systems.
+     */
+    lifting?: "pointwise" | "broadcast" | "mean" | "integral";
+    /**
+     * Map from a target system referenced by this coupling entry to the template-library imports registered into THAT component's template scope (esm-spec §9.7.10) — assembler-chosen discretization for a PDE component as it is wired into the assembly. Each key MUST name a model/reaction-system this entry references (template_inject_target_unknown otherwise); a key resolving to neither a model nor a reaction system is template_inject_target_not_component -- which from 1.0.0 is also how a key naming a `data_sources` entry is reported, since a data source is not a component and the separate template_inject_target_is_loader code is retired. Values use the §9.7.2 entry shape. Load-time only; consumed by the §9.6.3 fixpoint; does not survive parse→emit.
+     */
+    expression_template_imports?: {
+        [k: string]: TemplateImport[];
+    };
+    description?: string;
+}
+/**
+ * Bi-directional coupling via explicit ConnectorSystem equations.
+ */
+interface CouplingCouple {
+    type: "couple";
+    /**
+     * @minItems 2
+     * @maxItems 2
+     */
+    systems: [string, string];
+    connector: {
+        /**
+         * @minItems 1
+         */
+        equations: [ConnectorEquation, ...ConnectorEquation[]];
+    };
+    /**
+     * Strategy for mapping between 0D and spatial systems.
+     */
+    lifting?: "pointwise" | "broadcast" | "mean" | "integral";
+    /**
+     * Map from a target system referenced by this coupling entry to the template-library imports registered into THAT component's template scope (esm-spec §9.7.10) — assembler-chosen discretization for a PDE component as it is wired into the assembly. Each key MUST name a model/reaction-system this entry references (template_inject_target_unknown otherwise); a key resolving to neither a model nor a reaction system is template_inject_target_not_component -- which from 1.0.0 is also how a key naming a `data_sources` entry is reported, since a data source is not a component and the separate template_inject_target_is_loader code is retired. Values use the §9.7.2 entry shape. Load-time only; consumed by the §9.6.3 fixpoint; does not survive parse→emit.
+     */
+    expression_template_imports?: {
+        [k: string]: TemplateImport[];
+    };
+    description?: string;
+}
+/**
+ * A single equation in a ConnectorSystem linking two coupled systems.
+ */
+interface ConnectorEquation {
+    /**
+     * Source variable (scoped reference).
+     */
+    from: string;
+    /**
+     * Target variable (scoped reference).
+     */
+    to: string;
+    /**
+     * How the expression modifies the target.
+     */
+    transform: "additive" | "multiplicative" | "replacement";
+    /**
+     * Mathematical expression: a number literal, a variable/parameter reference string, or an operator node.
+     */
+    expression?: Expression;
+}
+/**
+ * Register a callback for simulation events.
+ */
+interface CouplingCallback {
+    type: "callback";
+    /**
+     * Registered identifier for the callback.
+     */
+    callback_id: string;
+    config?: {
+        [k: string]: unknown;
+    };
+    /**
+     * Map from a target system referenced by this coupling entry to the template-library imports registered into THAT component's template scope (esm-spec §9.7.10) — assembler-chosen discretization for a PDE component as it is wired into the assembly. Each key MUST name a model/reaction-system this entry references (template_inject_target_unknown otherwise); a key resolving to neither a model nor a reaction system is template_inject_target_not_component -- which from 1.0.0 is also how a key naming a `data_sources` entry is reported, since a data source is not a component and the separate template_inject_target_is_loader code is retired. Values use the §9.7.2 entry shape. Load-time only; consumed by the §9.6.3 fixpoint; does not survive parse→emit.
+     */
+    expression_template_imports?: {
+        [k: string]: TemplateImport[];
+    };
+    description?: string;
+}
+/**
+ * Reuse of a coupling-library file (esm-spec §10.9, §10.10): imports the library named by `ref` and binds each of its declared roles to a component in the assembly. Expands at flatten into concrete variable_map/couple/operator_compose/event edges by substituting bound actuals for role names; the entry itself round-trips intact. Carries no `expression_template_imports` (injection is a property of the wiring entries, not of an import indirection).
+ */
+interface CouplingImport {
+    type: "coupling_import";
+    /**
+     * §4.7 reference (relative path, absolute path, URL, or ${VAR}) to a coupling-library file (a document with top-level `coupling_roles`).
+     */
+    ref: string;
+    /**
+     * Total map from every library role name to a scoped component reference in the assembly (esm-spec §10.10.1). Each value names a top-level or nested models/reaction_systems component (a system node), not a variable. No role may be omitted; there is no auto-binding.
+     */
+    bind?: {
+        [k: string]: string;
+    };
+    description?: string;
+}
+/**
+ * The single temporal domain shared by every component in the document (temporal extent + numeric representation). A document has at most one domain; all spatial models live on it, and 0-D models simply have scalar-shaped variables.
+ */
+interface Domain {
+    /**
+     * Name of the independent (time) variable.
+     */
+    independent_variable?: string;
+    temporal?: {
+        start?: string;
+        end?: string;
+        reference_time?: string;
+    };
+    /**
+     * Floating point precision.
+     */
+    element_type?: "Float32" | "Float64";
+    /**
+     * Array backend (e.g., "Array", "CuArray").
+     */
+    array_type?: string;
+}
+/**
+ * A sampled function table (esm-spec.md §9.5). Carries one or more named axes and a literal nested-array data block. The shape of `data` is [len(outputs), len(axes[0].values), len(axes[1].values), ...] when `outputs` is declared; otherwise [len(axes[0].values), ...] (single-output convenience form). `table_lookup` AST nodes evaluate this table by supplying a per-axis input expression and selecting an output. Tables are syntactic sugar over `interp.linear` (1 axis) / `interp.bilinear` (2 axes) / `index` (nearest); the materialized AST a binding produces from a `table_lookup` MUST be bit-equivalent to the equivalent inline-const lookup.
+ */
+interface FunctionTable {
+    description?: string;
+    /**
+     * Ordered list of named axes. The order of entries defines the order of inner dimensions in `data` (after the leading output dimension when `outputs` is present). Axis names within a single table MUST be unique.
+     *
+     * @minItems 1
+     * @maxItems 2
+     */
+    axes: [FunctionTableAxis] | [FunctionTableAxis, FunctionTableAxis];
+    /**
+     * Interpolation kind applied by `table_lookup`. 'linear' (1 axis) lowers to `interp.linear`. 'bilinear' (2 axes) lowers to `interp.bilinear`. 'nearest' lowers to `index` after `interp.searchsorted`. The chosen kind MUST be consistent with the number of axes; mismatch is rejected at load time with diagnostic 'table_interpolation_axes_mismatch'.
+     */
+    interpolation?: "linear" | "bilinear" | "nearest";
+    /**
+     * Out-of-bounds policy applied to query coordinates that fall outside an axis range. 'clamp' pins to the nearest edge — this matches the semantics of `interp.linear` and `interp.bilinear` (extrapolate-flat). 'error' MUST raise at evaluation time; bindings emit diagnostic 'table_lookup_out_of_bounds' on first violation. v0.4.0: 'clamp' is the only policy required of all five bindings; 'error' is conformant when the binding implements it.
+     */
+    out_of_bounds?: "clamp" | "error";
+    /**
+     * Optional ordered list of output names. When present, `table_lookup.output` MAY name an entry of this list (in addition to using a 0-based integer index). Names within a table MUST be unique. The leading dimension of `data` MUST equal the length of `outputs`.
+     *
+     * @minItems 1
+     */
+    outputs?: [string, ...string[]];
+    /**
+     * Nested-array literal carrying the table's sampled values. Leaves MUST be finite numbers (NaN entries are rejected at load time with 'table_data_nan'). Shape: [len(outputs), len(axes[0].values), ...] when `outputs` is present; [len(axes[0].values), ...] otherwise. Mismatched nesting is rejected with 'table_data_shape_mismatch'.
+     */
+    data: {
+        [k: string]: unknown;
+    };
+    /**
+     * Optional redundant shape assertion. If present, MUST match the actual nesting of `data`; loaders verify and reject mismatches with 'table_data_shape_mismatch'. `data` is the canonical representation; `shape` is a load-time assertion only.
+     *
+     * @minItems 1
+     */
+    shape?: [number, ...number[]];
+    /**
+     * Optional pin of the table-schema minor version this entry was authored against. Bindings ignore the value beyond a same-major-version compatibility check; informational for tooling.
+     */
+    schema_version?: string;
+}
+/**
+ * A single named axis inside a FunctionTable. The `values` array supplies the sample coordinates along this axis; it MUST be strictly increasing finite floats with at least 2 entries (mirrors the `interp.linear` / `interp.bilinear` axis contract in §9.2).
+ */
+interface FunctionTableAxis {
+    /**
+     * Axis identifier. Used as the key in `table_lookup.axes` to bind the input-coordinate expression.
+     */
+    name: string;
+    /**
+     * Optional advisory units string (e.g. 'Pa', 'K'). v0.4.0 records this for documentation only — no load-time unit checking is performed against the supplied input expression. Promotion to enforcement is deferred to a future units RFC.
+     */
+    units?: string;
+    /**
+     * Strictly-increasing finite floats. Bindings MUST reject non-monotonic axes at load time with diagnostic 'table_axis_non_monotonic' and NaN entries with 'table_axis_nan'.
+     *
+     * @minItems 2
+     */
+    values: [number, number, ...number[]];
+}
+/**
+ * Document-scoped named integers bound at load (esm-spec §9.7.6): at import/subsystem edges via `bindings`, at the loader API for the root document, or by `default`. Admissible — as names or `{op, args}` integer expressions — in `index_sets` interval sizes, `aggregate` dense ranges, and `makearray` regions (folded exactly at load), and substituted as integer literals in ordinary expression positions. A metaparameter name MUST NOT collide with any visible variable/parameter/species/index-set name (`metaparameter_name_conflict`).
+ */
+interface Metaparameters {
+    [k: string]: {
+        /**
+         * The only v1 metaparameter kind.
+         */
+        type: "integer";
+        /**
+         * Fallback applied at root resolution, after edge and loader-API bindings; a still-open metaparameter with no default is `metaparameter_unbound`.
+         */
+        default?: number;
+        description?: string;
+    };
+}
+
+/**
+ * Tagged numeric-literal AST nodes and lossless JSON I/O per
+ * discretization RFC §5.4.1 (int/float distinction) and §5.4.6
+ * (on-wire number formatting).
+ *
+ * JS has a single IEEE-754 `number` type, so `JSON.parse("1")` and
+ * `JSON.parse("1.0")` both yield `1`. To preserve the RFC-mandated
+ * integer-vs-float AST-node distinction, this module provides:
+ *
+ *   - `NumericLiteral` — a tagged `{kind, value}` leaf that records
+ *     whether the on-wire token was a JSON-integer or a JSON-float.
+ *   - `losslessJsonParse` — a minimal JSON parser that emits
+ *     `NumericLiteral` at every numeric-token position. Token shape
+ *     (presence of `.`, `e`, `E`) determines kind per the RFC §5.4.6
+ *     round-trip parse rule.
+ *   - `losslessJsonStringify` — inverse: `NumericLiteral{kind:int}`
+ *     → JSON integer; `NumericLiteral{kind:float}` → RFC §5.4.6 float
+ *     with the trailing-`.0` override for integer-valued magnitudes
+ *     in `[−(1e21 − 1), 1e21 − 1]`.
+ *   - `intLit`, `floatLit`, `isNumericLiteral`, `isIntLit`, `isFloatLit`,
+ *     `numericValue` — ergonomic helpers so existing consumers of the
+ *     `number | string | ExpressionNode` union can accept
+ *     `NumericLiteral` with minimal churn.
+ *
+ * NaN and ±Infinity are rejected on serialize with
+ * `E_CANONICAL_NONFINITE` per RFC §5.4.6.
+ */
+interface NumericLiteral {
+    readonly kind: 'int' | 'float';
+    readonly value: number;
+}
+declare function intLit(value: number): NumericLiteral;
+declare function floatLit(value: number): NumericLiteral;
+declare function isNumericLiteral(x: unknown): x is NumericLiteral;
+declare function isIntLit(x: unknown): x is NumericLiteral & {
+    kind: 'int';
+};
+declare function isFloatLit(x: unknown): x is NumericLiteral & {
+    kind: 'float';
+};
+/**
+ * Return the underlying numeric value of a plain `number` or a
+ * `NumericLiteral`. Returns `undefined` for anything else. Use this
+ * at the boundary between kind-aware and kind-agnostic code.
+ */
+declare function numericValue(x: unknown): number | undefined;
+declare class LosslessJsonParseError extends Error {
+    readonly position: number;
+    constructor(message: string, position: number);
+}
+/**
+ * Parse a JSON document, preserving the integer-vs-float distinction
+ * of every numeric token per RFC §5.4.6: a token containing `.`, `e`,
+ * or `E` becomes `NumericLiteral{kind:'float'}`; otherwise it becomes
+ * `NumericLiteral{kind:'int'}`. All other JSON values (strings, bools,
+ * null, arrays, objects) decode to their native JS equivalents.
+ *
+ * Integer-grammar tokens outside the safe-integer range fall back to
+ * `float` kind to avoid silent precision loss, matching the Go
+ * binding's `normalizeJSONNumber` behavior.
+ */
+declare function losslessJsonParse(text: string): unknown;
+/**
+ * Canonical-form error carrying a stable RFC §5.4.6 / §5.4.7 `code` string
+ * (`E_CANONICAL_NONFINITE`, `E_CANONICAL_DIVBY_ZERO`).
+ *
+ * Defined here — the lowest module in the canonical-form stack — so that both
+ * this module's serializer and `canonicalize.ts` can share ONE nonfinite error
+ * type ({@link CanonicalNonfiniteError} extends it) without an import cycle.
+ * `canonicalize.ts` re-exports this class under the same name, so consumers may
+ * keep importing `CanonicalizeError` from either module.
+ */
+declare class CanonicalizeError extends Error {
+    /** Stable RFC §5.4.6 / §5.4.7 error code. */
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+/**
+ * Raised when a non-finite number (NaN, ±Infinity) reaches canonical / lossless
+ * serialization — RFC §5.4.6 forbids non-finite numbers in the wire form. A
+ * specialization of {@link CanonicalizeError} carrying the
+ * `E_CANONICAL_NONFINITE` code plus the offending `value` and its `path`, so a
+ * single `instanceof CanonicalizeError` check catches every canonical-form
+ * failure regardless of which pass raised it.
+ */
+declare class CanonicalNonfiniteError extends CanonicalizeError {
+    readonly value: number;
+    readonly path: string;
+    constructor(value: number, path: string);
+}
+/**
+ * Stringify a value to JSON, emitting `NumericLiteral` leaves per RFC
+ * §5.4.6:
+ *
+ *   - `kind: 'int'`  → JSON-integer token (no `.`, no `e`).
+ *   - `kind: 'float'` with integer-valued magnitude in
+ *     `[−(1e21 − 1), 1e21 − 1]` → `ToString(Number)` with trailing
+ *     `.0` appended so the token cannot be confused with an integer
+ *     on parse-back (e.g. `1.0`, `-3.0`, `0.0`).
+ *   - `kind: 'float'` otherwise → native `ToString(Number)` (which is
+ *     already distinguishable via `.` or `e`).
+ *   - `-0.0` float → `-0.0`.
+ *   - NaN or ±Infinity → throws `CanonicalNonfiniteError`.
+ *
+ * Plain JS `number` values are serialized with `JSON.stringify`'s
+ * default rules (no trailing `.0` override); callers that want
+ * canonical emission must tag literals via `intLit` / `floatLit`.
+ */
+declare function losslessJsonStringify(value: unknown): string;
+/**
+ * Emit a float token via ECMAScript `ToString(Number)` with a trailing
+ * `.0` override when the result is an integer-valued plain-decimal token.
+ *
+ * NAMING: this is the DOCUMENT-serialization float emitter (used by
+ * {@link losslessJsonStringify} and `save()`), which relies on
+ * `ToString(Number)`'s own exponent formatting. It is deliberately NOT the
+ * strict RFC §5.4.6 CANONICAL-FORM emitter — that is the confusingly-similar
+ * `formatCanonicalFloat` in `canonicalize.ts`, which additionally normalizes
+ * exponent notation (strips the leading `+` and forces the §5.4.6 exponent
+ * thresholds). Keep the two distinct: `formatFloatToken` for wire round-trip,
+ * `formatCanonicalFloat` for byte-canonical output.
+ */
+declare function formatFloatToken(value: number): string;
+
+/**
+ * EarthSciML Serialization Format TypeScript type definitions — plus a small
+ * set of RUNTIME re-exports.
+ *
+ * Provides the complete type definitions for the ESM format: the auto-generated
+ * types from the JSON schema (`export * from './generated.js'`) and manual
+ * augmentations for discriminated unions and ergonomics. For convenience this
+ * module ALSO re-exports the runtime tagged numeric-literal API (`intLit`,
+ * `floatLit`, `losslessJsonParse`, …) from `./numeric-literal.js`, so it is not
+ * purely type-level; `index.ts` re-exports both surfaces from here (do not move
+ * the runtime re-exports without updating `index.ts`).
+ *
+ * Canonical alias names (duplicates are kept for back-compat but marked
+ * `@deprecated`):
+ *   - root file structure → `EsmFile`   (aliases: `EsmFormat`, generated `ESMFormat`)
+ *   - operator node       → `ExpressionNode` (alias: `ExprNode`)
+ *   - `Expression` (wire / schema-shaped value) and `Expr` (widened in-memory
+ *     value that MAY carry a tagged `NumericLiteral`) are DISTINCT types, not
+ *     aliases — pick by whether you hold a wire value or an in-memory one.
+ */
+
+/**
+ * An expression node whose OPERANDS are in-memory {@link Expr} values.
+ *
+ * The wire `ExpressionNode` has `args: Expression[]`, which cannot hold a
+ * tagged `NumericLiteral`. Every rewriting pass (differentiation, substitution,
+ * simplification, CSE) builds nodes out of operands it was handed, so those
+ * operands are `Expr` and the node it builds is this. `ExpressionNode` is
+ * assignable to it — `Expression` is a subset of `Expr` and `args` is covariant
+ * — so a wire node flows into a rewriting pass unchanged.
+ *
+ * Before esm 1.0.0 this widening was ACCIDENTAL: json2ts resolved the generated
+ * `Expression` to `number | string | { [k: string]: unknown }`, whose open
+ * object branch swallowed anything at all. The 1.0.0 schema restructure made it
+ * resolve to the real `ExpressionNode` — strictly more faithful — which exposed
+ * every site that had been relying on that looseness. This states the widening
+ * deliberately instead of inheriting it from a generator artifact.
+ */
+interface ExprNodeOf {
+    op: string;
+    args: Expr[];
+    [k: string]: unknown;
+}
+type Expr = Expression | NumericLiteral | ExprNodeOf;
+
+type EsmFile = ESMFormat1 & Omit<ESMFormat2, 'models'> & {
+    /**
+     * Narrowed so that a model reached from the document root is the 1.0.0
+     * {@link Model} — closed variables, no data-source subsystem — rather than
+     * the generated shape. Without this the strictness stops at the root and
+     * `file.models[m].variables[v].expression` reads as `unknown` again.
+     *
+     * This REPLACES the generated `models` (via `Omit`) rather than
+     * intersecting with it. Intersecting produced
+     * `(GeneratedModel | SubsystemRef) & (Model | SubsystemRef)`, which
+     * TypeScript does not simplify — so assigning a `Model`-typed VARIABLE
+     * (as opposed to a fresh object literal, which gets an implicit index
+     * signature) demanded it also satisfy `SubsystemRef`, and failed with
+     * "Property 'ref' is missing".
+     */
+    models?: {
+        [k: string]: Model | SubsystemRef;
+    };
+};
+/** @deprecated Prefer {@link EsmFile}. Identical to the generated `ESMFormat`. */
+type EsmFormat = ESMFormat;
+/** @deprecated Prefer {@link ExpressionNode} (the generated name). */
+type ExprNode = ExpressionNode;
+
+/**
+ * Symmetric positive-semidefinite covariance matrix, row-major: `[i][j]` is the
+ * covariance of components i and j. Square, with order equal to the length of
+ * the accompanying `mean` / `mu` vector and of the parameter's `shape`.
+ */
+type CovarianceMatrix = number[][];
+/**
+ * Gaussian. Exactly one of `std` (independent components) or `cov` (a full
+ * covariance matrix) — never both, which is why this is a union rather than two
+ * optional fields.
+ */
+type NormalDistribution = {
+    kind: 'normal';
+    mean: number | number[];
+} & ({
+    std: number | number[];
+    cov?: never;
+} | {
+    cov: CovarianceMatrix;
+    std?: never;
+});
+/**
+ * Log-normal: `log(value)` is normal with mean `mu` and spread `sigma` / `cov`.
+ * Both spread forms are on the LOG scale. Exactly one of `sigma` or `cov`.
+ */
+type LognormalDistribution = {
+    kind: 'lognormal';
+    mu: number | number[];
+} & ({
+    sigma: number | number[];
+    cov?: never;
+} | {
+    cov: CovarianceMatrix;
+    sigma?: never;
+});
+/**
+ * Uniform on `[low, high]`. Components are independent by construction, so
+ * there is no covariance form.
+ */
+interface UniformDistribution {
+    kind: 'uniform';
+    low: number | number[];
+    high: number | number[];
+}
+/**
+ * A parameter's value drawn from a probability distribution rather than fixed.
+ * The closed set is `normal` | `lognormal` | `uniform`. Mutually exclusive with
+ * `default`. WHEN it is drawn is decided by the parameter's `update`: with no
+ * update it is sampled ONCE at setup; with `update.kind: "wiener"` it is
+ * resampled every step with √dt scaling.
+ *
+ * Univariate when the location parameter is a number, multivariate when it is
+ * an array (in which case the parameter's `shape` must agree).
+ */
+type Distribution = NormalDistribution | LognormalDistribution | UniformDistribution;
+/**
+ * A registered handler computing a parameter's new value when its update fires
+ * — the 0.x event `functional_affect`, relocated onto the parameter it writes.
+ */
+interface FunctionalUpdate {
+    handler_id: string;
+    read_vars?: string[];
+    read_params?: string[];
+    config?: {
+        [k: string]: unknown;
+    };
+}
+/** Decodes a TEXT source column into numbers a model can compute with. */
+interface DataSourceCodes {
+    map: {
+        [k: string]: number;
+    };
+    case_insensitive?: boolean;
+    unmapped?: 'drop' | 'error' | number;
+}
+/**
+ * Binds a parameter to one variable of a `data_sources` entry. This is the 0.x
+ * `DataLoaderVariable` minus `units`: the units are the parameter's own,
+ * declared once on the parameter instead of twice.
+ */
+interface DataSourceBinding {
+    file_variable: string;
+    unit_conversion?: Expression;
+    codes?: DataSourceCodes;
+    select?: DataSourceSelect;
+    description?: string;
+    reference?: Reference;
+}
+/**
+ * The value form every non-`wiener` update kind takes EXACTLY ONE of: computed
+ * symbolically (`expression`), read from a data source (`from`), or produced by
+ * a registered handler (`handler`).
+ */
+type UpdateValueForm = {
+    expression: Expression;
+    from?: never;
+    handler?: never;
+} | {
+    from: DataSourceBinding;
+    expression?: never;
+    handler?: never;
+} | {
+    handler: FunctionalUpdate;
+    expression?: never;
+    from?: never;
+};
+/**
+ * A driving Wiener (Brownian) process: the parameter's `distribution` is
+ * resampled every step with √dt increment scaling. Takes NO value form — the
+ * distribution IS the value — and requires `distribution` on the variable.
+ * Its presence promotes the enclosing model from an ODE system to an SDE.
+ */
+interface WienerUpdate {
+    kind: 'wiener';
+}
+/** Time-driven refresh at preset `times` and/or on a periodic `interval`. */
+type ScheduleUpdate = {
+    kind: 'schedule';
+    times?: number[];
+    interval?: number;
+    initial_offset?: number;
+} & UpdateValueForm;
+/** Refresh at the end of any timestep at which `when` is true. */
+type ConditionUpdate = {
+    kind: 'condition';
+    when: Expression;
+} & UpdateValueForm;
+/** Refresh when `when` crosses zero, located by root-finding. */
+type CrossingUpdate = {
+    kind: 'crossing';
+    when: Expression;
+    direction?: 'up' | 'down' | 'any';
+} & UpdateValueForm;
+/**
+ * Refresh when the named data source advances a record. `source` MUST resolve
+ * to a `data_sources` key (`data_source_undefined`).
+ */
+type DataUpdate = {
+    kind: 'data';
+    source: string;
+} & UpdateValueForm;
+/** Refresh on a mesh-topology change (AMR refinement, moving/reloaded mesh). */
+type RemeshUpdate = {
+    kind: 'remesh';
+    hook?: string;
+} & UpdateValueForm;
+/**
+ * Every update kind except `wiener`. The schema forbids `wiener` inside an
+ * update ARRAY (a driving noise process is the parameter's whole value), which
+ * is what this type names.
+ */
+type NonWienerParameterUpdate = ScheduleUpdate | ConditionUpdate | CrossingUpdate | DataUpdate | RemeshUpdate;
+/** One update rule. Six kinds, discriminated by `kind`. */
+type ParameterUpdate = WienerUpdate | NonWienerParameterUpdate;
+/**
+ * A parameter's update behavior: EITHER a single rule, OR an ordered array of
+ * TWO OR MORE rules applied in declaration order. A single rule MUST be the
+ * object form — a one-element array is invalid — so the representation of any
+ * given update set is unique and the round-trip is stable.
+ */
+type ParameterUpdateSpec = ParameterUpdate | [NonWienerParameterUpdate, NonWienerParameterUpdate, ...NonWienerParameterUpdate[]];
+/**
+ * A variable in a model — either an `unknown` the solver solves for, or a
+ * `parameter` supplied to it. There is no third kind, and no `expression`
+ * field: an unknown's behavior is stated by the model's `equations` and nowhere
+ * else.
+ *
+ * Everything a solver additionally needs is DERIVED, never declared — see the
+ * classification API in `./classification.js` (`odeStates`, `observedUnknowns`,
+ * `algebraicUnknowns`, `brownianParameters`, `discreteParameters`,
+ * `sampledParameters`, `constantParameters`, `systemKind`).
+ *
+ * Deliberately CLOSED (no index signature): reading a field 1.0.0 removed —
+ * `expression`, `noise_kind`, `correlation_group`, `refresh` — is a compile
+ * error rather than a silent `unknown`.
+ */
+interface ModelVariable {
+    type: 'unknown' | 'parameter';
+    units?: string;
+    /** For an unknown, its value at t=0. For a parameter, its constant value. */
+    default?: number;
+    default_units?: string;
+    description?: string;
+    /**
+     * Ordered index-set names. REQUIRED for a parameter whose `update` is
+     * `schedule`, `data`, or `remesh`.
+     */
+    shape?: string[];
+    location?: string;
+    /** Parameter-only. Mutually exclusive with `default`. */
+    distribution?: Distribution;
+    /** Parameter-only. Absent means the parameter never changes after setup. */
+    update?: ParameterUpdateSpec;
+}
+/**
+ * A model node. Narrows the generated type in the two places that matter: its
+ * variables are the CLOSED {@link ModelVariable} above, and a subsystem is a
+ * child model or a reference — never a data source, which from 1.0.0 is not a
+ * component and cannot be a subsystem, a coupling endpoint, or a scoped-name
+ * path root.
+ */
+type Model = Omit<Model$1, 'variables' | 'subsystems'> & {
+    variables: {
+        [k: string]: ModelVariable;
+    };
+    subsystems?: {
+        [k: string]: Model | SubsystemRef;
+    };
+};
+
+/**
+ * Runtime unit conversion for ESM format.
+ *
+ * Complements `units.ts` (which performs dimensional analysis) by adding
+ * numeric value conversion between compatible units: `convertUnits(1, "km", "m")` → 1000.
+ *
+ * Representation: each unit parses to a canonical SI-base dimension vector plus a
+ * multiplicative scale factor and (for temperature) an additive offset. Conversion
+ * goes through SI base: `value_SI = value * scale + offset`, then `target = (value_SI - offset_t) / scale_t`.
+ *
+ * This module is intentionally independent of the `DimensionalRep` used by `units.ts`
+ * — that representation lacks scale tracking and treats `cm`, `J`, `Pa` as base
+ * dimensions, which would make extension invasive.
+ */
+/**
+ * Exponents over the SI base dimensions — the SAME eight axes, in the same
+ * roles, as the Go reference's `Dimension` vector (`m kg s mol K A cd rad`),
+ * which is the cross-binding contract for what a unit string MEANS.
+ *
+ * `molec` is deliberately NOT an axis. A count of discrete things carries no
+ * physical dimension, so `molec` (and `individuals`, `vehicles`, `units`,
+ * `count`) is a DIMENSIONLESS unit in the table below — which is what makes
+ * `molec/cm^3` compare equal to `1/cm^3`, as every other binding has it. Giving
+ * counts their own axis made TS the only binding that could report a mismatch
+ * between the two spellings of a number density.
+ */
+interface CanonicalDims {
+    kg?: number;
+    m?: number;
+    s?: number;
+    K?: number;
+    mol?: number;
+    A?: number;
+    cd?: number;
+    rad?: number;
+}
+interface ParsedUnit {
+    dims: CanonicalDims;
+    scale: number;
+    offset?: number;
+}
+declare class UnitConversionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a unit string into canonical SI dimensions plus scale (and optional offset).
+ *
+ * Recursive-descent parser over the grammar of the Go reference implementation
+ * (`pkg/earthsci-ast-go/pkg/esm/units.go`), so the bindings agree on how a unit
+ * string associates:
+ *
+ * ```
+ *   unit     := term ( ('*' | '/')? term )*
+ *   term     := atom ( ('^' | '**') exponent )?
+ *   exponent := integer | decimal | '(' integer '/' integer ')'
+ *   atom     := '1' | symbol | '(' unit ')'
+ * ```
+ *
+ * EXPONENTS ARE RATIONAL, not integral: `1/s^0.5` (an SDE noise intensity) and
+ * `m^(1/2)` are legitimate corpus units, and a dimension vector may therefore
+ * carry fractional entries.
+ *
+ * `*` and `/` share one precedence level and associate LEFT — so `kg/m*s` is
+ * `(kg/m)*s` = kg·s·m⁻¹, NOT kg·m⁻¹·s⁻¹, and `a/b/c` is `a/(b*c)`. Grouping with
+ * parentheses is supported, so the ordinary earth-science spellings `J/(mol*K)`
+ * and `cm^3/(molec*s)` parse.
+ *
+ * WHITESPACE BETWEEN TWO TERMS IS MULTIPLICATION — the SI style `kg m^2 s^-2`
+ * and the corpus's `ppb^-1 s^-1`. The scanner is greedy over identifier
+ * characters, so `ms` stays ONE symbol (millisecond); juxtaposition can only
+ * arise across a real token boundary. `**` is accepted as a synonym for `^` (the
+ * Python/pint spelling, e.g. the corpus's `Pa*m**3`).
+ *
+ * The empty string, `"1"` and `"dimensionless"` are the dimensionless unit.
+ * Non-ASCII spellings (`μg`, `°C`) are normalized first — see
+ * {@link normalizeUnitString}.
+ *
+ * @throws {UnitConversionError} on unknown unit names, malformed tokens,
+ *   unbalanced parentheses, or trailing input.
+ */
+declare function parseUnitForConversion(unitStr: string): ParsedUnit;
+/**
+ * Convert a numeric value from one unit string to another.
+ *
+ * @example
+ *   convertUnits(1, 'km', 'm')            // 1000
+ *   convertUnits(0, 'Celsius', 'K')       // 273.15
+ *   convertUnits(1, 'atm', 'Pa')          // 101325
+ *   convertUnits(1, 'Dobson', 'molec/m^2') // 2.6867e20
+ *
+ * @throws {UnitConversionError} when the unit strings have incompatible dimensions
+ *   or cannot be parsed.
+ */
+declare function convertUnits(value: number, from: string, to: string): number;
+/**
+ * Report whether two unit strings represent compatible (same-dimension) quantities.
+ * A non-throwing companion to `convertUnits`.
+ */
+declare function unitsCompatible(a: string, b: string): boolean;
+
+/**
+ * Unit parsing and dimensional analysis for ESM format
+ *
+ * This module implements unit string parsing and dimensional consistency
+ * checking following the ESM specification Section 3.3.1. It shares its
+ * canonical representation (`CanonicalDims` + `ParsedUnit`) with
+ * `unit-conversion.ts`, so derived units like `cm`, `J`, `Pa` collapse to
+ * their SI-base decomposition (`m`, `kg·m²·s⁻²`, `kg·m⁻¹·s⁻²`) with a scale
+ * factor rather than being treated as independent dimensions.
+ */
+
+/**
+ * A single dimensional-analysis diagnostic: the message plus the classification
+ * decided AT THE POINT it was raised (see {@link UnitWarning.code}). The code is
+ * explicit rather than recovered from the prose, so rewording a message can
+ * never silently flip a warning between `analysis` and `dimensional_mismatch`.
+ */
+interface UnitDiagnostic {
+    message: string;
+    code: UnitWarning['code'];
+}
+/**
+ * Result of dimensional analysis for a single expression.
+ */
+interface UnitResult {
+    /**
+     * The expression's canonical dimension, or `null` when it is INDETERMINATE.
+     *
+     * `null` is not "dimensionless" — it is "this analysis cannot say", and it is
+     * the value returned for an unknown variable, an unparseable unit
+     * declaration, and any operator whose dimensional semantics this module does
+     * not model (`index`, `fn`, `aggregate`, `makearray`, `table_lookup`, ...).
+     * Keeping the two apart is what stops a structural op from being *assumed*
+     * dimensionless and thereby manufacturing a false mismatch against a
+     * dimensional operand. `null` propagates through every combining rule, and a
+     * comparison against `null` is never a mismatch — it is simply skipped, which
+     * mirrors the Go reference (`PropagateDimension` returns `nil, nil`).
+     */
+    dimensions: ParsedUnit | null;
+    /** Message-only view, retained for the public `checkDimensions` API and
+     *  legacy callers that inspect warning prose. */
+    warnings: string[];
+    /** Structured view of {@link warnings}: each message with its explicit
+     *  classification. `validateUnits` uses these codes (not a prose regex) to
+     *  decide which warnings `validate()` promotes to errors. */
+    diagnostics: UnitDiagnostic[];
+}
+/**
+ * Dimensional-consistency warning emitted during file-level validation.
+ */
+interface UnitWarning {
+    message: string;
+    /**
+     * Structured finding kind, and the whole of the severity policy.
+     *
+     * A unit finding is either a DEFECT IN THE FILE — which invalidates the
+     * document — or a limit of the ANALYSIS, which does not. The classification is
+     * decided AT THE POINT the finding is raised (never recovered later from the
+     * prose, so rewording a message can never silently change its severity), and
+     * `validate()` promotes exactly the defect-bearing codes to
+     * `unit_inconsistency` structural errors.
+     *
+     * - `dimensional_mismatch` — a PROVABLE inconsistency: metres added to
+     *   kilograms, `log()` of a dimensional quantity, an equation whose sides
+     *   cannot agree. The file is wrong. → HARD ERROR.
+     * - `unparseable_unit` — a declared unit string that does not denote a real
+     *   unit (`"not_a_unit"`). A unit that names nothing is not an ambiguity to be
+     *   worked around; the declaration is meaningless, and that is a defect in the
+     *   FILE, not in the checker. → HARD ERROR. (Which is why the registry in
+     *   `unit-conversion.ts` must not be missing real units — under this policy a
+     *   registry gap is a false rejection.)
+     * - `analysis` — the checker cannot DETERMINE a dimension: a symbolic
+     *   exponent (`x^n`, whose dimension depends on `n`'s runtime value), an
+     *   operator with no dimensional rule (`aggregate`, `index`, `fn`,
+     *   `table_lookup`), a malformed arity, an unknown variable. Genuinely
+     *   undeterminable — a statement about the checker, not the file. → WARNING,
+     *   and the dimension is reported UNKNOWN and the check SKIPPED, never assumed
+     *   dimensionless.
+     *
+     * An unknown VARIABLE is an `analysis` finding here and nothing more: it is
+     * separately a hard `undefined_variable` error, so the units layer does not
+     * double-report it.
+     */
+    code: 'dimensional_mismatch' | 'unparseable_unit' | 'analysis';
+    location?: string;
+    equation?: string;
+    /** For `unparseable_unit`: the declaration at fault. `validate()` promotes the
+     *  finding to a `unit_parse_error` structural error and reports these verbatim
+     *  as its `details`, which the shared corpus pins. */
+    variable?: string;
+    units?: string;
+}
+/**
+ * Parse a unit string into canonical SI dimensions plus scale factor, or return
+ * `null` when the string cannot be parsed.
+ *
+ * This is the fallible companion to {@link parseUnit}: instead of swallowing a
+ * parse failure into a dimensionless fallback, it surfaces the failure as
+ * `null`. Callers can then leave the variable's dimension UNKNOWN (unbound) and
+ * emit a warning, rather than silently manufacturing a dimensionless binding
+ * that HIDES real dimensional mismatches — or MANUFACTURES false ones
+ * (esm-libraries-spec §3.3.3/§3.4, matching the Julia reference). A
+ * `UnitConversionError` (unknown unit name, malformed token, misused offset
+ * unit) maps to `null`; any other error is rethrown.
+ *
+ * `"degree"` / `"degrees"` are resolved by the canonical table as long-form
+ * aliases of `deg` (esm-spec §4.8.1), i.e. as the ANGLE axis scaled by π/180 —
+ * the reading the Rust, Julia and Python tables already carry. They used to be
+ * short-circuited to dimensionless here, which both disagreed with those three
+ * bindings and left the SINGULAR spelling unresolvable, since only the plural
+ * was special-cased and neither was in the table.
+ */
+declare function tryParseUnit(unitStr: string): ParsedUnit | null;
+/**
+ * Parse a unit string into canonical SI dimensions plus scale factor.
+ *
+ * STRICT: an unparseable unit string is an ERROR. It is never silently
+ * collapsed to dimensionless — a dimensionless fallback is a *claim* about the
+ * quantity, and a wrong one, which both hides real mismatches (everything
+ * compares equal to everything) and manufactures false ones (against genuinely
+ * dimensional operands). `J/(mol*K)` used to land in exactly that trap.
+ *
+ * Callers that must degrade gracefully rather than throw — the validators, which
+ * want to leave a dimension UNKNOWN and carry on — use {@link tryParseUnit},
+ * which returns `null` instead.
+ *
+ * @throws {UnitConversionError} on an unknown unit name, a malformed token,
+ *   unbalanced parentheses, or a misused offset unit.
+ */
+declare function parseUnit(unitStr: string): ParsedUnit;
+/**
+ * Check dimensional consistency of an expression.
+ *
+ * Follows ESM spec Section 3.3.1:
+ * - Addition/subtraction: operands must share canonical dimensions
+ * - Multiplication: dimensions add (scales multiply)
+ * - Division: dimensions subtract (scales divide)
+ * - `^` with a constant integer exponent: dimensions scale by the exponent
+ * - `sqrt`: dimensions halve
+ * - `D(x, wrt=t)`: dimension of x divided by dimension of t
+ * - Transcendental functions require dimensionless arguments
+ *
+ * Returns `dimensions: null` for anything INDETERMINATE (see
+ * {@link UnitResult.dimensions}) — an unknown variable, or an operator this
+ * module does not model dimensionally. Indeterminate operands never produce a
+ * mismatch; only a *provable* inconsistency does.
+ */
+declare function checkDimensions(expr: Expression, unitBindings: Map<string, ParsedUnit>): UnitResult;
+/**
+ * Validate dimensional consistency of equations in an ESM file.
+ *
+ * SCOPE: every real inline component — each top-level model / reaction system
+ * AND their inline `subsystems` (walked via `forEachComponent(..., {recurse:
+ * true})`; reference-stub and data-loader subsystems are opaque leaves and are
+ * skipped). For each, `forEachEquation` covers a model's dynamic `equations`
+ * and a reaction system's `constraint_equations`; models additionally have
+ * their `observed` variable expressions checked.
+ *
+ * BINDINGS: the shared top-level environment (top-level models' variables +
+ * reaction systems' species/parameters, scoped key + bare first-wins) is used
+ * for EVERY component, including subsystems. Subsystem-local declarations are
+ * deliberately NOT added, so a name defined only inside a subsystem stays an
+ * "Unknown variable" and keeps the mismatch-suppression in `checkAndReport`.
+ * This is the conservative scope required to broaden coverage without
+ * introducing cross-language divergence: binding a subsystem's own variables
+ * would un-suppress equation-level mismatches for nondimensionalized subsystem
+ * ODEs (e.g. `D(u,t) = k*u` with a dimensionless `u`), which the other bindings
+ * — none of which run a full per-equation dimensional check — never flag. A
+ * top-level reaction system's `constraint_equations` still resolve fully,
+ * because that system's species/parameters ARE in the shared environment.
+ *
+ * SPATIAL-CALCULUS SUGAR: `grad`/`div`/`laplacian` (and `integral`, and any user
+ * op) are ordinary open-tier rewrite-target ops with NO dimensional rule
+ * (esm-spec §4.2 / §4.8.3 "any other op"): their dimension is UNDETERMINABLE
+ * until a discretization rule lowers them to a `D` stencil, so `checkDimensions`
+ * reports UNKNOWN and skips the enclosing check (§4.8.4). There is no coordinate
+ * table and no op-name special case — the checker never divides an operand by a
+ * coordinate's units. Unparseable variable-unit DECLARATIONS are still a defect;
+ * {@link reportUnparseableVariableUnits} flags them per component (the only pass
+ * that sees inline-subsystem variables).
+ */
+declare function validateUnits(file: EsmFile): UnitWarning[];
+
+/**
+ * ESM Format JSON Parsing
+ *
+ * Provides functionality to load and validate ESM files from JSON strings or objects.
+ * Separates concerns: JSON parsing → schema validation → type coercion.
+ */
+
+/**
+ * Schema validation error with JSON Pointer path
+ */
+interface SchemaError {
+    /** JSON Pointer path to the error location */
+    path: string;
+    /** Human-readable error message */
+    message: string;
+    /** AJV validation keyword that failed */
+    keyword: string;
+}
+/**
+ * Parse error - thrown when JSON parsing fails
+ */
+declare class ParseError extends Error {
+    originalError?: Error | undefined;
+    constructor(message: string, originalError?: Error | undefined);
+}
+/**
+ * Schema validation error - thrown when schema validation fails
+ */
+declare class SchemaValidationError extends Error {
+    errors: SchemaError[];
+    constructor(message: string, errors: SchemaError[]);
+}
+/**
+ * The schema version this library implements, derived from the embedded
+ * schema's `$id` (https://earthsciml.org/schemas/esm/<version>/esm.schema.json)
+ * so it cannot hand-drift from the canonical esm-schema.json. The package
+ * version in package.json is kept in lockstep.
+ */
+declare const SCHEMA_VERSION: string;
+/**
+ * Validate data against the ESM schema
+ */
+declare function validateSchema(data: unknown): SchemaError[];
+/**
+ * Options controlling how `load()` parses and represents an ESM file.
+ */
+interface LoadOptions {
+    /**
+     * When `true`, numeric literals at Expression-bearing positions are
+     * decoded to tagged `NumericLiteral` leaves (see
+     * {@link losslessJsonParse}) so downstream consumers can preserve the
+     * integer-vs-float distinction required by the canonical form
+     * (discretization RFC §5.4.1 / §5.4.6). When `false` or absent
+     * (default), numeric literals decode to plain JS numbers for
+     * backwards compatibility.
+     *
+     * Canonical mode only takes effect for string inputs; pre-parsed
+     * objects are returned as-is (callers that want tagged leaves should
+     * run `losslessJsonParse` themselves before passing the object in).
+     */
+    canonical?: boolean;
+    /**
+     * Directory anchoring relative `expression_template_imports` refs
+     * (esm-spec §9.7.2). Defaults to the current working directory. Callers
+     * loading from a known file path should pass that file's directory.
+     */
+    basePath?: string | undefined;
+    /**
+     * 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`.
+     */
+    metaparameters?: Record<string, number> | undefined;
+    /**
+     * Synchronous file reader used to resolve template-library import refs.
+     * Defaults to Node's `fs.readFileSync` (via `process.getBuiltinModule`);
+     * browser hosts that need template imports must supply their own.
+     */
+    readFile?: ((path: string) => string) | undefined;
+    /**
+     * Scope-directed template injection for a §4.7 subsystem-ref edge
+     * (esm-spec §9.7.10 form A): raw §9.7.2 import entries folded into this
+     * document's single top-level component's own scope BEFORE the §9.6.3
+     * fixpoint, so a mounted discretization-agnostic PDE leaf is lowered under
+     * the assembler-chosen discretization. Threaded in by `resolveSubsystemRefs`
+     * from the subsystem edge; not part of the public authoring surface.
+     */
+    injectedImports?: readonly unknown[] | undefined;
+    /**
+     * Skip schema validation because the caller has already run
+     * {@link validateSchema} on this input. Version checks and the
+     * removed-construct rejections still apply. Used by `validate()` to avoid
+     * validating the same document twice.
+     */
+    assumeValid?: boolean | undefined;
+    /**
+     * Receives each dimensional-analysis warning instead of the default
+     * `console.warn`. Used by `validate()` to collect unit warnings into its
+     * structured result.
+     */
+    onUnitWarning?: ((warning: UnitWarning) => void) | undefined;
+    /**
+     * Receives the forward-compatibility warning emitted when the file's minor
+     * version is newer than the schema this build implements, instead of the
+     * default `console.warn`. Parallels {@link onUnitWarning} so hosts can route
+     * both load-time warnings into a structured channel.
+     */
+    onVersionWarning?: ((message: string) => void) | undefined;
+}
+/**
+ * Load an ESM file from a JSON string or pre-parsed object
+ *
+ * @param input - JSON string or pre-parsed JavaScript object
+ * @param options - Optional load-time settings (see {@link LoadOptions})
+ * @returns Typed EsmFile object
+ * @throws {ParseError} When JSON parsing fails or version is incompatible
+ * @throws {SchemaValidationError} When schema validation fails
+ */
+declare function load(input: string | object, options?: LoadOptions): EsmFile;
+
+/**
+ * ESM Format JSON Serialization (esm-cs3).
+ *
+ * `save(file)` emits an `EsmFile` as wire-form JSON suitable for round-trip
+ * through `load()`. Mirrors the Python and Julia serializers in three respects:
+ *
+ *   1. **AST canonical numeric handling.** `NumericLiteral` tagged leaves
+ *      (the in-memory int/float carrier produced by `losslessJsonParse` and
+ *      `intLit` / `floatLit`) are emitted as bare JSON numbers. In default
+ *      mode they collapse to plain `number` tokens via `JSON.stringify`. In
+ *      `canonical: true` mode they emit per RFC §5.4.6: integer-tagged
+ *      leaves as integer tokens, float-tagged leaves with the trailing
+ *      `.0` discriminator preserved.
+ *
+ *   2. **Drop transient flags.** The Symbol-keyed
+ *      `[NUMERIC_LITERAL_TAG]` brand on tagged literals is non-enumerable
+ *      string-key-wise, so `JSON.stringify` already skips it; this module
+ *      strips the user-visible `kind` / `value` fields too so the wire
+ *      form contains only bare JSON numbers, never the in-memory
+ *      `{kind,value}` carrier.
+ *
+ *   3. **Wire-form keys.** TypeScript types are generated from the JSON
+ *      schema, so the in-memory shape already matches the wire form (no
+ *      Python-style dataclass → wire field-name remapping is needed).
+ *      Object key order is the insertion order produced by `load()` /
+ *      authored constructors, which is itself schema-driven.
+ *
+ * The Python reference at `pkg/earthsci-ast-py/src/earthsci_ast/serialize.py`
+ * is 1172 LoC because it carries dataclass → wire field-name mappings the
+ * TypeScript binding does not need. The TS implementation stays compact by
+ * delegating shape preservation to the generated types.
+ */
+
+/** Optional behavior controls for {@link save}. */
+interface SaveOptions {
+    /**
+     * When `true`, emit byte-canonical JSON per RFC §5.4.6: integer-tagged
+     * `NumericLiteral` leaves as integer tokens, float-tagged leaves with
+     * the trailing `.0` discriminator preserved (e.g. `1.0` stays `1.0`
+     * rather than collapsing to `1`). Plain JS `number` values keep
+     * `JSON.stringify` semantics in either mode.
+     *
+     * Default: `false` (structural round-trip; integer-valued floats may
+     * collapse to JSON integers).
+     */
+    canonical?: boolean;
+    /**
+     * Indentation passed through to the underlying JSON formatter.
+     * Default `2` to match the Python and Julia reference serializers.
+     * Set to `0` for a single-line emission.
+     */
+    indent?: number;
+}
+/**
+ * Serialize an `EsmFile` to wire-form JSON.
+ *
+ * @param file - The `EsmFile` to serialize.
+ * @param options - Optional behavior controls (see {@link SaveOptions}).
+ * @returns Wire-form JSON string.
+ * @throws {CanonicalNonfiniteError} In `canonical: true` mode, if a
+ *   `NumericLiteral` leaf holds NaN or ±Infinity (RFC §5.4.6 forbids
+ *   non-finite numbers in the canonical wire form).
+ */
+declare function save(file: EsmFile, options?: SaveOptions): string;
+
+/**
+ * Shared validation result / error types for the structural-validation modules.
+ *
+ * Leaf module: no dependency on any other `validate/` file, so the check
+ * modules and the orchestrator can all import these shapes without a cycle.
+ */
+
+/**
+ * Validation error with structured details
+ */
+interface ValidationError {
+    path: string;
+    message: string;
+    code: string;
+    details: Record<string, unknown>;
+}
+/**
+ * Structured validation result
+ */
+interface ValidationResult {
+    is_valid: boolean;
+    schema_errors: ValidationError[];
+    structural_errors: ValidationError[];
+    unit_warnings: UnitWarning[];
+}
+
+/**
+ * Public `validate()` orchestrator: parses/loads an ESM file, runs schema
+ * validation, then drives every structural (post-schema) validator and
+ * aggregates the results into a {@link ValidationResult}.
+ *
+ * This module imports the check modules (model-, reaction-, coupling-checks)
+ * and shared helpers; the check modules never import back, so there is no cycle.
+ */
+
+/**
+ * Options for {@link validate}.
+ */
+interface ValidateOptions {
+    /**
+     * Base directory that relative `{ref}` targets and `expression_template_imports`
+     * resolve against — normally the directory of the file being validated.
+     *
+     * WITHOUT it, `validate()` does no file I/O: it cannot open a ref target, so it
+     * cannot know whether that target exists, and every `{ref}` subsystem is
+     * reported as `unresolved_subsystem_ref`. That is a truthful answer (the
+     * document has an unresolved mount) but a useless one for a caller who has the
+     * file on disk and simply wants it validated — and it makes every subsystem-ref
+     * and template-import pin in the shared corpus unsatisfiable, because a
+     * MISSING target and a PRESENT one produce the identical verdict.
+     *
+     * WITH it, refs are resolved (recursively, including the §4.7 index-set merge
+     * and §9.7 template machinery) before structural validation runs: a present
+     * target validates through, and a missing one yields `unresolved_subsystem_ref`
+     * — the two are now distinguishable, which is the whole point.
+     *
+     * Only LOCAL paths resolve here, because `validate()` is synchronous and
+     * `fetch` cannot be awaited; a remote (`http(s)://`) ref is reported as
+     * unresolved with a message pointing at the async `resolveSubsystemRefs()`.
+     */
+    basePath?: string;
+}
+/**
+ * Validate ESM data and return structured validation result.
+ *
+ * @param data - ESM data as JSON string or object
+ * @param options - Optional {@link ValidateOptions}; pass `basePath` to let
+ *   relative `{ref}` / template-import targets be opened and resolved.
+ * @returns ValidationResult with validation status and errors
+ */
+declare function validate(data: string | object, options?: ValidateOptions): ValidationResult;
+
+/**
+ * The esm 1.0.0 classification API (esm-spec §6.3.1).
+ *
+ * The format declares TWO variable types, `unknown` and `parameter`. Everything
+ * a solver additionally needs — which unknowns are ODE states, which are
+ * observed, which are algebraic; which parameters are Brownian, discrete,
+ * sampled, constant — is DERIVED from the equations and from each parameter's
+ * `distribution` / `update`, never read off a declared type.
+ *
+ * Every binding exposes the same pure functions of a model, spelled in its own
+ * idiom: snake_case in Julia, Python, Rust and Go; camelCase HERE and only
+ * here. The semantics are identical; only the spelling differs.
+ *
+ * These functions are the ONLY sanctioned way to ask these questions. A site
+ * that used to branch on `variable.type === 'state'` calls {@link isOdeState};
+ * one that branched on `'observed'` calls {@link observedUnknowns}; `'brownian'`
+ * and `'discrete'` call {@link brownianParameters} / {@link discreteParameters}.
+ * Reading a declared type to answer a derived question is precisely what 1.0.0
+ * removes.
+ *
+ * The cross-language oracle is `tests/conformance/classification/`.
+ */
+
+/** The four derived parameter categories (esm-spec §6.3.1). */
+type ParameterClass = 'brownian' | 'discrete' | 'sampled' | 'constant';
+/** The three derived unknown categories (esm-spec §6.3.1). */
+type UnknownClass = 'ode_state' | 'observed' | 'algebraic';
+/** The MTK system type a model maps to. */
+type SystemKind = 'ode' | 'nonlinear' | 'sde' | 'pde';
+/** Names of every variable declared `unknown`, sorted. */
+declare function unknowns(model: Model): string[];
+/** Names of every variable declared `parameter`, sorted. */
+declare function parameters(model: Model): string[];
+/**
+ * Unknowns appearing under `D(·, t)` on some equation LHS — the integrated
+ * states.
+ */
+declare function odeStates(model: Model): string[];
+/** Membership test for {@link odeStates}. */
+declare function isOdeState(model: Model, name: string): boolean;
+/**
+ * Unknowns defined by a BARE-VARIABLE LHS (`y ~ f(…)`) — eliminable,
+ * materializable. An unknown that is already an ODE state is not observed.
+ */
+declare function observedUnknowns(model: Model): string[];
+/**
+ * The DEFINING EXPRESSION of every observed unknown: the RHS of the
+ * bare-variable-LHS equation whose LHS is that name.
+ *
+ * This is the 1.0.0 relocation, in one place. An observed unknown's definition
+ * used to live in `variables[v].expression`; it now lives in the model's
+ * `equations` array. Every site that read the removed field reads this instead,
+ * so the relocation is expressed once rather than in each of the ten passes
+ * that used to reach for `variable.expression`.
+ *
+ * Only the first equation for a name is recorded: a second one is an unbalanced
+ * system, which {@link validateEquationBalance} reports rather than this.
+ */
+declare function observedDefinitions(model: Model): Map<string, Expression>;
+/**
+ * Unknowns constrained only implicitly (`H*H*SO4 ~ Ksp`) — everything left once
+ * the ODE states and the observed unknowns are removed. Defining this set by
+ * elimination is what makes the three sets a partition by construction.
+ */
+declare function algebraicUnknowns(model: Model): string[];
+/** The update rules of a parameter, normalized to an array (possibly empty). */
+declare function updateRules(spec: ParameterUpdateSpec | undefined): ParameterUpdate[];
+/**
+ * The derived class of ONE parameter. Exported because the cadence pass seeds
+ * its leaves from this rather than re-deriving the categories locally
+ * (CONFORMANCE_SPEC §5.7.2).
+ */
+declare function parameterClass(variable: ModelVariable): ParameterClass;
+/** Parameters whose `update.kind` is `wiener` — the SDE noise sources. */
+declare function brownianParameters(model: Model): string[];
+/** Parameters carrying any OTHER update — piecewise-constant between refreshes. */
+declare function discreteParameters(model: Model): string[];
+/** Parameters with a `distribution` and no `update` — drawn once at setup. */
+declare function sampledParameters(model: Model): string[];
+/** Parameters with neither a `distribution` nor an `update` — plain constants. */
+declare function constantParameters(model: Model): string[];
+/**
+ * The system kind DERIVED from the equations and the parameter updates.
+ *
+ * FIRST match wins, and the order is normative
+ * (`tests/conformance/classification/manifest.json`, `system_kind_order`):
+ *
+ *   1. `sde`       — any Brownian parameter.
+ *   2. `pde`       — any equation contains a spatial derivative.
+ *   3. `nonlinear` — no time-derivative equation at all.
+ *   4. `ode`       — otherwise.
+ *
+ * Two orderings that look equivalent are not. `pde` is tested BEFORE
+ * `nonlinear`, so a steady-state PDE (`laplacian(phi) ~ f`, no time derivative)
+ * is `pde`. `sde` is tested BEFORE `pde`, so a model carrying both a wiener
+ * parameter and a spatial derivative is `sde` — not because it is not spatial,
+ * but because there is no SPDESystem constructor to select.
+ *
+ * Detection is a property of the EQUATIONS and never of the `domain` block:
+ * v0.8.0 removed `Domain.spatial`, so `domain` carries nothing spatial.
+ */
+declare function systemKind(model: Model): SystemKind;
+/** The model's explicit `system_kind` field, or `null` when absent. */
+declare function declaredSystemKind(model: Model): SystemKind | null;
+/** Every derived set for one model node, as the conformance goldens spell it. */
+interface ModelClassification {
+    odeStates: string[];
+    observedUnknowns: string[];
+    algebraicUnknowns: string[];
+    brownianParameters: string[];
+    discreteParameters: string[];
+    sampledParameters: string[];
+    constantParameters: string[];
+    systemKind: SystemKind;
+    declaredSystemKind: SystemKind | null;
+}
+/** Classify one model node. */
+declare function classifyModel(model: Model): ModelClassification;
+/**
+ * Classify every model node in a document, keyed by DOT-PATH from the document
+ * root, so a subsystem is `Parent.Child`. Classification is per model NODE, not
+ * per document: the names inside each list are LOCAL to that model and are not
+ * namespaced. A binding that flattens the document first and classifies once
+ * returns one merged answer instead of a scoped answer per node.
+ */
+declare function classifyDocument(models: {
+    [k: string]: unknown;
+}): {
+    [path: string]: ModelClassification;
+};
+
+/**
+ * Cadence-class seeding for the dependency-partition pass
+ * (CONFORMANCE_SPEC §5.7, normative; RFC semiring-faq-unified-ir §6.1).
+ *
+ * Every value is determined at one of three cadences, totally ordered
+ * `const ⊏ discrete ⊏ continuous`, and a node's class is `max` over its inputs.
+ * This module supplies the LEAF SEEDS that recursion bottoms out at, plus the
+ * `max`-over-an-expression helper built on them.
+ *
+ * **The seeds come from the §6.3.1 classification API, never from a locally
+ * re-derived notion of the categories.** §5.7.2 states the leaf-seed table in
+ * terms of those functions precisely so that five bindings cannot disagree
+ * about which nodes fold. Re-deriving "is this a state" here would be a sixth
+ * derivation and a sixth chance to be wrong.
+ *
+ * | Leaf | Seed |
+ * |---|---|
+ * | the independent variable `t` | `continuous` |
+ * | an unknown in `odeStates` | `continuous` |
+ * | an unknown in `algebraicUnknowns` | `continuous` |
+ * | an unknown in `observedUnknowns` | the join of its DEFINING EQUATION's RHS |
+ * | a parameter in `brownianParameters` | `continuous` (resampled every step) |
+ * | a parameter in `discreteParameters` | `discrete`, refined by its source |
+ * | a parameter in `sampledParameters` / `constantParameters` | `const` |
+ * | a numeric literal, index-set name, bound index symbol | `const` |
+ *
+ * The OBSERVED leaf is the one 1.0.0 changes, and it must not be shortcut.
+ * Before 1.0.0 an observed leaf seeded `const`, with the code admitting that
+ * was imprecise and unexercised. That is now both unavailable (observed and
+ * ODE-state are the same declared type) and unsound, since an observed defined
+ * from a state is `continuous`. Seeding every unknown `continuous` is equally
+ * wrong the other way: it would stop a STATE-FREE observed from folding, and
+ * const-folding exactly those is what the geometry and projection-pushdown
+ * paths rely on. So an observed leaf resolves to the join of its defining
+ * equation's RHS, transitively, memoised, with a cycle guard.
+ */
+
+/** The three cadence classes, totally ordered `const ⊏ discrete ⊏ continuous`. */
+type CadenceClass = 'const' | 'discrete' | 'continuous';
+/** The join (`max`) of two cadence classes. */
+declare function joinCadence(a: CadenceClass, b: CadenceClass): CadenceClass;
+/** The join of any number of cadence classes; `const` when there are none. */
+declare function joinAll(classes: Iterable<CadenceClass>): CadenceClass;
+/** Raised when the observed-definition chain contains a cycle. */
+declare class CadenceCycleError extends Error {
+    readonly cycle: string[];
+    constructor(cycle: string[]);
+}
+/**
+ * A reusable cadence seeder for ONE model. Holds the memo table for observed
+ * resolution, so a chain of observeds is resolved once rather than once per
+ * reference.
+ */
+declare class CadenceSeeder {
+    private readonly model;
+    private readonly esmFile?;
+    private readonly states;
+    private readonly algebraic;
+    private readonly brownian;
+    private readonly observedDefs;
+    private readonly memo;
+    private readonly inProgress;
+    private readonly independentVariable;
+    constructor(model: Model, esmFile?: EsmFile | undefined);
+    /** The set of observed unknowns, for callers that want to enumerate them. */
+    observedNames(): string[];
+    /**
+     * The cadence seed of a single NAME appearing as a leaf.
+     *
+     * A name that is not declared in this model — an index-set name, a bound index
+     * symbol, a relation tag, a coupled reference — seeds `const`, matching the
+     * final row of the §5.7.2 table.
+     */
+    leaf(name: string): CadenceClass;
+    /**
+     * A parameter's seed: `continuous` when Brownian, `const` when sampled or
+     * constant, otherwise `discrete` subject to the source refinement.
+     *
+     * **Source-seeded refinement** (§5.7.2, RFC pure-io-data-loaders §4.6). When a
+     * parameter's `update` is the `data` kind, its `source` names a `data_sources`
+     * entry, and it is the SOURCE — not the parameter's own declaration — that
+     * fixes the seed. A source WITH `temporal` keeps the parameter `discrete`
+     * (its refresh cadence is the source's update times); one WITHOUT describes
+     * non-time-varying data, so the parameter refines down to `const` — loaded
+     * once. Any other update kind, or a `source` that resolves to no entry, keeps
+     * the `discrete` seed.
+     *
+     * This is the one context in which a leaf's seed reads a document field
+     * outside its own declaration.
+     */
+    private parameterSeed;
+    /**
+     * The cadence of an EXPRESSION: `max` over its leaves.
+     *
+     * The gather rule needs no special case — index expressions are ordinary
+     * children, so `index(u, index(nbr, i, k))` splits naturally, the inner
+     * neighbour selection staying `const` while the outer value load is
+     * `continuous` because it touches `u`.
+     */
+    expression(expr: Expression): CadenceClass;
+}
+/** The cadence seed of one leaf NAME in a model. */
+declare function leafCadence(model: Model, name: string, esmFile?: EsmFile): CadenceClass;
+/** The cadence of an expression in a model: `max` over its leaves. */
+declare function expressionCadence(model: Model, expr: Expression, esmFile?: EsmFile): CadenceClass;
+
+/**
+ * Graph generation utilities for ESM files
+ *
+ * Provides functions to extract different graph representations from ESM files,
+ * as specified in the ESM Libraries Specification Section 4.8.
+ */
+
+/** Graph node representing a component in the system */
+interface ComponentNode {
+    /** Unique identifier for this component */
+    id: string;
+    /** Display name for the component */
+    name: string;
+    /**
+     * Type of component. From 1.0.0 there is no `data_loader`: a data source is
+     * ingest configuration, not a component, so it is neither a graph node nor a
+     * coupling endpoint (esm-spec §5.5).
+     */
+    type: 'model' | 'reaction_system';
+    /** Optional description */
+    description?: string;
+    /** Optional reference information */
+    reference?: Reference;
+    /** Metadata with counts for this component */
+    metadata: {
+        /** Number of variables */
+        var_count: number;
+        /** Number of equations */
+        eq_count: number;
+        /** Number of species (for reaction systems) */
+        species_count: number;
+    };
+}
+/** Graph edge representing a coupling relationship */
+interface CouplingEdge {
+    /** Unique identifier for this edge */
+    id: string;
+    /** Source component ID */
+    from: string;
+    /** Target component ID */
+    to: string;
+    /** Type of coupling */
+    type: CouplingEntry['type'];
+    /** Display label for the edge */
+    label: string;
+    /** Optional description */
+    description?: string;
+    /** Full coupling entry for editing */
+    coupling: CouplingEntry;
+}
+/** System graph representation with components and couplings */
+interface ComponentGraph {
+    /** All components in the system */
+    nodes: ComponentNode[];
+    /** All coupling relationships */
+    edges: CouplingEdge[];
+}
+/**
+ * Directed graph with node/edge lists plus adjacency, predecessor, and
+ * successor lookups (ESM Libraries Specification §4.8). Nodes are addressed by
+ * a string key (`ComponentNode.id` / `VariableNode.name`); edges reference
+ * those keys through `source`/`target`.
+ */
+interface Graph<N, E> {
+    /** All nodes in the graph */
+    nodes: N[];
+    /** All edges in the graph */
+    edges: Array<{
+        source: string;
+        target: string;
+        data: E;
+    }>;
+    /** Get adjacent nodes for a given node */
+    adjacency(node: string): string[];
+    /** Get predecessor nodes for a given node */
+    predecessors(node: string): string[];
+    /** Get successor nodes for a given node */
+    successors(node: string): string[];
+}
+/** Graph node representing a variable/parameter/species in the system */
+interface VariableNode {
+    /** Unique identifier for this variable (scoped, e.g., "Transport.temperature") */
+    name: string;
+    /**
+     * The variable's DERIVED category (esm-spec §6.3.1), not its declared type.
+     * The format declares only `unknown` and `parameter`; these are the finer
+     * categories a consumer of the graph actually wants, recovered from the
+     * equations and from each parameter's `distribution` / `update`.
+     *
+     * `state` is an ODE state, `observed` an unknown with a bare-variable-LHS
+     * definition, `algebraic` an implicitly-constrained unknown, `brownian` a
+     * wiener-updated parameter, `discrete` a parameter with any other update,
+     * `parameter` a sampled or constant one, and `species` a reaction-system
+     * species.
+     */
+    kind: 'state' | 'algebraic' | 'parameter' | 'observed' | 'brownian' | 'discrete' | 'species';
+    /** Units if specified */
+    units?: string;
+    /** System/component this variable belongs to */
+    system: string;
+}
+/**
+ * Graph edge representing a dependency between variables.
+ *
+ * The `equation_index` sentinel {@link NON_EQUATION_INDEX} (`-1`) marks a
+ * dependency that does not originate from a positionally-numbered equation or
+ * reaction — i.e. an observed/expression definition or a coupling variable map.
+ */
+interface DependencyEdge {
+    /** Source variable name */
+    source: string;
+    /** Target variable name */
+    target: string;
+    /**
+     * PROVENANCE category of the dependency — which structural site produced it,
+     * NOT a classification of the operators involved. See {@link EDGE_PROVENANCE}
+     * for the mapping. These values are historical labels and do NOT track the
+     * actual operator: an equation edge is always `'additive'` (even for
+     * `w = u * v`) and an observed-definition edge is always `'multiplicative'`
+     * (even for `w = u + v`), regardless of the `+`/`*`/etc. actually used. Do
+     * not read arithmetic meaning into them.
+     */
+    relationship: 'additive' | 'multiplicative' | 'rate' | 'stoichiometric';
+    /**
+     * Position of the equation/reaction that created this dependency, or
+     * {@link NON_EQUATION_INDEX} (`-1`) when the dependency has no positional
+     * equation (observed-variable definitions and coupling maps).
+     */
+    equation_index: number;
+    /** The expression that created this dependency */
+    expression: Expr;
+}
+/**
+ * Extract the system graph from an ESM file.
+ * Returns a directed graph (ESM Libraries Specification §4.8) where nodes are
+ * model components and edges are coupling rules, with adjacency helpers.
+ */
+declare function componentGraph(file: EsmFile): Graph<ComponentNode, CouplingEdge>;
+/**
+ * Extract the system graph from an ESM file in the legacy `{nodes, edges}`
+ * {@link ComponentGraph} shape (edges as {@link CouplingEdge} carrying
+ * `from`/`to`).
+ *
+ * @deprecated Prefer {@link componentGraph}, which returns the richer
+ * {@link Graph} with adjacency/predecessor/successor helpers. This snake_case
+ * alias is retained because the editor's web-components consume the flat
+ * `{nodes, edges}` shape; it will be removed once those callers migrate.
+ */
+declare function component_graph(esmFile: EsmFile): ComponentGraph;
+/**
+ * Utility to check if a component exists in the ESM file
+ */
+declare function componentExists(esmFile: EsmFile, componentId: string): boolean;
+/**
+ * Get the type of a component by its ID
+ */
+declare function getComponentType(esmFile: EsmFile, componentId: string): ComponentNode['type'] | null;
+/**
+ * Extract a variable-level dependency graph from an ESM file, model, reaction
+ * system, equation, reaction, or expression. Nodes are variables/parameters/
+ * species; edges represent dependencies (ESM Libraries Specification §4.8).
+ *
+ * @param target The target to analyze (EsmFile, Model, ReactionSystem, Equation, Reaction, or Expr)
+ * @param options Optional settings. `mergeCoupled` folds `variable_map` coupling
+ *   entries into cross-system edges (EsmFile targets only). `merge_coupled` is a
+ *   deprecated alias accepted for back-compat.
+ * @returns Graph with VariableNode nodes and DependencyEdge edges
+ */
+declare function expressionGraph(target: EsmFile | Model | ReactionSystem | Equation | Reaction | Expr, options?: {
+    mergeCoupled?: boolean;
+    /** @deprecated Use `mergeCoupled`. */
+    merge_coupled?: boolean;
+}): Graph<VariableNode, DependencyEdge>;
+/**
+ * Export graph as Graphviz DOT format.
+ * Node shapes: box for models and reaction systems, diamond for operators.
+ * Edge styles: solid for compose, dashed for variable_map.
+ */
+declare function toDot<N extends object, E>(graph: Graph<N, E>): string;
+/**
+ * Export graph as Mermaid flowchart format for Markdown embedding.
+ */
+declare function toMermaid<N extends object, E>(graph: Graph<N, E>): string;
+/**
+ * Export graph as JSON adjacency list format for web consumption.
+ */
+declare function toJsonGraph<N extends object, E>(graph: Graph<N, E>): string;
+
+/**
+ * Advanced expression analysis and manipulation types
+ *
+ * This module defines the core types for advanced expression analysis,
+ * including dependency graphs, complexity metrics, and manipulation utilities.
+ */
+
+/**
+ * The kind of a variable node. Derived from graph.ts's {@link VariableNode} so
+ * the union lives in exactly one place (analysis and the parent graph module
+ * must agree on the vocabulary of variable kinds).
+ */
+type VariableKind = VariableNode['kind'];
+/**
+ * Node representing a variable in a dependency graph.
+ *
+ * Overlaps graph.ts's {@link VariableNode} (both carry `name`/`kind`/`units`/
+ * `system`); this analysis variant additionally tracks the defining expression
+ * ({@link definition}) and the topological {@link depth}. The two families are
+ * kept separate because they are produced by different builders
+ * (`analysis/buildDependencyGraph` vs graph.ts's `expressionGraph`) with
+ * different edge payloads; the shared `kind` vocabulary is unified via
+ * {@link VariableKind}.
+ */
+interface DependencyNode {
+    /** Variable name */
+    name: string;
+    /** DERIVED variable category (state, algebraic, observed, parameter, brownian, discrete, species) — see {@link VariableKind}. */
+    kind: VariableKind;
+    /** System/model this variable belongs to */
+    system: string;
+    /** Units if specified */
+    units?: string;
+    /** Definition expression if available */
+    definition?: Expr;
+    /** Nesting level in the dependency graph */
+    depth: number;
+}
+/**
+ * Edge representing a dependency relationship between variables.
+ *
+ * Analysis-local counterpart of graph.ts's {@link DependencyEdge}; the two use
+ * disjoint edge vocabularies (`type` here vs `relationship`/`equation_index`
+ * there) because they are built by different graph constructors.
+ */
+interface DependencyRelation {
+    /** Source variable */
+    source: string;
+    /** Target variable */
+    target: string;
+    /** Type of dependency */
+    type: 'direct' | 'circular' | 'parameter_dependency' | 'definition_dependency';
+    /** Expression that creates this dependency */
+    expression?: Expr;
+}
+/** Graph representing variable dependencies */
+interface DependencyGraph extends Graph<DependencyNode, DependencyRelation> {
+    /** Check for circular dependencies */
+    hasCircularDependencies(): boolean;
+    /**
+     * Circular-dependency cycles. Each entry is one back-edge cycle found by a
+     * DFS over the directed edges; distinct cycles may share nodes (these are
+     * NOT strongly-connected components).
+     */
+    getCycles(): DependencyNode[][];
+    /**
+     * @deprecated Misnomer — this does NOT compute strongly-connected
+     * components; it returns the raw DFS cycles from {@link getCycles}. Use
+     * {@link getCycles} instead.
+     */
+    getStronglyConnectedComponents(): DependencyNode[][];
+    /** Topological sort of dependencies */
+    topologicalSort(): DependencyNode[];
+}
+/** Complexity metrics for an expression */
+interface ComplexityMetrics {
+    /** Total depth of the expression tree */
+    depth: number;
+    /** Total number of operations */
+    operationCount: number;
+    /** Number of unique variables */
+    variableCount: number;
+    /** Number of constants */
+    constantCount: number;
+    /** Distribution of operation types */
+    operationTypes: Record<string, number>;
+    /** Estimated computational cost (arbitrary units) */
+    computationalCost: number;
+    /** Memory usage estimate (arbitrary units) */
+    memoryUsage: number;
+}
+/** A single numerical-stability finding produced by `detectStabilityIssues`. */
+interface StabilityIssue {
+    /** Human-readable description of the issue */
+    issue: string;
+    /** Severity of the issue */
+    severity: 'low' | 'medium' | 'high';
+    /** Path to the offending subexpression (e.g. `['args[1]']`) */
+    path: string[];
+    /** Suggested remediation */
+    suggestion: string;
+}
+/** Common subexpression identification result */
+interface CommonSubexpression {
+    /** The common subexpression */
+    expression: Expr;
+    /** Locations where this subexpression appears */
+    locations: ExpressionLocation[];
+    /** Number of occurrences */
+    count: number;
+    /** Estimated cost savings from factoring out */
+    savings: number;
+}
+/** Location of an expression within a larger structure */
+interface ExpressionLocation {
+    /** Path to the expression (e.g. `['root', 'args[0]', 'args[1]']`) */
+    path: string[];
+    /** Human-readable description */
+    description: string;
+    /** Parent expression context */
+    context?: Expr;
+}
+/** Result of symbolic differentiation */
+interface DerivativeResult {
+    /** The derivative expression */
+    derivative: Expr;
+    /** Variable with respect to which we differentiated */
+    variable: string;
+    /** Simplified form if different from derivative */
+    simplified?: Expr;
+    /**
+     * For {@link higherOrderDerivative}: one entry per differentiation order,
+     * recording the expression at that order (`expression`) and its derivative
+     * (`derivative`, i.e. the expression at the next order). These are the
+     * successive derivative steps, NOT chain-rule multiplicative factors — hence
+     * the name `derivativeSteps` rather than the former misnomer `chainComponents`.
+     */
+    derivativeSteps?: Array<{
+        expression: Expr;
+        derivative: Expr;
+    }>;
+}
+
+/**
+ * Variable dependency graph construction and analysis
+ *
+ * This module provides functions to construct and analyze dependency graphs
+ * for variables in ESM files, supporting circular dependency detection,
+ * topological sorting, and dead code elimination.
+ */
+
+/**
+ * Build a dependency graph from an ESM file, model, or expression
+ * @param target The target to analyze
+ * @param options Analysis options
+ * @returns Dependency graph with nodes and edges
+ */
+declare function buildDependencyGraph(target: EsmFile | Model | ReactionSystem | Expr, options?: {
+    includeParameters?: boolean;
+    includeObserved?: boolean;
+    mergeAcrossSystems?: boolean;
+}): DependencyGraph;
+/**
+ * Find dependency-graph sinks: non-state variables that nothing else depends
+ * on. Note this includes terminal observed outputs — a sink is only truly
+ * "dead" if it is also not consumed outside the model (plots, couplings,
+ * downstream tooling), which this graph cannot see. State variables are
+ * excluded because they are integration outputs by definition.
+ */
+declare function findDeadVariables(graph: DependencyGraph): DependencyNode[];
+/**
+ * Enumerate every path from `startNode` to a sink (a node with no successors),
+ * following successor edges. Paths that revisit a node or exceed `maxDepth`
+ * hops are pruned.
+ */
+declare function findDependencyChains(graph: DependencyGraph, startNode: string, maxDepth?: number): string[][];
+
+/**
+ * Expression complexity metrics and analysis
+ *
+ * This module provides functions to analyze the computational complexity
+ * of expressions, including depth, operation counts, and estimated costs.
+ */
+
+/**
+ * Analyze the complexity of an expression
+ * @param expr Expression to analyze
+ * @returns Complexity metrics
+ */
+declare function analyzeComplexity(expr: Expr): ComplexityMetrics;
+/**
+ * Compare complexity of two expressions
+ * @param expr1 First expression
+ * @param expr2 Second expression
+ * @returns Comparison result (-1: expr1 simpler, 0: equal, 1: expr1 more complex)
+ */
+declare function compareComplexity(expr1: Expr, expr2: Expr): number;
+/**
+ * Classify expression complexity level
+ * @param expr Expression to classify
+ * @returns Complexity level
+ */
+declare function classifyComplexity(expr: Expr): 'trivial' | 'simple' | 'moderate' | 'complex' | 'very_complex';
+/**
+ * Find the most expensive sub-expressions in an expression
+ * @param expr Expression to analyze
+ * @param limit Maximum number of results to return
+ * @returns Array of expensive sub-expressions with their costs
+ */
+declare function findExpensiveSubexpressions(expr: Expr, limit?: number): Array<{
+    expression: Expr;
+    cost: number;
+    path: string[];
+}>;
+/**
+ * Estimate parallel execution potential
+ * @param expr Expression to analyze
+ * @returns Parallelization score (0-1, higher means more parallelizable)
+ */
+declare function estimateParallelPotential(expr: Expr): number;
+/**
+ * Detect numerical stability issues in expressions
+ * @param expr Expression to analyze
+ * @returns Array of potential stability issues
+ */
+declare function detectStabilityIssues(expr: Expr): StabilityIssue[];
+
+/**
+ * Common subexpression identification and elimination
+ *
+ * This module provides functions to identify repeated subexpressions
+ * within expressions or across multiple expressions in a model.
+ */
+
+/**
+ * Default minimum {@link analyzeComplexity} cost a subexpression must reach to
+ * be considered for factoring. Shared by every entry point below.
+ */
+declare const DEFAULT_MIN_COMPLEXITY = 5;
+/**
+ * Find common subexpressions in a single expression
+ * @param expr Expression to analyze
+ * @param minComplexity Minimum complexity threshold for considering subexpressions
+ * @returns Array of common subexpressions found
+ */
+declare function findCommonSubexpressions(expr: Expr, minComplexity?: number): CommonSubexpression[];
+/**
+ * Find common subexpressions across multiple expressions
+ * @param expressions Array of expressions to analyze
+ * @param minComplexity Minimum complexity threshold
+ * @returns Array of common subexpressions found across expressions
+ */
+declare function findCommonSubexpressionsAcrossExpressions(expressions: Array<{
+    expr: Expr;
+    name: string;
+}>, minComplexity?: number): CommonSubexpression[];
+/**
+ * Find common subexpressions in a model (including its subsystems). All of
+ * the model's expressions are analyzed in a single pass so duplicates that
+ * span the parent and a subsystem are counted together.
+ * @param model Model to analyze
+ * @param minComplexity Minimum complexity threshold
+ * @returns Array of common subexpressions found in the model
+ */
+declare function findCommonSubexpressionsInModel(model: Model, minComplexity?: number): CommonSubexpression[];
+/**
+ * Find common subexpressions across an entire ESM file. All models' and
+ * reaction systems' raw expressions are aggregated into ONE analysis pass so
+ * occurrence counts and locations reflect actual appearances — including
+ * duplicates local to a single model and duplicates spanning components.
+ * @param esmFile ESM file to analyze
+ * @param minComplexity Minimum complexity threshold
+ * @returns Array of common subexpressions found across the file
+ */
+declare function findCommonSubexpressionsInEsmFile(esmFile: EsmFile, minComplexity?: number): CommonSubexpression[];
+/**
+ * Estimate the cost savings from factoring out common subexpressions
+ * @param commonSubexpressions Array of common subexpressions
+ * @returns Total estimated cost savings
+ */
+declare function estimateSavings(commonSubexpressions: CommonSubexpression[]): number;
+/**
+ * Generate variable names for factored subexpressions.
+ *
+ * Keyed by the {@link CommonSubexpression} object itself so callers can look up
+ * a generated name directly from the array element (the previous private
+ * string key could not be reconstructed by callers).
+ * @param commonSubexpressions Array of common subexpressions
+ * @param prefix Prefix for generated variable names
+ * @returns Map from each common subexpression to its generated variable name
+ */
+declare function generateFactoredVariableNames(commonSubexpressions: CommonSubexpression[], prefix?: string): Map<CommonSubexpression, string>;
+/**
+ * Group common subexpressions by their structure type
+ * @param commonSubexpressions Array of common subexpressions
+ * @returns Grouped subexpressions by operation type
+ */
+declare function groupSubexpressionsByType(commonSubexpressions: CommonSubexpression[]): Record<string, CommonSubexpression[]>;
+
+/**
+ * Symbolic differentiation capabilities
+ *
+ * This module provides functions to compute symbolic derivatives
+ * of expressions with respect to variables, supporting the chain rule
+ * and various mathematical functions.
+ */
+
+/**
+ * Thrown when {@link differentiate} encounters an operator with no
+ * differentiation rule, or a known operator applied with an arity its rule
+ * does not cover. Callers that need a boolean answer should use
+ * {@link isDifferentiable}.
+ */
+declare class NonDifferentiableExpressionError extends Error {
+    readonly op: string;
+    readonly variable: string;
+    constructor(op: string, variable: string);
+}
+/** Thrown by {@link higherOrderDerivative} when `order` is not positive. */
+declare class InvalidDerivativeOrderError extends Error {
+    readonly order: number;
+    constructor(order: number);
+}
+/**
+ * Compute the symbolic derivative of an expression with respect to a variable
+ * @param expr Expression to differentiate
+ * @param variable Variable with respect to which to differentiate
+ * @returns Derivative result with simplified form
+ */
+declare function differentiate(expr: Expr, variable: string): DerivativeResult;
+/**
+ * Compute partial derivatives with respect to multiple variables
+ * @param expr Expression to differentiate
+ * @param variables Array of variables to differentiate with respect to
+ * @returns Map of variable names to their derivative results
+ */
+declare function partialDerivatives(expr: Expr, variables: string[]): Map<string, DerivativeResult>;
+/**
+ * Compute the gradient (all first partial derivatives)
+ * @param expr Expression to differentiate
+ * @param variables Array of variables (if not provided, will extract from expression)
+ * @returns Gradient as array of derivatives
+ */
+declare function gradient(expr: Expr, variables?: string[]): DerivativeResult[];
+/**
+ * Compute higher-order derivatives
+ * @param expr Expression to differentiate
+ * @param variable Variable with respect to which to differentiate
+ * @param order Order of derivative (default: 1)
+ * @returns Higher-order derivative result
+ */
+declare function higherOrderDerivative(expr: Expr, variable: string, order?: number): DerivativeResult;
+/**
+ * Check if an expression is differentiable with respect to a variable
+ * @param expr Expression to check
+ * @param variable Variable to check differentiability with respect to
+ * @returns True if differentiable, false otherwise
+ */
+declare function isDifferentiable(expr: Expr, variable: string): boolean;
+/**
+ * Find critical points (where derivative equals zero)
+ * This is a symbolic analysis - actual solving would require numerical methods
+ * @param expr Expression to analyze
+ * @param variable Variable to find critical points for
+ * @returns Information about potential critical points
+ */
+declare function findCriticalPoints(expr: Expr, variable: string): {
+    derivative: Expr;
+    simplified?: Expr;
+    hasConstantDerivative: boolean;
+    isConstantZero: boolean;
+};
+
+/**
+ * Advanced Expression Analysis and Manipulation
+ *
+ * This module provides analysis and manipulation capabilities for
+ * mathematical expressions in the ESM format:
+ *
+ * - Variable dependency graph construction and analysis
+ * - Expression complexity metrics
+ * - Common subexpression identification
+ * - Symbolic differentiation
+ *
+ * It re-exports only the symbols it owns. Graph generation/export
+ * (`expressionGraph`, `toDot`, ...), unit analysis, reaction ODE derivation,
+ * and model-editing operations live in their own modules and are re-exported
+ * from the package root (`../index.ts`), not duplicated here.
+ */
+
+/** Combined results returned by {@link analyzeExpression}. */
+interface AnalysisResults {
+    complexity?: ComplexityMetrics;
+    stabilityIssues?: StabilityIssue[];
+    commonSubexpressions?: CommonSubexpression[];
+    dependencyGraph?: DependencyGraph;
+    partialDerivatives?: Map<string, DerivativeResult>;
+    gradient?: DerivativeResult[];
+}
+/** Options controlling which analyses {@link analyzeExpression} runs. */
+interface AnalysisOptions {
+    /** Compute complexity metrics and stability issues (expression targets only). */
+    includeComplexity?: boolean;
+    /** Identify common subexpressions (expression targets only). */
+    includeSubexpressions?: boolean;
+    /** Build the variable dependency graph. */
+    includeDependencies?: boolean;
+    /** Compute partial derivatives and gradient (expression targets only). */
+    includeDerivatives?: boolean;
+    /** Variables to differentiate with respect to (required for derivatives). */
+    variables?: string[];
+    /** Minimum complexity threshold for common-subexpression detection. */
+    minComplexityThreshold?: number;
+}
+/**
+ * Perform comprehensive analysis of an expression or model.
+ * @param target Expression, Model, or ESM file to analyze
+ * @param options Analysis options
+ * @returns Complete analysis results
+ */
+declare function analyzeExpression(target: Expr | Model | EsmFile, options?: AnalysisOptions): AnalysisResults;
+/**
+ * Static namespace wrapping {@link analyzeExpression}.
+ * @deprecated Call {@link analyzeExpression} directly.
+ */
+declare const ExpressionAnalyzer: {
+    analyze: typeof analyzeExpression;
+};
+
+/**
+ * Pretty-printing formatters for ESM format expressions, equations, models, and files.
+ *
+ * Public output formats:
+ * - toUnicode(): Unicode mathematical notation with chemical subscripts
+ * - toLatex(): LaTeX mathematical notation
+ * - toAscii(): Plain text representation
+ * - toMathML(): MathML markup for web / academic publishing
+ * - formatChemicalName(): Unicode chemical-subscript rendering of a bare name
+ *
+ * The per-format rendering of each operator lives in one place — the
+ * {@link OP_RENDERERS} table — so adding an operator is a single entry
+ * (op-registry.ts:10-12).
+ *
+ * Based on ESM Format Specification Section 6.1
+ */
+
+/**
+ * Format an expression as Unicode mathematical notation
+ */
+declare function toUnicode(expr: Expr | Equation | Model | ReactionSystem | Reaction | EsmFile): string;
+/**
+ * Format an expression as LaTeX mathematical notation
+ */
+declare function toLatex(expr: Expr | Equation | Model | ReactionSystem | Reaction | EsmFile): string;
+/**
+ * Format an expression as plain ASCII text
+ */
+declare function toAscii(expr: Expr | Equation | Model | ReactionSystem | Reaction | EsmFile): string;
+/**
+ * Apply element-aware chemical subscript formatting to a bare variable /
+ * species name using Unicode subscript digits (e.g. "H2SO4" → "H₂SO₄").
+ * Exported for graph rendering (toDot / toMermaid labels).
+ */
+declare function formatChemicalName(name: string): string;
+/**
+ * Format an expression as MathML markup for web/academic publishing
+ */
+declare function toMathML(expr: Expr | Equation | Model | ReactionSystem | Reaction | EsmFile): string;
+
+/**
+ * parse-expression — the INVERSE of `toAscii` (pretty-print.ts) for authoring
+ * EarthSciAST expressions (esm-spec §4.2) as text.
+ *
+ * The concrete syntax IS what `toAscii` emits, so the pair round-trips:
+ * `toAscii(parseExpression(s)) === s`. Precedence is sourced from
+ * {@link opPrecedence} (op-registry.ts) so the parser can never drift from the
+ * printer. This parser RECONSTRUCTS existing AST node shapes; it never invents
+ * new ones, and it requires no change to `toAscii`.
+ *
+ * Coverage:
+ *  - scalar tier: arithmetic, powers, comparisons, boolean logic, elementary
+ *    functions, derivatives (`D(x)/Dt` and `D(x, t)`), open/user function calls;
+ *  - array & call-shaped tier: array literals `[…]` (`const`), indexing
+ *    `a[i, j]` (`index`), dotted closed-function calls `datetime.year(t)` (`fn`),
+ *    the `true` literal, and `integral` / `reshape` / `transpose` / `concat`;
+ *  - reduction & array-query tier: `aggregate` reductions
+ *    `sum[i] (expr) where {i in set, j in lo:hi} join(a=b) if pred distinct
+ *    key=k [semiring=…]` (all clause shapes), the `argmin`/`argmax` arg-witnesses
+ *    `argmin[g] (expr) where {…}`, template application
+ *    `name<binding = value, …>` (`apply_expression_template`),
+ *    `polygon_intersection_area(a, b, manifold=…)`, and the piecewise-region
+ *    array `makearray([lo:hi, …] = value, …)`.
+ *
+ * Aggregate `args` is a derived operand cache the printer doesn't emit; it's
+ * reconstructed best-effort (see {@link deriveAggregateArgs}) and is
+ * reprint-neutral. `sum` with neither an explicit `[semiring=…]` nor a `join`
+ * reconstructs as a plain `+` reduction — the join-less `sum_product` annotation
+ * (semantically identical there) is not recovered; both reprint identically.
+ *
+ * Still deferred (need dedicated surface syntax — a later pass): `table_lookup`,
+ * `broadcast`, `enum`, and `intersect_polygon` (its `id` field is not printed, so
+ * it can't round-trip). Those are refused with an {@link ExpressionParseError}.
+ *
+ * Design rules: multiplication is ALWAYS explicit (`k * A`) — no implicit
+ * juxtaposition, because identifiers are multi-letter (`NO2`, `O3`, `k_photo`).
+ * Two known non-exactnesses trace to `toAscii`, not the parser: float
+ * serialization (`formatNumber` routes through a JS double), and unary-minus
+ * operands being under-parenthesized (`-(a+b)` and `(-a)+b` both print
+ * `-a + b`) — the parser matches the printer's loose convention. Because the
+ * printer is not injective, `parseExpression(toAscii(ast))` is a faithful
+ * SEMANTIC round-trip but may normalize structure (flat vs. nested `+`; a scalar
+ * `const`/`fn` with a non-dotted name reprints identically to a plain
+ * number/op). Editors should treat text as a derived view and re-parse only
+ * dirtied expressions.
+ */
+
+/** Thrown when an expression string cannot be parsed. */
+declare class ExpressionParseError extends Error {
+    /** 0-based character offset into the source where parsing failed. */
+    pos: number;
+    constructor(message: string, 
+    /** 0-based character offset into the source where parsing failed. */
+    pos: number);
+}
+/**
+ * Parse a single expression string into an AST expression — the inverse of
+ * {@link toAscii}. Throws {@link ExpressionParseError} on malformed input or an
+ * operator with no text surface yet.
+ */
+declare function parseExpression(src: string): Expr;
+/**
+ * Parse `lhs = rhs` into an {@link Equation}. The top-level separator is a LONE
+ * `=`; `==` (and `>=`/`<=`/`!=`) remain comparison operators within either side.
+ */
+declare function parseEquation(src: string): Equation;
+
+/**
+ * parse-reaction.ts — the inverse of the reaction printer (`toAscii(reaction)`).
+ *
+ * Parses a single chemical reaction written in the text DSL, e.g.
+ *
+ *     2 NO + O3 -> [k1] NO2 + O2
+ *     CH4 + OH -> [arr(2.45e-12, 1775)] CH3O2 + H2O
+ *     -> [k_emit] O3            (source: ∅ → X, empty reactant side)
+ *     O3 -> [k_dep]             (sink:   X → ∅, empty product side)
+ *
+ * Grammar:
+ *   reaction := side? arrow rate? side?
+ *   arrow    := '->' | '→' | '⟶'
+ *   rate     := '[' expression ']'      (required — a reaction must have a rate)
+ *   side     := term ('+' term)*        (empty / '∅' ⇒ null: a source or sink)
+ *   term     := coefficient? species
+ *   coefficient := positive finite number (default 1; fractional yields allowed)
+ *   species  := any run of non-whitespace characters (a chemical formula token)
+ *
+ * The rate is parsed with the shared {@link parseExpression}, so a rate is any
+ * expression the DSL accepts (a parameter name, a number, an operator tree, a
+ * template application, …). The returned reaction carries an empty `id` — the
+ * caller (e.g. the editor merging into an existing reaction) supplies id/name.
+ */
+
+/**
+ * Parse a single reaction from its text-DSL form. Throws
+ * {@link ExpressionParseError} on any malformed input (the editor surfaces the
+ * message and blocks the edit). The returned reaction's `id` is empty — the
+ * caller assigns identity when merging into an existing reaction.
+ */
+declare function parseReaction(src: string): Reaction;
+
+/**
+ * Expression substitution functionality for the ESM format
+ *
+ * Provides immutable substitution operations that replace variable references
+ * with bound expressions throughout ESM structures.
+ */
+
+/**
+ * Context for resolving scoped references during substitution
+ */
+interface SubstitutionContext {
+    esmFile: EsmFile;
+}
+/**
+ * Recursively substitute variable references in an expression with bound expressions.
+ * Handles scoped references (Model.Subsystem.var) by splitting on '.' and matching
+ * path through system hierarchy per format spec Section 4.3.
+ *
+ * NOTE: when a `context` is supplied, any dotted reference NOT covered by
+ * `bindings` is resolved through the file hierarchy and replaced with the
+ * referenced variable's DECLARED DEFAULT VALUE. Callers that only want to
+ * rename/replace bound names must omit `context`.
+ *
+ * @param expr - Expression to substitute into
+ * @param bindings - Variable name to expression mappings
+ * @param context - Optional context; enables default-value inlining for
+ *   scoped references (see note above)
+ * @returns New expression with substitutions applied (immutable)
+ */
+declare function substitute(expr: Expr, bindings: Record<string, Expr>, context?: SubstitutionContext): Expr;
+/**
+ * Apply substitution across an ENTIRE model, not just its equations.
+ *
+ * The rewritten expression sites are, exhaustively (this is the single write
+ * definition of "a model's expression sites"; `edit.ts`'s read-side
+ * `forEachModelExpressionSite` MUST cover the same set):
+ *   - every equation `lhs` / `rhs`;
+ *   - every observed variable's `expression`;
+ *   - every continuous event's `conditions[]`, `affects[].rhs`, and
+ *     `affect_neg[].rhs`;
+ *   - every discrete event's condition-`trigger.expression` and `affects[].rhs`;
+ *   - recursively, every inline-model subsystem (data loaders and unresolved
+ *     `{ref}` subsystems pass through unchanged).
+ *
+ * Event affect `lhs` values are write-TARGET names (`string`), not expression
+ * read-sites, and are intentionally left untouched — substitution replaces
+ * references, not assignment targets.
+ *
+ * Returns a new model with substitutions applied (immutable).
+ *
+ * @param model - Model to substitute into
+ * @param bindings - Variable name to expression mappings
+ * @param context - Optional context for resolving scoped references
+ * @returns New model with substitutions applied
+ */
+declare function substituteInModel(model: Model, bindings: Record<string, Expr>, context?: SubstitutionContext): Model;
+/**
+ * Apply substitution across all rate expressions in a reaction system.
+ * Returns a new reaction system with substitutions applied (immutable).
+ *
+ * @param system - ReactionSystem to substitute into
+ * @param bindings - Variable name to expression mappings
+ * @param context - Optional context for resolving scoped references
+ * @returns New reaction system with substitutions applied
+ */
+declare function substituteInReactionSystem(system: ReactionSystem, bindings: Record<string, Expr>, context?: SubstitutionContext): ReactionSystem;
+
+/**
+ * Reaction system ODE derivation for the ESM format
+ *
+ * This module provides utilities for deriving ordinary differential equations (ODEs)
+ * from reaction systems using standard mass action kinetics.
+ */
+
+/**
+ * Derive ODEs from a reaction system using mass action kinetics
+ *
+ * Generates an ODE model from reaction stoichiometry and rate laws. For each reaction
+ * with rate k, substrates {Si} with stoichiometries {ni}, products {Pj} with
+ * stoichiometries {mj}:
+ * - rate law: v = k * prod(Si^ni)
+ * - ODE contribution: dX/dt += net_stoich_X * v
+ *
+ * Handles:
+ * - Source reactions (null substrates): rate is the direct production term
+ * - Sink reactions (null products): rate is the direct loss term
+ * - Constraint equations are appended as additional equations
+ *
+ * @param system ReactionSystem to derive ODEs from
+ * @returns Model with species as state variables, derived ODEs plus constraints
+ */
+declare function deriveODEs(system: ReactionSystem): Model;
+/**
+ * Compute stoichiometric matrix from a reaction system
+ *
+ * Returns the net stoichiometric matrix (species × reactions) where:
+ * - Rows are species (in declaration order)
+ * - Columns are reactions (in array order)
+ * - Entry [i][j] = (stoichiometry as product) - (stoichiometry as substrate) for species i in reaction j
+ * - Null substrates contribute 0 to substrate stoichiometry
+ * - Null products contribute 0 to product stoichiometry
+ *
+ * @param system ReactionSystem to compute matrix from
+ * @returns Object containing matrix, species list, and reactions list
+ */
+declare function stoichiometricMatrix(system: ReactionSystem): {
+    matrix: number[][];
+    species: string[];
+    reactions: string[];
+};
+/**
+ * Compute substrate stoichiometric matrix from a reaction system
+ *
+ * Returns the substrate stoichiometric matrix (species × reactions) where:
+ * - Rows are species (in declaration order)
+ * - Columns are reactions (in array order)
+ * - Entry [i][j] = substrate stoichiometry for species i in reaction j
+ * - Null substrates contribute 0
+ *
+ * @param system ReactionSystem to compute matrix from
+ * @returns Substrate stoichiometric matrix
+ */
+declare function substrateMatrix(system: ReactionSystem): number[][];
+/**
+ * Compute product stoichiometric matrix from a reaction system
+ *
+ * Returns the product stoichiometric matrix (species × reactions) where:
+ * - Rows are species (in declaration order)
+ * - Columns are reactions (in array order)
+ * - Entry [i][j] = product stoichiometry for species i in reaction j
+ * - Null products contribute 0
+ *
+ * @param system ReactionSystem to compute matrix from
+ * @returns Product stoichiometric matrix
+ */
+declare function productMatrix(system: ReactionSystem): number[][];
+
+/**
+ * Immutable editing operations for the ESM format
+ *
+ * This module provides comprehensive editing operations for ESM files, models,
+ * and reaction systems. All operations are immutable and return new objects.
+ */
+
+/**
+ * Error thrown when attempting to remove a variable that is still referenced
+ */
+declare class VariableInUseError extends Error {
+    variableName: string;
+    references: string[];
+    constructor(variableName: string, references: string[]);
+}
+/**
+ * Error thrown when attempting an operation on a non-existent entity
+ */
+declare class EntityNotFoundError extends Error {
+    entityType: string;
+    entityName: string;
+    constructor(entityType: string, entityName: string);
+}
+/**
+ * Add a new variable to a model
+ * @param model Model to add variable to
+ * @param name Variable name
+ * @param variable Variable definition
+ * @returns New model with variable added
+ */
+declare function addVariable(model: Model, name: string, variable: ModelVariable): Model;
+/**
+ * Remove a variable from a model, with reference checking
+ * @param model Model to remove variable from
+ * @param name Variable name to remove
+ * @returns New model with variable removed
+ * @throws VariableInUseError if variable is still referenced
+ * @throws EntityNotFoundError if variable doesn't exist
+ */
+declare function removeVariable(model: Model, name: string): Model;
+/**
+ * Rename a variable throughout a model.
+ *
+ * The rewrite covers exactly the expression sites `removeVariable` scans (via
+ * `substituteInModel` — equations, observed-variable expressions, event
+ * conditions/triggers/affect RHSs, and inline subsystems), so a rename never
+ * leaves a dangling reference in a site the removal guard would have flagged.
+ *
+ * @param model Model to rename variable in
+ * @param oldName Current variable name
+ * @param newName New variable name
+ * @returns New model with variable renamed
+ * @throws EntityNotFoundError if variable doesn't exist
+ */
+declare function renameVariable(model: Model, oldName: string, newName: string): Model;
+/**
+ * Add a new equation to a model
+ * @param model Model to add equation to
+ * @param equation Equation to add
+ * @returns New model with equation added
+ */
+declare function addEquation(model: Model, equation: Equation): Model;
+/**
+ * Remove an equation from a model
+ * @param model Model to remove equation from
+ * @param indexOrLhs Either the numeric index or the LHS expression of the equation
+ * @returns New model with equation removed
+ * @throws EntityNotFoundError if equation not found
+ */
+declare function removeEquation(model: Model, indexOrLhs: number | Expr): Model;
+/**
+ * Apply substitutions across a model.
+ *
+ * NOTE: despite the historical name, this does NOT touch only equations — it is
+ * a thin alias for {@link substituteInModel} and therefore also rewrites
+ * observed-variable expressions, event expression positions, and inline
+ * subsystems. See `substituteInModel` for the full list of rewritten sites.
+ *
+ * @deprecated The name understates its blast radius; call `substituteInModel`
+ *   (exported from `substitute.js`) directly. Retained as a public back-compat
+ *   export (re-exported via `index.ts` and `analysis/index.ts`).
+ * @param model Model to apply substitutions to
+ * @param bindings Variable name to expression mappings
+ * @returns New model with substitutions applied
+ */
+declare function substituteInEquations(model: Model, bindings: Record<string, Expr>): Model;
+/**
+ * Add a new reaction to a reaction system
+ * @param system ReactionSystem to add reaction to
+ * @param reaction Reaction to add
+ * @returns New reaction system with reaction added
+ */
+declare function addReaction(system: ReactionSystem, reaction: Reaction): ReactionSystem;
+/**
+ * Remove a reaction from a reaction system
+ * @param system ReactionSystem to remove reaction from
+ * @param id Reaction ID to remove
+ * @returns New reaction system with reaction removed
+ * @throws EntityNotFoundError if reaction not found
+ */
+declare function removeReaction(system: ReactionSystem, id: string): ReactionSystem;
+/**
+ * Add a new species to a reaction system
+ * @param system ReactionSystem to add species to
+ * @param name Species name
+ * @param species Species definition
+ * @returns New reaction system with species added
+ */
+declare function addSpecies(system: ReactionSystem, name: string, species: Species): ReactionSystem;
+/**
+ * Remove a species from a reaction system, with reference checking
+ * @param system ReactionSystem to remove species from
+ * @param name Species name to remove
+ * @returns New reaction system with species removed
+ * @throws VariableInUseError if species is still referenced in reactions
+ * @throws EntityNotFoundError if species doesn't exist
+ */
+declare function removeSpecies(system: ReactionSystem, name: string): ReactionSystem;
+/**
+ * Add a continuous event to a model
+ * @param model Model to add event to
+ * @param event Continuous event to add
+ * @returns New model with event added
+ */
+declare function addContinuousEvent(model: Model, event: ContinuousEvent): Model;
+/**
+ * Add a discrete event to a model
+ * @param model Model to add event to
+ * @param event Discrete event to add
+ * @returns New model with event added
+ */
+declare function addDiscreteEvent(model: Model, event: DiscreteEvent): Model;
+/**
+ * Remove events from a model by name.
+ *
+ * Remove-ALL semantics: EVERY event whose `name` matches is removed, not just
+ * the first. Containers are tried in order — if any continuous event matches,
+ * only continuous events are filtered; otherwise discrete events are filtered
+ * (a name present in both containers is removed only from `continuous_events`).
+ * If the filtered container ends up empty, its key is dropped per the
+ * module-wide drop-when-empty convention (see `withCollection`).
+ *
+ * @param model Model to remove event(s) from
+ * @param name Event name to remove
+ * @returns New model with matching event(s) removed
+ * @throws EntityNotFoundError if no event with that name exists
+ */
+declare function removeEvent(model: Model, name: string): Model;
+/**
+ * Add a coupling entry to an ESM file
+ * @param file ESM file to add coupling to
+ * @param entry Coupling entry to add
+ * @returns New ESM file with coupling added
+ */
+declare function addCoupling(file: EsmFile, entry: CouplingEntry): EsmFile;
+/**
+ * Remove a coupling entry from an ESM file by index
+ * @param file ESM file to remove coupling from
+ * @param index Index of coupling entry to remove
+ * @returns New ESM file with coupling removed
+ * @throws EntityNotFoundError if index is out of bounds
+ */
+declare function removeCoupling(file: EsmFile, index: number): EsmFile;
+/**
+ * Compose two systems using a coupling entry
+ * @param file ESM file
+ * @param a First system name
+ * @param b Second system name
+ * @returns New ESM file with composition coupling added
+ */
+declare function compose(file: EsmFile, a: string, b: string): EsmFile;
+/**
+ * Map a variable from one system to another with optional transformation
+ * @param file ESM file
+ * @param from Source variable reference
+ * @param to Target variable reference
+ * @param transform Optional transformation: one of the named transform strings,
+ *   or an Expression operator node evaluated in the flattened coupled system's
+ *   scope (esm-spec §8.6 — the regridding form)
+ * @returns New ESM file with variable mapping coupling added
+ */
+declare function mapVariable(file: EsmFile, from: string, to: string, transform?: CouplingVariableMap['transform']): EsmFile;
+/**
+ * Merge two ESM files
+ * @param fileA First ESM file
+ * @param fileB Second ESM file
+ * @returns New ESM file with merged content
+ */
+declare function merge(fileA: EsmFile, fileB: EsmFile): EsmFile;
+/**
+ * Extract a specific component from an ESM file into a new file
+ * @param file ESM file to extract from
+ * @param componentName Name of the component to extract
+ * @returns New ESM file containing only the specified component
+ * @throws EntityNotFoundError if component not found
+ */
+declare function extract(file: EsmFile, componentName: string): EsmFile;
+
+/**
+ * Expression structural operations for the ESM format
+ *
+ * This module provides utilities for analyzing and manipulating mathematical
+ * expressions in the ESM format AST.
+ */
+
+/**
+ * Extract all variable references from an expression.
+ *
+ * Routes through {@link forEachChild} — the ONE walker — so every
+ * expression-bearing field is seen, not just `args`. Walking `args` alone made
+ * whole sidecar subtrees invisible:
+ *
+ *   - `table_lookup{axes:{temp:'T_air'}}`      → `[]`      (missed `T_air`)
+ *   - `aggregate{args:['A'], expr:{*:['A','w']}}` → `['A']`  (missed `w`)
+ *   - `integral{lower:'a', upper:{+:['b',1]}}` → missed `a`, `b`
+ *
+ * `graph.ts` builds the dependency DAG from this, so every one of those misses
+ * was a silently-absent edge.
+ */
+declare function freeVariables(expr: Expr): Set<string>;
+/**
+ * Extract free parameters from an expression within a model context
+ * @param expr Expression to analyze
+ * @param model Model context to determine parameter vs state variables
+ * @returns Set of parameter names referenced in the expression
+ */
+declare function freeParameters(expr: Expr, model: Model): Set<string>;
+/**
+ * Check if an expression contains a specific variable
+ * @param expr Expression to search
+ * @param varName Variable name to look for
+ * @returns True if the variable appears in the expression
+ */
+declare function contains(expr: Expr, varName: string): boolean;
+/**
+ * Simplify an expression using basic algebraic rules
+ * @param expr Expression to simplify
+ * @returns Simplified expression
+ */
+declare function simplify(expr: Expr): Expr;
+
+/**
+ * Tree-walking scalar evaluator (`compileExpression` / `evaluateExpression`)
+ * — the EarthSciAST TypeScript in-process runner. Despite the historical
+ * "codegen" filename this performs NO code generation or lowering: a
+ * canonical-form `Expr` is walked directly. `compileExpression` returns a
+ * closure over a free-variable bindings map that returns the scalar numeric
+ * result; `evaluateExpression` walks and applies in one step.
+ *
+ * Structural / array ops and the closed-function registry are dispatched to
+ * their consumers; ANY op the evaluable-core op-registry does not know — the
+ * open-tier rewrite-target sugar `grad`/`div`/`laplacian`/`integral`, a user op,
+ * or a spatial / right-hand-side `D` — is rejected here as an unlowered
+ * rewrite-target: it must be lowered to a stencil by a rewrite rule before
+ * evaluation.
+ */
+
+/**
+ * Compiled expression closure produced by {@link compileExpression}.
+ * Accepts a `bindings` map of free-variable name → numeric value and
+ * returns the scalar result.
+ */
+type CompiledExpression = (bindings: Map<string, number>) => number;
+/**
+ * Error carrying the stable, cross-binding `unlowered_operator` diagnostic
+ * (esm-spec §4.2 / §9.6.3 constraint 6 / §9.6.8). Raised when a rewrite-target
+ * op reaches evaluation/compilation without having been lowered — the uniform
+ * gate that supersedes the old per-binding UnreachableSpatialOperator /
+ * UnsupportedDimensionality codes. Loading stays permissive (the op namespace
+ * is open); the gate fires only at evaluation, mirroring the Julia `_compile`
+ * gate in tree_walk.jl.
+ */
+declare class UnloweredOperatorError extends Error {
+    readonly code = "unlowered_operator";
+    constructor(message: string);
+}
+/**
+ * Error raised by the tree-walking evaluator for a node it cannot reduce to a
+ * scalar: an unbound variable, an unsupported operator, an unlowered `enum`, a
+ * non-scalar `const`, a malformed `fn`, or a non-expression value. Carries a
+ * stable `code` field so callers can branch programmatically instead of
+ * regex-matching prose.
+ *
+ * Unlike {@link UnloweredOperatorError}, the `message` is passed through
+ * VERBATIM (not `[code]`-prefixed): several of these strings are matched
+ * byte-for-byte by the cross-binding runner tests, so the wording is pinned.
+ * These `code` values are binding-local diagnostics for the in-process runner,
+ * distinct from the cross-language conformance codes in `errors.ts`.
+ */
+declare class EvaluatorError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Build a reusable closure that walks the canonical-AST {@link Expr} and
+ * evaluates it against a bindings map. This is the EarthSciAST TypeScript
+ * runner's entry point for scalar evaluation.
+ *
+ * The walker rejects unlowered `enum` ops (lower via `lowerEnums()` at
+ * load time) and array-valued `const` nodes (those are consumed by
+ * container ops such as `interp.searchsorted` and `index`, not by
+ * scalar evaluation).
+ */
+declare function compileExpression(expr: Expr): CompiledExpression;
+/**
+ * Compile and apply in one step. Equivalent to
+ * `compileExpression(expr)(bindings)` but avoids allocating a closure
+ * for one-shot callers (`simplify`'s constant-folding path,
+ * fixed-point observed-variable resolution, unit-conversion
+ * folding).
+ */
+declare function evaluateExpression(expr: Expr, bindings: Map<string, number>): number;
+
+/**
+ * Migration utilities for ESM format version upgrades.
+ *
+ * A migration here is a pure version-MARKER bump: it changes the `esm` field
+ * and touches nothing else. That is only ever sound along an ADDITIVE line —
+ * a run of schema releases each of which introduced its changes as additive,
+ * backward-compatible fields, so an older file already loads under the newer
+ * schema without any mechanical transform.
+ *
+ * The current additive line is `1.0.0 … <current schema version>`.
+ *
+ * **There is no migration across the 1.0.0 boundary.** esm 1.0.0 is a clean
+ * break with no deprecation path: the five declared variable types collapse to
+ * two, an observed variable's `expression` becomes an equation, `data_loaders`
+ * becomes a non-component `data_sources` registry, and parameter mutation moves
+ * off events onto the parameter. None of that is a marker bump — every one of
+ * them RESHAPES the document, and several need information (which unknowns are
+ * ODE states) that only the equations carry. A 0.x source therefore yields no
+ * supported targets rather than a bump that would produce a file claiming 1.0.0
+ * while still carrying 0.x shapes. Converting a 0.x document is a rewrite, and
+ * deliberately not offered as an automated one.
+ *
+ * The single supported target for an additive-line source is the CURRENT schema
+ * version (`SCHEMA_VERSION`); arbitrary intermediate targets are deliberately
+ * NOT offered — there is no per-minor transform to encode, only "bring this
+ * file up to current". Sources outside that line (newer than current, a
+ * different major, or malformed) yield no supported targets.
+ */
+
+/**
+ * Error thrown when migration fails.
+ */
+declare class MigrationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Check if migration is possible from the source version to target version.
+ */
+declare function canMigrate(sourceVersion: string, targetVersion: string): boolean;
+/**
+ * Get the list of schema versions that a given source version can migrate to.
+ *
+ * - any version on the additive line `1.0.0 … <current schema version>` →
+ *   `[SCHEMA_VERSION]` (a no-op marker bump to the current schema).
+ * - everything else — including EVERY 0.x version, which 1.0.0's clean break
+ *   puts out of reach of a marker bump — → `[]`.
+ */
+declare function getSupportedMigrationTargets(sourceVersion: string): string[];
+/**
+ * Migrate an ESM file from its current schema version to the target version.
+ *
+ * Every supported step is a pure version-marker bump with no structural
+ * transform: an additive-line source (`1.0.0 … <current>`) advanced to the
+ * current schema version (see the module header). Any other version pair — a
+ * 0.x source included — throws {@link MigrationError}. Content-level changes
+ * are not performed; they are modeling decisions, not mechanical migrations.
+ * The input file is never mutated; a new object with the updated `esm` marker
+ * is returned.
+ */
+declare function migrate(file: EsmFile, targetVersion: string): EsmFile;
+
+/**
+ * Coupling-library files and `coupling_import` role binding (esm-spec §10.9–§10.11).
+ *
+ * A *coupling-library file* is a document whose payload is a top-level
+ * `coupling_roles` map plus a role-scoped `coupling` array. An assembly reuses
+ * it with a `{ type: "coupling_import", ref, bind }` coupling entry: at flatten
+ * the import expands into concrete `variable_map` / `couple` / `operator_compose`
+ * / `event` edges by substituting the bound actual component for every
+ * role-named top-level segment (the §10.10.2 occurrence surface).
+ *
+ * Expansion runs *inside* flatten (esm-spec §10.10.3), after subsystem mounting
+ * (which happens at load, §2.1b) and before the coupling-rule step, so every
+ * `bind` target resolves against fully-mounted components. The `coupling_import`
+ * source entry is preserved for round-trip; only the flattened system carries
+ * the expanded edges.
+ */
+
+/** Options controlling how `coupling_import` refs are resolved at flatten. */
+interface CouplingImportOptions {
+    /** Directory the import `ref`s resolve against. Defaults to '.'. */
+    basePath?: string;
+    /**
+     * Resolve a `ref` string to a parsed coupling-library document. Defaults to a
+     * synchronous Node `fs` reader. Tests may supply an in-memory resolver.
+     */
+    loadRef?: (ref: string, basePath: string) => unknown;
+}
+/**
+ * True when `raw` has the coupling-library-file FORM (top-level
+ * `coupling_roles`, esm-spec §10.9). Presence of that key is the sole positive
+ * identifier of the file kind; purity is checked separately at the import edge.
+ */
+declare function isCouplingLibraryDoc(raw: unknown): boolean;
+/**
+ * Expand every `coupling_import` entry in `file.coupling` into concrete edges,
+ * splicing them in the position of the import entry (esm-spec §10.10.3).
+ * Returns the effective coupling array, or `undefined` if the file has no
+ * `coupling` block. Non-import entries pass through untouched; a file with no
+ * `coupling_import` entries needs no `options` and returns `file.coupling`
+ * verbatim.
+ */
+declare function expandCouplingImports(file: EsmFile, options?: CouplingImportOptions): CouplingEntry[] | undefined;
+
+/**
+ * Coupled System Flattening for the ESM format
+ *
+ * Transforms a multi-system ESM file into a single unified flattened system
+ * by namespacing all variables with their source system prefix and processing
+ * coupling entries to produce a unified equation set.
+ */
+
+/** Options for {@link flatten}. Only needed when the file uses `coupling_import`. */
+type FlattenOptions = CouplingImportOptions;
+/**
+ * A single equation in the flattened system, with dot-namespaced variable names.
+ */
+interface FlattenedEquation {
+    /** Dot-namespaced LHS variable name (e.g., "Atmos.O3") */
+    lhs: string;
+    /**
+     * Expression string with namespaced references.
+     *
+     * For equations produced from a `couple` connector, the string uses a
+     * `transform(expr)` pseudo-function convention: the connector's `transform`
+     * (`"additive"` / `"multiplicative"` / `"replacement"`) is emitted as the
+     * function name wrapping the (already-scoped) connector expression — e.g.
+     * `additive(A.x)`. These are provenance/intent markers, not scalar operators
+     * in {@link OPS}; a downstream consumer interprets the wrapper.
+     */
+    rhs: string;
+    /** Name of the source system this equation originated from */
+    sourceSystem: string;
+}
+/**
+ * Metadata describing the origin of the flattened system.
+ */
+interface FlattenMetadata {
+    /** Names of all source systems that were flattened */
+    sourceSystems: string[];
+    /** Human-readable descriptions of coupling rules applied */
+    couplingRules: string[];
+}
+/**
+ * A fully flattened representation of a coupled ESM system.
+ */
+interface FlattenedSystem {
+    /** All state variable names (dot-namespaced) */
+    stateVariables: string[];
+    /** All parameter names (dot-namespaced) */
+    parameters: string[];
+    /** All brownian (Wiener) noise variables (dot-namespaced). Any brownian => SDE system. */
+    brownianVariables: string[];
+    /** Observed/derived variables: namespaced name -> expression string */
+    variables: Record<string, string>;
+    /** All equations from all systems, with namespaced references */
+    equations: FlattenedEquation[];
+    /** Provenance metadata */
+    metadata: FlattenMetadata;
+}
+/**
+ * Flatten a multi-system ESM file into a single unified system.
+ *
+ * The algorithm:
+ * 1. Iterates over all models and reaction_systems in the file
+ * 2. Namespaces all variables with their system name prefix (dot notation)
+ * 3. Processes coupling entries to produce variable mappings and connector equations
+ * 4. Returns a unified flattened system
+ *
+ * @param file - The ESM file to flatten
+ * @returns A FlattenedSystem with all variables namespaced and equations unified
+ */
+declare function flatten(file: EsmFile, options?: FlattenOptions): FlattenedSystem;
+
+/**
+ * Subsystem reference loading for the ESM format (esm-spec §4.7).
+ *
+ * Resolves subsystem `ref` fields by loading the referenced ESM file (local
+ * path or remote URL), resolving any §9.7 template machinery + metaparameters
+ * the referenced document carries against this edge's `bindings` / injected
+ * imports, lowering it to the §9.6.3 fixpoint, then inlining the single
+ * extracted component in place. Resolution is recursive with path-scoped
+ * circular-reference detection.
+ *
+ * File access: local refs are read asynchronously via `node:fs/promises`
+ * (dynamic import so the module still parses in a browser), remote refs via
+ * `fetch`. Historically this module was purely fetch/fs I/O and so worked in
+ * both Node and the browser; that is no longer unconditional. Once a ref
+ * carries §9.7 machinery, resolution drives the SYNCHRONOUS §9.7 resolver over
+ * the already-loaded content (`resolveTemplateMachinery`), which needs a
+ * synchronous file reader for any transitive template-library imports — a
+ * plain-fetch browser host cannot satisfy that, so a machinery-bearing ref is
+ * fully resolvable only under Node (or a host supplying its own readFile hook).
+ */
+
+/**
+ * Error thrown when a circular reference is detected during subsystem resolution.
+ */
+declare class CircularReferenceError extends Error {
+    /** The chain of references that form the cycle */
+    readonly chain: string[];
+    constructor(chain: string[]);
+}
+/**
+ * Error thrown when a referenced file cannot be loaded, parsed, or uniquely
+ * resolved to one system.
+ *
+ * Carries the CANONICAL cross-binding diagnostic code (see `ERROR_CODES`):
+ *
+ *  - `unresolved_subsystem_ref` (default) — the file does not exist, or could
+ *    not be read or parsed.
+ *  - `ambiguous_subsystem_ref` — the file WAS read, and holds more than one
+ *    top-level system; §4.7 requires exactly one.
+ *
+ * The resolver is the only layer that reads the referenced file, so it is the
+ * only layer that can tell those two apart — the synchronous `validate()` does
+ * no I/O and reports every unresolved `{ref}` as `unresolved_subsystem_ref`.
+ */
+declare class RefLoadError extends Error {
+    /** The reference path or URL that failed to load */
+    readonly ref: string;
+    /** Canonical code: `unresolved_subsystem_ref` or `ambiguous_subsystem_ref`. */
+    readonly code: string;
+    /**
+     * JSON Pointer of the SUBSYSTEM ENTRY that carries the bad ref (e.g.
+     * `/models/ClimateModel/subsystems/Atm`) — not the document root. The corpus
+     * pins these errors at the offending mount, and a caller handed `$` has to go
+     * hunting for which of a dozen mounts failed.
+     */
+    readonly path: string;
+    constructor(ref: string, cause?: Error, code?: string, message?: string, path?: string);
+}
+/**
+ * Async resolution — the historical entry point, and the only one that can reach
+ * a REMOTE (`http(s)://`) ref, since `fetch` cannot be awaited synchronously.
+ *
+ * It is now a thin shell around the SYNC core: fetch every reachable ref into a
+ * cache first, then run the one and only resolution walk against that cache.
+ * There is deliberately no second walk implementing the same semantics — index-set
+ * merging, the §4.7 single-component invariant, template-machinery lowering,
+ * cycle detection and component inlining exist in exactly one place, so the sync
+ * and async paths cannot drift apart.
+ */
+declare function resolveSubsystemRefs(file: EsmFile, basePath: string): Promise<void>;
+/**
+ * esm-spec §9.7.10 form C: build a throwaway `EsmFile` in which component
+ * `mname` has the run'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 run-chosen discretization. The
+ * persisted `file` is never mutated. This is what lets one test/analysis suite
+ * exercise a discretization-agnostic PDE leaf under several schemes with no
+ * conflict between runs.
+ *
+ * The raw base is re-read from `sourcePath` when given (relative import `ref`s
+ * resolve against its directory), else re-serialized from `file`; `baseDir`
+ * anchors the injected `ref`s. Mirrors the Julia reference
+ * `_ephemeral_injected_file` (`EarthSciAST.jl/src/pde_inline_tests.jl`).
+ *
+ * This binding does not numerically simulate PDEs; the ephemeral build is the
+ * structural-lowering half of form C (the leaf's rewrite-target is lowered in
+ * this copy only). No solver is implied.
+ */
+declare function ephemeralInjectedFile(file: EsmFile | null, sourcePath: string | null, mname: string, imports: readonly unknown[], baseDir: string): Promise<EsmFile>;
+
+/**
+ * Canonical AST form per discretization RFC §5.4.
+ *
+ * Implements `canonicalize(expr)` and `canonicalJson(expr)` for the TypeScript
+ * binding. Integer-vs-float AST-node distinction is carried by the
+ * `NumericLiteral` tagged leaf (see `./numeric-literal.ts`); plain JS
+ * `number` values are treated as untagged float-like literals for backward
+ * compatibility with callers that have not migrated to `intLit` / `floatLit`.
+ *
+ * See `docs/rfcs/discretization.md` §5.4.1–§5.4.7 for the normative rules.
+ */
+
+/** `E_CANONICAL_NONFINITE` — NaN or ±Inf (§5.4.6). */
+declare const E_CANONICAL_NONFINITE = "E_CANONICAL_NONFINITE";
+/** `E_CANONICAL_DIVBY_ZERO` — `/(0, 0)` (§5.4.7). */
+declare const E_CANONICAL_DIVBY_ZERO = "E_CANONICAL_DIVBY_ZERO";
+/** Canonicalize an expression tree per RFC §5.4. Input is not mutated. */
+declare function canonicalize(expr: Expr): Expr;
+/**
+ * Emit canonical on-wire JSON per §5.4.6 (sorted keys, no whitespace).
+ *
+ * FAIL-CLOSED (matching the Julia reference): `canonicalize` PRESERVES every
+ * node field, then this validates the canonicalized tree and throws
+ * `E_CANONICAL_UNSUPPORTED_FIELD` if any node carries an own key (with a defined
+ * value) outside the emissible ∪ tolerated set. A node carrying a non-emissible
+ * aggregate/geometry field has NO faithful canonical JSON — emitting only the
+ * pinned fields would collapse structurally-different nodes to identical bytes.
+ */
+declare function canonicalJson(expr: Expr): string;
+/**
+ * Format a finite `number` as a byte-CANONICAL float token per RFC §5.4.6.
+ * Only handles float-typed values: integer-typed `NumericLiteral` nodes are
+ * emitted as bare JSON integers by {@link canonicalJson} directly.
+ *
+ * NAMING: distinct from `formatFloatToken` in `./numeric-literal` (the
+ * document-serialization emitter used by `save()` / `losslessJsonStringify`).
+ * This canonical version additionally NORMALIZES exponent notation — it strips
+ * the leading `+` (RFC §5.4.6: "no leading + on the exponent") so `1e25` emits
+ * as `1e25`, not `1e+25`, and forces the §5.4.6 exponent thresholds. Use this
+ * one for canonical output, `formatFloatToken` for wire round-trip.
+ */
+declare function formatCanonicalFloat(f: number): string;
+
+/**
+ * Closed function registry — TypeScript binding for esm-spec §9.2.
+ *
+ * v0.3.0 set:
+ *  - datetime.year / .month / .day / .hour / .minute / .second
+ *  - datetime.day_of_year / .julian_day / .is_leap_year
+ *  - interp.searchsorted
+ *  - interp.linear, interp.bilinear (named tensor-interpolation primitives, esm-94w)
+ *
+ * The dispatch table is closed by construction. `fn`-op nodes whose name
+ * is not in this set MUST be rejected with diagnostic
+ * `unknown_closed_function`.
+ *
+ * Boundary semantics, tolerances, and error codes match the Julia
+ * reference implementation (pkg/EarthSciAST.jl/src/registered_functions.jl).
+ */
+/** Stable diagnostic codes raised by the registry. */
+type ClosedFunctionErrorCode = 'unknown_closed_function' | 'closed_function_arity' | 'closed_function_overflow' | 'searchsorted_non_monotonic' | 'searchsorted_nan_in_table' | 'interp_non_monotonic_axis' | 'interp_axis_length_mismatch' | 'interp_nan_in_axis' | 'interp_axis_too_short' | 'interp_table_not_const' | 'interp_axis_not_const';
+/**
+ * Error thrown by closed function dispatch and load-time table validation.
+ * `code` identifies the spec-pinned diagnostic; cross-binding harnesses
+ * compare against this exact string.
+ */
+declare class ClosedFunctionError extends Error {
+    code: ClosedFunctionErrorCode;
+    constructor(code: ClosedFunctionErrorCode, message: string);
+}
+/**
+ * Validate a `searchsorted` xs table. Throws on NaN entries or
+ * non-monotonic order. Empty arrays are rejected with the spec arity
+ * code (the registry requires N ≥ 1).
+ */
+declare function validateSearchsortedTable(xs: readonly number[], where?: string): void;
+/**
+ * Smallest 1-based `i` with `xs[i] ≥ x` (Julia `searchsortedfirst`
+ * semantics). NaN x → N+1. xs MUST be pre-validated; the table is
+ * inspected at every call so the caller can pass a fresh array each
+ * scenario without bookkeeping (validation is cheap relative to the
+ * dispatch overhead).
+ */
+declare function searchsortedFirst(x: number, xs: readonly number[]): number;
+/**
+ * Validate a 1-D interpolation axis (`interp.linear` / `interp.bilinear`).
+ * Strictly increasing, no NaN, length ≥ 2. Diagnostic codes match
+ * esm-spec §9.2 "Errors (load time)" table.
+ */
+declare function validateInterpAxis(axis: readonly number[], where: string): void;
+/**
+ * 1-D linear interpolation with extrapolate-flat clamps. Pinned form
+ * `result = t[i] + w * (t[i+1] - t[i])` so that w=0/1 reproduce the
+ * endpoint exactly under IEEE-754 round-to-nearest.
+ *
+ * Validates `axis` on every call (cheap relative to dispatch overhead;
+ * matches the `searchsortedFirst` convention in this module).
+ */
+declare function interpLinear(table: readonly number[], axis: readonly number[], x: number): number;
+/**
+ * 2-D bilinear interpolation with per-axis extrapolate-flat clamps.
+ * Pinned evaluation order: two x-blends followed by one y-blend, each
+ * in the form `a + w*(b - a)` (esm-spec §9.2). `table` is row-major:
+ * `table[i][j]` is the value at `(axis_x[i], axis_y[j])`.
+ */
+declare function interpBilinear(table: readonly (readonly number[])[], axisX: readonly number[], axisY: readonly number[], x: number, y: number): number;
+/** Names that bindings MUST recognize (derived from the dispatch table keys). */
+declare const CLOSED_FUNCTION_NAMES: readonly string[];
+/**
+ * Resolve a closed-function name + already-evaluated positional args into a
+ * scalar result via {@link CLOSED_FUNCTION_DISPATCH}. Unknown names raise
+ * `unknown_closed_function`.
+ */
+declare function dispatchClosedFunction(name: string, args: unknown[]): number;
+
+/**
+ * Load-time enum lowering pass — esm-spec §9.3.
+ *
+ * Walks the AST of a parsed EsmFile and rewrites every
+ * `{op: "enum", args: [enum_name, member_name]}` node into the
+ * equivalent `{op: "const", args: [], value: <integer>}` node, using the
+ * file-local `enums` block to resolve the symbol.
+ *
+ * The pass is a no-op when no `enums` block is present. After lowering,
+ * the file's expression trees contain no `enum` ops; the codegen
+ * runner (`compileExpression` / `evaluateExpression`) sees only
+ * `const`. Mirrors the Julia `lower_enums!` pass.
+ *
+ * Errors are `EnumLoweringError`s carrying stable, registry-backed diagnostic
+ * codes (see `errors.ts` `ERROR_CODES`, mirrored by the Python `ErrorCode`
+ * enum):
+ *   - `enum_op_malformed` — an `enum` op whose args are not
+ *     `[enum_name, member_name]` (two strings).
+ *   - `enum_not_declared` — reference to an enum name not present in the file's
+ *     top-level `enums` block.
+ *   - `enum_member_not_found` — reference to an unknown member of a declared
+ *     enum.
+ */
+
+declare class EnumLoweringError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Resolve every `enum` op in `file` against `file.enums`. Returns the
+ * (possibly identical) input — the rewrite is structural, immutable:
+ * unchanged subtrees are shared with the input.
+ */
+declare function lowerEnums(file: EsmFile): EsmFile;
+
+/**
+ * Neutral base for EarthSciAST diagnostics: an `Error` carrying a stable `code`
+ * string (from {@link ERROR_CODES}) and optional structured `details`. This is
+ * purely additive — a single home for future diagnostics. It intentionally does
+ * NOT touch the existing `EsmMachineryError` / `EnumLoweringError` /
+ * `ClosedFunctionError` classes, which another file owns.
+ */
+declare class EsmDiagnosticError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, details?: Record<string, unknown> | undefined);
+}
+
+/**
+ * Load-time rewrite pass for `expression_templates` (esm-spec §9.6 /
+ * docs/rfcs/ast-expression-templates.md, docs/rfcs/open-op-namespace-fixpoint-rewrite.md).
+ *
+ * An `expression_templates` entry is a **rewrite rule** with `params`
+ * (metavariables), a `body` (the replacement Expression), an optional
+ * integer `priority`, and an optional `match` pattern. This single engine
+ * covers both application modes:
+ *
+ *   - **No `match`** — the entry is applied only by an explicit
+ *     `apply_expression_template` node that names it and supplies
+ *     per-parameter `bindings` (named-template expansion).
+ *   - **With `match`** — the entry is an *auto-applied* rewrite rule.
+ *     `match` is a pattern Expression in which the params are wildcards:
+ *     a param in an operand/`args` position binds to the matched sub-AST;
+ *     a param in a scalar field (e.g. `dim`, `side`, or a custom `attrs.<key>`)
+ *     binds to the matched literal. The rule fires wherever the pattern
+ *     structurally matches a node.
+ *
+ * Rewriting is an **outermost-first, priority-ordered, bounded-fixpoint**
+ * process (esm-spec §9.6.3; mirrors the Julia reference `_rewrite_pass` /
+ * `_rewrite_to_fixpoint`). Rule application proceeds in **passes**; one pass
+ * (`onePass`) is a single **pre-order (outermost-first)** walk of the tree. At
+ * each node visited the engine first tries to fire a rule AT that node before
+ * descending: an `apply_expression_template` op is expanded (counts as a
+ * rewrite), otherwise the structurally-matching `match` rule of highest
+ * `priority` (integer, default 0; ties broken by DECLARATION order) fires. A
+ * fired rule's `body` replaces the node and the walk does **not** descend into
+ * that freshly-produced body during the current pass (it is revisited next
+ * pass). If nothing fires, the walk descends into children. Passes repeat until
+ * a pass performs **zero** rewrites (the fixpoint) or until
+ * `MAX_REWRITE_PASSES = 64` productive passes have run without converging, in
+ * which case the file is rejected with `rewrite_rule_nonterminating`. The pass
+ * bound — NOT a static check — is the authoritative termination guard, so a
+ * self-reintroducing rule simply fails to converge. Because selection and
+ * traversal are fully deterministic, all bindings produce byte-identical
+ * fixpoints.
+ *
+ * After convergence the component carries no `expression_templates` block and
+ * no `apply_expression_template` ops — downstream consumers see only normal
+ * Expression ASTs (Option A round-trip). Any rewrite-target op (e.g. a spatial
+ * `D`) that survives the fixpoint into an evaluation position is caught later by
+ * the `unlowered_operator` gate (`evaluateExpression`), not here.
+ *
+ * Operates on the pre-coercion JSON view (plain objects) — runs in
+ * `load()` after schema validation but before typed coercion.
+ *
+ * Errors (raised directly by this file; the code STRINGS live in
+ * `./errors.js` `ERROR_CODES`):
+ *   - apply_expression_template_unknown_template
+ *   - apply_expression_template_bindings_mismatch
+ *   - apply_expression_template_recursive_body
+ *   - apply_expression_template_version_too_old
+ *   - apply_expression_template_invalid_declaration
+ *   - rewrite_rule_nonterminating
+ *   - template_constraint_unknown_index_set   (§9.6.1 `where` registration)
+ *   - geometry_manifold_invalid               (§9.6.4 expanded-form validator)
+ *   - makearray_region_inverted               (§9.6.4 expanded-form validator)
+ *
+ * plus the esm-spec §9.7 template-library / metaparameter codes (§9.6.6,
+ * raised from `template-imports.ts` and `ref-loading.ts`):
+ *
+ *   - template_import_version_too_old
+ *   - template_import_unresolved
+ *   - template_import_not_library
+ *   - subsystem_ref_is_template_library
+ *   - template_import_cycle
+ *   - template_import_name_conflict
+ *   - template_import_unknown_name
+ *   - template_import_index_set_conflict
+ *   - template_body_expansion_too_deep
+ *   - metaparameter_unbound
+ *   - metaparameter_type_error
+ *   - metaparameter_name_conflict
+ */
+
+/**
+ * Shared load-time diagnostic for the §9.x machinery: expression-template
+ * lowering (§9.6), template-library imports (§9.7), coupling-library imports
+ * (§10.10), subsystem-ref loading, and the §9.6.4 expanded-form validators all
+ * raise it as their common coded-diagnostic class — validate.ts maps it (by
+ * `instanceof`) to the `expression_template_error` load-error kind. Extends the
+ * neutral {@link EsmDiagnosticError} additively: the `(code, message)`
+ * constructor signature, the `[code] message` text, and the public `code`
+ * string property are all preserved byte-for-byte, so the emitted diagnostic is
+ * unchanged and every `instanceof` check is unaffected.
+ */
+declare class EsmMachineryError extends EsmDiagnosticError {
+    constructor(code: string, message: string);
+}
+
+/**
+ * Maximum template-body reference-chain depth (counted in TEMPLATES along the
+ * longest chain, so a 33-template chain is rejected while a 32-template chain
+ * is accepted) before a file is rejected with
+ * `template_body_expansion_too_deep` (esm-spec §9.7.3). Pinned identically
+ * across all bindings.
+ */
+declare const MAX_TEMPLATE_EXPANSION_DEPTH = 32;
+/**
+ * Reject `apply_expression_template` and `expression_templates` in files
+ * declaring `esm` < 0.4.0. Operates on the pre-coercion JSON view.
+ */
+declare function rejectExpressionTemplatesPreV04(view: unknown): void;
+/**
+ * Load the file under Option B (reference preservation, esm-spec §9.6.4): fire
+ * auto-applied `match` rules and eagerly expand target-bearing references to a
+ * fixpoint per component (outermost-first, priority-ordered, bounded — §9.6.3),
+ * but leave NON-eager `apply_expression_template` references intact (they
+ * denote their expansion, §9.6.4 rule 2). The per-component
+ * `expression_templates` registries are RETAINED — they are what {@link
+ * expandDocument} consumes (rule 2) and emit materializes (rule 5). Call-site
+ * checks (§9.6.9), the reference-aware geometry-manifold check, and the
+ * registration-time makearray-region check run on the reference-preserving form.
+ *
+ * Returns a new file object; the input is not mutated.
+ *
+ * Pre-condition: the input has been schema-validated.
+ */
+declare function lowerExpressionTemplates<T extends object>(file: T): T;
+/**
+ * Fully expand every surviving `apply_expression_template` reference in a
+ * document `loaded` by {@link lowerExpressionTemplates} (Option B), producing
+ * the Option-A image: every reference replaced by its expansion (pure
+ * substitution to the acyclic fixpoint, §9.6.4 rule 2) and every per-component
+ * `expression_templates` block stripped. Deterministic — the §9.7.3 DAG is
+ * acyclic and substitution confluent, so `expandDocument(load(f))` is
+ * structurally equal to the pre-0.9.0 expanded form (the `expanded*.esm`
+ * conformance oracle). Non-destructive: `loaded` is deep-cloned first. Mirrors
+ * the Julia reference `expand_document` / `Expand`.
+ */
+declare function expandDocument<T extends object>(loaded: T): T;
+
+/**
+ * Per-component MATCH-LESS template names authored in-file in `rawSource`
+ * (`compKind.cname` → ordered names). Emit keeps these verbatim as authored
+ * entries (esm-spec §9.6.4 rule 5); imported/derived templates are materialized
+ * instead. Mirrors the Julia reference `_authored_template_names`.
+ */
+declare function authoredTemplateNames(rawSource: unknown): Record<string, string[]>;
+/**
+ * Build the reference-preserving, self-contained emitted document (esm-spec
+ * §9.6.4 rule 5, §7.5) from an already Option-B-loaded document `loaded` and
+ * the authored-name map from the pristine source. For every component builds
+ * its emitted `expression_templates` block — authored match-less entries first
+ * in authored order, then the materialized transitive closure of its surviving
+ * references (match-less), lexicographically sorted — drops consumed
+ * `expression_template_imports`, and version-stamps `esm: 0.9.0` when any
+ * surviving reference or materialized entry remains (§9.6.4 rule 8). Mutates
+ * and returns `loaded`. Mirrors the Julia reference `emit_document` tail.
+ */
+declare function buildEmittedDocument(loaded: Record<string, unknown>, authored: Record<string, string[]>): Record<string, unknown>;
+/**
+ * Canonical byte serialization of an emitted document (esm-spec §9.6.4 rule 5):
+ * 2-space indent, object keys sorted lexicographically (UTF-8 byte order)
+ * EXCEPT the entries of an `expression_templates` object, which preserve their
+ * authored-first / materialized-sorted order. The cross-binding byte-identity
+ * surface for the Option-B emitted form and the target of the `emitted.esm`
+ * goldens. Mirrors the Julia reference `emit_esm_string`.
+ */
+declare function emitEsmString(doc: unknown): string;
+/** Result of {@link flattenTemplateRegistries}: the rewritten document + merged registry. */
+interface FlattenedTemplateRegistries {
+    root: Record<string, unknown>;
+    merged: Record<string, unknown>;
+}
+/**
+ * The flatten-time template-registry merge (esm-spec §9.6.4 rule 7, §10.7;
+ * esm-libraries-spec §4.7.5 step 4). Given an Option-B loaded multi-component
+ * document `loaded`, merge every component's match-less `expression_templates`
+ * registry into a single document-scoped merged registry:
+ *
+ *  - **Deep-equal dedup at first occurrence** — two components importing one
+ *    stencil produce identical folded bodies, kept once under the bare name.
+ *  - **Non-deep-equal same-name collision** — both entries are renamed
+ *    deterministically to `<ComponentPath>.<name>` and their
+ *    `apply_expression_template` references are rewritten in lockstep.
+ *  - **Collisions propagate along the reference DAG** — a declaration that
+ *    references a colliding name collides too (see
+ *    {@link registryCollisionNames}), so a byte-identical wrapper over a
+ *    per-component leaf is renamed per owner rather than deduped into one body
+ *    whose nested reference no longer resolves.
+ *
+ * Returns the rewritten document `root` (component reference sites updated) and
+ * the merged registry (the FlattenedSystem's first-class registry field).
+ * `match` rules are not merged (only match-less templates are referenceable).
+ * Mirrors the Julia reference `flatten_template_registries`.
+ */
+declare function flattenTemplateRegistries(loaded: object): FlattenedTemplateRegistries;
+
+type JsonObject = Record<string, unknown>;
+/** Schema-error shape accepted from the host's schema validator. */
+interface TemplateSchemaError {
+    path: string;
+    message: string;
+}
+/** Options threaded through §9.7 resolution. */
+interface TemplateResolveOptions {
+    /**
+     * Loader-API metaparameter bindings for the ROOT document
+     * (esm-spec §9.7.6 binding site 4). Already-closed edge bindings win;
+     * API bindings beat `default`s.
+     */
+    metaparameters?: Record<string, number> | undefined;
+    /**
+     * Synchronous file reader for import refs. Defaults to Node's
+     * `fs.readFileSync` (via `process.getBuiltinModule`); browser hosts must
+     * supply their own.
+     */
+    readFile?: ((path: string) => string) | undefined;
+    /**
+     * Schema validator applied to each import target (a target failing schema
+     * validation is `template_import_unresolved`, mirroring the Julia
+     * reference). Supplied by `load()`; optional for direct/raw use.
+     */
+    validateSchema?: ((raw: unknown) => TemplateSchemaError[]) | undefined;
+}
+/**
+ * `expression_template_imports`, top-level `expression_templates`
+ * (template-library files), and `metaparameters` arrive at `esm: 0.8.0`;
+ * files declaring an earlier version that carry any of them are rejected
+ * with `template_import_version_too_old` (esm-spec §9.6.5). Mirrors
+ * `rejectExpressionTemplatesPreV04` for the §9.7 constructs.
+ */
+declare function rejectTemplateImportsPreV08(view: unknown): void;
+/**
+ * True when `raw` has the template-library-file FORM (top-level
+ * `expression_templates`, esm-spec §9.7.1). Purity (no models / reaction
+ * systems / loaders / coupling / domain) is checked separately at import
+ * edges.
+ */
+declare function isTemplateLibraryDoc(raw: unknown): boolean;
+/**
+ * Resolve every esm-spec §9.7 construct of the ROOT document `rawData`
+ * (relative import refs resolve against `basePath`): imports recursively
+ * with per-edge instantiation, `index_sets` merge, metaparameter close
+ * (`options.metaparameters` is the loader-API binding site 4;
+ * already-closed edge bindings win, then API bindings, then defaults) and
+ * fold, expression-position substitution, and — for a root library file —
+ * §9.7.3 body composition.
+ *
+ * Returns an order-preserving plain-object tree ready for
+ * `lowerExpressionTemplates` with `expression_template_imports`,
+ * `metaparameters`, and top-level `expression_templates` consumed (Option A
+ * round-trip: none survives `parse → emit`), or `null` when the document
+ * carries no §9.7 machinery (the legacy fast path).
+ */
+declare function resolveTemplateMachinery(rawData: unknown, basePath: string, options?: TemplateResolveOptions): JsonObject | null;
+/**
+ * Produce the reference-preserving, self-contained emitted document (esm-spec
+ * §9.6.4 rule 5, RFC out-of-line-expression-templates §7.5) from a source
+ * document `rawSource` (a fixture, or an already-emitted document for the
+ * idempotency property; relative import refs resolve against `basePath`). Loads
+ * `rawSource` under Option B, then materializes each component's surviving
+ * reference closure into its `expression_templates` block, drops consumed
+ * imports, and version-stamps `esm: 0.9.0` when any reference/materialized entry
+ * remains (§9.6.4 rule 8). `emitEsmString ∘ emitDocument` is a byte-wise fixed
+ * point under reload. Mirrors the Julia reference `emit_document`.
+ */
+declare function emitDocument(rawSource: unknown, basePath: string, options?: TemplateResolveOptions): JsonObject;
+/**
+ * esm-spec §9.7.10 forms A + B: if `raw` needs a scope-directed injection (a
+ * non-empty subsystem-ref edge list `injected`, or a coupling entry carrying
+ * an injection map), return a fresh plain-object tree with the injected
+ * imports folded into the target components' own `expression_template_imports`,
+ * ready for `resolveTemplateMachinery`. Returns `null` when no injection
+ * applies, so the caller keeps its original fast path.
+ */
+declare function applyScopeInjections(raw: unknown, injected?: readonly unknown[]): JsonObject | null;
+
+export { CLOSED_FUNCTION_NAMES, CadenceCycleError, CadenceSeeder, CanonicalNonfiniteError, CanonicalizeError, CircularReferenceError, ClosedFunctionError, DEFAULT_MIN_COMPLEXITY, E_CANONICAL_DIVBY_ZERO, E_CANONICAL_NONFINITE, EntityNotFoundError, EnumLoweringError, EsmMachineryError, EvaluatorError, expandDocument as Expand, ExpressionAnalyzer, ExpressionParseError, EsmMachineryError as ExpressionTemplateError, InvalidDerivativeOrderError, LosslessJsonParseError, MAX_TEMPLATE_EXPANSION_DEPTH, MigrationError, NonDifferentiableExpressionError, ParseError, RefLoadError, SCHEMA_VERSION, SchemaValidationError, UnitConversionError, UnloweredOperatorError, SCHEMA_VERSION as VERSION, VariableInUseError, addContinuousEvent, addCoupling, addDiscreteEvent, addEquation, addReaction, addSpecies, addVariable, algebraicUnknowns, analyzeComplexity, analyzeExpression, applyScopeInjections, authoredTemplateNames, brownianParameters, buildDependencyGraph, buildEmittedDocument, canMigrate, canonicalJson, canonicalize, checkDimensions, classifyComplexity, classifyDocument, classifyModel, compareComplexity, compileExpression, componentExists, componentGraph, component_graph, compose, constantParameters, contains, convertUnits, declaredSystemKind, deriveODEs, detectStabilityIssues, differentiate, discreteParameters, dispatchClosedFunction, emitDocument, emitEsmString, ephemeralInjectedFile, estimateParallelPotential, estimateSavings, evaluateExpression, expandCouplingImports, expandDocument, expressionCadence, expressionGraph, extract, findCommonSubexpressions, findCommonSubexpressionsAcrossExpressions, findCommonSubexpressionsInEsmFile, findCommonSubexpressionsInModel, findCriticalPoints, findDeadVariables, findDependencyChains, findExpensiveSubexpressions, flatten, flattenTemplateRegistries, floatLit, formatCanonicalFloat, formatChemicalName, formatFloatToken, freeParameters, freeVariables, generateFactoredVariableNames, getComponentType, getSupportedMigrationTargets, gradient, groupSubexpressionsByType, higherOrderDerivative, intLit, interpBilinear, interpLinear, isCouplingLibraryDoc, isDifferentiable, isFloatLit, isIntLit, isNumericLiteral, isOdeState, isTemplateLibraryDoc, joinAll, joinCadence, leafCadence, load, losslessJsonParse, losslessJsonStringify, lowerEnums, lowerExpressionTemplates, mapVariable, merge, migrate, numericValue, observedDefinitions, observedUnknowns, odeStates, parameterClass, parameters, parseEquation, parseExpression, parseReaction, parseUnit, parseUnitForConversion, partialDerivatives, productMatrix, rejectExpressionTemplatesPreV04, rejectTemplateImportsPreV08, removeCoupling, removeEquation, removeEvent, removeReaction, removeSpecies, removeVariable, renameVariable, resolveSubsystemRefs, resolveTemplateMachinery, sampledParameters, save, searchsortedFirst, simplify, stoichiometricMatrix, substitute, substituteInEquations, substituteInModel, substituteInReactionSystem, substrateMatrix, systemKind, toAscii, toDot, toJsonGraph, toLatex, toMathML, toMermaid, toUnicode, tryParseUnit, unitsCompatible, unknowns, updateRules, validate, validateInterpAxis, validateSchema, validateSearchsortedTable, validateUnits };
+export type { AffectEquation, Analysis, AnalysisOptions, AnalysisResults, Assertion, Assertion1, CadenceClass, CanonicalDims, ClosedFunctionErrorCode, CommonSubexpression, CompiledExpression, ComplexityMetrics, ComponentGraph, ComponentNode, ConditionUpdate, ConnectorEquation, ContinuousEvent, Coordinate, Coordinate1, CouplingCallback, CouplingCouple, CouplingEdge, CouplingEntry, CouplingEvent, CouplingEvent1, CouplingImport, CouplingImportOptions, CouplingOperatorCompose, CouplingVariableMap, CouplingVariableMap1, CovarianceMatrix, CrossingUpdate, DataSource, DataSourceBinding, DataSourceCodes, DataSourceDeterminism, DataSourceExtent, DataSourceLocation, DataSourceRecordFilter, DataSourceSelect, DataSourceSelectAxis, DataSourceTemporal, DataUpdate, DependencyEdge, DependencyGraph, DependencyNode, DependencyRelation, DerivativeResult, DiscreteEvent, DiscreteEventTrigger, Distribution, Domain, ESMFormat, ESMFormat1, ESMFormat2, EnumDeclaration, Equation, EsmFile, EsmFormat, Expr, ExprNode, ExprNodeOf, Expression, ExpressionLocation, ExpressionNode, ExpressionNode1, ExpressionTemplate, FlattenMetadata, FlattenOptions, FlattenedEquation, FlattenedSystem, FlattenedTemplateRegistries, FunctionTable, FunctionTableAxis, FunctionalUpdate, Graph, IndexSet, IndexSet1, LoadOptions, LognormalDistribution, Metadata, MetaparameterExpression, Metaparameters, Model, ModelClassification, ModelVariable, ModelVariable1, NonWienerParameterUpdate, NormalDistribution, NumericLiteral, Parameter, Parameter1, ParameterClass, ParameterSweep, ParameterUpdate, ParameterUpdateSpec, ParsedUnit, Plot, Plot1, PlotAxis, PlotSeries, PlotValue, Reaction, ReactionSystem, Reference, RemeshUpdate, SaveOptions, ScheduleUpdate, SchemaError, Species, StabilityIssue, StoichiometryEntry, SubsystemRef, SweepDimension, SweepDimension1, SweepRange, SystemKind, TemplateImport, TemplateResolveOptions, TemplateSchemaError, Test, TimeSpan, Tolerance, Tolerance1, Tolerance2, Tolerance3, TranslateTarget, UniformDistribution, UnitResult, UnitWarning, UnknownClass, UpdateValueForm, ValidationError, ValidationResult, VariableKind, VariableNode, WienerUpdate };