v0.20.8: bump version

io+disc: bundle 0.20.8 dev work
- io/pipeline.rs: add send_with_halt + finish_with_halt for cooperative halt during blocking producer-consumer handoffs; 5 new tests - disc/patch.rs: split Disc::patch body (1168 -> 316 LOC) into named helpers (compute_initial_state, prime_cache, check_range_watchdog, handle_skip_limit, compute_damage_skip, handle_read_success, handle_read_failure, report_patch_progress, build_outcome) with PatchLoopState / RangeFrame structs; references shared PATCH_DAMAGE_THRESHOLD_PCT constant - disc/read_error.rs: add pub const PATCH_DAMAGE_THRESHOLD_PCT = 6; ReadCtx::for_patch() now references the shared constant (was a latent 12 / 6 inconsistency) - tests/passn_handler_ab.rs: 8-profile A/B fixture locking current patch-side recovery behavior (clean / all-medium / alternating / edge-bad-good-middle / single-bad / deep-pit / medium-then-good / batch-fail). Goldens captured pre-unification; will catch any future refactor that breaks the size-aware skip cap.
2026-10-07 18:13:10 +00:00 · 2026-05-13 19:18:51 -07:00 · 2026-05-13 19:15:48 -07:00 · 2026-05-13 14:29:40 -07:00 · 2026-05-13 14:22:24 -07:00 · 2026-05-13 14:09:55 -07:00
71 changed files with 15637 additions and 1906 deletions
@@ -14,6 +14,10 @@ jobs:
        with:
          components: clippy, rustfmt
      - run: cargo fmt --check
+      # libfreemkv is a library — Cargo.lock is gitignored. --locked
+      # would always fail on a fresh runner because there's no committed
+      # lockfile to lock against. The binary crates (freemkv, autorip,
+      # bdemu) track Cargo.lock and DO use --locked.
      - run: cargo clippy -- -D warnings

  test:
@@ -28,6 +28,8 @@ jobs:
    steps:
      - uses: actions/checkout@v5
      - uses: dtolnay/rust-toolchain@1.86.0
+      # libfreemkv is a library — Cargo.lock isn't tracked, so --locked
+      # would always fail (no lockfile to lock against on a fresh runner).
      - run: cargo test

  publish:
@@ -1,5 +1,396 @@
 # Changelog

+## 0.18.4 (2026-05-09)
+
+### Build / CI hardening — no library code changes
+
+- All `cargo` invocations in `.github/workflows/*.yml` now use
+  `--locked`. Previously `cargo build` / `cargo test` could silently
+  re-resolve `Cargo.lock` if a lock-pinned version wasn't yet on
+  crates.io — masking dependency races between same-tag releases of
+  sibling crates. The 0.18.3 release hit this: autorip's docker image
+  built `libfreemkv v0.18.2` because libfreemkv 0.18.3 hadn't
+  published yet at the time autorip's CI ran, and cargo silently fell
+  back to the previous version. With `--locked`, that race now hard-
+  fails the build with a clear "package X is not in registry" error
+  and we retrigger after the upstream lands.
+
+- `cargo publish --locked` in the release workflow guards against
+  publishing a lockfile-mismatched release.
+
+## 0.18.3 (2026-05-09)
+
+### Behaviour change
+
+- **`Disc::titles[0]` is now the canonical main feature on branching
+  discs, not the longest playlist.** Previously titles were sorted
+  purely by `duration_secs` descending, which puts a "play-all"
+  virtual playlist (alternate angles / seamless branching) at index 0
+  on UHDs that ship one — its inflated duration overshoots the real
+  movie. Concrete example: *The Amateur (2025)* 4K UHD on a 58.5 GB
+  disc has Title 1 = `00020.mpls` 4h13m / 92.4 GB / 253 clips
+  (impossible — the size exceeds the disc capacity, proving it's a
+  virtual composite) and Title 2 = `00800.mpls` 2h02m / 57.2 GB /
+  1 clip (the actual film, matching TMDB).
+
+  New sort priority:
+  1. Real titles (`size_bytes <= capacity_bytes`) before virtual
+     composites.
+  2. Among real titles, fewer clips first (1-clip wins).
+  3. Tiebreak on longer duration first.
+
+  **Migration:** consumers calling `disc.titles.first()` /
+  `disc.titles[0]` automatically get the corrected title — no code
+  changes needed. CLI users invoking `freemkv -t 1 disc:// …` now hit
+  the actual main feature on branching discs (this was the user-
+  visible bug). On non-branching discs the order is unchanged.
+
+  The comparator is exposed as
+  [`Disc::canonical_title_order`](#) for callers that need to
+  re-sort a custom title set with the same logic.
+
+  Regression tests: `disc::tests::canonical_order_*` (three cases:
+  branching-UHD, normal disc, clip-count tiebreak).
+
+## 0.18.2 (2026-05-09)
+
+### Bug fixes
+
+- **Nav-file scramble during AACS rip** (`decrypt::decrypt_sectors`). 0.18's
+  `DecryptingSectorSource` decorator broadened the call surface of
+  `decrypt_sectors` to every sector flowing through sweep, including UDF
+  navigation files (MPLS playlists, CLPI clip-info). The byte-0 heuristic
+  in `aacs::is_unit_encrypted` correctly fires on m2ts source-packet copy
+  markers but false-positives on any binary file whose first byte happens
+  to have the top 2 bits set — most notably MPLS files (start with 'M' =
+  0x4D) and CLPI files (start with 'H' = 0x48). `decrypt_unit_full`
+  already self-checks the result via TS-sync verification and returns
+  `false` on a misfire, but the chunk had been mutated by then;
+  `decrypt_sectors` discarded the return value, leaving scrambled bytes
+  in the ISO. Fix: snapshot the chunk before decryption and restore on
+  verification failure (same pattern `decrypt_unit_try_keys` already used
+  for multi-key discs). Symptom: `freemkv info iso://UHD.iso` and
+  `iso:// → mkv://` returned E6009 NoStreams on freshly-ripped UHD ISOs;
+  affected only the iso-source path, not the disc-source path or the
+  m2ts video payload itself. Regression test:
+  `decrypt::tests::nav_file_unit_survives_decrypt_attempt`.
+
+- **Sweep progress display can regress to zero** (`Disc::sweep`). The
+  consumer-side `bytes_good` snapshot lags producer-side `bytes_done`
+  whenever the consumer is behind on draining the work channel. Until
+  the first snapshot arrived, the placeholder branch reported
+  `bytes_done` correctly; once a stale snapshot landed, the report
+  switched to `snap.bytes_good` and could regress below `bytes_done`.
+  Fix: `bytes_good_total = max(snap.bytes_good, bytes_done)`, so the
+  user-visible counter never moves backward.
+
+## 0.18.1 (2026-05-09)
+
+### I/O stack redesign — primitives over orchestration
+
+0.18 reshapes the read/write surface from "library does the multipass dance"
+to "library hands the caller flat verbs and a few composable primitives." All
+in-tree consumers (autorip, the `freemkv` CLI) drove their own multipass
+loops in 0.18 rounds 1-3; 0.18.1 lands the cleanup with the deprecated names
+still alive for one minor-version window.
+
+The 0.18 design notes are in
+`(internal)/memory/0_18_redesign.md` (private) — this entry sticks to
+what changed at the public surface.
+
+#### Flat verbs
+
+`Disc::sweep` is the forward Pass 1. `Disc::patch` is one retry pass over the
+mapfile. Neither knows about pass index, retry budget, or accept-loss policy
+— the caller invokes them in whatever sequence its use case dictates. The
+old multipass-aware `Disc::copy` dispatcher is deprecated and slated for
+deletion in 0.18.2; no in-tree caller still uses it.
+
+#### Trait splits — direction-typed at compile time
+
+- `pes::Stream` (combined read+write) is split into `FrameSource` and
+  `FrameSink`. Calling `read()` on a write-only sink is now a compile error,
+  not the runtime `E9001` (`StreamWriteOnly`) it used to be.
+- `SectorReader` is split into `SectorSource` (read) and `SectorSink`
+  (write). `Drive` impls `SectorSource` only; `FileSectorSource` /
+  `FileSectorSink` replace `FileSectorReader` for ISO-backed I/O.
+- A blanket impl bridges legacy `SectorReader` callers onto the new
+  `SectorSource` so existing code keeps compiling through the deprecation
+  window.
+
+#### New primitives
+
+- `Halt` — one cancellation token (cloneable, `Arc<AtomicBool>` under the
+  hood) replaces the three near-duplicate halt flags scattered through the
+  workspace. Threaded through every long-running loop.
+- `Pipeline<I, R>` + `Sink<I>` — generic producer/consumer primitive in
+  `crate::io`. Replaces the bespoke `disc/sweep_pipeline.rs` and now also
+  drives `Disc::patch` and the autorip mux loop. `DEFAULT_PIPELINE_DEPTH`
+  for streaming reads (`4`); `WRITE_THROUGH_DEPTH` for write-through patch
+  semantics (`1`).
+- `WritebackFile` — was `crate::io::Writer`. The renamed type makes its job
+  explicit: a `File` wrapper that runs continuous `sync_file_range` +
+  `posix_fadvise(DONTNEED)` to keep the kernel dirty-page cache bounded on
+  long sequential writes.
+- `DecryptingSectorSource<S>` — a single decorator wrapping any
+  `SectorSource` to yield plaintext sectors. One audit surface for AACS /
+  CSS / passthrough; the previous two-site decrypt (sweep producer +
+  `DiscStream` demux) is gone.
+
+#### Throughput
+
+The round-2 producer/consumer split is now applied uniformly to sweep,
+patch, and mux. Mux on NFS-staged UHD measured ~16 MB/s sustained on the
+test bed (was ~12 MB/s pre-round-2).
+
+#### Module reorg
+
+- `sector/` and `io/` are now module directories.
+- `disc/sweep.rs`, `disc/patch.rs`, and `disc/mapfile.rs` split out of the
+  monolithic `disc/mod.rs`.
+
+#### Renames (no behavior change)
+
+- `crate::io::Writer` → `crate::io::WritebackFile`.
+- `Apply` → `Flow` (`Sink::apply` return value).
+- `DEFAULT_DEPTH` → `DEFAULT_PIPELINE_DEPTH`.
+- `PatchOpts` → `PatchOptions`.
+
+#### Deprecated (alive in 0.18.1, deletion target 0.18.2)
+
+`Disc::copy`, `pes::Stream`, `SectorReader`, `FileSectorReader`,
+`CopyOptions`, `CopyResult`, `DiscStream::set_halt`. Each compiles with a
+deprecation warning; all in-tree call sites have migrated.
+
+## 0.17.13 (2026-05-09)
+
+### Use `crate::io::Writer` uniformly for all binary file output
+
+0.17.10 introduced the bounded-cache writeback wrapper (`sync_file_range`
+ `posix_fadvise(DONTNEED)` per chunk) and 0.17.11 wired it into
+`Disc::sweep`. The other two big-write paths in the crate were still
+opening raw `std::fs::File` and would have hit the same dirty-page
+burst pathology against slow / network-attached staging.
+
+This release threads `crate::io::Writer` through the remaining sites:
+
+- **`Disc::patch`** (`disc/mod.rs:1981`): the ISO file reopened for
+  Pass-N recovery now wraps in `Writer` before any seek / write.
+  Recovery writes are sparse, but the wrapper costs nothing when
+  there's no chunk crossing — and on heavily-damaged discs it
+  matters as patch accumulates GB of recovered data.
+- **MKV mux output** (`mux/resolve.rs:243`): `BufWriter::with_capacity`
+  now wraps `Writer::new(file)` instead of a raw `File`. UHD MKVs
+  routinely exceed 70 GB of sequential writes; pre-0.17.13 those
+  bursts went straight to the kernel writeback queue.
+- **M2TS mux output** (`mux/resolve.rs:251`): same change for
+  parity with the MKV path — anyone using `m2ts://` URLs gets it
+  too.
+
+No new public surface. `Writer::sync_all()` is called from `Disc::patch`
+and `sweep_pipeline`'s consumer at end of pass; mux exits via Drop on
+the wrapping `BufWriter`, which propagates flush down to `Writer`'s
+final `note_progress` (kernel finishes the in-flight chunk on file
+close — there's no explicit `sync_all` for mux today, same behaviour
+as before).
+
+## 0.17.12 (2026-05-09)
+
+### Mapfile time-batched persistence — unblock NFS staging
+
+Pre-0.17.12 every `Mapfile::record()` wrote the entire mapfile to disk
+via tempfile-create + buffered-write + atomic-rename. On local LVM
+that's effectively free (page cache + microsecond-scale renames). On
+NFS (autorip's intended staging path for centralised media) each
+record() became three RPCs through the unraid user share's shfs-fuse
+layer — measured end-to-end at multiple ms each. With ~170 record()
+calls per second of sustained sweep, the mapfile path alone burned
+multiple seconds of wall time per real-world second of work, dragging
+the rip from ~11 MB/s on local to ~1.5 MB/s on NFS.
+
+Fix: time-batch the persistence inside `Mapfile`.
+
+- `record()` always updates in-memory state and stats (so callers'
+  `stats()` reads stay coherent in the same process).
+- The `write_to_disk()` rename only fires when ≥ `FLUSH_INTERVAL`
+  (1 s) has elapsed since the last persist.
+- New `flush()` method forces an out-of-band persist; called by
+  `sweep_pipeline`'s consumer at end-of-sweep and by `Disc::patch` at
+  end-of-patch, after the file's `sync_all()`.
+- `Drop` impl best-effort flushes so an early-return / unwind doesn't
+  silently lose pending state.
+
+Crash-safety changes from "lose at most one block" to "lose at most
+1 s of recorded progress" — the ISO file's payload bytes are
+unaffected; only the mapfile's authority over which sectors are
+already-good is at risk, and a resume re-reads anything Pass 1 had
+already covered. Acceptable for a 7× throughput recovery on the
+target deployment.
+
+The internal `round_trip_load` test now calls `flush()` before
+`Mapfile::load` to read back what the in-memory state asserts.
+External patch / copy tests are unaffected: `patch` and
+`sweep_pipeline` flush at completion before returning, so any
+`Mapfile::load` at the call-site sees fully persisted state.
+
+## 0.17.11 (2026-05-09)
+
+### Sweep producer/consumer split — overlap drive read with file write
+
+Pre-0.17.11 the sweep loop ran strictly serialised: SCSI read → decrypt
+→ seek + write → mapfile.record → next read. The drive idled for the
+post-read work; throughput capped at the **sum** of both costs. On a
+healthy disc that's ~7-12 ms read + ~5-15 ms write/record per 64 KB
+batch — limiting sustained throughput to ~10-12 MB/s on the test bed
+(BU40N + UHD inner zone), well below the drive's ceiling of ~14-16 MB/s.
+
+This release decouples them with a producer / consumer split:
+
+- **Producer** (caller's thread): owns the `SectorReader`, the entire
+  `read_error` state machine (Retry, Bisect, SkipBlock, JumpAhead,
+  AbortPass), `set_speed` damage-zone transitions, halt check, and
+  decrypt. Hands plaintext bytes to the consumer.
+- **Consumer** (one spawned thread): owns the `crate::io::Writer` and
+  the `Mapfile`. Receives `WorkItem` messages and applies the file
+  write + mapfile record per item.
+- **Channel**: bounded `mpsc::sync_channel(4)` — natural back-pressure
+  via blocking `send` when consumer falls behind.
+
+While the consumer is writing batch N to disk and updating the mapfile,
+the producer is already reading batch N+1 from the drive. Steady-state
+throughput is now bound by the slower of the two pipelines (the drive,
+on a healthy disc) instead of their sum.
+
+Side effects of the refactor:
+
+- **Bisect path now decrypts.** Pre-0.17.11 the bisect inner loop wrote
+  raw cyphertext when `decrypt=true` and a single sector was recovered
+  via single-sector retry — a quiet correctness bug exercised only by
+  the (rare) batch-fail-then-bisect-succeed path on encrypted discs.
+  The new producer-side decrypt covers both the main success path and
+  the bisect inner success path.
+- All `read_error::ReadCtx` state stays single-threaded on the producer
+  (damage window, jump multiplier, consecutive-good count, etc.). No
+  locking added.
+- Mapfile remains single-writer (consumer-only). No locking.
+- Halt-flag responsiveness unchanged: producer breaks the loop on
+  signal, sends `Finish`, consumer drains its ≤4 in-flight items and
+  exits within ~1 batch (~12 ms typical).
+- BU40N + Initio bridge wedge concern unchanged: still one SCSI command
+  in flight, error-path timing identical, no new retry logic.
+
+New module: `src/disc/sweep_pipeline.rs` (`WorkItem`, `ProgressSnapshot`,
+`ConsumerInputs`, `spawn_consumer`, `consumer_loop`, send/recv helpers).
+Public API surface unchanged — `Disc::copy` / `CopyOptions` /
+`CopyResult` look identical to callers.
+
+Patch (Pass N) is **not** affected by this release. Patch is bound by
+drive recovery time (60 s timeouts on bad sectors), not the read↔write
+serialisation; a similar split there would yield negligible benefit.
+
+## 0.17.10 (2026-05-09)
+
+### Bounded-cache writeback for big sequential writes
+
+Pass 1 sweep speed on a healthy disc previously dipped from ~15 MB/s
+to ~1 MB/s every ~30 s on a host with default Linux dirty-page
+settings. Cause: the kernel's `vm.dirty_ratio` (~20 % of RAM) lets
+hundreds of MB of dirty pages accumulate, then bursts a flush at
+99 % disk utilisation that blocks app writes for ~1 s. Confirmed
+empirically on the BU40N test bed: dirty pages grew 112 → 563 MB
+between bursts; lowering `vm.dirty_bytes` to 64 MB at the host
+sysctl level eliminated the dips.
+
+This release ships the equivalent inside libfreemkv so users don't
+need to tune the host kernel:
+
+- New `crate::io::Writer` — drop-in `File` wrapper implementing
+  `Write` + `Seek`. Wraps a per-platform `WritebackPipeline` that on
+  Linux schedules `sync_file_range(WRITE)` + lagging
+  `sync_file_range(WAIT_AFTER)` + `posix_fadvise(DONTNEED)` calls in
+  32 MB chunks, keeping dirty cache bounded at ~64 MB. macOS and
+  Windows ship a no-op stub — their default cache policies don't
+  exhibit the same pathology for our access pattern.
+- Disc::sweep wraps its output `File` in `Writer`. No changes to the
+  loop body — `Writer` forwards `seek`/`write_all` to `File` and
+  drives the pipeline transparently.
+- Module is purpose-built for any large sequential output (sweep,
+  patch, future mux) — they can adopt `crate::io::Writer` with a
+  one-line wrapper and inherit the same behaviour.
+
+## 0.17.7 (2026-05-08)
+
+### Sync release — no functional libfreemkv changes
+
+Version bump to keep the four freemkv crates at unified versioning.
+autorip shipped UI smoothness + audit fixes today (v0.17.6, v0.17.7);
+libfreemkv carries no code changes, but is bumped + republished to
+crates.io so downstream `libfreemkv = "0.17"` consumers stay aligned
+on the latest patch version. See autorip CHANGELOG for the
+user-visible work in this release window.
+
+## 0.17.5 (2026-05-08)
+
+### Pass N recovery — kernel block-device fallback + per-range fixes
+
+Live testing on direct-SATA BU40N + AACS-encrypted UHD disc revealed that
+the v0.17.3 single-shot SCSI READ path matched 0/22 of the small bad-sector
+LBAs that `dd if=/dev/sr0` recovers on the same drive. This release closes
+that gap and fixes several adjacent bugs that were silently capping
+recovery.
+
+- **`/dev/sr0` pread fallback in `Drive::read` (Linux)**: when a SCSI READ
+  via `/dev/sg*` returns Err, fall back to `posix_fadvise(POSIX_FADV_DONTNEED)
+  + pread()` against the corresponding block device. The kernel `sr_mod`
+  driver runs ~5 internal retries per command without the per-attempt
+  error-escalation overhead that userspace SG_IO retries pay, which is the
+  source of dd's recovery advantage. End-to-end byte-verification confirms
+  the fallback path returns real disc data (md5-equivalent to fresh dd from
+  the same drive session). The block fd is opened in `Drive::open` by
+  resolving `/sys/class/scsi_generic/sgN/device/block`; best-effort, with no
+  fallback if open fails.
+
+- **`Disc::patch` per-range watchdog fix**: when a range hit `MAX_RANGE_SECS`,
+  the old code did `wedged_exit = true; break 'outer;` — a single slow range
+  killed the entire patch. Now `break;` (skip this range, advance the outer
+  for loop). Pre-fix, patch was dying after 4 sectors of the first slow
+  range and never reaching the other 46.
+
+- **Per-sector range budget**: replaced flat `MAX_RANGE_SECS = 180` with
+  `range_budget_secs = (range_sectors × SECONDS_PER_SECTOR).min(RANGE_BUDGET_CAP_SECS)`.
+  Tiny ranges exit fast (1-sector range = 25 s); medium ranges get
+  proportional time (51-sector range ≈ 1275 s); large ranges still bounded
+  by the 1800 s cap so they cannot monopolise pass 1.
+
+- **`consecutive_failures` resets per range**: the wedge-exit detector
+  (`>= 50 consecutive failures`) is for "stuck on the same range"; pre-fix
+  the counter persisted across ranges, so 50 small post-bisection ranges
+  with one failure each falsely tripped the wedge mid-pass. Reset at every
+  range boundary.
+
+- **Reverted inline 5× retry in patch**: a brief experiment that was
+  measurably harmful — each "2 s" SCSI timeout paid ~1.5 s kernel SCSI
+  mid-layer error-escalation overhead, so 5× retry took ~17 s per LBA and
+  triggered the per-range watchdog in 4 sectors. Restored
+  `READ_RECOVERY_TIMEOUT_MS = 60_000` (the v0.17.3 baseline; the kernel-
+  auto-retry pattern is now provided by the `/dev/sr0` fallback above).
+
+### Empirical results (Dune Part Two UHD, BU40N direct SATA)
+
+- Pass 1: **94.6 MB recovered** (28% of formerly-bad data, 33 sr0 fallback
+  saves), **11 s of main-title content** restored. Patch completed all 47
+  retryable ranges naturally (was wedging at range 1 of 47 in v0.17.3).
+- Pass 2 cumulative: 95.2 MB (+0.6 MB; diminishing returns curve).
+- Remaining ~233 MB on the test disc appears physically unrecoverable on
+  this hardware (kernel auto-retry can't decode it either).
+
+### Behavioural notes
+
+- The `/dev/sr0` fallback is Linux only; macOS and Windows fall back to
+  the existing single-shot SCSI behaviour. The fallback is gated to
+  `recovery=true` reads (only fires from the patch path, not the sweep
+  path) to avoid page-cache pressure during multi-GB sequential ripping.
+
 ## 0.17.0 (2026-05-04)

 ### Code quality: unwrap safety, clippy compliance, test coverage
@@ -1,6 +1,6 @@
 [package]
 name = "libfreemkv"
-version = "0.17.2"
+version = "0.20.8"
 edition = "2024"
 rust-version = "1.86"
 license = "AGPL-3.0-only"
@@ -1,34 +0,0 @@
-# libfreemkv — Feature List
-
-## v0.10.10 (current)
-
-### Done
- [x] Drive access: open, identify, unlock, firmware upload, speed calibration, eject
- [x] 206 bundled drive profiles (MediaTek MT1959 A + B variants)
- [x] SCSI transport: Linux SG_IO, macOS IOKit, Windows SPTI
- [x] UDF 2.50 filesystem parser (metadata partitions, Blu-ray profile)
- [x] MPLS playlist parser (play items, STN table, secondary streams)
- [x] CLPI clip info parser (EP map, sector extents)
- [x] AACS 1.0 decryption (4 VUK paths: KEYDB, media key, processing key, device key)
- [x] AACS 2.0 SCSI handshake (P-256/SHA-256 ECDH, bus decryption, read data key)
- [x] DVD IFO parser (VMG, VTS, PGC chains, cell addresses)
- [x] DVD CSS decryption (bus auth, disc key via player keys, title key, sector descramble)
- [x] CSS Stevenson plaintext attack for ISO key recovery
- [x] MPEG-2 PS demuxer (DVD Program Stream with PES extraction)
- [x] MPEG-2 video codec parser (sequence header, quantizer matrices, keyframe detection)
- [x] KEYDB.cfg download, verify, save (raw TCP, zero HTTP deps)
- [x] Content reading with adaptive batch sizing, error recovery, 12+ MB/s
- [x] Stream labels: 5 BD-J format parsers (Paramount, Criterion, Pixelogic, CTRM, Deluxe)
- [x] MKV muxer: 14 codec parsers (H.264, HEVC, MPEG-2, AC-3, DTS, TrueHD, PGS, DVD Sub, VC-1, LPCM, +4 more)
- [x] SectorReader trait: decouples disc scanning from SCSI
- [x] 7 stream types: Disc, ISO, MKV, M2TS, Network, Stdio, Null
- [x] PES pipeline with unified Stream trait (any source → any dest)
- [x] FMKV metadata header for M2TS and network streams
- [x] Numeric error codes only (no English text in library)
- [x] Event system for progress callbacks
-
-### Planned
- [ ] Windows testing on real hardware
- [ ] Pioneer Renesas platform support (48 drives, need GET_CONFIG 010C)
- [ ] TranscodeStream (ffmpeg integration)
- [ ] ISO write with BD-compliant UDF structure
@@ -18,7 +18,7 @@ Part of the [freemkv](https://github.com/freemkv) project.

 ```toml
 [dependencies]
-libfreemkv = "0.17"
+libfreemkv = "0.18"
 ```

 ## Quick Start
@@ -53,27 +53,48 @@ output.finish()?;

 ### Multi-pass recovery rip

-For damaged discs, the library offers a two-stage rip model: fast sweep with zero-fill and a ddrescue-format mapfile, then targeted retry of bad ranges. See [`docs/rip-recovery.md`](docs/rip-recovery.md) for the full architecture.
+For damaged discs the library exposes two flat verbs — `Disc::sweep` for the
+forward Pass 1 and `Disc::patch` for retrying bad ranges. The library never
+loops; the multipass policy is the caller's job. See
+[`docs/rip-recovery.md`](docs/rip-recovery.md) and the design notes in
+`(internal)/memory/0_18_redesign.md`.

 ```rust
-use libfreemkv::disc::{CopyOptions, PatchOptions};
+use libfreemkv::{SweepOptions, PatchOptions};
+use libfreemkv::disc::{mapfile, mapfile_path_for};
+use std::path::Path;

-// Pass 1: disc → ISO. Fast 64 KB reads, skip-forward on failure,
-// zero-fill bad blocks, write a sidecar .mapfile.
-let mut result = disc.copy(
-    &mut drive,
-    Path::new("disc.iso"),
-    &CopyOptions { skip_on_error: true, skip_forward: true, ..Default::default() },
-)?;
+let iso = Path::new("disc.iso");

-// Pass 2..N: retry bad ranges with full drive recovery.
-// Idempotent — call as many times as you want.
-while result.bytes_unreadable + result.bytes_pending > 0 {
-    let pr = disc.patch(&mut drive, Path::new("disc.iso"), &PatchOptions::default())?;
-    if pr.bytes_recovered_this_pass == 0 { break; }
+// Pass 1: disc → ISO. Skip-on-error, zero-fill, write the sidecar mapfile.
+disc.sweep(&mut drive, iso, &SweepOptions {
+    decrypt: true,
+    resume: false,
+    batch_sectors: None,
+    skip_on_error: true,
+    progress: None,
+    halt: None,
+})?;
+
+// Pass 2..N: retry every non-finished range. Idempotent.
+loop {
+    let map = mapfile::Mapfile::load(&mapfile_path_for(iso))?;
+    let stats = map.stats();
+    if stats.bytes_pending + stats.bytes_unreadable == 0 { break; }
+
+    let outcome = disc.patch(&mut drive, iso, &PatchOptions {
+        decrypt: true,
+        block_sectors: None,
+        full_recovery: true,
+        reverse: true,
+        wedged_threshold: 50,
+        progress: None,
+        halt: None,
+    })?;
+    if outcome.bytes_recovered_this_pass == 0 { break; }
 }

-// Then mux from the ISO via the normal stream pipeline (no drive involvement).
+// Mux from the ISO via the normal stream pipeline (no drive involvement).
 ```

 ## What It Does
@@ -92,14 +113,14 @@ while result.bytes_unreadable + result.bytes_pending > 0 {
 | Stream | Input | Output | Transport |
 |--------|-------|--------|-----------|
 | DiscStream | Yes | -- | Optical drive via SCSI |
-| IsoStream | Yes | -- | Blu-ray ISO image file (read via stream pipeline; written via `Disc::copy()`) |
+| IsoStream | Yes | -- | Blu-ray ISO image file (read via stream pipeline; written via `Disc::sweep()`) |
 | MkvStream | Yes | Yes | Matroska container |
 | M2tsStream | Yes | Yes | BD transport stream with FMKV metadata header |
 | NetworkStream | Yes (listen) | Yes (connect) | TCP with FMKV metadata header |
 | StdioStream | Yes (stdin) | Yes (stdout) | Raw byte pipe |
 | NullStream | -- | Yes | Discard sink (byte counter for benchmarks) |

-Streams implement `pes::Stream` (frame-level). `input()` / `output()` resolve URL strings to PES stream instances. All URLs use the `scheme://path` format — bare paths are rejected.
+Streams implement `FrameSource` (read) and/or `FrameSink` (write); direction is type-checked. `input()` / `output()` resolve URL strings to PES stream instances. All URLs use the `scheme://path` format — bare paths are rejected.

 AACS decryption requires a KEYDB.cfg file. If available at `~/.config/aacs/KEYDB.cfg` or passed via `ScanOptions`, the library handles everything — handshake, key derivation, and per-sector decryption — without the application needing to know anything about encryption.

@@ -122,7 +143,8 @@ Disc                   — scan titles, streams, AACS/CSS state
  └── KEYDB            — download + verify + save

 Streams                — unified PES pipeline
-  ├── pes::Stream      — read()/write() PES frames
+  ├── FrameSource      — read() PES frames (direction-typed)
+  ├── FrameSink        — write() PES frames (direction-typed)
  ├── DiscStream       — sectors → decrypt → TS demux → PES
  ├── IsoStream        — ISO file → decrypt → TS demux → PES
  ├── MkvStream        — MKV mux/demux
@@ -44,35 +44,30 @@ while let Ok(Some(frame)) = input.read() {
 output.finish()?;
 ```

-The `pes::Stream` trait:
+The `FrameSource` and `FrameSink` traits — direction is type-checked, so
+calling `read()` on a write-only sink (or `write()` on a read-only source)
+is a compile error rather than a runtime fault:

 ```rust
-pub trait Stream {
-    fn read(&mut self) -> io::Result<Option<PesFrame>>;
-    fn write(&mut self, frame: &PesFrame) -> io::Result<()>;
-    fn finish(&mut self) -> io::Result<()>;
+pub trait FrameSource: Send {
+    fn read(&mut self) -> Result<Option<PesFrame>, Error>;
    fn info(&self) -> &DiscTitle;
-    fn codec_private(&self, track: usize) -> Option<Vec<u8>>;
-    fn headers_ready(&self) -> bool;
+    fn codec_private(&self, track: usize) -> Option<Vec<u8>> { None }
+    fn headers_ready(&self) -> bool { true }
 }
-```

-## IOStream (byte-level API)
-
-For raw byte copies (disc→ISO, resume, benchmarks). Lower level than PES.
-
-```rust
-let opts = InputOptions::default();
-let mut input = open_input("iso://Disc.iso", &opts)?;
-let mut output = open_output("mkv://Movie.mkv", input.info())?;
-io::copy(&mut *input, &mut *output)?;
-output.finish()?;
+pub trait FrameSink: Send {
+    fn write(&mut self, frame: &PesFrame) -> Result<(), Error>;
+    fn finish(self: Box<Self>) -> Result<(), Error>;
+    fn info(&self) -> &DiscTitle;
+}
 ```

 ## Streams

-All streams implement `IOStream` (byte-level) and/or `pes::Stream` (frame-level).
-URL-based resolvers open any stream by string.
+All streams implement `FrameSource` (read) and/or `FrameSink` (write); the
+directional split prevents runtime "wrong-direction" errors. URL-based
+resolvers open any stream by string.

 | Stream | Input | Output | URL | Transport |
 |--------|-------|--------|-----|-----------|
@@ -87,21 +82,14 @@ URL-based resolvers open any stream by string.
 All URLs require a `scheme://path` format. Bare paths are rejected.

 ```rust
-// PES pipeline (frame-level)
+// PES pipeline (frame-level) — input() returns Box<dyn FrameSource>,
+// output() returns Box<dyn FrameSink>.
 let input = libfreemkv::input("disc:///dev/sg4", &opts)?;    // DiscStream
 let input = libfreemkv::input("iso://Dune.iso", &opts)?;     // IsoStream
 let output = libfreemkv::output("mkv://Dune.mkv", &title)?;  // MkvOutputStream
 let output = libfreemkv::output("m2ts://Dune.m2ts", &title)?; // M2tsOutputStream
 let output = libfreemkv::output("network://10.0.0.1:9000", &title)?; // NetworkOutputStream
 let output = libfreemkv::output("null://", &title)?;          // NullOutputStream
-
-// IOStream (byte-level)
-let input = open_input("disc://", &opts)?;                    // DiscStream
-let input = open_input("iso://Dune.iso", &opts)?;             // IsoStream
-let output = open_output("iso://Copy.iso", &meta)?;           // IsoStream (write)
-let output = open_output("mkv://Dune.mkv", &meta)?;           // MkvStream
-let output = open_output("m2ts://Dune.m2ts", &meta)?;         // M2tsStream
-let output = open_output("null://", &meta)?;                  // NullStream
 ```

 ### FMKV Metadata Header
@@ -175,20 +163,34 @@ libfreemkv/src/
 ├── lib.rs              Public exports
 ├── error.rs            Error codes (no English)
 ├── event.rs            Event types for callbacks
+├── halt.rs             Halt cancellation token (Arc<AtomicBool> wrapper)
+├── io/                 Pipeline + WritebackFile primitives
+│   ├── mod.rs          Re-exports WritebackFile, Pipeline, Sink, Flow
+│   ├── pipeline.rs     Generic Pipeline<I, R> + Sink trait
+│   ├── writeback_file.rs  WritebackFile (was crate::io::Writer)
+│   └── writeback.rs    sync_file_range pipeline
 ├── drive/              Drive (open, init, single-shot read)
 │   ├── mod.rs          Drive struct, init, read (single-shot), reset, eject
 │   ├── capture.rs      Drive profile capture for contribution
 │   ├── linux.rs        Linux drive discovery
 │   ├── macos.rs        macOS drive discovery
 │   └── windows.rs      Windows drive discovery
-├── disc/               Disc (scan, titles, AACS setup)
+├── disc/               Disc (scan, titles, AACS setup, sweep, patch)
+│   ├── mod.rs          Disc struct, scan, titles, formats
+│   ├── sweep.rs        Disc::sweep (Pass 1 forward sweep)
+│   ├── patch.rs        Disc::patch (Pass N retry over mapfile)
+│   ├── mapfile.rs      ddrescue-format mapfile
+│   └── read_error.rs   ReadCtx / ReadAction state machine
 ├── scsi/               SCSI transport (Linux SG_IO, macOS IOKit, Windows SPTI)
 ├── platform/           Drive unlock (MT1959 A/B)
 ├── aacs/               AACS decryption (handshake, keys, keydb, decrypt)
 ├── css/                DVD CSS cipher
 ├── decrypt.rs          Unified decrypt dispatcher (AACS/CSS/None)
-├── pes.rs              PES frame types, Stream trait
-├── sector.rs           SectorReader trait
+├── pes.rs              PES frame types, FrameSource / FrameSink traits
+├── sector/             Sector I/O (was sector.rs in 0.17)
+│   ├── mod.rs          SectorSource, SectorSink traits
+│   ├── file.rs         FileSectorSource, FileSectorSink (ISO-backed)
+│   └── decrypting.rs   DecryptingSectorSource decorator
 ├── udf.rs              UDF 2.50 filesystem parser
 ├── mpls.rs             MPLS playlist parser
 ├── clpi.rs             CLPI clip info parser
@@ -199,15 +201,15 @@ libfreemkv/src/
 ├── profile.rs          Bundled drive profiles
 ├── speed.rs            DriveSpeed enum
 ├── mux/
-│   ├── mod.rs          IOStream trait, public exports
-│   ├── resolve.rs      URL parser + open_input/open_output + input/output
+│   ├── mod.rs          Public mux exports
+│   ├── resolve.rs      URL parser + input/output (Box<dyn FrameSource/Sink>)
 │   ├── meta.rs         FMKV header format
 │   ├── disc.rs         DiscStream (optical drive → PES)
-│   ├── iso.rs          IsoStream (ISO image read/write)
+│   ├── iso.rs          IsoStream (ISO image read)
 │   ├── isowriter.rs    ISO image writer (UDF, AVDP, multi-extent)
-│   ├── mkvstream.rs    MkvStream (bidirectional Matroska, IOStream)
+│   ├── mkvstream.rs    MkvStream (bidirectional Matroska)
 │   ├── mkvout.rs       MkvOutputStream (PES → MKV)
-│   ├── m2ts.rs         M2tsStream (BD-TS, IOStream)
+│   ├── m2ts.rs         M2tsStream (BD-TS)
 │   ├── pesout.rs       PES output streams (M2ts, Network, Stdio, Null)
 │   ├── network.rs      NetworkStream (TCP + FMKV header)
 │   ├── stdio.rs        StdioStream (stdin/stdout pipe)
@@ -65,8 +65,12 @@ libfreemkv (lib.rs)
 │
 ├── Streaming
 │   ├── mux/          Stream implementations (Disc, ISO, MKV, M2TS, Network, Stdio, Null)
-│   ├── pes           PES frame types, Stream trait (read/write frames)
-│   └── sector        SectorReader trait — abstracts disc vs ISO vs file
+│   ├── pes           PES frame types; FrameSource / FrameSink direction-typed traits
+│   └── sector/       SectorSource / SectorSink traits, FileSector{Source,Sink}, DecryptingSectorSource
+│
+├── I/O Primitives
+│   ├── halt          Halt cancellation token (one Arc<AtomicBool>, cloneable)
+│   └── io/           Pipeline<I, R> + Sink trait + WritebackFile (bounded-cache writer)
 │
 ├── Support
 │   ├── keydb         KEYDB.cfg download, parse, verify, save
@@ -97,7 +97,9 @@ drive.probe_disc()?;
 // Scan disc (UDF + playlists + AACS — all automatic)
 let disc = Disc::scan(&mut drive, &ScanOptions::default())?;

-// Stream pipeline — PES frames from any source to any output
+// Stream pipeline — PES frames from any source to any output.
+// 0.18: input() returns Box<dyn FrameSource>, output() returns Box<dyn FrameSink>;
+// direction is type-checked, so calling .write() on an input is a compile error.
 let opts = InputOptions::default();
 let mut input = libfreemkv::input("disc:///dev/sg4", &opts)?;
 let title = input.info().clone();
@@ -121,11 +123,13 @@ output.finish()?;
 | aacs/ | [aacs.md](aacs.md) | Key resolution + content decrypt + bus handshake |
 | css/ | -- | DVD CSS cipher |
 | decrypt.rs | -- | Unified decrypt dispatcher (AACS/CSS/None) |
-| disc/ | -- | High-level scan + read API |
+| disc/ | [rip-recovery.md](rip-recovery.md) | Disc::scan + Disc::sweep + Disc::patch + mapfile |
 | labels/ | -- | BD-J stream labels (5 format parsers) |
 | mux/ | -- | Stream implementations (7 stream types) |
-| pes.rs | -- | PES frame types + Stream trait |
-| sector.rs | -- | SectorReader trait |
+| pes.rs | -- | PES frame types + FrameSource / FrameSink traits |
+| sector/ | -- | SectorSource / SectorSink + DecryptingSectorSource decorator |
+| io/ | -- | Pipeline<I, R> + Sink trait + WritebackFile |
+| halt.rs | -- | Halt cancellation token |
 | keydb.rs | -- | KEYDB download, parse, save |
 | error.rs | -- | Error codes (E1xxx-E8xxx) |
 | event.rs | -- | Drive event system |
@@ -52,8 +52,8 @@ selects the per-CDB timeout:

 | `recovery` | Timeout  | Used by                                  |
 |------------|----------|------------------------------------------|
-| `false`    | 1.5 s    | `Disc::copy` fast skip-forward sweep, `DiscStream::fill_extents` |
-| `true`     | 30 s     | `Disc::patch` multi-pass over the mapfile |
+| `false`    | 1.5 s    | `Disc::sweep` fast skip-forward pass, `DiscStream::fill_extents` |
+| `true`     | 30 s     | `Disc::patch` retry pass over the mapfile |

 On any SCSI failure or timeout, `read` returns `Err(DiscRead)` immediately.
 There are no inline retries, no SCSI reset, no Phase 1/2/3 escalation.
@@ -12,21 +12,24 @@ reach into the others.

 | Layer | Where it lives | What it does |
 |-------|---------------|--------------|
-| 1 — Bad-range retry | `Disc::patch` (multi-pass over the mapfile) | Re-reads non-`+` ranges with the long timeout. Idempotent; call N times. |
+| 1 — Bad-range retry | `Disc::patch` (one pass over the mapfile per call) | Re-reads non-`+` ranges with the long timeout. Idempotent; caller invokes N times. |
 | 2 — Single-shot primitive | `Drive::read` in `src/drive/mod.rs` | One CDB, one timeout, one result. No inline retries, no SCSI reset. |
 | 3 — In-loop request adaptation | `DiscStream::fill_extents` adaptive batch sizer | Halves the batch on failure, retries at the same LBA, walks back up on a clean-read streak. |

-The caller orchestrates layer 1. Autorip's `rip_disc` loops `copy` then
-N × `patch` per the `MAX_RETRIES` config, then hands the ISO off to the
-existing mux pipeline. Layer 3 runs inside any consumer of `DiscStream`
-(direct PES pipeline, ISO playback, etc.) without caller involvement.
+The library exposes flat verbs; the caller drives the multipass loop. Autorip
+runs `Disc::sweep` once, then loops `Disc::patch` until either the mapfile is
+clean or the configured retry budget is exhausted, then hands the ISO off to
+the mux pipeline. The `freemkv` CLI does the same shape with a
+terminal-output progress sink. Layer 3 runs inside any consumer of
+`DiscStream` (direct PES pipeline, ISO playback, etc.) without caller
+involvement.

 Three primitives compose the disc-side flow:

 | Primitive                 | What it does                                                          |
 |---------------------------|-----------------------------------------------------------------------|
-| `Disc::copy`              | disc → ISO. Writes a sidecar `.mapfile`. Opt-in skip-forward on failure. |
-| `Disc::patch`             | Re-reads bad ranges from the drive. Idempotent; call N times.         |
+| `Disc::sweep`             | disc → ISO, one forward pass. Writes a sidecar `.mapfile`. Opt-in skip-on-error. |
+| `Disc::patch`             | Re-reads bad ranges from the drive. One pass per call; caller invokes N times. |
 | `DiscStream` (ISO source) | Reads sectors from the ISO, feeds decrypt → demux → codec → mux.      |

 ## Data model
@@ -60,28 +63,46 @@ Status characters match ddrescue:

 Position and size are hex byte offsets into the ISO.

-### `CopyOptions` and `PatchOptions`
+### `SweepOptions` and `PatchOptions`

-`Disc::copy()` auto-detects the pass from mapfile state:
+The library no longer dispatches between sweep and patch internally — the
+caller picks the verb explicitly per pass. The two option structs are flat
+and have no overlap:

 ```rust
-CopyOptions {
-    decrypt: true,     // decrypt AACS/CSS sectors
-    multipass: true,   // enable mapfile + skip-on-error + damage-jump
-    progress: Some(&reporter),  // progress callback
-    halt: Some(flag),  // halt flag for graceful stop
+SweepOptions {
+    decrypt: true,
+    resume: false,
+    batch_sectors: None,
+    skip_on_error: true,           // damage-jump + zero-fill on read failure
+    progress: Some(&reporter),
+    halt: Some(flag),
+}
+
+PatchOptions {
+    decrypt: true,
+    block_sectors: None,
+    full_recovery: true,
+    reverse: true,                 // walk bad ranges high → low LBA
+    wedged_threshold: 50,
+    progress: Some(&reporter),
+    halt: Some(flag),
 }
 ```

-Dispatch logic:
- No mapfile → sweep (fresh Pass 1)
- Mapfile with NonTried (`?`) → sweep with resume
- Mapfile covering full disc, only NonTrimmed/NonScraped/Unreadable → patch
- Mapfile clean → no-op
+Caller-orchestrated dispatch (the policy `Disc::copy` used to embed):
+
+- No mapfile → `sweep` (fresh Pass 1).
+- Mapfile with `?` ranges → `sweep` with `resume: true`.
+- Mapfile covers full disc, only `*` / `/` / `-` ranges → `patch`.
+- Mapfile clean → done; no further pass needed.
+
+Each consumer (autorip, `freemkv` CLI) implements the loop in roughly five
+lines of `Mapfile::stats()` checks.

 ## Algorithm

-### Pass 1 — fast sweep (`Disc::copy` → `sweep_internal`)
+### Pass 1 — fast sweep (`Disc::sweep`)

 1. Read one ECC block (32 sectors for UHD, 16 for BD/DVD) at the current LBA.
 2. On success: write data to ISO, mark `+`, advance.
@@ -95,7 +116,7 @@ Dispatch logic:

 Pass 1 completes when every byte has been visited (either `+` or `*`).

-### Pass 2+ — patch (`Disc::copy` → `patch_internal`)
+### Pass 2+ — patch (`Disc::patch`)

 `Disc::patch` reads the mapfile and iterates every non-`+` range. Default: **reverse** mode
 (walks ranges from highest LBA to lowest, within each range from end to start).
@@ -177,4 +198,4 @@ scrape vs. retry with direction reversal) if there's measured benefit.

 - [ddrescue manual, Algorithm chapter](https://www.gnu.org/software/ddrescue/manual/ddrescue_manual.html)
 - [ddrescue optical media notes](https://www.electric-spoon.com/doc/gddrescue/html/Optical-media.html)
- Source: [`src/disc/mapfile.rs`](../src/disc/mapfile.rs), [`src/disc/mod.rs`](../src/disc/mod.rs) (`Disc::copy`, `Disc::patch`), [`src/drive/mod.rs`](../src/drive/mod.rs) (`Drive::read`), [`src/mux/disc.rs`](../src/mux/disc.rs) (`DiscStream::fill_extents`).
+- Source: [`src/disc/mapfile.rs`](../src/disc/mapfile.rs), [`src/disc/sweep.rs`](../src/disc/sweep.rs) (`Disc::sweep`), [`src/disc/patch.rs`](../src/disc/patch.rs) (`Disc::patch`), [`src/drive/mod.rs`](../src/drive/mod.rs) (`Drive::read`), [`src/mux/disc.rs`](../src/mux/disc.rs) (`DiscStream::fill_extents`).
@@ -126,7 +126,7 @@ USB optical drives have ~500ms round-trip latency per SCSI command. Since `read_

 `Disc::scan()` wraps the drive in a `BufferedSectorReader` before reading. On a single-sector read, the buffer prefetches a batch of sectors (sized from the kernel's `max_hw_sectors_kb` for the device) and caches them. Subsequent reads to nearby LBAs return from cache with zero SCSI overhead. After parsing the UDF directory structure, the entire metadata partition is pre-read into the cache, so all ICB lookups during title scanning and encryption resolution are instant.

-The buffer is transparent -- `read_filesystem()`, `read_file()`, and all downstream code still call `read_sectors(lba, 1, buf)` as before. The batching happens inside the `SectorReader` implementation.
+The buffer is transparent -- `read_filesystem()`, `read_file()`, and all downstream code still call `read_sectors(lba, 1, buf)` as before. The batching happens inside the `SectorSource` implementation.

 ### UDF Filename Encoding

@@ -247,6 +247,7 @@ fn validate_processing_key(
 /// Find Verify Media Key Record (type 0x10) in MKB.
 fn mkb_find_mk_dv(mkb: &[u8]) -> Option<[u8; 16]> {
    let mut pos = 0;
+    let mut type10_seen: Vec<(usize, usize)> = Vec::new();
    while pos + 4 <= mkb.len() {
        let rec_type = mkb[pos];
        let rec_len = u32::from_be_bytes([0, mkb[pos + 1], mkb[pos + 2], mkb[pos + 3]]) as usize;
@@ -254,14 +255,32 @@ fn mkb_find_mk_dv(mkb: &[u8]) -> Option<[u8; 16]> {
            break;
        }

+        if rec_type == 0x10 {
+            type10_seen.push((pos, rec_len));
+        }
+
        if rec_type == 0x10 && rec_len >= 20 {
            // mk_dv is at offset 4 (after record header)
            let mut dv = [0u8; 16];
            dv.copy_from_slice(&mkb[pos + 4..pos + 20]);
+            tracing::warn!(
+                target: "freemkv::disc",
+                phase = "mkb_mk_dv_found",
+                pos,
+                rec_len,
+                "mk_dv extracted from MKB"
+            );
            return Some(dv);
        }
        pos += rec_len;
    }
+    tracing::warn!(
+        target: "freemkv::disc",
+        phase = "mkb_mk_dv_not_found",
+        type10_seen = ?type10_seen,
+        scanned_bytes = pos,
+        "no 0x10 record with rec_len>=20 found"
+    );
    None
 }

@@ -628,32 +647,70 @@ pub fn resolve_keys(
        }
    };

+    tracing::warn!(
+        target: "freemkv::disc",
+        phase = "resolve_keys_start",
+        aacs2,
+        bus_encryption,
+        disc_hash = %hash_hex,
+        mkb_present = mkb_data.is_some(),
+        "resolve_keys: starting"
+    );
+
    // Path 1: Look up VUK by disc hash in KEYDB
    if let Some(entry) = keydb.find_disc(&hash_hex) {
+        tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path1_hit_entry", "disc hash found in keydb");
        if let Some(vuk) = entry.vuk {
            return Some(build(vuk, 1));
        }
+        tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path1_no_vuk", "disc hash entry has no VUK");
+    } else {
+        tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path1_miss", "disc hash NOT in keydb");
    }

    // Path 2: Find entry with matching VID → derive VUK from MK + VID
+    let mut path2_mk_did_count = 0usize;
    for entry in keydb.disc_entries.values() {
        if let (Some(mk), Some(did)) = (entry.media_key, entry.disc_id) {
+            path2_mk_did_count += 1;
            if did == *volume_id {
+                tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path2_hit", "MK+VID entry matched volume_id");
                return Some(build(derive_vuk(&mk, volume_id), 2));
            }
        }
    }
+    tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path2_miss", mk_did_entries = path2_mk_did_count, "no MK+VID entry matched volume_id");

    // Path 3: MKB + processing keys → media key → VUK
    if let Some(mkb) = mkb_data {
+        let mk_dv = mkb_find_mk_dv(mkb);
+        let subdiff = mkb_find_subdiff_records(mkb);
+        let cvalues = mkb_find_cvalues(mkb);
+        tracing::warn!(
+            target: "freemkv::disc",
+            phase = "resolve_keys_mkb_records",
+            mk_dv_found = mk_dv.is_some(),
+            subdiff_found = subdiff.is_some(),
+            subdiff_len = subdiff.as_ref().map(|s| s.len()).unwrap_or(0),
+            cvalues_found = cvalues.is_some(),
+            cvalues_len = cvalues.as_ref().map(|c| c.len()).unwrap_or(0),
+            "MKB record scan results"
+        );
+
        if let Some(mk) = derive_media_key_from_pk(mkb, &keydb.processing_keys) {
+            tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path3_hit", "media key derived from processing key");
            return Some(build(derive_vuk(&mk, volume_id), 3));
        }
+        tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path3_miss", pk_count = keydb.processing_keys.len(), "PK derivation failed");

        // Path 4: MKB + device keys → processing key → media key → VUK
        if let Some(mk) = derive_media_key_from_dk(mkb, &keydb.device_keys) {
+            tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path4_hit", "media key derived from device key");
            return Some(build(derive_vuk(&mk, volume_id), 4));
        }
+        tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path4_miss", dk_count = keydb.device_keys.len(), "DK derivation failed");
+    } else {
+        tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_no_mkb", "no MKB data available; paths 3/4 skipped");
    }

    None
@@ -20,6 +20,35 @@ pub struct ClipInfo {
    pub ep_coarse: Vec<EpCoarse>,
    /// Fine EP entries for the primary video stream
    pub ep_fine: Vec<EpFine>,
+    /// Per-stream metadata from the ProgramInfo section (BD spec).
+    /// Cross-validates the MPLS STN view — see `labels/clpi.rs`.
+    /// Empty when program_info is missing or malformed.
+    pub streams: Vec<ClpiStream>,
+}
+
+/// One stream descriptor from the CLPI ProgramInfo / stream_coding_info
+/// table. Mirrors the same fields the MPLS STN table carries — see
+/// `mpls::StreamEntry` for the playlist-side equivalent.
+#[derive(Debug, Clone)]
+#[allow(dead_code)]
+pub struct ClpiStream {
+    /// PID of the stream in the MPEG-TS (matches MPLS).
+    pub pid: u16,
+    /// SCSI/BD coding type byte (0x80 LPCM, 0x83 TrueHD, 0x86 DTS-HD MA,
+    /// 0x90 PG, etc.). See `labels::mpls_universal::coding_type_to_codec_hint`.
+    pub coding_type: u8,
+    /// ISO 639-2 3-char language code. Empty for video streams.
+    pub language: String,
+    /// Audio format byte (1=mono, 3=stereo, 6=5.1, 12=7.1).
+    /// Zero for non-audio streams.
+    pub audio_format: u8,
+    /// Audio sample rate (1=48kHz, 4=96kHz, 5=192kHz). Zero for non-audio.
+    pub audio_rate: u8,
+    /// Video format byte (1=480i, 4=1080i, 5=720p, 6=1080p, 8=2160p).
+    /// Zero for non-video.
+    pub video_format: u8,
+    /// Video rate (1=23.976, 2=24, 3=25, 4=29.97, 6=50, 7=59.94).
+    pub video_rate: u8,
 }

 #[derive(Debug, Clone)]
@@ -128,7 +157,7 @@ pub fn parse(data: &[u8]) -> Result<ClipInfo> {

    // Header offsets
    let _seq_info_start = u32::from_be_bytes([data[8], data[9], data[10], data[11]]) as usize;
-    let _prog_info_start = u32::from_be_bytes([data[12], data[13], data[14], data[15]]) as usize;
+    let prog_info_start = u32::from_be_bytes([data[12], data[13], data[14], data[15]]) as usize;
    let cpi_start = u32::from_be_bytes([data[16], data[17], data[18], data[19]]) as usize;

    // ClipInfo section at offset 40
@@ -139,6 +168,16 @@ pub fn parse(data: &[u8]) -> Result<ClipInfo> {
        0
    };

+    // Parse ProgramInfo (per-stream language + codec). Best-effort:
+    // malformed program_info doesn't fail the parse, just gives an
+    // empty streams list. EP map is unaffected — sector-range lookups
+    // continue to work.
+    let streams = if prog_info_start > 0 && prog_info_start + 6 < data.len() {
+        parse_program_info(&data[prog_info_start..])
+    } else {
+        Vec::new()
+    };
+
    // Parse CPI / EP Map
    let (ep_coarse, ep_fine) = if cpi_start > 0 && cpi_start + 8 < data.len() {
        parse_cpi(&data[cpi_start..])?
@@ -151,9 +190,127 @@ pub fn parse(data: &[u8]) -> Result<ClipInfo> {
        source_packet_count,
        ep_coarse,
        ep_fine,
+        streams,
    })
 }

+/// Parse the ProgramInfo section: per-stream (pid, coding_type,
+/// language, codec sub-fields). Layout per BD spec / libbluray
+/// clpi_parse.c:
+///
+/// ```text
+/// ProgramInfo:
+///   length: 4 bytes
+///   reserved: 1 byte
+///   num_programs: 1 byte
+///   for each program:
+///     spn_program_sequence_start: 4 bytes
+///     program_map_pid: 2 bytes
+///     num_streams: 1 byte
+///     num_groups: 1 byte
+///     for each stream:
+///       pid: 2 bytes
+///       stream_coding_info_length: 1 byte
+///       stream_coding_info: (varies by coding_type)
+///         coding_type: 1 byte
+///         per-type bytes (see match arms below)
+/// ```
+///
+/// Returns `Vec::new()` on any structural mismatch — we don't propagate
+/// errors because the EP map is the primary CLPI output, and a corrupt
+/// program_info shouldn't break sector-range lookups.
+fn parse_program_info(data: &[u8]) -> Vec<ClpiStream> {
+    let mut out = Vec::new();
+    if data.len() < 6 {
+        return out;
+    }
+    // length: 4 bytes (skipped — we trust the section bounds in the
+    // caller's slice and read the bytes that follow). Reserved 1 byte
+    // at offset 4. num_programs at offset 5.
+    let num_programs = data[5] as usize;
+    let mut pos = 6usize;
+    for _ in 0..num_programs {
+        // Program header: 4 (spn) + 2 (pmt_pid) + 1 (num_streams) + 1 (num_groups) = 8 bytes
+        if pos + 8 > data.len() {
+            return out;
+        }
+        let num_streams = data[pos + 6] as usize;
+        pos += 8;
+
+        for _ in 0..num_streams {
+            // Stream header: 2 (pid) + 1 (sci_length) + sci bytes
+            if pos + 3 > data.len() {
+                return out;
+            }
+            let pid = u16::from_be_bytes([data[pos], data[pos + 1]]);
+            let sci_len = data[pos + 2] as usize;
+            let sci_end = pos + 3 + sci_len;
+            if sci_end > data.len() || sci_len < 1 {
+                return out;
+            }
+            let sci = &data[pos + 3..sci_end];
+            let coding_type = sci[0];
+
+            let mut audio_format = 0u8;
+            let mut audio_rate = 0u8;
+            let mut video_format = 0u8;
+            let mut video_rate = 0u8;
+            let mut language = String::new();
+
+            match coding_type {
+                // Video — MPEG-2 (0x02), H.264 (0x1B), HEVC (0x24)
+                0x02 | 0x1B | 0x24 => {
+                    if sci.len() >= 2 {
+                        video_format = (sci[1] >> 4) & 0x0F;
+                        video_rate = sci[1] & 0x0F;
+                    }
+                }
+                // Primary audio — LPCM(0x80), AC-3(0x81), DTS(0x82),
+                // TrueHD(0x83), AC-3+(0x84), DTS-HD(0x85), DTS-HD MA(0x86)
+                0x80..=0x86 => {
+                    if sci.len() >= 2 {
+                        audio_format = (sci[1] >> 4) & 0x0F;
+                        audio_rate = sci[1] & 0x0F;
+                    }
+                    if sci.len() >= 5 {
+                        language = String::from_utf8_lossy(&sci[2..5]).to_string();
+                    }
+                }
+                // Secondary audio (0xA1 AC-3+, 0xA2 DTS-HD)
+                0xA1 | 0xA2 => {
+                    if sci.len() >= 2 {
+                        audio_format = (sci[1] >> 4) & 0x0F;
+                        audio_rate = sci[1] & 0x0F;
+                    }
+                    if sci.len() >= 5 {
+                        language = String::from_utf8_lossy(&sci[2..5]).to_string();
+                    }
+                }
+                // PG (0x90), IG (0x91): coding_type + 3-byte language [+ char_code for PG]
+                0x90 | 0x91 => {
+                    if sci.len() >= 4 {
+                        language = String::from_utf8_lossy(&sci[1..4]).to_string();
+                    }
+                }
+                _ => {}
+            }
+
+            out.push(ClpiStream {
+                pid,
+                coding_type,
+                language,
+                audio_format,
+                audio_rate,
+                video_format,
+                video_rate,
+            });
+
+            pos = sci_end;
+        }
+    }
+    out
+}
+
 /// Parse the CPI section containing the EP map.
 fn parse_cpi(data: &[u8]) -> Result<(Vec<EpCoarse>, Vec<EpFine>)> {
    if data.len() < 8 {
@@ -16,7 +16,7 @@ pub mod lfsr;
 pub(crate) mod tables;

 use crate::disc::Extent;
-use crate::sector::SectorReader;
+use crate::sector::SectorSource;

 /// CSS decryption state for a DVD title.
 #[derive(Debug, Clone)]
@@ -34,7 +34,7 @@ pub struct CssState {
 /// 0x80 (start of the encrypted region). This only happens when a new PES
 /// packet begins at exactly sector offset 128. We scan up to 50000
 /// scrambled sectors sequentially across all extents.
-pub fn crack_key(reader: &mut dyn SectorReader, extents: &[Extent]) -> Option<CssState> {
+pub fn crack_key(reader: &mut dyn SectorSource, extents: &[Extent]) -> Option<CssState> {
    let mut tried = 0u32;
    let max_tries = 50_000;

@@ -62,7 +62,23 @@ pub fn decrypt_sectors(

            for chunk in buf.chunks_mut(unit_len) {
                if chunk.len() == unit_len && aacs::is_unit_encrypted(chunk) {
-                    aacs::decrypt_unit_full(chunk, &uk, rdk);
+                    // `is_unit_encrypted` is a byte-0 heuristic: it fires on any
+                    // unit whose first byte has the top 2 bits set, which is
+                    // correct for m2ts source packets (where those bits are the
+                    // copy-control marker) but false-positives on any other binary
+                    // data with similarly-shaped first bytes — notably MPLS/CLPI
+                    // navigation files that begin with ASCII magic ('M', 'H'…)
+                    // and survive sweep mixed in with encrypted m2ts payloads.
+                    // `decrypt_unit_full` self-checks via TS-sync verification and
+                    // returns false on a misfire, but it has already mutated the
+                    // chunk by then. Snapshot and restore on verification failure
+                    // — same pattern `decrypt_unit_try_keys` uses for multi-key
+                    // discs. Real m2ts units verify and stay decrypted; nav-file
+                    // sectors get scrambled briefly and then put back as-was.
+                    let original: Vec<u8> = chunk.to_vec();
+                    if !aacs::decrypt_unit_full(chunk, &uk, rdk) {
+                        chunk.copy_from_slice(&original);
+                    }
                }
            }
        }
@@ -74,3 +90,36 @@ pub fn decrypt_sectors(
    }
    Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Regression for the 0.18.1 nav-file scramble bug. A non-m2ts unit whose
+    /// first byte has the top 2 bits set (here: the ASCII letter 'M' that
+    /// MPLS files start with, 0x4D = 0b01001101) trips `is_unit_encrypted`,
+    /// gets AES-decrypted with the unit key, fails the TS-sync verification,
+    /// and must be restored to its original bytes — not left scrambled.
+    #[test]
+    fn nav_file_unit_survives_decrypt_attempt() {
+        let mut unit = vec![0u8; aacs::ALIGNED_UNIT_LEN];
+        unit[0] = b'M';
+        unit[1] = b'P';
+        unit[2] = b'L';
+        unit[3] = b'S';
+        for (i, b) in unit.iter_mut().enumerate().skip(4) {
+            *b = (i as u8).wrapping_mul(31);
+        }
+        let snapshot = unit.clone();
+
+        let keys = DecryptKeys::Aacs {
+            unit_keys: vec![(0, [0xAB; 16])],
+            read_data_key: None,
+        };
+        decrypt_sectors(&mut unit, &keys, 0).unwrap();
+        assert_eq!(
+            unit, snapshot,
+            "non-m2ts unit must be restored after failed decrypt"
+        );
+    }
+}
@@ -3,13 +3,13 @@
 use super::*;
 use crate::clpi;
 use crate::mpls;
-use crate::sector::SectorReader;
+use crate::sector::SectorSource;
 use crate::udf;

 impl Disc {
    /// Scan Blu-ray titles from MPLS playlists.
    pub(super) fn scan_bluray_titles(
-        reader: &mut dyn SectorReader,
+        reader: &mut dyn SectorSource,
        udf_fs: &udf::UdfFs,
    ) -> Vec<DiscTitle> {
        let mut titles = Vec::new();
@@ -31,7 +31,7 @@ impl Disc {
    }

    pub(super) fn parse_playlist(
-        reader: &mut dyn SectorReader,
+        reader: &mut dyn SectorSource,
        udf_fs: &udf::UdfFs,
        filename: &str,
        data: &[u8],
@@ -199,7 +199,7 @@ impl Disc {
    /// Prefers English, falls back to first available language.
    /// Returns None if META directory is empty or XML has no usable title.
    pub(super) fn read_meta_title(
-        reader: &mut dyn SectorReader,
+        reader: &mut dyn SectorSource,
        udf_fs: &udf::UdfFs,
    ) -> Option<String> {
        let meta_dir = udf_fs.find_dir("/BDMV/META")?;
@@ -2,13 +2,13 @@

 use super::*;
 use crate::ifo;
-use crate::sector::SectorReader;
+use crate::sector::SectorSource;
 use crate::udf;

 impl Disc {
    /// Scan DVD titles from IFO files (VIDEO_TS.IFO + VTS_XX_0.IFO).
    pub(super) fn scan_dvd_titles(
-        reader: &mut dyn SectorReader,
+        reader: &mut dyn SectorSource,
        udf_fs: &udf::UdfFs,
    ) -> Vec<DiscTitle> {
        let dvd_info = match ifo::parse_vmg(reader, udf_fs) {
@@ -2,7 +2,7 @@

 use super::*;
 use crate::error::{Error, Result};
-use crate::sector::SectorReader;
+use crate::sector::SectorSource;
 use crate::udf;

 /// Result of SCSI AACS handshake (ECDH authentication).
@@ -22,42 +22,103 @@ impl Disc {
    ) -> Option<HandshakeResult> {
        use crate::aacs::{self, KeyDb};

-        let keydb_path = opts.resolve_keydb()?;
-        let keydb = KeyDb::load(&keydb_path).ok()?;
+        tracing::warn!(
+            target: "freemkv::disc",
+            phase = "handshake_entry",
+            "do_handshake entered"
+        );
+        let keydb_path = match opts.resolve_keydb() {
+            Some(p) => p,
+            None => {
+                tracing::warn!(
+                    target: "freemkv::disc",
+                    phase = "handshake_no_keydb",
+                    "no KEYDB found in search paths; handshake skipped"
+                );
+                return None;
+            }
+        };
+        let keydb = match KeyDb::load(&keydb_path) {
+            Ok(db) => db,
+            Err(e) => {
+                tracing::warn!(
+                    target: "freemkv::disc",
+                    phase = "handshake_keydb_load_failed",
+                    io_error_kind = ?e.kind(),
+                    keydb = %keydb_path.display(),
+                    "KEYDB load failed; handshake skipped"
+                );
+                return None;
+            }
+        };
+
+        let host_cert_count = keydb.host_certs.len();
+        tracing::warn!(
+            target: "freemkv::disc",
+            phase = "handshake_start",
+            host_cert_count,
+            keydb = %keydb_path.display(),
+            "handshake starting"
+        );

        const MAX_CERT_ATTEMPTS: usize = 16;
-        for hc in keydb.host_certs.iter().take(MAX_CERT_ATTEMPTS) {
+        let mut last_err_code: Option<u16> = None;
+        for (idx, hc) in keydb.host_certs.iter().take(MAX_CERT_ATTEMPTS).enumerate() {
            match aacs::handshake::aacs_authenticate(session, &hc.private_key, &hc.certificate) {
                Ok(mut auth) => {
                    let volume_id = match aacs::handshake::read_volume_id(session, &mut auth) {
                        Ok(vid) => vid,
-                        Err(_) => return None, // handshake succeeded but can't read VID
+                        Err(e) => {
+                            tracing::warn!(
+                                target: "freemkv::disc",
+                                phase = "handshake_vid_read_failed",
+                                cert_index = idx,
+                                error_code = e.code(),
+                                "auth ok but volume ID read failed"
+                            );
+                            return None;
+                        }
                    };
                    let read_data_key = aacs::handshake::read_data_keys(session, &mut auth)
                        .ok()
                        .map(|(rdk, _)| rdk);
+                    tracing::debug!(
+                        target: "freemkv::disc",
+                        phase = "handshake_ok",
+                        cert_index = idx,
+                        has_read_data_key = read_data_key.is_some(),
+                    );
                    return Some(HandshakeResult {
                        volume_id,
                        read_data_key,
                    });
                }
-                Err(_) => {
+                Err(e) => {
+                    last_err_code = Some(e.code());
                    continue;
                }
            }
        }
+        tracing::warn!(
+            target: "freemkv::disc",
+            phase = "handshake_all_certs_failed",
+            host_cert_count,
+            tried = host_cert_count.min(MAX_CERT_ATTEMPTS),
+            last_error_code = last_err_code,
+            "all host certs in KEYDB rejected by drive"
+        );
        // All host certs failed — return None, not a fake success
        None
    }

    /// Resolve disc encryption — AACS 1.0, AACS 2.0, CSS, or none.
    ///
-    /// Reads AACS files from UDF (via SectorReader), resolves keys through
+    /// Reads AACS files from UDF (via SectorSource), resolves keys through
    /// whatever path works: KEYDB VUK lookup, media key derivation, processing
    /// keys, device keys. Uses handshake result (volume ID, bus key) if available.
    pub(super) fn resolve_encryption(
        udf_fs: &udf::UdfFs,
-        reader: &mut dyn SectorReader,
+        reader: &mut dyn SectorSource,
        keydb_path: &std::path::Path,
        handshake: Option<&HandshakeResult>,
    ) -> Result<AacsState> {
@@ -73,6 +134,19 @@ impl Disc {
            .or_else(|_| udf_fs.read_file(reader, "/AACS/DUPLICATE/Unit_Key_RO.inf"))
            .map_err(|_| Error::AacsNoKeys)?;

+        // Log the disc hash so we can confirm whether it's present in KEYDB
+        // when key resolution fails. The disc hash is SHA-1 of the full
+        // Unit_Key_RO.inf file bytes — same value KEYDB.cfg keys VUK entries by.
+        let dh = crate::aacs::disc_hash(&uk_ro_data);
+        let dh_hex = crate::aacs::disc_hash_hex(&dh);
+        tracing::warn!(
+            target: "freemkv::disc",
+            phase = "scan_aacs_disc_hash",
+            disc_hash = %dh_hex,
+            uk_ro_len = uk_ro_data.len(),
+            "disc hash computed (compare with keydb.cfg entries)"
+        );
+
        let cc_data = udf_fs
            .read_file(reader, "/AACS/Content000.cer")
            .or_else(|_| udf_fs.read_file(reader, "/AACS/Content001.cer"))
@@ -84,6 +158,28 @@ impl Disc {
            .ok();
        let mkb_ver = mkb_data.as_deref().and_then(aacs::mkb_version);

+        let mkb_first_64_hex = mkb_data
+            .as_deref()
+            .map(|m| {
+                m.iter()
+                    .take(64)
+                    .map(|b| format!("{b:02x}"))
+                    .collect::<String>()
+            })
+            .unwrap_or_default();
+        tracing::warn!(
+            target: "freemkv::disc",
+            phase = "scan_aacs_mkb_info",
+            mkb_present = mkb_data.is_some(),
+            mkb_len = mkb_data.as_deref().map(|m| m.len()).unwrap_or(0),
+            mkb_version = ?mkb_ver,
+            mkb_first_64 = %mkb_first_64_hex,
+            keydb_disc_count = keydb.disc_entries.len(),
+            keydb_dk_count = keydb.device_keys.len(),
+            keydb_pk_count = keydb.processing_keys.len(),
+            "AACS resolution inputs"
+        );
+
        // Use handshake volume ID if available, otherwise zeros
        // (KEYDB VUK lookup by disc hash works without volume ID)
        let volume_id = handshake.map(|h| h.volume_id).unwrap_or([0u8; 16]);
@@ -17,11 +17,22 @@
 //!
 //! Status chars: `?` non-tried · `*` non-trimmed · `/` non-scraped · `-` unreadable · `+` finished.
 //!
-//! The mapfile is flushed to disk on every `record()` call so a crashed
-//! rip loses at most one block of recorded state.
+//! The mapfile is flushed to disk at most once per `FLUSH_INTERVAL`
+//! during `record()` calls, plus on explicit `flush()` and on `Drop`.
+//! This bounds atomic-rename RPC rate on networked staging (e.g. NFS)
+//! where per-record persists otherwise serialize the rip pipeline.

 use std::io::{self, Write};
 use std::path::{Path, PathBuf};
+use std::time::{Duration, Instant};
+
+/// Minimum interval between mapfile persists. `record()` updates in-memory
+/// state every call but only writes to disk when this interval has elapsed
+/// since the last persist (or when `flush()` is called explicitly, or on
+/// `Drop`). Bounds RPC rate on NFS staging where atomic-rename per record
+/// otherwise dominates throughput. On crash the worst-case progress loss
+/// is one interval's worth of records.
+const FLUSH_INTERVAL: Duration = Duration::from_millis(1000);

 /// Status of a byte range in the mapfile. ddrescue-compatible.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -100,8 +111,11 @@ pub struct MapStats {
    pub main_lost_ms: f64,
 }

-/// Write-through mapfile. Every `record()` persists to disk immediately
-/// so a crash during rip loses at most one block.
+/// Time-batched mapfile. `record()` keeps in-memory state up-to-date on
+/// every call; persists to disk at most once per `FLUSH_INTERVAL`.
+/// Explicit `flush()` and `Drop` guarantee state is on disk after a sweep
+/// or patch finishes. On hard crash the worst-case loss is one flush
+/// interval of records — the file's payload bytes are unaffected.
 pub struct Mapfile {
    path: PathBuf,
    entries: Vec<MapEntry>,
@@ -110,6 +124,12 @@ pub struct Mapfile {
    /// Incrementally maintained stats — updated on every `record()` call
    /// so `stats()` is O(1) instead of O(n).
    stats: MapStats,
+    /// True when in-memory state has changed but `write_to_disk` has not
+    /// yet captured it.
+    dirty: bool,
+    /// Wall-clock timestamp of the last successful `write_to_disk` (or
+    /// the moment the mapfile was constructed, whichever is later).
+    last_flushed: Instant,
 }

 impl Mapfile {
@@ -117,7 +137,7 @@ impl Mapfile {
    /// Writes to disk immediately so a resume can pick up even if the caller
    /// never records anything.
    pub fn create(path: &Path, total_size: u64, version: &str) -> io::Result<Self> {
-        let mf = Self {
+        let mut mf = Self {
            path: path.to_path_buf(),
            entries: vec![MapEntry {
                pos: 0,
@@ -132,8 +152,13 @@ impl Mapfile {
                bytes_nontried: total_size,
                ..Default::default()
            },
+            dirty: false,
+            last_flushed: Instant::now(),
        };
+        // Eager initial persist so a resume can pick this up even if
+        // `record()` is never called.
        mf.write_to_disk()?;
+        mf.last_flushed = Instant::now();
        Ok(mf)
    }

@@ -200,6 +225,8 @@ impl Mapfile {
            total_size,
            version,
            stats,
+            dirty: false,
+            last_flushed: Instant::now(),
        })
    }

@@ -268,7 +295,24 @@ impl Mapfile {
        // path during sweep/patch, it just returns the cached value.
        self.stats = Self::compute_stats(&merged, self.total_size);
        self.entries = merged;
-        self.write_to_disk()?;
+        self.dirty = true;
+        if self.last_flushed.elapsed() >= FLUSH_INTERVAL {
+            self.write_to_disk()?;
+            self.dirty = false;
+            self.last_flushed = Instant::now();
+        }
+        Ok(())
+    }
+
+    /// Persist any pending in-memory changes to disk. No-op if clean.
+    /// Callers (sweep/patch finalisation) invoke this after their last
+    /// `record()` to guarantee state is durable before returning.
+    pub fn flush(&mut self) -> io::Result<()> {
+        if self.dirty {
+            self.write_to_disk()?;
+            self.dirty = false;
+            self.last_flushed = Instant::now();
+        }
        Ok(())
    }

@@ -363,6 +407,16 @@ impl Mapfile {
    }
 }

+impl Drop for Mapfile {
+    /// Best-effort flush on drop so a sweep / patch that returns early
+    /// (or unwinds) doesn't lose its in-memory state. Errors here are
+    /// swallowed because Drop has no way to surface them; explicit
+    /// `flush()` on the success path gives callers proper error handling.
+    fn drop(&mut self) {
+        let _ = self.flush();
+    }
+}
+
 fn parse_hex(s: &str) -> io::Result<u64> {
    let s = s.strip_prefix("0x").unwrap_or(s);
    u64::from_str_radix(s, 16).map_err(|_| {
@@ -463,6 +517,8 @@ mod tests {
        let mut mf = Mapfile::create(&p, 1000, "test").unwrap();
        mf.record(100, 200, SectorStatus::Finished).unwrap();
        mf.record(500, 100, SectorStatus::Unreadable).unwrap();
+        // record() batches; explicit flush before reading back from disk.
+        mf.flush().unwrap();
        let loaded = Mapfile::load(&p).unwrap();
        assert_eq!(loaded.entries(), mf.entries());
        let _ = std::fs::remove_file(&p);
@@ -25,11 +25,25 @@ pub struct ReadCtx {
    /// Failed reads since the last success. Resets to 0 on success.
    /// Drives long-pause escalation on persistent failure.
    pub consecutive_failures: u64,
+    /// Failed OUTER batch reads since the last outer success — bisect
+    /// inner-sector failures are NOT counted here. Drives the
+    /// fast-entry damage-jump on Pass 1 (skip the disc-level grind
+    /// once we're clearly in a damaged region; Pass N will recover
+    /// the actual sectors). Reset on outer success.
+    pub consecutive_outer_failures: u64,
    /// Sliding window of recent read outcomes (true=ok, false=fail).
    /// Capped at `damage_window_max`. Drives damage-jump decisions.
    pub damage_window: Vec<bool>,
    pub damage_window_max: usize,
    pub damage_threshold_pct: usize,
+    /// Trigger a damage-jump after this many consecutive outer-batch
+    /// failures, even when the damage_window isn't full yet. Pass 1
+    /// uses a small value (4) so we don't spend ~40 minutes grinding
+    /// to fill a 16-block window before the first jump on a damage
+    /// zone we entered cleanly. Pass N uses a larger value (or
+    /// disables this — see `bisect_on_marginal`) because Pass N's
+    /// whole job IS to grind on the bad ranges.
+    pub fast_jump_threshold: u64,
    /// Multiplier applied to damage-jump distance. Doubles each jump,
    /// resets to 1 after `damage_window_max` consecutive good reads.
    pub jump_multiplier: u64,
@@ -43,38 +57,177 @@ pub struct ReadCtx {
    /// failed batch, so the handler doesn't recursively request another
    /// bisect on the inner-sector failures.
    pub bisecting: bool,
+    /// Whether to return `Bisect` on a marginal-media batch failure.
+    /// Pass 1 sweep sets this false: a failed batch becomes
+    /// SkipBlock (mark the whole 32-sector ECC block NonTrimmed,
+    /// advance, let Pass N recover the salvageable sectors with
+    /// proper recovery semantics). Pass N sets this true: bisection
+    /// is its core job, and it has the right tools (single-sector
+    /// reads, 60s recovery timeout, retry budget, escalating skip).
+    pub bisect_on_marginal: bool,
+    /// Count of consecutive firmware-wedge responses (HARDWARE_ERROR
+    /// or ILLEGAL_REQUEST sense keys) since the last successful read.
+    /// Pass 1 uses this to drive the wedge-skip path: each wedge
+    /// triggers a 1 GB jump + cooldown pause. Reaching
+    /// `WEDGE_ABORT_THRESHOLD` consecutive wedges with no good read
+    /// in between → real AbortPass.
+    pub wedge_count: u64,
+    // ── Diagnostic counters (added 2026-05-10) ──
+    //
+    // Aggregate state for post-mortem analysis of wedge incidents.
+    // Every Pass 1 / Pass N sweep now produces a structured summary
+    // at the WARN log on each error AND an end-of-pass INFO summary.
+    // Goal: when a wedge happens, the operator should be able to tell
+    // from the logs whether it was triggered by ONE read at a
+    // physically-damaged sector (immediate failure) or by accumulated
+    // exposure across MANY reads (firmware-state buildup), and what
+    // the timing pattern looked like.
+    /// `Instant` of the most recent successful read. Used to compute
+    /// "time since last good" for the WARN log on each error. None
+    /// before the first successful read.
+    pub last_success_at: Option<std::time::Instant>,
+    /// `Instant` of the most recent failed read. Used to compute
+    /// "time since last error" for the WARN log. None before the
+    /// first error.
+    pub last_error_at: Option<std::time::Instant>,
+    /// Last error's sense-key "family" (Medium / Hardware / IllegalRequest
+    /// / NotReady / Other). Used to detect WEDGE TRANSITIONS — when
+    /// the family changes from Medium → Hardware/IllegalRequest, the
+    /// drive almost certainly just entered fast-fail mode. That
+    /// transition gets its own WARN log so the trace is unambiguous.
+    pub last_error_family: Option<SenseFamily>,
+    /// Sum of all errors observed during this sweep. Reported in the
+    /// end-of-pass summary.
+    pub total_errors: u64,
+    /// Sum of all successful reads during this sweep.
+    pub total_reads_ok: u64,
+    /// Count of damage zones entered (transitions from clean → in-damage).
+    pub zones_entered: u64,
+    /// Count of damage-jumps executed during this sweep.
+    pub jumps_taken: u64,
+    /// True between "first error after a clean period" and "16 consecutive
+    /// good reads after the last error in the cluster." Used to count
+    /// zone entries and to bound zone_reads accurately.
+    pub in_damage_zone: bool,
+}
+
+/// Coarse classification of a SCSI sense key for diagnostic logging.
+/// Wedge-family events (Hardware + IllegalRequest) get their own
+/// transition log when the sense family changes.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SenseFamily {
+    NotReady,
+    Medium,
+    Hardware,
+    IllegalRequest,
+    Other,
+}
+
+impl SenseFamily {
+    pub fn from_sense_key(sense_key: u8) -> Self {
+        match sense_key {
+            scsi::SENSE_KEY_NOT_READY => SenseFamily::NotReady,
+            scsi::SENSE_KEY_MEDIUM_ERROR => SenseFamily::Medium,
+            scsi::SENSE_KEY_HARDWARE_ERROR => SenseFamily::Hardware,
+            scsi::SENSE_KEY_ILLEGAL_REQUEST => SenseFamily::IllegalRequest,
+            _ => SenseFamily::Other,
+        }
+    }
+
+    /// True for the "wedge family" — Hardware + IllegalRequest are
+    /// the senses the BU40N firmware returns in its fast-fail state.
+    pub fn is_wedge_family(self) -> bool {
+        matches!(self, SenseFamily::Hardware | SenseFamily::IllegalRequest)
+    }
 }

 impl ReadCtx {
-    /// Initial context for a Pass 1 sweep with the documented constants.
+    /// Initial context for a Pass 1 sweep. The job is "fast and
+    /// accurate, get the most data in the shortest time" — Pass N
+    /// is the one that grinds on the bad ranges. So bisect-on-
+    /// marginal is OFF (failed batches become SkipBlock; whole 32-
+    /// sector blocks marked NonTrimmed for Pass N to revisit), and
+    /// the damage-jump fast-path triggers after just 1 consecutive
+    /// outer-batch failure — the user's wedge-prevention principle
+    /// (2026-05-11): once the drive returns ANY recoverable error,
+    /// retrying the same LBA quickly is what triggers the firmware
+    /// fast-fail transition. Jump immediately, never retry in Pass 1.
+    /// Pass N owns retries — it gets per-sector timeouts that don't
+    /// hammer the firmware the same way.
    pub fn for_sweep(batch: u16) -> Self {
        Self {
            batch,
            consecutive_good: 0,
            consecutive_failures: 0,
+            consecutive_outer_failures: 0,
            damage_window: Vec::with_capacity(16),
            damage_window_max: 16,
            damage_threshold_pct: 12,
+            fast_jump_threshold: 1,
            jump_multiplier: 1,
            not_ready_retries: 0,
            bridge_degradation_count: 0,
            bisecting: false,
+            bisect_on_marginal: false,
+            wedge_count: 0,
+            last_success_at: None,
+            last_error_at: None,
+            last_error_family: None,
+            total_errors: 0,
+            total_reads_ok: 0,
+            zones_entered: 0,
+            jumps_taken: 0,
+            in_damage_zone: false,
        }
    }

-    /// Initial context for a Pass 2-N patch.
+    /// Initial context for a Pass 2-N patch. Pass N's whole reason to
+    /// exist is to recover sectors Pass 1 skipped — bisection on
+    /// marginal media is part of the job, and the fast-jump
+    /// threshold is loose so we don't bail too early on a range that
+    /// has scattered good sectors mixed in.
+    ///
+    /// `damage_threshold_pct = 6` mirrors `disc/patch.rs`'s
+    /// `PASSN_DAMAGE_THRESHOLD_PCT`. Pass N triggers the damage-skip
+    /// at half the density Pass 1 uses (Pass 1 = 12%) because the
+    /// patch loop's whole job is to chip away at bad ranges — being
+    /// more eager to skip clustered bad sectors converges faster on
+    /// the recoverable good sectors inside a range. The patch-side
+    /// `compute_damage_skip` reads its threshold from
+    /// `PASSN_DAMAGE_THRESHOLD_PCT`; keep the two in sync until the
+    /// patch loop's damage-skip is unified with `handle_read_error`'s
+    /// jump path. (v0.20.8 unification attempt found the unification
+    /// itself blocked on the size-aware `range_remaining/4` cap that
+    /// lives in `compute_damage_skip` but not in
+    /// `handle_read_error::JumpAhead` — see
+    /// `tests/passn_handler_ab.rs` for the A/B fixture that pins
+    /// the divergence point.)
    pub fn for_patch(batch: u16) -> Self {
        Self {
            batch,
            consecutive_good: 0,
            consecutive_failures: 0,
+            consecutive_outer_failures: 0,
            damage_window: Vec::with_capacity(16),
            damage_window_max: 16,
-            damage_threshold_pct: 12,
+            damage_threshold_pct: PATCH_DAMAGE_THRESHOLD_PCT,
+            // Pass N is allowed to grind: window-based jump only,
+            // matching the historical behaviour for patch passes.
+            fast_jump_threshold: u64::MAX,
            jump_multiplier: 1,
            not_ready_retries: 0,
            bridge_degradation_count: 0,
            bisecting: false,
+            bisect_on_marginal: true,
+            wedge_count: 0,
+            last_success_at: None,
+            last_error_at: None,
+            last_error_family: None,
+            total_errors: 0,
+            total_reads_ok: 0,
+            zones_entered: 0,
+            jumps_taken: 0,
+            in_damage_zone: false,
        }
    }

@@ -83,11 +236,54 @@ impl ReadCtx {
        self.consecutive_good += 1;
        self.consecutive_failures = 0;
        self.not_ready_retries = 0;
+        // Any successful read clears the wedge-skip counter — the
+        // drive recovered, so further wedges should reset the skip
+        // budget instead of accumulating toward a real abort.
+        self.wedge_count = 0;
+        // Outer-success only: a good single-sector read inside a
+        // bisect doesn't mean we've left the damaged batch. Only an
+        // outer-batch success resets the outer-failure counter.
+        if !self.bisecting {
+            self.consecutive_outer_failures = 0;
+        }
        self.damage_window.push(true);
        if self.damage_window.len() > self.damage_window_max {
            self.damage_window.remove(0);
        }
+        // Diagnostic state.
+        self.total_reads_ok += 1;
+        self.last_success_at = Some(std::time::Instant::now());
+        // If we were in a damage zone and accumulated enough good
+        // reads to exit (damage_window now all-good), the zone is
+        // over. Don't reset zones_entered — that's a sweep total.
+        if self.in_damage_zone && self.consecutive_good >= self.damage_window_max as u64 {
+            self.in_damage_zone = false;
+            self.last_error_family = None;
+        }
    }
+
+    /// Final per-pass summary suitable for an INFO log at the end of
+    /// `sweep` / `patch`. Caller renders this to a single structured
+    /// log line.
+    pub fn pass_summary(&self) -> PassSummary {
+        PassSummary {
+            total_reads_ok: self.total_reads_ok,
+            total_errors: self.total_errors,
+            zones_entered: self.zones_entered,
+            jumps_taken: self.jumps_taken,
+        }
+    }
+}
+
+/// End-of-pass stats logged at INFO for post-mortem analysis. Lets
+/// an operator answer "how damaged is this disc?" from a single log
+/// line per pass.
+#[derive(Debug, Clone, Copy)]
+pub struct PassSummary {
+    pub total_reads_ok: u64,
+    pub total_errors: u64,
+    pub zones_entered: u64,
+    pub jumps_taken: u64,
 }

 /// What the caller should do after a read failure. The caller owns the
@@ -119,7 +315,42 @@ pub enum ReadAction {
 // Pause budget constants. Tuned from 2026-05-07 BU40N traces showing
 // bridge wedges 524 ms after a 5.4-second internal ECC retry. The
 // post-failure pauses give the drive — and the bridge — time to settle.
-const POST_FAILURE_PAUSE_SECS: u64 = 1;
+/// Pause between a failed read and the next read attempt — applied
+/// uniformly to Pass 1 sweep and Pass N patch.
+///
+/// 2026-05-11 reframe: a failed read is a failed read, regardless of
+/// which pass is running. The prior split (1s for Pass N, 5s for Pass
+/// 1 via `PASS_1_FAIL_PAUSE_SECS`) was solving an imaginary cost
+/// problem — real damaged-disc cases mark <50 MB NonTrimmed, and the
+/// extra 5s/error is single-digit minutes per pass, not hours. The
+/// cost of NOT pausing — a drive wedge that aborts the entire
+/// multi-pass recovery — is much worse.
+///
+/// The wedge avoidance principle: error → drive ECC retry (5-10s
+/// internal) → return → cooldown pause → next read. Same shape
+/// everywhere reads can fail.
+const FAIL_PAUSE_SECS: u64 = 5;
+/// Long cooldown applied when a damage zone is first entered (the
+/// FIRST read failure after a clean run, before the drive has had a
+/// chance to cycle in retries that push it toward fast-fail).
+///
+/// Empirical: 2026-05-11 Dune Pt 2 wedge incident showed 7 medium
+/// errors in 6.5 seconds (~1s per attempt + ~1s pause) push the
+/// BU40N's firmware into IllegalRequest fast-fail mode permanently.
+/// Once there, only physical eject + reload clears it. Giving the
+/// drive 30s of breathing room after the FIRST error in a zone —
+/// before we start adding more error counts in the firmware's
+/// internal window — prevents the transition.
+///
+/// Cost on clean discs: zero (first-error path doesn't trigger).
+/// Cost on damaged discs: ~30s × N damage zones; on a 5-zone disc
+/// that's 2.5 min extra. Trade for never wedging the drive.
+const ZONE_ENTRY_COOLDOWN_SECS: u64 = 30;
+/// Cooldown when a long streak of failures suggests the drive is
+/// stuck in a damage zone and needs MORE breathing room than the
+/// standard inter-error pause. Same value as `FAIL_PAUSE_SECS`
+/// because empirically 5s is enough; kept as a separate name so the
+/// escalation policy is explicit at the call site.
 const CONSECUTIVE_FAIL_LONG_PAUSE_SECS: u64 = 5;
 const CONSECUTIVE_FAIL_LONG_PAUSE_THRESHOLD: u64 = 10;
 const POST_JUMP_EXTRA_PAUSE_SECS: u64 = 2;
@@ -128,6 +359,76 @@ const NOT_READY_MAX_RETRIES: u32 = 3;
 const BRIDGE_DEGRADATION_PAUSE_SECS: u64 = 15;
 const BRIDGE_DEGRADATION_MAX_RETRIES: u32 = 5;

+/// Base of the damage-jump distance formula: `jump_sectors =
+/// JUMP_BASE_SECTORS × batch × jump_multiplier`. Bumped 2026-05-10
+/// from 256 → 1024 (4×) so the first damage-jump at batch=32 covers
+/// 64 MB instead of 16 MB. Empirically the BU40N's damage clusters
+/// are 100+ MB wide; 16 MB jumps landed inside the cluster and the
+/// re-read added to the firmware wedge counter. 64 MB → 128 MB
+/// (after one doubling) clears almost any single-cluster damage in
+/// 2 jumps.
+const JUMP_BASE_SECTORS: u64 = 1024;
+
+// Firmware-wedge skip policy for Pass 1 sweep
+// ===========================================
+//
+// When the BU40N (or similar drives) hits a physical-damage cluster,
+// its firmware can transition into a "wedge" state where it returns
+// HARDWARE_ERROR or ILLEGAL_REQUEST for every subsequent read —
+// often for many LBAs after the actual bad sector. Per project docs
+// "Bad-sector handling" rule #2: "Recovery requires eject+reload OR
+// significant cool-down."
+//
+// Pass 1's pre-fix behavior was to immediately AbortPass on the
+// first HARDWARE_ERROR / ILLEGAL_REQUEST, killing the rip at
+// whatever percentage it had reached. That's the wrong call when:
+//   - the damage zone may be small (jumping past it could resume
+//     normal reads), AND
+//   - even if the drive stays wedged, finishing the sweep gives us
+//     an honest mapfile for Pass N to attack later.
+//
+// New policy: treat wedge sense codes the same way the damage-window
+// treats persistent failure — JumpAhead by a large distance with a
+// cooldown pause. Allow up to WEDGE_ABORT_THRESHOLD consecutive
+// wedges (no successful read in between) before declaring the drive
+// truly stuck and surfacing AbortPass to autorip.
+
+/// One-gigabyte jump (1024 MiB) on each wedge. Big enough to clear
+/// almost any single-cluster damage zone we've seen.
+const WEDGE_JUMP_SECTORS: u64 = 524_288;
+/// Cooldown pause after each wedge. Per project docs the drive needs
+/// "significant cool-down"; 30 s strikes a balance between giving
+/// the drive a chance to recover and not stalling the rip if the
+/// drive is permanently stuck.
+const WEDGE_PAUSE_SECS: u64 = 30;
+/// Bail after this many consecutive wedges with no good read in
+/// between. At 1 GB jumps this lets us scan ~16 GB worth of fully
+/// wedged area before giving up — generous enough to clear most
+/// physical-damage clusters, bounded enough to not loop forever on
+/// a permanently bricked drive.
+const WEDGE_ABORT_THRESHOLD: u64 = 16;
+
+/// Pass-N wedge-skip distance. Pass N's batch=1 reads target
+/// specific NonTrimmed sectors from Pass 1, so a big 1 GB skip
+/// would blow past the current NonTrimmed range and abandon many
+/// sectors that might still recover. Use a smaller skip just to
+/// move past the bricked LBA + a small buffer — the outer patch
+/// loop's next iteration picks up the next sector in the same or
+/// next range.
+const WEDGE_PASS_N_SKIP_SECTORS: u64 = 64;
+
+/// Single source of truth for the Pass-N damage-window threshold.
+/// Both [`ReadCtx::for_patch`] and `disc::patch::compute_damage_skip`
+/// reference this constant so the two damage-skip paths cannot drift.
+///
+/// 6% means: with a 16-entry sliding window, the damage-skip fires
+/// once 1 out of 16 recent reads has failed. Pass 1 uses a 12%
+/// threshold via `damage_threshold_pct` on `for_sweep`; Pass N is
+/// twice as eager because patch's whole job is to converge on the
+/// bad sub-zones inside a NonTrimmed range — a faster trigger
+/// produces tighter convergence in fewer iterations.
+pub const PATCH_DAMAGE_THRESHOLD_PCT: usize = 6;
+
 /// THE single error-handling entry point. Updates `ctx`, returns the
 /// action the caller must apply.
 ///
@@ -137,13 +438,61 @@ const BRIDGE_DEGRADATION_MAX_RETRIES: u32 = 5;
 pub fn handle_read_error(err: &Error, ctx: &mut ReadCtx) -> ReadAction {
    ctx.consecutive_failures += 1;
    ctx.consecutive_good = 0;
+    // Outer-failure counter — only OUTER batch failures count toward
+    // the fast-jump trigger. Bisect inner failures are part of
+    // recovering an already-failed batch and don't represent
+    // independent damage signal.
+    if !ctx.bisecting {
+        ctx.consecutive_outer_failures += 1;
+    }
+
+    // Diagnostic instrumentation — compute timing context BEFORE
+    // mutating the timestamps so the log reflects the gap to the
+    // PREVIOUS error / success, not zero.
+    let now = std::time::Instant::now();
+    let ms_since_last_error = ctx
+        .last_error_at
+        .map(|t| now.duration_since(t).as_millis() as u64);
+    let ms_since_last_success = ctx
+        .last_success_at
+        .map(|t| now.duration_since(t).as_millis() as u64);
+
+    let current_family = err
+        .scsi_sense()
+        .map(|s| SenseFamily::from_sense_key(s.sense_key))
+        .unwrap_or(SenseFamily::Other);
+
+    // Zone-entry tracking: this is the first error after a clean run
+    // (or the first error of the sweep).
+    if !ctx.in_damage_zone && !ctx.bisecting {
+        ctx.in_damage_zone = true;
+        ctx.zones_entered += 1;
+    }
+
+    ctx.total_errors += 1;
+    ctx.last_error_at = Some(now);
+
+    // Wedge transition: previous error was MEDIUM, this one is
+    // HARDWARE or ILLEGAL_REQUEST. That's the moment the drive's
+    // firmware flipped into fast-fail mode. Distinct WARN so logs
+    // make it unambiguous when the wedge "started."
+    let is_wedge_transition = matches!(ctx.last_error_family, Some(prev) if !prev.is_wedge_family())
+        && current_family.is_wedge_family();
+    ctx.last_error_family = Some(current_family);

    tracing::warn!(
        target: "freemkv::disc",
        phase = "read_error",
        consecutive_failures = ctx.consecutive_failures,
+        consecutive_outer_failures = ctx.consecutive_outer_failures,
+        ms_since_last_error,
+        ms_since_last_success,
+        total_errors = ctx.total_errors,
+        total_reads_ok = ctx.total_reads_ok,
        batch = ctx.batch,
        bisecting = ctx.bisecting,
+        wedge_count = ctx.wedge_count,
+        sense_family = ?current_family,
        sense_key = err.scsi_sense().map(|s| s.sense_key),
        asc = err.scsi_sense().map(|s| s.asc),
        ascq = err.scsi_sense().map(|s| s.ascq),
@@ -151,6 +500,17 @@ pub fn handle_read_error(err: &Error, ctx: &mut ReadCtx) -> ReadAction {
        "read failed; classifying"
    );

+    if is_wedge_transition {
+        tracing::warn!(
+            target: "freemkv::disc",
+            phase = "wedge_transition",
+            errors_in_zone = ctx.total_errors,
+            ms_since_last_success,
+            new_family = ?current_family,
+            "drive entered wedge / fast-fail family (was returning recoverable medium errors before this)"
+        );
+    }
+
    // 1. Transport failure: bridge crash / USB disconnect. The outer
    //    pass loop knows how to handle this (rediscover sg path,
    //    re-open drive). Inline single-sector retry here was tried in
@@ -186,11 +546,62 @@ pub fn handle_read_error(err: &Error, ctx: &mut ReadCtx) -> ReadAction {
        ctx.not_ready_retries = 0;
    }

-    // 4. Hardware / illegal request: the drive said "no, won't do it".
-    //    Retrying won't change the answer. Surface to the outer layer
-    //    so it can eject + prompt user.
+    // 4. Hardware error / illegal request — the firmware-wedge family.
+    //    The drive transitioned into a fast-fail state where it
+    //    rejects reads near the LBA. Same response shape for both
+    //    passes (2026-05-11 reframe — error handling is centralized,
+    //    and the wedge is a code-induced state we can avoid via
+    //    pacing + skip):
+    //
+    //    - Pass 1 sweep (bisect_on_marginal=false): jump
+    //      WEDGE_JUMP_SECTORS (1 GB) ahead, pause WEDGE_PAUSE_SECS,
+    //      mark skipped region NonTrimmed.
+    //    - Pass N patch (bisect_on_marginal=true): give up on the
+    //      current sector (the granular target), pause for cooldown,
+    //      let the outer patch loop move to the next NonTrimmed
+    //      range. Implemented as a small JumpAhead so the same code
+    //      path serves both — Pass N's batch=1 means JumpAhead by
+    //      WEDGE_PASS_N_SKIP_SECTORS effectively skips just this
+    //      sector and a small buffer (gives the drive room to
+    //      recover before the next per-sector attempt).
+    //
+    //    Both paths share the WEDGE_ABORT_THRESHOLD budget — only
+    //    AbortPass after N consecutive wedges with no successful
+    //    read in between.
    if sense_key == scsi::SENSE_KEY_HARDWARE_ERROR || sense_key == scsi::SENSE_KEY_ILLEGAL_REQUEST {
-        return ReadAction::AbortPass;
+        if !ctx.bisecting {
+            ctx.wedge_count += 1;
+        }
+        if ctx.wedge_count >= WEDGE_ABORT_THRESHOLD {
+            tracing::warn!(
+                target: "freemkv::disc",
+                phase = "wedge_abort",
+                wedge_count = ctx.wedge_count,
+                threshold = WEDGE_ABORT_THRESHOLD,
+                pass = if ctx.bisect_on_marginal { "N" } else { "1" },
+                "wedge-skip exhausted — drive appears permanently stuck"
+            );
+            return ReadAction::AbortPass;
+        }
+        let jump_sectors = if ctx.bisect_on_marginal {
+            WEDGE_PASS_N_SKIP_SECTORS
+        } else {
+            WEDGE_JUMP_SECTORS
+        };
+        tracing::warn!(
+            target: "freemkv::disc",
+            phase = "wedge_skip",
+            pass = if ctx.bisect_on_marginal { "N" } else { "1" },
+            wedge_count = ctx.wedge_count,
+            jump_sectors,
+            pause_secs = WEDGE_PAUSE_SECS,
+            "wedge detected — skipping ahead and pausing for drive cooldown"
+        );
+        ctx.jumps_taken += 1;
+        return ReadAction::JumpAhead {
+            sectors: jump_sectors,
+            pause_secs: WEDGE_PAUSE_SECS,
+        };
    }

    // 5. Marginal media (MEDIUM_ERROR / ABORTED_COMMAND) on a multi-
@@ -198,11 +609,20 @@ pub fn handle_read_error(err: &Error, ctx: &mut ReadCtx) -> ReadAction {
    //    individually. Bisect into single-sector reads (gentler on the
    //    bridge too — shorter SCSI transactions). Avoid recursive
    //    bisect.
+    //
+    //    Pass 1 sweep sets `bisect_on_marginal=false` to skip this:
+    //    its job is "fast and accurate, get the most data in the
+    //    shortest time." Pass N is purpose-built to recover
+    //    individual sectors with proper recovery semantics, and Pass
+    //    1 grinding through 32-sector bisects costs ~2.5 min per bad
+    //    block AND fills the damage window slower than it should.
+    //    Whole-block NonTrimmed → SkipBlock → advance → Pass N
+    //    revisits.
    let is_marginal = matches!(
        sense_key,
        scsi::SENSE_KEY_MEDIUM_ERROR | scsi::SENSE_KEY_ABORTED_COMMAND
    );
-    if is_marginal && ctx.batch > 1 && !ctx.bisecting {
+    if is_marginal && ctx.batch > 1 && !ctx.bisecting && ctx.bisect_on_marginal {
        return ReadAction::Bisect;
    }

@@ -228,22 +648,74 @@ pub fn handle_read_error(err: &Error, ctx: &mut ReadCtx) -> ReadAction {
        bad_count * 100 / ctx.damage_window.len()
    };

-    let pause_secs = if ctx.consecutive_failures >= CONSECUTIVE_FAIL_LONG_PAUSE_THRESHOLD {
+    // Inter-error pause — wedge prevention via pacing.
+    //
+    // Zone-entry case (first error after a clean run): apply the
+    // long ZONE_ENTRY_COOLDOWN_SECS pause. The empirical wedge
+    // observed 2026-05-11 happened ~7 errors into a damage zone,
+    // each retry adding to the firmware's internal counter. A 30s
+    // pause at zone entry lets the drive's bridge / firmware
+    // counters reset before we issue the next read.
+    //
+    // Subsequent errors in the same zone: the standard 5s pause.
+    // (We've already jumped past the initial damage; further errors
+    // mean we landed in another bad cluster — same pacing applies.)
+    //
+    // Long-streak escalation: same 5s currently; kept as a separate
+    // branch for future tuning. Pass N (bisect_on_marginal=true)
+    // uses the standard pauses — it's running single-sector retries
+    // on already-known-bad LBAs by design.
+    let is_zone_entry =
+        ctx.consecutive_outer_failures == 1 && !ctx.bisecting && !ctx.bisect_on_marginal;
+    let pause_secs = if is_zone_entry {
+        ZONE_ENTRY_COOLDOWN_SECS
+    } else if ctx.consecutive_failures >= CONSECUTIVE_FAIL_LONG_PAUSE_THRESHOLD {
        CONSECUTIVE_FAIL_LONG_PAUSE_SECS
    } else {
-        POST_FAILURE_PAUSE_SECS
+        FAIL_PAUSE_SECS
    };

-    // 7. Damage-jump: too many failures in window → skip ahead by an
-    //    escalating gap. Multiplier capped so we can't accidentally
-    //    skip the entire rest of the disc (observed 2026-05-07: a
-    //    saturated multiplier produced a 56 GB jump). Saturating
-    //    arithmetic on the sector calc as defence in depth.
-    const MAX_JUMP_MULTIPLIER: u64 = 64; // 64 × 256 × batch sectors
-    if ctx.damage_window.len() >= ctx.damage_window_max && bad_pct >= ctx.damage_threshold_pct {
+    // 7. Damage-jump: too many failures → skip ahead by an escalating
+    //    gap. Multiplier capped so we can't accidentally skip the
+    //    entire rest of the disc (observed 2026-05-07: a saturated
+    //    multiplier produced a 56 GB jump). Saturating arithmetic on
+    //    the sector calc as defence in depth.
+    //
+    //    Jump base bumped 2026-05-10 from 256 to 1024 sectors per
+    //    multiplier unit (= 64 MB first jump at batch=32, up from
+    //    16 MB). The smaller base routinely landed jumps back inside
+    //    damage clusters of 100+ MB, each landing adding to the
+    //    firmware's wedge counter. 64 MB initial + 128 MB second +
+    //    256 MB third clears almost any single-cluster damage
+    //    pattern we've seen in 2 jumps.
+    //
+    //    Two triggers, evaluated in order:
+    //
+    //    a. **Fast-entry** — `consecutive_outer_failures >= fast_jump_threshold`.
+    //       Fires on Pass 1 (threshold=4) so we don't spend ~40 min
+    //       grinding to fill a 16-block damage window before the
+    //       first jump on a damage zone we entered cleanly. Doesn't
+    //       fire on Pass N (threshold=u64::MAX).
+    //
+    //    b. **Window-based** — original behaviour: 12% bad in a
+    //       sliding window of 16 outer reads. Pass N's only path,
+    //       and Pass 1's fallback if the failures are scattered
+    //       enough that we don't hit the consecutive threshold.
+    const MAX_JUMP_MULTIPLIER: u64 = 64;
+    let fast_trigger = !ctx.bisecting && ctx.consecutive_outer_failures >= ctx.fast_jump_threshold;
+    let window_trigger =
+        ctx.damage_window.len() >= ctx.damage_window_max && bad_pct >= ctx.damage_threshold_pct;
+    if fast_trigger || window_trigger {
        let mult = ctx.jump_multiplier.min(MAX_JUMP_MULTIPLIER);
-        let sectors = 256u64.saturating_mul(ctx.batch as u64).saturating_mul(mult);
+        let sectors = JUMP_BASE_SECTORS
+            .saturating_mul(ctx.batch as u64)
+            .saturating_mul(mult);
        ctx.jump_multiplier = (ctx.jump_multiplier.saturating_mul(2)).min(MAX_JUMP_MULTIPLIER);
+        // Reset the outer-failure counter so a long damaged region
+        // doesn't keep firing fast-jump every read after the initial
+        // jump fired. The window-based trigger handles further jumps.
+        ctx.consecutive_outer_failures = 0;
+        ctx.jumps_taken += 1;
        return ReadAction::JumpAhead {
            sectors,
            pause_secs: pause_secs + POST_JUMP_EXTRA_PAUSE_SECS,
@@ -285,16 +757,44 @@ mod tests {
        }
    }

+    fn illegal_request_err() -> Error {
+        Error::DiscRead {
+            sector: 100,
+            status: Some(2),
+            sense: Some(ScsiSense {
+                sense_key: scsi::SENSE_KEY_ILLEGAL_REQUEST,
+                asc: 0x24,
+                ascq: 0x00,
+            }),
+        }
+    }
+
    #[test]
-    fn medium_error_with_batch_gt_1_bisects() {
-        let mut ctx = ReadCtx::for_sweep(32);
+    fn pass_n_marginal_with_batch_gt_1_bisects() {
+        let mut ctx = ReadCtx::for_patch(32);
        let action = handle_read_error(&medium_err(), &mut ctx);
        assert_eq!(action, ReadAction::Bisect);
    }

+    #[test]
+    fn pass_1_marginal_jumps_immediately_not_bisecting() {
+        // 2026-05-11 wedge-prevention rewrite: Pass 1 jumps on the
+        // FIRST marginal error (fast_jump_threshold=1) rather than
+        // SkipBlock. Retrying the same LBA quickly is what triggers
+        // the BU40N's firmware fast-fail transition; immediate jump
+        // prevents the cascade. Pass N still bisects (its job is
+        // per-sector recovery on already-known-bad LBAs).
+        let mut ctx = ReadCtx::for_sweep(32);
+        let action = handle_read_error(&medium_err(), &mut ctx);
+        match action {
+            ReadAction::JumpAhead { .. } => {}
+            other => panic!("expected JumpAhead on first Pass 1 marginal error, got {other:?}"),
+        }
+    }
+
    #[test]
    fn medium_error_with_batch_1_skips() {
-        let mut ctx = ReadCtx::for_sweep(1);
+        let mut ctx = ReadCtx::for_patch(1);
        let action = handle_read_error(&medium_err(), &mut ctx);
        match action {
            ReadAction::SkipBlock { pause_secs } => assert!(pause_secs >= 1),
@@ -304,7 +804,7 @@ mod tests {

    #[test]
    fn medium_error_while_bisecting_does_not_recurse() {
-        let mut ctx = ReadCtx::for_sweep(32);
+        let mut ctx = ReadCtx::for_patch(32);
        ctx.bisecting = true;
        let action = handle_read_error(&medium_err(), &mut ctx);
        match action {
@@ -314,19 +814,187 @@ mod tests {
    }

    #[test]
-    fn hardware_error_aborts() {
+    fn pass_1_jumps_immediately_on_first_outer_failure() {
+        // 2026-05-11 rewrite: fast_jump_threshold is 1 on Pass 1, not
+        // 4. Even ONE error triggers a jump because BU40N's firmware
+        // fast-fail mode is sensitive to retry cadence. The wedge
+        // observed 2026-05-11 happened at 7 errors / 6.5s — by then
+        // we were already wedged. Jumping on error #1 means we
+        // physically can't reach the cascade.
        let mut ctx = ReadCtx::for_sweep(32);
+        let a = handle_read_error(&medium_err(), &mut ctx);
+        assert!(
+            matches!(a, ReadAction::JumpAhead { .. }),
+            "expected JumpAhead on first outer failure (fast_jump_threshold=1), got {a:?}"
+        );
+    }
+
+    #[test]
+    fn pass_n_does_not_fast_jump() {
+        // Pass N's whole reason to exist is to grind on bad ranges.
+        // It should NOT bail after 4 consecutive failures the way
+        // Pass 1 does — it bisects and skips with proper recovery.
+        let mut ctx = ReadCtx::for_patch(32);
+        for _ in 0..4 {
+            let a = handle_read_error(&medium_err(), &mut ctx);
+            assert!(
+                !matches!(a, ReadAction::JumpAhead { .. }),
+                "Pass N must not fast-jump; got {a:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn outer_success_resets_consecutive_outer_failures() {
+        // With fast_jump_threshold=1 each Pass 1 error fires a jump
+        // and resets `consecutive_outer_failures` to 0 inside the
+        // handler. So we can't accumulate "3" the old way — instead,
+        // verify the counter goes back to 0 after on_success too.
+        let mut ctx = ReadCtx::for_sweep(32);
+        handle_read_error(&medium_err(), &mut ctx);
+        // After fast-jump, consecutive_outer_failures already 0.
+        assert_eq!(ctx.consecutive_outer_failures, 0);
+        // on_success keeps it at 0 (defensive).
+        ctx.bisecting = false;
+        ctx.on_success();
+        assert_eq!(ctx.consecutive_outer_failures, 0);
+    }
+
+    #[test]
+    fn bisect_inner_success_does_not_reset_outer_counter() {
+        let mut ctx = ReadCtx::for_patch(32);
+        for _ in 0..3 {
+            handle_read_error(&medium_err(), &mut ctx);
+        }
+        assert_eq!(ctx.consecutive_outer_failures, 3);
+        // A successful inner-sector read during bisect is not the
+        // same as escaping the bad outer batch.
+        ctx.bisecting = true;
+        ctx.on_success();
+        assert_eq!(
+            ctx.consecutive_outer_failures, 3,
+            "bisect inner success must not reset outer-failure counter"
+        );
+    }
+
+    #[test]
+    fn pass_1_hardware_error_jumps_ahead_not_aborts() {
+        // New wedge-skip policy: Pass 1 (bisect_on_marginal=false)
+        // should JumpAhead with a 1 GB skip + cooldown pause instead
+        // of immediately aborting. Aborting on first wedge was the
+        // pre-fix behavior that killed rips at 48% on damaged discs.
+        let mut ctx = ReadCtx::for_sweep(32);
+        let action = handle_read_error(&hardware_err(), &mut ctx);
+        match action {
+            ReadAction::JumpAhead {
+                sectors,
+                pause_secs,
+            } => {
+                assert_eq!(sectors, WEDGE_JUMP_SECTORS);
+                assert_eq!(pause_secs, WEDGE_PAUSE_SECS);
+            }
+            other => panic!("expected JumpAhead, got {other:?}"),
+        }
+        assert_eq!(ctx.wedge_count, 1);
+    }
+
+    #[test]
+    fn pass_1_hardware_error_aborts_after_threshold() {
+        // After WEDGE_ABORT_THRESHOLD consecutive wedges with no good
+        // read in between, autorip should see a real AbortPass so it
+        // can surface "drive is stuck, power-cycle required" to the
+        // user — rather than looping forever on a permanently bricked
+        // drive.
+        let mut ctx = ReadCtx::for_sweep(32);
+        for i in 0..WEDGE_ABORT_THRESHOLD - 1 {
+            let action = handle_read_error(&hardware_err(), &mut ctx);
+            assert!(
+                matches!(action, ReadAction::JumpAhead { .. }),
+                "iter {i}: expected JumpAhead, got {action:?}"
+            );
+        }
+        // The Nth wedge crosses the threshold.
        let action = handle_read_error(&hardware_err(), &mut ctx);
        assert_eq!(action, ReadAction::AbortPass);
    }

    #[test]
-    fn long_failure_streak_extends_pause() {
-        let mut ctx = ReadCtx::for_sweep(1);
+    fn pass_1_good_read_resets_wedge_count() {
+        // A single successful read between wedges must clear the
+        // skip counter — otherwise a disc with a few scattered bad
+        // zones would eventually run out of skip budget even though
+        // the drive was recovering between zones.
+        let mut ctx = ReadCtx::for_sweep(32);
+        for _ in 0..(WEDGE_ABORT_THRESHOLD - 1) {
+            handle_read_error(&hardware_err(), &mut ctx);
+        }
+        assert_eq!(ctx.wedge_count, WEDGE_ABORT_THRESHOLD - 1);
+        ctx.on_success();
+        assert_eq!(ctx.wedge_count, 0);
+        // After the success, we should still get JumpAhead (not
+        // AbortPass) on the next wedge.
+        let action = handle_read_error(&hardware_err(), &mut ctx);
+        assert!(matches!(action, ReadAction::JumpAhead { .. }));
+    }
+
+    #[test]
+    fn pass_n_hardware_error_also_skips_not_aborts() {
+        // 2026-05-11 reframe: error handling is centralized, the
+        // wedge is a code-induced state, and the avoidance principle
+        // (skip + pause + continue) applies to Pass N too. Previously
+        // Pass N AbortPass'd on first wedge — same fatal-at-48% bug
+        // Pass 1 had pre-fix. Now Pass N gets a smaller skip
+        // (WEDGE_PASS_N_SKIP_SECTORS, not the 1 GB Pass 1 jump)
+        // because Pass N's job IS to revisit specific NonTrimmed
+        // ranges; over-skipping abandons recoverable sectors.
+        let mut ctx = ReadCtx::for_patch(1);
+        let action = handle_read_error(&hardware_err(), &mut ctx);
+        match action {
+            ReadAction::JumpAhead {
+                sectors,
+                pause_secs,
+            } => {
+                assert_eq!(sectors, WEDGE_PASS_N_SKIP_SECTORS);
+                assert_eq!(pause_secs, WEDGE_PAUSE_SECS);
+            }
+            other => panic!("expected JumpAhead, got {other:?}"),
+        }
+        assert_eq!(ctx.wedge_count, 1);
+    }
+
+    #[test]
+    fn pass_n_hardware_error_aborts_after_threshold() {
+        // Same threshold as Pass 1 — after WEDGE_ABORT_THRESHOLD
+        // consecutive wedges with no good read in between, give up.
+        let mut ctx = ReadCtx::for_patch(1);
+        for _ in 0..WEDGE_ABORT_THRESHOLD - 1 {
+            let action = handle_read_error(&hardware_err(), &mut ctx);
+            assert!(matches!(action, ReadAction::JumpAhead { .. }));
+        }
+        let action = handle_read_error(&hardware_err(), &mut ctx);
+        assert_eq!(action, ReadAction::AbortPass);
+    }
+
+    #[test]
+    fn pass_1_illegal_request_also_routes_to_wedge_skip() {
+        // ILLEGAL_REQUEST is the other half of the wedge family:
+        // drive saying "I won't parse your CDB" after entering the
+        // fast-fail state. Same treatment as HARDWARE_ERROR.
+        let mut ctx = ReadCtx::for_sweep(32);
+        let action = handle_read_error(&illegal_request_err(), &mut ctx);
+        assert!(matches!(action, ReadAction::JumpAhead { .. }));
+    }
+
+    #[test]
+    fn long_failure_streak_extends_pause_on_pass_n() {
+        // Pass N keeps the cooldown behaviour: after many consecutive
+        // failures, pauses extend to give the drive time to recover.
+        // Pass 1 explicitly does NOT pause — see
+        // `pass_1_does_not_pause_on_skip` below.
+        let mut ctx = ReadCtx::for_patch(1);
        for _ in 0..15 {
            handle_read_error(&medium_err(), &mut ctx);
        }
-        // After many consecutive failures we should be in the long-pause regime
        let final_action = handle_read_error(&medium_err(), &mut ctx);
        match final_action {
            ReadAction::SkipBlock { pause_secs } => {
@@ -339,6 +1007,47 @@ mod tests {
        }
    }

+    #[test]
+    fn pass_1_zone_entry_uses_long_cooldown() {
+        // 2026-05-11 wedge-prevention rewrite: Pass 1's FIRST error
+        // (zone entry) gets a 30 s ZONE_ENTRY_COOLDOWN_SECS pause +
+        // a 2 s POST_JUMP_EXTRA on top (since we're also jumping).
+        // The long pause prevents the retry cadence that triggers
+        // firmware fast-fail. Subsequent errors in the same zone fall
+        // back to the standard 5 s FAIL_PAUSE_SECS.
+        let mut ctx = ReadCtx::for_sweep(32);
+        let action = handle_read_error(&medium_err(), &mut ctx);
+        match action {
+            ReadAction::JumpAhead { pause_secs, .. } => {
+                assert_eq!(
+                    pause_secs,
+                    ZONE_ENTRY_COOLDOWN_SECS + POST_JUMP_EXTRA_PAUSE_SECS,
+                    "first-error pause should be 30 + 2 = 32 s"
+                );
+            }
+            other => panic!("expected JumpAhead on first Pass 1 error, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn pass_n_pauses_uniformly_on_failed_read() {
+        // Pass N (bisect_on_marginal=true) is exempt from the
+        // zone-entry long pause — its whole job is to retry single
+        // sectors on already-known-bad LBAs, and the 30 s pause every
+        // single-sector failure would multiply slow recovery
+        // pointlessly. Pass N keeps the standard 5 s FAIL_PAUSE_SECS.
+        let mut ctx = ReadCtx::for_patch(1);
+        let action = handle_read_error(&medium_err(), &mut ctx);
+        match action {
+            ReadAction::SkipBlock { pause_secs } => assert_eq!(pause_secs, FAIL_PAUSE_SECS),
+            ReadAction::JumpAhead { pause_secs, .. } => {
+                assert_eq!(pause_secs, FAIL_PAUSE_SECS + POST_JUMP_EXTRA_PAUSE_SECS)
+            }
+            ReadAction::Bisect => {}
+            other => panic!("expected pausing action, got {other:?}"),
+        }
+    }
+
    #[test]
    fn damage_window_fills_then_jumps() {
        let mut ctx = ReadCtx::for_sweep(1);
@@ -369,6 +1078,6 @@ mod tests {
        ctx.on_success();
        assert_eq!(ctx.consecutive_good, 1);
        assert_eq!(ctx.consecutive_failures, 0);
-        assert_eq!(*ctx.damage_window.last().unwrap(), true);
+        assert!(*ctx.damage_window.last().unwrap());
    }
 }
@@ -0,0 +1,239 @@
+//! `Disc::sweep`'s consumer-side `Sink<WorkItem>`.
+//!
+//! Background: the original sweep loop runs strictly serialised —
+//! SCSI read → decrypt → seek + write → mapfile.record → next iter.
+//! On a healthy disc the SCSI read costs ~5-12 ms per 64 KB batch and
+//! the post-read work (decrypt 1-3 ms + file write + mapfile fsync
+//! 5-15 ms) adds another batch's worth of latency. The drive idles
+//! during the post-read work; throughput tops out at the *sum* of
+//! both costs.
+//!
+//! 0.17.11 introduced a bespoke producer/consumer split (the now-
+//! removed `disc/sweep_pipeline.rs`) to overlap the two stages. 0.18
+//! collapses that split — together with the analogous splits patch
+//! and mux need — onto the generic [`crate::io::Pipeline`] +
+//! [`crate::io::Sink`] primitive. This module is the sweep-specific
+//! `Sink` impl; the producer-side state machine (read_error context,
+//! decrypt, set_speed, halt) stays in `Disc::sweep` in `disc/mod.rs`.
+//!
+//! Correctness invariants preserved (same as 0.17.11):
+//! - Mapfile is single-writer (consumer-only). No locking.
+//! - All `read_error::ReadCtx` state stays on the producer thread.
+//! - `set_speed` calls happen on the producer thread (same thread that
+//!   owns the `SectorSource`). No new SCSI concurrency.
+//! - Per-iteration ordering of file-write → mapfile-record is kept
+//!   intact in the consumer (write before record), so the on-disk
+//!   invariant "mapfile only marks Finished what the file has
+//!   received" survives a crash mid-pass.
+//! - The BU40N+Initio bridge wedge concern is unchanged: only one
+//!   SCSI command in flight at a time, error-path timing identical,
+//!   no new retry logic.
+
+use std::io::{Seek, SeekFrom, Write};
+use std::sync::mpsc::{Receiver, SyncSender, sync_channel};
+
+use crate::error::Error;
+use crate::io::{Flow, Sink};
+
+use super::mapfile::{MapStats, Mapfile, SectorStatus};
+
+/// Reusable zero buffer for SkipFill / GapFill / BisectBad. 64 KB
+/// matches the existing zero_gap chunk size used by the pre-split
+/// sweep loop.
+const ZERO_CHUNK: usize = 65 * 1024;
+
+/// Producer → Consumer messages. The consumer applies these in FIFO
+/// order; ordering of file writes and mapfile records across items is
+/// preserved.
+pub(super) enum WorkItem {
+    /// Successful batch read. Producer has already decrypted `buf` if
+    /// `opts.decrypt` was set. Consumer writes `buf` at `pos` and
+    /// records the range as `Finished`.
+    Good { pos: u64, buf: Vec<u8> },
+
+    /// Bisect inner-loop good single sector (already decrypted by the
+    /// producer). 2048 bytes.
+    BisectGood { pos: u64, buf: Box<[u8; 2048]> },
+
+    /// Bisect inner-loop bad single sector. Consumer writes 2048
+    /// zeros at `pos` and records the sector as `NonTrimmed`.
+    BisectBad { pos: u64 },
+
+    /// Whole-batch zero-fill (failed batch on `SkipBlock`, or the
+    /// failed batch portion of `JumpAhead`). Consumer streams zeros
+    /// across `[pos, pos+len)` and records the range as `NonTrimmed`.
+    SkipFill { pos: u64, len: u64 },
+
+    /// Gap fill following a `JumpAhead`. Same effect as `SkipFill`;
+    /// distinguished only so future logging / instrumentation can
+    /// tell them apart without parsing a flag.
+    GapFill { pos: u64, len: u64 },
+
+    /// Producer wants the latest mapfile stats for the progress
+    /// callback. Consumer responds on `prog_tx` with a fresh
+    /// [`ProgressSnapshot`]. Best-effort: if the producer hasn't
+    /// drained the previous snapshot, the new one is silently
+    /// dropped — the producer's local cache stays current enough.
+    StatsRequest,
+}
+
+/// Snapshot the consumer sends back to the producer for the progress
+/// callback.
+pub(super) struct ProgressSnapshot {
+    pub stats: MapStats,
+    pub bad_ranges: Vec<(u64, u64)>,
+}
+
+/// Final summary returned by the consumer thread on shutdown — what
+/// `SweepSink::close` produces, surfaced to the producer via
+/// `Pipeline::finish`.
+pub(super) struct ConsumerSummary {
+    pub stats: MapStats,
+}
+
+/// Drain any pending progress snapshots from the consumer. Returns
+/// the most recent one, if any. The producer caches it and uses it
+/// for subsequent progress callbacks until a fresh one arrives.
+pub(super) fn try_recv_progress(rx: &Receiver<ProgressSnapshot>) -> Option<ProgressSnapshot> {
+    let mut latest = None;
+    while let Ok(snap) = rx.try_recv() {
+        latest = Some(snap);
+    }
+    latest
+}
+
+/// `Sink<WorkItem>` for sweep. Owns the writeback file + mapfile +
+/// progress back-channel. `apply` carries the file-write +
+/// mapfile.record per item; `close` drains the writeback pipeline,
+/// fsyncs the ISO, and flushes the mapfile.
+pub(super) struct SweepSink {
+    file: crate::io::WritebackFile,
+    map: Mapfile,
+    /// `sync_all`-on-failure-is-an-error iff the output is a regular
+    /// file. `/dev/null` and pipes always fail `sync_all`; that's not
+    /// a real error.
+    is_regular: bool,
+    /// Back-channel for `StatsRequest` responses. The producer caches
+    /// the latest snapshot and uses it for the progress callback;
+    /// dropped sends on a full channel are by design.
+    prog_tx: SyncSender<ProgressSnapshot>,
+    /// Reusable zero buffer for SkipFill / GapFill / BisectBad. Held
+    /// in the sink so each apply call doesn't reallocate.
+    zero: Box<[u8; ZERO_CHUNK]>,
+}
+
+impl SweepSink {
+    /// Construct a new `SweepSink` plus the matching progress
+    /// receiver. Channel depth on the back-channel is `1` — the
+    /// producer's cache is the source of truth between snapshots.
+    pub(super) fn new(
+        file: crate::io::WritebackFile,
+        map: Mapfile,
+        is_regular: bool,
+    ) -> (Self, Receiver<ProgressSnapshot>) {
+        let (prog_tx, prog_rx) = sync_channel::<ProgressSnapshot>(1);
+        let sink = SweepSink {
+            file,
+            map,
+            is_regular,
+            prog_tx,
+            zero: Box::new([0u8; ZERO_CHUNK]),
+        };
+        (sink, prog_rx)
+    }
+}
+
+impl Sink<WorkItem> for SweepSink {
+    type Output = ConsumerSummary;
+
+    fn apply(&mut self, item: WorkItem) -> Result<Flow, Error> {
+        match item {
+            WorkItem::Good { pos, buf } => {
+                // Decrypt is on the producer; consumer assumes plaintext.
+                let len = buf.len() as u64;
+                self.file
+                    .seek(SeekFrom::Start(pos))
+                    .map_err(|e| Error::IoError { source: e })?;
+                self.file
+                    .write_all(&buf)
+                    .map_err(|e| Error::IoError { source: e })?;
+                self.map
+                    .record(pos, len, SectorStatus::Finished)
+                    .map_err(|e| Error::IoError { source: e })?;
+            }
+            WorkItem::BisectGood { pos, buf } => {
+                self.file
+                    .seek(SeekFrom::Start(pos))
+                    .map_err(|e| Error::IoError { source: e })?;
+                self.file
+                    .write_all(&buf[..])
+                    .map_err(|e| Error::IoError { source: e })?;
+                self.map
+                    .record(pos, 2048, SectorStatus::Finished)
+                    .map_err(|e| Error::IoError { source: e })?;
+            }
+            WorkItem::BisectBad { pos } => {
+                self.file
+                    .seek(SeekFrom::Start(pos))
+                    .map_err(|e| Error::IoError { source: e })?;
+                self.file
+                    .write_all(&self.zero[..2048])
+                    .map_err(|e| Error::IoError { source: e })?;
+                self.map
+                    .record(pos, 2048, SectorStatus::NonTrimmed)
+                    .map_err(|e| Error::IoError { source: e })?;
+            }
+            WorkItem::SkipFill { pos, len } | WorkItem::GapFill { pos, len } => {
+                self.file
+                    .seek(SeekFrom::Start(pos))
+                    .map_err(|e| Error::IoError { source: e })?;
+                // Subsequent writes are sequential; `WritebackFile`'s
+                // seek-elision keeps them on the writeback pipeline path.
+                let mut filled = 0u64;
+                while filled < len {
+                    let chunk = (len - filled).min(self.zero.len() as u64) as usize;
+                    self.file
+                        .write_all(&self.zero[..chunk])
+                        .map_err(|e| Error::IoError { source: e })?;
+                    filled += chunk as u64;
+                }
+                self.map
+                    .record(pos, len, SectorStatus::NonTrimmed)
+                    .map_err(|e| Error::IoError { source: e })?;
+            }
+            WorkItem::StatsRequest => {
+                let stats = self.map.stats();
+                let bad_ranges = self.map.ranges_with(&[
+                    SectorStatus::NonTrimmed,
+                    SectorStatus::Unreadable,
+                    SectorStatus::NonScraped,
+                    SectorStatus::NonTried,
+                ]);
+                // Best-effort: drop on backpressure; producer's cache
+                // stays current enough.
+                let _ = self
+                    .prog_tx
+                    .try_send(ProgressSnapshot { stats, bad_ranges });
+            }
+        }
+        Ok(Flow::Continue)
+    }
+
+    fn close(mut self) -> Result<Self::Output, Error> {
+        // Drain the writeback pipeline + fsync the ISO, then persist
+        // any pending mapfile state. Same finalisation order as the
+        // pre-Pipeline consumer loop.
+        if let Err(e) = self.file.sync_all() {
+            if self.is_regular {
+                return Err(Error::IoError { source: e });
+            }
+            // Non-regular outputs (/dev/null, pipes) always fail
+            // sync_all; that's not a real error.
+        }
+        self.map.flush().map_err(|e| Error::IoError { source: e })?;
+
+        Ok(ConsumerSummary {
+            stats: self.map.stats(),
+        })
+    }
+}
@@ -29,7 +29,7 @@ use crate::platform::PlatformDriver;
 use crate::platform::mt1959::Mt1959;
 use crate::profile::{self, DriveProfile};
 use crate::scsi::ScsiTransport;
-use crate::sector::SectorReader;
+use crate::sector::SectorSource;
 use std::path::Path;
 use std::sync::Arc;
 use std::sync::atomic::{AtomicBool, Ordering};
@@ -69,6 +69,16 @@ pub struct Drive {
    halt: Arc<AtomicBool>,
    /// Event handler — fires for read errors and library-level state changes.
    event_fn: Option<Box<dyn Fn(Event) + Send>>,
+    /// Linux only: raw fd for the corresponding block device (`/dev/sr*`)
+    /// used as a recovery fallback when SCSI READ via `/dev/sg*` returns
+    /// an error. The kernel `sr_mod` driver auto-retries failed reads
+    /// (~5× per command) — historically the reason `dd if=/dev/sr0`
+    /// recovers ~50% of bad sectors that single-shot `SG_IO` READ
+    /// misses on the same drive. `None` when the block device couldn't
+    /// be resolved or opened (no fallback in that case; SCSI read
+    /// errors propagate as before).
+    #[cfg(target_os = "linux")]
+    block_dev_fd: Option<std::os::unix::io::RawFd>,
 }

 impl Drive {
@@ -87,6 +97,9 @@ impl Drive {
            None => (None, None, None),
        };

+        #[cfg(target_os = "linux")]
+        let block_dev_fd = open_block_device_for_sg(device);
+
        Ok(Drive {
            scsi: transport,
            driver,
@@ -96,6 +109,8 @@ impl Drive {
            device_path: device.to_string_lossy().to_string(),
            halt: Arc::new(AtomicBool::new(false)),
            event_fn: None,
+            #[cfg(target_os = "linux")]
+            block_dev_fd,
        })
    }

@@ -483,6 +498,54 @@ impl Drive {
                    scsi_status = status,
                    "Drive::read checked_exec failed"
                );
+
+                // /dev/sr0 pread fallback (Linux only). The kernel
+                // sr_mod driver auto-retries failed reads (~5× per
+                // command). Empirically (BU40N + Dune Part 2 UHD,
+                // 2026-05-08) dd via /dev/sr0 recovers ~50% of bad
+                // sectors that a single-shot SG_IO READ misses.
+                #[cfg(target_os = "linux")]
+                if recovery {
+                    if let Some(fd) = self.block_dev_fd {
+                        let len = count as usize * 2048;
+                        if buf.len() >= len {
+                            let offset = lba as i64 * 2048;
+                            // Drop kernel cache for this region so we get
+                            // a fresh device read, not stale page-cache
+                            // data from a prior successful neighbour read.
+                            let _ = unsafe {
+                                libc::posix_fadvise(
+                                    fd,
+                                    offset,
+                                    len as i64,
+                                    libc::POSIX_FADV_DONTNEED,
+                                )
+                            };
+                            let n = unsafe {
+                                libc::pread(fd, buf.as_mut_ptr() as *mut libc::c_void, len, offset)
+                            };
+                            if n == len as isize {
+                                tracing::info!(
+                                    target: "freemkv::drive",
+                                    lba,
+                                    count,
+                                    bytes = len,
+                                    "Drive::read recovered via /dev/sr0 pread fallback"
+                                );
+                                return Ok(len);
+                            }
+                            tracing::debug!(
+                                target: "freemkv::drive",
+                                lba,
+                                count,
+                                pread_ret = n as i64,
+                                errno = std::io::Error::last_os_error().raw_os_error().unwrap_or(0),
+                                "/dev/sr0 pread fallback also failed"
+                            );
+                        }
+                    }
+                }
+
                Err(Error::DiscRead {
                    sector: lba as u64,
                    status: Some(status),
@@ -586,10 +649,65 @@ impl Drop for Drive {
    fn drop(&mut self) {
        self.cleanup();
        // SgIoTransport::drop() runs next, calling libc::close(fd)
+        #[cfg(target_os = "linux")]
+        if let Some(fd) = self.block_dev_fd.take() {
+            unsafe { libc::close(fd) };
+        }
    }
 }

-impl SectorReader for Drive {
+/// Resolve a `/dev/sg*` path to the corresponding `/dev/sr*` block
+/// device by walking sysfs, then open it for read (no `O_DIRECT` —
+/// `posix_fadvise(POSIX_FADV_DONTNEED)` flushes the cache before each
+/// pread, which avoids buffer-alignment requirements while still
+/// forcing fresh device reads).
+///
+/// Returns `None` on any error (sysfs not present, no matching block
+/// device, open failed). Callers treat that as "no fallback available"
+/// and propagate the original SCSI READ error.
+#[cfg(target_os = "linux")]
+fn open_block_device_for_sg(sg_path: &Path) -> Option<std::os::unix::io::RawFd> {
+    let basename = sg_path.file_name()?.to_str()?;
+    if !basename.starts_with("sg") {
+        return None;
+    }
+    let sysfs_dir = format!("/sys/class/scsi_generic/{}/device/block", basename);
+    let entries = std::fs::read_dir(&sysfs_dir).ok()?;
+    let block_name = entries
+        .flatten()
+        .find_map(|e| e.file_name().into_string().ok())?;
+    let block_path = format!("/dev/{}", block_name);
+
+    let mut bytes = block_path.as_bytes().to_vec();
+    bytes.push(0);
+    let fd = unsafe {
+        libc::open(
+            bytes.as_ptr() as *const libc::c_char,
+            libc::O_RDONLY | libc::O_CLOEXEC,
+        )
+    };
+    if fd < 0 {
+        tracing::debug!(
+            target: "freemkv::drive",
+            sg = basename,
+            block_path,
+            errno = std::io::Error::last_os_error().raw_os_error().unwrap_or(0),
+            "Failed to open block device for fallback; sr0 fallback disabled"
+        );
+        None
+    } else {
+        tracing::info!(
+            target: "freemkv::drive",
+            sg = basename,
+            block_path,
+            fd,
+            "Opened /dev/sr* as recovery fallback for failed SCSI reads"
+        );
+        Some(fd)
+    }
+}
+
+impl SectorSource for Drive {
    fn read_sectors(
        &mut self,
        lba: u32,
@@ -0,0 +1,166 @@
+//! One-bit cooperative cancellation flag.
+//!
+//! `Halt` is a clonable token wrapping `Arc<AtomicBool>`. Pass clones into
+//! every long-running loop; the loop polls `is_cancelled()` and bails out
+//! cleanly. Calling `cancel()` from any clone flips the shared flag, and
+//! every other clone observes it on its next poll.
+//!
+//! Why: `Ordering::Relaxed` is sufficient on both load and store because
+//! this flag is purely advisory — no other memory operations piggyback on
+//! it for happens-before ordering. Callers that need to publish data
+//! across threads do so via channels or other synchronization, not via
+//! this bit.
+
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+/// Clonable, infallible cooperative-cancellation token.
+///
+/// Clones share the same underlying flag. `cancel()` is one-way; there is
+/// no `reset()` by design — construct a fresh `Halt` for a fresh
+/// operation.
+///
+/// Construct with [`Halt::new`] (or [`Halt::default`]). The `Default`
+/// impl forwards to `new()` — both produce a fresh, uncancelled token.
+/// The pair exists because clippy's `new_without_default` lint requires
+/// `Default` whenever a public `new()` is present, even when the two
+/// would do exactly the same thing.
+#[derive(Clone, Debug)]
+pub struct Halt(Arc<AtomicBool>);
+
+impl Halt {
+    /// Construct a fresh, uncancelled token.
+    pub fn new() -> Self {
+        Self(Arc::new(AtomicBool::new(false)))
+    }
+
+    /// Wrap an existing `Arc<AtomicBool>` as a `Halt`. Useful as a
+    /// bridge during the 0.18 deprecation window: callers that already
+    /// hold an `Arc<AtomicBool>` (e.g. `Drive::halt_flag()`, the
+    /// deprecated `DiscStream::set_halt`) can adopt the new token API
+    /// without changing the underlying flag.
+    ///
+    /// Cancelling either side flips the same bit — the wrapping `Halt`
+    /// and the original `Arc` are two views over one shared flag.
+    pub fn from_arc(flag: Arc<AtomicBool>) -> Self {
+        Self(flag)
+    }
+
+    /// Borrow the underlying `Arc<AtomicBool>`. Used at boundaries with
+    /// pre-`Halt` APIs that still take an `Arc<AtomicBool>` directly
+    /// (`CopyOptions::halt`, the deprecated `DiscStream::set_halt`).
+    /// Round 3 deletes those boundaries and this accessor with them.
+    pub fn as_arc(&self) -> &Arc<AtomicBool> {
+        &self.0
+    }
+
+    /// Flip the shared flag to cancelled. Idempotent.
+    pub fn cancel(&self) {
+        self.0.store(true, Ordering::Relaxed);
+    }
+
+    /// Read the shared flag.
+    pub fn is_cancelled(&self) -> bool {
+        self.0.load(Ordering::Relaxed)
+    }
+}
+
+impl Default for Halt {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn fresh_is_not_cancelled() {
+        let h = Halt::new();
+        assert!(!h.is_cancelled());
+    }
+
+    #[test]
+    fn cancel_flips_state() {
+        let h = Halt::new();
+        assert!(!h.is_cancelled());
+        h.cancel();
+        assert!(h.is_cancelled());
+    }
+
+    #[test]
+    fn cancel_is_idempotent() {
+        let h = Halt::new();
+        h.cancel();
+        h.cancel();
+        assert!(h.is_cancelled());
+    }
+
+    #[test]
+    fn clone_shares_state() {
+        let original = Halt::new();
+        let cloned = original.clone();
+        assert!(!original.is_cancelled());
+        assert!(!cloned.is_cancelled());
+
+        // Cancel via the clone; the original observes it.
+        cloned.cancel();
+        assert!(original.is_cancelled());
+        assert!(cloned.is_cancelled());
+    }
+
+    #[test]
+    fn clone_shares_state_reverse_direction() {
+        let original = Halt::new();
+        let cloned = original.clone();
+
+        // Cancel via the original; the clone observes it.
+        original.cancel();
+        assert!(cloned.is_cancelled());
+    }
+
+    #[test]
+    fn clone_shares_state_across_threads() {
+        let h = Halt::new();
+        let h2 = h.clone();
+        let handle = std::thread::spawn(move || {
+            h2.cancel();
+        });
+        handle.join().unwrap();
+        assert!(h.is_cancelled());
+    }
+
+    #[test]
+    fn from_arc_shares_state() {
+        // The 0.18 deprecation-window bridge: a Halt built from an
+        // existing Arc<AtomicBool> must be a *view* over the same bit,
+        // not a fresh copy. Cancelling either side flips both.
+        let arc = Arc::new(AtomicBool::new(false));
+        let halt = Halt::from_arc(arc.clone());
+        assert!(!halt.is_cancelled());
+        assert!(!arc.load(Ordering::Relaxed));
+
+        // Cancel via the wrapping Halt; the original Arc observes it.
+        halt.cancel();
+        assert!(arc.load(Ordering::Relaxed));
+
+        // Conversely: flip the Arc directly; the Halt view observes it.
+        let arc2 = Arc::new(AtomicBool::new(false));
+        let halt2 = Halt::from_arc(arc2.clone());
+        arc2.store(true, Ordering::Relaxed);
+        assert!(halt2.is_cancelled());
+    }
+
+    #[test]
+    fn as_arc_returns_backing_flag() {
+        // `as_arc()` must hand back the *same* Arc, not a clone of a
+        // different bit. Verified by writing through the borrowed Arc
+        // and observing through the Halt.
+        let halt = Halt::new();
+        let arc = halt.as_arc().clone();
+        assert!(!halt.is_cancelled());
+        arc.store(true, Ordering::Relaxed);
+        assert!(halt.is_cancelled());
+    }
+}
@@ -9,7 +9,7 @@

 use crate::disc::{Codec, Resolution};
 use crate::error::{Error, Result};
-use crate::sector::SectorReader;
+use crate::sector::SectorSource;
 use crate::udf::UdfFs;

 // ── Public types ────────────────────────────────────────────────────────────
@@ -184,7 +184,7 @@ fn bcd_byte(b: u8) -> u32 {
 ///
 /// Reads the VMG (Video Manager) to discover title sets, then reads each
 /// VTS IFO to extract PGC chains, cell addresses, and stream attributes.
-pub fn parse_vmg(reader: &mut dyn SectorReader, udf: &UdfFs) -> Result<DvdInfo> {
+pub fn parse_vmg(reader: &mut dyn SectorSource, udf: &UdfFs) -> Result<DvdInfo> {
    let vmg_data = udf.read_file(reader, "/VIDEO_TS/VIDEO_TS.IFO")?;

    // Validate VMG magic
@@ -263,7 +263,7 @@ pub fn parse_vmg(reader: &mut dyn SectorReader, udf: &UdfFs) -> Result<DvdInfo>
 ///
 /// `titles_info` is a list of (chapter_count, vts_title_number) from TT_SRPT.
 fn parse_vts(
-    reader: &mut dyn SectorReader,
+    reader: &mut dyn SectorSource,
    udf: &UdfFs,
    vts_number: u8,
    titles_info: &[(u16, u8)],
@@ -0,0 +1,246 @@
+//! Bounded-syscall primitive: run a (potentially-blocking) operation
+//! on a worker thread, with a hard wall-clock deadline and an optional
+//! cooperative [`Halt`] poll. The calling thread is never trapped
+//! inside a kernel call.
+//!
+//! ## Why this exists
+//!
+//! [`crate::halt::Halt`] is cooperative: callers poll
+//! `is_cancelled()`. It cannot reach inside a syscall the kernel
+//! currently owns the thread for — `libc::sync_file_range`,
+//! `libc::fsync`, `File::write` on NFS, and so on. `/api/stop` from
+//! autorip therefore can't unstick a thread sitting in such a syscall.
+//!
+//! [`bounded_syscall`] is the escape hatch: it runs `op` on a fresh
+//! worker thread, then `recv_timeout`s on a rendezvous channel for the
+//! result. The wait is broken into ~250 ms slices so the calling
+//! thread can poll the supplied [`Halt`] in between. If the deadline
+//! elapses or the halt fires, the worker is intentionally leaked — the
+//! syscall will unwind whenever the kernel decides, or at process
+//! exit, but the caller is free to fall back to a degraded code path
+//! (skip the sync, log loudly, etc.).
+//!
+//! ## Trade-offs
+//!
+//! - **Thread per call.** Cheap (`std::thread::spawn` is < 100 µs on
+//!   Linux/macOS), but not free. Use on coarse-grained finalisation
+//!   syscalls (`sync_all`, `sync_file_range(WAIT_AFTER)`), not on hot
+//!   inner-loop writes.
+//! - **Leak on timeout.** A wedged syscall keeps a kernel slot and a
+//!   user-space thread around for the rest of the process's life.
+//!   Bounded by the number of independent rip/mux sessions, which is
+//!   one per disc. The alternative — trapping the caller forever —
+//!   defeats the entire purpose of `/api/stop`.
+//! - **Halt granularity ~250 ms.** Halt observation is not instant;
+//!   it's the worst-case latency of the `recv_timeout` slice. Good
+//!   enough for human-driven stop requests; not suitable for hard
+//!   real-time deadlines.
+//!
+//! ## Single source of truth
+//!
+//! Do NOT inline this pattern. Every blocking-syscall wrapper in the
+//! rip + mux pipeline calls this helper, so changes (e.g. swapping the
+//! channel impl, adjusting the poll slice, adding metrics) land in one
+//! place.
+//!
+//! ## Platform
+//!
+//! Pure `std::thread` + `std::sync::mpsc`. No `cfg(target_os)` needed
+//! here — the helper itself is platform-agnostic. Callers that wrap
+//! Linux-only syscalls (`sync_file_range`) still need their own
+//! `#[cfg(target_os = "linux")]` gates; this helper does not.
+
+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);
+
+/// Failure outcome from a bounded syscall wrapper.
+#[derive(Debug)]
+pub(crate) enum BoundedError {
+    /// The user-visible halt token fired during the wait. The worker
+    /// thread is intentionally leaked — the caller should fall back to
+    /// a degraded code path rather than waiting on the syscall to
+    /// return.
+    Halted,
+    /// The deadline elapsed before the syscall returned. Same leak
+    /// semantics as `Halted`.
+    Timeout,
+    /// The worker thread panicked, or its sender disconnected before
+    /// sending a result. Treat as a benign no-op (callers usually
+    /// log and continue) rather than a hard error — by definition no
+    /// syscall observably ran to completion in this case.
+    WorkerLost,
+}
+
+/// Run a (potentially-blocking) operation on a worker thread with a
+/// deadline and an optional cooperative halt-token poll. Returns the
+/// operation's result if it completes within `timeout`; otherwise one
+/// of [`BoundedError::Halted`] / [`BoundedError::Timeout`] /
+/// [`BoundedError::WorkerLost`].
+///
+/// On `Halted` / `Timeout` the worker thread is intentionally leaked:
+/// the syscall will unwind whenever the kernel decides, or when the
+/// process exits. The calling thread is never trapped inside a kernel
+/// call.
+///
+/// `halt` is polled at [`POLL_INTERVAL`] granularity. Pass `None` for
+/// callers that don't (yet) have a halt token plumbed through —
+/// behaviour degrades to deadline-only, matching the 0.20.5
+/// `wait_after_with_timeout` shape this helper generalises.
+///
+/// `op` returns `R: Send + 'static`. The closure must own everything
+/// it touches because it may outlive this call (timeout / halt cases).
+pub(crate) fn bounded_syscall<F, R>(
+    halt: Option<&Halt>,
+    timeout: Duration,
+    op: F,
+) -> Result<R, BoundedError>
+where
+    F: FnOnce() -> R + Send + 'static,
+    R: Send + 'static,
+{
+    // Rendezvous channel: the worker sends exactly one value (the
+    // op's return) and then exits. Capacity-0 means the send blocks
+    // until we receive — fine on the happy path; on the timeout /
+    // halt path the receiver is dropped and the worker's send
+    // returns Err, which the worker ignores.
+    let (tx, rx) = sync_channel::<R>(0);
+    let _ = thread::Builder::new()
+        .name("freemkv-bounded-syscall".into())
+        .spawn(move || {
+            // Ignore the send error: if we time out (or get halted)
+            // before the worker finishes, the receiver is dropped
+            // and `tx.send` returns Err. Either way, the worker has
+            // nothing more to do.
+            let _ = tx.send(op());
+        });
+
+    let deadline = Instant::now() + timeout;
+    loop {
+        let now = Instant::now();
+        let remaining = deadline.saturating_duration_since(now);
+        let slice = remaining.min(POLL_INTERVAL);
+        match rx.recv_timeout(slice) {
+            Ok(v) => return Ok(v),
+            Err(RecvTimeoutError::Timeout) => {
+                if let Some(h) = halt {
+                    if h.is_cancelled() {
+                        return Err(BoundedError::Halted);
+                    }
+                }
+                if Instant::now() >= deadline {
+                    return Err(BoundedError::Timeout);
+                }
+                // Otherwise: another slice.
+            }
+            Err(RecvTimeoutError::Disconnected) => {
+                // Worker thread spawn failed, or it panicked before
+                // sending. Caller treats this as "no syscall ran" —
+                // typically a no-op + log.
+                return Err(BoundedError::WorkerLost);
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Arc;
+    use std::sync::atomic::{AtomicBool, Ordering};
+
+    #[test]
+    fn op_completes_quickly() {
+        let r = bounded_syscall(None, Duration::from_secs(2), || 42u32);
+        assert!(matches!(r, Ok(42)));
+    }
+
+    #[test]
+    fn op_exceeds_timeout() {
+        // Op sleeps longer than the deadline → Timeout.
+        let r = bounded_syscall(None, Duration::from_millis(300), || {
+            thread::sleep(Duration::from_secs(2));
+            0u32
+        });
+        assert!(matches!(r, Err(BoundedError::Timeout)));
+    }
+
+    #[test]
+    fn halt_fires_during_wait() {
+        let halt = Halt::new();
+        let halt2 = halt.clone();
+        // Flip the halt from a side thread after ~300 ms — long
+        // enough that the receive loop has rolled at least one
+        // 250 ms slice and is sitting in `recv_timeout` again when
+        // the bit flips.
+        thread::spawn(move || {
+            thread::sleep(Duration::from_millis(300));
+            halt2.cancel();
+        });
+        let r = bounded_syscall(Some(&halt), Duration::from_secs(5), || {
+            thread::sleep(Duration::from_secs(5));
+            0u32
+        });
+        assert!(matches!(r, Err(BoundedError::Halted)));
+    }
+
+    #[test]
+    fn worker_panics() {
+        // Worker panics → sender drops without sending → recv sees
+        // Disconnected → WorkerLost. We use an explicit panic in the
+        // op closure rather than `panic!()` from inside the channel
+        // machinery; the spawned thread's panic is contained (no
+        // process abort) because we don't `.join()` it.
+        let r = bounded_syscall(None, Duration::from_secs(2), || -> u32 {
+            panic!("intentional test panic");
+        });
+        assert!(matches!(r, Err(BoundedError::WorkerLost)));
+    }
+
+    #[test]
+    fn halt_already_set_before_call_still_returns_halted() {
+        // Halt observed on the very first poll slice. The op blocks
+        // forever; we must not wait the full timeout to notice the
+        // halt is already set.
+        let halt = Halt::new();
+        halt.cancel();
+        let started = Instant::now();
+        let r = bounded_syscall(Some(&halt), Duration::from_secs(10), || {
+            thread::sleep(Duration::from_secs(10));
+            0u32
+        });
+        assert!(matches!(r, Err(BoundedError::Halted)));
+        // Should bail out within ~1 s; allow 2 s of slack for slow
+        // CI hosts.
+        assert!(
+            started.elapsed() < Duration::from_secs(2),
+            "halt-already-set took {:?}",
+            started.elapsed()
+        );
+    }
+
+    #[test]
+    fn ok_path_takes_no_halt_token() {
+        // Sanity: the `None` halt path is the documented zero-config
+        // form (matches the 0.20.5 `wait_after_with_timeout`
+        // behaviour). Op returns immediately; we must observe Ok.
+        let flag = Arc::new(AtomicBool::new(false));
+        let f2 = flag.clone();
+        let r = bounded_syscall(None, Duration::from_secs(2), move || {
+            f2.store(true, Ordering::Relaxed);
+            "ok"
+        });
+        assert!(matches!(r, Ok("ok")));
+        assert!(flag.load(Ordering::Relaxed));
+    }
+}
@@ -0,0 +1,34 @@
+//! File I/O helpers that bound kernel cache pressure on big writes.
+//!
+//! `WritebackFile` is a drop-in wrapper around `std::fs::File` for any
+//! call site that performs large sequential writes (sweep, patch, mux,
+//! etc.). It implements `Write` and `Seek` so existing code paths can
+//! swap `File` for `WritebackFile` with no body changes. Internally it
+//! drives a `WritebackPipeline` that, on Linux, drains dirty pages
+//! continuously at 32 MB granularity to avoid the kernel's
+//! accumulate-then-burst flush behaviour. macOS and Windows use a
+//! no-op pipeline — their default cache policies have not been shown
+//! to exhibit the same pathology for this access pattern.
+//!
+//! `Pipeline` + `Sink` (0.18) is the generic producer/consumer primitive
+//! used by sweep, patch, and mux to overlap reads with writes via a
+//! bounded channel + dedicated consumer thread.
+
+pub(crate) mod bounded;
+mod writeback;
+mod writeback_file;
+
+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)]
+pub use pipeline::{
+    DEFAULT_PIPELINE_DEPTH, Flow, Pipeline, READ_PIPELINE_DEPTH, Sink, WRITE_PIPELINE_DEPTH,
+    WRITE_THROUGH_DEPTH,
+};
@@ -0,0 +1,893 @@
+//! Generic bounded producer/consumer pipeline.
+//!
+//! `Pipeline<I, R>` spawns a single consumer thread, hands it items
+//! through a bounded `mpsc::sync_channel`, and joins it on `finish()`.
+//! The consumer's behaviour is supplied by a [`Sink`] implementation:
+//! `apply` is called once per item, `close` is called once at the end.
+//!
+//! Three call sites in libfreemkv want a producer/consumer split —
+//! sweep (migrated to `disc/sweep.rs::SweepSink`), patch, and mux.
+//! 0.18 collapses all three onto this primitive; sweep is in,
+//! patch and mux migrate in later 0.18 slices.
+//! See `(internal)/memory/0_18_redesign.md` for the full picture.
+//!
+//! ## Cancellation and error semantics
+//!
+//! - Producer dropping the channel (via `Pipeline::finish` dropping
+//!   `tx`) signals end-of-stream; consumer flushes via `close()` and
+//!   returns its `Output`.
+//! - Consumer returning [`Flow::Stop`] also calls `close()` and
+//!   returns its `Output`. `send()` from the producer will then either
+//!   succeed (if the item already fit in the channel buffer) or fail
+//!   with `Err(item)` once the consumer has dropped its receiver.
+//! - Consumer returning `Err` from `apply` skips `close()` entirely;
+//!   the consumer keeps draining the channel so the producer never
+//!   blocks on a dead receiver, and the first error is propagated as
+//!   the `JoinHandle` result.
+//! - Consumer panic is converted into
+//!   `Error::IoError { source: io::Error::other(...) }`.
+//!
+//! ## Debug logging
+//!
+//! Set `FREEMKV_DEBUG=1` environment variable to enable verbose debug
+//! logging throughout the pipeline (channel sends/receives, backpressure,
+//! consumer lag detection). This is critical for diagnosing stalls.
+
+use std::io;
+use std::sync::mpsc::{SyncSender, TrySendError, sync_channel};
+use std::thread::{self, JoinHandle};
+use std::time::{Duration, Instant};
+
+use crate::error::Error;
+use crate::halt::Halt;
+
+/// Deadline for [`Pipeline::finish_with_halt`]'s polling join. Chosen
+/// to be comfortably longer than the autorip hard watchdog
+/// (`HARD_WATCHDOG_STALL_SECS = 300s`) so the watchdog's `exit(1)`
+/// fires first when both are racing on the same wedged consumer.
+///
+/// 10 minutes is a backstop, not a normal timeout — the consumer is
+/// expected to drain in seconds. If we hit this, something is wedged
+/// inside a kernel call the consumer thread can't unwind from, and the
+/// 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);
+
+/// Polling slice for the halt-aware send loop. Smaller than
+/// [`POLL_INTERVAL`] because send latency tolerance is much lower —
+/// frames must move through the channel at hundreds-of-Hz on the
+/// happy path; 50 ms keeps backpressure-driven wakeups fine-grained
+/// without busy-looping.
+const SEND_POLL_INTERVAL: Duration = Duration::from_millis(50);
+
+/// Check if verbose debug logging is enabled via FREEMKV_DEBUG env var.
+pub fn debug_enabled() -> bool {
+    std::env::var("FREEMKV_DEBUG")
+        .ok()
+        .map(|v| v == "1" || v == "true" || v == "yes")
+        .unwrap_or(false)
+}
+
+/// Default channel depth for callers without a specific reason to
+/// pick another value. Kept conservative (4) — most callers should
+/// use READ_PIPELINE_DEPTH or WRITE_PIPELINE_DEPTH instead.
+pub const DEFAULT_PIPELINE_DEPTH: usize = 4;
+
+/// Read pipeline depth. Larger buffer compensates for drive variability
+/// and NFS sync_file_range stalls; keeps ISO reader thread fed even when
+/// consumer blocks on write.
+pub const READ_PIPELINE_DEPTH: usize = 32;
+
+/// Write pipeline depth. Smaller buffer reduces backpressure risk when
+/// sync_file_range blocks; prevents producer from accumulating too much
+/// work while consumer waits for NFS to drain.
+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)]
+pub const WRITE_THROUGH_DEPTH: usize = 1;
+
+/// Outcome of [`Sink::apply`]: either keep feeding items
+/// ([`Flow::Continue`]), or stop the pipeline early and run `close()`
+/// ([`Flow::Stop`]).
+///
+/// `Stop` has no in-tree caller in this slice — sweep never returns
+/// it (it always processes the producer's full work-list before the
+/// channel is dropped). Patch and mux are the intended consumers and
+/// migrate in later 0.18 slices. The variant ships now so the contract
+/// is fixed; the targeted `#[allow]` is removed when patch lands.
+pub enum Flow {
+    Continue,
+    #[allow(dead_code)]
+    Stop,
+}
+
+/// Consumer-side of a [`Pipeline`]. The pipeline owns one of these on
+/// its consumer thread and calls `apply` once per received item, then
+/// `close` once at end-of-stream.
+pub trait Sink<I>: Send + 'static {
+    /// Type returned from `close()` and surfaced via
+    /// [`Pipeline::finish`].
+    type Output: Send + 'static;
+
+    /// Apply one item. Returning [`Flow::Continue`] keeps the
+    /// pipeline running; [`Flow::Stop`] ends it cleanly (still calls
+    /// `close()`). An error short-circuits: `close()` is *not* called
+    /// and the error is what `finish()` will return, but the consumer
+    /// keeps draining the channel so the producer never blocks on a
+    /// dead receiver.
+    fn apply(&mut self, item: I) -> Result<Flow, Error>;
+
+    /// Called once at end-of-stream — either because the producer
+    /// dropped `tx` or because `apply` returned [`Flow::Stop`]. Use
+    /// this to flush, fsync, finalise. Skipped if any prior `apply`
+    /// returned `Err`.
+    fn close(self) -> Result<Self::Output, Error>;
+}
+
+/// Bounded producer/consumer pipeline. Holds the producer-side
+/// channel and the consumer thread's join handle.
+pub struct Pipeline<I: Send + 'static, R: Send + 'static> {
+    tx: SyncSender<I>,
+    handle: JoinHandle<Result<R, Error>>,
+}
+
+impl<I: Send + 'static, R: Send + 'static> Pipeline<I, R> {
+    /// Spawn the consumer thread with the given channel depth and
+    /// [`Sink`].
+    ///
+    /// The thread is named `freemkv-pipeline-consumer` so it shows up
+    /// distinctly in stack traces and `top -H`. Callers that want a
+    /// more specific name (e.g. `freemkv-sweep-consumer`) should use
+    /// [`Pipeline::spawn_named`] instead. Returns an `Error::IoError`
+    /// if the OS refuses the thread spawn (resource exhaustion);
+    /// callers already operate in fallible context, so this is
+    /// 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)]
+    pub fn spawn<S: Sink<I, Output = R>>(depth: usize, sink: S) -> Result<Self, Error> {
+        Self::spawn_named("freemkv-pipeline-consumer", depth, sink)
+    }
+
+    /// Like [`Pipeline::spawn`] but lets the caller supply the
+    /// consumer thread's name. Useful when several pipelines run in
+    /// the same process and stack traces / `top -H` need to tell them
+    /// apart (e.g. `freemkv-sweep-consumer`, `freemkv-mux-consumer`).
+    pub fn spawn_named<S: Sink<I, Output = R>>(
+        name: &str,
+        depth: usize,
+        sink: S,
+    ) -> Result<Self, Error> {
+        let (tx, rx) = sync_channel::<I>(depth);
+        let handle = thread::Builder::new()
+            .name(name.into())
+            .spawn(move || -> Result<R, Error> {
+                let mut sink = sink;
+                let mut first_err: Option<Error> = None;
+                let mut stopped = false;
+
+                while let Ok(item) = rx.recv() {
+                    if debug_enabled() {
+                        tracing::debug!("Pipeline receive: item={}", std::any::type_name::<I>());
+                    }
+
+                    let apply_start = std::time::Instant::now();
+
+                    if first_err.is_some() || stopped {
+                        // Drain remaining items so the producer never
+                        // blocks on a dead receiver. `apply` is not
+                        // called once we've decided to stop.
+                        continue;
+                    }
+                    match sink.apply(item) {
+                        Ok(Flow::Continue) => {}
+                        Ok(Flow::Stop) => {
+                            stopped = true;
+                            if debug_enabled() {
+                                tracing::debug!("Pipeline: consumer returned Flow::Stop");
+                            }
+                        }
+                        Err(e) => {
+                            if debug_enabled() {
+                                tracing::debug!("Pipeline: apply error, stopping, err={:?}", e);
+                            }
+                            first_err = Some(e);
+                        }
+                    }
+
+                    let apply_elapsed = apply_start.elapsed();
+                    if debug_enabled() && apply_elapsed > std::time::Duration::from_millis(100) {
+                        tracing::debug!(
+                            "Pipeline apply: took {:.2}s, item={}",
+                            apply_elapsed.as_secs_f64(),
+                            std::any::type_name::<I>()
+                        );
+                    } else if debug_enabled() {
+                        tracing::debug!(
+                            "Pipeline apply: OK in {:.3}ms, item={}",
+                            apply_elapsed.as_micros(),
+                            std::any::type_name::<I>()
+                        );
+                    }
+                }
+
+                match first_err {
+                    Some(e) => Err(e),
+                    None => sink.close(),
+                }
+            })
+            .map_err(|e| Error::IoError { source: e })?;
+
+        Ok(Pipeline { tx, handle })
+    }
+
+    /// Push one item. Blocks if the channel is full — that's the
+    /// back-pressure the whole primitive exists to provide. Returns
+    /// the item back if the consumer thread is gone (panicked or
+    /// already returned).
+    ///
+    /// After the consumer returns [`Flow::Stop`], `send` will silently
+    /// buffer items into the channel until the channel fills, then
+    /// return `Err(item)` once the consumer has dropped its receiver.
+    /// Producers that need to stop pushing on `Stop` should track an
+    /// independent signal (e.g. `Halt`) — `send` alone is not the
+    /// notification edge.
+    pub fn send(&self, item: I) -> Result<(), I> {
+        let start = std::time::Instant::now();
+        match self.tx.send(item) {
+            Ok(()) => {
+                let elapsed = start.elapsed();
+                if debug_enabled() && elapsed > std::time::Duration::from_millis(10) {
+                    tracing::debug!(
+                        "Pipeline send: blocked {:.2}s, item={}",
+                        elapsed.as_secs_f64(),
+                        std::any::type_name::<I>()
+                    );
+                } else if debug_enabled() {
+                    tracing::debug!("Pipeline send: OK in {:.3}ms", elapsed.as_micros());
+                }
+                Ok(())
+            }
+            Err(e) => {
+                let elapsed = start.elapsed();
+                if debug_enabled() && elapsed > std::time::Duration::from_millis(10) {
+                    tracing::debug!(
+                        "Pipeline send: blocked {:.2}s before channel closed, item={}",
+                        elapsed.as_secs_f64(),
+                        std::any::type_name::<I>()
+                    );
+                } else if debug_enabled() {
+                    tracing::debug!("Pipeline send: failed after {:.3}ms", elapsed.as_micros());
+                }
+                Err(e.0)
+            }
+        }
+    }
+
+    /// Non-blocking variant of [`Pipeline::send`]. If the channel is
+    /// full or the consumer has hung up, the item is returned in
+    /// `Err`. Useful for best-effort signalling (e.g. sweep's
+    /// throttled `StatsRequest`) where dropping the message is
+    /// preferable to blocking the producer.
+    pub fn try_send(&self, item: I) -> Result<(), std::sync::mpsc::TrySendError<I>> {
+        self.tx.try_send(item)
+    }
+
+    /// Halt-aware bounded variant of [`Pipeline::send`].
+    ///
+    /// Polls `try_send` on a 50 ms slice. Between slices, checks
+    /// (1) the [`Halt`] token and (2) the per-call `deadline`. Returns:
+    ///
+    /// - `Ok(())` once the item lands in the channel.
+    /// - `Err(item)` if the consumer disconnected, the halt fired, or
+    ///   the deadline elapsed — the caller gets the item back so it
+    ///   can decide whether to drop it, route it elsewhere, or unwind.
+    ///
+    /// Use this in producer threads that have a `Halt` token threaded
+    /// through (mux, sweep, patch). Plain [`Pipeline::send`] is
+    /// preserved for callers that don't (yet) plumb halt through.
+    ///
+    /// Unlike [`Pipeline::send`], this never blocks the producer
+    /// thread inside an unkillable `mpsc::send` — if the consumer is
+    /// wedged inside an unkillable syscall, the producer can still
+    /// observe `/api/stop` and unwind.
+    pub fn send_with_halt(&self, item: I, halt: &Halt, deadline: Duration) -> Result<(), I> {
+        let end = Instant::now() + deadline;
+        let mut pending = item;
+        loop {
+            match self.tx.try_send(pending) {
+                Ok(()) => return Ok(()),
+                Err(TrySendError::Full(returned)) => {
+                    pending = returned;
+                    if halt.is_cancelled() {
+                        if debug_enabled() {
+                            tracing::debug!(
+                                "Pipeline send_with_halt: halt observed, returning item={}",
+                                std::any::type_name::<I>()
+                            );
+                        }
+                        return Err(pending);
+                    }
+                    if Instant::now() >= end {
+                        if debug_enabled() {
+                            tracing::debug!(
+                                "Pipeline send_with_halt: deadline elapsed, returning item={}",
+                                std::any::type_name::<I>()
+                            );
+                        }
+                        return Err(pending);
+                    }
+                    thread::sleep(SEND_POLL_INTERVAL);
+                }
+                Err(TrySendError::Disconnected(returned)) => {
+                    if debug_enabled() {
+                        tracing::debug!(
+                            "Pipeline send_with_halt: consumer disconnected, item={}",
+                            std::any::type_name::<I>()
+                        );
+                    }
+                    return Err(returned);
+                }
+            }
+        }
+    }
+
+    /// Drop the producer-side channel and wait for the consumer
+    /// thread to finish. Returns whatever the consumer's `close()`
+    /// produced, or the first `apply` error, or — on consumer panic —
+    /// an `Error::IoError` whose source is `io::Error::other(...)`
+    /// with a "pipeline consumer panicked: <payload>" message
+    /// (callers can match on the constant prefix).
+    pub fn finish(self) -> Result<R, Error> {
+        let Pipeline { tx, handle } = self;
+        // Explicit drop, although the destructure already drops `tx`
+        // at end-of-scope. Being explicit keeps the intent obvious.
+        drop(tx);
+        match handle.join() {
+            Ok(result) => result,
+            Err(payload) => {
+                // Preserve the original panic message when the
+                // consumer's panic payload was a `&str` or `String`
+                // (the two stdlib formats that `panic!` produces).
+                // Anything else falls back to "(no message)".
+                let msg = payload
+                    .downcast_ref::<&'static str>()
+                    .copied()
+                    .or_else(|| payload.downcast_ref::<String>().map(|s| s.as_str()))
+                    .unwrap_or("(no message)");
+                Err(Error::IoError {
+                    source: io::Error::other(format!("pipeline consumer panicked: {msg}")),
+                })
+            }
+        }
+    }
+
+    /// Halt-aware, deadline-bounded variant of [`Pipeline::finish`].
+    ///
+    /// Drops the producer-side channel (same as `finish`) and then
+    /// polls `JoinHandle::is_finished()` on a 250 ms cadence. Between
+    /// slices, checks (1) the optional [`Halt`] token and (2) the
+    /// [`JOIN_TIMEOUT_SECS`] deadline. Returns:
+    ///
+    /// - `Ok(R)` on a clean consumer exit.
+    /// - `Err(Error::IoError)` with one of three message prefixes for
+    ///   wedge cases:
+    ///   - `"pipeline join halted"` — halt fired while waiting.
+    ///   - `"pipeline join timed out"` — `JOIN_TIMEOUT_SECS` elapsed.
+    ///   - `"pipeline consumer panicked"` — same as `finish()`.
+    ///
+    /// In the `halted` and `timed out` branches the consumer thread is
+    /// intentionally leaked — exactly the same trade-off the
+    /// `bounded_syscall` primitive makes. The wedged kernel call
+    /// inside the consumer will unwind whenever it does, or at
+    /// process exit. The caller is free to fall back to a degraded
+    /// path (in autorip's case: `exit(1)` after the hard watchdog
+    /// escalation, letting Docker restart the container).
+    ///
+    /// Plain [`Pipeline::finish`] is preserved for callers without a
+    /// halt-token plumbed through; that path still blocks indefinitely
+    /// on `join()`, matching pre-0.20.8 behaviour.
+    pub fn finish_with_halt(self, halt: Option<&Halt>) -> Result<R, Error> {
+        let Pipeline { tx, handle } = self;
+        drop(tx);
+        let deadline = Instant::now() + Duration::from_secs(JOIN_TIMEOUT_SECS);
+        loop {
+            if handle.is_finished() {
+                return match handle.join() {
+                    Ok(result) => result,
+                    Err(payload) => {
+                        let msg = payload
+                            .downcast_ref::<&'static str>()
+                            .copied()
+                            .or_else(|| payload.downcast_ref::<String>().map(|s| s.as_str()))
+                            .unwrap_or("(no message)");
+                        Err(Error::IoError {
+                            source: io::Error::other(format!("pipeline consumer panicked: {msg}")),
+                        })
+                    }
+                };
+            }
+            if let Some(h) = halt {
+                if h.is_cancelled() {
+                    // Consumer thread is intentionally leaked.
+                    return Err(Error::IoError {
+                        source: io::Error::other("pipeline join halted"),
+                    });
+                }
+            }
+            if Instant::now() >= deadline {
+                // Consumer thread is intentionally leaked.
+                return Err(Error::IoError {
+                    source: io::Error::other("pipeline join timed out"),
+                });
+            }
+            thread::sleep(POLL_INTERVAL);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Arc;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+    use std::time::{Duration, Instant};
+
+    /// Sums u64s; returns the total from `close`.
+    struct SumSink {
+        total: u64,
+    }
+
+    impl Sink<u64> for SumSink {
+        type Output = u64;
+
+        fn apply(&mut self, item: u64) -> Result<Flow, Error> {
+            self.total += item;
+            Ok(Flow::Continue)
+        }
+
+        fn close(self) -> Result<u64, Error> {
+            Ok(self.total)
+        }
+    }
+
+    #[test]
+    fn happy_path_sums_items() {
+        let pipe = Pipeline::spawn(DEFAULT_PIPELINE_DEPTH, SumSink { total: 0 })
+            .expect("spawn should succeed");
+        let mut expected = 0u64;
+        for i in 0..100u64 {
+            expected += i;
+            pipe.send(i).expect("send should succeed");
+        }
+        let total = pipe.finish().expect("finish should succeed");
+        assert_eq!(total, expected);
+        assert_eq!(total, (0..100u64).sum::<u64>());
+    }
+
+    /// Sleeps `delay` per apply; counts how many it received.
+    struct SlowSink {
+        delay: Duration,
+        count: Arc<AtomicUsize>,
+    }
+
+    impl Sink<()> for SlowSink {
+        type Output = usize;
+
+        fn apply(&mut self, _item: ()) -> Result<Flow, Error> {
+            std::thread::sleep(self.delay);
+            self.count.fetch_add(1, Ordering::SeqCst);
+            Ok(Flow::Continue)
+        }
+
+        fn close(self) -> Result<usize, Error> {
+            Ok(self.count.load(Ordering::SeqCst))
+        }
+    }
+
+    #[test]
+    fn back_pressure_blocks_sender() {
+        // depth=2 + 5 sends + 50ms/apply: with the consumer pinned at
+        // 50 ms per item, the producer can buffer 2 (channel cap) +
+        // 1 (consumer in flight) = 3 items before sends 4 and 5 must
+        // block on consumer progress. Wall-clock floor across all 5
+        // sends is therefore ~2 * 50ms = 100ms (sends 4 and 5 each
+        // wait roughly one apply-cycle). Use 80 ms as the assertion
+        // floor to stay above the 50ms-per-item progress floor while
+        // tolerating CI jitter — it still proves blocking is real.
+        let count = Arc::new(AtomicUsize::new(0));
+        let sink = SlowSink {
+            delay: Duration::from_millis(50),
+            count: count.clone(),
+        };
+        let pipe = Pipeline::spawn(2, sink).expect("spawn should succeed");
+
+        let start = Instant::now();
+        for _ in 0..5 {
+            pipe.send(()).expect("send should succeed");
+        }
+        let elapsed_send = start.elapsed();
+
+        let total = pipe.finish().expect("finish should succeed");
+        assert_eq!(total, 5);
+        assert!(
+            elapsed_send >= Duration::from_millis(80),
+            "back-pressure not observed: 5 sends with depth=2 and 50ms/apply \
+             took {elapsed_send:?}, expected ≥ ~100ms (one or more sends \
+             should have blocked behind the consumer)"
+        );
+    }
+
+    /// Returns `Err` on the Nth apply (1-indexed). Tracks all calls.
+    struct FailOnNthSink {
+        n: usize,
+        seen: Arc<AtomicUsize>,
+        close_called: Arc<AtomicUsize>,
+    }
+
+    impl Sink<u64> for FailOnNthSink {
+        type Output = ();
+
+        fn apply(&mut self, _item: u64) -> Result<Flow, Error> {
+            let i = self.seen.fetch_add(1, Ordering::SeqCst) + 1;
+            if i == self.n {
+                Err(Error::DecryptFailed)
+            } else {
+                Ok(Flow::Continue)
+            }
+        }
+
+        fn close(self) -> Result<(), Error> {
+            self.close_called.fetch_add(1, Ordering::SeqCst);
+            Ok(())
+        }
+    }
+
+    #[test]
+    fn apply_error_drains_then_propagates() {
+        let seen = Arc::new(AtomicUsize::new(0));
+        let close_called = Arc::new(AtomicUsize::new(0));
+        let pipe = Pipeline::spawn(
+            DEFAULT_PIPELINE_DEPTH,
+            FailOnNthSink {
+                n: 3,
+                seen: seen.clone(),
+                close_called: close_called.clone(),
+            },
+        )
+        .expect("spawn should succeed");
+
+        // Send 10 items. Subsequent sends after the 3rd error must
+        // still succeed (the consumer is draining).
+        for i in 0..10u64 {
+            pipe.send(i).expect("send should succeed even after error");
+        }
+
+        let res = pipe.finish();
+        assert!(matches!(res, Err(Error::DecryptFailed)));
+        assert_eq!(
+            close_called.load(Ordering::SeqCst),
+            0,
+            "close() must not be called when apply returned Err"
+        );
+        // The consumer kept calling `recv` to drain after the error;
+        // it just stopped invoking `apply`. So `seen` is exactly 3
+        // (apply was called for items 1, 2, 3).
+        assert_eq!(seen.load(Ordering::SeqCst), 3);
+    }
+
+    /// Returns `Flow::Stop` on the Nth apply.
+    struct StopOnNthSink {
+        n: usize,
+        seen: Arc<AtomicUsize>,
+        close_called: Arc<AtomicUsize>,
+    }
+
+    impl Sink<u64> for StopOnNthSink {
+        type Output = usize;
+
+        fn apply(&mut self, _item: u64) -> Result<Flow, Error> {
+            let i = self.seen.fetch_add(1, Ordering::SeqCst) + 1;
+            if i >= self.n {
+                Ok(Flow::Stop)
+            } else {
+                Ok(Flow::Continue)
+            }
+        }
+
+        fn close(self) -> Result<usize, Error> {
+            self.close_called.fetch_add(1, Ordering::SeqCst);
+            Ok(self.seen.load(Ordering::SeqCst))
+        }
+    }
+
+    #[test]
+    fn apply_stop_calls_close_and_returns_output() {
+        let seen = Arc::new(AtomicUsize::new(0));
+        let close_called = Arc::new(AtomicUsize::new(0));
+        let pipe = Pipeline::spawn(
+            DEFAULT_PIPELINE_DEPTH,
+            StopOnNthSink {
+                n: 3,
+                seen: seen.clone(),
+                close_called: close_called.clone(),
+            },
+        )
+        .expect("spawn should succeed");
+
+        // Send 10 items. After Stop, subsequent sends may either
+        // succeed (already buffered) or fail with Err(I) (channel
+        // closed). Both are valid — we don't assert on the send
+        // results.
+        for i in 0..10u64 {
+            let _ = pipe.send(i);
+        }
+
+        let out = pipe.finish().expect("finish should succeed after Stop");
+        assert_eq!(close_called.load(Ordering::SeqCst), 1);
+        // At least 3 items processed (the one that returned Stop).
+        assert!(
+            out >= 3,
+            "expected ≥ 3 applies before Stop took effect, got {out}"
+        );
+    }
+
+    /// Panics on the first apply call.
+    struct PanickingSink;
+
+    impl Sink<u64> for PanickingSink {
+        type Output = ();
+
+        fn apply(&mut self, _item: u64) -> Result<Flow, Error> {
+            panic!("synthetic test panic");
+        }
+
+        fn close(self) -> Result<(), Error> {
+            Ok(())
+        }
+    }
+
+    #[test]
+    fn consumer_panic_becomes_io_error() {
+        // Silence the panic message that would otherwise pollute the
+        // test output — we expect this panic.
+        let prev = std::panic::take_hook();
+        std::panic::set_hook(Box::new(|_| {}));
+
+        let pipe =
+            Pipeline::spawn(DEFAULT_PIPELINE_DEPTH, PanickingSink).expect("spawn should succeed");
+        // First send may succeed (item buffered before panic) or fail
+        // (channel closed after panic) — either is fine.
+        let _ = pipe.send(1);
+        // Drain a few more sends; once the channel is closed they'll
+        // return Err(I), which we just discard.
+        for i in 0..5u64 {
+            let _ = pipe.send(i);
+        }
+        let res = pipe.finish();
+
+        std::panic::set_hook(prev);
+
+        match res {
+            Err(Error::IoError { source }) => {
+                let msg = source.to_string();
+                // Constant prefix lets callers match without parsing
+                // the variable payload tail.
+                assert!(
+                    msg.contains("pipeline consumer panicked"),
+                    "expected constant panic prefix, got: {msg}"
+                );
+                // The original `panic!` payload (a `&'static str`) must
+                // be preserved — without the downcast the message
+                // would just be the prefix.
+                assert!(
+                    msg.contains("synthetic test panic"),
+                    "expected original panic payload, got: {msg}"
+                );
+            }
+            other => panic!("expected Err(IoError), got {other:?}"),
+        }
+    }
+
+    /// Never-completing sink — `apply` blocks until cancelled. Signals
+    /// `started` once it has consumed its first item so the test
+    /// driver knows the consumer thread is wedged in `apply` (and
+    /// will no longer drain the channel). Used to drive the
+    /// halt/timeout paths of `send_with_halt` and `finish_with_halt`
+    /// without depending on real I/O.
+    struct NeverDrainsSink {
+        cancel: Arc<std::sync::atomic::AtomicBool>,
+        started: Arc<std::sync::atomic::AtomicBool>,
+    }
+
+    impl Sink<u64> for NeverDrainsSink {
+        type Output = ();
+
+        fn apply(&mut self, _item: u64) -> Result<Flow, Error> {
+            self.started.store(true, Ordering::SeqCst);
+            while !self.cancel.load(Ordering::SeqCst) {
+                std::thread::sleep(Duration::from_millis(20));
+            }
+            Ok(Flow::Continue)
+        }
+
+        fn close(self) -> Result<(), Error> {
+            Ok(())
+        }
+    }
+
+    /// Spin until `started` flips or `bail` elapses. Used by the
+    /// send_with_halt tests to synchronise with the consumer thread
+    /// before exercising the bounded-send timeout path.
+    fn wait_for_started(started: &Arc<std::sync::atomic::AtomicBool>, bail: Duration) {
+        let end = Instant::now() + bail;
+        while !started.load(Ordering::SeqCst) {
+            assert!(Instant::now() < end, "consumer never started apply()");
+            std::thread::sleep(Duration::from_millis(10));
+        }
+    }
+
+    #[test]
+    fn send_with_halt_returns_item_on_deadline() {
+        // depth=1 + consumer wedged in apply on the first item, AND
+        // the channel buffer already loaded with a second item, means
+        // any further `try_send` sees Full; with a 200 ms deadline and
+        // no halt fired, send_with_halt must return `Err(item)` within
+        // roughly the deadline. Synchronising on `started` ensures the
+        // consumer has actually started its wedged apply BEFORE we
+        // load the channel-buffer slot — without that, the consumer
+        // could still drain in a race window.
+        let cancel = Arc::new(std::sync::atomic::AtomicBool::new(false));
+        let started = Arc::new(std::sync::atomic::AtomicBool::new(false));
+        let pipe = Pipeline::spawn(
+            1,
+            NeverDrainsSink {
+                cancel: cancel.clone(),
+                started: started.clone(),
+            },
+        )
+        .expect("spawn should succeed");
+        // First send: consumer recv()s it and wedges in apply.
+        pipe.send(0u64).expect("first send hands off to consumer");
+        wait_for_started(&started, Duration::from_secs(2));
+        // Second send: lands in the depth=1 buffer slot, consumer
+        // can't pick it up because it's wedged in apply. Channel now
+        // full from the producer's perspective.
+        pipe.send(1u64).expect("second send fills the buffer");
+
+        let halt = crate::halt::Halt::new();
+        let start = Instant::now();
+        let res = pipe.send_with_halt(99u64, &halt, Duration::from_millis(200));
+        let elapsed = start.elapsed();
+
+        // Release the leaked consumer so the test process winds down.
+        cancel.store(true, Ordering::SeqCst);
+        let _ = pipe.finish();
+
+        assert!(matches!(res, Err(99)), "expected item returned on deadline");
+        assert!(
+            elapsed >= Duration::from_millis(150),
+            "deadline returned too early: {elapsed:?}"
+        );
+        assert!(
+            elapsed < Duration::from_secs(2),
+            "deadline blew past tolerance: {elapsed:?}"
+        );
+    }
+
+    #[test]
+    fn send_with_halt_returns_item_on_halt() {
+        // Same setup, but the halt fires before the deadline elapses.
+        // The send loop must observe the halt within ~50 ms (the
+        // SEND_POLL_INTERVAL) and return the item.
+        let cancel = Arc::new(std::sync::atomic::AtomicBool::new(false));
+        let started = Arc::new(std::sync::atomic::AtomicBool::new(false));
+        let pipe = Pipeline::spawn(
+            1,
+            NeverDrainsSink {
+                cancel: cancel.clone(),
+                started: started.clone(),
+            },
+        )
+        .expect("spawn should succeed");
+        pipe.send(0u64).expect("first send hands off to consumer");
+        wait_for_started(&started, Duration::from_secs(2));
+        pipe.send(1u64).expect("second send fills the buffer");
+
+        let halt = crate::halt::Halt::new();
+        let halt2 = halt.clone();
+        std::thread::spawn(move || {
+            std::thread::sleep(Duration::from_millis(100));
+            halt2.cancel();
+        });
+
+        let start = Instant::now();
+        let res = pipe.send_with_halt(7u64, &halt, Duration::from_secs(10));
+        let elapsed = start.elapsed();
+
+        cancel.store(true, Ordering::SeqCst);
+        let _ = pipe.finish();
+
+        assert!(matches!(res, Err(7)), "expected item returned on halt");
+        assert!(
+            elapsed < Duration::from_secs(2),
+            "halt observation took too long: {elapsed:?}"
+        );
+    }
+
+    #[test]
+    fn finish_with_halt_returns_halted_when_consumer_wedged() {
+        // Consumer wedges on the first apply; halt fires; finish
+        // returns the documented "pipeline join halted" error rather
+        // than blocking forever.
+        let cancel = Arc::new(std::sync::atomic::AtomicBool::new(false));
+        let started = Arc::new(std::sync::atomic::AtomicBool::new(false));
+        let pipe = Pipeline::spawn(
+            DEFAULT_PIPELINE_DEPTH,
+            NeverDrainsSink {
+                cancel: cancel.clone(),
+                started: started.clone(),
+            },
+        )
+        .expect("spawn should succeed");
+        pipe.send(0u64).expect("seed item the consumer wedges on");
+        wait_for_started(&started, Duration::from_secs(2));
+
+        let halt = crate::halt::Halt::new();
+        let halt2 = halt.clone();
+        std::thread::spawn(move || {
+            std::thread::sleep(Duration::from_millis(400));
+            halt2.cancel();
+        });
+
+        let start = Instant::now();
+        let res = pipe.finish_with_halt(Some(&halt));
+        let elapsed = start.elapsed();
+
+        // Release the leaked consumer so the test process exits cleanly.
+        cancel.store(true, Ordering::SeqCst);
+
+        match res {
+            Err(Error::IoError { source }) => {
+                assert!(
+                    source.to_string().contains("pipeline join halted"),
+                    "expected halt-prefix error, got: {source}"
+                );
+            }
+            other => panic!("expected Err(IoError) halted, got {other:?}"),
+        }
+        // Bailed out within ~1 second of the halt firing (worst case
+        // one POLL_INTERVAL = 250 ms of slack).
+        assert!(
+            elapsed < Duration::from_secs(2),
+            "halt observation took too long: {elapsed:?}"
+        );
+    }
+
+    #[test]
+    fn finish_with_halt_happy_path_returns_output() {
+        // No halt token, sink completes normally — finish_with_halt
+        // must return the same Output that `finish` would.
+        let pipe = Pipeline::spawn(DEFAULT_PIPELINE_DEPTH, SumSink { total: 0 })
+            .expect("spawn should succeed");
+        for i in 0..10u64 {
+            pipe.send(i).expect("send should succeed");
+        }
+        let total = pipe
+            .finish_with_halt(None)
+            .expect("happy-path finish_with_halt should succeed");
+        assert_eq!(total, (0..10u64).sum::<u64>());
+    }
+}
@@ -0,0 +1,17 @@
+//! Per-platform writeback pipeline. On Linux, drains dirty pages
+//! continuously at chunk granularity to keep the kernel's writeback
+//! queue bounded. On macOS and Windows, a no-op stub.
+//!
+//! The platform decision lives entirely in this file (the cfg-gated
+//! `pub use` below). Callers — and `DiskWriter` itself — are
+//! platform-independent.
+
+#[cfg(target_os = "linux")]
+mod linux;
+#[cfg(not(target_os = "linux"))]
+mod noop;
+
+#[cfg(target_os = "linux")]
+pub(super) use linux::WritebackPipeline;
+#[cfg(not(target_os = "linux"))]
+pub(super) use noop::WritebackPipeline;
@@ -0,0 +1,354 @@
+//! Linux writeback pipeline using `sync_file_range` + `posix_fadvise`.
+//!
+//! Pathology this fixes: the kernel's default `vm.dirty_ratio` (~20 %
+//! of RAM) lets dirty pages accumulate to hundreds of MB during a
+//! big sequential write, then bursts a flush at 99 % disk utilisation.
+//! While the burst runs, app writes block on the writeback queue —
+//! observed empirically as instantaneous speed dropping from ~15 MB/s
+//! to ~1 MB/s every ~30 s during a Pass 1 sweep.
+//!
+//! Strategy: every `chunk_bytes` of new sequential output, kick async
+//! writeback (`SYNC_FILE_RANGE_WRITE`) on the just-completed chunk and
+//! finalise the *previous* chunk via `WAIT_AFTER` + `posix_fadvise
+//! (DONTNEED)`. By the time we finalise, that previous chunk has had
+//! a full chunk's worth of work to flush — the wait is near-instant.
+//! Dirty cache stays bounded at ~2 × `chunk_bytes` and writes drain
+//! continuously instead of in bursts.
+//!
+//! The chunk size is adaptive: we measure the elapsed time of the
+//! `WAIT_AFTER` call over a rolling window of the last 16 chunks and
+//! resize the chunk based on the p95. Slow storage (NFS, network
+//! shares, HDD) sees larger chunks to amortise per-chunk overhead;
+//! fast storage (NVMe) sees smaller chunks to keep cache pressure
+//! tight. Bounds: [4 MiB, 256 MiB].
+//!
+//! ## NFS escape hatch
+//!
+//! `sync_file_range(WAIT_AFTER)` on an NFS-mounted file can block
+//! indefinitely waiting for the server's commit ack. If the server
+//! never acks (network partition, server-side hang, slow commit), the
+//! syscall never returns and the consumer thread is stuck inside the
+//! kernel — `/api/stop` can't reach it because halt is cooperative.
+//!
+//! When `fstatfs` reports the file lives on an NFS mount
+//! (`f_type == NFS_SUPER_MAGIC`), the pipeline skips the WAIT_AFTER +
+//! `posix_fadvise(DONTNEED)` dance entirely. NFS clients have their
+//! own buffering and commit semantics that handle dirty-page bounds
+//! without us forcing the issue. The async `SYNC_FILE_RANGE_WRITE`
+//! kickoff still runs (non-blocking by spec) so writeback still gets
+//! a nudge.
+//!
+//! ## Defence in depth: WAIT_AFTER timeout
+//!
+//! Even on local storage, a degraded disk or odd filesystem driver
+//! could in principle wedge inside WAIT_AFTER. Each WAIT_AFTER call
+//! runs on a worker thread with a 30s recv_timeout on its result
+//! channel. On timeout we log a loud error, set a `degraded` flag,
+//! and from then on skip WAIT_AFTER + DONTNEED for the rest of the
+//! pipeline's life (same shape as the NFS path). The worker thread
+//! is intentionally leaked — it unwinds whenever the syscall
+//! eventually returns or the process exits. The mux continues; the
+//! original dirty-burst pathology re-emerges but the rip can still
+//! finish instead of freezing.
+
+use std::collections::VecDeque;
+use std::fs::File;
+use std::os::unix::io::{AsRawFd, RawFd};
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::{Duration, Instant};
+
+const ADAPTIVE_WINDOW: usize = 16;
+const CHUNK_BYTES_MIN: u64 = 4 * 1024 * 1024;
+const CHUNK_BYTES_MAX: u64 = 256 * 1024 * 1024;
+const ADAPTIVE_GROW_MS: u64 = 200;
+const ADAPTIVE_SHRINK_MS: u64 = 20;
+/// Every N chunks, emit a `debug!` snapshot of the current chunk
+/// size so operators tailing the log can see where the autoscaler
+/// settled.
+const SIZE_LOG_INTERVAL: u64 = 32;
+/// Hard upper bound on a single `sync_file_range(WAIT_AFTER)` call.
+/// Beyond this we declare the pipeline degraded and stop calling
+/// WAIT_AFTER for the rest of its life.
+const WAIT_AFTER_TIMEOUT: Duration = Duration::from_secs(30);
+
+pub(crate) struct WritebackPipeline {
+    /// Aliases the wrapping `WritebackFile::file`. Only valid for the
+    /// lifetime of that struct — moving the `File` independently
+    /// would silently UAF this fd. The pipeline is a private field of
+    /// `WritebackFile` and never exposed outside that wrapper, which
+    /// is what keeps the alias sound.
+    fd: RawFd,
+    chunk_bytes: u64,
+    last_flush_pos: u64,
+    pending: Option<(u64, u64)>,
+    /// Rolling window of recent `WAIT_AFTER` elapsed_ms measurements.
+    wait_after_window: VecDeque<u64>,
+    /// Count of chunks emitted (used to space out periodic
+    /// `debug!` size snapshots).
+    chunk_count: u64,
+    /// True when the underlying file is on an NFS mount. NFS makes
+    /// WAIT_AFTER unsafe (can block forever on missing server ack), so
+    /// we skip it entirely and let the NFS client handle commit on
+    /// close.
+    is_nfs: bool,
+    /// Set the first time WAIT_AFTER exceeds [`WAIT_AFTER_TIMEOUT`].
+    /// Once set, behaviour matches the NFS path for the rest of the
+    /// pipeline's life. Wrapped in `Arc` only because both this
+    /// struct and the spawned worker thread (which itself doesn't
+    /// touch the flag) share-via-fd patterns might one day need it;
+    /// today it's effectively a single-owner cell — the `Arc` shape
+    /// keeps the door open for moving the read side into a worker
+    /// without re-plumbing types.
+    degraded: Arc<AtomicBool>,
+}
+
+impl WritebackPipeline {
+    /// Construct a pipeline aliasing `file`'s file descriptor. The
+    /// returned `WritebackPipeline` MUST be dropped before `file`
+    /// itself, or kept inside the same struct that owns `file` — the
+    /// alias is unchecked.
+    pub(crate) fn new(file: &File, start_pos: u64, chunk_bytes: u64) -> Self {
+        let fd = file.as_raw_fd();
+        let is_nfs = detect_nfs(fd);
+        tracing::info!(
+            target: "mux",
+            "WritebackPipeline fd={fd} is_nfs={is_nfs} chunk_bytes={chunk_bytes} strategy={}",
+            if is_nfs { "nfs-skip-wait" } else { "wait+dontneed" }
+        );
+        Self {
+            fd,
+            chunk_bytes,
+            last_flush_pos: start_pos,
+            pending: None,
+            wait_after_window: VecDeque::with_capacity(ADAPTIVE_WINDOW),
+            chunk_count: 0,
+            is_nfs,
+            degraded: Arc::new(AtomicBool::new(false)),
+        }
+    }
+
+    /// True if we should bypass the WAIT_AFTER + DONTNEED finalisation
+    /// step. NFS always bypasses; local storage bypasses once the
+    /// pipeline has flipped to degraded after a WAIT_AFTER timeout.
+    #[inline]
+    fn skip_wait(&self) -> bool {
+        self.is_nfs || self.degraded.load(Ordering::Relaxed)
+    }
+
+    /// Caller advanced the file position to `pos`. If a chunk boundary
+    /// was crossed, kick async writeback for the just-completed chunk
+    /// and finalise the previous one.
+    pub(crate) fn note_progress(&mut self, pos: u64) {
+        if pos < self.last_flush_pos.saturating_add(self.chunk_bytes) {
+            return;
+        }
+        let chunk_off = self.last_flush_pos as i64;
+        let chunk_len = (pos - self.last_flush_pos) as i64;
+        let mut wait_ms: u64 = 0;
+        let mut fadvise_ms: u64 = 0;
+        // Async kickoff for the just-completed chunk runs on every
+        // path (NFS, degraded, normal) — it's nominally non-blocking
+        // by spec and gives the kernel an early hint that this range
+        // is ready to flush.
+        unsafe {
+            libc::sync_file_range(self.fd, chunk_off, chunk_len, libc::SYNC_FILE_RANGE_WRITE);
+        }
+        if let Some((prev_off, prev_len)) = self.pending.take() {
+            if self.skip_wait() {
+                // NFS branch (or degraded fallback after a prior
+                // timeout): the WAIT_AFTER + DONTNEED dance is what
+                // hangs on NFS — skip it. We still advance `pending`
+                // so the next call has a stable cycle.
+            } else {
+                // Normal local-storage branch with belt-and-braces
+                // timeout. If WAIT_AFTER hangs > WAIT_AFTER_TIMEOUT
+                // we mark the pipeline degraded, log a loud error,
+                // and fall through to the skip path on subsequent
+                // calls.
+                match wait_after_with_timeout(self.fd, prev_off, prev_len) {
+                    Some(ms) => {
+                        wait_ms = ms;
+                        let t_fadv = Instant::now();
+                        unsafe {
+                            libc::posix_fadvise(
+                                self.fd,
+                                prev_off as i64,
+                                prev_len as i64,
+                                libc::POSIX_FADV_DONTNEED,
+                            );
+                        }
+                        fadvise_ms = t_fadv.elapsed().as_millis() as u64;
+                        self.record_wait(wait_ms);
+                    }
+                    None => {
+                        // Timeout branch: switch to NFS-style skip
+                        // for the rest of the pipeline's life. Do
+                        // NOT call DONTNEED — if WAIT_AFTER hasn't
+                        // returned, the pages aren't safely flushed.
+                        self.degraded.store(true, Ordering::Relaxed);
+                        tracing::error!(
+                            target: "mux",
+                            "WritebackPipeline WAIT_AFTER timed out after {}s on chunk off={} len={}, marking writeback degraded (subsequent chunks will skip WAIT_AFTER + DONTNEED)",
+                            WAIT_AFTER_TIMEOUT.as_secs(),
+                            prev_off,
+                            prev_len
+                        );
+                    }
+                }
+            }
+        }
+        self.pending = Some((chunk_off as u64, chunk_len as u64));
+        self.last_flush_pos = pos;
+        self.chunk_count += 1;
+        tracing::trace!(
+            target: "mux",
+            "WritebackPipeline chunk off={} len={} sync_file_range_ms={wait_ms} fadvise_ms={fadvise_ms} chunk_bytes={} skip_wait={}",
+            chunk_off,
+            chunk_len,
+            self.chunk_bytes,
+            self.skip_wait(),
+        );
+        if self.chunk_count % SIZE_LOG_INTERVAL == 0 {
+            tracing::debug!(
+                target: "mux",
+                "WritebackPipeline chunk_bytes={} after {} chunks is_nfs={} degraded={}",
+                self.chunk_bytes,
+                self.chunk_count,
+                self.is_nfs,
+                self.degraded.load(Ordering::Relaxed),
+            );
+        }
+    }
+
+    /// Push a new `WAIT_AFTER` measurement into the rolling window
+    /// and, if the window is full, adapt `chunk_bytes` based on p95.
+    fn record_wait(&mut self, wait_ms: u64) {
+        if self.wait_after_window.len() == ADAPTIVE_WINDOW {
+            self.wait_after_window.pop_front();
+        }
+        self.wait_after_window.push_back(wait_ms);
+        if self.wait_after_window.len() < ADAPTIVE_WINDOW {
+            return;
+        }
+        // p95 of 16 samples ≈ sorted[14] (5 % of 16 = 0.8 ≈ 1 above).
+        let mut sorted: Vec<u64> = self.wait_after_window.iter().copied().collect();
+        sorted.sort_unstable();
+        let p95 = sorted[14];
+        let old = self.chunk_bytes;
+        let new = if p95 > ADAPTIVE_GROW_MS && self.chunk_bytes < CHUNK_BYTES_MAX {
+            (self.chunk_bytes * 2).min(CHUNK_BYTES_MAX)
+        } else if p95 < ADAPTIVE_SHRINK_MS && self.chunk_bytes > CHUNK_BYTES_MIN {
+            (self.chunk_bytes / 2).max(CHUNK_BYTES_MIN)
+        } else {
+            self.chunk_bytes
+        };
+        if new != old {
+            self.chunk_bytes = new;
+            tracing::info!(
+                target: "mux",
+                "WritebackPipeline adaptive chunk_bytes {} -> {} p95_ms={p95}",
+                old,
+                new
+            );
+        }
+    }
+
+    /// Caller is about to seek away from the current write region.
+    /// Drain any in-flight chunk and reset tracking.
+    pub(crate) fn handle_seek(&mut self, new_pos: u64) {
+        self.finalize();
+        self.last_flush_pos = new_pos;
+    }
+
+    /// Drain any in-flight chunk. Idempotent. Call before `sync_all()`
+    /// or when discarding the pipeline.
+    pub(crate) fn finalize(&mut self) {
+        if let Some((prev_off, prev_len)) = self.pending.take() {
+            tracing::debug!(
+                target: "mux",
+                "WritebackPipeline finalize chunk off={prev_off} len={prev_len} skip_wait={} is_nfs={} degraded={}",
+                self.skip_wait(),
+                self.is_nfs,
+                self.degraded.load(Ordering::Relaxed),
+            );
+            if self.skip_wait() {
+                // NFS / degraded: skip WAIT_AFTER + DONTNEED. close()
+                // / sync_all() handle commit through their normal
+                // paths.
+                return;
+            }
+            match wait_after_with_timeout(self.fd, prev_off, prev_len) {
+                Some(_ms) => unsafe {
+                    libc::posix_fadvise(
+                        self.fd,
+                        prev_off as i64,
+                        prev_len as i64,
+                        libc::POSIX_FADV_DONTNEED,
+                    );
+                },
+                None => {
+                    self.degraded.store(true, Ordering::Relaxed);
+                    tracing::error!(
+                        target: "mux",
+                        "WritebackPipeline finalize WAIT_AFTER timed out after {}s on chunk off={prev_off} len={prev_len}, marking writeback degraded",
+                        WAIT_AFTER_TIMEOUT.as_secs(),
+                    );
+                }
+            }
+        }
+    }
+}
+
+/// 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.
+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.
+    let f_type = buf.f_type as i64;
+    let nfs_magic = libc::NFS_SUPER_MAGIC as i64;
+    f_type == nfs_magic
+}
+
+/// Run `sync_file_range(WAIT_AFTER)` on a worker thread and wait up
+/// to [`WAIT_AFTER_TIMEOUT`] for it to return. `Some(elapsed_ms)` on
+/// success; `None` on timeout. On timeout the worker thread is
+/// 0.20.6 generalizes the worker-thread + recv_timeout pattern into
+/// [`crate::io::bounded::bounded_syscall`]; this helper now just adapts
+/// the generic primitive to the WAIT_AFTER call shape (returns elapsed_ms
+/// instead of the syscall's `()` return, treats `WorkerLost` as a benign
+/// no-op to match the original semantics).
+fn wait_after_with_timeout(fd: RawFd, off: u64, len: u64) -> Option<u64> {
+    let started = Instant::now();
+    match crate::io::bounded::bounded_syscall(None, WAIT_AFTER_TIMEOUT, move || unsafe {
+        libc::sync_file_range(fd, off as i64, len as i64, libc::SYNC_FILE_RANGE_WAIT_AFTER);
+    }) {
+        Ok(()) => Some(started.elapsed().as_millis() as u64),
+        Err(crate::io::bounded::BoundedError::Timeout)
+        | Err(crate::io::bounded::BoundedError::Halted) => None,
+        Err(crate::io::bounded::BoundedError::WorkerLost) => {
+            // Worker thread spawn failed or panicked before sending.
+            // Treat as a benign success (no syscall ran) rather than
+            // a degrade trigger — falling through with elapsed_ms=0
+            // matches the no-op behaviour.
+            Some(0)
+        }
+    }
+}
@@ -0,0 +1,18 @@
+//! No-op writeback pipeline for non-Linux targets. macOS and Windows
+//! page cache policies have not been shown to exhibit the Linux
+//! accumulate-then-burst flush pathology for our access pattern.
+//! If that changes, replace this stub with a real implementation
+//! (e.g. `F_NOCACHE` on macOS, `FILE_FLAG_WRITE_THROUGH` on Windows).
+
+use std::fs::File;
+
+pub(crate) struct WritebackPipeline;
+
+impl WritebackPipeline {
+    pub(crate) fn new(_file: &File, _start_pos: u64, _chunk_bytes: u64) -> Self {
+        Self
+    }
+    pub(crate) fn note_progress(&mut self, _pos: u64) {}
+    pub(crate) fn handle_seek(&mut self, _new_pos: u64) {}
+    pub(crate) fn finalize(&mut self) {}
+}
@@ -0,0 +1,229 @@
+//! `WritebackFile` — a `File` wrapper whose reason for existing is the
+//! bounded-cache writeback pipeline.
+//!
+//! Why: large sequential writes (sweep, patch, mux on UHD-scale output)
+//! left to the kernel's default writeback policy accumulate hundreds of
+//! megabytes of dirty pages and then burst-flush, stalling subsequent
+//! writes for seconds at a time. `WritebackFile` drives a continuous
+//! [`super::writeback::WritebackPipeline`] that on Linux issues
+//! incremental `sync_file_range` + `posix_fadvise(DONTNEED)` calls at
+//! 32 MB granularity so dirty pages drain at the same rate they're
+//! produced. macOS and Windows fall through to a no-op pipeline — their
+//! default cache policies have not been shown to exhibit the same
+//! pathology for this access pattern.
+//!
+//! It implements `Write` and `Seek` so any call site that wrote to a
+//! plain `File` through those traits (sweep, patch, mux) can swap in
+//! `WritebackFile` without touching the body of the loop. The wrapper
+//! also tracks the current file position to feed the pipeline with
+//! progress + seek boundaries.
+//!
+//! See `super::writeback::linux` for the underlying pathology and the
+//! strategy.
+
+use std::fs::{File, OpenOptions};
+use std::io::{self, Seek, SeekFrom, Write};
+use std::path::Path;
+
+use super::writeback::WritebackPipeline;
+
+const WRITEBACK_CHUNK_BYTES: u64 = 32 * 1024 * 1024;
+
+pub(crate) struct WritebackFile {
+    file: File,
+    pipeline: WritebackPipeline,
+    pos: u64,
+}
+
+impl WritebackFile {
+    /// Wrap an open `File`. The current OS file position is queried
+    /// once so the pipeline starts tracking from wherever the file
+    /// already is (typically 0 for fresh files; non-zero for resumed
+    /// 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);
+        Ok(Self {
+            file,
+            pipeline,
+            pos,
+        })
+    }
+
+    /// Create a new file at `path` (truncating any existing contents)
+    /// and wrap it. Convenience for the common
+    /// `File::create(path)` + `WritebackFile::new(file)` pair so callers
+    /// don't have to assemble a `File` first.
+    ///
+    /// Callers that know the target output size should prefer
+    /// [`Self::create_with_size_hint`] so the kernel can pre-reserve
+    /// extents.
+    #[allow(dead_code)]
+    pub(crate) fn create(path: &Path) -> io::Result<Self> {
+        let file = File::create(path)?;
+        Self::new(file)
+    }
+
+    /// Like [`Self::create`] but pre-reserves `size_bytes` of disk
+    /// space via `fallocate(FALLOC_FL_KEEP_SIZE)` on Linux. The
+    /// reported file size is unchanged (writes still grow the file
+    /// naturally) — only the on-disk extent allocation is preallocated,
+    /// which reduces extent fragmentation on large sequential writes
+    /// (mux output, especially on slow storage / NFS).
+    ///
+    /// On macOS / Windows the size hint is ignored and this is
+    /// equivalent to `create`.
+    pub(crate) fn create_with_size_hint(path: &Path, size_bytes: u64) -> io::Result<Self> {
+        let file = File::create(path)?;
+        #[cfg(target_os = "linux")]
+        {
+            use std::os::unix::io::AsRawFd;
+            // FALLOC_FL_KEEP_SIZE = 0x01 — keep the reported file
+            // size at 0 (writes grow it normally) while still
+            // pre-reserving the extents.
+            let rc = unsafe {
+                libc::fallocate(
+                    file.as_raw_fd(),
+                    libc::FALLOC_FL_KEEP_SIZE,
+                    0,
+                    size_bytes as i64,
+                )
+            };
+            tracing::debug!(
+                target: "mux",
+                "WritebackFile fallocate size_hint={size_bytes} rc={rc} ok={}",
+                rc == 0
+            );
+        }
+        #[cfg(not(target_os = "linux"))]
+        {
+            tracing::debug!(
+                target: "mux",
+                "WritebackFile fallocate size_hint={size_bytes} skipped (non-linux)"
+            );
+        }
+        Self::new(file)
+    }
+
+    /// Open an existing file at `path` for writing (no truncation) and
+    /// wrap it. Mirrors `File::open` semantics for the writable case
+    /// — used by patch / resume paths that mutate an existing ISO in
+    /// place.
+    pub(crate) fn open(path: &Path) -> io::Result<Self> {
+        let file = OpenOptions::new().write(true).open(path)?;
+        Self::new(file)
+    }
+
+    /// Drain in-flight writeback then issue a full fsync. Use this in
+    /// place of `File::sync_all`.
+    ///
+    /// The final fsync is wrapped in
+    /// [`crate::io::bounded::bounded_syscall`] with a 60 s deadline.
+    /// fsync on a wedged NFS server (or a degraded local disk) can
+    /// hang the calling thread; the wrapper ensures the worst case is
+    /// 60 s + log-and-continue rather than indefinite. On timeout the
+    /// page cache is left to the kernel's normal flush-on-close path —
+    /// best effort, but bounded.
+    pub(crate) fn sync_all(&mut self) -> io::Result<()> {
+        self.pipeline.finalize();
+        #[cfg(unix)]
+        {
+            use std::os::unix::io::AsRawFd;
+            use std::time::Duration;
+            let fd = self.file.as_raw_fd();
+            match crate::io::bounded::bounded_syscall(
+                None,
+                Duration::from_secs(60),
+                move || -> io::Result<()> {
+                    let rc = unsafe { libc::fsync(fd) };
+                    if rc == 0 {
+                        Ok(())
+                    } else {
+                        Err(io::Error::last_os_error())
+                    }
+                },
+            ) {
+                Ok(inner) => inner,
+                Err(crate::io::bounded::BoundedError::Timeout) => {
+                    tracing::error!(
+                        target: "mux",
+                        "WritebackFile::sync_all fsync timed out after 60s; kernel will flush on close (best-effort)"
+                    );
+                    Ok(())
+                }
+                Err(crate::io::bounded::BoundedError::Halted) => Ok(()),
+                Err(crate::io::bounded::BoundedError::WorkerLost) => Ok(()),
+            }
+        }
+        #[cfg(not(unix))]
+        {
+            self.file.sync_all()
+        }
+    }
+}
+
+impl Write for WritebackFile {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        let n = self.file.write(buf)?;
+        self.pos += n as u64;
+        self.pipeline.note_progress(self.pos);
+        Ok(n)
+    }
+
+    fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
+        self.file.write_all(buf)?;
+        self.pos += buf.len() as u64;
+        self.pipeline.note_progress(self.pos);
+        Ok(())
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        self.file.flush()
+    }
+}
+
+impl Seek for WritebackFile {
+    fn seek(&mut self, from: SeekFrom) -> io::Result<u64> {
+        let p = self.file.seek(from)?;
+        // Only treat seeks that actually move the position as
+        // boundaries — sweep does a redundant `seek(Current(pos))`
+        // before every write, and we don't want that to drain the
+        // pipeline on every iteration.
+        if p != self.pos {
+            // Diagnostic for the NFS 73 % mux hang: the MKV format
+            // requires the muxer to seek back occasionally (cluster
+            // size patching, Cues index write, Segment header
+            // backpatch). Each such seek invalidates the writeback
+            // chunk tracking and forces a finalize → WAIT_AFTER on
+            // the in-flight chunk. Logging the seek delta lets us
+            // correlate hang offsets with specific muxer operations.
+            let from_pos = self.pos;
+            let to_pos = p;
+            let delta: i64 = (to_pos as i64).wrapping_sub(from_pos as i64);
+            tracing::debug!(
+                target: "mux",
+                "WritebackFile seek from={from_pos} to={to_pos} delta={delta}"
+            );
+            self.pipeline.handle_seek(p);
+            self.pos = p;
+        }
+        Ok(p)
+    }
+}
+
+impl Drop for WritebackFile {
+    fn drop(&mut self) {
+        // Run the pipeline's tail finalize so the last in-flight chunk
+        // gets its `WAIT_AFTER` + `posix_fadvise(DONTNEED)`. Without
+        // this, callers that drop a `WritebackFile` without calling
+        // `sync_all` (panic, early-return, idiomatic `let _ = w;`)
+        // leave the trailing chunk in cache; the kernel still flushes
+        // on close, but the bounded-cache invariant fails at the tail.
+        // We deliberately do *not* call `self.file.sync_all()` here —
+        // close already triggers a flush, and an `fsync` from `Drop`
+        // would silently swallow its `io::Error` anyway. `finalize` is
+        // idempotent so an explicit `sync_all` followed by drop is
+        // still safe.
+        self.pipeline.finalize();
+    }
+}
@@ -0,0 +1,402 @@
+//! BDMV disc-library metadata (`/BDMV/META/DL/bdmt_<lang>.xml`).
+//!
+//! Every commercial Blu-ray carries a disc-library metadata directory
+//! with one XML file per shipped language. The schema is the Blu-ray
+//! "disc library metadata" namespace (`urn:BDA:bdmv;disclibmeta`),
+//! conventionally prefixed `di:`. Fields commonly present:
+//!
+//! - `<di:title>` or `<di:name>` — the title string. Vendor practice
+//!   varies (Paramount discs tend to use `<di:name>`).
+//! - `<di:description>` — optional synopsis (often absent on retail
+//!   discs; common on box sets and special editions).
+//! - `<di:discNumber>` / `<di:numSets>` (or `<di:numberOfSets>`) —
+//!   set position for multi-disc releases.
+//!
+//! This module is intentionally separate from the BD-J `StreamLabel`
+//! parsers under `labels/*.rs`. The XML here is disc-level (title,
+//! description, set position), not per-stream — wiring into the main
+//! parser registry happens elsewhere.
+//!
+//! Real-world XML is irregular: missing description elements, multiple
+//! title elements (first one wins), and occasional malformed content.
+//! Extraction is best-effort — a malformed file is treated as "no
+//! metadata" (returns `None` from the helper), and the caller can
+//! still get metadata from sibling-language XML files.
+
+// The module wiring (registry hook + public re-export) is added
+// separately. Until then the parse/detect entry points have no
+use super::xml;
+use crate::sector::SectorSource;
+use crate::udf::UdfFs;
+use std::collections::BTreeMap;
+
+/// Disc-level metadata extracted from `/BDMV/META/DL/bdmt_*.xml`.
+///
+/// All maps are keyed by 3-char ISO 639-2 language code (e.g.
+/// `"eng"`, `"fra"`, `"jpn"`) — the same key segment used in the
+/// `bdmt_<lang>.xml` filename.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, Default)]
+pub struct DiscMetadata {
+    /// Localized titles, keyed by 3-char ISO 639-2 lang code
+    /// (e.g. "eng" → "Dune Part Two")
+    pub titles: BTreeMap<String, String>,
+    /// First-line / short description, per lang
+    pub descriptions: BTreeMap<String, String>,
+    /// Disc N of M for box sets (None if not a box set)
+    pub disc_number: Option<(u32, u32)>,
+}
+
+/// True if `/BDMV/META/DL/` exists and contains at least one
+/// `bdmt_*.xml` file.
+pub fn detect(udf: &UdfFs) -> bool {
+    let Some(dir) = udf.find_dir("/BDMV/META/DL") else {
+        return false;
+    };
+    dir.entries
+        .iter()
+        .any(|e| !e.is_dir && is_bdmt_filename(&e.name))
+}
+
+/// Read every `bdmt_<lang>.xml` under `/BDMV/META/DL/` and return the
+/// aggregated [`DiscMetadata`]. Returns `None` if no titles could be
+/// extracted from any file.
+pub fn parse(reader: &mut dyn SectorSource, udf: &UdfFs) -> Option<DiscMetadata> {
+    let dir = udf.find_dir("/BDMV/META/DL")?;
+    let mut out = DiscMetadata::default();
+
+    for entry in &dir.entries {
+        if entry.is_dir {
+            continue;
+        }
+        let Some(lang) = lang_code_from_filename(&entry.name) else {
+            continue;
+        };
+        let path = format!("/BDMV/META/DL/{}", entry.name);
+        let Ok(bytes) = udf.read_file(reader, &path) else {
+            continue;
+        };
+        let Ok(text) = std::str::from_utf8(&bytes) else {
+            continue;
+        };
+        let Some((title, description, disc_set)) = parse_bdmt_xml(&lang, text) else {
+            continue;
+        };
+        out.titles.insert(lang.clone(), title);
+        if let Some(desc) = description {
+            out.descriptions.insert(lang.clone(), desc);
+        }
+        // Disc-set position is disc-global; first one we successfully
+        // read wins. (All bdmt_*.xml on a given disc carry the same
+        // value in practice.)
+        if out.disc_number.is_none() {
+            if let Some(ds) = disc_set {
+                out.disc_number = Some(ds);
+            }
+        }
+    }
+
+    if out.titles.is_empty() {
+        None
+    } else {
+        Some(out)
+    }
+}
+
+/// True if `name` matches the `bdmt_<lang>.xml` convention with a
+/// 3-character ISO 639-2 lang code segment. Case-insensitive.
+fn is_bdmt_filename(name: &str) -> bool {
+    lang_code_from_filename(name).is_some()
+}
+
+/// Extract the 3-char language code from a `bdmt_<lang>.xml` filename.
+/// Returns `None` if the filename doesn't match. Lang code is
+/// lowercased so callers always see e.g. `"eng"` not `"ENG"`.
+fn lang_code_from_filename(name: &str) -> Option<String> {
+    let lower = name.to_ascii_lowercase();
+    let stem = lower.strip_suffix(".xml")?;
+    let lang = stem.strip_prefix("bdmt_")?;
+    // ISO 639-2 codes are exactly 3 ASCII letters. Be strict — keeps
+    // us from picking up unrelated `bdmt_foo.xml` siblings.
+    if lang.len() != 3 || !lang.chars().all(|c| c.is_ascii_alphabetic()) {
+        return None;
+    }
+    Some(lang.to_string())
+}
+
+/// Tuple returned by [`parse_bdmt_xml`]: `(title, description?, disc_set?)`.
+/// Aliased so the function signature isn't a clippy::type-complexity offender.
+pub(crate) type BdmtFields = (String, Option<String>, Option<(u32, u32)>);
+
+/// Parse one `bdmt_<lang>.xml` document and return
+/// `(title, description?, disc_set?)`. Returns `None` if no title
+/// could be located — the caller treats this as "skip this file".
+///
+/// Title-element preference: `<di:name>` → `<di:title>` →
+/// `<di:tableOfContents>/<di:titleName>` (first match wins, per the
+/// authoring-tool conventions documented at the module level).
+pub(crate) fn parse_bdmt_xml(_lang_code: &str, xml_text: &str) -> Option<BdmtFields> {
+    let title = extract_title(xml_text)?;
+    let description = xml::text(xml_text, "description")
+        .filter(|s| !s.is_empty())
+        .filter(|s| !looks_like_xml(s))
+        .map(|s| s.trim().to_string())
+        .filter(|s| !s.is_empty());
+    let disc_set = extract_disc_set(xml_text);
+    Some((title, description, disc_set))
+}
+
+/// Reject candidate description strings that are themselves XML
+/// fragments — observed on disc-04 (Top Gun: Maverick), where
+/// `<di:description>` contained `<di:thumbnail href="…"/>` child
+/// elements and no actual prose. Surfacing that raw to the JSON
+/// output is worse than dropping the field entirely.
+fn looks_like_xml(s: &str) -> bool {
+    let t = s.trim_start();
+    t.starts_with('<')
+}
+
+/// Try title-bearing element variants in priority order. The `xml`
+/// helpers are case- and namespace-insensitive, so callers pass the
+/// bare local name (no `di:` prefix).
+fn extract_title(xml_text: &str) -> Option<String> {
+    // Order matches the module-level convention: <di:name> first
+    // (Paramount-style), then <di:title>, then the nested
+    // tableOfContents/titleName form.
+    for tag in ["name", "title"] {
+        if let Some(s) = xml::text(xml_text, tag) {
+            let trimmed = s.trim();
+            if !trimmed.is_empty() {
+                return Some(trimmed.to_string());
+            }
+        }
+    }
+    // tableOfContents/titleName: search inside the toc block so we
+    // don't accidentally pick a stray <titleName> from elsewhere.
+    if let Some((s, e)) = xml::find_element(xml_text, "tableOfContents", 0) {
+        let block = &xml_text[s..e];
+        if let Some(t) = xml::text(block, "titleName") {
+            let trimmed = t.trim();
+            if !trimmed.is_empty() {
+                return Some(trimmed.to_string());
+            }
+        }
+    }
+    None
+}
+
+/// Extract `(discNumber, numSets)` if both are present and parse as
+/// `u32`. Accepts either `<di:numSets>` or `<di:numberOfSets>` for
+/// the denominator (both forms appear in the wild).
+fn extract_disc_set(xml_text: &str) -> Option<(u32, u32)> {
+    let n = xml::text(xml_text, "discNumber")?
+        .trim()
+        .parse::<u32>()
+        .ok()?;
+    let total = xml::text(xml_text, "numSets")
+        .or_else(|| xml::text(xml_text, "numberOfSets"))?
+        .trim()
+        .parse::<u32>()
+        .ok()?;
+    Some((n, total))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn extract_simple_title() {
+        // Minimal Paramount-style document: <di:name> as the title
+        // carrier inside a <discInfo> root.
+        let xml = r#"<?xml version="1.0" encoding="UTF-8"?>
+<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
+  <di:name>Dune Part Two</di:name>
+</discInfo>"#;
+        let (title, desc, set) = parse_bdmt_xml("eng", xml).expect("title should parse");
+        assert_eq!(title, "Dune Part Two");
+        assert_eq!(desc, None);
+        assert_eq!(set, None);
+    }
+
+    #[test]
+    fn extract_title_element_variant() {
+        // <di:title> is the alternate carrier; should be picked up
+        // when <di:name> is absent.
+        let xml = r#"<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
+  <di:title>The Matrix</di:title>
+  <di:description>A film about computers.</di:description>
+</discInfo>"#;
+        let (title, desc, _) = parse_bdmt_xml("eng", xml).unwrap();
+        assert_eq!(title, "The Matrix");
+        assert_eq!(desc.as_deref(), Some("A film about computers."));
+    }
+
+    #[test]
+    fn extract_title_from_table_of_contents_fallback() {
+        // Some authoring tools nest the title under tableOfContents.
+        // No <di:name> or <di:title> at top level → fall back to
+        // titleName inside tableOfContents.
+        let xml = r#"<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
+  <di:tableOfContents>
+    <di:titleName>Inside Out 2</di:titleName>
+  </di:tableOfContents>
+</discInfo>"#;
+        let (title, _, _) = parse_bdmt_xml("eng", xml).unwrap();
+        assert_eq!(title, "Inside Out 2");
+    }
+
+    #[test]
+    fn extract_box_set_position() {
+        let xml = r#"<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
+  <di:name>LOTR Disc 2</di:name>
+  <di:discNumber>2</di:discNumber>
+  <di:numSets>5</di:numSets>
+</discInfo>"#;
+        let (_, _, set) = parse_bdmt_xml("eng", xml).unwrap();
+        assert_eq!(set, Some((2, 5)));
+    }
+
+    #[test]
+    fn extract_box_set_position_alternate_total_tag() {
+        // <di:numberOfSets> is an alternate spelling we've seen.
+        let xml = r#"<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
+  <di:name>X</di:name>
+  <di:discNumber>3</di:discNumber>
+  <di:numberOfSets>6</di:numberOfSets>
+</discInfo>"#;
+        let (_, _, set) = parse_bdmt_xml("eng", xml).unwrap();
+        assert_eq!(set, Some((3, 6)));
+    }
+
+    #[test]
+    fn extract_box_set_requires_both_fields() {
+        // discNumber alone (no total) yields None — we don't fabricate
+        // a denominator.
+        let xml = r#"<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
+  <di:name>X</di:name>
+  <di:discNumber>1</di:discNumber>
+</discInfo>"#;
+        let (_, _, set) = parse_bdmt_xml("eng", xml).unwrap();
+        assert_eq!(set, None);
+    }
+
+    #[test]
+    fn multiple_languages_keyed_correctly() {
+        // Simulate driving parse_bdmt_xml from two synthetic XML
+        // blobs and aggregating into DiscMetadata the same way parse()
+        // would. This exercises the BTreeMap key handling without
+        // needing a UdfFs.
+        let eng_xml = r#"<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
+  <di:name>Dune Part Two</di:name>
+</discInfo>"#;
+        let fra_xml = r#"<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
+  <di:name>Dune Deuxième Partie</di:name>
+  <di:description>Suite du film de 2021.</di:description>
+</discInfo>"#;
+
+        let mut meta = DiscMetadata::default();
+        for (lang, blob) in [("eng", eng_xml), ("fra", fra_xml)] {
+            let (title, desc, ds) = parse_bdmt_xml(lang, blob).unwrap();
+            meta.titles.insert(lang.to_string(), title);
+            if let Some(d) = desc {
+                meta.descriptions.insert(lang.to_string(), d);
+            }
+            if meta.disc_number.is_none() {
+                if let Some(d) = ds {
+                    meta.disc_number = Some(d);
+                }
+            }
+        }
+
+        assert_eq!(
+            meta.titles.get("eng").map(String::as_str),
+            Some("Dune Part Two")
+        );
+        assert_eq!(
+            meta.titles.get("fra").map(String::as_str),
+            Some("Dune Deuxième Partie")
+        );
+        assert!(meta.descriptions.get("eng").is_none());
+        assert_eq!(
+            meta.descriptions.get("fra").map(String::as_str),
+            Some("Suite du film de 2021.")
+        );
+        assert_eq!(meta.disc_number, None);
+    }
+
+    #[test]
+    fn malformed_xml_returns_none() {
+        // Random gibberish has no recognizable title element. We
+        // document the contract: parse_bdmt_xml returns None, and
+        // parse() (the caller) skips the file. Aggregating across
+        // zero files leaves DiscMetadata::default() — which parse()
+        // surfaces as None to its caller. Either is documented as
+        // acceptable per the module spec.
+        let bad = "this is not xml &&& <<< nope";
+        assert!(parse_bdmt_xml("eng", bad).is_none());
+
+        // Half-open tag, no body, no close: also yields no title.
+        let truncated = "<discInfo><di:name>";
+        assert!(parse_bdmt_xml("eng", truncated).is_none());
+    }
+
+    #[test]
+    fn description_with_only_child_xml_is_dropped() {
+        // Real-world bug from disc-04 (Top Gun: Maverick, 2026-05-11
+        // capture): <di:description> contained only <di:thumbnail/>
+        // child elements with no actual prose. The previous parser
+        // surfaced the raw XML fragment as the description string.
+        // Now we reject candidates that begin with `<`.
+        let xml = r#"<discInfo>
+            <di:name>Top Gun: Maverick</di:name>
+            <di:description>
+              <di:thumbnail href="tgm_meta_sm.jpg" />
+              <di:thumbnail href="tgm_meta_lg.jpg" />
+            </di:description>
+        </discInfo>"#;
+        let (title, description, _) =
+            parse_bdmt_xml("eng", xml).expect("title is present so parse must succeed");
+        assert_eq!(title, "Top Gun: Maverick");
+        assert!(
+            description.is_none(),
+            "description containing only XML children must be dropped, got {description:?}"
+        );
+    }
+
+    #[test]
+    fn description_with_plain_text_passes_through() {
+        // The legitimate case still works: a description with actual
+        // prose survives the looks_like_xml filter.
+        let xml = r#"<discInfo>
+            <di:name>Some Movie</di:name>
+            <di:description>An epic tale of one man's quest for tea.</di:description>
+        </discInfo>"#;
+        let (_, description, _) = parse_bdmt_xml("eng", xml).expect("must parse");
+        assert_eq!(
+            description.as_deref(),
+            Some("An epic tale of one man's quest for tea.")
+        );
+    }
+
+    #[test]
+    fn whitespace_in_title_is_trimmed() {
+        let xml = r#"<discInfo><di:name>
+            Dune Part Two
+        </di:name></discInfo>"#;
+        let (title, _, _) = parse_bdmt_xml("eng", xml).unwrap();
+        assert_eq!(title, "Dune Part Two");
+    }
+
+    #[test]
+    fn lang_code_extraction() {
+        assert_eq!(lang_code_from_filename("bdmt_eng.xml"), Some("eng".into()));
+        assert_eq!(lang_code_from_filename("BDMT_FRA.XML"), Some("fra".into()));
+        assert_eq!(lang_code_from_filename("bdmt_jpn.xml"), Some("jpn".into()));
+        // Non-matching cases:
+        assert_eq!(lang_code_from_filename("bdmt_.xml"), None);
+        assert_eq!(lang_code_from_filename("bdmt_engl.xml"), None);
+        assert_eq!(lang_code_from_filename("bdmt_e1g.xml"), None);
+        assert_eq!(lang_code_from_filename("bdmt_eng.txt"), None);
+        assert_eq!(lang_code_from_filename("foo.xml"), None);
+    }
+}
@@ -0,0 +1,291 @@
+//! CLPI vs MPLS cross-validation diagnostic.
+//!
+//! Empirical question (raised 2026-05-11): is CLPI's per-stream
+//! language and codec data truly redundant with MPLS's STN-table data
+//! on real-world Blu-rays?
+//!
+//! Build a quick audit that walks both sources, normalizes their stream
+//! lists by (PID, language, coding_type), and flags any disagreement.
+//!
+//! Three classes of mismatch we want to detect:
+//!
+//! 1. **CLPI has streams MPLS doesn't reference.** Orphan streams in
+//!    the .m2ts that no playlist's STN table includes. Means the user
+//!    can't reach them through the menu but they're physically on the
+//!    disc.
+//! 2. **MPLS has streams CLPI doesn't list.** Should never happen if
+//!    both parsers are correct — playlists reference clips which
+//!    reference streams. If it happens, one of our parsers has a bug.
+//! 3. **Same PID, different language / coding_type.** The playlist re-
+//!    tagged a stream's metadata. Rare but spec-permitted. Means CLPI
+//!    and MPLS disagree about the same physical stream's properties.
+//!
+//! If audits across the corpus show zero mismatches of any class, CLPI
+//! program_info extraction is **empirically redundant** for labels and
+//! we can leave it out of the registry. If even one mismatch surfaces,
+//! we add a CLPI label parser to the registry as belt-and-suspenders.
+//!
+//! This module exposes `audit(reader, udf)` returning a structured
+//! report. Surfaced via the labels-analyze tool — not part of the
+//! `analyze()` pipeline (no impact on the label output).
+
+use crate::sector::SectorSource;
+use crate::udf::UdfFs;
+use std::collections::BTreeMap;
+
+/// One row in the audit: a stream PID that's known to one source or
+/// both, with the fields each source reported.
+#[derive(Debug, Clone)]
+pub struct ClpiVsMplsRow {
+    pub pid: u16,
+    pub clpi_coding_type: Option<u8>,
+    pub clpi_language: Option<String>,
+    pub mpls_coding_type: Option<u8>,
+    pub mpls_language: Option<String>,
+}
+
+impl ClpiVsMplsRow {
+    /// Three rules for classification:
+    /// - both sources missing (impossible — caller wouldn't insert)
+    /// - one source missing → class A or B (orphan-on-disc / playlist-only)
+    /// - both present but fields differ → class C (metadata divergence)
+    /// - both present and identical → no mismatch
+    pub fn class(&self) -> ClpiVsMplsClass {
+        match (
+            self.clpi_coding_type.is_some(),
+            self.mpls_coding_type.is_some(),
+        ) {
+            (true, false) => ClpiVsMplsClass::ClpiOnly,
+            (false, true) => ClpiVsMplsClass::MplsOnly,
+            (true, true) => {
+                let coding_match = self.clpi_coding_type == self.mpls_coding_type;
+                let lang_match = self.clpi_language == self.mpls_language;
+                if coding_match && lang_match {
+                    ClpiVsMplsClass::Match
+                } else {
+                    ClpiVsMplsClass::Divergent
+                }
+            }
+            (false, false) => ClpiVsMplsClass::Match,
+        }
+    }
+}
+
+/// Classification of one (PID) row.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ClpiVsMplsClass {
+    /// PID seen in CLPI ProgramInfo but no MPLS STN table references
+    /// it. Orphan on disc.
+    ClpiOnly,
+    /// PID seen in MPLS STN table but no CLPI ProgramInfo includes it.
+    /// One of our parsers probably has a bug.
+    MplsOnly,
+    /// Both sources see this PID with the same coding_type + language.
+    Match,
+    /// Both sources see this PID but disagree on coding_type or language.
+    /// MPLS wins for label rendering (playlist-authoritative view); CLPI
+    /// is the per-clip ground truth.
+    Divergent,
+}
+
+/// Full audit report.
+#[derive(Debug, Clone, Default)]
+pub struct ClpiVsMplsAudit {
+    pub rows: Vec<ClpiVsMplsRow>,
+}
+
+impl ClpiVsMplsAudit {
+    pub fn class_counts(&self) -> (usize, usize, usize, usize) {
+        let mut clpi_only = 0;
+        let mut mpls_only = 0;
+        let mut matches = 0;
+        let mut divergent = 0;
+        for r in &self.rows {
+            match r.class() {
+                ClpiVsMplsClass::ClpiOnly => clpi_only += 1,
+                ClpiVsMplsClass::MplsOnly => mpls_only += 1,
+                ClpiVsMplsClass::Match => matches += 1,
+                ClpiVsMplsClass::Divergent => divergent += 1,
+            }
+        }
+        (clpi_only, mpls_only, matches, divergent)
+    }
+}
+
+/// Walk `/BDMV/CLIPINF/*.clpi` and `/BDMV/PLAYLIST/*.mpls`, build a
+/// dedup-by-PID table of (CLPI fields, MPLS fields), return the
+/// merged view. Missing files (read errors, parse failures) are
+/// silently skipped — this is diagnostic, not correctness-critical.
+pub fn audit(reader: &mut dyn SectorSource, udf: &UdfFs) -> ClpiVsMplsAudit {
+    // Aggregate by PID across all CLPI files. If a PID appears in
+    // multiple clips (typical — main movie clip + trailers reference
+    // the same audio stream PIDs), first encountered wins (they should
+    // all agree per BD spec).
+    let mut clpi_by_pid: BTreeMap<u16, (u8, String)> = BTreeMap::new();
+    if let Some(dir) = udf.find_dir("/BDMV/CLIPINF") {
+        let names: Vec<String> = dir
+            .entries
+            .iter()
+            .filter(|e| !e.is_dir && e.name.to_ascii_lowercase().ends_with(".clpi"))
+            .map(|e| e.name.clone())
+            .collect();
+        for name in names {
+            let path = format!("/BDMV/CLIPINF/{}", name);
+            let Ok(data) = udf.read_file(reader, &path) else {
+                continue;
+            };
+            let Ok(clip) = crate::clpi::parse(&data) else {
+                continue;
+            };
+            for s in clip.streams {
+                clpi_by_pid
+                    .entry(s.pid)
+                    .or_insert((s.coding_type, s.language));
+            }
+        }
+    }
+
+    // Same for MPLS streams.
+    let mut mpls_by_pid: BTreeMap<u16, (u8, String)> = BTreeMap::new();
+    if let Some(dir) = udf.find_dir("/BDMV/PLAYLIST") {
+        let names: Vec<String> = dir
+            .entries
+            .iter()
+            .filter(|e| !e.is_dir && e.name.to_ascii_lowercase().ends_with(".mpls"))
+            .map(|e| e.name.clone())
+            .collect();
+        for name in names {
+            let path = format!("/BDMV/PLAYLIST/{}", name);
+            let Ok(data) = udf.read_file(reader, &path) else {
+                continue;
+            };
+            let Ok(pl) = crate::mpls::parse(&data) else {
+                continue;
+            };
+            for s in pl.streams {
+                if s.pid == 0 {
+                    // PID 0 means "no PID in stream entry" — skip rather
+                    // than collide with other entries.
+                    continue;
+                }
+                mpls_by_pid
+                    .entry(s.pid)
+                    .or_insert((s.coding_type, s.language));
+            }
+        }
+    }
+
+    // Merge views: every PID seen anywhere gets a row.
+    let mut all_pids: std::collections::BTreeSet<u16> = std::collections::BTreeSet::new();
+    all_pids.extend(clpi_by_pid.keys().copied());
+    all_pids.extend(mpls_by_pid.keys().copied());
+
+    let mut rows = Vec::with_capacity(all_pids.len());
+    for pid in all_pids {
+        let clpi = clpi_by_pid.get(&pid);
+        let mpls = mpls_by_pid.get(&pid);
+        rows.push(ClpiVsMplsRow {
+            pid,
+            clpi_coding_type: clpi.map(|(c, _)| *c),
+            clpi_language: clpi.map(|(_, l)| l.clone()),
+            mpls_coding_type: mpls.map(|(c, _)| *c),
+            mpls_language: mpls.map(|(_, l)| l.clone()),
+        });
+    }
+
+    ClpiVsMplsAudit { rows }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn class_match_when_identical() {
+        let r = ClpiVsMplsRow {
+            pid: 0x1100,
+            clpi_coding_type: Some(0x83),
+            clpi_language: Some("eng".into()),
+            mpls_coding_type: Some(0x83),
+            mpls_language: Some("eng".into()),
+        };
+        assert_eq!(r.class(), ClpiVsMplsClass::Match);
+    }
+
+    #[test]
+    fn class_clpi_only_when_mpls_missing() {
+        let r = ClpiVsMplsRow {
+            pid: 0x1100,
+            clpi_coding_type: Some(0x83),
+            clpi_language: Some("eng".into()),
+            mpls_coding_type: None,
+            mpls_language: None,
+        };
+        assert_eq!(r.class(), ClpiVsMplsClass::ClpiOnly);
+    }
+
+    #[test]
+    fn class_mpls_only_when_clpi_missing() {
+        let r = ClpiVsMplsRow {
+            pid: 0x1100,
+            clpi_coding_type: None,
+            clpi_language: None,
+            mpls_coding_type: Some(0x90),
+            mpls_language: Some("fra".into()),
+        };
+        assert_eq!(r.class(), ClpiVsMplsClass::MplsOnly);
+    }
+
+    #[test]
+    fn class_divergent_on_lang_disagreement() {
+        let r = ClpiVsMplsRow {
+            pid: 0x1100,
+            clpi_coding_type: Some(0x83),
+            clpi_language: Some("eng".into()),
+            mpls_coding_type: Some(0x83),
+            mpls_language: Some("und".into()),
+        };
+        assert_eq!(r.class(), ClpiVsMplsClass::Divergent);
+    }
+
+    #[test]
+    fn class_counts_sum_rows() {
+        let audit = ClpiVsMplsAudit {
+            rows: vec![
+                ClpiVsMplsRow {
+                    pid: 0x1100,
+                    clpi_coding_type: Some(0x83),
+                    clpi_language: Some("eng".into()),
+                    mpls_coding_type: Some(0x83),
+                    mpls_language: Some("eng".into()),
+                }, // Match
+                ClpiVsMplsRow {
+                    pid: 0x1101,
+                    clpi_coding_type: Some(0x83),
+                    clpi_language: Some("fra".into()),
+                    mpls_coding_type: None,
+                    mpls_language: None,
+                }, // ClpiOnly
+                ClpiVsMplsRow {
+                    pid: 0x1102,
+                    clpi_coding_type: None,
+                    clpi_language: None,
+                    mpls_coding_type: Some(0x90),
+                    mpls_language: Some("eng".into()),
+                }, // MplsOnly
+                ClpiVsMplsRow {
+                    pid: 0x1103,
+                    clpi_coding_type: Some(0x86),
+                    clpi_language: Some("spa".into()),
+                    mpls_coding_type: Some(0x86),
+                    mpls_language: Some("ita".into()),
+                }, // Divergent
+            ],
+        };
+        let (co, mo, m, d) = audit.class_counts();
+        assert_eq!(co, 1);
+        assert_eq!(mo, 1);
+        assert_eq!(m, 1);
+        assert_eq!(d, 1);
+    }
+}
@@ -3,8 +3,8 @@
 //! Clean structured XML with Content/Qualifier per stream and
 //! stream number mapping via playbackconfig.

-use super::{LabelPurpose, LabelQualifier, StreamLabel, StreamLabelType};
-use crate::sector::SectorReader;
+use super::{LabelPurpose, LabelQualifier, ParseResult, StreamLabel, StreamLabelType, xml};
+use crate::sector::SectorSource;
 use crate::udf::UdfFs;
 use std::collections::HashMap;

@@ -12,7 +12,7 @@ pub fn detect(udf: &UdfFs) -> bool {
    super::jar_file_exists(udf, "streamproperties.xml")
 }

-pub fn parse(reader: &mut dyn SectorReader, udf: &UdfFs) -> Option<Vec<StreamLabel>> {
+pub fn parse(reader: &mut dyn SectorSource, udf: &UdfFs) -> Option<ParseResult> {
    let sp_data = super::read_jar_file(reader, udf, "streamproperties.xml")?;
    let sp_text = std::str::from_utf8(&sp_data).ok()?;

@@ -66,7 +66,8 @@ pub fn parse(reader: &mut dyn SectorReader, udf: &UdfFs) -> Option<Vec<StreamLab
    if labels.is_empty() {
        return None;
    }
-    Some(labels)
+    // High confidence: streamproperties.xml is fully structured.
+    Some(ParseResult::high(labels))
 }

 struct StreamInfo {
@@ -78,105 +79,68 @@ struct StreamInfo {
    qualifier: LabelQualifier,
 }

-fn parse_stream_infos(xml: &str) -> Vec<StreamInfo> {
+fn parse_stream_infos(text: &str) -> Vec<StreamInfo> {
    let mut infos = Vec::new();
-    let mut pos = 0;

-    while pos < xml.len() {
-        let (tag, stream_type) = if let Some(p) = xml[pos..].find("<AudioStreamInfos>") {
-            (p + pos, StreamLabelType::Audio)
-        } else if let Some(p) = xml[pos..].find("<SubtitleStreamInfos>") {
-            (p + pos, StreamLabelType::Subtitle)
-        } else {
-            break;
-        };
+    for (tag_name, stream_type) in [
+        ("AudioStreamInfos", StreamLabelType::Audio),
+        ("SubtitleStreamInfos", StreamLabelType::Subtitle),
+    ] {
+        let mut from = 0;
+        while let Some((start, end)) = xml::find_element(text, tag_name, from) {
+            let block = &text[start..end];
+            let id = xml::text(block, "ID").unwrap_or_default();
+            let lang_id = xml::text(block, "LangInfoID").unwrap_or_default();
+            let content = xml::text(block, "Content").unwrap_or_default();
+            let qualifier_str = xml::text(block, "Qualifier").unwrap_or_default();

-        let end_tag = match stream_type {
-            StreamLabelType::Audio => "</AudioStreamInfos>",
-            StreamLabelType::Subtitle => "</SubtitleStreamInfos>",
-        };
+            let (language, variant) = if lang_id.contains('_') {
+                let parts: Vec<&str> = lang_id.splitn(2, '_').collect();
+                (parts[0].to_lowercase(), parts[1].to_string())
+            } else {
+                (lang_id.to_lowercase(), String::new())
+            };

-        let block_end = match xml[tag..].find(end_tag) {
-            Some(p) => tag + p + end_tag.len(),
-            None => break,
-        };
+            let purpose = if content.eq_ignore_ascii_case("COMMENTARY") {
+                LabelPurpose::Commentary
+            } else {
+                LabelPurpose::Normal
+            };

-        let block = &xml[tag..block_end];
-        let id = extract_tag(block, "ID").unwrap_or_default();
-        let lang_id = extract_tag(block, "LangInfoID").unwrap_or_default();
-        let content = extract_tag(block, "Content").unwrap_or_default();
-        let qualifier_str = extract_tag(block, "Qualifier").unwrap_or_default();
+            let qualifier = match qualifier_str.to_ascii_uppercase().as_str() {
+                "SDH" => LabelQualifier::Sdh,
+                "DS" => LabelQualifier::DescriptiveService,
+                _ => LabelQualifier::None,
+            };

-        let (language, variant) = if lang_id.contains('_') {
-            let parts: Vec<&str> = lang_id.splitn(2, '_').collect();
-            (parts[0].to_lowercase(), parts[1].to_string())
-        } else {
-            (lang_id.to_lowercase(), String::new())
-        };
-
-        let purpose = match content.as_str() {
-            "COMMENTARY" => LabelPurpose::Commentary,
-            _ => LabelPurpose::Normal,
-        };
-
-        let qualifier = match qualifier_str.as_str() {
-            "SDH" => LabelQualifier::Sdh,
-            "DS" => LabelQualifier::DescriptiveService,
-            _ => LabelQualifier::None,
-        };
-
-        infos.push(StreamInfo {
-            id,
-            stream_type,
-            language,
-            variant,
-            purpose,
-            qualifier,
-        });
-        pos = block_end;
+            infos.push(StreamInfo {
+                id,
+                stream_type,
+                language,
+                variant,
+                purpose,
+                qualifier,
+            });
+            from = end;
+        }
    }
    infos
 }

-fn parse_playback_config(xml: &str, map: &mut HashMap<String, u16>) {
-    let mut pos = 0;
-    while pos < xml.len() {
-        let tag_start = if let Some(p) = xml[pos..].find("<AudioStreams>") {
-            Some(p + pos)
-        } else {
-            xml[pos..].find("<SubtitlesStreams>").map(|p| p + pos)
-        };
-
-        let tag_start = match tag_start {
-            Some(p) => p,
-            None => break,
-        };
-
-        let block_end = xml[tag_start..]
-            .find("</AudioStreams>")
-            .or_else(|| xml[tag_start..].find("</SubtitlesStreams>"))
-            .map(|p| tag_start + p + 20)
-            .unwrap_or(xml.len());
-
-        let block = &xml[tag_start..block_end];
-
-        if let (Some(stream_id_str), Some(info_id)) = (
-            extract_tag(block, "StreamID"),
-            extract_tag(block, "StreamInfo_ID"),
-        ) {
-            if let Ok(stream_num) = stream_id_str.parse::<u16>() {
-                map.insert(info_id, stream_num);
+fn parse_playback_config(text: &str, map: &mut HashMap<String, u16>) {
+    for tag_name in ["AudioStreams", "SubtitlesStreams"] {
+        let mut from = 0;
+        while let Some((start, end)) = xml::find_element(text, tag_name, from) {
+            let block = &text[start..end];
+            if let (Some(stream_id_str), Some(info_id)) = (
+                xml::text(block, "StreamID"),
+                xml::text(block, "StreamInfo_ID"),
+            ) {
+                if let Ok(stream_num) = stream_id_str.parse::<u16>() {
+                    map.insert(info_id, stream_num);
+                }
            }
+            from = end;
        }
-
-        pos = block_end;
    }
 }
-
-fn extract_tag(xml: &str, tag: &str) -> Option<String> {
-    let open = format!("<{tag}>");
-    let close = format!("</{tag}>");
-    let start = xml.find(&open)? + open.len();
-    let end = xml[start..].find(&close)? + start;
-    Some(xml[start..end].trim().to_string())
-}
@@ -4,8 +4,8 @@
 //! When both exist, language_streams.txt provides structured types while
 //! menu_base.prop provides stream number → button name mapping.

-use super::{LabelPurpose, LabelQualifier, StreamLabel, StreamLabelType, vocab};
-use crate::sector::SectorReader;
+use super::{LabelPurpose, LabelQualifier, ParseResult, StreamLabel, StreamLabelType, vocab};
+use crate::sector::SectorSource;
 use crate::udf::UdfFs;
 use std::collections::HashMap;

@@ -14,7 +14,7 @@ pub fn detect(udf: &UdfFs) -> bool {
        || super::jar_file_exists(udf, "language_streams.txt")
 }

-pub fn parse(reader: &mut dyn SectorReader, udf: &UdfFs) -> Option<Vec<StreamLabel>> {
+pub fn parse(reader: &mut dyn SectorSource, udf: &UdfFs) -> Option<ParseResult> {
    // Try language_streams.txt first (richer structured data)
    let ls_labels = parse_language_streams(reader, udf);

@@ -22,12 +22,18 @@ pub fn parse(reader: &mut dyn SectorReader, udf: &UdfFs) -> Option<Vec<StreamLab
    let mb_labels = parse_menu_base(reader, udf);

    // If we have both, merge: language_streams for structure, menu_base for names
-    match (ls_labels, mb_labels) {
-        (Some(ls), Some(mb)) => Some(merge(ls, mb)),
-        (Some(ls), None) => Some(ls),
-        (None, Some(mb)) => Some(mb),
-        (None, None) => None,
+    let labels = match (ls_labels, mb_labels) {
+        (Some(ls), Some(mb)) => merge(ls, mb),
+        (Some(ls), None) => ls,
+        (None, Some(mb)) => mb,
+        (None, None) => return None,
+    };
+    if labels.is_empty() {
+        return None;
    }
+    // High confidence: both language_streams.txt and menu_base.prop
+    // are structured key-value formats with documented types.
+    Some(ParseResult::high(labels))
 }

 fn merge(ls: Vec<StreamLabel>, mb: Vec<StreamLabel>) -> Vec<StreamLabel> {
@@ -49,7 +55,7 @@ fn merge(ls: Vec<StreamLabel>, mb: Vec<StreamLabel>) -> Vec<StreamLabel> {

 // ── language_streams.txt parser ────────────────────────────────────────────

-fn parse_language_streams(reader: &mut dyn SectorReader, udf: &UdfFs) -> Option<Vec<StreamLabel>> {
+fn parse_language_streams(reader: &mut dyn SectorSource, udf: &UdfFs) -> Option<Vec<StreamLabel>> {
    let data = super::read_jar_file(reader, udf, "language_streams.txt")?;
    let text = std::str::from_utf8(&data).ok()?;

@@ -172,9 +178,167 @@ fn parse_language_streams(reader: &mut dyn SectorReader, udf: &UdfFs) -> Option<
    Some(labels)
 }

+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Build a minimal menu_base.prop text and run `parse_menu_base`'s
+    /// inner logic via a temporary closure. This isolates the prop
+    /// parsing without needing a SectorSource.
+    fn parse_props(text: &str) -> Vec<StreamLabel> {
+        // Mirror the inner loop of parse_menu_base exactly. Kept
+        // separate so the test doesn't need disc fixtures.
+        use std::collections::HashMap;
+        let mut entries: HashMap<String, HashMap<String, String>> = HashMap::new();
+        for line in text.lines() {
+            let line = line.trim();
+            if line.is_empty() || line.starts_with('#') {
+                continue;
+            }
+            let Some(eq_pos) = line.find('=') else {
+                continue;
+            };
+            let full_key = &line[..eq_pos];
+            let value = &line[eq_pos + 1..];
+            if let Some(dot_pos) = full_key.rfind('.') {
+                entries
+                    .entry(full_key[..dot_pos].to_string())
+                    .or_default()
+                    .insert(full_key[dot_pos + 1..].to_string(), value.to_string());
+            }
+        }
+        let mut labels = Vec::new();
+        for (prefix, props) in &entries {
+            let is_audio = props
+                .get("class")
+                .is_some_and(|c| c.contains("AudioButton"))
+                || prefix.starts_with("audio_");
+            let is_subtitle = props
+                .get("class")
+                .is_some_and(|c| c.contains("SubtitleButton"))
+                || prefix.starts_with("subtitle_");
+            let stream_num_str = props
+                .get("streamNumber")
+                .or_else(|| props.get("audioStream"))
+                .or_else(|| props.get("subtitleStream"));
+            let stream_num: u16 = match stream_num_str.and_then(|s| s.parse().ok()) {
+                Some(n) if n > 0 => n,
+                _ => continue,
+            };
+            if !is_audio && !is_subtitle {
+                continue;
+            }
+            let name = props.get("name").cloned().unwrap_or_default();
+            let purpose = match vocab::purpose(&name) {
+                LabelPurpose::Normal if prefix.contains("comm") => LabelPurpose::Commentary,
+                p => p,
+            };
+            let qualifier = if is_subtitle {
+                vocab::qualifier(&name)
+            } else {
+                LabelQualifier::None
+            };
+            let stream_type = if is_audio {
+                StreamLabelType::Audio
+            } else {
+                StreamLabelType::Subtitle
+            };
+            let language = props
+                .get("audioLanguage")
+                .or_else(|| props.get("subtitleLanguage"))
+                .cloned()
+                .unwrap_or_default();
+            labels.push(StreamLabel {
+                stream_number: stream_num,
+                stream_type,
+                language,
+                name,
+                purpose,
+                qualifier,
+                codec_hint: String::new(),
+                variant: String::new(),
+            });
+        }
+        labels.sort_by_key(|l| (l.stream_type as u8, l.stream_number));
+        labels
+    }
+
+    #[test]
+    fn commentary_via_name() {
+        let labels = parse_props(
+            "audio_1.class=AudioButton\n\
+             audio_1.streamNumber=2\n\
+             audio_1.name=Director's Commentary\n\
+             audio_1.audioLanguage=eng\n",
+        );
+        assert_eq!(labels.len(), 1);
+        assert_eq!(labels[0].purpose, LabelPurpose::Commentary);
+        assert_eq!(labels[0].language, "eng");
+    }
+
+    #[test]
+    fn commentary_via_prefix_when_name_silent() {
+        let labels = parse_props(
+            "audio_commentary_1.class=AudioButton\n\
+             audio_commentary_1.streamNumber=2\n\
+             audio_commentary_1.name=Track 2\n\
+             audio_commentary_1.audioLanguage=eng\n",
+        );
+        assert_eq!(labels[0].purpose, LabelPurpose::Commentary);
+    }
+
+    #[test]
+    fn commenter_does_not_false_match_commentary() {
+        // Regression for the pre-refactor `name.contains("comment")`
+        // bug: this would wrongly classify a "Commenter Pro" track as
+        // Commentary. vocab::purpose enforces a word boundary.
+        let labels = parse_props(
+            "audio_1.class=AudioButton\n\
+             audio_1.streamNumber=2\n\
+             audio_1.name=Commenter Pro Track\n\
+             audio_1.audioLanguage=eng\n",
+        );
+        assert_eq!(labels[0].purpose, LabelPurpose::Normal);
+    }
+
+    #[test]
+    fn descriptive_via_name() {
+        let labels = parse_props(
+            "audio_1.class=AudioButton\n\
+             audio_1.streamNumber=3\n\
+             audio_1.name=English Descriptive Audio\n",
+        );
+        assert_eq!(labels[0].purpose, LabelPurpose::Descriptive);
+    }
+
+    #[test]
+    fn sdh_only_on_subtitles() {
+        // SDH applied to a subtitle stream.
+        let labels = parse_props(
+            "subtitle_1.class=SubtitleButton\n\
+             subtitle_1.streamNumber=4\n\
+             subtitle_1.name=English SDH\n",
+        );
+        assert_eq!(labels[0].qualifier, LabelQualifier::Sdh);
+    }
+
+    #[test]
+    fn sdh_not_applied_to_audio_stream_even_if_name_contains_sdh() {
+        // Audio streams should not pick up SDH (it's a subtitle
+        // concept). Edge case: badly-authored name happens to include
+        // "SDH" — we don't propagate it to audio metadata.
+        let labels = parse_props(
+            "audio_1.class=AudioButton\n\
+             audio_1.streamNumber=5\n\
+             audio_1.name=English SDH (track?)\n",
+        );
+        assert_eq!(labels[0].qualifier, LabelQualifier::None);
+    }
+}
+
 // ── menu_base.prop parser ──────────────────────────────────────────────────

-fn parse_menu_base(reader: &mut dyn SectorReader, udf: &UdfFs) -> Option<Vec<StreamLabel>> {
+fn parse_menu_base(reader: &mut dyn SectorSource, udf: &UdfFs) -> Option<Vec<StreamLabel>> {
    let data = super::read_jar_file(reader, udf, "menu_base.prop")?;
    let text = std::str::from_utf8(&data).ok()?;

@@ -231,16 +395,20 @@ fn parse_menu_base(reader: &mut dyn SectorReader, udf: &UdfFs) -> Option<Vec<Str
        }

        let name = props.get("name").cloned().unwrap_or_default();
-        let name_lower = name.to_lowercase();

-        let purpose = if name_lower.contains("comment") || prefix.contains("comm") {
-            LabelPurpose::Commentary
-        } else {
-            LabelPurpose::Normal
+        // Purpose: ask vocab first (word-boundary matched — avoids the
+        // "Commenter" false positive the prior `name.contains("comment")`
+        // had). Then fall back to the structural prefix check
+        // (`audio_commentary.foo`-style keys group commentary streams
+        // regardless of display name).
+        let purpose = match vocab::purpose(&name) {
+            LabelPurpose::Normal if prefix.contains("comm") => LabelPurpose::Commentary,
+            p => p,
        };

-        let qualifier = if is_subtitle && name_lower.contains("sdh") {
-            LabelQualifier::Sdh
+        // Qualifier: only apply to subtitles (SDH is a subtitle concept).
+        let qualifier = if is_subtitle {
+            vocab::qualifier(&name)
        } else {
            LabelQualifier::None
        };
@@ -0,0 +1,261 @@
+//! "dbp" framework — Magnolia Pictures BD-J authoring shop (per
+//! `bd-live.magpictures.com` referenced in the disc's
+//! `com/dbp/bluray.MenuXlet.perm`). Detected on UHD discs whose
+//! `/BDMV/JAR/<x>.jar` (top-level, not in a subdir) contains
+//! `com/dbp/` package paths.
+//!
+//! Stream labels live as plain ASCII strings inside compiled `.class`
+//! files in the jar — a quirk of the menu-rendering layer encoding
+//! its TextField positions and content as constant strings the
+//! Java compiler retained in the class string pool. Format observed
+//! in the corpus (Civil War UHD, 2024):
+//!
+//! ```text
+//! LTextField,Audio1,English Dolby Atmos,Fontstrip_Composite,...
+//! RTextField,Audio2,English Descriptive Audio,Fontstrip_Composite,...
+//! HTextField,Subtitle1,English SDH,Fontstrip_Composite,...
+//! ATextField,Subtitle0,None,Fontstrip_Composite,...
+//! ```
+//!
+//! The single uppercase letter before `TextField` is string-pool
+//! prefix noise — the parser anchors on `TextField,` regardless of
+//! what precedes it. `Subtitle0` is the disable-subtitles menu
+//! button and is skipped (not a real subtitle stream).
+//!
+//! ## Implementation
+//!
+//! v2 (2026-05-10): rewritten on top of [`super::class_reader`] —
+//! iterates `CpInfo::Utf8` constant-pool entries instead of raw byte
+//! scanning each class file. Equivalent label coverage (the literal
+//! `TextField,...` strings live in the CP as Utf8 entries), but
+//! structurally cleaner: no false-positive risk from method bytecode
+//! or attribute names happening to contain `TextField,`. Language /
+//! purpose / qualifier classification moved to [`super::vocab`] so all
+//! Java-parser families share one source of truth.
+
+use super::class_reader::CpInfo;
+use super::{ParseResult, StreamLabel, StreamLabelType, jar, vocab};
+use crate::sector::SectorSource;
+use crate::udf::UdfFs;
+use std::collections::BTreeMap;
+
+/// dbp detect can't peek inside a jar without a SectorSource (the
+/// trait function only takes `&UdfFs`), so we trigger on the cheap
+/// signal "any top-level .jar in /BDMV/JAR/." That fires on every
+/// BD-J disc, but parse() does the real `com/dbp/` check and
+/// returns None on a mismatch — so this parser only ever consumes
+/// time on discs that fell through every earlier parser.
+pub fn detect(udf: &UdfFs) -> bool {
+    jar::has_any_top_level_jar(udf)
+}
+
+pub fn parse(reader: &mut dyn SectorSource, udf: &UdfFs) -> Option<ParseResult> {
+    jar::for_each_jar(reader, udf, |_entry_name, archive| {
+        if !jar::has_path_prefix(archive, "com/dbp/") {
+            return None;
+        }
+        let labels = scan_jar(archive);
+        if labels.is_empty() {
+            None
+        } else {
+            // High confidence: TextField,Audio1,... is a stable anchor
+            // pattern + vocab routes language/purpose/qualifier.
+            Some(ParseResult::high(labels))
+        }
+    })
+}
+
+fn scan_jar(archive: &mut jar::Jar) -> Vec<StreamLabel> {
+    // BTreeMap so we keep the highest-numbered (last-written) label
+    // for each stream slot deterministic across runs. The same
+    // TextField,Audio1,... string can appear in multiple classes
+    // (button-state variants, localization fallbacks). Last write
+    // wins — they should all agree, but the structure is defensive.
+    let mut audios: BTreeMap<u16, String> = BTreeMap::new();
+    let mut subs: BTreeMap<u16, String> = BTreeMap::new();
+
+    jar::for_each_class(archive, |_class_name, class| {
+        for (_idx, cp) in class.constant_pool.iter() {
+            if let CpInfo::Utf8(s) = cp {
+                collect_textfield(s, &mut audios, &mut subs);
+            }
+        }
+    });
+
+    let mut out = Vec::new();
+    for (num, label) in audios {
+        out.push(make_label(num, label, StreamLabelType::Audio));
+    }
+    for (num, label) in subs {
+        out.push(make_label(num, label, StreamLabelType::Subtitle));
+    }
+    out
+}
+
+fn collect_textfield(
+    s: &str,
+    audios: &mut BTreeMap<u16, String>,
+    subs: &mut BTreeMap<u16, String>,
+) {
+    // Anchor on "TextField," — the prefix character before it varies
+    // (string-pool ordering inside compiled Java) and is irrelevant.
+    let Some(idx) = s.find("TextField,") else {
+        return;
+    };
+    let after = &s[idx + "TextField,".len()..];
+    let mut parts = after.splitn(3, ',');
+    let kind_n = parts.next().unwrap_or("").trim();
+    let label = parts.next().unwrap_or("").trim();
+    if label.is_empty() {
+        return;
+    }
+    if let Some(rest) = kind_n.strip_prefix("Audio") {
+        if let Ok(n) = rest.parse::<u16>() {
+            audios.insert(n, label.to_string());
+        }
+    } else if let Some(rest) = kind_n.strip_prefix("Subtitle") {
+        if let Ok(n) = rest.parse::<u16>() {
+            // Subtitle0 is conventionally the "None / Off" disable
+            // button, not an actual subtitle stream.
+            if n > 0 {
+                subs.insert(n, label.to_string());
+            }
+        }
+    }
+}
+
+fn make_label(num: u16, label: String, stream_type: StreamLabelType) -> StreamLabel {
+    let lang_info = vocab::lang(&label);
+    let language = lang_info.map(|l| l.code).unwrap_or("").to_string();
+    let variant = lang_info.map(|l| l.variant).unwrap_or("").to_string();
+    let qualifier = vocab::qualifier(&label);
+    let purpose = vocab::purpose(&label);
+    StreamLabel {
+        stream_number: num,
+        stream_type,
+        language,
+        name: label,
+        purpose,
+        qualifier,
+        codec_hint: String::new(),
+        variant,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::{LabelPurpose, LabelQualifier};
+    use super::*;
+
+    #[test]
+    fn collect_extracts_audio_and_subtitle_indices() {
+        let mut audios = BTreeMap::new();
+        let mut subs = BTreeMap::new();
+        let lines = [
+            "LTextField,Audio1,English Dolby Atmos,Fontstrip_Composite,296,763,275,25,left",
+            "RTextField,Audio2,English Descriptive Audio,Fontstrip_Composite,296,803,275,25,left",
+            "RTextField,Audio3,Spanish 5.1 Dolby Digital,Fontstrip_Composite,296,843,275,25,left",
+            "ATextField,Subtitle0,None,Fontstrip_Composite,1312,843,275,25,left",
+            "HTextField,Subtitle1,English SDH,Fontstrip_Composite,1312,763,275,25,left",
+            "DTextField,Subtitle2,Spanish,Fontstrip_Composite,1312,803,275,25,left",
+        ];
+        for s in &lines {
+            collect_textfield(s, &mut audios, &mut subs);
+        }
+        assert_eq!(audios.len(), 3);
+        assert_eq!(audios[&1], "English Dolby Atmos");
+        assert_eq!(audios[&2], "English Descriptive Audio");
+        assert_eq!(audios[&3], "Spanish 5.1 Dolby Digital");
+        // Subtitle0 ("None") is skipped — disable button, not a stream.
+        assert_eq!(subs.len(), 2);
+        assert_eq!(subs[&1], "English SDH");
+        assert_eq!(subs[&2], "Spanish");
+    }
+
+    #[test]
+    fn collect_ignores_non_textfield_strings() {
+        let mut audios = BTreeMap::new();
+        let mut subs = BTreeMap::new();
+        for s in [
+            "GraphicButton,SU_Audio",
+            "AudioMenu",
+            "CommentaryMenuAlternateScenes",
+            "PrimaryAudioControl",
+        ] {
+            collect_textfield(s, &mut audios, &mut subs);
+        }
+        assert!(audios.is_empty());
+        assert!(subs.is_empty());
+    }
+
+    #[test]
+    fn make_label_routes_via_vocab() {
+        let l = make_label(1, "English SDH".to_string(), StreamLabelType::Subtitle);
+        assert_eq!(l.language, "eng");
+        assert_eq!(l.qualifier, LabelQualifier::Sdh);
+        assert_eq!(l.purpose, LabelPurpose::Normal);
+    }
+
+    #[test]
+    fn make_label_descriptive_audio() {
+        let l = make_label(
+            2,
+            "English Descriptive Audio".to_string(),
+            StreamLabelType::Audio,
+        );
+        assert_eq!(l.language, "eng");
+        assert_eq!(l.purpose, LabelPurpose::Descriptive);
+    }
+
+    #[test]
+    fn make_label_commentary() {
+        let l = make_label(
+            3,
+            "English Director's Commentary".to_string(),
+            StreamLabelType::Audio,
+        );
+        assert_eq!(l.language, "eng");
+        assert_eq!(l.purpose, LabelPurpose::Commentary);
+    }
+
+    #[test]
+    fn make_label_compound_languages_populate_variant() {
+        let brazilian = make_label(1, "Brazilian Portuguese 5.1".into(), StreamLabelType::Audio);
+        assert_eq!(brazilian.language, "por");
+        assert_eq!(brazilian.variant, "Brazilian");
+
+        let castilian = make_label(1, "Castilian Spanish".into(), StreamLabelType::Audio);
+        assert_eq!(castilian.language, "spa");
+        assert_eq!(castilian.variant, "Castilian");
+
+        let canadian = make_label(
+            1,
+            "Canadian French Dolby Digital".into(),
+            StreamLabelType::Audio,
+        );
+        assert_eq!(canadian.language, "fra");
+        assert_eq!(canadian.variant, "Canadian");
+    }
+
+    #[test]
+    fn make_label_bare_language_has_empty_variant() {
+        let l = make_label(1, "English Dolby Atmos".into(), StreamLabelType::Audio);
+        assert_eq!(l.language, "eng");
+        assert_eq!(l.variant, "");
+    }
+
+    #[test]
+    fn make_label_unknown_language_is_empty() {
+        // vocab::lang returns None — make_label converts both fields to "".
+        let l = make_label(1, "Klingon Dolby Atmos".into(), StreamLabelType::Audio);
+        assert_eq!(l.language, "");
+        assert_eq!(l.variant, "");
+    }
+
+    #[test]
+    fn make_label_rnib_descriptive_service() {
+        let l = make_label(1, "English RNIB".into(), StreamLabelType::Subtitle);
+        assert_eq!(l.language, "eng");
+        assert_eq!(l.qualifier, LabelQualifier::DescriptiveService);
+    }
+}
@@ -0,0 +1,151 @@
+//! BD-J jar utilities — common scaffolding for parsers that read
+//! `/BDMV/JAR/*.jar`.
+//!
+//! Composes with [`class_reader`](super::class_reader) for structured
+//! `.class` access. Used by `dbp` (string-pool scan via constant pool)
+//! and `deluxe` (bytecode pattern matching) — those parsers express
+//! "open every top-level jar, look at every .class inside" without
+//! repeating the zip-archive boilerplate.
+
+// `try_each_class` is staged for `labels::deluxe`, which needs the
+// early-return form to short-circuit class iteration on a match.
+// dead-code allow comes off when deluxe lands.
+#![allow(dead_code)]
+
+use super::class_reader::ClassFile;
+use crate::sector::SectorSource;
+use crate::udf::UdfFs;
+use std::io::Cursor;
+use zip::ZipArchive;
+
+/// In-memory zip archive: backed by a `Vec<u8>` read from UDF. Owns
+/// the buffer; callers pass it to [`has_path_prefix`], [`for_each_class`],
+/// etc.
+pub type Jar = ZipArchive<Cursor<Vec<u8>>>;
+
+/// True if `/BDMV/JAR/` contains at least one top-level `.jar` file
+/// (not under a subdir). Used by `detect()` in parsers whose real
+/// signal lives inside a jar — they can't open the jar without a
+/// `SectorSource`, so they use this cheap pre-check and do the real
+/// `com/<vendor>/` discriminator in `parse()`.
+pub fn has_any_top_level_jar(udf: &UdfFs) -> bool {
+    let Some(jar_dir) = udf.find_dir("/BDMV/JAR") else {
+        return false;
+    };
+    jar_dir
+        .entries
+        .iter()
+        .any(|e| !e.is_dir && e.name.to_lowercase().ends_with(".jar"))
+}
+
+/// Open every top-level `*.jar` entry in `/BDMV/JAR/` and yield each
+/// `(entry_name, Jar)` to `f`. Returns the first `Some(R)` the callback
+/// produces, or `None` if every jar was visited without a hit.
+///
+/// "Top-level" means entries directly under `/BDMV/JAR/`, not nested
+/// under a subdir. (Pixelogic, Criterion, Paramount, etc. put their
+/// data files inside `/BDMV/JAR/<x>/`; dbp and Deluxe put their jar
+/// directly at `/BDMV/JAR/<name>.jar`.)
+///
+/// Entries that fail to read from UDF or that aren't valid zips are
+/// silently skipped — same defensive shape as the existing dbp parser.
+pub fn for_each_jar<R, F>(reader: &mut dyn SectorSource, udf: &UdfFs, mut f: F) -> Option<R>
+where
+    F: FnMut(&str, &mut Jar) -> Option<R>,
+{
+    let jar_dir = udf.find_dir("/BDMV/JAR")?;
+    for entry in &jar_dir.entries {
+        if entry.is_dir {
+            continue;
+        }
+        if !entry.name.to_lowercase().ends_with(".jar") {
+            continue;
+        }
+        let path = format!("/BDMV/JAR/{}", entry.name);
+        let Ok(bytes) = udf.read_file(reader, &path) else {
+            continue;
+        };
+        let Ok(mut archive) = ZipArchive::new(Cursor::new(bytes)) else {
+            continue;
+        };
+        if let Some(r) = f(&entry.name, &mut archive) {
+            return Some(r);
+        }
+    }
+    None
+}
+
+/// True if any entry in this jar's central directory starts with
+/// `prefix`. Fast — only reads filenames, never extracts bytes.
+///
+/// Used by parsers as a cheap "is this MY framework's jar?" check
+/// (e.g. `has_path_prefix(archive, "com/dbp/")` for dbp,
+/// `has_path_prefix(archive, "com/bydeluxe/")` for Deluxe).
+pub fn has_path_prefix(archive: &mut Jar, prefix: &str) -> bool {
+    for i in 0..archive.len() {
+        if let Ok(f) = archive.by_index(i) {
+            if f.name().starts_with(prefix) {
+                return true;
+            }
+        }
+    }
+    false
+}
+
+/// Iterate every `.class` entry in the jar, parse it with
+/// [`class_reader`], and call `f` with `(entry_name, &ClassFile)`.
+///
+/// Entries that fail to read or parse are silently skipped — this is
+/// label-extraction code, robustness matters more than completeness.
+/// Callers that need to know which classes failed should use the
+/// lower-level [`class_reader`] API directly.
+pub fn for_each_class<F>(archive: &mut Jar, mut f: F)
+where
+    F: FnMut(&str, &ClassFile),
+{
+    for i in 0..archive.len() {
+        let Ok(mut entry) = archive.by_index(i) else {
+            continue;
+        };
+        if !entry.name().ends_with(".class") {
+            continue;
+        }
+        let name = entry.name().to_string();
+        let mut bytes = Vec::with_capacity(entry.size() as usize);
+        if std::io::Read::read_to_end(&mut entry, &mut bytes).is_err() {
+            continue;
+        }
+        let Ok(class) = ClassFile::parse(&bytes) else {
+            continue;
+        };
+        f(&name, &class);
+    }
+}
+
+/// Like [`for_each_class`] but allows the callback to short-circuit
+/// iteration. Returns the first `Some(R)` the callback produces.
+pub fn try_each_class<R, F>(archive: &mut Jar, mut f: F) -> Option<R>
+where
+    F: FnMut(&str, &ClassFile) -> Option<R>,
+{
+    for i in 0..archive.len() {
+        let Ok(mut entry) = archive.by_index(i) else {
+            continue;
+        };
+        if !entry.name().ends_with(".class") {
+            continue;
+        }
+        let name = entry.name().to_string();
+        let mut bytes = Vec::with_capacity(entry.size() as usize);
+        if std::io::Read::read_to_end(&mut entry, &mut bytes).is_err() {
+            continue;
+        }
+        let Ok(class) = ClassFile::parse(&bytes) else {
+            continue;
+        };
+        if let Some(r) = f(&name, &class) {
+            return Some(r);
+        }
+    }
+    None
+}
@@ -0,0 +1,597 @@
+//! Universal MPLS-based stream labels.
+//!
+//! Unlike the framework-specific parsers in this directory (dbp,
+//! pixelogic, ctrm, criterion, ...), this module is the *floor*:
+//! every Blu-ray ships with MPLS playlists under `/BDMV/PLAYLIST/`,
+//! and every MPLS file has an STN table with per-stream ISO 639-2
+//! language codes plus coding-type / channel-layout / sample-rate
+//! bytes from the BD spec.
+//!
+//! The framework parsers extract richer editorial labels ("English
+//! Dolby Atmos", "Director's Commentary") when the disc was authored
+//! with a recognized tool. When none of them match (e.g. a "no BD-J"
+//! disc, or an authoring framework we haven't catalogued), MPLS still
+//! gives us language + codec on every stream — enough to render
+//! something more useful than the bare PID.
+//!
+//! Output confidence is Low: MPLS carries language + codec but
+//! never purpose/qualifier info (no way to tell "Commentary" from
+//! "Normal" from the STN table alone). Higher-confidence framework
+//! parsers, when present, always win on the registry's max-by-confidence
+//! tiebreaker — MPLS is only chosen when nothing else matched.
+
+use super::{
+    LabelPurpose, LabelQualifier, ParseResult, StreamLabel, StreamLabelType,
+    vocab::{self, LangInfo},
+};
+use crate::sector::SectorSource;
+use crate::udf::UdfFs;
+
+/// True iff `/BDMV/PLAYLIST/` exists and contains at least one
+/// `.mpls` file. Cheap directory walk only — no sector reads.
+pub fn detect(udf: &UdfFs) -> bool {
+    let Some(dir) = udf.find_dir("/BDMV/PLAYLIST") else {
+        return false;
+    };
+    dir.entries
+        .iter()
+        .any(|e| !e.is_dir && has_mpls_extension(&e.name))
+}
+
+/// Walk every `*.mpls` in `/BDMV/PLAYLIST/`, parse it, and convert
+/// each StreamEntry to a [`StreamLabel`]. Streams shared across
+/// playlists (same PID) are deduped.
+///
+/// Returns `None` if no labels could be produced (e.g. no .mpls files
+/// parsed successfully, or every parsed stream was a type we skip
+/// like IG / DV EL).
+pub fn parse(reader: &mut dyn SectorSource, udf: &UdfFs) -> Option<ParseResult> {
+    let playlist_dir = udf.find_dir("/BDMV/PLAYLIST")?;
+
+    // Collect mpls filenames first so we don't hold a borrow on udf
+    // while we call udf.read_file (which takes &self).
+    let mpls_names: Vec<String> = playlist_dir
+        .entries
+        .iter()
+        .filter(|e| !e.is_dir && has_mpls_extension(&e.name))
+        .map(|e| e.name.clone())
+        .collect();
+
+    if mpls_names.is_empty() {
+        return None;
+    }
+
+    let mut labels: Vec<StreamLabel> = Vec::new();
+    // (stream_type_tag, language, codec_hint, pid) — PID is the
+    // canonical "same physical stream" key; type+lang+codec round
+    // out the rare case where two distinct logical streams happen
+    // to share a PID across playlists with different metadata.
+    let mut seen: Vec<(u8, String, String, u16)> = Vec::new();
+
+    // Global 1-based counters keyed by StreamLabelType. Incremented
+    // only when an entry survives dedup, so stream_numbers are dense
+    // (1, 2, 3, ...) per type across the whole disc — not reset per
+    // playlist. A disc with 2 MPLS files that each list the same
+    // 8 audio streams ends up with audio_1..audio_8, not audio_1..
+    // audio_16 or audio_1..audio_8 with audio_1 duplicated.
+    let mut audio_idx: u16 = 0;
+    let mut sub_idx: u16 = 0;
+
+    for name in &mpls_names {
+        let path = format!("/BDMV/PLAYLIST/{}", name);
+        let Ok(data) = udf.read_file(reader, &path) else {
+            continue;
+        };
+        let Ok(playlist) = crate::mpls::parse(&data) else {
+            continue;
+        };
+
+        for entry in &playlist.streams {
+            let label_type = match entry.stream_type {
+                2 | 5 => StreamLabelType::Audio, // primary + secondary audio
+                3 => StreamLabelType::Subtitle,  // PG subtitle
+                // 1 = primary video, 6 = secondary video, 7 = DV EL
+                //     → no StreamLabelType variant for video, skip.
+                // 4 = IG (interactive graphics) — not a user-facing
+                //     stream, skip.
+                _ => continue,
+            };
+
+            let language = normalize_language(&entry.language);
+            let name = language_display_name(&language);
+            let codec_hint = build_codec_hint(label_type, entry);
+
+            let type_tag = type_tag(label_type);
+            let key = (type_tag, language.clone(), codec_hint.clone(), entry.pid);
+            if seen.contains(&key) {
+                continue;
+            }
+            seen.push(key);
+
+            let stream_number = match label_type {
+                StreamLabelType::Audio => {
+                    audio_idx += 1;
+                    audio_idx
+                }
+                StreamLabelType::Subtitle => {
+                    sub_idx += 1;
+                    sub_idx
+                }
+            };
+
+            labels.push(StreamLabel {
+                stream_number,
+                stream_type: label_type,
+                language,
+                name,
+                purpose: LabelPurpose::Normal,
+                qualifier: LabelQualifier::None,
+                codec_hint,
+                variant: String::new(),
+            });
+        }
+    }
+
+    if labels.is_empty() {
+        return None;
+    }
+
+    // MPLS gives language + codec but never editorial info (no
+    // commentary/SDH/director's cut). Low confidence means framework
+    // parsers (paramount, criterion, pixelogic, ctrm, dbp, deluxe) always
+    // win when they match. MPLS only gets chosen as the parser when
+    // nothing else fired — exactly the universal-fallback role we want.
+    Some(ParseResult::low(labels))
+}
+
+fn has_mpls_extension(name: &str) -> bool {
+    // Case-insensitive ".mpls" suffix. Some discs use uppercase,
+    // some lowercase; UDF filenames preserve case but we don't.
+    let n = name.len();
+    if n < 5 {
+        return false;
+    }
+    name[n - 5..].eq_ignore_ascii_case(".mpls")
+}
+
+/// Lowercase + trim the raw 3-char ISO 639-2 code. If the lowered
+/// string maps via [`vocab::lang`] (it won't for plain "eng" — that
+/// matcher is for English-name fragments, not codes) use its
+/// canonical code; otherwise return the trimmed lowercase string.
+fn normalize_language(raw: &str) -> String {
+    let trimmed = raw.trim().to_ascii_lowercase();
+    if trimmed.is_empty() {
+        return String::new();
+    }
+    // vocab::lang() matches free-form English names, not ISO 639-2
+    // codes — so for the typical MPLS payload ("eng", "fra", ...)
+    // it returns None and we keep the trimmed code.
+    if let Some(LangInfo { code, .. }) = vocab::lang(&trimmed) {
+        return code.to_string();
+    }
+    trimmed
+}
+
+/// Human-readable English name for an ISO 639-2 code, or empty if
+/// the code is unknown. Kept inline rather than in vocab because
+/// vocab is the *reverse* mapping (name → code).
+pub(crate) fn language_display_name(iso: &str) -> String {
+    match iso {
+        "eng" => "English",
+        "fra" | "fre" => "French",
+        "spa" => "Spanish",
+        "deu" | "ger" => "German",
+        "ita" => "Italian",
+        "jpn" => "Japanese",
+        "zho" | "chi" => "Chinese",
+        "kor" => "Korean",
+        "por" => "Portuguese",
+        "pol" => "Polish",
+        "ces" | "cze" => "Czech",
+        "hun" => "Hungarian",
+        "nld" | "dut" => "Dutch",
+        "ara" => "Arabic",
+        "hin" => "Hindi",
+        "tur" => "Turkish",
+        "tha" => "Thai",
+        "swe" => "Swedish",
+        "nor" => "Norwegian",
+        "dan" => "Danish",
+        "fin" => "Finnish",
+        "heb" => "Hebrew",
+        "rus" => "Russian",
+        "ell" | "gre" => "Greek",
+        "vie" => "Vietnamese",
+        "ind" => "Indonesian",
+        "msa" | "may" => "Malay",
+        "ukr" => "Ukrainian",
+        "ron" | "rum" => "Romanian",
+        "bul" => "Bulgarian",
+        "hrv" => "Croatian",
+        "srp" => "Serbian",
+        "slk" | "slo" => "Slovak",
+        "slv" => "Slovenian",
+        "est" => "Estonian",
+        "lav" => "Latvian",
+        "lit" => "Lithuanian",
+        "isl" | "ice" => "Icelandic",
+        "eus" | "baq" => "Basque",
+        "cat" => "Catalan",
+        "glg" => "Galician",
+        _ => "",
+    }
+    .to_string()
+}
+
+/// Map BD coding_type byte → codec name. Returns empty for unknown
+/// bytes (the table covers everything the spec defines, but unknown
+/// values are still possible on malformed discs).
+pub(crate) fn codec_name(coding_type: u8) -> &'static str {
+    match coding_type {
+        0x02 => "MPEG-2",
+        0x1B => "H.264",
+        0x24 => "HEVC",
+        0x80 => "LPCM",
+        0x81 => "AC-3",
+        0x82 => "DTS",
+        0x83 => "TrueHD",
+        0x84 => "AC-3+",
+        0x85 => "DTS-HD",
+        0x86 => "DTS-HD MA",
+        0x90 => "PG",
+        0x91 => "IG",
+        0xA1 => "AC-3+ Secondary",
+        0xA2 => "DTS-HD Secondary",
+        _ => "",
+    }
+}
+
+/// Build the final `codec_hint`. For audio streams, optionally
+/// append " <channels>" and/or " <rate>" suffixes. Sample rate is
+/// only spelled out for non-48k (the universal default).
+fn build_codec_hint(label_type: StreamLabelType, entry: &crate::mpls::StreamEntry) -> String {
+    let base = codec_name(entry.coding_type);
+    if base.is_empty() {
+        return String::new();
+    }
+
+    if label_type != StreamLabelType::Audio {
+        return base.to_string();
+    }
+
+    let mut out = base.to_string();
+
+    let channels = match entry.audio_format {
+        1 => Some("mono"),
+        3 => Some("2.0"),
+        6 => Some("5.1"),
+        12 => Some("7.1"),
+        _ => None,
+    };
+    if let Some(ch) = channels {
+        out.push(' ');
+        out.push_str(ch);
+    }
+
+    // 1 = 48 kHz (universal default, omit). Only call out higher rates.
+    let rate = match entry.audio_rate {
+        4 => Some("96kHz"),
+        5 => Some("192kHz"),
+        _ => None,
+    };
+    if let Some(r) = rate {
+        out.push(' ');
+        out.push_str(r);
+    }
+
+    out
+}
+
+/// Dedup-tag for the label type. `u8` instead of `StreamLabelType`
+/// itself because the enum does not derive `Hash` / `Eq`-by-discriminant
+/// in a way that we want to couple to (and `==` works fine for the
+/// linear `Vec::contains` lookup we do).
+fn type_tag(t: StreamLabelType) -> u8 {
+    match t {
+        StreamLabelType::Audio => 1,
+        StreamLabelType::Subtitle => 2,
+    }
+}
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::mpls::{Playlist, StreamEntry};
+
+    fn audio_entry(pid: u16, coding: u8, fmt: u8, rate: u8, lang: &str) -> StreamEntry {
+        StreamEntry {
+            stream_type: 2,
+            pid,
+            coding_type: coding,
+            video_format: 0,
+            video_rate: 0,
+            audio_format: fmt,
+            audio_rate: rate,
+            language: lang.to_string(),
+            dynamic_range: 0,
+            color_space: 0,
+            secondary: false,
+        }
+    }
+
+    fn pg_entry(pid: u16, lang: &str) -> StreamEntry {
+        StreamEntry {
+            stream_type: 3,
+            pid,
+            coding_type: 0x90,
+            video_format: 0,
+            video_rate: 0,
+            audio_format: 0,
+            audio_rate: 0,
+            language: lang.to_string(),
+            dynamic_range: 0,
+            color_space: 0,
+            secondary: false,
+        }
+    }
+
+    fn playlist_with(streams: Vec<StreamEntry>) -> Playlist {
+        Playlist {
+            version: "0200".to_string(),
+            play_items: Vec::new(),
+            streams,
+            marks: Vec::new(),
+        }
+    }
+
+    /// Drive the same conversion logic that `parse()` runs on real
+    /// disc data, but starting from already-parsed Playlists so we
+    /// don't have to synthesize valid MPLS bytes.
+    fn labels_from_playlists(playlists: &[Playlist]) -> Vec<StreamLabel> {
+        let mut labels: Vec<StreamLabel> = Vec::new();
+        let mut seen: Vec<(u8, String, String, u16)> = Vec::new();
+
+        for playlist in playlists {
+            let mut audio_idx: u16 = 0;
+            let mut sub_idx: u16 = 0;
+
+            for entry in &playlist.streams {
+                let label_type = match entry.stream_type {
+                    2 | 5 => StreamLabelType::Audio,
+                    3 => StreamLabelType::Subtitle,
+                    _ => continue,
+                };
+                let stream_number = match label_type {
+                    StreamLabelType::Audio => {
+                        audio_idx += 1;
+                        audio_idx
+                    }
+                    StreamLabelType::Subtitle => {
+                        sub_idx += 1;
+                        sub_idx
+                    }
+                };
+                let language = normalize_language(&entry.language);
+                let name = language_display_name(&language);
+                let codec_hint = build_codec_hint(label_type, entry);
+                let key = (
+                    type_tag(label_type),
+                    language.clone(),
+                    codec_hint.clone(),
+                    entry.pid,
+                );
+                if seen.contains(&key) {
+                    continue;
+                }
+                seen.push(key);
+                labels.push(StreamLabel {
+                    stream_number,
+                    stream_type: label_type,
+                    language,
+                    name,
+                    purpose: LabelPurpose::Normal,
+                    qualifier: LabelQualifier::None,
+                    codec_hint,
+                    variant: String::new(),
+                });
+            }
+        }
+        labels
+    }
+
+    #[test]
+    fn mpls_audio_streams_become_labels() {
+        // Two audio streams: English TrueHD 7.1 48k, French AC-3 5.1 48k.
+        let pl = playlist_with(vec![
+            audio_entry(0x1100, 0x83, 12, 1, "eng"),
+            audio_entry(0x1101, 0x81, 6, 1, "fra"),
+        ]);
+        let labels = labels_from_playlists(&[pl]);
+        assert_eq!(labels.len(), 2);
+
+        // English TrueHD 7.1
+        let a = &labels[0];
+        assert_eq!(a.stream_type, StreamLabelType::Audio);
+        assert_eq!(a.stream_number, 1);
+        assert_eq!(a.language, "eng");
+        assert_eq!(a.name, "English");
+        assert_eq!(a.codec_hint, "TrueHD 7.1");
+        assert_eq!(a.purpose, LabelPurpose::Normal);
+        assert_eq!(a.qualifier, LabelQualifier::None);
+        assert_eq!(a.variant, "");
+
+        // French AC-3 5.1
+        let b = &labels[1];
+        assert_eq!(b.stream_type, StreamLabelType::Audio);
+        assert_eq!(b.stream_number, 2);
+        assert_eq!(b.language, "fra");
+        assert_eq!(b.name, "French");
+        assert_eq!(b.codec_hint, "AC-3 5.1");
+    }
+
+    #[test]
+    fn mpls_pg_streams_become_subtitle_labels() {
+        let pl = playlist_with(vec![
+            pg_entry(0x1200, "eng"),
+            pg_entry(0x1201, "spa"),
+            pg_entry(0x1202, "fra"),
+        ]);
+        let labels = labels_from_playlists(&[pl]);
+        assert_eq!(labels.len(), 3);
+        for label in &labels {
+            assert_eq!(label.stream_type, StreamLabelType::Subtitle);
+            assert_eq!(label.codec_hint, "PG");
+        }
+        assert_eq!(labels[0].stream_number, 1);
+        assert_eq!(labels[0].language, "eng");
+        assert_eq!(labels[0].name, "English");
+        assert_eq!(labels[1].stream_number, 2);
+        assert_eq!(labels[1].language, "spa");
+        assert_eq!(labels[1].name, "Spanish");
+        assert_eq!(labels[2].stream_number, 3);
+        assert_eq!(labels[2].language, "fra");
+    }
+
+    #[test]
+    fn dedup_streams_across_playlists() {
+        // Two playlists, same English TrueHD 7.1 PID 0x1100 in both.
+        // Expect one Audio label, not two.
+        let pl1 = playlist_with(vec![
+            audio_entry(0x1100, 0x83, 12, 1, "eng"),
+            audio_entry(0x1101, 0x81, 6, 1, "fra"),
+        ]);
+        let pl2 = playlist_with(vec![
+            audio_entry(0x1100, 0x83, 12, 1, "eng"), // duplicate
+            audio_entry(0x1102, 0x82, 6, 1, "deu"),  // new
+        ]);
+        let labels = labels_from_playlists(&[pl1, pl2]);
+        // Expected: eng@0x1100, fra@0x1101, deu@0x1102 — three uniques.
+        assert_eq!(labels.len(), 3);
+        // PID isn't stored on StreamLabel, so assert on the surviving
+        // language set instead.
+        let mut langs: Vec<String> = labels.iter().map(|l| l.language.clone()).collect();
+        langs.sort();
+        assert_eq!(langs, vec!["deu", "eng", "fra"]);
+    }
+
+    #[test]
+    fn coding_type_to_codec_hint_table() {
+        // Spot-check every entry in the spec table. Audio entries
+        // come back bare (no channels/rate set) so codec_hint is the
+        // codec name alone.
+        let cases: &[(u8, &str)] = &[
+            (0x02, "MPEG-2"),
+            (0x1B, "H.264"),
+            (0x24, "HEVC"),
+            (0x80, "LPCM"),
+            (0x81, "AC-3"),
+            (0x82, "DTS"),
+            (0x83, "TrueHD"),
+            (0x84, "AC-3+"),
+            (0x85, "DTS-HD"),
+            (0x86, "DTS-HD MA"),
+            (0x90, "PG"),
+            (0x91, "IG"),
+            (0xA1, "AC-3+ Secondary"),
+            (0xA2, "DTS-HD Secondary"),
+        ];
+        for (ct, expected) in cases {
+            assert_eq!(
+                codec_name(*ct),
+                *expected,
+                "coding_type 0x{:02X} should map to {}",
+                ct,
+                expected
+            );
+        }
+        // Unknown bytes return empty.
+        assert_eq!(codec_name(0x00), "");
+        assert_eq!(codec_name(0xFF), "");
+    }
+
+    #[test]
+    fn audio_format_appends_channel_layout() {
+        let mono = audio_entry(1, 0x83, 1, 1, "eng");
+        let stereo = audio_entry(2, 0x83, 3, 1, "eng");
+        let surround_51 = audio_entry(3, 0x83, 6, 1, "eng");
+        let surround_71 = audio_entry(4, 0x83, 12, 1, "eng");
+        let unknown = audio_entry(5, 0x83, 0, 1, "eng");
+        assert_eq!(
+            build_codec_hint(StreamLabelType::Audio, &mono),
+            "TrueHD mono"
+        );
+        assert_eq!(
+            build_codec_hint(StreamLabelType::Audio, &stereo),
+            "TrueHD 2.0"
+        );
+        assert_eq!(
+            build_codec_hint(StreamLabelType::Audio, &surround_51),
+            "TrueHD 5.1"
+        );
+        assert_eq!(
+            build_codec_hint(StreamLabelType::Audio, &surround_71),
+            "TrueHD 7.1"
+        );
+        assert_eq!(build_codec_hint(StreamLabelType::Audio, &unknown), "TrueHD");
+    }
+
+    #[test]
+    fn audio_rate_only_shows_above_48k() {
+        // 48 kHz (rate=1) is the universal default → not surfaced.
+        let r48 = audio_entry(1, 0x83, 6, 1, "eng");
+        // 96 kHz (rate=4) → surfaced.
+        let r96 = audio_entry(2, 0x83, 6, 4, "eng");
+        // 192 kHz (rate=5) → surfaced.
+        let r192 = audio_entry(3, 0x83, 6, 5, "eng");
+        assert_eq!(build_codec_hint(StreamLabelType::Audio, &r48), "TrueHD 5.1");
+        assert_eq!(
+            build_codec_hint(StreamLabelType::Audio, &r96),
+            "TrueHD 5.1 96kHz"
+        );
+        assert_eq!(
+            build_codec_hint(StreamLabelType::Audio, &r192),
+            "TrueHD 5.1 192kHz"
+        );
+    }
+
+    #[test]
+    fn unknown_iso_code_passes_through_without_display_name() {
+        // Made-up code: keep the raw lowercase code as `language`,
+        // but `name` is empty because we don't know it.
+        let pl = playlist_with(vec![audio_entry(0x1100, 0x83, 6, 1, "xyz")]);
+        let labels = labels_from_playlists(&[pl]);
+        assert_eq!(labels.len(), 1);
+        assert_eq!(labels[0].language, "xyz");
+        assert_eq!(labels[0].name, "");
+    }
+
+    #[test]
+    fn ig_and_dv_streams_are_skipped() {
+        // stream_type 4 = IG, 7 = DV EL — both must not surface.
+        let mut ig = pg_entry(0x1400, "eng");
+        ig.stream_type = 4;
+        let mut dv = audio_entry(0x1011, 0x24, 0, 0, "");
+        dv.stream_type = 7;
+        let pl = playlist_with(vec![ig, dv]);
+        let labels = labels_from_playlists(&[pl]);
+        assert!(labels.is_empty());
+    }
+
+    #[test]
+    fn secondary_audio_becomes_audio_label() {
+        // stream_type 5 = secondary audio. The conversion should
+        // still produce an Audio label (the registry's apply path
+        // can ignore secondary if it wants — this module just
+        // surfaces what's there).
+        let mut sec = audio_entry(0x1A00, 0x83, 3, 1, "eng");
+        sec.stream_type = 5;
+        sec.secondary = true;
+        let pl = playlist_with(vec![sec]);
+        let labels = labels_from_playlists(&[pl]);
+        assert_eq!(labels.len(), 1);
+        assert_eq!(labels[0].stream_type, StreamLabelType::Audio);
+        assert_eq!(labels[0].codec_hint, "TrueHD 2.0");
+    }
+}
@@ -12,15 +12,15 @@
 //!   sub_com1_idx="23,24,25" />
 //! ```

-use super::{LabelPurpose, LabelQualifier, StreamLabel, StreamLabelType};
-use crate::sector::SectorReader;
+use super::{LabelPurpose, LabelQualifier, ParseResult, StreamLabel, StreamLabelType, xml};
+use crate::sector::SectorSource;
 use crate::udf::UdfFs;

 pub fn detect(udf: &UdfFs) -> bool {
    super::jar_file_exists(udf, "playlists.xml")
 }

-pub fn parse(reader: &mut dyn SectorReader, udf: &UdfFs) -> Option<Vec<StreamLabel>> {
+pub fn parse(reader: &mut dyn SectorSource, udf: &UdfFs) -> Option<ParseResult> {
    let data = super::read_jar_file(reader, udf, "playlists.xml")?;
    let text = std::str::from_utf8(&data).ok()?;

@@ -30,8 +30,8 @@ pub fn parse(reader: &mut dyn SectorReader, udf: &UdfFs) -> Option<Vec<StreamLab
    let mut labels = Vec::new();

    // Parse audio streams
-    if let Some(aud) = extract_attr(&feature, "aud") {
-        let com_idx = extract_attr(&feature, "aud_com1_idx").and_then(|s| s.parse::<usize>().ok());
+    if let Some(aud) = xml::attr(&feature, "aud") {
+        let com_idx = xml::attr(&feature, "aud_com1_idx").and_then(|s| s.parse::<usize>().ok());

        for (i, lang) in aud.split(',').enumerate() {
            let lang = lang.trim();
@@ -57,12 +57,12 @@ pub fn parse(reader: &mut dyn SectorReader, udf: &UdfFs) -> Option<Vec<StreamLab
    }

    // Parse subtitle streams
-    if let Some(sub) = extract_attr(&feature, "sub") {
-        let forced: Vec<bool> = extract_attr(&feature, "forced_sub")
+    if let Some(sub) = xml::attr(&feature, "sub") {
+        let forced: Vec<bool> = xml::attr(&feature, "forced_sub")
            .map(|s| s.split(',').map(|f| f.trim() == "1").collect())
            .unwrap_or_default();

-        let com_indices: Vec<usize> = extract_attr(&feature, "sub_com1_idx")
+        let com_indices: Vec<usize> = xml::attr(&feature, "sub_com1_idx")
            .map(|s| s.split(',').filter_map(|i| i.trim().parse().ok()).collect())
            .unwrap_or_default();

@@ -100,32 +100,29 @@ pub fn parse(reader: &mut dyn SectorReader, udf: &UdfFs) -> Option<Vec<StreamLab
    if labels.is_empty() {
        return None;
    }
-    Some(labels)
+    // High confidence: paramount's playlists.xml is fully structured
+    // and we extract every documented field.
+    Some(ParseResult::high(labels))
 }

 /// Find the feature playlist element (the one with the most audio tracks).
-fn find_feature_playlist(xml: &str) -> Option<String> {
+fn find_feature_playlist(text: &str) -> Option<String> {
    let mut best: Option<String> = None;
    let mut best_aud_count = 0;
+    let mut from = 0;

-    let mut pos = 0;
-    while let Some(start) = xml[pos..].find("<playlist ") {
-        let abs_start = pos + start;
-        let end = match xml[abs_start..].find("/>") {
-            Some(p) => abs_start + p + 2,
-            None => break,
-        };
-        let element = &xml[abs_start..end];
+    while let Some((start, end)) = xml::find_element(text, "playlist", from) {
+        let element = &text[start..end];

-        // Prefer name="Feature" explicitly
-        if let Some(name) = extract_attr(element, "name") {
+        // Prefer name="Feature" explicitly.
+        if let Some(name) = xml::attr(element, "name") {
            if name.eq_ignore_ascii_case("Feature") {
                return Some(element.to_string());
            }
        }

-        // Otherwise pick the one with the most audio streams
-        if let Some(aud) = extract_attr(element, "aud") {
+        // Otherwise pick the one with the most audio streams.
+        if let Some(aud) = xml::attr(element, "aud") {
            let count = aud.split(',').count();
            if count > best_aud_count {
                best_aud_count = count;
@@ -133,15 +130,7 @@ fn find_feature_playlist(xml: &str) -> Option<String> {
            }
        }

-        pos = end;
+        from = end;
    }
    best
 }
-
-/// Extract an XML attribute value from an element string.
-fn extract_attr(element: &str, name: &str) -> Option<String> {
-    let needle = format!("{name}=\"");
-    let start = element.find(&needle)? + needle.len();
-    let end = element[start..].find('"')? + start;
-    Some(element[start..end].to_string())
-}
@@ -5,9 +5,13 @@
 //!
 //! Token format: `{lang}_{codec?}_{purpose?}_{region?}_`

-use super::{LabelPurpose, LabelQualifier, StreamLabel, StreamLabelType, vocab};
-use crate::sector::SectorReader;
+use super::{
+    Confidence, LabelPurpose, LabelQualifier, ParseResult, StreamLabel, StreamLabelType, text,
+    vocab,
+};
+use crate::sector::SectorSource;
 use crate::udf::UdfFs;
+use std::sync::atomic::{AtomicBool, Ordering};

 /// Known audio codec tokens
 const AUDIO_CODECS: &[&str] = &["MLP", "AC3", "DTS", "DDL", "WAV", "AC"];
@@ -20,9 +24,18 @@ pub fn detect(udf: &UdfFs) -> bool {
    super::jar_file_exists(udf, "bluray_project.bin")
 }

-pub fn parse(reader: &mut dyn SectorReader, udf: &UdfFs) -> Option<Vec<StreamLabel>> {
+pub fn parse(reader: &mut dyn SectorSource, udf: &UdfFs) -> Option<ParseResult> {
    let data = super::read_jar_file(reader, udf, "bluray_project.bin")?;
-    let strings = extract_strings(&data);
+    // min_len=4 matches the prior local extract_strings impl. The token
+    // grammar is `{lang3}_{codec?}_{purpose?}_{region?}_` so the
+    // shortest meaningful run is 4 chars (lang + underscore).
+    let strings = text::extract_ascii_strings(&data, 4);
+
+    // Tracked across all parse_token calls in this run: did any stream
+    // hit an unrecognized token component (skip-unknown path)? If yes
+    // we downgrade confidence to Medium — the labels are still valid
+    // but the corpus surfaced something we don't catalogue.
+    let saw_unknown = AtomicBool::new(false);

    let mut labels = Vec::new();
    let mut in_feature = false;
@@ -50,7 +63,7 @@ pub fn parse(reader: &mut dyn SectorReader, udf: &UdfFs) -> Option<Vec<StreamLab
            continue;
        }

-        if let Some(label) = parse_token(s) {
+        if let Some(label) = parse_token_inner(s, Some(&saw_unknown)) {
            match label.stream_type {
                StreamLabelType::Audio => {
                    audio_num += 1;
@@ -73,10 +86,15 @@ pub fn parse(reader: &mut dyn SectorReader, udf: &UdfFs) -> Option<Vec<StreamLab
    if labels.is_empty() {
        return None;
    }
-    Some(labels)
+    let confidence = if saw_unknown.load(Ordering::Relaxed) {
+        Confidence::Medium
+    } else {
+        Confidence::High
+    };
+    Some(ParseResult { labels, confidence })
 }

-fn parse_token(s: &str) -> Option<StreamLabel> {
+fn parse_token_inner(s: &str, saw_unknown: Option<&AtomicBool>) -> Option<StreamLabel> {
    let clean = s.trim().trim_start_matches('\t').trim_end_matches('_');
    let parts: Vec<&str> = clean.split('_').collect();
    if parts.len() < 2 {
@@ -127,7 +145,18 @@ fn parse_token(s: &str) -> Option<StreamLabel> {
        } else if part.starts_with("PGStream") {
            is_subtitle = true;
        } else {
-            return None;
+            // Unknown token component — skip this single part rather
+            // than discarding the entire stream record. Pre-refactor
+            // behavior was `return None` here, which silently dropped
+            // any stream containing a single uncatalogued token (e.g.
+            // a new codec ID or framework variant). Better to surface
+            // what we know than discard a whole stream over one part,
+            // but flag the parse as Medium-confidence so callers know
+            // some data was elided.
+            tracing::debug!(part = %part, "pixelogic: unrecognized token component, skipping");
+            if let Some(flag) = saw_unknown {
+                flag.store(true, Ordering::Relaxed);
+            }
        }
    }

@@ -153,22 +182,72 @@ fn parse_token(s: &str) -> Option<StreamLabel> {
    })
 }

-fn extract_strings(data: &[u8]) -> Vec<String> {
-    let mut strings = Vec::new();
-    let mut current = String::new();
+// extract_strings removed — replaced by super::text::extract_ascii_strings(data, 4).

-    for &b in data {
-        if (0x20..0x7f).contains(&b) {
-            current.push(b as char);
-        } else {
-            if current.len() > 3 {
-                strings.push(current.clone());
-            }
-            current.clear();
-        }
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_token_basic_audio() {
+        let l = parse_token_inner("eng_MLP_", None).unwrap();
+        assert_eq!(l.stream_type, StreamLabelType::Audio);
+        assert_eq!(l.language, "eng");
+        assert_eq!(l.codec_hint, "TrueHD");
+        assert_eq!(l.purpose, LabelPurpose::Normal);
    }
-    if current.len() > 3 {
-        strings.push(current);
+
+    #[test]
+    fn parse_token_basic_subtitle_sdh() {
+        let l = parse_token_inner("eng_SDH_", None).unwrap();
+        assert_eq!(l.stream_type, StreamLabelType::Subtitle);
+        assert_eq!(l.language, "eng");
+        assert_eq!(l.qualifier, LabelQualifier::Sdh);
+    }
+
+    #[test]
+    fn parse_token_commentary() {
+        let l = parse_token_inner("eng_MLP_ACOM_", None).unwrap();
+        assert_eq!(l.stream_type, StreamLabelType::Audio);
+        assert_eq!(l.purpose, LabelPurpose::Commentary);
+    }
+
+    #[test]
+    fn parse_token_descriptive() {
+        let l = parse_token_inner("eng_AC3_ADES_", None).unwrap();
+        assert_eq!(l.purpose, LabelPurpose::Descriptive);
+    }
+
+    #[test]
+    fn parse_token_with_region() {
+        let l = parse_token_inner("eng_MLP_US_", None).unwrap();
+        assert_eq!(l.language, "eng");
+        assert_eq!(l.variant, "US");
+    }
+
+    #[test]
+    fn parse_token_unknown_component_does_not_kill_stream() {
+        // Regression: pre-refactor, an unrecognized token part returned
+        // None for the whole stream, silently dropping it. New
+        // behavior: skip the unknown part, surface what we know.
+        let l = parse_token_inner("eng_MLP_FUTUREFLAG_FOR_", None).unwrap();
+        assert_eq!(l.stream_type, StreamLabelType::Audio);
+        assert_eq!(l.language, "eng");
+        assert_eq!(l.codec_hint, "TrueHD");
+        assert_eq!(l.qualifier, LabelQualifier::Forced);
+    }
+
+    #[test]
+    fn parse_token_no_audio_or_subtitle_signal_returns_none() {
+        // A token that has only a language and an unknown part with
+        // no audio/subtitle classifier should still return None —
+        // there's no way to file it as a stream.
+        assert!(parse_token_inner("eng_UNKNOWN_", None).is_none());
+    }
+
+    #[test]
+    fn parse_token_rejects_non_lang_prefix() {
+        assert!(parse_token_inner("XX_MLP_", None).is_none());
+        assert!(parse_token_inner("ENG_MLP_", None).is_none()); // uppercase not accepted as ISO 639-2
    }
-    strings
 }
@@ -0,0 +1,89 @@
+//! Text-extraction helpers used by parsers that scan binary blobs for
+//! embedded label strings.
+//!
+//! Promoted from two near-duplicate implementations:
+//! - `pixelogic::extract_strings` (`bluray_project.bin`, min_len=4)
+//! - `dbp::extract_printable` (`.class` files in jars, min_len=5)
+//!
+//! Single implementation, threshold passed in. Callers that have a
+//! more structured parse path (e.g. `class_reader` for .class) should
+//! prefer that — this helper is for genuinely unstructured input.
+
+/// Walk `data`, emit every maximal run of printable-ASCII bytes
+/// (`0x20..=0x7E`) whose length is at least `min_len`.
+///
+/// Non-printable bytes (including `\t`, `\n`, NUL) terminate the
+/// current run. Output strings are guaranteed valid UTF-8 (they're
+/// pure 7-bit ASCII). Strings shorter than `min_len` are dropped.
+pub fn extract_ascii_strings(data: &[u8], min_len: usize) -> Vec<String> {
+    let mut out = Vec::new();
+    let mut current = String::new();
+    for &b in data {
+        if (0x20..=0x7E).contains(&b) {
+            current.push(b as char);
+        } else if current.len() >= min_len {
+            out.push(std::mem::take(&mut current));
+        } else {
+            current.clear();
+        }
+    }
+    if current.len() >= min_len {
+        out.push(current);
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn extracts_simple_runs() {
+        let got = extract_ascii_strings(b"hello\0world\0", 3);
+        assert_eq!(got, vec!["hello", "world"]);
+    }
+
+    #[test]
+    fn applies_minimum_length() {
+        let got = extract_ascii_strings(b"hi\0ok\0longer\0", 5);
+        assert_eq!(got, vec!["longer"]);
+    }
+
+    #[test]
+    fn treats_tab_and_newline_as_separators() {
+        // \t (0x09) and \n (0x0A) are below 0x20, so they break runs.
+        let got = extract_ascii_strings(b"alpha\tbeta\ngamma", 3);
+        assert_eq!(got, vec!["alpha", "beta", "gamma"]);
+    }
+
+    #[test]
+    fn handles_trailing_run_without_terminator() {
+        // Run at the very end of the buffer should still be emitted.
+        let got = extract_ascii_strings(b"prefix\0tail", 3);
+        assert_eq!(got, vec!["prefix", "tail"]);
+    }
+
+    #[test]
+    fn rejects_high_bit_bytes() {
+        // 0x80+ is non-printable per this helper's definition.
+        let mut buf = b"good".to_vec();
+        buf.push(0xC3);
+        buf.push(0xA9);
+        buf.extend_from_slice(b"more");
+        let got = extract_ascii_strings(&buf, 3);
+        assert_eq!(got, vec!["good", "more"]);
+    }
+
+    #[test]
+    fn empty_input_returns_empty() {
+        let got = extract_ascii_strings(&[], 1);
+        assert!(got.is_empty());
+    }
+
+    #[test]
+    fn min_len_zero_emits_singletons() {
+        // Pathological but well-defined.
+        let got = extract_ascii_strings(b"a\0b", 0);
+        assert_eq!(got, vec!["a", "b"]);
+    }
+}
@@ -1,19 +1,40 @@
-//! Shared label vocabulary — values we are 100% confident about.
+//! Shared label vocabulary — canonical mappings used by ≥1 label parser.
 //!
 //! Labels come from BD-J authoring tool files (bluray_project.bin,
-//! playlists.xml, menu_base.prop, etc.) — NOT from BD spec fields.
-//! This is NOT for MPLS/CLPI/STN data. Those follow the BD spec directly.
+//! playlists.xml, menu_base.prop, .class string pools, etc.) — NOT
+//! from BD spec fields. This module is the central, regression-tested
+//! source of truth for:
 //!
-//! Rules:
-//! - Only map values we are 100% certain about (published codec names).
-//! - Unknown codes (csp, eda, cf, etc.) pass through raw from disc.
-//! - The app/CLI handles display text, not the lib.
+//! - Codec brand name aliases (`MLP` → `TrueHD`).
+//! - English / multi-word language name → ISO 639-2 code.
+//! - English text → [`LabelPurpose`] (Commentary / Descriptive / etc.).
+//! - English text → [`LabelQualifier`] (SDH / Forced / Descriptive Service).
+//!
+//! Rules of engagement (carried over from
+//! `(internal)/memory/feedback_label_data_rules.md`):
+//!
+//! 1. Only map values we are 100% certain about — published codec
+//!    names, well-known ISO 639-2 mappings, vendor-documented purpose
+//!    keywords.
+//! 2. Unknown codes / unrecognized phrases pass through raw or return
+//!    `None`. We never guess.
+//! 3. Matching is case-insensitive and word-boundary-aware where
+//!    relevant (so "Commenter" doesn't match "commentary"). Anchoring
+//!    on whole tokens is the responsibility of this module — callers
+//!    pass raw text, we handle it.
+//!
+//! This module is NOT for BD spec STN codec IDs; those decode in
+//! `mpls.rs` separately.
+
+use super::{LabelPurpose, LabelQualifier};
+
+// ── Codec aliases ────────────────────────────────────────────────────────────

 /// Map a codec identifier found in label data to its display name.
 ///
 /// These are well-known codec identifiers used across multiple BD-J
-/// authoring tools. NOT BD spec STN codec IDs — those are decoded
-/// separately in mpls.rs.
+/// authoring tools. Unknown codes pass through unchanged so callers
+/// can still surface vendor-specific tokens we haven't catalogued.
 pub fn codec(code: &str) -> &str {
    match code {
        "MLP" => "TrueHD",
@@ -25,3 +46,405 @@ pub fn codec(code: &str) -> &str {
        _ => code,
    }
 }
+
+// ── Language: English / multi-word names → ISO 639-2 ─────────────────────────
+
+/// Result of [`lang`] — ISO code + human-readable regional variant.
+///
+/// `code` is ISO 639-2 (always 3 lowercase letters).
+/// `variant` is the regional dialect as a human-readable English word
+/// (`"Brazilian"`, `"Castilian"`, `"Canadian"`, `"Simplified"`, ...)
+/// or `""` when the input names just a bare language without
+/// dialect ("Spanish" → variant=""). The variant matches the
+/// convention pixelogic / ctrm / criterion already use for their
+/// `StreamLabel::variant` field: a short display token the UI can
+/// surface verbatim.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct LangInfo {
+    pub code: &'static str,
+    pub variant: &'static str,
+}
+
+/// Map a free-form language label fragment to an ISO 639-2 code AND
+/// (where applicable) its regional variant.
+///
+/// Handles both bare English names ("English", "Spanish") and the
+/// multi-word vendor variants we've seen in the corpus ("Brazilian
+/// Portuguese", "Castilian Spanish", "Canadian French"). Match is
+/// case-insensitive; longer compound phrases win over their bare
+/// counterparts (so "Brazilian Portuguese" returns
+/// `LangInfo { code: "por", variant: "Brazilian" }`, not consumed by
+/// the bare "Portuguese" entry).
+///
+/// Bare-name matches return `variant: ""`.
+///
+/// Returns `None` for unrecognized input — callers decide whether to
+/// fall back to MPLS spec codes, pass through raw, or drop the stream.
+/// Never guesses.
+///
+/// Why the variant: the prior `lang() -> Option<&str>` shape silently
+/// dropped regional dialect info. "Brazilian Portuguese 5.1" became
+/// `language="por", variant=""` — UI displayed plain "Portuguese"
+/// even though the disc had explicitly labeled this stream Brazilian.
+/// Capturing the variant here parallels how pixelogic and ctrm
+/// populate `StreamLabel::variant` from their own region tables.
+pub fn lang(text: &str) -> Option<LangInfo> {
+    let lower = text.to_lowercase();
+    // Multi-word compounds first — longest-match wins.
+    for (needle, code, variant) in COMPOUND_LANGS {
+        if lower.contains(needle) {
+            return Some(LangInfo { code, variant });
+        }
+    }
+    // Bare names: word-boundary match (avoid "english" inside "englishman"
+    // or any other accidental substring).
+    for (needle, code) in BARE_LANGS {
+        if has_word(&lower, needle) {
+            return Some(LangInfo { code, variant: "" });
+        }
+    }
+    None
+}
+
+const COMPOUND_LANGS: &[(&str, &str, &str)] = &[
+    ("brazilian portuguese", "por", "Brazilian"),
+    ("euro portuguese", "por", "European"),
+    ("european portuguese", "por", "European"),
+    ("castilian spanish", "spa", "Castilian"),
+    ("latin american spanish", "spa", "Latin American"),
+    ("latin spanish", "spa", "Latin American"),
+    ("canadian french", "fra", "Canadian"),
+    ("parisian french", "fra", "Parisian"),
+    ("australian english", "eng", "Australian"),
+    ("austrailian english", "eng", "Australian"), // disc-corpus typo, keep matching
+    ("british english", "eng", "British"),
+    ("simplified chinese", "zho", "Simplified"),
+    ("traditional chinese", "zho", "Traditional"),
+    ("mandarin chinese", "zho", "Mandarin"),
+    ("cantonese chinese", "zho", "Cantonese"),
+];
+
+const BARE_LANGS: &[(&str, &str)] = &[
+    ("english", "eng"),
+    ("spanish", "spa"),
+    ("french", "fra"),
+    ("german", "deu"),
+    ("italian", "ita"),
+    ("japanese", "jpn"),
+    ("chinese", "zho"),
+    ("mandarin", "zho"),
+    ("cantonese", "zho"),
+    ("portuguese", "por"),
+    ("polish", "pol"),
+    ("czech", "ces"),
+    ("hungarian", "hun"),
+    ("dutch", "nld"),
+    ("korean", "kor"),
+    ("arabic", "ara"),
+    ("hindi", "hin"),
+    ("turkish", "tur"),
+    ("thai", "tha"),
+    ("swedish", "swe"),
+    ("norwegian", "nor"),
+    ("danish", "dan"),
+    ("finnish", "fin"),
+    ("hebrew", "heb"),
+    ("russian", "rus"),
+    ("greek", "ell"),
+    ("vietnamese", "vie"),
+    ("indonesian", "ind"),
+    ("malay", "msa"),
+    ("ukrainian", "ukr"),
+    ("romanian", "ron"),
+    ("bulgarian", "bul"),
+    ("croatian", "hrv"),
+    ("serbian", "srp"),
+    ("slovak", "slk"),
+    ("slovenian", "slv"),
+    ("estonian", "est"),
+    ("latvian", "lav"),
+    ("lithuanian", "lit"),
+    ("icelandic", "isl"),
+    ("basque", "eus"),
+    ("catalan", "cat"),
+    ("galician", "glg"),
+];
+
+// ── Purpose ──────────────────────────────────────────────────────────────────
+
+/// Classify a free-form English label string into a [`LabelPurpose`].
+///
+/// Recognized keywords (case-insensitive, word-boundary matched):
+/// - "commentary", "director's commentary" → `Commentary`
+/// - "descriptive", "description", "audio description", "described" → `Descriptive`
+/// - "score", "music only" → `Score`
+/// - "ime" (alternate music for closing themes etc.) → `Ime`
+/// - anything else → `Normal`
+///
+/// Word-boundary matching means "Commentary track" matches but
+/// "Commenter Pro audio" does not.
+pub fn purpose(text: &str) -> LabelPurpose {
+    let lower = text.to_lowercase();
+    // Multi-word compounds first — they're more specific.
+    if lower.contains("audio description") || lower.contains("descriptive service") {
+        return LabelPurpose::Descriptive;
+    }
+    if lower.contains("music only") {
+        return LabelPurpose::Score;
+    }
+    if has_word(&lower, "commentary") {
+        return LabelPurpose::Commentary;
+    }
+    if has_word(&lower, "descriptive")
+        || has_word(&lower, "description")
+        || has_word(&lower, "described")
+    {
+        return LabelPurpose::Descriptive;
+    }
+    if has_word(&lower, "score") {
+        return LabelPurpose::Score;
+    }
+    if has_word(&lower, "ime") {
+        return LabelPurpose::Ime;
+    }
+    LabelPurpose::Normal
+}
+
+// ── Qualifier ────────────────────────────────────────────────────────────────
+
+/// Classify a free-form English label string into a [`LabelQualifier`].
+///
+/// Recognized keywords (case-insensitive, word-boundary matched):
+/// - "sdh", "captions" → `Sdh`
+/// - "forced", "forced narrative" → `Forced`
+/// - "rnib", "descriptive service" → `DescriptiveService`
+/// - anything else → `None`
+///
+/// SDH (Subtitles for the Deaf and Hard of hearing) wins over Forced
+/// when both keywords are present, because an SDH track is its own
+/// stream regardless of whether the player flags it as "forced".
+pub fn qualifier(text: &str) -> LabelQualifier {
+    let lower = text.to_lowercase();
+    if has_word(&lower, "sdh") || has_word(&lower, "captions") {
+        return LabelQualifier::Sdh;
+    }
+    if lower.contains("descriptive service") || has_word(&lower, "rnib") {
+        return LabelQualifier::DescriptiveService;
+    }
+    if has_word(&lower, "forced") {
+        return LabelQualifier::Forced;
+    }
+    LabelQualifier::None
+}
+
+// ── Internal: word-boundary matching ────────────────────────────────────────
+
+/// True if `needle` appears in `haystack` surrounded by non-alphanumeric
+/// boundaries (or string ends). `haystack` is assumed lowercase already.
+///
+/// This is the load-bearing primitive for `lang` / `purpose` /
+/// `qualifier`: bare-token matchers MUST use it, otherwise we match
+/// "english" inside "englishman" and "sdh" inside "lambdash". The
+/// existing parsers used `.contains()` and got lucky on the corpus;
+/// vocab guarantees the boundary.
+fn has_word(haystack: &str, needle: &str) -> bool {
+    if needle.is_empty() {
+        return false;
+    }
+    let bytes = haystack.as_bytes();
+    let nb = needle.as_bytes();
+    let mut i = 0;
+    while i + nb.len() <= bytes.len() {
+        if &bytes[i..i + nb.len()] == nb {
+            let before = if i == 0 { None } else { Some(bytes[i - 1]) };
+            let after = bytes.get(i + nb.len()).copied();
+            let bound = |c: Option<u8>| match c {
+                None => true,
+                Some(b) => !b.is_ascii_alphanumeric(),
+            };
+            if bound(before) && bound(after) {
+                return true;
+            }
+        }
+        i += 1;
+    }
+    false
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn codec_known_aliases() {
+        assert_eq!(codec("MLP"), "TrueHD");
+        assert_eq!(codec("AC3"), "Dolby Digital");
+        assert_eq!(codec("AC"), "Dolby Digital");
+        assert_eq!(codec("DDL"), "Dolby Digital Plus");
+        assert_eq!(codec("atmos"), "Dolby Atmos");
+    }
+
+    #[test]
+    fn codec_unknown_passes_through() {
+        assert_eq!(codec("FX9"), "FX9");
+        assert_eq!(codec(""), "");
+    }
+
+    fn li(code: &'static str, variant: &'static str) -> LangInfo {
+        LangInfo { code, variant }
+    }
+
+    #[test]
+    fn lang_bare_names_have_empty_variant() {
+        assert_eq!(lang("English"), Some(li("eng", "")));
+        assert_eq!(lang("english"), Some(li("eng", "")));
+        assert_eq!(lang("Spanish 5.1 Dolby Digital"), Some(li("spa", "")));
+        assert_eq!(lang("japanese"), Some(li("jpn", "")));
+        assert_eq!(lang("Italian"), Some(li("ita", "")));
+    }
+
+    #[test]
+    fn lang_compounds_carry_variant() {
+        assert_eq!(
+            lang("Brazilian Portuguese 5.1"),
+            Some(li("por", "Brazilian"))
+        );
+        assert_eq!(lang("Castilian Spanish"), Some(li("spa", "Castilian")));
+        assert_eq!(
+            lang("Canadian French Dolby Digital"),
+            Some(li("fra", "Canadian"))
+        );
+        assert_eq!(
+            lang("Latin American Spanish"),
+            Some(li("spa", "Latin American"))
+        );
+        assert_eq!(lang("Simplified Chinese"), Some(li("zho", "Simplified")));
+        assert_eq!(lang("British English"), Some(li("eng", "British")));
+    }
+
+    #[test]
+    fn lang_compounds_win_over_bare() {
+        // Brazilian Portuguese must map to (por, Brazilian) via the
+        // compound rule, not be intercepted by bare "portuguese"
+        // (which would yield (por, "") and lose the variant).
+        assert_eq!(lang("Brazilian Portuguese").unwrap().variant, "Brazilian");
+        assert_eq!(lang("Canadian French").unwrap().variant, "Canadian");
+    }
+
+    #[test]
+    fn lang_unknown_returns_none() {
+        assert_eq!(lang("Klingon Dolby Atmos"), None);
+        assert_eq!(lang(""), None);
+        assert_eq!(lang("eng"), None); // 3-letter codes are not English names
+    }
+
+    #[test]
+    fn lang_word_boundary_avoids_substring_false_positive() {
+        // No false positive — "engineering" must NOT match "english".
+        assert_eq!(lang("Audio Engineering Demo"), None);
+    }
+
+    #[test]
+    fn purpose_recognizes_commentary() {
+        assert_eq!(purpose("English Commentary"), LabelPurpose::Commentary);
+        assert_eq!(purpose("Director's Commentary"), LabelPurpose::Commentary);
+    }
+
+    #[test]
+    fn purpose_recognizes_descriptive() {
+        assert_eq!(
+            purpose("English Descriptive Audio"),
+            LabelPurpose::Descriptive
+        );
+        assert_eq!(purpose("Audio Description"), LabelPurpose::Descriptive);
+        assert_eq!(purpose("Described Video"), LabelPurpose::Descriptive);
+    }
+
+    #[test]
+    fn purpose_descriptive_service_routes_to_descriptive() {
+        // "Descriptive Service" is qualifier territory but the purpose
+        // implication is Descriptive — vocab::purpose treats it as such.
+        assert_eq!(
+            purpose("English Descriptive Service"),
+            LabelPurpose::Descriptive
+        );
+    }
+
+    #[test]
+    fn purpose_word_boundary_avoids_commenter_false_positive() {
+        // "Commenter Pro audio" does NOT match "commentary" — the
+        // existing dbp/ctrm hand-rolls would have. Vocab is stricter.
+        assert_eq!(purpose("Commenter Pro audio track"), LabelPurpose::Normal);
+    }
+
+    #[test]
+    fn purpose_recognizes_score() {
+        assert_eq!(purpose("Music Only"), LabelPurpose::Score);
+        assert_eq!(purpose("Isolated Score"), LabelPurpose::Score);
+    }
+
+    #[test]
+    fn purpose_unknown_is_normal() {
+        assert_eq!(purpose("English Dolby Atmos"), LabelPurpose::Normal);
+        assert_eq!(purpose(""), LabelPurpose::Normal);
+    }
+
+    #[test]
+    fn qualifier_recognizes_sdh() {
+        assert_eq!(qualifier("English SDH"), LabelQualifier::Sdh);
+        assert_eq!(qualifier("English Captions"), LabelQualifier::Sdh);
+    }
+
+    #[test]
+    fn qualifier_recognizes_forced() {
+        assert_eq!(qualifier("English Forced"), LabelQualifier::Forced);
+        assert_eq!(qualifier("Forced Narrative"), LabelQualifier::Forced);
+    }
+
+    #[test]
+    fn qualifier_recognizes_descriptive_service() {
+        assert_eq!(
+            qualifier("English RNIB"),
+            LabelQualifier::DescriptiveService
+        );
+        assert_eq!(
+            qualifier("English Descriptive Service"),
+            LabelQualifier::DescriptiveService
+        );
+    }
+
+    #[test]
+    fn qualifier_sdh_wins_over_forced_when_both_present() {
+        // SDH track is its own stream regardless of forced flag.
+        assert_eq!(qualifier("English Forced SDH"), LabelQualifier::Sdh);
+    }
+
+    #[test]
+    fn qualifier_unknown_is_none() {
+        assert_eq!(qualifier("English"), LabelQualifier::None);
+        assert_eq!(qualifier(""), LabelQualifier::None);
+    }
+
+    #[test]
+    fn has_word_basic() {
+        assert!(has_word("english forced", "english"));
+        assert!(has_word("english forced", "forced"));
+        assert!(has_word("english", "english"));
+    }
+
+    #[test]
+    fn has_word_rejects_substring() {
+        assert!(!has_word("engineering", "english"));
+        assert!(!has_word("englishman", "english"));
+        assert!(!has_word("aenglish", "english"));
+    }
+
+    #[test]
+    fn has_word_punctuation_boundary() {
+        // "(SDH)" is a valid boundary — parentheses count as non-alphanum.
+        assert!(has_word("english (sdh)", "sdh"));
+        assert!(has_word("commentary,extra,info", "commentary"));
+    }
+}
@@ -0,0 +1,452 @@
+//! Tolerant XML scraping helpers — promoted from two near-duplicate
+//! hand-rolls in `paramount.rs` (attribute extraction) and `criterion.rs`
+//! (tag-text extraction).
+//!
+//! These are NOT a full XML parser. They handle the subset of XML the
+//! BD-J authoring tools we've seen actually emit: ASCII tag/attr
+//! names, no entity references inside label strings, optional XML
+//! namespaces. Hardening goals over the prior `find("<tag>")` /
+//! `find(r#"name=""#)` matchers:
+//!
+//! 1. **Case-insensitive** tag and attribute names — vendors casing
+//!    is inconsistent across authoring-tool revisions.
+//! 2. **Namespace-aware** — strip an optional `ns:` prefix so
+//!    `<ns:playlist>` and `<playlist>` both match.
+//! 3. **Whitespace-tolerant** — multiple/tab/newline characters
+//!    around `=` between attribute name and value; whitespace inside
+//!    the opening tag.
+//! 4. **Quote-style tolerant** — both `"value"` and `'value'`.
+//! 5. **Self-closing tag handling** — `<tag />` and `<tag/>` both
+//!    work; [`text`] returns `Some("")` for empty content.
+//!
+//! Out of scope (intentionally simple): XML entity decoding
+//! (`&amp;`, `&lt;`, etc.), CDATA sections, comments, processing
+//! instructions, DTD declarations. None of the BD-J authored disc
+//! data we've observed exercises any of those — labels are plain
+//! ASCII/Latin-1 in attribute values.
+
+/// Extract the value of attribute `name` from one XML element
+/// fragment (e.g. `<playlist name="Feature" id="00222" />`).
+///
+/// Returns the raw attribute text (no entity decoding) or `None` if
+/// the attribute isn't present. Empty string for `name=""` is
+/// represented as `Some("")`.
+pub fn attr(element: &str, name: &str) -> Option<String> {
+    let bytes = element.as_bytes();
+    let name_lower = name.to_ascii_lowercase();
+    let name_bytes = name_lower.as_bytes();
+    let mut i = 0;
+    while i + name_bytes.len() < bytes.len() {
+        // Find the next position where `name=` could start. We need
+        // a word boundary before the name (whitespace or `<` or `:`).
+        if i > 0 && is_name_char(bytes[i - 1]) {
+            i += 1;
+            continue;
+        }
+        if !slice_eq_ignore_case(&bytes[i..i + name_bytes.len()], name_bytes) {
+            i += 1;
+            continue;
+        }
+        let after_name = i + name_bytes.len();
+        // The character immediately after the name must not be a
+        // name-continuation (otherwise we matched a prefix like
+        // `lang_id` when looking for `lang`).
+        if after_name < bytes.len() && is_name_char(bytes[after_name]) {
+            i = after_name;
+            continue;
+        }
+        // Walk past whitespace, then `=`, then more whitespace, then
+        // the opening quote.
+        let mut j = after_name;
+        while j < bytes.len() && is_ws(bytes[j]) {
+            j += 1;
+        }
+        if j >= bytes.len() || bytes[j] != b'=' {
+            i = j.max(i + 1);
+            continue;
+        }
+        j += 1; // past '='
+        while j < bytes.len() && is_ws(bytes[j]) {
+            j += 1;
+        }
+        if j >= bytes.len() {
+            return None;
+        }
+        let quote = bytes[j];
+        if quote != b'"' && quote != b'\'' {
+            // Unquoted attribute values aren't part of well-formed
+            // XML (HTML5 allows them, XML doesn't). Skip.
+            i = j;
+            continue;
+        }
+        let value_start = j + 1;
+        let close = bytes[value_start..].iter().position(|&b| b == quote)?;
+        let value = &element[value_start..value_start + close];
+        return Some(value.to_string());
+    }
+    None
+}
+
+/// Extract the trimmed text content of the first occurrence of
+/// `<tag>...</tag>` in `xml`. Returns `None` if the tag isn't found
+/// or its opening tag is malformed.
+///
+/// Whitespace around the inner text is stripped. Self-closing
+/// `<tag />` yields `Some("")`. Nested same-name tags are NOT
+/// handled — the first close encountered wins (this matches the
+/// prior behavior in criterion.rs).
+pub fn text(xml: &str, tag: &str) -> Option<String> {
+    let (open_end, body_start) = find_open_tag(xml, tag, 0)?;
+    // Self-closing — already consumed in find_open_tag if `/>`.
+    if open_end == body_start {
+        // Means find_open_tag returned the same offset twice for
+        // self-closing form. (Not currently the case in our impl,
+        // but defensive.)
+        return Some(String::new());
+    }
+    // For self-closing tags, body_start is past `/>` and we have no
+    // content. Detect by checking the char at body_start - 1 was `/`.
+    if body_start >= 2 && &xml[body_start - 2..body_start] == "/>" {
+        return Some(String::new());
+    }
+    // Find the matching close tag. Case-insensitive + namespace-aware.
+    let close_start = find_close_tag(xml, tag, body_start)?;
+    Some(xml[body_start..close_start].trim().to_string())
+}
+
+/// Locate the next `<tag>` opening AND its closing `</tag>` in
+/// `xml`, starting at byte offset `from`. Returns `(element_start,
+/// element_end)` — `element_start` is the `<` of the opening tag,
+/// `element_end` is one past the `>` of the closing tag. Useful for
+/// iterating over repeated elements like `<playlist>` blocks in
+/// `paramount`.
+///
+/// Self-closing elements return the same offset for body_end as the
+/// element_end (i.e. `element_end - element_start` includes only the
+/// `<tag .../>` text).
+pub fn find_element(xml: &str, tag: &str, from: usize) -> Option<(usize, usize)> {
+    let bytes = xml.as_bytes();
+    let mut i = from;
+    while i < bytes.len() {
+        if bytes[i] != b'<' {
+            i += 1;
+            continue;
+        }
+        // Try matching tag name at i+1 (after `<`).
+        let after_lt = i + 1;
+        if !matches_tag_name_at(bytes, after_lt, tag) {
+            i += 1;
+            continue;
+        }
+        // Found an open tag at offset i. Walk to find the closing `>`
+        // of the open tag itself.
+        let mut j = after_lt;
+        // Skip past the tag name (and optional namespace prefix).
+        while j < bytes.len() && (is_name_char(bytes[j]) || bytes[j] == b':') {
+            j += 1;
+        }
+        // Walk attributes — track quoting state.
+        let mut self_closing = false;
+        while j < bytes.len() {
+            match bytes[j] {
+                b'>' => {
+                    j += 1;
+                    break;
+                }
+                b'/' if j + 1 < bytes.len() && bytes[j + 1] == b'>' => {
+                    self_closing = true;
+                    j += 2;
+                    break;
+                }
+                b'"' | b'\'' => {
+                    let q = bytes[j];
+                    j += 1;
+                    while j < bytes.len() && bytes[j] != q {
+                        j += 1;
+                    }
+                    if j < bytes.len() {
+                        j += 1;
+                    }
+                }
+                _ => j += 1,
+            }
+        }
+        if self_closing {
+            return Some((i, j));
+        }
+        // Find matching close. Doesn't handle nested same-name; OK
+        // for our authoring-tool subset.
+        let close_start = find_close_tag(xml, tag, j)?;
+        let close_end = find_byte(bytes, b'>', close_start)? + 1;
+        return Some((i, close_end));
+    }
+    None
+}
+
+// ── Internal helpers ───────────────────────────────────────────────────────
+
+/// True if `bytes[start..]` opens a tag named `tag`, allowing an
+/// optional `ns:` namespace prefix. Comparison is case-insensitive.
+/// The character after the tag name must not be a name-continuation
+/// (so `<player>` doesn't match `<play>`).
+fn matches_tag_name_at(bytes: &[u8], start: usize, tag: &str) -> bool {
+    let tag_lower = tag.to_ascii_lowercase();
+    let tag_bytes = tag_lower.as_bytes();
+    // Skip optional `prefix:` (one or more name chars + `:`).
+    let mut name_start = start;
+    let mut scan = start;
+    while scan < bytes.len() && is_name_char(bytes[scan]) {
+        scan += 1;
+    }
+    if scan < bytes.len() && bytes[scan] == b':' {
+        name_start = scan + 1;
+    }
+    if name_start + tag_bytes.len() > bytes.len() {
+        return false;
+    }
+    if !slice_eq_ignore_case(&bytes[name_start..name_start + tag_bytes.len()], tag_bytes) {
+        return false;
+    }
+    // Boundary: char after the tag name must be `>`, `/`, whitespace.
+    let after = name_start + tag_bytes.len();
+    if after >= bytes.len() {
+        return false;
+    }
+    matches!(bytes[after], b'>' | b'/' | b' ' | b'\t' | b'\n' | b'\r')
+}
+
+/// Find the offset of the next `</tag>` (or `</ns:tag>`) in `xml`
+/// starting at `from`. Case-insensitive; returns the offset of the
+/// `<`. None if not found.
+fn find_close_tag(xml: &str, tag: &str, from: usize) -> Option<usize> {
+    let bytes = xml.as_bytes();
+    let mut i = from;
+    while i + 2 < bytes.len() {
+        if bytes[i] == b'<' && bytes[i + 1] == b'/' {
+            // Check tag name (with optional namespace).
+            if matches_tag_name_at(bytes, i + 2, tag) {
+                return Some(i);
+            }
+        }
+        i += 1;
+    }
+    None
+}
+
+/// Find the open tag of `<tag>` in `xml` starting at `from`. Returns
+/// `(after_open_lt, after_open_gt)` — the offsets are: just past
+/// the `<` of the open tag, and just past the `>` of the open tag.
+fn find_open_tag(xml: &str, tag: &str, from: usize) -> Option<(usize, usize)> {
+    let bytes = xml.as_bytes();
+    let (elem_start, _) = find_element(xml, tag, from)?;
+    let after_lt = elem_start + 1;
+    // Find the `>` that ends the open tag (handling quoted attrs).
+    let mut j = after_lt;
+    while j < bytes.len() {
+        match bytes[j] {
+            b'>' => return Some((after_lt, j + 1)),
+            b'/' if j + 1 < bytes.len() && bytes[j + 1] == b'>' => {
+                return Some((after_lt, j + 2));
+            }
+            b'"' | b'\'' => {
+                let q = bytes[j];
+                j += 1;
+                while j < bytes.len() && bytes[j] != q {
+                    j += 1;
+                }
+                if j < bytes.len() {
+                    j += 1;
+                }
+            }
+            _ => j += 1,
+        }
+    }
+    None
+}
+
+fn find_byte(bytes: &[u8], target: u8, from: usize) -> Option<usize> {
+    bytes[from..]
+        .iter()
+        .position(|&b| b == target)
+        .map(|p| p + from)
+}
+
+/// True if `c` can be part of an XML name token (rough). We accept
+/// alphanumerics, `_`, `-`, `.`.
+fn is_name_char(c: u8) -> bool {
+    c.is_ascii_alphanumeric() || c == b'_' || c == b'-' || c == b'.'
+}
+
+fn is_ws(c: u8) -> bool {
+    matches!(c, b' ' | b'\t' | b'\n' | b'\r')
+}
+
+fn slice_eq_ignore_case(a: &[u8], b_lower: &[u8]) -> bool {
+    if a.len() != b_lower.len() {
+        return false;
+    }
+    a.iter()
+        .zip(b_lower.iter())
+        .all(|(&x, &y)| x.to_ascii_lowercase() == y)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn attr_basic() {
+        assert_eq!(
+            attr(r#"<playlist name="Feature" id="00222" />"#, "name"),
+            Some("Feature".into())
+        );
+        assert_eq!(
+            attr(r#"<playlist name="Feature" id="00222" />"#, "id"),
+            Some("00222".into())
+        );
+    }
+
+    #[test]
+    fn attr_case_insensitive_name() {
+        assert_eq!(
+            attr(r#"<playlist Name="Feature" />"#, "name"),
+            Some("Feature".into())
+        );
+        assert_eq!(
+            attr(r#"<playlist NAME="Feature" />"#, "Name"),
+            Some("Feature".into())
+        );
+    }
+
+    #[test]
+    fn attr_accepts_single_quotes() {
+        assert_eq!(
+            attr(r#"<playlist name='Feature' />"#, "name"),
+            Some("Feature".into())
+        );
+    }
+
+    #[test]
+    fn attr_whitespace_around_equals() {
+        assert_eq!(
+            attr(r#"<playlist name = "Feature" />"#, "name"),
+            Some("Feature".into())
+        );
+        assert_eq!(
+            attr("<playlist name\n=\n\"Feature\" />", "name"),
+            Some("Feature".into())
+        );
+    }
+
+    #[test]
+    fn attr_missing_returns_none() {
+        assert_eq!(attr(r#"<playlist name="X" />"#, "id"), None);
+        assert_eq!(attr("", "name"), None);
+    }
+
+    #[test]
+    fn attr_no_substring_false_positive() {
+        // Looking for "lang" should NOT match "lang_id" or
+        // "language" because of the name-char boundary check.
+        assert_eq!(attr(r#"<x lang_id="fra" language="eng" />"#, "lang"), None);
+    }
+
+    #[test]
+    fn attr_empty_value() {
+        assert_eq!(attr(r#"<x name="" id="1" />"#, "name"), Some("".into()));
+    }
+
+    #[test]
+    fn text_basic() {
+        assert_eq!(text("<x>hello</x>", "x"), Some("hello".into()));
+        assert_eq!(
+            text("<x>  hello world  </x>", "x"),
+            Some("hello world".into())
+        );
+    }
+
+    #[test]
+    fn text_case_insensitive_tag() {
+        assert_eq!(text("<X>foo</X>", "x"), Some("foo".into()));
+        assert_eq!(text("<Foo>bar</foo>", "foo"), Some("bar".into()));
+    }
+
+    #[test]
+    fn text_namespace_prefix() {
+        assert_eq!(text("<ns:tag>value</ns:tag>", "tag"), Some("value".into()));
+        assert_eq!(text("<foo:Bar>v</foo:Bar>", "bar"), Some("v".into()));
+    }
+
+    #[test]
+    fn text_self_closing() {
+        assert_eq!(text("<x/>", "x"), Some("".into()));
+        assert_eq!(text("<x />", "x"), Some("".into()));
+        assert_eq!(text("<x  attr=\"y\" />", "x"), Some("".into()));
+    }
+
+    #[test]
+    fn text_with_attrs() {
+        assert_eq!(
+            text(r#"<x id="1" name="y">hello</x>"#, "x"),
+            Some("hello".into())
+        );
+    }
+
+    #[test]
+    fn text_missing_close_returns_none() {
+        assert_eq!(text("<x>hello", "x"), None);
+    }
+
+    #[test]
+    fn text_skips_inner_tags_naively() {
+        // Limitation noted: nested same-name tags aren't handled.
+        // Different-name nesting works (we just return everything
+        // between the open and close).
+        assert_eq!(
+            text("<x><y>nested</y></x>", "x"),
+            Some("<y>nested</y>".into())
+        );
+    }
+
+    #[test]
+    fn find_element_basic() {
+        let xml = r#"<x />  <y attr="1">body</y>"#;
+        let (s, e) = find_element(xml, "y", 0).unwrap();
+        assert_eq!(&xml[s..e], r#"<y attr="1">body</y>"#);
+    }
+
+    #[test]
+    fn find_element_self_closing() {
+        let xml = r#"<x />"#;
+        let (s, e) = find_element(xml, "x", 0).unwrap();
+        assert_eq!(&xml[s..e], "<x />");
+    }
+
+    #[test]
+    fn find_element_handles_quoted_gt_in_attr() {
+        // A `>` inside a quoted attribute value should not terminate
+        // the open tag prematurely.
+        let xml = r#"<x attr="foo>bar">body</x>"#;
+        let (s, e) = find_element(xml, "x", 0).unwrap();
+        assert_eq!(&xml[s..e], r#"<x attr="foo>bar">body</x>"#);
+    }
+
+    #[test]
+    fn find_element_iteration() {
+        let xml = "<p>a</p><p>b</p><p>c</p>";
+        let mut positions = Vec::new();
+        let mut from = 0;
+        while let Some((s, e)) = find_element(xml, "p", from) {
+            positions.push(&xml[s..e]);
+            from = e;
+        }
+        assert_eq!(positions, vec!["<p>a</p>", "<p>b</p>", "<p>c</p>"]);
+    }
+
+    #[test]
+    fn find_element_with_namespace() {
+        let xml = r#"<root><ns:item id="1" /></root>"#;
+        let (s, e) = find_element(xml, "item", 0).unwrap();
+        assert_eq!(&xml[s..e], r#"<ns:item id="1" />"#);
+    }
+}
@@ -79,10 +79,12 @@ pub mod disc;
 pub mod drive;
 pub mod error;
 pub mod event;
+pub mod halt;
 pub(crate) mod identity;
 pub(crate) mod ifo;
+pub mod io;
 pub mod keydb;
-pub(crate) mod labels;
+pub mod labels;
 pub(crate) mod mpls;
 pub mod mux;
 pub mod pes;
@@ -115,6 +117,31 @@ pub use drive::{Drive, DriveStatus, find_drive};
 // codes to localized messages. See `error.rs` for the full taxonomy.
 pub use error::{Error, Result};

+// ─── 0.18 primitives ────────────────────────────────────────────────────────
+//
+// One-bit cooperative cancellation token, shared by every long-running loop
+// in libfreemkv (sweep, patch, mux). Replaces the ad-hoc `Arc<AtomicBool>`
+// flags scattered across 0.17 (`DiscStream::set_halt`, autorip's
+// `HALT_FLAGS` registry). Clone it cheaply; pass it by value into each
+// component; poll `is_cancelled()` inside the loop body.
+pub use halt::Halt;
+
+// Generic bounded producer/consumer primitive used by sweep, patch, and
+// mux to overlap reads with writes via a dedicated consumer thread.
+// `Pipeline::spawn(name, depth, sink)` spawns a named consumer; `pipe.send(item)`
+// pushes one item with back-pressure; `pipe.finish()` joins the
+// consumer and surfaces its `close()` output. Callers implement `Sink`
+// to define per-item behaviour and end-of-stream finalisation.
+//
+// `DEFAULT_PIPELINE_DEPTH` (=4) is for callers without specific needs;
+// most should use READ_PIPELINE_DEPTH or WRITE_PIPELINE_DEPTH instead.
+// Patch uses `WRITE_THROUGH_DEPTH` (=1). Returning `Flow::Stop` from
+// `apply` ends the consumer cleanly (still calls `close()`).
+pub use io::pipeline::{
+    DEFAULT_PIPELINE_DEPTH, Flow, Pipeline, READ_PIPELINE_DEPTH, Sink, WRITE_PIPELINE_DEPTH,
+    WRITE_THROUGH_DEPTH,
+};
+
 // ─── Drive events (low-level callbacks) ─────────────────────────────────────
 pub use event::{Event, EventKind};
 pub use identity::DriveId;
@@ -136,11 +163,15 @@ pub use decrypt::{DecryptKeys, decrypt_sectors};
 // for displaying disc name + format quickly while a full scan runs in the
 // background. The codec / channel / resolution enums are the canonical
 // structured representation; never compare against display strings.
+// Note: `disc::Stream` here is the codec enum (audio / video / sub kind)
+// — not the `pes::Stream` trait re-exported below as `PesStream`. Two
+// different concepts, the same short name; the trait gets the `Pes`
+// prefix at the crate root to keep both addressable.
 pub use disc::{
    AacsState, AudioChannels, AudioStream, Clip, Codec, ColorSpace, ContentFormat, DamageSeverity,
    Disc, DiscFormat, DiscId, DiscTitle, Extent, FrameRate, HdrFormat, KeySource, LabelPurpose,
-    LabelQualifier, Resolution, SampleRate, ScanOptions, Stream, SubtitleStream, VideoStream,
-    classify_damage,
+    LabelQualifier, PatchOptions, PatchOutcome, Resolution, SampleRate, ScanOptions, Stream,
+    SubtitleStream, SweepOptions, VideoStream, classify_damage,
 };

 // ─── Streams ────────────────────────────────────────────────────────────────
@@ -148,7 +179,7 @@ pub use disc::{
 // All stream types implement `pes::Stream` — read PES frames from a source,
 // write PES frames to a sink. Pick the right type at construction:
 //
-// - `DiscStream` — physical drive or ISO (any `SectorReader`). Always read.
+// - `DiscStream` — physical drive or ISO (any `SectorSource`). Read-only.
 // - `MkvStream`  — Matroska container. Read on `open()`, write on `create()`.
 // - `M2tsStream` — Blu-ray Transport Stream. Read on `open()`, write on `create()`.
 // - `NetworkStream` — TCP. Read on `listen()`, write on `connect()`.
@@ -158,6 +189,12 @@ pub use disc::{
 // Most consumers use the URL resolvers (`input()` / `output()`) which pick
 // the right type from a scheme:// URL. Direct construction is for callers
 // that need to wire custom readers (e.g. autorip's drive-session reuse).
+// The trait is re-exported as `PesStream` here to disambiguate from
+// `disc::Stream` (the codec-kind enum re-exported above), which would
+// otherwise collide at the crate root.
+pub use pes::PesFrame;
+pub use pes::Stream as PesStream;
+
 pub use mux::DiscStream;
 pub use mux::M2tsStream;
 pub use mux::MkvStream;
@@ -169,10 +206,14 @@ pub use mux::{InputOptions, StreamUrl, input, output, parse_url};
 // ─── Lower-level surfaces ───────────────────────────────────────────────────
 //
 // `ScsiTransport` is the platform-abstraction trait Drive uses; expose for
-// out-of-tree platform backends. `SectorReader` lets callers feed any byte
-// source (test harness, network image, SMB share) into the disc scan
-// pipeline; `FileSectorReader` is the standard ISO-on-disk implementation.
+// out-of-tree platform backends. `SectorSource` / `SectorSink` are the
+// direction-typed read/write traits; `FileSectorSource` and `FileSectorSink`
+// are the ISO-on-disk implementations. [`DecryptingSectorSource`] is the
+// single decrypt-on-read decorator (AACS / CSS / none) — wrap any
+// `SectorSource` to get plaintext sectors out.
 pub use scsi::{DriveInfo, ScsiSense, ScsiTransport, drive_has_disc, list_drives};
-pub use sector::{FileSectorReader, SectorReader};
+pub use sector::{
+    DecryptingSectorSource, FileSectorSink, FileSectorSource, SectorSink, SectorSource,
+};
 pub use speed::DriveSpeed;
 pub use udf::{UdfFs, read_filesystem};
@@ -1,6 +1,6 @@
 //! DiscStream — read any disc (physical drive or ISO file) → PES frames.
 //!
-//! One stream type for all disc sources. The source is a SectorReader —
+//! One stream type for all disc sources. The source is a SectorSource —
 //! Drive (hardware) or IsoSectorReader (file). DiscStream doesn't care.
 //!
 //! Read-only. For disc→ISO (raw sector copy), use `Disc::copy()`.
@@ -8,10 +8,11 @@
 use crate::disc::{Disc, DiscTitle, Extent};
 use crate::drive::extract_scsi_context;
 use crate::event::{BatchSizeReason, Event, EventKind};
-use crate::sector::SectorReader;
+use crate::halt::Halt;
+use crate::sector::{DecryptingSectorSource, SectorSource};
 use std::io;
 use std::sync::Arc;
-use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::atomic::AtomicBool;

 /// Ramp back up to the preferred batch size after this many sectors
 /// of clean reading at the current (reduced) size. 100 MiB = 51,200 sectors.
@@ -96,12 +97,22 @@ impl AdaptiveBatch {

 /// Disc stream. Reads sectors from any source → PES frames.
 ///
-/// Sources: physical drive, ISO file, or any SectorReader.
+/// Sources: physical drive, ISO file, or any SectorSource.
 /// Decrypt, demux, and codec parsing happen internally.
 pub struct DiscStream {
-    reader: Box<dyn SectorReader>,
+    /// Underlying sector source wrapped in the 0.18
+    /// [`DecryptingSectorSource`] decorator. Every `read_sectors`
+    /// call yields plaintext, so `fill_extents` no longer needs an
+    /// inline `decrypt::decrypt_sectors` step. `DecryptKeys::None`
+    /// (raw / unencrypted disc) makes the decorator a pass-through.
+    reader: DecryptingSectorSource<Box<dyn SectorSource>>,
    title: DiscTitle,
    disc: Option<Disc>,
+    /// Mirror of the keys handed in at construction. The decorator
+    /// owns the cryptographic state; this field is kept for
+    /// metadata-side callers (`info()` and friends) that want to
+    /// know whether the disc was encrypted, without reaching through
+    /// the wrapper.
    decrypt_keys: crate::decrypt::DecryptKeys,

    // Extents to read
@@ -120,11 +131,13 @@ pub struct DiscStream {
    adaptive: AdaptiveBatch,
    pub errors: u64,
    pub skip_errors: bool,
-    /// When set and the flag is raised, fill_extents returns Err(Halted) at the
-    /// next retry boundary. Unlike skip_errors, this propagates the error up so
-    /// the rip terminates cleanly. Share the Arc with Drive::halt_flag() to get
-    /// unified Stop behavior across drive reads and sector processing.
-    halt: Option<Arc<AtomicBool>>,
+    /// When set and the token is cancelled, fill_extents returns Err(Halted)
+    /// at the next retry boundary. Unlike skip_errors, this propagates the
+    /// error up so the rip terminates cleanly. Construct with
+    /// [`DiscStream::with_halt`] (preferred) or set post-hoc via the
+    /// deprecated [`DiscStream::set_halt`] bridge — both populate this same
+    /// field and either entry point yields one source of truth.
+    halt: Option<Halt>,
    event_fn: Option<Box<dyn Fn(Event) + Send>>,
    eof: bool,

@@ -147,11 +160,11 @@ pub struct DiscStream {
 impl DiscStream {
    /// Create a disc stream from any sector reader.
    ///
-    /// Works with physical drives and ISO files — both implement SectorReader.
+    /// Works with physical drives and ISO files — both implement SectorSource.
    /// The caller opens the source, scans for titles/keys, and passes them in.
    /// The stream handles demuxing, decryption, and codec parsing internally.
    pub fn new(
-        reader: Box<dyn SectorReader>,
+        reader: Box<dyn SectorSource>,
        title: DiscTitle,
        decrypt_keys: crate::decrypt::DecryptKeys,
        batch_sectors: u16,
@@ -160,6 +173,13 @@ impl DiscStream {
        let extents = title.extents.clone();
        let bytes_total_extents: u64 = extents.iter().map(|e| e.sector_count as u64 * 2048).sum();

+        // Debug log reader type at construction — critical for diagnosing mux reading from drive instead of ISO
+        tracing::debug!(
+            target: "mux",
+            "DiscStream constructed with reader type: {}",
+            std::any::type_name::<dyn SectorSource>()
+        );
+
        let mut pids = Vec::new();
        let mut parsers = Vec::new();
        let mut pid_to_track = Vec::new();
@@ -189,7 +209,11 @@ impl DiscStream {
        }

        Self {
-            reader,
+            // Wrap the input reader in DecryptingSectorSource so the
+            // internal fill_extents path sees plaintext bytes. For
+            // DecryptKeys::None (unencrypted / raw / test fixtures)
+            // the decorator is a pass-through.
+            reader: DecryptingSectorSource::new(reader, decrypt_keys.clone()),
            title,
            disc: None,
            decrypt_keys,
@@ -219,19 +243,39 @@ impl DiscStream {
        self.event_fn = Some(Box::new(f));
    }

-    /// Share a halt flag — typically from `Drive::halt_flag()`. When raised,
-    /// the next read-retry boundary inside fill_extents returns Err(Halted)
-    /// instead of continuing. Required for Stop to work during dense bad-sector
-    /// regions (where read() loops internally waiting for enough clean data to
-    /// emit a frame and would otherwise never check an external stop signal).
+    /// Constructor-time builder: attach a [`Halt`] token so that when
+    /// any clone is cancelled, the next read-retry boundary inside
+    /// `fill_extents` returns `Err(Halted)`. Required for Stop to work
+    /// during dense bad-sector regions (where the outer PES read() loop
+    /// can spend minutes inside fill_extents before emitting a frame).
+    ///
+    /// Preferred over the post-hoc [`DiscStream::set_halt`] bridge —
+    /// pass the same `Halt` clone you hand to sweep / patch / mux so
+    /// every phase observes a single Stop signal.
+    pub fn with_halt(mut self, halt: Halt) -> Self {
+        self.halt = Some(halt);
+        self
+    }
+
+    /// Bridge for callers that haven't migrated to the
+    /// [`DiscStream::with_halt`] constructor-time path yet. Wraps the
+    /// supplied `Arc<AtomicBool>` as a [`Halt`] (`Halt::from_arc`) and
+    /// stores it in the same internal slot, so a halt installed via
+    /// either entry point goes through one halt-check inside
+    /// `fill_extents`. Calling `set_halt` after `with_halt` (or vice
+    /// versa) replaces the previous token with the new one.
+    #[deprecated(
+        since = "0.18.0",
+        note = "use `DiscStream::with_halt(Halt)` at construction instead"
+    )]
    pub fn set_halt(&mut self, flag: Arc<AtomicBool>) {
-        self.halt = Some(flag);
+        self.halt = Some(Halt::from_arc(flag));
    }

    fn is_halted(&self) -> bool {
        self.halt
            .as_ref()
-            .map(|h| h.load(Ordering::Relaxed))
+            .map(|h| h.is_cancelled())
            .unwrap_or(false)
    }

@@ -241,9 +285,12 @@ impl DiscStream {
        }
    }

-    /// Skip decryption — return raw encrypted bytes.
+    /// Skip decryption — return raw encrypted bytes. Updates both
+    /// the metadata-side key field and the wrapped reader's keys so
+    /// subsequent `read_sectors` calls become a pass-through.
    pub fn set_raw(&mut self) {
        self.decrypt_keys = crate::decrypt::DecryptKeys::None;
+        self.reader.set_keys(crate::decrypt::DecryptKeys::None);
    }

    /// Get the scanned Disc (for listing all titles).
@@ -275,10 +322,19 @@ impl DiscStream {
        // this loop can spend minutes shrinking and skipping sectors; without
        // the check, Stop wouldn't take effect until the outer PES read() loop
        // finally emits a frame, which may never happen.
+
+        let start_time = std::time::Instant::now();
+
        loop {
            if self.is_halted() {
                return Err(crate::error::Error::Halted.into());
            }
+
+            // Debug: log slow reads during mux — helps diagnose stalls
+            if cfg!(debug_assertions) && start_time.elapsed().as_secs() > 5 {
+                tracing::debug!(target: "mux", "fill_extents waiting at LBA {} ({}s elapsed, sectors={})", lba, start_time.elapsed().as_secs(), remaining);
+            }
+
            let mut sectors = remaining.min(self.adaptive.current() as u32) as u16;
            // Align to 3-sector AACS units when possible. Partial units at
            // extent boundaries are safely handled by decrypt_sectors().
@@ -419,11 +475,10 @@ impl crate::pes::Stream for DiscStream {
            }

            let bytes = self.buf_valid;
-            if let Err(e) =
-                crate::decrypt::decrypt_sectors(&mut self.read_buf[..bytes], &self.decrypt_keys, 0)
-            {
-                return Err(e.into());
-            }
+            // Plaintext: the wrapped reader (DecryptingSectorSource)
+            // applied AACS / CSS in-place during fill_extents'
+            // read_sectors call. The pre-0.18 inline decrypt step
+            // lived here.

            if let Some(ref mut demuxer) = self.ts_demuxer {
                let packets = demuxer.feed(&self.read_buf[..bytes]);
@@ -525,3 +580,140 @@ impl crate::pes::Stream for DiscStream {
        true
    }
 }
+
+#[cfg(test)]
+mod tests {
+    //! `DiscStream` is the only read-only `Stream` impl in tree (every
+    //! other concrete impl in `mux/*` is bidirectional or write-only).
+    //! These tests lock down a static `Send` assertion plus a
+    //! `Box<dyn Stream>` round trip exercising every method through the
+    //! trait object, so future Send-breaking edits to `DiscStream`'s
+    //! interior types fail at compile time.
+    use super::*;
+    use crate::disc::{ContentFormat, DiscTitle};
+    use crate::pes::Stream;
+
+    /// Static-assert `DiscStream: Send`. The `Stream` trait has `Send` as a
+    /// supertrait — if a future field on `DiscStream` is non-`Send` (e.g.
+    /// a `Box<dyn Read>` instead of `Box<dyn SectorSource>`), this fails
+    /// at compile time, before the runtime trait-object test below.
+    fn _assert_disc_stream_is_send() {
+        fn requires_send<T: Send>() {}
+        requires_send::<DiscStream>();
+    }
+
+    /// Trivial `SectorSource` that yields zeroed sectors. Empty title means
+    /// the demuxer produces no PES frames, so `read()` walks the extents to
+    /// EOF and returns `Ok(None)`. That's enough to exercise the trait-object
+    /// dispatch — the goal here is the bridge, not the demuxer.
+    struct ZeroReader {
+        capacity: u32,
+    }
+
+    impl crate::sector::SectorSource for ZeroReader {
+        fn read_sectors(
+            &mut self,
+            _lba: u32,
+            count: u16,
+            buf: &mut [u8],
+            _recovery: bool,
+        ) -> crate::error::Result<usize> {
+            let bytes = count as usize * 2048;
+            buf[..bytes].fill(0);
+            Ok(bytes)
+        }
+
+        fn capacity_sectors(&self) -> u32 {
+            self.capacity
+        }
+    }
+
+    fn synthetic_title(sector_count: u32) -> DiscTitle {
+        DiscTitle {
+            extents: vec![crate::disc::Extent {
+                start_lba: 0,
+                sector_count,
+            }],
+            ..DiscTitle::empty()
+        }
+    }
+
+    /// Smallest credible witness that `DiscStream` flows through `dyn Stream`:
+    /// build a `Box<dyn Stream>`, drive `read()` to EOF, exercise `info()` /
+    /// `headers_ready()` / `codec_private()` through the trait object.
+    #[test]
+    fn stream_via_dyn_object() {
+        let reader = ZeroReader { capacity: 8 };
+        let title = synthetic_title(8);
+        let stream = DiscStream::new(
+            Box::new(reader),
+            title,
+            crate::decrypt::DecryptKeys::None,
+            8,
+            ContentFormat::BdTs,
+        );
+
+        let mut src: Box<dyn Stream> = Box::new(stream);
+
+        // Empty-title fixture has no streams configured, so headers are
+        // trivially ready and codec_private() yields nothing on track 0.
+        assert!(src.headers_ready());
+        assert!(src.codec_private(0).is_none());
+        let _ = src.info();
+
+        // Drive read() to EOF through the trait object — empty-title fixture
+        // produces no frames, but the call still routes through the blanket
+        // dispatch into Stream::read.
+        let mut frames = 0usize;
+        while src.read().expect("read").is_some() {
+            frames += 1;
+            if frames > 1024 {
+                panic!("unexpected unbounded frame stream from empty title");
+            }
+        }
+        assert_eq!(frames, 0);
+    }
+
+    /// `is_halted()` must observe a cancellation signal regardless of
+    /// which entry point installed the token. The deprecated
+    /// `set_halt(Arc<AtomicBool>)` and the new `with_halt(Halt)` are
+    /// two views over one slot — flipping either bit must cause the
+    /// next `fill_extents` retry boundary to bail.
+    #[test]
+    fn halt_via_with_halt_observed_by_is_halted() {
+        let halt = Halt::new();
+        let stream = DiscStream::new(
+            Box::new(ZeroReader { capacity: 8 }),
+            synthetic_title(8),
+            crate::decrypt::DecryptKeys::None,
+            8,
+            crate::disc::ContentFormat::BdTs,
+        )
+        .with_halt(halt.clone());
+        assert!(!stream.is_halted());
+        halt.cancel();
+        assert!(
+            stream.is_halted(),
+            "with_halt token cancellation must be observed by is_halted()"
+        );
+    }
+
+    #[test]
+    fn halt_via_set_halt_bridge_observed_by_is_halted() {
+        let arc = Arc::new(AtomicBool::new(false));
+        let mut stream = DiscStream::new(
+            Box::new(ZeroReader { capacity: 8 }),
+            synthetic_title(8),
+            crate::decrypt::DecryptKeys::None,
+            8,
+            crate::disc::ContentFormat::BdTs,
+        );
+        stream.set_halt(arc.clone());
+        assert!(!stream.is_halted());
+        arc.store(true, std::sync::atomic::Ordering::Relaxed);
+        assert!(
+            stream.is_halted(),
+            "set_halt(Arc<AtomicBool>) bridge must observe Arc-side flips"
+        );
+    }
+}
@@ -1,10 +1,10 @@
-//! ISO sector reader — file-backed SectorReader for Blu-ray ISO images.
+//! ISO sector reader — file-backed SectorSource for Blu-ray ISO images.
 //!
 //! An ISO is a flat image of 2048-byte sectors. Sector N starts at byte offset N * 2048.
 //! Used by DiscStream::open_iso() and Disc::scan_image().

 use crate::error::{Error, Result};
-use crate::sector::SectorReader;
+use crate::sector::SectorSource;
 use std::fs::File;
 use std::io::{Read, Seek, SeekFrom};
 use std::path::Path;
@@ -32,12 +32,12 @@ impl IsoSectorReader {
        Ok(Self { file, capacity })
    }

-    pub fn capacity(&self) -> u32 {
+    pub fn capacity_sectors(&self) -> u32 {
        self.capacity
    }
 }

-impl SectorReader for IsoSectorReader {
+impl SectorSource for IsoSectorReader {
    fn read_sectors(
        &mut self,
        lba: u32,
@@ -73,7 +73,7 @@ mod tests {
        std::fs::write(&dir, &data).unwrap();

        let mut reader = IsoSectorReader::open(dir.to_str().unwrap()).unwrap();
-        assert_eq!(reader.capacity(), 4);
+        assert_eq!(reader.capacity_sectors(), 4);

        let mut buf = [0u8; 2048];
        reader.read_sectors(0, 1, &mut buf, true).unwrap();
@@ -94,7 +94,7 @@ mod tests {
        std::fs::write(&dir, &data).unwrap();

        let reader = IsoSectorReader::open(dir.to_str().unwrap()).unwrap();
-        assert_eq!(reader.capacity(), 10);
+        assert_eq!(reader.capacity_sectors(), 10);

        std::fs::remove_file(&dir).ok();
    }
@@ -18,10 +18,10 @@ const SCAN_SIZE: usize = 1024 * 1024;

 enum Mode {
    Write {
-        muxer: super::tsmux::TsMuxer<Box<dyn Write>>,
+        muxer: super::tsmux::TsMuxer<Box<dyn Write + Send>>,
    },
    Read {
-        reader: Box<dyn Read>,
+        reader: Box<dyn Read + Send>,
    },
 }

@@ -57,7 +57,7 @@ pub struct M2tsStream {
 impl M2tsStream {
    /// Create for writing PES frames → BD-TS output.
    /// Writes FMKV metadata header, then muxes PES frames into BD transport stream.
-    pub fn create(mut writer: impl Write + 'static, title: &DiscTitle) -> io::Result<Self> {
+    pub fn create(mut writer: impl Write + Send + 'static, title: &DiscTitle) -> io::Result<Self> {
        // Write FMKV metadata header
        if !title.streams.is_empty() {
            let m = meta::M2tsMeta::from_title(title);
@@ -72,7 +72,7 @@ impl M2tsStream {
                DiscStream::Subtitle(s) => s.pid,
            })
            .collect();
-        let boxed: Box<dyn Write> = Box::new(writer);
+        let boxed: Box<dyn Write + Send> = Box::new(writer);
        let mut muxer = super::tsmux::TsMuxer::new(boxed, &pids);
        for (i, cp) in title.codec_privates.iter().enumerate() {
            if let Some(data) = cp {
@@ -111,7 +111,7 @@ impl M2tsStream {
    /// Open an M2TS stream for reading. Takes any Read source — file, pipe, socket.
    ///
    /// Tries FMKV metadata header first. Falls back to PMT scan of first 1 MB.
-    pub fn open(mut reader: impl Read + 'static) -> io::Result<Self> {
+    pub fn open(mut reader: impl Read + Send + 'static) -> io::Result<Self> {
        // Read first chunk — enough for FMKV header or PMT scan
        let mut head = vec![0u8; SCAN_SIZE];
        let head_len = read_fill(&mut reader, &mut head)?;
@@ -125,7 +125,7 @@ impl M2tsStream {
            let (pids, parsers, pid_to_track) = Self::setup_pes(&title.streams);
            // Chain: remaining head bytes + rest of reader
            let remaining_head = &head[header_end..];
-            let chain: Box<dyn Read> =
+            let chain: Box<dyn Read + Send> =
                Box::new(io::Cursor::new(remaining_head.to_vec()).chain(reader));
            return Ok(Self {
                disc_title: title.clone(),
@@ -150,7 +150,7 @@ impl M2tsStream {
        let (pids, parsers, pid_to_track) = Self::setup_pes(&streams);

        // Chain: full head (it's all TS data) + rest of reader
-        let chain: Box<dyn Read> = Box::new(io::Cursor::new(head).chain(reader));
+        let chain: Box<dyn Read + Send> = Box::new(io::Cursor::new(head).chain(reader));

        Ok(Self {
            disc_title: DiscTitle {
@@ -18,7 +18,7 @@ use crate::disc::*;
 use std::io::{self, Read};

 struct ReadState {
-    reader: Box<dyn Read>,
+    reader: Box<dyn Read + Send>,
    cluster_ts_ms: i64,
    /// Codec private data per track (track_number, hvcC/avcC bytes).
    codec_privates: Vec<(u16, Vec<u8>)>,
@@ -26,7 +26,7 @@ struct ReadState {

 enum Mode {
    Write {
-        muxer: Option<MkvMuxer<Box<dyn WriteSeek>>>,
+        muxer: Option<MkvMuxer<Box<dyn WriteSeek + Send>>>,
    },
    Read(ReadState),
 }
@@ -40,7 +40,7 @@ pub struct MkvStream {
 impl MkvStream {
    /// Create for writing PES frames → MKV container.
    /// Codec privates come from title.codec_privates (populated by input stream).
-    pub fn create(writer: Box<dyn WriteSeek>, title: &DiscTitle) -> io::Result<Self> {
+    pub fn create(writer: Box<dyn WriteSeek + Send>, title: &DiscTitle) -> io::Result<Self> {
        let mut tracks = Vec::new();
        let mut has_default_video = false;
        let mut has_default_audio = false;
@@ -79,7 +79,7 @@ impl MkvStream {
    }

    /// Open an MKV file for reading → PES frames.
-    pub fn open(mut reader: impl Read + 'static) -> io::Result<Self> {
+    pub fn open(mut reader: impl Read + Send + 'static) -> io::Result<Self> {
        let (disc_title, codec_privates) = parse_mkv_header(&mut reader)?;
        Ok(Self {
            disc_title,
@@ -30,3 +30,26 @@ impl crate::pes::Stream for NullStream {
        &self.disc_title
    }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::pes::Stream;
+
+    /// Verify NullStream routes through the `Stream` trait object cleanly.
+    #[test]
+    fn stream_via_dyn_object_writes_and_finishes() {
+        let title = DiscTitle::empty();
+        let mut sink: Box<dyn Stream> = Box::new(NullStream::new(&title));
+
+        let frame = crate::pes::PesFrame {
+            track: 0,
+            pts: 0,
+            keyframe: true,
+            data: vec![0x01, 0x02, 0x03],
+        };
+        sink.write(&frame).unwrap();
+        let _ = sink.info();
+        sink.finish().unwrap();
+    }
+}
@@ -186,7 +186,7 @@ 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())?;
-            let capacity = reader.capacity();
+            let capacity = reader.capacity_sectors();
            let disc = crate::disc::Disc::scan_image(&mut reader, capacity, &scan_opts)
                .map_err(|e| -> io::Error { e.into() })?;
            if disc.titles.is_empty() {
@@ -203,7 +203,11 @@ 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;
-            let mut stream = DiscStream::new(Box::new(reader), title, keys, 64, 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.
+            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();
            }
@@ -242,15 +246,26 @@ pub fn output(
    match parsed {
        StreamUrl::Mkv { ref path } => {
            validate_file_path(path, "mkv")?;
-            let file = std::fs::File::create(path)?;
-            let writer: Box<dyn super::WriteSeek> =
-                Box::new(std::io::BufWriter::with_capacity(IO_BUF_SIZE, file));
+            // Wrap the output in `crate::io::WritebackFile` (bounded-cache
+            // writeback) so a UHD-scale MKV mux to slow / network-attached
+            // staging doesn't hit the dirty-page burst pathology that
+            // sweep already side-steps. BufWriter sits on top to coalesce
+            // mux's many small EBML element writes. Pre-reserve the
+            // target's worth of extents on Linux via fallocate(KEEP_SIZE)
+            // to reduce extent fragmentation during the mux.
+            let writer: Box<dyn super::WriteSeek + Send> =
+                Box::new(std::io::BufWriter::with_capacity(
+                    IO_BUF_SIZE,
+                    crate::io::WritebackFile::create_with_size_hint(path, title.size_bytes)?,
+                ));
            Ok(Box::new(MkvStream::create(writer, title)?))
        }
        StreamUrl::M2ts { ref path } => {
            validate_file_path(path, "m2ts")?;
-            let file = std::fs::File::create(path)?;
-            let writer = std::io::BufWriter::with_capacity(IO_BUF_SIZE, file);
+            let writer = std::io::BufWriter::with_capacity(
+                IO_BUF_SIZE,
+                crate::io::WritebackFile::create_with_size_hint(path, title.size_bytes)?,
+            );
            Ok(Box::new(M2tsStream::create(writer, title)?))
        }
        StreamUrl::Network { ref addr } => {
@@ -78,43 +78,20 @@ impl PesFrame {
    }
 }

-/// A PES frame source or sink. Each implementor is **either** read-only or
-/// write-only — never both.
+/// A PES frame stream. One trait per format — same type opens for read
+/// (`open()` / `listen()` / `input()`) or write (`create()` / `connect()` /
+/// `output()`). Calling the wrong-direction method returns a typed
+/// `StreamReadOnly` / `StreamWriteOnly` error.
 ///
-/// Implementors fall into two camps:
-///
-/// - **Read sources**: `DiscStream` (drive or ISO), `M2tsStream` (when
-///   constructed from an existing file), `MkvStream` (demux), `NetworkStream`
-///   (TCP listener), `StdioStream::input()`. These return frames from
-///   `read()` and surface `StreamWriteOnly` (E9001) from `write()`.
-/// - **Write sinks**: `MkvStream::create`, `M2tsStream::create`,
-///   `NetworkStream::connect`, `StdioStream::output()`, `NullStream`.
-///   These accept frames in `write()` and surface `StreamReadOnly` (E9000)
-///   from `read()`. Always call `finish()` when done — that's where MKV
-///   writes its `Cues` index and `M2tsStream` flushes the TS muxer.
-///
-/// Direction is established at construction; mixing produces an error code,
-/// not a panic. Most consumers don't construct streams directly — call
-/// `mux::input(url, opts)` / `mux::output(url, title)` and let URL parsing
-/// pick the right type.
-///
-/// `info()` returns the stream's `DiscTitle` metadata (track list, codec
-/// info, duration). For sources it's parsed from the input; for sinks it's
-/// the metadata supplied at creation. Stable across all reads.
-///
-/// `codec_private(track)` exposes per-track initialization data
-/// (H.264 SPS/PPS, HEVC VPS/SPS/PPS, AC-3 fscod, etc.) that some output
-/// formats need before any frame can be written. `headers_ready()` returns
-/// false until enough input frames have been seen to populate every video
-/// track's codec-private blob — callers buffer frames they read until
-/// `headers_ready()` returns true.
-pub trait Stream {
+/// `Send` is required so streams can move across the producer/consumer
+/// threads in autorip's mux pipeline.
+pub trait Stream: Send {
    /// Read the next frame, or `Ok(None)` at end of stream. Returns
-    /// `StreamWriteOnly` (E9001) on a write-only sink.
+    /// `StreamWriteOnly` on a stream opened for writing.
    fn read(&mut self) -> std::io::Result<Option<PesFrame>>;

-    /// Write a frame to the sink. Returns `StreamReadOnly` (E9000) on a
-    /// read-only source.
+    /// Write a frame to the sink. Returns `StreamReadOnly` on a stream
+    /// opened for reading.
    fn write(&mut self, frame: &PesFrame) -> std::io::Result<()>;

    /// Finalize the stream: flush buffered frames, write any container
@@ -143,7 +120,7 @@ pub trait Stream {
 /// Wraps any output stream and counts bytes written.
 ///
 /// Progress tracking is a CLI concern — streams don't know their size.
-/// Wrap the output with CountingStream, then query bytes_written().
+/// Wrap the output with `CountingStream`, then query `bytes_written()`.
 ///
 /// ```text
 /// let mut output = CountingStream::new(libfreemkv::output(dest, &title)?);
@@ -194,3 +171,96 @@ impl Stream for CountingStream {
        self.inner.headers_ready()
    }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::disc::DiscTitle;
+
+    fn make_frame(track: usize, pts: i64) -> PesFrame {
+        PesFrame {
+            track,
+            pts,
+            keyframe: track == 0 && pts == 0,
+            data: vec![track as u8, (pts & 0xff) as u8, 0xAA],
+        }
+    }
+
+    /// Minimal in-memory `Stream` for trait-shape tests. `read` replays
+    /// pre-seeded frames; `write` collects them.
+    struct MockStream {
+        read_queue: std::vec::IntoIter<PesFrame>,
+        written: Vec<PesFrame>,
+        title: DiscTitle,
+    }
+
+    impl MockStream {
+        fn new(read_frames: Vec<PesFrame>) -> Self {
+            Self {
+                read_queue: read_frames.into_iter(),
+                written: Vec::new(),
+                title: DiscTitle::empty(),
+            }
+        }
+    }
+
+    impl Stream for MockStream {
+        fn read(&mut self) -> std::io::Result<Option<PesFrame>> {
+            Ok(self.read_queue.next())
+        }
+
+        fn write(&mut self, frame: &PesFrame) -> std::io::Result<()> {
+            self.written.push(frame.clone());
+            Ok(())
+        }
+
+        fn finish(&mut self) -> std::io::Result<()> {
+            Ok(())
+        }
+
+        fn info(&self) -> &DiscTitle {
+            &self.title
+        }
+    }
+
+    #[test]
+    fn stream_read_yields_frames_then_eof() {
+        let frames = vec![make_frame(0, 0), make_frame(1, 1_000), make_frame(0, 2_000)];
+        let mut s = MockStream::new(frames.clone());
+
+        let f0 = s.read().unwrap().expect("first frame");
+        assert_eq!(f0.track, frames[0].track);
+        assert_eq!(f0.pts, frames[0].pts);
+        assert!(f0.keyframe);
+
+        let f1 = s.read().unwrap().expect("second frame");
+        assert_eq!(f1.pts, frames[1].pts);
+
+        let f2 = s.read().unwrap().expect("third frame");
+        assert_eq!(f2.pts, frames[2].pts);
+
+        assert!(s.read().unwrap().is_none());
+        assert!(s.read().unwrap().is_none()); // idempotent at EOF
+    }
+
+    #[test]
+    fn stream_write_collects_then_finishes() {
+        let mut s = MockStream::new(Vec::new());
+        let frames = [make_frame(0, 0), make_frame(1, 100), make_frame(2, 200)];
+
+        for f in &frames {
+            s.write(f).unwrap();
+        }
+        assert_eq!(s.written.len(), 3);
+        s.finish().unwrap();
+    }
+
+    #[test]
+    fn stream_via_dyn_object() {
+        let mut s: Box<dyn Stream> = Box::new(MockStream::new(vec![make_frame(0, 0)]));
+        let frame = s.read().unwrap().expect("first frame");
+        s.write(&frame).unwrap();
+        let _ = s.info();
+        s.finish().unwrap();
+    }
+}
@@ -68,10 +68,25 @@ pub(crate) const TUR_TIMEOUT_MS: u32 = 5_000;
 pub(crate) const READ_TIMEOUT_MS: u32 = 10_000;

 /// Timeout for content READ commands on the recovery path —
-/// [`disc::Disc::patch`]'s targeted retries on bad ranges. Doubles
-/// the fast-path budget so a sector that fails at 30 s gets one more
-/// honest attempt. Matches sg_dd's default per-command timeout
-/// (`DEF_TIMEOUT = 60000`).
+/// [`disc::Disc::patch`]'s targeted retries on bad ranges. Matches
+/// `sg_dd`'s 60 s ceiling: long enough that any sector the drive can
+/// recover at all gets the time to do so, short enough that an
+/// unresponsive bus is detected before the per-range watchdog fires.
+///
+/// In practice failed reads return in 1–4 s (the drive itself gives up
+/// on uncorrectable ECC before the timeout); the 60 s value is a
+/// safety ceiling, not a steady-state cost.
+///
+/// Historical note (2026-05-08): briefly lowered to 2 s with a 5×
+/// inline retry loop in `Disc::patch` to mimic the kernel `sr_mod`
+/// driver's auto-retry pattern. The synthetic logic worked but on the
+/// live drive each "2 s" read paid ~1.5 s of kernel SCSI mid-layer
+/// error escalation on top, so 5× retries took ~17 s per LBA and
+/// triggered MAX_RANGE_SECS after 4 sectors — pushing recovery to
+/// 0/22 ranges (worse than the 0/22 baseline of v0.17.3 single-shot
+/// at 60 s, since that at least visited every range). Reverted; the
+/// kernel-auto-retry approach is being pursued via a `/dev/sr0` pread
+/// fallback instead.
 pub(crate) const READ_RECOVERY_TIMEOUT_MS: u32 = 60_000;

 // ── SCSI status bytes (SPC-4 §4.5.5) ────────────────────────────────────────
@@ -1,82 +0,0 @@
-//! SectorReader — trait for reading 2048-byte disc sectors.
-//!
-//! Implemented by Drive (SCSI) and IsoFile (file-backed).
-//! Used by UDF parser, disc scanner, label parsers — anything that
-//! reads sectors doesn't need to know where they come from.
-
-use crate::error::Result;
-
-/// Read 2048-byte sectors from a disc or disc image.
-pub trait SectorReader: Send {
-    /// Read `count` sectors starting at `lba` into `buf`.
-    /// `buf` must be at least `count * 2048` bytes.
-    /// `recovery`: true = full retry/reset loop (ripping), false = single attempt (verify).
-    /// File-backed readers ignore the flag.
-    fn read_sectors(
-        &mut self,
-        lba: u32,
-        count: u16,
-        buf: &mut [u8],
-        recovery: bool,
-    ) -> Result<usize>;
-
-    /// Total capacity in sectors, if known.
-    fn capacity(&self) -> u32 {
-        0
-    }
-
-    fn set_speed(&mut self, _kbs: u16) {}
-}
-
-/// SectorReader backed by a file (ISO image).
-/// Seeks to lba * 2048, reads count * 2048 bytes.
-pub struct FileSectorReader {
-    file: std::io::BufReader<std::fs::File>,
-    capacity: u32,
-}
-
-impl FileSectorReader {
-    pub fn open(path: &str) -> std::io::Result<Self> {
-        let file = std::fs::File::open(path)?;
-        let len = file.metadata()?.len();
-        let sectors = len / 2048;
-        if sectors > u32::MAX as u64 {
-            // ~8 TB hard cap (u32::MAX × 2048 bytes). Path lives in the
-            // typed Error variant — no English in the message.
-            return Err(crate::error::Error::IsoTooLarge {
-                path: path.to_string(),
-            }
-            .into());
-        }
-        let capacity = sectors as u32;
-        Ok(Self {
-            file: std::io::BufReader::with_capacity(4 * 1024 * 1024, file),
-            capacity,
-        })
-    }
-}
-
-impl SectorReader for FileSectorReader {
-    fn read_sectors(
-        &mut self,
-        lba: u32,
-        count: u16,
-        buf: &mut [u8],
-        _recovery: bool,
-    ) -> Result<usize> {
-        use std::io::{Read, Seek, SeekFrom};
-        let offset = lba as u64 * 2048;
-        let bytes = count as usize * 2048;
-        self.file
-            .seek(SeekFrom::Start(offset))
-            .map_err(|e| crate::error::Error::IoError { source: e })?;
-        self.file
-            .read_exact(&mut buf[..bytes])
-            .map_err(|e| crate::error::Error::IoError { source: e })?;
-        Ok(bytes)
-    }
-
-    fn capacity(&self) -> u32 {
-        self.capacity
-    }
-}
@@ -0,0 +1,200 @@
+//! `DecryptingSectorSource` — wrap any [`SectorSource`] to apply
+//! AACS / CSS in-place decryption on every read.
+//!
+//! This is the 0.18 single-source-of-truth for decrypt-on-read. The
+//! actual cipher code lives in [`crate::aacs`] and [`crate::css`];
+//! we just call the existing [`crate::decrypt::decrypt_sectors`]
+//! helper that already drives both of them. In follow-up commits
+//! `sweep_pipeline` and `DiscStream` migrate onto this decorator
+//! and delete their duplicate decrypt call sites.
+//!
+//! Composition: `Drive` → `DecryptingSectorSource` → caller sees
+//! plaintext. For `DecryptKeys::None` discs the decorator is a
+//! pass-through, so callers can wire it unconditionally and keep
+//! their pipeline shape uniform regardless of encryption state.
+
+use crate::decrypt::{DecryptKeys, decrypt_sectors};
+use crate::error::Result;
+
+use super::SectorSource;
+
+/// Decorator: read from `inner`, then run the configured
+/// AACS / CSS decrypt over the bytes that landed in `buf`.
+///
+/// `unit_key_idx` selects the AACS unit key for the disc (0 for
+/// the vast majority of titles; the rare multi-CPS-unit discs pick
+/// the index that covers the title being read). For
+/// [`DecryptKeys::None`] and [`DecryptKeys::Css`] the index is
+/// ignored.
+pub struct DecryptingSectorSource<S: SectorSource> {
+    inner: S,
+    keys: DecryptKeys,
+    unit_key_idx: usize,
+}
+
+impl<S: SectorSource> DecryptingSectorSource<S> {
+    /// Wrap `inner` with the given keys. The default unit-key
+    /// index is 0; use [`with_unit_key_idx`] for the multi-CPS-unit
+    /// case.
+    ///
+    /// [`with_unit_key_idx`]: Self::with_unit_key_idx
+    pub fn new(inner: S, keys: DecryptKeys) -> Self {
+        Self {
+            inner,
+            keys,
+            unit_key_idx: 0,
+        }
+    }
+
+    /// Override the AACS unit-key index. Only meaningful for
+    /// [`DecryptKeys::Aacs`]; other variants ignore it.
+    pub fn with_unit_key_idx(mut self, idx: usize) -> Self {
+        self.unit_key_idx = idx;
+        self
+    }
+
+    /// Replace the configured keys without unwrapping the decorator.
+    /// Used by `DiscStream::set_raw()` to flip from encrypted-disc
+    /// decryption to a pass-through after the inner reader is already
+    /// owned by the wrapper. For new construction prefer [`new`].
+    ///
+    /// [`new`]: Self::new
+    pub fn set_keys(&mut self, keys: DecryptKeys) {
+        self.keys = keys;
+    }
+
+    /// Borrow the inner source. Useful for tests and for adapters
+    /// that want to introspect the underlying drive / file without
+    /// unwrapping the decorator.
+    pub fn inner(&self) -> &S {
+        &self.inner
+    }
+
+    /// Mutable borrow of the inner source.
+    pub fn inner_mut(&mut self) -> &mut S {
+        &mut self.inner
+    }
+
+    /// Consume the decorator and return the underlying source.
+    pub fn into_inner(self) -> S {
+        self.inner
+    }
+}
+
+impl<S: SectorSource> SectorSource for DecryptingSectorSource<S> {
+    fn capacity_sectors(&self) -> u32 {
+        self.inner.capacity_sectors()
+    }
+
+    fn read_sectors(
+        &mut self,
+        lba: u32,
+        count: u16,
+        buf: &mut [u8],
+        recovery: bool,
+    ) -> Result<usize> {
+        let n = self.inner.read_sectors(lba, count, buf, recovery)?;
+        // Reuse the existing crate-wide decrypt entry point — same
+        // path the 0.17 sweep_pipeline and DiscStream call, so we
+        // inherit their AACS / CSS / None semantics verbatim. The
+        // helper is a no-op for DecryptKeys::None.
+        decrypt_sectors(&mut buf[..n], &self.keys, self.unit_key_idx)?;
+        Ok(n)
+    }
+
+    fn set_speed(&mut self, kbs: u16) {
+        self.inner.set_speed(kbs)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::error::Result;
+
+    /// Synthetic SectorSource that yields a deterministic byte
+    /// pattern keyed by LBA. Used to verify the decorator's
+    /// pass-through behaviour for `DecryptKeys::None`.
+    struct PatternedSource {
+        capacity: u32,
+    }
+
+    impl PatternedSource {
+        fn fill(lba: u32, count: u16, buf: &mut [u8]) {
+            let bytes = count as usize * 2048;
+            for (i, slot) in buf[..bytes].iter_mut().enumerate() {
+                let abs = lba as u64 * 2048 + i as u64;
+                *slot = ((abs.wrapping_mul(2654435761) >> 16) & 0xff) as u8;
+            }
+        }
+    }
+
+    impl SectorSource for PatternedSource {
+        fn capacity_sectors(&self) -> u32 {
+            self.capacity
+        }
+
+        fn read_sectors(
+            &mut self,
+            lba: u32,
+            count: u16,
+            buf: &mut [u8],
+            _recovery: bool,
+        ) -> Result<usize> {
+            Self::fill(lba, count, buf);
+            Ok(count as usize * 2048)
+        }
+    }
+
+    #[test]
+    fn passthrough_with_no_keys() {
+        let src = PatternedSource { capacity: 16 };
+        let mut wrapped = DecryptingSectorSource::new(src, DecryptKeys::None);
+
+        // capacity_sectors delegates.
+        assert_eq!(wrapped.capacity_sectors(), 16);
+
+        let mut got = vec![0u8; 4 * 2048];
+        let n = wrapped.read_sectors(3, 4, &mut got, false).unwrap();
+        assert_eq!(n, 4 * 2048);
+
+        let mut expected = vec![0u8; 4 * 2048];
+        PatternedSource::fill(3, 4, &mut expected);
+        assert_eq!(got, expected);
+    }
+
+    #[test]
+    fn passthrough_set_speed_delegates() {
+        struct SpeedRecorder {
+            last: Option<u16>,
+        }
+        impl SectorSource for SpeedRecorder {
+            fn capacity_sectors(&self) -> u32 {
+                0
+            }
+            fn read_sectors(
+                &mut self,
+                _lba: u32,
+                _count: u16,
+                _buf: &mut [u8],
+                _recovery: bool,
+            ) -> Result<usize> {
+                Ok(0)
+            }
+            fn set_speed(&mut self, kbs: u16) {
+                self.last = Some(kbs);
+            }
+        }
+
+        let mut wrapped =
+            DecryptingSectorSource::new(SpeedRecorder { last: None }, DecryptKeys::None);
+        wrapped.set_speed(7200);
+        assert_eq!(wrapped.inner().last, Some(7200));
+    }
+
+    // TODO: AACS round-trip test — needs a fixture-encrypted unit
+    // (6144-byte aligned) plus the matching unit key. The cipher
+    // path itself is exercised by `crate::aacs` unit tests; here
+    // we only assert the decorator wires the existing helper, not
+    // that AES-128 is correct.
+}
@@ -0,0 +1,308 @@
+//! File-backed sector I/O — read and write 2048-byte sectors against
+//! an ISO image on disk.
+//!
+//! [`FileSectorSource`] is the read side (open-only). [`FileSectorSink`]
+//! is the write side (create or open-rw); writes go through
+//! [`crate::io::WritebackFile`] so big sequential ISO writes share
+//! the same bounded-cache writeback pipeline used by sweep / patch /
+//! mux.
+
+use std::fs::{File, OpenOptions};
+use std::io::{Read, Seek, SeekFrom, Write};
+use std::path::Path;
+
+use crate::error::{Error, Result};
+
+use super::{SectorSink, SectorSource};
+
+/// Bytes-read threshold per `posix_fadvise(DONTNEED)` drop on the
+/// read side. Mirrors the writeback chunk size so the read-side
+/// page cache stays bounded the same way the write side does.
+#[cfg(target_os = "linux")]
+const READ_DROP_CHUNK_BYTES: u64 = 32 * 1024 * 1024;
+
+/// SectorSource backed by a file (ISO image).
+///
+/// Seeks to `lba * 2048`, reads `count * 2048` bytes per call. The
+/// file is held directly: every `read_sectors` call performs an
+/// absolute seek, so a wrapping `BufReader` would have its buffer
+/// invalidated on every call (its internal cursor moves with the
+/// `Seek` impl) — pure overhead. Callers that benefit from buffered
+/// reads should compose their own `BufReader` at the `read_sectors`
+/// granularity they care about.
+pub struct FileSectorSource {
+    file: File,
+    capacity: u32,
+    /// Bytes read since the last `posix_fadvise(DONTNEED)` drop.
+    /// Only updated on Linux; on other targets it stays at 0.
+    #[cfg(target_os = "linux")]
+    bytes_read_since_drop: u64,
+    /// Byte offset at which the current drop window starts (the
+    /// next `posix_fadvise(DONTNEED)` call drops from here).
+    #[cfg(target_os = "linux")]
+    drop_window_start: u64,
+}
+
+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).
+    pub fn open(path: &Path) -> std::io::Result<Self> {
+        let file = File::open(path)?;
+        let len = file.metadata()?.len();
+        let sectors = len / 2048;
+        if sectors > u32::MAX as u64 {
+            return Err(Error::IsoTooLarge {
+                path: path.to_string_lossy().into_owned(),
+            }
+            .into());
+        }
+        let capacity = sectors as u32;
+
+        // Hint sequential access on Linux so the kernel's readahead
+        // window widens for the ISO sweep. Best-effort: return value
+        // is ignored. On macOS / Windows this is a no-op.
+        #[cfg(target_os = "linux")]
+        {
+            use std::os::unix::io::AsRawFd;
+            unsafe {
+                libc::posix_fadvise(file.as_raw_fd(), 0, 0, libc::POSIX_FADV_SEQUENTIAL);
+            }
+        }
+
+        Ok(Self {
+            file,
+            capacity,
+            #[cfg(target_os = "linux")]
+            bytes_read_since_drop: 0,
+            #[cfg(target_os = "linux")]
+            drop_window_start: 0,
+        })
+    }
+}
+
+// Implement the legacy `SectorSource` trait. The blanket impl in
+// `super` produces the `SectorSource` impl automatically — no need
+// to write both, and writing both would conflict. This keeps the
+// 0.17 method-resolution path intact (callers with `SectorSource`
+// in scope can still write `fsr.read_sectors(..)` against a
+// `FileSectorSource`).
+impl SectorSource for FileSectorSource {
+    fn capacity_sectors(&self) -> u32 {
+        self.capacity
+    }
+
+    fn read_sectors(
+        &mut self,
+        lba: u32,
+        count: u16,
+        buf: &mut [u8],
+        _recovery: bool,
+    ) -> Result<usize> {
+        let offset = lba as u64 * 2048;
+        let bytes = count as usize * 2048;
+        self.file
+            .seek(SeekFrom::Start(offset))
+            .map_err(|e| Error::IoError { source: e })?;
+        self.file
+            .read_exact(&mut buf[..bytes])
+            .map_err(|e| Error::IoError { source: e })?;
+
+        // On Linux, periodically drop the just-read region from the
+        // page cache to keep cache pressure bounded during multi-GB
+        // sequential ISO reads. Mirrors the write-side pipeline.
+        #[cfg(target_os = "linux")]
+        {
+            use std::os::unix::io::AsRawFd;
+            self.bytes_read_since_drop += bytes as u64;
+            if self.bytes_read_since_drop >= READ_DROP_CHUNK_BYTES {
+                let drop_start = self.drop_window_start;
+                let drop_len = self.bytes_read_since_drop;
+                let t0 = std::time::Instant::now();
+                unsafe {
+                    libc::posix_fadvise(
+                        self.file.as_raw_fd(),
+                        drop_start as i64,
+                        drop_len as i64,
+                        libc::POSIX_FADV_DONTNEED,
+                    );
+                }
+                let elapsed_ms = t0.elapsed().as_millis();
+                let start_lba = drop_start / 2048;
+                let end_lba = (drop_start + drop_len) / 2048;
+                tracing::trace!(
+                    target: "mux",
+                    "FileSectorSource fadvise DONTNEED lba=[{start_lba}..{end_lba}) bytes={drop_len} elapsed_ms={elapsed_ms}"
+                );
+                self.drop_window_start = drop_start + drop_len;
+                self.bytes_read_since_drop = 0;
+            }
+        }
+
+        Ok(bytes)
+    }
+}
+
+/// SectorSink backed by a file (ISO image).
+///
+/// Writes go through [`crate::io::WritebackFile`], which on Linux drives
+/// continuous `sync_file_range` + `posix_fadvise(DONTNEED)` to keep
+/// the kernel dirty page cache bounded during multi-GB sequential
+/// writes. macOS / Windows fall through to a no-op pipeline.
+///
+/// `finish` runs `sync_all` before dropping the underlying file.
+pub struct FileSectorSink {
+    inner: crate::io::WritebackFile,
+}
+
+impl FileSectorSink {
+    /// Create a new ISO file at `path`, truncating any existing
+    /// file. The file is opened read-write so the same handle can
+    /// later be reused for verification reads if needed (sweep
+    /// doesn't, but it costs nothing here).
+    pub fn create(path: &Path) -> std::io::Result<Self> {
+        let file = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .create(true)
+            .truncate(true)
+            .open(path)?;
+        Ok(Self {
+            inner: crate::io::WritebackFile::new(file)?,
+        })
+    }
+
+    /// Open an existing ISO file for in-place updates (e.g. patch
+    /// pass writing recovered sectors over zero-filled holes).
+    /// Does not truncate.
+    pub fn open(path: &Path) -> std::io::Result<Self> {
+        let file = OpenOptions::new().read(true).write(true).open(path)?;
+        Ok(Self {
+            inner: crate::io::WritebackFile::new(file)?,
+        })
+    }
+}
+
+impl SectorSink for FileSectorSink {
+    fn write_sectors(&mut self, lba: u32, buf: &[u8]) -> Result<()> {
+        debug_assert!(
+            buf.len() % 2048 == 0,
+            "FileSectorSink::write_sectors: buf len {} not a multiple of 2048",
+            buf.len()
+        );
+        let offset = lba as u64 * 2048;
+        self.inner
+            .seek(SeekFrom::Start(offset))
+            .map_err(|e| Error::IoError { source: e })?;
+        self.inner
+            .write_all(buf)
+            .map_err(|e| Error::IoError { source: e })?;
+        Ok(())
+    }
+
+    fn finish(mut self: Box<Self>) -> Result<()> {
+        self.inner
+            .sync_all()
+            .map_err(|e| Error::IoError { source: e })?;
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    // Bring the 0.18 trait into scope (not super::*: the super
+    // module also re-exports the legacy `SectorSource`, and
+    // having both `SectorSource::read_sectors` and
+    // `SectorSource::read_sectors` visible would force every
+    // call site to disambiguate). External consumers see the
+    // same surface this test exercises.
+    use super::{FileSectorSink, FileSectorSource};
+    use crate::sector::{SectorSink, SectorSource};
+    use tempfile::tempdir;
+
+    #[test]
+    fn round_trip_single_sector() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("rt.iso");
+
+        let mut sink = FileSectorSink::create(&path).unwrap();
+        // Pre-extend the file to 4 sectors of zeros so we can write
+        // sector 2 in place. Easiest way: write zeros first.
+        let zeros = [0u8; 4 * 2048];
+        sink.write_sectors(0, &zeros).unwrap();
+
+        let mut payload = [0u8; 2048];
+        for (i, b) in payload.iter_mut().enumerate() {
+            *b = (i as u8).wrapping_mul(17);
+        }
+        sink.write_sectors(2, &payload).unwrap();
+        Box::new(sink).finish().unwrap();
+
+        let mut src = FileSectorSource::open(&path).unwrap();
+        assert_eq!(src.capacity_sectors(), 4);
+
+        let mut got = [0u8; 2048];
+        let n = src.read_sectors(2, 1, &mut got, false).unwrap();
+        assert_eq!(n, 2048);
+        assert_eq!(got, payload);
+
+        // Sectors 0,1,3 still zero.
+        let mut z = [0xffu8; 2048];
+        src.read_sectors(0, 1, &mut z, false).unwrap();
+        assert!(z.iter().all(|b| *b == 0));
+    }
+
+    #[test]
+    fn round_trip_multi_sector() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("multi.iso");
+
+        let mut sink = FileSectorSink::create(&path).unwrap();
+        let mut payload = vec![0u8; 8 * 2048];
+        for (i, b) in payload.iter_mut().enumerate() {
+            *b = ((i * 31) ^ (i >> 7)) as u8;
+        }
+        sink.write_sectors(0, &payload).unwrap();
+        Box::new(sink).finish().unwrap();
+
+        let mut src = FileSectorSource::open(&path).unwrap();
+        assert_eq!(src.capacity_sectors(), 8);
+
+        let mut got = vec![0u8; 8 * 2048];
+        let n = src.read_sectors(0, 8, &mut got, false).unwrap();
+        assert_eq!(n, 8 * 2048);
+        assert_eq!(got, payload);
+    }
+
+    #[test]
+    fn open_existing_does_not_truncate() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("open.iso");
+
+        // Create with 4 sectors of pattern A.
+        let mut sink = FileSectorSink::create(&path).unwrap();
+        let pat_a = [0xaau8; 4 * 2048];
+        sink.write_sectors(0, &pat_a).unwrap();
+        Box::new(sink).finish().unwrap();
+
+        // Reopen and overwrite sector 1 only.
+        let mut sink = FileSectorSink::open(&path).unwrap();
+        let pat_b = [0xbbu8; 2048];
+        sink.write_sectors(1, &pat_b).unwrap();
+        Box::new(sink).finish().unwrap();
+
+        let mut src = FileSectorSource::open(&path).unwrap();
+        assert_eq!(src.capacity_sectors(), 4);
+        let mut got = [0u8; 2048];
+
+        src.read_sectors(0, 1, &mut got, false).unwrap();
+        assert_eq!(got, [0xaau8; 2048]);
+
+        src.read_sectors(1, 1, &mut got, false).unwrap();
+        assert_eq!(got, [0xbbu8; 2048]);
+
+        src.read_sectors(2, 1, &mut got, false).unwrap();
+        assert_eq!(got, [0xaau8; 2048]);
+    }
+}
@@ -0,0 +1,113 @@
+//! Sector-level I/O traits.
+//!
+//! The sector layer is direction-typed: [`SectorSource`] reads
+//! 2048-byte sectors, [`SectorSink`] writes them. Concrete impls
+//! never do both — physical drives are read-only, file-backed
+//! ISO images are opened for read OR write at construction time.
+//!
+//! - [`SectorSource`] is implemented by `Drive` (hardware) and
+//!   [`FileSectorSource`] / `IsoSectorReader` (file-backed).
+//! - [`SectorSink`] is implemented by [`FileSectorSink`]
+//!   (ISO-backed) and sweep/patch consumer adapters.
+//! - [`DecryptingSectorSource`] is a decorator that wraps any
+//!   `SectorSource` and applies AACS / CSS in-place decrypt to
+//!   yield plaintext sectors.
+
+pub mod decrypting;
+pub mod file;
+
+use crate::error::Result;
+
+/// Read 2048-byte sectors from a disc, image, or composed source.
+///
+/// Wrap the inner source in [`DecryptingSectorSource`] to get
+/// plaintext sectors out of an encrypted disc.
+pub trait SectorSource: Send {
+    /// Total capacity in sectors, if known. Default `0` = unknown
+    /// (e.g. live drives that haven't completed `READ CAPACITY` yet).
+    fn capacity_sectors(&self) -> u32 {
+        0
+    }
+
+    /// Read `count` sectors starting at `lba` into `buf`.
+    /// `buf` must be at least `count * 2048` bytes.
+    /// `recovery`: true = full retry/reset loop (ripping),
+    /// false = single attempt (verify). File-backed sources ignore
+    /// the flag.
+    ///
+    /// Returns the number of bytes written into `buf` on success.
+    fn read_sectors(
+        &mut self,
+        lba: u32,
+        count: u16,
+        buf: &mut [u8],
+        recovery: bool,
+    ) -> Result<usize>;
+
+    /// Optional speed control for sources that map to a physical
+    /// drive. No-op for everything else.
+    fn set_speed(&mut self, _kbs: u16) {}
+}
+
+// Forwarding impls so `Box<dyn SectorSource>` and `&mut dyn SectorSource`
+// satisfy the `SectorSource` trait bound when wrapped by generic
+// decorators like `DecryptingSectorSource<S: SectorSource>`.
+impl SectorSource for Box<dyn SectorSource> {
+    fn capacity_sectors(&self) -> u32 {
+        (**self).capacity_sectors()
+    }
+
+    fn read_sectors(
+        &mut self,
+        lba: u32,
+        count: u16,
+        buf: &mut [u8],
+        recovery: bool,
+    ) -> Result<usize> {
+        (**self).read_sectors(lba, count, buf, recovery)
+    }
+
+    fn set_speed(&mut self, kbs: u16) {
+        (**self).set_speed(kbs)
+    }
+}
+
+impl SectorSource for &mut (dyn SectorSource + '_) {
+    fn capacity_sectors(&self) -> u32 {
+        (**self).capacity_sectors()
+    }
+
+    fn read_sectors(
+        &mut self,
+        lba: u32,
+        count: u16,
+        buf: &mut [u8],
+        recovery: bool,
+    ) -> Result<usize> {
+        (**self).read_sectors(lba, count, buf, recovery)
+    }
+
+    fn set_speed(&mut self, kbs: u16) {
+        (**self).set_speed(kbs)
+    }
+}
+
+/// Write 2048-byte sectors to a disc image or composed sink.
+///
+/// The terminal [`finish`] takes `Box<Self>` so it can run on `dyn
+/// SectorSink` and consume the sink (`fsync` + close).
+///
+/// [`finish`]: SectorSink::finish
+pub trait SectorSink: Send {
+    /// Write the sectors in `buf` starting at `lba`. `buf.len()`
+    /// must be a multiple of 2048; the implementation seeks to
+    /// `lba * 2048` before writing.
+    fn write_sectors(&mut self, lba: u32, buf: &[u8]) -> Result<()>;
+
+    /// Flush, fsync, and close. Consumes the sink. Always called
+    /// last; subsequent operations are not defined.
+    fn finish(self: Box<Self>) -> Result<()>;
+}
+
+pub use decrypting::DecryptingSectorSource;
+pub use file::{FileSectorSink, FileSectorSource};
@@ -19,7 +19,7 @@
 //!   BD-ROM Part 3 — Blu-ray filesystem profile

 use crate::error::{Error, Result};
-use crate::sector::SectorReader;
+use crate::sector::SectorSource;

 /// A UDF filesystem parsed from disc.
 #[derive(Debug)]
@@ -84,7 +84,7 @@ impl UdfFs {
    /// Reads sector by sector from disc — no buffering.
    /// Get the absolute starting LBA of a file on disc.
    /// Used by the rip pipeline to locate m2ts content sectors.
-    pub fn file_start_lba(&self, reader: &mut dyn SectorReader, path: &str) -> Result<u32> {
+    pub fn file_start_lba(&self, reader: &mut dyn SectorSource, path: &str) -> Result<u32> {
        let parts: Vec<&str> = path.trim_matches('/').split('/').collect();
        let mut current = &self.root;
        for part in &parts[..parts.len() - 1] {
@@ -115,7 +115,7 @@ impl UdfFs {
        Ok(self.partition_start + data_lba)
    }

-    pub fn read_file(&self, reader: &mut dyn SectorReader, path: &str) -> Result<Vec<u8>> {
+    pub fn read_file(&self, reader: &mut dyn SectorSource, path: &str) -> Result<Vec<u8>> {
        let parts: Vec<&str> = path.trim_matches('/').split('/').collect();
        let mut current = &self.root;

@@ -175,7 +175,7 @@ impl UdfFs {
    ///
    /// Skips: STREAM/ (video), BACKUP/, DUPLICATE/,
    ///   MKB_RO.inf, ContentHash*, ContentRevocation*
-    pub fn metadata_sector_ranges(&self, reader: &mut dyn SectorReader) -> Result<Vec<(u32, u32)>> {
+    pub fn metadata_sector_ranges(&self, reader: &mut dyn SectorSource) -> Result<Vec<(u32, u32)>> {
        let mut ranges = Vec::new();

        // UDF structure: sector 0 through end of metadata partition
@@ -194,7 +194,7 @@ impl UdfFs {

    /// All sector ranges that contain data (metadata + all files including STREAM).
    /// For full disc-to-ISO dumps — reads only allocated sectors, skips gaps.
-    pub fn all_sector_ranges(&self, reader: &mut dyn SectorReader) -> Result<Vec<(u32, u32)>> {
+    pub fn all_sector_ranges(&self, reader: &mut dyn SectorSource) -> Result<Vec<(u32, u32)>> {
        let mut ranges = Vec::new();

        // UDF structure sectors
@@ -212,7 +212,7 @@ impl UdfFs {

    fn collect_all_file_ranges(
        &self,
-        reader: &mut dyn SectorReader,
+        reader: &mut dyn SectorSource,
        entry: &DirEntry,
        ranges: &mut Vec<(u32, u32)>,
    ) -> Result<()> {
@@ -238,7 +238,7 @@ impl UdfFs {

    fn collect_file_ranges(
        &self,
-        reader: &mut dyn SectorReader,
+        reader: &mut dyn SectorSource,
        entry: &DirEntry,
        ranges: &mut Vec<(u32, u32)>,
    ) -> Result<()> {
@@ -276,7 +276,7 @@ impl UdfFs {
    /// Read an Extended File Entry (tag 266) or File Entry (tag 261)
    /// and return its first allocation extent: (data_lba, data_length).
    /// The data_lba is partition-relative.
-    fn read_icb_extent(&self, reader: &mut dyn SectorReader, meta_lba: u32) -> Result<(u32, u32)> {
+    fn read_icb_extent(&self, reader: &mut dyn SectorSource, meta_lba: u32) -> Result<(u32, u32)> {
        let extents = self.read_icb_extents(reader, meta_lba)?;
        extents.first().copied().ok_or(Error::DiscRead {
            sector: 0,
@@ -290,7 +290,7 @@ impl UdfFs {
    /// Handles files with many extents (e.g. 88 GB m2ts files have ~90 extents).
    fn read_icb_extents(
        &self,
-        reader: &mut dyn SectorReader,
+        reader: &mut dyn SectorSource,
        meta_lba: u32,
    ) -> Result<Vec<(u32, u32)>> {
        let mut icb = [0u8; 2048];
@@ -367,7 +367,7 @@ impl UdfFs {
    /// Returns Vec of (absolute_lba, sector_count) covering the entire file.
    pub fn file_extents(
        &self,
-        reader: &mut dyn SectorReader,
+        reader: &mut dyn SectorSource,
        path: &str,
    ) -> Result<Vec<(u32, u32)>> {
        let parts: Vec<&str> = path.trim_matches('/').split('/').collect();
@@ -417,7 +417,7 @@ impl UdfFs {
 /// 3. Metadata partition file → metadata content location
 /// 4. FSD → root directory ICB
 /// 5. Root directory → file tree
-pub fn read_filesystem(reader: &mut dyn SectorReader) -> Result<UdfFs> {
+pub fn read_filesystem(reader: &mut dyn SectorSource) -> Result<UdfFs> {
    // Step 1: Anchor Volume Descriptor Pointer at sector 256
    // ECMA-167 §10.2 — always at sector 256
    let mut avdp = [0u8; 2048];
@@ -593,7 +593,7 @@ pub fn read_filesystem(reader: &mut dyn SectorReader) -> Result<UdfFs> {
 /// and points to its ICB.
 #[allow(clippy::only_used_in_recursion)]
 fn read_directory(
-    reader: &mut dyn SectorReader,
+    reader: &mut dyn SectorSource,
    part_start: u32,
    meta_start: u32,
    meta_lba: u32,
@@ -758,7 +758,7 @@ fn read_directory(
 }

 /// Read file size (info_length) from an Extended File Entry ICB.
-fn read_file_size(reader: &mut dyn SectorReader, meta_start: u32, meta_lba: u32) -> Result<u64> {
+fn read_file_size(reader: &mut dyn SectorSource, meta_start: u32, meta_lba: u32) -> Result<u64> {
    let mut icb = [0u8; 2048];
    read_sector(reader, meta_start + meta_lba, &mut icb)?;

@@ -874,7 +874,7 @@ fn parse_dstring(data: &[u8]) -> String {
 /// Each SCSI command has ~500ms overhead on USB drives, so reading 32 sectors
 /// at once (one command) is 32x faster than 32 individual reads.
 pub(crate) struct BufferedSectorReader<'a> {
-    inner: &'a mut dyn SectorReader,
+    inner: &'a mut dyn SectorSource,
    cache_start: u32,
    cache: Vec<u8>,
    cache_sectors: u32,
@@ -884,7 +884,7 @@ pub(crate) struct BufferedSectorReader<'a> {
 }

 impl<'a> BufferedSectorReader<'a> {
-    pub(crate) fn new(inner: &'a mut dyn SectorReader, batch: u16) -> Self {
+    pub(crate) fn new(inner: &'a mut dyn SectorSource, batch: u16) -> Self {
        Self {
            inner,
            cache_start: u32::MAX,
@@ -952,7 +952,7 @@ impl BufferedSectorReader<'_> {
    }
 }

-impl SectorReader for BufferedSectorReader<'_> {
+impl SectorSource for BufferedSectorReader<'_> {
    fn read_sectors(
        &mut self,
        lba: u32,
@@ -996,7 +996,7 @@ impl SectorReader for BufferedSectorReader<'_> {
    }
 }

-fn read_sector(reader: &mut dyn SectorReader, lba: u32, buf: &mut [u8]) -> Result<()> {
+fn read_sector(reader: &mut dyn SectorSource, lba: u32, buf: &mut [u8]) -> Result<()> {
    reader.read_sectors(lba, 1, buf, true)?;
    Ok(())
 }
@@ -2,7 +2,7 @@

 use crate::disc::{Chapter, DiscTitle};
 use crate::progress::Progress;
-use crate::sector::SectorReader;
+use crate::sector::SectorSource;
 use std::time::Instant;

 /// Health status of a single sector read.
@@ -82,7 +82,7 @@ impl VerifyResult {
 /// Reads in batches for speed, falls back to single-sector on failure.
 /// The progress callback returns false to request early stop.
 pub fn verify_title(
-    reader: &mut dyn SectorReader,
+    reader: &mut dyn SectorSource,
    title: &DiscTitle,
    batch_sectors: u16,
    on_progress: Option<&dyn Progress>,
@@ -1,6 +1,6 @@
 //! Disc scanning pipeline tests.

-use libfreemkv::SectorReader;
+use libfreemkv::SectorSource;
 use libfreemkv::error::Result;
 use libfreemkv::{Disc, DiscTitle, ScanOptions};
 use std::collections::HashMap;
@@ -20,7 +20,7 @@ impl MockSectorReader {
    }
 }

-impl SectorReader for MockSectorReader {
+impl SectorSource for MockSectorReader {
    fn read_sectors(
        &mut self,
        lba: u32,
@@ -5,8 +5,8 @@ use libfreemkv::disc::{CopyOptions, DiscRegion};
 use libfreemkv::error::Result;
 use libfreemkv::pes::Stream as PesStream;
 use libfreemkv::{
-    ContentFormat, Disc, DiscFormat, DiscStream, DiscTitle, EventKind, Extent, FileSectorReader,
-    SectorReader,
+    ContentFormat, Disc, DiscFormat, DiscStream, DiscTitle, EventKind, Extent, FileSectorSource,
+    SectorSource,
 };
 use std::io::Write;
 use std::sync::Arc;
@@ -32,7 +32,7 @@ impl ZeroSectorReader {
    }
 }

-impl SectorReader for ZeroSectorReader {
+impl SectorSource for ZeroSectorReader {
    fn read_sectors(
        &mut self,
        _lba: u32,
@@ -46,7 +46,7 @@ impl SectorReader for ZeroSectorReader {
        Ok(bytes)
    }

-    fn capacity(&self) -> u32 {
+    fn capacity_sectors(&self) -> u32 {
        self.capacity
    }
 }
@@ -67,7 +67,7 @@ impl SlowZeroSectorReader {
    }
 }

-impl SectorReader for SlowZeroSectorReader {
+impl SectorSource for SlowZeroSectorReader {
    fn read_sectors(
        &mut self,
        _lba: u32,
@@ -81,7 +81,7 @@ impl SectorReader for SlowZeroSectorReader {
        Ok(bytes)
    }

-    fn capacity(&self) -> u32 {
+    fn capacity_sectors(&self) -> u32 {
        self.capacity
    }
 }
@@ -101,6 +101,7 @@ fn synthetic_disc(capacity_sectors: u32) -> Disc {
        aacs: None,
        css: None,
        encrypted: false,
+        aacs_error: None,
        content_format: ContentFormat::BdTs,
    }
 }
@@ -303,7 +304,7 @@ fn test_drop_impls_do_not_panic_or_block() {
    panic!("DiscStream drop did not complete within 100ms");
 }

-// ── 5. FileSectorReader round trip ────────────────────────────────────────
+// ── 5. FileSectorSource round trip ────────────────────────────────────────

 #[test]
 fn test_file_sector_reader_round_trip() {
@@ -319,10 +320,14 @@ fn test_file_sector_reader_round_trip() {
    tmp.write_all(&data).expect("write data");
    tmp.flush().expect("flush");

-    let path = tmp.path().to_str().expect("path utf-8").to_string();
-    let mut fsr = FileSectorReader::open(&path).expect("open FileSectorReader");
+    let path = tmp.path().to_path_buf();
+    let mut fsr = FileSectorSource::open(&path).expect("open FileSectorSource");

-    assert_eq!(fsr.capacity(), N_SECTORS as u32, "capacity mismatch");
+    assert_eq!(
+        fsr.capacity_sectors(),
+        N_SECTORS as u32,
+        "capacity mismatch"
+    );

    // Read each sector individually and compare.
    let mut buf = vec![0u8; SECTOR_SIZE];
@@ -390,7 +395,7 @@ impl FailingSectorReader {
    }
 }

-impl SectorReader for FailingSectorReader {
+impl SectorSource for FailingSectorReader {
    fn read_sectors(
        &mut self,
        _lba: u32,
@@ -417,7 +422,7 @@ impl SectorReader for FailingSectorReader {
        })
    }

-    fn capacity(&self) -> u32 {
+    fn capacity_sectors(&self) -> u32 {
        self.capacity
    }
 }
@@ -454,11 +459,17 @@ fn test_disc_copy_completes_full_disc_with_failing_reader() {
    let _ = std::fs::remove_file(&iso_path);
    let _ = std::fs::remove_file(libfreemkv::disc::mapfile_path_for(&iso_path));

-    // Hard bound — even at 0 ms per read, 1024 sectors with skip-forward
-    // should complete in well under a second on any host.
+    // Hard bound — Pass 1 must NOT infinite-loop on a fully-failing
+    // reader. The threshold accommodates the 2026-05-10 wedge-
+    // avoidance pause (PASS_1_FAIL_PAUSE_SECS = 5 s on each failed
+    // batch). With batch=32 and 1024 sectors that's up to ~5 batch
+    // failures + a few damage-jump pauses before fast-trigger jumps
+    // us past end-of-disc — well-bounded total, ~20-30 s typical.
+    // The point of this test is "finishes cleanly, not infinitely",
+    // not "completes in milliseconds."
    assert!(
-        elapsed < Duration::from_secs(5),
-        "Pass 1 took {elapsed:?} on a 2 MB synthetic disc — expected < 5 s"
+        elapsed < Duration::from_secs(60),
+        "Pass 1 took {elapsed:?} on a 2 MB synthetic disc — expected < 60 s (not infinite)"
    );

    // Per RIP_DESIGN.md §2.1: Pass 1 must reach end of disc regardless of
@@ -560,7 +571,7 @@ struct BlockSizeFailingReader {
    capacity: u32,
 }

-impl SectorReader for BlockSizeFailingReader {
+impl SectorSource for BlockSizeFailingReader {
    fn read_sectors(
        &mut self,
        lba: u32,
@@ -586,7 +597,7 @@ impl SectorReader for BlockSizeFailingReader {
        }
    }

-    fn capacity(&self) -> u32 {
+    fn capacity_sectors(&self) -> u32 {
        self.capacity
    }
 }
@@ -619,29 +630,41 @@ fn test_disc_copy_marks_failed_ecc_blocks_as_nontrimmed() {
    let _ = std::fs::remove_file(&iso_path);
    let _ = std::fs::remove_file(libfreemkv::disc::mapfile_path_for(&iso_path));

-    // Pass 1 reads every batch at bpt=32 (no batch reduction, no skip-ahead).
-    // BlockSizeFailingReader fails on multi-sector reads but succeeds on single-sector.
-    // Bridge degradation handling retries failed batches as individual sectors,
-    // so all data is recovered as Finished. bytes_good == total_bytes is correct.
+    // Pass 1's job is "fast and accurate, get the most data in the
+    // shortest time." It no longer bisects on marginal media — that's
+    // Pass N's purpose-built role. So a BlockSizeFailingReader that
+    // fails on multi-sector reads and succeeds on single-sector
+    // results in: every batch fails → SkipBlock → whole 32-sector
+    // ECC block marked NonTrimmed → Pass N (Disc::patch) revisits and
+    // recovers via single-sector reads with proper recovery semantics.
+    //
+    // Pass 1 alone:
    assert_eq!(
-        result.bytes_good, total_bytes,
-        "Pass 1 at bpt=32 recovers all sectors via single-sector retry on MEDIUM_ERROR"
+        result.bytes_good, 0,
+        "Pass 1 doesn't bisect on marginal media — failed batches become NonTrimmed for Pass N to revisit"
    );
    assert_eq!(
-        result.bytes_pending, 0,
-        "no pending sectors after full recovery"
+        result.bytes_pending, total_bytes,
+        "every sector is NonTrimmed (pending) after Pass 1, awaiting Pass N"
+    );
+    assert!(
+        !result.complete,
+        "complete=false because NonTrimmed regions remain (Pass N's work)"
    );
-    assert!(result.complete, "complete=true when all sectors recovered");
 }

 // ── 9. PassProgress carries separate unreadable vs pending byte counts ─────
 //
-// The video-damage-time display needs bytes_unreadable_total (confirmed dead)
-// separate from bytes_pending_total (might still recover). This test verifies
-// that a Pass 2 with some confirmed failures produces correct field values.
+// 2026-05-11 design call: Pass N never marks bytes as `Unreadable` mid-multipass —
+// failed reads stay `NonTrimmed` so the next pass can retry them. The orchestrator
+// (autorip) promotes still-NonTrimmed bytes to Unreadable after the FINAL retry
+// pass completes. This test was rewritten from its pre-design-call shape (which
+// asserted Pass 2 produced bytes_unreadable > 0) to verify the new invariant:
+// pass-level retries keep failed bytes in `bytes_pending` so subsequent passes
+// get more shots at them.

 #[test]
-fn test_pass_progress_separates_unreadable_from_pending() {
+fn test_pass2_leaves_failed_reads_as_pending_not_unreadable() {
    let capacity_sectors: u32 = 128;
    let total_bytes: u64 = capacity_sectors as u64 * SECTOR_SIZE as u64;

@@ -715,24 +738,30 @@ fn test_pass_progress_separates_unreadable_from_pending() {
        pass2.bytes_good, 0,
        "pass2: still no good sectors (reader always fails)"
    );
-    assert!(
-        pass2.bytes_unreadable > 0,
-        "pass2: some sectors confirmed unreadable"
+    // 2026-05-11 design: pass-level retries do NOT promote failed bytes
+    // to Unreadable. Failed bytes stay NonTrimmed (pending) so a later
+    // pass can retry. End-of-recovery promotion is an orchestrator
+    // concern (autorip), not the patch loop's.
+    assert_eq!(
+        pass2.bytes_unreadable, 0,
+        "pass2: Disc::patch never marks Unreadable mid-multipass — orchestrator promotes after final pass"
    );
-    assert!(
-        pass2.bytes_pending < pass1.bytes_pending,
-        "pass2: fewer pending sectors than pass1"
+    // bytes_pending stays at total_bytes because everything still
+    // failed and nothing got recovered or promoted out of pending.
+    assert_eq!(
+        pass2.bytes_pending, total_bytes,
+        "pass2: failed bytes remain NonTrimmed for the next pass to retry"
    );

    let observed_unreadable = last_unreadable.load(Ordering::Relaxed);
    let observed_pending = last_pending.load(Ordering::Relaxed);
-    assert!(
-        observed_unreadable > 0,
-        "progress should report confirmed unreadable bytes"
+    assert_eq!(
+        observed_unreadable, 0,
+        "progress should report zero confirmed-unreadable mid-pass under the new design"
    );
    assert!(
-        observed_pending == 0 || observed_pending < total_bytes,
-        "pending should shrink as sectors are confirmed unreadable"
+        observed_pending > 0,
+        "progress should report pending bytes as the reader keeps failing"
    );

    // Video damage time: unreadable / total * duration
@@ -15,7 +15,7 @@ use libfreemkv::disc::CopyOptions;
 use libfreemkv::disc::DiscRegion;
 use libfreemkv::disc::mapfile::{Mapfile, SectorStatus};
 use libfreemkv::error::Result;
-use libfreemkv::{ContentFormat, Disc, DiscFormat, SectorReader};
+use libfreemkv::{ContentFormat, Disc, DiscFormat, SectorSource};
 use std::collections::HashSet;
 use std::sync::{Arc, Mutex};

@@ -30,8 +30,10 @@ struct PatternedSectorReader {
    trace: Arc<Mutex<Vec<(u32, u16)>>>,
 }

+type ReadTrace = Arc<Mutex<Vec<(u32, u16)>>>;
+
 impl PatternedSectorReader {
-    fn new(capacity: u32, bad_lbas: HashSet<u32>) -> (Self, Arc<Mutex<Vec<(u32, u16)>>>) {
+    fn new(capacity: u32, bad_lbas: HashSet<u32>) -> (Self, ReadTrace) {
        let trace = Arc::new(Mutex::new(Vec::new()));
        (
            Self {
@@ -44,7 +46,7 @@ impl PatternedSectorReader {
    }
 }

-impl SectorReader for PatternedSectorReader {
+impl SectorSource for PatternedSectorReader {
    fn read_sectors(
        &mut self,
        lba: u32,
@@ -68,13 +70,19 @@ impl SectorReader for PatternedSectorReader {
                });
            }
        }
-        for chunk in buf.chunks_mut(SECTOR_SIZE) {
-            chunk.fill((lba & 0xff) as u8);
+        // Fill each sector with ITS OWN LBA byte, not the starting LBA's
+        // byte. This matches real drive behavior: a multi-sector READ
+        // returns per-sector-correct data. Pre-0.18.13 only single-sector
+        // reads were exercised by patch tests, so the cheaper "fill the
+        // whole batch with one byte" worked; adaptive batching needs the
+        // per-sector pattern to verify correct positioning.
+        for (i, chunk) in buf.chunks_mut(SECTOR_SIZE).enumerate() {
+            chunk.fill(((lba + i as u32) & 0xff) as u8);
        }
        Ok(buf.len())
    }

-    fn capacity(&self) -> u32 {
+    fn capacity_sectors(&self) -> u32 {
        self.capacity
    }
 }
@@ -92,6 +100,7 @@ fn synthetic_disc(capacity_sectors: u32) -> Disc {
        aacs: None,
        css: None,
        encrypted: false,
+        aacs_error: None,
        content_format: ContentFormat::BdTs,
    }
 }
@@ -286,3 +295,114 @@ fn patch_recovers_multiple_good_middles() {
        pr.bytes_total,
    );
 }
+
+/// 0.18 Pass N pipeline split: exercises the new producer/consumer
+/// path end-to-end on a synthetic patterned reader. Bad range layout
+/// is small (5 bad LBAs surrounded by good middle) so the producer
+/// emits a mix of `Recovered` and `Unreadable` items and the consumer
+/// thread must apply both kinds. Verifies:
+///
+/// - `bytes_good` advances (good sectors flow producer→consumer→file
+///   →mapfile with the data preserved).
+/// - The recovered LBAs end up Finished; the bad LBAs end up Unreadable.
+/// - Bytes written at the recovered offsets match what the producer
+///   read from the patterned source (proves the channel hand-off
+///   didn't drop or reorder buffers, and the consumer's seek+write
+///   landed at the right offsets).
+#[test]
+fn patch_pipeline_split_recovers_and_records_correctly() {
+    let capacity_sectors: u32 = 512;
+    let total_bytes: u64 = capacity_sectors as u64 * SECTOR_SIZE as u64;
+
+    // Layout: LBAs 200-204 inclusive are bad (5 sectors), 205-249 good.
+    // The pre-existing range is LBAs 200-249 NonTrimmed (100 KB).
+    let mut bad_lbas = HashSet::new();
+    for lba in 200..205 {
+        bad_lbas.insert(lba);
+    }
+
+    let (mut reader, _trace) = PatternedSectorReader::new(capacity_sectors, bad_lbas.clone());
+    let disc = synthetic_disc(capacity_sectors);
+
+    let tmp = tempfile::NamedTempFile::new().unwrap();
+    let iso_path = tmp.path().to_path_buf();
+    drop(tmp);
+
+    let finished = [
+        (0, 200 * 2048),
+        (250 * 2048, (capacity_sectors as u64 - 250) * 2048),
+    ];
+    let nontrimmed = [(200 * 2048, 50 * 2048)];
+    prep_iso_and_mapfile(&iso_path, total_bytes, &finished, &nontrimmed);
+
+    let opts = CopyOptions {
+        decrypt: false,
+        multipass: true,
+        ..Default::default()
+    };
+    let pr = disc
+        .copy(&mut reader, &iso_path, &opts)
+        .expect("copy returns Ok");
+
+    // Bytes_good_total should advance — the good LBAs in the bad range
+    // (205-249, 45 sectors) are all reachable via per-sector retry.
+    // Initial bytes_good = 200 * 2048 + (512-250) * 2048 = 462 sectors.
+    // After patch, bytes_good should be ≥ 462 + 45 = 507 sectors worth.
+    let initial_good_sectors: u64 = 200 + (capacity_sectors as u64 - 250);
+    let min_expected_good_bytes = (initial_good_sectors + 30) * 2048;
+    assert!(
+        pr.bytes_good >= min_expected_good_bytes,
+        "patch should have recovered most good LBAs in the bad range via the pipeline. \
+         bytes_good={} (expected ≥ {}); bytes_total={}",
+        pr.bytes_good,
+        min_expected_good_bytes,
+        pr.bytes_total,
+    );
+
+    // Verify the mapfile records: every good LBA is Finished, every
+    // bad LBA is either Unreadable or NonTrimmed (not Finished).
+    let map_path = libfreemkv::disc::mapfile_path_for(&iso_path);
+    let map = Mapfile::load(&map_path).unwrap();
+    let finished_ranges = map.ranges_with(&[SectorStatus::Finished]);
+    let in_finished = |lba: u32| -> bool {
+        let pos = lba as u64 * 2048;
+        finished_ranges
+            .iter()
+            .any(|&(p, sz)| pos >= p && pos < p + sz)
+    };
+
+    for lba in 205..250 {
+        assert!(
+            in_finished(lba),
+            "good LBA {lba} should be Finished after pipeline patch run"
+        );
+    }
+    for lba in 200..205 {
+        assert!(
+            !in_finished(lba),
+            "bad LBA {lba} should NOT be Finished after pipeline patch run"
+        );
+    }
+
+    // Verify the consumer wrote the producer's bytes at the right
+    // offsets. PatternedSectorReader fills each sector with `(lba & 0xff)
+    // as u8` — picking LBA 220 (well inside the recovered region) gives
+    // a clean signature byte to check.
+    use std::io::{Read, Seek, SeekFrom};
+    let mut iso = std::fs::File::open(&iso_path).unwrap();
+    iso.seek(SeekFrom::Start(220 * 2048)).unwrap();
+    let mut sector = [0u8; 2048];
+    iso.read_exact(&mut sector).unwrap();
+    let expected_byte = (220u32 & 0xff) as u8;
+
+    let _ = std::fs::remove_file(&iso_path);
+    let _ = std::fs::remove_file(&map_path);
+
+    assert!(
+        sector.iter().all(|&b| b == expected_byte),
+        "consumer should have written PatternedSectorReader's pattern \
+         (byte {expected_byte:#x} for LBA 220) to the recovered offset; \
+         got first 8 bytes = {:?}",
+        &sector[..8]
+    );
+}
@@ -0,0 +1,807 @@
+//! Pass-N (`Disc::patch`) read-error handler — A/B golden fixture.
+//!
+//! Background (2026-05-13, v0.20.8 release bundle planning):
+//!
+//! `libfreemkv::disc::read_error::handle_read_error` is supposed to be
+//! the single source of truth for sector-read error → recovery action
+//! decisions. Pass 1 sweep routes through it. Pass N patch's
+//! `handle_read_failure` (in `disc/patch.rs`) does NOT — historically
+//! MEDIUM_ERROR / NOT_READY get inline handling with their own thresholds
+//! (`PASSN_DAMAGE_THRESHOLD_PCT=6` vs the sweep's `12`), their own
+//! damage_window (state.damage_window, separate from ReadCtx.damage_window),
+//! and their own skip logic (`compute_damage_skip`, which runs AFTER
+//! the failure handler and has a size-aware `range_remaining/4` cap
+//! that `handle_read_error::JumpAhead` does not know about).
+//!
+//! This file is the A/B fixture for that unification. It pins the
+//! CURRENT (pre-unification) end-to-end behavior of `Disc::patch` for
+//! eight canonical damage profiles against a synthetic
+//! `ScriptedSectorReader`. Each profile asserts the exact observable
+//! outcome — final mapfile byte counts and outer-loop counters — so any
+//! attempt to refactor the failure path either preserves the goldens or
+//! the test fails loudly.
+//!
+//! The prompt called for "exact sequence of `ReadAction` enums per
+//! LBA"; that framing doesn't fit the current architecture because
+//! `handle_read_failure` produces `FailureAction`, not `ReadAction`,
+//! and interleaves with `compute_damage_skip` + cursor management in
+//! the outer loop. The observable contract — what `Disc::patch` does
+//! to the mapfile and how many reads it performs — is the equivalent
+//! invariant, captured end-to-end.
+//!
+//! Why we expect divergence under naïve unification (see final report
+//! of the 0.20.8 unification attempt): the patch loop's skip semantics
+//! live in `compute_damage_skip` POST-failure-handler, with a size-aware
+//! cap that `handle_read_error` knows nothing about; routing through
+//! `handle_read_error` would invert that cursor flow. The fixture stays
+//! checked in regardless — it documents the contract for the next
+//! refactor attempt.
+
+use libfreemkv::ContentFormat;
+use libfreemkv::Disc;
+use libfreemkv::DiscFormat;
+use libfreemkv::disc::CopyOptions;
+use libfreemkv::disc::DiscRegion;
+use libfreemkv::disc::mapfile::{Mapfile, SectorStatus};
+use libfreemkv::error::{Error, Result};
+use libfreemkv::scsi;
+use libfreemkv::{ScsiSense, SectorSource};
+use std::sync::{Arc, Mutex};
+
+const SECTOR_SIZE: usize = 2048;
+
+/// Per-attempt result the script can emit. `Ok` returns a deterministic
+/// per-sector byte pattern (LBA mod 256 in each sector). `Err` returns
+/// the SCSI sense triple supplied — the patch failure path inspects
+/// `scsi_sense().sense_key` to classify (MEDIUM, NOT_READY,
+/// HARDWARE, ILLEGAL_REQUEST, ABORTED_COMMAND).
+#[derive(Debug, Clone, Copy)]
+enum ScriptStep {
+    Ok,
+    Err { sense_key: u8, asc: u8, ascq: u8 },
+}
+
+/// A scripted reader. For each (lba, count) read attempt, picks the
+/// step at `attempt_idx[lba]`, advances the index. If no script entry
+/// exists for an LBA, defaults to `Ok` so we don't need to script
+/// every sector of large ranges.
+///
+/// "Batch fails if ANY sector in the batch is bad" — matches real
+/// drive behavior (`pass_n_size_aware_skip.rs` uses the same model).
+/// For batched reads we synthesize an Err with the FIRST scripted
+/// failure in the batch.
+struct ScriptedSectorReader {
+    capacity: u32,
+    /// Per-LBA script of (step, then next step on retry, …). When
+    /// retries exhaust the script, the LAST step repeats forever.
+    script: std::collections::HashMap<u32, Vec<ScriptStep>>,
+    /// Per-LBA index into its script vec. Bumps on each read attempt
+    /// at that LBA.
+    attempt_idx: Mutex<std::collections::HashMap<u32, usize>>,
+    /// Full read trace: every (lba, count, result_was_ok) tuple in
+    /// call order. Lets the test assert that adaptive-batch dropped
+    /// to count=1, bisection happened, etc.
+    trace: Arc<Mutex<Vec<(u32, u16, bool)>>>,
+}
+
+impl ScriptedSectorReader {
+    fn new(capacity: u32) -> (Self, Arc<Mutex<Vec<(u32, u16, bool)>>>) {
+        let trace = Arc::new(Mutex::new(Vec::new()));
+        (
+            Self {
+                capacity,
+                script: std::collections::HashMap::new(),
+                attempt_idx: Mutex::new(std::collections::HashMap::new()),
+                trace: trace.clone(),
+            },
+            trace,
+        )
+    }
+
+    /// Set a single-step script for `lba`: every attempt yields `step`.
+    fn always(&mut self, lba: u32, step: ScriptStep) {
+        self.script.insert(lba, vec![step]);
+    }
+
+    /// Set a multi-step script for `lba`: first attempt yields
+    /// `steps[0]`, second `steps[1]`, … on retry the last step repeats.
+    #[allow(dead_code)]
+    fn sequence(&mut self, lba: u32, steps: Vec<ScriptStep>) {
+        self.script.insert(lba, steps);
+    }
+
+    fn step_for(&self, lba: u32) -> ScriptStep {
+        let v = match self.script.get(&lba) {
+            Some(v) => v,
+            None => return ScriptStep::Ok,
+        };
+        let mut idx = self.attempt_idx.lock().unwrap();
+        let i = idx.entry(lba).or_insert(0);
+        let step = v[(*i).min(v.len() - 1)];
+        *i += 1;
+        step
+    }
+}
+
+impl SectorSource for ScriptedSectorReader {
+    fn read_sectors(
+        &mut self,
+        lba: u32,
+        count: u16,
+        buf: &mut [u8],
+        _recovery: bool,
+    ) -> Result<usize> {
+        // Look at every sector in the batch — first failure determines
+        // the outcome.
+        let mut failure: Option<(u8, u8, u8)> = None;
+        for offset in 0..count as u32 {
+            match self.step_for(lba + offset) {
+                ScriptStep::Ok => {}
+                ScriptStep::Err {
+                    sense_key,
+                    asc,
+                    ascq,
+                } => {
+                    failure = Some((sense_key, asc, ascq));
+                    break;
+                }
+            }
+        }
+        let ok = failure.is_none();
+        self.trace.lock().unwrap().push((lba, count, ok));
+        if let Some((sense_key, asc, ascq)) = failure {
+            return Err(Error::ScsiError {
+                opcode: scsi::SCSI_READ_10,
+                status: scsi::SCSI_STATUS_CHECK_CONDITION,
+                sense: Some(ScsiSense {
+                    sense_key,
+                    asc,
+                    ascq,
+                }),
+            });
+        }
+        // Per-sector LBA byte pattern.
+        for (i, chunk) in buf.chunks_mut(SECTOR_SIZE).enumerate() {
+            chunk.fill(((lba + i as u32) & 0xff) as u8);
+        }
+        Ok(buf.len())
+    }
+
+    fn capacity_sectors(&self) -> u32 {
+        self.capacity
+    }
+}
+
+fn synthetic_disc(capacity_sectors: u32) -> Disc {
+    Disc {
+        volume_id: String::new(),
+        meta_title: None,
+        format: DiscFormat::BluRay,
+        capacity_sectors,
+        capacity_bytes: capacity_sectors as u64 * SECTOR_SIZE as u64,
+        layers: 1,
+        titles: Vec::new(),
+        region: DiscRegion::Free,
+        aacs: None,
+        css: None,
+        encrypted: false,
+        aacs_error: None,
+        content_format: ContentFormat::BdTs,
+    }
+}
+
+fn prep_iso_and_mapfile(
+    iso_path: &std::path::Path,
+    total_bytes: u64,
+    finished_ranges: &[(u64, u64)],
+    nontrimmed_ranges: &[(u64, u64)],
+) {
+    use std::fs::OpenOptions;
+    use std::io::{Seek, SeekFrom, Write};
+    let mut f = OpenOptions::new()
+        .create(true)
+        .write(true)
+        .truncate(true)
+        .open(iso_path)
+        .unwrap();
+    f.set_len(total_bytes).unwrap();
+    f.seek(SeekFrom::Start(0)).unwrap();
+    f.write_all(&[]).unwrap();
+
+    let map_path = libfreemkv::disc::mapfile_path_for(iso_path);
+    let mut mf = Mapfile::create(&map_path, total_bytes, "test").unwrap();
+    for &(pos, size) in finished_ranges {
+        mf.record(pos, size, SectorStatus::Finished).unwrap();
+    }
+    for &(pos, size) in nontrimmed_ranges {
+        mf.record(pos, size, SectorStatus::NonTrimmed).unwrap();
+    }
+}
+
+/// Observable outcome of a patch run. Goldens for each profile pin
+/// these exact values.
+#[derive(Debug, PartialEq, Eq)]
+struct Golden {
+    /// `bytes_good` at end of patch.
+    bytes_good: u64,
+    /// `bytes_unreadable` at end.
+    bytes_unreadable: u64,
+    /// `bytes_pending` (NonTrimmed) at end.
+    bytes_pending: u64,
+    /// Did the pass exit via wedge-detection?
+    wedged_exit: bool,
+    /// Sanity bound on trace length — patch makes a finite number of
+    /// reads bounded by `MAX_SKIPS_PER_RANGE * range_sectors` plus
+    /// retries. Asserted as an UPPER bound only (so any reduction in
+    /// retries via future tuning doesn't fail the test spuriously).
+    max_reads: usize,
+}
+
+/// Common helper: prep ISO + mapfile, run `disc.copy(multipass)`,
+/// return (PatchOutcome ↔ CopyResult, final-map stats, trace length).
+fn run_profile(
+    profile_name: &str,
+    capacity_sectors: u32,
+    nontrimmed: &[(u64, u64)],
+    finished: &[(u64, u64)],
+    scripted: ScriptedSectorReader,
+    trace: Arc<Mutex<Vec<(u32, u16, bool)>>>,
+) -> (
+    libfreemkv::disc::CopyResult,
+    libfreemkv::disc::mapfile::MapStats,
+    usize,
+) {
+    let total_bytes: u64 = capacity_sectors as u64 * SECTOR_SIZE as u64;
+    let disc = synthetic_disc(capacity_sectors);
+
+    let tmp = tempfile::NamedTempFile::new().unwrap();
+    let iso_path = tmp.path().to_path_buf();
+    drop(tmp);
+
+    prep_iso_and_mapfile(&iso_path, total_bytes, finished, nontrimmed);
+
+    let opts = CopyOptions {
+        decrypt: false,
+        multipass: true,
+        ..Default::default()
+    };
+
+    let mut reader = scripted;
+    let pr = disc
+        .copy(&mut reader, &iso_path, &opts)
+        .unwrap_or_else(|e| panic!("[{profile_name}] disc.copy returned Err: {e:?}"));
+
+    let map_path = libfreemkv::disc::mapfile_path_for(&iso_path);
+    let map = Mapfile::load(&map_path).unwrap();
+    let stats = map.stats();
+
+    let trace_len = trace.lock().unwrap().len();
+
+    let _ = std::fs::remove_file(&iso_path);
+    let _ = std::fs::remove_file(&map_path);
+
+    (pr, stats, trace_len)
+}
+
+// ─────────────────────────── Profile 1: CLEAN ────────────────────────────
+//
+// The NonTrimmed range has zero scripted failures — every read succeeds.
+// Patch should march through the range and mark it Finished. Validates
+// the happy-path side of the failure-handler dispatch (it shouldn't
+// fire at all).
+
+#[test]
+fn profile_01_clean_all_recoverable() {
+    let capacity_sectors: u32 = 256;
+    let (reader, trace) = ScriptedSectorReader::new(capacity_sectors);
+    // No scripted errors → all reads succeed.
+
+    let nontrimmed = [(100 * 2048, 16 * 2048)]; // 16-sector NonTrimmed range
+    let finished = [
+        (0, 100 * 2048),
+        (116 * 2048, (capacity_sectors as u64 - 116) * 2048),
+    ];
+
+    let (pr, stats, trace_len) = run_profile(
+        "01_clean",
+        capacity_sectors,
+        &nontrimmed,
+        &finished,
+        reader,
+        trace,
+    );
+
+    let expected = Golden {
+        bytes_good: capacity_sectors as u64 * 2048,
+        bytes_unreadable: 0,
+        bytes_pending: 0,
+        wedged_exit: false,
+        max_reads: 8, // adaptive batch=32 reads finishes 16 sectors in 1 read; allow up to 8.
+    };
+    assert_eq!(stats.bytes_good, expected.bytes_good, "01_clean bytes_good");
+    assert_eq!(
+        stats.bytes_unreadable, expected.bytes_unreadable,
+        "01_clean bytes_unreadable"
+    );
+    assert_eq!(
+        stats.bytes_pending, expected.bytes_pending,
+        "01_clean bytes_pending"
+    );
+    assert!(!pr.halted, "01_clean halted");
+    assert!(
+        trace_len <= expected.max_reads,
+        "01_clean trace_len={trace_len} exceeds bound {}",
+        expected.max_reads
+    );
+}
+
+// ─────────────────────────── Profile 2: ALL MEDIUM ───────────────────────
+//
+// Every LBA in the NonTrimmed range returns MEDIUM_ERROR every attempt.
+// Adaptive-batch drops to count=1 on first batch failure, then each
+// single-sector read fails → consecutive_failures climbs, damage_window
+// fills, compute_damage_skip fires, MAX_SKIPS_PER_RANGE caps the work,
+// remaining bytes stay NonTrimmed (NEVER marked Unreadable inside a
+// single pass — 2026-05-11 design call).
+
+#[test]
+fn profile_02_all_medium_error() {
+    let capacity_sectors: u32 = 256;
+    let (mut reader, trace) = ScriptedSectorReader::new(capacity_sectors);
+    for lba in 100..116 {
+        reader.always(
+            lba,
+            ScriptStep::Err {
+                sense_key: scsi::SENSE_KEY_MEDIUM_ERROR,
+                asc: 0x11,
+                ascq: 0x00,
+            },
+        );
+    }
+
+    let nontrimmed = [(100 * 2048, 16 * 2048)];
+    let finished = [
+        (0, 100 * 2048),
+        (116 * 2048, (capacity_sectors as u64 - 116) * 2048),
+    ];
+
+    let (pr, stats, trace_len) = run_profile(
+        "02_all_medium",
+        capacity_sectors,
+        &nontrimmed,
+        &finished,
+        reader,
+        trace,
+    );
+
+    // GOLDEN: the 16-sector bad range stays NonTrimmed (bytes_pending).
+    // Pre-2026-05-11 patch would mark Unreadable here; current code
+    // preserves NonTrimmed so subsequent passes get another shot.
+    assert_eq!(
+        stats.bytes_good,
+        (capacity_sectors as u64 - 16) * 2048,
+        "02_all_medium bytes_good"
+    );
+    assert_eq!(
+        stats.bytes_unreadable, 0,
+        "02_all_medium bytes_unreadable (must NOT be marked terminal in one pass)"
+    );
+    assert_eq!(
+        stats.bytes_pending,
+        16 * 2048,
+        "02_all_medium bytes_pending (NonTrimmed retained across passes)"
+    );
+    assert!(!pr.halted, "02_all_medium halted");
+    // Upper bound: every sector probed individually + a few batch-drop
+    // and skip-escalation attempts. 16 sectors × ~3 visits ≈ 50.
+    assert!(
+        trace_len <= 80,
+        "02_all_medium trace_len={trace_len} exceeds 80"
+    );
+}
+
+// ───────────────────── Profile 3: ALTERNATING GOOD/BAD ───────────────────
+//
+// LBAs 100, 102, 104, ... bad; odd LBAs good. Validates that good
+// sectors interleaved with bad get recovered individually after the
+// adaptive split (batch-fail → count=1 → per-sector probe).
+
+#[test]
+fn profile_03_alternating_good_bad() {
+    let capacity_sectors: u32 = 256;
+    let (mut reader, trace) = ScriptedSectorReader::new(capacity_sectors);
+    for lba in (100..116).step_by(2) {
+        reader.always(
+            lba,
+            ScriptStep::Err {
+                sense_key: scsi::SENSE_KEY_MEDIUM_ERROR,
+                asc: 0x11,
+                ascq: 0x00,
+            },
+        );
+    }
+
+    let nontrimmed = [(100 * 2048, 16 * 2048)];
+    let finished = [
+        (0, 100 * 2048),
+        (116 * 2048, (capacity_sectors as u64 - 116) * 2048),
+    ];
+
+    let (pr, stats, trace_len) = run_profile(
+        "03_alternating",
+        capacity_sectors,
+        &nontrimmed,
+        &finished,
+        reader,
+        trace,
+    );
+
+    // GOLDEN: 8 good sectors interleaved should mostly be Finished;
+    // 8 bad stay NonTrimmed. Allow 2 sectors of slop for the actual
+    // bisect cursor advance — converging on alternating bad/good in
+    // a single pass isn't always exact at boundaries with the
+    // size-aware skip cap.
+    let good_total = stats.bytes_good;
+    let baseline_good = (capacity_sectors as u64 - 16) * 2048;
+    let middle_recovered = good_total - baseline_good;
+    assert!(
+        middle_recovered >= 6 * 2048,
+        "03_alternating recovered only {middle_recovered} bytes of 8 good sectors"
+    );
+    assert!(
+        middle_recovered <= 9 * 2048,
+        "03_alternating recovered MORE than scripted good sectors: {middle_recovered}"
+    );
+    assert_eq!(stats.bytes_unreadable, 0, "03_alternating bytes_unreadable");
+    // Remaining must be NonTrimmed (pending), not lost.
+    assert!(
+        stats.bytes_pending > 0,
+        "03_alternating expected NonTrimmed remainder, got bytes_pending=0"
+    );
+    assert!(!pr.halted, "03_alternating halted");
+    assert!(
+        trace_len <= 120,
+        "03_alternating trace_len={trace_len} exceeds 120"
+    );
+}
+
+// ───────────────────── Profile 4: EDGE-BAD (size-aware-skip canon) ───────
+//
+// Bad at start (100..104), good middle (104..112), bad at end (112..116).
+// This is the size-aware-skip canonical case. The middle good sectors
+// MUST be recovered — pre-fix patch would skip-escalate across the
+// whole range and miss them.
+
+#[test]
+fn profile_04_edge_bad_good_middle() {
+    let capacity_sectors: u32 = 256;
+    let (mut reader, trace) = ScriptedSectorReader::new(capacity_sectors);
+    for lba in 100..104 {
+        reader.always(
+            lba,
+            ScriptStep::Err {
+                sense_key: scsi::SENSE_KEY_MEDIUM_ERROR,
+                asc: 0x11,
+                ascq: 0x00,
+            },
+        );
+    }
+    for lba in 112..116 {
+        reader.always(
+            lba,
+            ScriptStep::Err {
+                sense_key: scsi::SENSE_KEY_MEDIUM_ERROR,
+                asc: 0x11,
+                ascq: 0x00,
+            },
+        );
+    }
+
+    let nontrimmed = [(100 * 2048, 16 * 2048)];
+    let finished = [
+        (0, 100 * 2048),
+        (116 * 2048, (capacity_sectors as u64 - 116) * 2048),
+    ];
+
+    let (pr, stats, trace_len) = run_profile(
+        "04_edge_bad",
+        capacity_sectors,
+        &nontrimmed,
+        &finished,
+        reader,
+        trace,
+    );
+
+    // GOLDEN: the 8 good middle sectors should land Finished (allowing
+    // 2 sectors of bisection slop at boundaries).
+    let middle_recovered = stats.bytes_good - (capacity_sectors as u64 - 16) * 2048;
+    assert!(
+        middle_recovered >= 6 * 2048,
+        "04_edge_bad recovered only {middle_recovered} bytes of 8 good middle sectors"
+    );
+    assert_eq!(stats.bytes_unreadable, 0, "04_edge_bad bytes_unreadable");
+    assert!(
+        stats.bytes_pending > 0,
+        "04_edge_bad bytes_pending expected > 0"
+    );
+    assert!(!pr.halted, "04_edge_bad halted");
+    assert!(
+        trace_len <= 120,
+        "04_edge_bad trace_len={trace_len} exceeds 120"
+    );
+}
+
+// ───────────────────── Profile 5: SINGLE BAD SECTOR ──────────────────────
+//
+// 1 bad sector in the middle of an otherwise good 16-sector NonTrimmed
+// range. Validates the common "stochastic miss in Pass 1, easily picked
+// up in Pass N" scenario.
+
+#[test]
+fn profile_05_single_bad_sector() {
+    let capacity_sectors: u32 = 256;
+    let (mut reader, trace) = ScriptedSectorReader::new(capacity_sectors);
+    reader.always(
+        108,
+        ScriptStep::Err {
+            sense_key: scsi::SENSE_KEY_MEDIUM_ERROR,
+            asc: 0x11,
+            ascq: 0x00,
+        },
+    );
+
+    let nontrimmed = [(100 * 2048, 16 * 2048)];
+    let finished = [
+        (0, 100 * 2048),
+        (116 * 2048, (capacity_sectors as u64 - 116) * 2048),
+    ];
+
+    let (pr, stats, trace_len) = run_profile(
+        "05_single_bad",
+        capacity_sectors,
+        &nontrimmed,
+        &finished,
+        reader,
+        trace,
+    );
+
+    // GOLDEN: 15 of 16 sectors recovered. 1 sector stays NonTrimmed
+    // (NOT Unreadable — same multi-pass tolerance principle).
+    assert_eq!(
+        stats.bytes_good,
+        (capacity_sectors as u64 - 1) * 2048,
+        "05_single_bad bytes_good"
+    );
+    assert_eq!(stats.bytes_unreadable, 0, "05_single_bad bytes_unreadable");
+    assert_eq!(stats.bytes_pending, 2048, "05_single_bad bytes_pending");
+    assert!(!pr.halted, "05_single_bad halted");
+    assert!(
+        trace_len <= 80,
+        "05_single_bad trace_len={trace_len} exceeds 80"
+    );
+}
+
+// ───────────────────── Profile 6: DEEP PIT ───────────────────────────────
+//
+// A contiguous 8-sector bad pit in the middle of a wider 24-sector
+// NonTrimmed range. Tests the damage-window threshold + size-aware-skip
+// converging on the actual pit boundaries instead of bailing on
+// MAX_SKIPS_PER_RANGE.
+
+#[test]
+fn profile_06_deep_pit() {
+    let capacity_sectors: u32 = 256;
+    let (mut reader, trace) = ScriptedSectorReader::new(capacity_sectors);
+    for lba in 108..116 {
+        reader.always(
+            lba,
+            ScriptStep::Err {
+                sense_key: scsi::SENSE_KEY_MEDIUM_ERROR,
+                asc: 0x11,
+                ascq: 0x00,
+            },
+        );
+    }
+
+    // 24 sectors NonTrimmed: 100..108 good, 108..116 BAD, 116..124 good.
+    let nontrimmed = [(100 * 2048, 24 * 2048)];
+    let finished = [
+        (0, 100 * 2048),
+        (124 * 2048, (capacity_sectors as u64 - 124) * 2048),
+    ];
+
+    let (pr, stats, trace_len) = run_profile(
+        "06_deep_pit",
+        capacity_sectors,
+        &nontrimmed,
+        &finished,
+        reader,
+        trace,
+    );
+
+    // GOLDEN: 16 good (8 on each side of the pit) recovered, 8 bad
+    // stay NonTrimmed.
+    let recovered_in_range = stats.bytes_good - (capacity_sectors as u64 - 24) * 2048;
+    assert!(
+        recovered_in_range >= 14 * 2048,
+        "06_deep_pit recovered only {recovered_in_range} bytes of 16 good sectors"
+    );
+    assert_eq!(stats.bytes_unreadable, 0, "06_deep_pit bytes_unreadable");
+    assert!(
+        stats.bytes_pending > 0,
+        "06_deep_pit bytes_pending expected > 0"
+    );
+    assert!(!pr.halted, "06_deep_pit halted");
+    assert!(
+        trace_len <= 120,
+        "06_deep_pit trace_len={trace_len} exceeds 120"
+    );
+}
+
+// ───────────────────── Profile 7: MEDIUM-THEN-GOOD ───────────────────────
+//
+// First N attempts at each bad LBA fail with MEDIUM_ERROR, then succeed.
+// Tests whether patch's retry semantics revisit failed sectors. Current
+// patch dispatches NonTrimmed on first failure and ADVANCES the cursor
+// — it does NOT retry the same LBA inside one pass for MEDIUM_ERROR
+// (only NOT_READY retries in-place). So the goldens here are: bad
+// sectors stay NonTrimmed in this pass (the recovery would happen in a
+// subsequent pass, which this single-pass fixture does not run).
+
+#[test]
+fn profile_07_medium_then_good() {
+    let capacity_sectors: u32 = 256;
+    let (mut reader, trace) = ScriptedSectorReader::new(capacity_sectors);
+    // Sectors 105..110: fail twice, then succeed.
+    for lba in 105..110 {
+        reader.sequence(
+            lba,
+            vec![
+                ScriptStep::Err {
+                    sense_key: scsi::SENSE_KEY_MEDIUM_ERROR,
+                    asc: 0x11,
+                    ascq: 0x00,
+                },
+                ScriptStep::Err {
+                    sense_key: scsi::SENSE_KEY_MEDIUM_ERROR,
+                    asc: 0x11,
+                    ascq: 0x00,
+                },
+                ScriptStep::Ok,
+            ],
+        );
+    }
+
+    let nontrimmed = [(100 * 2048, 16 * 2048)];
+    let finished = [
+        (0, 100 * 2048),
+        (116 * 2048, (capacity_sectors as u64 - 116) * 2048),
+    ];
+
+    let (pr, stats, trace_len) = run_profile(
+        "07_medium_then_good",
+        capacity_sectors,
+        &nontrimmed,
+        &finished,
+        reader,
+        trace,
+    );
+
+    // GOLDEN: patch's cache-priming (`prime_cache`) issues 3
+    // throwaway single-sector reads at lba-3..lba before each count==1
+    // recovery read. Those throwaway reads ADVANCE the per-LBA script
+    // step counter even though their results are discarded. So a
+    // 3-step script (fail, fail, ok) gets consumed by 2 prime calls
+    // plus 1 real read → the real read sees `Ok` and the sector is
+    // recovered. Net effect: patch fully recovers the range in one
+    // pass thanks to priming, even though the script said "fails on
+    // first two attempts."
+    //
+    // This is the documented cache-prime behavior (`disc/patch.rs`
+    // ~line 398, "Proven 2026-05-07 with dd-as-oracle: 8/8 sectors
+    // recoverable when primed vs 6/8 cold"). The golden pins it.
+    assert_eq!(
+        stats.bytes_good,
+        capacity_sectors as u64 * 2048,
+        "07_medium_then_good bytes_good — cache-prime should consume \
+         the failing script steps so the real read sees Ok"
+    );
+    assert_eq!(
+        stats.bytes_unreadable, 0,
+        "07_medium_then_good bytes_unreadable"
+    );
+    assert_eq!(stats.bytes_pending, 0, "07_medium_then_good bytes_pending");
+    assert!(!pr.halted, "07_medium_then_good halted");
+    assert!(
+        trace_len <= 100,
+        "07_medium_then_good trace_len={trace_len} exceeds 100"
+    );
+}
+
+// ───────────────────── Profile 8: BATCHED-FAIL ONLY ──────────────────────
+//
+// LBA 108 fails on BATCH reads (any batch including it) but succeeds
+// individually. Models a marginal sector that the drive can ECC-recover
+// when read alone but not at multi-sector throughput. Validates that
+// adaptive batch's drop-to-count=1 retries the same starting position
+// and rescues the data.
+//
+// Implementation note: the scripted reader marks the entire batch failed
+// on any failed sector. We can't easily differentiate "single vs batch"
+// without bigger plumbing — so this profile uses a script that fails
+// once then succeeds on retry at the same LBA, simulating "drive
+// recovered after retry."
+
+#[test]
+fn profile_08_batch_fail_singles_ok() {
+    let capacity_sectors: u32 = 256;
+    let (mut reader, trace) = ScriptedSectorReader::new(capacity_sectors);
+    // Sector 108: fail on first call (which is the batch read), succeed
+    // on second call (the drop-to-count=1 retry at the same position).
+    reader.sequence(
+        108,
+        vec![
+            ScriptStep::Err {
+                sense_key: scsi::SENSE_KEY_MEDIUM_ERROR,
+                asc: 0x11,
+                ascq: 0x00,
+            },
+            ScriptStep::Ok,
+        ],
+    );
+
+    let nontrimmed = [(100 * 2048, 16 * 2048)];
+    let finished = [
+        (0, 100 * 2048),
+        (116 * 2048, (capacity_sectors as u64 - 116) * 2048),
+    ];
+
+    let (pr, stats, trace_len) = run_profile(
+        "08_batch_fail",
+        capacity_sectors,
+        &nontrimmed,
+        &finished,
+        reader,
+        trace,
+    );
+
+    // GOLDEN: the second attempt succeeds → all 16 sectors recovered.
+    assert_eq!(
+        stats.bytes_good,
+        capacity_sectors as u64 * 2048,
+        "08_batch_fail bytes_good — second attempt should recover"
+    );
+    assert_eq!(stats.bytes_unreadable, 0, "08_batch_fail bytes_unreadable");
+    assert_eq!(stats.bytes_pending, 0, "08_batch_fail bytes_pending");
+    assert!(!pr.halted, "08_batch_fail halted");
+    assert!(
+        trace_len <= 80,
+        "08_batch_fail trace_len={trace_len} exceeds 80"
+    );
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+//
+// Suppressed for now: NOT_READY-then-recover, HARDWARE_ERROR (wedge),
+// ILLEGAL_REQUEST (wedge), and ABORTED_COMMAND profiles. Each would
+// trigger long real-time sleeps inside `handle_read_failure`:
+//
+//   - NOT_READY (sense_key=0x02, asc=0x02/0x03/0x04): 15 s pause per
+//     occurrence (`patch_not_ready_pause`), and retries the same LBA
+//     in-place. Even one NOT_READY costs the test 15 s wall-time.
+//
+//   - HARDWARE_ERROR / ILLEGAL_REQUEST: 30 s per occurrence
+//     (`WEDGE_FAMILY_COOLDOWN_SECS`), bounded by
+//     `WEDGE_ABORT_THRESHOLD=16` before wedged-exit. Worst case ~8
+//     minutes per profile.
+//
+// The sleeps are not injectable. Adding them would require either a
+// `now()` / `sleep()` trait injection (out of scope for the unification
+// task) or a "test mode" compile-time flag (architectural smell). The
+// behavioural contracts for those paths are captured in
+// `read_error.rs`'s in-module tests instead — they exercise the
+// classifier without invoking the patch loop's sleep side-effects.
+//
+// If the unification ever proceeds, the next step is to add a clock
+// injection point in `handle_read_failure` and extend this fixture
+// with the wedge/NOT_READY profiles too.
@@ -24,6 +24,7 @@ fn test_sgio_transport_timeout_does_not_kill_transport() {
        use libfreemkv::scsi::{DataDirection, SCSI_STATUS_TRANSPORT_FAILURE};
        use std::sync::Arc;
        use std::sync::atomic::{AtomicI32, Ordering};
+        use std::time::Duration;

        let mut transport = SgIoTransport::open(_path).expect("open device");
        let fd_before = transport.fd;
@@ -93,6 +94,8 @@ fn test_drive_read_per_cdb_timeout_bounds_call() {

    #[cfg(target_os = "linux")]
    {
+        use std::time::Duration;
+
        let mut drive = libfreemkv::Drive::open(_path).expect("open drive");
        let timeout_ms: u32 = 5_000;

@@ -302,12 +302,12 @@ fn m2ts_stream_write_read() {
            keyframe: i == 0,
            data: vec![i; 100],
        };
-        stream.write(&frame).unwrap();
+        PesStream::write(&mut stream, &frame).unwrap();
    }
-    stream.finish().unwrap();
+    PesStream::finish(&mut stream).unwrap();

    // Verify the info is correct
-    let info = stream.info();
+    let info = PesStream::info(&stream);
    assert_eq!(info.streams.len(), 4);
    assert_eq!(info.duration_secs, 7200.0);
 }
@@ -356,7 +356,7 @@ fn m2ts_read_returns_error_on_write_stream() {
    let dt = sample_disc_title();
    let output = Cursor::new(Vec::new());
    let mut stream = M2tsStream::create(output, &dt).unwrap();
-    assert!(stream.read().is_err());
+    assert!(PesStream::read(&mut stream).is_err());
 }

 // ── DiscTitle::empty ──────────────────────────────────────────
@@ -578,7 +578,7 @@ fn meta_all_stream_types() {
 #[test]
 fn mkvstream_write_finish() {
    let dt = sample_disc_title();
-    let writer: Box<dyn libfreemkv::mux::WriteSeek> = Box::new(Cursor::new(Vec::new()));
+    let writer: Box<dyn libfreemkv::mux::WriteSeek + Send> = Box::new(Cursor::new(Vec::new()));
    let mut stream = MkvStream::create(writer, &dt).unwrap();

    // Write some fake PES frames (they won't produce valid MKV content
@@ -590,20 +590,20 @@ fn mkvstream_write_finish() {
            keyframe: i == 0,
            data: vec![i; 100],
        };
-        stream.write(&frame).unwrap();
+        PesStream::write(&mut stream, &frame).unwrap();
    }

    // finish should not panic even without valid codec data
-    stream.finish().unwrap();
+    PesStream::finish(&mut stream).unwrap();
 }

 #[test]
 fn mkvstream_meta_sets_title() {
    let dt = sample_disc_title();
-    let writer: Box<dyn libfreemkv::mux::WriteSeek> = Box::new(Cursor::new(Vec::new()));
+    let writer: Box<dyn libfreemkv::mux::WriteSeek + Send> = Box::new(Cursor::new(Vec::new()));
    let stream = MkvStream::create(writer, &dt).unwrap();

-    let info = stream.info();
+    let info = PesStream::info(&stream);
    assert_eq!(info.playlist, "Test Movie");
    assert_eq!(info.duration_secs, 7200.0);
    assert_eq!(info.streams.len(), 4);
@@ -640,7 +640,7 @@ fn mkvstream_roundtrip_bdts() {
        codec_privates: Vec::new(),
    };

-    let writer: Box<dyn libfreemkv::mux::WriteSeek> = Box::new(Cursor::new(Vec::new()));
+    let writer: Box<dyn libfreemkv::mux::WriteSeek + Send> = Box::new(Cursor::new(Vec::new()));
    let mut stream = MkvStream::create(writer, &dt).unwrap();

    // Write PES frames targeting the audio track
@@ -651,13 +651,13 @@ fn mkvstream_roundtrip_bdts() {
            keyframe: true,
            data: vec![i; 100],
        };
-        stream.write(&frame).unwrap();
+        PesStream::write(&mut stream, &frame).unwrap();
    }

-    stream.finish().unwrap();
+    PesStream::finish(&mut stream).unwrap();

    // Verify the info is correct
-    let info = stream.info();
+    let info = PesStream::info(&stream);
    assert_eq!(info.streams.len(), 1);
    assert_eq!(info.playlist, "Audio Only");
 }
@@ -724,10 +724,10 @@ fn mkvstream_meta_preserves_all_streams() {
        codec_privates: Vec::new(),
    };

-    let writer: Box<dyn libfreemkv::mux::WriteSeek> = Box::new(Cursor::new(Vec::new()));
+    let writer: Box<dyn libfreemkv::mux::WriteSeek + Send> = Box::new(Cursor::new(Vec::new()));
    let stream = MkvStream::create(writer, &dt).unwrap();

-    let info = stream.info();
+    let info = PesStream::info(&stream);
    assert_eq!(info.streams.len(), 5, "all 5 streams should be preserved");
    assert_eq!(info.playlist, "Stream Test");
    assert_eq!(info.duration_secs, 3600.0);
@@ -832,7 +832,8 @@ fn mkvstream_e2e_h264_produces_valid_mkv() {
        }
    }

-    let writer: Box<dyn libfreemkv::mux::WriteSeek> = Box::new(SharedWriter(output2.clone()));
+    let writer: Box<dyn libfreemkv::mux::WriteSeek + Send> =
+        Box::new(SharedWriter(output2.clone()));
    let mut stream2 = MkvStream::create(writer, &dt).unwrap();

    // Write the ES data (SPS+PPS+IDR) as a keyframe PES frame.
@@ -842,7 +843,7 @@ fn mkvstream_e2e_h264_produces_valid_mkv() {
        keyframe: true,
        data: es_data,
    };
-    stream2.write(&frame1).unwrap();
+    PesStream::write(&mut stream2, &frame1).unwrap();

    // Write a second non-IDR frame
    let frame2 = libfreemkv::pes::PesFrame {
@@ -851,8 +852,8 @@ fn mkvstream_e2e_h264_produces_valid_mkv() {
        keyframe: false,
        data: es_data2,
    };
-    stream2.write(&frame2).unwrap();
-    stream2.finish().unwrap();
+    PesStream::write(&mut stream2, &frame2).unwrap();
+    PesStream::finish(&mut stream2).unwrap();

    let data = output2.lock().unwrap().clone().into_inner();

@@ -1,7 +1,7 @@
 //! UDF parser tests using a MockSectorReader.

 use libfreemkv::error::Result;
-use libfreemkv::{SectorReader, read_filesystem};
+use libfreemkv::{SectorSource, read_filesystem};
 use std::collections::HashMap;

 const SECTOR_SIZE: usize = 2048;
@@ -38,7 +38,7 @@ impl MockSectorReader {
    }
 }

-impl SectorReader for MockSectorReader {
+impl SectorSource for MockSectorReader {
    fn read_sectors(
        &mut self,
        lba: u32,
@@ -463,11 +463,11 @@ fn find_dir_case_insensitive() {

 #[test]
 fn sector_reader_is_object_safe() {
-    // Verify SectorReader can be used as a trait object
+    // Verify SectorSource can be used as a trait object
    let mut reader = MockSectorReader::new();
    reader.set_sector(0, vec![42u8; SECTOR_SIZE]);

-    let dyn_reader: &mut dyn SectorReader = &mut reader;
+    let dyn_reader: &mut dyn SectorSource = &mut reader;
    let mut buf = vec![0u8; SECTOR_SIZE];
    let n = dyn_reader.read_sectors(0, 1, &mut buf, true).unwrap();
    assert_eq!(n, SECTOR_SIZE);