Compress vz machine state and overlap quiesce with disk copy

Implements the two remaining sections of the faster-standby-restore RFC
(Section C / APFS clonefile already shipped in #276).

Section A.1 — teach the snapshot-compression subsystem about the vz
machine-state file. Add machine-state.vzm to snapshotMemoryFileCandidates
at both the standby-latest level and the stored-payload-nested level, so
the existing async job compresses it and ensureSnapshotMemoryReady
decompresses it before restore. The filename constant moves to a
build-tag-free file in shimconfig (mirroring RosettaMountTag) so the
host-portable compression code can name it without pulling the darwin-only
package.

Section A.2 — optional synchronous compression in the shim. Add a
darwin/arm64 compressMachineStateFile helper (klauspost zstd; the vz
Save API is path-based and cannot stream-compress, so it is a post-write
pass) with a matching error stub off arm64 so the shim never references
zstd there. Gated behind a new CompressMachineState flag on the shim
snapshot request; the manifest still names the raw file and the .zst is
discovered by suffix.

Section B — overlap quiesce with the disk copy. After the VM is paused,
standbyInstance now runs the machine-state save and the guest-disk
CoW-clone concurrently under errgroup instead of serially, via an optional
overlap the running-source snapshot path supplies (vz only; other
hypervisors and auto-standby keep the serial path, byte-identical). The
overlapped disk copy prunes the snapshots subtree the save is writing and
copies it afterward, so the two legs never race; on either leg failing the
source is resumed and the partial snapshot dir is cleaned, matching the
serial path. forkvm's SkipRelativePaths now prunes a matched directory's
whole subtree (files still drop individually).

Plumbs CompressMachineState (+ optional level) through
hypervisor.SnapshotOptions -> vz Client.Snapshot -> shim request ->
handleSnapshot. When false (the default and the only value non-vz
hypervisors ever see) behavior is byte-identical to before.

Tests: machine-state participates in the compression candidate set and
.zst discovery; compress/decompress round-trips a synthetic .vzm; the
errgroup cancels its sibling on failure; standbyInstance resumes the
source when the disk leg fails; forkvm prunes a skipped directory subtree;
and a darwin/arm64 round-trip for compressMachineStateFile.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: rgarcia

cmd/vz-shim/save_restore_arm64.go

@@ -4,8 +4,11 @@ package main
 
 import (
 	"fmt"
+	"io"
+	"os"
 
 	"github.com/Code-Hex/vz/v3"
+	"github.com/klauspost/compress/zstd"
 )
 
 func validateSaveRestoreSupport(vmConfig *vz.VirtualMachineConfiguration) error {
@@ -27,3 +30,55 @@ func restoreMachineState(vm *vz.VirtualMachine, snapshotPath string) error {
 	// The vz wrapper accepts a filesystem path and constructs a file URL internally.
 	return vm.RestoreMachineStateFromURL(snapshotPath)
 }
+
+// compressMachineStateFile zstd-compresses statePath in place, producing
+// statePath+".zst" and removing the raw file on success. The vz framework
+// writes the whole machine-state file itself (SaveMachineStateToPath exposes no
+// io.Writer), so compression is a post-write pass over the complete file. Used
+// when the control plane overlaps the disk copy and wants the state file already
+// small before it reads it back. The control plane decompresses .zst -> raw in
+// ensureSnapshotMemoryReady before restore, so the discovered-by-suffix
+// convention matches the async compression job.
+func compressMachineStateFile(statePath string, level int) (string, error) {
+	src, err := os.Open(statePath)
+	if err != nil {
+		return "", err
+	}
+	defer src.Close()
+
+	// .zst.tmp is already skipped by the forkvm copy walk, so a concurrent disk
+	// clone never picks up the partial file.
+	tmp := statePath + ".zst.tmp"
+	dst, err := os.Create(tmp)
+	if err != nil {
+		return "", err
+	}
+	enc, err := zstd.NewWriter(dst, zstd.WithEncoderLevel(zstd.EncoderLevelFromZstd(level)))
+	if err != nil {
+		dst.Close()
+		_ = os.Remove(tmp)
+		return "", err
+	}
+	if _, err := io.Copy(enc, src); err != nil {
+		enc.Close()
+		dst.Close()
+		_ = os.Remove(tmp)
+		return "", err
+	}
+	if err := enc.Close(); err != nil {
+		dst.Close()
+		_ = os.Remove(tmp)
+		return "", err
+	}
+	if err := dst.Close(); err != nil {
+		_ = os.Remove(tmp)
+		return "", err
+	}
+	final := statePath + ".zst"
+	if err := os.Rename(tmp, final); err != nil {
+		_ = os.Remove(tmp)
+		return "", err
+	}
+	_ = os.Remove(statePath)
+	return final, nil
+}

cmd/vz-shim/save_restore_arm64_test.go

@@ -0,0 +1,59 @@
+//go:build darwin && arm64
+
+package main
+
+import (
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+
+	snapshotstore "github.com/kernel/hypeman/lib/snapshot"
+	"github.com/klauspost/compress/zstd"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestCompressMachineStateFileRoundTrip asserts compressMachineStateFile
+// produces machine-state.vzm.zst, removes the raw file, and that the compressed
+// bytes decompress back to the original (Section A.2).
+func TestCompressMachineStateFileRoundTrip(t *testing.T) {
+	dir := t.TempDir()
+	statePath := filepath.Join(dir, "machine-state.vzm")
+	payload := make([]byte, 1<<20)
+	for i := range payload {
+		payload[i] = byte(i*17 + i/5)
+	}
+	require.NoError(t, os.WriteFile(statePath, payload, 0o644))
+
+	out, err := compressMachineStateFile(statePath, snapshotstore.DefaultSnapshotCompressionZstdLevel)
+	require.NoError(t, err)
+	assert.Equal(t, statePath+".zst", out)
+
+	_, err = os.Stat(statePath)
+	assert.True(t, os.IsNotExist(err), "raw machine state should be removed after compression")
+	_, err = os.Stat(statePath + ".zst.tmp")
+	assert.True(t, os.IsNotExist(err), "temp file should not linger")
+
+	f, err := os.Open(out)
+	require.NoError(t, err)
+	defer f.Close()
+	dec, err := zstd.NewReader(f)
+	require.NoError(t, err)
+	defer dec.Close()
+	got, err := io.ReadAll(dec)
+	require.NoError(t, err)
+	assert.Equal(t, payload, got)
+}
+
+func TestCompressMachineStateFileMissingSource(t *testing.T) {
+	_, err := compressMachineStateFile(filepath.Join(t.TempDir(), "absent.vzm"), 0)
+	require.Error(t, err)
+}
+
+func TestResolveSnapshotCompressionLevel(t *testing.T) {
+	assert.Equal(t, snapshotstore.DefaultSnapshotCompressionZstdLevel, resolveSnapshotCompressionLevel(0))
+	assert.Equal(t, snapshotstore.DefaultSnapshotCompressionZstdLevel, resolveSnapshotCompressionLevel(-3))
+	assert.Equal(t, 5, resolveSnapshotCompressionLevel(5))
+	assert.Equal(t, snapshotstore.MaxSnapshotCompressionZstdLevel, resolveSnapshotCompressionLevel(1000))
+}

cmd/vz-shim/save_restore_unsupported.go

@@ -20,3 +20,7 @@ func saveMachineState(vm *vz.VirtualMachine, snapshotPath string) error {
 func restoreMachineState(vm *vz.VirtualMachine, snapshotPath string) error {
 	return fmt.Errorf("save/restore is only supported on darwin/arm64 (current arch: %s)", runtime.GOARCH)
 }
+
+func compressMachineStateFile(statePath string, level int) (string, error) {
+	return "", fmt.Errorf("save/restore is only supported on darwin/arm64 (current arch: %s)", runtime.GOARCH)
+}

cmd/vz-shim/server.go

@@ -16,6 +16,7 @@ import (
 
 	"github.com/Code-Hex/vz/v3"
 	"github.com/kernel/hypeman/lib/hypervisor/vz/shimconfig"
+	snapshotstore "github.com/kernel/hypeman/lib/snapshot"
 )
 
 // ShimServer handles control API and vsock proxy for a vz VM.
@@ -43,6 +44,13 @@ type VMInfoResponse struct {
 
 type snapshotRequest struct {
 	DestinationPath string `json:"destination_path"`
+	// CompressMachineState, when set, makes the shim zstd-compress
+	// machine-state.vzm before returning success. Used when the control plane
+	// overlaps the disk copy and wants the state file already small.
+	CompressMachineState bool `json:"compress_machine_state,omitempty"`
+	// CompressionLevel is the zstd level used when CompressMachineState is set.
+	// Zero falls back to the snapshot default.
+	CompressionLevel int `json:"compression_level,omitempty"`
 }
 
 type balloonRequest struct {
@@ -181,6 +189,13 @@ func (s *ShimServer) handleSnapshot(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	if req.CompressMachineState {
+		if _, err := compressMachineStateFile(machineStatePath, resolveSnapshotCompressionLevel(req.CompressionLevel)); err != nil {
+			http.Error(w, fmt.Sprintf("compress machine state failed: %v", err), http.StatusInternalServerError)
+			return
+		}
+	}
+
 	manifestPath := filepath.Join(req.DestinationPath, shimconfig.SnapshotManifestFile)
 	tmpManifestPath := manifestPath + ".tmp"
 	manifest := shimconfig.SnapshotManifest{
@@ -295,6 +310,18 @@ func (s *ShimServer) handleVMMShutdown(w http.ResponseWriter, r *http.Request) {
 	}()
 }
 
+// resolveSnapshotCompressionLevel maps the request's zstd level onto the valid
+// range, treating zero (the JSON-omitted default) as the snapshot default.
+func resolveSnapshotCompressionLevel(level int) int {
+	if level <= 0 {
+		return snapshotstore.DefaultSnapshotCompressionZstdLevel
+	}
+	if level > snapshotstore.MaxSnapshotCompressionZstdLevel {
+		return snapshotstore.MaxSnapshotCompressionZstdLevel
+	}
+	return level
+}
+
 func vzStateToString(state vz.VirtualMachineState) string {
 	switch state {
 	case vz.VirtualMachineStateStopped:

lib/forkvm/copy.go

@@ -79,6 +79,11 @@ func CopyGuestDirectoryWithOptions(srcDir, dstDir string, opts CopyOptions) erro
 			return nil
 		}
 		if _, ok := opts.SkipRelativePaths[filepath.Clean(relPath)]; ok {
+			// A skipped directory prunes its whole subtree; a skipped file is
+			// dropped on its own.
+			if d.IsDir() {
+				return filepath.SkipDir
+			}
 			return nil
 		}
 		if d.IsDir() && shouldSkipDirectory(relPath) {

lib/forkvm/copy_test.go

@@ -64,6 +64,24 @@ func TestCopyGuestDirectoryWithOptionsSkipsRelativePaths(t *testing.T) {
 	assert.FileExists(t, filepath.Join(dst, "overlay.raw"))
 }
 
+func TestCopyGuestDirectoryWithOptionsSkipsDirectorySubtree(t *testing.T) {
+	src := filepath.Join(t.TempDir(), "src")
+	dst := filepath.Join(t.TempDir(), "dst")
+
+	require.NoError(t, os.MkdirAll(filepath.Join(src, "snapshots", "snapshot-latest"), 0755))
+	require.NoError(t, os.WriteFile(filepath.Join(src, "snapshots", "snapshot-latest", "machine-state.vzm"), []byte("state"), 0644))
+	require.NoError(t, os.WriteFile(filepath.Join(src, "overlay.raw"), []byte("overlay"), 0644))
+
+	require.NoError(t, CopyGuestDirectoryWithOptions(src, dst, CopyOptions{
+		SkipRelativePaths: map[string]struct{}{
+			"snapshots": {},
+		},
+	}))
+
+	assert.NoDirExists(t, filepath.Join(dst, "snapshots"))
+	assert.FileExists(t, filepath.Join(dst, "overlay.raw"))
+}
+
 func TestCopyRegularFile(t *testing.T) {
 	src := filepath.Join(t.TempDir(), "src", "memory")
 	dst := filepath.Join(t.TempDir(), "dst", "snapshots", "snapshot-latest", "memory")

lib/hypervisor/hypervisor.go

@@ -140,6 +140,15 @@ type RestoreOptions struct {
 
 type SnapshotOptions struct {
 	DeferredMemoryBackingPath string
+
+	// CompressMachineState requests that the hypervisor compress the saved
+	// machine state before reporting the snapshot complete. Only the vz shim
+	// honors it; every other hypervisor ignores it, so the default (false)
+	// keeps behavior byte-identical to before this option existed.
+	CompressMachineState bool
+	// CompressionLevel is the optional zstd level for CompressMachineState.
+	// Zero means the snapshot default.
+	CompressionLevel int
 }
 
 // ForkNetworkConfig contains network identity fields for fork preparation.

lib/hypervisor/vz/client.go

@@ -71,7 +71,9 @@ type vmInfoResponse struct {
 }
 
 type snapshotRequest struct {
-	DestinationPath string `json:"destination_path"`
+	DestinationPath      string `json:"destination_path"`
+	CompressMachineState bool   `json:"compress_machine_state,omitempty"`
+	CompressionLevel     int    `json:"compression_level,omitempty"`
 }
 
 type balloonResponse struct {
@@ -249,8 +251,12 @@ func (c *Client) Resume(ctx context.Context) error {
 	return c.doPut(ctx, "/api/v1/vm.resume", nil)
 }
 
-func (c *Client) Snapshot(ctx context.Context, destPath string, _ hypervisor.SnapshotOptions) error {
-	req := snapshotRequest{DestinationPath: destPath}
+func (c *Client) Snapshot(ctx context.Context, destPath string, opts hypervisor.SnapshotOptions) error {
+	req := snapshotRequest{
+		DestinationPath:      destPath,
+		CompressMachineState: opts.CompressMachineState,
+		CompressionLevel:     opts.CompressionLevel,
+	}
 	body, err := json.Marshal(req)
 	if err != nil {
 		return fmt.Errorf("marshal snapshot request: %w", err)

lib/hypervisor/vz/shimconfig/config.go

@@ -4,14 +4,6 @@
 // the hypeman API server and the vz-shim subprocess.
 package shimconfig
 
-const (
-	// SnapshotManifestFile is the metadata file stored in snapshot directories.
-	// Kept as config.json to match existing snapshot path conventions.
-	SnapshotManifestFile = "config.json"
-	// SnapshotMachineStateFile is the serialized VM machine state filename.
-	SnapshotMachineStateFile = "machine-state.vzm"
-)
-
 // ShimConfig is the configuration passed from hypeman to the shim.
 type ShimConfig struct {
 	// Compute resources

lib/hypervisor/vz/shimconfig/paths.go

@@ -0,0 +1,13 @@
+package shimconfig
+
+// These snapshot path constants carry no build constraint so the host-portable
+// snapshot-compression subsystem (built on Linux) can name the vz machine-state
+// file when deciding what to compress/decompress, while the rest of the package
+// stays darwin-only.
+const (
+	// SnapshotManifestFile is the metadata file stored in snapshot directories.
+	// Kept as config.json to match existing snapshot path conventions.
+	SnapshotManifestFile = "config.json"
+	// SnapshotMachineStateFile is the serialized VM machine state filename.
+	SnapshotMachineStateFile = "machine-state.vzm"
+)