System Design & Architecture
An overview of the compiler sources, Rust bootstrap compiler, bytecode VM, and related tools in this repository.
compiler/*.aayu
The repository includes lexer, parser, analyzer, compiler, and UI-renderer sources in AAYU. The current CLI uses a separate Rust bootstrap compiler; a reproducible self-hosting comparison remains unfinished:
lexer.aayu
LZR Tokenizer with line & column tracking. Skips comments and normalizes tokens.
parser.aayu
Recursive descent AST generator for Models, Routes, Pages, Actions, Loops.
analyzer.aayu
Scope resolution, symbol table binding, and compile-time invariant checking.
compiler.aayu
Variable-length bytecode emission with two-pass jump offset patching.
ui_renderer.aayu
Transpiles declarative widget trees directly into DOM structures.
cargo build --release --manifest-path compiler_bootstrap/Cargo.toml
Repository Directory Layout
Crystalline organization ensuring zero confusion for contributors and AI agents.
| Directory | Core Technology | Architectural Purpose |
|---|---|---|
| compiler/ | Pure AAYU (.aayu) | Self-hosted lexer, parser, semantic analyzer, and compiler written 100% in AAYU. |
| runtime_rs/ | Native Rust | Bytecode VM, flat-stack base pointer, JIT engine, 4KB slotted disk B-Tree engine, ring BoringSSL FIPS crypto, and bounded thread pool server. |
| bin/ | Native Binaries & Seed | Precompiled aayu-vm.exe, aayuc.exe, aayu.exe, and aayuc.ayc bytecode seed. |
| std/ | Pure AAYU (.aayu) | Standard libraries: std/crypto.aayu (audited FIPS), std/payment.aayu, std/cloud_storage.aayu, std/oauth.aayu, std/db.aayu (4KB B-Tree), std/llm.aayu, std/quant.aayu, std/autograd.aayu, std/scientific.aayu, std/vector_db.aayu, std/tensor.aayu, std/liquid2.aayu, std/intent.aayu. |
| tests/ | Pure AAYU (.aayu) | Verification suites: 365 passing assertions across 20 suites (100% pass: Audited FIPS crypto, 4KB disk B-Tree DB, turnkey cloud/payment SDKs, Next-Gen AI/Math, compiler security, module namespaces, break/continue). |
| benchmarks/ | Pure AAYU (.aayu) | Empirical benchmark programs measuring loops, recursion, tensors, and memory compaction. |
| examples/ | Pure AAYU (.aayu) | Full-stack application examples: Conduit Realworld, Todo MVC, URL Shortener, Chat Server. |
| website/ | Next.js, React, TypeScript | Official documentation site, live benchmarks, architecture blueprint, and interactive tutorial. |
| vscode-aayu/ | TypeScript / JSON | VS Code syntax highlighting, code snippets, and language extension. |
The 64-Bit NaN-Box Memory Model
A tagged value representation for primitives and references to heap objects.
IEEE-754 Quiet NaN Bit Allocation
The VM stores tagged values in a 64-bit word. Primitive values and heap references use distinct tags; see `runtime_rs/src/vm.rs` for the implementation:
Why This Dominates Traditional VMs
- Tagged values: Primitive values and references are represented within the VM's 64-bit value format.
- Heap objects: Strings, arrays, and dictionaries are tracked by the runtime memory manager.
- Performance: Use the checked-in benchmarks for workload-specific measurements; results vary by machine and program.
Bytecode Instruction Set (ISA)
Silicon VM opcode definitions, widths, and stack effects.
| Hex | Instruction | Width | Stack Transition | Description |
|---|---|---|---|---|
| 0x00 | OP_HALT | 1 byte | [] -> [] | Terminates execution cleanly |
| 0x01 | OP_PUSH_CONST | 3 bytes | [] -> [val] | Pushes 16-bit constant from pool |
| 0x02 | OP_POP | 1 byte | [val] -> [] | Pops top stack value |
| 0x05 | OP_LOAD_VAR | 2 bytes | [] -> [val] | Loads local variable from slot 0..255 |
| 0x06 | OP_STORE_VAR | 2 bytes | [val] -> [] | Stores top stack item to local slot |
| 0x10 | OP_ADD | 1 byte | [a, b] -> [a+b] | Polymorphic add (Int, Float, Str, Arr) |
| 0x11 | OP_SUB | 1 byte | [a, b] -> [a-b] | Numeric subtract (Int, Float) |
| 0x12 | OP_MUL | 1 byte | [a, b] -> [a*b] | Numeric multiply (Int, Float) |
| 0x13 | OP_DIV | 1 byte | [a, b] -> [a/b] | Numeric division with zero check |
| 0x20 | OP_JMP | 3 bytes | [] -> [] | Unconditional jump to 16-bit offset |
| 0x21 | OP_JMP_IF_FALSE | 3 bytes | [cond] -> [] | Jumps if popped condition is false |
| 0x22 | OP_CALL | 3 bytes | [fn, args] -> [res] | Invokes function or action frame |
| 0x23 | OP_RET | 1 byte | [res] -> [res] | Returns from action frame |
| 0x26 | OP_CMP_EQ | 1 byte | [a, b] -> [bool] | Equality comparison (a == b) |
| 0x29 | OP_CMP_LT | 1 byte | [a, b] -> [bool] | Less-than comparison (a < b) |
| 0x30 | OP_STORE_STATE | 3 bytes | [val] -> [] | Stores runtime state; no WAL guarantee |
| 0x31 | OP_LOAD_STATE | 3 bytes | [] -> [val] | Reads key-value state from RAM |
| 0x51 | OP_PRINT | 1 byte | [val] -> [] | Native stdout print with newline |
Ready to build on AAYU?
Explore the tutorials, try the browser playground, or inspect the compiler and VM sources in the repository.