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.3"
+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.3" }
+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/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/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

@@ -41,21 +41,6 @@ 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 the forensic index keys.
-///
-/// `true` (today): the forensic 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 = false;
-
 /// One forensic segment: the inclusive source-packet range it occupies in the
 /// FMTS clip.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]

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,7 +53,7 @@ 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],
@@ -95,7 +95,7 @@ impl UnitKey {
 }
 
 /// 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,
@@ -110,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

@@ -191,9 +191,23 @@ impl DecryptKeys {
 /// 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 {
-    ranges: Vec<(u32, u32, usize)>,
+    // (start_lba, end_lba, key_idx, phase)
+    ranges: Vec<(u32, u32, usize, Phase)>,
     default_idx: usize,
 }
 
@@ -207,43 +221,68 @@ impl AacsKeyMap {
         }
     }
 
-    /// Build from explicit `[start_lba, end_lba) → key_idx` ranges (multi-CPS /
-    /// FMTS). Ranges are sorted; `default_idx` answers any uncovered LBA.
-    pub fn from_ranges(mut ranges: Vec<(u32, u32, usize)>, default_idx: usize) -> Self {
-        ranges.sort_by_key(|&(start, _, _)| start);
+    /// 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 unit-key index to decrypt the aligned unit at `lba` with. O(log n) —
-    /// the last range whose start is `<= lba` and whose end is `> lba`, else the
-    /// default. Cheap enough to call per aligned unit on the mux hot path.
-    pub fn key_idx_for(&self, lba: u32) -> usize {
+    /// 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;
+            return (self.default_idx, Phase::All, 0);
         }
         match self
             .ranges
-            .binary_search_by(|&(start, _, _)| start.cmp(&lba))
+            .binary_search_by(|&(start, _, _, _)| start.cmp(&lba))
         {
-            Ok(i) => self.ranges[i].2,
-            Err(0) => self.default_idx,
+            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) = self.ranges[i - 1];
+                let (start, end, idx, ph) = self.ranges[i - 1];
                 if lba >= start && lba < end {
-                    idx
+                    (idx, ph, start)
                 } else {
-                    self.default_idx
+                    (self.default_idx, Phase::All, 0)
                 }
             }
         }
     }
 
-    /// The `[start_lba, end_lba) → key_idx` ranges (sorted, disjoint). Empty for a
-    /// single-CPS map (everything uses [`default_idx`](Self::default_idx)).
-    pub fn ranges(&self) -> &[(u32, u32, usize)] {
+    /// 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
     }
 
@@ -256,12 +295,95 @@ impl AacsKeyMap {
     /// 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();
+        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
@@ -305,24 +427,46 @@ pub fn decrypt_sectors_mapped(
         }
     }
 
+    // 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
         }
-        // Gate on the authoritative encrypted flag ONLY (the CPI bits in the clear
-        // seed) — no `is_clean`. A clear unit (flag unset) is left untouched; an
-        // encrypted unit is decrypted with its MAPPED key and trusted.
+        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;
         }
-        let unit_lba = base_lba.saturating_add((idx_in_buf as u32) * unit_sectors);
-        let key_idx = map.key_idx_for(unit_lba);
         // 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();
@@ -345,6 +489,9 @@ pub fn decrypt_sectors_mapped(
             }
         }
     }
+    if verify_failed.load(std::sync::atomic::Ordering::Relaxed) {
+        return Err(crate::error::Error::DecryptFailed);
+    }
     Ok(())
 }
 
@@ -1476,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).

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`):
@@ -2672,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;
@@ -4188,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 {
@@ -5063,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),
     }
@@ -5124,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)"
@@ -5546,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");
             }
@@ -5571,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

@@ -39,6 +39,48 @@ use crate::error::Error;
 /// 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.
@@ -73,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
@@ -191,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
@@ -231,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
@@ -259,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
@@ -310,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;
             }
@@ -319,61 +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 {
-    // Memoize by the fingerprint of the sample batch. The resolved keys are
-    // disc-level (the same clip's index / CPS keys are identical for every title
-    // that references it), and this one closure is shared across every title's mux
-    // — so the first title resolves a given batch over the network and every later
-    // title (or repeated batch) is answered from the cache with no request. Empty
-    // replies are cached too: a key the service does not have for a batch will not
-    // appear on a re-ask, so re-hitting the network buys nothing.
-    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);
+    // 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();
             }
-            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]> = fetch_unit_keys(&sources, &ctx)
-            .into_iter()
-            .map(|u| u.key)
-            .collect();
-        cache
-            .lock()
-            .unwrap_or_else(|e| e.into_inner())
-            .insert(fp, keys.clone());
-        keys
-    })
+            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
@@ -467,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.
@@ -478,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())
             }
         }
@@ -535,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 {
@@ -592,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)])
         }
     }
@@ -647,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);
                 }
@@ -667,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],
@@ -681,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;

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,9 +108,10 @@ 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;

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
@@ -479,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")?;
@@ -531,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(
@@ -638,20 +635,11 @@ fn resolve_fmts_key_map(
     title: &DiscTitle,
     keys: &mut crate::decrypt::DecryptKeys,
     fetch: Option<&crate::sector::KeyFetch>,
-    _format: ContentFormat,
+    format: ContentFormat,
 ) -> io::Result<Option<crate::decrypt::AacsKeyMap>> {
-    use crate::aacs::content::ALIGNED_UNIT_LEN;
+    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};
 
-    // Off by default: while `BYPASS_FMTS_KEY` is set, forensic decode is disabled —
-    // no segment table read, no key-service traffic — and the caller's base-Unit-Key
-    // path applies (the forensic units garble and the demux drops them, the shipped
-    // behaviour). Flip `BYPASS_FMTS_KEY` to false to activate forensic decode once
-    // the index-key resolution is validated end to end.
-    if crate::aacs::segment::BYPASS_FMTS_KEY {
-        return Ok(None);
-    }
-
     // Load the segment map; absent → not an FMTS disc.
     let Ok(udf) = crate::udf::read_filesystem(reader) else {
         return Ok(None);
@@ -684,56 +672,64 @@ fn resolve_fmts_key_map(
             reader.read_sectors(lba, 3, &mut c, false).ok()?;
             Some(c)
         };
-    // ── ONE forensic query. The key service returns ALL forensic index keys for the
-    //    disc in a single response, ORDERED by index (array element i = index i+1).
-    //    So send one clean single-variant batch (a segment's even-phase units) and
-    //    read the whole set back — no per-index probing, no phase measurement, no
-    //    decrypt-and-check: the array position IS the index. The first readable
-    //    segment whose batch yields the full set wins; a short (e.g. 1-key,
-    //    base-UK-shaped) response means that batch wasn't forensic (a wrong
-    //    feature-title mapping), so try the next segment.
+    // ── 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.
     //
-    //    ANCHOR RULE: the query MUST sample an INDEX-1 segment. The key service only
-    //    returns the full set for the canonical anchor sample (a unit that decrypts
-    //    under the index-1 key); a batch from any other forensic index is rejected
-    //    (a base-UK-shaped miss). The `index == 1` filter guarantees every batch we
-    //    send is an anchor — and the forensic tag cycles 1..32 in file order, so
-    //    ~1-in-32 segments qualify (~25 across the feature), leaving ample read-fault
-    //    fallback within the `MAX_ANCHOR_ATTEMPTS` budget. ─────────────────────────
-    const N_INDEX: usize = 32;
-    // Each forensic batch carries the server's minimum-samples count (the same
-    // disambiguation floor the online source enforces), drawn as even-phase units
-    // to land one clean variant half.
+    //    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 budget: how many INDEX-1 (anchor) segments to attempt
-    // before giving up. Only matters when the leading anchor segments are
-    // unreadable; each attempt is one server round-trip, so it is bounded.
+    // 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();
-    for seg in segments
+    'anchor: for seg in segments
         .iter()
         .filter(|s| s.index == 1)
         .take(MAX_ANCHOR_ATTEMPTS)
     {
-        let mut batch: Vec<Vec<u8>> = Vec::new();
-        for p in 0..BATCH_UNITS {
-            if let Some(c) = read_unit(reader, seg, p * 2) {
-                batch.push(c);
+        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;
             }
         }
-        if batch.len() < BATCH_UNITS {
-            continue; // read fault / short tail
-        }
-        let fresh = fetch(&batch);
-        if fresh.len() >= N_INDEX {
-            index_keys = fresh;
-            break;
-        }
     }
-    tracing::info!(target: "freemkv::keysource", held = index_keys.len(), need = N_INDEX, "fmts: collection done");
-    // The full set is required. Anything short holes the rip — fail loud like a
-    // missing Unit Key rather than emit forensic-holed output.
-    if index_keys.len() < N_INDEX {
+    // 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());
     }
 
@@ -742,7 +738,7 @@ fn resolve_fmts_key_map(
     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().take(N_INDEX).enumerate() {
+        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,
@@ -758,21 +754,64 @@ fn resolve_fmts_key_map(
         }
     }
 
-    // ── Build the per-segment LBA ranges directly from the tag. Each segment is
-    //    decoded from its TAG half: the map routes the segment's whole span to its
-    //    tag's key; the tag key opens the tag half wherever it interleaves, and the
-    //    un-served version-B half — decrypted with that (for it, wrong) key —
-    //    garbles and the demux drops it, leaving one clean variant per span. No
-    //    re-read and no phase needed here: byte-5 `seg.index` selects the key. A
-    //    segment whose tag is somehow absent (cannot happen with all 32 held) or
-    //    that straddles an extent boundary is left unmapped and tallied. ─────────
-    let mut ranges: Vec<(u32, u32, usize)> = Vec::with_capacity(segments.len());
+    // ── 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)) = (
@@ -785,20 +824,19 @@ fn resolve_fmts_key_map(
         // 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));
+            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 (a read fault or an unexpected on-disc layout)
-    // rather than silently emitting a segment the base Unit Key only garbles.
+    // 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(
+    Ok(Some(crate::decrypt::AacsKeyMap::from_ranges_phased(
         ranges, base_idx,
     )))
 }
@@ -826,7 +864,7 @@ pub fn resolve_mux_key_map(
         if let Some(f) = fetch {
             let samples = crate::keysource::read_encrypted_units(reader, title, 8);
             if !samples.is_empty() {
-                let fresh = f(&samples);
+                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) {
@@ -916,7 +954,7 @@ pub fn resolve_mux_key_map(
         if idx.is_none() {
             if let Some(f) = fetch {
                 if !samples.is_empty() {
-                    let fresh = f(&samples);
+                    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) {
@@ -1000,6 +1038,18 @@ pub fn build_iso_pipeline<S: SectorSource + Send + 'static>(
             )),
             _ => 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);
     if let Some(map) = key_map {

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`.
@@ -122,6 +175,14 @@ impl<S: SectorSource> DecryptingSectorSource<S> {
         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)).
@@ -1167,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() },
@@ -1251,10 +1313,11 @@ mod tests {
 
         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::new() // service has nothing for the orphan — forces the sampling path
-        });
+        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(
@@ -1337,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 {
@@ -1478,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(
@@ -1563,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/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 {