WEP: Normalized IR (NIR) Layer

Context

The compiler pipeline from lower to wir_build runs entirely on FlatPackage with TIR-shaped function bodies:

... → link → monomorphize → erase → lower → optimize → wir_build → ...
                                    └─── FlatPackage (TIR bodies) ───┘

lower/ is a series of FlatPackage → FlatPackage transformations (wide_int, pattern, globals, boxing, closure, string, value_copy). The output is structurally the same type as the input.

This produces three problems that compound over time:

• Optimize and wir_build see the union of pre-lower and post-lower TIR variants. Several passes carry match arms for variants that lower has, in practice, eliminated. These arms are required for exhaustiveness but never taken at runtime.
• The "lower has run" precondition is implicit. A newly written pass can rely on a pre-lower shape; the type system does not catch it.
• Variants that pre-lower passes (annotate, synthesis, monomorphize) need but post-lower passes do not, and vice versa, share one enum. Neither side can shrink without breaking the other.

A second pressure reinforces the first. Removing the AST-level desugar phase (see LSP architecture) would push additional variants into TIR. Without a downstream type boundary, every optimize pass would grow further. A boundary at lower contains the blast radius.

Decision

Introduce NIR (Normalized IR) — a separately-typed body IR. lower/'s output type changes from FlatPackage to NirPackage. optimize/ and wir_build/ consume NirPackage.

What NIR Is

NIR is structurally derived from TIR. At the moment NIR lands, its expression, statement, type, and container shapes are identical to their TIR counterparts. They are distinct Rust types — separate enums, separate visitor traits — but they represent the same data.

The content of this Decision is the type boundary, not a shape redesign:

• TIR is what flows from annotate through synthesis / effect_check / link / monomorphize / erase into lower's input.
• NIR is what flows out of lower through optimize into wir_build.
• A function signature naming one of these never names the other.

What NIR Is Not

• Not a redesign. This WEP introduces no new node kinds, removes no variants, and changes no semantic behaviour. Wasm output is bit-identical before and after.
• Not a CFG or SSA representation. NIR keeps TIR's tree-structured shape. Wado has no borrow check, and Wasm has structured control flow; the tree shape is appropriate.
• Not the home for sugar removal. Sugar elimination is desugar's responsibility today, on AST. If desugar is later removed, sugar elimination moves to build_tir (AST → TIR). Neither path produces sugar that flows into NIR.
• Not a replacement for FlatPackage. FlatPackage continues to be the pre-lower container; NirPackage is the post-lower container. Both exist after this WEP.

Why "Normalized"

The name signals that NIR is the canonical form of a function body after lowering has run. "Normalized" captures the subtractive direction: only variants that survive lowering are part of NIR's enum, and TIR is free to drop variants that exist solely for post-lower passes. Both enums shrink toward their minimum useful shapes, while semantic behaviour stays unchanged.

(The Mesa shader compiler also names its IR NIR. The collision is in a different domain.)

Implementation

Source Files

Container

NirPackage mirrors FlatPackage: function table, type table reference, global table, exports, imports. Field shapes match initially.

Data Sharing With TIR

NIR reuses without copying:

• TypeTable (post-erase): types are interned globally, not per IR. NirPackage holds a reference in the same shape FlatPackage does.
• SymbolKey, FunctionId, GlobalId, name interners.
• Literal: value representation is independent of expression shape.

NIR owns its own:

• Expression / statement / pattern enums and their inline metadata.
• Visitor trait.

This follows the convention WirPackage already uses: WirTypeId borrows TIR-level type identity, while WirInstr is a fresh enum.

Lower Phase Role

lower/ continues to perform the same semantic work. Only its output type changes:

// Before
fn lower(package: FlatPackage) -> FlatPackage

// After
fn lower(package: FlatPackage) -> NirPackage

Because NIR is initially structurally identical to TIR, the cross-type conversion at lower's exit is mechanical: field-for-field reconstruction. The internal sub-passes (wide_int, pattern, globals, boxing, closure, string, value_copy) keep their current implementations.

Inspection

wado dump --nir renders NirPackage as pseudo-Wado, paralleling --tir and --wir.

Migration Plan

NIR started structurally identical to TIR; the migration is a sequence of in-place renames plus the lower-phase restructuring of Phase 10. The plan was reset on 2026-05-22 (variant-trio rewrite abandoned), then again on 2026-05-23 (Step 5 redesigned against the actual codebase — the earlier "must migrate as a cluster" framing was overcautious). What survives is small — see Phase 10 below.

Phases 1-9 — done

• [x] Phases 1-5 — NIR types (nir.rs / nir_visitor.rs / nir_unparse.rs, NirPackage) created as renamed TIR copies; lower/ switched to return NirPackage; optimize/ and wir_build/ migrated pass by pass; the temporary NirPackage → FlatPackage adapter added then removed; wado dump --nir wired; full NIR pipeline green.
• [x] Phase 6 — pre-lower-only variants trimmed from NIR (NirExprKind: Closure, Capture, FuncRef, TemplateString, WithHandler, Resume, TupleSpread, TupleZip, TypePackExpansion; NirStmtKind: IfLet, TaskReturn, VariadicForOf); LetDestructure kept for the multi-value core-builtin optimisation; ClosureToCanonical emitted directly as a NirExprKind.
• [x] Phases 7+9 — every TIR-mutating sub-pass moved into lower::plan::*; lower::lower reduced to plan + translate; wide-int and closure call-site rewriters folded into the translator; temp_module wrapping and vestigial body-IR fields dropped; the Cell-based translator slot replaced with a FunctionTranslator<'a,'p> sub-context.

Phase 10: Match / Switch / variant-trio split

Three pattern-derived forms coexist in NIR, each with a distinct role:

• Match — the canonical control-flow pattern-matching form. Preserves scrutinee identity, arm order, payload bindings, or-patterns, and guards. Compiled directly to ref.test + branch by wir_build::pattern_match.
• Switch — the dense-int / dense-enum br_table form. Optimiser-materialised only: emitted by optimize::match_to_switch, never by lower. Mirrors select_lowering — a late codegen-oriented lowering, not baked into the IR by lowering.
• VariantTag / VariantTest / VariantPayload — the canonical expression-value form of variant introspection: read a discriminant, test a discriminant, project a payload. Each is a scalar expression, not control flow.

The variant trio is permanent in both TIR and NIR. Rewriting it into Match was considered and rejected: ~30 optimize passes (labeled_block_fusion, inline, ref_elim, store_load_forward, dce, …) pattern-match the trio directly. Folding it into Match arms scatters the scalar fact across statements and forces every pass to re-derive it — a measured regression. cm_binding's variant_test / variant_tag / variant_payload uses (the CM discriminant byte at offset 0, and statically-known payload extractions in lift/lower helpers) are expression-value uses of exactly this kind; they are correct and final, not a migration debt.

Final NIR shape:

• NirExprKind::Match — canonical control-flow pattern matching.
• NirExprKind::Switch — dense form, emitted only by optimize::match_to_switch.
• NirExprKind::{VariantTag, VariantTest, VariantPayload} — canonical expression-value variant introspection; kept.

Step 1: Match → Switch is an optimiser pass — done

• [x] optimize::match_to_switch walks NIR and materialises Switch for dense-int / dense-enum scrutinees; the translator only ever emits canonical Match.

Step 2: Pattern lowering into the translator — done

• [x] IfLet / LetDestructure / or-patterns → explicit Let + Match lowering relocated from a lower::plan sub-pass into translate::pattern, run over every function before the fold; box-aware scrutinee peeling (Box<T> struct wrappers peeled via .value alongside Ref / MutRef); string literal collection folded into translate after pattern lowering (string-literal patterns synthesise string-literal expressions the data section must register); the mut-payload-binding lift extracted into lift_mut; boxing split into prepare_types and lower_bodies. Full e2e suite green at O0/O1/O2/O3/Os; mise run test-wado green.

Step 3: Synthesis migration to canonical Match — done

• [x] Synthesis control-flow migrated to canonical TIR Match (arms use TirPattern::Variant { bindings: [Binding] }, payloads bound to generator-allocated locals): synthesis/traits.rs (Inspect / InspectAlt / Eq), serde_synth.rs, effect_dispatch.rs, and all of cm_binding; shared helpers synthesis::common::match_variant_test / match_variant_payload cover the common shapes. The remaining variant_test / variant_tag / variant_payload references in cm_binding are expression-value uses, not control flow — final, see the variant-trio decision above.

Step 4: Drop TirStmtKind::IfLet and TirExprKind::Switch — done

TIR now carries no variant that exists solely to be lowered away; lower's input and wir_build's input are each at their minimum useful shape.

• [x] Dropped TirExprKind::Switch — dead. match_to_switch is a NIR-only optimiser pass; nothing constructed a TIR Switch, so the translate.rs Switch → Switch arm and every TIR walker's Switch arm were unreachable.
• [x] Dropped TirStmtKind::IfLet. elaborator::stmt lowers if let / let-chain conditions directly to a two-arm Match (<pattern> => <then>, _ => <else>) instead of IfLet; translate::pattern already handles Match, so the old IfLet → Match converter is gone. The scrutinee stays inline through synthesis so resource_cleanup's resource-flow analysis sees the same shape it saw for IfLet; the (Let, Match) temp-local hoist that labeled_block_fusion keys on is re-applied later, in translate::pattern, after resource_cleanup has run. task_return synthesis gained Match-arm descent — task return inside an if let body now lands in a Match arm, which its If / Loop walker missed.
• TirExprKind::{VariantTag, VariantTest, VariantPayload} are NOT dropped — see the variant-trio decision above. NirExprKind keeps the trio as well; the original plan to drop it from NIR is abandoned. TirStmtKind::LetDestructure stays — the elaborator emits it and NIR preserves the multi-value core-builtin optimisation.

Step 5: Plan sub-passes become analysis-only

Goal: lower::plan(flat) only mutates the type table, pushes additive synthesized entities into FlatPackage, and edits function declaration shapes (parameter shadows, lifted mut bindings). Every TIR body rewrite — boxing's &local / *ref forms, closure's Closure → StructLiteral, value_copy's copy_value insertion — runs inside the translate fold, consulting plan structs that the analysis built. After this step, TIR is read-only between lower::plan and translate at the expression-shape level, and ~1100 LoC of redundant TIR walkers collapse into fold rules.

Design findings from reading the code (2026-05-23):

• The earlier framing "passes are interdependent — must migrate as a cluster" was overcautious. The hard dependency is on boxing::prepare_types (type-table redefinition), which stays as a pre-pass anyway. The body rewrites of boxing / closure / value_copy are independent and can each migrate in their own phase, each with a green checkpoint.
• TirFunction.address_taken_locals is already populated by the elaborator; the fold reads it directly. BoxPlan carries only type-level facts (box payload mappings, Box<T> struct ids).
• The closure pass keeps its __call body synthesis (Phase 1, including the Capture → FieldAccess rewrite that runs during the body clone). Only the user-side Closure → StructLiteral at Let rewrite (Phase 3) moves to the fold; the remaining Phase 3 rewrites (IndirectCall → MethodCall, specialized Local retag, unspecialized Closure → ClosureToCanonical) are already in translate.
• value_copy's insertion predicate is_fresh_in_context is pure and shape-local. The fold and the analysis walker share it via value_copy::analyze::should_wrap. The analysis walker collects every TypeId the fold would wrap; the synthesizer generates helpers for that set transitively, before the fold runs.
• globals::extract and build_initialize_modules are purely additive (they push __initialize_module / __initialize_modules functions). No body-rewrite component to migrate.
• The Deref-assign field expansion is a 1-stmt → N-stmts rewrite; convert_block flat-maps convert_stmt so the boxing arm can emit a vector.

Migration phases (each with a green e2e checkpoint at the end):

• [x] Phase A — value_copy::insert → fold. insert.rs replaced by value_copy::analyze (read-only walker that collects TypeIds via the shared should_wrap / is_source_immutable / is_fresh_value predicates). value_copy::synthesize takes the seed as input and still closes the transitive set across nested helper bodies. The translator's convert_stmt_kind (Let / LetDestructure arms), convert_call_arg, IndirectCall arg loop, and Assign arm emit Call($value_copy$T, ...) wraps directly. Per- function immutable_locals lives on FunctionTranslator; fresh_locals is not threaded through the fold because the pre-Phase-A predicate only used it inside the LabeledBlock break-freshness sub-walk, which is shape-local. Synthesized Lets at translate time (wide-int rewrite, pattern lowering) now carry skip_value_copy: true so the fold does not look up helpers that were never seeded. Full e2e suite green at O0/O2 (2592 passed, 0 failed); mise run test-wado green (787 compile, 2825 tests passed).
• [x] Phase B — boxing::lower_bodies → fold. boxing is now prepare_types (type table; unchanged) + shadow_params (per-function parameter-shadow prelude injection plus a local-table retag for non-param address-taken locals; still a pre-pass because prelude injection is function-scoped). Every body rewrite landed in the translator: try_boxing_rewrite handles Local(addr-taken) → FieldAccess(.value), Unary(Ref|MutRef, _) (including the &FieldAccess(.value) → Local(box) collapse and the &primitive → Box{value: x} literal), and Unary(Deref, Box) → FieldAccess(.value). The Let arm wraps the initial value of an address-taken primitive local in Box{value: x} and retypes the binding's type_id. try_expand_deref_struct_assign recognises *ref_to_struct = value and emits a per-field expansion (let __deref_ref, let __deref_val, ref.f0 = val.f0, …); convert_block consumes statements as Vec<NirStmt> so the expansion plugs in cleanly. The closure planner now propagates the original closure's address_taken_locals to the synthesized __call method (with a +1 shift to make room for the self param) so the fold's boxing arm fires inside cloned closure bodies — previously latent because pre-Phase-B boxing ran before the closure clone. Full e2e at O0/O2 green (2592 passed, 0 failed); mise run test-wado green (790 compile, 2825 tests passed).
• [x] Phase C — Closure → StructLiteral (specialisable) → fold. ClosureCallSiteLowerer::visit_expr's Closure arm no longer rewrites TirExprKind::Closure into StructLiteral in place; the rewrite happens at the fold's Closure arm, which reads ClosurePlan::specializable (now exposed on the plan) to decide between a raw StructLiteral (specialisable functor — the call site can dispatch directly to the per-functor __call) and a ClosureToCanonical wrap (other functor — the call site goes through the canonical fn(...) vtable). Position no longer matters: the fold emits the right shape regardless of whether the Closure lives at a Let value, a Call arg slot, a struct field default, or a Return. CollectedClosure carries the closure's address_taken_locals; the synthesized __call function receives the set (shifted by +1 for the synthetic self) so the boxing fold rule fires correctly inside cloned closure bodies. The remaining ClosureCallSiteLowerer responsibilities — try_redirect_to_specialized_callee (Call → specialised callee + arg Closure → StructLiteral), try_redirect_inspect_to_functor, the Let.type_id retype, and update_local_types — stay as pre-pass synthesis: they touch FunctionRef / Let.type_id / func.locals[i].type_id, not the expression-shape rewrite Phase C targeted. Full e2e at O0/O2 green (2592 passed, 0 failed); mise run test-wado green.

Phase D (lift_mut → translate::pattern preamble) was considered and dropped. After Phase A, value-copy helpers are seeded by a read-only walker that runs before the fold. The lifted Let mut original = fresh_local statements lift_mut::lift_mut_match_bindings synthesises are themselves wrap-eligible — the predicate fires on the lifted Let's value when the binding's type is value-semantic. Moving lift_mut into the fold would make those Lets invisible to the seed walker, so the fold would either panic (helper not registered) or have to flag the lifted Lets skip_value_copy: true (no wrap — a real semantic change). Neither is acceptable. lift_mut therefore remains a lower::analyze step. The invariant Phase D was chasing — "every func.body mutator out of analyze" — costs more than it pays for: lift_mut is small (191 LoC), idempotent, and operates on pattern shapes that the fold also consumes.

Out of scope for this WEP:

• Removing the AST-level desugar phase.
• Folding boxing::shadow_params or closure::Phase 0 into the fold (would require multi-pass or per-function preamble buffers in FunctionTranslator; not justified by the saved walker LoC).

Consequences

Benefits

• Type boundary at lower. The "lower has run" precondition is enforced statically.
• Risk concentrates on lower. Optimize and wir_build migrations are mechanical renames; the semantically interesting work stays in the smallest of the three phases.
• Enables variant trimming on both sides. With two distinct enums, variants only meaningful pre-lower can leave NIR, and variants only meaningful post-lower can leave TIR. Each trim is a small PR enforced by the type system.
• Enables removal of the AST-level desugar phase. Adding variants to TIR (the consequence of moving sugar elimination into build_tir) does not propagate into optimize.

Trade-offs

• Code duplication on landing. NIR's expression / statement / visitor / unparse files start as copies of TIR's. The duplication is intentional and is paid down in subsequent WEPs as the two diverge. Copying is mechanical and reviewable in one sitting.
• A short window during the transition where both FlatPackage and NirPackage flow through downstream code. The Phase 2 adapter absorbs this; Phase 5 removes it.
• One more wado dump mode to maintain.

Additions

NIR's node set is not frozen. The migration landed with no new nodes (a scoping constraint for the type-boundary work, now lifted); going forward, NIR's expression set may grow when a new node makes its canonical form more analyzable.

NirExprKind::ArrayLiteral (proposed)

List literals are coerced into SequenceLiteralBuilder push sequences during elaboration (see Iterator-Based Literal Coercion), so an array constant reaches NIR as imperative with_capacity + push statements; a fixed const-array shape only re-materializes at WIR (collapse_array_push_sequences → array.new_fixed). NIR-level analysis of constant arrays is therefore impossible today.

Add NirExprKind::ArrayLiteral { elements } plus a collapse that recognizes the const builder push-sequence and rewrites it to the literal, early in the optimize loop. This is normalization, not a lowered-concept re-introduction: it gives constant arrays the same first-class, analyzable shape StructLiteral / TupleLiteral already have. It is shared infrastructure, not specific to one pass:

• cse can deduplicate identical constant arrays (today it returns None for aggregates).
• niri / const_fold can fold Index(ArrayLiteral, const) to the element.
• Bounds-check elimination knows the static length.
• Constant Object Globalization can globalize constant arrays and strings.

Status: landed. NirExprKind::ArrayLiteral is materialized by optimize::array_literal and lowered by wir_build to array.new_fixed; the WIR collapse_array_push_sequences it subsumed has been retired. See NirExprKind::ArrayLiteral — a NIR-Materialized List Node.

See Also

• WEP 2026-02-14: Wasm IR (WIR) Layer — the precedent for a separately-typed body IR. NIR follows WIR's data-sharing conventions (shared type / symbol identity, independent expression enum).
• WEP 2026-04-18: LSP Architecture — the LSP-driven motivation for removing the AST-level desugar phase, which becomes safe under NIR.