[WaylandYang]

Not yet run on KVM. None of bm, bj or hk has /dev/kvm. This is compiled and unit-tested on macOS only. DESIGN-v0.6-FIRECRACKER.md lists what to verify first on a KVM host; until then every behaviour here is an assumption.

The optional backend from DESIGN-v0.6 §2, on upstream Firecracker (no fork), built on the Backend trait from #368.

What it keeps from v0.5

Shared page cache across forks	every child of a tag maps one memory file (File backend, MAP_PRIVATE)
Diff snapshot chains	a restored sandbox snapshots next as only its dirtied pages; chains are hard-linked into each image, assembled once into a cached dot file
Private disk per sandbox	reflinked; refuses to start where reflink does not work (DESIGN-v0.6 §7.5)
Clock after restore	date -s through the agent

Not included: live fork (needs the vendored fork; upstream #6270 is not merged), hugepages (file-backed hugetlbfs restore is upstream #6099), user volumes (refused with an error for now).

How

• The trait now covers preparation (template_root, prepare, layer, unmount, teardown), because a VM needs a disk image, not an overlay. runsc's implementations call bundle.rs exactly as before.
• Memory and disk travel together. Every image carries the disk as it was while the VM was paused. The VM's disk path is the relative rootfs.ext4, and Firecracker runs in the sandbox's own disk directory, so a vmstate opens the loading sandbox's copy, never the parent's. Then resume_vm:false → PATCH /drives/rootfs → resume, as in feat(vmm): give every restored child its own rootfs backing #321; any failure kills it unresumed.
• Fixed guest address 10.42.0.2 behind a tap in each netns, DNATed from the netns address, so snapshots restore into any namespace.
• Same cgroup as runsc, joined before exec; own session. Freeze, accounting, cgroup.kill and restart adoption are unchanged code.
• Guest: the agent starts the template's program from sandstorm.app= on the kernel command line. Port 8888 belongs to the agent.

Testing

• macOS: cargo test -p sandstorm-core (173 lib + integration) and cargo clippy --all-targets -D warnings pass. New tests: the API client against a fake socket, load ordering (no resume before the re-point, none after a failed one), chain reading/assembly, sparse diff application, boot args and the 2048-byte limit, prepare. Agent: rootfs-init/tests/test_agent_app.py.
• The Linux-only code (FICLONE, SEEK_DATA) is compiled for the first time by this PR's CI. CI's ext4 cannot reflink, so the two reflink tests skip there; apply_diff has its own test that runs.
• Unrelated and pre-existing on dev: wake::tests::a_wake_behind_a_full_queue_is_refused_at_once fails whenever it runs alone, and passes in the full suite.

First things to check on a KVM host

1. That a Diff after snapshot/load with dirty tracking holds exactly the pages dirtied since the load. If not, chains lose pages.
2. Boot, freeze/thaw, hot ↔ snapshot, branch + fork, detach + reattach, destroy, and a sandstormd restart with VMs running.
3. The four tiers' numbers; runsc's do not carry over.

🤖 Generated with Claude Code