Invariants

An invariant is a property that must remain true across all versions, platforms, and contexts. IDL defines three categories of invariants: structural invariants, which govern source syntax and composition graph shape; semantic invariants, which govern token reference integrity and type correctness; and behavioral invariants, which govern state machine completeness and composition rule compliance. Each category is enforced at a distinct compiler phase.

Structural Invariants — Parse Phase

Structural invariants are evaluated during Parse. They include: every IDL file declares exactly one module; module names match the file path; the source is grammatically well-formed according to the BNF; no circular module imports exist. Structural invariant violations are hard Parse errors. The compiler produces no AST for an input that violates a structural invariant.

Semantic Invariants — Transform Phase

Semantic invariants are evaluated during Transform. They include: all token references resolve to declared tokens of the correct tier; token alias chains resolve within three hops; no alias chain is circular; component slot graphs are acyclic; state machine transition targets are declared states; composition rules reference valid component identifiers. Semantic invariant violations are Transform errors.

Behavioral Invariants — Emit Phase

Behavioral invariants are evaluated during Emit. They include: all emitter-required token values resolve to platform-representable types; motion token values are reproducible within platform tolerance bounds; density declarations produce valid spatial multipliers for the target density level. Behavioral invariant violations during Emit are implementation failures, not specification violations — they indicate a mismatch between the emitter and the validated AST.

Invariant Stability Across Versions

Invariants MUST NOT be weakened in a minor version. A rule that prevents a class of constructs may be strengthened in a minor version (fewer valid inputs) only if the compiler emits a deprecation warning in the preceding minor version. Weakening an invariant (more valid inputs) constitutes a breaking change and requires a major version increment.