Vox compiler architecture (research)
Authority: This page is research / orientation. Normative language rules and phased enforcement live in Vox Language Rules & Enforcement — Top-Level Plan (2026). Crate placement is summarized in where-things-live.md.
Pipeline overview
Section titled “Pipeline overview”At runtime, user-facing commands (vox check, vox build, LSP validation, parts of MCP) fan into the vox-compiler crate as the unified front door for parsing and analysis.
Diagram source
graph { direction: right node Source: "Vox_source" container lexerParser: "LexerAndParser" { node lex: "lex" node parse: "parse" lex -> parse } container analysis: "Analysis" { node ast: "AST_module" node hir: "HIR_lower" node typeck: "typecheck_ast_module" node hirVal: "validate_module_HIR" ast -> hir hir -> typeck hir -> hirVal } container emit: "Emit" { node codegen: "codegen_rust_and_emit_targets" } Source -> lexerParser.lex lexerParser.parse -> analysis.ast analysis.typeck -> emit.codegen analysis.hirVal -> emit.codegen}Module map (conceptual)
Section titled “Module map (conceptual)”| Stage | Primary location | Notes |
|---|---|---|
| Lexing | crates/vox-compiler/src/lexer/ | Token stream consumed by parser. |
| Parsing | crates/vox-compiler/src/parser/ | AST construction; grammar evolution ties to Phase 1 SSOT collapse. |
| AST | crates/vox-ast/src/ | Span-carrying surface syntax. |
| HIR | crates/vox-compiler/src/hir/ | Lowered representation; durability / workflow shapes tracked in durability-runtime-audit-2026.md. |
| Typecheck | crates/vox-compiler/src/typeck/ | Diagnostics, severity, suggestions/fixes consumed by LSP — see language-diagnostic-drift-findings-2026.md. |
| Codegen | crates/vox-compiler/src/codegen_rust/ (+ related) | Rust and other emit paths; Web IR / frontend convergence in frontend-convergence-findings-2026.md. |
| Interpreter tier | crates/vox-compiler/src/eval/ | --interp path; must stay aligned with shell stdlib SSOT. |
Downstream vox-codegen consumes analysis artifacts for Web IR and extracted IR — see where-things-live.md (vox-codegen row).
Extension points
Section titled “Extension points”- New syntax / keywords: Prefer decorators over bare keywords per root
AGENTS.md; any new bare keyword should go through ADR + xtask flow described in Phase 1 plan. - New diagnostics: Stable IDs and catalog discipline — Phase 2 lint extension and diagnostic UX (research).
- Runtime-visible behavior: Separately tracked in runtime crates (
vox-actor-runtime, orchestrator, mesh plans); compiler-only parses do not imply execution — see durability audit.
Related docs
Section titled “Related docs”- GUI-Native Roadmap Execution Status
- Feature growth boundaries
- Mesh Phase 1 — Language spine (distributed language features)