v0.4 foundation: WpBranch primitive + 3 PoCs + wp-bench CLI

[WaylandYang]

v0.4's "live-fork" foundation: the snapshot-side UFFD_WP primitive, validated by three kernel-level PoCs, promoted into the forkd-uffd crate as WpBranch, and exposed via the forkd wp-bench subcommand. Tracking #101, design RFC in #156.

What this PR ships

1. Production library: forkd_uffd::wp_snapshot::WpBranch

A struct that owns one in-flight v0.4 BRANCH:

let branch = unsafe {
    WpBranch::begin(memfd, region, region_size, snapshot_path)?
};
// arm_duration() is the BRANCH pause-window analog
let arm = branch.arm_duration();
// bulk-copy still-clean pages from main thread while handler thread
// captures dirty pages in the background
let bulk_copied = unsafe { branch.bulk_copy_clean() }?;
// stop handler, fsync, return stats
let stats = branch.finalize()?;

raw.rs (pub(crate)) wraps the userfaultfd ioctls since the userfaultfd 0.8 crate doesn't expose UFFDIO_WRITEPROTECT or UFFDIO_REGISTER_MODE_WP. Disjoint from the existing handshake module (v0.3 restore-side).

2. CLI surface: forkd wp-bench

$ sudo forkd wp-bench --region-mib 1024
  region: 1024 MiB (262144 pages of 4096 bytes)
  populated in 379ms
  arm UFFDIO_WRITEPROTECT: 3.18ms       ← v0.4 pause-window analog
  bulk_copy_clean: 262144 pages in 424ms
  finalize: 6.58s                        ← fsync 1 GiB on ext4
  total: 7.02s
  ✓ snapshot consistent (1073741824 bytes all 0x42)

3. Three kernel-level PoCs (verifying design assumptions)

Experiment	What it validates	Result
experiments/v0.4-uffd-wp-poc/	UFFD_WP on memfd, host writes	3 ms/GiB linear, 0 consistency violations
experiments/v0.4-kvm-uffd-wp-poc/	UFFD_WP catches KVM guest writes through EPT (open question #1)	✓ flags=0x3, pre-write content captured
experiments/v0.4-thp-uffd-wp-poc/	UFFD_WP × transparent hugepages (open question #2)	4 KiB fault granularity preserved; memfd + NO_HUGEPAGE is cheapest

Each has its own RESULTS.md with empirical numbers.

v0.4 vs v0.3.4 comparison (extrapolated from PoC data)

Parent VM size	v0.3.4 pause	v0.4 pause	Speedup
1 GiB	~150 ms	3 ms	50×
4 GiB	~150 ms	13 ms	12×
8 GiB	~150 ms	26 ms	6×

v0.3.4 pause includes ext4 metadata + memory.bin write. v0.4 pause is UFFDIO_WRITEPROTECT only; memory.bin writes happen async outside the critical section.

What's NOT in this PR

• The full forkd-controller::branch_sandbox integration. Firecracker's /snapshot/create always writes memory.bin synchronously inside the pause; replacing it requires either an FC patch (vmstate-only mode), bypassing FC's snapshot API entirely with raw KVM_GET_REGS, or accepting the existing pause for vmstate alongside async memory capture. This is a multi-day spike tracked in DESIGN-v0.4.md and the next session.
• The --live-fork flag on forkd snapshot and the controller. Depends on the integration above.
• Kernel < 5.7 fallback (graceful degradation to the v0.3.4 path).
• Multi-vcpu race coverage (the PoCs use a single vcpu).

Test plan

• cargo test --release -p forkd-uffd wp_snapshot — passes (sudo required for unprivileged_userfaultfd)
• forkd wp-bench --region-mib 64 — 203 µs arm, consistent snapshot
• forkd wp-bench --region-mib 1024 — 3.18 ms arm, consistent snapshot
• CI green: rust (fmt + clippy + build + test) + bench-python

Branches touched

Crate	What changed
crates/forkd-uffd	new modules raw, wp_snapshot (~625 lines, Linux-only behind cfg)
crates/forkd-cli	new subcommand wp-bench + dep on forkd-uffd (Linux-only)
Cargo.toml (workspace)	three new experiments/v0.4-*-poc members

🤖 Generated with Claude Code