"Explanation: Compiler Lowering Phases"

Explanation: Compiler Lowering Phases

Understand how the Vox compiler transforms high-level source code into optimized Rust and TypeScript output.

Implementation note: current production code keeps these stages under crates/vox-compiler/src/ with explicit modules for parser, HIR lowering, typecheck, and dual-target emitters.

1. Syntax to AST (Abstract Syntax Tree)

The parser converts the raw .vox file into a tree of declarations. This phase ensures the code is syntactically valid but does not yet understand types or decorators.

2. AST to HIR (High-level Intermediate Representation)

The Lowering phase begins by transforming the AST into the HIR.

  • Symbol Resolution: Linking variable names to their definitions.
  • Decorator Processing: Expanding decorators like @server into their underlying architectural primitives (handlers, endpoints, clients).
  • Type Inference: Deducing types for all expressions.

3. HIR to WebIR and LIR (Low-level intermediate layers)

ADR 012 introduces WebIR (crates/vox-compiler/src/web_ir/) as the normative structured layer before React/TanStack printers. lower_hir_to_web_ir lowers reactive view: JSX (plus routes { contracts and behavior summaries) into WebIrModule; validate_web_ir checks DOM id references; emit_component_view_tsx is a JSX string preview used for parity tests.

Current production behavior (important for migration planning):

  • codegen_ts still assembles production TS/TSX output on the primary path.
  • VOX_WEBIR_VALIDATE=1 runs WebIR lower/validate as a fail-fast gate.
  • VOX_WEBIR_EMIT_REACTIVE_VIEWS=1 enables reactive view: bridge output via WebIR preview emit only when parity checks pass.
  • The two flags are related but not equivalent; validation can be enabled without switching reactive view emission.

Operations catalog + gates: WebIR operations catalog and acceptance gates G1–G6 (includes supplemental OP-S049–OP-S220 rustc/doc gates). Roadmap link pass A (OP-S130, OP-S131, OP-S209–OP-S211): keep lowering docs aligned when renaming validation stages.

Separately, backend-oriented lowering remains optimized for Rust emission (database, actors, HTTP). The older “Frontend LIR” label maps to this split: WebIR for structured web UI, HIR emitters for expedient TS until the printer fully migrates.

3b. HIR to AppContract and RuntimeProjection (contract layers)

Two additional HIR-derived contract layers are authoritative for non-UI emitters and orchestration:

  • app_contract::project_app_contract produces AppContractModule (HTTP routes, server/query/mutation functions, client routes, islands, server config).
  • runtime_projection::project_runtime_from_hir produces RuntimeProjectionModule (DB planning policy snapshots and inferred task capability hints).

These projections are generated from the same lowered HIR input as WebIR and are validated in parity tests to prevent split semantic ownership.

4. Code Generation (Emission)

The final phase where lowered IR is converted into source files:

  • vox-compiler::codegen_rust: Produces generated Rust app files (src/main.rs, src/lib.rs, API client output, and DB scaffolding).
  • vox-compiler::codegen_ts: Produces TS/TSX output (App.tsx/route trees, server-fn wrappers, component files, and generated contracts).

For frontend IR layering and migration phases, see ADR 012 — Internal web IR strategy. For detailed implementation sequencing, see Internal Web IR implementation blueprint. For ordered file-by-file migration operations, see WebIR operations catalog. For exact current-vs-target representation mapping, see Internal Web IR side-by-side schema. For quantified token+grammar+escape-hatch savings on the canonical app, see WebIR K-complexity quantification. For reproducible counting registries and equation trace, see WebIR K-metric appendix.

5. Why Lowering Matters?

By having multiple intermediate representations, Vox can perform complex architectural optimizations—like automatically grouping database queries or optimizing actor communication—that would be impossible in a single-pass compiler.

Related Reference: