v1.4.5: bump version (freemkv-unlock git-pinned for the tag)

The read_plan fix landed on the file-backed highway (build_iso_pipeline)
but the inline DiscStream (live single-pass) still passed the alternate
device-group half to the demux — a known FMTS bug on rip_mode="single".

DiscStream::with_key_map installs the proactive map and rewrites the
extent walk to the read plan, so the live single-pass path reads ONLY
our-phase units, exactly like the highway. DecryptingSectorSource gains
set_key_map for the already-constructed decorator. Non-forensic maps
return the extents unchanged, so every non-FMTS disc is byte-identical.

Test: with_key_map_reads_only_our_phase_units — a forensic Even segment
drops exactly its alternate units from the extent walk. Precommit green
on 1.86.

CHANGELOG.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## [1.4.5] — 2026-07-18
+
+### Fixed
+
+- **FMTS (AACS 2.1) forensic discs now mux to a clean, single-variant stream.** A
+  forensic segment interleaves the local device group's variant with a foreign
+  group's at the aligned-unit level. The mux decrypted only our half but left the
+  foreign half in the buffer as ciphertext, on the assumption that the demuxer
+  "drops untouched ciphertext cleanly." It does not — a foreign unit's bytes hit a
+  tracked PID at the 192-byte stride, mis-parse, and trip the demux's concealed-gap
+  keyframe resync, which discards good frames of ours around every segment (visible
+  playback glitches). `AacsKeyMap::read_plan` now turns the map into the title's
+  read plan: every default / CPS unit, plus inside a forensic segment **only our
+  phase's units**. The foreign half is never read, decrypted, or handed to the
+  demux. On a retail 4K UHD title this took concealed-gap resyncs from **349 → 0**
+  and recovered ~2 GB of previously-dropped frames. Wired into **both** mux paths —
+  the file-backed highway (`build_iso_pipeline`) and the inline live-drive
+  `DiscStream` (`with_key_map`) — so single- and multi-pass FMTS rips are both clean.
+
+### Changed
+
+- **Key-bearing types redact their `Debug` output.** Every type that carries key
+  material (device keys, processing keys, unit keys, media keys, VUKs, resolved
+  chains, CSS/AACS state, …) now prints a `<redacted>` marker instead of the bytes,
+  so no key can reach a log or panic message. Each is covered by a test asserting no
+  key byte appears.
+- **Hex parsing is centralized and case-insensitive.** A single set of canonical
+  `0x`/`0X`-tolerant hex→integer parsers replaces scattered ad-hoc parsing (this is
+  what silently dropped keydb device keys written with an uppercase `0X` prefix).
+- **Internal-only public surface narrowed to `pub(crate)`, and duplicate
+  `foo_with_X` methods collapsed to one** — no behavioral change, smaller API.
+
+## [1.4.4] — 2026-07-17
+
+### Fixed
+
+- **Online key requests are no longer silently dropped on discs that yield few
+  sample units.** The online key source refuses any request carrying fewer than
+  `MIN_SAMPLE_UNITS` (8) encrypted-content samples — too few can match an
+  incidental unit rather than the one asked about (a false positive, most acute on
+  AACS 2.1 forensic-variant content). autorip gathered only 4, so every online
+  lookup was skipped before it ever reached the key service and surfaced to the
+  user as "key service down." autorip's sample count is now tied to
+  `MIN_SAMPLE_UNITS` with a **compile-time floor**, so it can never regress below
+  the minimum again.
+
+### Changed
+
+- **The online request is assembled from a proven-sufficient sample set.** New
+  `DecodeSampleSet` (`libfreemkv::keysource`) wraps the content-unit samples and
+  can only be constructed with at least `MIN_SAMPLE_UNITS` of them — so an online
+  key request cannot be built from too few samples. The minimum is validated once,
+  at construction, rather than by a runtime check a caller could forget.
+
+## [1.4.3] — 2026-07-17
+
+### Changed
+
+- **`MIN_SAMPLE_UNITS` moved to the base crate.** The minimum sample count an
+  online key request must carry now has a single definition in
+  `libfreemkv::keysource`; `freemkv-keysources` re-exports it, so the online source
+  and libfreemkv's own forensic query size their requests from one shared value.
+- **The online unit-key reply is parsed as a list.** A response carries either a
+  single Unit Key (ordinary disc) or the full ordered set (an AACS 2.1
+  forensic-variant disc); the client accepts both and maps array position to
+  forensic index.
+
+### Added
+
+- **Forensic-variant online query samples the anchor segment.** On an AACS 2.1
+  forensic-variant disc the online key query draws its sample from the first
+  forensic segment (index 1) — one canonical, deterministic sample — instead of an
+  arbitrary segment.
+
 ## [1.4.2] — 2026-07-15
 
 ### Fixed

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "libfreemkv"
-version = "1.4.2"
+version = "1.4.5"
 edition = "2024"
 rust-version = "1.86"
 license = "MIT"
@@ -28,7 +28,7 @@ cbc = "0.1"
 # Interim path dep for local cross-repo dev; the release script re-pins this to
 # `{ git = ".../freemkv-unlock", tag = "vX.Y.Z" }` before tagging libfreemkv (so
 # the released tag resolves freemkv-unlock from git, not a sibling path).
-freemkv-unlock = { git = "https://github.com/freemkv/freemkv-unlock", tag = "v1.4.2" }
+freemkv-unlock = { git = "https://github.com/freemkv/freemkv-unlock", tag = "v1.4.5" }
 num-bigint = "0.4"
 num-traits = "0.2"
 num-integer = "0.1"

src/aacs/content.rs

@@ -53,31 +53,6 @@ const TS_SYNC: u8 = 0x47;
 
 // ── Content decryption ──────────────────────────────────────────────────────
 
-/// True if a 6144-byte aligned unit's MPEG-TS sync structure is DESTROYED — it
-/// lacks the `0x47` sync bytes a clear BD-TS unit carries at offsets 4, 196,
-/// 388, … (one per 192-byte source packet).
-///
-/// This is a pure BYTE heuristic; on its own it does NOT mean "encrypted". A
-/// destroyed sync structure can be AACS ciphertext, uncorrected-ECC garbage, OR
-/// data that was never MPEG-TS at all (UDF filesystem / nav) — those are
-/// byte-indistinguishable. So this answers only *"does this unit look like valid
-/// clear TS, or not"*, nothing about encryption.
-///
-/// The "is this unit AACS-encrypted (and must decrypt)?" decision is COMPOSED by
-/// the caller, because it needs context this function lacks:
-/// `inside an m2ts content extent` AND `ts_sync_destroyed` AND `no key decrypts`
-/// (see [`crate::decrypt::decrypt_sectors_in_content`] and
-/// [`crate::Disc::encrypted_content_ranges`]). Inside known content this
-/// primitive separates an encrypted/garbled unit (destroyed) from a clear
-/// segment (intact); OUTSIDE content it is meaningless — feeding it filesystem
-/// bytes is what produced the first-2 GB false-positive this split fixes.
-///
-/// 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.
-pub fn ts_sync_destroyed(unit: &[u8]) -> bool {
-    unit.len() >= ALIGNED_UNIT_LEN && !ts_syncs_intact(unit)
-}
-
 /// HD-DVD `.evo` (MPEG-2 Program Stream) AACS-encrypted-unit flag offset & mask.
 ///
 /// BD/UHD/FMTS flag encryption with the Copy Permission Indicator in the top 2
@@ -144,12 +119,13 @@ pub fn aacs_unit_encrypted(unit: &[u8], format: crate::disc::ContentFormat) -> b
 ///
 /// Like the flag itself this is only meaningful at the clip-FILE-anchored boundary.
 pub fn aacs_unit_needs_decrypt(unit: &[u8], format: crate::disc::ContentFormat) -> bool {
-    use crate::disc::ContentFormat;
-    aacs_unit_encrypted(unit, format)
-        && match format {
-            ContentFormat::BdTs => ts_sync_destroyed(unit),
-            ContentFormat::MpegPs => !is_clean_ps(unit),
-        }
+    // "Still needs the key applied" = flagged encrypted AND not yet structurally
+    // clean. There is ONE definition of clean — [`is_clean`] (the min(E,4) proof
+    // floor: E>4 needs any 4 synced, E<=4 needs all present). Never a second
+    // threshold: the old >50% majority false-flagged a bad-encoded-but-OPENED
+    // unit as still-scrambled, so the mux re-sampled it to the key service every
+    // batch (the storm) and could re-apply the key over already-clear bytes.
+    aacs_unit_encrypted(unit, format) && !is_clean(unit, format)
 }
 
 /// Minimum synced content packets that PROVE a key opened a unit. Four `0x47`
@@ -241,10 +217,6 @@ pub fn ts_packet_total(unit: &[u8]) -> usize {
     unit.len() / BD_SOURCE_PACKET_BYTES
 }
 
-fn ts_syncs_intact(unit: &[u8]) -> bool {
-    ts_sync_count(unit) > ts_packet_total(unit) / 2
-}
-
 /// The Program-Stream arm of [`is_clean`] (HD-DVD `.evo`): a pure structural
 /// check that a unit is valid MPEG-2 PS — every 2048-byte pack begins with the
 /// pack_start_code `00 00 01 BA`; a 6144-byte AACS unit spans three packs.
@@ -421,7 +393,10 @@ mod tests {
             unit[off] = TS_SYNC;
             off += BD_SOURCE_PACKET_BYTES;
         }
-        assert!(!ts_sync_destroyed(&unit));
+        assert!(crate::aacs::content::is_clean(
+            &unit,
+            crate::disc::ContentFormat::BdTs
+        ));
         assert!(
             !aacs_unit_encrypted(&unit, ts),
             "byte-0 CPI clear ⇒ not flagged encrypted"
@@ -448,54 +423,70 @@ mod tests {
     }
 
     #[test]
-    fn scramble_detection_at_16_32_boundary() {
-        // With 32 stride positions the majority threshold is
-        // total/2 = 16. A unit with EXACTLY half its syncs intact (16) must
-        // NOT be over-counted into the "scrambled" bucket by an inflated
-        // total: 16 > 16 is false → not-intact → scrambled. 17 intact → clear.
-        // The fix is that `total` is 32 (not 33), so the boundary sits cleanly
-        // at the real midpoint.
-        let set_syncs = |n: usize| {
-            let mut unit = vec![0u8; ALIGNED_UNIT_LEN];
-            let mut off = 4;
+    fn is_clean_min4_proof_floor() {
+        // ONE rule: a unit is clean iff `synced >= min(E, 4)` over the ENCRYPTED
+        // (non-padding) packets — E>4 needs any 4, E<=4 needs all present. Build
+        // NON-ZERO payloads (real content, not padding) so every packet counts
+        // toward E; place `n` TS syncs among packets 1..31 (packet 0 is skipped).
+        let unit_with = |synced: usize| {
+            let mut unit: Vec<u8> = (0..ALIGNED_UNIT_LEN)
+                .map(|i| ((i * 7 + 1) as u8) | 1)
+                .collect();
+            // Scrub any accidental 0x47 at a sync position, then place exactly
+            // `synced` real syncs in packets 1.. (skip packet 0).
+            let mut off = BD_SOURCE_PACKET_BYTES + 4;
             let mut placed = 0;
-            while off < ALIGNED_UNIT_LEN && placed < n {
-                unit[off] = TS_SYNC;
-                off += BD_SOURCE_PACKET_BYTES;
+            while off < ALIGNED_UNIT_LEN {
+                unit[off] = if placed < synced { TS_SYNC } else { 0x46 };
                 placed += 1;
+                off += BD_SOURCE_PACKET_BYTES;
             }
             unit
         };
-
-        assert_eq!(ts_sync_count(&set_syncs(16)), 16);
-        assert_eq!(ts_sync_count(&set_syncs(17)), 17);
-
-        // Exactly half intact → classified scrambled (16 > 16 is false).
-        assert!(ts_sync_destroyed(&set_syncs(16)));
-        // One past half → classified clear.
-        assert!(!ts_sync_destroyed(&set_syncs(17)));
+        // E = 31 content packets (all non-zero) → threshold min(31,4) = 4.
+        assert!(
+            !crate::aacs::content::is_clean(&unit_with(3), crate::disc::ContentFormat::BdTs),
+            "3 synced of a well-populated unit is below the proof floor → not clean"
+        );
+        assert!(
+            crate::aacs::content::is_clean(&unit_with(4), crate::disc::ContentFormat::BdTs),
+            "4 synced proves the key opened it, even with many bad-encoded packets"
+        );
+        // The old >50% majority would have called `unit_with(4)` scrambled (4/31
+        // < half) — that false-flag was the mux key-server storm. min(E,4) fixes it.
     }
 
     #[test]
     fn scramble_detection_extremes() {
-        // Detection semantics for the clear-cut cases must be preserved:
-        // a fully-clear unit (all 32 syncs) is NOT scrambled; a unit with no
-        // syncs (fully scrambled body) IS scrambled.
+        // A fully-clear unit (every packet synced) is clean; a fully-scrambled
+        // unit (non-zero ciphertext, NO syncs) is not. (An all-zero buffer is
+        // empty padding — E==0 — which `is_clean` treats as clean, NOT scrambled.)
         let mut clear = vec![0u8; ALIGNED_UNIT_LEN];
         let mut off = 4;
         while off < ALIGNED_UNIT_LEN {
             clear[off] = TS_SYNC;
             off += BD_SOURCE_PACKET_BYTES;
         }
-        assert_eq!(ts_sync_count(&clear), 32);
         assert!(
-            !ts_sync_destroyed(&clear),
-            "fully-clear unit → not scrambled"
+            crate::aacs::content::is_clean(&clear, crate::disc::ContentFormat::BdTs),
+            "fully-clear unit → clean"
         );
 
-        let scrambled = vec![0u8; ALIGNED_UNIT_LEN];
-        assert_eq!(ts_sync_count(&scrambled), 0);
-        assert!(ts_sync_destroyed(&scrambled), "no syncs → scrambled");
+        // Real scrambled ciphertext: non-zero everywhere, no 0x47 at any sync slot.
+        let mut scrambled: Vec<u8> = (0..ALIGNED_UNIT_LEN)
+            .map(|i| ((i * 13 + 3) as u8) | 1)
+            .collect();
+        let mut off = 4;
+        while off < ALIGNED_UNIT_LEN {
+            if scrambled[off] == TS_SYNC {
+                scrambled[off] = 0x46;
+            }
+            off += BD_SOURCE_PACKET_BYTES;
+        }
+        assert!(
+            !crate::aacs::content::is_clean(&scrambled, crate::disc::ContentFormat::BdTs),
+            "non-zero body with no syncs → scrambled"
+        );
     }
 
     #[test]
@@ -574,9 +565,15 @@ mod tests {
 
         // Now plain contains encrypted data. Decrypt it.
         let mut unit = plain;
-        assert!(ts_sync_destroyed(&unit));
+        assert!(!crate::aacs::content::is_clean(
+            &unit,
+            crate::disc::ContentFormat::BdTs
+        ));
         decrypt_unit(&mut unit, &unit_key);
-        assert!(!ts_sync_destroyed(&unit)); // decrypted: TS syncs restored
+        assert!(crate::aacs::content::is_clean(
+            &unit,
+            crate::disc::ContentFormat::BdTs
+        )); // decrypted: TS syncs restored
 
         // Verify TS sync bytes
         let mut count = 0;
@@ -1151,14 +1148,17 @@ mod tests {
         let mut unit = clear_unit();
         aacs_encrypt_unit(&mut unit, &unit_key);
         assert!(
-            ts_sync_destroyed(&unit),
+            !crate::aacs::content::is_clean(&unit, crate::disc::ContentFormat::BdTs),
             "encrypted unit must look scrambled"
         );
 
         decrypt_unit(&mut unit, &unit_key);
         // All 32 stride positions carry sync after decrypt.
         assert_eq!(ts_sync_count(&unit), ts_packet_total(&unit));
-        assert!(!ts_sync_destroyed(&unit));
+        assert!(crate::aacs::content::is_clean(
+            &unit,
+            crate::disc::ContentFormat::BdTs
+        ));
     }
 
     #[test]
@@ -1291,13 +1291,22 @@ mod tests {
         // The function guards on `len >= ALIGNED_UNIT_LEN` first; anything
         // shorter is reported NOT scrambled (so the decrypt gate skips it)
         // rather than indexing past the end.
-        assert!(!ts_sync_destroyed(&[]));
-        assert!(!ts_sync_destroyed(&vec![0u8; ALIGNED_UNIT_LEN - 1]));
+        assert!(crate::aacs::content::is_clean(
+            &[],
+            crate::disc::ContentFormat::BdTs
+        ));
+        assert!(crate::aacs::content::is_clean(
+            &vec![0u8; ALIGNED_UNIT_LEN - 1],
+            crate::disc::ContentFormat::BdTs
+        ));
         // A scrambled-looking buffer that is one byte short is still "not
         // scrambled" by the length guard.
         let mut almost = vec![0u8; ALIGNED_UNIT_LEN - 1];
         almost[4] = 0x00; // no syncs
-        assert!(!ts_sync_destroyed(&almost));
+        assert!(crate::aacs::content::is_clean(
+            &almost,
+            crate::disc::ContentFormat::BdTs
+        ));
     }
 
     #[test]

src/aacs/derive.rs

@@ -465,7 +465,7 @@ pub enum KeyCandidate {
 /// its declared CPS-unit number); the caller runs
 /// `decrypt_unit` + `is_clean_ts` to find which one actually opens the
 /// disc. Rungs above the candidate are `None`.
-#[derive(Debug, Clone)]
+#[derive(Clone)]
 pub struct ResolvedChain {
     pub unit_keys: Vec<(u32, [u8; 16])>,
     pub vuk: Option<Vuk>,
@@ -475,6 +475,21 @@ pub struct ResolvedChain {
     pub dk: Option<DeviceKey>,
 }
 
+// Redacting `Debug`: `unit_keys` holds raw title-key bytes, never printed. The
+// other rungs are `types` newtypes that self-redact. Guarded by
+// `resolved_chain_debug_is_redacted`.
+impl std::fmt::Debug for ResolvedChain {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("ResolvedChain")
+            .field("unit_keys_len", &self.unit_keys.len())
+            .field("vuk", &self.vuk)
+            .field("mk", &self.mk)
+            .field("pk", &self.pk)
+            .field("dk", &self.dk)
+            .finish()
+    }
+}
+
 /// Derive the full AACS key chain from a candidate key of ANY ladder rung.
 ///
 /// Runs the deterministic derivation DOWNWARD to the disc's terminal unit keys:
@@ -568,6 +583,28 @@ mod resolve_candidate_tests {
     use super::*;
     use crate::aacs::crypto::aes_ecb_encrypt;
 
+    /// `ResolvedChain.unit_keys` holds raw title-key bytes (the other rungs are
+    /// self-redacting `types` newtypes). `Debug` must not leak the title keys.
+    #[test]
+    fn resolved_chain_debug_is_redacted() {
+        let c = ResolvedChain {
+            unit_keys: vec![(1, [0xD5; 16])],
+            vuk: None,
+            mk: None,
+            pk: None,
+            dk: None,
+        };
+        let dbg = format!("{c:?}");
+        assert!(
+            !dbg.contains("213"),
+            "ResolvedChain leaked unit keys: {dbg}"
+        );
+        assert!(
+            dbg.contains("unit_keys_len"),
+            "ResolvedChain missing redaction: {dbg}"
+        );
+    }
+
     /// Minimal AACS-1.0 (48-byte stride) `Unit_Key_RO.inf` with `n` encrypted
     /// unit keys — `parse_unit_key_ro` numbers CPS units 1..=n.
     fn synth_inf(encs: &[[u8; 16]]) -> Vec<u8> {

src/aacs/index_select.rs

@@ -1,73 +1,73 @@
-//! FMTS variant selection — the pure decode-time decision for a 2.1 disc.
+//! FMTS index selection — the pure decode-time decision for a 2.1 disc.
 //!
-//! A 2.1 disc resolves to exactly one forensic variant (1..=32) for a given
-//! rip. `IndividualSegment.tbl` tags each forensic segment with a variant (see
-//! [`super::segment`]); the decode keeps the segments matching our variant,
+//! A 2.1 disc resolves to exactly one forensic index (1..=32) for a given
+//! rip. `IndividualSegment.tbl` tags each forensic segment with an index (see
+//! [`super::segment`]); the decode keeps the segments matching our index,
 //! drops the other 31, and treats everything outside a segment as ordinary
-//! (variant-0) content. This module owns that classification and nothing else —
+//! (index-0) content. This module owns that classification and nothing else —
 //! no I/O, no keys, no cipher — so it is fully testable in isolation. The
 //! decrypt pipeline consumes the [`UnitDisposition`] it returns.
 //!
-//! Where the resolved variant comes from is a separate concern
-//! ([`resolve_disc_variant`]): today it is read off the variant keys the key
+//! Where the resolved index comes from is a separate concern
+//! ([`resolve_disc_index`]): today it is read off the index keys the key
 //! source handed us; when Processing Keys are available it will come from the
 //! VK derivation instead. Either way the disposition logic below is identical.
 
-use super::segment::{Segment, variant_segment_for_unit};
+use super::segment::{Segment, segment_for_unit};
 use super::types::UnitKey;
 
 /// What the decode should do with one AACS aligned unit.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum UnitDisposition {
     /// Outside every forensic segment: ordinary content, decrypt with the
-    /// default (variant-0) unit key.
+    /// default (index-0) unit key.
     Default,
-    /// Inside a forensic segment tagged with OUR resolved variant: decrypt with
-    /// that variant's key.
-    Variant(u8),
-    /// Inside a forensic segment tagged with a DIFFERENT variant: not our
+    /// Inside a forensic segment tagged with OUR resolved index: decrypt with
+    /// that index's key.
+    Index(u8),
+    /// Inside a forensic segment tagged with a DIFFERENT index: not our
     /// watermark, so it is not part of our output — drop it.
-    DropForeignVariant(u8),
-    /// Inside a forensic segment but no variant key is held (the disc's variant
+    DropForeignIndex(u8),
+    /// Inside a forensic segment but no index key is held (the disc's index
     /// was never resolved): the segment cannot be decoded, so it is concealed
-    /// as loss. Carries the segment's variant for diagnostics.
+    /// as loss. Carries the segment's index for diagnostics.
     ForensicNoKey(u8),
 }
 
-/// Resolve the disc's single forensic variant from the keys we hold.
+/// Resolve the disc's single forensic index from the keys we hold.
 ///
-/// Scans for a variant key (`variant_number` in `1..=32`) and returns its
-/// variant. `None` when only default (variant-0) keys are held — i.e. no
-/// variant source answered, so forensic segments are not decodable. A disc has
-/// exactly one variant, so the first non-zero key decides; if several distinct
-/// variant keys were somehow supplied the lowest wins (deterministic), which is
+/// Scans for an index key (`index_number` in `1..=32`) and returns its
+/// index. `None` when only default (index-0) keys are held — i.e. no
+/// index source answered, so forensic segments are not decodable. A disc has
+/// exactly one index, so the first non-zero key decides; if several distinct
+/// index keys were somehow supplied the lowest wins (deterministic), which is
 /// only a defensive tiebreak — the probe/derivation yields one.
-pub fn resolve_disc_variant(unit_keys: &[UnitKey]) -> Option<u8> {
+pub fn resolve_disc_index(unit_keys: &[UnitKey]) -> Option<u8> {
     unit_keys
         .iter()
-        .map(|k| k.variant_number)
+        .map(|k| k.index_number)
         .filter(|&v| v != 0)
         .min()
 }
 
 /// Classify the AACS aligned unit at `unit_offset` (clip-relative bytes) given
-/// the forensic segment map and the disc's resolved variant (`None` if no
-/// variant key is held).
+/// the forensic segment map and the disc's resolved index (`None` if no
+/// index key is held).
 pub fn unit_disposition(
     unit_offset: u64,
     segments: &[Segment],
-    disc_variant: Option<u8>,
+    disc_index: Option<u8>,
 ) -> UnitDisposition {
-    match variant_segment_for_unit(segments, unit_offset) {
+    match segment_for_unit(segments, unit_offset) {
         // Not in any forensic segment → ordinary content.
         None => UnitDisposition::Default,
-        // In a forensic segment → decide by whether it is our variant.
+        // In a forensic segment → decide by whether it is our index.
         Some(seg) => {
-            let seg_variant = seg.variant as u8;
-            match disc_variant {
-                Some(v) if v == seg_variant => UnitDisposition::Variant(v),
-                Some(_) => UnitDisposition::DropForeignVariant(seg_variant),
-                None => UnitDisposition::ForensicNoKey(seg_variant),
+            let seg_index = seg.index as u8;
+            match disc_index {
+                Some(v) if v == seg_index => UnitDisposition::Index(v),
+                Some(_) => UnitDisposition::DropForeignIndex(seg_index),
+                None => UnitDisposition::ForensicNoKey(seg_index),
             }
         }
     }
@@ -79,7 +79,7 @@ mod tests {
     use crate::aacs::content::ALIGNED_UNIT_LEN;
     use crate::aacs::segment::{SOURCE_PACKET_LEN, parse_individual_segments};
 
-    /// Build a one-record segment table (variant, start_spn, end_spn).
+    /// Build a one-record segment table (index, start_spn, end_spn).
     fn tbl(recs: &[(u16, u32, u32)]) -> Vec<Segment> {
         let mut v = Vec::new();
         v.extend_from_slice(&0x0100_0000u32.to_be_bytes());
@@ -95,23 +95,23 @@ mod tests {
         parse_individual_segments(&v).expect("parse")
     }
 
-    fn uk(idx: u32, variant: u8) -> UnitKey {
-        if variant == 0 {
+    fn uk(idx: u32, index: u8) -> UnitKey {
+        if index == 0 {
             UnitKey::new(idx, [0u8; 16])
         } else {
-            UnitKey::variant(idx, [variant; 16], variant)
+            UnitKey::forensic(idx, [index; 16], index)
         }
     }
 
     #[test]
-    fn resolve_picks_the_single_variant_key() {
-        // Default keys only → no variant resolved.
-        assert_eq!(resolve_disc_variant(&[uk(0, 0)]), None);
-        assert_eq!(resolve_disc_variant(&[]), None);
-        // One variant key among defaults → that variant.
-        assert_eq!(resolve_disc_variant(&[uk(0, 0), uk(1, 7)]), Some(7));
-        // Defensive: lowest of several distinct variants (deterministic).
-        assert_eq!(resolve_disc_variant(&[uk(0, 9), uk(1, 3)]), Some(3));
+    fn resolve_picks_the_single_index_key() {
+        // Default keys only → no index resolved.
+        assert_eq!(resolve_disc_index(&[uk(0, 0)]), None);
+        assert_eq!(resolve_disc_index(&[]), None);
+        // One index key among defaults → that index.
+        assert_eq!(resolve_disc_index(&[uk(0, 0), uk(1, 7)]), Some(7));
+        // Defensive: lowest of several distinct indexes (deterministic).
+        assert_eq!(resolve_disc_index(&[uk(0, 9), uk(1, 3)]), Some(3));
     }
 
     #[test]
@@ -130,29 +130,29 @@ mod tests {
     }
 
     #[test]
-    fn unit_in_our_variant_decrypts() {
+    fn unit_in_our_index_decrypts() {
         let segs = tbl(&[(7, 100, 200)]);
         let off = 120u64 * SOURCE_PACKET_LEN;
         assert_eq!(
             unit_disposition(off, &segs, Some(7)),
-            UnitDisposition::Variant(7)
+            UnitDisposition::Index(7)
         );
     }
 
     #[test]
-    fn unit_in_foreign_variant_drops() {
-        // Segment tagged variant 7, but our disc variant is 3 → drop it.
+    fn unit_in_foreign_index_drops() {
+        // Segment tagged index 7, but our disc index is 3 → drop it.
         let segs = tbl(&[(7, 100, 200)]);
         let off = 120u64 * SOURCE_PACKET_LEN;
         assert_eq!(
             unit_disposition(off, &segs, Some(3)),
-            UnitDisposition::DropForeignVariant(7)
+            UnitDisposition::DropForeignIndex(7)
         );
     }
 
     #[test]
     fn forensic_unit_with_no_key_is_concealed() {
-        // A forensic segment but we never resolved a variant → conceal as loss.
+        // A forensic segment but we never resolved an index → conceal as loss.
         let segs = tbl(&[(7, 100, 200)]);
         let off = 120u64 * SOURCE_PACKET_LEN;
         assert_eq!(
@@ -164,7 +164,7 @@ mod tests {
     #[test]
     fn straddling_unit_still_classified_as_its_segment() {
         // A unit whose 32-packet span only tails into the segment still routes
-        // to the segment (matches variant_segment_for_unit's span test).
+        // to the segment (matches segment_for_unit's span test).
         let segs = tbl(&[(5, 100, 200)]);
         let unit_packets = (ALIGNED_UNIT_LEN as u64 / SOURCE_PACKET_LEN) as u32; // 32
         // Start so the unit covers [80, 80+31] = [80, 111]: overlaps at 100.
@@ -172,7 +172,7 @@ mod tests {
         assert!(80 + unit_packets - 1 >= 100, "sanity: unit tails into seg");
         assert_eq!(
             unit_disposition(off, &segs, Some(5)),
-            UnitDisposition::Variant(5)
+            UnitDisposition::Index(5)
         );
     }
 }

src/aacs/mod.rs

@@ -29,6 +29,7 @@ pub mod content;
 pub mod crypto;
 pub mod derive;
 pub mod host_certs;
+pub mod index_select;
 pub mod inf;
 pub mod mkb;
 pub mod provider;
@@ -38,7 +39,6 @@ pub mod segment_key;
 pub mod trace;
 pub mod types;
 pub mod variant;
-pub mod variant_select;
 
 /// On-disc UDF paths to the AACS key-input files.
 ///
@@ -119,7 +119,7 @@ mod tests {
     //! Touching one representative item per module keeps these as a
     //! compile-time contract that the module paths stay stable.
 
-    use super::content::{ALIGNED_UNIT_LEN, ts_sync_destroyed};
+    use super::content::ALIGNED_UNIT_LEN;
     use super::inf::{disc_hash, disc_hash_hex};
     use super::mkb::{AacsVersion, mkb_content_len, walk_mkb};
     use super::variant::is_variant_mkb;
@@ -147,7 +147,10 @@ mod tests {
     fn public_helpers_are_callable_by_module_path() {
         // Touch a representative function from each module so a dropped/renamed
         // item fails to compile. Smoke calls, not behavioural assertions.
-        let _ = ts_sync_destroyed(&[0u8; ALIGNED_UNIT_LEN]);
+        let _ = !crate::aacs::content::is_clean(
+            &[0u8; ALIGNED_UNIT_LEN],
+            crate::disc::ContentFormat::BdTs,
+        );
         let _ = mkb_content_len(&[]);
         let _ = is_variant_mkb(&walk_mkb(&[]));
         let _ = disc_hash_hex(&disc_hash(b"x"));

src/aacs/resolve.rs

@@ -13,7 +13,6 @@ use super::mkb::*;
 // ── Full VUK resolution chain ───────────────────────────────────────────────
 
 /// Result of resolving a disc's VUK.
-#[derive(Debug)]
 pub struct ResolvedKeys {
     /// Disc hash (SHA1 of Unit_Key_RO.inf)
     pub disc_hash: [u8; 20],
@@ -34,6 +33,23 @@ pub struct ResolvedKeys {
     pub key_source: u8,
 }
 
+// Redacting `Debug`: `vuk` and `unit_keys` are raw key bytes, never printed.
+// `disc_hash` is the public per-disc identifier (SHA-1 of the .inf), not secret.
+// Guarded by `resolved_keys_debug_is_redacted`.
+impl std::fmt::Debug for ResolvedKeys {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("ResolvedKeys")
+            .field("disc_hash", &self.disc_hash)
+            .field("vuk", &self.vuk.map(|_| "<redacted>"))
+            .field("unit_keys_len", &self.unit_keys.len())
+            .field("title_cps_unit", &self.title_cps_unit)
+            .field("version", &self.version)
+            .field("bus_encryption", &self.bus_encryption)
+            .field("key_source", &self.key_source)
+            .finish()
+    }
+}
+
 /// Inputs shared by every classical-path resolver. References only —
 /// callers retain ownership of all buffers.
 pub struct ResolveContext<'a> {
@@ -467,6 +483,27 @@ mod tests {
     use super::super::types::*;
     use super::*;
 
+    /// `ResolvedKeys` carries the disc's VUK and unit keys raw; `Debug` must not
+    /// leak them. Sentinel 213 (0xD5); non-secret fields are not 213.
+    #[test]
+    fn resolved_keys_debug_is_redacted() {
+        let rk = ResolvedKeys {
+            disc_hash: [0u8; 20],
+            vuk: Some([0xD5; 16]),
+            unit_keys: vec![(1, [0xD5; 16])],
+            title_cps_unit: vec![0],
+            version: AacsVersion::V21,
+            bus_encryption: true,
+            key_source: 1,
+        };
+        let dbg = format!("{rk:?}");
+        assert!(!dbg.contains("213"), "ResolvedKeys leaked keys: {dbg}");
+        assert!(
+            dbg.contains("redacted"),
+            "ResolvedKeys missing marker: {dbg}"
+        );
+    }
+
     /// Audit #5: the `major` / `from_major` mapping is load-bearing for the
     /// Unit_Key_RO stride, so pin it as a table. V10 ↔ BD; V20/V21 → UHD; any
     /// non-BD major selects the V20/V21 64-byte stride (V10 is the only 48-byte).

src/aacs/segment.rs

@@ -1,61 +1,55 @@
 //! AACS 2.1 FMTS forensic segment map — `AACS/IndividualSegment.tbl`.
 //!
-//! An FMTS main feature interleaves N "variant" segments — the sequence-key /
-//! forensic-watermark mechanism. The same frames are authored as several
-//! slightly different variants; each variant is encrypted under its own SEGMENT
-//! key (from `SegmentKeyNNNNN.tbl`), NOT the CPS Unit Key. A player with the
-//! right device keys can decrypt exactly one variant per segment, and which one
-//! silently identifies the player (traitor tracing). Decrypting a variant
-//! segment with the Unit Key yields garbage — broken HEVC reference frames
-//! (empirically: `Could not find ref with POC …` on a plain unit-key rip).
+//! An FMTS main feature interleaves short forensic **segments** — the sequence-key
+//! / forensic-watermark mechanism. Each segment carries an **index** (1..32): a
+//! tag in `IndividualSegment.tbl` that selects which of the 32 forensic **index
+//! keys** decrypts that segment's units, in place of the ordinary CPS Unit Key.
 //!
-//! This table says WHERE the variant segments live so a decoder can decrypt
-//! them with segment keys and select one coherent variant instead of muxing
+//! Terminology (see the project AACS reference): the **index** here is NOT the
+//! AACS 2.1 *Media Key Variant* — that is the 65536-value device selector in the
+//! MKB that decides *which set* of index keys a device receives, a layer this
+//! module does not deal with. All the index keys belong to one variant, whose
+//! number is unknown and irrelevant to the segment map. Decrypting a segment with
+//! the Unit Key yields garbage — broken HEVC reference frames (empirically:
+//! `Could not find ref with POC …` on a plain unit-key rip).
+//!
+//! This table says WHERE the segments live and which index each carries, so a
+//! decoder can decrypt them with the matching index key instead of muxing
 //! unit-key garbage.
 //!
 //! Format (validated against a retail AACS 2.1 disc):
 //! ```text
 //!   header (8 bytes):  u32 type | u16 count | u16 record_size (= 16)
 //!   record[count] (16 bytes each):
-//!     u32 marker (= 0x01000000) | u16 variant | u16 flag (= 1)
+//!     u32 marker (= 0x01000000) | u16 index | u16 flag (= 1)
 //!     u32 start_spn | u32 end_spn        (source-packet numbers, inclusive)
 //! ```
-//! `variant` is the 1..32 forensic-variant tag, NOT a sequential segment id:
-//! measured on a retail 2.1 disc (Zombieland) it cycles 1,2,…,32,1,2,… across
-//! records in file order — 24 full cycles of 32 plus a final partial cycle of
-//! 24 = 792 records. Source-packet numbers are the 192-byte BDAV packet index:
-//! byte offset = `spn * 192`. Each segment is ~2560 packets (~480 KB), spread
-//! across the entire 54 GB feature (one roughly every 67 MB).
+//! `index` is the 1..32 forensic index tag, NOT a sequential segment id: measured
+//! on a retail 2.1 disc (Zombieland) it cycles 1,2,…,32,1,2,… across records in
+//! file order — 24 full cycles of 32 plus a final partial cycle of 24 = 792
+//! records. Source-packet numbers are the 192-byte BDAV packet index: byte offset
+//! = `spn * 192`. Each segment is ~2560 packets (~480 KB) = 80 aligned units,
+//! spread across the entire 54 GB feature (one roughly every 67 MB). Inside a
+//! segment the 80 units interleave in two stride-2 halves: applying the segment's
+//! index key decrypts ~40 of them to clean TS and garbles the other ~40 (a second
+//! interleaved half, unidentified), which the demux then drops — leaving one
+//! coherent stream. Confirmed by decoding a retail disc with a full set of 32
+//! index keys.
 
 /// Fixed size of one `IndividualSegment.tbl` record.
 pub const SEGMENT_RECORD_LEN: usize = 16;
 /// Bytes per BDAV source packet (188-byte TS + 4-byte arrival-time header).
 pub const SOURCE_PACKET_LEN: u64 = 192;
 
-/// Whether a 2.1 (FMTS) disc may rip WITHOUT segment (variant) keys.
-///
-/// `true` (today): the forensic variant segments are skipped as expected loss
-/// and the bulk of the title decodes with the unit key, so a 2.1 disc rips
-/// mostly-complete. A unit key (VUK) is still required, exactly as for any AACS
-/// disc. `false`: the absence of a segment-key source is a hard, UPFRONT failure
-/// ([`Error::FmtsKeyMissing`]) — the same policy as a missing unit key, so a
-/// forensic-holed rip is refused rather than produced. No segment-key source
-/// exists yet, so `true` is the only value under which a 2.1 disc rips at all;
-/// flip to `false` once segment keys can be sourced and a partial rip should be
-/// refused. Hardcoded on purpose — not a user setting.
-///
-/// [`Error::FmtsKeyMissing`]: crate::error::Error::FmtsKeyMissing
-pub const BYPASS_FMTS_KEY: bool = true;
-
-/// One forensic variant segment: the inclusive source-packet range it occupies
-/// in the FMTS clip.
+/// One forensic segment: the inclusive source-packet range it occupies in the
+/// FMTS clip.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct Segment {
-    /// Forensic variant tag, 1..=32 (field@4 of the record). Cycles across the
-    /// table rather than counting up — it selects WHICH variant this range is,
-    /// which is what a variant-keyed decode routes on. (`0` is not used here;
-    /// the default/non-forensic content carries no segment record at all.)
-    pub variant: u16,
+    /// Forensic index tag, 1..=32 (field@4 of the record). Cycles across the
+    /// table rather than counting up — it selects WHICH of the 32 index keys
+    /// decrypts this range. (`0` is not used here; the default/non-forensic
+    /// content carries no segment record at all.)
+    pub index: u16,
     /// First source packet of the segment (inclusive).
     pub start_spn: u32,
     /// Last source packet of the segment (inclusive).
@@ -109,8 +103,8 @@ pub fn lba_byte_offset(lba: u32) -> u64 {
 /// unit's clip-relative byte offset.
 ///
 /// This is the routing decision behind a 2.1 decrypt-miss: a unit that
-/// overlaps a forensic segment must be opened with that segment's **variant
-/// key** (from `SegmentKeyNNNNN.tbl`), not the CPS Unit Key. Opening it with
+/// overlaps a forensic segment must be opened with that segment's **index key**
+/// (selected by the segment's `index`), not the CPS Unit Key. Opening it with
 /// the Unit Key is exactly what yields the broken-reference-frame garbage a
 /// plain unit-key rip produces. A unit outside every segment is ordinary
 /// content and a miss on it is a Unit-Key miss, so this returns `None` and the
@@ -118,16 +112,16 @@ pub fn lba_byte_offset(lba: u32) -> u64 {
 ///
 /// The unit is tested as a packet *span* (`[off/192, (off+6144-1)/192]`) so a
 /// unit that only partly overlaps a segment edge is still classified as
-/// variant; on the observed disc segments are unit-aligned, but the span test
+/// forensic; on the observed disc segments are unit-aligned, but the span test
 /// does not rely on that.
-pub fn variant_segment_for_unit(segments: &[Segment], unit_offset: u64) -> Option<&Segment> {
+pub fn segment_for_unit(segments: &[Segment], unit_offset: u64) -> Option<&Segment> {
     let unit_len = crate::aacs::content::ALIGNED_UNIT_LEN as u64;
     let first = (unit_offset / SOURCE_PACKET_LEN) as u32;
     let last = ((unit_offset + unit_len - 1) / SOURCE_PACKET_LEN) as u32;
     segments.iter().find(|s| s.overlaps_spn(first, last))
 }
 
-/// Parse `IndividualSegment.tbl` into its forensic variant segments, in table
+/// Parse `IndividualSegment.tbl` into its forensic segments, in table
 /// order. Returns `None` when the header is malformed, the record size is not
 /// [`SEGMENT_RECORD_LEN`], or the declared record count overruns the buffer —
 /// so a truncated / foreign table degrades to "no segment map" rather than
@@ -147,12 +141,12 @@ pub fn parse_individual_segments(tbl: &[u8]) -> Option<Vec<Segment>> {
     let mut segments = Vec::with_capacity(count);
     for i in 0..count {
         let o = 8 + i * record_size;
-        // o+4..o+8 = variant (u16, 1..32) + flag (u16); o+8..o+16 = start/end SPN.
-        let variant = u16::from_be_bytes([tbl[o + 4], tbl[o + 5]]);
+        // o+4..o+8 = index (u16, 1..32) + flag (u16); o+8..o+16 = start/end SPN.
+        let index = u16::from_be_bytes([tbl[o + 4], tbl[o + 5]]);
         let start_spn = u32::from_be_bytes([tbl[o + 8], tbl[o + 9], tbl[o + 10], tbl[o + 11]]);
         let end_spn = u32::from_be_bytes([tbl[o + 12], tbl[o + 13], tbl[o + 14], tbl[o + 15]]);
         segments.push(Segment {
-            variant,
+            index,
             start_spn,
             end_spn,
         });
@@ -160,12 +154,74 @@ pub fn parse_individual_segments(tbl: &[u8]) -> Option<Vec<Segment>> {
     Some(segments)
 }
 
+/// Map a clip-relative byte offset to the absolute LBA that holds it, by walking
+/// the title's extents (the `.fmts` clip's sectors in file order). Segment
+/// offsets in [`Segment`] are clip-relative source-packet numbers, so this is how
+/// a segment's `spn` range becomes disc LBAs. `None` if the offset is past the
+/// clip.
+pub fn clip_byte_to_lba(extents: &[crate::disc::Extent], clip_byte: u64) -> Option<u32> {
+    let mut cum = 0u64;
+    for e in extents {
+        let len = e.sector_count as u64 * crate::consts::SECTOR_BYTES as u64;
+        if clip_byte < cum + len {
+            let sector_in_ext = ((clip_byte - cum) / crate::consts::SECTOR_BYTES as u64) as u32;
+            return Some(e.start_lba.saturating_add(sector_in_ext));
+        }
+        cum += len;
+    }
+    None
+}
+
+/// Build the `[start_lba, end_lba) → key_idx` ranges for an FMTS forensic key map.
+///
+/// Each forensic segment's clip-relative source-packet span becomes an absolute
+/// LBA range tagged with the key its `index` selects (via `index_to_key_idx`,
+/// e.g. `|i| i as usize` when the pool is `[base, idx1, idx2, …]`). Applying that
+/// one key across the whole segment decodes the ~40 units of its interleave half
+/// to clean TS and garbles the other ~40 (the second interleaved half), which the
+/// demux then drops — yielding one coherent stream. Ranges outside every segment
+/// are left for the map's default (the ordinary Unit Key). A segment that straddles
+/// a UDF extent boundary is emitted as one range per whole-sector slice it covers.
+///
+/// The result feeds [`AacsKeyMap::from_ranges`](crate::decrypt::AacsKeyMap::from_ranges)
+/// with the Unit-Key index as the default — the same structure the CPS map uses,
+/// only finer-grained.
+pub fn fmts_key_ranges(
+    segments: &[Segment],
+    extents: &[crate::disc::Extent],
+    index_to_key_idx: &dyn Fn(u16) -> usize,
+) -> Vec<(u32, u32, usize)> {
+    let mut ranges = Vec::new();
+    for s in segments {
+        let start_byte = s.start_spn as u64 * SOURCE_PACKET_LEN;
+        let end_byte = (s.end_spn as u64 + 1) * SOURCE_PACKET_LEN; // exclusive
+        // A segment is unit-aligned and contiguous in clip bytes; map its first
+        // and last sector to LBAs. Segments are ~480 KB and extents are GB-sized,
+        // so a segment almost never crosses an extent boundary — but if the two
+        // ends land in different extents (non-contiguous LBAs), skip rather than
+        // emit a wrong span; the units there fall to the Unit Key (garble+drop),
+        // never a mis-decrypt.
+        let (Some(a), Some(b)) = (
+            clip_byte_to_lba(extents, start_byte),
+            clip_byte_to_lba(extents, end_byte - 1),
+        ) else {
+            continue;
+        };
+        if b >= a
+            && (b - a) as u64 == (end_byte - 1 - start_byte) / crate::consts::SECTOR_BYTES as u64
+        {
+            ranges.push((a, b + 1, index_to_key_idx(s.index)));
+        }
+    }
+    ranges
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
 
     /// Build a table with the real on-disc layout: 8-byte header + N 16-byte
-    /// records. `recs` are `(variant, start_spn, end_spn)`.
+    /// records. `recs` are `(index, start_spn, end_spn)`.
     fn build_tbl(recs: &[(u16, u32, u32)]) -> Vec<u8> {
         let mut v = Vec::new();
         v.extend_from_slice(&0x0100_0000u32.to_be_bytes()); // type
@@ -181,11 +237,75 @@ mod tests {
         v
     }
 
+    #[test]
+    fn fmts_key_ranges_maps_segments_to_lba_by_index() {
+        use crate::disc::Extent;
+        // One big clip extent starting at LBA 1000. Clip byte B lives at
+        // LBA 1000 + B/2048.
+        let extents = vec![Extent {
+            start_lba: 1000,
+            sector_count: 1_000_000,
+        }];
+        // Two segments, indexes 5 and 7 (spn ranges as on a real disc).
+        let segs = vec![
+            Segment {
+                index: 5,
+                start_spn: 100,
+                end_spn: 199,
+            },
+            Segment {
+                index: 7,
+                start_spn: 10_000,
+                end_spn: 10_099,
+            },
+        ];
+        // Pool layout [base, idx1, idx2, …] → index N uses key slot N.
+        let ranges = fmts_key_ranges(&segs, &extents, &|v| v as usize);
+        assert_eq!(ranges.len(), 2, "one LBA range per segment");
+        // Segment 0: spn 100..=199 → clip bytes [19200, 38400) → sectors 9..=18
+        // → LBA 1009..1019, key index 5.
+        assert_eq!(ranges[0], (1009, 1019, 5));
+        // Segment 1: spn 10000..=10099 → bytes [1_920_000, 1_939_200) →
+        // sectors 937..=946 → LBA 1937..1947, key index 7.
+        assert_eq!(ranges[1], (1937, 1947, 7));
+
+        // The ranges drive an AacsKeyMap with the Unit Key (index 0) as default.
+        let map = crate::decrypt::AacsKeyMap::from_ranges(ranges, 0);
+        assert_eq!(map.key_idx_for(500), 0, "outside any segment → Unit Key");
+        assert_eq!(map.key_idx_for(1012), 5, "inside index-5 segment → key 5");
+        assert_eq!(map.key_idx_for(1940), 7, "inside index-7 segment → key 7");
+        assert_eq!(
+            map.key_idx_for(1019),
+            0,
+            "segment end is exclusive → Unit Key"
+        );
+    }
+
+    #[test]
+    fn clip_byte_to_lba_walks_extents() {
+        use crate::disc::Extent;
+        let extents = vec![
+            Extent {
+                start_lba: 100,
+                sector_count: 10,
+            }, // clip bytes [0, 20480)
+            Extent {
+                start_lba: 500,
+                sector_count: 10,
+            }, // clip bytes [20480, 40960)
+        ];
+        assert_eq!(clip_byte_to_lba(&extents, 0), Some(100));
+        assert_eq!(clip_byte_to_lba(&extents, 2048), Some(101));
+        assert_eq!(clip_byte_to_lba(&extents, 20480), Some(500)); // second extent
+        assert_eq!(clip_byte_to_lba(&extents, 22528), Some(501));
+        assert_eq!(clip_byte_to_lba(&extents, 40960), None); // past the clip
+    }
+
     #[test]
     fn parses_real_disc_layout() {
         // First three records observed on retail 2.1 (Zombieland): the variant
         // field counts 1,2,3,… (it wraps at 32 further into the table — see
-        // `variant_field_cycles_one_to_thirty_two`), segments are 2560 packets.
+        // `index_field_cycles_one_to_thirty_two`), segments are 2560 packets.
         let tbl = build_tbl(&[
             (1, 343680, 346239),
             (2, 695616, 698175),
@@ -193,9 +313,9 @@ mod tests {
         ]);
         let segs = parse_individual_segments(&tbl).expect("parse");
         assert_eq!(segs.len(), 3);
-        assert_eq!(segs[0].variant, 1);
-        assert_eq!(segs[1].variant, 2);
-        assert_eq!(segs[2].variant, 3);
+        assert_eq!(segs[0].index, 1);
+        assert_eq!(segs[1].index, 2);
+        assert_eq!(segs[2].index, 3);
         assert_eq!(segs[0].start_spn, 343680);
         assert_eq!(segs[0].end_spn, 346239);
         assert_eq!(segs[0].packet_count(), 2560);
@@ -234,18 +354,18 @@ mod tests {
     }
 
     #[test]
-    fn unit_inside_segment_routes_to_variant() {
+    fn unit_inside_segment_routes_to_index() {
         // A real first-record segment: packets [343680, 346239].
         let segs = parse_individual_segments(&build_tbl(&[(1, 343680, 346239)])).unwrap();
         // A unit sitting squarely inside: start at packet 344000 → byte 344000*192.
         let off = 344000u64 * SOURCE_PACKET_LEN;
-        let hit = variant_segment_for_unit(&segs, off).expect("inside the segment");
-        assert_eq!(hit.variant, 1);
+        let hit = segment_for_unit(&segs, off).expect("inside the segment");
+        assert_eq!(hit.index, 1);
     }
 
     #[test]
-    fn variant_field_cycles_one_to_thirty_two() {
-        // Reality on Zombieland: field@4 is the variant, cycling 1..=32 in file
+    fn index_field_cycles_one_to_thirty_two() {
+        // Reality on Zombieland: field@4 is the index, cycling 1..=32 in file
         // order (NOT a sequential segment id). Reproduce one-and-a-bit cycles.
         let mut recs = Vec::new();
         let mut spn = 1000u32;
@@ -258,9 +378,9 @@ mod tests {
         }
         let segs = parse_individual_segments(&build_tbl(&recs)).unwrap();
         assert_eq!(segs.len(), 64);
-        assert_eq!(segs[31].variant, 32); // end of first cycle
-        assert_eq!(segs[32].variant, 1); // wraps, does not become 33
-        assert!(segs.iter().all(|s| (1..=32).contains(&s.variant)));
+        assert_eq!(segs[31].index, 32); // end of first cycle
+        assert_eq!(segs[32].index, 1); // wraps, does not become 33
+        assert!(segs.iter().all(|s| (1..=32).contains(&s.index)));
     }
 
     #[test]
@@ -268,29 +388,29 @@ mod tests {
         let segs = parse_individual_segments(&build_tbl(&[(1, 343680, 346239)])).unwrap();
         // A unit well before the segment is ordinary content → None (unit-key path).
         let off = 1000u64 * SOURCE_PACKET_LEN;
-        assert!(variant_segment_for_unit(&segs, off).is_none());
+        assert!(segment_for_unit(&segs, off).is_none());
     }
 
     #[test]
-    fn unit_straddling_a_segment_edge_counts_as_variant() {
+    fn unit_straddling_a_segment_edge_counts_as_forensic() {
         // Segment starts at packet 100. A unit that ENDS just inside it (its 32
-        // packets straddle the boundary) must still route to the variant key,
-        // because part of its ciphertext is variant-encrypted.
+        // packets straddle the boundary) must still route to the index key,
+        // because part of its ciphertext is forensic-encrypted.
         let segs = parse_individual_segments(&build_tbl(&[(7, 100, 200)])).unwrap();
         // Unit covering packets [80, 111]: overlaps [100,200] at the tail.
         let off = 80u64 * SOURCE_PACKET_LEN;
-        let hit = variant_segment_for_unit(&segs, off).expect("straddles the start edge");
-        assert_eq!(hit.variant, 7);
+        let hit = segment_for_unit(&segs, off).expect("straddles the start edge");
+        assert_eq!(hit.index, 7);
         // A unit ending exactly at packet 99 (offset s.t. last = 99) does NOT overlap.
         let before = 68u64 * SOURCE_PACKET_LEN; // [68, 99]
-        assert!(variant_segment_for_unit(&segs, before).is_none());
+        assert!(segment_for_unit(&segs, before).is_none());
     }
 
     #[test]
-    fn no_segments_never_routes_to_variant() {
+    fn no_segments_never_routes_to_index() {
         // The 1.0 / 2.0 case: no forensic map, so every miss is a unit-key miss.
-        assert!(variant_segment_for_unit(&[], lba_byte_offset(0)).is_none());
-        assert!(variant_segment_for_unit(&[], lba_byte_offset(9_999_999)).is_none());
+        assert!(segment_for_unit(&[], lba_byte_offset(0)).is_none());
+        assert!(segment_for_unit(&[], lba_byte_offset(9_999_999)).is_none());
     }
 
     #[test]

src/aacs/types.rs

@@ -6,7 +6,7 @@
 //! owns only the crypto and these value types that flow through it.
 
 /// A device key for MKB subset-difference tree processing.
-#[derive(Debug, Clone)]
+#[derive(Clone)]
 pub struct DeviceKey {
     pub key: [u8; 16],
     pub node: u16,
@@ -15,7 +15,7 @@ pub struct DeviceKey {
 }
 
 /// Host certificate + private key for AACS SCSI authentication.
-#[derive(Debug, Clone)]
+#[derive(Clone)]
 pub struct HostCert {
     /// AACS 1.0: 20 bytes. AACS 2.0: 32 bytes.
     pub private_key: [u8; 20],
@@ -28,22 +28,22 @@ pub struct HostCert {
 }
 
 /// Volume ID (16 bytes) — read from the disc via the SCSI handshake / OEM path.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[derive(Clone, Copy, PartialEq, Eq)]
 pub struct Vid(pub [u8; 16]);
 
 /// Media Key (Km, 16 bytes) — the MKB-scoped key derived from device keys.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[derive(Clone, Copy, PartialEq, Eq)]
 pub struct MediaKey(pub [u8; 16]);
 
 /// Volume Unique Key (VUK / Kvu, 16 bytes) — derived from `MediaKey` + `Vid`,
 /// decrypts the per-disc encrypted title keys in `Unit_Key_RO.inf`.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[derive(Clone, Copy, PartialEq, Eq)]
 pub struct Vuk(pub [u8; 16]);
 
 /// Processing Key (Kp, 16 bytes) — an MKB Subset-Difference key that yields the
 /// Media Key. A leaked/precomputed PK in the keydb, or the intermediate PK a
 /// device-key walk derives at its matching SD node.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[derive(Clone, Copy, PartialEq, Eq)]
 pub struct ProcessingKey(pub [u8; 16]);
 
 /// One decrypted per-CPS-unit AACS title key.
@@ -53,50 +53,49 @@ pub struct ProcessingKey(pub [u8; 16]);
 /// area). The CPS-unit *number* association is a higher-level concern owned by
 /// [`super::inf::parse_unit_key_ro`], which pairs each positional key with its
 /// declared CPS unit; this primitive only does the AES, so it surfaces position.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[derive(Clone, Copy, PartialEq, Eq)]
 pub struct UnitKey {
     pub idx: u32,
     pub key: [u8; 16],
-    /// AACS 2.1 (FMTS) forensic-variant tag.
+    /// AACS 2.1 (FMTS) forensic **index** tag (see [`crate::aacs::segment`]).
     ///
     /// `0` = ordinary (non-forensic) content — the value for every 1.0 / 2.0
-    /// key and for the bulk of a 2.1 title. `1..=32` = a variant key that
-    /// decrypts the forensic segments tagged with that same variant in
-    /// `IndividualSegment.tbl`. A disc resolves to exactly one variant, so at
-    /// most one non-zero value is ever in play for a given rip; the decode
-    /// selects the segments matching it and drops the other variants.
-    pub variant_number: u8,
+    /// key and for the bulk of a 2.1 title. `1..=32` = a forensic index key that
+    /// decrypts the `IndividualSegment.tbl` segments tagged with that same index.
+    /// This is the per-segment index (1..32), NOT the AACS 2.1 Media Key Variant
+    /// (the 65536-value device selector), which is a separate MKB-layer concern.
+    pub index_number: u8,
 }
 
 impl UnitKey {
-    /// An ordinary (non-forensic) unit key: `variant_number == 0`. The value
+    /// An ordinary (non-forensic) unit key: `index_number == 0`. The value
     /// for every AACS 1.0 / 2.0 key and the bulk of a 2.1 title.
     pub const fn new(idx: u32, key: [u8; 16]) -> Self {
         Self {
             idx,
             key,
-            variant_number: 0,
+            index_number: 0,
         }
     }
 
-    /// A forensic-variant key: `variant_number` in `1..=32`, decrypting the
-    /// `IndividualSegment.tbl` segments tagged with that variant.
-    pub const fn variant(idx: u32, key: [u8; 16], variant_number: u8) -> Self {
+    /// A forensic index key: `index_number` in `1..=32`, decrypting the
+    /// `IndividualSegment.tbl` segments tagged with that index.
+    pub const fn forensic(idx: u32, key: [u8; 16], index_number: u8) -> Self {
         Self {
             idx,
             key,
-            variant_number,
+            index_number,
         }
     }
 
-    /// Whether this key decrypts ordinary (non-forensic) content.
-    pub const fn is_default_variant(&self) -> bool {
-        self.variant_number == 0
+    /// Whether this key decrypts ordinary (non-forensic) content (index 0).
+    pub const fn is_default_index(&self) -> bool {
+        self.index_number == 0
     }
 }
 
 /// A per-disc entry from the key database.
-#[derive(Debug, Clone)]
+#[derive(Clone)]
 pub struct DiscEntry {
     /// Disc hash (20 bytes, hex)
     pub disc_hash: String,
@@ -111,3 +110,158 @@ pub struct DiscEntry {
     /// Unit keys (title keys) indexed by CPS unit number
     pub unit_keys: Vec<(u32, [u8; 16])>,
 }
+
+// ── Redacting `Debug` impls ──────────────────────────────────────────────────
+//
+// Every type above carries AACS secret material (device keys, host PRIVATE keys,
+// media/volume/processing/unit keys). `#[derive(Debug)]` would print those bytes
+// verbatim, so a stray `debug!("{:?}", …)` or a panic message would leak the
+// keys. These hand-written impls print only NON-secret shape (presence, lengths,
+// tree coordinates, indices) — never key bytes. `decrypt::DecryptKeys` follows
+// the same policy by omitting `Debug` entirely; here we keep `Debug` because
+// these are `PartialEq`/`Eq` value types used in `assert_eq!` and nested inside
+// other `#[derive(Debug)]` structs, so the trait must exist — just not leak.
+// Guarded by `redaction_tests` below.
+
+impl std::fmt::Debug for DeviceKey {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("DeviceKey")
+            .field("key", &"<redacted>")
+            .field("node", &self.node)
+            .field("uv", &self.uv)
+            .field("u_mask_shift", &self.u_mask_shift)
+            .finish()
+    }
+}
+
+impl std::fmt::Debug for HostCert {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("HostCert")
+            .field("private_key", &"<redacted>")
+            .field("certificate_len", &self.certificate.len())
+            .field("private_key_v2", &self.private_key_v2.map(|_| "<redacted>"))
+            .field(
+                "certificate_v2_len",
+                &self.certificate_v2.as_ref().map(|c| c.len()),
+            )
+            .finish()
+    }
+}
+
+impl std::fmt::Debug for Vid {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str("Vid(<redacted>)")
+    }
+}
+
+impl std::fmt::Debug for MediaKey {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str("MediaKey(<redacted>)")
+    }
+}
+
+impl std::fmt::Debug for Vuk {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str("Vuk(<redacted>)")
+    }
+}
+
+impl std::fmt::Debug for ProcessingKey {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str("ProcessingKey(<redacted>)")
+    }
+}
+
+impl std::fmt::Debug for UnitKey {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("UnitKey")
+            .field("idx", &self.idx)
+            .field("key", &"<redacted>")
+            .field("index_number", &self.index_number)
+            .finish()
+    }
+}
+
+impl std::fmt::Debug for DiscEntry {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("DiscEntry")
+            .field("disc_hash", &self.disc_hash)
+            .field("title", &self.title)
+            .field("media_key", &self.media_key.map(|_| "<redacted>"))
+            .field("disc_id", &self.disc_id.map(|_| "<redacted>"))
+            .field("vuk", &self.vuk.map(|_| "<redacted>"))
+            .field("unit_keys_len", &self.unit_keys.len())
+            .finish()
+    }
+}
+
+#[cfg(test)]
+mod redaction_tests {
+    use super::*;
+
+    // Sentinel key byte 0xD5 = decimal 213. A derived `Debug` prints `[u8;N]`
+    // as decimal, so a leaked key surfaces the substring "213"; the redacting
+    // impls must not. No non-secret field below is 213, so "213" appearing means
+    // key bytes leaked. Each type must also carry a "redacted" marker (or omit
+    // the secret entirely) so re-adding `#[derive(Debug)]` fails this test.
+    const S: u8 = 0xD5;
+
+    fn assert_redacted(what: &str, dbg: &str) {
+        assert!(
+            !dbg.contains("213"),
+            "{what}: Debug leaked key bytes (found decimal 213): {dbg}"
+        );
+        assert!(
+            dbg.contains("redacted"),
+            "{what}: Debug missing redaction marker: {dbg}"
+        );
+    }
+
+    #[test]
+    fn device_key_debug_is_redacted() {
+        let d = DeviceKey {
+            key: [S; 16],
+            node: 1,
+            uv: 2,
+            u_mask_shift: 3,
+        };
+        assert_redacted("DeviceKey", &format!("{d:?}"));
+    }
+
+    #[test]
+    fn host_cert_debug_is_redacted() {
+        let h = HostCert {
+            private_key: [S; 20],
+            certificate: vec![0u8; 92],
+            private_key_v2: Some([S; 32]),
+            certificate_v2: None,
+        };
+        assert_redacted("HostCert", &format!("{h:?}"));
+    }
+
+    #[test]
+    fn newtype_keys_debug_is_redacted() {
+        assert_redacted("Vid", &format!("{:?}", Vid([S; 16])));
+        assert_redacted("MediaKey", &format!("{:?}", MediaKey([S; 16])));
+        assert_redacted("Vuk", &format!("{:?}", Vuk([S; 16])));
+        assert_redacted("ProcessingKey", &format!("{:?}", ProcessingKey([S; 16])));
+    }
+
+    #[test]
+    fn unit_key_debug_is_redacted() {
+        assert_redacted("UnitKey", &format!("{:?}", UnitKey::new(0, [S; 16])));
+    }
+
+    #[test]
+    fn disc_entry_debug_is_redacted() {
+        let e = DiscEntry {
+            disc_hash: "0xAA".into(),
+            title: "T".into(),
+            media_key: Some([S; 16]),
+            disc_id: Some([S; 16]),
+            vuk: Some([S; 16]),
+            unit_keys: vec![(1, [S; 16])],
+        };
+        assert_redacted("DiscEntry", &format!("{e:?}"));
+    }
+}

src/aacs/variant.rs

@@ -146,7 +146,7 @@ use super::derive::{calc_pk_from_dk, calc_v_mask};
 /// Outcome of a subset-difference walk against an MKB. Carries the
 /// processing key and the matching `uv` slot — both needed as inputs
 /// to the variant chain.
-#[derive(Debug, Clone, Copy)]
+#[derive(Clone, Copy)]
 pub struct ProcessingKeyMatch {
     /// Processing Key.
     pub kp: [u8; 16],
@@ -158,6 +158,20 @@ pub struct ProcessingKeyMatch {
     pub cvalue_index: usize,
 }
 
+// Redacting `Debug`: `kp` (a Processing Key) and `cvalue` are secret, never
+// printed. `uv` / `cvalue_index` are non-secret coordinates. Guarded by
+// `processing_key_match_debug_is_redacted`.
+impl std::fmt::Debug for ProcessingKeyMatch {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("ProcessingKeyMatch")
+            .field("kp", &"<redacted>")
+            .field("uv", &self.uv)
+            .field("cvalue", &"<redacted>")
+            .field("cvalue_index", &self.cvalue_index)
+            .finish()
+    }
+}
+
 fn mkb_find_mk_dv(records: &[MkbRecord]) -> Option<[u8; 16]> {
     let r = records.iter().find(|r| {
         (r.rec_type == REC_VERIFY_MEDIA_KEY_V1 || r.rec_type == REC_VERIFY_MEDIA_KEY_V2)
@@ -635,6 +649,27 @@ mod tests {
     use super::super::crypto::aesg3;
     use super::super::derive::calc_pk_from_dk;
 
+    /// `ProcessingKeyMatch` carries the Processing Key (`kp`) and `cvalue` raw;
+    /// `Debug` must redact both. Non-secret `uv`/`cvalue_index` are not 213.
+    #[test]
+    fn processing_key_match_debug_is_redacted() {
+        let m = ProcessingKeyMatch {
+            kp: [0xD5; 16],
+            uv: 1,
+            cvalue: [0xD5; 16],
+            cvalue_index: 2,
+        };
+        let dbg = format!("{m:?}");
+        assert!(
+            !dbg.contains("213"),
+            "ProcessingKeyMatch leaked kp/cvalue: {dbg}"
+        );
+        assert!(
+            dbg.contains("redacted"),
+            "ProcessingKeyMatch missing marker: {dbg}"
+        );
+    }
+
     #[test]
     fn calc_pk_from_dk_terminates_on_nonconvergent_mask() {
         // Regression for the unbounded-loop hang: pick a (dev_key_v_mask,

src/css/mod.rs

@@ -29,7 +29,7 @@ use crate::sector::SectorSource;
 const CSS_LOCKED_BAIL: u32 = 64;
 
 /// CSS decryption state for a DVD title.
-#[derive(Debug, Clone)]
+#[derive(Clone)]
 pub struct CssState {
     /// 5-byte CSS title key (from SCSI auth or the crack fallback).
     pub title_key: [u8; 5],
@@ -43,6 +43,18 @@ pub struct CssState {
     pub crack_span: Option<(u32, u32)>,
 }
 
+// Redacting `Debug`: `CssState` is reachable via the public `Disc.css` field, so
+// a `{:?}` on a `Disc` would otherwise print the raw CSS title key. Print only
+// the (non-secret) crack span. Guarded by `css_state_debug_is_redacted`.
+impl std::fmt::Debug for CssState {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("CssState")
+            .field("title_key", &"<redacted>")
+            .field("crack_span", &self.crack_span)
+            .finish()
+    }
+}
+
 /// Recover the CSS title key with no keys, by scanning scrambled sectors and
 /// running the Stevenson known-plaintext attack (see the [`stevenson`] module).
 ///
@@ -54,12 +66,16 @@ pub struct CssState {
 /// extents and return the first sector that yields a key — no player keys, no
 /// disc-key crack. Works on a live drive (after bus-auth unlocks reads) and on
 /// disc images alike.
+/// This convenience form runs to completion (no cancellation) and returns just
+/// the key; callers needing an operator-Stop / watchdog cancel, or the three-way
+/// [`CrackOutcome`] (to distinguish "unencrypted" from "encrypted-but-uncracked"),
+/// use [`crack_key_outcome`], which takes a `halt` token.
 pub fn crack_key(
     reader: &mut dyn SectorSource,
     extents: &[Extent],
     batch_sectors: u16,
 ) -> Option<CssState> {
-    crack_key_halt(reader, extents, batch_sectors, None)
+    crack_key_scan(reader, extents, batch_sectors, None, false).into_state()
 }
 
 /// Outcome of a CSS crack scan that distinguishes the THREE cases the bare
@@ -105,6 +121,12 @@ impl CrackOutcome {
 /// ScrambledUncracked) so callers can distinguish "genuinely unencrypted" from
 /// "encrypted but uncrackable" — the latter must become a hard error, never a
 /// silent fall-through to plaintext.
+///
+/// Takes an optional cooperative-cancellation token. "No silent hangs": the
+/// crack scans up to 50_000 sectors, which on a live drive hitting bad sectors
+/// can take a long time, so it polls `halt` once per batch (the same cadence
+/// sweep/patch use) and emits a `freemkv::heartbeat` beat ("css_crack") each
+/// batch so a stuck scan is visible in the log.
 pub fn crack_key_outcome(
     reader: &mut dyn SectorSource,
     extents: &[Extent],
@@ -114,27 +136,10 @@ pub fn crack_key_outcome(
     crack_key_scan(reader, extents, batch_sectors, halt, true)
 }
 
-/// [`crack_key`] with an optional cooperative-cancellation token.
-///
-/// "No silent hangs": the crack scans up to 50_000 sectors, which on a live
-/// drive hitting bad sectors can take a long time. This variant polls `halt`
-/// once per batch (the same cadence sweep/patch use) so an operator Stop or a
-/// scan-level watchdog can interrupt the scan, and emits a
-/// `freemkv::heartbeat` beat ("css_crack") each batch so a stuck scan is
-/// visible in the log.
-pub fn crack_key_halt(
-    reader: &mut dyn SectorSource,
-    extents: &[Extent],
-    batch_sectors: u16,
-    halt: Option<&crate::halt::Halt>,
-) -> Option<CssState> {
-    crack_key_scan(reader, extents, batch_sectors, halt, false).into_state()
-}
-
 /// The crack scan, returning the full [`CrackOutcome`]. Tracks a
 /// `saw_scrambled` flag so a scrambled-but-uncracked disc is distinguished
-/// from a genuinely-unencrypted one (the [`crack_key`] / [`crack_key_halt`]
-/// `Option` wrappers collapse both to `None`).
+/// from a genuinely-unencrypted one (the [`crack_key`] `Option` wrapper
+/// collapses both to `None` via [`CrackOutcome::into_state`]).
 fn crack_key_scan(
     reader: &mut dyn SectorSource,
     extents: &[Extent],
@@ -364,6 +369,26 @@ mod tests {
     use super::*;
     use crate::error::{Error, Result};
 
+    /// `CssState` is reachable via the public `Disc.css` field, so a `{:?}` on a
+    /// `Disc` must not print the raw CSS title key. Sentinel byte 213 (0xD5);
+    /// `crack_span` is non-secret and none of its values are 213.
+    #[test]
+    fn css_state_debug_is_redacted() {
+        let s = CssState {
+            title_key: [0xD5; 5],
+            crack_span: Some((10, 20)),
+        };
+        let dbg = format!("{s:?}");
+        assert!(
+            !dbg.contains("213"),
+            "CssState Debug leaked the title key: {dbg}"
+        );
+        assert!(
+            dbg.contains("redacted"),
+            "CssState Debug missing marker: {dbg}"
+        );
+    }
+
     // ── is_scrambled ───────────────────────────────────────────────────────
 
     /// is_scrambled returns false for any buffer shorter than one sector,

src/decrypt.rs

@@ -171,6 +171,330 @@ impl DecryptKeys {
     }
 }
 
+/// Proactive AACS key-selection map: which held unit key decrypts each LBA of a
+/// title's encrypted content, decided ONCE before mux from the disc's CPS-unit
+/// (and, later, FMTS segment) structure — never by trial-decrypt-and-check per
+/// unit at mux time.
+///
+/// This is the pivot that ends the mux "key-server storm": the old path decrypts
+/// a unit, checks whether the plaintext looks like clean MPEG-TS, and — because
+/// authored-bad content never reaches that bar — concludes "wrong key, fetch a
+/// fresh one" and re-asks the key service for units it already holds the correct
+/// key for. There is NO per-unit byte pattern that separates "correctly decrypted
+/// but authored-bad" from "still encrypted", so that check is unanswerable. The
+/// map removes the question: we resolve one key per CPS unit / segment up front
+/// (see `resolve_mux_key_map`), record which LBA ranges each covers, and at mux
+/// time simply "decrypt this LBA with key K" and trust it — bad TS is the muxer's
+/// concern, exactly as for a physically-read clear disc.
+///
+/// Ranges are `[start_lba, end_lba)` → index into the `Aacs { unit_keys }` pool,
+/// sorted and disjoint. `default_idx` covers any LBA no range claims — the
+/// single-CPS case is just an empty range list with `default_idx = 0`, so the
+/// common disc pays zero lookup cost and needs no structural walk.
+/// Which aligned units of a range a key decrypts. AACS 2.1 FMTS forensic segments
+/// interleave TWO variants at the unit level; `Even`/`Odd` selects the variant's
+/// half (parity of the unit's index within the segment) and the ALTERNATE half is
+/// left untouched (ciphertext) for the muxer to drop. Every non-forensic range —
+/// the base Unit Key, a multi-CPS unit — is `All` (decrypt every unit), so the
+/// common disc is byte-for-byte unchanged.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Phase {
+    All,
+    Even,
+    Odd,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct AacsKeyMap {
+    // (start_lba, end_lba, key_idx, phase)
+    ranges: Vec<(u32, u32, usize, Phase)>,
+    default_idx: usize,
+}
+
+impl AacsKeyMap {
+    /// The whole title is one CPS unit → one key (`idx`) everywhere. This is the
+    /// overwhelmingly common disc (incl. every single-CPS UHD); no LBA walk.
+    pub fn single(idx: usize) -> Self {
+        Self {
+            ranges: Vec::new(),
+            default_idx: idx,
+        }
+    }
+
+    /// Build from `[start_lba, end_lba) → key_idx` ranges that decrypt EVERY unit
+    /// (multi-CPS): each range is [`Phase::All`]. `default_idx` answers any
+    /// uncovered LBA. Byte-for-byte identical behaviour to before phases existed.
+    pub fn from_ranges(ranges: Vec<(u32, u32, usize)>, default_idx: usize) -> Self {
+        let phased = ranges
+            .into_iter()
+            .map(|(s, e, i)| (s, e, i, Phase::All))
+            .collect();
+        Self::from_ranges_phased(phased, default_idx)
+    }
+
+    /// Build a PHASE-AWARE map (FMTS): each range carries which unit-parity its key
+    /// opens ([`Phase::Even`]/[`Phase::Odd`] for a forensic segment, [`Phase::All`]
+    /// for base/CPS). Ranges are sorted; `default_idx` answers any uncovered LBA.
+    pub fn from_ranges_phased(
+        mut ranges: Vec<(u32, u32, usize, Phase)>,
+        default_idx: usize,
+    ) -> Self {
+        ranges.sort_by_key(|&(start, _, _, _)| start);
+        Self {
+            ranges,
+            default_idx,
+        }
+    }
+
+    /// The `(key_idx, phase, range_start_lba)` for the aligned unit at `lba`.
+    /// O(log n) — the last range whose start is `<= lba` and whose end is `> lba`,
+    /// else `(default_idx, All, 0)`. `range_start_lba` lets the mapped decrypt
+    /// compute a unit's parity WITHIN a forensic segment (for `Even`/`Odd`).
+    pub fn entry_for(&self, lba: u32) -> (usize, Phase, u32) {
+        if self.ranges.is_empty() {
+            return (self.default_idx, Phase::All, 0);
+        }
+        match self
+            .ranges
+            .binary_search_by(|&(start, _, _, _)| start.cmp(&lba))
+        {
+            Ok(i) => {
+                let (start, _, idx, ph) = self.ranges[i];
+                (idx, ph, start)
+            }
+            Err(0) => (self.default_idx, Phase::All, 0),
+            Err(i) => {
+                let (start, end, idx, ph) = self.ranges[i - 1];
+                if lba >= start && lba < end {
+                    (idx, ph, start)
+                } else {
+                    (self.default_idx, Phase::All, 0)
+                }
+            }
+        }
+    }
+
+    /// The unit-key index for the aligned unit at `lba` (phase-agnostic; see
+    /// [`entry_for`](Self::entry_for) for the phase). Cheap per-unit hot-path call.
+    pub fn key_idx_for(&self, lba: u32) -> usize {
+        self.entry_for(lba).0
+    }
+
+    /// The `[start_lba, end_lba) → (key_idx, phase)` ranges (sorted, disjoint).
+    /// Empty for a single-CPS map (everything uses [`default_idx`](Self::default_idx)).
+    pub fn ranges(&self) -> &[(u32, u32, usize, Phase)] {
+        &self.ranges
+    }
+
+    /// The key index for any LBA no explicit range claims (the single-CPS key).
+    pub fn default_idx(&self) -> usize {
+        self.default_idx
+    }
+
+    /// The distinct key indices this map can select — the CPS units / segments a
+    /// title actually reaches. Used by the resolver to know which keys to secure
+    /// up front.
+    pub fn key_indices(&self) -> Vec<usize> {
+        let mut v: Vec<usize> = self.ranges.iter().map(|&(_, _, i, _)| i).collect();
+        v.push(self.default_idx);
+        v.sort_unstable();
+        v.dedup();
+        v
+    }
+
+    /// Build the FMTS **read plan**: the title's aligned units filtered down to
+    /// only the units this rip must actually read — every default / CPS unit,
+    /// plus, inside each forensic segment, ONLY our-phase ([`Phase::Even`] /
+    /// [`Phase::Odd`]) units. The alternate-phase units are a different device
+    /// group's variant: a licensed player never reads them, and neither do we.
+    /// They are omitted from the plan entirely, so they are never fetched,
+    /// decrypted, or handed to the demux — the demux therefore sees one gapless
+    /// our-variant stream, with no ciphertext to trip a concealed-gap resync (the
+    /// old behaviour that dropped good frames around every segment).
+    ///
+    /// `extents` are the title's clip extents (unit-aligned in the interior;
+    /// a shorter tail is ordinary content and always kept). `unit_sectors` is the
+    /// AACS aligned-unit size in sectors (3). Contiguous kept units coalesce into
+    /// as few extents as possible so the producer still issues large sequential
+    /// reads across default content; only inside a ~480 KB forensic segment do
+    /// reads become unit-granular (every other unit). A map with no forensic
+    /// (Even/Odd) range returns `extents` unchanged — the common disc is not
+    /// touched.
+    ///
+    /// The parity test is byte-identical to the decrypt hot loop
+    /// (`(unit_lba - range_start) / unit_sectors`), so a unit kept here is exactly
+    /// a unit [`decrypt_sectors_mapped`] would open, and vice-versa.
+    pub fn read_plan(
+        &self,
+        extents: &[crate::disc::Extent],
+        unit_sectors: u32,
+    ) -> Vec<crate::disc::Extent> {
+        // No forensic segment → read everything, unchanged (byte-for-byte).
+        if !self
+            .ranges
+            .iter()
+            .any(|&(_, _, _, p)| matches!(p, Phase::Even | Phase::Odd))
+        {
+            return extents.to_vec();
+        }
+        let us = unit_sectors.max(1);
+        let mut plan: Vec<crate::disc::Extent> = Vec::new();
+        // Append `sectors` at `lba`, coalescing with the previous extent when they
+        // are physically contiguous so default runs stay one big sequential read.
+        let mut push = |lba: u32, sectors: u32| {
+            if sectors == 0 {
+                return;
+            }
+            if let Some(last) = plan.last_mut() {
+                if last.start_lba.saturating_add(last.sector_count) == lba {
+                    last.sector_count += sectors;
+                    return;
+                }
+            }
+            plan.push(crate::disc::Extent {
+                start_lba: lba,
+                sector_count: sectors,
+            });
+        };
+        for e in extents {
+            let mut off = 0u32;
+            while off < e.sector_count {
+                let lba = e.start_lba.saturating_add(off);
+                let remaining = e.sector_count - off;
+                if remaining < us {
+                    // Extent tail shorter than a whole unit: ordinary content
+                    // (nothing follows to desync), always read.
+                    push(lba, remaining);
+                    break;
+                }
+                let (_, phase, range_start) = self.entry_for(lba);
+                let keep = match phase {
+                    Phase::All => true,
+                    Phase::Even | Phase::Odd => {
+                        let unit_ix = (lba - range_start) / us;
+                        let is_odd = unit_ix % 2 == 1;
+                        is_odd == matches!(phase, Phase::Odd)
+                    }
+                };
+                if keep {
+                    push(lba, us);
+                }
+                off += us;
+            }
+        }
+        plan
+    }
+}
+
+/// Decrypt a buffer of sectors in-place using a resolved [`AacsKeyMap`] — the
+/// mux's TRUSTED decrypt. `base_lba` is the absolute LBA of `buf`'s first sector;
+/// each aligned unit (3 sectors) is decrypted with the key the map assigns to its
+/// LBA. There is NO key trial and NO `is_clean` verdict: the map already decided
+/// the key from disc structure, so we apply it and move on — a unit that decrypts
+/// to authored-bad TS passes through for the muxer to drop, never re-fetched.
+///
+/// Only [`DecryptKeys::Aacs`] uses a map (CSS self-cracks per region inside
+/// [`decrypt_sectors`]; `None` is clear) — other variants are a no-op here so the
+/// decorator can dispatch uniformly. A map index outside the held pool is a
+/// fail-loud [`Error::DecryptFailed`]: the resolver's job is to guarantee every
+/// selectable index is present, so a gap here is a resolver bug, not silent loss.
+pub fn decrypt_sectors_mapped(
+    buf: &mut [u8],
+    keys: &DecryptKeys,
+    base_lba: u32,
+    map: &AacsKeyMap,
+) -> Result<(), crate::error::Error> {
+    let (unit_keys, rdk, format) = match keys {
+        DecryptKeys::Aacs {
+            unit_keys,
+            read_data_key,
+            format,
+        } => (unit_keys, *read_data_key, *format),
+        // Clear / CSS: the mapped path is AACS-only. Leave the buffer untouched;
+        // CSS descrambles via `decrypt_sectors` and `None` is already clear.
+        _ => return Ok(()),
+    };
+
+    let unit_len = aacs::content::ALIGNED_UNIT_LEN;
+    let unit_sectors = (unit_len / 2048) as u32;
+
+    // Validate every selectable index up front (fail loud) so the per-unit hot
+    // loop can index without bounds churn and a resolver gap never silently
+    // passes ciphertext through as "decrypted".
+    for idx in map.key_indices() {
+        if unit_keys.get(idx).is_none() {
+            return Err(crate::error::Error::DecryptFailed);
+        }
+    }
+
+    // Cheap safety net for the "map must be right" model: with a correct
+    // phase-aware map, every CORRECT-PHASE forensic unit decrypts to clean TS, so
+    // this never fires in the happy path — but a map bug (wrong phase/key for a
+    // segment) surfaces as a loud DecryptFailed instead of silent corruption. Only
+    // forensic (Even/Odd) ranges are verified; base / multi-CPS (All) stays
+    // trust-only, so the common disc is byte-for-byte unchanged.
+    let verify_failed = std::sync::atomic::AtomicBool::new(false);
+
+    let decrypt_one = |idx_in_buf: usize, chunk: &mut [u8]| {
+        if chunk.len() != unit_len {
+            return; // trailing partial unit: clear tail on disc, leave as-is
+        }
+        let unit_lba = base_lba.saturating_add((idx_in_buf as u32) * unit_sectors);
+        let (key_idx, phase, range_start) = map.entry_for(unit_lba);
+        // PHASE GATE (FMTS forensic segment): the segment interleaves two variants
+        // at the unit level. Decrypt ONLY our parity; leave the alternate half as
+        // ciphertext (the muxer drops untouched ciphertext cleanly — no garble).
+        if matches!(phase, Phase::Even | Phase::Odd) {
+            let unit_ix = (unit_lba - range_start) / unit_sectors;
+            let is_odd = unit_ix % 2 == 1;
+            if is_odd != matches!(phase, Phase::Odd) {
+                return; // alternate half — leave as-is
+            }
+        }
+        // Gate on the authoritative encrypted flag ONLY (CPI bits in the clear
+        // seed): a clear unit is left untouched; an encrypted unit is decrypted
+        // with its MAPPED key and trusted.
+        if !aacs::content::aacs_unit_encrypted(chunk, format) {
+            return;
+        }
+        // Bounds already proven above; index directly.
+        let key = &unit_keys[key_idx].1;
+        if let Some(ref rdk_key) = rdk {
+            aacs::content::decrypt_bus(chunk, rdk_key);
+        }
+        aacs::content::decrypt_unit(chunk, key);
+        // Correct-phase forensic verify (silent unless the map is wrong).
+        if matches!(phase, Phase::Even | Phase::Odd) && !aacs::content::is_clean(chunk, format) {
+            verify_failed.store(true, std::sync::atomic::Ordering::Relaxed);
+        }
+    };
+
+    let nthreads = decrypt_threads();
+    let nunits = buf.len() / unit_len;
+    if nthreads <= 1 || nunits < PARALLEL_MIN_UNITS {
+        for (i, chunk) in buf.chunks_mut(unit_len).enumerate() {
+            decrypt_one(i, chunk);
+        }
+    } else {
+        match decrypt_pool() {
+            Some(pool) => pool.install(|| {
+                buf.par_chunks_mut(unit_len)
+                    .enumerate()
+                    .for_each(|(i, chunk)| decrypt_one(i, chunk));
+            }),
+            None => {
+                for (i, chunk) in buf.chunks_mut(unit_len).enumerate() {
+                    decrypt_one(i, chunk);
+                }
+            }
+        }
+    }
+    if verify_failed.load(std::sync::atomic::Ordering::Relaxed) {
+        return Err(crate::error::Error::DecryptFailed);
+    }
+    Ok(())
+}
+
 /// Decrypt a buffer of sectors in-place.
 ///
 /// For AACS: processes in 6144-byte aligned units (3 sectors).
@@ -286,7 +610,7 @@ fn decrypt_sectors_impl(
             //     silent corruption. We fail loud (Error::DecryptFailed), matching
             //     the highway path's Error::ExtentNotUnitAligned policy.
             //
-            // Detection: ts_sync_destroyed() short-circuits to false for any
+            // Detection: !crate::aacs::content::is_clean(, crate::disc::ContentFormat::BdTs) short-circuits to false for any
             // buffer shorter than a full unit, so it cannot judge a partial. We
             // instead apply the same TS-sync-intactness test it uses internally
             // (ts_sync_count vs ts_packet_total) directly to the available
@@ -308,15 +632,13 @@ fn decrypt_sectors_impl(
                     None => true,
                 };
                 // TS-only: a scrambled trailing PARTIAL unit (< a full 6144-byte
-                // unit) can't be unit-decrypted, so fail loud. The heuristic is
-                // MPEG-TS sync density, which a PS (`.evo`) partial lacks entirely —
-                // running it on PS would false-trip `DecryptFailed`. HD-DVD partial-
-                // scramble detection is not yet wired (consistent with the UNVERIFIED
-                // PS path in `aacs_unit_encrypted`).
+                // unit) can't be unit-decrypted, so fail loud. Validity is the SAME
+                // `is_clean` proof floor used everywhere — a clear TS tail passes it,
+                // a scrambled one fails. PS (`.evo`) partials lack the TS structure,
+                // so this stays TS-only (HD-DVD partial-scramble is not yet wired).
                 if partial_in_content && format == crate::disc::ContentFormat::BdTs {
                     let partial = &buf[buf.len() - partial_len..];
-                    let packets = aacs::content::ts_packet_total(partial);
-                    if packets > 0 && aacs::content::ts_sync_count(partial) <= packets / 2 {
+                    if !aacs::content::is_clean(partial, format) {
                         return Err(crate::error::Error::DecryptFailed);
                     }
                 }
@@ -1301,6 +1623,208 @@ mod tests {
         unit
     }
 
+    // ── FMTS phase-aware map ──────────────────────────────────────────────────
+
+    /// `entry_for` returns (idx, phase, range_start); `from_ranges` is All,
+    /// `from_ranges_phased` carries the phase; uncovered → (default, All, 0).
+    #[test]
+    fn aacskeymap_phase_entry_for() {
+        let all = AacsKeyMap::from_ranges(vec![(100, 200, 3)], 0);
+        assert_eq!(all.entry_for(150), (3, Phase::All, 100));
+        assert_eq!(all.entry_for(50), (0, Phase::All, 0));
+
+        let phased = AacsKeyMap::from_ranges_phased(vec![(100, 200, 3, Phase::Odd)], 7);
+        assert_eq!(phased.entry_for(150), (3, Phase::Odd, 100));
+        assert_eq!(phased.entry_for(250), (7, Phase::All, 0));
+        assert_eq!(phased.key_idx_for(150), 3);
+    }
+
+    /// A map with no forensic (Even/Odd) range is the common disc: `read_plan`
+    /// returns the extents unchanged, so nothing but FMTS is affected.
+    #[test]
+    fn read_plan_non_forensic_is_unchanged() {
+        use crate::disc::Extent;
+        let us = (aacs::content::ALIGNED_UNIT_LEN / 2048) as u32; // 3
+        let ext = vec![
+            Extent {
+                start_lba: 1000,
+                sector_count: 300,
+            },
+            Extent {
+                start_lba: 5000,
+                sector_count: 60,
+            },
+        ];
+        // Single-CPS and multi-CPS (All) maps both leave the plan untouched.
+        assert_eq!(AacsKeyMap::single(0).read_plan(&ext, us), ext);
+        let multi = AacsKeyMap::from_ranges(vec![(1000, 1150, 2)], 0);
+        assert_eq!(multi.read_plan(&ext, us), ext);
+    }
+
+    /// FMTS: a forensic Even segment drops exactly its alternate (odd) units from
+    /// the read plan — they are never fetched — while default content on either
+    /// side stays one coalesced sequential run. The kept units are byte-identical
+    /// to the ones the decrypt hot loop opens.
+    #[test]
+    fn read_plan_forensic_reads_only_our_phase_units() {
+        use crate::disc::Extent;
+        let us = (aacs::content::ALIGNED_UNIT_LEN / 2048) as u32; // 3
+        // One extent, 100 units [1000, 1300). A 10-unit Even forensic segment at
+        // LBA [1030, 1060): kept even units are ix 0,2,4,6,8 → LBA 1030,1036,1042,
+        // 1048,1054; dropped odd units → 1033,1039,1045,1051,1057.
+        let ext = vec![Extent {
+            start_lba: 1000,
+            sector_count: 300,
+        }];
+        let map = AacsKeyMap::from_ranges_phased(vec![(1030, 1060, 5, Phase::Even)], 0);
+        let plan = map.read_plan(&ext, us);
+        let expected = vec![
+            Extent {
+                start_lba: 1000,
+                sector_count: 33,
+            }, // 1000..1030 default + the ix-0 even unit at 1030
+            Extent {
+                start_lba: 1036,
+                sector_count: 3,
+            },
+            Extent {
+                start_lba: 1042,
+                sector_count: 3,
+            },
+            Extent {
+                start_lba: 1048,
+                sector_count: 3,
+            },
+            Extent {
+                start_lba: 1054,
+                sector_count: 3,
+            },
+            Extent {
+                start_lba: 1060,
+                sector_count: 240,
+            }, // default resumes, coalesced to the extent end
+        ];
+        assert_eq!(plan, expected);
+        // Exactly the 5 odd units (15 sectors) are omitted; nothing else.
+        let kept: u32 = plan.iter().map(|e| e.sector_count).sum();
+        assert_eq!(
+            kept,
+            300 - 5 * us,
+            "only the alternate-phase units are dropped"
+        );
+        // Every kept LBA is one the decrypt loop would decrypt (All or our parity),
+        // and no dropped LBA is: the plan and the decrypt gate agree unit-for-unit.
+        for e in &plan {
+            let mut off = 0;
+            while off < e.sector_count {
+                let lba = e.start_lba + off;
+                let (_, phase, rs) = map.entry_for(lba);
+                if let Phase::Even | Phase::Odd = phase {
+                    let is_odd = ((lba - rs) / us) % 2 == 1;
+                    assert!(
+                        is_odd == matches!(phase, Phase::Odd),
+                        "plan kept an alternate-phase unit at LBA {lba}"
+                    );
+                }
+                off += us;
+            }
+        }
+    }
+
+    /// Phase::Even → only even-index units in the range are decrypted; the odd
+    /// (alternate variant) half is left BYTE-FOR-BYTE as ciphertext for the muxer.
+    #[test]
+    fn mapped_phase_even_decrypts_even_leaves_odd_ciphertext() {
+        use crate::disc::ContentFormat;
+        let key_a = [0xAAu8; 16];
+        let key_b = [0xBBu8; 16];
+        let ul = aacs::content::ALIGNED_UNIT_LEN;
+        let usz = (ul / 2048) as u32;
+        let mut buf = vec![0u8; 8 * ul];
+        let mut odd_cipher = Vec::new();
+        for i in 0..8 {
+            let mut u = clear_ts_unit();
+            aacs_encrypt_unit_for_test(&mut u, if i % 2 == 0 { &key_a } else { &key_b });
+            if i % 2 == 1 {
+                odd_cipher.push(u.clone());
+            }
+            buf[i * ul..(i + 1) * ul].copy_from_slice(&u);
+        }
+        let keys = DecryptKeys::Aacs {
+            unit_keys: vec![(0, key_a)],
+            read_data_key: None,
+            format: ContentFormat::BdTs,
+        };
+        let map = AacsKeyMap::from_ranges_phased(vec![(0, 8 * usz, 0, Phase::Even)], 0);
+        decrypt_sectors_mapped(&mut buf, &keys, 0, &map).expect("even phase decrypts clean");
+        for i in 0..8 {
+            let u = &buf[i * ul..(i + 1) * ul];
+            if i % 2 == 0 {
+                assert!(
+                    aacs::content::is_clean(u, ContentFormat::BdTs),
+                    "even unit {i} decrypted to clean TS"
+                );
+            } else {
+                assert_eq!(
+                    u,
+                    odd_cipher[i / 2].as_slice(),
+                    "odd unit {i} left as ciphertext"
+                );
+            }
+        }
+    }
+
+    /// The correct-phase safety `is_clean` fires loud: an even unit whose mapped
+    /// key is wrong does NOT come clean → `DecryptFailed` (not silent corruption).
+    #[test]
+    fn mapped_phase_verify_fails_loud_on_wrong_key() {
+        use crate::disc::ContentFormat;
+        let ul = aacs::content::ALIGNED_UNIT_LEN;
+        let usz = (ul / 2048) as u32;
+        let mut buf = vec![0u8; 2 * ul];
+        let mut u0 = clear_ts_unit();
+        aacs_encrypt_unit_for_test(&mut u0, &[0xAAu8; 16]); // encrypted under A
+        buf[..ul].copy_from_slice(&u0);
+        let keys = DecryptKeys::Aacs {
+            unit_keys: vec![(0, [0xCCu8; 16])], // map slot points at the WRONG key
+            read_data_key: None,
+            format: ContentFormat::BdTs,
+        };
+        let map = AacsKeyMap::from_ranges_phased(vec![(0, 2 * usz, 0, Phase::Even)], 0);
+        assert!(matches!(
+            decrypt_sectors_mapped(&mut buf, &keys, 0, &map),
+            Err(crate::error::Error::DecryptFailed)
+        ));
+    }
+
+    /// Phase::All (multi-CPS / base) decrypts EVERY unit and never runs the verify
+    /// — the common-disc path is byte-for-byte unchanged.
+    #[test]
+    fn mapped_all_phase_decrypts_every_unit() {
+        use crate::disc::ContentFormat;
+        let key = [0x11u8; 16];
+        let ul = aacs::content::ALIGNED_UNIT_LEN;
+        let mut buf = vec![0u8; 4 * ul];
+        for i in 0..4 {
+            let mut u = clear_ts_unit();
+            aacs_encrypt_unit_for_test(&mut u, &key);
+            buf[i * ul..(i + 1) * ul].copy_from_slice(&u);
+        }
+        let keys = DecryptKeys::Aacs {
+            unit_keys: vec![(0, key)],
+            read_data_key: None,
+            format: ContentFormat::BdTs,
+        };
+        decrypt_sectors_mapped(&mut buf, &keys, 0, &AacsKeyMap::single(0))
+            .expect("all-phase decrypts");
+        for i in 0..4 {
+            assert!(
+                aacs::content::is_clean(&buf[i * ul..(i + 1) * ul], ContentFormat::BdTs),
+                "unit {i} decrypted (All)"
+            );
+        }
+    }
+
     /// A unit encrypted under unit_keys[1] (the second CPS unit) on a
     /// two-key disc must be correctly decrypted — not left as garbage —
     /// when `decrypt_sectors` is called with unit_key_idx=0 (the default).
@@ -1324,7 +1848,7 @@ mod tests {
         let mut unit = clear_ts_unit();
         aacs_encrypt_unit_for_test(&mut unit, &key1);
         assert!(
-            aacs::content::ts_sync_destroyed(&unit),
+            !crate::aacs::content::is_clean(&unit, crate::disc::ContentFormat::BdTs),
             "encrypted unit must look scrambled before decrypt"
         );
 
@@ -1339,7 +1863,7 @@ mod tests {
         decrypt_sectors(&mut buf, &mut keys, 0).expect("multi-CPS decrypt must succeed");
 
         assert!(
-            !aacs::content::ts_sync_destroyed(&buf),
+            crate::aacs::content::is_clean(&buf, crate::disc::ContentFormat::BdTs),
             "unit encrypted under key1 must be fully decrypted (TS syncs restored)"
         );
         // Every sync position must carry 0x47.
@@ -1371,7 +1895,7 @@ mod tests {
         let mut buf = unit;
         decrypt_sectors(&mut buf, &mut keys, 0).expect("single-key disc must decrypt");
         assert!(
-            !aacs::content::ts_sync_destroyed(&buf),
+            crate::aacs::content::is_clean(&buf, crate::disc::ContentFormat::BdTs),
             "single-key disc: TS syncs must be restored"
         );
         assert_eq!(
@@ -1401,7 +1925,7 @@ mod tests {
         aacs_encrypt_unit_for_test(&mut unit, &real_key);
         let ciphertext = unit.clone();
         assert!(
-            aacs::content::ts_sync_destroyed(&unit),
+            !crate::aacs::content::is_clean(&unit, crate::disc::ContentFormat::BdTs),
             "encrypted unit must look scrambled going in"
         );
 
@@ -1462,7 +1986,10 @@ mod tests {
             "exactly one unit's worth of bytes must be reported unverified"
         );
         assert!(
-            !aacs::content::ts_sync_destroyed(&buf[..aacs::content::ALIGNED_UNIT_LEN]),
+            crate::aacs::content::is_clean(
+                &buf[..aacs::content::ALIGNED_UNIT_LEN],
+                crate::disc::ContentFormat::BdTs
+            ),
             "the decryptable unit must come out clear"
         );
         assert_ne!(

src/diag.rs

@@ -336,7 +336,7 @@ fn frame_record(track_idx: usize, pts_ns: i64, keyframe: bool, data: &[u8]) -> V
 /// `track_number` is the 1-based MKV track number; `track` is the built
 /// [`crate::mux::mkv::MkvTrack`] whose fields map one-to-one onto the emitted
 /// elements (see `MkvMuxer::new`). No-op unless the diag target is on.
-pub fn dump_mkv_track(track_number: u64, track: &crate::mux::mkv::MkvTrack) {
+pub(crate) fn dump_mkv_track(track_number: u64, track: &crate::mux::mkv::MkvTrack) {
     if !diag_enabled() {
         return;
     }
@@ -530,7 +530,7 @@ fn dump_aacs(disc: &Disc) {
         a.bus_encryption,
         a.mkb_version,
         a.disc_hash,
-        a.key_source.name(),
+        a.key_source,
         a.vuk.is_some(),
         a.unit_keys.len(),
         a.uk_ro.len(),

src/disc/encrypt.rs

@@ -7,7 +7,6 @@ use crate::udf;
 
 /// Result of SCSI AACS handshake (ECDH authentication).
 /// Only available when scanning from a real drive, not ISO images.
-#[derive(Debug)]
 pub(super) struct HandshakeResult {
     pub volume_id: [u8; 16],
     pub read_data_key: Option<[u8; 16]>,
@@ -29,6 +28,19 @@ pub(super) struct HandshakeResult {
     pub drive_unlocked: bool,
 }
 
+// Redacting `Debug`: `volume_id` and `read_data_key` (the AACS 2.0 bus key) are
+// secret; print only shape. Guarded by `handshake_result_debug_is_redacted`.
+impl std::fmt::Debug for HandshakeResult {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("HandshakeResult")
+            .field("volume_id", &"<redacted>")
+            .field("read_data_key", &self.read_data_key.map(|_| "<redacted>"))
+            .field("read_data_key_err", &self.read_data_key_err)
+            .field("drive_unlocked", &self.drive_unlocked)
+            .finish()
+    }
+}
+
 /// Single source of truth for "is AACS bus encryption gone for this scan?". The
 /// gate asks ONLY this — `if !removed { error }` — never enumerating cases. Bus
 /// encryption is gone when ANY of these holds:
@@ -428,6 +440,27 @@ mod tests {
     use crate::sector::SectorSource;
     use std::collections::HashMap;
 
+    /// `HandshakeResult` carries the Volume ID and the AACS 2.0 bus (read-data)
+    /// key; `Debug` must redact both. Sentinel 213 (0xD5).
+    #[test]
+    fn handshake_result_debug_is_redacted() {
+        let hs = HandshakeResult {
+            volume_id: [0xD5; 16],
+            read_data_key: Some([0xD5; 16]),
+            read_data_key_err: None,
+            drive_unlocked: false,
+        };
+        let d = format!("{hs:?}");
+        assert!(
+            !d.contains("213"),
+            "HandshakeResult leaked VID/bus key: {d}"
+        );
+        assert!(
+            d.contains("redacted"),
+            "HandshakeResult missing marker: {d}"
+        );
+    }
+
     // ---------------------------------------------------------------
     // In-memory disc + minimal UDF image with a single physical
     // partition (metadata_start == partition_start). Offsets cited
@@ -976,7 +1009,7 @@ mod tests {
     /// A minimal in-test KeySource that yields no keys but a fixed cert list.
     struct CertSource(Vec<aacs::types::HostCert>);
     impl crate::KeySource for CertSource {
-        fn get_uk(
+        fn get_unit_keys(
             &self,
             _ctx: &dyn crate::keysource::ResolveCtx,
         ) -> Result<Vec<crate::aacs::types::UnitKey>> {

src/disc/hddvd.rs

@@ -522,8 +522,10 @@ fn compose_xpl_titles(
             })
             .collect();
         titles.push(DiscTitle {
+            // Language-neutral identifier (no user-facing English in the library):
+            // matches the UDF `TITLE_*` volume-label style. Apps localize display.
             playlist: if t.name.is_empty() {
-                format!("Title {}", t.number)
+                format!("TITLE_{}", t.number)
             } else {
                 t.name.clone()
             },

src/disc/mapfile.rs

@@ -77,7 +77,7 @@ impl SectorStatus {
 
 /// One contiguous range of bytes with a status.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct MapEntry {
+pub(crate) struct MapEntry {
     pub pos: u64,
     pub size: u64,
     pub status: SectorStatus,
@@ -498,7 +498,7 @@ impl Mapfile {
 
     /// All map entries, sorted ascending by `pos` and (after load)
     /// guaranteed disjoint and non-overflowing.
-    pub fn entries(&self) -> &[MapEntry] {
+    pub(crate) fn entries(&self) -> &[MapEntry] {
         &self.entries
     }
 

src/disc/mod.rs

@@ -457,7 +457,7 @@ pub(crate) fn chapter_name(i: usize) -> String {
 }
 
 /// A contiguous range of sectors on disc.
-#[derive(Debug, Clone, Copy)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct Extent {
     pub start_lba: u32,
     pub sector_count: u32,
@@ -683,7 +683,10 @@ fn range_chapter(lba: u32, title: &DiscTitle) -> (Option<u32>, Option<f64>) {
 /// This is the single place range→chapter/time annotation happens; autorip used
 /// to own it and read the mapfile to do so. Now the library computes it from
 /// its in-memory mapfile + title, and the client renders the result verbatim.
-pub fn locate_ranges(raw: &[(u64, u64)], title: &DiscTitle) -> crate::progress::LocatedProgress {
+pub(crate) fn locate_ranges(
+    raw: &[(u64, u64)],
+    title: &DiscTitle,
+) -> crate::progress::LocatedProgress {
     use crate::consts::{MILLIS_PER_SEC, SECTOR_BYTES_U64};
     use crate::progress::{LocatedProgress, LocatedRange};
     const MAX_LOCATED: usize = 50;
@@ -1363,7 +1366,6 @@ impl DiscTitle {
 // ─── Encryption ─────────────────────────────────────────────────────────────
 
 /// AACS decryption state for a disc.
-#[derive(Debug)]
 pub struct AacsState {
     /// AACS version (1 or 2)
     pub version: u8,
@@ -1394,6 +1396,28 @@ pub struct AacsState {
     pub mkb: Vec<u8>,
 }
 
+// Redacting `Debug`: `AacsState` is crate-root re-exported and reachable via the
+// public `Disc.aacs` field; it carries VUK / unit keys / read-data (bus) key /
+// volume id / raw .inf + MKB. Print only non-secret shape; redact every
+// key/secret field. Guarded by `aacs_state_and_key_debug_are_redacted`.
+impl std::fmt::Debug for AacsState {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("AacsState")
+            .field("version", &self.version)
+            .field("bus_encryption", &self.bus_encryption)
+            .field("mkb_version", &self.mkb_version)
+            .field("disc_hash", &self.disc_hash)
+            .field("key_source", &self.key_source)
+            .field("vuk", &self.vuk.map(|_| "<redacted>"))
+            .field("unit_keys_len", &self.unit_keys.len())
+            .field("read_data_key", &self.read_data_key.map(|_| "<redacted>"))
+            .field("volume_id", &"<redacted>")
+            .field("uk_ro_len", &self.uk_ro.len())
+            .field("mkb_len", &self.mkb.len())
+            .finish()
+    }
+}
+
 /// How AACS keys were resolved. Variants are ordered root-of-trust →
 /// per-disc-leaf, matching the resolver's path-try order: the resolver
 /// attempts derivation from the strongest input it has first and falls
@@ -1416,18 +1440,9 @@ pub enum KeyOrigin {
     ExternalUk,
 }
 
-impl KeyOrigin {
-    pub fn name(&self) -> &'static str {
-        match self {
-            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",
-        }
-    }
-}
+// No `KeyOrigin::name()`: the library holds ZERO user-facing English (CLAUDE.md).
+// `KeyOrigin` is a typed enum; applications map its variants to display text
+// (see freemkv's `disc_info::key_origin_label`).
 
 // ─── Disc scanning ──────────────────────────────────────────────────────────
 
@@ -2244,7 +2259,7 @@ impl Disc {
 /// 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)]
+#[derive(Clone)]
 #[non_exhaustive]
 pub enum Key {
     /// Device key(s) (AACS DK, positioned). libfreemkv walks the MKB
@@ -2273,6 +2288,22 @@ pub enum Key {
     Unit(Vec<(u32, [u8; 16])>),
 }
 
+// Redacting `Debug`: `Key` is crate-root re-exported and is the key-transport
+// type crossing `Disc::decrypt_with`; every variant carries raw key material.
+// Print only the variant name and count — never bytes. Guarded by
+// `aacs_state_and_key_debug_are_redacted`.
+impl std::fmt::Debug for Key {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Key::Device(v) => write!(f, "Key::Device(<{} redacted>)", v.len()),
+            Key::Processing(v) => write!(f, "Key::Processing(<{} redacted>)", v.len()),
+            Key::Media(v) => write!(f, "Key::Media(<{} redacted>)", v.len()),
+            Key::Volume(_) => f.write_str("Key::Volume(<redacted>)"),
+            Key::Unit(v) => write!(f, "Key::Unit(<{} redacted>)", v.len()),
+        }
+    }
+}
+
 /// True if `unit_keys` covers EVERY supplied scrambled content `sample` — the
 /// validation gate for [`Disc::decrypt_with`]. Conservative: a sample that is
 /// not AACS-scrambled proves nothing, and with no scrambled sample at all there
@@ -2387,7 +2418,7 @@ impl Disc {
     ///
     /// Empty when the disc has no parsed titles (CSS / unencrypted / unscanned);
     /// callers treat an empty map as "no content gate" and fall back accordingly.
-    pub fn encrypted_content_ranges(&self) -> Vec<(u32, u32)> {
+    pub(crate) fn encrypted_content_ranges(&self) -> Vec<(u32, u32)> {
         merged_extents(self.titles.iter().flat_map(|t| &t.extents))
     }
 
@@ -2395,10 +2426,10 @@ impl Disc {
     /// empty when this disc has no captured AACS state. Used to name the disc in
     /// a [`Error::NoDiscKey`] so the application can tell the user which disc to
     /// add to the keydb.
-    pub fn aacs_disc_hash(&self) -> String {
+    pub(crate) fn aacs_disc_hash(&self) -> String {
         self.aacs
             .as_ref()
-            .map(|a| a.disc_hash.trim_start_matches("0x").to_string())
+            .map(|a| crate::hex::strip_hex_prefix(&a.disc_hash).to_string())
             .unwrap_or_default()
     }
 
@@ -2535,35 +2566,25 @@ impl Disc {
     ///
     /// `batch_sectors` sizes the crack's batched reads (file-safe value for
     /// an ISO; `detect_max_batch_sectors` for a live drive).
-    pub fn decrypt_keys_for_title(
-        &self,
-        idx: usize,
-        reader: &mut dyn SectorSource,
-        batch_sectors: u16,
-    ) -> crate::decrypt::DecryptKeys {
-        self.decrypt_keys_for_title_checked(idx, reader, batch_sectors)
-            .0
-    }
-
-    /// [`Self::decrypt_keys_for_title`] plus the per-title encryption verdict the
-    /// gate needs to AVOID A FALSE ERROR on a genuinely-clear extra title.
+    /// Also returns the per-title encryption verdict the gate needs to AVOID A
+    /// FALSE ERROR on a genuinely-clear extra title.
     ///
     /// On a multi-VTS CSS DVD that ALSO carries a clear, unencrypted stub title
     /// (a 0.5 s menu loop, an FBI-warning nav title) living in its own VTS, the
     /// re-crack over that stub's extents finds NO scrambled sector and recovers
-    /// no key. The bare `decrypt_keys_for_title` collapses that to
+    /// no key. Returning ONLY the keys would collapse that to
     /// `DecryptKeys::None`, indistinguishable from "scrambled but uncrackable",
     /// so [`Self::ensure_decryptable_keys`] (which fails whenever `css.is_some()`
-    /// and the key is `None`) wrongly raised `E7023` for a title that needs no
-    /// key at all. That is the false error the multi-title mux must never emit.
+    /// and the key is `None`) would wrongly raise `E7023` for a title that needs
+    /// no key at all — the false error the multi-title mux must never emit.
     ///
-    /// This variant runs the re-crack via [`crate::css::crack_key_outcome`] and
+    /// So the re-crack runs via [`crate::css::crack_key_outcome`] and ALSO
     /// returns `title_is_clear == true` when the title's own extents showed NO
     /// scrambling (`CrackOutcome::Unencrypted`) — the gate then treats that title
     /// as needing no key and passes it cleanly. A title that genuinely IS
     /// scrambled but uncrackable returns `(None, false)` and still hard-fails.
     /// The returned bool pairs with [`Self::ensure_title_decryptable`].
-    pub fn decrypt_keys_for_title_checked(
+    pub fn decrypt_keys_for_title(
         &self,
         idx: usize,
         reader: &mut dyn SectorSource,
@@ -2627,7 +2648,7 @@ impl Disc {
     }
 
     /// Per-title decrypt gate that honours the `title_is_clear` verdict from
-    /// [`Self::decrypt_keys_for_title_checked`].
+    /// [`Self::decrypt_keys_for_title`].
     ///
     /// Identical to [`Self::ensure_decryptable_keys`] EXCEPT it does not raise
     /// `E7023` when the chosen title proved genuinely clear (`title_is_clear`):
@@ -2655,28 +2676,6 @@ impl Disc {
         self.ensure_decryptable_keys(raw, keys)
     }
 
-    /// Upfront FMTS (AACS 2.1) key gate, parallel to
-    /// [`ensure_title_decryptable`](Self::ensure_title_decryptable). A 2.1 disc
-    /// carries forensic variant segments that need segment (variant) keys the
-    /// unit-key path cannot provide. When
-    /// [`BYPASS_FMTS_KEY`](crate::aacs::segment::BYPASS_FMTS_KEY) is `false`,
-    /// their absence is a hard upfront failure ([`Error::FmtsKeyMissing`]) — the
-    /// same policy as a missing unit key, so a forensic-holed rip is refused, not
-    /// produced. When `true` (the default today) the segments are skipped as
-    /// expected loss and this passes. `raw` mode and non-FMTS discs always pass.
-    pub fn ensure_forensic_segments_decryptable(&self, raw: bool) -> Result<()> {
-        if raw || crate::aacs::segment::BYPASS_FMTS_KEY {
-            return Ok(());
-        }
-        // A 2.1 (FMTS) disc carries forensic variant segments with no segment-key
-        // source (none exists yet), so its variant segments cannot be opened.
-        // Refuse upfront rather than emit a forensic-holed rip.
-        if self.format == DiscFormat::Fmts {
-            return Err(Error::FmtsKeyMissing);
-        }
-        Ok(())
-    }
-
     /// 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
@@ -2694,7 +2693,7 @@ impl Disc {
     /// 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])>) {
+    pub(crate) 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;
@@ -4210,6 +4209,40 @@ pub fn detect_max_batch_sectors(device_path: &str) -> u16 {
 mod tests {
     use super::*;
 
+    /// `AacsState` (public via `Disc.aacs`) and `Key` (the key-transport enum)
+    /// must never print raw key bytes on `{:?}`. Sentinel 213 (0xD5); non-secret
+    /// fields below are not 213.
+    #[test]
+    fn aacs_state_and_key_debug_are_redacted() {
+        let st = AacsState {
+            version: 2,
+            bus_encryption: true,
+            mkb_version: Some(77),
+            disc_hash: "0xAA".into(),
+            key_source: KeyOrigin::ExternalUk,
+            vuk: Some([0xD5; 16]),
+            unit_keys: vec![(1, [0xD5; 16])],
+            read_data_key: Some([0xD5; 16]),
+            volume_id: [0xD5; 16],
+            uk_ro: vec![1, 2, 3],
+            mkb: vec![4, 5, 6],
+        };
+        let d = format!("{st:?}");
+        assert!(!d.contains("213"), "AacsState leaked key bytes: {d}");
+        assert!(d.contains("redacted"), "AacsState missing marker: {d}");
+
+        for k in [
+            Key::Unit(vec![(1, [0xD5; 16])]),
+            Key::Volume([0xD5; 16]),
+            Key::Processing(vec![[0xD5; 16]]),
+            Key::Media(vec![[0xD5; 16]]),
+        ] {
+            let d = format!("{k:?}");
+            assert!(!d.contains("213"), "Key leaked bytes: {d}");
+            assert!(d.contains("redacted"), "Key missing marker: {d}");
+        }
+    }
+
     // ── encrypted-content map (`merged_extents` core) ────────────────────────
 
     fn ext(start_lba: u32, sector_count: u32) -> Extent {
@@ -5085,8 +5118,8 @@ mod tests {
     // ── Fix 2/3: a genuinely-clear extra title on a CSS disc never E7023s ──────
 
     /// Reader that serves clear (unscrambled) sectors for one extent range and
-    /// CSS-locked errors elsewhere — enough to drive `decrypt_keys_for_title_
-    /// checked`'s per-title re-crack to `Unencrypted` for a clear stub.
+    /// CSS-locked errors elsewhere — enough to drive `decrypt_keys_for_title`'s
+    /// per-title re-crack to `Unencrypted` for a clear stub.
     struct ClearStubReader {
         clear_range: (u32, u32),
     }
@@ -5146,7 +5179,7 @@ mod tests {
         let mut reader = ClearStubReader {
             clear_range: (0, 100_000),
         };
-        let (keys, title_is_clear) = disc.decrypt_keys_for_title_checked(stub_idx, &mut reader, 8);
+        let (keys, title_is_clear) = disc.decrypt_keys_for_title(stub_idx, &mut reader, 8);
         assert!(
             !keys.is_encrypted(),
             "a clear stub needs no key (got encrypted keys)"
@@ -5326,7 +5359,7 @@ mod tests {
 
     #[test]
     fn unit_key_validation_gates_on_real_ciphertext() {
-        use crate::aacs::content::{ALIGNED_UNIT_LEN, ts_sync_destroyed};
+        use crate::aacs::content::ALIGNED_UNIT_LEN;
 
         // No samples -> nothing to disprove against -> accept (sample-less paths
         // like resume / mapfile must be unaffected).
@@ -5345,7 +5378,10 @@ mod tests {
             clear[off] = 0x47;
             off += 192;
         }
-        assert!(!ts_sync_destroyed(&clear));
+        assert!(crate::aacs::content::is_clean(
+            &clear,
+            crate::disc::ContentFormat::BdTs
+        ));
         assert!(super::aligned_unit_keys_validate(
             &[(0, [0x11u8; 16])],
             None,
@@ -5357,7 +5393,7 @@ mod tests {
         let uk = [0x5au8; 16];
         let enc = encrypt_unit_for_test(&clear, &uk);
         assert!(
-            ts_sync_destroyed(&enc),
+            !crate::aacs::content::is_clean(&enc, crate::disc::ContentFormat::BdTs),
             "encrypted unit must read scrambled"
         );
 
@@ -5393,7 +5429,7 @@ mod tests {
         // CPS-unit-1 sectors then passed through as raw encrypted bytes into the
         // ISO/MKV with no error surfaced. The gate must now reject a key set
         // that leaves any scrambled sample uncovered.
-        use crate::aacs::content::{ALIGNED_UNIT_LEN, ts_sync_destroyed};
+        use crate::aacs::content::ALIGNED_UNIT_LEN;
 
         let mut clear = vec![0u8; ALIGNED_UNIT_LEN];
         let mut off = 4;
@@ -5406,8 +5442,14 @@ mod tests {
         let uk1 = [0x22u8; 16];
         let sample0 = encrypt_unit_for_test(&clear, &uk0); // CPS unit 0 body
         let sample1 = encrypt_unit_for_test(&clear, &uk1); // CPS unit 1 body
-        assert!(ts_sync_destroyed(&sample0));
-        assert!(ts_sync_destroyed(&sample1));
+        assert!(!crate::aacs::content::is_clean(
+            &sample0,
+            crate::disc::ContentFormat::BdTs
+        ));
+        assert!(!crate::aacs::content::is_clean(
+            &sample1,
+            crate::disc::ContentFormat::BdTs
+        ));
 
         let samples = vec![sample0.clone(), sample1.clone()];
 
@@ -5559,7 +5601,7 @@ mod tests {
         let mut src = RecordingSource {
             reads: std::cell::RefCell::new(Vec::new()),
         };
-        match disc.decrypt_keys_for_title(0, &mut src, 16) {
+        match disc.decrypt_keys_for_title(0, &mut src, 16).0 {
             crate::decrypt::DecryptKeys::Css { title_key } => {
                 assert_eq!(title_key, [0xAB; 5], "same-VTS title reuses cracked key");
             }
@@ -5584,7 +5626,7 @@ mod tests {
         let mut src = RecordingSource {
             reads: std::cell::RefCell::new(Vec::new()),
         };
-        let keys = disc.decrypt_keys_for_title(1, &mut src, 16);
+        let keys = disc.decrypt_keys_for_title(1, &mut src, 16).0;
         assert!(
             matches!(keys, crate::decrypt::DecryptKeys::None),
             "a re-crack miss in a provably-different VTS must be a hard failure (None), \

src/hex.rs

@@ -16,7 +16,7 @@
 /// (case-insensitive), then requires an even run of ASCII hex digits. Any
 /// non-hex byte, or an odd length, yields `None`.
 pub fn parse_hex_bytes(s: &str) -> Option<Vec<u8>> {
-    let body = strip_prefix(s.trim());
+    let body = strip_hex_prefix(s.trim());
     let bytes = body.as_bytes();
     // Empty → empty Vec (a legitimately-empty variable-length field); odd length
     // is malformed. (`parse_hex_fixed` enforces a concrete length separately.)
@@ -34,7 +34,7 @@ pub fn parse_hex_bytes(s: &str) -> Option<Vec<u8>> {
 /// prefix; requires EXACTLY `2*N` ASCII hex digits after it. `None` on any
 /// non-hex byte or a length mismatch.
 pub fn parse_hex_fixed<const N: usize>(s: &str) -> Option<[u8; N]> {
-    let body = strip_prefix(s.trim());
+    let body = strip_hex_prefix(s.trim());
     let bytes = body.as_bytes();
     if bytes.len() != 2 * N {
         return None;
@@ -46,8 +46,33 @@ pub fn parse_hex_fixed<const N: usize>(s: &str) -> Option<[u8; N]> {
     Some(out)
 }
 
-/// Strip a single leading `0x` / `0X` if present (case-insensitive).
-fn strip_prefix(s: &str) -> &str {
+/// Parse a hex string into a `u16`. Accepts an optional `0x`/`0X` prefix
+/// (case-insensitive) via the same [`strip_hex_prefix`] the byte parsers use.
+/// `None` on any non-hex content or overflow.
+///
+/// Exists so callers never hand-roll `from_str_radix(s.trim_start_matches("0x"), 16)`
+/// — a **case-sensitive** strip that silently dropped an uppercase-`0X` value.
+/// (That reintroduced-in-keydb bug is exactly what this module was built to kill;
+/// the integer fields now share the one prefix rule.)
+pub fn parse_hex_u16(s: &str) -> Option<u16> {
+    u16::from_str_radix(strip_hex_prefix(s.trim()), 16).ok()
+}
+
+/// Parse a hex string into a `u32`. See [`parse_hex_u16`].
+pub fn parse_hex_u32(s: &str) -> Option<u32> {
+    u32::from_str_radix(strip_hex_prefix(s.trim()), 16).ok()
+}
+
+/// Parse a hex string into a `u8`. See [`parse_hex_u16`].
+pub fn parse_hex_u8(s: &str) -> Option<u8> {
+    u8::from_str_radix(strip_hex_prefix(s.trim()), 16).ok()
+}
+
+/// Strip a single leading `0x` / `0X` if present (case-insensitive). Public so
+/// callers that only need the prefix rule (e.g. normalizing a disc hash) reuse
+/// the one definition instead of hand-rolling a case-sensitive
+/// `trim_start_matches("0x")`.
+pub fn strip_hex_prefix(s: &str) -> &str {
     s.strip_prefix("0x")
         .or_else(|| s.strip_prefix("0X"))
         .unwrap_or(s)
@@ -95,6 +120,23 @@ mod tests {
         assert_eq!(parse_hex_fixed::<16>(&s), None);
     }
 
+    #[test]
+    fn hex_ints_accept_both_prefix_cases_and_bare() {
+        // The regression the keydb device-key bug hit: uppercase `0X` must parse
+        // identically to `0x` and to a bare value.
+        assert_eq!(parse_hex_u16("0x0001"), Some(1));
+        assert_eq!(parse_hex_u16("0X0001"), Some(1));
+        assert_eq!(parse_hex_u16("0001"), Some(1));
+        assert_eq!(parse_hex_u16(" 0XABCD "), Some(0xABCD));
+        assert_eq!(parse_hex_u32("0X00000002"), Some(2));
+        assert_eq!(parse_hex_u32("deadbeef"), Some(0xDEAD_BEEF));
+        assert_eq!(parse_hex_u8("0X03"), Some(3));
+        assert_eq!(parse_hex_u8("ff"), Some(0xFF));
+        // Overflow / non-hex → None.
+        assert_eq!(parse_hex_u8("0x1FF"), None);
+        assert_eq!(parse_hex_u16("0xzz"), None);
+    }
+
     #[test]
     fn bytes_variable_length_and_odd_rejected() {
         assert_eq!(parse_hex_bytes("0xAABBCC"), Some(vec![0xAA, 0xBB, 0xCC]));

src/keysource.rs

@@ -23,6 +23,64 @@ use crate::aacs::types::{UnitKey, Vid};
 use crate::disc::Key;
 use crate::error::Error;
 
+/// Minimum encrypted-content unit samples a single online key request must carry.
+///
+/// The key service identifies a key by which of the submitted units it decrypts,
+/// so too few samples — especially on FMTS, where a segment interleaves several
+/// variants at the unit level — can return a key that matches an incidental unit
+/// rather than the one asked about (a false positive). This many distinct units
+/// make the request unambiguous.
+///
+/// Canonical here (the base crate) so BOTH consumers agree on one value: the
+/// online source in `freemkv-keysources` (which refuses to send an under-sampled
+/// request) re-exports it, and libfreemkv's own FMTS forensic query
+/// ([`crate::mux`]) sizes its per-segment batch by it. Layering forbids the
+/// reverse import (keysources depends on libfreemkv, not vice versa), so the
+/// value lives at the lower layer both share.
+pub const MIN_SAMPLE_UNITS: usize = 8;
+
+/// A set of encrypted content-unit samples PROVEN to carry at least
+/// [`MIN_SAMPLE_UNITS`] units — the online `/decode` request's proof-of-ownership.
+///
+/// "Parse, don't validate": the only constructor, [`DecodeSampleSet::new`], returns
+/// `None` for an under-sized slice, so an online key request simply *cannot be built*
+/// from too few samples. The runtime `len() < MIN_SAMPLE_UNITS` check that used to
+/// live at the request site (and was silently forgotten by an under-sampling caller,
+/// reading as "key service down") becomes a compile-time obligation: a request builder
+/// that takes `&DecodeSampleSet` can never receive an unchecked `Vec`.
+///
+/// The *count* enforced here is a runtime property of the disc (how many encrypted
+/// units it yields); the *requested* count is a caller-side compile-time constant that
+/// callers pin to `MIN_SAMPLE_UNITS` (see e.g. autorip's `SAMPLE_UNITS`). Together the
+/// two make under-sampling unrepresentable at the request boundary.
+#[derive(Debug, Clone)]
+pub struct DecodeSampleSet(Vec<Vec<u8>>);
+
+impl DecodeSampleSet {
+    /// Wrap `units` iff it carries at least [`MIN_SAMPLE_UNITS`] samples; `None`
+    /// otherwise (the caller then skips the online source rather than sending an
+    /// ambiguous request). This is the sole way to obtain a `DecodeSampleSet`.
+    pub fn new(units: Vec<Vec<u8>>) -> Option<Self> {
+        (units.len() >= MIN_SAMPLE_UNITS).then_some(Self(units))
+    }
+
+    /// The proven-sufficient samples. Guaranteed `>= MIN_SAMPLE_UNITS` in length.
+    pub fn units(&self) -> &[Vec<u8>] {
+        &self.0
+    }
+
+    /// Number of samples — always `>= MIN_SAMPLE_UNITS`.
+    pub fn len(&self) -> usize {
+        self.0.len()
+    }
+
+    /// Always `false` (a `DecodeSampleSet` never holds fewer than `MIN_SAMPLE_UNITS`);
+    /// provided so the type satisfies the usual `len`/`is_empty` pairing.
+    pub fn is_empty(&self) -> bool {
+        false
+    }
+}
+
 /// 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.
@@ -57,7 +115,7 @@ pub struct DiscInputs {
     pub volume_label: Option<String>,
 }
 
-/// A lazy view of a disc's AACS material, handed to [`KeySource::get_uk`] so a
+/// A lazy view of a disc's AACS material, handed to [`KeySource::get_unit_keys`] so a
 /// source can drive the derivation chain without holding the disc reader.
 ///
 /// "Lazy" by contract: each accessor returns only what the source asks for, so a
@@ -175,10 +233,34 @@ impl ResolveCtx for DiscInputsCtx<'_> {
 /// ([`resolve_and_apply`]) tries each source in order and validates the returned
 /// keys against real ciphertext before committing them, so a wrong key from one
 /// source transparently falls through to the next.
+///
+/// Two explicit resolve operations, one per key kind — never one overloaded call
+/// whose meaning depends on how many keys came back:
+/// * [`get_unit_keys`](Self::get_unit_keys) — the disc's base per-CPS-unit Unit
+///   Keys (index space = CPS-unit number). The common path for every disc.
+/// * [`get_fmts_indexes`](Self::get_fmts_indexes) — the AACS 2.1 forensic index
+///   keys (index space = forensic index 1..N). Defaults to empty: a source with
+///   no forensic material opts out, and only an FMTS disc ever asks.
+///
+/// What each source must do to answer is the source's own business: a keydb keys
+/// on `disc_hash` and reads no samples; the online source submits the ctx's
+/// content samples (a base batch for `get_unit_keys`, an index-1 anchor batch for
+/// `get_fmts_indexes`) to the key service.
 pub trait KeySource {
-    /// Resolve this disc's terminal Unit Keys from this source. An empty `Vec`
-    /// is a genuine "no key here"; `Err` is a source failure.
-    fn get_uk(&self, ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error>;
+    /// Resolve this disc's base per-CPS-unit Unit Keys from this source. An empty
+    /// `Vec` is a genuine "no key here"; `Err` is a source failure.
+    fn get_unit_keys(&self, ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error>;
+
+    /// Resolve this disc's AACS 2.1 forensic index keys — the per-index keys the
+    /// base Unit Key cannot open (see [`crate::aacs::segment`]) — ordered by
+    /// forensic index (element `i` carries `UnitKey.idx == i`, forensic index
+    /// `i + 1`). The source hands back the COMPLETE set it holds; the caller
+    /// trusts any non-empty result as all of them and never assumes a fixed count.
+    /// Defaults to empty: a source with no forensic material (a plain keydb, the
+    /// mapfile) opts out, and only an FMTS disc's mux ever calls this.
+    fn get_fmts_indexes(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error> {
+        Ok(Vec::new())
+    }
 
     /// The AACS host certificate(s) this source can supply for the live-drive
     /// SCSI mutual-auth handshake (the OEM/AACS baseline route). `mkb` is the
@@ -215,7 +297,7 @@ pub fn resolve_and_apply(
 /// [`crate::aacs::trace::ResolutionTrace`] recording, per source, what happened — for
 /// applications to render. ZERO English; the trace is typed enums only.
 ///
-/// One-shot per source: each source's [`KeySource::get_uk`] is called exactly
+/// One-shot per source: each source's [`KeySource::get_unit_keys`] is called exactly
 /// once with a [`DiscInputsCtx`] over `inputs`. Non-empty Unit Keys are mapped
 /// to terminal [`Key::Unit`]s and applied via [`crate::Disc::decrypt_with`],
 /// which validates them against `inputs.samples` and only mutates the disc on
@@ -243,7 +325,7 @@ pub fn resolve_and_apply_traced(
     for source in sources {
         // `who` is the source's own stable identifier — no enum to map back to.
         let who = source.label().to_string();
-        match source.get_uk(&ctx) {
+        match source.get_unit_keys(&ctx) {
             Ok(uks) if !uks.is_empty() => {
                 // Positional index → canonical CPS-unit number (position + 1).
                 let unit_keys: Vec<(u32, [u8; 16])> = uks
@@ -294,7 +376,7 @@ pub fn resolve_and_apply_traced(
 /// decorator re-decrypts with the returned keys, which is the validation.
 pub fn fetch_unit_keys(sources: &[Box<dyn KeySource>], ctx: &dyn ResolveCtx) -> Vec<UnitKey> {
     for source in sources {
-        if let Ok(uks) = source.get_uk(ctx) {
+        if let Ok(uks) = source.get_unit_keys(ctx) {
             if !uks.is_empty() {
                 return uks;
             }
@@ -303,35 +385,92 @@ pub fn fetch_unit_keys(sources: &[Box<dyn KeySource>], ctx: &dyn ResolveCtx) ->
     Vec::new()
 }
 
-/// Build the read-time key-fetch closure from the disc's public AACS inputs and
-/// a way to (re)build the application's key sources. The decorator calls it with
-/// the still-scrambled unit ciphertext when no held key opens that unit; it runs
-/// [`fetch_unit_keys`] with those bytes as `samples` and returns any keys.
+/// The forensic counterpart to [`fetch_unit_keys`]: drive `sources` in order and
+/// return the first source's non-empty AACS 2.1 forensic index set. `ctx` carries
+/// the index-1 anchor batch (the mux, which owns disc geometry, gathers it and
+/// injects it as the ctx's samples); a source that needs no samples (a keydb
+/// keying on `disc_hash`) ignores them. Whatever the winning source returns —
+/// ≥ 1 key — is trusted as the COMPLETE ordered set; no fixed count is assumed.
+pub fn fetch_fmts_indexes(sources: &[Box<dyn KeySource>], ctx: &dyn ResolveCtx) -> Vec<UnitKey> {
+    for source in sources {
+        if let Ok(uks) = source.get_fmts_indexes(ctx) {
+            if !uks.is_empty() {
+                return uks;
+            }
+        }
+    }
+    Vec::new()
+}
+
+/// Build the read-time [`crate::sector::KeyFetch`] from the disc's public AACS
+/// inputs and a way to (re)build the application's key sources. The returned
+/// resolver has the two explicit operations the mux and recovery decorator call:
+/// [`unit_keys`](crate::sector::KeyFetch::unit_keys) drives [`fetch_unit_keys`]
+/// (base per-CPS-unit keys), [`fmts_indexes`](crate::sector::KeyFetch::fmts_indexes)
+/// drives [`fetch_fmts_indexes`] (the AACS 2.1 forensic set). Each is handed the
+/// caller's sample batch as the ctx's `samples`, so a source pulls whatever
+/// material it needs.
 ///
-/// One builder, used by every read path (sweep / patch / mux) and by every
-/// consumer (CLI, autorip) — neither application contains the fetch logic, only
-/// its key-source config. Returns a **shared, stateless** [`crate::sector::KeyFetch`]
-/// (`Arc<Fn>`): build it once, clone it into each read path. `make_sources` is
-/// invoked per fetch (the cold path, ~once per CPS unit) so the closure stays
+/// One builder, used by every read path (sweep / patch / mux) and every consumer
+/// (CLI, autorip) — neither application contains the fetch logic, only its
+/// key-source config. Cheap to clone; build once, clone into each read path.
+/// `make_sources` is invoked per fetch (the cold path) so the resolver stays
 /// `Send + Sync` without requiring `KeySource: Send`.
 pub fn key_fetch(
     inputs: DiscInputs,
     make_sources: std::sync::Arc<dyn Fn() -> Vec<Box<dyn KeySource>> + Send + Sync>,
 ) -> crate::sector::KeyFetch {
-    std::sync::Arc::new(move |samples: &[Vec<u8>]| -> Vec<[u8; 16]> {
-        let sources = make_sources();
-        let mut di = inputs.clone();
-        di.samples = samples.to_vec();
-        // Parse Unit_Key_RO.inf at the disc's OWN stride (carried on `inputs`):
-        // an online /decode reply that returns a VUK (not a terminal UK) then
-        // derives unit keys from `enc_title_keys`, which a V10 disc parses at the
-        // 48-byte stride — hardcoding the V20 stride here corrupted them.
-        let ctx = DiscInputsCtx::new(&di);
-        fetch_unit_keys(&sources, &ctx)
-            .into_iter()
-            .map(|u| u.key)
-            .collect()
-    })
+    // One driver behind both operations: rebuild the sources, inject `samples`
+    // as the ctx's content samples, run `drive` (the per-kind fetch), map the
+    // resolved UnitKeys to raw keys. Memoized by the fingerprint of the sample
+    // batch: the resolved keys are disc-level (a clip's index / CPS keys are
+    // identical for every title that references it), so the first batch resolves
+    // over the network and every repeat is answered from the cache with no
+    // request. Empty replies are cached too — a key the service lacks for a batch
+    // won't appear on a re-ask, so re-hitting the network buys nothing. Each
+    // operation gets its OWN cache: a base batch and a forensic anchor never
+    // collide, and the same bytes could legitimately resolve differently per op.
+    // The per-kind driver: `fetch_unit_keys` or `fetch_fmts_indexes`.
+    type FetchDriver = fn(&[Box<dyn KeySource>], &dyn ResolveCtx) -> Vec<UnitKey>;
+    fn make_op(
+        inputs: DiscInputs,
+        make_sources: std::sync::Arc<dyn Fn() -> Vec<Box<dyn KeySource>> + Send + Sync>,
+        drive: FetchDriver,
+    ) -> crate::sector::KeyFetchFn {
+        let cache: std::sync::Arc<std::sync::Mutex<std::collections::HashMap<u64, Vec<[u8; 16]>>>> =
+            std::sync::Arc::new(std::sync::Mutex::new(std::collections::HashMap::new()));
+        std::sync::Arc::new(move |samples: &[Vec<u8>]| -> Vec<[u8; 16]> {
+            let fp = {
+                use std::hash::{Hash, Hasher};
+                let mut h = std::collections::hash_map::DefaultHasher::new();
+                samples.len().hash(&mut h);
+                for s in samples {
+                    s.hash(&mut h);
+                }
+                h.finish()
+            };
+            if let Some(hit) = cache.lock().unwrap_or_else(|e| e.into_inner()).get(&fp) {
+                return hit.clone();
+            }
+            let sources = make_sources();
+            let mut di = inputs.clone();
+            di.samples = samples.to_vec();
+            // Parse Unit_Key_RO.inf at the disc's OWN stride (carried on `inputs`):
+            // an online /decode reply that returns a VUK (not a terminal UK) then
+            // derives unit keys from `enc_title_keys`, which a V10 disc parses at
+            // the 48-byte stride — hardcoding the V20 stride here corrupted them.
+            let ctx = DiscInputsCtx::new(&di);
+            let keys: Vec<[u8; 16]> = drive(&sources, &ctx).into_iter().map(|u| u.key).collect();
+            cache
+                .lock()
+                .unwrap_or_else(|e| e.into_inner())
+                .insert(fp, keys.clone());
+            keys
+        })
+    }
+    let unit = make_op(inputs.clone(), make_sources.clone(), fetch_unit_keys);
+    let fmts = make_op(inputs, make_sources, fetch_fmts_indexes);
+    crate::sector::KeyFetch::new(unit, fmts)
 }
 
 /// Read up to `n` ENCRYPTED 6144-byte aligned units from `title`'s body, raw (no
@@ -425,6 +564,46 @@ mod tests {
     use crate::aacs::types::UnitKey;
     use std::sync::{Arc, Mutex};
 
+    fn units(n: usize) -> Vec<Vec<u8>> {
+        (0..n).map(|i| vec![i as u8; 4]).collect()
+    }
+
+    // ── DecodeSampleSet: the online request can't be built under-sized ─────────
+
+    /// Fewer than MIN_SAMPLE_UNITS → no set. Mutation: accepting a short slice
+    /// resurrects the exact autorip bug (a 4-sample request silently skipped /
+    /// read as "service down").
+    #[test]
+    fn decode_sample_set_rejects_under_min() {
+        for n in 0..MIN_SAMPLE_UNITS {
+            assert!(
+                DecodeSampleSet::new(units(n)).is_none(),
+                "{n} samples (< {MIN_SAMPLE_UNITS}) must not build a DecodeSampleSet"
+            );
+        }
+    }
+
+    /// Exactly the minimum, and above it, construct — and expose all samples.
+    #[test]
+    fn decode_sample_set_accepts_min_and_above() {
+        let exact = DecodeSampleSet::new(units(MIN_SAMPLE_UNITS)).expect("min builds");
+        assert_eq!(exact.len(), MIN_SAMPLE_UNITS);
+        assert_eq!(exact.units().len(), MIN_SAMPLE_UNITS);
+        assert!(!exact.is_empty());
+
+        let more = DecodeSampleSet::new(units(MIN_SAMPLE_UNITS + 5)).expect("above min builds");
+        assert_eq!(more.len(), MIN_SAMPLE_UNITS + 5);
+    }
+
+    /// The wrapped units round-trip byte-for-byte (the request carries exactly what
+    /// was gathered — no reordering/truncation).
+    #[test]
+    fn decode_sample_set_preserves_units() {
+        let raw = units(MIN_SAMPLE_UNITS);
+        let set = DecodeSampleSet::new(raw.clone()).unwrap();
+        assert_eq!(set.units(), raw.as_slice());
+    }
+
     // ── KeySource default-method behaviour ────────────────────────────────────
 
     /// KeySource::host_certs() defaults to empty regardless of the MKB argument.
@@ -436,7 +615,7 @@ mod tests {
     fn key_source_host_certs_defaults_to_empty() {
         struct MinimalSource;
         impl KeySource for MinimalSource {
-            fn get_uk(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error> {
+            fn get_unit_keys(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error> {
                 Ok(Vec::new())
             }
         }
@@ -493,7 +672,7 @@ mod tests {
     fn trace_who_is_the_source_label_verbatim() {
         struct LabeledSource(&'static str);
         impl KeySource for LabeledSource {
-            fn get_uk(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error> {
+            fn get_unit_keys(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error> {
                 Ok(Vec::new())
             }
             fn label(&self) -> &'static str {
@@ -550,19 +729,19 @@ mod tests {
 
     struct EmptySource;
     impl KeySource for EmptySource {
-        fn get_uk(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error> {
+        fn get_unit_keys(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error> {
             Ok(Vec::new())
         }
     }
     struct ErroringSource;
     impl KeySource for ErroringSource {
-        fn get_uk(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error> {
+        fn get_unit_keys(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error> {
             Err(Error::AacsNoKeys)
         }
     }
     struct HasKey([u8; 16]);
     impl KeySource for HasKey {
-        fn get_uk(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error> {
+        fn get_unit_keys(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error> {
             Ok(vec![UnitKey::new(0, self.0)])
         }
     }
@@ -605,7 +784,7 @@ mod tests {
             seen: Arc<Mutex<Vec<Vec<u8>>>>,
         }
         impl KeySource for Probe {
-            fn get_uk(&self, ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error> {
+            fn get_unit_keys(&self, ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error> {
                 if let Ok(s) = ctx.samples(8) {
                     self.seen.lock().unwrap().extend(s);
                 }
@@ -625,7 +804,7 @@ mod tests {
 
         let cb = key_fetch(empty_inputs(), make);
         let samples = vec![vec![0xEEu8; crate::aacs::content::ALIGNED_UNIT_LEN]];
-        let got = cb(&samples);
+        let got = cb.unit_keys(&samples);
         assert_eq!(
             got,
             vec![key],
@@ -639,6 +818,85 @@ mod tests {
         assert_eq!(*builds.lock().unwrap(), 1, "make_sources invoked per fetch");
     }
 
+    /// The two `KeyFetch` operations route to the two DISTINCT trait methods:
+    /// `unit_keys` drives `get_unit_keys`, `fmts_indexes` drives
+    /// `get_fmts_indexes`. A source that returns different keys per method proves
+    /// the seam no longer collapses "1 base key" and "the forensic set" into one
+    /// overloaded call — the operation, not the return length, decides which.
+    #[test]
+    fn key_fetch_routes_unit_and_fmts_to_distinct_source_methods() {
+        const BASE: [u8; 16] = [0xB0; 16];
+        const F1: [u8; 16] = [0xF1; 16];
+        const F2: [u8; 16] = [0xF2; 16];
+
+        struct TwoOp;
+        impl KeySource for TwoOp {
+            fn get_unit_keys(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error> {
+                Ok(vec![UnitKey::new(0, BASE)])
+            }
+            fn get_fmts_indexes(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error> {
+                Ok(vec![UnitKey::new(0, F1), UnitKey::new(1, F2)])
+            }
+        }
+
+        let make: Arc<dyn Fn() -> Vec<Box<dyn KeySource>> + Send + Sync> =
+            Arc::new(|| vec![Box::new(TwoOp) as Box<dyn KeySource>]);
+        let cb = key_fetch(empty_inputs(), make);
+        let samples = vec![vec![0x01u8; 4]];
+
+        assert_eq!(
+            cb.unit_keys(&samples),
+            vec![BASE],
+            "unit_keys resolves the base Unit Key via get_unit_keys"
+        );
+        assert_eq!(
+            cb.fmts_indexes(&samples),
+            vec![F1, F2],
+            "fmts_indexes resolves the forensic set (any length) via get_fmts_indexes"
+        );
+    }
+
+    /// `KeyFetch::unit_only` serves base keys but NEVER a forensic set — the
+    /// contract the sweep/patch recovery decorator relies on (it resolves CPS
+    /// units only). Its `fmts_indexes` is unconditionally empty.
+    #[test]
+    fn key_fetch_unit_only_never_serves_forensic() {
+        let f = crate::sector::KeyFetch::unit_only(std::sync::Arc::new(|_| vec![[0xAA; 16]]));
+        assert_eq!(f.unit_keys(&[vec![0u8; 4]]), vec![[0xAA; 16]]);
+        assert!(
+            f.fmts_indexes(&[vec![0u8; 4]]).is_empty(),
+            "unit_only resolver yields no forensic keys"
+        );
+    }
+
+    /// `get_fmts_indexes` defaults to empty, so a base-only source (a keydb) opts
+    /// out of the forensic path without implementing it. `fetch_fmts_indexes` then
+    /// falls through to the next source, exactly like the unit-key driver.
+    #[test]
+    fn fetch_fmts_indexes_skips_default_optout_source() {
+        struct BaseOnly; // uses the default (empty) get_fmts_indexes
+        impl KeySource for BaseOnly {
+            fn get_unit_keys(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error> {
+                Ok(vec![UnitKey::new(0, [0x11; 16])])
+            }
+        }
+        struct Forensic;
+        impl KeySource for Forensic {
+            fn get_unit_keys(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error> {
+                Ok(Vec::new())
+            }
+            fn get_fmts_indexes(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error> {
+                Ok(vec![UnitKey::new(0, [0x77; 16])])
+            }
+        }
+        let inputs = empty_inputs();
+        let ctx = DiscInputsCtx::new(&inputs);
+        let sources: Vec<Box<dyn KeySource>> = vec![Box::new(BaseOnly), Box::new(Forensic)];
+        let got = fetch_fmts_indexes(&sources, &ctx);
+        assert_eq!(got.len(), 1);
+        assert_eq!(got[0].key, [0x77; 16], "the base-only source is skipped");
+    }
+
     /// #4 regression: encrypted content NOT at the extent midpoint (a late-
     /// starting feature, or a midpoint landing in clear nav) must still be
     /// sampled — empty samples make `decrypt_with` skip wrong-key validation.

src/lib.rs

@@ -98,7 +98,7 @@ pub const VERSION_LABEL: &str = concat!(env!("FREEMKV_VERSION"), env!("GIT_SUFFI
 
 /// The muxing/writing-application string written into MKV output
 /// (`"freemkv <version> (g<hash>)"`).
-pub const MUX_APP: &str = concat!("freemkv ", env!("FREEMKV_VERSION"), env!("GIT_SUFFIX"));
+pub(crate) const MUX_APP: &str = concat!("freemkv ", env!("FREEMKV_VERSION"), env!("GIT_SUFFIX"));
 
 pub mod aacs;
 pub(crate) mod clpi;
@@ -187,7 +187,10 @@ pub use identity::DriveId;
 // don't touch `DecryptKeys` directly — `DiscStream::new(reader, title, keys, …)`
 // accepts whatever `Disc::decrypt_keys()` returned. `decrypt_sectors()` is
 // for callers that operate on raw sector buffers (e.g. ISO patching).
-pub use decrypt::{DecryptKeys, decrypt_sectors, decrypt_threads, set_decrypt_threads};
+pub use decrypt::{
+    AacsKeyMap, DecryptKeys, decrypt_sectors, decrypt_sectors_mapped, decrypt_threads,
+    set_decrypt_threads,
+};
 
 // ─── Disc structure ─────────────────────────────────────────────────────────
 //
@@ -248,6 +251,7 @@ pub use mux::{InputOptions, StreamUrl, input, output, parse_url};
 // single decrypt-on-read decorator (AACS / CSS / none) — wrap any
 // `SectorSource` to get plaintext sectors out.
 pub use mux::build_iso_pipeline;
+pub use mux::resolve_mux_key_map;
 pub use scsi::{DriveInfo, ScsiSense, ScsiTransport, drive_has_disc, list_drives};
 pub use sector::{
     DecryptingSectorSource, FileSectorSink, FileSectorSource, KeyFetch, PrefetchedSectorSource,

src/mux/demux_sink.rs

@@ -31,6 +31,10 @@ use std::io::{self, BufWriter, Write};
 use std::path::{Path, PathBuf};
 
 /// Filename-naming strategy for the per-track files.
+// `allow(dead_code)`: the sink honours all variants, but only the `#[default]` is
+// constructed today (`output()` builds `DemuxOptions::default()`). The alternates
+// are a staged option surface awaiting the CLI `--naming` flag (not yet wired).
+#[allow(dead_code)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub enum Naming {
     /// `<base> <track> <lang> <codec> [DELAY <n>ms].<ext>` — human-readable.
@@ -55,6 +59,9 @@ pub enum DelayMode {
 }
 
 /// Chapter export format.
+// `allow(dead_code)`: only the `#[default]` XML variant is constructed today (via
+// `DemuxOptions::default()`); OGM/Both await the CLI `--chapters` flag.
+#[allow(dead_code)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub enum ChaptersFmt {
     /// mkvmerge chapter XML.

src/mux/disc.rs

@@ -139,14 +139,14 @@ pub struct DiscStream {
     // Adaptive batch sizer — preferred comes from the caller
     // (detect_max_batch_sectors), shrinks/grows based on read outcomes.
     adaptive: AdaptiveBatch,
-    pub errors: u64,
+    errors: u64,
     /// Cumulative bytes actually skipped (zero-filled) on read error.
     /// Distinct from `errors`, which counts skip *events*: one event can
     /// cover a whole AACS unit (`unit_align` sectors = 6144 bytes), so
     /// `errors * 2048` understates real loss by the alignment factor.
     /// Consumers estimating lost video time must scale by this, not by
     /// the event count.
-    pub lost_bytes: u64,
+    lost_bytes: u64,
     pub skip_errors: bool,
     /// When set and the token is cancelled, fill_extents returns Err(Halted)
     /// at the next retry boundary. Unlike skip_errors, this propagates the
@@ -351,6 +351,27 @@ impl DiscStream {
         self
     }
 
+    /// Install a proactive [`AacsKeyMap`](crate::decrypt::AacsKeyMap) on the inline
+    /// live-drive path — the counterpart to what
+    /// [`build_iso_pipeline`](crate::mux::resolve::build_iso_pipeline) does for the
+    /// file-backed highway. The map is the title's read plan: it decides which unit
+    /// each LBA is and, for an FMTS forensic segment, which phase is ours. The
+    /// extent walk is rewritten to the read plan so **only our-phase units are read
+    /// off the drive** (the alternate device-group units are never fetched,
+    /// decrypted, or muxed), and the map is installed so each unit decrypts with its
+    /// mapped key. A non-forensic map returns the extents unchanged, so a plain
+    /// single/multi-CPS disc reads exactly as before.
+    pub fn with_key_map(mut self, map: std::sync::Arc<crate::decrypt::AacsKeyMap>) -> Self {
+        self.extents = map.read_plan(&self.extents, self.unit_align.max(1) as u32);
+        self.bytes_total_extents = self
+            .extents
+            .iter()
+            .map(|e| e.sector_count as u64 * 2048)
+            .sum();
+        self.reader.set_key_map(map);
+        self
+    }
+
     fn is_halted(&self) -> bool {
         self.halt
             .as_ref()
@@ -1118,6 +1139,44 @@ mod tests {
         );
     }
 
+    /// `with_key_map` on the inline live-drive path applies the same FMTS read plan
+    /// the file-backed highway uses: within a forensic segment only our-phase units
+    /// survive the extent walk, so the alternate device-group units are never read.
+    #[test]
+    fn with_key_map_reads_only_our_phase_units() {
+        use crate::decrypt::{AacsKeyMap, DecryptKeys, Phase};
+        // AACS keys → unit_align = 3, so a unit is 3 sectors and the phase filter
+        // engages. Key contents are irrelevant to the read plan.
+        let aacs = DecryptKeys::Aacs {
+            unit_keys: vec![(0, [0u8; 16]), (1, [1u8; 16])],
+            read_data_key: None,
+            format: ContentFormat::BdTs,
+        };
+        // 100 units (300 sectors). A 10-unit Even forensic segment at LBA [30,60):
+        // even units (30,36,42,48,54) are ours; odd (33,39,45,51,57) are dropped.
+        let map = AacsKeyMap::from_ranges_phased(vec![(30, 60, 1, Phase::Even)], 0);
+        let stream = DiscStream::new(
+            Box::new(ZeroReader { capacity: 300 }),
+            synthetic_title(300),
+            aacs,
+            8,
+            ContentFormat::BdTs,
+        )
+        .with_key_map(std::sync::Arc::new(map));
+        let total: u32 = stream.extents.iter().map(|e| e.sector_count).sum();
+        assert_eq!(
+            total,
+            300 - 5 * 3,
+            "exactly the 5 alternate-phase units (15 sectors) are dropped from the read walk"
+        );
+        assert!(
+            stream.extents.len() > 1,
+            "the forensic segment split the single extent into our-phase-only runs"
+        );
+        // The progress denominator tracks the reduced read set.
+        assert_eq!(stream.bytes_total_extents, total as u64 * 2048);
+    }
+
     /// Recording `SectorSource`: logs every `(lba, count)` request and
     /// returns `Err` whenever the requested range covers `bad_sector`.
     /// Successful reads return zeroed sectors (which are NOT

src/mux/fvi_sink.rs

@@ -157,31 +157,19 @@ impl FviSink {
     ///
     /// `source_path` / `source_title` record where the index was built from
     /// (the input URL path + the 0-based title index); they are carried into the
-    /// header's `source` object. The medium defaults to `file` — callers with a
-    /// known medium / playlist / volume use [`FviSink::create_with_source`].
+    /// header's `source` object. The remaining provenance (medium, playlist,
+    /// volume) takes its `SourceInfo` defaults — no caller needs to override them.
     pub fn create(
         path: &Path,
         title: &DiscTitle,
         source_path: String,
         source_title: usize,
     ) -> io::Result<Self> {
-        Self::create_with_source(
-            path,
-            title,
-            SourceInfo {
-                path: source_path,
-                title: source_title,
-                ..SourceInfo::default()
-            },
-        )
-    }
-
-    /// Create the sink with a fully-specified [`SourceInfo`] provenance root.
-    pub fn create_with_source(
-        path: &Path,
-        title: &DiscTitle,
-        source: SourceInfo,
-    ) -> io::Result<Self> {
+        let source = SourceInfo {
+            path: source_path,
+            title: source_title,
+            ..SourceInfo::default()
+        };
         let file = File::create(path)?;
 
         let video_track = title

src/mux/mkvstream.rs

@@ -323,17 +323,14 @@ fn extract_mvc_params(data: &[u8]) -> Option<(Vec<u8>, Vec<u8>)> {
 }
 
 impl MkvStream {
-    /// Create for writing PES frames → MKV container.
-    /// Codec privates come from title.codec_privates (populated by input stream).
-    pub fn create(writer: Box<dyn WriteSeek + Send>, title: &DiscTitle) -> io::Result<Self> {
-        Self::create_at(writer, title, None)
-    }
-
-    /// As [`create`](Self::create), but `output_path` (when known) enables the
-    /// `--log-level 3` opening-frame capture to `<output>.opening.bin`. A `None`
-    /// path (e.g. an in-memory / stdio sink) silently skips the side-file
-    /// capture; the per-track TrackEntry dump still fires.
-    pub fn create_at(
+    /// Create for writing PES frames → MKV container. Codec privates come from
+    /// `title.codec_privates` (populated by the input stream).
+    ///
+    /// `output_path` (when known) enables the `--log-level 3` opening-frame
+    /// capture to `<output>.opening.bin`; `None` (e.g. an in-memory / stdio sink)
+    /// silently skips the side-file capture — the per-track TrackEntry dump still
+    /// fires either way.
+    pub fn create(
         writer: Box<dyn WriteSeek + Send>,
         title: &DiscTitle,
         output_path: Option<&std::path::Path>,
@@ -1409,7 +1406,7 @@ mod tests {
             streams: vec![Stream::Video(dep)],
             ..DiscTitle::empty()
         };
-        let s = MkvStream::create(Box::new(Cursor::new(Vec::new())), &title)
+        let s = MkvStream::create(Box::new(Cursor::new(Vec::new())), &title, None)
             .expect("create must succeed, not panic");
         assert!(
             s.mvc.is_none(),

src/mux/mod.rs

@@ -108,15 +108,17 @@ pub(crate) mod tsmux;
 #[allow(dead_code)]
 pub(crate) mod videomap;
 
-pub use demux_sink::{ChaptersFmt, DelayMode, DemuxOptions, DemuxSink, Naming};
+// `demux://` and `fvi://` sinks are constructed internally by `output()` via the
+// direct `super::demux_sink::` / `super::fvi_sink::` paths — no re-export needed,
+// and no consumer names these types, so they are not public API.
 pub use disc::DiscStream;
-pub use fvi_sink::FviSink;
 pub use m2ts::M2tsStream;
 pub use mkvstream::MkvStream;
 pub use network::NetworkStream;
 pub use null::NullStream;
 pub use pipelined_stream::PipelinedPesStream;
 pub use resolve::build_iso_pipeline;
+pub use resolve::resolve_mux_key_map;
 pub use resolve::{InputOptions, StreamUrl, input, output, parse_url};
 pub use stdio::StdioStream;
 

src/mux/resolve.rs

@@ -344,9 +344,7 @@ pub fn input(url: &str, opts: &InputOptions) -> io::Result<Box<dyn crate::pes::S
             // unchanged (decrypt_keys_for_title short-circuits to decrypt_keys).
             let (keys, title_is_clear) =
                 match crate::io::file_sector_source::FileSectorSource::open(path) {
-                    Ok(mut crack_reader) => {
-                        disc.decrypt_keys_for_title_checked(idx, &mut crack_reader, 64)
-                    }
+                    Ok(mut crack_reader) => disc.decrypt_keys_for_title(idx, &mut crack_reader, 64),
                     Err(_) => (disc.decrypt_keys(), false),
                 };
             // Per-title decrypt gate (parallel to the disc-wide gate above): on
@@ -358,12 +356,11 @@ pub fn input(url: &str, opts: &InputOptions) -> io::Result<Box<dyn crate::pes::S
             // case must NOT raise a false E7023.
             disc.ensure_title_decryptable(opts.raw, &keys, title_is_clear)
                 .map_err(|e| -> io::Error { e.into() })?;
-            // Upfront FMTS gate, parallel to the unit-key gate above. With
-            // BYPASS_FMTS_KEY this is a no-op and a 2.1 disc's forensic units are
-            // concealed as ordinary decrypt loss below; without it, a 2.1 disc
-            // lacking segment keys fails here rather than emitting a holed mux.
-            disc.ensure_forensic_segments_decryptable(opts.raw)
-                .map_err(|e| -> io::Error { e.into() })?;
+            // FMTS (AACS 2.1) forensic segments are sourced + fail-loud-checked
+            // downstream by `resolve_mux_key_map`/`resolve_fmts_key_map`, which hold
+            // the key-fetch closure and can actually attempt resolution. (An older
+            // upfront blanket-reject gate lived here; it predated the resolver and
+            // rejected every 2.1 disc before a source could be tried.)
             // 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. Skipped in
@@ -480,7 +477,7 @@ pub fn output(
                     IO_BUF_SIZE,
                     crate::io::WritebackFile::create_with_size_hint(path, title.size_bytes)?,
                 ));
-            Ok(Box::new(MkvStream::create_at(writer, title, Some(path))?))
+            Ok(Box::new(MkvStream::create(writer, title, Some(path))?))
         }
         StreamUrl::M2ts { ref path } => {
             validate_file_path(path, "m2ts")?;
@@ -532,8 +529,7 @@ pub fn output(
         // `fvi://` writes the per-picture video index (`docs/FVI_FORMAT.md`).
         // The bare `output()` arm records the resolver path as the provenance
         // `source.path` and defaults the title index to 0 (the resolver carries
-        // no title-index context — the CLI follow-up passes the real medium /
-        // title via `FviSink::create_with_source`).
+        // no title-index context).
         StreamUrl::Fvi { ref path } => {
             validate_file_path(path, "fvi")?;
             Ok(Box::new(super::fvi_sink::FviSink::create(
@@ -600,6 +596,391 @@ fn build_demux_state(title: &DiscTitle, format: ContentFormat) -> DemuxState {
     (parsers, pid_to_track, ts, ps)
 }
 
+/// Resolve the proactive [`AacsKeyMap`](crate::decrypt::AacsKeyMap) for a title
+/// before muxing. It decides which held unit key decrypts each of the title's
+/// LBA ranges and secures any key the pool is missing through the app's
+/// configured source (`fetch`) up front, never reactively per unit at mux time.
+///
+/// This is what ends the key-server storm. The old mux decrypted a unit, checked
+/// whether the plaintext looked like clean MPEG-TS, and — because authored-bad
+/// content never reaches that bar — re-asked the key service for a key it already
+/// held. There is no per-unit byte pattern that separates "correctly decrypted
+/// but authored-bad" from "still encrypted", so that check is unanswerable. Here
+/// we answer the answerable question instead: which CPS unit does each LBA range
+/// belong to, decided by the disc's key structure (validated once against real
+/// ciphertext samples, where the `is_clean` proof IS sound). The mux then just
+/// decrypts each unit with its mapped key and trusts it.
+///
+/// Single-CPS (the overwhelming majority, incl. every single-key UHD) is the
+/// trivial map: one key everywhere, no sampling. Multi-CPS assigns each extent to
+/// the key that opens a real sample from it; a bad-content extent no sample can
+/// classify inherits its predecessor's key (contiguity). FMTS segment mapping
+/// layers onto the same structure.
+/// FMTS (AACS 2.1) branch of [`resolve_mux_key_map`]. Returns `Some(map)` when the
+/// disc carries `IndividualSegment.tbl` AND a key source is configured; `None`
+/// otherwise (not FMTS, or no source — the caller's base-Unit-Key path then
+/// applies, and the forensic units garble and are dropped by the demux).
+///
+/// The forensic segments each carry an **index** tag (1..32) selecting one of 32
+/// **index keys** the base Unit Key cannot open (see [`crate::aacs::segment`]).
+/// This resolves those keys up front from the configured source — sending, per
+/// index, a batch of same-index units the service maps to that index's key — adds
+/// them to the pool, and builds a per-segment LBA→key map. Applying a segment's
+/// key over its whole range decodes the ~40 units of that index's interleave half
+/// to clean TS and garbles the other ~40 (the alternate half), which the demux
+/// then drops, yielding one coherent stream. The base Unit Key covers everything
+/// outside a segment.
+fn resolve_fmts_key_map(
+    reader: &mut dyn SectorSource,
+    title: &DiscTitle,
+    keys: &mut crate::decrypt::DecryptKeys,
+    fetch: Option<&crate::sector::KeyFetch>,
+    format: ContentFormat,
+) -> io::Result<Option<crate::decrypt::AacsKeyMap>> {
+    use crate::aacs::content::{ALIGNED_UNIT_LEN, aacs_unit_encrypted, decrypt_unit, is_clean};
+    use crate::aacs::segment::{clip_byte_to_lba, parse_individual_segments};
+
+    // Load the segment map; absent → not an FMTS disc.
+    let Ok(udf) = crate::udf::read_filesystem(reader) else {
+        return Ok(None);
+    };
+    let Ok(tbl) = udf.read_file(reader, "/AACS/IndividualSegment.tbl") else {
+        return Ok(None);
+    };
+    let Some(segments) = parse_individual_segments(&tbl) else {
+        return Ok(None);
+    };
+    if segments.is_empty() {
+        return Ok(None);
+    }
+    // This IS an FMTS disc, so the forensic index keys are REQUIRED — exactly like
+    // a Unit Key. Without a configured key source we cannot obtain them, so we
+    // cannot produce a complete rip: fail loud rather than silently drop the
+    // forensic segments. (The caller may still choose `--raw`, which never reaches
+    // this path.)
+    let Some(fetch) = fetch else {
+        return Err(crate::error::Error::FmtsKeyMissing.into());
+    };
+    tracing::info!(target: "freemkv::keysource", segments = segments.len(), extents = title.extents.len(), "fmts: begin index-key resolution");
+
+    // Read aligned unit `index` of `seg`: clip byte `start_spn*192 + index*6144`.
+    let read_unit =
+        |reader: &mut dyn SectorSource, seg: &crate::aacs::segment::Segment, index: usize| {
+            let clip_byte = seg.start_spn as u64 * 192 + index as u64 * ALIGNED_UNIT_LEN as u64;
+            let lba = clip_byte_to_lba(&title.extents, clip_byte)?;
+            let mut c = vec![0u8; ALIGNED_UNIT_LEN];
+            reader.read_sectors(lba, 3, &mut c, false).ok()?;
+            Some(c)
+        };
+    // ── ANCHOR — fetch the whole 32-key set from ONE index-1 batch. The key
+    //    service returns ALL forensic index keys ordered (element i = index i+1)
+    //    only for a canonical INDEX-1 sample that decrypts under the index-1 key.
+    //    A forensic segment interleaves TWO variants at the aligned-unit level, so
+    //    index-1's real content is one PHASE (even or odd units) and the alternate
+    //    is a different variant that won't decrypt. We don't know the phase a
+    //    priori, so try PHASE A (even) then PHASE B (odd): whichever is index-1's
+    //    content comes back with the full set. Both phases failing (across the
+    //    read-fault fallback over index-1 segments) ⇒ this disc has no FMTS keys.
+    //
+    //    The set's SIZE is whatever the source returns (≥ 1) — never assumed. 32
+    //    is all we have seen, but a disc with a different forensic index count is
+    //    not ruled out, so the map is sized to the returned `len()`, not a const.
+    //    ─────────────────────────────────────────────────────────────────────────
+    // Batch size = the key service's minimum-samples floor (same as the online
+    // source), drawn from ONE phase to land a clean single-variant half.
+    const BATCH_UNITS: usize = crate::keysource::MIN_SAMPLE_UNITS;
+    // Read-fault fallback: how many index-1 segments to attempt if the leading one
+    // is unreadable. The 2 phase requests happen per readable segment.
+    const MAX_ANCHOR_ATTEMPTS: usize = 16;
+    // Even units = p*2; odd units = p*2 + 1.
+    let read_phase_batch = |reader: &mut dyn SectorSource,
+                            seg: &crate::aacs::segment::Segment,
+                            phase_off: usize|
+     -> Option<Vec<Vec<u8>>> {
+        let mut batch: Vec<Vec<u8>> = Vec::with_capacity(BATCH_UNITS);
+        for p in 0..BATCH_UNITS {
+            batch.push(read_unit(reader, seg, p * 2 + phase_off)?);
+        }
+        Some(batch)
+    };
+    let mut index_keys: Vec<[u8; 16]> = Vec::new();
+    'anchor: for seg in segments
+        .iter()
+        .filter(|s| s.index == 1)
+        .take(MAX_ANCHOR_ATTEMPTS)
+    {
+        for phase_off in [0usize, 1usize] {
+            let Some(batch) = read_phase_batch(reader, seg, phase_off) else {
+                continue; // read fault on this phase — try the other / next segment
+            };
+            let fresh = fetch.fmts_indexes(&batch);
+            // Any non-empty reply is the source's COMPLETE ordered forensic set;
+            // trust it and stop. An empty reply = this phase/segment did not anchor.
+            if !fresh.is_empty() {
+                index_keys = fresh;
+                break 'anchor;
+            }
+        }
+    }
+    // The count is whatever the source returned — not a fixed 32. Sized here, used
+    // everywhere below.
+    let n_index = index_keys.len();
+    tracing::info!(target: "freemkv::keysource", held = n_index, "fmts: collection done");
+    // At least one forensic index key is required. None ⇒ no FMTS key for this
+    // disc from any source — fail loud like a missing Unit Key rather than emit
+    // forensic-holed output.
+    if index_keys.is_empty() {
+        return Err(crate::error::Error::FmtsKeyMissing.into());
+    }
+
+    // Map array position → forensic index (element i = index i+1); add each key to
+    // the pool and remember its slot by tag. `base_idx` is the Unit Key (slot 0).
+    let base_idx = 0usize;
+    let mut tag_slot: std::collections::HashMap<u16, usize> = std::collections::HashMap::new();
+    if let crate::decrypt::DecryptKeys::Aacs { unit_keys, .. } = keys {
+        for (i, k) in index_keys.iter().enumerate() {
+            let tag = (i + 1) as u16;
+            let slot = match unit_keys.iter().position(|(_, h)| h == k) {
+                Some(s) => s,
+                None => {
+                    let s = unit_keys.len();
+                    // CPS-unit id is cosmetic for the mapped decrypt (it indexes by
+                    // slot); use a high, distinct number for the forensic keys.
+                    unit_keys.push((1000 + s as u32, *k));
+                    s
+                }
+            };
+            tag_slot.insert(tag, slot);
+        }
+    }
+
+    // ── PROBE each index's phase. A forensic segment interleaves two variants at
+    //    the aligned-unit level; only ONE parity is this index's real content (the
+    //    other is the alternate variant — a different key, garbles under ours). For
+    //    each index, read a representative tagged segment and count clean decrypts
+    //    of its EVEN vs ODD units under that index's key: the clean half is the
+    //    index's phase. This is the ONE place `is_clean` runs — "the map must be
+    //    right", verified here, once — so the mux decrypt can then trust the map.
+    //    Phase is per-index and shared by every segment carrying that index. ──────
+    let mut phase_of_index: std::collections::HashMap<u16, crate::decrypt::Phase> =
+        std::collections::HashMap::new();
+    for (i, k) in index_keys.iter().enumerate() {
+        let tag = (i + 1) as u16;
+        let Some(seg) = segments.iter().find(|s| s.index == tag) else {
+            continue; // no segment carries this index on this feature — skip
+        };
+        let (mut even, mut odd) = (0usize, 0usize);
+        for p in 0..BATCH_UNITS {
+            for (phase_off, counter) in [(0usize, &mut even), (1usize, &mut odd)] {
+                if let Some(mut c) = read_unit(reader, seg, p * 2 + phase_off) {
+                    if aacs_unit_encrypted(&c, format) {
+                        decrypt_unit(&mut c, k);
+                        if is_clean(&c, format) {
+                            *counter += 1;
+                        }
+                    }
+                }
+            }
+        }
+        let phase = match even.cmp(&odd) {
+            std::cmp::Ordering::Greater => crate::decrypt::Phase::Even,
+            std::cmp::Ordering::Less => crate::decrypt::Phase::Odd,
+            std::cmp::Ordering::Equal => {
+                // Neither half decrypts clean under this index's key: the map would
+                // be wrong. Fail loud rather than emit a broken segment map.
+                tracing::warn!(target: "freemkv::keysource", index = tag, even, odd, "fmts: no clean phase under index key — refusing broken map");
+                return Err(crate::error::Error::FmtsKeyMissing.into());
+            }
+        };
+        phase_of_index.insert(tag, phase);
+    }
+
+    // ── Build the per-segment LBA ranges: each forensic segment → its tag's key
+    //    AND its index's phase. The mapped decrypt opens only that half and leaves
+    //    the alternate as ciphertext (the muxer drops untouched ciphertext) —
+    //    clean by construction, no garble. A segment straddling an extent boundary
+    //    is left unmapped and tallied (a hard failure below). ────────────────────
+    let mut ranges: Vec<(u32, u32, usize, crate::decrypt::Phase)> =
+        Vec::with_capacity(segments.len());
+    let mut unresolved = 0usize;
+    for seg in &segments {
+        let Some(&slot) = tag_slot.get(&seg.index) else {
+            unresolved += 1;
+            continue;
+        };
+        let phase = phase_of_index
+            .get(&seg.index)
+            .copied()
+            .unwrap_or(crate::decrypt::Phase::All);
+        let start_byte = seg.start_spn as u64 * 192;
+        let end_byte = (seg.end_spn as u64 + 1) * 192;
+        let (Some(a), Some(b)) = (
+            clip_byte_to_lba(&title.extents, start_byte),
+            clip_byte_to_lba(&title.extents, end_byte - 1),
+        ) else {
+            unresolved += 1;
+            continue;
+        };
+        // Only emit a contiguous within-extent range (segments are ~480 KB; a rare
+        // extent-straddle is left unresolved rather than given a wrong span).
+        if b >= a && (b - a) as u64 == (end_byte - 1 - start_byte) / 2048 {
+            ranges.push((a, b + 1, slot, phase));
+        } else {
+            unresolved += 1;
+        }
+    }
+    // Every forensic segment must map to an index key. Any that did not is a hole
+    // in the rip — with the full 32-key set in hand this should never happen, so
+    // treat it as a hard failure rather than silently emitting a garbled segment.
+    if unresolved != 0 {
+        return Err(crate::error::Error::FmtsKeyMissing.into());
+    }
+
+    Ok(Some(crate::decrypt::AacsKeyMap::from_ranges_phased(
+        ranges, base_idx,
+    )))
+}
+
+pub fn resolve_mux_key_map(
+    reader: &mut dyn SectorSource,
+    title: &DiscTitle,
+    keys: &mut crate::decrypt::DecryptKeys,
+    fetch: Option<&crate::sector::KeyFetch>,
+    format: ContentFormat,
+) -> io::Result<crate::decrypt::AacsKeyMap> {
+    use crate::aacs::content::{
+        ALIGNED_UNIT_LEN, ALIGNED_UNIT_SECTORS, aacs_unit_encrypted, decrypt_unit, is_clean,
+    };
+
+    let pool_len = match keys {
+        crate::decrypt::DecryptKeys::Aacs { unit_keys, .. } => unit_keys.len(),
+        // CSS / clear: no AACS map (the decorator's map path is AACS-only).
+        _ => return Ok(crate::decrypt::AacsKeyMap::single(0)),
+    };
+
+    // Secure the disc's key up front from the configured source when the pool is
+    // empty (a genuine "no key yet" — e.g. keydb miss, online-only disc).
+    if pool_len == 0 {
+        if let Some(f) = fetch {
+            let samples = crate::keysource::read_encrypted_units(reader, title, 8);
+            if !samples.is_empty() {
+                let fresh = f.unit_keys(&samples);
+                if let crate::decrypt::DecryptKeys::Aacs { unit_keys, .. } = keys {
+                    for k in fresh {
+                        if !unit_keys.iter().any(|(_, h)| *h == k) {
+                            let i = unit_keys.len() as u32;
+                            unit_keys.push((i, k));
+                        }
+                    }
+                }
+            }
+        }
+        // If the pool is STILL empty, this AACS-encrypted title needs a Unit Key we
+        // could not obtain from any source. That is the same situation as any known
+        // key we don't hold — fail loud at resolve time rather than deferring an
+        // opaque decrypt error (or, worse, emitting ciphertext) at mux time.
+        let empty = matches!(
+            keys,
+            crate::decrypt::DecryptKeys::Aacs { unit_keys, .. } if unit_keys.is_empty()
+        );
+        if empty {
+            return Err(crate::error::Error::DecryptFailed.into());
+        }
+        return Ok(crate::decrypt::AacsKeyMap::single(0));
+    }
+    // FMTS (AACS 2.1): if the disc carries `IndividualSegment.tbl`, the forensic
+    // segments need per-index keys the base Unit Key can't open. Resolve them up
+    // front from the configured source and build a per-segment map. Returns `None`
+    // when the disc is not FMTS, or no key source is configured (then the base UK
+    // path below applies and the forensic units garble → demux drops them).
+    if let Some(map) = resolve_fmts_key_map(reader, title, keys, fetch, format)? {
+        return Ok(map);
+    }
+    if pool_len == 1 {
+        // One CPS unit → one key everywhere. No structural walk, no sampling.
+        return Ok(crate::decrypt::AacsKeyMap::single(0));
+    }
+
+    // Multi-CPS: read a spread of real encrypted units from each extent and pick
+    // the held key that opens one (the `is_clean` proof is sound HERE — samples
+    // are guaranteed real content, not the authored-bad units that trip the mux).
+    let sample_units = |reader: &mut dyn SectorSource, start: u32, sectors: u32| -> Vec<Vec<u8>> {
+        let total_units = sectors / ALIGNED_UNIT_SECTORS;
+        let mut out = Vec::new();
+        if total_units == 0 {
+            return out;
+        }
+        const PROBES: u32 = 8;
+        for p in 1..=PROBES {
+            let unit = ((total_units as u64 * p as u64) / (PROBES as u64 + 1)) as u32;
+            if unit >= total_units {
+                continue;
+            }
+            let lba = start.saturating_add(unit.saturating_mul(ALIGNED_UNIT_SECTORS));
+            let mut buf = vec![0u8; ALIGNED_UNIT_LEN];
+            if reader
+                .read_sectors(lba, ALIGNED_UNIT_SECTORS as u16, &mut buf, false)
+                .is_ok()
+                && aacs_unit_encrypted(&buf, format)
+            {
+                out.push(buf);
+            }
+        }
+        out
+    };
+    let pick = |samples: &[Vec<u8>], pool: &[(u32, [u8; 16])]| -> Option<usize> {
+        for (i, (_, k)) in pool.iter().enumerate() {
+            if samples.iter().any(|s| {
+                let mut u = s.clone();
+                decrypt_unit(&mut u, k);
+                is_clean(&u, format)
+            }) {
+                return Some(i);
+            }
+        }
+        None
+    };
+
+    let mut ranges: Vec<(u32, u32, usize)> = Vec::with_capacity(title.extents.len());
+    let mut last_idx = 0usize;
+    for ext in &title.extents {
+        let samples = sample_units(reader, ext.start_lba, ext.sector_count);
+        // Snapshot the current pool for the pure `pick` closure.
+        let pool: Vec<(u32, [u8; 16])> = match keys {
+            crate::decrypt::DecryptKeys::Aacs { unit_keys, .. } => unit_keys.clone(),
+            _ => Vec::new(),
+        };
+        let mut idx = pick(&samples, &pool);
+        if idx.is_none() {
+            if let Some(f) = fetch {
+                if !samples.is_empty() {
+                    let fresh = f.unit_keys(&samples);
+                    if let crate::decrypt::DecryptKeys::Aacs { unit_keys, .. } = keys {
+                        for k in fresh {
+                            if !unit_keys.iter().any(|(_, h)| *h == k) {
+                                let i = unit_keys.len() as u32;
+                                unit_keys.push((i, k));
+                            }
+                        }
+                        idx = pick(&samples, unit_keys);
+                    }
+                }
+            }
+        }
+        // A bad-content extent no sample can classify inherits its predecessor's
+        // key (CPS boundaries are contiguous, so the neighbour is almost always
+        // right); this never storms and never mis-fails a decryptable disc.
+        let idx = idx.unwrap_or(last_idx);
+        last_idx = idx;
+        ranges.push((
+            ext.start_lba,
+            ext.start_lba.saturating_add(ext.sector_count),
+            idx,
+        ));
+    }
+    Ok(crate::decrypt::AacsKeyMap::from_ranges(ranges, 0))
+}
+
 /// Assemble the ISO mux pipeline (read+decrypt → demux → parse) for
 /// a `FileSectorSource`-backed reader. Returns the resulting
 /// `PipelinedPesStream`.
@@ -618,18 +999,16 @@ fn build_demux_state(title: &DiscTitle, format: ContentFormat) -> DemuxState {
 /// - `halt`: cooperative cancel token (not a timeout); when cancelled the
 ///   pipeline stops at the next boundary. `None` disables cancellation.
 /// - `event_fn`: optional progress/event callback invoked by the prefetcher.
-/// - `fetch`: optional fresh-key-on-failure callback (see
-///   [`crate::sector::KeyFetch`]). When a unit no held key decrypts, the
-///   decrypt decorator hands that ciphertext to `fetch` and adds any key it
-///   returns, then re-decrypts. `None` means no mid-stream key recovery — the
-///   unit's best-effort bytes pass through to the muxer as-is.
+/// - `fetch`: optional key source used UP FRONT by [`resolve_mux_key_map`] to
+///   secure any CPS-unit key the pool is missing. Not a per-unit mux-time
+///   callback: the map decides the key for every LBA before the read loop starts.
 // Eight reader/title/keys/tuning/callback params is inherent to the mux entry
 // point; grouping them into a struct would only move the same fields around.
 #[allow(clippy::too_many_arguments)]
 pub fn build_iso_pipeline<S: SectorSource + Send + 'static>(
-    reader: S,
+    mut reader: S,
     title: DiscTitle,
-    keys: crate::decrypt::DecryptKeys,
+    mut keys: crate::decrypt::DecryptKeys,
     batch_sectors: u16,
     format: ContentFormat,
     halt: Option<crate::halt::Halt>,
@@ -646,20 +1025,35 @@ pub fn build_iso_pipeline<S: SectorSource + Send + 'static>(
         crate::decrypt::DecryptKeys::Aacs { .. } => 3,
         _ => 1,
     };
-    // MUX path: read > decrypt > mux. The decrypt seam applies the CPS unit key and
-    // passes the bytes to the muxer; a unit that decrypts to broken TS is the
-    // muxer's problem, not a decrypt failure, so the mux never conceals a unit or
-    // counts it as loss.
+    // MUX path: read > decrypt > mux. Resolve the proactive AACS key map UP FRONT
+    // — one key per CPS unit / segment, secured from the configured source and
+    // recorded against the LBA ranges it covers. The mux then decrypts each unit
+    // with its KNOWN key and trusts it: no per-unit `is_clean` verdict, no reactive
+    // key-fetch, no key-server storm. A unit that decrypts to broken TS is the
+    // muxer's problem, exactly as before. AACS-only; CSS self-cracks per region.
+    let key_map =
+        match &keys {
+            crate::decrypt::DecryptKeys::Aacs { .. } => Some(std::sync::Arc::new(
+                resolve_mux_key_map(&mut reader, &title, &mut keys, fetch.as_ref(), format)?,
+            )),
+            _ => None,
+        };
+    // The map IS the title's read plan: it says which CPS unit / forensic segment
+    // each LBA belongs to. Walk ONLY the units it marks as ours — every default /
+    // CPS unit, and inside an FMTS forensic segment only our-phase units. The
+    // alternate-phase units are a different device group's variant; a licensed
+    // player never reads them, and neither do we — they are never fetched,
+    // decrypted, or handed to the demux, so the demux sees one gapless our-variant
+    // stream (no ciphertext to trip a concealed-gap resync). A non-forensic map
+    // returns the extents unchanged, so the common disc reads exactly as before.
+    let extents = match &key_map {
+        Some(map) => map.read_plan(&extents, unit_align as u32),
+        None => extents,
+    };
     let mut decrypting =
         crate::sector::DecryptingSectorSource::new(Box::new(reader) as Box<dyn SectorSource>, keys);
-    // Install the fresh-key-on-failure callback (if the app supplied one). This is
-    // how multi-CPS is muxed: each CPS unit's key is fetched when the mux reaches a
-    // unit no held key opens — "get the key when we need it." It fires only on a
-    // genuine miss: now that key selection is accurate (`is_clean_ts`), a unit that
-    // decrypted correctly but has bad-encoded TS is NOT a miss, so this no longer
-    // storms the key source the way the old TS supermajority gate did.
-    if let Some(cb) = fetch {
-        decrypting = decrypting.with_key_fetch(cb);
+    if let Some(map) = key_map {
+        decrypting = decrypting.with_key_map(map);
     }
     // Loss-counter handle. The mux does NOT tally decrypt-quality misses: a
     // broken-TS unit is the muxer's concern, and a missing key is an up-front

src/sector/decrypting.rs

@@ -28,14 +28,67 @@ use super::SectorSource;
 /// empty if the source can't help. Mirrors the DVD model (try the held key,
 /// then ask the key source for the failing data) generalised to AACS.
 ///
-/// The library performs NO key lookup or network I/O itself; this closure is
-/// the seam an application uses to call its key source (e.g. an online key
-/// service) with the exact ciphertext that failed. A **stateless, shared**
-/// `Arc<Fn>` — the decorator owns the only mutable state (its call-count cap and
-/// spent flag), so one closure is built once and cloned cheaply into every read
-/// path (sweep / patch / mux); no per-decorator factory is needed. `Send + Sync`
+/// The library performs NO key lookup or network I/O itself; this is the seam an
+/// application uses to call its key source (e.g. an online key service) with the
+/// exact ciphertext that failed.
+///
+/// TWO explicit operations, so the "one base key vs a whole forensic set"
+/// contract lives in the type instead of a caller guessing at the return length:
+///
+/// * [`unit_keys`](Self::unit_keys) — the base Unit Key(s) for a CPS unit, from
+///   real encrypted samples drawn from it. The non-forensic path: one key per CPS
+///   unit (the pool grows by whatever it returns). Used by the mux's base /
+///   multi-CPS map resolution AND by the sweep/patch recovery decorator.
+/// * [`fmts_indexes`](Self::fmts_indexes) — the disc's AACS 2.1 forensic index
+///   keys, from an index-1 single-phase anchor batch. The source hands back the
+///   COMPLETE set (ordered index 1..N); the caller sizes the forensic map to
+///   `len()` and never assumes a fixed N (32 is all we've seen, but the contract
+///   is "whatever the source returns, ≥ 1, is all of them").
+///
+/// A **stateless, shared** pair of `Arc<Fn>` — the decorator owns the only
+/// mutable state (its call-count cap and spent flag), so one `KeyFetch` is built
+/// once and cloned cheaply (two `Arc` bumps) into every read path. `Send + Sync`
 /// so it can ride the mux highway's producer thread.
-pub type KeyFetch = std::sync::Arc<dyn Fn(&[Vec<u8>]) -> Vec<[u8; 16]> + Send + Sync>;
+/// A closure resolving keys from encrypted-content samples — the shape of both
+/// [`KeyFetch`] operations. Named so the two constructors (and the struct fields)
+/// read clearly.
+pub type KeyFetchFn = std::sync::Arc<dyn Fn(&[Vec<u8>]) -> Vec<[u8; 16]> + Send + Sync>;
+
+#[derive(Clone)]
+pub struct KeyFetch {
+    unit: KeyFetchFn,
+    fmts: KeyFetchFn,
+}
+
+impl KeyFetch {
+    /// Build a resolver from its two operations: `unit` resolves base Unit Keys
+    /// from a CPS unit's samples; `fmts` resolves the forensic index set from an
+    /// index-1 anchor batch.
+    pub fn new(unit: KeyFetchFn, fmts: KeyFetchFn) -> Self {
+        Self { unit, fmts }
+    }
+
+    /// A resolver that serves ONLY base Unit Keys; [`fmts_indexes`](Self::fmts_indexes)
+    /// is always empty. For read paths that never resolve forensic keys — the
+    /// sweep/patch recovery decorator, which handles CPS units only.
+    pub fn unit_only(unit: KeyFetchFn) -> Self {
+        Self::new(unit, std::sync::Arc::new(|_| Vec::new()))
+    }
+
+    /// Resolve the base Unit Key(s) for a CPS unit from `samples` (real encrypted
+    /// units drawn from it). Normally one key; the caller adds whatever it returns
+    /// to the pool.
+    pub fn unit_keys(&self, samples: &[Vec<u8>]) -> Vec<[u8; 16]> {
+        (self.unit)(samples)
+    }
+
+    /// Resolve the disc's AACS 2.1 forensic index keys from an index-1 single-
+    /// phase `anchor` batch. The source returns the COMPLETE ordered set (index i
+    /// = element i); the caller trusts any non-empty result as all of them.
+    pub fn fmts_indexes(&self, anchor: &[Vec<u8>]) -> Vec<[u8; 16]> {
+        (self.fmts)(anchor)
+    }
+}
 
 /// Decorator: read from `inner`, then run the configured
 /// AACS / CSS decrypt over the bytes that landed in `buf`.
@@ -79,6 +132,14 @@ pub struct DecryptingSectorSource<S: SectorSource> {
     /// batches at highway speed, now that the mux installs a key-fetch for
     /// multi-CPS — reuses one allocation instead of alloc/free-ing every read.
     cipher_scratch: Vec<u8>,
+    /// Proactive AACS key map (see [`crate::decrypt::AacsKeyMap`]). When set, the
+    /// mux resolved one key per CPS unit / segment UP FRONT, so this read decrypts
+    /// each aligned unit with its MAPPED key and TRUSTS it — no per-unit
+    /// `is_clean` verdict, no reactive key-fetch, no key-server storm. `None`
+    /// keeps the legacy trial-and-recover path (sweep / patch, or a mux that did
+    /// not build a map). Mutually exclusive with `recovery` in practice: the mux
+    /// installs one or the other.
+    key_map: Option<Arc<crate::decrypt::AacsKeyMap>>,
 }
 
 impl<S: SectorSource> DecryptingSectorSource<S> {
@@ -99,9 +160,29 @@ impl<S: SectorSource> DecryptingSectorSource<S> {
             recovery: None,
             content_ranges: None,
             cipher_scratch: Vec::new(),
+            key_map: None,
         }
     }
 
+    /// Install a proactive [`AacsKeyMap`](crate::decrypt::AacsKeyMap): the mux
+    /// resolved one key per CPS unit / segment up front, so every aligned unit is
+    /// decrypted with its MAPPED key and trusted — no per-unit `is_clean` check,
+    /// no reactive key-fetch. This is the storm-free mux path; it supersedes
+    /// [`with_key_fetch`](Self::with_key_fetch) (do not set both). AACS-only; a
+    /// CSS / clear disc ignores it.
+    pub fn with_key_map(mut self, map: Arc<crate::decrypt::AacsKeyMap>) -> Self {
+        self.key_map = Some(map);
+        self
+    }
+
+    /// `&mut` counterpart of [`with_key_map`](Self::with_key_map): install the
+    /// proactive map on an already-constructed source (the inline live-drive
+    /// [`DiscStream`](crate::mux::DiscStream) builds the decorator first, then
+    /// installs the map via its own `with_key_map`).
+    pub fn set_key_map(&mut self, map: Arc<crate::decrypt::AacsKeyMap>) {
+        self.key_map = Some(map);
+    }
+
     /// Restrict decrypt to the disc's encrypted-content extents
     /// (sorted/merged `(start_lba, sector_count)` — see
     /// [`Disc::encrypted_content_ranges`](crate::Disc::encrypted_content_ranges)).
@@ -221,6 +302,18 @@ impl<S: SectorSource> SectorSource for DecryptingSectorSource<S> {
         let n = self
             .inner
             .read_sectors_fua(lba, count, buf, recovery, fua)?;
+
+        // PROACTIVE MAP PATH (the storm-free mux): when a key map is installed the
+        // mux resolved one key per CPS unit / segment up front, so decrypt each
+        // aligned unit with its MAPPED key and trust it — no per-unit `is_clean`
+        // verdict, no reactive key-fetch. A resolver gap surfaces loud from
+        // `decrypt_sectors_mapped` (DecryptFailed); authored-bad TS just passes
+        // through for the muxer to drop.
+        if let Some(map) = self.key_map.clone() {
+            crate::decrypt::decrypt_sectors_mapped(&mut buf[..n], &self.keys, lba, &map)?;
+            return Ok(n);
+        }
+
         // Decrypt the bytes just read IN PLACE. Scheme-agnostic (None / CSS / AACS).
         // With a content map installed the `*_in_content` entry skips units OUTSIDE
         // the encrypted extents (clear filesystem / nav pass through untouched); the
@@ -1135,10 +1228,11 @@ mod tests {
         // Capture what the callback was handed, and how many times it fired.
         let seen: Arc<Mutex<Vec<Vec<u8>>>> = Arc::new(Mutex::new(Vec::new()));
         let seen_cb = Arc::clone(&seen);
-        let fetch: super::KeyFetch = std::sync::Arc::new(move |samples: &[Vec<u8>]| {
-            seen_cb.lock().unwrap().extend_from_slice(samples);
-            vec![real_key]
-        });
+        let fetch: super::KeyFetch =
+            super::KeyFetch::unit_only(std::sync::Arc::new(move |samples: &[Vec<u8>]| {
+                seen_cb.lock().unwrap().extend_from_slice(samples);
+                vec![real_key]
+            }));
 
         let mut wrapped = DecryptingSectorSource::new(
             EncUnitSource { unit: unit.clone() },
@@ -1156,7 +1250,7 @@ mod tests {
         // The recovered key decrypts the unit: it is now clean TS in `buf`.
         let unit0 = &buf[..crate::aacs::content::ALIGNED_UNIT_LEN];
         assert!(
-            !crate::aacs::content::ts_sync_destroyed(unit0),
+            crate::aacs::content::is_clean(unit0, crate::disc::ContentFormat::BdTs),
             "fetch supplied the key → the unit decrypts to clean TS"
         );
         let got = seen.lock().unwrap();
@@ -1166,7 +1260,7 @@ mod tests {
             "callback must be invoked once with the failing unit"
         );
         assert!(
-            crate::aacs::content::ts_sync_destroyed(&got[0]),
+            !crate::aacs::content::is_clean(&got[0], crate::disc::ContentFormat::BdTs),
             "the sample handed to the callback is the still-scrambled ciphertext"
         );
         assert_eq!(
@@ -1175,6 +1269,92 @@ mod tests {
         );
     }
 
+    /// THE MUX-STORM REGRESSION. A unit the held key OPENS (>= the 4-packet proof
+    /// floor) but that carries many authored-bad packets (< half synced) must
+    /// NEVER be handed to the key-fetch closure — its key is already in hand. Only
+    /// a GENUINE miss (no held key opens it) is sampled. Before the min(E,4)
+    /// unification, the bad-encoded unit tripped the old >50% majority in
+    /// `aacs_unit_needs_decrypt`, so every batch re-sampled it to the key service
+    /// (the Jason Bourne / Stand By Me stall). This drives the REAL
+    /// `DecryptingSectorSource` recovery path, not a synthetic check.
+    #[test]
+    fn bad_encoded_opened_unit_is_never_sampled_to_the_key_service() {
+        use crate::aacs::content::ALIGNED_UNIT_LEN;
+        let held = [0x5au8; 16]; // opens the bad-encoded unit
+        let orphan = [0x77u8; 16]; // opens the genuine-miss unit (NOT held)
+        // Knock out packets 1..27 (26 authored-bad) → ~5 synced: >= the 4-packet
+        // floor (OPENED) yet < half (what the old >50% majority false-flagged).
+        let bad_pkts: Vec<usize> = (1..27).collect();
+        let bad_encoded = encrypt_aacs_unit_bad(&held, &bad_pkts);
+        let genuine_miss = encrypt_aacs_unit(&orphan);
+
+        // One 6-sector read spans both units: bad-encoded at [0,3), miss at [3,6).
+        struct TwoUnits {
+            a: Vec<u8>,
+            b: Vec<u8>,
+        }
+        impl SectorSource for TwoUnits {
+            fn capacity_sectors(&self) -> u32 {
+                6
+            }
+            fn read_sectors(
+                &mut self,
+                _lba: u32,
+                _count: u16,
+                buf: &mut [u8],
+                _r: bool,
+            ) -> Result<usize> {
+                let n = crate::aacs::content::ALIGNED_UNIT_LEN;
+                buf[..n].copy_from_slice(&self.a);
+                buf[n..2 * n].copy_from_slice(&self.b);
+                Ok(2 * n)
+            }
+        }
+
+        let seen: Arc<Mutex<Vec<Vec<u8>>>> = Arc::new(Mutex::new(Vec::new()));
+        let seen_cb = Arc::clone(&seen);
+        let fetch: super::KeyFetch =
+            super::KeyFetch::unit_only(std::sync::Arc::new(move |samples: &[Vec<u8>]| {
+                seen_cb.lock().unwrap().extend_from_slice(samples);
+                Vec::new() // service has nothing for the orphan — forces the sampling path
+            }));
+
+        let ranges: Arc<[(u32, u32)]> = Arc::from(vec![(0u32, 6u32)]);
+        let mut dec = DecryptingSectorSource::new(
+            TwoUnits {
+                a: bad_encoded.clone(),
+                b: genuine_miss.clone(),
+            },
+            DecryptKeys::Aacs {
+                unit_keys: vec![(0, held)], // opens bad_encoded, NOT genuine_miss
+                read_data_key: None,
+                format: crate::disc::ContentFormat::BdTs,
+            },
+        )
+        .with_content_ranges(ranges)
+        .with_key_fetch(fetch);
+
+        let mut buf = vec![0u8; 6 * 2048];
+        let _ = dec.read_sectors(0, 6, &mut buf, false);
+
+        let got = seen.lock().unwrap();
+        assert!(
+            !got.is_empty(),
+            "the genuine orphan-key miss must trigger a fetch"
+        );
+        for s in got.iter() {
+            assert_ne!(
+                &s[..ALIGNED_UNIT_LEN.min(s.len())],
+                &bad_encoded[..],
+                "a bad-encoded unit the key OPENED must NEVER be sampled (the storm)"
+            );
+        }
+        assert!(
+            got.iter().any(|s| s.as_slice() == genuine_miss.as_slice()),
+            "only the genuine miss is sampled to the key service"
+        );
+    }
+
     /// A fetch that comes back EMPTY for one unit must NOT block a later fetch
     /// for a DIFFERENT unit (the multi-CPS case). The old global `fetch_spent`
     /// latch wrongly blocked it; the per-sample `fetch_dry` set must let unit B
@@ -1220,14 +1400,15 @@ mod tests {
         let unit_b_cb = unit_b.clone();
         let calls = Arc::new(Mutex::new(0usize));
         let calls_cb = Arc::clone(&calls);
-        let fetch: super::KeyFetch = std::sync::Arc::new(move |samples: &[Vec<u8>]| {
-            *calls_cb.lock().unwrap() += 1;
-            if samples.iter().any(|s| *s == unit_b_cb) {
-                vec![key_b]
-            } else {
-                vec![]
-            }
-        });
+        let fetch: super::KeyFetch =
+            super::KeyFetch::unit_only(std::sync::Arc::new(move |samples: &[Vec<u8>]| {
+                *calls_cb.lock().unwrap() += 1;
+                if samples.iter().any(|s| *s == unit_b_cb) {
+                    vec![key_b]
+                } else {
+                    vec![]
+                }
+            }));
 
         let mut wrapped = DecryptingSectorSource::new(
             AltSource {
@@ -1257,7 +1438,7 @@ mod tests {
             "fetch fired for BOTH units — the dry result for A did not latch off B"
         );
         assert!(
-            !crate::aacs::content::ts_sync_destroyed(&buf2),
+            crate::aacs::content::is_clean(&buf2, crate::disc::ContentFormat::BdTs),
             "unit B is decrypted after its on-demand fetch"
         );
     }
@@ -1361,13 +1542,14 @@ mod tests {
 
         let calls = Arc::new(Mutex::new(0usize));
         let calls_cb = Arc::clone(&calls);
-        let fetch: super::KeyFetch = std::sync::Arc::new(move |samples: &[Vec<u8>]| {
-            *calls_cb.lock().unwrap() += 1;
-            // The closure is handed the still-scrambled on-disc ciphertext.
-            assert!(!samples.is_empty(), "fetch receives the failing units");
-            assert_eq!(samples[0].len(), crate::aacs::content::ALIGNED_UNIT_LEN);
-            vec![real_key]
-        });
+        let fetch: super::KeyFetch =
+            super::KeyFetch::unit_only(std::sync::Arc::new(move |samples: &[Vec<u8>]| {
+                *calls_cb.lock().unwrap() += 1;
+                // The closure is handed the still-scrambled on-disc ciphertext.
+                assert!(!samples.is_empty(), "fetch receives the failing units");
+                assert_eq!(samples[0].len(), crate::aacs::content::ALIGNED_UNIT_LEN);
+                vec![real_key]
+            }));
 
         let ranges: Arc<[(u32, u32)]> = Arc::from(vec![(0u32, 6u32)]); // LBA 0..6 content
         let mut dec = DecryptingSectorSource::new(
@@ -1388,7 +1570,7 @@ mod tests {
             .expect("fetch recovers the orphan unit's key");
         assert_ne!(buf, unit, "the fetched key decrypts the unit in place");
         assert!(
-            !crate::aacs::content::ts_sync_destroyed(&buf),
+            crate::aacs::content::is_clean(&buf, crate::disc::ContentFormat::BdTs),
             "the recovered read is clean TS"
         );
         assert_eq!(*calls.lock().unwrap(), 1, "fetch called exactly once");
@@ -1446,10 +1628,11 @@ mod tests {
         let unit = encrypt_aacs_unit(&real_key);
         let calls = Arc::new(Mutex::new(0usize));
         let calls_cb = Arc::clone(&calls);
-        let fetch: super::KeyFetch = std::sync::Arc::new(move |_: &[Vec<u8>]| {
-            *calls_cb.lock().unwrap() += 1;
-            vec![real_key]
-        });
+        let fetch: super::KeyFetch =
+            super::KeyFetch::unit_only(std::sync::Arc::new(move |_: &[Vec<u8>]| {
+                *calls_cb.lock().unwrap() += 1;
+                vec![real_key]
+            }));
         // Content lives far away; LBA 0 is "filesystem".
         let ranges: Arc<[(u32, u32)]> = Arc::from(vec![(1002u32, 99u32)]);
         let mut dec = DecryptingSectorSource::new(

src/sector/mod.rs

@@ -189,7 +189,7 @@ pub trait SectorSink: Send {
 }
 
 pub use crate::io::file_sector_source::FileSectorSource;
-pub use decrypting::{DecryptingSectorSource, KeyFetch};
+pub use decrypting::{DecryptingSectorSource, KeyFetch, KeyFetchFn};
 pub use file::FileSectorSink;
 pub use prefetched::PrefetchedSectorSource;
 

src/sector/recovery.rs

@@ -170,7 +170,7 @@ fn aacs_fetch_step(
         return prev_dropped;
     }
     *calls += 1;
-    let fresh = (fetch)(&samples);
+    let fresh = fetch.unit_keys(&samples);
     // Add only keys we don't already hold (dedup by value).
     let mut added = 0usize;
     if let DecryptKeys::Aacs { unit_keys, .. } = keys {
@@ -276,11 +276,11 @@ mod tests {
         // decorator's integration tests); here we pin the seam's key-plumbing.
         let calls = Arc::new(AtomicUsize::new(0));
         let c2 = Arc::clone(&calls);
-        let fetch: KeyFetch = Arc::new(move |samples: &[Vec<u8>]| {
+        let fetch: KeyFetch = KeyFetch::unit_only(Arc::new(move |samples: &[Vec<u8>]| {
             c2.fetch_add(1, Ordering::SeqCst);
             assert!(!samples.is_empty(), "failing ciphertext is forwarded");
             vec![[0xAB; 16]]
-        });
+        }));
         let mut r = key_fetch(fetch);
         let mut buf = scrambled_unit(0x33);
         let mut keys = DecryptKeys::Aacs {
@@ -304,10 +304,10 @@ mod tests {
         // the SAME ciphertext must not call the fetch again.
         let calls = Arc::new(AtomicUsize::new(0));
         let c2 = Arc::clone(&calls);
-        let fetch: KeyFetch = Arc::new(move |_: &[Vec<u8>]| {
+        let fetch: KeyFetch = KeyFetch::unit_only(Arc::new(move |_: &[Vec<u8>]| {
             c2.fetch_add(1, Ordering::SeqCst);
             Vec::new() // never helps
-        });
+        }));
         let mut r = key_fetch(fetch);
         let mut keys = DecryptKeys::Aacs {
             unit_keys: vec![],
@@ -331,10 +331,10 @@ mod tests {
     fn key_fetch_call_budget_bounds_fetches() {
         let calls = Arc::new(AtomicUsize::new(0));
         let c2 = Arc::clone(&calls);
-        let fetch: KeyFetch = Arc::new(move |_: &[Vec<u8>]| {
+        let fetch: KeyFetch = KeyFetch::unit_only(Arc::new(move |_: &[Vec<u8>]| {
             c2.fetch_add(1, Ordering::SeqCst);
             Vec::new()
-        });
+        }));
         let mut r = key_fetch(fetch);
         let mut keys = DecryptKeys::Aacs {
             unit_keys: vec![],

tests/crypto_tests.rs

@@ -131,12 +131,15 @@ fn aacs_decrypt_unit_roundtrip() {
     }
 
     // Verify it looks encrypted (body TS syncs scrambled)
-    assert!(aacs::content::ts_sync_destroyed(&plain));
+    assert!(!aacs::content::is_clean(
+        &plain,
+        libfreemkv::disc::ContentFormat::BdTs
+    ));
 
     // Now decrypt
     aacs::content::decrypt_unit(&mut plain, &unit_key);
     assert!(
-        !aacs::content::ts_sync_destroyed(&plain),
+        aacs::content::is_clean(&plain, libfreemkv::disc::ContentFormat::BdTs),
         "decrypted unit should read as clear (TS syncs restored)"
     );
 
@@ -254,9 +257,9 @@ fn aacs_vuk_derivation_roundtrip() {
     assert_eq!(vuk, vuk2, "derive_vuk not deterministic");
 }
 
-/// Test: aacs_ts_sync_destroyed detects scrambled units via the raw TS syncs.
+/// Test: `is_clean` distinguishes clean vs scrambled units via the TS proof floor.
 #[test]
-fn aacs_ts_sync_destroyed_detection() {
+fn aacs_is_clean_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::content::ALIGNED_UNIT_LEN];
@@ -266,7 +269,7 @@ fn aacs_ts_sync_destroyed_detection() {
         off += 192;
     }
     assert!(
-        !aacs::content::ts_sync_destroyed(&clear),
+        aacs::content::is_clean(&clear, libfreemkv::disc::ContentFormat::BdTs),
         "clear unit (syncs intact) must not be scrambled"
     );
 
@@ -275,21 +278,21 @@ fn aacs_ts_sync_destroyed_detection() {
     flagged[0] = 0xC0; // copy-control bits
     flagged[7] = 0xC0; // TSC bits
     assert!(
-        !aacs::content::ts_sync_destroyed(&flagged),
+        aacs::content::is_clean(&flagged, libfreemkv::disc::ContentFormat::BdTs),
         "flag bits must not be read as encryption"
     );
 
     // A scrambled body (syncs destroyed) → scrambled.
     let scrambled = vec![0x99u8; aacs::content::ALIGNED_UNIT_LEN];
     assert!(
-        aacs::content::ts_sync_destroyed(&scrambled),
+        !aacs::content::is_clean(&scrambled, libfreemkv::disc::ContentFormat::BdTs),
         "unit with no intact TS syncs must read as scrambled"
     );
 
     // Too short
     let short = vec![0xFFu8; 100];
     assert!(
-        !aacs::content::ts_sync_destroyed(&short),
+        aacs::content::is_clean(&short, libfreemkv::disc::ContentFormat::BdTs),
         "short buffer should not be detected"
     );
 }
@@ -312,7 +315,10 @@ fn aacs_clear_unit_reports_not_encrypted() {
     // CPI bits (byte 0) CLEAR → the authoritative gate reads this as plaintext.
     unit[0] &= 0x3F;
 
-    assert!(!aacs::content::ts_sync_destroyed(&unit));
+    assert!(aacs::content::is_clean(
+        &unit,
+        libfreemkv::disc::ContentFormat::BdTs
+    ));
     assert!(
         !aacs::content::aacs_unit_encrypted(&unit, libfreemkv::disc::ContentFormat::BdTs),
         "CPI-clear unit reports not-encrypted; the caller never decrypts it"

tests/pass_n_patch_fix.rs

@@ -108,16 +108,25 @@ fn aacs_encryption_flag_detection() {
         off += 192;
     }
     // Encryption is the scrambled body (TS syncs destroyed), NOT a flag bit.
-    assert!(!aacs::content::ts_sync_destroyed(&unit));
+    assert!(aacs::content::is_clean(
+        &unit,
+        libfreemkv::disc::ContentFormat::BdTs
+    ));
 
     // Flag bits on a synced unit do not make it look encrypted.
     unit[0] = 0xC0;
     unit[7] = 0xC0;
-    assert!(!aacs::content::ts_sync_destroyed(&unit));
+    assert!(aacs::content::is_clean(
+        &unit,
+        libfreemkv::disc::ContentFormat::BdTs
+    ));
 
     // Scrambled body (syncs gone) → encrypted.
     let scrambled = vec![0x99u8; aacs::content::ALIGNED_UNIT_LEN];
-    assert!(aacs::content::ts_sync_destroyed(&scrambled));
+    assert!(!aacs::content::is_clean(
+        &scrambled,
+        libfreemkv::disc::ContentFormat::BdTs
+    ));
 }
 
 /// Test: DecryptKeys::is_encrypted() correctly identifies encrypted state.

tests/streams.rs

@@ -591,7 +591,7 @@ fn meta_all_stream_types() {
 fn mkvstream_write_finish() {
     let dt = sample_disc_title();
     let writer: Box<dyn libfreemkv::mux::WriteSeek + Send> = Box::new(Cursor::new(Vec::new()));
-    let mut stream = MkvStream::create(writer, &dt).unwrap();
+    let mut stream = MkvStream::create(writer, &dt, None).unwrap();
 
     // Write some fake PES frames (they won't produce valid MKV content
     // since there is no real codec data, but it should not panic)
@@ -616,7 +616,7 @@ fn mkvstream_write_finish() {
 fn mkvstream_meta_sets_title() {
     let dt = sample_disc_title();
     let writer: Box<dyn libfreemkv::mux::WriteSeek + Send> = Box::new(Cursor::new(Vec::new()));
-    let stream = MkvStream::create(writer, &dt).unwrap();
+    let stream = MkvStream::create(writer, &dt, None).unwrap();
 
     let info = PesStream::info(&stream);
     assert_eq!(info.playlist, "Test Movie");
@@ -656,7 +656,7 @@ fn mkvstream_roundtrip_bdts() {
     };
 
     let writer: Box<dyn libfreemkv::mux::WriteSeek + Send> = Box::new(Cursor::new(Vec::new()));
-    let mut stream = MkvStream::create(writer, &dt).unwrap();
+    let mut stream = MkvStream::create(writer, &dt, None).unwrap();
 
     // Write PES frames targeting the audio track
     for i in 0..10u8 {
@@ -745,7 +745,7 @@ fn mkvstream_meta_preserves_all_streams() {
     };
 
     let writer: Box<dyn libfreemkv::mux::WriteSeek + Send> = Box::new(Cursor::new(Vec::new()));
-    let stream = MkvStream::create(writer, &dt).unwrap();
+    let stream = MkvStream::create(writer, &dt, None).unwrap();
 
     let info = PesStream::info(&stream);
     assert_eq!(info.streams.len(), 5, "all 5 streams should be preserved");
@@ -856,7 +856,7 @@ fn mkvstream_e2e_h264_produces_valid_mkv() {
 
     let writer: Box<dyn libfreemkv::mux::WriteSeek + Send> =
         Box::new(SharedWriter(output2.clone()));
-    let mut stream2 = MkvStream::create(writer, &dt).unwrap();
+    let mut stream2 = MkvStream::create(writer, &dt, None).unwrap();
 
     // Write the ES data (SPS+PPS+IDR) as a keyframe PES frame.
     let frame1 = libfreemkv::pes::PesFrame {