0.28.0: version bump (keydb decoupling)

- mux input(): propagate a failed decrypt_with rather than muxing an
  undecryptable stream silently (review M6).
- Scrub synthetic but key-SHAPED hex (HOST_PRIV_KEY/DEVICE_KEY/disc-entry) from
  the keydb parser tests to obvious zero/repeated-byte placeholders. No real or
  real-looking key material in code.

.gitignore

@@ -4,3 +4,7 @@ Cargo.lock
 *.swo
 .DS_Store
 .cargo/
+.claude/worktrees/
+
+# session scratch — never track (may contain RE breadcrumbs)
+scratch/

CHANGELOG.md

@@ -1,5 +1,425 @@
 # Changelog
 
+## 0.27.3 (2026-06-04)
+
+### Added
+
+- **The mapfile now persists resolved AACS unit keys, not just the Volume ID.**
+  A keyed disc writes its decrypted unit keys as `# freemkv-uk: <cps>:<hex>`
+  comment headers; an unresolved disc writes only the `# freemkv-vid:` marker.
+  The two are **mutually exclusive** (`Mapfile::set_unit_keys` clears the VID):
+  unit keys are the final answer, so a deferred-mux / resume decrypts directly
+  with no key-service round-trip, while the VID alone means "still unresolved —
+  retry the key service." `CopyOptions`/`SweepOptions` gain a `unit_keys` field
+  (written when non-empty, else the VID), and `Disc::inject_unit_keys` applies
+  mapfile-recovered keys to a scanned disc (marking the source `ExternalUk`).
+
+## 0.27.0 (2026-06-03)
+
+### Changed
+
+- **AACS unit-encryption detection now reads the raw MPEG-TS sync bytes
+  instead of header flag bits.** `is_unit_encrypted` is renamed
+  `is_aacs_scrambled`: a unit is encrypted iff its body TS packet sync bytes
+  (`0x47` at offset 4 and every 192 bytes) are not intact — the encrypted
+  body destroys them. The previous check read the TP_extra copy-control bits
+  (byte 0) or TS transport_scrambling_control bits (byte 7), which discs and
+  players do not set reliably. A single predicate now backs both the decrypt
+  gate and out-of-band key validation, so all callers agree on what
+  "encrypted" means. Decryption restores the syncs, so a decrypted unit reads
+  as clear and there is no encryption flag to clear.
+
+## 0.26.1 (2026-05-22)
+
+### Added
+
+- **AACS resolver path 5 — KEYDB unit-keys direct fallback.** When a
+  KEYDB entry for the disc has no VUK field but does have pre-decrypted
+  unit keys, the resolver now consumes those unit keys directly instead
+  of treating the entry as unusable. Covers ~4,572 entries in the
+  public keydb (≈2.5% of the database, heavily skewed toward MKBv76+
+  UHD discs that DVDFab/FindVUK can no longer extract VUKs for).
+  Surfaces as `KeySource::KeyDbUnitKeys`; `AacsState::vuk` and
+  `ResolvedKeys::vuk` are `None` on this path because no VUK exists to
+  return. Partial CPS-unit coverage is rejected so a disc is never
+  half-decrypted.
+
+### Changed
+
+- **AACS resolver path order reordered root-to-leaf.** Paths now run in
+  derivation-strength order: device-key (1) → processing-key (2) →
+  KEYDB-derived from MK+VID (3) → KEYDB VUK direct (4) → KEYDB unit
+  keys direct (5). Previous order was leaf-first (KEYDB hash lookup,
+  then derivation). Resolution runs once per disc, so the few extra
+  milliseconds of MKB walking when a KEYDB VUK would have answered are
+  invisible against the rip itself; the new order matches the AACS
+  derivation hierarchy. `KeySource` enum variants are reordered to
+  match.
+- **`AacsState::vuk` type is now `Option<[u8; 16]>`** (was `[u8; 16]`).
+  Required by path 5, which has no VUK. Public-API break.
+- **`ResolvedKeys::vuk` type is now `Option<[u8; 16]>`** (was
+  `[u8; 16]`). Same rationale.
+
+## 0.25.14 (2026-05-21)
+
+### Changed
+
+- `Drive::is_libredrive_active()` renamed to `Drive::is_raw_read_active()`.
+  Same semantics; old name removed. Mirrored on the internal
+  `PlatformDriver::is_libredrive_active()` trait method (now
+  `is_raw_read_active()`).
+- `Error::AacsLibredriveUnsupported` renamed to
+  `Error::AacsRawReadUnsupported`; the underlying numeric code (E7016)
+  is unchanged. The `E_AACS_LIBREDRIVE_UNSUPPORTED` constant is
+  renamed to `E_AACS_RAW_READ_UNSUPPORTED`.
+
+No behavioural change — purely a rename pass.
+
+## 0.25.13 (2026-05-21)
+
+### Added
+
+- **`DrmScheme` top-level dispatcher.** New `drm` module with a
+  `DrmScheme` enum (`Css`, `Aacs10`, `Aacs20`, `Aacs21`) and a
+  `detect` + `load` pair that uniformly handles all four content
+  protection schemes. Replaces the inlined dispatch in
+  `disc::encrypt::resolve_encryption` and the scattered CSS routing
+  in `disc::mod`. Both CSS call sites now route through the same
+  entry point.
+- **AACS 2.1 Media Key Variant framework.** New `aacs::variants`
+  module implementing the Media Key Variant derivation chain
+  (`Kp + C → Kmp → ⊕KCD → Kpnew → Km → VUK`), Variant-scheme MKB
+  record parsing (record types `0x82` / `0x83`), bit-0x02 SoftKCD
+  and bit-0x04 online-challenge detection with dedicated error
+  variants. Wired into `DrmScheme::Aacs21` but the dispatcher arm
+  is commented out pending validation against a Variant-scheme
+  disc. Per-manufacturer Key Correction Data must be supplied by
+  the integrator; `KEY_CORRECTION_DATA_PLACEHOLDER` is the empty
+  placeholder slot.
+- **`AacsVersion` enum.** Replaces the `aacs2: bool` field on
+  `ContentCertificate`, `UnitKeyFile`, and `ResolvedKeys`.
+  `parse_unit_key_ro` and `parse_content_cert` now take/emit the
+  enum. `resolve_keys` is split into `resolve_keys_v1`,
+  `resolve_keys_v2`, and `resolve_keys_v21` (the last not reachable
+  from the dispatcher today).
+
+### Fixed
+
+- **Libredrive raw-read VID shortcut deleted.** v0.25.11 introduced a
+  `do_handshake` branch that, on libredrive-active drives, skipped the
+  AACS cert handshake and issued `READ_DISC_STRUCTURE` format 0x80
+  with AGID=0 directly. The hypothesis was that unlocked
+  drives would serve VID without auth. Empirical test (BU40N
+  + UHD disc, 2026-05-21) showed the drive returns
+  `0x05 / 0x6F / 0x02` (`ILLEGAL_REQUEST / Copy protection key
+  exchange failure: KEY NOT ESTABLISHED`) to that CDB regardless of
+  drive-unlock state. The AACS spec requires a successful
+  `REPORT_KEY` / `SEND_KEY` exchange to establish an AGID before
+  format 0x80 returns VID; that requirement is enforced by the drive
+  itself and isn't bypassed by libredrive firmware. The shortcut
+  fired for every libredrive-active drive, so v0.25.11 / v0.25.12
+  MOVIE scans were stuck at E7017 instead of progressing to the
+  real wall (no DK walks MKB v77).
+- `Disc::do_handshake` now always routes through `do_handshake_cert`.
+  `Drive::is_libredrive_active()` and the Mt1959 MMkv+LbDr marker
+  detection are kept as informational signals (logged in the
+  `handshake_entry` warn line) but no longer steer the auth path.
+- `read_volume_id_libredrive` deleted (~50 LOC).
+
+The corollary: AACS resolution on HRL-burned drives + UHD discs now
+fails honestly. Either cert auth succeeds (drive unlock may or
+may not bypass the HRL — that's the new empirical question) and we
+hit the actual DK wall (E7018 "No DK that walks this MKB" for v77+
+UHD without a v77+ DK in keydb), or cert auth fails and we surface
+E7015. Both are real verdicts; E7017's previous spurious dispatch
+is gone.
+
+## 0.25.12 (2026-05-21)
+
+No libfreemkv source changes — unified sync bump for autorip's
+`aacs_failure_message` two-line wording rewrite. See the autorip
+v0.25.12 release for details.
+
+## 0.25.11 (2026-05-21)
+
+### Added
+
+- **Libredrive raw-read VID path.** When the Mt1959 unlock response
+  confirms both the active-mode (`MMkv`) and mode-ID (`LbDr`) markers,
+  `Drive::is_libredrive_active()` returns true and `do_handshake`
+  skips the AACS cert dance entirely — VID is retrieved via
+  `READ_DISC_STRUCTURE` format 0x80 with AGID=0, and bus encryption
+  is already off. This is what unblocks UHD ripping on drives whose
+  leaked host cert is on the AACS HRL.
+- New `Error` variants for finer-grained AACS failure reporting:
+  `AacsHostCertRejected` (E7015), `AacsLibredriveUnsupported`
+  (E7016), `AacsVidUnavailable` (E7017), `AacsMkUnavailable`
+  (E7018), `AacsVukNotInKeydb` (E7019). Lets CLIs/UIs render which
+  piece of the AACS chain failed instead of always saying "no keys."
+
+### Fixed
+
+- `validate_processing_key` now matches libaacs `_validate_pk`
+  exactly: XORs `uv` into `mk[12..16]` (was omitted), AES-decrypts
+  `mk_dv` and checks the `01 23 45 67 89 AB CD EF` magic (was
+  AES-encrypt + 12-zero check). Pre-fix, every non-zero-uv
+  processing key was rejected — i.e. essentially every real disc.
+- `mkb_find_cvalues` now prefers record type `0x07` (AACS 2.x) and
+  falls back to `0x05` (AACS 1.0), so the walker handles both
+  generations without an out-of-band version flag.
+- `resolve_keys` short-circuits paths 2/3/4 when VID is the zero
+  sentinel — saves cycles and emits an honest "VID unavailable" log
+  instead of the misleading "all paths failed."
+- AES-CMAC VID verification gains NIST SP 800-38B KAT + round-trip
+  + mutation + all-zero-rejection tests.
+
+### Removed
+
+- **Built-in AACS keys** (added in 0.25.9). `src/aacs/builtin_keys.rs`
+  deleted; `KeyDb::with_builtins`, `KeyDb::load_or_builtins`,
+  `KeyDb::merge_from`, and internal dedup helpers gone. The
+  compiled-in shortcut was a slim convenience that didn't move the
+  hard problem (no v77+ DKs) and added a maintenance surface.
+- **Operator plugin slot** at `~/.config/freemkv/local_keys.cfg`
+  (added in 0.25.9). `local_plugin_path` and `KeyDb::merge_local_plugin`
+  removed. Single source: the main `keydb.cfg`.
+- `KeyDb::load` reverts to the pre-0.25.9 form — read the file or
+  return I/O error; no layering, no fallback.
+- `Disc::scan` reverts to surfacing `KeydbLoad { path: "<no keydb
+  in search paths>" }` for an encrypted disc with no keydb — same
+  sentinel autorip's message switch already handles.
+
+CSS player keys in `src/css/auth.rs` remain compiled in; they're
+1999-era public inputs separate from the AACS pipeline and were
+never part of the 0.25.9 additions.
+
+## 0.25.9 (2026-05-20)
+
+### Fixed
+
+- **MKB record-type identification.** `mkb_find_mk_dv` and `mkb_version`
+  had their record-type constants swapped. The Verify Media Key record
+  is Type 0x81 (AACS 1.0) or Type 0x86 (AACS 2.0/2.1), not 0x10. The
+  Type-and-Version record is Type 0x10, not 0x81. PK and DK derivation
+  paths therefore failed silently on every disc, masking how often the
+  fallback paths could have succeeded. Fixed; mk_dv extracted at
+  offset 4 of the verify record, MKB version read at offset 8 of the
+  Type 0x10 record body. Tests added for both forms.
+
+### Added
+
+- **Built-in AACS keys.** Four device keys (covering MKB v01-v82+) and
+  three processing keys (covering v63-v68) are now compiled into
+  `libfreemkv` directly. DVDs and Blu-rays (AACS 1.0) decrypt with
+  zero external files. Combined with the existing 31 CSS player keys
+  in `css/auth.rs`, the library is self-sufficient for all DVD and
+  AACS 1.0 content.
+- **Operator plugin slot.** `~/.config/freemkv/local_keys.cfg` is
+  loaded automatically (same format as `keydb.cfg`) and layered
+  additively on top of the built-ins and the main keydb.cfg. For
+  operators who derive their own keys, this is the additive surface
+  to drop them into — main keydb.cfg from upstream auto-update stays
+  separate and overwritable.
+- `KeyDb::with_builtins()`, `KeyDb::load_or_builtins()`,
+  `KeyDb::empty()` constructors.
+
+### Changed
+
+- `Disc::scan` no longer errors when keydb.cfg is absent. With
+  built-ins covering DVD/BD, missing keydb is treated as "no UHD
+  keys available" — the AACS 2.0 / UHD code path surfaces a
+  specific error only when the disc actually needs keys that
+  aren't in built-ins, main keydb, or local plugin.
+
+## 0.25.8 (2026-05-20)
+
+### Changed
+
+- Synchronized to autorip 0.25.8. No libfreemkv code changes —
+  unified versioning bump only. autorip 0.25.7 image was DOA
+  (missing +x on the binary); see autorip changelog.
+
+## 0.25.7 (2026-05-20)
+
+### Fixed — BU40N firmware wedge on KEYDB-miss discs
+
+`disc::encrypt::do_handshake` used to fire up to 16 AACS authenticate
+attempts back-to-back with no pause between them. Each attempt is
+5-10 SCSI REPORT_KEY/SEND_KEY exchanges. On a disc whose host cert
+isn't in our KEYDB (or one the drive rejects), that's 80-160 SCSI
+commands hammered at the drive in a few hundred milliseconds — and
+the BU40N (plus most consumer optical drives) responds by entering
+a fast-fail firmware wedge state where every subsequent CDB returns
+`ILLEGAL_REQUEST/INVALID_FIELD_IN_CDB` (sense 0x05/0x24) until the
+drive is physically power-cycled.
+
+Live wedge event 2026-05-20 during a UHD disc scan
+(KEYDB miss) confirmed the diagnosis and motivated this fix.
+
+Defence-in-depth:
+- `MAX_CERT_ATTEMPTS` capped at 3 (was 16). If three different
+  host certs all fail, more won't help — the drive doesn't have a
+  match.
+- 1-second sleep between attempts. Gives the drive's firmware time
+  to recover internal state between auth challenges.
+- Bail immediately on any sense code with sense_key = 0x05
+  (`ILLEGAL_REQUEST`). The drive isn't merely rejecting our cert
+  — it's saying "I won't talk to you anymore" — so trying more
+  certs would deepen the wedge.
+
+## 0.25.6 (2026-05-20)
+
+### Changed
+
+- Synchronized to autorip 0.25.6 release. No behavioural changes.
+
+## 0.25.5 (2026-05-20)
+
+### Changed
+
+- Synchronized to autorip 0.25.5 release. No behavioural changes.
+
+## 0.25.4 (2026-05-20)
+
+### Changed
+
+- Synchronized to autorip 0.25.4 release. No behavioural changes
+  in the library — the v0.25.4 release ships the autorip-side
+  in-container NFS mount option.
+
+## 0.25.3 (2026-05-19)
+
+### Changed
+
+- Synchronized to autorip 0.25.3 release. No behavioural changes
+  in the library — the v0.25.3 release ships the autorip-side
+  parallel mux pipeline.
+
+## 0.25.2 (2026-05-19)
+
+### Fixed
+
+- **DTS-HD codec ID** — `MkvTrack::audio` now emits `A_DTS/MA` for
+  DTS-HD MA and `A_DTS/HR` for DTS-HD HR instead of mislabelling
+  both as plain `A_DTS`. Strict players (Plex transcoder, some
+  hardware decoders, AV receivers) reject lossless DTS-HD MA
+  payload when the track advertises `A_DTS` because the ID
+  implies the 1.5 Mbps core-only bitstream.
+- **PGS subtitle BlockDuration** — the PGS parser is now stateful:
+  it pairs each display PCS with the following empty/clear PCS to
+  compute a duration, and the MKV muxer emits a `BlockGroup` +
+  `BlockDuration` for subtitles that carry one. Without this the
+  last bitmap lingered on screen until the next display set
+  replaced it (or until end of file).
+
+### Changed
+
+- `codec::Frame` gains `duration_ns: Option<u64>` (set by parsers
+  that can compute one; currently only PGS).
+- `pes::PesFrame` gains `duration_ns: Option<u64>` (in-memory only;
+  not part of the on-wire serialization).
+- `MkvMuxer::write_frame` now takes a final `duration_ns: Option<u64>`
+  parameter. When `Some`, the frame is emitted as a `BlockGroup`
+  with `BlockDuration` instead of a `SimpleBlock`.
+
+## 0.25.1 (2026-05-19)
+
+### New — autorip event_fn plumbing
+
+- `PrefetchedSectorSource::new_with_events(reader, extents, batch,
+  halt, event_fn)` — same producer-thread pipeline as `new()`, plus
+  an optional callback fired from the producer with `BytesRead`
+  events after every successful batch. Lets the autorip multipass
+  + resume mux paths drive their progress UI from the highway
+  without polling the consumer side.
+- `build_iso_pipeline` gains an `event_fn` parameter so callers can
+  wire the same callback through one ctor.
+
+### Changed
+
+- `pes::Stream` trait: new default `errors() -> u64` method
+  (default returns 0). Lets `Box<dyn Stream>` callers query the
+  skip-on-error counter without downcasting. `DiscStream` overrides
+  to surface its existing `errors` field.
+
+### Removed (breaking)
+
+- `DiscStream::new_pipeline` and `DiscStream::read_pipeline`
+  deleted. All file-backed mux now uses `build_iso_pipeline` →
+  `PipelinedPesStream`. `DiscStream` is now the single-threaded
+  inline reader used by autorip's live-drive single-pass path only.
+- `DiscStream::demux_thread` and `demux_rx` fields removed.
+- `M2tsStream::open` deleted; `Mode::Read` variant removed.
+  `m2ts://` URLs go through the internal `build_m2ts_pipeline`
+  helper in `mux/resolve.rs` → `PipelinedPesStream`. `M2tsStream`
+  is a write-only sink now.
+
+## 0.25.0 (2026-05-19)
+
+### New — the freemkv mux throughput "highway"
+
+Three-stage pipelined PES read path. Read+decrypt runs on a
+producer thread, M2TS demux runs on a second thread, codec parse
+runs on the caller's thread. Communication between stages is via
+bounded `crossbeam_channel` with a recycled buffer pool — no
+allocations or memcpys in the steady-state hot loop.
+
+**Throughput on the test bed (a UHD disc, 62 GiB ISO →
+`null://`, single-thread caller):**
+
+|                                       |   MB/s |
+| ------------------------------------- | -----: |
+| 0.23.2 baseline                       |     60 |
+| + memchr SIMD HEVC start-code scan    |     69 |
+| + ts.feed no-copy boundary            |     72 |
+| + `PrefetchedSectorSource` (producer) |    124 |
+| + `DemuxThread` (3-stage pipeline)    |    135 |
+| + zero-copy recycled buffer pool      |    148 |
+| + 16 KiB initial PesAssembler buffer  |    162 |
+| + mimalloc allocator in freemkv CLI   |  200+  |
+| **+ warm cache**                      | **660** |
+
+The new public API:
+
+- `libfreemkv::PrefetchedSectorSource` — wraps any `SectorSource`,
+  spawns a producer thread, exposes recycled-buffer channels.
+- `libfreemkv::io::byte_prefetcher::BytePrefetcher` —
+  `std::io::Read` analogue for byte-stream sources (m2ts files,
+  sockets, stdin).
+- `libfreemkv::mux::demux_thread::DemuxThread` — the M2TS demux
+  worker; `spawn_zero_copy` takes either prefetcher's channels.
+- `libfreemkv::PipelinedPesStream` — the read-side `Stream` impl
+  that runs codec parse on the caller thread.
+- `libfreemkv::build_iso_pipeline(reader, title, keys, batch,
+  format, halt)` — the canonical ctor that wires all three stages
+  for an ISO file source.
+
+### Changed (breaking)
+
+- `IsoSectorReader` (the naive duplicate of `FileSectorSource`)
+  deleted. `FileSectorSource` is the sole file-backed sector
+  source; it carries the SEQUENTIAL fadvise hint, the periodic
+  DONTNEED page-cache eviction, and (new) the per-read
+  `readahead()` async-prefetch syscall.
+- `mux::input("iso://...", &opts)` now returns a
+  `PipelinedPesStream`. Function signature
+  `input(&str, &InputOptions) -> io::Result<Box<dyn Stream>>` is
+  unchanged; callers that treated the return value as
+  `Box<dyn Stream>` keep working.
+
+### Other
+
+- `FileSectorSource` exposes per-OS `prefetch()` hooks
+  (`readahead(2)` on Linux, `fcntl(F_RDADVISE)` on macOS, no-op on
+  Windows + other).
+- AACS decrypt thread-pool: env var renamed from
+  `FREEMKV_DECRYPT_THREADS` to `FREEMKV_THREADS`; default raised
+  to `cores.clamp(1, 64)`.
+- `PesAssembler` initial buffer capacity 256 KiB → 16 KiB (avoids
+  the 64-page first-touch fault tax on every PES boundary).
+- HEVC / H.264 `find_start_code` swapped onto
+  `memchr::memmem::find` (SIMD).
+
 ## 0.18.4 (2026-05-09)
 
 ### Build / CI hardening — no library code changes
@@ -94,8 +514,7 @@ in-tree consumers (autorip, the `freemkv` CLI) drove their own multipass
 loops in 0.18 rounds 1-3; 0.18.1 lands the cleanup with the deprecated names
 still alive for one minor-version window.
 
-The 0.18 design notes are in
-`(internal)/memory/0_18_redesign.md` (private) — this entry sticks to
+The 0.18 design notes are kept privately — this entry sticks to
 what changed at the public surface.
 
 #### Flat verbs
@@ -375,7 +794,7 @@ recovery.
   `READ_RECOVERY_TIMEOUT_MS = 60_000` (the v0.17.3 baseline; the kernel-
   auto-retry pattern is now provided by the `/dev/sr0` fallback above).
 
-### Empirical results (Dune Part Two UHD, BU40N direct SATA)
+### Empirical results (a UHD disc, BU40N direct SATA)
 
 - Pass 1: **94.6 MB recovered** (28% of formerly-bad data, 33 sr0 fallback
   saves), **11 s of main-title content** restored. Patch completed all 47
@@ -503,7 +922,7 @@ bridges (notably the Initio INIC-1618L) that crash on MEDIUM ERROR retries.
 - Patch instrumentation: counters for reads_ok/err, writes_ok/err, finished/unreadable.
 - `as_encoded_bytes()` replaces `as_bytes()` for portable OsStr handling.
 - Removed inline retry/reset from Drive::read — orchestration layer handles recovery.
-- Removed all `(internal)` references from public code.
+- Removed all internal references from public code.
 
 ## 0.13.26 (2026-04-27)
 
@@ -531,7 +950,7 @@ warnings` red on Linux CI that the Mac toolchain doesn't catch.
 
 ### Pre-commit gate uses CI's exact toolchain
 
-`(internal)/scripts/precommit.sh` (new) runs `cargo +1.86 fmt
+A new pre-commit script runs `cargo +1.86 fmt
 --check`, `cargo +1.86 clippy -- -D warnings`, and `cargo +1.86 test
 --tests` across all 5 freemkv crates. Mirrors each repo's
 `.github/workflows/ci.yml` step-for-step. Use it as a pre-commit hook
@@ -573,7 +992,7 @@ Through the entire 0.13.x line, every CHECK CONDITION reply from the
 drive (the standard way SCSI reports a sector failure) was being
 collapsed into a synthetic `status=0xFF, sense_key=0` "transport
 wedge" sentinel and the real sense data was thrown away. Live tracing
-on the BU40N reading Dune 2 on 2026-04-27 confirmed it: the drive was
+on the BU40N reading a UHD disc on 2026-04-27 confirmed it: the drive was
 returning `host_status=0, driver_status=8, status=2, exec_elapsed_ms=1416`
 on every bad sector — a clean CHECK CONDITION carrying full sense
 data — and the library was misclassifying it as a wedge and bailing.
@@ -645,7 +1064,7 @@ recovered or marked Unreadable. Calibration data
 
 ### Replace bisect-on-fail with hysteresis state machine (Block ↔ Single)
 
-Live test on Dune 2 v0.13.21 showed bisect-on-fail recovered every
+Live test on a UHD disc v0.13.21 showed bisect-on-fail recovered every
 recoverable sector, but spent ~30 sec per damaged 60-block (paying a
 ~5 sec kernel timeout at every bisection level). Each level descended
 log₂(60) ≈ 6 times on the failing branch.
@@ -674,7 +1093,7 @@ Per-block cost on a 60-sector damaged block with 1 bad sector:
 
 Plus inside a damaged cluster spanning many 60-blocks, hysteresis
 pays the bpt=batch fail cost ONCE on entry; bisection paid it every
-60 sectors. For Dune 2's ~1248-sector boundary cluster that's ~21
+60 sectors. For the ~1248-sector boundary cluster that's ~21
 fewer 5-sec waits = ~100 sec saved.
 
 Telemetry: new `phase=mode_change` trace event with `from`, `to`,
@@ -692,8 +1111,7 @@ synthetic BU40N-pattern reader; same 100% recovery expectation.
 ### Fix: Disc::copy bisect-on-fail (replaces skip-forward)
 
 Empirical live-hardware testing on the LG BU40N (see
-`(internal)/docs/audits/2026-04-26-test-plan-audit.md` and the
-TEST_PLAN.md run log) revealed that the drive often **fails
+the internal test-plan audit and run log) revealed that the drive often **fails
 multi-sector READ commands** in damaged regions but **succeeds when
 asked one sector at a time**. The old skip-forward strategy responded
 to multi-sector failures by jumping up to 1 % of the disc forward,
@@ -705,7 +1123,7 @@ half, retry each half, recurse down to single-sector reads. Sectors
 the drive can read individually are recovered in Pass 1; only sectors
 that fail at bpt=1 are marked NonTrimmed for the patch passes.
 
-Empirical results on Dune 2 UHD on the BU40N:
+Empirical results on a UHD disc on the BU40N:
 - Old algorithm: 25 GB read in Pass 1, then ~6 GB skip-forwarded;
   retry passes failed to recover most of the skipped zone.
 - New algorithm: ~99 % of disc recovered in Pass 1; only the truly
@@ -747,7 +1165,7 @@ LUN/BUS/HOST reset. `READ_RECOVERY_TIMEOUT_MS` (60 s) unchanged.
 `ioctl(fd, SG_IO, &hdr)`. The old pattern abandoned slow-but-alive
 commands faster than the drive could drain its internal queue,
 deepening the BU40N wedge. Per the audit at
-`(internal)/docs/audits/2026-04-26-scsi-architecture-research.md`,
+internal SCSI-architecture research,
 no reference project (MakeMKV / sg_dd / ddrescue) does what we did —
 all use sync blocking SG_IO with 8-60 s timeouts and let the kernel's
 mid-layer (`scsi_eh.rst`) run ABORT TASK / LUN RESET / BUS RESET /
@@ -874,7 +1292,7 @@ clean reads (Finished sectors) and freezes during skip-forward bad zones,
 which made every previous version's UI look hung at the bad-zone boundary.
 This was the v0.13.9 stall-guard origin bug.
 
-Live trace from v0.13.14: Pass 1 hit a Dune 2 bad zone at 24 GB and
+Live trace from v0.13.14: Pass 1 hit a bad zone at 24 GB and
 appeared "stuck" for 14 minutes per autorip's UI (`bytes_good = 23.97 GB`
 unchanged). Disc trace events showed `pos` actually advanced from 25.8 GB
 to 70 GB during that window — Pass 1 was 83 % through the disc, marking
@@ -922,7 +1340,7 @@ trace events were silently dropped by the default `libfreemkv=warn` rule.
 
 ### Telemetry: instrument the rip pipeline for in-flight diagnosis
 
-v0.13.12 shipped Fix 1+2+4 + cross-platform parity but a live test on Dune 2
+v0.13.12 shipped Fix 1+2+4 + cross-platform parity but a live test
 showed Pass 1 sat for 14 minutes with `bytes_good=0` while the inner loop
 appeared to iterate (the throttled `on_progress` log fired every 78s). The
 async fd_recovery design at §7 said each `execute()` call should bound at
@@ -966,7 +1384,7 @@ The v0.13.9 stall guard at `disc/mod.rs` exited Pass 1 early when
 `bytes_good` was flat for `stall_secs` (default 120s). This violated the
 ddrescue model: Pass 1 must sweep end-to-end, marking failed reads
 NonTrimmed for Pass 2 retry. The guard caused Pass 1 to bail at 30% on
-Dune 2 with 56 GB still NonTried, leaving Pass 2 nothing useful to do.
+a UHD disc with 56 GB still NonTried, leaving Pass 2 nothing useful to do.
 
 - Deleted the stall-guard state vars and the `if cur_good != ...
   break 'outer;` block.
@@ -1021,7 +1439,7 @@ same observable recovery contract as Linux:
 
 `PatchResult` now reports `blocks_attempted`, `blocks_read_ok`,
 `blocks_read_failed`. Pass 2's "100 minutes recovered 0 bytes" mystery
-(Dune 2) becomes diagnosable from these counters: distinguish "drive
+(a UHD disc) becomes diagnosable from these counters: distinguish "drive
 returned Ok but write/record dropped data" from "every read was Err for
 the entire range" without instrumenting from outside the lib.
 
@@ -1050,7 +1468,7 @@ against the spawned close()). The intent was to escape the 60-s
 blocking reopen.
 
 The cost was too high: a single transient poll timeout permanently
-killed the transport. Live test on Dune 2 (post-replug):
+killed the transport. Live test on a UHD disc (post-replug):
 - Pass 1 ran for **45 ms** then returned with 0 GB good and 80 GB
   pending.
 - The first SCSI READ timed out, fd went to -1, every subsequent
@@ -1083,7 +1501,7 @@ Sync bump for the autorip-side fix in 0.13.10 (Pass 1 batch reporting).
 ### Fix: Disc::copy silent stall + SgIoTransport reopen-after-timeout serialization
 
 Two correlated fixes for a hang observed live on the LG BU40N during a
-v0.13.8 rip of Dune: Part Two. At ~30 % progress through Pass 1
+v0.13.8 rip of a UHD disc. At ~30 % progress through Pass 1
 (disc → ISO), `bytes_good` froze for 10+ minutes with `errs=0`,
 no error surfaced, drive not wedged.
 
@@ -1970,10 +2388,9 @@ Rip recovery rewritten. The old binary-search-per-bad-sector model paid the full
 - **Kernel transfer limit detection**: auto-detect `max_hw_sectors_kb` via sysfs, resolve sg→block device. Previously hardcoded to 510 sectors (1MB) which exceeded the 120KB kernel limit, causing all reads to error and fall back to 6KB reads at 4.8 MB/s. Now auto-tunes to 48 sectors (96KB) or whatever the device supports.
 - **Result: 12.5 MB/s sustained, 23 MB/s peak** (was 4.8 MB/s)
 
-### LibreDrive — full init pipeline
+### Drive init pipeline
 
-- **All 10 ARM handlers translated**: unlock, firmware upload (A: WRITE_BUFFER, B: MODE SELECT), calibrate (256 zones), register reads, status, probe, set_read_speed, keepalive, timing
-- **Cold boot firmware upload**: WRITE_BUFFER 1888B (A variant) or MODE SELECT 2496B (B variant) proven on hardware
+- **Full drive init pipeline**: unlock, calibrate (256 zones), register reads, status, probe, set_read_speed, keepalive, timing
 - **Speed calibration**: 256+ disc surface probes, 64-entry speed table, triple SET_CD_SPEED
 - **Platform trait locked down**: `pub(crate)`, 3 methods only (init, set_read_speed, is_ready)
 - **Init guard**: prevents double-init, signature mismatch aborts early
@@ -1988,7 +2405,7 @@ Rip recovery rewritten. The old binary-search-per-bad-sector model paid the full
 ### Profiles
 
 - **206 profiles with full per-drive data**: ld_microcode (base64), all CDBs, speed tables, signatures
-- **Automated pipeline**: `sdf_unpack --profiles` → profiles.json (no manual merging)
+- **Automated pipeline**: profile import → profiles.json (no manual merging)
 
 ## 0.4.0 (2026-04-07)
 

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "libfreemkv"
-version = "0.20.6"
+version = "0.28.0"
 edition = "2024"
 rust-version = "1.86"
 license = "AGPL-3.0-only"
@@ -28,6 +28,22 @@ base64 = "0.22.1"
 # under project docs ("Acceptable strings: debug/trace logging"). Consumers (autorip)
 # wire a tracing subscriber and pipe events into the JSONL debug log.
 tracing = "0.1"
+# Bounded MPSC channel with kernel-wakeup send_timeout. Used by `io::pipeline`
+# so the halt-aware send/finish loops can BLOCK on consumer drain instead of
+# polling — the 50 ms poll cadence of the previous mpsc-based impl capped mux
+# throughput at ~1 MB/s (0.21.7).
+crossbeam-channel = "0.5"
+# Persistent work-stealing thread pool for parallel AACS unit
+# decryption. Per-call std::thread::scope spawned fresh OS threads
+# and that overhead dominated for typical batch sizes (60 units).
+# rayon's global pool initialises once on first use.
+rayon = "1"
+# SIMD-accelerated bytestring search. Drives the HEVC/H.264 start-code
+# scan in `mux::codec::h264::find_start_code` — naive byte-by-byte
+# walk is ~500 MB/s single-thread on x86_64; memchr's vectorised
+# `memmem::find` for the 3-byte `00 00 01` needle hits ~5 GB/s on
+# AVX2-capable hosts.
+memchr = "2"
 
 [target.'cfg(target_os = "linux")'.dependencies]
 libc = "0.2"

Makefile

@@ -1,6 +1,5 @@
 # libfreemkv — local dev helper.
-# Mirrors the cross-crate scripts in (internal)/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

@@ -6,6 +6,8 @@
 
 Rust library for 4K UHD / Blu-ray / DVD optical drives. Drive access, disc scanning, stream labels, AACS decryption, CSS decryption, KEYDB updates, and content reading in one crate. Bundled drive profiles — no external files needed.
 
+Built-in keys cover DVDs and Blu-rays (AACS 1.0). For UHD (AACS 2.0 / 2.1) discs, an optional `keydb.cfg` supplies disc-specific volume unique keys.
+
 **12+ MB/s** sustained read speeds on BD. Full init: unlock, firmware upload, speed calibration — all from pure Rust.
 
 Multi-lingual by design — the library outputs structured data and numeric error codes, never English text. Build any UI or localization on top.
@@ -18,7 +20,7 @@ Part of the [freemkv](https://github.com/freemkv) project.
 
 ```toml
 [dependencies]
-libfreemkv = "0.18"
+libfreemkv = "0.25"
 ```
 
 ## Quick Start
@@ -56,8 +58,7 @@ output.finish()?;
 For damaged discs the library exposes two flat verbs — `Disc::sweep` for the
 forward Pass 1 and `Disc::patch` for retrying bad ranges. The library never
 loops; the multipass policy is the caller's job. See
-[`docs/rip-recovery.md`](docs/rip-recovery.md) and the design notes in
-`(internal)/memory/0_18_redesign.md`.
+[`docs/rip-recovery.md`](docs/rip-recovery.md).
 
 ```rust
 use libfreemkv::{SweepOptions, PatchOptions};
@@ -122,7 +123,11 @@ loop {
 
 Streams implement `FrameSource` (read) and/or `FrameSink` (write); direction is type-checked. `input()` / `output()` resolve URL strings to PES stream instances. All URLs use the `scheme://path` format — bare paths are rejected.
 
-AACS decryption requires a KEYDB.cfg file. If available at `~/.config/aacs/KEYDB.cfg` or passed via `ScanOptions`, the library handles everything — handshake, key derivation, and per-sector decryption — without the application needing to know anything about encryption.
+### Keys
+
+DVDs (CSS) decrypt out of the box — the 1999-era public player keys are compiled into the library.
+
+Blu-rays and UHD (AACS) require a `keydb.cfg` at `~/.config/freemkv/keydb.cfg` (or passed via `ScanOptions`). The file holds all DKs, PKs, host certs, and per-disc VUKs. No AACS key material is compiled into the binary.
 
 ## Architecture
 

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.0.0.1: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
 ```
 

src/aacs/decrypt.rs

@@ -69,16 +69,29 @@ pub(crate) fn aes_cbc_decrypt(key: &[u8; 16], data: &mut [u8]) {
 
 // ── Content decryption ──────────────────────────────────────────────────────
 
-/// Check if a 6144-byte aligned unit is encrypted (copy_permission_indicator bits).
-pub fn is_unit_encrypted(unit: &[u8]) -> bool {
-    unit.len() >= ALIGNED_UNIT_LEN && (unit[0] & 0xC0) != 0
+/// True if a 6144-byte aligned unit is AACS-scrambled on disc.
+///
+/// AACS encrypts the unit body, which destroys the MPEG-TS sync bytes (`0x47`)
+/// a clear unit carries at offsets 4, 196, 388, … (one per 192-byte source
+/// packet). So "scrambled" = "the TS syncs are NOT intact". This is
+/// flag-independent: it does NOT read the TP_extra copy-control bits (byte 0)
+/// or the TS scrambling-control bits (byte 7) — AACS sets neither reliably
+/// across discs/players.
+///
+/// This is the single shared definition of "encrypted" for the whole ecosystem
+/// — libfreemkv's decrypt gate, autorip's sample selection, and the online key
+/// service's validation gate all call THIS, so they always agree on what is
+/// encrypted. A correctly-decrypted (or natively-clear) unit reports `false`,
+/// so the decrypt path never double-decrypts and there is no flag to clear.
+pub fn is_aacs_scrambled(unit: &[u8]) -> bool {
+    unit.len() >= ALIGNED_UNIT_LEN && !ts_syncs_intact(unit)
 }
 
-/// Verify decrypted unit by checking TS sync bytes at expected offsets.
-fn verify_ts(unit: &[u8]) -> bool {
-    // In a 6144-byte unit, TS packets start at byte 0 with 4-byte TP_extra_header
-    // then 188-byte TS packet, repeating every 192 bytes.
-    // Sync byte 0x47 should appear at offset 4, 196, 388, ...
+/// Most TS packet positions in `unit` carry the `0x47` sync byte — i.e. the
+/// unit looks like clear MPEG-TS. Syncs sit at offset 4 and every 192 bytes
+/// after (4-byte TP_extra_header + 188-byte TS packet). An encrypted body
+/// scrambles all but the first (which lives in the clear 16-byte seed).
+fn ts_syncs_intact(unit: &[u8]) -> bool {
     let mut count = 0;
     let mut offset = 4;
     while offset < unit.len() {
@@ -87,11 +100,15 @@ fn verify_ts(unit: &[u8]) -> bool {
         }
         offset += TS_PACKET_LEN;
     }
-    // Expect at least most packets to have sync bytes
     let total = (unit.len() - 4) / TS_PACKET_LEN + 1;
     count > total / 2
 }
 
+/// Verify a decrypted unit looks like clear MPEG-TS (sync bytes intact).
+fn verify_ts(unit: &[u8]) -> bool {
+    ts_syncs_intact(unit)
+}
+
 /// Decrypt one AACS aligned unit (6144 bytes) in-place.
 /// Returns true if decryption succeeded (verified by TS sync bytes).
 ///
@@ -99,12 +116,14 @@ fn verify_ts(unit: &[u8]) -> bool {
 /// 1. AES-128-ECB encrypt first 16 bytes with unit_key → derived
 /// 2. XOR derived with original 16 bytes → unit_decrypt_key
 /// 3. AES-128-CBC decrypt bytes 16..6143 with unit_decrypt_key and AACS IV
-/// 4. Clear encryption flag bits
+///
+/// Decryption restores the TS sync bytes, so the unit reads as clear afterward;
+/// there is no flag to clear.
 pub fn decrypt_unit(unit: &mut [u8], unit_key: &[u8; 16]) -> bool {
     if unit.len() < ALIGNED_UNIT_LEN {
         return false;
     }
-    if !is_unit_encrypted(unit) {
+    if !is_aacs_scrambled(unit) {
         return true; // not encrypted
     }
 
@@ -124,16 +143,13 @@ pub fn decrypt_unit(unit: &mut [u8], unit_key: &[u8; 16]) -> bool {
     // Step 3: Decrypt bytes 16..6143 with AES-CBC
     aes_cbc_decrypt(&decrypt_key, &mut unit[16..ALIGNED_UNIT_LEN]);
 
-    // Step 4: Clear encryption flag
-    unit[0] &= !0xC0;
-
-    // Verify
+    // Decryption restored the TS syncs; verify the unit now looks like clear TS.
     verify_ts(unit)
 }
 
 /// Decrypt one aligned unit trying multiple unit keys. Returns the key index that worked.
 pub fn decrypt_unit_try_keys(unit: &mut [u8], unit_keys: &[[u8; 16]]) -> Option<usize> {
-    if !is_unit_encrypted(unit) {
+    if !is_aacs_scrambled(unit) {
         return Some(0);
     }
 
@@ -173,7 +189,7 @@ pub fn decrypt_unit_full(
     unit_key: &[u8; 16],
     read_data_key: Option<&[u8; 16]>,
 ) -> bool {
-    if !is_unit_encrypted(unit) {
+    if !is_aacs_scrambled(unit) {
         return true;
     }
     if let Some(rdk) = read_data_key {
@@ -200,10 +216,15 @@ mod tests {
 
     #[test]
     fn test_decrypt_unit_unencrypted() {
-        // Unit with 0xC0 bits clear should pass through unchanged
+        // A clear unit (TS syncs intact) is not scrambled → passes through.
         let mut unit = vec![0u8; ALIGNED_UNIT_LEN];
-        unit[0] = 0x00; // not encrypted
+        let mut off = 4;
+        while off < ALIGNED_UNIT_LEN {
+            unit[off] = TS_SYNC;
+            off += TS_PACKET_LEN;
+        }
         let key = [0u8; 16];
+        assert!(!is_aacs_scrambled(&unit));
         assert!(decrypt_unit(&mut unit, &key));
     }
 
@@ -253,8 +274,8 @@ mod tests {
             plain[offset] = TS_SYNC;
             offset += TS_PACKET_LEN;
         }
-        // Set encryption flag
-        plain[0] |= 0xC0;
+        // No flag set: CBC-encrypting the body below scrambles packets 1..31's
+        // TS syncs, which is exactly what `is_aacs_scrambled` (raw-sync) detects.
 
         // Now encrypt bytes 16..6143 using the AACS algorithm (reverse of decrypt)
         let header: [u8; 16] = plain[..16].try_into().unwrap();
@@ -281,9 +302,9 @@ mod tests {
 
         // Now plain contains encrypted data. Decrypt it.
         let mut unit = plain;
-        assert!(is_unit_encrypted(&unit));
+        assert!(is_aacs_scrambled(&unit));
         assert!(decrypt_unit(&mut unit, &unit_key));
-        assert!(!is_unit_encrypted(&unit)); // flag should be cleared
+        assert!(!is_aacs_scrambled(&unit)); // decrypted: TS syncs restored
 
         // Verify TS sync bytes
         let mut count = 0;

src/aacs/handshake.rs

@@ -1235,8 +1235,8 @@ mod tests {
     }
 
     #[test]
-    fn test_aes_cmac() {
-        // Basic CMAC test — at minimum verify it produces consistent output
+    fn test_aes_cmac_deterministic() {
+        // Same (data, key) must always produce the same MAC.
         let key = [
             0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6, 0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf,
             0x4f, 0x3c,
@@ -1248,6 +1248,93 @@ mod tests {
         assert_ne!(mac1, [0u8; 16]); // shouldn't be all zeros
     }
 
+    #[test]
+    fn test_aes_cmac_nist_kat_full_block() {
+        // NIST SP 800-38B Appendix D.1, Example 2 (Mlen = 128):
+        //   K = 2b7e1516 28aed2a6 abf71588 09cf4f3c
+        //   M = 6bc1bee2 2e409f96 e93d7e11 7393172a
+        //   T = 070a16b4 6b4d4144 f79bdd9d d04a287c
+        let key = [
+            0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6, 0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf,
+            0x4f, 0x3c,
+        ];
+        let data = [
+            0x6b, 0xc1, 0xbe, 0xe2, 0x2e, 0x40, 0x9f, 0x96, 0xe9, 0x3d, 0x7e, 0x11, 0x73, 0x93,
+            0x17, 0x2a,
+        ];
+        let expected = [
+            0x07, 0x0a, 0x16, 0xb4, 0x6b, 0x4d, 0x41, 0x44, 0xf7, 0x9b, 0xdd, 0x9d, 0xd0, 0x4a,
+            0x28, 0x7c,
+        ];
+        let mac = aes_cmac_16(&data, &key);
+        assert_eq!(mac, expected, "AES-CMAC-128 must match NIST SP 800-38B KAT");
+    }
+
+    #[test]
+    fn test_vid_mac_verify_roundtrip() {
+        // Simulate the drive-side: pick a (bus_key, vid), compute the MAC, and
+        // verify the host-side check accepts it. Then mutate VID and MAC each
+        // in turn and verify both mutations cause a mismatch (the path that
+        // would yield Error::AacsVidMac in read_volume_id).
+        let bus_key = [
+            0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0xfe, 0xdc, 0xba, 0x98, 0x76, 0x54,
+            0x32, 0x10,
+        ];
+        let vid = [
+            0xde, 0xad, 0xbe, 0xef, 0xca, 0xfe, 0xba, 0xbe, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66,
+            0x77, 0x88,
+        ];
+
+        // Drive returns vid + mac where mac == AES-CMAC-128(bus_key, vid).
+        let drive_mac = aes_cmac_16(&vid, &bus_key);
+        let calc_mac = aes_cmac_16(&vid, &bus_key);
+        assert_eq!(calc_mac, drive_mac, "honest drive: MACs must match");
+
+        // Mutate the MAC: a malicious drive that swapped VID but returned its
+        // original MAC would produce a mismatch here.
+        let mut bad_mac = drive_mac;
+        bad_mac[0] ^= 0x01;
+        assert_ne!(calc_mac, bad_mac, "mutated MAC must be rejected");
+
+        // Mutate the VID: even one bit of VID drift produces a wildly different
+        // CMAC (this is what catches a substituted VID with a stale MAC).
+        let mut bad_vid = vid;
+        bad_vid[15] ^= 0x01;
+        let calc_for_bad_vid = aes_cmac_16(&bad_vid, &bus_key);
+        assert_ne!(
+            calc_for_bad_vid, drive_mac,
+            "MAC over mutated VID must not match original MAC"
+        );
+
+        // Wrong bus key (e.g. handshake replayed against the wrong session)
+        // also produces a different MAC over the same VID.
+        let mut wrong_key = bus_key;
+        wrong_key[0] ^= 0xff;
+        let calc_with_wrong_key = aes_cmac_16(&vid, &wrong_key);
+        assert_ne!(
+            calc_with_wrong_key, drive_mac,
+            "MAC under wrong bus key must not match"
+        );
+    }
+
+    #[test]
+    fn test_vid_mac_all_zero_mac_rejected() {
+        // Defensive: a buggy or hostile drive that returns all-zero MAC must
+        // be rejected (the real MAC over any non-trivial VID is nearly never
+        // 0...0). This guards against a class of "drive returned garbage"
+        // failures masquerading as success.
+        let bus_key = [
+            0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6, 0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf,
+            0x4f, 0x3c,
+        ];
+        let vid = [
+            0x6b, 0xc1, 0xbe, 0xe2, 0x2e, 0x40, 0x9f, 0x96, 0xe9, 0x3d, 0x7e, 0x11, 0x73, 0x93,
+            0x17, 0x2a,
+        ];
+        let calc_mac = aes_cmac_16(&vid, &bus_key);
+        assert_ne!(calc_mac, [0u8; 16], "real CMAC must not be all zeros");
+    }
+
     #[test]
     fn test_verify_host_cert_from_keydb() {
         // Verify the host cert from our KEYDB

src/aacs/keydb.rs

@@ -89,6 +89,17 @@ pub(crate) fn parse_hex20(s: &str) -> Option<[u8; 20]> {
 }
 
 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 {
@@ -106,10 +117,19 @@ impl KeyDb {
                 continue;
             }
 
-            // Device Key
+            // Device Key.
+            // Two shapes are accepted:
+            //   1. Positioned DK: `| DK | DEVICE_KEY 0x... | DEVICE_NODE 0x... | KEY_UV 0x... | KEY_U_MASK_SHIFT 0x...`
+            //      → loaded into `device_keys` (deterministic tree walk via `calc_pk_from_dk`).
+            //   2. Orphan DK: `| DK | DEVICE_KEY 0x...` with no position fields.
+            //      → loaded into `processing_keys` (brute walker / terminal validation).
+            // Per AACS spec a "PK" IS a DK at terminal position, so both row types
+            // are DKs in the unified model; only the metadata differs.
             if line.starts_with("| DK") {
                 if let Some(dk) = Self::parse_device_key(line) {
                     db.device_keys.push(dk);
+                } else if let Some(key) = Self::parse_orphan_dk(line) {
+                    db.processing_keys.push(key);
                 }
                 continue;
             }
@@ -152,7 +172,7 @@ impl KeyDb {
         db
     }
 
-    /// Load KEYDB.cfg from a file path.
+    /// 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))
@@ -184,8 +204,53 @@ impl KeyDb {
             .or_else(|| self.disc_entries.get(&hash))
     }
 
-    // ── Parsers ─────────────────────────────────────────────────────────────
+    /// Iterate every disc entry. Used by Path 3 (scan for matching VID).
+    pub fn iter_disc_entries(&self) -> impl Iterator<Item = &DiscEntry> {
+        self.disc_entries.values()
+    }
+}
 
+// ── KeyProvider impl ──────────────────────────────────────────────────────────
+//
+// Lets `KeyDb` plug into `resolve_keys` via the trait. Cloning happens in the
+// bulk methods because the trait returns owned `Vec`s (so HTTP-backed providers
+// don't need to retain state across calls).
+
+impl super::provider::KeyProvider for KeyDb {
+    fn device_keys(&self) -> Vec<DeviceKey> {
+        self.device_keys.clone()
+    }
+    fn processing_keys(&self) -> Vec<[u8; 16]> {
+        self.processing_keys.clone()
+    }
+    fn media_keys(&self) -> Vec<[u8; 16]> {
+        // Every per-disc Media Key in the db. The resolver dedups; MKs are
+        // MKB-scoped so the same value recurs across a pressing's discs.
+        self.iter_disc_entries()
+            .filter_map(|e| e.media_key)
+            .collect()
+    }
+    fn host_certs(&self) -> Vec<HostCert> {
+        self.host_certs.clone()
+    }
+    fn lookup_disc_by_hash(&self, disc_hash: &[u8; 20]) -> Option<DiscEntry> {
+        let mut hex = String::with_capacity(42);
+        hex.push_str("0x");
+        for b in disc_hash {
+            hex.push_str(&format!("{b:02X}"));
+        }
+        self.find_disc(&hex).cloned()
+    }
+    fn lookup_disc_by_vid(&self, volume_id: &[u8; 16]) -> Option<DiscEntry> {
+        self.iter_disc_entries()
+            .find(|e| matches!(e.disc_id, Some(id) if &id == volume_id))
+            .cloned()
+    }
+}
+
+// ── Private parsers (re-open the inherent impl) ─────────────────────────────
+
+impl KeyDb {
     fn parse_device_key(line: &str) -> Option<DeviceKey> {
         // | DK | DEVICE_KEY 0x... | DEVICE_NODE 0x... | KEY_UV 0x... | KEY_U_MASK_SHIFT 0x...
         let key_str = line.split("DEVICE_KEY").nth(1)?.split('|').next()?.trim();
@@ -218,6 +283,30 @@ impl KeyDb {
         None
     }
 
+    /// Parse an orphan DK row: a `| DK |` line carrying only the
+    /// `DEVICE_KEY` field (no position metadata). The key is then
+    /// treated like a terminal/unpositioned label by the resolver
+    /// (Path 2's brute walker). Returns `None` if the line carries
+    /// any position field — those are positioned DKs and parsed by
+    /// [`Self::parse_device_key`] instead.
+    fn parse_orphan_dk(line: &str) -> Option<[u8; 16]> {
+        if line.contains("DEVICE_NODE")
+            || line.contains("KEY_UV")
+            || line.contains("KEY_U_MASK_SHIFT")
+        {
+            return None;
+        }
+        let key_str = line
+            .split("DEVICE_KEY")
+            .nth(1)?
+            .split('|')
+            .next()?
+            .split(';')
+            .next()?
+            .trim();
+        parse_hex16(key_str)
+    }
+
     fn parse_host_cert(line: &str) -> Option<HostCert> {
         // | HC | HOST_PRIV_KEY 0x... | HOST_CERT 0x...
         let priv_str = line
@@ -366,28 +455,84 @@ mod tests {
 
     #[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");
+        // All-zero placeholders — synthetic; no real key material in code.
+        let z40 = "00".repeat(20);
+        let z32 = "00".repeat(16);
+        let line = format!(
+            "0x{z40} = SAMPLE_FILM (Sample Film) | D | 2024-01-01 | M | 0x{z32} | I | 0x{z32} | V | 0x{z32} | U | 1-0x{z32} ; MKBv77"
+        );
+        let entry = KeyDb::parse_disc_entry(&line).unwrap();
+        assert_eq!(entry.title, "Sample Film");
         assert!(entry.media_key.is_some());
         assert!(entry.vuk.is_some());
         assert_eq!(entry.unit_keys.len(), 1);
         assert_eq!(entry.unit_keys[0].0, 1);
     }
 
+    // NOTE: key fields below use obvious repeated-byte / zero placeholders
+    // (0x01.., 0x02.., 0x03.., 0x00..). NEVER put real — or real-looking — host,
+    // device, or processing key material in code; these tests exercise the
+    // parser's field-splitting only, not any genuine key.
+
     #[test]
     fn test_parse_device_key() {
-        let line = "| DK | DEVICE_KEY ***REMOVED*** | DEVICE_NODE 0x0800 | KEY_UV 0x00000400 | KEY_U_MASK_SHIFT 0x17 ; MKBv01-MKBv48";
+        let line = "| DK | DEVICE_KEY 0x00000000000000000000000000000000 | DEVICE_NODE 0x0800 | KEY_UV 0x00000400 | KEY_U_MASK_SHIFT 0x17 ; MKBv01-MKBv48";
         let dk = KeyDb::parse_device_key(line).unwrap();
         assert_eq!(dk.node, 0x0800);
         assert_eq!(dk.u_mask_shift, 0x17);
     }
 
+    #[test]
+    fn test_orphan_dk_row_loads_into_processing_keys() {
+        // `| DK |` row without position fields = an orphan DK. Per the
+        // unified model the resolver treats it like a terminal/PK
+        // candidate: it lands in `processing_keys` and the brute walker
+        // handles it.
+        let cfg = r#"
+| DK | DEVICE_KEY 0x01010101010101010101010101010101 ; orphan, no position fields
+| DK | DEVICE_KEY 0x02020202020202020202020202020202 | DEVICE_NODE 0x0800 | KEY_UV 0x00000400 | KEY_U_MASK_SHIFT 0x17 ; positioned MKBv01-MKBv48
+| PK | 0x03030303030303030303030303030303 ; legacy PK row still works
+"#;
+        let db = KeyDb::parse(cfg);
+        assert_eq!(
+            db.device_keys.len(),
+            1,
+            "positioned DK row should land in device_keys"
+        );
+        // Orphan DK + legacy PK row both end up in processing_keys.
+        assert_eq!(
+            db.processing_keys.len(),
+            2,
+            "orphan DK row + legacy PK row both belong in processing_keys"
+        );
+        assert_eq!(db.processing_keys[0][..4], [0x01, 0x01, 0x01, 0x01]);
+        assert_eq!(db.processing_keys[1][..4], [0x03, 0x03, 0x03, 0x03]);
+    }
+
+    #[test]
+    fn test_parse_orphan_dk_rejects_lines_with_position_fields() {
+        // The parser must NOT pick up a positioned DK row as an orphan
+        // (that would double-count). parse_orphan_dk explicitly checks.
+        let positioned = "| DK | DEVICE_KEY 0x02020202020202020202020202020202 | DEVICE_NODE 0x0800 | KEY_UV 0x00000400 | KEY_U_MASK_SHIFT 0x17";
+        assert!(
+            KeyDb::parse_orphan_dk(positioned).is_none(),
+            "positioned DK must not match orphan parser"
+        );
+        let orphan = "| DK | DEVICE_KEY 0x01010101010101010101010101010101";
+        let key = KeyDb::parse_orphan_dk(orphan).expect("orphan should parse");
+        assert_eq!(key[..4], [0x01, 0x01, 0x01, 0x01]);
+    }
+
     #[test]
     fn test_parse_host_cert() {
-        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);
+        // 20-byte priv + 92-byte cert, all zeros — placeholders, not a key.
+        let line = format!(
+            "| HC | HOST_PRIV_KEY 0x{} | HOST_CERT 0x{} ; Revoked",
+            "00".repeat(20),
+            "00".repeat(92)
+        );
+        let hc = KeyDb::parse_host_cert(&line).unwrap();
+        assert_eq!(hc.private_key, [0u8; 20]);
         assert_eq!(hc.certificate.len(), 92);
     }
 
@@ -405,15 +550,15 @@ mod tests {
         assert!(!db.host_certs.is_empty());
         assert!(db.disc_entries.len() > 170000);
 
-        // Look up Dune: Part Two
-        let dune = db
+        // Look up any disc entry carrying a full key set.
+        let entry = 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());
+            .find(|e| e.vuk.is_some() && e.media_key.is_some() && !e.unit_keys.is_empty())
+            .expect("no disc entry with a full key set");
+        assert!(entry.media_key.is_some());
+        assert!(entry.vuk.is_some());
+        assert!(!entry.unit_keys.is_empty());
 
         eprintln!(
             "Parsed {} disc entries, {} DK, {} PK",

src/aacs/mod.rs

@@ -17,16 +17,26 @@ pub mod decrypt;
 pub mod handshake;
 pub mod keydb;
 pub mod keys;
+pub mod provider;
+pub mod variants;
 
 // Explicit re-exports — only items needed by external consumers and sibling crate modules.
 // AES primitives (aes_ecb_encrypt, aes_ecb_decrypt, aes_cbc_decrypt) are pub(crate) in decrypt.rs.
 pub use decrypt::{
     ALIGNED_UNIT_LEN, decrypt_bus, decrypt_unit, decrypt_unit_full, decrypt_unit_try_keys,
-    is_unit_encrypted,
+    is_aacs_scrambled,
 };
 pub use keydb::{DeviceKey, DiscEntry, HostCert, KeyDb};
+pub use keys::probe;
 pub use keys::{
-    ContentCert, ResolvedKeys, UnitKeyFile, decrypt_unit_key, 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,
+    AacsVersion, ContentCert, ResolveContext, ResolvedKeys, UnitKeyFile, decrypt_unit_key,
+    derive_media_key_from_dk, derive_media_key_from_pk, derive_vuk, disc_hash, disc_hash_hex,
+    mkb_content_len, mkb_version, parse_content_cert, parse_unit_key_ro, read_mkb_from_drive,
+    resolve_keys_v1, resolve_keys_v2, resolve_keys_v21,
+};
+pub use provider::KeyProvider;
+pub use variants::{
+    KEY_CORRECTION_DATA_PLACEHOLDER, MediaKeyVariantError, MkbRecord, ProcessingKeyMatch,
+    derive_media_key_variant, is_variant_mkb, variant_data_record, variant_key_data, variant_nonce,
+    walk_mkb, walk_processing_key,
 };

src/aacs/provider.rs

@@ -0,0 +1,161 @@
+//! 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`],
+//!   [`host_certs`]) — the resolver unions 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.
+//!
+//! 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 five.
+//!
+//! 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
+//! [`host_certs`]: KeyProvider::host_certs
+//! [`lookup_disc_by_hash`]: KeyProvider::lookup_disc_by_hash
+//! [`lookup_disc_by_vid`]: KeyProvider::lookup_disc_by_vid
+
+use super::keydb::{DeviceKey, DiscEntry, HostCert};
+
+/// Source of AACS key material.
+///
+/// Implementors return raw material only — the resolver in
+/// `aacs::keys` owns all the crypto (DK→PK walking, PK validation,
+/// MK→VUK→TK derivation). See module docs for method semantics.
+pub trait KeyProvider: Send + Sync {
+    /// Device keys (top-of-tree, walked by the resolver).
+    fn device_keys(&self) -> Vec<DeviceKey> {
+        Vec::new()
+    }
+
+    /// Processing keys — terminal PKs or walk-input PKs. The
+    /// resolver tries each as a terminal first (cheap validate).
+    fn processing_keys(&self) -> Vec<[u8; 16]> {
+        Vec::new()
+    }
+
+    /// Every Media Key this provider holds, regardless of which disc it was
+    /// filed under. An MK is MKB-scoped (shared across a pressing/MKB-family),
+    /// so the resolver can verify each against the disc's MKB (`km_verifies`)
+    /// and resolve a disc whose own hash/VID isn't directly keyed.
+    fn media_keys(&self) -> Vec<[u8; 16]> {
+        Vec::new()
+    }
+
+    /// AACS host certificates (with their private keys) for drive
+    /// authentication. Multiple in case some are revoked.
+    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 consumes `&[&dyn KeyProvider]` directly; these
+/// helpers wrap the union-vs-short-circuit policy per method.
+pub(crate) struct Providers<'a>(pub &'a [&'a dyn KeyProvider]);
+
+impl Providers<'_> {
+    /// Union — gather DKs from every provider.
+    pub fn device_keys(&self) -> Vec<DeviceKey> {
+        self.0.iter().flat_map(|p| p.device_keys()).collect()
+    }
+
+    /// Union — gather PKs from every provider.
+    pub fn processing_keys(&self) -> Vec<[u8; 16]> {
+        self.0.iter().flat_map(|p| p.processing_keys()).collect()
+    }
+
+    /// 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. Not yet wired into
+    /// the SCSI handshake (which still reads `KeyDb.host_certs` directly);
+    /// kept here so a provider-aware handshake refactor is a drop-in.
+    #[allow(dead_code)]
+    pub fn host_certs(&self) -> Vec<HostCert> {
+        self.0.iter().flat_map(|p| p.host_certs()).collect()
+    }
+
+    /// Short-circuit — query providers in array order, first hit wins.
+    pub fn lookup_disc_by_hash(&self, disc_hash: &[u8; 20]) -> Option<DiscEntry> {
+        self.0.iter().find_map(|p| p.lookup_disc_by_hash(disc_hash))
+    }
+
+    /// Short-circuit — query providers in array order, first hit wins.
+    pub fn lookup_disc_by_vid(&self, volume_id: &[u8; 16]) -> Option<DiscEntry> {
+        self.0.iter().find_map(|p| p.lookup_disc_by_vid(volume_id))
+    }
+}
+
+/// A [`KeyProvider`] backed by a single caller-supplied key's raw material —
+/// the bridge for [`crate::disc::Disc::decrypt_with`].
+///
+/// The application's key source did the lookup and handed in material at one
+/// level (DK / PK / MK / VUK). This exposes exactly that material to the
+/// version-dispatched resolver, which owns ALL derivation — so a source never
+/// derives, and the lib remains the single home for the AACS chain across
+/// 1.0 / 2.0 / 2.1 / 2.x.
+///
+/// Each level fills only its own field; the rest stay empty, so the resolver
+/// naturally runs the matching path (DK→…, PK→…, MK-pool brute, or a
+/// disc-keyed VUK hit). `decrypt_with` already knows the disc, so the
+/// `lookup_disc_by_*` hash/VID arguments are irrelevant — a present
+/// `disc_entry` is returned for any query.
+pub(crate) struct SuppliedKey {
+    pub device_keys: Vec<DeviceKey>,
+    pub processing_keys: Vec<[u8; 16]>,
+    pub media_keys: Vec<[u8; 16]>,
+    pub disc_entry: Option<DiscEntry>,
+}
+
+impl KeyProvider for SuppliedKey {
+    fn device_keys(&self) -> Vec<DeviceKey> {
+        self.device_keys.clone()
+    }
+    fn processing_keys(&self) -> Vec<[u8; 16]> {
+        self.processing_keys.clone()
+    }
+    fn media_keys(&self) -> Vec<[u8; 16]> {
+        self.media_keys.clone()
+    }
+    fn lookup_disc_by_hash(&self, _disc_hash: &[u8; 20]) -> Option<DiscEntry> {
+        self.disc_entry.clone()
+    }
+    fn lookup_disc_by_vid(&self, _volume_id: &[u8; 16]) -> Option<DiscEntry> {
+        self.disc_entry.clone()
+    }
+}

src/aacs/variants.rs

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

src/css/auth.rs

@@ -4,13 +4,14 @@
 //!   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
-//!
-//! Based on libdvdcss (VideoLAN) and Stevenson 1999 analysis.
 
 use crate::drive::Drive;
 use crate::error::{Error, Result};
 
-// ── Player keys (from libdvdcss, Stevenson's PlayerKey cracker) ───────────
+// ── 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],

src/css/mod.rs

@@ -16,6 +16,7 @@ pub mod lfsr;
 pub(crate) mod tables;
 
 use crate::disc::Extent;
+use crate::drive::Drive;
 use crate::sector::SectorSource;
 
 /// CSS decryption state for a DVD title.
@@ -25,6 +26,50 @@ pub struct CssState {
     pub title_key: [u8; 5],
 }
 
+/// Inputs for CSS key acquisition.
+///
+/// The acquisition path depends on which inputs the caller supplies:
+///
+/// - With `drive` + `auth_lba` set, [`resolve`] runs the full SCSI bus
+///   auth + title-key path (live BU40N / DVD drive).
+/// - With `reader` + `extents` set, [`resolve`] falls back to the
+///   crack path (Stevenson known-plaintext attack on encrypted PES
+///   headers; works on disc images and on drives whose CSS auth path
+///   is unavailable).
+///
+/// `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]>,
+}
+
+/// Acquire a CSS title key using whichever inputs the context provides.
+///
+/// Order of attempts:
+///   1. SCSI auth path (when `drive` and `auth_lba` are set).
+///   2. Crack path (when `reader` and `extents` are set).
+///
+/// Returns `None` if neither path is configured or both fail.
+pub fn resolve(ctx: &mut CssContext<'_>) -> Option<CssState> {
+    if let (Some(drive), Some(lba)) = (ctx.drive.as_deref_mut(), ctx.auth_lba) {
+        if let Ok(title_key) = auth::authenticate_and_read_title_key(drive, lba) {
+            return Some(CssState { title_key });
+        }
+    }
+    if let (Some(reader), Some(extents)) = (ctx.reader.as_deref_mut(), ctx.extents) {
+        return crack_key(reader, extents);
+    }
+    None
+}
+
 /// Crack the CSS title key by reading encrypted sectors and applying
 /// a known-plaintext attack on MPEG-2 headers.
 ///

src/decrypt.rs

@@ -3,9 +3,131 @@
 //! Decrypts sectors in-place using resolved keys from disc scanning.
 //! Handles AACS 1.0, AACS 2.0, and CSS transparently.
 //! The caller never sees encrypted data unless explicitly bypassed.
+//!
+//! ## Parallel AACS decrypt
+//!
+//! Each AACS aligned unit (6144 bytes) is decrypted INDEPENDENTLY of
+//! every other unit — per-unit key derivation from the unit_key plus
+//! the unit's own first-16-byte header. There is no cross-unit
+//! dependency, so a buffer of N units can be decrypted on N threads
+//! in parallel via a persistent rayon thread pool.
+//!
+//! Small buffers (< [`PARALLEL_MIN_UNITS`] units) fall through to the
+//! serial path to avoid pool dispatch overhead beating the per-unit
+//! AES work.
+//!
+//! ## Thread-count configuration — three layers
+//!
+//! Resolution order (highest wins):
+//! 1. The most recent [`set_decrypt_threads`] call with `n > 0`.
+//!    Calling this *replaces* the live thread pool — useful for a
+//!    settings-page slider in a long-running daemon.
+//! 2. `FREEMKV_THREADS` env var, if set and `> 0`. Single knob
+//!    covering decrypt today, intended to also drive any future
+//!    input-side / output-side worker pools.
+//! 3. Default: all available cores. Algorithm optimisation comes
+//!    first — we measure single-thread performance to find serial
+//!    bottlenecks before throwing parallelism at it — but once a
+//!    pool is engaged we use the whole box. Hard cap at
+//!    [`MAX_THREADS`] (rayon stack memory).
 
 use crate::aacs;
 use crate::css;
+use rayon::prelude::*;
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::{Arc, RwLock};
+
+/// Minimum units in a buffer before we pay the pool-dispatch cost of
+/// fanning out. Below this, serial is faster.
+const PARALLEL_MIN_UNITS: usize = 8;
+
+/// Hard upper bound on configurable thread count. Anything larger is
+/// almost certainly a misconfiguration; rayon would happily allocate
+/// thousands of worker stacks otherwise.
+pub const MAX_THREADS: usize = 64;
+
+/// Process-wide decrypt thread count override. `0` means "use env
+/// var, else default" — see [`decrypt_threads`] for the resolution
+/// order.
+static DECRYPT_THREADS: AtomicUsize = AtomicUsize::new(0);
+
+/// Current rayon pool. `RwLock<Option<Arc<...>>>` so that
+/// [`set_decrypt_threads`] can swap the pool out without leaking the
+/// old one and without blocking ongoing decrypt work (in-flight calls
+/// hold an `Arc` clone via [`decrypt_pool`] and finish on the old
+/// pool; new calls pick up the new pool).
+static DECRYPT_POOL: RwLock<Option<Arc<rayon::ThreadPool>>> = RwLock::new(None);
+
+/// Configure how many threads to use for AACS unit decryption. A value
+/// of `0` resets to the env / default resolution. `1` forces serial.
+/// `N > 1` builds a new rayon pool of size N and atomically replaces
+/// the live pool.
+///
+/// Thread-safe. Live decrypt calls keep their previously-acquired
+/// pool reference for the rest of the call — no mid-call pool
+/// switch. Subsequent calls see the new pool.
+///
+/// Pool construction is ~ms-scale; safe to call from a settings POST
+/// handler.
+pub fn set_decrypt_threads(n: usize) {
+    let clamped = n.min(MAX_THREADS);
+    DECRYPT_THREADS.store(clamped, Ordering::Relaxed);
+    // Drop the existing pool. Next decrypt_pool() call rebuilds with
+    // the new resolved thread count.
+    if let Ok(mut guard) = DECRYPT_POOL.write() {
+        *guard = None;
+    }
+}
+
+/// Get (or lazily build) the active rayon thread pool. Returns an
+/// `Arc` so in-flight work survives a concurrent
+/// [`set_decrypt_threads`] swap.
+fn decrypt_pool() -> Arc<rayon::ThreadPool> {
+    // Fast path: pool already built.
+    if let Ok(guard) = DECRYPT_POOL.read() {
+        if let Some(pool) = guard.as_ref() {
+            return Arc::clone(pool);
+        }
+    }
+    // Slow path: build a new one under the write lock. Double-check
+    // after acquiring in case another caller built it first.
+    let mut guard = DECRYPT_POOL.write().expect("DECRYPT_POOL RwLock poisoned");
+    if let Some(pool) = guard.as_ref() {
+        return Arc::clone(pool);
+    }
+    let n = decrypt_threads();
+    let pool = Arc::new(
+        rayon::ThreadPoolBuilder::new()
+            .num_threads(n)
+            .thread_name(|i| format!("freemkv-decrypt-{i}"))
+            .build()
+            .expect("rayon decrypt pool build failed"),
+    );
+    *guard = Some(Arc::clone(&pool));
+    pool
+}
+
+/// Current effective decrypt thread count. Resolution order:
+/// 1. Most recent [`set_decrypt_threads`] value (if > 0)
+/// 2. `FREEMKV_THREADS` env var (if set and > 0)
+/// 3. Default: all available cores, capped at [`MAX_THREADS`].
+pub fn decrypt_threads() -> usize {
+    let explicit = DECRYPT_THREADS.load(Ordering::Relaxed);
+    if explicit > 0 {
+        return explicit;
+    }
+    let env = std::env::var("FREEMKV_THREADS")
+        .ok()
+        .and_then(|v| v.parse::<usize>().ok())
+        .unwrap_or(0);
+    if env > 0 {
+        return env.min(MAX_THREADS);
+    }
+    let cores = std::thread::available_parallelism()
+        .map(|n| n.get())
+        .unwrap_or(2);
+    cores.clamp(1, MAX_THREADS)
+}
 
 /// Resolved decryption state from disc scanning.
 /// Passed to `decrypt_sectors()` — the caller doesn't need to know
@@ -57,29 +179,45 @@ pub fn decrypt_sectors(
                     return Err(crate::error::Error::DecryptFailed);
                 }
             };
-            let rdk = read_data_key.as_ref();
+            let rdk: Option<[u8; 16]> = *read_data_key;
             let unit_len = aacs::ALIGNED_UNIT_LEN;
+            let nthreads = decrypt_threads();
+            let chunks: Vec<&mut [u8]> = buf.chunks_mut(unit_len).collect();
+            let nunits = chunks.len();
 
-            for chunk in buf.chunks_mut(unit_len) {
-                if chunk.len() == unit_len && aacs::is_unit_encrypted(chunk) {
-                    // `is_unit_encrypted` is a byte-0 heuristic: it fires on any
-                    // unit whose first byte has the top 2 bits set, which is
-                    // correct for m2ts source packets (where those bits are the
-                    // copy-control marker) but false-positives on any other binary
-                    // data with similarly-shaped first bytes — notably MPLS/CLPI
-                    // navigation files that begin with ASCII magic ('M', 'H'…)
-                    // and survive sweep mixed in with encrypted m2ts payloads.
-                    // `decrypt_unit_full` self-checks via TS-sync verification and
-                    // returns false on a misfire, but it has already mutated the
-                    // chunk by then. Snapshot and restore on verification failure
-                    // — same pattern `decrypt_unit_try_keys` uses for multi-key
-                    // discs. Real m2ts units verify and stay decrypted; nav-file
-                    // sectors get scrambled briefly and then put back as-was.
+            // Per-unit decrypt closure. The is_aacs_scrambled check reads the
+            // raw TS syncs; a non-m2ts unit (e.g. MPLS/CLPI nav file) can look
+            // scrambled and trigger a decrypt attempt, so on a verify miss we
+            // snapshot+restore the original bytes so it survives. See test
+            // `nav_file_unit_survives_decrypt_attempt`.
+            let decrypt_one = |chunk: &mut [u8]| {
+                if chunk.len() == unit_len && aacs::is_aacs_scrambled(chunk) {
                     let original: Vec<u8> = chunk.to_vec();
-                    if !aacs::decrypt_unit_full(chunk, &uk, rdk) {
+                    if !aacs::decrypt_unit_full(chunk, &uk, rdk.as_ref()) {
                         chunk.copy_from_slice(&original);
                     }
                 }
+            };
+
+            if nthreads <= 1 || nunits < PARALLEL_MIN_UNITS {
+                // Serial path: avoids thread-pool overhead for tiny
+                // buffers; also the only path when caller pinned
+                // single-threaded via FREEMKV_THREADS=1.
+                for chunk in chunks {
+                    decrypt_one(chunk);
+                }
+            } else {
+                // Parallel path via rayon's persistent global pool.
+                // The pool is built once on first use (lazy_static-style)
+                // and reused across every decrypt_sectors call — no
+                // per-call OS thread spawn, no thread-creation latency
+                // amortised per batch. Each unit decrypts independently
+                // (own key derivation), so par_iter is sound.
+                decrypt_pool().install(|| {
+                    chunks.into_par_iter().for_each(|chunk| {
+                        decrypt_one(chunk);
+                    });
+                });
             }
         }
         DecryptKeys::Css { title_key } => {
@@ -95,11 +233,11 @@ pub fn decrypt_sectors(
 mod tests {
     use super::*;
 
-    /// Regression for the 0.18.1 nav-file scramble bug. A non-m2ts unit whose
-    /// first byte has the top 2 bits set (here: the ASCII letter 'M' that
-    /// MPLS files start with, 0x4D = 0b01001101) trips `is_unit_encrypted`,
-    /// gets AES-decrypted with the unit key, fails the TS-sync verification,
-    /// and must be restored to its original bytes — not left scrambled.
+    /// Regression for the 0.18.1 nav-file scramble bug. A non-m2ts unit (here
+    /// an MPLS file: starts "MPLS", carries no TS syncs) reads as scrambled
+    /// under `is_aacs_scrambled`, gets AES-decrypted with the unit key, fails
+    /// the TS-sync verification, and must be restored to its original bytes —
+    /// not left scrambled.
     #[test]
     fn nav_file_unit_survives_decrypt_attempt() {
         let mut unit = vec![0u8; aacs::ALIGNED_UNIT_LEN];

src/disc/encrypt.rs

@@ -14,56 +14,221 @@ pub(super) struct HandshakeResult {
 }
 
 impl Disc {
-    /// SCSI handshake result — volume ID and bus keys from ECDH authentication.
-    /// Only available when scanning from a real drive (not ISO images).
+    /// Acquire the Volume ID. Tries the per-drive OEM CDB path first
+    /// when the drive reports `is_unlocked()` (extended-access state),
+    /// and falls back to the cert-based AACS mutual-auth handshake
+    /// otherwise.
+    ///
+    /// The OEM path is a single READ_BUFFER CDB built from the drive
+    /// profile's `read_vid_cdb` template. The response carries a 3-byte
+    /// header (validated against `00 22 00`) followed by the 16-byte
+    /// VID at bytes [4..20]. Crucially, no AGID setup is required —
+    /// the drive's runtime firmware serves the VID directly when in
+    /// extended-access state.
+    ///
+    /// The cert path is the standard AACS spec flow: ECDH key
+    /// agreement, bus-key derivation, then `REPORT_DISC_STRUCTURE`
+    /// format 0x80 to retrieve VID under bus-key MAC.
+    pub(super) fn read_vid(
+        session: &mut crate::drive::Drive,
+        opts: &ScanOptions,
+    ) -> Result<[u8; 16]> {
+        if session.is_unlocked() {
+            let profile = session
+                .drive_profile()
+                .ok_or(Error::DriveProfileMissing)?
+                .clone();
+            return Self::read_vid_oem(session, &profile);
+        }
+        Self::read_vid_cert(session, opts)
+    }
+
+    /// OEM VID retrieval — issues the per-drive READ_BUFFER CDB and
+    /// parses the response.
+    ///
+    /// Response layout (36 bytes):
+    ///   * [0..3]   3-byte response signature; expected `00 22 00`
+    ///   * [3]      reserved
+    ///   * [4..20]  16-byte Volume ID
+    ///   * [20..36] reserved / per-drive padding
+    fn read_vid_oem(
+        session: &mut crate::drive::Drive,
+        profile: &crate::profile::DriveProfile,
+    ) -> Result<[u8; 16]> {
+        const RESPONSE_LEN: usize = 36;
+        const EXPECTED_HEADER: [u8; 3] = [0x00, 0x22, 0x00];
+
+        let cdb = profile.read_vid_cdb.ok_or(Error::VidCdbUnavailable)?;
+        let mut buf = vec![0u8; RESPONSE_LEN];
+        let result = session.scsi_execute(
+            &cdb,
+            crate::scsi::DataDirection::FromDevice,
+            &mut buf,
+            5_000,
+        )?;
+        if result.bytes_transferred < RESPONSE_LEN {
+            tracing::warn!(
+                target: "freemkv::disc",
+                phase = "oem_vid_short_response",
+                bytes_transferred = result.bytes_transferred,
+                "OEM VID CDB returned short response"
+            );
+            return Err(Error::AacsVidRead);
+        }
+        if buf[0..3] != EXPECTED_HEADER {
+            tracing::warn!(
+                target: "freemkv::disc",
+                phase = "oem_vid_bad_header",
+                header_0 = buf[0],
+                header_1 = buf[1],
+                header_2 = buf[2],
+                "OEM VID response header mismatch"
+            );
+            return Err(Error::AacsVidRead);
+        }
+        let mut vid = [0u8; 16];
+        vid.copy_from_slice(&buf[4..20]);
+        tracing::warn!(
+            target: "freemkv::disc",
+            phase = "oem_vid_ok",
+            "OEM VID retrieved"
+        );
+        Ok(vid)
+    }
+
+    /// Cert-based VID retrieval — runs the full AACS mutual-auth
+    /// handshake and extracts VID from the bus-key-MAC'd
+    /// `REPORT_DISC_STRUCTURE` response.
+    fn read_vid_cert(session: &mut crate::drive::Drive, opts: &ScanOptions) -> Result<[u8; 16]> {
+        match Self::do_handshake_cert(session, opts) {
+            (Some(h), _) => Ok(h.volume_id),
+            (None, Some(e)) => Err(e),
+            (None, None) => Err(Error::AacsVidUnavailable),
+        }
+    }
+
+    /// SCSI handshake — drives the VID-acquisition flow and returns
+    /// a structured `HandshakeResult` for downstream key resolution.
+    /// Prefers the OEM path when `Drive::is_unlocked()` is true and
+    /// falls back to cert-based mutual auth otherwise.
+    ///
+    /// The OEM path produces only VID (no bus-key, so no
+    /// `read_data_key`); the cert path can produce both. AACS 2.0
+    /// content that needs read_data_key for bus decryption requires
+    /// the cert path.
+    ///
+    /// Returns `(handshake, error)`:
+    ///   * `(Some(_), None)`  — VID acquired
+    ///   * `(None, Some(_))`  — specific failure mode (see
+    ///     `AacsHostCertRejected` / `AacsRawReadUnsupported` /
+    ///     `AacsVidUnavailable` / `DriveProfileMissing` /
+    ///     `VidCdbUnavailable` variants in `error.rs`)
+    ///   * `(None, None)`     — handshake not attempted (no keydb;
+    ///     resolution will proceed with VID=zero and rely on path 1
+    ///     disc-hash → VUK lookup)
     pub(super) fn do_handshake(
         session: &mut crate::drive::Drive,
         opts: &ScanOptions,
-    ) -> Option<HandshakeResult> {
-        use crate::aacs::{self, KeyDb};
-
+    ) -> (Option<HandshakeResult>, Option<Error>) {
+        let unlocked = session.is_unlocked();
         tracing::warn!(
             target: "freemkv::disc",
             phase = "handshake_entry",
+            unlocked,
             "do_handshake entered"
         );
-        let keydb_path = match opts.resolve_keydb() {
-            Some(p) => p,
-            None => {
-                tracing::warn!(
-                    target: "freemkv::disc",
-                    phase = "handshake_no_keydb",
-                    "no KEYDB found in search paths; handshake skipped"
-                );
-                return None;
+
+        if unlocked {
+            // Try OEM VID retrieval first. If the drive's profile
+            // doesn't carry the CDB template, or the response is
+            // malformed, fall through to cert-based auth.
+            match Self::read_vid(session, opts) {
+                Ok(volume_id) => {
+                    return (
+                        Some(HandshakeResult {
+                            volume_id,
+                            read_data_key: None,
+                        }),
+                        None,
+                    );
+                }
+                Err(Error::DriveProfileMissing) | Err(Error::VidCdbUnavailable) => {
+                    tracing::warn!(
+                        target: "freemkv::disc",
+                        phase = "handshake_oem_unavailable",
+                        "OEM VID path unavailable for this drive; trying cert handshake"
+                    );
+                }
+                Err(e) => {
+                    tracing::warn!(
+                        target: "freemkv::disc",
+                        phase = "handshake_oem_failed",
+                        error_code = e.code(),
+                        "OEM VID retrieval failed; trying cert handshake"
+                    );
+                }
             }
-        };
-        let keydb = match KeyDb::load(&keydb_path) {
-            Ok(db) => db,
-            Err(e) => {
+        }
+
+        Self::do_handshake_cert(session, opts)
+    }
+
+    /// Cert-based AACS handshake. The legacy auth path; still used as
+    /// the fallback when the OEM VID path isn't available or fails.
+    fn do_handshake_cert(
+        session: &mut crate::drive::Drive,
+        opts: &ScanOptions,
+    ) -> (Option<HandshakeResult>, Option<Error>) {
+        use crate::aacs;
+
+        // Host certs come from the caller's DriveCredentials (e.g. the keydb's
+        // host_certs(), sourced app-side) — the library does not load a keydb.
+        // Absent ⇒ no cert auth: an unlocked / LibreDrive drive already returned
+        // a Volume ID via the OEM path before reaching here, so this is the
+        // locked-drive-without-credentials case.
+        let host_certs: &[aacs::HostCert] = match &opts.credentials {
+            Some(c) if !c.host_certs.is_empty() => &c.host_certs,
+            _ => {
                 tracing::warn!(
                     target: "freemkv::disc",
-                    phase = "handshake_keydb_load_failed",
-                    io_error_kind = ?e.kind(),
-                    keydb = %keydb_path.display(),
-                    "KEYDB load failed; handshake skipped"
+                    phase = "handshake_no_credentials",
+                    "no drive credentials supplied; cert handshake skipped"
                 );
-                return None;
+                return (None, None);
             }
         };
 
-        let host_cert_count = keydb.host_certs.len();
+        let host_cert_count = host_certs.len();
         tracing::warn!(
             target: "freemkv::disc",
             phase = "handshake_start",
             host_cert_count,
-            keydb = %keydb_path.display(),
             "handshake starting"
         );
 
-        const MAX_CERT_ATTEMPTS: usize = 16;
+        // v0.25.7 wedge fix. Pre-0.25.7 this loop fired up to 16 AACS
+        // authenticate attempts back-to-back with no pause. Each attempt
+        // is 5-10 SCSI REPORT_KEY/SEND_KEY exchanges. On a disc whose
+        // host cert isn't in our KEYDB (or one the drive rejects),
+        // that's 80-160 SCSI commands hammered at the drive in a
+        // few hundred milliseconds — and the BU40N (and most consumer
+        // optical drives) responds by entering a fast-fail firmware
+        // wedge state where every subsequent CDB returns
+        // ILLEGAL_REQUEST/INVALID_FIELD_IN_CDB (sense 05/24) until
+        // power-cycled. Hit live on rip1 2026-05-20 during a MOVIE
+        // UHD scan: KEYDB miss → 16 cert attempts in a tight loop →
+        // wedge → forced host reboot + drive disconnect to recover.
+        //
+        // Defense-in-depth: cap attempts, sleep between, and bail
+        // early on the drive's wedge sense so any later regression
+        // can't undo the protection silently.
+        const MAX_CERT_ATTEMPTS: usize = 3;
+        const PER_CERT_BACKOFF_MS: u64 = 1000;
         let mut last_err_code: Option<u16> = None;
-        for (idx, hc) in keydb.host_certs.iter().take(MAX_CERT_ATTEMPTS).enumerate() {
+        for (idx, hc) in host_certs.iter().take(MAX_CERT_ATTEMPTS).enumerate() {
+            if idx > 0 {
+                std::thread::sleep(std::time::Duration::from_millis(PER_CERT_BACKOFF_MS));
+            }
             match aacs::handshake::aacs_authenticate(session, &hc.private_key, &hc.certificate) {
                 Ok(mut auth) => {
                     let volume_id = match aacs::handshake::read_volume_id(session, &mut auth) {
@@ -76,7 +241,7 @@ impl Disc {
                                 error_code = e.code(),
                                 "auth ok but volume ID read failed"
                             );
-                            return None;
+                            return (None, Some(Error::AacsVidUnavailable));
                         }
                     };
                     let read_data_key = aacs::handshake::read_data_keys(session, &mut auth)
@@ -88,13 +253,33 @@ impl Disc {
                         cert_index = idx,
                         has_read_data_key = read_data_key.is_some(),
                     );
-                    return Some(HandshakeResult {
-                        volume_id,
-                        read_data_key,
-                    });
+                    return (
+                        Some(HandshakeResult {
+                            volume_id,
+                            read_data_key,
+                        }),
+                        None,
+                    );
                 }
                 Err(e) => {
-                    last_err_code = Some(e.code());
+                    let code = e.code();
+                    last_err_code = Some(code);
+                    // Drive wedge senses (any with high byte 0x05 =
+                    // ILLEGAL_REQUEST). The drive isn't merely
+                    // rejecting our cert — it's saying "I won't talk
+                    // to you anymore." Trying more certs makes the
+                    // wedge worse. Bail out immediately.
+                    let sense_key = ((code >> 8) & 0xFF) as u8;
+                    if sense_key == 0x05 {
+                        tracing::warn!(
+                            target: "freemkv::disc",
+                            phase = "handshake_wedge_detected",
+                            cert_index = idx,
+                            error_code = code,
+                            "drive returned ILLEGAL_REQUEST during auth; bailing out to avoid wedge"
+                        );
+                        return (None, Some(Error::AacsHostCertRejected));
+                    }
                     continue;
                 }
             }
@@ -105,112 +290,83 @@ impl Disc {
             host_cert_count,
             tried = host_cert_count.min(MAX_CERT_ATTEMPTS),
             last_error_code = last_err_code,
-            "all host certs in KEYDB rejected by drive"
+            "all host certs in KEYDB rejected by drive (capped at {} attempts to prevent firmware wedge)",
+            MAX_CERT_ATTEMPTS
         );
-        // All host certs failed — return None, not a fake success
-        None
+        (None, Some(Error::AacsHostCertRejected))
     }
 
-    /// Resolve disc encryption — AACS 1.0, AACS 2.0, CSS, or none.
-    ///
-    /// Reads AACS files from UDF (via SectorSource), resolves keys through
-    /// whatever path works: KEYDB VUK lookup, media key derivation, processing
-    /// keys, device keys. Uses handshake result (volume ID, bus key) if available.
-    pub(super) fn resolve_encryption(
+    /// Build a keys-free AACS state that carries only the Volume ID (+ version
+    /// metadata), for callers that resolve Unit Keys out-of-band and have
+    /// disabled the local keydb. The VID is on-disc content read during the
+    /// handshake; preserving it here lets the out-of-band path use it. No keys
+    /// are present (`unit_keys` empty, `vuk` None), so the disc reports as
+    /// "encrypted, no keys" until the caller re-scans with a resolved Unit Key.
+    pub(super) fn resolve_vid_only(
         udf_fs: &udf::UdfFs,
         reader: &mut dyn SectorSource,
-        keydb_path: &std::path::Path,
         handshake: Option<&HandshakeResult>,
     ) -> Result<AacsState> {
-        use crate::aacs::{self, KeyDb};
+        use crate::aacs;
 
-        let keydb = KeyDb::load(keydb_path).map_err(|_| Error::KeydbLoad {
-            path: keydb_path.display().to_string(),
-        })?;
-
-        // Read AACS files from disc/image via UDF
         let uk_ro_data = udf_fs
             .read_file(reader, "/AACS/Unit_Key_RO.inf")
             .or_else(|_| udf_fs.read_file(reader, "/AACS/DUPLICATE/Unit_Key_RO.inf"))
             .map_err(|_| Error::AacsNoKeys)?;
+        let dh = aacs::disc_hash(&uk_ro_data);
 
-        // Log the disc hash so we can confirm whether it's present in KEYDB
-        // when key resolution fails. The disc hash is SHA-1 of the full
-        // Unit_Key_RO.inf file bytes — same value KEYDB.cfg keys VUK entries by.
-        let dh = crate::aacs::disc_hash(&uk_ro_data);
-        let dh_hex = crate::aacs::disc_hash_hex(&dh);
-        tracing::warn!(
-            target: "freemkv::disc",
-            phase = "scan_aacs_disc_hash",
-            disc_hash = %dh_hex,
-            uk_ro_len = uk_ro_data.len(),
-            "disc hash computed (compare with keydb.cfg entries)"
-        );
-
-        let cc_data = udf_fs
+        let cc = udf_fs
             .read_file(reader, "/AACS/Content000.cer")
             .or_else(|_| udf_fs.read_file(reader, "/AACS/Content001.cer"))
-            .ok();
-
-        let mkb_data = udf_fs
-            .read_file(reader, "/AACS/MKB_RW.inf")
-            .or_else(|_| udf_fs.read_file(reader, "/AACS/MKB_RO.inf"))
-            .ok();
-        let mkb_ver = mkb_data.as_deref().and_then(aacs::mkb_version);
-
-        let mkb_first_64_hex = mkb_data
+            .ok()
             .as_deref()
-            .map(|m| {
-                m.iter()
-                    .take(64)
-                    .map(|b| format!("{b:02x}"))
-                    .collect::<String>()
-            })
+            .and_then(aacs::parse_content_cert);
+        let bus_encryption = cc.as_ref().map(|c| c.bus_encryption).unwrap_or(false);
+        let version = match cc.as_ref().map(|c| c.version) {
+            Some(aacs::AacsVersion::V10) => 1,
+            Some(_) => 2,
+            None if bus_encryption => 2,
+            None => 1,
+        };
+        // MKB_RO/RW are allocated to a fixed ~128 MiB and zero-padded; trim to
+        // the real record length (same as `read_aacs_inputs`). Without this the
+        // MKB stashed on `AacsState` — which `Disc::inputs()` and the device/
+        // processing-key `decrypt_with` derivation consume, and which a key
+        // source ships to an online service — is the full 128 MiB pad, not the
+        // ~few-MB record stream.
+        let mut mkb_bytes = udf_fs
+            .read_file(reader, "/AACS/MKB_RO.inf")
+            .or_else(|_| udf_fs.read_file(reader, "/AACS/MKB_RW.inf"))
+            .ok()
             .unwrap_or_default();
+        let n = aacs::mkb_content_len(&mkb_bytes);
+        if n > 0 && n < mkb_bytes.len() {
+            mkb_bytes.truncate(n);
+        }
+        let mkb_ver = aacs::mkb_version(&mkb_bytes);
+
         tracing::warn!(
             target: "freemkv::disc",
-            phase = "scan_aacs_mkb_info",
-            mkb_present = mkb_data.is_some(),
-            mkb_len = mkb_data.as_deref().map(|m| m.len()).unwrap_or(0),
-            mkb_version = ?mkb_ver,
-            mkb_first_64 = %mkb_first_64_hex,
-            keydb_disc_count = keydb.disc_entries.len(),
-            keydb_dk_count = keydb.device_keys.len(),
-            keydb_pk_count = keydb.processing_keys.len(),
-            "AACS resolution inputs"
+            phase = "scan_aacs_vid_only",
+            disc_hash = %aacs::disc_hash_hex(&dh),
+            version,
+            bus_encryption,
+            has_vid = handshake.is_some(),
+            "keydb disabled — carrying VID only, keys resolved out-of-band"
         );
 
-        // Use handshake volume ID if available, otherwise zeros
-        // (KEYDB VUK lookup by disc hash works without volume ID)
-        let volume_id = handshake.map(|h| h.volume_id).unwrap_or([0u8; 16]);
-        let read_data_key = handshake.and_then(|h| h.read_data_key);
-
-        // Resolve: tries all available paths — KEYDB VUK, media key, processing key, device key
-        let resolved = aacs::resolve_keys(
-            &uk_ro_data,
-            cc_data.as_deref(),
-            &volume_id,
-            &keydb,
-            mkb_data.as_deref(),
-        )
-        .ok_or(Error::AacsNoKeys)?;
-
         Ok(AacsState {
-            version: if resolved.aacs2 { 2 } else { 1 },
-            bus_encryption: resolved.bus_encryption,
+            version,
+            bus_encryption,
             mkb_version: mkb_ver,
-            disc_hash: aacs::disc_hash_hex(&resolved.disc_hash),
-            key_source: match resolved.key_source {
-                1 => KeySource::KeyDb,
-                2 => KeySource::KeyDbDerived,
-                3 => KeySource::ProcessingKey,
-                4 => KeySource::DeviceKey,
-                _ => KeySource::KeyDb,
-            },
-            vuk: resolved.vuk,
-            unit_keys: resolved.unit_keys,
-            read_data_key,
-            volume_id,
+            disc_hash: aacs::disc_hash_hex(&dh),
+            key_source: KeyOrigin::ExternalUk,
+            vuk: None,
+            unit_keys: vec![],
+            read_data_key: handshake.and_then(|h| h.read_data_key),
+            volume_id: handshake.map(|h| h.volume_id).unwrap_or([0u8; 16]),
+            uk_ro: uk_ro_data,
+            mkb: mkb_bytes,
         })
     }
 }

src/disc/mapfile.rs

@@ -130,6 +130,21 @@ pub struct Mapfile {
     /// Wall-clock timestamp of the last successful `write_to_disk` (or
     /// the moment the mapfile was constructed, whichever is later).
     last_flushed: Instant,
+    /// AACS Volume ID (16 bytes) for the disc, persisted as a
+    /// `# freemkv-vid:` comment header so it survives to deferred-mux /
+    /// resume without altering the ISO payload or breaking ddrescue
+    /// data-line parsing. `None` for unencrypted / non-AACS discs.
+    ///
+    /// MUTUALLY EXCLUSIVE with `unit_keys`: a disc whose keys were resolved
+    /// persists the keys (`unit_keys`) and NOT the VID — the keys are the final
+    /// answer, so deferred-mux/resume decrypts directly with no key service. A
+    /// disc that did NOT resolve persists only the VID, the retry-able "still
+    /// need a key" marker (a future mux can re-ask the key service with it).
+    vid: Option<[u8; 16]>,
+    /// Decrypted AACS unit keys `(CPS unit, key)`, persisted as `# freemkv-uk:`
+    /// comment headers when the disc was successfully keyed. Mutually exclusive
+    /// with `vid` (see above). Empty when unresolved.
+    unit_keys: Vec<(u32, [u8; 16])>,
 }
 
 impl Mapfile {
@@ -154,6 +169,8 @@ impl Mapfile {
             },
             dirty: false,
             last_flushed: Instant::now(),
+            vid: None,
+            unit_keys: Vec::new(),
         };
         // Eager initial persist so a resume can pick this up even if
         // `record()` is never called.
@@ -168,6 +185,8 @@ impl Mapfile {
         let mut entries = Vec::new();
         let mut saw_current_line = false;
         let mut version = String::from("unknown");
+        let mut vid: Option<[u8; 16]> = None;
+        let mut unit_keys: Vec<(u32, [u8; 16])> = Vec::new();
         for line in text.lines() {
             let t = line.trim();
             if t.is_empty() {
@@ -178,6 +197,17 @@ impl Mapfile {
                 if let Some(v) = rest.strip_prefix("Rescue Logfile. Created by ") {
                     version = v.to_string();
                 }
+                if let Some(hex) = rest.strip_prefix("freemkv-vid:") {
+                    // Best-effort: a malformed or short VID comment is
+                    // ignored rather than failing the whole load.
+                    vid = parse_vid_hex(hex.trim());
+                }
+                if let Some(uk) = rest.strip_prefix("freemkv-uk:") {
+                    // `<cps>:<32hex>`. Best-effort: a malformed line is skipped.
+                    if let Some(entry) = parse_uk_line(uk.trim()) {
+                        unit_keys.push(entry);
+                    }
+                }
                 continue;
             }
             // First non-comment line is the "current" state line (pos status [pass] [pass_time]).
@@ -227,6 +257,8 @@ impl Mapfile {
             stats,
             dirty: false,
             last_flushed: Instant::now(),
+            vid,
+            unit_keys,
         })
     }
 
@@ -316,6 +348,41 @@ impl Mapfile {
         Ok(())
     }
 
+    /// Record the disc's 16-byte AACS Volume ID so it persists in the
+    /// mapfile's comment header. Marks the mapfile dirty; the next
+    /// `flush()` / `Drop` writes the `# freemkv-vid:` line. Does not
+    /// touch the ISO payload or the ddrescue data lines.
+    pub fn set_vid(&mut self, vid: [u8; 16]) {
+        self.vid = Some(vid);
+        self.dirty = true;
+    }
+
+    /// The disc's AACS Volume ID, if one was set or parsed from a
+    /// `# freemkv-vid:` comment on load. `None` for unencrypted /
+    /// non-AACS discs.
+    pub fn vid(&self) -> Option<[u8; 16]> {
+        self.vid
+    }
+
+    /// Record the disc's decrypted AACS unit keys so they persist in the
+    /// mapfile header (`# freemkv-uk:` lines). The KEYED state: a deferred-mux /
+    /// resume decrypts directly from these with no key-service round-trip.
+    /// Setting keys clears any VID — the mapfile holds keys XOR VID, never both
+    /// (keys are the final answer; VID is only the "still unresolved" marker).
+    pub fn set_unit_keys(&mut self, keys: &[(u32, [u8; 16])]) {
+        self.unit_keys = keys.to_vec();
+        if !self.unit_keys.is_empty() {
+            self.vid = None;
+        }
+        self.dirty = true;
+    }
+
+    /// The disc's decrypted AACS unit keys, if the disc was keyed (parsed from
+    /// `# freemkv-uk:` comments on load). Empty = unresolved (check `vid()`).
+    pub fn unit_keys(&self) -> &[(u32, [u8; 16])] {
+        &self.unit_keys
+    }
+
     pub fn entries(&self) -> &[MapEntry] {
         &self.entries
     }
@@ -388,6 +455,30 @@ impl Mapfile {
             let file = std::fs::File::create(&tmp)?;
             let mut w = std::io::BufWriter::new(file);
             writeln!(w, "# Rescue Logfile. Created by {}", self.version)?;
+            // VID comment lives in the header block. ddrescue treats any
+            // `#`-prefixed line as a comment, so this round-trips through
+            // our `load()` without affecting the `pos size status` data
+            // parser. 16 bytes → 32 lowercase hex chars.
+            // KEYS XOR VID: a keyed disc persists its unit keys (the final
+            // answer — deferred-mux decrypts directly); an unresolved disc
+            // persists only the VID (the retry marker, so a future mux can
+            // re-ask the key service). Never both.
+            use std::fmt::Write as _;
+            if !self.unit_keys.is_empty() {
+                for (cps, key) in &self.unit_keys {
+                    let mut hex = String::with_capacity(32);
+                    for b in key {
+                        let _ = write!(hex, "{b:02x}");
+                    }
+                    writeln!(w, "# freemkv-uk: {cps}:{hex}")?;
+                }
+            } else if let Some(vid) = self.vid {
+                let mut hex = String::with_capacity(32);
+                for b in vid {
+                    let _ = write!(hex, "{b:02x}");
+                }
+                writeln!(w, "# freemkv-vid: {hex}")?;
+            }
             writeln!(w, "# Current pos / status / pass / pass_time")?;
             writeln!(w, "0x000000000  ?  1  0")?;
             writeln!(w, "#      pos        size  status")?;
@@ -417,6 +508,31 @@ impl Drop for Mapfile {
     }
 }
 
+/// Parse a 32-char lowercase/uppercase hex string into a 16-byte VID.
+/// Returns `None` on any malformation (wrong length, non-hex) — the
+/// caller treats a bad VID comment as simply absent rather than an
+/// error, so a corrupt header never fails a mapfile load.
+fn parse_vid_hex(s: &str) -> Option<[u8; 16]> {
+    let s = s.strip_prefix("0x").unwrap_or(s);
+    if s.len() != 32 {
+        return None;
+    }
+    let mut out = [0u8; 16];
+    for (i, b) in out.iter_mut().enumerate() {
+        *b = u8::from_str_radix(&s[i * 2..i * 2 + 2], 16).ok()?;
+    }
+    Some(out)
+}
+
+/// Parse a `# freemkv-uk:` value `<cps>:<32hex>` into `(cps_unit, key)`. Returns
+/// `None` on any malformation so a corrupt line is ignored, never fatal.
+fn parse_uk_line(s: &str) -> Option<(u32, [u8; 16])> {
+    let (cps, hex) = s.split_once(':')?;
+    let cps: u32 = cps.trim().parse().ok()?;
+    let key = parse_vid_hex(hex.trim())?; // 32-hex → [u8; 16], shared parser
+    Some((cps, key))
+}
+
 fn parse_hex(s: &str) -> io::Result<u64> {
     let s = s.strip_prefix("0x").unwrap_or(s);
     u64::from_str_radix(s, 16).map_err(|_| {
@@ -583,6 +699,138 @@ mod tests {
         let _ = std::fs::remove_file(&p);
     }
 
+    #[test]
+    fn unit_keys_round_trip_and_are_mutually_exclusive_with_vid() {
+        let p = tmpfile("uk_round_trips");
+        let _ = std::fs::remove_file(&p);
+        let mut mf = Mapfile::create(&p, 1000, "test").unwrap();
+        mf.record(0, 500, SectorStatus::Finished).unwrap();
+        // Set a VID first, then unit keys: keys must WIN and clear the VID.
+        mf.set_vid([0xAA; 16]);
+        let keys: Vec<(u32, [u8; 16])> = vec![
+            (
+                0,
+                [
+                    0x57, 0x60, 0xcc, 0x83, 0x3d, 0x86, 0x0e, 0x48, 0x92, 0x1f, 0x88, 0x16, 0xe1,
+                    0x35, 0x9b, 0xad,
+                ],
+            ),
+            (1, [0x11; 16]),
+        ];
+        mf.set_unit_keys(&keys);
+        assert_eq!(
+            mf.vid(),
+            None,
+            "set_unit_keys must clear vid (keys XOR vid)"
+        );
+        mf.flush().unwrap();
+
+        let text = std::fs::read_to_string(&p).unwrap();
+        assert!(
+            text.contains("# freemkv-uk: 0:5760cc833d860e48921f8816e1359bad"),
+            "uk comment format mismatch: {text}"
+        );
+        assert!(
+            text.contains("# freemkv-uk: 1:11111111111111111111111111111111"),
+            "second uk missing: {text}"
+        );
+        assert!(
+            !text.contains("# freemkv-vid:"),
+            "VID must NOT be written when keys are present: {text}"
+        );
+
+        // load() recovers the unit keys (and no VID).
+        let loaded = Mapfile::load(&p).unwrap();
+        assert_eq!(loaded.unit_keys(), keys.as_slice());
+        assert_eq!(loaded.vid(), None);
+        assert_eq!(loaded.entries(), mf.entries());
+
+        // VID-only path (no keys) still persists the VID as the retry marker.
+        let p2 = tmpfile("uk_vid_only");
+        let _ = std::fs::remove_file(&p2);
+        let mut mf2 = Mapfile::create(&p2, 1000, "test").unwrap();
+        mf2.set_vid([0xBB; 16]);
+        mf2.flush().unwrap();
+        let loaded2 = Mapfile::load(&p2).unwrap();
+        assert_eq!(loaded2.vid(), Some([0xBB; 16]));
+        assert!(loaded2.unit_keys().is_empty());
+        let _ = std::fs::remove_file(&p);
+        let _ = std::fs::remove_file(&p2);
+    }
+
+    #[test]
+    fn vid_round_trips_and_data_lines_unaffected() {
+        let p = tmpfile("vid_round_trips");
+        let _ = std::fs::remove_file(&p);
+
+        // Build a mapfile with some data ranges, set a VID, persist.
+        let mut mf = Mapfile::create(&p, 1000, "test").unwrap();
+        mf.record(100, 200, SectorStatus::Finished).unwrap();
+        mf.record(500, 100, SectorStatus::Unreadable).unwrap();
+        mf.record(700, 50, SectorStatus::NonTrimmed).unwrap();
+        let vid: [u8; 16] = [
+            0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd,
+            0xee, 0xff,
+        ];
+        mf.set_vid(vid);
+        mf.flush().unwrap();
+
+        // The saved file must contain the VID comment in lowercase hex.
+        let text = std::fs::read_to_string(&p).unwrap();
+        assert!(
+            text.contains("# freemkv-vid:"),
+            "saved mapfile missing VID comment: {text}"
+        );
+        assert!(
+            text.contains("# freemkv-vid: 00112233445566778899aabbccddeeff"),
+            "VID comment format mismatch: {text}"
+        );
+
+        // load() recovers the VID and the identical data ranges.
+        let loaded = Mapfile::load(&p).unwrap();
+        assert_eq!(loaded.vid(), Some(vid));
+        assert_eq!(loaded.entries(), mf.entries());
+
+        // A mapfile WITHOUT the VID comment must parse the same +/-/?
+        // data ranges as the one WITH it (comment ignored by parser).
+        let p2 = tmpfile("vid_round_trips_novid");
+        let _ = std::fs::remove_file(&p2);
+        let mut mf2 = Mapfile::create(&p2, 1000, "test").unwrap();
+        mf2.record(100, 200, SectorStatus::Finished).unwrap();
+        mf2.record(500, 100, SectorStatus::Unreadable).unwrap();
+        mf2.record(700, 50, SectorStatus::NonTrimmed).unwrap();
+        mf2.flush().unwrap();
+        let loaded_novid = Mapfile::load(&p2).unwrap();
+        assert_eq!(loaded_novid.vid(), None);
+        assert_eq!(loaded_novid.entries(), loaded.entries());
+
+        // Malformed VID comments must not error the load (treated absent).
+        let mut bad = text.replace("00112233445566778899aabbccddeeff", "zzzz");
+        let pbad = tmpfile("vid_round_trips_bad");
+        let _ = std::fs::remove_file(&pbad);
+        std::fs::write(&pbad, &bad).unwrap();
+        let loaded_bad = Mapfile::load(&pbad).unwrap();
+        assert_eq!(loaded_bad.vid(), None);
+        assert_eq!(loaded_bad.entries(), loaded.entries());
+
+        // A load->save cycle preserves the VID (the patch-pass path).
+        bad.clear();
+        let resaved = tmpfile("vid_round_trips_resave");
+        let _ = std::fs::remove_file(&resaved);
+        let mut reloaded = Mapfile::load(&p).unwrap();
+        // Repoint at a fresh path and flush; mark dirty via a no-op record.
+        reloaded.path = resaved.clone();
+        reloaded.dirty = true;
+        reloaded.flush().unwrap();
+        let again = Mapfile::load(&resaved).unwrap();
+        assert_eq!(again.vid(), Some(vid));
+
+        let _ = std::fs::remove_file(&p);
+        let _ = std::fs::remove_file(&p2);
+        let _ = std::fs::remove_file(&pbad);
+        let _ = std::fs::remove_file(&resaved);
+    }
+
     #[test]
     fn stats_consistent_after_split_record() {
         let p = tmpfile("stats_consistent_after_split");

src/disc/mod.rs

@@ -882,88 +882,96 @@ pub struct AacsState {
     /// Disc hash (SHA1 of Unit_Key_RO.inf) -- hex string with 0x prefix
     pub disc_hash: String,
     /// How keys were resolved
-    pub key_source: KeySource,
-    /// Volume Unique Key (16 bytes)
-    pub vuk: [u8; 16],
+    pub key_source: KeyOrigin,
+    /// Volume Unique Key (16 bytes). `None` when keys were resolved
+    /// via the [`KeyOrigin::KeyDbUnitKeys`] path — that source delivers
+    /// pre-decrypted unit keys without a VUK to derive them from.
+    pub vuk: Option<[u8; 16]>,
     /// Decrypted unit keys (CPS unit number, key)
     pub unit_keys: Vec<(u32, [u8; 16])>,
     /// Read data key for AACS 2.0 bus decryption -- None for AACS 1.0
     pub read_data_key: Option<[u8; 16]>,
     /// Volume ID (16 bytes) -- from SCSI handshake
     pub volume_id: [u8; 16],
+    /// Raw `Unit_Key_RO.inf` bytes (encrypted unit keys + CPS map). Stashed at
+    /// scan so an external resolver (key-resolver) can derive the unit keys
+    /// from a VUK without re-reading the disc. Empty when not captured.
+    pub uk_ro: Vec<u8>,
+    /// Raw MKB bytes (`MKB_RO.inf`). Stashed at scan so an external resolver can
+    /// walk it (device/processing key → media key). Empty when not captured.
+    pub mkb: Vec<u8>,
 }
 
-/// How AACS keys were resolved.
+/// How AACS keys were resolved. Variants are ordered root-of-trust →
+/// per-disc-leaf, matching the resolver's path-try order: the resolver
+/// attempts derivation from the strongest input it has first and falls
+/// back toward pre-computed per-disc material.
 #[derive(Debug, Clone, Copy, PartialEq)]
-pub enum KeySource {
-    /// VUK found directly in KEYDB by disc hash
-    KeyDb,
-    /// Media key + Volume ID from KEYDB → derived VUK
-    KeyDbDerived,
-    /// MKB + processing keys → media key → VUK
-    ProcessingKey,
+pub enum KeyOrigin {
     /// MKB + device keys → subset-difference tree → VUK
     DeviceKey,
+    /// MKB + processing keys → media key → VUK
+    ProcessingKey,
+    /// Media key + Volume ID from KEYDB → derived VUK
+    KeyDbDerived,
+    /// VUK found directly in KEYDB by disc hash
+    KeyDb,
+    /// Pre-decrypted unit keys taken directly from KEYDB by disc hash.
+    /// No VUK present in the entry — `AacsState::vuk` is `None`.
+    KeyDbUnitKeys,
+    /// Unit key supplied directly by the caller (the external Unit Key path).
+    /// No keydb, no derivation — `AacsState::vuk` is `None`.
+    ExternalUk,
 }
 
-impl KeySource {
+impl KeyOrigin {
     pub fn name(&self) -> &'static str {
         match self {
-            KeySource::KeyDb => "KEYDB",
-            KeySource::KeyDbDerived => "KEYDB (derived)",
-            KeySource::ProcessingKey => "MKB + processing key",
-            KeySource::DeviceKey => "MKB + device key",
+            KeyOrigin::DeviceKey => "MKB + device key",
+            KeyOrigin::ProcessingKey => "MKB + processing key",
+            KeyOrigin::KeyDbDerived => "KEYDB (derived)",
+            KeyOrigin::KeyDb => "KEYDB",
+            KeyOrigin::KeyDbUnitKeys => "KEYDB (unit keys)",
+            KeyOrigin::ExternalUk => "external UK",
         }
     }
 }
 
 // ─── Disc scanning ──────────────────────────────────────────────────────────
 
-/// Standard KEYDB.cfg search locations (compatible with libaacs).
-const KEYDB_SEARCH_PATHS: &[&str] = &[
-    ".config/aacs/KEYDB.cfg",    // libaacs standard path
-    ".config/freemkv/keydb.cfg", // freemkv download path
-];
-const KEYDB_SYSTEM_PATH: &str = "/etc/aacs/KEYDB.cfg";
-
-/// Options for disc scanning.
-#[derive(Default)]
-pub struct ScanOptions {
-    /// Path to KEYDB.cfg for AACS key lookup.
-    /// If None, searches standard locations ($HOME/.config/aacs/ and /etc/aacs/).
-    pub keydb_path: Option<std::path::PathBuf>,
+/// AACS host credentials for the live-drive authenticated handshake.
+///
+/// Optional and source-agnostic: an unlocked / LibreDrive drive uses the OEM
+/// Volume-ID path and needs none, and an ISO scan has no handshake at all. The
+/// caller supplies the host cert(s) from wherever it likes — today the keydb's
+/// `host_certs()`, tomorrow a cert file or built-in. Decoupled from the key
+/// source: a locked drive needs the cert to unlock even when the decryption key
+/// comes from an online service.
+#[derive(Default, Clone)]
+pub struct DriveCredentials {
+    /// Host certificate(s) + private key(s) for the SCSI AACS handshake.
+    pub host_certs: Vec<crate::aacs::HostCert>,
 }
 
-impl ScanOptions {
-    /// Resolve KEYDB path: explicit path first, then standard locations.
-    fn resolve_keydb(&self) -> Option<std::path::PathBuf> {
-        if let Some(p) = &self.keydb_path {
-            if p.exists() {
-                return Some(p.clone());
-            }
-        }
-        if let Some(home) = std::env::var_os("HOME").or_else(|| std::env::var_os("USERPROFILE")) {
-            for relative in KEYDB_SEARCH_PATHS {
-                let p = std::path::PathBuf::from(&home).join(relative);
-                if p.exists() {
-                    return Some(p);
-                }
-            }
-        }
-        let p = std::path::PathBuf::from(KEYDB_SYSTEM_PATH);
-        if p.exists() {
-            return Some(p);
-        }
-        None
-    }
+/// Options for disc scanning.
+///
+/// libfreemkv is lookup-free — it resolves no keys. The caller resolves a key
+/// out-of-band (a key source) and applies it via [`Disc::decrypt_with`]. The
+/// only scan input is the optional drive credentials for the live-drive
+/// authenticated handshake.
+#[derive(Default)]
+pub struct ScanOptions {
+    /// Host credentials for the live-drive AACS handshake. `None` for an
+    /// unlocked / LibreDrive drive (OEM Volume-ID path) and for ISO scans.
+    pub credentials: Option<DriveCredentials>,
 }
 
 /// Quick disc identification — name, format, capacity. No title/stream parsing.
 #[derive(Debug)]
 pub struct DiscId {
-    /// UDF Volume Identifier (always present, e.g. "V_FOR_VENDETTA")
+    /// UDF Volume Identifier (always present, e.g. "SAMPLE_FILM")
     pub volume_id: String,
-    /// Disc title from META/DL/bdmt_eng.xml (e.g. "V for Vendetta")
+    /// Disc title from META/DL/bdmt_eng.xml (e.g. "Sample Film")
     pub meta_title: Option<String>,
     /// Disc format (BD, UHD, DVD) — UHD vs BD requires full scan to confirm
     pub format: DiscFormat,
@@ -1043,8 +1051,11 @@ impl Disc {
     /// The session must be open and unlocked (Drive::open handles this).
     /// All disc reads use standard READ(10) via UDF -- no vendor SCSI commands.
     pub fn scan(session: &mut Drive, opts: &ScanOptions) -> Result<Self> {
-        // AACS handshake (Blu-ray/UHD)
-        let handshake = Self::do_handshake(session, opts);
+        // AACS handshake (Blu-ray/UHD). Routes through Disc::read_vid,
+        // which prefers the per-drive OEM CDB path when the drive is
+        // in the extended-access state and falls back to cert-based
+        // mutual auth otherwise.
+        let (handshake, handshake_error) = Self::do_handshake(session, opts);
 
         // Request max read speed — removes riplock on DVD
         // (BD/UHD speed is set by firmware init, but DVD needs explicit SET CD SPEED)
@@ -1059,31 +1070,56 @@ impl Disc {
             buffered.prefetch_ranges(&ranges);
         }
 
-        let mut disc = Self::scan_with(&mut buffered, capacity, handshake, opts, udf_fs)?;
+        let mut disc = Self::scan_with(
+            &mut buffered,
+            capacity,
+            handshake,
+            handshake_error,
+            opts,
+            udf_fs,
+        )?;
 
         // CSS key extraction for DVDs (bus auth → disc key → title key).
         // Must be a single auth session — can't call authenticate() separately.
+        // Route through the DRM dispatcher: probe a title sector, detect
+        // CSS if scrambled, then load via the SCSI auth path.
         if disc.css.is_none()
             && disc.content_format == ContentFormat::MpegPs
             && !disc.titles.is_empty()
         {
-            let lba = disc.titles[0].extents.iter().find_map(|ext| {
-                let mut buf = vec![0u8; 2048];
+            let mut probe_buf = vec![0u8; 2048];
+            let auth_lba = disc.titles[0].extents.iter().find_map(|ext| {
                 if session
-                    .read_sectors(ext.start_lba, 1, &mut buf, true)
+                    .read_sectors(ext.start_lba, 1, &mut probe_buf, true)
                     .is_ok()
-                    && crate::css::is_scrambled(&buf)
                 {
-                    return Some(ext.start_lba);
+                    let probe = crate::drm::DrmProbe {
+                        dvd_sample_sector: Some(&probe_buf),
+                        content_cert: None,
+                        mkb: None,
+                    };
+                    if crate::drm::DrmScheme::detect(&probe) == Some(crate::drm::DrmScheme::Css) {
+                        return Some(ext.start_lba);
+                    }
                 }
                 None
             });
 
-            if let Some(lba) = lba {
-                if let Ok(title_key) =
-                    crate::css::auth::authenticate_and_read_title_key(session, lba)
+            if let Some(lba) = auth_lba {
+                let css_ctx = crate::css::CssContext {
+                    drive: Some(session),
+                    auth_lba: Some(lba),
+                    reader: None,
+                    extents: None,
+                };
+                let mut ctx = crate::drm::DrmContext {
+                    aacs: None,
+                    css: Some(css_ctx),
+                };
+                if let Some(crate::drm::ResolvedScheme::Css(state)) =
+                    crate::drm::DrmScheme::Css.load(&mut ctx)
                 {
-                    disc.css = Some(crate::css::CssState { title_key });
+                    disc.css = Some(state);
                     disc.encrypted = true;
                 }
             }
@@ -1100,60 +1136,95 @@ impl Disc {
         opts: &ScanOptions,
     ) -> Result<Self> {
         let udf_fs = udf::read_filesystem(reader)?;
-        Self::scan_with(reader, capacity, None, opts, udf_fs)
+        Self::scan_with(reader, capacity, None, None, opts, udf_fs)
+    }
+
+    /// Read a disc's AACS key-input files from an ISO image: returns
+    /// `(Unit_Key_RO.inf, MKB)` raw bytes. For callers that resolve a Unit Key
+    /// out-of-band: obtain the key however you like, then scan with
+    /// `ScanOptions { unit_key: Some(uk), .. }`. libfreemkv never makes a
+    /// network call.
+    pub fn read_aacs_inputs(iso_path: &std::path::Path) -> Result<(Vec<u8>, Vec<u8>)> {
+        let mut reader = crate::io::file_sector_source::FileSectorSource::open(iso_path)
+            .map_err(|_| Error::AacsNoKeys)?;
+        let udf_fs = udf::read_filesystem(&mut reader)?;
+        let inf = udf_fs
+            .read_file(&mut reader, "/AACS/Unit_Key_RO.inf")
+            .or_else(|_| udf_fs.read_file(&mut reader, "/AACS/DUPLICATE/Unit_Key_RO.inf"))
+            .map_err(|_| Error::AacsNoKeys)?;
+        // Prefer MKB_RO, fall back to MKB_RW, then TRIM to the real record
+        // length. Both files are allocated to a fixed ~128 MiB and zero-padded,
+        // so reading either ships up to ~124 MiB of nothing — trim to the
+        // record stream so callers send/store a few MB, not 128 MiB.
+        let mut mkb = udf_fs
+            .read_file(&mut reader, "/AACS/MKB_RO.inf")
+            .or_else(|_| udf_fs.read_file(&mut reader, "/AACS/MKB_RW.inf"))
+            .map_err(|_| Error::AacsNoKeys)?;
+        let n = crate::aacs::mkb_content_len(&mkb);
+        if n > 0 && n < mkb.len() {
+            mkb.truncate(n);
+        }
+        Ok((inf, mkb))
+    }
+
+    /// Same as [`Disc::read_aacs_inputs`] but reads from a live drive. The
+    /// out-of-band Unit Key path fetches the disc's key files from the drive,
+    /// resolves a key from them however it likes, then scans with
+    /// `ScanOptions { unit_key: Some(uk), .. }`. These files are plaintext UDF
+    /// metadata — no AACS handshake or keys are required to read them.
+    pub fn read_aacs_inputs_from_drive(drive: &mut Drive) -> Result<(Vec<u8>, Vec<u8>)> {
+        let (_, mut reader, udf_fs) = Self::read_udf(drive)?;
+        let inf = udf_fs
+            .read_file(&mut reader, "/AACS/Unit_Key_RO.inf")
+            .or_else(|_| udf_fs.read_file(&mut reader, "/AACS/DUPLICATE/Unit_Key_RO.inf"))
+            .map_err(|_| Error::AacsNoKeys)?;
+        // Prefer MKB_RO, fall back to MKB_RW, then TRIM to the real record
+        // length. Both files are allocated to a fixed ~128 MiB and zero-padded,
+        // so reading either ships up to ~124 MiB of nothing — trim to the
+        // record stream so callers send/store a few MB, not 128 MiB.
+        let mut mkb = udf_fs
+            .read_file(&mut reader, "/AACS/MKB_RO.inf")
+            .or_else(|_| udf_fs.read_file(&mut reader, "/AACS/MKB_RW.inf"))
+            .map_err(|_| Error::AacsNoKeys)?;
+        let n = crate::aacs::mkb_content_len(&mkb);
+        if n > 0 && n < mkb.len() {
+            mkb.truncate(n);
+        }
+        Ok((inf, mkb))
     }
 
     /// Core scan pipeline — works with any SectorSource.
+    ///
+    /// `handshake_error` is plumbed from `do_handshake` so failures
+    /// (cert rejected, raw-read unsupported, VID read failed) are
+    /// preserved as `disc.aacs_error` for callers to render. When key
+    /// resolution succeeds despite the handshake failure (built-in
+    /// keys + disc-hash lookup hit) the error is dropped.
     fn scan_with(
         reader: &mut dyn SectorSource,
         capacity: u32,
         handshake: Option<HandshakeResult>,
-        opts: &ScanOptions,
+        handshake_error: Option<Error>,
+        _opts: &ScanOptions,
         udf_fs: udf::UdfFs,
     ) -> Result<Self> {
         // 2. Resolve encryption (AACS, CSS, or none)
         let encrypted =
             udf_fs.find_dir("/AACS").is_some() || udf_fs.find_dir("/BDMV/AACS").is_some();
 
-        let (aacs, aacs_error) = if encrypted {
-            match opts.resolve_keydb() {
-                Some(keydb_path) => {
-                    match Self::resolve_encryption(&udf_fs, reader, &keydb_path, handshake.as_ref())
-                    {
-                        Ok(state) => (Some(state), None),
-                        Err(e) => {
-                            tracing::warn!(
-                                target: "freemkv::disc",
-                                phase = "scan_aacs_resolve_failed",
-                                error_code = e.code(),
-                                keydb = %keydb_path.display(),
-                                handshake_ok = handshake.is_some(),
-                                "AACS key resolution failed"
-                            );
-                            (None, Some(e))
-                        }
-                    }
-                }
-                None => {
-                    tracing::warn!(
-                        target: "freemkv::disc",
-                        phase = "scan_aacs_no_keydb",
-                        "encrypted disc but no KEYDB found in search paths"
-                    );
-                    // Reuse KeydbLoad with sentinel path — adding a new Error
-                    // variant would be a breaking change for downstream
-                    // exhaustive matches. The path string makes the cause
-                    // unambiguous to autorip's message switch.
-                    (
-                        None,
-                        Some(crate::error::Error::KeydbLoad {
-                            path: String::from("<no keydb in search paths>"),
-                        }),
-                    )
-                }
-            }
-        } else {
+        let (aacs, aacs_error) = if !encrypted {
             (None, None)
+        } else {
+            // Lookup-free: capture the disc's AACS inputs (MKB, VID,
+            // Unit_Key_RO.inf) but resolve NO key. The caller resolves a Key
+            // from a key source and applies it via `Disc::decrypt_with`. The
+            // disc reports "encrypted, no keys" until then.
+            match Self::resolve_vid_only(&udf_fs, reader, handshake.as_ref()) {
+                Ok(state) => (Some(state), None),
+                // A handshake failure (no VID) is more actionable than the
+                // generic capture error, so surface it when present.
+                Err(e) => (None, Some(handshake_error.unwrap_or(e))),
+            }
         };
 
         // 3. Titles — BD (MPLS playlists) or DVD (IFO title sets)
@@ -1190,9 +1261,27 @@ impl Disc {
         let layers = if capacity > 24_000_000 { 2 } else { 1 };
         let region = DiscRegion::Free;
 
-        // 6. CSS detection for DVDs
+        // 6. CSS detection for DVDs — route through the DRM dispatcher.
+        //    Detection from a single probe sector would miss
+        //    DVDs whose first sector is unscrambled, so we go straight
+        //    to `DrmScheme::Css.load` with the crack-path context; the
+        //    crack path scans extents internally and bottoms out at
+        //    None on unencrypted media.
         let css = if content_format == ContentFormat::MpegPs && !titles.is_empty() {
-            crate::css::crack_key(reader, &titles[0].extents)
+            let css_ctx = crate::css::CssContext {
+                drive: None,
+                auth_lba: None,
+                reader: Some(reader),
+                extents: Some(&titles[0].extents),
+            };
+            let mut ctx = crate::drm::DrmContext {
+                aacs: None,
+                css: Some(css_ctx),
+            };
+            match crate::drm::DrmScheme::Css.load(&mut ctx) {
+                Some(crate::drm::ResolvedScheme::Css(s)) => Some(s),
+                _ => None,
+            }
         } else {
             None
         };
@@ -1313,11 +1402,60 @@ impl Disc {
     }
 }
 
+/// A decryption key handed to libfreemkv by the caller.
+///
+/// libfreemkv is **lookup-free**: it never reads a keydb, never talks to a key
+/// server, never searches paths. The application resolves a key from whatever
+/// source it likes (a local keydb, an online key service, a mapfile cache) and
+/// hands it in here; libfreemkv uses it to decrypt, deriving any remaining
+/// AACS-chain steps it can from disc-read inputs (MKB / VID / `Unit_Key_RO.inf`).
+///
+/// `#[non_exhaustive]`: AACS is a derivation chain
+/// (`DK →(MKB)→ MK →(VID)→ VK →(Unit_Key_RO)→ UK`). Each variant is an entry
+/// point at one level of that chain; [`Disc::decrypt_with`] derives down from
+/// it to the per-CPS unit keys. New levels can be added without breaking
+/// callers.
+#[derive(Debug, Clone)]
+#[non_exhaustive]
+pub enum Key {
+    /// Device key(s) (AACS DK, positioned). libfreemkv walks the MKB
+    /// (subset-difference tree) to find the one that applies → media key →
+    /// VUK → unit keys. A source hands in its FULL device-key set, because
+    /// choosing which one applies *is* the MKB walk (derivation), and all
+    /// derivation lives here — never in a source.
+    Device(Vec<crate::aacs::keydb::DeviceKey>),
+    /// Processing key(s) (AACS PK). libfreemkv applies each against the MKB
+    /// → media key → VUK → unit keys.
+    Processing(Vec<[u8; 16]>),
+    /// Media key candidate(s) (Km). A source hands its full pool because an MK
+    /// is MKB-scoped (shared across a pressing/MKB family) — picking the one
+    /// that applies is `km_verifies` against this disc's MKB, which is
+    /// derivation, so it lives here. libfreemkv verifies, then derives the VUK
+    /// via the Volume ID and the per-CPS-unit keys.
+    Media(Vec<[u8; 16]>),
+    /// Volume Unique Key (VK / VUK). libfreemkv decrypts `Unit_Key_RO.inf`
+    /// into the per-CPS-unit keys. NOT terminal — the chain continues to the
+    /// unit keys.
+    Volume([u8; 16]),
+    /// Final per-CPS-unit AACS keys (`(cps_unit, 16-byte key)`). A key source
+    /// (keydb / key server) resolved these, or they were cached in the mapfile
+    /// at sweep; libfreemkv decrypts directly with no further derivation. This
+    /// is the terminal level every other variant derives down into.
+    Unit(Vec<(u32, [u8; 16])>),
+}
+
 impl Disc {
     /// Get the resolved decryption keys for this disc.
     /// Used by disc-to-ISO and other full-disc operations.
     pub fn decrypt_keys(&self) -> crate::decrypt::DecryptKeys {
         if let Some(ref aacs) = self.aacs {
+            // An AACS state with NO unit keys is "encrypted, no keys" — e.g.
+            // the VID-only state from out-of-band resolution before a Unit Key
+            // is supplied. Report None so callers treat it as missing keys
+            // (not a usable, empty key set).
+            if aacs.unit_keys.is_empty() {
+                return crate::decrypt::DecryptKeys::None;
+            }
             crate::decrypt::DecryptKeys::Aacs {
                 unit_keys: aacs.unit_keys.clone(),
                 read_data_key: aacs.read_data_key,
@@ -1331,6 +1469,152 @@ impl Disc {
         }
     }
 
+    /// Inject pre-resolved AACS unit keys into a scanned disc — the deferred-mux
+    /// / resume path. The keys come from the mapfile's `# freemkv-uk:` header
+    /// (persisted at sweep time when the disc was keyed), so the mux decrypts
+    /// directly with NO key-service round-trip. Populates `self.aacs.unit_keys`
+    /// so [`decrypt_keys`] returns them and marks the source `ExternalUk`.
+    ///
+    /// If the scan built no AACS state (`self.aacs == None`) — which happens
+    /// when the keydb was absent at scan time (`scan_aacs_no_keydb` →
+    /// `aacs_error = KeydbLoad`) — this synthesizes a minimal `ExternalUk`
+    /// state for an encrypted AACS disc. A Unit Key is the FINAL per-title
+    /// decryption key; the keydb is only needed to *derive* it, and that
+    /// derivation already happened at sweep (the UK is in the mapfile). So a UK
+    /// alone is sufficient to decrypt the on-disk ISO — AACS 2.0 bus decryption
+    /// was applied by the drive at read time, so `read_data_key` is unused for
+    /// file-backed mux. Without this, a keyed disc swept without a keydb would
+    /// recover its UK yet still report E8005 (no usable `decrypt_keys`) at
+    /// remux. No-op for an unencrypted or CSS (DVD) disc.
+    pub fn inject_unit_keys(&mut self, keys: Vec<(u32, [u8; 16])>) {
+        if let Some(aacs) = self.aacs.as_mut() {
+            aacs.unit_keys = keys;
+            aacs.key_source = KeyOrigin::ExternalUk;
+        } else if self.encrypted && self.css.is_none() {
+            self.aacs = Some(AacsState {
+                version: if self.format == DiscFormat::Uhd { 2 } else { 1 },
+                bus_encryption: self.format == DiscFormat::Uhd,
+                mkb_version: None,
+                disc_hash: String::new(),
+                key_source: KeyOrigin::ExternalUk,
+                vuk: None,
+                unit_keys: keys,
+                read_data_key: None,
+                volume_id: [0u8; 16],
+                uk_ro: Vec::new(),
+                mkb: Vec::new(),
+            });
+            // The prior resolution error (e.g. KeydbLoad) is now moot — we have
+            // the decryption key. Clear it so callers don't treat the disc as
+            // keyless on the stale error.
+            self.aacs_error = None;
+        }
+    }
+
+    /// The public AACS inputs for this disc, for a [`crate::KeySource`] to look
+    /// a key up. `None` when the disc carries no AACS state (unencrypted, CSS,
+    /// or AACS inputs not captured at scan). Contains no secrets — just disc
+    /// identity plus the on-disc AACS structures.
+    pub fn inputs(&self) -> Option<crate::keysource::DiscInputs> {
+        self.aacs.as_ref().map(|a| crate::keysource::DiscInputs {
+            disc_hash: a.disc_hash.clone(),
+            volume_id: a.volume_id,
+            mkb: a.mkb.clone(),
+            unit_key_ro: a.uk_ro.clone(),
+            // Content samples need the disc reader, which scan does not retain;
+            // the caller fills these for sources that validate against ciphertext.
+            samples: Vec::new(),
+        })
+    }
+
+    /// Apply a caller-resolved [`Key`] so [`Self::decrypt_keys`] yields usable
+    /// decryption state. **Lookup-free**: no keydb, no network — the caller
+    /// (an application, via a key source) does all resolution and hands the key
+    /// in here. For [`Key::Unit`] this is the deferred-mux / resume path: the
+    /// unit keys came from a key source or the mapfile cache, and libfreemkv
+    /// decrypts directly (see [`Self::inject_unit_keys`]).
+    pub fn decrypt_with(&mut self, key: Key) -> Result<()> {
+        // Unit keys are terminal — no derivation. Inject directly (resume /
+        // mapfile cache / a source that already had the final UKs).
+        if let Key::Unit(keys) = key {
+            self.inject_unit_keys(keys);
+            return Ok(());
+        }
+
+        // Every higher level derives DOWN to the unit keys, reusing the
+        // version-dispatched resolver — the single home for all AACS
+        // derivation (1.0 / 2.0 / 2.1 / 2.x). It needs the AACS inputs
+        // (Unit_Key_RO.inf, MKB, VID) stashed on the disc at scan time.
+        let aacs = self.aacs.as_ref().ok_or(crate::error::Error::AacsNoKeys)?;
+        if aacs.uk_ro.is_empty() {
+            // Scan captured no Unit_Key_RO.inf — nothing to derive into.
+            return Err(crate::error::Error::AacsNoKeys);
+        }
+
+        // Map the supplied Key -> raw material. The source handed in material
+        // at exactly one level; choosing/applying it is the resolver's job.
+        let mut supplied = crate::aacs::provider::SuppliedKey {
+            device_keys: Vec::new(),
+            processing_keys: Vec::new(),
+            media_keys: Vec::new(),
+            disc_entry: None,
+        };
+        match key {
+            Key::Device(dks) => supplied.device_keys = dks,
+            Key::Processing(pks) => supplied.processing_keys = pks,
+            Key::Media(mks) => supplied.media_keys = mks,
+            Key::Volume(vuk) => {
+                supplied.disc_entry = Some(crate::aacs::DiscEntry {
+                    disc_hash: aacs.disc_hash.clone(),
+                    title: String::new(),
+                    media_key: None,
+                    disc_id: None,
+                    vuk: Some(vuk),
+                    unit_keys: Vec::new(),
+                });
+            }
+            Key::Unit(_) => unreachable!("Key::Unit handled above"),
+        }
+
+        // Snapshot inputs (releases the &self borrow before the &mut below).
+        let volume_id = aacs.volume_id;
+        let mkb = aacs.mkb.clone();
+        let uk_ro = aacs.uk_ro.clone();
+        let version_u8 = aacs.version;
+
+        let provider_refs: [&dyn crate::aacs::KeyProvider; 1] = [&supplied];
+        let ctx = crate::aacs::ResolveContext {
+            unit_key_ro: &uk_ro,
+            content_cert: None,
+            volume_id: &volume_id,
+            providers: &provider_refs,
+            mkb: if mkb.is_empty() { None } else { Some(&mkb) },
+        };
+
+        // Version dispatch — V10 uses the classical resolver at 48-byte
+        // stride; V20/V21 share the 64-byte stride, so try the classical V20
+        // paths first and fall back to the 2.1 variant chain.
+        let resolved = match version_u8 {
+            1 => crate::aacs::resolve_keys_v1(&ctx),
+            _ => crate::aacs::resolve_keys_v2(&ctx).or_else(|| crate::aacs::resolve_keys_v21(&ctx)),
+        }
+        .ok_or(crate::error::Error::AacsKeyRejected)?;
+
+        if resolved.unit_keys.is_empty() {
+            return Err(crate::error::Error::AacsKeyRejected);
+        }
+
+        let a = self.aacs.as_mut().expect("aacs present (checked above)");
+        a.unit_keys = resolved.unit_keys;
+        if resolved.vuk.is_some() {
+            a.vuk = resolved.vuk;
+        }
+        a.key_source = KeyOrigin::ExternalUk;
+        // A prior scan-time resolution error (e.g. keyless scan) is now moot.
+        self.aacs_error = None;
+        Ok(())
+    }
+
     /// Copy disc sectors to an ISO image file.
     ///
     /// NOT a stream operation. Copies sectors byte-for-byte producing a valid
@@ -1415,6 +1699,8 @@ impl Disc {
             skip_on_error: opts.multipass,
             progress: opts.progress,
             halt: opts.halt.clone(),
+            vid: opts.vid,
+            unit_keys: opts.unit_keys.clone(),
         };
         self.sweep(reader, path, &sweep_opts)
     }
@@ -1506,13 +1792,24 @@ impl Disc {
         if !opts.resume {
             let _ = std::fs::remove_file(&mapfile_path);
         }
-        let map = mapfile::Mapfile::open_or_create(
+        let mut map = mapfile::Mapfile::open_or_create(
             &mapfile_path,
             total_bytes,
             concat!("libfreemkv v", env!("CARGO_PKG_VERSION")),
         )
         .map_err(|e| Error::IoError { source: e })?;
 
+        // Persist the disc's decryption state into the mapfile header so it
+        // survives to deferred-mux / resume. ddrescue-safe (comment lines);
+        // does not touch the ISO payload. KEYS XOR VID: a keyed disc writes its
+        // unit keys (the final answer — deferred-mux decrypts directly, no key
+        // service); an unresolved disc writes only the VID (the retry marker).
+        if !opts.unit_keys.is_empty() {
+            map.set_unit_keys(&opts.unit_keys);
+        } else if let Some(vid) = opts.vid {
+            map.set_vid(vid);
+        }
+
         // ISO file: if resuming and mapfile has Finished ranges, open existing;
         // otherwise create fresh and pre-size to total_bytes (sparse holes for
         // non-tried regions).
@@ -1984,6 +2281,19 @@ pub struct CopyOptions<'a> {
     pub multipass: bool,
     pub progress: Option<&'a dyn crate::progress::Progress>,
     pub halt: Option<std::sync::Arc<std::sync::atomic::AtomicBool>>,
+    /// AACS Volume ID (16 bytes) to persist into the mapfile during
+    /// Pass 1 so it survives to deferred-mux / resume. `None` for
+    /// unencrypted / non-AACS discs. Caller wires this from
+    /// `Disc::aacs.volume_id`.
+    ///
+    /// Persisted ONLY when `unit_keys` is empty (the disc didn't resolve a
+    /// key): the VID is the "still unresolved, retry-able" marker.
+    pub vid: Option<[u8; 16]>,
+    /// Resolved AACS unit keys `(CPS unit, key)` to persist into the mapfile
+    /// during Pass 1. When non-empty these are written (the final answer, so
+    /// deferred-mux/resume decrypts directly) and the VID is NOT — keys XOR VID.
+    /// Caller wires this from `Disc::aacs.unit_keys`.
+    pub unit_keys: Vec<(u32, [u8; 16])>,
 }
 
 #[derive(Debug, Clone, Copy)]
@@ -2005,6 +2315,13 @@ pub struct SweepOptions<'a> {
     pub skip_on_error: bool,
     pub progress: Option<&'a dyn crate::progress::Progress>,
     pub halt: Option<std::sync::Arc<std::sync::atomic::AtomicBool>>,
+    /// AACS Volume ID (16 bytes) persisted into the mapfile when the
+    /// sweep creates / opens it. `None` for unencrypted discs. Written ONLY
+    /// when `unit_keys` is empty (keys XOR VID — the VID is the retry marker).
+    pub vid: Option<[u8; 16]>,
+    /// Resolved AACS unit keys persisted into the mapfile when the sweep
+    /// creates / opens it. When non-empty these win over `vid`.
+    pub unit_keys: Vec<(u32, [u8; 16])>,
 }
 
 /// Options for [`Disc::patch`] (Pass N retry pass over bad ranges).
@@ -2499,6 +2816,229 @@ mod tests {
         }
     }
 
+    #[test]
+    fn inject_unit_keys_synthesizes_aacs_state_when_scan_built_none() {
+        // Regression (E8005 deferred-mux loop): a keyed AACS disc swept WITHOUT a
+        // keydb scans to aacs=None + aacs_error=KeydbLoad, but its UK is persisted
+        // in the mapfile. At remux the UK is recovered and injected — that MUST
+        // yield usable decrypt keys. Before the fix, inject_unit_keys no-op'd
+        // (no aacs to mutate), decrypt_keys stayed None, and the mux deferred
+        // forever with "No keys available (E8005)" despite holding the UK.
+        let mut disc = make_test_disc(1000, "UHD");
+        disc.encrypted = true;
+        disc.aacs_error = Some(crate::error::Error::KeydbLoad {
+            path: "<no keydb in search paths>".into(),
+        });
+        assert!(
+            matches!(disc.decrypt_keys(), crate::decrypt::DecryptKeys::None),
+            "precondition: encrypted disc with no aacs state => no decrypt keys"
+        );
+
+        let uk = vec![(0u32, [0x11u8; 16])];
+        disc.inject_unit_keys(uk.clone());
+
+        match disc.decrypt_keys() {
+            crate::decrypt::DecryptKeys::Aacs {
+                unit_keys,
+                read_data_key,
+            } => {
+                assert_eq!(unit_keys, uk, "injected UK must be the decrypt key");
+                assert_eq!(read_data_key, None, "ISO mux needs no bus key");
+            }
+            _ => panic!("expected Aacs decrypt keys after injecting a UK"),
+        }
+        assert!(
+            disc.aacs_error.is_none(),
+            "stale KeydbLoad must be cleared once a UK is in hand"
+        );
+        assert_eq!(
+            disc.aacs.as_ref().unwrap().key_source,
+            KeyOrigin::ExternalUk
+        );
+    }
+
+    /// Build an AacsState carrying the given unit keys (other fields are inert
+    /// defaults — these tests only exercise the unit-key/decrypt-keys plumbing).
+    fn aacs_with(unit_keys: Vec<(u32, [u8; 16])>) -> AacsState {
+        AacsState {
+            version: 2,
+            bus_encryption: true,
+            mkb_version: None,
+            disc_hash: String::new(),
+            key_source: KeyOrigin::DeviceKey,
+            vuk: None,
+            unit_keys,
+            read_data_key: None,
+            volume_id: [0u8; 16],
+            uk_ro: Vec::new(),
+            mkb: Vec::new(),
+        }
+    }
+
+    #[test]
+    fn decrypt_keys_none_when_aacs_present_but_unit_keys_empty() {
+        // VID-only state (resolved but no Unit Key yet) must read as None, not
+        // an empty-but-usable key set — callers treat it as "keys missing".
+        let mut disc = make_test_disc(1000, "UHD");
+        disc.encrypted = true;
+        disc.aacs = Some(aacs_with(Vec::new()));
+        assert!(matches!(
+            disc.decrypt_keys(),
+            crate::decrypt::DecryptKeys::None
+        ));
+    }
+
+    #[test]
+    fn decrypt_with_replaces_existing_aacs_unit_keys_and_marks_external() {
+        // When scan DID build an AACS state, decrypt_with must overwrite its
+        // unit keys (not append) and mark the source ExternalUk.
+        let mut disc = make_test_disc(1000, "UHD");
+        disc.encrypted = true;
+        disc.aacs = Some(aacs_with(vec![(0, [0x01; 16])]));
+        let new = vec![(0u32, [0x77u8; 16]), (1, [0x88; 16])];
+        disc.decrypt_with(Key::Unit(new.clone())).unwrap();
+        match disc.decrypt_keys() {
+            crate::decrypt::DecryptKeys::Aacs { unit_keys, .. } => {
+                assert_eq!(unit_keys, new, "must replace, preserving every CPS unit");
+            }
+            _ => panic!("expected Aacs decrypt keys"),
+        }
+        assert_eq!(
+            disc.aacs.as_ref().unwrap().key_source,
+            KeyOrigin::ExternalUk
+        );
+    }
+
+    /// Build a minimal valid `Unit_Key_RO.inf` carrying the given encrypted
+    /// unit keys at the V20 (64-byte) stride. Header is inert (no titles); only
+    /// the key-storage area matters for `parse_unit_key_ro`.
+    fn uk_ro_v20(enc_keys: &[[u8; 16]]) -> Vec<u8> {
+        let uk_pos = 32usize;
+        let keys_start = uk_pos + 48;
+        let stride = 64usize;
+        let mut data = vec![0u8; keys_start + enc_keys.len().max(1) * stride];
+        data[0..4].copy_from_slice(&(uk_pos as u32).to_be_bytes());
+        data[uk_pos..uk_pos + 2].copy_from_slice(&(enc_keys.len() as u16).to_be_bytes());
+        for (i, k) in enc_keys.iter().enumerate() {
+            let off = keys_start + i * stride;
+            data[off..off + 16].copy_from_slice(k);
+        }
+        data
+    }
+
+    #[test]
+    fn decrypt_with_volume_derives_per_cps_unit_keys() {
+        // A Volume key (VUK) is NOT terminal — the lib must decrypt
+        // Unit_Key_RO.inf into ONE unit key per CPS unit. Oracle = the lib's
+        // own decrypt_unit_key, so this pins the derive-down WIRING (Volume →
+        // per-CPS Unit), not the cipher.
+        let vuk = [0x5au8; 16];
+        let enc0 = [0x12u8; 16];
+        let enc1 = [0x34u8; 16];
+        let exp0 = crate::aacs::decrypt_unit_key(&vuk, &enc0);
+        let exp1 = crate::aacs::decrypt_unit_key(&vuk, &enc1);
+
+        let mut disc = make_test_disc(1000, "UHD");
+        disc.encrypted = true;
+        let mut a = aacs_with(Vec::new());
+        a.uk_ro = uk_ro_v20(&[enc0, enc1]);
+        disc.aacs = Some(a);
+
+        disc.decrypt_with(Key::Volume(vuk)).unwrap();
+        match disc.decrypt_keys() {
+            crate::decrypt::DecryptKeys::Aacs { unit_keys, .. } => {
+                assert_eq!(
+                    unit_keys,
+                    vec![(1u32, exp0), (2u32, exp1)],
+                    "VUK must decrypt EACH CPS unit's encrypted key (does not stop at VK)"
+                );
+            }
+            _ => panic!("expected Aacs decrypt keys after Volume-key derive-down"),
+        }
+        assert_eq!(
+            disc.aacs.as_ref().unwrap().key_source,
+            KeyOrigin::ExternalUk
+        );
+    }
+
+    #[test]
+    fn decrypt_with_higher_key_without_inputs_errors() {
+        // A non-Unit key needs the AACS inputs (Unit_Key_RO.inf) stashed at
+        // scan. Without them the lib cannot derive — surfaces AacsNoKeys, not a
+        // panic and not a silent keyless "success".
+        let mut disc = make_test_disc(1000, "UHD");
+        disc.encrypted = true;
+        disc.aacs = Some(aacs_with(Vec::new())); // uk_ro empty
+        assert!(matches!(
+            disc.decrypt_with(Key::Volume([0x11u8; 16])).unwrap_err(),
+            crate::error::Error::AacsNoKeys
+        ));
+
+        // No AACS state at all → same.
+        let mut disc2 = make_test_disc(1000, "UHD");
+        disc2.encrypted = true;
+        assert!(matches!(
+            disc2
+                .decrypt_with(Key::Media(vec![[0x22u8; 16]]))
+                .unwrap_err(),
+            crate::error::Error::AacsNoKeys
+        ));
+    }
+
+    #[test]
+    fn decrypt_with_volume_yielding_no_units_is_rejected() {
+        // A key that produces zero unit keys (here: an empty key-storage area)
+        // is a rejection, not a silent empty success.
+        let mut disc = make_test_disc(1000, "UHD");
+        disc.encrypted = true;
+        let mut a = aacs_with(Vec::new());
+        a.uk_ro = uk_ro_v20(&[]); // num_uk = 0
+        disc.aacs = Some(a);
+        assert!(matches!(
+            disc.decrypt_with(Key::Volume([0x11u8; 16])).unwrap_err(),
+            crate::error::Error::AacsKeyRejected
+        ));
+    }
+
+    #[test]
+    fn decrypt_with_unit_key_yields_decrypt_keys() {
+        // The public lookup-free entry point: hand libfreemkv a Key::Unit and
+        // decrypt_keys() must return usable AACS state (same path as the
+        // deferred-mux resume — autorip resolves the UK and passes it in).
+        let mut disc = make_test_disc(1000, "UHD");
+        disc.encrypted = true;
+        let uk = vec![(0u32, [0x44u8; 16])];
+        disc.decrypt_with(Key::Unit(uk.clone())).unwrap();
+        match disc.decrypt_keys() {
+            crate::decrypt::DecryptKeys::Aacs { unit_keys, .. } => {
+                assert_eq!(unit_keys, uk);
+            }
+            _ => panic!("expected Aacs decrypt keys after decrypt_with(Key::Unit)"),
+        }
+    }
+
+    #[test]
+    fn inject_unit_keys_is_noop_without_aacs_on_unencrypted_or_css() {
+        // Unencrypted disc: nothing to inject into, stays None.
+        let mut plain = make_test_disc(1000, "PLAIN");
+        plain.inject_unit_keys(vec![(0, [0x22; 16])]);
+        assert!(plain.aacs.is_none());
+        assert!(matches!(
+            plain.decrypt_keys(),
+            crate::decrypt::DecryptKeys::None
+        ));
+
+        // Encrypted CSS (DVD): an AACS UK must NOT synthesize an AACS state.
+        let mut dvd = make_test_disc(1000, "DVD");
+        dvd.format = DiscFormat::Dvd;
+        dvd.encrypted = true;
+        dvd.css = Some(crate::css::CssState {
+            title_key: [0u8; 5],
+        });
+        dvd.inject_unit_keys(vec![(0, [0x33; 16])]);
+        assert!(dvd.aacs.is_none(), "CSS disc must not gain an AACS state");
+    }
+
     #[test]
     fn sweep_to_dev_null_no_enodev() {
         let tmp = tempfile::tempdir().unwrap();
@@ -2515,6 +3055,8 @@ mod tests {
             multipass: true,
             progress: None,
             halt: None,
+            vid: None,
+            unit_keys: Vec::new(),
         };
         let result = disc.copy(&mut reader, &iso_path, &opts);
         assert!(
@@ -2539,6 +3081,8 @@ mod tests {
             multipass: true,
             progress: None,
             halt: None,
+            vid: None,
+            unit_keys: Vec::new(),
         };
         let result = disc.copy(&mut reader, std::path::Path::new("/dev/null"), &opts);
         assert!(
@@ -2569,6 +3113,8 @@ mod tests {
             multipass: false,
             progress: None,
             halt: None,
+            vid: None,
+            unit_keys: Vec::new(),
         };
         let result = disc.copy(&mut reader, std::path::Path::new("/dev/null"), &opts);
         assert!(
@@ -2598,6 +3144,8 @@ mod tests {
             multipass: true,
             progress: None,
             halt: None,
+            vid: None,
+            unit_keys: Vec::new(),
         };
         let sweep_result = disc.copy(&mut reader, &iso_path, &sweep_opts);
         assert!(
@@ -2615,6 +3163,8 @@ mod tests {
             multipass: true,
             progress: None,
             halt: None,
+            vid: None,
+            unit_keys: Vec::new(),
         };
         let patch_result = disc.copy(&mut reader2, &iso_path, &patch_opts);
         assert!(
@@ -2647,6 +3197,8 @@ mod tests {
             multipass: true,
             progress: None,
             halt: None,
+            vid: None,
+            unit_keys: Vec::new(),
         };
         let _sweep_result = disc.copy(&mut reader, &iso_path, &sweep_opts).unwrap();
 
@@ -2659,6 +3211,8 @@ mod tests {
             multipass: true,
             progress: None,
             halt: None,
+            vid: None,
+            unit_keys: Vec::new(),
         };
         let patch_result = disc.copy(&mut reader2, std::path::Path::new("/dev/null"), &patch_opts);
         assert!(
@@ -2691,6 +3245,8 @@ mod tests {
             multipass: false,
             progress: None,
             halt: None,
+            vid: None,
+            unit_keys: Vec::new(),
         };
         let result = disc.copy(&mut reader, &iso_path, &opts);
         let r = result.expect("100-batch clean sweep should succeed");