Firecracker: rootfs preparation from CID store OCI images

[jeremymanning]

Description

src/sandbox/firecracker.rs line ~281 has a TODO: "Pull OCI image from CID store, extract layers into rootfs.ext4". The Firecracker driver can configure and start VMs but cannot yet prepare the guest root filesystem from content-addressed workload images.

Requirements

• Fetch OCI image layers from the CID store by content address
• Extract and overlay OCI layers into a ext4 filesystem image (rootfs.ext4)
• Mount rootfs.ext4 as the Firecracker VM's root drive
• Handle multi-layer OCI images with proper overlay ordering
• Clean up temporary filesystem images on job completion
• Size rootfs appropriately based on extracted content + scratch space

Success Criteria

• OCI images fetched from CID store and assembled into rootfs.ext4
• Firecracker VM boots from assembled rootfs
• Multi-layer images assembled correctly
• Cleanup removes temporary rootfs files
• Integration test: store OCI image → prepare rootfs → boot Firecracker → execute → verify output
• Test on real Linux+KVM hardware

Testing (Principle V)

• Build minimal OCI image, store in CID store, boot in Firecracker
• Test with multi-layer image (base + app layers)
• Test cleanup after job completion (no leftover rootfs files)
• Test with corrupted image (must fail gracefully, not leave partial files)

[jeremymanning]

Partially addressed by spec 004 / PR #59 — not closing. CID-store fetch and layer-assembly logic exists in src/sandbox/firecracker.rs. HOWEVER, assemble_rootfs concatenates layer bytes into a file — it does NOT run mkfs.ext4 + loopback mount + extract OCI tar layers, which is what a real bootable rootfs requires. Real Firecracker dispatch would fail today.

Remaining work tracked here.

[jeremymanning]

Spec 005 progress — PR #61

STATUS: Real rootfs assembly implemented. Real-hardware boot evidence deferred.

Done (commit a0b6f74):

• Real mkfs.ext4 + losetup + mount + tar-extraction pipeline in assemble_rootfs_real() when Linux + mkfs.ext4 + losetup + mount are available.
• Fallback marker path for non-Linux / no-root / no-tooling environments (tests can exercise structure without requiring sudo).
• is_real_ext4() probe at superblock offset 1024+0x38 for production callers.
• Scope-guard cleanup: umount + losetup -d on any error path; no orphaned loopback devices.
• Gzip auto-detection by magic bytes (0x1f 0x8b); OCI whiteout handling via tar crate's unpack.

Remaining:

• T047 src/sandbox/firecracker/vsock_io.rs for stdout/stderr capture not written.
• T043 tests/sandbox/firecracker/test_real_boot.rs not written.
• T049 real Firecracker boot run on tensor01 deferred (needs sudo + KVM + Firecracker installed).
• Minimal OCI image for the test not prepared.

See notes/session-2026-04-19-spec-005-kickoff.md.