This document lists non‑negotiable invariants the implementation preserves across backends. They’re used as a contract for testing and design.
Core
- PHI hygiene
- No empty PHI nodes are emitted in LLVM IR (temporary safety valve exists behind `NYASH_LLVM_SANITIZE_EMPTY_PHI=1`).
- All PHIs appear at the beginning of a basic block.
- Match/Peek
- A match scrutinee is evaluated exactly once, bound to an internal gensym.
- Guard conditions are logically conjoined with the arm predicate; fallthrough reaches the next arm.
- Exceptions
- Exceptions follow “scope first” semantics. Postfix `catch/cleanup` normalize to a single `TryCatch` block around the immediately‑preceding expression.
- LoopForm
- Loop bodies may be normalized where safe to a stable order: non‑assign statements then assign statements. No semantic reorder is performed when a non‑assign appears after any assign.
- Carrier analysis emits observation hints only (zero runtime cost).
- Break/continue lowering is unified via LoopBuilder; nested bare blocks inside loops are handled consistently (Program nodes recurse into loop‑aware lowering).
- Enter/Leave scope events are observable through MIR hints; they do not affect program semantics.
- Block‑scoped locals: `local x = ...` declares a binding limited to the lexical block. Assignment without `local` updates the nearest enclosing binding; redeclaration with `local` shadows the outer variable. This is Lua‑like and differs from Python's block (no) scope.
