0.31.0: hardening and correctness pass across mux, codec, AACS/CSS, UDF/MPLS/CLPI, recovery, drive/SCSI, labels, and I/O

Library-wide review-and-fix pass: tightened AACS keydb/handshake/variant
handling and trailing-partial-unit policy, corrected MPLS mark offset and
added UDF allocation bounds, hardened the mux/codec framing and M2TS paths,
guarded SCSI READ CAPACITY short transfers and unified error mapping, added
overflow guards on untrusted disc input, and made prefetch shutdown
deterministic. Release profile now builds with thin LTO + single codegen unit.

src/mux/mod.rs

@@ -1,7 +1,15 @@
 //! Stream-based I/O pipeline.
 //!
-//! All formats are PES streams. Read from a format → PES frames.
-//! Write PES frames → a format.
+//! Two muxer families live here:
+//!
+//! 1. **Bidirectional PES streams** (`disc`, `mkv`, `m2ts`, `network`,
+//!    `stdio`, `null`) implement the [`crate::pes::Stream`] interface:
+//!    read a format → PES frames, or write PES frames → a format.
+//! 2. **Write-only sequential-sink muxers** (`fmp4`, `hevc`,
+//!    `m2ts_mux`) consume PES frames and write a container to a
+//!    `SequentialSink`; they do not implement the read loop below.
+//!
+//! The bidirectional family is driven like this:
 //!
 //! ```text
 //! let mut input = input("iso://Disc.iso", &opts)?;
@@ -16,12 +24,26 @@
 //! For disc→ISO (raw sector copy), use `Disc::copy()` instead.
 
 // Public modules — types here are intentionally part of the consumable API.
-pub mod codec;
-pub mod demux_thread;
 pub mod disc;
 pub mod pipelined_stream;
 pub mod resolve;
 
+// Internal-only modules. Every reference is via `crate::mux::…` /
+// `super::…` from inside the crate; nothing in the downstream crates or
+// integration tests imports them and lib.rs re-exports nothing from
+// them, so they are not part of the stable public API.
+//
+// `#[allow(dead_code)]`: narrowing these from `pub` to `pub(crate)`
+// surfaces a handful of helpers/accessors that were only ever reachable
+// as (unused) public API — e.g. the MPEG-2 resolution/frame-rate
+// accessors and an alternate `DemuxThread` spawn path. They are kept as
+// part of the parser/demux surface and covered by unit tests; allow the
+// dead-code lint rather than delete still-relevant scaffolding.
+#[allow(dead_code)]
+pub(crate) mod codec;
+#[allow(dead_code)]
+pub(crate) mod demux_thread;
+
 // Internal modules — implementation details. Their *types* are re-exported
 // where appropriate (`MkvStream`, `M2tsStream`, etc. surface from `lib.rs`),
 // but the module paths themselves are not part of the API. Pre-0.13 these
@@ -35,16 +57,30 @@ pub(crate) mod m2ts;
 /// Exposed for integration tests that exercise the wire format directly.
 pub mod meta;
 
-// ── Phase 3 sequential muxers ──────────────────────────────────────────────
+// ── Sequential-sink muxers ──────────────────────────────────────────────────
 //
-// New container muxers that consume PES frames and write to a
-// `SequentialSink`. They are NOT refactors of the existing `MkvStream` /
-// `M2tsStream` (which round-trip via the legacy `Stream` trait + the
-// BD-TS framing); they're sequential-only and target the Phase 2 sink
-// split end-to-end.
-pub mod fmp4;
-pub mod hevc;
-pub mod m2ts_mux;
+// Container muxers that consume PES frames and write to a
+// `SequentialSink`. They are NOT the bidirectional `MkvStream` /
+// `M2tsStream` (which round-trip via the `Stream` trait + BD-TS
+// framing); these are write-only and sequential.
+//
+// `pub(crate)`: these have no external callers and are not re-exported
+// from lib.rs. `fmp4` is an explicit STUB (`Fmp4Mux::write_video`
+// accumulates and discards) — shipping it as `pub` would lock a
+// half-built type into the v1.0 stability contract via the
+// `libfreemkv::mux::fmp4::Fmp4Mux` path. `m2ts_mux` is the plain
+// MPEG-TS sequential muxer and `hevc` is its Annex-B helper; both are
+// staged scaffolding for the sink split and are not yet wired into a
+// live pipeline (the production paths use `tsmux` / `mkv`).
+// `#[allow(dead_code)]`: retained intentionally until the sink split
+// lands; they are exercised by their own unit tests. If any becomes a
+// public muxer, re-export its concrete type from lib.rs instead.
+#[allow(dead_code)]
+pub(crate) mod fmp4;
+#[allow(dead_code)]
+pub(crate) mod hevc;
+#[allow(dead_code)]
+pub(crate) mod m2ts_mux;
 pub(crate) mod mkv;
 pub(crate) mod mkvstream;
 pub(crate) mod network;