block/file cloning support for macOS / Linux (#786)

- Add block cloning (copy-on-write) support for Linux and macOS to complement the existing Windows (ReFS) implementation
  - **Linux**: `TryCloneFile` via `FICLONE` ioctl, `CloneQueryInterface` with range cloning via `FICLONERANGE` (Btrfs/XFS)
  - **macOS**: `TryCloneFile` via `clonefile()` syscall (APFS), `SupportsBlockRefCounting` via `VOL_CAP_INT_CLONE`. `CloneQueryInterface` is not implemented as macOS lacks a sub-file range clone API
- Promote `ScopedFd` to file scope for broader use in filesystem code
- Add test scripts for block cloning validation on Linux (Btrfs via loopback) and macOS (APFS)
- Also added test script for testing on Windows (ReFS)

1 files changed, 43 insertions, 0 deletions

diff --git a/scripts/test_scripts/block-clone-test-mac.sh b/scripts/test_scripts/block-clone-test-mac.sh
new file mode 100755
index 000000000..a3d3ca4d3
--- /dev/null
+++ b/scripts/test_scripts/block-clone-test-mac.sh
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Test block-clone functionality on macOS (APFS).
+#
+# APFS is the default filesystem on modern Macs and natively supports
+# clonefile(), so no special setup is needed — just run the tests.
+#
+# Usage:
+#   ./scripts/test_scripts/block-clone-test-mac.sh [path-to-zencore-test]
+#
+# If no path is given, defaults to build/macosx/<arch>/debug/zencore-test
+# relative to the repository root.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+ARCH="$(uname -m)"
+TEST_BINARY="${1:-$REPO_ROOT/build/macosx/$ARCH/debug/zencore-test}"
+
+if [ ! -x "$TEST_BINARY" ]; then
+    echo "error: test binary not found or not executable: $TEST_BINARY" >&2
+    echo "hint:  build with 'xmake config -m debug && xmake build zencore-test'" >&2
+    exit 1
+fi
+
+# Verify we're on APFS
+BINARY_DIR="$(dirname "$TEST_BINARY")"
+FS_TYPE="$(diskutil info "$(df "$BINARY_DIR" | tail -1 | awk '{print $1}')" 2>/dev/null | grep "Type (Bundle)" | awk '{print $NF}' || true)"
+
+if [ "$FS_TYPE" != "apfs" ]; then
+    echo "warning: filesystem does not appear to be APFS (got: ${FS_TYPE:-unknown}), clone tests may skip" >&2
+fi
+
+TEST_CASES="TryCloneFile,CopyFile.Clone,SupportsBlockRefCounting,CloneQueryInterface"
+
+echo "Running block-clone tests ..."
+echo "---"
+"$TEST_BINARY" \
+    --test-suite="core.filesystem" \
+    --test-case="$TEST_CASES"
+echo "---"
+echo "All block-clone tests passed."