v0.28.1: bump version

mux: wire TrueHD channel probe into iso:// mux setup
correct_truehd_channels() probes the first DECRYPTED access units of the chosen title (TrueHD PIDs, bounded 8 MiB read of the first extent) and sets AudioStream.channels from the MLP major sync — fixing the MPLS audio_format understatement (5.1 declared on a 7.1/Atmos TrueHD track). Regenerates the basic codec label for the corrected count; richer editorial labels are left untouched. Wired in resolve.rs input() for iso:// after decrypt_with (the m2ts is only decryptable post-key), using a fresh reader so the mux reader is undisturbed. generate_audio_label made pub(crate).
2026-10-07 18:13:10 +00:00 · 2026-06-04 21:46:41 -07:00 · 2026-06-04 20:28:37 -07:00 · 2026-06-04 19:51:46 -07:00 · 2026-06-04 19:42:14 -07:00 · 2026-06-04 19:28:34 -07:00
42 changed files with 2830 additions and 710 deletions
@@ -5,3 +5,6 @@ Cargo.lock
 .DS_Store
 .cargo/
 .claude/worktrees/
+
+# session scratch — never track (may contain RE breadcrumbs)
+scratch/
@@ -1,5 +1,34 @@
 # 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
@@ -79,17 +108,17 @@ No behavioural change — purely a rename pass.
 - **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 firmware-uploaded
-  drives would serve VID without auth. Empirical test on rip1 (BU40N
-  + Barbie UHD, 2026-05-21) showed the drive returns
+  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
-  firmware-upload state. The AACS spec requires a successful
+  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
-  Barbie scans were stuck at E7017 instead of progressing to the
+  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
@@ -98,7 +127,7 @@ No behavioural change — purely a rename pass.
 - `read_volume_id_libredrive` deleted (~50 LOC).

 The corollary: AACS resolution on HRL-burned drives + UHD discs now
-fails honestly. Either cert auth succeeds (firmware-upload may or
+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
@@ -224,7 +253,7 @@ 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 on rip1 2026-05-20 during a Barbie UHD scan
+Live wedge event 2026-05-20 during a UHD disc scan
 (KEYDB miss) confirmed the diagnosis and motivated this fix.

 Defence-in-depth:
@@ -335,7 +364,7 @@ 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 rip1 testbed (Civil_War UHD, 62 GiB ISO →
+**Throughput on the test bed (a UHD disc, 62 GiB ISO →
 `null://`, single-thread caller):**

 |                                       |   MB/s |
@@ -485,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
@@ -766,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
@@ -894,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)

@@ -922,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
@@ -964,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.
@@ -1036,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.
@@ -1065,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`,
@@ -1083,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,
@@ -1096,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
@@ -1138,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 /
@@ -1265,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
@@ -1313,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
@@ -1357,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.
@@ -1412,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.

@@ -1441,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
@@ -1474,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.

@@ -2361,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
@@ -2379,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)

@@ -1,6 +1,6 @@
 [package]
 name = "libfreemkv"
-version = "0.26.1"
+version = "0.28.1"
 edition = "2024"
 rust-version = "1.86"
 license = "AGPL-3.0-only"
@@ -31,8 +31,7 @@ tracing = "0.1"
 # Bounded MPSC channel with kernel-wakeup send_timeout. Used by `io::pipeline`
 # so the halt-aware send/finish loops can BLOCK on consumer drain instead of
 # polling — the 50 ms poll cadence of the previous mpsc-based impl capped mux
-# throughput at ~1 MB/s (see (internal)/memory/
-# feedback_send_with_halt_poll_throttle.md, 0.21.7).
+# throughput at ~1 MB/s (0.21.7).
 crossbeam-channel = "0.5"
 # Persistent work-stealing thread pool for parallel AACS unit
 # decryption. Per-call std::thread::scope spawned fresh OS threads
@@ -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

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

@@ -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;
@@ -117,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;
            }
@@ -195,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();
@@ -229,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
@@ -377,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);
    }

@@ -416,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",
@@ -1,7 +1,7 @@
 //! AACS key resolution — VUK derivation, MKB processing, disc hash, unit key parsing.

 use super::decrypt::aes_ecb_decrypt;
-use super::keydb::{DeviceKey, KeyDb};
+use super::keydb::DeviceKey;

 // ── AACS version ────────────────────────────────────────────────────────────

@@ -205,21 +205,59 @@ pub fn parse_unit_key_ro(data: &[u8], version: AacsVersion) -> Option<UnitKeyFil
 ///   Record type 0x81 = Verify Media Key Record, AACS 1.0 (has mk_dv)
 ///   Record type 0x86 = Verify Media Key Record, AACS 2.0/2.1 (has mk_dv)
 ///   Record type 0x04 = Subset-Difference Index (has UVS entries)
-///   Record type 0x07 = Explicit Subset-Difference Record (has cvalues)
+///   Record type 0x05 = Media Key Data Record (cvalues, 1:1 with 0x04)
+///   Record type 0x07 = Explicit Subset-Difference Record (NOT cvalues)
 pub fn derive_media_key_from_pk(mkb: &[u8], processing_keys: &[[u8; 16]]) -> Option<[u8; 16]> {
-    // Parse MKB records
+    derive_media_key_from_pk_walked(mkb, processing_keys, PK_WALK_MAX_DEPTH)
+}
+
+/// SD-tree walk depth applied to every entry in `processing_keys`.
+///
+/// Each entry is treated as a node-key (label) at unknown depth. The
+/// resolver applies `AES-G3(K, 1)` to derive the PK at this node, then
+/// descends via `AES-G3(K, 0)` (left child) and `AES-G3(K, 2)` (right
+/// child) up to this many additional levels — try-everything since we
+/// have no path bits per entry.
+///
+/// Each level doubles the candidate count. Cost per entry per MKB
+/// cvalue ≈ `2 × (2^(D+1) - 1)` AES decrypts. For a ~100-cvalue MKB
+/// (typical UHD) at depth 2: ~14 × 100 = 1400 ops per entry; for 1.5k
+/// entries that's ~2 M validate calls, sub-second with AES-NI.
+///
+/// Set to 0 to disable walking (entries tried only as terminal PKs).
+const PK_WALK_MAX_DEPTH: u8 = 3;
+
+/// Same as [`derive_media_key_from_pk`] but with explicit walk depth.
+/// Each entry is tried as a terminal PK at depth 0, then as a node-key
+/// whose PK and children are derived via `AES-G3(K, 0|1|2)` for up to
+/// `max_depth` additional levels.
+pub fn derive_media_key_from_pk_walked(
+    mkb: &[u8],
+    processing_keys: &[[u8; 16]],
+    max_depth: u8,
+) -> Option<[u8; 16]> {
    let mk_dv = mkb_find_mk_dv(mkb)?;
    let uvs = mkb_find_subdiff_records(mkb)?;
    let cvalues = mkb_find_cvalues(mkb)?;
+    walk_pk_against_tables_impl(processing_keys, &uvs, &cvalues, &mk_dv, max_depth)
+}

-    // Count UV entries (each 5 bytes, stop when high bits set)
+/// Core Subset-Difference PK walk over explicit record bodies. Shared by
+/// [`derive_media_key_from_pk_walked`] (production, records auto-selected) and
+/// [`probe::walk_pk_against_tables`] (harness, records caller-pinned).
+fn walk_pk_against_tables_impl(
+    processing_keys: &[[u8; 16]],
+    uvs: &[u8],
+    cvalues: &[u8],
+    mk_dv: &[u8; 16],
+    max_depth: u8,
+) -> Option<[u8; 16]> {
    let num_uvs = uvs
        .chunks(5)
        .take_while(|c| c.len() == 5 && (c[0] & 0xC0) == 0)
        .count();

-    // Try each processing key against each UV/cvalue pair
-    for pk in processing_keys {
+    let try_against_mkb = |pk: &[u8; 16]| -> Option<[u8; 16]> {
        for i in 0..num_uvs {
            if (i + 1) * 16 > cvalues.len() {
                continue;
@@ -228,13 +266,54 @@ pub fn derive_media_key_from_pk(mkb: &[u8], processing_keys: &[[u8; 16]]) -> Opt
            if record_start + 5 > uvs.len() {
                continue;
            }
-            let _u_mask_shift = uvs[record_start];
            let uv = &uvs[record_start + 1..record_start + 5];
            let cv = &cvalues[i * 16..(i + 1) * 16];
-            if let Some(mk) = validate_processing_key(pk, cv, uv, &mk_dv) {
+            if let Some(mk) = validate_processing_key(pk, cv, uv, mk_dv) {
                return Some(mk);
            }
        }
+        None
+    };
+
+    // Two interpretations per entry:
+    //   (a) entry IS already a terminal PK → validate directly
+    //   (b) entry is a node key (label) → derive PK via aesg3(K, 1) and validate
+    // Then descend to children's node keys via aesg3(K, 0) / aesg3(K, 2) and
+    // repeat up to max_depth levels deep.
+    for entry in processing_keys {
+        // Depth-0 attempts on the raw entry
+        if let Some(mk) = try_against_mkb(entry) {
+            return Some(mk);
+        }
+        let pk_at_node = aesg3(entry, 1);
+        if let Some(mk) = try_against_mkb(&pk_at_node) {
+            return Some(mk);
+        }
+        if max_depth == 0 {
+            continue;
+        }
+        // Walk: BFS through child node keys
+        let mut frontier: Vec<[u8; 16]> = vec![aesg3(entry, 0), aesg3(entry, 2)];
+        for depth in 1..=max_depth {
+            let mut next = Vec::with_capacity(frontier.len() * 2);
+            for nk in &frontier {
+                // Try this node's PK (label → PK at this level)
+                let pk_here = aesg3(nk, 1);
+                if let Some(mk) = try_against_mkb(&pk_here) {
+                    return Some(mk);
+                }
+                // Some leaked materials are themselves PKs at this depth, so
+                // also try the node-key bytes directly.
+                if let Some(mk) = try_against_mkb(nk) {
+                    return Some(mk);
+                }
+                if depth < max_depth {
+                    next.push(aesg3(nk, 0));
+                    next.push(aesg3(nk, 2));
+                }
+            }
+            frontier = next;
+        }
    }
    None
 }
@@ -276,6 +355,78 @@ fn validate_processing_key(
    None
 }

+/// Public, side-effect-free accessors over the MKB record helpers, exposed so
+/// independent reproduction harnesses (e.g. `examples/prove_hkd_aacs.rs`) can
+/// exercise the exact same parser + verify primitives the production walk uses.
+/// These are thin wrappers — no new logic.
+pub mod probe {
+    use super::aes_ecb_decrypt;
+
+    /// `mk_dv` from the MKB's Verify-Media-Key record (type 0x81 / 0x86).
+    pub fn mkb_mk_dv(mkb: &[u8]) -> Option<[u8; 16]> {
+        super::mkb_find_mk_dv(mkb)
+    }
+
+    /// Body of the MKB's Subset-Difference Index record (type 0x04).
+    pub fn mkb_subdiff(mkb: &[u8]) -> Option<Vec<u8>> {
+        super::mkb_find_subdiff_records(mkb)
+    }
+
+    /// Body of the MKB's Media-Key-Data (cvalues) record. Selects record
+    /// `0x05` (the large cvalue table, 1:1 with the `0x04` Subset-Difference
+    /// index on AACS 2.x UHD MKBs), falling back to `0x07` only when `0x05`
+    /// is absent.
+    pub fn mkb_cvalues(mkb: &[u8]) -> Option<Vec<u8>> {
+        super::mkb_find_cvalues(mkb)
+    }
+
+    /// Body (header stripped) of the first MKB record of `rec_type`. Lets a
+    /// harness pin an exact record type for cross-checking the production
+    /// cvalue selection (e.g. compare record `0x05` vs `0x07` sizes).
+    pub fn mkb_record_body(mkb: &[u8], rec_type: u8) -> Option<Vec<u8>> {
+        super::find_record_body(mkb, rec_type)
+    }
+
+    /// AES-128-ECB single-block decrypt (the AACS verify primitive).
+    pub fn aes_dec(key: &[u8; 16], block: &[u8; 16]) -> [u8; 16] {
+        aes_ecb_decrypt(key, block)
+    }
+
+    /// Does `km` satisfy the MKB's Verify-Media-Key relation?
+    /// `AES-D(km, mk_dv)[0..8] == 01 23 45 67 89 AB CD EF`.
+    pub fn km_verifies(mkb: &[u8], km: &[u8; 16]) -> bool {
+        match super::mkb_find_mk_dv(mkb) {
+            Some(mk_dv) => {
+                aes_ecb_decrypt(km, &mk_dv)[..8] == [0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF]
+            }
+            None => false,
+        }
+    }
+
+    /// Run the exact production Subset-Difference PK walk
+    /// ([`super::derive_media_key_from_pk_walked`]) but against
+    /// CALLER-SUPPLIED record bodies — so a harness can pin a specific
+    /// Media-Key-Data table (record `0x05` on AACS 2.x UHD MKBs, which the
+    /// production `mkb_find_cvalues` now selects) and the matching `0x04`
+    /// Subset-Difference Index, across ALL entries.
+    ///
+    /// `subdiff` is the type-0x04 body (5-byte entries
+    /// `[u_mask_shift][uv:be32]`); `cvalues` is the chosen cvalue table
+    /// (16-byte entries); `mk_dv` is from the verify record. Each entry in
+    /// `keys` is tried as a terminal PK and as an SD node-key descending via
+    /// `AES-G3(K, 0|1|2)` for `max_depth` levels — identical logic to the
+    /// production walk. Returns the verified Media Key, if any.
+    pub fn walk_pk_against_tables(
+        keys: &[[u8; 16]],
+        subdiff: &[u8],
+        cvalues: &[u8],
+        mk_dv: &[u8; 16],
+        max_depth: u8,
+    ) -> Option<[u8; 16]> {
+        super::walk_pk_against_tables_impl(keys, subdiff, cvalues, mk_dv, max_depth)
+    }
+}
+
 /// Find Verify Media Key Record (type 0x81 for AACS 1.0, 0x86 for AACS 2.0/2.1) in MKB.
 fn mkb_find_mk_dv(mkb: &[u8]) -> Option<[u8; 16]> {
    let mut pos = 0;
@@ -337,17 +488,26 @@ fn mkb_find_subdiff_records(mkb: &[u8]) -> Option<Vec<u8>> {

 /// Find the Media Key Data Record (cvalues table) in an MKB.
 ///
-/// libaacs hard-codes record type `0x05` (matches AACS 1.0 and BD type-3/4
-/// MKBs), but on AACS 2.x Category-C MKBs the cvalues table moved to
-/// record type `0x07` and `0x05` now carries the host-revocation
-/// signature. To stay correct on both lines we prefer `0x07` first (the
-/// AACS 2.x layout used by every modern UHD disc) and fall back to
-/// `0x05` for AACS 1.0 MKBs.
+/// The cvalue table is record type `0x05` (Media Key Data) on BOTH AACS
+/// 1.0 and AACS 2.x MKBs — its 16-byte cvalue entries are 1:1 with the
+/// 5-byte Subset-Difference index entries in record `0x04`. This matches
+/// libaacs, whose `mkb_cvalues()` reads `0x05` and `mkb_subdiff_records()`
+/// reads `0x04`.
+///
+/// On AACS 2.x in-drive UHD MKBs the `0x05` table is large (the full
+/// subset-difference cvalue set: ~181k entries on a retail MKB, 1:1 with
+/// the giant `0x04` index), while record `0x07` (Explicit
+/// Subset-Difference Record) is a much smaller structure (~96 entries) and
+/// is NOT the cvalue table. An earlier version of this function preferred
+/// `0x07`, which under-tested the Subset-Difference walk on UHD discs and
+/// prevented the DK→walk path from ever finding the matching uv. The
+/// selection MUST therefore be `0x05`-first; `0x07` is only a fallback for
+/// malformed/legacy MKBs that somehow lack a `0x05` record.
 fn mkb_find_cvalues(mkb: &[u8]) -> Option<Vec<u8>> {
-    if let Some(body) = find_record_body(mkb, 0x07) {
+    if let Some(body) = find_record_body(mkb, 0x05) {
        return Some(body);
    }
-    find_record_body(mkb, 0x05)
+    find_record_body(mkb, 0x07)
 }

 /// Walk an MKB and return the payload (header stripped) of the first
@@ -372,6 +532,27 @@ fn find_record_body(mkb: &[u8], rec_type_wanted: u8) -> Option<Vec<u8>> {
    None
 }

+/// Real content length of an MKB: the byte offset where the record stream
+/// ends. MKB files (especially `MKB_RW.inf`, but `MKB_RO.inf` too on some
+/// discs) are allocated to a fixed size — often ~128 MiB — with the records at
+/// the front and the rest zero padding. Walking records (type+len) and stopping
+/// at the first padding byte (`type == 0` / zero-length / overrun) gives the
+/// actual size so callers can trim off megabytes of zeros before sending or
+/// archiving. Returns `mkb.len()` only if the whole buffer parsed as records.
+pub fn mkb_content_len(mkb: &[u8]) -> usize {
+    let mut pos = 0;
+    while pos + 4 <= mkb.len() {
+        let rec_type = mkb[pos];
+        let rec_len = u32::from_be_bytes([0, mkb[pos + 1], mkb[pos + 2], mkb[pos + 3]]) as usize;
+        // A zero type, a zero/short length, or an overrun = records done, padding begun.
+        if rec_type == 0x00 || rec_len < 4 || pos + rec_len > mkb.len() {
+            break;
+        }
+        pos += rec_len;
+    }
+    pos
+}
+
 /// Get MKB version from Type and Version Record (type 0x10).
 /// Version is a BE u32 at offset 8 of the record body (offset 12 from `pos`).
 pub fn mkb_version(mkb: &[u8]) -> Option<u32> {
@@ -670,8 +851,10 @@ pub struct ResolveContext<'a> {
    /// 16-byte Volume ID from SCSI handshake. `[0u8; 16]` is the
    /// "no VID" sentinel and disables paths 1-3.
    pub volume_id: &'a [u8; 16],
-    /// Key database.
-    pub keydb: &'a KeyDb,
+    /// Key sources — checked in array order for disc-keyed lookups,
+    /// union'd across all entries for bulk material (DKs, PKs, HCs).
+    /// A keydb file, a webservice, an OEM provider can all coexist.
+    pub providers: &'a [&'a dyn super::provider::KeyProvider],
    /// MKB raw bytes (optional — paths 1/2 require it).
    pub mkb: Option<&'a [u8]>,
 }
@@ -755,14 +938,17 @@ pub fn resolve_keys_v21(ctx: &ResolveContext<'_>) -> Option<ResolvedKeys> {
        "resolve_keys_v21: starting"
    );

+    let providers = super::provider::Providers(ctx.providers);
+
    if has_vid {
        // Path 1: Variant chain (V21's analogue of classical Path 1's
        // DK derivation). Placeholder until KCD constant is supplied.
        if let Some(mkb) = ctx.mkb {
            let recs = super::variants::walk_mkb(mkb);
+            let all_dks = providers.device_keys();
            match super::variants::derive_media_key_variant(
                &recs,
-                &ctx.keydb.device_keys,
+                &all_dks,
                &super::variants::KEY_CORRECTION_DATA_PLACEHOLDER,
                ctx.volume_id,
            ) {
@@ -785,14 +971,13 @@ pub fn resolve_keys_v21(ctx: &ResolveContext<'_>) -> Option<ResolvedKeys> {
            }
        }

-        // Path 3: KEYDB MK + matching VID → derived VUK
-        for entry in ctx.keydb.disc_entries.values() {
-            if let (Some(mk), Some(did)) = (entry.media_key, entry.disc_id) {
-                if did == *ctx.volume_id {
-                    let vuk = derive_vuk(&mk, ctx.volume_id);
-                    tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_v21_path3_hit", "MK+VID entry matched volume_id");
-                    return Some(build(Some(vuk), derive_uks(&vuk), 3));
-                }
+        // Path 3: pre-computed MK + matching VID → derived VUK.
+        // Short-circuit: first provider with a matching VID wins.
+        if let Some(entry) = providers.lookup_disc_by_vid(ctx.volume_id) {
+            if let (Some(mk), Some(_)) = (entry.media_key, entry.disc_id) {
+                let vuk = derive_vuk(&mk, ctx.volume_id);
+                tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_v21_path3_hit", "MK+VID entry matched volume_id");
+                return Some(build(Some(vuk), derive_uks(&vuk), 3));
            }
        }
    } else {
@@ -804,7 +989,7 @@ pub fn resolve_keys_v21(ctx: &ResolveContext<'_>) -> Option<ResolvedKeys> {
    }

    // Paths 4 and 5: hash lookup, prefer V over U on the same entry.
-    if let Some(entry) = ctx.keydb.find_disc(&hash_hex) {
+    if let Some(entry) = providers.lookup_disc_by_hash(&uk_file.disc_hash) {
        if let Some(vuk) = entry.vuk {
            tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_v21_path4_hit", "VUK from KEYDB");
            return Some(build(Some(vuk), derive_uks(&vuk), 4));
@@ -881,6 +1066,8 @@ fn resolve_keys_classical(ctx: &ResolveContext<'_>, version: AacsVersion) -> Opt
        "resolve_keys: starting"
    );

+    let providers = super::provider::Providers(ctx.providers);
+
    // Paths 1 and 2 need both MKB and VID. Logged as a single skip when
    // either is absent so operators see one reason, not two.
    if has_vid {
@@ -900,37 +1087,60 @@ fn resolve_keys_classical(ctx: &ResolveContext<'_>, version: AacsVersion) -> Opt
            );

            // Path 1: MKB + device keys → media key → VUK
-            if let Some(mk) = derive_media_key_from_dk(mkb, &ctx.keydb.device_keys) {
+            let all_dks = providers.device_keys();
+            if let Some(mk) = derive_media_key_from_dk(mkb, &all_dks) {
                let vuk = derive_vuk(&mk, ctx.volume_id);
                tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path1_hit", "media key derived from device key");
                return Some(build(Some(vuk), derive_uks(&vuk), 1));
            }
-            tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path1_miss", dk_count = ctx.keydb.device_keys.len(), "DK derivation failed");
+            tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path1_miss", dk_count = all_dks.len(), "DK derivation failed");

            // Path 2: MKB + processing keys → media key → VUK
-            if let Some(mk) = derive_media_key_from_pk(mkb, &ctx.keydb.processing_keys) {
+            let all_pks = providers.processing_keys();
+            if let Some(mk) = derive_media_key_from_pk(mkb, &all_pks) {
                let vuk = derive_vuk(&mk, ctx.volume_id);
                tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path2_hit", "media key derived from processing key");
                return Some(build(Some(vuk), derive_uks(&vuk), 2));
            }
-            tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path2_miss", pk_count = ctx.keydb.processing_keys.len(), "PK derivation failed");
+            tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path2_miss", pk_count = all_pks.len(), "PK derivation failed");
+
+            // Path 2.5: MK-pool brute. keydb stores Media Keys per-disc, but an
+            // MK is MKB-scoped (shared across a pressing/MKB-family). A disc
+            // whose own hash/VID isn't keyed can still resolve if ANY stored MK
+            // verifies against its MKB. Try every distinct MK via km_verifies;
+            // a UNIQUE pass is this disc's Km → derive VUK (needs VID) → UK.
+            // km_verifies is one AES-D + magic check per candidate (cheap).
+            let mks = providers.media_keys();
+            let mut mk_hits: Vec<[u8; 16]> = Vec::new();
+            for mk in &mks {
+                if probe::km_verifies(mkb, mk) && !mk_hits.contains(mk) {
+                    mk_hits.push(*mk);
+                    if mk_hits.len() > 1 {
+                        break; // ambiguous — bail to avoid a wrong key
+                    }
+                }
+            }
+            if mk_hits.len() == 1 {
+                let vuk = derive_vuk(&mk_hits[0], ctx.volume_id);
+                tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path2_5_hit", mk_pool = mks.len(), "media key from keydb MK-pool brute (km_verifies)");
+                // Same class as path 3 (KEYDB MK → derived VUK).
+                return Some(build(Some(vuk), derive_uks(&vuk), 3));
+            }
+            tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path2_5_miss", mk_pool = mks.len(), mk_hits = mk_hits.len(), "MK-pool brute: no unique verifying MK");
        } else {
            tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_no_mkb", "no MKB; paths 1/2 skipped");
        }

-        // Path 3: KEYDB MK + matching VID → derived VUK
-        let mut path3_mk_did_count = 0usize;
-        for entry in ctx.keydb.disc_entries.values() {
-            if let (Some(mk), Some(did)) = (entry.media_key, entry.disc_id) {
-                path3_mk_did_count += 1;
-                if did == *ctx.volume_id {
-                    let vuk = derive_vuk(&mk, ctx.volume_id);
-                    tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path3_hit", "MK+VID entry matched volume_id");
-                    return Some(build(Some(vuk), derive_uks(&vuk), 3));
-                }
+        // Path 3: pre-computed MK + matching VID → derived VUK.
+        // Short-circuit: first provider with a matching VID wins.
+        if let Some(entry) = providers.lookup_disc_by_vid(ctx.volume_id) {
+            if let (Some(mk), Some(_)) = (entry.media_key, entry.disc_id) {
+                let vuk = derive_vuk(&mk, ctx.volume_id);
+                tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path3_hit", "MK+VID entry matched volume_id");
+                return Some(build(Some(vuk), derive_uks(&vuk), 3));
            }
        }
-        tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path3_miss", mk_did_entries = path3_mk_did_count, "no MK+VID entry matched volume_id");
+        tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path3_miss", "no MK+VID entry matched volume_id");
    } else {
        tracing::warn!(
            target: "freemkv::disc",
@@ -939,26 +1149,26 @@ fn resolve_keys_classical(ctx: &ResolveContext<'_>, version: AacsVersion) -> Opt
        );
    }

-    // Paths 4 and 5: single hash-table lookup, prefer V (path 4) over
+    // Paths 4 and 5: single hash-keyed lookup, prefer V (path 4) over
    // U (path 5). They are not independent checks — path 5 only fires
    // because path 4 had no VUK on the same entry.
-    if let Some(entry) = ctx.keydb.find_disc(&hash_hex) {
-        tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_keydb_hit_entry", "disc hash found in keydb");
+    if let Some(entry) = providers.lookup_disc_by_hash(&uk_file.disc_hash) {
+        tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_keydb_hit_entry", "disc hash found in provider");
        if let Some(vuk) = entry.vuk {
-            tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path4_hit", "VUK from KEYDB");
+            tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_path4_hit", "VUK from provider");
            return Some(build(Some(vuk), derive_uks(&vuk), 4));
        } else if let Some(unit_keys) = match_keydb_unit_keys(&uk_file, &entry.unit_keys) {
            tracing::warn!(
                target: "freemkv::disc",
                phase = "resolve_keys_path5_hit",
                uk_count = unit_keys.len(),
-                "unit keys from KEYDB (no VUK)"
+                "unit keys from provider (no VUK)"
            );
            return Some(build(None, unit_keys, 5));
        }
-        tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_keydb_no_keys", "KEYDB entry has neither VUK nor matching unit keys");
+        tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_keydb_no_keys", "provider entry has neither VUK nor matching unit keys");
    } else {
-        tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_keydb_miss", "disc hash NOT in KEYDB");
+        tracing::warn!(target: "freemkv::disc", phase = "resolve_keys_keydb_miss", "disc hash NOT found in any provider");
    }

    None
@@ -998,8 +1208,7 @@ mod tests {

    #[test]
    fn test_vuk_derivation() {
-        // Civil War UHD: known MK, VID, VUK from KEYDB
-        // MK = 15665F98..., VID (disc_id) = from entry, VUK = F96D7908...
+        // Pick any UHD entry with a known MK, VID, and VUK from KEYDB.
        // VUK = AES-DEC(MK, VID) XOR VID
        let path = match keydb_path() {
            Some(p) => p,
@@ -1072,7 +1281,7 @@ mod tests {

    #[test]
    fn test_decrypt_real_unit() {
-        // Try decrypting a real encrypted aligned unit from Civil War UHD
+        // Try decrypting a real encrypted aligned unit from a UHD sample.
        // This disc is AACS 2.0 (BEE) so unit key alone won't work —
        // we need bus decryption first. But this verifies the pipeline.
        let unit_path = std::path::Path::new("/tmp/encrypted_unit.bin");
@@ -1083,7 +1292,7 @@ mod tests {
        let original = std::fs::read(unit_path).unwrap();
        assert_eq!(original.len(), ALIGNED_UNIT_LEN);
        assert!(
-            super::super::decrypt::is_unit_encrypted(&original),
+            super::super::decrypt::is_aacs_scrambled(&original),
            "Unit should be encrypted"
        );

@@ -1093,20 +1302,17 @@ mod tests {
        };
        let db = KeyDb::load(&kp).unwrap();

-        // Civil War UHD entries
-        let civil_war_entries: Vec<&DiscEntry> = db
+        // Candidate entries: any UHD entry that carries unit keys.
+        let candidate_entries: Vec<&DiscEntry> = db
            .disc_entries
            .values()
-            .filter(|e| e.title.contains("CIVIL WAR") && !e.unit_keys.is_empty())
+            .filter(|e| !e.unit_keys.is_empty())
            .collect();

-        eprintln!(
-            "Found {} Civil War entries with unit keys",
-            civil_war_entries.len()
-        );
+        eprintln!("Found {} entries with unit keys", candidate_entries.len());

        // Try each entry's unit keys
-        for entry in &civil_war_entries {
+        for entry in &candidate_entries {
            let keys: Vec<[u8; 16]> = entry.unit_keys.iter().map(|(_, k)| *k).collect();
            let mut unit = original.clone();

@@ -1139,10 +1345,11 @@ mod tests {
    #[test]
    fn test_disc_hash_hex() {
        let hash = [
-            ***REMOVED***,
+            0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D,
+            0x0E, 0x0F, 0x10, 0x11, 0x12, 0x13,
        ];
        let hex = disc_hash_hex(&hash);
-        assert_eq!(hex, "***REMOVED***");
+        assert_eq!(hex, "0x000102030405060708090A0B0C0D0E0F10111213");
    }

    #[test]
@@ -1212,6 +1419,26 @@ mod tests {
        assert_eq!(mkb_version(&mkb), Some(77));
    }

+    #[test]
+    fn mkb_content_len_trims_trailing_padding() {
+        // Two real records (0x10 type/version + 0x86 verify), then 128 KiB of
+        // zero padding (the fixed-region tail). Content length must stop at the
+        // end of the records, not include the padding.
+        let mut mkb = vec![
+            0x10, 0x00, 0x00, 0x0C, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x4D,
+        ];
+        mkb.extend_from_slice(&[0x86, 0x00, 0x00, 0x18]);
+        mkb.extend_from_slice(&[0xAB; 16]);
+        mkb.extend_from_slice(&[0x00, 0x00, 0x00, 0x00]);
+        let records_len = mkb.len();
+        mkb.extend(std::iter::repeat(0u8).take(128 * 1024)); // padding
+        assert_eq!(mkb_content_len(&mkb), records_len);
+        // No padding → returns the full length.
+        assert_eq!(mkb_content_len(&mkb[..records_len]), records_len);
+        // Empty → 0.
+        assert_eq!(mkb_content_len(&[]), 0);
+    }
+
    #[test]
    fn mkb_version_returns_none_on_empty() {
        assert_eq!(mkb_version(&[]), None);
@@ -1240,6 +1467,53 @@ mod tests {
        assert_eq!(mkb_find_mk_dv(&mkb), Some(expected));
    }

+    #[test]
+    fn probe_walk_pk_against_tables_accepts_planted_pk_rejects_corrupt() {
+        // Lock in the shared SD walk used by both production
+        // (`derive_media_key_from_pk_walked`) and the independent-reproduction
+        // harness (`probe::walk_pk_against_tables`). Plant a terminal PK whose
+        // derived Media Key satisfies a synthetic verify record; confirm the
+        // walk ACCEPTS it against caller-supplied SD/cvalue tables and REJECTS a
+        // 1-byte corruption.
+        use super::super::decrypt::aes_ecb_encrypt as enc;
+
+        let pk: [u8; 16] = [
+            0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE,
+            0xFF, 0x00,
+        ];
+        let mk: [u8; 16] = [
+            0xA0, 0xA1, 0xA2, 0xA3, 0xA4, 0xA5, 0xA6, 0xA7, 0xA8, 0xA9, 0xAA, 0xAB, 0xAC, 0xAD,
+            0xAE, 0xAF,
+        ];
+        let uv: [u8; 4] = [0x00, 0x00, 0x04, 0x00];
+
+        let mut mk_raw = mk;
+        for a in 0..4 {
+            mk_raw[12 + a] ^= uv[a];
+        }
+        let cv = enc(&pk, &mk_raw); // AES-D(pk, cv) == mk_raw
+        let mut vd = [0u8; 16];
+        vd[..8].copy_from_slice(&[0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF]);
+        let mk_dv = enc(&mk, &vd); // AES-D(mk, mk_dv) starts with sentinel
+
+        // 0x04 SD body: one entry [u_mask_shift=0][uv].
+        let mut subdiff = vec![0u8];
+        subdiff.extend_from_slice(&uv);
+
+        assert_eq!(
+            probe::walk_pk_against_tables(std::slice::from_ref(&pk), &subdiff, &cv, &mk_dv, 1),
+            Some(mk),
+            "planted terminal PK must verify"
+        );
+        let mut bad = pk;
+        bad[0] ^= 0xFF;
+        assert_eq!(
+            probe::walk_pk_against_tables(std::slice::from_ref(&bad), &subdiff, &cv, &mk_dv, 1),
+            None,
+            "corrupted PK must be rejected"
+        );
+    }
+
    #[test]
    fn validate_processing_key_round_trip_with_nonzero_uv() {
        // Synthesise a (pk, uv, mk, cvalue, mk_dv) tuple that satisfies the
@@ -1294,27 +1568,176 @@ mod tests {
        assert!(validate_processing_key(&pk, &cvalue, &wrong_uv, &mk_dv).is_none());
    }

-    #[test]
-    fn mkb_find_cvalues_prefers_0x07_then_falls_back_to_0x05() {
-        // AACS 2.x: type 0x07 carries cvalues; 0x05 is the host-revocation
-        // signature. Mixed-record MKB → 0x07 wins.
-        let mut mkb = vec![
-            0x10, 0x00, 0x00, 0x0C, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x4D,
-        ];
-        // type=0x05, body = [0xAA; 4]
-        mkb.extend_from_slice(&[0x05, 0x00, 0x00, 0x08, 0xAA, 0xAA, 0xAA, 0xAA]);
-        // type=0x07, body = [0xBB; 4]
-        mkb.extend_from_slice(&[0x07, 0x00, 0x00, 0x08, 0xBB, 0xBB, 0xBB, 0xBB]);
-        let body = mkb_find_cvalues(&mkb).expect("cvalues record must be found");
-        assert_eq!(body, vec![0xBB, 0xBB, 0xBB, 0xBB], "0x07 must be preferred");
+    // ── MKB cvalue-record selection (issue #259 / #281) ─────────────────
+    //
+    // The cvalue (Media Key Data) table is record 0x05; the
+    // Subset-Difference index is record 0x04. This matches libaacs
+    // (`mkb_cvalues` → 0x05, `mkb_subdiff_records` → 0x04). Record 0x07
+    // (Explicit Subset-Difference Record) is NOT the cvalue table. On real
+    // in-drive AACS 2.x UHD MKBs 0x07 is small (~96 entries) while the 0x05
+    // table is large (181270 entries, 1:1 with 0x04). An earlier
+    // `mkb_find_cvalues` preferred 0x07, which under-tested the SD walk and
+    // broke the DK→walk path. The selector must prefer 0x05.

-        // AACS 1.0: only 0x05 present → fall back to it.
-        let mut mkb1 = vec![
-            0x10, 0x00, 0x00, 0x0C, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
+    /// Build a 4-byte MKB record header (type + 3-byte big-endian total
+    /// length, header included) and append `body`.
+    fn mkb_record(rec_type: u8, body: &[u8]) -> Vec<u8> {
+        let total = 4 + body.len();
+        let mut rec = Vec::with_capacity(total);
+        rec.push(rec_type);
+        rec.push(((total >> 16) & 0xFF) as u8);
+        rec.push(((total >> 8) & 0xFF) as u8);
+        rec.push((total & 0xFF) as u8);
+        rec.extend_from_slice(body);
+        rec
+    }
+
+    /// Synthesize an AACS-2.x-shaped MKB carrying BOTH a small 0x07 record
+    /// and the real 0x05 cvalue table, with 0x07 placed first so a
+    /// "0x07-first" selector would pick the wrong record. The 0x05 table
+    /// has `n` 16-byte entries (1:1 with the `n`-entry 0x04 SD index); the
+    /// 0x07 decoy has `decoy` 16-byte entries.
+    fn synth_aacs2_mkb(n: usize, decoy: usize) -> Vec<u8> {
+        let mut mkb = Vec::new();
+        mkb.extend_from_slice(&mkb_record(0x10, &[0, 0, 0, 0x20, 0, 0, 0, 0x52]));
+        mkb.extend_from_slice(&mkb_record(0x86, &[0xABu8; 16]));
+        let mut sd = Vec::with_capacity(n * 5);
+        for i in 0..n {
+            sd.push(0x00); // u_mask_shift, top bits clear → not revoked
+            sd.extend_from_slice(&((i as u32) + 1).to_be_bytes());
+        }
+        mkb.extend_from_slice(&mkb_record(0x04, &sd));
+        mkb.extend_from_slice(&mkb_record(0x07, &vec![0x11u8; decoy * 16])); // decoy first
+        mkb.extend_from_slice(&mkb_record(0x05, &vec![0x22u8; n * 16])); // real cvalues
+        mkb
+    }
+
+    #[test]
+    fn cvalue_selection_prefers_0x05_over_0x07() {
+        // AACS-2.x layout: large 0x05 (1:1 with 0x04) + smaller decoy 0x07
+        // placed earlier in the record stream.
+        let n = 1500;
+        let decoy = 96;
+        let mkb = synth_aacs2_mkb(n, decoy);
+
+        let sd = probe::mkb_subdiff(&mkb).expect("0x04 present");
+        let r05 = probe::mkb_record_body(&mkb, 0x05).expect("0x05 present");
+        let r07 = probe::mkb_record_body(&mkb, 0x07).expect("0x07 present");
+        let selected = mkb_find_cvalues(&mkb).expect("cvalues selected");
+
+        assert_eq!(sd.len() / 5, n, "0x04 SD index entry count");
+        assert_eq!(r05.len() / 16, n, "0x05 cvalue entry count");
+        assert_eq!(r07.len() / 16, decoy, "0x07 decoy entry count");
+
+        // The fix: selection MUST pick 0x05 (the large 1:1 table), NOT the
+        // 0x07 decoy a "0x07-first" rule would return.
+        assert_eq!(
+            selected.len() / 16,
+            n,
+            "cvalue selection must use the large 0x05 table, not the {decoy}-entry 0x07 decoy"
+        );
+        assert_eq!(
+            selected, r05,
+            "selected body must be the 0x05 record verbatim"
+        );
+        assert_eq!(
+            selected.len() / 16,
+            sd.len() / 5,
+            "cvalue table must be 1:1 with the 0x04 Subset-Difference index"
+        );
+    }
+
+    #[test]
+    fn cvalue_selection_falls_back_to_0x07_when_no_0x05() {
+        // Malformed/legacy MKB with only a 0x07 record and no 0x05: the
+        // selector falls back to 0x07 rather than returning None.
+        let mut mkb = Vec::new();
+        mkb.extend_from_slice(&mkb_record(0x10, &[0, 0, 0, 0x10, 0, 0, 0, 1]));
+        mkb.extend_from_slice(&mkb_record(0x86, &[0xCDu8; 16]));
+        mkb.extend_from_slice(&mkb_record(0x04, &[0x00, 0, 0, 0, 1]));
+        let only07 = vec![0x33u8; 16];
+        mkb.extend_from_slice(&mkb_record(0x07, &only07));
+
+        assert!(probe::mkb_record_body(&mkb, 0x05).is_none());
+        let selected = mkb_find_cvalues(&mkb).expect("falls back to 0x07");
+        assert_eq!(selected, only07, "fallback returns the 0x07 body");
+    }
+
+    /// Locate a captured MKB sample under the optional `MKB_SAMPLE_DIR`.
+    /// Returns `None` (skip) when the directory or file is absent.
+    fn mkb_sample(rel: &str) -> Option<std::path::PathBuf> {
+        let dir = std::env::var("MKB_SAMPLE_DIR").ok()?;
+        let p = std::path::Path::new(&dir).join(rel);
+        if p.exists() { Some(p) } else { None }
+    }
+
+    #[test]
+    fn real_aacs2_samples_select_large_0x05_not_small_0x07() {
+        // Real in-drive AACS 2.x UHD MKBs carry BOTH a small 0x07
+        // Explicit-Subset-Difference record (96 16-byte entries) AND the
+        // large 0x05 Media Key Data / cvalue table (181270 entries, 1:1
+        // with the 0x04 index). The production selector must return the
+        // LARGE 0x05 body, not the small 0x07 one. This is the exact
+        // regression #259 found. Skips when no sample dir is present.
+        let samples = [
+            "sample-a/MKB_RO.inf",
+            "sample-b/MKB_RO.inf",
+            "sample-c/MKB_RO.inf",
        ];
-        mkb1.extend_from_slice(&[0x05, 0x00, 0x00, 0x08, 0xCC, 0xCC, 0xCC, 0xCC]);
-        let body = mkb_find_cvalues(&mkb1).expect("0x05 fallback must work for AACS 1.0");
-        assert_eq!(body, vec![0xCC, 0xCC, 0xCC, 0xCC]);
+        let mut checked = 0;
+        for rel in samples {
+            let path = match mkb_sample(rel) {
+                Some(p) => p,
+                None => continue,
+            };
+            let data = std::fs::read(&path).expect("read sample MKB");
+
+            let r05 = probe::mkb_record_body(&data, 0x05)
+                .unwrap_or_else(|| panic!("{rel}: expected a 0x05 Media Key Data record"));
+            let r07 = probe::mkb_record_body(&data, 0x07)
+                .unwrap_or_else(|| panic!("{rel}: expected a 0x07 record"));
+            let sd = probe::mkb_subdiff(&data)
+                .unwrap_or_else(|| panic!("{rel}: expected a 0x04 Subset-Difference index"));
+
+            let n05 = r05.len() / 16;
+            let n07 = r07.len() / 16;
+
+            // The discriminating facts the bug report cited.
+            assert!(
+                n05 > n07 * 100,
+                "{rel}: 0x05 ({n05}) must dwarf 0x07 ({n07})"
+            );
+            assert_eq!(n05, 181270, "{rel}: full 0x05 cvalue table size");
+            assert_eq!(n07, 96, "{rel}: small 0x07 record size");
+
+            // Production selection must be the large 0x05 table.
+            let selected = mkb_find_cvalues(&data)
+                .unwrap_or_else(|| panic!("{rel}: cvalue selection returned None"));
+            assert_eq!(
+                selected, r05,
+                "{rel}: selector must return the large 0x05 body, not 0x07"
+            );
+
+            // And it is 1:1 with the 0x04 SD index the walk iterates: the
+            // walk's UV count (take_while top-2-bits clear) lines up with
+            // the cvalue count to within the trailing padding entry.
+            let uv_entries = sd
+                .chunks(5)
+                .take_while(|c| c.len() == 5 && (c[0] & 0xC0) == 0)
+                .count();
+            assert!(
+                uv_entries >= n05 - 2 && uv_entries <= n05,
+                "{rel}: 0x04 UV count ({uv_entries}) should match 0x05 cvalue count ({n05})"
+            );
+
+            eprintln!(
+                "{rel}: 0x05={n05} cvalues, 0x07={n07}, 0x04 UVs={uv_entries} — selected 0x05"
+            );
+            checked += 1;
+        }
+        if checked == 0 {
+            eprintln!("no MKB samples present; skipping real-sample assertion");
+        }
    }

    #[test]
@@ -1343,29 +1766,32 @@ mod tests {
        };
        let db = KeyDb::load(&path).unwrap();

-        // Find V for Vendetta BD — has VUK and unit keys
-        // hash: ***REMOVED***
-        let entry = db.find_disc("***REMOVED***");
+        // Find any BD entry that carries a VUK and unit keys, then exercise
+        // the lookup-by-hash + VUK-derivation chain against it.
+        let entry = db
+            .disc_entries
+            .values()
+            .find(|e| e.vuk.is_some() && !e.unit_keys.is_empty() && e.disc_id.is_some());
        if entry.is_none() {
            return;
        }
        let entry = entry.unwrap();
        let vuk = entry.vuk.unwrap();
        let vid = entry.disc_id.unwrap();
+        let hash_hex = format!("0x{}", entry.disc_hash.trim_start_matches("0x"));

        // We need the actual Unit_Key_RO.inf from the disc to compute disc hash.
        // Since we don't have it, we can at least test that the KEYDB lookup
        // works with a known hash.
-        let hash_hex = "***REMOVED***";
-        let found = db.find_disc(hash_hex);
+        let found = db.find_disc(&hash_hex);
        assert!(found.is_some());
        assert_eq!(found.unwrap().vuk, Some(vuk));

        // Verify VUK derivation if we have MK + VID
        if let Some(mk) = entry.media_key {
            let derived = derive_vuk(&mk, &vid);
-            assert_eq!(derived, vuk, "VUK derivation mismatch for V for Vendetta");
-            eprintln!("V for Vendetta VUK derivation verified");
+            assert_eq!(derived, vuk, "VUK derivation mismatch");
+            eprintln!("VUK derivation verified");
        }
    }

@@ -1414,11 +1840,12 @@ mod tests {
        );
        keydb.processing_keys.push([0u8; 16]);

+        let providers: &[&dyn super::super::KeyProvider] = &[&keydb];
        let ctx = ResolveContext {
            unit_key_ro: &uk_ro,
            content_cert: None,
            volume_id: &zero_vid,
-            keydb: &keydb,
+            providers,
            mkb: None,
        };
        let result = resolve_keys_v1(&ctx);
@@ -1455,11 +1882,12 @@ mod tests {
        );

        let vid = [0u8; 16];
+        let providers: &[&dyn super::super::KeyProvider] = &[&keydb];
        let ctx = ResolveContext {
            unit_key_ro: &uk_ro,
            content_cert: None,
            volume_id: &vid,
-            keydb: &keydb,
+            providers,
            mkb: None,
        };
        let resolved =
@@ -1495,11 +1923,12 @@ mod tests {
        );

        let vid = [0u8; 16];
+        let providers: &[&dyn super::super::KeyProvider] = &[&keydb];
        let ctx = ResolveContext {
            unit_key_ro: &uk_ro,
            content_cert: None,
            volume_id: &vid,
-            keydb: &keydb,
+            providers,
            mkb: None,
        };
        let resolved =
@@ -1535,11 +1964,12 @@ mod tests {
        );

        let vid = [0u8; 16];
+        let providers: &[&dyn super::super::KeyProvider] = &[&keydb];
        let ctx = ResolveContext {
            unit_key_ro: &uk_ro,
            content_cert: None,
            volume_id: &vid,
-            keydb: &keydb,
+            providers,
            mkb: None,
        };
        assert!(
@@ -1548,6 +1978,68 @@ mod tests {
        );
    }

+    #[test]
+    fn resolve_keys_path2_5_mk_pool_brute_resolves_unkeyed_disc() {
+        // The Dunkirk case: this disc's own hash/VID are NOT in keydb, but its
+        // Media Key IS — filed under a sibling disc that shares its MKB. Path
+        // 2.5 must km_verifies that MK against the MKB and resolve.
+        use super::super::decrypt::aes_ecb_encrypt as enc;
+
+        let km = [0x11u8; 16];
+        let vid = [0x22u8; 16];
+
+        // MKB: 0x10 type/version + 0x86 verify record whose mk_dv decrypts under
+        // km to the AACS verify magic, so km_verifies(mkb, km) == true.
+        let mut vd = [0u8; 16];
+        vd[..8].copy_from_slice(&[0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF]);
+        let mk_dv = enc(&km, &vd);
+        let mut mkb = mkb_record(0x10, &[0, 0, 0, 0x20, 0, 0, 0, 0x4D]);
+        mkb.extend_from_slice(&mkb_record(0x86, &mk_dv));
+        assert!(
+            probe::km_verifies(&mkb, &km),
+            "fixture: km must verify the MKB"
+        );
+
+        // This disc's inf (its hash will NOT be in keydb).
+        let uk_ro = minimal_unit_key_ro();
+
+        // keydb: a SIBLING disc carries our km, keyed by the sibling's own
+        // hash + VID (neither matches THIS disc) — so only the MK-pool brute
+        // (km_verifies) can find it.
+        let mut keydb = KeyDb::empty();
+        keydb.disc_entries.insert(
+            "0xsibling".to_string(),
+            DiscEntry {
+                disc_hash: "0xsibling".to_string(),
+                title: "sibling".to_string(),
+                media_key: Some(km),
+                disc_id: Some([0x99u8; 16]),
+                vuk: None,
+                unit_keys: Vec::new(),
+            },
+        );
+
+        let providers: &[&dyn super::super::KeyProvider] = &[&keydb];
+        let ctx = ResolveContext {
+            unit_key_ro: &uk_ro,
+            content_cert: None,
+            volume_id: &vid,
+            providers,
+            mkb: Some(&mkb),
+        };
+        let resolved = resolve_keys_v1(&ctx)
+            .expect("MK-pool brute (path 2.5) must resolve a disc whose MK is in keydb");
+        assert_eq!(
+            resolved.key_source, 3,
+            "MK-pool brute is the KEYDB-derived class"
+        );
+        assert_eq!(
+            resolved.vuk,
+            Some(derive_vuk(&km, &vid)),
+            "VUK must derive from the verified Km + this disc's VID"
+        );
+    }
+
    #[test]
    fn test_content_cert_parse() {
        // AACS 1.0 cert
@@ -17,21 +17,24 @@ 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::{
    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_version, parse_content_cert, parse_unit_key_ro, read_mkb_from_drive, resolve_keys_v1,
-    resolve_keys_v2, resolve_keys_v21,
+    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,
@@ -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()
+    }
+}
@@ -185,12 +185,13 @@ pub fn decrypt_sectors(
            let chunks: Vec<&mut [u8]> = buf.chunks_mut(unit_len).collect();
            let nunits = chunks.len();

-            // Per-unit decrypt closure. The is_unit_encrypted check is
-            // a byte-0 heuristic; on a misfire we snapshot+restore via
-            // the original bytes so non-m2ts (e.g. MPLS/CLPI nav files)
-            // survive. See test `nav_file_unit_survives_decrypt_attempt`.
+            // 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_unit_encrypted(chunk) {
+                if chunk.len() == unit_len && aacs::is_aacs_scrambled(chunk) {
                    let original: Vec<u8> = chunk.to_vec();
                    if !aacs::decrypt_unit_full(chunk, &uk, rdk.as_ref()) {
                        chunk.copy_from_slice(&original);
@@ -232,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];
@@ -179,54 +179,33 @@ impl Disc {
        session: &mut crate::drive::Drive,
        opts: &ScanOptions,
    ) -> (Option<HandshakeResult>, Option<Error>) {
-        use crate::aacs::{self, KeyDb};
+        use crate::aacs;

-        let keydb_path = match opts.resolve_keydb() {
-            Some(p) => p,
-            None => {
+        // Host certs come from the caller's DriveCredentials (e.g. the keydb's
+        // host_certs(), sourced app-side) — the library does not load a keydb.
+        // Absent ⇒ no cert auth: an unlocked / LibreDrive drive already returned
+        // a Volume ID via the OEM path before reaching here, so this is the
+        // locked-drive-without-credentials case.
+        let host_certs: &[aacs::HostCert] = match &opts.credentials {
+            Some(c) if !c.host_certs.is_empty() => &c.host_certs,
+            _ => {
                tracing::warn!(
                    target: "freemkv::disc",
-                    phase = "handshake_no_keydb",
-                    "no KEYDB found in search paths; handshake skipped"
+                    phase = "handshake_no_credentials",
+                    "no drive credentials supplied; cert handshake skipped"
                );
                return (None, None);
            }
        };
-        let keydb = match KeyDb::load(&keydb_path) {
-            Ok(db) => db,
-            Err(e) => {
-                tracing::warn!(
-                    target: "freemkv::disc",
-                    phase = "handshake_keydb_load_failed",
-                    io_error_kind = ?e.kind(),
-                    keydb = %keydb_path.display(),
-                    "KEYDB load failed; handshake skipped"
-                );
-                return (
-                    None,
-                    Some(Error::KeydbLoad {
-                        path: keydb_path.display().to_string(),
-                    }),
-                );
-            }
-        };

-        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"
        );

-        if host_cert_count == 0 {
-            // No host certs in keydb -> cert auth cannot proceed.
-            // Surface as RawReadUnsupported so the caller knows
-            // neither path is available on this configuration.
-            return (None, Some(Error::AacsRawReadUnsupported));
-        }
-
        // 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
@@ -236,7 +215,7 @@ impl Disc {
        // 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 Barbie
+        // 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.
        //
@@ -246,7 +225,7 @@ impl Disc {
        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));
            }
@@ -317,153 +296,77 @@ impl Disc {
        (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::drm::{DrmContext, DrmProbe, DrmScheme, ResolvedScheme};
+        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;
-        // paths 2/3/4 in `resolve_keys` short-circuit on the zero
-        // sentinel and don't waste cycles trying to derive against
-        // garbage input).
-        let volume_id = handshake.map(|h| h.volume_id).unwrap_or([0u8; 16]);
-        let vid_available = volume_id != [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.
-        //
-        // Distinguish "we had every input and still missed" from "we
-        // never had VID so the derivation paths couldn't run." The
-        // former points at a stale keydb / unsupported MKB; the
-        // latter points at a failed handshake upstream. Path 1
-        // (disc-hash lookup) ran without VID and missed -> disc isn't
-        // in the keydb. If the caller has a handshake-failure reason
-        // it overrides this in `scan_with`.
-        let miss_error = if vid_available {
-            Error::AacsMkUnavailable
-        } else {
-            Error::AacsVukNotInKeydb
-        };
-
-        // Build a probe + context and let the dispatcher pick V10 / V20
-        // / V21. CSS is impossible here (this function is only called
-        // when /AACS exists), so we don't populate the DVD probe sector
-        // or a CSS context.
-        let probe = DrmProbe {
-            dvd_sample_sector: None,
-            content_cert: cc_data.as_deref(),
-            mkb: mkb_data.as_deref(),
-        };
-        let scheme = match DrmScheme::detect(&probe) {
-            Some(s) => s,
-            None => return Err(miss_error),
-        };
-        let aacs_ctx = aacs::ResolveContext {
-            unit_key_ro: &uk_ro_data,
-            content_cert: cc_data.as_deref(),
-            volume_id: &volume_id,
-            keydb: &keydb,
-            mkb: mkb_data.as_deref(),
-        };
-        let mut ctx = DrmContext {
-            aacs: Some(aacs_ctx),
-            css: None,
-        };
-        let resolved = match scheme.load(&mut ctx) {
-            Some(ResolvedScheme::Aacs(r)) => r,
-            // Resolution against /AACS inputs can only produce AACS
-            // keys. Either the dispatcher returned None (load failed)
-            // or — structurally impossible here — a CSS state. Both
-            // surface as the upstream miss-error.
-            _ => return Err(miss_error),
-        };
-
        Ok(AacsState {
-            version: match resolved.version {
-                aacs::AacsVersion::V10 => 1,
-                aacs::AacsVersion::V20 | aacs::AacsVersion::V21 => 2,
-            },
-            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::DeviceKey,
-                2 => KeySource::ProcessingKey,
-                3 => KeySource::KeyDbDerived,
-                4 => KeySource::KeyDb,
-                5 => KeySource::KeyDbUnitKeys,
-                _ => 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,
        })
    }
 }
@@ -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");
@@ -375,6 +375,79 @@ pub struct Extent {
    pub sector_count: u32,
 }

+/// Correct the channel count of a title's TrueHD audio streams by probing the
+/// first decrypted access units. The MPLS `audio_format` field declares the
+/// BASE layout (often 5.1) even for a 7.1/Atmos TrueHD track; the real count is
+/// in the MLP major sync. `reader` must yield DECRYPTED sectors (the m2ts is
+/// AACS-encrypted, so this can only run at mux time, not scan). Reads a bounded
+/// window of the title's first extent. Also regenerates the stream's codec
+/// label when it was the basic descriptor for the (now corrected) count —
+/// richer editorial labels (e.g. "Dolby Atmos") are left untouched.
+pub(crate) fn correct_truehd_channels(reader: &mut dyn SectorSource, title: &mut DiscTitle) {
+    use crate::mux::codec::truehd::truehd_channels_from_stream;
+
+    let pids: Vec<u16> = title
+        .streams
+        .iter()
+        .filter_map(|s| match s {
+            Stream::Audio(a) if matches!(a.codec, Codec::TrueHd) => Some(a.pid),
+            _ => None,
+        })
+        .collect();
+    if pids.is_empty() {
+        return;
+    }
+    let Some(ext) = title.extents.first() else {
+        return;
+    };
+    // Bounded probe: up to 8 MiB from the start of the title — enough for the
+    // first interleaved TrueHD major sync of each stream.
+    const PROBE_SECTORS: u32 = 4096;
+    let n = ext.sector_count.min(PROBE_SECTORS) as u16;
+    if n == 0 {
+        return;
+    }
+    let mut buf = vec![0u8; n as usize * 2048];
+    if reader
+        .read_sectors(ext.start_lba, n, &mut buf, true)
+        .is_err()
+    {
+        return;
+    }
+
+    let mut demux = crate::mux::ts::TsDemuxer::new(&pids);
+    let mut payloads: std::collections::HashMap<u16, Vec<u8>> = std::collections::HashMap::new();
+    for pes in demux.feed(&buf).into_iter().chain(demux.flush()) {
+        payloads
+            .entry(pes.pid)
+            .or_default()
+            .extend_from_slice(&pes.data);
+    }
+
+    for s in title.streams.iter_mut() {
+        let Stream::Audio(a) = s else { continue };
+        if !matches!(a.codec, Codec::TrueHd) {
+            continue;
+        }
+        let Some(payload) = payloads.get(&a.pid) else {
+            continue;
+        };
+        let Some(count) = truehd_channels_from_stream(payload) else {
+            continue;
+        };
+        let new_ch = AudioChannels::from_count(count);
+        if new_ch == AudioChannels::Unknown || new_ch == a.channels {
+            continue;
+        }
+        let was_basic =
+            a.label == crate::labels::generate_audio_label(&a.codec, &a.channels, a.secondary);
+        a.channels = new_ch;
+        if was_basic {
+            a.label = crate::labels::generate_audio_label(&a.codec, &new_ch, a.secondary);
+        }
+    }
+}
+
 /// Calculate how many bytes of bad/unreadable data fall within a title's extents.
 /// `pub(crate)` so autorip can use it for main-movie lost_ms computation.
 pub fn bytes_bad_in_title(title: &DiscTitle, bad_ranges: &[(u64, u64)]) -> u64 {
@@ -882,9 +955,9 @@ 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,
+    pub key_source: KeyOrigin,
    /// Volume Unique Key (16 bytes). `None` when keys were resolved
-    /// via the [`KeySource::KeyDbUnitKeys`] path — that source delivers
+    /// 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)
@@ -893,6 +966,13 @@ pub struct AacsState {
    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. Variants are ordered root-of-trust →
@@ -900,7 +980,7 @@ pub struct AacsState {
 /// 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 {
+pub enum KeyOrigin {
    /// MKB + device keys → subset-difference tree → VUK
    DeviceKey,
    /// MKB + processing keys → media key → VUK
@@ -912,67 +992,59 @@ pub enum KeySource {
    /// 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::DeviceKey => "MKB + device key",
-            KeySource::ProcessingKey => "MKB + processing key",
-            KeySource::KeyDbDerived => "KEYDB (derived)",
-            KeySource::KeyDb => "KEYDB",
-            KeySource::KeyDbUnitKeys => "KEYDB (unit keys)",
+            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,
@@ -1140,6 +1212,60 @@ impl Disc {
        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
@@ -1152,63 +1278,26 @@ impl Disc {
        capacity: u32,
        handshake: Option<HandshakeResult>,
        handshake_error: Option<Error>,
-        opts: &ScanOptions,
+        _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) => {
-                            // When the handshake itself failed AND resolution
-                            // bottomed out at "no keys", surface the upstream
-                            // handshake failure — it's more actionable than
-                            // the generic AacsNoKeys.
-                            let final_err = match (&e, handshake_error.as_ref()) {
-                                (
-                                    Error::AacsNoKeys
-                                    | Error::AacsVukNotInKeydb
-                                    | Error::AacsVidUnavailable,
-                                    Some(_),
-                                ) => handshake_error.unwrap(),
-                                _ => e,
-                            };
-                            tracing::warn!(
-                                target: "freemkv::disc",
-                                phase = "scan_aacs_resolve_failed",
-                                error_code = final_err.code(),
-                                keydb = %keydb_path.display(),
-                                handshake_ok = handshake.is_some(),
-                                "AACS key resolution failed"
-                            );
-                            (None, Some(final_err))
-                        }
-                    }
-                }
-                None => {
-                    tracing::warn!(
-                        target: "freemkv::disc",
-                        phase = "scan_aacs_no_keydb",
-                        "encrypted disc but no KEYDB found in search paths"
-                    );
-                    // Sentinel path string lets autorip's message switch
-                    // distinguish "no keydb found anywhere" from "keydb at
-                    // <path> failed to parse".
-                    let final_err =
-                        handshake_error.unwrap_or_else(|| crate::error::Error::KeydbLoad {
-                            path: String::from("<no keydb in search paths>"),
-                        });
-                    (None, Some(final_err))
-                }
-            }
-        } 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)
@@ -1340,6 +1429,44 @@ impl Disc {
            .cmp(&b_oversize)
            .then_with(|| a.clips.len().cmp(&b.clips.len()))
            .then_with(|| b.duration_secs.total_cmp(&a.duration_secs))
+            // Same length + clip count = the same feature authored as multiple
+            // playlists (a full-audio main vs an audio-reduced twin, e.g. Fight
+            // Club's 00800 [DTS-HD MA + 13 tracks] vs 00004 [stereo AC-3 only]).
+            // Prefer the richer audio so we never rip a stereo-only variant over
+            // the lossless-multichannel main feature.
+            .then_with(|| Self::audio_richness(b).cmp(&Self::audio_richness(a)))
+    }
+
+    /// Audio-richness rank for `canonical_title_order`'s same-length tiebreak.
+    /// Higher is better: `(any lossless track, best channel count, audio count)`.
+    fn audio_richness(t: &DiscTitle) -> (u8, u8, usize) {
+        let mut lossless = 0u8;
+        let mut max_ch = 0u8;
+        let mut count = 0usize;
+        for s in &t.streams {
+            if let Stream::Audio(a) = s {
+                count += 1;
+                if matches!(
+                    a.codec,
+                    Codec::TrueHd | Codec::DtsHdMa | Codec::DtsHdHr | Codec::Lpcm | Codec::Flac
+                ) {
+                    lossless = 1;
+                }
+                let ch = match a.channels {
+                    AudioChannels::Surround71 => 8,
+                    AudioChannels::Surround61 => 7,
+                    AudioChannels::Surround51 => 6,
+                    AudioChannels::Surround50 => 5,
+                    AudioChannels::Quad => 4,
+                    AudioChannels::Stereo21 => 3,
+                    AudioChannels::Stereo => 2,
+                    AudioChannels::Mono => 1,
+                    AudioChannels::Unknown => 0,
+                };
+                max_ch = max_ch.max(ch);
+            }
+        }
+        (lossless, max_ch, count)
    }

    fn detect_format(titles: &[DiscTitle]) -> DiscFormat {
@@ -1386,11 +1513,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,
@@ -1404,6 +1580,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
@@ -1488,6 +1810,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)
    }
@@ -1579,13 +1903,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).
@@ -2057,6 +2392,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)]
@@ -2078,6 +2426,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).
@@ -2572,6 +2927,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();
@@ -2588,6 +3166,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!(
@@ -2612,6 +3192,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!(
@@ -2642,6 +3224,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!(
@@ -2671,6 +3255,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!(
@@ -2688,6 +3274,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!(
@@ -2720,6 +3308,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();

@@ -2732,6 +3322,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!(
@@ -2764,6 +3356,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");
@@ -334,7 +334,7 @@ const FAIL_PAUSE_SECS: u64 = 5;
 /// FIRST read failure after a clean run, before the drive has had a
 /// chance to cycle in retries that push it toward fast-fail).
 ///
-/// Empirical: 2026-05-11 Dune Pt 2 wedge incident showed 7 medium
+/// Empirical: a 2026-05-11 wedge incident showed 7 medium
 /// errors in 6.5 seconds (~1s per attempt + ~1s pause) push the
 /// BU40N's firmware into IllegalRequest fast-fail mode permanently.
 /// Once there, only physical eject + reload clears it. Giving the
@@ -529,7 +529,7 @@ impl Drive {

                // /dev/sr0 pread fallback (Linux only). The kernel
                // sr_mod driver auto-retries failed reads (~5× per
-                // command). Empirically (BU40N + Dune Part 2 UHD,
+                // command). Empirically (BU40N + a UHD disc,
                // 2026-05-08) dd via /dev/sr0 recovers ~50% of bad
                // sectors that a single-shot SG_IO READ misses.
                #[cfg(target_os = "linux")]
@@ -246,11 +246,12 @@ mod tests {
        let uk_ro = vec![0u8; 256];
        let vid = [0u8; 16];
        let keydb = aacs::KeyDb::empty();
+        let providers: &[&dyn aacs::KeyProvider] = &[&keydb];
        let ctx_aacs = aacs::ResolveContext {
            unit_key_ro: &uk_ro,
            content_cert: None,
            volume_id: &vid,
-            keydb: &keydb,
+            providers,
            mkb: None,
        };
        let mut ctx = DrmContext {
@@ -272,12 +273,13 @@ mod tests {
        let uk_ro = vec![0u8; 256];
        let vid = [0xAAu8; 16];
        let keydb = aacs::KeyDb::empty();
+        let providers: &[&dyn aacs::KeyProvider] = &[&keydb];
        let mkb = mkb_with_variant();
        let ctx = aacs::ResolveContext {
            unit_key_ro: &uk_ro,
            content_cert: None,
            volume_id: &vid,
-            keydb: &keydb,
+            providers,
            mkb: Some(&mkb),
        };
        // Just confirm the symbol is callable; we don't assert on the
@@ -16,9 +16,6 @@
 //! The underlying mpsc channel is created with a very large slot count
 //! so the byte cap (not the slot count) is the real backpressure. Slot
 //! count is only there to give the kernel a small chunk to wake on.
-//!
-//! See `(internal)/memory/project_buffering_architecture.md` §
-//! Pipeline channel — sizing.

 use std::sync::mpsc::{Receiver as MpscReceiver, RecvError, SendError, SyncSender, sync_channel};
 use std::sync::{Arc, Condvar, Mutex};
@@ -23,8 +23,7 @@
 //! bounded channel + dedicated consumer thread.
 //!
 //! `byte_channel` is a byte-sized producer/consumer channel for the
-//! mux pipeline, sized to absorb worst-case input read stalls (see
-//! `(internal)/memory/project_buffering_architecture.md`).
+//! mux pipeline, sized to absorb worst-case input read stalls.

 pub(crate) mod bounded;
 pub mod byte_channel;
@@ -9,7 +9,6 @@
 //! sweep (migrated to `disc/sweep.rs::SweepSink`), patch, and mux.
 //! 0.18 collapses all three onto this primitive; sweep is in,
 //! patch and mux migrate in later 0.18 slices.
-//! See `(internal)/memory/0_18_redesign.md` for the full picture.
 //!
 //! ## Cancellation and error semantics
 //!
@@ -68,9 +67,7 @@ pub const JOIN_TIMEOUT_SECS: u64 = 600;
 ///
 /// 0.21.7 replaced an old `std::sync::mpsc::sync_channel` + 50 ms
 /// `thread::sleep` polling loop that capped mux throughput at
-/// ~20 frames/sec ≈ 1 MB/s on saturated channels. See
-/// (internal)/memory/feedback_send_with_halt_poll_throttle.md
-/// for the multi-day diagnostic that surfaced it.
+/// ~20 frames/sec ≈ 1 MB/s on saturated channels.
 use crate::halt::POLL_INTERVAL;
 const SEND_HALT_CHECK_INTERVAL: Duration = POLL_INTERVAL;

@@ -20,9 +20,6 @@
 //! 4 MiB buffer for the common local-disk case; `WritebackFile`
 //! (separate module) wraps a `File` with the adaptive-chunk
 //! `sync_file_range` machinery for the Linux+NFS case.
-//!
-//! See `(internal)/memory/project_buffering_architecture.md` for
-//! the full design and the source/sink matrix.

 use std::io::{Seek, Write};

@@ -47,7 +47,7 @@ impl SocketSink {
    /// writing. `sndbuf_bytes`, when present, is forwarded to
    /// `setsockopt(SO_SNDBUF)` as a kernel hint — the OS may clamp it.
    ///
-    /// `addr` accepts anything `ToSocketAddrs` does: `"10.0.0.1:1234"`,
+    /// `addr` accepts anything `ToSocketAddrs` does: `"192.0.2.1:1234"`,
    /// `("host", 1234)`, a `SocketAddr`, etc.
    pub fn connect<A: ToSocketAddrs>(addr: A, sndbuf_bytes: Option<usize>) -> io::Result<Self> {
        let stream = TcpStream::connect(addr)?;
@@ -0,0 +1,69 @@
+//! Key sources — the lookup layer that hands libfreemkv a [`Key`].
+//!
+//! libfreemkv performs NO key lookup. An application resolves a key for a disc
+//! through one or more [`KeySource`]s, each a dumb adapter over a backing store
+//! (a keydb file, a key server, the mapfile cache): given the disc's
+//! [`DiscInputs`] it returns the raw [`Key`] at whatever level it holds. The
+//! library then derives down and decrypts via `Disc::decrypt_with`.
+//!
+//! Source implementations are published in the companion `freemkv-keysources`
+//! crate — keeping all key *policy* (which store, which order, online vs local)
+//! out of the library while all key *mechanism* (the AACS derivation chain)
+//! stays in it.
+
+use crate::disc::Key;
+use crate::error::Result;
+
+/// The public AACS inputs a key source needs to look a disc up. Captured at
+/// scan; contains no secrets — only the disc identity and the on-disc AACS
+/// structures a source or key server may key on.
+#[derive(Debug, Clone)]
+pub struct DiscInputs {
+    /// SHA-1 of `Unit_Key_RO.inf`, `0x`-prefixed hex. The value a keydb keys
+    /// its per-disc entries by, and a key server identifies the disc with.
+    pub disc_hash: String,
+    /// Volume ID (16 bytes). `[0u8; 16]` when no authenticated handshake ran
+    /// (e.g. an ISO/mapfile flow), which disables VID-keyed lookups.
+    pub volume_id: [u8; 16],
+    /// Raw MKB bytes. Empty when not captured.
+    pub mkb: Vec<u8>,
+    /// Raw `Unit_Key_RO.inf` bytes. Empty when not captured.
+    pub unit_key_ro: Vec<u8>,
+    /// Encrypted on-disc content sample units (each a 6144-byte aligned unit),
+    /// for sources that validate a key server-side against real ciphertext
+    /// (e.g. an online key service). Empty for sources that don't need them
+    /// (a local keydb). Populated by the application — reading content requires
+    /// the disc reader, which the library's scan does not retain — so
+    /// [`crate::Disc::inputs`] leaves it empty for the caller to fill.
+    pub samples: Vec<Vec<u8>>,
+}
+
+/// A key source: given a disc's [`DiscInputs`], offer candidate [`Key`]s.
+///
+/// Dumb by contract — a source queries its backing store and enumerates the raw
+/// material it holds as candidate keys at whatever level it has (device /
+/// processing / media / volume / unit). It performs NO AACS derivation and NO
+/// validation; `Disc::decrypt_with` derives down, and the caller validates by
+/// decrypting a sample. That keeps every derivation step in one place (the
+/// library) across AACS 1.0 / 2.0 / 2.1 / 2.x.
+///
+/// A source returns *multiple ordered candidates* because a single store can
+/// hold material for several derivation paths (a keydb has a per-disc VUK *and*
+/// a device-key pool *and* a media-key pool — the source can't know which
+/// applies without the MKB walk, which is derivation). The caller tries the
+/// candidates in order and keeps the first that decrypts (validate-before-
+/// return). A source that resolves server-side (an online key service) or holds
+/// a cached final key (the mapfile) simply returns one candidate.
+pub trait KeySource {
+    /// Candidate keys for this disc, most-specific first. Empty = this source
+    /// has nothing; `Err(_)` = the source itself failed (I/O, network, parse).
+    fn resolve(&self, inputs: &DiscInputs) -> Result<Vec<Key>>;
+
+    /// Whether this source needs [`DiscInputs::samples`] populated (encrypted
+    /// content samples) — true for a source that validates against ciphertext
+    /// server-side, false for one that keys purely on disc identity. The caller
+    /// reads samples (an extra disc read) only when some source needs them.
+    fn needs_samples(&self) -> bool {
+        false
+    }
+}
@@ -38,7 +38,7 @@ use std::collections::BTreeMap;
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize, Default)]
 pub struct DiscMetadata {
    /// Localized titles, keyed by 3-char ISO 639-2 lang code
-    /// (e.g. "eng" → "Dune Part Two")
+    /// (e.g. "eng" → "Aurora Drift")
    pub titles: BTreeMap<String, String>,
    /// First-line / short description, per lang
    pub descriptions: BTreeMap<String, String>,
@@ -146,7 +146,7 @@ pub(crate) fn parse_bdmt_xml(_lang_code: &str, xml_text: &str) -> Option<BdmtFie
 }

 /// Reject candidate description strings that are themselves XML
-/// fragments — observed on disc-04 (Top Gun: Maverick), where
+/// fragments — observed on a captured disc, where
 /// `<di:description>` contained `<di:thumbnail href="…"/>` child
 /// elements and no actual prose. Surfacing that raw to the JSON
 /// output is worse than dropping the field entirely.
@@ -210,10 +210,10 @@ mod tests {
        // carrier inside a <discInfo> root.
        let xml = r#"<?xml version="1.0" encoding="UTF-8"?>
 <discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
-  <di:name>Dune Part Two</di:name>
+  <di:name>Aurora Drift</di:name>
 </discInfo>"#;
        let (title, desc, set) = parse_bdmt_xml("eng", xml).expect("title should parse");
-        assert_eq!(title, "Dune Part Two");
+        assert_eq!(title, "Aurora Drift");
        assert_eq!(desc, None);
        assert_eq!(set, None);
    }
@@ -223,12 +223,12 @@ mod tests {
        // <di:title> is the alternate carrier; should be picked up
        // when <di:name> is absent.
        let xml = r#"<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
-  <di:title>The Matrix</di:title>
-  <di:description>A film about computers.</di:description>
+  <di:title>Echo Chamber</di:title>
+  <di:description>A film about machines.</di:description>
 </discInfo>"#;
        let (title, desc, _) = parse_bdmt_xml("eng", xml).unwrap();
-        assert_eq!(title, "The Matrix");
-        assert_eq!(desc.as_deref(), Some("A film about computers."));
+        assert_eq!(title, "Echo Chamber");
+        assert_eq!(desc.as_deref(), Some("A film about machines."));
    }

    #[test]
@@ -238,17 +238,17 @@ mod tests {
        // titleName inside tableOfContents.
        let xml = r#"<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
  <di:tableOfContents>
-    <di:titleName>Inside Out 2</di:titleName>
+    <di:titleName>Feelings Two</di:titleName>
  </di:tableOfContents>
 </discInfo>"#;
        let (title, _, _) = parse_bdmt_xml("eng", xml).unwrap();
-        assert_eq!(title, "Inside Out 2");
+        assert_eq!(title, "Feelings Two");
    }

    #[test]
    fn extract_box_set_position() {
        let xml = r#"<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
-  <di:name>LOTR Disc 2</di:name>
+  <di:name>Box Set Disc 2</di:name>
  <di:discNumber>2</di:discNumber>
  <di:numSets>5</di:numSets>
 </discInfo>"#;
@@ -287,11 +287,11 @@ mod tests {
        // would. This exercises the BTreeMap key handling without
        // needing a UdfFs.
        let eng_xml = r#"<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
-  <di:name>Dune Part Two</di:name>
+  <di:name>Aurora Drift</di:name>
 </discInfo>"#;
        let fra_xml = r#"<discInfo xmlns:di="urn:BDA:bdmv;disclibmeta">
-  <di:name>Dune Deuxième Partie</di:name>
-  <di:description>Suite du film de 2021.</di:description>
+  <di:name>Aurora Drift (Partie Deux)</di:name>
+  <di:description>Suite du film fictif.</di:description>
 </discInfo>"#;

        let mut meta = DiscMetadata::default();
@@ -310,16 +310,16 @@ mod tests {

        assert_eq!(
            meta.titles.get("eng").map(String::as_str),
-            Some("Dune Part Two")
+            Some("Aurora Drift")
        );
        assert_eq!(
            meta.titles.get("fra").map(String::as_str),
-            Some("Dune Deuxième Partie")
+            Some("Aurora Drift (Partie Deux)")
        );
        assert!(meta.descriptions.get("eng").is_none());
        assert_eq!(
            meta.descriptions.get("fra").map(String::as_str),
-            Some("Suite du film de 2021.")
+            Some("Suite du film fictif.")
        );
        assert_eq!(meta.disc_number, None);
    }
@@ -342,21 +342,21 @@ mod tests {

    #[test]
    fn description_with_only_child_xml_is_dropped() {
-        // Real-world bug from disc-04 (Top Gun: Maverick, 2026-05-11
+        // Real-world bug from a captured disc (2026-05-11
        // capture): <di:description> contained only <di:thumbnail/>
        // child elements with no actual prose. The previous parser
        // surfaced the raw XML fragment as the description string.
        // Now we reject candidates that begin with `<`.
        let xml = r#"<discInfo>
-            <di:name>Top Gun: Maverick</di:name>
+            <di:name>Skyline Run</di:name>
            <di:description>
-              <di:thumbnail href="tgm_meta_sm.jpg" />
-              <di:thumbnail href="tgm_meta_lg.jpg" />
+              <di:thumbnail href="sample_meta_sm.jpg" />
+              <di:thumbnail href="sample_meta_lg.jpg" />
            </di:description>
        </discInfo>"#;
        let (title, description, _) =
            parse_bdmt_xml("eng", xml).expect("title is present so parse must succeed");
-        assert_eq!(title, "Top Gun: Maverick");
+        assert_eq!(title, "Skyline Run");
        assert!(
            description.is_none(),
            "description containing only XML children must be dropped, got {description:?}"
@@ -381,10 +381,10 @@ mod tests {
    #[test]
    fn whitespace_in_title_is_trimmed() {
        let xml = r#"<discInfo><di:name>
-            Dune Part Two
+            Aurora Drift
        </di:name></discInfo>"#;
        let (title, _, _) = parse_bdmt_xml("eng", xml).unwrap();
-        assert_eq!(title, "Dune Part Two");
+        assert_eq!(title, "Aurora Drift");
    }

    #[test]
@@ -7,8 +7,7 @@
 //! Stream labels live as plain ASCII strings inside compiled `.class`
 //! files in the jar — a quirk of the menu-rendering layer encoding
 //! its TextField positions and content as constant strings the
-//! Java compiler retained in the class string pool. Format observed
-//! in the corpus (Civil War UHD, 2024):
+//! Java compiler retained in the class string pool. Observed format:
 //!
 //! ```text
 //! LTextField,Audio1,English Dolby Atmos,Fontstrip_Composite,...
@@ -1,83 +1,65 @@
 //! Deluxe BD-J framework — `com/bydeluxe/bluray/` package signature.
 //!
-//! Used by major studios (Disney, Warner, others) for their UHD
-//! BD-J authoring. Detected on discs whose `/BDMV/JAR/<x>.jar`
-//! contains a `com/bydeluxe/` directory entry.
+//! Detected on discs whose `/BDMV/JAR/<x>.jar` contains a
+//! `com/bydeluxe/` directory entry.
 //!
-//! ## Why this parser exists
+//! ## What this parser reads
 //!
-//! Deluxe-authored discs store stream labels as **ordinal references
-//! into obfuscated enum classes**. The label text isn't a literal
-//! string in any anchor pattern (unlike dbp's `TextField,...` rows).
-//! Instead, the binding code is roughly:
-//!
-//! ```java
-//! streamTable.put(1, new AudioSlot(LanguageEnum.English,
-//!                                  CodecEnum.ATMOS_HD_AUDIO,
-//!                                  PurposeEnum.Normal));
-//! ```
-//!
-//! The class names `LanguageEnum`, `CodecEnum`, `PurposeEnum`, and
-//! `AudioSlot` are obfuscated per-disc (`be.class`, `ma.class`,
-//! `lp.class`, etc.) — no name pattern survives the obfuscator. But
-//! the **shape of `<clinit>`** is framework-stable:
+//! Deluxe-authored discs store stream labels as ordinal references into
+//! enum classes whose names are obfuscated per-disc, so a name-based
+//! match won't work. The label data is instead recovered by matching on
+//! the **shape of each enum's `<clinit>`**, which is framework-stable:
 //!
 //! | Enum | Signature |
 //! |---|---|
 //! | Language | 70 `ldc` operations in `<clinit>`, sequence starts `English, French, Spanish, Dutch, ...` |
 //! | Purpose | 8 ldcs starting `Normal, Commentary, PiP, Trivia, ...` |
 //! | VideoFormat | 7 ldcs starting `HD, HDR10 Plus, HD Dolby, ...` |
-//! | Region | 22 ldcs starting `USA_D1, LIC1, LIC2, LIC3, ...` (Disney only) |
-//! | Studio | 6 ldcs starting `Disney, Marvel, Pixar, ...` (Disney only) |
-//! | Codec | ~46 `new` instructions, 0 ldcs in `<clinit>` (codec strings live in subclasses) |
+//! | Region | 22 ldcs starting `USA_D1, LIC1, LIC2, LIC3, ...` |
+//! | Studio | 6 ldcs starting `Disney, Marvel, Pixar, ...` |
+//! | Codec | many `new` instructions, 0 ldcs in `<clinit>` (codec strings live in subclasses) |
 //!
-//! Match on the SHAPE, not the name, and the parser survives obfuscation.
+//! Matching on the shape rather than the class name keeps the parser
+//! working across obfuscation variants.
 //!
 //! ## Implementation phases
 //!
 //! - **Phase A** — master enum identification (`identify_master_enums`).
 //!   Walks every `.class`'s `<clinit>` ldc sequence and matches against
 //!   the framework-stable fingerprints. Output: `Vec<(label, MasterEnum)>`
-//!   with full ordinal → string-value tables. **Empirically verified**
-//!   on disc-01 (Disney) + disc-09 (Warner).
+//!   with full ordinal → string-value tables.
 //!
 //! - **Phase B** — codec enum subclass walk (`decode_codec_enum`).
-//!   The codec enum's `<clinit>` has ~46 `new` instructions and zero
+//!   The codec enum's `<clinit>` has many `new` instructions and zero
 //!   string ldcs — codec name strings live in the subclasses each
 //!   `new` constructs. Walks every referenced subclass's constant
-//!   pool, extracts the codec name string. **Structural shape
-//!   verified** on disc-01 (ma.class, 41 `new` ops) + disc-09
-//!   (ea.class, 46 `new` ops); per-subclass string extraction
-//!   designed against the published Java enum compilation convention
-//!   (each enum value's `<init>` is called with its name string as
-//!   the first arg).
+//!   pool, extracts the codec name string, following the standard Java
+//!   enum compilation convention (each enum value's `<init>` is called
+//!   with its name string as the first arg).
 //!
 //! - **Phase C** — binding-class identification (`find_binding_classes`).
 //!   The per-stream table is built by some class via repeated
 //!   `getstatic` references to the master enums identified in A.
 //!   That class has the highest such `getstatic` count in the jar.
-//!   **Heuristic shape**; precise threshold may need tuning.
+//!   Heuristic shape; precise threshold may need tuning.
 //!
 //! - **Phase D** — binding-class bytecode decoder (`decode_binding`).
 //!   Walks the binding class's `<clinit>` with a tiny symbolic stack
 //!   machine. For each `new X / dup / ... / invokespecial X.<init>`
 //!   sequence, collects the int values and enum-reference operands
 //!   between the `dup` and the constructor call, then emits a
-//!   `DecodedStream`. **Mechanism verified** in unit tests against
-//!   synthetic class fixtures; the **signal-to-StreamLabel mapping**
-//!   (which arg is stream index? which is language? audio vs
-//!   subtitle?) uses a documented heuristic that needs corpus-disc
-//!   verification — see `interpret_stream` for the mapping rules.
+//!   `DecodedStream`. The signal-to-StreamLabel mapping (which arg is
+//!   stream index? which is language? audio vs subtitle?) uses a
+//!   heuristic — see `interpret_streams` for the mapping rules.
 //!
 //! ## Confidence
 //!
 //! [`parse`] returns `Some(ParseResult::medium(labels))` when Phases A
 //! through D produce at least one stream — `Medium` because the
-//! signal-to-label mapping is heuristic until real disc bytecode
-//! confirms the binding pattern. Once verified the parser can promote
-//! to `High`. `None` when the disc isn't Deluxe-authored or when
-//! decoding produces zero streams (a recognized-but-broken state that
-//! the analyzer still surfaces via `parsers_detected`).
+//! signal-to-label mapping is heuristic. `None` when the disc isn't
+//! Deluxe-authored or when decoding produces zero streams (a
+//! recognized-but-broken state that the analyzer still surfaces via
+//! `parsers_detected`).

 use super::class_reader::{
    AASTORE, BIPUSH, ClassFile, CodeAttribute, ConstantPool, CpInfo, GETSTATIC, ICONST_0, ICONST_1,
@@ -559,10 +541,9 @@ fn clinit_news_and_ldcs(
 /// candidates ordered by descending getstatic count, filtered to a
 /// minimum concentration of master-enum references.
 ///
-/// Empirically (POC v0.3 dumps): on disc-01 the audio binding class
-///   (`ma.class`) has ~82 getstatic refs, the subtitle binding
-///   (`ko.class`) has ~63. Both share the master Language + Purpose
-///   enums.
+/// A disc that splits the table commonly has one audio binding class
+/// with the most getstatic refs and a subtitle binding class with
+/// somewhat fewer; both share the master Language + Purpose enums.
 pub(crate) fn find_binding_classes(
    archive: &mut jar::Jar,
    master_enum_classes: &HashSet<&str>,
@@ -641,10 +622,9 @@ pub(crate) enum StackVal {
    /// name (e.g. `DOLBY_AC3_AUDIO`, `DOLBY_LOSSLESS_AUDIO`) is the
    /// codec identifier. Deluxe binding constructors take a
    /// `LCodingType;` arg directly — codecs are NOT a Deluxe-internal
-    /// enum (Phase B's codec-subclass walk was based on a wrong
-    /// assumption; the actual codec source is the standard BD-J API
-    /// enum). Discovered via deluxe-poc v0.3 binding-bytecode dump
-    /// against disc-01 (Disney) + disc-09 (Warner) on 2026-05-10.
+    /// enum; the codec source is the standard BD-J API `CodingType`
+    /// enum, so the binding constructor's codec arg is read straight
+    /// from that getstatic operand.
    CodingType(String),
    /// An uninitialized `new` object — popped by the matching
    /// invokespecial.
@@ -988,11 +968,10 @@ impl MasterEnumTable {
 // ── interpret_streams: Constructions → StreamLabels ─────────────────────────

 /// Convert the per-construction tuples from Phase D into
-/// [`StreamLabel`]s. Pattern verified against corpus discs via
-/// deluxe-poc v0.3 binding-bytecode dump (2026-05-10):
+/// [`StreamLabel`]s. Two binding-constructor shapes are handled:
 ///
-/// Disney binding (5-arg): `BindingType.<init>(I, Lbe;, Llp;, I, LCodingType;)V`
-/// Warner binding (4-arg): `BindingType.<init>(I, Law;, Lgp;, LCodingType;)V`
+/// 5-arg: `BindingType.<init>(I, Lang;, Lpurpose;, I, LCodingType;)V`
+/// 4-arg: `BindingType.<init>(I, Lang;, Lpurpose;, LCodingType;)V`
 ///
 /// Args are identified by **TYPE**, not position:
 /// - First `EnumRef{kind: "Language"}` → audio/subtitle language
@@ -1098,11 +1077,10 @@ fn interpret_streams(constructions: &[Construction], master: &MasterEnumTable) -
 /// getstatic operands on Deluxe binding classes) to a human-readable
 /// codec hint string.
 ///
-/// CodingType is the standard BD-J API enum; values are documented
-/// in the BD-J specification and verified empirically against the
-/// binding-bytecode dumps in `(internal)/research/deluxe-poc/data/`.
-/// Unknown field names pass through unchanged so unfamiliar codecs
-/// still surface something rather than going silent.
+/// CodingType is the standard BD-J API enum; values are documented in
+/// the BD-J specification. Unknown field names pass through unchanged
+/// so unfamiliar codecs still surface something rather than going
+/// silent.
 fn coding_type_to_codec_hint(field: &str) -> &str {
    match field {
        // Lossless / hi-res.
@@ -207,14 +207,41 @@ pub(crate) fn apply_labels(labels: &[StreamLabel], titles: &mut [DiscTitle]) {
                        // Structured fields — callers translate purpose to UI text.
                        a.purpose = label.purpose;

+                        // Codec descriptor: trust the parser's `codec_hint` ONLY
+                        // when it's consistent with the stream's actual codec — it
+                        // may legitimately be richer (e.g. "Dolby Atmos" on a TrueHD
+                        // stream, which the raw spec codec can't express). If the
+                        // hint CONTRADICTS the stream (a mis-bound / shuffled label,
+                        // e.g. "AC-3 2.0" on a TrueHD track, or "TrueHD" on a DD+
+                        // track), discard it and derive the descriptor from the
+                        // stream itself — that's correct per-stream and can never be
+                        // shuffled. An empty hint is left for `fill_defaults`.
+                        let codec_desc = if label.codec_hint.is_empty() {
+                            // No codec hint — leave for fill_defaults.
+                            String::new()
+                        } else if !codec_hint_consistent(&label.codec_hint, &a.codec) {
+                            // Hint contradicts the stream (mis-bound / shuffled):
+                            // derive from the stream itself.
+                            generate_audio_label(&a.codec, &a.channels, a.secondary)
+                        } else if codec_hint_adds_detail(&label.codec_hint) {
+                            // Consistent AND richer than the spec codec can express
+                            // (e.g. "Dolby Atmos", "DTS:X") — keep the parser's hint.
+                            label.codec_hint.clone()
+                        } else {
+                            // Consistent but a plain codec/channel restatement —
+                            // normalize to the stream's own marketing descriptor so
+                            // styling is uniform across tracks.
+                            generate_audio_label(&a.codec, &a.channels, a.secondary)
+                        };
+
                        // a.label only carries codec/variant info. NEVER any
                        // English purpose text — the CLI handles that via i18n.
                        let mut parts = Vec::new();
                        if !label.variant.is_empty() {
                            parts.push(format!("({})", label.variant));
                        }
-                        if !label.codec_hint.is_empty() {
-                            parts.push(label.codec_hint.clone());
+                        if !codec_desc.is_empty() {
+                            parts.push(codec_desc);
                        }
                        if !parts.is_empty() {
                            a.label = parts.join(" ");
@@ -322,7 +349,70 @@ fn generate_video_label(
    parts.join(" ")
 }

-fn generate_audio_label(
+/// Does the parser's `codec_hint` name a codec consistent with the stream's
+/// actual `codec`? [`apply_labels`] uses this to keep richer-but-consistent
+/// hints (e.g. "Dolby Atmos" on a TrueHD stream — Atmos is a TrueHD extension
+/// the raw spec codec can't express) while rejecting mis-bound ones (e.g.
+/// "AC-3 2.0" on a TrueHD stream, the shuffled-label bug). Matching is by codec
+/// FAMILY parsed out of the hint string. "Atmos" with no carrier named is
+/// treated as compatible with its lossless carriers (TrueHD / E-AC-3). A hint
+/// naming no recognizable codec family (pure editorial, e.g. "Commentary") is
+/// consistent — it isn't asserting a codec.
+fn codec_hint_consistent(hint: &str, codec: &crate::disc::Codec) -> bool {
+    use crate::disc::Codec;
+    let h = hint.to_ascii_lowercase();
+
+    let says_truehd = h.contains("truehd") || h.contains("true hd");
+    let says_ddp = h.contains("ac-3+")
+        || h.contains("ac3+")
+        || h.contains("e-ac-3")
+        || h.contains("eac-3")
+        || h.contains("eac3")
+        || h.contains("digital plus")
+        || h.contains("dd+");
+    let says_ac3 =
+        !says_ddp && (h.contains("ac-3") || h.contains("ac3") || h.contains("dolby digital"));
+    let says_dts_ma = h.contains("master audio") || h.contains("hd ma");
+    let says_dts_hr = h.contains("high resolution") || h.contains("hd hr");
+    let says_dts = !says_dts_ma && !says_dts_hr && h.contains("dts");
+    let says_lpcm = h.contains("lpcm") || h.contains("pcm");
+    let says_atmos = h.contains("atmos");
+
+    let names_family =
+        says_truehd || says_ddp || says_ac3 || says_dts_ma || says_dts_hr || says_dts || says_lpcm;
+
+    // Pure-editorial hint (no codec family named) isn't asserting a codec →
+    // consistent. "Atmos" alone implies a lossless carrier (TrueHD or DD+).
+    if !names_family {
+        return if says_atmos {
+            matches!(codec, Codec::TrueHd | Codec::Ac3Plus)
+        } else {
+            true
+        };
+    }
+
+    match codec {
+        Codec::TrueHd => says_truehd || says_atmos,
+        Codec::Ac3Plus => says_ddp || says_atmos,
+        Codec::Ac3 => says_ac3,
+        Codec::DtsHdMa => says_dts_ma,
+        Codec::DtsHdHr => says_dts_hr,
+        Codec::Dts => says_dts,
+        Codec::Lpcm => says_lpcm,
+        // Unknown / other stream codec — don't second-guess the parser's hint.
+        _ => true,
+    }
+}
+
+/// Does the hint carry object-audio detail the spec codec can't express
+/// (Atmos / DTS:X)? Such hints are kept verbatim; plain codec/channel hints are
+/// normalized to the stream's own descriptor for uniform styling across tracks.
+fn codec_hint_adds_detail(hint: &str) -> bool {
+    let h = hint.to_ascii_lowercase();
+    h.contains("atmos") || h.contains("dts:x") || h.contains("dts-x") || h.contains("dtsx")
+}
+
+pub(crate) fn generate_audio_label(
    codec: &crate::disc::Codec,
    channels: &crate::disc::AudioChannels,
    _secondary: bool,
@@ -954,7 +1044,7 @@ mod gap_fill_tests {

    #[test]
    fn partial_yield_fills_gaps_keeps_framework() {
-        // Oppenheimer-style: framework matched but only labeled 2 of 6 audios.
+        // Partial-coverage case: framework matched but only labeled 2 of 6 audios.
        let mut framework = vec![
            label(StreamLabelType::Audio, 1, "eng", "Atmos"),
            label(StreamLabelType::Audio, 4, "eng", "Commentary"),
@@ -1182,6 +1272,94 @@ mod apply_tests {
        }
    }

+    #[test]
+    fn apply_rejects_mismatched_codec_hint_and_uses_stream_codec() {
+        // Paddington case: a TrueHD+Atmos main track the parser mislabeled
+        // "AC-3 2.0" (a compat-core hint bound to the wrong stream). The hint
+        // contradicts the stream's real codec → discard it, use the stream's own.
+        let mut titles = vec![title_with(vec![audio(
+            0x1100,
+            Codec::TrueHd,
+            AudioChannels::Surround71,
+            "eng",
+        )])];
+        let labels = vec![audio_label(1, "eng", "AC-3 2.0", "")];
+        apply_labels(&labels, &mut titles);
+        if let Stream::Audio(a) = &titles[0].streams[0] {
+            assert_eq!(a.label, "Dolby TrueHD 7.1");
+        } else {
+            panic!("expected audio stream");
+        }
+    }
+
+    #[test]
+    fn apply_unshuffles_cross_labeled_streams() {
+        // Wicked case: hints fully cross-bound — a TrueHD stream wears "AC-3 5.1"
+        // and a DD+ stream wears "TrueHD 5.1". Each is corrected from its own
+        // stream codec, eliminating the shuffle.
+        let mut titles = vec![title_with(vec![
+            audio(0x1100, Codec::TrueHd, AudioChannels::Surround51, "eng"),
+            audio(0x1101, Codec::Ac3Plus, AudioChannels::Surround51, "spa"),
+        ])];
+        let labels = vec![
+            audio_label(1, "eng", "AC-3 5.1", ""),
+            audio_label(2, "spa", "TrueHD 5.1", ""),
+        ];
+        apply_labels(&labels, &mut titles);
+        let got: Vec<String> = titles[0]
+            .streams
+            .iter()
+            .filter_map(|s| {
+                if let Stream::Audio(a) = s {
+                    Some(a.label.clone())
+                } else {
+                    None
+                }
+            })
+            .collect();
+        assert_eq!(got, vec!["Dolby TrueHD 5.1", "Dolby Digital Plus 5.1"]);
+    }
+
+    #[test]
+    fn apply_keeps_consistent_richer_atmos_hint() {
+        // A DD+ Atmos stream legitimately labeled "Dolby Atmos" — the hint is
+        // richer than the spec codec yet consistent with it, so it's kept.
+        let mut titles = vec![title_with(vec![audio(
+            0x1100,
+            Codec::Ac3Plus,
+            AudioChannels::Surround51,
+            "eng",
+        )])];
+        let labels = vec![audio_label(1, "eng", "Dolby Atmos", "")];
+        apply_labels(&labels, &mut titles);
+        if let Stream::Audio(a) = &titles[0].streams[0] {
+            assert_eq!(a.label, "Dolby Atmos");
+        } else {
+            panic!("expected audio stream");
+        }
+    }
+
+    #[test]
+    fn apply_normalizes_plain_consistent_hint_to_marketing() {
+        // Wicked's French track: a DD+ stream whose hint "AC-3+ 5.1" is correct
+        // but short-form. A sibling DD+ track that fell back uses the marketing
+        // form — keeping the short form here would read inconsistently, so a
+        // plain (non-richer) consistent hint is normalized to the stream's own.
+        let mut titles = vec![title_with(vec![audio(
+            0x1100,
+            Codec::Ac3Plus,
+            AudioChannels::Surround51,
+            "fra",
+        )])];
+        let labels = vec![audio_label(1, "fra", "AC-3+ 5.1", "")];
+        apply_labels(&labels, &mut titles);
+        if let Stream::Audio(a) = &titles[0].streams[0] {
+            assert_eq!(a.label, "Dolby Digital Plus 5.1");
+        } else {
+            panic!("expected audio stream");
+        }
+    }
+
    #[test]
    fn apply_sets_purpose_on_audio_commentary() {
        let mut titles = vec![title_with(vec![audio(
@@ -1342,9 +1520,11 @@ mod apply_tests {
        if let Stream::Audio(a) = &titles[0].streams[1] {
            assert_eq!(a.label, "Dolby Atmos");
        }
-        // Audio #2 (4th stream overall)
+        // Audio #2 (4th stream overall). The plain "Dolby Digital" hint is
+        // consistent with the AC-3 stream but carries no channel info, so it's
+        // normalized to the stream's own uniform descriptor.
        if let Stream::Audio(a) = &titles[0].streams[3] {
-            assert_eq!(a.label, "Dolby Digital");
+            assert_eq!(a.label, "Dolby Digital 2.0");
        }
        // Subtitle #1
        if let Stream::Subtitle(s) = &titles[0].streams[2] {
@@ -37,14 +37,47 @@ pub fn parse(reader: &mut dyn SectorSource, udf: &UdfFs) -> Option<ParseResult>
    // but the corpus surfaced something we don't catalogue.
    let saw_unknown = AtomicBool::new(false);

+    let labels = assign_labels(&strings, &saw_unknown);
+
+    if labels.is_empty() {
+        return None;
+    }
+    let confidence = if saw_unknown.load(Ordering::Relaxed) {
+        Confidence::Medium
+    } else {
+        Confidence::High
+    };
+    Some(ParseResult { labels, confidence })
+}
+
+/// Walk the extracted token strings of the feature section and emit a
+/// `StreamLabel` per editorial token, numbered in STN order. Split out
+/// from `parse` so the section/numbering logic is unit-testable without
+/// a `SectorSource`/`UdfFs`.
+fn assign_labels(strings: &[String], saw_unknown: &AtomicBool) -> Vec<StreamLabel> {
+    // The authoritative per-feature stream list lives in the `FPL_`
+    // (FeaturePLaylist) section, in STN order. `SEG_*` entries are menu
+    // segments (intros, logos, disclaimers, previews) that can also carry
+    // stray stream tokens — e.g. a `SEG_MainFeature` preview segment that
+    // lists only a commentary track. Anchoring on such a segment grabs the
+    // wrong streams and misnumbers them. So when the project ships any
+    // `FPL_` playlist, anchor exclusively on it; only fall back to
+    // `SEG_MainFeature` on discs that have no `FPL_` section at all.
+    let has_fpl = strings.iter().any(|s| s.starts_with("FPL_"));
+
    let mut labels = Vec::new();
    let mut in_feature = false;
    let mut audio_num: u16 = 0;
    let mut sub_num: u16 = 0;

-    for s in &strings {
+    for s in strings {
        // Detect feature section start
-        if s.starts_with("FPL_") || s.starts_with("SEG_MainFeature") {
+        let is_start = if has_fpl {
+            s.starts_with("FPL_")
+        } else {
+            s.starts_with("SEG_MainFeature")
+        };
+        if is_start {
            if in_feature {
                break;
            }
@@ -63,7 +96,25 @@ pub fn parse(reader: &mut dyn SectorSource, udf: &UdfFs) -> Option<ParseResult>
            continue;
        }

-        if let Some(label) = parse_token_inner(s, Some(&saw_unknown)) {
+        // Generic audio-slot placeholder. Pixelogic lists each audio stream
+        // in the playlist as either an editorial `{lang}_{codec}_…` token OR
+        // a bare `Audio Stream N` placeholder when no editorial label was
+        // authored. The placeholder carries nothing to label, but it DOES
+        // occupy an STN slot — so it must advance `audio_num`. Otherwise a
+        // later editorial token (e.g. a lone `eng_ACOM_` commentary sitting
+        // at STN slot 4, behind three unlabelled main tracks) collapses onto
+        // slot 1 and its Commentary purpose lands on the main feature track.
+        //
+        // Only audio is corrected here: subtitle (`PG Stream N`) numbering is
+        // left exactly as-is — the corpus snapshots show forced/commentary
+        // subtitle tokens already align with STN without counting the
+        // placeholders, and counting them regresses several discs.
+        if s.starts_with("Audio Stream") {
+            audio_num += 1;
+            continue;
+        }
+
+        if let Some(label) = parse_token_inner(s, Some(saw_unknown)) {
            match label.stream_type {
                StreamLabelType::Audio => {
                    audio_num += 1;
@@ -83,15 +134,7 @@ pub fn parse(reader: &mut dyn SectorSource, udf: &UdfFs) -> Option<ParseResult>
        }
    }

-    if labels.is_empty() {
-        return None;
-    }
-    let confidence = if saw_unknown.load(Ordering::Relaxed) {
-        Confidence::Medium
-    } else {
-        Confidence::High
-    };
-    Some(ParseResult { labels, confidence })
+    labels
 }

 fn parse_token_inner(s: &str, saw_unknown: Option<&AtomicBool>) -> Option<StreamLabel> {
@@ -250,4 +293,75 @@ mod tests {
        assert!(parse_token_inner("XX_MLP_", None).is_none());
        assert!(parse_token_inner("ENG_MLP_", None).is_none()); // uppercase not accepted as ISO 639-2
    }
+
+    fn strs(v: &[&str]) -> Vec<String> {
+        v.iter().map(|s| s.to_string()).collect()
+    }
+
+    #[test]
+    fn assign_labels_numbers_commentary_behind_placeholders() {
+        // Observed case: the FPL_MainFeature playlist lists three unlabelled main
+        // audio tracks as `Audio Stream N` placeholders, then a lone
+        // `eng_ACOM_` commentary at STN slot 4. The commentary must land on
+        // audio #4, not collapse onto #1 (which would tag the main feature
+        // track as commentary).
+        let flag = AtomicBool::new(false);
+        let tokens = strs(&[
+            "FPL_MainFeature",
+            "Audio Stream 1",
+            "Audio Stream 2",
+            "Audio Stream 3",
+            "eng_ACOM_",
+        ]);
+        let labels = assign_labels(&tokens, &flag);
+        let audio: Vec<_> = labels
+            .iter()
+            .filter(|l| l.stream_type == StreamLabelType::Audio)
+            .collect();
+        assert_eq!(audio.len(), 1, "only the commentary carries a label");
+        assert_eq!(audio[0].stream_number, 4, "commentary is STN slot 4");
+        assert_eq!(audio[0].purpose, LabelPurpose::Commentary);
+        assert_eq!(audio[0].language, "eng");
+    }
+
+    #[test]
+    fn assign_labels_prefers_fpl_over_seg_mainfeature() {
+        // A `SEG_MainFeature` menu/preview segment carries a stray commentary
+        // token, but the real playlist is `FPL_MainFeature`. When an FPL_
+        // section exists, the SEG_ one must be ignored as an anchor — so we
+        // number from the FPL playlist, putting the commentary at slot 2.
+        let flag = AtomicBool::new(false);
+        let tokens = strs(&[
+            "SEG_MainFeature",
+            "eng_ACOM_", // stray token in the menu segment — must be ignored
+            "FPL_MainFeature",
+            "Audio Stream 1",
+            "eng_ACOM_",
+        ]);
+        let labels = assign_labels(&tokens, &flag);
+        let audio: Vec<_> = labels
+            .iter()
+            .filter(|l| l.stream_type == StreamLabelType::Audio)
+            .collect();
+        assert_eq!(audio.len(), 1);
+        assert_eq!(audio[0].stream_number, 2, "numbered from the FPL playlist");
+        assert_eq!(audio[0].purpose, LabelPurpose::Commentary);
+    }
+
+    #[test]
+    fn assign_labels_falls_back_to_seg_without_fpl() {
+        // Discs with no FPL_ playlist still anchor on SEG_MainFeature.
+        let flag = AtomicBool::new(false);
+        let tokens = strs(&["SEG_MainFeature", "eng_MLP_", "spa_AC3_"]);
+        let labels = assign_labels(&tokens, &flag);
+        let audio: Vec<_> = labels
+            .iter()
+            .filter(|l| l.stream_type == StreamLabelType::Audio)
+            .collect();
+        assert_eq!(audio.len(), 2);
+        assert_eq!(audio[0].stream_number, 1);
+        assert_eq!(audio[0].language, "eng");
+        assert_eq!(audio[1].stream_number, 2);
+        assert_eq!(audio[1].language, "spa");
+    }
 }
@@ -10,8 +10,7 @@
 //! - English text → [`LabelPurpose`] (Commentary / Descriptive / etc.).
 //! - English text → [`LabelQualifier`] (SDH / Forced / Descriptive Service).
 //!
-//! Rules of engagement (carried over from
-//! `(internal)/memory/feedback_label_data_rules.md`):
+//! Rules of engagement:
 //!
 //! 1. Only map values we are 100% certain about — published codec
 //!    names, well-known ISO 639-2 mappings, vendor-documented purpose
@@ -85,6 +85,7 @@ pub(crate) mod identity;
 pub(crate) mod ifo;
 pub mod io;
 pub mod keydb;
+pub mod keysource;
 pub mod labels;
 pub(crate) mod mpls;
 pub mod mux;
@@ -170,10 +171,11 @@ pub use decrypt::{DecryptKeys, decrypt_sectors, decrypt_threads, set_decrypt_thr
 // prefix at the crate root to keep both addressable.
 pub use disc::{
    AacsState, AudioChannels, AudioStream, Clip, Codec, ColorSpace, ContentFormat, DamageSeverity,
-    Disc, DiscFormat, DiscId, DiscTitle, Extent, FrameRate, HdrFormat, KeySource, LabelPurpose,
-    LabelQualifier, PatchOptions, PatchOutcome, Resolution, SampleRate, ScanOptions, Stream,
-    SubtitleStream, SweepOptions, VideoStream, classify_damage,
+    Disc, DiscFormat, DiscId, DiscTitle, DriveCredentials, Extent, FrameRate, HdrFormat, Key,
+    KeyOrigin, LabelPurpose, LabelQualifier, PatchOptions, PatchOutcome, Resolution, SampleRate,
+    ScanOptions, Stream, SubtitleStream, SweepOptions, VideoStream, classify_damage,
 };
+pub use keysource::{DiscInputs, KeySource};

 // ─── Streams ────────────────────────────────────────────────────────────────
 //
@@ -301,9 +301,21 @@ fn parse_stream_entry(item: &[u8], pos: usize, stream_type: u8) -> Option<(Strea
        return None;
    }

-    // PID from stream entry (type 0x01 = PlayItem stream: PID at bytes 2-3)
-    let pid = if item[pos + 1] == 0x01 && pos + 4 <= item.len() {
-        u16::from_be_bytes([item[pos + 2], item[pos + 3]])
+    // PID location depends on the stream-entry type (BD spec stream_entry()):
+    //   type 1 (stream in the PlayItem's Clip):          PID at +2
+    //   type 2 (stream in a SubPath SubClip):            +subpath_id(1)+subclip_id(1) → PID at +4
+    //   type 3 / 4 (SubPath clip; type 4 = Dolby Vision  +subpath_id(1)              → PID at +3
+    //              enhancement layer, e.g. PID 0x1015):
+    // Previously only type 1 was handled, so the DV EL (type 4) and any
+    // sub-path stream fell through to PID 0 and were dropped by the mux.
+    let pid_off = match item[pos + 1] {
+        0x01 => 2,
+        0x02 => 4,
+        0x03 | 0x04 => 3,
+        _ => 0,
+    };
+    let pid = if pid_off != 0 && pos + pid_off + 2 <= item.len() {
+        u16::from_be_bytes([item[pos + pid_off], item[pos + pid_off + 1]])
    } else {
        0
    };
@@ -64,23 +64,40 @@ impl CodecParser for DtsParser {
                break;
            }

-            // Check for DTS-HD extension after core
-            let mut total_size = core_size;
-            if start + core_size + 4 <= data.len() {
-                if let Some(0) = find_sync(
-                    &data[start + core_size..start + core_size + 4],
-                    &DTS_HD_EXT_SYNC,
-                ) {
-                    let ext = &data[start + core_size..];
-                    if ext.len() >= 9 {
-                        let ext_size = dts_hd_ext_frame_size(ext);
-                        if start + core_size + ext_size <= data.len() {
-                            total_size = core_size + ext_size;
-                        }
-                        // If ext incomplete, just emit core
-                    }
+            // Include the DTS-HD extension substream if one immediately follows
+            // the core. The extension carries the LOSSLESS (DTS-HD MA / HRA)
+            // data; emitting a core-only frame and dropping the trailing
+            // extension silently downgrades the track to lossy DTS core. If we
+            // can't yet tell whether an extension follows, or it's present but
+            // not fully buffered, WAIT for more PES data (break, leaving `pos`
+            // at this access unit's core sync so the buffer keeps the partial
+            // unit) rather than splitting the extension off and losing it.
+            let after = start + core_size;
+            let avail = data.len() - after;
+            // Does a DTS-HD extension substream follow the core? Match the full
+            // sync when it's buffered, or a partial PREFIX when the buffer ends
+            // mid-sync — so we wait for the rest instead of splitting the
+            // extension off and losing the lossless data. Nothing after the core
+            // (e.g. the final access unit / EOF, with no parser flush) is taken
+            // as a legitimate lossy core-only unit.
+            let ext_follows = if avail >= 4 {
+                data[after..after + 4] == DTS_HD_EXT_SYNC
+            } else if avail > 0 {
+                DTS_HD_EXT_SYNC[..avail] == data[after..]
+            } else {
+                false
+            };
+            let total_size = if !ext_follows {
+                core_size
+            } else if avail < 9 {
+                break; // extension present but its size header isn't buffered — wait
+            } else {
+                let ext_size = dts_hd_ext_frame_size(&data[after..]);
+                if ext_size == 0 || avail < ext_size {
+                    break; // extension known but not fully buffered — wait
                }
-            }
+                core_size + ext_size
+            };

            frames.push(Frame {
                pts_ns,
@@ -204,6 +221,47 @@ mod tests {
        assert_eq!(frames[0].data.len(), 512);
    }

+    /// Build a DTS-HD extension substream of `size` bytes with a valid sync +
+    /// size header (matching `dts_hd_ext_frame_size`).
+    fn make_dts_ext(size: usize) -> Vec<u8> {
+        let raw = size - 1;
+        let mut e = vec![0u8; size];
+        e[0..4].copy_from_slice(&DTS_HD_EXT_SYNC);
+        e[6] = ((raw >> 11) & 0x1F) as u8;
+        e[7] = ((raw >> 3) & 0xFF) as u8;
+        e[8] = (((raw & 0x07) << 5) as u8) | (e[8] & 0x1F);
+        e
+    }
+
+    #[test]
+    fn keeps_dts_hd_extension_across_pes_boundary() {
+        // DTS-HD MA access unit = core + extension substream. When the
+        // extension straddles a PES boundary, the parser must WAIT and emit the
+        // full unit — not a core-only frame (which would drop the lossless
+        // data, the Dunkirk lossy-core bug).
+        let mut parser = DtsParser::new();
+        let core = make_dts_core(512);
+        let ext = make_dts_ext(256);
+        let mut au = core;
+        au.extend_from_slice(&ext); // 768-byte access unit
+
+        // Split mid-extension: first PES carries the core + 100 ext bytes.
+        let split = 512 + 100;
+        let f1 = parser.parse(&make_pes(au[..split].to_vec(), Some(90000)));
+        assert!(
+            f1.is_empty(),
+            "must wait for the full extension, not emit a core-only frame"
+        );
+
+        let f2 = parser.parse(&make_pes(au[split..].to_vec(), Some(90000)));
+        assert_eq!(f2.len(), 1);
+        assert_eq!(
+            f2[0].data.len(),
+            768,
+            "frame must include core + extension (lossless preserved)"
+        );
+    }
+
    #[test]
    fn codec_private_none() {
        let parser = DtsParser::new();
@@ -153,6 +153,52 @@ impl CodecParser for TrueHdParser {
    }
 }

+/// Per-bit channel counts for the TrueHD 8-channel and 6-channel presentation
+/// channel-assignment masks (per the MLP spec / FFmpeg `thd_channels`). Some
+/// bits denote a stereo pair (2), others a single channel (1).
+const THD_8CH: [u8; 13] = [2, 1, 1, 2, 2, 2, 2, 1, 1, 2, 2, 1, 1];
+const THD_6CH: [u8; 5] = [2, 1, 1, 2, 1];
+
+/// Decode the true channel count from a TrueHD major-sync `format_info` word
+/// (the 32 bits immediately after the 0xF8726FBA sync). Returns the richest
+/// presentation's channel count — the 8-channel (e.g. 7.1) presentation when
+/// present, else the 6-channel (5.1) one. This is the real layout that the MPLS
+/// `audio_format` base field (often 5.1 even on a 7.1/Atmos track) understates.
+pub fn truehd_channels(format_info: u32) -> Option<u8> {
+    let ch8 = (format_info & 0x1FFF) as u16; // 8ch_presentation_channel_assignment (13 bits)
+    let ch6 = ((format_info >> 15) & 0x1F) as u16; // 6ch_presentation_channel_assignment (5 bits)
+    let count = |mask: u16, tbl: &[u8]| -> u8 {
+        tbl.iter()
+            .enumerate()
+            .filter(|(i, _)| mask & (1 << i) != 0)
+            .map(|(_, &c)| c)
+            .sum()
+    };
+    if ch8 != 0 {
+        Some(count(ch8, &THD_8CH))
+    } else if ch6 != 0 {
+        Some(count(ch6, &THD_6CH))
+    } else {
+        None
+    }
+}
+
+/// Scan a demuxed TrueHD elementary-stream chunk for the first major sync and
+/// decode its true channel count. The stream may interleave AC-3; we scan for
+/// the major-sync word anywhere and read the following `format_info`.
+pub fn truehd_channels_from_stream(data: &[u8]) -> Option<u8> {
+    let mut p = 0;
+    while p + 8 <= data.len() {
+        let w = u32::from_be_bytes([data[p], data[p + 1], data[p + 2], data[p + 3]]);
+        if (w & 0xFFFF_FFFE) == 0xF872_6FBA {
+            let fi = u32::from_be_bytes([data[p + 4], data[p + 5], data[p + 6], data[p + 7]]);
+            return truehd_channels(fi);
+        }
+        p += 1;
+    }
+    None
+}
+
 #[cfg(test)]
 mod tests {
    use super::*;
@@ -247,4 +293,27 @@ mod tests {
        let parser = TrueHdParser::new();
        assert!(parser.codec_private().is_none());
    }
+
+    #[test]
+    fn truehd_channels_71_from_8ch_presentation() {
+        // 8ch presentation assignment bits 0-4 (LR,C,LFE,LsRs,back-LR) = 2+1+1+2+2 = 8.
+        let format_info = 0x1F; // low 13 bits = 0x1F
+        assert_eq!(truehd_channels(format_info), Some(8));
+    }
+
+    #[test]
+    fn truehd_channels_51_from_6ch_presentation() {
+        // No 8ch presentation; 6ch bits 0-3 (LR,C,LFE,LsRs) = 2+1+1+2 = 6.
+        let format_info = 0xF << 15; // 6ch field = 0xF, 8ch field = 0
+        assert_eq!(truehd_channels(format_info), Some(6));
+    }
+
+    #[test]
+    fn truehd_channels_scan_finds_major_sync() {
+        // [junk][major sync 0xF8726FBA][format_info: 8ch=0x1F -> 7.1]
+        let mut data = vec![0xAA, 0xBB];
+        data.extend_from_slice(&0xF872_6FBAu32.to_be_bytes());
+        data.extend_from_slice(&0x0000_001Fu32.to_be_bytes());
+        assert_eq!(truehd_channels_from_stream(&data), Some(8));
+    }
 }
@@ -362,6 +362,12 @@ pub const MATRIX_COEFFICIENTS: u32 = 0x55B1;
 pub const PRIMARIES: u32 = 0x55BB;
 pub const RANGE: u32 = 0x55B9;

+// Dolby Vision — BlockAdditionMapping carries the DOVIDecoderConfigurationRecord
+// (dvcC) so players / mediainfo recognise the track as Dolby Vision.
+pub const BLOCK_ADDITION_MAPPING: u32 = 0x41E4;
+pub const BLOCK_ADD_ID_TYPE: u32 = 0x41E7;
+pub const BLOCK_ADD_ID_EXTRA_DATA: u32 = 0x41ED;
+
 // Audio
 pub const AUDIO: u32 = 0xE1;
 pub const SAMPLING_FREQUENCY: u32 = 0xB5;
@@ -34,6 +34,24 @@ pub struct MkvTrack {
    pub sample_rate: f64,
    pub channels: u8,
    pub bit_depth: u8,
+    // Dolby Vision: the dvcC (DOVIDecoderConfigurationRecord) for the DV layer,
+    // emitted as a BlockAdditionMapping. `None` for non-DV tracks.
+    pub dv_config: Option<Vec<u8>>,
+}
+
+/// Build a DOVIDecoderConfigurationRecord (dvcC) — 24 bytes — for the Matroska
+/// BlockAdditionMapping. For disc Profile 7 dual-layer the base, enhancement,
+/// and RPU are all present (lossless FEL/MEL preserved as a second track).
+pub fn dolby_vision_config(profile: u8, level: u8, bl_compat_id: u8) -> Vec<u8> {
+    let mut v = vec![0u8; 24];
+    v[0] = 1; // dv_version_major
+    v[1] = 0; // dv_version_minor
+    // profile(7) | level(6) | rpu_present(1) | el_present(1) | bl_present(1)
+    v[2] = ((profile & 0x7F) << 1) | ((level >> 5) & 0x01);
+    v[3] = ((level & 0x1F) << 3) | (1 << 2) | (1 << 1) | 1; // rpu = el = bl = 1
+    v[4] = (bl_compat_id & 0x0F) << 4;
+    // v[5..24] reserved = 0
+    v
 }

 impl MkvTrack {
@@ -83,6 +101,13 @@ impl MkvTrack {
            sample_rate: 0.0,
            channels: 0,
            bit_depth: 0,
+            // The DV layer (hdr=DolbyVision) carries the dvcC so the track is
+            // recognised as Dolby Vision (disc Profile 7 dual-layer).
+            dv_config: if matches!(v.hdr, HdrFormat::DolbyVision) {
+                Some(dolby_vision_config(7, 6, 0))
+            } else {
+                None
+            },
        }
    }

@@ -128,6 +153,7 @@ impl MkvTrack {
            sample_rate: sr,
            channels: ch,
            bit_depth: 0,
+            dv_config: None,
        }
    }

@@ -156,6 +182,7 @@ impl MkvTrack {
            sample_rate: 0.0,
            channels: 0,
            bit_depth: 0,
+            dv_config: None,
        }
    }
 }
@@ -333,6 +360,17 @@ impl<W: Write + Seek> MkvMuxer<W> {
                ebml::end_master(&mut writer, vid_pos)?;
            }

+            // Dolby Vision signaling — BlockAdditionMapping is a child of the
+            // TrackEntry (sibling of Video). Carries the dvcC so players /
+            // mediainfo recognise the track as Dolby Vision.
+            if let Some(ref dvcc) = track.dv_config {
+                let map_pos = ebml::start_master(&mut writer, ebml::BLOCK_ADDITION_MAPPING)?;
+                // BlockAddIDType = "dvcC" fourcc (DOVIDecoderConfigurationRecord).
+                ebml::write_uint(&mut writer, ebml::BLOCK_ADD_ID_TYPE, 0x6476_6343)?;
+                ebml::write_binary(&mut writer, ebml::BLOCK_ADD_ID_EXTRA_DATA, dvcc)?;
+                ebml::end_master(&mut writer, map_pos)?;
+            }
+
            // Audio-specific
            if track.track_type == ebml::TRACK_TYPE_AUDIO && track.sample_rate > 0.0 {
                let aud_pos = ebml::start_master(&mut writer, ebml::AUDIO)?;
@@ -612,6 +650,7 @@ mod tests {
            sample_rate: 0.0,
            channels: 0,
            bit_depth: 0,
+            dv_config: None,
        }
    }

@@ -636,9 +675,24 @@ mod tests {
            sample_rate: 48000.0,
            channels: 6,
            bit_depth: 0,
+            dv_config: None,
        }
    }

+    #[test]
+    fn dolby_vision_config_profile7() {
+        // dvcC for disc Profile 7 dual-layer: version 1.0, profile 7, all of
+        // bl/el/rpu present. 24 bytes.
+        let c = dolby_vision_config(7, 6, 0);
+        assert_eq!(c.len(), 24);
+        assert_eq!(c[0], 1); // dv_version_major
+        assert_eq!(c[1], 0); // dv_version_minor
+        // profile in the top 7 bits of byte 2
+        assert_eq!(c[2] >> 1, 7, "dv_profile must be 7");
+        // rpu/el/bl present flags in byte 3 (low 3 bits after level)
+        assert_eq!(c[3] & 0b0000_0111, 0b0000_0111, "rpu+el+bl all present");
+    }
+
    #[test]
    fn mkv_writes_ebml_header() {
        let buf = Cursor::new(Vec::new());
@@ -6,7 +6,7 @@
 //! ```text
 //! let mut input = input("iso://Disc.iso", &opts)?;
 //! let title = input.info().clone();
-//! let mut output = output("mkv://Dune.mkv", &title)?;
+//! let mut output = output("mkv://Movie.mkv", &title)?;
 //! while let Ok(Some(frame)) = input.read() {
 //!     output.write(&frame)?;
 //! }
@@ -162,7 +162,11 @@ fn validate_network_addr(addr: &str) -> io::Result<()> {
 /// Options for opening an input stream.
 #[derive(Default)]
 pub struct InputOptions {
-    pub keydb_path: Option<String>,
+    /// Caller-resolved per-CPS-unit AACS keys to apply to the scanned disc
+    /// (`(cps_unit, 16-byte key)`). Empty for an unencrypted disc or when the
+    /// caller has no key. The library does no lookup — a key source resolves
+    /// these and the caller passes them here.
+    pub unit_keys: Vec<(u32, [u8; 16])>,
    pub title_index: Option<usize>,
    /// Skip decryption — return raw encrypted bytes.
    pub raw: bool,
@@ -181,12 +185,6 @@ pub fn input(url: &str, opts: &InputOptions) -> io::Result<Box<dyn crate::pes::S
        }
        StreamUrl::Iso { ref path } => {
            validate_file_path(path, "iso")?;
-            let scan_opts = match &opts.keydb_path {
-                Some(p) => crate::disc::ScanOptions {
-                    keydb_path: Some(p.into()),
-                },
-                None => crate::disc::ScanOptions::default(),
-            };
            // FileSectorSource is the sole file-backed sector source.
            // It carries the platform-tuned SEQUENTIAL fadvise hint
            // (so the kernel readahead window widens) and the periodic
@@ -194,8 +192,19 @@ pub fn input(url: &str, opts: &InputOptions) -> io::Result<Box<dyn crate::pes::S
            // when the mux output is being written to the same disk.
            let mut reader = crate::io::file_sector_source::FileSectorSource::open(path)?;
            let capacity = reader.capacity_sectors();
-            let disc = crate::disc::Disc::scan_image(&mut reader, capacity, &scan_opts)
-                .map_err(|e| -> io::Error { e.into() })?;
+            let mut disc = crate::disc::Disc::scan_image(
+                &mut reader,
+                capacity,
+                &crate::disc::ScanOptions::default(),
+            )
+            .map_err(|e| -> io::Error { e.into() })?;
+            // Apply the caller-resolved keys (lookup-free); decrypt_keys() then
+            // yields them for the stream below. Propagate a failed application
+            // rather than silently muxing an undecryptable stream.
+            if !opts.unit_keys.is_empty() {
+                disc.decrypt_with(crate::disc::Key::Unit(opts.unit_keys.clone()))
+                    .map_err(|e| -> io::Error { e.into() })?;
+            }
            if disc.titles.is_empty() {
                return Err(crate::error::Error::NoStreams.into());
            }
@@ -207,8 +216,15 @@ pub fn input(url: &str, opts: &InputOptions) -> io::Result<Box<dyn crate::pes::S
                }
                .into());
            }
-            let title = disc.titles[idx].clone();
+            // Correct TrueHD channel counts (MPLS understates 7.1/Atmos as 5.1)
+            // by probing the first DECRYPTED access units of the chosen title.
+            // A fresh reader avoids disturbing the mux reader below.
            let keys = disc.decrypt_keys();
+            if let Ok(probe) = crate::io::file_sector_source::FileSectorSource::open(path) {
+                let mut dec = crate::sector::DecryptingSectorSource::new(probe, keys.clone());
+                crate::disc::correct_truehd_channels(&mut dec, &mut disc.titles[idx]);
+            }
+            let title = disc.titles[idx].clone();
            let format = disc.content_format;
            // ISO file: 16 MiB batch — sequential read from fast
            // storage, no bad sectors. Measured optimum on the rip1
@@ -89,8 +89,8 @@ fn aacs_decrypt_unit_roundtrip() {
        plain[offset] = 0x47; // TS sync byte
        offset += 192;
    }
-    // Set encryption flag (bits 6-7 of byte 0)
-    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.

    // Save original plaintext for comparison
    let expected = plain.clone();
@@ -126,8 +126,8 @@ fn aacs_decrypt_unit_roundtrip() {
        prev.copy_from_slice(&plain[off..off + 16]);
    }

-    // Verify it looks encrypted
-    assert!(aacs::is_unit_encrypted(&plain));
+    // Verify it looks encrypted (body TS syncs scrambled)
+    assert!(aacs::is_aacs_scrambled(&plain));

    // Now decrypt
    let result = aacs::decrypt_unit(&mut plain, &unit_key);
@@ -136,8 +136,8 @@ fn aacs_decrypt_unit_roundtrip() {
        "decrypt_unit should return true on valid encrypted unit"
    );
    assert!(
-        !aacs::is_unit_encrypted(&plain),
-        "encryption flag should be cleared"
+        !aacs::is_aacs_scrambled(&plain),
+        "decrypted unit should read as clear (TS syncs restored)"
    );

    // Verify TS sync bytes at expected positions (flag byte is cleared by decrypt)
@@ -156,17 +156,11 @@ fn aacs_decrypt_unit_roundtrip() {
        sync_count, expected_syncs
    );

-    // Compare all bytes except byte 0 (encryption flag cleared)
+    // Decryption clears no flag, so the unit round-trips byte-for-byte.
    assert_eq!(
-        &plain[1..aacs::ALIGNED_UNIT_LEN],
-        &expected[1..aacs::ALIGNED_UNIT_LEN],
-        "decrypted unit body does not match original"
-    );
-    // Byte 0: original had 0xC0 set, decrypted has it cleared
-    assert_eq!(
-        plain[0] & !0xC0,
-        expected[0] & !0xC0,
-        "byte 0 mismatch ignoring flag"
+        &plain[..],
+        &expected[..],
+        "decrypted unit does not match original plaintext"
    );
 }

@@ -260,49 +254,65 @@ fn aacs_vuk_derivation_roundtrip() {
    assert_eq!(vuk, vuk2, "derive_vuk not deterministic");
 }

-/// Test: aacs_is_unit_encrypted detects encryption flags correctly.
+/// Test: aacs_is_aacs_scrambled detects scrambled units via the raw TS syncs.
 #[test]
-fn aacs_is_unit_encrypted_detection() {
-    let mut unit = vec![0u8; aacs::ALIGNED_UNIT_LEN];
-
+fn aacs_is_aacs_scrambled_detection() {
+    // A clear unit: TS sync (0x47) intact at every 192-byte packet → not
+    // scrambled. (Flag bits play no role.)
+    let mut clear = vec![0u8; aacs::ALIGNED_UNIT_LEN];
+    let mut off = 4;
+    while off < aacs::ALIGNED_UNIT_LEN {
+        clear[off] = 0x47;
+        off += 192;
+    }
    assert!(
-        !aacs::is_unit_encrypted(&unit),
-        "zero unit should not be encrypted"
+        !aacs::is_aacs_scrambled(&clear),
+        "clear unit (syncs intact) must not be scrambled"
    );

-    unit[0] = 0x40; // bit 6 set
-    assert!(aacs::is_unit_encrypted(&unit));
+    // Flag bits do NOT make a synced unit look scrambled.
+    let mut flagged = clear.clone();
+    flagged[0] = 0xC0; // copy-control bits
+    flagged[7] = 0xC0; // TSC bits
+    assert!(
+        !aacs::is_aacs_scrambled(&flagged),
+        "flag bits must not be read as encryption"
+    );

-    unit[0] = 0x80; // bit 7 set
-    assert!(aacs::is_unit_encrypted(&unit));
-
-    unit[0] = 0xC0; // both bits set
-    assert!(aacs::is_unit_encrypted(&unit));
-
-    unit[0] = 0x3F; // bits 6-7 clear
-    assert!(!aacs::is_unit_encrypted(&unit));
+    // A scrambled body (syncs destroyed) → scrambled.
+    let scrambled = vec![0x99u8; aacs::ALIGNED_UNIT_LEN];
+    assert!(
+        aacs::is_aacs_scrambled(&scrambled),
+        "unit with no intact TS syncs must read as scrambled"
+    );

    // Too short
-    let short = vec![0xC0u8; 100];
+    let short = vec![0xFFu8; 100];
    assert!(
-        !aacs::is_unit_encrypted(&short),
+        !aacs::is_aacs_scrambled(&short),
        "short buffer should not be detected"
    );
 }

 /// Test: aacs_decrypt_unit_unencrypted_passthrough
 ///
-/// A unit without encryption flags should pass through decrypt_unit unchanged.
+/// A clear unit (TS syncs intact) should pass through decrypt_unit unchanged.
 #[test]
 fn aacs_decrypt_unit_unencrypted_passthrough() {
    let mut unit = vec![0x42u8; aacs::ALIGNED_UNIT_LEN];
-    unit[0] = 0x00; // no encryption flag
+    // Intact TS syncs every 192 bytes → not scrambled → passthrough.
+    let mut off = 4;
+    while off < aacs::ALIGNED_UNIT_LEN {
+        unit[off] = 0x47;
+        off += 192;
+    }
    let original = unit.clone();
    let key = [0xAA; 16];

+    assert!(!aacs::is_aacs_scrambled(&unit));
    let result = aacs::decrypt_unit(&mut unit, &key);
-    assert!(result, "unencrypted unit should return true");
-    assert_eq!(unit, original, "unencrypted unit should be unchanged");
+    assert!(result, "clear unit should return true");
+    assert_eq!(unit, original, "clear unit should be unchanged");
 }

 // ── AACS cross-validation with independent AES implementation ──────────────
@@ -369,8 +379,7 @@ fn aacs_cross_validation_encrypt_then_decrypt() {
            plaintext[i] = (i % 251) as u8;
        }
    }
-    // Set encryption flag
-    plaintext[0] = 0xC0;
+    // No flag set: the CBC-encrypted body scrambles the packet syncs.

    let expected = plaintext.clone();

@@ -401,14 +410,11 @@ fn aacs_cross_validation_encrypt_then_decrypt() {
        ok,
        "decrypt_unit returned false (TS sync verification failed)"
    );
-    assert_eq!(plaintext[0] & 0xC0, 0x00, "encryption flag not cleared");

-    // Compare (byte 0 flag was cleared)
-    let mut expected_cleared = expected.clone();
-    expected_cleared[0] &= !0xC0;
+    // Decryption clears no flag, so the unit round-trips byte-for-byte.
    assert_eq!(
-        &plaintext[1..aacs::ALIGNED_UNIT_LEN],
-        &expected_cleared[1..aacs::ALIGNED_UNIT_LEN],
+        &plaintext[..],
+        &expected[..],
        "decrypted unit does not match original plaintext"
    );
 }
@@ -428,7 +434,7 @@ fn aacs_cross_validation_alternate_key() {
        plaintext[off] = 0x47;
        off += 192;
    }
-    plaintext[0] = 0xC0;
+    // No flag set: the CBC-encrypted body scrambles the packet syncs.
    let expected = plaintext.clone();

    let mut header = [0u8; 16];
@@ -446,12 +452,8 @@ fn aacs_cross_validation_alternate_key() {

    assert!(aacs::decrypt_unit(&mut plaintext, &unit_key));

-    let mut expected_cleared = expected;
-    expected_cleared[0] &= !0xC0;
-    assert_eq!(
-        &plaintext[1..aacs::ALIGNED_UNIT_LEN],
-        &expected_cleared[1..aacs::ALIGNED_UNIT_LEN],
-    );
+    // Decryption clears no flag, so the unit round-trips byte-for-byte.
+    assert_eq!(&plaintext[..], &expected[..]);
 }

 /// Verify that `decrypt_bus` correctly reverses AES-CBC encryption applied
@@ -126,29 +126,19 @@ fn disc_title_total_sectors() {
 // ── ScanOptions tests ──────────────────────────────────────────────────────

 #[test]
-fn scan_options_default() {
+fn scan_options_default_has_no_credentials() {
+    // Lookup-free: the only scan input is the optional live-drive credentials.
    let opts = ScanOptions::default();
-    assert!(opts.keydb_path.is_none());
+    assert!(opts.credentials.is_none());
 }

 #[test]
-fn scan_options_with_keydb() {
+fn scan_options_with_credentials() {
    let opts = ScanOptions {
-        keydb_path: Some(("/tmp/KEYDB.cfg").into()),
+        credentials: Some(libfreemkv::DriveCredentials::default()),
    };
-    assert_eq!(
-        opts.keydb_path.as_ref().unwrap().to_str().unwrap(),
-        "/tmp/KEYDB.cfg"
-    );
-}
-
-#[test]
-fn scan_options_with_keydb_pathbuf() {
-    let path = std::path::PathBuf::from("/home/user/.config/aacs/KEYDB.cfg");
-    let opts = ScanOptions {
-        keydb_path: Some(path.clone()),
-    };
-    assert_eq!(opts.keydb_path.unwrap(), path);
+    assert!(opts.credentials.is_some());
+    assert!(opts.credentials.unwrap().host_certs.is_empty());
 }

 // ── detect_format integration tests ───────────────────────────────────────
@@ -509,20 +499,16 @@ fn batch_count_max_batch_sizes() {
 }

 #[test]
-fn resolve_encryption_no_keydb() {
-    // A UDF image with /AACS directory but no keydb path -> aacs is None
+fn scan_encrypted_resolves_no_keys() {
+    // A UDF image with an /AACS directory: the lookup-free scan detects
+    // encryption and captures inputs, but resolves NO key on its own — a
+    // caller applies one later via Disc::decrypt_with.
    let mut reader = MockSectorReader::new();
    build_udf_with_aacs_dir(&mut reader);

-    // No keydb configured and no standard keydb on the system
-    let opts = ScanOptions {
-        keydb_path: Some(("/nonexistent/path/KEYDB.cfg").into()),
-    };
-    let disc = Disc::scan_image(&mut reader, 1000, &opts).unwrap();
+    let disc = Disc::scan_image(&mut reader, 1000, &ScanOptions::default()).unwrap();

-    // The disc detects encryption but can't resolve keys without a keydb
-    assert!(
-        disc.aacs.is_none(),
-        "aacs should be None when keydb is unavailable"
-    );
+    // No unit keys without an external key (the mock has no Unit_Key_RO.inf to
+    // capture, so the keyless state isn't even built) — either way, no keys.
+    assert!(matches!(disc.decrypt_keys(), libfreemkv::DecryptKeys::None));
 }
@@ -82,22 +82,24 @@ fn decrypt_sectors_with_css_keys_works() {
 /// Test: AACS unit encryption detection works.
 #[test]
 fn aacs_encryption_flag_detection() {
+    // A clear unit: TS syncs (0x47) intact at every 192-byte packet.
    let mut unit = vec![0u8; aacs::ALIGNED_UNIT_LEN];
+    let mut off = 4;
+    while off < aacs::ALIGNED_UNIT_LEN {
+        unit[off] = 0x47;
+        off += 192;
+    }
+    // Encryption is the scrambled body (TS syncs destroyed), NOT a flag bit.
+    assert!(!aacs::is_aacs_scrambled(&unit));

-    // No encryption flag
-    assert!(!aacs::is_unit_encrypted(&unit));
-
-    // Set bit 6
-    unit[0] |= 0x40;
-    assert!(aacs::is_unit_encrypted(&unit));
-
-    // Set bit 7
-    unit[0] = 0x80;
-    assert!(aacs::is_unit_encrypted(&unit));
-
-    // Both bits set
+    // Flag bits on a synced unit do not make it look encrypted.
    unit[0] = 0xC0;
-    assert!(aacs::is_unit_encrypted(&unit));
+    unit[7] = 0xC0;
+    assert!(!aacs::is_aacs_scrambled(&unit));
+
+    // Scrambled body (syncs gone) → encrypted.
+    let scrambled = vec![0x99u8; aacs::ALIGNED_UNIT_LEN];
+    assert!(aacs::is_aacs_scrambled(&scrambled));
 }

 /// Test: DecryptKeys::is_encrypted() correctly identifies encrypted state.
@@ -9,9 +9,7 @@
 //! [`ScsiSense::is_*`].
 //!
 //! The actual `ioctl(SG_IO, ...)` call is impossible to mock without a
-//! kernel — see
-//! `(internal)/docs/audits/2026-04-26-scsi-architecture-research.md`
-//! for why the audit recommends against libc shims here. These tests
+//! kernel, so libc shims are deliberately avoided here. These tests
 //! therefore pin the *contract* every backend must satisfy via a mock
 //! `ScsiTransport`:
 //!
@@ -77,21 +77,21 @@ fn parse_url_disc_device() {

 #[test]
 fn parse_url_mkv() {
-    let u = parse_url("mkv://Dune.mkv");
+    let u = parse_url("mkv://Movie.mkv");
    assert_eq!(u.scheme(), "mkv");
-    assert_eq!(u.path_str(), "Dune.mkv");
+    assert_eq!(u.path_str(), "Movie.mkv");
 }

 #[test]
 fn parse_url_network() {
-    let u = parse_url("network://10.0.0.1:9000");
+    let u = parse_url("network://192.0.2.10:9000");
    assert_eq!(u.scheme(), "network");
-    assert_eq!(u.path_str(), "10.0.0.1:9000");
+    assert_eq!(u.path_str(), "192.0.2.10:9000");
 }

 #[test]
 fn parse_url_bare_path_rejected() {
-    let u = parse_url("Dune.mkv");
+    let u = parse_url("Movie.mkv");
    assert_eq!(u.scheme(), "unknown");
 }

@@ -104,21 +104,21 @@ fn parse_url_null() {

 #[test]
 fn parse_url_m2ts_with_path() {
-    let u = parse_url("m2ts:///tmp/Dune.m2ts");
+    let u = parse_url("m2ts:///tmp/Movie.m2ts");
    assert_eq!(u.scheme(), "m2ts");
-    assert_eq!(u.path_str(), "/tmp/Dune.m2ts");
+    assert_eq!(u.path_str(), "/tmp/Movie.m2ts");
 }

 #[test]
 fn parse_url_m2ts_relative() {
-    let u = parse_url("m2ts://Dune.m2ts");
+    let u = parse_url("m2ts://Movie.m2ts");
    assert_eq!(u.scheme(), "m2ts");
-    assert_eq!(u.path_str(), "Dune.m2ts");
+    assert_eq!(u.path_str(), "Movie.m2ts");
 }

 #[test]
 fn open_input_bare_path_errors() {
-    let result = libfreemkv::input("Dune.mkv", &libfreemkv::InputOptions::default());
+    let result = libfreemkv::input("Movie.mkv", &libfreemkv::InputOptions::default());
    assert!(result.is_err());
    let msg = match result {
        Err(e) => e.to_string(),
@@ -134,7 +134,7 @@ fn open_input_bare_path_errors() {
 #[test]
 fn open_output_bare_path_errors() {
    let dt = sample_disc_title();
-    let result = libfreemkv::output("Dune.mkv", &dt);
+    let result = libfreemkv::output("Movie.mkv", &dt);
    assert!(result.is_err());
    let msg = match result {
        Err(e) => e.to_string(),
@@ -195,7 +195,7 @@ fn open_output_disc_errors() {

 #[test]
 fn open_input_network_no_port_errors() {
-    let result = libfreemkv::input("network://10.0.0.1", &libfreemkv::InputOptions::default());
+    let result = libfreemkv::input("network://192.0.2.1", &libfreemkv::InputOptions::default());
    assert!(result.is_err());
    let msg = match result {
        Err(e) => e.to_string(),
Author	SHA1	Message	Date
MattJackson	e04d79c593	v0.28.1: bump version	2026-06-04 21:46:41 -07:00
MattJackson	b34af1fa74	mux: wire TrueHD channel probe into iso:// mux setup correct_truehd_channels() probes the first DECRYPTED access units of the chosen title (TrueHD PIDs, bounded 8 MiB read of the first extent) and sets AudioStream.channels from the MLP major sync — fixing the MPLS audio_format understatement (5.1 declared on a 7.1/Atmos TrueHD track). Regenerates the basic codec label for the corrected count; richer editorial labels are left untouched. Wired in resolve.rs input() for iso:// after decrypt_with (the m2ts is only decryptable post-key), using a fresh reader so the mux reader is undisturbed. generate_audio_label made pub(crate).	2026-06-04 20:28:37 -07:00
MattJackson	a7317f8885	mux/truehd: decode true channel count from MLP major-sync format_info Adds truehd_channels(format_info) + truehd_channels_from_stream(): the real presentation channel count (8ch/7.1 when present, else 6ch/5.1) from the TrueHD major sync, which the MPLS audio_format base field understates (declares 5.1 even on a 7.1/Atmos track — the Dune case). Per the MLP spec presentation channel-assignment masks. 3 unit tests. This is the decoder; wiring it to correct AudioStream.channels requires a mux-time probe of the DECRYPTED audio payload (the channel truth isn't readable at scan — the m2ts is AACS-encrypted until the key is applied at mux), to be added + validated on a real rip.	2026-06-04 19:51:46 -07:00
MattJackson	474273afc0	mux/mkv: signal Dolby Vision via dvcC BlockAdditionMapping With the EL now carried (mpls PID fix), the MKV writer tags the Dolby Vision layer so players/mediainfo recognise it: a BlockAdditionMapping (0x41E4) with BlockAddIDType 'dvcC' and a DOVIDecoderConfigurationRecord (profile 7, bl+el+rpu present) on the DV-layer video track. Disc Profile 7 dual-layer is preserved losslessly as a second video track (archival-correct, MakeMKV-equivalent); M2TS carries the EL as a native second video PID with no extra signaling needed. Adds dolby_vision_config() + a profile-7 dvcC unit test. End-to-end DV recognition (mediainfo / playback) to be confirmed on a full rip.	2026-06-04 19:42:14 -07:00
MattJackson	0a2bab5789	mpls: resolve PID for sub-path / DV-EL stream entries (types 2/3/4) parse_stream_entry only read the PID for stream-entry type 1 (a stream in the PlayItem's own clip), returning PID 0 for every other type. The Dolby Vision enhancement layer uses type 4 (verified on Wicked + Dune: se_len=9 type=0x04 [00 10 15] -> PID 0x1015), so the EL fell through to PID 0x0000 and was silently dropped by the demux/mux — Dolby Vision lost. Now the PID offset is keyed off the entry type per the BD stream_entry() layout: type 1 -> +2, type 2 -> +4, type 3/4 -> +3. The DV EL now resolves to its real PID (0x1015) so it is demuxed and carried as a stream through the PES layer to every writer (M2TS carries dual-PID DV natively; the MKV writer's DV signaling is the format-specific piece).	2026-06-04 19:28:34 -07:00
MattJackson	fa4d7ef871	mux/dts: keep DTS-HD extension substream across PES boundaries The DTS parser emitted a core-only frame and discarded the trailing DTS-HD extension substream whenever the extension straddled a PES boundary (it advanced past only the core, then re-synced on the core syncword, skipping the leftover extension bytes). That silently downgrades DTS-HD MA / HRA to lossy DTS core. Now: when an extension sync is visible after the core — full, or a partial prefix at the buffer edge — wait for the full extension instead of splitting it off; only 'nothing after the core' (final unit / EOF, no parser flush) is taken as a genuine lossy core-only unit. Adds a boundary-split regression test asserting core+extension is preserved.	2026-06-04 19:16:26 -07:00
MattJackson	36d1af1b7f	labels+disc: codec from stream, audio-richness title tiebreak Two validated audio-correctness fixes (proven on real discs Wicked/ Paddington/Dune/Fight Club via head-captures): labels: apply_labels now derives the codec/channel descriptor from the stream's OWN codec/channels unless the parser's codec_hint is BOTH consistent with it AND richer (e.g. "Dolby Atmos" on a TrueHD stream). A mis-bound hint ("AC-3 2.0" on a TrueHD track) is rejected and the stream's own codec used — killing the cross-labeled shuffle (Wicked) and the compat-core mislabel (Paddington), while keeping rich hints and normalizing plain ones to uniform marketing names. (codec_hint_consistent + codec_hint_adds_detail, 5 tests.) disc: canonical_title_order gains an audio-richness tiebreak (lossless > channels > track-count) for titles that tie on duration+clips — so a movie authored as a full-audio playlist plus a stereo-only twin (Fight Club 00800 vs 00004) picks the full-audio one instead of falling to array order.	2026-06-04 19:10:11 -07:00
MattJackson	b96f6206fe	0.28.0: version bump (keydb decoupling)	2026-06-04 16:41:04 -07:00
MattJackson	bb32fb993b	0.28.0 review fixes: propagate mux key-apply error; scrub key-shaped fixtures - 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.	2026-06-04 16:38:58 -07:00
MattJackson	c1eb74dfa5	AACS: cutover — lookup-free lib; DriveCredentials for the handshake The library no longer loads a keydb anywhere. The scan path always captures the disc's AACS inputs (MKB, VID, Unit_Key_RO.inf) and resolves NO key; a caller resolves a Key from a key source and applies it via Disc::decrypt_with. - ScanOptions loses keydb_path / unit_key / disable_keydb (and the path search); it now carries only optional DriveCredentials (host certs) for the live-drive AACS handshake. do_handshake_cert uses those instead of loading the keydb. An unlocked / LibreDrive drive takes the OEM Volume-ID path and needs none. - The mux input() path takes caller-resolved unit_keys instead of a keydb_path, and applies them via decrypt_with. - Deleted the now-dead inline resolve_encryption / resolve_encryption_static. All 700+ lib tests pass.	2026-06-04 16:04:06 -07:00
MattJackson	46838c63ca	AACS: trim the MKB captured at keyless scan to its record length The VID-only scan path stashed MKB_RO/RW raw — those files are allocated to a fixed ~128 MiB and zero-padded, so the MKB on AacsState (consumed by Disc::inputs() and the device/processing-key decrypt_with derivation) was the full pad, not the ~few-MB record stream. Trim to mkb_content_len, matching read_aacs_inputs.	2026-06-04 15:32:12 -07:00
MattJackson	1e60220ff6	AACS: KeySource::needs_samples() gates the content-sample read A source that validates server-side against ciphertext (an online key service) needs encrypted content samples; one that keys on disc identity (keydb, mapfile) does not. needs_samples() lets the caller skip the extra disc read unless a configured source actually needs it. Defaults false.	2026-06-04 14:45:40 -07:00
MattJackson	080f03e8ed	AACS: DiscInputs gains app-populated samples for ciphertext-validating sources An online key service validates a candidate against real ciphertext, so it needs a few encrypted content sample units. Add a samples field to DiscInputs; Disc::inputs() leaves it empty (reading content needs the disc reader, which scan does not retain) for the application to fill.	2026-06-04 14:42:11 -07:00
MattJackson	35de6101d4	AACS: add KeySource trait + DiscInputs; Media key carries a candidate pool The library now describes the key-source abstraction it consumes, while the concrete sources live in a companion crate. A KeySource looks a disc up from its DiscInputs (disc hash, volume id, MKB, Unit_Key_RO.inf) and returns a Key; the library derives down and decrypts. Sources do no derivation. Disc::inputs() exposes those inputs from a scanned disc. Key::Media now carries a Vec of candidate media keys rather than one: a media key is MKB-scoped, so a source hands its whole pool and the library picks the one that verifies against the disc's MKB. That mirrors Device/Processing and keeps key selection (a derivation step) inside the library.	2026-06-04 14:29:32 -07:00
MattJackson	9012101573	AACS: decrypt_with accepts higher-level keys and derives down Disc::decrypt_with now takes Device / Processing / Media / Volume keys in addition to Unit. A caller hands in whatever level it resolved and the library derives down the AACS chain to the per-CPS-unit keys, then decrypts: Device -> MKB walk -> media key -> VUK -> per-CPS unit keys Processing -> MKB -> media key -> VUK -> per-CPS unit keys Media -> Volume ID -> VUK -> per-CPS unit keys Volume -> Unit_Key_RO.inf, one unit key per CPS unit Unit -> used directly (terminal) Derivation stays centralized in the version-dispatched resolver (1.0 / 2.0 / 2.1), fed by a single-key provider built from the supplied key — no new crypto. Volume notably does NOT stop at the volume key: it decrypts every CPS unit's key. Scan stashes the AACS inputs (Unit_Key_RO.inf and MKB) on AacsState so an out-of-band decrypt_with can derive without re-reading the disc. Non-breaking: Key is #[non_exhaustive] and the existing Unit path is unchanged. New tests cover the Volume -> per-CPS derive-down, the missing-inputs error, and the no-units rejection.	2026-06-04 14:20:16 -07:00
MattJackson	8bc1de6c9b	0.27.5 (step 2, Phase 1): expose AACS inputs (uk_ro, mkb) on AacsState scan now stashes the raw Unit_Key_RO.inf + MKB bytes on AacsState (via resolve_vid_only, the disable_keydb path), so an external key-resolver can derive unit keys from a resolved VUK without re-reading the disc — the foundation for moving lookup/derivation out of libfreemkv. Additive: the keydb path is untouched, all existing constructors default the new fields empty. 584 lib tests green. Builds on the KeyOrigin rename + the Key/decrypt_with API.	2026-06-04 13:20:27 -07:00
MattJackson	d94a4d3444	0.27.5 (step 2, item 2): rename provenance enum KeySource -> KeyOrigin Disambiguates the key vocabulary: Key (the input handed to decrypt_with), key sources (the resolver's lookup list), and KeyOrigin (how a key was resolved). Internal-only rename — no dependents import it.	2026-06-04 11:42:21 -07:00
MattJackson	1bd7e1de2a	0.27.4: lookup-free Key API (Disc::decrypt_with) + E8005 deferred-mux fix Add libfreemkv::Key (non_exhaustive; Unit wired) + Disc::decrypt_with(Key) — the caller resolves a key from any source and hands it in; the library decrypts with no keydb/network of its own. inject_unit_keys now synthesizes a minimal ExternalUk AACS state when a scan built none (no keydb at scan time), so a disc keyed at sweep but scanned without a keydb still decrypts from its mapfile UK instead of reporting E8005 and deferring the mux forever. Tests cover the synthesize, replace, empty->None, and decrypt_with paths.	2026-06-04 11:08:33 -07:00
MattJackson	da62ee7cf2	v0.27.3: bump version	2026-06-03 21:47:43 -07:00
MattJackson	575c76156f	mapfile: persist resolved unit keys (keys XOR VID) A keyed disc now writes its decrypted AACS unit keys to the mapfile header (# freemkv-uk: <cps>:<hex>); an unresolved disc writes only the VID. The two are mutually exclusive (set_unit_keys clears the VID) — unit keys are the final answer, so deferred-mux / resume decrypts directly with no key lookup, while the VID alone is the 'still unresolved, retry' marker. CopyOptions/SweepOptions carry the keys (written when present, else the VID); Disc::inject_unit_keys applies mapfile-recovered keys to a scanned disc. Round-trip test added.	2026-06-03 21:45:37 -07:00
MattJackson	b518860d9c	v0.27.0: detect AACS-scrambled units by raw TS sync, not flag bits Rename is_unit_encrypted -> is_aacs_scrambled and decide encryption from the unit's MPEG-TS sync bytes (destroyed by the encrypted body) instead of the TP_extra copy-control (byte 0) or TS scrambling-control (byte 7) flags, which discs do not set reliably. One shared predicate now backs the decrypt gate and out-of-band key validation, so callers agree on what 'encrypted' means. Decryption restores the syncs, so a decrypted unit reads as clear and there is no flag to clear.	2026-06-03 07:35:50 -07:00
MattJackson	c8eb42b490	v0.26.11: detect AACS unit encryption via TS scrambling-control bits is_unit_encrypted read the TP_extra copy-control bits (byte 0), which are a copy-permission flag, not an encryption flag. On discs whose sampled units are clear navigation packets (PAT/PMT) those bits can be set while the unit is not scrambled, so a correct Unit Key was used to 'decrypt' already-plaintext data, produced garbage, and the key was wrongly treated as failing. Read the actual flag instead: the TS transport_scrambling_control bits (top two of TS-header byte 3 = byte 7 of the aligned unit, inside the clear seed). AACS encrypts whole aligned units, so this one packet's TSC reflects the unit. decrypt_unit now clears the TSC bits of every packet on the way out so the result is valid unscrambled TS. Tests updated to the TSC flag.	2026-06-02 20:37:56 -07:00
MattJackson	48570ac065	Local resolve: MK-pool brute via km_verifies (path 2.5) keydb stores Media Keys per-disc, but an MK is MKB-scoped (shared across a pressing/MKB-family). A disc whose own hash/VID isn't keyed can still resolve if any stored MK verifies against its MKB. New path 2.5 (between PK and the VID lookup) collects the distinct MK pool from the providers, km_verifies each against the disc MKB, and on a UNIQUE pass derives VUK (with the disc VID) then the UK — matching the online resolver's behavior so local keydb mode resolves the same discs (e.g. an MK present in keydb under a sibling pressing). km_verifies is one AES-D + magic check per candidate (cheap). Adds KeyProvider::media_keys() + a path-2.5 unit test.	2026-06-02 16:14:09 -07:00
MattJackson	08e46640fd	v0.26.8: bump version	2026-06-02 15:41:38 -07:00
MattJackson	a9195824ff	Trim MKB to real record length; empty unit-keys means no keys - mkb_content_len walks the MKB record stream and returns where it ends, so callers can drop the trailing zero padding. MKB files are allocated to a fixed size (~128 MiB) with records at the front; both MKB_RO and MKB_RW can be padded. read_aacs_inputs* now trim to the real records (~few MB) instead of shipping ~128 MiB of zeros. - decrypt_keys() returns None when unit_keys is empty: an AACS state that carries only a VID (out-of-band resolution, pre-key) is 'encrypted, no keys', not a usable empty key set.	2026-06-02 15:41:27 -07:00
MattJackson	401fe23988	v0.26.7: bump version	2026-06-02 15:15:58 -07:00
MattJackson	f89bce5851	Read MKB_RO not the padded MKB_RW; keep VID when keydb is disabled - read_aacs_inputs / read_aacs_inputs_from_drive now read MKB_RO.inf first. MKB_RW.inf is a fixed ~128 MiB rewritable region that is mostly zero padding; reading it shipped 124 MiB of nothing. MKB_RO is the real, correctly-sized MKB (a few MB). Fall back to RW only if RO is absent. - disable_keydb no longer drops the Volume ID. A caller resolving Unit Keys out-of-band needs the VID (on-disc content read during the handshake). New resolve_vid_only builds a keys-free AacsState carrying just the VID + version metadata, so the disc reports 'encrypted, no keys' (resolved out-of-band) instead of discarding the VID.	2026-06-02 15:15:45 -07:00
MattJackson	dfccb85e15	v0.26.6: bump version	2026-06-02 14:11:13 -07:00
MattJackson	ebedffb762	ScanOptions: add disable_keydb to skip all keydb lookup A caller that resolves Unit Keys out-of-band can now set disable_keydb so the scan consults no keydb at all — neither an explicit keydb_path nor the standard search locations. Without it, a keydb that merely sits in a default location ('~/.config/...') silently shadows the out-of-band path. unit_key still takes precedence over everything.	2026-06-02 14:09:59 -07:00
MattJackson	fdf63ccb7f	v0.26.5: bump version	2026-06-02 13:37:32 -07:00
MattJackson	c735d284da	v0.26.4: bump version	2026-06-02 13:06:10 -07:00
MattJackson	94ab7bc73c	scan: genericize the caller-supplied unit-key docs (no external-source naming) The ScanOptions.unit_key path is a generic primitive — a caller-supplied Unit Key that bypasses keydb lookup. Doc comments + a tracing log named a specific external source; reworded to neutral 'out-of-band / external key service' so the library makes no assumptions about where the key came from.	2026-06-02 13:00:11 -07:00
MattJackson	9f209fe066	v0.26.3: bump version	2026-06-02 10:56:56 -07:00
MattJackson	32a1a6e095	mapfile: persist AACS Volume ID as ddrescue-safe comment Add an optional 16-byte AACS Volume ID to the Mapfile, persisted as a '# freemkv-vid: <32-hex>' header comment so it survives to deferred-mux and resume without touching the ISO payload. ddrescue treats the line as a comment, so the pos/size/status data parser is unaffected. - Mapfile gains set_vid/vid accessors; save() emits the comment in the header block, load() parses it back (malformed/absent -> None, never errors the load). Load->save round-trip preserves it (patch pass). - Thread vid through CopyOptions and SweepOptions; sweep persists it when creating/opening the mapfile. - Unit test: round-trips the VID, asserts the saved comment, and confirms data ranges parse identically with and without the comment.	2026-06-02 08:50:19 -07:00
MattJackson	1d3b8f5fb6	chore: gitignore scratch/ (prevent accidental commit of session artifacts)	2026-06-01 22:52:58 -07:00
MattJackson	97b0ae7be2	chore: scrub internal refs from changelog/makefile/cargo	2026-06-01 22:46:54 -07:00
MattJackson	7756f1feca	aacs: restore read_aacs_inputs_from_drive (live-drive key-file extractor)	2026-06-01 21:52:27 -07:00
MattJackson	1565da610a	chore: scrub non-shippable references from tests/comments	2026-06-01 21:36:57 -07:00
MattJackson	e134616422	v0.26.2: bump version	2026-06-01 21:06:56 -07:00
MattJackson	8d54a3c64e	aacs: KeyProvider abstraction + PK walker + external-UK key source Two coherent additions to the AACS resolver: KeyProvider abstraction (provider.rs) — key material comes from pluggable backends; KeyDb implements it (device/processing keys, host certs, disc-by-hash / disc-by-vid lookup) plus orphan-DK parsing. ResolveContext takes a provider array. Adds the SD-tree PK walker (derive_media_key_from_pk_walked) and a `probe` module (km_verifies MK oracle, mkb_* record parsers) used for offline key verification. Cvalue record selection prefers 0x05, falls back to 0x07. External-UK key source — the second, mutually-exclusive key source for the keyserver path. ScanOptions/InputOptions gain `unit_key`; when set, resolve_encryption_static skips keydb entirely and uses the caller-supplied Unit Key directly (KeySource::ExternalUk). Disc::read_aacs_inputs exposes a disc's Unit_Key_RO.inf + MKB so a caller can fetch the UK out-of-band; the library makes no network call itself. CHANGELOG: redact test-disc title in historical notes.	2026-06-01 20:47:14 -07:00
MattJackson	c0478e1273	labels(pixelogic): number audio from the FPL playlist, not menu segments Pixelogic discs that authored a SEG_MainFeature menu/preview segment containing a stray commentary token made the parser anchor on that segment instead of the real FPL_MainFeature playlist. Combined with 'Audio Stream N' placeholder tokens not advancing the audio counter, a lone eng_ACOM_ commentary at STN slot 4 collapsed onto slot 1 — tagging the main feature track as Commentary (seen on Wicked: For Good). Fix: - Anchor the feature section on the FPL_ playlist when present; only fall back to SEG_MainFeature on discs with no FPL_ section. - Count 'Audio Stream N' placeholders so editorial audio tokens get their true STN ordinal. Subtitle (PG Stream N) numbering is left unchanged — counting it regressed several corpus discs. Extract the section/numbering loop into assign_labels with unit tests. Verified: 11/11 labels-corpus discs still PASS; Wicked commentary now lands on the AC-3 2.0 stereo track instead of the main TrueHD.	2026-05-31 21:16:11 -07:00