aacs: full-ladder resolve_candidate + correct mk_from_dk

resolve_candidate(candidate, mkb, unit_key_ro, vid) -> ResolvedChain: one
composed, PURE-DERIVATION boil-down for a candidate key at any ladder rung
(KeyCandidate::{Uk,Vuk,Mk,Pk,Dk}, each carrying the module's newtype). Walks
DK/PK/MK/VUK -> terminal unit keys, parsing Unit_Key_RO.inf at the version
the disc's MKB declares, and returns every CPS unit key as (cps_unit, key)
(matching ResolvedKeys) plus the intermediate chain. No sampling/validation
(that's the caller's unit_key_validates) and no position recovery (Dk is a
positioned DeviceKey; recover_dk_position first). Adds ProcessingKey newtype.
Consumers stop re-composing the ladder; every client hardens one impl.

Correct mk_from_dk: real Subset-Difference walk (derive_media_key_and_pk_from_dk)
instead of the Media-Key-Variant path, which needed integrator KCD absent
in-tree and Err'd for every real disc -- dead for both consumers. Drops the
now-unused vid arg.

.github/workflows/ci.yml

@@ -13,6 +13,7 @@ jobs:
       - uses: dtolnay/rust-toolchain@1.86.0
         with:
           components: clippy, rustfmt
+      - uses: Swatinem/rust-cache@v2
       - 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
@@ -25,6 +26,7 @@ jobs:
     steps:
       - uses: actions/checkout@v5
       - uses: dtolnay/rust-toolchain@1.86.0
+      - uses: Swatinem/rust-cache@v2
       - run: cargo test --tests
 
   check-macos:
@@ -32,6 +34,7 @@ jobs:
     steps:
       - uses: actions/checkout@v5
       - uses: dtolnay/rust-toolchain@1.86.0
+      - uses: Swatinem/rust-cache@v2
       - run: cargo check
 
   check-windows:
@@ -39,4 +42,10 @@ jobs:
     steps:
       - uses: actions/checkout@v5
       - uses: dtolnay/rust-toolchain@1.86.0
-      - run: cargo check
+      - uses: Swatinem/rust-cache@v2
+      # Build the tests (not just `cargo check`): catches errors in test
+      # code and forces full codegen of the Windows-only SPTI transport
+      # (src/scsi/windows.rs), which never compiles on the Linux/macOS dev
+      # hosts. We don't `cargo test` here — the suite needs no drive but the
+      # extra build is the value; running tests is covered by the Linux job.
+      - run: cargo build --tests

.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

@@ -22,29 +22,51 @@ jobs:
           fi
           echo "Version match: $CARGO_VER"
 
+  # Tests run as a PARALLEL TRIPWIRE: they fail the run if they fail, but the
+  # publish/release jobs do NOT `needs:` this job. The tag decision was already
+  # gated by the local precommit (same Rust 1.86, same commit). Binary consumers
+  # (freemkv/autorip/bdemu) git-tag-pin libfreemkv and therefore start building
+  # the instant this tag exists — so this test job and the crates.io publish
+  # below must NOT sit on their critical path.
   test:
     needs: verify
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
       - uses: dtolnay/rust-toolchain@1.86.0
+      - uses: Swatinem/rust-cache@v2
       # 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
 
+  # crates.io publish is an INDEPENDENT job: it serves EXTERNAL consumers only.
+  # The freemkv binaries no longer depend on it (they git-tag-pin libfreemkv via
+  # a committed [patch.crates-io]), so this publish runs in parallel with their
+  # release builds rather than gating them. It `needs: [verify, test]` so a
+  # failing test suite still blocks publication to crates.io — external
+  # consumers who `cargo add libfreemkv` must never receive a release whose
+  # tests were failing. (The two upstream jobs run in parallel, so this gate
+  # does not serialize publish behind test beyond their own completion.)
   publish:
-    needs: test
+    needs: [verify, test]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
       - uses: dtolnay/rust-toolchain@1.86.0
+      - uses: Swatinem/rust-cache@v2
+      # --no-verify: CI already compiled this exact commit (in the `test` job
+      # and on every push via ci.yml). cargo publish's default re-verify does a
+      # full cold release build of the packaged tarball, which here is pure
+      # redundant work (~a cold lib build). Skip it.
       - name: Publish to crates.io
-        run: cargo publish
+        run: cargo publish --no-verify
         env:
           CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
 
   release:
-    needs: test
+    # Only needs `verify`; the GitHub Release can be cut as soon as the version
+    # check passes, in parallel with test + publish.
+    needs: verify
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5

.gitignore

@@ -4,4 +4,13 @@ Cargo.lock
 *.swo
 .DS_Store
 .cargo/
-.claude/worktrees/
+
+# 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/

CLAUDE.md

@@ -1,94 +0,0 @@
-# libfreemkv — Rules
-
-## No English in library code
-
-The library contains ZERO user-facing English text. All errors use numeric codes from `error.rs`. Applications (CLI, GUI, server) handle i18n.
-
-- `io::Error::new(kind, "english string")` — NEVER. Use `Error::VariantName.into()`.
-- If you need a new error, add a variant to `error.rs` with a code, not a string.
-- Acceptable strings: debug/trace logging, test assertions, comments, data format strings (paths, codec IDs).
-- `Error` implements `From<Error> for io::Error` — use `?` or `.into()` anywhere an `io::Error` is expected.
-
-## Architecture
-
-- **Streams are PES.** Every stream reads its format → PES frames out, or PES frames in → writes its format. One type per format.
-- **Disc::copy() for sector dumps.** disc→ISO is NOT a stream. It's `Disc::copy()`.
-- **DiscStream = any disc.** Physical drive or ISO file. Same type, different SectorReader.
-- **No IOStream.** Deleted. No byte-level Read/Write on streams.
-- **Streams don't know their size.** Progress/file_size is a CLI concern.
-- **One method per action.** No `foo_with_X` variants. Use `Option<T>` params.
-- **Streams impl Read only (conceptually).** No Seek, no File backing.
-- **Functions return errors, only main() exits.** No `process::exit` in library code.
-
-## Device rules
-
-- Always use `/dev/sg*` not `/dev/sr*` for SCSI.
-- `--raw` only skips decryption. Init/probe/speed still run.
-- Each function does one thing. One runner orchestrates the sequence.
-
-## AACS key sources
-
-Single source: `keydb.cfg`. Located at `~/.config/freemkv/keydb.cfg` by
-default, or pointed at via `ScanOptions::keydb_path`. The file holds
-all DKs, PKs, host certs, and per-disc VUK entries. No keys are
-compiled into the binary.
-
-CSS player keys (DVD) remain compiled in — they're 1999-era public
-inputs separate from the AACS key pipeline and have always lived in
-`src/css/auth.rs`.
-
-The library treats a missing `keydb.cfg` for an AACS-encrypted disc as
-`Error::KeydbLoad` with the sentinel path `<no keydb in search paths>`.
-CLIs render this as "no KEYDB.cfg found"; consumers can disambiguate
-on the sentinel string.
-
-## macOS IOKit transport
-
-The macOS SCSI transport uses exclusive IOKit access, not hybrid MMC+pread.
-
-- **C shim** (`src/scsi/macos_shim.c`):
-  - `shim_open_exclusive(bsd_name)`: `diskutil unmountDisk force` on target device only → find `IOBDServices` matching BSD name via IOKit registry walk → MMCDeviceInterface → SCSITaskDeviceInterface → `ObtainExclusiveAccess` → raw CDB dispatch.
-  - `shim_list_drives()`: registry-based enumeration. Walks all `IOBDServices` entries, reads `"Device Characteristics"` for vendor/model/firmware, walks child chain to `IOMedia` for BSD name. Zero SCSI, zero exclusive access, zero unmounts.
-  - `shim_execute()` / `shim_close()`: raw CDB dispatch and cleanup.
-- **Build** (`build.rs`): compiles shim via `cc` into static lib, linked by Cargo. NOT the `cc` crate (produces object code that breaks IOKit exclusive access).
-- **Rust** (`src/scsi/macos.rs`): FFI to `shim_open_exclusive`, `shim_close`, `shim_execute`, `shim_list_drives`. `list_drives()` uses registry-based enumeration. `MacScsiTransport::open()` uses exclusive access only when ripping a specific device.
-- **IOBDServices parent chain**: IOSCSIPeripheralDeviceType05 → IOBDServices → IOBDBlockStorageDriver → IOMedia (has `"BSD Name"`). The shim walks this chain to match BSD name to IOBDServices.
-- **IOKit lookup order**: (1) iterate all IOBDServices → match child IOMedia BSD name, (2) fallback: find IOMedia by BSD name → walk parent chain to IOBDServices, (3) fallback: first IOBDServices (single-drive systems).
-- **Test disc**: DUNE_PART_TWO UHD, `/dev/disk6`, ~84.6 GB.
-
-## Bad-sector handling (BU40N + Initio INIC-1618L)
-
-Three failure modes on this USB bridge:
-1. **NOT READY** (sense_key=2, ASC=0x04, ASCQ=0x3E) — most common on BU40N for bad sectors. Pause 3s, retry up to 3x, then mark NonTrimmed.
-2. **Transport failure** (status=0xFF) — bridge crash, auto-recovers ~15s. Aborts copy.
-3. **INCOMPATIBLE FORMAT** (ASC=0x30) wedge — ALL sectors fail, requires power cycle.
-
-### Damage-jump algorithm (Pass 1 sweep)
-
-When `skip_on_error=true` (multipass mode):
-- Read each ECC block sequentially. Track a sliding window of the last 16 ECC block results.
-- On error: zero-fill, mark NonTrimmed, push `false` to window.
-- On success: write data, mark Finished, push `true` to window. Track consecutive good count.
-- When ≥12% of the 16-block window are failures → **jump** ahead by `JUMP_BASE_SECTORS (1024) × batch × multiplier` sectors. For UHD encrypted ECC (batch=32) that's a 64 MiB base jump. Zero-fill the gap as NonTrimmed. Double the multiplier (64→128→256→512 MiB...) up to `MAX_JUMP_MULTIPLIER=64` (4 GiB cap). Plus a separate wedge-skip path of `WEDGE_JUMP_SECTORS=524288` (1 GiB) for HARDWARE_ERROR / ILLEGAL_REQUEST senses, capped at 16 consecutive wedges.
-- When 16 consecutive good reads → reset multiplier to 1, restore max read speed.
-- Only transport failures (bridge crash) abort the pass.
-
-Tuning knobs: `DAMAGE_WINDOW=16` and `DAMAGE_THRESHOLD_PCT=12%`. Calibrated from live BU40N data: old 50/25% was too diluted by good reads between sparse failures; 16/12% triggers on the 2nd scattered failure (2/16 = 12.5% ≥ 12%).
-
-### Patch (Pass N) — `disc/mod.rs:1910`
-
-- Default: **reverse** mode. Walks bad ranges from highest LBA to lowest, and within each range from end to start. Rationale: sweep jumps forward with escalating gaps, so NonTrimmed ranges have good data at their tail (where the jump landed). Reverse hits good data first, converges on actual bad block boundaries.
-- Single-sector reads with 60 s timeout (`READ_RECOVERY_TIMEOUT_MS`).
-- NOT_READY (sense=2, ASC ∈ {0x02, 0x03, 0x04}): 15 s pause, retry without immediate Unreadable mark.
-- Non-marginal SCSI sense → mark Unreadable and continue.
-- Skip escalation: damage window 16, `PASSN_DAMAGE_THRESHOLD_PCT=6`, skip `PASSN_SKIP_SECTORS_BASE (32) << escalation` sectors capped at `PASSN_SKIP_SECTORS_CAP=4096`; `MAX_SKIPS_PER_RANGE=10`, then mark range Unreadable.
-- Wedge exit: 50 consecutive failures **and** ≥ 2 ranges attempted (single-range stalls don't kill the pass).
-- Whole-pass watchdog: `STALL_SECS = 3600` on `bytes_good`. Per-range watchdog: proportional `range_sectors × SECONDS_PER_SECTOR(25)`, capped at `RANGE_BUDGET_CAP_SECS=1800` (replaces the old flat 180s/range — tiny ranges got starved).
-
-Constants live in `disc/patch.rs::Disc::patch` (PASSN_*, STALL_SECS, SECONDS_PER_SECTOR, RANGE_BUDGET_CAP_SECS, MAX_SKIPS_PER_RANGE). The full algorithm is documented in `freemkv-private/memory/project_recovery_v0_16.md`.
-
-## Public repo rules
-
-- **No internal docs.** Audit reports, test plans, roadmaps, TODOs go in freemkv-private, never here.
-- **No Co-Authored-By** in commit messages. One contributor: MattJackson.
-- **No private references.** No Gitea URLs, no /data/code paths, no internal IPs in code.

CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at matthew@pq.io. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "libfreemkv"
-version = "0.26.0"
+version = "1.2.1"
 edition = "2024"
 rust-version = "1.86"
 license = "AGPL-3.0-only"
@@ -8,6 +8,15 @@ 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"]
+# OFF crates.io: libfreemkv git-deps freemkv-unlock (firmware, never published),
+# so libfreemkv itself can only be consumed by git tag. Clients git-tag-pin it.
+publish = false
+
+[profile.release]
+lto = "thin"
+codegen-units = 1
 
 [dependencies]
 serde = { version = "1", features = ["derive"] }
@@ -16,7 +25,10 @@ sha1 = "0.10"
 sha2 = "0.10"
 aes = "0.8"
 cbc = "0.1"
-flate2 = "1"
+# Interim path dep for local cross-repo dev; the release script re-pins this to
+# `{ git = ".../freemkv-unlock", tag = "vX.Y.Z" }` before tagging libfreemkv (so
+# the released tag resolves freemkv-unlock from git, not a sibling path).
+freemkv-unlock = { path = "../freemkv-unlock" }
 num-bigint = "0.4"
 num-traits = "0.2"
 num-integer = "0.1"
@@ -31,8 +43,7 @@ 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 (see freemkv-private/memory/
-# feedback_send_with_halt_poll_throttle.md, 0.21.7).
+# 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

Makefile

@@ -1,6 +1,5 @@
 # libfreemkv — local dev helper.
-# Mirrors the cross-crate scripts in freemkv-private/scripts/test-all.sh
-# but scoped to this single crate.
+# Mirrors the workspace-wide CI checks but scoped to this single crate.
 
 .PHONY: test build check ci clean
 

README.md

@@ -1,26 +1,26 @@
-[![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)
 
 # libfreemkv
 
-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.
+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. Drive-level unlocking is handled internally; consumers work with disc access and decryption only.
 
-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.
+DVDs (CSS) decrypt out of the box. Blu-ray and UHD (AACS) require a `keydb.cfg` (default `~/.config/freemkv/keydb.cfg`) supplying disc-specific volume unique keys; no AACS key material is compiled in.
 
-**12+ MB/s** sustained read speeds on BD. Full init: unlock, firmware upload, speed calibration — all from pure Rust.
+**12+ MB/s** sustained read speeds on BD. Drive prep (`init()`) handles unlocking internally via the `freemkv-unlock` crate — clients never see it; when no drive unlock applies, the library rips via the host-certificate AACS handshake.
 
 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/)**
+**[Source & API](https://github.com/freemkv/libfreemkv)** · **[Technical Docs](docs/)**
 
 Part of the [freemkv](https://github.com/freemkv) project.
 
 ## Install
 
+Consumed by git tag (not published to crates.io):
+
 ```toml
 [dependencies]
-libfreemkv = "0.25"
+libfreemkv = { git = "https://github.com/freemkv/libfreemkv", tag = "vX.Y.Z" }
 ```
 
 ## Quick Start
@@ -29,10 +29,10 @@ libfreemkv = "0.25"
 use libfreemkv::{Drive, Disc, ScanOptions};
 use std::path::Path;
 
-// Open drive — profiles are bundled, auto-identified
+// Open drive — identified via INQUIRY
 let mut drive = Drive::open(Path::new("/dev/sg4"))?;
 drive.wait_ready()?;              // wait for disc
-drive.init()?;                     // unlock + firmware upload
+drive.init()?;                     // unlock + prep (handled internally)
 drive.probe_disc()?;               // probe disc surface for optimal speeds
 
 // Scan disc — UDF, playlists, streams, AACS (all automatic)
@@ -100,7 +100,7 @@ loop {
 
 ## What It Does
 
-- **Drive access** — open, identify, unlock, firmware upload, speed calibration, eject
+- **Drive access** — open, identify, internal unlock + prep, speed control, 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)
@@ -121,21 +121,21 @@ loop {
 | 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.
+Streams implement a single unified `pes::Stream` trait (re-exported as `PesStream`) exposing `read()` and `write()` on one type. `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.
+DVDs (CSS) decrypt out of the box, with no external key file needed.
 
-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.
+Blu-rays and UHD (AACS) require a `keydb.cfg` at `~/.config/freemkv/keydb.cfg` (or passed via `ScanOptions`). No AACS key material is compiled into the binary.
 
 ## Architecture
 
 ```text
-Drive                  — open, identify, init, unlock, single-shot read
+Drive                  — open, identify, init, single-shot read
   ├── ScsiTransport    — SG_IO (Linux), IOKit (macOS), SPTI (Windows)
-  ├── DriveProfile     — per-drive unlock parameters (bundled)
-  └── PlatformDriver   — MediaTek (supported), Renesas (planned)
+  └── unlock_bridge    — private seam to the freemkv-unlock crate
+                         (firmware / AACS cert / CSS bus-auth unlockers)
 
 Disc                   — scan titles, streams, AACS/CSS state
   ├── UDF reader       — Blu-ray UDF 2.50 with metadata partitions
@@ -144,12 +144,11 @@ Disc                   — scan titles, streams, AACS/CSS state
   ├── 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)
+  ├── CSS              — DVD CSS (bus auth → player-key disc crack → known-plaintext title-key attack)
   └── KEYDB            — download + verify + save
 
 Streams                — unified PES pipeline
-  ├── FrameSource      — read() PES frames (direction-typed)
-  ├── FrameSink        — write() PES frames (direction-typed)
+  ├── PesStream        — pes::Stream: one trait, read()/write() PES frames
   ├── DiscStream       — sectors → decrypt → TS demux → PES
   ├── IsoStream        — ISO file → decrypt → TS demux → PES
   ├── MkvStream        — MKV mux/demux
@@ -175,6 +174,7 @@ All errors are structured with numeric codes. No user-facing English text — ap
 | E6xxx | Disc format errors |
 | E7xxx | AACS errors |
 | E8xxx | KEYDB update errors |
+| E9xxx | Stream / mux errors (URL, PES, ISO, pipeline, demux) |
 
 ## Platform Support
 
@@ -186,7 +186,7 @@ All errors are structured with numeric codes. No user-facing English text — ap
 
 ## Contributing
 
-Run `freemkv info disc:// --share` with the [freemkv CLI](https://github.com/freemkv/freemkv) to contribute your drive's profile.
+Run `freemkv info disc:// --share` with the [freemkv CLI](https://github.com/freemkv/freemkv) to capture your drive's identity for contribution. Drive-unlock profiles are maintained in the [freemkv-unlock](https://github.com/freemkv/freemkv-unlock) repository.
 
 ## License
 

build.rs

@@ -1,4 +1,6 @@
 fn main() {
+    emit_git_suffix();
+
     let target = std::env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
     if target == "macos" {
         println!("cargo:rustc-link-lib=framework=IOKit");
@@ -8,8 +10,22 @@ fn main() {
         let obj = format!("{out_dir}/macos_shim.o");
         let lib = format!("{out_dir}/libmacos_scsi.a");
 
+        // Build the shim for the TARGET arch, not the host's. A bare `cc` on an
+        // Apple-Silicon CI runner defaults to arm64, so cross-building to
+        // x86_64-apple-darwin would link a host-arch object against x86_64 Rust
+        // code → "Undefined symbols for architecture x86_64". (Still raw `cc`,
+        // not the `cc` crate, which breaks IOKit exclusive access.)
+        let target_arch = std::env::var("CARGO_CFG_TARGET_ARCH").unwrap_or_default();
+        let clang_arch: &str = if target_arch == "aarch64" {
+            "arm64"
+        } else {
+            &target_arch // x86_64 → x86_64
+        };
+
         std::process::Command::new("cc")
             .args([
+                "-arch",
+                clang_arch,
                 "-c",
                 "src/scsi/macos_shim.c",
                 "-o",
@@ -34,3 +50,48 @@ fn main() {
         println!("cargo:rerun-if-changed=src/scsi/macos_shim.c");
     }
 }
+
+/// Bake the git short hash into the build as `GIT_SUFFIX` so any muxed MKV or
+/// FVI index is traceable to the exact source revision (e.g. ` (g835cc99)`).
+/// Empty when git or the repo is unavailable (e.g. a crates.io tarball build),
+/// leaving just the package version. Always emitted so `env!("GIT_SUFFIX")`
+/// resolves on every target.
+fn emit_git_suffix() {
+    // Version label for the muxing-app / FVI generator tag. `FREEMKV_BUILD_LABEL`
+    // overrides the Cargo package version when set (non-empty) — used to stamp a
+    // pre-release/test build without bumping Cargo.toml and disturbing the
+    // tag-pinned [patch] version matching. Unset → the package version.
+    let version = std::env::var("FREEMKV_BUILD_LABEL")
+        .ok()
+        .filter(|s| !s.trim().is_empty())
+        .or_else(|| std::env::var("CARGO_PKG_VERSION").ok())
+        .unwrap_or_default();
+    println!("cargo:rustc-env=FREEMKV_VERSION={version}");
+    println!("cargo:rerun-if-env-changed=FREEMKV_BUILD_LABEL");
+
+    let suffix = git_short_hash()
+        .map(|h| format!(" (g{h})"))
+        .unwrap_or_default();
+    println!("cargo:rustc-env=GIT_SUFFIX={suffix}");
+
+    // Re-run when HEAD (or the branch it points at) moves so the stamp stays
+    // current without a clean rebuild.
+    println!("cargo:rerun-if-changed=.git/HEAD");
+    if let Ok(head) = std::fs::read_to_string(".git/HEAD") {
+        if let Some(ref_path) = head.strip_prefix("ref: ") {
+            println!("cargo:rerun-if-changed=.git/{}", ref_path.trim());
+        }
+    }
+}
+
+fn git_short_hash() -> Option<String> {
+    let out = std::process::Command::new("git")
+        .args(["rev-parse", "--short=7", "HEAD"])
+        .output()
+        .ok()?;
+    if !out.status.success() {
+        return None;
+    }
+    let h = String::from_utf8(out.stdout).ok()?.trim().to_string();
+    if h.is_empty() { None } else { Some(h) }
+}

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/FVI_FORMAT.md

@@ -0,0 +1,302 @@
+# FVI — Freemkv Video Index Format
+
+**Specification version:** 1.0 (DRAFT)\
+**File extension:** `.fvi`\
+**Media type:** `application/vnd.freemkv.fvi+jsonl`\
+**Status:** Draft for review. This document is the normative reference for the FVI
+format; implementations and downstream tools cite it by section.
+
+---
+
+## 1. Scope and purpose
+
+FVI is an open, codec-agnostic, byte-exact **index of the coded pictures** in a
+video bitstream, together with **provenance** back to the source medium.
+
+An FVI document answers, for every picture in a stream, three questions:
+
+1. **Where is it?** — the byte-exact offset of its first byte in the *source*
+   (the disc/ISO/file), so a reader can extract or seek to any picture without
+   re-parsing the whole bitstream.
+2. **What is it?** — coding type, random-access capability, GOP boundary, and
+   (where the codec defines them) field/pulldown attributes.
+3. **When is it?** — decode and presentation timestamps on a declared timescale.
+
+FVI is **not** a container, a codec, or a copy of the bitstream. It indexes; it
+never stores coded samples. It is the serialized form of an indexer's per-picture
+truth — carried from the demuxer, **never reconstructed** (§9).
+
+## 2. Conformance
+
+The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**,
+**SHOULD**, **SHOULD NOT**, **MAY**, and **OPTIONAL** are to be interpreted as
+described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all
+capitals.
+
+A **conformant writer** MUST emit a document that satisfies §4–§10. A
+**conformant reader** MUST accept any such document and MUST ignore unknown
+object members (§11) so that forward-compatible extensions do not break it.
+
+## 3. Terminology
+
+- **Picture** — one coded video frame (or pair of fields coded as a frame). The
+  unit FVI indexes.
+- **Access unit (AU)** — the set of bitstream bytes that decode to exactly one
+  picture (ISO/IEC 14496-10 §3; ISO/IEC 23008-2 §3).
+- **Coded order** — the order pictures appear in the bitstream. FVI records are
+  emitted in coded order.
+- **GOP / coded video sequence** — a self-contained run beginning at a
+  random-access point.
+- **Provenance** — the mapping from an AU back to the exact bytes of the physical
+  source it was read from (§9).
+- **Source position (`src`)** — `{ file, sector, byte }`, the provenance anchor of
+  an AU.
+
+## 4. Encoding
+
+An FVI document is a sequence of **UTF-8** text lines separated by a single LF
+(`U+000A`). Each non-empty line is exactly one JSON value (RFC 8259), forming a
+**JSON Lines / NDJSON** stream. A writer MUST NOT emit a UTF-8 BOM. A writer MUST
+NOT pretty-print: each JSON value occupies exactly one line.
+
+The first line MUST be the **Header** object (§6). Each subsequent line is one
+**Picture record** (§7), in coded order.
+
+Rationale: line-delimited JSON is streamable (a writer appends as it indexes; a
+reader processes without loading the whole file), line-addressable (picture *n*
+is near line *n+1*), append-safe, and parseable by every language without a
+custom grammar — while remaining a precisely specified format, not an ad-hoc dump.
+
+A document MAY be concatenated for multiple elementary streams: each stream is its
+own header line followed by its records. Readers MUST treat a Header line as the
+start of a new stream section.
+
+## 5. Document structure
+
+```
+<header>            line 1            (exactly one Header object)
+<record>            line 2 .. N       (one Picture record per picture, coded order)
+[<header> <record>…]                  (OPTIONAL further stream sections)
+```
+
+## 6. Header object
+
+| Member | JSON type | Req | Semantics / reference |
+|---|---|---|---|
+| `format` | string | MUST | Constant `"freemkv/video-index"`. Signature: a document begins with these bytes. |
+| `fvi_version` | integer | MUST | Document format version. This spec defines `1`. |
+| `generator` | string | SHOULD | Producing tool + version, e.g. `"freemkv/1.0.0-rc.6"`. |
+| `stream` | object | MUST | The indexed elementary stream (§6.1). |
+| `source` | object | MUST | Provenance root (§6.2). |
+| `timescale` | integer | MUST | Ticks per second for all `pts`/`dts` (§10). E.g. `90000`. |
+| `picture_count` | integer | MAY | Total pictures, if known at header time; OMITTED when streaming. |
+
+### 6.1 `stream` object
+
+| Member | JSON type | Req | Semantics / reference |
+|---|---|---|---|
+| `codec` | string | MUST | Registered codec id (Appendix B), e.g. `"mpeg2video"`, `"hevc"`. |
+| `width`,`height` | integer | MUST | Coded luma dimensions in pixels. |
+| `dar` | `[int,int]` | SHOULD | Display aspect ratio as `[num,den]`. |
+| `frame_rate` | `[int,int]` | SHOULD | Nominal rate as exact rational `[num,den]` (e.g. `[24000,1001]`). |
+| `scan` | string | MUST | `"progressive"`<br>`"interlaced"`<br>`"mbaff"` |
+| `colour` | object | SHOULD | CICP per ITU-T H.273: `primaries`, `transfer`, `matrix` (integer CICP codes or registered names)<br>`range`: `"limited"` \| `"full"`<br>HDR: `mastering_display`, `max_cll`, `max_fall` per ITU-T H.273 / SMPTE ST 2086. |
+| `language` | string | MAY | BCP 47 tag, if known. |
+
+### 6.2 `source` object
+
+| Member | JSON type | Req | Semantics / reference |
+|---|---|---|---|
+| `medium` | string | MUST | `"disc"`<br>`"iso"`<br>`"file"`<br>`"stream"` |
+| `path` | string | MAY | Source path/label. |
+| `title` | integer | MAY | Title/program number. |
+| `playlist` | string | MAY | Playlist/PGC identifier. |
+| `volume_id` | string | MAY | Disc volume identifier, if read. |
+| `sector_size` | integer | SHOULD | Bytes per `src.sector` unit (e.g. `2048`). Lets readers convert `src` to an absolute byte offset. |
+
+## 7. Picture record
+
+One JSON object per coded picture, in coded order.
+
+| Member | JSON type | Req | Semantics / reference |
+|---|---|---|---|
+| `n` | integer | MUST | Coded-order index, 0-based, contiguous. |
+| `src` | object | MUST | Provenance: `{ "file": int?, "sector": uint, "byte": uint }` — the offset of this AU's **first byte** in the source (§9). MUST be carried from demux, never reconstructed. |
+| `type` | string | MUST | Coding type:<br>`"I"`<br>`"P"`<br>`"B"`<br>_ISO/IEC 13818-2 §6.3.9; H.264/H.265 slice types collapsed to frame type._ |
+| `key` | boolean | MUST | `true` iff this picture is an intra (I) picture / parser-flagged decode-restart point (IDR / IRAP / I-picture).<br>_MPEG-2 open-GOP clean-RAP precision (`closed_gop`) is not currently distinguished — see note below._ |
+| `gop` | boolean | SHOULD | `true` iff this picture begins a GOP / coded video sequence.<br>_Omitted when the implementation does not carry a distinct GOP-boundary signal._ |
+| `pts` | integer\|null | SHOULD | Presentation timestamp in `timescale` ticks; `null` if unknown. |
+| `dts` | integer\|null | MAY | Decode timestamp in `timescale` ticks. |
+| `size` | integer | MAY | AU length in bytes; enables byte-range extraction with `src`. |
+| `recovered` | boolean | MAY | `true` iff any byte of this AU came from a retried/marginal read (§9.1).<br>_Default `false`._ |
+| codec ext | object | MAY | Codec-specific members under the codec's namespace (§8). |
+
+The `type` and `key` members are **codec-agnostic** and MUST be populated for
+every codec. `type` is the I/P/B coding type the parser decoded (collapsing
+H.264/H.265 slice types to a frame type); where no per-picture coding is carried
+(audio / synthetic frames), `type` is `"I"` for a key picture else `"P"`. `key`
+is the picture's random-access flag as the codec parser sets it (IDR / IRAP /
+I-picture). A writer MUST NOT emit a degraded record (`type:"?"` or `src:null`)
+merely because a codec lacks per-picture coding info — those fallbacks are
+reserved for a field that is genuinely unavailable (e.g. provenance absent on a
+synthetic source).
+
+> **Limitation (honest random-access).** `key` is set from the picture's
+> intra / decode-restart flag. The per-picture coding model this index carries
+> does **not** distinguish MPEG-2 open-GOP clean random-access points
+> (`closed_gop`) from any other I-picture, so `key` is the parser-flagged
+> decode-restart point, not a verified clean-RAP claim. A future revision MAY
+> tighten `key` for codecs/profiles that carry that signal; readers MUST NOT
+> assume present `key` precision beyond "intra / decode-restart point".
+
+### 7.1 Interlace / pulldown fields
+
+Codec-agnostic interlace/pulldown attributes, derived through the indexer's
+per-picture coding accessors (MPEG-2: ISO/IEC 13818-2 §6.3.10). Emitted as
+top-level members of the record, and ONLY when the codec actually measured the
+signal — an OPTIONAL member that is omitted (not defaulted) when unknown:
+
+| Member | JSON type | Req | Semantics / reference |
+|---|---|---|---|
+| `field_order` | string | MAY | Display field order:<br>`"tff"` — top field first<br>`"bff"` — bottom field first<br>`"progressive"` — no field order applies<br>_Omitted when the codec did not signal it._ |
+| `progressive` | boolean | MAY | `true` iff the picture is progressive.<br>_Omitted when the codec did not signal it._ |
+| `nb_fields` | integer | MAY | Number of displayed field periods this picture occupies (the soft-telecine / 2:3 pulldown basis):<br>`1` for a single field picture<br>`2` for a normal frame<br>`3`/`4`/`6` for `repeat_first_field` pulldown per §6.3.10 |
+
+Codecs that carry only a coding type (e.g. H.264 / HEVC / VC-1 through this
+pipeline) omit `field_order` and `progressive` rather than guessing a default.
+
+## 8. Codec model and extensibility
+
+Core record members (§7) are codec-agnostic and present for every codec.
+Codec-specific data is either (a) promoted to top-level members for a small,
+registered set per codec profile (e.g. MPEG-2 §7.1), or (b) placed under an
+`ext` object keyed by codec id for richer/optional data:
+
+```json
+{
+  "n": 42,
+  "type": "P",
+  "key": false,
+  "src": {
+    "sector": 17,
+    "byte": 924
+  },
+  "ext": {
+    "hevc": {
+      "temporal_id": 0,
+      "nal_type": 1
+    }
+  }
+}
+```
+
+New codecs and members are added through Appendix B (codec registry) without a
+breaking version bump, provided readers continue to ignore unknown members (§11).
+
+## 9. Provenance and recovery semantics
+
+`src` is **byte-exact** to the source as read. `src.sector` counts in
+`source.sector_size`-byte units; `src.byte` is the offset within that sector of
+the AU's first byte. For multi-file sources, `src.file` indexes a writer-declared
+file list. Provenance MUST be the value observed at demux time; an implementation
+MUST NOT recompute `src` by re-parsing — the point of FVI is to *carry* the truth.
+
+### 9.1 Recovery
+
+Because FVI is provenance-native, it can record reliability. A record with
+`"recovered":true` indicates the AU's source bytes required retry/marginal-read
+recovery. This lets downstream tools surface or quarantine pictures whose bytes
+are not byte-identical to a clean read — a capability legacy index formats lack.
+
+## 10. Time model
+
+All `pts`/`dts` are integers in units of `1/timescale` seconds. `pts` is
+presentation (display) time; `dts` is decode time. Records are in **coded**
+(decode) order, so `pts` is not necessarily monotonic across records (B-pictures
+reorder); `dts` is non-decreasing. Readers needing display order sort by `pts`.
+
+## 11. Versioning and forward compatibility
+
+- `fvi_version` is the document version; this spec defines `1`.
+- **Additive** changes (new OPTIONAL members, new registered codecs) do NOT bump
+  `fvi_version`. Readers MUST ignore members they do not recognize.
+- A change that alters the meaning of an existing member or makes a new member
+  REQUIRED bumps `fvi_version`.
+- A reader encountering a higher `fvi_version` than it implements SHOULD process
+  the members it understands and MUST NOT reject the document solely for the
+  version being higher, unless a member it relies on is absent.
+
+## 12. Conformance requirements (summary)
+
+A conformant **writer** MUST: emit a Header first; emit records in coded order
+with contiguous `n`; populate `src` from demux; use named/registered codec ids;
+encode one JSON value per UTF-8 LF-terminated line.
+
+A conformant **reader** MUST: accept any §4–§10 document; ignore unknown members;
+not assume `picture_count`, `pts`, or `size` are present unless required above.
+
+---
+
+## Appendix A — JSON Schema (informative)
+
+Header:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": ["format", "fvi_version", "stream", "source", "timescale"],
+  "properties": {
+    "format": { "const": "freemkv/video-index" },
+    "fvi_version": { "type": "integer", "minimum": 1 },
+    "timescale": { "type": "integer", "minimum": 1 },
+    "stream": { "type": "object", "required": ["codec", "width", "height", "scan"] },
+    "source": { "type": "object", "required": ["medium"] }
+  }
+}
+```
+
+Record:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": ["n", "src", "type", "key"],
+  "properties": {
+    "n": { "type": "integer", "minimum": 0 },
+    "type": { "enum": ["I", "P", "B"] },
+    "key": { "type": "boolean" },
+    "src": {
+      "type": "object",
+      "required": ["sector", "byte"],
+      "properties": {
+        "file": { "type": "integer" },
+        "sector": { "type": "integer", "minimum": 0 },
+        "byte": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}
+```
+
+## Appendix B — Registered codec identifiers
+
+| `codec` | Bitstream | Field profile |
+|---|---|---|
+| `mpeg2video` | ISO/IEC 13818-2 | §7.1 (field_order/progressive/nb_fields) |
+| `mpeg1video` | ISO/IEC 11172-2 | §7.1 |
+| `h264` | ISO/IEC 14496-10 | core + `ext.h264` |
+| `hevc` | ISO/IEC 23008-2 | core + `ext.hevc` |
+| `vc1` | SMPTE 421M | core |
+
+## Appendix C — Normative references
+
+- RFC 2119, RFC 8174 — Requirement keywords (BCP 14).
+- RFC 8259 — JSON.
+- ISO/IEC 13818-2 — MPEG-2 video (picture coding, §6.3.9–6.3.10).
+- ISO/IEC 14496-10 — H.264/AVC. ISO/IEC 23008-2 — H.265/HEVC.
+- ITU-T H.273 — Coding-independent code points (colour primaries/transfer/matrix).
+- SMPTE ST 2086 — Mastering display colour volume (HDR).
+- BCP 47 — Language tags.
+- RFC 9559 — Matroska (alignment of colour/field-order semantics).

docs/aacs.md

@@ -2,191 +2,45 @@
 
 ## 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.
+AACS (Advanced Access Content System) is the encryption layer used by Blu-ray
+and UHD 4K discs to protect content. libfreemkv implements AACS decryption so
+disc access is transparent to the application.
 
 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.
-
+- **AACS 1.0** -- Used by standard Blu-ray discs.
+- **AACS 2.0 / 2.1** -- Used by UHD 4K Blu-ray discs. Adds a per-sector bus
+  encryption layer on top of the standard content encryption. UHD drives accept
+  AACS 1.0 host credentials for backward compatibility.
+
+All versions use AES-128 for content decryption. The library reads the keys it
+needs from `keydb.cfg`, walks the disc's Media Key Block (MKB) to resolve the
+disc's key, and decrypts the content stream. AACS-encrypted discs therefore
+require a `keydb.cfg`; CSS-protected DVDs do not (see the CSS notes in the
+library docs).
+
+## How it works (feature level)
+
+When a disc is scanned, the library:
+
+1. Reads the disc's AACS key-input files from the `/AACS/` directory.
+2. Resolves the disc's key from `keydb.cfg` — either directly from a per-disc
+   entry, or by walking the MKB with the keys present in the keydb.
+3. Performs the drive-level SCSI authentication handshake needed to obtain the
+   Volume ID and, for UHD, the bus-decryption key.
+4. Decrypts the content stream as titles are read.
+
+A resolved key is verified against actual disc content before it is applied, so
+a stale or wrong key fails loudly rather than producing silent garbage. If no
+usable key is available for an AACS-encrypted disc, the library surfaces a
+specific error (the E70xx family) describing which part of the chain was
+missing, and a missing `keydb.cfg` surfaces as `Error::KeydbLoad` with the
+sentinel path `<no keydb in search paths>`.
 
 ## API Usage
 
-AACS decryption is transparent to the application. The `Disc::scan()` method handles everything automatically:
+AACS decryption is transparent to the application. `Disc::scan()` handles
+everything automatically:
 
 ```rust
 use libfreemkv::{Drive, Disc};
@@ -203,7 +57,6 @@ 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);
         }
@@ -215,108 +68,41 @@ if disc.encrypted {
 // 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
+    // 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()`.
+The application never touches keys, never calls decryption functions, and never
+manages handshakes. All of that is internal to `Disc::scan()` and the content
+reader.
 
 ### 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:
+`ScanOptions` controls where the keydb is loaded from. If no explicit path is
+set, the library checks the standard config locations. To specify an explicit
+path:
 
 ```rust
-let opts = ScanOptions::with_keydb("/path/to/KEYDB.cfg");
+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:
+After a successful scan, `disc.aacs` contains an `AacsState`:
 
 | 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 |
+| `disc_hash` | `String` | Identifier for the disc's key-input files |
+| `key_source` | `KeySource` | How the disc's key was resolved |
 
-### KeySource
+## keydb.cfg
 
-| 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
-```
+`keydb.cfg` is the single source of AACS key material. It is a text file (lines
+starting with `;` or `#` are comments) holding the host credentials and per-disc
+entries the library uses to resolve a disc. autorip can auto-download and
+refresh it from a configured URL. The library does not ship any AACS keys
+compiled into the binary.

docs/api-design.md

@@ -85,10 +85,10 @@ All URLs require a `scheme://path` format. Bare paths are rejected.
 // PES pipeline (frame-level) — input() returns Box<dyn FrameSource>,
 // output() returns Box<dyn FrameSink>.
 let input = libfreemkv::input("disc:///dev/sg4", &opts)?;    // DiscStream
-let input = libfreemkv::input("iso://Dune.iso", &opts)?;     // IsoStream
-let output = libfreemkv::output("mkv://Dune.mkv", &title)?;  // MkvOutputStream
-let output = libfreemkv::output("m2ts://Dune.m2ts", &title)?; // M2tsOutputStream
-let output = libfreemkv::output("network://10.1.7.11:9000", &title)?; // NetworkOutputStream
+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
 ```
 
@@ -171,23 +171,23 @@ libfreemkv/src/
 │   └── 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
+│   ├── capture.rs      Raw drive SCSI capture (INQUIRY/GET_CONFIG) 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)
+│   ├── mod.rs          Disc struct, scan, titles, formats; Disc::copy + Disc::sweep (Pass 1)
+│   ├── sweep.rs        Pass 1 internal helpers (pub(super))
 │   ├── 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)
+├── unlock.rs           Unlocker trait + registry (pluggable unlock seam)
 ├── 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)
+├── sector/             Sector I/O
 │   ├── mod.rs          SectorSource, SectorSink traits
 │   ├── file.rs         FileSectorSource, FileSectorSink (ISO-backed)
 │   └── decrypting.rs   DecryptingSectorSource decorator
@@ -198,7 +198,6 @@ libfreemkv/src/
 ├── 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

docs/architecture.md

@@ -1,8 +1,10 @@
 # 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.
+Rust library with profiles bundled and all SCSI communication handled in-process.
+AACS decryption requires an external `keydb.cfg` (default
+`~/.config/freemkv/keydb.cfg`) — the derivation math is internal, but no AACS key
+material is compiled in; DVD CSS player keys are the only compiled-in keys.
 
 **Repository:** <https://github.com/freemkv/libfreemkv>
 **License:** AGPL-3.0-only
@@ -15,9 +17,10 @@ AACS keys are derived internally, and all SCSI communication is handled in-proce
    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.
+2. **Firmware-clean core.** libfreemkv ships no firmware, no unlock CDBs, and no
+   drive profiles. Drive-unlock logic is plugged in by an external crate through
+   the `Unlocker` trait + registry (`register_unlocker`); without one the library
+   still rips via the host-certificate AACS handshake.
 
 3. **Transparent AACS.** The `ContentReader` decrypts on the fly when keys are
    available. Callers read cleartext sectors without knowing whether the disc
@@ -41,11 +44,9 @@ AACS keys are derived internally, and all SCSI communication is handled in-proce
 libfreemkv (lib.rs)
 │
 ├── Drive Access
-│   ├── drive         Drive — open, identify, init, unlock, single-shot read
+│   ├── drive         Drive — open, identify, init, 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
+│   ├── unlock        Unlocker trait + registry — the pluggable unlock seam
 │   ├── identity      DriveId from INQUIRY + GET_CONFIG 010C
 │   ├── speed         DriveSpeed enum, SET CD SPEED CDB builder
 │   └── event         Event system for drive status callbacks
@@ -65,7 +66,7 @@ libfreemkv (lib.rs)
 │
 ├── Streaming
 │   ├── mux/          Stream implementations (Disc, ISO, MKV, M2TS, Network, Stdio, Null)
-│   ├── pes           PES frame types; FrameSource / FrameSink direction-typed traits
+│   ├── pes           PES frame types; the unified pes::Stream (PesStream) read/write trait
 │   └── sector/       SectorSource / SectorSink traits, FileSector{Source,Sink}, DecryptingSectorSource
 │
 ├── I/O Primitives
@@ -74,8 +75,7 @@ libfreemkv (lib.rs)
 │
 ├── Support
 │   ├── keydb         KEYDB.cfg download, parse, verify, save
-│   ├── error         Error enum with numeric codes E1000-E8000
-│   └── profile       Bundled drive profiles
+│   └── error         Error enum with numeric codes E1000-E8000
 │
 └── lib.rs            Public API re-exports
 ```
@@ -89,13 +89,12 @@ 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
+  └─ Drive ready for init/read
 ```
 
 After open:
-- `init()` -- unlock + firmware upload + speed calibration
+- `init()` -- routes to the matching registered unlocker (if any); otherwise
+  a no-op and the cert handshake carries the disc
 - `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
@@ -195,17 +194,20 @@ implementing `execute()` for that OS and wiring it into `scsi::open()`.
 
 ---
 
-## Chipset Support
+## Drive Unlock
 
-| Chipset | Drives | Status |
-|---------|--------|--------|
-| MediaTek MT1959 | LG, ASUS, HP | Supported (bundled profiles) |
-| Renesas RS8xxx/RS9xxx | Pioneer, some HL-DT-ST | Planned |
+libfreemkv carries no drive-unlock mechanism. The `Unlocker` trait + registry
+(`src/unlock.rs`) is the seam: an external crate implements `Unlocker` and
+registers it once via `register_unlocker(...)`. At drive-prep the registry is
+walked in order and the first unlocker whose `matches()` is true is asked to
+`unlock_drive()` over the raw `ScsiTransport`. If none match, the drive is left
+untouched and the host-certificate AACS handshake carries the disc.
 
-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.
+The implementor owns everything firmware-specific — drive profiles, vendor CDBs,
+variant logic. Concrete unlockers live in the separate
+**[freemkv-unlock](https://github.com/freemkv/freemkv-unlock)** repository, never
+in libfreemkv. See [`drive-access.md`](drive-access.md#drive-unlock-seam) for the
+trait definition and routing.
 
 ---
 

docs/clpi.md

@@ -189,7 +189,7 @@ The full ripping pipeline chains three parsers:
 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.
+The `Disc::scan()` method in `src/disc/mod.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
 

docs/disc-to-rip.md

@@ -10,14 +10,14 @@ Insert disc
     │
     ▼
 1. Open drive (drive/mod.rs)
-    │  INQUIRY → identify drive
-    │  Match bundled profile → chipset, unlock parameters
+    │  INQUIRY → identify drive (DriveId)
     │
     ▼
-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()
+2. Init drive (drive/mod.rs → unlock seam)
+    │  Walk the registered-unlocker registry; first match unlocks the drive
+    │  (firmware/vendor handshakes are the unlocker's own business)
+    │  No match → drive untouched; host-cert AACS handshake carries the disc
+    │  Speed control → probe_disc()
     │
     ▼
 3. AACS handshake (aacs/handshake.rs) — optional
@@ -98,7 +98,7 @@ drive.probe_disc()?;
 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>;
+// 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)?;

docs/drive-access.md

@@ -7,8 +7,9 @@ optical drives.
 
 ## Drive
 
-`Drive` is the primary API. It owns the SCSI transport, the matched
-drive profile, and the chipset-specific platform driver.
+`Drive` is the primary API. It owns the SCSI transport and the drive
+identity (`DriveId`); any drive-specific unlock logic lives behind the
+pluggable [unlock seam](#drive-unlock-seam), not in `Drive` itself.
 
 ### Opening a Drive
 
@@ -16,15 +17,16 @@ drive profile, and the chipset-specific platform driver.
 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()`.
+`open()` performs: open device → send INQUIRY → build `DriveId`. The drive
+is ready for `wait_ready()` and `init()` (which routes through the unlock
+seam).
 
 ### Drive Operations
 
 | Method | Description |
 |--------|-------------|
 | `wait_ready()` | Wait for disc insertion (30s timeout, TUR polling) |
-| `init()` | Firmware upload + unlock + speed calibration |
+| `init()` | Route to the matching registered unlocker (if any), then prepare for reads |
 | `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. |
@@ -32,17 +34,21 @@ platform driver. The drive is ready for `wait_ready()` and `init()`.
 | `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 |
+| `has_profile()` | Whether a registered unlocker matches this drive |
 | `close()` | Consume Drive, cleanup (also runs via Drop) |
 
 ### init() Sequence
 
-`init()` orchestrates the full drive unlock:
+`init()` routes drive preparation through the unlock seam:
 
-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
+1. Walk the registered-unlocker registry; the first whose `matches()` is true
+   is asked to `unlock_drive()` over the raw transport.
+2. Whatever that unlocker needs (firmware upload, vendor handshakes, retries)
+   is the unlocker's own business — libfreemkv only forwards the transport.
+3. If no unlocker matches, the drive is left untouched and the library uses
+   the host-certificate AACS handshake.
+
+See [Drive Unlock Seam](#drive-unlock-seam) for the trait and registry.
 
 ### read() — single-shot
 
@@ -164,100 +170,68 @@ date for drives where Feature 010C is unavailable.
 
 ---
 
-## Drive Profiles
+## Drive Unlock Seam
 
-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:
+libfreemkv ships **no firmware, no unlock CDBs, and no drive profiles.** It
+knows only the *seam*, never the *mechanism*. The seam is the `Unlocker`
+trait plus a small process-wide registry (`src/unlock.rs`):
 
 ```rust
-// Bundled (compiled-in) -- no file I/O
-let profiles = profile::load_bundled()?;
+pub trait Unlocker: Send + Sync {
+    /// Stable, language-neutral identifier (logged).
+    fn name(&self) -> &str;
 
-// External file
-let profiles = profile::load_all(Path::new("/path/to/profiles.json"))?;
+    /// True if this unlocker handles the given drive.
+    fn matches(&self, id: &DriveId) -> bool;
+
+    /// Put the drive into extended-access mode. The one required capability.
+    fn unlock_drive(&self, scsi: &mut dyn ScsiTransport, id: &DriveId) -> Result<()>;
+
+    /// Read the disc Volume ID via the drive's OEM path. Default: no-op.
+    fn read_volume_id(&self, _scsi: &mut dyn ScsiTransport, _id: &DriveId)
+        -> Result<Option<[u8; 16]>> { Ok(None) }
+
+    /// Raise the drive to its maximum read speed. Default: no-op.
+    fn set_max_read_speed(&self, _scsi: &mut dyn ScsiTransport, _id: &DriveId)
+        -> Result<()> { Ok(()) }
+}
 ```
 
----
+An unlocker is supplied by an **external crate** and registered once at
+process start:
 
-## Chipsets
+```rust
+libfreemkv::register_unlocker(Box::new(some_unlocker::Plugin::new()));
+```
 
-### MediaTek MT1959
+The implementor owns everything about *how* a particular drive family is
+driven — drive identification against its own profile database, firmware
+upload, vendor CDBs, variant logic. libfreemkv only hands over the raw
+`ScsiTransport` and the `DriveId`.
 
-Covers all LG, ASUS, and HP optical drives. Two sub-variants share identical
-logic with different SCSI parameters:
+### Routing
 
-| Variant | READ BUFFER mode | Buffer ID |
-|---------|------------------|-----------|
-| MT1959-A | 0x01 | 0x44 |
-| MT1959-B | 0x02 | 0x77 |
+At drive-prep the registry is walked in registration order; the first
+unlocker whose `matches()` returns true is asked to `unlock_drive()` (and,
+when needed, `read_volume_id()` / `set_max_read_speed()`). If no unlocker
+matches, the drive is left untouched and the library falls back to the
+standard host-certificate AACS handshake (the "OEM route"). The
+`register_unlocker(...)` line is the entire plug: drop it (and the unlocker
+crate) and libfreemkv still compiles and rips via the cert handshake.
 
-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.
+Concrete unlockers — including the firmware-unlock profile databases,
+variant logic, and vendor CDBs that used to live in-tree — are maintained
+in the separate **[freemkv-unlock](https://github.com/freemkv/freemkv-unlock)**
+repository, never here.
 
 ---
 
 ## 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).
+A matching unlocker may raise the drive to its maximum read speed via
+`set_max_read_speed()` (a no-op when no unlocker matches or the unlocker
+declines). The library issues SET CD SPEED (0xBB) through the generic CDB
+builder; the concrete speed policy lives in the unlocker.
 
 Available speeds:
 

docs/rip-recovery.md

@@ -108,8 +108,8 @@ lines of `Mapfile::stats()` checks.
 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 `*`.
+   → **damage-jump**: skip ahead by `1024×batch×multiplier` sectors (64 MB base for
+   UHD). Double the multiplier on each jump (64→128→256→512 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.
@@ -161,8 +161,8 @@ 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.** Research showed neither ddrescue
-nor MakeMKV does this. Drive firmware has access to raw analog signal, laser
+**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
@@ -178,7 +178,7 @@ 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),
+mux stage reads the ISO via `FileSectorSource`. 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), …)`
@@ -198,4 +198,4 @@ scrape vs. retry with direction reversal) if there's measured benefit.
 
 - [ddrescue manual, Algorithm chapter](https://www.gnu.org/software/ddrescue/manual/ddrescue_manual.html)
 - [ddrescue optical media notes](https://www.electric-spoon.com/doc/gddrescue/html/Optical-media.html)
-- Source: [`src/disc/mapfile.rs`](../src/disc/mapfile.rs), [`src/disc/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`).
+- Source: [`src/disc/mapfile.rs`](../src/disc/mapfile.rs), [`src/disc/mod.rs`](../src/disc/mod.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`).

src/aacs/boil.rs

@@ -0,0 +1,500 @@
+//! AACS derivation "boil-down" — one public home for the key chain.
+//!
+//! Thin newtypes at the API boundary and three wrapper functions over the
+//! existing crypto. Nothing here re-implements a primitive: every function
+//! delegates to the already-audited code in [`super::keys`] and
+//! [`super::variants`], so the boil-down cannot drift from production math.
+//!
+//! The newtypes wrap bare `[u8; 16]` ONLY at this boundary — the crypto
+//! internals continue to operate on raw arrays. They exist so a caller threads
+//! the chain `DK → MK → VUK → UK` without confusing one 16-byte secret for
+//! another, not to refactor the resolver.
+//!
+//! Chain (matches `aacs::keys::resolve_keys_classical` path 1 and
+//! `aacs::keys::resolve_keys_v21` path 1 byte-for-byte):
+//!
+//! ```text
+//!   mk_from_dk(device_keys, mkb, vid)  →  MediaKey   (Km)
+//!   mk_from_pk(processing_keys, mkb)   →  MediaKey   (Km)
+//!   vuk_from_mk(MediaKey, Vid)         →  Vuk        (= AES-G(Km, VID))
+//!   uk_from_vuk(Vuk, enc_title_keys)   →  [UnitKey]  (decrypt_unit_key each)
+//! ```
+//!
+//! `mk_from_dk` and `mk_from_pk` are two entry points to the SAME Media Key,
+//! both via the MKB's Subset-Difference cvalue tables: the device-key path
+//! recovers its Processing Key at the matching SD node and walks on to the MK;
+//! the processing-key path starts from a precomputed PK. Neither needs a VID
+//! (the VID enters at `vuk_from_mk`).
+
+use super::keys::{
+    decrypt_unit_key, derive_media_key_and_pk_from_dk, derive_media_key_from_pk, derive_vuk,
+};
+use super::types::DeviceKey;
+
+/// Volume ID (16 bytes) — read from the disc via the SCSI handshake / OEM path.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Vid(pub [u8; 16]);
+
+/// Media Key (Km, 16 bytes) — the MKB-scoped key derived from device keys.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct MediaKey(pub [u8; 16]);
+
+/// Volume Unique Key (VUK / Kvu, 16 bytes) — derived from `MediaKey` + `Vid`,
+/// decrypts the per-disc encrypted title keys in `Unit_Key_RO.inf`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Vuk(pub [u8; 16]);
+
+/// Processing Key (Kp, 16 bytes) — an MKB Subset-Difference key that yields the
+/// Media Key. A leaked/precomputed PK in the keydb, or the intermediate PK a
+/// device-key walk derives at its matching SD node.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ProcessingKey(pub [u8; 16]);
+
+/// One decrypted per-CPS-unit AACS title key.
+///
+/// `idx` is the POSITIONAL index of the encrypted title key within the slice
+/// handed to [`uk_from_vuk`] (i.e. its order in `Unit_Key_RO.inf`'s key-storage
+/// area). The CPS-unit *number* association (the `u32` in
+/// `ResolvedKeys::unit_keys`) is a higher-level concern owned by
+/// [`super::keys::parse_unit_key_ro`], which pairs each positional key with its
+/// declared CPS unit; this primitive only does the AES, so it surfaces position.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct UnitKey {
+    pub idx: u32,
+    pub key: [u8; 16],
+}
+
+/// Derive the Volume Unique Key from a Media Key and Volume ID.
+///
+/// Wraps [`derive_vuk`] verbatim: `VUK = AES-128-ECB-DECRYPT(MK, VID) XOR VID`.
+/// This is byte-identical to the inline `derive_vuk(&mk, ctx.volume_id)` call in
+/// every classical resolver path AND to the `Kvu = AES-G(Km, VID)` step inside
+/// [`derive_media_key_variant`] (AES-G and `derive_vuk` are the same math), so
+/// `vuk_from_mk(mk_from_dk(..)?, vid)` reproduces the V21 variant VUK exactly.
+pub fn vuk_from_mk(mk: MediaKey, vid: Vid) -> Vuk {
+    Vuk(derive_vuk(&mk.0, &vid.0))
+}
+
+/// Decrypt the disc's encrypted title keys with a VUK.
+///
+/// Wraps [`decrypt_unit_key`] (AES-128-ECB-DECRYPT) per entry, mirroring the
+/// `derive_uks` closure in `resolve_keys_classical` / `resolve_keys_v21`. The
+/// returned `UnitKey::idx` is the slice position; pair with CPS-unit numbers via
+/// [`super::keys::parse_unit_key_ro`] when the numbering matters.
+pub fn uk_from_vuk(vuk: Vuk, enc_title_keys: &[[u8; 16]]) -> Vec<UnitKey> {
+    enc_title_keys
+        .iter()
+        .enumerate()
+        .map(|(i, enc)| UnitKey {
+            idx: i as u32,
+            key: decrypt_unit_key(&vuk.0, enc),
+        })
+        .collect()
+}
+
+/// Derive the Media Key (Km) from positioned device keys via the MKB's
+/// Subset-Difference tables.
+///
+/// Wraps [`derive_media_key_and_pk_from_dk`] — the real SD walk the resolver
+/// runs: each positioned device key is placed against the MKB's subset-diff /
+/// cvalue records, recovering its Processing Key at the matching node and
+/// continuing to the Media Key. Reachable for real discs whenever a device key
+/// applies to the MKB. No VID is involved here — it enters at [`vuk_from_mk`].
+///
+/// Returns [`Error::AacsMkUnavailable`] (E7018) when no supplied device key
+/// resolves the MKB — the same terminal error as [`mk_from_pk`]; no numeric
+/// distinction is load-bearing at this boundary.
+///
+/// [`Error::AacsMkUnavailable`]: crate::error::Error::AacsMkUnavailable
+pub fn mk_from_dk(device_keys: &[DeviceKey], mkb: &[u8]) -> Result<MediaKey, crate::error::Error> {
+    // Positioned device keys drive the real Subset-Difference MKB walk
+    // ([`derive_media_key_and_pk_from_dk`], the same walk the resolver runs). The
+    // old Media-Key-Variant path needed integrator Key Correction Data absent
+    // in-tree, so it Err'd for EVERY real disc (dead for both consumers —
+    // freemkv-keysources' DK fallback and the kdb harvester). No VID is needed
+    // for the Media Key; it enters only at [`vuk_from_mk`].
+    match derive_media_key_and_pk_from_dk(mkb, device_keys) {
+        Some((km, _pk)) => Ok(MediaKey(km)),
+        None => Err(crate::error::Error::AacsMkUnavailable),
+    }
+}
+
+/// Derive the Media Key (Km) from one or more Processing Keys and the disc MKB.
+///
+/// Wraps [`derive_media_key_from_pk`] — the Subset-Difference PK→MK walk: each
+/// processing key is validated (and tree-walked) against the MKB's cvalue tables
+/// (records `0x04`/`0x05`) until one yields the Media Key whose verify record
+/// (`0x81`/`0x86`) matches. Unlike [`mk_from_dk`] this path is reachable for
+/// real discs — a leaked/precomputed AACS Processing Key in the keydb resolves
+/// the Media Key directly. No VID is involved at this step; the VID enters at
+/// [`vuk_from_mk`].
+///
+/// Returns [`Error::AacsMkUnavailable`] (E7018) when no processing key resolves
+/// the MKB — the same terminal error as [`mk_from_dk`]; no numeric distinction
+/// is load-bearing at this boundary.
+///
+/// [`Error::AacsMkUnavailable`]: crate::error::Error::AacsMkUnavailable
+pub fn mk_from_pk(
+    processing_keys: &[[u8; 16]],
+    mkb: &[u8],
+) -> Result<MediaKey, crate::error::Error> {
+    match derive_media_key_from_pk(mkb, processing_keys) {
+        Some(km) => Ok(MediaKey(km)),
+        None => Err(crate::error::Error::AacsMkUnavailable),
+    }
+}
+
+/// A candidate key at any rung of the AACS ladder, handed to [`resolve_candidate`].
+///
+/// Each variant carries the module's existing newtype for that rung (a `Dk` is a
+/// POSITIONED [`DeviceKey`] — recover an unpositioned one with
+/// [`super::keys::recover_dk_position`] first).
+#[derive(Debug, Clone)]
+pub enum KeyCandidate {
+    Uk(UnitKey),
+    Vuk(Vuk),
+    Mk(MediaKey),
+    Pk(ProcessingKey),
+    Dk(DeviceKey),
+}
+
+/// The AACS key chain derived from a candidate, from [`resolve_candidate`].
+///
+/// PURE DERIVATION — no unit sampling, no validation. `unit_keys` holds every
+/// CPS-unit key the disc's `Unit_Key_RO.inf` yields from the VUK (positional
+/// order); the caller runs [`super::decrypt::unit_key_validates`] to find which
+/// one actually opens the disc. Rungs above the candidate are `None` (a `Vuk`
+/// candidate has no `mk`/`pk`/`dk`; a `Uk` candidate has only `unit_keys`).
+#[derive(Debug, Clone)]
+pub struct ResolvedChain {
+    /// Every unit key derived from the VUK, as `(cps_unit_number, key)` — the
+    /// CPS-unit numbers come from `Unit_Key_RO.inf` (via `parse_unit_key_ro`), so
+    /// a consumer maps `UK → CPS unit` directly. Same shape as
+    /// [`super::keys::ResolvedKeys::unit_keys`]. A `Uk` candidate yields exactly
+    /// itself, keyed by its own `idx`.
+    pub unit_keys: Vec<(u32, [u8; 16])>,
+    pub vuk: Option<Vuk>,
+    pub mk: Option<MediaKey>,
+    pub pk: Option<ProcessingKey>,
+    /// The positioned device key (for a `Dk` candidate).
+    pub dk: Option<DeviceKey>,
+}
+
+/// Derive the full AACS key chain from a candidate key of ANY ladder rung.
+///
+/// Runs the deterministic derivation DOWNWARD to the disc's terminal unit keys:
+/// `DK → MK → VUK → UKs`, `PK → MK → VUK → UKs`, `MK → VUK → UKs`,
+/// `VUK → UKs`, or `UK → itself`. Composes the module's own boil steps
+/// ([`mk_from_pk`], [`vuk_from_mk`], [`uk_from_vuk`]) and parses
+/// `Unit_Key_RO.inf` at the version the disc's MKB declares (48-byte stride for
+/// AACS-1.0, 64 for AACS-2.x), so a multi-CPS disc yields all its unit keys from
+/// the one candidate.
+///
+/// PURE DERIVATION: no sampling, no validation, no position recovery. Every step
+/// is deterministic AES, so the returned keys are only as sound as the input
+/// candidate — validate `unit_keys` against a real encrypted unit with
+/// [`super::decrypt::unit_key_validates`] to prove the candidate opens the disc.
+///
+/// Returns `None` only when derivation itself cannot proceed: a PK its MKB
+/// rejects, a `Dk` the MKB can't process, a missing VID on a path that needs
+/// one, or an unparseable/empty `Unit_Key_RO.inf`.
+pub fn resolve_candidate(
+    candidate: &KeyCandidate,
+    mkb: &[u8],
+    unit_key_ro: &[u8],
+    vid: Option<Vid>,
+) -> Option<ResolvedChain> {
+    use super::keys::{AacsVersion, derive_media_key_and_pk_from_dk, mkb_type, parse_unit_key_ro};
+
+    // Boil a VUK → all unit keys, each paired with its declared CPS-unit number.
+    // `.inf` parsing lives here: derive the stride version from the disc's own
+    // MKB, then defer the VUK→unit-keys step to the shared `derive_unit_keys`
+    // (the one place both resolvers and this path decrypt the title keys).
+    let boil = |vuk: Vuk| -> Option<Vec<(u32, [u8; 16])>> {
+        let version = mkb_type(mkb)
+            .map(|t| t.generation())
+            .unwrap_or(AacsVersion::V10);
+        let ukf = parse_unit_key_ro(unit_key_ro, version)?;
+        if ukf.encrypted_keys.is_empty() {
+            return None;
+        }
+        Some(super::keys::derive_unit_keys(&ukf, &vuk.0))
+    };
+
+    match candidate {
+        KeyCandidate::Uk(uk) => Some(ResolvedChain {
+            unit_keys: vec![(uk.idx, uk.key)],
+            vuk: None,
+            mk: None,
+            pk: None,
+            dk: None,
+        }),
+        KeyCandidate::Vuk(v) => Some(ResolvedChain {
+            unit_keys: boil(*v)?,
+            vuk: Some(*v),
+            mk: None,
+            pk: None,
+            dk: None,
+        }),
+        KeyCandidate::Mk(mk) => {
+            let vuk = vuk_from_mk(*mk, vid?);
+            Some(ResolvedChain {
+                unit_keys: boil(vuk)?,
+                vuk: Some(vuk),
+                mk: Some(*mk),
+                pk: None,
+                dk: None,
+            })
+        }
+        KeyCandidate::Pk(pk) => {
+            let mk = mk_from_pk(std::slice::from_ref(&pk.0), mkb).ok()?;
+            let vuk = vuk_from_mk(mk, vid?);
+            Some(ResolvedChain {
+                unit_keys: boil(vuk)?,
+                vuk: Some(vuk),
+                mk: Some(mk),
+                pk: Some(*pk),
+                dk: None,
+            })
+        }
+        KeyCandidate::Dk(dk) => {
+            let (km, pk) = derive_media_key_and_pk_from_dk(mkb, std::slice::from_ref(dk))?;
+            let mk = MediaKey(km);
+            let vuk = vuk_from_mk(mk, vid?);
+            Some(ResolvedChain {
+                unit_keys: boil(vuk)?,
+                vuk: Some(vuk),
+                mk: Some(mk),
+                pk: Some(ProcessingKey(pk)),
+                dk: Some(dk.clone()),
+            })
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::aacs::decrypt::aes_ecb_encrypt;
+    use crate::aacs::keys::{decrypt_unit_key, derive_vuk};
+
+    /// `vuk_from_mk` must equal the inline `derive_vuk` path bit-for-bit, for
+    /// several known (MK, VID) vectors.
+    #[test]
+    fn vuk_from_mk_matches_inline_derive_vuk() {
+        let cases: [([u8; 16], [u8; 16]); 3] = [
+            ([0x5A; 16], [0xA5; 16]),
+            ([0x11; 16], [0x22; 16]),
+            (
+                [
+                    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C,
+                    0x0D, 0x0E, 0x0F,
+                ],
+                [
+                    0xF0, 0xE1, 0xD2, 0xC3, 0xB4, 0xA5, 0x96, 0x87, 0x78, 0x69, 0x5A, 0x4B, 0x3C,
+                    0x2D, 0x1E, 0x0F,
+                ],
+            ),
+        ];
+        for (mk, vid) in cases {
+            let inline = derive_vuk(&mk, &vid);
+            let boiled = vuk_from_mk(MediaKey(mk), Vid(vid));
+            assert_eq!(boiled.0, inline, "vuk_from_mk must equal derive_vuk");
+        }
+    }
+
+    /// `uk_from_vuk` must equal the inline `decrypt_unit_key` path bit-for-bit
+    /// and carry positional indices 0..n. Built by encrypting known plaintext
+    /// title keys under the VUK (the same primitive the resolver inverts).
+    #[test]
+    fn uk_from_vuk_matches_inline_decrypt_unit_key() {
+        let vuk = [0x5Au8; 16];
+        let plain_keys = [[0x11u8; 16], [0x22u8; 16], [0xCDu8; 16]];
+        let enc: Vec<[u8; 16]> = plain_keys
+            .iter()
+            .map(|k| aes_ecb_encrypt(&vuk, k))
+            .collect();
+
+        let boiled = uk_from_vuk(Vuk(vuk), &enc);
+        assert_eq!(boiled.len(), enc.len());
+        for (i, uk) in boiled.iter().enumerate() {
+            assert_eq!(uk.idx, i as u32, "idx must be the positional index");
+            // Matches the inline derive_uks closure: decrypt_unit_key(vuk, enc).
+            assert_eq!(uk.key, decrypt_unit_key(&vuk, &enc[i]));
+            // And recovers the original plaintext title key.
+            assert_eq!(
+                uk.key, plain_keys[i],
+                "VUK roundtrip recovers the title key"
+            );
+        }
+    }
+
+    /// `uk_from_vuk` on an empty slice yields no keys (no panic, no phantom idx).
+    #[test]
+    fn uk_from_vuk_empty_is_empty() {
+        assert!(uk_from_vuk(Vuk([0u8; 16]), &[]).is_empty());
+    }
+
+    /// `mk_from_dk` returns `Err(AacsMkUnavailable)` when the MKB has no
+    /// processable Subset-Difference tables (empty MKB, or one with no
+    /// mk_dv/cvalues/subdiff records) — never a wrong key, never a panic.
+    #[test]
+    fn mk_from_dk_errors_on_unprocessable_mkb() {
+        let dk = DeviceKey {
+            key: [0x11; 16],
+            node: 1,
+            uv: 1,
+            u_mask_shift: 0,
+        };
+        // Empty MKB → no SD records to walk → Err.
+        let e = mk_from_dk(std::slice::from_ref(&dk), &[]);
+        assert!(matches!(e, Err(crate::error::Error::AacsMkUnavailable)));
+
+        // An MKB with no complete Subset-Difference tables (mk_dv / cvalues /
+        // subdiff) cannot yield a Media Key, so the real walk also errors —
+        // never silently yields a key.
+        let mut mkb: Vec<u8> = Vec::new();
+        mkb.extend_from_slice(&[0x82, 0x00, 0x00, 0x14]); // stray data record only
+        mkb.extend_from_slice(&[0xAB; 16]);
+        let e2 = mk_from_dk(&[dk], &mkb);
+        assert!(matches!(e2, Err(crate::error::Error::AacsMkUnavailable)));
+    }
+
+    /// Build a 4-byte MKB record header (type + 3-byte big-endian total length,
+    /// header included) and append `body`. Mirrors the MKB record framing the
+    /// parser expects; no crypto.
+    fn mkb_record(rec_type: u8, body: &[u8]) -> Vec<u8> {
+        let total = 4 + body.len();
+        let mut rec = Vec::with_capacity(total);
+        rec.push(rec_type);
+        rec.push(((total >> 16) & 0xFF) as u8);
+        rec.push(((total >> 8) & 0xFF) as u8);
+        rec.push((total & 0xFF) as u8);
+        rec.extend_from_slice(body);
+        rec
+    }
+
+    /// `mk_from_pk` resolves a planted Processing Key against a synthetic MKB and
+    /// drives the FULL boil chain PK → MK → VUK → UK. The MKB is built with the
+    /// same (pk, cv, mk_dv, uv) construction the production SD walk validates, so
+    /// this proves a PK entry yields real Unit Keys — not just an `Ok`.
+    #[test]
+    fn mk_from_pk_drives_full_chain_to_uks() {
+        let pk: [u8; 16] = [
+            0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE,
+            0xFF, 0x00,
+        ];
+        let mk: [u8; 16] = [
+            0xA0, 0xA1, 0xA2, 0xA3, 0xA4, 0xA5, 0xA6, 0xA7, 0xA8, 0xA9, 0xAA, 0xAB, 0xAC, 0xAD,
+            0xAE, 0xAF,
+        ];
+        let uv: [u8; 4] = [0x00, 0x00, 0x04, 0x00];
+
+        // cv = AES-E(pk, mk_raw), where mk_raw is mk with the last-4-bytes-uv XOR
+        // pre-undone, so the validate step XORs uv back in and recovers mk.
+        let mut mk_raw = mk;
+        for a in 0..4 {
+            mk_raw[12 + a] ^= uv[a];
+        }
+        let cv = aes_ecb_encrypt(&pk, &mk_raw);
+
+        // mk_dv = AES-E(mk, magic||pad): AES-D(mk, mk_dv) starts with the AACS
+        // verify sentinel.
+        let mut vd = [0x11u8; 16];
+        vd[..8].copy_from_slice(&[0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF]);
+        let mk_dv = aes_ecb_encrypt(&mk, &vd);
+
+        // Synthetic MKB: type/version (0x10), verify record (0x86 = mk_dv),
+        // one-entry SD index (0x04 = [u_mask_shift=0][uv]), one-entry cvalue
+        // table (0x05 = cv).
+        let mut sd = vec![0u8];
+        sd.extend_from_slice(&uv);
+        let mut mkb = Vec::new();
+        mkb.extend_from_slice(&mkb_record(0x10, &[0, 0, 0, 0x20, 0, 0, 0, 0x52]));
+        mkb.extend_from_slice(&mkb_record(0x86, &mk_dv));
+        mkb.extend_from_slice(&mkb_record(0x04, &sd));
+        mkb.extend_from_slice(&mkb_record(0x05, &cv));
+
+        // PK → MK.
+        let got_mk = mk_from_pk(std::slice::from_ref(&pk), &mkb).expect("planted PK resolves MK");
+        assert_eq!(got_mk, MediaKey(mk), "mk_from_pk recovers the planted MK");
+
+        // MK → VUK → UK over an encrypted title key.
+        let vid = Vid([0x42u8; 16]);
+        let plain_uk = [0x7Eu8; 16];
+        let vuk = vuk_from_mk(got_mk, vid);
+        let enc = aes_ecb_encrypt(&vuk.0, &plain_uk);
+        let uks = uk_from_vuk(vuk, std::slice::from_ref(&enc));
+        assert_eq!(uks.len(), 1);
+        assert_eq!(uks[0].key, plain_uk, "PK chain recovers the title key");
+
+        // A corrupt PK resolves nothing.
+        let mut bad = pk;
+        bad[0] ^= 0xFF;
+        assert!(matches!(
+            mk_from_pk(std::slice::from_ref(&bad), &mkb),
+            Err(crate::error::Error::AacsMkUnavailable)
+        ));
+    }
+
+    /// Minimal AACS-1.0 (48-byte stride) `Unit_Key_RO.inf` with `n` encrypted
+    /// unit keys — `parse_unit_key_ro` numbers CPS units 1..=n.
+    fn synth_inf(encs: &[[u8; 16]]) -> Vec<u8> {
+        let uk_pos = 32usize;
+        let stride = 48usize;
+        let n = encs.len();
+        let total = uk_pos + 48 + n.saturating_sub(1) * stride + 16;
+        let mut inf = vec![0u8; total.max(20)];
+        inf[..4].copy_from_slice(&(uk_pos as u32).to_be_bytes());
+        inf[uk_pos..uk_pos + 2].copy_from_slice(&(n as u16).to_be_bytes());
+        for (i, k) in encs.iter().enumerate() {
+            let o = uk_pos + 48 + i * stride;
+            inf[o..o + 16].copy_from_slice(k);
+        }
+        inf
+    }
+
+    /// A VUK candidate boils to ALL the disc's unit keys, each paired with its
+    /// declared CPS-unit number, and each key equals the VUK-decrypt of its slot.
+    #[test]
+    fn resolve_candidate_vuk_returns_all_cps_units() {
+        let vuk = Vuk([0x33u8; 16]);
+        let encs = [[0x11u8; 16], [0x22u8; 16], [0x44u8; 16]];
+        let inf = synth_inf(&encs);
+        let r = resolve_candidate(&KeyCandidate::Vuk(vuk), &[], &inf, None).expect("vuk derives");
+        let cps: Vec<u32> = r.unit_keys.iter().map(|(c, _)| *c).collect();
+        assert_eq!(
+            cps,
+            vec![1, 2, 3],
+            "every CPS unit surfaced, numbered from the inf"
+        );
+        for ((_, key), enc) in r.unit_keys.iter().zip(encs.iter()) {
+            assert_eq!(
+                *key,
+                decrypt_unit_key(&vuk.0, enc),
+                "key = VUK-decrypt of its slot"
+            );
+        }
+        assert_eq!(r.vuk, Some(vuk));
+        assert!(r.mk.is_none() && r.pk.is_none() && r.dk.is_none());
+    }
+
+    /// A bare UK candidate is terminal — it returns itself keyed by its own idx.
+    #[test]
+    fn resolve_candidate_uk_is_itself() {
+        let uk = UnitKey {
+            idx: 2,
+            key: [0x9u8; 16],
+        };
+        let r = resolve_candidate(&KeyCandidate::Uk(uk), &[], &[], None).expect("uk is terminal");
+        assert_eq!(r.unit_keys, vec![(2, uk.key)]);
+        assert!(r.vuk.is_none() && r.mk.is_none());
+    }
+
+    /// MK/PK/DK paths derive the VUK from a VID; without one, derivation stops.
+    #[test]
+    fn resolve_candidate_mk_requires_vid() {
+        let r = resolve_candidate(&KeyCandidate::Mk(MediaKey([1u8; 16])), &[], &[], None);
+        assert!(r.is_none(), "MK path returns None without a VID");
+    }
+}

src/aacs/host_certs.rs

@@ -0,0 +1,22 @@
+//! Host-certificate collection — the one libfreemkv-side concern left from the
+//! old in-tree AACS handshake. The cert mutual-auth itself now lives in the
+//! `freemkv-unlock` AACS unlocker; libfreemkv only gathers the certs (a
+//! keysource concern) and hands them across the seam.
+
+/// Union the host certificates a scan can offer the drive: the explicit
+/// `DriveCredentials`, then each key source's `host_certs(mkb)`. Host certs are
+/// keysource-served, never compiled in. `mkb` lets a source pick a
+/// generation-appropriate cert (the default impl ignores it).
+pub fn collect_host_certs(
+    opts: &crate::disc::ScanOptions,
+    mkb: Option<u32>,
+) -> Vec<crate::aacs::HostCert> {
+    let mut host_certs: Vec<crate::aacs::HostCert> = Vec::new();
+    if let Some(c) = &opts.credentials {
+        host_certs.extend(c.host_certs.iter().cloned());
+    }
+    for src in &opts.key_sources {
+        host_certs.extend(src.host_certs(mkb));
+    }
+    host_certs
+}

src/aacs/keydb.rs

@@ -1,436 +0,0 @@
-//! 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.
-pub(crate) fn parse_hex(s: &str) -> Option<Vec<u8>> {
-    let s = s.trim().trim_start_matches("0x").trim_start_matches("0X");
-    if s.len() % 2 != 0 {
-        return None;
-    }
-    let mut out = Vec::with_capacity(s.len() / 2);
-    for i in (0..s.len()).step_by(2) {
-        out.push(u8::from_str_radix(&s[i..i + 2], 16).ok()?);
-    }
-    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
-            if line.starts_with("| DK") {
-                if let Some(dk) = Self::parse_device_key(line) {
-                    db.device_keys.push(dk);
-                }
-                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)
-            if line.starts_with("| HC2") {
-                if let Some(hc) = db.host_certs.last_mut() {
-                    if let Some((pk, cert)) = Self::parse_host_cert_v2(line) {
-                        hc.private_key_v2 = Some(pk);
-                        hc.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.
-    pub fn load(path: &std::path::Path) -> std::io::Result<Self> {
-        let data = std::fs::read_to_string(path)?;
-        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))
-    }
-
-    // ── Parsers ─────────────────────────────────────────────────────────────
-
-    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
-    }
-
-    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();
-
-        Some(HostCert {
-            private_key: parse_hex20(priv_str)?,
-            certificate: parse_hex(cert_str)?,
-            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
-        let title = if let Some(start) = title_part.find('(') {
-            if let Some(end) = title_part.rfind(')') {
-                title_part[start + 1..end].to_string()
-            } else {
-                title_part.to_string()
-            }
-        } else {
-            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() {
-        let line = r#"***REMOVED*** = DUNE_PART_TWO (Dune: Part Two) | D | 2024-04-02 | M | ***REMOVED*** | I | ***REMOVED*** | V | ***REMOVED*** | U | 1-***REMOVED*** ; MKBv77"#;
-        let entry = KeyDb::parse_disc_entry(line).unwrap();
-        assert_eq!(entry.title, "Dune: Part Two");
-        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);
-    }
-
-    #[test]
-    fn test_parse_device_key() {
-        let line = "| DK | DEVICE_KEY ***REMOVED*** | 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_parse_host_cert() {
-        let line = "| HC | HOST_PRIV_KEY ***REMOVED*** | HOST_CERT ***REMOVED*** ; Revoked";
-        let hc = KeyDb::parse_host_cert(line).unwrap();
-        assert_eq!(hc.private_key[0], 0x90);
-        assert_eq!(hc.certificate.len(), 92);
-    }
-
-    #[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 Dune: Part Two
-        let dune = db
-            .disc_entries
-            .values()
-            .find(|e| e.title.contains("Dune: Part Two") && e.vuk.is_some())
-            .expect("Dune: Part Two not found");
-        assert!(dune.media_key.is_some());
-        assert!(dune.vuk.is_some());
-        assert!(!dune.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

@@ -8,33 +8,116 @@
 //!   | 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 boil;
 pub mod decrypt;
-pub mod handshake;
-pub mod keydb;
+pub mod host_certs;
 pub mod keys;
+pub mod provider;
+pub mod trace;
+pub mod types;
 pub mod variants;
-pub mod verify_magics;
+
+/// On-disc UDF paths to the AACS key-input files (with their fallbacks).
+/// Centralised so every reader (`resolve_vid_only`, `read_aacs_inputs`,
+/// `read_mkb_content`, `read_aacs_version`) walks the exact same files — adding
+/// or changing a fallback in one place can then never silently diverge the
+/// disc_hash / MKB / VID that another reader feeds a key service.
+pub const PATH_UNIT_KEY_RO: &str = "/AACS/Unit_Key_RO.inf";
+pub const PATH_UNIT_KEY_RO_DUPLICATE: &str = "/AACS/DUPLICATE/Unit_Key_RO.inf";
+pub const PATH_MKB_RO: &str = "/AACS/MKB_RO.inf";
+pub const PATH_MKB_RW: &str = "/AACS/MKB_RW.inf";
+pub const PATH_CONTENT_CERT: &str = "/AACS/Content000.cer";
+pub const PATH_CONTENT_CERT_ALT: &str = "/AACS/Content001.cer";
+
+// Boil-down derivation primitives (thin newtypes + wrappers over the crypto).
+pub use boil::{
+    KeyCandidate, MediaKey, ProcessingKey, ResolvedChain, UnitKey, Vid, Vuk, mk_from_dk,
+    mk_from_pk, resolve_candidate, uk_from_vuk, vuk_from_mk,
+};
+// Structured, English-free resolution trace.
+pub use trace::{KeyNode, KeyOutcome, KeyStep, ResolutionTrace, UnlockOutcome, UnlockStep};
 
 // 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, decrypt_bus, decrypt_unit, decrypt_unit_full, decrypt_unit_try_keys,
-    is_unit_encrypted,
+    ALIGNED_UNIT_LEN, ALIGNED_UNIT_SECTORS, UnitKeyResult, aacs_unit_encrypted,
+    aacs_unit_needs_decrypt, aacs_unit_still_ciphertext, decrypt_bus, decrypt_unit,
+    decrypt_unit_checked, decrypt_unit_full, decrypt_unit_try_keys, fill_null_ts_unit,
+    is_unit_aligned, ts_packet_total, ts_sync_count, ts_sync_destroyed, unit_is_clean_ps,
+    unit_is_clean_ts, unit_key_validates,
 };
-pub use keydb::{DeviceKey, DiscEntry, HostCert, KeyDb};
+// `probe` is a reproduction-harness helper (see keys.rs), not part of the
+// documented 1.0 surface; keep it reachable but off the rendered docs so we
+// don't commit semver stability to test primitives.
+#[doc(hidden)]
+pub use keys::probe;
 pub use keys::{
-    AacsVersion, ContentCert, ResolveContext, ResolvedKeys, UnitKeyFile, decrypt_unit_key,
+    AACS_MAJOR_BD, AACS_MAJOR_UHD, AacsVersion, ContentCert, MKB_20_CATEGORY_C, MKB_21_CATEGORY_C,
+    MKB_TYPE_3_RECORDABLE, MKB_TYPE_4_PRERECORDED, MKB_TYPE_10_CLASS_II, MkbType, ResolveContext,
+    ResolveFailure, ResolvedKeys, UnitKeyFile, decrypt_unit_key, derive_media_key_and_pk_from_dk,
     derive_media_key_from_dk, derive_media_key_from_pk, derive_vuk, disc_hash, disc_hash_hex,
-    mkb_version, parse_content_cert, parse_unit_key_ro, read_mkb_from_drive, resolve_keys_v1,
-    resolve_keys_v2, resolve_keys_v21, validate_media_key_against_mkb,
+    mkb_content_len, mkb_is_uhd, mkb_type, mkb_type_raw, mkb_version, parse_content_cert,
+    parse_unit_key_ro, read_mkb_from_drive, recover_dk_position, resolve_keys_v1, resolve_keys_v2,
+    resolve_keys_v21, resolve_keys_with_reason, trim_mkb,
 };
+pub use provider::KeyProvider;
+pub use types::{DeviceKey, DiscEntry, HostCert};
 pub use variants::{
     KEY_CORRECTION_DATA_PLACEHOLDER, MediaKeyVariantError, MkbRecord, ProcessingKeyMatch,
-    derive_media_key_variant, is_variant_mkb, variant_data_record, variant_key_data, variant_nonce,
-    walk_mkb, walk_processing_key,
+    derive_media_key_variant, is_variant_mkb, variant_nonce, walk_mkb, walk_processing_key,
 };
+
+#[cfg(test)]
+mod tests {
+    //! Re-export surface guards. The module's public API is the set of
+    //! `pub use` items above. A regression that drops or renames an export
+    //! (the class of bug that shipped in 0.31.0 by silently changing a
+    //! surface) breaks compilation of these references, so they act as a
+    //! compile-time contract for the crate's AACS surface.
+
+    use super::*;
+
+    #[test]
+    fn aligned_unit_len_is_three_2048_byte_sectors() {
+        // ALIGNED_UNIT_LEN is the AACS aligned-unit size: 3 × 2048 = 6144.
+        // Re-exported from decrypt; pin the value here so the public constant
+        // and the spec stay in lockstep.
+        assert_eq!(ALIGNED_UNIT_LEN, 6144);
+        assert_eq!(ALIGNED_UNIT_LEN, 3 * 2048);
+    }
+
+    #[test]
+    fn version_strides_are_reexported_and_distinct() {
+        // The three AACS generations are part of the public surface, and the
+        // V10 (48) vs V20/V21 (64) stride distinction is the load-bearing
+        // difference. Confirm the enum re-export is usable and the variants
+        // are distinct values.
+        assert_ne!(AacsVersion::V10, AacsVersion::V20);
+        assert_ne!(AacsVersion::V20, AacsVersion::V21);
+    }
+
+    #[test]
+    fn key_correction_data_placeholder_is_all_zero() {
+        // The variant chain refuses to run against this all-zero placeholder
+        // KCD; the public constant must therefore be exactly 16 zero bytes.
+        assert_eq!(KEY_CORRECTION_DATA_PLACEHOLDER, [0u8; 16]);
+    }
+
+    #[test]
+    fn public_helpers_are_callable_through_the_facade() {
+        // Touch a representative function from each re-export group so a
+        // dropped/renamed export fails to compile. These are smoke calls, not
+        // behavioural assertions (behaviour is covered in each module).
+        let _ = ts_sync_destroyed(&[0u8; ALIGNED_UNIT_LEN]);
+        let _ = mkb_content_len(&[]);
+        let _ = is_variant_mkb(&walk_mkb(&[]));
+        let _ = disc_hash_hex(&disc_hash(b"x"));
+        let _ = mk_from_pk(&[[0u8; 16]], &[]);
+    }
+}

src/aacs/provider.rs

@@ -0,0 +1,409 @@
+//! 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::types::{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()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn entry(hash: &str, vuk: u8) -> DiscEntry {
+        DiscEntry {
+            disc_hash: hash.to_string(),
+            title: "t".to_string(),
+            media_key: None,
+            disc_id: None,
+            vuk: Some([vuk; 16]),
+            unit_keys: Vec::new(),
+        }
+    }
+
+    fn dk(byte: u8, node: u16) -> DeviceKey {
+        DeviceKey {
+            key: [byte; 16],
+            node,
+            uv: 1,
+            u_mask_shift: 0,
+        }
+    }
+
+    /// A provider that returns fixed bulk material and an optional disc entry
+    /// keyed unconditionally (used to test array-order short-circuiting).
+    #[derive(Default)]
+    struct Fixed {
+        dks: Vec<DeviceKey>,
+        pks: Vec<[u8; 16]>,
+        mks: Vec<[u8; 16]>,
+        hash_hit: Option<DiscEntry>,
+        vid_hit: Option<DiscEntry>,
+    }
+    impl KeyProvider for Fixed {
+        fn device_keys(&self) -> Vec<DeviceKey> {
+            self.dks.clone()
+        }
+        fn processing_keys(&self) -> Vec<[u8; 16]> {
+            self.pks.clone()
+        }
+        fn media_keys(&self) -> Vec<[u8; 16]> {
+            self.mks.clone()
+        }
+        fn lookup_disc_by_hash(&self, _h: &[u8; 20]) -> Option<DiscEntry> {
+            self.hash_hit.clone()
+        }
+        fn lookup_disc_by_vid(&self, _v: &[u8; 16]) -> Option<DiscEntry> {
+            self.vid_hit.clone()
+        }
+    }
+
+    // ── KeyProvider default methods all return empty ───────────────────────
+
+    #[test]
+    fn default_provider_methods_return_empty() {
+        // A bare provider that overrides nothing must yield empty material so
+        // the resolver simply finds nothing through it (no surprise hits).
+        struct Empty;
+        impl KeyProvider for Empty {}
+        let e = Empty;
+        assert!(e.device_keys().is_empty());
+        assert!(e.processing_keys().is_empty());
+        assert!(e.media_keys().is_empty());
+        assert!(e.host_certs().is_empty());
+        assert!(e.lookup_disc_by_hash(&[0u8; 20]).is_none());
+        assert!(e.lookup_disc_by_vid(&[0u8; 16]).is_none());
+    }
+
+    // ── Providers::processing_keys: union + dedup ──────────────────────────
+
+    #[test]
+    fn providers_processing_keys_union_and_dedup() {
+        // Two providers each carrying overlapping PKs → the aggregate is the
+        // deduped union (the resolver must not re-validate identical material).
+        let a = Fixed {
+            pks: vec![[0x01u8; 16], [0x02u8; 16]],
+            ..Default::default()
+        };
+        let b = Fixed {
+            pks: vec![[0x02u8; 16], [0x03u8; 16]],
+            ..Default::default()
+        };
+        let arr: &[&dyn KeyProvider] = &[&a, &b];
+        let mut got = Providers(arr).processing_keys();
+        got.sort();
+        assert_eq!(got, vec![[0x01u8; 16], [0x02u8; 16], [0x03u8; 16]]);
+    }
+
+    #[test]
+    fn providers_media_keys_union_and_dedup() {
+        let a = Fixed {
+            mks: vec![[0xAAu8; 16]],
+            ..Default::default()
+        };
+        let b = Fixed {
+            mks: vec![[0xAAu8; 16], [0xBBu8; 16]],
+            ..Default::default()
+        };
+        let arr: &[&dyn KeyProvider] = &[&a, &b];
+        let mut got = Providers(arr).media_keys();
+        got.sort();
+        assert_eq!(got, vec![[0xAAu8; 16], [0xBBu8; 16]]);
+    }
+
+    #[test]
+    fn providers_device_keys_dedup_on_value_tuple() {
+        // DeviceKey has no Hash/Ord; dedup keys on (key,node,uv,u_mask_shift).
+        // Two identical DKs across providers collapse to one; a DK differing
+        // only in node is kept.
+        let a = Fixed {
+            dks: vec![dk(0x11, 5), dk(0x11, 5)],
+            ..Default::default()
+        };
+        let b = Fixed {
+            dks: vec![dk(0x11, 5), dk(0x11, 6)],
+            ..Default::default()
+        };
+        let arr: &[&dyn KeyProvider] = &[&a, &b];
+        let got = Providers(arr).device_keys();
+        assert_eq!(got.len(), 2, "identical DKs dedup; differing node kept");
+        let nodes: Vec<u16> = got.iter().map(|d| d.node).collect();
+        assert!(nodes.contains(&5) && nodes.contains(&6));
+    }
+
+    // ── Disc-keyed lookups: array-order short-circuit ──────────────────────
+
+    #[test]
+    fn providers_lookup_by_hash_first_hit_wins() {
+        // Querying providers in array order, the FIRST hit wins (closest /
+        // fastest first). Provider 0 hits → its entry is returned even though
+        // provider 1 also has one.
+        let a = Fixed {
+            hash_hit: Some(entry("first", 0x01)),
+            ..Default::default()
+        };
+        let b = Fixed {
+            hash_hit: Some(entry("second", 0x02)),
+            ..Default::default()
+        };
+        let arr: &[&dyn KeyProvider] = &[&a, &b];
+        let got = Providers(arr).lookup_disc_by_hash(&[0u8; 20]).unwrap();
+        assert_eq!(got.disc_hash, "first");
+        assert_eq!(got.vuk, Some([0x01u8; 16]));
+    }
+
+    #[test]
+    fn providers_lookup_by_hash_falls_through_to_later_provider() {
+        // Provider 0 misses, provider 1 hits → the later provider's entry is
+        // used (find_map continues past None).
+        let a = Fixed::default(); // hash_hit None
+        let b = Fixed {
+            hash_hit: Some(entry("second", 0x02)),
+            ..Default::default()
+        };
+        let arr: &[&dyn KeyProvider] = &[&a, &b];
+        let got = Providers(arr).lookup_disc_by_hash(&[0u8; 20]).unwrap();
+        assert_eq!(got.disc_hash, "second");
+    }
+
+    #[test]
+    fn providers_lookup_by_vid_first_hit_wins() {
+        let a = Fixed {
+            vid_hit: Some(entry("vid-a", 0x07)),
+            ..Default::default()
+        };
+        let b = Fixed {
+            vid_hit: Some(entry("vid-b", 0x08)),
+            ..Default::default()
+        };
+        let arr: &[&dyn KeyProvider] = &[&a, &b];
+        let got = Providers(arr).lookup_disc_by_vid(&[0u8; 16]).unwrap();
+        assert_eq!(got.disc_hash, "vid-a");
+    }
+
+    #[test]
+    fn providers_empty_array_yields_nothing() {
+        let arr: &[&dyn KeyProvider] = &[];
+        let p = Providers(arr);
+        assert!(p.device_keys().is_empty());
+        assert!(p.processing_keys().is_empty());
+        assert!(p.media_keys().is_empty());
+        assert!(p.lookup_disc_by_hash(&[0u8; 20]).is_none());
+        assert!(p.lookup_disc_by_vid(&[0u8; 16]).is_none());
+    }
+
+    // ── SuppliedKey: each level exposes only its own material ──────────────
+
+    #[test]
+    fn supplied_key_exposes_only_populated_fields() {
+        // A SuppliedKey filled at the DK level exposes DKs and nothing else,
+        // so the resolver runs the matching (DK→…) path and no other.
+        let sk = SuppliedKey {
+            device_keys: vec![dk(0x33, 9)],
+            processing_keys: Vec::new(),
+            media_keys: Vec::new(),
+            disc_entry: None,
+        };
+        assert_eq!(sk.device_keys().len(), 1);
+        assert!(sk.processing_keys().is_empty());
+        assert!(sk.media_keys().is_empty());
+        assert!(sk.lookup_disc_by_hash(&[0u8; 20]).is_none());
+        assert!(sk.lookup_disc_by_vid(&[0u8; 16]).is_none());
+    }
+
+    #[test]
+    fn supplied_key_disc_entry_returned_for_any_hash_or_vid() {
+        // decrypt_with already knows the disc, so a present disc_entry is
+        // returned regardless of the hash/VID argument (the lookup args are
+        // irrelevant in this bridge).
+        let sk = SuppliedKey {
+            device_keys: Vec::new(),
+            processing_keys: Vec::new(),
+            media_keys: Vec::new(),
+            disc_entry: Some(entry("supplied", 0x44)),
+        };
+        // Two unrelated hashes both return the same entry.
+        let h1 = sk.lookup_disc_by_hash(&[0x01u8; 20]).unwrap();
+        let h2 = sk.lookup_disc_by_hash(&[0xFFu8; 20]).unwrap();
+        assert_eq!(h1.disc_hash, "supplied");
+        assert_eq!(h2.disc_hash, "supplied");
+        // And by VID likewise.
+        assert!(sk.lookup_disc_by_vid(&[0x00u8; 16]).is_some());
+    }
+}

src/aacs/trace.rs

@@ -0,0 +1,144 @@
+//! Structured resolution trace — what the unlock + key-resolution attempt did.
+//!
+//! No user-facing English. Every step's STATE is a typed enum variant;
+//! applications RENDER these into localized text (the library never does). This
+//! module only DEFINES the shape and is wired through the resolve/handshake
+//! return path far enough to compile.
+//!
+//! The `who` of each step is the source's `label()` / unlocker's `name()` — a
+//! stable identifier string (a NAME, like a codec id, NOT user-facing prose),
+//! carried verbatim so an app renderer never has to match an enum back to a name
+//! it already has. Only the OUTCOME / path enums are structured states the app
+//! maps to i18n English.
+
+/// The full trace of a resolution attempt: the unlock phase, then the
+/// key-resolution phase.
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct ResolutionTrace {
+    /// One step per unlocker consulted, in consultation order.
+    pub unlock: Vec<UnlockStep>,
+    /// One step per key source consulted, in consultation order.
+    pub keys: Vec<KeyStep>,
+}
+
+impl ResolutionTrace {
+    /// An empty trace (no steps recorded).
+    pub fn new() -> Self {
+        Self::default()
+    }
+}
+
+// ── Unlock phase ────────────────────────────────────────────────────────────
+
+/// One unlocker's contribution to the unlock phase. `who` is the unlocker's
+/// `name()` (a stable, product-neutral identifier), carried verbatim.
+#[derive(Debug, Clone, PartialEq)]
+pub struct UnlockStep {
+    pub who: String,
+    pub outcome: UnlockOutcome,
+}
+
+/// What an unlocker did.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum UnlockOutcome {
+    /// The drive was unlocked (or already usable) and a VID is available.
+    Unlocked,
+    /// This unlocker cannot unlock this drive's firmware.
+    FirmwareNotUnlockable,
+    /// No non-revoked host cert was usable for the auth attempt. `mkb` is the
+    /// disc MKB generation when known.
+    NoUsableHostCert { mkb: Option<u32> },
+    /// Every available host cert was revoked on this drive's HRL. `mkb` is the
+    /// disc MKB generation when known.
+    CertRevoked { mkb: Option<u32> },
+    /// The drive rejected the auth handshake (non-revocation rejection / wedge).
+    HandshakeRejected,
+    /// Auth succeeded (or was skipped) but the Volume ID could not be read.
+    VidUnavailable,
+}
+
+// ── Key-resolution phase ────────────────────────────────────────────────────
+
+/// One key source's contribution to the key-resolution phase, including the
+/// derivation path it walked. `who` is the source's `label()` (a stable
+/// identifier, e.g. `"keydb"` / `"online"`), carried verbatim.
+#[derive(Debug, Clone, PartialEq)]
+pub struct KeyStep {
+    pub who: String,
+    pub path: Vec<KeyNode>,
+    pub outcome: KeyOutcome,
+}
+
+/// A node on the derivation path a source walked. Ordered as encountered; not
+/// every path hits every node.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum KeyNode {
+    /// The source matched this disc (by hash / VID).
+    MatchedDisc,
+    /// The source had no entry for this disc.
+    NoEntry,
+    /// Pre-decrypted unit keys were found.
+    FoundUnitKeys,
+    /// A VUK was found.
+    FoundVuk,
+    /// A Media Key was found.
+    FoundMediaKey,
+    /// A VID is required to proceed.
+    NeedVid,
+    /// The VID came from the unlock phase.
+    VidFromUnlock,
+    /// The VID came from the keydb entry.
+    VidFromKeydb,
+    /// No VID was available.
+    NoVid,
+    /// A VUK was derived (from MK + VID).
+    DerivedVuk,
+    /// Unit keys were derived (from VUK).
+    DerivedUnitKeys,
+}
+
+/// The terminal outcome of a source's resolution attempt.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum KeyOutcome {
+    /// Usable unit keys were produced.
+    Resolved,
+    /// Derivation material existed but no VID was available to finish.
+    MissingVid,
+    /// No usable key from this source.
+    NoKey,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The trace types are constructible, derive the required traits, and an
+    /// empty trace round-trips. Pins the structural contract apps build against.
+    #[test]
+    fn trace_is_constructible_and_comparable() {
+        let t = ResolutionTrace {
+            unlock: vec![UnlockStep {
+                who: "AACS cert".to_string(),
+                outcome: UnlockOutcome::NoUsableHostCert { mkb: Some(68) },
+            }],
+            keys: vec![KeyStep {
+                who: "keydb".to_string(),
+                path: vec![
+                    KeyNode::MatchedDisc,
+                    KeyNode::FoundVuk,
+                    KeyNode::DerivedUnitKeys,
+                ],
+                outcome: KeyOutcome::Resolved,
+            }],
+        };
+        // Clone + PartialEq (derive contract the renderers rely on).
+        assert_eq!(t.clone(), t);
+        // `who` is the source's name carried verbatim.
+        assert_eq!(t.keys[0].who, "keydb");
+        assert_eq!(t.unlock[0].who, "AACS cert");
+        // Default / new is empty.
+        assert_eq!(ResolutionTrace::new(), ResolutionTrace::default());
+        assert!(ResolutionTrace::new().unlock.is_empty());
+        assert!(ResolutionTrace::new().keys.is_empty());
+    }
+}

src/aacs/types.rs

@@ -0,0 +1,45 @@
+//! AACS primitive types shared across the resolve chain.
+//!
+//! These structs describe AACS key material (device keys, host
+//! certificates, per-disc entries). They carry no parsing logic — the
+//! keydb.cfg format lives in the `freemkv-keysources` crate. libfreemkv
+//! owns only the crypto and these value types that flow through it.
+
+/// 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])>,
+}

src/aacs/variants.rs

@@ -14,6 +14,19 @@
 //! 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
@@ -28,9 +41,22 @@
 //! 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;
+use super::types::DeviceKey;
 
 // ── Public constants ──────────────────────────────────────────────────────
 
@@ -62,29 +88,44 @@ pub struct MkbRecord {
 /// 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() {
+    mkb_records(mkb)
+        .map(|(offset, rec_type, rec_len)| MkbRecord {
+            offset,
+            rec_type,
+            rec_len,
+            body: mkb[offset + 4..offset + rec_len].to_vec(),
+        })
+        .collect()
+}
+
+/// THE single MKB record-framing walker: yields `(offset, rec_type, rec_len)`
+/// for each record — a 4-byte header (type byte + big-endian 24-bit length)
+/// then the body — stopping at the `00 000000` end marker or a
+/// malformed/out-of-bounds length. Lazy (no body clone), so a find-one-record
+/// caller never materialises the multi-MB cvalue table. [`walk_mkb`] and every
+/// MKB record walk in `aacs::keys` are built on this, so the framing rules — and
+/// any future fix to them — live in exactly one place (they had drifted across
+/// six hand-rolled copies).
+pub(crate) fn mkb_records(mkb: &[u8]) -> impl Iterator<Item = (usize, u8, usize)> + '_ {
+    let mut pos = 0usize;
+    std::iter::from_fn(move || {
+        if pos + 4 > mkb.len() {
+            return None;
+        }
         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;
+            return None;
         }
         if rec_len < 4 || pos + rec_len > mkb.len() {
-            break;
+            return None;
         }
-        let body = mkb[pos + 4..pos + rec_len].to_vec();
-        out.push(MkbRecord {
-            offset: pos,
-            rec_type,
-            rec_len,
-            body,
-        });
+        let here = pos;
         pos += rec_len;
-    }
-    out
+        Some((here, rec_type, rec_len))
+    })
 }
 
 /// True iff `records` contains at least one Media Key Variant record
@@ -94,7 +135,13 @@ pub fn is_variant_mkb(records: &[MkbRecord]) -> bool {
 }
 
 /// Body of the Encrypted Media Key Variant Data record (type `0x82`).
-pub fn variant_data_record(records: &[MkbRecord]) -> Option<&[u8]> {
+///
+/// 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)
@@ -115,7 +162,11 @@ pub fn variant_nonce(records: &[MkbRecord]) -> Option<[u8; 16]> {
 
 /// Body of the Variant Key Data record. Returns the first `0x82` body
 /// that is a non-empty multiple of 16 bytes.
-pub fn variant_key_data(records: &[MkbRecord]) -> Option<&[u8]> {
+///
+/// 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)
@@ -141,56 +192,11 @@ fn aes_g(x1: &[u8; 16], x2: &[u8; 16]) -> [u8; 16] {
 
 // ── 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;
-
-    while current_v_mask != v_mask {
-        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
-}
+// `calc_v_mask` and `calc_pk_from_dk` (and the AES-G3 seed step they ride
+// on) are shared with the classical walk in [`super::keys`] — a single
+// definition keeps the variant SD tree byte-identical to the classical one.
+// (`aesg3` itself is imported separately in the test module.)
+use super::keys::{calc_pk_from_dk, calc_v_mask};
 
 /// Outcome of a subset-difference walk against an MKB. Carries the
 /// processing key and the matching `uv` slot — both needed as inputs
@@ -225,6 +231,27 @@ fn mkb_find_mk_dv(records: &[MkbRecord]) -> Option<[u8; 16]> {
 
 /// Walk an MKB and return the first `(Kp, uv, cvalue)` that
 /// `device_keys` covers. Returns `None` if no DK walks any uv.
+///
+/// This is the AACS-2.1 **variant** walk; the classical walk lives in
+/// [`super::keys::derive_media_key_and_pk_from_dk`]. The two are kept
+/// separate on purpose and select MKB records in DELIBERATELY different
+/// order:
+///
+///   - cvalues: this variant walk tries record `0x07`-then-`0x05`; the
+///     classical walk tries `0x05`-then-`0x07`. On a variant MKB the
+///     small `0x07` Explicit-Subset-Difference record carries the
+///     cvalue the Precursor chain consumes, whereas a classical UHD MKB
+///     keeps its 1:1 cvalue table in the large `0x05` record (see the
+///     note on [`super::keys::probe::mkb_cvalues`]). They must NOT be
+///     unified to one order — each is correct for its own MKB shape.
+///   - finders: this walk operates on parsed [`MkbRecord`]s (needed
+///     because the variant chain also reads `0x82`/`0x83`); the
+///     classical walk operates on raw MKB bytes. Same framing, different
+///     input type.
+///
+/// Consequence: do NOT route the classical DK path through this function
+/// — on a classical MKB the `0x07`-first selection picks the wrong (or
+/// missing) cvalue and the magic check fails, so it returns `None`.
 pub fn walk_processing_key(
     records: &[MkbRecord],
     device_keys: &[DeviceKey],
@@ -243,11 +270,23 @@ pub fn walk_processing_key(
 
         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 {
@@ -260,6 +299,11 @@ pub fn walk_processing_key(
             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);
 
@@ -334,6 +378,10 @@ pub enum MediaKeyVariantError {
     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 {
@@ -347,6 +395,7 @@ impl std::fmt::Display for MediaKeyVariantError {
             MediaKeyVariantError::KcdNotProvided => 7105,
             MediaKeyVariantError::VariantsTableUnavailable => 7106,
             MediaKeyVariantError::VkdIndexOutOfRange => 7107,
+            MediaKeyVariantError::MediaKeyVerifyFailed => 7108,
         };
         write!(f, "E{code}")
     }
@@ -356,11 +405,15 @@ impl std::error::Error for MediaKeyVariantError {}
 
 // ── Chain ─────────────────────────────────────────────────────────────────
 
-/// Look up `VARIANTS[uv]` for the matched uv. The byte layout of the
-/// per-uv slot in the Variant Number record is undocumented and is
-/// disc-specific; this helper returns `None` until a Variant disc is
-/// available to fix the layout against.
-fn variants_for_uv(_records: &[MkbRecord], _uv_index: usize) -> Option<u16> {
+/// 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
 }
 
@@ -377,6 +430,12 @@ fn variants_for_uv(_records: &[MkbRecord], _uv_index: usize) -> Option<u16> {
 ///   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],
@@ -446,6 +505,17 @@ pub fn derive_media_key_variant(
         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);
 
@@ -455,6 +525,23 @@ pub fn derive_media_key_variant(
 #[cfg(test)]
 mod tests {
     use super::*;
+    // These three live in `super::keys` now (consolidated SD-walk helpers);
+    // `use super::*` does not re-export the parent module's private `use`
+    // imports, so pull them in directly for the tests below.
+    use super::super::keys::{aesg3, calc_pk_from_dk};
+
+    #[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 ──
 
@@ -575,6 +662,7 @@ mod tests {
             MediaKeyVariantError::KcdNotProvided,
             MediaKeyVariantError::VariantsTableUnavailable,
             MediaKeyVariantError::VkdIndexOutOfRange,
+            MediaKeyVariantError::MediaKeyVerifyFailed,
         ];
         for e in cases {
             let s = e.to_string();
@@ -605,7 +693,7 @@ mod tests {
     ///   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).
+    ///   times — Kp = aesg3(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
@@ -626,14 +714,14 @@ mod tests {
         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 (==1), dev_key_v_mask
+        // 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).
+        // no-op — Kp = aesg3(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);
+        let kp = aesg3(&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.
@@ -676,4 +764,282 @@ mod tests {
         };
         (recs, dk, kp, kmp)
     }
+
+    // ════════════════════════════════════════════════════════════════════
+    // Hardening additions
+    // ════════════════════════════════════════════════════════════════════
+
+    // ── walk_mkb framing: BE24 length incl. header, end markers ────────────
+
+    #[test]
+    fn walk_mkb_reports_offsets_and_be24_lengths() {
+        // Two records; the walker must report each record's byte offset and
+        // its full length (header + body). rec_len is the 3-byte BE field at
+        // bytes 1..4, and INCLUDES the 4-byte header.
+        let mut mkb = vec![0x10, 0x00, 0x00, 0x06, 0xAA, 0xBB]; // len 6 (2-byte body)
+        mkb.extend_from_slice(&[0x05, 0x00, 0x00, 0x08, 1, 2, 3, 4]); // len 8
+        let recs = walk_mkb(&mkb);
+        assert_eq!(recs.len(), 2);
+        assert_eq!(recs[0].offset, 0);
+        assert_eq!(recs[0].rec_len, 6);
+        assert_eq!(recs[0].body, vec![0xAA, 0xBB]);
+        assert_eq!(recs[1].offset, 6);
+        assert_eq!(recs[1].rec_len, 8);
+        assert_eq!(recs[1].body, vec![1, 2, 3, 4]);
+    }
+
+    #[test]
+    fn mkb_records_matches_walk_mkb_framing() {
+        // The lazy `mkb_records` iterator and the owning `walk_mkb` must agree on
+        // (offset, type, len) for every record — they share the one framing
+        // walker, and every keys.rs MKB walk now relies on this equivalence.
+        let mut mkb = vec![0x10, 0x00, 0x00, 0x06, 0xAA, 0xBB];
+        mkb.extend_from_slice(&[0x05, 0x00, 0x00, 0x08, 1, 2, 3, 4]);
+        mkb.extend_from_slice(&[0x00, 0x00, 0x00, 0x00, 0xFF]); // terminator + trailing
+        let owned: Vec<(usize, u8, usize)> = walk_mkb(&mkb)
+            .iter()
+            .map(|r| (r.offset, r.rec_type, r.rec_len))
+            .collect();
+        let lazy: Vec<(usize, u8, usize)> = mkb_records(&mkb).collect();
+        assert_eq!(lazy, owned);
+        assert_eq!(lazy, vec![(0, 0x10, 6), (6, 0x05, 8)]);
+    }
+
+    #[test]
+    fn walk_mkb_be24_high_byte_is_honored() {
+        // A record longer than 255 bytes needs the high BE24 byte. Build a
+        // 0x10 record of total length 0x000110 (272) and confirm the body is
+        // 268 bytes (a parser that read only the low byte would see len 0x10).
+        let total = 0x0110usize; // 272
+        let mut mkb = vec![0x10, 0x00, 0x01, 0x10];
+        mkb.resize(total, 0xAB);
+        let recs = walk_mkb(&mkb);
+        assert_eq!(recs.len(), 1);
+        assert_eq!(recs[0].rec_len, total);
+        assert_eq!(recs[0].body.len(), total - 4);
+    }
+
+    #[test]
+    fn walk_mkb_stops_at_type0_len0_end_marker() {
+        // A (type=0, len=0) record ends the walk; trailing bytes after it are
+        // not parsed.
+        let mut mkb = vec![0x10, 0x00, 0x00, 0x06, 0xAA, 0xBB];
+        mkb.extend_from_slice(&[0x00, 0x00, 0x00, 0x00]); // end marker
+        mkb.extend_from_slice(&[0x05, 0x00, 0x00, 0x08, 9, 9, 9, 9]); // ignored
+        let recs = walk_mkb(&mkb);
+        assert_eq!(recs.len(), 1);
+        assert_eq!(recs[0].rec_type, 0x10);
+    }
+
+    #[test]
+    fn walk_mkb_stops_on_overrun_record() {
+        // rec_len running past the buffer ends the walk after the records that
+        // fit (no OOB, no partial body past the end).
+        let mut mkb = vec![0x10, 0x00, 0x00, 0x06, 0xAA, 0xBB];
+        mkb.extend_from_slice(&[0x05, 0x00, 0xFF, 0xFF]); // claims 65535 bytes
+        let recs = walk_mkb(&mkb);
+        assert_eq!(recs.len(), 1, "overrun record must be dropped");
+    }
+
+    #[test]
+    fn walk_mkb_stops_on_sub_4_length() {
+        // A non-zero type with rec_len < 4 (and not the 0/0 marker) breaks the
+        // walk — otherwise pos would not advance (infinite loop guard).
+        let mkb = vec![0x10, 0x00, 0x00, 0x02, 0xAA];
+        assert!(walk_mkb(&mkb).is_empty());
+    }
+
+    #[test]
+    fn walk_mkb_handles_trailing_partial_header() {
+        // Fewer than 4 bytes left → loop condition `pos + 4 <= len` stops.
+        let mkb = vec![0x10, 0x00, 0x00, 0x06, 0xAA, 0xBB, 0x05, 0x00]; // 2 trailing
+        let recs = walk_mkb(&mkb);
+        assert_eq!(recs.len(), 1);
+    }
+
+    // ── Record selectors ───────────────────────────────────────────────────
+
+    #[test]
+    fn is_variant_mkb_true_for_0x82_alone_and_0x83_alone() {
+        // Either record type alone flags the MKB as variant.
+        let only82 = walk_mkb(&{
+            let mut m = vec![0x10, 0x00, 0x00, 0x08, 0, 0, 0, 0];
+            m.extend_from_slice(&[0x82, 0x00, 0x00, 0x14]);
+            m.extend_from_slice(&[0xEE; 16]);
+            m
+        });
+        assert!(is_variant_mkb(&only82));
+        let only83 = walk_mkb(&{
+            let mut m = vec![0x10, 0x00, 0x00, 0x08, 0, 0, 0, 0];
+            m.extend_from_slice(&[0x83, 0x00, 0x00, 0x14]);
+            m.extend_from_slice(&[0x55; 16]);
+            m
+        });
+        assert!(is_variant_mkb(&only83));
+    }
+
+    #[test]
+    fn variant_nonce_requires_16_byte_body() {
+        // A 0x83 record with < 16-byte body → None (no panic on the copy).
+        let recs = walk_mkb(&{
+            let mut m = vec![0x83, 0x00, 0x00, 0x0C]; // 8-byte body
+            m.extend_from_slice(&[0x11; 8]);
+            m
+        });
+        assert_eq!(variant_nonce(&recs), None);
+    }
+
+    #[test]
+    fn variant_key_data_requires_nonempty_multiple_of_16() {
+        // A 0x82 body that is NOT a multiple of 16 is rejected by
+        // variant_key_data (it needs whole 16-byte VKD slots).
+        let recs = walk_mkb(&{
+            let mut m = vec![0x82, 0x00, 0x00, 0x0E]; // 10-byte body (not %16)
+            m.extend_from_slice(&[0x22; 10]);
+            m
+        });
+        assert_eq!(variant_key_data(&recs), None);
+        // variant_data_record returns the body regardless of length.
+        assert_eq!(variant_data_record(&recs), Some(&[0x22u8; 10][..]));
+    }
+
+    // ── derive_media_key_variant: missing-record classification ────────────
+
+    #[test]
+    fn chain_reports_processing_key_unavailable_with_no_dks() {
+        // A complete variant MKB but an empty device-key pool → no uv covered
+        // → ProcessingKeyUnavailable (the walk_processing_key None branch).
+        let (recs, _dk, _, _) = synthetic_variant_setup(0x00);
+        let err = derive_media_key_variant(&recs, &[], &[0xAA; 16], &[0u8; 16])
+            .expect_err("no DK → ProcessingKeyUnavailable");
+        assert_eq!(err, MediaKeyVariantError::ProcessingKeyUnavailable);
+    }
+
+    #[test]
+    fn chain_reports_mkb_incomplete_when_nonce_missing() {
+        // Build a variant MKB (has 0x82 so is_variant true, and a DK can walk
+        // it) but WITHOUT a 0x83 nonce record → MkbIncomplete at the
+        // variant_nonce `?`.
+        // Start from the full setup, then rebuild the byte stream dropping
+        // the 0x83 record.
+        let (recs, dk, _, _) = synthetic_variant_setup(0x00);
+        // Reconstruct bytes without the 0x83 record.
+        let mut mkb = Vec::new();
+        for r in &recs {
+            if r.rec_type == 0x83 {
+                continue;
+            }
+            mkb.push(r.rec_type);
+            mkb.push(((r.rec_len >> 16) & 0xFF) as u8);
+            mkb.push(((r.rec_len >> 8) & 0xFF) as u8);
+            mkb.push((r.rec_len & 0xFF) as u8);
+            mkb.extend_from_slice(&r.body);
+        }
+        let recs2 = walk_mkb(&mkb);
+        assert!(is_variant_mkb(&recs2), "still variant via 0x82");
+        let err = derive_media_key_variant(&recs2, &[dk], &[0xAA; 16], &[0u8; 16])
+            .expect_err("missing nonce → MkbIncomplete");
+        assert_eq!(err, MediaKeyVariantError::MkbIncomplete);
+    }
+
+    // ── walk_processing_key: skips out-of-range u_mask_shift ───────────────
+
+    #[test]
+    fn walk_processing_key_skips_shift_32_to_63_without_panic() {
+        // A subset-difference u_mask_shift in 0x20..=0x3F passes the 0xC0
+        // revoke check but is out of range for a u32 shift. The walk must skip
+        // the slot (continue) and not panic / not match a wrong uv. With only
+        // that one bad slot, no match → None.
+        let mut mkb = vec![
+            0x10, 0x00, 0x00, 0x0C, 0x48, 0x14, 0x10, 0x03, 0x00, 0x00, 0x00, 0x4D,
+        ];
+        // 0x04: u_mask_shift=0x20 (32), uv=2.
+        mkb.extend_from_slice(&[0x04, 0x00, 0x00, 0x09]);
+        mkb.extend_from_slice(&[0x20, 0x00, 0x00, 0x00, 0x02]);
+        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]);
+        let recs = walk_mkb(&mkb);
+        let dk = DeviceKey {
+            key: [0x11; 16],
+            node: 4,
+            uv: 2,
+            u_mask_shift: 3,
+        };
+        assert!(
+            walk_processing_key(&recs, &[dk]).is_none(),
+            "out-of-range shift must be skipped, yielding no match"
+        );
+    }
+
+    #[test]
+    fn walk_processing_key_skips_uv_zero() {
+        // A uv == 0 slot is skipped (`if uv == 0 { continue }`). With only a
+        // zero-uv slot present, no DK can match → None.
+        let mut mkb = vec![
+            0x10, 0x00, 0x00, 0x0C, 0x48, 0x14, 0x10, 0x03, 0x00, 0x00, 0x00, 0x4D,
+        ];
+        mkb.extend_from_slice(&[0x04, 0x00, 0x00, 0x09]);
+        mkb.extend_from_slice(&[0x03, 0x00, 0x00, 0x00, 0x00]); // uv = 0
+        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]);
+        let recs = walk_mkb(&mkb);
+        let dk = DeviceKey {
+            key: [0x11; 16],
+            node: 4,
+            uv: 2,
+            u_mask_shift: 3,
+        };
+        assert!(walk_processing_key(&recs, &[dk]).is_none());
+    }
+
+    #[test]
+    fn walk_processing_key_returns_match_on_variant_mkb_without_magic() {
+        // On a variant MKB the per-match VERIFY_MAGIC check does not hold, but
+        // the walk still returns the (Kp, uv) match because variant_present is
+        // true. The synthetic_variant_setup fixture is exactly this case.
+        let (recs, dk, planted_kp, _) = synthetic_variant_setup(0x00);
+        let m = walk_processing_key(&recs, &[dk]).expect("variant MKB yields a match");
+        assert_eq!(m.uv, 2, "matched the planted uv");
+        assert_eq!(m.kp, planted_kp, "Kp equals aesg3(dk,1) for the no-op walk");
+        assert_eq!(m.cvalue_index, 0);
+    }
+
+    #[test]
+    fn aes_g_matches_decrypt_xor_relation() {
+        // AES-G(x1,x2) = AES-128D(x1,x2) XOR x2 — the same form as derive_vuk.
+        // Pin it explicitly so a dropped XOR or an encrypt-instead-of-decrypt
+        // is caught.
+        let x1 = [0x31u8; 16];
+        let x2 = [0x9Fu8; 16];
+        let mut expected = aes_ecb_decrypt(&x1, &x2);
+        for i in 0..16 {
+            expected[i] ^= x2[i];
+        }
+        assert_eq!(aes_g(&x1, &x2), expected);
+    }
+
+    #[test]
+    fn error_codes_are_unique_and_in_7100_range() {
+        // Each MediaKeyVariantError maps to a distinct E71xx code. A
+        // copy-paste collision (two variants sharing a code) would break
+        // operator triage; assert all nine are distinct.
+        use std::collections::HashSet;
+        let cases = [
+            MediaKeyVariantError::NotVariantMkb,
+            MediaKeyVariantError::MkbIncomplete,
+            MediaKeyVariantError::ProcessingKeyUnavailable,
+            MediaKeyVariantError::SoftCorrectionRequired,
+            MediaKeyVariantError::OnlineChallengeRequired,
+            MediaKeyVariantError::KcdNotProvided,
+            MediaKeyVariantError::VariantsTableUnavailable,
+            MediaKeyVariantError::VkdIndexOutOfRange,
+            MediaKeyVariantError::MediaKeyVerifyFailed,
+        ];
+        let codes: HashSet<String> = cases.iter().map(|e| e.to_string()).collect();
+        assert_eq!(codes.len(), cases.len(), "all error codes must be unique");
+    }
 }

src/aacs/verify_magics.rs

@@ -1,172 +0,0 @@
-//! AACS Verify-Media-Key magic constants used to confirm Media Key
-//! candidates produced during MKB walking.
-//!
-//! AACS MKBs contain "Verify Media Key Records" whose decrypted output
-//! is a known-plaintext constant. Walking code decrypts the verify
-//! record with each MK candidate and compares the result against the
-//! magic; on match, the MK is correct.
-//!
-//! Five distinct magics are observed in the canonical reference AACS
-//! engine (MakeMKV v1.18.3, file offsets in parens):
-//!
-//! 1. **MK\_V10** at `.rodata:0x2909c0`. The original AACS-1.0 spec
-//!    constant. Single 16-byte AES-128-ECB compare. Used at 3 sites in
-//!    that engine. We already use it in `keys.rs::validate_media_key_against_mkb`.
-//!
-//! 2. **MK\_AUX\_16** at `.rodata:0x290890`. A second single-block
-//!    16-byte verification magic. Reverse-engineering of the call site
-//!    at `0x580f73` shows it after a call to the single-block AES-ECB
-//!    helper. Likely a per-vendor or per-record-type extended verify.
-//!    Use it when an MKB carries an extended verify record alongside
-//!    the standard one.
-//!
-//! 3. **MK\_SK\_32a** = `MK_SK32A_BLK0` || `MK_SK32A_BLK1`. A 32-byte
-//!    (2-block) verify magic at `.rodata:0x290910 / 0x290620`. Used at
-//!    `0x580ff0`: both blocks must match after AES-128 decrypt of a
-//!    32-byte verify record. Almost certainly the AACS-2 / Sequence
-//!    Key Block "Verify Media Key Record for Sequence Keys" expanded
-//!    form — i.e. AACS-2 SKB verification.
-//!
-//! 4. **MK\_SK\_32b** = `MK_SK32B_BLK0` || `MK_SK32B_BLK1`. A second
-//!    32-byte verify magic at `.rodata:0x290980 / 0x290a60`. Used at
-//!    `0x581063`. Different record type within the SKB family — likely
-//!    the AACS-2 SD-tree variant verification.
-//!
-//! All five are KNOWN PLAINTEXT compared bit-for-bit against the
-//! AES-128 decrypt output. They are NOT keys. They are oracle values
-//! that say "yes, the MK candidate you tried is the right one."
-//!
-//! Provenance: identified via static RE of MakeMKV v1.18.3 amd64
-//! (binary sha256 `9970a50a97231b2d09d73f521ff1daf0609ea201040a68ecaa9f31af957d6401`)
-//! on 2026-05-22 via objdump of the `pcmpeqb` callsite cluster around
-//! file offset `0x580f70..0x581080`.
-
-/// AACS-1.0 / pre-existing canonical Verify Media Key magic.
-///
-/// `AES-128-ECB-DECRYPT(MK, verify_record) == [VERIFY_MK_V10 || pad]`
-pub const VERIFY_MK_V10: [u8; 8] = [0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF];
-
-/// Single-block 16-byte verify magic (auxiliary). Compared full-16
-/// after AES-128-ECB(MK, in) at `pcmpeqb` site `0x580f73`.
-pub const VERIFY_MK_AUX_16: [u8; 16] = [
-    0xf9, 0x91, 0xa3, 0x60, 0x68, 0x15, 0xa6, 0xb9, 0x55, 0xbb, 0xce, 0xa3, 0xb1, 0x4b, 0xf8, 0xd8,
-];
-
-/// 32-byte SKB-style verify magic, block 0 of 2. Compared full-16
-/// after AES-128 decrypt of the first 16 bytes of a 32-byte verify
-/// record. `pcmpeqb` site `0x580ff0`.
-pub const VERIFY_MK_SK_32A_BLK0: [u8; 16] = [
-    0x19, 0x0f, 0xe9, 0x7f, 0xad, 0x11, 0xa4, 0x10, 0xc6, 0x56, 0x9d, 0x1c, 0x84, 0x21, 0x1d, 0x18,
-];
-
-/// 32-byte SKB-style verify magic, block 1 of 2. Compared full-16
-/// after AES-128 decrypt of bytes 16..32 of the same record.
-/// `pcmpeqb` site `0x580fe8`.
-pub const VERIFY_MK_SK_32A_BLK1: [u8; 16] = [
-    0x9b, 0x54, 0x9a, 0x25, 0x69, 0x8a, 0xa2, 0x3f, 0x9d, 0xfd, 0x2c, 0x95, 0xe2, 0x4a, 0x97, 0x02,
-];
-
-/// 32-byte SKB-style verify magic (variant B), block 0 of 2.
-/// `pcmpeqb` site `0x581063`.
-pub const VERIFY_MK_SK_32B_BLK0: [u8; 16] = [
-    0x8d, 0xee, 0xe0, 0x1e, 0xc7, 0x0c, 0xea, 0xb3, 0xdb, 0xd2, 0xfb, 0x82, 0x16, 0x3c, 0x26, 0x80,
-];
-
-/// 32-byte SKB-style verify magic (variant B), block 1 of 2.
-/// `pcmpeqb` site `0x58105b`.
-pub const VERIFY_MK_SK_32B_BLK1: [u8; 16] = [
-    0xaf, 0x93, 0x7a, 0x74, 0x8a, 0xce, 0xd3, 0x69, 0x36, 0x84, 0xe6, 0xea, 0xf8, 0x54, 0xe8, 0xa2,
-];
-
-/// Tag for a candidate-Media-Key check. Tells the verifier which
-/// known-plaintext to compare against; the verifier chooses the
-/// magic that matches the MKB record type at hand.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum VerifyMagic {
-    /// AACS-1.0 / canonical.
-    V10,
-    /// Auxiliary single-block (16-byte) verification.
-    Aux16,
-    /// SKB-style 32-byte verification, variant A.
-    Sk32A,
-    /// SKB-style 32-byte verification, variant B.
-    Sk32B,
-}
-
-/// Verify a candidate Media Key against a `dec_vd` (AES-128 decrypt
-/// of the MKB Verify Media Key Record under the candidate MK).
-///
-/// Returns `true` if `dec_vd` matches the magic identified by `tag`.
-///
-/// - `V10`: compares the first 8 bytes against `VERIFY_MK_V10`.
-/// - `Aux16`: compares the full 16 bytes against `VERIFY_MK_AUX_16`.
-/// - `Sk32A` / `Sk32B`: `dec_vd` must be exactly 32 bytes (`block0 ||
-///   block1`); compares each block against the corresponding constant.
-pub fn check_verify(tag: VerifyMagic, dec_vd: &[u8]) -> bool {
-    match tag {
-        VerifyMagic::V10 => dec_vd.len() >= 8 && dec_vd[..8] == VERIFY_MK_V10,
-        VerifyMagic::Aux16 => dec_vd.len() >= 16 && dec_vd[..16] == VERIFY_MK_AUX_16,
-        VerifyMagic::Sk32A => {
-            dec_vd.len() >= 32
-                && dec_vd[..16] == VERIFY_MK_SK_32A_BLK0
-                && dec_vd[16..32] == VERIFY_MK_SK_32A_BLK1
-        }
-        VerifyMagic::Sk32B => {
-            dec_vd.len() >= 32
-                && dec_vd[..16] == VERIFY_MK_SK_32B_BLK0
-                && dec_vd[16..32] == VERIFY_MK_SK_32B_BLK1
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn v10_matches_canonical_prefix() {
-        let mut dec = [0u8; 16];
-        dec[..8].copy_from_slice(&VERIFY_MK_V10);
-        assert!(check_verify(VerifyMagic::V10, &dec));
-    }
-
-    #[test]
-    fn aux16_matches_full_block() {
-        assert!(check_verify(VerifyMagic::Aux16, &VERIFY_MK_AUX_16));
-    }
-
-    #[test]
-    fn sk32a_requires_both_blocks() {
-        let mut dec = [0u8; 32];
-        dec[..16].copy_from_slice(&VERIFY_MK_SK_32A_BLK0);
-        dec[16..].copy_from_slice(&VERIFY_MK_SK_32A_BLK1);
-        assert!(check_verify(VerifyMagic::Sk32A, &dec));
-
-        // Mutate block 1, must fail.
-        dec[20] ^= 0x80;
-        assert!(!check_verify(VerifyMagic::Sk32A, &dec));
-    }
-
-    #[test]
-    fn sk32b_distinct_from_sk32a() {
-        let mut dec = [0u8; 32];
-        dec[..16].copy_from_slice(&VERIFY_MK_SK_32B_BLK0);
-        dec[16..].copy_from_slice(&VERIFY_MK_SK_32B_BLK1);
-        assert!(check_verify(VerifyMagic::Sk32B, &dec));
-        // Same plaintext must NOT validate as Sk32A.
-        assert!(!check_verify(VerifyMagic::Sk32A, &dec));
-    }
-
-    #[test]
-    fn short_input_never_matches() {
-        let dec = [0u8; 4];
-        for tag in [
-            VerifyMagic::V10,
-            VerifyMagic::Aux16,
-            VerifyMagic::Sk32A,
-            VerifyMagic::Sk32B,
-        ] {
-            assert!(!check_verify(tag, &dec));
-        }
-    }
-}

src/clpi.rs

@@ -6,22 +6,28 @@
 //!
 //! Reference: https://github.com/lw/BluRay/wiki/CLPI
 
+use crate::consts::{BD_SOURCE_PACKET_BYTES, SECTOR_BYTES_U64};
 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 struct ClipInfo {
     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
+    /// 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
+    /// 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.rs`.
+    /// Cross-validates the MPLS STN view — see `labels/clpi_audit.rs`.
     /// Empty when program_info is missing or malformed.
     pub streams: Vec<ClpiStream>,
 }
@@ -30,57 +36,82 @@ pub struct ClipInfo {
 /// table. Mirrors the same fields the MPLS STN table carries — see
 /// `mpls::StreamEntry` for the playlist-side equivalent.
 #[derive(Debug, Clone)]
-#[allow(dead_code)]
-pub struct ClpiStream {
+pub(crate) struct ClpiStream {
     /// PID of the stream in the MPEG-TS (matches MPLS).
     pub pid: u16,
-    /// SCSI/BD coding type byte (0x80 LPCM, 0x83 TrueHD, 0x86 DTS-HD MA,
+    /// 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 struct EpCoarse {
+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 struct EpFine {
+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.
-    pub fn full_pts(coarse: &EpCoarse, fine: &EpFine) -> u32 {
-        (coarse.pts_coarse << 19) + (fine.pts_fine << 8)
+    ///
+    /// 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 {
-        (coarse.spn_coarse & 0xFFFE_0000) + fine.spn_fine
+        // 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.
-    pub fn resolved_ep_map(&self) -> Vec<(u32, u32)> {
-        let mut entries = Vec::new();
+    ///
+    /// 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;
@@ -98,6 +129,12 @@ impl ClipInfo {
             }
         }
 
+        // 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
     }
 
@@ -105,7 +142,9 @@ impl ClipInfo {
     ///
     /// 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: u32, out_time: u32) -> Vec<Extent> {
+    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();
@@ -122,20 +161,22 @@ impl ClipInfo {
         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 + 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;
+        // SPN → byte offset → sector range. Note: the caller adds the file's
+        // starting LBA from UDF. The start sector FLOORS (the extent begins in
+        // whichever sector contains its first byte) and the end sector CEILS
+        // (the extent must cover through the sector holding its last byte), so
+        // a sub-sector-aligned range still spans every sector it touches.
+        let start_byte = start_spn as u64 * BD_SOURCE_PACKET_BYTES as u64;
+        let end_byte = end_spn as u64 * BD_SOURCE_PACKET_BYTES as u64;
+        let start_sector = (start_byte / SECTOR_BYTES_U64) as u32;
+        let end_sector = end_byte.div_ceil(SECTOR_BYTES_U64) as u32;
 
         vec![Extent {
             start_lba: start_sector, // relative to m2ts file start
@@ -162,7 +203,7 @@ pub fn parse(data: &[u8]) -> Result<ClipInfo> {
 
     // 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() > 56 {
+    let source_packet_count = if data.len() >= 60 {
         u32::from_be_bytes([data[56], data[57], data[58], data[59]])
     } else {
         0
@@ -220,6 +261,7 @@ pub fn parse(data: &[u8]) -> Result<ClipInfo> {
 /// 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> {
+    use crate::consts::coding_type as c;
     let mut out = Vec::new();
     if data.len() < 6 {
         return out;
@@ -258,16 +300,15 @@ fn parse_program_info(data: &[u8]) -> Vec<ClpiStream> {
             let mut language = String::new();
 
             match coding_type {
-                // Video — MPEG-2 (0x02), H.264 (0x1B), HEVC (0x24)
-                0x02 | 0x1B | 0x24 => {
+                // Video — MPEG-2, H.264, HEVC
+                c::MPEG2_VIDEO | c::H264 | c::HEVC => {
                     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 => {
+                // Primary audio — LPCM, AC-3, DTS, TrueHD, AC-3+, DTS-HD HR, DTS-HD MA
+                c::LPCM..=c::DTS_HD_MA => {
                     if sci.len() >= 2 {
                         audio_format = (sci[1] >> 4) & 0x0F;
                         audio_rate = sci[1] & 0x0F;
@@ -276,8 +317,8 @@ fn parse_program_info(data: &[u8]) -> Vec<ClpiStream> {
                         language = String::from_utf8_lossy(&sci[2..5]).to_string();
                     }
                 }
-                // Secondary audio (0xA1 AC-3+, 0xA2 DTS-HD)
-                0xA1 | 0xA2 => {
+                // Secondary audio (AC-3+ secondary, DTS-HD secondary)
+                c::AC3_PLUS_SECONDARY | c::DTS_HD_SECONDARY => {
                     if sci.len() >= 2 {
                         audio_format = (sci[1] >> 4) & 0x0F;
                         audio_rate = sci[1] & 0x0F;
@@ -286,8 +327,8 @@ fn parse_program_info(data: &[u8]) -> Vec<ClpiStream> {
                         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 => {
+                // PG, IG: coding_type + 3-byte language [+ char_code for PG]
+                c::PG | c::IG => {
                     if sci.len() >= 4 {
                         language = String::from_utf8_lossy(&sci[1..4]).to_string();
                     }
@@ -322,8 +363,17 @@ fn parse_cpi(data: &[u8]) -> Result<(Vec<EpCoarse>, Vec<EpFine>)> {
         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()));
@@ -351,9 +401,6 @@ fn parse_cpi(data: &[u8]) -> Result<(Vec<EpCoarse>, Vec<EpFine>)> {
     //   num_EP_coarse: 16 bits        │ (10+4+16+18+32 = 80)
     //   num_EP_fine: 18 bits          │
     //   EP_map_start_address: 32 bits ┘
-    if ep_map.len() < 16 {
-        return Ok((Vec::new(), Vec::new()));
-    }
     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
@@ -389,7 +436,10 @@ fn parse_cpi(data: &[u8]) -> Result<(Vec<EpCoarse>, Vec<EpFine>)> {
 
     // Coarse entries start at offset 4, 8 bytes each
     let coarse_data = &stream_ep[4..];
-    let mut ep_coarse = Vec::with_capacity(num_coarse);
+    // 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() {
@@ -419,7 +469,13 @@ fn parse_cpi(data: &[u8]) -> Result<(Vec<EpCoarse>, Vec<EpFine>)> {
     }
 
     // Fine entries at fine_start, 4 bytes each
-    let mut ep_fine = Vec::with_capacity(num_fine);
+    // 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 {
@@ -643,10 +699,49 @@ mod tests {
         };
         // full_pts = (100 << 19) + (50 << 8) = 52_428_800 + 12_800 = 52_441_600
         let pts = ClipInfo::full_pts(&coarse, &fine);
-        assert_eq!(pts, (100 << 19) + (50 << 8));
+        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 {
@@ -674,6 +769,22 @@ mod tests {
         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);
@@ -707,4 +818,463 @@ mod tests {
         assert!(clip2.ep_coarse.is_empty());
         assert!(clip2.ep_fine.is_empty());
     }
+
+    // ─────────────────────────────────────────────────────────────────────
+    // Added hardening tests. Grounded in the BD-ROM CLPI spec
+    // (https://github.com/lw/BluRay/wiki/CLPI) and libbluray clpi_parse.c.
+    // ─────────────────────────────────────────────────────────────────────
+
+    /// Build a ProgramInfo section. `streams` = Vec<(pid, sci_bytes)>.
+    /// Layout per source doc: length(4)+reserved(1)+num_programs(1)+
+    /// per program [spn(4)+pmt_pid(2)+num_streams(1)+num_groups(1)] then
+    /// per stream [pid(2)+sci_len(1)+sci].
+    fn build_program_info(streams: &[(u16, Vec<u8>)]) -> Vec<u8> {
+        let mut body = Vec::new();
+        body.push(0); // reserved (offset 4)
+        body.push(1); // num_programs = 1 (offset 5)
+        // program 0 header (8 bytes)
+        body.extend_from_slice(&0u32.to_be_bytes()); // spn_program_sequence_start
+        body.extend_from_slice(&0u16.to_be_bytes()); // program_map_pid
+        body.push(streams.len() as u8); // num_streams
+        body.push(0); // num_groups
+        for (pid, sci) in streams {
+            body.extend_from_slice(&pid.to_be_bytes());
+            body.push(sci.len() as u8);
+            body.extend_from_slice(sci);
+        }
+        // Prepend length(4) = bytes after the length field.
+        let mut out = Vec::new();
+        out.extend_from_slice(&(body.len() as u32).to_be_bytes());
+        out.extend_from_slice(&body);
+        out
+    }
+
+    /// Build a CLPI with a ProgramInfo section. prog_info_start is placed
+    /// right after the 60-byte header; cpi (if any) follows program_info.
+    fn build_clpi_with_proginfo(
+        source_packet_count: u32,
+        prog_info: &[u8],
+        cpi_data: Option<&[u8]>,
+    ) -> Vec<u8> {
+        let mut buf = vec![0u8; 60];
+        buf[0..4].copy_from_slice(b"HDMV");
+        buf[4..8].copy_from_slice(b"0200");
+        let prog_info_start: u32 = 60;
+        buf[12..16].copy_from_slice(&prog_info_start.to_be_bytes());
+        let cpi_start: u32 = if cpi_data.is_some() {
+            (60 + prog_info.len()) as u32
+        } else {
+            0
+        };
+        buf[16..20].copy_from_slice(&cpi_start.to_be_bytes());
+        buf[56..60].copy_from_slice(&source_packet_count.to_be_bytes());
+        buf.extend_from_slice(prog_info);
+        if let Some(cpi) = cpi_data {
+            buf.extend_from_slice(cpi);
+        }
+        buf
+    }
+
+    /// source_packet_count is a big-endian u32 at offset [56..60]. Verify
+    /// BE decode of a value with all four bytes distinct (not LE / wrong
+    /// offset).
+    #[test]
+    fn source_packet_count_big_endian_offset_56() {
+        let data = build_clpi(0x01020304, None);
+        let clip = parse(&data).expect("should parse");
+        assert_eq!(clip.source_packet_count, 0x01020304);
+    }
+
+    /// Magic must be exactly "HDMV" at [0..4]. Anything else → ClpiParse.
+    /// Spec: CLPI files begin with the type_indicator "HDMV".
+    #[test]
+    fn wrong_magic_rejected() {
+        let mut data = build_clpi(1000, None);
+        data[0..4].copy_from_slice(b"INDX");
+        assert!(parse(&data).is_err());
+    }
+
+    /// Under-40-byte input is rejected before any field read
+    /// (`data.len() < 40` guard).
+    #[test]
+    fn under_40_bytes_rejected() {
+        assert!(parse(&[0u8; 39]).is_err());
+        assert!(parse(b"HDMV0200").is_err());
+        assert!(parse(&[]).is_err());
+    }
+
+    /// ProgramInfo: a video stream (coding 0x1B = H.264) carries
+    /// format/rate in sci[1] nibbles and NO language. Verify the video
+    /// arm: format hi-nibble, rate lo-nibble, language stays empty.
+    #[test]
+    fn program_info_video_stream() {
+        // sci = coding_type(0x1B) + format_rate(0x61 → fmt 6, rate 1)
+        let sci = vec![0x1Bu8, 0x61];
+        let pi = build_program_info(&[(0x1011, sci)]);
+        let data = build_clpi_with_proginfo(100, &pi, None);
+        let clip = parse(&data).expect("should parse");
+        assert_eq!(clip.streams.len(), 1);
+        assert_eq!(clip.streams[0].pid, 0x1011);
+        assert_eq!(clip.streams[0].coding_type, 0x1B);
+        assert_eq!(clip.streams[0].video_format, 6);
+        assert_eq!(clip.streams[0].video_rate, 1);
+        assert_eq!(clip.streams[0].language, "");
+    }
+
+    /// ProgramInfo primary-audio (coding 0x80..=0x86): sci[1] = format/rate
+    /// nibbles, sci[2..5] = ISO 639 language. Verify TrueHD (0x83) at
+    /// offset, 5.1 / 48kHz, language "eng".
+    #[test]
+    fn program_info_audio_stream_lang_offset() {
+        // sci = 0x83 + 0x61 (fmt 6, rate 1) + "eng"
+        let sci = vec![0x83u8, 0x61, b'e', b'n', b'g'];
+        let pi = build_program_info(&[(0x1100, sci)]);
+        let data = build_clpi_with_proginfo(100, &pi, None);
+        let clip = parse(&data).expect("should parse");
+        assert_eq!(clip.streams[0].coding_type, 0x83);
+        assert_eq!(clip.streams[0].audio_format, 6);
+        assert_eq!(clip.streams[0].audio_rate, 1);
+        assert_eq!(clip.streams[0].language, "eng");
+    }
+
+    /// ProgramInfo PG (0x90)/IG (0x91): layout is coding_type(1)+lang(3),
+    /// so language is at sci[1..4] (NOT sci[2..5] like audio). Verify the
+    /// PG arm reads from the right offset.
+    #[test]
+    fn program_info_pg_lang_offset() {
+        // sci = 0x90 + "fra" (lang directly after coding_type)
+        let sci = vec![0x90u8, b'f', b'r', b'a'];
+        let pi = build_program_info(&[(0x1200, sci)]);
+        let data = build_clpi_with_proginfo(100, &pi, None);
+        let clip = parse(&data).expect("should parse");
+        assert_eq!(clip.streams[0].coding_type, 0x90);
+        assert_eq!(clip.streams[0].language, "fra");
+        // Audio nibbles must NOT be populated for a PG stream.
+        assert_eq!(clip.streams[0].audio_format, 0);
+    }
+
+    /// ProgramInfo with multiple streams: PID and coding for each must be
+    /// read from the correct per-stream offset (pid(2)+sci_len(1)+sci).
+    /// Three mixed streams must all parse with distinct PIDs in order.
+    #[test]
+    fn program_info_multiple_streams_advance_correctly() {
+        let v = (0x1011u16, vec![0x24u8, 0x81]); // HEVC video
+        let a = (0x1100u16, vec![0x86u8, 0x61, b'e', b'n', b'g']); // DTS-HD MA
+        let s = (0x1200u16, vec![0x90u8, b'j', b'p', b'n']); // PG
+        let pi = build_program_info(&[v, a, s]);
+        let data = build_clpi_with_proginfo(100, &pi, None);
+        let clip = parse(&data).expect("should parse");
+        assert_eq!(clip.streams.len(), 3);
+        assert_eq!(clip.streams[0].pid, 0x1011);
+        assert_eq!(clip.streams[0].coding_type, 0x24);
+        assert_eq!(clip.streams[1].pid, 0x1100);
+        assert_eq!(clip.streams[1].coding_type, 0x86);
+        assert_eq!(clip.streams[1].language, "eng");
+        assert_eq!(clip.streams[2].pid, 0x1200);
+        assert_eq!(clip.streams[2].language, "jpn");
+    }
+
+    /// parse_program_info is best-effort: a stream whose declared sci_len
+    /// runs past the section (`sci_end > data.len()`) makes it return the
+    /// streams collected so far (here: none), never panic. Source returns
+    /// `out` early on the overflow.
+    #[test]
+    fn program_info_truncated_sci_no_panic() {
+        // One stream claiming sci_len = 200 but with no body.
+        let mut body = Vec::new();
+        body.push(0); // reserved
+        body.push(1); // num_programs
+        body.extend_from_slice(&0u32.to_be_bytes());
+        body.extend_from_slice(&0u16.to_be_bytes());
+        body.push(1); // num_streams
+        body.push(0); // num_groups
+        body.extend_from_slice(&0x1011u16.to_be_bytes()); // pid
+        body.push(200); // sci_len = 200, no body follows
+        let mut pi = Vec::new();
+        pi.extend_from_slice(&(body.len() as u32).to_be_bytes());
+        pi.extend_from_slice(&body);
+        let data = build_clpi_with_proginfo(100, &pi, None);
+        let clip = parse(&data).expect("should not panic");
+        assert!(clip.streams.is_empty());
+    }
+
+    /// parse_program_info rejects sci_len == 0 (`sci_len < 1` → return).
+    /// A zero-length stream_coding_info is unusable.
+    #[test]
+    fn program_info_zero_sci_len_yields_no_stream() {
+        let mut body = Vec::new();
+        body.push(0);
+        body.push(1);
+        body.extend_from_slice(&0u32.to_be_bytes());
+        body.extend_from_slice(&0u16.to_be_bytes());
+        body.push(1);
+        body.push(0);
+        body.extend_from_slice(&0x1011u16.to_be_bytes());
+        body.push(0); // sci_len = 0
+        let mut pi = Vec::new();
+        pi.extend_from_slice(&(body.len() as u32).to_be_bytes());
+        pi.extend_from_slice(&body);
+        let data = build_clpi_with_proginfo(100, &pi, None);
+        let clip = parse(&data).expect("should parse");
+        assert!(clip.streams.is_empty());
+    }
+
+    /// pts_coarse field is 14 bits: dword0 = ref_to_fine_id<<14 | pts_coarse.
+    /// A pts_coarse of 0x3FFF (max) with ref_to_fine_id 5 must decode both
+    /// without bleed. Verify the >>14 and &0x3FFF split.
+    #[test]
+    fn coarse_pts_14bit_split() {
+        let cpi = build_cpi(0x1011, &[(5, 0x3FFF, 0x12340000)], &[(0, 0)]);
+        let data = build_clpi(1000, Some(&cpi));
+        let clip = parse(&data).expect("should parse");
+        assert_eq!(clip.ep_coarse[0].ref_to_fine_id, 5);
+        assert_eq!(clip.ep_coarse[0].pts_coarse, 0x3FFF);
+        assert_eq!(clip.ep_coarse[0].spn_coarse, 0x12340000);
+    }
+
+    /// Fine entry: dword = is_angle(1)+i_end_offset(3)+pts_fine(11)+
+    /// spn_fine(17). pts_fine occupies bits 17..28 (>>17 & 0x7FF), spn_fine
+    /// the low 17 bits (& 0x1FFFF). Set high bits (is_angle/i_end_offset)
+    /// and verify they do NOT bleed into pts_fine.
+    #[test]
+    fn fine_entry_bit_layout_isolates_pts_and_spn() {
+        // Construct a raw fine dword with is_angle=1, i_end_offset=0b111,
+        // pts_fine=0x5AA, spn_fine=0x1AAAA, then verify decode.
+        let is_angle: u32 = 1;
+        let i_end: u32 = 0b111;
+        let pts_f: u32 = 0x5AA; // 11-bit
+        let spn_f: u32 = 0x1AAAA; // 17-bit
+        let dword: u32 = (is_angle << 31) | (i_end << 28) | (pts_f << 17) | spn_f;
+
+        // Build the CPI by hand with this raw fine dword.
+        let mut stream_ep = Vec::new();
+        let fine_start: u32 = 4; // no coarse entries → fine right after header
+        stream_ep.extend_from_slice(&fine_start.to_be_bytes());
+        stream_ep.extend_from_slice(&dword.to_be_bytes());
+
+        let num_coarse: u32 = 0;
+        let num_fine: u32 = 1;
+        let ep_map_start: u32 = 14;
+        let ep_stream_type: u32 = 1;
+        let packed: u128 = ((ep_stream_type as u128) << 66)
+            | ((num_coarse as u128) << 50)
+            | ((num_fine as u128) << 32)
+            | (ep_map_start as u128);
+        let packed_bytes = packed.to_be_bytes();
+        let stream_header_bits = &packed_bytes[6..16];
+
+        let mut ep_map = Vec::new();
+        ep_map.push(0);
+        ep_map.push(1);
+        ep_map.extend_from_slice(&0x1011u16.to_be_bytes());
+        ep_map.extend_from_slice(stream_header_bits);
+        ep_map.extend_from_slice(&stream_ep);
+
+        let mut cpi = Vec::new();
+        cpi.extend_from_slice(&((2 + ep_map.len()) as u32).to_be_bytes());
+        cpi.extend_from_slice(&[0u8; 2]);
+        cpi.extend_from_slice(&ep_map);
+
+        let data = build_clpi(1000, Some(&cpi));
+        let clip = parse(&data).expect("should parse");
+        assert_eq!(clip.ep_fine.len(), 1);
+        assert_eq!(clip.ep_fine[0].pts_fine, 0x5AA); // high bits stripped
+        assert_eq!(clip.ep_fine[0].spn_fine, 0x1AAAA);
+    }
+
+    /// resolved_ep_map assigns fine entries to coarse groups via
+    /// [ref_to_fine_id .. next coarse's ref_to_fine_id). full_pts combines
+    /// coarse<<19 + fine<<8 and full_spn ORs masked coarse with fine.
+    /// Verify the first resolved entry's (pts, spn) for a known fixture.
+    #[test]
+    fn resolved_ep_map_combines_coarse_and_fine() {
+        // coarse 0: ref_to_fine_id=0, pts_coarse=10, spn_coarse=0x00020000
+        // fine 0: pts_fine=3, spn_fine=0x100
+        let cpi = build_cpi(0x1011, &[(0, 10, 0x00020000)], &[(3, 0x100)]);
+        let data = build_clpi(1000, Some(&cpi));
+        let clip = parse(&data).expect("should parse");
+        let resolved = clip.resolved_ep_map();
+        assert_eq!(resolved.len(), 1);
+        let expected_pts = (10u64 << 19) + (3u64 << 8);
+        let expected_spn = (0x00020000u32 & 0xFFFE_0000) | 0x100;
+        assert_eq!(resolved[0].0, expected_pts);
+        assert_eq!(resolved[0].1, expected_spn);
+    }
+
+    /// get_extents converts an in/out PTS range to a single sector Extent.
+    /// SPN→byte = spn×192, byte→sector = /2048 (start floored, end ceiled),
+    /// relative to m2ts file start. Verify the math for a known fixture.
+    #[test]
+    fn get_extents_spn_to_sector_math() {
+        // Two EP points: PTS p0 → SPN 0, PTS p1 → SPN big_spn.
+        // full_spn ORs (spn_coarse & 0xFFFE0000) with spn_fine, so the SPN
+        // must be coarse-aligned (low 17 bits clear) to survive intact.
+        // 0x20000 (131072) is the smallest non-zero coarse-aligned SPN.
+        let big_spn: u32 = 0x20000;
+        let cpi = build_cpi(0x1011, &[(0, 0, 0), (1, 100, big_spn)], &[(0, 0), (0, 0)]);
+        let data = build_clpi(1000, Some(&cpi));
+        let clip = parse(&data).expect("should parse");
+
+        let p0 = 0u64; // PTS of first EP
+        let p1 = 100u64 << 19; // PTS of second EP
+        let extents = clip.get_extents(p0, p1);
+        assert_eq!(extents.len(), 1);
+        // Mirror production: SPN→byte ×packet, byte→sector with start FLOORed
+        // and end CEILed (same constants as get_extents).
+        let start_spn: u64 = 0;
+        let end_spn = big_spn as u64;
+        let start_byte = start_spn * BD_SOURCE_PACKET_BYTES as u64;
+        let end_byte = end_spn * BD_SOURCE_PACKET_BYTES as u64;
+        let start_sector = (start_byte / SECTOR_BYTES_U64) as u32;
+        let end_sector = end_byte.div_ceil(SECTOR_BYTES_U64) as u32;
+        assert_eq!(extents[0].start_lba, start_sector);
+        assert_eq!(extents[0].sector_count, end_sector - start_sector);
+        // Concretely: 0x20000 × 192 / 2048 = 12288 sectors.
+        assert_eq!(extents[0].sector_count, 12288);
+    }
+
+    /// get_extents returns an empty Vec when the EP map is empty (no CPI),
+    /// since there is no SPN to resolve. Documented early return.
+    #[test]
+    fn get_extents_empty_when_no_ep_map() {
+        let data = build_clpi(1000, None);
+        let clip = parse(&data).expect("should parse");
+        assert!(clip.get_extents(0, 1_000_000).is_empty());
+    }
+
+    /// get_extents returns empty when end_spn <= start_spn (degenerate or
+    /// inverted range). Source has an explicit `if end_spn <= start_spn`
+    /// guard. Use in_time == out_time on a single-point map.
+    #[test]
+    fn get_extents_empty_on_degenerate_range() {
+        let cpi = build_cpi(0x1011, &[(0, 50, 0x1000)], &[(0, 0)]);
+        let data = build_clpi(1000, Some(&cpi));
+        let clip = parse(&data).expect("should parse");
+        let p = 50u64 << 19;
+        // in == out → start_spn == end_spn → empty.
+        assert!(clip.get_extents(p, p).is_empty());
+    }
+
+    /// full_spn masks the LOW 17 bits of spn_coarse (& 0xFFFE0000) before
+    /// OR-ing fine. A spn_coarse with low bits set must have them cleared,
+    /// then replaced by spn_fine. Independent of parse, exercises the
+    /// reconstruction directly with a hostile low-bit pattern.
+    #[test]
+    fn full_spn_clears_coarse_low_17_bits() {
+        let coarse = EpCoarse {
+            ref_to_fine_id: 0,
+            pts_coarse: 0,
+            spn_coarse: 0x0006_FFFF, // low 17 bits all set
+        };
+        let fine = EpFine {
+            pts_fine: 0,
+            spn_fine: 0x5,
+        };
+        // 0x0006_FFFF & 0xFFFE_0000 = 0x0006_0000; | 0x5 = 0x0006_0005.
+        assert_eq!(ClipInfo::full_spn(&coarse, &fine), 0x0006_0005);
+    }
+
+    /// CPI guard: cpi_length < 4 short-circuits to empty maps (the length
+    /// field counts bytes after itself, and the EP map needs ≥4). A
+    /// cpi_length of 0/1/2/3 must yield empty EP maps, not panic.
+    #[test]
+    fn cpi_length_below_4_yields_empty() {
+        for bad_len in 0u32..4 {
+            let mut cpi = Vec::new();
+            cpi.extend_from_slice(&bad_len.to_be_bytes());
+            cpi.extend_from_slice(&[0u8; 20]); // padding so the slice exists
+            let data = build_clpi(1000, Some(&cpi));
+            let clip = parse(&data).expect("should parse");
+            assert!(clip.ep_coarse.is_empty(), "len={bad_len}");
+            assert!(clip.ep_fine.is_empty(), "len={bad_len}");
+        }
+    }
+
+    /// ep_map_offset that points past the EP map (`ep_map_offset + 4 >
+    /// ep_map.len()`) → empty maps (bounds guard), not panic. Patch the
+    /// EP_map_start field to a huge value.
+    #[test]
+    fn ep_map_offset_out_of_bounds_yields_empty() {
+        let cpi = build_cpi(0x1011, &[(0, 10, 0x20000)], &[(5, 100)]);
+        let mut data = build_clpi(1000, Some(&cpi));
+        // EP_map_start is the low 32 bits of the 80-bit stream header at
+        // ep_map[4..14]. In the file: header(60) + cpi_length(4) +
+        // reserved(2) + ep_map reserved(1) + num_streams(1) + pid(2) = 70,
+        // then 10 header bytes [70..80]; EP_map_start is the last 4 [76..80].
+        let off = 60 + 4 + 2 + 1 + 1 + 2 + 6; // = 76
+        data[off..off + 4].copy_from_slice(&0xFFFF_FFFFu32.to_be_bytes());
+        let clip = parse(&data).expect("should not panic");
+        assert!(clip.ep_coarse.is_empty());
+        assert!(clip.ep_fine.is_empty());
+    }
+
+    /// num_coarse declares more entries than the CPI section holds. The
+    /// loop must stop at `off + 8 > coarse_data.len()` (break), not read
+    /// out of bounds. Patch num_coarse to a large value while supplying 1
+    /// coarse entry's worth of bytes.
+    #[test]
+    fn coarse_count_overshoot_truncates_safely() {
+        let cpi = build_cpi(0x1011, &[(0, 10, 0x20000)], &[(5, 100)]);
+        let mut data = build_clpi(1000, Some(&cpi));
+        // num_coarse is bits 14..30 of the 80-bit header. Rather than
+        // bit-surgery, rebuild with a hand-set num_coarse=255 but only 1
+        // coarse entry of bytes — done below directly.
+        let _ = &mut data;
+
+        let num_coarse_decl: u32 = 255;
+        let num_fine: u32 = 1;
+        let ep_map_start: u32 = 14;
+        let ep_stream_type: u32 = 1;
+        let packed: u128 = ((ep_stream_type as u128) << 66)
+            | ((num_coarse_decl as u128) << 50)
+            | ((num_fine as u128) << 32)
+            | (ep_map_start as u128);
+        let packed_bytes = packed.to_be_bytes();
+        let stream_header_bits = &packed_bytes[6..16];
+
+        // stream EP data: fine_start points past the 1 coarse entry.
+        let fine_start: u32 = 4 + 8; // 4-byte header + 1 coarse entry x 8 bytes
+        let mut stream_ep = Vec::new();
+        stream_ep.extend_from_slice(&fine_start.to_be_bytes());
+        // exactly ONE coarse entry (8 bytes), though header claims 255.
+        stream_ep.extend_from_slice(&10u32.to_be_bytes());
+        stream_ep.extend_from_slice(&0x20000u32.to_be_bytes());
+        // one fine entry (4 bytes)
+        stream_ep.extend_from_slice(&(((5u32 & 0x7FF) << 17) | 100).to_be_bytes());
+
+        let mut ep_map = Vec::new();
+        ep_map.push(0);
+        ep_map.push(1);
+        ep_map.extend_from_slice(&0x1011u16.to_be_bytes());
+        ep_map.extend_from_slice(stream_header_bits);
+        ep_map.extend_from_slice(&stream_ep);
+        let mut cpi2 = Vec::new();
+        cpi2.extend_from_slice(&((2 + ep_map.len()) as u32).to_be_bytes());
+        cpi2.extend_from_slice(&[0u8; 2]);
+        cpi2.extend_from_slice(&ep_map);
+        let data2 = build_clpi(1000, Some(&cpi2));
+        let clip = parse(&data2).expect("should not panic on coarse overshoot");
+        // Only the 1 real coarse entry was readable.
+        assert_eq!(clip.ep_coarse.len(), 1);
+        assert_eq!(clip.ep_coarse[0].pts_coarse, 10);
+    }
+
+    /// resolved_ep_map: the LAST coarse group's fine range extends to
+    /// ep_fine.len() (no "next coarse" bound). Verify all trailing fine
+    /// entries are assigned to the final coarse group.
+    #[test]
+    fn resolved_ep_map_last_group_to_end() {
+        // coarse 0 ref_to_fine_id=0, coarse 1 ref_to_fine_id=1.
+        // 3 fine entries: fine 0 → coarse 0; fine 1,2 → coarse 1.
+        let cpi = build_cpi(
+            0x1011,
+            &[(0, 0, 0), (1, 100, 0)],
+            &[(0, 10), (0, 20), (0, 30)],
+        );
+        let data = build_clpi(1000, Some(&cpi));
+        let clip = parse(&data).expect("should parse");
+        let resolved = clip.resolved_ep_map();
+        // All 3 fine entries resolved (last group picks up fine 1 and 2).
+        assert_eq!(resolved.len(), 3);
+    }
 }

src/consts.rs

@@ -0,0 +1,125 @@
+//! Physical media constants — the single source of truth.
+//!
+//! Naming convention: a constant is prefixed by the **narrowest scope where it
+//! is valid**. A value common to all optical media carries no prefix; a value
+//! specific to a container/format/disc-type is prefixed by it
+//! (`TS_`, `BD_`, …). Define each physical quantity here exactly once and import
+//! it — never re-declare a bare literal or a local copy.
+
+/// Bytes per logical sector on every optical medium freemkv reads
+/// (Blu-ray, DVD-Video, CD-ROM Mode 1). Universal — hence unprefixed.
+///
+/// `usize` because its dominant use is buffer sizing and slice indexing, where
+/// Rust *requires* `usize` (`vec![0u8; SECTOR_BYTES]`, `buf.len() < SECTOR_BYTES`).
+/// For byte-offset / capacity arithmetic — which is `u64` because a disc can
+/// exceed 4 GiB — use [`SECTOR_BYTES_U64`] instead of casting at each site.
+pub const SECTOR_BYTES: usize = 2048;
+
+/// [`SECTOR_BYTES`] as `u64`, for byte-offset and capacity arithmetic. The
+/// single `usize → u64` boundary cast lives here, once, so offset math across
+/// the workspace reads as `sectors * SECTOR_BYTES_U64` with no per-site cast.
+pub const SECTOR_BYTES_U64: u64 = SECTOR_BYTES as u64;
+
+/// Milliseconds per second. For turning a byte count ÷ bytes-per-second into a
+/// movie-time figure (`bytes / bps * MILLIS_PER_SEC`) without a bare `1000.0`.
+pub const MILLIS_PER_SEC: f64 = 1_000.0;
+
+/// Bytes per MPEG-2 transport-stream packet. Common to all MPEG-TS, not just
+/// Blu-ray — prefixed by the format, not a disc type.
+pub const TS_PACKET_BYTES: usize = 188;
+
+/// Bytes in an MPEG-2 transport-stream packet header: sync byte, the
+/// flags/PID word, and the adaptation/continuity byte.
+pub const TS_HEADER_BYTES: usize = 4;
+
+/// Bytes in the arrival-timestamp prefix a Blu-ray M2TS prepends to each TS
+/// packet to form a source packet. Same width as a TS header but a distinct
+/// quantity ([`TS_HEADER_BYTES`]) — do not conflate.
+pub const BD_TIMESTAMP_PREFIX_BYTES: usize = 4;
+
+/// Bytes of payload in an MPEG-2 transport-stream packet:
+/// [`TS_PACKET_BYTES`] minus the [`TS_HEADER_BYTES`] header.
+pub const TS_PAYLOAD_BYTES: usize = TS_PACKET_BYTES - TS_HEADER_BYTES;
+
+/// Bytes per Blu-ray M2TS *source packet*: a TS packet ([`TS_PACKET_BYTES`])
+/// prefixed with the [`BD_TIMESTAMP_PREFIX_BYTES`] arrival-timestamp header.
+/// A BDAV/M2TS construct only — DVD VOBs have no source packets — hence `BD_`.
+pub const BD_SOURCE_PACKET_BYTES: usize = TS_PACKET_BYTES + BD_TIMESTAMP_PREFIX_BYTES;
+
+/// Elementary-stream coding-type codes — the single source of truth for the
+/// byte that identifies a stream's codec.
+///
+/// This is one registry used in two places that share the same value space:
+/// the MPEG-TS PMT `stream_type` (ISO/IEC 13818-1 Table 2-34) and the Blu-ray
+/// STN/CLPI `stream_coding_type` (BD-ROM Part 3). The standardized video codes
+/// (`0x02`, `0x1B`, `0x24`) are ISO assignments (ISO/IEC 13818-1 Table 2-34);
+/// `0xEA` (VC-1) is a BD-ROM convention in the ISO user-private range. The
+/// `0x80..=0xA2` audio/graphics codes also sit in the user-private range and follow the
+/// Blu-ray Disc Association / ATSC A/52 convention. Because every consumer
+/// reads or writes this single byte, the family is unprefixed — the scope is
+/// "any elementary stream freemkv parses or muxes".
+///
+/// Each constant is `u8`: the spec defines an 8-bit field and the code compares
+/// it directly against a byte read from the buffer, so no casts are needed.
+pub mod coding_type {
+    /// MPEG-2 video (ISO/IEC 13818-1 Table 2-34).
+    pub const MPEG2_VIDEO: u8 = 0x02;
+    /// H.264 / AVC video (ISO/IEC 13818-1 Table 2-34).
+    pub const H264: u8 = 0x1B;
+    /// HEVC / H.265 video (ISO/IEC 13818-1 Table 2-34, 2015 amendment).
+    pub const HEVC: u8 = 0x24;
+    /// SMPTE VC-1 video (BD-ROM convention, ISO user-private range).
+    pub const VC1: u8 = 0xEA;
+
+    /// LPCM audio (BD-ROM convention).
+    pub const LPCM: u8 = 0x80;
+    /// Dolby Digital (AC-3) audio (BD-ROM / ATSC A/52 convention).
+    pub const AC3: u8 = 0x81;
+    /// DTS audio (BD-ROM convention).
+    pub const DTS: u8 = 0x82;
+    /// Dolby TrueHD audio (BD-ROM convention).
+    pub const TRUEHD: u8 = 0x83;
+    /// Dolby Digital Plus (E-AC-3 / AC-3+) audio (BD-ROM convention).
+    pub const AC3_PLUS: u8 = 0x84;
+    /// DTS-HD High Resolution audio (BD-ROM Part 3-1).
+    pub const DTS_HD_HR: u8 = 0x85;
+    /// DTS-HD Master Audio (lossless) (BD-ROM Part 3-1).
+    pub const DTS_HD_MA: u8 = 0x86;
+
+    /// Presentation Graphics — PG subtitle stream (BD-ROM HDMV).
+    pub const PG: u8 = 0x90;
+    /// Interactive Graphics — IG / BD-J menu overlay, NOT a subtitle (BD-ROM HDMV).
+    pub const IG: u8 = 0x91;
+    /// Text subtitle stream (BD-ROM HDMV).
+    pub const TEXT_SUBTITLE: u8 = 0x92;
+
+    /// Secondary Dolby Digital Plus audio (BD-ROM convention).
+    pub const AC3_PLUS_SECONDARY: u8 = 0xA1;
+    /// Secondary DTS-HD audio (lossless MA, not lossy HR) (BD-ROM convention).
+    pub const DTS_HD_SECONDARY: u8 = 0xA2;
+}
+
+/// MPEG PES `stream_id` codes — the byte after the `00 00 01` start-code prefix
+/// that identifies an elementary stream's role in a PES packet (ISO/IEC
+/// 13818-1 Table 2-22). Shared by the program-stream demuxer and the TS/M2TS
+/// muxers, so defined here once. Each is `u8` (matches the byte on the wire).
+pub mod pes_stream_id {
+    /// Video stream (`110x xxxx`; freemkv emits the base id `0xE0`).
+    pub const VIDEO: u8 = 0xE0;
+    /// private_stream_1 — AC-3 / DTS / LPCM / PGS subtitle payloads.
+    pub const PRIVATE_STREAM_1: u8 = 0xBD;
+    /// padding_stream — stuffing bytes only, no payload to demux.
+    pub const PADDING_STREAM: u8 = 0xBE;
+    /// private_stream_2 — DVD navigation (PCI/DSI); carries no muxable ES.
+    pub const PRIVATE_STREAM_2: u8 = 0xBF;
+
+    /// Highest video stream_id — the `110x xxxx` video range tops out at 0xEF.
+    pub const VIDEO_MAX: u8 = 0xEF;
+
+    /// Inclusive range of every PES `stream_id` that carries demuxable payload:
+    /// [`PRIVATE_STREAM_1`] (0xBD) through [`VIDEO_MAX`] (0xEF) — i.e. private
+    /// stream 1/2, padding, MPEG audio (0xC0-0xDF) and video (0xE0-0xEF). The
+    /// pack (0xBA), system-header (0xBB) and program-end (0xB9) codes sit below
+    /// this range and are deliberately excluded: they're structural, not ES.
+    pub const PAYLOAD_RANGE: core::ops::RangeInclusive<u8> = PRIVATE_STREAM_1..=VIDEO_MAX;
+}

src/css/auth.rs

@@ -1,639 +0,0 @@
-//! 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; 288] = [
-    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,
-    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x33, 0x72, 0x39, 0x25, 0x67, 0x26, 0x6D, 0x71,
-    0x36, 0x77, 0x3C, 0x20, 0x62, 0x23, 0x68, 0x74, 0xC3, 0x82, 0xC9, 0x15, 0x57, 0x16, 0x5D, 0x81,
-];
-
-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,
-    ],
-];
-
-// ── SCSI constants ────────────────────────────────────────────────────────
-
-const SCSI_READ_DVD_STRUCTURE: u8 = 0xAD;
-
-// ── 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] = SCSI_READ_DVD_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 try all known player keys and verify by checking that two different
-    // entries produce the same disc key.
-    let mut candidates: Vec<([u8; 5], usize, usize)> = Vec::new(); // (disc_key, pk_idx, pos)
-
-    for (pk_idx, player_key) in PLAYER_KEYS.iter().enumerate() {
-        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);
-
-            // Check if any previous candidate matches (same disc key from different entry/pk)
-            for (prev, _, _) in &candidates {
-                if *prev == candidate {
-                    return Ok(candidate);
-                }
-            }
-            candidates.push((candidate, pk_idx, pos));
-        }
-    }
-
-    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)
-}
-
-#[allow(dead_code)]
-fn read_title_key(
-    drive: &mut Drive,
-    agid: u8,
-    lba: u32,
-    bus_key: &[u8; 5],
-    disc_key: &[u8; 5],
-) -> 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 tk_result = scsi.execute(
-        &cdb,
-        crate::scsi::DataDirection::FromDevice,
-        &mut buf,
-        5_000,
-    );
-    tk_result.map_err(|_| Error::CssAuthFailed)?;
-
-    // Title key at bytes 5..10, byte-reversed
-    let mut title_key = [0u8; 5];
-    for i in 0..5 {
-        title_key[i] = buf[5 + (4 - i)];
-    }
-
-    // XOR with reversed bus key (same pattern as disc key block)
-    for i in 0..5 {
-        title_key[i] ^= bus_key[4 - i];
-    }
-
-    // Check for null key (title not encrypted)
-    if title_key == [0u8; 5] {
-        return Ok(title_key);
-    }
-
-    // Decrypt with disc key (invert=0xFF for title keys)
-    let title_key = super::lfsr::decrypt_key(0xFF, disc_key, &title_key);
-
-    Ok(title_key)
-}
-
-// ── CSSCryptKey ───────────────────────────────────────────────────────────
-
-/// Exposed for testing only.
-pub fn test_crypt_key(key_type: usize, variant: u8, challenge: &[u8; 10]) -> [u8; 5] {
-    crypt_key(key_type, variant, challenge)
-}
-
-fn crypt_key(key_type: usize, variant: u8, challenge: &[u8; 10]) -> [u8; 5] {
-    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

@@ -1,398 +0,0 @@
-//! CSS title key recovery — Stevenson's divide-and-conquer attack (1999).
-//!
-//! Given a scrambled DVD sector with known plaintext (MPEG-2 PES headers),
-//! recovers the 5-byte title key by:
-//!
-//! 1. XORing ciphertext with TAB1[ciphertext] to cancel the mangling
-//! 2. Iterating all 2^16 LFSR1 states
-//! 3. For each: deducing what LFSR0 must produce, then verifying
-//!
-//! Total work: ~65536 iterations with 10-byte validation = instant.
-//!
-//! 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.
-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
-    // The CSS cipher applies TAB1 as an output permutation.
-    // XORing ciphertext with TAB1[ciphertext] and plaintext removes it,
-    // leaving the raw LFSR combination output.
-    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
-            t3 = (t3 << 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
-            let t6 = ((((((t3 >> 8) ^ t3) >> 1) ^ t3) >> 3) ^ t3) >> 7;
-            t3 = (t3 << 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);
-            if (val * 2 + 8 - (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 MPEG-2 pattern attack.
-///
-/// Detects the PES header pattern at byte 0x80 and uses it as known plaintext.
-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]
-    let mut patterns: Vec<[u8; 10]> = Vec::with_capacity(128);
-
-    // 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
-}
-
-/// Crack CSS key from multiple sectors.
-pub fn crack_from_sectors(sectors: &[Vec<u8>]) -> Option<[u8; 5]> {
-    for sector in sectors {
-        if sector.len() < SECTOR_SIZE {
-            continue;
-        }
-        let flags = (sector[FLAG_BYTE] >> 4) & 0x03;
-        if flags == 0 {
-            continue;
-        }
-        if let Some(key) = crack_title_key(sector) {
-            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());
-    }
-
-    #[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());
-    }
-
-    /// Test 3: css_crack_recovers_key_from_scrambled_sector
-    ///
-    /// Build a plaintext sector with known MPEG-2 PES headers, scramble it
-    /// with a known title key, then run crack_title_key() on the scrambled
-    /// sector. If the Stevenson attack succeeds, verify that descrambling
-    /// with the recovered key produces the original plaintext at bytes 128..132.
-    #[test]
-    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)
-        // Then typical PES header bytes for a stream with PTS
-        plaintext[0x80] = 0x00;
-        plaintext[0x81] = 0x00;
-        plaintext[0x82] = 0x01;
-        plaintext[0x83] = 0xE0;
-        plaintext[0x84] = 0x00; // PES length hi
-        plaintext[0x85] = 0x00; // PES length lo
-        plaintext[0x86] = 0x80; // flags: data_alignment, copyright
-        plaintext[0x87] = 0x80; // PTS flag
-        plaintext[0x88] = 0x05; // PES header data length
-        plaintext[0x89] = 0x21; // PTS byte 1
-
-        let original_plaintext = plaintext.clone();
-
-        // "Scramble" the sector by calling descramble (which XORs the keystream)
-        // on the plaintext. This produces a scrambled sector.
-        descramble_sector(&title_key, &mut plaintext);
-
-        // The scramble flag was cleared by descramble_sector. Restore it so
-        // the cracker sees it as encrypted.
-        plaintext[FLAG_BYTE] = 0x30;
-
-        // Now we have a scrambled sector. Try to crack the title key.
-        let cracked_key = crack_title_key(&plaintext);
-
-        match cracked_key {
-            Some(key) => {
-                // Verify: descramble with the cracked key should recover plaintext
-                let mut test = plaintext.clone();
-                descramble_sector(&key, &mut test);
-
-                // Check that the PES header is recovered
-                assert_eq!(test[0x80], 0x00, "PES byte 0 mismatch");
-                assert_eq!(test[0x81], 0x00, "PES byte 1 mismatch");
-                assert_eq!(test[0x82], 0x01, "PES byte 2 mismatch");
-                assert_eq!(test[0x83], 0xE0, "PES byte 3 mismatch");
-
-                // Also verify the rest of the encrypted region matches original
-                assert_eq!(
-                    &test[0x80..SECTOR_SIZE],
-                    &original_plaintext[0x80..SECTOR_SIZE],
-                    "Decrypted content does not match original plaintext"
-                );
-
-                eprintln!(
-                    "Stevenson attack succeeded: cracked key = {:02X?}, original = {:02X?}",
-                    key, title_key
-                );
-            }
-            None => {
-                // The Stevenson attack may not always find a key for all title keys
-                // and sector seeds. This is expected for some combinations where the
-                // known plaintext pattern doesn't match what crack_title_key tries.
-                eprintln!(
-                    "Stevenson attack did not find key for title_key={:02X?} seed={:02X?}. \
-                     This can happen when the cipher output doesn't match the tried patterns. \
-                     Testing with recover_title_key directly with exact plaintext.",
-                    title_key,
-                    &[0x11u8, 0x22, 0x33, 0x44, 0x55],
-                );
-
-                // Try with exact known plaintext instead of guessing
-                let exact_plain: [u8; 10] =
-                    [0x00, 0x00, 0x01, 0xE0, 0x00, 0x00, 0x80, 0x80, 0x05, 0x21];
-                let recovered = recover_title_key(&plaintext, &exact_plain);
-                if let Some(key) = recovered {
-                    let mut test = plaintext.clone();
-                    descramble_sector(&key, &mut test);
-                    assert_eq!(test[0x80], 0x00);
-                    assert_eq!(test[0x81], 0x00);
-                    assert_eq!(test[0x82], 0x01);
-                    eprintln!(
-                        "recover_title_key with exact plaintext succeeded: {:02X?}",
-                        key
-                    );
-                } else {
-                    eprintln!(
-                        "recover_title_key also returned None. The attack may not converge \
-                         for this particular key/seed combination. This is a known limitation \
-                         of the brute-force LFSR0 recovery phase."
-                    );
-                }
-            }
-        }
-    }
-}

src/css/lfsr.rs

@@ -1,11 +1,15 @@
 //! CSS cipher implementation based on the Stevenson 1999 analysis.
 //!
 //! The CSS cipher uses two table-driven feedback circuits:
-//! - LFSR1: 9-bit state (two halves), driven by TAB2/TAB3
-//! - LFSR0: 32-bit state, driven by a feedback polynomial through TAB4
+//! - LFSR1: 17-bit state (9-bit lo + 8-bit hi register, seeded from
+//!   key[0..2]), driven by TAB2/TAB3
+//! - LFSR0: 24-bit feedback register (seeded from key[2..5] XOR seed[2..5],
+//!   masked to 0xFFFFFF), 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.
+//! Content descrambling computes plain = TAB1[cipher] ^ keystream — a TAB1
+//! substitution of each ciphertext byte followed by an XOR with the keystream
+//! (NOT a plain XOR; the cipher is not its own inverse).
 //!
 //! Algorithm: Frank A. Stevenson's divide-and-conquer attack (1999).
 //! Tables: CSS specification constants.
@@ -14,122 +18,155 @@ use super::tables::{TAB1, TAB2, TAB3, TAB4, TAB5};
 
 /// 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.
+/// Exact port of libdvdcss `dvdcss_unscramble` (css.c). The two content
+/// LFSRs are seeded **directly** from `title_key XOR sector_seed` — there is
+/// no `decrypt_key` mangling on this path (that is the disc/title-key
+/// hierarchy, not the content cipher). Bytes 0x80..0x800 are recovered with
+/// `*p = TAB1[*p] ^ (i_t5 & 0xff)`.
 ///
-/// The scramble flag at byte 0x14 (bits 4-5) indicates encryption.
-/// After descrambling, the flag is cleared.
+/// The scramble flag at byte 0x14 (bits 4-5) indicates encryption. Like
+/// libdvdcss, the flag byte is NOT modified here — the caller treats a
+/// nonzero `sector[0x14] & 0x30` as "needs unscrambling" and the descramble
+/// is its own inverse, so re-running it on plaintext would re-scramble.
+/// (freemkv historically cleared the flag; we keep clearing it so callers
+/// and the existing tests can distinguish a descrambled sector. This does
+/// not affect the recovered body.)
+///
+/// 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.
+///
+/// Design reference: libdvdcss `dvdcss_unscramble`. The combiner mirrors
+/// `css.c` line-for-line:
+/// ```text
+/// i_t1 = (key[0] ^ sec[0x54]) | 0x100;
+/// i_t2 =  key[1] ^ sec[0x55];
+/// i_t3 = (key[2]|key[3]<<8|key[4]<<16) ^ (sec[0x56]|sec[0x57]<<8|sec[0x58]<<16);
+/// i_t4 = i_t3 & 7;  i_t3 = i_t3*2 + 8 - i_t4;
+/// // per byte over 0x80..0x800:
+/// i_t4 = TAB2[i_t2] ^ TAB3[i_t1];
+/// i_t2 = i_t1 >> 1;  i_t1 = ((i_t1 & 1) << 8) ^ i_t4;  i_t4 = TAB5[i_t4];
+/// i_t6 = (((((((i_t3>>3)^i_t3)>>1)^i_t3)>>8)^i_t3)>>5) & 0xff;
+/// i_t3 = (i_t3 << 8) | i_t6;  i_t6 = TAB4[i_t6];
+/// i_t5 += i_t6 + i_t4;  *p = TAB1[*p] ^ (i_t5 & 0xff);  i_t5 >>= 8;
+/// ```
 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 {
+    // libdvdcss: `if( !(p_sec[0x14] & 0x30) ) return;`
+    if sector[0x14] & 0x30 == 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],
-    ];
+    // LFSR1: seeded directly from (key ^ seed) — NO decrypt_key.
+    let mut i_t1: u32 = ((title_key[0] ^ sector[0x54]) as u32) | 0x100;
+    let mut i_t2: u32 = (title_key[1] ^ sector[0x55]) as u32;
 
-    // Decrypt the key through the CSS mangling function to get the working key
-    let working_key = decrypt_key(0xFF, &key, &sector[0x54..0x59]);
+    // LFSR0 (i_t3): 24-bit feedback register seeded from the remaining three
+    // key/seed bytes, then transformed `i_t3 = i_t3*2 + 8 - (i_t3 & 7)`.
+    let mut i_t3: u32 = (((title_key[2] as u32)
+        | ((title_key[3] as u32) << 8)
+        | ((title_key[4] as u32) << 16))
+        ^ ((sector[0x56] as u32) | ((sector[0x57] as u32) << 8) | ((sector[0x58] as u32) << 16)))
+        & 0xFF_FFFF;
+    let i_t4_seed = i_t3 & 7;
+    i_t3 = i_t3 * 2 + 8 - i_t4_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 i_t5: u32 = 0;
 
-    let mut lfsr0: u32 = ((working_key[4] as u32) << 17)
-        | ((working_key[3] as u32) << 9)
-        | (((working_key[2] as u32) << 1) + 8 - (working_key[2] as u32 & 7));
-    lfsr0 = (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;
-
-    let mut combined: u32 = 0;
-
-    // Generate 1920 keystream bytes (for sector bytes 128..2048)
-    // Per libdvdcss css_unscramble: TAB1 permutation on ciphertext, no invert on LFSR0
     for byte in sector.iter_mut().take(2048).skip(128) {
-        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;
+        // Advance LFSR1.
+        let mut i_t4 = (TAB2[i_t2 as usize] ^ TAB3[i_t1 as usize]) as u32;
+        i_t2 = i_t1 >> 1;
+        i_t1 = ((i_t1 & 1) << 8) ^ i_t4;
+        i_t4 = TAB5[i_t4 as usize] as u32;
 
-        let o_lfsr0 = (((((((lfsr0 >> 8) ^ lfsr0) >> 1) ^ lfsr0) >> 3) ^ lfsr0) >> 7) as u8;
-        lfsr0 = (lfsr0 >> 8) | ((o_lfsr0 as u32) << 24);
+        // Advance LFSR0 (i_t3) and fold both outputs into i_t5.
+        let mut i_t6 = (((((((i_t3 >> 3) ^ i_t3) >> 1) ^ i_t3) >> 8) ^ i_t3) >> 5) & 0xFF;
+        i_t3 = (i_t3 << 8) | i_t6;
+        i_t6 = TAB4[i_t6 as usize] as u32;
+        i_t5 += i_t6 + i_t4;
 
-        combined += TAB5[o_lfsr1 as usize] as u32 + TAB4[o_lfsr0 as usize] as u32;
-        *byte ^= (combined & 0xFF) as u8;
-        combined >>= 8;
+        *byte = TAB1[*byte as usize] ^ (i_t5 & 0xFF) as u8;
+        i_t5 >>= 8;
     }
 
-    // Clear scramble flags
+    // libdvdcss leaves byte 0x14 untouched; freemkv clears the scramble bits
+    // so downstream code and tests can tell a sector was descrambled.
     sector[0x14] &= 0xCF;
 }
 
-/// CSS key decryption / mangling function.
+/// Exact inverse of [`descramble_sector`]: turn a plaintext sector body into
+/// CSS ciphertext under `title_key`.
 ///
-/// 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]) -> [u8; 5] {
-    if p_crypted.len() < 5 {
-        return *p_key;
+/// Descramble computes `plain = TAB1[cipher] ^ (i_t5 & 0xff)`, so the
+/// inverse is `cipher = TAB1_INV[plain ^ (i_t5 & 0xff)]` with the identical
+/// LFSR keystream. The keystream derivation is byte-for-byte the same as
+/// `descramble_sector` (libdvdcss `dvdcss_unscramble`); only the final
+/// substitution differs. Bytes 0x80..0x800 are rewritten in place; the
+/// scramble flag is set to 0x10 so a subsequent descramble runs.
+///
+/// Not on any production read path — it exists so the key-recovery tests
+/// (and any caller that needs to produce a known CSS-encrypted sector) can
+/// build genuine ciphertext rather than approximating it.
+#[cfg(test)]
+pub(crate) fn scramble_sector(title_key: &[u8; 5], sector: &mut [u8]) {
+    if sector.len() < 2048 {
+        return;
     }
 
-    let mut lfsr1_lo: u32 = p_key[0] as u32 | 0x100;
-    let mut lfsr1_hi: u32 = p_key[1] as u32;
+    let mut i_t1: u32 = ((title_key[0] ^ sector[0x54]) as u32) | 0x100;
+    let mut i_t2: u32 = (title_key[1] ^ sector[0x55]) as u32;
+    let mut i_t3: u32 = (((title_key[2] as u32)
+        | ((title_key[3] as u32) << 8)
+        | ((title_key[4] as u32) << 16))
+        ^ ((sector[0x56] as u32) | ((sector[0x57] as u32) << 8) | ((sector[0x58] as u32) << 16)))
+        & 0xFF_FFFF;
+    let i_t4_seed = i_t3 & 7;
+    i_t3 = i_t3 * 2 + 8 - i_t4_seed;
 
-    let mut lfsr0: u32 = ((p_key[4] as u32) << 17)
-        | ((p_key[3] as u32) << 9)
-        | (((p_key[2] as u32) << 1) + 8 - (p_key[2] as u32 & 7));
-    lfsr0 = (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;
+    let mut i_t5: u32 = 0;
 
-    let mut combined: u32 = 0;
-    let mut k = [0u8; 5];
+    for byte in sector.iter_mut().take(2048).skip(128) {
+        let mut i_t4 = (TAB2[i_t2 as usize] ^ TAB3[i_t1 as usize]) as u32;
+        i_t2 = i_t1 >> 1;
+        i_t1 = ((i_t1 & 1) << 8) ^ i_t4;
+        i_t4 = TAB5[i_t4 as usize] as u32;
 
-    for byte in &mut k {
-        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 mut i_t6 = (((((((i_t3 >> 3) ^ i_t3) >> 1) ^ i_t3) >> 8) ^ i_t3) >> 5) & 0xFF;
+        i_t3 = (i_t3 << 8) | i_t6;
+        i_t6 = TAB4[i_t6 as usize] as u32;
+        i_t5 += i_t6 + i_t4;
 
-        let o_lfsr0 = (((((((lfsr0 >> 8) ^ lfsr0) >> 1) ^ lfsr0) >> 3) ^ lfsr0) >> 7) as u8;
-        lfsr0 = (lfsr0 >> 8) | ((o_lfsr0 as u32) << 24);
-
-        // TAB5 for LFSR1 output, TAB4 for LFSR0^invert (per libdvdcss css_DecryptKey)
-        combined += TAB5[o_lfsr1 as usize] as u32 + TAB4[(o_lfsr0 ^ invert) as usize] as u32;
-        *byte = (combined & 0xFF) as u8;
-        combined >>= 8;
+        // Inverse of `*p = TAB1[*p] ^ ks`: apply ks then TAB1's inverse.
+        *byte = (*TAB1_INV)[(*byte ^ (i_t5 & 0xFF) as u8) as usize];
+        i_t5 >>= 8;
     }
 
-    // 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
+    // Mark the sector scrambled so the descrambler will process it.
+    sector[0x14] = (sector[0x14] & 0xCF) | 0x10;
 }
 
+/// Inverse permutation of [`TAB1`], built at first use. `TAB1` is a
+/// bijection on 0..256, so `TAB1_INV[TAB1[x]] == x`.
+#[cfg(test)]
+static TAB1_INV: std::sync::LazyLock<[u8; 256]> = std::sync::LazyLock::new(|| {
+    let mut inv = [0u8; 256];
+    for (i, &v) in TAB1.iter().enumerate() {
+        inv[v as usize] = i as u8;
+    }
+    inv
+});
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -144,6 +181,34 @@ mod tests {
         assert_eq!(sector, original);
     }
 
+    /// Cross-check `descramble_sector` against the EXACT output of libdvdcss
+    /// `dvdcss_unscramble` (css.c) for a fixed sector, computed from the
+    /// reference C semantics with the reference tables. Pins the content
+    /// cipher to libdvdcss byte-for-byte.
+    ///
+    /// key = 42 13 37 BE EF, seed (0x54..0x59) = DE AD BE EF 42, body = 0xAA.
+    #[test]
+    fn descramble_matches_libdvdcss_unscramble_vector() {
+        let key = [0x42, 0x13, 0x37, 0xBE, 0xEF];
+        let mut sector = vec![0xAAu8; 2048];
+        sector[0x14] = 0x30;
+        sector[0x54..0x59].copy_from_slice(&[0xDE, 0xAD, 0xBE, 0xEF, 0x42]);
+        descramble_sector(&key, &mut sector);
+        assert_eq!(
+            &sector[0x80..0x90],
+            &[
+                0x81, 0x92, 0x24, 0xA2, 0x46, 0x70, 0x3C, 0x64, 0xA6, 0x91, 0x84, 0xF5, 0x1F, 0x98,
+                0xA0, 0x31
+            ],
+            "descramble body head must match libdvdcss dvdcss_unscramble"
+        );
+        assert_eq!(
+            &sector[0x7F8..0x800],
+            &[0x46, 0x94, 0x80, 0x0E, 0x67, 0x36, 0x65, 0xBC],
+            "descramble body tail must match libdvdcss dvdcss_unscramble"
+        );
+    }
+
     #[test]
     fn descramble_modifies_scrambled() {
         let key = [0x01, 0x02, 0x03, 0x04, 0x05];
@@ -174,67 +239,14 @@ mod tests {
         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]);
-    }
-
-    /// Test 1: css_decrypt_key_roundtrip
+    /// Test 2: descramble inverts scramble over the body.
     ///
-    /// 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.
+    /// The content cipher is NOT a plain XOR involution (it applies TAB1 to
+    /// the ciphertext: `plain = TAB1[cipher] ^ ks`). The true inverse is
+    /// [`scramble_sector`]. Scrambling a plaintext body and then descrambling
+    /// with the same key must reproduce the original body exactly.
     #[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: css_descramble_produces_valid_mpeg2
-    ///
-    /// descramble_sector XORs a keystream into bytes 128..2048. Calling it
-    /// twice with the same key and restored scramble flag should roundtrip,
-    /// since XOR is its own inverse.
-    #[test]
-    fn css_descramble_modifies_encrypted_region() {
+    fn css_descramble_inverts_scramble_over_body() {
         let title_key = [0x42, 0x13, 0x37, 0xBE, 0xEF];
 
         let mut sector = vec![0xAAu8; 2048];
@@ -242,11 +254,10 @@ mod tests {
         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
+        // Scramble the plaintext body into ciphertext.
+        scramble_sector(&title_key, &mut sector);
+        // Header (0..128) unchanged except the flag byte (set by scramble).
         for i in 0..128 {
             if i == 0x14 {
                 continue;
@@ -255,9 +266,18 @@ mod tests {
         }
         // Encrypted region modified
         assert_ne!(&sector[128..256], &original[128..256]);
+
+        // Descramble restores the plaintext body byte-for-byte.
+        descramble_sector(&title_key, &mut sector);
+        assert_eq!(sector[0x14] & 0x30, 0x00, "flag cleared after descramble");
+        assert_eq!(
+            &sector[128..2048],
+            &original[128..2048],
+            "descramble(scramble(body)) did not restore the body"
+        );
     }
 
-    /// Test 4: css_tab1_relationship
+    /// 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
@@ -281,7 +301,7 @@ mod tests {
         }
     }
 
-    /// Test 5: css_tab4_is_bit_reversal
+    /// css_tab4_is_bit_reversal
     ///
     /// TAB4 reverses the bits of each byte: TAB4[0x01] = 0x80, TAB4[0x80] = 0x01, etc.
     #[test]
@@ -303,4 +323,189 @@ mod tests {
             );
         }
     }
+
+    // ── scramble-flag detection (byte 0x14, bits 4-5) ──────────────────────
+
+    /// Only bits 4-5 of byte 0x14 are the CSS scramble flag: the code reads
+    /// `sector[0x14] & 0x30 == 0` (bits 6-7, i.e. 0x40/0x80, are masked out by
+    /// 0x30). A sector with 0x14 == 0x40 or 0x80 must therefore be treated as
+    /// UNSCRAMBLED and left byte-for-byte unchanged. This guards against a
+    /// too-wide mask silently "descrambling" (and thus corrupting) clear data.
+    ///
+    /// Grounding: CSS sector header byte 0x14 — copyright/scramble bits live
+    /// in bits 4-5; the masked value 0 means not scrambled.
+    /// Mutation: widen the mask `0x30` to `0x70`/`0xF0` -> 0x40/0x80 would be
+    /// seen as scrambled and the body would change.
+    #[test]
+    fn descramble_treats_high_bits_of_0x14_as_clear() {
+        let key = [0x01, 0x02, 0x03, 0x04, 0x05];
+        for &flag in &[0x40u8, 0x80, 0xC0, 0x0F, 0x4F, 0x8F] {
+            let mut sector = vec![0xAA; 2048];
+            sector[0x14] = flag;
+            sector[0x54..0x59].copy_from_slice(&[0x11, 0x22, 0x33, 0x44, 0x55]);
+            let original = sector.clone();
+            descramble_sector(&key, &mut sector);
+            assert_eq!(
+                sector, original,
+                "byte 0x14 = {flag:#04x} has flag bits 4-5 clear; sector must be untouched"
+            );
+        }
+    }
+
+    /// Each individual scramble bit (4 and 5) independently marks the sector
+    /// as encrypted: 0x10 and 0x20 must both trigger descrambling.
+    ///
+    /// Grounding: `(0x10 >> 4) & 3 == 1`, `(0x20 >> 4) & 3 == 2` — both
+    /// nonzero.
+    /// Mutation: change `!= 0` early-return condition to `== 3` -> a sector
+    /// flagged only 0x10 or 0x20 would be skipped and left scrambled.
+    #[test]
+    fn descramble_triggers_on_either_flag_bit() {
+        let key = [0x01, 0x02, 0x03, 0x04, 0x05];
+        for &flag in &[0x10u8, 0x20, 0x30] {
+            let mut sector = vec![0xAA; 2048];
+            sector[0x14] = flag;
+            sector[0x54..0x59].copy_from_slice(&[0xDE, 0xAD, 0xBE, 0xEF, 0x42]);
+            let original = sector.clone();
+            descramble_sector(&key, &mut sector);
+            assert_ne!(
+                &sector[128..256],
+                &original[128..256],
+                "flag {flag:#04x} (bits 4-5 nonzero) must descramble the body"
+            );
+        }
+    }
+
+    /// After descrambling, ONLY the two scramble bits are cleared (`& 0xCF`);
+    /// bits 6 and 7 of byte 0x14 must be preserved. A sector with 0x14 == 0xF0
+    /// becomes 0xC0 (bits 6,7 kept, bits 4,5 cleared), NOT 0x00.
+    ///
+    /// Grounding: code does `sector[0x14] &= 0xCF`; 0xF0 & 0xCF == 0xC0.
+    /// Mutation: change `&= 0xCF` to `= 0` or `&= 0x0F` -> the preserved
+    /// high bits assert fails.
+    #[test]
+    fn descramble_clear_preserves_high_bits_of_0x14() {
+        let key = [0x01, 0x02, 0x03, 0x04, 0x05];
+        let mut sector = vec![0x00; 2048];
+        sector[0x14] = 0xF0; // bits 4-7 set; bits 4-5 are the flag
+        sector[0x54..0x59].copy_from_slice(&[0x00; 5]);
+        descramble_sector(&key, &mut sector);
+        assert_eq!(
+            sector[0x14], 0xC0,
+            "scramble bits cleared, bits 6-7 preserved (0xF0 & 0xCF)"
+        );
+    }
+
+    // ── header / body boundary (encrypted region is 0x80..0x800) ───────────
+
+    /// The encrypted region is exactly bytes 0x80..0x800. Bytes 0x00..0x80
+    /// (the header) must NOT be modified by the keystream — except byte 0x14
+    /// whose flag is cleared. In particular the sector-seed bytes 0x54..0x59
+    /// (which live inside the header) must survive untouched, since the
+    /// descrambler reads them but never writes them.
+    ///
+    /// Grounding: loop is `sector.iter_mut().take(2048).skip(128)` -> indices
+    /// 128..2048 only.
+    /// Mutation: change `.skip(128)` to `.skip(0)` -> header bytes (incl. the
+    /// seed) get XORed and this fails.
+    #[test]
+    fn descramble_leaves_header_and_seed_intact() {
+        let key = [0x42, 0x13, 0x37, 0xBE, 0xEF];
+        let mut sector = vec![0x5Au8; 2048];
+        sector[0x14] = 0x30;
+        let seed = [0xDE, 0xAD, 0xBE, 0xEF, 0x42];
+        sector[0x54..0x59].copy_from_slice(&seed);
+        let original = sector.clone();
+        descramble_sector(&key, &mut sector);
+        for i in 0..0x80usize {
+            if i == 0x14 {
+                continue;
+            }
+            assert_eq!(
+                sector[i], original[i],
+                "header byte {i:#04x} must be untouched"
+            );
+        }
+        assert_eq!(&sector[0x54..0x59], &seed, "sector seed must survive");
+    }
+
+    /// The descrambler must touch the WHOLE body 0x80..0x800, not just a
+    /// prefix. With a constant body and constant key, the keystream is
+    /// non-degenerate enough that the very last sector byte (index 2047) is
+    /// altered. This guards the loop bound `.take(2048)` against an
+    /// off-by-one that would leave the final byte(s) scrambled.
+    ///
+    /// Grounding: encrypted region end is 0x800 == 2048 (exclusive).
+    /// Mutation: change `.take(2048)` to `.take(2047)` -> last byte unchanged,
+    /// assert fires (keystream byte for the last position is verified nonzero
+    /// below by the round-trip, and this body is all-zero so any XOR shows).
+    #[test]
+    fn descramble_covers_final_body_byte() {
+        let key = [0x42, 0x13, 0x37, 0xBE, 0xEF];
+        let mut sector = vec![0x00u8; 2048];
+        sector[0x14] = 0x30;
+        sector[0x54..0x59].copy_from_slice(&[0x11, 0x22, 0x33, 0x44, 0x55]);
+        descramble_sector(&key, &mut sector);
+        // Body was all zero; any nonzero in [0x80,0x800) is keystream. Confirm
+        // the keystream reaches the final byte. (If the last keystream byte
+        // happened to be 0 this could be a flaky test, so assert the run-end
+        // region as a whole differs from zero.)
+        assert_ne!(
+            &sector[2040..2048],
+            &[0u8; 8][..],
+            "the tail of the body must be descrambled (loop must reach index 2047)"
+        );
+    }
+
+    /// Descramble is keyed by `title_key XOR seed`: two different title keys
+    /// produce two different bodies for the same scrambled input. A cipher
+    /// that ignored the title key (or mixed it in wrongly) would yield
+    /// identical output — silent wrong-key decryption.
+    ///
+    /// Grounding: per-sector key = title_key[i] ^ sector[0x54+i].
+    /// Mutation: in the `key` array drop the `title_key[i] ^` term -> both
+    /// keys give the same body, assert fires.
+    #[test]
+    fn descramble_output_depends_on_title_key() {
+        let seed = [0xDE, 0xAD, 0xBE, 0xEF, 0x42];
+        let make = |k: &[u8; 5]| {
+            let mut s = vec![0x00u8; 2048];
+            s[0x14] = 0x30;
+            s[0x54..0x59].copy_from_slice(&seed);
+            descramble_sector(k, &mut s);
+            s
+        };
+        let a = make(&[0x01, 0x02, 0x03, 0x04, 0x05]);
+        let b = make(&[0x01, 0x02, 0x03, 0x04, 0x06]); // differs in last byte
+        assert_ne!(
+            &a[128..2048],
+            &b[128..2048],
+            "different title keys must descramble differently"
+        );
+    }
+
+    /// Descramble is keyed by the sector seed too: same title key, different
+    /// seed -> different body. Pins that bytes 0x54..0x59 actually feed the
+    /// keystream (not just the per-sector XOR key).
+    ///
+    /// Mutation: replace `seed` array reads with a constant -> both seeds give
+    /// the same body, assert fires.
+    #[test]
+    fn descramble_output_depends_on_seed() {
+        let key = [0x01, 0x02, 0x03, 0x04, 0x05];
+        let make = |seed: [u8; 5]| {
+            let mut s = vec![0x00u8; 2048];
+            s[0x14] = 0x30;
+            s[0x54..0x59].copy_from_slice(&seed);
+            descramble_sector(&key, &mut s);
+            s
+        };
+        let a = make([0x11, 0x22, 0x33, 0x44, 0x55]);
+        let b = make([0x11, 0x22, 0x33, 0x44, 0x56]);
+        assert_ne!(
+            &a[128..2048],
+            &b[128..2048],
+            "different seeds must descramble differently"
+        );
+    }
 }

src/css/mod.rs

@@ -1,110 +1,269 @@
 //! CSS (Content Scramble System) — DVD disc encryption.
 //!
 //! CSS uses a weak 40-bit LFSR stream cipher (broken since 1999).
-//! No keys needed — the title key is cracked from encrypted content
-//! using a known-plaintext attack on MPEG-2 PES headers.
+//!
+//! The title key is recovered keylessly: [`crack_key`] runs the Stevenson
+//! known-plaintext attack (see the [`stevenson`] module) on the scrambled
+//! data, needing no player keys, disc-key crack, or external key file.
+//! Sectors are then decrypted with [`descramble_sector`].
 //!
 //! Usage:
 //! ```rust,ignore
-//! let key = css::crack_key(reader, &extents)?;
-//! css::descramble_sector(&key, &mut sector);
+//! if let Some(state) = css::crack_key(reader, extents, batch) {
+//!     css::descramble_sector(&state, &mut sector);
+//! }
 //! ```
 
-pub mod auth;
-pub mod crack;
 pub mod lfsr;
+pub mod stevenson;
 pub(crate) mod tables;
 
 use crate::disc::Extent;
-use crate::drive::Drive;
 use crate::sector::SectorSource;
 
+/// Consecutive CSS-locked (`05/6F/03`) reads before the crack scan early-bails.
+/// The bus-auth read gate is global (all-or-nothing), so a run this long means
+/// it is shut and nothing here is crackable — bail instead of grinding the full
+/// 50_000-sector budget (which is what made rc5 appear to hang on a wedged USB
+/// bridge). The counter resets to 0 on any readable batch.
+const CSS_LOCKED_BAIL: u32 = 64;
+
 /// CSS decryption state for a DVD title.
 #[derive(Debug, Clone)]
 pub struct CssState {
-    /// Cracked 5-byte title key
+    /// 5-byte CSS title key (from SCSI auth or the crack fallback).
     pub title_key: [u8; 5],
+    /// LBA half-open span `[start, end)` of the extent set this key was
+    /// cracked from. CSS title keys are per-VTS: a key cracked from one
+    /// VTS does NOT descramble a title living in a different VTS. The mux
+    /// path checks whether the title being opened overlaps this span; if
+    /// not, it re-cracks from that title's own extents. `None` for keys
+    /// of unknown provenance (e.g. test fixtures) — treated as "applies
+    /// everywhere" for backward compatibility.
+    pub crack_span: Option<(u32, u32)>,
 }
 
-/// Inputs for CSS key acquisition.
+/// Recover the CSS title key with no keys, by scanning scrambled sectors and
+/// running the Stevenson known-plaintext attack (see the [`stevenson`] module).
 ///
-/// 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).
-///
-/// `live_drive` 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]>,
+/// The crib comes from `AttackPattern`: a scrambled sector's cleartext region
+/// (bytes 0x00..0x80) often ends in a short-period repeating run (stuffing /
+/// constant fill); the attack assumes that run continues across the 0x80
+/// boundary into the encrypted region, giving the known plaintext the 2^16
+/// LFSR recovery needs. We scan up to 50000 sectors across the
+/// extents and return the first sector that yields a key — no player keys, no
+/// disc-key crack. Works on a live drive (after bus-auth unlocks reads) and on
+/// disc images alike.
+pub fn crack_key(
+    reader: &mut dyn SectorSource,
+    extents: &[Extent],
+    batch_sectors: u16,
+) -> Option<CssState> {
+    crack_key_halt(reader, extents, batch_sectors, None)
 }
 
-/// Acquire a CSS title key using whichever inputs the context provides.
+/// Outcome of a CSS crack scan that distinguishes the THREE cases the bare
+/// `Option<CssState>` conflated (and which caused a silent-failure bug:
+/// scrambled-but-uncracked content was treated as "unencrypted" and muxed as
+/// plaintext garbage at exit 0):
 ///
-/// 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
+/// - [`CrackOutcome::Cracked`] — a scrambled sector yielded a title key.
+/// - [`CrackOutcome::Unencrypted`] — NO scrambled sector was seen across the
+///   scanned extents (`is_scrambled` never true): the content is genuinely
+///   plaintext, so proceeding without a key is correct.
+/// - [`CrackOutcome::ScrambledUncracked`] — scrambled sectors WERE seen but no
+///   key could be recovered (the Stevenson attack found no crackable crib, or
+///   the scrambled region was unreadable). The content is encrypted; muxing it
+///   as plaintext would emit garbage, so callers MUST surface a hard error
+///   ([`crate::error::Error::CssKeyMissing`]) instead of falling through to
+///   "unencrypted".
+#[derive(Debug, Clone)]
+pub enum CrackOutcome {
+    Cracked(CssState),
+    Unencrypted,
+    ScrambledUncracked,
 }
 
-/// Crack the CSS title key by reading encrypted sectors and applying
-/// a known-plaintext attack on MPEG-2 headers.
+impl CrackOutcome {
+    /// The cracked `CssState`, if any. `None` for `Unencrypted` /
+    /// `ScrambledUncracked`. Lets the `Option`-returning wrappers stay thin.
+    pub fn into_state(self) -> Option<CssState> {
+        match self {
+            CrackOutcome::Cracked(s) => Some(s),
+            _ => None,
+        }
+    }
+
+    /// True when scrambled sectors were seen but no key was recovered — the
+    /// case callers must surface as a hard error instead of "unencrypted".
+    pub fn is_scrambled_uncracked(&self) -> bool {
+        matches!(self, CrackOutcome::ScrambledUncracked)
+    }
+}
+
+/// [`crack_key`] returning the full [`CrackOutcome`] (Cracked / Unencrypted /
+/// ScrambledUncracked) so callers can distinguish "genuinely unencrypted" from
+/// "encrypted but uncrackable" — the latter must become a hard error, never a
+/// silent fall-through to plaintext.
+pub fn crack_key_outcome(
+    reader: &mut dyn SectorSource,
+    extents: &[Extent],
+    batch_sectors: u16,
+    halt: Option<&crate::halt::Halt>,
+) -> CrackOutcome {
+    crack_key_scan(reader, extents, batch_sectors, halt, true)
+}
+
+/// [`crack_key`] with an optional cooperative-cancellation token.
 ///
-/// Crack the CSS title key by scanning scrambled sectors across extents.
-///
-/// 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.
-pub fn crack_key(reader: &mut dyn SectorSource, extents: &[Extent]) -> Option<CssState> {
+/// "No silent hangs": the crack scans up to 50_000 sectors, which on a live
+/// drive hitting bad sectors can take a long time. This variant polls `halt`
+/// once per batch (the same cadence sweep/patch use) so an operator Stop or a
+/// scan-level watchdog can interrupt the scan, and emits a
+/// `freemkv::heartbeat` beat ("css_crack") each batch so a stuck scan is
+/// visible in the log.
+pub fn crack_key_halt(
+    reader: &mut dyn SectorSource,
+    extents: &[Extent],
+    batch_sectors: u16,
+    halt: Option<&crate::halt::Halt>,
+) -> Option<CssState> {
+    crack_key_scan(reader, extents, batch_sectors, halt, false).into_state()
+}
+
+/// The crack scan, returning the full [`CrackOutcome`]. Tracks a
+/// `saw_scrambled` flag so a scrambled-but-uncracked disc is distinguished
+/// from a genuinely-unencrypted one (the [`crack_key`] / [`crack_key_halt`]
+/// `Option` wrappers collapse both to `None`).
+fn crack_key_scan(
+    reader: &mut dyn SectorSource,
+    extents: &[Extent],
+    batch_sectors: u16,
+    halt: Option<&crate::halt::Halt>,
+    // True only on the INITIAL scan: a fully CSS-locked (`05/6F/03`) result is a
+    // hard `ScrambledUncracked`. False on the per-VTS re-crack so a lapsed-AGID
+    // locked read returns None instead of killing a genuinely crackable title.
+    fail_on_locked: bool,
+) -> CrackOutcome {
+    // Batch the reads: a live optical drive at 1 sector/read is glacial, and the
+    // crack only needs to FIND one scrambled sector whose 0x80 plaintext matches
+    // a known PES header. `batch_sectors` MUST be sized to the source — a drive
+    // rejects a READ(10) larger than its per-command max (DVD = 16) and
+    // `Drive::read` does not chunk, so an over-large batch fails every read and
+    // scans nothing. Callers pass `detect_max_batch_sectors(device_path)` for a
+    // live drive, a file-safe value for an image, or 1 to force per-sector.
+    let batch = (batch_sectors.max(1)) as u32;
+    // Record the LBA span the key is being cracked from so the per-title mux
+    // path can tell whether a later title lives in the same VTS (overlaps the
+    // span → key applies) or a different one (→ re-crack). Half-open [min,max).
+    let crack_span = extents
+        .iter()
+        .filter(|e| e.sector_count > 0)
+        .map(|e| (e.start_lba, e.start_lba.saturating_add(e.sector_count)))
+        .reduce(|(amin, amax), (bmin, bmax)| (amin.min(bmin), amax.max(bmax)));
     let mut tried = 0u32;
-    let max_tries = 50_000;
+    let max_tries = 50_000u32;
+    let mut buf = vec![0u8; batch as usize * 2048];
+    let mut hb = crate::progress::Heartbeat::new("css_crack");
+    // Track whether ANY scrambled sector was observed. If we exhaust the scan
+    // budget having seen scrambled data but never recovered a key, the content
+    // is encrypted-but-uncrackable — a HARD failure the caller must surface,
+    // NOT silently treat as unencrypted (which would mux scrambled MPEG as
+    // plaintext → garbage at exit 0). See `CrackOutcome::ScrambledUncracked`.
+    let mut saw_scrambled = false;
+    // A read rejected with sense `05/6F/03` ("scrambled sector without
+    // authentication") is positive proof of CSS encryption — never collapse it
+    // to "unencrypted". A run of consecutive locked reads means the bus-auth
+    // gate is shut (it is global, so reads are all-or-nothing), so the scan
+    // early-bails. `consecutive_locked` resets on any readable batch, so a
+    // crackable title (gate open) never trips it.
+    let mut saw_locked = false;
+    let mut consecutive_locked = 0u32;
 
-    for ext in extents {
-        let mut i = 0;
+    'outer: for (extent_idx, ext) in extents.iter().enumerate() {
+        let mut i = 0u32;
         while i < ext.sector_count && tried < max_tries {
-            let mut buf = vec![0u8; 2048];
-            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 });
+            // Cooperative cancellation — poll once per batch, the same cadence
+            // sweep/patch use, so a Stop / watchdog can interrupt the scan.
+            if let Some(h) = halt {
+                if h.is_cancelled() {
+                    break 'outer;
                 }
+            }
+            // Liveness beacon: a long scan over a damaged disc stays visible.
+            // The heartbeat is time-throttled; only when it actually beats do
+            // we emit the crack-specific context (tried/lba/extent_idx).
+            if hb.tick(tried as u64, max_tries as u64) {
+                tracing::debug!(
+                    target: "freemkv::heartbeat",
+                    phase = "css_crack",
+                    tried,
+                    lba = ext.start_lba + i,
+                    extent_idx,
+                    "scanning"
+                );
+            }
+            let n = (ext.sector_count - i).min(batch);
+            let want = n as usize * 2048;
+            match reader.read_sectors(ext.start_lba + i, n as u16, &mut buf[..want], true) {
+                Ok(_) => {
+                    // A readable batch: the gate is open — reset the locked run.
+                    consecutive_locked = 0;
+                    for s in 0..n as usize {
                         tried += 1;
+                        let sect = &buf[s * 2048..(s + 1) * 2048];
+                        // Use the HARDENED pack-gated check (Fix 3): a clear stub
+                        // sector with stray bits at 0x14 must NOT count as
+                        // scramble evidence, or a genuinely-unencrypted title
+                        // would falsely report ScrambledUncracked (a false E7023).
+                        if is_scrambled_pack(sect) {
+                            saw_scrambled = true;
+                            if let Some(key) = stevenson::crack_title_key(sect) {
+                                return CrackOutcome::Cracked(CssState {
+                                    title_key: key,
+                                    crack_span,
+                                });
                             }
-            i += 1;
                         }
                         if tried >= max_tries {
-            break;
+                            break 'outer;
+                        }
+                    }
+                }
+                // A failed batch still counts toward the budget so a damaged
+                // region can't loop forever. A CSS-locked failure (`05/6F/03`)
+                // proves encryption and, in a long enough run, means the read
+                // gate is shut — track it and early-bail rather than grind.
+                Err(e) => {
+                    tried += n;
+                    if e.scsi_sense().is_some_and(|s| s.is_css_locked()) {
+                        saw_locked = true;
+                        consecutive_locked += 1;
+                        if consecutive_locked >= CSS_LOCKED_BAIL {
+                            break 'outer;
+                        }
+                    } else {
+                        consecutive_locked = 0;
+                    }
+                }
+            }
+            i += n;
         }
     }
 
-    None
+    // Budget exhausted / extents walked / early-bailed with no key recovered.
+    // The disc is ENCRYPTED-but-uncracked (a hard failure on the initial scan)
+    // when EITHER a scrambled sector was actually seen, OR — on the initial scan
+    // only (`fail_on_locked`) — every read was CSS-locked (`05/6F/03`), itself
+    // proof of scrambling. A re-crack (`fail_on_locked` false) stays soft: a
+    // lapsed-AGID locked read yields None, not a hard fail, so a crackable title
+    // in another VTS isn't killed. Only a scan that saw neither a scrambled
+    // sector nor a CSS-lock is genuinely unencrypted.
+    if saw_scrambled || (saw_locked && fail_on_locked) {
+        CrackOutcome::ScrambledUncracked
+    } else {
+        CrackOutcome::Unencrypted
+    }
 }
 
 /// Descramble a single CSS-encrypted sector in place.
@@ -113,6 +272,616 @@ pub fn descramble_sector(state: &CssState, sector: &mut [u8]) {
 }
 
 /// Check if a sector has the CSS scramble flag set.
+///
+/// This is the RAW flag test — bits 4-5 of the sub-header byte 0x14 — used by
+/// the descramble loop (`decrypt::decrypt_sectors`), which has already committed
+/// to descrambling a known title's VOB data and only needs to skip the clear
+/// NAV packs interleaved in it. For the CRACK SCAN's "did this disc actually
+/// contain scrambled content?" decision (which must not false-positive on a
+/// clear stub), use [`is_scrambled_pack`] instead.
 pub fn is_scrambled(sector: &[u8]) -> bool {
     sector.len() >= 2048 && (sector[0x14] >> 4) & 0x03 != 0
 }
+
+/// The 4-byte MPEG-2 Program Stream pack-start code (`00 00 01 BA`) every DVD
+/// video sector opens with. CSS leaves the clear header (`0x00..0x80`)
+/// untouched, so this signature survives scrambling.
+pub(crate) const PACK_START: [u8; 4] = [0x00, 0x00, 0x01, 0xBA];
+
+/// Check if a sector is a CSS-scrambled DVD **video pack** — the HARDENED test
+/// the crack scan uses to set its `saw_scrambled` evidence flag (Fix 3).
+///
+/// [`is_scrambled`] keys solely on bits 4-5 of byte 0x14. That single byte is
+/// only meaningful inside a real DVD sector — an MPEG-2 Program Stream pack,
+/// which ALWAYS begins with the 32-bit pack-start code `00 00 01 BA` at offset
+/// 0x00. A tiny clear / nav-only stub (a 0.5 s menu loop, an FBI-warning title)
+/// can carry arbitrary bytes that happen to set bits 4-5 of byte 0x14; trusting
+/// byte 0x14 alone there would flip the scan's `saw_scrambled` gate and make a
+/// genuinely-UNENCRYPTED title report `ScrambledUncracked` — a false E7023.
+///
+/// Requiring the pack-start signature FIRST means only a sector that is
+/// structurally a DVD video pack can be counted as scramble evidence. This does
+/// NOT weaken the genuine "encrypted but uncrackable" hard-fail: a real
+/// scrambled feature is made of valid PS packs, so its scrambled sectors still
+/// pass this check and still drive `ScrambledUncracked` when no key cracks. (The
+/// descramble loop keeps the looser [`is_scrambled`]: by the time it runs we
+/// already know the title is CSS, and it only needs to skip interleaved clear
+/// NAV packs — a wrongly-skipped or wrongly-included sector there is recoverable
+/// per-sector, whereas a false scramble verdict in the scan poisons the whole
+/// title's outcome.)
+pub fn is_scrambled_pack(sector: &[u8]) -> bool {
+    sector.len() >= 2048 && sector[0x00..0x04] == PACK_START && (sector[0x14] >> 4) & 0x03 != 0
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::error::{Error, Result};
+
+    // ── is_scrambled ───────────────────────────────────────────────────────
+
+    /// is_scrambled returns false for any buffer shorter than one sector,
+    /// WITHOUT indexing byte 0x14 (which would panic on a tiny buffer). The
+    /// length guard is short-circuited before the flag read.
+    ///
+    /// Grounding: `sector.len() >= 2048 && (sector[0x14] >> 4) & 0x03 != 0` —
+    /// `&&` short-circuits so a 20-byte buffer never reads index 0x14.
+    /// Mutation: swap the operands so the flag is read first
+    /// (`(sector[0x14]...) && sector.len() >= 2048`) -> panics indexing a
+    /// 20-byte slice; this test catches it.
+    #[test]
+    fn is_scrambled_short_buffer_is_false_no_panic() {
+        assert!(!is_scrambled(&[]));
+        assert!(!is_scrambled(&[0u8; 20])); // shorter than 0x14+1 even
+        assert!(!is_scrambled(&[0xFFu8; 2047])); // one byte short of a sector
+    }
+
+    /// is_scrambled keys on bits 4-5 of byte 0x14 (the CSS scramble field).
+    /// A full sector flagged 0x10/0x20/0x30 is scrambled; 0x00 and the
+    /// high-bit-only values 0x40/0x80 are clear.
+    ///
+    /// Grounding: `(sector[0x14] >> 4) & 0x03`.
+    /// Mutation: widen mask to `& 0x0F` -> 0x40 reports scrambled, the 0x40
+    /// assert fails.
+    #[test]
+    fn is_scrambled_uses_bits_4_5_only() {
+        let mut s = vec![0u8; 2048];
+        for (flag, expected) in [
+            (0x00u8, false),
+            (0x10, true),
+            (0x20, true),
+            (0x30, true),
+            (0x40, false),
+            (0x80, false),
+            (0xC0, false),
+            (0xFF, true), // bits 4-5 set within 0xFF
+        ] {
+            s[0x14] = flag;
+            assert_eq!(
+                is_scrambled(&s),
+                expected,
+                "flag byte {flag:#04x} scramble detection"
+            );
+        }
+    }
+
+    /// is_scrambled accepts exactly 2048 bytes as the minimum (boundary at the
+    /// inclusive value 2048).
+    ///
+    /// Grounding: `sector.len() >= 2048`.
+    /// Mutation: change `>= 2048` to `> 2048` -> an exact 2048-byte scrambled
+    /// sector reports false; this fails.
+    #[test]
+    fn is_scrambled_exact_sector_length_accepted() {
+        let mut s = vec![0u8; 2048];
+        s[0x14] = 0x30;
+        assert!(is_scrambled(&s), "exactly 2048 bytes must be eligible");
+    }
+
+    /// Fix 3 hardening: `is_scrambled_pack` (the crack-scan evidence gate)
+    /// requires BOTH the MPEG-PS pack-start code at 0x00 AND the 0x14 scramble
+    /// bits. A clear / nav-only stub whose bytes happen to set bits 4-5 of 0x14
+    /// but lacks the pack-start is NOT counted as scramble evidence — without
+    /// this the scan flips `saw_scrambled` and a genuinely unencrypted title
+    /// reports `ScrambledUncracked` (the false E7023). The looser `is_scrambled`
+    /// (descramble gate) still reads the same sector as flagged.
+    ///
+    /// Grounding: `sector[0x00..0x04] == 00 00 01 BA && (sector[0x14] >> 4)...`.
+    /// Mutation: drop the pack-start clause -> the 0x14-only sector counts as a
+    /// scrambled pack; the first assert fails.
+    #[test]
+    fn is_scrambled_pack_requires_pack_start_signature() {
+        let mut s = vec![0u8; 2048];
+        s[0x14] = 0x30; // scramble bits set, but no pack-start at 0x00
+        assert!(
+            !is_scrambled_pack(&s),
+            "0x14 bits without the MPEG-PS pack-start must NOT count as a scrambled pack"
+        );
+        // The looser descramble-gate check still sees the raw flag.
+        assert!(is_scrambled(&s), "is_scrambled keys on the 0x14 flag alone");
+        // A near-miss pack-start (wrong final byte) is still rejected.
+        s[0x00..0x04].copy_from_slice(&[0x00, 0x00, 0x01, 0xBB]);
+        assert!(
+            !is_scrambled_pack(&s),
+            "a wrong pack-start byte must not qualify"
+        );
+        // The real signature flips it to a scrambled pack.
+        s[0x00..0x04].copy_from_slice(&PACK_START);
+        assert!(
+            is_scrambled_pack(&s),
+            "valid pack-start + 0x14 bits → scrambled pack"
+        );
+    }
+
+    // ── crack_key scanning over a mock SectorSource ────────────────────────
+
+    /// Records every (lba, count) read; returns a caller-supplied flag byte at
+    /// 0x14 so we can drive scrambled/clear sectors, or an injected error.
+    struct MockSource {
+        reads: std::cell::RefCell<Vec<u32>>,
+        flag_byte: u8,
+        fail_all: bool,
+        /// Every read fails with CSS-locked sense `05/6F/03` (drive refusing
+        /// scrambled reads because the bus-auth gate isn't open).
+        lock_all: bool,
+        /// When set, the sector at `crackable.0` is served as a full
+        /// Stevenson-crackable scrambled sector (`crackable.1`, 2048 bytes)
+        /// instead of the uniform `flag_byte` fill. Lets the scan actually
+        /// reach `CrackOutcome::Cracked` from a synthetic ISO.
+        crackable: Option<(u32, Vec<u8>)>,
+    }
+
+    impl MockSource {
+        fn new(flag_byte: u8) -> Self {
+            Self {
+                reads: std::cell::RefCell::new(Vec::new()),
+                flag_byte,
+                fail_all: false,
+                lock_all: false,
+                crackable: None,
+            }
+        }
+    }
+
+    /// Build a Stevenson-crackable scrambled sector for `(title_key, seed)`:
+    /// the cleartext header (0x59..0x80) carries a periodic run that continues
+    /// across the 0x80 boundary into the encrypted region — the crib
+    /// `stevenson::crack_title_key` recovers a key from. Mirrors the
+    /// `synth_periodic_sector` fixture in the stevenson tests but built here
+    /// from the crate-internal `scramble_sector`.
+    fn crackable_sector(title_key: &[u8; 5], seed: &[u8; 5], period: usize) -> Vec<u8> {
+        const RUN_START: usize = 0x59;
+        const SEED_OFFSET: usize = 0x54;
+        let mut plaintext = vec![0u8; 2048];
+        plaintext[0x00..0x04].copy_from_slice(&PACK_START); // valid DVD pack header
+        plaintext[0x14] = 0x10; // scramble flag
+        let pat: Vec<u8> = (0..period)
+            .map(|k| (0xA0u8.wrapping_add(k as u8)) ^ 0x5A)
+            .collect();
+        for (i, b) in plaintext.iter_mut().enumerate().skip(RUN_START) {
+            *b = pat[i % period];
+        }
+        plaintext[SEED_OFFSET..SEED_OFFSET + 5].copy_from_slice(seed);
+        lfsr::scramble_sector(title_key, &mut plaintext);
+        plaintext
+    }
+
+    impl SectorSource for MockSource {
+        fn read_sectors(
+            &mut self,
+            lba: u32,
+            count: u16,
+            buf: &mut [u8],
+            _recovery: bool,
+        ) -> Result<usize> {
+            self.reads.borrow_mut().push(lba);
+            if self.lock_all {
+                return Err(Error::DiscRead {
+                    sector: lba as u64,
+                    status: Some(2),
+                    sense: Some(crate::scsi::ScsiSense {
+                        sense_key: 0x05,
+                        asc: 0x6F,
+                        ascq: 0x03,
+                    }),
+                });
+            }
+            if self.fail_all {
+                return Err(Error::DecryptFailed);
+            }
+            let n = count as usize * 2048;
+            let end = n.min(buf.len());
+            for b in buf[..end].iter_mut() {
+                *b = 0;
+            }
+            // Fill each sector in the batch with the uniform flag byte, EXCEPT a
+            // designated crackable LBA which gets the full synthetic sector.
+            for s in 0..count as u32 {
+                let sect_lba = lba + s;
+                let base = s as usize * 2048;
+                if base + 2048 > end {
+                    break;
+                }
+                match &self.crackable {
+                    Some((clba, sector)) if *clba == sect_lba => {
+                        buf[base..base + 2048].copy_from_slice(sector);
+                    }
+                    _ => {
+                        // Real DVD video sectors always open with the MPEG-PS
+                        // pack-start code; `is_scrambled` (Fix 3) requires it
+                        // before trusting the 0x14 scramble bits, so the fixture
+                        // must include it for a `flag_byte` of 0x30 to register
+                        // as scrambled.
+                        buf[base..base + 4].copy_from_slice(&PACK_START);
+                        buf[base + 0x14] = self.flag_byte;
+                    }
+                }
+            }
+            Ok(n)
+        }
+    }
+
+    /// crack_key caps total scanned sectors at 50_000 even when extents are
+    /// far larger, and counts EVERY scanned sector (clear ones included)
+    /// toward the budget. With one 200_000-sector extent of clear sectors, it
+    /// must read exactly 50_000 sectors and return None — never run away.
+    ///
+    /// Grounding: `let max_tries = 50_000; ... tried += 1` before the read,
+    /// loop guard `tried < max_tries`.
+    /// Mutation: change `50_000` to `500_000` -> read count exceeds 50_000;
+    /// the exact-count assert fails. Removing the `tried += 1` increment ->
+    /// would read all 200_000; also fails.
+    #[test]
+    fn crack_key_caps_total_tries_at_50000() {
+        let mut src = MockSource::new(0x00); // clear sectors, never a hit
+        let extents = [Extent {
+            start_lba: 0,
+            sector_count: 200_000,
+        }];
+        let res = crack_key(&mut src, &extents, 1);
+        assert!(res.is_none(), "clear sectors yield no key");
+        assert_eq!(
+            src.reads.borrow().len(),
+            50_000,
+            "scan must stop at the 50_000-sector budget"
+        );
+    }
+
+    // ── CrackOutcome: scrambled-but-uncracked vs genuinely unencrypted (Fix 6) ─
+
+    /// A scan over CLEAR sectors (scramble flag never set) returns
+    /// `Unencrypted` — the content is genuinely plaintext, so proceeding
+    /// without a key is correct.
+    #[test]
+    fn crack_outcome_clear_sectors_is_unencrypted() {
+        let mut src = MockSource::new(0x00); // never scrambled
+        let extents = [Extent {
+            start_lba: 0,
+            sector_count: 100,
+        }];
+        let outcome = crack_key_outcome(&mut src, &extents, 1, None);
+        assert!(
+            matches!(outcome, CrackOutcome::Unencrypted),
+            "no scrambled sector seen → Unencrypted, got {outcome:?}"
+        );
+        // The Option wrapper collapses Unencrypted → None.
+        assert!(crack_key(&mut MockSource::new(0x00), &extents, 1).is_none());
+    }
+
+    /// THE Fix 6 regression: a scan that SEES scrambled sectors (flag set) but
+    /// recovers no key (the mock's zeroed data has no Stevenson crib) must
+    /// return `ScrambledUncracked` — a HARD failure — NOT `Unencrypted`. The
+    /// old code conflated this with "unencrypted" and muxed scrambled MPEG as
+    /// plaintext (garbage at exit 0).
+    #[test]
+    fn crack_outcome_scrambled_uncracked_is_hard_failure() {
+        let mut src = MockSource::new(0x30); // scrambled flag set, no crackable crib
+        let extents = [Extent {
+            start_lba: 0,
+            sector_count: 100,
+        }];
+        let outcome = crack_key_outcome(&mut src, &extents, 1, None);
+        assert!(
+            outcome.is_scrambled_uncracked(),
+            "scrambled sectors seen but no key → ScrambledUncracked, got {outcome:?}"
+        );
+        // The legacy Option wrapper still collapses this to None (the callers
+        // that need the distinction now use crack_key_outcome instead).
+        assert!(crack_key(&mut MockSource::new(0x30), &extents, 1).is_none());
+    }
+
+    /// Even when every read FAILS, a scan that never managed to observe a
+    /// scrambled sector reports `Unencrypted` (we cannot prove encryption from
+    /// unreadable data alone — the AACS/keydb paths and the disc-level
+    /// `css_error` plumbing cover genuinely unreadable encrypted discs).
+    #[test]
+    fn crack_outcome_all_reads_fail_is_unencrypted() {
+        let mut src = MockSource::new(0x30);
+        src.fail_all = true; // no sector is ever inspected
+        let extents = [Extent {
+            start_lba: 0,
+            sector_count: 10,
+        }];
+        let outcome = crack_key_outcome(&mut src, &extents, 1, None);
+        assert!(
+            matches!(outcome, CrackOutcome::Unencrypted),
+            "no readable scrambled sector → Unencrypted, got {outcome:?}"
+        );
+    }
+
+    /// Fix C (rc.5.1): on the INITIAL scan, a drive that refuses every read with
+    /// CSS-locked sense (`05/6F/03`) is encrypted-but-locked →
+    /// `ScrambledUncracked` (a hard failure), NOT `Unencrypted`. This is the
+    /// rc4.3 bug: every VOB read came back `6F/03`, so the scan saw no scrambled
+    /// sector and wrongly declared the disc unencrypted → 19 KB garbage.
+    #[test]
+    fn crack_outcome_css_locked_initial_is_scrambled_uncracked() {
+        let mut src = MockSource::new(0x30);
+        src.lock_all = true; // every read → 05/6F/03
+        let extents = [Extent {
+            start_lba: 0,
+            sector_count: 100,
+        }];
+        let outcome = crack_key_outcome(&mut src, &extents, 1, None);
+        assert!(
+            outcome.is_scrambled_uncracked(),
+            "every read 6F/03 on the initial scan → ScrambledUncracked, got {outcome:?}"
+        );
+    }
+
+    /// MISSING #1 guard: the re-crack path (the `Option`-returning `crack_key`,
+    /// `fail_on_locked == false`) must NOT hard-fail on a CSS-locked read — it
+    /// returns `None`. A lapsed-AGID re-crack of another VTS stays soft so a
+    /// genuinely crackable title isn't killed by a transient locked read.
+    #[test]
+    fn crack_key_recrack_locked_is_none_not_hard_fail() {
+        let mut src = MockSource::new(0x30);
+        src.lock_all = true;
+        let extents = [Extent {
+            start_lba: 0,
+            sector_count: 100,
+        }];
+        assert!(crack_key(&mut src, &extents, 1).is_none());
+    }
+
+    /// Fix F: a fully CSS-locked scan early-bails near `CSS_LOCKED_BAIL`
+    /// consecutive locked reads instead of grinding the whole 50_000-sector
+    /// budget (the rc5 "stuck Scanning…" hang on a wedged bridge).
+    #[test]
+    fn crack_css_locked_scan_early_bails() {
+        let mut src = MockSource::new(0x30);
+        src.lock_all = true;
+        let extents = [Extent {
+            start_lba: 0,
+            sector_count: 10_000,
+        }];
+        let _ = crack_key_outcome(&mut src, &extents, 1, None);
+        let n = src.reads.borrow().len();
+        assert!(
+            n <= (CSS_LOCKED_BAIL as usize) + 1,
+            "locked scan early-bails near {CSS_LOCKED_BAIL}, not 10000; read {n}"
+        );
+    }
+
+    /// The budget spans ALL extents, not per-extent: two extents summing past
+    /// the cap must still stop at 50_000 total reads.
+    ///
+    /// Grounding: `tried` is declared outside the `for ext in extents` loop;
+    /// `if tried >= max_tries { break }` after each extent.
+    /// Mutation: move `let mut tried = 0` inside the extent loop -> each extent
+    /// gets its own 50_000 budget; total reads would be 80_000, this fails.
+    #[test]
+    fn crack_key_budget_is_shared_across_extents() {
+        let mut src = MockSource::new(0x00);
+        let extents = [
+            Extent {
+                start_lba: 0,
+                sector_count: 40_000,
+            },
+            Extent {
+                start_lba: 100_000,
+                sector_count: 40_000,
+            },
+        ];
+        let res = crack_key(&mut src, &extents, 1);
+        assert!(res.is_none());
+        assert_eq!(
+            src.reads.borrow().len(),
+            50_000,
+            "the 50_000 budget is shared across all extents"
+        );
+    }
+
+    /// crack_key scans sequentially from each extent's start_lba. The first
+    /// reads must be at the extent's start_lba, start_lba+1, ... pinning the
+    /// LBA arithmetic `ext.start_lba + i`.
+    ///
+    /// Grounding: `reader.read_sectors(ext.start_lba + i, 1, ...)`.
+    /// Mutation: change `ext.start_lba + i` to just `i` -> the recorded LBAs
+    /// would start at 0, not 5000; this fails.
+    #[test]
+    fn crack_key_scans_from_extent_start_lba() {
+        let mut src = MockSource::new(0x00);
+        let extents = [Extent {
+            start_lba: 5_000,
+            sector_count: 4,
+        }];
+        let _ = crack_key(&mut src, &extents, 1);
+        let reads = src.reads.borrow();
+        assert_eq!(
+            &reads[..],
+            &[5_000, 5_001, 5_002, 5_003],
+            "sequential scan from start_lba"
+        );
+    }
+
+    /// A read error on a sector does NOT abort the scan: crack_key keeps
+    /// scanning subsequent sectors (the error sector still counts toward the
+    /// budget). With a small failing extent, every sector is attempted and the
+    /// function returns None.
+    ///
+    /// Grounding: `if reader.read_sectors(...).is_ok() && is_scrambled(...)` —
+    /// an Err simply falls through to `i += 1`.
+    /// Mutation: change the read-error handling to `reader.read_sectors(...)?`
+    /// (propagate) -> crack_key would stop after the first error and read only
+    /// 1 sector; this asserts all 10 were attempted.
+    #[test]
+    fn crack_key_continues_past_read_errors() {
+        let mut src = MockSource::new(0x30);
+        src.fail_all = true;
+        let extents = [Extent {
+            start_lba: 0,
+            sector_count: 10,
+        }];
+        let res = crack_key(&mut src, &extents, 1);
+        assert!(res.is_none());
+        assert_eq!(
+            src.reads.borrow().len(),
+            10,
+            "read errors must not abort the scan"
+        );
+    }
+
+    /// Empty extents (no sectors) -> crack_key reads nothing and returns None.
+    /// A zero-sector extent must not read its start_lba.
+    ///
+    /// Grounding: `while i < ext.sector_count` with sector_count == 0 never
+    /// enters.
+    /// Mutation: change `i < ext.sector_count` to `i <= ext.sector_count` ->
+    /// one spurious read at start_lba; this asserts zero reads.
+    #[test]
+    fn crack_key_empty_extent_reads_nothing() {
+        let mut src = MockSource::new(0x30);
+        let extents = [Extent {
+            start_lba: 42,
+            sector_count: 0,
+        }];
+        let res = crack_key(&mut src, &extents, 1);
+        assert!(res.is_none());
+        assert_eq!(
+            src.reads.borrow().len(),
+            0,
+            "zero-sector extent reads nothing"
+        );
+    }
+
+    /// No extents at all -> immediate None, zero reads.
+    ///
+    /// Grounding: `for ext in extents` over an empty slice is a no-op.
+    /// Mutation: any change that reads before the loop would break this.
+    #[test]
+    fn crack_key_no_extents_is_none() {
+        let mut src = MockSource::new(0x30);
+        let res = crack_key(&mut src, &[], 1);
+        assert!(res.is_none());
+        assert_eq!(src.reads.borrow().len(), 0);
+    }
+
+    // ── Scan-level Cracked branch + per-VTS re-crack success (audit §2 / §5 #8) ─
+
+    /// SCAN-LEVEL CRACKED (audit gap "MockSource never yields a crackable
+    /// sector"): drive the full `crack_key_scan` over a synthetic ISO whose
+    /// scan hits a Stevenson-crackable scrambled sector. The outcome must be
+    /// `CrackOutcome::Cracked` with a key that round-trips the sector, AND the
+    /// `crack_span` must be recorded as the half-open extent span (the per-VTS
+    /// routing key the mux path needs). Previously only the leaf crack and the
+    /// Uncracked/Unencrypted branches were tested — the Cracked branch and
+    /// `crack_span` recording were never exercised end-to-end.
+    #[test]
+    fn crack_outcome_reaches_cracked_with_span() {
+        let title_key = [0x42, 0x13, 0x37, 0xBE, 0xEF];
+        let seed = [0x11, 0x22, 0x33, 0x44, 0x55];
+        let crackable = crackable_sector(&title_key, &seed, 8);
+        // The crackable sector sits a few sectors into the extent.
+        let mut src = MockSource::new(0x00); // surrounding sectors: clear
+        src.crackable = Some((1003, crackable.clone()));
+        let extents = [Extent {
+            start_lba: 1000,
+            sector_count: 50,
+        }];
+        let outcome = crack_key_outcome(&mut src, &extents, 4, None);
+        let state = match outcome {
+            CrackOutcome::Cracked(s) => s,
+            other => panic!("expected Cracked, got {other:?}"),
+        };
+        // The recovered key descrambles the crackable sector body.
+        let mut test = crackable.clone();
+        descramble_sector(&state, &mut test);
+        let mut plain = crackable;
+        lfsr::descramble_sector(&title_key, &mut plain);
+        assert_eq!(
+            &test[0x80..],
+            &plain[0x80..],
+            "recovered key must round-trip the scrambled sector body"
+        );
+        // crack_span = half-open [start, start+count) of the scanned extent.
+        assert_eq!(
+            state.crack_span,
+            Some((1000, 1050)),
+            "crack_span must record the extent LBA span for per-VTS routing"
+        );
+    }
+
+    /// CSS_ERROR WIRING (audit §2 / §5 #7): an all-locked synthetic ISO (every
+    /// VOB read returns CSS-locked sense `05/6F/03` across MULTIPLE extents, as a
+    /// real encrypted-but-unauthenticated disc image does) must produce the exact
+    /// outcome the scan converts into `disc.css_error = Some(Error::CssKeyMissing)`
+    /// — i.e. `CrackOutcome::ScrambledUncracked` / `is_scrambled_uncracked()`,
+    /// NOT `Unencrypted`. disc/mod.rs's `crack_key_outcome → ScrambledUncracked`
+    /// arm (where it stamps css_error) is driven by exactly this signal, so this
+    /// pins the css-layer contract that arm depends on without touching the
+    /// scan plumbing.
+    #[test]
+    fn all_locked_synthetic_iso_yields_css_key_missing_signal() {
+        let mut src = MockSource::new(0x30);
+        src.lock_all = true; // every read → 05/6F/03 across the whole "ISO"
+        let extents = [
+            Extent {
+                start_lba: 0,
+                sector_count: 30,
+            },
+            Extent {
+                start_lba: 5_000,
+                sector_count: 30,
+            },
+        ];
+        let outcome = crack_key_outcome(&mut src, &extents, 16, None);
+        assert!(
+            outcome.is_scrambled_uncracked(),
+            "all-locked ISO → ScrambledUncracked (the css_error=CssKeyMissing \
+             signal), got {outcome:?}"
+        );
+        // The legacy Option wrapper still collapses it to None — callers that
+        // surface the hard error must use crack_key_outcome, which this proves.
+        let mut src2 = MockSource::new(0x30);
+        src2.lock_all = true;
+        assert!(crack_key(&mut src2, &extents, 16).is_none());
+    }
+
+    /// PER-VTS RE-CRACK SUCCESS (audit gap "success path missing"): the prior
+    /// re-crack test only covered the locked→None path. Here a re-crack
+    /// (`crack_key`, `fail_on_locked == false`) over a DIFFERENT VTS's extents
+    /// finds that VTS's own crackable sector and returns a `CssState` whose
+    /// `crack_span` matches the new extents — proving a key cracked for one VTS
+    /// is genuinely re-derived (not reused) for another.
+    #[test]
+    fn recrack_succeeds_on_other_vts_extents() {
+        let title_key = [0xFE, 0xDC, 0xBA, 0x98, 0x76];
+        let seed = [0x00, 0xFF, 0x80, 0x7F, 0x01];
+        let crackable = crackable_sector(&title_key, &seed, 5);
+        let mut src = MockSource::new(0x00);
+        // The second VTS lives at a disjoint LBA range; its crackable sector is
+        // the first one in the extent.
+        src.crackable = Some((9000, crackable));
+        let other_vts = [Extent {
+            start_lba: 9000,
+            sector_count: 20,
+        }];
+        let state = crack_key(&mut src, &other_vts, 4).expect("re-crack must recover a key");
+        assert_eq!(
+            state.crack_span,
+            Some((9000, 9020)),
+            "re-crack span must reflect the OTHER VTS extents, not a reused span"
+        );
+    }
+}

src/css/stevenson.rs

@@ -0,0 +1,593 @@
+//! CSS title-key recovery — Frank A. Stevenson's divide-and-conquer attack
+//! (1999), ported exactly from libdvdcss `RecoverTitleKey` + `AttackPattern`
+//! (css.c).
+//!
+//! Recovers the 5-byte CSS title key from a single scrambled DVD sector with
+//! no player keys and no disc-key crack, using only known plaintext.
+//!
+//! # The cipher this attacks
+//!
+//! The content descrambler ([`super::lfsr::descramble_sector`], = libdvdcss
+//! `dvdcss_unscramble`) seeds its two LFSRs **directly** from
+//! `key = title_key XOR sector_seed` (seed = `sector[0x54..0x59]`):
+//!
+//! ```text
+//! i_t1 = (key[0] ^ sec[0x54]) | 0x100;          // LFSR1 low (9-bit)
+//! i_t2 =  key[1] ^ sec[0x55];                    // LFSR1 high
+//! i_t3 = (key[2]|key[3]<<8|key[4]<<16) ^ seed3;  // LFSR0 (24-bit feedback)
+//! i_t3 = i_t3*2 + 8 - (i_t3 & 7);
+//! // per byte:  *p = TAB1[*p] ^ (i_t5 & 0xff)
+//! ```
+//!
+//! There is NO `decrypt_key` mangling on the content path. So the recovery
+//! is a single inversion of `dvdcss_unscramble`, not the multi-stage
+//! working-key inversion the previous (non-CSS) implementation used.
+//!
+//! # The attack
+//!
+//! 1. **Known plaintext → keystream.** Because the descramble applies TAB1
+//!    to the ciphertext, the per-byte keystream is
+//!    `buf[i] = TAB1[cipher[i]] ^ plain[i]` (matching libdvdcss
+//!    `RecoverTitleKey`'s `p_buffer`).
+//! 2. **Brute the 16-bit LFSR1 seed.** For each of 2^16 seeds, run LFSR1
+//!    forward; for the first four steps deduce the LFSR0 output bytes from
+//!    the keystream (carry-tracked), reconstructing `i_t3`. For the next six
+//!    steps clock LFSR0 normally and check it reproduces the keystream — a
+//!    wrong LFSR1 seed fails fast.
+//! 3. **Back-clock LFSR0.** Run four backward `i_t3` steps (each a 256-way
+//!    search for the byte shifted in) to reach the initial state, then undo
+//!    `i_t3 = i_t3*2 + 8 - (i_t3 & 7)` to recover key[2..5].
+//! 4. **XOR back the seed.** `key[0..5] ^= sector_seed[0..5]` (plain XOR —
+//!    the descramble seeds directly, so there is no inversion).
+//!
+//! `AttackPattern` finds known plaintext for step 1: the longest periodic
+//! run in the cleartext `sec[0x00..0x80]`, assumed to continue into the
+//! encrypted region at 0x80.
+
+use super::lfsr::descramble_sector;
+use super::tables::{TAB1, TAB2, TAB3, TAB4, TAB5};
+
+use crate::consts::SECTOR_BYTES;
+const ENCRYPTED_START: usize = 0x80; // byte 128
+const SEED_OFFSET: usize = 0x54; // sector seed at bytes 0x54-0x58
+const FLAG_BYTE: usize = 0x14;
+
+/// RecoverTitleKey: recover the title key from cipher + known plaintext.
+///
+/// Exact port of libdvdcss `RecoverTitleKey` (css.c). `crypted` is the
+/// ciphertext starting at sector byte 0x80; `decrypted` is the matching
+/// known plaintext; `seed` is `sector[0x54..0x59]`. On success returns the
+/// recovered 5-byte title key; `None` if no LFSR seed reproduces the
+/// keystream.
+///
+/// At least 10 bytes of `crypted`/`decrypted` are required (the cipher is
+/// iterated 10 times: 4 to reconstruct LFSR0, 6 to validate).
+fn recover_title_key_from_plain(
+    crypted: &[u8],
+    decrypted: &[u8],
+    seed: &[u8; 5],
+) -> Option<[u8; 5]> {
+    if crypted.len() < 10 || decrypted.len() < 10 {
+        return None;
+    }
+
+    // buf[i] = TAB1[cipher[i]] ^ plain[i] — the per-byte content keystream.
+    let mut buffer = [0u8; 10];
+    for (i, b) in buffer.iter_mut().enumerate() {
+        *b = TAB1[crypted[i] as usize] ^ decrypted[i];
+    }
+
+    let mut key = [0u8; 5];
+    let mut found = false;
+
+    for i_try in 0u32..0x1_0000 {
+        let mut i_t1 = (i_try >> 8) | 0x100;
+        let mut i_t2 = i_try & 0xff;
+        let mut i_t3: u32 = 0; // not needed yet
+        let mut i_t5: u32 = 0;
+
+        // Iterate the cipher 4 times to reconstruct LFSR0 (i_t3).
+        for &b in buffer.iter().take(4) {
+            let i_t4 = (TAB2[i_t2 as usize] ^ TAB3[i_t1 as usize]) as u32;
+            i_t2 = i_t1 >> 1;
+            i_t1 = ((i_t1 & 1) << 8) ^ i_t4;
+            let i_t4 = TAB5[i_t4 as usize] as u32;
+
+            // Deduce i_t6 (LFSR0 output, pre-TAB4) and the carry.
+            let mut i_t6 = b as u32;
+            if i_t5 != 0 {
+                i_t6 = (i_t6 + 0xff) & 0xff;
+            }
+            if i_t6 < i_t4 {
+                i_t6 += 0x100;
+            }
+            i_t6 -= i_t4;
+            i_t5 += i_t6 + i_t4;
+            let i_t6 = TAB4[i_t6 as usize] as u32;
+
+            i_t3 = (i_t3 << 8) | i_t6;
+            i_t5 >>= 8;
+        }
+
+        let i_candidate = i_t3;
+
+        // Iterate 6 more times to validate the candidate.
+        let mut i = 4usize;
+        while i < 10 {
+            let i_t4 = (TAB2[i_t2 as usize] ^ TAB3[i_t1 as usize]) as u32;
+            i_t2 = i_t1 >> 1;
+            i_t1 = ((i_t1 & 1) << 8) ^ i_t4;
+            let i_t4 = TAB5[i_t4 as usize] as u32;
+            let mut i_t6 = (((((((i_t3 >> 3) ^ i_t3) >> 1) ^ i_t3) >> 8) ^ i_t3) >> 5) & 0xff;
+            i_t3 = (i_t3 << 8) | i_t6;
+            i_t6 = TAB4[i_t6 as usize] as u32;
+            i_t5 += i_t6 + i_t4;
+            if (i_t5 & 0xff) as u8 != buffer[i] {
+                break;
+            }
+            i_t5 >>= 8;
+            i += 1;
+        }
+
+        if i != 10 {
+            continue;
+        }
+
+        // Four backward steps of iterating i_t3 to deduce the initial state.
+        i_t3 = i_candidate;
+        for _ in 0..4 {
+            let i_t1_byte = i_t3 & 0xff;
+            i_t3 >>= 8;
+            // Brute-force the byte shifted in (top byte of the 24-bit reg).
+            for j in 0u32..256 {
+                i_t3 = (i_t3 & 0x1_ffff) | (j << 17);
+                let i_t6 = (((((((i_t3 >> 3) ^ i_t3) >> 1) ^ i_t3) >> 8) ^ i_t3) >> 5) & 0xff;
+                if i_t6 == i_t1_byte {
+                    break;
+                }
+            }
+        }
+
+        // Undo `i_t3 = i_t3*2 + 8 - (i_t3 & 7)` to recover key[2..5].
+        let i_t4 = (i_t3 >> 1).wrapping_sub(4);
+        for i_t5 in 0u32..8 {
+            let val = i_t4.wrapping_add(i_t5);
+            if val.wrapping_mul(2).wrapping_add(8).wrapping_sub(val & 7) == i_t3 {
+                key[0] = (i_try >> 8) as u8;
+                key[1] = (i_try & 0xff) as u8;
+                key[2] = (val & 0xff) as u8;
+                key[3] = ((val >> 8) & 0xff) as u8;
+                key[4] = ((val >> 16) & 0xff) as u8;
+                found = true;
+                break;
+            }
+        }
+        // First fully-validated candidate wins. The 48-bit keystream constraint
+        // makes a second match cryptographically negligible on real sectors, but
+        // continuing would let a later spurious match overwrite a correct key.
+        if found {
+            break;
+        }
+    }
+
+    if found {
+        for (k, &s) in key.iter_mut().zip(seed.iter()) {
+            *k ^= s;
+        }
+        Some(key)
+    } else {
+        None
+    }
+}
+
+/// Recover the CSS title key from a scrambled sector using a known plaintext
+/// for the encrypted region.
+///
+/// `plain` is the expected plaintext at byte 0x80 (at least 10 bytes).
+/// Returns the recovered key only if it actually descrambles the sector back
+/// to `plain` — guarding against the rare spurious LFSR-seed match.
+pub fn recover_title_key(sector: &[u8], plain: &[u8]) -> Option<[u8; 5]> {
+    if sector.len() < SECTOR_BYTES || plain.len() < 10 {
+        return None;
+    }
+    if sector[FLAG_BYTE] & 0x30 == 0 {
+        return None;
+    }
+
+    let seed: [u8; 5] = [
+        sector[SEED_OFFSET],
+        sector[SEED_OFFSET + 1],
+        sector[SEED_OFFSET + 2],
+        sector[SEED_OFFSET + 3],
+        sector[SEED_OFFSET + 4],
+    ];
+
+    let crypted = &sector[ENCRYPTED_START..ENCRYPTED_START + 10];
+    let key = recover_title_key_from_plain(crypted, plain, &seed)?;
+
+    if descramble_matches(sector, &key, plain) {
+        Some(key)
+    } else {
+        None
+    }
+}
+
+/// Verify a title key by descrambling a copy of `sector` and checking the
+/// known plaintext reappears at byte 0x80.
+fn descramble_matches(sector: &[u8], title: &[u8; 5], plain: &[u8]) -> bool {
+    let mut test = sector.to_vec();
+    test[FLAG_BYTE] |= 0x10; // ensure scramble flag set for the descrambler
+    descramble_sector(title, &mut test);
+    let n = plain.len().min(SECTOR_BYTES - ENCRYPTED_START);
+    test[ENCRYPTED_START..ENCRYPTED_START + n] == plain[..n]
+}
+
+/// AttackPattern: find a repeating pattern just before the encrypted region
+/// and assume the plaintext at 0x80 continues it.
+///
+/// Functionally-equivalent port of libdvdcss `AttackPattern` (css.c) — finds the
+/// same periodic cribs on real DVD data, though its byte-comparison anchor
+/// differs from the C on phase-misaligned runs. Scans cleartext
+/// `sec[0x00..0x80]` for the longest run that repeats with a cycle length in
+/// 2..0x2F. If the run is long enough (`plen > 3` and at least two full
+/// cycles), the known plaintext at 0x80 is taken to be the periodic run
+/// continuing forward, and [`recover_title_key_from_plain`] is applied.
+pub fn crack_title_key(sector: &[u8]) -> Option<[u8; 5]> {
+    if sector.len() < SECTOR_BYTES {
+        return None;
+    }
+    if sector[FLAG_BYTE] & 0x30 == 0 {
+        return None;
+    }
+
+    // Runaway guard: a single sector's crack is a bounded 2^16 LFSR search and
+    // should finish in well under a second on any modern CPU. If it ever
+    // exceeds ~2s wall-clock, something pathological is happening — log it so a
+    // hang is never silent.
+    let crack_t0 = std::time::Instant::now();
+
+    let result = crack_title_key_inner(sector);
+
+    let elapsed = crack_t0.elapsed();
+    if elapsed.as_secs_f64() > 2.0 {
+        tracing::warn!(
+            target: "freemkv::css",
+            elapsed_ms = elapsed.as_millis() as u64,
+            found = result.is_some(),
+            "css crack: single-sector recovery exceeded 2s (runaway guard)"
+        );
+    }
+    result
+}
+
+/// Inner body of [`crack_title_key`] — the actual AttackPattern search. Split
+/// out so the public entry point can wall-clock the whole attempt for the
+/// runaway guard without threading a timer through every return path.
+/// AttackPattern crib: the predicted 10-byte plaintext at byte 0x80.
+///
+/// Scans the clear header `sec[0x00..0x80]` (never scrambled) for the longest
+/// run that repeats with a cycle length in 2..0x2F. If the run is long enough
+/// (`plen > 3` and at least two full cycles), the plaintext at 0x80 is taken to
+/// be that periodic run continuing forward. Returns `None` for an unscrambled
+/// sector or one with no usable run — such a sector can be neither cracked nor
+/// key-validated, only descrambled with an externally-cached key.
+///
+/// The header is untouched by `descramble_sector`, so the crib is identical
+/// before and after descramble: the decrypt path uses it as a per-sector
+/// "did the cached key descramble correctly?" oracle (the predicted plaintext
+/// must reappear at 0x80), and the cracker uses it as its known plaintext.
+pub(crate) fn attack_crib(sector: &[u8]) -> Option<[u8; 10]> {
+    if sector.len() < SECTOR_BYTES || sector[FLAG_BYTE] & 0x30 == 0 {
+        return None;
+    }
+    let mut best_plen: usize = 0;
+    let mut best_p: usize = 0;
+
+    // For all cycle lengths from 2 to 0x2F.
+    for i in 2usize..0x30 {
+        // Count bytes that repeat with cycle length i, scanning backward from
+        // 0x7F. `sec[0x7F - (j % i)] == sec[0x7F - j]`.
+        let mut j = i + 1;
+        while j < 0x80 && sector[0x7f - (j % i)] == sector[0x7f - j] {
+            if j > best_plen {
+                best_plen = j;
+                best_p = i;
+            }
+            j += 1;
+        }
+    }
+
+    // Need at least a few repeated bytes and at least one full cycle.
+    if best_plen > 3 && best_p > 0 && best_plen / best_p >= 2 {
+        // The known plaintext is the periodic run continuing past 0x80. The
+        // crib starts at `0x80 - (best_plen/best_p)*best_p` and continues
+        // through the encrypted region; the bytes at and after 0x80 are the
+        // predicted plaintext (the pattern repeats with period best_p).
+        let cycles = best_plen / best_p;
+        let plain_start = 0x80 - cycles * best_p;
+
+        // Each predicted byte is the run sample one or more periods back:
+        // `sec[plain_start + (i % best_p)]`. For in-run offsets
+        // (`plain_start + i < 0x80`) the run is exactly periodic, so this
+        // equals `sec[plain_start + i]`; for offsets at/after 0x80 the raw
+        // byte is ciphertext, so we MUST wrap within the period rather than
+        // read it. (Reading `&sec[plain_start..+10]` directly — as before —
+        // pulled ciphertext into the crib whenever the run covered fewer than
+        // 10 bytes before 0x80, producing false-negative key recovery.)
+        let mut plain = [0u8; 10];
+        for (i, p) in plain.iter_mut().enumerate() {
+            *p = sector[plain_start + (i % best_p)];
+        }
+        Some(plain)
+    } else {
+        None
+    }
+}
+
+fn crack_title_key_inner(sector: &[u8]) -> Option<[u8; 5]> {
+    let plain = attack_crib(sector)?;
+    let seed: [u8; 5] = [
+        sector[SEED_OFFSET],
+        sector[SEED_OFFSET + 1],
+        sector[SEED_OFFSET + 2],
+        sector[SEED_OFFSET + 3],
+        sector[SEED_OFFSET + 4],
+    ];
+    let crypted = &sector[0x80..0x80 + 10];
+    if let Some(key) = recover_title_key_from_plain(crypted, &plain, &seed) {
+        // Verify against the same predicted plaintext.
+        if descramble_matches(sector, &key, &plain) {
+            return Some(key);
+        }
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::lfsr::scramble_sector;
+    use super::*;
+
+    /// Build a synthetic scrambled sector for a given title key and seed,
+    /// with `plain` placed as the plaintext at byte 0x80, scrambled with
+    /// EXACTLY the cipher `descramble_sector` inverts. Returns
+    /// (scrambled_sector, full_plaintext_body).
+    fn synth_sector(title_key: &[u8; 5], seed: &[u8; 5], plain: &[u8]) -> (Vec<u8>, Vec<u8>) {
+        let mut plaintext = vec![0u8; SECTOR_BYTES];
+        plaintext[0..4].copy_from_slice(&[0x00, 0x00, 0x01, 0xBA]);
+        plaintext[FLAG_BYTE] = 0x10;
+        plaintext[SEED_OFFSET..SEED_OFFSET + 5].copy_from_slice(seed);
+        plaintext[ENCRYPTED_START..ENCRYPTED_START + plain.len()].copy_from_slice(plain);
+
+        let body = plaintext.clone();
+
+        // scramble_sector turns the plaintext body into ciphertext and sets
+        // the scramble flag.
+        scramble_sector(title_key, &mut plaintext);
+        (plaintext, body)
+    }
+
+    /// Build a synthetic scrambled sector whose CLEARTEXT (0x00..0x80) ends
+    /// in a periodic run that continues into the encrypted region — the case
+    /// `AttackPattern` (crack_title_key) is designed to crack.
+    fn synth_periodic_sector(
+        title_key: &[u8; 5],
+        seed: &[u8; 5],
+        period: usize,
+    ) -> (Vec<u8>, Vec<u8>) {
+        let mut plaintext = vec![0u8; SECTOR_BYTES];
+        plaintext[FLAG_BYTE] = 0x10;
+
+        // A clean periodic run occupying the tail of the cleartext header
+        // (RUN_START..0x80) and continuing into the encrypted region. This
+        // mirrors a real VOB: a periodic data run just before the scrambled
+        // part. The run must NOT overlap the seed bytes (0x54..0x59), or the
+        // AttackPattern detector would break mid-run. The phase is anchored to
+        // offset 0 so the run is consistent across the 0x80 boundary.
+        // Just above the seed (0x54..0x59); gives a 39-byte run (0x59..0x80)
+        // — enough for >=2 cycles of every tested period (<=19).
+        const RUN_START: usize = 0x59;
+        let pat: Vec<u8> = (0..period)
+            .map(|k| (0xA0u8.wrapping_add(k as u8)) ^ 0x5A)
+            .collect();
+        for (i, b) in plaintext.iter_mut().enumerate().skip(RUN_START) {
+            *b = pat[i % period];
+        }
+
+        // Seed sits below the run, undisturbed.
+        plaintext[SEED_OFFSET..SEED_OFFSET + 5].copy_from_slice(seed);
+
+        let body = plaintext.clone();
+        scramble_sector(title_key, &mut plaintext);
+        (plaintext, body)
+    }
+
+    #[test]
+    fn crack_unscrambled_returns_none() {
+        let sector = vec![0u8; SECTOR_BYTES];
+        assert!(crack_title_key(&sector).is_none());
+    }
+
+    #[test]
+    fn crack_too_short_returns_none() {
+        let sector = vec![0u8; 100];
+        assert!(crack_title_key(&sector).is_none());
+    }
+
+    #[test]
+    fn recover_needs_min_plain() {
+        let sector = vec![0u8; SECTOR_BYTES];
+        let short_plain = [0u8; 4];
+        assert!(recover_title_key(&sector, &short_plain).is_none());
+    }
+
+    /// The known plaintext used at byte 0x80 for the direct-recovery tests.
+    /// A realistic MPEG-2 PES header start.
+    const PES: [u8; 10] = [0x00, 0x00, 0x01, 0xE0, 0x00, 0x00, 0x80, 0x80, 0x05, 0x21];
+
+    /// MANDATORY round-trip (Task C.1): synthesize a scrambled sector for a
+    /// known (title_key, seed), then assert recover_title_key returns a key
+    /// that descrambles the body back to plaintext. CSS title-key recovery is
+    /// well-defined up to keys that scramble identically; we assert the full
+    /// body round-trips (the true correctness property), and additionally
+    /// that the EXACT key is returned for the common case.
+    #[test]
+    fn recover_round_trips_known_keys() {
+        let cases: &[([u8; 5], [u8; 5])] = &[
+            (
+                [0x42, 0x13, 0x37, 0xBE, 0xEF],
+                [0x11, 0x22, 0x33, 0x44, 0x55],
+            ),
+            (
+                [0x01, 0x02, 0x03, 0x04, 0x05],
+                [0xDE, 0xAD, 0xBE, 0xEF, 0x42],
+            ),
+            (
+                [0xFE, 0xDC, 0xBA, 0x98, 0x76],
+                [0x00, 0xFF, 0x80, 0x7F, 0x01],
+            ),
+            (
+                [0x9A, 0x78, 0x56, 0x34, 0x12],
+                [0xA5, 0x5A, 0x0F, 0xF0, 0xCC],
+            ),
+            (
+                [0xFF, 0xFF, 0xFF, 0xFF, 0xFF],
+                [0x01, 0x01, 0x01, 0x01, 0x01],
+            ),
+        ];
+        for (title_key, seed) in cases {
+            let (mut sector, body) = synth_sector(title_key, seed, &PES);
+            let recovered =
+                recover_title_key(&sector, &PES).expect("recover_title_key returned None");
+            descramble_sector(&recovered, &mut sector);
+            assert_eq!(
+                &sector[ENCRYPTED_START..SECTOR_BYTES],
+                &body[ENCRYPTED_START..SECTOR_BYTES],
+                "recovered key did not descramble the full body for \
+                 title={title_key:02x?} seed={seed:02x?}"
+            );
+        }
+    }
+
+    /// MANDATORY (Task C.1): the AttackPattern entry point crack_title_key —
+    /// no plaintext supplied — recovers a round-tripping key when the
+    /// cleartext ends in a periodic run that continues into 0x80.
+    #[test]
+    fn crack_title_key_recovers_via_attack_pattern() {
+        for &period in &[2usize, 3, 5, 8, 16] {
+            let title_key = [0x42, 0x13, 0x37, 0xBE, 0xEF];
+            let seed = [0x11, 0x22, 0x33, 0x44, 0x55];
+            let (sector, body) = synth_periodic_sector(&title_key, &seed, period);
+
+            let cracked = crack_title_key(&sector)
+                .unwrap_or_else(|| panic!("crack_title_key returned None for period {period}"));
+            let mut test = sector.clone();
+            descramble_sector(&cracked, &mut test);
+            assert_eq!(
+                &test[ENCRYPTED_START..SECTOR_BYTES],
+                &body[ENCRYPTED_START..SECTOR_BYTES],
+                "crack_title_key key did not round-trip the body (period {period})"
+            );
+        }
+    }
+
+    /// recover_title_key_from_plain inverts dvdcss_unscramble exactly: scramble
+    /// a known body, hand back the keystream-derived key, and the recovered
+    /// key (XOR-back included) reproduces the plaintext.
+    #[test]
+    fn recovered_key_descrambles_back_to_plaintext() {
+        let cases: &[([u8; 5], [u8; 5])] = &[
+            (
+                [0x42, 0x13, 0x37, 0xBE, 0xEF],
+                [0x11, 0x22, 0x33, 0x44, 0x55],
+            ),
+            (
+                [0x9A, 0x78, 0x56, 0x34, 0x12],
+                [0xA5, 0x5A, 0x0F, 0xF0, 0xCC],
+            ),
+            (
+                [0xFF, 0xFF, 0xFF, 0xFF, 0xFF],
+                [0x01, 0x01, 0x01, 0x01, 0x01],
+            ),
+        ];
+        for (title_key, seed) in cases {
+            let (mut sector, body) = synth_sector(title_key, seed, &PES);
+            let recovered =
+                recover_title_key(&sector, &PES).expect("recover_title_key returned None");
+            descramble_sector(&recovered, &mut sector);
+            assert_eq!(
+                &sector[ENCRYPTED_START..SECTOR_BYTES],
+                &body[ENCRYPTED_START..SECTOR_BYTES],
+                "descramble with recovered key did not reproduce the body \
+                 for title={title_key:02x?} seed={seed:02x?}"
+            );
+        }
+    }
+
+    // ── early-return guards ────────────────────────────────────────────────
+
+    #[test]
+    fn recover_rejects_sector_one_byte_short() {
+        let mut sector = vec![0u8; SECTOR_BYTES - 1];
+        sector[FLAG_BYTE] = 0x30;
+        assert!(recover_title_key(&sector, &PES).is_none());
+    }
+
+    #[test]
+    fn recover_rejects_unscrambled_sector() {
+        let sector = vec![0x00u8; SECTOR_BYTES];
+        assert!(recover_title_key(&sector, &PES).is_none());
+    }
+
+    #[test]
+    fn recover_high_flag_bits_are_not_scramble() {
+        for &flag in &[0x40u8, 0x80, 0xC0] {
+            let mut sector = vec![0x11u8; SECTOR_BYTES];
+            sector[FLAG_BYTE] = flag;
+            assert!(
+                recover_title_key(&sector, &PES).is_none(),
+                "flag {flag:#04x} has scramble bits clear; recover must return None"
+            );
+        }
+    }
+
+    #[test]
+    fn crack_high_flag_bits_are_not_scramble() {
+        for &flag in &[0x40u8, 0x80, 0xC0] {
+            let mut sector = vec![0x11u8; SECTOR_BYTES];
+            sector[FLAG_BYTE] = flag;
+            assert!(
+                crack_title_key(&sector).is_none(),
+                "flag {flag:#04x} clear scramble bits -> crack must return None"
+            );
+        }
+    }
+
+    #[test]
+    fn crack_rejects_sector_one_byte_short() {
+        let mut sector = vec![0u8; SECTOR_BYTES - 1];
+        if sector.len() > FLAG_BYTE {
+            sector[FLAG_BYTE] = 0x30;
+        }
+        assert!(crack_title_key(&sector).is_none());
+    }
+
+    /// crack_title_key must never panic on a fully scrambled sector with
+    /// arbitrary (non-periodic) content — it just returns None.
+    #[test]
+    fn crack_full_path_never_panics() {
+        for seed in 0u32..3 {
+            let mut sector = vec![0u8; SECTOR_BYTES];
+            sector[FLAG_BYTE] = 0x30;
+            let mut x = seed.wrapping_mul(2_654_435_761).wrapping_add(7);
+            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) ^ 0xA5) as u8;
+            }
+            let _ = crack_title_key(&sector);
+        }
+    }
+}

src/css/tables.rs

@@ -25,6 +25,8 @@ pub const TAB1: [u8; 256] = [
 ];
 
 /// Table 2: LFSR1 high-byte feedback permutation.
+///
+/// Byte-identical to libdvdcss `p_css_tab2` (csstables.h).
 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,
@@ -40,11 +42,18 @@ pub const TAB2: [u8; 256] = [
     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,
+    0xed, 0xec, 0xef, 0xee, 0xe9, 0xe8, 0xeb, 0xea, 0xe4, 0xe5, 0xe6, 0xe7, 0xe0, 0xe1, 0xe2, 0xe3,
 ];
 
-/// Table 3: LFSR1 low-byte feedback permutation.
+/// Table 3: LFSR1 9-bit low-word feedback table (512 entries).
+///
+/// Byte-identical to libdvdcss `p_css_tab3` (csstables.h): the 8-value
+/// block `BASE[i & 7]` repeated 64 times. The CSS LFSR1 step indexes this
+/// table with the 9-bit low register (0x100..=0x1FF), but only the low 3
+/// bits select the output — the high bits are ignored, hence the constant
+/// blocks. The 512-entry width simply lets the 9-bit index be used without
+/// masking.
 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,
@@ -54,30 +63,30 @@ 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,
-    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,
+    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,
+    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,
+    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,
 ];
 
 /// Table 4: LFSR0 byte permutation (used in initialization and output).
@@ -100,8 +109,10 @@ pub const TAB4: [u8; 256] = [
     0x0f, 0x8f, 0x4f, 0xcf, 0x2f, 0xaf, 0x6f, 0xef, 0x1f, 0x9f, 0x5f, 0xdf, 0x3f, 0xbf, 0x7f, 0xff,
 ];
 
-/// Table 5: LFSR1 output permutation for the Stevenson attack.
-/// This is the inverse byte-reversal of TAB4.
+/// 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,
@@ -120,3 +131,155 @@ pub const TAB5: [u8; 256] = [
     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"
+            );
+        }
+    }
+
+    /// TAB1 is a bijection on 0..256. CSS uses it as an invertible output
+    /// permutation in css_DecryptKey's chained-XOR rounds; if two inputs
+    /// collided, the key mangling would not be invertible.
+    ///
+    /// Mutation: duplicate any value (e.g. set TAB1[1] = TAB1[0]) -> the
+    /// "maps two inputs" assert fires.
+    #[test]
+    fn tab1_is_a_permutation() {
+        let mut seen = [false; 256];
+        for (i, &v) in TAB1.iter().enumerate() {
+            assert!(
+                !seen[v as usize],
+                "TAB1 maps two inputs to {v:#04x} (collision at index {i:#04x})"
+            );
+            seen[v as usize] = true;
+        }
+    }
+
+    /// TAB1's fixed structural anchors from the CSS spec table:
+    /// TAB1[0x00] == 0x33 and the inverse TAB1[0x33] == 0x00. These two
+    /// entries are the canonical first-row / inverse-lookup landmarks of the
+    /// published CSS TAB1 and pin the table's orientation.
+    ///
+    /// Grounding: CSS specification TAB1, row 0 col 0 = 0x33; index 0x33
+    /// (row 3 col 3) = 0x00.
+    /// Mutation: change the first literal `0x33` in TAB1 -> first assert fails.
+    #[test]
+    fn tab1_known_spec_anchors() {
+        assert_eq!(TAB1[0x00], 0x33, "TAB1[0] is the published 0x33");
+        assert_eq!(TAB1[0x33], 0x00, "TAB1[0x33] is the published 0x00");
+    }
+
+    /// TAB2 is a permutation of 0..256 (it is the LFSR1 high-byte feedback
+    /// substitution). A non-bijective TAB2 would bias the LFSR1 keystream.
+    ///
+    /// Mutation: set TAB2[8] = 0x00 (collides with TAB2[0]) -> assert fires.
+    #[test]
+    fn tab2_is_a_permutation() {
+        let mut seen = [false; 256];
+        for (i, &v) in TAB2.iter().enumerate() {
+            assert!(
+                !seen[v as usize],
+                "TAB2 maps two inputs to {v:#04x} (collision at index {i:#04x})"
+            );
+            seen[v as usize] = true;
+        }
+    }
+
+    /// TAB3 is the libdvdcss `p_css_tab3`: the 8-value feedback block
+    ///   BASE = [0x00,0x24,0x49,0x6d,0x92,0xb6,0xdb,0xff]
+    /// repeated 64 times — `TAB3[i] == BASE[i & 7]`. The high bits of the
+    /// 9-bit index do not affect the output (libdvdcss's LFSR1 step indexes
+    /// with the full 9-bit low register but only `& 7` matters). This pins
+    /// all 512 entries to the published table.
+    ///
+    /// Mutation: flip any single byte in the TAB3 literal -> the formula
+    /// check fails at that index.
+    #[test]
+    fn tab3_matches_lfsr1_generating_formula() {
+        const BASE: [u8; 8] = [0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff];
+        for i in 0..512usize {
+            let expected = BASE[i & 7];
+            assert_eq!(
+                TAB3[i], expected,
+                "TAB3[{i:#05x}] = {:#04x}, formula BASE[i&7] = {expected:#04x}",
+                TAB3[i]
+            );
+        }
+    }
+
+    /// TAB4 is the exact bit-reversal of each byte (CSS uses it to permute
+    /// LFSR0 bytes on seed and output). TAB4[b] reverses b's 8 bits MSB<->LSB.
+    /// Therefore it is also an involution: TAB4[TAB4[b]] == b.
+    ///
+    /// Grounding: TAB4[0x01]=0x80, TAB4[0x80]=0x01, TAB4[0x00]=0x00,
+    /// TAB4[0xFF]=0xFF.
+    /// Mutation: set TAB4[1] = 0x40 (not the reversal 0x80) -> bit-reversal
+    /// check fails at index 1.
+    #[test]
+    fn tab4_is_exact_bit_reversal_and_involution() {
+        for b in 0u16..256 {
+            let rev = (0..8).fold(0u8, |acc, k| acc | (((b as u8 >> k) & 1) << (7 - k)));
+            assert_eq!(
+                TAB4[b as usize], rev,
+                "TAB4[{b:#04x}] is not the bit-reversal {rev:#04x}"
+            );
+        }
+        for b in 0..256usize {
+            assert_eq!(
+                TAB4[TAB4[b] as usize], b as u8,
+                "TAB4 not an involution at {b:#04x}"
+            );
+        }
+        // Spec landmark entries.
+        assert_eq!(TAB4[0x01], 0x80);
+        assert_eq!(TAB4[0x80], 0x01);
+        assert_eq!(TAB4[0x00], 0x00);
+        assert_eq!(TAB4[0xFF], 0xFF);
+    }
+
+    /// TAB4 is a permutation (bit-reversal is bijective). Distinct from the
+    /// reversal test: a table that is "reversal except two swapped entries"
+    /// would still be a permutation, and a table that is "reversal except one
+    /// duplicated entry" would fail this but might pass a sampled reversal
+    /// check — the two tests pin different failure modes.
+    ///
+    /// Mutation: set TAB4[2] = TAB4[1] -> permutation assert fires.
+    #[test]
+    fn tab4_is_a_permutation() {
+        let mut seen = [false; 256];
+        for &v in TAB4.iter() {
+            assert!(!seen[v as usize], "TAB4 maps two inputs to {v:#04x}");
+            seen[v as usize] = true;
+        }
+    }
+
+    /// TAB5 is also a permutation (complement of a bijection is a bijection)
+    /// and its own self-consistency landmark: TAB5[0x00] == 0xFF (TAB4[0]^0xFF)
+    /// and TAB5[0xFF] == 0x00 (TAB4[0xFF]^0xFF). Pins orientation independent
+    /// of the complement-loop test.
+    ///
+    /// Mutation: change the first TAB5 literal 0xff -> 0xfe -> the landmark
+    /// and permutation checks both catch it.
+    #[test]
+    fn tab5_is_permutation_with_anchors() {
+        let mut seen = [false; 256];
+        for &v in TAB5.iter() {
+            assert!(!seen[v as usize], "TAB5 maps two inputs to {v:#04x}");
+            seen[v as usize] = true;
+        }
+        assert_eq!(TAB5[0x00], 0xFF, "TAB5[0] = TAB4[0]^0xFF = 0xFF");
+        assert_eq!(TAB5[0xFF], 0x00, "TAB5[0xFF] = TAB4[0xFF]^0xFF = 0x00");
+    }
+}

src/diag.rs

@@ -0,0 +1,753 @@
+//! Structured scan diagnostics — the `--log-level 3` self-diagnosing dump.
+//!
+//! A bug report log must be self-diagnosing: everything needed to explain
+//! *why* freemkv made the choices it did at scan must be in the log, in a
+//! compact, machine-parseable form. This module emits one terse line per row
+//! (title, cell, stream, decision) under the `tracing` target
+//! `freemkv::diag`, which the CLI routes to `log.txt` when `--log-level 3`
+//! (debug) is set.
+//!
+//! Format conventions (stable, greppable):
+//!   - Every line is prefixed by a `tag=` so a log scraper can filter
+//!     (`disc`, `title`, `dvd.cell`, `dvd.vattr`, `dvd.aattr`, `bd.clip`,
+//!     `bd.mark`, `aacs`, `stream`, `decision`).
+//!   - Raw bytes are shown as `0xNN` next to their decode so a wrong decode
+//!     is obvious against the raw value.
+//!   - This module only READS already-parsed scan state — it never re-reads
+//!     the disc and never mutates anything.
+//!
+//! The DVD per-cell table (with the raw cell-category byte) is emitted from
+//! the IFO scan itself ([`dump_dvd_cells`]), because the per-cell
+//! `ifo::DvdCell` detail is lowered away before the `Disc` is built. The
+//! `Disc`-level dump ([`dump_disc`]) covers everything that survives
+//! lowering: titles, streams, the picked main feature, and AACS state.
+
+use crate::disc::{
+    AudioChannels, ColorSpace, Disc, DiscTitle, FrameRate, HdrFormat, Resolution, SampleRate,
+    Stream,
+};
+use crate::ifo::{CellCategory, DvdTitle};
+
+const DIAG: &str = "freemkv::diag";
+
+// ── small format helpers (pure, unit-testable) ──────────────────────────────
+
+/// Compact name for a [`Resolution`] with the interlace marker preserved.
+pub fn res_str(r: Resolution) -> &'static str {
+    match r {
+        Resolution::R480i => "480i",
+        Resolution::R480p => "480p",
+        Resolution::R576i => "576i",
+        Resolution::R576p => "576p",
+        Resolution::R720p => "720p",
+        Resolution::R1080i => "1080i",
+        Resolution::R1080p => "1080p",
+        Resolution::R2160p => "2160p",
+        Resolution::R4320p => "4320p",
+        Resolution::Unknown => "res?",
+    }
+}
+
+/// Frames-per-second string for a [`FrameRate`].
+pub fn fps_str(f: FrameRate) -> &'static str {
+    match f {
+        FrameRate::F23_976 => "23.976",
+        FrameRate::F24 => "24",
+        FrameRate::F25 => "25",
+        FrameRate::F29_97 => "29.97",
+        FrameRate::F30 => "30",
+        FrameRate::F50 => "50",
+        FrameRate::F59_94 => "59.94",
+        FrameRate::F60 => "60",
+        FrameRate::Unknown => "fps?",
+    }
+}
+
+/// PAL/NTSC field-rate family inferred from the frame rate (DVD has no
+/// explicit field, so this is the colour/standard the muxer stamps).
+pub fn tv_system_str(f: FrameRate) -> &'static str {
+    match f {
+        FrameRate::F25 | FrameRate::F50 => "PAL",
+        FrameRate::F23_976 | FrameRate::F29_97 | FrameRate::F59_94 => "NTSC",
+        _ => "—",
+    }
+}
+
+/// CICP-ish short name for a [`ColorSpace`].
+pub fn color_str(c: ColorSpace) -> &'static str {
+    match c {
+        ColorSpace::Bt709 => "BT.709",
+        ColorSpace::Bt2020 => "BT.2020",
+        ColorSpace::Bt470bg => "BT.470BG",
+        ColorSpace::Smpte170m => "SMPTE-170M",
+        ColorSpace::Unknown => "color?",
+    }
+}
+
+/// HDR format short name.
+pub fn hdr_str(h: HdrFormat) -> &'static str {
+    match h {
+        HdrFormat::Sdr => "SDR",
+        HdrFormat::Hdr10 => "HDR10",
+        HdrFormat::Hdr10Plus => "HDR10+",
+        HdrFormat::DolbyVision => "DoVi",
+        HdrFormat::Hlg => "HLG",
+    }
+}
+
+/// Channel count from an [`AudioChannels`] layout (what lands in the MKV
+/// `Channels` element).
+pub fn channel_count(ch: AudioChannels) -> u8 {
+    match ch {
+        AudioChannels::Mono => 1,
+        AudioChannels::Stereo => 2,
+        AudioChannels::Stereo21 => 3,
+        AudioChannels::Quad => 4,
+        AudioChannels::Surround50 => 5,
+        AudioChannels::Surround51 => 6,
+        AudioChannels::Surround61 => 7,
+        AudioChannels::Surround71 => 8,
+        AudioChannels::Unknown => 0,
+    }
+}
+
+/// Sample-rate in Hz for a [`SampleRate`].
+pub fn sample_rate_hz(s: SampleRate) -> u32 {
+    match s {
+        SampleRate::S44_1 => 44100,
+        SampleRate::S48 => 48000,
+        SampleRate::S88_2 => 88200,
+        SampleRate::S96 => 96000,
+        SampleRate::S176_4 => 176400,
+        SampleRate::S192 => 192000,
+        SampleRate::S48_96 => 96000,
+        SampleRate::S48_192 => 192000,
+        SampleRate::Unknown => 0,
+    }
+}
+
+// ── DVD cell-category dump (from the IFO scan, pre-lowering) ─────────────────
+
+/// One formatted cell row for the DVD per-PGC cell table. Returned as a
+/// string so it can be unit-tested without a logger.
+///
+/// Columns: `idx`, raw category (`cat=0xNN`) + decoded fields, first/last
+/// sector, duration, and the keep/drop verdict from the bug-4 leading-cell
+/// filter.
+pub fn dvd_cell_row(idx: usize, cell: &crate::ifo::DvdCell, dropped: bool) -> String {
+    let c = CellCategory::decode(cell.category);
+    // Per-cell keep/skip REASON (self-sufficient bug log): a dropped cell is a
+    // leading secondary angle/interleave block piece; a kept cell is either the
+    // first feature cell or genuine feature content. This makes the
+    // leading-cell-filter decision auditable from the log without the disc.
+    let verdict = if dropped {
+        "DROP(leading-secondary-block-piece)"
+    } else if c.is_secondary_block_piece() {
+        // Kept despite being a secondary piece — only happens past the leading
+        // run (the filter stops at the first plain feature cell).
+        "keep(feature-body)"
+    } else {
+        "keep(plain-feature)"
+    };
+    format!(
+        "tag=dvd.cell idx={idx} cat=0x{:02X} block_mode={} block_type={} \
+seamless={} ilv={} stc={} angle={} plain={} first={} last={} dur={:.1}s {}",
+        cell.category,
+        c.block_mode,
+        c.block_type,
+        c.seamless_play as u8,
+        c.interleaved as u8,
+        c.stc_discontinuity as u8,
+        c.seamless_angle as u8,
+        c.is_plain_feature() as u8,
+        cell.first_sector,
+        cell.last_sector,
+        cell.duration_secs,
+        verdict,
+    )
+}
+
+/// Emit the per-PGC cell table for one DVD title during the IFO scan.
+///
+/// `vts`/`title` identify the row group; `title` is the `DvdTitle` whose
+/// cells (and bug-4 leading-cell verdict) are dumped. Called from
+/// `scan_dvd_titles` while the `DvdTitle` is still in scope (the per-cell
+/// category byte is lowered away before the `Disc` exists).
+pub fn dump_dvd_cells(vts: u8, title_num: u16, title: &DvdTitle) {
+    if !tracing::enabled!(target: DIAG, tracing::Level::DEBUG) {
+        return;
+    }
+    let feature_start = title.feature_start_cell();
+    tracing::debug!(
+        target: DIAG,
+        "tag=dvd.pgc vts={vts} title={title_num} cells={} chapters={} \
+    dur={:.1}s feature_start_cell={feature_start}",
+        title.cells.len(),
+        title.chapters,
+        title.duration_secs,
+    );
+    for (i, cell) in title.cells.iter().enumerate() {
+        tracing::debug!(target: DIAG, "{}", dvd_cell_row(i, cell, i < feature_start));
+    }
+    // Chapter/PTT map (program → cumulative start time).
+    for (i, &t) in title.chapter_times.iter().enumerate() {
+        tracing::debug!(
+            target: DIAG,
+            "tag=dvd.chap vts={vts} title={title_num} ch={} time={:.1}s",
+            i + 1,
+            t,
+        );
+    }
+}
+
+/// Emit the IFO `video_attr` / `audio_attr` decode for one DVD title set,
+/// showing the raw bytes next to their decoded meaning. Called from the IFO
+/// scan with the still-parsed `ifo::DvdTitleSet` view.
+pub fn dump_dvd_attrs(ts: &crate::ifo::DvdTitleSet) {
+    if !tracing::enabled!(target: DIAG, tracing::Level::DEBUG) {
+        return;
+    }
+    tracing::debug!(
+        target: DIAG,
+        "tag=dvd.vobs vts={} vob_start_sector={}",
+        ts.vts_number,
+        ts.vob_start_sector,
+    );
+    let v = &ts.video;
+    tracing::debug!(
+        target: DIAG,
+        "tag=dvd.vattr vts={} codec={:?} res={} aspect={:?} std={:?}",
+        ts.vts_number,
+        v.codec,
+        res_str(v.resolution),
+        v.aspect,
+        v.standard,
+    );
+    for (i, a) in ts.audio_streams.iter().enumerate() {
+        tracing::debug!(
+            target: DIAG,
+            "tag=dvd.aattr vts={} idx={i} codec={:?} ch={} sr={}Hz lang={:?} sub_id={:?}",
+            ts.vts_number,
+            a.codec,
+            a.channels,
+            a.sample_rate,
+            a.language,
+            a.sub_stream_id.map(|x| format!("0x{x:02X}")),
+        );
+    }
+    for (i, s) in ts.subtitle_streams.iter().enumerate() {
+        tracing::debug!(
+            target: DIAG,
+            "tag=dvd.sattr vts={} idx={i} lang={:?}",
+            ts.vts_number,
+            s.language,
+        );
+    }
+}
+
+/// Emit the ACTUAL per-physical-sub-stream AC-3 channel counts read off the VOB
+/// during the mux-time sub-stream probe (the Silence-of-the-Lambs wrong-stream
+/// fix). This is the ground truth the IFO nibble is compared against: each row
+/// is `sub_id=0x8x channels=N` for a physical `private_stream_1` AC-3 sub-stream
+/// whose first frame was decoded. An empty probe (scrambled / unreadable / short
+/// VOB) logs a single `probed=0` line so the absence is explicit in a bug log.
+///
+/// Self-sufficiency: with `tag=dvd.aattr` (the IFO's declared sub_id + claimed
+/// channels) and these `tag=dvd.substream` rows (the physical reality), a bug
+/// log alone shows whether the ordinal `0x80` actually carries the declared
+/// channel layout — no disc needed to diagnose a wrong-substream rip.
+pub fn dump_dvd_substream_probe(title_id: u16, probed: &std::collections::BTreeMap<u8, u8>) {
+    if !tracing::enabled!(target: DIAG, tracing::Level::DEBUG) {
+        return;
+    }
+    if probed.is_empty() {
+        tracing::debug!(
+            target: DIAG,
+            "tag=dvd.substream title={title_id} probed=0 (no AC-3 sync in feature head — scrambled/unreadable/none)",
+        );
+        return;
+    }
+    for (sub, ch) in probed {
+        tracing::debug!(
+            target: DIAG,
+            "tag=dvd.substream title={title_id} sub_id=0x{sub:02X} channels={ch} (physical acmod read from VOB)",
+        );
+    }
+}
+
+// ── MKV TrackEntry dump (the ACTUAL container elements written) ──────────────
+
+/// `true` when the `--log-level 3` diagnostic target is enabled. Hot-path
+/// callers (the opening-frame capture) check this once and skip all work when
+/// off, so a normal run pays nothing.
+pub fn diag_enabled() -> bool {
+    tracing::enabled!(target: DIAG, tracing::Level::DEBUG)
+}
+
+/// Cap on the number of codecPrivate bytes rendered to hex in a `tag=mkv.track`
+/// line. The sequence header / avcC / hvcC prefix that matters for diagnosis
+/// (resolution, frame rate, profile) is at the front; a multi-KB blob past this
+/// is summarised as `..(+NB)` rather than flooding the log.
+const CODEC_PRIVATE_HEX_CAP: usize = 64;
+
+/// Render a track's codecPrivate as an uppercase-hex string for the diagnostic
+/// line, capped at [`CODEC_PRIVATE_HEX_CAP`] bytes (`..(+NB)` suffix beyond).
+/// `None` / empty → `"none"`. Pure (no logging) so it is directly unit-testable.
+fn codec_private_hex(cp: Option<&[u8]>) -> String {
+    match cp {
+        Some(b) if !b.is_empty() => {
+            use std::fmt::Write;
+            let shown = b.len().min(CODEC_PRIVATE_HEX_CAP);
+            let mut s = String::with_capacity(shown * 2 + 8);
+            for byte in &b[..shown] {
+                let _ = write!(s, "{byte:02X}");
+            }
+            if b.len() > CODEC_PRIVATE_HEX_CAP {
+                let _ = write!(s, "..(+{}B)", b.len() - CODEC_PRIVATE_HEX_CAP);
+            }
+            s
+        }
+        _ => "none".to_string(),
+    }
+}
+
+/// Frame the raw bytes of one captured opening frame for the `.opening.bin` side
+/// file: `[track:u8][keyframe:u8][pts_ns:i64 LE][len:u32 LE][raw bytes]`. Pure
+/// (no I/O) so the record layout is directly unit-testable; `record` appends the
+/// returned bytes to the side file.
+fn frame_record(track_idx: usize, pts_ns: i64, keyframe: bool, data: &[u8]) -> Vec<u8> {
+    let mut rec = Vec::with_capacity(14 + data.len());
+    rec.push(track_idx as u8);
+    rec.push(keyframe as u8);
+    rec.extend_from_slice(&pts_ns.to_le_bytes());
+    rec.extend_from_slice(&(data.len() as u32).to_le_bytes());
+    rec.extend_from_slice(data);
+    rec
+}
+
+/// Emit the MKV `TrackEntry` elements the muxer is about to WRITE for one
+/// track — the Windows-fps-class metadata (FlagInterlaced, FieldOrder,
+/// DefaultDuration, DefaultDecodedFieldDuration, Display dims) plus the
+/// codecPrivate as hex. With this row a bug log alone is enough to verify why
+/// Windows Explorer reports a given frame rate for an interlaced SD track: the
+/// container values that drive its fps derivation are all present, no disc and
+/// no MediaInfo needed.
+///
+/// `track_number` is the 1-based MKV track number; `track` is the built
+/// [`crate::mux::mkv::MkvTrack`] whose fields map one-to-one onto the emitted
+/// elements (see `MkvMuxer::new`). No-op unless the diag target is on.
+pub fn dump_mkv_track(track_number: u64, track: &crate::mux::mkv::MkvTrack) {
+    if !diag_enabled() {
+        return;
+    }
+    // codecPrivate as hex (capped so a multi-KB hvcC doesn't flood the log; the
+    // sequence header / avcC prefix that matters for diagnosis is at the front).
+    let cp = codec_private_hex(track.codec_private.as_deref());
+    let field_order = match track.field_order {
+        crate::mux::ebml::FIELD_ORDER_TFF => "TFF",
+        crate::mux::ebml::FIELD_ORDER_BFF => "BFF",
+        _ => "—",
+    };
+    // FlagInterlaced is only written for video tracks (1=interlaced/2=progressive);
+    // report what the muxer will emit, or "—" for non-video tracks where the
+    // element is omitted entirely.
+    let interlaced = if track.track_type == crate::mux::ebml::TRACK_TYPE_VIDEO {
+        if track.interlaced {
+            "1(interlaced)"
+        } else {
+            "2(progressive)"
+        }
+    } else {
+        "—"
+    };
+    tracing::debug!(
+        target: DIAG,
+        "tag=mkv.track num={track_number} type={} codec={} flag_interlaced={interlaced} \
+    field_order={field_order} default_duration_ns={} field_duration_ns={} \
+    pixel={}x{} display={}x{} cp_len={} cp_hex={cp}",
+        track.track_type,
+        track.codec_id,
+        track.default_duration_ns,
+        track.field_duration_ns,
+        track.pixel_width,
+        track.pixel_height,
+        track.display_width,
+        track.display_height,
+        track.codec_private.as_ref().map_or(0, |b| b.len()),
+    );
+}
+
+// ── Opening-frame capture (first ~N coded frames per track → side file) ──────
+
+/// Number of coded frames captured PER TRACK before the capture goes dormant.
+/// ~100 frames covers a DVD's first few seconds of every track (the
+/// opening-GOP / still-frame / menu window where mid-GOP open or PTS-floor bugs
+/// show up) while bounding the side file to a few MB even for HD I-frames.
+const OPENING_FRAMES_PER_TRACK: usize = 100;
+
+/// Captures the first [`OPENING_FRAMES_PER_TRACK`] coded frames of EACH track to
+/// a side file (`<output>.opening.bin`) and logs a per-frame summary line, so an
+/// opening-GOP / menu / mid-GOP-open issue is diagnosable from a future log +
+/// side file WITHOUT the disc. Gated to `--log-level 3`: constructed only when
+/// the diag target is on, so a normal run never opens the file or records a byte.
+///
+/// Side-file record framing (so a reader can split it back into frames):
+/// `[track:u8][keyframe:u8][pts_ns:i64 LE][len:u32 LE][raw frame bytes]`.
+pub struct OpeningCapture {
+    file: std::fs::File,
+    /// Frames captured so far, per track index. Capture for a track stops once
+    /// its counter reaches [`OPENING_FRAMES_PER_TRACK`].
+    counts: Vec<usize>,
+}
+
+impl OpeningCapture {
+    /// Open `<output>.opening.bin` next to the MKV output. Returns `None` (no
+    /// capture) when the diag target is off OR the side file can't be created —
+    /// a diagnostic must never fail the rip. `track_count` sizes the per-track
+    /// counters.
+    pub fn new(output_path: &std::path::Path, track_count: usize) -> Option<Self> {
+        if !diag_enabled() {
+            return None;
+        }
+        let mut name = output_path.as_os_str().to_os_string();
+        name.push(".opening.bin");
+        match std::fs::File::create(&name) {
+            Ok(file) => {
+                tracing::debug!(
+                    target: DIAG,
+                    "tag=mkv.opening.open path={:?} per_track_cap={OPENING_FRAMES_PER_TRACK}",
+                    std::path::Path::new(&name),
+                );
+                Some(Self {
+                    file,
+                    counts: vec![0; track_count],
+                })
+            }
+            Err(e) => {
+                tracing::debug!(
+                    target: DIAG,
+                    "tag=mkv.opening.open path={:?} failed={e} (capture disabled, rip unaffected)",
+                    std::path::Path::new(&name),
+                );
+                None
+            }
+        }
+    }
+
+    /// Record one coded frame for `track_idx` if that track is still under its
+    /// per-track cap. Writes the framed raw bytes to the side file and logs a
+    /// one-line summary. A write error disables further capture for the track
+    /// (counter pinned to the cap) but never propagates — the rip is unaffected.
+    pub fn record(&mut self, track_idx: usize, pts_ns: i64, keyframe: bool, data: &[u8]) {
+        let Some(count) = self.counts.get_mut(track_idx) else {
+            return;
+        };
+        if *count >= OPENING_FRAMES_PER_TRACK {
+            return;
+        }
+        use std::io::Write;
+        let rec = frame_record(track_idx, pts_ns, keyframe, data);
+        if let Err(e) = self.file.write_all(&rec) {
+            // Stop trying on this track; a broken side file must not stall mux.
+            *count = OPENING_FRAMES_PER_TRACK;
+            tracing::debug!(
+                target: DIAG,
+                "tag=mkv.opening.frame track={track_idx} write_failed={e} (capture stopped for track)",
+            );
+            return;
+        }
+        *count += 1;
+        tracing::debug!(
+            target: DIAG,
+            "tag=mkv.opening.frame track={track_idx} n={count} type={} size={} pts_ns={pts_ns}",
+            if keyframe { "key" } else { "delta" },
+            data.len(),
+        );
+    }
+}
+
+// ── Disc-level dump (post-lowering: titles, streams, decisions, AACS) ────────
+
+/// Emit the full scan diagnostic block for a built [`Disc`]. Terse, one line
+/// per row, under target `freemkv::diag` at DEBUG. No-op unless that target
+/// is enabled, so it costs nothing when `--log-level 3` is off.
+pub fn dump_disc(disc: &Disc) {
+    if !tracing::enabled!(target: DIAG, tracing::Level::DEBUG) {
+        return;
+    }
+
+    tracing::debug!(
+        target: DIAG,
+        "tag=disc vol={:?} format={:?} content={:?} cap_sectors={} layers={} titles={} encrypted={}",
+        disc.volume_id,
+        disc.format,
+        disc.content_format,
+        disc.capacity_sectors,
+        disc.layers,
+        disc.titles.len(),
+        disc.encrypted,
+    );
+
+    dump_aacs(disc);
+
+    for (ti, title) in disc.titles.iter().enumerate() {
+        dump_title(ti, title);
+    }
+
+    // freemkv's top-level DECISION: which title is the main feature.
+    if let Some(main) = disc.titles.first() {
+        tracing::debug!(
+            target: DIAG,
+            "tag=decision pick=main_feature title_idx=0 playlist={:?} dur={:.1}s \
+        size={}B clips={} reason=canonical_title_order(fits-disc, fewest-clips, longest, richest-audio)",
+            main.playlist,
+            main.duration_secs,
+            main.size_bytes,
+            main.clips.len(),
+        );
+    }
+}
+
+fn dump_aacs(disc: &Disc) {
+    let Some(a) = disc.aacs.as_ref() else {
+        if disc.css.is_some() {
+            tracing::debug!(target: DIAG, "tag=aacs none crypto=CSS(DVD)");
+        } else if disc.encrypted {
+            tracing::debug!(target: DIAG, "tag=aacs none crypto=encrypted-no-keys");
+        } else {
+            tracing::debug!(target: DIAG, "tag=aacs none crypto=clear");
+        }
+        return;
+    };
+    // CPS-unit / unit-key counts: at scan `unit_keys` is empty (keys are
+    // resolved later); the unit-key count is the BE16 in the raw
+    // Unit_Key_RO.inf if captured. Report both: resolved count and raw len.
+    tracing::debug!(
+        target: DIAG,
+        "tag=aacs version={} bus_enc={} mkb_version={:?} disc_hash={} key_source={:?} \
+    vuk={} unit_keys_resolved={} uk_ro_bytes={} mkb_bytes={}",
+        a.version,
+        a.bus_encryption,
+        a.mkb_version,
+        a.disc_hash,
+        a.key_source.name(),
+        a.vuk.is_some(),
+        a.unit_keys.len(),
+        a.uk_ro.len(),
+        a.mkb.len(),
+    );
+}
+
+fn dump_title(ti: usize, title: &DiscTitle) {
+    let (mut nv, mut na, mut ns) = (0u32, 0u32, 0u32);
+    for s in &title.streams {
+        match s {
+            Stream::Video(_) => nv += 1,
+            Stream::Audio(_) => na += 1,
+            Stream::Subtitle(_) => ns += 1,
+        }
+    }
+    tracing::debug!(
+        target: DIAG,
+        "tag=title idx={ti} playlist={:?} id={} dur={:.1}s size={}B clips={} \
+    extents={} chapters={} v={nv} a={na} s={ns} fmt={:?}",
+        title.playlist,
+        title.playlist_id,
+        title.duration_secs,
+        title.size_bytes,
+        title.clips.len(),
+        title.extents.len(),
+        title.chapters.len(),
+        title.content_format,
+    );
+
+    // Per-clip rows (BD: PlayItem/CLPI; DVD has none).
+    for (ci, c) in title.clips.iter().enumerate() {
+        tracing::debug!(
+            target: DIAG,
+            "tag=clip title={ti} idx={ci} id={:?} in={} out={} dur={:.1}s src_packets={}",
+            c.clip_id,
+            c.in_time,
+            c.out_time,
+            c.duration_secs,
+            c.source_packets,
+        );
+    }
+
+    // Per-extent rows (the sectors freemkv will actually rip — the bug-4
+    // decision is visible here: leading non-feature cells are already gone).
+    for (ei, e) in title.extents.iter().enumerate() {
+        tracing::debug!(
+            target: DIAG,
+            "tag=extent title={ti} idx={ei} start_lba={} sectors={}",
+            e.start_lba,
+            e.sector_count,
+        );
+    }
+
+    // freemkv's per-stream DECISIONS (what the muxer will write).
+    for (si, s) in title.streams.iter().enumerate() {
+        match s {
+            Stream::Video(v) => tracing::debug!(
+                target: DIAG,
+                "tag=stream title={ti} idx={si} kind=video pid=0x{:04X} codec={:?} \
+            res={} interlaced={} fps={} std={} color={} hdr={} aspect={:?} secondary={}",
+                v.pid,
+                v.codec,
+                res_str(v.resolution),
+                v.resolution.is_interlaced(),
+                fps_str(v.frame_rate),
+                tv_system_str(v.frame_rate),
+                color_str(v.color_space),
+                hdr_str(v.hdr),
+                v.display_aspect,
+                v.secondary,
+            ),
+            Stream::Audio(a) => tracing::debug!(
+                target: DIAG,
+                "tag=stream title={ti} idx={si} kind=audio pid=0x{:04X} codec={:?} \
+            channels={}({}) sr={}Hz lang={:?} secondary={}",
+                a.pid,
+                a.codec,
+                a.channels,
+                channel_count(a.channels),
+                sample_rate_hz(a.sample_rate),
+                a.language,
+                a.secondary,
+            ),
+            Stream::Subtitle(sub) => tracing::debug!(
+                target: DIAG,
+                "tag=stream title={ti} idx={si} kind=subtitle pid=0x{:04X} codec={:?} \
+            lang={:?} forced={}",
+                sub.pid,
+                sub.codec,
+                sub.language,
+                sub.forced,
+            ),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn res_str_keeps_interlace_marker() {
+        assert_eq!(res_str(Resolution::R576i), "576i");
+        assert_eq!(res_str(Resolution::R480i), "480i");
+        assert_eq!(res_str(Resolution::R2160p), "2160p");
+    }
+
+    #[test]
+    fn fps_and_tv_system() {
+        assert_eq!(fps_str(FrameRate::F25), "25");
+        assert_eq!(tv_system_str(FrameRate::F25), "PAL");
+        assert_eq!(fps_str(FrameRate::F29_97), "29.97");
+        assert_eq!(tv_system_str(FrameRate::F29_97), "NTSC");
+    }
+
+    #[test]
+    fn color_and_hdr() {
+        assert_eq!(color_str(ColorSpace::Bt470bg), "BT.470BG");
+        assert_eq!(color_str(ColorSpace::Bt2020), "BT.2020");
+        assert_eq!(hdr_str(HdrFormat::Hdr10), "HDR10");
+        assert_eq!(hdr_str(HdrFormat::DolbyVision), "DoVi");
+        assert_eq!(hdr_str(HdrFormat::Sdr), "SDR");
+    }
+
+    #[test]
+    fn channel_count_matches_layout() {
+        assert_eq!(channel_count(AudioChannels::Mono), 1);
+        assert_eq!(channel_count(AudioChannels::Stereo), 2);
+        assert_eq!(channel_count(AudioChannels::Surround51), 6);
+        assert_eq!(channel_count(AudioChannels::Surround71), 8);
+    }
+
+    #[test]
+    fn sample_rate_hz_values() {
+        assert_eq!(sample_rate_hz(SampleRate::S48), 48000);
+        assert_eq!(sample_rate_hz(SampleRate::S96), 96000);
+    }
+
+    #[test]
+    fn codec_private_hex_renders_caps_and_handles_empty() {
+        // None / empty → "none" (no hex). The Windows-fps diagnosis only needs
+        // the seq-header prefix, so render it but cap long blobs.
+        assert_eq!(codec_private_hex(None), "none");
+        assert_eq!(codec_private_hex(Some(&[])), "none");
+        // Short blob: full uppercase hex, no suffix. An MPEG-2 seq header starts
+        // 00 00 01 B3 — exactly what a reader greps for in a bug log.
+        assert_eq!(
+            codec_private_hex(Some(&[0x00, 0x00, 0x01, 0xB3])),
+            "000001B3"
+        );
+        // Over the cap: first CODEC_PRIVATE_HEX_CAP bytes + a "..(+NB)" summary.
+        let big = vec![0xABu8; CODEC_PRIVATE_HEX_CAP + 5];
+        let s = codec_private_hex(Some(&big));
+        assert!(s.starts_with(&"AB".repeat(CODEC_PRIVATE_HEX_CAP)), "{s}");
+        assert!(s.ends_with("..(+5B)"), "{s}");
+    }
+
+    #[test]
+    fn frame_record_layout_is_parseable() {
+        // The .opening.bin record framing must round-trip so a future tool can
+        // split the side file back into frames without the disc:
+        // [track:u8][keyframe:u8][pts_ns:i64 LE][len:u32 LE][raw bytes].
+        let data = [0xDEu8, 0xAD, 0xBE, 0xEF];
+        let rec = frame_record(2, -40_000_000, true, &data);
+        assert_eq!(rec.len(), 14 + data.len());
+        assert_eq!(rec[0], 2, "track index");
+        assert_eq!(rec[1], 1, "keyframe flag");
+        assert_eq!(
+            i64::from_le_bytes(rec[2..10].try_into().unwrap()),
+            -40_000_000,
+            "pts_ns survives (signed — opening back-anchor can be negative)"
+        );
+        assert_eq!(
+            u32::from_le_bytes(rec[10..14].try_into().unwrap()),
+            4,
+            "len"
+        );
+        assert_eq!(&rec[14..], &data, "raw frame bytes follow");
+        // A non-keyframe records the flag as 0.
+        let delta = frame_record(0, 0, false, &[]);
+        assert_eq!(delta[1], 0);
+        assert_eq!(u32::from_le_bytes(delta[10..14].try_into().unwrap()), 0);
+    }
+
+    /// The cell row shows the raw category byte (0xNN) beside the decode, and
+    /// the keep/drop verdict. A plain feature cell (0x00) is "keep"; a leading
+    /// secondary-block cell flagged dropped reads "DROP".
+    #[test]
+    fn cell_row_shows_raw_byte_and_verdict() {
+        let plain = crate::ifo::DvdCell {
+            first_sector: 100,
+            last_sector: 199,
+            category: 0x00,
+            duration_secs: 12.5,
+        };
+        let row = dvd_cell_row(0, &plain, false);
+        assert!(row.contains("cat=0x00"), "{row}");
+        assert!(row.contains("block_mode=0"), "{row}");
+        assert!(row.contains("first=100"), "{row}");
+        assert!(row.contains("last=199"), "{row}");
+        assert!(row.contains("dur=12.5s"), "{row}");
+        assert!(row.contains("keep(plain-feature)"), "{row}");
+        assert!(!row.contains("DROP"), "{row}");
+
+        // 0x90 = in-block cell of an angle block (block_mode=2, block_type=1),
+        // shown dropped as a leading secondary piece.
+        let sec = crate::ifo::DvdCell {
+            first_sector: 0,
+            last_sector: 9,
+            category: 0x90,
+            duration_secs: 1.0,
+        };
+        let row = dvd_cell_row(0, &sec, true);
+        assert!(row.contains("cat=0x90"), "{row}");
+        assert!(row.contains("block_mode=2"), "{row}");
+        assert!(row.contains("block_type=1"), "{row}");
+        assert!(row.contains("DROP(leading-secondary-block-piece)"), "{row}");
+    }
+}

src/disc/dvd_audio_probe.rs

@@ -0,0 +1,466 @@
+//! Physical AC-3 sub-stream probing for DVD audio routing.
+//!
+//! ## Why this exists (Silence-of-the-Lambs wrong-substream bug)
+//!
+//! A DVD VTS IFO declares its audio streams in a fixed table, and freemkv's
+//! scan assigns each declared stream a `private_stream_1` sub-stream id purely
+//! by per-codec ordinal — the first AC-3 stream becomes `0x80`, the second
+//! `0x81`, and so on (`ifo::assign_audio_sub_stream_ids`). That assumes the
+//! physical sub-stream order on the wire matches the IFO declaration order.
+//!
+//! On some discs it does NOT. The R2 PAL "The Silence of the Lambs" feature
+//! declares ONE AC-3 audio stream the IFO nibble marks as 5.1 (6 channels), but
+//! the physical VOB carries the 5.1 main mix and a 2.0 down-mix on DIFFERENT
+//! `0x8x` sub-stream ids, and the 2.0 is the one that happens to land at the
+//! ordinal `0x80` slot. Routing the declared 5.1 stream to `0x80` by ordinal
+//! therefore muxes the 2.0 down-mix while labelling it 5.1 — the wrong physical
+//! track.
+//!
+//! The robust fix is data-driven and codec/disc agnostic: read each physical
+//! AC-3 sub-stream's REAL channel count from the VOB (the `acmod`/`lfeon` of its
+//! first frame after the `0x0B77` sync) and route each IFO-declared AC-3 stream
+//! to the physical sub-stream whose actual channel count matches the IFO's
+//! declared count — instead of trusting the ordinal. This never re-reads the
+//! disc beyond a bounded head-of-feature probe and degrades to the original
+//! ordinal mapping when the probe yields nothing (unreadable/short VOB).
+
+use crate::disc::Stream;
+use crate::mux::codec::ac3;
+use crate::mux::ps::PsDemuxer;
+use crate::sector::SectorSource;
+use std::collections::BTreeMap;
+
+/// How many 2048-byte sectors of the first feature extent to probe. The head of
+/// a DVD feature opens with logos/warnings whose audio is frequently a thin 2.0
+/// bed on the FIRST sub-stream only — the other physical `0x8x` sub-streams and
+/// the main 5.1 mix do not appear until a sector or two further in. 512 sectors
+/// (1 MiB) was too short: on Greenland it saw ONLY `0x80`, and only its opening
+/// 2.0 frames. 1024 sectors (2 MiB) reliably contains at least one frame of
+/// every physical AC-3 sub-stream AND enough of `0x80` to reach its 5.1 frames.
+/// Still bounded so a live drive is never hammered (see the project "don't
+/// hammer the live drive" rule).
+const PROBE_SECTORS: u16 = 1024;
+
+/// Decode the real per-sub-stream AC-3 channel count from a buffer of decrypted
+/// MPEG-PS (DVD VOB) bytes.
+///
+/// Demuxes `private_stream_1` (0xBD), and for each AC-3 sub-stream id
+/// (`0x80..=0x87`) records the MAXIMUM channel count seen across EVERY decodable
+/// frame in the probe window (`acmod` + `lfeon` at each `0x0B77` sync). Pure and
+/// unit-testable — takes the already-read bytes, never touches the disc.
+///
+/// ## Why the maximum, not the first frame
+///
+/// The first frame of a sub-stream at the head of a feature is NOT
+/// representative. A DVD opens with logos/warnings, and the main `0x80`
+/// sub-stream there frequently carries a thin 2.0 bed before transitioning to
+/// its real 5.1 main mix a fraction of a second later (observed on Greenland:
+/// `0x80`'s first frames are acmod=2 → 2 channels, then it becomes acmod=7+lfe →
+/// 6 channels within the same 2 MiB window). Recording only the FIRST frame read
+/// `0x80=2` and missed the 5.1 entirely, defeating the channel-match routing.
+/// The 5.1 capability of a sub-stream is the *maximum* channel count any of its
+/// frames carries, so we scan them all and keep the max.
+///
+/// Returns a map `sub_id -> max channels`. Sub-streams whose frames are all too
+/// short to carry the BSI bits, or that never appear in the buffer, are absent
+/// from the map.
+pub fn probe_ac3_substream_channels(ps_bytes: &[u8]) -> BTreeMap<u8, u8> {
+    let mut found: BTreeMap<u8, u8> = BTreeMap::new();
+    let mut demux = PsDemuxer::new();
+    let mut packets = demux.feed(ps_bytes);
+    packets.extend(demux.flush());
+    for p in packets {
+        // Only private_stream_1 AC-3 sub-streams (0x80..=0x87).
+        let Some(sub) = p.sub_stream_id else { continue };
+        if !(0x80..=0x87).contains(&sub) {
+            continue;
+        }
+        // The PS demux strips the 4-byte AC-3 sub-header but does not align to a
+        // frame. Walk EVERY 0x0B77 sync in this sub-stream's payload, decode
+        // each frame's channel count, and keep the largest — the sub-stream's
+        // real (main-mix) channel capability. See the doc comment above for why
+        // the first frame alone is unreliable.
+        if let Some(ch) = max_substream_channels(&p.data) {
+            let slot = found.entry(sub).or_insert(0);
+            *slot = (*slot).max(ch);
+        }
+    }
+    found
+}
+
+/// Largest AC-3 channel count over every decodable frame in a single
+/// sub-stream's payload. Returns `None` when no frame carries enough BSI bits.
+///
+/// Each frame is advanced by its real `ac3_frame_size` so a frame's compressed
+/// body (which can contain stray `0x0B77` byte pairs) cannot be mistaken for a
+/// new frame; only when a size is unmappable do we fall back to a +2 byte
+/// rescan to re-lock the next genuine sync.
+fn max_substream_channels(data: &[u8]) -> Option<u8> {
+    let mut best: Option<u8> = None;
+    let mut pos = 0;
+    while pos < data.len() {
+        let Some(rel) = ac3::find_ac3_sync(&data[pos..]) else {
+            break;
+        };
+        let start = pos + rel;
+        let frame = &data[start..];
+        if let Some(ch) = ac3::acmod_channels(frame) {
+            if ch > 0 {
+                best = Some(best.map_or(ch, |b| b.max(ch)));
+            }
+        }
+        // Advance past this frame by its declared size when that is mappable;
+        // otherwise step 2 bytes past the sync and re-scan for the next one.
+        let size = ac3::ac3_frame_size(frame);
+        pos = if (6..=8192).contains(&size) {
+            start + size
+        } else {
+            start + 2
+        };
+    }
+    best
+}
+
+/// Re-route the title's declared AC-3 audio streams onto the physical
+/// sub-stream ids whose REAL channel counts match, using a probed
+/// `sub_id -> channels` map.
+///
+/// For each declared AC-3 audio stream (in IFO order), it picks the physical
+/// `0x8x` sub-stream whose probed channel count equals the stream's declared
+/// channel count, never re-using a sub-stream already claimed by an earlier
+/// stream. The chosen sub-stream's PID (`0xBD00 | sub_id`) is written back onto
+/// the `Stream::Audio` so BOTH mux demux paths (`DiscStream` and the file-backed
+/// highway) route by it.
+///
+/// Conservative — it only ever REASSIGNS among the physical sub-streams the
+/// probe actually saw, and only when a better (exact-channel) match exists than
+/// the stream's current assignment. A stream whose current sub-stream already
+/// matches is left alone; a stream with no matching physical sub-stream keeps
+/// its ordinal assignment. So a normal disc (physical order == IFO order) is a
+/// no-op.
+///
+/// Returns the number of streams whose PID was changed (for diagnostics).
+pub fn remap_audio_pids(streams: &mut [Stream], probed: &BTreeMap<u8, u8>) -> usize {
+    if probed.is_empty() {
+        return 0;
+    }
+    // Sub-streams already claimed by a remapped (or matching) earlier stream,
+    // so two declared streams never collide on one physical sub-stream.
+    let mut claimed: Vec<u8> = Vec::new();
+    let mut changed = 0usize;
+
+    for s in streams.iter_mut() {
+        let Stream::Audio(a) = s else { continue };
+        if a.codec != crate::disc::Codec::Ac3 {
+            continue;
+        }
+        let declared = a.channels.count();
+        // The sub-id this stream currently routes by (low byte of its PID).
+        let current_sub = (a.pid & 0x00FF) as u8;
+
+        // If the stream's current physical sub-stream already matches its
+        // declared channel count, keep it and claim it.
+        if probed.get(&current_sub) == Some(&declared) {
+            claimed.push(current_sub);
+            continue;
+        }
+
+        // Otherwise find an unclaimed physical sub-stream whose REAL channel
+        // count equals the declared count.
+        let pick = probed
+            .iter()
+            .find(|(sub, ch)| **ch == declared && !claimed.contains(*sub))
+            .map(|(sub, _)| *sub);
+
+        if let Some(sub) = pick {
+            let new_pid = 0xBD00 | sub as u16;
+            if new_pid != a.pid {
+                tracing::debug!(
+                    target: "freemkv::scan",
+                    old_pid = a.pid,
+                    new_pid,
+                    declared_channels = declared,
+                    "dvd: re-routed AC-3 audio to physical sub-stream matching channel count"
+                );
+                a.pid = new_pid;
+                changed += 1;
+            }
+            claimed.push(sub);
+        } else {
+            // No physical match — leave the ordinal assignment, but claim its
+            // current sub so later streams don't steal a slot it may still use.
+            claimed.push(current_sub);
+        }
+    }
+    changed
+}
+
+/// Probe the first feature extent of a DVD title through a (decrypted) sector
+/// source and re-route its AC-3 audio PIDs to the physically-correct
+/// sub-streams. A bounded, best-effort scan: any read error or empty probe
+/// leaves the ordinal assignment untouched.
+///
+/// `reader` MUST yield PLAINTEXT VOB bytes (i.e. a `DecryptingSectorSource` on a
+/// CSS disc) — probing scrambled sectors yields no AC-3 syncs and is a safe
+/// no-op. Returns the number of audio streams whose PID changed.
+pub fn probe_and_remap<S: SectorSource + ?Sized>(
+    reader: &mut S,
+    title: &mut crate::disc::DiscTitle,
+) {
+    // Only DVD (MPEG-PS) titles carry private_stream_1 AC-3 sub-streams.
+    if title.content_format != crate::disc::ContentFormat::MpegPs {
+        return;
+    }
+    // Nothing to disambiguate unless there is at least one AC-3 audio stream.
+    let has_ac3 = title
+        .streams
+        .iter()
+        .any(|s| matches!(s, Stream::Audio(a) if a.codec == crate::disc::Codec::Ac3));
+    if !has_ac3 {
+        return;
+    }
+    let Some(ext) = title.extents.first() else {
+        return;
+    };
+    let count: u16 = ext.sector_count.min(PROBE_SECTORS as u32) as u16;
+    if count == 0 {
+        return;
+    }
+    let mut buf = vec![0u8; count as usize * 2048];
+    // `recovery=false`: a single best-effort attempt — the probe must never
+    // stall the mux or hammer a marginal drive. On any error, bail to ordinal.
+    let n = match reader.read_sectors(ext.start_lba, count, &mut buf, false) {
+        Ok(n) => n,
+        Err(_) => return,
+    };
+    buf.truncate(n);
+    let probed = probe_ac3_substream_channels(&buf);
+    crate::diag::dump_dvd_substream_probe(title.playlist_id, &probed);
+    remap_audio_pids(&mut title.streams, &probed);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::disc::{AudioChannels, AudioStream, Codec, LabelPurpose, SampleRate};
+
+    /// Build a single, correctly-SIZED AC-3 frame whose `acmod`/`lfeon` encode a
+    /// known channel count. `byte4` is `fscod=0 | frmsizecod=0`, so
+    /// `ac3_frame_size` reports 128 bytes and the frame is zero-padded to exactly
+    /// that — this lets `max_substream_channels` advance frame-by-frame over a
+    /// multi-frame payload exactly as it does on real VOB data. The BSI bits are
+    /// laid down with a writer so the test never hand-miscomputes the lfeon
+    /// offset, matching `acmod_channels`' reader.
+    fn ac3_frame(acmod: u8, lfeon: bool) -> Vec<u8> {
+        let mut bits: Vec<u8> = Vec::new();
+        let push = |val: u32, n: usize, bits: &mut Vec<u8>| {
+            for i in (0..n).rev() {
+                bits.push(((val >> i) & 1) as u8);
+            }
+        };
+        push(acmod as u32, 3, &mut bits);
+        if (acmod & 0x1) != 0 && acmod != 0x1 {
+            push(0, 2, &mut bits); // cmixlev
+        }
+        if (acmod & 0x4) != 0 {
+            push(0, 2, &mut bits); // surmixlev
+        }
+        if acmod == 0x2 {
+            push(0, 2, &mut bits); // dsurmod
+        }
+        push(lfeon as u32, 1, &mut bits);
+        // Pack the bit vector MSB-first into bytes (byte6 onward).
+        let mut tail = Vec::new();
+        let mut cur = 0u8;
+        for (i, b) in bits.iter().enumerate() {
+            cur = (cur << 1) | b;
+            if i % 8 == 7 {
+                tail.push(cur);
+                cur = 0;
+            }
+        }
+        let rem = bits.len() % 8;
+        if rem != 0 {
+            cur <<= 8 - rem;
+            tail.push(cur);
+        }
+        // AC-3 frame: 0x0B 0x77 crc(2) byte4(fscod=0,frmsizecod=0) bsid<<3 then BSI.
+        let mut frame = vec![0x0B, 0x77, 0x00, 0x00, 0x00, 8u8 << 3];
+        frame.extend_from_slice(&tail);
+        // frmsizecod=0 @ 48kHz → 64 words = 128 bytes. Pad to the real size so
+        // the frame-stepping in max_substream_channels lands on the next sync.
+        frame.resize(128, 0);
+        frame
+    }
+
+    /// Build a minimal `private_stream_1` PES carrying `frames` for `sub_id`,
+    /// each preceded only by the 4-byte AC-3 sub-header at the PES head. Mirrors
+    /// the on-disc layout the PS demux expects: PES start `0x000001BD`, length,
+    /// PES header (no PTS), sub-header `[sub_id, frame_count, ptr_hi, ptr_lo]`,
+    /// then the concatenated AC-3 frames.
+    fn ps_ac3_frames(sub_id: u8, frames: &[Vec<u8>]) -> Vec<u8> {
+        // PES sub-header for AC-3: sub_id + frame_count + 2-byte access ptr.
+        let mut payload = vec![sub_id, frames.len() as u8, 0x00, 0x04];
+        for f in frames {
+            payload.extend_from_slice(f);
+        }
+        // PES packet: start code 00 00 01 BD, length(2), flags(2), hdr_len(0).
+        let pes_payload_len = 3 + payload.len(); // flags(2)+hdrlen(1)+payload
+        let mut pkt = vec![0x00, 0x00, 0x01, 0xBD];
+        pkt.extend_from_slice(&(pes_payload_len as u16).to_be_bytes());
+        pkt.extend_from_slice(&[0x80, 0x00, 0x00]); // no PTS, header_data_len=0
+        pkt.extend_from_slice(&payload);
+        pkt
+    }
+
+    /// Single-frame `private_stream_1` PES — the common case in existing tests.
+    fn ps_ac3(sub_id: u8, acmod: u8, lfeon: bool) -> Vec<u8> {
+        ps_ac3_frames(sub_id, &[ac3_frame(acmod, lfeon)])
+    }
+
+    fn ac3_stream(pid: u16, channels: AudioChannels) -> Stream {
+        Stream::Audio(AudioStream {
+            pid,
+            codec: Codec::Ac3,
+            channels,
+            language: "en".into(),
+            sample_rate: SampleRate::S48,
+            secondary: false,
+            purpose: LabelPurpose::Normal,
+            label: String::new(),
+        })
+    }
+
+    /// The probe decodes the real channel count of each physical sub-stream.
+    /// 0x80 carries a 2.0 frame (acmod=2,no lfe → 2ch); 0x81 carries 5.1
+    /// (acmod=7 + lfe → 6ch).
+    #[test]
+    fn probe_decodes_per_substream_channels() {
+        let mut bytes = ps_ac3(0x80, 2, false);
+        bytes.extend(ps_ac3(0x81, 7, true));
+        let probed = probe_ac3_substream_channels(&bytes);
+        assert_eq!(probed.get(&0x80), Some(&2), "0x80 is the 2.0 down-mix");
+        assert_eq!(probed.get(&0x81), Some(&6), "0x81 is the 5.1 main mix");
+    }
+
+    /// GREENLAND regression — the probe must read each sub-stream's TRUE
+    /// (max-mix) channel count, not be poisoned by an unrepresentative head
+    /// frame, and must NOT cross-contaminate between sub-streams.
+    ///
+    /// Mirrors the real on-disc layout that caused the mis-read: the feature
+    /// head carries `0x80` opening with a 2.0 frame and THEN a 5.1 frame (its
+    /// real main mix), interleaved with `0x81` carrying only 2.0. The old
+    /// first-frame probe read `0x80=2` (the logo bed) and missed the 5.1; the
+    /// max-over-frames probe must report `0x80=6` and `0x81=2`.
+    #[test]
+    fn probe_reads_max_channels_no_cross_contamination() {
+        let mut bytes = Vec::new();
+        // 0x80 opens with a 2.0 frame (the logo bed)...
+        bytes.extend(ps_ac3_frames(0x80, &[ac3_frame(2, false)]));
+        // ...0x81 interleaves a pure-2.0 PES (must NOT bleed 6 into 0x80)...
+        bytes.extend(ps_ac3_frames(
+            0x81,
+            &[ac3_frame(2, false), ac3_frame(2, false)],
+        ));
+        // ...then 0x80 reaches its real 5.1 main mix (acmod=7 + lfe → 6 ch),
+        // with a trailing 2.0 frame in the SAME PES to prove we take the max,
+        // not the last frame.
+        bytes.extend(ps_ac3_frames(
+            0x80,
+            &[ac3_frame(7, true), ac3_frame(2, false)],
+        ));
+
+        let probed = probe_ac3_substream_channels(&bytes);
+        assert_eq!(
+            probed.get(&0x80),
+            Some(&6),
+            "0x80's real 5.1 mix must win over its 2.0 head/tail frames"
+        );
+        assert_eq!(
+            probed.get(&0x81),
+            Some(&2),
+            "0x81 is a pure 2.0 stream — must not absorb 0x80's 6-channel frame"
+        );
+    }
+
+    /// SILENCE-OF-THE-LAMBS regression: the IFO declares ONE 5.1 AC-3 stream and
+    /// the ordinal mapping put it at 0x80, but physically 0x80 is the 2.0
+    /// down-mix and the 5.1 lives at 0x81. After probe+remap the declared 5.1
+    /// stream must route to 0x81 (PID 0xBD81), NOT the ordinal 0x80.
+    #[test]
+    fn remap_routes_declared_51_to_physical_51_substream() {
+        // Physical layout: 0x80 = 2.0, 0x81 = 5.1 (reversed vs ordinal).
+        let mut probed = BTreeMap::new();
+        probed.insert(0x80u8, 2u8);
+        probed.insert(0x81u8, 6u8);
+
+        // Declared: one 5.1 stream, ordinally assigned 0x80 (PID 0xBD80).
+        let mut streams = vec![ac3_stream(0xBD80, AudioChannels::Surround51)];
+        let changed = remap_audio_pids(&mut streams, &probed);
+        assert_eq!(changed, 1, "the one 5.1 stream must be re-routed");
+        let Stream::Audio(a) = &streams[0] else {
+            panic!("audio")
+        };
+        assert_eq!(
+            a.pid, 0xBD81,
+            "declared 5.1 must route to physical 0x81 (the real 5.1), not ordinal 0x80"
+        );
+    }
+
+    /// Conservative no-op: when the physical order already matches the IFO
+    /// order (0x80 = 5.1 as declared), remap changes nothing.
+    #[test]
+    fn remap_noop_when_physical_matches_ordinal() {
+        let mut probed = BTreeMap::new();
+        probed.insert(0x80u8, 6u8); // 0x80 really is the 5.1
+        let mut streams = vec![ac3_stream(0xBD80, AudioChannels::Surround51)];
+        let changed = remap_audio_pids(&mut streams, &probed);
+        assert_eq!(changed, 0, "matching physical order is a no-op");
+        let Stream::Audio(a) = &streams[0] else {
+            panic!()
+        };
+        assert_eq!(a.pid, 0xBD80);
+    }
+
+    /// Two declared streams (5.1 + 2.0) where the physical order is reversed:
+    /// 0x80=2.0, 0x81=5.1. The 5.1 declaration must claim 0x81 and the 2.0
+    /// declaration must claim 0x80 — no collision, both correct.
+    #[test]
+    fn remap_two_streams_no_collision() {
+        let mut probed = BTreeMap::new();
+        probed.insert(0x80u8, 2u8);
+        probed.insert(0x81u8, 6u8);
+        // Declared order: 5.1 first (ordinal 0x80), 2.0 second (ordinal 0x81).
+        let mut streams = vec![
+            ac3_stream(0xBD80, AudioChannels::Surround51),
+            ac3_stream(0xBD81, AudioChannels::Stereo),
+        ];
+        remap_audio_pids(&mut streams, &probed);
+        let pids: Vec<u16> = streams
+            .iter()
+            .filter_map(|s| match s {
+                Stream::Audio(a) => Some(a.pid),
+                _ => None,
+            })
+            .collect();
+        assert_eq!(
+            pids,
+            vec![0xBD81, 0xBD80],
+            "5.1→0x81, 2.0→0x80, no collision"
+        );
+    }
+
+    /// Empty probe (unreadable / scrambled VOB) is a no-op — the ordinal
+    /// assignment survives so behaviour never regresses below today's.
+    #[test]
+    fn remap_empty_probe_is_noop() {
+        let probed = BTreeMap::new();
+        let mut streams = vec![ac3_stream(0xBD80, AudioChannels::Surround51)];
+        let changed = remap_audio_pids(&mut streams, &probed);
+        assert_eq!(changed, 0);
+        let Stream::Audio(a) = &streams[0] else {
+            panic!()
+        };
+        assert_eq!(a.pid, 0xBD80, "no probe data → keep ordinal");
+    }
+}

src/disc/read_error.rs

@@ -1,11 +1,10 @@
 //! Single source of truth for what to do when a sector read fails.
 //!
-//! Both Pass 1 (`Disc::sweep`) and Pass 2-N (`Disc::patch`) call into
-//! `handle_read_error` after every failed `read_sectors`. The handler
-//! classifies the error, updates the in-flight context (counters,
-//! damage window, retry budgets), and returns a `ReadAction` the caller
-//! dispatches on. Every read goes through the same gate — no path can
-//! silently skip pause/skip/jump/abort logic.
+//! Pass 1 (`Disc::sweep`) calls into `handle_read_error` after every failed
+//! `read_sectors`. The handler classifies the error, updates the in-flight
+//! context (counters, damage window, retry budgets), and returns a
+//! `ReadAction` the caller dispatches on. Pass N patch has its own
+//! `handle_read_failure` in `disc/patch.rs` that does not route here.
 //!
 //! Adding a new error class = add one arm in `handle_read_error`.
 //! Adding new logging on errors = one place.
@@ -34,14 +33,20 @@ pub struct ReadCtx {
     /// Sliding window of recent read outcomes (true=ok, false=fail).
     /// Capped at `damage_window_max`. Drives damage-jump decisions.
     pub damage_window: Vec<bool>,
+    /// Maximum number of outcome entries kept in `damage_window`; the
+    /// oldest is evicted once this is exceeded. A whole count (e.g. 16).
     pub damage_window_max: usize,
+    /// Fraction of `damage_window` entries that must be failures before
+    /// the window-based damage-jump fires, as a whole-number percentage
+    /// (e.g. `12` = 12%).
     pub damage_threshold_pct: usize,
     /// Trigger a damage-jump after this many consecutive outer-batch
     /// failures, even when the damage_window isn't full yet. Pass 1
-    /// uses a small value (4) so we don't spend ~40 minutes grinding
-    /// to fill a 16-block window before the first jump on a damage
-    /// zone we entered cleanly. Pass N uses a larger value (or
-    /// disables this — see `bisect_on_marginal`) because Pass N's
+    /// uses a small value (1 — jump on the first outer failure; see
+    /// the 2026-05-11 rewrite in `for_sweep`) so we don't spend ~40
+    /// minutes grinding to fill a 16-block window before the first jump
+    /// on a damage zone we entered cleanly. Pass N uses a larger value
+    /// (or disables this — see `bisect_on_marginal`) because Pass N's
     /// whole job IS to grind on the bad ranges.
     pub fast_jump_threshold: u64,
     /// Multiplier applied to damage-jump distance. Doubles each jump,
@@ -151,8 +156,12 @@ impl ReadCtx {
     /// outer-batch failure — the user's wedge-prevention principle
     /// (2026-05-11): once the drive returns ANY recoverable error,
     /// retrying the same LBA quickly is what triggers the firmware
-    /// fast-fail transition. Jump immediately, never retry in Pass 1.
-    /// Pass N owns retries — it gets per-sector timeouts that don't
+    /// fast-fail transition. On the damage-jump and marginal paths Pass 1
+    /// jumps immediately rather than grinding the same LBA. Transient errors
+    /// (NOT_READY, bridge degradation) are still retried a small bounded
+    /// number of times (`NOT_READY_MAX_RETRIES` / `BRIDGE_DEGRADATION_MAX_RETRIES`)
+    /// in both passes before falling through to the skip path.
+    /// Pass N owns the heavy retries — it gets per-sector timeouts that don't
     /// hammer the firmware the same way.
     pub fn for_sweep(batch: u16) -> Self {
         Self {
@@ -193,9 +202,10 @@ impl ReadCtx {
     /// patch loop's whole job is to chip away at bad ranges — being
     /// more eager to skip clustered bad sectors converges faster on
     /// the recoverable good sectors inside a range. The patch-side
-    /// `compute_damage_skip` reads its threshold from
-    /// `PASSN_DAMAGE_THRESHOLD_PCT`; keep the two in sync until the
-    /// patch loop's damage-skip is unified with `handle_read_error`'s
+    /// `compute_damage_skip` reads its threshold directly from
+    /// `PASSN_DAMAGE_THRESHOLD_PCT`, which is an alias for this crate's
+    /// `PATCH_DAMAGE_THRESHOLD_PCT`, so the two are always in sync.
+    /// The patch loop's damage-skip is not yet unified with `handle_read_error`'s
     /// jump path. (v0.20.8 unification attempt found the unification
     /// itself blocked on the size-aware `range_remaining/4` cap that
     /// lives in `compute_damage_skip` but not in
@@ -240,6 +250,13 @@ impl ReadCtx {
         // drive recovered, so further wedges should reset the skip
         // budget instead of accumulating toward a real abort.
         self.wedge_count = 0;
+        // A successful read also means the bridge recovered, so the
+        // 15s-cooldown retry budget should be available again for the
+        // next bridge-degradation event. Without this reset the budget
+        // saturates permanently after 5 cumulative events across the
+        // whole pass and later degradations skip the cooldown retry,
+        // needlessly losing data.
+        self.bridge_degradation_count = 0;
         // Outer-success only: a good single-sector read inside a
         // bisect doesn't mean we've left the damaged batch. Only an
         // outer-batch success resets the outer-failure counter.
@@ -259,6 +276,13 @@ impl ReadCtx {
         if self.in_damage_zone && self.consecutive_good >= self.damage_window_max as u64 {
             self.in_damage_zone = false;
             self.last_error_family = None;
+            // Reset the damage-jump multiplier so the NEXT zone starts
+            // from the base jump distance. Without this the multiplier
+            // stays at whatever the prior zone inflated it to (up to
+            // MAX_JUMP_MULTIPLIER=64), so the next zone's first jump is
+            // 64x oversized and skips recoverable data. The field doc
+            // promises this reset.
+            self.jump_multiplier = 1;
         }
     }
 
@@ -316,7 +340,8 @@ pub enum ReadAction {
 // bridge wedges 524 ms after a 5.4-second internal ECC retry. The
 // post-failure pauses give the drive — and the bridge — time to settle.
 /// Pause between a failed read and the next read attempt — applied
-/// uniformly to Pass 1 sweep and Pass N patch.
+/// by Pass 1 sweep via `handle_read_error`. Pass N patch uses its own
+/// `POST_FAILURE_PAUSE_SECS` (see `disc/patch.rs`).
 ///
 /// 2026-05-11 reframe: a failed read is a failed read, regardless of
 /// which pass is running. The prior split (1s for Pass N, 5s for Pass
@@ -334,7 +359,7 @@ const FAIL_PAUSE_SECS: u64 = 5;
 /// FIRST read failure after a clean run, before the drive has had a
 /// chance to cycle in retries that push it toward fast-fail).
 ///
-/// Empirical: 2026-05-11 Dune Pt 2 wedge incident showed 7 medium
+/// Empirical: a 2026-05-11 wedge incident showed 7 medium
 /// errors in 6.5 seconds (~1s per attempt + ~1s pause) push the
 /// BU40N's firmware into IllegalRequest fast-fail mode permanently.
 /// Once there, only physical eject + reload clears it. Giving the
@@ -345,7 +370,7 @@ const FAIL_PAUSE_SECS: u64 = 5;
 /// Cost on clean discs: zero (first-error path doesn't trigger).
 /// Cost on damaged discs: ~30s × N damage zones; on a 5-zone disc
 /// that's 2.5 min extra. Trade for never wedging the drive.
-const ZONE_ENTRY_COOLDOWN_SECS: u64 = 30;
+pub(crate) const ZONE_ENTRY_COOLDOWN_SECS: u64 = 30;
 /// Cooldown when a long streak of failures suggests the drive is
 /// stuck in a damage zone and needs MORE breathing room than the
 /// standard inter-error pause. Same value as `FAIL_PAUSE_SECS`
@@ -375,9 +400,9 @@ const JUMP_BASE_SECTORS: u64 = 1024;
 // When the BU40N (or similar drives) hits a physical-damage cluster,
 // its firmware can transition into a "wedge" state where it returns
 // HARDWARE_ERROR or ILLEGAL_REQUEST for every subsequent read —
-// often for many LBAs after the actual bad sector. Per CLAUDE.md
-// "Bad-sector handling" rule #2: "Recovery requires eject+reload OR
-// significant cool-down."
+// often for many LBAs after the actual bad sector. Once wedged,
+// recovery requires either a physical eject + reload or a significant
+// cool-down period; hammering the same LBA only deepens the state.
 //
 // Pass 1's pre-fix behavior was to immediately AbortPass on the
 // first HARDWARE_ERROR / ILLEGAL_REQUEST, killing the rip at
@@ -396,10 +421,10 @@ const JUMP_BASE_SECTORS: u64 = 1024;
 /// One-gigabyte jump (1024 MiB) on each wedge. Big enough to clear
 /// almost any single-cluster damage zone we've seen.
 const WEDGE_JUMP_SECTORS: u64 = 524_288;
-/// Cooldown pause after each wedge. Per CLAUDE.md the drive needs
-/// "significant cool-down"; 30 s strikes a balance between giving
-/// the drive a chance to recover and not stalling the rip if the
-/// drive is permanently stuck.
+/// Cooldown pause after each wedge. A wedged drive needs a
+/// significant cool-down to leave fast-fail; 30 s strikes a balance
+/// between giving the drive a chance to recover and not stalling the
+/// rip if the drive is permanently stuck.
 const WEDGE_PAUSE_SECS: u64 = 30;
 /// Bail after this many consecutive wedges with no good read in
 /// between. At 1 GB jumps this lets us scan ~16 GB worth of fully
@@ -463,8 +488,13 @@ pub fn handle_read_error(err: &Error, ctx: &mut ReadCtx) -> ReadAction {
         .unwrap_or(SenseFamily::Other);
 
     // Zone-entry tracking: this is the first error after a clean run
-    // (or the first error of the sweep).
-    if !ctx.in_damage_zone && !ctx.bisecting {
+    // (or the first error of the sweep). Capture the genuine
+    // clean->damaged transition here, BEFORE mutating in_damage_zone,
+    // so the 30s zone-entry cooldown below keys off the real
+    // transition rather than re-deriving it from a counter that the
+    // fast-jump path resets after every jump.
+    let is_zone_entry_transition = !ctx.in_damage_zone && !ctx.bisecting;
+    if is_zone_entry_transition {
         ctx.in_damage_zone = true;
         ctx.zones_entered += 1;
     }
@@ -501,13 +531,20 @@ pub fn handle_read_error(err: &Error, ctx: &mut ReadCtx) -> ReadAction {
     );
 
     if is_wedge_transition {
+        // NOTE: this is the FIRST escalation into the hardware/illegal-request
+        // sense family — NOT a confirmed wedge. Drives frequently recover and keep
+        // reading after one such error (a single bad spot), so calling it a "wedge"
+        // here over-claims (it sent past investigations chasing a drive ghost). A
+        // genuine wedge is PERSISTENT — see the `wedge_skip` / WEDGE_ABORT_THRESHOLD
+        // path below, which only fires after repeated fast-fails with no recovery.
         tracing::warn!(
             target: "freemkv::disc",
-            phase = "wedge_transition",
+            phase = "fastfail_escalation",
             errors_in_zone = ctx.total_errors,
             ms_since_last_success,
             new_family = ?current_family,
-            "drive entered wedge / fast-fail family (was returning recoverable medium errors before this)"
+            "drive escalated into the fast-fail sense family (was returning recoverable medium \
+             errors before this) — often transient; only a PERSISTENT run is a real wedge"
         );
     }
 
@@ -519,11 +556,17 @@ pub fn handle_read_error(err: &Error, ctx: &mut ReadCtx) -> ReadAction {
         return ReadAction::AbortPass;
     }
 
-    // 2. Bridge degradation: NOT_READY with the well-known signature
-    //    (sense_key=2, ASC=0x04, ASCQ=0x3E). Drive's bridge is in a
-    //    semi-stuck state but typically recovers after a long cooldown.
-    //    If we've exhausted our retry budget, fall through to the
-    //    marginal/skip path below.
+    // 2. Bridge degradation: the SCSI status byte is non-standard —
+    //    neither GOOD (0x00), CHECK CONDITION (0x02), nor TRANSPORT
+    //    FAILURE (0xFF). The USB bridge firmware returns these bogus
+    //    status bytes (e.g. 0x04, 0x05) with empty sense data when it
+    //    enters a semi-stuck state preceding a crash. This is keyed on
+    //    the status byte alone, NOT on sense_key/ASC/ASCQ — a real
+    //    NOT_READY 04/3E bad-sector error arrives as CHECK CONDITION
+    //    (0x02) and is handled by the generic NOT_READY branch below.
+    //    The bridge typically recovers after a long cooldown; if we've
+    //    exhausted our retry budget, fall through to the marginal/skip
+    //    path below.
     if err.is_bridge_degradation() && ctx.bridge_degradation_count < BRIDGE_DEGRADATION_MAX_RETRIES
     {
         ctx.bridge_degradation_count += 1;
@@ -569,9 +612,13 @@ pub fn handle_read_error(err: &Error, ctx: &mut ReadCtx) -> ReadAction {
     //    AbortPass after N consecutive wedges with no successful
     //    read in between.
     if sense_key == scsi::SENSE_KEY_HARDWARE_ERROR || sense_key == scsi::SENSE_KEY_ILLEGAL_REQUEST {
-        if !ctx.bisecting {
+        // Count every wedge, including bisect-inner ones. A wedge is a
+        // firmware fast-fail state regardless of whether we're inside a
+        // bisect; if we did NOT count bisect-inner wedges, a drive that
+        // wedges mid-bisect would burn a 30s WEDGE_PAUSE cooldown per
+        // inner sector and never reach WEDGE_ABORT_THRESHOLD from inside
+        // the bisect — ~16 min of cooldown sleeping on a batch=32 bisect.
         ctx.wedge_count += 1;
-        }
         if ctx.wedge_count >= WEDGE_ABORT_THRESHOLD {
             tracing::warn!(
                 target: "freemkv::disc",
@@ -665,8 +712,7 @@ pub fn handle_read_error(err: &Error, ctx: &mut ReadCtx) -> ReadAction {
     // branch for future tuning. Pass N (bisect_on_marginal=true)
     // uses the standard pauses — it's running single-sector retries
     // on already-known-bad LBAs by design.
-    let is_zone_entry =
-        ctx.consecutive_outer_failures == 1 && !ctx.bisecting && !ctx.bisect_on_marginal;
+    let is_zone_entry = is_zone_entry_transition && !ctx.bisecting && !ctx.bisect_on_marginal;
     let pause_secs = if is_zone_entry {
         ZONE_ENTRY_COOLDOWN_SECS
     } else if ctx.consecutive_failures >= CONSECUTIVE_FAIL_LONG_PAUSE_THRESHOLD {
@@ -692,7 +738,7 @@ pub fn handle_read_error(err: &Error, ctx: &mut ReadCtx) -> ReadAction {
     //    Two triggers, evaluated in order:
     //
     //    a. **Fast-entry** — `consecutive_outer_failures >= fast_jump_threshold`.
-    //       Fires on Pass 1 (threshold=4) so we don't spend ~40 min
+    //       Fires on Pass 1 (threshold=1) so we don't spend ~40 min
     //       grinding to fill a 16-block damage window before the
     //       first jump on a damage zone we entered cleanly. Doesn't
     //       fire on Pass N (threshold=u64::MAX).
@@ -1029,6 +1075,43 @@ mod tests {
         }
     }
 
+    #[test]
+    fn pass_1_subsequent_in_zone_errors_skip_long_cooldown() {
+        // Regression: the fast-jump path resets consecutive_outer_failures
+        // to 0 after each jump, so the next in-zone error re-increments it
+        // to 1. Zone-entry must key off the genuine clean->damaged
+        // transition (in_damage_zone), not the counter, otherwise every
+        // error in a damaged region pays the 30 s cooldown.
+        let mut ctx = ReadCtx::for_sweep(32);
+        // First error: genuine zone entry, gets the long cooldown.
+        let first = handle_read_error(&medium_err(), &mut ctx);
+        match first {
+            ReadAction::JumpAhead { pause_secs, .. } => assert_eq!(
+                pause_secs,
+                ZONE_ENTRY_COOLDOWN_SECS + POST_JUMP_EXTRA_PAUSE_SECS
+            ),
+            other => panic!("expected JumpAhead on first error, got {other:?}"),
+        }
+        // We are now still in the damage zone; the jump reset the outer
+        // counter. A second error must NOT re-arm the 30 s cooldown.
+        assert!(ctx.in_damage_zone);
+        let second = handle_read_error(&medium_err(), &mut ctx);
+        let pause = match second {
+            ReadAction::JumpAhead { pause_secs, .. } => pause_secs,
+            ReadAction::SkipBlock { pause_secs } => pause_secs,
+            other => panic!("expected pausing action, got {other:?}"),
+        };
+        assert_ne!(
+            pause,
+            ZONE_ENTRY_COOLDOWN_SECS + POST_JUMP_EXTRA_PAUSE_SECS,
+            "subsequent in-zone error must not pay the 30 s zone-entry cooldown"
+        );
+        assert!(
+            pause <= FAIL_PAUSE_SECS + POST_JUMP_EXTRA_PAUSE_SECS,
+            "subsequent in-zone pause should be the standard fail pause, got {pause}"
+        );
+    }
+
     #[test]
     fn pass_n_pauses_uniformly_on_failed_read() {
         // Pass N (bisect_on_marginal=true) is exempt from the
@@ -1067,6 +1150,66 @@ mod tests {
         );
     }
 
+    #[test]
+    fn jump_multiplier_resets_after_damage_zone_exit() {
+        // A zone that doubles the multiplier must not carry the inflated
+        // value into the next zone — otherwise the next zone's first
+        // jump is up to 64x oversized and skips recoverable data.
+        let mut ctx = ReadCtx::for_sweep(32);
+        // First zone: a few errors push jumps and double the multiplier.
+        for _ in 0..4 {
+            handle_read_error(&medium_err(), &mut ctx);
+        }
+        assert!(
+            ctx.jump_multiplier > 1,
+            "expected the multiplier to inflate inside a damage zone"
+        );
+        // Exit the zone: damage_window_max consecutive good reads.
+        ctx.bisecting = false;
+        for _ in 0..ctx.damage_window_max {
+            ctx.on_success();
+        }
+        assert!(!ctx.in_damage_zone, "zone should have exited");
+        assert_eq!(
+            ctx.jump_multiplier, 1,
+            "jump_multiplier must reset to 1 on zone exit"
+        );
+    }
+
+    #[test]
+    fn bridge_degradation_count_resets_on_success() {
+        // After a good read the bridge recovered; the 15s-cooldown retry
+        // budget must be available again instead of staying saturated
+        // for the whole pass.
+        let mut ctx = ReadCtx::for_patch(1);
+        ctx.bridge_degradation_count = BRIDGE_DEGRADATION_MAX_RETRIES;
+        ctx.on_success();
+        assert_eq!(ctx.bridge_degradation_count, 0);
+    }
+
+    #[test]
+    fn wedge_abort_reachable_during_bisect() {
+        // A drive that wedges mid-bisect must still reach the abort
+        // threshold rather than burning a WEDGE_PAUSE cooldown per inner
+        // sector forever.
+        let mut ctx = ReadCtx::for_patch(32);
+        ctx.bisecting = true;
+        let mut aborted = false;
+        for _ in 0..WEDGE_ABORT_THRESHOLD {
+            if matches!(
+                handle_read_error(&hardware_err(), &mut ctx),
+                ReadAction::AbortPass
+            ) {
+                aborted = true;
+                break;
+            }
+        }
+        assert!(
+            aborted,
+            "wedge abort threshold must be reachable from inside a bisect"
+        );
+    }
+
     #[test]
     fn on_success_resets_failure_counters_and_pushes_window() {
         let mut ctx = ReadCtx::for_sweep(32);
@@ -1080,4 +1223,220 @@ mod tests {
         assert_eq!(ctx.consecutive_failures, 0);
         assert!(*ctx.damage_window.last().unwrap());
     }
+
+    // ----------------------------------------------------------------
+    // Additional hardening: retry-budget boundaries, transport-abort
+    // precedence, and the bounded-jump invariant. These guard against
+    // off-by-one in the retry caps (which would either hammer a wedging
+    // drive or give up a recovery one attempt early) and against an
+    // unbounded jump multiplier skipping the rest of the disc.
+    // ----------------------------------------------------------------
+
+    /// NOT_READY check-condition (status 0x02 so it is NOT classified as
+    /// bridge degradation, which keys off non-standard status bytes).
+    /// sense_key=2 with a generic ASC routes to the NOT_READY retry path.
+    fn not_ready_err() -> Error {
+        Error::DiscRead {
+            sector: 100,
+            status: Some(crate::scsi::SCSI_STATUS_CHECK_CONDITION),
+            sense: Some(ScsiSense {
+                sense_key: scsi::SENSE_KEY_NOT_READY,
+                asc: 0x04,
+                ascq: 0x00,
+            }),
+        }
+    }
+
+    /// Transport failure: SCSI status 0xFF (bridge crash). CLAUDE.md
+    /// "Bad-sector handling": this aborts the copy.
+    fn transport_failure_err() -> Error {
+        Error::DiscRead {
+            sector: 100,
+            status: Some(crate::scsi::SCSI_STATUS_TRANSPORT_FAILURE),
+            sense: None,
+        }
+    }
+
+    /// Bridge degradation: a non-standard status byte (0x04 - neither
+    /// GOOD/CHECK/TRANSPORT) with empty sense, per `Error::is_bridge_degradation`.
+    fn bridge_degradation_err() -> Error {
+        Error::DiscRead {
+            sector: 100,
+            status: Some(0x04),
+            sense: None,
+        }
+    }
+
+    #[test]
+    fn not_ready_retries_capped_at_three_then_falls_through() {
+        // CLAUDE.md "Bad-sector handling" mode 1: NOT READY -> "Pause 3s,
+        // retry up to 3x, then mark NonTrimmed." NOT_READY_MAX_RETRIES=3.
+        // The 1st-3rd NOT_READY must Retry; the 4th must NOT Retry (it
+        // falls through to skip). Pass N (batch=1) so the marginal-bisect
+        // branch is irrelevant.
+        // Mutation that makes this RED: change `ctx.not_ready_retries <
+        // NOT_READY_MAX_RETRIES` to `<=` (retries 4 times) or to `>`
+        // (never retries).
+        let mut ctx = ReadCtx::for_patch(1);
+        for i in 0..NOT_READY_MAX_RETRIES {
+            let a = handle_read_error(&not_ready_err(), &mut ctx);
+            assert!(
+                matches!(a, ReadAction::Retry { .. }),
+                "NOT_READY attempt {i} should Retry, got {a:?}"
+            );
+        }
+        // Budget exhausted: the next NOT_READY must not Retry.
+        let a = handle_read_error(&not_ready_err(), &mut ctx);
+        assert!(
+            !matches!(a, ReadAction::Retry { .. }),
+            "NOT_READY past the retry cap must fall through, got {a:?}"
+        );
+    }
+
+    #[test]
+    fn transport_failure_aborts_even_mid_bisect() {
+        // CLAUDE.md "Bad-sector handling" mode 2: a transport failure
+        // (bridge crash, status 0xFF) aborts the pass so the outer loop
+        // can re-enumerate the bridge. This must hold even while
+        // bisecting and even on Pass N - the wedge-skip/jump paths must
+        // NOT swallow a real transport crash into a JumpAhead.
+        // Mutation that makes this RED: move the transport-failure check
+        // below the HARDWARE/ILLEGAL wedge arm, so a transport failure
+        // that also carried a wedge-family sense would JumpAhead instead.
+        let mut ctx = ReadCtx::for_patch(32);
+        ctx.bisecting = true;
+        assert_eq!(
+            handle_read_error(&transport_failure_err(), &mut ctx),
+            ReadAction::AbortPass
+        );
+        // And on a fresh Pass 1 context, still AbortPass.
+        let mut ctx1 = ReadCtx::for_sweep(32);
+        assert_eq!(
+            handle_read_error(&transport_failure_err(), &mut ctx1),
+            ReadAction::AbortPass
+        );
+    }
+
+    #[test]
+    fn bridge_degradation_retries_to_budget_then_falls_through() {
+        // The bridge-degradation cooldown retry is bounded by
+        // BRIDGE_DEGRADATION_MAX_RETRIES (=5). The first 5 degradation
+        // errors must Retry with the long bridge cooldown; the 6th must
+        // fall through to skip/jump rather than retrying forever and
+        // stalling the pass.
+        // Mutation that makes this RED: change the budget comparison
+        // `ctx.bridge_degradation_count < BRIDGE_DEGRADATION_MAX_RETRIES`
+        // to `<=` (retries 6 times).
+        let mut ctx = ReadCtx::for_patch(1);
+        for i in 0..BRIDGE_DEGRADATION_MAX_RETRIES {
+            let a = handle_read_error(&bridge_degradation_err(), &mut ctx);
+            match a {
+                ReadAction::Retry { pause_secs } => {
+                    assert_eq!(
+                        pause_secs, BRIDGE_DEGRADATION_PAUSE_SECS,
+                        "bridge retry {i} should use the bridge cooldown"
+                    );
+                }
+                other => panic!("bridge degradation attempt {i} should Retry, got {other:?}"),
+            }
+        }
+        let a = handle_read_error(&bridge_degradation_err(), &mut ctx);
+        assert!(
+            !matches!(a, ReadAction::Retry { .. }),
+            "bridge degradation past the retry budget must fall through, got {a:?}"
+        );
+    }
+
+    /// The documented BU40N bad-sector signature: NOT_READY
+    /// (sense_key=2, ASC=0x04, ASCQ=0x3E) delivered as a CHECK CONDITION
+    /// (status 0x02). This is the case the old comment on the bridge
+    /// branch wrongly claimed `is_bridge_degradation` matched.
+    fn not_ready_04_3e_err() -> Error {
+        Error::DiscRead {
+            sector: 100,
+            status: Some(crate::scsi::SCSI_STATUS_CHECK_CONDITION),
+            sense: Some(ScsiSense {
+                sense_key: scsi::SENSE_KEY_NOT_READY,
+                asc: 0x04,
+                ascq: 0x3E,
+            }),
+        }
+    }
+
+    #[test]
+    fn not_ready_04_3e_does_not_take_bridge_branch() {
+        // Regression guard for the misleading-comment fix: the bridge
+        // branch keys on the *status byte* (non-standard, i.e. not
+        // GOOD/CHECK/TRANSPORT), NOT on the NOT_READY 04/3E sense. A real
+        // 04/3E bad-sector error arrives as CHECK CONDITION (0x02), so
+        // `is_bridge_degradation()` must be false for it, and it must
+        // route to the generic NOT_READY retry (3 s pause) rather than
+        // the bridge cooldown (15 s pause).
+        let err = not_ready_04_3e_err();
+        assert!(
+            !err.is_bridge_degradation(),
+            "04/3E arrives as CHECK CONDITION (0x02); it is not bridge degradation"
+        );
+
+        let mut ctx = ReadCtx::for_patch(1);
+        match handle_read_error(&err, &mut ctx) {
+            ReadAction::Retry { pause_secs } => {
+                assert_eq!(
+                    pause_secs, NOT_READY_PAUSE_SECS,
+                    "04/3E must use the generic NOT_READY pause, not the bridge cooldown"
+                );
+                assert_ne!(
+                    pause_secs, BRIDGE_DEGRADATION_PAUSE_SECS,
+                    "04/3E must not take the bridge-degradation branch"
+                );
+                // Confirm it really went through the NOT_READY path.
+                assert_eq!(ctx.not_ready_retries, 1);
+                assert_eq!(ctx.bridge_degradation_count, 0);
+            }
+            other => panic!("04/3E should Retry via the NOT_READY path, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn jump_multiplier_caps_and_jump_distance_stays_bounded() {
+        // CLAUDE.md damage-jump: multiplier doubles per jump but is
+        // capped at MAX_JUMP_MULTIPLIER=64 (the "4 GiB cap"); a single
+        // jump must never be allowed to grow without bound and skip the
+        // rest of the disc. Drive a long single-sector failure streak on
+        // a sweep ctx with a tiny window so window-trigger jumps fire
+        // repeatedly, and verify the multiplier saturates at 64 and the
+        // emitted jump distance equals JUMP_BASE_SECTORS * batch * 64.
+        // Mutation that makes this RED: remove the
+        // `.min(MAX_JUMP_MULTIPLIER)` on the multiplier doubling, or use
+        // wrapping/non-saturating mul -> distance overshoots or panics.
+        const MAX_JUMP_MULTIPLIER: u64 = 64;
+        let batch: u16 = 32;
+        let mut ctx = ReadCtx::for_sweep(batch);
+        // Small window + 0% threshold so every failure can window-trigger
+        // a jump and keep doubling the multiplier toward the cap.
+        ctx.damage_window_max = 2;
+        ctx.damage_threshold_pct = 0;
+        let mut last_jump_sectors = 0u64;
+        for _ in 0..40 {
+            // Reset bisecting flag defensively; these are outer failures.
+            ctx.bisecting = false;
+            if let ReadAction::JumpAhead { sectors, .. } =
+                handle_read_error(&medium_err(), &mut ctx)
+            {
+                last_jump_sectors = sectors;
+            }
+            assert!(
+                ctx.jump_multiplier <= MAX_JUMP_MULTIPLIER,
+                "jump_multiplier {} exceeded the cap {}",
+                ctx.jump_multiplier,
+                MAX_JUMP_MULTIPLIER
+            );
+        }
+        // After saturation, the jump distance is exactly base*batch*cap.
+        let expected = JUMP_BASE_SECTORS * batch as u64 * MAX_JUMP_MULTIPLIER;
+        assert_eq!(
+            last_jump_sectors, expected,
+            "saturated jump distance must equal base*batch*64"
+        );
+    }
 }

src/disc/sweep.rs

@@ -8,15 +8,13 @@
 //! during the post-read work; throughput tops out at the *sum* of
 //! both costs.
 //!
-//! 0.17.11 introduced a bespoke producer/consumer split (the now-
-//! removed `disc/sweep_pipeline.rs`) to overlap the two stages. 0.18
-//! collapses that split — together with the analogous splits patch
-//! and mux need — onto the generic [`crate::io::Pipeline`] +
-//! [`crate::io::Sink`] primitive. This module is the sweep-specific
-//! `Sink` impl; the producer-side state machine (read_error context,
-//! decrypt, set_speed, halt) stays in `Disc::sweep` in `disc/mod.rs`.
+//! 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 (same as 0.17.11):
+//! 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
@@ -25,9 +23,8 @@
 //!   intact in the consumer (write before record), so the on-disk
 //!   invariant "mapfile only marks Finished what the file has
 //!   received" survives a crash mid-pass.
-//! - The BU40N+Initio bridge wedge concern is unchanged: only one
-//!   SCSI command in flight at a time, error-path timing identical,
-//!   no new retry logic.
+//! - 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};
@@ -40,7 +37,7 @@ use super::mapfile::{MapStats, Mapfile, SectorStatus};
 /// Reusable zero buffer for SkipFill / GapFill / BisectBad. 64 KB
 /// matches the existing zero_gap chunk size used by the pre-split
 /// sweep loop.
-const ZERO_CHUNK: usize = 65 * 1024;
+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
@@ -69,6 +66,14 @@ pub(super) enum WorkItem {
     /// tell them apart without parsing a flag.
     GapFill { pos: u64, len: u64 },
 
+    /// Post-read verify downgrade. The producer's `UnitVerifier` found that the
+    /// just-`Finished` clip unit at `[pos, pos+len)` is confidently undecryptable
+    /// (a silent bad read). The consumer re-records the range as `NonTrimmed` so
+    /// the patch pass re-reads it — the ISO bytes (ciphertext) already written by
+    /// the preceding `Good` are left in place for the patch to overwrite. FIFO
+    /// pipe ordering guarantees this arrives AFTER the `Good` that wrote them.
+    MarkBad { 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
@@ -151,63 +156,51 @@ impl Sink<WorkItem> for SweepSink {
             WorkItem::Good { pos, buf } => {
                 // Decrypt is on the producer; consumer assumes plaintext.
                 let len = buf.len() as u64;
-                self.file
-                    .seek(SeekFrom::Start(pos))
-                    .map_err(|e| Error::IoError { source: e })?;
-                self.file
-                    .write_all(&buf)
-                    .map_err(|e| Error::IoError { source: e })?;
-                self.map
-                    .record(pos, len, SectorStatus::Finished)
-                    .map_err(|e| Error::IoError { source: e })?;
+                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))
-                    .map_err(|e| Error::IoError { source: e })?;
-                self.file
-                    .write_all(&buf[..])
-                    .map_err(|e| Error::IoError { source: e })?;
-                self.map
-                    .record(pos, 2048, SectorStatus::Finished)
-                    .map_err(|e| Error::IoError { source: e })?;
+                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))
-                    .map_err(|e| Error::IoError { source: e })?;
-                self.file
-                    .write_all(&self.zero[..2048])
-                    .map_err(|e| Error::IoError { source: e })?;
-                self.map
-                    .record(pos, 2048, SectorStatus::NonTrimmed)
-                    .map_err(|e| Error::IoError { source: e })?;
+                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))
-                    .map_err(|e| Error::IoError { source: e })?;
+                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])
-                        .map_err(|e| Error::IoError { source: e })?;
+                    self.file.write_all(&self.zero[..chunk])?;
                     filled += chunk as u64;
                 }
-                self.map
-                    .record(pos, len, SectorStatus::NonTrimmed)
-                    .map_err(|e| Error::IoError { source: e })?;
+                self.map.record(pos, len, SectorStatus::NonTrimmed)?;
+            }
+            WorkItem::MarkBad { pos, len } => {
+                // Verify downgrade: the ISO bytes are already written by the
+                // preceding Good; only the mapfile status changes so patch
+                // re-reads this range. No file write.
+                self.map.record(pos, len, SectorStatus::NonTrimmed)?;
             }
             WorkItem::StatsRequest => {
                 let stats = self.map.stats();
+                // DAMAGE only — NOT NonTried. NonTried is the unread remainder
+                // ahead of the sweep head, not damage; including it made the live
+                // located drilldown (at-risk movie time + range count) treat the
+                // whole unread disc as confirmed damage, so at sweep start it
+                // showed ~full-movie at-risk and melted to 0 as the sweep
+                // progressed. Matches the one-shot progress path, which already
+                // excludes NonTried.
                 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.
@@ -230,7 +223,7 @@ impl Sink<WorkItem> for SweepSink {
             // Non-regular outputs (/dev/null, pipes) always fail
             // sync_all; that's not a real error.
         }
-        self.map.flush().map_err(|e| Error::IoError { source: e })?;
+        self.map.flush()?;
 
         Ok(ConsumerSummary {
             stats: self.map.stats(),

src/drive/capture.rs

@@ -25,8 +25,14 @@ pub struct DriveCapture {
 /// 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>,
 }
 
@@ -114,3 +120,77 @@ pub fn mask_bytes(data: &[u8]) -> Vec<u8> {
         })
         .collect()
 }
+
+#[cfg(test)]
+mod tests {
+    //! Privacy-masking + capture-orchestration tests.
+    //!
+    //! `mask_string` / `mask_bytes` redact identifying characters before
+    //! a drive capture leaves the machine: every ASCII letter → 'A',
+    //! every ASCII digit → '0', everything else (punctuation, spaces,
+    //! control bytes, non-ASCII) is preserved verbatim so structural
+    //! framing (offsets, separators) survives for diffing.
+    use super::*;
+
+    #[test]
+    fn mask_string_letters_become_a_digits_become_zero() {
+        // Mixed case letters all collapse to 'A'; digits to '0'.
+        assert_eq!(mask_string("HL-DT-ST"), "AA-AA-AA");
+        assert_eq!(mask_string("BU40N"), "AA00A");
+    }
+
+    #[test]
+    fn mask_string_preserves_non_alnum_punctuation_and_space() {
+        // Separators and spaces must be preserved so the masked output
+        // keeps the same shape as the original (the whole point of a
+        // structure-preserving redaction).
+        assert_eq!(mask_string("1.04"), "0.00");
+        assert_eq!(mask_string("a b-c.d_e"), "A A-A.A_A");
+    }
+
+    #[test]
+    fn mask_string_preserves_non_ascii_chars() {
+        // is_ascii_alphabetic/is_ascii_digit are false for non-ASCII, so
+        // multibyte chars pass through unchanged (no mojibake, no panic).
+        // 'c','a','f' are ASCII letters → 'A'; 'é' is non-ASCII →
+        // preserved; '9' → '0'.
+        assert_eq!(mask_string("café9"), "AAAé0");
+    }
+
+    #[test]
+    fn mask_bytes_matches_string_masking_for_ascii() {
+        // mask_bytes is the byte-wise analogue: letters→b'A', digits→b'0'.
+        assert_eq!(mask_bytes(b"HL-DT-ST"), b"AA-AA-AA".to_vec());
+        assert_eq!(mask_bytes(b"1.04"), b"0.00".to_vec());
+    }
+
+    #[test]
+    fn mask_bytes_preserves_non_alnum_and_high_bytes() {
+        // Control bytes (0x00), high bytes (0xFF), and punctuation are
+        // not ASCII alnum and must survive verbatim — INQUIRY payloads
+        // are space-padded binary and the framing must be diffable.
+        let input = [0x00u8, b'A', 0x20, b'7', 0xFF, b'-'];
+        assert_eq!(mask_bytes(&input), vec![0x00, b'A', 0x20, b'0', 0xFF, b'-']);
+    }
+
+    #[test]
+    fn feature_table_has_no_duplicate_codes() {
+        // capture_drive_data iterates FEATURES once per code; a duplicate
+        // code would silently capture the same feature twice (and bloat
+        // the report). Each MMC-6 feature code must be unique.
+        let mut seen = std::collections::HashSet::new();
+        for &(code, _name) in FEATURES {
+            assert!(seen.insert(code), "duplicate feature code {code:#06x}");
+        }
+    }
+
+    #[test]
+    fn feature_table_includes_aacs_010d() {
+        // AACS (0x010D) is the feature that gates UHD decryption capture;
+        // it must be in the table or AACS drives capture incompletely.
+        assert!(
+            FEATURES.iter().any(|&(c, _)| c == 0x010D),
+            "AACS feature 0x010D must be captured"
+        );
+    }
+}

src/drive/linux.rs

@@ -1,18 +1,33 @@
 //! 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 i in 0..16 {
-        let path = format!("/dev/sg{i}");
+    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) == 0x05 {
+                if !id.raw_inquiry.is_empty()
+                    && (id.raw_inquiry[0] & 0x1F) == SCSI_PERIPHERAL_TYPE_OPTICAL
+                {
                     drives.push((path, id));
                 }
             }
@@ -21,41 +36,78 @@ pub fn find_drives() -> Vec<(String, DriveId)> {
     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, Option<String>)> {
+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(), None));
+        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() {
-            if sg_id.vendor_id == sr_id.vendor_id
+            // 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
             {
-                let warning =
-                    format!("{path} is a block device (sr) — using {sg_path} (sg) for raw access");
-                return Ok((sg_path, Some(warning)));
+                return Ok((sg_path, DeviceResolution::SrToSg));
             }
         }
-        return Ok((
-            path.to_string(),
-            Some(format!(
-                "{path} is a block device (sr) — no matching sg device found"
-            )),
-        ));
+        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(), None))
+    Ok((path.to_string(), DeviceResolution::Direct))
 }

src/drive/macos.rs

@@ -4,9 +4,20 @@
 //! 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();
@@ -15,9 +26,13 @@ pub fn find_drives() -> Vec<(String, DriveId)> {
         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;
             }
@@ -26,20 +41,15 @@ pub fn find_drives() -> Vec<(String, DriveId)> {
     drives
 }
 
-pub fn resolve_device(path: &str) -> Result<(String, Option<String>)> {
-    // Accept /dev/diskN or /dev/rdiskN paths as-is
-    if path.contains("/disk") || path.contains("/rdisk") {
+/// 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(),
         });
     }
-        return Ok((path.to_string(), None));
-    }
-    if !std::path::Path::new(path).exists() {
-        return Err(Error::DeviceNotFound {
-            path: path.to_string(),
-        });
-    }
-    Ok((path.to_string(), None))
+    Ok((path.to_string(), DeviceResolution::Direct))
 }

src/drive/windows.rs

@@ -1,9 +1,18 @@
 //! 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();
 
@@ -12,7 +21,9 @@ pub fn find_drives() -> Vec<(String, DriveId)> {
         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) == 0x05 {
+                if !id.raw_inquiry.is_empty()
+                    && (id.raw_inquiry[0] & 0x1F) == SCSI_PERIPHERAL_TYPE_OPTICAL
+                {
                     drives.push((path, id));
                 }
             }
@@ -25,8 +36,12 @@ pub fn find_drives() -> Vec<(String, DriveId)> {
             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) == 0x05 {
-                        drives.push((path, id));
+                    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));
                     }
                 }
             }
@@ -36,8 +51,11 @@ pub fn find_drives() -> Vec<(String, DriveId)> {
     drives
 }
 
-pub fn resolve_device(path: &str) -> Result<(String, Option<String>)> {
-    Ok((normalize_path(path), None))
+/// 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.
@@ -55,9 +73,6 @@ fn normalize_path(path: &str) -> String {
     if trimmed.len() == 2 && trimmed.as_bytes()[1] == b':' {
         return format!("\\\\.\\{}", trimmed);
     }
-    if path.to_lowercase().starts_with("cdrom") {
-        return format!("\\\\.\\{}", path);
-    }
     format!("\\\\.\\{}", path)
 }
 

src/drm/mod.rs

@@ -1,287 +0,0 @@
-//! 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`] | Content cert + MKB records `0x82` / `0x83`   |
-//!
-//! 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).
-//!
-//! The AACS 2.1 arm is wired but disabled. The dispatcher leaves
-//! [`crate::aacs::resolve_keys_v21`] reachable as a library entry point
-//! for fixture-driven validation, but production consumers go through
-//! [`DrmScheme::load`], which short-circuits V21 to `None` until the
-//! Variant chain has a real Variant-scheme disc to validate against.
-
-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.) or when
-    /// the scheme itself is gated off (see the inline comment on the
-    /// `Aacs21` arm).
-    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),
-            DrmScheme::Aacs20 => ctx
-                .aacs
-                .as_ref()
-                .and_then(aacs::resolve_keys_v2)
-                .map(ResolvedScheme::Aacs),
-            // AACS 2.1 derivation is wired but disabled. KCD validation
-            // against a Variant-scheme disc is pending. To enable,
-            // uncomment the line below.
-            // DrmScheme::Aacs21 => ctx
-            //     .aacs
-            //     .as_ref()
-            //     .and_then(aacs::resolve_keys_v21)
-            //     .map(ResolvedScheme::Aacs),
-            DrmScheme::Aacs21 => None,
-        }
-    }
-}
-
-#[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_returns_none() {
-        // The Aacs21 dispatch arm is commented out; load() must
-        // return None until KCD validation lands.
-        let uk_ro = vec![0u8; 256];
-        let vid = [0u8; 16];
-        let keydb = aacs::KeyDb::empty();
-        let ctx_aacs = aacs::ResolveContext {
-            unit_key_ro: &uk_ro,
-            content_cert: None,
-            volume_id: &vid,
-            keydb: &keydb,
-            mkb: None,
-        };
-        let mut ctx = DrmContext {
-            aacs: Some(ctx_aacs),
-            css: None,
-        };
-        assert!(DrmScheme::Aacs21.load(&mut ctx).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 mkb = mkb_with_variant();
-        let ctx = aacs::ResolveContext {
-            unit_key_ro: &uk_ro,
-            content_cert: None,
-            volume_id: &vid,
-            keydb: &keydb,
-            mkb: Some(&mkb),
-        };
-        // Just confirm the symbol is callable; we don't assert on the
-        // result.
-        let _ = aacs::resolve_keys_v21(&ctx);
-    }
-}

src/dvdnav/mod.rs

@@ -0,0 +1,49 @@
+//! DVD-Video navigation — read-only resolver for the **main-feature start
+//! point** (issue #40). Mirrors what a DVD player's nav VM resolves: First-Play
+//! → menu "Play" → title dispatch → the first cell of the feature, so the rip
+//! starts at the movie rather than at raw cell 0 (e.g. skipping a leading
+//! logo/warning segment when the disc's own navigation does).
+//!
+//! Byte layout follows the DVD-Video specification (VMGI/VTSI headers,
+//! PGC/cell tables, PCI/HLI button packets); the VM command decoder is
+//! verified against libdvdnav's decoder.
+//!
+//! Current contents: [`vmcmd`] — the VM command decoder (proven against the
+//! SOTL/Greenland test discs). The IFO/PCI parsing and the navigation executor
+//! that resolves the start cell build on top of this.
+
+pub mod vmcmd;
+
+use crate::sector::SectorSource;
+
+/// Resolve the feature title's **true start cell** (0-based index into the
+/// title PGC's cell list) by following the disc's own navigation — First-Play →
+/// menu "Play" → title dispatch — the way a player reaches the movie. This is
+/// what lets the rip begin at the feature instead of at raw cell 0 when the
+/// disc's nav enters the title past a leading logo/warning segment (e.g. a
+/// disc whose "Play" resolves to a later cell than cell 0).
+///
+/// Returns `None` when navigation cannot be resolved, so the caller falls back
+/// to the structural leading-cell filter (today's behaviour, ≈ cell 0 / 0:00).
+///
+/// TODO(#40): the IFO/PCI parsing + nav executor (built on [`vmcmd`]) land
+/// incrementally. Until the executor is complete this returns `None`, so wiring
+/// it in is behaviour-neutral; improvements to the resolver take effect here
+/// without touching the call site.
+pub fn resolve_feature_start(
+    reader: &mut dyn SectorSource,
+    udf: &crate::udf::UdfFs,
+    vtsn: u16,
+    vts_ttn: u16,
+) -> Option<usize> {
+    // `reader`/`udf` are the seam inputs the nav executor will consume to read
+    // VIDEO_TS.IFO + the VTS IFOs/menu VOBs. Reserved until that lands.
+    let _ = (reader, udf);
+    tracing::trace!(
+        target: "freemkv::dvdnav",
+        vtsn,
+        vts_ttn,
+        "nav start-cell resolver: unresolved — caller falls back to leading-cell filter"
+    );
+    None
+}

src/dvdnav/vmcmd.rs

@@ -0,0 +1,408 @@
+//! DVD-Video VM command decoder.
+//!
+//! An 8-byte navigation command as found in PGC command tables (pre/post/cell)
+//! and PCI button info. Decoded per the DVD-Video VM instruction set and
+//! verified against libdvdnav's command decoder.
+//!
+//! Bit model: the 8 bytes are a big-endian 64-bit word. `byte0` bits 7-5 are the
+//! command **type**; for type 1, `byte0` bit 4 selects Link (0) vs Jump (1), and
+//! `byte1` bits 3-0 are the sub-command. Compare predicates live in `byte1`
+//! bits 6-4 with the operands in bytes 2-5.
+//!
+//! This module is pure decode + a register model — no I/O, no English (numeric
+//! semantics only), matching libfreemkv conventions. The navigation *executor*
+//! and IFO/PCI parsing build on top of this.
+
+/// A decoded navigation instruction. Only the variants freemkv's start-point
+/// resolver needs are modelled explicitly; everything else is [`Instr::Other`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Instr {
+    Nop,
+    /// Stop executing the current command list (resume cell playback).
+    Break,
+    /// Goto command line within the same list (1-based).
+    Goto {
+        line: u8,
+    },
+    /// Leave the current domain.
+    Exit,
+    /// Jump to a VMG title (1-based TT_SRPT index).
+    JumpTt {
+        ttn: u8,
+    },
+    /// Jump to a title within the current VTS (1-based VTS title index).
+    JumpVtsTt {
+        ttn: u8,
+    },
+    /// Jump to a part-of-title (chapter) within a VTS title.
+    JumpVtsPtt {
+        ttn: u8,
+        pttn: u16,
+    },
+    /// Jump to the First-Play PGC.
+    JumpSsFp,
+    /// Jump to a Video-Manager menu (`menu` = menu id).
+    JumpSsVmgm {
+        menu: u8,
+    },
+    /// Jump to a Video-Title-Set menu.
+    JumpSsVtsm {
+        vts: u8,
+        ttn: u8,
+        menu: u8,
+    },
+    /// Jump to a specific VMGM menu PGC.
+    JumpSsVmgmPgc {
+        pgcn: u16,
+    },
+    /// Call a sub-domain (raw retained; resume handled by the executor).
+    CallSs {
+        sub: u8,
+    },
+    /// Link to a PGC number within the current domain.
+    LinkPgcn {
+        pgcn: u16,
+    },
+    /// Link to a part-of-title within the current PGC's title.
+    LinkPttn {
+        pttn: u16,
+    },
+    /// Link to a program number within the current PGC (1-based).
+    LinkPgn {
+        pgn: u8,
+    },
+    /// Link to a cell number within the current PGC (1-based).
+    LinkCn {
+        cn: u8,
+    },
+    /// A link "subset" op (LinkTopCell/NextPG/RSM/…); `sub` is the raw code.
+    LinkSub {
+        sub: u8,
+    },
+    /// Set a GPRM. `op` is the set-op code (1=mov, 3=add, …); value is immediate
+    /// (`imm`) when `immediate`, else the contents of register `src`.
+    SetGprm {
+        reg: u8,
+        op: u8,
+        immediate: bool,
+        imm: u16,
+        src: u8,
+    },
+    /// Set a system parameter / unmodelled set — executor may ignore.
+    SetSystem,
+    /// Anything not individually modelled (kept as raw bytes).
+    Other([u8; 8]),
+}
+
+/// A compare predicate carried by a command (`byte1` bits 6-4). `None` = always.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Compare {
+    /// Compare op: 1=&,2===,3=!=,4=>=,5=>,6=<=,7=<.
+    pub op: u8,
+    /// Left register index (GPRM 0-15, SPRM 128+).
+    pub lhs_reg: u8,
+    /// Right side: immediate when `immediate`, else register `rhs_reg`.
+    pub immediate: bool,
+    pub imm: u16,
+    pub rhs_reg: u8,
+}
+
+/// A fully decoded command: its predicate (if any) and the instruction.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Command {
+    pub compare: Option<Compare>,
+    pub instr: Instr,
+}
+
+// Command types — `byte0` bits 7-5.
+const TYPE_SPECIAL: u8 = 0;
+const TYPE_LINK_JUMP: u8 = 1;
+const TYPE_SET_SYSTEM: u8 = 2;
+const TYPE_SET_GPRM: u8 = 3;
+
+// Special (type 0) sub-commands — `byte1` bits 3-0.
+const SP_GOTO: u8 = 1;
+const SP_BREAK: u8 = 2;
+
+// Jump/Call (type 1, direct=1) sub-commands.
+const JP_EXIT: u8 = 1;
+const JP_JUMP_TT: u8 = 2;
+const JP_JUMP_VTS_TT: u8 = 3;
+const JP_JUMP_VTS_PTT: u8 = 5;
+const JP_JUMP_SS: u8 = 6;
+const JP_CALL_SS: u8 = 8;
+
+// Link (type 1, direct=0) sub-commands. NOTE: sub-op 0 is NOP/no-link and 1 is
+// the LinkSub form (libdvdnav `decoder.c` `eval_link_instruction`).
+const LK_SUB: u8 = 1;
+const LK_PGCN: u8 = 4;
+const LK_PTTN: u8 = 5;
+const LK_PGN: u8 = 6;
+const LK_CN: u8 = 7;
+
+// JumpSS sub-domain selector — `byte5` bits 7-6.
+const SS_FP: u8 = 0;
+const SS_VMGM_MENU: u8 = 1;
+const SS_VTSM: u8 = 2;
+
+// Operand field widths (spec-defined bit counts).
+const MASK_TTN: u8 = 0x7F; // 7-bit title number
+const MASK_PGN: u8 = 0x7F; // 7-bit program number
+const MASK_LINKOP: u8 = 0x1F; // 5-bit link sub-op
+const MASK_REG: u8 = 0x0F; // 4-bit GPRM index
+const MASK_MENU: u8 = 0x0F; // 4-bit menu id
+const MASK_PTTN: u16 = 0x03FF; // 10-bit part-of-title
+const MASK_PGCN: u16 = 0x7FFF; // 15-bit PGC number
+
+#[inline]
+fn be16(b: &[u8; 8], o: usize) -> u16 {
+    ((b[o] as u16) << 8) | b[o + 1] as u16
+}
+
+// Compare-operand layouts ("if_version"s) per libdvdnav `decoder.c`. The op
+// nibble is always `byte1` bits 6-4; the immediate flag is `byte1` bit 7. The
+// operand *offsets* differ by command family.
+//
+// v1 (special + link): lhs reg = b[3]; rhs imm = bytes4-5 / rhs reg = b[4].
+// v2 (jump + system-set): lhs reg = b[6]; rhs reg = b[7] (registers only).
+// v3 (set-GPRM): lhs reg = b[2]; rhs imm = bytes6-7 / rhs reg = b[6].
+fn if_v1(b: &[u8; 8]) -> Option<Compare> {
+    let op = (b[1] >> 4) & 7;
+    (op != 0).then(|| Compare {
+        op,
+        lhs_reg: b[3],
+        immediate: b[1] >> 7 != 0,
+        imm: be16(b, 4),
+        rhs_reg: b[4],
+    })
+}
+fn if_v2(b: &[u8; 8]) -> Option<Compare> {
+    let op = (b[1] >> 4) & 7;
+    (op != 0).then(|| Compare {
+        op,
+        lhs_reg: b[6],
+        immediate: false,
+        imm: 0,
+        rhs_reg: b[7],
+    })
+}
+fn if_v3(b: &[u8; 8]) -> Option<Compare> {
+    let op = (b[1] >> 4) & 7;
+    (op != 0).then(|| Compare {
+        op,
+        lhs_reg: b[2],
+        immediate: b[1] >> 7 != 0,
+        imm: be16(b, 6),
+        rhs_reg: b[6],
+    })
+}
+
+/// Decode an 8-byte VM command.
+pub fn decode(b: &[u8; 8]) -> Command {
+    let typ = b[0] >> 5;
+    let direct = (b[0] >> 4) & 1;
+    let setop = b[0] & 0x0F;
+    let cmd = b[1] & 0x0F;
+
+    // Compare predicate, with the operand layout for this command family
+    // (libdvdnav `decoder.c` `vm_eval_command` type dispatch).
+    let compare = match (typ, direct) {
+        (TYPE_SPECIAL, _) => if_v1(b),
+        (TYPE_LINK_JUMP, 1) => if_v2(b), // jump
+        (TYPE_LINK_JUMP, 0) => if_v1(b), // link
+        (TYPE_SET_SYSTEM, _) => if_v2(b),
+        (TYPE_SET_GPRM, _) => if_v3(b),
+        _ => None, // 4/5/6 compound — not needed by the resolver
+    };
+
+    // JumpSS sub-domain selector lives in byte5 bits 7-6.
+    let ss_sel = b[5] >> 6;
+
+    let instr = match typ {
+        TYPE_LINK_JUMP if direct == 1 => match cmd {
+            JP_EXIT => Instr::Exit,
+            JP_JUMP_TT => Instr::JumpTt {
+                ttn: b[5] & MASK_TTN,
+            },
+            JP_JUMP_VTS_TT => Instr::JumpVtsTt {
+                ttn: b[5] & MASK_TTN,
+            },
+            JP_JUMP_VTS_PTT => Instr::JumpVtsPtt {
+                ttn: b[5] & MASK_TTN,
+                pttn: be16(b, 2) & MASK_PTTN,
+            },
+            JP_JUMP_SS => match ss_sel {
+                SS_FP => Instr::JumpSsFp,
+                SS_VMGM_MENU => Instr::JumpSsVmgm {
+                    menu: b[5] & MASK_MENU,
+                },
+                SS_VTSM => Instr::JumpSsVtsm {
+                    vts: b[4],
+                    ttn: b[3],
+                    menu: b[5] & MASK_MENU,
+                },
+                _ => Instr::JumpSsVmgmPgc {
+                    pgcn: be16(b, 2) & MASK_PGCN,
+                },
+            },
+            JP_CALL_SS => Instr::CallSs { sub: ss_sel },
+            _ => Instr::Nop,
+        },
+        TYPE_LINK_JUMP => match cmd {
+            // direct == 0 (link). sub-op 0 = NOP/no-link.
+            LK_SUB => Instr::LinkSub {
+                sub: b[7] & MASK_LINKOP,
+            },
+            LK_PGCN => Instr::LinkPgcn {
+                pgcn: be16(b, 6) & MASK_PGCN,
+            },
+            LK_PTTN => Instr::LinkPttn {
+                pttn: be16(b, 6) & MASK_PTTN,
+            },
+            LK_PGN => Instr::LinkPgn {
+                pgn: b[7] & MASK_PGN,
+            },
+            LK_CN => Instr::LinkCn { cn: b[7] },
+            _ => Instr::Nop,
+        },
+        TYPE_SPECIAL => match cmd {
+            SP_GOTO => Instr::Goto { line: b[7] },
+            SP_BREAK => Instr::Break,
+            _ => Instr::Nop,
+        },
+        TYPE_SET_GPRM => Instr::SetGprm {
+            reg: b[3] & MASK_REG,
+            op: setop,
+            immediate: direct != 0,
+            imm: be16(b, 4),
+            src: b[5],
+        },
+        TYPE_SET_SYSTEM => Instr::SetSystem,
+        _ => Instr::Other(*b),
+    };
+
+    Command { compare, instr }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn h(s: &str) -> [u8; 8] {
+        let v: Vec<u8> = (0..8)
+            .map(|i| u8::from_str_radix(&s[i * 2..i * 2 + 2], 16).unwrap())
+            .collect();
+        v.try_into().unwrap()
+    }
+
+    // KATs taken from the real SOTL / Greenland discs (decoded in the PoC).
+    #[test]
+    fn greenland_first_play_is_jumptt_1() {
+        let c = decode(&h("3002000000010000"));
+        assert_eq!(c.instr, Instr::JumpTt { ttn: 1 });
+        assert!(c.compare.is_none());
+    }
+
+    #[test]
+    fn sotl_first_play_is_jumpss_vtsm_root() {
+        // 30 06 ... byte5=0x83 -> sub 2 (VTSM), vts=byte4=1, menu=byte5&0xF=3 (root)
+        let c = decode(&h("3006000101830000"));
+        assert_eq!(
+            c.instr,
+            Instr::JumpSsVtsm {
+                vts: 1,
+                ttn: 1,
+                menu: 3
+            }
+        );
+    }
+
+    #[test]
+    fn sotl_title_dispatch_is_conditional_linkpgn_2() {
+        // 20 a6 ... CmpLink: if GPRM0 == 2 -> LinkPGN 2  (cell 2 = the 5:02 start)
+        let c = decode(&h("20a6000000020002"));
+        assert_eq!(c.instr, Instr::LinkPgn { pgn: 2 });
+        let cmp = c.compare.expect("conditional");
+        assert_eq!(cmp.op, 2); // ==
+        assert_eq!(cmp.lhs_reg, 0); // GPRM0
+        assert!(cmp.immediate);
+        assert_eq!(cmp.imm, 2);
+    }
+
+    #[test]
+    fn sotl_root_button_is_linkpgcn_37() {
+        assert_eq!(
+            decode(&h("2004000000000025")).instr,
+            Instr::LinkPgcn { pgcn: 37 }
+        );
+    }
+
+    #[test]
+    fn greenland_scene_button_is_linkpgn() {
+        assert_eq!(
+            decode(&h("2006000000001401")).instr,
+            Instr::LinkPgn { pgn: 1 }
+        );
+    }
+
+    #[test]
+    fn jumpvts_ptt_decodes_ttn_and_pttn() {
+        // synthetic: 30 05 | ptt(bytes2-3)=0x0002 | ttn(byte5)=1
+        let c = decode(&h("3005000200010000"));
+        assert_eq!(c.instr, Instr::JumpVtsPtt { ttn: 1, pttn: 2 });
+    }
+
+    #[test]
+    fn setgprm_immediate_mov() {
+        // SOTL First-Play pre[0]: 71 00 | reg=byte3=6 | imm(bytes4-5)=0x03e8 -> g6 = 1000
+        match decode(&h("7100000603e80000")).instr {
+            Instr::SetGprm {
+                reg,
+                op,
+                immediate,
+                imm,
+                ..
+            } => {
+                assert_eq!(reg, 6);
+                assert_eq!(op, 1); // mov
+                assert!(immediate);
+                assert_eq!(imm, 1000);
+            }
+            other => panic!("expected SetGprm, got {other:?}"),
+        }
+    }
+
+    // Regression for the libdvdnav cross-check: link sub-op 0 = NOP, 1 = LinkSub.
+    #[test]
+    fn link_subop_zero_is_nop_one_is_linksub() {
+        assert_eq!(decode(&h("2000000000000000")).instr, Instr::Nop);
+        assert_eq!(
+            decode(&h("2001000000000010")).instr,
+            Instr::LinkSub { sub: 0x10 }
+        );
+    }
+
+    // if_version_1 register compare: rhs register is byte4 (not byte5).
+    #[test]
+    fn link_register_compare_rhs_is_byte4() {
+        // 20 26: link, cmp=EQ(2), dircmp=0(register) ; cmd=6 LinkPGN
+        let c = decode(&h("2026000304000002"));
+        assert_eq!(c.instr, Instr::LinkPgn { pgn: 2 });
+        let cmp = c.compare.expect("conditional");
+        assert!(!cmp.immediate);
+        assert_eq!(cmp.lhs_reg, 3);
+        assert_eq!(cmp.rhs_reg, 4);
+    }
+
+    // if_version_2 jump compare: both operands are registers in byte6 / byte7.
+    #[test]
+    fn jump_compare_uses_bytes6_and_7() {
+        // 30 22: jump, cmp=EQ(2) ; cmd=2 JumpTT ttn=byte5=5
+        let c = decode(&h("3022000000050607"));
+        assert_eq!(c.instr, Instr::JumpTt { ttn: 5 });
+        let cmp = c.compare.expect("conditional");
+        assert!(!cmp.immediate);
+        assert_eq!(cmp.lhs_reg, 6);
+        assert_eq!(cmp.rhs_reg, 7);
+    }
+}

src/event.rs

@@ -8,11 +8,17 @@
 //! disc.rip(&mut session, 0, output, |event| {
 //!     match event.kind {
 //!         EventKind::BytesRead { bytes, total } => update_progress(bytes, total),
-//!         EventKind::ReadError { sector, .. } => log_error(sector),
+//!         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;
 
@@ -116,3 +122,29 @@ pub enum BatchSizeReason {
 
 /// A no-op event handler. Ignores all events.
 pub fn ignore(_event: Event) {}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// BatchSizeReason::Shrunk != BatchSizeReason::Probed.
+    /// These two variants carry distinct meanings (error vs. recovery); they
+    /// must not compare as equal.
+    /// Mutation: deriving PartialEq without proper variant discrimination
+    ///           could make two distinct variants equal.
+    #[test]
+    fn batch_size_reason_variants_are_not_equal() {
+        assert_ne!(BatchSizeReason::Shrunk, BatchSizeReason::Probed);
+    }
+
+    /// BatchSizeReason is Clone + Copy: cloning does not move the original.
+    /// This is required because EventKind::BatchSizeChanged embeds it by value.
+    /// Mutation: removing Copy would require the caller to clone explicitly;
+    ///           code that passes reason by value would fail to compile.
+    #[test]
+    fn batch_size_reason_is_copy() {
+        let r = BatchSizeReason::Shrunk;
+        let _r2 = r; // copy, not move
+        let _r3 = r; // r still usable after copy
+    }
+}

src/halt.rs

@@ -34,11 +34,9 @@ impl Halt {
         Self(Arc::new(AtomicBool::new(false)))
     }
 
-    /// Wrap an existing `Arc<AtomicBool>` as a `Halt`. Useful as a
-    /// bridge during the 0.18 deprecation window: callers that already
-    /// hold an `Arc<AtomicBool>` (e.g. `Drive::halt_flag()`, the
-    /// deprecated `DiscStream::set_halt`) can adopt the new token API
-    /// without changing the underlying flag.
+    /// 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.
@@ -46,10 +44,9 @@ impl Halt {
         Self(flag)
     }
 
-    /// Borrow the underlying `Arc<AtomicBool>`. Used at boundaries with
-    /// pre-`Halt` APIs that still take an `Arc<AtomicBool>` directly
-    /// (`CopyOptions::halt`, the deprecated `DiscStream::set_halt`).
-    /// Round 3 deletes those boundaries and this accessor with them.
+    /// 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
     }
@@ -177,4 +174,18 @@ mod tests {
         arc.store(true, Ordering::Relaxed);
         assert!(halt.is_cancelled());
     }
+
+    // ── New comprehensive tests ────────────────────────────────────────────────
+
+    /// POLL_INTERVAL is 250ms — a specific value that the multi-thread halt
+    /// loops depend on for responsiveness guarantees.
+    /// Mutation: setting POLL_INTERVAL to 5s makes stop requests take 5s to notice.
+    #[test]
+    fn poll_interval_is_250ms() {
+        assert_eq!(
+            POLL_INTERVAL,
+            std::time::Duration::from_millis(250),
+            "POLL_INTERVAL must be 250ms for the guaranteed ~quarter-second cancel latency"
+        );
+    }
 }

src/hex.rs

@@ -0,0 +1,106 @@
+//! The single hex → bytes parser for the whole workspace.
+//!
+//! Key material arrives as hex from three third-party sources — the keydb, an
+//! online key service, and the mapfile's `# freemkv-vid:` comment — and each
+//! used to parse it slightly differently (one stripped `0x`/`0X`, one stripped
+//! nothing, one stripped `0x` only). A key written with a prefix one parser
+//! didn't expect was silently dropped → "can't decrypt" with no error. This is
+//! the one parser they all call, so the prefix/case/validation rules live in
+//! exactly one place.
+//!
+//! Operates on BYTES, not `&str` char indices: the inputs are untrusted, so a
+//! multi-byte UTF-8 scalar must reject as malformed, never panic on a
+//! mid-codepoint slice.
+
+/// Parse a hex string into bytes. Accepts an optional `0x`/`0X` prefix
+/// (case-insensitive), then requires an even run of ASCII hex digits. Any
+/// non-hex byte, or an odd length, yields `None`.
+pub fn parse_hex_bytes(s: &str) -> Option<Vec<u8>> {
+    let body = strip_prefix(s.trim());
+    let bytes = body.as_bytes();
+    // Empty → empty Vec (a legitimately-empty variable-length field); odd length
+    // is malformed. (`parse_hex_fixed` enforces a concrete length separately.)
+    if bytes.len() % 2 != 0 {
+        return None;
+    }
+    let mut out = Vec::with_capacity(bytes.len() / 2);
+    for pair in bytes.chunks_exact(2) {
+        out.push(byte(pair[0], pair[1])?);
+    }
+    Some(out)
+}
+
+/// Parse a hex string into a fixed `[u8; N]`. Accepts an optional `0x`/`0X`
+/// prefix; requires EXACTLY `2*N` ASCII hex digits after it. `None` on any
+/// non-hex byte or a length mismatch.
+pub fn parse_hex_fixed<const N: usize>(s: &str) -> Option<[u8; N]> {
+    let body = strip_prefix(s.trim());
+    let bytes = body.as_bytes();
+    if bytes.len() != 2 * N {
+        return None;
+    }
+    let mut out = [0u8; N];
+    for (i, slot) in out.iter_mut().enumerate() {
+        *slot = byte(bytes[2 * i], bytes[2 * i + 1])?;
+    }
+    Some(out)
+}
+
+/// Strip a single leading `0x` / `0X` if present (case-insensitive).
+fn strip_prefix(s: &str) -> &str {
+    s.strip_prefix("0x")
+        .or_else(|| s.strip_prefix("0X"))
+        .unwrap_or(s)
+}
+
+/// Combine two ASCII hex-digit bytes into one byte. `as char` is intentional:
+/// for a non-ASCII byte it produces a Latin-1 scalar that `to_digit(16)` then
+/// rejects — so non-hex (incl. `+`/`-` sign chars) and multi-byte input fail
+/// cleanly rather than slipping through `from_str_radix`'s sign handling.
+fn byte(hi: u8, lo: u8) -> Option<u8> {
+    let hi = (hi as char).to_digit(16)?;
+    let lo = (lo as char).to_digit(16)?;
+    Some((hi * 16 + lo) as u8)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn fixed_accepts_0x_0x_and_bare_same_result() {
+        let want = [0x00, 0x11, 0xab, 0xCD, 0xef, 0x42, 0x99, 0x00];
+        let bare = "0011abcdef429900";
+        assert_eq!(parse_hex_fixed::<8>(bare), Some(want));
+        assert_eq!(parse_hex_fixed::<8>(&format!("0x{bare}")), Some(want));
+        // The case that used to be dropped by one parser but not another.
+        assert_eq!(parse_hex_fixed::<8>(&format!("0X{bare}")), Some(want));
+        assert_eq!(parse_hex_fixed::<8>(&format!("  0X{bare}  ")), Some(want));
+    }
+
+    #[test]
+    fn fixed_rejects_wrong_length_and_non_hex_and_signs() {
+        assert_eq!(parse_hex_fixed::<16>("00"), None); // too short
+        assert_eq!(parse_hex_fixed::<2>("00112233"), None); // too long
+        assert_eq!(parse_hex_fixed::<2>("zz11"), None); // non-hex
+        assert_eq!(parse_hex_fixed::<2>("+5-A"), None); // sign chars
+    }
+
+    #[test]
+    fn does_not_panic_on_multibyte_of_exact_byte_length() {
+        // "中" is 3 bytes; + 29 'a' = 32 bytes → would mis-slice a &str-indexed
+        // parser. Must reject, not panic.
+        let s = "中".to_string() + &"a".repeat(29);
+        assert_eq!(s.len(), 32);
+        assert_eq!(parse_hex_fixed::<16>(&s), None);
+    }
+
+    #[test]
+    fn bytes_variable_length_and_odd_rejected() {
+        assert_eq!(parse_hex_bytes("0xAABBCC"), Some(vec![0xAA, 0xBB, 0xCC]));
+        assert_eq!(parse_hex_bytes("AABBC"), None); // odd
+        // Empty (or prefix-only) → empty Vec: a legitimately-empty field.
+        assert_eq!(parse_hex_bytes(""), Some(vec![]));
+        assert_eq!(parse_hex_bytes("0x"), Some(vec![]));
+    }
+}

src/identity.rs

@@ -57,27 +57,48 @@ 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)?;
-
-        let firmware_date = if result.bytes_transferred > 12 {
-            String::from_utf8_lossy(&gc[12..24.min(result.bytes_transferred)])
+        // `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()),
+            };
 
-        // GET CONFIGURATION Feature 0108h — Serial Number
+        // 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 {
-                String::from_utf8_lossy(&gc_serial[12..r.bytes_transferred])
+                // `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 {
@@ -94,8 +115,8 @@ impl DriveId {
             vendor_specific: ascii_field(&inquiry, 36, 43),
             firmware_date,
             serial_number,
-            raw_inquiry: inquiry.to_vec(),
-            raw_gc_010c: gc[..result.bytes_transferred].to_vec(),
+            raw_inquiry: inquiry,
+            raw_gc_010c,
         })
     }
 
@@ -155,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() {
@@ -190,4 +254,135 @@ mod tests {
         assert_eq!(id.vendor_specific.trim(), "16/04/");
         assert_eq!(id.firmware_date, "201604250000");
     }
+
+    // ── New comprehensive tests ────────────────────────────────────────────────
+
+    /// ascii_field with a buffer shorter than `start` returns empty string
+    /// rather than panicking.
+    /// Spec: SPC-4 §6.4.2 — bytes[8:16] are vendor ID; a truncated buffer
+    ///       (e.g. a device that reports fewer than 8 bytes) must not panic.
+    /// Mutation: removing the `data.len() > start` guard makes it panic on short inputs.
+    #[test]
+    fn ascii_field_short_buffer_returns_empty() {
+        // Buffer of length 5: start=8 is beyond the end → empty string.
+        let buf = vec![0u8; 5];
+        let result = ascii_field(&buf, 8, 16); // SPC-4 vendor ID range
+        assert!(result.is_empty(), "short buffer must yield empty string");
+    }
+
+    /// ascii_field with a buffer that covers start but not end is clamped.
+    /// Spec: `ascii_field` documents "clamps to data.len()".
+    /// Mutation: using `end` directly without `min(data.len())` panics here.
+    #[test]
+    fn ascii_field_partial_buffer_is_clamped_not_panicked() {
+        // Buffer of length 12: vendor_id range is [8..16], but only [8..12] present.
+        let mut buf = vec![0u8; 12];
+        buf[8..12].copy_from_slice(b"SONY");
+        let result = ascii_field(&buf, 8, 16);
+        // Must not panic; the returned string holds what we wrote.
+        assert_eq!(result, "SONY");
+    }
+
+    /// from_inquiry extracts the product_id field from INQUIRY bytes [16:32].
+    /// Spec: SPC-4 §6.4.2 — PRODUCT IDENTIFICATION at offset 16, length 16.
+    /// Mutation: shifting the product_id slice to [8:24] makes this fail.
+    #[test]
+    fn from_inquiry_extracts_product_id_at_offset_16() {
+        let mut inquiry = vec![0u8; 96];
+        // Leave vendor_id (8..16) as zeros, write product_id at 16..32.
+        inquiry[16..32].copy_from_slice(b"BD-RW   BDR-209M");
+        let id = DriveId::from_inquiry(&inquiry, "");
+        assert_eq!(
+            id.product_id, "BD-RW   BDR-209M",
+            "product_id must come from INQUIRY bytes 16..32 (SPC-4 §6.4.2)"
+        );
+    }
+
+    /// from_inquiry extracts product_revision from INQUIRY bytes [32:36].
+    /// Spec: SPC-4 §6.4.2 — PRODUCT REVISION LEVEL at offset 32, length 4.
+    /// Mutation: reading revision from [36:40] produces the wrong value.
+    #[test]
+    fn from_inquiry_extracts_revision_at_offset_32() {
+        let mut inquiry = vec![0u8; 96];
+        inquiry[32..36].copy_from_slice(b"1.53");
+        let id = DriveId::from_inquiry(&inquiry, "");
+        assert_eq!(
+            id.product_revision, "1.53",
+            "product_revision must come from INQUIRY bytes 32..36 (SPC-4 §6.4.2)"
+        );
+    }
+
+    /// from_inquiry extracts vendor_specific from INQUIRY bytes [36:43].
+    /// Spec: SPC-4 §6.4.2 — VENDOR SPECIFIC at offset 36, length 8.
+    /// Mutation: reading vendor_specific from [32:39] returns the revision instead.
+    #[test]
+    fn from_inquiry_extracts_vendor_specific_at_offset_36() {
+        let mut inquiry = vec![0u8; 96];
+        inquiry[36..43].copy_from_slice(b"MM01234");
+        let id = DriveId::from_inquiry(&inquiry, "");
+        assert_eq!(
+            id.vendor_specific, "MM01234",
+            "vendor_specific must come from INQUIRY bytes 36..43 (SPC-4 §6.4.2)"
+        );
+    }
+
+    /// from_inquiry stores the raw inquiry bytes in raw_inquiry unchanged.
+    /// Mutation: copying only a slice of inquiry into raw_inquiry truncates it.
+    #[test]
+    fn from_inquiry_stores_raw_inquiry() {
+        let mut inquiry = vec![0u8; 96];
+        inquiry[8..16].copy_from_slice(b"TESTDRVR");
+        let id = DriveId::from_inquiry(&inquiry, "");
+        assert_eq!(
+            id.raw_inquiry, inquiry,
+            "raw_inquiry must preserve the full 96-byte buffer"
+        );
+    }
+
+    /// GET CONFIGURATION failure (transport error) must not abort the
+    /// identity probe — firmware_date is empty, raw_gc_010c is empty.
+    /// Mutation: propagating the GET_CONFIGURATION error with `?` aborts from_drive.
+    #[test]
+    fn from_drive_gc_failure_yields_empty_firmware_date() {
+        struct GcFailTransport;
+        impl ScsiTransport for GcFailTransport {
+            fn execute(
+                &mut self,
+                cdb: &[u8],
+                _dir: DataDirection,
+                buf: &mut [u8],
+                _timeout_ms: u32,
+            ) -> Result<ScsiResult> {
+                if cdb.first() == Some(&0x12) {
+                    // INQUIRY succeeds with a plausible response.
+                    buf[8..16].copy_from_slice(b"TESTDRV ");
+                    buf[16..32].copy_from_slice(b"FAKE DRIVE MODEL");
+                    buf[32..36].copy_from_slice(b"0001");
+                    buf[36..43].copy_from_slice(b"X000001");
+                    Ok(ScsiResult {
+                        status: 0,
+                        bytes_transferred: buf.len(),
+                        sense: [0u8; 32],
+                    })
+                } else {
+                    // GET CONFIGURATION fails.
+                    Err(crate::error::Error::ScsiError {
+                        opcode: cdb[0],
+                        status: crate::scsi::SCSI_STATUS_CHECK_CONDITION,
+                        sense: None,
+                    })
+                }
+            }
+        }
+        let mut t = GcFailTransport;
+        let id = DriveId::from_drive(&mut t).expect("from_drive must succeed despite GC failure");
+        assert!(
+            id.firmware_date.is_empty(),
+            "firmware_date must be empty when GC fails"
+        );
+        assert!(
+            id.raw_gc_010c.is_empty(),
+            "raw_gc_010c must be empty when GC fails"
+        );
+    }
 }

src/io/bounded.rs

@@ -67,10 +67,12 @@ pub(crate) enum BoundedError {
     /// The deadline elapsed before the syscall returned. Same leak
     /// semantics as `Halted`.
     Timeout,
-    /// The worker thread panicked, or its sender disconnected before
-    /// sending a result. Treat as a benign no-op (callers usually
-    /// log and continue) rather than a hard error — by definition no
-    /// syscall observably ran to completion in this case.
+    /// 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,
 }
 
@@ -101,6 +103,12 @@ 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 /
@@ -235,4 +243,53 @@ mod tests {
         assert!(matches!(r, Ok("ok")));
         assert!(flag.load(Ordering::Relaxed));
     }
+
+    // ── Added hardening tests ───────────────────────────────────────
+
+    /// Doc contract (lines 106-110): "If the caller already requested
+    /// halt, don't spawn (and leak) a worker that would run `op`."
+    /// When halt is pre-cancelled the op closure must NEVER run — the
+    /// short-circuit returns Halted before spawning the worker. We
+    /// prove the op did not execute by checking a side-effect flag.
+    #[test]
+    fn pre_cancelled_halt_never_runs_op() {
+        let halt = Halt::new();
+        halt.cancel();
+        let ran = Arc::new(AtomicBool::new(false));
+        let r2 = ran.clone();
+        let r = bounded_syscall(Some(&halt), Duration::from_secs(2), move || {
+            r2.store(true, Ordering::SeqCst);
+            7u32
+        });
+        assert!(matches!(r, Err(BoundedError::Halted)));
+        // The op closure must not have been scheduled at all.
+        assert!(
+            !ran.load(Ordering::SeqCst),
+            "op ran despite pre-cancelled halt — short-circuit at line 108 broken"
+        );
+    }
+
+    /// Timeout boundary: with a tiny deadline and an op that sleeps
+    /// much longer, the helper must return Timeout and must do so
+    /// roughly at the deadline — NOT wait for the op to finish (that
+    /// is the whole point of the bounded wrapper; the worker is
+    /// leaked). Grounds the `Instant::now() >= deadline` arm (line 141)
+    /// and the leak contract (doc lines 84-88).
+    #[test]
+    fn timeout_returns_near_deadline_not_after_op() {
+        let started = Instant::now();
+        let r = bounded_syscall(None, Duration::from_millis(100), || {
+            thread::sleep(Duration::from_secs(3));
+            0u32
+        });
+        let elapsed = started.elapsed();
+        assert!(matches!(r, Err(BoundedError::Timeout)));
+        // Must bail near the 100ms deadline (one POLL_INTERVAL slack at
+        // most), not after the 3s op. Allow generous CI slack but stay
+        // well under the op's 3s sleep.
+        assert!(
+            elapsed < Duration::from_millis(1500),
+            "timeout did not return near deadline: {elapsed:?} (op should be leaked, not awaited)"
+        );
+    }
 }

src/io/byte_channel.rs

@@ -1,330 +0,0 @@
-//! Byte-sized bounded producer/consumer channel.
-//!
-//! Wraps `std::sync::mpsc::sync_channel` with a byte-accounting
-//! `Mutex<usize> + Condvar` cap. Sender blocks (cooperatively) when
-//! `used_bytes + item.byte_size() > capacity_bytes`. Receiver
-//! decrements `used_bytes` when it takes the item.
-//!
-//! Why: the existing producer→consumer channel between `DiscStream`
-//! (PES producer) and `MuxSink` (PES consumer) is bounded by frame
-//! count. Frame sizes vary 100× between metadata and keyframes, so a
-//! count-based cap either starves on small frames or buffers far too
-//! much memory on big ones. Byte-sized accounting sizes the buffer for
-//! the worst-case input stall (NFS read p99 ≈ 1–2 s × ~15 MB/s peak
-//! compressed bitrate ≈ ~30 MB) directly.
-//!
-//! The underlying mpsc channel is created with a very large slot count
-//! so the byte cap (not the slot count) is the real backpressure. Slot
-//! count is only there to give the kernel a small chunk to wake on.
-//!
-//! See `freemkv-private/memory/project_buffering_architecture.md` §
-//! Pipeline channel — sizing.
-
-use std::sync::mpsc::{Receiver as MpscReceiver, RecvError, SendError, SyncSender, sync_channel};
-use std::sync::{Arc, Condvar, Mutex};
-
-/// Default byte cap for the muxer's input channel. Sized to hide a
-/// worst-case ~2 s NFS read refill at UHD peak compressed bitrate
-/// (~15 MB/s); 64 MiB gives headroom. Tweakable; not magic.
-pub const BYTE_CHANNEL_DEFAULT_CAPACITY: usize = 64 * 1024 * 1024;
-
-/// Slot capacity of the inner `sync_channel`. Large so the byte cap is
-/// the real backpressure mechanism — the mpsc slot count only exists
-/// to give the kernel a chunk to wake on. PES frames are typically
-/// ~700 B each, so 64 MiB ≈ 90 k frames; 200 k is comfortable headroom.
-const INNER_SLOT_CAPACITY: usize = 200_000;
-
-/// Anything whose in-memory cost can be accounted by a single
-/// `usize`. Implement on the item type sent through [`Sender`].
-pub trait HasByteSize {
-    /// Bytes this item contributes to the channel's used budget.
-    /// Must be > 0 to make progress (a 0-byte item would never
-    /// block the sender no matter the cap; see send_blocks_at_capacity
-    /// test).
-    fn byte_size(&self) -> usize;
-}
-
-impl HasByteSize for crate::pes::PesFrame {
-    fn byte_size(&self) -> usize {
-        // Frame data + the fixed header overhead the serializer
-        // writes (track + pts + keyframe + len). The `Vec<u8>` heap
-        // allocation also has alloc-header overhead but that's
-        // <0.1 % at typical frame sizes — folding it in would just
-        // add noise to the budget.
-        self.data.len() + 14
-    }
-}
-
-/// Shared book-keeping between [`Sender`] and [`Receiver`]. Wrapped in
-/// an `Arc` because both halves hold it independently.
-struct Accounting {
-    used: Mutex<usize>,
-    cv: Condvar,
-    capacity: usize,
-}
-
-/// Send half of the byte-bounded channel.
-///
-/// `send` blocks (on a `Condvar`) when adding the item would push
-/// `used_bytes` past `capacity_bytes`. Unblocks when the receiver
-/// `recv`s items out and notifies. Returns `Err(item)` if the
-/// receiver has been dropped — mirrors `mpsc::SyncSender::send`.
-pub struct Sender<T: HasByteSize> {
-    tx: SyncSender<T>,
-    acct: Arc<Accounting>,
-}
-
-impl<T: HasByteSize> Clone for Sender<T> {
-    fn clone(&self) -> Self {
-        Sender {
-            tx: self.tx.clone(),
-            acct: self.acct.clone(),
-        }
-    }
-}
-
-impl<T: HasByteSize> Sender<T> {
-    /// Push one item. Blocks until adding it would not exceed the
-    /// capacity, then sends through the inner mpsc channel.
-    pub fn send(&self, item: T) -> Result<(), SendError<T>> {
-        let sz = item.byte_size();
-        // Reserve capacity first. The reservation is observable to
-        // other senders via `used`; only after we win the slot do we
-        // hand the item to the inner mpsc channel. That ordering means
-        // `used` is always a conservative upper bound on what's in the
-        // mpsc queue + about-to-be-sent.
-        {
-            let mut used = self.acct.used.lock().expect("byte_channel poisoned");
-            // An item bigger than the whole capacity will never fit; let
-            // it through anyway as a one-shot reservation, otherwise the
-            // sender deadlocks forever waiting for `used == 0` AND
-            // nothing in flight. The receiver will drain it on the
-            // other side. Same behaviour as `std::sync::mpsc` for
-            // arbitrarily large messages.
-            while *used + sz > self.acct.capacity && *used > 0 {
-                used = self.acct.cv.wait(used).expect("byte_channel cv poisoned");
-            }
-            *used += sz;
-        }
-        match self.tx.send(item) {
-            Ok(()) => Ok(()),
-            Err(SendError(returned)) => {
-                // Receiver dropped — refund the reservation so a later
-                // sender on a clone doesn't observe phantom used bytes
-                // (the receiver is gone so nobody will decrement).
-                let mut used = self.acct.used.lock().expect("byte_channel poisoned");
-                *used = used.saturating_sub(sz);
-                self.acct.cv.notify_all();
-                Err(SendError(returned))
-            }
-        }
-    }
-}
-
-/// Receive half of the byte-bounded channel.
-///
-/// `recv` blocks on the inner mpsc until an item is available, then
-/// decrements the byte-accounting and wakes any sender waiting on
-/// capacity.
-pub struct Receiver<T: HasByteSize> {
-    rx: MpscReceiver<T>,
-    acct: Arc<Accounting>,
-}
-
-impl<T: HasByteSize> Receiver<T> {
-    /// Take the next item. Returns `Err(RecvError)` when all senders
-    /// have been dropped and the channel is empty.
-    pub fn recv(&self) -> Result<T, RecvError> {
-        let item = self.rx.recv()?;
-        let sz = item.byte_size();
-        let mut used = self.acct.used.lock().expect("byte_channel poisoned");
-        *used = used.saturating_sub(sz);
-        // Notify all so multi-sender setups wake every blocked sender,
-        // not just one. Wasted wakeups are cheap; missed wakeups would
-        // be a deadlock.
-        self.acct.cv.notify_all();
-        Ok(item)
-    }
-}
-
-/// Create a byte-bounded channel with the given capacity in bytes.
-/// Returns a `(Sender, Receiver)` pair; clone the `Sender` for
-/// multi-producer setups.
-pub fn channel<T: HasByteSize>(capacity_bytes: usize) -> (Sender<T>, Receiver<T>) {
-    let (tx, rx) = sync_channel::<T>(INNER_SLOT_CAPACITY);
-    let acct = Arc::new(Accounting {
-        used: Mutex::new(0),
-        cv: Condvar::new(),
-        capacity: capacity_bytes,
-    });
-    (
-        Sender {
-            tx,
-            acct: acct.clone(),
-        },
-        Receiver { rx, acct },
-    )
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use std::sync::Arc;
-    use std::sync::atomic::{AtomicUsize, Ordering};
-    use std::thread;
-    use std::time::{Duration, Instant};
-
-    /// Test payload — its `byte_size` returns whatever we passed at
-    /// construction so capacity math is exact and predictable.
-    #[derive(Clone, Debug, PartialEq, Eq)]
-    struct Item {
-        sz: usize,
-        tag: u32,
-    }
-
-    impl HasByteSize for Item {
-        fn byte_size(&self) -> usize {
-            self.sz
-        }
-    }
-
-    #[test]
-    fn send_recv_round_trip() {
-        let (tx, rx) = channel::<Item>(1024);
-        for i in 0..5 {
-            tx.send(Item { sz: 100, tag: i }).unwrap();
-        }
-        for i in 0..5 {
-            let got = rx.recv().unwrap();
-            assert_eq!(got, Item { sz: 100, tag: i });
-        }
-    }
-
-    #[test]
-    fn byte_accounting_decrements_on_recv() {
-        // Internal book-keeping check via observable side-effect: after
-        // sending K items totalling N bytes and receiving them all, a
-        // subsequent send of an N-byte item must NOT block (no items
-        // in flight, all capacity refunded).
-        let (tx, rx) = channel::<Item>(1024);
-        for _ in 0..4 {
-            tx.send(Item { sz: 256, tag: 0 }).unwrap();
-        }
-        for _ in 0..4 {
-            rx.recv().unwrap();
-        }
-        // Cap is now fully available again. Send a 1024-byte item; the
-        // `used > 0` guard means it goes through alone (no wait).
-        let start = Instant::now();
-        tx.send(Item { sz: 1024, tag: 99 }).unwrap();
-        assert!(start.elapsed() < Duration::from_millis(100));
-        let got = rx.recv().unwrap();
-        assert_eq!(got.tag, 99);
-    }
-
-    #[test]
-    fn send_blocks_at_capacity_unblocks_on_recv() {
-        // Cap = 200 bytes, item = 100 bytes. First two sends fit
-        // exactly; the third must block until a recv frees capacity.
-        let (tx, rx) = channel::<Item>(200);
-        tx.send(Item { sz: 100, tag: 0 }).unwrap();
-        tx.send(Item { sz: 100, tag: 1 }).unwrap();
-
-        let tx2 = tx.clone();
-        let sent_at = Arc::new(Mutex::new(None::<Instant>));
-        let sent_at2 = sent_at.clone();
-        let h = thread::spawn(move || {
-            tx2.send(Item { sz: 100, tag: 2 }).unwrap();
-            *sent_at2.lock().unwrap() = Some(Instant::now());
-        });
-
-        // Give the sender thread a head start; it should be parked in
-        // `cv.wait` because used (200) + 100 > capacity (200).
-        thread::sleep(Duration::from_millis(100));
-        assert!(
-            sent_at.lock().unwrap().is_none(),
-            "third send should be blocked at capacity"
-        );
-
-        // Drain one. Sender wakes and completes.
-        let recv_at = Instant::now();
-        let got = rx.recv().unwrap();
-        assert_eq!(got.tag, 0);
-        h.join().unwrap();
-
-        let sent_when = sent_at.lock().unwrap().unwrap();
-        assert!(
-            sent_when >= recv_at,
-            "sender must complete AFTER receiver freed capacity"
-        );
-
-        // Drain the remaining two.
-        assert_eq!(rx.recv().unwrap().tag, 1);
-        assert_eq!(rx.recv().unwrap().tag, 2);
-    }
-
-    #[test]
-    fn item_larger_than_capacity_still_goes_through() {
-        // Pathological case: a single item bigger than the capacity.
-        // The guard `*used > 0` lets it through when the channel is
-        // empty (otherwise the sender deadlocks forever). Matches
-        // `mpsc::SyncSender` semantics for oversize messages.
-        let (tx, rx) = channel::<Item>(100);
-        tx.send(Item { sz: 1000, tag: 7 }).unwrap();
-        let got = rx.recv().unwrap();
-        assert_eq!(got, Item { sz: 1000, tag: 7 });
-    }
-
-    #[test]
-    fn concurrent_send_recv_stress() {
-        // 4 sender threads × 1k items each, 1 receiver. Verify byte
-        // accounting stays sane (channel never deadlocks, every item
-        // arrives exactly once) under contention.
-        const SENDERS: u32 = 4;
-        const PER_SENDER: u32 = 1000;
-        const TOTAL: u32 = SENDERS * PER_SENDER;
-
-        let (tx, rx) = channel::<Item>(8 * 1024);
-        let sent = Arc::new(AtomicUsize::new(0));
-        let mut handles = Vec::new();
-        for s in 0..SENDERS {
-            let tx = tx.clone();
-            let sent = sent.clone();
-            handles.push(thread::spawn(move || {
-                for i in 0..PER_SENDER {
-                    // Vary item size so accounting actually has to
-                    // multiplex differently-sized blockers. 1B → 256B.
-                    let sz = 1 + ((i as usize) % 256);
-                    tx.send(Item {
-                        sz,
-                        tag: s * PER_SENDER + i,
-                    })
-                    .unwrap();
-                    sent.fetch_add(1, Ordering::SeqCst);
-                }
-            }));
-        }
-        // Drop our local sender so the receiver can eventually see
-        // RecvError once all sender clones are done. Cloning the
-        // sender into each producer means each clone Drop'd separately.
-        drop(tx);
-
-        let mut received = 0u32;
-        while let Ok(_item) = rx.recv() {
-            received += 1;
-        }
-        for h in handles {
-            h.join().unwrap();
-        }
-        assert_eq!(received, TOTAL);
-        assert_eq!(sent.load(Ordering::SeqCst) as u32, TOTAL);
-    }
-
-    #[test]
-    fn send_after_recv_dropped_returns_err() {
-        let (tx, rx) = channel::<Item>(1024);
-        drop(rx);
-        let r = tx.send(Item { sz: 10, tag: 0 });
-        assert!(r.is_err());
-    }
-}

src/io/byte_prefetcher.rs

@@ -10,11 +10,12 @@
 //!
 //! This is the byte-stream half of the freemkv mux highway —
 //! `BytePrefetcher` feeds [`crate::mux::demux_thread::DemuxThread`]
-//! for `m2ts://`, `network://`, `stdio://`, and any other stream
-//! whose source is an `io::Read` rather than a `SectorSource`.
+//! 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;
-use crossbeam_channel::{Receiver, Sender, bounded};
+use crate::halt::{Halt, POLL_INTERVAL};
+use crossbeam_channel::{Receiver, RecvTimeoutError, SendTimeoutError, Sender, bounded};
 use std::io::Read;
 use std::thread::JoinHandle;
 
@@ -38,6 +39,13 @@ 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<()>>,
 }
@@ -52,8 +60,8 @@ impl Drop for PrefetchShell {
 
 /// Spawned byte prefetcher. Drop joins the producer thread.
 pub struct BytePrefetcher {
-    rx: Receiver<Batch>,
-    recycle_tx: Sender<Vec<u8>>,
+    rx: Option<Receiver<Batch>>,
+    recycle_tx: Option<Sender<Vec<u8>>>,
     producer: Option<JoinHandle<()>>,
 }
 
@@ -66,7 +74,13 @@ impl BytePrefetcher {
         mut reader: R,
         chunk_bytes: usize,
         halt: Option<Halt>,
-    ) -> Self {
+    ) -> 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);
 
@@ -80,16 +94,49 @@ impl BytePrefetcher {
         let producer = std::thread::Builder::new()
             .name("freemkv-byte-prefetch".into())
             .spawn(move || {
+                // Wrap the feed loop in catch_unwind so a panic in the inner
+                // `reader.read` (e.g. a decrypt-on-read slice/arith bug) is NOT
+                // indistinguishable from a clean finish at the demux boundary. A
+                // clean exit (EOF, halt, consumer disconnect) returns and drops
+                // `tx` → the demux loop reads RecvError as EOF (correct). A PANIC
+                // sends an explicit error sentinel first so the demux loop's
+                // `Ok(Err(_))` arm fires and propagates a typed error instead of
+                // converting the dropped channel into a clean `DemuxBatch::Eof`
+                // that would finalize a TRUNCATED mux while reporting success.
+                let body = std::panic::AssertUnwindSafe(|| {
+                    let cancelled = || halt.as_ref().map(|h| h.is_cancelled()).unwrap_or(false);
+                    // Liveness heartbeat: the producer blocks on the recycle and
+                    // forward channels; a stalled consumer or a wedged reader shows
+                    // up as the beat going silent. Total is unknown, so `pos` is
+                    // cumulative bytes read.
+                    let mut hb = crate::progress::Heartbeat::new("byte_prefetch");
+                    let mut produced_bytes: u64 = 0;
                     loop {
-                    if halt.as_ref().map(|h| h.is_cancelled()).unwrap_or(false) {
+                        hb.tick(produced_bytes, 0);
+                        if cancelled() {
                             return;
                         }
-                    let mut buf = match recycle_rx.recv() {
-                        Ok(b) => b,
-                        Err(_) => return, // consumer dropped both channels
+                        // 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 (previous iteration
-                    // may have truncated after a short read).
+                        // 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 {
@@ -108,19 +155,40 @@ impl BytePrefetcher {
                                 return;
                             }
                         };
+                        produced_bytes += n as u64;
                         buf.truncate(n);
-                    if tx.send(Ok(buf)).is_err() {
-                        return; // consumer dropped
+                        // 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,
                             }
                         }
-            })
-            .expect("freemkv-byte-prefetch thread spawn failed");
+                    }
+                });
+                if std::panic::catch_unwind(body).is_err() {
+                    // Producer panicked mid-stream — surface a typed terminal
+                    // error so the demux thread does NOT read the dropped channel
+                    // as a clean EOF and truncate output.
+                    let _ = tx.send(Err(crate::error::Error::DemuxThreadPanicked.into()));
+                }
+            })?;
 
-        Self {
-            rx,
-            recycle_tx,
+        Ok(Self {
+            rx: Some(rx),
+            recycle_tx: Some(recycle_tx),
             producer: Some(producer),
-        }
+        })
     }
 
     /// Peel off the channels for zero-copy pipeline consumption. The
@@ -128,19 +196,364 @@ impl BytePrefetcher {
     /// drains `rx`, runs the demuxer in place on each filled buffer,
     /// and recycles back through `recycle_tx`.
     pub fn into_channels(self) -> (Receiver<Batch>, Sender<Vec<u8>>, PrefetchShell) {
-        let mut me = self;
-        let producer = me.producer.take();
-        let rx = me.rx.clone();
-        let recycle = me.recycle_tx.clone();
-        std::mem::forget(me);
+        // 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) };
+        // SAFETY: `rx` and `recycle_tx` are always `Some` here —
+        // `into_channels` is the only way to consume a live
+        // `BytePrefetcher`; `Drop::drop` is suppressed by `ManuallyDrop`.
+        let rx = unsafe { std::ptr::read(&me.rx) }.expect("rx always Some before drop");
+        let recycle =
+            unsafe { std::ptr::read(&me.recycle_tx) }.expect("recycle_tx always Some before drop");
         (rx, recycle, PrefetchShell { producer })
     }
 }
 
 impl Drop for BytePrefetcher {
     fn drop(&mut self) {
+        // Drop channel endpoints BEFORE joining the producer so the
+        // producer observes SendTimeoutError::Disconnected (forward tx)
+        // or RecvTimeoutError::Disconnected (recycle rx) and exits
+        // promptly. Without this, a non-EOF source fills the depth-2
+        // forward channel and then spins in send_timeout(POLL_INTERVAL)
+        // forever because rx is never drained, causing join() to
+        // deadlock.
+        drop(self.rx.take());
+        drop(self.recycle_tx.take());
         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);
+        });
+    }
+
+    // ── Added hardening tests ───────────────────────────────────────
+
+    use std::io::Cursor;
+
+    /// Drain the forward channel, recycling every buffer, and
+    /// reassemble the bytes. Returns the concatenation of every
+    /// delivered chunk. Stops on RecvError (producer dropped tx == EOF)
+    /// or on the first Err batch (which it returns separately).
+    fn drain_to_vec(pf: BytePrefetcher) -> (Vec<u8>, Option<std::io::Error>) {
+        let (rx, recycle_tx, shell) = pf.into_channels();
+        let mut out = Vec::new();
+        let mut err = None;
+        while let Ok(batch) = rx.recv() {
+            match batch {
+                Ok(buf) => {
+                    out.extend_from_slice(&buf);
+                    // Recycle so the producer can refill. Ignore send
+                    // error (producer may have already exited at EOF).
+                    let _ = recycle_tx.send(buf);
+                }
+                Err(e) => {
+                    err = Some(e);
+                    break;
+                }
+            }
+        }
+        drop(rx);
+        drop(recycle_tx);
+        drop(shell);
+        (out, err)
+    }
+
+    /// CORE CONTRACT: the prefetcher must deliver every source byte,
+    /// in order, exactly once — never silently truncate or duplicate.
+    /// Source is 5000 bytes; chunk size 1024 forces multiple chunks
+    /// (4 full + 1 short of 904). The reassembled stream must equal the
+    /// source. Mutation: replacing `buf.truncate(n)` (line 141) with a
+    /// no-op would over-report bytes on the final short read and this
+    /// fails.
+    #[test]
+    fn delivers_all_bytes_in_order_across_chunks() {
+        within(10, || {
+            let src: Vec<u8> = (0..5000u32).map(|i| (i & 0xff) as u8).collect();
+            let pf = BytePrefetcher::new(Cursor::new(src.clone()), 1024, None).expect("spawn");
+            let (got, err) = drain_to_vec(pf);
+            assert!(err.is_none(), "unexpected error batch: {err:?}");
+            assert_eq!(got, src, "prefetcher truncated or reordered bytes");
+        });
+    }
+
+    /// Short-read truncation: a reader that returns fewer bytes than
+    /// requested per call must NOT leave stale tail bytes in the
+    /// delivered chunk. Cursor over 10 bytes with a 4096 chunk yields a
+    /// single 10-byte chunk; the consumer must see exactly 10 bytes,
+    /// not 4096. Grounds `buf.truncate(n)` at line 141. Mutation:
+    /// delete the truncate and the chunk would carry 4086 zero bytes of
+    /// padding, failing the length assert.
+    #[test]
+    fn short_read_truncates_to_actual_length() {
+        within(10, || {
+            let src = vec![0xAB; 10];
+            let pf = BytePrefetcher::new(Cursor::new(src.clone()), 4096, None).expect("spawn");
+            let (got, err) = drain_to_vec(pf);
+            assert!(err.is_none());
+            assert_eq!(got.len(), 10, "delivered chunk padded past actual read");
+            assert_eq!(got, src);
+        });
+    }
+
+    /// EOF semantics: an empty source (Cursor over `[]`) yields
+    /// `read() == Ok(0)` on the first call, which the producer treats
+    /// as EOF and returns, dropping tx. The consumer sees RecvError
+    /// (zero batches), NOT an Err batch and NOT a zero-length Ok batch.
+    /// Grounds the `Ok(0) => return` arm at line 134. Mutation:
+    /// changing `Ok(0) => return` to `Ok(0) => continue` would spin
+    /// forever (within() would time out).
+    #[test]
+    fn empty_source_yields_clean_eof_no_batches() {
+        within(10, || {
+            let pf = BytePrefetcher::new(Cursor::new(Vec::<u8>::new()), 4096, None).expect("spawn");
+            let (rx, recycle_tx, shell) = pf.into_channels();
+            // No Ok batch should ever arrive; first recv must be Err
+            // (producer dropped tx at EOF).
+            let first = rx.recv();
+            assert!(
+                first.is_err(),
+                "empty source produced a batch instead of clean EOF: {first:?}"
+            );
+            drop(rx);
+            drop(recycle_tx);
+            drop(shell);
+        });
+    }
+
+    /// Error propagation: a reader that fails mid-stream must surface
+    /// the io::Error as an `Err` batch on the forward channel (line
+    /// 137), not swallow it. We deliver one good chunk then an error.
+    /// The consumer must see the good bytes followed by the error.
+    /// Mutation: changing `let _ = tx.send(Err(e)); return;` to a plain
+    /// `return` would drop the error silently and this fails.
+    #[test]
+    fn read_error_is_propagated_as_err_batch() {
+        within(10, || {
+            struct OneThenError {
+                served: bool,
+            }
+            impl Read for OneThenError {
+                fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
+                    if !self.served {
+                        self.served = true;
+                        let n = buf.len().min(8);
+                        buf[..n].fill(0x11);
+                        Ok(n)
+                    } else {
+                        Err(std::io::Error::other("synthetic mid-stream read failure"))
+                    }
+                }
+            }
+            let pf = BytePrefetcher::new(OneThenError { served: false }, 8, None).expect("spawn");
+            let (got, err) = drain_to_vec(pf);
+            assert_eq!(got, vec![0x11; 8], "good chunk lost");
+            let err = err.expect("read error must surface as an Err batch");
+            assert_eq!(err.kind(), std::io::ErrorKind::Other);
+        });
+    }
+
+    /// PANIC propagation: a reader that PANICS mid-stream must NOT be read as a
+    /// clean EOF at the demux boundary. The producer's catch_unwind sends an
+    /// explicit `Err` sentinel before the thread unwinds, so the consumer sees
+    /// the good bytes followed by an error batch — never a silent truncation.
+    /// Without the catch_unwind the panic would just drop `tx`, the consumer
+    /// would see RecvError (== clean EOF) and the partial output would be
+    /// finalized as if complete.
+    #[test]
+    fn read_panic_surfaces_as_err_batch_not_clean_eof() {
+        within(10, || {
+            struct OneThenPanic {
+                served: bool,
+            }
+            impl Read for OneThenPanic {
+                fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
+                    if !self.served {
+                        self.served = true;
+                        let n = buf.len().min(8);
+                        buf[..n].fill(0x22);
+                        Ok(n)
+                    } else {
+                        panic!("synthetic mid-stream reader panic");
+                    }
+                }
+            }
+            let pf = BytePrefetcher::new(OneThenPanic { served: false }, 8, None).expect("spawn");
+            let (got, err) = drain_to_vec(pf);
+            assert_eq!(got, vec![0x22; 8], "good chunk lost before the panic");
+            assert!(
+                err.is_some(),
+                "a mid-stream producer PANIC must surface as an Err batch, \
+                 not a clean EOF (which would silently truncate the mux)"
+            );
+        });
+    }
+
+    /// Recycle-buffer reuse must NOT leak stale bytes between chunks of
+    /// different lengths. After a full chunk, a short read reuses the
+    /// same recycled buffer; lines 123-129 regrow it to chunk_bytes
+    /// before reading, then line 141 truncates to the short count. We
+    /// verify the short chunk carries only fresh bytes by reassembling
+    /// the full stream. Source: 8 bytes of 0xAA + 3 bytes of 0xBB, with
+    /// chunk_bytes=8 → chunk0 = 8×0xAA, chunk1 = 3×0xBB.
+    #[test]
+    fn recycled_buffer_carries_no_stale_tail() {
+        within(10, || {
+            let mut src = vec![0xAA; 8];
+            src.extend_from_slice(&[0xBB; 3]);
+            let pf = BytePrefetcher::new(Cursor::new(src.clone()), 8, None).expect("spawn");
+            let (got, err) = drain_to_vec(pf);
+            assert!(err.is_none());
+            assert_eq!(
+                got, src,
+                "stale bytes from recycled buffer leaked into short chunk"
+            );
+        });
+    }
+
+    /// Exact-multiple boundary: when the source length is an exact
+    /// multiple of chunk_bytes, the final non-empty chunk is followed
+    /// by an `Ok(0)` EOF read, NOT a spurious empty Ok batch. 12 bytes
+    /// with chunk_bytes=4 → three 4-byte chunks then clean EOF. Total
+    /// bytes must equal 12 and no zero-length batch may appear.
+    #[test]
+    fn exact_multiple_length_no_trailing_empty_batch() {
+        within(10, || {
+            let src = vec![0x42u8; 12];
+            let pf = BytePrefetcher::new(Cursor::new(src.clone()), 4, None).expect("spawn");
+            let (rx, recycle_tx, shell) = pf.into_channels();
+            let mut total = 0usize;
+            let mut batch_count = 0usize;
+            while let Ok(Ok(buf)) = rx.recv() {
+                assert!(!buf.is_empty(), "producer emitted a zero-length batch");
+                total += buf.len();
+                batch_count += 1;
+                let _ = recycle_tx.send(buf);
+            }
+            assert_eq!(total, 12);
+            assert_eq!(batch_count, 3, "expected exactly 3 full chunks");
+            drop(rx);
+            drop(recycle_tx);
+            drop(shell);
+        });
+    }
+
+    /// Dropping the BytePrefetcher directly (without into_channels)
+    /// must join the producer cleanly when the source is finite. The
+    /// producer reaches EOF, drops tx, and exits; Drop's join returns.
+    /// Grounds the BytePrefetcher Drop impl (lines 202-208). Mutation:
+    /// removing the `Ok(0) => return` EOF exit would hang this join.
+    #[test]
+    fn drop_finite_prefetcher_joins_cleanly() {
+        within(10, || {
+            let pf = BytePrefetcher::new(Cursor::new(vec![1u8; 100]), 4096, None).expect("spawn");
+            // Drop without consuming — producer fills the forward
+            // channel (capacity 2), reaches EOF on the third read since
+            // 100 < 4096 (single chunk + EOF), drops tx, exits.
+            drop(pf);
+        });
+    }
+
+    /// Regression: dropping a BytePrefetcher directly (without
+    /// into_channels) with an ENDLESS source must not deadlock. Before
+    /// the fix, Drop joined the producer while rx/recycle_tx were still
+    /// alive (sibling field drop order), so the producer filled the
+    /// depth-2 forward channel and then spun in send_timeout forever
+    /// (rx never drained, halt=None). The fix drops rx+recycle_tx
+    /// BEFORE the join so the producer sees SendTimeoutError::Disconnected
+    /// and exits.
+    #[test]
+    fn drop_endless_prefetcher_joins_cleanly() {
+        within(10, || {
+            let pf = BytePrefetcher::new(EndlessReader, 4096, None).expect("spawn");
+            // Drop without consuming — the old Drop deadlocked here.
+            drop(pf);
+        });
+    }
+}

src/io/file_sector_source/macos.rs

@@ -8,32 +8,22 @@
 use std::fs::File;
 use std::os::unix::io::AsRawFd;
 
-/// `F_RDADVISE` opcode — not in libc's named constants on all SDKs.
-const F_RDADVISE: libc::c_int = 44;
-
 /// Cap on the byte length we pass to `F_RDADVISE`. Asking for a
 /// multi-GB readahead window is counterproductive — the OS doesn't
 /// have that much cache to throw at one fd. 64 MiB is generous for
-/// our use case (sweep, mux) and matches the byte-channel cap so the
-/// kernel's prefetch ≥ our app-level pipeline depth.
+/// our use case (sweep, mux) so the kernel's prefetch ≥ our app-level
+/// pipeline depth.
 const RDADVISE_MAX_BYTES: i64 = 64 * 1024 * 1024;
 
-/// `radvisory` per `<sys/fcntl.h>`. repr(C) layout is stable.
-#[repr(C)]
-struct RadAdvisory {
-    ra_offset: libc::off_t,
-    ra_count: libc::c_int,
-}
-
 pub(super) fn hint_sequential(file: &File, len_bytes: u64) {
     let bytes = (len_bytes as i64).min(RDADVISE_MAX_BYTES);
-    let mut ra = RadAdvisory {
+    let mut ra = libc::radvisory {
         ra_offset: 0,
         ra_count: bytes as libc::c_int,
     };
     // Best-effort.
     unsafe {
-        libc::fcntl(file.as_raw_fd(), F_RDADVISE, &mut ra);
+        libc::fcntl(file.as_raw_fd(), libc::F_RDADVISE, &mut ra);
     }
 }
 
@@ -52,11 +42,12 @@ pub(super) fn drop_window(_file: &File, _start: u64, _len: u64) {}
 /// returns immediately.
 pub(super) fn prefetch(file: &File, offset: u64, len: u64) {
     let bytes = (len as i64).min(RDADVISE_MAX_BYTES);
-    let mut ra = RadAdvisory {
+    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(), F_RDADVISE, &mut ra);
+        libc::fcntl(file.as_raw_fd(), libc::F_RDADVISE, &mut ra);
     }
 }

src/io/file_sector_source/mod.rs

@@ -17,9 +17,17 @@
 //! Without page-cache eviction an 85 GB streaming ISO read pins the
 //! entire file in memory, starves the concurrent writer, and collapses
 //! mux throughput (observed: 2.7 MB/s mux on 0.21.5 vs. 70 MB/s
-//! isolated NFS reads). Every [`READ_DROP_CHUNK_BYTES`] of consumed
-//! bytes we call `posix_fadvise(DONTNEED)` over that window, mirroring
-//! the write-side [`crate::io::writeback::WritebackPipeline`] policy.
+//! 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
 //!
@@ -64,7 +72,7 @@ use std::path::Path;
 use crate::error::{Error, Result};
 use crate::sector::SectorSource;
 
-const SECTOR_SIZE: usize = 2048;
+use crate::consts::{SECTOR_BYTES, SECTOR_BYTES_U64};
 
 /// Bytes-read threshold per `posix_fadvise(DONTNEED)` drop on the
 /// read side. Mirrors `WRITEBACK_CHUNK_BYTES` so the read-side page
@@ -102,7 +110,10 @@ pub struct FileSectorSource {
     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.
+    /// `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,
@@ -116,16 +127,18 @@ impl FileSectorSource {
     ///
     /// Issues the platform's "sequential access expected" hint on the
     /// fd (Linux `posix_fadvise(SEQUENTIAL)`, macOS `fcntl(F_RDADVISE)`,
-    /// Windows TODO stub) so the kernel's readahead widens.
-    pub fn open(path: &Path) -> std::io::Result<Self> {
-        let file = File::open(path)?;
-        let len = file.metadata()?.len();
-        let sectors = len / SECTOR_SIZE as u64;
+    /// 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_BYTES_U64;
         if sectors > u32::MAX as u64 {
             return Err(Error::IsoTooLarge {
                 path: path.to_string_lossy().into_owned(),
-            }
-            .into());
+            });
         }
         let capacity = sectors as u32;
 
@@ -157,7 +170,7 @@ impl SectorSource for FileSectorSource {
         _recovery: bool,
     ) -> Result<usize> {
         let count = count as u32;
-        let bytes = count as usize * SECTOR_SIZE;
+        let bytes = count as usize * SECTOR_BYTES;
         debug_assert!(
             out.len() >= bytes,
             "FileSectorSource::read_sectors: out len {} < requested {}",
@@ -167,7 +180,7 @@ impl SectorSource for FileSectorSource {
         if count == 0 {
             return Ok(0);
         }
-        let offset = lba as u64 * SECTOR_SIZE as u64;
+        let offset = lba as u64 * SECTOR_BYTES_U64;
         self.file
             .seek(SeekFrom::Start(offset))
             .map_err(|e| Error::IoError { source: e })?;
@@ -211,7 +224,7 @@ mod tests {
     /// 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];
+        let mut chunk = vec![0u8; SECTOR_BYTES];
         for n in 0..sectors {
             let b = (n & 0xff) as u8;
             chunk.iter_mut().for_each(|c| *c = b);
@@ -236,7 +249,7 @@ mod tests {
         let mut src = FileSectorSource::open(&path).unwrap();
         assert_eq!(src.capacity_sectors(), total);
 
-        let mut got = vec![0u8; SECTOR_SIZE];
+        let mut got = vec![0u8; SECTOR_BYTES];
         for lba in 0..total {
             src.read_sectors(lba, 1, &mut got, false).unwrap();
             let expected = (lba & 0xff) as u8;
@@ -257,12 +270,12 @@ mod tests {
         let mut src = FileSectorSource::open(&path).unwrap();
 
         let span_lba = TEST_SPAN_SECTORS - 2;
-        let mut buf4 = vec![0u8; SECTOR_SIZE * 4];
+        let mut buf4 = vec![0u8; SECTOR_BYTES * 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] {
+            for b in &buf4[i * SECTOR_BYTES..(i + 1) * SECTOR_BYTES] {
                 assert_eq!(*b, expected, "byte mismatch at sub-sector {i}");
             }
         }
@@ -278,7 +291,7 @@ mod tests {
         make_iso(&path, total);
 
         let mut src = FileSectorSource::open(&path).unwrap();
-        let mut got = vec![0u8; SECTOR_SIZE];
+        let mut got = vec![0u8; SECTOR_BYTES];
 
         src.read_sectors(TEST_SPAN_SECTORS + 1, 1, &mut got, false)
             .unwrap();
@@ -298,7 +311,7 @@ mod tests {
         let mut src = FileSectorSource::open(&path).unwrap();
         assert_eq!(src.capacity_sectors(), total);
 
-        let mut got = vec![0u8; SECTOR_SIZE];
+        let mut got = vec![0u8; SECTOR_BYTES];
         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;
@@ -317,15 +330,15 @@ mod tests {
 
         let mut src = FileSectorSource::open(&path).unwrap();
         let req = (TEST_SPAN_SECTORS + 1) as u16;
-        let req_bytes = req as usize * SECTOR_SIZE;
+        let req_bytes = req as usize * SECTOR_BYTES;
         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));
+        assert!(big[..SECTOR_BYTES].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;
+        let last_off = (req as usize - 1) * SECTOR_BYTES;
         assert!(
-            big[last_off..last_off + SECTOR_SIZE]
+            big[last_off..last_off + SECTOR_BYTES]
                 .iter()
                 .all(|b| *b == exp)
         );
@@ -358,4 +371,151 @@ mod tests {
             std::env::remove_var("FREEMKV_READ_DROP_CHUNK_MIB");
         }
     }
+
+    // ---------------------------------------------------------------
+    // Additional coverage.
+    // ---------------------------------------------------------------
+
+    /// `count == 0` must short-circuit to Ok(0) WITHOUT seeking or
+    /// reading, even at an out-of-range LBA — the early-return guard
+    /// runs before any I/O. Grounding: `if count == 0 { return Ok(0) }`.
+    #[test]
+    fn zero_count_returns_zero_no_io() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("zc.iso");
+        make_iso(&path, 4);
+        let mut src = FileSectorSource::open(&path).unwrap();
+        // LBA far past EOF — must not matter because count==0 returns early.
+        let mut buf = [0u8; 1];
+        let n = src.read_sectors(1_000_000, 0, &mut buf, false).unwrap();
+        assert_eq!(n, 0);
+    }
+
+    /// Reading past EOF must ERROR (read_exact's UnexpectedEof), never
+    /// return a partial/short count. This is the core "never silently
+    /// truncate / never return fewer bytes than declared" property of
+    /// the SectorSource contract. Grounding: `self.file.read_exact(...)`
+    /// — read_exact fails if the file can't supply the full span.
+    #[test]
+    fn read_past_eof_errors_not_truncates() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("eof.iso");
+        make_iso(&path, 4); // 4 sectors only
+        let mut src = FileSectorSource::open(&path).unwrap();
+        assert_eq!(src.capacity_sectors(), 4);
+
+        // Request 2 sectors starting at LBA 3 → sector 4 doesn't exist.
+        let mut buf = vec![0u8; 2 * SECTOR_BYTES];
+        let r = src.read_sectors(3, 2, &mut buf, false);
+        let err = r.expect_err("reading past EOF must error, not short-read");
+        let io: std::io::Error = err.into();
+        assert_eq!(
+            io.kind(),
+            std::io::ErrorKind::UnexpectedEof,
+            "partial read at EOF must surface read_exact's UnexpectedEof"
+        );
+    }
+
+    /// On a successful full read the returned count MUST equal
+    /// `count * 2048` exactly — the declared byte count. Grounding:
+    /// `Ok(bytes)` where `bytes = count * SECTOR_BYTES`.
+    #[test]
+    fn full_read_returns_exact_declared_bytes() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("exact.iso");
+        make_iso(&path, 16);
+        let mut src = FileSectorSource::open(&path).unwrap();
+        let mut buf = vec![0u8; 5 * SECTOR_BYTES];
+        let n = src.read_sectors(2, 5, &mut buf, false).unwrap();
+        assert_eq!(n, 5 * SECTOR_BYTES, "must return exactly count*2048 bytes");
+    }
+
+    /// Capacity is `file_len / 2048` (floor); trailing bytes that don't
+    /// complete a sector are NOT counted. A file of 4 sectors + 100
+    /// extra bytes reports capacity 4. Grounding: `len / SECTOR_BYTES`
+    /// integer division in `open`.
+    #[test]
+    fn capacity_floors_partial_trailing_sector() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("partial.iso");
+        make_iso(&path, 4);
+        // Append 100 stray bytes (a torn final sector).
+        {
+            let mut f = std::fs::OpenOptions::new()
+                .append(true)
+                .open(&path)
+                .unwrap();
+            f.write_all(&[0xee; 100]).unwrap();
+            f.flush().unwrap();
+        }
+        let src = FileSectorSource::open(&path).unwrap();
+        assert_eq!(
+            src.capacity_sectors(),
+            4,
+            "partial trailing bytes must not inflate the sector capacity"
+        );
+    }
+
+    /// An empty file opens cleanly with capacity 0. Grounding:
+    /// `0 / 2048 == 0`, and the IsoTooLarge guard only fires for
+    /// oversize files.
+    #[test]
+    fn empty_file_capacity_zero() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("empty.iso");
+        std::fs::File::create(&path).unwrap();
+        let src = FileSectorSource::open(&path).unwrap();
+        assert_eq!(src.capacity_sectors(), 0);
+    }
+
+    /// Opening a nonexistent path returns an IoError (NotFound), not a
+    /// panic. Grounding: `File::open(path).map_err(...)`.
+    #[test]
+    fn open_missing_file_errors() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("does-not-exist.iso");
+        let err = match FileSectorSource::open(&path) {
+            Ok(_) => panic!("missing file must error"),
+            Err(e) => e,
+        };
+        let io: std::io::Error = err.into();
+        assert_eq!(io.kind(), std::io::ErrorKind::NotFound);
+    }
+
+    /// A DONTNEED drop crossing the chunk threshold must not corrupt or
+    /// short subsequent reads — the eviction is a pure page-cache hint.
+    /// We read past the DEFAULT 32 MiB drop chunk (16384 sectors) so the
+    /// eviction block fires at least once, asserting every sector still
+    /// reads correctly. (Avoids mutating FREEMKV_READ_DROP_CHUNK_MIB to
+    /// sidestep a parallel-test env race with `drop_chunk_size_env_override`.)
+    /// Grounding: the `bytes_read_since_drop >= drop_chunk_bytes`
+    /// eviction block calls only `platform::drop_window` (advisory) and
+    /// resets counters — no data effect.
+    #[test]
+    fn dontneed_eviction_does_not_affect_data() {
+        // 32 MiB default chunk = 16384 sectors; read a bit past it.
+        let total = (READ_DROP_CHUNK_BYTES_DEFAULT / SECTOR_BYTES_U64) as u32 + 64;
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("drop.iso");
+        make_iso(&path, total);
+        let mut src = FileSectorSource::open(&path).unwrap();
+        // Read in 16-sector batches to keep the loop fast while still
+        // crossing the drop boundary by byte count.
+        let batch = 16u16;
+        let mut got = vec![0u8; batch as usize * SECTOR_BYTES];
+        let mut lba = 0u32;
+        while lba + batch as u32 <= total {
+            src.read_sectors(lba, batch, &mut got, false).unwrap();
+            for i in 0..batch as u32 {
+                let expected = ((lba + i) & 0xff) as u8;
+                let off = i as usize * SECTOR_BYTES;
+                assert!(
+                    got[off..off + SECTOR_BYTES].iter().all(|x| *x == expected),
+                    "DONTNEED eviction corrupted sector {}",
+                    lba + i
+                );
+            }
+            lba += batch as u32;
+        }
+    }
 }

src/io/file_sector_source/windows.rs

@@ -1,20 +1,18 @@
 //! Windows: the canonical sequential-access hint is
-//! `FILE_FLAG_SEQUENTIAL_SCAN` passed to `CreateFile` at open time —
-//! it cannot be set after the fact via `SetFileInformationByHandle`.
-//! Routing the open call through this module would mean a custom
-//! `File::from_raw_handle` plumb for every `FileSectorSource::open`
-//! caller, which is more invasive than the Phase 1 scope.
-//!
-//! TODO: replumb `FileSectorSource::open` to take an
-//! `OpenOptions`-style builder so the Windows path can flip the flag
-//! at open time. For now this is a no-op stub.
+//! `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 stub (TODO: FILE_FLAG_SEQUENTIAL_SCAN at open)"
+        "FileSectorSource hint_sequential: windows no-op stub"
     );
 }
 

src/io/fsync/mod.rs

@@ -0,0 +1,92 @@
+//! Platform-aware crash-durability primitives.
+//!
+//! Two flush operations need OS-specific handling to make a write survive a
+//! crash / power loss:
+//!
+//! - [`dir`] — fsync a directory so a prior `rename(2)` into it is durable.
+//!   After a crash a renamed file's dirent can otherwise be lost even though
+//!   the rename returned, because it is still page-cache-only. This is a POSIX
+//!   concept: on Windows std cannot even open a directory as a `File` (it does
+//!   not set `FILE_FLAG_BACKUP_SEMANTICS`), and NTFS/ReFS commit the rename's
+//!   dirent without an explicit directory flush — so it is a no-op there
+//!   rather than a failed open that logs on every marker write.
+//!
+//! - [`file_durable`] — fsync a file's contents + metadata. Opens the file
+//!   **read+write**: on Windows `File::sync_all` maps to `FlushFileBuffers`,
+//!   which requires a handle with write access and returns
+//!   `ERROR_ACCESS_DENIED` (os error 5) on a read-only handle. (A read-only
+//!   `File::open` + `sync_all` is legal on POSIX, which is why that bug only
+//!   bit Windows.) The open mode is platform-uniform, so this lives here with
+//!   no dispatch.
+//!
+//! Per the crate convention (see [`crate::io::writeback_file`]), platform
+//! dispatch happens once here via cfg-gated `mod` decls — callers carry no
+//! inline `#[cfg(...)]`.
+
+use std::io;
+use std::path::Path;
+
+#[cfg(not(windows))]
+mod posix;
+#[cfg(windows)]
+mod windows;
+
+#[cfg(not(windows))]
+use posix as platform;
+#[cfg(windows)]
+use windows as platform;
+
+/// fsync a directory so a prior `rename(2)` into it is durable. Best-effort:
+/// failures are logged and swallowed, never propagated — the renamed file's
+/// bytes are already synced and the caller's write itself succeeded. No-op on
+/// Windows (see module docs).
+pub fn dir(path: &Path) {
+    platform::fsync_dir(path)
+}
+
+/// Durably flush an existing file's contents + metadata to stable storage.
+///
+/// Opens the file read+write (not read-only) so the flush succeeds on every
+/// platform — see the module docs for the Windows `FlushFileBuffers` rationale.
+/// The file must already exist; its bytes are left intact (no create/truncate).
+pub fn file_durable(path: &Path) -> io::Result<()> {
+    let f = std::fs::OpenOptions::new()
+        .read(true)
+        .write(true)
+        .open(path)?;
+    f.sync_all()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// `file_durable` opens read+write (so the flush works on Windows) and
+    /// syncs an existing file; a missing path surfaces as `Err` so the caller
+    /// treats it as "not durably synced". Platform-uniform — same on
+    /// unix/windows.
+    #[test]
+    fn file_durable_ok_for_existing_err_for_missing() {
+        let td = tempfile::tempdir().unwrap();
+        let f = td.path().join("data.bin");
+        std::fs::write(&f, b"durable").unwrap();
+        assert!(
+            file_durable(&f).is_ok(),
+            "an existing file must open read+write and fsync cleanly"
+        );
+        assert!(
+            file_durable(&td.path().join("absent.bin")).is_err(),
+            "a missing file must surface the open failure as Err"
+        );
+    }
+
+    /// `dir` is best-effort: it must return normally for a real directory
+    /// (POSIX fsyncs it, Windows no-ops) and must swallow — never panic on —
+    /// a missing directory.
+    #[test]
+    fn dir_is_best_effort_never_panics() {
+        let td = tempfile::tempdir().unwrap();
+        dir(td.path());
+        dir(&td.path().join("does-not-exist"));
+    }
+}

src/io/fsync/posix.rs

@@ -0,0 +1,18 @@
+//! POSIX directory-fsync. Active on unix and any non-Windows fallback target
+//! (BSD, illumos, …) — all share the same `File::open(dir).sync_all()`
+//! semantics. The Windows no-op lives in the sibling `windows` module.
+
+use std::path::Path;
+
+pub(super) fn fsync_dir(dir: &Path) {
+    match std::fs::File::open(dir) {
+        Ok(f) => {
+            if let Err(e) = f.sync_all() {
+                tracing::warn!(path = %dir.display(), error = %e, "failed to fsync directory");
+            }
+        }
+        Err(e) => {
+            tracing::warn!(path = %dir.display(), error = %e, "could not open directory to fsync");
+        }
+    }
+}

src/io/fsync/windows.rs

@@ -0,0 +1,13 @@
+//! Windows directory-fsync: a no-op.
+//!
+//! Directory fsync is a POSIX concept. std cannot open a directory as a `File`
+//! on Windows (it does not set `FILE_FLAG_BACKUP_SEMANTICS`), so the POSIX impl
+//! could only ever fail the open and log a spurious warning on every marker /
+//! mapfile write. NTFS/ReFS commit a rename's directory entry without an
+//! explicit directory flush, so skipping it here is correct — not a durability
+//! regression. (File-content durability is handled platform-uniformly by
+//! [`super::file_durable`].)
+
+use std::path::Path;
+
+pub(super) fn fsync_dir(_dir: &Path) {}

src/io/mod.rs

@@ -18,18 +18,19 @@
 //! consumed window so an 85 GB streaming ISO read doesn't fill the
 //! page cache and starve the concurrent MKV write.
 //!
-//! `Pipeline` + `Sink` (0.18) is the generic producer/consumer primitive
+//! `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_channel` is a byte-sized producer/consumer channel for the
-//! mux pipeline, sized to absorb worst-case input read stalls (see
-//! `freemkv-private/memory/project_buffering_architecture.md`).
+//! `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_channel;
 pub mod byte_prefetcher;
 pub mod file_sector_source;
+pub mod fsync;
 pub mod sink;
 mod writeback;
 mod writeback_file;
@@ -41,8 +42,6 @@ pub mod pipeline;
 
 pub(crate) use writeback_file::WritebackFile;
 
-// Re-exports for the 0.18 redesign. Sweep, patch, and mux are all
-// wired up (disc/sweep.rs, disc/patch.rs, autorip's ripper/mux.rs).
 pub use pipeline::{
     DEFAULT_PIPELINE_DEPTH, Flow, Pipeline, READ_PIPELINE_DEPTH, Sink, WRITE_PIPELINE_DEPTH,
     WRITE_THROUGH_DEPTH,

src/io/sink/local_file.rs

@@ -12,14 +12,18 @@
 //! size patch, Cues index, segment header backpatch) to land on the
 //! right offset.
 //!
-//! `RandomAccessSink` is satisfied via the blanket impl in
-//! [`super::mod`]; no explicit impl needed here.
+//! [`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;
 
@@ -80,13 +84,26 @@ impl LocalFileSink {
     /// 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).
-    #[allow(dead_code)] // exposed for parity with WritebackFile::sync_all
+    /// [`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)
@@ -159,4 +176,58 @@ mod tests {
         let bytes = std::fs::read(&p).unwrap();
         assert_eq!(&bytes[..], b"hint-ok");
     }
+
+    // ── Added hardening tests ───────────────────────────────────────
+
+    /// `create` must TRUNCATE an existing file (OpenOptions
+    /// `.truncate(true)`, lines 52-58). Pre-seed a long file, recreate
+    /// it via the sink, write a shorter payload — the old tail must be
+    /// gone. Mutation: dropping `.truncate(true)` would leave the stale
+    /// tail and the length assert fails.
+    #[test]
+    fn create_truncates_existing_file() {
+        let dir = tempfile::tempdir().unwrap();
+        let p = dir.path().join("trunc.bin");
+        std::fs::write(&p, vec![0xFFu8; 4096]).unwrap();
+        let mut s = LocalFileSink::create(&p).unwrap();
+        s.write_all(b"short").unwrap();
+        s.sync_all().unwrap();
+        drop(s);
+        let bytes = std::fs::read(&p).unwrap();
+        assert_eq!(
+            bytes.len(),
+            5,
+            "create must truncate the pre-existing 4096 bytes"
+        );
+        assert_eq!(&bytes, b"short");
+    }
+
+    /// Seek must flush the BufWriter FIRST so buffered bytes land at
+    /// their intended offset, not the post-seek one (lines 121-128, and
+    /// the module doc's silent-corruption warning). We write into the
+    /// buffer (no explicit flush), seek backward, write again, and
+    /// confirm the first write stayed at offset 0. Mutation: removing
+    /// the `self.inner.flush()?` in `seek` would flush the first 4
+    /// bytes at the seeked offset, corrupting the file.
+    #[test]
+    fn seek_flushes_buffer_before_moving() {
+        let dir = tempfile::tempdir().unwrap();
+        let p = dir.path().join("seek-flush.bin");
+        let mut s = LocalFileSink::create(&p).unwrap();
+        // These bytes sit in the 4 MiB BufWriter, unflushed.
+        s.write_all(b"HEAD").unwrap();
+        // Seek forward to offset 10; the buffered HEAD must be flushed
+        // to offset 0 BEFORE the position moves.
+        s.seek(SeekFrom::Start(10)).unwrap();
+        s.write_all(b"TAIL").unwrap();
+        s.sync_all().unwrap();
+        drop(s);
+        let bytes = std::fs::read(&p).unwrap();
+        assert_eq!(
+            &bytes[0..4],
+            b"HEAD",
+            "buffered head landed at the wrong offset"
+        );
+        assert_eq!(&bytes[10..14], b"TAIL");
+    }
 }

src/io/sink/mod.rs

@@ -20,9 +20,6 @@
 //! 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.
-//!
-//! See `freemkv-private/memory/project_buffering_architecture.md` for
-//! the full design and the source/sink matrix.
 
 use std::io::{Seek, Write};
 
@@ -38,14 +35,22 @@ pub use socket::{SocketSink, UdpSocketSink};
 /// 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 on a
-/// buffered writer, etc.). The default impl is a no-op; concrete
-/// implementations that need explicit shutdown can override it but the
-/// blanket impl below keeps it optional for adapter types like
-/// `&mut File`.
+/// 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<()> {
-        Ok(())
+        self.flush()
     }
 }
 
@@ -54,15 +59,6 @@ pub trait SequentialSink: Write + Send {
 /// random-access sink is always usable as a sequential sink.
 pub trait RandomAccessSink: SequentialSink + Seek {}
 
-// Blanket impls so any `Write + Send` type acts as a `SequentialSink`
-// (with default `finish`), and any sink that also impls `Seek` is
-// automatically a `RandomAccessSink`. Keeps call-site ergonomics simple
-// — `&mut File`, `LocalFileSink`, `WritebackFile`, `BufWriter<File>`,
-// and `Cursor<Vec<u8>>` all satisfy the right trait without per-type
-// boilerplate.
-impl<T: Write + Send + ?Sized> SequentialSink for T {}
-impl<T: SequentialSink + Seek + ?Sized> RandomAccessSink for T {}
-
 /// Pick the right `RandomAccessSink` impl for `dest` based on its
 /// filesystem type.
 ///
@@ -80,18 +76,16 @@ impl<T: SequentialSink + Seek + ?Sized> RandomAccessSink for T {}
 ///
 /// 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(
+// Not yet wired into mux::resolve (follow-up commit). Kept `pub(crate)` until
+// then so an unfinished signature isn't frozen into the public 1.0 API.
+#[allow(dead_code)]
+pub(crate) fn open_for_mkv(
     dest: &std::path::Path,
     size_hint: Option<u64>,
 ) -> std::io::Result<Box<dyn RandomAccessSink>> {
-    #[cfg(not(target_os = "linux"))]
-    use crate::platform::fs_type::detect;
-    #[cfg(target_os = "linux")]
-    use crate::platform::fs_type::{FsType, detect};
-
     #[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)?,
@@ -100,12 +94,13 @@ pub fn open_for_mkv(
             return Ok(Box::new(wf));
         }
     }
-    // Silence the unused-binding warning on non-Linux where the only
-    // branch above is cfg-gated out.
+    // 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 _ = detect(dest);
-    }
+    let _ = crate::platform::fs_type::detect;
 
     let sink = match size_hint {
         Some(n) => LocalFileSink::with_size_hint(dest, n)?,
@@ -117,32 +112,25 @@ pub fn open_for_mkv(
 #[cfg(test)]
 mod tests {
     use super::*;
-    use std::fs::File;
 
-    // Type-level assertion: the blanket impls cover the shapes we care
-    // about. These functions never run; they just have to type-check.
-    fn _assert_file_is_sequential(_: &mut dyn SequentialSink) {}
-    fn _assert_file_is_random_access(_: &mut dyn RandomAccessSink) {}
+    // 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 blanket_impls_cover_file_and_localfilesink() {
-        // `File` directly via blanket impls.
+    fn concrete_sinks_satisfy_traits() {
         let dir = tempfile::tempdir().unwrap();
-        let mut f = File::create(dir.path().join("a.bin")).unwrap();
-        _assert_file_is_sequential(&mut f);
-        _assert_file_is_random_access(&mut f);
 
-        // `LocalFileSink` ditto.
+        // `LocalFileSink` is a random-access (and thus sequential) sink.
         let mut s = LocalFileSink::create(&dir.path().join("b.bin")).unwrap();
-        _assert_file_is_sequential(&mut s);
-        _assert_file_is_random_access(&mut s);
+        _assert_is_sequential(&mut s);
+        _assert_is_random_access(&mut s);
 
-        // `WritebackFile` — confirms the Phase 1 type still satisfies
-        // the trait via the blanket impl without needing an explicit
-        // `impl RandomAccessSink for WritebackFile {}`.
+        // `WritebackFile` ditto, via its explicit per-type impls.
         let mut wf = crate::io::WritebackFile::create(&dir.path().join("c.bin")).unwrap();
-        _assert_file_is_sequential(&mut wf);
-        _assert_file_is_random_access(&mut wf);
+        _assert_is_sequential(&mut wf);
+        _assert_is_random_access(&mut wf);
     }
 
     #[test]
@@ -158,4 +146,94 @@ mod tests {
         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");
+    }
+
+    // ── Added hardening tests ───────────────────────────────────────
+
+    use std::io::{self, Write};
+    use std::sync::Arc;
+    use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+
+    /// A minimal `SequentialSink` that does NOT override `finish`, so it
+    /// exercises the trait's DEFAULT impl (lines 51-55), which must call
+    /// `Write::flush`. We record whether flush ran. This pins the
+    /// documented contract that the default `finish` is "correct for an
+    /// unbuffered destination" by flushing. Mutation: changing the
+    /// default `finish` body from `self.flush()` to `Ok(())` would set
+    /// `flushed=false` and fail.
+    struct FlushTracker {
+        flushed: Arc<AtomicBool>,
+        bytes: Arc<AtomicUsize>,
+    }
+    impl Write for FlushTracker {
+        fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+            self.bytes.fetch_add(buf.len(), Ordering::SeqCst);
+            Ok(buf.len())
+        }
+        fn flush(&mut self) -> io::Result<()> {
+            self.flushed.store(true, Ordering::SeqCst);
+            Ok(())
+        }
+    }
+    // Uses the DEFAULT finish() — deliberately no override.
+    impl SequentialSink for FlushTracker {}
+
+    #[test]
+    fn default_finish_flushes() {
+        let flushed = Arc::new(AtomicBool::new(false));
+        let bytes = Arc::new(AtomicUsize::new(0));
+        let mut sink = FlushTracker {
+            flushed: flushed.clone(),
+            bytes: bytes.clone(),
+        };
+        sink.write_all(b"abc").unwrap();
+        assert!(
+            !flushed.load(Ordering::SeqCst),
+            "flush should not run before finish"
+        );
+        sink.finish().unwrap();
+        assert!(
+            flushed.load(Ordering::SeqCst),
+            "default SequentialSink::finish must call Write::flush"
+        );
+        assert_eq!(bytes.load(Ordering::SeqCst), 3);
+    }
+
+    /// `open_for_mkv` with `None` size hint must still produce a working
+    /// random-access sink (the `match size_hint { None => ... }` arm,
+    /// lines 103-106). Round-trip a seek-back patch through it to prove
+    /// both Write and Seek dispatch. Mutation: if the None arm returned
+    /// a sequential-only sink the seek would not compile / would fail.
+    #[test]
+    fn open_for_mkv_without_size_hint_is_random_access() {
+        use std::io::{Seek, SeekFrom};
+        let dir = tempfile::tempdir().unwrap();
+        let p = dir.path().join("nohint.bin");
+        let mut sink = open_for_mkv(&p, None).unwrap();
+        sink.write_all(b"AAAABBBB").unwrap();
+        sink.seek(SeekFrom::Start(4)).unwrap();
+        sink.write_all(b"CCCC").unwrap();
+        sink.finish().unwrap();
+        drop(sink);
+        assert_eq!(std::fs::read(&p).unwrap(), b"AAAACCCC");
+    }
 }

src/io/sink/preallocate/linux.rs

@@ -5,13 +5,16 @@
 //! the file naturally.
 
 use std::fs::File;
-#[cfg(unix)]
 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, size_bytes as i64) };
+    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={}",

src/io/sink/preallocate/macos.rs

@@ -1,7 +1,8 @@
 //! macOS `F_PREALLOCATE` extent reservation.
 //!
-//! `fcntl(F_PREALLOCATE)` with `F_ALLOCATECONTIG` first (try for a
-//! contiguous run) and fall back to `F_ALLOCATEALL` (non-contig OK).
+//! `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;
@@ -13,16 +14,24 @@ use crate::io::platform_macos::{
 
 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 {
-        fst_flags: F_ALLOCATECONTIG,
+        // 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: size_bytes as libc::off_t,
+        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.
+        // Fall back to non-contiguous only.
         store.fst_flags = F_ALLOCATEALL;
         rc = unsafe { libc::fcntl(fd, F_PREALLOCATE, &mut store as *mut Fstore) };
     }

src/io/sink/socket.rs

@@ -11,16 +11,21 @@
 //! conventional choice). `finish()` is a no-op; UDP has no end-of-stream
 //! marker.
 //!
-//! Both types satisfy [`SequentialSink`] via the blanket impl in
-//! `super::mod`. Neither implements `Seek`, so neither satisfies
-//! [`RandomAccessSink`] — using one with `MkvMux` is a compile error,
-//! which is the design intent.
+//! 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, TcpStream, ToSocketAddrs, UdpSocket};
+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
@@ -47,15 +52,17 @@ impl SocketSink {
     /// 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: `"10.0.0.1:1234"`,
+    /// `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.
-        stream.set_nodelay(true)?;
+        // 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)?;
         }
@@ -76,17 +83,12 @@ impl Write for SocketSink {
     }
 }
 
-impl SocketSink {
+impl SequentialSink for SocketSink {
     /// Drain the BufWriter and `shutdown(Write)` the underlying socket
-    /// so the peer sees a clean EOF.
-    ///
-    /// Note: [`SequentialSink::finish`](super::SequentialSink::finish)'s
-    /// blanket-impl default is a no-op. Trait-object call sites that
-    /// need socket shutdown should call this inherent method directly
-    /// before dropping the sink, or hold the concrete `SocketSink` type
-    /// (typical pattern: each muxer's `finish()` calls the appropriate
-    /// inherent close method on its captured concrete sink).
-    pub fn finish(&mut self) -> io::Result<()> {
+    /// 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
@@ -117,10 +119,22 @@ impl UdpSocketSink {
     ///
     /// `sndbuf_bytes`, when present, is a hint to `SO_SNDBUF`.
     pub fn connect<A: ToSocketAddrs>(peer: A, sndbuf_bytes: Option<usize>) -> io::Result<Self> {
-        // Bind to all-zeros / any port. The kernel picks an ephemeral
-        // source port and the source IP at first send.
-        let socket = UdpSocket::bind("0.0.0.0:0")?;
-        socket.connect(peer)?;
+        // 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)?;
         }
@@ -140,10 +154,12 @@ impl Write for UdpSocketSink {
     }
 }
 
-impl UdpSocketSink {
-    /// No-op — UDP has no end-of-stream marker. Provided for parity
-    /// with [`SocketSink::finish`] so call sites can treat them uniformly.
-    pub fn finish(&mut self) -> io::Result<()> {
+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(())
     }
 }
@@ -275,4 +291,86 @@ mod tests {
         let n2 = receiver.recv(&mut buf).unwrap();
         assert_eq!(&buf[..n2], &[9, 9, 9]);
     }
+
+    // ── Added hardening tests ───────────────────────────────────────
+
+    /// `SocketSink::finish` must signal a clean EOF to the peer via
+    /// `shutdown(Write)` (lines 91-97). The receiving side's
+    /// `read_to_end` only returns when it observes that EOF — if
+    /// `finish` merely flushed without the shutdown, `read_to_end`
+    /// would block forever (the socket stays half-open). We assert the
+    /// receiver completes promptly AND sees the buffered tail.
+    /// Mutation: replacing the `shutdown(Write)` line with `Ok(())`
+    /// makes the accept thread hang and the join times out.
+    #[test]
+    fn finish_signals_eof_to_peer() {
+        use std::sync::mpsc;
+        use std::time::Duration;
+        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
+        let addr = listener.local_addr().unwrap();
+        let (tx, rx) = mpsc::channel();
+        thread::spawn(move || {
+            let (mut sock, _) = listener.accept().unwrap();
+            let mut buf = Vec::new();
+            // Returns only when the peer half-closes (shutdown Write).
+            sock.read_to_end(&mut buf).unwrap();
+            let _ = tx.send(buf);
+        });
+
+        let mut sink = SocketSink::connect(addr, None).unwrap();
+        sink.write_all(b"unflushed-tail").unwrap();
+        sink.finish().unwrap();
+
+        // read_to_end must complete because finish() shut down writes.
+        let received = rx
+            .recv_timeout(Duration::from_secs(3))
+            .expect("peer never saw EOF — finish() did not shutdown(Write)");
+        assert_eq!(received, b"unflushed-tail");
+    }
+
+    /// UDP `write` must emit ONE datagram per call carrying exactly the
+    /// bytes passed — no buffering, no coalescing (doc lines 100-108).
+    /// Two writes of different lengths must arrive as two separate
+    /// datagrams of those exact lengths, in order. Mutation: adding a
+    /// BufWriter to UdpSocketSink (the doc explicitly forbids it) would
+    /// merge these into one datagram and the second `recv` would time
+    /// out.
+    #[test]
+    fn udp_write_is_one_datagram_per_call() {
+        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, None).unwrap();
+
+        // Distinct lengths so a merge would be detectable.
+        let n_a = sink.write(&[0xAA; 10]).unwrap();
+        let n_b = sink.write(&[0xBB; 20]).unwrap();
+        assert_eq!(n_a, 10);
+        assert_eq!(n_b, 20);
+
+        let mut buf = [0u8; 256];
+        let first = receiver.recv(&mut buf).unwrap();
+        assert_eq!(first, 10, "first datagram must be exactly 10 bytes");
+        assert!(buf[..first].iter().all(|&b| b == 0xAA));
+        let second = receiver.recv(&mut buf).unwrap();
+        assert_eq!(second, 20, "second datagram must be exactly 20 bytes");
+        assert!(buf[..second].iter().all(|&b| b == 0xBB));
+    }
+
+    /// UDP `finish` is a documented no-op (lines 157-165): there is no
+    /// EOF marker for UDP. Calling it must not error and must not
+    /// affect prior datagrams. Mutation: if `finish` tried to
+    /// `shutdown` the UDP socket it could error or close it
+    /// prematurely; here it must just return Ok.
+    #[test]
+    fn udp_finish_is_noop_ok() {
+        let receiver = UdpSocket::bind("127.0.0.1:0").unwrap();
+        let addr = receiver.local_addr().unwrap();
+        let mut sink = UdpSocketSink::connect(addr, None).unwrap();
+        assert!(sink.finish().is_ok());
+        // A second finish is equally harmless.
+        assert!(sink.finish().is_ok());
+    }
 }

src/io/writeback/linux.rs

@@ -54,7 +54,6 @@
 use std::collections::VecDeque;
 use std::fs::File;
 use std::os::unix::io::{AsRawFd, RawFd};
-use std::sync::Arc;
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::time::{Duration, Instant};
 
@@ -79,6 +78,15 @@ pub(crate) struct WritebackPipeline {
     /// `WritebackFile` and never exposed outside that wrapper, which
     /// is what keeps the alias sound.
     fd: RawFd,
+    /// An owned clone of the file descriptor, held so that any
+    /// leaked WAIT_AFTER worker thread retains a valid reference to
+    /// the underlying file description for the duration of its
+    /// syscall — even if the original `WritebackFile` is closed first
+    /// and the OS reuses its fd number. `None` only when `try_clone`
+    /// failed at construction (rare); the pipeline falls back to the
+    /// pre-clone `fd` integer in that case, which carries the original
+    /// fd-reuse risk but is no worse than the previous behaviour.
+    wait_file: Option<File>,
     chunk_bytes: u64,
     last_flush_pos: u64,
     pending: Option<(u64, u64)>,
@@ -94,13 +102,11 @@ pub(crate) struct WritebackPipeline {
     is_nfs: bool,
     /// Set the first time WAIT_AFTER exceeds [`WAIT_AFTER_TIMEOUT`].
     /// Once set, behaviour matches the NFS path for the rest of the
-    /// pipeline's life. Wrapped in `Arc` only because both this
-    /// struct and the spawned worker thread (which itself doesn't
-    /// touch the flag) share-via-fd patterns might one day need it;
-    /// today it's effectively a single-owner cell — the `Arc` shape
-    /// keeps the door open for moving the read side into a worker
-    /// without re-plumbing types.
-    degraded: Arc<AtomicBool>,
+    /// 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 {
@@ -111,6 +117,19 @@ impl WritebackPipeline {
     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);
+        // Clone the fd so any leaked WAIT_AFTER worker thread keeps the
+        // file description alive. Log but continue on clone failure.
+        let wait_file = match file.try_clone() {
+            Ok(f) => Some(f),
+            Err(e) => {
+                tracing::warn!(
+                    target: "mux",
+                    "WritebackPipeline fd={fd}: try_clone failed ({e}), WAIT_AFTER workers \
+                     will use raw fd (fd-reuse risk on timeout)"
+                );
+                None
+            }
+        };
         tracing::info!(
             target: "mux",
             "WritebackPipeline fd={fd} is_nfs={is_nfs} chunk_bytes={chunk_bytes} strategy={}",
@@ -118,13 +137,14 @@ impl WritebackPipeline {
         );
         Self {
             fd,
+            wait_file,
             chunk_bytes,
             last_flush_pos: start_pos,
             pending: None,
             wait_after_window: VecDeque::with_capacity(ADAPTIVE_WINDOW),
             chunk_count: 0,
             is_nfs,
-            degraded: Arc::new(AtomicBool::new(false)),
+            degraded: AtomicBool::new(false),
         }
     }
 
@@ -136,6 +156,22 @@ impl WritebackPipeline {
         self.is_nfs || self.degraded.load(Ordering::Relaxed)
     }
 
+    /// Produce a fresh per-call `File` clone for the WAIT_AFTER worker.
+    ///
+    /// Each call to `wait_after_with_timeout` needs its own owned clone
+    /// so the worker thread keeps the file description alive for the
+    /// duration of the syscall. We clone from `self.wait_file` (itself a
+    /// clone taken at construction) rather than from the original file.
+    ///
+    /// Returns `None` only if `wait_file` is `None` (construction
+    /// try_clone failed) or if the second-level try_clone fails — both
+    /// rare; the fallback raw-fd path in `wait_after_with_timeout`
+    /// handles that case.
+    #[inline]
+    fn clone_for_worker(&self) -> Option<File> {
+        self.wait_file.as_ref().and_then(|f| f.try_clone().ok())
+    }
+
     /// 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.
@@ -143,16 +179,35 @@ impl WritebackPipeline {
         if pos < self.last_flush_pos.saturating_add(self.chunk_bytes) {
             return;
         }
-        let chunk_off = self.last_flush_pos as i64;
-        let chunk_len = (pos - self.last_flush_pos) as i64;
+        // 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, chunk_len, libc::SYNC_FILE_RANGE_WRITE);
+        let kickoff_rc = unsafe {
+            libc::sync_file_range(
+                self.fd,
+                chunk_off as i64,
+                chunk_len as i64,
+                libc::SYNC_FILE_RANGE_WRITE,
+            )
+        };
+        if kickoff_rc != 0 {
+            // Non-fatal: the async write-out hint failed, but the data is
+            // still in the page cache and will be flushed by later fsync /
+            // kernel writeback. Surface it for diagnosability.
+            tracing::warn!(
+                target: "freemkv::io",
+                errno = std::io::Error::last_os_error().raw_os_error().unwrap_or(0),
+                "sync_file_range(WRITE) kickoff failed"
+            );
         }
         if let Some((prev_off, prev_len)) = self.pending.take() {
             if self.skip_wait() {
@@ -166,7 +221,8 @@ impl WritebackPipeline {
                 // 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) {
+                match wait_after_with_timeout(self.clone_for_worker(), self.fd, prev_off, prev_len)
+                {
                     Some(ms) => {
                         wait_ms = ms;
                         let t_fadv = Instant::now();
@@ -187,9 +243,16 @@ impl WritebackPipeline {
                         // NOT call DONTNEED — if WAIT_AFTER hasn't
                         // returned, the pages aren't safely flushed.
                         self.degraded.store(true, Ordering::Relaxed);
+                        // Once degraded we skip DONTNEED, so every subsequent
+                        // chunk's pages stay resident until close — the same
+                        // page-cache exposure profile as NFS. Shrink to the
+                        // floor so that exposure window is as small as the NFS
+                        // path keeps it, instead of whatever the adaptive sizing
+                        // had grown chunk_bytes to (up to 256 MiB).
+                        self.chunk_bytes = CHUNK_BYTES_MIN;
                         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)",
+                            "WritebackPipeline WAIT_AFTER timed out after {}s on chunk off={} len={}, marking writeback degraded (subsequent chunks will skip WAIT_AFTER + DONTNEED, chunk_bytes lowered to floor)",
                             WAIT_AFTER_TIMEOUT.as_secs(),
                             prev_off,
                             prev_len
@@ -198,12 +261,12 @@ impl WritebackPipeline {
                 }
             }
         }
-        self.pending = Some((chunk_off as u64, chunk_len as u64));
+        self.pending = Some((chunk_off, chunk_len));
         self.last_flush_pos = pos;
         self.chunk_count += 1;
         tracing::trace!(
             target: "mux",
-            "WritebackPipeline chunk off={} len={} sync_file_range_ms={wait_ms} fadvise_ms={fadvise_ms} chunk_bytes={} skip_wait={}",
+            "WritebackPipeline chunk off={} len={} wait_after_ms={wait_ms} fadvise_ms={fadvise_ms} chunk_bytes={} skip_wait={}",
             chunk_off,
             chunk_len,
             self.chunk_bytes,
@@ -231,10 +294,14 @@ impl WritebackPipeline {
         if self.wait_after_window.len() < ADAPTIVE_WINDOW {
             return;
         }
-        // p95 of 16 samples ≈ sorted[14] (5 % of 16 = 0.8 ≈ 1 above).
+        // 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 = sorted[14];
+        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)
@@ -278,7 +345,7 @@ impl WritebackPipeline {
                 // paths.
                 return;
             }
-            match wait_after_with_timeout(self.fd, prev_off, prev_len) {
+            match wait_after_with_timeout(self.clone_for_worker(), self.fd, prev_off, prev_len) {
                 Some(_ms) => unsafe {
                     libc::posix_fadvise(
                         self.fd,
@@ -321,16 +388,56 @@ fn detect_nfs(fd: RawFd) -> bool {
 /// Run `sync_file_range(WAIT_AFTER)` on a worker thread and wait up
 /// to [`WAIT_AFTER_TIMEOUT`] for it to return. `Some(elapsed_ms)` on
 /// success; `None` on timeout. On timeout the worker thread is
-/// 0.20.6 generalizes the worker-thread + recv_timeout pattern into
-/// [`crate::io::bounded::bounded_syscall`]; this helper now just adapts
-/// the generic primitive to the WAIT_AFTER call shape (returns elapsed_ms
-/// instead of the syscall's `()` return, treats `WorkerLost` as a benign
-/// no-op to match the original semantics).
-fn wait_after_with_timeout(fd: RawFd, off: u64, len: u64) -> Option<u64> {
+/// 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.
+///
+/// ## fd lifetime / fd-reuse safety
+///
+/// `worker_file` is an *owned* `File` (produced by `File::try_clone` at
+/// pipeline construction). It is moved into the worker closure so the
+/// file description stays alive for exactly as long as the worker thread
+/// lives — even if the original `WritebackFile` is closed and the OS
+/// reuses its fd number before the worker's syscall returns.
+///
+/// `fallback_fd` is used only when `worker_file` is `None` (i.e. the
+/// `try_clone` at construction failed). In that case the worker captures
+/// the raw fd integer, which carries the original fd-reuse risk but is
+/// no worse than the pre-fix behaviour.
+fn wait_after_with_timeout(
+    worker_file: Option<File>,
+    fallback_fd: RawFd,
+    off: u64,
+    len: u64,
+) -> Option<u64> {
     let started = Instant::now();
-    match crate::io::bounded::bounded_syscall(None, WAIT_AFTER_TIMEOUT, move || unsafe {
+    let result = if let Some(owned) = worker_file {
+        // Happy path: the closure owns a cloned File that keeps the
+        // file description alive until the worker drops it.
+        crate::io::bounded::bounded_syscall(None, WAIT_AFTER_TIMEOUT, move || unsafe {
+            let fd = owned.as_raw_fd();
             libc::sync_file_range(fd, off as i64, len as i64, libc::SYNC_FILE_RANGE_WAIT_AFTER);
-    }) {
+            // `owned` drops here, closing the cloned fd.
+        })
+    } else {
+        // Fallback: try_clone failed at construction; use the raw fd.
+        // This carries the pre-fix fd-reuse risk on timeout, but is no
+        // regression from the original behaviour.
+        crate::io::bounded::bounded_syscall(None, WAIT_AFTER_TIMEOUT, move || unsafe {
+            libc::sync_file_range(
+                fallback_fd,
+                off as i64,
+                len as i64,
+                libc::SYNC_FILE_RANGE_WAIT_AFTER,
+            );
+        })
+    };
+    match result {
         Ok(()) => Some(started.elapsed().as_millis() as u64),
         Err(crate::io::bounded::BoundedError::Timeout)
         | Err(crate::io::bounded::BoundedError::Halted) => None,
@@ -456,4 +563,64 @@ mod tests {
         assert_eq!(p.chunk_count, before);
         assert!(p.pending.is_none());
     }
+
+    // ── Bug-fix regression tests ────────────────────────────────────────
+
+    /// Regression for the fd-reuse / use-after-close fix. Verifies that
+    /// `WritebackPipeline::new` successfully clones the fd into
+    /// `wait_file` (i.e. `try_clone` doesn't fail for a normal
+    /// tempfile) and that `clone_for_worker` returns `Some` — meaning
+    /// the WAIT_AFTER worker will capture an owned `File` rather than a
+    /// raw fd integer.
+    ///
+    /// A deterministic test for the actual fd-reuse race is not clean to
+    /// write (it would require simultaneously closing the original File
+    /// and re-opening a new one to steal the fd number while the worker
+    /// is mid-syscall, which is inherently racy). This test instead pins
+    /// the structural invariant: on a normal local file, the pipeline
+    /// holds a valid clone and will give the worker an owned File.
+    #[test]
+    fn wait_file_clone_is_present_for_local_tempfile() {
+        let (_f, p) = local_pipeline(32 * 1024 * 1024);
+        assert!(
+            p.wait_file.is_some(),
+            "wait_file must be Some for a normal local tempfile (try_clone should not fail)"
+        );
+        // clone_for_worker must return Some — the worker will get an
+        // owned File, not fall through to the raw-fd fallback.
+        let worker_clone = p.clone_for_worker();
+        assert!(
+            worker_clone.is_some(),
+            "clone_for_worker must return Some when wait_file is Some"
+        );
+    }
+
+    /// Structural: the worker `File` clone returned by `clone_for_worker`
+    /// is a distinct file descriptor (different fd number) that refers to
+    /// the same underlying file. Closing the original tempfile must not
+    /// affect the clone's validity — the OS keeps the file description
+    /// alive until all file descriptors referring to it are closed.
+    ///
+    /// We verify "distinct fd number" and "still usable as a raw fd"
+    /// without actually racing a syscall.
+    #[test]
+    fn worker_clone_has_distinct_fd_from_original() {
+        let f = NamedTempFile::new().expect("tempfile create");
+        let original_fd = f.as_file().as_raw_fd();
+        let pipeline = WritebackPipeline::new(f.as_file(), 0, 32 * 1024 * 1024);
+
+        let clone = pipeline
+            .clone_for_worker()
+            .expect("clone_for_worker returned None");
+        let clone_fd = clone.as_raw_fd();
+
+        // The clone must have a different fd number — it is a separate
+        // open file description (dup'd by try_clone).
+        assert_ne!(
+            clone_fd, original_fd,
+            "worker clone must have a distinct fd number from the original"
+        );
+        // The clone fd must be valid (non-negative on Unix).
+        assert!(clone_fd >= 0, "clone fd must be non-negative");
+    }
 }

src/io/writeback_file/linux.rs

@@ -19,14 +19,10 @@ use std::time::Duration;
 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.
-    let rc = unsafe {
-        libc::fallocate(
-            file.as_raw_fd(),
-            libc::FALLOC_FL_KEEP_SIZE,
-            0,
-            size_bytes as i64,
-        )
-    };
+    // 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={}",
@@ -34,17 +30,46 @@ pub(super) fn preallocate(file: &File, size_bytes: u64) {
     );
 }
 
-/// Run `fsync` on `file` with a 60 s deadline. On timeout we log loudly
-/// 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) defeats `/api/stop`.
+/// 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.
+///
+/// ## fd-reuse safety
+///
+/// The `fsync` runs on a bounded worker thread that may be leaked on
+/// timeout. To avoid the leaked worker's syscall hitting a recycled fd
+/// number after the original `File` is closed, we `try_clone` an owned
+/// `File` and move it into the closure. The clone keeps the underlying
+/// file description alive for as long as the worker thread lives.
+/// On `try_clone` failure (rare) we fall back to the raw fd integer —
+/// no worse than the previous behaviour.
 pub(super) fn durable_sync(file: &File) -> io::Result<()> {
+    // Clone so a leaked worker thread retains a valid fd even after the
+    // original File is closed and its fd number is reused.
+    let owned = match file.try_clone() {
+        Ok(f) => Some(f),
+        Err(e) => {
             let fd = file.as_raw_fd();
+            tracing::warn!(
+                target: "mux",
+                "WritebackFile::sync_all fd={fd}: try_clone failed ({e}), fsync worker will use raw fd (fd-reuse risk on timeout)"
+            );
+            None
+        }
+    };
+    let fallback_fd = file.as_raw_fd();
     match crate::io::bounded::bounded_syscall(
         None,
         Duration::from_secs(60),
         move || -> io::Result<()> {
+            let fd = owned.as_ref().map(|f| f.as_raw_fd()).unwrap_or(fallback_fd);
             let rc = unsafe { libc::fsync(fd) };
+            // `owned` (if Some) drops here, releasing the cloned fd.
             if rc == 0 {
                 Ok(())
             } else {
@@ -60,7 +85,61 @@ pub(super) fn durable_sync(file: &File) -> io::Result<()> {
             );
             Ok(())
         }
-        Err(crate::io::bounded::BoundedError::Halted) => Ok(()),
-        Err(crate::io::bounded::BoundedError::WorkerLost) => 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(())
+        }
+    }
+}
+
+#[cfg(test)]
+#[cfg(target_os = "linux")]
+mod tests {
+    use super::*;
+    use tempfile::NamedTempFile;
+
+    /// Regression for the fd-reuse / use-after-close fix in `durable_sync`.
+    ///
+    /// Verifies the structural invariant: `try_clone` succeeds for a normal
+    /// local tempfile, and the cloned `File` has a distinct fd number from
+    /// the original. This pins the property that a leaked fsync worker thread
+    /// captures an owned `File` (and thus keeps the file description alive)
+    /// rather than a bare fd integer that can be reused after the original
+    /// `File` closes.
+    ///
+    /// The actual fd-reuse race is non-deterministic and not cleanly
+    /// testable without coordinating a simultaneous close + re-open on
+    /// another thread. A structural test is the accepted substitute.
+    #[test]
+    fn durable_sync_worker_uses_owned_clone_with_distinct_fd() {
+        let f = NamedTempFile::new().expect("tempfile create");
+        let original_fd = f.as_file().as_raw_fd();
+
+        // try_clone must succeed for a normal local file.
+        let owned = f
+            .as_file()
+            .try_clone()
+            .expect("try_clone must succeed for a local tempfile");
+        let clone_fd = owned.as_raw_fd();
+
+        // The clone must be a distinct fd (dup'd, not aliased).
+        assert_ne!(
+            clone_fd, original_fd,
+            "owned clone must have a distinct fd number — not an alias of the original"
+        );
+        assert!(clone_fd >= 0, "clone fd must be a valid non-negative fd");
+
+        // durable_sync must complete without error on the local tempfile.
+        durable_sync(f.as_file()).expect("durable_sync must return Ok on a local tempfile");
     }
 }

src/io/writeback_file/macos.rs

@@ -1,10 +1,12 @@
 //! macOS platform impl for [`super::WritebackFile`].
 //!
 //! - `preallocate`: `fcntl(F_PREALLOCATE)` — macOS's fallocate-equiv.
-//!   Reserves a contiguous extent when possible, falling back to a
-//!   non-contiguous reservation if the FS can't satisfy it. Reported
-//!   file size is unchanged (`F_ALLOCATEALL` is not set, so allocation
-//!   is "best effort up to length"; growth happens via writes).
+//!   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
@@ -25,11 +27,14 @@ use crate::io::platform_macos::{
 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: size_bytes as libc::off_t,
+        fst_length: len,
         fst_bytesalloc: 0,
     };
     // First attempt: contiguous.
@@ -47,28 +52,54 @@ pub(super) fn preallocate(file: &File, size_bytes: u64) {
     );
 }
 
+/// ## fd-reuse safety
+///
+/// The F_FULLFSYNC / fsync runs on a bounded worker thread that may be
+/// leaked on timeout. To avoid the leaked worker's syscall hitting a
+/// recycled fd number after the original `File` is closed, we
+/// `try_clone` an owned `File` and move it into the closure. The clone
+/// keeps the underlying file description alive for as long as the worker
+/// thread lives. On `try_clone` failure (rare) we fall back to the raw
+/// fd integer — no worse than the previous behaviour.
 pub(super) fn durable_sync(file: &File) -> io::Result<()> {
+    // Clone so a leaked worker thread retains a valid fd even after the
+    // original File is closed and its fd number is reused.
+    let owned = match file.try_clone() {
+        Ok(f) => Some(f),
+        Err(e) => {
             let fd = file.as_raw_fd();
+            tracing::warn!(
+                target: "mux",
+                "WritebackFile::sync_all fd={fd}: try_clone failed ({e}), F_FULLFSYNC worker will use raw fd (fd-reuse risk on timeout)"
+            );
+            None
+        }
+    };
+    let fallback_fd = file.as_raw_fd();
     match crate::io::bounded::bounded_syscall(
         None,
         Duration::from_secs(60),
         move || -> io::Result<()> {
+            let fd = owned.as_ref().map(|f| f.as_raw_fd()).unwrap_or(fallback_fd);
             // 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 {
+                // `owned` (if Some) drops here, releasing the cloned fd.
                 return Ok(());
             }
             let err = io::Error::last_os_error();
             if err.raw_os_error() == Some(libc::ENOTSUP) {
                 let rc = unsafe { libc::fsync(fd) };
+                // `owned` drops here.
                 if rc == 0 {
                     Ok(())
                 } else {
                     Err(io::Error::last_os_error())
                 }
             } else {
+                // `owned` drops here.
                 Err(err)
             }
         },
@@ -85,3 +116,44 @@ pub(super) fn durable_sync(file: &File) -> io::Result<()> {
         Err(crate::io::bounded::BoundedError::WorkerLost) => Ok(()),
     }
 }
+
+#[cfg(test)]
+#[cfg(target_os = "macos")]
+mod tests {
+    use super::*;
+    use tempfile::NamedTempFile;
+
+    /// Regression for the fd-reuse / use-after-close fix in `durable_sync`.
+    ///
+    /// Verifies the structural invariant: `try_clone` succeeds for a normal
+    /// local tempfile, and the cloned `File` has a distinct fd number from
+    /// the original. This pins the property that a leaked F_FULLFSYNC/fsync
+    /// worker thread captures an owned `File` (keeping the file description
+    /// alive) rather than a bare fd integer that can be reused after the
+    /// original `File` closes.
+    ///
+    /// The actual fd-reuse race is non-deterministic; a structural test is
+    /// the accepted substitute.
+    #[test]
+    fn durable_sync_worker_uses_owned_clone_with_distinct_fd() {
+        let f = NamedTempFile::new().expect("tempfile create");
+        let original_fd = f.as_file().as_raw_fd();
+
+        // try_clone must succeed for a normal local file.
+        let owned = f
+            .as_file()
+            .try_clone()
+            .expect("try_clone must succeed for a local tempfile");
+        let clone_fd = owned.as_raw_fd();
+
+        // The clone must be a distinct fd (dup'd, not aliased).
+        assert_ne!(
+            clone_fd, original_fd,
+            "owned clone must have a distinct fd number — not an alias of the original"
+        );
+        assert!(clone_fd >= 0, "clone fd must be a valid non-negative fd");
+
+        // durable_sync must complete without error on the local tempfile.
+        durable_sync(f.as_file()).expect("durable_sync must return Ok on a local tempfile");
+    }
+}