200. Capstone: the whole machine

Where Track B started

Chapter 121’s first program was three lines:

fn main() {
    println!("Hello, Drip!");
}

That chapter’s argument was about memory. Viscosity exists because JavaScript gives you no say over layout, so it has to trick the engine into a struct of arrays; Rust lets you decide, with a strict inspector checking the plans. Eighty chapters later, both of the book’s large programs exist in both languages.

What you built

Drip, three times. A tree-walking interpreter in TypeScript (Part III), a bytecode VM in TypeScript (Part IV), and drip-rs, the same VM design in Rust (Part X): typed arena handles instead of pointers, a mark-sweep collector with explicit roots, #![forbid(unsafe_code)], and the shared corpus as its judge.

Viscosity, twice. The TypeScript reference (Parts VII and VIII), and its Rust port (Part XI): VIR in arenas, the plugin trait, oxc for parsing, the SSA builder and dataflow framework, the analyses, the cost model, the code generators for SoA and AoSoA, explain with code frames, and PGO.

Two languages. The JavaScript plugin and the Python plugin both lower to the same VIR, so the analyses and the planner never see syntax. Both exist in both engines.

Three ways to run it. A native CLI (chapter 197), the same engine as WebAssembly in an npm package (189, 190), and that WebAssembly inside this book’s Playground (191).

Every one of these is checked against another. drip-rs runs the corpus the TypeScript VM runs. The Rust engine reproduces every stored output of the TypeScript engine byte for byte, and the fuzzer keeps generating programs to compare them on. The compiled programs are run against their originals. That chain of checks is what makes “the same machine, in Rust” a claim you can test rather than a hope.

One program, all the way through

Here is a small program with two collections, one worth transforming and one that can’t be. The step-through follows it through the Rust engine. The VIR, analysis and plan listings come from a small program of mine (not in the repository) that calls the crates directly; the code and the report come from the viscosity CLI. All of it is real output, trimmed to fit:

const ps = [];
for (let i = 0; i < 1000; i++) {
  ps.push({ x: i, vx: 1, hp: 3 });
}
for (let t = 0; t < 10; t++) {
  for (const p of ps) p.x += p.vx;
}
const qs = [];
for (let i = 0; i < 100; i++) {
  qs.push({ x: i, vx: 1, hp: 3 });
}
let s = 0;
for (const p of ps) s += p.x;
console.log(s, qs[0]);

Read the stages against the book. oxc parsed it (chapter 172) and the plugin lowered it to VIR in SSA form, where line 6’s for…of became a phi, a length check, an index.get, two field.gets and a field.set (173, 176). The analyses saw only VIR: they found two collections (178), three numeric fields each (179), and an escape for qs when qs[0] was passed to console.log (180). They found the two loops over ps and their fields (181), and proved both of its indexes in bounds. The cost model wrote its reasons as it decided (182), the emitter turned ps into three Float64Array columns (183), and explain --frames put carets under qs[0] (185). Both programs print 509500 { x: 0, vx: 1, hp: 3 }. The TypeScript CLI prints the same report, byte for byte.

Run it yourself, on the Rust engine compiled to WebAssembly (the toggle switches to TypeScript, and the decisions don’t change):

Try breaking it: change line 14 to print qs[0].hp instead, and qs is refused for a different reason, because now no loop touches its fields. Make the first loop run to 10, and ps falls under the 64-element threshold.

What it measured

Chapter 199’s matrix holds the summary. On Node, Viscosity sped up all five end-to-end programs, with a geometric mean of 2.54×; on Bun, 1.74×, with heat gaining nothing. The Rust compiler is up to 5.26× faster than the TypeScript one inside a warm Node process (an upper bound, chapter 199 explains why), and 10.9× faster as a command-line tool, mostly because it doesn’t start Node. drip-rs is 4× faster than the TypeScript VM. Every figure is from one shared cloud machine, and the files record the noise beside them.

What is still open

An honest capstone lists what isn’t done. Some items are chores; some are research.

• Nothing is published (chapter 198). Every crate now packages, but there is no changelog yet, and whether and when to publish is Tariq’s decision.
• The Rust port has gaps. It rejects TypeScript input (the reference strips types with sucrase, and copying sucrase’s exact output is out of scope), and its syntax errors are worded by oxc, not acorn. Neither engine profiles Python programs.
• The cost model can’t see the engine. It decides from size and access patterns, with a 64-element threshold, and the matrix showed the same output gaining a lot on V8 and nothing on JSC for heat. Why is still a hypothesis without an engine trace (chapter 199).
• Many ordinary programs are refused, as chapter 118 listed: sorting, classes as records, varying shapes, exported arrays. Hot/cold splitting is by type only.
• Every version emits source code. There is no WebAssembly back end for the compiled programs (chapter 117); WebAssembly runs the compiler, not its output.
• Drip’s VMs share a limit: 256 constants per chunk, which is why string_equality runs only on the tree-walker.

Going further

If you want to keep going, each of these starts from code you have read:

• Confirm or refute the heat hypothesis. Take an engine trace of heat’s objects on V8 (chapter 72 shows how to watch the engine work), and see whether its fields really are boxed doubles.
• Teach the cost model about engines. Run the matrix on more machines and engines, and see whether a per-engine threshold would have predicted Bun’s results.
• Add a third language. The plugin trait (chapter 171) is the whole contract. The Python plugin shows what the minimum looks like.
• Grow the subset. Pick one refusal from chapter 118, make the analysis prove it safe, and let the fuzzer tell you whether you were right (node scripts/fuzz.mjs --count 20000).
• Fix the small things: the wasm smoke test in CI, a changelog, a Python fuzzer (chapter 188).

Your turn

The core exercise rebuilds the heart of the planner from memory: the order of its questions and the exact words of its answers.

// A collection as the analyses saw it
// (simplified from core::Collection).
struct Loop {
    line: u32,
    func: &'static str,
    // the fields it reads or writes
    touches: Vec<&'static str>,
}

struct Coll {
    fields: Vec<&'static str>,
    numeric: bool, // every field
    loops: Vec<Loop>,
    size: f64,
    bailouts: Vec<&'static str>,
}

#[derive(Debug, PartialEq)]
enum Layout {
    Aos,
    Soa,
}

const NO_NUM: &str = "no field is \
    provably numeric, so there are no \
    typed columns to gain";
const NO_LOOP: &str = "no loop reads \
    or writes its fields, so a new \
    layout cannot pay off";

fn plan(
    c: &Coll,
    min: f64,
) -> (Layout, Vec<String>) {
    todo!()
}

What you learned

• The book built Drip three times and Viscosity twice, for two languages, and runs the Rust engine natively, in Node and in the browser.
• Every implementation is checked against another: the shared corpus, byte-identical fixtures, the fuzzer, and original-versus-compiled runs.
• One program passes through parse, lower, analyze, plan, emit and explain, and each line of its output can be traced to a chapter.
• What is open is known and written down: publishing, the port’s gaps, an engine-blind cost model, refused programs, no WebAssembly output.
• Mastery is being able to build it again, and to say how you would know it works.

That is the end of the book. It started from a question about where an array of objects sits in memory, and every chapter since has been one step towards being able to answer it with a tool you understand all the way down. The code is in the repository, the numbers are in its result files, and the rough edges are listed above. Fifteen minutes at a time, you built the whole machine.