THE WHOLE TOOLCHAIN, WITH THE WIRES SHOWING.
When something breaks, do not fix three layers at once. Find the first liar. This map shows where syntax stops, machine work starts, and the ugly bugs usually hide.
00 front end and canonical meaning
Parsing produces syntax. Canonical HIR/semantic analysis decides types, profiles, intrinsic legality and interface meaning. A backend should consume analyzed meaning, not invent a second language while lowering.
10 native pipeline
HIR -> Native MIR -> target legalization -> O0 / O1 -> linear-scan allocation -> instruction selection -> ELF / COFF / PE / executable writer
The 12.4 manual remains the detailed machine-code owner. v13 uses that machinery for freestanding work instead of creating an unrelated kernel backend.
20 runtime and ownership
The first-party runtime owns allocation and Drop contracts described in 12.1. Collections in 12.3 sit on top of that ownership model. When debugging a collection bug, first separate semantic ownership, runtime allocation and backend code generation before changing all three.
30 ABI and file formats
12.2 owns the modern x86_64 ABI/file-format foundation. Win64 shadow space, SysV64 argument classes, ELF64 relocations, COFF and PE32+ are target contracts. They are not portable-language semantics.
40 VM as an independent execution path
The flat VM is useful because it gives canonical bytecode another execution boundary. Agreement between hosted, VM and native paths is meaningful only when they receive the same semantic program and the expected result is fixed independently.
50 freestanding v13
The v13 machine foundation introduces BIOS-first x86_64 discovery, memory ownership, interrupts, virtual storage/input and userspace gates. Virtual G1-G5 PASS does not authorize physical writes or certify arbitrary hardware.
60 release engineering
Release identity is a chain: exact commit → annotated tag → independent tagged exports → deterministic package A/B → package verifier/smoke → sealed receipt. The website stable ZIP is the exact reproducible v13.0 package, not a convenient file with the same name.
70 current source after 13.0
13.1 development adds a stricter portability analysis and explicit native floats. Start at portability, then f32/f64, C float ABI and same-source parity. These pages are a captured snapshot, not release documentation.
80 failure routing
| Observed failure | Start here |
|---|---|
| Type/profile rejection | HIR semantic analysis. |
| Hosted and VM disagree | Canonical lowering/bytecode/runtime boundary. |
| VM agrees, one native target differs | Native MIR legalization, selector or ABI. |
| O0 passes, O1 fails | Bounded optimization. |
| Object links incorrectly | Relocation/object writer/linker. |
| QEMU passes, physical machine fails | Hardware discovery/evidence. Do not rewrite language semantics first. |
90 change discipline
A safe compiler change starts by naming the semantic owner and the execution paths that must agree. Add or change the canonical representation first when the feature changes language meaning. Add target-specific lowering only after that representation exists. Then exercise hosted, VM and native paths with the same fixed expectation where the feature is target-neutral.
Do not use a passing backend as evidence that another backend is allowed to differ. Conversely, do not force target-specific ABI or privileged-machine behavior into the portable semantic layer. The distinction between shared meaning and target contract is one of the main mechanisms keeping the codebase understandable.