CI-003: qemu/ checkpoint store — hash-named staged VM images

Now:: OPEN

CI runner disks live in a qemu/ dir as a chain of content-addressed qcow2 checkpoints: base OS → toolchain → jab-built, each file named by a hash of what produced it. A per-worktree be/test/ run boots a throwaway overlay backed by the jab-built checkpoint, so jab is built once per rev, never per run. This refines CI-001's flat "base image + overlay per runner" into a multi-stage chain; revert/close remains rm <overlay>.

Input

Context

CI-001 TODOs 2–3 (runner images) assume one base + one overlay; every run would redo clone+build of jab inside the VM.
qcow2 backing chains layer like docker images: a child stores only blocks changed vs its parent; parents stay immutable while referenced.
Measured on this host (qemu-img 10.1.3): overlay create 7 ms, discard (rm) 1 ms — the disk open/close is effectively free.
The real open cost is boot, not disk: cold qemu boot ~~5–15 s Ubuntu,~~ 20–40 s FreeBSD; loadvm restore of a running-state snapshot ~1–3 s (RAM-size bound). Numbers are estimates until measured on real images.

Goals

qemu/ dir holding checkpoints qemu/<hash>.qcow2; hash identifies the stage content, so a runner picks its start state by name alone.
Open a run = create overlay backed by a checkpoint (ms); close = rm the overlay (ms); the checkpoint chain is never mutated by a run.
Rebuilding a stage (new jab rev) mints a new hash-named file; old chains stay bootable until GC'd.

Constraints

A checkpoint is immutable once any overlay backs onto it; rebuild means a new file, never in-place qemu-img commit into a referenced parent.
Hash naming is content-addressed from (parent hash, stage recipe, source rev) — never mtime/serial; exact scheme to align with beagle hashlets.
RAM checkpoints are per runner flavor, not per rev: a savevm stream costs ~0.3–1× guest RAM on disk (zero pages skipped), a few GB each.
Same wire rules as CI-001: no shared mounts; images provisioned over ssh/beagle wire only.

WIP

Design decisions

Chain: <os-base> ← <toolchain> ← <jab@rev> ← run overlay (throwaway). Per-commit increments still ride the warm ninja cache inside the <jab@rev> clone, checkpoints cover the coarse stages.
Checkpoint creation: boot parent with no children, run the stage recipe, clean shutdown, hash, rename into qemu/<hash>.qcow2.

TODOs

1. qemu/ layout + hash-naming spec, folded into meta/ci.mkd (CI-001 TODO 1).
2. make-checkpoint script: boot parent → recipe → shutdown → hash → rename; refuse if parent already has children.
3. open-run/close-run script: overlay create / rm around a test run.
4. Measure real cold-boot and loadvm times on the actual Ubuntu and FreeBSD images; record here.
5. GC: delete checkpoints no run/child references, by hash.
6. loadvm fast-open: one "booted, idle" savevm RAM snapshot per runner flavor (drop guest caches before saving); open-run does loadvm (~1–3 s) instead of cold boot — kills the FreeBSD boot cost. Verify overlay+internal-snapshot interplay.

Blockers and bummers

None; feeds CI-001 TODOs 2–3. FreeBSD viability still gated by CI-001 TODO 3.

Outcome

Open. Filed 2026-07-24 from the incremental-snapshot discussion.