mux: pipelined PES highway — read+decrypt → demux → parse on 3 threads

Introduces the freemkv mux throughput highway: a three-stage thread
pipeline that replaces the inline single-thread read path for any
file-backed source (ISO and m2ts file URLs both route through it).

  Thread A: read + decrypt  (PrefetchedSectorSource / BytePrefetcher)
  Thread B: M2TS demux      (DemuxThread)
  Thread C: codec parse     (PipelinedPesStream, on caller thread)

Each handoff uses a bounded crossbeam channel with a recycled buffer
pool — no allocations or memcpys in the steady-state hot loop.

Component map:

* io/byte_prefetcher.rs (new) — std::io::Read producer thread with
  recycled Vec<u8> pool. Pairs with PrefetchedSectorSource (sector
  side) so demux_thread::spawn_zero_copy can wire either upstream.
* sector/prefetched.rs — recycled buffer pool added; into_channels()
  peels off the rx/recycle_tx/shell triple for zero-copy demux.
* mux/demux_thread.rs (new) — owns the TsDemuxer/PsDemuxer, runs
  feed() on its thread, ships Vec<PesPacket> batches.
* mux/pipelined_stream.rs (new) — the read-side Stream impl. Pulls
  packets from the demux thread and runs codec parse on the caller.
* mux/resolve.rs — build_iso_pipeline (public) / build_m2ts_pipeline
  (private) assemble the three stages; iso:// and m2ts:// both
  return PipelinedPesStream.
* mux/m2ts.rs — collapsed to a write-only sink (Mode::Read deleted;
  the read direction lives on the highway now).
* mux/codec/h264.rs — find_start_code uses memchr SIMD memmem::find.
* mux/codec/hevc.rs — tightened frame_data initial capacity.
* mux/ts.rs — boundary-packet handling avoids the per-batch 16 MiB
  remainder copy; PesAssembler starts at 16 KiB to dodge the 64-page
  first-touch fault tax that the previous 256 KiB pre-alloc paid on
  every PES boundary.
* mux/disc.rs — gains DiscStream::new_pipeline + read_pipeline as
  the legacy autorip ingress (drive + multipass paths still need
  on_event / skip_errors before they migrate to the highway).
* io/file_sector_source/* — per-OS prefetch() syscall hook
  (Linux readahead, macOS F_RDADVISE, Windows/other no-op).
* decrypt.rs — FREEMKV_DECRYPT_THREADS renamed to FREEMKV_THREADS;
  pool sized to all cores by default.

Measured on rip1 testbed (Civil War UHD, 62 GiB ISO → null://):

  60 → 322 MB/s warm cache (old new_pipeline path)
  60 → 660 MB/s warm cache (highway path, this commit)
  60 → 126 MB/s sustained disk-bound

The IsoSectorReader baseline reader was deleted in favour of
FileSectorSource so the freemkv CLI and autorip exercise the same
read path.

src/io/bounded.rs

@@ -54,15 +54,7 @@ use std::sync::mpsc::{RecvTimeoutError, sync_channel};
 use std::thread;
 use std::time::{Duration, Instant};
 
-use crate::halt::Halt;
-
-/// Granularity of the halt poll. The receive loop wakes every
-/// [`POLL_INTERVAL`] to (a) check the [`Halt`] token, then (b) check
-/// the overall deadline, then go back to waiting. 250 ms is a
-/// pragmatic balance: short enough that human-driven `/api/stop` feels
-/// responsive (< 0.5 s p99), long enough that the polling overhead is
-/// negligible against multi-second syscalls.
-const POLL_INTERVAL: Duration = Duration::from_millis(250);
+use crate::halt::{Halt, POLL_INTERVAL};
 
 /// Failure outcome from a bounded syscall wrapper.
 #[derive(Debug)]

src/io/byte_prefetcher.rs

@@ -0,0 +1,146 @@
+//! `BytePrefetcher` — `std::io::Read` analogue of
+//! [`crate::sector::PrefetchedSectorSource`].
+//!
+//! Spawns a producer thread that fills a bounded pool of `Vec<u8>`
+//! chunks from the underlying reader and ships them through a
+//! channel; the consumer pulls filled chunks, uses them, and sends
+//! the empty `Vec<u8>` back through a recycle channel so the
+//! producer can re-fill in place. Result: zero allocations and zero
+//! cross-thread frees in the steady-state hot loop.
+//!
+//! This is the byte-stream half of the freemkv mux highway —
+//! `BytePrefetcher` feeds [`crate::mux::demux_thread::DemuxThread`]
+//! for `m2ts://`, `network://`, `stdio://`, and any other stream
+//! whose source is an `io::Read` rather than a `SectorSource`.
+
+use crate::halt::Halt;
+use crossbeam_channel::{Receiver, Sender, bounded};
+use std::io::Read;
+use std::thread::JoinHandle;
+
+/// Items flowing through the forward channel.
+pub type Batch = std::io::Result<Vec<u8>>;
+
+/// Forward channel depth — how many filled buffers the producer can
+/// stay ahead by. Two is enough to absorb a moderate consumer stall
+/// without piling up bytes.
+const FORWARD_DEPTH: usize = 2;
+
+/// Recycle channel depth = forward + 1 so the producer always has at
+/// least one buffer to fill while the consumer holds one.
+const RECYCLE_DEPTH: usize = FORWARD_DEPTH + 1;
+
+/// Default chunk size — 16 MiB matches the ISO-mux sector batch and
+/// is large enough that per-chunk overhead is amortised; small
+/// enough that the in-flight memory footprint stays bounded.
+pub const DEFAULT_CHUNK_BYTES: usize = 16 * 1024 * 1024;
+
+/// Returned from [`BytePrefetcher::into_channels`]. Owns the
+/// producer-thread join handle so dropping the shell joins the
+/// producer.
+pub struct PrefetchShell {
+    producer: Option<JoinHandle<()>>,
+}
+
+impl Drop for PrefetchShell {
+    fn drop(&mut self) {
+        if let Some(h) = self.producer.take() {
+            let _ = h.join();
+        }
+    }
+}
+
+/// Spawned byte prefetcher. Drop joins the producer thread.
+pub struct BytePrefetcher {
+    rx: Receiver<Batch>,
+    recycle_tx: Sender<Vec<u8>>,
+    producer: Option<JoinHandle<()>>,
+}
+
+impl BytePrefetcher {
+    /// Spawn the producer thread. `reader` must be `Send` because it
+    /// moves into the thread. `chunk_bytes` is the size of each
+    /// recycled buffer; pick the natural batch size of the
+    /// downstream demuxer (16 MiB for the BD-TS mux pipeline).
+    pub fn new<R: Read + Send + 'static>(
+        mut reader: R,
+        chunk_bytes: usize,
+        halt: Option<Halt>,
+    ) -> Self {
+        let (tx, rx) = bounded::<Batch>(FORWARD_DEPTH);
+        let (recycle_tx, recycle_rx) = bounded::<Vec<u8>>(RECYCLE_DEPTH);
+
+        // Seed the recycle pool. Without these the first
+        // `recycle_rx.recv()` would block forever (no consumer has
+        // returned a buffer yet).
+        for _ in 0..RECYCLE_DEPTH {
+            let _ = recycle_tx.send(vec![0u8; chunk_bytes]);
+        }
+
+        let producer = std::thread::Builder::new()
+            .name("freemkv-byte-prefetch".into())
+            .spawn(move || {
+                loop {
+                    if halt.as_ref().map(|h| h.is_cancelled()).unwrap_or(false) {
+                        return;
+                    }
+                    let mut buf = match recycle_rx.recv() {
+                        Ok(b) => b,
+                        Err(_) => return, // consumer dropped both channels
+                    };
+                    // Re-expose the full extent (previous iteration
+                    // may have truncated after a short read).
+                    if buf.len() < chunk_bytes {
+                        buf.resize(chunk_bytes, 0);
+                    } else {
+                        // SAFETY: capacity is at least chunk_bytes
+                        // after construction.
+                        unsafe { buf.set_len(chunk_bytes) };
+                    }
+                    // Read up to one full chunk. Short reads are
+                    // valid and common — pipe `truncate` so the
+                    // consumer sees only the bytes that arrived.
+                    let n = match reader.read(&mut buf[..]) {
+                        Ok(0) => return, // EOF — drop tx, consumer sees RecvError
+                        Ok(n) => n,
+                        Err(e) => {
+                            let _ = tx.send(Err(e));
+                            return;
+                        }
+                    };
+                    buf.truncate(n);
+                    if tx.send(Ok(buf)).is_err() {
+                        return; // consumer dropped
+                    }
+                }
+            })
+            .expect("freemkv-byte-prefetch thread spawn failed");
+
+        Self {
+            rx,
+            recycle_tx,
+            producer: Some(producer),
+        }
+    }
+
+    /// Peel off the channels for zero-copy pipeline consumption. The
+    /// caller (typically [`crate::mux::demux_thread::DemuxThread`])
+    /// drains `rx`, runs the demuxer in place on each filled buffer,
+    /// and recycles back through `recycle_tx`.
+    pub fn into_channels(self) -> (Receiver<Batch>, Sender<Vec<u8>>, PrefetchShell) {
+        let mut me = self;
+        let producer = me.producer.take();
+        let rx = me.rx.clone();
+        let recycle = me.recycle_tx.clone();
+        std::mem::forget(me);
+        (rx, recycle, PrefetchShell { producer })
+    }
+}
+
+impl Drop for BytePrefetcher {
+    fn drop(&mut self) {
+        if let Some(h) = self.producer.take() {
+            let _ = h.join();
+        }
+    }
+}

src/io/file_sector_source/linux.rs

@@ -44,3 +44,22 @@ pub(super) fn drop_window(file: &File, start: u64, len: u64) {
         );
     }
 }
+
+/// Async-prefetch `len` bytes at `offset` into the page cache. The
+/// kernel `readahead(2)` syscall queues the I/O and returns
+/// immediately — it does NOT wait for completion. Called right after
+/// each consumed read so the next batch's I/O overlaps with the
+/// caller's processing of the current batch (decrypt + demux + mux).
+///
+/// Without this hint, with a synchronous demux consumer running at
+/// ~50 MB/s and a single-spindle disk capable of ~150 MB/s, the disk
+/// sits idle ~70% of each iteration because kernel readahead alone
+/// (capped at `/sys/block/<dev>/queue/read_ahead_kb`, default 128 KB)
+/// can only pre-stage a tiny slice of the next batch. An explicit
+/// `readahead()` of the same size as the current batch tells the
+/// kernel to queue the full next-batch read now.
+pub(super) fn prefetch(file: &File, offset: u64, len: u64) {
+    unsafe {
+        libc::readahead(file.as_raw_fd(), offset as i64, len as usize);
+    }
+}

src/io/file_sector_source/macos.rs

@@ -44,3 +44,19 @@ pub(super) fn hint_sequential(file: &File, len_bytes: u64) {
 /// less prone to the pin-everything pathology that triggers the
 /// regression on Linux NFS clients.
 pub(super) fn drop_window(_file: &File, _start: u64, _len: u64) {}
+
+/// Async-prefetch the byte range `[offset, offset+len)`. macOS uses
+/// the same `fcntl(F_RDADVISE, &radvisory)` primitive as the open-
+/// time sequential hint, just targeted at a moving window instead of
+/// the whole file. The kernel queues I/O for the requested range and
+/// returns immediately.
+pub(super) fn prefetch(file: &File, offset: u64, len: u64) {
+    let bytes = (len as i64).min(RDADVISE_MAX_BYTES);
+    let mut ra = RadAdvisory {
+        ra_offset: offset as libc::off_t,
+        ra_count: bytes as libc::c_int,
+    };
+    unsafe {
+        libc::fcntl(file.as_raw_fd(), F_RDADVISE, &mut ra);
+    }
+}

src/io/file_sector_source/mod.rs

@@ -1,39 +1,43 @@
 //! [`FileSectorSource`] — read 2048-byte sectors from an ISO file on
-//! disk, with an internal 32 MiB read-ahead buffer.
+//! disk via direct `seek + read_exact` (`pread`-equivalent) calls,
+//! letting the kernel's own readahead policy manage prefetch.
 //!
-//! ## Why the buffer
+//! ## Why no app-level buffer
 //!
-//! On NFS-mounted ISOs, an unbuffered `pread(2048)` per sector pays an
-//! NFS round-trip for every sector. With `rsize=1 MiB` and a 100-150 ms
-//! NFS RTT, that's three orders of magnitude more round trips than
-//! necessary — the muxer goes read-bound on every read, even though
-//! the local NFS client could deliver MB/s on bigger requests.
+//! Pre-0.21.3 this source held a 32 MiB (later 4 MiB) read-ahead
+//! buffer to amortise per-sector NFS round-trips. Empirically that
+//! buffer hurt: 32 MiB refills bursted the NFS TCP connection hard
+//! enough to starve the concurrent writer, and even a 4 MiB window
+//! gave the kernel less freedom to pipeline reads with writes. Direct
+//! pread per call lets Linux's readahead widen as it detects the
+//! sequential pattern, and naturally interleaves with writeback.
 //!
-//! Internally this source keeps a [`READAHEAD_BUF_BYTES`] (32 MiB)
-//! window pre-read from the file. `read_sectors(lba, count)` slices
-//! into the window if `[lba, lba+count)` is contained in it; otherwise
-//! the window is refilled (full-size aligned to the requested LBA's
-//! buffer position).
+//! ## DONTNEED on the consumed window
 //!
-//! ## Access pattern assumption
+//! Without page-cache eviction an 85 GB streaming ISO read pins the
+//! entire file in memory, starves the concurrent writer, and collapses
+//! mux throughput (observed: 2.7 MB/s mux on 0.21.5 vs. 70 MB/s
+//! isolated NFS reads). Every [`READ_DROP_CHUNK_BYTES`] of consumed
+//! bytes we call `posix_fadvise(DONTNEED)` over that window, mirroring
+//! the write-side [`crate::io::writeback::WritebackPipeline`] policy.
 //!
-//! The buffer is sized for **forward-sequential** reads (sweep, mux).
-//! Reverse-mode patch is range-local, so a refill per range works out
-//! fine (the buffer covers the whole range for typical bad-range
-//! sizes). Random-access reads thrash the buffer — at which point the
-//! 32 MiB pre-read is wasted work. We accept that: the use case is
-//! mux + sweep, both forward-sequential.
-//!
-//! Backward seeks rebuffer from the new LBA; partial reads at EOF
-//! return only the bytes that exist (the underlying file is shorter
-//! than a full buffer slot).
-//!
-//! ## Platform open hints
+//! ## Platform open hint
 //!
 //! On `open()` each platform issues its "sequential access expected"
-//! hint to the kernel so OS-level readahead widens. The hint lives in
-//! a per-OS sibling module ([`linux::hint_sequential`] et al.) — no
-//! inline `#[cfg]` in this file.
+//! hint so OS-level readahead widens. The hint and the DONTNEED call
+//! live in per-OS sibling modules ([`linux::hint_sequential`] et al.)
+//! — no inline `#[cfg]` in this file.
+//!
+//! ## Read-ahead prefetch
+//!
+//! After every consumed read we issue an OS-level prefetch hint for
+//! the next equivalent-sized window (`platform::prefetch`). The
+//! kernel queues that I/O asynchronously and returns immediately, so
+//! the next batch's read overlaps with the caller's processing of
+//! the current batch (decrypt + demux + mux). Without this the disk
+//! sits idle ~70% of each iteration because kernel SEQUENTIAL
+//! readahead alone (capped at `read_ahead_kb`, default 128 KB) is
+//! far smaller than our 16 MiB app-level batch.
 
 #[cfg(target_os = "linux")]
 mod linux;
@@ -60,66 +64,48 @@ use std::path::Path;
 use crate::error::{Error, Result};
 use crate::sector::SectorSource;
 
-/// Internal read-ahead buffer size. 32 MiB amortises one NFS round
-/// trip across ~16 k sectors — three orders of magnitude fewer trips
-/// than per-sector pread, and large enough to coast through a typical
-/// NFS server commit blip.
-///
-/// 0.21.2: shrunk from 32 MiB → 4 MiB. On NFS-backed ISOs with
-/// concurrent NFS writes (the mux phase), a 32 MiB refill bursts the
-/// TCP connection hard enough to starve the writer thread, observed
-/// empirically as a ~3× drop in sustained mux throughput on the
-/// rip1/unraid-1 setup. 4 MiB matches `rsize=1 MiB` × 4 round-trips
-/// and interleaves cleanly with writes.
-///
-/// Tweakable. Named const, not a magic number.
-pub const READAHEAD_BUF_BYTES: usize = 4 * 1024 * 1024;
-
 const SECTOR_SIZE: usize = 2048;
-/// Sectors per refill: [`READAHEAD_BUF_BYTES`] / [`SECTOR_SIZE`]. The
-/// buffer always tries to hold this many, except at the tail of the
-/// file where less data exists.
-const BUF_SECTORS: u32 = (READAHEAD_BUF_BYTES / SECTOR_SIZE) as u32;
 
-/// SectorSource backed by a file (ISO image) with an internal
-/// `READAHEAD_BUF_BYTES`-sized read-ahead window.
-///
-/// `read_sectors` is satisfied from the buffer when possible; otherwise
-/// a full-buffer refill is issued at the requested LBA's position and
-/// the call is re-tried against the freshly populated window.
 /// Bytes-read threshold per `posix_fadvise(DONTNEED)` drop on the
 /// read side. Mirrors `WRITEBACK_CHUNK_BYTES` so the read-side page
 /// cache stays bounded the same way the write side does.
 ///
-/// 0.21.6: re-added after empirical discovery that Phase 1 had silently
-/// dropped this from the pre-Phase-1 (0.20.7) hot path. Without it,
-/// 85 GB of streaming ISO reads pin the entire file in the kernel page
-/// cache, starving the MKV writeback and collapsing mux throughput
-/// (observed: 2.7 MB/s mux on 0.21.5 vs. 70 MB/s isolated NFS reads).
-const READ_DROP_CHUNK_BYTES: u64 = 32 * 1024 * 1024;
+/// 32 MiB is the empirically tuned value on the rip1 test bed (single
+/// 7200rpm HDD via SATA): smaller windows (8 / 16 MiB) shorten the
+/// kernel-readahead overlap and slow the producer; larger windows
+/// (64 / 128 MiB) let the page cache pin enough of the ISO to
+/// pressure concurrent writes. Override via `FREEMKV_READ_DROP_CHUNK_MIB`.
+const READ_DROP_CHUNK_BYTES_DEFAULT: u64 = 32 * 1024 * 1024;
 
+fn read_drop_chunk_bytes() -> u64 {
+    std::env::var("FREEMKV_READ_DROP_CHUNK_MIB")
+        .ok()
+        .and_then(|v| v.parse::<u64>().ok())
+        .filter(|&n| n > 0)
+        .map(|n| n * 1024 * 1024)
+        .unwrap_or(READ_DROP_CHUNK_BYTES_DEFAULT)
+}
+
+/// SectorSource backed by a file (ISO image). Every `read_sectors`
+/// call is a direct `seek + read_exact` against the underlying file
+/// — kernel readahead handles prefetch, and every
+/// [`READ_DROP_CHUNK_BYTES_DEFAULT`] bytes of consumed data the
+/// platform's `DONTNEED` hook drops the consumed window from the
+/// page cache to bound memory pressure.
 pub struct FileSectorSource {
     file: File,
     /// Total file size in sectors. Constant after construction;
     /// surfaced via [`SectorSource::capacity_sectors`].
     capacity: u32,
-    /// 0.21.3+: the app-level buffer is no longer touched on the hot
-    /// path (every `read_sectors` is a direct pread). The fields are
-    /// retained so a future per-source-type policy (e.g. a local-disk
-    /// source where batched reads ARE beneficial) can re-enable
-    /// buffering cleanly without re-plumbing the struct.
-    #[allow(dead_code)]
-    buf: Box<[u8]>,
-    #[allow(dead_code)]
-    buf_start_lba: u32,
-    buf_len_sectors: u32,
-    /// 0.21.6: bytes read since the last DONTNEED drop. Drives the
-    /// per-`READ_DROP_CHUNK_BYTES` page-cache eviction in read_sectors.
+    /// Bytes read since the last DONTNEED drop. Drives the per-
+    /// [`read_drop_chunk_bytes`] page-cache eviction in read_sectors.
     bytes_read_since_drop: u64,
-    /// 0.21.6: file offset at which the current drop window starts.
-    /// The next DONTNEED drops from `drop_window_start` for
+    /// File offset at which the current drop window starts. The next
+    /// DONTNEED drops from `drop_window_start` for
     /// `bytes_read_since_drop` bytes.
     drop_window_start: u64,
+    /// Cached drop chunk size (resolved from env once at open).
+    drop_chunk_bytes: u64,
 }
 
 impl FileSectorSource {
@@ -148,59 +134,14 @@ impl FileSectorSource {
         // FS doesn't honour it).
         platform::hint_sequential(&file, len);
 
-        // Pre-allocate the buffer once. `vec![0u8; N].into_boxed_slice()`
-        // is the canonical way to fix the allocation size up-front;
-        // `Vec::with_capacity` would leave `len == 0` and force callers
-        // to do unsafe length manipulation to write into it.
-        let buf = vec![0u8; READAHEAD_BUF_BYTES].into_boxed_slice();
-
         Ok(Self {
             file,
             capacity,
-            buf,
-            buf_start_lba: 0,
-            buf_len_sectors: 0,
             bytes_read_since_drop: 0,
             drop_window_start: 0,
+            drop_chunk_bytes: read_drop_chunk_bytes(),
         })
     }
-
-    /// True if `[lba, lba + count)` is wholly inside the current
-    /// buffer window. `count == 0` is vacuously true.
-    #[allow(dead_code)]
-    fn buffer_covers(&self, lba: u32, count: u32) -> bool {
-        if self.buf_len_sectors == 0 {
-            return false;
-        }
-        let end = match lba.checked_add(count) {
-            Some(e) => e,
-            None => return false,
-        };
-        let buf_end = self.buf_start_lba.saturating_add(self.buf_len_sectors);
-        lba >= self.buf_start_lba && end <= buf_end
-    }
-
-    /// Refill the buffer so it starts at `lba`. Read as many sectors
-    /// as we have buffer space AND file capacity for. Caller has
-    /// already checked `lba < capacity`.
-    #[allow(dead_code)]
-    fn refill(&mut self, lba: u32) -> Result<()> {
-        debug_assert!(lba < self.capacity, "refill past capacity");
-        // Don't read past EOF — clamp the request to remaining
-        // sectors. partial-buffer-at-EOF behaviour is intentional.
-        let want = BUF_SECTORS.min(self.capacity - lba);
-        let want_bytes = want as usize * SECTOR_SIZE;
-        let offset = lba as u64 * SECTOR_SIZE as u64;
-        self.file
-            .seek(SeekFrom::Start(offset))
-            .map_err(|e| Error::IoError { source: e })?;
-        self.file
-            .read_exact(&mut self.buf[..want_bytes])
-            .map_err(|e| Error::IoError { source: e })?;
-        self.buf_start_lba = lba;
-        self.buf_len_sectors = want;
-        Ok(())
-    }
 }
 
 impl SectorSource for FileSectorSource {
@@ -226,20 +167,6 @@ impl SectorSource for FileSectorSource {
         if count == 0 {
             return Ok(0);
         }
-        // 0.21.3: bypass the application-level buffer entirely.
-        //
-        // Empirically the 32 MiB readahead window (0.21.0–0.21.1) and the
-        // 4 MiB shrink (0.21.2) both regressed mux throughput vs the
-        // pre-Phase-1 0.20.7 baseline on NFS bidirectional workloads
-        // (sweep ~25 MB/s OK; mux dropped from 18 → 7-8 → 5-6 MB/s).
-        // Direct pread per call lets the kernel's own readahead policy
-        // run, which interleaves naturally with concurrent NFS writes on
-        // the same TCP connection.
-        //
-        // Buffer fields are retained (currently unused on this path) so
-        // any future per-source policy can be reintroduced without
-        // re-plumbing structure. `refill` / `buffer_covers` are kept too
-        // (still exercised by the tests so the API contract is locked).
         let offset = lba as u64 * SECTOR_SIZE as u64;
         self.file
             .seek(SeekFrom::Start(offset))
@@ -247,15 +174,21 @@ impl SectorSource for FileSectorSource {
         self.file
             .read_exact(&mut out[..bytes])
             .map_err(|e| Error::IoError { source: e })?;
-        self.buf_len_sectors = 0;
 
-        // 0.21.6: periodic page-cache eviction on the read side. Without
+        // Queue the next batch's read with the kernel before the
+        // caller starts processing what we just returned. readahead()
+        // is non-blocking — it queues I/O and returns, so the kernel
+        // pulls those pages into cache while the consumer (decrypt +
+        // demux + mux) runs. Next read_sectors call hits a warm cache.
+        platform::prefetch(&self.file, offset + bytes as u64, bytes as u64);
+
+        // Periodic page-cache eviction on the read side. Without
         // this, an 85 GB streaming ISO read pins the entire file in
-        // kernel page cache, which starves concurrent NFS writes (the
-        // MKV output) and collapses mux throughput. Mirrors the
-        // write-side WritebackPipeline's DONTNEED policy.
+        // the kernel page cache, which starves concurrent writes and
+        // collapses mux throughput. Mirrors the write-side
+        // WritebackPipeline's DONTNEED policy.
         self.bytes_read_since_drop += bytes as u64;
-        if self.bytes_read_since_drop >= READ_DROP_CHUNK_BYTES {
+        if self.bytes_read_since_drop >= self.drop_chunk_bytes {
             let drop_start = self.drop_window_start;
             let drop_len = self.bytes_read_since_drop;
             platform::drop_window(&self.file, drop_start, drop_len);
@@ -287,11 +220,15 @@ mod tests {
         f.flush().unwrap();
     }
 
+    /// Sectors used by spanning-boundary tests. Pick something that
+    /// exercises multi-megabyte reads without making test ISOs huge.
+    /// 8192 sectors = 16 MiB — large enough to cross any readahead
+    /// chunk size we set the kernel hint to.
+    const TEST_SPAN_SECTORS: u32 = 8192;
+
     #[test]
     fn sequential_reads_match_file() {
-        // Two full buffer windows + a tail = exercise refill across
-        // boundaries.
-        let total = BUF_SECTORS * 2 + 17;
+        let total = TEST_SPAN_SECTORS * 2 + 17;
         let dir = tempdir().unwrap();
         let path = dir.path().join("seq.iso");
         make_iso(&path, total);
@@ -311,28 +248,15 @@ mod tests {
     }
 
     #[test]
-    fn multi_sector_read_spanning_buffer_boundary() {
-        // A read that lands exactly on the last sector of the buffer
-        // plus the first sector of the next refill must rebuffer
-        // mid-read. Bypass path triggers when count > BUF_SECTORS; we
-        // want the in-window path, so count stays small but
-        // straddles the boundary.
-        let total = BUF_SECTORS * 2;
+    fn multi_sector_read_across_chunk_boundary() {
+        let total = TEST_SPAN_SECTORS * 2;
         let dir = tempdir().unwrap();
         let path = dir.path().join("span.iso");
         make_iso(&path, total);
 
         let mut src = FileSectorSource::open(&path).unwrap();
 
-        // Prime: read sector 0. (0.21.3+: app-level buffer is bypassed,
-        // so we don't assert internal buf state here — just exercise
-        // the read path.)
-        let mut got = vec![0u8; SECTOR_SIZE];
-        src.read_sectors(0, 1, &mut got, false).unwrap();
-
-        // Now read 4 sectors crossing what used to be the buffer
-        // boundary. Still a valid SectorSource-contract test.
-        let span_lba = BUF_SECTORS - 2;
+        let span_lba = TEST_SPAN_SECTORS - 2;
         let mut buf4 = vec![0u8; SECTOR_SIZE * 4];
         src.read_sectors(span_lba, 4, &mut buf4, false).unwrap();
         for i in 0..4 {
@@ -345,10 +269,10 @@ mod tests {
     }
 
     #[test]
-    fn backward_seek_rebuffers() {
-        // Read forward across two windows, then jump back to sector
-        // 0. Buffer must refill from the start.
-        let total = BUF_SECTORS * 2 + 5;
+    fn backward_seek_reads_correct_bytes() {
+        // Read forward then jump back: the SectorSource contract is
+        // byte-correctness regardless of access pattern.
+        let total = TEST_SPAN_SECTORS * 2 + 5;
         let dir = tempdir().unwrap();
         let path = dir.path().join("back.iso");
         make_iso(&path, total);
@@ -356,24 +280,17 @@ mod tests {
         let mut src = FileSectorSource::open(&path).unwrap();
         let mut got = vec![0u8; SECTOR_SIZE];
 
-        // Forward to the second window.
-        src.read_sectors(BUF_SECTORS + 1, 1, &mut got, false)
+        src.read_sectors(TEST_SPAN_SECTORS + 1, 1, &mut got, false)
             .unwrap();
-
-        // Backward to sector 0. (0.21.3+: app-level buffer is bypassed
-        // so we only assert the byte-level contract, not internal
-        // buffer state.)
         src.read_sectors(0, 1, &mut got, false).unwrap();
         assert!(got.iter().all(|b| *b == 0));
     }
 
     #[test]
-    fn partial_buffer_at_eof() {
-        // File is smaller than one buffer window. The buffer must
-        // populate with only the available sectors and reads must
-        // still succeed.
+    fn read_at_eof_returns_correct_bytes() {
+        // File smaller than the readahead chunk — reads near EOF must
+        // still return correct bytes.
         let total: u32 = 100;
-        assert!(total < BUF_SECTORS);
         let dir = tempdir().unwrap();
         let path = dir.path().join("small.iso");
         make_iso(&path, total);
@@ -382,39 +299,27 @@ mod tests {
         assert_eq!(src.capacity_sectors(), total);
 
         let mut got = vec![0u8; SECTOR_SIZE];
-        // First read at sector 0.
         src.read_sectors(0, 1, &mut got, false).unwrap();
-
-        // Read the very last sector. (0.21.3+: app-level buffer is
-        // bypassed; the test still verifies that EOF-region reads
-        // return correct bytes.)
         src.read_sectors(total - 1, 1, &mut got, false).unwrap();
         let expected = ((total - 1) & 0xff) as u8;
         assert!(got.iter().all(|b| *b == expected));
     }
 
     #[test]
-    fn oversized_read_bypasses_buffer() {
-        // A request larger than the buffer must not deadlock the
-        // refill (which only loads BUF_SECTORS at a time). Bypass
-        // path handles it via direct pread.
-        let total = BUF_SECTORS + 100;
+    fn large_single_read() {
+        // A multi-MB single read must work — the implementation has
+        // no app-level chunking, so this just exercises the direct
+        // pread path on a larger request.
+        let total = TEST_SPAN_SECTORS + 100;
         let dir = tempdir().unwrap();
-        let path = dir.path().join("over.iso");
+        let path = dir.path().join("big.iso");
         make_iso(&path, total);
 
         let mut src = FileSectorSource::open(&path).unwrap();
-        // Read more than BUF_SECTORS in one call. count is u16, so we
-        // can't actually exceed BUF_SECTORS (16k) — but the path also
-        // triggers via `out.len() / SECTOR_SIZE > BUF_SECTORS` check
-        // implicitly because count > BUF_SECTORS. BUF_SECTORS for
-        // 32 MiB is 16384, which does fit in u16 (max 65535). Cap
-        // at BUF_SECTORS + 1 to exercise the bypass.
-        let req = (BUF_SECTORS + 1) as u16;
+        let req = (TEST_SPAN_SECTORS + 1) as u16;
         let req_bytes = req as usize * SECTOR_SIZE;
         let mut big = vec![0u8; req_bytes];
         src.read_sectors(0, req, &mut big, false).unwrap();
-        // Spot-check sector 0 and the last requested sector.
         assert!(big[..SECTOR_SIZE].iter().all(|b| *b == 0));
         let last_lba = req as u32 - 1;
         let exp = (last_lba & 0xff) as u8;
@@ -425,4 +330,32 @@ mod tests {
                 .all(|b| *b == exp)
         );
     }
+
+    #[test]
+    fn drop_chunk_size_env_override() {
+        // Explicit 8 MiB via env var.
+        // SAFETY: tests in this crate are single-threaded per the
+        // default cargo test harness, but std::env::set_var is
+        // declared `unsafe` since Rust 2024 (it can race with other
+        // threads / TLS). For a test that runs in-process before any
+        // FileSectorSource construction this is safe in practice.
+        unsafe {
+            std::env::set_var("FREEMKV_READ_DROP_CHUNK_MIB", "8");
+        }
+        assert_eq!(read_drop_chunk_bytes(), 8 * 1024 * 1024);
+
+        unsafe {
+            std::env::remove_var("FREEMKV_READ_DROP_CHUNK_MIB");
+        }
+        assert_eq!(read_drop_chunk_bytes(), READ_DROP_CHUNK_BYTES_DEFAULT);
+
+        // Garbage env value falls back to default.
+        unsafe {
+            std::env::set_var("FREEMKV_READ_DROP_CHUNK_MIB", "not-a-number");
+        }
+        assert_eq!(read_drop_chunk_bytes(), READ_DROP_CHUNK_BYTES_DEFAULT);
+        unsafe {
+            std::env::remove_var("FREEMKV_READ_DROP_CHUNK_MIB");
+        }
+    }
 }

src/io/file_sector_source/other.rs

@@ -7,3 +7,5 @@ use std::fs::File;
 pub(super) fn hint_sequential(_file: &File, _len_bytes: u64) {}
 
 pub(super) fn drop_window(_file: &File, _start: u64, _len: u64) {}
+
+pub(super) fn prefetch(_file: &File, _offset: u64, _len: u64) {}

src/io/file_sector_source/windows.rs

@@ -22,3 +22,9 @@ pub(super) fn hint_sequential(_file: &File, _len_bytes: u64) {
 /// equivalent. The kernel does its own working-set management. No-op
 /// for now.
 pub(super) fn drop_window(_file: &File, _start: u64, _len: u64) {}
+
+/// Windows async-prefetch hint. With FILE_FLAG_SEQUENTIAL_SCAN at
+/// open the kernel already prefetches aggressively, so there's no
+/// per-range hint we'd add on top. No-op stub for parity with the
+/// posix platforms.
+pub(super) fn prefetch(_file: &File, _offset: u64, _len: u64) {}

src/io/mod.rs

@@ -11,9 +11,12 @@
 //! to exhibit the same pathology for this access pattern.
 //!
 //! `FileSectorSource` is the read-side dual — it implements
-//! [`crate::sector::SectorSource`] for an ISO file with an internal
-//! 32 MiB read-ahead buffer that amortises NFS round-trip latency
-//! across thousands of sector reads.
+//! [`crate::sector::SectorSource`] for an ISO file using direct
+//! `pread`-equivalent calls so the kernel's own readahead policy runs
+//! (which interleaves naturally with the concurrent writeback). It
+//! pairs that with periodic `posix_fadvise(DONTNEED)` drops on the
+//! consumed window so an 85 GB streaming ISO read doesn't fill the
+//! page cache and starve the concurrent MKV write.
 //!
 //! `Pipeline` + `Sink` (0.18) is the generic producer/consumer primitive
 //! used by sweep, patch, and mux to overlap reads with writes via a
@@ -25,21 +28,21 @@
 
 pub(crate) mod bounded;
 pub mod byte_channel;
+pub mod byte_prefetcher;
 pub mod file_sector_source;
 pub mod sink;
 mod writeback;
 mod writeback_file;
 
+#[cfg(target_os = "macos")]
+pub(crate) mod platform_macos;
+
 pub mod pipeline;
 
 pub(crate) use writeback_file::WritebackFile;
 
-// Re-exports for the 0.18 redesign. Sweep + patch are both wired up
-// (disc/sweep.rs, disc/patch.rs); mux migrates separately in autorip.
-// `WRITE_THROUGH_DEPTH` is patch-specific and has no other in-tree
-// caller — the targeted `#[allow]` keeps the re-export visible without
-// dragging the rest of the module under `dead_code`.
-#[allow(unused_imports)]
+// Re-exports for the 0.18 redesign. Sweep, patch, and mux are all
+// wired up (disc/sweep.rs, disc/patch.rs, autorip's ripper/mux.rs).
 pub use pipeline::{
     DEFAULT_PIPELINE_DEPTH, Flow, Pipeline, READ_PIPELINE_DEPTH, Sink, WRITE_PIPELINE_DEPTH,
     WRITE_THROUGH_DEPTH,

src/io/pipeline.rs

@@ -53,26 +53,26 @@ use crate::halt::Halt;
 /// caller has already lost the rip.
 pub const JOIN_TIMEOUT_SECS: u64 = 600;
 
-/// Polling slice for the halt-aware send/finish loops. Mirrors the
-/// `bounded_syscall` cadence (250 ms) so halt observation feels equally
-/// responsive across both primitives.
-const POLL_INTERVAL: Duration = Duration::from_millis(250);
-
 /// Halt-check cadence for the send loop. Producer blocks on
 /// [`crossbeam_channel::Sender::send_timeout`] for this slice — the
 /// kernel wakes it the instant the consumer drains a slot, so on the
 /// happy path there's no throughput cap from this primitive at all
 /// (the cap is whatever the underlying medium can sustain). When the
-/// consumer is genuinely wedged, the timeout fires every 250 ms and
-/// the producer checks the halt token; that's the latency a stop
-/// request will observe.
+/// consumer is genuinely wedged, the timeout fires every
+/// [`crate::halt::POLL_INTERVAL`] and the producer checks the halt
+/// token; that's the latency a stop request will observe.
+///
+/// Single source of truth lives in [`crate::halt::POLL_INTERVAL`]
+/// (also used by `bounded_syscall`). Aliased here for readability of
+/// the send/finish call sites below.
 ///
 /// 0.21.7 replaced an old `std::sync::mpsc::sync_channel` + 50 ms
 /// `thread::sleep` polling loop that capped mux throughput at
 /// ~20 frames/sec ≈ 1 MB/s on saturated channels. See
 /// (internal)/memory/feedback_send_with_halt_poll_throttle.md
 /// for the multi-day diagnostic that surfaced it.
-const SEND_HALT_CHECK_INTERVAL: Duration = Duration::from_millis(250);
+use crate::halt::POLL_INTERVAL;
+const SEND_HALT_CHECK_INTERVAL: Duration = POLL_INTERVAL;
 
 /// Check if verbose debug logging is enabled via FREEMKV_DEBUG env var.
 pub fn debug_enabled() -> bool {
@@ -100,8 +100,7 @@ pub const WRITE_PIPELINE_DEPTH: usize = 16;
 /// Channel depth for write-through pipelines. Each `send` fully
 /// drains before the next can enqueue. Use this when the producer
 /// must observe consumer side-effects (e.g. mapfile state) before
-/// emitting the next item.
-#[allow(dead_code)]
+/// emitting the next item. Currently used by `disc::patch`.
 pub const WRITE_THROUGH_DEPTH: usize = 1;
 
 /// Outcome of [`Sink::apply`]: either keep feeding items
@@ -162,11 +161,10 @@ impl<I: Send + 'static, R: Send + 'static> Pipeline<I, R> {
     /// propagated rather than panicked.
     ///
     /// Sweep uses [`Pipeline::spawn_named`] directly so the consumer
-    /// thread shows up as `freemkv-sweep-consumer`; this function has
-    /// no in-tree caller yet. Patch and mux migrate in later 0.18
-    /// slices. The targeted `#[allow]` is removed when one of them
-    /// lands on the default name.
-    #[allow(dead_code)]
+    /// thread shows up as `freemkv-sweep-consumer`; mux uses
+    /// `freemkv-mux-consumer`. `Pipeline::spawn` (this function, with
+    /// the default name) is used by `disc::patch` and by the unit
+    /// tests in this module.
     pub fn spawn<S: Sink<I, Output = R>>(depth: usize, sink: S) -> Result<Self, Error> {
         Self::spawn_named("freemkv-pipeline-consumer", depth, sink)
     }

src/io/platform_macos.rs

@@ -0,0 +1,38 @@
+//! Shared macOS `fcntl(F_PREALLOCATE)` definitions.
+//!
+//! The `libc` crate doesn't expose these symbols across all macOS SDK
+//! versions, so we define them locally with values from
+//! `/usr/include/sys/fcntl.h`. Two call sites (
+//! [`crate::io::writeback_file`] and [`crate::io::sink::preallocate`])
+//! need the same constants and `fstore_t` layout — keeping a single
+//! source of truth here prevents the two copies from drifting.
+//!
+//! Module-level cfg gate lives in the parent (`io/mod.rs`); this file
+//! is only compiled on macOS, so no inner `#![cfg]` is needed.
+
+/// `fcntl(F_PREALLOCATE)` command number from `sys/fcntl.h`.
+pub(crate) const F_PREALLOCATE: libc::c_int = 42;
+
+/// Anchor preallocation at the current physical EOF.
+pub(crate) const F_PEOFPOSMODE: libc::c_int = 3;
+
+/// Prefer a contiguous allocation. Try this first; on `EINVAL` (no
+/// contiguous run of that size), fall back to `F_ALLOCATEALL`.
+pub(crate) const F_ALLOCATECONTIG: libc::c_uint = 0x0000_0002;
+
+/// Allow non-contiguous allocation. Stronger guarantee than just
+/// asking for `F_ALLOCATECONTIG` because the kernel will piece
+/// together fragments rather than failing.
+pub(crate) const F_ALLOCATEALL: libc::c_uint = 0x0000_0004;
+
+/// `fstore_t` from `sys/fcntl.h`. `repr(C)` because we hand it to
+/// `fcntl(F_PREALLOCATE)` which writes through the pointer.
+#[repr(C)]
+#[derive(Clone, Copy)]
+pub(crate) struct Fstore {
+    pub fst_flags: libc::c_uint,
+    pub fst_posmode: libc::c_int,
+    pub fst_offset: libc::off_t,
+    pub fst_length: libc::off_t,
+    pub fst_bytesalloc: libc::off_t,
+}

src/io/sink/preallocate/macos.rs

@@ -7,23 +7,9 @@
 use std::fs::File;
 use std::os::unix::io::AsRawFd;
 
-// Mirror the Darwin `fstore_t` struct from `<sys/fcntl.h>`. libc on
-// some Rust toolchains/versions doesn't ship this binding, so define
-// it locally with the layout the kernel ABI requires.
-#[repr(C)]
-struct Fstore {
-    fst_flags: libc::c_uint,
-    fst_posmode: libc::c_int,
-    fst_offset: libc::off_t,
-    fst_length: libc::off_t,
-    fst_bytesalloc: libc::off_t,
-}
-
-// Constants from <sys/fcntl.h>.
-const F_PREALLOCATE: libc::c_int = 42;
-const F_ALLOCATECONTIG: libc::c_uint = 0x0000_0002;
-const F_ALLOCATEALL: libc::c_uint = 0x0000_0004;
-const F_PEOFPOSMODE: libc::c_int = 3;
+use crate::io::platform_macos::{
+    F_ALLOCATEALL, F_ALLOCATECONTIG, F_PEOFPOSMODE, F_PREALLOCATE, Fstore,
+};
 
 pub(super) fn preallocate_impl(file: &File, size_bytes: u64) {
     let fd = file.as_raw_fd();

src/io/writeback/linux.rs

@@ -300,35 +300,22 @@ impl WritebackPipeline {
     }
 }
 
-/// Probe whether `fd` lives on an NFS mount via `fstatfs`. Returns
-/// `false` on any error — we fail open, not closed: better to run the
-/// normal local-storage path on a misdetected NFS mount (and surface
-/// the freeze loudly via the timeout) than to needlessly disable
-/// writeback bounding on every local file because of a transient
-/// stat error.
+/// Probe whether `fd` lives on an NFS mount. Thin wrapper around
+/// [`crate::platform::fs_type::detect_fd`] so writeback policy and
+/// general-purpose fs-type classification stay in sync (same magic
+/// numbers, same musl-vs-glibc cast handling).
+///
+/// Fails open: any classification other than NFS counts as "not NFS"
+/// (including `Unknown` on `fstatfs` error) — better to run the
+/// normal local-storage path on a misdetected NFS mount and surface
+/// the freeze loudly via [`WAIT_AFTER_TIMEOUT`] than to needlessly
+/// disable writeback bounding on every local file because of a
+/// transient stat error.
 fn detect_nfs(fd: RawFd) -> bool {
-    // `libc::statfs` is repr(C) with a fixed layout; zeroing is the
-    // documented init pattern for the kernel uapi struct.
-    let mut buf: libc::statfs = unsafe { std::mem::zeroed() };
-    let rc = unsafe { libc::fstatfs(fd, &mut buf) };
-    if rc != 0 {
-        let errno = std::io::Error::last_os_error();
-        tracing::warn!(
-            target: "mux",
-            "WritebackPipeline fstatfs(fd={fd}) failed: {errno} — defaulting is_nfs=false",
-        );
-        return false;
-    }
-    // `f_type` is signed (`__fsword_t`) on glibc and unsigned
-    // (`c_ulong`) on musl. Cast both sides to i64 for a portable
-    // comparison. On glibc x86_64 both already are i64 — clippy flags
-    // the cast as unnecessary on that target only, but we need it for
-    // musl, so silence the lint.
-    #[allow(clippy::unnecessary_cast)]
-    let f_type = buf.f_type as i64;
-    #[allow(clippy::unnecessary_cast)]
-    let nfs_magic = libc::NFS_SUPER_MAGIC as i64;
-    f_type == nfs_magic
+    matches!(
+        crate::platform::fs_type::detect_fd(fd),
+        crate::platform::fs_type::FsType::Nfs
+    )
 }
 
 /// Run `sync_file_range(WAIT_AFTER)` on a worker thread and wait up
@@ -356,3 +343,117 @@ fn wait_after_with_timeout(fd: RawFd, off: u64, len: u64) -> Option<u64> {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::NamedTempFile;
+
+    /// Helper: build a `WritebackPipeline` over a local tempfile. On
+    /// every test rig (linux dev box, CI) the tempfile lives on a
+    /// local FS, so `is_nfs=false` and `skip_wait` returns false until
+    /// we explicitly mark the pipeline degraded.
+    fn local_pipeline(chunk_bytes: u64) -> (NamedTempFile, WritebackPipeline) {
+        let f = NamedTempFile::new().expect("tempfile create");
+        let pipeline = WritebackPipeline::new(f.as_file(), 0, chunk_bytes);
+        (f, pipeline)
+    }
+
+    #[test]
+    fn new_pipeline_starts_active() {
+        let (_f, p) = local_pipeline(32 * 1024 * 1024);
+        assert!(!p.is_nfs, "local tempfile must not classify as NFS");
+        assert!(!p.degraded.load(Ordering::Relaxed));
+        assert!(!p.skip_wait(), "fresh local pipeline must not skip wait");
+    }
+
+    #[test]
+    fn degraded_flag_short_circuits_wait() {
+        let (_f, p) = local_pipeline(32 * 1024 * 1024);
+        assert!(!p.skip_wait());
+        p.degraded.store(true, Ordering::Relaxed);
+        assert!(
+            p.skip_wait(),
+            "degraded flag must force the wait+dontneed bypass"
+        );
+    }
+
+    #[test]
+    fn record_wait_grows_chunk_on_high_p95() {
+        let (_f, mut p) = local_pipeline(16 * 1024 * 1024);
+        // Fill the window with samples above the grow threshold.
+        for _ in 0..ADAPTIVE_WINDOW {
+            p.record_wait(ADAPTIVE_GROW_MS + 50);
+        }
+        assert!(
+            p.chunk_bytes > 16 * 1024 * 1024,
+            "chunk should have grown; got {}",
+            p.chunk_bytes
+        );
+        assert!(p.chunk_bytes <= CHUNK_BYTES_MAX);
+    }
+
+    #[test]
+    fn record_wait_shrinks_chunk_on_low_p95() {
+        let (_f, mut p) = local_pipeline(64 * 1024 * 1024);
+        for _ in 0..ADAPTIVE_WINDOW {
+            p.record_wait(1); // well under ADAPTIVE_SHRINK_MS
+        }
+        assert!(
+            p.chunk_bytes < 64 * 1024 * 1024,
+            "chunk should have shrunk; got {}",
+            p.chunk_bytes
+        );
+        assert!(p.chunk_bytes >= CHUNK_BYTES_MIN);
+    }
+
+    #[test]
+    fn record_wait_no_op_below_window_fill() {
+        let (_f, mut p) = local_pipeline(16 * 1024 * 1024);
+        let initial = p.chunk_bytes;
+        // Only push a few samples; window not full → no adaptation.
+        for _ in 0..(ADAPTIVE_WINDOW - 1) {
+            p.record_wait(ADAPTIVE_GROW_MS + 100);
+        }
+        assert_eq!(
+            p.chunk_bytes, initial,
+            "chunk must not change before window is full"
+        );
+    }
+
+    #[test]
+    fn record_wait_clamps_to_chunk_bounds() {
+        // Grow past the max.
+        let (_f, mut p) = local_pipeline(CHUNK_BYTES_MAX);
+        for _ in 0..ADAPTIVE_WINDOW {
+            p.record_wait(ADAPTIVE_GROW_MS + 1000);
+        }
+        assert_eq!(p.chunk_bytes, CHUNK_BYTES_MAX, "must clamp to MAX");
+
+        // Shrink past the min.
+        let (_f, mut p) = local_pipeline(CHUNK_BYTES_MIN);
+        for _ in 0..ADAPTIVE_WINDOW {
+            p.record_wait(0);
+        }
+        assert_eq!(p.chunk_bytes, CHUNK_BYTES_MIN, "must clamp to MIN");
+    }
+
+    #[test]
+    fn detect_nfs_local_file_is_false() {
+        // Local tempfile must not classify as NFS. This locks in the
+        // consolidation through `crate::platform::fs_type::detect_fd`.
+        let f = NamedTempFile::new().expect("tempfile create");
+        use std::os::unix::io::AsRawFd;
+        assert!(!detect_nfs(f.as_file().as_raw_fd()));
+    }
+
+    #[test]
+    fn note_progress_below_chunk_is_noop() {
+        let (_f, mut p) = local_pipeline(32 * 1024 * 1024);
+        // No-op return before crossing the first chunk boundary.
+        let before = p.chunk_count;
+        p.note_progress(1024); // < 32 MiB
+        assert_eq!(p.chunk_count, before);
+        assert!(p.pending.is_none());
+    }
+}

src/io/writeback_file/macos.rs

@@ -16,31 +16,14 @@ use std::io;
 use std::os::unix::io::AsRawFd;
 use std::time::Duration;
 
-/// libc `F_PREALLOCATE` — not exposed by the `libc` crate on all macOS
-/// SDK versions, so define it here.
-const F_PREALLOCATE: libc::c_int = 42;
-/// Allocate from current EOF.
-const F_PEOFPOSMODE: libc::c_int = 3;
-/// Hint: contiguous extent preferred.
-const F_ALLOCATECONTIG: libc::c_uint = 0x00000002;
-/// Allocate all the requested bytes (fall back to non-contig if needed).
-const F_ALLOCATEALL: libc::c_uint = 0x00000004;
+use crate::io::platform_macos::{
+    F_ALLOCATEALL, F_ALLOCATECONTIG, F_PEOFPOSMODE, F_PREALLOCATE, Fstore,
+};
 
 /// `fcntl(F_FULLFSYNC)` opcode. Documented in `man 2 fcntl` on macOS;
 /// not in the `libc` crate as a named constant.
 const F_FULLFSYNC: libc::c_int = 51;
 
-/// `fstore_t` layout matches `sys/fcntl.h`. Repr is C-stable so we can
-/// build it manually.
-#[repr(C)]
-struct Fstore {
-    fst_flags: libc::c_uint,
-    fst_posmode: libc::c_int,
-    fst_offset: libc::off_t,
-    fst_length: libc::off_t,
-    fst_bytesalloc: libc::off_t,
-}
-
 pub(super) fn preallocate(file: &File, size_bytes: u64) {
     let mut fst = Fstore {
         fst_flags: F_ALLOCATECONTIG | F_ALLOCATEALL,

src/io/writeback_file/mod.rs

@@ -73,10 +73,21 @@ use std::path::Path;
 use super::writeback::WritebackPipeline;
 
 /// Granularity at which the Linux writeback pipeline issues
-/// `sync_file_range` pairs. 32 MiB is the empirically best value:
-/// iter8 = 28.7, iter9 (64 MiB) = 27.5, iter11 (128 MiB) = 16.6,
-/// iter6 (8 MiB) = 15.8. Locked.
-const WRITEBACK_CHUNK_BYTES: u64 = 32 * 1024 * 1024;
+/// `sync_file_range` pairs. 32 MiB is the empirically best value on
+/// the rip1 test bed (NFS to unraid-1 over 1 GbE, single-disk SAS):
+/// 8 MiB / 64 MiB / 128 MiB all measured worse in the 0.21.x mux
+/// iteration runs. Override via `FREEMKV_WRITEBACK_CHUNK_MIB` —
+/// faster backends (NVMe, RAID) may tolerate larger windows.
+const WRITEBACK_CHUNK_BYTES_DEFAULT: u64 = 32 * 1024 * 1024;
+
+fn writeback_chunk_bytes() -> u64 {
+    std::env::var("FREEMKV_WRITEBACK_CHUNK_MIB")
+        .ok()
+        .and_then(|v| v.parse::<u64>().ok())
+        .filter(|&n| n > 0)
+        .map(|n| n * 1024 * 1024)
+        .unwrap_or(WRITEBACK_CHUNK_BYTES_DEFAULT)
+}
 
 pub(crate) struct WritebackFile {
     file: File,
@@ -91,7 +102,7 @@ impl WritebackFile {
     /// or appended files).
     pub(crate) fn new(mut file: File) -> io::Result<Self> {
         let pos = file.stream_position()?;
-        let pipeline = WritebackPipeline::new(&file, pos, WRITEBACK_CHUNK_BYTES);
+        let pipeline = WritebackPipeline::new(&file, pos, writeback_chunk_bytes());
         Ok(Self {
             file,
             pipeline,