The Capstone Projects
Eight projects. Each one takes something the curriculum deliberately deferred and makes it real.
They are optional, they are where the depth compounds, and several of them are the measurements that earlier ADRs promised. Doing project 1 is how ADR-002 stops being an opinion.
The Portfolio
| # | Project | Deferred from | What it makes real |
|---|---|---|---|
| 1 | Register VM | ADR-002 | The stack-vs-register measurement, on your workload |
| 2 | NaN Boxing | ADR-004 | 8-byte values, and what unsafe buys |
| 3 | Incremental GC | ADR-006 | Write barriers, and pause distribution |
| 4 | Coroutines | the introduction | Multiple call stacks; a VM-structure change |
| 5 | A Source Debugger | — | Breakpoints, stepping, locals; the payoff for debug info |
| 6 | WASM Build | the workspace rules | Proof the core has no OS dependency |
| 7 | Lua Compatibility Harness | Lab 26 | An independent oracle, at scale |
| 8 | An Upstream Contribution | — | The thing that turns a project into a career |
How to Choose
If you want to understand runtimes better: 1, 3, 4. Each changes the machine, not just its performance, and each forces you to re-derive an invariant you thought you understood.
If you want to ship something: 5, 6, 7. A debugger, a WASM build, and a compatibility harness are what make a runtime usable by people who did not build it.
If you want the strongest portfolio artifact: 8, and then 1 or 3 as the evidence that you can do the deep work. A merged PR to a real language runtime is a different kind of claim from a repository of your own.
If you have time for exactly one: project 1. It is the measurement ADR-002 promised, it is a weekend rather than a month, and it will change how you read every VM you encounter afterwards.
The Rules
Every project follows the curriculum's discipline, and the first two are the ones that make these projects worth doing rather than merely finishing:
- Baseline first. No project that touches performance starts without a committed measurement.
- The differential tests stay green. Every one of these changes the implementation and none of them may change the semantics. That is what the oracle is for, and projects 1 and 2 are exactly the situations it was built to protect.
- An ADR per project. Superseding an existing ADR is the normal outcome, and superseding is better than editing.
- A written result, including the negative ones. "We built a register VM and it was 8% faster, which did not justify the compiler complexity" is a better outcome than an unmeasured 30% claim.
What "Done" Looks Like
For each project:
- It works, with tests.
- The differential suite is green.
- A measurement, against a committed baseline, on your own machine.
- An ADR: context, options, decision, consequences — and which earlier ADR it supersedes.
-
A
docs/learning/entry with the thing that surprised you. - An honest paragraph on whether it was worth it.
That last item is the deliverable. Four of these eight projects will probably not be worth shipping, and knowing which four — from your own measurements rather than from folklore — is the point.
Next: Project 1 — Register VM.