Module copy 

Sparse-aware fast copy with reflink fallback.

Two-tier strategy that preserves sparseness on every supported platform:

1. Reflink (zero-copy COW). Tries clonefile(2) on macOS and ioctl(FICLONE) on Linux via reflink-copy. Succeeds instantly on APFS, btrfs, XFS (with reflink=1), and bcachefs. Returns EOPNOTSUPP (or similar) on ext4 and other non-COW filesystems.

2. Sparse-aware copy. POSIX SEEK_DATA / SEEK_HOLE walk of the source’s allocation map, with copy_file_range(2) on Linux for in-kernel zero-copy of data extents. The destination is ftruncated to the source size up front so unallocated regions stay holes.

Never falls back to a naive byte-for-byte copy — that would densify a 4 GiB sparse file with a few MB of data into 4 GiB on disk, which is the exact failure mode this module exists to prevent.

See planning/microsandbox/implementation/snapshots.md for the full design and tradeoffs.

Enums

FastCopyStrategy

Strategy that successfully created a destination in fast_copy_with_strategy.

Functions

fast_copy

Copy src to dst, preserving sparseness. Returns the apparent size of the destination in bytes.

fast_copy_with_strategy

Copy using the fastest safe strategy and report which strategy resolved.

reflink

Require a filesystem copy-on-write clone with no fallback.

sparse_copy

Sparse-aware copy via SEEK_DATA/SEEK_HOLE and per-extent copy.