HIR

High-level Intermediate Representation is semantic analysis’s output and monomorphization’s input. It retains enough source structure for diagnostics, tooling, generic substitution, and higher-level lowering, but every name and type relevant to execution is already resolved.

HIR’s central contract is:

A valid HIR node says what the program means without requiring the consumer to repeat parsing, name lookup, overload selection, or type inference.

Project shape

HirProject is the semantic container for a checked project. Its primary arenas hold expressions, statements, patterns, functions, and their contiguous-list ranges. Associated tables hold facts that are naturally keyed by a type, symbol, declaration, or call site rather than duplicated inside every node.

Major fact families include:

This split is intentional. An expression stores its resolved TypeRef, while a call’s selected dispatch lives in call_dispatch keyed by that call’s HirExprId. Consumers must treat the node and its required side-table entries as one logical record.

Node contract

Every expression has:

• an Origin linking it to syntax or a classified synthesis;
• a fully resolved TypeRef, or the distinguished error type during recovery;
• a HirExprKind whose child IDs belong to the same project.

Statements and patterns follow the same arena-and-origin discipline. Function nodes add ordered parameter symbols, body identity, result information, and an effect row. Effects are currently tracked at function granularity; consumers must not infer that an arbitrary expression has a separately stored effect row.

Read Nodes for the node families and Invariants for validity and relocation rules.

Semantic decisions

HIR makes implicit source behavior explicit without prematurely selecting a machine representation:

• omitted else branches receive a unit-valued branch;
• loops share a unified loop form;
• optional member access, string templates, and structural dispatch can introduce classified synthetic nodes;
• coercions are explicit nodes rather than backend guesses;
• calls retain their argument order and carry a dispatch result when known;
• propagation, error returns, spawning, selection, and catching remain recognizable high-level constructs;
• compile-time type matches remain until substitution selects one arm.

This is also the last representation allowed to contain generic type variables that matter to emitted code. Monomorphization clones reachable generic bodies, applies canonical substitutions, rewrites concrete calls, and materializes layouts. The resulting monomorphic HIR must not require MIR to choose a type-match arm or invent a generic layout.

Producers and consumers

Semantic lowering produces per-file LocalHir arenas while checking a file. Project assembly relocates them into a HirProject in canonical file order. That order makes IDs deterministic even when independent files were analyzed in parallel.

Primary consumers are:

• monomorphization, which clones and substitutes HIR;
• MIR construction, which lowers monomorphic bodies;
• diagnostics, language-server features, and trace tooling;
• unit discovery and dependency analysis;
• internal caches for selected prechecked compiler inputs.

HIR is primarily an in-process API. Serialized compiler snapshots are versioned implementation artifacts: some derived and post-specialization tables are deliberately skipped and rebuilt. They are not a public, forward-compatible interchange format.

Boundary

HIR does not own frame offsets, reference-count insertion, continuation splitting, WebAssembly value types, or module indices. Those choices belong to MIR and WasmIR. Conversely, a lower representation may preserve HIR identity, but it must not reinterpret unresolved source syntax.

See Analysis for construction and Specialization for the transition to concrete bodies.