feat: sparse writes with range_upload, zero-download write path

.github/workflows/ci.yml

@@ -121,6 +121,10 @@ jobs:
         timeout-minutes: 10
         run: cargo test --release --test fsx -- --test-threads=1 --nocapture
 
+      - name: fsx paranoid (CAS round-trip per mutation)
+        timeout-minutes: 15
+        run: cargo test --release --test fsx_paranoid -- --test-threads=1 --nocapture
+
   xfstests:
     name: xfstests (filesystem exerciser)
     runs-on:

Cargo.toml

@@ -10,10 +10,10 @@ categories = ["filesystem", "command-line-utilities"]
 
 [dependencies]
 # xet-core crates
-xet-client = { git = "https://github.com/huggingface/xet-core.git", branch = "main" }
-xet-core-structures = { git = "https://github.com/huggingface/xet-core.git", branch = "main" }
-xet-data = { git = "https://github.com/huggingface/xet-core.git", branch = "main" }
-xet-runtime = { git = "https://github.com/huggingface/xet-core.git", branch = "main" }
+xet-client = { git = "https://github.com/huggingface/xet-core.git", rev = "40f9530753e48f9517b5ad09e2339df7059d8de4" }
+xet-core-structures = { git = "https://github.com/huggingface/xet-core.git", rev = "40f9530753e48f9517b5ad09e2339df7059d8de4" }
+xet-data = { git = "https://github.com/huggingface/xet-core.git", rev = "40f9530753e48f9517b5ad09e2339df7059d8de4" }
+xet-runtime = { git = "https://github.com/huggingface/xet-core.git", rev = "40f9530753e48f9517b5ad09e2339df7059d8de4" }
 
 # External crates
 async-trait = "0.1"

src/cached_xet_client.rs

@@ -77,7 +77,7 @@ impl CachedXetClient {
     }
 }
 
-/// Derive a range-scoped `QueryReconstructionResponse` from a cached full-file response.
+/// Derive a range-scoped `QueryReconstructionResponseV2` from a cached full-file response.
 ///
 /// The full-file response lists all terms in file order with their unpacked byte lengths.
 /// We walk the terms, track cumulative byte offsets, and keep only terms that overlap

src/nfs.rs

@@ -816,6 +816,11 @@ fn errno_to_nfs(e: i32) -> nfsstat3 {
         libc::ENOTEMPTY => nfsstat3::NFS3ERR_NOTEMPTY,
         libc::EBADF => nfsstat3::NFS3ERR_STALE,
         libc::ENOSPC => nfsstat3::NFS3ERR_NOSPC,
+        // EAGAIN signals a transient condition the caller should retry
+        // (e.g., open_advanced_write exhausted its drift-retry budget).
+        // NFS3ERR_JUKEBOX tells the client to back off and retry; mapping
+        // to EIO would surface as a hard failure for a recoverable case.
+        libc::EAGAIN => nfsstat3::NFS3ERR_JUKEBOX,
         _ => nfsstat3::NFS3ERR_IO,
     }
 }

src/setup.rs

@@ -104,6 +104,15 @@ pub struct MountOptions {
     #[arg(long, default_value_t = false)]
     pub advanced_writes: bool,
 
+    /// EXPERIMENTAL (beta). Skip the full CAS download when opening for write
+    /// and only upload modified byte ranges via `range_upload`. Much faster
+    /// for large files with small edits, but exercises more lifecycle paths
+    /// (handle pool reuse, drift retries, multi-handle reads/writes) than the
+    /// download-then-upload mode. Off by default — opt in if you understand
+    /// the trade-off. Implies --advanced-writes.
+    #[arg(long, default_value_t = false)]
+    pub sparse_writes: bool,
+
     /// Interval in seconds for polling remote changes (0 to disable).
     #[arg(long, default_value_t = 30)]
     pub poll_interval_secs: u64,
@@ -230,6 +239,7 @@ pub struct MountSetup {
     pub mount_point: PathBuf,
     pub read_only: bool,
     pub advanced_writes: bool,
+    pub sparse_writes: bool,
     pub direct_io: bool,
     pub metadata_ttl: std::time::Duration,
     pub max_threads: usize,
@@ -428,6 +438,18 @@ pub fn build_with_runtime(
     let xet_sessions = XetSessions::new(xet_ctx, download_session, upload_config, cached_client, xorb_cache);
 
     let advanced_writes = options.advanced_writes || options.overlay || (is_nfs && !read_only);
+    // Sparse writes are an experimental optimization on top of advanced writes.
+    // They imply advanced_writes (the advanced_writes path is where the sparse
+    // staging lives), but advanced_writes does NOT imply sparse_writes — the
+    // safe default is to download-then-write, which is well-tested and avoids
+    // the lifecycle edge cases that sparse staging exposes.
+    let sparse_writes = options.sparse_writes && advanced_writes;
+    if options.sparse_writes && !advanced_writes {
+        warn!("--sparse-writes ignored: requires --advanced-writes (or NFS read-write, or --overlay)");
+    }
+    if sparse_writes {
+        warn!("--sparse-writes is EXPERIMENTAL. Disable with `--sparse-writes=false` if you see issues.");
+    }
 
     // Overlay: open a pre-mount fd to the mount point directory. The fd is
     // held by OverlayBacking so overlay-local filesystem ops can stay rooted
@@ -526,6 +548,7 @@ pub fn build_with_runtime(
         VfsConfig {
             read_only,
             advanced_writes,
+            sparse_writes,
             uid,
             gid,
             poll_interval_secs: options.poll_interval_secs,
@@ -552,6 +575,7 @@ pub fn build_with_runtime(
         mount_point,
         read_only,
         advanced_writes,
+        sparse_writes,
         direct_io: options.direct_io,
         metadata_ttl,
         max_threads: options.max_threads,