sparsify snapshot: punch zero pages to reduce disk usage by ~80%

After writing the HLS snapshot, scan for all-zero 4 KiB pages and
punch them with fallocate(PUNCH_HOLE). This makes the file sparse:
zeros still read back via mmap but consume no disk blocks.

On a typical pyhl snapshot (Python + pandas/numpy warm):
  Before: 2016 MiB on disk
  After:   648 MiB on disk (same 2016 MiB apparent size)

No load-time overhead — mmap of sparse files is identical to dense.
Linux-only; other platforms get a no-op fallback.

Signed-off-by: danbugs <danilochiarlone@gmail.com>

Author: danbugs

host/Cargo.lock

@@ -38,4 +38,5 @@ base64 = "0.22"
 
 [target.'cfg(unix)'.dependencies]
 nix = { version = "0.29", features = ["fs"] }
+libc = "0.2"
 

host/Cargo.toml

@@ -373,8 +373,9 @@ fn cmd_setup(args: SetupArgs) -> Result<()> {
         mib(&dst_initrd)
     );
     eprintln!(
-        "  snapshot: {} ({} MiB)",
+        "  snapshot: {} ({} MiB on disk, {} MiB apparent)",
         dst_snapshot.display(),
+        disk_mib(&dst_snapshot),
         mib(&dst_snapshot)
     );
     Ok(())
@@ -384,6 +385,19 @@ fn mib(p: &Path) -> u64 {
     fs::metadata(p).map(|m| m.len() / 1024 / 1024).unwrap_or(0)
 }
 
+#[cfg(unix)]
+fn disk_mib(p: &Path) -> u64 {
+    use std::os::unix::fs::MetadataExt;
+    fs::metadata(p)
+        .map(|m| m.blocks() * 512 / 1024 / 1024)
+        .unwrap_or_else(|_| mib(p))
+}
+
+#[cfg(not(unix))]
+fn disk_mib(p: &Path) -> u64 {
+    mib(p)
+}
+
 /// Lightweight timestamp (seconds since epoch in ISO-8601-ish) so we don't
 /// need to pull chrono just for the VERSION stamp.
 fn now_iso8601() -> String {

host/src/bin/pyhl.rs

@@ -1355,17 +1355,19 @@ impl Sandbox {
         Ok(())
     }
 
-    /// Persist the current post-evolve (or post-`snapshot_now`) snapshot
-    /// to disk so a later process can skip evolve + init and go straight
-    /// to `call`. Uses hyperlight's `Snapshot::to_file` — the file
-    /// format and cross-platform mmap load are documented in
-    /// hyperlight/docs/snapshot-file-implementation-plan.md.
+    /// Persist the current snapshot to disk as a sparse file.
+    ///
+    /// After writing the raw HLS snapshot, zero-filled 4 KiB pages are
+    /// punched out with `fallocate(PUNCH_HOLE)` so they consume no disk
+    /// space. The file is still mmap-loadable — holes read back as
+    /// zeros with no decompression overhead.
     pub fn save_snapshot<P: AsRef<Path>>(&self, path: P) -> Result<()> {
         let snap = self
             .snapshot
             .as_ref()
             .ok_or_else(|| anyhow!("no snapshot present; build() or snapshot_now() first"))?;
         snap.to_file(path.as_ref())?;
+        sparsify_snapshot(path.as_ref())?;
         Ok(())
     }
 
@@ -1530,6 +1532,67 @@ pub fn run_vm_capture_output(
     })
 }
 
+// ---------------------------------------------------------------------------
+// Snapshot sparsification
+// ---------------------------------------------------------------------------
+
+/// Punch holes in zero-filled 4 KiB pages of a snapshot file.
+///
+/// The HLS snapshot format is a 4 KiB header followed by a dense memory
+/// blob where ~80 % of pages are all-zeros (unused heap). Punching them
+/// with `fallocate(PUNCH_HOLE)` turns the file sparse — the zeros still
+/// read back via mmap but consume no disk blocks.
+#[cfg(target_os = "linux")]
+fn sparsify_snapshot(path: &Path) -> Result<()> {
+    use std::os::unix::io::AsRawFd;
+
+    let file = std::fs::OpenOptions::new()
+        .read(true)
+        .write(true)
+        .open(path)?;
+    let len = file.metadata()?.len();
+    let mmap = unsafe { memmap2::Mmap::map(&file)? };
+
+    const PAGE: usize = 4096;
+    const HEADER: usize = PAGE;
+    let zero_page = [0u8; PAGE];
+
+    let mut punched = 0u64;
+    let mut offset = HEADER;
+    while offset + PAGE <= len as usize {
+        if mmap[offset..offset + PAGE] == zero_page {
+            let ret = unsafe {
+                libc::fallocate(
+                    file.as_raw_fd(),
+                    libc::FALLOC_FL_PUNCH_HOLE | libc::FALLOC_FL_KEEP_SIZE,
+                    offset as i64,
+                    PAGE as i64,
+                )
+            };
+            if ret == 0 {
+                punched += 1;
+            }
+        }
+        offset += PAGE;
+    }
+    drop(mmap);
+
+    if punched > 0 {
+        eprintln!(
+            "  sparsified: punched {} zero pages ({} MiB saved on disk)",
+            punched,
+            punched * 4 / 1024
+        );
+    }
+
+    Ok(())
+}
+
+#[cfg(not(target_os = "linux"))]
+fn sparsify_snapshot(_path: &Path) -> Result<()> {
+    Ok(())
+}
+
 // ---------------------------------------------------------------------------
 // FsSandbox tests — prove that host-side path resolution rejects escapes.
 //