Add APFS clonefile fast path for macOS VM disk forks (#276)

* Add design proposal: APFS clonefile fast path for macOS VM forks

Documents wiring clonefile(2) into the forkvm reflink slot on darwin so
VM disk forks become copy-on-write-instant on Apple Silicon, with a
sparse-copy fallback for cross-volume cases.

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

* forkvm: add APFS clonefile(2) reflink fast path on darwin

Wire Apple's clonefile(2) into forkvm's reflink->sparse fallback ladder so
forking a guest directory on APFS becomes a near-instant, copy-on-write,
space-shared operation instead of a dense SEEK_DATA/SEEK_HOLE byte copy.

clonefile(2) requires the destination to not exist, so the darwin path removes
any stale destination first, clones with CLONE_NOFOLLOW|CLONE_NOOWNERCOPY, then
chmods to honor the perms contract. Unsupported/cross-volume failures
(ENOTSUP/EOPNOTSUPP/EXDEV/EEXIST/EINVAL/ENOTDIR) map to ErrReflinkUnsupported to
fall back to the sparse copy; EIO/ENOSPC/EACCES propagate. The non-Linux stub is
retagged to !linux && !darwin so darwin uses the new file.

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

* TEMP(ci): narrow to forkvm reflink feature — revert before merge

Disable the linux test and e2e-install jobs on this branch and run only the
forkvm tests on the darwin runner (make test TEST='Reflink|CopyGuestDirectory|
CopyRegularFile|Sparse|Clone') so this PR gets fast, focused darwin signal.
Revert this commit before merge.

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

* TEMP(ci): quote forkvm test regex so the | survives the make recipe

The make recipe substitutes -run=$(TEST) unquoted, so the recipe shell split
the alternation on |. Wrap the regex in embedded single quotes so go test
receives it intact. Part of the temporary forkvm-only narrowing; revert before
merge.

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

* forkvm: fix darwin clone tests for the macOS runner

Use a short /tmp base in the clone-correctness test so the unix socket fits the
sockaddr length limit (macOS t.TempDir() under /var/folders is too long), and
assert CoW block sharing via volume free space (statfs) rather than per-file
st_blocks, which still reports the full logical size for an APFS clone.

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

* forkvm: harden darwin clone tests and tighten errno mapping

Address review findings on the APFS clonefile fast path:
- SharesBlocks now compares the clone's free-space consumption against a
  dense control file written in the same window instead of an absolute
  statfs delta, so concurrent cross-package activity on the shared runner
  perturbs both samples rather than flaking the assertion.
- Drop EINVAL and ENOTDIR from isReflinkUnsupportedError: on clonefile(2)
  these are programming/path errors, not capability signals, so silently
  falling back would mask a broken flag set. They now propagate.
- Add skipUnlessAPFS so clone tests fail hard (not skip) when
  HYPEMAN_REQUIRE_APFS_CLONE=1, preventing a false green on a non-APFS
  runner; clone-correctness probes APFS before asserting.
- Add a darwin integration test that injects a clonefile rejection via a
  test seam and verifies the sparse fallback still yields identical bytes.
- Trim the CLONE_NOFOLLOW comment to note it is defensive only.

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

* TEMP(ci): verbose darwin run + require APFS clone — revert before merge

Set VERBOSE=1 so the narrowed darwin run logs per-test PASS/SKIP (proving
the clone tests executed), and HYPEMAN_REQUIRE_APFS_CLONE=1 so an
unexpected non-APFS skip fails the step instead of reporting a false
green. Revert alongside the other TEMP(ci) commits before merge.

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

* ci: restore full test workflow (drop temporary Rosetta-narrowing)

Reverts the temporary CI narrowing used during development; runs the full
linux + darwin + e2e-install suite again.

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

* forkvm: add macOS fork-speed benchmark (clonefile vs sparse)

BenchmarkForkGuestDisk copies a dense guest-disk-shaped file via the APFS
clonefile fast path and the sparse-copy fallback (the pre-clonefile
behavior) for an apples-to-apples comparison. Includes a temporary CI
step to capture the numbers on the macOS runner.

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

* ci: drop temporary fork-speed benchmark step

Numbers captured; the BenchmarkForkGuestDisk benchmark remains runnable
via `go test -bench=BenchmarkForkGuestDisk ./lib/forkvm/`.

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

* instances: add end-to-end VM fork-speed measurement

TestVZForkSpeed (gated behind HYPEMAN_FORK_BENCH) times mgr.ForkInstance
end to end — copy guest disk + rewrite manifest + materialize a stopped
instance — with the APFS clonefile fast path vs the sparse fallback, on a
source given a dense overlay. Includes a temporary CI step to capture the
numbers on the macOS runner.

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

* ci: drop temporary e2e fork-speed step

Numbers captured; TestVZForkSpeed remains runnable via HYPEMAN_FORK_BENCH=1.

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

* Address review: align clonefile RFC with shipped errno behavior

- Drop EEXIST from isReflinkUnsupportedError: the pre-clone os.Remove
  owns the "destination exists" case, so a per-file EEXIST is unreachable
  and should propagate rather than flip the whole walk to sparse.
- Remove the flake-prone CoW free-space test and its statfs helpers; the
  fork-speed benchmark already evidences the space/latency win.
- Reconcile the RFC's errno block, prose, and testing plan with the
  shipped mapping (EINVAL/ENOTDIR/EEXIST propagate, not fall back), soften
  the perm-parity claim (umask divergence), and trim volatile x/sys
  generated-file line numbers to stable public symbols.

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

* forkvm: address review — CoW write-isolation test + test hygiene + doc fixes

From hiro's review of #276 (all non-blocking):
- Add TestCopyRegularFileReflink_WriteIsolation: writing to a clone must not
  modify the source (the headline CoW correctness property; previously only
  verified manually).
- fork_speed_darwin_test: reset the global reflink flag via t.Cleanup so a
  require failure mid-loop can't leak disabled-state into other tests.
- copy_bench_darwin_test: note the shared source means the sparse sub-benchmark
  reads cache-warm (ratio valid; absolute sparse number is warm-cache).
- copy_reflink_darwin_test: listener close via t.Cleanup (consistency).
- proposal: correct the unix.Clonefile availability note (generated per-arch,
  links on both darwin/arm64 and darwin/amd64; verified via go doc).

The reflinkDisabled flag is left in place: it predates this PR (lib/forkvm/copy.go
on main) and is used by existing tests to exercise the sparse fallback path
deterministically; removing it is out of scope here.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: rgarcia <72655+rgarcia@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: rgarcia

docs/proposals/apfs-clonefile-forks.md

@@ -0,0 +1,95 @@
+//go:build darwin
+
+package forkvm
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"testing"
+)
+
+// benchDiskSizeBytes returns the size of the synthetic guest disk copied by the
+// fork benchmark. Override with HYPEMAN_BENCH_DISK_BYTES (bytes); defaults to 2 GiB.
+func benchDiskSizeBytes(b *testing.B) int64 {
+	if v := os.Getenv("HYPEMAN_BENCH_DISK_BYTES"); v != "" {
+		n, err := strconv.ParseInt(v, 10, 64)
+		if err != nil {
+			b.Fatalf("invalid HYPEMAN_BENCH_DISK_BYTES %q: %v", v, err)
+		}
+		return n
+	}
+	return 2 << 30
+}
+
+// writeDenseFile writes sizeBytes of non-zero data so the sparse-copy fallback
+// has real work to do (a hole-free extent it must read and rewrite in full).
+func writeDenseFile(path string, sizeBytes int64) error {
+	f, err := os.Create(path)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+
+	buf := make([]byte, 1<<20)
+	for i := range buf {
+		buf[i] = 0xAB
+	}
+	for written := int64(0); written < sizeBytes; {
+		n := int64(len(buf))
+		if rem := sizeBytes - written; rem < n {
+			n = rem
+		}
+		if _, err := f.Write(buf[:n]); err != nil {
+			return err
+		}
+		written += n
+	}
+	return f.Sync()
+}
+
+// BenchmarkForkGuestDisk measures the dominant cost of forking a VM on macOS:
+// copying the guest disk. It compares the APFS clonefile(2) fast path against
+// the sparse-copy fallback, which is the pre-clonefile behavior (reflink
+// disabled).
+//
+// Both sub-benchmarks read the same source file, so by the time the sparse run
+// executes the source is cache-warm: the clonefile-vs-sparse ratio is valid, but
+// read the absolute sparse number as a warm-cache best case, not a cold read.
+//
+// Run with, e.g.:
+//
+//	go test -run='^$' -bench=BenchmarkForkGuestDisk -benchmem -benchtime=5x ./lib/forkvm/
+func BenchmarkForkGuestDisk(b *testing.B) {
+	size := benchDiskSizeBytes(b)
+	dir := b.TempDir()
+	src := filepath.Join(dir, "disk.raw")
+	if err := writeDenseFile(src, size); err != nil {
+		b.Fatalf("write source disk: %v", err)
+	}
+
+	for _, tc := range []struct {
+		name     string
+		disabled bool
+	}{
+		{"clonefile", false}, // with the change
+		{"sparse", true},     // without the change (reflink fallback)
+	} {
+		b.Run(tc.name, func(b *testing.B) {
+			SetReflinkDisabled(tc.disabled)
+			b.Cleanup(func() { SetReflinkDisabled(false) })
+			b.SetBytes(size)
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				dst := filepath.Join(dir, fmt.Sprintf("copy-%s-%d.raw", tc.name, i))
+				if err := CopyRegularFile(src, dst); err != nil {
+					b.Fatalf("copy: %v", err)
+				}
+				b.StopTimer()
+				_ = os.Remove(dst)
+				b.StartTimer()
+			}
+		})
+	}
+}

lib/forkvm/copy_bench_darwin_test.go

@@ -0,0 +1,74 @@
+//go:build darwin
+
+package forkvm
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+
+	"golang.org/x/sys/unix"
+)
+
+// cloneFileFn indirects clonefile(2) so tests can inject a rejection and
+// exercise the sparse-copy fallback. Production leaves it untouched.
+var cloneFileFn = unix.Clonefile
+
+// copyRegularFileReflink clones srcPath to dstPath via clonefile(2) (APFS
+// copy-on-write). On APFS this is effectively instantaneous and consumes no
+// additional space until the cloned file's pages diverge.
+//
+// Unlike the Linux FICLONE path, clonefile(2) requires the destination to NOT
+// exist: it creates the destination as part of the clone. We remove any stale
+// destination first and must not pre-create or O_TRUNC it.
+//
+// Returns ErrReflinkUnsupported when the volume cannot serve the clone (e.g.
+// cross-volume EXDEV, non-APFS ENOTSUP); callers fall back to a sparse copy.
+// Real errors (EIO, ENOSPC, EACCES) propagate as-is.
+func copyRegularFileReflink(srcPath, dstPath string, perms fs.FileMode) error {
+	// clonefile fails with EEXIST if the destination is present. The walk may be
+	// re-running over a partially populated destination, so clear it first.
+	if err := os.Remove(dstPath); err != nil && !errors.Is(err, os.ErrNotExist) {
+		return fmt.Errorf("remove stale clone destination %s: %w", dstPath, err)
+	}
+
+	// CLONE_NOOWNERCOPY drops owner/SUID/SGID/ACL metadata we have no business
+	// propagating into a fork; the explicit Chmod below re-establishes the mode.
+	// CLONE_NOFOLLOW is defensive only: callers route regular files here and
+	// symlinks through os.Symlink, so the source is never a symlink in practice.
+	flags := unix.CLONE_NOFOLLOW | unix.CLONE_NOOWNERCOPY
+	if err := cloneFileFn(srcPath, dstPath, flags); err != nil {
+		if isReflinkUnsupportedError(err) {
+			return fmt.Errorf("%w: clonefile rejected for %s: %v", ErrReflinkUnsupported, srcPath, err)
+		}
+		return fmt.Errorf("clonefile %s -> %s: %w", srcPath, dstPath, err)
+	}
+
+	if err := os.Chmod(dstPath, perms); err != nil {
+		_ = os.Remove(dstPath)
+		return fmt.Errorf("chmod cloned file %s: %w", dstPath, err)
+	}
+	return nil
+}
+
+// isReflinkUnsupportedError returns true when a clonefile failure indicates the
+// clone cannot be served and the caller should fall back to a sparse copy. Only
+// volume/filesystem-capability signals belong here; everything else propagates.
+//
+// EINVAL and ENOTDIR are programming/path errors on clonefile(2) against
+// fixed-constant flags, not capability signals — mapping them to the fallback
+// would silently disable the fast path for every file if a future edit broke the
+// flag set. EEXIST is owned by the os.Remove above (the destination is cleared
+// before the clone); mapping a per-file EEXIST here would wrongly flip the whole
+// directory walk to sparse via the reflinkDead short-circuit. Real errors (EIO,
+// ENOSPC, EACCES) likewise propagate.
+func isReflinkUnsupportedError(err error) bool {
+	switch {
+	case errors.Is(err, unix.ENOTSUP),
+		errors.Is(err, unix.EOPNOTSUPP),
+		errors.Is(err, unix.EXDEV):
+		return true
+	}
+	return false
+}

lib/forkvm/copy_reflink_darwin.go

@@ -0,0 +1,191 @@
+//go:build darwin
+
+package forkvm
+
+import (
+	"bytes"
+	"errors"
+	"net"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"golang.org/x/sys/unix"
+)
+
+// skipUnlessAPFS skips a clone test when the temp volume cannot serve a
+// clonefile (i.e. not APFS). On CI we set HYPEMAN_REQUIRE_APFS_CLONE=1 so the
+// clone path can't silently skip and report a false green on a non-APFS runner;
+// there the unsupported signal becomes a hard failure instead.
+func skipUnlessAPFS(t *testing.T, err error) {
+	t.Helper()
+	if !errors.Is(err, ErrReflinkUnsupported) {
+		return
+	}
+	if os.Getenv("HYPEMAN_REQUIRE_APFS_CLONE") == "1" {
+		t.Fatalf("clonefile reported unsupported but HYPEMAN_REQUIRE_APFS_CLONE=1: %v", err)
+	}
+	t.Skip("clonefile unsupported on this volume; not APFS")
+}
+
+// TestCopyGuestDirectory_CloneCorrectness exercises the real clonefile(2) path
+// over a guest-shaped tree: regular files must be byte-identical, perms must be
+// preserved (the Chmod contract), symlinks copied, and runtime sockets skipped.
+func TestCopyGuestDirectory_CloneCorrectness(t *testing.T) {
+	SetReflinkDisabled(false)
+
+	// Use a short base path so the unix socket below fits within the sockaddr
+	// length limit; macOS t.TempDir() paths under /var/folders are too long.
+	base, err := os.MkdirTemp("/tmp", "forkvm-clone-*")
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = os.RemoveAll(base) })
+
+	src := filepath.Join(base, "src")
+	dst := filepath.Join(base, "dst")
+	require.NoError(t, os.MkdirAll(src, 0755))
+
+	rootfs := bytes.Repeat([]byte("rootfs-"), 1<<20) // ~7 MiB dense payload
+	require.NoError(t, os.WriteFile(filepath.Join(src, "rootfs.ext4"), rootfs, 0644))
+	require.NoError(t, os.WriteFile(filepath.Join(src, "config.ext4"), []byte("config-bytes"), 0600))
+	require.NoError(t, writeSparseFile(filepath.Join(src, "overlay.raw"), 64*1024*1024))
+	require.NoError(t, os.Symlink("rootfs.ext4", filepath.Join(src, "rootfs-link")))
+
+	socketPath := filepath.Join(src, "vsock.sock")
+	listener, err := net.Listen("unix", socketPath)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = listener.Close() })
+
+	// Probe the volume so a non-APFS runner skips (or fails under CI) before we
+	// assert on clone output rather than silently exercising the sparse path.
+	skipUnlessAPFS(t, copyRegularFileReflink(filepath.Join(src, "config.ext4"), filepath.Join(base, "probe"), 0600))
+
+	require.NoError(t, CopyGuestDirectory(src, dst))
+
+	for _, name := range []string{"rootfs.ext4", "config.ext4", "overlay.raw"} {
+		want, err := os.ReadFile(filepath.Join(src, name))
+		require.NoError(t, err)
+		got, err := os.ReadFile(filepath.Join(dst, name))
+		require.NoError(t, err)
+		assert.True(t, bytes.Equal(want, got), "contents of %s must match", name)
+
+		srcInfo, err := os.Stat(filepath.Join(src, name))
+		require.NoError(t, err)
+		dstInfo, err := os.Stat(filepath.Join(dst, name))
+		require.NoError(t, err)
+		assert.Equal(t, srcInfo.Mode().Perm(), dstInfo.Mode().Perm(), "perms of %s must be preserved", name)
+	}
+
+	target, err := os.Readlink(filepath.Join(dst, "rootfs-link"))
+	require.NoError(t, err)
+	assert.Equal(t, "rootfs.ext4", target)
+
+	assert.NoFileExists(t, filepath.Join(dst, "vsock.sock"))
+}
+
+// TestCopyRegularFileReflink_StaleDestination guards the "destination must not
+// exist" divergence from the Linux path: a pre-existing destination is removed
+// before the clone, so the clone still succeeds and matches the source.
+func TestCopyRegularFileReflink_StaleDestination(t *testing.T) {
+	dir := t.TempDir()
+	src := filepath.Join(dir, "rootfs.ext4")
+	dst := filepath.Join(dir, "dst.ext4")
+
+	want := bytes.Repeat([]byte("clone-me"), 4096)
+	require.NoError(t, os.WriteFile(src, want, 0644))
+	require.NoError(t, os.WriteFile(dst, []byte("stale-contents"), 0600))
+
+	err := copyRegularFileReflink(src, dst, 0644)
+	skipUnlessAPFS(t, err)
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(dst)
+	require.NoError(t, err)
+	assert.True(t, bytes.Equal(want, got))
+
+	info, err := os.Stat(dst)
+	require.NoError(t, err)
+	assert.Equal(t, os.FileMode(0644), info.Mode().Perm())
+}
+
+// TestCopyRegularFileReflink_WriteIsolation verifies the clone is copy-on-write:
+// mutating the clone must not change the source. This is the headline correctness
+// property of the fast path — a fork must never corrupt the instance it forked from.
+func TestCopyRegularFileReflink_WriteIsolation(t *testing.T) {
+	dir := t.TempDir()
+	src := filepath.Join(dir, "rootfs.ext4")
+	dst := filepath.Join(dir, "fork.ext4")
+
+	orig := bytes.Repeat([]byte("source-data"), 8192)
+	require.NoError(t, os.WriteFile(src, orig, 0644))
+
+	err := copyRegularFileReflink(src, dst, 0644)
+	skipUnlessAPFS(t, err)
+	require.NoError(t, err)
+
+	// Diverge the clone by overwriting it entirely.
+	require.NoError(t, os.WriteFile(dst, bytes.Repeat([]byte("forked-data!"), 8192), 0644))
+
+	// The source must be byte-for-byte unchanged (copy-on-write).
+	got, err := os.ReadFile(src)
+	require.NoError(t, err)
+	assert.True(t, bytes.Equal(orig, got), "writing to the clone must not modify the source")
+}
+
+// TestCopyGuestDirectory_DarwinReflinkFallback drives the darwin-specific
+// rejection path: when clonefile reports an unsupported error, copyRegularFile
+// must route through isReflinkUnsupportedError to the sparse copy and still
+// produce byte-identical output. CI volumes are always APFS, so this is the
+// only coverage of the clonefile-rejected -> sparse transition on darwin.
+func TestCopyGuestDirectory_DarwinReflinkFallback(t *testing.T) {
+	orig := cloneFileFn
+	cloneFileFn = func(src, dst string, flags int) error { return unix.EXDEV }
+	t.Cleanup(func() { cloneFileFn = orig })
+	SetReflinkDisabled(false)
+
+	src := filepath.Join(t.TempDir(), "src")
+	dst := filepath.Join(t.TempDir(), "dst")
+	require.NoError(t, os.MkdirAll(src, 0755))
+	require.NoError(t, os.WriteFile(filepath.Join(src, "rootfs.ext4"), []byte("rootfs-bytes"), 0644))
+	require.NoError(t, writeSparseFile(filepath.Join(src, "overlay.raw"), 16*1024*1024))
+
+	require.NoError(t, CopyGuestDirectory(src, dst))
+
+	got, err := os.ReadFile(filepath.Join(dst, "rootfs.ext4"))
+	require.NoError(t, err)
+	assert.Equal(t, "rootfs-bytes", string(got))
+
+	want, err := os.ReadFile(filepath.Join(src, "overlay.raw"))
+	require.NoError(t, err)
+	got, err = os.ReadFile(filepath.Join(dst, "overlay.raw"))
+	require.NoError(t, err)
+	assert.True(t, bytes.Equal(want, got), "sparse fallback output must match source")
+}
+
+func TestIsReflinkUnsupportedError(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+		want bool
+	}{
+		{"ENOTSUP", unix.ENOTSUP, true},
+		{"EOPNOTSUPP", unix.EOPNOTSUPP, true},
+		{"EXDEV", unix.EXDEV, true},
+		// EEXIST is owned by the pre-clone os.Remove; EINVAL/ENOTDIR are
+		// programming/path errors on clonefile(2). None are capability signals,
+		// so they propagate rather than trigger fallback.
+		{"EEXIST", unix.EEXIST, false},
+		{"EINVAL", unix.EINVAL, false},
+		{"ENOTDIR", unix.ENOTDIR, false},
+		{"EIO", unix.EIO, false},
+		{"ENOSPC", unix.ENOSPC, false},
+		{"EACCES", unix.EACCES, false},
+		{"nil", nil, false},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			assert.Equal(t, tc.want, isReflinkUnsupportedError(tc.err))
+		})
+	}
+}

lib/forkvm/copy_reflink_darwin_test.go

@@ -1,4 +1,4 @@
-//go:build !linux
+//go:build !linux && !darwin
 
 package forkvm
 
@@ -7,9 +7,8 @@ import (
 	"io/fs"
 )
 
-// copyRegularFileReflink is unavailable on non-Linux platforms. On macOS APFS
-// supports clonefile(2) and could be wired up here, but we currently only
-// rely on the sparse-copy fallback off-Linux.
+// copyRegularFileReflink is unavailable on platforms without a copy-on-write
+// clone primitive; callers fall back to the sparse copy.
 func copyRegularFileReflink(srcPath, dstPath string, perms fs.FileMode) error {
 	_ = dstPath
 	_ = perms