Wado Compiler

The Wado compiler (wado-compiler/) translates .wado source into a Wasm component binary. This document gives a high-level overview of the architecture; deeper topics live in their own docs:

• Optimization passes: optimizer.md
• LSP architecture: WEP 2026-04-18
• Language features: spec.md

Pipeline

Source (.wado)
  → Lex → Parse → Bind                    (per module, in loader)
  → Annotate (Analyze + Resolve + lower TIR)
  → Default-purity Check
  → Synthesis (auto-derives, template, From, serde, pre-CM effect dispatch, CM bindings)
  → Effect Check → Stores Check
  → Effect Dispatch (post-check: WithHandler / Resume desugaring)
  → Link (Package → FlatPackage)
  → Monomorphize → Erase Newtypes & Flags
  → Lower
  → Optimize
  → WIR Build → WIR Optimize → Codegen
  → Wasm component bytes

The driver is compile_after_load in src/lib.rs.

Compilation Units and IRs

Codegen takes &NirPackage + &WirPackage (emit_wasm) and has no knowledge of earlier phases — the rule that keeps the back end decoupled from the front.

Frontend (per-module)

The loader runs lexer → parser → bind on every loaded module:

• The lexer extracts the optional __DATA__ section and tokenizes the rest.
• The parser builds a faithful AST. Compound assigns, comparison chains, struct shorthand, and &self parameters are kept verbatim so wado format round-trips.
• bind.rs performs local name resolution, scope/mutability checking, and use-before-define detection.

The AST is parser-immutable from this point on. The desugar-replacement surface rewrites — compound assignment (x += y → x = x + y), while / C-style for → explicit loop, for x of expr iteration (the .into_iter() / .next() dispatch and the match Some(x) => body, _ => break shape), the assert statement, the matches operator, the comparison chain a < b < c, template-string interpolations, use … namespace prefix stripping (helper::foo), and Self::method / T::method (T bound to concrete) static-call dispatch — happen inside the elaborator and are built TIR-direct: each rewrite resolves the user AST and constructs TirExpr / TirStmt nodes directly without producing synthetic AST. The implementations live in elaborator/{stmt,operators,assert,matches}.rs (resolve_while, resolve_for, resolve_iterator_for_of, resolve_compound_assign, desugar_assert, desugar_matches_expr, desugar_comparison_chain), Elaborator::strip_ns_prefix in elaborator.rs, and CalleeIdentKind / classify_call_callee in elaborator/call.rs (the prefix is resolved to its concrete type name before parameter-type lookup so argument resolution runs once with the correct expected-type hints). Synthetic call sites that need to dispatch a method on an already-resolved receiver TIR (the for-of .into_iter() / .next() calls today) reuse the AST-driven method dispatch via Elaborator::resolve_method_call_with (elaborator/method_call.rs) — that helper takes a pre-resolved receiver plus a method name and signals "no source AST" with method_id: None so no use→def edge is recorded against the synthesis site. Keeping the AST parser-shaped is what lets LSP queries land on the user's text rather than on a synthesised replacement.

Annotate (Analyze + Resolve + TIR Lowering)

semantics_of (semantics.rs) is the entry point shared by LSP and batch compilation. It runs analyze.rs for symbol-table construction and elaborator/ for type checking; bodies are then lowered into TIR.

The result, Semantics, carries the TIR modules plus an AstIndex and a use→def map (AstId → AstId, globally-unique ids). This is what makes the architecture LSP-friendly: facts are attached to AST nodes without mutating them, so cross-file navigation, hover, and rename all fall out of the same data the batch compiler uses. See the LSP section below.

The elaborator covers trait selection, generic inference, method dispatch, coercion, and effect typing. All trait calls are resolved statically — by the end of the pipeline every call targets a concrete monomorphized function. There is no runtime vtable.

Synthesis

synthesis::synthesize (synthesis.rs) generates synthetic TIR that the user does not write:

Synthesized impls are recorded back into the shared TraitEnv so subsequent phases query a single source of truth.

Bound-driven requests (WEP 2026-06-25-trait-derivation) originate during Annotate, from two funnels into the shared TypeTable::bound_driven_synth_requests set (one per TypeTable, project-wide, since each module gets a fresh Elaborator):

• A satisfied bound: Elaborator::type_implements_trait_inner (elaborator/trait_query.rs) records a (type, trait) pair whenever a T: Serialize/Deserialize/Eq/Ord/Default bound is satisfied. Eq/Ord/serde recurse through members via one walker, walk_structural_derive_members, shared with marker validation and reason-chain diagnostics; Default instead checks that every field carries a default expression (auto_derive_default_struct_type). A direct S::default() call records at static-method resolution (method_call.rs), since it reaches no bound check.
• A body-less marker: impl Eq/Ord/Default/Serialize/Deserialize for T; all validate eligibility immediately at the marker's own span (Elaborator::record_explicit_derive_request — a compile error if T isn't eligible) and then record into the same set, keyed by the target type's defining module.

The format traits (Inspect/InspectAlt/Display/DisplayAlt) are total (WEP): classify_on_bound_trait classifies them, type_implements_trait_inner short-circuits true for any type, and generation stays unconditional — so a T: Inspect/T: Display bound always holds and impl Inspect for T; markers are accepted, without gating. They record no demand request.

Two passes read the demand set as a snapshot, not a drain (consuming it would starve whichever runs second): serde_synth::synthesize_serde claims Serialize/Deserialize; traits::synthesize_traits claims Eq/Ord/Default, gating generation on set membership (SynthesisCtx::should_synthesize) instead of its former unconditional sweep.

A body-less marker is itself an Item::Impl and lands in TraitEnv's impl indexes like any other, so every gate that means "a real impl already covers this" must count only methodful impls: SynthesisCtx::has_real_impl (module-scoped, for Eq/Ord/Default generation dedup), has_methodful_impl_anywhere (module-agnostic, so a body-less format marker never suppresses the eager format body while a real impl Display for String does), and Elaborator::has_real_trait_impl_for_type (module-agnostic — a serde impl legitimately lives outside the type's module, e.g. core:serde's impl Serialize for i128).

Effect and Stores Checks

check_effects and check_stores (effect_check.rs) run after synthesis and before monomorphize. They validate that every function declares the effects and reference stores it actually requires. Synthesized CM boundary code is exempted. A separate check_default_purity runs earlier, immediately before synthesis, to gate auto-derived Default::default() bodies on pure field defaults.

Effect Dispatch (post-check)

synthesis::effect_dispatch::synthesize_post_check runs between the effect/stores checks and link. It desugars WithHandler / Resume constructs into the per-effect dispatch infrastructure (struct, mut global, dispatch wrappers). This pass is split out of the main synthesis stage so that effect-check sees the original WithHandler shape and can validate which effects are satisfied locally.

Link → Monomorphize → Erase

• link.rs merges per-module TIR into a single FlatPackage. After link, functions and types are addressed by global indices.
• monomorphize/ walks call sites, instantiates generic structs and functions with concrete type arguments, and rewrites references. Generic structs are keyed by (name, ModuleSource); generic functions are keyed by (ModuleSource, String), where the string is the bare method name for methods and a module-qualified FreeFunctionName for free functions. The ModuleSource is always the body's home module (where the template is registered in Package::functions), so same-named generics from different modules coexist. The dispatch loop panics if a queued generic has no template at its (module_source, name) key — every generic must be defined somewhere reachable (e.g. in core:prelude for built-in shapes like the tuple, whose reserved base name is []). Variadic TupleSpread nodes are expanded here. name.rs produces stable mangled names (Box$i32, identity$1, …).
• type_table.erase_newtypes_and_flags() then collapses newtypes to their base type and flag types to u32. The distinction is needed during monomorphize for trait dispatch but not afterwards.

Lower

lower.rs runs FlatPackage (TIR-shaped) → NirPackage as planner + translator: the planner ([lower::plan::plan]) runs the TIR-mutating sub-passes and produces a LowerPlan of facts; the translator ([lower::translate::translate]) is a single fold from TIR to NIR. See docs/wep-2026-05-11-nir.md.

Optimize

optimize/ runs a fixed-point loop of NIR-level passes (inlining, copy propagation, SROA, LICM, DCE, …). Local rewrites run on a worklist engine (nir_engine.rs) over the arena Body — a node is revisited only when an edit might have made it reducible — with the position-flexible rules sharing one session (optimize/peephole.rs). A per-function dirty-set gate (optimize/gate.rs) lets each pass skip functions unchanged since it last ran. See optimizer.md and WEP: NIR Rewrite Engine.

WIR Build

wir_build/build_wir_package translates a NirPackage into a WirPackage in three stages: register types, collect function signatures, then translate each function body via FunctionTranslator. The pass is split across sibling files by concern:

Each helper module calls back into translate.rs for sub-expression translation; cross-module access uses pub(super) on shared fields.

CM canonical operations (stream / future read + write, waitable-set, error-context) carry no wir_build code: they are lowered entirely in the synthesis phase (synthesis/cm_binding/) into ordinary TIR that translates like any other function.

WIR Optimize

wir_optimize/ runs Wasm-shape-specific passes that need WIR's lower-level view: peephole, variant-return SROA, init-guard removal, struct elision, array data promotion, parameter SROA, nullable-ref folding, constant forwarding, DCE, and final cleanup. Tuple- and user-struct-return ABIs are decided by the TIR-level optimize::multi_value_return pass before WIR build.

Codegen

codegen::emit_wasm produces the final component bytes:

1. emit.rs emits core Wasm bytes from WIR.
2. component.rs wraps the core module in a Component Model envelope (imports, exports, adapters, optional WIT bundling, embedded data).
3. postprocess.rs adds branch-hint sections and other post-emission custom sections.

Output is validated with wasmparser unless --no-validate is set.

Module Loading and Names

Module Sources

name.rs::ModuleSource distinguishes where a module originated:

The loader canonicalizes paths (RFC 3986, project-root-relative with / separator) so the same file imported via different paths shares one identity.

Naming Convention

name.rs centralizes mangling so other components do not depend on name shapes:

Component Model Registries

Three registries collect declarative information from the standard library and feed both the elaborator and codegen:

• CmInterfaceRegistry (component_model.rs) — extracts WASI interfaces from lib/wasi/*.wado: version pins, async flags, canonical method names, supported types. Codegen drives import generation from this registry; only interfaces whose types are fully supported are imported.
• WorldRegistry (world_registry.rs) — collects world definitions (e.g., the Command world from wasi/cli.wado) and provides export signatures.
• BuiltinRegistry (builtin_registry.rs) — collects function signatures from lib/core/builtin.wado. Functions tagged #[canonical("ns", "name")] import a CM canonical builtin (wasi, mem, or bundled); untagged builtins compile directly to Wasm instructions.

LSP

The language server (wado-lsp/) is a thin layer on top of wado_compiler::semantics. The Engine holds open documents and answers LSP queries (diagnostics, hover, go-to-definition, references, document highlight, semantic tokens). Each query:

1. Composes parse(source) → load(parsed, …, invocations, …) → semantics_of(loaded, host, …) to obtain a Semantics snapshot (kiln invocation discovery runs against the parsed entry AST between stages).
2. Uses Semantics::cursor_at(module, line, col) → Cursor to translate a (line, col) into an AstId cursor.
3. Reads pre-computed facts off Cursor / Semantics (def_key, def_name_span, references_to_def, is_write_target, …).

Engine itself performs no I/O — every query takes an &impl CompilerHost, so the caller decides how imported modules are loaded. wado-lsp ships a FilesystemCompilerHost; embeddings (VS Code Wasm, browser playground) supply their own host. The wado-compiler crate must compile to wasm32-unknown-unknown to support those bundled deployments; CI enforces this. See WEP 2026-04-18: LSP Architecture.

Kiln (Schema-Driven Code Generation)

Kiln is the compiler's mechanism for turning external schemas (.proto, .graphql, .g4, .wit, custom IDLs) into .wado source. A generator is itself an ordinary Wado package that targets the core:kiln/generator world; the compiler builds it to a Wasm component, and the host (wado-cli) executes it via wasmtime to produce .wado source files. Invocations are content-addressed by their schema bytes, options, and the generator's source hash. See WEP 2026-04-12: Kiln.

The compiler-side pieces live in src/kiln/:

The pipeline driver (run_generator, file persistence, wado.lock handling) lives in wado-cli; wado-compiler exports only the pure-data pieces above so it stays wasm32-unknown-unknown-clean.

compile_after_load integrates Kiln at three spots:

• Phases 1a–1b (pre-analysis): when the entry module's target world is core:kiln/generator, import_check rejects forbidden imports and rewrites fn generate(req: Request<Options>) to insert the bind_request boilerplate. Options::deserialize needs no dedicated hook: bind_request::<Options>'s T: Deserialize bound records the bound-driven synthesis request like any other bound (WEP 2026-06-25-trait-derivation).
• Phase 6c (post-annotate): if the target world is core:kiln/generator, extract_options_descriptor walks the resolved pub struct Options and produces the descriptor that the CLI provider caches on disk so it can answer describe-options without a second compile.
• Module loading: when an import target matches an entry in the caller-supplied InvocationIndex, the loader resolves it to ModuleSource::Redirected { uri } and asks the host to load the generated bytes. This is how use Foo from "schema.proto" with { generator: ... } gets wired up after generation.

Standard Library

The compiler bundles the standard library inside its binary (stdlib.rs embeds lib/):

• lib/core/ — prelude, cli, collections, serde, json, simd, zlib, base64, url, router, kiln, internal, builtin, allocator, plus co-located _test modules.
• lib/wasi/ — Wado bindings for WASI P3 interfaces. Generated from WIT by wado-from-idl; regenerate with mise run update-stdlib-wasi.

Bundled Math (wado-bundled-libm)

The wado-bundled-libm/ crate compiles a deterministic libm to wasm32-unknown-unknown. The compiler links it as a separate core module inside the produced component, and core:builtin exposes its functions via #[canonical("bundled", …)].

Allocators

Three allocators live in lib/core/allocator.wado, each tagged #[allocator("name")]. The compiler picks one by setting that function's export_name to "realloc":

--allocator <name> overrides the defaults.

In Progress

• [ ] Variant pattern matching: struct payloads not yet supported (single-payload and tuple-payload work).
• [ ] Function types: parser supports fn(T) -> U and closure codegen works, but full first-class function types are incomplete.
• [ ] Stream/Future: resource declarations exist in core:prelude/types.wado, but method resolution (.new(), .read(), .write(), .close(), .drop()) is still hardcoded in elaborator/method_call.rs rather than driven by the resource declarations.

Known Limitations

• Implicit struct literals do not work with generic structs: let b: Box<i32> = { value }; fails. Use let b: Box<i32> = Box { value };.
• GC arrays cannot be passed directly to stream<u8> — they must be copied to linear memory first (component-model#525).

Not Yet Implemented

• ? operator (error propagation)
• Effect handlers
• Reactive signals (source values, derived values, effect blocks)