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/mux/resolve.rs

@@ -15,11 +15,13 @@
 //! Bare paths without a scheme are rejected.
 //! For disc→ISO (raw sector copy), use `Disc::copy()` instead.
 
-use super::disc::DiscStream;
 use super::network::NetworkStream;
 use super::null::NullStream;
+use super::pipelined_stream::PipelinedPesStream;
 use super::stdio::StdioStream;
 use super::{M2tsStream, MkvStream};
+use crate::disc::{ContentFormat, DiscTitle};
+use crate::sector::SectorSource;
 use std::io;
 use std::path::{Path, PathBuf};
 
@@ -185,7 +187,12 @@ pub fn input(url: &str, opts: &InputOptions) -> io::Result<Box<dyn crate::pes::S
                 },
                 None => crate::disc::ScanOptions::default(),
             };
-            let mut reader = super::iso::IsoSectorReader::open(&path.to_string_lossy())?;
+            // FileSectorSource is the sole file-backed sector source.
+            // It carries the platform-tuned SEQUENTIAL fadvise hint
+            // (so the kernel readahead window widens) and the periodic
+            // DONTNEED page-cache eviction that bounds memory pressure
+            // when the mux output is being written to the same disk.
+            let mut reader = crate::io::file_sector_source::FileSectorSource::open(path)?;
             let capacity = reader.capacity_sectors();
             let disc = crate::disc::Disc::scan_image(&mut reader, capacity, &scan_opts)
                 .map_err(|e| -> io::Error { e.into() })?;
@@ -203,21 +210,39 @@ pub fn input(url: &str, opts: &InputOptions) -> io::Result<Box<dyn crate::pes::S
             let title = disc.titles[idx].clone();
             let keys = disc.decrypt_keys();
             let format = disc.content_format;
-            // ISO file: use large batch size (16 MB) — sequential read from fast storage, no bad sectors.
-            // Physical drives need small batches for adaptive error handling and retry logic.
+            // ISO file: 16 MiB batch — sequential read from fast
+            // storage, no bad sectors. Measured optimum on the rip1
+            // testbed; bumping to 32 MiB regressed (more cache
+            // pressure, longer per-batch latency starves the consumer
+            // between iterations). Physical drives keep smaller
+            // batches for adaptive error handling.
             const ISO_MUX_BATCH_SECTORS: u16 = 8192;
-            let mut stream =
-                DiscStream::new(Box::new(reader), title, keys, ISO_MUX_BATCH_SECTORS, format);
-            if opts.raw {
-                stream.set_raw();
-            }
+
+            // Pass `DecryptKeys::None` to the decrypt decorator when
+            // --raw is set — the read stack still flows through the
+            // same producer+demux+parse pipeline, just without the
+            // AACS / CSS step. Single highway for all ISO reads.
+            let effective_keys = if opts.raw {
+                crate::decrypt::DecryptKeys::None
+            } else {
+                keys
+            };
+            let stream = build_iso_pipeline(
+                reader,
+                title,
+                effective_keys,
+                ISO_MUX_BATCH_SECTORS,
+                format,
+                None,
+            );
             Ok(Box::new(stream))
         }
         StreamUrl::M2ts { ref path } => {
             validate_file_path(path, "m2ts")?;
             let file = std::fs::File::open(path)?;
             let reader = std::io::BufReader::with_capacity(IO_BUF_SIZE, file);
-            Ok(Box::new(M2tsStream::open(reader)?))
+            let stream = build_m2ts_pipeline(reader)?;
+            Ok(Box::new(stream))
         }
         StreamUrl::Mkv { ref path } => {
             validate_file_path(path, "mkv")?;
@@ -281,3 +306,135 @@ pub fn output(
         }
     }
 }
+
+/// Demuxer-side state derived from a `DiscTitle`: the codec parser
+/// table (keyed by PID), the PID-to-track index map, and an initial
+/// `TsDemuxer` / `PsDemuxer` (whichever the content format calls
+/// for).
+type DemuxState = (
+    Vec<(u16, Box<dyn super::codec::CodecParser>)>,
+    Vec<(u16, usize)>,
+    Option<super::ts::TsDemuxer>,
+    Option<super::ps::PsDemuxer>,
+);
+
+/// Build the title's codec parser table + initial `TsDemuxer` /
+/// `PsDemuxer`. Used by both the ISO and M2TS pipeline builders.
+fn build_demux_state(title: &DiscTitle, format: ContentFormat) -> DemuxState {
+    let mut pids = Vec::new();
+    let mut parsers = Vec::new();
+    let mut pid_to_track = Vec::new();
+    for (idx, s) in title.streams.iter().enumerate() {
+        let (pid, codec) = match s {
+            crate::disc::Stream::Video(v) => (v.pid, v.codec),
+            crate::disc::Stream::Audio(a) => (a.pid, a.codec),
+            crate::disc::Stream::Subtitle(s) => (s.pid, s.codec),
+        };
+        pids.push(pid);
+        pid_to_track.push((pid, idx));
+        parsers.push((pid, super::codec::parser_for_codec(codec, None)));
+    }
+    let (ts, ps) = match format {
+        ContentFormat::MpegPs => (None, Some(super::ps::PsDemuxer::new())),
+        ContentFormat::BdTs => {
+            if pids.is_empty() {
+                (None, None)
+            } else {
+                (Some(super::ts::TsDemuxer::new(&pids)), None)
+            }
+        }
+    };
+    (parsers, pid_to_track, ts, ps)
+}
+
+/// Assemble the ISO mux pipeline (read+decrypt → demux → parse) for
+/// a `FileSectorSource`-backed reader. Returns the resulting
+/// `PipelinedPesStream`.
+pub fn build_iso_pipeline<S: SectorSource + Send + 'static>(
+    reader: S,
+    title: DiscTitle,
+    keys: crate::decrypt::DecryptKeys,
+    batch_sectors: u16,
+    format: ContentFormat,
+    halt: Option<crate::halt::Halt>,
+) -> PipelinedPesStream {
+    let extents = title.extents.clone();
+    let decrypting =
+        crate::sector::DecryptingSectorSource::new(Box::new(reader) as Box<dyn SectorSource>, keys);
+    let prefetched = crate::sector::PrefetchedSectorSource::new(
+        decrypting,
+        extents,
+        batch_sectors,
+        halt.clone(),
+    );
+    let (rx, recycle_tx, shell) = prefetched.into_channels();
+
+    let (parsers, pid_to_track, ts, ps) = build_demux_state(&title, format);
+    let (demux_thread, demux_rx) =
+        super::demux_thread::DemuxThread::spawn_zero_copy(rx, recycle_tx, shell, halt, ts, ps);
+    PipelinedPesStream::new(demux_thread, demux_rx, title, parsers, pid_to_track)
+}
+
+/// Assemble the M2TS file mux pipeline (read → demux → parse) for a
+/// byte-stream reader. Scans the head for FMKV header or PMT/PAT,
+/// rebuilds the title metadata, then wraps a chained reader (head +
+/// remainder) in a `BytePrefetcher` feeding the demux + parse
+/// threads.
+fn build_m2ts_pipeline<R: std::io::Read + Send + 'static>(
+    mut reader: R,
+) -> io::Result<PipelinedPesStream> {
+    use super::meta;
+    use std::io::Read;
+
+    const M2TS_SCAN_BYTES: usize = 1024 * 1024;
+    let mut head = vec![0u8; M2TS_SCAN_BYTES];
+    let head_len = {
+        let mut filled = 0;
+        while filled < head.len() {
+            match reader.read(&mut head[filled..])? {
+                0 => break,
+                n => filled += n,
+            }
+        }
+        filled
+    };
+    head.truncate(head_len);
+
+    // Try FMKV metadata header first; fall back to PMT scan.
+    let mut cursor = io::Cursor::new(&head);
+    let (title, head_consumed) = if let Ok(Some(m)) = meta::read_header(&mut cursor) {
+        (m.to_title(), cursor.position() as usize)
+    } else {
+        let streams = super::ts::scan_streams(&head)
+            .ok_or_else(|| -> io::Error { crate::error::Error::NoStreams.into() })?;
+        let t = DiscTitle {
+            duration_secs: 0.0,
+            streams,
+            ..DiscTitle::empty()
+        };
+        (t, 0)
+    };
+
+    // Chain: any un-consumed head bytes + the remainder of the
+    // reader. The demuxer sees a contiguous M2TS byte stream.
+    let remaining_head = head[head_consumed..].to_vec();
+    let chained: Box<dyn Read + Send> = Box::new(io::Cursor::new(remaining_head).chain(reader));
+
+    let prefetcher = crate::io::byte_prefetcher::BytePrefetcher::new(
+        chained,
+        crate::io::byte_prefetcher::DEFAULT_CHUNK_BYTES,
+        None,
+    );
+    let (rx, recycle_tx, shell) = prefetcher.into_channels();
+
+    let (parsers, pid_to_track, ts, ps) = build_demux_state(&title, ContentFormat::BdTs);
+    let (demux_thread, demux_rx) =
+        super::demux_thread::DemuxThread::spawn_zero_copy(rx, recycle_tx, shell, None, ts, ps);
+    Ok(PipelinedPesStream::new(
+        demux_thread,
+        demux_rx,
+        title,
+        parsers,
+        pid_to_track,
+    ))
+}