Compiler Toolchain Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Sploosh compiler toolchain is a bootstrap implementation in Rust designed to support an "AI-native" programming language. Its architecture prioritizes single-syntax dual-target compilation, enabling a single codebase to target both Web2 (Native LLVM, WASM) and Web3 (EVM, Solana SBF) environments. The toolchain is built as a workspace of modular crates, currently focused on a spec-first frontend implementation that enforces memory safety and actor-based concurrency rules at compile time.
Sources: README.md:1-15, VISION.md:7-15, Cargo.toml:1-10
Multi-Phase Compilation Roadmap
The compiler's execution logic is structured into distinct phases that align with the language specification. The toolchain is currently in the bootstrap phase, focusing on frontend components (Lexer, Parser, AST) before moving into semantic analysis and code generation.
The diagram shows the progression from raw source code through the specialized frontend crates into the planned semantic analysis and multi-target code generation backends.
Sources: README.md:90-105, crates/AGENTS.md:10-20
Compiler Workspace Components
| Crate | Purpose | Key Responsibilities |
|---|---|---|
sploosh-lexer | Tokenization | Implements UTF-8 lexing for §2 and §16.1 tokens, including 45 keywords. |
sploosh-parser | Syntax Analysis | Recursive-descent parser targeting the §16 EBNF grammar. |
sploosh-ast | Representation | Shared source spans, AST nodes, and operator enums. |
Sources: crates/AGENTS.md:13-17, README.md:80-87
Frontend Architecture
Lexical Analysis (sploosh-lexer)
The lexer transforms UTF-8 source text into a stream of tokens. It distinguishes between 36 reserved keywords and 9 contextual keywords. To maintain efficiency, the lexer is "allocation-free," utilizing spans to reference source text on demand. It specifically enforces rules for numeric literals, such as requiring decimal literals for float suffixes and validating base-aware separators.
This sequence illustrates the conversion of character sequences into categorized tokens with associated source spans.
Sources: crates/sploosh-lexer/src/lib.rs:1-15, crates/sploosh-lexer/src/lib.rs:150-200, crates/sploosh-lexer/src/lib.rs:320-335
Recursive-Descent Parsing (sploosh-parser)
The parser consumes the token stream to produce a typed AST. It implements a recursive-descent strategy with specific lookahead for ambiguous forms like attribute arguments and pipe stages.
- Block-Head Restriction: Implements restrictions (§5.1, §5.2) where struct literals cannot be the outermost expression in conditions (e.g.,
if,matchscrutinees) to prevent ambiguity with block delimiters. - Error Propagation: The parser handles the pipeline operator (
|>) where trailing?stages desugar to wrap the accumulated application. - Pattern Grammar: Supports complex matching including or-patterns (
A | B), tuple/struct destructuring, andifguards.
Sources: crates/sploosh-parser/src/lib.rs:1-50, crates/sploosh-parser/src/lib.rs:450-480, crates/sploosh-parser/src/lib.rs:600-650
Target Architecture & Enforcement
Sploosh enforces environment-specific restrictions at compile time based on the module type.
Dual-Target Enforcement
The toolchain distinguishes between standard modules and onchain mod blocks. The compiler is designed to reject non-deterministic or illegal operations when targeting Web3 environments.
| Feature | Standard Module | onchain mod |
|---|---|---|
| Float Math | Allowed | Rejected |
| Actor Spawning | Allowed | Rejected |
| File/Net IO | Allowed | Rejected |
| Storage Layout | Native/WASM | Solidity-Compatible |
| Reentrancy | Actor-Isolated | Guarded by Default |
Sources: VISION.md:85-110, README.md:45-65
The AST structure preserves visibility and attributes across all item types, including specialized on-chain modules.
Sources: crates/sploosh-parser/src/lib.rs:55-90, crates/sploosh-ast/Cargo.toml
Toolchain Development Standards
The toolchain bootstrap adheres to strict engineering requirements to ensure compatibility across diverse targets:
- Rust Version: Requires stable Rust 1.91+.
- CI Validation: All PRs are validated against a "Prompt Budget" to ensure the language core remains under 5,600 tokens for AI context loading.
- Agent-Friendly Diagnostics: The architecture includes plans for NDJSON output and machine-applicable fixes to facilitate AI tool-loop integration.
Sources: CONTRIBUTING.md:25-35, README.md:25-30, crates/AGENTS.md:45-55
Conclusion
The Sploosh Compiler Toolchain Architecture is a modular, Rust-based system designed to unify Web2 and Web3 development. By implementing a strict, spec-first frontend and planning for a multi-backend code generation strategy, the toolchain enables high-level safety and concurrency guarantees while maintaining a minimal footprint suitable for AI-driven development workflows.