AILANG Architecture
This section documents the internal architecture of AILANG for contributors and those who want to understand how the language works.
Core Concepts
Type System
AILANG uses a Hindley-Milner type system with row polymorphism and effect tracking. Learn about:
- Type inference pipeline (Surface AST → Core → Types → Evaluation)
- CoreTypeInfo: type storage and validation
- Row polymorphism for records and effects
- Dictionary passing for type classes
A-Normal Form (ANF)
All AILANG code is transformed to A-Normal Form before type checking and evaluation:
- Every non-trivial expression bound to a name
- Explicit sequencing
- Easy instrumentation and type-guided lowering
Adding Operators
Step-by-step guide for implementing new operators:
- Parser and token definitions
- Type checking rules
- Type-guided lowering
- Builtin registration
Debug Tools
CLI tools for understanding the compilation pipeline:
ailang debug ast- Inspect Core AST (ANF)ailang check -debug-compile- Compilation telemetryailang builtins list- Explore 128 registered builtinsailang docs- Stdlib documentation
Compilation Pipeline
Key Phases
- Parsing: Source text → Surface AST
- Elaboration: Surface AST → Core AST (ANF normalization)
- Type Inference: Core AST → Typed AST + CoreTypeInfo
- Validation: Verify CoreTypeInfo completeness
- Lowering: Type-directed operator specialization
- Evaluation: Execute lowered Core AST
Implementation Files
| Component | Location | Description |
|---|---|---|
| Lexer | internal/lexer/ | Tokenization |
| Parser | internal/parser/ | Surface AST construction |
| Elaboration | internal/elaborate/ | Surface → Core |
| Type System | internal/types/ | Type inference |
| Core AST | internal/core/ | ANF representation |
| Pipeline | internal/pipeline/ | Compilation orchestration |
| Evaluator | internal/eval/ | Interpretation |
| Builtins | internal/builtins/ | Built-in functions |
| Effects | internal/effects/ | Effect runtime |
Design Documents
For detailed design decisions and implementation history, see:
See Also
- Development Guide - Contributing to the codebase
- Development Workflow - Sprint planning and execution
- Testing Guide - Writing and running tests
- Debugging Guide - Debug flags and troubleshooting