@earthsciml/ast 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -1669,6 +1669,121 @@ 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 DOMAIN_UNIT_MISMATCH: "domain_unit_mismatch";
+    readonly COUPLE_MULTIPLICATIVE_NO_TENDENCY: "couple_multiplicative_no_tendency";
+    readonly RELATIONAL_NODE_IN_CONTINUOUS: "relational_node_in_continuous";
+    readonly UNDEFINED_INDEX_SET: "undefined_index_set";
+    readonly INVALID_BROADCAST_FN: "invalid_broadcast_fn";
+    readonly ARRAY_SHAPE_MISMATCH: "array_shape_mismatch";
+    readonly EQUATION_COUNT_MISMATCH: "equation_count_mismatch";
+    readonly EVENT_AFFECTS_PARAMETER: "event_affects_parameter";
+    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 UNDEFINED_PARAMETER: "undefined_parameter";
+    readonly UNDEFINED_SPECIES: "undefined_species";
+    readonly UNDEFINED_SYSTEM: "undefined_system";
+    readonly UNDEFINED_VARIABLE: "undefined_variable";
+    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 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_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 GEOMETRY_MANIFOLD_INVALID: "geometry_manifold_invalid";
+    readonly MAKEARRAY_REGION_INVERTED: "makearray_region_inverted";
+    readonly SUBSYSTEM_INDEX_SET_CONFLICT: "subsystem_index_set_conflict";
+    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 ENUM_NOT_DECLARED: "enum_not_declared";
+    readonly ENUM_MEMBER_NOT_FOUND: "enum_member_not_found";
+    readonly UNKNOWN_CLOSED_FUNCTION: "unknown_closed_function";
+    readonly CLOSED_FUNCTION_ARITY: "closed_function_arity";
+    readonly CLOSED_FUNCTION_OVERFLOW: "closed_function_overflow";
+};
+/** 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 +1811,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 +1831,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 +1857,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 +1899,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
@@ -1807,11 +1923,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 +1991,35 @@ 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>;
 };
-/** @deprecated Prefer {@link EsmFile}. Identical to the generated `ESMFormat`. */
-type EsmFormat = ESMFormat;
 /** @deprecated Prefer {@link ExpressionNode} (the generated name). */
 type ExprNode = ExpressionNode;
 
@@ -2098,6 +2259,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;
@@ -2113,7 +2275,7 @@ interface ParsedUnit {
     scale: number;
     offset?: number;
 }
-declare class UnitConversionError extends Error {
+declare class UnitConversionError extends EsmDiagnosticError {
     constructor(message: string);
 }
 /**
@@ -2376,14 +2538,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 +2561,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 +2628,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 +2692,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 +2701,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 +2722,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 +2811,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 +2884,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 +2918,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 +2967,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 +3049,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[]);
 }
@@ -2907,6 +3168,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 +3177,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 +3213,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 +3231,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 +3253,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 +3265,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 +3293,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 +3631,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 +3739,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.
@@ -3537,9 +3810,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 +3828,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 +3971,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 +4016,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 +4035,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 +4043,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);
@@ -4016,8 +4297,8 @@ 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: 'unlowered_operator';
     constructor(message: string);
 }
 /**
@@ -4033,8 +4314,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);
 }
 /**
@@ -4089,7 +4369,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 +4384,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 +4449,321 @@ 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 `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: an ODE state, an algebraic unknown, or an arrayed
+ *   observed that materializes into a buffer.
+ * - `observed` — an unknown a bare-variable-LHS equation defines, eliminable by
+ *   inlining.
+ * - `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[];
+    /** The declared cadence machinery, carried verbatim (parameters only). */
+    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;
     /**
-     * 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;
+     * 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[];
+}
+/** 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 +4791,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,7 +4811,7 @@ 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`. */
@@ -4321,6 +4857,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 +5067,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 +5092,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 +5139,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
@@ -4460,7 +5184,7 @@ declare function dispatchClosedFunction(name: string, args: unknown[]): number;
  *     enum.
  */
 
-declare class EnumLoweringError extends Error {
+declare class EnumLoweringError extends EsmDiagnosticError {
     code: string;
     constructor(code: string, message: string);
 }
@@ -4471,19 +5195,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,7 +5408,7 @@ 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;
 }
@@ -4754,5 +5465,20 @@ 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 };
+/**
+ * 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.1.1";
+
+export { CLOSED_FUNCTION_NAMES, CadenceCycleError, CadenceSeeder, CanonicalNonfiniteError, CanonicalizeError, CircularReferenceError, ClosedFunctionError, ConflictingDerivativeError, CoupleMultiplicativeNoTendencyError, DEFAULT_MIN_COMPLEXITY, 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, ParseError, RefLoadError, ReferenceGraph, ReferenceResolutionError, SCHEMA_VERSION, SchemaValidationError, 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, rejectTemplateImportsPreV08, removeCoupling, removeEquation, removeEvent, removeReaction, removeSpecies, removeVariable, renameVariable, resolveReferences, resolveSubsystemRefs, resolveTemplateMachinery, 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, NumericLiteral, Parameter, Parameter1, ParameterClass, ParameterSweep, ParameterUpdate, ParameterUpdateSpec, ParsedUnit, Plot, Plot1, PlotAxis, PlotSeries, PlotValue, Reaction, ReactionSystem, Reference, ReferenceEdge, ReferenceVertex, RemeshUpdate, ScheduleUpdate, SchemaError, 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 };