io: phase 1 buffering — read-side flatness

Three changes targeting 0.20.9's "muxer never read-stalls on NFS read
latency" invariant:

A. FileSectorSource gets a 32 MiB internal read-ahead buffer
   (READAHEAD_BUF_BYTES). Splits out from src/sector/file.rs into
   src/io/file_sector_source/ with per-OS open hints (Linux
   posix_fadvise(SEQUENTIAL), macOS fcntl(F_RDADVISE) with 64 MiB
   cap, Windows TODO stub, BSD/illumos no-op). Backward seeks
   rebuffer; partial reads at EOF return only the bytes that exist;
   oversize-request bypass for count > BUF_SECTORS.

B. WritebackFile inline #[cfg(target_os = "linux")] blocks split
   into per-OS files under src/io/writeback_file/. Linux unchanged
   (fallocate KEEP_SIZE, fsync via bounded_syscall). macOS gets a
   real F_PREALLOCATE + F_FULLFSYNC impl (was a "skipped (non-linux)"
   debug log before). Windows is a stub (FlushFileBuffers via
   std sync_all; TODO for SetFileValidData). BSDs/illumos fall back
   to std sync_all.

C. New byte_channel module — byte-bounded producer/consumer wrapping
   std sync_channel with Mutex/Condvar byte accounting. Sender blocks
   when used_bytes + item.byte_size() > capacity. HasByteSize impl
   for PesFrame. Default cap BYTE_CHANNEL_DEFAULT_CAPACITY = 64 MiB,
   sized to absorb worst-case NFS read p99 (~2 s × UHD peak compressed
   ~15 MB/s). The mux call site lives in autorip (out of scope here);
   this lands the primitive in libfreemkv for autorip to adopt.

Test counts: byte_channel +6, file_sector_source +5, sector::file
round-trip suite (3) preserved. passn_handler_ab.rs A/B fixture
(8 profiles) still green.

precommit.sh libfreemkv: fmt + clippy + test all green on Rust 1.86.

No version bump; no Cargo.lock changes; no forbidden-file edits
(disc/patch.rs, disc/read_error.rs, io/pipeline.rs,
tests/passn_handler_ab.rs).

src/io/file_sector_source/linux.rs

@@ -0,0 +1,15 @@
+//! Linux: hint the kernel that this fd will be read sequentially so
+//! readahead widens. `posix_fadvise(POSIX_FADV_SEQUENTIAL)` is a hint,
+//! not a guarantee — the kernel still owns the policy decision.
+
+use std::fs::File;
+use std::os::unix::io::AsRawFd;
+
+pub(super) fn hint_sequential(file: &File, _len_bytes: u64) {
+    // Best-effort: return value ignored. A fadvise failure has no
+    // user-observable consequence (reads still work, just without the
+    // widened readahead window).
+    unsafe {
+        libc::posix_fadvise(file.as_raw_fd(), 0, 0, libc::POSIX_FADV_SEQUENTIAL);
+    }
+}

src/io/file_sector_source/macos.rs

@@ -0,0 +1,38 @@
+//! macOS: hint the kernel to prefetch a generous chunk. macOS has no
+//! direct `POSIX_FADV_SEQUENTIAL` equivalent; the idiomatic hint is
+//! `fcntl(F_RDADVISE, &radvisory)` describing the byte range you
+//! intend to read soon. We point it at the whole file (clamped to a
+//! ceiling so a multi-TB ISO doesn't ask the kernel to prefetch
+//! everything at once).
+
+use std::fs::File;
+use std::os::unix::io::AsRawFd;
+
+/// `F_RDADVISE` opcode — not in libc's named constants on all SDKs.
+const F_RDADVISE: libc::c_int = 44;
+
+/// Cap on the byte length we pass to `F_RDADVISE`. Asking for a
+/// multi-GB readahead window is counterproductive — the OS doesn't
+/// have that much cache to throw at one fd. 64 MiB is generous for
+/// our use case (sweep, mux) and matches the byte-channel cap so the
+/// kernel's prefetch ≥ our app-level pipeline depth.
+const RDADVISE_MAX_BYTES: i64 = 64 * 1024 * 1024;
+
+/// `radvisory` per `<sys/fcntl.h>`. repr(C) layout is stable.
+#[repr(C)]
+struct RadAdvisory {
+    ra_offset: libc::off_t,
+    ra_count: libc::c_int,
+}
+
+pub(super) fn hint_sequential(file: &File, len_bytes: u64) {
+    let bytes = (len_bytes as i64).min(RDADVISE_MAX_BYTES);
+    let mut ra = RadAdvisory {
+        ra_offset: 0,
+        ra_count: bytes as libc::c_int,
+    };
+    // Best-effort.
+    unsafe {
+        libc::fcntl(file.as_raw_fd(), F_RDADVISE, &mut ra);
+    }
+}

src/io/file_sector_source/mod.rs

@@ -0,0 +1,393 @@
+//! [`FileSectorSource`] — read 2048-byte sectors from an ISO file on
+//! disk, with an internal 32 MiB read-ahead buffer.
+//!
+//! ## Why the 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.
+//!
+//! 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).
+//!
+//! ## Access pattern assumption
+//!
+//! 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
+//!
+//! 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.
+
+#[cfg(target_os = "linux")]
+mod linux;
+#[cfg(target_os = "macos")]
+mod macos;
+#[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "windows")))]
+mod other;
+#[cfg(target_os = "windows")]
+mod windows;
+
+#[cfg(target_os = "linux")]
+use linux as platform;
+#[cfg(target_os = "macos")]
+use macos as platform;
+#[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "windows")))]
+use other as platform;
+#[cfg(target_os = "windows")]
+use windows as platform;
+
+use std::fs::File;
+use std::io::{Read, Seek, SeekFrom};
+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.
+///
+/// Tweakable. Named const, not a magic number.
+pub const READAHEAD_BUF_BYTES: usize = 32 * 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.
+pub struct FileSectorSource {
+    file: File,
+    /// Total file size in sectors. Constant after construction;
+    /// surfaced via [`SectorSource::capacity_sectors`].
+    capacity: u32,
+    /// Heap-allocated read-ahead buffer. Boxed slice (not `Vec`) so
+    /// the allocation is sized exactly once and the layout is
+    /// stable. Length is at most [`READAHEAD_BUF_BYTES`].
+    buf: Box<[u8]>,
+    /// First LBA covered by `buf`. `buf_len_sectors == 0` means the
+    /// buffer is empty (e.g. immediately after construction or a
+    /// backward seek); the value of `buf_start_lba` is then
+    /// meaningless.
+    buf_start_lba: u32,
+    /// Number of valid sectors in `buf`. `[buf_start_lba,
+    /// buf_start_lba + buf_len_sectors)` is the half-open LBA range
+    /// the buffer currently caches.
+    buf_len_sectors: u32,
+}
+
+impl FileSectorSource {
+    /// Open an existing ISO file for reading. Capacity is derived
+    /// from `metadata().len() / 2048`. Returns
+    /// [`Error::IsoTooLarge`] if the file would exceed the 32-bit
+    /// LBA address space (~8 TB).
+    ///
+    /// Issues the platform's "sequential access expected" hint on the
+    /// fd (Linux `posix_fadvise(SEQUENTIAL)`, macOS `fcntl(F_RDADVISE)`,
+    /// Windows TODO stub) so the kernel's readahead widens.
+    pub fn open(path: &Path) -> std::io::Result<Self> {
+        let file = File::open(path)?;
+        let len = file.metadata()?.len();
+        let sectors = len / SECTOR_SIZE as u64;
+        if sectors > u32::MAX as u64 {
+            return Err(Error::IsoTooLarge {
+                path: path.to_string_lossy().into_owned(),
+            }
+            .into());
+        }
+        let capacity = sectors as u32;
+
+        // Best-effort sequential hint. Ignored on platforms without
+        // an equivalent primitive (or where the API exists but the
+        // 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,
+        })
+    }
+
+    /// True if `[lba, lba + count)` is wholly inside the current
+    /// buffer window. `count == 0` is vacuously true.
+    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`.
+    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 {
+    fn capacity_sectors(&self) -> u32 {
+        self.capacity
+    }
+
+    fn read_sectors(
+        &mut self,
+        lba: u32,
+        count: u16,
+        out: &mut [u8],
+        _recovery: bool,
+    ) -> Result<usize> {
+        let count = count as u32;
+        let bytes = count as usize * SECTOR_SIZE;
+        debug_assert!(
+            out.len() >= bytes,
+            "FileSectorSource::read_sectors: out len {} < requested {}",
+            out.len(),
+            bytes
+        );
+        if count == 0 {
+            return Ok(0);
+        }
+        // Refill if the requested range isn't entirely buffered.
+        // `buffer_covers` also handles the empty-buffer case
+        // (buf_len_sectors == 0).
+        if !self.buffer_covers(lba, count) {
+            // A request larger than the buffer itself can never fit;
+            // fall back to a one-shot direct pread for that pathological
+            // case so callers can't deadlock the source.
+            if count > BUF_SECTORS {
+                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 out[..bytes])
+                    .map_err(|e| Error::IoError { source: e })?;
+                // Invalidate buffer state — we bypassed it, the
+                // window is no longer authoritative for this LBA.
+                self.buf_len_sectors = 0;
+                return Ok(bytes);
+            }
+            self.refill(lba)?;
+        }
+
+        // Slice the buffer at the requested LBA's offset within it.
+        let off_sectors = (lba - self.buf_start_lba) as usize;
+        let off_bytes = off_sectors * SECTOR_SIZE;
+        out[..bytes].copy_from_slice(&self.buf[off_bytes..off_bytes + bytes]);
+        Ok(bytes)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Write;
+    use tempfile::tempdir;
+
+    /// Build a deterministic ISO of `sectors` sectors where sector `n`
+    /// is filled with the byte pattern `((n & 0xff) as u8)`. Lets us
+    /// verify any sector by content alone.
+    fn make_iso(path: &std::path::Path, sectors: u32) {
+        let mut f = std::fs::File::create(path).unwrap();
+        let mut chunk = vec![0u8; SECTOR_SIZE];
+        for n in 0..sectors {
+            let b = (n & 0xff) as u8;
+            chunk.iter_mut().for_each(|c| *c = b);
+            f.write_all(&chunk).unwrap();
+        }
+        f.flush().unwrap();
+    }
+
+    #[test]
+    fn sequential_reads_match_file() {
+        // Two full buffer windows + a tail = exercise refill across
+        // boundaries.
+        let total = BUF_SECTORS * 2 + 17;
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("seq.iso");
+        make_iso(&path, total);
+
+        let mut src = FileSectorSource::open(&path).unwrap();
+        assert_eq!(src.capacity_sectors(), total);
+
+        let mut got = vec![0u8; SECTOR_SIZE];
+        for lba in 0..total {
+            src.read_sectors(lba, 1, &mut got, false).unwrap();
+            let expected = (lba & 0xff) as u8;
+            assert!(
+                got.iter().all(|b| *b == expected),
+                "sector {lba} content mismatch: expected 0x{expected:02x}"
+            );
+        }
+    }
+
+    #[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;
+        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 to populate buffer #0.
+        let mut got = vec![0u8; SECTOR_SIZE];
+        src.read_sectors(0, 1, &mut got, false).unwrap();
+        assert_eq!(src.buf_start_lba, 0);
+        assert!(src.buf_len_sectors > 0);
+
+        // Now read 4 sectors crossing the buffer boundary at
+        // BUF_SECTORS - 2 → BUF_SECTORS + 1. Spans the refill.
+        let span_lba = BUF_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 {
+            let lba = span_lba + i as u32;
+            let expected = (lba & 0xff) as u8;
+            for b in &buf4[i * SECTOR_SIZE..(i + 1) * SECTOR_SIZE] {
+                assert_eq!(*b, expected, "byte mismatch at sub-sector {i}");
+            }
+        }
+    }
+
+    #[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;
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("back.iso");
+        make_iso(&path, total);
+
+        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)
+            .unwrap();
+        let start_after_forward = src.buf_start_lba;
+        assert!(start_after_forward >= BUF_SECTORS);
+
+        // Backward to sector 0. The current buffer doesn't cover it
+        // → refill must happen.
+        src.read_sectors(0, 1, &mut got, false).unwrap();
+        assert_eq!(src.buf_start_lba, 0);
+        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.
+        let total: u32 = 100;
+        assert!(total < BUF_SECTORS);
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("small.iso");
+        make_iso(&path, total);
+
+        let mut src = FileSectorSource::open(&path).unwrap();
+        assert_eq!(src.capacity_sectors(), total);
+
+        let mut got = vec![0u8; SECTOR_SIZE];
+        // First read triggers refill clamped to `total`.
+        src.read_sectors(0, 1, &mut got, false).unwrap();
+        assert_eq!(src.buf_len_sectors, total);
+
+        // Read the very last sector — still inside the buffer.
+        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;
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("over.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_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;
+        let last_off = (req as usize - 1) * SECTOR_SIZE;
+        assert!(
+            big[last_off..last_off + SECTOR_SIZE]
+                .iter()
+                .all(|b| *b == exp)
+        );
+    }
+}

src/io/file_sector_source/other.rs

@@ -0,0 +1,7 @@
+//! Fallback for targets without a known sequential-readahead hint
+//! (BSDs, illumos, etc.). No-op — reads still work, they just don't
+//! get the OS-level prefetch widening.
+
+use std::fs::File;
+
+pub(super) fn hint_sequential(_file: &File, _len_bytes: u64) {}

src/io/file_sector_source/windows.rs

@@ -0,0 +1,19 @@
+//! Windows: the canonical sequential-access hint is
+//! `FILE_FLAG_SEQUENTIAL_SCAN` passed to `CreateFile` at open time —
+//! it cannot be set after the fact via `SetFileInformationByHandle`.
+//! Routing the open call through this module would mean a custom
+//! `File::from_raw_handle` plumb for every `FileSectorSource::open`
+//! caller, which is more invasive than the Phase 1 scope.
+//!
+//! TODO: replumb `FileSectorSource::open` to take an
+//! `OpenOptions`-style builder so the Windows path can flip the flag
+//! at open time. For now this is a no-op stub.
+
+use std::fs::File;
+
+pub(super) fn hint_sequential(_file: &File, _len_bytes: u64) {
+    tracing::debug!(
+        target: "mux",
+        "FileSectorSource hint_sequential: windows stub (TODO: FILE_FLAG_SEQUENTIAL_SCAN at open)"
+    );
+}