Every WasmIR instruction has one effect class. This closed classification is the optimizer’s authority for elimination, common-subexpression reuse, aliasing, and motion.
Classes
| Effect | May remove when result is dead? | Main ordering rule |
|---|---|---|
Pure |
Yes | May move within barrier constraints |
LoadFrame |
Yes | Invalidated by an aliasing frame store or broad clobber |
StoreFrame |
No | Orders with matching frame accesses |
LoadFlex |
Yes | Invalidated by an aliasing flex store or broad clobber |
StoreFlex |
No | Orders with matching flex accesses |
HostCall |
No | Conservatively clobbers both memory domains |
AsyncBarrier |
No | Never reorder, split, or eliminate |
Pure includes scalar/vector algebra, constants, conversions, and other register-only work. Loads are removable only if their result is dead and no trap or other observable behavior is part of that selected instruction’s contract.
Host calls include imports, intra-unit calls, bulk memory changes, memory-growth-sensitive operations, and synchronous runtime calls such as spawn setup or cancellation. The conservative classification allows a callee to inspect or modify linear memory without teaching every optimization its implementation.
Async barriers include signaling completion, enqueuing a resume or loop step, and beginning asynchronous I/O. Once a barrier appears in a block, only barrier instructions can follow before the leaf terminator.
Alias domains
Frame and flex memory are separate domains. Within a domain, an optimizer can use a precise key such as frame slot or base-plus-offset when the instruction provides one.
A HostCall or AsyncBarrier clears cached knowledge in both domains. With
relocating arena growth enabled, it also invalidates an absolute arena-base
assumption. This is conservative by design; a missed forwarding opportunity is
safe, while forwarding a stale load is a miscompile.
Verifier
The WasmIR verifier checks eight groups of invariants:
- Structure: referenced registers and blocks exist; the entry has no block parameters.
- SSA dominance: each use is dominated by its sole definition.
- Types: operand and destination types match the instruction.
- Edges: each jump and branch arm matches target parameter arity and types.
- Barriers: async instructions form a valid terminal sequence.
- Effect domains: frame slots and flex access data are valid.
- Reachability: every block is reachable from entry.
- Function shape: parameters agree with continuation, block-function, or direct kind.
When call signatures are available, signature-aware verification additionally checks argument and result types. An unavailable signature does not invent a failure; the structural verifier still checks everything it can prove.
Verification runs after lowering and after optimization passes in debug
builds. A failure includes a human-readable WasmIR dump and identifies a
compiler defect. It is never converted into an unreachable instruction to
let module generation continue.
Provenance
Lowering records:
(WasmIR block, instruction index)
→ (MIR block, operation index)The MIR key can then resolve a source range or HIR node. One MIR operation can produce several WasmIR instructions; all inherit its origin. Instructions created solely by an optimization can omit the map, but passes that delete or reorder instructions must remap existing keys.
Provenance is observational metadata. It supports dumps, traces, line tables, and debugger navigation but must not affect generated program behavior.
Pass discipline
An optimization may use opcode fields for algebraic details and the effect class for observability. It must update:
- use and definition tables after register rewriting;
- block arguments after CFG rewriting;
- provenance after instruction compaction;
- any allocation or residency data computed from changed liveness.
The final encoder is intentionally boring: it maps verified instruction fields to bytes. If an optimization requires semantic types, layout lookup beyond a named frame slot, or knowledge of how an Atoll feature desugared, it belongs before WasmIR.