v0.13.11: revert SgIoTransport timeout path — keep transport alive

v0.13.10's 'fd=-1 on first poll timeout' was too aggressive: a single
transient killed the entire transport, Pass 1 finished in 45ms with
0 GB good on Dune 2.

Revert to spawn-close + main-thread-reopen (the v0.13.5/8 pattern).
Per-timeout cost is up to ~60s while the kernel completes the
abandoned command, but the v0.13.9 Disc::copy stall guard caps
catastrophic stalls at 120s of bytes_good non-advance. Pass 1 bails
cleanly with NonTrimmed ranges; Pass 2 has a working Drive for
retries with recovery=true + 30s timeouts.

.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
     steps:
       - uses: actions/checkout@v5
       - uses: dtolnay/rust-toolchain@1.86.0
-      - run: cargo test
+      - run: cargo test --tests
 
   check-macos:
     runs-on: macos-latest

CHANGELOG.md

@@ -1,5 +1,716 @@
 # Changelog
 
+## 0.13.11 (2026-04-25)
+
+### Fix: revert SgIoTransport timeout path to keep transport alive
+
+v0.13.10 changed `SgIoTransport::execute` to set `fd = -1` on a poll
+timeout (no reopen on the main thread, since that would serialize
+against the spawned close()). The intent was to escape the 60-s
+blocking reopen.
+
+The cost was too high: a single transient poll timeout permanently
+killed the transport. Live test on Dune 2 (post-replug):
+- Pass 1 ran for **45 ms** then returned with 0 GB good and 80 GB
+  pending.
+- The first SCSI READ timed out, fd went to -1, every subsequent
+  read returned `DeviceNotFound` instantly, Disc::copy raced through
+  the entire disc skip-forwarding in milliseconds.
+- Pass 2 inherited the dead Drive and was equally useless.
+
+Revert: spawn close + reopen on main thread (the v0.13.5/8
+behavior). Yes the main-thread open() may block up to ~60 s while
+the kernel completes the abandoned command — but the v0.13.9
+`Disc::copy` stall guard already caps catastrophic stalls at 120 s
+of `bytes_good` non-advance. Net: per-timeout cost is ~60 s, but
+Pass 1 cleanly bails out within 120 s of any wedge, and Pass 2 has
+a working Drive to retry NonTrimmed ranges with `recovery=true` +
+30 s timeouts.
+
+The integration test for the stall guard
+(`test_disc_copy_stall_detection_triggers_skip_forward`) continues
+to pass — the guard fires regardless of which transport-recovery
+strategy is in play.
+
+## 0.13.10 (2026-04-25)
+
+### Version sync — no functional changes
+
+Sync bump for the autorip-side fix in 0.13.10 (Pass 1 batch reporting).
+
+## 0.13.9 (2026-04-25)
+
+### Fix: Disc::copy silent stall + SgIoTransport reopen-after-timeout serialization
+
+Two correlated fixes for a hang observed live on the LG BU40N during a
+v0.13.8 rip of Dune: Part Two. At ~30 % progress through Pass 1
+(disc → ISO), `bytes_good` froze for 10+ minutes with `errs=0`,
+no error surfaced, drive not wedged.
+
+Root cause: `SgIoTransport::execute` (linux.rs) attempted to recover from
+a `poll()` timeout by spawning a background `close()` of the old fd and
+opening a fresh `/dev/sg*` fd on the main thread. On Linux, opening the
+SAME device while a prior fd is mid-close serializes via the kernel's
+per-device state lock — so the fresh `open()` blocks for as long as the
+close does (until the kernel completes the in-flight CDB). This undid
+the userspace 1.5 s timeout: each timed-out read added 60+ s to the
+next iteration. From `Disc::copy`'s perspective, reads kept returning
+Err slowly, the skip-forward path advanced `pos` but never `bytes_good`.
+
+Fixes:
+- `SgIoTransport::execute` no longer reopens on timeout. Spawns the
+  close, sets `self.fd = -1`, returns Err immediately. Subsequent
+  calls fail with `DeviceNotFound` (already gated at line 248).
+  Caller (Drive) is invalidated until reopened. Pass 2's
+  `Disc::patch` would need a fresh Drive; that's a v0.14 follow-up.
+- `Disc::copy` adds a stall guard. New `CopyOptions::stall_secs:
+  Option<u64>` (default 120 s). If `bytes_good` doesn't advance for
+  the threshold, breaks the outer loop with `complete: false,
+  bytes_pending > 0` so the caller's retry path picks up.
+
+Tests: new `test_disc_copy_stall_detection_triggers_skip_forward` in
+`tests/integration_progress_and_halt.rs` proves the guard fires within
+the configured threshold.
+
+Other:
+- Cosmetic: warning text "rip thread did not drain within 35s" updated
+  to 60s (matches the v0.13.8 timeout bump).
+
+## 0.13.8 (2026-04-25)
+
+### Version sync — no functional changes
+
+Sync bump for the ecosystem. 0.13.8 carries autorip-side fixes:
+post-stop "error" leak (halt-aware Err handling in Pass 1/2+),
+60 s drain timeout, and a structural spawn_rip_thread helper.
+
+## 0.13.7 (2026-04-25)
+
+### Version sync — no functional changes
+
+Sync bump for the ecosystem. All four freemkv crates (libfreemkv,
+freemkv CLI, bdemu, autorip) always share a version number; 0.13.7
+carries an autorip-side fix (HTTP-spawned rip/scan threads now
+register for stop-drain).
+
+## 0.13.6 (2026-04-25)
+
+### Inline retry/reset stripped from `Drive::read`; `BytesRead` now emitted
+
+Two related changes that close the loop on the BU40N wedge work from
+0.13.1–0.13.4 and on the long-standing autorip "0 KB/s, 0%" UI bug.
+
+**`Drive::read` is now single-shot.** The phase 1 / 2 / 3 retry loop
+(reset → reopen → repeat) inside `Drive::read` is gone (~80 lines
+deleted). `recovery=true` only bumps the per-CDB timeout to 30 s;
+`recovery=false` keeps the 1.5 s timeout. On a failed read the
+function returns `Err(DiscRead)` immediately. Per the BU40N
+post-mortem, every USB / SCSI reset path tested in 0.13.1–0.13.3
+resets the bridge but not the drive firmware, and the inline
+reset+reopen *was* the wedge primitive itself — issuing it from
+inside `Drive::read` produced multi-minute hangs and made the wedge
+class harder to surface to the user. The correct retry layer is
+`Disc::patch`'s outer multi-pass loop, which is unaffected. A stuck
+drive now surfaces as a clean `DiscRead` to the caller, who can
+prompt physical replug.
+
+**SCSI reset surface trimmed.** `SgIoTransport::reset` (Linux) drops
+the `SG_SCSI_RESET` ioctl and the STOP / START UNIT escalation; it
+keeps the kernel `SG_IO` state flush plus `ALLOW MEDIUM REMOVAL`.
+`MacScsiTransport::reset` is removed entirely (was open + drop +
+sleep, no SCSI). The top-level `scsi::reset` /
+`scsi::reset_with_timeout` / `scsi::reset_blocking` family is
+removed — no callers remain after the `Drive::read` strip.
+
+**`EventKind::BytesRead` now emitted.** The variant was declared in
+0.13.0 but never fired. `DiscStream::fill_extents` now emits
+`BytesRead { bytes_read_total, total_extents_bytes }` after every
+successful sector read, so consumers in direct (no-mapfile) mode can
+drive a real-time progress bar without polling `output.bytes_written`.
+Multi-pass mode continues to use `Disc::copy`'s `on_progress`
+callback unchanged. Drives the autorip per-device live progress UI.
+
+`Drive::checked_sleep` is removed (only used by the recovery loop);
+`Drive::sleep_until_halted` is `#[cfg(test)]`-only; `Drive::emit` is
+retained because `BytesRead` uses it.
+
+### Tests
+- New `tests/integration_progress_and_halt.rs` (5 tests): `BytesRead`
+  emission, `Disc::copy` `on_progress` regression guard, halt aborts
+  copy, Drop safety, `FileSectorReader` round-trip.
+- 233 unit tests + 5 integration tests pass.
+
+### Net diff
+~80 lines deleted, ~20 added.
+
+### Version sync
+0.13.6 ecosystem release (libfreemkv + freemkv + bdemu + autorip all
+on 0.13.6).
+
+## 0.13.5 (2026-04-25)
+
+### Version sync — no functional changes
+Sync bump for the ecosystem. All four freemkv crates (libfreemkv,
+freemkv CLI, bdemu, autorip) always share a version number; 0.13.5
+carries autorip-side fixes (stop-is-reset, startup staging sweep).
+
+## 0.13.4 (2026-04-25)
+
+### Wedge recovery rolled back + sysfs identity fallback
+
+**What changed.** The in-library USB / SCSI wedge-recovery escalation
+added in 0.13.1 – 0.13.3 has been removed. `drive_has_disc` now returns
+the raw TUR result (or the `0xFF` poll-timeout wedge error) directly to
+the caller. `scsi::usb_reset()` / `usb_reset_with_timeout()` /
+`DEFAULT_USB_RESET_TIMEOUT_SECS` and the per-platform
+`SgIoTransport::usb_reset` / `MacScsiTransport::usb_reset` /
+`SptiTransport::usb_reset` are gone. All three platform backends pass
+transport errors through verbatim, keeping the public
+`list_drives` + `drive_has_disc` contract symmetric
+(Linux / macOS / Windows).
+
+**Why.** Production testing against the LG BU40N USB BD-RE (the drive
+that drove the whole 0.13.1–0.13.3 recovery push) showed:
+- `SG_SCSI_RESET`, `STOP UNIT` + `START UNIT`, and `USBDEVFS_RESET`
+  all succeed at the USB transport layer (kernel logs
+  `usb 3-2: reset high-speed USB device`, device re-authorises).
+- But the drive firmware *below* the USB bridge stays locked: no
+  LUN enumerates on the fresh `scsi_host`, TUR never succeeds,
+  `/dev/sg*` never reappears.
+- Also tried (outside the lib): `/sys/bus/usb/devices/<port>/authorized`
+  toggle, `usb-storage` driver unbind/rebind, forced SCSI host rescan.
+  All same outcome.
+
+Only physical unplug-replug (or host reboot) clears this wedge class.
+The library was logging 2-minute-per-tick escalation cycles for nothing,
+and consumers had no way to surface "drive needs physical intervention"
+to users because the escalation was masking the real failure. Upper
+layers (autorip, CLI) now see the wedge error directly and prompt the
+user.
+
+A breadcrumb in `scsi/linux.rs::drive_has_disc` catalogues every
+recovery method tried and points to git tag `v0.13.3` for the full
+implementation, in case a future hardware class is found where
+USB-layer recovery actually works.
+
+**New: sysfs-cached identity fallback (Linux).** `list_drives` now
+populates empty INQUIRY vendor/model/firmware fields from
+`/sys/class/scsi_generic/sgN/device/{vendor,model,rev}` — the kernel
+runs its own INQUIRY at device probe time and stashes the answer there,
+so even a mid-wedge INQUIRY still yields the UI a human-readable
+identity. The drive surface on screen doesn't suddenly go blank the
+moment the drive firmware locks up.
+
+## 0.13.3 (2026-04-24)
+
+### Bug fix — `drive_has_disc` wedge recovery was dead code for TUR errors
+
+The wedge-signature predicate introduced in 0.13.2 gated on
+`opcode == SCSI_INQUIRY (0x12)` — a holdover from when enumerate-time
+INQUIRY was the only path wedges surfaced on. `drive_has_disc` issues
+`TEST UNIT READY (0x00)`, so its wedge errors (`E4000: 0x00/0xff/0x00`)
+never matched the predicate and the SCSI-reset + USB-reset escalation
+never fired. Production result: the BU40N USB BD-RE stayed wedged
+indefinitely, with autorip logging `recovery exhausted` on the raw
+pass-through error while no recovery had actually been attempted.
+
+Fix: drop the opcode constraint. Status byte `0xFF` is synthesised by
+our own `execute()` path when `poll()` on the SG fd times out; it's
+the ground-truth wedge marker regardless of which opcode was in flight.
+Doc comments on `is_wedge_signature` and `WEDGE_STATUS_BYTE` updated
+accordingly. Linux-only — macOS / Windows use sense-key-based wedge
+detection and are unaffected.
+
+## 0.13.2 (2026-04-24)
+
+### Public discovery + presence APIs; SCSI/USB primitives no longer
+### exposed to consumer crates
+
+The autorip / freemkv-CLI side of the ecosystem was reimplementing
+hardware discovery (sysfs walking, SCSI type-5 filtering, sg-path
+construction) and SCSI recovery primitives in their own crates — a
+direct violation of the architectural rule that ALL hardware-aware
+code lives in libfreemkv. 0.13.2 closes that gap with two cheap public
+probes that absorb everything consumers were doing themselves, plus
+visibility tightening to make future violations a compile error.
+
+#### New public APIs
+
+- `pub struct DriveInfo { path, vendor, model, firmware }` — a single
+  enumerated optical drive's identity. Returned by `list_drives()`,
+  populated from a single SCSI INQUIRY at enumeration time. No
+  firmware reset, no `init`.
+- `pub fn list_drives() -> Vec<DriveInfo>` — one-shot enumeration
+  across Linux/macOS/Windows. Linux walks `/sys/class/scsi_generic/`
+  with the SCSI type-5 filter and `/dev/sg0..15` fallback; macOS
+  walks `/dev/disk0..15` with the INQUIRY peripheral-type-5 filter;
+  Windows iterates `CdRom0..15`. Cheap (~10 ms / drive); cache the
+  result and refresh on udev events.
+- `pub fn drive_has_disc(path: &Path) -> Result<bool>` — single TEST
+  UNIT READY. Returns `Ok(true)` when ready / `Ok(false)` on sense-key 2
+  ("medium not present") / `Err` only after recovery has been exhausted.
+  **Internal wedge recovery is hidden from callers** — when the kernel
+  returns the wedge-signature pattern (status 0xFF, no sense), this
+  function transparently escalates: SCSI bus reset → if still wedged →
+  USB device reset → retry TUR. Consumers never see the escalation.
+
+#### USB-layer reset, multi-platform
+
+`USBDEVFS_RESET` (Linux) is the only thing that recovers a kernel-
+level USB Mass Storage wedge — software equivalent of unplug-replug.
+Now wired for all three OSes:
+
+- **Linux**: `USBDEVFS_RESET` ioctl on `/dev/bus/usb/BBB/DDD`. Resolves
+  sg → USB device via sysfs walk (`busnum`/`devnum` parents).
+- **macOS**: `IOUSBDeviceInterface::ResetDevice()`. Walks IORegistry
+  parents from the SCSI service to the USB device, queries the IOKit
+  USB plugin, calls ResetDevice.
+- **Windows**: existing `IOCTL_STORAGE_RESET_DEVICE` covers both SCSI
+  and USB layers via storport, so `usb_reset` returns `DeviceNotFound`
+  by design — the recovery escalation in `drive_has_disc` falls
+  through cleanly. (See the `windows::usb_reset` doc comment for
+  why a separate cycle-port IOCTL isn't needed on Windows.)
+
+All wrapped in a thread + `mpsc::recv_timeout` so a kernel ioctl that
+hangs forever can't lock up the caller (the inner thread leaks one OS
+thread per hard wedge — acceptable for a daemon that recovers vs. one
+that wedges the whole poll loop).
+
+#### Visibility tightening (architectural enforcement)
+
+These were `pub` in 0.13.1; consumer crates could (and did) call them
+directly, leaking SCSI knowledge across the lib boundary:
+
+- `scsi::reset` → `pub(crate)`
+- `scsi::reset_with_timeout` → `pub(crate)`
+- `scsi::usb_reset` → `pub(crate)`
+- `scsi::usb_reset_with_timeout` → `pub(crate)`
+- `DEFAULT_RESET_TIMEOUT_SECS` / `DEFAULT_USB_RESET_TIMEOUT_SECS` →
+  `pub(crate)`
+
+Consumers now reach recovery exclusively through `drive_has_disc`,
+which folds the escalation in. **Compile-time guarantee** that no
+future autorip/CLI/bdemu commit can reintroduce direct SCSI access.
+
+#### Why this design
+
+`Drive::open(path)` runs a ~2 s firmware-reset preamble + identify
+sequence; suitable for ripping but wasteful for a poll loop probing
+"is there a disc?". Pre-0.13.2 autorip called `Drive::open` 4 × every
+5 s = ~17 000 speculative SCSI sessions/day, hammering the drives
+between actual rips. The wedge in production at 23:51 UTC was
+triggered by exactly this hot-loop pattern. With `drive_has_disc`,
+the same poll cadence costs ~50 ms / drive (one TUR) — 40× cheaper
+and side-effect-free on a healthy drive.
+
+#### Tests
+
+- 233 lib tests pass (no change in count; APIs covered indirectly via
+  the existing transport tests + a new `device_key` test on the
+  autorip side).
+- `cargo clippy --all-targets -D warnings` clean across Linux/macOS.
+
+## 0.13.1 (2026-04-24)
+
+### `scsi::reset()` now has a hard wallclock timeout
+
+Production incident on a wedged BU40N USB drive: autorip's poll loop
+called `scsi::reset()` and the call hung for 60+ seconds before the
+operator manually intervened. Root cause: the Linux `SG_SCSI_RESET`
+ioctl can block indefinitely when the kernel SCSI subsystem is waiting
+on a bus-wedged device that will never ack — there's no kernel-side
+timeout on this ioctl. Without an outer wallclock bound the caller's
+thread is stuck in the kernel until the device unwedges (which, for a
+permanently-dead USB target, may be never).
+
+`scsi::reset()` is now a wrapper that runs the platform-specific reset
+on a detached worker thread and bounds the caller's wait via
+`mpsc::recv_timeout(DEFAULT_RESET_TIMEOUT_SECS)` (30 s). Returns
+`DeviceResetFailed` on timeout. The worker thread keeps running until
+the kernel eventually unblocks (we can't cancel a Linux ioctl from
+userspace) — this leaks one OS thread per hard wedge, an acceptable
+cost for a daemon that recovers vs. one that hangs.
+
+- New `pub const DEFAULT_RESET_TIMEOUT_SECS: u64 = 30;`
+- New `pub fn reset_with_timeout(device, Duration) -> Result<()>` for
+  callers that want a different bound.
+- Existing `pub fn reset(device) -> Result<()>` keeps the same
+  signature; behaviour change is the timeout, not the API.
+
+### Follow-up flagged
+
+`SG_SCSI_RESET` only resets at the SCSI layer. For USB-attached drives
+(the BU40N case), the wedge is often in the USB Mass Storage layer
+*below* SCSI — `SG_SCSI_RESET` doesn't help. The proper escalation is
+`USBDEVFS_RESET` (the `usbreset.c` ioctl), which re-enumerates the
+device at the USB layer. Tracked for 0.13.2: a `scsi::usb_reset(path)`
+that resolves sg → USB device and issues `USBDEVFS_RESET`. That would
+have recovered tonight's BU40N without operator intervention.
+
+## 0.13.0 (2026-04-24)
+
+### Zero English in library — typed variants for every error path
+
+Audit pass against the `project docs` rule (no English text in library code).
+Found nine call sites that violated the contract by stuffing English into
+`io::Error::new(kind, "…")` or by abusing `Error::DeviceNotFound { path }`
+as a free-form description field. Each is now a typed variant with
+structured fields; the CLI / autorip translates to localized text.
+
+New `Error` variants and codes:
+
+- `ScsiInterfaceUnavailable { path }` — `E1004` (macOS
+  `SCSITaskDeviceInterface` couldn't be obtained)
+- `DeviceLocked { path, kr }` — `E1005` (replaces an English
+  "exclusive access denied. Try: diskutil unmountDisk" message)
+- `IoKitPluginFailed { path, kr }` — `E1006`
+- `UnsupportedPlatform { target }` — `E2003` (built on an OS without an
+  SCSI backend)
+- `PlatformNotImplemented { platform }` — `E2004` (replaces the
+  `product_revision: "Renesas not yet implemented"` string-stuffing in
+  `drive::mod`)
+- `MapfileInvalid { kind }` — `E6011` (ddrescue mapfile parse, with a
+  stable `&'static str` kind: `"status_char"` or `"hex"`)
+- `DiscUrlNotDirect` — `E9009` (replaces the full English sentence
+  `"Use Drive::open() + Disc::scan() + DiscStream::new() for disc sources"`
+  that `mux::input(disc://…)` returned to callers)
+
+Migrated call sites:
+
+- `mux/resolve.rs` — disc URL → `DiscUrlNotDirect`; the four
+  `format!("m2ts://…")` / `format!("mkv://…")` IO error wraps now
+  propagate the inner `io::Error` unchanged (the URL-prefix wrap added
+  no semantic information).
+- `mux/iso.rs` — same `format!("iso://…")` wrap dropped.
+- `sector.rs` — image-too-large now uses the existing `IsoTooLarge`
+  variant instead of `format!("…image too large, max ~8 TB")`.
+- `disc/mapfile.rs` — bad-status-char and bad-hex parser errors now use
+  `MapfileInvalid { kind }`.
+- `scsi/mod.rs` — unsupported-platform path uses `UnsupportedPlatform`.
+- `scsi/macos.rs` — IOKit plugin failure → `IoKitPluginFailed`,
+  `SCSITaskDeviceInterface` missing → `ScsiInterfaceUnavailable`,
+  exclusive-access denied → `DeviceLocked` with the IOReturn code as a
+  structured `kr` field. The `find_scsi_service` four-stage failure path
+  is now a single `DeviceNotFound { path }` (none of the prior
+  per-stage English descriptions were user-actionable individually).
+- `drive/mod.rs` — Renesas platform → `PlatformNotImplemented`.
+
+### Stripped English from `labels` module
+
+`labels::apply()` previously pushed `"Commentary"`, `"Descriptive Audio"`,
+`"Score"`, `"IME"`, and `" (Secondary)"` directly into
+`AudioStream.label`. Those English strings then leaked into MKV titles
+and into autorip's UI. The data was already structured upstream
+(`LabelPurpose` enum on `StreamLabel`); the lib was downcasting it for
+the caller's convenience.
+
+- `AudioStream` gains `purpose: LabelPurpose` (re-exported from
+  `crate::disc` next to the struct, alongside `LabelQualifier`).
+- `SubtitleStream` gains `qualifier: LabelQualifier`.
+- `apply()` writes structured fields, never English. `label` keeps
+  codec-formatting only (`"Dolby TrueHD 5.1"`).
+- `generate_audio_label` drops the `" (Secondary)"` suffix; `secondary`
+  is already a `bool` field, callers render it.
+- `generate_video_label` drops the `"Secondary Video"` fallback.
+  `"Dolby Vision EL"` kept (brand identifier, not translatable).
+
+### API hygiene
+
+- **mux module visibility tightened**. `pub mod ebml`, `m2ts`, `mkv`,
+  `network`, `null`, `ps`, `stdio`, `ts`, `tsmux` are now `pub(crate)`.
+  Their *types* are still re-exported from `lib.rs` — the modules
+  themselves were leaking low-level EBML primitives, TS muxer
+  internals, and network/stdio implementations that no external caller
+  used. `mux::codec`, `mux::disc`, `mux::iso`, `mux::resolve`, and
+  `mux::meta` stay public (genuine APIs).
+- **Stream trait rustdoc**. The keystone PES `Stream` trait (in
+  `pes.rs`) had per-method docs but no trait-level doc. Now explains
+  read-vs-write split, error contracts, the role of `info()` /
+  `codec_private()` / `headers_ready()`.
+- **lib.rs re-export sections**. Eight grouped sections with a
+  paragraph each (Drive lifecycle, Errors, Decryption, Disc structure,
+  Streams, Lower-level surfaces) so `cargo doc` tells callers when to
+  reach for what.
+- **Dropped `ScanOptions::with_keydb()`**. The `_with_X` constructor
+  pattern was banned by `project docs` (one method per action). Use the
+  struct literal: `ScanOptions { keydb_path: Some(p.into()) }`. Five
+  external call sites (autorip ×3, freemkv CLI ×3) and three test
+  fixtures migrated.
+- **`pid_index` allocation documented**. The `TsDemuxer::new` flat
+  lookup table was flagged by audit as "unbounded for adversarial
+  PIDs"; on closer reading it's bounded by `u16::MAX × 2 bytes ≈ 128 KB`.
+  Doc comment now states the bound explicitly so future contributors
+  don't re-flag it.
+
+### Dead-code sweep
+
+Pre-PES-rewrite leftovers that were `pub` but unreachable:
+
+- Deleted `mux/lookahead.rs` entirely (orphan file — never had a `mod`
+  declaration; only used by its own tests).
+- Deleted `mux/tsreader.rs` (`TsDemuxReader` struct + four methods,
+  used nowhere).
+- Deleted `mux::ebml::write_int`, `read_vint`, `SEEK_HEAD`, `SEEK`,
+  `SEEK_ID`, `SEEK_POSITION` (unused).
+- Deleted `mux::ts::scan_first_pts`, `scan_last_pts`, `scan_duration`,
+  `SCAN_HEAD_SIZE`, `SCAN_TAIL_SIZE`, `take_remainder`, `set_remainder`
+  (unused since the v0.10 PES rewrite).
+- Deleted `MkvMuxer::codec_private_slots` /
+  `codec_private_filled` fields and `fill_codec_private` method —
+  deferred-codecPrivate path was never exercised once codec_privates
+  flowed through `DiscTitle`.
+
+`cargo clippy --all-targets -- -D warnings` is clean.
+
+### Tests
+
+- New `error::tests` module — code distinctness, Display has no English
+  words, `io::ErrorKind` mapping for every new variant.
+- 233 lib tests (was 230), all green.
+
+### Breaking changes
+
+Source-compatible for callers who use `Error` opaquely (handle
+`Result<T, Error>` and `error.code()` only). The following are breaking:
+
+- `ScanOptions::with_keydb()` removed — use struct literal.
+- `mux::ebml`, `mux::mkv`, `mux::ts`, etc. modules no longer accessible
+  externally — use the re-exported types from the crate root instead.
+- `AudioStream` and `SubtitleStream` gained required fields (`purpose`,
+  `qualifier`). Construction-by-struct-literal must include them.
+- `Error::UnsupportedDrive { product_revision: "Renesas not yet
+  implemented" }` no longer produced — match `PlatformNotImplemented`.
+
+### Magic-number policy
+
+Per the v0.13 audit directive: new code in this release uses named
+documented constants (e.g. `POLL_INTERVAL_SECS` in autorip, the wedge
+signature literals in `ripper.rs`, the `BD_TS_PID_SPACE` floor in
+`ts.rs`'s table allocation). A comprehensive retrofit of pre-existing
+magic numbers across the older codebase is queued as follow-up work for
+0.13.1+ — too large to absorb into this release without scope creep.
+
+## 0.12.0 (2026-04-24)
+
+### Rust 2024 edition migration
+- Bumped `edition = "2024"`. Required code changes:
+  - FFI declarations in `src/scsi/macos.rs` wrapped in `unsafe extern "C" { … }` per the 2024 FFI safety rules.
+  - `unsafe_op_in_unsafe_fn` lint: `vtable_fn()` body now has an explicit `unsafe { … }` block rather than relying on implicit unsafe of the containing `unsafe fn`.
+  - Match-ergonomics: removed redundant `ref`/`ref mut` bindings in `mux/meta.rs`, `mux/mkvstream.rs`, `mux/network.rs`, `mux/stdio.rs` — 2024 tightens "cannot explicitly borrow within an implicitly-borrowing pattern."
+- No behavior change. MSRV stays at 1.86.
+
+### Minor / version sync
+- Part of the 0.12.0 ecosystem release. The autorip-side fixes (progress regressions, UI redesign, regression-guard tests) drove the minor bump.
+
+## 0.11.22 (2026-04-24)
+
+### Version sync — no functional changes
+Part of the 0.11.22 ecosystem release. autorip 0.11.22 ships full multi-pass UI (bad-range viz, live mapfile stats, Recovery settings); the library API is unchanged from 0.11.21.
+
+## 0.11.21 (2026-04-24)
+
+### Multi-pass rip architecture — disc → ISO → patch → ISO
+
+New primitives for two-stage rip: fast forward pass with zero-fill on failures, then targeted retries of bad ranges. Keeps the library API stream-based; the multi-pass model lives entirely in caller-orchestrated function composition.
+
+- **New `Disc::copy(reader, path, &CopyOptions)`** replaces the positional-arg version. Always produces a ddrescue-format mapfile at `path + ".mapfile"` as a side-effect. With `skip_on_error=true` + `skip_forward=true`, does ddrescue-style fast sweep: 64 KB block reads, exponential skip-forward (256 KB → cap at 1% of disc) on failure, zero-fill bad blocks, record ranges in the mapfile. With defaults (both false), matches pre-0.11.21 behavior — uses drive-level recovery, aborts on bad sector. Mapfile is produced either way.
+- **New `Disc::patch(reader, path, &PatchOptions)`** — idempotent retry pass. Reads the mapfile, re-reads every non-`+` range with full drive recovery enabled, writes successful bytes back into the ISO at exact offsets, updates mapfile. Call N times for N retry attempts.
+- **New `disc::mapfile` module** — ddrescue-compatible plain-text format. Crash-safe (flushes on every `record()`), greppable, human-editable, tool-interoperable. Status chars match ddrescue: `?` non-tried · `*` non-trimmed · `/` non-scraped · `-` unreadable · `+` finished.
+- **Re-exports:** `FileSectorReader` from the crate root for ISO readers.
+
+### Breaking changes
+- `Disc::copy`'s signature changes from positional args (`decrypt, resume, batch, on_progress`) to `CopyOptions`. Previous callers must migrate. `freemkv` CLI updated in lockstep.
+
+### Version sync
+- Part of the 0.11.21 ecosystem release (libfreemkv + freemkv + bdemu + autorip all on 0.11.21).
+
+## 0.11.18 (2026-04-24)
+
+### DiscStream halt flag — Stop works during dense bad-sector regions
+
+`DiscStream::fill_extents` loops internally when the demuxer hasn't accumulated enough data to emit a PES frame — during a dense bad-sector run, that loop can spend many minutes shrinking batch sizes and zero-filling sectors without ever returning to the outer read() call. Without an internal halt check, the caller's Stop request goes unserviced until the demuxer eventually emits a frame, which may be very far away.
+
+- **`DiscStream::set_halt(Arc<AtomicBool>)`** — share a halt flag with the stream. Typically wired to `Drive::halt_flag()` so Stop propagates across both the drive's recovery phases and the stream's sector processing.
+- **`fill_extents()` checks the halt flag** at the top of every retry iteration (before each attempt at every size level). Raising the flag aborts within one read round-trip — at most the current SCSI command's timeout.
+- Returns `Err(Error::Halted)` (E6010) so the outer rip pipeline terminates cleanly.
+
+No behavior change for callers that don't call `set_halt`. Unblocks the architectural fix for the "Stop doesn't stop" bug observed on a damaged UHD disc where the stream was stuck in a 12+ hour bad-sector grind.
+
+## 0.11.17 (2026-04-23)
+
+### Adaptive batch sizer in DiscStream — no more per-sector descent
+
+Rip recovery rewritten. The old binary-search-per-bad-sector model paid the full descent (batch → half → quarter → … → single) for every bad sector in a region. On a damaged disc with 600 consecutive bad sectors this took 12+ hours. The new algorithm pays the descent once, remembers the working size, and ramps back up only after a sustained clean streak.
+
+- **`BatchSizeChanged { new_size, reason }` event** — fires on shrink (read failed) and probe-up (clean streak threshold hit). Consumers use this to distinguish a "recovering" rip from a normal one.
+- **Removed `BinarySearch` and `SectorRecovered` emissions from DiscStream** — no longer produced by the rip path. `SectorRecovered` still fires from `Drive::read`'s multi-phase recovery (unused by rips today, but kept for scan/other callers).
+- **Removed `read_with_binary_search` and the 3×5s light-recovery loop** — no retry loops, no sleeps. One 5s attempt per read. On size-1 failure, skip (zero-fill) or error.
+- **Probe-up threshold: 100 MiB (51,200 sectors) of clean reading at current size** before doubling toward preferred. Ramp 1 → preferred on good reading takes ~100 seconds for a typical BD — trivial vs. rip duration, conservative enough that a single lucky sector in a marginal zone can't trigger a premature probe.
+- **Bad-region math**: ~600 consecutive bad sectors now complete in ~50 min (600 × 5s) instead of ~12h. The descent is O(log preferred) one time, not per sector.
+
+### macOS
+
+- Fix new clippy lint (`manual_c_str_literals`) in `scsi/macos.rs`.
+
+## 0.11.16 (2026-04-21)
+
+### API cleanup — one method per action
+- **SectorReader::read_sectors(lba, count, buf, recovery)** — single method with `recovery: bool`. Removes `read_sectors_recover()`.
+- **parser_for_codec(codec, codec_data)** — single constructor. Removes `parser_for_codec_with_data()`.
+- **DvdSubParser::new(codec_data)** — single constructor. Removes `with_codec_data()`.
+- **MkvMuxer::new(writer, tracks, title, duration, chapters)** — single constructor. Removes `new_with_chapters()`.
+
+## 0.11.15 (2026-04-21)
+
+### Lint cleanup
+- Fix all `cargo fmt` and `cargo clippy -D warnings` across codebase.
+- Remove unused imports, dead code, collapsible if-statements, div_ceil reimplementation.
+
+## 0.11.14 (2026-04-21)
+
+### Audit fixes: read recovery, verify, SCSI
+- **Fix: trailing sectors at extent boundaries** — extents with sector_count not divisible by 3 no longer drop 1-2 trailing sectors. decrypt_sectors() safely skips partial AACS units.
+- **Fix: verify_title stop support** — progress callback now returns bool. Return false to stop verification early instead of running to completion.
+- **Fix: O_CLOEXEC on all SCSI fd opens** — prevents fd leak to child processes.
+- **Fix: SCSI sense descriptor format** — correctly detect response code 0x72/0x73 (descriptor format) and extract sense key from byte 1 instead of byte 2.
+- **Fix: DecryptFailed on missing unit key** — decrypt_sectors() returns Err(DecryptFailed) instead of silently using a zero key.
+
+## 0.11.13 (2026-04-21)
+
+### Fix: all rip reads use fast timeout
+- Initial batch read changed from full Drive::read() recovery to fast 5s timeout. Binary search starts immediately on failure instead of after 10 minutes of retries.
+- Max 15 seconds per bad sector (3 x 5s attempts). Max 23 seconds per batch with 1 bad sector.
+
+## 0.11.12 (2026-04-21)
+
+### Drive halt + sector events + light recovery
+- **Drive.halt()** — AtomicBool flag checked between retry phases. Max 30s to stop.
+- **Drive.on_event()** — callback for ReadError, Retry, SpeedChange, SectorRecovered events.
+- **Error::Halted (E6010)** — distinct from DiscRead, indicates intentional stop.
+- **Binary search light recovery** — single sectors get 3 attempts x 5s (15s max) instead of full 10-min Drive::read() recovery. Marginal disc zones complete in minutes not hours.
+- **DiscStream.on_event()** — BinarySearch, SectorRecovered, SectorSkipped events.
+
+## 0.11.11 (2026-04-20)
+
+### Binary search error recovery
+- **fill_extents binary search** — when a batch read fails, binary search to isolate the failing sector(s). Good sectors read in sub-batches at full speed. Only truly bad sectors get individual recovery. 60-sector batch with 1 bad sector: ~5 seconds instead of 10+ minutes.
+
+## 0.11.10 (2026-04-20)
+
+### Skip errors + clean verify API
+- **DiscStream.skip_errors** — when true, zero-fills unreadable sectors and continues instead of aborting. Caller sets based on user preference.
+- **read_sectors_recover(recovery: bool)** — single API for recovery vs fast reads. Replaces separate read_sectors_fast method.
+
+## 0.11.9 (2026-04-20)
+
+### Fast verify reads
+- **read_sectors_fast()** — single-attempt 5s timeout SCSI read for verify. No recovery loop. Bad sectors detected in seconds instead of 10+ minutes.
+- **SectorReader trait** — added read_sectors_fast() with default fallback to read_sectors().
+
+## 0.11.8 (2026-04-20)
+
+### Disc verify
+- **verify::verify_title()** — sector-by-sector health check. Classifies sectors as Good/Slow/Recovered/Bad. Progress callback, chapter mapping, sector ranges.
+
+## 0.11.7 (2026-04-19)
+
+### TrueHD parser rewrite
+- **12-bit length mask** — access unit length is lower 12 bits of first 2 bytes, not full 16. Upper 4 bits are parity nibble. Wrong mask caused misaligned frame splits.
+- **AC-3 frame skipping** — BD-TS TrueHD PES contains interleaved AC-3 frames (same PID). Parser now detects AC-3 sync word (0x0B77) and skips those frames.
+- **Cross-PES buffering** — access units that span PES packet boundaries are correctly reassembled.
+- **Per-unit timestamps** — each access unit gets incrementing PTS (1/1200th second apart) instead of all units in one PES sharing the same timestamp.
+- **Major sync detection** — keyframe flag set when access unit contains MLP major sync (0xF8726FBA).
+- Result: zero TrueHD decode errors on UHD and BD (was ~19 per 30 seconds).
+
+## 0.11.6 (2026-04-18)
+
+### TrueHD fix (incomplete)
+- Initial attempt at TrueHD header stripping — wrong approach, superseded by 0.11.7.
+
+## 0.11.5 (2026-04-18)
+
+### MKV container fixes — Jellyfin/player compatibility
+- **Timestamp normalization** — MKV and M2TS output starts at 0.000s instead of raw disc PTS offset. Fixes playback failures in Jellyfin and other players.
+- **DefaultDuration** — correct frame rate written to MKV track header. Fixes wrong avg_frame_rate (was 293/12, now 24000/1001).
+- **HDR Colour metadata** — MatrixCoefficients, TransferCharacteristics, Primaries, Range written to MKV video track. Enables HDR tone mapping in players.
+- **DisplayWidth/DisplayHeight** — aspect ratio fields in MKV video track.
+- **Chapters (Blu-ray)** — accept mark_type 0 as chapter entry (was filtering to type 1 only, which no disc uses).
+- **Chapters (DVD)** — extract chapter timestamps from PGC program map + cell durations.
+- **Default disposition** — only first video and first audio track marked default. Fixes wrong auto-selection in players.
+
+## 0.11.3 (2026-04-18)
+
+### Unified versioning
+- All freemkv repos now share the same version number. No functional changes from 0.10.10.
+
+## 0.10.10 (2026-04-18)
+
+### Dual-layer disc fix
+- **UDF extent allocation** — use actual UDF allocation descriptors (`file_extents()`) instead of assuming m2ts files are contiguous from `file_start_lba`. Dual-layer UHD discs split large files across many extents (~1 GB each). The old single-extent assumption truncated rips at ~37% on affected discs.
+- **Read error propagation** — `fill_extents()` returns `io::Result<bool>` so SCSI read errors propagate to the caller instead of being silently treated as EOF.
+
+## 0.10.9 (2026-04-17)
+
+### Fast disc identification
+- **Disc::identify()** — reads UDF filesystem only (name, format, layers, encrypted). ~3s on USB vs 18s for full scan. No AACS handshake or playlist parsing.
+- **KEYDB path fix** — added `~/.config/freemkv/keydb.cfg` to search paths. Fixes silent rip hang when KEYDB exists but isn't found by `resolve_keydb()`.
+
+## 0.10.8 (2026-04-17)
+
+### Buffered UDF reads
+- **BufferedSectorReader** — prefetches batch sectors on single-sector reads. USB drives have ~500ms per SCSI command; this eliminates scan hangs.
+- **Metadata partition pre-read** — loads entire UDF metadata partition into memory after initial parse.
+- Scan time reduced from 10+ minutes to ~18 seconds on USB.
+
+## 0.10.7 (2026-04-17)
+
+### DiscStream::new()
+- Replaced open_drive(), open_iso(), from_reader() with single new() constructor
+- Stream accepts ContentFormat and sets up demuxer internally
+- Removed disc:// case from input() — callers use primitives directly
+
+## 0.10.6 (2026-04-16)
+
+### Docker compatibility
+- **Drive discovery** — removed sysfs check that blocked detection inside Docker containers. Device nodes are sufficient; INQUIRY command validates the device is an optical drive.
+
+## 0.10.5 (2026-04-16)
+
+### Audio parser buffering
+- **AC3** — buffer across PES boundaries with frame size from fscod/frmsizecod table. Eliminates all AC3 decode errors on BD and UHD.
+- **DTS** — buffer with core sync detection + frame size from header. DTS-HD extension frames handled correctly.
+- **TrueHD** — buffer with unit length field parsing. Incomplete units held for next PES.
+- All audio parsers now emit complete frames only. When PES boundaries align (normal case), buffering is a no-op.
+
+## 0.10.4 (2026-04-16)
+
+### CSS decryption — full key hierarchy
+- **Bus auth → disc key → title key** — complete CSS key chain. Bus authentication with CSSCryptKey challenge-response, disc key decryption using 31 player keys via READ DVD STRUCTURE, title key extraction via REPORT KEY format 0x04.
+- **CSS descramble cipher** — correct LFSR keystream generation with TAB5 for LFSR1 output and TAB4 for LFSR0 output. Per-sector key derivation from title key XOR sector seed.
+- **Stevenson plaintext attack** — expanded pattern set (padding, video, audio, nav pack headers), scans up to 50K scrambled sectors for ISO key recovery.
+- **Disc::copy() CSS decrypt** — sector-level decryption during disc→ISO copy produces clean ISOs with zero scramble flags.
+
+### MPEG-2 PS demuxer fixes
+- **DVD PS path routes through codec parsers** — was bypassing parser.parse(), producing raw PES frames without codec_private extraction or keyframe detection.
+- **MPEG-2 sequence header extraction** — calculates exact header size including quantizer matrices (intra/non-intra flags), captures sequence extension from subsequent PES packets.
+- **TsDemuxer dynamic PID table** — Vec instead of fixed [i16; 8192] for DVD PIDs that may exceed 8192.
+
+## 0.10.3 (2026-04-16)
+
+### DVD CSS authentication
+- **CSS drive authentication** — full SCSI REPORT KEY / SEND KEY handshake with 6-round substitution-permutation cipher (CSSCryptKey). Brute-forces variant from 32 possibilities. Drive serves scrambled sectors after auth completes.
+- **CSS auth runs before scan** — chicken-and-egg fix: auth must happen before reading VOB sectors for title key cracking, not after.
+- **Remove debug output** — strip temporary eprintln from drive reads and CSS auth.
+
+## 0.10.2 (2026-04-15)
+
+### Fixes
+- **Disc::copy() batch overflow** — hardcoded 64-sector batch exceeded BU40N's 60-sector hardware limit, causing every read to fail and trigger 5×30s recovery sleep. Now accepts detected batch size from caller, defaults to 60.
+- **IFO PGC parsing** — playback time read from offset 0x04 (correct) instead of 0x02 (nr_programs). Cell BCD time at cell+4 not cell+0. DVD durations now correct.
+- **Demuxer flush at EOF** — TS and PS demuxers flushed when source reaches EOF, preventing loss of last PES frame. Applied to DiscStream and M2tsStream.
+- **DiscStream demuxer selection** — demuxer set by caller based on content_format (TS for Blu-ray, PS for DVD) instead of unconditionally creating TsDemuxer in from_reader()
+- **StdioStream FMKV header** — writes/reads metadata header for roundtrip compatibility through stdio pipes
+
 ## 0.10.1 (2026-04-15)
 
 ### Architecture: streams are PES, disc.copy() for sector dumps

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "libfreemkv"
-version = "0.10.2"
-edition = "2021"
+version = "0.13.11"
+edition = "2024"
 rust-version = "1.86"
 license = "AGPL-3.0-only"
 description = "Open source raw disc access library for optical drives"
@@ -31,6 +31,9 @@ libc = "0.2"
 [target.'cfg(target_os = "macos")'.dependencies]
 libc = "0.2"
 
+[dev-dependencies]
+tempfile = "3"
+
 [[bench]]
 name = "sgio_read"
 harness = false

FEATURES.md

@@ -1,6 +1,6 @@
 # libfreemkv — Feature List
 
-## v0.7.1 (current)
+## v0.10.10 (current)
 
 ### Done
 - [x] Drive access: open, identify, unlock, firmware upload, speed calibration, eject
@@ -11,13 +11,18 @@
 - [x] CLPI clip info parser (EP map, sector extents)
 - [x] AACS 1.0 decryption (4 VUK paths: KEYDB, media key, processing key, device key)
 - [x] AACS 2.0 SCSI handshake (P-256/SHA-256 ECDH, bus decryption, read data key)
+- [x] DVD IFO parser (VMG, VTS, PGC chains, cell addresses)
+- [x] DVD CSS decryption (bus auth, disc key via player keys, title key, sector descramble)
+- [x] CSS Stevenson plaintext attack for ISO key recovery
+- [x] MPEG-2 PS demuxer (DVD Program Stream with PES extraction)
+- [x] MPEG-2 video codec parser (sequence header, quantizer matrices, keyframe detection)
 - [x] KEYDB.cfg download, verify, save (raw TCP, zero HTTP deps)
 - [x] Content reading with adaptive batch sizing, error recovery, 12+ MB/s
 - [x] Stream labels: 5 BD-J format parsers (Paramount, Criterion, Pixelogic, CTRM, Deluxe)
-- [x] MKV muxer: 8 codec parsers (H.264, HEVC, AC-3, DTS, TrueHD, PGS, VC-1, LPCM)
+- [x] MKV muxer: 14 codec parsers (H.264, HEVC, MPEG-2, AC-3, DTS, TrueHD, PGS, DVD Sub, VC-1, LPCM, +4 more)
 - [x] SectorReader trait: decouples disc scanning from SCSI
 - [x] 7 stream types: Disc, ISO, MKV, M2TS, Network, Stdio, Null
-- [x] IOStream trait with URL-based resolver (scheme://path)
+- [x] PES pipeline with unified Stream trait (any source → any dest)
 - [x] FMKV metadata header for M2TS and network streams
 - [x] Numeric error codes only (no English text in library)
 - [x] Event system for progress callbacks
@@ -25,6 +30,5 @@
 ### Planned
 - [ ] Windows testing on real hardware
 - [ ] Pioneer Renesas platform support (48 drives, need GET_CONFIG 010C)
-- [ ] DVD CSS decryption
 - [ ] TranscodeStream (ffmpeg integration)
 - [ ] ISO write with BD-compliant UDF structure

Makefile

@@ -0,0 +1,20 @@
+# libfreemkv — local dev helper.
+# Mirrors the cross-crate scripts in (internal)/scripts/test-all.sh
+# but scoped to this single crate.
+
+.PHONY: test build check ci clean
+
+test:
+	cargo test --tests
+
+build:
+	cargo build --release
+
+check:
+	cargo fmt --check
+	cargo clippy --all-targets -- -D warnings
+
+ci: check build test
+
+clean:
+	cargo clean

README.md

@@ -4,7 +4,7 @@
 
 # libfreemkv
 
-Rust library for 4K UHD / Blu-ray optical drives. Drive access, disc scanning, stream labels, AACS decryption, KEYDB updates, and content reading in one crate. Bundled drive profiles — no external files needed.
+Rust library for 4K UHD / Blu-ray / DVD optical drives. Drive access, disc scanning, stream labels, AACS decryption, CSS decryption, KEYDB updates, and content reading in one crate. Bundled drive profiles — no external files needed.
 
 **12+ MB/s** sustained read speeds on BD. Full init: unlock, firmware upload, speed calibration — all from pure Rust.
 
@@ -18,7 +18,7 @@ Part of the [freemkv](https://github.com/freemkv) project.
 
 ```toml
 [dependencies]
-libfreemkv = "0.10"
+libfreemkv = "0.13"
 ```
 
 ## Quick Start
@@ -51,6 +51,31 @@ while let Ok(Some(frame)) = input.read() {
 output.finish()?;
 ```
 
+### Multi-pass recovery rip
+
+For damaged discs, the library offers a two-stage rip model: fast sweep with zero-fill and a ddrescue-format mapfile, then targeted retry of bad ranges. See [`docs/rip-recovery.md`](docs/rip-recovery.md) for the full architecture.
+
+```rust
+use libfreemkv::disc::{CopyOptions, PatchOptions};
+
+// Pass 1: disc → ISO. Fast 64 KB reads, skip-forward on failure,
+// zero-fill bad blocks, write a sidecar .mapfile.
+let mut result = disc.copy(
+    &mut drive,
+    Path::new("disc.iso"),
+    &CopyOptions { skip_on_error: true, skip_forward: true, ..Default::default() },
+)?;
+
+// Pass 2..N: retry bad ranges with full drive recovery.
+// Idempotent — call as many times as you want.
+while result.bytes_unreadable + result.bytes_pending > 0 {
+    let pr = disc.patch(&mut drive, Path::new("disc.iso"), &PatchOptions::default())?;
+    if pr.bytes_recovered_this_pass == 0 { break; }
+}
+
+// Then mux from the ISO via the normal stream pipeline (no drive involvement).
+```
+
 ## What It Does
 
 - **Drive access** — open, identify, unlock, firmware upload, speed calibration, eject
@@ -59,7 +84,7 @@ output.finish()?;
 - **Stream labels** — 5 BD-J format parsers (Paramount, Criterion, Pixelogic, CTRM, Deluxe)
 - **AACS decryption** — transparent key resolution and content decrypt (1.0 + 2.0 bus decryption)
 - **KEYDB updates** — download, verify, save from any HTTP URL (zero deps, raw TCP)
-- **Content reading** — adaptive batch reads with automatic decryption and error recovery
+- **Content reading** — adaptive batch reads with automatic decryption
 - **Stream I/O** — unified stream pipeline for reading and writing any format
 
 ### Streams
@@ -67,21 +92,21 @@ output.finish()?;
 | Stream | Input | Output | Transport |
 |--------|-------|--------|-----------|
 | DiscStream | Yes | -- | Optical drive via SCSI |
-| IsoStream | Yes | Yes | Blu-ray ISO image file |
+| IsoStream | Yes | -- | Blu-ray ISO image file (read via stream pipeline; written via `Disc::copy()`) |
 | MkvStream | Yes | Yes | Matroska container |
 | M2tsStream | Yes | Yes | BD transport stream with FMKV metadata header |
 | NetworkStream | Yes (listen) | Yes (connect) | TCP with FMKV metadata header |
 | StdioStream | Yes (stdin) | Yes (stdout) | Raw byte pipe |
 | NullStream | -- | Yes | Discard sink (byte counter for benchmarks) |
 
-Streams implement `IOStream` (byte-level) and `pes::Stream` (frame-level). `input()` / `output()` resolve URL strings to PES stream instances. `open_input()` / `open_output()` resolve to byte-level IOStream instances. All URLs use the `scheme://path` format — bare paths are rejected.
+Streams implement `pes::Stream` (frame-level). `input()` / `output()` resolve URL strings to PES stream instances. All URLs use the `scheme://path` format — bare paths are rejected.
 
 AACS decryption requires a KEYDB.cfg file. If available at `~/.config/aacs/KEYDB.cfg` or passed via `ScanOptions`, the library handles everything — handshake, key derivation, and per-sector decryption — without the application needing to know anything about encryption.
 
 ## Architecture
 
 ```text
-Drive                  — open, identify, init, unlock, read (with recovery)
+Drive                  — open, identify, init, unlock, single-shot read
   ├── ScsiTransport    — SG_IO (Linux), IOKit (macOS), SPTI (Windows)
   ├── DriveProfile     — per-drive unlock parameters (bundled)
   └── PlatformDriver   — MediaTek (supported), Renesas (planned)
@@ -134,7 +159,7 @@ All errors are structured with numeric codes. No user-facing English text — ap
 
 ## Contributing
 
-Run `freemkv drive-info --share` with the [freemkv CLI](https://github.com/freemkv/freemkv) to contribute your drive's profile.
+Run `freemkv info disc:// --share` with the [freemkv CLI](https://github.com/freemkv/freemkv) to contribute your drive's profile.
 
 ## License
 

benches/sgio_read.rs

@@ -34,24 +34,34 @@ fn main() {
     let file = std::fs::File::create("/dev/null").unwrap();
     let mut writer = std::io::BufWriter::with_capacity(4 * 1024 * 1024, file);
 
-    eprintln!("Reading 1000 batches ({:.1} MB) with write + progress...",
-        1000.0 * batch as f64 * 2048.0 / 1_048_576.0);
+    eprintln!(
+        "Reading 1000 batches ({:.1} MB) with write + progress...",
+        1000.0 * batch as f64 * 2048.0 / 1_048_576.0
+    );
 
     let start = Instant::now();
     let mut ok = 0u32;
     let mut fail = 0u32;
     let mut bytes: u64 = 0;
 
+    // Recovery flag: true matches pre-0.11.13 bench behavior — full SCSI
+    // ECC retry loop on errors (slower, what the rip path used before the
+    // adaptive batch sizer landed). Flip to `false` for the fast-fail path
+    // that current rips use; benches are configurable via this constant.
+    const READ_WITH_RECOVERY: bool = true;
+
     for i in 0..1000u32 {
         let lba = i * batch as u32;
-        match drive.read(lba, batch, &mut buf) {
+        match drive.read(lba, batch, &mut buf, READ_WITH_RECOVERY) {
             Ok(_) => {
                 writer.write_all(&buf).unwrap();
                 ok += 1;
             }
             Err(e) => {
                 fail += 1;
-                if fail <= 5 { eprintln!("  FAIL LBA {}: {}", lba, e); }
+                if fail <= 5 {
+                    eprintln!("  FAIL LBA {}: {}", lba, e);
+                }
                 buf.fill(0);
                 writer.write_all(&buf).unwrap();
             }
@@ -67,5 +77,12 @@ fn main() {
 
     let elapsed = start.elapsed().as_secs_f64();
     let mb = ok as f64 * batch as f64 * 2048.0 / 1_048_576.0;
-    eprintln!("\n{} ok, {} fail, {:.1} MB in {:.1}s = {:.1} MB/s", ok, fail, mb, elapsed, mb / elapsed);
+    eprintln!(
+        "\n{} ok, {} fail, {:.1} MB in {:.1}s = {:.1} MB/s",
+        ok,
+        fail,
+        mb,
+        elapsed,
+        mb / elapsed
+    );
 }

docs/README.md

@@ -12,6 +12,7 @@ Technical documentation for [libfreemkv](https://github.com/freemkv/libfreemkv),
 |----------|---------------|
 | [Architecture](architecture.md) | Module map, design principles, error codes, platform support |
 | [Drive Access](drive-access.md) | Drive, SCSI transport, profiles, unlock, why raw mode is needed |
+| [Rip Recovery](rip-recovery.md) | Three-layer recovery model: Disc::patch, single-shot Drive::read, DiscStream batch halving |
 | [AACS Encryption](aacs.md) | Key resolution (4 paths), content decryption, bus encryption, SCSI handshake |
 | [UDF Filesystem](udf.md) | UDF 2.50 with metadata partitions, pointer chain, how files are read from disc |
 | [MPLS Playlists](mpls.md) | Playlist format, play items, STN stream table, coding types |

docs/api-design.md

@@ -126,15 +126,45 @@ pub struct Event {
 }
 
 pub enum EventKind {
+    // Init / scan
+    DriveOpened { device: String },
+    DriveReady,
+    InitComplete { success: bool },
+    ProbeComplete { success: bool },
+    ScanComplete { titles: usize },
+
+    // Read pipeline
     BytesRead { bytes: u64, total: u64 },
     ReadError { sector: u64, error: Error },
-    Retry { attempt: u32 },
     SpeedChange { speed_kbs: u16 },
     ExtentStart { index: usize, start_sector: u64, sector_count: u64 },
+    SectorSkipped { sector: u64 },
+    BatchSizeChanged { new_size: u16, reason: BatchSizeReason },
     Complete { bytes: u64, errors: u32 },
+
+    // Kept for forward-compat; not emitted in 0.13.6+
+    Retry { attempt: u32 },
+    SectorRecovered { sector: u64 },
 }
 ```
 
+Emission notes:
+
+- `BytesRead { bytes, total }` is emitted from `DiscStream::fill_extents`
+  after each successful sector read. `bytes` is the cumulative running
+  total; `total` is the precomputed extent sum (0 if unknown).
+- `SpeedChange` is emitted from the public `Drive::set_speed` API path.
+  It is no longer emitted from a recovery hot loop (recovery loop removed
+  in 0.13.6).
+- `BatchSizeChanged` fires from the `DiscStream` adaptive sizer on shrink
+  (read failed at a larger size) and on probe-up (clean-read streak hit
+  the threshold). Consumers use it to display a "recovering" state
+  distinct from "ripping normally".
+- `Retry` and `SectorRecovered` are NOT emitted in 0.13.6+. They were
+  tied to the inline `Drive::read` recovery phases that were removed; the
+  variants are kept for forward compatibility so consumers' match arms
+  don't need conditional compilation.
+
 Events report what happened. App decides what to do. GUI shows a dialog. CLI
 prints a line. Server logs to file.
 
@@ -145,8 +175,8 @@ libfreemkv/src/
 ├── lib.rs              Public exports
 ├── error.rs            Error codes (no English)
 ├── event.rs            Event types for callbacks
-├── drive/              Drive (open, init, read with recovery)
-│   ├── mod.rs          Drive struct, init, read, reset, eject
+├── drive/              Drive (open, init, single-shot read)
+│   ├── mod.rs          Drive struct, init, read (single-shot), reset, eject
 │   ├── capture.rs      Drive profile capture for contribution
 │   ├── linux.rs        Linux drive discovery
 │   ├── macos.rs        macOS drive discovery

docs/architecture.md

@@ -41,8 +41,8 @@ AACS keys are derived internally, and all SCSI communication is handled in-proce
 libfreemkv (lib.rs)
 │
 ├── Drive Access
-│   ├── drive         Drive — open, identify, init, unlock, read (with recovery)
-│   ├── scsi          ScsiTransport trait + platform backends (SG_IO, IOKit, SPTI)
+│   ├── drive         Drive — open, identify, init, unlock, single-shot read
+│   ├── scsi          ScsiTransport trait + platform backends (sg async, IOKit, SPTI)
 │   ├── platform/     Platform trait — per-chipset command handlers
 │   │   └── mt1959    MediaTek MT1959 driver (LG, ASUS, HP)
 │   ├── profile       DriveProfile loading, matching, bundled JSON
@@ -83,7 +83,7 @@ libfreemkv (lib.rs)
 ```
 Drive::open(Path::new("/dev/sg4"))
   │
-  ├─ scsi::open()           Open /dev/sg4 via SG_IO
+  ├─ scsi::open()           Open /dev/sg4 (async write/poll/read)
   ├─ DriveId::from_drive()  INQUIRY + GET_CONFIG 010C
   ├─ profile::find_by_drive_id()  Match against bundled profiles
   ├─ Platform::new()        Instantiate chipset driver (Mt1959)
@@ -93,10 +93,17 @@ Drive::open(Path::new("/dev/sg4"))
 After open:
 - `init()` -- unlock + firmware upload + speed calibration
 - `probe_disc()` -- probe disc surface for optimal speeds
-- `read(lba, count, buf)` -- single read method with built-in error recovery
+- `read(lba, count, buf, recovery)` -- single-shot read; `recovery` only selects the per-CDB timeout (1.5 s vs. 30 s)
 - `wait_ready()` -- wait for disc insertion
 - `eject()` -- eject tray
 
+Recovery is layered above `Drive::read`, not inside it. Layer 1
+(`Disc::patch`) handles bad-range retry by replaying the ddrescue mapfile.
+Layer 3 (`DiscStream::fill_extents` adaptive batch sizer) handles in-loop
+request-size adaptation. Inline recovery (gentle retry → SCSI reset → retry)
+was removed in 0.13.6 — see [`rip-recovery.md`](rip-recovery.md) and
+`(internal)/postmortems/2026-04-25-stop-wedge-and-zero-kbs.md`.
+
 ---
 
 ## Disc Scanning Flow
@@ -175,7 +182,7 @@ is baked into the library.
 
 | Platform | Transport | Status |
 |----------|-----------|--------|
-| Linux | SG_IO ioctl on `/dev/sg*` | Supported |
+| Linux | async sg write/poll/read on `/dev/sg*` | Supported |
 | macOS | IOKit SCSITask | Supported |
 | Windows | SPTI (`IOCTL_SCSI_PASS_THROUGH_DIRECT`) | Supported |
 

docs/disc-to-rip.md

@@ -77,7 +77,9 @@ Insert disc
 10. Stream content (mux/disc.rs → DiscStream)
      │  Read sectors → decrypt → TS demux → PES frames
      │  Or: read sectors → decrypt → raw bytes (for ISO output)
-     │  Drive::read() handles error recovery (min speed → reset → retry)
+     │  Drive::read() is single-shot. DiscStream::fill_extents adapts the
+     │  batch size on failure (halve / probe-up). Bad-range retry is layer
+     │  1 above this — Disc::patch re-runs against the mapfile.
      │
      ▼
   PES frames → output stream (MKV, M2TS, network, etc.)
@@ -110,7 +112,7 @@ output.finish()?;
 
 | Module | Doc | Purpose |
 |--------|-----|---------|
-| drive/ | [drive-access.md](drive-access.md) | Open, identify, init, unlock, read (with recovery) |
+| drive/ | [drive-access.md](drive-access.md) | Open, identify, init, unlock, single-shot read |
 | scsi/ | [drive-access.md](drive-access.md) | Platform SCSI transport (Linux, macOS, Windows) |
 | udf.rs | [udf.md](udf.md) | UDF 2.50 filesystem |
 | mpls.rs | [mpls.md](mpls.md) | MPLS playlists + STN streams |

docs/drive-access.md

@@ -26,8 +26,8 @@ platform driver. The drive is ready for `wait_ready()` and `init()`.
 | `wait_ready()` | Wait for disc insertion (30s timeout, TUR polling) |
 | `init()` | Firmware upload + unlock + speed calibration |
 | `probe_disc()` | Probe disc surface for optimal speeds |
-| `read(lba, count, buf)` | Read sectors with built-in error recovery |
-| `reset()` | Close/reopen device, TUR, escalate if needed |
+| `read(lba, count, buf, recovery)` | Read sectors. Single-shot — no inline retries or reset. |
+| `reset()` | Eject-cycle escape hatch. Caller-invoked only; not on the read path. |
 | `lock_tray()` | Prevent tray ejection during rip |
 | `unlock_tray()` | Allow tray ejection (also runs on Drop) |
 | `eject()` | Eject disc tray |
@@ -44,16 +44,33 @@ platform driver. The drive is ready for `wait_ready()` and `init()`.
 3. Speed calibration after unlock
 4. Max 3 attempts before giving up
 
-### read() with Recovery
+### read() — single-shot
 
-`Drive::read()` is the single read method. On error:
+`Drive::read(lba, count, buf, recovery)` is the single read method. It issues
+exactly one READ(10) CDB and returns the result. The `recovery` parameter only
+selects the per-CDB timeout:
 
-1. Set minimum speed immediately
-2. Reset device (close/reopen/TUR)
-3. Wait 2s for drive to settle
-4. Retry at min speed, min batch (3 sectors)
-5. If still failing: skip sectors, zero-fill, log
-6. Stay at min speed for 500 MB after error (recovery window)
+| `recovery` | Timeout  | Used by                                  |
+|------------|----------|------------------------------------------|
+| `false`    | 1.5 s    | `Disc::copy` fast skip-forward sweep, `DiscStream::fill_extents` |
+| `true`     | 30 s     | `Disc::patch` multi-pass over the mapfile |
+
+On any SCSI failure or timeout, `read` returns `Err(DiscRead)` immediately.
+There are no inline retries, no SCSI reset, no Phase 1/2/3 escalation.
+
+Recovery is layered above `Drive::read`:
+
+- **Layer 1 — `Disc::patch`** loops over the ddrescue mapfile and re-issues
+  `read(.., recovery=true)` against each non-`+` range.
+- **Layer 3 — `DiscStream::fill_extents`** halves the request size on
+  failure, retries at the same LBA, and probes back up on a clean-read
+  streak.
+
+Inline recovery (5× gentle retry → close + reset + reopen → 5× more) was
+removed in 0.13.6. See `(internal)/postmortems/2026-04-25-stop-wedge-and-zero-kbs.md`
+for rationale: the inline reset wedged drive firmware on the LG BU40N (Initio
+USB-SATA bridge) without ever recovering a sector. See
+[`rip-recovery.md`](rip-recovery.md) for the full three-layer model.
 
 ---
 
@@ -70,8 +87,6 @@ pub trait ScsiTransport: Send {
         data: &mut [u8],
         timeout_ms: u32,
     ) -> Result<ScsiResult>;
-
-    fn reset(&mut self, device: &str) -> Result<()>;
 }
 ```
 
@@ -82,15 +97,29 @@ descriptors or calls ioctls outside of a `ScsiTransport` implementation.
 
 | Platform | Implementation | Device |
 |----------|---------------|--------|
-| Linux | `SgIoTransport` — `ioctl(fd, SG_IO, &hdr)` | `/dev/sg*` |
+| Linux | `SgIoTransport` — async `write`/`poll`/`read` on `/dev/sg*` | `/dev/sg*` |
 | macOS | `MacScsiTransport` — IOKit SCSITask | IOKit service |
 | Windows | `WindowsScsiTransport` — SPTI | `\\.\CdRomN` |
 
-The Linux backend opens with `O_RDWR | O_NONBLOCK`, constructs `sg_io_hdr`,
-and returns `ScsiResult` with status, bytes transferred, and sense data.
+The Linux backend uses the sg driver's asynchronous interface: `write()` submits
+the command, `poll()` waits with an enforceable wall-clock timeout, `read()`
+retrieves the result. If `poll()` times out, the fd is abandoned (closed in a
+background thread) and a fresh fd opened — the kernel's USB error recovery
+cannot block us. Opens with `O_RDWR | O_NONBLOCK`.
 
-On non-zero SCSI status, the transport parses sense key, ASC, and ASCQ from the
-sense buffer and returns `Error::ScsiError`.
+On non-zero SCSI status, the transport parses sense key from the sense buffer
+and returns `Error::ScsiError`.
+
+`SgIoTransport::reset` (Linux) does pure userspace state cleanup: an open +
+close pair to make the kernel cancel any SG_IO commands queued against a
+previous fd, a 2 s sleep to let the kernel finish that cancellation, then a
+fresh fd to send ALLOW MEDIUM REMOVAL to clear any stale tray lock. It does
+NOT issue `SG_SCSI_RESET` or escalate via STOP+START UNIT. Both were tried
+in 0.13.0–0.13.5 against the LG BU40N (Initio USB-SATA bridge); both failed
+to recover wedged drives and made the wedge worse. The macOS reset (which
+had been a no-op) was removed entirely in 0.13.6, and the top-level
+`scsi::reset()` / `reset_with_timeout()` / `reset_blocking()` wrappers were
+removed at the same time (no callers).
 
 ### CDB Builders
 

docs/rip-recovery.md

@@ -0,0 +1,181 @@
+# Rip recovery — three-layer architecture
+
+`libfreemkv` supports a multi-stage rip model for damaged or protection-bearing
+discs: a fast forward sweep that tolerates read failures, in-loop request-size
+adaptation that survives transient drive trouble without bailing, and targeted
+retry passes against a persistent bad-range map. The stream pipeline
+(`DiscStream` + `input`/`output`) operates against the resulting ISO image, so
+the mux stage never touches the drive.
+
+Recovery is layered cleanly. Each layer has one responsibility and does not
+reach into the others.
+
+| Layer | Where it lives | What it does |
+|-------|---------------|--------------|
+| 1 — Bad-range retry | `Disc::patch` (multi-pass over the mapfile) | Re-reads non-`+` ranges with the long timeout. Idempotent; call N times. |
+| 2 — Single-shot primitive | `Drive::read` in `src/drive/mod.rs` | One CDB, one timeout, one result. No inline retries, no SCSI reset. |
+| 3 — In-loop request adaptation | `DiscStream::fill_extents` adaptive batch sizer | Halves the batch on failure, retries at the same LBA, walks back up on a clean-read streak. |
+
+The caller orchestrates layer 1. Autorip's `rip_disc` loops `copy` then
+N × `patch` per the `MAX_RETRIES` config, then hands the ISO off to the
+existing mux pipeline. Layer 3 runs inside any consumer of `DiscStream`
+(direct PES pipeline, ISO playback, etc.) without caller involvement.
+
+Three primitives compose the disc-side flow:
+
+| Primitive                 | What it does                                                          |
+|---------------------------|-----------------------------------------------------------------------|
+| `Disc::copy`              | disc → ISO. Writes a sidecar `.mapfile`. Opt-in skip-forward on failure. |
+| `Disc::patch`             | Re-reads bad ranges from the drive. Idempotent; call N times.         |
+| `DiscStream` (ISO source) | Reads sectors from the ISO, feeds decrypt → demux → codec → mux.      |
+
+## Data model
+
+### Mapfile
+
+Format: [ddrescue](https://www.gnu.org/software/ddrescue/manual/ddrescue_manual.html)-compatible
+plain text, greppable, tool-interoperable. Flushed to disk on every `record()`
+so a crashed rip loses at most one block.
+
+```
+# Rescue Logfile. Created by libfreemkv v0.13.6
+# Current pos / status / pass / pass_time
+0x000000000  ?  1  0
+#      pos        size  status
+0x000000000  0x12a35d000    +
+0x12a35d000  0x000003000    -
+0x12a360000  0x009c4a000    +
+0x12d00a000  0x000064000    *
+```
+
+Status characters match ddrescue:
+
+| Char | Meaning                                            |
+|------|----------------------------------------------------|
+| `?`  | Not yet attempted                                  |
+| `*`  | Fast-pass failed; needs edge-trim                  |
+| `/`  | Trimmed; interior needs sector scrape              |
+| `-`  | Unreadable this session                            |
+| `+`  | Finished (good)                                    |
+
+Position and size are hex byte offsets into the ISO.
+
+### `CopyOptions` and `PatchOptions`
+
+Defaults preserve pre-`0.11.21` behavior — abort on the first unreadable
+sector. Opt in to the recovery-friendly path:
+
+```rust
+CopyOptions {
+    skip_on_error: true,   // zero-fill bad blocks, continue
+    skip_forward: true,    // exponential skip-forward after a failure
+    resume: true,          // pick up from an existing ISO + mapfile
+    decrypt: false,        // keep the ISO a raw disc image
+    ..Default::default()
+}
+```
+
+## Algorithm
+
+### Pass 1 — fast sweep (`Disc::copy`)
+
+1. Read 64 KB (32 sectors, one BD ECC block) at the current LBA via
+   `Drive::read(.., recovery=false)` — short 1.5 s timeout, single shot.
+2. On success: mark the range `+`, advance by one block.
+3. On failure (with `skip_on_error`): zero-fill the block in the ISO, mark
+   it `*`, advance.
+4. If `skip_forward` is set: after a failure, jump ahead by an exponentially
+   growing amount (256 KB initial, doubling on consecutive failures, capped at
+   1% of disc). The skipped bytes are also marked `*` — `patch` will visit
+   them later.
+5. Reset the skip size to 256 KB on the first success after a failure.
+
+Pass 1 completes when every byte has terminal status (`+`, `-`, or the caller
+bails via the halt flag).
+
+### Pass 2+ — patch (`Disc::patch`)
+
+`Disc::patch` reads the mapfile and iterates every non-`+` range. For each:
+
+1. Issue a drive read via `Drive::read(.., recovery=true)` — long 30 s
+   timeout, still single shot. Drive firmware does its own ECC and retries
+   inside that window; userspace does not pile on additional retries here.
+2. On success: write the good bytes into the ISO at the exact byte offset,
+   mark `+`.
+3. On failure: mark `-`.
+4. Update the mapfile after every block — crash-safe resume.
+
+Idempotent. Call `patch` N times for N retry attempts; typically the caller
+stops early if a pass recovers zero bytes (structure-protected sectors will
+never yield).
+
+### In-stream — adaptive batch halving (`DiscStream::fill_extents`)
+
+When a consumer reads a `DiscStream` directly (no ISO intermediate),
+`fill_extents` runs an adaptive sizer in front of `Drive::read`:
+
+1. Try the current preferred batch size (e.g. 32 sectors, one BD ECC block).
+2. On failure: halve the batch and retry at the same LBA. Emit
+   `EventKind::BatchSizeChanged { reason: Shrunk }`.
+3. On a clean-read streak: probe back up toward the preferred size. Emit
+   `EventKind::BatchSizeChanged { reason: Probed }`.
+4. If a single-sector read fails: skip (zero-fill, emit
+   `EventKind::SectorSkipped`) when `skip_errors` is set, otherwise return
+   `Err(DiscRead)`.
+
+This is layer 3. It exists so a transient single-sector glitch in a 32-sector
+batch can be isolated and read individually without the caller needing to
+implement retry logic.
+
+## Design choices
+
+**`Drive::read` is single-shot.** No inline retry phases, no SCSI reset,
+no eject cycle. The `recovery` flag controls only the per-CDB timeout
+(1.5 s vs. 30 s); on any failure it returns `Err(DiscRead)` immediately.
+Inline recovery (5× gentle retry → close + SCSI reset + reopen → 5× more)
+was removed in 0.13.6. See `(internal)/postmortems/2026-04-25-stop-wedge-and-zero-kbs.md`
+for rationale: the inline reset on the LG BU40N (Initio USB-SATA bridge)
+wedged drive firmware below the bridge without ever recovering a sector,
+and the gentle-retry phase produced long stretches of 0 KB/s with no
+recoveries to show for it. Recovery responsibility is now layered: layer 1
+handles ranges, layer 3 handles request size, neither touches the
+wedge-prone reset path.
+
+**No `MODE SELECT` to disable drive retries.** Research showed neither ddrescue
+nor MakeMKV does this. Drive firmware has access to raw analog signal, laser
+power control, and drive-specific ECC tuning that userspace can't replicate —
+disabling it throws away recovery headroom on marginal sectors. We fail fast
+via short SG_IO timeouts in pass 1 and let the firmware work the long timeout
+in pass 2 / patch.
+
+**No SCSI reset from any retry path.** `SgIoTransport::reset` (Linux) is
+trimmed to a kernel SG_IO state flush plus ALLOW MEDIUM REMOVAL — the
+`SG_SCSI_RESET` ioctl and STOP/START UNIT escalation were removed in 0.13.6.
+The macOS reset (which had been a no-op) was removed entirely. The top-level
+`scsi::reset()` / `reset_with_timeout()` / `reset_blocking()` wrappers were
+also removed (no callers). The remaining `Drive::reset()` is only invoked
+explicitly by callers that need an eject-cycle escape hatch — it is never
+reached from a read path.
+
+**ISO intermediate, even for single-pass.** Pass 1 always writes an ISO. The
+mux stage reads the ISO via `IsoSectorReader`. For single-pass (no retries),
+this adds ~2-3 min (local disk mux) but gains resumability across crashes,
+re-muxability without re-ripping, and a persistent forensic artifact. Callers
+who need pure speed can bypass and use `DiscStream::new(Box::new(drive), …)`
+directly — the lib doesn't forbid it, and layer 3 (adaptive batch halving)
+still applies there.
+
+**Mapfile in ddrescue format.** Plain text so users can `less` it, `diff` it,
+or feed it to ddrescue's own tooling. Crash-safe (flush-per-record). Entries
+coalesce on adjacent same-status ranges so files stay small.
+
+**Patches target `-`, `*`, `/`, and `?` alike.** The status state machine is
+ddrescue's but `patch` collapses the distinction — it just tries every
+non-finished range with the long timeout. Future work can specialize (trim vs.
+scrape vs. retry with direction reversal) if there's measured benefit.
+
+## References
+
+- [ddrescue manual, Algorithm chapter](https://www.gnu.org/software/ddrescue/manual/ddrescue_manual.html)
+- [ddrescue optical media notes](https://www.electric-spoon.com/doc/gddrescue/html/Optical-media.html)
+- Source: [`src/disc/mapfile.rs`](../src/disc/mapfile.rs), [`src/disc/mod.rs`](../src/disc/mod.rs) (`Disc::copy`, `Disc::patch`), [`src/drive/mod.rs`](../src/drive/mod.rs) (`Drive::read`), [`src/mux/disc.rs`](../src/mux/disc.rs) (`DiscStream::fill_extents`).

docs/udf.md

@@ -120,6 +120,14 @@ Each directory read involves two sector reads: one for the ICB, then one or more
 
 `read_file()` reads a file by navigating the directory tree, reading the file's ICB to get its data extent, then reading the data sector by sector from the **physical partition** (partition_start + LBA, not metadata_start).
 
+## Buffered Sector Reads
+
+USB optical drives have ~500ms round-trip latency per SCSI command. Since `read_filesystem()` and `read_file()` issue one SCSI READ per sector, a full disc scan can require hundreds of commands -- taking 10+ minutes on USB.
+
+`Disc::scan()` wraps the drive in a `BufferedSectorReader` before reading. On a single-sector read, the buffer prefetches a batch of sectors (sized from the kernel's `max_hw_sectors_kb` for the device) and caches them. Subsequent reads to nearby LBAs return from cache with zero SCSI overhead. After parsing the UDF directory structure, the entire metadata partition is pre-read into the cache, so all ICB lookups during title scanning and encryption resolution are instant.
+
+The buffer is transparent -- `read_filesystem()`, `read_file()`, and all downstream code still call `read_sectors(lba, 1, buf)` as before. The batching happens inside the `SectorReader` implementation.
+
 ### UDF Filename Encoding
 
 UDF filenames use a compression ID as the first byte:

examples/iso_dump.rs

@@ -42,7 +42,7 @@ fn main() {
         // Tiny yield between reads — test if pacing prevents firmware throttle
         std::thread::yield_now();
         let t0 = Instant::now();
-        let ok = drive.read(lba, count, &mut buf[..n]).is_ok();
+        let ok = drive.read(lba, count, &mut buf[..n], true).is_ok();
         let read_ms = t0.elapsed().as_millis();
 
         // Flag slow reads
@@ -50,7 +50,9 @@ fn main() {
             eprintln!("\n  SLOW READ: LBA {} took {}ms (ok={})", lba, read_ms, ok);
         }
 
-        if !ok { buf[..n].fill(0); }
+        if !ok {
+            buf[..n].fill(0);
+        }
         w.write_all(&buf[..n]).unwrap();
         lba += count as u32;
         bytes += n as u64;
@@ -60,11 +62,22 @@ fn main() {
             let speed = delta as f64 / last.elapsed().as_secs_f64() / 1_048_576.0;
             let avg = bytes as f64 / start.elapsed().as_secs_f64() / 1_048_576.0;
             let pct = bytes as f64 / (cap as f64 * 2048.0) * 100.0;
-            eprint!("\r  {:.1}% LBA {} | {:.0} MB/s (avg {:.0}) | {:.1} GB    ", pct, lba, speed, avg, bytes as f64 / 1e9);
+            eprint!(
+                "\r  {:.1}% LBA {} | {:.0} MB/s (avg {:.0}) | {:.1} GB    ",
+                pct,
+                lba,
+                speed,
+                avg,
+                bytes as f64 / 1e9
+            );
             last_bytes = bytes;
             last = Instant::now();
         }
     }
     w.flush().unwrap();
-    eprintln!("\nDone: {:.1} GB in {:.0}s", bytes as f64 / 1e9, start.elapsed().as_secs_f64());
+    eprintln!(
+        "\nDone: {:.1} GB in {:.0}s",
+        bytes as f64 / 1e9,
+        start.elapsed().as_secs_f64()
+    );
 }

rustfmt.toml

@@ -0,0 +1 @@
+max_width = 100

src/aacs/decrypt.rs

@@ -1,7 +1,7 @@
 //! AACS content decryption — AES primitives, unit decryption, bus encryption.
 
-use aes::cipher::{generic_array::GenericArray, BlockDecrypt, BlockEncrypt, KeyInit};
 use aes::Aes128;
+use aes::cipher::{BlockDecrypt, BlockEncrypt, KeyInit, generic_array::GenericArray};
 
 // ── AACS constants ──────────────────────────────────────────────────────────
 

src/aacs/handshake.rs

@@ -674,8 +674,8 @@ fn generate_host_key_pair() -> ([u8; 20], [u8; 20], [u8; 20]) {
 
 /// AES-128-CMAC over 16 bytes of data.
 fn aes_cmac_16(data: &[u8; 16], key: &[u8; 16]) -> [u8; 16] {
-    use aes::cipher::{generic_array::GenericArray, BlockEncrypt, KeyInit};
     use aes::Aes128;
+    use aes::cipher::{BlockEncrypt, KeyInit, generic_array::GenericArray};
 
     let cipher = Aes128::new(GenericArray::from_slice(key));
 

src/aacs/keydb.rs

@@ -361,11 +361,7 @@ mod tests {
     /// Get KEYDB path from KEYDB_PATH environment variable. Returns None if not set or not found.
     fn keydb_path() -> Option<std::path::PathBuf> {
         let path = std::path::PathBuf::from(std::env::var("KEYDB_PATH").ok()?);
-        if path.exists() {
-            Some(path)
-        } else {
-            None
-        }
+        if path.exists() { Some(path) } else { None }
     }
 
     #[test]

src/aacs/keys.rs

@@ -661,18 +661,14 @@ pub fn resolve_keys(
 
 #[cfg(test)]
 mod tests {
-    use super::super::decrypt::{aes_ecb_encrypt, ALIGNED_UNIT_LEN};
+    use super::super::decrypt::{ALIGNED_UNIT_LEN, aes_ecb_encrypt};
     use super::super::keydb::{DiscEntry, KeyDb};
     use super::*;
 
     /// Get KEYDB path from KEYDB_PATH environment variable. Returns None if not set or not found.
     fn keydb_path() -> Option<std::path::PathBuf> {
         let path = std::path::PathBuf::from(std::env::var("KEYDB_PATH").ok()?);
-        if path.exists() {
-            Some(path)
-        } else {
-            None
-        }
+        if path.exists() { Some(path) } else { None }
     }
 
     #[test]
@@ -849,7 +845,7 @@ mod tests {
         data[23] = 1; // top_menu = CPS unit 1
         data[24] = 0;
         data[25] = 1; // num_titles = 1
-                      // Title 0 entry: 2 bytes pad + CPS unit
+        // Title 0 entry: 2 bytes pad + CPS unit
         data[28] = 0;
         data[29] = 1; // CPS unit 1