@earthsciml/ast 0.1.1 → 0.3.0

package/dist/esm/index.d.ts

@@ -4,7 +4,7 @@
  * 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.
+ * EarthSciML Abstract Syntax Tree Format — v1.2.0 adds an OPTIONAL declared `units` string on a `const` expression node (esm-spec §4.8.5): the unit the constant's value is in, so a conversion constant such as `{"op": "const", "args": [], "value": 0.44704, "units": "m*h/(mi*s)"}` makes its equation dimensionally checkable. Purely additive: `units` is legal on no other node, and a document declaring esm below 1.2.0 that carries it is rejected with `const_units_version_too_old`. v1.1.0 renames the unified query node from `aggregate` to `faq`, the Functional Aggregate Query it has always been (docs/content/rfcs/faq-node-rename.md). `aggregate` names only one of the node's specializations: it also joins, filters, and — under `bool_and_or` with `distinct` — produces an index set rather than an array, reducing nothing. `faq` is the canonical tag; `aggregate` is accepted as a DEPRECATED ALIAS, normalized to `faq` at load with the warning `deprecated_op_alias`, and REMOVED at esm 2.0.0. The text surface is unchanged: the head keyword there is the ⊕-word (`sum`/`prod`/`max`/`min`/`any`), not the node name. The `arrayop` alias — nominally removed at 0.8.0 but still live in all five bindings — is removed for real. Also at v1.1.0: the top-level `solver` block. (v1.0.0) — a `faq`'s `join` clause carries the optional `syms`, naming the two RANGE SYMBOLS its `on` pairs are read at, so a relation can be joined to ITSELF: two ranges over one index set, whose key columns' shared axis cannot say which side is which (CONFORMANCE_SPEC §5.5.8, docs/content/rfcs/self-join-two-ranges-over-one-index-set.md). Purely additive — every document written before it stays valid and unchanged, which is why it lands without a version bump; see that note's §4. 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 (`faq`) 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 `faq` nodes (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, `faq` 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 = {
@@ -20,13 +20,17 @@ type ModelVariable$1 = ModelVariable1 & {
     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.
+     * For an unknown, its initial value at t=0. For a parameter, its constant value — mutually exclusive with `distribution`, which draws the value instead. A SHAPED variable (non-empty `shape`) may instead carry a row-major nested JSON array whose nesting matches the declared shape after metaparameter folding; a mismatch is a load-time error. A scalar on a shaped variable keeps its broadcast meaning — the one value applies to every element (esm-spec §6.3).
      */
-    default?: number;
+    default?: number | NumericArrayLiteral;
     /**
      * 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;
+    /**
+     * Floating-point precision of THIS variable and of the arithmetic over it, overriding the document-wide `domain.element_type` (esm-spec §11.3.1). It exists for the key/quantity split one document-wide precision cannot express: a relational model whose floating-point QUANTITIES are binary32 still has join keys and integer identifiers binary32 cannot represent (a ten-digit category code is ~2.26e9, 135x binary32's exact-integer limit of 2^24), so the keys declare `Float64` while the quantities follow the document. Precision propagates from the leaves: an operator evaluates at its operands' precision, a numeric literal adopts its context's, and an operator whose operands carry DIFFERENT precisions is an error naming both variables — never a silent widening. Omitted means the document's `domain.element_type`.
+     */
+    element_type?: "Float32" | "Float64";
     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.
@@ -64,6 +68,10 @@ type ModelVariable$1 = ModelVariable1 & {
 type ModelVariable1 = {
     [k: string]: unknown;
 };
+/**
+ * A row-major nested JSON array of numbers carrying a SHAPED variable's inline data (esm-spec §6.3, §6.6.2). Every axis is a JSON array and every leaf a number; the nesting depth and the per-axis lengths MUST match the variable's declared `shape` after metaparameter folding, and a mismatch is a load-time error — the same convention `from_file` data already follows (§6.6.5 convention 3). A SCALAR in the same position keeps its broadcast meaning (one value applied to every element).
+ */
+type NumericArrayLiteral = (number | NumericArrayLiteral)[];
 /**
  * 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).
  */
@@ -81,11 +89,11 @@ type Expression = number | string | ExpressionNode;
  */
 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.
+     * Operator name. TWO TIERS (esm-spec §4.2). (1) The CLOSED evaluable-core set — every binding's evaluator implements each one directly: `+ - * / ^` and `pow` (the word spelling of `^`), 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`, the boolean literals `true` and `false`, and the array/query ops (`faq 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. The array/query node `faq` is a FUNCTIONAL AGGREGATE QUERY (docs/content/rfcs/semiring-faq-unified-ir.md): a semiring reduction of a body over named index sets, carrying joins, filters and set semantics, so under `bool_and_or` + `distinct` it produces an INDEX SET rather than an array and reduces nothing. DEPRECATED ALIAS: `aggregate` is the pre-1.1.0 spelling of `faq`. A loader MUST accept it, MUST normalize the node to `faq` before validation so that nothing downstream of the loader sees the alias, and MUST report the warning diagnostic `deprecated_op_alias` once per document per alias. It is REMOVED at esm 2.0.0 (docs/content/rfcs/faq-node-rename.md). The older `arrayop` spelling is NOT accepted. It was removed at 0.8.0 and is rejected BY NAME with the hard error `removed_op` — NOT left to the open tier: `arrayop` is a well-formed identifier, so the open rewrite-target tier would otherwise admit it and the document would load silently, failing much later as `unlowered_operator`, or never. A loader MUST also reject a document that spells `faq` while declaring esm < 1.1.0 (`faq_version_too_old`), the same version gate the top-level `solver` block follows; the gate reads the AUTHORED form, so a pre-1.1.0 document carrying the `aggregate` alias stays legal and is normalized with its declared version raised to the 1.1.0 floor.
      */
     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.
+     * 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 `faq` node that materializes it — and it names it by this id. When present it MUST be unique among the expression nodes of its DOCUMENT — `index_sets` is a document-scoped registry, so a `from_faq` in it resolves against every model's nodes, and per-model uniqueness would leave a cross-model reference ambiguous. The build-time reference-resolution pass errors on a duplicate id and on a `from_faq` that names no node in the document. 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;
     /**
@@ -93,7 +101,7 @@ type ExpressionNode = ExpressionNode1 & {
      */
     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.
+     * Operand list. For most ops these are sub-expressions. Array ops use args for the input array operands (faq, 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
      */
@@ -125,7 +133,7 @@ type ExpressionNode = ExpressionNode1 & {
      */
     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.
+     * For faq: 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)[];
     /**
@@ -133,15 +141,15 @@ type ExpressionNode = ExpressionNode1 & {
      */
     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".
+     * For faq: 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).
+     * For faq: 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.
+     * For faq: 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] | {
@@ -150,13 +158,13 @@ type ExpressionNode = ExpressionNode1 & {
              */
             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).
+             * Parent index name(s) for a ragged / dependent inner set: the enumeration depends on these outer indices (e.g. { "from": "edges_of_cell", "of": ["i"] } iterates the POSITIONS k in 1…offsets[i] of cell i's edges, and the body gathers each edge as index(values, i, k); esm-spec §4.3.1 "Ragged ranges").
              */
             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.
+     * For faq: 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. A key column may name a loop symbol, an index set, or a genuine 1-D DATA COLUMN, and the resolved match set DRIVES enumeration rather than merely testing it (CONFORMANCE_SPEC §5.5.8).
      */
     join?: ({
         [k: string]: unknown;
@@ -168,7 +176,7 @@ type ExpressionNode = ExpressionNode1 & {
      */
     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.
+     * For faq: 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 `faq` 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;
     /**
@@ -216,7 +224,7 @@ type ExpressionNode = ExpressionNode1 & {
      */
     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.
+     * 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 (`faq 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;
     /**
@@ -229,6 +237,10 @@ type ExpressionNode = ExpressionNode1 & {
     value?: {
         [k: string]: unknown;
     };
+    /**
+     * For const only: the declared units of the constant's `value`, resolved against the esm-spec §4.8.1 registry with the §4.8.2 grammar exactly as a variable's `units` are. A unit-bearing constant has that dimension and exact scale in dimensional analysis (esm-spec §4.8.5); a `const` without `units`, like a bare numeric literal, stays undeterminable. The numeric value is never checked against the units. Legal on no other op. Arrives at esm 1.2.0 (`const_units_version_too_old`).
+     */
+    units?: string;
     /**
      * 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'.
      */
@@ -254,7 +266,7 @@ 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.
+ * 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`, `faq` 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: "+" | "-" | "*" | "/";
@@ -289,36 +301,7 @@ type DiscreteEventTrigger = {
     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`.
+ * 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 is valid only on a variable declared without a `shape` or on an element name such as `u[1]` (esm-spec §6.6.5). Error-norm reductions (L2_error, Linf_error) require `reference`.
  */
 type Assertion = Assertion1 & {
     /**
@@ -468,6 +451,35 @@ type Parameter = Parameter1 & {
 type Parameter1 = {
     [k: string]: unknown;
 };
+/**
+ * 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 closed value (esm-spec §9.7.6).
+         */
+        start?: number | string;
+        /**
+         * Exclusive last index. A string names a `metaparameters` entry and resolves to its closed value (esm-spec §9.7.6), 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 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`.
  */
@@ -558,11 +570,11 @@ type CouplingEvent = CouplingEvent1 & {
         times: [number, ...number[]];
     };
     /**
-     * Affect equations. Required unless functional_affect is used.
+     * Affect equations. Required: esm 1.0.0 removed the `functional_affect` alternative, so `affects` is the only affect channel. Every LHS MUST name an unknown (`event_affects_parameter` otherwise).
      */
     affects: AffectEquation[];
     affect_neg?: null | AffectEquation[];
-    root_find?: "left" | "right" | "all";
+    root_find?: "left" | "right";
     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.
@@ -578,15 +590,15 @@ type CouplingEvent1 = {
     [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.
+ * A named index set (RFC semiring-faq-unified-ir §5.2): the declaration shape for an iteration domain referenced from a `faq` 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.
+     * 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` `faq`, 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 an `offsets` per-parent length factor and a padded `values` member factor; a `faq` range over it binds the POSITION k in 1…offsets[parent] (esm-spec §4.3.1 "Ragged ranges").
      */
     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.
+     * 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`, `faq` 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: "+" | "-" | "*" | "/";
@@ -600,11 +612,11 @@ type IndexSet = IndexSet1 & {
      */
     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".
+     * derived: the id of the index-set-producing node (RFC §5.5) that materializes this set, named by its `id`. Usually a `faq` 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).
+     * 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 a `faq` ranging over the compact derived axis can gather the full-grid rows that axis selects. That is what downstream FAQ nodes do; it is not a claim about ORIENTATION — a `faq` 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` `faq`. 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;
     /**
@@ -612,11 +624,11 @@ type IndexSet = IndexSet1 & {
      */
     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".
+     * ragged: name of the keyed factor giving |set(i)| for each parent tuple — the per-parent LENGTH, not a cumulative offset (e.g. MPAS nEdgesOnCell). A `faq` range {"from": <this set>, "of": ["i"]} binds the POSITION k in 1…offsets[i] (esm-spec §4.3.1 "Ragged ranges"). 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".
+     * ragged: name of the keyed factor giving the member at (i, k) for k in 1…|set(i)| — a PADDED [parent, max length] array whose row i holds parent i's members in positions 1…offsets[i] (e.g. MPAS edgesOnCell); entries past offsets[i] are padding and are never read. Because a range over the set binds the position k, a `faq` body reads a member by gathering it explicitly, index(values, i, k); a body that never reads this array is `ragged_values_not_gathered`. The one exception is a value-invention `faq` (distinct / skolem / rank / argmin / argmax), whose ragged range binds the member values[i, k] itself (esm-spec §4.3.1 "Ragged ranges"). Required when kind is "ragged".
      */
     values?: string;
 };
@@ -678,7 +690,7 @@ interface ESMFormat2 {
         [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.
+     * File-local symbol-to-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 integers — any integer, negative, zero or positive, since an enum member is a categorical code rather than a 1-based position. 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;
@@ -695,7 +707,7 @@ interface ESMFormat2 {
         [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.
+     * 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. A `faq` 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;
@@ -706,6 +718,7 @@ interface ESMFormat2 {
     coordinates?: {
         [k: string]: Coordinate;
     };
+    solver?: Solver;
     /**
      * 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`).
      */
@@ -828,7 +841,7 @@ interface Model$1 {
      * 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;
+        [k: string]: Model$1 | SubsystemRef;
     };
     tolerance?: Tolerance;
     /**
@@ -915,136 +928,13 @@ interface ContinuousEvent {
     /**
      * Root-finding direction.
      */
-    root_find?: "left" | "right" | "all";
+    root_find?: "left" | "right";
     /**
      * 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.
  */
@@ -1071,6 +961,12 @@ interface SubsystemRef {
      * 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[];
+    /**
+     * Mount-edge index-set renaming (esm-spec §4.7 'Mount-edge index-set renaming'; docs/content/rfcs/mount-edge-index-set-renaming.md): a map from an index-set name AS THE RESOLVED MOUNTED DOCUMENT SPELLS IT to the name it takes in the mounting document. `index_sets` is a document-scoped registry, so two mounts that independently use one axis name at different lengths (a 59-layer atmospheric column and a 4-layer soil column both over `lev`) collide with subsystem_index_set_conflict; this field is the §9.7.7 renaming mechanism at a component-mount edge, restricted to index sets because they are the only declaration kind a mount contributes to document scope. Applied as ONE simultaneous substitution AFTER the referenced document resolves completely (its own imports, this edge's `bindings` and injection, its metaparameter close and the §9.6.3 fixpoint) and BEFORE its `index_sets` merge, transitively through every occurrence inside the mounted document — `index_sets` keys and ragged `of` lists, `{"from": …}` ranges, the `wrt`/`dim`/`var` axis scalars and bare-axis-name `integral` bounds, `where` `shape` constraints, variable/parameter `shape` lists, `Assertion.coords` keys, and `DataSourceSelectAxis.gated_by`. Keys must name an index set of the resolved mounted document (subsystem_index_set_rename_unknown_name); targets are dotted identifiers (template_import_rename_invalid) and must be distinct (template_import_rename_collision). The map need not be total: an unnamed axis passes through unrenamed, so a deliberately shared axis still merges deep-equal. Load-time only; consumed at the mount; does not survive parse→emit.
+     */
+    index_set_rename?: {
+        [k: string]: string;
+    };
 }
 /**
  * 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`).
@@ -1110,7 +1006,7 @@ interface TemplateImport {
     };
 }
 /**
- * Model-level default numerical tolerance for tests, used when a test or assertion does not provide its own.
+ * Model-level default numerical tolerance for tests. Resolution is PER FIELD over four levels (esm-spec 6.6.4): assertion, test, model, then the implementation default (rel = 1e-6, no abs bound). abs and rel each take their value from the innermost level that declares that field, so a test or assertion that declares only one bound does not mask the other from here. An explicit 0 is a declaration ('no bound of this kind'), not an absence, and stops the fallthrough - including the fallthrough to the implementation default, which is why rel: 0 is the only way to ask for an absolute-only comparison.
  */
 interface Tolerance {
     /**
@@ -1118,7 +1014,7 @@ interface Tolerance {
      */
     abs?: number;
     /**
-     * Relative tolerance: |actual - expected| / max(|expected|, epsilon) <= rel.
+     * Relative tolerance: |actual - expected| <= rel * max(|actual|, |expected|). Symmetric in actual and expected -- the scale is the larger of the two magnitudes, not |expected| alone.
      */
     rel?: number;
 }
@@ -1135,16 +1031,22 @@ interface Test {
      */
     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-value overrides for unknowns, keyed by variable name (local to this component). Values not listed fall back to the variable's declared default. A shaped unknown's value may be a row-major nested JSON array matching its declared shape (esm-spec §6.6.2).
      */
     initial_conditions?: {
-        [k: string]: number;
+        /**
+         * Initial value for one unknown: a number, or — for a SHAPED unknown — a row-major nested JSON array matching its declared shape after metaparameter folding (a mismatch is a load-time error). A scalar broadcasts to every element (esm-spec §6.6.2).
+         */
+        [k: string]: number | NumericArrayLiteral;
     };
     /**
-     * Parameter overrides, keyed by parameter name (local to this component). Values not listed fall back to the parameter's declared default.
+     * Parameter overrides, keyed by parameter name (local to this component). Values not listed fall back to the parameter's declared default. A shaped parameter's value may be a row-major nested JSON array matching its declared shape (esm-spec §6.6.2).
      */
     parameter_overrides?: {
-        [k: string]: number;
+        /**
+         * Value for one parameter: a number, or — for a SHAPED parameter — a row-major nested JSON array matching its declared shape after metaparameter folding (a mismatch is a load-time error). A scalar broadcasts to every element (esm-spec §6.6.2).
+         */
+        [k: string]: number | NumericArrayLiteral;
     };
     time_span: TimeSpan;
     tolerance?: Tolerance1;
@@ -1167,7 +1069,7 @@ interface TimeSpan {
     end: number;
 }
 /**
- * Test-level default tolerance applied to all assertions in this test that do not override it.
+ * Test-level default tolerance, merged PER FIELD (esm-spec 6.6.4): it supplies each of abs and rel that an assertion in this test does not declare, and falls through to the model-level default - and then to the implementation default rel = 1e-6 - for each field it does not declare itself. Write rel: 0 to stop that fallthrough.
  */
 interface Tolerance1 {
     /**
@@ -1175,12 +1077,12 @@ interface Tolerance1 {
      */
     abs?: number;
     /**
-     * Relative tolerance: |actual - expected| / max(|expected|, epsilon) <= rel.
+     * Relative tolerance: |actual - expected| <= rel * max(|actual|, |expected|). Symmetric in actual and expected -- the scale is the larger of the two magnitudes, not |expected| alone.
      */
     rel?: number;
 }
 /**
- * Per-assertion tolerance override. If present, this takes precedence over the test-level and model-level defaults.
+ * Per-assertion tolerance override, merged PER FIELD over the test-level and model-level defaults and then the implementation default (esm-spec 6.6.4): each of abs and rel that this object declares wins, and each it omits falls through independently. Declaring only abs here therefore keeps an outer rel rather than dropping it, and falls through to the implementation default rel = 1e-6 when no enclosing level declares one; write rel: 0 to mean 'no relative bound'.
  */
 interface Tolerance2 {
     /**
@@ -1188,7 +1090,7 @@ interface Tolerance2 {
      */
     abs?: number;
     /**
-     * Relative tolerance: |actual - expected| / max(|expected|, epsilon) <= rel.
+     * Relative tolerance: |actual - expected| <= rel * max(|actual|, |expected|). Symmetric in actual and expected -- the scale is the larger of the two magnitudes, not |expected| alone.
      */
     rel?: number;
 }
@@ -1298,7 +1200,7 @@ interface PlotSeries {
     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).
+ * 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'}` → a `faq`/`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 {
     /**
@@ -1434,7 +1336,7 @@ interface StoichiometryEntry {
     stoichiometry: number;
 }
 /**
- * System-level default numerical tolerance for tests, used when a test or assertion does not provide its own.
+ * System-level default numerical tolerance for tests. Resolution is PER FIELD over four levels (esm-spec 6.6.4): assertion, test, system, then the implementation default (rel = 1e-6, no abs bound). abs and rel each take their value from the innermost level that declares that field, so a test or assertion that declares only one bound does not mask the other from here. An explicit 0 is a declaration ('no bound of this kind'), not an absence, and stops the fallthrough - including the fallthrough to the implementation default, which is why rel: 0 is the only way to ask for an absolute-only comparison.
  */
 interface Tolerance3 {
     /**
@@ -1442,12 +1344,135 @@ interface Tolerance3 {
      */
     abs?: number;
     /**
-     * Relative tolerance: |actual - expected| / max(|expected|, epsilon) <= rel.
+     * Relative tolerance: |actual - expected| <= rel * max(|actual|, |expected|). Symmetric in actual and expected -- the scale is the larger of the two magnitudes, not |expected| alone.
      */
     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.
+ * 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 `faq` nodes 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 `faq` nodes 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 file-local enum mapping symbolic names to integers (esm-spec.md §9.3). The value domain is the WHOLE integer range — negative, zero and positive — because an enum member is a categorical CODE, not a position: it lowers to a `const` NUMBER used in arithmetic and in `join.on` key comparisons, where 0 and -1 are ordinary values (a source table's `opModeID = 0` or `polProcessID = -1` is a real code, not an absence). The two 1-based constructs in the format — `index`-op / index-set coordinates and `makearray` regions — are separate and carry their own bounds validation; using an enum member as an `index` argument is an authoring choice the index op bounds-checks, not a constraint on this block. 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;
@@ -1470,6 +1495,10 @@ interface CouplingOperatorCompose {
     translate?: {
         [k: string]: TranslateTarget;
     };
+    /**
+     * The entry's MERGE INTENT (esm-libraries-spec §4.7.1 step 5). TRI-STATE: absent is NOT the same as `false`, which is why this property declares no default. ABSENT — the author has not said; an entry that merges NOTHING is then `operator_compose_no_merge`, a hard refusal at flatten (such an entry is indistinguishable from one that is not there: the operator would integrate a private decoupled system from its own defaults and the other system would receive no contribution), while a PARTIAL merge is a warning. `true` — the `systems[1]` equations are CONTRIBUTIONS and every one of them whose LHS names a dependent variable MUST match an equation of `systems[0]`; any shortfall, PARTIAL included, is `operator_compose_require_match_unmatched`. There is no 'some is enough' reading. `false` — a standalone-contributing operator, DECLARED: unmatched equations are expected, are preserved per step 5, and nothing is reported.
+     */
+    require_match?: boolean;
     /**
      * Strategy for mapping between 0D and spatial systems.
      */
@@ -1653,7 +1682,28 @@ interface FunctionTableAxis {
     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`).
+ * Document-scoped, OPTIONAL solver hints (esm-spec §2.2): numerics the document knows about ITSELF, which each binding maps to its own integrator. Purely additive — a document without it validates, flattens and emits exactly as before. Every field is ADVISORY: a binding MAY ignore any or all of them and still conform. Advisory governs the MECHANISM, never the OUTCOME — a binding that ignores every field and still converges conforms; the requirement to integrate successfully and agree within the CONFORMANCE_SPEC §5.9 error band is untouched by this block and is not excused by it. What IS normative: parse it, validate it, round-trip it VERBATIM (it is authored configuration, a peer of `tolerance` and `parameter_overrides` — not a load-time construct like `expression_template_imports`), leave the flattened system unchanged, and reject it in a document declaring `esm` below 1.1.0 with `solver_version_too_old`. This block is NOT for algorithm names (`BDF`/`LSODA`/`Rosenbrock23` are per-binding identifiers and would not be portable — there is deliberately no `alg` field), NOT for binding-specific compile knobs (`cse` is a sympy.lambdify concern), and NOT a DAE declaration (`system_class` is DERIVED from the equation set). An empty block (`"solver": {}`) is LEGAL and means exactly what absence means; it NORMALIZES to absence at load, so it does not survive `parse -> emit` and the typed value never holds a block with nothing set. That normalization is why the schema does NOT carry `minProperties: 1`: every other optional top-level container (`coordinates`, `index_sets`, `metaparameters`, `coupling_roles`) admits an empty object, and a lone exception here would be a rule a reader has to learn for no gain. Arrives at esm 1.1.0.
+ */
+interface Solver {
+    /**
+     * The author's declaration of the system's stiffness. A binding MAY select an implicit / BDF-family integrator on `high`. ABSENCE IS NOT A DEFAULT VALUE: a document that omits this key has not declared its stiffness and does not thereby declare `low`; bindings MUST NOT read absence as an assertion about the system. The motivating case is the POLLU stiff-ODE benchmark (Verwer 1994), whose rate constants span ~8e-7 to ~7e9 1/s: scipy's LSODA cannot integrate it at all while BDF reproduces the published reference, a fact that is true of the MODEL rather than of any runner.
+     */
+    stiffness?: "low" | "moderate" | "high";
+    /**
+     * Absolute INTEGRATION tolerance the document asks for. Spelled as the `solve()` keyword (API_SPEC §4) so it passes through literally. This is a DIFFERENT QUANTITY from the `tolerance` object on a model / reaction system / test / assertion (esm-spec §6.6.4), which is the tolerance an assertion is COMPARED at; the two resolve independently and neither substitutes for the other. Resolution order, most-specific first: an explicit argument at the `solve()` call site, then this field, then the binding default (1e-6).
+     */
+    abstol?: number;
+    /**
+     * Relative INTEGRATION tolerance the document asks for. Same resolution order and the same distinction from the assertion-comparison `tolerance` object as `abstol`; the binding default is 1e-4.
+     */
+    reltol?: number;
+    /**
+     * Advisory: the system tolerates or benefits from this operator-splitting convention. Carries NO prescribed substep structure and does not amend esm-spec §9's single-flat-system model — a binding that does not split ignores it. The vocabulary is deliberately the one the discretization RFC §7.5 dimensional-splitting field already uses, so the word means one thing across the spec, even though that occurrence is executable and this one is a hint.
+     */
+    splitting?: "none" | "lie" | "strang";
+}
+/**
+ * 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, `faq` 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]: {
@@ -1669,6 +1719,186 @@ interface Metaparameters {
     };
 }
 
+/**
+ * Central registry of the diagnostic code STRINGS emitted by this binding, plus
+ * a neutral diagnostic base class.
+ *
+ * Cross-binding contract — values must never change; see Python `ErrorCode`
+ * enum (`pkg/earthsci-ast-py/src/earthsci_ast/error_handling.py`). These strings
+ * are pinned by the shared conformance fixtures: every value below equals, byte
+ * for byte, a literal currently emitted somewhere in `src/`. This module only
+ * CENTRALIZES the references — it does not (and must not) change any emitted
+ * string. Adding a new diagnostic means adding an entry here AND coordinating
+ * the value across every binding.
+ *
+ * Keys are the SCREAMING_SNAKE_CASE form of the value (mirroring the Python
+ * enum) so a reference reads as `ERROR_CODES.UNDEFINED_VARIABLE`.
+ */
+declare const ERROR_CODES: {
+    readonly ANALYSIS: "analysis";
+    readonly CIRCULAR_DEPENDENCY: "circular_dependency";
+    readonly DIMENSIONAL_MISMATCH: "dimensional_mismatch";
+    readonly JOIN_KEY_INVALID_TYPE: "join_key_invalid_type";
+    readonly JOIN_SIDE_AMBIGUOUS: "join_side_ambiguous";
+    readonly JOIN_SYMS_UNKNOWN_SYMBOL: "join_syms_unknown_symbol";
+    readonly DOMAIN_UNIT_MISMATCH: "domain_unit_mismatch";
+    readonly COUPLE_MULTIPLICATIVE_NO_TENDENCY: "couple_multiplicative_no_tendency";
+    readonly OPERATOR_COMPOSE_NO_MERGE: "operator_compose_no_merge";
+    readonly OPERATOR_COMPOSE_PARTIAL_MERGE: "operator_compose_partial_merge";
+    readonly OPERATOR_COMPOSE_REQUIRE_MATCH_UNMATCHED: "operator_compose_require_match_unmatched";
+    readonly OPERATOR_COMPOSE_AMBIGUOUS_BARE_NAME: "operator_compose_ambiguous_bare_name";
+    readonly RELATIONAL_NODE_IN_CONTINUOUS: "relational_node_in_continuous";
+    readonly DERIVED_INDEX_SET_UNMATERIALIZED: "derived_index_set_unmaterialized";
+    readonly UNDEFINED_INDEX_SET: "undefined_index_set";
+    readonly RAGGED_VALUES_NOT_GATHERED: "ragged_values_not_gathered";
+    readonly INVALID_BROADCAST_FN: "invalid_broadcast_fn";
+    readonly ARRAY_SHAPE_MISMATCH: "array_shape_mismatch";
+    readonly OBSERVED_CYCLE: "observed_cycle";
+    readonly AMBIGUOUS_OUTPUT_NAME: "ambiguous_output_name";
+    readonly RECURRENCE_NOT_WELLFOUNDED: "recurrence_not_wellfounded";
+    readonly RECURRENCE_UNSUPPORTED_FORM: "recurrence_unsupported_form";
+    readonly INDEXED_DEFINITION_UNSUPPORTED_FORM: "indexed_definition_unsupported_form";
+    readonly UNSUPPORTED_CONSTRUCT: "unsupported_construct";
+    readonly CALLBACK_UNREGISTERED: "callback_unregistered";
+    readonly DATA_SOURCE_UNBOUND: "data_source_unbound";
+    readonly COMPILER_UNKNOWN: "compiler_unknown";
+    readonly COMPILER_UNAVAILABLE: "compiler_unavailable";
+    readonly COMPILER_REFUSED_RULE: "compiler_refused_rule";
+    readonly EQUATION_COUNT_MISMATCH: "equation_count_mismatch";
+    readonly EVENT_AFFECTS_PARAMETER: "event_affects_parameter";
+    readonly EQUATION_DEFINES_PARAMETER: "equation_defines_parameter";
+    readonly UNBOUND_INDEX_SYMBOL: "unbound_index_symbol";
+    readonly EVENT_VAR_UNDECLARED: "event_var_undeclared";
+    readonly FACTOR_WITH_EXPRESSION_TRANSFORM: "factor_with_expression_transform";
+    readonly IC_IN_REACTION_SYSTEM: "ic_in_reaction_system";
+    readonly INVALID_STOICHIOMETRY: "invalid_stoichiometry";
+    readonly INVALID_TEMPORAL_DURATION: "invalid_temporal_duration";
+    readonly NULL_REACTION: "null_reaction";
+    readonly AMBIGUOUS_SUBSYSTEM_REF: "ambiguous_subsystem_ref";
+    readonly DATA_SOURCE_UNDEFINED: "data_source_undefined";
+    readonly DATA_SOURCE_URL_UNRESOLVED: "data_source_url_unresolved";
+    readonly RESERVED_VARIABLE_NAME: "reserved_variable_name";
+    readonly ARRAY_DEFAULT_WITHOUT_SHAPE: "array_default_without_shape";
+    readonly UNDEFINED_PARAMETER: "undefined_parameter";
+    readonly UNDEFINED_SPECIES: "undefined_species";
+    readonly UNDEFINED_SYSTEM: "undefined_system";
+    readonly UNDEFINED_VARIABLE: "undefined_variable";
+    readonly UNKNOWN_OVERRIDE_KEY: "unknown_override_key";
+    readonly ASSERTION_RANK_MISMATCH: "assertion_rank_mismatch";
+    readonly UNIT_ERROR: "unit_error";
+    readonly UNIT_INCONSISTENCY: "unit_inconsistency";
+    readonly UNIT_PARSE_ERROR: "unit_parse_error";
+    readonly UNPARSEABLE_UNIT: "unparseable_unit";
+    readonly UNRESOLVED_SCOPED_REF: "unresolved_scoped_ref";
+    readonly UNRESOLVED_SUBSYSTEM_REF: "unresolved_subsystem_ref";
+    readonly JSON_PARSE_ERROR: "json_parse_error";
+    readonly UNEXPECTED_ERROR: "unexpected_error";
+    readonly SCHEMA_VALIDATION_ERROR: "schema_validation_error";
+    readonly PARSE_ERROR: "parse_error";
+    readonly EXPRESSION_TEMPLATE_ERROR: "expression_template_error";
+    readonly ENUM_LOWERING_ERROR: "enum_lowering_error";
+    readonly NONFINITE_NUMBER: "nonfinite_number";
+    readonly LOAD_ERROR: "load_error";
+    readonly SOLVER_VERSION_TOO_OLD: "solver_version_too_old";
+    readonly CONST_UNITS_VERSION_TOO_OLD: "const_units_version_too_old";
+    readonly APPLY_EXPRESSION_TEMPLATE_BINDINGS_MISMATCH: "apply_expression_template_bindings_mismatch";
+    readonly APPLY_EXPRESSION_TEMPLATE_INVALID_DECLARATION: "apply_expression_template_invalid_declaration";
+    readonly APPLY_EXPRESSION_TEMPLATE_RECURSIVE_BODY: "apply_expression_template_recursive_body";
+    readonly APPLY_EXPRESSION_TEMPLATE_UNKNOWN_TEMPLATE: "apply_expression_template_unknown_template";
+    readonly APPLY_EXPRESSION_TEMPLATE_VERSION_TOO_OLD: "apply_expression_template_version_too_old";
+    readonly REWRITE_RULE_NONTERMINATING: "rewrite_rule_nonterminating";
+    readonly TEMPLATE_BODY_EXPANSION_TOO_DEEP: "template_body_expansion_too_deep";
+    readonly TEMPLATE_BODY_REFERENCES_COUPLING_REWRITTEN_VARIABLE: "template_body_references_coupling_rewritten_variable";
+    readonly TEMPLATE_CONSTRAINT_UNKNOWN_INDEX_SET: "template_constraint_unknown_index_set";
+    readonly METAPARAMETER_NAME_CONFLICT: "metaparameter_name_conflict";
+    readonly METAPARAMETER_TYPE_ERROR: "metaparameter_type_error";
+    readonly METAPARAMETER_UNBOUND: "metaparameter_unbound";
+    readonly TEMPLATE_IMPORT_CYCLE: "template_import_cycle";
+    readonly TEMPLATE_IMPORT_INDEX_SET_CONFLICT: "template_import_index_set_conflict";
+    readonly TEMPLATE_IMPORT_IS_COUPLING_LIBRARY: "template_import_is_coupling_library";
+    readonly TEMPLATE_IMPORT_NAME_CONFLICT: "template_import_name_conflict";
+    readonly TEMPLATE_IMPORT_NOT_LIBRARY: "template_import_not_library";
+    readonly TEMPLATE_IMPORT_REBIND_UNKNOWN_NAME: "template_import_rebind_unknown_name";
+    readonly TEMPLATE_IMPORT_RENAME_COLLISION: "template_import_rename_collision";
+    readonly TEMPLATE_IMPORT_RENAME_INVALID: "template_import_rename_invalid";
+    readonly TEMPLATE_IMPORT_RENAME_UNKNOWN_NAME: "template_import_rename_unknown_name";
+    readonly TEMPLATE_IMPORT_UNKNOWN_NAME: "template_import_unknown_name";
+    readonly TEMPLATE_IMPORT_UNRESOLVED: "template_import_unresolved";
+    readonly TEMPLATE_IMPORT_VERSION_TOO_OLD: "template_import_version_too_old";
+    readonly TEMPLATE_INJECT_TARGET_NOT_COMPONENT: "template_inject_target_not_component";
+    readonly TEMPLATE_INJECT_TARGET_UNKNOWN: "template_inject_target_unknown";
+    readonly TEMPLATE_LIBRARY_ILLEGAL_PAYLOAD: "template_library_illegal_payload";
+    readonly GEOMETRY_MANIFOLD_INVALID: "geometry_manifold_invalid";
+    readonly MAKEARRAY_REGION_INVERTED: "makearray_region_inverted";
+    readonly SUBSYSTEM_INDEX_SET_CONFLICT: "subsystem_index_set_conflict";
+    readonly SUBSYSTEM_INDEX_SET_RENAME_UNKNOWN_NAME: "subsystem_index_set_rename_unknown_name";
+    readonly SUBSYSTEM_INDEX_SET_RENAME_UNSUPPORTED_MOUNT_FORM: "subsystem_index_set_rename_unsupported_mount_form";
+    /**
+     * A §4.7 `{ ref }` mount at a form this binding does not implement — a
+     * top-level `reaction_systems.<k>` `{ ref }` (esm-spec §4.7 "Two mount forms,
+     * one mechanism"). Refused at `/reaction_systems/<k>` rather than left as an
+     * unresolved stub.
+     */
+    readonly MOUNT_FORM_UNSUPPORTED: "mount_form_unsupported";
+    readonly SUBSYSTEM_REF_IS_COUPLING_LIBRARY: "subsystem_ref_is_coupling_library";
+    readonly SUBSYSTEM_REF_IS_TEMPLATE_LIBRARY: "subsystem_ref_is_template_library";
+    readonly COUPLING_EDGE_UNKNOWN_ROLE: "coupling_edge_unknown_role";
+    readonly COUPLING_IMPORT_BIND_NOT_A_COMPONENT: "coupling_import_bind_not_a_component";
+    readonly COUPLING_IMPORT_NOT_LIBRARY: "coupling_import_not_library";
+    readonly COUPLING_IMPORT_ROLE_UNBOUND: "coupling_import_role_unbound";
+    readonly COUPLING_IMPORT_UNKNOWN_ROLE: "coupling_import_unknown_role";
+    readonly COUPLING_IMPORT_UNRESOLVED: "coupling_import_unresolved";
+    readonly COUPLING_LIBRARY_ILLEGAL_PAYLOAD: "coupling_library_illegal_payload";
+    readonly COUPLING_LIBRARY_NESTED_IMPORT: "coupling_library_nested_import";
+    readonly COUPLING_ROLE_UNUSED: "coupling_role_unused";
+    readonly ENUM_OP_MALFORMED: "enum_op_malformed";
+    readonly UNKNOWN_ENUM: "unknown_enum";
+    readonly UNKNOWN_ENUM_SYMBOL: "unknown_enum_symbol";
+    readonly TABLE_LOOKUP_UNKNOWN_TABLE: "table_lookup_unknown_table";
+    readonly TABLE_LOOKUP_AXIS_NAME_MISMATCH: "table_lookup_axis_name_mismatch";
+    readonly TABLE_LOOKUP_OUTPUT_OUT_OF_RANGE: "table_lookup_output_out_of_range";
+    readonly TABLE_INTERPOLATION_AXES_MISMATCH: "table_interpolation_axes_mismatch";
+    readonly TABLE_DATA_SHAPE_MISMATCH: "table_data_shape_mismatch";
+    readonly TABLE_AXIS_NAN: "table_axis_nan";
+    readonly TABLE_OUT_OF_BOUNDS_UNSUPPORTED: "table_out_of_bounds_unsupported";
+    readonly UNKNOWN_CLOSED_FUNCTION: "unknown_closed_function";
+    readonly CLOSED_FUNCTION_ARITY: "closed_function_arity";
+    readonly CLOSED_FUNCTION_OVERFLOW: "closed_function_overflow";
+    readonly INTERP_AXIS_LENGTH_MISMATCH: "interp_axis_length_mismatch";
+    readonly INTERP_AXIS_NOT_CONST: "interp_axis_not_const";
+    readonly INTERP_AXIS_TOO_SHORT: "interp_axis_too_short";
+    readonly INTERP_NAN_IN_AXIS: "interp_nan_in_axis";
+    readonly INTERP_NON_MONOTONIC_AXIS: "interp_non_monotonic_axis";
+    readonly INTERP_TABLE_NOT_CONST: "interp_table_not_const";
+    readonly SEARCHSORTED_NAN_IN_TABLE: "searchsorted_nan_in_table";
+    readonly SEARCHSORTED_NON_MONOTONIC: "searchsorted_non_monotonic";
+    readonly CONST_NOT_SCALAR: "const_not_scalar";
+    readonly ENUM_NOT_LOWERED: "enum_not_lowered";
+    readonly FN_MISSING_NAME: "fn_missing_name";
+    readonly INVALID_EXPRESSION: "invalid_expression";
+    readonly UNBOUND_VARIABLE: "unbound_variable";
+    readonly UNLOWERED_OPERATOR: "unlowered_operator";
+    readonly UNSUPPORTED_OPERATOR: "unsupported_operator";
+    readonly CONFLICTING_DERIVATIVE: "conflicting_derivative";
+    readonly DIMENSION_PROMOTION: "dimension_promotion";
+    readonly FLATTEN_ERROR: "flatten_error";
+    readonly UNEVALUABLE_OPERATOR: "unevaluable_operator";
+};
+/** A diagnostic code string from {@link ERROR_CODES}. */
+type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+/**
+ * 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);
+}
+
 /**
  * Tagged numeric-literal AST nodes and lossless JSON I/O per
  * discretization RFC §5.4.1 (int/float distinction) and §5.4.6
@@ -1696,6 +1926,7 @@ interface Metaparameters {
  * 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;
@@ -1715,7 +1946,7 @@ declare function isFloatLit(x: unknown): x is NumericLiteral & {
  * at the boundary between kind-aware and kind-agnostic code.
  */
 declare function numericValue(x: unknown): number | undefined;
-declare class LosslessJsonParseError extends Error {
+declare class LosslessJsonParseError extends EsmDiagnosticError {
     readonly position: number;
     constructor(message: string, position: number);
 }
@@ -1741,7 +1972,7 @@ declare function losslessJsonParse(text: string): unknown;
  * `canonicalize.ts` re-exports this class under the same name, so consumers may
  * keep importing `CanonicalizeError` from either module.
  */
-declare class CanonicalizeError extends Error {
+declare class CanonicalizeError extends EsmDiagnosticError {
     /** Stable RFC §5.4.6 / §5.4.7 error code. */
     readonly code: string;
     constructor(code: string, message?: string);
@@ -1783,7 +2014,7 @@ declare function losslessJsonStringify(value: unknown): string;
  * `.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
+ * {@link losslessJsonStringify} and `toJson()`), 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
@@ -1794,7 +2025,7 @@ declare function losslessJsonStringify(value: unknown): string;
 declare function formatFloatToken(value: number): string;
 
 /**
- * EarthSciML Serialization Format TypeScript type definitions — plus a small
+ * EarthSciML Abstract Syntax Tree Format TypeScript type definitions — plus a small
  * set of RUNTIME re-exports.
  *
  * Provides the complete type definitions for the ESM format: the auto-generated
@@ -1807,11 +2038,30 @@ declare function formatFloatToken(value: number): string;
  *
  * Canonical alias names (duplicates are kept for back-compat but marked
  * `@deprecated`):
- *   - root file structure → `EsmFile`   (aliases: `EsmFormat`, generated `ESMFormat`)
+ *   - root file structure → `EsmFile`   (alias: the 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.
+ *
+ * DO NOT collapse `Expression` and `Expr` into one type. The phase-6 surface
+ * tidy (API_SPEC.md §8) proposed it and it was refused, because the two are not
+ * an alias pair in either direction:
+ *
+ *   - `Expression` is GENERATED from `esm-schema.json` by json2ts (plus
+ *     `scripts/fix-generated-expression.mjs`). Deleting it means the next
+ *     `npm run generate-types` puts it back.
+ *   - The relationship is a strict, ONE-WAY subtype: `Expression` is assignable
+ *     to `Expr`, and `Expr` is NOT assignable to `Expression` — the compiler
+ *     rejects it, because `Expr` admits the tagged `NumericLiteral` leaf that
+ *     only exists in memory. Collapsing onto `Expr` would let a tagged literal
+ *     reach a serialization boundary typed for the wire; collapsing onto
+ *     `Expression` would delete the tagged leaf the discretization RFC §5.4.1
+ *     requires.
+ *
+ * Both names are load-bearing and heavily used (roughly 400 references each in
+ * this package), and the editor is written almost entirely against `Expression`
+ * because it edits wire values.
  */
 
 /**
@@ -1856,9 +2106,64 @@ type EsmFile = ESMFormat1 & Omit<ESMFormat2, 'models'> & {
     models?: {
         [k: string]: Model | SubsystemRef;
     };
+    /**
+     * NON-SCHEMA, LOADER-POPULATED. The per-component `expression_templates`
+     * registries of the Option-B loaded image, keyed
+     * `"models.<name>"` / `"reaction_systems.<name>"` — the Julia / Python
+     * `component_templates` key shape.
+     *
+     * `loadInput` (`parse.ts`) snapshots these between
+     * `lowerExpressionTemplates` (which preserves the per-component blocks) and
+     * `expandDocument` (which strips them), because esm-libraries-spec §4.7.5
+     * step 4 requires `flatten` to carry the MERGED template registry as a
+     * first-class field of the flattened representation — see
+     * `mergedTemplateRegistry` in `flatten-template-registry.ts`.
+     *
+     * It is NOT part of `esm-schema.json`, is NEVER serialized (`toJson`
+     * excludes it), and is absent on a document that declares no per-component
+     * `expression_templates` block — i.e. on almost every document. Values are
+     * raw JSON template declarations (`{params, body, match?, …}`), not the
+     * typed `Expression` form.
+     *
+     * `loadInput` attaches it as a NON-ENUMERABLE own property, so
+     * `Object.keys`, `JSON.stringify`, spread and structural equality all see
+     * exactly the document and nothing else — the conformance round-trip
+     * (`loadString(toJson(loadString(f)))` deep-equals `loadString(f)`) would
+     * otherwise fail for every template-bearing fixture. A consequence worth
+     * knowing: a shallow copy (`{...file}`) DROPS it, so a pass that rebuilds
+     * the file object must re-attach it if the result will be flattened.
+     */
+    componentTemplates?: Record<string, unknown>;
+    /**
+     * NON-SCHEMA, LOADER-POPULATED. The loader-API metaparameter bindings this
+     * document was loaded with (esm-spec §9.7.6 binding site 4) — the map a
+     * discovered §8.9.4 `extent` arrives as.
+     *
+     * `loadInput` (`parse.ts`) attaches it so `resolveSubsystemRefsSync` can
+     * BACKFILL each `subsystems.<k>` mount edge's close with it (§4.7 "Two mount
+     * forms, one mechanism"): in this binding ref resolution is a separate step
+     * from `load`, so the bindings have no other route from the loader call to
+     * the mount edge. Filtered at the edge to the names the LEAF declares, and
+     * an explicit edge `binding` always wins.
+     *
+     * NON-ENUMERABLE for the same reason `componentTemplates` is: the
+     * conformance round-trip compares loaded documents structurally, and a
+     * loader sidecar is not part of the document. Absent unless the document was
+     * loaded with `metaparameters`.
+     */
+    loaderMetaparameters?: Record<string, number>;
+    /**
+     * NON-SCHEMA, LOADER-POPULATED. The directory relative `coupling_import`
+     * refs resolve against (esm-spec §10.10 -> §4.7: "relative to the directory
+     * of the referencing file"), recorded by `loadInput` when the load had an
+     * explicit `basePath` (`loadPath` always passes the file's directory) and
+     * preferred by `expandCouplingImports` over `CouplingImportOptions.basePath`.
+     * NON-ENUMERABLE for the same reason `componentTemplates` is: the
+     * `coupling_import` entry must round-trip verbatim (§10.10.3), so the base is
+     * kept beside the document, never written into its refs.
+     */
+    couplingImportBase?: string;
 };
-/** @deprecated Prefer {@link EsmFile}. Identical to the generated `ESMFormat`. */
-type EsmFormat = ESMFormat;
 /** @deprecated Prefer {@link ExpressionNode} (the generated name). */
 type ExprNode = ExpressionNode;
 
@@ -2098,6 +2403,7 @@ type Model = Omit<Model$1, 'variables' | 'subsystems'> & {
  * 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;
@@ -2108,12 +2414,65 @@ interface CanonicalDims {
     cd?: number;
     rad?: number;
 }
+/**
+ * The EXACT scale of a unit relative to SI (esm-spec §4.8.1 "Scales are EXACT"):
+ * a product of prime powers and a power of π, each with a rational exponent, so
+ * `mi` is 2^4 * 3^2 * 5^-3 * 11 * 127. Multiplying units adds exponents,
+ * dividing subtracts them and a rational power multiplies them, so a composite
+ * unit's scale never rounds. Every scale AGREEMENT (`m + km`, `m/s = mi/h`) is
+ * decided with {@link ExactScale.equals}; the floating-point `scale` is kept for
+ * numeric conversion only.
+ */
+declare class ExactScale {
+    private readonly primes;
+    private readonly piExp;
+    private constructor();
+    private static readonly ONE;
+    /** Exactly 1. */
+    static one(): ExactScale;
+    /** A positive safe integer. */
+    static integer(value: number): ExactScale;
+    /** `num/den` for positive safe integers. */
+    static ratio(num: number, den: number): ExactScale;
+    /** `10^k`. */
+    static pow10(k: number): ExactScale;
+    /** π. */
+    static pi(): ExactScale;
+    /**
+     * The exact value of a positive decimal literal as the registry writes it
+     * (`"0.3048"`, `"133.322387415"`, `"2.6867e20"`), read from its TEXT.
+     */
+    static decimal(literal: string): ExactScale;
+    private normalized;
+    private combine;
+    /** The scale of a product of units. */
+    multiply(other: ExactScale): ExactScale;
+    /** The scale of a quotient of units. */
+    divide(other: ExactScale): ExactScale;
+    /** The scale of a unit raised to a (rational) power. */
+    power(exponent: number): ExactScale;
+    /** Whether two scales are the same number. */
+    equals(other: ExactScale): boolean;
+    /** Whether this is exactly 1. */
+    isOne(): boolean;
+    /** The nearest double, for diagnostics and numeric conversion — never for comparison. */
+    toNumber(): number;
+    /**
+     * `p/q`, `p/q*pi` or `p/q*pi^k` in lowest terms (`/q` omitted when it is 1),
+     * the spelling tests/conformance/unit_registry pins; `null` when an exponent is
+     * not whole (`sqrt(km)`).
+     */
+    ratioString(): string | null;
+    toString(): string;
+}
 interface ParsedUnit {
     dims: CanonicalDims;
     scale: number;
     offset?: number;
+    /** The scale every agreement is decided on (esm-spec §4.8.1). */
+    exact: ExactScale;
 }
-declare class UnitConversionError extends Error {
+declare class UnitConversionError extends EsmDiagnosticError {
     constructor(message: string);
 }
 /**
@@ -2203,7 +2562,7 @@ interface UnitResult {
      * `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`, ...).
+     * not model (`index`, `fn`, `faq`, `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
@@ -2245,7 +2604,7 @@ interface UnitWarning {
      *   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`,
+     *   operator with no dimensional rule (`faq`, `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
@@ -2376,14 +2735,14 @@ interface SchemaError {
 /**
  * Parse error - thrown when JSON parsing fails
  */
-declare class ParseError extends Error {
+declare class ParseError extends EsmDiagnosticError {
     originalError?: Error | undefined;
     constructor(message: string, originalError?: Error | undefined);
 }
 /**
  * Schema validation error - thrown when schema validation fails
  */
-declare class SchemaValidationError extends Error {
+declare class SchemaValidationError extends EsmDiagnosticError {
     errors: SchemaError[];
     constructor(message: string, errors: SchemaError[]);
 }
@@ -2399,7 +2758,7 @@ declare const SCHEMA_VERSION: string;
  */
 declare function validateSchema(data: unknown): SchemaError[];
 /**
- * Options controlling how `load()` parses and represents an ESM file.
+ * Options controlling how the `load*` entry points parse and represent an ESM file.
  */
 interface LoadOptions {
     /**
@@ -2466,21 +2825,51 @@ interface LoadOptions {
     onVersionWarning?: ((message: string) => void) | undefined;
 }
 /**
- * Load an ESM file from a JSON string or pre-parsed object
+ * Read and parse an ESM document from a filesystem path.
+ *
+ * The file's own directory anchors relative `expression_template_imports`
+ * refs and `{ref}` subsystem refs unless `options.basePath` overrides it.
+ * Requires synchronous file access (Node); browser hosts should read the
+ * bytes themselves and call {@link loadString}.
+ *
+ * @param path - Filesystem path to the `.esm` document
+ * @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 loadPath(path: string, options?: LoadOptions): EsmFile;
+/**
+ * Parse an ESM document from JSON TEXT.
  *
- * @param input - JSON string or pre-parsed JavaScript object
+ * @param json - The document as a JSON string
  * @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;
+declare function loadString(json: string, options?: LoadOptions): EsmFile;
+/**
+ * Parse an ESM document that is ALREADY a JavaScript object — the same
+ * document a `.esm` file holds, just already `JSON.parse`d.
+ *
+ * `options.canonical` has no effect here: canonical mode tags numeric
+ * literals during JSON decoding, and this entry point does no decoding.
+ * Callers who want tagged leaves should run `losslessJsonParse` on the text
+ * themselves, or use {@link loadString}.
+ *
+ * @param doc - The already-parsed document
+ * @param options - Optional load-time settings (see {@link LoadOptions})
+ * @returns Typed EsmFile object
+ * @throws {SchemaValidationError} When schema validation fails
+ */
+declare function loadDocument(doc: 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:
+ * `toJson(file)` emits an `EsmFile` as wire-form JSON suitable for round-trip
+ * through `loadString()`. 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
@@ -2500,7 +2889,7 @@ declare function load(input: string | object, options?: LoadOptions): EsmFile;
  *   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()` /
+ *      Object key order is the insertion order produced by `loadString()` /
  *      authored constructors, which is itself schema-driven.
  *
  * The Python reference at `pkg/earthsci-ast-py/src/earthsci_ast/serialize.py`
@@ -2509,8 +2898,8 @@ declare function load(input: string | object, options?: LoadOptions): EsmFile;
  * delegating shape preservation to the generated types.
  */
 
-/** Optional behavior controls for {@link save}. */
-interface SaveOptions {
+/** Optional behavior controls for {@link toJson} / {@link writePath}. */
+interface ToJsonOptions {
     /**
      * When `true`, emit byte-canonical JSON per RFC §5.4.6: integer-tagged
      * `NumericLiteral` leaves as integer tokens, float-tagged leaves with
@@ -2530,16 +2919,31 @@ interface SaveOptions {
     indent?: number;
 }
 /**
- * Serialize an `EsmFile` to wire-form JSON.
+ * Serialize an `EsmFile` to wire-form JSON. PURE — it never touches disk;
+ * {@link writePath} is the writer.
  *
  * @param file - The `EsmFile` to serialize.
- * @param options - Optional behavior controls (see {@link SaveOptions}).
+ * @param options - Optional behavior controls (see {@link ToJsonOptions}).
  * @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;
+declare function toJson(file: EsmFile, options?: ToJsonOptions): string;
+/**
+ * {@link toJson} with no indentation — the single-line wire form. Present in
+ * every binding, because Rust and Go have no default arguments and so cannot
+ * express `toJson(file, { indent: 0 })`.
+ */
+declare function toJsonCompact(file: EsmFile, options?: ToJsonOptions): string;
+/**
+ * Write an `EsmFile` to `path` as wire-form JSON. Returns nothing: no
+ * function in this API both writes and hands back the payload — call
+ * {@link toJson} when you want the string.
+ *
+ * Requires synchronous file access (Node).
+ */
+declare function writePath(file: EsmFile, path: string, options?: ToJsonOptions): void;
 
 /**
  * Shared validation result / error types for the structural-validation modules.
@@ -2604,14 +3008,37 @@ interface ValidateOptions {
     basePath?: string;
 }
 /**
- * Validate ESM data and return structured validation result.
+ * Validate a TYPED ESM DOCUMENT and return a structured validation result.
  *
- * @param data - ESM data as JSON string or object
+ * API_SPEC.md §8 item 13: `validate` takes a typed document in EVERY binding.
+ * It used to accept `string | object` here, so `validate(someString)` meant
+ * "parse this JSON text" in TypeScript and Python but was a type error in Rust
+ * and Go. The text convenience now has its own name, {@link validateText}, so
+ * the argument type says which one you are calling.
+ *
+ * Passing a string is rejected at compile time by the signature and at runtime
+ * by an explicit guard, rather than silently doing something else.
+ *
+ * @param document - a loaded ESM document (or a plain object of the same shape)
  * @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;
+declare function validate(document: EsmFile | object, options?: ValidateOptions): ValidationResult;
+/**
+ * Validate ESM JSON **text**: parse it, then run {@link validate} on the result.
+ *
+ * A malformed document does not throw — it comes back as a `ValidationResult`
+ * carrying a single `json_parse_error` schema error, the same envelope the old
+ * string-accepting `validate()` produced.
+ *
+ * The canonical name is `validate_text` (API_SPEC.md §8 item 13). There is no
+ * `validatePath` counterpart in this binding: `@earthsciml/ast` is built for
+ * the browser as well as Node, and the package has no filesystem story on the
+ * public surface for a synchronous read. Read the file yourself and call
+ * `validateText`, passing `basePath` so relative `{ref}` targets still resolve.
+ */
+declare function validateText(text: string, options?: ValidateOptions): ValidationResult;
 
 /**
  * The esm 1.0.0 classification API (esm-spec §6.3.1).
@@ -2654,13 +3081,30 @@ 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.
+ * Unknowns an equation DEFINES — its LHS naming them, bare (`y ~ f(…)`) or
+ * indexed (`y[i] ~ f(…)`, which defines the whole array `y`) — eliminable,
+ * materializable (esm-spec §6.3.1). An unknown that is already an ODE state is
+ * not observed.
+ *
+ * The split from {@link algebraicUnknowns} is SEMANTIC, not syntactic: observed
+ * when an equation defines the unknown, algebraic when it is only constrained.
+ * The defining form is read through the LHS's BASE NAME, so an arrayed
+ * definition is observed exactly as its scalar counterpart is; only a genuine
+ * expression LHS, one that names no single variable (`H*H*SO4 ~ Ksp`), is an
+ * implicit constraint. §6.3.1 used to spell the criterion "a bare-variable
+ * LHS", which was written for scalar equations and contradicted the semantic
+ * criterion in the arrayed case.
+ *
+ * Note that *eliminable* is not *inlineable*: a scalar observed is eliminated
+ * by substituting its definition into every consumer, while an arrayed one
+ * materializes into a buffer its consumers index. Both are observed; a caller
+ * that wants the strict inlineable form asks {@link observedDefinitions} for it
+ * with `bareOnly`.
  */
 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.
+ * The DEFINING EXPRESSION of every observed unknown: the RHS of the equation
+ * whose LHS names it, bare (`y ~ f(…)`) or indexed (`y[i] ~ f(…)`).
  *
  * 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
@@ -2671,11 +3115,14 @@ declare function observedUnknowns(model: Model): string[];
  * 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>;
+declare function observedDefinitions(model: Model, options?: {
+    bareOnly?: boolean;
+}): 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.
+ * Unknowns constrained only implicitly — no equation names them on its LHS
+ * (`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). */
@@ -2717,6 +3164,17 @@ declare function constantParameters(model: Model): string[];
 declare function systemKind(model: Model): SystemKind;
 /** The model's explicit `system_kind` field, or `null` when absent. */
 declare function declaredSystemKind(model: Model): SystemKind | null;
+/**
+ * The kind a caller choosing a solver actually asks for: the DECLARED
+ * `system_kind` when the document states one, otherwise the DERIVED kind.
+ *
+ * API_SPEC.md §8 item 11 rules the family as three distinct questions plus this
+ * one composition — {@link systemKind} derives, {@link declaredSystemKind}
+ * reads the field, and this composes them as `declared ?? derived`. It never
+ * returns `null`: an undeclared model still has a derived kind. Matches Go's
+ * `EffectiveSystemKind`.
+ */
+declare function effectiveSystemKind(model: Model): SystemKind;
 /** Every derived set for one model node, as the conformance goldens spell it. */
 interface ModelClassification {
     odeStates: string[];
@@ -2788,7 +3246,7 @@ 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 {
+declare class CadenceCycleError extends EsmDiagnosticError {
     readonly cycle: string[];
     constructor(cycle: string[]);
 }
@@ -2807,7 +3265,26 @@ declare class CadenceSeeder {
     private readonly memo;
     private readonly inProgress;
     private readonly independentVariable;
+    /**
+     * Memo for {@link isRecurrence}. A recurrence body reads itself once per lag —
+     * 38 times in `tests/fixtures/recurrence/07_recurrence_thirty_eight_lags.esm`
+     * — and each read reaches `leaf` as a separate self-edge, so without this the
+     * whole well-foundedness analysis would re-run per lag.
+     */
+    private readonly recurrenceMemo;
     constructor(model: Model, esmFile?: EsmFile | undefined);
+    /**
+     * Whether `name`'s defining equation is a causal-recurrence CANDIDATE --
+     * array-shaped, with an `index` self-read in its own RHS -- and so whether its
+     * self-edge is an ordering the §4.3.1.1 rules govern rather than a cycle.
+     *
+     * Candidacy, not well-foundedness: see `isRecurrenceCandidate` for why the
+     * stricter predicate would mask the very codes §5.19.5 requires. Delegated
+     * wholesale to `recurrence.js` so the seeder and the validator cannot disagree
+     * about which equations the construct covers. Memoized because a recurrence
+     * body reads itself once per lag.
+     */
+    private isRecurrence;
     /** The set of observed unknowns, for callers that want to enumerate them. */
     observedNames(): string[];
     /**
@@ -2907,6 +3384,8 @@ interface ComponentGraph {
     /** All coupling relationships */
     edges: CouplingEdge[];
 }
+/** Which of the two graphs §4.8 defines. */
+type GraphKind = 'component' | 'expression';
 /**
  * Directed graph with node/edge lists plus adjacency, predecessor, and
  * successor lookups (ESM Libraries Specification §4.8). Nodes are addressed by
@@ -2914,6 +3393,17 @@ interface ComponentGraph {
  * those keys through `source`/`target`.
  */
 interface Graph<N, E> {
+    /**
+     * Which of the two §4.8 graphs this is. Carried explicitly because the DOT
+     * and Mermaid exporters name the graph in their header
+     * (`digraph ComponentGraph` / `digraph ExpressionGraph`) and an EMPTY graph —
+     * `tests/valid/data_sources_only.esm` produces two — has no node to sniff.
+     * The other bindings get this from their type system (Julia dispatches on
+     * `Graph{ComponentNode,CouplingEdge}`, Python reads `node_type`, Go and Rust
+     * have two distinct structs); TypeScript's `Graph` is one generic interface,
+     * so it carries the tag.
+     */
+    kind?: GraphKind;
     /** All nodes in the graph */
     nodes: N[];
     /** All edges in the graph */
@@ -2939,8 +3429,9 @@ interface VariableNode {
      * 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
+     * `state` is an ODE state, `observed` an unknown some equation DEFINES (its
+     * LHS naming it, bare or indexed), `algebraic` one that is only implicitly
+     * CONSTRAINED (no equation names it on its LHS), `brownian` a
      * wiener-updated parameter, `discrete` a parameter with any other update,
      * `parameter` a sampled or constant one, and `species` a reaction-system
      * species.
@@ -2956,7 +3447,9 @@ interface VariableNode {
  *
  * 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.
+ * reaction — a coupling variable map, or the synthetic `expr_result` edges of a
+ * BARE-EXPRESSION target. (An observed unknown's definition IS one of the
+ * model's equations from 1.0.0, so its edges carry that equation's index.)
  */
 interface DependencyEdge {
     /** Source variable name */
@@ -2976,7 +3469,7 @@ interface DependencyEdge {
     /**
      * 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 (coupling maps and bare-expression targets).
      */
     equation_index: number;
     /** The expression that created this dependency */
@@ -2988,17 +3481,6 @@ interface DependencyEdge {
  * 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
  */
@@ -3027,10 +3509,24 @@ declare function expressionGraph(target: EsmFile | Model | ReactionSystem | Equa
  * 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.
+ *
+ * The header NAMES the graph — `digraph ComponentGraph` / `digraph
+ * ExpressionGraph`. §4.8.3 requires a DOT export and specifies no syntax for it,
+ * so the cross-binding tie-break is the majority: Python, Go, Rust and Julia all
+ * emitted the named form and this binding alone emitted a bare `digraph {`.
+ * `tests/conformance/graph/cases.json` pins it.
  */
 declare function toDot<N extends object, E>(graph: Graph<N, E>): string;
 /**
  * Export graph as Mermaid flowchart format for Markdown embedding.
+ *
+ * The header is `graph TD`. §4.8.3 requires a Mermaid export and specifies no
+ * syntax for it, so the cross-binding tie-break is the majority, applied to the
+ * keyword and the direction independently: `graph` beats `flowchart` 4-1
+ * (Python, Go, Rust and Julia against this binding) and `TD` beats `LR` 3-2
+ * (this binding, Python and Julia against Go and Rust). `graph` is Mermaid's
+ * legacy spelling of `flowchart`; both render, and the majority points at
+ * `graph`. `tests/conformance/graph/cases.json` pins it.
  */
 declare function toMermaid<N extends object, E>(graph: Graph<N, E>): string;
 /**
@@ -3351,13 +3847,13 @@ declare function groupSubexpressionsByType(commonSubexpressions: CommonSubexpres
  * does not cover. Callers that need a boolean answer should use
  * {@link isDifferentiable}.
  */
-declare class NonDifferentiableExpressionError extends Error {
+declare class NonDifferentiableExpressionError extends EsmDiagnosticError {
     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 {
+declare class InvalidDerivativeOrderError extends EsmDiagnosticError {
     readonly order: number;
     constructor(order: number);
 }
@@ -3459,13 +3955,6 @@ interface AnalysisOptions {
  * @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.
@@ -3522,8 +4011,8 @@ declare function toMathML(expr: Expr | Equation | Model | ReactionSystem | React
  *    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
+ *    the `true` and `false` literals, and `integral` / `reshape` / `transpose` / `concat`;
+ *  - reduction & array-query tier: `faq` 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
@@ -3537,9 +4026,9 @@ declare function toMathML(expr: Expr | Equation | Model | ReactionSystem | React
  * 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}.
+ * Still deferred (need dedicated surface syntax — a later pass): `broadcast` and
+ * `enum`. Those are refused with an {@link ExpressionParseError}, as is the
+ * call spelling `table_lookup(…)` (its real surface is `visc[T=temp]`).
  *
  * Design rules: multiplication is ALWAYS explicit (`k * A`) — no implicit
  * juxtaposition, because identifiers are multi-letter (`NO2`, `O3`, `k_photo`).
@@ -3555,7 +4044,7 @@ declare function toMathML(expr: Expr | Equation | Model | ReactionSystem | React
  */
 
 /** Thrown when an expression string cannot be parsed. */
-declare class ExpressionParseError extends Error {
+declare class ExpressionParseError extends EsmDiagnosticError {
     /** 0-based character offset into the source where parsing failed. */
     pos: number;
     constructor(message: string, 
@@ -3698,7 +4187,7 @@ declare function substituteInReactionSystem(system: ReactionSystem, bindings: Re
  * @param system ReactionSystem to derive ODEs from
  * @returns Model with species as state variables, derived ODEs plus constraints
  */
-declare function deriveODEs(system: ReactionSystem): Model;
+declare function deriveOdes(system: ReactionSystem): Model;
 /**
  * Compute stoichiometric matrix from a reaction system
  *
@@ -3743,6 +4232,14 @@ declare function substrateMatrix(system: ReactionSystem): number[][];
  * @returns Product stoichiometric matrix
  */
 declare function productMatrix(system: ReactionSystem): number[][];
+/**
+ * @deprecated Spelling alias for {@link deriveOdes}, kept for one minor per
+ * API_SPEC.md §10. `deriveODEs` violated §2/§2.1: the canonical name is
+ * `derive_odes`, whose TypeScript transliteration is `deriveOdes`, and this
+ * binding already spelled the siblings `odeStates` / `isOdeState` that way.
+ * Removed at the next major.
+ */
+declare const deriveODEs: typeof deriveOdes;
 
 /**
  * Immutable editing operations for the ESM format
@@ -3754,7 +4251,7 @@ declare function productMatrix(system: ReactionSystem): number[][];
 /**
  * Error thrown when attempting to remove a variable that is still referenced
  */
-declare class VariableInUseError extends Error {
+declare class VariableInUseError extends EsmDiagnosticError {
     variableName: string;
     references: string[];
     constructor(variableName: string, references: string[]);
@@ -3762,7 +4259,7 @@ declare class VariableInUseError extends Error {
 /**
  * Error thrown when attempting an operation on a non-existent entity
  */
-declare class EntityNotFoundError extends Error {
+declare class EntityNotFoundError extends EsmDiagnosticError {
     entityType: string;
     entityName: string;
     constructor(entityType: string, entityName: string);
@@ -3985,20 +4482,70 @@ declare function contains(expr: Expr, varName: string): boolean;
  */
 declare function simplify(expr: Expr): Expr;
 
+/**
+ * `table_lookup` → `interp.linear` / `interp.bilinear` / `index` lowering —
+ * esm-spec §9.5.3.
+ *
+ * A `table_lookup` node is SUGAR. It names a `function_tables` entry plus one
+ * input expression per declared axis, and §9.5.3 gives the exact §9.2
+ * closed-function tree it stands for. Nothing in this binding evaluated
+ * `table_lookup` itself: the op is absent from the evaluable-core op registry,
+ * so `evaluateExpression` refused it as an `unlowered_operator` — and the only
+ * lowering that existed lived INSIDE a test harness
+ * (`function-tables-lowering.test.ts`). A document whose observed is defined by
+ * a `table_lookup` therefore validated, round-tripped, and then failed every
+ * evaluation that depended on it, while the same lookup written out by hand in
+ * the lowered form worked (issue #188).
+ *
+ * **This runs at EVALUATION, not at load, and that is the point.** §9.5.4 makes
+ * `function_tables` / `table_lookup` first-class AUTHORED constructs that must
+ * survive a round trip, and `toJson` serializes the typed `EsmFile` that
+ * `loadString` produced — so lowering in `parse.ts` (where `lowerEnums` sits)
+ * would emit the lowered `fn` form and break §9.5.4. §9.5.3 admits either an
+ * in-memory transformation or a direct evaluator dispatch; `codegen.ts`
+ * dispatches on the node and lowers it here, one node at a time, leaving the
+ * loaded image authored-as-written.
+ *
+ * Bit-equivalence with the hand-written inline-`const` lookup (§9.5's central
+ * promise) comes for free: the lowered tree drives the very same
+ * `closed-functions.ts` `interp.linear` / `interp.bilinear` implementations an
+ * author would have invoked by hand.
+ *
+ * **`out_of_bounds: "error"` is REFUSED, not silently clamped.** `"clamp"` is
+ * required of every binding and `"error"` is "conformant when implemented"
+ * (§9.5.1); this binding does not implement it, so §9.5.3a makes the lookup a
+ * `table_out_of_bounds_unsupported` error here rather than an `interp.*` tree
+ * that answers in a mode the author did not ask for. That would be the same
+ * defect as the one this module exists to fix: a wrong number with nothing in
+ * the result to say so. The document still LOADS and still round-trips — it
+ * simply does not evaluate.
+ */
+
+/** A document's `function_tables` block (esm-spec §9.5.1), keyed by table id. */
+type FunctionTables = {
+    [k: string]: FunctionTable;
+};
+
 /**
  * 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.
+ * "codegen" filename this performs NO code generation: 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.
+ * their consumers. `table_lookup` is the one op lowered rather than dispatched
+ * — to its §9.5.3 `interp.*` form, one node at a time, on the way through; see
+ * `lower-table-lookups.ts` for why that happens HERE and not at load.
+ *
+ * Both entry points walk the whole expression BEFORE evaluating any of it
+ * (esm-spec §9.6.6) and refuse an operator this evaluator cannot evaluate: an op
+ * outside the §4.2 evaluable core — the open-tier sugar
+ * `grad`/`div`/`laplacian`/`integral`, a user op, or a spatial / right-hand-side
+ * `D` — with `unlowered_operator`, and a core op with no scalar rule — the
+ * array/query and value-invention ops, `Pre`, an unlowered `enum` — with
+ * `unevaluable_operator`. An op in an untaken `ifelse` branch is refused too.
  */
 
 /**
@@ -4007,6 +4554,19 @@ declare function simplify(expr: Expr): Expr;
  * returns the scalar result.
  */
 type CompiledExpression = (bindings: Map<string, number>) => number;
+/**
+ * Document context an expression may need beyond its free-variable bindings.
+ *
+ * Only `table_lookup` needs any: the node names a `function_tables` entry that
+ * lives on the DOCUMENT, not in the expression, so an expression lifted out of
+ * an `EsmFile` cannot be evaluated without being handed the block it refers to
+ * (`{ functionTables: file.function_tables }`). Every other op is
+ * self-contained, which is why this is optional.
+ */
+interface EvaluateOptions {
+    /** The document's `function_tables` block (esm-spec §9.5.1). */
+    functionTables?: FunctionTables | undefined;
+}
 /**
  * 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
@@ -4016,10 +4576,24 @@ type CompiledExpression = (bindings: Map<string, number>) => number;
  * 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";
+declare class UnloweredOperatorError extends EsmDiagnosticError {
+    readonly code: typeof ERROR_CODES.UNLOWERED_OPERATOR;
     constructor(message: string);
 }
+/**
+ * Error carrying the stable, cross-binding `unevaluable_operator` diagnostic
+ * (esm-spec §9.6.6): an op that IS in the §4.2 evaluable-core set but that this
+ * scalar evaluator has no rule for. The complement of
+ * {@link UnloweredOperatorError}, which is for an op OUTSIDE the core, so it
+ * carries no rewrite-rule advice: the op needs an earlier pipeline stage (value
+ * invention, or a load-time lowering pass), not a rewrite rule.
+ */
+declare class UnevaluableOperatorError extends EsmDiagnosticError {
+    readonly code: typeof ERROR_CODES.UNEVALUABLE_OPERATOR;
+    /** The offending operator name. */
+    readonly op: string;
+    constructor(op: string, remedy?: 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
@@ -4033,8 +4607,7 @@ declare class UnloweredOperatorError extends Error {
  * 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;
+declare class EvaluatorError extends EsmDiagnosticError {
     constructor(code: string, message: string);
 }
 /**
@@ -4046,8 +4619,11 @@ declare class EvaluatorError extends Error {
  * load time) and array-valued `const` nodes (those are consumed by
  * container ops such as `interp.searchsorted` and `index`, not by
  * scalar evaluation).
+ *
+ * Pass `{ functionTables: file.function_tables }` to evaluate an expression
+ * containing `table_lookup` nodes — see {@link EvaluateOptions}.
  */
-declare function compileExpression(expr: Expr): CompiledExpression;
+declare function compileExpression(expr: Expr, options?: EvaluateOptions): CompiledExpression;
 /**
  * Compile and apply in one step. Equivalent to
  * `compileExpression(expr)(bindings)` but avoids allocating a closure
@@ -4055,7 +4631,7 @@ declare function compileExpression(expr: Expr): CompiledExpression;
  * fixed-point observed-variable resolution, unit-conversion
  * folding).
  */
-declare function evaluateExpression(expr: Expr, bindings: Map<string, number>): number;
+declare function evaluateExpression(expr: Expr, bindings: Map<string, number>, options?: EvaluateOptions): number;
 
 /**
  * Migration utilities for ESM format version upgrades.
@@ -4089,7 +4665,7 @@ declare function evaluateExpression(expr: Expr, bindings: Map<string, number>):
 /**
  * Error thrown when migration fails.
  */
-declare class MigrationError extends Error {
+declare class MigrationError extends EsmDiagnosticError {
     constructor(message: string);
 }
 /**
@@ -4104,7 +4680,14 @@ declare function canMigrate(sourceVersion: string, targetVersion: string): boole
  * - 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[];
+declare function supportedMigrationTargets(sourceVersion: string): string[];
+/**
+ * @deprecated Use {@link supportedMigrationTargets}. The canonical name is
+ * `supported_migration_targets` (Julia, Python and Go already spell it that
+ * way); the harmonized API drops the `get` prefix. Kept for one minor per
+ * API_SPEC.md §10; removed at the next major.
+ */
+declare const getSupportedMigrationTargets: typeof supportedMigrationTargets;
 /**
  * Migrate an ESM file from its current schema version to the target version.
  *
@@ -4162,72 +4745,396 @@ declare function isCouplingLibraryDoc(raw: unknown): boolean;
 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.
+ * Coupled System Flattening for the ESM format (esm-libraries-spec §4.7.5).
+ *
+ * Transforms a multi-system ESM file into a single unified flattened system:
+ * every variable dot-namespaced by its owning component, every coupling rule
+ * resolved INTO the equation set, and the registries a consumer needs
+ * (`index_sets`, `function_tables`, the merged `template_registry`) carried
+ * along so the flattened form is self-describing.
+ *
+ * ## The canonical field set (esm-libraries-spec §4.7.5 step 4, `esm: 1.0.0`)
+ *
+ * Step 4's field table is a CROSS-BINDING CONTRACT, not a suggestion: the
+ * canonical `snake_case` names transliterate to `camelCase` here per
+ * API_SPEC.md §2, and the shared corpus `tests/conformance/flatten/cases.json`
+ * (generated from the Python oracle) pins every field of it, INCLUDING ORDER.
+ *
+ * Three rules from that section drive shapes this module would otherwise get
+ * wrong, and each cost a real defect before it was written down:
+ *
+ *  - **The parameter subsets partition `parameters`; they are not siblings of
+ *    it.** esm-spec §6.3.1 says `brownian_parameters` / `discrete_parameters` /
+ *    `sampled_parameters` / `constant_parameters` *partition the parameters*, so
+ *    a `wiener`-updated entry appears in BOTH {@link FlattenedSystem.parameters}
+ *    and {@link FlattenedSystem.brownianParameters}. This binding used to
+ *    EXCLUDE it (under the old name `brownianVariables`), which made the
+ *    parameter vector's LENGTH depend on whether the model happened to be
+ *    stochastic and left the four sets partitioning nothing.
+ *  - **`algebraicVariables` is a SUBSET of `stateVariables`.** `stateVariables`
+ *    is the SOLVED-FOR VECTOR (an implementation axis), not §6.3.1's
+ *    classification of the unknowns; a DAE solves for its algebraic unknowns, so
+ *    they ride in the vector.
+ *  - **`fieldIcs` entries are REMOVED from `equations`.** An initial condition is
+ *    a datum, not an equation of motion.
+ *
+ * ## Ordering is observable
+ *
+ * Every ordered map and list below is in DOCUMENT ORDER: components in the order
+ * the file declares them (models first, then reaction systems), and within a
+ * component the order it declares its variables; a coupling-merged entry keeps
+ * the position of its first occurrence. A parameter vector is positional, so
+ * lexicographic sorting or host-map iteration order is NON-CONFORMING. The
+ * `name -> variable` maps are plain objects, whose string-key insertion order
+ * JavaScript preserves.
+ *
+ * The Python binding (`pkg/earthsci-ast-py`) is the flatten oracle; this module
+ * mirrors its semantics function for function.
  */
 
 /** 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.
+ * Base class for every error {@link flatten} raises. Mirrors Rust's
+ * `FlattenError` and Python's `FlattenError` for cross-language error-name
+ * parity.
  */
-interface FlattenedEquation {
-    /** Dot-namespaced LHS variable name (e.g., "Atmos.O3") */
-    lhs: string;
+declare class FlattenError extends EsmDiagnosticError {
+    constructor(message: string, code?: string);
+}
+/**
+ * Two systems define non-additive equations for the same dependent variable —
+ * the §4.7.5 over-determination check. Such a system is over-determined: one
+ * contribution to `d[X]/dt` would silently shadow the other.
+ */
+declare class ConflictingDerivativeError extends FlattenError {
+    constructor(message: string);
+}
+/**
+ * A `couple` connector equation with `transform: "multiplicative"` targets
+ * something with no tendency to multiply.
+ *
+ * esm-spec §10.3 and esm-libraries-spec §4.7.2 define `multiplicative` against
+ * the target's EXISTING ODE right-hand side. When `to` names a parameter, an
+ * observed, an algebraic unknown, or an undefined name, there is no `D(to)` and
+ * the operation has no meaning.
+ *
+ * Silently dropping the connector equation — what this binding did before — is
+ * the one outcome a coupling mis-specification must not have: the document
+ * declares a coupling and the flattened system carries no trace of it.
+ *
+ * `additive` has no counterpart error because zero is the additive identity, so
+ * an additive term against an absent tendency simply becomes the tendency.
+ */
+declare class CoupleMultiplicativeNoTendencyError extends FlattenError {
+    constructor(message: string);
+}
+/**
+ * An `operator_compose` entry merged NOTHING (esm-libraries-spec §4.7.1 step 5).
+ *
+ * Such an entry is indistinguishable from one that is not there: the operator
+ * integrates a private, decoupled system from its own defaults, the other system
+ * receives no contribution at all, and the only evidence is a state count one too
+ * high. That is the one outcome a coupling mis-specification must not have, so it
+ * is refused rather than reported.
+ *
+ * An operator that genuinely contributes only states of its own — a transport
+ * operator whose single equation defines its own wind field, say — says so with
+ * `require_match: false`, and is then permitted.
+ */
+declare class OperatorComposeNoMergeError extends FlattenError {
+    constructor(message: string);
+}
+/**
+ * An `operator_compose` entry declared `require_match: true` and one of
+ * `systems[1]`'s equations found no equation of `systems[0]` to land on
+ * (esm-libraries-spec §4.7.1 step 5).
+ *
+ * Step 5 otherwise preserves an unmatched equation unchanged, and a PARTIAL
+ * shortfall is only a warning by default; `require_match` is the author's opt-in
+ * to make it fatal. A PARTIAL match throws here — there is no "some is enough"
+ * reading an author could rely on.
+ */
+declare class OperatorComposeRequireMatchError extends FlattenError {
+    constructor(message: string);
+}
+/**
+ * The bare-name fallback would unify two STATE variables and the document has
+ * not said which spelling survives (esm-libraries-spec §4.7.1 step 3).
+ *
+ * The fallback binds `A.x` to `B.x` on the strength of a shared local name alone.
+ * When both are states, each carries its own INITIAL CONDITION, and the merge has
+ * to delete one of them — so the choice decides which IC the flattened system
+ * integrates from. Nothing in the document expresses that choice, and picking one
+ * silently is how flipping the entry's `systems` order came to change the answer.
+ *
+ * A match where only ONE side is a state is NOT ambiguous: the other carries no
+ * initial condition, so the state is the owner and the merge renames onto it.
+ */
+declare class OperatorComposeAmbiguousBareNameError extends FlattenError {
+    constructor(message: string);
+}
+/**
+ * An `identity`-transform `variable_map` bridges two variables whose declared,
+ * non-empty units differ (esm-libraries-spec §4.7.6). `conversion_factor` and
+ * `param_to_var` are exempt: the first declares the conversion explicitly, the
+ * second does not imply unit equivalence at the mapping site.
+ */
+declare class DomainUnitMismatchError extends FlattenError {
+    constructor(message: string);
+}
+/**
+ * A variable or equation cannot be promoted onto the target grid — raised by the
+ * §10.5 pointwise spatial lift when a species' operator makearrays yield no
+ * full-rank interior-stencil gather.
+ */
+declare class DimensionPromotionError extends FlattenError {
+    constructor(message: string);
+}
+/**
+ * The DERIVED role of a flattened variable (esm-spec §6.3.1) — never a declared
+ * type, which from 1.0.0 is only `unknown` or `parameter`.
+ *
+ * - `state` — solved for and defined by no equation of its own: an ODE state or
+ *   an algebraic unknown.
+ * - `observed` — an unknown an equation DEFINES, at either LHS spelling. A
+ *   scalar one is eliminable by inlining and appears in `observedVariables`
+ *   alone; an arrayed one materializes into a buffer and appears in
+ *   `stateVariables` too, keeping this role in both (esm-libraries-spec §4.7.5
+ *   step 4: `stateVariables` is the solved-for vector, not a classification).
+ * - `parameter` — a parameter of any cadence.
+ * - `species` — a reaction-system state (a `state` that came from a species).
+ */
+type FlattenedVariableRole = 'state' | 'parameter' | 'observed' | 'species';
+/**
+ * One variable of the flattened system, carrying the COMPLETE declared metadata
+ * step 4 requires ("Full metadata, not names"): a consumer must be able to build
+ * a solver problem from the flattened form alone, without re-reading the source
+ * document.
+ */
+interface FlattenedVariable {
+    /** Dot-namespaced name, e.g. `"OU.theta"`. */
+    name: string;
+    /** The DERIVED role — see {@link FlattenedVariableRole}. */
+    type: FlattenedVariableRole;
+    units?: string;
+    /** For an unknown, its value at t=0; for a parameter, its constant value. */
+    default?: number;
+    description?: string;
+    /** The namespaced prefix of the component that declared it. */
+    sourceSystem?: string;
+    /** Ordered index-set names for an arrayed variable; absent means scalar. */
+    shape?: 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;
+     * The declared cadence machinery (parameters only), with its expression
+     * slots — a `condition` / `crossing` `when` and the value `expression` —
+     * namespaced like any other reference (§4.7.5 step 2).
+     */
+    update?: ParameterUpdateSpec;
+    /** The declared sampling law, carried verbatim (parameters only). */
+    distribution?: Distribution;
+}
+/**
+ * An insertion-ORDERED map from namespaced name to variable. Order is part of
+ * the cross-binding contract (see the module doc); JavaScript preserves the
+ * insertion order of string keys that do not look like array indices, which a
+ * dot-namespaced variable name never does.
+ */
+type FlattenedVariableMap = Record<string, FlattenedVariable>;
+/**
+ * A data-fed PARAMETER lowered to a flattened array input (esm-spec §8.5).
+ *
+ * From 1.0.0 a data source is not a component: a model consumes one by declaring
+ * a parameter whose `update` is `{kind: "data", source, from: {file_variable}}`.
+ * The parameter IS the loaded field and owns the units; this descriptor is what
+ * lets a simulator execute the source at its cadence and bind the resulting
+ * array into the RHS as a read-only input.
+ */
+interface LoaderField {
+    /** The namespaced parameter symbol, e.g. `"Plume.wind"`. */
+    name: string;
+    /** The owning component's namespaced prefix, e.g. `"Plume"`. */
+    owner: string;
+    /** The `data_sources` key the parameter's `update` names. */
+    subkey: string;
+    /** The source-file variable the binding names. */
+    var: string;
+    /** The resolved `data_sources` entry (carries kind / source / temporal). */
+    dataSource: DataSource;
+    /**
+     * Source-seeded cadence (CONFORMANCE_SPEC §5.7.2): a source WITH a `temporal`
+     * block is time-varying (`discrete`); one without is read once (`const`).
+     */
+    cadence: 'const' | 'discrete';
+    /** The binding's declared `unit_conversion` (§8.5), when the document has one. */
+    unitConversion?: Expression;
 }
 /**
- * Metadata describing the origin of the flattened system.
+ * A single equation of the flattened system, with dot-namespaced Expression
+ * TREES.
+ *
+ * ### Breaking change in `esm 1.0.0`
+ *
+ * `lhs` / `rhs` used to be pretty-printed STRINGS produced by a flatten-local,
+ * fully-parenthesizing printer. They are now the canonical Expression AST, which
+ * is what every other binding carries and what the shared corpus pins (rendered
+ * through the shared `toAscii`). A caller that wants text calls `toAscii` on
+ * them — one renderer for the whole toolkit rather than a second, subtly
+ * different one living here.
  */
+interface FlattenedEquation {
+    /** Dot-namespaced LHS, e.g. `D(Atmos.O3, t)` or a bare `Atmos.total`. */
+    lhs: Expression;
+    /** Dot-namespaced RHS, with coupling contributions merged in. */
+    rhs: Expression;
+    /** 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 */
+    /** Names of all top-level source systems, in document order. */
     sourceSystems: string[];
-    /** Human-readable descriptions of coupling rules applied */
+    /** Human-readable descriptions of every coupling rule, in array order. */
     couplingRules: string[];
+    /** `operator_apply` entries, recorded as opaque runtime references. */
+    operatorApplies: string[];
+    /** `callback` entries, recorded as opaque runtime references. */
+    callbacks: string[];
+    /**
+     * Every state spelling an `operator_compose` renaming match DELETED, mapped
+     * onto the survivor it was folded into (issue #230).
+     *
+     * The flattener's own retarget reaches equation ASTs; this is the map a
+     * CONSUMER that addresses a state by name needs — a `parameter_overrides` /
+     * `initial_conditions` key, an output selection — to resolve a spelling the
+     * merge moved out from under it. Empty for a document with no renaming merge,
+     * which is the overwhelming majority.
+     */
+    mergedVariableRenames: Record<string, string>;
+    /**
+     * Every name a COUPLING rule rewrote OUT of the flattened equations: a
+     * `variable_map`'s substituted target, plus every merged-away spelling of
+     * {@link FlattenMetadata.mergedVariableRenames}.
+     *
+     * Only the registry guard reads it. A surviving `expression_templates` body
+     * is authored source that no equation walk reaches, so a body naming one of
+     * these is REFUSED rather than resolved (see `checkRegistryCouplingRewrites`,
+     * CONFORMANCE_SPEC §5.35). Unlike `mergedVariableRenames` this is not a
+     * consumer-facing map: it says a name is GONE, not where it went.
+     */
+    couplingRewrittenNames: Set<string>;
+}
+/** A deferred `ic` equation (esm-spec §11.4.1): an initial condition, not dynamics. */
+interface FieldInitialCondition {
+    /** The namespaced state the condition pins. */
+    state: string;
+    /** The value at t=0. */
+    expr: Expression;
 }
 /**
- * A fully flattened representation of a coupled ESM system.
+ * A fully flattened representation of a coupled ESM system — the canonical
+ * field set of esm-libraries-spec §4.7.5 step 4.
+ *
+ * ### Removed in `esm 1.0.0`
+ *
+ * `variables: Record<string, string>` (observed name -> expression string) is
+ * gone. It predates the canonical shape and duplicated, in a bespoke string
+ * form, information the canonical fields already carry: WHICH unknowns are
+ * observed is {@link observedVariables} (with full metadata rather than a bare
+ * name), and each one's DEFINING EXPRESSION is its equation in
+ * {@link equations}, as an AST. The coupling-derived entries it also collected
+ * are no longer a side table: a `variable_map` now performs the substitution and
+ * the promotion the spec calls for, so its effect is visible in `equations` and
+ * `parameters` instead. Nothing it held is lost.
+ *
+ * Python exposes a `variables` property with a DIFFERENT meaning (namespaced
+ * name -> role label); this binding deliberately does not reuse the name for a
+ * third thing.
  */
 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 */
+    /**
+     * Always contains `"t"`. A spatial axis appears only while an UNDISCRETIZED
+     * spatial differential still names it, so a discretized (array) system stays a
+     * pure ODE.
+     */
+    independentVariables: string[];
+    /**
+     * The SOLVED-FOR VECTOR: every unknown the solver advances or solves for —
+     * differential unknowns, PLUS {@link algebraicVariables}, PLUS any arrayed
+     * observed that materializes into a buffer. NOT esm-spec §6.3.1's `odeStates`.
+     */
+    stateVariables: FlattenedVariableMap;
+    /** ALL parameters of every cadence, minus any promoted by `variable_map`. */
+    parameters: FlattenedVariableMap;
+    /** Unknowns DEFINED by an equation naming them on its LHS (esm-spec §6.3.1). */
+    observedVariables: FlattenedVariableMap;
+    /**
+     * Unknowns CONSTRAINED only by an expression-LHS equation. A SUBSET of
+     * {@link stateVariables} — a DAE solves for them.
+     */
+    algebraicVariables: FlattenedVariableMap;
+    /**
+     * Parameters whose `update.kind` is `"wiener"` — the SDE noise sources. A
+     * SUBSET of {@link parameters}, not a sibling bucket (esm-spec §6.3.1).
+     */
+    brownianParameters: FlattenedVariableMap;
+    /** Parameters carrying any OTHER `update`. A SUBSET of {@link parameters}. */
+    discreteParameters: FlattenedVariableMap;
+    /**
+     * The governing equations — dynamics and constraints — coupling applied,
+     * dot-namespaced. Entries classified out into {@link fieldIcs} are REMOVED.
+     */
     equations: FlattenedEquation[];
-    /** Provenance metadata */
+    /** Continuous events, dot-namespaced. */
+    continuousEvents: ContinuousEvent[];
+    /** Discrete events, dot-namespaced. */
+    discreteEvents: DiscreteEvent[];
+    /** The file's `domain` section, unchanged, or `null`. */
+    domain: Domain | null;
+    /** Provenance metadata. */
     metadata: FlattenMetadata;
+    /** Document-scoped index-set registry; required to interpret arrayed equations. */
+    indexSets: Record<string, unknown>;
+    /** Merged function-table registry; resolves `table_lookup`. */
+    functionTables: Record<string, unknown>;
+    /**
+     * The MERGED expression-template registry (esm-spec §9.6.4 rule 7, §10.7):
+     * the union of the component registries with their bodies component-scoped
+     * FIRST, deep-equal same-name entries deduplicated at first occurrence, and
+     * non-deep-equal collisions renamed along the reference DAG.
+     */
+    templateRegistry: Record<string, unknown>;
+    /** Deferred scoped-reference / array `ic` equations (esm-spec §11.4.1). */
+    fieldIcs: FieldInitialCondition[];
+    /** Provider-served loaded fields the system consumes. */
+    loaderFields: LoaderField[];
+    /** Post-lift grid shapes for arrayed states, e.g. `{ "Chemistry.O3": [4, 2] }`. */
+    liftedShapes: Record<string, number[]>;
+    /**
+     * The system kind DERIVED from the FLATTENED system (esm-spec §6.3.1),
+     * testing `brownianParameters` FIRST — which is exactly why that bucket must
+     * survive flattening.
+     */
+    systemKind: SystemKind;
 }
 /**
- * Flatten a multi-system ESM file into a single unified system.
+ * Flatten a coupled multi-system ESM file into a single unified system
+ * (esm-libraries-spec §4.7.5).
  *
- * 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
+ * The result is the canonical intermediate representation: dot-namespaced
+ * variables carrying their full declared metadata, equations as Expression trees,
+ * coupling rules resolved INTO the equation set, and the registries needed to
+ * consume it without re-reading the source document.
  *
- * @param file - The ESM file to flatten
- * @returns A FlattenedSystem with all variables namespaced and equations unified
+ * @throws {FlattenError} when the file has no models and no reaction systems, or
+ *   when a variable carries a type esm 1.0.0 removed.
+ * @throws {ConflictingDerivativeError} when two source systems define
+ *   non-additive equations for the same dependent variable.
+ * @throws {CoupleMultiplicativeNoTendencyError} when a `couple` connector
+ *   equation with `transform: "multiplicative"` targets something with no
+ *   `D(to)` tendency to multiply (esm-spec §10.3).
+ * @throws {DomainUnitMismatchError} when an `identity` `variable_map` bridges two
+ *   variables whose declared, non-empty units differ.
  */
 declare function flatten(file: EsmFile, options?: FlattenOptions): FlattenedSystem;
 
@@ -4255,7 +5162,7 @@ declare function flatten(file: EsmFile, options?: FlattenOptions): FlattenedSyst
 /**
  * Error thrown when a circular reference is detected during subsystem resolution.
  */
-declare class CircularReferenceError extends Error {
+declare class CircularReferenceError extends EsmDiagnosticError {
     /** The chain of references that form the cycle */
     readonly chain: string[];
     constructor(chain: string[]);
@@ -4275,10 +5182,13 @@ declare class CircularReferenceError extends Error {
  * 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 {
+declare class RefLoadError extends EsmDiagnosticError {
     /** The reference path or URL that failed to load */
     readonly ref: string;
-    /** Canonical code: `unresolved_subsystem_ref` or `ambiguous_subsystem_ref`. */
+    /**
+     * Canonical code: `unresolved_subsystem_ref`, `ambiguous_subsystem_ref`, or
+     * `mount_form_unsupported` for a mount form this binding does not implement.
+     */
     readonly code: string;
     /**
      * JSON Pointer of the SUBSYSTEM ENTRY that carries the bad ref (e.g.
@@ -4300,7 +5210,7 @@ declare class RefLoadError extends Error {
  * 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>;
+declare function resolveSubsystemRefs(file: EsmFile, basePath: string, loaderMetaparameters?: Readonly<Record<string, number>>): 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
@@ -4313,7 +5223,7 @@ declare function resolveSubsystemRefs(file: EsmFile, basePath: string): Promise<
  * 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`).
+ * `_ephemeral_injected_file` (`EarthSciAST.jl/src/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
@@ -4321,6 +5231,181 @@ declare function resolveSubsystemRefs(file: EsmFile, basePath: string): Promise<
  */
 declare function ephemeralInjectedFile(file: EsmFile | null, sourcePath: string | null, mname: string, imports: readonly unknown[], baseDir: string): Promise<EsmFile>;
 
+/**
+ * Build-time reference resolution for the semiring-FAQ unified IR: the
+ * intra-document node-id / index-set dependency DAG.
+ *
+ * Not to be confused with `./ref-loading.js`, which inlines cross-file
+ * `{ "ref": ... }` subsystem mounts at load time — this module never touches
+ * the filesystem; it wires id-addressed edges inside ONE document.
+ *
+ * It implements *node addressing* and *reference-edge resolution* — the hard
+ * prerequisite the §6.1 cadence-partition pass of the
+ * `semiring-faq-unified-ir` RFC calls out:
+ *
+ * > "node addressing — referencing a node by id — is a hard prerequisite: the
+ * > pass cannot be built until `from_faq` and join references are real edges
+ * > in this DAG."
+ *
+ * Three kinds of name/id reference become real, queryable graph edges
+ * (RFC §6.1 "Propagation"):
+ *
+ * - an aggregate node → an index set it iterates (`ranges[*].from`);
+ * - a `kind: "derived"` index set → its `from_faq` node (by stable id);
+ * - an aggregate `join.on` factor → the factor it names.
+ *
+ * Like the Julia, Python, Rust and Go passes, this one walks the RAW parsed
+ * document rather than the typed layer: `index_sets`, node `id`,
+ * `ranges[*].from` and `join` are exactly the fields the typed layer drops, so
+ * working the raw shape is what keeps the five bindings in step.
+ *
+ * PORTED FROM the Python binding (`earthsci_ast/reference_resolution.py`),
+ * which is the most complete of the four: it registers every node BEFORE
+ * resolving any reference (a two-step walk), so a `join.on` or `from_faq` may
+ * name a node that appears later in the document. Rust's single-pass
+ * `register_and_process` cannot do that. Vertex keys, edge kinds, error codes
+ * and message shapes follow Python byte for byte.
+ */
+
+/**
+ * A reference could not be resolved, or the reference graph has a cycle.
+ *
+ * Carries the stable `code` (one of the `E_REF_*` constants above) so callers
+ * and the cross-binding conformance suite can assert on the failure mode. For a
+ * cycle, `cycle` holds the offending vertex-key path.
+ */
+declare class ReferenceResolutionError extends EsmDiagnosticError {
+    code: string;
+    readonly cycle: string[] | undefined;
+    constructor(code: string, message: string, cycle?: string[]);
+}
+/** The three kinds of vertex in the reference graph. */
+declare const VertexKind: {
+    readonly NODE: "node";
+    readonly INDEX_SET: "index_set";
+    readonly FACTOR: "factor";
+};
+type VertexKind = (typeof VertexKind)[keyof typeof VertexKind];
+/** The three kinds of reference edge (RFC §6.1 "Propagation"). */
+declare const EdgeKind: {
+    /** aggregate node → the index set it iterates (`ranges[*].from`). */
+    readonly RANGE_FROM: "range_from";
+    /** `kind: "derived"` index set → the node that materializes it (`from_faq`). */
+    readonly FROM_FAQ: "from_faq";
+    /** aggregate node → a factor named by `join.on`. */
+    readonly JOIN_FACTOR: "join_factor";
+};
+type EdgeKind = (typeof EdgeKind)[keyof typeof EdgeKind];
+/**
+ * A vertex in the reference graph, addressed by a kind-namespaced `key`.
+ *
+ * `key` is `` `${kind}:${name}` ``. For a `node` vertex, `name` is the node's
+ * stable address: its explicit `id` when it has one, else its structural path
+ * (e.g. `equations/0/rhs/expr`).
+ */
+interface ReferenceVertex {
+    key: string;
+    kind: VertexKind;
+    name: string;
+    op?: string;
+    nodeId?: string;
+    path?: string;
+}
+/** A directed `source → target` edge: *source references / depends on target*. */
+interface ReferenceEdge {
+    source: string;
+    target: string;
+    kind: EdgeKind;
+}
+type RawObject = Record<string, unknown>;
+/**
+ * The resolved reference DAG for one model — the partition pass's input.
+ *
+ * Vertices are keyed by their kind-namespaced `key`. Edges point from a vertex
+ * to a vertex it *depends on*, so a bottom-up {@link topologicalOrder} walk
+ * visits each vertex after its dependencies — exactly the order
+ * `class(n) = max(class(inputs))` propagation needs.
+ */
+declare class ReferenceGraph {
+    readonly model: string;
+    /** Insertion-ordered `key -> vertex`. */
+    readonly vertices: Map<string, ReferenceVertex>;
+    readonly edges: ReferenceEdge[];
+    private readonly out;
+    private readonly inn;
+    constructor(model?: string);
+    /** @internal */
+    ensureVertex(vertex: ReferenceVertex): void;
+    /** @internal */
+    addEdge(source: string, target: string, kind: EdgeKind): void;
+    /** Vertices `key` references / depends on (its out-neighbours). */
+    dependencies(key: string): string[];
+    /** Vertices that reference / depend on `key` (its in-neighbours). */
+    dependents(key: string): string[];
+    edgesOfKind(kind: EdgeKind): ReferenceEdge[];
+    /**
+     * A reference cycle as a vertex-key path, or `null` if acyclic.
+     *
+     * Three-colour DFS over the dependency edges, traversing sorted keys and
+     * sorted neighbours so the reported path is deterministic and matches the
+     * other bindings. The returned path is `[v, …, v]` (the repeated vertex
+     * closes the cycle).
+     */
+    detectCycle(): string[] | null;
+    /**
+     * Bottom-up order (dependencies before dependents).
+     *
+     * Throws {@link ReferenceResolutionError} (`E_REF_CYCLE`) if the graph is
+     * cyclic — a cycle among reference edges is an out-of-scope
+     * implicit/iterative solve (RFC §6.1 "Acyclicity").
+     */
+    topologicalOrder(): string[];
+}
+/**
+ * Resolve the reference edges of ONE `model` into a {@link ReferenceGraph}.
+ *
+ * @param model - the raw model object (as parsed, not the typed layer)
+ * @param modelName - the model's key in the document, used in diagnostics
+ * @param indexSets - the DOCUMENT-SCOPED `index_sets` registry. `esm-schema.json`
+ *   declares `index_sets` only at document scope: since v0.8.0 it is a sibling
+ *   of `models` rather than nested inside each model, and 1.0.0 keeps it there.
+ *   {@link resolveReferences} reads it once from the document root and threads
+ *   it into every model, which is how a caller normally arrives here. It is an
+ *   OPTIONAL TRAILING argument — not a separate function, and not required
+ *   (API_SPEC.md §8 item 17). A model-nested `index_sets` key (pre-0.8.0) is
+ *   merged ON TOP, so a model-level entry wins a key collision, matching Go and
+ *   Rust exactly. Reading ONLY the nested key is the Julia bug §8 item 17
+ *   records — it threw on any 1.0.0 document with a top-level registry — and
+ *   this binding does not reproduce it.
+ *
+ * Throws {@link ReferenceResolutionError} on a duplicate node id, an undeclared
+ * `ranges[*].from` index set, a `from_faq` naming no node, or an unresolved
+ * `join.on` factor. Cycles are reported lazily by
+ * {@link ReferenceGraph.topologicalOrder}, or eagerly by
+ * {@link resolveReferences}.
+ *
+ * `from_faq` resolves at DOCUMENT scope (esm-spec.md §9.7.5). A caller holding
+ * one model gets that model as its own document, which is the right answer for
+ * a one-model document; {@link resolveReferences} is the document-scoped entry
+ * point and resolves against every model's nodes.
+ */
+declare function buildReferenceGraph(model: Model | RawObject, modelName?: string, indexSets?: Record<string, unknown>): ReferenceGraph;
+/**
+ * Resolve reference edges for EVERY model in `document`.
+ *
+ * Returns a `modelName -> ReferenceGraph` map. Throws
+ * {@link ReferenceResolutionError} on any unresolved reference *or* reference
+ * cycle (each model's graph is checked acyclic eagerly here).
+ *
+ * The document-scoped `index_sets` registry is read once from the top level and
+ * threaded into every model, so a caller never assembles it by hand.
+ *
+ * Node ids are collected from EVERY model first, so a derived index set's
+ * `from_faq` may name a producer in any model (esm-spec.md §9.7.5) and a
+ * duplicate id anywhere in the document is an error.
+ */
+declare function resolveReferences(document: EsmFile | RawObject): Map<string, ReferenceGraph>;
+
 /**
  * Canonical AST form per discretization RFC §5.4.
  *
@@ -4356,7 +5441,7 @@ declare function canonicalJson(expr: Expr): string;
  * emitted as bare JSON integers by {@link canonicalJson} directly.
  *
  * NAMING: distinct from `formatFloatToken` in `./numeric-literal` (the
- * document-serialization emitter used by `save()` / `losslessJsonStringify`).
+ * document-serialization emitter used by `toJson()` / `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
@@ -4381,13 +5466,14 @@ declare function formatCanonicalFloat(f: number): string;
  * 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 {
+declare class ClosedFunctionError extends EsmDiagnosticError {
     code: ClosedFunctionErrorCode;
     constructor(code: ClosedFunctionErrorCode, message: string);
 }
@@ -4427,7 +5513,19 @@ declare function interpLinear(table: readonly number[], axis: readonly number[],
  * `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). */
+/**
+ * Names that bindings MUST recognize (derived from the dispatch table keys).
+ *
+ * A FUNCTION, matching Julia's `closed_function_names()`, Rust's
+ * `closed_function_names()` and Go's `ClosedFunctionNames()` — API_SPEC.md §8
+ * item 4. TypeScript alone exposed this as a constant array, so a caller
+ * writing binding-agnostic code had to special-case it.
+ */
+declare function closedFunctionNames(): readonly string[];
+/**
+ * @deprecated Use {@link closedFunctionNames}. Kept for one minor per
+ * API_SPEC.md §10; removed at the next major.
+ */
 declare const CLOSED_FUNCTION_NAMES: readonly string[];
 /**
  * Resolve a closed-function name + already-evaluated positional args into a
@@ -4454,13 +5552,13 @@ declare function dispatchClosedFunction(name: string, args: unknown[]): number;
  * 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.
+ *   - `unknown_enum` — reference to an enum name not present in the file's
+ *     top-level `enums` block (esm-spec §4.5).
+ *   - `unknown_enum_symbol` — reference to an unknown member of a declared
+ *     enum (esm-spec §4.5).
  */
 
-declare class EnumLoweringError extends Error {
+declare class EnumLoweringError extends EsmDiagnosticError {
     code: string;
     constructor(code: string, message: string);
 }
@@ -4471,19 +5569,6 @@ declare class EnumLoweringError extends Error {
  */
 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).
@@ -4697,9 +5782,25 @@ interface TemplateResolveOptions {
     /**
      * 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.
+     * reference). Supplied by the `load*` entry points; optional for direct/raw use.
      */
     validateSchema?: ((raw: unknown) => TemplateSchemaError[]) | undefined;
+    /**
+     * Metaparameter names declared by the documents this one MOUNTS (esm-spec
+     * §4.7, either mount form, transitively) — see
+     * {@link collectMountDeclaredMetaparameters}. Widens the §9.7.6 site-4
+     * check: a loader-API binding naming one of these is meaningful even though
+     * THIS document does not declare it, because the mount edge forwards it into
+     * the leaf's own close.
+     */
+    mountDeclared?: ReadonlySet<string> | undefined;
+    /**
+     * This call IS a §4.7 mount edge, so index-set sizes this scope cannot close
+     * stay symbolic for the MOUNTING document's registry to close (§9.7.6 site
+     * 5) instead of being `metaparameter_unbound` here. A root document leaves it
+     * unset.
+     */
+    mountedLeaf?: boolean | undefined;
 }
 /**
  * `expression_template_imports`, top-level `expression_templates`
@@ -4754,5 +5855,70 @@ declare function emitDocument(rawSource: unknown, basePath: string, options?: Te
  */
 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 };
+/**
+ * Document-scoped solver hints (esm-spec §2.2).
+ *
+ * The `solver` block records numerics the document knows about *itself* —
+ * stiffness, integration tolerances, and a splitting hint — which each binding
+ * maps to its own integrator.
+ *
+ * Every field is ADVISORY: a binding may ignore any or all of them and still
+ * conform. Advisory governs the MECHANISM, never the OUTCOME — the
+ * CONFORMANCE_SPEC §5.9 requirement to integrate successfully and agree within
+ * the error band is untouched by this block and is not excused by it.
+ *
+ * This module carries the parts that are NOT advisory: the spec-version gate
+ * (§2.2.4) and the §2.2.2 tolerance resolution order. TypeScript ships no
+ * integrator, so `resolveTolerances` exists for parity and for callers driving
+ * another runtime.
+ */
+
+/** Binding defaults (API_SPEC §5.8) — the bottom of the §2.2.2 chain. */
+declare const DEFAULT_RELTOL = 0.0001;
+declare const DEFAULT_ABSTOL = 0.000001;
+/**
+ * Reject a top-level `solver` block in a file declaring esm < 1.1.0.
+ *
+ * The block arrives at `esm: 1.1.0`; a document declaring an earlier version
+ * that carries one is rejected with `solver_version_too_old` (esm-spec
+ * §2.2.4). Mirrors `rejectTemplateImportsPreV08`.
+ */
+declare function rejectSolverPreV11(view: unknown): void;
+/**
+ * Resolve integration tolerances most-specific first (esm-spec §2.2.2):
+ *
+ * 1. An explicit argument at the call site — wins outright.
+ * 2. Otherwise the document's `solver.abstol` / `solver.reltol`.
+ * 3. Otherwise the binding default (`reltol` 1e-4, `abstol` 1e-6).
+ *
+ * The two resolve INDEPENDENTLY, so a document declaring only `reltol` leaves
+ * `abstol` on the default — the same per-field fall-through §6.6.4 uses.
+ *
+ * These are INTEGRATION tolerances, a different quantity from the `tolerance`
+ * object an assertion is COMPARED at (§6.6.4).
+ */
+declare function resolveTolerances(solver: Solver | undefined | null, opts?: {
+    abstol?: number;
+    reltol?: number;
+}): {
+    abstol: number;
+    reltol: number;
+};
+
+/**
+ * The package's OWN version — distinct from {@link SCHEMA_VERSION}, which is
+ * the `.esm` FORMAT version this build implements. The two are unrelated
+ * numbers and used to be conflated: `VERSION` meant the schema version here
+ * and the package version in Rust, so the same name read two different
+ * things depending on which binding you were in. `VERSION` is gone; every
+ * binding now exposes exactly `SCHEMA_VERSION` and `LIBRARY_VERSION`.
+ *
+ * package.json is the source of truth. It cannot be imported here —
+ * tsconfig's `rootDir` is `./src`, and a runtime read would break browser
+ * hosts — so the value is mirrored, and `version.test.ts` fails the build if
+ * the mirror drifts. Same arrangement Rust uses for its `SCHEMA_VERSION`.
+ */
+declare const LIBRARY_VERSION = "0.3.0";
+
+export { CLOSED_FUNCTION_NAMES, CadenceCycleError, CadenceSeeder, CanonicalNonfiniteError, CanonicalizeError, CircularReferenceError, ClosedFunctionError, ConflictingDerivativeError, CoupleMultiplicativeNoTendencyError, DEFAULT_ABSTOL, DEFAULT_MIN_COMPLEXITY, DEFAULT_RELTOL, DimensionPromotionError, DomainUnitMismatchError, ERROR_CODES, E_CANONICAL_DIVBY_ZERO, E_CANONICAL_NONFINITE, EdgeKind, EntityNotFoundError, EnumLoweringError, EsmDiagnosticError, EsmMachineryError, EvaluatorError, expandDocument as Expand, ExpressionParseError, EsmMachineryError as ExpressionTemplateError, FlattenError, InvalidDerivativeOrderError, LIBRARY_VERSION, LosslessJsonParseError, MAX_TEMPLATE_EXPANSION_DEPTH, MigrationError, NonDifferentiableExpressionError, OperatorComposeAmbiguousBareNameError, OperatorComposeNoMergeError, OperatorComposeRequireMatchError, ParseError, RefLoadError, ReferenceGraph, ReferenceResolutionError, SCHEMA_VERSION, SchemaValidationError, UnevaluableOperatorError, UnitConversionError, UnloweredOperatorError, VariableInUseError, VertexKind, addContinuousEvent, addCoupling, addDiscreteEvent, addEquation, addReaction, addSpecies, addVariable, algebraicUnknowns, analyzeComplexity, analyzeExpression, applyScopeInjections, authoredTemplateNames, brownianParameters, buildDependencyGraph, buildEmittedDocument, buildReferenceGraph, canMigrate, canonicalJson, canonicalize, checkDimensions, classifyComplexity, classifyDocument, classifyModel, closedFunctionNames, compareComplexity, compileExpression, componentExists, componentGraph, compose, constantParameters, contains, convertUnits, declaredSystemKind, deriveODEs, deriveOdes, detectStabilityIssues, differentiate, discreteParameters, dispatchClosedFunction, effectiveSystemKind, 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, loadDocument, loadPath, loadString, losslessJsonParse, losslessJsonStringify, lowerEnums, lowerExpressionTemplates, mapVariable, merge, migrate, numericValue, observedDefinitions, observedUnknowns, odeStates, parameterClass, parameters, parseEquation, parseExpression, parseReaction, parseUnit, parseUnitForConversion, partialDerivatives, productMatrix, rejectExpressionTemplatesPreV04, rejectSolverPreV11, rejectTemplateImportsPreV08, removeCoupling, removeEquation, removeEvent, removeReaction, removeSpecies, removeVariable, renameVariable, resolveReferences, resolveSubsystemRefs, resolveTemplateMachinery, resolveTolerances, sampledParameters, searchsortedFirst, simplify, stoichiometricMatrix, substitute, substituteInEquations, substituteInModel, substituteInReactionSystem, substrateMatrix, supportedMigrationTargets, systemKind, toAscii, toDot, toJson, toJsonCompact, toJsonGraph, toLatex, toMathML, toMermaid, toUnicode, tryParseUnit, unitsCompatible, unknowns, updateRules, validate, validateInterpAxis, validateSchema, validateSearchsortedTable, validateText, validateUnits, writePath };
+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, ErrorCode, EsmFile, Expr, ExprNode, ExprNodeOf, Expression, ExpressionLocation, ExpressionNode, ExpressionNode1, ExpressionTemplate, FieldInitialCondition, FlattenMetadata, FlattenOptions, FlattenedEquation, FlattenedSystem, FlattenedTemplateRegistries, FlattenedVariable, FlattenedVariableMap, FlattenedVariableRole, FunctionTable, FunctionTableAxis, FunctionalUpdate, Graph, IndexSet, IndexSet1, LoadOptions, LoaderField, LognormalDistribution, Metadata, MetaparameterExpression, Metaparameters, Model, ModelClassification, ModelVariable, ModelVariable1, NonWienerParameterUpdate, NormalDistribution, NumericArrayLiteral, NumericLiteral, Parameter, Parameter1, ParameterClass, ParameterSweep, ParameterUpdate, ParameterUpdateSpec, ParsedUnit, Plot, Plot1, PlotAxis, PlotSeries, PlotValue, Reaction, ReactionSystem, Reference, ReferenceEdge, ReferenceVertex, RemeshUpdate, ScheduleUpdate, SchemaError, Solver, Species, StabilityIssue, StoichiometryEntry, SubsystemRef, SweepDimension, SweepDimension1, SweepRange, SystemKind, TemplateImport, TemplateResolveOptions, TemplateSchemaError, Test, TimeSpan, ToJsonOptions, Tolerance, Tolerance1, Tolerance2, Tolerance3, TranslateTarget, UniformDistribution, UnitResult, UnitWarning, UnknownClass, UpdateValueForm, ValidationError, ValidationResult, VariableKind, VariableNode, WienerUpdate };