libfreemkv/docs/resolve.md

# Stream URL resolver

`src/mux/resolve.rs` parses URL strings (`scheme://path`) into PES stream
instances.

## Scheme table

| Scheme | Input | Output | Path |
|--------|-------|--------|------|
| disc:// | Yes | -- | empty (auto-detect) or /dev/sgN |
| disk:// | Yes | -- | alias for `disc://` (identical behavior) |
| iso://  | Yes | -- | file path (required) |
| mkv://  | Yes | Yes | file path (required) |
| m2ts:// | Yes | Yes | file path (required) |
| network:// | Yes (listen) | Yes (connect) | host:port (required) |
| stdio:// | Yes (stdin) | Yes (stdout) | empty |
| null:// | -- | Yes | empty |
| demux:// | -- | Yes | directory path (required) — per-track ES demux |
| fvi://  | -- | Yes | file path (required) — per-picture video index |

Bare paths without a scheme are rejected.

## `image_input` (shared IMAGE-level source body)

`iso://` and `dir://` differ only in how the sectors are produced — a file
versus a synthesized UDF volume over a folder — and not at all in what is
done with them: scan, apply caller-resolved keys, gate on decryptability,
select the title, prune streams, correct TrueHD channel counts, mux. One
body means a `dir://` source cannot drift away from the `iso://` behaviour
that has years of fixes in it.

`reopen` yields a SECOND, independent reader for the TrueHD channel probe,
which must not disturb the mux reader's position. It returns `Option`
because a failed re-open is non-fatal: the correction is skipped, not the
mux.

## `FMTS_POOL_TAG_BASE`

CPS-unit id given to an FMTS forensic **index key** banked into the caller's
key pool by `resolve_fmts_key_map` (`FMTS_POOL_TAG_BASE + slot`).

The pool entry's first field is a CPS-unit number that the mapped decrypt
never reads — it indexes the pool by SLOT (`crate::decrypt::AacsKeyMap`
ranges carry slots) — so the field doubles as the tag that separates the
disc's BASE CPS unit keys from the forensic index keys appended on top of
them. Base ids come from a key's position in `Unit_Key_RO.inf` (+1), whose
count is a BE16, so they cannot exceed 65_536; this base is far above that,
so the two id spaces can never collide and misclassify a base key as
forensic (which would under-count the CPS units and hand the wrong key to a
whole extent).

## `single_base_key_slot`

The pool slot of the disc's ONE base CPS Unit Key, or `None` when the pool
holds several (a genuine multi-CPS disc) — the forensic index keys
(`FMTS_POOL_TAG_BASE`) that `resolve_fmts_key_map` appends to the same pool
are excluded, so the answer is a property of the DISC and not of how many
titles have already resolved through the shared pool.

## `base_slot_for_extent`

Which CPS unit's BASE Unit Key opens `ext`, as a pool slot — decided by this
extent's own ciphertext, exactly like the multi-CPS path in
`resolve_mux_key_map_cached`, and memoised in the same per-disc
`CpsUnitCache` so a clip several playlists share is sampled once.

Only base keys are considered: the forensic index keys share the pool but
belong to segment ranges, which are already mapped by tag before this runs.

`last_idx` is the slot resolved for the PRECEDING extent of this title,
carried into an extent with no sampleable encrypted units (nothing to
mis-decrypt). An extent that does have real ciphertext no held or fetched
key opens is a fail-loud `crate::error::Error::DecryptFailed` rather than a
silently wrong key over the whole extent.

## `resolve_fmts_key_map`

FMTS (AACS 2.1) branch of `resolve_mux_key_map`. Returns `Some(map)` when the
disc carries `IndividualSegment.tbl` AND a key source is configured; `None`
otherwise (not FMTS, or no source — the caller's base-Unit-Key path then
applies, and the forensic units garble and are dropped by the demux).

The forensic segments each carry an **index** tag (1..32) selecting one of 32
**index keys** the base Unit Key cannot open (see `crate::aacs::segment`).
This resolves those keys up front from the configured source — sending, per
index, a batch of same-index units the service maps to that index's key — adds
them to the pool, and builds a per-segment LBA→key map. Applying a segment's
key over its whole range decodes the ~40 units of that index's interleave half
to clean TS and garbles the other ~40 (the alternate half), which the demux
then drops, yielding one coherent stream. The base Unit Key covers everything
outside a segment.

The segment SPNs are offsets into the FORENSIC FEATURE CLIP, so every
clip-byte → LBA mapping here is anchored on that clip's own extents
(`forensic_clip_extents`) — never on `title.extents`, which on a play-all
playlist is the concatenation of several clips and would put the segments in
the wrong one.

Everything expensive here is memoised per DISC, not recomputed per title:
`cache.table` holds the UDF walk + `IndividualSegment.tbl` and `cache.clip`
the forensic clip's extents (both disc-invariant outright), and `cache.keys`
holds the index keys + phases. See `resolve_mux_key_map_cached` for why a hit
is provably the same answer. What remains per title is the pool→slot
mapping, the LBA range arithmetic and the base-key gap fill.

The gap fill covers each non-forensic LBA with the base Unit Key of the CPS
unit it belongs to. On the single-base-key disc that is every FMTS disc seen
so far that costs nothing; a disc with several base CPS Unit Keys resolves
each extent from its own ciphertext through `cps` (`CpsUnitCache`, shared
with the multi-CPS path so a clip is sampled once per disc).

## `probe_fmts_index_keys`

The drive- and key-service-hitting half of `resolve_fmts_key_map`: anchor the
disc's whole forensic index-key set from ONE key-service round trip, then
probe each index's interleave phase. Split out so the result can be memoised
per disc (`FmtsKeyCache`) — the arithmetic that turns these keys into a
per-title LBA map stays at the call site, where the title belongs.

`clip_extents` are the FORENSIC FEATURE CLIP's own extents — the byte space
the segment SPNs are relative to — and `segments` those addressable within
it; every read is `clip_byte_to_lba(clip_extents, …)`, so a probe never lands
in another clip's sectors whatever order a playlist lists its clips in.
Neither probe reads the caller's key pool, which is what makes the result
independent of resolve order across titles.

## `forensic_clip_extents`

The FMTS forensic feature clip's own extents — the byte space every
`IndividualSegment.tbl` SPN is relative to — or `None` when the disc does not
identify exactly one such clip.

An AACS 2.1 disc names its forensic feature `BDMV/STREAM/<clip>.fmts` (the
extension `bluray.rs` already resolves clip extents through), and the disc
carries ONE segment table, whose SPNs are therefore in ONE clip's byte space.
So: exactly one `.fmts` file → that clip's extents; none, or several (an
ambiguous SPN space), → `None`, which `resolve_fmts_key_map` turns into a
loud `Error::FmtsKeyMissing` rather than a guess.

This is a DISC fact — no title is consulted — which is exactly why it is a
sound anchor: a playlist's `extents` are the concatenation of ALL its clips
in playback order, so their byte space is the playlist's, not the forensic
clip's.

A read fault on the clip's ICB propagates (`Err`), like every other read on
this path; a purely structural absence is `Ok(None)`.

## `filter_addressable_segments`

Keep only the forensic segments addressable within the FORENSIC CLIP's
extents: a segment whose clip-byte start (`start_spn * 192`) maps to an LBA
inside the clip is real forensic content; one that does not is past the
clip's end (a stale or foreign table record) and is dropped. An empty result
means there is nothing forensic to resolve, so `resolve_fmts_key_map` returns
`Ok(None)` and the caller's base Unit-Key path applies. Extracted from
`resolve_fmts_key_map` for direct testing of the inclusion/exclusion
decision.

## `resolve_tie_phase`

Decide a forensic index's decrypt phase from the clean-sample counts of its
EVEN vs ODD aligned units under that index's key. Extracted from
`resolve_fmts_key_map` so the tie logic is unit-testable; the `tracing`
diagnostics stay at the call site, which holds the segment-index context.

* `even > odd` → `Phase::Even`; `odd > even` → `Phase::Odd` — the clean half
  is this index's real content variant.
* `even == odd == 0` → `Error::FmtsKeyMissing`: NEITHER half decrypts clean,
  so the key is wrong (or the sample is not this index's content) — fail
  loud rather than emit a broken segment.
* `even == odd > 0` → `Phase::Even`: BOTH halves are clean, i.e. source-zero
  padding (clean under any key), so the parity is immaterial — default Even.

## `IndexProbe`

Outcome of probing ONE forensic index's decrypt phase (see
`probe_index_phase`). The load-bearing distinction is between the last two: a
genuine wrong key and a transient live-drive read fault both leave zero clean
decrypts, but only the former is a real `FmtsKeyMissing` — the latter must
NOT abort a rip whose index keys are valid.

## `probe_index_phase`

Probe one forensic index's decrypt phase by reading a representative
segment's EVEN vs ODD aligned units and counting clean decrypts under `key`.
Extracted from `resolve_fmts_key_map` so the read-fault-vs-wrong-key decision
is directly testable without a full UDF/segment-table fixture.

Mirrors the anchor loop's read-fault tolerance: try up to `max_segments`
same-index segments (rather than a single `.find`), skipping any whose reads
all fault, and only conclude `IndexProbe::WrongKey` once a segment actually
yielded decrypt attempts. If EVERY read of EVERY same-index segment faults,
return `IndexProbe::ReadFault` — the caller then leaves the phase unresolved
(defaults to `Phase::All`) instead of hard-aborting the rip. `read(seg,
unit)` reads aligned unit `unit` of `seg`; `None` is a read fault.

Masking guard: `IndexProbe::ReadFault` is returned ONLY when not a single
read succeeded, so a genuine wrong key (whose reads DO succeed) can never be
masked as a read fault — any successful, non-clean decrypt yields
`IndexProbe::WrongKey`.

## `fill_base_key_gaps`

Back-fill the LBA gaps NOT covered by the forensic segment ranges with the
base Unit Key, so the finished map is a COMPLETE positive list over the
title's content extents: every content LBA resolves to either a forensic key
(inside a segment) or the base key (`base_idx`). An LBA left in no range
would pass ciphertext through as clear — this range arithmetic guarantees
there is no such hole inside any extent. Extracted from `resolve_fmts_key_map`
for exhaustive direct testing (gaplessness over every extent).

`forensic_ranges` are the already-built per-segment ranges; only their
`[start, end)` spans matter here (they carve the holes — the key idx / phase
are irrelevant). The return is the base-key fill ranges ONLY; the caller
appends them to `forensic_ranges` to form the full map.

## `resolve_mux_key_map`

This is what ends the key-server storm. The old mux decrypted a unit, checked
whether the plaintext looked like clean MPEG-TS, and — because authored-bad
content never reaches that bar — re-asked the key service for a key it
already held. There is no per-unit byte pattern that separates "correctly
decrypted but authored-bad" from "still encrypted", so that check is
unanswerable. Here we answer the answerable question instead: which CPS unit
does each LBA range belong to, decided by the disc's key structure (validated
once against real ciphertext samples, where the `is_clean` proof IS sound).
The mux then just decrypts each unit with its mapped key and trusts it.

Single-CPS (the overwhelming majority, incl. every single-key UHD) keys every
content extent with one index; multi-CPS keys each extent with the key that
opens a real sample from it; FMTS layers per-segment index keys on top. Any
LBA outside the title's content (nav/filesystem) is in no range and passes
through.

## `CpsUnitCache`

Memoises the multi-CPS "which held unit key opens this extent" decision
across the titles of ONE disc, for `resolve_mux_key_map_cached`.

Keyed by content format plus the extent's exact `(start_lba, sector_count)`,
so a hit returns the index that was resolved from *those same physical
bytes* — see the safety argument on `resolve_mux_key_map_cached`. Only
successfully resolved extents are memoised; a no-samples extent (whose index
is inherited from the preceding extent of the SAME title, i.e. not a
property of the extent) and the fail-loud "no key opens it" outcome are
never cached.

A disc's playlists overwhelmingly reference the same handful of clips (main
feature, play-all, per-chapter and seamless-branch variants), so without this
the same extents are re-sampled off the drive once per playlist: 8 random
6144-byte reads each, ~200 ms of seek apiece on a stock BD drive.

Scope, stated precisely: this memo covers the extent-sampling reads that
decide which CPS unit an extent belongs to, and nothing else. On an FMTS
(AACS 2.1) disc `resolve_fmts_key_map` runs first and returns a finished map
before the extent loop below is ever reached, so the loop's reads are
removed by `FmtsTableCache` and `FmtsKeyCache` instead — but a MULTI-CPS
FMTS disc samples through this same memo from the gap fill
(`base_slot_for_extent`), and the cached value means the same thing on both
paths: the pool slot whose key opens that extent's own ciphertext.

## `FmtsTableCache`

The disc's forensic segment table (`/AACS/IndividualSegment.tbl`), resolved
at most ONCE per disc: `None` = not looked for yet; `Some(None)` = looked for
and this disc is not FMTS; `Some(Some(v))` = the parsed, non-empty segment
list.

Every input is a property of the MEDIA, not of a title: the UDF walk
(`crate::udf::read_filesystem`) reads fixed low LBAs (the anchor at 256, the
VDS, the FSD, the root directory), `read_file` follows that file's own
allocation descriptors, and `parse_individual_segments` is pure. Re-running
it per title re-reads ~35 single sectors at low LBAs from a head the
previous title's content sampling left deep in the content area — a
full-stroke seek out and back per playlist, for a byte-identical answer.

Only the two *deterministic* negatives are memoised as "not FMTS"
(`UdfNotFilesystem`, and `UdfNotFound` for the table): a read fault is NEVER
cached, so a transient failure still propagates and a later title still
retries.

## `FmtsKeyCache`

Memoises the FMTS (AACS 2.1) forensic **index-key set and per-index phase** —
the expensive half of `resolve_fmts_key_map` — across the titles of ONE disc.

Keyed by `(format, the title's exact extent list)`, mirroring
`crate::disc::pgs_forced_probe::ForcedProbeCache`. Every read the anchor
probe, the phase probe and the key-service call make is
`clip_byte_to_lba(forensic_clip_extents, …)` and the probed segments are
`filter_addressable_segments(_, forensic_clip_extents)` — both DISC facts
(see `forensic_clip_extents`), so the answer no longer varies by title at
all. The extent list is KEPT in the key deliberately: it is finer than the
answer needs, so each distinct extent list still gets its own verdict rather
than inheriting another's, and a title can never be served an answer
resolved from bytes it does not read. Two titles with the same extent list
feed byte-identical samples to a stateless `crate::sector::KeyFetch` and to
the same `is_clean` arithmetic under the same `format` — see the safety
argument on `resolve_mux_key_map_cached`.

The value holds the ordered index keys (element `i` = forensic index `i + 1`)
and the resolved phase per index tag. It is key material: never logged,
never rendered, and dropped with the disc's resolve.

## `FmtsClipCache`

The disc's forensic feature clip extents, resolved in the SAME UDF walk as
`FmtsTableCache` and at most once per disc: `None` = not looked for yet;
`Some(None)` = looked for and not identifiable (or the disc is not FMTS);
`Some(Some(v))` = the clip's extents, the anchor for every segment SPN.

A disc fact like the table itself — see `forensic_clip_extents` for why, and
for what `Some(None)` costs on an FMTS disc (a loud `FmtsKeyMissing`, not a
guess).

## `resolve_mux_key_map_cached`

`resolve_mux_key_map` with a caller-owned per-disc cache (`DiscKeyCache`)
shared across the titles of one disc.

### Why a cache cannot change a resolved key

#### Multi-CPS extents (`CpsUnitCache`)

The cached value is the pool index `pick` chose for an extent, and every
input to that choice is stable across the titles of one disc:

* The samples are a deterministic function of the extent's `(start_lba,
  sector_count)` and `format` — both in the key — read from unchanging media.
* The key pool is APPEND-only here (base-key fetch and the FMTS resolver only
  push), and `pick` returns the FIRST pool entry that opens a sample, so a
  later, longer pool yields the same first match for the same samples.
* `crate::sector::KeyFetch` is stateless by contract, and any key a hit's
  index refers to was already banked into the pool on the miss that filled
  the entry — so skipping the re-fetch skips no side effect the map depends
  on.

#### FMTS segment table (`FmtsTableCache`)

Disc-invariant outright: no input to the UDF walk, the `read_file` or the
parse mentions the title. See the type's doc for the negatives that are
(and are not) memoised.

#### FMTS forensic clip extents (`FmtsClipCache`)

Disc-invariant outright, like the table: the clip is found by name in the
UDF tree and its extents come from its own allocation descriptors. No title
is consulted — which is the point. It is the byte-space anchor for every
segment SPN, and anchoring on a TITLE's extent list instead made a playlist
that lists a trailer before the feature map every segment into the
trailer's sectors.

#### FMTS index keys and phases (`FmtsKeyCache`)

Every input to the anchor and phase probes is now a disc fact: the probes
read `clip_byte_to_lba(forensic_clip_extents, …)` and visit
`filter_addressable_segments(_, forensic_clip_extents)`. The title's extent
list stays IN the key anyway — a strictly finer key than the answer needs,
so no title inherits a verdict resolved from bytes it does not read. Given
the same key, the same `format` and unchanging media:

* `filter_addressable_segments` yields the same segments in the same order,
  so the anchor loop and each `probe_index_phase` visit the same segments.
* every probe read is at the same LBA, so the same ciphertext is fed to a
  `crate::sector::KeyFetch` that is stateless by contract, and to the same
  `aacs_unit_encrypted` / `decrypt_unit` / `is_clean` arithmetic.
* NEITHER probe reads the key pool. The anchor takes its keys from `fetch`;
  the phase probe takes them from the anchor's reply. So the pool's growth
  across titles — the one thing that does change between calls — cannot
  move this result, and the cached value is independent of the order titles
  are resolved in.

What is deliberately NOT memoised, which is what makes this safe rather than
merely faster:

* the fail-loud `FmtsKeyMissing` verdicts (no anchor, wrong key), so a retry
  after a key source is reconfigured re-probes rather than inheriting
  nothing;
* a run where any index's phase probe came back `IndexProbe::ReadFault` —
  that leaves the phase defaulted to `Phase::All` (degraded but complete), a
  property of a transient live-drive fault and NOT of the extents. Caching
  it would spread one bad read across every remaining title.

Everything downstream of the cache still runs per title: the pool insertion
that turns index keys into slots, the per-segment LBA range arithmetic, and
the base-key gap fill — all of which genuinely depend on this title's
extents.

Halt is polled per extent AND once on entry to the FMTS branch, so a
60-playlist sweep stays cancellable even when every title is served from
cache.

## `build_iso_pipeline` parameters

Assembles the ISO mux pipeline (read+decrypt → demux → parse) for a
`FileSectorSource`-backed reader. Returns the resulting `PipelinedPesStream`.

- `reader`: the sector source to read from (typically a `FileSectorSource`
  over the ISO image).
- `title`: the selected title; its `extents` drive the read range and its
  `streams` build the demux/parse tables.
- `keys`: decryption keys applied per sector batch. Pass
  `crate::decrypt::DecryptKeys::None` for raw / unencrypted reads (the
  decrypt decorator then becomes a pass-through).
- `batch_sectors`: read batch size in logical (2048-byte) sectors — a
  throughput/latency tuning knob, not a correctness parameter.
- `format`: container format (`BdTs` → TS demuxer, `MpegPs` → PS demuxer).
- `raw`: ciphertext passthrough. When `true`, the per-title CSS crack
  (`resolve_dvd_title_key`) is skipped entirely — no key is resolved and a
  scrambled title is neither descrambled nor hard-failed.
- `halt`: cooperative cancel token (not a timeout); when cancelled the
  pipeline stops at the next boundary (and the CSS crack surfaces `Halted`).
  `None` disables cancellation.
- `event_fn`: optional progress/event callback invoked by the prefetcher.
- `fetch`: optional key source used UP FRONT by `resolve_mux_key_map` to
  secure any CPS-unit key the pool is missing. Not a per-unit mux-time
  callback: the map decides the key for every LBA before the read loop
  starts.

Nine reader/title/keys/tuning/callback params is inherent to the mux entry
point; grouping them into a struct would only move the same fields around.

## `parse_url_never_panics_on_adversarial_input`

`parse_url` must never panic on ANY input — it is the front door for
caller-supplied URL strings, so a panic here would crash the binary on
malformed input instead of surfacing a clean error downstream. Feed it a
battery of adversarial strings (empty, doubled/garbled schemes, embedded
NUL, unicode, a very long path, lone scheme markers) plus an exhaustive
sweep of every single byte 0x00..=0xFF as the whole input and as a scheme
suffix. Any `StreamUrl` variant is an acceptable result; the only failure
mode under test is a panic.

## `fvi_output_records_the_source_not_the_destination`

`fvi://` must record the SOURCE in `source.{path,medium,title}`. It used to
pass the DESTINATION path as `FviSink::create`'s `source_path` (and default
the medium/title), so every index claimed to be its own source —
`docs/FVI_FORMAT.md` §6.2 defines `source` as describing the input.

## `fvi_output_is_reproducible_across_destination_paths`

The property the destination-as-source defect broke: two runs indexing the
SAME source must produce byte-identical output regardless of where they
write. Previously the header embedded the destination path, so the two
files differed (and differed in length when the paths differed in length)
purely from where they landed.

## `parse_dir_url_is_an_image_source_unlike_the_directory_sinks`

`dir://PATH/` parses to `StreamUrl::Dir` with the raw remainder as the path.
Unlike the other directory schemes it IS an image-level source (1.6.1):
`crate::dirimage` synthesizes a UDF volume over the folder, so
`is_disc_source()` — "has a filesystem to scan" — is true for it and false
for the write-only `demux://` / `fvi://` directory sinks.

## `dir_url_is_an_input_but_never_a_pes_sink`

`dir://` is never a PES SINK — it writes raw decrypted files, not muxed
frames, so `output()` still rejects it (StreamReadOnly → Unsupported) and
the CLI routes a `dir://` dest to `Disc::extract_tree`.

As a SOURCE it is no longer rejected out of hand: it is an image source, and
a missing folder now fails as a missing folder (NotFound) rather than as
"this scheme cannot be read".

## `build_demux_state_bdts_builds_ts_demuxer_and_pid_table`

BdTs format must build a TsDemuxer (Some(ts), None(ps)) when there is at
least one PID, and one parser + pid_to_track entry per stream keyed by the
stream's own PID. (Mis-keying here is exactly the class of bug that
mis-routes PES into the wrong codec parser.)

## `HaltCountSource`

A counting `SectorSource` over zeros. `touched_extent` flags whether any
read landed in the title's extent region (LBA >= 1000); the UDF probe only
reads near LBA 256 (small `capacity`), so a hit there means the expensive
per-extent `sample_units` loop ran.

## `resolve_mux_key_map_honors_pre_cancelled_halt`

`resolve_mux_key_map` on the multi-CPS live path must honor a pre-cancelled
halt PROMPTLY — `Err(Halted)` at the first extent boundary, before sampling
any extent's ciphertext — rather than reading through every extent. This is
the round-2 Fix 1 guard: the resolve chain runs on the LIVE drive (each
`read_sectors` can stall to the SCSI recovery timeout), so an operator Stop
during key resolution must interrupt it.

Mutation: dropping the `halt.is_some_and(...) → Err(Halted)` check in the
multi-CPS extent loop makes the resolve run the sampling reads and return
`Ok(map)` (zeros sample to no encrypted units → carry key 0), so
`expect_err` fails AND `touched_extent` flips true.

## `bdts_data_packet`

Build a 192-byte BD-TS data packet on `pid` carrying `payload` as the TS
payload (payload-only adaptation). Layout: 4-byte TP_extra_header (zeros) +
188-byte TS packet (sync 0x47, PID, PUSI, AFC=0b01). Mirrors the BD-TS
framing in ts.rs.

## `build_iso_pipeline_empty_extents_clean_eof`

Empty extents → the producer thread exits immediately, the demux thread sees
a clean channel close and emits the Eof sentinel, and the PipelinedPesStream
returns Ok(None) on the first read. The highway must terminate cleanly (no
panic, no hang) when there is nothing to read.

## `build_iso_pipeline_delivers_one_frame_then_eof`

End-to-end: one BD-TS packet carrying a complete audio PES flows read →
decrypt(passthrough) → TS demux → codec parse → one PesFrame. Proves the
full highway wiring delivers the ES payload intact and reaches a clean EOF
afterward (never silently truncating the frame).

## `build_iso_pipeline_pruned_title_drops_unselected_pid_frames`

End-to-end proof of stream selection: a title declaring TWO audio PIDs,
pruned to one via `StreamSelection::apply` BEFORE `build_iso_pipeline`, must
never surface a frame from the excluded PID. The demuxer is built from the
pruned `title.streams`, so the excluded PID is untracked and its packets are
skipped — track headers and frames both follow the pruned list, which is
the whole point of the selection seam.

## `build_iso_pipeline_dvd_none_keys_scrambled_hard_fails`

REGRESSION (autorip production corruption): `build_iso_pipeline` for a DVD
(MPEG-PS) with `None` keys — what autorip's mux passes on a detection-miss
DVD (`disc.decrypt_keys()` == None) — must resolve the CSS key from the
reader itself. A scrambled-but-uncrackable title must HARD-FAIL, never build
a passthrough pipeline that muxes the scrambled sectors as corrupt video.
Before this fix, autorip handed None straight through and the mux wrote
garbage at exit 0.

## `content_map_builds_exact_ranges_from_extents`

`content_map(title, idx)` keys every single-CPS UHD disc (the common case):
each content extent → one `[start_lba, start_lba+sector_count)` range at
`idx`, phase `All`. Assert the exact ranges — an off-by-one on the end (or a
wrong idx / phase) must flip this test to FAIL.

## `filter_addressable_segments_keeps_only_in_title_segments`

BEHAVIOR 1 — segment filter (`resolve_fmts_key_map` line ~800). A segment
whose clip-byte start (`start_spn * 192`) maps inside the title's extents is
kept; one whose start is past the clip is dropped; all-outside → empty (the
resolver then returns `Ok(None)` and the base-UK path applies).

## `resolve_tie_phase_covers_all_arms`

BEHAVIOR 2 — phase-tie default (`resolve_fmts_key_map` line ~936). All four
arms of the even/odd clean-count decision.

## `assert_gapless`

Assert `forensic` + `fills` together cover every LBA of every extent EXACTLY
once — no gap (a hole would pass ciphertext through as clear) and no
overlap (two keys over one LBA). This is the load-bearing invariant of the
gap-fill.

## `fill_base_key_gaps_is_gapless_over_every_extent`

BEHAVIOR 3 — gap-fill range arithmetic (`resolve_fmts_key_map` line ~1005).
Exhaustive: no segments, mid-extent, at-start, at-end, adjacent segments,
and multi-extent. Each asserts the EXACT fills AND gaplessness over every
extent — an off-by-one that leaves a hole flips this to FAIL.

## `encrypted_clean_unit`

Build a 6144-byte aligned unit of CLEAN MPEG-TS (sync `0x47` + non-zero
payload in packets 1.., packet 0 is the clear seed) then AACS-encrypt it
under `key`. Decrypting under the SAME key restores clean TS (`is_clean` →
true); decrypting under any other key yields garbage.

## `probe_index_phase_all_faults_is_read_fault_not_wrong_key`

A probe whose EVERY read faults (`read` returns `None`) must classify as
`IndexProbe::ReadFault`, NOT `IndexProbe::WrongKey` — a transient live-drive
read fault while probing must not be read as a missing key (which the
caller turns into a rip-aborting `FmtsKeyMissing`).

Mutation: reverting to the no-fallback single-segment probe (i.e. treating
even==odd==0 as unconditional `FmtsKeyMissing` regardless of whether any
read succeeded) makes this return `WrongKey` → the assert fails.

## `probe_index_phase_reads_succeed_but_no_clean_phase_is_wrong_key`

Reads SUCCEED but decrypt to NEITHER clean parity (ciphertext under a key we
do NOT hold) → `IndexProbe::WrongKey`. This is the genuine-missing-key path
the caller MUST keep as a hard `FmtsKeyMissing`.

## `probe_index_phase_falls_through_faulting_segment_to_next`

Read-fault TOLERANCE across segments: the first same-index segment faults on
every read, but a SECOND same-index segment decrypts clean → the probe must
fall through to it and resolve a phase (mirrors the anchor loop's
multi-segment retry). A single-`.find` probe would have stopped at the
faulting first segment.

## `CipherSource`

A SectorSource that tiles a fixed 6144-byte ciphertext unit across each
registered extent range (`(start_lba, end_lba, unit)`), zeros elsewhere.
Every 3-sector aligned-unit read inside a range returns the same ciphertext,
so `sample_units` collects real encrypted content for `pick`/fetch to run
on. Low LBAs are zero, so `udf::read_filesystem` fails → the FMTS branch
returns `Ok(None)` and the multi-CPS path is exercised.

## `resolve_mux_key_map_multi_cps_pick_selects_correct_index`

`pick()` must select the pool index of the key that actually opens the
extent's real ciphertext — index 2 here, NOT 0. Feeds units encrypted under
the third pool key through the live multi-CPS path.

Mutation: `pick` hard-returning `Some(0)` keys the extent to 0 → this assert
(Some(2)) fails.

## `resolve_mux_key_map_multi_cps_fail_loud_on_absent_key`

Fail-loud: a sample that decrypts clean under NO held key and NO fetched key
(fetch = None) must surface `Error::DecryptFailed`, never silently key the
extent to a neighbour's (wrong) index.

Mutation: dropping the `None => Err(DecryptFailed)` guard (e.g. falling back
to `last_idx`) returns `Ok` → this `expect_err` fails.

## `resolve_mux_key_map_multi_cps_fetch_recovers_missing_key`

KeyFetch cold path: the pool is missing the extent's key, but the injected
`KeyFetch::unit_keys` returns it from the failing samples → the extent
resolves to the newly-appended pool index (2) and the map succeeds. Proves
the on-miss fetch+re-pick branch runs end to end.

## `CountingCipherSource`

`CipherSource` plus a counter of CONTENT reads (`lba >= CONTENT_LBA_FLOOR`) —
the `sample_units` probes whose cost this cache exists to remove. Low-LBA
UDF metadata probes are excluded so the counts speak only about extent
sampling.

## `multi_cps_shared_extent_is_served_from_cache_not_resampled`

A disc's playlists overwhelmingly share clips, and the multi-CPS path issues
8 random 6144-byte reads per extent. The SECOND title over the same extent
must cost ZERO further reads and resolve the SAME index; a DIFFERENT extent
must still be sampled and get its own index.

Mutation: dropping the `cache.get` short-circuit re-samples → the
zero-further-reads assert fails. Caching the wrong index (e.g. inserting
`last_idx`) breaks the same-index asserts.

## `multi_cps_cache_hit_matches_a_full_recompute`

The cached index must be exactly what a full recompute produces: resolve the
same title twice, once through a warm shared cache and once through a cold
one (a real re-read), and compare the maps range for range.

Mutation: caching under a key that ignores `start_lba`/`sector_count`, or
storing anything but `pick`'s index, diverges here.

## `multi_cps_inherited_index_is_not_cached`

An extent with no sampleable encrypted units inherits the PRECEDING extent's
index — per-title state, not a property of the extent — so it must never be
memoised. Title A reaches the clear extent carrying index 2, title B carries
index 1: B's clear extent must key to 1, not to A's cached 2.

Mutation: caching the `samples.is_empty() => last_idx` arm makes B's clear
extent resolve to 2 and this fails.

## `multi_cps_failed_extent_is_not_cached`

A fail-loud extent (real ciphertext no key opens) must not be memoised: a
later retry, after a key source banked the missing key, has to re-sample and
succeed rather than inherit the earlier failure.

Mutation: caching before the `None => Err(DecryptFailed)` arm (or caching
the error) leaves the retry unable to resolve.

## `FaultSource`

A SectorSource whose every read is a transient I/O fault (`DiscRead`),
modelling a marginal live drive stalling while `resolve_fmts_key_map` probes
the UDF metadata / segment table.

## `resolve_fmts_key_map_read_fault_propagates`

A transient `DiscRead` fault while reading the UDF metadata for the segment
table must PROPAGATE (fail loud / retryable), NOT be swallowed into the
not-FMTS `Ok(None)` fall-through — otherwise a marginal AACS 2.1 disc would
silently drop its forensic content under a base-Unit-Key-only map and the
mux would report success.

Mutation: revert the read_filesystem arm to `let Ok(udf) = ... else { return
Ok(None) }` → this returns `Ok(None)` and the assert fails.

## `resolve_fmts_key_map_not_udf_is_clean_none`

A reader whose bytes are structurally NOT a UDF disc (all zeros → no AVDP at
sector 256 → `UdfNotFilesystem`) is genuinely not FMTS: it must map to the
clean `Ok(None)` negative, NOT fail loud. Guards against Fix 1 over-reaching
and rejecting benign non-FMTS discs.

## `fmts_disc_with_extra_records`

The same synthetic disc with extra records appended to
`IndividualSegment.tbl` ONLY — the content region is laid out from
`fmts_segments` exactly as before, so the anchor and phase probes still
resolve normally and the extra records are seen purely by the range
builder. That is what isolates each of its "this record does not map" arms.

## `FmtsDisc::rebuild_meta` / `with_forensic_clip`

`clip = false` drops `BDMV/STREAM/00001.fmts` from the tree: an FMTS disc
(the table is there) whose forensic clip cannot be identified, so the
segment SPNs have no defensible anchor. `rebuild_meta` returns just the UDF
metadata image, with `tbl_segs` as the segment table and the forensic clip
present — see `fmts_disc_with_extra_records`.

## `FmtsDisc::with_second_cps_unit`

The same disc, plus a second CPS unit occupying the extent at
`FMTS_CPS2_LBA` — a disc whose `Unit_Key_RO.inf` carries two base Unit Keys,
which is what makes "the base key" ambiguous.

## `FmtsDisc::unit_at`

The 6144-byte ciphertext of the aligned unit starting at clip byte
`unit_byte`: inside a segment, EVEN units carry that index's content and ODD
units the alternate variant; outside, ordinary base-Unit-Key content.

## `counting_fmts_fetch`

A `KeyFetch` whose `fmts_indexes` counts its calls and behaves like the real
service: it replies with the disc's COMPLETE ordered index-key set only for
a genuine index-1 anchor batch (one that opens under index key 1), and empty
otherwise. `unit_keys` is never used on this path.

## `fmts_two_cps_title`

A play-all title over BOTH CPS units: the forensic clip (CPS unit 1) then
the second unit's extent (CPS unit 2).

## `fmts_two_cps_keys`

The disc's two BASE CPS Unit Keys, in `Unit_Key_RO.inf` order — the pool an
AACS 2.1 disc with two CPS units is resolved with.

## `fmts_gap_fill_uses_each_lbas_own_cps_unit_key_not_pool_slot_zero`

On an FMTS (AACS 2.1) disc the non-forensic gap fill used to hardcode pool
slot 0 as "the" base Unit Key. On a disc carrying MORE THAN ONE base CPS
Unit Key in `Unit_Key_RO.inf` that is simply the first CPS unit's key, so
every content LBA outside a forensic segment in any OTHER CPS unit was
keyed with the wrong key.

It does not fail loudly: the mapped decrypt runs the wrong key over those
units and emits garbage plaintext with `lost_bytes == 0`. And
`resolve_mux_key_map_cached` calls the FMTS resolver BEFORE the
`single_base_key_slot` short-circuit, so the guard that makes slot 0 correct
on a single-CPS disc is never consulted on this path.

The title spans both CPS units; the second extent's every unit is encrypted
under the SECOND base key (pool slot 1). Mutation: pinning the gap fill back
to slot 0 fails the second extent's asserts, and pinning it to slot 1 fails
the first extent's.

## `fmts_index_keys_resolved_once_per_disc_not_once_per_title`

The defect this fixes: `resolve_content_key_map` resolves EVERY title, and
the FMTS branch used to re-walk the UDF filesystem, re-run the anchor probe,
re-run the 2-index phase probe AND re-ask the key service — once per
playlist — for an answer that is a property of the DISC. N titles must cost
ONE UDF walk, ONE index probe and ONE `fmts_indexes` call.

Mutations, and which assert kills each:
* `if table.is_none()` → `if true` (never memoise the segment table): the
  `meta_reads` assert fails (the walk repeats per title).
* removing the `memo.get(&ek)` short-circuit: the `probe_reads` AND the
  `fmts_indexes` call-count asserts both fail.
* `if probed.all_phases_definite` → `if false` (never insert): same two.

## `fmts_memoised_map_equals_per_title_recomputation`

Result-identity, proven rather than assumed: the same three titles resolved
with a SHARED per-disc memo must produce the same maps — and leave the key
pool in the same state — as resolving each with a FRESH memo (i.e. the
unmemoised per-title recomputation).

Mutation: key the FMTS memo on something NOT title-invariant (e.g. drop the
extent list from `extent_key` and key on `format` alone) → title 3's
differing extents are served the wrong answer and the range comparison
fails.

## `fmts_different_extent_list_is_a_miss_and_reprobes`

A DIFFERENT extent list is a genuine miss: the extent list is the only
per-title input to the probes, so it is IN the memo key and a title with a
different one must re-probe rather than inherit.

Mutation: drop `title.extents` from `extent_key` → the second title hits
and the `probe_reads` / call-count asserts fail.

## `fmts_read_faulted_phase_is_not_memoised`

A phase probe that READ-FAULTED on every segment of an index leaves that
index defaulted to `Phase::All` — degraded but complete. That is a property
of a transient live-drive fault, NOT of the title's extents, so it must NOT
be memoised: caching it would spread one bad read across every remaining
playlist. The next title must re-probe.

Mutation: memoise unconditionally (drop the `all_phases_definite` guard) →
the second title is served from cache and both the `probe_reads` and the
key-service call-count asserts fail.

## `non_fmts_disc_walks_the_filesystem_once_for_every_title`

The UDF walk that decides whether a disc is FMTS at all runs on EVERY disc,
FMTS or not. On a plain (non-UDF / non-FMTS) BD it must be attempted ONCE
for the whole disc, not once per playlist — ~35 low-LBA single-sector reads
reached by a full-stroke seek back from wherever the last title's content
sampling left the head.

Mutation: `if table.is_none()` → `if true` → the second title re-reads the
metadata and the `meta` assert fails.

## `fmts_memoised_title_still_honors_halt`

Halt must stay responsive even when both FMTS memos are warm and a title
does no I/O at all: `resolve_content_key_map` polls nothing itself, so the
entry check inside the FMTS branch is the only cancellation point a
fully-memoised title reaches.

Mutation: remove the `check_halt()?` at the top of `resolve_fmts_key_map` →
the cancelled second title returns `Ok(map)` and `expect_err` fails.

## `single_cps_short_circuit_survives_a_forensic_title_resolving_first`

The single-CPS short-circuit must depend on the number of BASE CPS Unit
Keys, NOT on the length of the whole pool — which the FMTS resolver APPENDS
its forensic index keys to. Before the fix, a disc whose first-resolved
playlist was forensic left the shared pool at `1 + n_index`, so every LATER
title (single-CPS, non-forensic) missed the short-circuit and took the
multi-CPS sampling path: 8 random 6144-byte reads per extent, and a
`DecryptFailed` abort of the WHOLE-disc key map for any extent no pooled
key opened. That made the result depend on the ORDER titles resolve in,
contradicting the order-independence `resolve_mux_key_map_cached`
documents.

Mutation: count the whole pool (`unit_keys.len() == 1`) → the menu title
samples its extent and the `probe_reads` assert fails.

## `forensic_segments_anchor_to_the_forensic_clip_not_the_titles_first_extent`

Forensic segment SPNs live in the FORENSIC FEATURE CLIP's byte space, so
mapping them through the TITLE's extent list is wrong for any playlist whose
extents do not begin with that clip. On a play-all playlist ordered
[trailer, forensic feature] the old code treated clip byte 0 as the
trailer's first sector: every segment landed 300 sectors early, the anchor
probe sampled the TRAILER (so the key service never anchored →
`FmtsKeyMissing` aborted the whole disc), and had it anchored, the index
keys would have been applied to non-forensic sectors — silent garble with
no error at all.

Mutation: anchor the byte space on `title.extents` again → the resolve
either errors (no anchor) or maps segment 1 to 10_000 instead of 10_300.

## `unidentifiable_forensic_clip_fails_loud_rather_than_guessing_an_anchor`

The anchor is only sound because the forensic clip is IDENTIFIED. A disc
that carries a non-empty `IndividualSegment.tbl` but no `BDMV/STREAM/*.fmts`
gives the SPNs no defensible byte space, so the resolve must fail LOUD
(`FmtsKeyMissing`, retryable) rather than fall back to a title's extent list
and map forensic index keys onto whatever clip happens to be first — which
produces silently garbled output with no error at all.

## `single_base_key_slot_counts_cps_units_not_banked_forensic_keys`

The base-CPS count that drives the single-CPS short-circuit, in isolation:
the forensic index keys the FMTS resolver appends (tagged
`FMTS_POOL_TAG_BASE + n`) are NOT CPS units, and a genuine second CPS unit
is.

Mutation: drop the tag filter → the first case returns `None` and its
assert fails.

## `fill_base_key_gaps_sorts_cuts_that_arrive_in_table_order_not_lba_order`

The forensic ranges reach `fill_base_key_gaps` in `IndividualSegment.tbl`
RECORD order, which is not LBA order — the table is a list of segments, and
nothing in `aacs::segment` sorts it. The gap walk is a single forward sweep
(`cur = cur.max(ce)`), so it is only correct on cuts in ascending order;
that is what `c.sort_unstable()` is for.

Every existing gap-fill case happens to pass its cuts already sorted, so the
sort is unconstrained by them. Here the cuts arrive REVERSED: without the
sort the sweep takes the high cut first, jumps `cur` past it, then discards
the low cut as "already behind" — and emits a base-key fill straight over
the low forensic segment. That is the silent-wrong-key shape: the forensic
LBAs end up in TWO ranges, one of them keyed with the base Unit Key.

## `RecordingSource`

A `SectorSource` that records every `(lba, count)` it is asked for and
serves a caller-chosen aligned unit, so the probe SPREAD of
`sample_encrypted_units` is observable directly.

## `sample_encrypted_units_probes_eight_aligned_units_spread_across_the_extent`

`sample_encrypted_units` is the evidence every CPS-unit decision rests on,
so WHICH units it reads matters: 8 probes at `total * p / 9` for p in 1..=8,
each a whole aligned unit (3 sectors) measured from the extent's own start.

Pinned exactly. A probe count, a divisor or a `p` range that drifts moves
the sample set — clustering probes at one end of a 20-minute clip, where an
authored-bad or padding region can make an extent look unopenable — and
each of those is an independently reachable mutation of this arithmetic.

## `sample_encrypted_units_drops_clear_units_and_reads_nothing_below_one_unit`

Only genuinely AACS-encrypted units come back — that is the whole contract
that lets a caller treat a decrypt-to-clean as proof of the key. A clear
(unencrypted) extent yields NO samples, which is what makes `pick_pool_slot`
return `None` and the caller inherit rather than fail loud.

## `pick_pool_slot_honours_the_caller_s_slot_list_and_its_order`

`pick_pool_slot` answers "which of THESE slots, in THIS order, opens the
extent" — and its two callers pass different slot lists for a reason: the
multi-CPS path offers the whole pool, the FMTS gap fill only the BASE keys
(offering a forensic index key there would key a whole extent with it).

So both the RESTRICTION and the ORDER are load-bearing, and neither is
implied by "some slot matched". Two samples open under two different pool
slots here, so the answer is decided purely by which slot the caller listed
first — a `find` that ignored `slots` order, or that scanned the pool
instead, would return the same value for both directions.

## `extents_overlap_is_half_open_at_both_ends`

Extents are `[start_lba, start_lba + sector_count)` — half open. This
decides whether a title "reads the forensic clip", i.e. whether
`resolve_fmts_key_map` resolves index keys at all or returns `Ok(None)` and
leaves the title on the base-Unit-Key path.

Both directions are wrong in a way that does not fail loudly: an inclusive
end makes a title that merely ABUTS the forensic clip resolve (and pay a
key-service round trip) for content it does not read, while a stricter test
makes a title that shares exactly one sector fall through to a
base-key-only map and silently garble its forensic units.

## `fmts_resolve_err_with`

Resolve the synthetic FMTS disc with `extra` bogus records appended to its
segment table, and return the error text.

## `fmts_baseline_table_resolves_so_the_unmappable_record_tests_mean_something`

Control: the SAME resolve with no extra records succeeds. Without this the
four tests below could be passing for any reason at all — a fixture that
never reaches the range builder would `expect_err` just as happily.

## `fmts_inverted_segment_record_aborts_rather_than_base_keying_the_hole`

Arm 1 — an INVERTED record (`start_spn > end_spn`). `end_byte - 1 -
start_byte` would underflow, so the record is refused; the tally is what
turns that refusal into a loud failure instead of a base-keyed hole.

## `fmts_record_with_no_index_key_aborts_rather_than_base_keying_the_hole`

Arm 2 — a record whose forensic INDEX has no key. The synthetic source
returns two index keys, so tags 1 and 2 have pool slots and tag 3 has none.
On a real disc this is a table that outruns the key set the service
returned — precisely the case where guessing a key is worst.

## `fmts_record_running_past_the_clips_end_aborts_rather_than_base_keying_it`

Arm 3 — a record whose START is addressable within the clip (so
`filter_addressable_segments` keeps it) but whose END runs past the clip's
last byte. Only the second `clip_byte_to_lba` fails, which is why the
filter upstream cannot stand in for this check.

## `fmts_record_off_the_aligned_unit_grid_aborts_rather_than_spanning_wrongly`

Arm 4 — a record whose LBA span is not one contiguous run: `b - a` counts
SECTOR crossings while `(end_byte - 1 - start_byte) / 2048` counts the
span's own length in sectors, and the two disagree exactly when the record
is not aligned to the aligned-unit grid the forensic interleave is defined
on (or when it straddles a clip extent boundary).

A structurally valid forensic segment cannot hit this: the interleave is
per 6144-byte aligned unit, so a real record starts and ends on a
32-packet boundary and the two counts agree. `start_spn = 10` does not —
clip byte 1920 is mid-sector — so the span is refused.

## `multi_cps_cache_hit_still_feeds_the_next_extents_inheritance`

The multi-CPS loop's inheritance chain has to run THROUGH a cache hit. An
extent served from the memo never re-samples, so its index reaches the next
extent only because the hit arm carries it into `last_idx`; without that, a
following extent with no sampleable ciphertext inherits whatever the loop
started at (slot 0) instead of its neighbour's key.

That is silent: an unsampleable extent produces no error either way, so the
map simply keys those LBAs to the wrong CPS unit and the mux decrypts them
to garbage with `lost_bytes == 0`. The existing shared-extent test resolves
a SINGLE-extent title through the cache, so nothing downstream of the hit
is observed; here the clear extent is deliberately placed AFTER the hit.

## `fmts_multi_cps_gap_fill_carries_the_preceding_extents_cps_unit_to_a_clear_tail`

The FMTS gap fill on a MULTI-CPS disc runs its own extent loop, with its own
inheritance chain (`base_slot_for_extent`'s `last_idx`). A title whose last
extent has no sampleable ciphertext — a clear/nav tail, which is exactly the
case that cannot fail loudly — must take the CPS unit its neighbour is in,
not `base_slots[0]`.

Slot 0 here is CPS unit 1's key and the neighbour is CPS unit 2, so losing
the carry keys the tail with the wrong unit's key and decrypts it to
garbage with no error at all.

## `fmts_multi_cps_gap_fill_samples_each_extent_once_per_disc`

The FMTS gap fill samples extents off the LIVE DRIVE through the same
per-disc `CpsUnitCache` the multi-CPS path uses — 8 random 6144-byte reads
per extent, ~200 ms of seek apiece. Every input to that decision is in the
cache key, so a second title over the same extents must cost ZERO further
content reads.

The index-key memo alone does not deliver that: it short-circuits the
anchor and phase probes but the gap-fill loop still runs, and on a
multi-CPS disc it re-samples every extent unless `base_slot_for_extent`
banked its verdict.

## `fmts_stop_during_the_udf_walk_touches_no_content_sector`

Stop lands while the UDF walk is still running — before the anchor loop.
The anchor loop's own poll must catch it, so the drive is never asked for a
single CONTENT sector. Without that poll the entry poll has already passed
and the next one is inside the phase loop, so the full anchor batch (two
`MIN_SAMPLE_UNITS` phase reads plus a key-service round trip) is issued to
a drive the operator has already stopped.

## `fmts_stop_during_the_anchor_batch_stops_before_the_phase_probes`

Stop lands with the drive already working, during the anchor batch. The
PHASE loop's poll must catch it before probing index 1's parity —
otherwise every index in the set is probed (`MAX_ANCHOR_ATTEMPTS` segments
× `MIN_SAMPLE_UNITS` × 2 parities each) after the operator said stop.