Skip to content
Vox: The AI-Native Programming Language

Vox compiler architecture (research)

Vox compiler architecture (research)

Section titled “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.

flowchart LR
  subgraph lexerParser [LexerAndParser]
    lex[lex]
    parse[parse]
  end
  subgraph analysis [Analysis]
    ast[AST_module]
    hir[HIR_lower]
    typeck[typecheck_ast_module]
    hirVal[validate_module_HIR]
  end
  subgraph emit [Emit]
    codegen[codegen_rust_and_emit_targets]
  end
  Source[Vox_source] --> lex --> parse --> ast
  ast --> hir --> typeck
  hir --> hirVal
  typeck --> codegen
  hirVal --> codegen

Module map (conceptual)

Section titled “Module map (conceptual)”
StagePrimary locationNotes
Lexingcrates/vox-compiler/src/lexer/Token stream consumed by parser.
Parsingcrates/vox-compiler/src/parser/AST construction; grammar evolution ties to Phase 1 SSOT collapse.
ASTcrates/vox-compiler/src/ast/Span-carrying surface syntax.
HIRcrates/vox-compiler/src/hir/Lowered representation; durability / workflow shapes tracked in durability-runtime-audit-2026.md.
Typecheckcrates/vox-compiler/src/typeck/Diagnostics, severity, suggestions/fixes consumed by LSP — see language-diagnostic-drift-findings-2026.md.
Codegencrates/vox-compiler/src/codegen_rust/ (+ related)Rust and other emit paths; Web IR / frontend convergence in frontend-convergence-findings-2026.md.
Interpreter tiercrates/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.
Section titled “Related docs”