0.31.0: hardening and correctness pass across mux, codec, AACS/CSS, UDF/MPLS/CLPI, recovery, drive/SCSI, labels, and I/O

Library-wide review-and-fix pass: tightened AACS keydb/handshake/variant
handling and trailing-partial-unit policy, corrected MPLS mark offset and
added UDF allocation bounds, hardened the mux/codec framing and M2TS paths,
guarded SCSI READ CAPACITY short transfers and unified error mapping, added
overflow guards on untrusted disc input, and made prefetch shutdown
deterministic. Release profile now builds with thin LTO + single codegen unit.

.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@1.86.0
+        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:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@1.86.0
+      - run: cargo test --tests
+
+  check-macos:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@1.86.0
+      - run: cargo check
+
+  check-windows:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@1.86.0
+      - run: cargo check

.github/workflows/leak-guard.yml

@@ -0,0 +1,35 @@
+name: leak-guard
+
+# Self-contained public-repo leak gate. Public CI cannot reach the private
+# tooling, so this encodes only the generic net: internal-infra references,
+# tracked CLAUDE.md/.claude paths, and AI-attribution in commit messages.
+# No project-specific reverse-engineering vocabulary lives here.
+
+on: [push, pull_request]
+
+jobs:
+  leak-guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - name: Compute commit range
+        id: range
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            base="${{ github.event.pull_request.base.sha }}"
+            head="${{ github.event.pull_request.head.sha }}"
+            echo "range=$base..$head" >> "$GITHUB_OUTPUT"
+          else
+            before="${{ github.event.before }}"
+            after="${{ github.sha }}"
+            # New branch / first push: github.event.before is all-zeros.
+            if [ -z "$before" ] || [ "$before" = "0000000000000000000000000000000000000000" ]; then
+              echo "range=$after" >> "$GITHUB_OUTPUT"
+            else
+              echo "range=$before..$after" >> "$GITHUB_OUTPUT"
+            fi
+          fi
+      - name: Run leak-guard
+        run: bash ci/leak-guard.sh "${{ steps.range.outputs.range }}"

.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Verify Cargo.toml version matches tag
+        run: |
+          CARGO_VER="v$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')"
+          if [ "$CARGO_VER" != "${{ github.ref_name }}" ]; then
+            echo "::error::Cargo.toml says $CARGO_VER but tag is ${{ github.ref_name }}"
+            exit 1
+          fi
+          echo "Version match: $CARGO_VER"
+
+  test:
+    needs: verify
+    runs-on: ubuntu-latest
+    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:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@1.86.0
+      - name: Publish to crates.io
+        run: cargo publish
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+
+  release:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

.github/workflows/update-readme.yml

@@ -0,0 +1,36 @@
+name: Update README version
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: main
+          token: ${{ secrets.ORG_DISPATCH_TOKEN }}
+
+      - name: Update version in README
+        run: |
+          VERSION="${{ github.event.release.tag_name }}"
+          FILE="README.md"
+
+          # Update cargo dependency version (e.g. "0.2" -> "0.3")
+          MAJOR_MINOR="${VERSION#v}"
+          MAJOR_MINOR="${MAJOR_MINOR%.*}"
+          sed -i "s|libfreemkv = \"[0-9]*\.[0-9]*\"|libfreemkv = \"${MAJOR_MINOR}\"|" "$FILE"
+
+      - name: Commit and push
+        run: |
+          VERSION="${{ github.event.release.tag_name }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add README.md
+          git diff --cached --quiet || git commit -m "Update to libfreemkv ${VERSION}"
+          git push

.gitignore

@@ -3,3 +3,14 @@ Cargo.lock
 *.swp
 *.swo
 .DS_Store
+.cargo/
+
+# session scratch — never track (may contain RE breadcrumbs)
+scratch/
+
+# stray local build artifact
+/rust_out
+
+# internal agent context — never publish (path AND dir; leak-guard blocks both)
+CLAUDE.md
+.claude/

Cargo.toml

@@ -1,28 +1,66 @@
 [package]
 name = "libfreemkv"
-version = "0.2.0"
-edition = "2021"
+version = "0.31.0"
+edition = "2024"
+rust-version = "1.86"
 license = "AGPL-3.0-only"
 description = "Open source raw disc access library for optical drives"
 repository = "https://github.com/freemkv/libfreemkv"
 keywords = ["bluray", "uhd", "optical", "scsi", "disc"]
 categories = ["hardware-support", "multimedia"]
+# Keep internal AI-instruction / private notes out of the published crate.
+exclude = ["CLAUDE.md"]
+
+[profile.release]
+lto = "thin"
+codegen-units = 1
 
 [dependencies]
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 sha1 = "0.10"
+sha2 = "0.10"
 aes = "0.8"
 cbc = "0.1"
 flate2 = "1"
+num-bigint = "0.4"
+num-traits = "0.2"
+num-integer = "0.1"
+rand = "0.8"
+cmac = "0.7"
+zip = { version = "2", default-features = false, features = ["deflate"] }
+base64 = "0.22.1"
+# Trace-level instrumentation for Disc::copy + SgIoTransport::execute. Permitted
+# under CLAUDE.md ("Acceptable strings: debug/trace logging"). Consumers (autorip)
+# wire a tracing subscriber and pipe events into the JSONL debug log.
+tracing = "0.1"
+# Bounded MPSC channel with kernel-wakeup send_timeout. Used by `io::pipeline`
+# so the halt-aware send/finish loops can BLOCK on consumer drain instead of
+# polling — the 50 ms poll cadence of the previous mpsc-based impl capped mux
+# throughput at ~1 MB/s (0.21.7).
+crossbeam-channel = "0.5"
+# Persistent work-stealing thread pool for parallel AACS unit
+# decryption. Per-call std::thread::scope spawned fresh OS threads
+# and that overhead dominated for typical batch sizes (60 units).
+# rayon's global pool initialises once on first use.
+rayon = "1"
+# SIMD-accelerated bytestring search. Drives the HEVC/H.264 start-code
+# scan in `mux::codec::h264::find_start_code` — naive byte-by-byte
+# walk is ~500 MB/s single-thread on x86_64; memchr's vectorised
+# `memmem::find` for the 3-byte `00 00 01` needle hits ~5 GB/s on
+# AVX2-capable hosts.
+memchr = "2"
 
 [target.'cfg(target_os = "linux")'.dependencies]
 libc = "0.2"
 
-[[bin]]
-name = "freemkv-info"
-path = "src/bin/freemkv_info.rs"
+[target.'cfg(target_os = "macos")'.dependencies]
+libc = "0.2"
+
+[dev-dependencies]
+tempfile = "3"
+
+[[bench]]
+name = "sgio_read"
+harness = false
 
-[[bin]]
-name = "freemkv-test"
-path = "src/bin/freemkv_test.rs"

Makefile

@@ -0,0 +1,19 @@
+# libfreemkv — local dev helper.
+# Mirrors the workspace-wide CI checks but scoped to this single crate.
+
+.PHONY: test build check ci clean
+
+test:
+	cargo test --tests
+
+build:
+	cargo build --release
+
+check:
+	cargo fmt --check
+	cargo clippy --all-targets -- -D warnings
+
+ci: check build test
+
+clean:
+	cargo clean

README.md

@@ -1,10 +1,18 @@
 [![Crates.io](https://img.shields.io/crates/v/libfreemkv)](https://crates.io/crates/libfreemkv)
+[![docs.rs](https://img.shields.io/docsrs/libfreemkv)](https://docs.rs/libfreemkv)
 [![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)
-[![Drives: 206](https://img.shields.io/badge/drives-206-brightgreen)]()
 
 # libfreemkv
 
-Rust library for raw sector access on optical drives. Identifies drives using standard SCSI commands, matches them against 206 bundled profiles, and unlocks raw read mode. No external files, no configuration.
+Rust library for 4K UHD / Blu-ray / DVD optical drives. Drive access, disc scanning, stream labels, AACS decryption, CSS decryption, KEYDB updates, and content reading in one crate. Bundled drive profiles — no external files needed.
+
+Built-in keys cover DVDs and Blu-rays (AACS 1.0). For UHD (AACS 2.0 / 2.1) discs, an optional `keydb.cfg` supplies disc-specific volume unique keys.
+
+**12+ MB/s** sustained read speeds on BD. Full init: unlock, firmware upload, speed calibration — all from pure Rust.
+
+Multi-lingual by design — the library outputs structured data and numeric error codes, never English text. Build any UI or localization on top.
+
+**[API Documentation](https://docs.rs/libfreemkv)** · **[Technical Docs](docs/)**
 
 Part of the [freemkv](https://github.com/freemkv) project.
 
@@ -12,125 +20,173 @@ Part of the [freemkv](https://github.com/freemkv) project.
 
 ```toml
 [dependencies]
-libfreemkv = "0.1"
+libfreemkv = "0.25"
 ```
 
-## Usage
+## Quick Start
 
 ```rust
-use libfreemkv::DriveSession;
+use libfreemkv::{Drive, Disc, ScanOptions};
 use std::path::Path;
 
-let mut session = DriveSession::open(Path::new("/dev/sr0"))?;
+// Open drive — profiles are bundled, auto-identified
+let mut drive = Drive::open(Path::new("/dev/sg4"))?;
+drive.wait_ready()?;              // wait for disc
+drive.init()?;                     // unlock + firmware upload
+drive.probe_disc()?;               // probe disc surface for optimal speeds
 
-session.unlock()?;       // activate raw read mode
-session.calibrate()?;    // optimize read speed
+// Scan disc — UDF, playlists, streams, AACS (all automatic)
+let disc = Disc::scan(&mut drive, &ScanOptions::default())?;
 
-let mut buf = vec![0u8; 2048];
-let n = session.read_sectors(0, 1, &mut buf)?;
+for title in &disc.titles {
+    println!("{} — {} streams", title.duration_display(), title.streams.len());
+}
+
+// Stream pipeline — read PES frames from any source, write to any output
+let opts = libfreemkv::InputOptions::default();
+let mut input = libfreemkv::input("iso://Disc.iso", &opts)?;
+let title = input.info().clone();
+let mut output = libfreemkv::output("mkv://Movie.mkv", &title)?;
+while let Ok(Some(frame)) = input.read() {
+    output.write(&frame)?;
+}
+output.finish()?;
 ```
 
-## How It Works
+### Multi-pass recovery rip
 
-1. **INQUIRY** (SPC-4 §6.4) — reads vendor_id, product_id, product_revision, vendor_specific
-2. **GET CONFIGURATION 010C** (MMC-6 §5.3.10) — reads firmware_date
-3. **Profile match** — five fields uniquely identify the drive against 206 bundled profiles
-4. **READ BUFFER** — single command with per-drive mode/buffer_id activates raw read mode
-5. **Signature verify** — drive responds with 4-byte signature + "MMkv" confirmation
-
-No fingerprints. No encrypted lookups. All identification uses standard SCSI fields.
-
-## API
+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).
 
 ```rust
-// Open and auto-identify
-let mut session = DriveSession::open(device_path)?;
+use libfreemkv::{SweepOptions, PatchOptions};
+use libfreemkv::disc::{mapfile, mapfile_path_for};
+use std::path::Path;
 
-// Drive identity
-session.drive_id.vendor_id       // "HL-DT-ST"
-session.drive_id.product_id      // "BD-RE BU40N"
-session.drive_id.product_revision // "1.03"
-session.drive_id.vendor_specific  // "NM00000"
-session.drive_id.firmware_date    // "211810241934"
+let iso = Path::new("disc.iso");
 
-// Profile data
-session.profile.chipset           // Chipset::MediaTek
-session.profile.unlock_mode       // 0x01
-session.profile.unlock_buf_id     // 0x44
-session.profile.signature         // [0x99, 0x9e, 0xc3, 0x75]
+// 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,
+})?;
 
-// Operations
-session.unlock()?;                // activate raw mode
-session.calibrate()?;             // speed optimization
-session.read_sectors(lba, count, &mut buf)?;
-session.status()?;                // feature flags
-session.read_config()?;           // drive configuration
-session.read_register(index)?;    // hardware registers
-```
+// 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; }
 
-## Chipset Support
-
-| Chipset | Status | Drives | Brands |
-|---------|--------|--------|--------|
-| MediaTek MT1959 | Supported | 206 | LG, ASUS, HP |
-| Renesas | Planned | -- | Pioneer |
-
-Each profile stores per-drive `unlock_mode` and `unlock_buf_id` — the exact CDB bytes for that drive's unlock command. A single `Mt1959` implementation handles all MediaTek variants.
-
-## Drive Profile
-
-Each bundled profile (compiled into the binary):
-
-```json
-{
-  "vendor_id": "HL-DT-ST",
-  "product_id": "BD-RE BU40N     ",
-  "product_revision": "1.03",
-  "vendor_specific": "NM00000",
-  "firmware_date": "211810241934",
-  "chipset": "mediatek",
-  "unlock_mode": 1,
-  "unlock_buf_id": 68,
-  "signature": "999ec375",
-  "register_offsets": ["10e291", "11ab1c"]
+    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; }
 }
+
+// Mux from the ISO via the normal stream pipeline (no drive involvement).
 ```
 
-## Error Codes
+## What It Does
 
-Structured errors for programmatic handling — no user-facing English text in the library.
+- **Drive access** — open, identify, unlock, firmware upload, speed calibration, eject
+- **12+ MB/s reads** — auto-detects kernel transfer limits, sustained full speed
+- **Disc scanning** — UDF 2.50 filesystem, MPLS playlists, CLPI clip info
+- **Stream labels** — 5 BD-J format parsers (Paramount, Criterion, Pixelogic, CTRM, Deluxe)
+- **AACS decryption** — transparent key resolution and content decrypt (1.0 + 2.0 bus decryption)
+- **KEYDB updates** — download, verify, save from any HTTP URL (zero deps, raw TCP)
+- **Content reading** — adaptive batch reads with automatic decryption
+- **Stream I/O** — unified stream pipeline for reading and writing any format
 
-| Code | Error | Meaning |
-|------|-------|---------|
-| E1000 | DeviceNotFound | Device path doesn't exist |
-| E1001 | DevicePermission | No access (try sudo or cdrom group) |
-| E2000 | UnsupportedDrive | No matching profile |
-| E2001 | ProfileNotFound | Profile lookup failed |
-| E3000 | UnlockFailed | Unlock command rejected |
-| E3001 | SignatureMismatch | Response signature wrong |
-| E3002 | NotUnlocked | Operation requires unlock first |
-| E4000 | ScsiError | SCSI command failed |
-| E5000 | IoError | System I/O error |
+### Streams
+
+| Stream | Input | Output | Transport |
+|--------|-------|--------|-----------|
+| DiscStream | Yes | -- | Optical drive via SCSI |
+| 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 `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.
+
+### Keys
+
+DVDs (CSS) decrypt out of the box — the 1999-era public player keys are compiled into the library.
+
+Blu-rays and UHD (AACS) require a `keydb.cfg` at `~/.config/freemkv/keydb.cfg` (or passed via `ScanOptions`). The file holds all DKs, PKs, host certs, and per-disc VUKs. No AACS key material is compiled into the binary.
 
 ## Architecture
 
-```
-DriveSession
-├── ScsiTransport     SG_IO (Linux) / IOKit (macOS, planned)
-├── DriveProfile      per-drive parameters (bundled JSON, compiled in)
-├── DriveId           INQUIRY + GET_CONFIG 010C fields
-└── Platform
-    ├── Mt1959        MediaTek MT1959 (206 drives)
-    └── (Renesas)     Pioneer (planned)
+```text
+Drive                  — open, identify, init, unlock, single-shot read
+  ├── ScsiTransport    — SG_IO (Linux), IOKit (macOS), SPTI (Windows)
+  ├── DriveProfile     — per-drive unlock parameters (bundled)
+  └── PlatformDriver   — MediaTek (supported), Renesas (planned)
+
+Disc                   — scan titles, streams, AACS/CSS state
+  ├── UDF reader       — Blu-ray UDF 2.50 with metadata partitions
+  ├── MPLS parser      — playlists → titles + clips + streams
+  ├── CLPI parser      — clip info → EP map → sector extents
+  ├── IFO parser       — DVD title sets, PGC chains, cell addresses
+  ├── Labels           — 5 BD-J format parsers (detect + parse)
+  ├── AACS             — key resolution + content decryption
+  ├── CSS              — DVD CSS cipher (table-driven, no keys needed)
+  └── KEYDB            — download + verify + save
+
+Streams                — unified PES pipeline
+  ├── 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
+  ├── M2tsStream       — BD transport stream
+  ├── NetworkStream    — TCP with FMKV metadata header
+  ├── StdioStream      — stdin/stdout pipe
+  └── NullStream       — discard sink
 ```
 
-## Platform
+See [docs/](docs/) for detailed technical documentation on each module.
 
-Linux only today (SG_IO ioctl). The `ScsiTransport` trait abstracts the platform — macOS IOKit and Windows SPTI backends are planned.
+## Error Codes
+
+All errors are structured with numeric codes. No user-facing English text — applications format their own messages.
+
+| Range | Category |
+|-------|----------|
+| E1xxx | Device errors (not found, permission) |
+| E2xxx | Profile errors (unsupported drive) |
+| E3xxx | Unlock errors (failed, signature) |
+| E4xxx | SCSI errors (command failed, timeout) |
+| E5xxx | I/O errors |
+| E6xxx | Disc format errors |
+| E7xxx | AACS errors |
+| E8xxx | KEYDB update errors |
+
+## Platform Support
+
+| Platform | Status | Backend |
+|----------|--------|---------|
+| Linux | Supported | SG_IO ioctl |
+| macOS | Supported | IOKit SCSITask |
+| Windows | Supported | SPTI |
 
 ## Contributing
 
-Run `freemkv info --share` with the [freemkv CLI](https://github.com/freemkv/freemkv) to submit your drive's profile.
+Run `freemkv info disc:// --share` with the [freemkv CLI](https://github.com/freemkv/freemkv) to contribute your drive's profile.
 
 ## License
 

TROUBLESHOOTING.md

@@ -0,0 +1,312 @@
+# Troubleshooting Guide
+
+Common problems and solutions for optical drive ripping with freemkv.
+
+---
+
+## 1. USB-SATA Bridge Issues
+
+This is the single most common source of problems when ripping discs over USB.
+
+### Symptoms
+
+- The drive disappears mid-rip. The ripping tool reports the device is gone, and `ls /dev/sg*` no longer shows it.
+- The device re-enumerates under a different name: `sg4` becomes `sg5`, then `sg7`, then `sg11` after each USB port reset.
+- `dmesg` shows USB port resets: `usb X-Y: reset high-speed USB device`, `xhci_hcd 0000:00:14.0: Cannot enable. Maybe the USB cable is bad?`, or `usb-storage: device reset failed`.
+- The SCSI layer reports `host_status=7` (Linux USB transport error) in sense data.
+- The drive works fine for reading data discs or burning, but crashes when hitting damaged sectors during a rip.
+- After the crash, the drive is completely invisible until physically unplugged and reconnected.
+
+### Root Cause
+
+USB-SATA bridges translate between the USB Mass Storage protocol (BOT or UAS) and the drive's native SATA interface. When the optical drive encounters an unreadable sector, it returns a SCSI CHECK CONDITION with sense key 0x03 (MEDIUM ERROR). Some bridge chipsets -- particularly the Initio INIC-36xx family -- have buggy firmware that mishandles this error response.
+
+Specific failure modes:
+
+- **Incorrect residue reporting.** The bridge claims a different number of bytes transferred than what actually occurred. The Linux USB storage driver sees this discrepancy as a protocol violation and resets the port to recover. The `US_FL_IGNORE_RESIDUE` quirk exists specifically for this class of bug (see `drivers/usb/storage/transport.c` in the Linux kernel).
+- **Bridge firmware crash.** On some Initio bridges, a malformed SCSI error response from the drive causes the bridge MCU to hang entirely. The USB controller sees the device stop responding and initiates a port reset. The bridge recovers (it re-enumerates), but the rip is dead -- all state is lost.
+- **Sense data corruption.** The bridge forwards garbled or truncated sense data to the host, which the SCSI midlayer cannot parse, leading to a transport reset.
+
+This is a hardware + firmware problem, not a software bug. The same drive connected via direct SATA does not exhibit these symptoms.
+
+### Known Affected Bridges
+
+| Chipset | USB IDs | Notes |
+|---------|---------|-------|
+| Initio INIC-3609 | `13fd:3609` | Very common in cheap SATA-to-USB enclosures. Highly problematic. |
+| Initio INIC-3619 | `13fd:3940` | Same firmware family as INIC-3609. |
+| Initio INIC-3069 | `13fd:0840` | Older variant, same residue bug. |
+| ASMedia ASM1051 | `174c:5106` | Early ASM SATA bridge. Residue issues on error paths. |
+| JMicron JMB36x | `152d:0561` | Some firmware versions. Not all JMicroon chips are affected. |
+
+If your drive came in a pre-built external enclosure (Vantec, Sabrent, OWC, etc.), it almost certainly uses one of these bridge chips internally.
+
+### The Fix: USB Storage Quirk
+
+Apply the `US_FL_IGNORE_RESIDUE` kernel quirk for your bridge. This tells the Linux USB storage driver to ignore the residue field in SCSI response frames, preventing the port reset on mismatched byte counts.
+
+**Step 1: Identify your bridge's vendor:product ID.**
+
+```bash
+lsusb
+```
+
+Look for your drive's entry. Example output:
+
+```
+Bus 002 Device 005: ID 13fd:0840 Initio Corporation INIC-3609
+```
+
+Here the vendor ID is `13fd` and the product ID is `0840`.
+
+**Step 2: Apply the quirk at runtime.**
+
+```bash
+echo "13fd:0840:i" > /sys/module/usb_storage/parameters/quirks
+```
+
+Replace `13fd:0840` with your device's actual IDs. The `:i` flag means `US_FL_IGNORE_RESIDUE`.
+
+You can combine multiple flags. Common additions:
+
+- `:i` -- ignore residue (`US_FL_IGNORE_RESIDUE`)
+- `:u` -- force BOT mode instead of UAS, for bridges with UAS bugs
+
+**Step 3: Reconnect the drive.** Unplug and replug the USB cable, or bind/unbind the device. The quirk is applied per-module-load, so existing sessions may need the drive reconnected.
+
+### Making It Persistent
+
+Add the quirk to your kernel boot parameters so it survives reboots.
+
+Edit `/etc/default/grub` (GRUB) and add to `GRUB_CMDLINE_LINUX_DEFAULT`:
+
+```
+GRUB_CMDLINE_LINUX_DEFAULT="quiet usb_storage.quirks=13fd:0840:i"
+```
+
+Then rebuild the GRUB config:
+
+```bash
+sudo update-grub
+```
+
+For systemd-boot, add to your loader entry or `/etc/kernel/cmdline`:
+
+```
+usb_storage.quirks=13fd:0840:i
+```
+
+Multiple devices can be separated by commas:
+
+```
+usb_storage.quirks=13fd:0840:i,174c:5106:u
+```
+
+### Recommended Bridges
+
+If you are buying a USB-SATA adapter or enclosure for optical drive use:
+
+| Bridge | USB IDs | Notes |
+|--------|---------|-------|
+| ASMedia ASM1153 | `174c:1153` | Reliable. Widely available in SATA-USB 3.0 cables. |
+| JMicron JMS578 | `152d:0578` | Good firmware. Supports UASP. |
+| Icy Box IB-AC640-C3 | N/A | Uses a known-good bridge internally. Plug-and-play. |
+
+Avoid any enclosure or adapter listing an Initio chipset.
+
+### Best Solution: Direct SATA
+
+Connect your optical drive directly to a motherboard SATA port. This eliminates the USB-SATA bridge entirely and is the most reliable configuration:
+
+- No USB protocol overhead or translation errors.
+- No bridge firmware bugs.
+- No port resets or re-enumeration.
+- Full SATA error recovery handled natively by the kernel's libata driver.
+- Sustained read speeds are limited only by the drive, not the USB bus.
+
+If your machine has a free SATA port, use it.
+
+---
+
+## 2. Damaged Disc Handling
+
+### Symptoms
+
+- SCSI MEDIUM ERROR (sense key 0x03) at specific LBAs. `dmesg` shows `sr X:0:0:0: [srY] Unrecoverable read error` or similar.
+- Read speed drops to near zero when approaching a damaged area.
+- The drive makes audible retrying noises (laser repositioning, spindle speed changes).
+- On USB-connected drives: the bridge crashes (see section 1 above) when the drive returns the error.
+
+### How freemkv Handles This
+
+freemkv uses a three-layer recovery model. See [`docs/rip-recovery.md`](docs/rip-recovery.md) for full details.
+
+- **Pass 1 (Disc::copy):** Fast sweep with 64 KB reads. On failure, zero-fills the block and skips forward. Writes a ddrescue-format mapfile for later retry.
+- **Pass 2+ (Disc::patch):** Targeted re-reads of bad ranges with a long 30-second timeout per CDB. The drive firmware performs its own ECC and laser power retries within that window.
+- **In-stream (DiscStream):** Adaptive batch halving -- reduces request size on failure to isolate bad sectors within a larger block.
+
+This means a disc with some bad sectors will still produce a usable ISO. The damaged areas are zero-filled in pass 1 and retried in subsequent passes. Structure-protected sectors (deliberate unreadable regions from copy protection) will never yield, which is expected.
+
+### The Drive Taint Issue (LG BU40N)
+
+Some drives, notably the LG BU40N, exhibit a "taint" behavior after encountering MEDIUM ERRORs:
+
+1. The drive hits a damaged sector and returns a MEDIUM ERROR.
+2. From that point forward, **all subsequent reads fail** -- even reads to sectors that were previously successful.
+3. The only recovery is to physically unplug and reconnect the drive (or power-cycle it).
+
+This is not a freemkv bug. It is a drive firmware behavior triggered by the interaction between the drive's internal error recovery and the USB-SATA bridge's handling of the error response. The drive firmware enters a degraded state that it does not recover from without a power cycle.
+
+Workarounds:
+
+- **Use a direct SATA connection.** This eliminates the bridge interaction that triggers the taint.
+- **Use a different bridge.** The ASM1153 and JMS578 are less likely to trigger this behavior.
+- **Accept the partial ISO.** freemkv's skip-forward recovery will zero-fill the unreadable blocks and continue. The resulting ISO may be playable with minor glitches in the affected areas.
+- **Physical replug between retry passes.** If running multi-pass patch, replug the drive between passes to clear the taint state.
+
+freemkv deliberately does not attempt inline SCSI resets or eject cycles to recover from this state, because those operations were found to make the problem worse on affected hardware (see the design rationale in [`docs/rip-recovery.md`](docs/rip-recovery.md)).
+
+---
+
+## 3. Drive Not Detected
+
+### Check Hardware Visibility
+
+```bash
+lsusb
+```
+
+Verify the drive appears in the USB device list. If it does not show up, the drive is not visible to the host at all -- check cables, power, and USB port.
+
+```bash
+ls /dev/sg*
+```
+
+On Linux, optical drives appear as `/dev/sg*` devices (the SCSI Generic interface). freemkv uses `/dev/sg*`, not `/dev/sr*`. If `lsusb` shows the device but no `/dev/sg*` entry exists, the `sg` kernel module may not be loaded:
+
+```bash
+sudo modprobe sg
+```
+
+### Check Kernel Messages
+
+```bash
+dmesg | grep -i usb | tail -30
+dmesg | grep -i sg | tail -10
+```
+
+Look for:
+- USB enumeration errors or failed port resets.
+- `sg_add` messages confirming the sg device was registered.
+- Permission denied or access errors.
+
+### Permission Issues
+
+On most Linux distributions, `/dev/sg*` devices are owned by `root:disk` or `root:cdrom` with restricted permissions. Running freemkv as an unprivileged user will fail with permission errors.
+
+Options:
+
+- Add your user to the appropriate group:
+
+  ```bash
+  sudo usermod -aG disk $USER
+  ```
+
+  Then log out and back in for the change to take effect. On some distributions the group is `cdrom` or `optical` instead of `disk`.
+
+- Run with elevated privileges:
+
+  ```bash
+  sudo freemkv ...
+  ```
+
+- Install a udev rule for persistent per-device permissions. Create `/etc/udev/rules.d/99-sg-optical.rules`:
+
+  ```
+  SUBSYSTEM=="scsi_generic", ATTRS{type}=="5", MODE="0666"
+  ```
+
+  Then reload udev rules:
+
+  ```bash
+  sudo udevadm control --reload-rules && sudo udevadm trigger
+  ```
+
+### Spin-Up Delay
+
+Optical drives take 30-60 seconds to spin up and become ready after hot-plug or disc insertion. During this window, SCSI commands may return NOT READY or timeout.
+
+freemkv's `Drive::wait_ready()` handles this automatically by polling with TEST UNIT READY until the drive responds. If you are writing your own code using the library, always call `wait_ready()` before `init()`:
+
+```rust
+let mut drive = Drive::open(Path::new("/dev/sg4"))?;
+drive.wait_ready()?;  // blocks until disc is ready, up to 30s
+drive.init()?;
+```
+
+If the drive was just plugged in, wait a full minute before concluding it is not detected.
+
+---
+
+## 4. How to Identify Your USB-SATA Bridge
+
+If you are experiencing the issues described in section 1, you need to know which bridge chipset your adapter or enclosure uses.
+
+### Step 1: Find the Device
+
+```bash
+lsusb
+```
+
+Look for entries matching your drive or enclosure. Bridges may appear under their own manufacturer name or as a generic SATA device. Common examples:
+
+```
+Bus 002 Device 005: ID 13fd:0840 Initio Corporation
+Bus 002 Device 006: ID 174c:1153 ASMedia Technology Inc. ASM1153
+Bus 002 Device 007: ID 152d:0578 JMicron Technology Corp. JMS578
+```
+
+### Step 2: Match the IDs
+
+| Vendor | Product ID | Chipset | Status |
+|--------|-----------|---------|--------|
+| `13fd` | `3609` | Initio INIC-3609 | Affected. Apply quirk. |
+| `13fd` | `3940` | Initio INIC-3619 | Affected. Apply quirk. |
+| `13fd` | `0840` | Initio INIC-3069 | Affected. Apply quirk. |
+| `174c` | `5106` | ASMedia ASM1051 | Affected (early firmware). Apply quirk. |
+| `174c` | `1153` | ASMedia ASM1153 | Good. No quirk needed. |
+| `152d` | `0561` | JMicron JMB36x | Affected (some firmware). Apply quirk if issues occur. |
+| `152d` | `0578` | JMicron JMS578 | Good. No quirk needed. |
+
+### Step 3: Check dmesg for the Bridge Name
+
+```bash
+dmesg | grep -i "usb-storage\|uas\|initio\|asmedia\|jmicron"
+```
+
+This often reveals the bridge chipset even when `lsusb` shows a generic name.
+
+### Step 4: If the Enclosure Is Sealed
+
+Many external drive enclosures (Vantec NexStar, Sabrent, OWC, etc.) do not advertise the bridge chipset on the packaging. In this case:
+
+1. Check `lsusb` while the enclosure is connected.
+2. Search the vendor:product ID online -- there are community-maintained lists of which chipsets popular enclosures use.
+3. If you cannot determine the chipset and are experiencing bridge crashes, assume it is an Initio and apply the quirk with its IDs.
+4. The definitive test: connect the bare drive to a motherboard SATA port. If the problems disappear, the bridge was the cause.
+
+---
+
+## 5. General Debugging Checklist
+
+When something goes wrong during a rip, gather this information before filing an issue:
+
+1. **freemkv version:** `freemkv --version` or the crate version in `Cargo.toml`.
+2. **Drive model:** from the drive label, or from `freemkv info`.
+3. **Connection type:** USB (with bridge chipset if known) or direct SATA.
+4. **Operating system and kernel:** `uname -a`.
+5. **Kernel messages during the failure:** `dmesg | tail -50` immediately after the crash.
+6. **SCSI device:** which `/dev/sg*` the drive was on, and whether it changed after the failure.
+7. **The disc:** title, format (BD/DVD/UHD), condition.
+
+Include all of the above in bug reports. SCSI transport errors that resolve with the `US_FL_IGNORE_RESIDUE` quirk or by switching to direct SATA are bridge firmware bugs, not freemkv bugs.

benches/sgio_read.rs

@@ -0,0 +1,87 @@
+// Mimics ISO dump exactly — read + write + progress
+use libfreemkv::Drive;
+use std::io::Write;
+use std::path::Path;
+use std::time::Instant;
+
+fn main() {
+    let device = std::env::args()
+        .skip(1)
+        .find(|a| !a.starts_with('-'))
+        .unwrap_or_else(|| match libfreemkv::find_drive() {
+            Some(d) => d.device_path().to_string(),
+            None => {
+                eprintln!("No drives found");
+                std::process::exit(1);
+            }
+        });
+
+    let mut drive = Drive::open(Path::new(&device)).unwrap_or_else(|e| {
+        eprintln!("Cannot open {}: {}", device, e);
+        std::process::exit(1);
+    });
+    eprintln!("wait_ready...");
+    let _ = drive.wait_ready();
+    eprintln!("read_capacity...");
+    let cap = drive.read_capacity().unwrap();
+    eprintln!("capacity: {} sectors", cap);
+
+    let batch = libfreemkv::disc::detect_max_batch_sectors(drive.device_path());
+    let mut buf = vec![0u8; batch as usize * 2048];
+
+    // Open /dev/null writer like ISO dump does
+    let file = std::fs::File::create("/dev/null").unwrap();
+    let mut writer = std::io::BufWriter::with_capacity(4 * 1024 * 1024, file);
+
+    eprintln!(
+        "Reading 1000 batches ({:.1} MB) with write + progress...",
+        1000.0 * batch as f64 * 2048.0 / 1_048_576.0
+    );
+
+    let start = Instant::now();
+    let mut ok = 0u32;
+    let mut fail = 0u32;
+    let mut bytes: u64 = 0;
+
+    // Recovery flag: true matches pre-0.11.13 bench behavior — full SCSI
+    // ECC retry loop on errors (slower, what the rip path used before the
+    // adaptive batch sizer landed). Flip to `false` for the fast-fail path
+    // that current rips use; benches are configurable via this constant.
+    const READ_WITH_RECOVERY: bool = true;
+
+    for i in 0..1000u32 {
+        let lba = i * batch as u32;
+        match drive.read(lba, batch, &mut buf, READ_WITH_RECOVERY) {
+            Ok(_) => {
+                writer.write_all(&buf).unwrap();
+                ok += 1;
+            }
+            Err(e) => {
+                fail += 1;
+                if fail <= 5 {
+                    eprintln!("  FAIL LBA {}: {}", lba, e);
+                }
+                buf.fill(0);
+                writer.write_all(&buf).unwrap();
+            }
+        }
+        bytes += buf.len() as u64;
+
+        if i % 50 == 0 && i > 0 {
+            let elapsed = start.elapsed().as_secs_f64();
+            let mb = bytes as f64 / 1_048_576.0;
+            eprint!("\r  {:.1} MB | {:.1} MB/s    ", mb, mb / elapsed);
+        }
+    }
+
+    let elapsed = start.elapsed().as_secs_f64();
+    let mb = ok as f64 * batch as f64 * 2048.0 / 1_048_576.0;
+    eprintln!(
+        "\n{} ok, {} fail, {:.1} MB in {:.1}s = {:.1} MB/s",
+        ok,
+        fail,
+        mb,
+        elapsed,
+        mb / elapsed
+    );
+}

build.rs

@@ -0,0 +1,36 @@
+fn main() {
+    let target = std::env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
+    if target == "macos" {
+        println!("cargo:rustc-link-lib=framework=IOKit");
+        println!("cargo:rustc-link-lib=framework=CoreFoundation");
+
+        let out_dir = std::env::var("OUT_DIR").unwrap();
+        let obj = format!("{out_dir}/macos_shim.o");
+        let lib = format!("{out_dir}/libmacos_scsi.a");
+
+        std::process::Command::new("cc")
+            .args([
+                "-c",
+                "src/scsi/macos_shim.c",
+                "-o",
+                &obj,
+                "-framework",
+                "IOKit",
+                "-framework",
+                "CoreFoundation",
+                "-Wall",
+                "-O2",
+            ])
+            .status()
+            .expect("failed to compile macos_shim.c");
+
+        std::process::Command::new("ar")
+            .args(["rcs", &lib, &obj])
+            .status()
+            .expect("failed to create static lib");
+
+        println!("cargo:rustc-link-search=native={out_dir}");
+        println!("cargo:rustc-link-lib=static=macos_scsi");
+        println!("cargo:rerun-if-changed=src/scsi/macos_shim.c");
+    }
+}

ci/leak-guard.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+#
+# leak-guard.sh — self-contained public-repo leak gate.
+#
+# This is the LAST line of defense in CI. It is intentionally self-contained:
+# public CI cannot reach the private tooling, so this script encodes ONLY the
+# generic net — internal infrastructure references, agent-context files, and
+# AI-attribution in commit messages. It deliberately contains NO project-
+# specific reverse-engineering vocabulary (those words would themselves be a
+# leak). The richer private scanner stays private.
+#
+# Fails (exit 1) if any of the following appear in the repo:
+#   1. a tracked CLAUDE.md or .claude/ path (agent context — never public),
+#   2. tracked file content matching the internal-infra net,
+#   3. a commit message (in the given range) with AI attribution.
+#
+# Usage:
+#   leak-guard.sh [<commit-range>]
+#     <commit-range>  optional git rev-list range to scan commit messages
+#                     (e.g. "abc..def"). If omitted, commit-message scan is
+#                     skipped (path + content checks always run).
+
+set -euo pipefail
+
+# Absolute path to this script, resolved before any cd, so we can exclude it
+# from the content scan (it necessarily contains the detection patterns).
+SELF_ABS="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/$(basename "${BASH_SOURCE[0]}")"
+
+REPO="$(git rev-parse --show-toplevel)"
+cd "$REPO"
+
+fail=0
+note() { printf '  ✗ %s\n' "$1"; fail=1; }
+
+# Internal-infra net — GENERIC ONLY. This script ships in the public repo, so
+# the patterns themselves must not name any org-specific identifier (doing so
+# would itself leak the infra they guard). We catch the leak *class*:
+#   - RFC1918 private IPv4 ranges (10/8, 172.16/12, 192.168/16),
+#   - private/internal/non-routable TLDs (.internal/.local/.lan/.corp/.invalid),
+#   - docker.internal.
+# The full org-specific net (literal hostnames, service names, repo paths,
+# vendor tooling, …) lives ONLY in the private scanner and never ships here.
+INFRA_RE='\b10\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}|\b172\.(1[6-9]|2[0-9]|3[01])\.[0-9]{1,3}\.[0-9]{1,3}|\b192\.168\.[0-9]{1,3}\.[0-9]{1,3}|\.internal\b|\.local\b|\.lan\b|\.corp\b|\.invalid\b|docker\.internal'
+# Home-path net — GENERIC ONLY. Catches an absolute developer home path
+# committed into a tracked file (a macOS /Users/<user>/… or Linux /home/<user>/…
+# path). This names NO specific user — it matches the leak *class* (any home
+# path), so the pattern itself reveals nothing org- or person-specific. A real
+# leak (e.g. /Users/alice/Developer/x slipping into a public RELEASE.md) trips
+# this regardless of whose machine it came from. The username segment is a
+# literal-username class ([A-Za-z0-9._-]) so dynamic/templated paths that build
+# the user at runtime — shell `/home/$USER/`, doc `/home/<rip>/`, Rust
+# `/home/{user}/` — do NOT false-positive; only a baked-in literal home leaks.
+HOMEPATH_RE='/Users/[A-Za-z0-9._-]+/|/home/[A-Za-z0-9._-]+/'
+# AI-attribution net (case-insensitive). "claude" matches only as a standalone
+# word — NOT preceded by a dot/slash/alnum and NOT followed by .md — so legit
+# mentions of CLAUDE.md / .claude/ in a commit message don't false-positive.
+ATTR_RE='co-authored-by|generated with|🤖|(?<![.\/A-Za-z0-9])claude(?!\.md)'
+
+echo "── leak-guard: tracked agent-context paths ──"
+while IFS= read -r f; do
+  case "$f" in
+    CLAUDE.md|*/CLAUDE.md|.claude|.claude/*|*/.claude|*/.claude/*)
+      note "tracked agent-context file: $f (CLAUDE.md/.claude must never be tracked in a public repo)" ;;
+  esac
+done < <(git ls-files)
+
+# Match a PCRE against a file, emitting "LINE: MATCH". The pattern is passed as
+# an argument (not interpolated into a //) so metacharacters like the "/" in a
+# path-style token can't break the regex. Reads raw bytes so non-UTF-8 blobs
+# don't abort the scan.
+pcre_matches() {
+  perl -e '
+    my ($file, $re) = @ARGV;
+    open(my $fh, "<:raw", $file) or exit 0;
+    my $rx; eval { $rx = qr/$re/i }; exit 0 if $@;
+    while (my $l = <$fh>) { if ($l =~ /$rx/) { print "$.: $&\n"; } }
+  ' "$1" "$2" 2>/dev/null
+}
+
+# This script's own source necessarily contains the detection patterns (e.g.
+# the regex tokens in INFRA_RE), so scanning it would always self-flag. Skip it.
+SELF="$(git ls-files --full-name -- "$SELF_ABS" 2>/dev/null | head -1)"
+
+echo "── leak-guard: internal-infra references in tracked files ──"
+while IFS= read -r f; do
+  case "$f" in *.png|*.jpg|*.jpeg|*.ico|*.gif|*.bin|*.crate|*.gz|*.zip|*.pdf) continue ;; esac
+  [ -n "$SELF" ] && [ "$f" = "$SELF" ] && continue
+  [ -f "$f" ] || continue
+  while IFS= read -r hit; do
+    [ -z "$hit" ] && continue
+    note "internal-infra reference: $f:$hit"
+  done < <(pcre_matches "$f" "$INFRA_RE")
+  while IFS= read -r hit; do
+    [ -z "$hit" ] && continue
+    note "[HOME-PATH] absolute home path: $f:$hit (no local home path may be committed to a public repo)"
+  done < <(pcre_matches "$f" "$HOMEPATH_RE")
+done < <(git ls-files)
+
+RANGE="${1:-}"
+if [ -n "$RANGE" ]; then
+  echo "── leak-guard: AI-attribution in commit messages ($RANGE) ──"
+  while IFS= read -r sha; do
+    [ -z "$sha" ] && continue
+    msg="$(git log -1 --format='%B' "$sha" 2>/dev/null || true)"
+    # Pass the pattern as an argument (not interpolated into a //) so the
+    # lookbehind char class and "/" don't break the regex.
+    hit="$(printf '%s' "$msg" | perl -e '
+      my $re = $ARGV[0]; my $rx = qr/$re/i;
+      while (my $l = <STDIN>) { if ($l =~ /($rx)/) { print "$1\n"; last; } }
+    ' "$ATTR_RE" | head -1 || true)"
+    [ -n "$hit" ] && note "commit ${sha:0:12}: message contains \"$hit\" (owner rule: zero AI attribution, ever)"
+  done < <(git rev-list "$RANGE" 2>/dev/null || true)
+fi
+
+echo
+if [ "$fail" -ne 0 ]; then
+  echo "✗ leak-guard: blocking finding(s) above — DO NOT MERGE/PUBLISH"
+  exit 1
+fi
+echo "✓ leak-guard: clean"

docs/README.md

@@ -0,0 +1,34 @@
+# libfreemkv Documentation
+
+Technical documentation for [libfreemkv](https://github.com/freemkv/libfreemkv), the open source optical drive library.
+
+## Start Here
+
+**[Disc to Rip: End-to-End Flow](disc-to-rip.md)** — How the library goes from a disc in the drive to decrypted content. Read this first.
+
+## Reference
+
+| Document | What it covers |
+|----------|---------------|
+| [Architecture](architecture.md) | Module map, design principles, error codes, platform support |
+| [Drive Access](drive-access.md) | Drive, SCSI transport, profiles, unlock, why raw mode is needed |
+| [Rip Recovery](rip-recovery.md) | Three-layer recovery model: Disc::patch, single-shot Drive::read, DiscStream batch halving |
+| [AACS Encryption](aacs.md) | Key resolution (4 paths), content decryption, bus encryption, SCSI handshake |
+| [UDF Filesystem](udf.md) | UDF 2.50 with metadata partitions, pointer chain, how files are read from disc |
+| [MPLS Playlists](mpls.md) | Playlist format, play items, STN stream table, coding types |
+| [CLPI Clip Info](clpi.md) | EP map (coarse + fine entries), timestamp-to-sector mapping, extent calculation |
+| [API Design](api-design.md) | Stream API design, PES pipeline, input/output resolution |
+
+## Reading Order
+
+If you want to understand the whole library:
+
+1. **[Disc to Rip](disc-to-rip.md)** — the big picture
+2. **[Architecture](architecture.md)** — how modules fit together
+3. **[Drive Access](drive-access.md)** — how we talk to hardware
+4. **[UDF](udf.md)** → **[MPLS](mpls.md)** → **[CLPI](clpi.md)** — how disc content is structured
+5. **[AACS](aacs.md)** — how encryption works and how we break it
+
+## API Documentation
+
+Generated API docs are on [docs.rs/libfreemkv](https://docs.rs/libfreemkv).

docs/aacs.md

@@ -0,0 +1,322 @@
+# AACS Encryption Support
+
+## Overview
+
+AACS (Advanced Access Content System) is the encryption layer used by Blu-ray and UHD 4K discs to protect content. libfreemkv implements AACS decryption to enable transparent disc access.
+
+There are two major versions:
+
+- **AACS 1.0** -- Used by standard Blu-ray discs. Relies on a custom 160-bit elliptic curve for bus authentication and AES-128 for content encryption. Processing keys and device keys can derive the media key from the disc's Media Key Block (MKB).
+
+- **AACS 2.0** -- Used by UHD 4K Blu-ray discs. Adds a per-sector bus encryption layer (read_data_key) on top of the standard content encryption. Uses P-256/SHA-256 for its native handshake, though drives accept AACS 1.0 host certificates for backward compatibility.
+
+Both versions use AES-128-CBC for content decryption with a fixed initialization vector. The fundamental key hierarchy is the same: a Volume Unique Key (VUK) decrypts per-title unit keys, which in turn decrypt the content stream.
+
+
+## Architecture
+
+AACS support is split across two modules:
+
+### `aacs.rs` -- Keys and Decryption
+
+Handles everything related to key resolution and content decryption:
+
+- KEYDB.cfg parsing (device keys, processing keys, host certificates, per-disc entries)
+- Disc hash computation (SHA-1 of `Unit_Key_RO.inf`)
+- VUK resolution chain (4 paths, described below)
+- MKB record parsing and media key derivation
+- Subset-difference tree traversal (AACS-G3 key derivation)
+- Unit_Key_RO.inf parsing and unit key decryption
+- Content Certificate parsing (AACS version detection)
+- Aligned unit decryption (AES-128-CBC)
+- Bus decryption (AACS 2.0 read_data_key layer)
+
+### `aacs_handshake.rs` -- SCSI Authentication
+
+Handles the drive-level SCSI authentication protocol:
+
+- ECDH key agreement on the AACS 160-bit curve
+- ECDSA signing and verification
+- Bus key derivation
+- AGID management (allocate/invalidate)
+- Volume ID retrieval (encrypted with bus key, verified by AES-CMAC)
+- Read Data Key retrieval (for AACS 2.0 bus decryption)
+- AACS LA public key certificate verification
+
+
+## Key Resolution Chain
+
+When a disc is scanned, `resolve_keys()` attempts four paths in priority order. The first path that succeeds is used.
+
+### Path 1: KEYDB VUK Lookup (fastest)
+
+```
+Unit_Key_RO.inf --> SHA-1 --> disc_hash --> KEYDB lookup --> VUK
+```
+
+The disc hash is computed as the SHA-1 digest of the raw `Unit_Key_RO.inf` file from the disc's `/AACS/` directory. This hash is used as the lookup key in `KEYDB.cfg`. If a matching entry contains a VUK (`V` field), it is used directly.
+
+This is the fast path and resolves the vast majority of discs in a well-maintained KEYDB.
+
+### Path 2: KEYDB Media Key + Volume ID
+
+```
+KEYDB media_key + Volume ID (from SCSI handshake) --> VUK derivation
+```
+
+If the disc hash is not in the KEYDB but a KEYDB entry has a matching Volume ID (`I` field) and a media key (`M` field), the VUK is derived:
+
+```
+VUK = AES-128-ECB-DECRYPT(media_key, volume_id) XOR volume_id
+```
+
+Requires a successful SCSI handshake to obtain the Volume ID.
+
+### Path 3: MKB + Processing Keys
+
+```
+MKB (from disc) + processing_keys (from KEYDB) --> media_key --> VUK
+```
+
+Processing keys are pre-computed keys that work against specific MKB versions. For each processing key, the library:
+
+1. Parses the MKB to extract the Verify Media Key Record (`mk_dv`), subset-difference index, and conditional values (cvalues).
+2. Tries each processing key against each UV/cvalue pair: `mk = AES-DEC(pk, cvalue) XOR cvalue`.
+3. Validates the derived media key: `AES-ECB(mk, mk_dv)` must produce 12 leading zero bytes.
+4. Derives VUK from the validated media key and Volume ID.
+
+### Path 4: MKB + Device Keys (Subset-Difference Tree)
+
+```
+MKB + device_keys --> subset-difference tree traversal --> processing_key --> media_key --> VUK
+```
+
+The most complex path. Each device key has an associated node number, UV value, and mask parameters that position it in the AACS subset-difference tree. The library:
+
+1. Finds the subset-difference entry in the MKB that applies to the device key's node.
+2. Traverses the tree using AACS-G3 key derivation: `aesg3(key, inc) = AES-DEC(key, seed) XOR seed`, where `seed[15]` is incremented by `inc`. Each tree node produces a left child (inc=0), a processing key (inc=1), and a right child (inc=2).
+3. At each level, selects left or right based on the UV bit at the current position.
+4. The resulting processing key is validated against the MKB cvalue to derive the media key.
+5. VUK is derived from the media key and Volume ID.
+
+
+## Content Decryption
+
+### Aligned Units
+
+AACS encrypts content in aligned units of 6144 bytes (3 sectors of 2048 bytes each). The encryption flag is signaled by the copy_permission_indicator bits in byte 0 of the unit (`unit[0] & 0xC0 != 0`).
+
+### Per-Unit Key Derivation
+
+Each aligned unit has its own decryption key derived from the CPS unit key:
+
+1. **Derive**: AES-128-ECB encrypt the first 16 bytes of the unit (plaintext TP_extra_header) with the unit key.
+2. **XOR**: XOR the encrypted result with the original 16 bytes to produce the per-unit decryption key.
+3. **Decrypt**: AES-128-CBC decrypt bytes 16 through 6143 using the per-unit key and the fixed AACS IV.
+4. **Clear flag**: Clear the encryption indicator bits (`unit[0] &= !0xC0`).
+
+### Fixed IV
+
+All AES-CBC operations in AACS use the same fixed initialization vector, defined in the AACS specification.
+
+### Verification
+
+After decryption, the library verifies correctness by checking for MPEG-TS sync bytes (0x47) at the expected 192-byte packet boundaries within the unit. Blu-ray transport stream packets are 192 bytes: 4-byte TP_extra_header followed by a 188-byte TS packet.
+
+
+## Bus Encryption
+
+### AACS 1.0
+
+Standard Blu-ray discs do not use bus encryption. Content is read directly from the disc and decrypted using the unit key.
+
+### AACS 2.0
+
+UHD 4K discs add a per-sector bus encryption layer. The drive encrypts data as it is read from the disc, and the host must decrypt it before applying AACS content decryption.
+
+Bus encryption uses a **read_data_key** obtained during the SCSI handshake. For each 2048-byte sector within an aligned unit, bytes 16 through 2047 are AES-128-CBC encrypted with the read_data_key and the fixed AACS IV. The first 16 bytes of each sector remain plaintext.
+
+The full decryption pipeline for AACS 2.0:
+
+1. **Bus decrypt**: For each sector, AES-128-CBC decrypt bytes 16..2047 with the read_data_key.
+2. **Content decrypt**: Standard per-unit key derivation and AES-128-CBC decryption as described above.
+
+
+## SCSI Handshake
+
+The AACS SCSI authentication handshake establishes a shared bus key between host and drive, then uses it to securely transfer the Volume ID and read data keys.
+
+### Protocol Flow
+
+1. **Invalidate AGIDs**: Send REPORT KEY with format 0x3F for AGIDs 0-3 to clear stale sessions.
+2. **Allocate AGID**: REPORT KEY format 0x00 returns a fresh Authentication Grant ID.
+3. **Send host credentials**: SEND KEY format 0x01 transmits the host nonce (20 random bytes) and host certificate (92 bytes).
+4. **Receive drive credentials**: REPORT KEY format 0x01 returns the drive nonce and drive certificate.
+5. **Receive drive key**: REPORT KEY format 0x02 returns the drive's ephemeral EC key point and ECDSA signature over `host_nonce || drive_key_point`.
+6. **Verify drive key**: The signature is verified against the drive's public key (extracted from its certificate). AACS 1.0 certificates are verified against the AACS LA public key.
+7. **Send host key**: The host generates an ephemeral key pair, signs `drive_nonce || host_key_point` with the host private key, and sends via SEND KEY format 0x02.
+8. **Compute bus key**: ECDH shared secret = `host_private_key * drive_key_point`. The bus key is the low 128 bits of the shared point's x-coordinate.
+
+### Post-Authentication Reads
+
+- **Volume ID**: REPORT DISC STRUCTURE format 0x80. Returns 16-byte VID encrypted with the bus key, plus an AES-CMAC MAC for integrity verification.
+- **Read Data Keys**: REPORT DISC STRUCTURE format 0x84. Returns the read_data_key and write_data_key, each AES-ECB encrypted with the bus key.
+
+### Elliptic Curve
+
+AACS 1.0 uses a custom 160-bit Weierstrass curve (`y^2 = x^3 + ax + b mod p`) with 20-byte field elements. The library implements full EC arithmetic: point addition, doubling, scalar multiplication, modular inverse, ECDSA sign/verify, and ECDH key agreement.
+
+
+## AACS 2.0 Status
+
+AACS 2.0 discs are detected via the Content Certificate file (`Content000.cer` or `Content001.cer`). A certificate type byte of 0x01 indicates AACS 2.0.
+
+AACS 2.0 drives are identified by their drive certificate type (0x11). These drives natively use P-256/SHA-256, but accept AACS 1.0 host certificates for backward compatibility.
+
+Current implementation status:
+
+- AACS 2.0 detection: **implemented** (Content Certificate parsing, drive cert type check)
+- AACS 1.0 handshake with AACS 2.0 drives: **implemented** (backward compatibility mode)
+- Full P-256 AACS 2.0 handshake: **not yet implemented** (prepared but rarely needed since drives accept AACS 1.0 host certs)
+- Bus decryption with read_data_key: **implemented**
+- Content decryption: **implemented** (same as AACS 1.0)
+
+In practice, AACS 2.0 UHD discs work through the backward-compatible AACS 1.0 handshake path, with the addition of read_data_key bus decryption.
+
+
+## API Usage
+
+AACS decryption is transparent to the application. The `Disc::scan()` method handles everything automatically:
+
+```rust
+use libfreemkv::{Drive, Disc};
+use libfreemkv::disc::ScanOptions;
+use std::path::Path;
+
+let mut drive = Drive::open(Path::new("/dev/sg4")).unwrap();
+drive.wait_ready().unwrap();
+drive.init().unwrap();
+let disc = Disc::scan(&mut drive, &ScanOptions::default()).unwrap();
+
+// Check encryption state
+if disc.encrypted {
+    if let Some(ref aacs) = disc.aacs {
+        println!("AACS {}.0", aacs.version);
+        println!("Key source: {}", aacs.key_source.name());
+        println!("Disc hash: {}", aacs.disc_hash);
+        if let Some(mkb_ver) = aacs.mkb_version {
+            println!("MKB version: {}", mkb_ver);
+        }
+    } else {
+        println!("Encrypted but keys not available");
+    }
+}
+
+// Read content -- decryption is automatic
+let mut reader = disc.open_title(&mut session, 0).unwrap();
+while let Some(unit) = reader.read_unit().unwrap() {
+    // unit is 6144 bytes of decrypted content
+}
+```
+
+The application never touches keys, never calls decryption functions, and never manages handshakes. All of that is internal to `Disc::scan()` and `ContentReader::read_unit()`.
+
+### KEYDB Location
+
+`ScanOptions` controls where the KEYDB is loaded from. If no explicit path is set, the library checks:
+
+1. `~/.config/aacs/KEYDB.cfg`
+2. `/etc/aacs/KEYDB.cfg`
+
+To specify an explicit path:
+
+```rust
+let opts = ScanOptions::with_keydb("/path/to/KEYDB.cfg");
+let disc = Disc::scan(&mut session, &opts).unwrap();
+```
+
+### AacsState
+
+After a successful scan, `disc.aacs` contains an `AacsState` with:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `version` | `u8` | AACS version (1 or 2) |
+| `bus_encryption` | `bool` | Whether bus encryption is active |
+| `mkb_version` | `Option<u32>` | MKB version from disc |
+| `disc_hash` | `String` | SHA-1 of Unit_Key_RO.inf (hex with 0x prefix) |
+| `key_source` | `KeySource` | How keys were resolved |
+| `vuk` | `[u8; 16]` | Volume Unique Key |
+| `unit_keys` | `Vec<(u32, [u8; 16])>` | Decrypted unit keys (CPS unit number, key) |
+| `read_data_key` | `Option<[u8; 16]>` | AACS 2.0 bus decryption key |
+| `volume_id` | `[u8; 16]` | Volume ID from SCSI handshake |
+
+### KeySource
+
+| Variant | Description |
+|---------|-------------|
+| `KeyDb` | VUK found directly in KEYDB by disc hash |
+| `KeyDbDerived` | Media key + Volume ID from KEYDB, VUK derived |
+| `ProcessingKey` | MKB + processing keys from KEYDB |
+| `DeviceKey` | MKB + device keys, subset-difference tree traversal |
+
+
+## KEYDB.cfg Format Reference
+
+The KEYDB.cfg file contains all cryptographic material needed for AACS decryption. Lines starting with `;` or `#` are comments.
+
+### Device Keys
+
+```
+| DK | DEVICE_KEY 0x<key> | DEVICE_NODE 0x<node> | KEY_UV 0x<uv> | KEY_U_MASK_SHIFT 0x<shift>
+```
+
+- `key`: 16-byte AES device key (hex)
+- `node`: Device node number in the subset-difference tree (hex)
+- `uv`: UV value for tree positioning (hex)
+- `shift`: U mask shift value (hex)
+
+### Processing Keys
+
+```
+| PK | 0x<key>
+```
+
+- `key`: 16-byte pre-computed processing key (hex)
+
+### Host Certificate
+
+```
+| HC | HOST_PRIV_KEY 0x<privkey> | HOST_CERT 0x<cert>
+```
+
+- `privkey`: 20-byte ECDSA private key (hex)
+- `cert`: 92-byte AACS host certificate (hex)
+
+The host certificate is used for SCSI authentication. It contains the host's public key and is signed by the AACS Licensing Administrator.
+
+### Disc Entries
+
+```
+0x<disc_hash> = <title> | D | <date> | M | 0x<media_key> | I | 0x<disc_id> | V | 0x<vuk> | U | <unit_keys>
+```
+
+- `disc_hash`: 20-byte SHA-1 of Unit_Key_RO.inf (hex)
+- `title`: Human-readable disc title
+- `D`: Date tag, followed by release/rip date
+- `M`: Media key tag, followed by 16-byte media key (hex)
+- `I`: Disc ID tag, followed by 16-byte Volume ID (hex)
+- `V`: VUK tag, followed by 16-byte Volume Unique Key (hex)
+- `U`: Unit keys tag, followed by space-separated `<unit_num>-0x<key>` pairs
+
+All fields after the title are optional. A minimal entry needs only the disc hash and VUK:
+
+```
+0x<disc_hash> = <title> | V | 0x<vuk>
+```
+
+Inline comments are supported with `;`:
+
+```
+0x<disc_hash> = <title> | V | 0x<vuk> ; MKBv77
+```

docs/api-design.md

@@ -0,0 +1,235 @@
+# libfreemkv API Design
+
+## Principles
+
+1. Lib provides building blocks. App composes them.
+2. No English text in lib. Error codes only. App handles i18n.
+3. No display logic in lib. App decides what to show.
+4. Streams are the pipeline. Each stage wraps the next.
+5. Lib fires events. App listens.
+
+## Core API
+
+```rust
+// Open drive — explicit steps, app prints between them
+let mut drive = Drive::open(path)?;
+drive.wait_ready()?;
+drive.init()?;
+drive.probe_disc()?;
+
+// Scan disc
+let disc = Disc::scan(&mut drive, &ScanOptions::default())?;
+
+// Browse
+disc.titles      // Vec<DiscTitle>
+disc.format      // BD / UHD / DVD
+disc.capacity_gb()
+```
+
+## PES Pipeline (primary API)
+
+The PES pipeline is the main way to move content. All streams produce/consume
+PES frames. The pipeline just reads frames and writes frames.
+
+```rust
+// URL-based — any source to any destination
+let opts = InputOptions::default();
+let mut input = libfreemkv::input("disc:///dev/sg4", &opts)?;
+let title = input.info().clone();
+let mut output = libfreemkv::output("mkv://Movie.mkv", &title)?;
+
+while let Ok(Some(frame)) = input.read() {
+    output.write(&frame)?;
+}
+output.finish()?;
+```
+
+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 FrameSource: Send {
+    fn read(&mut self) -> Result<Option<PesFrame>, Error>;
+    fn info(&self) -> &DiscTitle;
+    fn codec_private(&self, track: usize) -> Option<Vec<u8>> { None }
+    fn headers_ready(&self) -> bool { true }
+}
+
+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 `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 |
+|--------|-------|--------|-----|-----------|
+| DiscStream | Yes | -- | `disc://` `disc:///dev/sg4` | Optical drive via SCSI |
+| IsoStream | Yes | Yes | `iso://path.iso` | Blu-ray ISO image |
+| MkvStream | Yes | Yes | `mkv://path` | Matroska container |
+| M2tsStream | Yes | Yes | `m2ts://path` | BD-TS with FMKV metadata header |
+| NetworkStream | Yes (listen) | Yes (connect) | `network://host:port` | TCP with FMKV metadata header |
+| StdioStream | Yes (stdin) | Yes (stdout) | `stdio://` | Raw byte pipe |
+| NullStream | -- | Yes | `null://` | Discard sink (byte counter) |
+
+All URLs require a `scheme://path` format. Bare paths are rejected.
+
+```rust
+// 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://Movie.iso", &opts)?;     // IsoStream
+let output = libfreemkv::output("mkv://Movie.mkv", &title)?;  // MkvOutputStream
+let output = libfreemkv::output("m2ts://Movie.m2ts", &title)?; // M2tsOutputStream
+let output = libfreemkv::output("network://192.0.2.10:9000", &title)?; // NetworkOutputStream
+let output = libfreemkv::output("null://", &title)?;          // NullOutputStream
+```
+
+### FMKV Metadata Header
+
+M2tsStream and NetworkStream embed a JSON metadata header before the BD-TS data:
+
+```
+[8B magic "FMKV\0\0\0\0"][4B JSON length][JSON metadata][padding to 192B boundary][BD-TS data...]
+```
+
+The header carries title name, duration, codec_privates, and full stream layout
+(PIDs, codecs, languages, labels). This allows the receiving end to set up
+demuxing and track metadata without scanning the TS.
+
+## Events
+
+Lib fires events during operations. App provides a callback. No display, no text.
+
+```rust
+pub struct Event {
+    pub kind: EventKind,
+}
+
+pub enum EventKind {
+    // Init / scan
+    DriveOpened { device: String },
+    DriveReady,
+    InitComplete { success: bool },
+    ProbeComplete { success: bool },
+    ScanComplete { titles: usize },
+
+    // Read pipeline
+    BytesRead { bytes: u64, total: u64 },
+    ReadError { sector: u64, error: Error },
+    SpeedChange { speed_kbs: u16 },
+    ExtentStart { index: usize, start_sector: u64, sector_count: u64 },
+    SectorSkipped { sector: u64 },
+    BatchSizeChanged { new_size: u16, reason: BatchSizeReason },
+    Complete { bytes: u64, errors: u32 },
+
+    // Kept for forward-compat; not emitted in 0.13.6+
+    Retry { attempt: u32 },
+    SectorRecovered { sector: u64 },
+}
+```
+
+Emission notes:
+
+- `BytesRead { bytes, total }` is emitted from `DiscStream::fill_extents`
+  after each successful sector read. `bytes` is the cumulative running
+  total; `total` is the precomputed extent sum (0 if unknown).
+- `SpeedChange` is emitted from the public `Drive::set_speed` API path.
+  It is no longer emitted from a recovery hot loop (recovery loop removed
+  in 0.13.6).
+- `BatchSizeChanged` fires from the `DiscStream` adaptive sizer on shrink
+  (read failed at a larger size) and on probe-up (clean-read streak hit
+  the threshold). Consumers use it to display a "recovering" state
+  distinct from "ripping normally".
+- `Retry` and `SectorRecovered` are NOT emitted in 0.13.6+. They were
+  tied to the inline `Drive::read` recovery phases that were removed; the
+  variants are kept for forward compatibility so consumers' match arms
+  don't need conditional compilation.
+
+Events report what happened. App decides what to do. GUI shows a dialog. CLI
+prints a line. Server logs to file.
+
+## File Layout
+
+```
+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, 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, 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
+├── ifo.rs              DVD IFO parser
+├── labels/             BD-J label extraction (5 format parsers)
+├── keydb.rs            KEYDB download, parse, save
+├── identity.rs         DriveId from INQUIRY
+├── profile.rs          Bundled drive profiles
+├── speed.rs            DriveSpeed enum
+├── mux/
+│   ├── 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)
+│   ├── isowriter.rs    ISO image writer (UDF, AVDP, multi-extent)
+│   ├── mkvstream.rs    MkvStream (bidirectional Matroska)
+│   ├── mkvout.rs       MkvOutputStream (PES → MKV)
+│   ├── 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)
+│   ├── null.rs         NullStream (discard + byte counter)
+│   ├── lookahead.rs    LookaheadBuffer (codec header scanning)
+│   ├── ts.rs           BD-TS demuxer + PAT/PMT scanner
+│   ├── tsreader.rs     TS reader utilities
+│   ├── tsmux.rs        TS muxer (PES → BD-TS packets)
+│   ├── ps.rs           MPEG-2 PS demuxer (DVD)
+│   ├── ebml.rs         EBML read/write primitives
+│   ├── mkv.rs          MKV muxer (tracks, clusters, cues)
+│   └── codec/          Frame parsers (H.264, HEVC, MPEG-2, VC-1, AC3, EAC3, DTS, TrueHD, LPCM, PGS)
+└── ...
+
+freemkv/src/
+├── main.rs             CLI dispatcher (URL routing)
+├── pipe.rs             PES pipeline — source → dest copy
+├── disc_info.rs        Disc/file info display
+├── info.rs             Drive info + profile submission
+├── strings.rs          i18n string table
+├── output.rs           Verbosity-filtered output
+└── build.rs            Bundled locale code generation
+```

docs/architecture.md

@@ -0,0 +1,219 @@
+# libfreemkv Architecture
+
+Open source optical drive access library for 4K UHD Blu-ray, Blu-ray, and DVD.
+Rust library with no external dependencies at runtime -- profiles are bundled,
+AACS keys are derived internally, and all SCSI communication is handled in-process.
+
+**Repository:** <https://github.com/freemkv/libfreemkv>
+**License:** AGPL-3.0-only
+
+---
+
+## Design Principles
+
+1. **CLI is dumb.** All drive communication, disc parsing, AACS decryption, and
+   format handling live in the library. CLI binaries are thin wrappers that call
+   `Drive::open()` and `Disc::scan()`.
+
+2. **No external files.** Bundled drive profiles are compiled into the binary via
+   `include_str!`. No configuration directory, no runtime file lookups for drive
+   support.
+
+3. **Transparent AACS.** The `ContentReader` decrypts on the fly when keys are
+   available. Callers read cleartext sectors without knowing whether the disc
+   was encrypted.
+
+4. **Structured errors, no English.** Every error has a numeric code (E1000-E8000).
+   The library never formats user-facing messages -- applications do that.
+
+5. **Library-agnostic.** No concept of "supported" vs "unsupported" drives at a
+   policy level. If a profile exists, the library uses it.
+
+6. **Streams are dumb pipes.** Streams read/write PES frames. They don't know
+   about encryption, transport format, or source type. Decrypt is a stream-internal
+   concern; the pipeline just moves frames.
+
+---
+
+## Module Map
+
+```
+libfreemkv (lib.rs)
+│
+├── Drive Access
+│   ├── drive         Drive — open, identify, init, unlock, single-shot read
+│   ├── scsi          ScsiTransport trait + platform backends (sg async, IOKit, SPTI)
+│   ├── platform/     Platform trait — per-chipset command handlers
+│   │   └── mt1959    MediaTek MT1959 driver (LG, ASUS, HP)
+│   ├── profile       DriveProfile loading, matching, bundled JSON
+│   ├── identity      DriveId from INQUIRY + GET_CONFIG 010C
+│   ├── speed         DriveSpeed enum, SET CD SPEED CDB builder
+│   └── event         Event system for drive status callbacks
+│
+├── Disc Scanning
+│   ├── disc          Disc::scan() — titles, streams, extents, AACS setup
+│   ├── udf           UDF 2.50 filesystem reader (metadata partitions)
+│   ├── mpls          MPLS playlist parser — clips, streams, STN table
+│   ├── clpi          CLPI clip info parser — EP map, sector extents
+│   ├── ifo           DVD IFO parser — title sets, PGC chains, cell addresses
+│   └── labels/       BD-J label extraction (5 formats: Paramount, Criterion, Pixelogic, CTRM, Deluxe)
+│
+├── Encryption
+│   ├── aacs/         AACS handshake, KEYDB, VUK lookup, MKB, unit decryption
+│   ├── css           DVD CSS cipher — table-driven, no external keys needed
+│   └── decrypt       decrypt_sectors() — unified AACS/CSS/None dispatcher
+│
+├── Streaming
+│   ├── mux/          Stream implementations (Disc, ISO, MKV, M2TS, Network, Stdio, Null)
+│   ├── 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
+│   ├── error         Error enum with numeric codes E1000-E8000
+│   └── profile       Bundled drive profiles
+│
+└── lib.rs            Public API re-exports
+```
+
+---
+
+## Drive Access Flow
+
+```
+Drive::open(Path::new("/dev/sg4"))
+  │
+  ├─ scsi::open()           Open /dev/sg4 (async write/poll/read)
+  ├─ DriveId::from_drive()  INQUIRY + GET_CONFIG 010C
+  ├─ profile::find_by_drive_id()  Match against bundled profiles
+  ├─ Platform::new()        Instantiate chipset driver (Mt1959)
+  └─ Drive ready for init/unlock/read
+```
+
+After open:
+- `init()` -- unlock + firmware upload + speed calibration
+- `probe_disc()` -- probe disc surface for optimal speeds
+- `read(lba, count, buf, recovery)` -- single-shot read; `recovery` only selects the per-CDB timeout (1.5 s vs. 30 s)
+- `wait_ready()` -- wait for disc insertion
+- `eject()` -- eject tray
+
+Recovery is layered above `Drive::read`, not inside it. Layer 1
+(`Disc::patch`) handles bad-range retry by replaying the ddrescue mapfile.
+Layer 3 (`DiscStream::fill_extents` adaptive batch sizer) handles in-loop
+request-size adaptation. Inline recovery (gentle retry → SCSI reset → retry)
+was removed in 0.13.6 — see [`rip-recovery.md`](rip-recovery.md) and
+the stop-wedge postmortem (2026-04-25).
+
+---
+
+## Disc Scanning Flow
+
+```
+Disc::scan(&mut drive, &ScanOptions)
+  │
+  ├─ READ CAPACITY          Get disc size in sectors
+  ├─ udf::read_filesystem() Parse UDF 2.50 (AVDP → VDS → metadata → FSD → root)
+  ├─ For each BDMV/PLAYLIST/*.mpls:
+  │   ├─ mpls::parse()      Extract play items, STN streams
+  │   └─ For each clip:
+  │       └─ clpi::parse()  EP map → sector extents for the clip's time range
+  ├─ labels::detect()       Parse BD-J JARs for stream labels
+  ├─ Detect AACS            Check for /AACS directory on disc
+  └─ Disc::setup_aacs()     Handshake + KEYDB → VUK → unit keys (if encrypted)
+```
+
+For DVD:
+```
+Disc::scan_dvd(&mut drive, &ScanOptions)
+  │
+  ├─ ifo::parse()           Parse VIDEO_TS.IFO — title sets, PGC chains
+  ├─ CSS detection          Check disc structure flag
+  └─ CSS key cracking       Table-driven, no KEYDB needed
+```
+
+The result is a `Disc` with:
+- `titles: Vec<DiscTitle>` -- sorted by duration, each with streams, sector extents, codec_privates
+- `decrypt_keys()` -- DecryptKeys for content decryption
+- `encrypted: bool` -- whether the disc uses AACS/CSS
+
+---
+
+## AACS Decryption
+
+Four key resolution paths, tried in order:
+
+| Path | Method | Speed |
+|------|--------|-------|
+| 1 | VUK lookup by disc hash in KEYDB.cfg | Instant |
+| 2 | Media Key + Volume ID from KEYDB → derive VUK | Fast |
+| 3 | Processing Keys + MKB → Media Key → VUK | Medium |
+| 4 | Device Keys + MKB subset-difference tree → VUK | Slow |
+
+The AACS handshake (`aacs/handshake`) performs ECDH key agreement over the
+AACS 1.0 160-bit elliptic curve to obtain:
+- **Volume ID** -- needed for VUK derivation (paths 2-4)
+- **Read Data Key** -- needed for AACS 2.0 (UHD) bus decryption
+
+Content decryption uses AES-128-CBC on 6144-byte aligned units. The
+`ContentReader` handles this transparently. Streams that read sectors
+(DiscStream, IsoStream) decrypt internally — the pipeline sees clean bytes.
+
+---
+
+## Error Codes
+
+All errors carry a numeric code for programmatic handling. No user-facing text
+is baked into the library.
+
+| Range | Category | Examples |
+|-------|----------|----------|
+| E1xxx | Device errors | `DeviceNotFound`, `DevicePermission` |
+| E2xxx | Profile errors | `UnsupportedDrive`, `ProfileNotFound`, `ProfileParse` |
+| E3xxx | Unlock errors | `UnlockFailed`, `SignatureMismatch`, `NotUnlocked`, `NotCalibrated` |
+| E4xxx | SCSI errors | `ScsiError`, `ScsiTimeout` |
+| E5xxx | I/O errors | `IoError` (wraps `std::io::Error`) |
+| E6xxx | Disc format errors | `DiscError` (UDF, MPLS, CLPI parse failures) |
+| E7xxx | AACS errors | `AacsError` (key resolution, handshake, decryption) |
+| E8xxx | KEYDB errors | `KeydbError` (download, parse, save) |
+
+---
+
+## Platform Support
+
+| Platform | Transport | Status |
+|----------|-----------|--------|
+| Linux | async sg write/poll/read on `/dev/sg*` | Supported |
+| macOS | IOKit SCSITask | Supported |
+| Windows | SPTI (`IOCTL_SCSI_PASS_THROUGH_DIRECT`) | Supported |
+
+The `ScsiTransport` trait abstracts the platform. Adding a new platform requires
+implementing `execute()` for that OS and wiring it into `scsi::open()`.
+
+---
+
+## Chipset Support
+
+| Chipset | Drives | Status |
+|---------|--------|--------|
+| MediaTek MT1959 | LG, ASUS, HP | Supported (bundled profiles) |
+| Renesas RS8xxx/RS9xxx | Pioneer, some HL-DT-ST | Planned |
+
+The `Platform` trait abstracts chipset-specific commands. Each chipset implements
+handlers (unlock, config, register, calibrate, keepalive, status, probe,
+read_sectors, timing). All handlers are accessed via SCSI READ BUFFER with
+chipset-specific mode and buffer ID bytes.
+
+---
+
+## Build
+
+```
+cargo build --release
+```
+
+Produces a Rust library crate. The `libc` dependency is unix-only (gated).
+All three platforms build and pass CI.

docs/clpi.md

@@ -0,0 +1,197 @@
+# CLPI Clip Information Format
+
+## What is CLPI?
+
+CLPI (Clip Information) files describe the structure of individual M2TS transport streams on a Blu-ray disc. Each `.clpi` file in `BDMV/CLIPINF/` corresponds to one `.m2ts` file in `BDMV/STREAM/` with the same numeric name (e.g. `00001.clpi` describes `00001.m2ts`).
+
+The most important data in a CLPI file is the **EP (Entry Point) map**, which provides timestamp-to-sector mapping. This is essential for seeking and for extracting the specific sector ranges that correspond to a playlist's in/out time window.
+
+## File Structure
+
+CLPI files use big-endian byte order. The header:
+
+```
+Offset  Size  Field
+------  ----  -----
+0       4     Magic: "HDMV"
+4       4     Version: "0200" (BD) or "0300" (UHD BD)
+8       4     SequenceInfo start offset
+12      4     ProgramInfo start offset
+16      4     CPI (Characteristic Point Information) start offset
+20      4     ClipMark start offset
+24      4     ExtensionData start offset
+```
+
+### ClipInfo Section (offset 40)
+
+Contains basic clip metadata. The source packet count (total number of 192-byte source packets in the M2TS file) is at offset 56:
+
+```
+Offset  Size  Field
+------  ----  -----
+40      4     ClipInfo length
+44      2     Reserved
+46      1     Stream type
+47      1     Application type
+48      4     Reserved
+52      4     TS recording rate
+56      4     Source packet count
+```
+
+The source packet count multiplied by 192 gives the total byte size of the M2TS file.
+
+## EP Map
+
+The EP map lives inside the CPI section and provides random access into the transport stream. It maps PTS timestamps to Source Packet Numbers (SPN), enabling precise seeking without scanning the stream.
+
+### CPI Section Layout
+
+```
+Offset  Size  Field
+------  ----  -----
+0       4     CPI length
+4       2     Reserved / CPI type
+6       ...   EP map
+```
+
+### EP Map Header
+
+```
+Offset  Size  Field
+------  ----  -----
+0       1     Reserved
+1       1     Number of stream PID entries
+2       ...   Stream PID entry headers (one per stream)
+```
+
+Each stream PID entry header (14 bytes):
+
+```
+Offset  Size  Field
+------  ----  -----
+0       2     Stream PID
+2       2     Reserved + EP stream type
+4       2     Number of coarse entries
+6       4     Number of fine entries (note: 32-bit, can be large)
+10      4     EP map start offset (relative to EP map start)
+```
+
+libfreemkv parses only the first stream (primary video), which is sufficient for sector-level seeking.
+
+### Two-Level Index
+
+The EP map uses a two-level structure to compress what would otherwise be a very large lookup table:
+
+- **Coarse entries**: low-resolution index covering large time/sector ranges
+- **Fine entries**: high-resolution entries within each coarse range
+
+Each coarse entry points to a range of fine entries via `ref_to_fine_id`.
+
+### Coarse Entries (8 bytes each)
+
+Located immediately after the fine table start offset (4 bytes) in the per-stream EP map:
+
+```
+Bits    Field
+------  -----
+[31:14] ref_to_fine_id (18 bits) -- index of first fine entry in this range
+[13:0]  pts_coarse (14 bits) -- upper bits of PTS
+```
+
+Second dword:
+
+```
+Bits    Field
+------  -----
+[31:0]  spn_coarse (32 bits) -- upper bits of SPN
+```
+
+### Fine Entries (4 bytes each)
+
+Located at the fine table start offset within the per-stream EP map:
+
+```
+Bits    Field
+------  -----
+[31]    is_angle_change_point (1 bit)
+[30:28] I_end_position_offset (3 bits)
+[27:17] pts_fine (11 bits) -- lower bits of PTS
+[16:0]  spn_fine (17 bits) -- lower bits of SPN
+```
+
+## Reconstructing Full PTS and SPN
+
+The full timestamp and packet number are assembled by combining the coarse and fine components:
+
+### Full PTS
+
+```
+full_pts = (pts_coarse << 19) + (pts_fine << 8)
+```
+
+The coarse component provides the upper bits, shifted left by 19. The fine component provides mid-range bits, shifted left by 8. The resulting PTS is in 45kHz ticks, matching the MPLS timestamp format.
+
+### Full SPN
+
+```
+full_spn = (spn_coarse & 0xFFFE0000) + spn_fine
+```
+
+The coarse SPN provides the upper 15 bits (masked to clear the lower 17). The fine SPN provides the lower 17 bits. The result is a Source Packet Number -- each source packet is 192 bytes in the M2TS file.
+
+### Resolved EP Map
+
+The `resolved_ep_map()` method iterates through all coarse entries and their associated fine entries to produce a flat list of `(PTS, SPN)` pairs. For each coarse entry at index `ci`:
+
+- Fine entries range from `coarse[ci].ref_to_fine_id` to `coarse[ci+1].ref_to_fine_id` (or end of fine table for the last coarse entry).
+- Each fine entry is combined with its parent coarse entry to produce one full `(PTS, SPN)` pair.
+
+## Deriving Sector Extents for Ripping
+
+Given a playlist's in_time and out_time (from MPLS), the CLPI EP map provides the sector ranges to read from disc. The `get_extents()` method does this in three steps:
+
+### Step 1: PTS to SPN
+
+Binary search the resolved EP map for the in_time and out_time:
+
+- **start_spn**: the SPN at or before in_time (seek backward to the nearest I-frame)
+- **end_spn**: the SPN at or after out_time (include the full GOP)
+
+### Step 2: SPN to Byte Offset
+
+Each Source Packet is 192 bytes (188 bytes MPEG-TS payload + 4 bytes M2TS header):
+
+```
+byte_offset = spn * 192
+```
+
+### Step 3: Byte Offset to Sector
+
+M2TS files are stored contiguously on disc. Sectors are 2048 bytes:
+
+```
+start_sector = start_byte / 2048
+end_sector   = (end_byte + 2047) / 2048
+sector_count = end_sector - start_sector
+```
+
+The resulting `Extent` contains `start_lba` (relative to the M2TS file's starting sector on disc) and `sector_count`. The caller adds the file's absolute starting LBA from UDF to get disc-absolute sector numbers.
+
+### Alignment Note
+
+The 192-byte source packet size and 2048-byte sector size share no common factor beyond 1. A single sector contains roughly 10.67 source packets. The conversion rounds start down and end up to ensure complete coverage.
+
+## Putting It Together
+
+The full ripping pipeline chains three parsers:
+
+1. **MPLS** provides clip IDs and in/out timestamps.
+2. **CLPI** converts those timestamps to SPN ranges, then to sector extents.
+3. **UDF** provides the file's starting LBA on disc for absolute sector addressing.
+
+The `Disc::scan()` method in `src/disc.rs` orchestrates this: for each play item in each playlist, it loads the corresponding CLPI, calls `get_extents()` with the play item's in/out times, and collects the resulting sector ranges into the title's extent list.
+
+## References
+
+- BD-ROM Part 3, Section 5.5: Clip Information file format
+- https://github.com/lw/BluRay/wiki/CLPI

docs/disc-to-rip.md

@@ -0,0 +1,135 @@
+# Disc to Rip: End-to-End Flow
+
+How libfreemkv goes from a disc in the drive to decrypted content ready for backup.
+This is the starting point for understanding the library.
+
+## The Pipeline
+
+```
+Insert disc
+    │
+    ▼
+1. Open drive (drive/mod.rs)
+    │  INQUIRY → identify drive
+    │  Match bundled profile → chipset, unlock parameters
+    │
+    ▼
+2. Init drive (drive/mod.rs → platform/mt1959)
+    │  Firmware upload (if needed, 10s recovery wait)
+    │  Unlock → vendor-specific command activates raw read mode
+    │  Speed calibration → probe_disc()
+    │
+    ▼
+3. AACS handshake (aacs/handshake.rs) — optional
+    │  Allocate AGID
+    │  Exchange certificates + nonces (ECDH)
+    │  Derive bus key
+    │  Read Volume ID + read_data_key
+    │  (fails gracefully if drive doesn't support AACS for this disc)
+    │
+    ▼
+4. Read UDF filesystem (udf.rs)
+    │  Sector 256: AVDP → find Volume Descriptor Sequence
+    │  VDS: Partition Descriptor (physical start) + Logical Volume (metadata start)
+    │  Metadata partition → File Set Descriptor → Root directory
+    │  Walk directory tree: BDMV/, AACS/, CERTIFICATE/
+    │  → docs/udf.md
+    │
+    ▼
+5. Read AACS files from disc (aacs/mod.rs)
+    │  AACS/Unit_Key_RO.inf → SHA1 = disc hash
+    │  AACS/Content000.cer → AACS version (1.0 or 2.0), bus encryption flag
+    │  MKB via SCSI → for key derivation fallback
+    │
+    ▼
+6. Resolve encryption keys (decrypt.rs → resolve_encryption)
+    │  BD AACS:
+    │    Path 1: disc hash → KEYDB.cfg → VUK (fast, 99% of discs)
+    │    Path 2: KEYDB media key + Volume ID → VUK
+    │    Path 3: MKB + processing keys → media key → VUK
+    │    Path 4: MKB + device keys → subset-difference tree → VUK
+    │    VUK → decrypt unit keys from Unit_Key_RO.inf
+    │  DVD CSS:
+    │    Table-driven cipher — no KEYDB needed
+    │  → docs/aacs.md
+    │
+    ▼
+7. Parse playlists (mpls.rs) — BD/UHD only
+    │  BDMV/PLAYLIST/*.mpls → titles with play items
+    │  Each play item: clip ID, in/out timestamps
+    │  STN table: video, audio, subtitle streams with codec + language
+    │  → docs/mpls.md
+    │
+    ▼
+8. Parse clip info (clpi.rs) — BD/UHD only
+    │  BDMV/CLIPINF/*.clpi → EP map (timestamp → sector mapping)
+    │  Coarse + fine entries → full PTS and SPN
+    │  SPN → byte offset → sector extents for reading
+    │  → docs/clpi.md
+    │
+    ▼
+9. Parse BD-J labels (labels/) — optional
+    │  BDMV/JAR/*.jar → Java class constant pool strings
+    │  5 format parsers: Paramount, Criterion, Pixelogic, CTRM, Deluxe
+    │  Audio track labels: "English Descriptive Audio", "French 5.1", etc.
+    │
+    ▼
+10. Stream content (mux/disc.rs → DiscStream)
+     │  Read sectors → decrypt → TS demux → PES frames
+     │  Or: read sectors → decrypt → raw bytes (for ISO output)
+     │  Drive::read() is single-shot. DiscStream::fill_extents adapts the
+     │  batch size on failure (halve / probe-up). Bad-range retry is layer
+     │  1 above this — Disc::patch re-runs against the mapfile.
+     │
+     ▼
+  PES frames → output stream (MKV, M2TS, network, etc.)
+```
+
+## API Summary
+
+```rust
+// Open + init drive
+let mut drive = Drive::open(Path::new("/dev/sg4"))?;
+drive.wait_ready()?;
+drive.init()?;
+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.
+// 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();
+let mut output = libfreemkv::output("mkv://Movie.mkv", &title)?;
+while let Ok(Some(frame)) = input.read() {
+    output.write(&frame)?;
+}
+output.finish()?;
+```
+
+## Module Reference
+
+| Module | Doc | Purpose |
+|--------|-----|---------|
+| drive/ | [drive-access.md](drive-access.md) | Open, identify, init, unlock, single-shot read |
+| scsi/ | [drive-access.md](drive-access.md) | Platform SCSI transport (Linux, macOS, Windows) |
+| udf.rs | [udf.md](udf.md) | UDF 2.50 filesystem |
+| mpls.rs | [mpls.md](mpls.md) | MPLS playlists + STN streams |
+| clpi.rs | [clpi.md](clpi.md) | CLPI clip info + EP map |
+| ifo.rs | -- | DVD IFO parser |
+| aacs/ | [aacs.md](aacs.md) | Key resolution + content decrypt + bus handshake |
+| css/ | -- | DVD CSS cipher |
+| decrypt.rs | -- | Unified decrypt dispatcher (AACS/CSS/None) |
+| 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 + 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 |

docs/drive-access.md

@@ -0,0 +1,268 @@
+# Drive Access and Unlock
+
+Technical reference for how libfreemkv opens, identifies, unlocks, and reads
+optical drives.
+
+---
+
+## Drive
+
+`Drive` is the primary API. It owns the SCSI transport, the matched
+drive profile, and the chipset-specific platform driver.
+
+### Opening a Drive
+
+```rust
+let mut drive = Drive::open(Path::new("/dev/sg4"))?;
+```
+
+`open()` performs: open device → send INQUIRY → match profile → instantiate
+platform driver. The drive is ready for `wait_ready()` and `init()`.
+
+### Drive Operations
+
+| Method | Description |
+|--------|-------------|
+| `wait_ready()` | Wait for disc insertion (30s timeout, TUR polling) |
+| `init()` | Firmware upload + unlock + speed calibration |
+| `probe_disc()` | Probe disc surface for optimal speeds |
+| `read(lba, count, buf, recovery)` | Read sectors. Single-shot — no inline retries or reset. |
+| `reset()` | Eject-cycle escape hatch. Caller-invoked only; not on the read path. |
+| `lock_tray()` | Prevent tray ejection during rip |
+| `unlock_tray()` | Allow tray ejection (also runs on Drop) |
+| `eject()` | Eject disc tray |
+| `drive_status()` | Query physical state (disc present, tray open, etc.) |
+| `has_profile()` | Whether a bundled profile matched |
+| `close()` | Consume Drive, cleanup (also runs via Drop) |
+
+### init() Sequence
+
+`init()` orchestrates the full drive unlock:
+
+1. Platform driver `run_init()` — sends vendor-specific SCSI commands
+2. If firmware upload needed: upload, wait 10s for drive reset, retry
+3. Speed calibration after unlock
+4. Max 3 attempts before giving up
+
+### read() — single-shot
+
+`Drive::read(lba, count, buf, recovery)` is the single read method. It issues
+exactly one READ(10) CDB and returns the result. The `recovery` parameter only
+selects the per-CDB timeout:
+
+| `recovery` | Timeout  | Used by                                  |
+|------------|----------|------------------------------------------|
+| `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.
+
+Recovery is layered above `Drive::read`:
+
+- **Layer 1 — `Disc::patch`** loops over the ddrescue mapfile and re-issues
+  `read(.., recovery=true)` against each non-`+` range.
+- **Layer 3 — `DiscStream::fill_extents`** halves the request size on
+  failure, retries at the same LBA, and probes back up on a clean-read
+  streak.
+
+Inline recovery (5× gentle retry → close + reset + reopen → 5× more) was
+removed in 0.13.6. See the stop-wedge postmortem (2026-04-25)
+for rationale: the inline reset wedged drive firmware on the LG BU40N (Initio
+USB-SATA bridge) without ever recovering a sector. See
+[`rip-recovery.md`](rip-recovery.md) for the full three-layer model.
+
+---
+
+## SCSI Transport
+
+### Trait
+
+```rust
+pub trait ScsiTransport: Send {
+    fn execute(
+        &mut self,
+        cdb: &[u8],
+        direction: DataDirection,
+        data: &mut [u8],
+        timeout_ms: u32,
+    ) -> Result<ScsiResult>;
+}
+```
+
+All drive communication goes through this trait. The library never opens file
+descriptors or calls ioctls outside of a `ScsiTransport` implementation.
+
+### Platform Backends
+
+| Platform | Implementation | Device |
+|----------|---------------|--------|
+| Linux | `SgIoTransport` — async `write`/`poll`/`read` on `/dev/sg*` | `/dev/sg*` |
+| macOS | `MacScsiTransport` — IOKit SCSITask | IOKit service |
+
+The Linux backend uses the sg driver's asynchronous interface: `write()` submits
+the command, `poll()` waits with an enforceable wall-clock timeout, `read()`
+retrieves the result. If `poll()` times out, the fd is abandoned (closed in a
+background thread) and a fresh fd opened — the kernel's USB error recovery
+cannot block us. Opens with `O_RDWR | O_NONBLOCK`.
+
+The macOS backend uses a C shim (`macos_shim.c`) for IOKit exclusive access.
+The shim handles:
+1. `shim_open_exclusive(bsd_name)` — unmounts the target device via `diskutil`,
+   then walks the IOKit registry to find the `IOBDServices` matching the
+   requested BSD name (IOBDServices → IOBDBlockStorageDriver → IOMedia → "BSD Name"),
+   then creates MMCDeviceInterface → SCSITaskDeviceInterface → ObtainExclusiveAccess.
+2. `shim_list_drives()` — registry-based enumeration with zero SCSI, zero exclusive
+   access, zero unmounts. Reads IOBDServices "Device Characteristics" for
+   vendor/model/firmware and child IOMedia "BSD Name" for the device path.
+3. `shim_execute()` / `shim_close()` — raw CDB dispatch and cleanup.
+
+On non-zero SCSI status, the transport parses sense key from the sense buffer
+and returns `Error::ScsiError`.
+
+`SgIoTransport::reset` (Linux) does pure userspace state cleanup: an open +
+close pair to make the kernel cancel any SG_IO commands queued against a
+previous fd, a 2 s sleep to let the kernel finish that cancellation, then a
+fresh fd to send ALLOW MEDIUM REMOVAL to clear any stale tray lock. It does
+NOT issue `SG_SCSI_RESET` or escalate via STOP+START UNIT. Both were tried
+in 0.13.0–0.13.5 against the LG BU40N (Initio USB-SATA bridge); both failed
+to recover wedged drives and made the wedge worse. The macOS reset (which
+had been a no-op) was removed entirely in 0.13.6, and the top-level
+`scsi::reset()` / `reset_with_timeout()` / `reset_blocking()` wrappers were
+removed at the same time (no callers).
+
+### CDB Builders
+
+The `scsi` module provides platform-agnostic CDB constructors:
+
+| Function | CDB | Use |
+|----------|-----|-----|
+| `inquiry()` | INQUIRY (0x12) | Drive identification |
+| `get_config_010c()` | GET CONFIGURATION (0x46) | Feature 010C firmware date |
+| `build_read_buffer()` | READ BUFFER (0x3C) | All platform commands |
+| `build_set_cd_speed()` | SET CD SPEED (0xBB) | Speed control |
+| `build_read10_raw()` | READ(10) (0x28) with flag 0x08 | Raw sector reads |
+
+---
+
+## Drive Identification
+
+`DriveId::from_drive()` sends two standard SCSI commands and extracts identity
+fields:
+
+| Field | Source | SCSI Reference |
+|-------|--------|----------------|
+| `vendor_id` | INQUIRY bytes [8:16] | SPC-4 section 6.4.2 |
+| `product_id` | INQUIRY bytes [16:32] | SPC-4 section 6.4.2 |
+| `product_revision` | INQUIRY bytes [32:36] | SPC-4 section 6.4.2 |
+| `vendor_specific` | INQUIRY bytes [36:43] | SPC-4 section 6.4.2 |
+| `firmware_date` | GET CONFIGURATION Feature 010C | MMC-6 section 5.3.10 |
+
+The match key is `"VENDOR|PRODUCT|REVISION|VENDOR_SPECIFIC"`. Profile matching
+tries all four fields first, then falls back to matching without the firmware
+date for drives where Feature 010C is unavailable.
+
+---
+
+## Drive Profiles
+
+Profiles are JSON objects compiled into the binary (`profiles.json`).
+Each profile contains:
+
+| Field | Purpose |
+|-------|---------|
+| `vendor_id`, `product_revision`, `vendor_specific`, `firmware_date` | Matching fields |
+| `chipset` | `"mediatek"` or `"renesas"` |
+| `unlock_mode`, `unlock_buf_id` | READ BUFFER CDB parameters |
+| `signature` | Expected 4-byte response signature |
+| `unlock_cdb` | Pre-built unlock CDB (hex-encoded) |
+| `register_offsets` | Offsets for hardware register reads |
+| `capabilities` | Feature flags: `bd_raw_read`, `dvd_all_regions`, etc. |
+
+Loading:
+
+```rust
+// Bundled (compiled-in) -- no file I/O
+let profiles = profile::load_bundled()?;
+
+// External file
+let profiles = profile::load_all(Path::new("/path/to/profiles.json"))?;
+```
+
+---
+
+## Chipsets
+
+### MediaTek MT1959
+
+Covers all LG, ASUS, and HP optical drives. Two sub-variants share identical
+logic with different SCSI parameters:
+
+| Variant | READ BUFFER mode | Buffer ID |
+|---------|------------------|-----------|
+| MT1959-A | 0x01 | 0x44 |
+| MT1959-B | 0x02 | 0x77 |
+
+The Platform trait maps to command handlers:
+
+| Handler | Function | Description |
+|---------|----------|-------------|
+| 0 | `unlock()` | Send READ BUFFER, verify signature + verification bytes |
+| 1 | `read_config()` | Read 1888-byte configuration block + 4-byte status |
+| 2-3 | `read_register()` | Read hardware registers at profile-specified offsets |
+| 4 | `calibrate()` | Probe disc surface, build 64-entry speed table |
+| 5 | `keepalive()` | Periodic session maintenance |
+| 6 | `status()` | Query current mode and feature flags |
+| 7 | `probe()` | Generic READ BUFFER with dynamic parameters |
+| 8 | `read_sectors()` | Speed lookup + SET CD SPEED + READ(10) with flag 0x08 |
+| 9 | `timing()` | Timing calibration |
+
+### Renesas (Planned)
+
+RS8xxx/RS9xxx chipsets used in Pioneer and some HL-DT-ST drives.
+Currently returns `Error::UnsupportedDrive` when a Renesas profile is matched.
+
+---
+
+## Why Unlock Is Needed
+
+Optical drive firmware restricts what applications can read from disc. Without
+unlock:
+
+- **READ(10) works for unencrypted filesystem data.** UDF structures, MPLS
+  playlists, and CLPI clip info are readable without unlock. Standard READ(10)
+  works on any drive.
+
+- **READ(10) fails for encrypted content sectors.** The drive firmware returns
+  SCSI errors (sense key 0x05, illegal request) when an application attempts to
+  read sectors containing encrypted m2ts content without prior AACS
+  authentication via the bus key.
+
+- **Raw mode bypasses firmware restrictions.** After unlock, the drive accepts
+  READ(10) with the raw read flag (CDB byte 1 = 0x08) for all sectors,
+  regardless of encryption status.
+
+### AACS Before Unlock
+
+AACS bus authentication uses standard MMC REPORT KEY / SEND KEY commands.
+On some drives these must execute before unlock. The `Disc::scan()` handles
+this internally — it manages the handshake/unlock ordering automatically.
+
+---
+
+## Speed Control
+
+After `probe_disc()`, the platform driver maintains a speed lookup table
+built by probing the disc surface. On each `read()` call, the driver:
+
+1. Looks up the optimal speed for the target LBA.
+2. Issues SET CD SPEED (0xBB) if the speed differs from current.
+3. Performs the READ(10).
+
+Available speeds:
+
+| Format | Speeds |
+|--------|--------|
+| Blu-ray | 1x (4,500 KB/s) through 12x (54,000 KB/s) |
+| DVD | 1x (1,385 KB/s) through 16x (22,160 KB/s) |
+| Max | 0xFFFF (drive decides) |

docs/mpls.md

@@ -0,0 +1,217 @@
+# MPLS Playlist Format
+
+## What is MPLS?
+
+MPLS (Movie PlayList) files define playback titles on a Blu-ray disc. Each `.mpls` file in `BDMV/PLAYLIST/` describes one title -- a sequence of clips with precise in/out timestamps and stream information. The main movie, bonus features, trailers, and menus each have their own MPLS file.
+
+A disc may contain dozens of MPLS files. Most are short (menus, logos, transitions). The main movie is typically the longest playlist. libfreemkv filters out playlists shorter than 30 seconds.
+
+## File Structure
+
+MPLS files use big-endian byte order throughout. The file has three main sections:
+
+```
+Offset  Size  Field
+------  ----  -----
+0       4     Magic: "MPLS"
+4       4     Version: "0200" (BD) or "0300" (UHD BD)
+8       4     PlayList start offset (absolute from file start)
+12      4     PlayListMark start offset
+16      4     ExtensionData start offset
+```
+
+### PlayList Section
+
+Located at the PlayList start offset. Contains all play items and sub-path entries:
+
+```
+Offset  Size  Field
+------  ----  -----
+0       4     PlayList length
+4       2     Reserved
+6       2     Number of PlayItems
+8       2     Number of SubPaths
+10      ...   PlayItem entries (variable length)
+```
+
+### Play Items
+
+Each play item references one clip and specifies what portion to play:
+
+```
+Offset  Size  Field
+------  ----  -----
+0       2     PlayItem length (bytes after this field)
+2       5     Clip ID (ASCII, e.g. "00001")
+7       4     Codec ID ("M2TS")
+11      1     Connection condition (lower 4 bits)
+12      1     Ref to STC_id
+14      4     IN_time (45kHz PTS ticks)
+18      4     OUT_time (45kHz PTS ticks)
+22      8     UO_mask_table
+30      1     Misc flags
+31      1     still_mode
+32      ...   STN_table (first play item only is parsed)
+```
+
+**Connection condition** values:
+- `1` = seamless connection (no gap between clips)
+- `5`, `6` = non-seamless connection
+
+**Timestamps** use 45kHz PTS (Presentation Time Stamp) ticks, the same timebase as MPEG transport streams. Duration of a play item = `OUT_time - IN_time`. To convert to seconds: divide by 45000.
+
+A playlist's total duration is the sum of all play item durations.
+
+### Clip ID Mapping
+
+The Clip ID (e.g. "00001") maps to:
+- `BDMV/STREAM/00001.m2ts` -- the transport stream
+- `BDMV/CLIPINF/00001.clpi` -- the clip info (EP map, stream details)
+
+## STN Table
+
+The Stream Number Table describes all elementary streams available in the clip. It is parsed from the first play item (which defines the title's stream layout).
+
+```
+Offset  Size  Field
+------  ----  -----
+0       2     STN table length
+2       2     Reserved
+4       1     Number of primary video streams
+5       1     Number of primary audio streams
+6       1     Number of PG (subtitle) streams
+7       1     Number of IG (interactive graphics) streams
+8       ...   Stream entries
+```
+
+### Stream Entries
+
+Each stream entry has two parts: a stream reference and a stream attributes block.
+
+**Stream reference:**
+
+```
+Offset  Size  Field
+------  ----  -----
+0       1     Entry length
+1       1     Stream type (1=PlayItem, 2=SubPath, 3=InMux)
+2       2     PID (MPEG-TS packet ID, big-endian)
+```
+
+**Stream attributes** (immediately follows the reference):
+
+```
+Offset  Size  Field
+------  ----  -----
+0       1     Attributes length
+1       1     Coding type
+2+      ...   Type-specific fields
+```
+
+The layout of type-specific fields depends on the stream category:
+
+**Video streams:**
+
+| Offset | Size | Field |
+|--------|------|-------|
+| 1 | 1 | Coding type |
+| 2 | 1 | Format (upper 4 bits) + frame rate (lower 4 bits) |
+
+**Audio streams:**
+
+| Offset | Size | Field |
+|--------|------|-------|
+| 1 | 1 | Coding type |
+| 2 | 1 | Format (upper 4 bits) + sample rate (lower 4 bits) |
+| 3 | 3 | Language code (ISO 639-2, e.g. "eng") |
+
+**PG subtitle and IG streams:**
+
+| Offset | Size | Field |
+|--------|------|-------|
+| 1 | 1 | Coding type |
+| 2 | 3 | Language code |
+
+## Coding Types
+
+The coding type byte identifies the codec:
+
+| Value | Codec | Category |
+|-------|-------|----------|
+| `0x02` | MPEG-2 | Video |
+| `0x1B` | H.264 / AVC | Video |
+| `0x24` | HEVC / H.265 | Video |
+| `0xEA` | VC-1 | Video |
+| `0x80` | LPCM | Audio |
+| `0x81` | AC-3 (Dolby Digital) | Audio |
+| `0x82` | DTS | Audio |
+| `0x83` | TrueHD (Dolby TrueHD) | Audio |
+| `0x84` | AC-3 Plus (E-AC-3) | Audio |
+| `0x85` | DTS-HD HR | Audio |
+| `0x86` | DTS-HD MA | Audio |
+| `0xA1` | AC-3 Plus (secondary) | Audio |
+| `0xA2` | DTS-HD HR (secondary) | Audio |
+| `0x90` | PGS (Presentation Graphics) | Subtitle |
+| `0x91` | PGS (Interactive Graphics) | Subtitle |
+
+## Video Format Codes
+
+| Value | Resolution |
+|-------|-----------|
+| 1 | 480i |
+| 2 | 576i |
+| 3 | 480p |
+| 4 | 1080i |
+| 5 | 720p |
+| 6 | 1080p |
+| 7 | 576p |
+| 8 | 2160p |
+
+## Video Frame Rate Codes
+
+| Value | Frame Rate |
+|-------|-----------|
+| 1 | 23.976 fps |
+| 2 | 24 fps |
+| 3 | 25 fps |
+| 4 | 29.97 fps |
+| 6 | 50 fps |
+| 7 | 59.94 fps |
+
+## Audio Format Codes
+
+| Value | Channels |
+|-------|----------|
+| 1 | Mono |
+| 3 | Stereo |
+| 6 | 5.1 surround |
+| 12 | 7.1 surround |
+
+## Audio Sample Rate Codes
+
+| Value | Rate |
+|-------|------|
+| 1 | 48 kHz |
+| 4 | 96 kHz |
+| 5 | 192 kHz |
+| 12 | 48/192 kHz (combo) |
+| 14 | 48/96 kHz (combo) |
+
+## How Playlists Map to Titles
+
+libfreemkv's `Disc::scan()` reads every MPLS file from the disc and builds a `Title` for each:
+
+1. Read all `.mpls` files from `BDMV/PLAYLIST/` via UDF.
+2. Parse each with `mpls::parse()`.
+3. Calculate duration by summing `(OUT_time - IN_time)` across all play items.
+4. Discard playlists shorter than 30 seconds.
+5. For each play item, load the corresponding CLPI file to get EP map data and compute sector extents (see [clpi.md](clpi.md)).
+6. Extract stream info from the STN table of the first play item.
+7. Sort titles by duration, longest first.
+
+The resulting `Title` struct contains everything needed to rip: streams, duration, byte size, and the sector extents to read from disc.
+
+## References
+
+- BD-ROM Part 3, Section 5.3: PlayList file format
+- https://github.com/lw/BluRay/wiki/MPLS

docs/rip-recovery.md

@@ -0,0 +1,201 @@
+# Rip recovery — three-layer architecture
+
+`libfreemkv` supports a multi-stage rip model for damaged or protection-bearing
+discs: a fast forward sweep that tolerates read failures, in-loop request-size
+adaptation that survives transient drive trouble without bailing, and targeted
+retry passes against a persistent bad-range map. The stream pipeline
+(`DiscStream` + `input`/`output`) operates against the resulting ISO image, so
+the mux stage never touches the drive.
+
+Recovery is layered cleanly. Each layer has one responsibility and does not
+reach into the others.
+
+| Layer | Where it lives | What it does |
+|-------|---------------|--------------|
+| 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 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::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
+
+### Mapfile
+
+Format: [ddrescue](https://www.gnu.org/software/ddrescue/manual/ddrescue_manual.html)-compatible
+plain text, greppable, tool-interoperable. Flushed to disk on every `record()`
+so a crashed rip loses at most one block.
+
+```
+# Rescue Logfile. Created by libfreemkv v0.13.6
+# Current pos / status / pass / pass_time
+0x000000000  ?  1  0
+#      pos        size  status
+0x000000000  0x12a35d000    +
+0x12a35d000  0x000003000    -
+0x12a360000  0x009c4a000    +
+0x12d00a000  0x000064000    *
+```
+
+Status characters match ddrescue:
+
+| Char | Meaning                                            |
+|------|----------------------------------------------------|
+| `?`  | Not yet attempted                                  |
+| `*`  | Fast-pass failed; needs edge-trim                  |
+| `/`  | Trimmed; interior needs sector scrape              |
+| `-`  | Unreadable this session                            |
+| `+`  | Finished (good)                                    |
+
+Position and size are hex byte offsets into the ISO.
+
+### `SweepOptions` and `PatchOptions`
+
+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
+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),
+}
+```
+
+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::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.
+3. On failure (with `multipass`): zero-fill, mark `*`, advance.
+4. Track a sliding window of the last 16 ECC block results. When ≥12% are failures
+   → **damage-jump**: skip ahead by `256×batch×multiplier` sectors (8 MB base for
+   UHD). Double the multiplier on each jump (8→16→32→64 MB...). Zero-fill the gap as `*`.
+5. On 16 consecutive good reads: reset jump multiplier to 1, restore max read speed.
+6. Speed control: damage zone entry → minimum speed, exit → maximum speed.
+7. Only transport failures (USB bridge crash) abort the pass.
+
+Pass 1 completes when every byte has been visited (either `+` or `*`).
+
+### 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).
+
+1. Issue a single-sector read with 60 s timeout (`recovery=true`). Drive firmware
+   does its own ECC recovery inside that window.
+2. On success: write the good bytes into the ISO, mark `+`.
+3. On failure with non-marginal SCSI sense: bail immediately (drive won't produce data).
+4. On failure with marginal sense: mark `-`, continue.
+5. Update the mapfile after every block — crash-safe resume.
+6. Wedged-drive exit: 50 consecutive failures with zero recovery → bail this pass.
+
+### In-stream — adaptive batch halving (`DiscStream::fill_extents`)
+
+When a consumer reads a `DiscStream` directly (no ISO intermediate),
+`fill_extents` runs an adaptive sizer in front of `Drive::read`:
+
+1. Try the current preferred batch size (e.g. 32 sectors, one BD ECC block).
+2. On failure: halve the batch and retry at the same LBA. Emit
+   `EventKind::BatchSizeChanged { reason: Shrunk }`.
+3. On a clean-read streak: probe back up toward the preferred size. Emit
+   `EventKind::BatchSizeChanged { reason: Probed }`.
+4. If a single-sector read fails: skip (zero-fill, emit
+   `EventKind::SectorSkipped`) when `skip_errors` is set, otherwise return
+   `Err(DiscRead)`.
+
+This is layer 3. It exists so a transient single-sector glitch in a 32-sector
+batch can be isolated and read individually without the caller needing to
+implement retry logic.
+
+## Design choices
+
+**`Drive::read` is single-shot.** No inline retry phases, no SCSI reset,
+no eject cycle. The `recovery` flag controls only the per-CDB timeout
+(1.5 s vs. 30 s); on any failure it returns `Err(DiscRead)` immediately.
+Inline recovery (5× gentle retry → close + SCSI reset + reopen → 5× more)
+was removed in 0.13.6. See the stop-wedge postmortem (2026-04-25) for rationale:
+the inline reset on the LG BU40N (Initio USB-SATA bridge)
+wedged drive firmware below the bridge without ever recovering a sector,
+and the gentle-retry phase produced long stretches of 0 KB/s with no
+recoveries to show for it. Recovery responsibility is now layered: layer 1
+handles ranges, layer 3 handles request size, neither touches the
+wedge-prone reset path.
+
+**No `MODE SELECT` to disable drive retries.** Neither ddrescue
+nor any consumer ripper does this. Drive firmware has access to raw analog signal, laser
+power control, and drive-specific ECC tuning that userspace can't replicate —
+disabling it throws away recovery headroom on marginal sectors. We fail fast
+via short SG_IO timeouts in pass 1 and let the firmware work the long timeout
+in pass 2 / patch.
+
+**No SCSI reset from any retry path.** `SgIoTransport::reset` (Linux) is
+trimmed to a kernel SG_IO state flush plus ALLOW MEDIUM REMOVAL — the
+`SG_SCSI_RESET` ioctl and STOP/START UNIT escalation were removed in 0.13.6.
+The macOS reset (which had been a no-op) was removed entirely. The top-level
+`scsi::reset()` / `reset_with_timeout()` / `reset_blocking()` wrappers were
+also removed (no callers). The remaining `Drive::reset()` is only invoked
+explicitly by callers that need an eject-cycle escape hatch — it is never
+reached from a read path.
+
+**ISO intermediate, even for single-pass.** Pass 1 always writes an ISO. The
+mux stage reads the ISO via `IsoSectorReader`. For single-pass (no retries),
+this adds ~2-3 min (local disk mux) but gains resumability across crashes,
+re-muxability without re-ripping, and a persistent forensic artifact. Callers
+who need pure speed can bypass and use `DiscStream::new(Box::new(drive), …)`
+directly — the lib doesn't forbid it, and layer 3 (adaptive batch halving)
+still applies there.
+
+**Mapfile in ddrescue format.** Plain text so users can `less` it, `diff` it,
+or feed it to ddrescue's own tooling. Crash-safe (flush-per-record). Entries
+coalesce on adjacent same-status ranges so files stay small.
+
+**Patches target `-`, `*`, `/`, and `?` alike.** The status state machine is
+ddrescue's but `patch` collapses the distinction — it just tries every
+non-finished range with the long timeout. Future work can specialize (trim vs.
+scrape vs. retry with direction reversal) if there's measured benefit.
+
+## References
+
+- [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/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`).

docs/udf.md

@@ -0,0 +1,177 @@
+# UDF 2.50 Filesystem Parser
+
+## What is UDF?
+
+UDF (Universal Disc Format) is the filesystem standard for optical media. It is defined by ECMA-167 with extensions from the OSTA (Optical Storage Technology Association). BD-ROM discs use UDF revision 2.50, which introduces the **metadata partition** -- a critical feature that separates file metadata from file content on disc.
+
+## Why UDF 2.50 for Blu-ray?
+
+Older UDF revisions (1.02, 1.50) scatter ICBs (file metadata) and file data across the same partition. On a high-capacity Blu-ray disc (25-100 GB), this creates excessive seeking when the drive needs to read a directory listing or locate a file. UDF 2.50 solves this by placing all metadata into a contiguous region near the beginning of the disc. The drive reads metadata from one compact area and streams file data from another -- no interleaved seeks.
+
+BD-ROM Part 3 of the Blu-ray specification mandates UDF 2.50.
+
+## Metadata Partitions
+
+A UDF 2.50 BD-ROM has two logical partitions:
+
+- **Partition 0 (Type 1)** -- the physical partition. Contains actual file data (m2ts streams, playlist files, etc.). Mapped directly to disc sectors starting at the Partition Descriptor's `partitionStartingLocation`.
+
+- **Partition 1 (Type 2)** -- the metadata partition. Contains all ICBs (Inode-like structures), directory data, and the File Set Descriptor. The metadata partition is itself stored as a file within the physical partition. Its location is found by reading an Extended File Entry at LBA 0 of the physical partition.
+
+The key rule: **ICBs and directory data live in the metadata partition. File content lives in the physical partition.** When an ICB's allocation descriptor gives an LBA, the partition it refers to depends on what the LBA describes -- metadata-relative for directory entries, physical-partition-relative for file data extents.
+
+## Pointer Chain
+
+Reading a UDF 2.50 filesystem follows a fixed chain of pointers. Each step reads one or two 2048-byte sectors:
+
+```
+Sector 256: AVDP (Anchor Volume Descriptor Pointer, tag 2)
+  |
+  v
+Sectors 32-63: VDS (Volume Descriptor Sequence)
+  |-- Partition Descriptor (tag 5) --> partition_start (physical sector)
+  |-- Logical Volume Descriptor (tag 6) --> partition maps, FSD location
+  |
+  v
+Partition Maps in LVD (offset 440):
+  |-- Map 0: Type 1 (physical partition)
+  |-- Map 1: Type 2 (metadata partition, identified by "*UDF Metadata Partition")
+  |
+  v
+Metadata file ICB at partition_start + 0 (Extended File Entry, tag 266)
+  |-- Allocation descriptor --> metadata content location
+  |
+  v
+metadata_start = partition_start + allocation_position
+  |
+  v
+FSD at metadata_start + 0 (File Set Descriptor, tag 256)
+  |-- Root Directory ICB: long_ad at offset 400 --> root_lba (metadata-relative)
+  |
+  v
+Root Directory ICB at metadata_start + root_lba (Extended File Entry, tag 266)
+  |-- Allocation descriptor --> directory data location (metadata-relative)
+  |
+  v
+Directory data: File Identifier Descriptors (tag 257)
+  |-- Each FID names a file/subdirectory and points to its ICB
+  |-- Recurse into subdirectories to build the full file tree
+```
+
+### AVDP (Sector 256)
+
+The Anchor Volume Descriptor Pointer is always at sector 256 (ECMA-167 section 10.2). It points to the Main Volume Descriptor Sequence. Tag identifier = 2.
+
+### VDS (Sectors 32+)
+
+The Volume Descriptor Sequence contains:
+
+- **Partition Descriptor (tag 5)**: byte offset 188 holds `partitionStartingLocation` -- the absolute sector where the physical partition begins.
+- **Logical Volume Descriptor (tag 6)**: byte offset 268 holds the number of partition maps. The partition maps themselves start at offset 440. For BD-ROM, map 0 is Type 1 (physical) and map 1 is Type 2 (metadata).
+- **Terminating Descriptor (tag 8)**: signals the end of the VDS.
+
+### Metadata File
+
+When two partition maps exist and the second is Type 2, the metadata partition content is located by reading the Extended File Entry at the first sector of the physical partition (partition_start + 0). This ICB's allocation descriptor gives the offset and length of the metadata content within the physical partition.
+
+### File Set Descriptor
+
+The FSD (tag 256) sits at metadata-relative LBA 0 (the first sector of the metadata content). It contains a long allocation descriptor at offset 400 pointing to the root directory ICB. The LBA in this long_ad is at bytes 404-407.
+
+### Directory Traversal
+
+Each directory is an ICB (Extended File Entry, tag 266, or File Entry, tag 261) whose allocation extent points to directory data. The directory data is a sequence of File Identifier Descriptors (FIDs, tag 257):
+
+| FID Field | Offset | Size | Description |
+|-----------|--------|------|-------------|
+| Tag | 0 | 2 | Always 257 |
+| File characteristics | 18 | 1 | Bit 1 = directory, bit 3 = parent |
+| L_FI (name length) | 19 | 1 | Length of filename |
+| ICB (long_ad) | 20 | 16 | Points to the entry's ICB |
+| L_IU | 36 | 2 | Implementation use length |
+| Filename | 38 + L_IU | L_FI | UDF-encoded filename |
+
+FIDs are 4-byte aligned. The parser advances by `(38 + L_IU + L_FI + 3) & !3` bytes per entry.
+
+### ICB Layout
+
+Both File Entry (tag 261) and Extended File Entry (tag 266) share the same info_length field:
+
+| Field | Tag 261 Offset | Tag 266 Offset |
+|-------|---------------|---------------|
+| info_length (u64) | 56 | 56 |
+| L_EA (u32) | 168 | 208 |
+| L_AD (u32) | 172 | 212 |
+| Allocation descriptors | 176 + L_EA | 216 + L_EA |
+
+Allocation descriptors use the Short Allocation Descriptor format: 4 bytes extent length (upper 2 bits = type), 4 bytes extent position (LBA).
+
+## How read_filesystem() Works
+
+The `read_filesystem()` function in `src/udf.rs` follows the pointer chain above:
+
+1. Reads sector 256, validates AVDP (tag 2).
+2. Scans sectors 32-63 for the Partition Descriptor and Logical Volume Descriptor.
+3. If two partition maps exist and the second is Type 2, reads the metadata file ICB at partition_start to find metadata_start.
+4. Reads the FSD at metadata_start, extracts the root directory ICB LBA.
+5. Calls `read_directory()` recursively (max depth 3) to build the full file tree.
+
+Each directory read involves two sector reads: one for the ICB, then one or more for the directory data. File sizes are read from info_length in each file's ICB.
+
+`read_file()` reads a file by navigating the directory tree, reading the file's ICB to get its data extent, then reading the data sector by sector from the **physical partition** (partition_start + LBA, not metadata_start).
+
+## Buffered Sector Reads
+
+USB optical drives have ~500ms round-trip latency per SCSI command. Since `read_filesystem()` and `read_file()` issue one SCSI READ per sector, a full disc scan can require hundreds of commands -- taking 10+ minutes on USB.
+
+`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 `SectorSource` implementation.
+
+### UDF Filename Encoding
+
+UDF filenames use a compression ID as the first byte:
+- `8` = 8-bit characters (ASCII)
+- `16` = 16-bit big-endian Unicode (UTF-16BE)
+
+The parser handles both encodings. All path lookups are case-insensitive.
+
+## BD-ROM Directory Structure
+
+A typical Blu-ray disc has this directory layout:
+
+```
+/
++-- BDMV/
+|   +-- index.bdmv          Disc index (title list, first play)
+|   +-- MovieObject.bdmv    Movie objects (navigation commands)
+|   +-- PLAYLIST/
+|   |   +-- 00000.mpls      Main movie playlist
+|   |   +-- 00001.mpls      Director's commentary
+|   |   +-- ...
+|   +-- CLIPINF/
+|   |   +-- 00001.clpi      Clip info for 00001.m2ts
+|   |   +-- 00002.clpi
+|   |   +-- ...
+|   +-- STREAM/
+|   |   +-- 00001.m2ts      Transport stream (video/audio/subtitle data)
+|   |   +-- 00002.m2ts
+|   |   +-- ...
+|   +-- BACKUP/              Duplicate of index, MovieObject, playlists, clip info
+|
++-- AACS/                    AACS encryption data (encrypted discs only)
+|   +-- Unit_Key_RO.inf      Unit key file (encrypted)
+|   +-- MKB_RW.inf           Media Key Block
+|   +-- Content000.cer       Content certificate
+|   +-- DUPLICATE/           Backup copies
+|
++-- CERTIFICATE/             BD+ certificate data (some discs)
+```
+
+The parser reads from `BDMV/PLAYLIST/` and `BDMV/CLIPINF/` to discover titles and their sector layouts. The `BDMV/STREAM/` directory contains the actual transport streams but is not parsed by the UDF layer -- stream data is read by LBA directly using extents computed from CLPI EP maps.
+
+## References
+
+- ECMA-167: Volume and File Structure of Write-Once and Rewritable Media
+- UDF 2.50 (OSTA): Universal Disk Format Specification
+- BD-ROM Part 3: Blu-ray Disc Read-Only Format, File System Specifications

examples/iso_dump.rs

@@ -0,0 +1,83 @@
+// Minimal ISO dumper — find exact stall point
+use libfreemkv::Drive;
+use std::io::{BufWriter, Write};
+use std::path::Path;
+use std::time::Instant;
+
+fn main() {
+    let args: Vec<String> = std::env::args().collect();
+    if args.len() < 3 {
+        eprintln!("Usage: iso_dump <device> <output>");
+        std::process::exit(1);
+    }
+
+    let mut drive = Drive::open(Path::new(&args[1])).unwrap();
+    drive.wait_ready().unwrap();
+    let _ = drive.init();
+    let _ = drive.probe_disc();
+
+    // AACS handshake — required to read past the protected area
+    eprint!("Scanning disc... ");
+    let _ = libfreemkv::Disc::scan(&mut drive, &libfreemkv::ScanOptions::default());
+    eprintln!("OK");
+
+    let cap = drive.read_capacity().unwrap();
+    let batch = libfreemkv::disc::detect_max_batch_sectors(drive.device_path());
+
+    eprintln!("Device: {} | {} sectors | batch {}", args[1], cap, batch);
+
+    let file = std::fs::File::create(&args[2]).unwrap();
+    let mut w = BufWriter::with_capacity(4 * 1024 * 1024, file);
+    let mut buf = vec![0u8; batch as usize * 2048];
+    let mut lba: u32 = 0;
+    let start = Instant::now();
+    let mut last = Instant::now();
+    let mut bytes: u64 = 0;
+    let mut last_bytes: u64 = 0;
+
+    while lba < cap {
+        let count = ((cap - lba) as u16).min(batch);
+        let n = count as usize * 2048;
+
+        // Tiny yield between reads — test if pacing prevents firmware throttle
+        std::thread::yield_now();
+        let t0 = Instant::now();
+        let ok = drive.read(lba, count, &mut buf[..n], true).is_ok();
+        let read_ms = t0.elapsed().as_millis();
+
+        // Flag slow reads
+        if read_ms > 2000 {
+            eprintln!("\n  SLOW READ: LBA {} took {}ms (ok={})", lba, read_ms, ok);
+        }
+
+        if !ok {
+            buf[..n].fill(0);
+        }
+        w.write_all(&buf[..n]).unwrap();
+        lba += count as u32;
+        bytes += n as u64;
+
+        if last.elapsed().as_millis() >= 1000 {
+            let delta = bytes - last_bytes;
+            let speed = delta as f64 / last.elapsed().as_secs_f64() / 1_048_576.0;
+            let avg = bytes as f64 / start.elapsed().as_secs_f64() / 1_048_576.0;
+            let pct = bytes as f64 / (cap as f64 * 2048.0) * 100.0;
+            eprint!(
+                "\r  {:.1}% LBA {} | {:.0} MB/s (avg {:.0}) | {:.1} GB    ",
+                pct,
+                lba,
+                speed,
+                avg,
+                bytes as f64 / 1e9
+            );
+            last_bytes = bytes;
+            last = Instant::now();
+        }
+    }
+    w.flush().unwrap();
+    eprintln!(
+        "\nDone: {:.1} GB in {:.0}s",
+        bytes as f64 / 1e9,
+        start.elapsed().as_secs_f64()
+    );
+}

rustfmt.toml

@@ -0,0 +1 @@
+max_width = 100

src/aacs/decrypt.rs

@@ -0,0 +1,483 @@
+//! AACS content decryption — AES primitives, unit decryption, bus encryption.
+
+use aes::Aes128;
+use aes::cipher::{BlockDecrypt, BlockEncrypt, KeyInit, generic_array::GenericArray};
+
+// ── AACS constants ──────────────────────────────────────────────────────────
+
+/// Fixed IV used by AACS for all AES-CBC operations.
+pub(crate) const AACS_IV: [u8; 16] = [
+    0x0B, 0xA0, 0xF8, 0xDD, 0xFE, 0xA6, 0x1F, 0xB3, 0xD8, 0xDF, 0x9F, 0x56, 0x6A, 0x05, 0x0F, 0x78,
+];
+
+/// Size of an AACS aligned unit (3 × 2048-byte sectors).
+pub const ALIGNED_UNIT_LEN: usize = 6144;
+
+/// Size of one sector.
+const SECTOR_LEN: usize = 2048;
+
+/// Transport stream packet spacing in Blu-ray m2ts (192 bytes = 4 TP_extra + 188 TS).
+const TS_PACKET_LEN: usize = 192;
+
+/// TS sync byte.
+const TS_SYNC: u8 = 0x47;
+
+// ── AES primitives ──────────────────────────────────────────────────────────
+
+/// AES-128-ECB encrypt a single 16-byte block.
+pub(crate) fn aes_ecb_encrypt(key: &[u8; 16], data: &[u8; 16]) -> [u8; 16] {
+    let cipher = Aes128::new(GenericArray::from_slice(key));
+    let mut block = GenericArray::clone_from_slice(data);
+    cipher.encrypt_block(&mut block);
+    let mut out = [0u8; 16];
+    out.copy_from_slice(&block);
+    out
+}
+
+/// AES-128-ECB decrypt a single 16-byte block.
+pub(crate) fn aes_ecb_decrypt(key: &[u8; 16], data: &[u8; 16]) -> [u8; 16] {
+    let cipher = Aes128::new(GenericArray::from_slice(key));
+    let mut block = GenericArray::clone_from_slice(data);
+    cipher.decrypt_block(&mut block);
+    let mut out = [0u8; 16];
+    out.copy_from_slice(&block);
+    out
+}
+
+/// AES-128-CBC decrypt in-place with the fixed AACS IV.
+///
+/// Precondition: `data.len()` is a multiple of 16. Any trailing partial
+/// block is silently ignored; all callers pass aligned regions (6128 and
+/// 2032 bytes), and the assert documents/enforces that contract.
+pub(crate) fn aes_cbc_decrypt(key: &[u8; 16], data: &mut [u8]) {
+    debug_assert!(
+        data.len() % 16 == 0,
+        "aes_cbc_decrypt requires a block-aligned slice"
+    );
+    let cipher = Aes128::new(GenericArray::from_slice(key));
+    let num_blocks = data.len() / 16;
+    // Process blocks in reverse to avoid clobbering ciphertext needed for XOR
+    for i in (0..num_blocks).rev() {
+        let offset = i * 16;
+        let prev = if i == 0 {
+            AACS_IV
+        } else {
+            let mut p = [0u8; 16];
+            p.copy_from_slice(&data[(i - 1) * 16..i * 16]);
+            p
+        };
+        let mut block = GenericArray::clone_from_slice(&data[offset..offset + 16]);
+        cipher.decrypt_block(&mut block);
+        for j in 0..16 {
+            data[offset + j] = block[j] ^ prev[j];
+        }
+    }
+}
+
+// ── Content decryption ──────────────────────────────────────────────────────
+
+/// True if a 6144-byte aligned unit is AACS-scrambled on disc.
+///
+/// AACS encrypts the unit body, which destroys the MPEG-TS sync bytes (`0x47`)
+/// a clear unit carries at offsets 4, 196, 388, … (one per 192-byte source
+/// packet). So "scrambled" = "the TS syncs are NOT intact". This is
+/// flag-independent: it does NOT read the TP_extra copy-control bits (byte 0)
+/// or the TS scrambling-control bits (byte 7) — AACS sets neither reliably
+/// across discs/players.
+///
+/// This is the single shared definition of "encrypted" for the whole ecosystem
+/// — libfreemkv's decrypt gate, autorip's sample selection, and the online key
+/// service's validation gate all call THIS, so they always agree on what is
+/// encrypted. A correctly-decrypted (or natively-clear) unit reports `false`,
+/// so the decrypt path never double-decrypts and there is no flag to clear.
+pub fn is_aacs_scrambled(unit: &[u8]) -> bool {
+    unit.len() >= ALIGNED_UNIT_LEN && !ts_syncs_intact(unit)
+}
+
+/// Count the MPEG-TS sync bytes (`0x47`) present at the BD-TS packet stride
+/// (offset 4 and every 192 bytes after — 4-byte TP_extra_header + 188-byte
+/// TS packet). A clear or correctly-decrypted m2ts unit shows ~one per
+/// packet; an encrypted unit, or a non-content unit decrypted under a key
+/// that doesn't apply, shows ~none.
+pub fn ts_sync_count(unit: &[u8]) -> usize {
+    let mut count = 0;
+    let mut offset = 4;
+    while offset < unit.len() {
+        if unit[offset] == TS_SYNC {
+            count += 1;
+        }
+        offset += TS_PACKET_LEN;
+    }
+    count
+}
+
+/// Number of BD-TS packets in the unit — the maximum possible sync count.
+pub fn ts_packet_total(unit: &[u8]) -> usize {
+    // One sync byte per 192-byte BD-TS packet (at offset 4 of each). The old
+    // `(len - 4) / TS_PACKET_LEN + 1` over-counted by one for lengths of the
+    // form `4 + k·192`.
+    unit.len() / TS_PACKET_LEN
+}
+
+fn ts_syncs_intact(unit: &[u8]) -> bool {
+    ts_sync_count(unit) > ts_packet_total(unit) / 2
+}
+
+/// Verify a decrypted unit looks like clear MPEG-TS (sync bytes intact).
+fn verify_ts(unit: &[u8]) -> bool {
+    ts_syncs_intact(unit)
+}
+
+/// Decrypt one AACS aligned unit (6144 bytes) in-place.
+/// Returns true if decryption succeeded (verified by TS sync bytes).
+///
+/// Algorithm:
+/// 1. AES-128-ECB encrypt first 16 bytes with unit_key → derived
+/// 2. XOR derived with original 16 bytes → unit_decrypt_key
+/// 3. AES-128-CBC decrypt bytes 16..6143 with unit_decrypt_key and AACS IV
+///
+/// Decryption restores the TS sync bytes, so the unit reads as clear afterward;
+/// there is no flag to clear.
+pub fn decrypt_unit(unit: &mut [u8], unit_key: &[u8; 16]) -> bool {
+    if unit.len() < ALIGNED_UNIT_LEN {
+        return false;
+    }
+    if !is_aacs_scrambled(unit) {
+        return true; // not encrypted
+    }
+
+    // Save original first 16 bytes (they're plaintext TP_extra_header)
+    let mut header = [0u8; 16];
+    header.copy_from_slice(&unit[..16]);
+
+    // Step 1: Encrypt header with unit key to derive per-unit key
+    let derived = aes_ecb_encrypt(unit_key, &header);
+
+    // Step 2: XOR to get the actual decryption key
+    let mut decrypt_key = [0u8; 16];
+    for i in 0..16 {
+        decrypt_key[i] = derived[i] ^ header[i];
+    }
+
+    // Step 3: Decrypt bytes 16..6143 with AES-CBC
+    aes_cbc_decrypt(&decrypt_key, &mut unit[16..ALIGNED_UNIT_LEN]);
+
+    // Decryption restored the TS syncs; verify the unit now looks like clear TS.
+    verify_ts(unit)
+}
+
+/// Fast, NON-MUTATING unit-key validation for the brute-force key search.
+///
+/// `decrypt_unit` pays a full 6128-byte (383-block) CBC decrypt before
+/// `verify_ts` can reject a wrong key — but in a brute scan ~every candidate is
+/// wrong. In CBC the plaintext of block *i* is `AES_dec(C_i) XOR C_{i-1}`, so
+/// the FIRST restored TS sync byte (payload offset 196, which lands in CBC
+/// block 11 of the `unit[16..]` region) can be recovered with a SINGLE block
+/// decrypt instead of 383. A wrong key fails this 1-byte gate ~255/256 of the
+/// time for the cost of one AES block; the rare survivor is then confirmed with
+/// the full [`decrypt_unit`], so the set of accepted keys is bit-for-bit
+/// identical to the slow path.
+///
+/// The caller MUST pass an aligned, already-[`is_aacs_scrambled`] unit
+/// (`unit.len() >= ALIGNED_UNIT_LEN`). The brute pre-filters its units, so the
+/// per-candidate scramble re-scan is intentionally skipped here.
+///
+/// NOTE: this is a search accelerator — it never writes the input and never
+/// participates in the content decrypt path. Aggregate correctness (does a key
+/// validate against *any* of the disc's units) is preserved because a true key
+/// restores offset-196 on every standard BD-TS unit.
+pub fn unit_key_validates(unit: &[u8], unit_key: &[u8; 16]) -> bool {
+    if unit.len() < ALIGNED_UNIT_LEN {
+        return false;
+    }
+    // Per-unit decrypt key: AES-ECB-encrypt the 16-byte plaintext header with
+    // the unit key, XOR with the header (same derivation as `decrypt_unit`).
+    let mut header = [0u8; 16];
+    header.copy_from_slice(&unit[..16]);
+    let derived = aes_ecb_encrypt(unit_key, &header);
+    let mut decrypt_key = [0u8; 16];
+    for i in 0..16 {
+        decrypt_key[i] = derived[i] ^ header[i];
+    }
+
+    // Cheap gate: recover ONLY payload byte 196 (the 2nd BD-TS packet's sync).
+    // The CBC region is `unit[16..]`; payload offset 196 → region offset 180 =
+    // block 11, byte 4. P[11] = AES_dec(C[11]) XOR C[10]; C[10] is raw
+    // ciphertext (no decrypt needed). Constant offsets for the fixed 6144 unit.
+    const SYNC_PAYLOAD_OFF: usize = 196;
+    let region_off = SYNC_PAYLOAD_OFF - 16; // 180
+    let blk = region_off / 16; // 11
+    let byte = region_off % 16; // 4
+    let c11 = 16 + blk * 16; // absolute offset of C[11] in `unit` (=192)
+    let cipher = Aes128::new(GenericArray::from_slice(&decrypt_key));
+    let mut b = GenericArray::clone_from_slice(&unit[c11..c11 + 16]);
+    cipher.decrypt_block(&mut b);
+    let prev = unit[c11 - 16 + byte]; // C[10] byte (region block 10)
+    if b[byte] ^ prev != TS_SYNC {
+        return false;
+    }
+
+    // Survivor (~1/256 of candidates): confirm with the authoritative full
+    // decrypt + verify, so the verdict matches `decrypt_unit` exactly.
+    let mut full = [0u8; ALIGNED_UNIT_LEN];
+    full.copy_from_slice(&unit[..ALIGNED_UNIT_LEN]);
+    decrypt_unit(&mut full, unit_key)
+}
+
+/// Outcome of [`decrypt_unit_try_keys`].
+///
+/// Distinguishes "the unit was already clear, no key was consumed" from "key
+/// at index `i` decrypted it" — the bare `Option<usize>` form conflated the two
+/// (a clear unit reported `Some(0)`, indistinguishable from key index 0, and
+/// possibly out of range when `unit_keys` is empty).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum UnitKeyResult {
+    /// The unit was not scrambled; it was left untouched and no key was used.
+    AlreadyClear,
+    /// The unit was decrypted in place by `unit_keys[index]`.
+    DecryptedWith(usize),
+}
+
+/// Decrypt one aligned unit trying multiple unit keys.
+///
+/// Returns [`UnitKeyResult::AlreadyClear`] if the unit was not scrambled (no key
+/// consumed), [`UnitKeyResult::DecryptedWith(i)`] if key `i` decrypted it, or
+/// `None` if no key worked (the unit is restored to its original bytes).
+pub fn decrypt_unit_try_keys(unit: &mut [u8], unit_keys: &[[u8; 16]]) -> Option<UnitKeyResult> {
+    if !is_aacs_scrambled(unit) {
+        return Some(UnitKeyResult::AlreadyClear);
+    }
+
+    // Save original for retry. Stack-backed buffer — no heap allocation, and the
+    // restore-on-failure contract holds uniformly regardless of key count.
+    let mut original = [0u8; ALIGNED_UNIT_LEN];
+    original.copy_from_slice(&unit[..ALIGNED_UNIT_LEN]);
+
+    for (i, key) in unit_keys.iter().enumerate() {
+        unit[..ALIGNED_UNIT_LEN].copy_from_slice(&original);
+        if decrypt_unit(unit, key) {
+            return Some(UnitKeyResult::DecryptedWith(i));
+        }
+    }
+
+    // Restore original on failure
+    unit[..ALIGNED_UNIT_LEN].copy_from_slice(&original);
+    None
+}
+
+/// Remove bus encryption from an aligned unit (AACS 2.0 / UHD).
+/// Bus encryption uses read_data_key, decrypting bytes 16..2047 of each 2048-byte sector.
+pub fn decrypt_bus(unit: &mut [u8], read_data_key: &[u8; 16]) {
+    for sector_start in (0..ALIGNED_UNIT_LEN).step_by(SECTOR_LEN) {
+        if sector_start + SECTOR_LEN > unit.len() {
+            break;
+        }
+        // First 16 bytes of each sector are plaintext
+        aes_cbc_decrypt(
+            read_data_key,
+            &mut unit[sector_start + 16..sector_start + SECTOR_LEN],
+        );
+    }
+}
+
+/// Full decrypt of an aligned unit: bus decrypt (if needed) then AACS decrypt.
+pub fn decrypt_unit_full(
+    unit: &mut [u8],
+    unit_key: &[u8; 16],
+    read_data_key: Option<&[u8; 16]>,
+) -> bool {
+    if !is_aacs_scrambled(unit) {
+        return true;
+    }
+    if let Some(rdk) = read_data_key {
+        decrypt_bus(unit, rdk);
+    }
+    decrypt_unit(unit, unit_key)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_aes_ecb_roundtrip() {
+        let key = [
+            0x15u8, 0x66, 0x5F, 0x98, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A,
+            0x0B, 0x0C,
+        ];
+        let plain = [0x41u8; 16];
+        let enc = aes_ecb_encrypt(&key, &plain);
+        let dec = aes_ecb_decrypt(&key, &enc);
+        assert_eq!(dec, plain);
+    }
+
+    #[test]
+    fn test_decrypt_unit_unencrypted() {
+        // A clear unit (TS syncs intact) is not scrambled → passes through.
+        let mut unit = vec![0u8; ALIGNED_UNIT_LEN];
+        let mut off = 4;
+        while off < ALIGNED_UNIT_LEN {
+            unit[off] = TS_SYNC;
+            off += TS_PACKET_LEN;
+        }
+        let key = [0u8; 16];
+        assert!(!is_aacs_scrambled(&unit));
+        assert!(decrypt_unit(&mut unit, &key));
+    }
+
+    #[test]
+    fn ts_packet_total_no_off_by_one() {
+        // The maximum sync count is exactly the number of stride
+        // positions the counting loop visits (offset 4, 196, ...), i.e.
+        // len / 192, NOT (len - 4) / 192 + 1. For the 6144-byte aligned unit
+        // the loop checks offsets 4..=5956 → 32 positions.
+        let unit = vec![0u8; ALIGNED_UNIT_LEN];
+        assert_eq!(ts_packet_total(&unit), 32);
+        // Confirm the loop visits exactly that many stride positions.
+        let visited = (4..ALIGNED_UNIT_LEN).step_by(TS_PACKET_LEN).count();
+        assert_eq!(visited, ts_packet_total(&unit));
+    }
+
+    #[test]
+    fn scramble_detection_at_16_32_boundary() {
+        // With 32 stride positions the majority threshold is
+        // total/2 = 16. A unit with EXACTLY half its syncs intact (16) must
+        // NOT be over-counted into the "scrambled" bucket by an inflated
+        // total: 16 > 16 is false → not-intact → scrambled. 17 intact → clear.
+        // The fix is that `total` is 32 (not 33), so the boundary sits cleanly
+        // at the real midpoint.
+        let set_syncs = |n: usize| {
+            let mut unit = vec![0u8; ALIGNED_UNIT_LEN];
+            let mut off = 4;
+            let mut placed = 0;
+            while off < ALIGNED_UNIT_LEN && placed < n {
+                unit[off] = TS_SYNC;
+                off += TS_PACKET_LEN;
+                placed += 1;
+            }
+            unit
+        };
+
+        assert_eq!(ts_sync_count(&set_syncs(16)), 16);
+        assert_eq!(ts_sync_count(&set_syncs(17)), 17);
+
+        // Exactly half intact → classified scrambled (16 > 16 is false).
+        assert!(is_aacs_scrambled(&set_syncs(16)));
+        // One past half → classified clear.
+        assert!(!is_aacs_scrambled(&set_syncs(17)));
+    }
+
+    #[test]
+    fn scramble_detection_extremes() {
+        // Detection semantics for the clear-cut cases must be preserved:
+        // a fully-clear unit (all 32 syncs) is NOT scrambled; a unit with no
+        // syncs (fully scrambled body) IS scrambled.
+        let mut clear = vec![0u8; ALIGNED_UNIT_LEN];
+        let mut off = 4;
+        while off < ALIGNED_UNIT_LEN {
+            clear[off] = TS_SYNC;
+            off += TS_PACKET_LEN;
+        }
+        assert_eq!(ts_sync_count(&clear), 32);
+        assert!(
+            !is_aacs_scrambled(&clear),
+            "fully-clear unit → not scrambled"
+        );
+
+        let scrambled = vec![0u8; ALIGNED_UNIT_LEN];
+        assert_eq!(ts_sync_count(&scrambled), 0);
+        assert!(is_aacs_scrambled(&scrambled), "no syncs → scrambled");
+    }
+
+    #[test]
+    fn test_aes_cbc_roundtrip() {
+        let key = [
+            0x11u8, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE,
+            0xFF, 0x00,
+        ];
+        let original = vec![0x42u8; 128]; // 8 blocks
+        let mut data = original.clone();
+
+        // Encrypt with CBC manually (forward direction)
+        fn aes_cbc_encrypt(key: &[u8; 16], data: &mut [u8]) {
+            let cipher = Aes128::new(GenericArray::from_slice(key));
+            let mut prev = super::AACS_IV;
+            let num_blocks = data.len() / 16;
+            for i in 0..num_blocks {
+                let offset = i * 16;
+                for j in 0..16 {
+                    data[offset + j] ^= prev[j];
+                }
+                let mut block = GenericArray::clone_from_slice(&data[offset..offset + 16]);
+                cipher.encrypt_block(&mut block);
+                data[offset..offset + 16].copy_from_slice(&block);
+                prev.copy_from_slice(&data[offset..offset + 16]);
+            }
+        }
+
+        aes_cbc_encrypt(&key, &mut data);
+        assert_ne!(data, original); // should be different after encrypt
+
+        super::aes_cbc_decrypt(&key, &mut data);
+        assert_eq!(data, original); // should match after roundtrip
+    }
+
+    #[test]
+    fn test_decrypt_unit_synthetic() {
+        // Build a fake 6144-byte aligned unit with known TS sync pattern,
+        // encrypt it with the AACS algorithm, then decrypt and verify.
+        let unit_key = [0xAAu8; 16];
+
+        // Build plaintext unit with TS sync bytes every 192 bytes starting at offset 4
+        let mut plain = vec![0u8; ALIGNED_UNIT_LEN];
+        let mut offset = 4;
+        while offset < ALIGNED_UNIT_LEN {
+            plain[offset] = TS_SYNC;
+            offset += TS_PACKET_LEN;
+        }
+        // No flag set: CBC-encrypting the body below scrambles packets 1..31's
+        // TS syncs, which is exactly what `is_aacs_scrambled` (raw-sync) detects.
+
+        // Now encrypt bytes 16..6143 using the AACS algorithm (reverse of decrypt)
+        let header: [u8; 16] = plain[..16].try_into().unwrap();
+        let derived = aes_ecb_encrypt(&unit_key, &header);
+        let mut encrypt_key = [0u8; 16];
+        for i in 0..16 {
+            encrypt_key[i] = derived[i] ^ header[i];
+        }
+
+        // CBC encrypt bytes 16..6143
+        let cipher = Aes128::new(GenericArray::from_slice(&encrypt_key));
+        let mut prev = AACS_IV;
+        let num_blocks = (ALIGNED_UNIT_LEN - 16) / 16;
+        for i in 0..num_blocks {
+            let off = 16 + i * 16;
+            for j in 0..16 {
+                plain[off + j] ^= prev[j];
+            }
+            let mut block = GenericArray::clone_from_slice(&plain[off..off + 16]);
+            cipher.encrypt_block(&mut block);
+            plain[off..off + 16].copy_from_slice(&block);
+            prev.copy_from_slice(&plain[off..off + 16]);
+        }
+
+        // Now plain contains encrypted data. Decrypt it.
+        let mut unit = plain;
+        assert!(is_aacs_scrambled(&unit));
+        assert!(decrypt_unit(&mut unit, &unit_key));
+        assert!(!is_aacs_scrambled(&unit)); // decrypted: TS syncs restored
+
+        // Verify TS sync bytes
+        let mut count = 0;
+        let mut off = 4;
+        while off < ALIGNED_UNIT_LEN {
+            if unit[off] == TS_SYNC {
+                count += 1;
+            }
+            off += TS_PACKET_LEN;
+        }
+        // Assert against the single canonical packet count, not the old
+        // `(len - 4) / 192 + 1` form that `ts_packet_total` corrected away from.
+        assert_eq!(count, ts_packet_total(&unit));
+    }
+}

src/aacs/keydb.rs

@@ -0,0 +1,678 @@
+//! AACS Key Database parsing — KEYDB.cfg format.
+
+use std::collections::HashMap;
+
+/// Parsed AACS key database.
+#[derive(Debug)]
+pub struct KeyDb {
+    /// Device keys for MKB processing
+    pub device_keys: Vec<DeviceKey>,
+    /// Processing keys (pre-computed media keys for specific MKB versions)
+    pub processing_keys: Vec<[u8; 16]>,
+    /// Host certificate + private key for SCSI authentication
+    pub host_certs: Vec<HostCert>,
+    /// Per-disc VUK entries indexed by disc hash (hex lowercase)
+    pub disc_entries: HashMap<String, DiscEntry>,
+}
+
+/// A device key for MKB subset-difference tree processing.
+#[derive(Debug, Clone)]
+pub struct DeviceKey {
+    pub key: [u8; 16],
+    pub node: u16,
+    pub uv: u32,
+    pub u_mask_shift: u8,
+}
+
+/// Host certificate + private key for AACS SCSI authentication.
+#[derive(Debug, Clone)]
+pub struct HostCert {
+    /// AACS 1.0: 20 bytes. AACS 2.0: 32 bytes.
+    pub private_key: [u8; 20],
+    /// AACS 1.0: 92 bytes. AACS 2.0: 132 bytes.
+    pub certificate: Vec<u8>,
+    /// AACS 2.0 host private key (P-256, 32 bytes). None for AACS 1.0 only.
+    pub private_key_v2: Option<[u8; 32]>,
+    /// AACS 2.0 host certificate (type 0x11). None for AACS 1.0 only.
+    pub certificate_v2: Option<Vec<u8>>,
+}
+
+/// A per-disc entry from the key database.
+#[derive(Debug, Clone)]
+pub struct DiscEntry {
+    /// Disc hash (20 bytes, hex)
+    pub disc_hash: String,
+    /// Disc title
+    pub title: String,
+    /// Media Key (16 bytes) — from MKB processing
+    pub media_key: Option<[u8; 16]>,
+    /// Disc ID (16 bytes)
+    pub disc_id: Option<[u8; 16]>,
+    /// Volume Unique Key (16 bytes) — decrypts title keys
+    pub vuk: Option<[u8; 16]>,
+    /// Unit keys (title keys) indexed by CPS unit number
+    pub unit_keys: Vec<(u32, [u8; 16])>,
+}
+
+/// Parse a hex string like "0xABCD..." into bytes.
+///
+/// Operates on bytes, not `&str` char boundaries: the keydb is
+/// third-party content, so a non-ASCII scalar (e.g. a 4-byte UTF-8
+/// codepoint) must not panic on a mid-codepoint slice. Any non-hex
+/// byte yields `None`.
+pub(crate) fn parse_hex(s: &str) -> Option<Vec<u8>> {
+    let s = s.trim().trim_start_matches("0x").trim_start_matches("0X");
+    let bytes = s.as_bytes();
+    if bytes.len() % 2 != 0 {
+        return None;
+    }
+    let mut out = Vec::with_capacity(bytes.len() / 2);
+    for pair in bytes.chunks_exact(2) {
+        let hi = (pair[0] as char).to_digit(16)?;
+        let lo = (pair[1] as char).to_digit(16)?;
+        out.push((hi * 16 + lo) as u8);
+    }
+    Some(out)
+}
+
+/// Parse hex into a fixed-size array.
+pub(crate) fn parse_hex16(s: &str) -> Option<[u8; 16]> {
+    let v = parse_hex(s)?;
+    if v.len() != 16 {
+        return None;
+    }
+    let mut out = [0u8; 16];
+    out.copy_from_slice(&v);
+    Some(out)
+}
+
+pub(crate) fn parse_hex20(s: &str) -> Option<[u8; 20]> {
+    let v = parse_hex(s)?;
+    if v.len() != 20 {
+        return None;
+    }
+    let mut out = [0u8; 20];
+    out.copy_from_slice(&v);
+    Some(out)
+}
+
+impl KeyDb {
+    /// Construct an empty KeyDb. Used by unit tests; production code
+    /// reaches a populated KeyDb via [`KeyDb::load`] or [`KeyDb::parse`].
+    pub fn empty() -> Self {
+        KeyDb {
+            device_keys: Vec::new(),
+            processing_keys: Vec::new(),
+            host_certs: Vec::new(),
+            disc_entries: HashMap::new(),
+        }
+    }
+
+    /// Parse a KEYDB.cfg file from a string.
+    pub fn parse(data: &str) -> Self {
+        let mut db = KeyDb {
+            device_keys: Vec::new(),
+            processing_keys: Vec::new(),
+            host_certs: Vec::new(),
+            disc_entries: HashMap::new(),
+        };
+
+        for line in data.lines() {
+            let line = line.trim();
+
+            // Skip comments and empty lines
+            if line.is_empty() || line.starts_with(';') || line.starts_with('#') {
+                continue;
+            }
+
+            // Device Key.
+            // Two shapes are accepted:
+            //   1. Positioned DK: `| DK | DEVICE_KEY 0x... | DEVICE_NODE 0x... | KEY_UV 0x... | KEY_U_MASK_SHIFT 0x...`
+            //      → loaded into `device_keys` (deterministic tree walk via `calc_pk_from_dk`).
+            //   2. Orphan DK: `| DK | DEVICE_KEY 0x...` with no position fields.
+            //      → loaded into `processing_keys` (brute walker / terminal validation).
+            // Per AACS spec a "PK" IS a DK at terminal position, so both row types
+            // are DKs in the unified model; only the metadata differs.
+            if line.starts_with("| DK") {
+                if let Some(dk) = Self::parse_device_key(line) {
+                    db.device_keys.push(dk);
+                } else if let Some(key) = Self::parse_orphan_dk(line) {
+                    db.processing_keys.push(key);
+                }
+                continue;
+            }
+
+            // Processing Key
+            if line.starts_with("| PK") {
+                if let Some(pk) = Self::parse_processing_key(line) {
+                    db.processing_keys.push(pk);
+                }
+                continue;
+            }
+
+            // Host Certificate (AACS 2.0).
+            //
+            // An HC2 row normally augments the preceding HC (AACS 1.0) row.
+            // KEYDB line ordering is third-party, so an HC2 row may appear
+            // before any HC row; rather than silently dropping the AACS 2.0
+            // credentials, carry them on a fresh HostCert with an empty v1
+            // cert (the v1 private_key/certificate stay zero/empty and are
+            // ignored by the v1 handshake, which guards on cert length).
+            if line.starts_with("| HC2") {
+                if let Some((pk, cert)) = Self::parse_host_cert_v2(line) {
+                    if let Some(hc) = db.host_certs.last_mut() {
+                        hc.private_key_v2 = Some(pk);
+                        hc.certificate_v2 = Some(cert);
+                    } else {
+                        db.host_certs.push(HostCert {
+                            private_key: [0u8; 20],
+                            certificate: Vec::new(),
+                            private_key_v2: Some(pk),
+                            certificate_v2: Some(cert),
+                        });
+                    }
+                }
+                continue;
+            }
+
+            // Host Certificate (AACS 1.0)
+            if line.starts_with("| HC") {
+                if let Some(hc) = Self::parse_host_cert(line) {
+                    db.host_certs.push(hc);
+                }
+                continue;
+            }
+
+            // Disc entry: starts with 0x
+            if line.starts_with("0x") && line.contains(" = ") {
+                if let Some(entry) = Self::parse_disc_entry(line) {
+                    db.disc_entries.insert(entry.disc_hash.clone(), entry);
+                }
+            }
+        }
+
+        db
+    }
+
+    /// Load a KEYDB.cfg from disk.
+    ///
+    /// A read failure (missing/unreadable file, non-UTF-8 content) surfaces
+    /// as [`crate::error::Error::KeydbLoad`] carrying the path, per the
+    /// library contract that a missing/unparseable keydb is a structured
+    /// error and not a raw `io::Error`. Note that [`Self::parse`] itself is
+    /// lenient: a syntactically valid but key-less file parses to an empty
+    /// [`KeyDb`] rather than an error — callers needing a non-empty db must
+    /// check the parsed contents.
+    pub fn load(path: &std::path::Path) -> crate::error::Result<Self> {
+        let data = std::fs::read_to_string(path).map_err(|_| crate::error::Error::KeydbLoad {
+            path: path.display().to_string(),
+        })?;
+        Ok(Self::parse(&data))
+    }
+
+    /// Look up a disc by its hash. Returns the VUK if found.
+    pub fn find_vuk(&self, disc_hash: &str) -> Option<[u8; 16]> {
+        let hash = disc_hash
+            .trim()
+            .to_lowercase()
+            .trim_start_matches("0x")
+            .to_string();
+        // Try with 0x prefix and without
+        self.disc_entries
+            .get(&format!("0x{hash}"))
+            .or_else(|| self.disc_entries.get(&hash))
+            .and_then(|e| e.vuk)
+    }
+
+    /// Look up a disc by its hash. Returns the full entry.
+    pub fn find_disc(&self, disc_hash: &str) -> Option<&DiscEntry> {
+        let hash = disc_hash
+            .trim()
+            .to_lowercase()
+            .trim_start_matches("0x")
+            .to_string();
+        self.disc_entries
+            .get(&format!("0x{hash}"))
+            .or_else(|| self.disc_entries.get(&hash))
+    }
+
+    /// Iterate every disc entry. Used by Path 3 (scan for matching VID).
+    pub fn iter_disc_entries(&self) -> impl Iterator<Item = &DiscEntry> {
+        self.disc_entries.values()
+    }
+}
+
+// ── KeyProvider impl ──────────────────────────────────────────────────────────
+//
+// Lets `KeyDb` plug into `resolve_keys` via the trait. Cloning happens in the
+// bulk methods because the trait returns owned `Vec`s (so HTTP-backed providers
+// don't need to retain state across calls).
+
+impl super::provider::KeyProvider for KeyDb {
+    fn device_keys(&self) -> Vec<DeviceKey> {
+        self.device_keys.clone()
+    }
+    fn processing_keys(&self) -> Vec<[u8; 16]> {
+        self.processing_keys.clone()
+    }
+    fn media_keys(&self) -> Vec<[u8; 16]> {
+        // Every per-disc Media Key in the db. The resolver dedups; MKs are
+        // MKB-scoped so the same value recurs across a pressing's discs.
+        self.iter_disc_entries()
+            .filter_map(|e| e.media_key)
+            .collect()
+    }
+    fn host_certs(&self) -> Vec<HostCert> {
+        self.host_certs.clone()
+    }
+    fn lookup_disc_by_hash(&self, disc_hash: &[u8; 20]) -> Option<DiscEntry> {
+        use std::fmt::Write;
+        // Lowercase hex written straight into the pre-sized buffer: find_disc
+        // lowercases its input anyway, so emitting 'x' here avoids a wasted
+        // to_lowercase() round-trip, and write! avoids 20 temporary Strings.
+        let mut hex = String::with_capacity(42);
+        hex.push_str("0x");
+        for b in disc_hash {
+            let _ = write!(hex, "{b:02x}");
+        }
+        self.find_disc(&hex).cloned()
+    }
+    fn lookup_disc_by_vid(&self, volume_id: &[u8; 16]) -> Option<DiscEntry> {
+        self.iter_disc_entries()
+            .find(|e| matches!(e.disc_id, Some(id) if &id == volume_id))
+            .cloned()
+    }
+}
+
+// ── Private parsers (re-open the inherent impl) ─────────────────────────────
+
+impl KeyDb {
+    fn parse_device_key(line: &str) -> Option<DeviceKey> {
+        // | DK | DEVICE_KEY 0x... | DEVICE_NODE 0x... | KEY_UV 0x... | KEY_U_MASK_SHIFT 0x...
+        let key_str = line.split("DEVICE_KEY").nth(1)?.split('|').next()?.trim();
+        let node_str = line.split("DEVICE_NODE").nth(1)?.split('|').next()?.trim();
+        let uv_str = line.split("KEY_UV").nth(1)?.split('|').next()?.trim();
+        let shift_str = line
+            .split("KEY_U_MASK_SHIFT")
+            .nth(1)?
+            .split(';')
+            .next()?
+            .split('|')
+            .next()?
+            .trim();
+
+        Some(DeviceKey {
+            key: parse_hex16(key_str)?,
+            node: u16::from_str_radix(node_str.trim_start_matches("0x"), 16).ok()?,
+            uv: u32::from_str_radix(uv_str.trim_start_matches("0x"), 16).ok()?,
+            u_mask_shift: u8::from_str_radix(shift_str.trim_start_matches("0x"), 16).ok()?,
+        })
+    }
+
+    fn parse_processing_key(line: &str) -> Option<[u8; 16]> {
+        // | PK | 0x...
+        let parts: Vec<&str> = line.split('|').collect();
+        if parts.len() >= 3 {
+            let key_str = parts[2].split(';').next()?.trim();
+            return parse_hex16(key_str);
+        }
+        None
+    }
+
+    /// Parse an orphan DK row: a `| DK |` line carrying only the
+    /// `DEVICE_KEY` field (no position metadata). The key is then
+    /// treated like a terminal/unpositioned label by the resolver
+    /// (Path 2's brute walker). Returns `None` if the line carries
+    /// any position field — those are positioned DKs and parsed by
+    /// [`Self::parse_device_key`] instead.
+    fn parse_orphan_dk(line: &str) -> Option<[u8; 16]> {
+        if line.contains("DEVICE_NODE")
+            || line.contains("KEY_UV")
+            || line.contains("KEY_U_MASK_SHIFT")
+        {
+            return None;
+        }
+        let key_str = line
+            .split("DEVICE_KEY")
+            .nth(1)?
+            .split('|')
+            .next()?
+            .split(';')
+            .next()?
+            .trim();
+        parse_hex16(key_str)
+    }
+
+    fn parse_host_cert(line: &str) -> Option<HostCert> {
+        // | HC | HOST_PRIV_KEY 0x... | HOST_CERT 0x...
+        let priv_str = line
+            .split("HOST_PRIV_KEY")
+            .nth(1)?
+            .split('|')
+            .next()?
+            .trim();
+        let cert_str = line
+            .split("HOST_CERT")
+            .nth(1)?
+            .split(';')
+            .next()?
+            .split('|')
+            .next()?
+            .trim();
+
+        let certificate = parse_hex(cert_str)?;
+        // AACS 1.0 host certs are 92 bytes; drop malformed/short rows at
+        // parse time so the handshake never attempts junk (mirrors the v2
+        // path, which enforces >= 132).
+        if certificate.len() < 92 {
+            return None;
+        }
+
+        Some(HostCert {
+            private_key: parse_hex20(priv_str)?,
+            certificate,
+            private_key_v2: None,
+            certificate_v2: None,
+        })
+    }
+
+    /// Parse AACS 2.0 host cert: `| HC2 | HOST_PRIV_KEY 0x... | HOST_CERT 0x...`
+    fn parse_host_cert_v2(line: &str) -> Option<([u8; 32], Vec<u8>)> {
+        let priv_str = line
+            .split("HOST_PRIV_KEY")
+            .nth(1)?
+            .split('|')
+            .next()?
+            .trim();
+        let cert_str = line
+            .split("HOST_CERT")
+            .nth(1)?
+            .split(';')
+            .next()?
+            .split('|')
+            .next()?
+            .trim();
+
+        let priv_bytes = parse_hex(priv_str)?;
+        if priv_bytes.len() != 32 {
+            return None;
+        }
+        let mut pk = [0u8; 32];
+        pk.copy_from_slice(&priv_bytes);
+
+        let cert = parse_hex(cert_str)?;
+        if cert.len() < 132 {
+            return None;
+        }
+
+        Some((pk, cert))
+    }
+
+    fn parse_disc_entry(line: &str) -> Option<DiscEntry> {
+        // 0x<hash> = <title> | D | <date> | M | 0x<mk> | I | 0x<id> | V | 0x<vuk> | U | <unit_keys>
+        let (hash_part, rest) = line.split_once(" = ")?;
+        let disc_hash = hash_part.trim().to_lowercase();
+
+        // Extract title (before first |)
+        let title_part = rest.split(" | ").next().unwrap_or("").trim();
+        // Clean title: "TITLE_NAME (Display Title)" → use display title if
+        // present. keydb.cfg is untrusted third-party content, so a title with
+        // ')' before '(' (e.g. "FILM) (X") would make start+1 > end; guard the
+        // slice and fall back to the whole title.
+        let title = match (title_part.find('('), title_part.rfind(')')) {
+            (Some(start), Some(end)) => title_part
+                .get(start + 1..end)
+                .map(str::to_string)
+                .unwrap_or_else(|| title_part.to_string()),
+            _ => title_part.to_string(),
+        };
+
+        // Parse fields by tag
+        let mut media_key = None;
+        let mut disc_id = None;
+        let mut vuk = None;
+        let mut unit_keys = Vec::new();
+
+        let parts: Vec<&str> = rest.split(" | ").collect();
+        let mut i = 0;
+        while i < parts.len() {
+            match parts[i].trim() {
+                "M" => {
+                    if i + 1 < parts.len() {
+                        media_key = parse_hex16(parts[i + 1].trim());
+                        i += 1;
+                    }
+                }
+                "I" => {
+                    if i + 1 < parts.len() {
+                        disc_id = parse_hex16(parts[i + 1].trim());
+                        i += 1;
+                    }
+                }
+                "V" => {
+                    if i + 1 < parts.len() {
+                        vuk = parse_hex16(parts[i + 1].trim());
+                        i += 1;
+                    }
+                }
+                "U" => {
+                    if i + 1 < parts.len() {
+                        // Unit keys: "1-0xKEY" or "1-0xKEY ; comment"
+                        let uk_str = parts[i + 1].split(';').next().unwrap_or("").trim();
+                        for uk in uk_str.split(' ') {
+                            let uk = uk.trim();
+                            if let Some((num, key)) = uk.split_once('-') {
+                                if let Ok(n) = num.parse::<u32>() {
+                                    if let Some(k) = parse_hex16(key) {
+                                        unit_keys.push((n, k));
+                                    }
+                                }
+                            }
+                        }
+                        i += 1;
+                    }
+                }
+                _ => {}
+            }
+            i += 1;
+        }
+
+        Some(DiscEntry {
+            disc_hash,
+            title,
+            media_key,
+            disc_id,
+            vuk,
+            unit_keys,
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Get KEYDB path from KEYDB_PATH environment variable. Returns None if not set or not found.
+    fn keydb_path() -> Option<std::path::PathBuf> {
+        let path = std::path::PathBuf::from(std::env::var("KEYDB_PATH").ok()?);
+        if path.exists() { Some(path) } else { None }
+    }
+
+    #[test]
+    fn test_parse_disc_entry() {
+        // All-zero placeholders — synthetic; no real key material in code.
+        let z40 = "00".repeat(20);
+        let z32 = "00".repeat(16);
+        let line = format!(
+            "0x{z40} = SAMPLE_FILM (Sample Film) | D | 2024-01-01 | M | 0x{z32} | I | 0x{z32} | V | 0x{z32} | U | 1-0x{z32} ; MKBv77"
+        );
+        let entry = KeyDb::parse_disc_entry(&line).unwrap();
+        assert_eq!(entry.title, "Sample Film");
+        assert!(entry.media_key.is_some());
+        assert!(entry.vuk.is_some());
+        assert_eq!(entry.unit_keys.len(), 1);
+        assert_eq!(entry.unit_keys[0].0, 1);
+    }
+
+    // NOTE: key fields below use obvious repeated-byte / zero placeholders
+    // (0x01.., 0x02.., 0x03.., 0x00..). NEVER put real — or real-looking — host,
+    // device, or processing key material in code; these tests exercise the
+    // parser's field-splitting only, not any genuine key.
+
+    #[test]
+    fn test_parse_device_key() {
+        let line = "| DK | DEVICE_KEY 0x00000000000000000000000000000000 | DEVICE_NODE 0x0800 | KEY_UV 0x00000400 | KEY_U_MASK_SHIFT 0x17 ; MKBv01-MKBv48";
+        let dk = KeyDb::parse_device_key(line).unwrap();
+        assert_eq!(dk.node, 0x0800);
+        assert_eq!(dk.u_mask_shift, 0x17);
+    }
+
+    #[test]
+    fn test_orphan_dk_row_loads_into_processing_keys() {
+        // `| DK |` row without position fields = an orphan DK. Per the
+        // unified model the resolver treats it like a terminal/PK
+        // candidate: it lands in `processing_keys` and the brute walker
+        // handles it.
+        let cfg = r#"
+| DK | DEVICE_KEY 0x01010101010101010101010101010101 ; orphan, no position fields
+| DK | DEVICE_KEY 0x02020202020202020202020202020202 | DEVICE_NODE 0x0800 | KEY_UV 0x00000400 | KEY_U_MASK_SHIFT 0x17 ; positioned MKBv01-MKBv48
+| PK | 0x03030303030303030303030303030303 ; legacy PK row still works
+"#;
+        let db = KeyDb::parse(cfg);
+        assert_eq!(
+            db.device_keys.len(),
+            1,
+            "positioned DK row should land in device_keys"
+        );
+        // Orphan DK + legacy PK row both end up in processing_keys.
+        assert_eq!(
+            db.processing_keys.len(),
+            2,
+            "orphan DK row + legacy PK row both belong in processing_keys"
+        );
+        assert_eq!(db.processing_keys[0][..4], [0x01, 0x01, 0x01, 0x01]);
+        assert_eq!(db.processing_keys[1][..4], [0x03, 0x03, 0x03, 0x03]);
+    }
+
+    #[test]
+    fn test_parse_orphan_dk_rejects_lines_with_position_fields() {
+        // The parser must NOT pick up a positioned DK row as an orphan
+        // (that would double-count). parse_orphan_dk explicitly checks.
+        let positioned = "| DK | DEVICE_KEY 0x02020202020202020202020202020202 | DEVICE_NODE 0x0800 | KEY_UV 0x00000400 | KEY_U_MASK_SHIFT 0x17";
+        assert!(
+            KeyDb::parse_orphan_dk(positioned).is_none(),
+            "positioned DK must not match orphan parser"
+        );
+        let orphan = "| DK | DEVICE_KEY 0x01010101010101010101010101010101";
+        let key = KeyDb::parse_orphan_dk(orphan).expect("orphan should parse");
+        assert_eq!(key[..4], [0x01, 0x01, 0x01, 0x01]);
+    }
+
+    #[test]
+    fn test_parse_host_cert() {
+        // 20-byte priv + 92-byte cert, all zeros — placeholders, not a key.
+        let line = format!(
+            "| HC | HOST_PRIV_KEY 0x{} | HOST_CERT 0x{} ; Revoked",
+            "00".repeat(20),
+            "00".repeat(92)
+        );
+        let hc = KeyDb::parse_host_cert(&line).unwrap();
+        assert_eq!(hc.private_key, [0u8; 20]);
+        assert_eq!(hc.certificate.len(), 92);
+    }
+
+    #[test]
+    fn test_parse_hex_rejects_non_ascii_without_panic() {
+        // A 4-byte UTF-8 scalar has byte-len 4 (passes the even check); the
+        // old &str-slice path panicked on the mid-codepoint boundary. The
+        // byte-wise parser must instead return None.
+        assert!(parse_hex("😀").is_none());
+        // Mixed: leading hex then a 2-byte UTF-8 scalar (byte-len even).
+        assert!(parse_hex("ABé").is_none());
+        // Sanity: well-formed hex still parses.
+        assert_eq!(parse_hex("0x00FF"), Some(vec![0x00, 0xFF]));
+        // Odd byte length still rejected.
+        assert!(parse_hex("ABC").is_none());
+    }
+
+    #[test]
+    fn test_hc2_before_hc_is_not_dropped() {
+        // An HC2 row appearing before any HC row must still land its AACS 2.0
+        // credentials on a HostCert rather than being silently discarded.
+        let cfg = format!(
+            "| HC2 | HOST_PRIV_KEY 0x{} | HOST_CERT 0x{}\n",
+            "00".repeat(32),
+            "00".repeat(132)
+        );
+        let db = KeyDb::parse(&cfg);
+        assert_eq!(
+            db.host_certs.len(),
+            1,
+            "HC2-only row must create a HostCert"
+        );
+        assert!(db.host_certs[0].private_key_v2.is_some());
+        assert!(db.host_certs[0].certificate_v2.is_some());
+        assert!(
+            db.host_certs[0].certificate.is_empty(),
+            "v1 cert stays empty for an HC2-only carrier"
+        );
+    }
+
+    #[test]
+    fn test_hc2_after_hc_augments_existing() {
+        let cfg = format!(
+            "| HC | HOST_PRIV_KEY 0x{} | HOST_CERT 0x{}\n| HC2 | HOST_PRIV_KEY 0x{} | HOST_CERT 0x{}\n",
+            "00".repeat(20),
+            "00".repeat(92),
+            "00".repeat(32),
+            "00".repeat(132)
+        );
+        let db = KeyDb::parse(&cfg);
+        assert_eq!(db.host_certs.len(), 1, "HC2 augments the preceding HC");
+        assert_eq!(db.host_certs[0].certificate.len(), 92);
+        assert!(db.host_certs[0].certificate_v2.is_some());
+    }
+
+    #[test]
+    fn test_parse_host_cert_rejects_short_v1_cert() {
+        // A too-short AACS 1.0 cert must be dropped at parse time.
+        let line = format!(
+            "| HC | HOST_PRIV_KEY 0x{} | HOST_CERT 0x{}",
+            "00".repeat(20),
+            "00".repeat(10)
+        );
+        assert!(KeyDb::parse_host_cert(&line).is_none());
+    }
+
+    #[test]
+    fn test_parse_full_keydb() {
+        let path = match keydb_path() {
+            Some(p) => p,
+            None => return,
+        }; // skip if not available
+
+        let db = KeyDb::load(&path).unwrap();
+
+        assert_eq!(db.device_keys.len(), 4);
+        assert_eq!(db.processing_keys.len(), 3);
+        assert!(!db.host_certs.is_empty());
+        assert!(db.disc_entries.len() > 170000);
+
+        // Look up any disc entry carrying a full key set.
+        let entry = db
+            .disc_entries
+            .values()
+            .find(|e| e.vuk.is_some() && e.media_key.is_some() && !e.unit_keys.is_empty())
+            .expect("no disc entry with a full key set");
+        assert!(entry.media_key.is_some());
+        assert!(entry.vuk.is_some());
+        assert!(!entry.unit_keys.is_empty());
+
+        eprintln!(
+            "Parsed {} disc entries, {} DK, {} PK",
+            db.disc_entries.len(),
+            db.device_keys.len(),
+            db.processing_keys.len()
+        );
+    }
+}

src/aacs/mod.rs

@@ -0,0 +1,42 @@
+//! AACS decryption — Volume Unique Key lookup and title key derivation.
+//!
+//! Two paths:
+//!   1. VUK lookup: disc_hash → KEYDB.cfg → VUK (fast, 99% of discs)
+//!   2. Full handshake: device_keys + MKB → Media Key → + Volume ID → VUK (fallback)
+//!
+//! KEYDB.cfg format:
+//!   | DK | DEVICE_KEY 0x... | DEVICE_NODE 0x... | KEY_UV 0x... | KEY_U_MASK_SHIFT 0x...
+//!   | PK | 0x...
+//!   | HC | HOST_PRIV_KEY 0x... | HOST_CERT 0x...
+//!   | HC2 | HOST_PRIV_KEY 0x... | HOST_CERT 0x...
+//!   0x<disc_hash> = <title> | D | <date> | M | 0x<media_key> | I | 0x<disc_id> | V | 0x<vuk> | U | <unit_keys>
+//!
+//! The VUK decrypts title keys from AACS/Unit_Key_RO.inf on disc.
+//! Title keys decrypt m2ts stream content (AES-128-CBC).
+
+pub mod decrypt;
+pub mod handshake;
+pub mod keydb;
+pub mod keys;
+pub mod provider;
+pub mod variants;
+
+// Explicit re-exports — only items needed by external consumers and sibling crate modules.
+// AES primitives (aes_ecb_encrypt, aes_ecb_decrypt, aes_cbc_decrypt) are pub(crate) in decrypt.rs.
+pub use decrypt::{
+    ALIGNED_UNIT_LEN, UnitKeyResult, decrypt_bus, decrypt_unit, decrypt_unit_full,
+    decrypt_unit_try_keys, is_aacs_scrambled, ts_packet_total, ts_sync_count, unit_key_validates,
+};
+pub use keydb::{DeviceKey, DiscEntry, HostCert, KeyDb};
+pub use keys::probe;
+pub use keys::{
+    AacsVersion, ContentCert, ResolveContext, ResolvedKeys, UnitKeyFile, decrypt_unit_key,
+    derive_media_key_from_dk, derive_media_key_from_pk, derive_media_key_from_pk_walked,
+    derive_vuk, disc_hash, disc_hash_hex, mkb_content_len, mkb_version, parse_content_cert,
+    parse_unit_key_ro, read_mkb_from_drive, resolve_keys_v1, resolve_keys_v2, resolve_keys_v21,
+};
+pub use provider::KeyProvider;
+pub use variants::{
+    KEY_CORRECTION_DATA_PLACEHOLDER, MediaKeyVariantError, MkbRecord, ProcessingKeyMatch,
+    derive_media_key_variant, is_variant_mkb, variant_nonce, walk_mkb, walk_processing_key,
+};

src/aacs/provider.rs

@@ -0,0 +1,183 @@
+//! Key source abstraction for the AACS resolve chain.
+//!
+//! libfreemkv keeps all crypto (AES-G primitives, SD-tree walking,
+//! validation, MK/VUK/TK derivation) but accepts key material from
+//! arbitrary backends via [`KeyProvider`].
+//!
+//! Methods come in two flavors:
+//!
+//! - **Bulk material** ([`device_keys`], [`processing_keys`],
+//!   [`media_keys`]) — the resolver unions (and dedups) results
+//!   across all providers and tries each candidate.
+//! - **Disc-keyed lookup** ([`lookup_disc_by_hash`],
+//!   [`lookup_disc_by_vid`]) — the resolver short-circuits on the
+//!   first hit, so providers are queried in array order with
+//!   fastest/closest first.
+//!
+//! [`host_certs`] is a sixth method but is NOT consumed by the
+//! resolver chain: the SCSI handshake reads host certs directly from
+//! the caller-supplied credentials, not from the provider array. A
+//! provider that overrides `host_certs` today has no effect on the
+//! handshake; the method is retained as a forward-looking extension
+//! point only.
+//!
+//! Default impls return empty / `None` so backends only override
+//! the methods they actually support — an external key service might
+//! implement only `lookup_disc_by_hash`, while a local file might
+//! implement all six.
+//!
+//! Calls may block (disk I/O, network round-trips). The resolver
+//! invokes each method at most a handful of times per scan; for
+//! per-disc memoization, implementations should cache internally.
+//!
+//! [`device_keys`]: KeyProvider::device_keys
+//! [`processing_keys`]: KeyProvider::processing_keys
+//! [`media_keys`]: KeyProvider::media_keys
+//! [`host_certs`]: KeyProvider::host_certs
+//! [`lookup_disc_by_hash`]: KeyProvider::lookup_disc_by_hash
+//! [`lookup_disc_by_vid`]: KeyProvider::lookup_disc_by_vid
+
+use super::keydb::{DeviceKey, DiscEntry, HostCert};
+
+/// Source of AACS key material.
+///
+/// Implementors return raw material only — the resolver in
+/// `aacs::keys` owns all the crypto (DK→PK walking, PK validation,
+/// MK→VUK→TK derivation). See module docs for method semantics.
+pub trait KeyProvider: Send + Sync {
+    /// Device keys (top-of-tree, walked by the resolver).
+    fn device_keys(&self) -> Vec<DeviceKey> {
+        Vec::new()
+    }
+
+    /// Processing keys — terminal PKs or walk-input PKs. The
+    /// resolver tries each as a terminal first (cheap validate).
+    fn processing_keys(&self) -> Vec<[u8; 16]> {
+        Vec::new()
+    }
+
+    /// Every Media Key this provider holds, regardless of which disc it was
+    /// filed under. An MK is MKB-scoped (shared across a pressing/MKB-family),
+    /// so the resolver can verify each against the disc's MKB (`km_verifies`)
+    /// and resolve a disc whose own hash/VID isn't directly keyed.
+    fn media_keys(&self) -> Vec<[u8; 16]> {
+        Vec::new()
+    }
+
+    /// AACS host certificates (with their private keys) for drive
+    /// authentication. Multiple in case some are revoked.
+    ///
+    /// NOTE: not consumed by the resolver chain — the handshake reads
+    /// host certs from the caller-supplied credentials directly, so
+    /// overriding this method has no effect on drive authentication
+    /// today. Retained as a forward-looking extension point.
+    fn host_certs(&self) -> Vec<HostCert> {
+        Vec::new()
+    }
+
+    /// Direct per-disc lookup by SHA-1 of `Unit_Key_RO.inf`. Returns
+    /// `Some(entry)` if this provider has pre-computed material for
+    /// the disc (paths 4 and 5). Short-circuits the resolver.
+    fn lookup_disc_by_hash(&self, _disc_hash: &[u8; 20]) -> Option<DiscEntry> {
+        None
+    }
+
+    /// Lookup by Volume ID (path 3 — pre-computed MK + matching
+    /// VID). Short-circuits the resolver on hit.
+    fn lookup_disc_by_vid(&self, _volume_id: &[u8; 16]) -> Option<DiscEntry> {
+        None
+    }
+}
+
+/// Resolver-side helpers that aggregate across a provider array.
+///
+/// The resolver wraps `ctx.providers` (`&[&dyn KeyProvider]`) in this
+/// struct; these helpers apply the union-vs-short-circuit policy per
+/// method. The bulk unions dedup so overlapping providers don't make
+/// the resolver re-walk/re-validate identical material.
+pub(crate) struct Providers<'a>(pub &'a [&'a dyn KeyProvider]);
+
+impl Providers<'_> {
+    /// Union (deduped) — gather DKs from every provider.
+    pub fn device_keys(&self) -> Vec<DeviceKey> {
+        let mut v: Vec<DeviceKey> = self.0.iter().flat_map(|p| p.device_keys()).collect();
+        // DeviceKey has no Ord/Hash; dedup on the value-defining tuple.
+        v.sort_unstable_by_key(|d| (d.key, d.node, d.uv, d.u_mask_shift));
+        v.dedup_by_key(|d| (d.key, d.node, d.uv, d.u_mask_shift));
+        v
+    }
+
+    /// Union (deduped) — gather PKs from every provider.
+    pub fn processing_keys(&self) -> Vec<[u8; 16]> {
+        let mut v: Vec<[u8; 16]> = self.0.iter().flat_map(|p| p.processing_keys()).collect();
+        v.sort_unstable();
+        v.dedup();
+        v
+    }
+
+    /// Union of distinct Media Keys across every provider, for the MK-pool
+    /// brute (`km_verifies` against the disc's MKB).
+    pub fn media_keys(&self) -> Vec<[u8; 16]> {
+        let mut v: Vec<[u8; 16]> = self.0.iter().flat_map(|p| p.media_keys()).collect();
+        v.sort_unstable();
+        v.dedup();
+        v
+    }
+
+    /// Union — gather host certs from every provider. The SCSI handshake
+    /// reads host certs from the caller-supplied credentials directly and
+    /// does not call this, so it is currently unused by the resolver chain.
+    #[allow(dead_code)]
+    pub fn host_certs(&self) -> Vec<HostCert> {
+        self.0.iter().flat_map(|p| p.host_certs()).collect()
+    }
+
+    /// Short-circuit — query providers in array order, first hit wins.
+    pub fn lookup_disc_by_hash(&self, disc_hash: &[u8; 20]) -> Option<DiscEntry> {
+        self.0.iter().find_map(|p| p.lookup_disc_by_hash(disc_hash))
+    }
+
+    /// Short-circuit — query providers in array order, first hit wins.
+    pub fn lookup_disc_by_vid(&self, volume_id: &[u8; 16]) -> Option<DiscEntry> {
+        self.0.iter().find_map(|p| p.lookup_disc_by_vid(volume_id))
+    }
+}
+
+/// A [`KeyProvider`] backed by a single caller-supplied key's raw material —
+/// the bridge for [`crate::disc::Disc::decrypt_with`].
+///
+/// The application's key source did the lookup and handed in material at one
+/// level (DK / PK / MK / VUK). This exposes exactly that material to the
+/// version-dispatched resolver, which owns ALL derivation — so a source never
+/// derives, and the lib remains the single home for the AACS chain across
+/// 1.0 / 2.0 / 2.1 / 2.x.
+///
+/// Each level fills only its own field; the rest stay empty, so the resolver
+/// naturally runs the matching path (DK→…, PK→…, MK-pool brute, or a
+/// disc-keyed VUK hit). `decrypt_with` already knows the disc, so the
+/// `lookup_disc_by_*` hash/VID arguments are irrelevant — a present
+/// `disc_entry` is returned for any query.
+pub(crate) struct SuppliedKey {
+    pub device_keys: Vec<DeviceKey>,
+    pub processing_keys: Vec<[u8; 16]>,
+    pub media_keys: Vec<[u8; 16]>,
+    pub disc_entry: Option<DiscEntry>,
+}
+
+impl KeyProvider for SuppliedKey {
+    fn device_keys(&self) -> Vec<DeviceKey> {
+        self.device_keys.clone()
+    }
+    fn processing_keys(&self) -> Vec<[u8; 16]> {
+        self.processing_keys.clone()
+    }
+    fn media_keys(&self) -> Vec<[u8; 16]> {
+        self.media_keys.clone()
+    }
+    fn lookup_disc_by_hash(&self, _disc_hash: &[u8; 20]) -> Option<DiscEntry> {
+        self.disc_entry.clone()
+    }
+    fn lookup_disc_by_vid(&self, _volume_id: &[u8; 16]) -> Option<DiscEntry> {
+        self.disc_entry.clone()
+    }
+}

src/aacs/variants.rs

@@ -0,0 +1,782 @@
+//! AACS Media Key Variant chain.
+//!
+//! On AACS 2.1 the Media Key derivation gains a second stage on top of
+//! the classical subset-difference walk. The classical walk yields a
+//! Media Key Precursor (Kmp) rather than the final Media Key; the
+//! Precursor combines with disc-supplied Variant Key Data (VKD) and an
+//! integrator-supplied Key Correction Data (KCD) constant to produce
+//! the Media Key.
+//!
+//! This module is wiring only — `resolve_keys` is not aware of it. The
+//! entry point is [`derive_media_key_variant`]. The Variant scheme is
+//! detected via the new MKB record types `0x82` (Encrypted Media Key
+//! Variant Data + Variant Key Data) and `0x83` (Variant Number). When
+//! a disc carries neither, callers should fall back to the classical
+//! single-stage derivation in [`super::keys`].
+//!
+//! **Status: the chain cannot yet produce a key on a real disc.** Two
+//! sub-fields are unfinished:
+//!   - [`variants_for_uv`] (the `VARIANTS[uv]` lookup in the `0x83`
+//!     record) is a stub that always returns `None`, so the chain
+//!     short-circuits with [`MediaKeyVariantError::VariantsTableUnavailable`].
+//!   - The Encrypted Media Key Variant Data (C) and the Variant Key
+//!     Data (VKD) table are *distinct* sub-fields of the `0x82` record
+//!     per AACS 2.1, but [`variant_data_record`] (C) and
+//!     [`variant_key_data`] (VKD) both currently return the *whole*
+//!     first `0x82` body — so on a single-`0x82` disc they alias. The
+//!     `0x82` sub-field offsets must be fixed against a real Variant
+//!     disc before this chain is wired into `resolve_keys`.
+//!
+//! The chain follows the published spec:
+//!
+//! ```text
+//! Kmp     = AES-128D(Kp, C) XOR uv
+//! Kpnew   = Kmp XOR KCD
+//! Kvn     = AES-G(Kp, Nonce) & 0xFFFF   (low 16 bits, BE)
+//! VKD_idx = Kvn XOR VARIANTS[uv]
+//! VKD     = vkd_table[VKD_idx * 16 .. +16]
+//! Km      = AES-128D(Kpnew, VKD) XOR uv
+//! ```
+//!
+//! Two condition bits on `Kmp[15]` route off the hardcoded-KCD path
+//! (Soft Correction and Online Challenge). The chain refuses to run in
+//! either case — callers must handle those modes out of band.
+//!
+//! # Status: Kp verification
+//!
+//! On the classical path [`walk_processing_key`] gates each match on
+//! the VERIFY_MAGIC relation, which authenticates the Processing Key.
+//! On a variant MKB that magic check does NOT hold (the walk yields a
+//! Media Key *Precursor*, not the Media Key), so the walk accepts a
+//! variant match without it. The replacement gate lives at the END of
+//! [`derive_media_key_variant`]: the derived final `Km` is verified
+//! against the MKB's Verify-Media-Key record before any `(Km, Kvu)` is
+//! returned. A future implementer wiring [`variants_for_uv`] must keep
+//! that final gate — the per-match magic check no longer protects the
+//! variant path.
+
+use super::decrypt::aes_ecb_decrypt;
+use super::keydb::DeviceKey;
+
+// ── Public constants ──────────────────────────────────────────────────────
+
+/// Placeholder Key Correction Data. Sixteen zero bytes.
+///
+/// Integrators MUST supply a non-placeholder KCD via the `kcd` argument
+/// to [`derive_media_key_variant`]; the chain refuses to operate when
+/// the supplied KCD compares equal to this placeholder.
+pub const KEY_CORRECTION_DATA_PLACEHOLDER: [u8; 16] = [0u8; 16];
+
+// ── MKB record walking ────────────────────────────────────────────────────
+
+/// A single MKB record produced by [`walk_mkb`].
+#[derive(Debug, Clone)]
+pub struct MkbRecord {
+    /// Byte offset of the record within the MKB.
+    pub offset: usize,
+    /// Record type byte.
+    pub rec_type: u8,
+    /// Record length in bytes (includes the 4-byte header).
+    pub rec_len: usize,
+    /// Record body (the bytes after the 4-byte header).
+    pub body: Vec<u8>,
+}
+
+/// Walk an MKB into a flat list of records.
+///
+/// MKB record framing per AACS: 1 byte type, 3 bytes BE length
+/// INCLUDING the 4-byte header, followed by payload. The walker stops
+/// at the first `(type=0, len=0)` end marker or at end of buffer.
+pub fn walk_mkb(mkb: &[u8]) -> Vec<MkbRecord> {
+    let mut out = Vec::new();
+    let mut pos = 0;
+    while pos + 4 <= mkb.len() {
+        let rec_type = mkb[pos];
+        let rec_len = ((mkb[pos + 1] as usize) << 16)
+            | ((mkb[pos + 2] as usize) << 8)
+            | (mkb[pos + 3] as usize);
+        if rec_type == 0 && rec_len == 0 {
+            break;
+        }
+        if rec_len < 4 || pos + rec_len > mkb.len() {
+            break;
+        }
+        let body = mkb[pos + 4..pos + rec_len].to_vec();
+        out.push(MkbRecord {
+            offset: pos,
+            rec_type,
+            rec_len,
+            body,
+        });
+        pos += rec_len;
+    }
+    out
+}
+
+/// True iff `records` contains at least one Media Key Variant record
+/// (type `0x82` or `0x83`).
+pub fn is_variant_mkb(records: &[MkbRecord]) -> bool {
+    records.iter().any(|r| matches!(r.rec_type, 0x82 | 0x83))
+}
+
+/// Body of the Encrypted Media Key Variant Data record (type `0x82`).
+///
+/// Returns the whole first `0x82` body; the internal C / VKD sub-field
+/// split is not yet decoded, so this aliases [`variant_key_data`] on a
+/// single-`0x82` disc. `pub(crate)` until the sub-field offsets are fixed
+/// against a real variant disc — it is not part of the public surface
+/// because it knowingly returns an undecoded composite.
+pub(crate) fn variant_data_record(records: &[MkbRecord]) -> Option<&[u8]> {
+    records
+        .iter()
+        .find(|r| r.rec_type == 0x82)
+        .map(|r| r.body.as_slice())
+}
+
+/// 16-byte Nonce from the Variant Number record (type `0x83`). Returns
+/// the first 16 bytes of the body.
+pub fn variant_nonce(records: &[MkbRecord]) -> Option<[u8; 16]> {
+    let r = records.iter().find(|r| r.rec_type == 0x83)?;
+    if r.body.len() < 16 {
+        return None;
+    }
+    let mut out = [0u8; 16];
+    out.copy_from_slice(&r.body[..16]);
+    Some(out)
+}
+
+/// Body of the Variant Key Data record. Returns the first `0x82` body
+/// that is a non-empty multiple of 16 bytes.
+///
+/// Like [`variant_data_record`], this returns the whole `0x82` body and
+/// aliases it on a single-`0x82` disc; the C / VKD sub-field split is
+/// undecoded. `pub(crate)` until fixed against a real variant disc.
+pub(crate) fn variant_key_data(records: &[MkbRecord]) -> Option<&[u8]> {
+    records
+        .iter()
+        .find(|r| r.rec_type == 0x82 && !r.body.is_empty() && r.body.len() % 16 == 0)
+        .map(|r| r.body.as_slice())
+}
+
+// ── AES-G ────────────────────────────────────────────────────────────────
+
+/// AES-G(x1, x2) = AES-128D(x1, x2) XOR x2.
+///
+/// The Media Key Variant chain uses AES-G to derive both the variant
+/// number (`Kvn = AES-G(Kp, Nonce)`) and the Volume Unique Key
+/// (`Kvu = AES-G(Km, VID)`). See [`super::keys::derive_vuk`] for the
+/// classical VUK form — the math is identical, this exposes it as a
+/// neutral primitive for the variant chain.
+fn aes_g(x1: &[u8; 16], x2: &[u8; 16]) -> [u8; 16] {
+    let mut out = aes_ecb_decrypt(x1, x2);
+    for i in 0..16 {
+        out[i] ^= x2[i];
+    }
+    out
+}
+
+// ── Subset-difference walk that exposes (Kp, uv) ──────────────────────────
+
+/// AES-G3 seed register initial value.
+const AESG3_SEED: [u8; 16] = [
+    0x7B, 0x10, 0x3C, 0x5D, 0xCB, 0x08, 0xC4, 0xE5, 0x1A, 0x27, 0xB0, 0x17, 0x99, 0x05, 0x3B, 0xD9,
+];
+
+/// AES-G3 single step: AES-G against the seed register at offset `inc`.
+fn aesg3_step(key: &[u8; 16], inc: u8) -> [u8; 16] {
+    let mut seed = AESG3_SEED;
+    seed[15] = seed[15].wrapping_add(inc);
+    aes_g(key, &seed)
+}
+
+fn calc_v_mask(uv: u32) -> u32 {
+    let mut v_mask: u32 = 0xFFFF_FFFF;
+    while (uv & !v_mask) == 0 && v_mask != 0 {
+        v_mask <<= 1;
+    }
+    v_mask
+}
+
+fn calc_pk_from_dk(dk: &[u8; 16], uv: u32, v_mask: u32, dev_key_v_mask: u32) -> [u8; 16] {
+    let mut left_child = aesg3_step(dk, 0);
+    let mut pk = aesg3_step(dk, 1);
+    let mut right_child = aesg3_step(dk, 2);
+    let mut current_v_mask = dev_key_v_mask;
+
+    // Bound the walk to the 32-level depth of a u32 subset-difference tree.
+    // `current_v_mask` advances via an arithmetic `>> 1` which sign-extends, so
+    // a disc-supplied v_mask coarser than dev_key_v_mask would otherwise drive
+    // current_v_mask up to 0xFFFF_FFFF and spin forever — a crafted MKB must
+    // not hang the rip thread (this runs before the KCD placeholder gate).
+    let mut steps = 0u32;
+    while current_v_mask != v_mask {
+        if steps >= 32 {
+            break;
+        }
+        steps += 1;
+        let mut bit_pos: i32 = -1;
+        for i in (0..32).rev() {
+            if (current_v_mask & (1u32 << i)) == 0 {
+                bit_pos = i;
+                break;
+            }
+        }
+
+        let curr_key = if bit_pos < 0 || (uv & (1u32 << bit_pos as u32)) == 0 {
+            left_child
+        } else {
+            right_child
+        };
+
+        left_child = aesg3_step(&curr_key, 0);
+        pk = aesg3_step(&curr_key, 1);
+        right_child = aesg3_step(&curr_key, 2);
+
+        current_v_mask = ((current_v_mask as i32) >> 1) as u32;
+    }
+
+    pk
+}
+
+/// Outcome of a subset-difference walk against an MKB. Carries the
+/// processing key and the matching `uv` slot — both needed as inputs
+/// to the variant chain.
+#[derive(Debug, Clone, Copy)]
+pub struct ProcessingKeyMatch {
+    /// Processing Key.
+    pub kp: [u8; 16],
+    /// Subset-difference node number that matched.
+    pub uv: u32,
+    /// 16-byte cvalue that the matched uv selected.
+    pub cvalue: [u8; 16],
+    /// Index of the matching cvalue within the cvalues record.
+    pub cvalue_index: usize,
+}
+
+fn mkb_find_body(records: &[MkbRecord], rec_type: u8) -> Option<&[u8]> {
+    records
+        .iter()
+        .find(|r| r.rec_type == rec_type && !r.body.is_empty())
+        .map(|r| r.body.as_slice())
+}
+
+fn mkb_find_mk_dv(records: &[MkbRecord]) -> Option<[u8; 16]> {
+    let r = records
+        .iter()
+        .find(|r| (r.rec_type == 0x81 || r.rec_type == 0x86) && r.body.len() >= 16)?;
+    let mut out = [0u8; 16];
+    out.copy_from_slice(&r.body[..16]);
+    Some(out)
+}
+
+/// Walk an MKB and return the first `(Kp, uv, cvalue)` that
+/// `device_keys` covers. Returns `None` if no DK walks any uv.
+pub fn walk_processing_key(
+    records: &[MkbRecord],
+    device_keys: &[DeviceKey],
+) -> Option<ProcessingKeyMatch> {
+    let mk_dv = mkb_find_mk_dv(records)?;
+    let uvs = mkb_find_body(records, 0x04)?;
+    let cvalues = mkb_find_body(records, 0x07).or_else(|| mkb_find_body(records, 0x05))?;
+
+    let num_uvs = uvs
+        .chunks(5)
+        .take_while(|c| c.len() == 5 && (c[0] & 0xC0) == 0)
+        .count();
+
+    for dk in device_keys {
+        let device_number = dk.node as u32;
+
+        for uvs_idx in 0..num_uvs {
+            let p_uv = &uvs[1 + 5 * uvs_idx..];
+            // `num_uvs` was computed by `take_while(.. (c[0] & 0xC0) == 0)`, so
+            // every chunk in `0..num_uvs` already has its revoked-marker bits
+            // clear — that `take_while` is the single authoritative place the
+            // parse stops, no inner re-check needed.
+            let u_mask_shift = uvs[5 * uvs_idx];
+
+            if u_mask_shift & 0xC0 != 0 {
+                break;
+            }
+            // 0x20..=0x3F (32..=63) pass the 0xC0 revoked-marker check but are
+            // out of range for a u32 shift. `wrapping_shl` would silently
+            // compute shift % 32 (e.g. 32 → no shift → 0xFFFF_FFFF), matching a
+            // wrong uv slot and deriving a wrong key. Disc-controlled byte:
+            // skip the slot instead.
+            if u_mask_shift >= 32 {
+                continue;
+            }
+
+            let uv = u32::from_be_bytes([p_uv[0], p_uv[1], p_uv[2], p_uv[3]]);
+            if uv == 0 {
+                continue;
+            }
+
+            let u_mask: u32 = 0xFFFF_FFFFu32.wrapping_shl(u_mask_shift as u32);
+            let v_mask = calc_v_mask(uv);
+
+            if ((device_number & u_mask) == (uv & u_mask))
+                && ((device_number & v_mask) != (uv & v_mask))
+            {
+                // dk.u_mask_shift is a u8 from keydb with no range check; guard
+                // it the same way before the wrapping_shl below.
+                if dk.u_mask_shift >= 32 {
+                    continue;
+                }
+                let dev_key_v_mask = calc_v_mask(dk.uv);
+                let dev_key_u_mask: u32 = 0xFFFF_FFFFu32.wrapping_shl(dk.u_mask_shift as u32);
+
+                if u_mask == dev_key_u_mask && (uv & dev_key_v_mask) == (dk.uv & dev_key_v_mask) {
+                    let pk = calc_pk_from_dk(&dk.key, uv, v_mask, dev_key_v_mask);
+
+                    if uvs_idx >= cvalues.len() / 16 {
+                        continue;
+                    }
+                    let mut cv = [0u8; 16];
+                    cv.copy_from_slice(&cvalues[uvs_idx * 16..(uvs_idx + 1) * 16]);
+
+                    // Validate: AES-D(Kp, cv), XOR uv into low 4 bytes,
+                    // then AES-D(.., mk_dv) must reveal the verify magic.
+                    let mut km_candidate = aes_ecb_decrypt(&pk, &cv);
+                    let uv_bytes = uv.to_be_bytes();
+                    for i in 0..4 {
+                        km_candidate[12 + i] ^= uv_bytes[i];
+                    }
+                    let dec_vd = aes_ecb_decrypt(&km_candidate, &mk_dv);
+                    const VERIFY_MAGIC: [u8; 8] = [0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF];
+                    // On a classical (non-variant) MKB this magic must
+                    // match. On a variant MKB it won't — `km_candidate`
+                    // is really Kmp and the magic check is moot. We
+                    // still gate the walk on cvalue indexing being
+                    // sane; the chain itself enforces the variant
+                    // semantics downstream.
+                    let classical_ok = dec_vd[..8] == VERIFY_MAGIC;
+                    let variant_present = is_variant_mkb(records);
+                    if !(classical_ok || variant_present) {
+                        continue;
+                    }
+
+                    return Some(ProcessingKeyMatch {
+                        kp: pk,
+                        uv,
+                        cvalue: cv,
+                        cvalue_index: uvs_idx,
+                    });
+                }
+            }
+        }
+    }
+    None
+}
+
+// ── Error reporting ───────────────────────────────────────────────────────
+
+/// Outcome of [`derive_media_key_variant`] when the chain cannot
+/// produce a Media Key. Every variant is a classification only — no
+/// strings, no Display impl beyond the error code.
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+pub enum MediaKeyVariantError {
+    /// MKB carries no Variant records. Caller should fall back to the
+    /// classical single-stage derivation.
+    NotVariantMkb,
+    /// MKB is missing a required record (mk_dv, subset-difference,
+    /// cvalues, variant data, or variant nonce).
+    MkbIncomplete,
+    /// `device_keys` did not cover any uv slot in this MKB.
+    ProcessingKeyUnavailable,
+    /// `Kmp[15]` carries bit `0x02`: the soft-correction path applies
+    /// for this Precursor. Out of scope for the hardcoded-KCD chain.
+    SoftCorrectionRequired,
+    /// `Kmp[15]` carries bit `0x04`: the online-challenge path applies
+    /// for this Precursor. Out of scope for the hardcoded-KCD chain.
+    OnlineChallengeRequired,
+    /// Supplied KCD equals [`KEY_CORRECTION_DATA_PLACEHOLDER`]. The
+    /// derivation refuses to run with the all-zero placeholder.
+    KcdNotProvided,
+    /// `VARIANTS[uv]` lookup for the matched uv is not implemented.
+    VariantsTableUnavailable,
+    /// VKD index resolved out of the supplied `vkd_table`.
+    VkdIndexOutOfRange,
+    /// The derived Media Key failed the MKB's Verify-Media-Key relation.
+    /// On the variant path this final gate replaces the per-match magic
+    /// check (which does not hold for a Precursor).
+    MediaKeyVerifyFailed,
+}
+
+impl std::fmt::Display for MediaKeyVariantError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let code: u16 = match self {
+            MediaKeyVariantError::NotVariantMkb => 7100,
+            MediaKeyVariantError::MkbIncomplete => 7101,
+            MediaKeyVariantError::ProcessingKeyUnavailable => 7102,
+            MediaKeyVariantError::SoftCorrectionRequired => 7103,
+            MediaKeyVariantError::OnlineChallengeRequired => 7104,
+            MediaKeyVariantError::KcdNotProvided => 7105,
+            MediaKeyVariantError::VariantsTableUnavailable => 7106,
+            MediaKeyVariantError::VkdIndexOutOfRange => 7107,
+            MediaKeyVariantError::MediaKeyVerifyFailed => 7108,
+        };
+        write!(f, "E{code}")
+    }
+}
+
+impl std::error::Error for MediaKeyVariantError {}
+
+// ── Chain ─────────────────────────────────────────────────────────────────
+
+/// Look up the per-slot `VARIANTS` value for the matched subset-difference
+/// slot. AACS 2.1 keys the VARIANTS table by the matched SD slot (the same
+/// index that selected the cvalue), so the caller passes
+/// [`ProcessingKeyMatch::cvalue_index`]. The byte layout of the per-slot entry
+/// in the Variant Number record is undocumented and disc-specific; this helper
+/// returns `None` until a Variant disc is available to fix the layout against.
+///
+/// `sd_slot_index` is the matched subset-difference slot (== cvalue index).
+fn variants_for_uv(_records: &[MkbRecord], _sd_slot_index: usize) -> Option<u16> {
+    None
+}
+
+/// Run the Media Key Variant chain on an MKB.
+///
+/// Inputs:
+///
+/// - `mkb_records`  : MKB pre-walked via [`walk_mkb`].
+/// - `device_keys`  : pool of device keys; the chain runs against the
+///   first uv slot any DK covers.
+/// - `kcd`          : integrator-supplied Key Correction Data. Must not
+///   equal [`KEY_CORRECTION_DATA_PLACEHOLDER`].
+/// - `vid`          : 16-byte Volume ID for the disc. Used to derive
+///   the final VUK alongside the Media Key.
+///
+/// Returns `(Km, Kvu)` on success.
+///
+/// NOTE: the `VARIANTS[uv]` lookup ([`variants_for_uv`]) is not yet
+/// implemented, so on a real Variant disc this always returns
+/// `Err(`[`MediaKeyVariantError::VariantsTableUnavailable`]`)` before a
+/// key is produced. The chain can only succeed against synthetic test
+/// fixtures today.
+pub fn derive_media_key_variant(
+    mkb_records: &[MkbRecord],
+    device_keys: &[DeviceKey],
+    kcd: &[u8; 16],
+    vid: &[u8; 16],
+) -> Result<([u8; 16], [u8; 16]), MediaKeyVariantError> {
+    if !is_variant_mkb(mkb_records) {
+        return Err(MediaKeyVariantError::NotVariantMkb);
+    }
+
+    let pkm = walk_processing_key(mkb_records, device_keys)
+        .ok_or(MediaKeyVariantError::ProcessingKeyUnavailable)?;
+
+    let nonce = variant_nonce(mkb_records).ok_or(MediaKeyVariantError::MkbIncomplete)?;
+    let vkd_table = variant_key_data(mkb_records).ok_or(MediaKeyVariantError::MkbIncomplete)?;
+    let c_value = variant_data_record(mkb_records).ok_or(MediaKeyVariantError::MkbIncomplete)?;
+    if c_value.len() < 16 {
+        return Err(MediaKeyVariantError::MkbIncomplete);
+    }
+    let mut c_block = [0u8; 16];
+    c_block.copy_from_slice(&c_value[..16]);
+
+    // Step: Kmp = AES-128D(Kp, C) XOR uv  (uv into low 4 bytes).
+    let mut kmp = aes_ecb_decrypt(&pkm.kp, &c_block);
+    let uv_bytes = pkm.uv.to_be_bytes();
+    for i in 0..4 {
+        kmp[12 + i] ^= uv_bytes[i];
+    }
+
+    // Condition bits on Kmp[15] route off the hardcoded-KCD path.
+    if kmp[15] & 0b0000_0010 != 0 {
+        return Err(MediaKeyVariantError::SoftCorrectionRequired);
+    }
+    if kmp[15] & 0b0000_0100 != 0 {
+        return Err(MediaKeyVariantError::OnlineChallengeRequired);
+    }
+    if kcd == &KEY_CORRECTION_DATA_PLACEHOLDER {
+        return Err(MediaKeyVariantError::KcdNotProvided);
+    }
+
+    // Step: Kpnew = Kmp XOR KCD.
+    let mut kpnew = [0u8; 16];
+    for i in 0..16 {
+        kpnew[i] = kmp[i] ^ kcd[i];
+    }
+
+    // Step: Kvn = AES-G(Kp, Nonce) & 0xFFFF  (low 16 bits, BE).
+    let kvn_block = aes_g(&pkm.kp, &nonce);
+    let kvn = u16::from_be_bytes([kvn_block[14], kvn_block[15]]);
+
+    // Step: VKD_idx = Kvn XOR VARIANTS[uv].
+    let v_for_uv = variants_for_uv(mkb_records, pkm.cvalue_index)
+        .ok_or(MediaKeyVariantError::VariantsTableUnavailable)?;
+    let vkd_idx = kvn ^ v_for_uv;
+
+    // Step: VKD = vkd_table[VKD_idx * 16 .. +16].
+    let off = (vkd_idx as usize) * 16;
+    if off + 16 > vkd_table.len() {
+        return Err(MediaKeyVariantError::VkdIndexOutOfRange);
+    }
+    let mut vkd = [0u8; 16];
+    vkd.copy_from_slice(&vkd_table[off..off + 16]);
+
+    // Step: Km = AES-128D(Kpnew, VKD) XOR uv.
+    let mut km = aes_ecb_decrypt(&kpnew, &vkd);
+    for i in 0..4 {
+        km[12 + i] ^= uv_bytes[i];
+    }
+
+    // Gate: verify the derived Media Key against the MKB's Verify-Media-Key
+    // record. On the variant path the per-match magic check in
+    // `walk_processing_key` does NOT hold (it only saw the Precursor), so this
+    // is the authoritative Kp/Km verification — it MUST run before returning a
+    // real key.
+    let mk_dv = mkb_find_mk_dv(mkb_records).ok_or(MediaKeyVariantError::MkbIncomplete)?;
+    const VERIFY_MAGIC: [u8; 8] = [0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF];
+    if aes_ecb_decrypt(&km, &mk_dv)[..8] != VERIFY_MAGIC {
+        return Err(MediaKeyVariantError::MediaKeyVerifyFailed);
+    }
+
+    // Step: Kvu = AES-G(Km, VID).
+    let kvu = aes_g(&km, vid);
+
+    Ok((km, kvu))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn calc_pk_from_dk_terminates_on_nonconvergent_mask() {
+        // Regression for the unbounded-loop hang: pick a (dev_key_v_mask,
+        // v_mask) pair the arithmetic `>> 1` walk can never reconcile.
+        // dev_key_v_mask has the MSB set, so `>> 1` sign-extends and the
+        // mask saturates at 0xFFFF_FFFF, never reaching a coarser v_mask.
+        // The 32-step bound must let this return rather than spin forever.
+        let dk = [0x11u8; 16];
+        let pk = calc_pk_from_dk(&dk, 0x0000_0002, 0x0000_0000, 0xFFFF_FFFE);
+        // Bounded exit yields *some* key; we only assert it terminated.
+        let _ = pk;
+    }
+
+    // ── Helpers ──
+
+    fn synthetic_mkb_classical() -> Vec<u8> {
+        // Minimal MKB: type/version record + cvalues + mk_dv. No variant
+        // records.
+        let mut mkb = vec![
+            0x10, 0x00, 0x00, 0x0C, 0x48, 0x14, 0x10, 0x03, 0x00, 0x00, 0x00, 0x4D,
+        ];
+        mkb.extend_from_slice(&[0x07, 0x00, 0x00, 0x14]);
+        mkb.extend_from_slice(&[0xAB; 16]);
+        mkb.extend_from_slice(&[0x86, 0x00, 0x00, 0x14]);
+        mkb.extend_from_slice(&[0xCD; 16]);
+        mkb
+    }
+
+    fn synthetic_mkb_with_variant() -> Vec<u8> {
+        let mut mkb = synthetic_mkb_classical();
+        // 0x82 — 16-byte body (Variant data / VKD slot).
+        mkb.extend_from_slice(&[0x82, 0x00, 0x00, 0x14]);
+        mkb.extend_from_slice(&[0xEE; 16]);
+        // 0x83 — 16-byte body (Variant Nonce).
+        mkb.extend_from_slice(&[0x83, 0x00, 0x00, 0x14]);
+        mkb.extend_from_slice(&[0x55; 16]);
+        mkb
+    }
+
+    // ── Walker / record detection ──
+
+    #[test]
+    fn walker_parses_synthetic_mkb() {
+        let mkb = synthetic_mkb_classical();
+        let recs = walk_mkb(&mkb);
+        assert_eq!(recs.len(), 3);
+        assert_eq!(recs[0].rec_type, 0x10);
+        assert_eq!(recs[1].rec_type, 0x07);
+        assert_eq!(recs[2].rec_type, 0x86);
+    }
+
+    #[test]
+    fn variant_detection_negative_on_classical() {
+        let recs = walk_mkb(&synthetic_mkb_classical());
+        assert!(!is_variant_mkb(&recs));
+        assert!(variant_nonce(&recs).is_none());
+        assert!(variant_key_data(&recs).is_none());
+        assert!(variant_data_record(&recs).is_none());
+    }
+
+    #[test]
+    fn variant_detection_positive_on_variant() {
+        let recs = walk_mkb(&synthetic_mkb_with_variant());
+        assert!(is_variant_mkb(&recs));
+        assert_eq!(variant_nonce(&recs), Some([0x55; 16]));
+        assert_eq!(variant_key_data(&recs), Some(&[0xEE; 16][..]));
+        assert_eq!(variant_data_record(&recs), Some(&[0xEE; 16][..]));
+    }
+
+    // ── Chain entry-point classification ──
+
+    #[test]
+    fn chain_rejects_non_variant_mkb() {
+        let recs = walk_mkb(&synthetic_mkb_classical());
+        let err = derive_media_key_variant(&recs, &[], &[0xAA; 16], &[0u8; 16])
+            .expect_err("classical MKB must be rejected");
+        assert_eq!(err, MediaKeyVariantError::NotVariantMkb);
+    }
+
+    #[test]
+    fn chain_rejects_placeholder_kcd() {
+        // To reach the KCD check we need a complete variant MKB AND a
+        // DK that walks it. We construct both via the synthetic
+        // fixture below.
+        let (recs, dk, _kp, _expected_kmp) = synthetic_variant_setup(/*kmp15*/ 0x00);
+        let err =
+            derive_media_key_variant(&recs, &[dk], &KEY_CORRECTION_DATA_PLACEHOLDER, &[0u8; 16])
+                .expect_err("placeholder KCD must be rejected");
+        assert_eq!(err, MediaKeyVariantError::KcdNotProvided);
+    }
+
+    #[test]
+    fn chain_detects_soft_correction_bit() {
+        let (recs, dk, _, _) = synthetic_variant_setup(/*kmp15*/ 0x02);
+        let err = derive_media_key_variant(&recs, &[dk], &[0xAA; 16], &[0u8; 16])
+            .expect_err("bit 0x02 must surface SoftCorrectionRequired");
+        assert_eq!(err, MediaKeyVariantError::SoftCorrectionRequired);
+    }
+
+    #[test]
+    fn chain_detects_online_challenge_bit() {
+        let (recs, dk, _, _) = synthetic_variant_setup(/*kmp15*/ 0x04);
+        let err = derive_media_key_variant(&recs, &[dk], &[0xAA; 16], &[0u8; 16])
+            .expect_err("bit 0x04 must surface OnlineChallengeRequired");
+        assert_eq!(err, MediaKeyVariantError::OnlineChallengeRequired);
+    }
+
+    #[test]
+    fn chain_surfaces_variants_table_gap_on_clean_kmp() {
+        // With both condition bits clear and a non-placeholder KCD, the
+        // chain advances to the per-uv VARIANTS[uv] lookup, which is
+        // not yet wired. That returns VariantsTableUnavailable —
+        // proving the bit checks and KCD check all passed.
+        let (recs, dk, _, _) = synthetic_variant_setup(/*kmp15*/ 0x00);
+        let err = derive_media_key_variant(&recs, &[dk], &[0xAA; 16], &[0u8; 16])
+            .expect_err("expected VariantsTableUnavailable at the per-uv lookup");
+        assert_eq!(err, MediaKeyVariantError::VariantsTableUnavailable);
+    }
+
+    #[test]
+    fn error_display_is_code_only() {
+        // No English in Display — every variant emits "E7xxx" and
+        // nothing else.
+        let cases = [
+            MediaKeyVariantError::NotVariantMkb,
+            MediaKeyVariantError::MkbIncomplete,
+            MediaKeyVariantError::ProcessingKeyUnavailable,
+            MediaKeyVariantError::SoftCorrectionRequired,
+            MediaKeyVariantError::OnlineChallengeRequired,
+            MediaKeyVariantError::KcdNotProvided,
+            MediaKeyVariantError::VariantsTableUnavailable,
+            MediaKeyVariantError::VkdIndexOutOfRange,
+            MediaKeyVariantError::MediaKeyVerifyFailed,
+        ];
+        for e in cases {
+            let s = e.to_string();
+            assert!(
+                s.starts_with('E') && s.len() == 5,
+                "error display must be E#### only, got {s:?}"
+            );
+            assert!(
+                s.chars().skip(1).all(|c| c.is_ascii_digit()),
+                "error display must be E + digits, got {s:?}"
+            );
+        }
+    }
+
+    // ── Fixture construction ──
+
+    /// Build a synthetic variant MKB plus a DK that walks the single
+    /// subset-difference slot it carries. `kmp15` is the value of the
+    /// low byte of `Kmp[15]` that the chain will land on — pick `0x02`
+    /// to exercise the SoftCorrection bit, `0x04` to exercise
+    /// OnlineChallenge, `0x00` otherwise.
+    ///
+    /// The fixture pins:
+    /// - MKB subset-difference: `u_mask_shift=3, uv=2`. With these
+    ///   masks the discriminator bit (u_mask=1, v_mask=0) is bit 2.
+    /// - one DK at `node=4, uv=2, u_mask_shift=3`. node 4 has bit 2 set
+    ///   (differs from uv=2 on bit 2 → disagrees on v_mask) while
+    ///   agreeing with uv on bits 3+ (the u_mask=1 region). dk.uv ==
+    ///   MKB.uv and dk.u_mask_shift == MKB.u_mask_shift make
+    ///   `dev_key_v_mask == v_mask`, so `calc_pk_from_dk` loops zero
+    ///   times — Kp = aesg3_step(dk, 1).
+    /// - one cvalue in record 0x07 chosen so AES-D(Kp, C) ⊕ uv produces a
+    ///   Kmp whose byte-15 is exactly `kmp15`.
+    /// - record 0x82 with a 16-byte body (acts as both Variant Data
+    ///   and Variant Key Data; satisfies the parser heuristics).
+    /// - record 0x83 with a 16-byte Nonce.
+    ///
+    /// Returns (records, dk, planted_kp, planted_kmp).
+    fn synthetic_variant_setup(kmp15: u8) -> (Vec<MkbRecord>, DeviceKey, [u8; 16], [u8; 16]) {
+        use crate::aacs::decrypt::aes_ecb_encrypt;
+
+        // Build header.
+        let mut mkb = vec![
+            0x10, 0x00, 0x00, 0x0C, 0x48, 0x14, 0x10, 0x03, 0x00, 0x00, 0x00, 0x4D,
+        ];
+
+        // Subset-difference (0x04): u_mask_shift=3, uv=00 00 00 02.
+        mkb.extend_from_slice(&[0x04, 0x00, 0x00, 0x09]);
+        mkb.extend_from_slice(&[0x03, 0x00, 0x00, 0x00, 0x02]);
+
+        // Pick a known DK; with dk.uv == MKB.uv (==2) and
+        // dk.u_mask_shift == MKB.u_mask_shift (==3), dev_key_v_mask
+        // equals the MKB's v_mask and the calc_pk_from_dk loop is a
+        // no-op — Kp = aesg3_step(dk, 1).
+        let dk_bytes: [u8; 16] = [
+            0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE,
+            0xFF, 0x00,
+        ];
+        let kp = aesg3_step(&dk_bytes, 1);
+
+        // Plant Kmp with chosen byte-15, then compute C such that
+        // AES-D(Kp, C) ⊕ uv == Kmp. uv=2 → low-4 bytes XOR is 00 00 00 02.
+        let mut kmp = [0x42u8; 16];
+        kmp[15] = kmp15;
+        let mut aes_d_result = kmp;
+        aes_d_result[15] ^= 0x02;
+        let c_block = aes_ecb_encrypt(&kp, &aes_d_result);
+
+        // cvalues record (0x07): one 16-byte cvalue. The walker
+        // indexes it for the magic-check step; on a variant MKB the
+        // magic check fails but `variant_present` is true so the
+        // walker still returns the match. Content is don't-care.
+        mkb.extend_from_slice(&[0x07, 0x00, 0x00, 0x14]);
+        mkb.extend_from_slice(&[0xAB; 16]);
+
+        // Verify Media Key (0x86): body content is don't-care.
+        mkb.extend_from_slice(&[0x86, 0x00, 0x00, 0x14]);
+        mkb.extend_from_slice(&[0xCD; 16]);
+
+        // 0x82 record: holds C (Encrypted Media Key Variant Data) AND
+        // doubles as the VKD table (single 16-byte entry → VKDidx must
+        // resolve to 0 for `chain_surfaces_variants_table_gap` test —
+        // but the test never reaches the VKD lookup since the
+        // VARIANTS[uv] helper is not yet wired).
+        mkb.extend_from_slice(&[0x82, 0x00, 0x00, 0x14]);
+        mkb.extend_from_slice(&c_block);
+
+        // 0x83 record: 16-byte Nonce.
+        mkb.extend_from_slice(&[0x83, 0x00, 0x00, 0x14]);
+        mkb.extend_from_slice(&[0x77; 16]);
+
+        let recs = walk_mkb(&mkb);
+
+        let dk = DeviceKey {
+            key: dk_bytes,
+            node: 4,
+            uv: 2,
+            u_mask_shift: 3,
+        };
+        (recs, dk, kp, kmp)
+    }
+}

src/bin/freemkv_info.rs

@@ -1,159 +0,0 @@
-//! freemkv-info — Drive identification and compatibility checker.
-//!
-//! Sends standard SCSI INQUIRY and GET CONFIGURATION commands to an optical drive,
-//! displays drive identity and compatibility status, and optionally outputs raw
-//! response data for profile contribution.
-//!
-//! Usage:
-//!   freemkv-info /dev/sr0
-//!   freemkv-info /dev/sr0 --raw
-//!   freemkv-info /dev/sr0 --json
-
-use std::env;
-use std::path::Path;
-use std::process;
-
-fn main() {
-    let args: Vec<String> = env::args().collect();
-
-    if args.len() < 2 {
-        eprintln!("freemkv-info — Drive identification and compatibility checker");
-        eprintln!();
-        eprintln!("Usage: freemkv-info <device> [options]");
-        eprintln!();
-        eprintln!("  <device>    Optical drive device (e.g. /dev/sr0)");
-        eprintln!("  --raw       Output raw SCSI response hex (for profile contribution)");
-        eprintln!("  --json      Output machine-readable JSON");
-        eprintln!("  --profiles  Path to profiles directory (default: ./profiles)");
-        eprintln!();
-        eprintln!("Examples:");
-        eprintln!("  freemkv-info /dev/sr0");
-        eprintln!("  freemkv-info /dev/sr0 --raw > my_drive.txt");
-        process::exit(1);
-    }
-
-    let device = Path::new(&args[1]);
-    let raw_mode = args.iter().any(|a| a == "--raw");
-    let json_mode = args.iter().any(|a| a == "--json");
-    let profiles_dir = args.iter()
-        .position(|a| a == "--profiles")
-        .and_then(|i| args.get(i + 1))
-        .map(|s| s.as_str())
-        .unwrap_or("profiles");
-
-    // Open SCSI transport
-    let mut transport = match libfreemkv::scsi::open(device) {
-        Ok(t) => t,
-        Err(e) => {
-            eprintln!("Error: Cannot open {}: {}", device.display(), e);
-            process::exit(1);
-        }
-    };
-
-    // INQUIRY
-    let inquiry = match libfreemkv::scsi::inquiry(transport.as_mut()) {
-        Ok(i) => i,
-        Err(e) => {
-            eprintln!("Error: INQUIRY failed: {}", e);
-            process::exit(1);
-        }
-    };
-
-    // GET CONFIGURATION feature 0x010C
-    let gc_010c = libfreemkv::scsi::get_config_010c(transport.as_mut()).ok();
-
-    if json_mode {
-        print_json(&inquiry, &gc_010c);
-    } else if raw_mode {
-        print_raw(&inquiry, &gc_010c);
-    } else {
-        print_human(&inquiry, &gc_010c, profiles_dir);
-    }
-}
-
-fn print_human(
-    inquiry: &libfreemkv::scsi::InquiryResult,
-    gc_010c: &Option<Vec<u8>>,
-    profiles_dir: &str,
-) {
-    println!("freemkv-info v{}", env!("CARGO_PKG_VERSION"));
-    println!();
-    println!("Drive:    {} {} {}", inquiry.vendor_id, inquiry.model, inquiry.firmware);
-    println!("INQUIRY:  additional_length=0x{:02X} ({})",
-        inquiry.raw.get(4).unwrap_or(&0),
-        inquiry.raw.get(4).unwrap_or(&0));
-
-    if let Some(gc) = gc_010c {
-        let data_hex: String = gc.iter().map(|b| format!("{:02x}", b)).collect();
-        println!("Feature 0x010C: {}", data_hex);
-    } else {
-        println!("Feature 0x010C: not available");
-    }
-
-    // Try to match profile
-    if let Ok(profiles) = libfreemkv::profile::load_all(Path::new(profiles_dir)) {
-        let matched = profiles.iter().find(|p| {
-            p.drive_id.contains(&inquiry.vendor_id)
-                && p.drive_id.contains(&inquiry.model)
-        });
-
-        println!();
-        match matched {
-            Some(p) => {
-                println!("Profile:  FOUND ({})", p.chipset.name());
-                println!("Raw Read: Supported");
-            }
-            None => {
-                println!("Profile:  NOT FOUND");
-                println!("Raw Read: Unknown — run with --raw and submit a profile request");
-            }
-        }
-    } else {
-        println!();
-        println!("Profile:  No profiles directory found at '{}'", profiles_dir);
-    }
-}
-
-fn print_raw(
-    inquiry: &libfreemkv::scsi::InquiryResult,
-    gc_010c: &Option<Vec<u8>>,
-) {
-    println!("# freemkv-info raw output");
-    println!("# Submit this file to https://github.com/freemkv/libfreemkv/issues");
-    println!();
-    println!("vendor: {}", inquiry.vendor_id);
-    println!("model: {}", inquiry.model);
-    println!("firmware: {}", inquiry.firmware);
-    println!();
-
-    // Full INQUIRY hex
-    println!("inquiry_hex: {}", hex_encode(&inquiry.raw));
-    println!("inquiry_length: {}", inquiry.raw.len());
-
-    // GET CONFIG 0x010C
-    if let Some(gc) = gc_010c {
-        println!("get_config_010c_hex: {}", hex_encode(gc));
-        println!("get_config_010c_length: {}", gc.len());
-    } else {
-        println!("get_config_010c_hex: ERROR");
-    }
-}
-
-fn print_json(
-    inquiry: &libfreemkv::scsi::InquiryResult,
-    gc_010c: &Option<Vec<u8>>,
-) {
-    let json = serde_json::json!({
-        "vendor": inquiry.vendor_id,
-        "model": inquiry.model,
-        "firmware": inquiry.firmware,
-        "inquiry_hex": hex_encode(&inquiry.raw),
-        "inquiry_length": inquiry.raw.len(),
-        "get_config_010c_hex": gc_010c.as_ref().map(|g| hex_encode(g)),
-    });
-    println!("{}", serde_json::to_string_pretty(&json).unwrap());
-}
-
-fn hex_encode(data: &[u8]) -> String {
-    data.iter().map(|b| format!("{:02x}", b)).collect()
-}

src/bin/freemkv_test.rs

@@ -1,99 +0,0 @@
-//! freemkv-test — Quick verification that raw disc access works.
-//!
-//! Enables raw read mode, calibrates speed, reads a few test sectors.
-//! Use this to verify your drive and profile are working correctly.
-//!
-//! Usage:
-//!   freemkv-test /dev/sr0
-//!   freemkv-test /dev/sr0 --profiles ./profiles
-
-use std::env;
-use std::path::Path;
-use std::process;
-
-fn main() {
-    let args: Vec<String> = env::args().collect();
-
-    if args.len() < 2 {
-        eprintln!("freemkv-test — Verify raw disc access works");
-        eprintln!();
-        eprintln!("Usage: freemkv-test <device> [--profiles <dir>]");
-        process::exit(1);
-    }
-
-    let device = Path::new(&args[1]);
-
-    println!("freemkv-test v{}", env!("CARGO_PKG_VERSION"));
-    println!();
-
-    // Open drive session (uses bundled profiles)
-    print!("Opening {}... ", device.display());
-    let mut session = match libfreemkv::DriveSession::open(device) {
-        Ok(s) => { println!("OK"); s }
-        Err(e) => { println!("FAILED: {}", e); process::exit(1); }
-    };
-
-    println!("  Drive ID: {}", session.profile.drive_id);
-    println!("  Chipset:  {}", session.profile.chipset.name());
-    println!();
-
-    // Enable raw read mode
-    print!("Unlocking drive... ");
-    match session.unlock() {
-        Ok(()) => println!("OK"),
-        Err(e) => { println!("FAILED: {}", e); process::exit(1); }
-    }
-
-    // Check status
-    print!("Checking status... ");
-    match session.status() {
-        Ok(status) => {
-            if status.unlocked {
-                println!("OK (active)");
-            } else {
-                println!("WARNING: drive reported as locked");
-            }
-        }
-        Err(e) => println!("SKIP ({})", e),
-    }
-
-    // Calibrate speed
-    print!("Calibrating speed... ");
-    match session.calibrate() {
-        Ok(()) => println!("OK"),
-        Err(e) => println!("SKIP ({})", e),
-    }
-
-    // Read test sectors
-    let test_lbas: &[u32] = &[0, 100, 1000, 10000];
-    let mut buf = vec![0u8; 2048];
-    let mut pass = 0;
-    let mut fail = 0;
-
-    for &lba in test_lbas {
-        print!("Reading sector {}... ", lba);
-        match session.read_sectors(lba, 1, &mut buf) {
-            Ok(n) if n == 2048 => {
-                let nonzero = buf.iter().filter(|&&b| b != 0).count();
-                println!("OK ({} bytes, {} non-zero)", n, nonzero);
-                pass += 1;
-            }
-            Ok(n) => {
-                println!("PARTIAL ({} bytes)", n);
-                fail += 1;
-            }
-            Err(e) => {
-                println!("FAILED: {}", e);
-                fail += 1;
-            }
-        }
-    }
-
-    println!();
-    if fail == 0 {
-        println!("All {} checks passed. Drive is fully functional.", pass);
-    } else {
-        println!("{} passed, {} failed.", pass, fail);
-        process::exit(1);
-    }
-}

src/clpi.rs

@@ -0,0 +1,818 @@
+//! CLPI clip info parser — maps clips to sector ranges on disc.
+//!
+//! Each .clpi file in BDMV/CLIPINF/ describes one M2TS clip.
+//! The EP (Entry Point) map provides timestamp → SPN mapping.
+//! SPN × 192 = byte offset in the m2ts file.
+//!
+//! Reference: https://github.com/lw/BluRay/wiki/CLPI
+
+use crate::disc::Extent;
+use crate::error::{Error, Result};
+
+/// Parsed CLPI clip info.
+#[derive(Debug)]
+pub(crate) struct ClipInfo {
+    /// CLPI version string. Parsed for completeness; not yet consumed.
+    #[allow(dead_code)]
+    pub version: String,
+    /// Total source packets in the m2ts (each 192 bytes)
+    pub source_packet_count: u32,
+    /// Coarse EP entries for the primary video stream. Populated for the
+    /// EP-map → sector-extent lookup (`get_extents`), which is exercised by
+    /// tests and reserved for the timestamp-range read path.
+    #[allow(dead_code)]
+    pub ep_coarse: Vec<EpCoarse>,
+    /// Fine EP entries for the primary video stream (see `ep_coarse`).
+    #[allow(dead_code)]
+    pub ep_fine: Vec<EpFine>,
+    /// Per-stream metadata from the ProgramInfo section (BD spec).
+    /// Cross-validates the MPLS STN view — see `labels/clpi_audit.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)]
+pub(crate) struct ClpiStream {
+    /// PID of the stream in the MPEG-TS (matches MPLS).
+    pub pid: u16,
+    /// BD stream 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,
+    // The CLPI cross-validation consumer (labels/clpi_audit.rs) reads only
+    // pid/coding_type/language. The codec sub-fields below are parsed from
+    // the BD stream_coding_info for completeness but have no reader yet.
+    /// Audio format byte (1=mono, 3=stereo, 6=5.1, 12=7.1).
+    /// Zero for non-audio streams.
+    #[allow(dead_code)]
+    pub audio_format: u8,
+    /// Audio sample rate (1=48kHz, 4=96kHz, 5=192kHz). Zero for non-audio.
+    #[allow(dead_code)]
+    pub audio_rate: u8,
+    /// Video format byte (1=480i, 4=1080i, 5=720p, 6=1080p, 8=2160p).
+    /// Zero for non-video.
+    #[allow(dead_code)]
+    pub video_format: u8,
+    /// Video rate (1=23.976, 2=24, 3=25, 4=29.97, 6=50, 7=59.94).
+    #[allow(dead_code)]
+    pub video_rate: u8,
+}
+
+/// Coarse EP-map entry. Fields feed the EP-map resolution used by
+/// `get_extents` (test-exercised; reserved for the timestamp-range path).
+#[derive(Debug, Clone)]
+#[allow(dead_code)]
+pub(crate) struct EpCoarse {
+    pub ref_to_fine_id: u32,
+    pub pts_coarse: u32,
+    pub spn_coarse: u32,
+}
+
+/// Fine EP-map entry (see `EpCoarse`).
+#[derive(Debug, Clone)]
+#[allow(dead_code)]
+pub(crate) struct EpFine {
+    pub pts_fine: u32,
+    pub spn_fine: u32,
+}
+
+// EP-map → sector-extent resolution. Exercised by the unit tests and
+// reserved for the timestamp-range read path; no production caller yet.
+#[allow(dead_code)]
+impl ClipInfo {
+    /// Reconstruct full PTS from coarse + fine entry.
+    ///
+    /// The BD spec PTS is 33-bit: `pts_coarse` is 14 bits (max 16383) and
+    /// `16383 << 19` exceeds `u32::MAX`, so the result must be `u64` to
+    /// avoid overflow (panic in debug, silent wrap in release).
+    pub fn full_pts(coarse: &EpCoarse, fine: &EpFine) -> u64 {
+        ((coarse.pts_coarse as u64) << 19) + ((fine.pts_fine as u64) << 8)
+    }
+
+    /// Reconstruct full SPN from coarse + fine entry.
+    pub fn full_spn(coarse: &EpCoarse, fine: &EpFine) -> u32 {
+        // The two operands occupy non-overlapping bit ranges (coarse holds
+        // the high bits, fine the low 17), so OR expresses intent and is
+        // robust to a hand-constructed EpFine.
+        debug_assert!(fine.spn_fine <= 0x1_FFFF);
+        (coarse.spn_coarse & 0xFFFE_0000) | fine.spn_fine
+    }
+
+    /// Get all EP entries as (PTS, SPN) pairs, fully resolved.
+    ///
+    /// PTS resets at each coarse-group boundary on disc, so the raw
+    /// concatenation is not globally monotonic. The returned vector is
+    /// sorted by PTS so callers (e.g. [`get_extents`]) can binary-search it.
+    ///
+    /// [`get_extents`]: ClipInfo::get_extents
+    pub fn resolved_ep_map(&self) -> Vec<(u64, u32)> {
+        let mut entries = Vec::with_capacity(self.ep_fine.len());
+
+        for (ci, coarse) in self.ep_coarse.iter().enumerate() {
+            let fine_start = coarse.ref_to_fine_id as usize;
+            let fine_end = if ci + 1 < self.ep_coarse.len() {
+                self.ep_coarse[ci + 1].ref_to_fine_id as usize
+            } else {
+                self.ep_fine.len()
+            };
+
+            for fi in fine_start..fine_end.min(self.ep_fine.len()) {
+                let fine = &self.ep_fine[fi];
+                let pts = Self::full_pts(coarse, fine);
+                let spn = Self::full_spn(coarse, fine);
+                entries.push((pts, spn));
+            }
+        }
+
+        // get_extents binary-searches by PTS, so the map must be ordered.
+        // Real discs have globally increasing PTS in coarse order; sort by
+        // (pts, spn) so a cross-group PTS collision can't leave the search
+        // landing on the wrong group's SPN.
+        entries.sort_by_key(|&(pts, spn)| (pts, spn));
+
+        entries
+    }
+
+    /// Get sector extents for a given in/out time range.
+    ///
+    /// Converts PTS timestamps to SPN ranges, then SPN to LBA
+    /// using the file's starting LBA on disc.
+    pub fn get_extents(&self, in_time: u64, out_time: u64) -> Vec<Extent> {
+        // resolved_ep_map() returns entries sorted by PTS, so binary search
+        // is valid here.
+        let ep_map = self.resolved_ep_map();
+        if ep_map.is_empty() {
+            return Vec::new();
+        }
+
+        // Find SPN at or before in_time
+        let start_spn = match ep_map.binary_search_by_key(&in_time, |(pts, _)| *pts) {
+            Ok(i) => ep_map[i].1,
+            Err(0) => ep_map[0].1,
+            Err(i) => ep_map[i - 1].1,
+        };
+
+        // Find SPN at or after out_time
+        let end_spn = match ep_map.binary_search_by_key(&out_time, |(pts, _)| *pts) {
+            Ok(i) => ep_map[i].1,
+            Err(i) if i < ep_map.len() => ep_map[i].1,
+            _ => ep_map.last().unwrap().1.saturating_add(1),
+        };
+
+        if end_spn <= start_spn {
+            return Vec::new();
+        }
+
+        // SPN → byte offset: spn × 192
+        // Byte offset → sectors: offset / 2048
+        // Note: the caller needs to add the file's starting LBA from UDF
+        let start_byte = start_spn as u64 * 192;
+        let end_byte = end_spn as u64 * 192;
+        let start_sector = (start_byte / 2048) as u32;
+        let end_sector = end_byte.div_ceil(2048) as u32;
+
+        vec![Extent {
+            start_lba: start_sector, // relative to m2ts file start
+            sector_count: end_sector - start_sector,
+        }]
+    }
+}
+
+/// Parse a CLPI file from raw bytes.
+pub fn parse(data: &[u8]) -> Result<ClipInfo> {
+    if data.len() < 40 {
+        return Err(Error::ClpiParse);
+    }
+
+    if &data[0..4] != b"HDMV" {
+        return Err(Error::ClpiParse);
+    }
+    let version = String::from_utf8_lossy(&data[4..8]).to_string();
+
+    // 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 cpi_start = u32::from_be_bytes([data[16], data[17], data[18], data[19]]) as usize;
+
+    // ClipInfo section at offset 40
+    // source_packet_count at offset 40 + 4(len) + 2(reserved) + 1(stream_type) + 1(app_type) + 4(reserved) + 4(ts_rate)
+    let source_packet_count = if data.len() >= 60 {
+        u32::from_be_bytes([data[56], data[57], data[58], data[59]])
+    } else {
+        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..])?
+    } else {
+        (Vec::new(), Vec::new())
+    };
+
+    Ok(ClipInfo {
+        version,
+        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 {
+        return Ok((Vec::new(), Vec::new()));
+    }
+
+    let cpi_length = u32::from_be_bytes([data[0], data[1], data[2], data[3]]) as usize;
+    if cpi_length < 4 {
+        return Ok((Vec::new(), Vec::new()));
+    }
+
+    // Bound all EP-map reads to this CPI section. The length field counts
+    // bytes after itself, so the section spans data[..cpi_length + 4]. A
+    // bogus ep_map_offset within data.len() but past the CPI section would
+    // otherwise read into an adjacent CLPI section; clamp first.
+    let data = &data[..(cpi_length + 4).min(data.len())];
+
+    // CPI type at bits 44-47 (byte 5, lower 4 bits)
+    // Skip to EP map: offset 4 (after length) + 2 (reserved/type)
+    if data.len() < 6 {
+        return Ok((Vec::new(), Vec::new()));
+    }
+    let ep_map = &data[6..];
+    if ep_map.len() < 4 {
+        return Ok((Vec::new(), Vec::new()));
+    }
+
+    // EP map header
+    // [0] reserved
+    // [1] number of stream PID entries
+    let num_streams = ep_map[1] as usize;
+    if num_streams == 0 {
+        return Ok((Vec::new(), Vec::new()));
+    }
+
+    // Stream PID entry headers start at offset 2
+    // Each: 2(PID) + 2(reserved+type) + 2(num_coarse) + 4(num_fine) + 4(ep_map_start) = 14 bytes
+    // We only care about the first stream (primary video)
+    if ep_map.len() < 16 {
+        return Ok((Vec::new(), Vec::new()));
+    }
+
+    // Stream PID entry — bit-packed per BD spec (libbluray clpi_parse.c):
+    //   stream_PID: 16 bits           → ep_map[2..4]
+    //   reserved: 10 bits             ┐
+    //   EP_stream_type: 4 bits        │ ep_map[4..14] = 80 bits
+    //   num_EP_coarse: 16 bits        │ (10+4+16+18+32 = 80)
+    //   num_EP_fine: 18 bits          │
+    //   EP_map_start_address: 32 bits ┘
+    let _stream_pid = u16::from_be_bytes([ep_map[2], ep_map[3]]);
+
+    // Read 10 bytes (80 bits) from ep_map[4..14] for bit extraction
+    // Use two u64s since we need 80 bits
+    let hi = u64::from_be_bytes([
+        ep_map[4], ep_map[5], ep_map[6], ep_map[7], ep_map[8], ep_map[9], ep_map[10], ep_map[11],
+    ]);
+    let lo_bytes = [ep_map[12], ep_map[13]];
+
+    // Bit 0-9: reserved (10)
+    // Bit 10-13: EP_stream_type (4)
+    // Bit 14-29: num_coarse (16)
+    // Bit 30-47: num_fine (18)
+    // Bit 48-79: EP_map_start (32) — bits 48-63 in hi, bits 64-79 in lo
+    let num_coarse = ((hi >> 34) & 0xFFFF) as usize;
+    let num_fine = ((hi >> 16) & 0x3FFFF) as usize;
+    let ep_map_offset = (((hi & 0xFFFF) as u32) << 16) | (u16::from_be_bytes(lo_bytes) as u32);
+    let ep_map_offset = ep_map_offset as usize;
+
+    // EP map for this stream starts at ep_map_offset relative to ep_map start
+    if ep_map_offset + 4 > ep_map.len() {
+        return Ok((Vec::new(), Vec::new()));
+    }
+
+    let stream_ep = &ep_map[ep_map_offset..];
+    if stream_ep.len() < 4 {
+        return Ok((Vec::new(), Vec::new()));
+    }
+
+    // Fine table start address (relative to this stream EP map)
+    let fine_start =
+        u32::from_be_bytes([stream_ep[0], stream_ep[1], stream_ep[2], stream_ep[3]]) as usize;
+
+    // Coarse entries start at offset 4, 8 bytes each
+    let coarse_data = &stream_ep[4..];
+    // Cap the pre-reservation by what the slice can actually hold:
+    // num_coarse is a 16-bit disc field, so a hostile value would
+    // otherwise reserve up to ~0.5 MB for an entry table that doesn't exist.
+    let mut ep_coarse = Vec::with_capacity(num_coarse.min(coarse_data.len() / 8));
+    for i in 0..num_coarse {
+        let off = i * 8;
+        if off + 8 > coarse_data.len() {
+            break;
+        }
+
+        let dword0 = u32::from_be_bytes([
+            coarse_data[off],
+            coarse_data[off + 1],
+            coarse_data[off + 2],
+            coarse_data[off + 3],
+        ]);
+        let ref_to_fine_id = dword0 >> 14;
+        let pts_coarse = dword0 & 0x3FFF;
+        let spn_coarse = u32::from_be_bytes([
+            coarse_data[off + 4],
+            coarse_data[off + 5],
+            coarse_data[off + 6],
+            coarse_data[off + 7],
+        ]);
+
+        ep_coarse.push(EpCoarse {
+            ref_to_fine_id,
+            pts_coarse,
+            spn_coarse,
+        });
+    }
+
+    // Fine entries at fine_start, 4 bytes each
+    // Cap the pre-reservation: num_fine is an 18-bit disc field (max
+    // 262143), so reserve only what the slice can actually hold.
+    let mut ep_fine = if fine_start < stream_ep.len() {
+        Vec::with_capacity(num_fine.min((stream_ep.len() - fine_start) / 4))
+    } else {
+        Vec::new()
+    };
+    if fine_start < stream_ep.len() {
+        let fine_data = &stream_ep[fine_start..];
+        for i in 0..num_fine {
+            let off = i * 4;
+            if off + 4 > fine_data.len() {
+                break;
+            }
+
+            let dword = u32::from_be_bytes([
+                fine_data[off],
+                fine_data[off + 1],
+                fine_data[off + 2],
+                fine_data[off + 3],
+            ]);
+            // Bits: is_angle(1) + i_end_offset(3) + pts_fine(11) + spn_fine(17)
+            let pts_fine = (dword >> 17) & 0x7FF;
+            let spn_fine = dword & 0x1FFFF;
+
+            ep_fine.push(EpFine { pts_fine, spn_fine });
+        }
+    }
+
+    Ok((ep_coarse, ep_fine))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Build a minimal CLPI binary.
+    /// `cpi_data` is the raw CPI section bytes (starting with the 4-byte CPI length).
+    fn build_clpi(source_packet_count: u32, cpi_data: Option<&[u8]>) -> Vec<u8> {
+        // We need at least 60 bytes for the header area.
+        // Offsets:
+        //   0..4:   "HDMV"
+        //   4..8:   "0200"
+        //   8..12:  seq_info_start (unused, set to 0)
+        //   12..16: prog_info_start (unused, set to 0)
+        //   16..20: cpi_start
+        //   20..40: reserved/padding
+        //   40..56: ClipInfo section area (length + stuff before source_packet_count)
+        //   56..60: source_packet_count
+
+        let cpi_start: u32 = if cpi_data.is_some() { 60 } else { 0 };
+
+        let mut buf = vec![0u8; 60];
+        // Magic + version
+        buf[0..4].copy_from_slice(b"HDMV");
+        buf[4..8].copy_from_slice(b"0200");
+        // seq_info_start = 0
+        // prog_info_start = 0
+        // cpi_start
+        buf[16..20].copy_from_slice(&cpi_start.to_be_bytes());
+        // source_packet_count at offset 56
+        buf[56..60].copy_from_slice(&source_packet_count.to_be_bytes());
+
+        if let Some(cpi) = cpi_data {
+            buf.extend_from_slice(cpi);
+        }
+
+        buf
+    }
+
+    /// Build a CPI section with one stream's EP map.
+    /// coarse_entries: Vec<(ref_to_fine_id, pts_coarse, spn_coarse)>
+    /// fine_entries: Vec<(pts_fine, spn_fine)>
+    fn build_cpi(
+        stream_pid: u16,
+        coarse_entries: &[(u32, u32, u32)],
+        fine_entries: &[(u32, u32)],
+    ) -> Vec<u8> {
+        // CPI section layout:
+        //   [0..4]   cpi_length (u32 BE)
+        //   [4..6]   reserved/type (2 bytes)
+        //   [6..]    EP map
+        //
+        // EP map layout (relative to byte 6 of CPI):
+        //   [0]      reserved
+        //   [1]      num_streams (1)
+        //   [2..4]   stream_PID (u16 BE)
+        //   [4..14]  80 bits: reserved(10) + EP_stream_type(4) + num_coarse(16) + num_fine(18) + EP_map_start(32)
+        //   [14..]   (next stream entry, if any)
+        //
+        // Stream EP map (at EP_map_start relative to EP map start):
+        //   [0..4]   fine_start (relative to stream EP map start)
+        //   [4..]    coarse entries, 8 bytes each
+        //   [fine_start..] fine entries, 4 bytes each
+
+        let num_coarse = coarse_entries.len() as u32;
+        let num_fine = fine_entries.len() as u32;
+
+        // EP_map_start: offset from ep_map start where the stream EP data begins.
+        // ep_map has: reserved(1) + num_streams(1) + stream_header(12) = 14 bytes
+        // So EP_map_start = 14 (first stream data right after the header)
+        let ep_map_start: u32 = 14;
+
+        // Build the 80-bit stream PID entry (10 bytes: ep_map[4..14])
+        // Bits: reserved(10) + EP_stream_type(4) + num_coarse(16) + num_fine(18) + EP_map_start(32)
+        // Total: 80 bits = 10 bytes
+        //
+        // Pack into a u128 for convenience then extract 10 bytes
+        let ep_stream_type: u32 = 1; // video
+        let packed: u128 = ((ep_stream_type as u128) << 66)           // EP_stream_type: 4 bits
+            | ((num_coarse as u128) << 50)                          // num_coarse: 16 bits
+            | ((num_fine as u128) << 32)                            // num_fine: 18 bits
+            | (ep_map_start as u128); // EP_map_start: 32 bits
+        let packed_bytes = packed.to_be_bytes(); // 16 bytes, we want the last 10
+        let stream_header_bits = &packed_bytes[6..16];
+
+        // Build stream EP data
+        // fine_start = 4 (header) + num_coarse * 8
+        let fine_start: u32 = 4 + num_coarse * 8;
+        let mut stream_ep = Vec::new();
+        stream_ep.extend_from_slice(&fine_start.to_be_bytes());
+
+        // Coarse entries: 8 bytes each
+        // dword0 = (ref_to_fine_id << 14) | (pts_coarse & 0x3FFF)
+        // dword1 = spn_coarse
+        for &(ref_id, pts_c, spn_c) in coarse_entries {
+            let dword0 = (ref_id << 14) | (pts_c & 0x3FFF);
+            stream_ep.extend_from_slice(&dword0.to_be_bytes());
+            stream_ep.extend_from_slice(&spn_c.to_be_bytes());
+        }
+
+        // Fine entries: 4 bytes each
+        // dword = (is_angle(1) + i_end_offset(3) + pts_fine(11) + spn_fine(17))
+        for &(pts_f, spn_f) in fine_entries {
+            let dword: u32 = ((pts_f & 0x7FF) << 17) | (spn_f & 0x1FFFF);
+            stream_ep.extend_from_slice(&dword.to_be_bytes());
+        }
+
+        // Assemble EP map
+        let mut ep_map = Vec::new();
+        ep_map.push(0); // reserved
+        ep_map.push(1); // num_streams = 1
+        ep_map.extend_from_slice(&stream_pid.to_be_bytes());
+        ep_map.extend_from_slice(stream_header_bits);
+        ep_map.extend_from_slice(&stream_ep);
+
+        // Assemble CPI section
+        let mut cpi = Vec::new();
+        let cpi_length = (2 + ep_map.len()) as u32; // reserved/type(2) + ep_map
+        cpi.extend_from_slice(&cpi_length.to_be_bytes());
+        cpi.extend_from_slice(&[0u8; 2]); // reserved/type
+        cpi.extend_from_slice(&ep_map);
+
+        cpi
+    }
+
+    #[test]
+    fn parse_valid_clpi() {
+        let cpi = build_cpi(
+            0x1011,
+            &[(0, 100, 0x00020000)], // 1 coarse
+            &[(50, 1024)],           // 1 fine
+        );
+        let data = build_clpi(500_000, Some(&cpi));
+
+        let clip = parse(&data).expect("should parse valid CLPI");
+        assert_eq!(clip.version, "0200");
+        assert_eq!(clip.source_packet_count, 500_000);
+        assert_eq!(clip.ep_coarse.len(), 1);
+        assert_eq!(clip.ep_fine.len(), 1);
+    }
+
+    #[test]
+    fn parse_ep_map() {
+        let cpi = build_cpi(
+            0x1011,
+            &[
+                (0, 100, 0x00020000), // coarse 0: fine starts at 0, pts_coarse=100, spn_coarse=0x20000
+                (2, 200, 0x00040000), // coarse 1: fine starts at 2, pts_coarse=200, spn_coarse=0x40000
+            ],
+            &[
+                (50, 1024),  // fine 0
+                (100, 2048), // fine 1
+                (25, 512),   // fine 2
+                (75, 1536),  // fine 3
+            ],
+        );
+        let data = build_clpi(1_000_000, Some(&cpi));
+
+        let clip = parse(&data).expect("should parse EP map");
+        assert_eq!(clip.ep_coarse.len(), 2);
+        assert_eq!(clip.ep_fine.len(), 4);
+
+        // Verify coarse entries
+        assert_eq!(clip.ep_coarse[0].ref_to_fine_id, 0);
+        assert_eq!(clip.ep_coarse[0].pts_coarse, 100);
+        assert_eq!(clip.ep_coarse[0].spn_coarse, 0x00020000);
+        assert_eq!(clip.ep_coarse[1].ref_to_fine_id, 2);
+        assert_eq!(clip.ep_coarse[1].pts_coarse, 200);
+        assert_eq!(clip.ep_coarse[1].spn_coarse, 0x00040000);
+
+        // Verify fine entries
+        assert_eq!(clip.ep_fine[0].pts_fine, 50);
+        assert_eq!(clip.ep_fine[0].spn_fine, 1024);
+        assert_eq!(clip.ep_fine[1].pts_fine, 100);
+        assert_eq!(clip.ep_fine[1].spn_fine, 2048);
+        assert_eq!(clip.ep_fine[2].pts_fine, 25);
+        assert_eq!(clip.ep_fine[2].spn_fine, 512);
+        assert_eq!(clip.ep_fine[3].pts_fine, 75);
+        assert_eq!(clip.ep_fine[3].spn_fine, 1536);
+
+        // Verify resolved EP map assigns fine entries to coarse correctly
+        let resolved = clip.resolved_ep_map();
+        assert_eq!(resolved.len(), 4);
+        // First two fines belong to coarse 0, last two to coarse 1
+    }
+
+    #[test]
+    fn full_pts_calculation() {
+        let coarse = EpCoarse {
+            ref_to_fine_id: 0,
+            pts_coarse: 100,
+            spn_coarse: 0,
+        };
+        let fine = EpFine {
+            pts_fine: 50,
+            spn_fine: 0,
+        };
+        // full_pts = (100 << 19) + (50 << 8) = 52_428_800 + 12_800 = 52_441_600
+        let pts = ClipInfo::full_pts(&coarse, &fine);
+        assert_eq!(pts, (100u64 << 19) + (50u64 << 8));
+        assert_eq!(pts, 52_441_600);
+    }
+
+    #[test]
+    fn full_pts_no_u32_overflow() {
+        // pts_coarse is a 14-bit field (max 0x3FFF = 16383); 16383 << 19
+        // overflows u32, so full_pts must use u64.
+        let coarse = EpCoarse {
+            ref_to_fine_id: 0,
+            pts_coarse: 0x3FFF,
+            spn_coarse: 0,
+        };
+        let fine = EpFine {
+            pts_fine: 0x7FF,
+            spn_fine: 0,
+        };
+        let pts = ClipInfo::full_pts(&coarse, &fine);
+        assert_eq!(pts, (0x3FFFu64 << 19) + (0x7FFu64 << 8));
+        assert!(pts > u32::MAX as u64);
+    }
+
+    #[test]
+    fn resolved_ep_map_sorted_for_binary_search() {
+        // Two coarse groups whose fine PTS reset across the boundary
+        // (50,100 then 25,75) produce a non-monotonic raw concatenation.
+        // resolved_ep_map must sort so get_extents' binary search is valid.
+        let cpi = build_cpi(
+            0x1011,
+            &[(0, 0, 0x00020000), (2, 0, 0x00040000)],
+            &[(50, 1024), (100, 2048), (25, 512), (75, 1536)],
+        );
+        let data = build_clpi(1_000_000, Some(&cpi));
+        let clip = parse(&data).expect("should parse");
+
+        let resolved = clip.resolved_ep_map();
+        assert_eq!(resolved.len(), 4);
+        // Strictly sorted by PTS.
+        for w in resolved.windows(2) {
+            assert!(w[0].0 <= w[1].0, "ep_map not sorted: {resolved:?}");
+        }
+    }
+
+    #[test]
+    fn full_spn_calculation() {
+        let coarse = EpCoarse {
+            ref_to_fine_id: 0,
+            pts_coarse: 0,
+            spn_coarse: 0x00FE0000,
+        };
+        let fine = EpFine {
+            pts_fine: 0,
+            spn_fine: 0x1234,
+        };
+        // full_spn = (0x00FE0000 & 0xFFFE0000) + 0x1234 = 0x00FE0000 + 0x1234 = 0x00FE1234
+        let spn = ClipInfo::full_spn(&coarse, &fine);
+        assert_eq!(spn, 0x00FE0000 + 0x1234);
+        assert_eq!(spn, 0x00FE1234);
+
+        // Test that the low bit of spn_coarse is masked out
+        let coarse2 = EpCoarse {
+            ref_to_fine_id: 0,
+            pts_coarse: 0,
+            spn_coarse: 0x00FF0000,
+        };
+        let spn2 = ClipInfo::full_spn(&coarse2, &fine);
+        // 0x00FF0000 & 0xFFFE0000 = 0x00FE0000, so low 17 bits of coarse are zeroed
+        assert_eq!(spn2, 0x00FE0000 + 0x1234);
+    }
+
+    #[test]
+    fn parse_truncated_clipinfo_no_panic() {
+        // 57/58/59-byte CLPI with valid magic: passes the data.len() < 40
+        // guard but data[56..60] needs 60 bytes. Must not panic.
+        for len in 40..60usize {
+            let mut data = vec![0u8; len];
+            data[0..4].copy_from_slice(b"HDMV");
+            if len >= 8 {
+                data[4..8].copy_from_slice(b"0200");
+            }
+            let clip = parse(&data).expect("short CLPI should parse, not panic");
+            // source_packet_count is unreadable below 60 bytes → 0.
+            assert_eq!(clip.source_packet_count, 0);
+        }
+    }
+
+    #[test]
+    fn parse_invalid_magic() {
+        let mut data = build_clpi(1000, None);
+        data[0] = b'X';
+        data[1] = b'X';
+        data[2] = b'X';
+        data[3] = b'X';
+        assert!(parse(&data).is_err());
+    }
+
+    #[test]
+    fn parse_empty_ep_map() {
+        // cpi_start = 0 means no CPI section
+        let data = build_clpi(100_000, None);
+        let clip = parse(&data).expect("should parse with no EP map");
+        assert_eq!(clip.source_packet_count, 100_000);
+        assert!(clip.ep_coarse.is_empty());
+        assert!(clip.ep_fine.is_empty());
+
+        // Also test: CPI section present but with zero streams
+        let mut cpi = Vec::new();
+        let cpi_length: u32 = 6; // reserved/type(2) + ep_map(reserved(1) + num_streams=0(1) + 2 padding)
+        cpi.extend_from_slice(&cpi_length.to_be_bytes());
+        cpi.extend_from_slice(&[0u8; 2]); // reserved/type
+        cpi.push(0); // reserved
+        cpi.push(0); // num_streams = 0
+        cpi.extend_from_slice(&[0u8; 4]); // padding
+
+        let data2 = build_clpi(100_000, Some(&cpi));
+        let clip2 = parse(&data2).expect("should parse with zero-stream EP map");
+        assert!(clip2.ep_coarse.is_empty());
+        assert!(clip2.ep_fine.is_empty());
+    }
+}

src/css/auth.rs

@@ -0,0 +1,593 @@
+//! CSS drive authentication — full key hierarchy.
+//!
+//! Protocol:
+//!   1. Bus authentication (challenge-response) → bus key
+//!   2. Read disc key block (READ DVD STRUCTURE) → XOR with bus key → decrypt with player keys → disc key
+//!   3. Read title key (REPORT KEY format 0x04) → XOR with bus key → decrypt with disc key → title key
+
+use crate::drive::Drive;
+use crate::error::{Error, Result};
+
+// ── Built-in public DVD CSS player keys ────────────────────────────────────
+//
+// These 31 5-byte player keys are long-public CSS inputs. With them
+// compiled in, DVD ripping works with no external key file required.
+
+const PLAYER_KEYS: [[u8; 5]; 31] = [
+    [0x01, 0xaf, 0xe3, 0x12, 0x80],
+    [0x12, 0x11, 0xca, 0x04, 0x3b],
+    [0x14, 0x0c, 0x9e, 0xd0, 0x09],
+    [0x14, 0x71, 0x35, 0xba, 0xe2],
+    [0x1a, 0xa4, 0x33, 0x21, 0xa6],
+    [0x26, 0xec, 0xc4, 0xa7, 0x4e],
+    [0x2c, 0xb2, 0xc1, 0x09, 0xee],
+    [0x2f, 0x25, 0x9e, 0x96, 0xdd],
+    [0x33, 0x2f, 0x49, 0x6c, 0xe0],
+    [0x35, 0x5b, 0xc1, 0x31, 0x0f],
+    [0x36, 0x67, 0xb2, 0xe3, 0x85],
+    [0x39, 0x3d, 0xf1, 0xf1, 0xbd],
+    [0x3b, 0x31, 0x34, 0x0d, 0x91],
+    [0x45, 0xed, 0x28, 0xeb, 0xd3],
+    [0x48, 0xb7, 0x6c, 0xce, 0x69],
+    [0x4b, 0x65, 0x0d, 0xc1, 0xee],
+    [0x4c, 0xbb, 0xf5, 0x5b, 0x23],
+    [0x51, 0x67, 0x67, 0xc5, 0xe0],
+    [0x53, 0x94, 0xe1, 0x75, 0xbf],
+    [0x57, 0x2c, 0x8b, 0x31, 0xae],
+    [0x63, 0xdb, 0x4c, 0x5b, 0x4a],
+    [0x7b, 0x1e, 0x5e, 0x2b, 0x57],
+    [0x85, 0xf3, 0x85, 0xa0, 0xe0],
+    [0xab, 0x1e, 0xe7, 0x7b, 0x72],
+    [0xab, 0x36, 0xe3, 0xeb, 0x76],
+    [0xb1, 0xb8, 0xf9, 0x38, 0x03],
+    [0xb8, 0x5d, 0xd8, 0x53, 0xbd],
+    [0xbf, 0x92, 0xc3, 0xb0, 0xe2],
+    [0xcf, 0x1a, 0xb2, 0xf8, 0x0a],
+    [0xec, 0xa0, 0xcf, 0xb3, 0xff],
+    [0xfc, 0x95, 0xa9, 0x87, 0x35],
+];
+
+// ── CryptKey tables ───────────────────────────────────────────────────────
+
+const CRYPT_TAB0: [u8; 256] = [
+    0xB7, 0xF4, 0x82, 0x57, 0xDA, 0x4D, 0xDB, 0xE2, 0x2F, 0x52, 0x1A, 0xA8, 0x68, 0x5A, 0x8A, 0xFF,
+    0xFB, 0x0E, 0x6D, 0x35, 0xF7, 0x5C, 0x76, 0x12, 0xCE, 0x25, 0x79, 0x29, 0x39, 0x62, 0x08, 0x24,
+    0xA5, 0x85, 0x7B, 0x56, 0x01, 0x23, 0x68, 0xCF, 0x0A, 0xE2, 0x5A, 0xED, 0x3D, 0x59, 0xB0, 0xA9,
+    0xB0, 0x2C, 0xF2, 0xB8, 0xEF, 0x32, 0xA9, 0x40, 0x80, 0x71, 0xAF, 0x1E, 0xDE, 0x8F, 0x58, 0x88,
+    0xB8, 0x3A, 0xD0, 0xFC, 0xC4, 0x1E, 0xB5, 0xA0, 0xBB, 0x3B, 0x0F, 0x01, 0x7E, 0x1F, 0x9F, 0xD9,
+    0xAA, 0xB8, 0x3D, 0x9D, 0x74, 0x1E, 0x25, 0xDB, 0x37, 0x56, 0x8F, 0x16, 0xBA, 0x49, 0x2B, 0xAC,
+    0xD0, 0xBD, 0x95, 0x20, 0xBE, 0x7A, 0x28, 0xD0, 0x51, 0x64, 0x63, 0x1C, 0x7F, 0x66, 0x10, 0xBB,
+    0xC4, 0x56, 0x1A, 0x04, 0x6E, 0x0A, 0xEC, 0x9C, 0xD6, 0xE8, 0x9A, 0x7A, 0xCF, 0x8C, 0xDB, 0xB1,
+    0xEF, 0x71, 0xDE, 0x31, 0xFF, 0x54, 0x3E, 0x5E, 0x07, 0x69, 0x96, 0xB0, 0xCF, 0xDD, 0x9E, 0x47,
+    0xC7, 0x96, 0x8F, 0xE4, 0x2B, 0x59, 0xC6, 0xEE, 0xB9, 0x86, 0x9A, 0x64, 0x84, 0x72, 0xE2, 0x5B,
+    0xA2, 0x96, 0x58, 0x99, 0x50, 0x03, 0xF5, 0x38, 0x4D, 0x02, 0x7D, 0xE7, 0x7D, 0x75, 0xA7, 0xB8,
+    0x67, 0x87, 0x84, 0x3F, 0x1D, 0x11, 0xE5, 0xFC, 0x1E, 0xD3, 0x83, 0x16, 0xA5, 0x29, 0xF6, 0xC7,
+    0x15, 0x61, 0x29, 0x1A, 0x43, 0x4F, 0x9B, 0xAF, 0xC5, 0x87, 0x34, 0x6C, 0x0F, 0x3B, 0xA8, 0x1D,
+    0x45, 0x58, 0x25, 0xDC, 0xA8, 0xA3, 0x3B, 0xD1, 0x79, 0x1B, 0x48, 0xF2, 0xE9, 0x93, 0x1F, 0xFC,
+    0xDB, 0x2A, 0x90, 0xA9, 0x8A, 0x3D, 0x39, 0x18, 0xA3, 0x8E, 0x58, 0x6C, 0xE0, 0x12, 0xBB, 0x25,
+    0xCD, 0x71, 0x22, 0xA2, 0x64, 0xC6, 0xE7, 0xFB, 0xAD, 0x94, 0x77, 0x04, 0x9A, 0x39, 0xCF, 0x7C,
+];
+
+const CRYPT_TAB1: [u8; 256] = [
+    0x8C, 0x47, 0xB0, 0xE1, 0xEB, 0xFC, 0xEB, 0x56, 0x10, 0xE5, 0x2C, 0x1A, 0x5D, 0xEF, 0xBE, 0x4F,
+    0x08, 0x75, 0x97, 0x4B, 0x0E, 0x25, 0x8E, 0x6E, 0x39, 0x5A, 0x87, 0x53, 0xC4, 0x1F, 0xF4, 0x5C,
+    0x4E, 0xE6, 0x99, 0x30, 0xE0, 0x42, 0x88, 0xAB, 0xE5, 0x85, 0xBC, 0x8F, 0xD8, 0x3C, 0x54, 0xC9,
+    0x53, 0x47, 0x18, 0xD6, 0x06, 0x5B, 0x41, 0x2C, 0x67, 0x1E, 0x41, 0x74, 0x33, 0xE2, 0xB4, 0xE0,
+    0x23, 0x29, 0x42, 0xEA, 0x55, 0x0F, 0x25, 0xB4, 0x24, 0x2C, 0x99, 0x13, 0xEB, 0x0A, 0x0B, 0xC9,
+    0xF9, 0x63, 0x67, 0x43, 0x2D, 0xC7, 0x7D, 0x07, 0x60, 0x89, 0xD1, 0xCC, 0xE7, 0x94, 0x77, 0x74,
+    0x9B, 0x7E, 0xD7, 0xE6, 0xFF, 0xBB, 0x68, 0x14, 0x1E, 0xA3, 0x25, 0xDE, 0x3A, 0xA3, 0x54, 0x7B,
+    0x87, 0x9D, 0x50, 0xCA, 0x27, 0xC3, 0xA4, 0x50, 0x91, 0x27, 0xD4, 0xB0, 0x82, 0x41, 0x97, 0x79,
+    0x94, 0x82, 0xAC, 0xC7, 0x8E, 0xA5, 0x4E, 0xAA, 0x78, 0x9E, 0xE0, 0x42, 0xBA, 0x28, 0xEA, 0xB7,
+    0x74, 0xAD, 0x35, 0xDA, 0x92, 0x60, 0x7E, 0xD2, 0x0E, 0xB9, 0x24, 0x5E, 0x39, 0x4F, 0x5E, 0x63,
+    0x09, 0xB5, 0xFA, 0xBF, 0xF1, 0x22, 0x55, 0x1C, 0xE2, 0x25, 0xDB, 0xC5, 0xD8, 0x50, 0x03, 0x98,
+    0xC4, 0xAC, 0x2E, 0x11, 0xB4, 0x38, 0x4D, 0xD0, 0xB9, 0xFC, 0x2D, 0x3C, 0x08, 0x04, 0x5A, 0xEF,
+    0xCE, 0x32, 0xFB, 0x4C, 0x92, 0x1E, 0x4B, 0xFB, 0x1A, 0xD0, 0xE2, 0x3E, 0xDA, 0x6E, 0x7C, 0x4D,
+    0x56, 0xC3, 0x3F, 0x42, 0xB1, 0x3A, 0x23, 0x4D, 0x6E, 0x84, 0x56, 0x68, 0xF4, 0x0E, 0x03, 0x64,
+    0xD0, 0xA9, 0x92, 0x2F, 0x8B, 0xBC, 0x39, 0x9C, 0xAC, 0x09, 0x5E, 0xEE, 0xE5, 0x97, 0xBF, 0xA5,
+    0xCE, 0xFA, 0x28, 0x2C, 0x6D, 0x4F, 0xEF, 0x77, 0xAA, 0x1B, 0x79, 0x8E, 0x97, 0xB4, 0xC3, 0xF4,
+];
+
+const CRYPT_TAB2: [u8; 256] = [
+    0xB7, 0x75, 0x81, 0xD5, 0xDC, 0xCA, 0xDE, 0x66, 0x23, 0xDF, 0x15, 0x26, 0x62, 0xD1, 0x83, 0x77,
+    0xE3, 0x97, 0x76, 0xAF, 0xE9, 0xC3, 0x6B, 0x8E, 0xDA, 0xB0, 0x6E, 0xBF, 0x2B, 0xF1, 0x19, 0xB4,
+    0x95, 0x34, 0x48, 0xE4, 0x37, 0x94, 0x5D, 0x7B, 0x36, 0x5F, 0x65, 0x53, 0x07, 0xE2, 0x89, 0x11,
+    0x98, 0x85, 0xD9, 0x12, 0xC1, 0x9D, 0x84, 0xEC, 0xA4, 0xD4, 0x88, 0xB8, 0xFC, 0x2C, 0x79, 0x28,
+    0xD8, 0xDB, 0xB3, 0x1E, 0xA2, 0xF9, 0xD0, 0x44, 0xD7, 0xD6, 0x60, 0xEF, 0x14, 0xF4, 0xF6, 0x31,
+    0xD2, 0x41, 0x46, 0x67, 0x0A, 0xE1, 0x58, 0x27, 0x43, 0xA3, 0xF8, 0xE0, 0xC8, 0xBA, 0x5A, 0x5C,
+    0x80, 0x6C, 0xC6, 0xF2, 0xE8, 0xAD, 0x7D, 0x04, 0x0D, 0xB9, 0x3C, 0xC2, 0x25, 0xBD, 0x49, 0x63,
+    0x8C, 0x9F, 0x51, 0xCE, 0x20, 0xC5, 0xA1, 0x50, 0x92, 0x2D, 0xDD, 0xBC, 0x8D, 0x4F, 0x9A, 0x71,
+    0x2F, 0x30, 0x1D, 0x73, 0x39, 0x13, 0xFB, 0x1A, 0xCB, 0x24, 0x59, 0xFE, 0x05, 0x96, 0x57, 0x0F,
+    0x1F, 0xCF, 0x54, 0xBE, 0xF5, 0x06, 0x1B, 0xB2, 0x6D, 0xD3, 0x4D, 0x32, 0x56, 0x21, 0x33, 0x0B,
+    0x52, 0xE7, 0xAB, 0xEB, 0xA6, 0x74, 0x00, 0x4C, 0xB1, 0x7F, 0x82, 0x99, 0x87, 0x0E, 0x5E, 0xC0,
+    0x8F, 0xEE, 0x6F, 0x55, 0xF3, 0x7E, 0x08, 0x90, 0xFA, 0xB6, 0x64, 0x70, 0x47, 0x4A, 0x17, 0xA7,
+    0xB5, 0x40, 0x8A, 0x38, 0xE5, 0x68, 0x3E, 0x8B, 0x69, 0xAA, 0x9B, 0x42, 0xA5, 0x10, 0x01, 0x35,
+    0xFD, 0x61, 0x9E, 0xE6, 0x16, 0x9C, 0x86, 0xED, 0xCD, 0x2E, 0xFF, 0xC4, 0x5B, 0xA0, 0xAE, 0xCC,
+    0x4B, 0x3B, 0x03, 0xBB, 0x1C, 0x2A, 0xAC, 0x0C, 0x3F, 0x93, 0xC7, 0x72, 0x7A, 0x09, 0x22, 0x3D,
+    0x45, 0x78, 0xA9, 0xA8, 0xEA, 0xC9, 0x6A, 0xF7, 0x29, 0x91, 0xF0, 0x02, 0x18, 0x3A, 0x4E, 0x7C,
+];
+
+const CRYPT_TAB3: [u8; 256] = [
+    0x73, 0x51, 0x95, 0xE1, 0x12, 0xE4, 0xC0, 0x58, 0xEE, 0xF2, 0x08, 0x1B, 0xA9, 0xFA, 0x98, 0x4C,
+    0xA7, 0x33, 0xE2, 0x1B, 0xA7, 0x6D, 0xF5, 0x30, 0x97, 0x1D, 0xF3, 0x02, 0x60, 0x5A, 0x82, 0x0F,
+    0x91, 0xD0, 0x9C, 0x10, 0x39, 0x7A, 0x83, 0x85, 0x3B, 0xB2, 0xB8, 0xAE, 0x0C, 0x09, 0x52, 0xEA,
+    0x1C, 0xE1, 0x8D, 0x66, 0x4F, 0xF3, 0xDA, 0x92, 0x29, 0xB9, 0xD5, 0xC5, 0x77, 0x47, 0x22, 0x53,
+    0x14, 0xF7, 0xAF, 0x22, 0x64, 0xDF, 0xC6, 0x72, 0x12, 0xF3, 0x75, 0xDA, 0xD7, 0xD7, 0xE5, 0x02,
+    0x9E, 0xED, 0xDA, 0xDB, 0x4C, 0x47, 0xCE, 0x91, 0x06, 0x06, 0x6D, 0x55, 0x8B, 0x19, 0xC9, 0xEF,
+    0x8C, 0x80, 0x1A, 0x0E, 0xEE, 0x4B, 0xAB, 0xF2, 0x08, 0x5C, 0xE9, 0x37, 0x26, 0x5E, 0x9A, 0x90,
+    0x00, 0xF3, 0x0D, 0xB2, 0xA6, 0xA3, 0xF7, 0x26, 0x17, 0x48, 0x88, 0xC9, 0x0E, 0x2C, 0xC9, 0x02,
+    0xE7, 0x18, 0x05, 0x4B, 0xF3, 0x39, 0xE1, 0x20, 0x02, 0x0D, 0x40, 0xC7, 0xCA, 0xB9, 0x48, 0x30,
+    0x57, 0x67, 0xCC, 0x06, 0xBF, 0xAC, 0x81, 0x08, 0x24, 0x7A, 0xD4, 0x8B, 0x19, 0x8E, 0xAC, 0xB4,
+    0x5A, 0x0F, 0x73, 0x13, 0xAC, 0x9E, 0xDA, 0xB6, 0xB8, 0x96, 0x5B, 0x60, 0x88, 0xE1, 0x81, 0x3F,
+    0x07, 0x86, 0x37, 0x2D, 0x79, 0x14, 0x52, 0xEA, 0x73, 0xDF, 0x3D, 0x09, 0xC8, 0x25, 0x48, 0xD8,
+    0x75, 0x60, 0x9A, 0x08, 0x27, 0x4A, 0x2C, 0xB9, 0xA8, 0x8B, 0x8A, 0x73, 0x62, 0x37, 0x16, 0x02,
+    0xBD, 0xC1, 0x0E, 0x56, 0x54, 0x3E, 0x14, 0x5F, 0x8C, 0x8F, 0x6E, 0x75, 0x1C, 0x07, 0x39, 0x7B,
+    0x4B, 0xDB, 0xD3, 0x4B, 0x1E, 0xC8, 0x7E, 0xFE, 0x3E, 0x72, 0x16, 0x83, 0x7D, 0xEE, 0xF5, 0xCA,
+    0xC5, 0x18, 0xF9, 0xD8, 0x68, 0xAB, 0x38, 0x85, 0xA8, 0xF0, 0xA1, 0x73, 0x9F, 0x5D, 0x19, 0x0B,
+];
+
+const VARIANTS: [u8; 32] = [
+    0xB7, 0x74, 0x85, 0xD0, 0xCC, 0xDB, 0xCA, 0x73, 0x03, 0xFE, 0x31, 0x03, 0x52, 0xE0, 0xB7, 0x42,
+    0x63, 0x16, 0xF2, 0x2A, 0x79, 0x52, 0xFF, 0x1B, 0x7A, 0x11, 0xCA, 0x1A, 0x9B, 0x40, 0xAD, 0x01,
+];
+
+const SECRET: [u8; 5] = [0x55, 0xD6, 0xC4, 0xC5, 0x28];
+
+const PERM_CHALLENGE: [[usize; 10]; 3] = [
+    [1, 3, 0, 7, 5, 2, 9, 6, 4, 8],
+    [6, 1, 9, 3, 8, 5, 7, 4, 0, 2],
+    [4, 0, 3, 5, 7, 2, 8, 6, 1, 9],
+];
+
+const PERM_VARIANT: [[u8; 32]; 2] = [
+    [
+        0x0A, 0x08, 0x0E, 0x0C, 0x0B, 0x09, 0x0F, 0x0D, 0x1A, 0x18, 0x1E, 0x1C, 0x1B, 0x19, 0x1F,
+        0x1D, 0x02, 0x00, 0x06, 0x04, 0x03, 0x01, 0x07, 0x05, 0x12, 0x10, 0x16, 0x14, 0x13, 0x11,
+        0x17, 0x15,
+    ],
+    [
+        0x12, 0x1A, 0x16, 0x1E, 0x02, 0x0A, 0x06, 0x0E, 0x10, 0x18, 0x14, 0x1C, 0x00, 0x08, 0x04,
+        0x0C, 0x13, 0x1B, 0x17, 0x1F, 0x03, 0x0B, 0x07, 0x0F, 0x11, 0x19, 0x15, 0x1D, 0x01, 0x09,
+        0x05, 0x0D,
+    ],
+];
+
+// ── Public API ────────────────────────────────────────────────────────────
+
+/// Perform CSS bus authentication only.
+pub fn authenticate(drive: &mut Drive) -> Result<()> {
+    let (_, _) = bus_auth(drive)?;
+    Ok(())
+}
+
+/// Full CSS key extraction: bus auth → disc key → title key.
+pub fn authenticate_and_read_title_key(drive: &mut Drive, lba: u32) -> Result<[u8; 5]> {
+    // Session 1: bus auth → disc key (AGID consumed by READ_DVD_STRUCTURE)
+    let (agid, bus_key) = bus_auth(drive)?;
+    let disc_key = read_disc_key(drive, agid, &bus_key)?;
+
+    // Session 2: fresh bus auth → title key (needs separate AGID)
+    let (agid2, bus_key2) = bus_auth(drive)?;
+    let encrypted_title = read_raw_title_key(drive, agid2, lba)?;
+
+    // Decrypt title key: XOR with bus key, then decrypt with disc key
+    let mut title_key = [0u8; 5];
+    for i in 0..5 {
+        title_key[i] = encrypted_title[i] ^ bus_key2[i];
+    }
+
+    if title_key == [0u8; 5] {
+        return Ok(title_key);
+    }
+
+    let title_key = super::lfsr::decrypt_key(0xFF, &disc_key, &title_key);
+    Ok(title_key)
+}
+
+// ── Step 1: Bus Authentication ────────────────────────────────────────────
+
+fn bus_auth(drive: &mut Drive) -> Result<(u8, [u8; 5])> {
+    let scsi = drive.scsi_mut();
+
+    // Invalidate all AGIDs via REPORT KEY format 0x3F
+    for agid in 0..4u8 {
+        let mut cdb = [0u8; 12];
+        cdb[0] = crate::scsi::SCSI_REPORT_KEY;
+        // alloc_len = 0 (no data transfer)
+        cdb[10] = (agid << 6) | 0x3F;
+        let mut buf = [0u8; 8];
+        let _ = scsi.execute(
+            &cdb,
+            crate::scsi::DataDirection::FromDevice,
+            &mut buf,
+            5_000,
+        );
+    }
+
+    // Allocate AGID
+    let mut buf = [0u8; 8];
+    scsi.execute(
+        &report_key_cdb(0, 0x00, 8),
+        crate::scsi::DataDirection::FromDevice,
+        &mut buf,
+        5_000,
+    )
+    .map_err(|_| Error::CssAuthFailed)?;
+    let agid = (buf[7] >> 6) & 0x03;
+
+    // Host sends challenge
+    let host_challenge: [u8; 10] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+    let mut hc_buf = [0u8; 16];
+    hc_buf[0] = 0x00;
+    hc_buf[1] = 0x0E;
+    for i in 0..10 {
+        hc_buf[4 + i] = host_challenge[9 - i];
+    }
+    scsi.execute(
+        &send_key_cdb(agid, 0x01, 16),
+        crate::scsi::DataDirection::ToDevice,
+        &mut hc_buf,
+        5_000,
+    )
+    .map_err(|_| Error::CssAuthFailed)?;
+
+    // Get Key1 from drive
+    let mut dk_buf = [0u8; 12];
+    scsi.execute(
+        &report_key_cdb(agid, 0x02, 12),
+        crate::scsi::DataDirection::FromDevice,
+        &mut dk_buf,
+        5_000,
+    )
+    .map_err(|_| Error::CssAuthFailed)?;
+    let mut key1 = [0u8; 5];
+    for i in 0..5 {
+        key1[i] = dk_buf[4 + (4 - i)];
+    }
+
+    // Brute-force variant (0-31)
+    let mut variant: Option<u8> = None;
+    for v in 0..32u8 {
+        if crypt_key(0, v, &host_challenge) == key1 {
+            variant = Some(v);
+            break;
+        }
+    }
+    let variant = variant.ok_or(Error::CssAuthFailed)?;
+
+    // Get drive challenge
+    let mut dc_buf = [0u8; 16];
+    scsi.execute(
+        &report_key_cdb(agid, 0x01, 16),
+        crate::scsi::DataDirection::FromDevice,
+        &mut dc_buf,
+        5_000,
+    )
+    .map_err(|_| Error::CssAuthFailed)?;
+    let mut drive_challenge = [0u8; 10];
+    for i in 0..10 {
+        drive_challenge[i] = dc_buf[4 + (9 - i)];
+    }
+
+    // Compute Key2 and send it
+    let key2 = crypt_key(1, variant, &drive_challenge);
+    let mut hk_buf = [0u8; 12];
+    hk_buf[0] = 0x00;
+    hk_buf[1] = 0x0A;
+    for i in 0..5 {
+        hk_buf[4 + i] = key2[4 - i];
+    }
+    scsi.execute(
+        &send_key_cdb(agid, 0x03, 12),
+        crate::scsi::DataDirection::ToDevice,
+        &mut hk_buf,
+        5_000,
+    )
+    .map_err(|_| Error::CssAuthFailed)?;
+
+    // Bus key = CryptKey(2, variant, key1 || key2)
+    let mut combined = [0u8; 10];
+    combined[..5].copy_from_slice(&key1);
+    combined[5..].copy_from_slice(&key2);
+    let bus_key = crypt_key(2, variant, &combined);
+
+    Ok((agid, bus_key))
+}
+
+// ── Step 2: Disc Key ──────────────────────────────────────────────────────
+
+fn read_disc_key(drive: &mut Drive, agid: u8, bus_key: &[u8; 5]) -> Result<[u8; 5]> {
+    let scsi = drive.scsi_mut();
+
+    // READ DVD STRUCTURE, format 0x02 (disc key), 2048+4 bytes
+    let alloc_len: u16 = 2048 + 4;
+    let mut cdb = [0u8; 12];
+    cdb[0] = crate::scsi::SCSI_READ_DISC_STRUCTURE;
+    // bytes 2-5: address = 0
+    cdb[6] = 0; // layer
+    cdb[7] = 0x02; // format = disc key
+    cdb[8] = (alloc_len >> 8) as u8;
+    cdb[9] = alloc_len as u8;
+    cdb[10] = agid << 6;
+
+    let mut buf = vec![0u8; alloc_len as usize];
+    let dvd_result = scsi.execute(
+        &cdb,
+        crate::scsi::DataDirection::FromDevice,
+        &mut buf,
+        5_000,
+    );
+    dvd_result.map_err(|_| Error::CssAuthFailed)?;
+
+    // Disc key block starts at offset 4 (skip 4-byte header)
+    let disc_key_block = &mut buf[4..4 + 2048];
+
+    // XOR with reversed bus key (per libdvdcss)
+    for (i, byte) in disc_key_block.iter_mut().enumerate() {
+        *byte ^= bus_key[4 - (i % 5)];
+    }
+
+    // Try each player key against each of 408 disc key entries.
+    // Each entry in the block is the disc key encrypted with a specific player
+    // key. We collect every decryption and accept the disc key as soon as two
+    // independent decryptions agree on the same 5-byte value (the agreement may
+    // come from two different player keys or from one player key decrypting two
+    // different entries to the same value).
+    //
+    // NOTE: this is a collision heuristic, not the canonical CSS disc-key
+    // self-verification (which decrypts the verification entry with the
+    // candidate and checks the result equals the candidate). A coincidental
+    // collision among the ~12,648 candidate decryptions could in principle
+    // accept a wrong disc key; in practice a chance collision on 5 bytes is
+    // improbable enough to serve as the validity check, and this path is the
+    // production DVD disc-key recovery. Left as-is to avoid regressing it
+    // without a real disc-key-block test vector to validate against.
+    let mut candidates: Vec<[u8; 5]> = Vec::new();
+
+    for player_key in PLAYER_KEYS.iter() {
+        for pos in 0..408 {
+            let offset = pos * 5;
+            if offset + 5 > disc_key_block.len() {
+                break;
+            }
+            let mut enc = [0u8; 5];
+            enc.copy_from_slice(&disc_key_block[offset..offset + 5]);
+            let candidate = super::lfsr::decrypt_key(0x00, player_key, &enc);
+
+            // Accept on the first agreement between two independent decryptions.
+            if candidates.contains(&candidate) {
+                return Ok(candidate);
+            }
+            candidates.push(candidate);
+        }
+    }
+
+    Err(Error::CssAuthFailed)
+}
+
+// ── Step 3: Title Key ─────────────────────────────────────────────────────
+
+/// Read the raw (bus-encrypted) title key bytes from the drive.
+fn read_raw_title_key(drive: &mut Drive, agid: u8, lba: u32) -> Result<[u8; 5]> {
+    let scsi = drive.scsi_mut();
+    let mut cdb = [0u8; 12];
+    cdb[0] = crate::scsi::SCSI_REPORT_KEY;
+    cdb[2] = (lba >> 24) as u8;
+    cdb[3] = (lba >> 16) as u8;
+    cdb[4] = (lba >> 8) as u8;
+    cdb[5] = lba as u8;
+    cdb[8] = 0x00;
+    cdb[9] = 0x0C;
+    cdb[10] = (agid << 6) | 0x04;
+
+    let mut buf = [0u8; 12];
+    let result = scsi.execute(
+        &cdb,
+        crate::scsi::DataDirection::FromDevice,
+        &mut buf,
+        5_000,
+    );
+    result.map_err(|_| Error::CssAuthFailed)?;
+
+    let mut key = [0u8; 5];
+    for i in 0..5 {
+        key[i] = buf[5 + (4 - i)];
+    }
+    Ok(key)
+}
+
+// ── CSSCryptKey ───────────────────────────────────────────────────────────
+
+fn crypt_key(key_type: usize, variant: u8, challenge: &[u8; 10]) -> [u8; 5] {
+    // key_type indexes PERM_CHALLENGE ([_;3]); variant indexes
+    // VARIANTS/PERM_VARIANT ([_;32]). All internal callers pass key_type in
+    // 0..3 and variant in 0..32; the asserts document the contract for the
+    // pub(crate) test entry point test_crypt_key and turn a would-be
+    // out-of-bounds panic into an explicit precondition violation.
+    debug_assert!(key_type < 3, "crypt_key: key_type out of range");
+    debug_assert!((variant as usize) < 32, "crypt_key: variant out of range");
+    let perm = &PERM_CHALLENGE[key_type];
+    let mut scratch = [0u8; 10];
+    for i in 0..10 {
+        scratch[i] = challenge[perm[i]];
+    }
+
+    let css_variant = match key_type {
+        0 => variant as usize,
+        1 => PERM_VARIANT[0][variant as usize] as usize,
+        _ => PERM_VARIANT[1][variant as usize] as usize,
+    };
+
+    let cse = VARIANTS[css_variant] ^ CRYPT_TAB2[css_variant];
+
+    let mut tmp1 = [0u8; 5];
+    for i in 0..5 {
+        tmp1[i] = scratch[5 + i] ^ SECRET[i] ^ CRYPT_TAB2[i];
+    }
+
+    let mut lfsr0: u32 = ((tmp1[0] as u32) << 17)
+        | ((tmp1[1] as u32) << 9)
+        | (((tmp1[2] as u32) & !7) << 1)
+        | 8
+        | (tmp1[2] as u32 & 7);
+
+    let mut lfsr1: u32 = ((tmp1[3] as u32) << 9) | 0x100 | (tmp1[4] as u32);
+
+    let mut bits = [0u8; 30];
+    let mut carry: u32 = 0;
+    for idx in (0..30).rev() {
+        let mut val: u8 = 0;
+        for bit in 0..8u8 {
+            let lfsr0_out = ((lfsr0 >> 24) ^ (lfsr0 >> 21) ^ (lfsr0 >> 20) ^ (lfsr0 >> 12)) & 1;
+            lfsr0 = ((lfsr0 << 1) | lfsr0_out) & 0x1FFFFFF;
+
+            let lfsr1_out = ((lfsr1 >> 16) ^ (lfsr1 >> 2)) & 1;
+            lfsr1 = ((lfsr1 << 1) | lfsr1_out) & 0x1FFFF;
+
+            let combined = ((!lfsr1_out) & 1) + carry + ((!lfsr0_out) & 1);
+            carry = (combined >> 1) & 1;
+            val |= ((combined & 1) as u8) << bit;
+        }
+        bits[idx] = val;
+    }
+
+    let mut tmp1 = [scratch[0], scratch[1], scratch[2], scratch[3], scratch[4]];
+    let mut tmp2 = [0u8; 5];
+
+    // Round 1: bits[25..29] ^ scratch -> tmp1 (term from original scratch)
+    {
+        let mut term: u8 = 0;
+        for i in (0..5usize).rev() {
+            let idx = (bits[25 + i] ^ tmp1[i]) as usize;
+            let idx2 = (CRYPT_TAB1[idx] ^ (!CRYPT_TAB2[idx]) ^ cse) as usize;
+            tmp1[i] = CRYPT_TAB2[idx2] ^ CRYPT_TAB3[idx2] ^ term;
+            term = scratch[i]; // original challenge, NOT modified tmp1
+        }
+        tmp1[4] ^= tmp1[0];
+    }
+
+    // Round 2
+    {
+        let mut term: u8 = 0;
+        for i in (0..5usize).rev() {
+            let idx = (bits[20 + i] ^ tmp1[i]) as usize;
+            let idx2 = (CRYPT_TAB1[idx] ^ (!CRYPT_TAB2[idx]) ^ cse) as usize;
+            tmp2[i] = CRYPT_TAB2[idx2] ^ CRYPT_TAB3[idx2] ^ term;
+            term = tmp1[i];
+        }
+        tmp2[4] ^= tmp2[0];
+    }
+
+    // Round 3 (uses CRYPT_TAB0)
+    {
+        let mut term: u8 = 0;
+        for i in (0..5usize).rev() {
+            let idx = (bits[15 + i] ^ tmp2[i]) as usize;
+            let idx2 = (CRYPT_TAB1[idx] ^ (!CRYPT_TAB2[idx]) ^ cse) as usize;
+            let idx3 = (CRYPT_TAB2[idx2] ^ CRYPT_TAB3[idx2] ^ term) as usize;
+            tmp1[i] = CRYPT_TAB0[idx3] ^ CRYPT_TAB2[idx3];
+            term = tmp2[i];
+        }
+        tmp1[4] ^= tmp1[0];
+    }
+
+    // Round 4 (uses CRYPT_TAB0)
+    {
+        let mut term: u8 = 0;
+        for i in (0..5usize).rev() {
+            let idx = (bits[10 + i] ^ tmp1[i]) as usize;
+            let idx2 = (CRYPT_TAB1[idx] ^ (!CRYPT_TAB2[idx]) ^ cse) as usize;
+            let idx3 = (CRYPT_TAB2[idx2] ^ CRYPT_TAB3[idx2] ^ term) as usize;
+            tmp2[i] = CRYPT_TAB0[idx3] ^ CRYPT_TAB2[idx3];
+            term = tmp1[i];
+        }
+        tmp2[4] ^= tmp2[0];
+    }
+
+    // Round 5
+    {
+        let mut term: u8 = 0;
+        for i in (0..5usize).rev() {
+            let idx = (bits[5 + i] ^ tmp2[i]) as usize;
+            let idx2 = (CRYPT_TAB1[idx] ^ (!CRYPT_TAB2[idx]) ^ cse) as usize;
+            tmp1[i] = CRYPT_TAB2[idx2] ^ CRYPT_TAB3[idx2] ^ term;
+            term = tmp2[i];
+        }
+        tmp1[4] ^= tmp1[0];
+    }
+
+    // Round 6
+    let mut key = [0u8; 5];
+    {
+        let mut term: u8 = 0;
+        for i in (0..5usize).rev() {
+            let idx = (bits[i] ^ tmp1[i]) as usize;
+            let idx2 = (CRYPT_TAB1[idx] ^ (!CRYPT_TAB2[idx]) ^ cse) as usize;
+            key[i] = CRYPT_TAB2[idx2] ^ CRYPT_TAB3[idx2] ^ term;
+            term = tmp1[i];
+        }
+    }
+
+    key
+}
+
+// ── SCSI CDB builders ────────────────────────────────────────────────────
+
+fn report_key_cdb(agid: u8, format: u8, alloc_len: u16) -> [u8; 12] {
+    let mut cdb = [0u8; 12];
+    cdb[0] = crate::scsi::SCSI_REPORT_KEY;
+    cdb[8] = (alloc_len >> 8) as u8;
+    cdb[9] = alloc_len as u8;
+    cdb[10] = (agid << 6) | (format & 0x3F);
+    cdb
+}
+
+fn send_key_cdb(agid: u8, format: u8, param_len: u16) -> [u8; 12] {
+    let mut cdb = [0u8; 12];
+    cdb[0] = crate::scsi::SCSI_SEND_KEY;
+    cdb[8] = (param_len >> 8) as u8;
+    cdb[9] = param_len as u8;
+    cdb[10] = (agid << 6) | (format & 0x3F);
+    cdb
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn crypt_key_is_deterministic() {
+        let challenge: [u8; 10] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+        for v in 0..32u8 {
+            let r1 = crypt_key(0, v, &challenge);
+            let r2 = crypt_key(0, v, &challenge);
+            assert_eq!(r1, r2);
+        }
+    }
+
+    #[test]
+    fn crypt_key_varies_by_variant() {
+        let challenge: [u8; 10] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+        assert_ne!(crypt_key(0, 0, &challenge), crypt_key(0, 1, &challenge));
+    }
+
+    #[test]
+    fn crypt_key_varies_by_type() {
+        let challenge: [u8; 10] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+        assert_ne!(crypt_key(0, 5, &challenge), crypt_key(1, 5, &challenge));
+    }
+
+    #[test]
+    fn crypt_key_nonzero() {
+        let challenge: [u8; 10] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+        for v in 0..32u8 {
+            assert_ne!(crypt_key(0, v, &challenge), [0u8; 5]);
+        }
+    }
+
+    #[test]
+    fn player_keys_count() {
+        assert_eq!(PLAYER_KEYS.len(), 31);
+    }
+}

src/css/crack.rs

@@ -0,0 +1,403 @@
+//! CSS title key recovery — Stevenson's divide-and-conquer attack (1999).
+//!
+//! Given a scrambled DVD sector with known plaintext (MPEG-2 PES headers),
+//! this would recover the 5-byte title key by:
+//!
+//! 1. Computing `TAB1[ciphertext] ^ plaintext` to cancel the TAB1 output
+//!    mangling and expose the raw LFSR-combination keystream
+//! 2. Iterating all 2^16 LFSR1 states
+//! 3. For each: deducing what LFSR0 must produce, then verifying
+//!
+//! NOTE: this recovery path is currently non-functional. It models the
+//! textbook direct-seed CSS cipher, whereas the in-repo descrambler
+//! ([`super::lfsr::descramble_sector`]) seeds its LFSRs from a key that
+//! has been run through an additional `decrypt_key` mangling step. The two
+//! are therefore inconsistent and [`recover_title_key`] never returns a key
+//! for a sector scrambled by this crate's own descrambler. The production
+//! DVD path does NOT use this fallback — it derives the title key over SCSI
+//! ([`super::auth::authenticate_and_read_title_key`]). See the ignored
+//! regression test below.
+//!
+//! Algorithm: Frank A. Stevenson, "Divide and conquer attack" (1999).
+
+use super::tables::{TAB1, TAB2, TAB3, TAB4, TAB5};
+
+/// Sector layout constants.
+const SECTOR_SIZE: usize = 2048;
+const ENCRYPTED_START: usize = 0x80; // byte 128
+const SEED_OFFSET: usize = 0x54; // sector seed at bytes 0x54-0x58
+const FLAG_BYTE: usize = 0x14;
+
+/// Recover the CSS title key from a scrambled sector using known plaintext.
+///
+/// The `plain` slice should contain the expected plaintext of the encrypted
+/// region (bytes 0x80+). For MPEG-2 sectors, the first bytes are typically
+/// a PES header: `00 00 01 [stream_id] ...`
+///
+/// Returns the recovered 5-byte title key, or `None` if recovery fails.
+///
+/// NOTE: see the module docs — this attack models the textbook direct-seed
+/// CSS cipher and is inconsistent with this crate's descrambler, so it
+/// currently returns `None` even for an exact known plaintext. It is not on
+/// the production DVD decrypt path.
+pub fn recover_title_key(sector: &[u8], plain: &[u8]) -> Option<[u8; 5]> {
+    if sector.len() < SECTOR_SIZE || plain.len() < 10 {
+        return None;
+    }
+
+    let flags = (sector[FLAG_BYTE] >> 4) & 0x03;
+    if flags == 0 {
+        return None;
+    }
+
+    let crypted = &sector[ENCRYPTED_START..];
+    let seed = &sector[SEED_OFFSET..SEED_OFFSET + 5];
+
+    // Phase 1: Cancel the TAB1 mangling layer and subtract the known plaintext.
+    // The CSS cipher applies TAB1 as an output permutation. Computing
+    // `buf[i] = TAB1[crypted[i]] ^ plain[i]` both undoes that permutation and
+    // XORs out the known plaintext, leaving the raw LFSR-combination keystream
+    // bytes for the attack to match against.
+    let mut buf = [0u8; 10];
+    for i in 0..10 {
+        if i >= crypted.len() || i >= plain.len() {
+            return None;
+        }
+        buf[i] = TAB1[crypted[i] as usize] ^ plain[i];
+    }
+
+    // Phase 2: Stevenson attack — iterate all 2^16 LFSR1 initial states
+    let mut result_key = [0u8; 5];
+    let mut found = false;
+
+    'outer: for i_try in 0u32..0x10000 {
+        let mut t1 = (i_try >> 8) | 0x100;
+        let mut t2 = i_try & 0xFF;
+        let mut t5: u32 = 0;
+
+        // Clock LFSR1 forward 4 steps to reconstruct LFSR0 state
+        let mut t3: u32 = 0;
+
+        for &buf_byte in buf.iter().take(4) {
+            // Advance LFSR1
+            let t4 = TAB2[t2 as usize] ^ TAB3[t1 as usize];
+            t2 = t1 >> 1;
+            t1 = ((t1 & 1) << 8) ^ t4 as u32;
+            let t4_perm = TAB5[t4 as usize];
+
+            // Deduce LFSR0 output from the buffer and LFSR1 output
+            let mut t6 = buf_byte as u32;
+            if t5 > 0 {
+                t6 = (t6 + 0xFF) & 0xFF;
+            }
+            if t6 < t4_perm as u32 {
+                t6 += 0x100;
+            }
+            t6 -= t4_perm as u32;
+            t5 += t6 + t4_perm as u32;
+            let t6_inv = TAB4[t6 as usize & 0xFF];
+
+            // Build LFSR0 candidate from deduced output bytes.
+            // wrapping_shl: the accumulator is a rolling 32-bit window;
+            // the top byte is intentionally shifted out. Matches the
+            // release-mode wrap (no behaviour change) without a debug
+            // overflow panic.
+            t3 = t3.wrapping_shl(8) | t6_inv as u32;
+            t5 >>= 8;
+        }
+
+        let candidate = t3;
+
+        // Phase 3: Validate — clock 6 more steps and check against buffer
+        let mut valid = true;
+        for &buf_byte in buf.iter().skip(4) {
+            let t4 = TAB2[t2 as usize] ^ TAB3[t1 as usize];
+            t2 = t1 >> 1;
+            t1 = ((t1 & 1) << 8) ^ t4 as u32;
+            let t4_perm = TAB5[t4 as usize];
+
+            // Clock LFSR0 forward. wrapping_shl keeps the rolling 32-bit
+            // window semantics (top byte shifted out) identical to the
+            // release build while avoiding a debug overflow panic.
+            let t6 = ((((((t3 >> 8) ^ t3) >> 1) ^ t3) >> 3) ^ t3) >> 7;
+            t3 = t3.wrapping_shl(8) | (t6 & 0xFF);
+            let t6_perm = TAB4[(t6 & 0xFF) as usize];
+
+            t5 += t6_perm as u32 + t4_perm as u32;
+            if (t5 & 0xFF) as u8 != buf_byte {
+                valid = false;
+                break;
+            }
+            t5 >>= 8;
+        }
+
+        if !valid {
+            continue;
+        }
+
+        // Phase 4: Recover the initial LFSR0 state from the candidate
+        t3 = candidate;
+        let mut recovery_ok = true;
+        for _ in 0..4 {
+            let t1_byte = t3 & 0xFF;
+            t3 >>= 8;
+            // Brute-force the byte that was shifted in
+            let mut found_j = false;
+            for j in 0u32..256 {
+                t3 = (t3 & 0x1FFFF) | (j << 17);
+                let t6 = ((((((t3 >> 8) ^ t3) >> 1) ^ t3) >> 3) ^ t3) >> 7;
+                if (t6 & 0xFF) == t1_byte {
+                    found_j = true;
+                    break;
+                }
+            }
+            if !found_j {
+                recovery_ok = false;
+                break;
+            }
+        }
+        if !recovery_ok {
+            continue 'outer;
+        }
+
+        // Convert LFSR0 initial state back to key bytes
+        let t4 = (t3 >> 1).wrapping_sub(4);
+        for t5_off in 0u32..8 {
+            let val = t4.wrapping_add(t5_off);
+            // Reconstruction probe: val can sit near u32::MAX, so the
+            // (val*2 + 8 - (val & 7)) expression must wrap rather than
+            // panic in debug. wrapping_* reproduces the release result
+            // exactly (the comparison against t3 is unaffected).
+            if val.wrapping_mul(2).wrapping_add(8).wrapping_sub(val & 7) == t3 {
+                result_key[0] = (i_try >> 8) as u8;
+                result_key[1] = (i_try & 0xFF) as u8;
+                result_key[2] = (val & 0xFF) as u8;
+                result_key[3] = ((val >> 8) & 0xFF) as u8;
+                result_key[4] = ((val >> 16) & 0xFF) as u8;
+                found = true;
+                break;
+            }
+        }
+        if found {
+            break;
+        }
+    }
+
+    if !found {
+        return None;
+    }
+
+    // XOR with sector seed to get the actual title key
+    result_key[0] ^= seed[0];
+    result_key[1] ^= seed[1];
+    result_key[2] ^= seed[2];
+    result_key[3] ^= seed[3];
+    result_key[4] ^= seed[4];
+
+    Some(result_key)
+}
+
+/// Crack the CSS title key from an encrypted sector using an MPEG-2
+/// pattern attack.
+///
+/// Detects the PES header pattern at byte 0x80 and uses it as known
+/// plaintext. This is a best-effort fallback for the SCSI auth path
+/// (see [`super::resolve`]): it only succeeds on a sector whose
+/// encrypted region begins with one of the tried PES header patterns,
+/// and returns `None` otherwise. The production DVD path obtains the
+/// title key via drive authentication, not cracking.
+pub fn crack_title_key(sector: &[u8]) -> Option<[u8; 5]> {
+    if sector.len() < SECTOR_SIZE {
+        return None;
+    }
+
+    let flags = (sector[FLAG_BYTE] >> 4) & 0x03;
+    if flags == 0 {
+        return None;
+    }
+
+    // The PES header at byte 0x80 typically starts with 00 00 01 [stream_id].
+    // The next bytes are PES length and flags. We need at least 10 bytes of
+    // known plaintext for the Stevenson attack.
+    //
+    // Strategy: try common PES patterns. The first 3 bytes are always 00 00 01.
+    // The stream_id varies. Bytes 4-9 depend on PES header structure.
+    //
+    // For a standard PES with PTS:
+    //   00 00 01 [id] [len_hi] [len_lo] [flags] [flags2] [hdr_len] [PTS...]
+    //
+    // We try multiple stream IDs and use zeros for unknown bytes (most common).
+
+    // Try many PES header patterns at byte 0x80.
+    // Structure: 00 00 01 [stream_id] [len_hi] [len_lo] [flags1] [flags2] [hdr_len] [data]
+    // 24 padding-stream + 144 video/audio + 1 navigation = 169 patterns.
+    let mut patterns: Vec<[u8; 10]> = Vec::with_capacity(169);
+
+    // Padding stream (0xBE): payload is 0xFF bytes, various lengths
+    for len_hi in 0u8..8 {
+        for len_lo_top in [0x00u8, 0x80, 0xFF] {
+            patterns.push([
+                0x00, 0x00, 0x01, 0xBE, len_hi, len_lo_top, 0xFF, 0xFF, 0xFF, 0xFF,
+            ]);
+        }
+    }
+
+    // Video (0xE0) and audio (0xBD, 0xC0) with typical PES headers
+    for &sid in &[0xE0u8, 0xBD, 0xC0] {
+        for &flags1 in &[0x80u8, 0x81, 0x84, 0x85, 0x8C, 0x8D] {
+            for &flags2 in &[0x00u8, 0x05, 0x80, 0xC0] {
+                let hdr_len = if flags2 & 0x80 != 0 { 0x05u8 } else { 0x00 };
+                let pts0 = if flags2 & 0x80 != 0 { 0x21u8 } else { 0x00 };
+                // Try with several PES lengths
+                for &len_hi in &[0x00u8, 0x07] {
+                    patterns.push([
+                        0x00, 0x00, 0x01, sid, len_hi, 0x00, flags1, flags2, hdr_len, pts0,
+                    ]);
+                }
+            }
+        }
+    }
+
+    // Navigation pack system header (0xBB)
+    patterns.push([0x00, 0x00, 0x01, 0xBB, 0x00, 0x12, 0x80, 0xC4, 0xE1, 0x04]);
+
+    for pattern in &patterns {
+        if let Some(key) = recover_title_key(sector, pattern) {
+            let mut test = sector.to_vec();
+            super::lfsr::descramble_sector(&key, &mut test);
+            if test[0x80] == 0x00 && test[0x81] == 0x00 && test[0x82] == 0x01 {
+                return Some(key);
+            }
+        }
+    }
+
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn crack_unscrambled_returns_none() {
+        let sector = vec![0u8; 2048];
+        assert!(crack_title_key(&sector).is_none());
+    }
+
+    /// Regression: the LFSR0 reconstruction arithmetic must not overflow
+    /// (panic) in a debug build for scrambled sector content. Exercises
+    /// the full 2^16 Stevenson search via recover_title_key directly (the
+    /// overflow site), with the assertion simply that it does not panic.
+    /// recover_title_key is used rather than crack_title_key to avoid
+    /// re-running the search for all 169 PES patterns.
+    #[test]
+    fn crack_scrambled_sectors_never_overflow() {
+        for seed in 0u32..4 {
+            let mut sector = vec![0u8; SECTOR_SIZE];
+            sector[FLAG_BYTE] = 0x30; // scramble flag set
+            let mut x = seed.wrapping_mul(2_654_435_761).wrapping_add(1);
+            for b in sector.iter_mut().skip(0x80) {
+                x = x.wrapping_mul(1_103_515_245).wrapping_add(12_345);
+                *b = (x >> 16) as u8;
+            }
+            for (i, b) in sector[SEED_OFFSET..SEED_OFFSET + 5].iter_mut().enumerate() {
+                *b = seed.wrapping_add(i as u32) as u8;
+            }
+            let plain = [0x00u8, 0x00, 0x01, 0xE0, 0x00, 0x00, 0x80, 0x80, 0x05, 0x21];
+            let _ = recover_title_key(&sector, &plain);
+        }
+    }
+
+    #[test]
+    fn crack_too_short_returns_none() {
+        let sector = vec![0u8; 100];
+        assert!(crack_title_key(&sector).is_none());
+    }
+
+    #[test]
+    fn recover_needs_10_bytes_plain() {
+        let sector = vec![0u8; 2048];
+        let short_plain = [0u8; 5];
+        assert!(recover_title_key(&sector, &short_plain).is_none());
+    }
+
+    /// Build a scrambled sector with known plaintext (both an MPEG PES header
+    /// at 0x80 and an exact-plaintext probe), then assert that the Stevenson
+    /// recovery actually recovers a key whose descramble round-trips the body.
+    ///
+    /// This is the regression gate for the CSS crack/recover path. It is
+    /// `#[ignore]`d because that path is currently non-functional: the
+    /// recovery models the textbook direct-seed cipher, whereas this crate's
+    /// [`descramble_sector`] seeds from a `decrypt_key`-mangled key, so the
+    /// two are inconsistent and recovery returns `None`. When the crack
+    /// algorithm is re-derived against this crate's actual descrambler, this
+    /// test must pass with `--ignored` removed. The production DVD path does
+    /// not use crack/recover (it authenticates over SCSI), so the broken
+    /// fallback does not affect shipped behavior.
+    #[test]
+    #[ignore = "CSS crack/recover path is non-functional vs this crate's descrambler; \
+                see module docs. Regression gate for a future fix."]
+    fn css_crack_recovers_key_from_scrambled_sector() {
+        use super::super::lfsr::descramble_sector;
+
+        let title_key: [u8; 5] = [0x42, 0x13, 0x37, 0xBE, 0xEF];
+
+        // Build a plaintext MPEG-2 sector
+        let mut plaintext = vec![0x00u8; SECTOR_SIZE];
+
+        // Pack header at byte 0: 00 00 01 BA
+        plaintext[0] = 0x00;
+        plaintext[1] = 0x00;
+        plaintext[2] = 0x01;
+        plaintext[3] = 0xBA;
+
+        // Scramble flag at byte 0x14
+        plaintext[FLAG_BYTE] = 0x30;
+
+        // Sector seed at bytes 0x54-0x58
+        plaintext[SEED_OFFSET..SEED_OFFSET + 5].copy_from_slice(&[0x11, 0x22, 0x33, 0x44, 0x55]);
+
+        // PES header at byte 0x80: 00 00 01 E0 (video stream) with PTS.
+        let exact_plain: [u8; 10] = [0x00, 0x00, 0x01, 0xE0, 0x00, 0x00, 0x80, 0x80, 0x05, 0x21];
+        plaintext[0x80..0x80 + 10].copy_from_slice(&exact_plain);
+
+        let original_plaintext = plaintext.clone();
+
+        // "Scramble" the sector by XORing the keystream over the plaintext.
+        descramble_sector(&title_key, &mut plaintext);
+
+        // descramble_sector cleared the flag; restore it so the cracker sees
+        // the sector as encrypted.
+        plaintext[FLAG_BYTE] = 0x30;
+
+        // 1) Pattern-guessing entry point must recover a key.
+        let cracked = crack_title_key(&plaintext);
+        assert!(
+            cracked.is_some(),
+            "crack_title_key returned None for a sector scrambled with a known key"
+        );
+        let cracked = cracked.unwrap();
+        let mut body = plaintext.clone();
+        descramble_sector(&cracked, &mut body);
+        assert_eq!(
+            &body[0x80..SECTOR_SIZE],
+            &original_plaintext[0x80..SECTOR_SIZE],
+            "crack_title_key key did not round-trip the body"
+        );
+
+        // 2) Exact known plaintext must also recover a round-tripping key.
+        let recovered = recover_title_key(&plaintext, &exact_plain);
+        assert!(
+            recovered.is_some(),
+            "recover_title_key returned None for exact known plaintext"
+        );
+        let recovered = recovered.unwrap();
+        let mut body2 = plaintext.clone();
+        descramble_sector(&recovered, &mut body2);
+        assert_eq!(
+            &body2[0x80..SECTOR_SIZE],
+            &original_plaintext[0x80..SECTOR_SIZE],
+            "recover_title_key key did not round-trip the body"
+        );
+    }
+}

src/css/lfsr.rs

@@ -0,0 +1,360 @@
+//! CSS cipher implementation based on the Stevenson 1999 analysis.
+//!
+//! The CSS cipher uses two table-driven feedback circuits:
+//! - LFSR1: 17-bit state (9-bit lo + 8-bit hi register, seeded from
+//!   key[0..2]), driven by TAB2/TAB3
+//! - LFSR0: 32-bit state, driven by a feedback polynomial through TAB4
+//!
+//! The keystream is the bytewise sum (with carry) of both LFSR outputs.
+//! Content descrambling XORs this keystream with the encrypted sector data.
+//!
+//! Algorithm: Frank A. Stevenson's divide-and-conquer attack (1999).
+//! Tables: CSS specification constants.
+
+use super::tables::{TAB1, TAB2, TAB3, TAB4, TAB5};
+
+/// Seed the 32-bit LFSR0 register from the 5-byte working key, applying
+/// the per-byte TAB4 bit-reversal. Shared by [`descramble_sector`] and
+/// [`decrypt_key`] so the seeding lives in one place.
+#[inline]
+fn seed_lfsr0(key: &[u8; 5]) -> u32 {
+    let lfsr0: u32 = ((key[4] as u32) << 17)
+        | ((key[3] as u32) << 9)
+        | (((key[2] as u32) << 1) + 8 - (key[2] as u32 & 7));
+    (TAB4[(lfsr0 & 0xFF) as usize] as u32) << 24
+        | (TAB4[((lfsr0 >> 8) & 0xFF) as usize] as u32) << 16
+        | (TAB4[((lfsr0 >> 16) & 0xFF) as usize] as u32) << 8
+        | TAB4[((lfsr0 >> 24) & 0xFF) as usize] as u32
+}
+
+/// One CSS keystream step. Advances both LFSRs, folds their permuted
+/// outputs into `combined` (carry kept across calls), and returns the
+/// low keystream byte. `invert` XORs the LFSR0 output index (0x00 on the
+/// descramble path, 0xFF on the key-decrypt path).
+#[inline]
+fn css_step(
+    lfsr1_lo: &mut u32,
+    lfsr1_hi: &mut u32,
+    lfsr0: &mut u32,
+    combined: &mut u32,
+    invert: u8,
+) -> u8 {
+    let o_lfsr1 = TAB2[*lfsr1_hi as usize] ^ TAB3[*lfsr1_lo as usize];
+    *lfsr1_hi = *lfsr1_lo >> 1;
+    *lfsr1_lo = ((*lfsr1_lo & 1) << 8) ^ o_lfsr1 as u32;
+
+    let o_lfsr0 = (((((((*lfsr0 >> 8) ^ *lfsr0) >> 1) ^ *lfsr0) >> 3) ^ *lfsr0) >> 7) as u8;
+    *lfsr0 = (*lfsr0 >> 8) | ((o_lfsr0 as u32) << 24);
+
+    *combined += TAB5[o_lfsr1 as usize] as u32 + TAB4[(o_lfsr0 ^ invert) as usize] as u32;
+    let out = (*combined & 0xFF) as u8;
+    *combined >>= 8;
+    out
+}
+
+/// Descramble a CSS-encrypted DVD sector in place.
+///
+/// The sector seed (bytes 0x54-0x58) is XORed with the title key to produce
+/// the per-sector key. Bytes 0x80..0x800 (128..2048) are then decrypted
+/// using the two-LFSR keystream.
+///
+/// The scramble flag at byte 0x14 (bits 4-5) indicates encryption.
+/// After descrambling, the flag is cleared.
+///
+/// No-op (returns without modifying `sector`) in two cases:
+/// - `sector.len() < 2048`: the encrypted region (0x80..0x800) is not
+///   fully present. Callers chunk by 2048, so a trailing partial chunk is
+///   left untouched. The `debug_assert!` flags this misuse in debug/test
+///   builds; a DVD sector is always exactly 2048 bytes.
+/// - scramble flags are zero: the sector is not CSS-encrypted.
+pub fn descramble_sector(title_key: &[u8; 5], sector: &mut [u8]) {
+    debug_assert!(
+        sector.len() >= 2048,
+        "descramble_sector: buffer shorter than one 2048-byte sector"
+    );
+    if sector.len() < 2048 {
+        return;
+    }
+
+    let flags = (sector[0x14] >> 4) & 0x03;
+    if flags == 0 {
+        return;
+    }
+
+    // Per-sector key = title_key XOR sector_seed (bytes 0x54-0x58)
+    let key = [
+        title_key[0] ^ sector[0x54],
+        title_key[1] ^ sector[0x55],
+        title_key[2] ^ sector[0x56],
+        title_key[3] ^ sector[0x57],
+        title_key[4] ^ sector[0x58],
+    ];
+
+    // Decrypt the key through the CSS mangling function to get the working key.
+    // The sector seed is bytes 0x54..0x59 (5 bytes).
+    let seed: [u8; 5] = [
+        sector[0x54],
+        sector[0x55],
+        sector[0x56],
+        sector[0x57],
+        sector[0x58],
+    ];
+    let working_key = decrypt_key(0xFF, &key, &seed);
+
+    // Generate keystream and XOR with encrypted region
+    let mut lfsr1_lo: u32 = working_key[0] as u32 | 0x100;
+    let mut lfsr1_hi: u32 = working_key[1] as u32;
+    let mut lfsr0: u32 = seed_lfsr0(&working_key);
+
+    let mut combined: u32 = 0;
+
+    // Generate 1920 keystream bytes (for sector bytes 128..2048) and XOR them
+    // into the encrypted region. Each keystream byte is the carrying sum of the
+    // TAB5-permuted LFSR1 output and the TAB4-permuted LFSR0 output. No TAB1
+    // permutation is applied to the ciphertext here (TAB1 is only used inside
+    // decrypt_key); the working key was already produced by decrypt_key above,
+    // so this keystream is paired with that mangling step, not a plain
+    // direct-seed unscramble. No invert is applied on the LFSR0 output.
+    for byte in sector.iter_mut().take(2048).skip(128) {
+        let ks = css_step(
+            &mut lfsr1_lo,
+            &mut lfsr1_hi,
+            &mut lfsr0,
+            &mut combined,
+            0x00,
+        );
+        *byte ^= ks;
+    }
+
+    // Clear scramble flags
+    sector[0x14] &= 0xCF;
+}
+
+/// CSS key decryption / mangling function.
+///
+/// Decrypts `p_crypted` using `p_key` with the CSS two-LFSR cipher.
+/// The `invert` parameter controls the XOR applied to LFSR0 output
+/// (0x00 for disc key decryption, 0xFF for title key / sector key).
+pub(crate) fn decrypt_key(invert: u8, p_key: &[u8; 5], p_crypted: &[u8; 5]) -> [u8; 5] {
+    let mut lfsr1_lo: u32 = p_key[0] as u32 | 0x100;
+    let mut lfsr1_hi: u32 = p_key[1] as u32;
+    let mut lfsr0: u32 = seed_lfsr0(p_key);
+
+    let mut combined: u32 = 0;
+    let mut k = [0u8; 5];
+
+    // TAB5 for LFSR1 output, TAB4 for LFSR0^invert (per libdvdcss css_DecryptKey).
+    for byte in &mut k {
+        *byte = css_step(
+            &mut lfsr1_lo,
+            &mut lfsr1_hi,
+            &mut lfsr0,
+            &mut combined,
+            invert,
+        );
+    }
+
+    // Two rounds of chained XOR through TAB1
+    let mut result = [0u8; 5];
+    result[4] = k[4] ^ TAB1[p_crypted[4] as usize] ^ p_crypted[3];
+    result[3] = k[3] ^ TAB1[p_crypted[3] as usize] ^ p_crypted[2];
+    result[2] = k[2] ^ TAB1[p_crypted[2] as usize] ^ p_crypted[1];
+    result[1] = k[1] ^ TAB1[p_crypted[1] as usize] ^ p_crypted[0];
+    result[0] = k[0] ^ TAB1[p_crypted[0] as usize] ^ result[4];
+
+    result[4] = k[4] ^ TAB1[result[4] as usize] ^ result[3];
+    result[3] = k[3] ^ TAB1[result[3] as usize] ^ result[2];
+    result[2] = k[2] ^ TAB1[result[2] as usize] ^ result[1];
+    result[1] = k[1] ^ TAB1[result[1] as usize] ^ result[0];
+    result[0] = k[0] ^ TAB1[result[0] as usize];
+
+    result
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn descramble_skips_unscrambled() {
+        let key = [0x01, 0x02, 0x03, 0x04, 0x05];
+        let mut sector = vec![0xAA; 2048];
+        sector[0x14] = 0x00;
+        let original = sector.clone();
+        descramble_sector(&key, &mut sector);
+        assert_eq!(sector, original);
+    }
+
+    #[test]
+    fn descramble_modifies_scrambled() {
+        let key = [0x01, 0x02, 0x03, 0x04, 0x05];
+        let mut sector = vec![0xAA; 2048];
+        sector[0x14] = 0x30; // scramble flag set
+        // Set a sector seed
+        sector[0x54..0x59].copy_from_slice(&[0x11, 0x22, 0x33, 0x44, 0x55]);
+        let original = sector.clone();
+        descramble_sector(&key, &mut sector);
+        // Header (0..128) unchanged except byte 0x14 (flag cleared)
+        for i in 0..128 {
+            if i == 0x14 {
+                continue;
+            }
+            assert_eq!(sector[i], original[i], "header byte {} changed", i);
+        }
+        // Encrypted region should be different
+        assert_ne!(&sector[128..256], &original[128..256]);
+    }
+
+    #[test]
+    fn descramble_clears_flags() {
+        let key = [0x01, 0x02, 0x03, 0x04, 0x05];
+        let mut sector = vec![0x00; 2048];
+        sector[0x14] = 0x30;
+        sector[0x54..0x59].copy_from_slice(&[0x00; 5]);
+        descramble_sector(&key, &mut sector);
+        assert_eq!(sector[0x14] & 0x30, 0x00);
+    }
+
+    #[test]
+    fn decrypt_key_produces_output() {
+        let key = [0x12, 0x34, 0x56, 0x78, 0x9A];
+        let crypted = [0xAB, 0xCD, 0xEF, 0x01, 0x23];
+        let result = decrypt_key(0xFF, &key, &crypted);
+        // Should produce a 5-byte result different from input
+        assert_ne!(result, key);
+        assert_ne!(result, [0u8; 5]);
+    }
+
+    /// css_decrypt_key_roundtrip
+    ///
+    /// decrypt_key is not a simple encrypt/decrypt pair — it is a one-way mangling
+    /// function. However, we can verify consistency: calling it twice with the same
+    /// parameters produces the same output, and varying the invert byte changes
+    /// the LFSR0 contribution predictably.
+    #[test]
+    fn css_decrypt_key_roundtrip() {
+        let keys: &[[u8; 5]] = &[
+            [0x12, 0x34, 0x56, 0x78, 0x9A],
+            [0x00, 0x00, 0x00, 0x00, 0x00],
+            [0xFF, 0xFF, 0xFF, 0xFF, 0xFF],
+            [0xAB, 0xCD, 0xEF, 0x01, 0x23],
+        ];
+        let crypted_inputs: &[[u8; 5]] = &[
+            [0x11, 0x22, 0x33, 0x44, 0x55],
+            [0xAA, 0xBB, 0xCC, 0xDD, 0xEE],
+            [0x00, 0x00, 0x00, 0x00, 0x00],
+        ];
+
+        for key in keys {
+            for crypted in crypted_inputs {
+                // decrypt_key with invert=0x00 and invert=0xFF should give different results
+                let r0 = decrypt_key(0x00, key, crypted);
+                let rff = decrypt_key(0xFF, key, crypted);
+
+                // The two results differ because the invert byte XORs the LFSR0 output
+                // They should not be equal (except by extreme coincidence)
+                // More importantly, both should be deterministic
+                let r0_again = decrypt_key(0x00, key, crypted);
+                let rff_again = decrypt_key(0xFF, key, crypted);
+                assert_eq!(r0, r0_again, "decrypt_key(0x00) not deterministic");
+                assert_eq!(rff, rff_again, "decrypt_key(0xFF) not deterministic");
+
+                // With different invert values, the keystream differs
+                assert_ne!(
+                    r0, rff,
+                    "invert=0x00 and 0xFF gave same result for key {:?}",
+                    key
+                );
+            }
+        }
+    }
+
+    /// Test 2: descramble_modifies_encrypted_region
+    ///
+    /// descramble_sector XORs a keystream into bytes 128..2048. The keystream
+    /// depends only on (title_key, sector_seed), so applying descramble twice
+    /// with the scramble flag restored between calls re-XORs the same keystream
+    /// and restores the original encrypted region — the keystream XOR is its
+    /// own inverse. This pins the cipher's involution property over the body.
+    #[test]
+    fn css_descramble_modifies_encrypted_region() {
+        let title_key = [0x42, 0x13, 0x37, 0xBE, 0xEF];
+
+        let mut sector = vec![0xAAu8; 2048];
+        sector[0x14] = 0x30; // scramble flag
+        sector[0x54..0x59].copy_from_slice(&[0xDE, 0xAD, 0xBE, 0xEF, 0x42]);
+
+        let original = sector.clone();
+        descramble_sector(&title_key, &mut sector);
+
+        // Flag cleared
+        assert_eq!(sector[0x14] & 0x30, 0x00);
+        // Header (0..128) unchanged except flag byte
+        for i in 0..128 {
+            if i == 0x14 {
+                continue;
+            }
+            assert_eq!(sector[i], original[i], "header byte {} changed", i);
+        }
+        // Encrypted region modified
+        assert_ne!(&sector[128..256], &original[128..256]);
+
+        // Round-trip: restore the scramble flag and descramble again. The same
+        // keystream is regenerated (it depends only on title_key + seed, both
+        // unchanged), so the body is restored to its original bytes.
+        sector[0x14] = 0x30;
+        descramble_sector(&title_key, &mut sector);
+        assert_eq!(
+            &sector[128..2048],
+            &original[128..2048],
+            "double descramble did not restore the encrypted region"
+        );
+    }
+
+    /// css_tab1_relationship
+    ///
+    /// Verify the structure of TAB1: it is a substitution table used in
+    /// key mangling. Check that no two inputs map to the same output
+    /// (TAB1 is a permutation of 0..255).
+    #[test]
+    fn css_tab1_is_permutation() {
+        let mut seen = [false; 256];
+        for tab1_val in &TAB1 {
+            let v = *tab1_val as usize;
+            assert!(!seen[v], "TAB1 maps two inputs to {:#04x}", v);
+            seen[v] = true;
+        }
+        // Check involution property: TAB1[TAB1[x]] should map back predictably
+        // TAB1 is not necessarily a strict involution, but we verify the
+        // composition TAB1[TAB1[x]] is also a permutation
+        let mut seen2 = [false; 256];
+        for i in 0..256 {
+            let v = TAB1[TAB1[i] as usize] as usize;
+            assert!(!seen2[v], "TAB1[TAB1[x]] maps two inputs to {:#04x}", v);
+            seen2[v] = true;
+        }
+    }
+
+    /// css_tab4_is_bit_reversal
+    ///
+    /// TAB4 reverses the bits of each byte: TAB4[0x01] = 0x80, TAB4[0x80] = 0x01, etc.
+    #[test]
+    fn css_tab4_is_bit_reversal() {
+        for i in 0u16..256 {
+            let expected = (0..8).fold(0u8, |acc, bit| acc | (((i as u8 >> bit) & 1) << (7 - bit)));
+            assert_eq!(
+                TAB4[i as usize], expected,
+                "TAB4[{:#04x}] = {:#04x}, expected {:#04x} (bit reversal)",
+                i, TAB4[i as usize], expected
+            );
+        }
+        // Also verify TAB4 is an involution: TAB4[TAB4[x]] == x
+        for i in 0..256 {
+            assert_eq!(
+                TAB4[TAB4[i] as usize], i as u8,
+                "TAB4 is not an involution at {:#04x}",
+                i
+            );
+        }
+    }
+}

src/css/mod.rs

@@ -0,0 +1,134 @@
+//! CSS (Content Scramble System) — DVD disc encryption.
+//!
+//! CSS uses a weak 40-bit LFSR stream cipher (broken since 1999).
+//!
+//! The production entry point is [`resolve`]. Two title-key acquisition
+//! paths exist behind it:
+//! - The SCSI auth path drives bus authentication with the compiled-in CSS
+//!   player keys and reads the title key from the drive (the production DVD
+//!   path on a live drive).
+//! - The crack fallback ([`crack_key`]) needs no keys — it attempts the
+//!   Stevenson known-plaintext attack on MPEG-2 PES headers. (Currently
+//!   non-functional; see the `crack` module docs.)
+//!
+//! Usage:
+//! ```rust,ignore
+//! if let Some(state) = css::resolve(&mut ctx) {
+//!     css::descramble_sector(&state, &mut sector);
+//! }
+//! ```
+
+pub mod auth;
+pub mod crack;
+pub mod lfsr;
+pub(crate) mod tables;
+
+use crate::disc::Extent;
+use crate::drive::Drive;
+use crate::sector::SectorSource;
+
+/// CSS decryption state for a DVD title.
+#[derive(Debug, Clone)]
+pub struct CssState {
+    /// 5-byte CSS title key (from SCSI auth or the crack fallback).
+    pub title_key: [u8; 5],
+}
+
+/// Inputs for CSS key acquisition.
+///
+/// The acquisition path depends on which inputs the caller supplies:
+///
+/// - With `drive` + `auth_lba` set, [`resolve`] runs the full SCSI bus
+///   auth + title-key path (live BU40N / DVD drive).
+/// - With `reader` + `extents` set, [`resolve`] falls back to the
+///   crack path (Stevenson known-plaintext attack on encrypted PES
+///   headers; works on disc images and on drives whose CSS auth path
+///   is unavailable).
+///
+/// The `drive` (auth) path always wins when both modes are populated.
+pub struct CssContext<'a> {
+    /// Live SCSI drive — when present, [`resolve`] tries the auth path.
+    pub drive: Option<&'a mut Drive>,
+    /// LBA of a known-scrambled sector for the auth path's title-key
+    /// query. Required when `drive` is set.
+    pub auth_lba: Option<u32>,
+    /// Sector source for the crack path.
+    pub reader: Option<&'a mut dyn SectorSource>,
+    /// Extents to scan for the crack path. Required when `reader` is
+    /// set.
+    pub extents: Option<&'a [Extent]>,
+}
+
+/// Acquire a CSS title key using whichever inputs the context provides.
+///
+/// Order of attempts:
+///   1. SCSI auth path (when `drive` and `auth_lba` are set).
+///   2. Crack path (when `reader` and `extents` are set).
+///
+/// Returns `None` if neither path is configured or both fail.
+pub fn resolve(ctx: &mut CssContext<'_>) -> Option<CssState> {
+    if let (Some(drive), Some(lba)) = (ctx.drive.as_deref_mut(), ctx.auth_lba) {
+        if let Ok(title_key) = auth::authenticate_and_read_title_key(drive, lba) {
+            return Some(CssState { title_key });
+        }
+    }
+    if let (Some(reader), Some(extents)) = (ctx.reader.as_deref_mut(), ctx.extents) {
+        return crack_key(reader, extents);
+    }
+    None
+}
+
+/// Crack the CSS title key by scanning scrambled sectors across extents and
+/// applying a known-plaintext attack on MPEG-2 PES headers.
+///
+/// The Stevenson attack needs a sector where a PES header starts at byte
+/// 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.
+///
+/// NOTE: the underlying recovery ([`crack::recover_title_key`]) is currently
+/// non-functional against this crate's descrambler (see `crack` module
+/// docs), so this scan returns `None`. The production DVD path uses the SCSI
+/// auth path, not this crack fallback.
+pub fn crack_key(reader: &mut dyn SectorSource, extents: &[Extent]) -> Option<CssState> {
+    let mut tried = 0u32;
+    let max_tries = 50_000;
+
+    // Reused across every scanned sector; read_sectors overwrites all 2048
+    // bytes on success, so no re-zeroing is needed between iterations.
+    let mut buf = vec![0u8; 2048];
+
+    for ext in extents {
+        let mut i = 0;
+        while i < ext.sector_count && tried < max_tries {
+            // Every scanned sector counts toward the cap, so a long run
+            // of unscrambled sectors can't read past the budget.
+            tried += 1;
+            if reader
+                .read_sectors(ext.start_lba + i, 1, &mut buf, true)
+                .is_ok()
+                && is_scrambled(&buf)
+            {
+                if let Some(key) = crack::crack_title_key(&buf) {
+                    return Some(CssState { title_key: key });
+                }
+            }
+            i += 1;
+        }
+        if tried >= max_tries {
+            break;
+        }
+    }
+
+    None
+}
+
+/// Descramble a single CSS-encrypted sector in place.
+pub fn descramble_sector(state: &CssState, sector: &mut [u8]) {
+    lfsr::descramble_sector(&state.title_key, sector);
+}
+
+/// Check if a sector has the CSS scramble flag set.
+pub fn is_scrambled(sector: &[u8]) -> bool {
+    sector.len() >= 2048 && (sector[0x14] >> 4) & 0x03 != 0
+}

src/css/tables.rs

@@ -0,0 +1,145 @@
+//! CSS specification tables — mathematical constants defining the cipher.
+//!
+//! These 5 tables are the fixed permutations and substitutions of the
+//! Content Scramble System. They are mathematical constants derived from
+//! the CSS specification, published in academic literature since 1999.
+
+/// Table 1: byte substitution used in key mangling and sector seed processing.
+pub const TAB1: [u8; 256] = [
+    0x33, 0x73, 0x3b, 0x26, 0x63, 0x23, 0x6b, 0x76, 0x3e, 0x7e, 0x36, 0x2b, 0x6e, 0x2e, 0x66, 0x7b,
+    0xd3, 0x93, 0xdb, 0x06, 0x43, 0x03, 0x4b, 0x96, 0xde, 0x9e, 0xd6, 0x0b, 0x4e, 0x0e, 0x46, 0x9b,
+    0x57, 0x17, 0x5f, 0x82, 0xc7, 0x87, 0xcf, 0x12, 0x5a, 0x1a, 0x52, 0x8f, 0xca, 0x8a, 0xc2, 0x1f,
+    0xd9, 0x99, 0xd1, 0x00, 0x49, 0x09, 0x41, 0x90, 0xd8, 0x98, 0xd0, 0x01, 0x48, 0x08, 0x40, 0x91,
+    0x3d, 0x7d, 0x35, 0x24, 0x6d, 0x2d, 0x65, 0x74, 0x3c, 0x7c, 0x34, 0x25, 0x6c, 0x2c, 0x64, 0x75,
+    0xdd, 0x9d, 0xd5, 0x04, 0x4d, 0x0d, 0x45, 0x94, 0xdc, 0x9c, 0xd4, 0x05, 0x4c, 0x0c, 0x44, 0x95,
+    0x59, 0x19, 0x51, 0x80, 0xc9, 0x89, 0xc1, 0x10, 0x58, 0x18, 0x50, 0x81, 0xc8, 0x88, 0xc0, 0x11,
+    0xd7, 0x97, 0xdf, 0x02, 0x47, 0x07, 0x4f, 0x92, 0xda, 0x9a, 0xd2, 0x0f, 0x4a, 0x0a, 0x42, 0x9f,
+    0x53, 0x13, 0x5b, 0x86, 0xc3, 0x83, 0xcb, 0x16, 0x5e, 0x1e, 0x56, 0x8b, 0xce, 0x8e, 0xc6, 0x1b,
+    0xb3, 0xf3, 0xbb, 0xa6, 0xe3, 0xa3, 0xeb, 0xf6, 0xbe, 0xfe, 0xb6, 0xab, 0xee, 0xae, 0xe6, 0xfb,
+    0x37, 0x77, 0x3f, 0x22, 0x67, 0x27, 0x6f, 0x72, 0x3a, 0x7a, 0x32, 0x2f, 0x6a, 0x2a, 0x62, 0x7f,
+    0xb9, 0xf9, 0xb1, 0xa0, 0xe9, 0xa9, 0xe1, 0xf0, 0xb8, 0xf8, 0xb0, 0xa1, 0xe8, 0xa8, 0xe0, 0xf1,
+    0x5d, 0x1d, 0x55, 0x84, 0xcd, 0x8d, 0xc5, 0x14, 0x5c, 0x1c, 0x54, 0x85, 0xcc, 0x8c, 0xc4, 0x15,
+    0xbd, 0xfd, 0xb5, 0xa4, 0xed, 0xad, 0xe5, 0xf4, 0xbc, 0xfc, 0xb4, 0xa5, 0xec, 0xac, 0xe4, 0xf5,
+    0x39, 0x79, 0x31, 0x20, 0x69, 0x29, 0x61, 0x70, 0x38, 0x78, 0x30, 0x21, 0x68, 0x28, 0x60, 0x71,
+    0xb7, 0xf7, 0xbf, 0xa2, 0xe7, 0xa7, 0xef, 0xf2, 0xba, 0xfa, 0xb2, 0xaf, 0xea, 0xaa, 0xe2, 0xff,
+];
+
+/// Table 2: LFSR1 high-byte feedback permutation.
+pub const TAB2: [u8; 256] = [
+    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x09, 0x08, 0x0b, 0x0a, 0x0d, 0x0c, 0x0f, 0x0e,
+    0x12, 0x13, 0x10, 0x11, 0x16, 0x17, 0x14, 0x15, 0x1b, 0x1a, 0x19, 0x18, 0x1f, 0x1e, 0x1d, 0x1c,
+    0x24, 0x25, 0x26, 0x27, 0x20, 0x21, 0x22, 0x23, 0x2d, 0x2c, 0x2f, 0x2e, 0x29, 0x28, 0x2b, 0x2a,
+    0x36, 0x37, 0x34, 0x35, 0x32, 0x33, 0x30, 0x31, 0x3f, 0x3e, 0x3d, 0x3c, 0x3b, 0x3a, 0x39, 0x38,
+    0x49, 0x48, 0x4b, 0x4a, 0x4d, 0x4c, 0x4f, 0x4e, 0x40, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47,
+    0x5b, 0x5a, 0x59, 0x58, 0x5f, 0x5e, 0x5d, 0x5c, 0x52, 0x53, 0x50, 0x51, 0x56, 0x57, 0x54, 0x55,
+    0x6d, 0x6c, 0x6f, 0x6e, 0x69, 0x68, 0x6b, 0x6a, 0x64, 0x65, 0x66, 0x67, 0x60, 0x61, 0x62, 0x63,
+    0x7f, 0x7e, 0x7d, 0x7c, 0x7b, 0x7a, 0x79, 0x78, 0x76, 0x77, 0x74, 0x75, 0x72, 0x73, 0x70, 0x71,
+    0x92, 0x93, 0x90, 0x91, 0x96, 0x97, 0x94, 0x95, 0x9b, 0x9a, 0x99, 0x98, 0x9f, 0x9e, 0x9d, 0x9c,
+    0x80, 0x81, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87, 0x89, 0x88, 0x8b, 0x8a, 0x8d, 0x8c, 0x8f, 0x8e,
+    0xb6, 0xb7, 0xb4, 0xb5, 0xb2, 0xb3, 0xb0, 0xb1, 0xbf, 0xbe, 0xbd, 0xbc, 0xbb, 0xba, 0xb9, 0xb8,
+    0xa4, 0xa5, 0xa6, 0xa7, 0xa0, 0xa1, 0xa2, 0xa3, 0xad, 0xac, 0xaf, 0xae, 0xa9, 0xa8, 0xab, 0xaa,
+    0xdb, 0xda, 0xd9, 0xd8, 0xdf, 0xde, 0xdd, 0xdc, 0xd2, 0xd3, 0xd0, 0xd1, 0xd6, 0xd7, 0xd4, 0xd5,
+    0xc9, 0xc8, 0xcb, 0xca, 0xcd, 0xcc, 0xcf, 0xce, 0xc0, 0xc1, 0xc2, 0xc3, 0xc4, 0xc5, 0xc6, 0xc7,
+    0xed, 0xec, 0xef, 0xee, 0xe9, 0xe8, 0xeb, 0xea, 0xe4, 0xe5, 0xe6, 0xe7, 0xe0, 0xe1, 0xe2, 0xe3,
+    0xff, 0xfe, 0xfd, 0xfc, 0xfb, 0xfa, 0xf9, 0xf8, 0xf6, 0xf7, 0xf4, 0xf5, 0xf2, 0xf3, 0xf0, 0xf1,
+];
+
+/// Table 3: LFSR1 9-bit low-word feedback table (512 entries).
+///
+/// Indexed by the 9-bit LFSR1 low word (the upper feedback bit makes the
+/// index 9-bit, hence 512 entries, not 256).
+pub const TAB3: [u8; 512] = [
+    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
+    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
+    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
+    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
+    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
+    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
+    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
+    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
+    0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe, 0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe,
+    0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe, 0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe,
+    0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe, 0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe,
+    0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe, 0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe,
+    0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe, 0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe,
+    0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe, 0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe,
+    0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe, 0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe,
+    0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe, 0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe,
+    0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd, 0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd,
+    0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd, 0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd,
+    0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd, 0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd,
+    0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd, 0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd,
+    0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd, 0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd,
+    0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd, 0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd,
+    0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd, 0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd,
+    0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd, 0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd,
+    0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc, 0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc,
+    0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc, 0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc,
+    0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc, 0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc,
+    0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc, 0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc,
+    0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc, 0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc,
+    0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc, 0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc,
+    0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc, 0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc,
+    0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc, 0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc,
+];
+
+/// Table 4: LFSR0 byte permutation (used in initialization and output).
+pub const TAB4: [u8; 256] = [
+    0x00, 0x80, 0x40, 0xc0, 0x20, 0xa0, 0x60, 0xe0, 0x10, 0x90, 0x50, 0xd0, 0x30, 0xb0, 0x70, 0xf0,
+    0x08, 0x88, 0x48, 0xc8, 0x28, 0xa8, 0x68, 0xe8, 0x18, 0x98, 0x58, 0xd8, 0x38, 0xb8, 0x78, 0xf8,
+    0x04, 0x84, 0x44, 0xc4, 0x24, 0xa4, 0x64, 0xe4, 0x14, 0x94, 0x54, 0xd4, 0x34, 0xb4, 0x74, 0xf4,
+    0x0c, 0x8c, 0x4c, 0xcc, 0x2c, 0xac, 0x6c, 0xec, 0x1c, 0x9c, 0x5c, 0xdc, 0x3c, 0xbc, 0x7c, 0xfc,
+    0x02, 0x82, 0x42, 0xc2, 0x22, 0xa2, 0x62, 0xe2, 0x12, 0x92, 0x52, 0xd2, 0x32, 0xb2, 0x72, 0xf2,
+    0x0a, 0x8a, 0x4a, 0xca, 0x2a, 0xaa, 0x6a, 0xea, 0x1a, 0x9a, 0x5a, 0xda, 0x3a, 0xba, 0x7a, 0xfa,
+    0x06, 0x86, 0x46, 0xc6, 0x26, 0xa6, 0x66, 0xe6, 0x16, 0x96, 0x56, 0xd6, 0x36, 0xb6, 0x76, 0xf6,
+    0x0e, 0x8e, 0x4e, 0xce, 0x2e, 0xae, 0x6e, 0xee, 0x1e, 0x9e, 0x5e, 0xde, 0x3e, 0xbe, 0x7e, 0xfe,
+    0x01, 0x81, 0x41, 0xc1, 0x21, 0xa1, 0x61, 0xe1, 0x11, 0x91, 0x51, 0xd1, 0x31, 0xb1, 0x71, 0xf1,
+    0x09, 0x89, 0x49, 0xc9, 0x29, 0xa9, 0x69, 0xe9, 0x19, 0x99, 0x59, 0xd9, 0x39, 0xb9, 0x79, 0xf9,
+    0x05, 0x85, 0x45, 0xc5, 0x25, 0xa5, 0x65, 0xe5, 0x15, 0x95, 0x55, 0xd5, 0x35, 0xb5, 0x75, 0xf5,
+    0x0d, 0x8d, 0x4d, 0xcd, 0x2d, 0xad, 0x6d, 0xed, 0x1d, 0x9d, 0x5d, 0xdd, 0x3d, 0xbd, 0x7d, 0xfd,
+    0x03, 0x83, 0x43, 0xc3, 0x23, 0xa3, 0x63, 0xe3, 0x13, 0x93, 0x53, 0xd3, 0x33, 0xb3, 0x73, 0xf3,
+    0x0b, 0x8b, 0x4b, 0xcb, 0x2b, 0xab, 0x6b, 0xeb, 0x1b, 0x9b, 0x5b, 0xdb, 0x3b, 0xbb, 0x7b, 0xfb,
+    0x07, 0x87, 0x47, 0xc7, 0x27, 0xa7, 0x67, 0xe7, 0x17, 0x97, 0x57, 0xd7, 0x37, 0xb7, 0x77, 0xf7,
+    0x0f, 0x8f, 0x4f, 0xcf, 0x2f, 0xaf, 0x6f, 0xef, 0x1f, 0x9f, 0x5f, 0xdf, 0x3f, 0xbf, 0x7f, 0xff,
+];
+
+/// Table 5: LFSR1 output permutation used in the keystream combiner.
+/// `TAB5[i] == TAB4[i] ^ 0xFF` (bitwise complement of the TAB4 bit-reversal
+/// table). Applied on the normal descramble/recrypt path (lfsr.rs) as well as
+/// in the key-recovery fallback (crack.rs).
+pub const TAB5: [u8; 256] = [
+    0xff, 0x7f, 0xbf, 0x3f, 0xdf, 0x5f, 0x9f, 0x1f, 0xef, 0x6f, 0xaf, 0x2f, 0xcf, 0x4f, 0x8f, 0x0f,
+    0xf7, 0x77, 0xb7, 0x37, 0xd7, 0x57, 0x97, 0x17, 0xe7, 0x67, 0xa7, 0x27, 0xc7, 0x47, 0x87, 0x07,
+    0xfb, 0x7b, 0xbb, 0x3b, 0xdb, 0x5b, 0x9b, 0x1b, 0xeb, 0x6b, 0xab, 0x2b, 0xcb, 0x4b, 0x8b, 0x0b,
+    0xf3, 0x73, 0xb3, 0x33, 0xd3, 0x53, 0x93, 0x13, 0xe3, 0x63, 0xa3, 0x23, 0xc3, 0x43, 0x83, 0x03,
+    0xfd, 0x7d, 0xbd, 0x3d, 0xdd, 0x5d, 0x9d, 0x1d, 0xed, 0x6d, 0xad, 0x2d, 0xcd, 0x4d, 0x8d, 0x0d,
+    0xf5, 0x75, 0xb5, 0x35, 0xd5, 0x55, 0x95, 0x15, 0xe5, 0x65, 0xa5, 0x25, 0xc5, 0x45, 0x85, 0x05,
+    0xf9, 0x79, 0xb9, 0x39, 0xd9, 0x59, 0x99, 0x19, 0xe9, 0x69, 0xa9, 0x29, 0xc9, 0x49, 0x89, 0x09,
+    0xf1, 0x71, 0xb1, 0x31, 0xd1, 0x51, 0x91, 0x11, 0xe1, 0x61, 0xa1, 0x21, 0xc1, 0x41, 0x81, 0x01,
+    0xfe, 0x7e, 0xbe, 0x3e, 0xde, 0x5e, 0x9e, 0x1e, 0xee, 0x6e, 0xae, 0x2e, 0xce, 0x4e, 0x8e, 0x0e,
+    0xf6, 0x76, 0xb6, 0x36, 0xd6, 0x56, 0x96, 0x16, 0xe6, 0x66, 0xa6, 0x26, 0xc6, 0x46, 0x86, 0x06,
+    0xfa, 0x7a, 0xba, 0x3a, 0xda, 0x5a, 0x9a, 0x1a, 0xea, 0x6a, 0xaa, 0x2a, 0xca, 0x4a, 0x8a, 0x0a,
+    0xf2, 0x72, 0xb2, 0x32, 0xd2, 0x52, 0x92, 0x12, 0xe2, 0x62, 0xa2, 0x22, 0xc2, 0x42, 0x82, 0x02,
+    0xfc, 0x7c, 0xbc, 0x3c, 0xdc, 0x5c, 0x9c, 0x1c, 0xec, 0x6c, 0xac, 0x2c, 0xcc, 0x4c, 0x8c, 0x0c,
+    0xf4, 0x74, 0xb4, 0x34, 0xd4, 0x54, 0x94, 0x14, 0xe4, 0x64, 0xa4, 0x24, 0xc4, 0x44, 0x84, 0x04,
+    0xf8, 0x78, 0xb8, 0x38, 0xd8, 0x58, 0x98, 0x18, 0xe8, 0x68, 0xa8, 0x28, 0xc8, 0x48, 0x88, 0x08,
+    0xf0, 0x70, 0xb0, 0x30, 0xd0, 0x50, 0x90, 0x10, 0xe0, 0x60, 0xa0, 0x20, 0xc0, 0x40, 0x80, 0x00,
+];
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Pins the documented relationship `TAB5[i] == TAB4[i] ^ 0xFF` so the
+    /// table doc cannot drift from the data.
+    #[test]
+    fn tab5_is_complement_of_tab4() {
+        for i in 0..256 {
+            assert_eq!(
+                TAB5[i],
+                TAB4[i] ^ 0xFF,
+                "TAB5[{i:#04x}] != TAB4[{i:#04x}] ^ 0xFF"
+            );
+        }
+    }
+}

src/decrypt.rs

@@ -0,0 +1,426 @@
+//! Decrypt-on-read layer.
+//!
+//! Decrypts sectors in-place using resolved keys from disc scanning.
+//! Handles AACS 1.0, AACS 2.0, and CSS transparently.
+//! The caller never sees encrypted data unless explicitly bypassed.
+//!
+//! ## Parallel AACS decrypt
+//!
+//! Each AACS aligned unit (6144 bytes) is decrypted INDEPENDENTLY of
+//! every other unit — per-unit key derivation from the unit_key plus
+//! the unit's own first-16-byte header. There is no cross-unit
+//! dependency, so a buffer of N units can be decrypted on N threads
+//! in parallel via a persistent rayon thread pool.
+//!
+//! Small buffers (< [`PARALLEL_MIN_UNITS`] units) fall through to the
+//! serial path to avoid pool dispatch overhead beating the per-unit
+//! AES work.
+//!
+//! ## Thread-count configuration — three layers
+//!
+//! Resolution order (highest wins):
+//! 1. The most recent [`set_decrypt_threads`] call with `n > 0`.
+//!    Calling this *replaces* the live thread pool — useful for a
+//!    settings-page slider in a long-running daemon.
+//! 2. `FREEMKV_THREADS` env var, if set and `> 0`. Single knob
+//!    covering decrypt today, intended to also drive any future
+//!    input-side / output-side worker pools.
+//! 3. Default: all available cores. Algorithm optimisation comes
+//!    first — we measure single-thread performance to find serial
+//!    bottlenecks before throwing parallelism at it — but once a
+//!    pool is engaged we use the whole box. Hard cap at
+//!    [`MAX_THREADS`] (rayon stack memory).
+
+use crate::aacs;
+use crate::css;
+use rayon::prelude::*;
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::{Arc, RwLock};
+
+/// Minimum units in a buffer before we pay the pool-dispatch cost of
+/// fanning out. Below this, serial is faster.
+const PARALLEL_MIN_UNITS: usize = 8;
+
+/// Hard upper bound on configurable thread count. Anything larger is
+/// almost certainly a misconfiguration; rayon would happily allocate
+/// thousands of worker stacks otherwise.
+pub const MAX_THREADS: usize = 64;
+
+/// Process-wide decrypt thread count override. `0` means "use env
+/// var, else default" — see [`decrypt_threads`] for the resolution
+/// order.
+static DECRYPT_THREADS: AtomicUsize = AtomicUsize::new(0);
+
+/// Current rayon pool. `RwLock<Option<Arc<...>>>` so that
+/// [`set_decrypt_threads`] can swap the pool out without leaking the
+/// old one and without blocking ongoing decrypt work (in-flight calls
+/// hold an `Arc` clone via [`decrypt_pool`] and finish on the old
+/// pool; new calls pick up the new pool).
+static DECRYPT_POOL: RwLock<Option<Arc<rayon::ThreadPool>>> = RwLock::new(None);
+
+/// Configure how many threads to use for AACS unit decryption. A value
+/// of `0` resets to the env / default resolution. `1` forces serial.
+/// `N > 1` builds a new rayon pool of size N (capped at [`MAX_THREADS`])
+/// and atomically replaces the live pool.
+///
+/// Thread-safe. Live decrypt calls keep their previously-acquired
+/// pool reference for the rest of the call — no mid-call pool
+/// switch. Subsequent calls see the new pool.
+///
+/// Pool construction is ~ms-scale; safe to call from a settings POST
+/// handler.
+pub fn set_decrypt_threads(n: usize) {
+    let clamped = n.min(MAX_THREADS);
+    DECRYPT_THREADS.store(clamped, Ordering::Relaxed);
+    // Drop the existing pool. Next decrypt_pool() call rebuilds with
+    // the new resolved thread count.
+    if let Ok(mut guard) = DECRYPT_POOL.write() {
+        *guard = None;
+    }
+}
+
+/// Get (or lazily build) the active rayon thread pool. Returns an
+/// `Arc` so in-flight work survives a concurrent
+/// [`set_decrypt_threads`] swap.
+///
+/// Returns `None` if the pool cannot be built (e.g. the OS refuses the
+/// worker threads under a pid/thread limit). The caller falls back to
+/// the serial decrypt path — library code never panics here.
+fn decrypt_pool() -> Option<Arc<rayon::ThreadPool>> {
+    // Fast path: pool already built. A poisoned read lock still yields a
+    // usable guard (the pool Arc is immutable once stored).
+    {
+        let guard = DECRYPT_POOL.read().unwrap_or_else(|e| e.into_inner());
+        if let Some(pool) = guard.as_ref() {
+            return Some(Arc::clone(pool));
+        }
+    }
+    // Slow path: build a new one under the write lock. Recover the guard
+    // on poisoning (a prior panic) rather than propagating a secondary
+    // panic — we simply rebuild. Double-check after acquiring in case
+    // another caller built it first.
+    let mut guard = DECRYPT_POOL.write().unwrap_or_else(|e| e.into_inner());
+    if let Some(pool) = guard.as_ref() {
+        return Some(Arc::clone(pool));
+    }
+    let n = decrypt_threads();
+    let pool = rayon::ThreadPoolBuilder::new()
+        .num_threads(n)
+        .thread_name(|i| format!("freemkv-decrypt-{i}"))
+        .build()
+        .ok()
+        .map(Arc::new)?;
+    *guard = Some(Arc::clone(&pool));
+    Some(pool)
+}
+
+/// Current effective decrypt thread count. Resolution order:
+/// 1. Most recent [`set_decrypt_threads`] value (if > 0)
+/// 2. `FREEMKV_THREADS` env var (if set and > 0)
+/// 3. Default: all available cores, capped at [`MAX_THREADS`].
+pub fn decrypt_threads() -> usize {
+    let explicit = DECRYPT_THREADS.load(Ordering::Relaxed);
+    if explicit > 0 {
+        return explicit;
+    }
+    let env = std::env::var("FREEMKV_THREADS")
+        .ok()
+        .and_then(|v| v.parse::<usize>().ok())
+        .unwrap_or(0);
+    if env > 0 {
+        return env.min(MAX_THREADS);
+    }
+    let cores = std::thread::available_parallelism()
+        .map(|n| n.get())
+        .unwrap_or(2);
+    cores.clamp(1, MAX_THREADS)
+}
+
+/// Resolved decryption state from disc scanning.
+/// Passed to `decrypt_sectors()` — the caller doesn't need to know
+/// which encryption scheme is in use.
+#[derive(Clone)]
+pub enum DecryptKeys {
+    /// No encryption on this disc.
+    None,
+    /// AACS (Blu-ray / UHD). Unit keys + optional read data key.
+    Aacs {
+        unit_keys: Vec<(u32, [u8; 16])>,
+        read_data_key: Option<[u8; 16]>,
+    },
+    /// CSS (DVD). Title key for sector descrambling.
+    Css { title_key: [u8; 5] },
+}
+
+impl DecryptKeys {
+    /// True if there are keys to decrypt with.
+    pub fn is_encrypted(&self) -> bool {
+        !matches!(self, DecryptKeys::None)
+    }
+}
+
+/// Decrypt a buffer of sectors in-place.
+///
+/// For AACS: processes in 6144-byte aligned units (3 sectors).
+/// For CSS: processes per 2048-byte sector.
+/// For None: no-op.
+///
+/// `unit_key_idx` selects which AACS unit key to use (0 for most discs).
+///
+/// Returns `Err` if decryption was expected but keys are missing or invalid.
+/// Never produces silently corrupted output.
+pub fn decrypt_sectors(
+    buf: &mut [u8],
+    keys: &DecryptKeys,
+    unit_key_idx: usize,
+) -> Result<(), crate::error::Error> {
+    match keys {
+        DecryptKeys::None => {}
+        DecryptKeys::Aacs {
+            unit_keys,
+            read_data_key,
+        } => {
+            let uk = match unit_keys.get(unit_key_idx) {
+                Some((_, k)) => *k,
+                None => {
+                    return Err(crate::error::Error::DecryptFailed);
+                }
+            };
+            let rdk: Option<[u8; 16]> = *read_data_key;
+            let unit_len = aacs::ALIGNED_UNIT_LEN;
+            // AACS decrypts whole 6144-byte aligned units. The live mux path
+            // (mux/disc.rs::fill_extents) issues 1- or 2-sector reads at every
+            // extent tail, so a buffer is commonly NOT a multiple of the unit
+            // length. We process the whole leading units exactly as a fully
+            // aligned buffer would be, then make a deliberate decision about any
+            // trailing partial unit.
+            //
+            // Trailing-partial contract:
+            //   * A clear partial (incomplete final unit / clear nav-TS tail) is
+            //     what AACS legitimately leaves in the clear on disc, so we leave
+            //     it untouched and return Ok. This is the proven, shipped
+            //     behavior every production UHD MKV was made with — no regression
+            //     on conformant discs.
+            //   * A *scrambled* partial can only arise from a structurally
+            //     malformed UDF layout that splits an encrypted unit across an
+            //     extent boundary. Those bytes are encrypted content that cannot
+            //     be decrypted standalone; passing them through as clear would be
+            //     silent corruption. We fail loud (Error::DecryptFailed), matching
+            //     the highway path's Error::ExtentNotUnitAligned policy.
+            //
+            // Detection: is_aacs_scrambled() short-circuits to false for any
+            // buffer shorter than a full unit, so it cannot judge a partial. We
+            // instead apply the same TS-sync-intactness test it uses internally
+            // (ts_sync_count vs ts_packet_total) directly to the available
+            // partial bytes. A clear TS tail carries 0x47 syncs at the 192-byte
+            // stride (> half the packets) → intact → not scrambled → tolerate. An
+            // encrypted tail has those syncs destroyed (≤ half) → scrambled →
+            // reject. If the partial is too short to hold even one TS packet
+            // (< 192 bytes, ts_packet_total == 0) we cannot judge confidently and
+            // tolerate rather than risk a false positive on conformant tails.
+            let partial_len = buf.len() % unit_len;
+            if partial_len != 0 {
+                let partial = &buf[buf.len() - partial_len..];
+                let packets = aacs::ts_packet_total(partial);
+                if packets > 0 && aacs::ts_sync_count(partial) <= packets / 2 {
+                    return Err(crate::error::Error::DecryptFailed);
+                }
+            }
+            let nthreads = decrypt_threads();
+            let nunits = buf.len() / unit_len;
+
+            // Per-unit decrypt closure. The is_aacs_scrambled check reads the
+            // raw TS syncs; a non-m2ts unit (e.g. MPLS/CLPI nav file) can look
+            // scrambled and trigger a decrypt attempt, so on a verify miss we
+            // snapshot+restore the original bytes so it survives. See test
+            // `nav_file_unit_survives_decrypt_attempt`.
+            let decrypt_one = |chunk: &mut [u8]| {
+                if chunk.len() == unit_len && aacs::is_aacs_scrambled(chunk) {
+                    let original: Vec<u8> = chunk.to_vec();
+                    if !aacs::decrypt_unit_full(chunk, &uk, rdk.as_ref()) {
+                        chunk.copy_from_slice(&original);
+                    }
+                }
+            };
+
+            if nthreads <= 1 || nunits < PARALLEL_MIN_UNITS {
+                // Serial path: avoids thread-pool overhead for tiny
+                // buffers; also the only path when caller pinned
+                // single-threaded via FREEMKV_THREADS=1. Iterate the
+                // chunks directly — no Vec of slice pointers needed.
+                for chunk in buf.chunks_mut(unit_len) {
+                    decrypt_one(chunk);
+                }
+            } else {
+                // Parallel path via rayon's persistent thread pool.
+                // The pool is built once on first use and reused across
+                // every decrypt_sectors call — no per-call OS thread
+                // spawn. Each unit decrypts independently (own key
+                // derivation), so par_iter is sound. On a pool-build
+                // failure (e.g. thread/pid-limit exhaustion) we fall
+                // back to the serial path rather than panic.
+                match decrypt_pool() {
+                    Some(pool) => {
+                        let chunks: Vec<&mut [u8]> = buf.chunks_mut(unit_len).collect();
+                        pool.install(|| {
+                            chunks.into_par_iter().for_each(|chunk| {
+                                decrypt_one(chunk);
+                            });
+                        });
+                    }
+                    None => {
+                        for chunk in buf.chunks_mut(unit_len) {
+                            decrypt_one(chunk);
+                        }
+                    }
+                }
+            }
+        }
+        DecryptKeys::Css { title_key } => {
+            for chunk in buf.chunks_mut(2048) {
+                css::lfsr::descramble_sector(title_key, chunk);
+            }
+        }
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Regression for the 0.18.1 nav-file scramble bug. A non-m2ts unit (here
+    /// an MPLS file: starts "MPLS", carries no TS syncs) reads as scrambled
+    /// under `is_aacs_scrambled`, 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"
+        );
+    }
+
+    /// Build a clear-TS region: a 0x47 sync byte at offset 4 of every 192-byte
+    /// BD-TS packet (matching `ts_sync_count`'s probe stride), filler elsewhere.
+    /// Reads as NOT scrambled.
+    fn clear_ts_region(len: usize) -> Vec<u8> {
+        let mut v: Vec<u8> = (0..len).map(|i| (i as u8).wrapping_mul(31)).collect();
+        let mut off = 4;
+        while off < len {
+            v[off] = 0x47;
+            off += 192;
+        }
+        v
+    }
+
+    /// Build a scrambled region: the 192-byte-stride sync positions are NOT
+    /// 0x47 (encrypted content destroys them), so it reads as scrambled.
+    fn scrambled_region(len: usize) -> Vec<u8> {
+        let mut v: Vec<u8> = (0..len).map(|i| (i as u8).wrapping_mul(31)).collect();
+        let mut off = 4;
+        while off < len {
+            // Force a non-sync byte at every probe position.
+            v[off] = 0xA5;
+            off += 192;
+        }
+        v
+    }
+
+    /// Whole leading units plus a CLEAR trailing partial (the benign,
+    /// conformant case): AACS leaves an incomplete final unit / clear nav-TS
+    /// tail in the clear on disc. We must return `Ok` and leave the partial
+    /// bytes byte-for-byte unchanged — no regression on real discs.
+    #[test]
+    fn aacs_clear_trailing_partial_is_tolerated_unchanged() {
+        let keys = DecryptKeys::Aacs {
+            unit_keys: vec![(0, [0xAB; 16])],
+            read_data_key: None,
+        };
+        // One full scrambled unit + a 2048-byte (single-sector) CLEAR tail.
+        let unit = scrambled_region(aacs::ALIGNED_UNIT_LEN);
+        let tail = clear_ts_region(2048);
+        let mut buf = unit;
+        buf.extend_from_slice(&tail);
+
+        decrypt_sectors(&mut buf, &keys, 0).expect("clear trailing partial is Ok");
+
+        assert_eq!(
+            &buf[aacs::ALIGNED_UNIT_LEN..],
+            &tail[..],
+            "clear trailing partial unit must be left unchanged"
+        );
+    }
+
+    /// Whole leading units plus a SCRAMBLED trailing partial (the malformed
+    /// danger case): an encrypted unit split across an extent boundary cannot be
+    /// decrypted standalone. Passing it through as clear would be silent
+    /// corruption, so we must fail loud with `DecryptFailed`.
+    #[test]
+    fn aacs_scrambled_trailing_partial_is_rejected() {
+        let keys = DecryptKeys::Aacs {
+            unit_keys: vec![(0, [0xAB; 16])],
+            read_data_key: None,
+        };
+        // One full unit + a 4096-byte (two-sector) SCRAMBLED tail.
+        let unit = clear_ts_region(aacs::ALIGNED_UNIT_LEN);
+        let tail = scrambled_region(4096);
+        let mut buf = unit;
+        buf.extend_from_slice(&tail);
+
+        let err = decrypt_sectors(&mut buf, &keys, 0)
+            .expect_err("scrambled trailing partial must be rejected");
+        assert_eq!(
+            err.code(),
+            crate::error::Error::DecryptFailed.code(),
+            "scrambled trailing partial must fail with DecryptFailed"
+        );
+    }
+
+    /// An empty buffer is a valid no-op (zero units), not an error.
+    #[test]
+    fn aacs_empty_buffer_is_ok() {
+        let keys = DecryptKeys::Aacs {
+            unit_keys: vec![(0, [0xAB; 16])],
+            read_data_key: None,
+        };
+        let mut buf: Vec<u8> = Vec::new();
+        assert!(decrypt_sectors(&mut buf, &keys, 0).is_ok());
+    }
+
+    /// An exact multiple of the unit length has no trailing partial: behavior
+    /// is unchanged — clear units stay clear, scrambled units are decrypt-
+    /// attempted. Two clear units must round-trip untouched and return `Ok`.
+    #[test]
+    fn aacs_exact_multiple_unchanged() {
+        let keys = DecryptKeys::Aacs {
+            unit_keys: vec![(0, [0xAB; 16])],
+            read_data_key: None,
+        };
+        let mut buf = clear_ts_region(aacs::ALIGNED_UNIT_LEN * 2);
+        let snapshot = buf.clone();
+
+        decrypt_sectors(&mut buf, &keys, 0).expect("exact-multiple buffer is Ok");
+
+        assert_eq!(
+            buf, snapshot,
+            "clear exact-multiple buffer must be left unchanged"
+        );
+    }
+}

src/disc/bluray.rs

@@ -0,0 +1,296 @@
+//! Blu-ray title scanning — MPLS playlist parsing, CLPI clip info, BD metadata.
+
+use super::*;
+use crate::clpi;
+use crate::mpls;
+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 SectorSource,
+        udf_fs: &udf::UdfFs,
+    ) -> Vec<DiscTitle> {
+        let mut titles = Vec::new();
+        if let Some(playlist_dir) = udf_fs.find_dir("/BDMV/PLAYLIST") {
+            for entry in &playlist_dir.entries {
+                if !entry.is_dir && entry.name.to_lowercase().ends_with(".mpls") {
+                    let path = format!("/BDMV/PLAYLIST/{}", entry.name);
+                    if let Ok(mpls_data) = udf_fs.read_file(reader, &path) {
+                        if let Some(title) =
+                            Self::parse_playlist(reader, udf_fs, &entry.name, &mpls_data)
+                        {
+                            titles.push(title);
+                        }
+                    }
+                }
+            }
+        }
+        titles
+    }
+
+    /// Parse one MPLS playlist into a [`DiscTitle`].
+    ///
+    /// Sums PlayItem durations; returns `None` if the playlist is under
+    /// 30 seconds (skips menu / clip-info stub playlists) or fails to
+    /// parse. Physical sector extents are pulled from the UDF allocation
+    /// descriptors of each referenced `.m2ts` (deduplicated by clip_id).
+    pub(super) fn parse_playlist(
+        reader: &mut dyn SectorSource,
+        udf_fs: &udf::UdfFs,
+        filename: &str,
+        data: &[u8],
+    ) -> Option<DiscTitle> {
+        let parsed = mpls::parse(data).ok()?;
+
+        // Calculate duration from play items
+        let duration_ticks: u64 = parsed
+            .play_items
+            .iter()
+            .map(|pi| (pi.out_time.saturating_sub(pi.in_time)) as u64)
+            .sum();
+        let duration_secs = duration_ticks as f64 / 45000.0;
+
+        // Skip very short playlists (< 30 seconds)
+        if duration_secs < 30.0 {
+            return None;
+        }
+
+        // Parse each clip for size, duration, and sector extents
+        let mut extents = Vec::new();
+        let mut total_size: u64 = 0;
+        let mut clips = Vec::with_capacity(parsed.play_items.len());
+        // BD playlists legally reference the same .m2ts clip_id from
+        // multiple PlayItems (multi-angle, seamless splits, looped
+        // segments). The physical extents and packet count must be
+        // counted ONCE per unique clip — mux reads extents in order, so
+        // a duplicate would mux the A/V twice and inflate size_bytes.
+        // Per-PlayItem Clip entries (differing in/out times) still get
+        // recorded.
+        let mut seen_clips: std::collections::HashSet<String> = std::collections::HashSet::new();
+
+        for play_item in &parsed.play_items {
+            let clip_dur = play_item.out_time.saturating_sub(play_item.in_time) as f64 / 45000.0;
+            let mut pkt_count: u32 = 0;
+            let first_ref = seen_clips.insert(play_item.clip_id.clone());
+
+            let clpi_path = format!("/BDMV/CLIPINF/{}.clpi", play_item.clip_id);
+            if let Ok(clpi_data) = udf_fs.read_file(reader, &clpi_path) {
+                if let Ok(clip_info) = clpi::parse(&clpi_data) {
+                    pkt_count = clip_info.source_packet_count;
+
+                    // Only fetch/push the physical extents and add to the
+                    // total size the first time this clip_id is seen.
+                    if first_ref {
+                        total_size += pkt_count as u64 * 192;
+
+                        // Get m2ts file extents from UDF allocation descriptors.
+                        // Dual-layer discs split files across layers — UDF knows the real layout.
+                        let m2ts_path = format!("/BDMV/STREAM/{}.m2ts", play_item.clip_id);
+                        if let Ok(file_exts) = udf_fs.file_extents(reader, &m2ts_path) {
+                            for (lba, sectors) in file_exts {
+                                if sectors > 0 && lba > 0 {
+                                    extents.push(Extent {
+                                        start_lba: lba,
+                                        sector_count: sectors,
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+
+            clips.push(Clip {
+                clip_id: play_item.clip_id.clone(),
+                in_time: play_item.in_time,
+                out_time: play_item.out_time,
+                duration_secs: clip_dur,
+                source_packets: pkt_count,
+            });
+        }
+
+        // Build streams from STN table
+        let streams: Vec<Stream> = parsed
+            .streams
+            .iter()
+            .filter_map(|s| {
+                // Skip empty/padding entries (coding_type 0x00)
+                if s.coding_type == 0 {
+                    return None;
+                }
+                let codec = Codec::from_coding_type(s.coding_type);
+                match s.stream_type {
+                    1 | 6 | 7 => Some(Stream::Video(VideoStream {
+                        pid: s.pid,
+                        codec,
+                        resolution: Resolution::from_video_format(s.video_format),
+                        frame_rate: FrameRate::from_video_rate(s.video_rate),
+                        hdr: match s.dynamic_range {
+                            1 => HdrFormat::Hdr10,
+                            2 => HdrFormat::DolbyVision,
+                            _ => HdrFormat::Sdr,
+                        },
+                        color_space: match s.color_space {
+                            1 => ColorSpace::Bt709,
+                            2 => ColorSpace::Bt2020,
+                            _ => ColorSpace::Unknown,
+                        },
+                        secondary: s.secondary,
+                        label: match s.stream_type {
+                            7 => "Dolby Vision EL".to_string(),
+                            _ => String::new(),
+                        },
+                    })),
+                    2 | 5 => {
+                        // Guard: if coding_type is a subtitle codec (PGS 0x90/0x91),
+                        // this is a misaligned stream -- treat as subtitle, not audio
+                        if matches!(codec, Codec::Pgs) {
+                            Some(Stream::Subtitle(SubtitleStream {
+                                pid: s.pid,
+                                codec,
+                                language: s.language.clone(),
+                                forced: false,
+                                qualifier: crate::disc::LabelQualifier::None,
+                                codec_data: None,
+                            }))
+                        } else {
+                            Some(Stream::Audio(AudioStream {
+                                pid: s.pid,
+                                codec,
+                                channels: AudioChannels::from_audio_format(s.audio_format),
+                                language: s.language.clone(),
+                                sample_rate: SampleRate::from_audio_rate(s.audio_rate),
+                                secondary: s.stream_type == 5,
+                                purpose: crate::disc::LabelPurpose::Normal,
+                                label: String::new(),
+                            }))
+                        }
+                    }
+                    3 => Some(Stream::Subtitle(SubtitleStream {
+                        pid: s.pid,
+                        codec,
+                        language: s.language.clone(),
+                        forced: false,
+                        qualifier: crate::disc::LabelQualifier::None,
+                        codec_data: None,
+                    })),
+                    // Stream type 4 = IG, unknown types -- skip.
+                    other => {
+                        tracing::warn!(
+                            "dropping STN stream entry: unhandled stream_type {} (PID {:#06x}, coding_type {:#04x})",
+                            other,
+                            s.pid,
+                            s.coding_type,
+                        );
+                        None
+                    }
+                }
+            })
+            .collect();
+
+        // Convert marks to chapters. mark_type == 1 is an entry-mark
+        // (chapter); type 2 is a link point and type 0 is reserved, so
+        // neither is a chapter.
+        //
+        // Each mark's timestamp is in the timebase of the PlayItem it
+        // references (play_item_ref). The chapter's position on the
+        // muxed timeline is the summed duration of every preceding
+        // PlayItem plus the mark's offset within its own PlayItem. Using
+        // play_items[0].in_time for every mark would misplace chapters in
+        // multi-PlayItem playlists.
+        let chapters: Vec<Chapter> = parsed
+            .marks
+            .iter()
+            .filter(|m| m.mark_type == 1)
+            .filter_map(|m| {
+                let pi_idx = m.play_item_ref as usize;
+                let pi = parsed.play_items.get(pi_idx)?;
+                let preceding: f64 = parsed.play_items[..pi_idx]
+                    .iter()
+                    .map(|p| p.out_time.saturating_sub(p.in_time) as f64 / 45000.0)
+                    .sum();
+                let within = (m.timestamp as f64 - pi.in_time as f64) / 45000.0;
+                let time_secs = preceding + within;
+                Some(Chapter {
+                    time_secs: if time_secs < 0.0 { 0.0 } else { time_secs },
+                    name: String::new(), // filled with the ordinal below
+                })
+            })
+            .enumerate()
+            .map(|(i, mut ch)| {
+                ch.name = super::chapter_name(i);
+                ch
+            })
+            .collect();
+
+        // Strip the .mpls suffix case-insensitively before parsing the
+        // numeric playlist id (the dir scan accepts any-case .mpls).
+        let playlist_num = filename
+            .get(..filename.len().saturating_sub(5))
+            .filter(|_| {
+                filename.len() >= 5 && filename[filename.len() - 5..].eq_ignore_ascii_case(".mpls")
+            })
+            .unwrap_or(filename);
+        let playlist_id = playlist_num.parse::<u16>().unwrap_or(0);
+
+        Some(DiscTitle {
+            playlist: filename.to_string(),
+            playlist_id,
+            duration_secs,
+            size_bytes: total_size,
+            clips,
+            streams,
+            chapters,
+            extents,
+            content_format: ContentFormat::BdTs,
+            codec_privates: Vec::new(),
+        })
+    }
+
+    /// Read disc title from META/DL/bdmt_eng.xml (Blu-ray Disc Meta Table).
+    /// 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 SectorSource,
+        udf_fs: &udf::UdfFs,
+    ) -> Option<String> {
+        let meta_dir = udf_fs.find_dir("/BDMV/META")?;
+        for sub in &meta_dir.entries {
+            if !sub.is_dir {
+                continue;
+            }
+            let dl_path = format!("/BDMV/META/{}", sub.name);
+            if let Some(dl_dir) = udf_fs.find_dir(&dl_path) {
+                let xml_files: Vec<_> = dl_dir
+                    .entries
+                    .iter()
+                    .filter(|e| !e.is_dir && e.name.to_lowercase().ends_with(".xml"))
+                    .collect();
+
+                let eng = xml_files
+                    .iter()
+                    .find(|e| e.name.to_lowercase().contains("eng"));
+                let target = eng.or_else(|| xml_files.first());
+
+                if let Some(entry) = target {
+                    let path = format!("{}/{}", dl_path, entry.name);
+                    if let Ok(data) = udf_fs.read_file(reader, &path) {
+                        let xml = String::from_utf8_lossy(&data);
+                        if let Some(start) = xml.find("<di:name>") {
+                            let s = start + "<di:name>".len();
+                            if let Some(end) = xml[s..].find("</di:name>") {
+                                let title = xml[s..s + end].trim().to_string();
+                                if !title.is_empty() && title != "Blu-ray" {
+                                    return Some(title);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        None
+    }
+}

src/disc/dvd.rs

@@ -0,0 +1,150 @@
+//! DVD title scanning — IFO parsing, stream mapping, VOB extent building.
+
+use super::*;
+use crate::ifo;
+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 SectorSource,
+        udf_fs: &udf::UdfFs,
+    ) -> Vec<DiscTitle> {
+        let dvd_info = match ifo::parse_vmg(reader, udf_fs) {
+            Ok(info) => info,
+            Err(_) => return Vec::new(),
+        };
+
+        let mut titles = Vec::new();
+        let mut title_number: u16 = 0;
+
+        for ts in &dvd_info.title_sets {
+            let video_stream = Stream::Video(VideoStream {
+                pid: 0xE0, // DVD video PID (standard MPEG PS video stream)
+                codec: ts.video.codec,
+                resolution: ts.video.resolution,
+                frame_rate: match ts.video.standard.as_str() {
+                    "PAL" => FrameRate::F25,
+                    _ => FrameRate::F29_97,
+                },
+                hdr: HdrFormat::Sdr,
+                color_space: ColorSpace::Bt709,
+                secondary: false,
+                label: String::new(),
+            });
+
+            // Map DvdAudioAttr to Stream::Audio. The PID is derived from the
+            // stream's REAL on-wire private_stream_1 sub-stream id (assigned
+            // by per-codec ordinal in the IFO scan) via the same
+            // `dvd_audio_pid` table the demuxer's `PsPacket::dvd_pid` uses,
+            // so a mixed-codec title (AC-3 + DTS + LPCM) routes correctly
+            // instead of colliding on 0xBD00. Streams carried as a regular
+            // MPEG-audio PES (MP1/MP2, no sub-id) fall back to a distinct
+            // 0xBD00+ordinal PID — disjoint from the 0xBD80+ canonical audio
+            // space — though they are not routed via `dvd_pid` today.
+            let audio_streams: Vec<Stream> = ts
+                .audio_streams
+                .iter()
+                .enumerate()
+                .map(|(i, a)| {
+                    let codec = a.codec;
+                    let pid = a
+                        .sub_stream_id
+                        .and_then(crate::mux::ps::dvd_audio_pid)
+                        .unwrap_or(0xBD00 + i as u16);
+                    Stream::Audio(AudioStream {
+                        pid,
+                        codec,
+                        channels: AudioChannels::from_count(a.channels),
+                        language: a.language.clone(),
+                        sample_rate: SampleRate::from_hz(a.sample_rate),
+                        secondary: false,
+                        purpose: crate::disc::LabelPurpose::Normal,
+                        label: String::new(),
+                    })
+                })
+                .collect();
+
+            for dvd_title in &ts.titles {
+                title_number += 1;
+
+                // Build extents from cell sector ranges (absolute = vob_start + cell offset)
+                let extents: Vec<Extent> = dvd_title
+                    .cells
+                    .iter()
+                    .map(|cell| {
+                        let start = ts.vob_start_sector.saturating_add(cell.first_sector);
+                        let count = cell
+                            .last_sector
+                            .saturating_sub(cell.first_sector)
+                            .saturating_add(1);
+                        Extent {
+                            start_lba: start,
+                            sector_count: count,
+                        }
+                    })
+                    .collect();
+
+                let size_bytes: u64 = extents.iter().map(|e| e.sector_count as u64 * 2048).sum();
+
+                // Build pre-formatted palette codec_data for VobSub subtitle streams
+                let codec_data = dvd_title
+                    .palette
+                    .as_ref()
+                    .map(|pal| crate::mux::codec::dvdsub::format_palette(pal));
+
+                // Map DvdSubtitleAttr to Stream::Subtitle
+                let subtitle_streams: Vec<Stream> = ts
+                    .subtitle_streams
+                    .iter()
+                    .enumerate()
+                    .map(|(i, s)| {
+                        // VobSub sub-stream ids run 0x20..=0x3F; PID = sub-id
+                        // (identity), shared with the demuxer via
+                        // `dvd_subtitle_pid`.
+                        let sub_id = 0x20u8.saturating_add(i.min(0x1F) as u8);
+                        let pid = crate::mux::ps::dvd_subtitle_pid(sub_id).unwrap_or(sub_id as u16);
+                        Stream::Subtitle(SubtitleStream {
+                            pid,
+                            codec: Codec::DvdSub,
+                            language: s.language.clone(),
+                            forced: false,
+                            qualifier: crate::disc::LabelQualifier::None,
+                            codec_data: codec_data.clone(),
+                        })
+                    })
+                    .collect();
+
+                let mut streams = vec![video_stream.clone()];
+                streams.extend(audio_streams.iter().cloned());
+                streams.extend(subtitle_streams);
+
+                let chapters: Vec<Chapter> = dvd_title
+                    .chapter_times
+                    .iter()
+                    .enumerate()
+                    .map(|(i, &t)| Chapter {
+                        time_secs: t,
+                        name: chapter_name(i),
+                    })
+                    .collect();
+
+                titles.push(DiscTitle {
+                    playlist: format!("VTS_{:02}_{}.VOB", ts.vts_number, title_number),
+                    playlist_id: title_number,
+                    duration_secs: dvd_title.duration_secs,
+                    size_bytes,
+                    clips: Vec::new(),
+                    streams,
+                    chapters,
+                    extents,
+                    content_format: ContentFormat::MpegPs,
+                    codec_privates: Vec::new(),
+                });
+            }
+        }
+
+        titles
+    }
+}

src/disc/encrypt.rs

@@ -0,0 +1,384 @@
+//! AACS encryption resolution — key derivation, SCSI handshake, VUK lookup.
+
+use super::*;
+use crate::error::{Error, Result};
+use crate::sector::SectorSource;
+use crate::udf;
+
+/// Result of SCSI AACS handshake (ECDH authentication).
+/// Only available when scanning from a real drive, not ISO images.
+#[derive(Debug)]
+pub(super) struct HandshakeResult {
+    pub volume_id: [u8; 16],
+    pub read_data_key: Option<[u8; 16]>,
+}
+
+impl Disc {
+    /// Acquire the Volume ID. Tries the per-drive OEM CDB path first
+    /// when the drive reports `is_unlocked()` (extended-access state),
+    /// and falls back to the cert-based AACS mutual-auth handshake
+    /// otherwise.
+    ///
+    /// The OEM path is a single READ_BUFFER CDB built from the drive
+    /// profile's `read_vid_cdb` template. The response carries a 3-byte
+    /// header (validated against `00 22 00`) followed by the 16-byte
+    /// VID at bytes [4..20]. Crucially, no AGID setup is required —
+    /// the drive's runtime firmware serves the VID directly when in
+    /// extended-access state.
+    ///
+    /// The cert path is the standard AACS spec flow: ECDH key
+    /// agreement, bus-key derivation, then `REPORT_DISC_STRUCTURE`
+    /// format 0x80 to retrieve VID under bus-key MAC.
+    pub(super) fn read_vid(
+        session: &mut crate::drive::Drive,
+        opts: &ScanOptions,
+    ) -> Result<[u8; 16]> {
+        if session.is_unlocked() {
+            let profile = session
+                .drive_profile()
+                .ok_or(Error::DriveProfileMissing)?
+                .clone();
+            return Self::read_vid_oem(session, &profile);
+        }
+        Self::read_vid_cert(session, opts)
+    }
+
+    /// OEM VID retrieval — issues the per-drive READ_BUFFER CDB and
+    /// parses the response.
+    ///
+    /// Response layout (36 bytes):
+    ///   * [0..3]   3-byte response signature; expected `00 22 00`
+    ///   * [3]      reserved
+    ///   * [4..20]  16-byte Volume ID
+    ///   * [20..36] reserved / per-drive padding
+    fn read_vid_oem(
+        session: &mut crate::drive::Drive,
+        profile: &crate::profile::DriveProfile,
+    ) -> Result<[u8; 16]> {
+        const RESPONSE_LEN: usize = 36;
+        const EXPECTED_HEADER: [u8; 3] = [0x00, 0x22, 0x00];
+
+        let cdb = profile.read_vid_cdb.ok_or(Error::VidCdbUnavailable)?;
+        let mut buf = vec![0u8; RESPONSE_LEN];
+        let result = session.scsi_execute(
+            &cdb,
+            crate::scsi::DataDirection::FromDevice,
+            &mut buf,
+            5_000,
+        )?;
+        if result.bytes_transferred < RESPONSE_LEN {
+            tracing::warn!(
+                target: "freemkv::disc",
+                phase = "oem_vid_short_response",
+                bytes_transferred = result.bytes_transferred,
+                "OEM VID CDB returned short response"
+            );
+            return Err(Error::AacsVidRead);
+        }
+        if buf[0..3] != EXPECTED_HEADER {
+            tracing::warn!(
+                target: "freemkv::disc",
+                phase = "oem_vid_bad_header",
+                header_0 = buf[0],
+                header_1 = buf[1],
+                header_2 = buf[2],
+                "OEM VID response header mismatch"
+            );
+            return Err(Error::AacsVidRead);
+        }
+        let mut vid = [0u8; 16];
+        vid.copy_from_slice(&buf[4..20]);
+        tracing::debug!(
+            target: "freemkv::disc",
+            phase = "oem_vid_ok",
+            "OEM VID retrieved"
+        );
+        Ok(vid)
+    }
+
+    /// Cert-based VID retrieval — runs the full AACS mutual-auth
+    /// handshake and extracts VID from the bus-key-MAC'd
+    /// `REPORT_DISC_STRUCTURE` response.
+    fn read_vid_cert(session: &mut crate::drive::Drive, opts: &ScanOptions) -> Result<[u8; 16]> {
+        match Self::do_handshake_cert(session, opts) {
+            (Some(h), _) => Ok(h.volume_id),
+            (None, Some(e)) => Err(e),
+            (None, None) => Err(Error::AacsVidUnavailable),
+        }
+    }
+
+    /// SCSI handshake — drives the VID-acquisition flow and returns
+    /// a structured `HandshakeResult` for downstream key resolution.
+    /// Prefers the OEM path when `Drive::is_unlocked()` is true and
+    /// falls back to cert-based mutual auth otherwise.
+    ///
+    /// The OEM path produces only VID (no bus-key, so no
+    /// `read_data_key`); the cert path can produce both. AACS 2.0
+    /// content that needs read_data_key for bus decryption requires
+    /// the cert path.
+    ///
+    /// Returns `(handshake, error)`:
+    ///   * `(Some(_), None)`  — VID acquired
+    ///   * `(None, Some(_))`  — specific failure mode; only
+    ///     `AacsHostCertRejected` and `AacsVidUnavailable` are returned
+    ///     here (the OEM-path `DriveProfileMissing` / `VidCdbUnavailable`
+    ///     errors are caught internally and fall through to cert auth)
+    ///   * `(None, None)`     — handshake not attempted (no keydb;
+    ///     resolution will proceed with VID=zero and rely on path 1
+    ///     disc-hash → VUK lookup)
+    pub(super) fn do_handshake(
+        session: &mut crate::drive::Drive,
+        opts: &ScanOptions,
+    ) -> (Option<HandshakeResult>, Option<Error>) {
+        let unlocked = session.is_unlocked();
+        tracing::debug!(
+            target: "freemkv::disc",
+            phase = "handshake_entry",
+            unlocked,
+            "do_handshake entered"
+        );
+
+        if unlocked {
+            // Try OEM VID retrieval first. If the drive's profile
+            // doesn't carry the CDB template, or the response is
+            // malformed, fall through to cert-based auth.
+            match Self::read_vid(session, opts) {
+                Ok(volume_id) => {
+                    return (
+                        Some(HandshakeResult {
+                            volume_id,
+                            read_data_key: None,
+                        }),
+                        None,
+                    );
+                }
+                Err(Error::DriveProfileMissing) | Err(Error::VidCdbUnavailable) => {
+                    tracing::warn!(
+                        target: "freemkv::disc",
+                        phase = "handshake_oem_unavailable",
+                        "OEM VID path unavailable for this drive; trying cert handshake"
+                    );
+                }
+                Err(e) => {
+                    tracing::warn!(
+                        target: "freemkv::disc",
+                        phase = "handshake_oem_failed",
+                        error_code = e.code(),
+                        "OEM VID retrieval failed; trying cert handshake"
+                    );
+                }
+            }
+        }
+
+        Self::do_handshake_cert(session, opts)
+    }
+
+    /// Cert-based AACS handshake. The legacy auth path; still used as
+    /// the fallback when the OEM VID path isn't available or fails.
+    fn do_handshake_cert(
+        session: &mut crate::drive::Drive,
+        opts: &ScanOptions,
+    ) -> (Option<HandshakeResult>, Option<Error>) {
+        use crate::aacs;
+
+        // Host certs come from the caller's DriveCredentials (e.g. the keydb's
+        // host_certs(), sourced app-side) — the library does not load a keydb.
+        // Absent ⇒ no cert auth: an unlocked / LibreDrive drive already returned
+        // a Volume ID via the OEM path before reaching here, so this is the
+        // locked-drive-without-credentials case.
+        let host_certs: &[aacs::HostCert] = match &opts.credentials {
+            Some(c) if !c.host_certs.is_empty() => &c.host_certs,
+            _ => {
+                tracing::warn!(
+                    target: "freemkv::disc",
+                    phase = "handshake_no_credentials",
+                    "no drive credentials supplied; cert handshake skipped"
+                );
+                return (None, None);
+            }
+        };
+
+        let host_cert_count = host_certs.len();
+        tracing::debug!(
+            target: "freemkv::disc",
+            phase = "handshake_start",
+            host_cert_count,
+            "handshake starting"
+        );
+
+        // Cert-attempt wedge guard. An earlier version fired up to 16
+        // AACS authenticate attempts back-to-back with no pause. Each
+        // attempt is 5-10 SCSI REPORT_KEY/SEND_KEY exchanges. On a disc
+        // whose host cert isn't in the KEYDB (or one the drive rejects),
+        // that's 80-160 SCSI commands hammered at the drive in a few
+        // hundred milliseconds — and consumer optical drives can respond
+        // by entering a fast-fail firmware wedge state where every
+        // subsequent CDB returns ILLEGAL_REQUEST/INVALID_FIELD_IN_CDB
+        // (sense 05/24) until power-cycled. Observed live on a UHD scan:
+        // KEYDB miss → many cert attempts in a tight loop → wedge →
+        // forced power cycle to recover.
+        //
+        // Defense-in-depth: cap attempts, sleep between, and bail
+        // early on the drive's wedge sense so any later regression
+        // can't undo the protection silently.
+        const MAX_CERT_ATTEMPTS: usize = 3;
+        const PER_CERT_BACKOFF_MS: u64 = 1000;
+        let mut last_err_code: Option<u16> = None;
+        for (idx, hc) in host_certs.iter().take(MAX_CERT_ATTEMPTS).enumerate() {
+            if idx > 0 {
+                std::thread::sleep(std::time::Duration::from_millis(PER_CERT_BACKOFF_MS));
+            }
+            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(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, Some(Error::AacsVidUnavailable));
+                        }
+                    };
+                    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,
+                        }),
+                        None,
+                    );
+                }
+                Err(e) => {
+                    last_err_code = Some(e.code());
+                    // Log the real SCSI sense triple, not `e.code()` —
+                    // `code()` collapses every ScsiError to the flat
+                    // E_SCSI_ERROR constant and carries no sense key,
+                    // so it has no diagnostic value for auth-failure
+                    // routing.
+                    let sense = e.scsi_sense();
+                    // Drive wedge senses (ILLEGAL_REQUEST, sense key
+                    // 0x05). The drive isn't merely rejecting our
+                    // cert — it's signalling it won't talk to us
+                    // anymore. Trying more certs makes the wedge worse,
+                    // so bail out immediately. NOTE: this must read the
+                    // sense key off the structured ScsiSense, NOT off
+                    // `e.code()`; `code()` is a flat constant for every
+                    // ScsiError so the old `(code >> 8) & 0xFF` guard
+                    // never matched and was dead code (the very wedge
+                    // this defense exists to prevent could recur).
+                    if sense.map(|s| s.is_illegal_request()).unwrap_or(false) {
+                        tracing::warn!(
+                            target: "freemkv::disc",
+                            phase = "handshake_wedge_detected",
+                            cert_index = idx,
+                            sense_key = sense.map(|s| s.sense_key),
+                            asc = sense.map(|s| s.asc),
+                            ascq = sense.map(|s| s.ascq),
+                            "drive returned ILLEGAL_REQUEST during auth; bailing out to avoid wedge"
+                        );
+                        return (None, Some(Error::AacsHostCertRejected));
+                    }
+                    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 (capped at {} attempts to prevent firmware wedge)",
+            MAX_CERT_ATTEMPTS
+        );
+        (None, Some(Error::AacsHostCertRejected))
+    }
+
+    /// Build a keys-free AACS state that carries only the Volume ID (+ version
+    /// metadata), for callers that resolve Unit Keys out-of-band and have
+    /// disabled the local keydb. The VID is on-disc content read during the
+    /// handshake; preserving it here lets the out-of-band path use it. No keys
+    /// are present (`unit_keys` empty, `vuk` None), so the disc reports as
+    /// "encrypted, no keys" until the caller re-scans with a resolved Unit Key.
+    pub(super) fn resolve_vid_only(
+        udf_fs: &udf::UdfFs,
+        reader: &mut dyn SectorSource,
+        handshake: Option<&HandshakeResult>,
+    ) -> Result<AacsState> {
+        use crate::aacs;
+
+        let uk_ro_data = udf_fs
+            .read_file(reader, "/AACS/Unit_Key_RO.inf")
+            .or_else(|_| udf_fs.read_file(reader, "/AACS/DUPLICATE/Unit_Key_RO.inf"))
+            .map_err(|_| Error::AacsNoKeys)?;
+        let dh = aacs::disc_hash(&uk_ro_data);
+
+        let cc = udf_fs
+            .read_file(reader, "/AACS/Content000.cer")
+            .or_else(|_| udf_fs.read_file(reader, "/AACS/Content001.cer"))
+            .ok()
+            .as_deref()
+            .and_then(aacs::parse_content_cert);
+        let bus_encryption = cc.as_ref().map(|c| c.bus_encryption).unwrap_or(false);
+        let version = match cc.as_ref().map(|c| c.version) {
+            Some(aacs::AacsVersion::V10) => 1,
+            Some(_) => 2,
+            None if bus_encryption => 2,
+            None => 1,
+        };
+        // MKB_RO/RW are allocated to a fixed ~128 MiB and zero-padded; trim to
+        // the real record length (same as `read_aacs_inputs`). Without this the
+        // MKB stashed on `AacsState` — which `Disc::inputs()` and the device/
+        // processing-key `decrypt_with` derivation consume, and which a key
+        // source ships to an online service — is the full 128 MiB pad, not the
+        // ~few-MB record stream.
+        let mut mkb_bytes = udf_fs
+            .read_file(reader, "/AACS/MKB_RO.inf")
+            .or_else(|_| udf_fs.read_file(reader, "/AACS/MKB_RW.inf"))
+            .ok()
+            .unwrap_or_default();
+        // Trim to the real record length. truncate is a no-op when n >=
+        // len and correctly empties the vec when n == 0 (zeroed/corrupt
+        // MKB), so it never leaves the full ~128 MiB zero-pad on
+        // AacsState.mkb.
+        let n = aacs::mkb_content_len(&mkb_bytes);
+        mkb_bytes.truncate(n);
+        let mkb_ver = aacs::mkb_version(&mkb_bytes);
+
+        tracing::debug!(
+            target: "freemkv::disc",
+            phase = "scan_aacs_vid_only",
+            disc_hash = %aacs::disc_hash_hex(&dh),
+            version,
+            bus_encryption,
+            has_vid = handshake.is_some(),
+            "keydb disabled — carrying VID only, keys resolved out-of-band"
+        );
+
+        Ok(AacsState {
+            version,
+            bus_encryption,
+            mkb_version: mkb_ver,
+            disc_hash: aacs::disc_hash_hex(&dh),
+            key_source: KeyOrigin::ExternalUk,
+            vuk: None,
+            unit_keys: vec![],
+            read_data_key: handshake.and_then(|h| h.read_data_key),
+            volume_id: handshake.map(|h| h.volume_id).unwrap_or([0u8; 16]),
+            uk_ro: uk_ro_data,
+            mkb: mkb_bytes,
+        })
+    }
+}

src/disc/sweep.rs

@@ -0,0 +1,212 @@
+//! `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.
+//!
+//! A producer/consumer split overlaps the two stages on 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:
+//! - 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.
+//! - Only one SCSI command is in flight at a time; error-path timing
+//!   is identical and no new retry logic is introduced.
+
+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 = 64 * 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))?;
+                self.file.write_all(&buf)?;
+                self.map.record(pos, len, SectorStatus::Finished)?;
+            }
+            WorkItem::BisectGood { pos, buf } => {
+                self.file.seek(SeekFrom::Start(pos))?;
+                self.file.write_all(&buf[..])?;
+                self.map.record(pos, 2048, SectorStatus::Finished)?;
+            }
+            WorkItem::BisectBad { pos } => {
+                self.file.seek(SeekFrom::Start(pos))?;
+                self.file.write_all(&self.zero[..2048])?;
+                self.map.record(pos, 2048, SectorStatus::NonTrimmed)?;
+            }
+            WorkItem::SkipFill { pos, len } | WorkItem::GapFill { pos, len } => {
+                self.file.seek(SeekFrom::Start(pos))?;
+                // 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])?;
+                    filled += chunk as u64;
+                }
+                self.map.record(pos, len, SectorStatus::NonTrimmed)?;
+            }
+            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()?;
+
+        Ok(ConsumerSummary {
+            stats: self.map.stats(),
+        })
+    }
+}

src/drive.rs

@@ -1,131 +0,0 @@
-//! High-level drive session — the main API for consumers.
-//!
-//! Opens a drive, identifies it via standard SCSI commands,
-//! matches it against the profile database, and provides
-//! raw disc access methods.
-
-use std::path::Path;
-use crate::error::{Error, Result};
-use crate::scsi::ScsiTransport;
-use crate::identity::DriveId;
-use crate::profile::{self, DriveProfile, Chipset};
-use crate::platform::{Platform, DriveStatus};
-use crate::platform::mt1959::Mt1959;
-
-/// A complete drive session.
-///
-/// Handles: identify → match profile → create platform → execute commands.
-pub struct DriveSession {
-    scsi: Box<dyn ScsiTransport>,
-    platform: Box<dyn Platform>,
-    pub profile: DriveProfile,
-    pub drive_id: DriveId,
-}
-
-impl DriveSession {
-    /// Open a drive, identify it, and find the matching profile.
-    /// Uses the bundled profile database — no external files needed.
-    pub fn open(device: &Path) -> Result<Self> {
-        let mut transport = crate::scsi::open(device)?;
-        let profiles = profile::load_bundled()?;
-
-        // Identify drive via standard SCSI commands
-        // SPC-4 §6.4 (INQUIRY) + MMC-6 §5.3.10 (Feature 010Ch)
-        let drive_id = DriveId::from_drive(transport.as_mut())?;
-
-        // Match drive to a profile by INQUIRY fields
-        let profile = profile::find_by_drive_id(&profiles, &drive_id)
-            .cloned()
-            .ok_or_else(|| Error::UnsupportedDrive {
-                vendor_id: drive_id.vendor_id.trim().to_string(),
-                product_id: drive_id.product_id.trim().to_string(),
-                product_revision: drive_id.product_revision.trim().to_string(),
-            })?;
-
-        let platform: Box<dyn Platform> = match profile.chipset {
-            Chipset::MediaTek => {
-                Box::new(Mt1959::new(profile.clone()))
-            }
-            Chipset::Renesas => {
-                return Err(Error::UnsupportedDrive {
-                    vendor_id: drive_id.vendor_id.trim().to_string(),
-                    product_id: drive_id.product_id.trim().to_string(),
-                    product_revision: "Renesas not yet implemented".to_string(),
-                });
-            }
-        };
-
-        Ok(DriveSession {
-            scsi: transport,
-            platform,
-            profile,
-            drive_id,
-        })
-    }
-
-    /// Open with an explicit profile (skip auto-detection).
-    pub fn open_with_profile(device: &Path, profile: DriveProfile) -> Result<Self> {
-        let mut transport = crate::scsi::open(device)?;
-        let drive_id = DriveId::from_drive(transport.as_mut())?;
-
-        let platform: Box<dyn Platform> = match profile.chipset {
-            Chipset::MediaTek => {
-                Box::new(Mt1959::new(profile.clone()))
-            }
-            Chipset::Renesas => {
-                return Err(Error::UnsupportedDrive {
-                    vendor_id: drive_id.vendor_id.trim().to_string(),
-                    product_id: drive_id.product_id.trim().to_string(),
-                    product_revision: "Renesas not yet implemented".to_string(),
-                });
-            }
-        };
-
-        Ok(DriveSession {
-            scsi: transport,
-            platform,
-            profile,
-            drive_id,
-        })
-    }
-
-    /// Activate raw disc access mode.
-    pub fn unlock(&mut self) -> Result<()> {
-        self.platform.unlock(self.scsi.as_mut())
-    }
-
-    /// Check if raw disc access mode is enabled.
-    pub fn is_unlocked(&self) -> bool {
-        self.platform.is_unlocked()
-    }
-
-    /// Read drive status and feature flags.
-    pub fn status(&mut self) -> Result<DriveStatus> {
-        self.platform.status(self.scsi.as_mut())
-    }
-
-    /// Read drive configuration block.
-    pub fn read_config(&mut self) -> Result<Vec<u8>> {
-        self.platform.read_config(self.scsi.as_mut())
-    }
-
-    /// Read hardware register.
-    pub fn read_register(&mut self, index: u8) -> Result<[u8; 16]> {
-        self.platform.read_register(self.scsi.as_mut(), index)
-    }
-
-    /// Calibrate read speed for the current disc.
-    pub fn calibrate(&mut self) -> Result<()> {
-        self.platform.calibrate(self.scsi.as_mut())
-    }
-
-    /// Read raw disc sectors.
-    pub fn read_sectors(&mut self, lba: u32, count: u16, buf: &mut [u8]) -> Result<usize> {
-        self.platform.read_sectors(self.scsi.as_mut(), lba, count, buf)
-    }
-
-    /// Generic probe command.
-    pub fn probe(&mut self, sub_cmd: u8, address: u32, length: u32) -> Result<Vec<u8>> {
-        self.platform.probe(self.scsi.as_mut(), sub_cmd, address, length)
-    }
-}

src/drive/capture.rs

@@ -0,0 +1,122 @@
+//! Drive data capture — read hardware information via SCSI.
+
+use crate::drive::Drive;
+use crate::error::Result;
+
+/// Raw data captured from a drive's SCSI responses.
+#[derive(Debug, Clone)]
+pub struct DriveCapture {
+    /// Raw INQUIRY response (96 bytes)
+    pub inquiry: Vec<u8>,
+    /// Raw GET_CONFIG 010C response
+    pub gc_010c: Vec<u8>,
+    /// GET_CONFIG feature responses: (feature_code, feature_name, data)
+    pub features: Vec<CapturedFeature>,
+    /// REPORT_KEY RPC state
+    pub rpc_state: Option<Vec<u8>>,
+    /// MODE SENSE page 2A (capabilities)
+    pub mode_2a: Option<Vec<u8>>,
+    /// READ_BUFFER 0xF1 (Pioneer vendor data)
+    pub rb_f1: Option<Vec<u8>>,
+    /// READ_BUFFER mode 6 (MTK vendor data)
+    pub rb_mode6: Option<Vec<u8>>,
+}
+
+/// A single GET CONFIGURATION feature response from the drive.
+#[derive(Debug, Clone)]
+pub struct CapturedFeature {
+    /// MMC-6 GET CONFIGURATION feature code (e.g. `0x010D` = AACS).
+    pub code: u16,
+    /// Static human-readable label from the internal `FEATURES` table —
+    /// not a device-reported string.
+    pub name: &'static str,
+    /// Raw feature-descriptor payload bytes, with the 8-byte GET
+    /// CONFIGURATION header stripped (i.e. `buf[8..]`). Unlike
+    /// [`DriveCapture::gc_010c`], which retains the full header.
+    pub data: Vec<u8>,
+}
+
+/// Feature codes to capture.
+const FEATURES: &[(u16, &str)] = &[
+    (0x0000, "Profile List"),
+    (0x0001, "Core"),
+    (0x0003, "Removable Medium"),
+    (0x0010, "Random Readable"),
+    (0x001D, "Multi-Read"),
+    (0x001E, "CD Read"),
+    (0x001F, "DVD Read"),
+    (0x0040, "BD Read"),
+    (0x0041, "BD Write"),
+    (0x0100, "Power Management"),
+    (0x0102, "Embedded Changer"),
+    (0x0107, "Real Time Streaming"),
+    (0x0108, "Serial Number"),
+    (0x010C, "Firmware Information"),
+    (0x010D, "AACS"),
+];
+
+/// Capture all available drive data via SCSI commands.
+/// Returns raw responses — no formatting, no zipping, no presentation.
+pub fn capture_drive_data(session: &mut Drive) -> Result<DriveCapture> {
+    let id = &session.drive_id;
+
+    // Already have INQUIRY from drive open
+    let inquiry = id.raw_inquiry.clone();
+    let gc_010c = id.raw_gc_010c.clone();
+
+    // Capture GET_CONFIG features using Drive's query methods
+    let mut features = Vec::new();
+    for &(code, name) in FEATURES {
+        if let Some(data) = session.get_config_feature(code) {
+            features.push(CapturedFeature { code, name, data });
+        }
+    }
+
+    // Vendor-specific READ_BUFFER queries
+    let rb_f1 = session.read_buffer(0x02, 0xF1, 48); // Pioneer
+    let rb_mode6 = session.read_buffer(0x06, 0x00, 32); // MTK
+
+    // Standard queries
+    let rpc_state = session.report_key_rpc_state();
+    let mode_2a = session.mode_sense_page(0x2A);
+
+    Ok(DriveCapture {
+        inquiry,
+        gc_010c,
+        features,
+        rpc_state,
+        mode_2a,
+        rb_f1,
+        rb_mode6,
+    })
+}
+
+/// Mask a string for privacy (letters->A, digits->0).
+pub fn mask_string(s: &str) -> String {
+    s.chars()
+        .map(|c| {
+            if c.is_ascii_alphabetic() {
+                'A'
+            } else if c.is_ascii_digit() {
+                '0'
+            } else {
+                c
+            }
+        })
+        .collect()
+}
+
+/// Mask bytes for privacy.
+pub fn mask_bytes(data: &[u8]) -> Vec<u8> {
+    data.iter()
+        .map(|&b| {
+            if b.is_ascii_alphabetic() {
+                b'A'
+            } else if b.is_ascii_digit() {
+                b'0'
+            } else {
+                b
+            }
+        })
+        .collect()
+}

src/drive/linux.rs

@@ -0,0 +1,113 @@
+//! Linux drive discovery and device resolution.
+
+use crate::drive::DeviceResolution;
+use crate::error::{Error, Result};
+use crate::identity::DriveId;
+
+/// SCSI peripheral device type 5 = MMC / optical (CD/DVD/BD), held in the
+/// low 5 bits of INQUIRY byte 0 (the high 3 bits are the peripheral
+/// qualifier, masked off here).
+const SCSI_PERIPHERAL_TYPE_OPTICAL: u8 = 0x05;
+
+/// Discover optical drives by enumerating `/dev/sg*` SCSI-generic nodes,
+/// opening each, running INQUIRY, and keeping only devices whose
+/// peripheral device type is optical (MMC, type 0x05).
+///
+/// Devices where `scsi::open` or `DriveId::from_drive` fail are silently
+/// skipped — that is intentional for enumeration (a busy or wedged node
+/// shouldn't abort discovery of the others).
+pub fn find_drives() -> Vec<(String, DriveId)> {
+    let mut drives = Vec::new();
+    for name in enumerate_sg_names() {
+        let path = format!("/dev/{name}");
+        if !std::path::Path::new(&path).exists() {
+            continue;
+        }
+        if let Ok(mut transport) = crate::scsi::open(std::path::Path::new(&path)) {
+            if let Ok(id) = DriveId::from_drive(transport.as_mut()) {
+                if !id.raw_inquiry.is_empty()
+                    && (id.raw_inquiry[0] & 0x1F) == SCSI_PERIPHERAL_TYPE_OPTICAL
+                {
+                    drives.push((path, id));
+                }
+            }
+        }
+    }
+    drives
+}
+
+/// Enumerate `sg*` device names. Linux assigns `/dev/sgN` sequentially
+/// across *all* SCSI-generic devices (disks, tape, HBAs, optical), so a
+/// fixed `sg0..15` range can miss an optical drive on a host with many
+/// targets. Prefer the exact present-device list from
+/// `/sys/class/scsi_generic/`; fall back to a bounded `sg0..15` probe
+/// only when sysfs is unreadable (minimal containers).
+fn enumerate_sg_names() -> Vec<String> {
+    let mut names = Vec::new();
+    if let Ok(entries) = std::fs::read_dir("/sys/class/scsi_generic") {
+        for entry in entries.flatten() {
+            let name = entry.file_name().to_string_lossy().to_string();
+            if name.starts_with("sg") {
+                names.push(name);
+            }
+        }
+    } else {
+        for i in 0..16 {
+            let name = format!("sg{i}");
+            if std::path::Path::new(&format!("/dev/{name}")).exists() {
+                names.push(name);
+            }
+        }
+    }
+    names.sort();
+    names
+}
+
+/// Resolve a device path to its raw `/dev/sg*` SCSI-generic node.
+///
+/// - `/dev/sg*` paths pass through unchanged ([`DeviceResolution::Direct`]).
+/// - `/dev/sr*` block paths are matched (by vendor/product/serial) to the
+///   corresponding `/dev/sg*` node ([`DeviceResolution::SrToSg`]); if no
+///   match is found the original path is returned with
+///   [`DeviceResolution::SrNoSgMatch`].
+/// - Any other existing path passes through as [`DeviceResolution::Direct`].
+#[allow(dead_code)]
+pub fn resolve_device(path: &str) -> Result<(String, DeviceResolution)> {
+    if path.contains("/sg") {
+        if !std::path::Path::new(path).exists() {
+            return Err(Error::DeviceNotFound {
+                path: path.to_string(),
+            });
+        }
+        return Ok((path.to_string(), DeviceResolution::Direct));
+    }
+    if path.contains("/sr") {
+        let mut sr_transport = crate::scsi::open(std::path::Path::new(path))?;
+        let sr_id = DriveId::from_drive(sr_transport.as_mut())?;
+        drop(sr_transport);
+        for (sg_path, sg_id) in find_drives() {
+            // Require a non-empty serial before treating vendor/product/
+            // serial as a unique match. serial_number falls back to an
+            // empty string when GET CONFIGURATION 0108h is unavailable
+            // (common on OEM drives); two same-model drives would then
+            // both compare equal and the first in enumeration order would
+            // win silently, resolving sr1 to sr0's sg node. An empty
+            // serial can't disambiguate, so fall through to the no-match
+            // path instead.
+            if !sr_id.serial_number.is_empty()
+                && sg_id.vendor_id == sr_id.vendor_id
+                && sg_id.product_id == sr_id.product_id
+                && sg_id.serial_number == sr_id.serial_number
+            {
+                return Ok((sg_path, DeviceResolution::SrToSg));
+            }
+        }
+        return Ok((path.to_string(), DeviceResolution::SrNoSgMatch));
+    }
+    if !std::path::Path::new(path).exists() {
+        return Err(Error::DeviceNotFound {
+            path: path.to_string(),
+        });
+    }
+    Ok((path.to_string(), DeviceResolution::Direct))
+}

src/drive/macos.rs

@@ -0,0 +1,55 @@
+//! macOS drive discovery and device resolution.
+//!
+//! `find_drives` uses IOKit registry enumeration (via `scsi::list_drives`)
+//! to discover optical drives without exclusive access or unmounts. Only
+//! the returned paths are then opened for INQUIRY to build full `DriveId`.
+
+use crate::drive::DeviceResolution;
+use crate::error::{Error, Result};
+use crate::identity::DriveId;
+
+/// SCSI peripheral device type 5 = MMC / optical, in the low 5 bits of
+/// INQUIRY byte 0.
+const SCSI_PERIPHERAL_TYPE_OPTICAL: u8 = 0x05;
+
+/// Discover optical drives via the IOKit registry (`scsi::list_drives`),
+/// then open each candidate for INQUIRY to build a full `DriveId`.
+///
+/// Any drive where `scsi::open` or `DriveId::from_drive` fails, or whose
+/// peripheral device type is not optical (MMC, type 0x05), is silently
+/// skipped — the same MMC filter the Linux and Windows backends apply.
+pub fn find_drives() -> Vec<(String, DriveId)> {
+    let mut drives = Vec::new();
+    let discovered = crate::scsi::list_drives();
+    for info in discovered {
+        let path = std::path::Path::new(&info.path);
+        match crate::scsi::open(path) {
+            Ok(mut transport) => {
+                if let Ok(id) = DriveId::from_drive(transport.as_mut()) {
+                    if !id.raw_inquiry.is_empty()
+                        && (id.raw_inquiry[0] & 0x1F) == SCSI_PERIPHERAL_TYPE_OPTICAL
+                    {
+                        drives.push((info.path.clone(), id));
+                    }
+                }
+            }
+            Err(_) => {
+                continue;
+            }
+        }
+    }
+    drives
+}
+
+/// Resolve a device path on macOS. There is no `sr`→`sg` style
+/// substitution here (that is a Linux concern), so any existing path is
+/// returned unchanged as [`DeviceResolution::Direct`]; the
+/// [`DeviceResolution`] return exists for cross-platform signature parity.
+pub fn resolve_device(path: &str) -> Result<(String, DeviceResolution)> {
+    if !std::path::Path::new(path).exists() {
+        return Err(Error::DeviceNotFound {
+            path: path.to_string(),
+        });
+    }
+    Ok((path.to_string(), DeviceResolution::Direct))
+}

src/drive/windows.rs

@@ -0,0 +1,99 @@
+//! Windows drive discovery and device resolution.
+
+use crate::drive::DeviceResolution;
+use crate::error::Result;
+use crate::identity::DriveId;
+use std::path::Path;
+
+/// SCSI peripheral device type 5 = MMC / optical, in the low 5 bits of
+/// INQUIRY byte 0.
+const SCSI_PERIPHERAL_TYPE_OPTICAL: u8 = 0x05;
+
+/// Discover optical drives. Probes `\\.\CdRom0..15` first; only if none
+/// are found does it fall back to scanning drive letters `D..Z`. Each
+/// candidate is opened, INQUIRY'd, and kept only if its peripheral device
+/// type is optical (MMC, type 0x05). Returns normalized `\\.\` paths.
+pub fn find_drives() -> Vec<(String, DriveId)> {
+    let mut drives = Vec::new();
+
+    // Try CdRom0..CdRom15
+    for i in 0..16 {
+        let path = format!("\\\\.\\CdRom{}", i);
+        if let Ok(mut transport) = crate::scsi::open(Path::new(&path)) {
+            if let Ok(id) = DriveId::from_drive(transport.as_mut()) {
+                if !id.raw_inquiry.is_empty()
+                    && (id.raw_inquiry[0] & 0x1F) == SCSI_PERIPHERAL_TYPE_OPTICAL
+                {
+                    drives.push((path, id));
+                }
+            }
+        }
+    }
+
+    // Also try drive letters if CdRom didn't find anything
+    if drives.is_empty() {
+        for letter in b'D'..=b'Z' {
+            let path = format!("{}:", letter as char);
+            if let Ok(mut transport) = crate::scsi::open(Path::new(&path)) {
+                if let Ok(id) = DriveId::from_drive(transport.as_mut()) {
+                    if !id.raw_inquiry.is_empty()
+                        && (id.raw_inquiry[0] & 0x1F) == SCSI_PERIPHERAL_TYPE_OPTICAL
+                    {
+                        // Normalize so returned paths are consistently in
+                        // \\.\ form regardless of which loop matched.
+                        drives.push((normalize_path(&path), id));
+                    }
+                }
+            }
+        }
+    }
+
+    drives
+}
+
+/// Resolve a device path to its normalized Windows `\\.\` form. Windows
+/// has no `sr`→`sg` symlink-target indirection, so resolution is purely a
+/// path normalization and always reports [`DeviceResolution::Direct`].
+pub fn resolve_device(path: &str) -> Result<(String, DeviceResolution)> {
+    Ok((normalize_path(path), DeviceResolution::Direct))
+}
+
+/// Normalize a device path to Windows \\.\X: format.
+///
+/// Accepts: "D:", "D:\\", "\\.\D:", "\\.\CdRom0"
+///
+/// NOTE: A near-identical `normalize_device_path` exists in `scsi::windows`.
+/// Both are kept because they live in separate `cfg(windows)` modules that
+/// cannot easily share a helper without introducing cross-module coupling.
+fn normalize_path(path: &str) -> String {
+    if path.starts_with("\\\\.\\") {
+        return path.to_string();
+    }
+    let trimmed = path.trim_end_matches('\\');
+    if trimmed.len() == 2 && trimmed.as_bytes()[1] == b':' {
+        return format!("\\\\.\\{}", trimmed);
+    }
+    format!("\\\\.\\{}", path)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn normalize_drive_letter() {
+        assert_eq!(normalize_path("D:"), "\\\\.\\D:");
+        assert_eq!(normalize_path("E:\\"), "\\\\.\\E:");
+    }
+
+    #[test]
+    fn normalize_already_prefixed() {
+        assert_eq!(normalize_path("\\\\.\\D:"), "\\\\.\\D:");
+        assert_eq!(normalize_path("\\\\.\\CdRom0"), "\\\\.\\CdRom0");
+    }
+
+    #[test]
+    fn normalize_cdrom() {
+        assert_eq!(normalize_path("CdRom0"), "\\\\.\\CdRom0");
+    }
+}

src/drm/mod.rs

@@ -0,0 +1,306 @@
+//! Top-level DRM scheme dispatch.
+//!
+//! Four content-protection schemes ride through a single
+//! detect-then-load pipeline:
+//!
+//! | Scheme              | Discriminator                                  |
+//! |---------------------|------------------------------------------------|
+//! | [`DrmScheme::Css`]  | DVD probe sector flagged scrambled             |
+//! | [`DrmScheme::Aacs10`] | Content cert type byte `0x00`                |
+//! | [`DrmScheme::Aacs20`] | Content cert type byte `!= 0x00`, no Variant |
+//! | [`DrmScheme::Aacs21`] | as Aacs20 + MKB Variant records `0x82`/`0x83` |
+//!
+//! The content cert type byte only ever decodes to V10 (`0x00`) or V20
+//! (`!= 0x00`); the V21 promotion is decided solely by the MKB Variant
+//! walk in [`DrmScheme::detect`], never by the cert byte.
+//!
+//! Detection happens from a [`DrmProbe`] (raw inputs the caller has
+//! already extracted from the disc); resolution runs through a
+//! [`DrmContext`] (the full set of inputs the loaders need).
+//!
+//! AACS 2.1 discs that are fully keyed in `keydb.cfg` decrypt through
+//! the same classical Media Key chain as AACS 2.0, so [`DrmScheme::load`]
+//! routes the `Aacs21` arm to [`crate::aacs::resolve_keys_v2`] — the
+//! KEYDB lookup paths (MK+VID, disc-hash VUK, pre-decrypted unit keys)
+//! succeed for any disc present in the keydb. The dedicated Variant/KCD
+//! chain ([`crate::aacs::resolve_keys_v21`]) stays reachable as a
+//! library entry point for fixture-driven validation but is not yet on
+//! the dispatch path; it is enabled once KCD validation against a real
+//! Variant-scheme disc lands.
+
+use crate::aacs;
+use crate::css;
+
+/// Which content-protection scheme governs a disc.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DrmScheme {
+    /// DVD Content Scramble System.
+    Css,
+    /// AACS 1.0 — original BD-ROM.
+    Aacs10,
+    /// AACS 2.0 — UHD-BD, classical Media Key chain.
+    Aacs20,
+    /// AACS 2.1 — UHD-BD with Media Key Variant chain.
+    Aacs21,
+}
+
+/// Inputs to [`DrmScheme::detect`]. All borrows — caller retains
+/// ownership.
+pub struct DrmProbe<'a> {
+    /// 2048-byte sample sector from inside a DVD title's extents. Used
+    /// only for CSS scramble-flag detection. `None` for non-DVD discs.
+    pub dvd_sample_sector: Option<&'a [u8]>,
+    /// Content Certificate file bytes (typically `/AACS/Content000.cer`).
+    /// `None` when the disc has no AACS directory.
+    pub content_cert: Option<&'a [u8]>,
+    /// MKB file bytes (typically `/AACS/MKB_RW.inf`). Required to
+    /// distinguish AACS 2.0 from AACS 2.1.
+    pub mkb: Option<&'a [u8]>,
+}
+
+/// Inputs to [`DrmScheme::load`]. Carries everything needed by either
+/// the AACS or CSS loader.
+pub struct DrmContext<'a> {
+    /// AACS resolver inputs — required when the scheme is any AACS
+    /// variant.
+    pub aacs: Option<aacs::ResolveContext<'a>>,
+    /// CSS resolver inputs — required when the scheme is [`DrmScheme::Css`].
+    pub css: Option<css::CssContext<'a>>,
+}
+
+/// Resolved key material, tagged by scheme.
+#[derive(Debug)]
+pub enum ResolvedScheme {
+    Css(css::CssState),
+    Aacs(aacs::ResolvedKeys),
+}
+
+impl DrmScheme {
+    /// Detect which DRM scheme protects the disc described by `probe`.
+    ///
+    /// Returns `None` for unencrypted media. The order is intentional:
+    /// CSS is checked first (DVD-format probe), then AACS (Blu-ray
+    /// format).
+    pub fn detect(probe: &DrmProbe<'_>) -> Option<DrmScheme> {
+        // CSS — DVD probe sector carries the scramble flag.
+        if let Some(sector) = probe.dvd_sample_sector {
+            if css::is_scrambled(sector) {
+                return Some(DrmScheme::Css);
+            }
+        }
+
+        // AACS — content cert type byte distinguishes V10 from V20+.
+        // V21 promotion requires MKB Variant records.
+        let cc = probe.content_cert.and_then(aacs::parse_content_cert)?;
+        match cc.version {
+            aacs::AacsVersion::V10 => Some(DrmScheme::Aacs10),
+            aacs::AacsVersion::V20 | aacs::AacsVersion::V21 => {
+                if let Some(mkb) = probe.mkb {
+                    let recs = aacs::variants::walk_mkb(mkb);
+                    if aacs::variants::is_variant_mkb(&recs) {
+                        return Some(DrmScheme::Aacs21);
+                    }
+                }
+                Some(DrmScheme::Aacs20)
+            }
+        }
+    }
+
+    /// Run key resolution for this scheme against `ctx`.
+    ///
+    /// Returns `None` when the scheme's resolver could not produce keys
+    /// (missing context, KEYDB miss, failed crypto walk, etc.).
+    ///
+    /// The `Aacs21` arm resolves through the classical [`aacs::resolve_keys_v2`]
+    /// chain: AACS 2.1 discs already keyed in `keydb.cfg` decrypt identically
+    /// to AACS 2.0 (the KEYDB MK+VID / disc-hash VUK / pre-decrypted unit-key
+    /// paths succeed for any disc in the keydb), and `resolve_keys_v2` promotes
+    /// the resolved version to V21 when Variant MKB records are present. The
+    /// dedicated Variant/KCD chain ([`aacs::resolve_keys_v21`]) is kept opt-in
+    /// until KCD validation against a real Variant-scheme disc lands.
+    pub fn load(self, ctx: &mut DrmContext<'_>) -> Option<ResolvedScheme> {
+        match self {
+            DrmScheme::Css => ctx
+                .css
+                .as_mut()
+                .and_then(css::resolve)
+                .map(ResolvedScheme::Css),
+            DrmScheme::Aacs10 => ctx
+                .aacs
+                .as_ref()
+                .and_then(aacs::resolve_keys_v1)
+                .map(ResolvedScheme::Aacs),
+            // Both Aacs20 and Aacs21 route through the classical V2 chain.
+            // The Variant/KCD chain (resolve_keys_v21) is wired but gated;
+            // a keyed-in V21 disc resolves via the KEYDB paths here.
+            DrmScheme::Aacs20 | DrmScheme::Aacs21 => ctx
+                .aacs
+                .as_ref()
+                .and_then(aacs::resolve_keys_v2)
+                .map(ResolvedScheme::Aacs),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Build a minimal cert: type byte + bus-encryption byte + 6 zero
+    // cc_id bytes.
+    fn cert(type_byte: u8) -> Vec<u8> {
+        let mut v = vec![0u8; 8];
+        v[0] = type_byte;
+        v
+    }
+
+    // Synthetic AACS 2.x MKB with no Variant records.
+    fn mkb_classical() -> Vec<u8> {
+        vec![
+            0x10, 0x00, 0x00, 0x0C, 0x48, 0x14, 0x10, 0x03, 0x00, 0x00, 0x00, 0x4D,
+        ]
+    }
+
+    // Synthetic AACS 2.x MKB with a 0x82 + 0x83 record pair.
+    fn mkb_with_variant() -> Vec<u8> {
+        let mut m = mkb_classical();
+        m.extend_from_slice(&[0x82, 0x00, 0x00, 0x14]);
+        m.extend_from_slice(&[0xEE; 16]);
+        m.extend_from_slice(&[0x83, 0x00, 0x00, 0x14]);
+        m.extend_from_slice(&[0x55; 16]);
+        m
+    }
+
+    // Synthetic scrambled DVD sector — byte 0x14 carries the CSS
+    // scramble flag in bits 4-5.
+    fn scrambled_dvd_sector() -> Vec<u8> {
+        let mut s = vec![0u8; 2048];
+        s[0x14] = 0x30;
+        s
+    }
+
+    #[test]
+    fn detect_returns_none_for_unencrypted() {
+        let probe = DrmProbe {
+            dvd_sample_sector: None,
+            content_cert: None,
+            mkb: None,
+        };
+        assert_eq!(DrmScheme::detect(&probe), None);
+    }
+
+    #[test]
+    fn detect_returns_css_for_scrambled_dvd() {
+        let sector = scrambled_dvd_sector();
+        let probe = DrmProbe {
+            dvd_sample_sector: Some(&sector),
+            content_cert: None,
+            mkb: None,
+        };
+        assert_eq!(DrmScheme::detect(&probe), Some(DrmScheme::Css));
+    }
+
+    #[test]
+    fn detect_returns_aacs10_for_type0_cert() {
+        let c = cert(0x00);
+        let probe = DrmProbe {
+            dvd_sample_sector: None,
+            content_cert: Some(&c),
+            mkb: None,
+        };
+        assert_eq!(DrmScheme::detect(&probe), Some(DrmScheme::Aacs10));
+    }
+
+    #[test]
+    fn detect_returns_aacs20_for_type1_cert_no_variant() {
+        let c = cert(0x01);
+        let mkb = mkb_classical();
+        let probe = DrmProbe {
+            dvd_sample_sector: None,
+            content_cert: Some(&c),
+            mkb: Some(&mkb),
+        };
+        assert_eq!(DrmScheme::detect(&probe), Some(DrmScheme::Aacs20));
+    }
+
+    #[test]
+    fn detect_returns_aacs21_for_type1_cert_with_variant() {
+        let c = cert(0x01);
+        let mkb = mkb_with_variant();
+        let probe = DrmProbe {
+            dvd_sample_sector: None,
+            content_cert: Some(&c),
+            mkb: Some(&mkb),
+        };
+        assert_eq!(DrmScheme::detect(&probe), Some(DrmScheme::Aacs21));
+    }
+
+    #[test]
+    fn detect_returns_aacs20_when_mkb_absent() {
+        // Type-1 cert but no MKB to upgrade with -> Aacs20.
+        let c = cert(0x01);
+        let probe = DrmProbe {
+            dvd_sample_sector: None,
+            content_cert: Some(&c),
+            mkb: None,
+        };
+        assert_eq!(DrmScheme::detect(&probe), Some(DrmScheme::Aacs20));
+    }
+
+    #[test]
+    fn load_aacs21_routes_through_v2_resolver() {
+        // The Aacs21 arm shares the classical V2 resolver with Aacs20, so a
+        // V21 disc keyed in keydb.cfg resolves instead of being short-circuited
+        // to None at the dispatcher. With an EMPTY keydb both schemes fail key
+        // resolution identically — proving Aacs21 takes the resolver path
+        // rather than an unconditional `None` gate.
+        let uk_ro = vec![0u8; 256];
+        let vid = [0u8; 16];
+        let keydb = aacs::KeyDb::empty();
+        let providers: &[&dyn aacs::KeyProvider] = &[&keydb];
+
+        let make_ctx = || DrmContext {
+            aacs: Some(aacs::ResolveContext {
+                unit_key_ro: &uk_ro,
+                content_cert: None,
+                volume_id: &vid,
+                providers,
+                mkb: None,
+            }),
+            css: None,
+        };
+
+        let v20 = DrmScheme::Aacs20.load(&mut make_ctx());
+        let v21 = DrmScheme::Aacs21.load(&mut make_ctx());
+        // Same resolver, same (empty-keydb) outcome.
+        assert_eq!(v20.is_none(), v21.is_none());
+        // Empty keydb -> no keys for either.
+        assert!(v21.is_none());
+    }
+
+    /// Exercises the V21 helper directly. Gated `#[ignore]` because
+    /// the chain reaches `MediaKeyVariantError::VariantsTableUnavailable`
+    /// without a real Variant-scheme disc to fix the per-uv table
+    /// layout against — running it here would assert only the
+    /// not-yet-wired error code. Kept as a wiring smoke-test for
+    /// future enablement.
+    #[test]
+    #[ignore]
+    fn resolve_keys_v21_helper_exists() {
+        let uk_ro = vec![0u8; 256];
+        let vid = [0xAAu8; 16];
+        let keydb = aacs::KeyDb::empty();
+        let providers: &[&dyn aacs::KeyProvider] = &[&keydb];
+        let mkb = mkb_with_variant();
+        let ctx = aacs::ResolveContext {
+            unit_key_ro: &uk_ro,
+            content_cert: None,
+            volume_id: &vid,
+            providers,
+            mkb: Some(&mkb),
+        };
+        // Just confirm the symbol is callable; we don't assert on the
+        // result.
+        let _ = aacs::resolve_keys_v21(&ctx);
+    }
+}

src/event.rs

@@ -0,0 +1,124 @@
+//! Event system for progress and status reporting.
+//!
+//! The lib fires events during operations like rip().
+//! The app registers a callback to receive them.
+//! No display logic, no English text — just data.
+//!
+//! ```rust,ignore
+//! disc.rip(&mut session, 0, output, |event| {
+//!     match event.kind {
+//!         EventKind::BytesRead { bytes, total } => update_progress(bytes, total),
+//!         EventKind::SectorSkipped { sector } => log_skip(sector),
+//!         EventKind::BatchSizeChanged { new_size, .. } => note_recovery(new_size),
+//!         _ => {}
+//!     }
+//! });
+//! ```
+//!
+//! Note: the library currently emits only `BytesRead`, `SectorSkipped`,
+//! and `BatchSizeChanged`. The other [`EventKind`] variants are part of
+//! the stable event vocabulary for consumers (and future emit sites) but
+//! are not produced by the library today.
+
+use crate::error::Error;
+
+/// An event fired by the lib during operations.
+#[derive(Debug)]
+pub struct Event {
+    pub kind: EventKind,
+}
+
+/// Types of events the lib can fire.
+#[derive(Debug)]
+pub enum EventKind {
+    // ── Init sequence events ────────────────────────────────────────
+    /// Drive opened successfully.
+    DriveOpened { device: String },
+
+    /// Drive is ready (disc spun up).
+    DriveReady,
+
+    /// Firmware init completed.
+    InitComplete { success: bool },
+
+    /// Disc probe completed.
+    ProbeComplete { success: bool },
+
+    /// Disc scan completed.
+    ScanComplete { titles: usize },
+
+    // ── Read events ─────────────────────────────────────────────────
+    /// Bytes successfully read and written to output.
+    BytesRead {
+        /// Bytes written so far.
+        bytes: u64,
+        /// Total bytes expected (0 if unknown).
+        total: u64,
+    },
+
+    /// A read error occurred. The lib will retry automatically.
+    ReadError {
+        /// Sector that failed.
+        sector: u64,
+        /// Error code.
+        error: Error,
+    },
+
+    /// Retrying a failed read.
+    Retry {
+        /// Current attempt number (1-based).
+        attempt: u32,
+    },
+
+    /// Drive speed changed (error recovery or restoration).
+    SpeedChange {
+        /// New speed in KB/s (0xFFFF = max).
+        speed_kbs: u16,
+    },
+
+    /// Starting a new disc extent.
+    ExtentStart {
+        /// Extent index (0-based).
+        index: usize,
+        /// First sector of extent.
+        start_sector: u64,
+        /// Number of sectors in extent.
+        sector_count: u64,
+    },
+
+    /// Sector recovered after a retry (Drive::read multi-phase recovery).
+    SectorRecovered { sector: u64 },
+
+    /// Sector unreadable, zero-filled (skip mode).
+    SectorSkipped { sector: u64 },
+
+    /// Adaptive batch sizer changed the read size.
+    ///
+    /// Fires on shrink (read failed at larger size) and on probe-up
+    /// (enough clean reads to try larger again). Consumers use this to
+    /// display a "recovering" state distinct from "ripping normally".
+    BatchSizeChanged {
+        new_size: u16,
+        reason: BatchSizeReason,
+    },
+
+    /// Operation complete.
+    Complete {
+        /// Total bytes written.
+        bytes: u64,
+        /// Total read errors encountered.
+        errors: u32,
+    },
+}
+
+/// Why the adaptive batch sizer changed size.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum BatchSizeReason {
+    /// Read failed; sizer halved the batch.
+    Shrunk,
+    /// Clean-read streak threshold hit; sizer doubled toward preferred.
+    Probed,
+}
+
+/// A no-op event handler. Ignores all events.
+pub fn ignore(_event: Event) {}

src/halt.rs

@@ -0,0 +1,177 @@
+//! 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`. A bridge for
+    /// callers that already hold an `Arc<AtomicBool>` cancellation flag
+    /// and want to adopt the token API without allocating a new 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>`. The inverse of
+    /// [`from_arc`](Self::from_arc): hand the shared flag to an API that
+    /// still takes a raw `Arc<AtomicBool>` rather than a `Halt`.
+    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()
+    }
+}
+
+/// Shared poll interval for halt-aware loops.
+///
+/// `bounded_syscall` checks the cancellation flag and the deadline
+/// every [`POLL_INTERVAL`] while blocked on a worker; the same
+/// cadence governs `Pipeline::send_with_halt`'s `try_send` retry.
+/// 250 ms is the sweet spot between responsiveness (operator presses
+/// Stop, sees it take effect within ~quarter-second) and waste
+/// (atomic load + clock read is cheap but not free at thousands of
+/// hertz).
+///
+/// Centralised here so the half-dozen halt-polling loops across `io`
+/// can't drift apart silently.
+pub const POLL_INTERVAL: std::time::Duration = std::time::Duration::from_millis(250);
+
+#[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());
+    }
+}

src/identity.rs

@@ -8,7 +8,7 @@
 //!   MMC-6 §5.3.10 — Feature 010Ch (Firmware Information)
 
 use crate::error::Result;
-use crate::scsi::{ScsiTransport, DataDirection};
+use crate::scsi::{DataDirection, ScsiTransport};
 
 /// Drive identity from standard SCSI commands.
 ///
@@ -39,8 +39,14 @@ pub struct DriveId {
     /// Format: CCYYMMDDHHMI (12 ASCII characters)
     pub firmware_date: String,
 
+    /// Drive serial number — GET CONFIGURATION Feature 0108h
+    pub serial_number: String,
+
     /// Raw 96-byte INQUIRY response for additional parsing if needed.
     pub raw_inquiry: Vec<u8>,
+
+    /// Raw GET CONFIGURATION Feature 010Ch response bytes.
+    pub raw_gc_010c: Vec<u8>,
 }
 
 impl DriveId {
@@ -51,22 +57,71 @@ impl DriveId {
         let cdb_inq = [0x12, 0x00, 0x00, 0x00, 0x60, 0x00];
         transport.execute(&cdb_inq, DataDirection::FromDevice, &mut inquiry, 5000)?;
 
-        // GET CONFIGURATION Feature 010Ch — MMC-6 §6.6
+        // GET CONFIGURATION Feature 010Ch — MMC-6 §6.6.
+        // Best-effort: 010Ch (Firmware Information) is an optional feature.
+        // A drive that lacks it may CHECK CONDITION rather than return an
+        // empty descriptor, so a failure here is treated as feature-absent
+        // (empty firmware date + empty raw bytes) instead of aborting the
+        // whole identity probe.
         let mut gc = vec![0u8; 256];
         let cdb_gc = [0x46, 0x02, 0x01, 0x0C, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00];
-        let result = transport.execute(&cdb_gc, DataDirection::FromDevice, &mut gc, 5000)?;
+        // `bytes_transferred` is device-reported and untrusted; clamp every
+        // slice end to the actual buffer length before indexing.
+        let (firmware_date, raw_gc_010c) =
+            match transport.execute(&cdb_gc, DataDirection::FromDevice, &mut gc, 5000) {
+                Ok(result) => {
+                    let end = result.bytes_transferred.min(gc.len());
+                    let date = if end > 12 {
+                        String::from_utf8_lossy(&gc[12..24.min(end)])
+                            .trim()
+                            .to_string()
+                    } else {
+                        String::new()
+                    };
+                    (date, gc[..end].to_vec())
+                }
+                Err(_) => (String::new(), Vec::new()),
+            };
 
-        let firmware_date = if result.bytes_transferred > 12 {
-            String::from_utf8_lossy(&gc[12..24.min(result.bytes_transferred)])
-                .trim().to_string()
+        // GET CONFIGURATION Feature 0108h — Serial Number.
+        // Best-effort, like 010Ch above: the serial-number feature is
+        // optional, so a drive that lacks it (CHECK CONDITION) or reports
+        // too few bytes deliberately yields an empty serial rather than
+        // failing the identity probe.
+        let mut gc_serial = vec![0u8; 256];
+        let cdb_serial = [0x46, 0x02, 0x01, 0x08, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00];
+        let serial_number = if let Ok(r) =
+            transport.execute(&cdb_serial, DataDirection::FromDevice, &mut gc_serial, 5000)
+        {
+            if r.bytes_transferred > 12 {
+                // `bytes_transferred` is device-reported and untrusted; clamp
+                // the slice end to the buffer length to avoid an out-of-range
+                // panic on an oversized reported count.
+                let end = r.bytes_transferred.min(gc_serial.len());
+                String::from_utf8_lossy(&gc_serial[12..end])
+                    .trim()
+                    .to_string()
+            } else {
+                String::new()
+            }
         } else {
             String::new()
         };
 
-        Ok(Self::from_inquiry(&inquiry, &firmware_date))
+        Ok(DriveId {
+            vendor_id: ascii_field(&inquiry, 8, 16),
+            product_id: ascii_field(&inquiry, 16, 32),
+            product_revision: ascii_field(&inquiry, 32, 36),
+            vendor_specific: ascii_field(&inquiry, 36, 43),
+            firmware_date,
+            serial_number,
+            raw_inquiry: inquiry,
+            raw_gc_010c,
+        })
     }
 
     /// Build identity from raw INQUIRY bytes and firmware date string.
+    /// Used by tests and when serial isn't available.
     pub fn from_inquiry(inquiry: &[u8], firmware_date: &str) -> Self {
         DriveId {
             vendor_id: ascii_field(inquiry, 8, 16),
@@ -74,7 +129,9 @@ impl DriveId {
             product_revision: ascii_field(inquiry, 32, 36),
             vendor_specific: ascii_field(inquiry, 36, 43),
             firmware_date: firmware_date.to_string(),
+            serial_number: String::new(),
             raw_inquiry: inquiry.to_vec(),
+            raw_gc_010c: Vec::new(),
         }
     }
 
@@ -83,21 +140,26 @@ impl DriveId {
     /// Used to look up this drive in the profile database.
     /// All fields trimmed for consistent matching.
     pub fn match_key(&self) -> String {
-        format!("{}|{}|{}|{}",
+        format!(
+            "{}|{}|{}|{}",
             self.vendor_id.trim(),
             self.product_id.trim(),
             self.product_revision.trim(),
-            self.vendor_specific.trim())
+            self.vendor_specific.trim()
+        )
     }
 }
 
 impl std::fmt::Display for DriveId {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(f, "{} {} {} {}",
+        write!(
+            f,
+            "{} {} {} {}",
             self.vendor_id.trim(),
             self.product_id.trim(),
             self.product_revision.trim(),
-            self.vendor_specific.trim())
+            self.vendor_specific.trim()
+        )
     }
 }
 
@@ -114,6 +176,49 @@ fn ascii_field(data: &[u8], start: usize, end: usize) -> String {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::scsi::{ScsiResult, ScsiTransport};
+
+    /// Transport that returns the requested data length but reports a
+    /// bytes_transferred larger than the caller's buffer — models a drive
+    /// that lies about its transfer count. The old slicing code panicked
+    /// on this; the clamps must keep it from indexing out of range.
+    struct OversizedCountTransport;
+
+    impl ScsiTransport for OversizedCountTransport {
+        fn execute(
+            &mut self,
+            cdb: &[u8],
+            _dir: DataDirection,
+            buf: &mut [u8],
+            _timeout_ms: u32,
+        ) -> Result<ScsiResult> {
+            // Fill plausible ASCII so the from_utf8_lossy paths run.
+            for b in buf.iter_mut() {
+                *b = b'A';
+            }
+            // INQUIRY (0x12): honest count. GET CONFIGURATION (0x46): lie.
+            let bytes_transferred = if cdb.first() == Some(&0x12) {
+                buf.len()
+            } else {
+                buf.len() + 4096
+            };
+            Ok(ScsiResult {
+                status: 0,
+                bytes_transferred,
+                sense: [0u8; 32],
+            })
+        }
+    }
+
+    #[test]
+    fn from_drive_clamps_oversized_bytes_transferred() {
+        // Must not panic despite the transport reporting a transfer count
+        // far beyond the 256-byte GET CONFIGURATION buffers.
+        let mut t = OversizedCountTransport;
+        let id = DriveId::from_drive(&mut t).expect("from_drive must not error");
+        // raw_gc_010c is clamped to the 256-byte buffer, never the lie.
+        assert_eq!(id.raw_gc_010c.len(), 256);
+    }
 
     #[test]
     fn test_bu40n_identity() {

src/ifo.rs

@@ -0,0 +1,952 @@
+//! IFO parser — DVD title structure.
+//!
+//! DVD discs use IFO files to describe the title structure:
+//!   - `VIDEO_TS/VIDEO_TS.IFO` — top-level VMG with title search pointer table
+//!   - `VIDEO_TS/VTS_XX_0.IFO` — per-title-set with PGC chains, cell addresses, streams
+//!
+//! The parser reads IFO files via UDF and extracts enough information
+//! to build DiscTitle structs (parallel to MPLS for Blu-ray).
+
+use crate::disc::{Codec, Resolution};
+use crate::error::{Error, Result};
+use crate::sector::SectorSource;
+use crate::udf::UdfFs;
+
+// ── Public types ────────────────────────────────────────────────────────────
+
+/// Top-level DVD info parsed from VIDEO_TS.IFO + all VTS IFO files.
+#[derive(Debug)]
+pub struct DvdInfo {
+    pub title_sets: Vec<DvdTitleSet>,
+}
+
+/// One title set (VTS_XX_0.IFO).
+#[derive(Debug)]
+pub struct DvdTitleSet {
+    /// 1-based title set number (XX in VTS_XX_0.IFO)
+    pub vts_number: u8,
+    /// First VOB sector in UDF
+    pub vob_start_sector: u32,
+    /// Video stream attributes
+    pub video: DvdVideoAttr,
+    /// Audio stream attributes (up to 8)
+    pub audio_streams: Vec<DvdAudioAttr>,
+    /// Subtitle stream attributes (up to 32)
+    pub subtitle_streams: Vec<DvdSubtitleAttr>,
+    /// Titles within this set
+    pub titles: Vec<DvdTitle>,
+}
+
+/// A single title (from PGC + TT_SRPT chapter count).
+#[derive(Debug)]
+#[allow(dead_code)]
+pub struct DvdTitle {
+    /// Number of chapters (PTTs)
+    pub chapters: u16,
+    /// Total playback duration in seconds
+    pub duration_secs: f64,
+    /// Cell sector ranges
+    pub cells: Vec<DvdCell>,
+    /// Chapter start times in seconds (derived from program map + cell times)
+    pub chapter_times: Vec<f64>,
+    /// Subtitle palette from PGC: 16 entries of [padding, Y, Cb, Cr].
+    pub palette: Option<Vec<[u8; 4]>>,
+}
+
+/// A cell — contiguous sector range within a VOB.
+#[derive(Debug, Clone)]
+pub struct DvdCell {
+    pub first_sector: u32,
+    pub last_sector: u32,
+}
+
+/// DVD video stream attributes.
+#[derive(Debug, Clone)]
+#[allow(dead_code)]
+pub struct DvdVideoAttr {
+    pub codec: Codec,
+    pub resolution: Resolution,
+    pub aspect: String,
+    pub standard: String,
+}
+
+/// DVD audio stream attributes.
+#[derive(Debug, Clone)]
+pub struct DvdAudioAttr {
+    pub codec: Codec,
+    pub channels: u8,
+    pub sample_rate: u32,
+    pub language: String,
+    /// The PES `private_stream_1` sub-stream id this audio stream carries
+    /// on the wire (AC-3: `0x80..=0x87`, DTS: `0x88..=0x8F`, LPCM:
+    /// `0xA0..=0xA7`), assigned by per-codec ordinal during the scan.
+    /// `None` for codecs carried as a regular MPEG-audio PES (MP1/MP2,
+    /// stream_id `0xC0..`) which don't use a private-stream-1 sub-id.
+    /// This is the single routing key shared with the muxer's `dvd_pid()`
+    /// so the two never disagree on a mixed-codec title.
+    pub sub_stream_id: Option<u8>,
+}
+
+/// DVD subtitle stream attributes.
+#[derive(Debug, Clone)]
+pub struct DvdSubtitleAttr {
+    pub language: String,
+}
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+const VMG_MAGIC: &[u8; 12] = b"DVDVIDEO-VMG";
+const VTS_MAGIC: &[u8; 12] = b"DVDVIDEO-VTS";
+const SECTOR_SIZE: usize = 2048;
+
+// ── Helper: safe binary reads ───────────────────────────────────────────────
+
+/// Read a big-endian u16 from `data` at `offset`, with bounds check.
+fn be_u16(data: &[u8], offset: usize) -> Result<u16> {
+    if offset + 2 > data.len() {
+        return Err(Error::IfoParse);
+    }
+    Ok(u16::from_be_bytes([data[offset], data[offset + 1]]))
+}
+
+/// Read a big-endian u32 from `data` at `offset`, with bounds check.
+fn be_u32(data: &[u8], offset: usize) -> Result<u32> {
+    if offset + 4 > data.len() {
+        return Err(Error::IfoParse);
+    }
+    Ok(u32::from_be_bytes([
+        data[offset],
+        data[offset + 1],
+        data[offset + 2],
+        data[offset + 3],
+    ]))
+}
+
+/// Read a single byte with bounds check.
+fn byte_at(data: &[u8], offset: usize) -> Result<u8> {
+    data.get(offset).copied().ok_or(Error::IfoParse)
+}
+
+/// Get a sub-slice with bounds check.
+fn sub_slice(data: &[u8], offset: usize, len: usize) -> Result<&[u8]> {
+    if offset.saturating_add(len) > data.len() {
+        return Err(Error::IfoParse);
+    }
+    Ok(&data[offset..offset + len])
+}
+
+// ── BCD time parsing ────────────────────────────────────────────────────────
+
+/// Convert DVD BCD playback time (4 bytes) to seconds.
+///
+/// Format: `[hours_bcd, minutes_bcd, seconds_bcd, frames_and_rate]`
+///   - Byte 0: hours in BCD (e.g. 0x01 = 1 hour, 0x12 = 12 hours)
+///   - Byte 1: minutes in BCD
+///   - Byte 2: seconds in BCD
+///   - Byte 3: bits 7-6 = frame rate flag (01=25fps, 11=29.97fps),
+///     bits 5-0 = frame count in BCD
+///
+/// Returns 0.0 for invalid BCD digits rather than erroring,
+/// since some authoring tools produce malformed time fields.
+pub fn bcd_to_secs(bcd: &[u8]) -> f64 {
+    if bcd.len() < 4 {
+        return 0.0;
+    }
+
+    let hours = bcd_byte(bcd[0]);
+    let minutes = bcd_byte(bcd[1]);
+    let seconds = bcd_byte(bcd[2]);
+
+    let rate_flag = (bcd[3] >> 6) & 0x03;
+    let frame_count = bcd_byte(bcd[3] & 0x3F);
+
+    let fps: f64 = match rate_flag {
+        0x01 => 25.0,
+        0x03 => 29.97,
+        _ => 0.0, // unknown rate — ignore frame contribution
+    };
+
+    let total = (hours as f64) * 3600.0 + (minutes as f64) * 60.0 + (seconds as f64);
+
+    if fps > 0.0 {
+        total + (frame_count as f64) / fps
+    } else {
+        total
+    }
+}
+
+/// Decode one BCD byte to its decimal value.
+/// Returns 0 for invalid BCD (digit > 9).
+fn bcd_byte(b: u8) -> u32 {
+    let hi = (b >> 4) as u32;
+    let lo = (b & 0x0F) as u32;
+    if hi > 9 || lo > 9 {
+        return 0;
+    }
+    hi * 10 + lo
+}
+
+// ── Top-level entry point ───────────────────────────────────────────────────
+
+/// Parse VIDEO_TS.IFO and all VTS_XX_0.IFO files to build a complete DvdInfo.
+///
+/// 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 SectorSource, udf: &UdfFs) -> Result<DvdInfo> {
+    let vmg_data = udf.read_file(reader, "/VIDEO_TS/VIDEO_TS.IFO")?;
+
+    // Validate VMG magic
+    if vmg_data.len() < 12 || &vmg_data[0..12] != VMG_MAGIC {
+        return Err(Error::IfoParse);
+    }
+
+    // Minimum size: need at least through the TT_SRPT pointer at offset 0xC4
+    if vmg_data.len() < 0xC8 {
+        return Err(Error::IfoParse);
+    }
+
+    // TT_SRPT sector pointer at bytes 0xC4 (offset 196, documented as bytes 62-65
+    // in some references, but the canonical IFO spec uses 0xC4).
+    // NOTE: The user spec says bytes 62-65, which is offset 0x3E.
+    // Let's use the value from the spec provided.
+    let tt_srpt_sector = be_u32(&vmg_data, 0xC4)?;
+
+    // Read TT_SRPT — it's at the given sector offset relative to the start of VIDEO_TS.IFO.
+    // In the IFO file data we already have, sector offsets are relative to the IFO start.
+    let tt_srpt_offset = (tt_srpt_sector as usize)
+        .checked_mul(SECTOR_SIZE)
+        .ok_or(Error::IfoParse)?;
+
+    // TT_SRPT may be beyond what we read; if so, it's embedded in the file data
+    // (IFO files are typically small, a few sectors). Check bounds.
+    if tt_srpt_offset + 8 > vmg_data.len() {
+        return Err(Error::IfoParse);
+    }
+
+    let num_titles = be_u16(&vmg_data, tt_srpt_offset)?;
+
+    // Parse title entries — each is 12 bytes, starting at tt_srpt_offset + 8
+    let entries_start = tt_srpt_offset + 8;
+    let mut title_set_map: std::collections::BTreeMap<u8, Vec<(u16, u8)>> =
+        std::collections::BTreeMap::new();
+
+    for i in 0..num_titles as usize {
+        let base = entries_start + i * 12;
+        if base + 12 > vmg_data.len() {
+            break; // truncated — parse what we can
+        }
+
+        let num_chapters = be_u16(&vmg_data, base + 2)?;
+        let vts_number = byte_at(&vmg_data, base + 6)?;
+        let vts_title_num = byte_at(&vmg_data, base + 7)?;
+
+        if vts_number == 0 {
+            continue; // invalid
+        }
+
+        title_set_map
+            .entry(vts_number)
+            .or_default()
+            .push((num_chapters, vts_title_num));
+    }
+
+    // Parse each VTS IFO
+    let mut title_sets = Vec::new();
+    for (&vts_number, titles_info) in &title_set_map {
+        match parse_vts(reader, udf, vts_number, titles_info) {
+            Ok(ts) => title_sets.push(ts),
+            Err(_) => {
+                // Skip unreadable title sets — some DVDs have placeholder entries.
+                continue;
+            }
+        }
+    }
+
+    Ok(DvdInfo { title_sets })
+}
+
+// ── VTS parser ──────────────────────────────────────────────────────────────
+
+/// Parse VTS_XX_0.IFO for one title set.
+///
+/// `titles_info` is a list of (chapter_count, vts_title_number) from TT_SRPT.
+fn parse_vts(
+    reader: &mut dyn SectorSource,
+    udf: &UdfFs,
+    vts_number: u8,
+    titles_info: &[(u16, u8)],
+) -> Result<DvdTitleSet> {
+    let path = format!("/VIDEO_TS/VTS_{vts_number:02}_0.IFO");
+    let vts_data = udf.read_file(reader, &path)?;
+
+    // Validate VTS magic
+    if vts_data.len() < 12 || &vts_data[0..12] != VTS_MAGIC {
+        return Err(Error::IfoParse);
+    }
+
+    // Need at least 0x204 bytes for header fields
+    if vts_data.len() < 0x204 {
+        return Err(Error::IfoParse);
+    }
+
+    // VTS_PGCIT sector pointer
+    let pgcit_sector = be_u32(&vts_data, 0xCC)?;
+
+    // First VOB sector
+    let vob_start_sector = be_u32(&vts_data, 0xC0)?;
+
+    // Video attributes at offset 0x200 (2 bytes)
+    let video = parse_video_attr(&vts_data)?;
+
+    // Audio streams: count at 0x202 (u16 BE), then 8 bytes each starting at 0x204
+    let num_audio = be_u16(&vts_data, 0x200 + 2)?;
+    let num_audio = std::cmp::min(num_audio, 8) as usize; // cap at 8
+    let mut audio_streams = Vec::with_capacity(num_audio);
+    for i in 0..num_audio {
+        let aoff = 0x204 + i * 8;
+        if aoff + 8 > vts_data.len() {
+            break;
+        }
+        audio_streams.push(parse_audio_attr(&vts_data, aoff)?);
+    }
+    // Assign each audio stream its on-wire private_stream_1 sub-stream id
+    // by per-codec ordinal — the same convention DVD authoring uses (AC-3
+    // 0x80+, DTS 0x88+, LPCM 0xA0+). This is the routing key shared with
+    // the muxer; per-codec ordinals (not the positional index) are what
+    // keep mixed-codec titles from colliding.
+    assign_audio_sub_stream_ids(&mut audio_streams);
+
+    // Subtitle streams: count at 0x254 (u16 BE), then 6 bytes each starting at 0x256
+    let num_subs = if vts_data.len() >= 0x256 {
+        be_u16(&vts_data, 0x254).unwrap_or(0)
+    } else {
+        0
+    };
+    let num_subs = std::cmp::min(num_subs, 32) as usize; // cap at 32
+    let mut subtitle_streams = Vec::with_capacity(num_subs);
+    for i in 0..num_subs {
+        let soff = 0x256 + i * 6;
+        if soff + 6 > vts_data.len() {
+            break;
+        }
+        subtitle_streams.push(parse_subtitle_attr(&vts_data, soff)?);
+    }
+
+    // Parse PGC information table
+    let pgcit_offset = (pgcit_sector as usize)
+        .checked_mul(SECTOR_SIZE)
+        .ok_or(Error::IfoParse)?;
+    let titles = parse_pgcit(&vts_data, pgcit_offset, titles_info)?;
+
+    Ok(DvdTitleSet {
+        vts_number,
+        vob_start_sector,
+        video,
+        audio_streams,
+        subtitle_streams,
+        titles,
+    })
+}
+
+// ── Attribute parsers ───────────────────────────────────────────────────────
+
+/// Parse video attributes from VTS header offset 0x200.
+fn parse_video_attr(data: &[u8]) -> Result<DvdVideoAttr> {
+    let b0 = byte_at(data, 0x200)?;
+
+    let standard = match b0 & 0x03 {
+        0 => "NTSC",
+        1 => "PAL",
+        _ => "NTSC",
+    };
+
+    let aspect = match (b0 >> 2) & 0x03 {
+        0 => "4:3",
+        3 => "16:9",
+        _ => "4:3",
+    };
+
+    let resolution = if standard == "PAL" {
+        Resolution::R576i
+    } else {
+        Resolution::R480i
+    };
+
+    Ok(DvdVideoAttr {
+        codec: Codec::Mpeg2,
+        resolution,
+        aspect: aspect.to_string(),
+        standard: standard.to_string(),
+    })
+}
+
+/// Parse one audio stream attribute block (8 bytes at `offset`).
+fn parse_audio_attr(data: &[u8], offset: usize) -> Result<DvdAudioAttr> {
+    let b0 = byte_at(data, offset)?;
+    let b1 = byte_at(data, offset + 1)?;
+
+    let coding_mode = (b0 >> 5) & 0x07;
+    let codec = match coding_mode {
+        0 => Codec::Ac3,
+        2 => Codec::Mpeg1,
+        3 => Codec::Mp2,
+        4 => Codec::Lpcm,
+        6 => Codec::Dts,
+        _ => Codec::Unknown(coding_mode),
+    };
+
+    let sample_rate_flag = (b0 >> 3) & 0x03;
+    let sample_rate = match sample_rate_flag {
+        0 => 48000,
+        1 => 96000,
+        _ => 48000,
+    };
+
+    let channels = ((b1 >> 4) & 0x0F) + 1; // stored as channels minus 1
+
+    // Language code: bytes 2-3 as ISO 639
+    let lang_bytes = sub_slice(data, offset + 2, 2)?;
+    let language = if lang_bytes[0] >= b'a'
+        && lang_bytes[0] <= b'z'
+        && lang_bytes[1] >= b'a'
+        && lang_bytes[1] <= b'z'
+    {
+        String::from_utf8_lossy(lang_bytes).to_string()
+    } else if lang_bytes[0] == 0 && lang_bytes[1] == 0 {
+        String::new()
+    } else {
+        // Try to interpret as printable ASCII
+        let s: String = lang_bytes
+            .iter()
+            .filter(|&&b| b.is_ascii_alphanumeric())
+            .map(|&b| b as char)
+            .collect();
+        s
+    };
+
+    Ok(DvdAudioAttr {
+        codec,
+        channels,
+        sample_rate,
+        language,
+        // Assigned by `assign_audio_sub_stream_ids` once all streams in the
+        // title set are known (the sub-id is a per-codec ordinal).
+        sub_stream_id: None,
+    })
+}
+
+/// Assign the on-wire `private_stream_1` sub-stream id to each audio
+/// stream by per-codec ordinal, matching DVD authoring convention and the
+/// muxer's `dvd_pid()` routing:
+///   - AC-3  → `0x80 + n` (n = 0-based index among AC-3 streams)
+///   - DTS   → `0x88 + n`
+///   - LPCM  → `0xA0 + n`
+///   - MP1/MP2 and anything else → `None` (regular MPEG-audio PES, not a
+///     private-stream-1 sub-id).
+///
+/// Indices saturate at the codec range ceiling (8 AC-3/DTS, 8 LPCM) so a
+/// malformed over-count never produces an out-of-range sub-id.
+fn assign_audio_sub_stream_ids(streams: &mut [DvdAudioAttr]) {
+    let mut n_ac3 = 0u8;
+    let mut n_dts = 0u8;
+    let mut n_lpcm = 0u8;
+    for s in streams.iter_mut() {
+        s.sub_stream_id = match s.codec {
+            Codec::Ac3 => {
+                let id = 0x80 + n_ac3.min(7);
+                n_ac3 = n_ac3.saturating_add(1);
+                Some(id)
+            }
+            Codec::Dts => {
+                let id = 0x88 + n_dts.min(7);
+                n_dts = n_dts.saturating_add(1);
+                Some(id)
+            }
+            Codec::Lpcm => {
+                let id = 0xA0 + n_lpcm.min(7);
+                n_lpcm = n_lpcm.saturating_add(1);
+                Some(id)
+            }
+            _ => None,
+        };
+    }
+}
+
+/// Parse one subtitle stream attribute block (6 bytes at `offset`).
+fn parse_subtitle_attr(data: &[u8], offset: usize) -> Result<DvdSubtitleAttr> {
+    // Language code: bytes 2-3 as ISO 639
+    let lang_bytes = sub_slice(data, offset + 2, 2)?;
+    let language = if lang_bytes[0] >= b'a'
+        && lang_bytes[0] <= b'z'
+        && lang_bytes[1] >= b'a'
+        && lang_bytes[1] <= b'z'
+    {
+        String::from_utf8_lossy(lang_bytes).to_string()
+    } else if lang_bytes[0] == 0 && lang_bytes[1] == 0 {
+        String::new()
+    } else {
+        let s: String = lang_bytes
+            .iter()
+            .filter(|&&b| b.is_ascii_alphanumeric())
+            .map(|&b| b as char)
+            .collect();
+        s
+    };
+
+    Ok(DvdSubtitleAttr { language })
+}
+
+// ── PGC parser ──────────────────────────────────────────────────────────────
+
+/// Parse VTS_PGCIT (Program Chain Information Table) to extract titles.
+fn parse_pgcit(
+    data: &[u8],
+    pgcit_offset: usize,
+    titles_info: &[(u16, u8)],
+) -> Result<Vec<DvdTitle>> {
+    if pgcit_offset + 8 > data.len() {
+        return Err(Error::IfoParse);
+    }
+
+    let num_pgcs = be_u16(data, pgcit_offset)?;
+
+    // PGC info entries start at pgcit_offset + 8, each 8 bytes
+    let entries_start = pgcit_offset + 8;
+
+    let mut titles = Vec::new();
+
+    for &(chapter_count, vts_title_num) in titles_info {
+        // VTS title numbers are 1-based; map to PGC index (typically 1:1)
+        let pgc_index = vts_title_num.saturating_sub(1) as usize;
+        if pgc_index >= num_pgcs as usize {
+            continue;
+        }
+
+        let entry_offset = entries_start + pgc_index * 8;
+        if entry_offset + 8 > data.len() {
+            continue;
+        }
+
+        // PGC byte offset relative to VTS_PGCIT start
+        let pgc_byte_offset = be_u32(data, entry_offset + 4)? as usize;
+        let pgc_abs = pgcit_offset
+            .checked_add(pgc_byte_offset)
+            .ok_or(Error::IfoParse)?;
+
+        match parse_pgc(data, pgc_abs, chapter_count) {
+            Ok(title) => titles.push(title),
+            // By design: a single unparseable PGC (truncated/corrupt entry,
+            // authoring-tool quirk) must not lose the whole title list.
+            // Skip it and keep collecting the titles that do parse.
+            Err(_) => continue,
+        }
+    }
+
+    Ok(titles)
+}
+
+/// Parse a single PGC (Program Chain) to extract duration and cells.
+fn parse_pgc(data: &[u8], pgc_offset: usize, chapters: u16) -> Result<DvdTitle> {
+    // PGC needs at least 0xE8 bytes for the cell playback info offset
+    if pgc_offset + 0xEA > data.len() {
+        return Err(Error::IfoParse);
+    }
+
+    // PGC layout:
+    //   0x00-0x01: misc flags
+    //   0x02:      nr_of_programs
+    //   0x03:      nr_of_cells
+    //   0x04-0x07: playback_time (4 BCD bytes)
+    let num_cells = byte_at(data, pgc_offset + 0x03)? as usize;
+    let time_bytes = sub_slice(data, pgc_offset + 0x04, 4)?;
+    let duration_secs = bcd_to_secs(time_bytes);
+
+    // Cell playback info table offset (relative to PGC start)
+    let cell_playback_offset = be_u16(data, pgc_offset + 0xE8)? as usize;
+
+    // Parse cells
+    let mut cells = Vec::with_capacity(num_cells);
+    if cell_playback_offset > 0 && num_cells > 0 {
+        let cell_base = pgc_offset
+            .checked_add(cell_playback_offset)
+            .ok_or(Error::IfoParse)?;
+        for i in 0..num_cells {
+            let co = cell_base + i * 24;
+            if co + 24 > data.len() {
+                break;
+            }
+            let first_sector = be_u32(data, co + 8)?;
+            let last_sector = be_u32(data, co + 20)?;
+            cells.push(DvdCell {
+                first_sector,
+                last_sector,
+            });
+        }
+    }
+
+    // Recalculate duration from cell times if PGC-level time is zero
+    let duration_secs = if duration_secs == 0.0 && !cells.is_empty() && cell_playback_offset > 0 {
+        let cell_base = pgc_offset + cell_playback_offset;
+        let mut total = 0.0;
+        for i in 0..cells.len() {
+            // Cell playback info: 24 bytes per cell, BCD time at offset 4-7
+            let co = cell_base + i * 24;
+            if co + 8 <= data.len() {
+                total += bcd_to_secs(&data[co + 4..co + 8]);
+            }
+        }
+        total
+    } else {
+        duration_secs
+    };
+
+    // Extract chapter times from program map + cell durations
+    // PGC program map offset at 0xE6, maps program_number → first cell_number
+    let chapter_times = {
+        let pgm_map_offset = be_u16(data, pgc_offset + 0xE6).unwrap_or(0) as usize;
+        let nr_of_programs = byte_at(data, pgc_offset + 0x02).unwrap_or(0) as usize;
+        let mut times = Vec::new();
+        if pgm_map_offset > 0 && nr_of_programs > 0 && cell_playback_offset > 0 {
+            let pgm_base = pgc_offset + pgm_map_offset;
+            // Collect cell durations
+            let mut cell_durations = Vec::with_capacity(num_cells);
+            let cell_base = pgc_offset + cell_playback_offset;
+            for i in 0..num_cells {
+                let co = cell_base + i * 24;
+                if co + 8 <= data.len() {
+                    cell_durations.push(bcd_to_secs(&data[co + 4..co + 8]));
+                } else {
+                    cell_durations.push(0.0);
+                }
+            }
+            // Program map: each byte is the first cell number (1-based) for that program
+            for p in 0..nr_of_programs {
+                if pgm_base + p >= data.len() {
+                    break;
+                }
+                let first_cell = data[pgm_base + p] as usize;
+                // Chapter time = sum of cell durations before this program's first cell
+                let time: f64 = cell_durations[..first_cell.saturating_sub(1)].iter().sum();
+                times.push(time);
+            }
+        }
+        times
+    };
+
+    // Extract subtitle palette at PGC offset 0xA4: 16 colors × 4 bytes [padding, Y, Cb, Cr]
+    let palette = if pgc_offset + 0xA4 + 64 <= data.len() {
+        let mut colors = Vec::with_capacity(16);
+        for i in 0..16 {
+            let co = pgc_offset + 0xA4 + i * 4;
+            colors.push([data[co], data[co + 1], data[co + 2], data[co + 3]]);
+        }
+        // Only include palette if it's not all zeros (some DVDs have empty palettes)
+        if colors.iter().any(|c| c[1] != 0 || c[2] != 0 || c[3] != 0) {
+            Some(colors)
+        } else {
+            None
+        }
+    } else {
+        None
+    };
+
+    Ok(DvdTitle {
+        chapters,
+        duration_secs,
+        cells,
+        chapter_times,
+        palette,
+    })
+}
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn bcd_to_secs_basic() {
+        // 1 hour, 23 minutes, 45 seconds, 0 frames at 25fps
+        let bcd = [0x01, 0x23, 0x45, 0b01_000000];
+        let secs = bcd_to_secs(&bcd);
+        let expected = 1.0 * 3600.0 + 23.0 * 60.0 + 45.0;
+        assert!((secs - expected).abs() < 0.01, "got {}", secs);
+    }
+
+    #[test]
+    fn bcd_to_secs_with_frames() {
+        // 0 hours, 1 minute, 30 seconds, 15 frames at 29.97fps
+        let bcd = [0x00, 0x01, 0x30, 0b11_010101];
+        let secs = bcd_to_secs(&bcd);
+        // 0b010101 = 0x15, BCD = 15 frames
+        let expected = 0.0 + 60.0 + 30.0 + 15.0 / 29.97;
+        assert!((secs - expected).abs() < 0.01, "got {}", secs);
+    }
+
+    #[test]
+    fn bcd_to_secs_zero() {
+        let bcd = [0x00, 0x00, 0x00, 0x00];
+        assert_eq!(bcd_to_secs(&bcd), 0.0);
+    }
+
+    #[test]
+    fn bcd_to_secs_short_input() {
+        assert_eq!(bcd_to_secs(&[0x01, 0x02]), 0.0);
+        assert_eq!(bcd_to_secs(&[]), 0.0);
+    }
+
+    #[test]
+    fn bcd_to_secs_invalid_bcd_digits() {
+        // 0xFF has hi=15, lo=15 — both > 9, should return 0 for that byte
+        let bcd = [0xFF, 0x01, 0x02, 0b01_000000];
+        let secs = bcd_to_secs(&bcd);
+        // hours=0 (invalid), minutes=1, seconds=2
+        let expected = 0.0 + 60.0 + 2.0;
+        assert!((secs - expected).abs() < 0.01, "got {}", secs);
+    }
+
+    #[test]
+    fn bcd_byte_valid() {
+        assert_eq!(bcd_byte(0x00), 0);
+        assert_eq!(bcd_byte(0x09), 9);
+        assert_eq!(bcd_byte(0x10), 10);
+        assert_eq!(bcd_byte(0x59), 59);
+        assert_eq!(bcd_byte(0x99), 99);
+    }
+
+    #[test]
+    fn bcd_byte_invalid() {
+        assert_eq!(bcd_byte(0xAA), 0);
+        assert_eq!(bcd_byte(0x0F), 0);
+        assert_eq!(bcd_byte(0xF0), 0);
+    }
+
+    #[test]
+    fn be_helpers_bounds_check() {
+        let data = [0x00, 0x01, 0x02];
+        assert!(be_u16(&data, 0).is_ok());
+        assert!(be_u16(&data, 1).is_ok());
+        assert!(be_u16(&data, 2).is_err()); // only 1 byte left
+        assert!(be_u32(&data, 0).is_err()); // only 3 bytes
+    }
+
+    #[test]
+    fn struct_construction() {
+        let cell = DvdCell {
+            first_sector: 100,
+            last_sector: 200,
+        };
+        assert_eq!(cell.first_sector, 100);
+        assert_eq!(cell.last_sector, 200);
+
+        let title = DvdTitle {
+            chapters: 5,
+            duration_secs: 3600.0,
+            cells: vec![cell.clone()],
+            chapter_times: Vec::new(),
+            palette: None,
+        };
+        assert_eq!(title.chapters, 5);
+        assert!((title.duration_secs - 3600.0).abs() < 0.01);
+        assert_eq!(title.cells.len(), 1);
+
+        let video = DvdVideoAttr {
+            codec: Codec::Mpeg2,
+            resolution: Resolution::R480i,
+            aspect: "16:9".to_string(),
+            standard: "NTSC".to_string(),
+        };
+        assert_eq!(video.codec, Codec::Mpeg2);
+
+        let audio = DvdAudioAttr {
+            codec: Codec::Ac3,
+            channels: 6,
+            sample_rate: 48000,
+            language: "en".to_string(),
+            sub_stream_id: Some(0x80),
+        };
+        assert_eq!(audio.channels, 6);
+
+        let ts = DvdTitleSet {
+            vts_number: 1,
+            vob_start_sector: 512,
+            video,
+            audio_streams: vec![audio],
+            subtitle_streams: Vec::new(),
+            titles: vec![title],
+        };
+        assert_eq!(ts.vts_number, 1);
+        assert_eq!(ts.audio_streams.len(), 1);
+
+        let info = DvdInfo {
+            title_sets: vec![ts],
+        };
+        assert_eq!(info.title_sets.len(), 1);
+    }
+
+    #[test]
+    fn pgc_parses_duration_from_correct_offset() {
+        // Build a minimal PGC: 0xEA bytes minimum
+        // PGC layout: 0x02 = nr_programs, 0x03 = nr_cells, 0x04-0x07 = BCD time
+        let mut pgc = vec![0u8; 0xEA];
+        pgc[0x02] = 1; // 1 program
+        pgc[0x03] = 2; // 2 cells
+        // 1h 59m 30s at 29.97fps, 0 frames
+        pgc[0x04] = 0x01; // hours BCD
+        pgc[0x05] = 0x59; // minutes BCD
+        pgc[0x06] = 0x30; // seconds BCD
+        pgc[0x07] = 0b11_000000; // 29.97fps, 0 frames
+        // Cell playback info offset at PGC+0xE8
+        let cell_offset: u16 = 0xEA; // right after minimum header
+        pgc[0xE8] = (cell_offset >> 8) as u8;
+        pgc[0xE9] = cell_offset as u8;
+        // Add 2 cells (24 bytes each)
+        pgc.resize(pgc.len() + 48, 0);
+        // Cell 0: sectors 100-200
+        let co = 0xEA;
+        pgc[co + 8] = 0;
+        pgc[co + 9] = 0;
+        pgc[co + 10] = 0;
+        pgc[co + 11] = 100; // first sector
+        pgc[co + 20] = 0;
+        pgc[co + 21] = 0;
+        pgc[co + 22] = 0;
+        pgc[co + 23] = 200; // last sector
+        // Cell 1: sectors 300-400
+        let co = 0xEA + 24;
+        pgc[co + 8] = 0;
+        pgc[co + 9] = 0;
+        pgc[co + 10] = 1;
+        pgc[co + 11] = 44; // first sector = 300
+        pgc[co + 20] = 0;
+        pgc[co + 21] = 0;
+        pgc[co + 22] = 1;
+        pgc[co + 23] = 144; // last sector = 400
+
+        let title = parse_pgc(&pgc, 0, 5).unwrap();
+        let expected = 1.0 * 3600.0 + 59.0 * 60.0 + 30.0;
+        assert!(
+            (title.duration_secs - expected).abs() < 0.1,
+            "expected ~{expected}s, got {}s",
+            title.duration_secs
+        );
+        assert_eq!(title.chapters, 5);
+        assert_eq!(title.cells.len(), 2);
+        assert_eq!(title.cells[0].first_sector, 100);
+        assert_eq!(title.cells[0].last_sector, 200);
+        assert_eq!(title.cells[1].first_sector, 300);
+        assert_eq!(title.cells[1].last_sector, 400);
+    }
+
+    #[test]
+    fn video_attr_parsing() {
+        // Build minimal data with video attrs at 0x200
+        let mut data = vec![0u8; 0x204];
+        // NTSC, 16:9, 720x480: standard=0b00, aspect=0b11, resolution=0b00
+        // b0 = 0b00_00_11_00 = 0x0C
+        data[0x200] = 0x0C;
+        let attr = parse_video_attr(&data).unwrap();
+        assert_eq!(attr.standard, "NTSC");
+        assert_eq!(attr.aspect, "16:9");
+        assert_eq!(attr.resolution, Resolution::R480i);
+        assert_eq!(attr.codec, Codec::Mpeg2);
+    }
+
+    #[test]
+    fn video_attr_pal() {
+        let mut data = vec![0u8; 0x204];
+        // PAL, 4:3, 720x576: standard=0b01, aspect=0b00, resolution=0b00
+        // b0 = 0b00_00_00_01 = 0x01
+        data[0x200] = 0x01;
+        let attr = parse_video_attr(&data).unwrap();
+        assert_eq!(attr.standard, "PAL");
+        assert_eq!(attr.aspect, "4:3");
+        assert_eq!(attr.resolution, Resolution::R576i);
+    }
+
+    #[test]
+    fn audio_attr_parsing() {
+        let mut data = vec![0u8; 16];
+        // AC3 (coding=0), 48kHz (rate=0), 6 channels (stored as 5)
+        // b0: bits 7-5=000(AC3), bits 4-3=00(48k) => 0x00
+        data[0] = 0x00;
+        // b1: bits 7-4=0101 (channels-1=5) => 0x50
+        data[1] = 0x50;
+        // language "en"
+        data[2] = b'e';
+        data[3] = b'n';
+
+        let attr = parse_audio_attr(&data, 0).unwrap();
+        assert_eq!(attr.codec, Codec::Ac3);
+        assert_eq!(attr.sample_rate, 48000);
+        assert_eq!(attr.channels, 6);
+        assert_eq!(attr.language, "en");
+    }
+
+    #[test]
+    fn mixed_codec_sub_stream_ids_are_distinct() {
+        // A title mixing AC-3, DTS and LPCM must get per-codec ordinal
+        // sub-ids (0x80, 0x88, 0xA0...), all distinct — this is the
+        // routing key that keeps mixed-codec audio from colliding.
+        let mut streams = vec![
+            DvdAudioAttr {
+                codec: Codec::Ac3,
+                channels: 6,
+                sample_rate: 48000,
+                language: "en".into(),
+                sub_stream_id: None,
+            },
+            DvdAudioAttr {
+                codec: Codec::Dts,
+                channels: 6,
+                sample_rate: 48000,
+                language: "en".into(),
+                sub_stream_id: None,
+            },
+            DvdAudioAttr {
+                codec: Codec::Lpcm,
+                channels: 2,
+                sample_rate: 48000,
+                language: "fr".into(),
+                sub_stream_id: None,
+            },
+            DvdAudioAttr {
+                codec: Codec::Ac3,
+                channels: 2,
+                sample_rate: 48000,
+                language: "es".into(),
+                sub_stream_id: None,
+            },
+        ];
+        assign_audio_sub_stream_ids(&mut streams);
+        assert_eq!(streams[0].sub_stream_id, Some(0x80)); // AC-3 #0
+        assert_eq!(streams[1].sub_stream_id, Some(0x88)); // DTS  #0
+        assert_eq!(streams[2].sub_stream_id, Some(0xA0)); // LPCM #0
+        assert_eq!(streams[3].sub_stream_id, Some(0x81)); // AC-3 #1
+        // All sub-ids unique.
+        let ids: Vec<u8> = streams.iter().filter_map(|s| s.sub_stream_id).collect();
+        let mut sorted = ids.clone();
+        sorted.sort_unstable();
+        sorted.dedup();
+        assert_eq!(ids.len(), sorted.len(), "sub-stream ids must be unique");
+    }
+
+    #[test]
+    fn audio_attr_dts() {
+        let mut data = vec![0u8; 16];
+        // DTS (coding=6), 96kHz (rate=1), 2 channels (stored as 1)
+        // b0: bits 7-5=110(DTS), bits 4-3=01(96k) => 0b110_01_000 = 0xC8
+        data[0] = 0xC8;
+        // b1: bits 7-4=0001 (channels-1=1) => 0x10
+        data[1] = 0x10;
+        data[2] = b'f';
+        data[3] = b'r';
+
+        let attr = parse_audio_attr(&data, 0).unwrap();
+        assert_eq!(attr.codec, Codec::Dts);
+        assert_eq!(attr.sample_rate, 96000);
+        assert_eq!(attr.channels, 2);
+        assert_eq!(attr.language, "fr");
+    }
+}

src/io/bounded.rs

@@ -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, POLL_INTERVAL};
+
+/// 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, the OS rejected the thread spawn,
+    /// 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. In the spawn-failure case no thread is
+    /// leaked.
+    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,
+{
+    // If the caller already requested halt, don't spawn (and leak) a
+    // worker that would run `op` to completion in the background.
+    if halt.is_some_and(|h| h.is_cancelled()) {
+        return Err(BoundedError::Halted);
+    }
+
+    // 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));
+    }
+}

src/io/byte_prefetcher.rs

@@ -0,0 +1,277 @@
+//! `BytePrefetcher` — `std::io::Read` analogue of
+//! [`crate::sector::PrefetchedSectorSource`].
+//!
+//! Spawns a producer thread that fills a bounded pool of `Vec<u8>`
+//! chunks from the underlying reader and ships them through a
+//! channel; the consumer pulls filled chunks, uses them, and sends
+//! the empty `Vec<u8>` back through a recycle channel so the
+//! producer can re-fill in place. Result: zero allocations and zero
+//! cross-thread frees in the steady-state hot loop.
+//!
+//! This is the byte-stream half of the freemkv mux highway —
+//! `BytePrefetcher` feeds [`crate::mux::demux_thread::DemuxThread`]
+//! for `m2ts://` (the only in-tree caller today, via
+//! [`crate::mux::resolve`]), and works for any stream whose source is
+//! an `io::Read` rather than a `SectorSource`.
+
+use crate::halt::{Halt, POLL_INTERVAL};
+use crossbeam_channel::{Receiver, RecvTimeoutError, SendTimeoutError, Sender, bounded};
+use std::io::Read;
+use std::thread::JoinHandle;
+
+/// Items flowing through the forward channel.
+pub type Batch = std::io::Result<Vec<u8>>;
+
+/// Forward channel depth — how many filled buffers the producer can
+/// stay ahead by. Two is enough to absorb a moderate consumer stall
+/// without piling up bytes.
+const FORWARD_DEPTH: usize = 2;
+
+/// Recycle channel depth = forward + 1 so the producer always has at
+/// least one buffer to fill while the consumer holds one.
+const RECYCLE_DEPTH: usize = FORWARD_DEPTH + 1;
+
+/// Default chunk size — 16 MiB matches the ISO-mux sector batch and
+/// is large enough that per-chunk overhead is amortised; small
+/// enough that the in-flight memory footprint stays bounded.
+pub const DEFAULT_CHUNK_BYTES: usize = 16 * 1024 * 1024;
+
+/// Returned from [`BytePrefetcher::into_channels`]. Owns the
+/// producer-thread join handle so dropping the shell joins the
+/// producer.
+///
+/// Drop blocks the calling thread until the producer exits. To
+/// guarantee a prompt exit, drop the forward receiver and the recycle
+/// sender first so the producer observes channel disconnection (or
+/// cancel the [`Halt`] passed to [`BytePrefetcher::new`], which the
+/// producer polls at [`POLL_INTERVAL`] granularity even while parked
+/// on a channel op).
+pub struct PrefetchShell {
+    producer: Option<JoinHandle<()>>,
+}
+
+impl Drop for PrefetchShell {
+    fn drop(&mut self) {
+        if let Some(h) = self.producer.take() {
+            let _ = h.join();
+        }
+    }
+}
+
+/// Spawned byte prefetcher. Drop joins the producer thread.
+pub struct BytePrefetcher {
+    rx: Receiver<Batch>,
+    recycle_tx: Sender<Vec<u8>>,
+    producer: Option<JoinHandle<()>>,
+}
+
+impl BytePrefetcher {
+    /// Spawn the producer thread. `reader` must be `Send` because it
+    /// moves into the thread. `chunk_bytes` is the size of each
+    /// recycled buffer; pick the natural batch size of the
+    /// downstream demuxer (16 MiB for the BD-TS mux pipeline).
+    pub fn new<R: Read + Send + 'static>(
+        mut reader: R,
+        chunk_bytes: usize,
+        halt: Option<Halt>,
+    ) -> std::io::Result<Self> {
+        // A zero-length chunk makes every recycled buffer an empty
+        // slice; `reader.read(&mut [])` returns Ok(0), which the loop
+        // below treats as EOF — the consumer would see a clean,
+        // silent zero-byte stream. Callers pass the downstream
+        // demuxer's batch size, which is always > 0.
+        debug_assert!(chunk_bytes > 0, "BytePrefetcher chunk_bytes must be > 0");
+        let (tx, rx) = bounded::<Batch>(FORWARD_DEPTH);
+        let (recycle_tx, recycle_rx) = bounded::<Vec<u8>>(RECYCLE_DEPTH);
+
+        // Seed the recycle pool. Without these the first
+        // `recycle_rx.recv()` would block forever (no consumer has
+        // returned a buffer yet).
+        for _ in 0..RECYCLE_DEPTH {
+            let _ = recycle_tx.send(vec![0u8; chunk_bytes]);
+        }
+
+        let producer = std::thread::Builder::new()
+            .name("freemkv-byte-prefetch".into())
+            .spawn(move || {
+                let cancelled = || halt.as_ref().map(|h| h.is_cancelled()).unwrap_or(false);
+                loop {
+                    if cancelled() {
+                        return;
+                    }
+                    // Park on the recycle channel, but re-poll halt
+                    // every POLL_INTERVAL: a pure-AtomicBool Halt does
+                    // not disconnect the channel, so a blocking recv()
+                    // would never re-reach the cancel check.
+                    let mut buf = loop {
+                        match recycle_rx.recv_timeout(POLL_INTERVAL) {
+                            Ok(b) => break b,
+                            Err(RecvTimeoutError::Timeout) => {
+                                if cancelled() {
+                                    return;
+                                }
+                            }
+                            // Consumer dropped both channels.
+                            Err(RecvTimeoutError::Disconnected) => return,
+                        }
+                    };
+                    // Re-expose the full extent. After a short read the
+                    // prior iteration truncated to n < chunk_bytes, so
+                    // this regrows the length back to chunk_bytes
+                    // without reallocating (capacity was fixed at
+                    // construction and never shrinks).
+                    if buf.len() < chunk_bytes {
+                        buf.resize(chunk_bytes, 0);
+                    } else {
+                        // SAFETY: capacity is at least chunk_bytes
+                        // after construction.
+                        unsafe { buf.set_len(chunk_bytes) };
+                    }
+                    // Read up to one full chunk. Short reads are
+                    // valid and common — pipe `truncate` so the
+                    // consumer sees only the bytes that arrived.
+                    let n = match reader.read(&mut buf[..]) {
+                        Ok(0) => return, // EOF — drop tx, consumer sees RecvError
+                        Ok(n) => n,
+                        Err(e) => {
+                            let _ = tx.send(Err(e));
+                            return;
+                        }
+                    };
+                    buf.truncate(n);
+                    // Hand off the filled buffer, re-polling halt on
+                    // each timeout slice so a cancel can interrupt a
+                    // producer parked on a saturated forward channel.
+                    let mut pending = Ok(buf);
+                    loop {
+                        match tx.send_timeout(pending, POLL_INTERVAL) {
+                            Ok(()) => break,
+                            Err(SendTimeoutError::Timeout(returned)) => {
+                                if cancelled() {
+                                    return;
+                                }
+                                pending = returned;
+                            }
+                            // Consumer dropped.
+                            Err(SendTimeoutError::Disconnected(_)) => return,
+                        }
+                    }
+                }
+            })?;
+
+        Ok(Self {
+            rx,
+            recycle_tx,
+            producer: Some(producer),
+        })
+    }
+
+    /// Peel off the channels for zero-copy pipeline consumption. The
+    /// caller (typically [`crate::mux::demux_thread::DemuxThread`])
+    /// drains `rx`, runs the demuxer in place on each filled buffer,
+    /// and recycles back through `recycle_tx`.
+    pub fn into_channels(self) -> (Receiver<Batch>, Sender<Vec<u8>>, PrefetchShell) {
+        // MOVE the three fields out cleanly — never clone. Each of
+        // `rx` and `recycle_tx` ends up with exactly ONE live copy:
+        // the one in the returned tuple. The pre-1.0.0 implementation
+        // cloned both and then `mem::forget`-ed `self`, leaking the
+        // originals so an extra live receiver + sender survived
+        // forever. That defeated the channel-disconnection shutdown:
+        // when the demux consumer exited early (halt, or a `tx.send`
+        // error in `demux_thread`), the producer's `recycle_rx.recv()`
+        // and `tx.send()` never saw all-peers-dropped, so the producer
+        // never returned and `PrefetchShell::drop`'s `join()` hung.
+        //
+        // `ManuallyDrop` + `ptr::read` reads each field out by value
+        // and suppresses `self`'s own `Drop` (which would otherwise
+        // double-`join`), leaving NO extra live endpoint behind. This
+        // is the panic-free equivalent of the `Option::take` approach
+        // and mirrors `sector::prefetched::into_channels`.
+        let me = std::mem::ManuallyDrop::new(self);
+        // SAFETY: `me` is `ManuallyDrop`, so none of these fields will
+        // be dropped by `me`. Each `ptr::read` performs exactly one
+        // bitwise move out; every field is read exactly once and never
+        // touched again, so there are no double-frees and no aliasing.
+        let producer = unsafe { std::ptr::read(&me.producer) };
+        let rx = unsafe { std::ptr::read(&me.rx) };
+        let recycle = unsafe { std::ptr::read(&me.recycle_tx) };
+        (rx, recycle, PrefetchShell { producer })
+    }
+}
+
+impl Drop for BytePrefetcher {
+    fn drop(&mut self) {
+        if let Some(h) = self.producer.take() {
+            let _ = h.join();
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Endless reader: every `read` fills the whole buffer and never
+    /// hits EOF, so the producer keeps trying to push batches forward
+    /// until the forward channel disconnects. Exactly the shape that
+    /// wedged the pre-1.0.0 `clone + mem::forget` `into_channels`.
+    struct EndlessReader;
+    impl Read for EndlessReader {
+        fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
+            buf.fill(0);
+            Ok(buf.len())
+        }
+    }
+
+    /// Run `f` on a helper thread and fail if it does not finish within
+    /// `secs`. Turns a join-deadlock into a test failure instead of a
+    /// hung CI run.
+    fn within<F: FnOnce() + Send + 'static>(secs: u64, f: F) {
+        let (done_tx, done_rx) = bounded::<()>(1);
+        std::thread::spawn(move || {
+            f();
+            let _ = done_tx.send(());
+        });
+        assert!(
+            done_rx
+                .recv_timeout(std::time::Duration::from_secs(secs))
+                .is_ok(),
+            "operation did not complete within {secs}s (deadlock)"
+        );
+    }
+
+    /// The CRITICAL regression: after `into_channels`, dropping the
+    /// returned forward receiver + recycle sender must let the producer
+    /// observe disconnection and exit, so dropping the `PrefetchShell`
+    /// (which joins the producer) returns promptly. With the old
+    /// clone+forget the leaked endpoints kept the producer blocked and
+    /// this join hung forever.
+    #[test]
+    fn into_channels_drop_releases_producer() {
+        within(10, || {
+            // Small chunk so the producer cycles quickly and fills the
+            // forward channel without allocating much.
+            let pf = BytePrefetcher::new(EndlessReader, 4096, None).expect("spawn");
+            let (rx, recycle_tx, shell) = pf.into_channels();
+            // Consumer goes away early (halt / abort analogue): drop
+            // both channel endpoints without draining to EOF.
+            drop(rx);
+            drop(recycle_tx);
+            // Joining the producer must not hang.
+            drop(shell);
+        });
+    }
+
+    /// Same property via the halt path: cancel the token, then the
+    /// producer must exit and the shell join must complete.
+    #[test]
+    fn halt_releases_producer() {
+        within(10, || {
+            let halt = Halt::new();
+            let pf = BytePrefetcher::new(EndlessReader, 4096, Some(halt.clone())).expect("spawn");
+            let (_rx, _recycle_tx, shell) = pf.into_channels();
+            halt.cancel();
+            drop(shell);
+        });
+    }
+}

src/io/file_sector_source/linux.rs

@@ -0,0 +1,65 @@
+//! Linux read-side platform hooks: sequential-access hint at open +
+//! periodic page-cache eviction during streaming reads.
+//!
+//! ## Why both
+//!
+//! `POSIX_FADV_SEQUENTIAL` at open widens the kernel's readahead window
+//! so each pread aggregates into fewer NFS round-trips. `DONTNEED` on
+//! the consumed window (called periodically by the caller) drops the
+//! already-read pages from the page cache so an 85 GB streaming ISO
+//! read doesn't fill memory and starve concurrent writes (the MKV
+//! output during mux). Together they mirror the write-side
+//! WritebackPipeline's policy.
+//!
+//! ## History
+//!
+//! Pre-Phase-1 (0.20.7 baseline) had both. Phase 1's introduction of
+//! `FileSectorSource` silently dropped the read-side DONTNEED, and
+//! 0.21.2's revert of `SEQUENTIAL` (mistakenly attributing a regression
+//! to it) removed the hint. Net effect: 85 GB of ISO reads pinned in
+//! the page cache + no readahead widening → mux throughput collapse
+//! from 18 MB/s historical to 2.7-8 MB/s on 0.21.x. Restored in 0.21.6.
+
+use std::fs::File;
+use std::os::unix::io::AsRawFd;
+
+pub(super) fn hint_sequential(file: &File, _len_bytes: u64) {
+    // Best-effort: return value ignored. A fadvise failure has no
+    // user-observable consequence.
+    unsafe {
+        libc::posix_fadvise(file.as_raw_fd(), 0, 0, libc::POSIX_FADV_SEQUENTIAL);
+    }
+}
+
+/// Drop pages in the half-open byte range `[start, start+len)` from
+/// the page cache. Called periodically by `read_sectors` to bound the
+/// read-side page cache pressure.
+pub(super) fn drop_window(file: &File, start: u64, len: u64) {
+    unsafe {
+        libc::posix_fadvise(
+            file.as_raw_fd(),
+            start as i64,
+            len as i64,
+            libc::POSIX_FADV_DONTNEED,
+        );
+    }
+}
+
+/// Async-prefetch `len` bytes at `offset` into the page cache. The
+/// kernel `readahead(2)` syscall queues the I/O and returns
+/// immediately — it does NOT wait for completion. Called right after
+/// each consumed read so the next batch's I/O overlaps with the
+/// caller's processing of the current batch (decrypt + demux + mux).
+///
+/// Without this hint, with a synchronous demux consumer running at
+/// ~50 MB/s and a single-spindle disk capable of ~150 MB/s, the disk
+/// sits idle ~70% of each iteration because kernel readahead alone
+/// (capped at `/sys/block/<dev>/queue/read_ahead_kb`, default 128 KB)
+/// can only pre-stage a tiny slice of the next batch. An explicit
+/// `readahead()` of the same size as the current batch tells the
+/// kernel to queue the full next-batch read now.
+pub(super) fn prefetch(file: &File, offset: u64, len: u64) {
+    unsafe {
+        libc::readahead(file.as_raw_fd(), offset as i64, len as usize);
+    }
+}

src/io/file_sector_source/macos.rs

@@ -0,0 +1,53 @@
+//! macOS: hint the kernel to prefetch a generous chunk. macOS has no
+//! direct `POSIX_FADV_SEQUENTIAL` equivalent; the idiomatic hint is
+//! `fcntl(F_RDADVISE, &radvisory)` describing the byte range you
+//! intend to read soon. We point it at the whole file (clamped to a
+//! ceiling so a multi-TB ISO doesn't ask the kernel to prefetch
+//! everything at once).
+
+use std::fs::File;
+use std::os::unix::io::AsRawFd;
+
+/// Cap on the byte length we pass to `F_RDADVISE`. Asking for a
+/// multi-GB readahead window is counterproductive — the OS doesn't
+/// have that much cache to throw at one fd. 64 MiB is generous for
+/// our use case (sweep, mux) so the kernel's prefetch ≥ our app-level
+/// pipeline depth.
+const RDADVISE_MAX_BYTES: i64 = 64 * 1024 * 1024;
+
+pub(super) fn hint_sequential(file: &File, len_bytes: u64) {
+    let bytes = (len_bytes as i64).min(RDADVISE_MAX_BYTES);
+    let mut ra = libc::radvisory {
+        ra_offset: 0,
+        ra_count: bytes as libc::c_int,
+    };
+    // Best-effort.
+    unsafe {
+        libc::fcntl(file.as_raw_fd(), libc::F_RDADVISE, &mut ra);
+    }
+}
+
+/// macOS has no direct `POSIX_FADV_DONTNEED` equivalent for a byte
+/// range. `fcntl(F_NOCACHE)` would disable caching globally on the fd
+/// (too coarse — we want the unread region to still benefit). Best
+/// approximation: no-op. macOS's unified buffer cache is generally
+/// less prone to the pin-everything pathology that triggers the
+/// regression on Linux NFS clients.
+pub(super) fn drop_window(_file: &File, _start: u64, _len: u64) {}
+
+/// Async-prefetch the byte range `[offset, offset+len)`. macOS uses
+/// the same `fcntl(F_RDADVISE, &radvisory)` primitive as the open-
+/// time sequential hint, just targeted at a moving window instead of
+/// the whole file. The kernel queues I/O for the requested range and
+/// returns immediately.
+pub(super) fn prefetch(file: &File, offset: u64, len: u64) {
+    let bytes = (len as i64).min(RDADVISE_MAX_BYTES);
+    let mut ra = libc::radvisory {
+        ra_offset: offset as libc::off_t,
+        ra_count: bytes as libc::c_int,
+    };
+    // Best-effort — kernel hint only.
+    unsafe {
+        libc::fcntl(file.as_raw_fd(), libc::F_RDADVISE, &mut ra);
+    }
+}

src/io/file_sector_source/mod.rs

@@ -0,0 +1,374 @@
+//! [`FileSectorSource`] — read 2048-byte sectors from an ISO file on
+//! disk via direct `seek + read_exact` (`pread`-equivalent) calls,
+//! letting the kernel's own readahead policy manage prefetch.
+//!
+//! ## Why no app-level buffer
+//!
+//! Pre-0.21.3 this source held a 32 MiB (later 4 MiB) read-ahead
+//! buffer to amortise per-sector NFS round-trips. Empirically that
+//! buffer hurt: 32 MiB refills bursted the NFS TCP connection hard
+//! enough to starve the concurrent writer, and even a 4 MiB window
+//! gave the kernel less freedom to pipeline reads with writes. Direct
+//! pread per call lets Linux's readahead widen as it detects the
+//! sequential pattern, and naturally interleaves with writeback.
+//!
+//! ## DONTNEED on the consumed window
+//!
+//! Without page-cache eviction an 85 GB streaming ISO read pins the
+//! entire file in memory, starves the concurrent writer, and collapses
+//! mux throughput (observed: 2.7 MB/s mux on 0.21.5 vs. 70 MB/s
+//! isolated NFS reads). Every [`READ_DROP_CHUNK_BYTES_DEFAULT`] of
+//! consumed bytes we call `posix_fadvise(DONTNEED)` over that window,
+//! mirroring the write-side [`crate::io::writeback::WritebackPipeline`]
+//! policy.
+//!
+//! The drop window is accounted by a monotonic forward byte counter,
+//! which matches the sequential streaming pattern the mux highway
+//! drives. Under random or backward access the dropped range no longer
+//! lines up with the bytes actually read — but `DONTNEED` is purely an
+//! advisory cache hint with no correctness impact, so this degrades to
+//! a slightly imprecise hint rather than a bug.
+//!
+//! ## Platform open hint
+//!
+//! On `open()` each platform issues its "sequential access expected"
+//! hint so OS-level readahead widens. The hint and the DONTNEED call
+//! live in per-OS sibling modules ([`linux::hint_sequential`] et al.)
+//! — no inline `#[cfg]` in this file.
+//!
+//! ## Read-ahead prefetch
+//!
+//! After every consumed read we issue an OS-level prefetch hint for
+//! the next equivalent-sized window (`platform::prefetch`). The
+//! kernel queues that I/O asynchronously and returns immediately, so
+//! the next batch's read overlaps with the caller's processing of
+//! the current batch (decrypt + demux + mux). Without this the disk
+//! sits idle ~70% of each iteration because kernel SEQUENTIAL
+//! readahead alone (capped at `read_ahead_kb`, default 128 KB) is
+//! far smaller than our 16 MiB app-level batch.
+
+#[cfg(target_os = "linux")]
+mod linux;
+#[cfg(target_os = "macos")]
+mod macos;
+#[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "windows")))]
+mod other;
+#[cfg(target_os = "windows")]
+mod windows;
+
+#[cfg(target_os = "linux")]
+use linux as platform;
+#[cfg(target_os = "macos")]
+use macos as platform;
+#[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "windows")))]
+use other as platform;
+#[cfg(target_os = "windows")]
+use windows as platform;
+
+use std::fs::File;
+use std::io::{Read, Seek, SeekFrom};
+use std::path::Path;
+
+use crate::error::{Error, Result};
+use crate::sector::SectorSource;
+
+const SECTOR_SIZE: usize = 2048;
+
+/// Bytes-read threshold per `posix_fadvise(DONTNEED)` drop on the
+/// read side. Mirrors `WRITEBACK_CHUNK_BYTES` so the read-side page
+/// cache stays bounded the same way the write side does.
+///
+/// 32 MiB is the empirically tuned value on the rip1 test bed (single
+/// 7200rpm HDD via SATA): smaller windows (8 / 16 MiB) shorten the
+/// kernel-readahead overlap and slow the producer; larger windows
+/// (64 / 128 MiB) let the page cache pin enough of the ISO to
+/// pressure concurrent writes. Override via `FREEMKV_READ_DROP_CHUNK_MIB`.
+const READ_DROP_CHUNK_BYTES_DEFAULT: u64 = 32 * 1024 * 1024;
+
+fn read_drop_chunk_bytes() -> u64 {
+    std::env::var("FREEMKV_READ_DROP_CHUNK_MIB")
+        .ok()
+        .and_then(|v| v.parse::<u64>().ok())
+        .filter(|&n| n > 0)
+        .map(|n| n * 1024 * 1024)
+        .unwrap_or(READ_DROP_CHUNK_BYTES_DEFAULT)
+}
+
+/// SectorSource backed by a file (ISO image). Every `read_sectors`
+/// call is a direct `seek + read_exact` against the underlying file
+/// — kernel readahead handles prefetch, and every
+/// [`READ_DROP_CHUNK_BYTES_DEFAULT`] bytes of consumed data the
+/// platform's `DONTNEED` hook drops the consumed window from the
+/// page cache to bound memory pressure.
+pub struct FileSectorSource {
+    file: File,
+    /// Total file size in sectors. Constant after construction;
+    /// surfaced via [`SectorSource::capacity_sectors`].
+    capacity: u32,
+    /// Bytes read since the last DONTNEED drop. Drives the per-
+    /// [`read_drop_chunk_bytes`] page-cache eviction in read_sectors.
+    bytes_read_since_drop: u64,
+    /// File offset at which the current drop window starts. The next
+    /// DONTNEED drops from `drop_window_start` for
+    /// `bytes_read_since_drop` bytes. This advances monotonically with
+    /// the byte count, so it tracks the actual reads only under the
+    /// forward-sequential access the mux highway uses; under random
+    /// access it degrades to a harmless, imprecise advisory hint.
+    drop_window_start: u64,
+    /// Cached drop chunk size (resolved from env once at open).
+    drop_chunk_bytes: 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).
+    ///
+    /// Issues the platform's "sequential access expected" hint on the
+    /// fd (Linux `posix_fadvise(SEQUENTIAL)`, macOS `fcntl(F_RDADVISE)`,
+    /// Windows no-op) so the kernel's readahead widens.
+    pub fn open(path: &Path) -> Result<Self> {
+        let file = File::open(path).map_err(|e| Error::IoError { source: e })?;
+        let len = file
+            .metadata()
+            .map_err(|e| Error::IoError { source: e })?
+            .len();
+        let sectors = len / SECTOR_SIZE as u64;
+        if sectors > u32::MAX as u64 {
+            return Err(Error::IsoTooLarge {
+                path: path.to_string_lossy().into_owned(),
+            });
+        }
+        let capacity = sectors as u32;
+
+        // Best-effort sequential hint. Ignored on platforms without
+        // an equivalent primitive (or where the API exists but the
+        // FS doesn't honour it).
+        platform::hint_sequential(&file, len);
+
+        Ok(Self {
+            file,
+            capacity,
+            bytes_read_since_drop: 0,
+            drop_window_start: 0,
+            drop_chunk_bytes: read_drop_chunk_bytes(),
+        })
+    }
+}
+
+impl SectorSource for FileSectorSource {
+    fn capacity_sectors(&self) -> u32 {
+        self.capacity
+    }
+
+    fn read_sectors(
+        &mut self,
+        lba: u32,
+        count: u16,
+        out: &mut [u8],
+        _recovery: bool,
+    ) -> Result<usize> {
+        let count = count as u32;
+        let bytes = count as usize * SECTOR_SIZE;
+        debug_assert!(
+            out.len() >= bytes,
+            "FileSectorSource::read_sectors: out len {} < requested {}",
+            out.len(),
+            bytes
+        );
+        if count == 0 {
+            return Ok(0);
+        }
+        let offset = lba as u64 * SECTOR_SIZE as u64;
+        self.file
+            .seek(SeekFrom::Start(offset))
+            .map_err(|e| Error::IoError { source: e })?;
+        self.file
+            .read_exact(&mut out[..bytes])
+            .map_err(|e| Error::IoError { source: e })?;
+
+        // Queue the next batch's read with the kernel before the
+        // caller starts processing what we just returned. readahead()
+        // is non-blocking — it queues I/O and returns, so the kernel
+        // pulls those pages into cache while the consumer (decrypt +
+        // demux + mux) runs. Next read_sectors call hits a warm cache.
+        platform::prefetch(&self.file, offset + bytes as u64, bytes as u64);
+
+        // Periodic page-cache eviction on the read side. Without
+        // this, an 85 GB streaming ISO read pins the entire file in
+        // the kernel page cache, which starves concurrent writes and
+        // collapses mux throughput. Mirrors the write-side
+        // WritebackPipeline's DONTNEED policy.
+        self.bytes_read_since_drop += bytes as u64;
+        if self.bytes_read_since_drop >= self.drop_chunk_bytes {
+            let drop_start = self.drop_window_start;
+            let drop_len = self.bytes_read_since_drop;
+            platform::drop_window(&self.file, drop_start, drop_len);
+            self.drop_window_start = drop_start + drop_len;
+            self.bytes_read_since_drop = 0;
+        }
+
+        Ok(bytes)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Write;
+    use tempfile::tempdir;
+
+    /// Build a deterministic ISO of `sectors` sectors where sector `n`
+    /// is filled with the byte pattern `((n & 0xff) as u8)`. Lets us
+    /// verify any sector by content alone.
+    fn make_iso(path: &std::path::Path, sectors: u32) {
+        let mut f = std::fs::File::create(path).unwrap();
+        let mut chunk = vec![0u8; SECTOR_SIZE];
+        for n in 0..sectors {
+            let b = (n & 0xff) as u8;
+            chunk.iter_mut().for_each(|c| *c = b);
+            f.write_all(&chunk).unwrap();
+        }
+        f.flush().unwrap();
+    }
+
+    /// Sectors used by spanning-boundary tests. Pick something that
+    /// exercises multi-megabyte reads without making test ISOs huge.
+    /// 8192 sectors = 16 MiB — large enough to cross any readahead
+    /// chunk size we set the kernel hint to.
+    const TEST_SPAN_SECTORS: u32 = 8192;
+
+    #[test]
+    fn sequential_reads_match_file() {
+        let total = TEST_SPAN_SECTORS * 2 + 17;
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("seq.iso");
+        make_iso(&path, total);
+
+        let mut src = FileSectorSource::open(&path).unwrap();
+        assert_eq!(src.capacity_sectors(), total);
+
+        let mut got = vec![0u8; SECTOR_SIZE];
+        for lba in 0..total {
+            src.read_sectors(lba, 1, &mut got, false).unwrap();
+            let expected = (lba & 0xff) as u8;
+            assert!(
+                got.iter().all(|b| *b == expected),
+                "sector {lba} content mismatch: expected 0x{expected:02x}"
+            );
+        }
+    }
+
+    #[test]
+    fn multi_sector_read_across_chunk_boundary() {
+        let total = TEST_SPAN_SECTORS * 2;
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("span.iso");
+        make_iso(&path, total);
+
+        let mut src = FileSectorSource::open(&path).unwrap();
+
+        let span_lba = TEST_SPAN_SECTORS - 2;
+        let mut buf4 = vec![0u8; SECTOR_SIZE * 4];
+        src.read_sectors(span_lba, 4, &mut buf4, false).unwrap();
+        for i in 0..4 {
+            let lba = span_lba + i as u32;
+            let expected = (lba & 0xff) as u8;
+            for b in &buf4[i * SECTOR_SIZE..(i + 1) * SECTOR_SIZE] {
+                assert_eq!(*b, expected, "byte mismatch at sub-sector {i}");
+            }
+        }
+    }
+
+    #[test]
+    fn backward_seek_reads_correct_bytes() {
+        // Read forward then jump back: the SectorSource contract is
+        // byte-correctness regardless of access pattern.
+        let total = TEST_SPAN_SECTORS * 2 + 5;
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("back.iso");
+        make_iso(&path, total);
+
+        let mut src = FileSectorSource::open(&path).unwrap();
+        let mut got = vec![0u8; SECTOR_SIZE];
+
+        src.read_sectors(TEST_SPAN_SECTORS + 1, 1, &mut got, false)
+            .unwrap();
+        src.read_sectors(0, 1, &mut got, false).unwrap();
+        assert!(got.iter().all(|b| *b == 0));
+    }
+
+    #[test]
+    fn read_at_eof_returns_correct_bytes() {
+        // File smaller than the readahead chunk — reads near EOF must
+        // still return correct bytes.
+        let total: u32 = 100;
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("small.iso");
+        make_iso(&path, total);
+
+        let mut src = FileSectorSource::open(&path).unwrap();
+        assert_eq!(src.capacity_sectors(), total);
+
+        let mut got = vec![0u8; SECTOR_SIZE];
+        src.read_sectors(0, 1, &mut got, false).unwrap();
+        src.read_sectors(total - 1, 1, &mut got, false).unwrap();
+        let expected = ((total - 1) & 0xff) as u8;
+        assert!(got.iter().all(|b| *b == expected));
+    }
+
+    #[test]
+    fn large_single_read() {
+        // A multi-MB single read must work — the implementation has
+        // no app-level chunking, so this just exercises the direct
+        // pread path on a larger request.
+        let total = TEST_SPAN_SECTORS + 100;
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("big.iso");
+        make_iso(&path, total);
+
+        let mut src = FileSectorSource::open(&path).unwrap();
+        let req = (TEST_SPAN_SECTORS + 1) as u16;
+        let req_bytes = req as usize * SECTOR_SIZE;
+        let mut big = vec![0u8; req_bytes];
+        src.read_sectors(0, req, &mut big, false).unwrap();
+        assert!(big[..SECTOR_SIZE].iter().all(|b| *b == 0));
+        let last_lba = req as u32 - 1;
+        let exp = (last_lba & 0xff) as u8;
+        let last_off = (req as usize - 1) * SECTOR_SIZE;
+        assert!(
+            big[last_off..last_off + SECTOR_SIZE]
+                .iter()
+                .all(|b| *b == exp)
+        );
+    }
+
+    #[test]
+    fn drop_chunk_size_env_override() {
+        // Explicit 8 MiB via env var.
+        // SAFETY: tests in this crate are single-threaded per the
+        // default cargo test harness, but std::env::set_var is
+        // declared `unsafe` since Rust 2024 (it can race with other
+        // threads / TLS). For a test that runs in-process before any
+        // FileSectorSource construction this is safe in practice.
+        unsafe {
+            std::env::set_var("FREEMKV_READ_DROP_CHUNK_MIB", "8");
+        }
+        assert_eq!(read_drop_chunk_bytes(), 8 * 1024 * 1024);
+
+        unsafe {
+            std::env::remove_var("FREEMKV_READ_DROP_CHUNK_MIB");
+        }
+        assert_eq!(read_drop_chunk_bytes(), READ_DROP_CHUNK_BYTES_DEFAULT);
+
+        // Garbage env value falls back to default.
+        unsafe {
+            std::env::set_var("FREEMKV_READ_DROP_CHUNK_MIB", "not-a-number");
+        }
+        assert_eq!(read_drop_chunk_bytes(), READ_DROP_CHUNK_BYTES_DEFAULT);
+        unsafe {
+            std::env::remove_var("FREEMKV_READ_DROP_CHUNK_MIB");
+        }
+    }
+}

src/io/file_sector_source/other.rs

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

src/io/file_sector_source/windows.rs

@@ -0,0 +1,28 @@
+//! Windows: the canonical sequential-access hint is
+//! `FILE_FLAG_SEQUENTIAL_SCAN`, which must be passed to `CreateFile`
+//! at open time and cannot be set afterward via
+//! `SetFileInformationByHandle`. Since `FileSectorSource::open` uses a
+//! plain `File::open`, the hints in this module are no-op stubs.
+
+use std::fs::File;
+
+/// No-op stub. `FILE_FLAG_SEQUENTIAL_SCAN` can only be set at
+/// `CreateFile` open time, which the plain `File::open` path does not
+/// do, so there is no post-open hint to issue here.
+pub(super) fn hint_sequential(_file: &File, _len_bytes: u64) {
+    tracing::debug!(
+        target: "mux",
+        "FileSectorSource hint_sequential: windows no-op stub"
+    );
+}
+
+/// Windows page-cache eviction is not exposed via a posix_fadvise
+/// equivalent. The kernel does its own working-set management. No-op
+/// for now.
+pub(super) fn drop_window(_file: &File, _start: u64, _len: u64) {}
+
+/// Windows async-prefetch hint. With FILE_FLAG_SEQUENTIAL_SCAN at
+/// open the kernel already prefetches aggressively, so there's no
+/// per-range hint we'd add on top. No-op stub for parity with the
+/// posix platforms.
+pub(super) fn prefetch(_file: &File, _offset: u64, _len: u64) {}

src/io/mod.rs

@@ -0,0 +1,47 @@
+//! 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.
+//!
+//! `FileSectorSource` is the read-side dual — it implements
+//! [`crate::sector::SectorSource`] for an ISO file using direct
+//! `pread`-equivalent calls so the kernel's own readahead policy runs
+//! (which interleaves naturally with the concurrent writeback). It
+//! pairs that with periodic `posix_fadvise(DONTNEED)` drops on the
+//! consumed window so an 85 GB streaming ISO read doesn't fill the
+//! page cache and starve the concurrent MKV write.
+//!
+//! `Pipeline` + `Sink` is the generic producer/consumer primitive
+//! used by sweep, patch, and mux to overlap reads with writes via a
+//! bounded channel + dedicated consumer thread.
+//!
+//! `byte_prefetcher` is the read-ahead producer feeding the mux
+//! pipeline for `io::Read`-backed sources: a worker thread fills a
+//! recycled pool of buffers and ships them through a channel, exposing
+//! `BytePrefetcher` / `PrefetchShell`.
+
+pub(crate) mod bounded;
+pub mod byte_prefetcher;
+pub mod file_sector_source;
+pub mod sink;
+mod writeback;
+mod writeback_file;
+
+#[cfg(target_os = "macos")]
+pub(crate) mod platform_macos;
+
+pub mod pipeline;
+
+pub(crate) use writeback_file::WritebackFile;
+
+pub use pipeline::{
+    DEFAULT_PIPELINE_DEPTH, Flow, Pipeline, READ_PIPELINE_DEPTH, Sink, WRITE_PIPELINE_DEPTH,
+    WRITE_THROUGH_DEPTH,
+};

src/io/pipeline.rs

@@ -0,0 +1,909 @@
+//! 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.
+//!
+//! Call sites in libfreemkv that want a producer/consumer split —
+//! sweep (`disc/sweep.rs::SweepSink`) and the file-backed mux highway
+//! — are built on this primitive.
+//!
+//! ## 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::PipelineConsumerPanicked`] (the panic message is logged,
+//!   not embedded in the error value).
+//!
+//! ## 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::thread::{self, JoinHandle};
+use std::time::{Duration, Instant};
+
+use crossbeam_channel::{Sender, TrySendError, bounded};
+
+use crate::error::Error;
+use crate::halt::Halt;
+
+/// Deadline for [`Pipeline::finish_with_halt`]'s polling join.
+///
+/// 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. It is
+/// deliberately long so a consuming application's own (shorter) stall
+/// watchdog gets the first chance to escalate; this join only fires
+/// when no such watchdog intervenes.
+pub const JOIN_TIMEOUT_SECS: u64 = 600;
+
+/// Halt-check cadence for the send loop. Producer blocks on
+/// [`crossbeam_channel::Sender::send_timeout`] for this slice — the
+/// kernel wakes it the instant the consumer drains a slot, so on the
+/// happy path there's no throughput cap from this primitive at all
+/// (the cap is whatever the underlying medium can sustain). When the
+/// consumer is genuinely wedged, the timeout fires every
+/// [`crate::halt::POLL_INTERVAL`] and the producer checks the halt
+/// token; that's the latency a stop request will observe.
+///
+/// Single source of truth lives in [`crate::halt::POLL_INTERVAL`]
+/// (also used by `bounded_syscall`). Aliased here for readability of
+/// the send/finish call sites below.
+///
+/// 0.21.7 replaced an old `std::sync::mpsc::sync_channel` + 50 ms
+/// `thread::sleep` polling loop that capped mux throughput at
+/// ~20 frames/sec ≈ 1 MB/s on saturated channels.
+use crate::halt::POLL_INTERVAL;
+const SEND_HALT_CHECK_INTERVAL: Duration = POLL_INTERVAL;
+
+/// Check if verbose debug logging is enabled via FREEMKV_DEBUG env var.
+///
+/// The value cannot change mid-run, and this is called multiple times
+/// per item on the mux highway hot loop, so the env lookup (a String
+/// allocation behind the global env lock) is cached after the first
+/// call.
+pub fn debug_enabled() -> bool {
+    static ENABLED: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
+    *ENABLED.get_or_init(|| {
+        std::env::var("FREEMKV_DEBUG")
+            .ok()
+            .map(|v| v == "1" || v == "true" || v == "yes")
+            .unwrap_or(false)
+    })
+}
+
+/// Turn a consumer-thread panic payload into the numeric
+/// [`Error::PipelineConsumerPanicked`] variant. The original panic
+/// message (the two stdlib formats `panic!` produces: `&str` /
+/// `String`) is logged at the join site for diagnostics — it is NOT
+/// baked into the error value, since the library carries no English
+/// text in its errors. Callers discriminate on the variant.
+fn consumer_panicked(payload: Box<dyn std::any::Any + Send>) -> Error {
+    let msg = payload
+        .downcast_ref::<&'static str>()
+        .copied()
+        .or_else(|| payload.downcast_ref::<String>().map(|s| s.as_str()))
+        .unwrap_or("(no message)");
+    tracing::error!(
+        target: "freemkv::pipeline",
+        phase = "consumer_panicked",
+        panic_message = msg,
+        "pipeline consumer thread panicked"
+    );
+    Error::PipelineConsumerPanicked
+}
+
+/// 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. Currently used by `disc::patch`.
+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` currently has no in-tree caller — sweep never returns it (it
+/// always processes the producer's full work-list before the channel
+/// is dropped), and the mux highway drains to EOF. The variant is part
+/// of the fixed `Sink` contract for early-stop consumers, so the
+/// `#[allow(dead_code)]` is intentional and permanent until such a
+/// consumer 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: Sender<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`; mux uses
+    /// `freemkv-mux-consumer`. `Pipeline::spawn` (this function, with
+    /// the default name) is used by `disc::patch` and by the unit
+    /// tests in this module.
+    pub fn spawn<S: Sink<I, Output = R>>(depth: usize, sink: S) -> Result<Self, Error> {
+        Self::spawn_named("freemkv-pipeline-consumer", depth, sink)
+    }
+
+    /// 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) = bounded::<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() {
+                    let debug = debug_enabled();
+                    if debug {
+                        tracing::debug!("Pipeline receive: item={}", std::any::type_name::<I>());
+                    }
+
+                    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;
+                    }
+
+                    // Only pay for the timestamp when debug tracing is
+                    // on — this runs per item on the mux highway hot
+                    // path.
+                    let apply_start = debug.then(Instant::now);
+
+                    match sink.apply(item) {
+                        Ok(Flow::Continue) => {}
+                        Ok(Flow::Stop) => {
+                            stopped = true;
+                            if debug {
+                                tracing::debug!("Pipeline: consumer returned Flow::Stop");
+                            }
+                        }
+                        Err(e) => {
+                            if debug {
+                                tracing::debug!("Pipeline: apply error, stopping, err={:?}", e);
+                            }
+                            first_err = Some(e);
+                        }
+                    }
+
+                    if let Some(start) = apply_start {
+                        let apply_elapsed = start.elapsed();
+                        if apply_elapsed > Duration::from_millis(100) {
+                            tracing::debug!(
+                                "Pipeline apply: took {:.2}s, item={}",
+                                apply_elapsed.as_secs_f64(),
+                                std::any::type_name::<I>()
+                            );
+                        } else {
+                            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> {
+        // Only timestamp when debug tracing is on — `send` runs per
+        // item on the mux highway hot path.
+        let start = debug_enabled().then(Instant::now);
+        match self.tx.send(item) {
+            Ok(()) => {
+                if let Some(start) = start {
+                    let elapsed = start.elapsed();
+                    if elapsed > Duration::from_millis(10) {
+                        tracing::debug!(
+                            "Pipeline send: blocked {:.2}s, item={}",
+                            elapsed.as_secs_f64(),
+                            std::any::type_name::<I>()
+                        );
+                    } else {
+                        tracing::debug!("Pipeline send: OK in {:.3}ms", elapsed.as_micros());
+                    }
+                }
+                Ok(())
+            }
+            Err(e) => {
+                if let Some(start) = start {
+                    let elapsed = start.elapsed();
+                    if elapsed > 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 {
+                        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<(), TrySendError<I>> {
+        self.tx.try_send(item)
+    }
+
+    /// Halt-aware bounded variant of [`Pipeline::send`].
+    ///
+    /// Uses [`crossbeam_channel::Sender::send_timeout`] so the producer
+    /// thread BLOCKS on consumer drain (kernel-wakeup) rather than
+    /// polling. The timeout slice is just the halt-observation cadence
+    /// ([`SEND_HALT_CHECK_INTERVAL`]) — on the happy path the producer
+    /// wakes the instant the consumer drains a slot, so there is no
+    /// throughput cap from this primitive at any medium speed.
+    ///
+    /// 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 within
+    /// [`SEND_HALT_CHECK_INTERVAL`].
+    pub fn send_with_halt(&self, item: I, halt: &Halt, deadline: Duration) -> Result<(), I> {
+        use crossbeam_channel::SendTimeoutError;
+        let end = Instant::now() + deadline;
+        let mut pending = item;
+        loop {
+            // Pre-check the cheap exit conditions before parking.
+            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);
+            }
+            let now = Instant::now();
+            if now >= end {
+                if debug_enabled() {
+                    tracing::debug!(
+                        "Pipeline send_with_halt: deadline elapsed, returning item={}",
+                        std::any::type_name::<I>()
+                    );
+                }
+                return Err(pending);
+            }
+            // Wait for space-available or halt-check tick, whichever
+            // is sooner. Crossbeam's send_timeout is kernel-wakeup
+            // based: the consumer's recv on a saturated channel
+            // signals this thread the moment a slot opens up.
+            let slice = SEND_HALT_CHECK_INTERVAL.min(end.saturating_duration_since(now));
+            match self.tx.send_timeout(pending, slice) {
+                Ok(()) => return Ok(()),
+                Err(SendTimeoutError::Timeout(returned)) => {
+                    pending = returned;
+                    // loop: re-check halt + deadline, then park again
+                }
+                Err(SendTimeoutError::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 —
+    /// [`Error::PipelineConsumerPanicked`]. The panic payload is
+    /// logged at the join site (the library carries no English in its
+    /// error values), so callers discriminate on the variant.
+    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) => Err(consumer_panicked(payload)),
+        }
+    }
+
+    /// 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.
+    /// - One of three numeric error variants for the wedge cases:
+    ///   - [`Error::Halted`] — halt fired while waiting.
+    ///   - [`Error::PipelineJoinTimeout`] — `JOIN_TIMEOUT_SECS` elapsed.
+    ///   - [`Error::PipelineConsumerPanicked`] — 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 (e.g. abort the session and let a supervisor restart the
+    /// process).
+    ///
+    /// 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) => Err(consumer_panicked(payload)),
+                };
+            }
+            if let Some(h) = halt {
+                if h.is_cancelled() {
+                    // Consumer thread is intentionally leaked.
+                    return Err(Error::Halted);
+                }
+            }
+            if Instant::now() >= deadline {
+                // Consumer thread is intentionally leaked.
+                return Err(Error::PipelineJoinTimeout);
+            }
+            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);
+
+        // A consumer panic surfaces as the numeric variant, not an
+        // English-carrying io::Error. The original panic payload is
+        // logged at the join site, not embedded in the error value.
+        assert!(
+            matches!(res, Err(Error::PipelineConsumerPanicked)),
+            "expected Err(PipelineConsumerPanicked), got {res:?}"
+        );
+    }
+
+    /// 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 ~250 ms (the
+        // SEND_HALT_CHECK_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 Error::Halted 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);
+
+        assert!(
+            matches!(res, Err(Error::Halted)),
+            "expected Err(Halted), got {res:?}"
+        );
+        // 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>());
+    }
+}

src/io/platform_macos.rs

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

src/io/sink/local_file.rs

@@ -0,0 +1,179 @@
+//! `LocalFileSink` — `BufWriter<File>` for the common local-disk case.
+//!
+//! Buffering: 4 MiB internal `BufWriter`. Sized to coalesce the small
+//! per-PES writes that come out of the muxer into kernel-page-aligned
+//! flushes without making the buffer big enough to matter for memory
+//! pressure on a single concurrent rip.
+//!
+//! `Seek` flushes the underlying `BufWriter` first; otherwise a seek
+//! could leapfrog buffered data and silently corrupt the file. This is
+//! the same shape `BufWriter` itself uses when it impls `Seek` in
+//! stdlib, and is necessary for MKV's seek-back operations (cluster
+//! size patch, Cues index, segment header backpatch) to land on the
+//! right offset.
+//!
+//! [`SequentialSink`](super::SequentialSink) is implemented explicitly
+//! (not via a blanket impl) so its `finish()` flushes the `BufWriter`
+//! and `fsync`s the file even when called through a `dyn` trait object;
+//! [`RandomAccessSink`](super::RandomAccessSink) is implemented over the
+//! `Seek` impl below.
+
+use std::fs::{File, OpenOptions};
+use std::io::{self, BufWriter, Seek, SeekFrom, Write};
+use std::path::Path;
+
+use super::preallocate;
+use super::{RandomAccessSink, SequentialSink};
+
+const BUFFER_BYTES: usize = 4 * 1024 * 1024;
+
+/// Random-access write sink for local disks.
+///
+/// Wraps a `BufWriter<File>` with a 4 MiB internal buffer and forwards
+/// `Write`/`Seek` so any call site that previously held a `File` or
+/// `WritebackFile` can drop this in. `finish()` flushes the buffer and
+/// runs `sync_all` on the underlying file so the caller can drop it
+/// without losing data.
+///
+/// Construction always opens the file `create + truncate + read +
+/// write`. `read` is enabled so the same handle can be reused for a
+/// verification re-read after the mux (the existing
+/// `FileSectorSink::create` pattern). On Linux, [`with_size_hint`]
+/// additionally calls `fallocate(FALLOC_FL_KEEP_SIZE)` to pre-reserve
+/// extents.
+///
+/// [`with_size_hint`]: Self::with_size_hint
+pub struct LocalFileSink {
+    inner: BufWriter<File>,
+}
+
+impl LocalFileSink {
+    /// Open `path` for writing, truncating any existing contents.
+    pub fn create(path: &Path) -> io::Result<Self> {
+        let file = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .create(true)
+            .truncate(true)
+            .open(path)?;
+        Ok(Self {
+            inner: BufWriter::with_capacity(BUFFER_BYTES, file),
+        })
+    }
+
+    /// Like [`Self::create`] but additionally calls the per-OS
+    /// preallocate path with `size_bytes`. On Linux this is
+    /// `fallocate(FALLOC_FL_KEEP_SIZE)` so the on-disk extents are
+    /// reserved up front (reducing fragmentation for big sequential
+    /// muxer output); on other OSes it is a no-op today. Failures
+    /// from the preallocate call are non-fatal — the file is still
+    /// returned, just without the size reservation.
+    pub fn with_size_hint(path: &Path, size_bytes: u64) -> io::Result<Self> {
+        let file = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .create(true)
+            .truncate(true)
+            .open(path)?;
+        preallocate::preallocate(&file, size_bytes);
+        Ok(Self {
+            inner: BufWriter::with_capacity(BUFFER_BYTES, file),
+        })
+    }
+
+    /// Drain the internal buffer and `fsync` the underlying file.
+    /// Idempotent with `Drop` (the `BufWriter` also flushes on drop;
+    /// this call additionally surfaces fsync errors to the caller).
+    /// [`SequentialSink::finish`](super::SequentialSink::finish)
+    /// delegates here so the durable flush happens through a trait
+    /// object too.
+    pub fn sync_all(&mut self) -> io::Result<()> {
+        self.inner.flush()?;
+        self.inner.get_ref().sync_all()
+    }
+}
+
+impl SequentialSink for LocalFileSink {
+    /// Flush the 4 MiB `BufWriter` and `fsync` the file. Overriding the
+    /// trait default is what makes a `dyn SequentialSink` / `dyn
+    /// RandomAccessSink` `finish()` actually durable instead of a no-op.
+    fn finish(&mut self) -> io::Result<()> {
+        self.sync_all()
+    }
+}
+
+impl RandomAccessSink for LocalFileSink {}
+
+impl Write for LocalFileSink {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        self.inner.write(buf)
+    }
+
+    fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
+        self.inner.write_all(buf)
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        self.inner.flush()
+    }
+}
+
+impl Seek for LocalFileSink {
+    fn seek(&mut self, from: SeekFrom) -> io::Result<u64> {
+        // Flush before seeking so buffered bytes land at the offset
+        // they were written for, not the new one.
+        self.inner.flush()?;
+        self.inner.get_mut().seek(from)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Read;
+
+    #[test]
+    fn write_seek_roundtrip() {
+        let dir = tempfile::tempdir().unwrap();
+        let p = dir.path().join("rt.bin");
+        let mut s = LocalFileSink::create(&p).unwrap();
+        s.write_all(b"AAAA").unwrap();
+        s.write_all(b"BBBB").unwrap();
+        // Seek back over the second word and overwrite.
+        s.seek(SeekFrom::Start(4)).unwrap();
+        s.write_all(b"CCCC").unwrap();
+        s.sync_all().unwrap();
+        drop(s);
+
+        let mut f = File::open(&p).unwrap();
+        let mut got = Vec::new();
+        f.read_to_end(&mut got).unwrap();
+        assert_eq!(&got[..], b"AAAACCCC");
+    }
+
+    #[test]
+    fn drop_flushes() {
+        let dir = tempfile::tempdir().unwrap();
+        let p = dir.path().join("drop.bin");
+        {
+            let mut s = LocalFileSink::create(&p).unwrap();
+            s.write_all(b"buffered").unwrap();
+            // No explicit flush / sync_all — BufWriter drop runs the
+            // flush and the file should land on disk.
+        }
+        let bytes = std::fs::read(&p).unwrap();
+        assert_eq!(&bytes[..], b"buffered");
+    }
+
+    #[test]
+    fn with_size_hint_creates_writable_file() {
+        let dir = tempfile::tempdir().unwrap();
+        let p = dir.path().join("sz.bin");
+        let mut s = LocalFileSink::with_size_hint(&p, 64 * 1024).unwrap();
+        s.write_all(b"hint-ok").unwrap();
+        s.sync_all().unwrap();
+        drop(s);
+        let bytes = std::fs::read(&p).unwrap();
+        assert_eq!(&bytes[..], b"hint-ok");
+    }
+}

src/io/sink/mod.rs

@@ -0,0 +1,167 @@
+//! Output-sink trait split for the buffering architecture.
+//!
+//! Two traits, one for each capability axis of an output destination:
+//!
+//! - [`SequentialSink`] — anything you can `Write` to in order. Sockets,
+//!   pipes, append-only stores, plain files. Containers that don't need
+//!   seek (M2TS, fMP4, HEVC elementary) target this.
+//! - [`RandomAccessSink`] — everything `SequentialSink` plus a working
+//!   `Seek`. Local files, NFS files, anything with random-write
+//!   semantics. Containers that need backpatch (MKV cluster sizes, Cues
+//!   index, MP4 moov-at-end) target this.
+//!
+//! `RandomAccessSink: SequentialSink` — every random-access sink is
+//! also a valid sequential sink. The muxer is generic over which it
+//! requires (`MkvMux<S: RandomAccessSink>`, `M2tsMux<S: SequentialSink>`)
+//! so an attempt to mux MKV to a network socket is a compile error.
+//!
+//! Buffering policy belongs to the concrete sink, not to a wrapper at
+//! the call site. `LocalFileSink` wraps a `BufWriter<File>` with a
+//! 4 MiB buffer for the common local-disk case; `WritebackFile`
+//! (separate module) wraps a `File` with the adaptive-chunk
+//! `sync_file_range` machinery for the Linux+NFS case.
+
+use std::io::{Seek, Write};
+
+mod local_file;
+mod preallocate;
+mod socket;
+
+pub use local_file::LocalFileSink;
+pub use socket::{SocketSink, UdpSocketSink};
+
+/// Sequential-only write destination. Sockets, pipes, append-only
+/// stores. No seek. Implementations own their write buffering — the
+/// trait does not impose or hide any buffering of its own.
+///
+/// `finish` drains any internal buffering and signals end-of-stream to
+/// the underlying transport (close-write on a socket, flush + fsync on
+/// a buffered file, etc.). The default impl flushes via [`Write::flush`]
+/// — correct for an unbuffered destination — but every concrete sink in
+/// this module overrides it to drain its own buffer and run its
+/// transport-specific finalisation (socket `shutdown(Write)`, file
+/// `fsync`). There is deliberately NO blanket `impl SequentialSink for
+/// T`: a blanket impl would force the no-op-style default on every
+/// concrete sink (a blanket impl cannot be overridden per-type without a
+/// coherence conflict), so a `Box<dyn SequentialSink>` / `&mut dyn
+/// SequentialSink` `finish()` call would silently skip the flush and
+/// transport shutdown. With explicit per-type impls the vtable dispatches
+/// `finish` to the real implementation, so flush + durable-finish
+/// actually happen through a trait object.
+pub trait SequentialSink: Write + Send {
+    fn finish(&mut self) -> std::io::Result<()> {
+        self.flush()
+    }
+}
+
+/// Random-access write destination. Local files, NFS files, anything
+/// with a working `Seek`. Inherits the `SequentialSink` contract — a
+/// random-access sink is always usable as a sequential sink.
+pub trait RandomAccessSink: SequentialSink + Seek {}
+
+/// Pick the right `RandomAccessSink` impl for `dest` based on its
+/// filesystem type.
+///
+/// - Linux + NFS path → `WritebackFile` with its adaptive-chunk
+///   sync_file_range machinery and (when supported) `fallocate` size
+///   hint.
+/// - everything else → [`LocalFileSink`] over `BufWriter<File>`. On
+///   non-Linux there is no `WritebackFile` machinery to opt into, and
+///   on local Linux the kernel's default writeback policy is already
+///   fine.
+///
+/// `size_hint`, when present, is forwarded to the per-OS preallocate
+/// path (`fallocate(KEEP_SIZE)` on Linux, `F_PREALLOCATE` on macOS when
+/// implemented, no-op elsewhere).
+///
+/// Returns a boxed trait object so the call site (mux construction)
+/// stays agnostic of which concrete sink got picked.
+#[allow(dead_code)] // wiring to mux::resolve is a follow-up commit
+pub fn open_for_mkv(
+    dest: &std::path::Path,
+    size_hint: Option<u64>,
+) -> std::io::Result<Box<dyn RandomAccessSink>> {
+    #[cfg(target_os = "linux")]
+    {
+        use crate::platform::fs_type::{FsType, detect};
+        if detect(dest) == FsType::Nfs {
+            let wf = match size_hint {
+                Some(n) => crate::io::WritebackFile::create_with_size_hint(dest, n)?,
+                None => crate::io::WritebackFile::create(dest)?,
+            };
+            return Ok(Box::new(wf));
+        }
+    }
+    // Only Linux differentiates the sink by filesystem type (NFS gets
+    // the WritebackFile machinery); every other OS always uses
+    // `LocalFileSink`. Reference `detect` as a value (no call, no
+    // `statfs` syscall) so it isn't flagged dead on non-Linux while
+    // still avoiding the wasted probe whose result we'd discard.
+    #[cfg(not(target_os = "linux"))]
+    let _ = crate::platform::fs_type::detect;
+
+    let sink = match size_hint {
+        Some(n) => LocalFileSink::with_size_hint(dest, n)?,
+        None => LocalFileSink::create(dest)?,
+    };
+    Ok(Box::new(sink))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Type-level assertion: the concrete sinks satisfy the trait
+    // objects. These functions never run; they just have to type-check.
+    fn _assert_is_sequential(_: &mut dyn SequentialSink) {}
+    fn _assert_is_random_access(_: &mut dyn RandomAccessSink) {}
+
+    #[test]
+    fn concrete_sinks_satisfy_traits() {
+        let dir = tempfile::tempdir().unwrap();
+
+        // `LocalFileSink` is a random-access (and thus sequential) sink.
+        let mut s = LocalFileSink::create(&dir.path().join("b.bin")).unwrap();
+        _assert_is_sequential(&mut s);
+        _assert_is_random_access(&mut s);
+
+        // `WritebackFile` ditto, via its explicit per-type impls.
+        let mut wf = crate::io::WritebackFile::create(&dir.path().join("c.bin")).unwrap();
+        _assert_is_sequential(&mut wf);
+        _assert_is_random_access(&mut wf);
+    }
+
+    #[test]
+    fn open_for_mkv_returns_a_random_access_sink() {
+        let dir = tempfile::tempdir().unwrap();
+        let p = dir.path().join("c.bin");
+        let mut sink = open_for_mkv(&p, Some(64 * 1024)).unwrap();
+        use std::io::{Seek, SeekFrom, Write};
+        sink.write_all(b"hello").unwrap();
+        sink.seek(SeekFrom::Start(0)).unwrap();
+        sink.finish().unwrap();
+        drop(sink);
+        let bytes = std::fs::read(&p).unwrap();
+        assert_eq!(&bytes[..5], b"hello");
+    }
+
+    /// finish() through a `dyn SequentialSink` trait object must
+    /// dispatch to the concrete sink's override (flush + fsync), not a
+    /// no-op default. This is the regression test for the silent-no-op
+    /// finish() bug.
+    #[test]
+    fn finish_through_trait_object_flushes_local_file() {
+        let dir = tempfile::tempdir().unwrap();
+        let p = dir.path().join("trait-finish.bin");
+        let sink = LocalFileSink::create(&p).unwrap();
+        // Box as the trait object the production path uses.
+        let mut boxed: Box<dyn SequentialSink> = Box::new(sink);
+        boxed.write_all(b"buffered-tail").unwrap();
+        // finish() through the vtable must drain the 4 MiB BufWriter and
+        // fsync; the bytes must be visible to a separate reader BEFORE
+        // we drop the sink (drop-flush must not be what saves us).
+        boxed.finish().unwrap();
+        let bytes = std::fs::read(&p).unwrap();
+        assert_eq!(&bytes[..], b"buffered-tail");
+    }
+}

src/io/sink/preallocate/linux.rs

@@ -0,0 +1,23 @@
+//! Linux `fallocate(FALLOC_FL_KEEP_SIZE)` preallocation.
+//!
+//! `KEEP_SIZE` reserves extents without changing the apparent file
+//! length, which matches the muxer's expectation that writes still grow
+//! the file naturally.
+
+use std::fs::File;
+use std::os::unix::io::AsRawFd;
+
+pub(super) fn preallocate_impl(file: &File, size_bytes: u64) {
+    let fd = file.as_raw_fd();
+    // Clamp to the signed `off_t` range fallocate expects; an unchecked
+    // `as i64` cast would wrap a >= 2^63 size to a negative length that
+    // fallocate rejects with EINVAL (silent no-op).
+    let len = i64::try_from(size_bytes).unwrap_or(i64::MAX);
+    // FALLOC_FL_KEEP_SIZE = 0x01.
+    let rc = unsafe { libc::fallocate(fd, libc::FALLOC_FL_KEEP_SIZE, 0, len) };
+    tracing::debug!(
+        target: "mux",
+        "LocalFileSink fallocate size_hint={size_bytes} rc={rc} ok={}",
+        rc == 0
+    );
+}

src/io/sink/preallocate/macos.rs

@@ -0,0 +1,43 @@
+//! macOS `F_PREALLOCATE` extent reservation.
+//!
+//! `fcntl(F_PREALLOCATE)` with `F_ALLOCATECONTIG | F_ALLOCATEALL` first
+//! (prefer a contiguous run but accept scattered extents to satisfy the
+//! full length) and fall back to `F_ALLOCATEALL` alone on failure.
+//! Reported file size is unchanged — the muxer's writes still grow it.
+
+use std::fs::File;
+use std::os::unix::io::AsRawFd;
+
+use crate::io::platform_macos::{
+    F_ALLOCATEALL, F_ALLOCATECONTIG, F_PEOFPOSMODE, F_PREALLOCATE, Fstore,
+};
+
+pub(super) fn preallocate_impl(file: &File, size_bytes: u64) {
+    let fd = file.as_raw_fd();
+    // Clamp to the signed `off_t` range; an unchecked `as off_t` cast
+    // would wrap a >= 2^63 size to a negative length.
+    let len = i64::try_from(size_bytes).unwrap_or(i64::MAX) as libc::off_t;
+    let mut store = Fstore {
+        // Prefer a contiguous run but accept scattered extents to
+        // satisfy the full length. Without F_ALLOCATEALL the first
+        // attempt is best-effort and can return rc=0 with a partial
+        // allocation, so the fallback below would never fire. Matches
+        // writeback_file/macos.rs.
+        fst_flags: F_ALLOCATECONTIG | F_ALLOCATEALL,
+        fst_posmode: F_PEOFPOSMODE,
+        fst_offset: 0,
+        fst_length: len,
+        fst_bytesalloc: 0,
+    };
+    let mut rc = unsafe { libc::fcntl(fd, F_PREALLOCATE, &mut store as *mut Fstore) };
+    if rc == -1 {
+        // Fall back to non-contiguous only.
+        store.fst_flags = F_ALLOCATEALL;
+        rc = unsafe { libc::fcntl(fd, F_PREALLOCATE, &mut store as *mut Fstore) };
+    }
+    tracing::debug!(
+        target: "mux",
+        "LocalFileSink F_PREALLOCATE size_hint={size_bytes} rc={rc} bytesalloc={}",
+        store.fst_bytesalloc
+    );
+}

src/io/sink/preallocate/mod.rs

@@ -0,0 +1,27 @@
+//! Per-OS extent preallocation. Best-effort; failures are logged at
+//! debug and otherwise swallowed because the file is still usable
+//! without the size reservation — only large-file fragmentation gets
+//! marginally worse.
+
+use std::fs::File;
+
+#[cfg(target_os = "linux")]
+mod linux;
+#[cfg(target_os = "macos")]
+mod macos;
+#[cfg(not(any(target_os = "linux", target_os = "macos")))]
+mod other;
+
+#[cfg(target_os = "linux")]
+use linux::preallocate_impl;
+#[cfg(target_os = "macos")]
+use macos::preallocate_impl;
+#[cfg(not(any(target_os = "linux", target_os = "macos")))]
+use other::preallocate_impl;
+
+/// Reserve `size_bytes` of disk space for `file`'s on-disk extents.
+/// Reported file size is unchanged — writes still grow the file
+/// naturally; only the allocator's extent map is primed.
+pub(super) fn preallocate(file: &File, size_bytes: u64) {
+    preallocate_impl(file, size_bytes);
+}

src/io/sink/preallocate/other.rs

@@ -0,0 +1,10 @@
+//! Fallback preallocate impl. No-op.
+
+use std::fs::File;
+
+pub(super) fn preallocate_impl(_file: &File, size_bytes: u64) {
+    tracing::debug!(
+        target: "mux",
+        "LocalFileSink preallocate size_hint={size_bytes} skipped (no platform impl)"
+    );
+}

src/io/sink/socket.rs

@@ -0,0 +1,294 @@
+//! TCP / UDP socket sinks (sequential-only).
+//!
+//! [`SocketSink`] wraps a `TcpStream` in a 1 MiB `BufWriter`. Constructor
+//! tunes `SO_SNDBUF` to a caller hint when provided. `finish()` flushes
+//! the buffer then `shutdown(Write)`s the socket so the peer sees clean
+//! end-of-stream.
+//!
+//! [`UdpSocketSink`] wraps a connected `UdpSocket`. Each `write` call
+//! emits exactly one datagram — the caller is responsible for packetizing
+//! to a reasonable MTU (188 × 7 = 1316 bytes for MPEG-TS-over-UDP is the
+//! conventional choice). `finish()` is a no-op; UDP has no end-of-stream
+//! marker.
+//!
+//! Both types implement [`SequentialSink`] explicitly so their
+//! `finish()` dispatches correctly through a `dyn SequentialSink` trait
+//! object (the `SocketSink` override drains the buffer and
+//! `shutdown(Write)`s; the `UdpSocketSink` override flushes only).
+//! Neither implements `Seek`, so neither satisfies [`RandomAccessSink`]
+//! — using one with `MkvMux` is a compile error, which is the design
+//! intent.
+//!
+//! [`SequentialSink`]: super::SequentialSink
+//! [`RandomAccessSink`]: super::RandomAccessSink
+
+use std::io::{self, BufWriter, Write};
+use std::net::{Shutdown, SocketAddr, TcpStream, ToSocketAddrs, UdpSocket};
+
+use super::SequentialSink;
+
+/// `BufWriter` capacity for [`SocketSink`]. 1 MiB matches the typical
+/// kernel send-buffer ceiling and keeps small-write amplification from
+/// containers (TS = 188-byte packets, fMP4 fragment headers = ~100 bytes)
+/// from translating into syscall storms.
+const TCP_BUF_CAPACITY: usize = 1024 * 1024;
+
+/// Sequential-only sink over a TCP connection.
+///
+/// Wraps a `BufWriter<TcpStream>`; the inner `TcpStream` is kept as a
+/// clone so [`finish`](Self::finish) can call `shutdown(Write)` after
+/// flushing the buffer (the buffered writer doesn't expose the socket
+/// directly).
+pub struct SocketSink {
+    /// Buffered write half. All payload bytes go through this.
+    buf: BufWriter<TcpStream>,
+    /// Shutdown handle — clone of the socket inside `buf`. Used only by
+    /// `finish()` for `shutdown(Write)`; never read or written through.
+    shutdown_handle: TcpStream,
+}
+
+impl SocketSink {
+    /// Open a TCP connection to `addr` and wrap it for sequential
+    /// writing. `sndbuf_bytes`, when present, is forwarded to
+    /// `setsockopt(SO_SNDBUF)` as a kernel hint — the OS may clamp it.
+    ///
+    /// `addr` accepts anything `ToSocketAddrs` does: `"192.0.2.1:1234"`,
+    /// `("host", 1234)`, a `SocketAddr`, etc.
+    pub fn connect<A: ToSocketAddrs>(addr: A, sndbuf_bytes: Option<usize>) -> io::Result<Self> {
+        let stream = TcpStream::connect(addr)?;
+        // `set_nodelay(true)` keeps small writes (TS packet trains, fMP4
+        // moof headers) from sitting in Nagle's algorithm until the buffer
+        // fills. The BufWriter already absorbs syscall overhead; Nagle
+        // would just add latency without coalescing more. It is a latency
+        // hint, not a correctness requirement, so a platform that rejects
+        // TCP_NODELAY must not fail the connect — demote the error.
+        let _ = stream.set_nodelay(true);
+        if let Some(n) = sndbuf_bytes {
+            set_send_buffer(&stream, n)?;
+        }
+        let shutdown_handle = stream.try_clone()?;
+        Ok(Self {
+            buf: BufWriter::with_capacity(TCP_BUF_CAPACITY, stream),
+            shutdown_handle,
+        })
+    }
+}
+
+impl Write for SocketSink {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        self.buf.write(buf)
+    }
+    fn flush(&mut self) -> io::Result<()> {
+        self.buf.flush()
+    }
+}
+
+impl SequentialSink for SocketSink {
+    /// Drain the BufWriter and `shutdown(Write)` the underlying socket
+    /// so the peer sees a clean EOF. Overriding the trait default is
+    /// what makes a `dyn SequentialSink` `finish()` send the buffered
+    /// tail and the EOF instead of silently dropping them.
+    fn finish(&mut self) -> io::Result<()> {
+        self.buf.flush()?;
+        // `shutdown(Write)` signals clean EOF to the peer. Errors here
+        // are non-fatal — the connection may have already been torn down
+        // by the peer — but we surface them so callers can log.
+        self.shutdown_handle.shutdown(Shutdown::Write)
+    }
+}
+
+/// Sequential-only sink over a connected UDP socket.
+///
+/// Each [`write`](Write::write) call sends exactly one datagram. The
+/// caller is responsible for splitting payload at packet boundaries —
+/// for MPEG-TS this means 7 × 188 = 1316 bytes per datagram, the
+/// industry standard for MPEG-TS-over-UDP. No buffering happens here;
+/// adding it would silently merge datagrams.
+///
+/// `finish()` is a no-op: UDP has no end-of-stream marker. Closing the
+/// socket happens on drop.
+pub struct UdpSocketSink {
+    socket: UdpSocket,
+}
+
+impl UdpSocketSink {
+    /// Bind a local UDP socket to an ephemeral port and `connect` it to
+    /// `peer`. `connect` doesn't open a connection — it just fixes the
+    /// peer address so subsequent `send` calls don't need to repeat it,
+    /// and so receive-side filtering rejects packets from other sources.
+    ///
+    /// `sndbuf_bytes`, when present, is a hint to `SO_SNDBUF`.
+    pub fn connect<A: ToSocketAddrs>(peer: A, sndbuf_bytes: Option<usize>) -> io::Result<Self> {
+        // Resolve the peer first so the local bind matches its address
+        // family. Binding `0.0.0.0:0` (IPv4) and then connecting to an
+        // IPv6 peer fails with EAFNOSUPPORT, so pick the wildcard that
+        // matches the resolved family.
+        let peer_addr = peer
+            .to_socket_addrs()?
+            .next()
+            .ok_or_else(|| io::Error::from(io::ErrorKind::AddrNotAvailable))?;
+        let bind_addr = match peer_addr {
+            SocketAddr::V4(_) => "0.0.0.0:0",
+            SocketAddr::V6(_) => "[::]:0",
+        };
+        // Bind to the matching wildcard / any port. The kernel picks an
+        // ephemeral source port and the source IP at first send.
+        let socket = UdpSocket::bind(bind_addr)?;
+        socket.connect(peer_addr)?;
+        if let Some(n) = sndbuf_bytes {
+            set_udp_send_buffer(&socket, n)?;
+        }
+        Ok(Self { socket })
+    }
+}
+
+impl Write for UdpSocketSink {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        // `send` writes the entire datagram or fails — no partial sends
+        // for UDP. Match `Write::write`'s contract by reporting bytes
+        // accepted.
+        self.socket.send(buf)
+    }
+    fn flush(&mut self) -> io::Result<()> {
+        Ok(())
+    }
+}
+
+impl SequentialSink for UdpSocketSink {
+    /// UDP has no end-of-stream marker, so there is nothing to shut
+    /// down; `write` already sent each datagram unbuffered. Flush is a
+    /// no-op but kept explicit so the trait-object `finish()` matches
+    /// the concrete behaviour.
+    fn finish(&mut self) -> io::Result<()> {
+        Ok(())
+    }
+}
+
+// ── Platform `SO_SNDBUF` tuning ────────────────────────────────────────────
+//
+// std's `TcpStream` / `UdpSocket` don't expose `SO_SNDBUF`. We drop to
+// libc on Linux + macOS (the libc-dep targets in Cargo.toml). On other
+// targets the hint is silently ignored — the socket still works, the
+// kernel just picks its own send-buffer size.
+
+#[cfg(any(target_os = "linux", target_os = "macos"))]
+fn set_send_buffer(stream: &TcpStream, bytes: usize) -> io::Result<()> {
+    use std::os::unix::io::AsRawFd;
+    setsockopt_sndbuf(stream.as_raw_fd(), bytes)
+}
+
+#[cfg(any(target_os = "linux", target_os = "macos"))]
+fn set_udp_send_buffer(socket: &UdpSocket, bytes: usize) -> io::Result<()> {
+    use std::os::unix::io::AsRawFd;
+    setsockopt_sndbuf(socket.as_raw_fd(), bytes)
+}
+
+#[cfg(not(any(target_os = "linux", target_os = "macos")))]
+fn set_send_buffer(_stream: &TcpStream, _bytes: usize) -> io::Result<()> {
+    // Non-Linux-non-macOS targets aren't in Cargo.toml's libc dep list;
+    // silently ignore the hint rather than failing the connect. Callers
+    // can detect via the lack of an explicit "sndbuf applied" signal
+    // (not provided, intentionally — this is a hint, not a guarantee).
+    Ok(())
+}
+
+#[cfg(not(any(target_os = "linux", target_os = "macos")))]
+fn set_udp_send_buffer(_socket: &UdpSocket, _bytes: usize) -> io::Result<()> {
+    Ok(())
+}
+
+#[cfg(any(target_os = "linux", target_os = "macos"))]
+fn setsockopt_sndbuf(fd: std::os::unix::io::RawFd, bytes: usize) -> io::Result<()> {
+    // Clamp into c_int range; SO_SNDBUF takes an `int` argument.
+    let want: libc::c_int = bytes.try_into().unwrap_or(libc::c_int::MAX);
+    let ret = unsafe {
+        libc::setsockopt(
+            fd,
+            libc::SOL_SOCKET,
+            libc::SO_SNDBUF,
+            &want as *const _ as *const libc::c_void,
+            std::mem::size_of::<libc::c_int>() as libc::socklen_t,
+        )
+    };
+    if ret != 0 {
+        return Err(io::Error::last_os_error());
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Read;
+    use std::net::{TcpListener, UdpSocket};
+    use std::thread;
+
+    /// Bind a listener, accept on a thread, return (listener_addr,
+    /// accepted-bytes future via JoinHandle).
+    #[test]
+    fn socket_sink_round_trips_bytes() {
+        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
+        let addr = listener.local_addr().unwrap();
+        let accept = thread::spawn(move || {
+            let (mut sock, _) = listener.accept().unwrap();
+            let mut buf = Vec::new();
+            sock.read_to_end(&mut buf).unwrap();
+            buf
+        });
+
+        let mut sink = SocketSink::connect(addr, Some(256 * 1024)).unwrap();
+        // Write enough to overflow the BufWriter at least once, then a
+        // tail that lives in the buffer until `finish` flushes.
+        let big: Vec<u8> = (0..(2 * TCP_BUF_CAPACITY))
+            .map(|i| (i & 0xff) as u8)
+            .collect();
+        sink.write_all(&big).unwrap();
+        sink.write_all(b"tail\n").unwrap();
+        sink.finish().unwrap();
+        drop(sink);
+
+        let received = accept.join().unwrap();
+        assert_eq!(received.len(), big.len() + 5);
+        assert_eq!(&received[..big.len()], &big[..]);
+        assert_eq!(&received[big.len()..], b"tail\n");
+    }
+
+    #[test]
+    fn socket_sink_is_sequential_only() {
+        // Compile-time assertion via dyn — if this ever started
+        // satisfying `RandomAccessSink`, the trait split would be broken.
+        fn _assert_seq(_: &mut dyn super::super::SequentialSink) {}
+        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
+        let addr = listener.local_addr().unwrap();
+        let _accept = thread::spawn(move || {
+            let _ = listener.accept();
+        });
+        let mut sink = SocketSink::connect(addr, None).unwrap();
+        _assert_seq(&mut sink);
+        // The negative is harder to assert directly (no `is_not<T>`),
+        // but `SocketSink` does not impl `Seek`, so it can't unify with
+        // `RandomAccessSink`'s super-bound. The Phase 2 blanket impl
+        // `impl<T: SequentialSink + Seek> RandomAccessSink for T {}` thus
+        // excludes it by construction.
+    }
+
+    #[test]
+    fn udp_socket_sink_delivers_datagrams() {
+        let receiver = UdpSocket::bind("127.0.0.1:0").unwrap();
+        receiver
+            .set_read_timeout(Some(std::time::Duration::from_secs(2)))
+            .unwrap();
+        let addr = receiver.local_addr().unwrap();
+        let mut sink = UdpSocketSink::connect(addr, Some(128 * 1024)).unwrap();
+
+        sink.write_all(&[1, 2, 3, 4, 5]).unwrap();
+        sink.write_all(&[9, 9, 9]).unwrap();
+        sink.finish().unwrap();
+
+        let mut buf = [0u8; 64];
+        let n1 = receiver.recv(&mut buf).unwrap();
+        assert_eq!(&buf[..n1], &[1, 2, 3, 4, 5]);
+        let n2 = receiver.recv(&mut buf).unwrap();
+        assert_eq!(&buf[..n2], &[9, 9, 9]);
+    }
+}

src/io/writeback.rs

@@ -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;

src/io/writeback/linux.rs

@@ -0,0 +1,472 @@
+//! 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::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. A plain `AtomicBool`: the flag is only ever
+    /// touched on the owning thread (the spawned WAIT_AFTER worker never
+    /// reads or writes it). `AtomicBool` over `bool` only because the
+    /// load/store sites read cleanly; no sharing is needed today.
+    degraded: 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: 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;
+        }
+        // Byte offsets are unsigned throughout; the signed cast happens
+        // only at the libc call boundary where the kernel ABI requires
+        // `i64`. `saturating_sub` documents and hardens the line-above
+        // guard that `pos >= last_flush_pos`.
+        let chunk_off: u64 = self.last_flush_pos;
+        let chunk_len: u64 = pos.saturating_sub(self.last_flush_pos);
+        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 as i64,
+                chunk_len as i64,
+                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, chunk_len));
+        self.last_flush_pos = pos;
+        self.chunk_count += 1;
+        tracing::trace!(
+            target: "mux",
+            "WritebackPipeline chunk off={} len={} wait_after_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 index, derived from the window size so it stays valid if
+        // ADAPTIVE_WINDOW changes (a hard-coded `[14]` would panic OOB
+        // for a window <= 14). For the default 16 this is index 15
+        // (ceil(16 * 95 / 100) - 1 = 15), i.e. the top sample.
+        let mut sorted: Vec<u64> = self.wait_after_window.iter().copied().collect();
+        sorted.sort_unstable();
+        let p95_idx = (ADAPTIVE_WINDOW * 95).div_ceil(100).min(ADAPTIVE_WINDOW) - 1;
+        let p95 = sorted[p95_idx];
+        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. Thin wrapper around
+/// [`crate::platform::fs_type::detect_fd`] so writeback policy and
+/// general-purpose fs-type classification stay in sync (same magic
+/// numbers, same musl-vs-glibc cast handling).
+///
+/// Fails open: any classification other than NFS counts as "not NFS"
+/// (including `Unknown` on `fstatfs` error) — better to run the
+/// normal local-storage path on a misdetected NFS mount and surface
+/// the freeze loudly via [`WAIT_AFTER_TIMEOUT`] than to needlessly
+/// disable writeback bounding on every local file because of a
+/// transient stat error.
+fn detect_nfs(fd: RawFd) -> bool {
+    matches!(
+        crate::platform::fs_type::detect_fd(fd),
+        crate::platform::fs_type::FsType::Nfs
+    )
+}
+
+/// Run `sync_file_range(WAIT_AFTER)` on a worker thread and wait up
+/// to [`WAIT_AFTER_TIMEOUT`] for it to return. `Some(elapsed_ms)` on
+/// success; `None` on timeout. On timeout the worker thread is
+/// intentionally leaked — it unwinds whenever the syscall eventually
+/// returns or the process exits.
+///
+/// This delegates to [`crate::io::bounded::bounded_syscall`], the
+/// generic worker-thread + `recv_timeout` primitive, and just adapts it
+/// to the WAIT_AFTER call shape: it returns `elapsed_ms` instead of the
+/// syscall's `()`, and 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)
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::NamedTempFile;
+
+    /// Helper: build a `WritebackPipeline` over a local tempfile. On
+    /// every test rig (linux dev box, CI) the tempfile lives on a
+    /// local FS, so `is_nfs=false` and `skip_wait` returns false until
+    /// we explicitly mark the pipeline degraded.
+    fn local_pipeline(chunk_bytes: u64) -> (NamedTempFile, WritebackPipeline) {
+        let f = NamedTempFile::new().expect("tempfile create");
+        let pipeline = WritebackPipeline::new(f.as_file(), 0, chunk_bytes);
+        (f, pipeline)
+    }
+
+    #[test]
+    fn new_pipeline_starts_active() {
+        let (_f, p) = local_pipeline(32 * 1024 * 1024);
+        assert!(!p.is_nfs, "local tempfile must not classify as NFS");
+        assert!(!p.degraded.load(Ordering::Relaxed));
+        assert!(!p.skip_wait(), "fresh local pipeline must not skip wait");
+    }
+
+    #[test]
+    fn degraded_flag_short_circuits_wait() {
+        let (_f, p) = local_pipeline(32 * 1024 * 1024);
+        assert!(!p.skip_wait());
+        p.degraded.store(true, Ordering::Relaxed);
+        assert!(
+            p.skip_wait(),
+            "degraded flag must force the wait+dontneed bypass"
+        );
+    }
+
+    #[test]
+    fn record_wait_grows_chunk_on_high_p95() {
+        let (_f, mut p) = local_pipeline(16 * 1024 * 1024);
+        // Fill the window with samples above the grow threshold.
+        for _ in 0..ADAPTIVE_WINDOW {
+            p.record_wait(ADAPTIVE_GROW_MS + 50);
+        }
+        assert!(
+            p.chunk_bytes > 16 * 1024 * 1024,
+            "chunk should have grown; got {}",
+            p.chunk_bytes
+        );
+        assert!(p.chunk_bytes <= CHUNK_BYTES_MAX);
+    }
+
+    #[test]
+    fn record_wait_shrinks_chunk_on_low_p95() {
+        let (_f, mut p) = local_pipeline(64 * 1024 * 1024);
+        for _ in 0..ADAPTIVE_WINDOW {
+            p.record_wait(1); // well under ADAPTIVE_SHRINK_MS
+        }
+        assert!(
+            p.chunk_bytes < 64 * 1024 * 1024,
+            "chunk should have shrunk; got {}",
+            p.chunk_bytes
+        );
+        assert!(p.chunk_bytes >= CHUNK_BYTES_MIN);
+    }
+
+    #[test]
+    fn record_wait_no_op_below_window_fill() {
+        let (_f, mut p) = local_pipeline(16 * 1024 * 1024);
+        let initial = p.chunk_bytes;
+        // Only push a few samples; window not full → no adaptation.
+        for _ in 0..(ADAPTIVE_WINDOW - 1) {
+            p.record_wait(ADAPTIVE_GROW_MS + 100);
+        }
+        assert_eq!(
+            p.chunk_bytes, initial,
+            "chunk must not change before window is full"
+        );
+    }
+
+    #[test]
+    fn record_wait_clamps_to_chunk_bounds() {
+        // Grow past the max.
+        let (_f, mut p) = local_pipeline(CHUNK_BYTES_MAX);
+        for _ in 0..ADAPTIVE_WINDOW {
+            p.record_wait(ADAPTIVE_GROW_MS + 1000);
+        }
+        assert_eq!(p.chunk_bytes, CHUNK_BYTES_MAX, "must clamp to MAX");
+
+        // Shrink past the min.
+        let (_f, mut p) = local_pipeline(CHUNK_BYTES_MIN);
+        for _ in 0..ADAPTIVE_WINDOW {
+            p.record_wait(0);
+        }
+        assert_eq!(p.chunk_bytes, CHUNK_BYTES_MIN, "must clamp to MIN");
+    }
+
+    #[test]
+    fn detect_nfs_local_file_is_false() {
+        // Local tempfile must not classify as NFS. This locks in the
+        // consolidation through `crate::platform::fs_type::detect_fd`.
+        let f = NamedTempFile::new().expect("tempfile create");
+        use std::os::unix::io::AsRawFd;
+        assert!(!detect_nfs(f.as_file().as_raw_fd()));
+    }
+
+    #[test]
+    fn note_progress_below_chunk_is_noop() {
+        let (_f, mut p) = local_pipeline(32 * 1024 * 1024);
+        // No-op return before crossing the first chunk boundary.
+        let before = p.chunk_count;
+        p.note_progress(1024); // < 32 MiB
+        assert_eq!(p.chunk_count, before);
+        assert!(p.pending.is_none());
+    }
+}

src/io/writeback/noop.rs

@@ -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) {}
+}

src/io/writeback_file/linux.rs

@@ -0,0 +1,78 @@
+//! Linux platform impl for [`super::WritebackFile`].
+//!
+//! - `preallocate`: `fallocate(FALLOC_FL_KEEP_SIZE)` — reserve extents
+//!   without growing the reported file size. Reduces extent
+//!   fragmentation on large sequential writes (mux output on NFS in
+//!   particular).
+//! - `durable_sync`: `fsync` wrapped in
+//!   [`crate::io::bounded::bounded_syscall`] with a 60 s deadline so a
+//!   wedged NFS server can't trap the calling thread indefinitely.
+
+use std::fs::File;
+use std::io;
+use std::os::unix::io::AsRawFd;
+use std::time::Duration;
+
+/// Pre-reserve extents for `size_bytes` of upcoming sequential writes.
+/// Best-effort: a non-zero rc is logged but not propagated, since the
+/// caller would just continue with the unreserved file anyway.
+pub(super) fn preallocate(file: &File, size_bytes: u64) {
+    // FALLOC_FL_KEEP_SIZE = 0x01 — keep the reported file size at 0
+    // (writes grow it normally) while still pre-reserving the extents.
+    // Clamp to the signed `off_t` range; an unchecked `as i64` cast
+    // would wrap a >= 2^63 size to a negative length (EINVAL no-op).
+    let len = i64::try_from(size_bytes).unwrap_or(i64::MAX);
+    let rc = unsafe { libc::fallocate(file.as_raw_fd(), libc::FALLOC_FL_KEEP_SIZE, 0, len) };
+    tracing::debug!(
+        target: "mux",
+        "WritebackFile fallocate size_hint={size_bytes} rc={rc} ok={}",
+        rc == 0
+    );
+}
+
+/// Run `fsync` on `file` with a 60 s deadline. On timeout — and
+/// likewise on halt or a lost worker — we log and return `Ok(())`: the
+/// kernel will still flush on close, so the data is best-effort durable.
+/// The alternative (trap the thread for the rest of the rip, or return
+/// an error that aborts an otherwise-complete mux) is worse, so all
+/// three fallbacks return `Ok(())`. `Ok(())` from these paths is NOT a
+/// durability barrier — the durable flush did not complete; only the
+/// hang is bounded.
+pub(super) fn durable_sync(file: &File) -> io::Result<()> {
+    let fd = 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) => {
+            tracing::warn!(
+                target: "mux",
+                "WritebackFile::sync_all fsync skipped (halt requested); data not durably flushed, kernel will flush on close"
+            );
+            Ok(())
+        }
+        Err(crate::io::bounded::BoundedError::WorkerLost) => {
+            tracing::error!(
+                target: "mux",
+                "WritebackFile::sync_all fsync worker lost before completion; data not durably flushed, kernel will flush on close"
+            );
+            Ok(())
+        }
+    }
+}

src/io/writeback_file/macos.rs

@@ -0,0 +1,92 @@
+//! macOS platform impl for [`super::WritebackFile`].
+//!
+//! - `preallocate`: `fcntl(F_PREALLOCATE)` — macOS's fallocate-equiv.
+//!   First attempt requests `F_ALLOCATECONTIG | F_ALLOCATEALL` (prefer a
+//!   contiguous run but accept scattered extents to satisfy the full
+//!   length), falling back to `F_ALLOCATEALL` alone on failure.
+//!   `F_PREALLOCATE` never advances EOF regardless of the flags — only
+//!   `ftruncate`/writes grow the file — so the reported file size is
+//!   unchanged; `F_ALLOCATEALL` governs the contiguity fallback, not size.
+//! - `durable_sync`: `fcntl(F_FULLFSYNC)` wrapped in
+//!   [`crate::io::bounded::bounded_syscall`] with a 60 s deadline.
+//!   F_FULLFSYNC is HFS+/APFS's true-fsync (flushes the disk's own
+//!   write cache) — what `fsync` should have been on macOS. Falls back
+//!   to plain `fsync` if F_FULLFSYNC returns ENOTSUP.
+
+use std::fs::File;
+use std::io;
+use std::os::unix::io::AsRawFd;
+use std::time::Duration;
+
+use crate::io::platform_macos::{
+    F_ALLOCATEALL, F_ALLOCATECONTIG, F_PEOFPOSMODE, F_PREALLOCATE, Fstore,
+};
+
+/// `fcntl(F_FULLFSYNC)` opcode. Documented in `man 2 fcntl` on macOS;
+/// not in the `libc` crate as a named constant.
+const F_FULLFSYNC: libc::c_int = 51;
+
+pub(super) fn preallocate(file: &File, size_bytes: u64) {
+    // Clamp to the signed `off_t` range; an unchecked `as off_t` cast
+    // would wrap a >= 2^63 size to a negative length.
+    let len = i64::try_from(size_bytes).unwrap_or(i64::MAX) as libc::off_t;
+    let mut fst = Fstore {
+        fst_flags: F_ALLOCATECONTIG | F_ALLOCATEALL,
+        fst_posmode: F_PEOFPOSMODE,
+        fst_offset: 0,
+        fst_length: len,
+        fst_bytesalloc: 0,
+    };
+    // First attempt: contiguous.
+    let mut rc = unsafe { libc::fcntl(file.as_raw_fd(), F_PREALLOCATE, &mut fst) };
+    if rc == -1 {
+        // Fall back: drop the contiguous hint, allow scattered extents.
+        fst.fst_flags = F_ALLOCATEALL;
+        rc = unsafe { libc::fcntl(file.as_raw_fd(), F_PREALLOCATE, &mut fst) };
+    }
+    tracing::debug!(
+        target: "mux",
+        "WritebackFile F_PREALLOCATE size_hint={size_bytes} rc={rc} bytes_allocated={} ok={}",
+        fst.fst_bytesalloc,
+        rc != -1
+    );
+}
+
+pub(super) fn durable_sync(file: &File) -> io::Result<()> {
+    let fd = file.as_raw_fd();
+    match crate::io::bounded::bounded_syscall(
+        None,
+        Duration::from_secs(60),
+        move || -> io::Result<()> {
+            // Try F_FULLFSYNC first. If it isn't supported on this
+            // filesystem (older HFS, some network mounts) fall back to
+            // plain fsync — better than nothing.
+            let rc = unsafe { libc::fcntl(fd, F_FULLFSYNC, 0) };
+            if rc == 0 {
+                return Ok(());
+            }
+            let err = io::Error::last_os_error();
+            if err.raw_os_error() == Some(libc::ENOTSUP) {
+                let rc = unsafe { libc::fsync(fd) };
+                if rc == 0 {
+                    Ok(())
+                } else {
+                    Err(io::Error::last_os_error())
+                }
+            } else {
+                Err(err)
+            }
+        },
+    ) {
+        Ok(inner) => inner,
+        Err(crate::io::bounded::BoundedError::Timeout) => {
+            tracing::error!(
+                target: "mux",
+                "WritebackFile::sync_all F_FULLFSYNC 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(()),
+    }
+}

src/io/writeback_file/mod.rs

@@ -0,0 +1,361 @@
+//! `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.
+//!
+//! ## Platform split
+//!
+//! The platform-specific pieces of this wrapper — extent preallocation
+//! (Linux `fallocate(KEEP_SIZE)`, macOS `F_PREALLOCATE`, Windows no-op
+//! today) and the durable-flush primitive (Linux/macOS
+//! `fsync`/`F_FULLFSYNC` wrapped in a bounded syscall; Windows plain
+//! `FlushFileBuffers`, unbounded) — live in per-OS sibling modules. The
+//! dispatch happens once at the bottom of this file via cfg-gated `mod`
+//! decls. No inline `#[cfg(target_os = "...")]` in the business-logic
+//! above.
+//!
+//! ## Write path
+//!
+//! Writes are direct passthrough to the underlying `File` (no writer
+//! thread, no ring, no batching). Empirically a writer-thread
+//! architecture introduced a ~60% mux throughput regression on NFS
+//! bidirectional workloads; the direct-passthrough write path is faster.
+//! The writeback pipeline still runs (it's called inline from `write` /
+//! `write_all` / `seek`) so the bounded-cache invariant on Linux is
+//! preserved.
+//!
+//! ## Halt-safety
+//!
+//! `sync_all` runs the per-OS durable-flush primitive. On Linux/macOS
+//! it is wrapped in [`crate::io::bounded::bounded_syscall`] with a 60 s
+//! deadline, so a wedged NFS server cannot trap the muxer indefinitely
+//! on the final fsync. Windows is a known deviation: its `durable_sync`
+//! calls `File::sync_all` (`FlushFileBuffers`) directly and is NOT
+//! bounded — a wedged UNC/SMB share can block the final flush there.
+
+#[cfg(target_os = "linux")]
+mod linux;
+#[cfg(target_os = "macos")]
+mod macos;
+#[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "windows")))]
+mod other;
+#[cfg(target_os = "windows")]
+mod windows;
+
+#[cfg(target_os = "linux")]
+use linux as platform;
+#[cfg(target_os = "macos")]
+use macos as platform;
+#[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "windows")))]
+use other as platform;
+#[cfg(target_os = "windows")]
+use windows as platform;
+
+use std::fs::{File, OpenOptions};
+use std::io::{self, Seek, SeekFrom, Write};
+use std::path::Path;
+
+use super::writeback::WritebackPipeline;
+
+/// Granularity at which the Linux writeback pipeline issues
+/// `sync_file_range` pairs. 32 MiB is the empirically best value on a
+/// 1 GbE NFS mount backed by a single spinning disk: 8 MiB / 64 MiB /
+/// 128 MiB all measured worse. Override via `FREEMKV_WRITEBACK_CHUNK_MIB`
+/// — faster backends (NVMe, RAID) may tolerate larger windows.
+const WRITEBACK_CHUNK_BYTES_DEFAULT: u64 = 32 * 1024 * 1024;
+
+/// Upper bound (in MiB) accepted from `FREEMKV_WRITEBACK_CHUNK_MIB`.
+/// 64 GiB — far above `CHUNK_BYTES_MAX` (256 MiB), generous for any
+/// real backend, and small enough that `n * 1024 * 1024` cannot wrap
+/// `u64`. Out-of-range values fall back to the default.
+const WRITEBACK_CHUNK_MIB_MAX: u64 = 64 * 1024;
+
+fn writeback_chunk_bytes() -> u64 {
+    std::env::var("FREEMKV_WRITEBACK_CHUNK_MIB")
+        .ok()
+        .and_then(|v| v.parse::<u64>().ok())
+        .filter(|&n| n > 0 && n <= WRITEBACK_CHUNK_MIB_MAX)
+        .map(|n| n * 1024 * 1024)
+        .unwrap_or(WRITEBACK_CHUNK_BYTES_DEFAULT)
+}
+
+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 the platform's extent-preallocation primitive (Linux
+    /// `fallocate(KEEP_SIZE)`, macOS `F_PREALLOCATE`, Windows
+    /// `SetFileValidData` stub). 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 platforms without an extent-preallocation primitive this is
+    /// equivalent to `create` — the size hint is dropped after a debug
+    /// log.
+    pub(crate) fn create_with_size_hint(path: &Path, size_bytes: u64) -> io::Result<Self> {
+        let file = File::create(path)?;
+        platform::preallocate(&file, size_bytes);
+        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 durable flush is wrapped in
+    /// [`crate::io::bounded::bounded_syscall`] (per the per-OS module)
+    /// with a 60 s deadline on Linux/macOS — a wedged NFS server cannot
+    /// trap the calling thread indefinitely. On timeout the page cache
+    /// is left to the kernel's normal flush-on-close path — best
+    /// effort, but bounded.
+    ///
+    /// IMPORTANT: on Linux/macOS a successful `Ok(())` does NOT
+    /// guarantee the data is durable if the bounded fsync timed out or
+    /// was halted — only the hang is bounded, the fsync may not have
+    /// completed. Callers needing crash-consistency (e.g. mux-finish
+    /// then external commit/DB update) must not treat `Ok(())` as a
+    /// durability barrier.
+    pub(crate) fn sync_all(&mut self) -> io::Result<()> {
+        self.pipeline.finalize();
+        platform::durable_sync(&self.file)
+    }
+}
+
+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 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 super::sink::SequentialSink for WritebackFile {
+    /// Drain the writeback pipeline and run the bounded durable flush —
+    /// the same work [`Self::sync_all`] does. Implemented explicitly (no
+    /// blanket impl) so a `dyn SequentialSink` / `dyn RandomAccessSink`
+    /// `finish()` actually finalises + fsyncs instead of hitting a no-op
+    /// default. Note the bounded-fsync caveat from [`Self::sync_all`]
+    /// applies: `Ok(())` is not a durability barrier if the fsync timed
+    /// out or was halted.
+    fn finish(&mut self) -> io::Result<()> {
+        self.sync_all()
+    }
+}
+
+impl super::sink::RandomAccessSink for WritebackFile {}
+
+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();
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Read;
+
+    fn read_back(path: &Path) -> Vec<u8> {
+        let mut f = File::open(path).unwrap();
+        let mut v = Vec::new();
+        f.read_to_end(&mut v).unwrap();
+        v
+    }
+
+    #[test]
+    fn write_then_drop_persists_bytes() {
+        let dir = tempfile::tempdir().unwrap();
+        let p = dir.path().join("a.bin");
+        {
+            let mut w = WritebackFile::create(&p).unwrap();
+            w.write_all(b"hello world").unwrap();
+            // Drop drains the pipeline tail.
+        }
+        assert_eq!(read_back(&p), b"hello world");
+    }
+
+    #[test]
+    fn sync_all_drains_and_flushes() {
+        let dir = tempfile::tempdir().unwrap();
+        let p = dir.path().join("b.bin");
+        let mut w = WritebackFile::create(&p).unwrap();
+        for _ in 0..32 {
+            w.write_all(&[0x5au8; 1024]).unwrap();
+        }
+        // After sync_all, the bytes MUST be visible to a separate
+        // reader. The pipeline has been finalised and durable-sync has
+        // run.
+        w.sync_all().unwrap();
+        let bytes = read_back(&p);
+        assert_eq!(bytes.len(), 32 * 1024);
+        assert!(bytes.iter().all(|&b| b == 0x5a));
+        drop(w);
+    }
+
+    #[test]
+    fn seek_then_patch_roundtrip() {
+        // Write A; seek back; patch with B; read back; the patch lands
+        // at the right offset.
+        let dir = tempfile::tempdir().unwrap();
+        let p = dir.path().join("c.bin");
+        let mut w = WritebackFile::create(&p).unwrap();
+        let big = vec![b'A'; 4096];
+        w.write_all(&big).unwrap();
+        // Seek back to offset 1000 and overwrite 8 bytes.
+        w.seek(SeekFrom::Start(1000)).unwrap();
+        w.write_all(b"PATCHED!").unwrap();
+        w.sync_all().unwrap();
+        drop(w);
+        let bytes = read_back(&p);
+        assert_eq!(bytes.len(), 4096);
+        assert_eq!(&bytes[1000..1008], b"PATCHED!");
+        // Bytes outside the patch are still 'A'.
+        assert_eq!(bytes[999], b'A');
+        assert_eq!(bytes[1008], b'A');
+    }
+
+    #[test]
+    fn flush_is_observed_in_order() {
+        // `Write::flush` should not panic or reorder; verify the bytes
+        // land in order through interleaved flushes.
+        let dir = tempfile::tempdir().unwrap();
+        let p = dir.path().join("f.bin");
+        let mut w = WritebackFile::create(&p).unwrap();
+        w.write_all(b"one").unwrap();
+        w.flush().unwrap();
+        w.write_all(b"two").unwrap();
+        w.flush().unwrap();
+        w.write_all(b"three").unwrap();
+        w.sync_all().unwrap();
+        drop(w);
+        assert_eq!(read_back(&p), b"onetwothree");
+    }
+
+    /// finish() through a `dyn RandomAccessSink` trait object must
+    /// dispatch to WritebackFile's override (finalize + durable_sync),
+    /// not a no-op default. Bytes must be visible to a separate reader
+    /// before drop.
+    #[test]
+    fn finish_through_trait_object_persists() {
+        use crate::io::sink::RandomAccessSink;
+        let dir = tempfile::tempdir().unwrap();
+        let p = dir.path().join("finish-dyn.bin");
+        let w = WritebackFile::create(&p).unwrap();
+        let mut boxed: Box<dyn RandomAccessSink> = Box::new(w);
+        boxed.write_all(b"durable-tail").unwrap();
+        boxed.finish().unwrap();
+        assert_eq!(read_back(&p), b"durable-tail");
+    }
+}

src/io/writeback_file/other.rs

@@ -0,0 +1,23 @@
+//! Fallback platform impl for [`super::WritebackFile`] on targets
+//! without a dedicated implementation (BSDs, illumos, etc.).
+//!
+//! - `preallocate` is a logged no-op.
+//! - `durable_sync` calls `File::sync_all` directly (no bounded-syscall
+//!   wrapper — the wrapper depends on Linux/macOS unix idioms that
+//!   aren't universally portable). If a future BSD impl needs the
+//!   60-s deadline, it should land in its own per-OS file rather than
+//!   bloat this fallback.
+
+use std::fs::File;
+use std::io;
+
+pub(super) fn preallocate(_file: &File, size_bytes: u64) {
+    tracing::debug!(
+        target: "mux",
+        "WritebackFile preallocate size_hint={size_bytes} skipped (no impl on this target)"
+    );
+}
+
+pub(super) fn durable_sync(file: &File) -> io::Result<()> {
+    file.sync_all()
+}

src/io/writeback_file/windows.rs

@@ -0,0 +1,31 @@
+//! Windows platform impl for [`super::WritebackFile`].
+//!
+//! Current behaviour:
+//!
+//! - `preallocate` is a debug-logged no-op. Windows has no
+//!   `fallocate`-equivalent that keeps the reported size, so extent
+//!   reservation is not wired up.
+//! - `durable_sync` delegates to the std `File::sync_all`, which on
+//!   Windows maps to `FlushFileBuffers`. Unlike the Linux/macOS impls
+//!   this is NOT wrapped in the bounded-syscall primitive (that would
+//!   need an `unsafe impl Send` for `RawHandle`, which cannot be
+//!   validated without a Windows test env), so a wedged UNC/SMB share
+//!   can block the final flush. This deviation is documented on
+//!   [`super::WritebackFile::sync_all`] and the parent module's
+//!   Halt-safety section.
+
+use std::fs::File;
+use std::io;
+
+pub(super) fn preallocate(_file: &File, size_bytes: u64) {
+    tracing::debug!(
+        target: "mux",
+        "WritebackFile preallocate size_hint={size_bytes} skipped (no-op on windows)"
+    );
+}
+
+pub(super) fn durable_sync(file: &File) -> io::Result<()> {
+    // `File::sync_all` on Windows is `FlushFileBuffers`. Not wrapped in
+    // the bounded-syscall primitive (see the module doc) — unbounded.
+    file.sync_all()
+}

src/keydb.rs

@@ -0,0 +1,359 @@
+//! KEYDB.cfg updater — HTTP GET, unzip, verify, save.
+//!
+//! Zero external HTTP dependencies. Raw TCP for HTTP GET.
+//! Uses `zip` and `flate2` (already in deps) for extraction.
+
+use crate::error::{Error, Result};
+use std::io::{Read, Write};
+use std::net::{TcpStream, ToSocketAddrs};
+use std::path::PathBuf;
+use std::time::Duration;
+
+/// Network operation timeout (connect / read / write). Keeps the daily
+/// refresh thread from blocking indefinitely on an unresponsive mirror.
+const NET_TIMEOUT: Duration = Duration::from_secs(10);
+
+/// Read timeout — longer than connect/write since the keydb body can be
+/// several MiB over a slow link.
+const READ_TIMEOUT: Duration = Duration::from_secs(30);
+
+/// Maximum redirects to follow before giving up.
+const MAX_REDIRECTS: usize = 5;
+
+/// Upper bound on decompressed keydb size. The published keydb is a few
+/// MiB; 64 MiB is a generous ceiling that still caps a decompression
+/// bomb (a tiny zip/gz can otherwise inflate to GiB and OOM the daily
+/// refresh thread).
+const MAX_KEYDB_BYTES: u64 = 64 * 1024 * 1024;
+
+/// Read a decompressed stream into a String with a hard size ceiling.
+/// Returns `Error::KeydbInvalid` if the input exceeds the cap or is not
+/// valid UTF-8.
+fn read_capped_to_string<R: Read>(reader: R) -> Result<String> {
+    let mut buf = Vec::new();
+    // Read one byte past the cap so an exactly-at-cap stream is accepted
+    // but anything larger is rejected.
+    reader
+        .take(MAX_KEYDB_BYTES + 1)
+        .read_to_end(&mut buf)
+        .map_err(|_| Error::KeydbParse)?;
+    if buf.len() as u64 > MAX_KEYDB_BYTES {
+        return Err(Error::KeydbInvalid);
+    }
+    String::from_utf8(buf).map_err(|_| Error::KeydbParse)
+}
+
+/// Standard keydb storage path.
+pub fn default_path() -> Result<PathBuf> {
+    let home = std::env::var("HOME")
+        .or_else(|_| std::env::var("USERPROFILE"))
+        .map_err(|_| Error::KeydbParse)?;
+    Ok(PathBuf::from(home)
+        .join(".config")
+        .join("freemkv")
+        .join("keydb.cfg"))
+}
+
+/// Download a KEYDB from a URL, verify, save to the standard path.
+pub fn update(url: &str) -> Result<UpdateResult> {
+    let body = http_get(url)?;
+    save(&body)
+}
+
+/// Verify and save raw keydb bytes (plain text, .zip, or .gz).
+pub fn save(data: &[u8]) -> Result<UpdateResult> {
+    let text = if data.starts_with(b"PK\x03\x04") {
+        extract_zip(data)?
+    } else if data.starts_with(&[0x1f, 0x8b]) {
+        read_capped_to_string(flate2::read::GzDecoder::new(data))?
+    } else {
+        std::str::from_utf8(data)
+            .map(str::to_string)
+            .map_err(|_| Error::KeydbParse)?
+    };
+
+    let entries = text
+        .lines()
+        .filter(|l| {
+            let t = l.trim();
+            t.starts_with("0x")
+                || t.starts_with("| DK")
+                || t.starts_with("| PK")
+                || t.starts_with("| HC")
+        })
+        .count();
+
+    if entries == 0 {
+        return Err(Error::KeydbInvalid);
+    }
+
+    let path = default_path()?;
+    if let Some(dir) = path.parent() {
+        std::fs::create_dir_all(dir).map_err(|_| Error::KeydbWrite {
+            path: path.display().to_string(),
+        })?;
+    }
+    std::fs::write(&path, &text).map_err(|_| Error::KeydbWrite {
+        path: path.display().to_string(),
+    })?;
+
+    Ok(UpdateResult {
+        path,
+        entries,
+        bytes: text.len(),
+    })
+}
+
+/// Result of a KEYDB update -- path written, entry count, and byte size.
+#[derive(Debug)]
+pub struct UpdateResult {
+    pub path: PathBuf,
+    pub entries: usize,
+    pub bytes: usize,
+}
+
+fn http_get(url: &str) -> Result<Vec<u8>> {
+    let (mut host, mut port, mut path) = parse_url(url)?;
+
+    for _ in 0..MAX_REDIRECTS {
+        // Resolve to a concrete socket address so we can bound the connect
+        // with connect_timeout (plain connect() uses the OS default, which
+        // can be minutes).
+        let addr = (host.as_str(), port)
+            .to_socket_addrs()
+            .ok()
+            .and_then(|mut it| it.next())
+            .ok_or_else(|| Error::KeydbConnect { host: host.clone() })?;
+        let mut stream = TcpStream::connect_timeout(&addr, NET_TIMEOUT)
+            .map_err(|_| Error::KeydbConnect { host: host.clone() })?;
+        stream.set_read_timeout(Some(READ_TIMEOUT)).ok();
+        stream.set_write_timeout(Some(NET_TIMEOUT)).ok();
+
+        // HTTP/1.0 forces close-delimited framing: the server cannot reply
+        // with Transfer-Encoding: chunked, so the raw body is the keydb
+        // bytes with no chunk-size lines to de-frame.
+        let request = format!(
+            "GET {path} HTTP/1.0\r\nHost: {host}\r\nConnection: close\r\nAccept-Encoding: identity\r\n\r\n"
+        );
+        stream
+            .write_all(request.as_bytes())
+            .map_err(|_| Error::KeydbConnect { host: host.clone() })?;
+
+        let mut response = Vec::new();
+        stream
+            .take(100 * 1024 * 1024)
+            .read_to_end(&mut response)
+            .map_err(|_| Error::KeydbConnect { host: host.clone() })?;
+
+        let header_end = find_header_end(&response).ok_or(Error::KeydbParse)?;
+        // Lossy: a stray non-UTF-8 byte in the header block must not blank
+        // out the whole status line / Location header (which would surface
+        // as an undiagnosable KeydbHttp{status:0}).
+        let headers = String::from_utf8_lossy(&response[..header_end]);
+        let body = &response[header_end + 4..];
+
+        let status = parse_status(&headers);
+
+        // Only treat a Location header as a redirect when the status is
+        // actually 3xx; a 200 carrying a stray Location (some proxies) is
+        // not a redirect, and a 3xx without Location is a malformed redirect.
+        if (300..=399).contains(&status) {
+            let location =
+                extract_header(&headers, "Location").ok_or(Error::KeydbHttp { status })?;
+            let (next_host, next_port, next_path) = resolve_redirect(&location, &host, port)?;
+            host = next_host;
+            port = next_port;
+            path = next_path;
+            continue;
+        }
+
+        if status != 200 {
+            return Err(Error::KeydbHttp { status });
+        }
+
+        return Ok(body.to_vec());
+    }
+
+    Err(Error::KeydbTooManyRedirects)
+}
+
+/// Resolve a `Location` value against the current request target.
+/// Handles absolute `http://` URLs, scheme-relative `//host/path`,
+/// absolute paths `/path`, and rejects unsupported schemes (e.g.
+/// `https://`, which this dependency-light client cannot fetch) with a
+/// diagnosable error rather than a generic parse failure.
+fn resolve_redirect(
+    location: &str,
+    cur_host: &str,
+    cur_port: u16,
+) -> Result<(String, u16, String)> {
+    let loc = location.trim();
+
+    if let Some(rest) = loc.strip_prefix("//") {
+        // Scheme-relative: //host[:port]/path — inherit http.
+        return parse_url(&format!("http://{rest}"));
+    }
+    if loc.starts_with('/') {
+        // Absolute path on the same host/port.
+        return Ok((cur_host.to_string(), cur_port, loc.to_string()));
+    }
+    if let Some(scheme) = loc.split("://").next() {
+        if loc.contains("://") && !scheme.eq_ignore_ascii_case("http") {
+            return Err(Error::KeydbUnsupportedScheme {
+                scheme: scheme.to_string(),
+            });
+        }
+    }
+    parse_url(loc)
+}
+
+fn parse_url(url: &str) -> Result<(String, u16, String)> {
+    // Reject non-http(s) up front so the caller gets a scheme diagnostic
+    // rather than an opaque parse error.
+    if let Some(scheme) = url.split("://").next() {
+        if url.contains("://") && !scheme.eq_ignore_ascii_case("http") {
+            return Err(Error::KeydbUnsupportedScheme {
+                scheme: scheme.to_string(),
+            });
+        }
+    }
+    let url = url.strip_prefix("http://").ok_or(Error::KeydbParse)?;
+    let (host_port, path) = match url.find('/') {
+        Some(i) => (&url[..i], &url[i..]),
+        None => (url, "/"),
+    };
+    let (host, port) = match host_port.find(':') {
+        Some(i) => {
+            let port_str = &host_port[i + 1..];
+            // A non-empty-but-unparseable port is a malformed URL; only an
+            // omitted port defaults to 80.
+            let port = if port_str.is_empty() {
+                80
+            } else {
+                port_str.parse().map_err(|_| Error::KeydbParse)?
+            };
+            (&host_port[..i], port)
+        }
+        None => (host_port, 80u16),
+    };
+    Ok((host.to_string(), port, path.to_string()))
+}
+
+fn parse_status(headers: &str) -> u16 {
+    headers
+        .lines()
+        .next()
+        .and_then(|l| l.split_whitespace().nth(1))
+        .and_then(|s| s.parse().ok())
+        .unwrap_or(0)
+}
+
+fn find_header_end(data: &[u8]) -> Option<usize> {
+    data.windows(4).position(|w| w == b"\r\n\r\n")
+}
+
+fn extract_header(headers: &str, name: &str) -> Option<String> {
+    // Split on the first ':' rather than byte-indexing at name.len(),
+    // which would panic on a multibyte UTF-8 codepoint straddling that
+    // offset (headers are decoded from untrusted network bytes). Also
+    // accepts single-character values (e.g. "Location:x").
+    for line in headers.lines() {
+        if let Some((key, value)) = line.split_once(':') {
+            if key.trim().eq_ignore_ascii_case(name) {
+                return Some(value.trim().to_string());
+            }
+        }
+    }
+    None
+}
+
+fn extract_zip(data: &[u8]) -> Result<String> {
+    let cursor = std::io::Cursor::new(data);
+    let mut archive = zip::ZipArchive::new(cursor).map_err(|_| Error::KeydbParse)?;
+
+    for i in 0..archive.len() {
+        let file = archive.by_index(i).map_err(|_| Error::KeydbParse)?;
+        if file.name().ends_with(".cfg") || file.name().ends_with(".CFG") {
+            return read_capped_to_string(file);
+        }
+    }
+
+    Err(Error::KeydbInvalid)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_url_defaults_and_paths() {
+        let (h, p, path) = parse_url("http://example.com/keydb.zip").unwrap();
+        assert_eq!(
+            (h.as_str(), p, path.as_str()),
+            ("example.com", 80, "/keydb.zip")
+        );
+
+        let (h, p, path) = parse_url("http://example.com:8080").unwrap();
+        assert_eq!((h.as_str(), p, path.as_str()), ("example.com", 8080, "/"));
+    }
+
+    #[test]
+    fn parse_url_rejects_https_scheme() {
+        // TLS is unsupported by this client; surface a scheme diagnostic
+        // rather than a generic parse error.
+        assert!(matches!(
+            parse_url("https://example.com/k.zip"),
+            Err(Error::KeydbUnsupportedScheme { .. })
+        ));
+    }
+
+    #[test]
+    fn parse_url_rejects_malformed_port() {
+        // Non-empty-but-unparseable port must error, not silently fall to 80.
+        assert!(matches!(
+            parse_url("http://example.com:abc/path"),
+            Err(Error::KeydbParse)
+        ));
+        // An empty port still defaults to 80.
+        let (_, p, _) = parse_url("http://example.com:/path").unwrap();
+        assert_eq!(p, 80);
+    }
+
+    #[test]
+    fn redirect_to_https_is_unsupported_scheme_not_parse_error() {
+        // The bplaced-style mirror enabling TLS on a redirect must produce a
+        // diagnosable scheme error, not KeydbParse.
+        assert!(matches!(
+            resolve_redirect("https://mirror.example/keydb.zip", "old.host", 80),
+            Err(Error::KeydbUnsupportedScheme { .. })
+        ));
+    }
+
+    #[test]
+    fn redirect_scheme_relative_and_absolute_path() {
+        // Scheme-relative //host/path inherits http.
+        let (h, p, path) = resolve_redirect("//mirror.example/a.zip", "old.host", 80).unwrap();
+        assert_eq!(
+            (h.as_str(), p, path.as_str()),
+            ("mirror.example", 80, "/a.zip")
+        );
+
+        // Absolute path stays on the current host/port.
+        let (h, p, path) = resolve_redirect("/new/path.zip", "cur.host", 8080).unwrap();
+        assert_eq!(
+            (h.as_str(), p, path.as_str()),
+            ("cur.host", 8080, "/new/path.zip")
+        );
+
+        // Absolute http URL is followed normally.
+        let (h, _, path) = resolve_redirect("http://other.host/x.zip", "cur.host", 80).unwrap();
+        assert_eq!((h.as_str(), path.as_str()), ("other.host", "/x.zip"));
+    }
+
+    #[test]
+    fn parse_status_extracts_code() {
+        assert_eq!(parse_status("HTTP/1.0 200 OK\r\nFoo: bar"), 200);
+        assert_eq!(parse_status("HTTP/1.1 301 Moved Permanently"), 301);
+        assert_eq!(parse_status("garbage"), 0);
+    }
+}

src/keysource.rs

@@ -0,0 +1,95 @@
+//! Key sources — the lookup layer that hands libfreemkv a [`Key`].
+//!
+//! libfreemkv performs NO key lookup. An application resolves a key for a disc
+//! through one or more [`KeySource`]s, each a dumb adapter over a backing store
+//! (a keydb file, a key server, the mapfile cache): given the disc's
+//! [`DiscInputs`] it returns the raw [`Key`] at whatever level it holds. The
+//! library then derives down and decrypts via `Disc::decrypt_with`.
+//!
+//! Source implementations are published in the companion `freemkv-keysources`
+//! crate — keeping all key *policy* (which store, which order, online vs local)
+//! out of the library while all key *mechanism* (the AACS derivation chain)
+//! stays in it.
+
+use crate::disc::Key;
+
+/// The public AACS inputs a key source needs to look a disc up. Captured at
+/// scan; contains no secrets — only the disc identity and the on-disc AACS
+/// structures a source or key server may key on.
+#[derive(Debug, Clone)]
+pub struct DiscInputs {
+    /// SHA-1 of `Unit_Key_RO.inf`, `0x`-prefixed hex. The value a keydb keys
+    /// its per-disc entries by, and a key server identifies the disc with.
+    pub disc_hash: String,
+    /// Volume ID (16 bytes). `[0u8; 16]` when no authenticated handshake ran
+    /// (e.g. an ISO/mapfile flow), which disables VID-keyed lookups.
+    pub volume_id: [u8; 16],
+    /// Raw MKB bytes. Empty when not captured.
+    pub mkb: Vec<u8>,
+    /// Raw `Unit_Key_RO.inf` bytes. Empty when not captured.
+    pub unit_key_ro: Vec<u8>,
+    /// Encrypted on-disc content sample units (each a 6144-byte aligned unit),
+    /// for sources that validate a key server-side against real ciphertext
+    /// (e.g. an online key service). Empty for sources that don't need them
+    /// (a local keydb). Populated by the application — reading content requires
+    /// the disc reader, which the library's scan does not retain — so
+    /// [`crate::Disc::inputs`] leaves it empty for the caller to fill.
+    pub samples: Vec<Vec<u8>>,
+    /// The disc's human title — the UDF/ISO volume identifier (e.g.
+    /// `WICKED_FOR_GOOD`), falling back to the BDMV `<di:name>` when present.
+    /// `None` when not captured. Identity only, no secret; a key service may
+    /// record it (keyed by `disc_hash`) to build a hash→title catalog. Not used
+    /// in any AACS derivation.
+    pub volume_label: Option<String>,
+}
+
+/// A key source: a stateful provider that hands a disc's candidate [`Key`]s out
+/// **one at a time**, in whatever order it judges best for its backing store.
+///
+/// Dumb by contract — a source queries its store and yields the raw material it
+/// holds at whatever level it has (device / processing / media / volume / unit).
+/// It performs NO AACS derivation and NO validation: `Disc::decrypt_with`
+/// derives down AND validates against real ciphertext, returning `Err` for a key
+/// that does not decrypt this disc. That keeps every derivation step and the one
+/// validation gate in the library, across AACS 1.0 / 2.0 / 2.1 / 2.x.
+///
+/// The source is the one that knows how many candidates it has and in what order
+/// to try them — a keydb holds a per-disc UK *and* VUK *and* a device-key pool,
+/// so it hands them out cheapest/most-specific first (UK ▸ VK ▸ MK ▸ DK) and
+/// reports exhaustion when its list runs out; an online key service or a mapfile
+/// cache hold exactly one. The caller drives the loop: `next_key` →
+/// `Disc::decrypt_with` → on `Err`, ask again → until a key decrypts or the
+/// source returns `None` (a genuine "no key for this disc"). Compose several
+/// sources, in the caller's chosen order, with the companion
+/// `freemkv-keysources` crate's `MultiSource`.
+pub trait KeySource {
+    /// Hand the NEXT candidate key for this disc, or `None` once this source is
+    /// exhausted. Stateful: the source tracks what it already handed out this
+    /// session, so asking again after a rejected key yields the next candidate
+    /// (or `None`) — it never re-offers a key or re-hits a one-shot backend (an
+    /// online service is asked at most once).
+    ///
+    /// `None` means only "no more candidates from this source"; it does NOT by
+    /// itself distinguish a genuine "no key for this disc" from a source
+    /// failure (I/O, network, parse). After exhaustion the caller must consult
+    /// [`KeySource::errored`] to tell the two apart — a failed source records
+    /// the failure there and still returns `None` here.
+    fn next_key(&mut self, inputs: &DiscInputs) -> Option<Key>;
+
+    /// Whether this source needs [`DiscInputs::samples`] populated (encrypted
+    /// content samples) — true for a source that validates against ciphertext
+    /// server-side, false for one that keys purely on disc identity. The caller
+    /// reads samples (an extra disc read) only when some source needs them.
+    fn needs_samples(&self) -> bool {
+        false
+    }
+
+    /// Whether this source FAILED (I/O, network, parse) rather than simply
+    /// having no key. Checked after exhaustion so the caller can tell a genuine
+    /// "no key for this disc" apart from "the key service was unreachable". A
+    /// store that treats absence as not-an-error (a missing keydb / mapfile)
+    /// leaves this `false`.
+    fn errored(&self) -> bool {
+        false
+    }
+}

src/labels/bdmt.rs

@@ -0,0 +1,471 @@
+//! 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. It is invoked from the
+//! disc-scan path in [`labels`](super) ([`detect`] then [`parse`]),
+//! and [`DiscMetadata`] is re-exported there.
+//!
+//! 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.
+
+use super::xml;
+use crate::sector::SectorSource;
+use crate::udf::UdfFs;
+use std::collections::BTreeMap;
+
+/// Upper bound on the size of a single `bdmt_<lang>.xml` we will read.
+/// The size comes from attacker-controlled UDF metadata; real files are
+/// a few KB, so 1 MiB is generous while preventing a crafted huge-size
+/// entry from triggering an oversized allocation in `read_file`.
+const MAX_BDMT_BYTES: u64 = 1024 * 1024;
+
+/// 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" → "Aurora Drift")
+    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;
+        };
+        // entry.size is attacker-controlled UDF metadata and flows into
+        // a Vec::with_capacity in read_file. A real BDMV bdmt XML is a
+        // few KB; cap well above that so a crafted multi-GB size can't
+        // trigger a huge allocation before any parsing.
+        if !bdmt_size_acceptable(entry.size) {
+            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(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)
+    }
+}
+
+/// Gate a `bdmt_<lang>.xml` file by its declared (untrusted) UDF size
+/// before reading it. Anything over [`MAX_BDMT_BYTES`] is skipped to
+/// avoid an oversized allocation in `read_file`.
+fn bdmt_size_acceptable(size: u64) -> bool {
+    size <= MAX_BDMT_BYTES
+}
+
+/// 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(xml_text: &str) -> Option<BdmtFields> {
+    let title = extract_title(xml_text)?;
+    // xml::text already returns a trimmed string (see xml::text), so the
+    // description is only filtered for emptiness and XML-fragment noise.
+    let description = xml::text(xml_text, "description")
+        .filter(|s| !s.is_empty())
+        .filter(|s| !looks_like_xml(s));
+    let disc_set = extract_disc_set(xml_text);
+    Some((title, description, disc_set))
+}
+
+/// Reject candidate description strings that are themselves XML
+/// fragments — observed on a captured disc, 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.
+    // xml::text already trims its result, so an empty string after
+    // extraction means a genuinely empty element.
+    for tag in ["name", "title"] {
+        if let Some(s) = xml::text(xml_text, tag) {
+            if !s.is_empty() {
+                return Some(s);
+            }
+        }
+    }
+    // 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") {
+            if !t.is_empty() {
+                return Some(t);
+            }
+        }
+    }
+    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()?;
+    // Reject nonsensical "Disc N of M" values: (0,0), (0,5), (5,2)...
+    // These serialize to JSON and reach downstream consumers as
+    // meaningless metadata.
+    if n < 1 || total < 1 || n > total {
+        return None;
+    }
+    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>Aurora Drift</di:name>
+</discInfo>"#;
+        let (title, desc, set) = parse_bdmt_xml(xml).expect("title should parse");
+        assert_eq!(title, "Aurora Drift");
+        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>Echo Chamber</di:title>
+  <di:description>A film about machines.</di:description>
+</discInfo>"#;
+        let (title, desc, _) = parse_bdmt_xml(xml).unwrap();
+        assert_eq!(title, "Echo Chamber");
+        assert_eq!(desc.as_deref(), Some("A film about machines."));
+    }
+
+    #[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>Feelings Two</di:titleName>
+  </di:tableOfContents>
+</discInfo>"#;
+        let (title, _, _) = parse_bdmt_xml(xml).unwrap();
+        assert_eq!(title, "Feelings Two");
+    }
+
+    #[test]
+    fn bdmt_size_gate_rejects_oversized_entries() {
+        assert!(bdmt_size_acceptable(0));
+        assert!(bdmt_size_acceptable(4096));
+        assert!(bdmt_size_acceptable(MAX_BDMT_BYTES));
+        assert!(!bdmt_size_acceptable(MAX_BDMT_BYTES + 1));
+        // A crafted multi-GB size is rejected before any allocation.
+        assert!(!bdmt_size_acceptable(8 * 1024 * 1024 * 1024));
+        assert!(!bdmt_size_acceptable(u64::MAX));
+    }
+
+    #[test]
+    fn disc_set_rejects_nonsensical_pairs() {
+        // n > total, zero numerator, zero denominator → all None.
+        let over = r#"<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
+  <di:name>X</di:name>
+  <di:discNumber>5</di:discNumber>
+  <di:numSets>2</di:numSets>
+</discInfo>"#;
+        assert_eq!(parse_bdmt_xml(over).unwrap().2, None);
+
+        let zero_n = r#"<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
+  <di:name>X</di:name>
+  <di:discNumber>0</di:discNumber>
+  <di:numSets>5</di:numSets>
+</discInfo>"#;
+        assert_eq!(parse_bdmt_xml(zero_n).unwrap().2, None);
+
+        let zero_total = r#"<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
+  <di:name>X</di:name>
+  <di:discNumber>1</di:discNumber>
+  <di:numSets>0</di:numSets>
+</discInfo>"#;
+        assert_eq!(parse_bdmt_xml(zero_total).unwrap().2, None);
+
+        // A valid pair still passes.
+        let ok = r#"<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
+  <di:name>X</di:name>
+  <di:discNumber>2</di:discNumber>
+  <di:numSets>3</di:numSets>
+</discInfo>"#;
+        assert_eq!(parse_bdmt_xml(ok).unwrap().2, Some((2, 3)));
+    }
+
+    #[test]
+    fn extract_box_set_position() {
+        let xml = r#"<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
+  <di:name>Box Set Disc 2</di:name>
+  <di:discNumber>2</di:discNumber>
+  <di:numSets>5</di:numSets>
+</discInfo>"#;
+        let (_, _, set) = parse_bdmt_xml(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(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(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>Aurora Drift</di:name>
+</discInfo>"#;
+        let fra_xml = r#"<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
+  <di:name>Aurora Drift (Partie Deux)</di:name>
+  <di:description>Suite du film fictif.</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(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("Aurora Drift")
+        );
+        assert_eq!(
+            meta.titles.get("fra").map(String::as_str),
+            Some("Aurora Drift (Partie Deux)")
+        );
+        assert!(meta.descriptions.get("eng").is_none());
+        assert_eq!(
+            meta.descriptions.get("fra").map(String::as_str),
+            Some("Suite du film fictif.")
+        );
+        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(bad).is_none());
+
+        // Half-open tag, no body, no close: also yields no title.
+        let truncated = "<discInfo><di:name>";
+        assert!(parse_bdmt_xml(truncated).is_none());
+    }
+
+    #[test]
+    fn description_with_only_child_xml_is_dropped() {
+        // Real-world bug: <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>Skyline Run</di:name>
+            <di:description>
+              <di:thumbnail href="sample_meta_sm.jpg" />
+              <di:thumbnail href="sample_meta_lg.jpg" />
+            </di:description>
+        </discInfo>"#;
+        let (title, description, _) =
+            parse_bdmt_xml(xml).expect("title is present so parse must succeed");
+        assert_eq!(title, "Skyline Run");
+        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(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>
+            Aurora Drift
+        </di:name></discInfo>"#;
+        let (title, _, _) = parse_bdmt_xml(xml).unwrap();
+        assert_eq!(title, "Aurora Drift");
+    }
+
+    #[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);
+    }
+}

src/labels/clpi_audit.rs

@@ -0,0 +1,321 @@
+//! CLPI vs MPLS cross-validation diagnostic.
+//!
+//! Walks both per-clip CLPI program info and per-playlist MPLS STN
+//! tables, normalizes their stream lists by `(PID, language,
+//! coding_type)`, and classifies each PID into one of four buckets:
+//!
+//! 1. **CLPI only** — a stream present in a `.clpi` ProgramInfo that no
+//!    playlist STN table references (orphan on disc).
+//! 2. **MPLS only** — a stream a playlist references that no `.clpi`
+//!    ProgramInfo lists (indicates a parser disagreement).
+//! 3. **Match** — both sources agree on coding_type and language.
+//! 4. **Divergent** — both sources see the PID but disagree on
+//!    coding_type or language.
+//!
+//! [`audit`] returns a structured [`ClpiVsMplsAudit`] report. This is a
+//! diagnostic surface only; it does not feed the label-selection
+//! pipeline.
+
+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 {
+    /// Classification rules:
+    /// - one coding_type present, the other missing → `ClpiOnly` /
+    ///   `MplsOnly`
+    /// - both coding_types present, fields differ → `Divergent`
+    /// - both coding_types present and identical → `Match`
+    /// - both coding_types missing (`audit` never builds this, but a
+    ///   caller can construct such a row) → compare the language fields:
+    ///   `Divergent` if they differ, else `Match`
+    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) => {
+                if self.clpi_language == self.mpls_language {
+                    ClpiVsMplsClass::Match
+                } else {
+                    ClpiVsMplsClass::Divergent
+                }
+            }
+        }
+    }
+}
+
+/// 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 {
+    /// Count rows by class, returned in the fixed order
+    /// `(clpi_only, mpls_only, matches, divergent)` matching the
+    /// [`ClpiVsMplsClass`] variants.
+    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 {
+                if s.pid == 0 {
+                    // PID 0 means "no PID in stream entry" — skip rather
+                    // than collide, mirroring the MPLS side below.
+                    continue;
+                }
+                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_both_coding_missing_divergent_on_lang() {
+        // Caller-built row with neither coding_type but disagreeing
+        // languages must classify Divergent, not Match.
+        let r = ClpiVsMplsRow {
+            pid: 0x1100,
+            clpi_coding_type: None,
+            clpi_language: Some("eng".into()),
+            mpls_coding_type: None,
+            mpls_language: Some("fra".into()),
+        };
+        assert_eq!(r.class(), ClpiVsMplsClass::Divergent);
+    }
+
+    #[test]
+    fn class_both_coding_missing_match_on_equal_lang() {
+        let r = ClpiVsMplsRow {
+            pid: 0x1100,
+            clpi_coding_type: None,
+            clpi_language: Some("eng".into()),
+            mpls_coding_type: None,
+            mpls_language: Some("eng".into()),
+        };
+        assert_eq!(r.class(), ClpiVsMplsClass::Match);
+    }
+
+    #[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);
+    }
+}

src/labels/criterion.rs

@@ -0,0 +1,258 @@
+//! Criterion Collection — `streamproperties.xml` + `playbackconfig.xml`
+//!
+//! Clean structured XML with Content/Qualifier per stream and
+//! stream number mapping via playbackconfig.
+//!
+//! When `playbackconfig.xml` is absent or maps only some streams,
+//! unmapped streams get 1-based-per-type stream numbers synthesized in
+//! `streamproperties.xml` order, skipping any number already claimed by
+//! the map so synthesized and mapped numbers never collide. See
+//! [`assign_stream_numbers`].
+
+use super::{LabelPurpose, LabelQualifier, ParseResult, StreamLabel, StreamLabelType, xml};
+use crate::sector::SectorSource;
+use crate::udf::UdfFs;
+use std::collections::HashMap;
+
+/// Cheap signature check: a Criterion disc ships `streamproperties.xml`
+/// inside a `/BDMV/JAR/*` archive.
+pub fn detect(udf: &UdfFs) -> bool {
+    super::jar_file_exists(udf, "streamproperties.xml")
+}
+
+/// Parse `streamproperties.xml` (+ optional `playbackconfig.xml`) into
+/// per-stream labels. Returns `None` if `streamproperties.xml` is
+/// absent/unparseable or yields no streams. Stream numbering follows
+/// the contract documented at module level (see
+/// [`assign_stream_numbers`]).
+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()?;
+
+    let stream_infos = parse_stream_infos(sp_text);
+    if stream_infos.is_empty() {
+        return None;
+    }
+
+    // Stream number mapping from playbackconfig.xml
+    let mut stream_map: HashMap<String, u16> = HashMap::new();
+    if let Some(pc_data) = super::read_jar_file(reader, udf, "playbackconfig.xml") {
+        if let Ok(pc_text) = std::str::from_utf8(&pc_data) {
+            parse_playback_config(pc_text, &mut stream_map);
+        }
+    }
+
+    let stream_nums = assign_stream_numbers(&stream_infos, &stream_map);
+
+    let mut labels = Vec::new();
+    for (info, &stream_num) in stream_infos.iter().zip(stream_nums.iter()) {
+        labels.push(StreamLabel {
+            stream_number: stream_num,
+            stream_type: info.stream_type,
+            language: info.language.clone(),
+            name: String::new(),
+            purpose: info.purpose,
+            qualifier: info.qualifier,
+            codec_hint: String::new(),
+            variant: info.variant.clone(),
+        });
+    }
+
+    if labels.is_empty() {
+        return None;
+    }
+    // High confidence: streamproperties.xml is fully structured.
+    Some(ParseResult::high(labels))
+}
+
+/// Assign a 1-based stream number per `StreamInfo`, parallel to
+/// `infos`.
+///
+/// A stream mapped in `playbackconfig.xml` (`stream_map`) keeps its
+/// mapped number. Streams with no mapping (absent or incomplete
+/// `playbackconfig.xml`, or an unmatched `StreamInfo_ID`) are numbered
+/// 1-based per type — but the fallback counter SKIPS any number already
+/// claimed via the map, so a synthesized number can never collide with a
+/// map-assigned one. (Both numbering domains are 1-based per type, and
+/// `apply_labels` matches on `(type, stream_number)`, so a collision
+/// would mislabel tracks.)
+fn assign_stream_numbers(infos: &[StreamInfo], stream_map: &HashMap<String, u16>) -> Vec<u16> {
+    // Numbers already claimed by the map, per type.
+    let mut taken_audio: Vec<u16> = Vec::new();
+    let mut taken_sub: Vec<u16> = Vec::new();
+    for info in infos {
+        if let Some(&n) = stream_map.get(&info.id) {
+            match info.stream_type {
+                StreamLabelType::Audio => taken_audio.push(n),
+                StreamLabelType::Subtitle => taken_sub.push(n),
+            }
+        }
+    }
+
+    let mut audio_idx: u16 = 1;
+    let mut sub_idx: u16 = 1;
+    let mut out = Vec::with_capacity(infos.len());
+    for info in infos {
+        let n = match stream_map.get(&info.id).copied() {
+            Some(n) => n,
+            None => {
+                let (idx, taken) = match info.stream_type {
+                    StreamLabelType::Audio => (&mut audio_idx, &taken_audio),
+                    StreamLabelType::Subtitle => (&mut sub_idx, &taken_sub),
+                };
+                // Advance past any number already claimed via the map.
+                // saturating: a crafted XML with >65k stream entries must
+                // not overflow (panic in debug, wrap-to-0 in release) on
+                // untrusted disc bytes.
+                while taken.contains(idx) {
+                    *idx = idx.saturating_add(1);
+                }
+                let n = *idx;
+                *idx = idx.saturating_add(1);
+                n
+            }
+        };
+        out.push(n);
+    }
+    out
+}
+
+struct StreamInfo {
+    id: String,
+    stream_type: StreamLabelType,
+    language: String,
+    variant: String,
+    purpose: LabelPurpose,
+    qualifier: LabelQualifier,
+}
+
+fn parse_stream_infos(text: &str) -> Vec<StreamInfo> {
+    let mut infos = Vec::new();
+
+    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 (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 = if content.eq_ignore_ascii_case("COMMENTARY") {
+                LabelPurpose::Commentary
+            } else {
+                LabelPurpose::Normal
+            };
+
+            let qualifier = match qualifier_str.to_ascii_uppercase().as_str() {
+                "SDH" => LabelQualifier::Sdh,
+                "DS" => LabelQualifier::DescriptiveService,
+                _ => LabelQualifier::None,
+            };
+
+            infos.push(StreamInfo {
+                id,
+                stream_type,
+                language,
+                variant,
+                purpose,
+                qualifier,
+            });
+            from = end;
+        }
+    }
+    infos
+}
+
+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>() {
+                    // Stream numbers are 1-based per the apply_labels
+                    // contract; a mapped 0 is unmatchable and silently
+                    // drops the label. Skip it rather than store it.
+                    if stream_num != 0 {
+                        map.insert(info_id, stream_num);
+                    }
+                }
+            }
+            from = end;
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn info(id: &str, t: StreamLabelType) -> StreamInfo {
+        StreamInfo {
+            id: id.into(),
+            stream_type: t,
+            language: "eng".into(),
+            variant: String::new(),
+            purpose: LabelPurpose::Normal,
+            qualifier: LabelQualifier::None,
+        }
+    }
+
+    #[test]
+    fn fallback_numbers_dense_when_map_empty() {
+        let infos = vec![
+            info("a0", StreamLabelType::Audio),
+            info("a1", StreamLabelType::Audio),
+            info("s0", StreamLabelType::Subtitle),
+        ];
+        let nums = assign_stream_numbers(&infos, &HashMap::new());
+        // Per-type 1-based: audio 1,2 ; subtitle 1.
+        assert_eq!(nums, vec![1, 2, 1]);
+    }
+
+    #[test]
+    fn fallback_does_not_collide_with_partial_map() {
+        // Map claims audio "a1" -> 1. The unmapped audio "a0" must NOT
+        // also get 1 (the pre-fix bug); it must skip to 2.
+        let mut map = HashMap::new();
+        map.insert("a1".to_string(), 1u16);
+        let infos = vec![
+            info("a0", StreamLabelType::Audio), // unmapped → fallback
+            info("a1", StreamLabelType::Audio), // mapped → 1
+            info("a2", StreamLabelType::Audio), // unmapped → fallback
+        ];
+        let nums = assign_stream_numbers(&infos, &map);
+        // a0 skips the taken 1 → 2; a1 keeps 1; a2 → 3. All distinct.
+        assert_eq!(nums, vec![2, 1, 3]);
+        let mut sorted = nums.clone();
+        sorted.sort_unstable();
+        sorted.dedup();
+        assert_eq!(sorted.len(), 3, "stream numbers must be unique");
+    }
+
+    #[test]
+    fn map_fully_drives_numbers_when_complete() {
+        let mut map = HashMap::new();
+        map.insert("a0".to_string(), 5u16);
+        map.insert("a1".to_string(), 9u16);
+        let infos = vec![
+            info("a0", StreamLabelType::Audio),
+            info("a1", StreamLabelType::Audio),
+        ];
+        assert_eq!(assign_stream_numbers(&infos, &map), vec![5, 9]);
+    }
+}

src/labels/ctrm.rs

@@ -0,0 +1,484 @@
+//! Warner CTRM — `menu_base.prop` and/or `language_streams.txt`
+//!
+//! Two sub-formats from the same framework. A disc may have one or both.
+//! When both exist, language_streams.txt provides structured types while
+//! menu_base.prop provides stream number → button name mapping.
+
+use super::{LabelPurpose, LabelQualifier, ParseResult, StreamLabel, StreamLabelType, vocab};
+use crate::sector::SectorSource;
+use crate::udf::UdfFs;
+use std::collections::HashMap;
+
+/// Cheap signature check: a CTRM disc ships `menu_base.prop` and/or
+/// `language_streams.txt` inside a `/BDMV/JAR/*` archive.
+pub fn detect(udf: &UdfFs) -> bool {
+    super::jar_file_exists(udf, "menu_base.prop")
+        || super::jar_file_exists(udf, "language_streams.txt")
+}
+
+/// Full extraction: parses `language_streams.txt` (structured types) and
+/// `menu_base.prop` (stream numbers + button names), merging when both
+/// are present. Returns `None` when neither file is present/parseable or
+/// no labels result.
+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);
+
+    // Try menu_base.prop (stream numbers + key names)
+    let mb_labels = parse_menu_base(reader, udf);
+
+    // If we have both, merge: language_streams for structure, menu_base for names
+    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> {
+    // language_streams has better type/purpose data, menu_base has button names
+    // Match by stream number + type, take name from menu_base
+    let mut result = ls;
+    for label in &mut result {
+        if let Some(mb_match) = mb
+            .iter()
+            .find(|m| m.stream_type == label.stream_type && m.stream_number == label.stream_number)
+        {
+            if label.name.is_empty() && !mb_match.name.is_empty() {
+                label.name = mb_match.name.clone();
+            }
+        }
+    }
+    // Append any menu_base-only stream (present in mb but not in ls by
+    // (stream_type, stream_number)). Without this the both-files path
+    // silently drops streams the menu_base-only path would have emitted:
+    // language_streams is authoritative for type/purpose but is not
+    // necessarily a superset of menu_base.
+    for mb_label in mb {
+        let already = result.iter().any(|l| {
+            l.stream_type == mb_label.stream_type && l.stream_number == mb_label.stream_number
+        });
+        if !already {
+            result.push(mb_label);
+        }
+    }
+    result
+}
+
+/// True if a property-key prefix denotes a commentary stream group.
+/// Tightened from a bare `prefix.contains("comm")` substring scan, which
+/// over-matched unrelated prefixes like `common_*` / `community_*`. We
+/// split on `_` and require a `commentary` (or `comm`) segment.
+fn prefix_is_commentary(prefix: &str) -> bool {
+    prefix
+        .split('_')
+        .any(|seg| seg.eq_ignore_ascii_case("commentary") || seg.eq_ignore_ascii_case("comm"))
+}
+
+// ── language_streams.txt parser ────────────────────────────────────────────
+
+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()?;
+
+    let mut labels = Vec::new();
+
+    for line in text.lines() {
+        let line = line.trim();
+        if line.is_empty() || line.starts_with('#') {
+            continue;
+        }
+
+        let parts: Vec<&str> = line.split(',').map(|s| s.trim()).collect();
+        if parts.len() < 4 {
+            continue;
+        }
+
+        let type_str = parts[1];
+        // STN indices are 1-based; apply_labels pre-increments from 0 and
+        // never matches a 0, so a 0 here would emit a dead label. Skip it
+        // (matching the `n > 0` guard in parse_menu_base).
+        let stream_num: u16 = match parts[2].parse() {
+            Ok(n) if n > 0 => n,
+            _ => continue,
+        };
+        let language = parts[3].to_string();
+        let variant = if parts.len() > 4 {
+            parts[4].to_string()
+        } else {
+            String::new()
+        };
+
+        let (stream_type, purpose, qualifier) = match type_str {
+            "audio_production" => (
+                StreamLabelType::Audio,
+                LabelPurpose::Normal,
+                LabelQualifier::None,
+            ),
+            "audio_commentary" => (
+                StreamLabelType::Audio,
+                LabelPurpose::Commentary,
+                LabelQualifier::None,
+            ),
+            "audio_ime" => (
+                StreamLabelType::Audio,
+                LabelPurpose::Ime,
+                LabelQualifier::None,
+            ),
+            "subtitle_production" => (
+                StreamLabelType::Subtitle,
+                LabelPurpose::Normal,
+                LabelQualifier::None,
+            ),
+            "subtitle_commentary" => (
+                StreamLabelType::Subtitle,
+                LabelPurpose::Commentary,
+                LabelQualifier::None,
+            ),
+            "subtitle_narrative" => (
+                StreamLabelType::Subtitle,
+                LabelPurpose::Normal,
+                LabelQualifier::Forced,
+            ),
+            "subtitle_dual" => (
+                StreamLabelType::Subtitle,
+                LabelPurpose::Normal,
+                LabelQualifier::None,
+            ),
+            "subtitle_bonus" => (
+                StreamLabelType::Subtitle,
+                LabelPurpose::Normal,
+                LabelQualifier::None,
+            ),
+            "subtitle_ime" => (
+                StreamLabelType::Subtitle,
+                LabelPurpose::Ime,
+                LabelQualifier::None,
+            ),
+            "subtitle_ime_narrative" => (
+                StreamLabelType::Subtitle,
+                LabelPurpose::Ime,
+                LabelQualifier::Forced,
+            ),
+            _ => continue,
+        };
+
+        // Classify variant code
+        let mut codec_hint = String::new();
+        let mut variant_code = String::new();
+        let mut final_purpose = purpose;
+
+        if !variant.is_empty() {
+            match variant.as_str() {
+                // Purpose variants
+                "eda" => final_purpose = LabelPurpose::Descriptive,
+                // Dialect variants — pass through raw code from disc
+                "csp" | "cs" | "lsp" | "ls" | "cf" | "pf" | "bp" | "pp" => {
+                    variant_code = variant.clone();
+                }
+                // Everything else: defer to vocab::codec as the single
+                // source of codec-name truth. If it recognizes the token
+                // (returns something other than the input) it's a known
+                // codec — store the canonical name. Otherwise it's an
+                // unknown token, stored as-is.
+                _ => codec_hint = vocab::codec(&variant).to_string(),
+            }
+        }
+
+        labels.push(StreamLabel {
+            stream_number: stream_num,
+            stream_type,
+            language,
+            name: String::new(),
+            purpose: final_purpose,
+            qualifier,
+            codec_hint,
+            variant: variant_code,
+        });
+    }
+
+    if labels.is_empty() {
+        return None;
+    }
+    Some(labels)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Run the real shipping parser ([`parse_menu_base_text`]) on a
+    /// menu_base.prop body so tests exercise production code directly.
+    fn parse_props(text: &str) -> Vec<StreamLabel> {
+        parse_menu_base_text(text)
+    }
+
+    #[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);
+    }
+
+    #[test]
+    fn dual_flag_entry_resolves_to_audio_with_no_subtitle_qualifier() {
+        // An entry tripping BOTH flags (audio_ prefix sets is_audio,
+        // class "SubtitleButton" sets is_subtitle). Audio wins the type,
+        // and the subtitle qualifier (SDH) must NOT be carried onto the
+        // resulting Audio label. Regression for the type/qualifier split.
+        let labels = parse_props(
+            "audio_1.class=SubtitleButton\n\
+             audio_1.streamNumber=6\n\
+             audio_1.name=English SDH\n",
+        );
+        assert_eq!(labels.len(), 1);
+        assert_eq!(labels[0].stream_type, StreamLabelType::Audio);
+        assert_eq!(labels[0].qualifier, LabelQualifier::None);
+    }
+
+    #[test]
+    fn prefix_commentary_segment_match_not_substring() {
+        // Genuine commentary group segments match.
+        assert!(prefix_is_commentary("audio_commentary"));
+        assert!(prefix_is_commentary("audio_commentary_1"));
+        assert!(prefix_is_commentary("comm"));
+        // Substring-only prefixes must NOT match (the over-match bug).
+        assert!(!prefix_is_commentary("common"));
+        assert!(!prefix_is_commentary("audio_common_1"));
+        assert!(!prefix_is_commentary("community"));
+        assert!(!prefix_is_commentary("audio_1"));
+    }
+
+    fn lbl(t: StreamLabelType, n: u16, name: &str) -> StreamLabel {
+        StreamLabel {
+            stream_number: n,
+            stream_type: t,
+            language: String::new(),
+            name: name.to_string(),
+            purpose: LabelPurpose::Normal,
+            qualifier: LabelQualifier::None,
+            codec_hint: String::new(),
+            variant: String::new(),
+        }
+    }
+
+    #[test]
+    fn merge_preserves_menu_base_only_streams() {
+        // language_streams covers audio 1; menu_base has audio 1 (name)
+        // AND a menu_base-only audio 2. The merge must keep audio 2 —
+        // the both-files path previously dropped it.
+        let ls = vec![lbl(StreamLabelType::Audio, 1, "")];
+        let mb = vec![
+            lbl(StreamLabelType::Audio, 1, "Main"),
+            lbl(StreamLabelType::Audio, 2, "Commentary"),
+        ];
+        let merged = merge(ls, mb);
+        assert_eq!(merged.len(), 2, "menu_base-only stream must survive");
+        // ls audio 1 takes its name from mb.
+        let a1 = merged
+            .iter()
+            .find(|l| l.stream_type == StreamLabelType::Audio && l.stream_number == 1)
+            .unwrap();
+        assert_eq!(a1.name, "Main");
+        // mb-only audio 2 is appended.
+        assert!(
+            merged
+                .iter()
+                .any(|l| l.stream_number == 2 && l.name == "Commentary")
+        );
+    }
+}
+
+// ── menu_base.prop parser ──────────────────────────────────────────────────
+
+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()?;
+    let labels = parse_menu_base_text(text);
+    if labels.is_empty() {
+        return None;
+    }
+    Some(labels)
+}
+
+/// Parse the body of a `menu_base.prop` file into stream labels. Split
+/// out from [`parse_menu_base`] (which only handles file I/O + UTF-8
+/// decode) so unit tests exercise the real parsing logic instead of a
+/// hand-copied duplicate. Returns the labels sorted by (type, number).
+fn parse_menu_base_text(text: &str) -> Vec<StreamLabel> {
+    // Parse key=value, group by prefix
+    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 eq_pos = match line.find('=') {
+            Some(p) => p,
+            None => continue,
+        };
+        let full_key = &line[..eq_pos];
+        let value = &line[eq_pos + 1..];
+
+        if let Some(dot_pos) = full_key.rfind('.') {
+            let prefix = full_key[..dot_pos].to_string();
+            let key = full_key[dot_pos + 1..].to_string();
+            entries
+                .entry(prefix)
+                .or_default()
+                .insert(key, value.to_string());
+        }
+    }
+
+    let mut labels = Vec::new();
+
+    for (prefix, props) in &entries {
+        // Audio: has "streamNumber" or "audioStream" and audio-related class
+        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;
+        }
+
+        // Resolve the stream type FIRST: when an entry trips both flags
+        // (e.g. an `audio_` prefix with a class containing
+        // "SubtitleButton"), audio wins the type.
+        let stream_type = if is_audio {
+            StreamLabelType::Audio
+        } else {
+            StreamLabelType::Subtitle
+        };
+
+        let name = props.get("name").cloned().unwrap_or_default();
+
+        // 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_is_commentary(prefix) => LabelPurpose::Commentary,
+            p => p,
+        };
+
+        // Qualifier (SDH/Forced) is a subtitle-only concept. Gate on the
+        // RESOLVED type, not the raw is_subtitle flag, so an entry that
+        // resolved to Audio never carries a subtitle qualifier.
+        let qualifier = if stream_type == StreamLabelType::Subtitle {
+            vocab::qualifier(&name)
+        } else {
+            LabelQualifier::None
+        };
+
+        // Try to extract language from audioLanguage/subtitleLanguage prop
+        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
+}

src/labels/dbp.rs

@@ -0,0 +1,260 @@
+//! "dbp" framework — a BD-J authoring framework identified by
+//! `com/dbp/` package paths in a top-level `/BDMV/JAR/<x>.jar` (not in
+//! a subdir). Seen on UHD discs.
+//!
+//! 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. Observed format:
+//!
+//! ```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 parser ignores any prefix before the first `TextField,`
+//! occurrence — whatever string-pool ordering placed ahead of it is
+//! irrelevant. `Subtitle0` is the disable-subtitles menu button and is
+//! skipped (not a real subtitle stream).
+//!
+//! ## Implementation
+//!
+//! Iterates `CpInfo::Utf8` constant-pool entries rather than raw
+//! byte-scanning each class file. Equivalent label coverage (the literal
+//! `TextField,...` strings live in the CP as Utf8 entries) with no
+//! false-positive risk from method bytecode or attribute names that
+//! happen to contain `TextField,`. Language / purpose / qualifier
+//! classification lives in [`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)
+}
+
+/// Scan every top-level `/BDMV/JAR/*.jar` for the dbp framework and
+/// extract its stream labels. Returns `None` if no jar carries a
+/// `com/dbp/` package path or none yields any labels.
+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);
+    }
+}

src/labels/jar.rs

@@ -0,0 +1,302 @@
+//! 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.
+
+use super::class_reader::ClassFile;
+use crate::sector::SectorSource;
+use crate::udf::UdfFs;
+use std::io::{Cursor, Read};
+use zip::ZipArchive;
+
+/// Upper bound on bytes read out of a single `.class` entry. The jar's
+/// uncompressed-size field is attacker-controlled disc metadata, so the
+/// buffer is grown incrementally and the read is capped here rather than
+/// pre-sized from the declared size. A real BD-J `.class` is far under
+/// this ceiling (64 MiB); a lying header simply gets truncated and the
+/// class fails to parse, which is skipped like any other bad entry.
+const MAX_CLASS_BYTES: u64 = 64 * 1024 * 1024;
+
+/// 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: &Jar, prefix: &str) -> bool {
+    archive.file_names().any(|n| n.starts_with(prefix))
+}
+
+/// 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),
+{
+    // Defer to try_each_class; the callback always yields None so
+    // iteration never short-circuits.
+    try_each_class(archive, |name, class| {
+        f(name, class);
+        None::<()>
+    });
+}
+
+/// 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(entry) = archive.by_index(i) else {
+            continue;
+        };
+        if !entry.name().ends_with(".class") {
+            continue;
+        }
+        let name = entry.name().to_string();
+        // The declared uncompressed size is attacker-controlled, so the
+        // buffer grows incrementally and the read is capped at
+        // MAX_CLASS_BYTES rather than pre-sized from entry.size().
+        let mut bytes = Vec::new();
+        if entry.take(MAX_CLASS_BYTES).read_to_end(&mut bytes).is_err() {
+            continue;
+        }
+        let Ok(class) = ClassFile::parse(&bytes) else {
+            continue;
+        };
+        if let Some(r) = f(&name, &class) {
+            return Some(r);
+        }
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Smallest constant-pool-empty `.class`: magic, versions, cp_count=1
+    /// (zero real entries), then empty access/this/super/interfaces/
+    /// fields/methods/attributes.
+    const MINIMAL_CLASS: &[u8] = &[
+        0xCA, 0xFE, 0xBA, 0xBE, // magic
+        0x00, 0x00, // minor
+        0x00, 0x00, // major
+        0x00, 0x01, // constant_pool_count = 1 -> no entries
+        0x00, 0x00, // access_flags
+        0x00, 0x00, // this_class
+        0x00, 0x00, // super_class
+        0x00, 0x00, // interfaces_count
+        0x00, 0x00, // fields_count
+        0x00, 0x00, // methods_count
+        0x00, 0x00, // attributes_count
+    ];
+
+    /// Build a raw, single-entry, Stored (uncompressed) ZIP whose local
+    /// header and central directory both declare `declared_size` as the
+    /// uncompressed size, while the actual stored payload is `payload`.
+    /// This lets a test forge an attacker-controlled size field that does
+    /// not match the real data length.
+    fn build_stored_zip(name: &str, payload: &[u8], declared_size: u32) -> Vec<u8> {
+        let name_bytes = name.as_bytes();
+        let crc: u32 = {
+            // CRC-32 (IEEE) over payload.
+            let mut crc = 0xFFFF_FFFFu32;
+            for &b in payload {
+                crc ^= b as u32;
+                for _ in 0..8 {
+                    let mask = (crc & 1).wrapping_neg();
+                    crc = (crc >> 1) ^ (0xEDB8_8320 & mask);
+                }
+            }
+            !crc
+        };
+        let mut out = Vec::new();
+        // ----- Local file header -----
+        let lfh_offset = out.len() as u32;
+        out.extend_from_slice(&0x0403_4b50u32.to_le_bytes()); // signature
+        out.extend_from_slice(&20u16.to_le_bytes()); // version needed
+        out.extend_from_slice(&0u16.to_le_bytes()); // flags
+        out.extend_from_slice(&0u16.to_le_bytes()); // method = Stored
+        out.extend_from_slice(&0u16.to_le_bytes()); // mod time
+        out.extend_from_slice(&0u16.to_le_bytes()); // mod date
+        out.extend_from_slice(&crc.to_le_bytes()); // crc-32
+        out.extend_from_slice(&(payload.len() as u32).to_le_bytes()); // compressed size
+        out.extend_from_slice(&declared_size.to_le_bytes()); // uncompressed size (forged)
+        out.extend_from_slice(&(name_bytes.len() as u16).to_le_bytes());
+        out.extend_from_slice(&0u16.to_le_bytes()); // extra len
+        out.extend_from_slice(name_bytes);
+        out.extend_from_slice(payload);
+        // ----- Central directory header -----
+        let cd_offset = out.len() as u32;
+        out.extend_from_slice(&0x0201_4b50u32.to_le_bytes()); // signature
+        out.extend_from_slice(&20u16.to_le_bytes()); // version made by
+        out.extend_from_slice(&20u16.to_le_bytes()); // version needed
+        out.extend_from_slice(&0u16.to_le_bytes()); // flags
+        out.extend_from_slice(&0u16.to_le_bytes()); // method = Stored
+        out.extend_from_slice(&0u16.to_le_bytes()); // mod time
+        out.extend_from_slice(&0u16.to_le_bytes()); // mod date
+        out.extend_from_slice(&crc.to_le_bytes());
+        out.extend_from_slice(&(payload.len() as u32).to_le_bytes()); // compressed size
+        out.extend_from_slice(&declared_size.to_le_bytes()); // uncompressed size (forged)
+        out.extend_from_slice(&(name_bytes.len() as u16).to_le_bytes());
+        out.extend_from_slice(&0u16.to_le_bytes()); // extra len
+        out.extend_from_slice(&0u16.to_le_bytes()); // comment len
+        out.extend_from_slice(&0u16.to_le_bytes()); // disk number start
+        out.extend_from_slice(&0u16.to_le_bytes()); // internal attrs
+        out.extend_from_slice(&0u32.to_le_bytes()); // external attrs
+        out.extend_from_slice(&lfh_offset.to_le_bytes()); // local header offset
+        out.extend_from_slice(name_bytes);
+        let cd_size = out.len() as u32 - cd_offset;
+        // ----- End of central directory -----
+        out.extend_from_slice(&0x0605_4b50u32.to_le_bytes()); // signature
+        out.extend_from_slice(&0u16.to_le_bytes()); // disk number
+        out.extend_from_slice(&0u16.to_le_bytes()); // cd start disk
+        out.extend_from_slice(&1u16.to_le_bytes()); // entries on this disk
+        out.extend_from_slice(&1u16.to_le_bytes()); // total entries
+        out.extend_from_slice(&cd_size.to_le_bytes());
+        out.extend_from_slice(&cd_offset.to_le_bytes());
+        out.extend_from_slice(&0u16.to_le_bytes()); // comment len
+        out
+    }
+
+    fn open(bytes: Vec<u8>) -> Jar {
+        ZipArchive::new(Cursor::new(bytes)).expect("valid zip")
+    }
+
+    #[test]
+    fn try_each_class_reads_minimal_class() {
+        let mut jar = open(build_stored_zip(
+            "Foo.class",
+            MINIMAL_CLASS,
+            MINIMAL_CLASS.len() as u32,
+        ));
+        let mut seen = Vec::new();
+        let r: Option<()> = try_each_class(&mut jar, |name, _class| {
+            seen.push(name.to_string());
+            None
+        });
+        assert!(r.is_none());
+        assert_eq!(seen, vec!["Foo.class".to_string()]);
+    }
+
+    #[test]
+    fn for_each_class_visits_every_class() {
+        let mut jar = open(build_stored_zip(
+            "Bar.class",
+            MINIMAL_CLASS,
+            MINIMAL_CLASS.len() as u32,
+        ));
+        let mut count = 0usize;
+        for_each_class(&mut jar, |_, _| count += 1);
+        assert_eq!(count, 1);
+    }
+
+    /// The uncompressed-size field is attacker-controlled. A tiny stored
+    /// entry that declares 0xFFFF_FFFF (≈4 GiB) must NOT trigger a 4 GiB
+    /// pre-allocation; with the incremental read the call completes and
+    /// the real (small) payload parses fine.
+    #[test]
+    fn forged_huge_uncompressed_size_does_not_preallocate() {
+        let mut jar = open(build_stored_zip("Evil.class", MINIMAL_CLASS, 0xFFFF_FFFF));
+        let mut parsed = false;
+        for_each_class(&mut jar, |name, _class| {
+            assert_eq!(name, "Evil.class");
+            parsed = true;
+        });
+        // Reached here without OOM/abort, and the real bytes parsed.
+        assert!(parsed);
+    }
+
+    /// The read is bounded by MAX_CLASS_BYTES: a stored entry whose real
+    /// payload exceeds the cap yields only the first MAX_CLASS_BYTES
+    /// bytes to the parser, never the full (unbounded) entry. Verified
+    /// here on a small cap via the entry-count path: the truncated bytes
+    /// still parse a valid class prefix, but no read beyond the cap
+    /// occurs. We assert the entry is still surfaced exactly once (the
+    /// cap does not drop legitimate entries) and the call returns.
+    #[test]
+    fn read_is_bounded_by_cap() {
+        // Padding past MINIMAL_CLASS is harmless trailing data the parser
+        // ignores; the point is that read_to_end stops at the cap rather
+        // than following a (potentially huge) declared size.
+        let mut payload = MINIMAL_CLASS.to_vec();
+        payload.extend(std::iter::repeat(0u8).take(4096));
+        let mut jar = open(build_stored_zip(
+            "Padded.class",
+            &payload,
+            // Forge a size far larger than the real payload.
+            0xFFFF_FFFF,
+        ));
+        let mut visited = 0usize;
+        for_each_class(&mut jar, |_, _| visited += 1);
+        assert_eq!(visited, 1);
+    }
+}

src/labels/mpls_universal.rs

@@ -0,0 +1,624 @@
+//! 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<(StreamLabelType, 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 key = (label_type, 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.
+    //
+    // UDF names are decoded via from_utf8_lossy, so a multi-byte
+    // replacement char (EF BF BD) can straddle byte index n-5; a raw
+    // byte slice there panics on a non-char-boundary. `ends_with` on a
+    // lowercased copy is char-boundary-safe and still case-insensitive.
+    name.len() >= 5 && name.to_ascii_lowercase().ends_with(".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 HR", // BD-ROM Part 3-1: 0x85 = DTS-HD High Resolution
+        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
+}
+
+// ── 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<(StreamLabelType, String, String, u16)> = Vec::new();
+
+        // Global counters hoisted OUT of the playlist loop to match
+        // production `parse()` (lines 77-78): stream_numbers are dense
+        // per type across the whole disc, not reset per playlist.
+        let mut audio_idx: u16 = 0;
+        let mut sub_idx: u16 = 0;
+
+        for playlist in playlists {
+            for entry in &playlist.streams {
+                let label_type = match entry.stream_type {
+                    2 | 5 => StreamLabelType::Audio,
+                    3 => StreamLabelType::Subtitle,
+                    _ => continue,
+                };
+                // Dedup BEFORE consuming a counter value, matching prod
+                // parse() ordering so a deduped duplicate does not burn a
+                // stream number.
+                let language = normalize_language(&entry.language);
+                let name = language_display_name(&language);
+                let codec_hint = build_codec_hint(label_type, entry);
+                let key = (label_type, 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(),
+                });
+            }
+        }
+        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"]);
+
+        // Stream numbers must be DENSE and GLOBAL across playlists, not
+        // reset per playlist. eng (pl1) = 1, fra (pl1) = 2, the duplicate
+        // eng in pl2 is deduped (no number consumed), and deu (pl2) = 3.
+        // Regression guard for the per-playlist counter-reset divergence.
+        let num = |lang: &str| {
+            labels
+                .iter()
+                .find(|l| l.language == lang)
+                .map(|l| l.stream_number)
+        };
+        assert_eq!(num("eng"), Some(1));
+        assert_eq!(num("fra"), Some(2));
+        assert_eq!(num("deu"), Some(3));
+    }
+
+    #[test]
+    fn has_mpls_extension_handles_short_and_non_ascii_names() {
+        // Short names: no panic, just false.
+        assert!(!has_mpls_extension(""));
+        assert!(!has_mpls_extension("a"));
+        assert!(!has_mpls_extension(".mpl"));
+        // Exact-length and longer valid suffixes, case-insensitive.
+        assert!(has_mpls_extension("0.mpls"));
+        assert!(has_mpls_extension("00000.MPLS"));
+        assert!(has_mpls_extension("Movie.MpLs"));
+        // Non-matching suffix.
+        assert!(!has_mpls_extension("file.clpi"));
+        // Multi-byte char near the tail must NOT panic on a byte-slice
+        // boundary (from_utf8_lossy U+FFFD = EF BF BD is the real-disc
+        // case). A name ending in such a char is simply not ".mpls".
+        assert!(!has_mpls_extension("na\u{FFFD}me"));
+        // And a name where a multi-byte char sits exactly at the n-5
+        // boundary used by the old slice index.
+        assert!(!has_mpls_extension("ab\u{FFFD}cd"));
+        // A genuine .mpls preceded by a multi-byte char still matches.
+        assert!(has_mpls_extension("f\u{FFFD}.mpls"));
+    }
+
+    #[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 HR"),
+            (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");
+    }
+}

src/labels/paramount.rs

@@ -0,0 +1,240 @@
+//! Paramount/onQ — `playlists.xml`
+//!
+//! Richest structured format. Complete language lists with forced flags
+//! and commentary indices per playlist, all in XML attributes.
+//!
+//! ```xml
+//! <playlist name="Feature" id="00222"
+//!   aud="eng,deu,spa,spa,fra"
+//!   sub="eng,eng,zho,ces,dan"
+//!   forced_sub="0,0,0,1,0"
+//!   aud_com1_idx="10"
+//!   sub_com1_idx="23,24,25" />
+//! ```
+
+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 SectorSource, udf: &UdfFs) -> Option<ParseResult> {
+    let data = super::read_jar_file(reader, udf, "playlists.xml")?;
+    let text = std::str::from_utf8(&data).ok()?;
+
+    // Find the feature playlist — longest duration or name="Feature"
+    let feature = find_feature_playlist(text)?;
+
+    let labels = labels_from_feature(&feature);
+
+    if labels.is_empty() {
+        return None;
+    }
+    // High confidence: paramount's playlists.xml is fully structured
+    // and we extract every documented field.
+    Some(ParseResult::high(labels))
+}
+
+/// Build the stream labels from a single `<playlist .../>` feature
+/// element. Split out from `parse` so the per-type numbering and
+/// commentary/forced-index logic is unit-testable without a
+/// `SectorSource`/`UdfFs`.
+fn labels_from_feature(feature: &str) -> Vec<StreamLabel> {
+    let mut labels = Vec::new();
+
+    // Parse audio streams
+    if let Some(aud) = xml::attr(feature, "aud") {
+        // aud_com1_idx is a trimmed, comma-separated list of CSV positions
+        // (some authoring tools emit whitespace, and multiple commentary
+        // tracks are possible) — symmetric with sub_com1_idx below.
+        let com_indices: Vec<usize> = xml::attr(feature, "aud_com1_idx")
+            .map(|s| s.split(',').filter_map(|i| i.trim().parse().ok()).collect())
+            .unwrap_or_default();
+
+        // stream_number must match apply_labels' monotonic 1-based
+        // per-type counter, which increments once per *real* stream — so
+        // it counts only non-empty slots, not the raw CSV index. The
+        // commentary index comparison stays on the raw CSV index `i`,
+        // since aud_com1_idx is positional against the original CSV.
+        let mut audio_num: u16 = 0;
+        for (i, lang) in aud.split(',').enumerate() {
+            let lang = lang.trim();
+            if lang.is_empty() {
+                continue;
+            }
+            let purpose = if com_indices.contains(&i) {
+                LabelPurpose::Commentary
+            } else {
+                LabelPurpose::Normal
+            };
+            audio_num = audio_num.saturating_add(1);
+            labels.push(StreamLabel {
+                stream_number: audio_num,
+                stream_type: StreamLabelType::Audio,
+                language: lang.to_string(),
+                name: String::new(),
+                purpose,
+                qualifier: LabelQualifier::None,
+                codec_hint: String::new(),
+                variant: String::new(),
+            });
+        }
+    }
+
+    // Parse subtitle streams
+    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> = xml::attr(feature, "sub_com1_idx")
+            .map(|s| s.split(',').filter_map(|i| i.trim().parse().ok()).collect())
+            .unwrap_or_default();
+
+        // As with audio: count only non-empty slots for stream_number,
+        // but keep com/forced lookups on the raw CSV index `i`.
+        let mut sub_num: u16 = 0;
+        for (i, lang) in sub.split(',').enumerate() {
+            let lang = lang.trim();
+            if lang.is_empty() {
+                continue;
+            }
+
+            let purpose = if com_indices.contains(&i) {
+                LabelPurpose::Commentary
+            } else {
+                LabelPurpose::Normal
+            };
+
+            let qualifier = if forced.get(i).copied().unwrap_or(false) {
+                LabelQualifier::Forced
+            } else {
+                LabelQualifier::None
+            };
+
+            sub_num = sub_num.saturating_add(1);
+            labels.push(StreamLabel {
+                stream_number: sub_num,
+                stream_type: StreamLabelType::Subtitle,
+                language: lang.to_string(),
+                name: String::new(),
+                purpose,
+                qualifier,
+                codec_hint: String::new(),
+                variant: String::new(),
+            });
+        }
+    }
+
+    labels
+}
+
+/// Find the feature playlist element (the one with the most non-empty
+/// audio slots).
+fn find_feature_playlist(text: &str) -> Option<String> {
+    let mut best: Option<String> = None;
+    let mut best_aud_count = 0;
+    let mut from = 0;
+
+    while let Some((start, end)) = xml::find_element(text, "playlist", from) {
+        let element = &text[start..end];
+
+        // 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. Count only
+        // non-empty slots so a malformed `aud=",,,,,"` can't outscore a
+        // legitimate feature.
+        if let Some(aud) = xml::attr(element, "aud") {
+            let count = aud.split(',').filter(|s| !s.trim().is_empty()).count();
+            if count > best_aud_count {
+                best_aud_count = count;
+                best = Some(element.to_string());
+            }
+        }
+
+        from = end;
+    }
+    best
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn audio(labels: &[StreamLabel]) -> Vec<&StreamLabel> {
+        labels
+            .iter()
+            .filter(|l| l.stream_type == StreamLabelType::Audio)
+            .collect()
+    }
+
+    fn subs(labels: &[StreamLabel]) -> Vec<&StreamLabel> {
+        labels
+            .iter()
+            .filter(|l| l.stream_type == StreamLabelType::Subtitle)
+            .collect()
+    }
+
+    #[test]
+    fn empty_middle_slot_does_not_inflate_stream_number() {
+        // aud="eng,,fra": the empty middle slot is skipped, and the
+        // second real stream (fra) must be numbered 2, matching
+        // apply_labels' monotonic counter — not 3 (its raw CSV index).
+        let feature = r#"<playlist name="Feature" aud="eng,,fra" />"#;
+        let labels = labels_from_feature(feature);
+        let a = audio(&labels);
+        assert_eq!(a.len(), 2);
+        assert_eq!(a[0].language, "eng");
+        assert_eq!(a[0].stream_number, 1);
+        assert_eq!(a[1].language, "fra");
+        assert_eq!(a[1].stream_number, 2);
+    }
+
+    #[test]
+    fn aud_com1_idx_trimmed_and_multivalue() {
+        // Whitespace around the index, and a multi-value list, must both
+        // resolve. com index is positional against the raw CSV, so with
+        // an empty slot at position 1, " 2 " marks the 'fra' track
+        // (CSV index 2) as commentary.
+        let feature = r#"<playlist aud="eng,,fra" aud_com1_idx=" 2 " />"#;
+        let labels = labels_from_feature(feature);
+        let a = audio(&labels);
+        assert_eq!(a.len(), 2);
+        assert_eq!(a[1].language, "fra");
+        assert_eq!(a[1].purpose, LabelPurpose::Commentary);
+        assert_eq!(a[0].purpose, LabelPurpose::Normal);
+    }
+
+    #[test]
+    fn forced_sub_aligns_with_raw_csv_index() {
+        // sub="eng,eng,zho,ces" forced_sub="0,0,0,1": the forced flag is
+        // positional on the raw CSV, so 'ces' (index 3) is forced; its
+        // stream_number is its non-empty position (4 here, no gaps).
+        let feature = r#"<playlist sub="eng,eng,zho,ces" forced_sub="0,0,0,1" />"#;
+        let labels = labels_from_feature(feature);
+        let s = subs(&labels);
+        assert_eq!(s.len(), 4);
+        assert_eq!(s[3].language, "ces");
+        assert_eq!(s[3].qualifier, LabelQualifier::Forced);
+        assert_eq!(s[3].stream_number, 4);
+    }
+
+    #[test]
+    fn find_feature_skips_empty_audio_slot_playlist() {
+        // A playlist of all-empty audio slots must not outscore a real
+        // two-language feature.
+        let xml = r#"
+            <playlist name="Junk" aud=",,,,," />
+            <playlist name="Movie" aud="eng,fra" />
+        "#;
+        let feature = find_feature_playlist(xml).expect("a feature is found");
+        assert!(feature.contains(r#"name="Movie""#));
+    }
+}