Enum StructuralErrorCode 

pub enum StructuralErrorCode {
    UndefinedVariable,
    EquationCountMismatch,
    UndefinedSpecies,
    UndefinedParameter,
    NullReaction,
    EquationDefinesParameter,
    UnboundIndexSymbol,
    EventAffectsParameter,
    UnresolvedScopedRef,
    EventVarUndeclared,
    UndefinedOperator,
    DataSourceUndefined,
    UndefinedSystem,
    OperatorVariableMissing,
    CircularDependency,
    UnitInconsistency,
    UnitParseError,
    IcInReactionSystem,
    FactorWithExpressionTransform,
    UnresolvedSubsystemRef,
    AmbiguousSubsystemRef,
    MountFormUnsupported,
    DomainUnitMismatch,
    JoinKeyInvalidType,
    JoinSideAmbiguous,
    JoinSymsUnknownSymbol,
    RaggedValuesNotGathered,
    RelationalNodeInContinuous,
    RecurrenceNotWellfounded,
    RecurrenceUnsupportedForm,
    UndefinedIndexSet,
    InvalidBroadcastFn,
    ArrayShapeMismatch,
    ObservedCycle,
    ReservedVariableName,
    UnknownOverrideKey,
    AssertionRankMismatch,
    ArrayDefaultWithoutShape,
}

Error codes for structural validation

Serialized in snake_case so the wasm-boundary JSON matches this type’s std::fmt::Display output and the cross-binding contract in tests/invalid/expected_errors.json (e.g. undefined_variable, not the default PascalCase UndefinedVariable).

Variants

UndefinedVariable

Undefined variable reference

EquationCountMismatch

Number of equations doesn’t match state variables

UndefinedSpecies

Undefined species in reactions

UndefinedParameter

Undefined parameter in expressions

NullReaction

Reaction with both substrates and products null

EquationDefinesParameter

An equation whose left-hand side names a parameter (esm-spec §6.3.1)

UnboundIndexSymbol

A left-hand-side subscript bound by no faq (esm-spec §6.3.1)

EventAffectsParameter

An event affects LHS names a PARAMETER (esm-spec §5.4/§5.5): esm 1.0.0 events may affect UNKNOWNS only, and a parameter that changes during a run declares its own update block instead.

UnresolvedScopedRef

Scoped reference cannot be resolved

EventVarUndeclared

Variable in event is not declared

UndefinedOperator

Operator referenced but not declared

DataSourceUndefined

A parameter update of kind data names a data_sources entry the document does not declare (esm-spec §8.5).

UndefinedSystem

System referenced but not declared

OperatorVariableMissing

Operator variable not available

CircularDependency

Circular dependency detected

UnitInconsistency

Reaction rate expression has incompatible units for reaction stoichiometry

UnitParseError

A declared units string denotes no real unit (esm-spec §4.8.4)

IcInReactionSystem

An ic-op equation placed inside a reaction system’s constraint_equations

FactorWithExpressionTransform

A variable_map expression transform carries a factor (esm-spec §10.4: the expression spells its own arithmetic — fold scaling into it)

UnresolvedSubsystemRef

A subsystem ref (esm-spec §4.7) that could not be resolved — a missing file, a remote URL, a cycle, or an otherwise unreadable document.

AmbiguousSubsystemRef

A subsystem ref that resolved to a file NOT containing exactly one top-level system (zero or several), so which system to mount is ambiguous.

MountFormUnsupported

A §4.7 {ref} mount at a form this binding does not implement — a top-level reaction_systems.<k> {ref}.

DomainUnitMismatch

A variable_map identity coupling whose from/to variables carry declared, non-empty, and DIFFERING units (esm-spec §4.7.6). Static mirror of the flatten-time crate::flatten::FlattenError::DomainUnitMismatch.

JoinKeyInvalidType

A faq value-equality join whose key column ranges over a categorical index set carrying a FLOAT or NULL member (RFC semiring-faq-unified-ir §5.3 / §5.7 rule 1): floats are not portably equality-comparable and a null key is unmatchable.

JoinSideAmbiguous

A join.on key whose range symbol the document does not determine (CONFORMANCE_SPEC §5.5.8).

JoinSymsUnknownSymbol

A join.syms entry that is not a range symbol of the node.

RaggedValuesNotGathered

A faq whose range iterates a kind: "ragged" index set but whose body never reads that set’s values array (esm-spec §4.3.1 “Ragged ranges”).

RelationalNodeInContinuous

A value-invention faq (distinct: true) whose key/expr reads a model STATE variable, so the cadence partition classes it CONTINUOUS — relational work is forbidden on the per-step hot path (RFC semiring-faq-unified-ir §6.1; CONFORMANCE_SPEC.md §5.7.6 guard 2).

RecurrenceNotWellfounded

A causal self-read (esm-spec §4.3.1.1) that is not a well-founded strictly-earlier read along exactly one axis: a provably same-cell or forward read, an index that is not affine in its frame symbol with coefficient 1, self-reads disagreeing on the axis, or a bare read of the variable inside its own defining RHS.

RecurrenceUnsupportedForm

A causal self-read (esm-spec §4.3.1.1) the runtime cannot restrict to a single cell: reached through a makearray region value or a reshape/transpose/concat operand, or in an equation whose RHS is not a faq over the variable’s own axes. The READ is causal; the CARRIER cannot sequence it.

UndefinedIndexSet

A faq ranges entry { "from": NAME } whose NAME is not a key of the document index_sets registry (RFC semiring-faq-unified-ir §5.2): no implicit interval is inferred for an undeclared name.

InvalidBroadcastFn

A broadcast node whose fn field is absent, does not name a scalar operator in the registry, or is applied to an argument count that operator does not accept (esm-spec §4.3.4: “the fn value MUST name a scalar operator … loading MUST fail”).

broadcast is the one op whose OPERATOR is data — the node says broadcast and the arithmetic is named by a sibling string field — so no amount of op-keyed checking reaches it. Until this code existed, {"op":"broadcast","fn":"not_a_real_op","args":[x]} validated clean and then evaluated to x (issue #101).

ArrayShapeMismatch

A BARE array-level expression whose operand is declared over an index set the result does not have (esm-spec §4.3.4). Operands of an array-level expression align by index-set NAME, so an operand declared over a SUBSET of the result’s index sets broadcasts along the missing ones; one carrying an index set the result does not carry has no axis to align to. Both shapes are declared, so this is decidable here — and it must be decided here, because the alternative is a positional flatten that produces plausible, non-NaN, zero-padded garbage.

ObservedCycle

A dependency cycle among a model’s OBSERVED unknowns (esm-spec §4.9.6): each observed on the cycle is defined in terms of the next, so no evaluation order satisfies every definition and the algebraic block is not a substitutable one. Decidable from the equations alone, so it is decided HERE — before a build reaches the cycle and reports whichever name its walk happened to try next (issue #181).

The self-edge of a §4.3.1.1 recurrence CANDIDATE is an ordering within one variable, not a dependency between two, and is dropped (CONFORMANCE_SPEC §5.19.5). Every other self-reference is a cycle of length one and is reported here.

ReservedVariableName

A DECLARATION spelled with a globally-scoped name — the document’s independent variable (domain.independent_variable, default "t") or the §6.4 _var placeholder (esm-spec §4.9.1.1).

Both names are implicitly declared in every component’s expression scope (§4.9.1) and are resolved BY NAME ahead of the declaration maps — ModelCtx::new extends defined_vars with them, and every evaluator in this crate resolves them first — so such a declaration is unreachable: the implicit symbol shadows it, not the other way round. That is why it is a hard error rather than a lint (issue #200). The reported document VALIDATED, a bare build reported the observed as having no defining expression, and a build with a subsystem mounted handed every reader of t the simulation clock, so log(t) was -inf at t = 0 and every number downstream was finite, plausible and wrong.

Reserved set defined by §4.9.1.1, shared with the sibling reserved_index_symbol binder rule, and it follows the document: renaming the independent variable moves the rejection onto the new name and frees t.

UnknownOverrideKey

An inline test’s initial_conditions / parameter_overrides key that matches no declared name under the esm-spec §6.6.2 override-key rules.

AssertionRankMismatch

An assertion whose form does not match the declared rank of the variable it names (esm-spec §6.6.5).

ArrayDefaultWithoutShape

Inline ARRAY data as the default of a variable that declares no shape — omitted, null or empty (esm-spec §6.3).

Inline array data is a SHAPED variable’s value: its nesting is matched against the declared shape, so with no shape there is nothing for it to fill and no scalar reading of it. Rejected at the declaration so the document fails to load instead of reaching a runtime that would have to drop the variable from scope or fabricate a value for it.

Trait Implementations

impl Clone for StructuralErrorCode

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for StructuralErrorCode

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for StructuralErrorCode

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for StructuralErrorCode

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Serialize for StructuralErrorCode

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.