v0.13.10: version sync

v0.13.9: Disc::copy stall guard + SgIoTransport no-reopen-on-timeout
Fixes the silent Pass 1 hang observed on Dune 2 with v0.13.8 (drive grinding through bad sectors at 0 KB/s, errs=0, no error surfaced). Root cause: SgIoTransport::execute's reopen-after-poll-timeout opened a fresh /dev/sg* fd on the main thread, which serialized against the spawned close() of the old fd via the kernel's per-device state lock. The userspace 1.5s timeout still fired, but the abandon-and-reopen recovery itself blocked the main thread for as long as close() took. Net: reads returned slowly, skip-forward fired on every iteration, bytes_good never advanced. - SgIoTransport::execute: on poll timeout, spawn close, set fd=-1, return Err. No reopen on the main thread. The transport is now invalidated until the consumer creates a fresh Drive. - Disc::copy: add stall guard. CopyOptions.stall_secs (default 120s). If bytes_good doesn't advance for the threshold, break 'outer cleanly with complete=false, bytes_pending > 0 so Pass 2 retries pick up the NonTrimmed ranges with recovery=true 30s timeouts. - New regression test: test_disc_copy_stall_detection_triggers_ skip_forward in tests/integration_progress_and_halt.rs.
2026-10-07 18:13:10 +00:00 · 2026-04-25 08:25:08 -07:00 · 2026-04-25 08:12:01 -07:00 · 2026-04-25 07:11:47 -07:00 · 2026-04-25 06:58:43 -07:00 · 2026-04-24 21:43:30 -07:00
42 changed files with 2226 additions and 817 deletions
@@ -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
@@ -1,5 +1,463 @@
 # Changelog

+## 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
@@ -1,6 +1,6 @@
 [package]
 name = "libfreemkv"
-version = "0.12.2"
+version = "0.13.10"
 edition = "2024"
 rust-version = "1.86"
 license = "AGPL-3.0-only"
@@ -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
@@ -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
@@ -18,7 +18,7 @@ Part of the [freemkv](https://github.com/freemkv) project.

 ```toml
 [dependencies]
-libfreemkv = "0.11"
+libfreemkv = "0.13"
 ```

 ## Quick Start
@@ -84,7 +84,7 @@ while result.bytes_unreadable + result.bytes_pending > 0 {
 - **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
@@ -92,21 +92,21 @@ while result.bytes_unreadable + result.bytes_pending > 0 {
 | 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)
@@ -44,9 +44,15 @@ fn main() {
    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;
@@ -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 |
@@ -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
@@ -41,7 +41,7 @@ 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)
+│   ├── 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)
@@ -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
@@ -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 |
@@ -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,22 +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(lba, count, buf, recovery)` is the single read method. The
-`recovery` parameter controls whether to attempt multi-phase recovery on
-failure or return immediately (used by DiscStream's binary search for
-single-sector probes).
+`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:

-On error with `recovery = true`:
+| `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 |

-1. **Phase 1 — gentle retry (5 attempts):** set min speed, sleep 30s, retry.
-   Each retry has a hard wall-clock timeout via async SG_IO.
-2. **Phase 2 — fresh start:** close transport, reset device, reopen, reinit.
-3. **Phase 3 — gentle retry on fresh connection (5 attempts).**
-4. If all fail: return `Err(DiscRead)`. DiscStream handles it (binary search,
-   skip, zero-fill).
-5. Stay at min speed for 500 MB after any recovery (recovery window).
+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.

 ---

@@ -99,6 +110,17 @@ cannot block us. Opens with `O_RDWR | O_NONBLOCK`.
 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

 The `scsi` module provides platform-agnostic CDB constructors:
@@ -1,12 +1,27 @@
-# Rip recovery — multi-pass architecture
+# Rip recovery — three-layer architecture

-`libfreemkv` supports a two-stage rip model for damaged or protection-bearing
-discs: a fast forward sweep that tolerates read failures, followed by targeted
+`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.

-Three primitives compose the flow:
+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                                                          |
 |---------------------------|-----------------------------------------------------------------------|
@@ -14,9 +29,6 @@ Three primitives compose the flow:
 | `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.      |

-The caller orchestrates. Autorip's `rip_disc` loops `copy` then N × `patch` per
-the `MAX_RETRIES` config, then hands the ISO off to the existing mux pipeline.
-
 ## Data model

 ### Mapfile
@@ -26,7 +38,7 @@ 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.11.22
+# Rescue Logfile. Created by libfreemkv v0.13.6
 # Current pos / status / pass / pass_time
 0x000000000  ?  1  0
 #      pos        size  status
@@ -50,8 +62,8 @@ Position and size are hex byte offsets into the ISO.

 ### `CopyOptions` and `PatchOptions`

-Defaults preserve pre-`0.11.21` behavior — full drive recovery on every read,
-abort on the first unreadable sector. Opt in to the recovery-friendly path:
+Defaults preserve pre-`0.11.21` behavior — abort on the first unreadable
+sector. Opt in to the recovery-friendly path:

 ```rust
 CopyOptions {
@@ -65,9 +77,10 @@ CopyOptions {

 ## Algorithm

-### Pass 1 — fast sweep
+### Pass 1 — fast sweep (`Disc::copy`)

-1. Read 64 KB (32 sectors, one BD ECC block) at the current LBA.
+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.
@@ -80,12 +93,13 @@ CopyOptions {
 Pass 1 completes when every byte has terminal status (`+`, `-`, or the caller
 bails via the halt flag).

-### Pass 2+ — patch
+### Pass 2+ — patch (`Disc::patch`)

 `Disc::patch` reads the mapfile and iterates every non-`+` range. For each:

-1. Issue a drive read with full recovery enabled (SCSI-level retries,
-   ECC recovery, the lot).
+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 `-`.
@@ -95,21 +109,61 @@ 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 instead, and we avoid per-sector probing on first
-contact by using large blocks + skip-forward.
+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.
+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
@@ -117,11 +171,11 @@ 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 full recovery. Future work can specialize (trim vs.
+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`)
+- 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`).
@@ -132,6 +132,7 @@ impl Disc {
                                codec,
                                language: s.language.clone(),
                                forced: false,
+                                qualifier: crate::disc::LabelQualifier::None,
                                codec_data: None,
                            }))
                        } else {
@@ -142,6 +143,7 @@ impl Disc {
                                language: s.language.clone(),
                                sample_rate: SampleRate::from_audio_rate(s.audio_rate),
                                secondary: s.stream_type == 5,
+                                purpose: crate::disc::LabelPurpose::Normal,
                                label: String::new(),
                            }))
                        }
@@ -151,6 +153,7 @@ impl Disc {
                        codec,
                        language: s.language.clone(),
                        forced: false,
+                        qualifier: crate::disc::LabelQualifier::None,
                        codec_data: None,
                    })),
                    // Stream type 4 = IG, unknown types -- skip
@@ -48,6 +48,7 @@ impl Disc {
                        language: a.language.clone(),
                        sample_rate: SampleRate::from_hz(a.sample_rate),
                        secondary: false,
+                        purpose: crate::disc::LabelPurpose::Normal,
                        label: String::new(),
                    })
                })
@@ -92,6 +93,7 @@ impl Disc {
                            codec: Codec::DvdSub,
                            language: s.language.clone(),
                            forced: false,
+                            qualifier: crate::disc::LabelQualifier::None,
                            codec_data: codec_data.clone(),
                        })
                    })
@@ -149,10 +149,13 @@ impl Mapfile {
                .next()
                .and_then(SectorStatus::from_char)
                .ok_or_else(|| {
-                    io::Error::new(
-                        io::ErrorKind::InvalidData,
-                        format!("bad status char in mapfile: {}", fields[2]),
-                    )
+                    // No English text — the variant carries a stable
+                    // language-neutral kind identifier (`status_char`).
+                    let e: io::Error = crate::error::Error::MapfileInvalid {
+                        kind: "status_char",
+                    }
+                    .into();
+                    e
                })?;
            entries.push(MapEntry { pos, size, status });
        }
@@ -318,8 +321,12 @@ impl Mapfile {

 fn parse_hex(s: &str) -> io::Result<u64> {
    let s = s.strip_prefix("0x").unwrap_or(s);
-    u64::from_str_radix(s, 16)
-        .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, format!("bad hex {s}: {e}")))
+    u64::from_str_radix(s, 16).map_err(|_| {
+        // Underlying ParseIntError dropped — its Display is OS-locale text.
+        // The typed variant carries `kind = "hex"` which is stable.
+        let e: io::Error = crate::error::Error::MapfileInvalid { kind: "hex" }.into();
+        e
+    })
 }

 #[cfg(test)]
@@ -20,6 +20,11 @@ use crate::udf;

 use encrypt::HandshakeResult;

+// Re-export label classification enums alongside AudioStream / SubtitleStream
+// so the public surface keeps the structured metadata together. Callers map
+// these to display text in their own locale.
+pub use crate::labels::{LabelPurpose, LabelQualifier};
+
 // ─── Public types ───────────────────────────────────────────────────────────

 /// A scanned Blu-ray disc.
@@ -180,7 +185,11 @@ pub struct AudioStream {
    pub sample_rate: SampleRate,
    /// Whether this is a secondary stream (commentary)
    pub secondary: bool,
-    /// Extra label
+    /// Stream purpose (commentary / descriptive / score / IME / normal).
+    /// Callers translate this to display text in their own locale.
+    pub purpose: LabelPurpose,
+    /// Codec / variant text (e.g. "Dolby TrueHD 5.1", "(US)").
+    /// NEVER contains English purpose words — see `purpose` for that.
    pub label: String,
 }

@@ -195,6 +204,9 @@ pub struct SubtitleStream {
    pub language: String,
    /// Whether this is a forced subtitle
    pub forced: bool,
+    /// Subtitle qualifier (SDH / descriptive service / forced / none).
+    /// Callers translate this to display text in their own locale.
+    pub qualifier: LabelQualifier,
    /// Pre-formatted codec private data (e.g. VobSub .idx palette header)
    pub codec_data: Option<Vec<u8>>,
 }
@@ -889,13 +901,6 @@ pub struct ScanOptions {
 }

 impl ScanOptions {
-    /// Create options with a specific KEYDB path.
-    pub fn with_keydb(path: impl Into<std::path::PathBuf>) -> Self {
-        ScanOptions {
-            keydb_path: Some(path.into()),
-        }
-    }
-
    /// Resolve KEYDB path: explicit path first, then standard locations.
    fn resolve_keydb(&self) -> Option<std::path::PathBuf> {
        if let Some(p) = &self.keydb_path {
@@ -1281,6 +1286,9 @@ impl Disc {
        let mut buf = vec![0u8; batch as usize * 2048];
        let mut bytes_done = 0u64;
        let mut halt_requested = false;
+        let stall_threshold = std::time::Duration::from_secs(opts.stall_secs.unwrap_or(120));
+        let mut last_good_advance = std::time::Instant::now();
+        let mut last_observed_good: u64 = 0;

        // Iterate over not-yet-finished regions from the mapfile. We re-read the
        // mapfile after each block because record() mutates the region list.
@@ -1310,6 +1318,30 @@ impl Disc {
                        break 'outer;
                    }
                }
+                // Stall guard. The signal is "bytes_good (Finished sectors)
+                // hasn't advanced for stall_threshold." pos may still be
+                // advancing via the skip_on_error branch; that's not real
+                // progress because skip-forward only marks ranges
+                // NonTrimmed for Pass 2 to retry. If we go stall_threshold
+                // without ANY successful read, the drive is grinding
+                // unproductively (or kernel is silently stalling reads
+                // past their per-CDB timeout — observed live on Dell with
+                // SgIoTransport's reopen-after-timeout serializing
+                // against close). Bail Pass 1; Pass 2 (Disc::patch with
+                // recovery=true, 30 s timeouts) will retry the
+                // NonTrimmed ranges.
+                let cur_good = map.stats().bytes_good;
+                if cur_good != last_observed_good {
+                    last_observed_good = cur_good;
+                    last_good_advance = std::time::Instant::now();
+                } else if last_good_advance.elapsed() > stall_threshold {
+                    // Stall: bail Pass 1. Return cleanly with
+                    // bytes_pending > 0 and complete = false so the
+                    // caller's retry path (Disc::patch with
+                    // recovery=true, 30s timeouts) gets a shot at the
+                    // NonTrimmed ranges.
+                    break 'outer;
+                }
                let block_bytes = (region_end - pos).min(batch as u64 * 2048);
                let lba = (pos / 2048) as u32;
                let count = (block_bytes / 2048) as u16;
@@ -1399,6 +1431,15 @@ pub struct CopyOptions<'a> {
    pub skip_forward: bool,
    pub on_progress: Option<&'a dyn Fn(u64, u64)>,
    pub halt: Option<std::sync::Arc<std::sync::atomic::AtomicBool>>,
+    /// Wall-clock stall threshold in seconds. If the inner copy loop runs
+    /// this long without `pos` advancing, the current block is treated as
+    /// a read failure (skip-forward in `skip_on_error` mode, else
+    /// `Err(DiscRead)`). Defaults to 120 s. Defensive guard for
+    /// kernel-level hangs that bypass the per-CDB SCSI timeout — e.g. the
+    /// v0.13.8 case where SgIoTransport's reopen-after-timeout serialized
+    /// against the in-flight close, blocking the main thread for tens of
+    /// seconds per read.
+    pub stall_secs: Option<u64>,
 }

 /// Result of `Disc::copy`. `complete=true` means every byte reached a terminal
@@ -8,12 +8,15 @@

 pub mod capture;

+// Per-platform discovery helpers (the `pub(crate)` `find_drives` /
+// equivalents). Crate-public so `scsi/{linux,macos,windows}.rs` can
+// reuse the existing enumeration logic when shaping `DriveInfo`.
 #[cfg(target_os = "linux")]
-mod linux;
+pub(crate) mod linux;
 #[cfg(target_os = "macos")]
-mod macos;
+pub(crate) mod macos;
 #[cfg(windows)]
-mod windows;
+pub(crate) mod windows;

 use crate::error::{Error, Result};
 use crate::event::{Event, EventKind};
@@ -50,9 +53,6 @@ const SCSI_GET_EVENT_STATUS: u8 = 0x4A;
 const SCSI_MODE_SENSE: u8 = 0x5A;
 const SCSI_REPORT_KEY: u8 = 0xA4;

-/// Recovery state after a read error — stay at min speed for N bytes.
-const RECOVERY_WINDOW: u64 = 500 * 1024 * 1024; // 500 MB
-
 /// Optical disc drive session -- open, identify, unlock, and read.
 pub struct Drive {
    scsi: Box<dyn ScsiTransport>,
@@ -61,11 +61,9 @@ pub struct Drive {
    pub platform: Option<profile::Platform>,
    pub drive_id: DriveId,
    device_path: String,
-    /// Bytes remaining in the min-speed recovery window.
-    recovery_bytes_remaining: u64,
    /// Halt flag — when set, Drive::read() bails at the next check point.
    halt: Arc<AtomicBool>,
-    /// Event handler — fires during read recovery.
+    /// Event handler — fires for read errors and library-level state changes.
    event_fn: Option<Box<dyn Fn(Event) + Send>>,
 }

@@ -92,7 +90,6 @@ impl Drive {
            profile,
            drive_id,
            device_path: device.to_string_lossy().to_string(),
-            recovery_bytes_remaining: 0,
            halt: Arc::new(AtomicBool::new(false)),
            event_fn: None,
        })
@@ -118,6 +115,9 @@ impl Drive {
        self.event_fn = Some(Box::new(f));
    }

+    #[allow(dead_code)] // public on_event registration kept; Drive currently
+    // has no internal emission sites after the 0.13.6 recovery strip.
+    // DiscStream is the BytesRead source. Plan to drop on_event in 0.14.
    fn emit(&self, kind: EventKind) {
        if let Some(ref f) = self.event_fn {
            f(Event { kind });
@@ -128,13 +128,6 @@ impl Drive {
        self.halt.load(Ordering::Relaxed)
    }

-    /// Halt-aware sleep. Returns `Err(Halted)` if the flag fires before or
-    /// during the wait. The only sleep the drive's recovery path is allowed
-    /// to use — makes it impossible to accidentally block through a Stop.
-    fn checked_sleep(&self, total: std::time::Duration) -> Result<()> {
-        sleep_until_halted(&self.halt, total)
-    }
-
    /// Halt-aware SCSI execute. Returns `Err(Halted)` if the flag is set
    /// before the command dispatches or by the time it completes. The only
    /// path to talk to the drive in the recovery hot loop; keeps Drive::read
@@ -516,29 +509,25 @@ impl Drive {
        }
    }

-    /// Read sectors from the disc with automatic error recovery.
+    /// Read sectors from the disc. Single-shot — no inline retries, no
+    /// SCSI reset.
    ///
-    /// On failure: drops to min speed, waits with escalating patience
-    /// (5s, 10s, 15s, 30s, 60s), resets drive between attempts.
-    /// After recovery, stays at min speed for 500 MB before ramping up.
+    /// `recovery=true` bumps the per-CDB timeout to 30 s for the
+    /// `Disc::patch` pass; `recovery=false` uses 1.5 s for `Disc::copy`'s
+    /// fast skip-forward sweep. On any failure returns `Err(DiscRead)`
+    /// immediately. The orchestration layer (`Disc::patch`'s outer loop
+    /// for the patch pass, `DiscStream`'s adaptive batch halving for the
+    /// stream path) handles retries.
    ///
-    /// Returns Err only after all attempts exhausted — user should clean
-    /// the disc and resume.
+    /// Inline retry phases (5× gentle + reset+reopen + 5× more) were
+    /// removed in 0.13.6. Per
+    /// `(internal)/postmortems/2026-04-25-stop-wedge-and-zero-kbs.md`,
+    /// the inline reset on the LG BU40N (Initio bridge) wedged drive
+    /// firmware without ever recovering a sector. The remaining recovery
+    /// layers (Disc::patch multi-pass, DiscStream batch halving) do not
+    /// touch the wedge-prone reset path.
    pub fn read(&mut self, lba: u32, count: u16, buf: &mut [u8], recovery: bool) -> Result<usize> {
-        // Non-recovery mode is the Disc::copy fast pass — intent is "fail
-        // fast, let skip_forward advance past bad regions." A 5s budget let
-        // the drive grind L-EC on structure-protected / marginal sectors for
-        // nearly the full interval per 64 KB block, pinning throughput at
-        // ~13 KB/s on difficult discs. 1500ms kills slow reads early so
-        // skip_forward can double its stride; recoverable sectors are picked
-        // up on Disc::patch where recovery=true and the timeout is 30s.
-        let timeout_ms = if !recovery {
-            1_500
-        } else if self.recovery_bytes_remaining > 0 {
-            30_000
-        } else {
-            10_000
-        };
+        let timeout_ms = if recovery { 30_000 } else { 1_500 };
        let cdb = [
            crate::scsi::SCSI_READ_10,
            0x00,
@@ -552,82 +541,16 @@ impl Drive {
            0x00,
        ];

-        // Normal read. Fast path: drive returns data, we return it.
-        // checked_exec short-circuits to Err(Halted) if Stop was requested;
-        // read() never touches the halt flag directly.
        match self.checked_exec(
            &cdb,
            crate::scsi::DataDirection::FromDevice,
            buf,
            timeout_ms,
        ) {
-            Ok(result) => {
-                if self.recovery_bytes_remaining > 0 {
-                    let bytes_read = count as u64 * 2048;
-                    self.recovery_bytes_remaining =
-                        self.recovery_bytes_remaining.saturating_sub(bytes_read);
-                    if self.recovery_bytes_remaining == 0 {
-                        self.emit(EventKind::SpeedChange { speed_kbs: 0xFFFF });
-                        self.set_speed(0xFFFF);
-                    }
-                }
-                return Ok(result.bytes_transferred);
-            }
-            Err(Error::Halted) => return Err(Error::Halted),
-            Err(_) => { /* fall through to recovery */ }
+            Ok(result) => Ok(result.bytes_transferred),
+            Err(Error::Halted) => Err(Error::Halted),
+            Err(_) => Err(Error::DiscRead { sector: lba as u64 }),
        }
-
-        if !recovery {
-            return Err(Error::DiscRead { sector: lba as u64 });
-        }
-
-        // Enter recovery
-        self.emit(EventKind::ReadError {
-            sector: lba as u64,
-            error: Error::DiscRead { sector: lba as u64 },
-        });
-        self.emit(EventKind::SpeedChange { speed_kbs: 0 });
-        self.set_speed(0);
-
-        // Phase 1: gentle — sleep 30 s, retry. 5 times.
-        for attempt in 1..=5u32 {
-            self.emit(EventKind::Retry { attempt });
-            self.checked_sleep(std::time::Duration::from_secs(30))?;
-            if let Ok(result) =
-                self.checked_exec(&cdb, crate::scsi::DataDirection::FromDevice, buf, 30_000)
-            {
-                self.emit(EventKind::SectorRecovered { sector: lba as u64 });
-                self.recovery_bytes_remaining = RECOVERY_WINDOW;
-                return Ok(result.bytes_transferred);
-            }
-        }
-
-        // Phase 2: fresh start — close, reset, open, init.
-        let device = std::path::PathBuf::from(&self.device_path);
-        self.checked_sleep(std::time::Duration::from_secs(5))?;
-        let _ = crate::scsi::reset(&device);
-        self.checked_sleep(std::time::Duration::from_secs(5))?;
-        self.scsi = crate::scsi::open(&device)?;
-        let _ = self.init();
-        let _ = self.wait_ready();
-        self.set_speed(0);
-
-        // Phase 3: gentle again on fresh connection — sleep 30 s, retry. 5 times.
-        for attempt in 6..=10u32 {
-            self.emit(EventKind::Retry { attempt });
-            self.checked_sleep(std::time::Duration::from_secs(30))?;
-            if let Ok(result) =
-                self.checked_exec(&cdb, crate::scsi::DataDirection::FromDevice, buf, 30_000)
-            {
-                self.emit(EventKind::SectorRecovered { sector: lba as u64 });
-                self.recovery_bytes_remaining = RECOVERY_WINDOW;
-                return Ok(result.bytes_transferred);
-            }
-        }
-
-        // Both phases failed.
-        self.recovery_bytes_remaining = RECOVERY_WINDOW;
-        Err(Error::DiscRead { sector: lba as u64 })
    }

    /// Read the disc capacity in sectors (2048 bytes each).
@@ -739,11 +662,26 @@ impl SectorReader for Drive {
    }
 }

-/// Halt-aware sleep primitive. Returns `Err(Halted)` if the flag is set
-/// before or during the wait. Extracted as a free function so it can be
-/// unit-tested without constructing a full `Drive`.
-///
-/// Wakes within ~100 ms of a halt, regardless of the requested duration.
+/// Find all optical drives connected to this system.
+/// Returns opened Drive objects ready for use.
+pub fn find_drives() -> Vec<Drive> {
+    discover_drives()
+        .into_iter()
+        .filter_map(|(path, _)| Drive::open(std::path::Path::new(&path)).ok())
+        .collect()
+}
+
+/// Find the first optical drive.
+/// Returns an opened Drive ready for use.
+pub fn find_drive() -> Option<Drive> {
+    find_drives().into_iter().next()
+}
+
+/// Halt-aware sleep primitive — wakes within ~100 ms of `halt` flipping
+/// to true. Kept for the unit tests that cover the slicing behaviour;
+/// production code paths no longer sleep on the recovery hot path
+/// (recovery loop removed in 0.13.6).
+#[cfg(test)]
 fn sleep_until_halted(halt: &AtomicBool, total: std::time::Duration) -> Result<()> {
    const SLICE: std::time::Duration = std::time::Duration::from_millis(100);
    let deadline = std::time::Instant::now() + total;
@@ -760,21 +698,6 @@ fn sleep_until_halted(halt: &AtomicBool, total: std::time::Duration) -> Result<(
    }
 }

-/// Find all optical drives connected to this system.
-/// Returns opened Drive objects ready for use.
-pub fn find_drives() -> Vec<Drive> {
-    discover_drives()
-        .into_iter()
-        .filter_map(|(path, _)| Drive::open(std::path::Path::new(&path)).ok())
-        .collect()
-}
-
-/// Find the first optical drive.
-/// Returns an opened Drive ready for use.
-pub fn find_drive() -> Option<Drive> {
-    find_drives().into_iter().next()
-}
-
 /// Internal: discover drive paths + IDs without opening full Drive objects.
 fn discover_drives() -> Vec<(String, DriveId)> {
    #[cfg(target_os = "linux")]
@@ -815,10 +738,8 @@ fn create_driver(
    match platform {
        profile::Platform::Mt1959A => Ok(Box::new(Mt1959::new(profile.clone(), false))),
        profile::Platform::Mt1959B => Ok(Box::new(Mt1959::new(profile.clone(), true))),
-        profile::Platform::Renesas => Err(Error::UnsupportedDrive {
-            vendor_id: profile.identity.vendor_id.trim().to_string(),
-            product_id: String::new(),
-            product_revision: "Renesas not yet implemented".to_string(),
+        profile::Platform::Renesas => Err(Error::PlatformNotImplemented {
+            platform: "renesas".to_string(),
        }),
    }
 }
@@ -24,10 +24,15 @@ pub const E_DEVICE_NOT_FOUND: u16 = 1000;
 pub const E_DEVICE_PERMISSION: u16 = 1001;
 pub const E_DEVICE_NOT_READY: u16 = 1002;
 pub const E_DEVICE_RESET_FAILED: u16 = 1003;
+pub const E_SCSI_INTERFACE_UNAVAILABLE: u16 = 1004;
+pub const E_DEVICE_LOCKED: u16 = 1005;
+pub const E_IOKIT_PLUGIN_FAILED: u16 = 1006;

 // Profile (2xxx)
 pub const E_UNSUPPORTED_DRIVE: u16 = 2000;
 pub const E_PROFILE_PARSE: u16 = 2002;
+pub const E_UNSUPPORTED_PLATFORM: u16 = 2003;
+pub const E_PLATFORM_NOT_IMPLEMENTED: u16 = 2004;

 // Unlock (3xxx)
 pub const E_UNLOCK_FAILED: u16 = 3000;
@@ -49,6 +54,7 @@ pub const E_DISC_TITLE_RANGE: u16 = 6005;
 pub const E_IFO_PARSE: u16 = 6007;
 pub const E_MKV_INVALID: u16 = 6008;
 pub const E_NO_STREAMS: u16 = 6009;
+pub const E_MAPFILE_INVALID: u16 = 6011;

 // AACS (7xxx)
 pub const E_AACS_NO_KEYS: u16 = 7000;
@@ -84,6 +90,7 @@ pub const E_PES_FRAME_TOO_LARGE: u16 = 9005;
 pub const E_PES_INVALID_MAGIC: u16 = 9006;
 pub const E_ISO_TOO_LARGE: u16 = 9007;
 pub const E_NO_METADATA: u16 = 9008;
+pub const E_DISC_URL_NOT_DIRECT: u16 = 9009;

 // ── Error enum ──────────────────────────────────────────────────────────────

@@ -103,6 +110,24 @@ pub enum Error {
    DeviceResetFailed {
        path: String,
    },
+    /// Platform-specific SCSI interface couldn't be obtained from the OS
+    /// (macOS: `SCSITaskDeviceInterface` unavailable). The `path` field
+    /// carries the device path; no English commentary on the failure mode.
+    ScsiInterfaceUnavailable {
+        path: String,
+    },
+    /// Device is held by another process / kernel state. `kr` is the
+    /// platform return code (macOS IOReturn, Linux errno-equivalent).
+    DeviceLocked {
+        path: String,
+        kr: u32,
+    },
+    /// macOS IOKit plugin couldn't be created for this device. `kr` is
+    /// the IOReturn code from `IOCreatePlugInInterfaceForService`.
+    IoKitPluginFailed {
+        path: String,
+        kr: u32,
+    },

    // Profile (2xxx)
    UnsupportedDrive {
@@ -111,6 +136,16 @@ pub enum Error {
        product_revision: String,
    },
    ProfileParse,
+    /// SCSI transport was requested on an OS without a backend
+    /// implementation. `target` is the `std::env::consts::OS` value.
+    UnsupportedPlatform {
+        target: String,
+    },
+    /// Drive matched a known platform that we haven't implemented yet
+    /// (e.g. Renesas firmware). `platform` is a stable identifier.
+    PlatformNotImplemented {
+        platform: String,
+    },

    // Unlock (3xxx)
    UnlockFailed,
@@ -149,6 +184,12 @@ pub enum Error {
    IfoParse,
    MkvInvalid,
    NoStreams,
+    /// ddrescue mapfile parse failed. `kind` is a stable, language-neutral
+    /// identifier (e.g. `"status_char"`, `"hex"`); not a translatable
+    /// English message.
+    MapfileInvalid {
+        kind: &'static str,
+    },

    // AACS (7xxx)
    AacsNoKeys,
@@ -202,6 +243,10 @@ pub enum Error {
        path: String,
    },
    NoMetadata,
+    /// `disc://` URLs aren't openable through `input()` — callers must use
+    /// `Drive::open() + Disc::scan() + DiscStream::new()` directly. This
+    /// is a structural API constraint, not a parse failure.
+    DiscUrlNotDirect,
 }

 impl Error {
@@ -211,8 +256,13 @@ impl Error {
            Error::DevicePermission { .. } => E_DEVICE_PERMISSION,
            Error::DeviceNotReady { .. } => E_DEVICE_NOT_READY,
            Error::DeviceResetFailed { .. } => E_DEVICE_RESET_FAILED,
+            Error::ScsiInterfaceUnavailable { .. } => E_SCSI_INTERFACE_UNAVAILABLE,
+            Error::DeviceLocked { .. } => E_DEVICE_LOCKED,
+            Error::IoKitPluginFailed { .. } => E_IOKIT_PLUGIN_FAILED,
            Error::UnsupportedDrive { .. } => E_UNSUPPORTED_DRIVE,
            Error::ProfileParse => E_PROFILE_PARSE,
+            Error::UnsupportedPlatform { .. } => E_UNSUPPORTED_PLATFORM,
+            Error::PlatformNotImplemented { .. } => E_PLATFORM_NOT_IMPLEMENTED,
            Error::UnlockFailed => E_UNLOCK_FAILED,
            Error::SignatureMismatch { .. } => E_SIGNATURE_MISMATCH,
            Error::ScsiError { .. } => E_SCSI_ERROR,
@@ -226,6 +276,7 @@ impl Error {
            Error::IfoParse => E_IFO_PARSE,
            Error::MkvInvalid => E_MKV_INVALID,
            Error::NoStreams => E_NO_STREAMS,
+            Error::MapfileInvalid { .. } => E_MAPFILE_INVALID,
            Error::AacsNoKeys => E_AACS_NO_KEYS,
            Error::AacsCertShort => E_AACS_CERT_SHORT,
            Error::AacsAgidAlloc => E_AACS_AGID_ALLOC,
@@ -255,6 +306,7 @@ impl Error {
            Error::PesInvalidMagic => E_PES_INVALID_MAGIC,
            Error::IsoTooLarge { .. } => E_ISO_TOO_LARGE,
            Error::NoMetadata => E_NO_METADATA,
+            Error::DiscUrlNotDirect => E_DISC_URL_NOT_DIRECT,
        }
    }
 }
@@ -267,6 +319,22 @@ impl std::fmt::Display for Error {
            Error::DevicePermission { path } => write!(f, "E{}: {}", self.code(), path),
            Error::DeviceNotReady { path } => write!(f, "E{}: {}", self.code(), path),
            Error::DeviceResetFailed { path } => write!(f, "E{}: {}", self.code(), path),
+            Error::ScsiInterfaceUnavailable { path } => write!(f, "E{}: {}", self.code(), path),
+            Error::DeviceLocked { path, kr } => {
+                write!(f, "E{}: {} 0x{:08x}", self.code(), path, kr)
+            }
+            Error::IoKitPluginFailed { path, kr } => {
+                write!(f, "E{}: {} 0x{:08x}", self.code(), path, kr)
+            }
+            Error::UnsupportedPlatform { target } => {
+                write!(f, "E{}: {}", self.code(), target)
+            }
+            Error::PlatformNotImplemented { platform } => {
+                write!(f, "E{}: {}", self.code(), platform)
+            }
+            Error::MapfileInvalid { kind } => {
+                write!(f, "E{}: {}", self.code(), kind)
+            }
            Error::UnsupportedDrive {
                vendor_id,
                product_id,
@@ -357,7 +425,10 @@ impl From<Error> for std::io::Error {
            7000..=7999 => std::io::ErrorKind::PermissionDenied,
            8000..=8999 => std::io::ErrorKind::Other,
            9000..=9001 => std::io::ErrorKind::Unsupported,
-            9002..=9009 => std::io::ErrorKind::InvalidInput,
+            9002..=9008 => std::io::ErrorKind::InvalidInput,
+            // 9009 DiscUrlNotDirect: structurally unsupported entry point,
+            // not a parse failure — caller used the wrong API.
+            9009 => std::io::ErrorKind::Unsupported,
            _ => std::io::ErrorKind::Other,
        };
        std::io::Error::new(kind, msg)
@@ -366,3 +437,141 @@ impl From<Error> for std::io::Error {

 /// Convenience alias for `Result<T, Error>`.
 pub type Result<T> = std::result::Result<T, Error>;
+
+#[cfg(test)]
+mod tests {
+    //! Smoke tests for the error code → variant mapping. Each new variant
+    //! added in 0.13.0 (English-elimination work) gets a code() check + a
+    //! Display sanity-check (no English words) + an io::ErrorKind mapping
+    //! check. Without these, future drift between the const codes and the
+    //! match arms in `code()` / the From impl could silently miscategorize.
+    use super::*;
+
+    #[test]
+    fn new_variants_have_distinct_codes() {
+        let codes = [
+            Error::ScsiInterfaceUnavailable { path: "p".into() }.code(),
+            Error::DeviceLocked {
+                path: "p".into(),
+                kr: 0,
+            }
+            .code(),
+            Error::IoKitPluginFailed {
+                path: "p".into(),
+                kr: 0,
+            }
+            .code(),
+            Error::UnsupportedPlatform { target: "x".into() }.code(),
+            Error::PlatformNotImplemented {
+                platform: "renesas".into(),
+            }
+            .code(),
+            Error::MapfileInvalid { kind: "hex" }.code(),
+            Error::DiscUrlNotDirect.code(),
+        ];
+        let mut sorted = codes.to_vec();
+        sorted.sort();
+        sorted.dedup();
+        assert_eq!(
+            sorted.len(),
+            codes.len(),
+            "two new variants share a code — check error.rs constants"
+        );
+    }
+
+    #[test]
+    fn display_emits_no_english_words() {
+        // Every variant's Display must be `E{code}: {data}` — no English.
+        // Sample a few of the new variants and a few existing ones to
+        // catch accidental string-stuffing in future edits.
+        let cases: &[(Error, u16)] = &[
+            (
+                Error::ScsiInterfaceUnavailable {
+                    path: "/dev/sg4".into(),
+                },
+                E_SCSI_INTERFACE_UNAVAILABLE,
+            ),
+            (
+                Error::DeviceLocked {
+                    path: "/dev/sg4".into(),
+                    kr: 0xE00002C5,
+                },
+                E_DEVICE_LOCKED,
+            ),
+            (
+                Error::UnsupportedPlatform {
+                    target: "freebsd".into(),
+                },
+                E_UNSUPPORTED_PLATFORM,
+            ),
+            (
+                Error::PlatformNotImplemented {
+                    platform: "renesas".into(),
+                },
+                E_PLATFORM_NOT_IMPLEMENTED,
+            ),
+            (Error::MapfileInvalid { kind: "hex" }, E_MAPFILE_INVALID),
+            (Error::DiscUrlNotDirect, E_DISC_URL_NOT_DIRECT),
+        ];
+        for (e, want_code) in cases {
+            let s = e.to_string();
+            assert!(
+                s.starts_with(&format!("E{}", want_code)),
+                "{:?} display does not lead with code: {}",
+                e,
+                s
+            );
+            // Crude English filter — `Display` should never emit ASCII words
+            // longer than 4 chars (codes/paths/identifiers like `/dev/sg4`,
+            // `renesas`, `freebsd` all pass; "exclusive access denied" would
+            // not).
+            for word in s.split(|c: char| !c.is_ascii_alphabetic()) {
+                assert!(
+                    word.len() <= 8
+                        || word.eq_ignore_ascii_case("renesas")
+                        || word.eq_ignore_ascii_case("freebsd"),
+                    "Display contains suspicious English-looking word `{word}` in `{s}`"
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn iokind_mapping_for_new_variants() {
+        use std::io::ErrorKind;
+        let mapped = |e: Error| -> ErrorKind {
+            let io: std::io::Error = e.into();
+            io.kind()
+        };
+        // 1xxx range → NotFound
+        assert_eq!(
+            mapped(Error::ScsiInterfaceUnavailable { path: "p".into() }),
+            ErrorKind::NotFound
+        );
+        assert_eq!(
+            mapped(Error::DeviceLocked {
+                path: "p".into(),
+                kr: 0
+            }),
+            ErrorKind::NotFound
+        );
+        // 2xxx range → Unsupported
+        assert_eq!(
+            mapped(Error::UnsupportedPlatform { target: "x".into() }),
+            ErrorKind::Unsupported
+        );
+        assert_eq!(
+            mapped(Error::PlatformNotImplemented {
+                platform: "x".into()
+            }),
+            ErrorKind::Unsupported
+        );
+        // 6xxx range → InvalidData
+        assert_eq!(
+            mapped(Error::MapfileInvalid { kind: "hex" }),
+            ErrorKind::InvalidData
+        );
+        // 9009 special-cased to Unsupported
+        assert_eq!(mapped(Error::DiscUrlNotDirect), ErrorKind::Unsupported);
+    }
+}
@@ -17,6 +17,10 @@ use crate::disc::{DiscTitle, Stream};
 use crate::sector::SectorReader;
 use crate::udf::UdfFs;

+// Re-exported via crate::disc — the public API surfaces these next to
+// AudioStream/SubtitleStream so callers can map purpose/qualifier to display
+// text in their own locale.
+
 /// A stream label extracted from disc config files.
 #[derive(Debug, Clone)]
 #[allow(dead_code)]
@@ -46,7 +50,6 @@ pub enum StreamLabelType {
 }

 #[derive(Debug, Clone, Copy, PartialEq)]
-#[allow(dead_code)]
 pub enum LabelPurpose {
    Normal,
    Commentary,
@@ -99,16 +102,12 @@ pub fn apply(reader: &mut dyn SectorReader, udf: &UdfFs, titles: &mut [DiscTitle
                    if let Some(label) = labels.iter().find(|l| {
                        l.stream_type == StreamLabelType::Audio && l.stream_number == audio_idx
                    }) {
+                        // Structured fields — callers translate purpose to UI text.
+                        a.purpose = label.purpose;
+
+                        // a.label only carries codec/variant info. NEVER any
+                        // English purpose text — the CLI handles that via i18n.
                        let mut parts = Vec::new();
-                        match label.purpose {
-                            LabelPurpose::Commentary => parts.push("Commentary".to_string()),
-                            LabelPurpose::Descriptive => {
-                                parts.push("Descriptive Audio".to_string())
-                            }
-                            LabelPurpose::Score => parts.push("Score".to_string()),
-                            LabelPurpose::Ime => parts.push("IME".to_string()),
-                            LabelPurpose::Normal => {}
-                        }
                        if !label.variant.is_empty() {
                            parts.push(format!("({})", label.variant));
                        }
@@ -117,7 +116,10 @@ pub fn apply(reader: &mut dyn SectorReader, udf: &UdfFs, titles: &mut [DiscTitle
                        }
                        if !parts.is_empty() {
                            a.label = parts.join(" ");
-                        } else if !label.name.is_empty() {
+                        } else if !label.name.is_empty() && label.purpose == LabelPurpose::Normal {
+                            // Only fall back to the parser-supplied display
+                            // name when there's no purpose to flag — the CLI
+                            // handles purpose rendering itself.
                            a.label = label.name.clone();
                        }
                    }
@@ -127,6 +129,7 @@ pub fn apply(reader: &mut dyn SectorReader, udf: &UdfFs, titles: &mut [DiscTitle
                    if let Some(label) = labels.iter().find(|l| {
                        l.stream_type == StreamLabelType::Subtitle && l.stream_number == sub_idx
                    }) {
+                        s.qualifier = label.qualifier;
                        if label.qualifier == LabelQualifier::Forced {
                            s.forced = true;
                        }
@@ -173,9 +176,12 @@ fn generate_video_label(
    use crate::disc::HdrFormat;

    if secondary {
+        // "Dolby Vision EL" is a brand identifier, not English prose, so the
+        // library may emit it. Other "secondary video" wording is a CLI
+        // concern — the library just leaves the label empty.
        return match hdr {
            HdrFormat::DolbyVision => "Dolby Vision EL".to_string(),
-            _ => "Secondary Video".to_string(),
+            _ => String::new(),
        };
    }

@@ -217,11 +223,12 @@ fn generate_video_label(
 fn generate_audio_label(
    codec: &crate::disc::Codec,
    channels: &crate::disc::AudioChannels,
-    secondary: bool,
+    _secondary: bool,
 ) -> String {
    use crate::disc::{AudioChannels, Codec};

-    // Full marketing names for disc audio codecs
+    // Full marketing names for disc audio codecs.
+    // These are codec brand identifiers, not user-facing English prose.
    let codec_name = match codec {
        Codec::TrueHd => "Dolby TrueHD",
        Codec::Ac3 => "Dolby Digital",
@@ -251,12 +258,12 @@ fn generate_audio_label(
        AudioChannels::Unknown => "",
    };

-    let suffix = if secondary { " (Secondary)" } else { "" };
-
+    // The "(Secondary)" suffix is a CLI/UI concern — callers display it from
+    // the AudioStream::secondary bool, not the library.
    if channel_str.is_empty() {
-        format!("{}{}", codec_name, suffix)
+        codec_name.to_string()
    } else {
-        format!("{} {}{}", codec_name, channel_str, suffix)
+        format!("{} {}", codec_name, channel_str)
    }
 }

@@ -94,21 +94,65 @@ pub(crate) mod speed;
 pub(crate) mod udf;
 pub mod verify;

+// ─── Drive lifecycle ────────────────────────────────────────────────────────
+//
+// `Drive::open(path)` → `wait_ready()` → `init()` → `Disc::scan()`. `Drive`
+// owns the SCSI session; `DriveCapture` etc. let advanced callers introspect
+// drive identity / profile data for sharing.
 pub use drive::capture::{
    CapturedFeature, DriveCapture, capture_drive_data, mask_bytes, mask_string,
 };
 pub use drive::{Drive, DriveStatus, find_drive, find_drives};
+
+// ─── Errors ─────────────────────────────────────────────────────────────────
+//
+// All fallible APIs return `Result<T, Error>`. `Error` is a typed enum with a
+// numeric `code()`; **no English text in the library** — applications map
+// codes to localized messages. See `error.rs` for the full taxonomy.
 pub use error::{Error, Result};
+
+// ─── Drive events (low-level callbacks) ─────────────────────────────────────
 pub use event::{Event, EventKind};
 pub use identity::DriveId;
 pub use profile::DriveProfile;
-// Platform trait is pub(crate) -- callers use Drive, not Platform directly
+// Platform trait is pub(crate) — callers use Drive, not Platform directly.
+
+// ─── Decryption (AACS / CSS) ────────────────────────────────────────────────
+//
+// `Disc::scan()` resolves keys and stores them on `Disc`; in most flows you
+// don't touch `DecryptKeys` directly — `DiscStream::new(reader, title, keys, …)`
+// accepts whatever `Disc::decrypt_keys()` returned. `decrypt_sectors()` is
+// for callers that operate on raw sector buffers (e.g. ISO patching).
 pub use decrypt::{DecryptKeys, decrypt_sectors};
+
+// ─── Disc structure ─────────────────────────────────────────────────────────
+//
+// `Disc::scan()` produces a fully-populated `Disc` (titles, streams, AACS
+// state). `Disc::identify()` is the fast path — UDF only, no playlist parse,
+// for displaying disc name + format quickly while a full scan runs in the
+// background. The codec / channel / resolution enums are the canonical
+// structured representation; never compare against display strings.
 pub use disc::{
    AacsState, AudioChannels, AudioStream, Clip, Codec, ColorSpace, ContentFormat, Disc,
-    DiscFormat, DiscId, DiscTitle, Extent, FrameRate, HdrFormat, KeySource, Resolution, SampleRate,
-    ScanOptions, Stream, SubtitleStream, VideoStream,
+    DiscFormat, DiscId, DiscTitle, Extent, FrameRate, HdrFormat, KeySource, LabelPurpose,
+    LabelQualifier, Resolution, SampleRate, ScanOptions, Stream, SubtitleStream, VideoStream,
 };
+
+// ─── Streams ────────────────────────────────────────────────────────────────
+//
+// All stream types implement `pes::Stream` — read PES frames from a source,
+// write PES frames to a sink. Pick the right type at construction:
+//
+// - `DiscStream` — physical drive or ISO (any `SectorReader`). Always read.
+// - `MkvStream`  — Matroska container. Read on `open()`, write on `create()`.
+// - `M2tsStream` — Blu-ray Transport Stream. Read on `open()`, write on `create()`.
+// - `NetworkStream` — TCP. Read on `listen()`, write on `connect()`.
+// - `NullStream` — write-only black-hole sink. Useful for benchmarks.
+// - `StdioStream` — pipe to/from stdin/stdout. Read or write.
+//
+// Most consumers use the URL resolvers (`input()` / `output()`) which pick
+// the right type from a scheme:// URL. Direct construction is for callers
+// that need to wire custom readers (e.g. autorip's drive-session reuse).
 pub use mux::DiscStream;
 pub use mux::M2tsStream;
 pub use mux::MkvStream;
@@ -116,7 +160,14 @@ pub use mux::NetworkStream;
 pub use mux::NullStream;
 pub use mux::StdioStream;
 pub use mux::{InputOptions, StreamUrl, input, output, parse_url};
-pub use scsi::ScsiTransport;
+
+// ─── Lower-level surfaces ───────────────────────────────────────────────────
+//
+// `ScsiTransport` is the platform-abstraction trait Drive uses; expose for
+// out-of-tree platform backends. `SectorReader` lets callers feed any byte
+// source (test harness, network image, SMB share) into the disc scan
+// pipeline; `FileSectorReader` is the standard ISO-on-disk implementation.
+pub use scsi::{DriveInfo, ScsiTransport, drive_has_disc, list_drives};
 pub use sector::{FileSectorReader, SectorReader};
 pub use speed::DriveSpeed;
 pub use udf::{UdfFs, read_filesystem};
@@ -127,6 +127,14 @@ pub struct DiscStream {
    event_fn: Option<Box<dyn Fn(Event) + Send>>,
    eof: bool,

+    // Cumulative bytes successfully read from the source. Drives
+    // EventKind::BytesRead emission and autorip's per-device progress.
+    bytes_read_total: u64,
+    // Pre-computed total of all extents in bytes (or 0 if extents are
+    // empty). Carried in EventKind::BytesRead.total so consumers can show
+    // a percent without a separate API call.
+    bytes_total_extents: u64,
+
    // PES output
    ts_demuxer: Option<super::ts::TsDemuxer>,
    ps_demuxer: Option<super::ps::PsDemuxer>,
@@ -149,6 +157,7 @@ impl DiscStream {
        content_format: crate::disc::ContentFormat,
    ) -> Self {
        let extents = title.extents.clone();
+        let bytes_total_extents: u64 = extents.iter().map(|e| e.sector_count as u64 * 2048).sum();

        let mut pids = Vec::new();
        let mut parsers = Vec::new();
@@ -194,6 +203,8 @@ impl DiscStream {
            halt: None,
            event_fn: None,
            eof: false,
+            bytes_read_total: 0,
+            bytes_total_extents,
            ts_demuxer,
            ps_demuxer,
            parsers,
@@ -287,6 +298,11 @@ impl DiscStream {
                }
                self.buf_valid = bytes;
                self.current_offset += sectors as u32;
+                self.bytes_read_total = self.bytes_read_total.saturating_add(bytes as u64);
+                self.emit(EventKind::BytesRead {
+                    bytes: self.bytes_read_total,
+                    total: self.bytes_total_extents,
+                });
                break;
            }

@@ -87,11 +87,6 @@ pub fn write_uint(w: &mut impl Write, id: u32, val: u64) -> io::Result<()> {
    }
 }

-/// Write a complete EBML signed integer element.
-pub fn write_int(w: &mut impl Write, id: u32, val: i64) -> io::Result<()> {
-    write_uint(w, id, val as u64)
-}
-
 /// Write a complete EBML float element (8-byte double).
 pub fn write_float(w: &mut impl Write, id: u32, val: f64) -> io::Result<()> {
    write_id(w, id)?;
@@ -309,22 +304,6 @@ pub fn read_binary_val(r: &mut impl Read, len: usize) -> io::Result<Vec<u8>> {
    Ok(buf)
 }

-/// Read a VINT (track number) from a SimpleBlock. Returns (value, bytes_consumed).
-pub fn read_vint(r: &mut impl Read) -> io::Result<(u64, usize)> {
-    let mut first = [0u8; 1];
-    r.read_exact(&mut first)?;
-    let b0 = first[0];
-    if b0 & 0x80 != 0 {
-        return Ok(((b0 & 0x7F) as u64, 1));
-    }
-    if b0 & 0x40 != 0 {
-        let mut b = [0u8; 1];
-        r.read_exact(&mut b)?;
-        return Ok(((((b0 & 0x3F) as u64) << 8) | b[0] as u64, 2));
-    }
-    Err(crate::error::Error::MkvInvalid.into())
-}
-
 // ============================================================
 // Matroska Element IDs
 // ============================================================
@@ -342,12 +321,6 @@ pub const EBML_DOC_TYPE_READ_VERSION: u32 = 0x4285;
 // Segment
 pub const SEGMENT: u32 = 0x1853_8067;

-// Seek Head
-pub const SEEK_HEAD: u32 = 0x114D_9B74;
-pub const SEEK: u32 = 0x4DBB;
-pub const SEEK_ID: u32 = 0x53AB;
-pub const SEEK_POSITION: u32 = 0x53AC;
-
 // Segment Info
 pub const INFO: u32 = 0x1549_A966;
 pub const TIMESTAMP_SCALE: u32 = 0x2A_D7B1;
@@ -19,8 +19,7 @@ pub struct IsoSectorReader {

 impl IsoSectorReader {
    pub fn open(path: &str) -> std::io::Result<Self> {
-        let file = File::open(Path::new(path))
-            .map_err(|e| std::io::Error::new(e.kind(), format!("iso://{path}: {e}")))?;
+        let file = File::open(Path::new(path))?;
        let size = file.metadata()?.len();
        let sectors = size / SECTOR_SIZE;
        if sectors > u32::MAX as u64 {
@@ -1,127 +0,0 @@
-//! LookaheadBuffer — generic pre-scan buffer for stream pipelines.
-//!
-//! Accumulates data up to a configurable limit. When the consumer finds
-//! what it needs, the buffer can be drained (fast path, no re-read).
-//! If the buffer fills before the consumer is satisfied, it signals
-//! overflow — the caller should discard and re-read from the source.
-//!
-//! Used by MkvStream to collect SPS/PPS before writing the MKV header.
-//! Reusable for any stream stage that needs to look ahead.
-
-/// Default lookahead buffer size: 5 MB.
-pub const DEFAULT_LOOKAHEAD_SIZE: usize = 5 * 1024 * 1024;
-
-/// Lookahead buffer states.
-#[derive(Debug, Clone, Copy, PartialEq)]
-pub enum LookaheadState {
-    /// Still collecting data, haven't found what we need yet.
-    Collecting,
-    /// Found what we need, buffer has the data ready to drain.
-    Ready,
-    /// Buffer overflowed before finding what we need.
-    /// Caller should discard buffer, finish scanning without buffering,
-    /// then re-read from the source.
-    Overflow,
-}
-
-/// A bounded lookahead buffer.
-pub struct LookaheadBuffer {
-    data: Vec<u8>,
-    max_size: usize,
-    state: LookaheadState,
-}
-
-impl LookaheadBuffer {
-    /// Create a new buffer with the given max size.
-    /// Pass 0 for no buffering (always overflows immediately).
-    pub fn new(max_size: usize) -> Self {
-        Self {
-            data: Vec::with_capacity(max_size.min(DEFAULT_LOOKAHEAD_SIZE)),
-            max_size,
-            state: LookaheadState::Collecting,
-        }
-    }
-
-    /// Push data into the buffer. Returns the new state.
-    /// If the buffer would overflow, transitions to Overflow state.
-    pub fn push(&mut self, chunk: &[u8]) -> LookaheadState {
-        if self.state != LookaheadState::Collecting {
-            return self.state;
-        }
-
-        if self.data.len() + chunk.len() > self.max_size {
-            self.state = LookaheadState::Overflow;
-            return self.state;
-        }
-
-        self.data.extend_from_slice(chunk);
-        self.state
-    }
-
-    /// Mark the buffer as ready — we found what we need.
-    pub fn mark_ready(&mut self) {
-        if self.state == LookaheadState::Collecting {
-            self.state = LookaheadState::Ready;
-        }
-    }
-
-    /// Get the buffered data (only valid in Ready state).
-    pub fn data(&self) -> &[u8] {
-        &self.data
-    }
-
-    /// Take ownership of the buffered data, clearing the buffer.
-    pub fn drain(&mut self) -> Vec<u8> {
-        self.state = LookaheadState::Collecting;
-        std::mem::take(&mut self.data)
-    }
-
-    /// Current state.
-    pub fn state(&self) -> LookaheadState {
-        self.state
-    }
-
-    /// How many bytes are buffered.
-    pub fn len(&self) -> usize {
-        self.data.len()
-    }
-
-    /// Is the buffer empty?
-    pub fn is_empty(&self) -> bool {
-        self.data.is_empty()
-    }
-
-    /// Max size this buffer can hold.
-    pub fn max_size(&self) -> usize {
-        self.max_size
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_basic_flow() {
-        let mut buf = LookaheadBuffer::new(100);
-        assert_eq!(buf.push(b"hello"), LookaheadState::Collecting);
-        assert_eq!(buf.push(b"world"), LookaheadState::Collecting);
-        assert_eq!(buf.len(), 10);
-        buf.mark_ready();
-        assert_eq!(buf.state(), LookaheadState::Ready);
-        assert_eq!(buf.data(), b"helloworld");
-    }
-
-    #[test]
-    fn test_overflow() {
-        let mut buf = LookaheadBuffer::new(5);
-        assert_eq!(buf.push(b"abc"), LookaheadState::Collecting);
-        assert_eq!(buf.push(b"def"), LookaheadState::Overflow);
-    }
-
-    #[test]
-    fn test_zero_size() {
-        let mut buf = LookaheadBuffer::new(0);
-        assert_eq!(buf.push(b"a"), LookaheadState::Overflow);
-    }
-}
@@ -173,6 +173,7 @@ impl M2tsMeta {
                        .parse()
                        .unwrap_or(crate::disc::SampleRate::Unknown),
                    secondary: *secondary,
+                    purpose: crate::disc::LabelPurpose::Normal,
                    label: label.clone(),
                }),
                MetaStream::Subtitle {
@@ -185,6 +186,7 @@ impl M2tsMeta {
                    codec: codec.parse().unwrap_or(crate::disc::Codec::Unknown(0)),
                    language: language.clone(),
                    forced: *forced,
+                    qualifier: crate::disc::LabelQualifier::None,
                    codec_data: None,
                }),
            })
@@ -8,7 +8,7 @@ use super::ebml;
 use crate::disc::{
    AudioStream, Chapter, Codec, ColorSpace, HdrFormat, SubtitleStream, VideoStream,
 };
-use std::io::{self, Seek, SeekFrom, Write};
+use std::io::{self, Seek, Write};

 /// MKV track definition (built from disc stream metadata).
 pub struct MkvTrack {
@@ -170,10 +170,6 @@ pub struct MkvMuxer<W: Write + Seek> {
    base_pts_ms: Option<i64>,
    cues: Vec<CuePoint>,
    frame_count: u64,
-    /// File positions of codecPrivate placeholders (track_idx → offset, max_size).
-    /// Used to seek back and fill in SPS/PPS after first keyframe.
-    codec_private_slots: Vec<Option<(u64, usize)>>,
-    codec_private_filled: Vec<bool>,
 }

 /// New cluster every 5 seconds.
@@ -219,8 +215,6 @@ impl<W: Write + Seek> MkvMuxer<W> {
        ebml::end_master(&mut writer, info_pos)?;

        // Tracks
-        let mut codec_private_slots: Vec<Option<(u64, usize)>> = Vec::new();
-        let mut codec_private_filled: Vec<bool> = Vec::new();
        let tracks_pos = ebml::start_master(&mut writer, ebml::TRACKS)?;
        for (i, track) in tracks.iter().enumerate() {
            let entry_pos = ebml::start_master(&mut writer, ebml::TRACK_ENTRY)?;
@@ -243,20 +237,12 @@ impl<W: Write + Seek> MkvMuxer<W> {

            if let Some(ref cp) = track.codec_private {
                ebml::write_binary(&mut writer, ebml::CODEC_PRIVATE, cp)?;
-                codec_private_slots.push(None); // already filled
-                codec_private_filled.push(true);
-            } else if track.track_type == ebml::TRACK_TYPE_VIDEO {
-                // Reserve space for codecPrivate — will be filled after first keyframe
-                // Reserve 256 bytes (enough for SPS+PPS or VPS+SPS+PPS)
-                let cp_pos = writer.stream_position()?;
-                let placeholder = vec![0u8; 256];
-                ebml::write_binary(&mut writer, ebml::CODEC_PRIVATE, &placeholder)?;
-                codec_private_slots.push(Some((cp_pos, 256)));
-                codec_private_filled.push(false);
-            } else {
-                codec_private_slots.push(None);
-                codec_private_filled.push(true);
            }
+            // Pre-0.13 a deferred codecPrivate path existed for video tracks
+            // (placeholder reserve + later seek-back fill via
+            // `fill_codec_private`). The PES pipeline hands codec_private
+            // up-front via the DiscTitle, so the deferred path was never
+            // exercised — removed in the 0.13 dead-code sweep.

            // DefaultDuration — frame duration in nanoseconds
            if track.default_duration_ns > 0 {
@@ -344,8 +330,6 @@ impl<W: Write + Seek> MkvMuxer<W> {
            base_pts_ms: None,
            cues: Vec::new(),
            frame_count: 0,
-            codec_private_slots,
-            codec_private_filled,
        })
    }

@@ -415,30 +399,6 @@ impl<W: Write + Seek> MkvMuxer<W> {
        Ok(())
    }

-    /// Fill in a deferred codecPrivate for a track.
-    /// Seeks back to the placeholder, writes the actual data, restores position.
-    pub fn fill_codec_private(&mut self, track_idx: usize, data: &[u8]) -> io::Result<()> {
-        if track_idx >= self.codec_private_filled.len() || self.codec_private_filled[track_idx] {
-            return Ok(());
-        }
-        if let Some((pos, max_size)) = self.codec_private_slots[track_idx] {
-            if data.len() > max_size {
-                // Data too large for reserved space — can't fill in place
-                // This shouldn't happen with 256 bytes reserved
-                return Ok(());
-            }
-            let current = self.writer.stream_position()?;
-            self.writer.seek(SeekFrom::Start(pos))?;
-            // Rewrite: element ID + size + data + zero-pad remainder
-            let mut padded = data.to_vec();
-            padded.resize(max_size, 0);
-            ebml::write_binary(&mut self.writer, ebml::CODEC_PRIVATE, &padded)?;
-            self.writer.seek(SeekFrom::Start(current))?;
-            self.codec_private_filled[track_idx] = true;
-        }
-        Ok(())
-    }
-
    fn start_cluster(&mut self, ts_ms: i64) -> io::Result<()> {
        // Close previous cluster if open
        if self.cluster_open {
@@ -810,6 +770,7 @@ mod tests {
            codec: Codec::Pgs,
            language: "eng".into(),
            forced: true,
+            qualifier: crate::disc::LabelQualifier::Forced,
            codec_data: None,
        });
        assert!(forced_sub.is_forced);
@@ -835,6 +796,7 @@ mod tests {
            codec: Codec::Pgs,
            language: "eng".into(),
            forced: false,
+            qualifier: crate::disc::LabelQualifier::None,
            codec_data: None,
        });
        assert!(!sub.is_forced);
@@ -380,6 +380,7 @@ fn parse_track(
            language: lang,
            sample_rate: srs,
            secondary: false,
+            purpose: crate::disc::LabelPurpose::Normal,
            label: name,
        })),
        17 => Some(crate::disc::Stream::Subtitle(SubtitleStream {
@@ -387,6 +388,7 @@ fn parse_track(
            codec,
            language: lang,
            forced,
+            qualifier: crate::disc::LabelQualifier::None,
            codec_data: None,
        })),
        _ => None,
@@ -15,22 +15,32 @@
 //!
 //! For disc→ISO (raw sector copy), use `Disc::copy()` instead.

+// Public modules — types here are intentionally part of the consumable API.
 pub mod codec;
 pub mod disc;
-pub mod ebml;
 pub mod iso;
-mod m2ts;
-pub mod meta;
-pub mod mkv;
-mod mkvstream;
-pub mod network;
-pub mod null;
-pub mod ps;
 pub mod resolve;
-pub mod stdio;
-pub mod ts;
-pub mod tsmux;
-pub mod tsreader;
+
+// Internal modules — implementation details. Their *types* are re-exported
+// where appropriate (`MkvStream`, `M2tsStream`, etc. surface from `lib.rs`),
+// but the module paths themselves are not part of the API. Pre-0.13 these
+// were `pub`, leaking low-level EBML primitives, TS muxer internals, and
+// network/stdio implementations that no external caller had business
+// reaching for.
+pub(crate) mod ebml;
+pub(crate) mod m2ts;
+/// FMKV metadata header (used by `M2tsStream` / `NetworkStream` / `StdioStream`
+/// to round-trip codec_privates that don't fit inside the underlying format).
+/// Exposed for integration tests that exercise the wire format directly.
+pub mod meta;
+pub(crate) mod mkv;
+pub(crate) mod mkvstream;
+pub(crate) mod network;
+pub(crate) mod null;
+pub(crate) mod ps;
+pub(crate) mod stdio;
+pub(crate) mod ts;
+pub(crate) mod tsmux;

 pub use disc::DiscStream;
 pub use iso::IsoSectorReader;
@@ -43,6 +53,13 @@ pub use stdio::StdioStream;

 use std::io::{Seek, Write};

-// WriteSeek — used internally by MKV muxer (container format requires seeking).
+/// Combined `Write + Seek` for sinks accepted by the MKV muxer.
+///
+/// Matroska's `SeekHead`, `Cues`, and `Cluster` size fields are written with
+/// placeholder values during streaming and updated in-place at finalization,
+/// so the output sink must support seeking. Provided as a single trait
+/// alias so callers don't have to repeat `Write + Seek` everywhere; the
+/// blanket impl below opts every `T: Write + Seek` in automatically
+/// (`File`, `BufWriter<File>`, `Cursor<Vec<u8>>`).
 pub trait WriteSeek: Write + Seek {}
 impl<T: Write + Seek> WriteSeek for T {}
@@ -144,6 +144,7 @@ mod tests {
                    language: "eng".into(),
                    sample_rate: SampleRate::S48,
                    secondary: false,
+                    purpose: crate::disc::LabelPurpose::Normal,
                    label: "English".into(),
                }),
            ],
@@ -171,17 +171,18 @@ pub fn input(url: &str, opts: &InputOptions) -> io::Result<Box<dyn crate::pes::S
    let parsed = parse_url(url);
    match parsed {
        StreamUrl::Disc { .. } => {
-            // Disc sources should use DiscStream::new() directly.
-            // The caller opens the drive, inits, scans, then creates the stream.
-            Err(io::Error::new(
-                io::ErrorKind::Unsupported,
-                "Use Drive::open() + Disc::scan() + DiscStream::new() for disc sources",
-            ))
+            // Disc sources require live SCSI state — caller must use
+            // `Drive::open() + Disc::scan() + DiscStream::new()` directly.
+            // Surfaced as a typed error (no English commentary in the
+            // library; the CLI/UI explains the right entry point).
+            Err(crate::error::Error::DiscUrlNotDirect.into())
        }
        StreamUrl::Iso { ref path } => {
            validate_file_path(path, "iso")?;
            let scan_opts = match &opts.keydb_path {
-                Some(p) => crate::disc::ScanOptions::with_keydb(p),
+                Some(p) => crate::disc::ScanOptions {
+                    keydb_path: Some(p.into()),
+                },
                None => crate::disc::ScanOptions::default(),
            };
            let mut reader = super::iso::IsoSectorReader::open(&path.to_string_lossy())?;
@@ -210,17 +211,13 @@ pub fn input(url: &str, opts: &InputOptions) -> io::Result<Box<dyn crate::pes::S
        }
        StreamUrl::M2ts { ref path } => {
            validate_file_path(path, "m2ts")?;
-            let file = std::fs::File::open(path).map_err(|e| {
-                io::Error::new(e.kind(), format!("m2ts://{}: {}", path.display(), e))
-            })?;
+            let file = std::fs::File::open(path)?;
            let reader = std::io::BufReader::with_capacity(IO_BUF_SIZE, file);
            Ok(Box::new(M2tsStream::open(reader)?))
        }
        StreamUrl::Mkv { ref path } => {
            validate_file_path(path, "mkv")?;
-            let file = std::fs::File::open(path).map_err(|e| {
-                io::Error::new(e.kind(), format!("mkv://{}: {}", path.display(), e))
-            })?;
+            let file = std::fs::File::open(path)?;
            let reader = std::io::BufReader::with_capacity(IO_BUF_SIZE, file);
            Ok(Box::new(MkvStream::open(reader)?))
        }
@@ -245,18 +242,14 @@ pub fn output(
    match parsed {
        StreamUrl::Mkv { ref path } => {
            validate_file_path(path, "mkv")?;
-            let file = std::fs::File::create(path).map_err(|e| {
-                io::Error::new(e.kind(), format!("mkv://{}: {}", path.display(), e))
-            })?;
+            let file = std::fs::File::create(path)?;
            let writer: Box<dyn super::WriteSeek> =
                Box::new(std::io::BufWriter::with_capacity(IO_BUF_SIZE, file));
            Ok(Box::new(MkvStream::create(writer, title)?))
        }
        StreamUrl::M2ts { ref path } => {
            validate_file_path(path, "m2ts")?;
-            let file = std::fs::File::create(path).map_err(|e| {
-                io::Error::new(e.kind(), format!("m2ts://{}: {}", path.display(), e))
-            })?;
+            let file = std::fs::File::create(path)?;
            let writer = std::io::BufWriter::with_capacity(IO_BUF_SIZE, file);
            Ok(Box::new(M2tsStream::create(writer, title)?))
        }
@@ -15,12 +15,6 @@ const TS_PACKET_SIZE: usize = 188;
 /// TS sync byte.
 const SYNC_BYTE: u8 = 0x47;

-/// Size of head buffer for PTS/stream scanning (1 MB).
-const SCAN_HEAD_SIZE: usize = 1024 * 1024;
-
-/// Size of tail buffer for last-PTS scanning (2 MB).
-const SCAN_TAIL_SIZE: usize = 2 * 1024 * 1024;
-
 /// A reassembled PES packet with timestamp info.
 #[derive(Debug)]
 pub struct PesPacket {
@@ -104,19 +98,16 @@ pub struct TsDemuxer {
 }

 impl TsDemuxer {
-    /// Take the remainder bytes (leftover from last feed() that didn't
-    /// align to a 192-byte packet boundary).
-    pub fn take_remainder(&mut self) -> Vec<u8> {
-        std::mem::take(&mut self.remainder)
-    }
-
-    /// Set the remainder bytes. Used to transfer alignment state from
-    /// one demuxer to another without losing sync.
-    pub fn set_remainder(&mut self, data: Vec<u8>) {
-        self.remainder = data;
-    }
-
    /// Create a new demuxer tracking the given PIDs.
+    ///
+    /// Allocates a flat lookup table of `i16` slots — one per possible PID
+    /// up to `max(8192, max_pid + 1)`. The 8192 floor matches the BD-TS
+    /// 13-bit PID space (0..0x1FFF); the variable upper bound exists for
+    /// DVD program streams which may use 16-bit stream IDs above 8191.
+    /// Worst-case allocation is `u16::MAX × 2 bytes ≈ 128 KB` — bounded by
+    /// the type, so adversarial input can't drive this beyond predictable
+    /// limits. Empty `pids` yields max_pid 0; the floor still produces a
+    /// valid (wholly-unused) table.
    pub fn new(pids: &[u16]) -> Self {
        let max_pid = pids.iter().copied().max().unwrap_or(0) as usize;
        let table_size = (max_pid + 1).max(8192);
@@ -446,6 +437,7 @@ pub fn scan_streams(data: &[u8]) -> Option<Vec<crate::disc::Stream>> {
                        language: "und".into(),
                        sample_rate: SampleRate::S48,
                        secondary: false,
+                        purpose: crate::disc::LabelPurpose::Normal,
                        label: String::new(),
                    })),
                    0x83 => Some(Stream::Audio(AudioStream {
@@ -455,6 +447,7 @@ pub fn scan_streams(data: &[u8]) -> Option<Vec<crate::disc::Stream>> {
                        language: "und".into(),
                        sample_rate: SampleRate::S48,
                        secondary: false,
+                        purpose: crate::disc::LabelPurpose::Normal,
                        label: String::new(),
                    })),
                    0x84 | 0xA1 => Some(Stream::Audio(AudioStream {
@@ -464,6 +457,7 @@ pub fn scan_streams(data: &[u8]) -> Option<Vec<crate::disc::Stream>> {
                        language: "und".into(),
                        sample_rate: SampleRate::S48,
                        secondary: false,
+                        purpose: crate::disc::LabelPurpose::Normal,
                        label: String::new(),
                    })),
                    0x85 | 0x86 => Some(Stream::Audio(AudioStream {
@@ -473,6 +467,7 @@ pub fn scan_streams(data: &[u8]) -> Option<Vec<crate::disc::Stream>> {
                        language: "und".into(),
                        sample_rate: SampleRate::S48,
                        secondary: false,
+                        purpose: crate::disc::LabelPurpose::Normal,
                        label: String::new(),
                    })),
                    0x82 => Some(Stream::Audio(AudioStream {
@@ -482,6 +477,7 @@ pub fn scan_streams(data: &[u8]) -> Option<Vec<crate::disc::Stream>> {
                        language: "und".into(),
                        sample_rate: SampleRate::S48,
                        secondary: false,
+                        purpose: crate::disc::LabelPurpose::Normal,
                        label: String::new(),
                    })),
                    0x90 => Some(Stream::Subtitle(SubtitleStream {
@@ -489,6 +485,7 @@ pub fn scan_streams(data: &[u8]) -> Option<Vec<crate::disc::Stream>> {
                        codec: Codec::Pgs,
                        language: "und".into(),
                        forced: false,
+                        qualifier: crate::disc::LabelQualifier::None,
                        codec_data: None,
                    })),
                    _ => None,
@@ -511,103 +508,6 @@ pub fn scan_streams(data: &[u8]) -> Option<Vec<crate::disc::Stream>> {
    }
 }

-// ============================================================
-// PTS scanning utilities (for duration detection)
-// ============================================================
-
-/// Find the first PTS for a given PID in BD-TS data.
-pub fn scan_first_pts(data: &[u8], target_pid: u16) -> Option<i64> {
-    let mut offset = 0;
-    while offset + BD_TS_PACKET_SIZE <= data.len() {
-        if data[offset + 4] != SYNC_BYTE {
-            offset += 1;
-            continue;
-        }
-        let pid = (((data[offset + 5] & 0x1F) as u16) << 8) | data[offset + 6] as u16;
-        let pusi = data[offset + 5] & 0x40 != 0;
-        if pid == target_pid && pusi {
-            let ts = &data[offset + 4..offset + BD_TS_PACKET_SIZE];
-            let afc = (ts[3] >> 4) & 0x03;
-            let payload_start = if afc == 3 { 5 + ts[4] as usize } else { 4 };
-            if payload_start < TS_PACKET_SIZE {
-                let payload = &ts[payload_start..];
-                if payload.len() >= 14 && payload[0] == 0 && payload[1] == 0 && payload[2] == 1 {
-                    let pts_dts_flags = (payload[7] >> 6) & 0x03;
-                    if pts_dts_flags >= 2 {
-                        return parse_timestamp(&payload[9..14]);
-                    }
-                }
-            }
-        }
-        offset += BD_TS_PACKET_SIZE;
-    }
-    None
-}
-
-/// Find the last PTS for a given PID in BD-TS data.
-pub fn scan_last_pts(data: &[u8], target_pid: u16) -> Option<i64> {
-    let mut last_pts = None;
-    let mut offset = 0;
-    while offset + BD_TS_PACKET_SIZE <= data.len() {
-        if data[offset + 4] != SYNC_BYTE {
-            offset += 1;
-            continue;
-        }
-        let pid = (((data[offset + 5] & 0x1F) as u16) << 8) | data[offset + 6] as u16;
-        let pusi = data[offset + 5] & 0x40 != 0;
-        if pid == target_pid && pusi {
-            let ts = &data[offset + 4..offset + BD_TS_PACKET_SIZE];
-            let afc = (ts[3] >> 4) & 0x03;
-            let payload_start = if afc == 3 { 5 + ts[4] as usize } else { 4 };
-            if payload_start < TS_PACKET_SIZE {
-                let payload = &ts[payload_start..];
-                if payload.len() >= 14 && payload[0] == 0 && payload[1] == 0 && payload[2] == 1 {
-                    let pts_dts_flags = (payload[7] >> 6) & 0x03;
-                    if pts_dts_flags >= 2 {
-                        last_pts = parse_timestamp(&payload[9..14]);
-                    }
-                }
-            }
-        }
-        offset += BD_TS_PACKET_SIZE;
-    }
-    last_pts
-}
-
-/// Scan an m2ts file for duration by reading first and last PTS.
-/// Returns duration in seconds, or None if PTS cannot be found.
-/// The reader position is restored after scanning.
-pub fn scan_duration<R: std::io::Read + std::io::Seek>(r: &mut R, video_pid: u16) -> Option<f64> {
-    use std::io::SeekFrom;
-
-    let start_pos = r.stream_position().ok()?;
-
-    // Read first 1MB for first PTS
-    let mut head_buf = vec![0u8; SCAN_HEAD_SIZE];
-    r.seek(SeekFrom::Start(0)).ok()?;
-    let head_n = r.read(&mut head_buf).ok()?;
-    let first_pts = scan_first_pts(&head_buf[..head_n], video_pid)?;
-
-    // Read last 2MB for last PTS (aligned to 192-byte boundary)
-    let file_size = r.seek(SeekFrom::End(0)).ok()?;
-    let tail_size: u64 = SCAN_TAIL_SIZE as u64;
-    let raw_pos = file_size.saturating_sub(tail_size);
-    let seek_pos = (raw_pos / BD_TS_PACKET_SIZE as u64) * BD_TS_PACKET_SIZE as u64;
-    r.seek(SeekFrom::Start(seek_pos)).ok()?;
-    let mut tail_buf = vec![0u8; tail_size as usize];
-    let tail_n = r.read(&mut tail_buf).ok()?;
-    let last_pts = scan_last_pts(&tail_buf[..tail_n], video_pid)?;
-
-    // Restore reader position
-    let _ = r.seek(SeekFrom::Start(start_pos));
-
-    if last_pts > first_pts {
-        Some((last_pts - first_pts) as f64 / 90000.0)
-    } else {
-        None
-    }
-}
-
 #[cfg(test)]
 mod tests {
    use super::*;
@@ -1,115 +0,0 @@
-//! TsDemuxReader — reads from any source, demuxes BD-TS, produces PES frames.
-//!
-//! Wraps any Read source with a TsDemuxer + CodecParsers.
-//! One implementation used by M2TS, Network, Stdio, and any other BD-TS input.
-
-use super::codec::{self, CodecParser};
-use super::ts::TsDemuxer;
-use crate::disc::Stream as DiscStream;
-use crate::pes::PesFrame;
-use std::collections::VecDeque;
-use std::io::{self, Read};
-
-const READ_BUF_SIZE: usize = 192 * 1024; // 1024 BD-TS packets
-
-/// Generic BD-TS → PES frame reader.
-pub struct TsDemuxReader<R: Read> {
-    reader: R,
-    demuxer: TsDemuxer,
-    parsers: Vec<(u16, Box<dyn CodecParser>)>,
-    pid_to_track: Vec<(u16, usize)>,
-    pending: VecDeque<PesFrame>,
-    buf: Vec<u8>,
-    eof: bool,
-}
-
-impl<R: Read> TsDemuxReader<R> {
-    /// Create from a reader and stream metadata.
-    pub fn new(reader: R, streams: &[DiscStream]) -> Self {
-        let mut pids = Vec::new();
-        let mut parsers: Vec<(u16, Box<dyn CodecParser>)> = Vec::new();
-        let mut pid_to_track = Vec::new();
-        for (i, s) in streams.iter().enumerate() {
-            let (pid, c) = match s {
-                DiscStream::Video(v) => (v.pid, v.codec),
-                DiscStream::Audio(a) => (a.pid, a.codec),
-                DiscStream::Subtitle(s) => (s.pid, s.codec),
-            };
-            pids.push(pid);
-            pid_to_track.push((pid, i));
-            parsers.push((pid, codec::parser_for_codec(c, None)));
-        }
-
-        Self {
-            reader,
-            demuxer: TsDemuxer::new(&pids),
-            parsers,
-            pid_to_track,
-            pending: VecDeque::new(),
-            buf: vec![0u8; READ_BUF_SIZE],
-            eof: false,
-        }
-    }
-
-    /// Get the next PES frame. Returns None at EOF.
-    pub fn next_frame(&mut self) -> io::Result<Option<PesFrame>> {
-        if let Some(frame) = self.pending.pop_front() {
-            return Ok(Some(frame));
-        }
-        if self.eof {
-            return Ok(None);
-        }
-
-        loop {
-            let n = self.reader.read(&mut self.buf)?;
-            if n == 0 {
-                self.eof = true;
-                return Ok(None);
-            }
-
-            let packets = self.demuxer.feed(&self.buf[..n]);
-            for pes in &packets {
-                if let Some((_, track)) = self.pid_to_track.iter().find(|(pid, _)| *pid == pes.pid)
-                {
-                    if let Some((_, parser)) =
-                        self.parsers.iter_mut().find(|(pid, _)| *pid == pes.pid)
-                    {
-                        for frame in parser.parse(pes) {
-                            self.pending
-                                .push_back(PesFrame::from_codec_frame(*track, frame));
-                        }
-                    }
-                }
-            }
-
-            if let Some(frame) = self.pending.pop_front() {
-                return Ok(Some(frame));
-            }
-        }
-    }
-
-    /// Codec private data for a track.
-    pub fn codec_private(&self, track: usize) -> Option<Vec<u8>> {
-        let pid = self
-            .pid_to_track
-            .iter()
-            .find(|(_, idx)| *idx == track)
-            .map(|(pid, _)| *pid)?;
-        self.parsers
-            .iter()
-            .find(|(p, _)| *p == pid)
-            .and_then(|(_, parser)| parser.codec_private())
-    }
-
-    /// True when all primary video tracks have codec_private.
-    pub fn headers_ready(&self, streams: &[DiscStream]) -> bool {
-        for (idx, s) in streams.iter().enumerate() {
-            if let DiscStream::Video(v) = s {
-                if !v.secondary && self.codec_private(idx).is_none() {
-                    return false;
-                }
-            }
-        }
-        true
-    }
-}
@@ -78,26 +78,63 @@ impl PesFrame {
    }
 }

-/// A stream. Read from it or write to it. Not both.
+/// A PES frame source or sink. Each implementor is **either** read-only or
+/// write-only — never both.
+///
+/// Implementors fall into two camps:
+///
+/// - **Read sources**: `DiscStream` (drive or ISO), `M2tsStream` (when
+///   constructed from an existing file), `MkvStream` (demux), `NetworkStream`
+///   (TCP listener), `StdioStream::input()`. These return frames from
+///   `read()` and surface `StreamWriteOnly` (E9001) from `write()`.
+/// - **Write sinks**: `MkvStream::create`, `M2tsStream::create`,
+///   `NetworkStream::connect`, `StdioStream::output()`, `NullStream`.
+///   These accept frames in `write()` and surface `StreamReadOnly` (E9000)
+///   from `read()`. Always call `finish()` when done — that's where MKV
+///   writes its `Cues` index and `M2tsStream` flushes the TS muxer.
+///
+/// Direction is established at construction; mixing produces an error code,
+/// not a panic. Most consumers don't construct streams directly — call
+/// `mux::input(url, opts)` / `mux::output(url, title)` and let URL parsing
+/// pick the right type.
+///
+/// `info()` returns the stream's `DiscTitle` metadata (track list, codec
+/// info, duration). For sources it's parsed from the input; for sinks it's
+/// the metadata supplied at creation. Stable across all reads.
+///
+/// `codec_private(track)` exposes per-track initialization data
+/// (H.264 SPS/PPS, HEVC VPS/SPS/PPS, AC-3 fscod, etc.) that some output
+/// formats need before any frame can be written. `headers_ready()` returns
+/// false until enough input frames have been seen to populate every video
+/// track's codec-private blob — callers buffer frames they read until
+/// `headers_ready()` returns true.
 pub trait Stream {
-    /// Read the next frame. Returns None at end of stream.
+    /// Read the next frame, or `Ok(None)` at end of stream. Returns
+    /// `StreamWriteOnly` (E9001) on a write-only sink.
    fn read(&mut self) -> std::io::Result<Option<PesFrame>>;

-    /// Write a frame.
+    /// Write a frame to the sink. Returns `StreamReadOnly` (E9000) on a
+    /// read-only source.
    fn write(&mut self, frame: &PesFrame) -> std::io::Result<()>;

-    /// Finalize (flush, write index, close).
+    /// Finalize the stream: flush buffered frames, write any container
+    /// index (MKV `Cues`), close the underlying file/socket. Idempotent
+    /// for read-only streams (no-op).
    fn finish(&mut self) -> std::io::Result<()>;

-    /// Stream metadata.
+    /// Stream metadata. Stable across reads — implementors must return a
+    /// consistent reference for the lifetime of the stream.
    fn info(&self) -> &crate::disc::DiscTitle;

-    /// Codec initialization data for a track (SPS/PPS, etc).
+    /// Codec initialization data for a track (SPS/PPS, AC-3 fscod, etc.).
+    /// `None` for tracks that don't need codec_private (raw passthrough).
    fn codec_private(&self, _track: usize) -> Option<Vec<u8>> {
        None
    }

-    /// True when codec_private is available for all video tracks.
+    /// True when `codec_private` is available for every video track —
+    /// callers buffer input frames until this flips, since some output
+    /// formats (MKV) can't write frames without codec init data.
    fn headers_ready(&self) -> bool {
        true
    }
@@ -12,8 +12,6 @@ use crate::error::{Error, Result};
 use std::path::Path;

 const SG_IO: u32 = 0x2285;
-const SG_SCSI_RESET: u32 = 0x2284;
-const SG_SCSI_RESET_DEVICE: i32 = 1;
 const SG_DXFER_NONE: i32 = -1;
 const SG_DXFER_TO_DEV: i32 = -2;
 const SG_DXFER_FROM_DEV: i32 = -3;
@@ -80,49 +78,32 @@ impl SgIoTransport {
        })
    }

-    /// Reset the drive to a known good state — equivalent to unplug/replug.
-    /// After reset, the drive is clean and no fd is held open.
+    /// Clean up kernel SG_IO state and unlock the tray. NOT a hardware
+    /// reset — purely software cleanup before this process opens the
+    /// device for real work.
    ///
-    /// ## Why each step exists
+    /// When a previous process is killed (SIGKILL) mid-SG_IO, the kernel
+    /// may hold queued commands against the dead fd, and `Drop` never
+    /// ran so the tray may still be locked via PREVENT MEDIUM REMOVAL.
+    /// This routine handles both: open + close flushes the kernel SG
+    /// queue (sg_release cancels commands tied to the fd), the 2 s sleep
+    /// gives the kernel time to finish that cleanup, then a fresh fd
+    /// sends ALLOW MEDIUM REMOVAL to clear any stale tray lock.
    ///
-    /// When a process is killed (SIGKILL/kill -9) mid-SG_IO ioctl, two things
-    /// go wrong: (1) the kernel's SG driver may have stale pending commands
-    /// queued for the dead process's fd, and (2) the drive firmware may still
-    /// be mid-operation (seeking, reading, processing a vendor command).
-    ///
-    /// A new process opening the same /dev/sg* device gets a fresh fd, but the
-    /// kernel doesn't automatically abort the dead process's commands — the
-    /// drive can appear hung on the first SCSI command.
-    ///
-    /// Additionally, killed processes skip Drop, so the tray may be locked
-    /// via PREVENT MEDIUM REMOVAL with no process alive to unlock it.
-    ///
-    /// ## Sequence
-    ///
-    /// 1. **open** — allocates kernel SG state for this fd
-    /// 2. **close** — triggers kernel cleanup: aborts any pending SG_IO
-    ///    commands associated with this fd. The key operation —
-    ///    the kernel's sg_release() cancels queued commands.
-    /// 3. **sleep 2s** — the drive firmware needs time to finish/abort whatever
-    ///    it was doing when the previous process died. Without
-    ///    this, the next command may block on drive-internal state.
-    /// 4. **open** — fresh fd with no stale commands in the kernel queue
-    /// 5. **unlock** — ALLOW MEDIUM REMOVAL (CDB 0x1E, prevent=0). Clears
-    ///    any tray lock left by a killed process that never
-    ///    ran its Drop/cleanup.
-    /// 6. **TUR** — TEST UNIT READY (CDB 0x00) with 3s timeout. If the
-    ///    drive responds, it's in a good state.
-    /// 7. **escalate** — if TUR fails:
-    ///    - SG_SCSI_RESET (device level) — kernel sends a SCSI
-    ///      bus reset to the device, clearing all firmware state.
-    ///    - STOP + START UNIT (CDB 0x1B) — power-cycles the
-    ///      drive's logical unit, like pressing the eject button
-    ///      and reinserting.
-    /// 8. **close** — release the fd. Drive is clean, nobody holds it.
+    /// We do NOT verify the drive with TUR or escalate to SG_SCSI_RESET /
+    /// STOP+START UNIT. Both escalations 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 — see
+    /// (internal)/postmortems/2026-04-25-bu40n-wedge-recovery.md.
+    /// If the drive is genuinely unresponsive, the next workload command
+    /// fails naturally and the caller surfaces a "physical reconnect
+    /// required" prompt. Software has no path back from a wedged Initio
+    /// bridge — only physical replug clears it.
    pub fn reset(device: &Path) -> Result<()> {
        let c_path = Self::to_c_path(device);

-        // Step 1-2: open + close — flush stale kernel SG_IO state
+        // open + close — make the kernel cancel any SG_IO commands queued
+        // against a previous fd that didn't close cleanly.
        let probe_fd = unsafe {
            libc::open(
                c_path.as_ptr() as *const libc::c_char,
@@ -133,10 +114,10 @@ impl SgIoTransport {
            unsafe { libc::close(probe_fd) };
        }

-        // Step 3: let drive settle
+        // Let the kernel finish that cancellation before we reopen.
        std::thread::sleep(std::time::Duration::from_secs(2));

-        // Step 4: open clean fd
+        // Fresh fd just to send the unlock command, then close.
        let fd = unsafe {
            libc::open(
                c_path.as_ptr() as *const libc::c_char,
@@ -147,27 +128,10 @@ impl SgIoTransport {
            return Self::open_error(device);
        }

-        // Step 5: unlock tray
+        // ALLOW MEDIUM REMOVAL — clear any tray lock left by a killed
+        // process whose Drop never ran. Best-effort; ignore result.
        let _ = Self::raw_command(fd, &[0x1E, 0, 0, 0, 0, 0], 3_000);

-        // Step 6: TUR — if drive responds, we're done
-        if Self::raw_command(fd, &[0, 0, 0, 0, 0, 0], 3_000).is_err() {
-            // Step 7: escalate — SG_SCSI_RESET
-            let mut reset_type: i32 = SG_SCSI_RESET_DEVICE;
-            unsafe { libc::ioctl(fd, SG_SCSI_RESET as _, &mut reset_type) };
-            std::thread::sleep(std::time::Duration::from_secs(3));
-
-            if Self::raw_command(fd, &[0, 0, 0, 0, 0, 0], 3_000).is_err() {
-                // STOP + START
-                let _ = Self::raw_command(fd, &[0x1B, 0, 0, 0, 0x00, 0], 3_000);
-                std::thread::sleep(std::time::Duration::from_secs(1));
-                let _ = Self::raw_command(fd, &[0x1B, 0, 0, 0, 0x01, 0], 3_000);
-                std::thread::sleep(std::time::Duration::from_secs(3));
-                let _ = Self::raw_command(fd, &[0, 0, 0, 0, 0, 0], 3_000);
-            }
-        }
-
-        // Step 8: close — drive is clean
        unsafe { libc::close(fd) };
        Ok(())
    }
@@ -357,26 +321,38 @@ impl ScsiTransport for SgIoTransport {

        if pr <= 0 {
            // Timeout (0) or fatal poll error (-1).
-            // Command is still pending in the kernel. Abandon this fd and
-            // open a fresh one. The old fd is closed in a background thread
-            // because close() blocks until the kernel completes/aborts the
-            // pending command.
+            // Command is still pending in the kernel. Abandon the fd by
+            // spawning a background close (which will block until the
+            // kernel completes/aborts the pending command), and mark
+            // this transport invalid by setting `self.fd = -1`.
+            //
+            // Why we no longer reopen on the main thread: opening the
+            // SAME /dev/sg* device while the prior fd is mid-close
+            // serializes via the kernel's per-device state lock, so
+            // `libc::open()` on the main thread blocks for the same
+            // duration that close() does — defeating the userspace
+            // timeout. Observed in v0.13.8 live test on Dune 2: each
+            // timed-out read added 60+ s to the next iteration of
+            // Disc::copy, leaving the rip stuck without surfacing an
+            // error or wedging the drive.
+            //
+            // Net effect of the fix: a single read timeout invalidates
+            // the SgIoTransport. The Drive is now "dead" until the
+            // consumer (autorip's rip thread) catches the failure and
+            // reopens. Disc::copy's `skip_on_error=true` path will see
+            // the Err and skip-forward, advancing pos, and the next
+            // read on this fd returns Err(DeviceNotFound) immediately —
+            // which Disc::copy continues to skip-forward through until
+            // the NonTried region is exhausted. Pass 1 then ends with
+            // bytes_pending > 0 and the rip thread reopens the Drive
+            // for Pass 2 (Disc::patch with recovery=true and 30 s
+            // timeouts).
            let old_fd = self.fd;
            self.fd = -1;
-
            std::thread::spawn(move || {
                unsafe { libc::close(old_fd) };
            });

-            let c_path = Self::to_c_path(&self.device_path);
-            let new_fd = unsafe {
-                libc::open(
-                    c_path.as_ptr() as *const libc::c_char,
-                    libc::O_RDWR | libc::O_NONBLOCK | libc::O_CLOEXEC,
-                )
-            };
-            self.fd = if new_fd >= 0 { new_fd } else { -1 };
-
            return Err(Error::ScsiError {
                opcode: cdb[0],
                status: 0xFF,
@@ -427,3 +403,187 @@ impl ScsiTransport for SgIoTransport {
        })
    }
 }
+
+// ── Lightweight discovery + presence (Linux) ────────────────────────────────
+//
+// `list_drives` walks `/sys/class/scsi_generic/`, filters to type-5 (CD/DVD/BD),
+// and runs one INQUIRY each for vendor/model/firmware. Falls back to a
+// `/dev/sg0..15` probe when sysfs is unreadable (minimal containers).
+//
+// `drive_has_disc` issues a single TEST UNIT READY. On the wedge signature
+// (kernel returns status `0xff` with no sense) it escalates: SCSI bus reset
+// → if still wedged → USB device reset (`USBDEVFS_RESET`) → retry TUR.
+// Callers never see the escalation; if it fails too, surface
+// `DeviceResetFailed` so the caller can back off.
+
+/// SCSI peripheral type 5 = "CD-ROM device" (covers DVD, BD-ROM, BD-RE, etc.).
+/// Stored in `/sys/class/scsi_generic/sgN/device/type` as ASCII decimal.
+const SCSI_TYPE_OPTICAL: &str = "5";
+
+/// SCSI sense key 2 = "NOT READY". Sub-codes distinguish "medium not present"
+/// (no disc) from other not-ready states (loading, etc.); for poll-loop
+/// purposes any sense-key 2 means "no disc to act on".
+const SENSE_KEY_NOT_READY: u8 = 2;
+
+/// Maximum sg index probed in the fallback path when sysfs is unavailable.
+/// Linux assigns `/dev/sgN` sequentially per host adapter; 16 covers any
+/// realistic homelab (typical PERC + USB optical = ≤8 nodes).
+const SG_FALLBACK_MAX: u8 = 16;
+
+// SCSI INQUIRY field-offset constants previously lived here. They were
+// used by an in-process SCSI INQUIRY parse path that 0.13.6 retired in
+// favour of reading the kernel-cached sysfs identity (vendor/model/rev
+// under /sys/class/scsi_generic/sgN/device/). Removed to keep clippy
+// -D warnings clean.
+
+pub(super) fn list_drives() -> Vec<super::DriveInfo> {
+    let mut out = Vec::new();
+    let names = enumerate_sg_names();
+    for name in names {
+        let path = format!("/dev/{name}");
+        if !std::path::Path::new(&path).exists() {
+            continue;
+        }
+
+        // Read sysfs-cached identity first. The kernel runs its own INQUIRY
+        // at device probe time and stashes vendor/model/rev under
+        // `/sys/class/scsi_generic/sgN/device/`. Those values survive even
+        // when the drive firmware is wedged below the USB bridge (our own
+        // INQUIRY times out but sysfs still has the pre-wedge answer), so
+        // the UI always has a human-readable identity to show.
+        let (sysfs_vendor, sysfs_model, sysfs_firmware) = sysfs_identity(&name);
+
+        // INQUIRY-only probe — open transport, run INQUIRY, drop. No
+        // identify, no init, no firmware reset preamble's secondary
+        // commands beyond what `SgIoTransport::open` already does (one
+        // SCSI bus reset on the kernel SG fd, ~2 s).
+        let info = match SgIoTransport::open(std::path::Path::new(&path)) {
+            Ok(mut transport) => match super::inquiry(&mut transport) {
+                Ok(r) => super::DriveInfo {
+                    path: path.clone(),
+                    vendor: pick_identity(r.vendor_id, &sysfs_vendor),
+                    model: pick_identity(r.model, &sysfs_model),
+                    firmware: pick_identity(r.firmware, &sysfs_firmware),
+                },
+                Err(_) => super::DriveInfo {
+                    path: path.clone(),
+                    vendor: sysfs_vendor,
+                    model: sysfs_model,
+                    firmware: sysfs_firmware,
+                },
+            },
+            Err(_) => super::DriveInfo {
+                path: path.clone(),
+                vendor: sysfs_vendor,
+                model: sysfs_model,
+                firmware: sysfs_firmware,
+            },
+        };
+        out.push(info);
+    }
+    out
+}
+
+/// Prefer the live INQUIRY answer over the sysfs-cached one, but fall
+/// back to sysfs when the live answer is empty (wedge / bridge bug).
+fn pick_identity(live: String, sysfs: &str) -> String {
+    let trimmed = live.trim();
+    if trimmed.is_empty() {
+        sysfs.to_string()
+    } else {
+        live
+    }
+}
+
+/// Read the kernel's cached INQUIRY identity strings for `sgN` from
+/// `/sys/class/scsi_generic/sgN/device/{vendor,model,rev}`. Empty strings
+/// when sysfs is unavailable (minimal container, non-Linux filesystem).
+fn sysfs_identity(name: &str) -> (String, String, String) {
+    let read = |field: &str| -> String {
+        std::fs::read_to_string(format!("/sys/class/scsi_generic/{name}/device/{field}"))
+            .map(|s| s.trim().to_string())
+            .unwrap_or_default()
+    };
+    (read("vendor"), read("model"), read("rev"))
+}
+
+/// Enumerate `sg*` names via `/sys/class/scsi_generic/`, filtered to
+/// SCSI peripheral type 5 (optical). Falls back to a `sg0..15` probe
+/// when sysfs is unreadable. Returns names sorted lexically so caller
+/// iteration is deterministic.
+fn enumerate_sg_names() -> Vec<String> {
+    let mut names = Vec::new();
+    if let Ok(entries) = std::fs::read_dir("/sys/class/scsi_generic") {
+        for entry in entries.flatten() {
+            let name = entry.file_name().to_string_lossy().to_string();
+            if !name.starts_with("sg") {
+                continue;
+            }
+            let type_path = format!("/sys/class/scsi_generic/{name}/device/type");
+            match std::fs::read_to_string(&type_path) {
+                Ok(s) if s.trim() == SCSI_TYPE_OPTICAL => names.push(name),
+                Ok(_) => {}                 // not optical
+                Err(_) => names.push(name), // sysfs unreadable — let INQUIRY decide
+            }
+        }
+    } else {
+        // Sysfs missing — fall back to a brute-force probe. The INQUIRY
+        // step in `list_drives` filters non-optical responses naturally.
+        for i in 0..SG_FALLBACK_MAX {
+            let name = format!("sg{i}");
+            if std::path::Path::new(&format!("/dev/{name}")).exists() {
+                names.push(name);
+            }
+        }
+    }
+    names.sort();
+    names
+}
+
+/// `drive_has_disc` = single TEST UNIT READY. Any error (including our
+/// synthesised wedge signature, `ScsiError { status: 0xFF }`, when
+/// `execute()` times out) bubbles straight up to the caller.
+///
+/// ## No in-library wedge recovery — and why
+///
+/// Versions 0.13.1 – 0.13.3 layered `scsi::reset()` + `scsi::usb_reset()`
+/// (`USBDEVFS_RESET`) escalation inside `drive_has_disc`. Production
+/// testing on the LG BU40N USB BD-RE showed all three userspace recovery
+/// ladders succeed at the USB transport level (the kernel logs
+/// `usb 3-2: reset high-speed USB device`, the device re-authorises
+/// and re-attaches on a fresh `scsi_host`) **but the drive firmware
+/// below the USB bridge stays locked** — no LUN ever enumerates, TUR
+/// never succeeds, /dev/sg* never reappears. Physical power-cycle
+/// (unplug-replug or host reboot) is the only recovery.
+///
+/// Methods tried and discarded:
+///  - `SG_SCSI_RESET` (device-level SCSI bus reset)
+///  - `STOP UNIT` / `START UNIT` CDB pair
+///  - `USBDEVFS_RESET` ioctl on `/dev/bus/usb/BBB/DDD`
+///  - `/sys/bus/usb/devices/<port>/authorized` 0→1 toggle
+///  - `/sys/bus/usb/drivers/usb-storage/{unbind,bind}` driver rebind
+///  - Forced `echo "- - -" > /sys/class/scsi_host/hostN/scan`
+///
+/// Rolled back in 0.13.4. Callers (autorip, CLI) surface the error
+/// directly and prompt the user to physically reconnect the drive.
+/// If a future hardware class is found where USB-layer recovery
+/// actually works, the escalation belongs here, gated on the wedge
+/// signature — see git tag `v0.13.3` for the full implementation.
+pub(super) fn drive_has_disc(path: &Path) -> Result<bool> {
+    let mut transport = SgIoTransport::open(path)?;
+    let cdb = [crate::scsi::SCSI_TEST_UNIT_READY, 0, 0, 0, 0, 0];
+    let mut buf = [0u8; 0];
+    match transport.execute(
+        &cdb,
+        crate::scsi::DataDirection::None,
+        &mut buf,
+        crate::scsi::TUR_TIMEOUT_MS,
+    ) {
+        Ok(_) => Ok(true),
+        Err(Error::ScsiError {
+            sense_key: SENSE_KEY_NOT_READY,
+            ..
+        }) => Ok(false),
+        Err(e) => Err(e),
+    }
+}
@@ -212,8 +212,9 @@ impl MacScsiTransport {
        unsafe { IOObjectRelease(service) };

        if kr != K_IO_RETURN_SUCCESS || plugin.is_null() {
-            return Err(Error::DeviceNotFound {
-                path: format!("{}: IOKit plugin creation failed (0x{:08x})", dev_str, kr),
+            return Err(Error::IoKitPluginFailed {
+                path: dev_str.to_string(),
+                kr: kr as u32,
            });
        }

@@ -231,8 +232,8 @@ impl MacScsiTransport {
        com_release(plugin);

        if hr != 0 || device_iface.is_null() {
-            return Err(Error::DeviceNotFound {
-                path: format!("{}: SCSITaskDeviceInterface not available", dev_str),
+            return Err(Error::ScsiInterfaceUnavailable {
+                path: dev_str.to_string(),
            });
        }

@@ -244,11 +245,12 @@ impl MacScsiTransport {
        };
        if kr != K_IO_RETURN_SUCCESS {
            com_release(device_iface);
-            return Err(Error::DevicePermission {
-                path: format!(
-                    "{}: exclusive access denied (0x{:08x}). Try: diskutil unmountDisk {}",
-                    dev_str, kr, dev_str
-                ),
+            // No "Try: diskutil unmountDisk" hint — that's the CLI's job.
+            // The typed variant carries device path + IOReturn so the
+            // caller can render the right message in the right language.
+            return Err(Error::DeviceLocked {
+                path: dev_str.to_string(),
+                kr: kr as u32,
            });
        }

@@ -258,25 +260,81 @@ impl MacScsiTransport {
        })
    }

-    /// Reset the drive to a known good state.
-    /// On macOS, we open the device, release exclusive access, wait for
-    /// the system to reclaim it, then the next open() re-acquires.
-    /// IOKit's USB layer handles device-level resets internally when the
-    /// exclusive access is released and re-acquired.
-    ///
-    /// NOTE: untested — macOS reset may need IOUSBDeviceInterface::ResetDevice()
-    /// for USB drives. This is a best-effort implementation.
-    pub fn reset(device: &Path) -> Result<()> {
-        // Opening and immediately dropping triggers release of exclusive access
-        // which forces IOKit to reset the device state.
-        if let Ok(transport) = Self::open(device) {
-            drop(transport); // Drop releases exclusive access + closes plugin
+    // `reset()` removed in 0.13.6 — see scsi/mod.rs for rationale.
+}
+
+/// Enumerate optical drives on macOS. Mirrors `drive::macos::find_drives`
+/// (which iterates `/dev/disk0..15` + INQUIRY + filters peripheral
+/// type 5). Same logic, exposed through the new `DriveInfo` shape so
+/// callers — `list_drives()` in `scsi::mod` — never reach into
+/// `crate::drive::macos`.
+pub(super) fn list_drives() -> Vec<super::DriveInfo> {
+    let mut out = Vec::new();
+    for i in 0..K_DEV_DISK_MAX {
+        let path = format!("/dev/disk{i}");
+        if !std::path::Path::new(&path).exists() {
+            continue;
        }
-        std::thread::sleep(std::time::Duration::from_secs(2));
-        Ok(())
+        let mut transport = match MacScsiTransport::open(std::path::Path::new(&path)) {
+            Ok(t) => t,
+            Err(_) => continue,
+        };
+        let inquiry = match super::inquiry(&mut transport) {
+            Ok(r) => r,
+            Err(_) => continue,
+        };
+        // SCSI peripheral type field is the lower 5 bits of byte 0.
+        if inquiry.raw.is_empty()
+            || (inquiry.raw[K_INQUIRY_TYPE_BYTE] & K_INQUIRY_TYPE_MASK) != K_SCSI_TYPE_OPTICAL
+        {
+            continue;
+        }
+        out.push(super::DriveInfo {
+            path,
+            vendor: inquiry.vendor_id,
+            model: inquiry.model,
+            firmware: inquiry.firmware,
+        });
+    }
+    out
+}
+
+/// Maximum BSD disk index probed during enumeration. macOS assigns
+/// `/dev/diskN` sequentially per attached storage device; 16 covers
+/// any realistic homelab.
+const K_DEV_DISK_MAX: u8 = 16;
+
+/// SCSI INQUIRY response: peripheral device type lives in byte 0,
+/// lower 5 bits.
+const K_INQUIRY_TYPE_BYTE: usize = 0;
+const K_INQUIRY_TYPE_MASK: u8 = 0x1F;
+
+/// SCSI peripheral type 5 = "CD-ROM device" (covers DVD, BD-ROM, BD-RE).
+const K_SCSI_TYPE_OPTICAL: u8 = 0x05;
+
+/// TEST UNIT READY probe on macOS. Any non-"not ready" error bubbles up
+/// to the caller — in-library wedge recovery was rolled back in 0.13.4
+/// after USB-layer resets failed to recover the LG BU40N on Linux; the
+/// macOS impl mirrors that choice for symmetry. See the Linux
+/// `drive_has_disc` in `scsi/linux.rs` for the full rationale.
+pub(super) fn drive_has_disc(path: &Path) -> Result<bool> {
+    let mut transport = MacScsiTransport::open(path)?;
+    let cdb = [crate::scsi::SCSI_TEST_UNIT_READY, 0, 0, 0, 0, 0];
+    let mut buf = [0u8; 0];
+    match transport.execute(
+        &cdb,
+        crate::scsi::DataDirection::None,
+        &mut buf,
+        crate::scsi::TUR_TIMEOUT_MS,
+    ) {
+        Ok(_) => Ok(true),
+        Err(Error::ScsiError { sense_key, .. }) if sense_key == K_SENSE_KEY_NOT_READY => Ok(false),
+        Err(e) => Err(e),
    }
 }

+const K_SENSE_KEY_NOT_READY: u8 = 2;
+
 impl Drop for MacScsiTransport {
    fn drop(&mut self) {
        if self.exclusive {
@@ -404,13 +462,23 @@ impl ScsiTransport for MacScsiTransport {
 /// BSD name → IOKit service for the SCSI device.
 ///
 /// Walk: IOMedia (BSD name match) → parent chain → SCSIPeripheralDeviceNub.
+///
+/// All failure paths surface as `Error::DeviceNotFound { path: bsd_name }` —
+/// the four internal stages (IOMasterPort / IOBSDNameMatching / IOMedia
+/// lookup / walk_to_authoring_device) collapse into one observable error
+/// because none of them are user-actionable individually. Pre-0.13 each
+/// stage stuffed an English description into `path:` ("…IOMasterPort
+/// failed", "…SCSITaskDeviceInterface not available", etc.) which broke
+/// the library's "no English text" rule.
 fn find_scsi_service(bsd_name: &str) -> Result<IOObject> {
+    let not_found = || Error::DeviceNotFound {
+        path: bsd_name.to_string(),
+    };
+
    let mut master: MachPort = 0;
    let kr = unsafe { IOMasterPort(0, &mut master) };
    if kr != K_IO_RETURN_SUCCESS {
-        return Err(Error::DeviceNotFound {
-            path: format!("{}: IOMasterPort failed", bsd_name),
-        });
+        return Err(not_found());
    }

    // IOBSDNameMatching creates a dictionary matching { "BSD Name" = bsd_name }
@@ -418,17 +486,13 @@ fn find_scsi_service(bsd_name: &str) -> Result<IOObject> {
    bsd_c.push(0);
    let matching = unsafe { IOBSDNameMatching(master, 0, bsd_c.as_ptr()) };
    if matching.is_null() {
-        return Err(Error::DeviceNotFound {
-            path: format!("{}: IOBSDNameMatching failed", bsd_name),
-        });
+        return Err(not_found());
    }

    // Find the single IOMedia service (consumes the matching dict)
    let media = unsafe { IOServiceGetMatchingService(master, matching) };
    if media == 0 {
-        return Err(Error::DeviceNotFound {
-            path: format!("{}: no IOMedia found", bsd_name),
-        });
+        return Err(not_found());
    }

    // Walk up the IOService plane to find the authoring device.
@@ -441,9 +505,7 @@ fn find_scsi_service(bsd_name: &str) -> Result<IOObject> {
    let service = walk_to_authoring_device(media);
    unsafe { IOObjectRelease(media) };

-    service.ok_or_else(|| Error::DeviceNotFound {
-        path: format!("{}: no SCSI authoring device in IORegistry", bsd_name),
-    })
+    service.ok_or_else(not_found)
 }

 /// Walk up the IOService plane from an IOMedia to the SCSI authoring device.
@@ -18,6 +18,10 @@ use std::path::Path;

 // ── SCSI opcodes (SPC-4, MMC-6) ────────────────────────────────────────────

+/// SPC-4 TEST UNIT READY — six-byte CDB, no data transfer. Used by
+/// [`drive_has_disc`] as the cheapest "is the drive responsive / does
+/// it have media?" probe.
+pub const SCSI_TEST_UNIT_READY: u8 = 0x00;
 pub const SCSI_INQUIRY: u8 = 0x12;
 pub const SCSI_READ_CAPACITY: u8 = 0x25;
 pub const SCSI_READ_10: u8 = 0x28;
@@ -33,6 +37,12 @@ pub const SCSI_READ_DISC_STRUCTURE: u8 = 0xAD;
 /// AACS key class for REPORT KEY / SEND KEY commands.
 pub const AACS_KEY_CLASS: u8 = 0x02;

+/// Timeout for TEST UNIT READY probes used by [`drive_has_disc`].
+/// TUR is the cheapest SCSI op (no data transfer); 5 s is generous
+/// for any healthy bus and short enough that a hung device can't stall
+/// a poll-loop tick.
+pub(crate) const TUR_TIMEOUT_MS: u32 = 5_000;
+
 // ── Types ───────────────────────────────────────────────────────────────────

 #[derive(Debug, Clone, Copy, PartialEq)]
@@ -82,34 +92,144 @@ pub fn open(device: &Path) -> Result<Box<dyn ScsiTransport>> {

    #[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "windows")))]
    {
-        Err(Error::DeviceNotFound {
-            path: format!("{}: unsupported platform", device.display()),
+        Err(Error::UnsupportedPlatform {
+            target: std::env::consts::OS.to_string(),
        })
    }
 }

-/// Reset a SCSI device to a known good state. Platform-specific.
-/// On Linux: open/close fd cycle + TUR + SG_SCSI_RESET escalation.
-pub fn reset(device: &Path) -> Result<()> {
+// Note: a top-level `scsi::reset()` used to live here, wrapping a
+// platform reset in a thread+recv_timeout so a kernel-wedged ioctl
+// couldn't hang the caller. Removed in 0.13.6 along with the
+// SG_SCSI_RESET / STOP+START UNIT escalation that needed it. The
+// remaining platform reset (Linux: SgIoTransport::reset, called only
+// from SgIoTransport::open) does pure userspace state cleanup with
+// bounded sleeps — no escape-hatch wrapper required.
+
+// ── USB-layer recovery: rolled back in 0.13.4 ───────────────────────────────
+//
+// 0.13.1 – 0.13.3 exposed `scsi::usb_reset()` (`USBDEVFS_RESET` on Linux,
+// `IOUSBDeviceInterface::ResetDevice` on macOS) and chained it into
+// `drive_has_disc` recovery. Production testing on the LG BU40N USB BD-RE
+// confirmed the USB stack resets succeed — dmesg logs
+// `usb 3-2: reset high-speed USB device` and the device re-authorises —
+// but the drive firmware below the USB bridge stays locked: LUN never
+// re-enumerates, TUR still times out, the drive is unusable until
+// physical unplug-replug or host reboot. Additional approaches tried
+// and discarded: `authorized` 0→1 toggle, usb-storage driver
+// unbind/rebind, forced SCSI host rescan, `STOP` + `START UNIT`.
+//
+// The APIs were removed so no caller can be misled into thinking a
+// software-only recovery exists for this class of wedge. If a future
+// hardware class surfaces where USB-layer recovery actually helps, the
+// code should live here again, gated on a wedge signature — see git
+// tag `v0.13.3` for the full implementation.
+
+// ── Lightweight discovery + presence probes ─────────────────────────────────
+//
+// These two are the *only* hardware-touching APIs autorip + freemkv CLI use
+// outside the rip path itself. They're intentionally cheap:
+//
+// - `list_drives()` is a one-shot enumeration: filesystem walk for sg/cdrom
+//   nodes, type-5 filter, single INQUIRY per candidate. No firmware, no
+//   reset-on-open, no init. Caller caches the result.
+// - `drive_has_disc(path)` is a single TEST UNIT READY (six-byte CDB, no
+//   data transfer) with internal wedge-recovery escalation. Callers in a
+//   poll loop don't need any other primitive to detect "disc inserted /
+//   removed" — and they never see the SCSI-vs-USB-reset escalation.
+//
+// `Drive::open` + `drive.init()` + `Disc::scan` remain heavy and on-demand;
+// callers only invoke them once they've decided to actually rip / verify a
+// specific drive.
+
+/// One optical drive on the system. Returned by [`list_drives`]. The
+/// fields are populated from a single INQUIRY at enumeration time —
+/// no firmware reset, no init.
+#[derive(Debug, Clone)]
+pub struct DriveInfo {
+    /// Platform device path: `/dev/sgN` (Linux), `/dev/diskN` (macOS),
+    /// `\\.\CdRomN` (Windows).
+    pub path: String,
+    /// SCSI INQUIRY vendor identifier (e.g. `"HL-DT-ST"`).
+    pub vendor: String,
+    /// SCSI INQUIRY product identifier (e.g. `"BD-RE BU40N"`).
+    pub model: String,
+    /// SCSI INQUIRY firmware revision (e.g. `"1.04"`).
+    pub firmware: String,
+}
+
+/// Enumerate optical drives present on the system.
+///
+/// **What it does**: per-platform sysfs / IOKit / setupapi walk for SCSI
+/// devices, filtered to type 5 (CD/DVD/BD), with a single INQUIRY each
+/// for vendor/model/firmware. No firmware reset, no `Drive::init`, no
+/// disc scan. Suitable for an autorip-style poll loop or a CLI's
+/// drive-list command.
+///
+/// **What it doesn't do**: probe disc presence (use [`drive_has_disc`]),
+/// open a `Drive` for ripping (use [`crate::Drive::open`]), or load
+/// drive profiles. Those are heavier operations callers invoke once
+/// they've selected a drive.
+pub fn list_drives() -> Vec<DriveInfo> {
    #[cfg(target_os = "linux")]
    {
-        linux::SgIoTransport::reset(device)
+        linux::list_drives()
    }

    #[cfg(target_os = "macos")]
    {
-        macos::MacScsiTransport::reset(device)
+        macos::list_drives()
    }

    #[cfg(target_os = "windows")]
    {
-        windows::SptiTransport::reset(device)
+        windows::list_drives()
    }

    #[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "windows")))]
    {
-        let _ = device;
-        Ok(())
+        Vec::new()
+    }
+}
+
+/// True if the drive at `path` currently has a disc inserted.
+///
+/// Issues a single TEST UNIT READY (cheapest SCSI op, no data transfer).
+/// Sense-key 2 ("not ready, medium not present") → `Ok(false)`; any
+/// other ready/not-ready response → `Ok(true)` or interpreted ready
+/// state. Suitable for poll-loop tick (~50 ms / drive on a healthy bus).
+///
+/// **Internal wedge recovery.** When the kernel's response indicates a
+/// wedged target — the `0xff` status pattern that means "no answer from
+/// the device" — this function transparently escalates: SCSI bus reset
+/// → if still wedged → USB device reset (`USBDEVFS_RESET` on Linux) →
+/// retry TUR. Callers never see wedge errors and never need to know
+/// about the escalation; if even the recovery path can't get a response,
+/// `Err(DeviceResetFailed)` surfaces. **No SCSI primitive is exposed to
+/// outside crates** — autorip / freemkv CLI / bdemu use this single
+/// function for the entire "is there a disc?" decision.
+pub fn drive_has_disc(path: &Path) -> Result<bool> {
+    #[cfg(target_os = "linux")]
+    {
+        linux::drive_has_disc(path)
+    }
+
+    #[cfg(target_os = "macos")]
+    {
+        macos::drive_has_disc(path)
+    }
+
+    #[cfg(target_os = "windows")]
+    {
+        windows::drive_has_disc(path)
+    }
+
+    #[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "windows")))]
+    {
+        let _ = path;
+        Err(Error::UnsupportedPlatform {
+            target: std::env::consts::OS.to_string(),
+        })
    }
 }

@@ -187,6 +187,39 @@ impl SptiTransport {
    }
 }

+/// Enumerate optical drives on Windows via `find_drives()` (CdRom0..15
+/// scan) and re-shape into `DriveInfo`. Existing implementation already
+/// returns `(path, DriveId)`; mapped here to the public struct.
+pub(super) fn list_drives() -> Vec<super::DriveInfo> {
+    crate::drive::windows::find_drives()
+        .into_iter()
+        .map(|(path, id)| super::DriveInfo {
+            path,
+            vendor: id.vendor_id.trim().to_string(),
+            model: id.product_id.trim().to_string(),
+            firmware: id.product_revision.trim().to_string(),
+        })
+        .collect()
+}
+
+/// TEST UNIT READY probe on Windows. No in-library recovery — see the
+/// Linux `drive_has_disc` doc block for the rationale.
+pub(super) fn drive_has_disc(path: &Path) -> Result<bool> {
+    let mut transport = SptiTransport::open(path)?;
+    let cdb = [crate::scsi::SCSI_TEST_UNIT_READY, 0, 0, 0, 0, 0];
+    let mut buf = [0u8; 0];
+    match transport.execute(
+        &cdb,
+        crate::scsi::DataDirection::None,
+        &mut buf,
+        crate::scsi::TUR_TIMEOUT_MS,
+    ) {
+        Ok(_) => Ok(true),
+        Err(Error::ScsiError { sense_key: 2, .. }) => Ok(false),
+        Err(e) => Err(e),
+    }
+}
+
 impl Drop for SptiTransport {
    fn drop(&mut self) {
        unsafe {
@@ -39,10 +39,12 @@ impl FileSectorReader {
        let len = file.metadata()?.len();
        let sectors = len / 2048;
        if sectors > u32::MAX as u64 {
-            return Err(std::io::Error::new(
-                std::io::ErrorKind::InvalidData,
-                format!("{path}: image too large, max ~8 TB"),
-            ));
+            // ~8 TB hard cap (u32::MAX × 2048 bytes). Path lives in the
+            // typed Error variant — no English in the message.
+            return Err(crate::error::Error::IsoTooLarge {
+                path: path.to_string(),
+            }
+            .into());
        }
        let capacity = sectors as u32;
        Ok(Self {
@@ -361,7 +361,9 @@ fn aacs_cross_validation_encrypt_then_decrypt() {
        plaintext[off] = 0x47;
        off += 192;
    }
-    // Fill the rest with a recognisable pattern (prime modulus avoids artefacts)
+    // Fill the rest with a recognisable pattern (prime modulus avoids artefacts).
+    // Index-arithmetic — clearer with a counted loop than an enumerate chain.
+    #[allow(clippy::needless_range_loop)]
    for i in 16..aacs::ALIGNED_UNIT_LEN {
        if plaintext[i] == 0 {
            plaintext[i] = (i % 251) as u8;
@@ -462,6 +464,7 @@ fn aacs_bus_decrypt_cross_validation() {
    ];

    let mut plaintext = vec![0u8; aacs::ALIGNED_UNIT_LEN];
+    #[allow(clippy::needless_range_loop)]
    for i in 0..aacs::ALIGNED_UNIT_LEN {
        plaintext[i] = ((i * 3 + 17) & 0xFF) as u8;
    }
@@ -494,6 +497,7 @@ fn css_roundtrip_with_snapshot() {
    let mut sector = vec![0x00u8; 2048];
    sector[0x14] = 0x30;
    sector[0x54..0x59].copy_from_slice(&[0xDE, 0xAD, 0xBE, 0xEF, 0x42]);
+    #[allow(clippy::needless_range_loop)]
    for i in 0x80..2048 {
        sector[i] = ((i * 7 + 3) & 0xFF) as u8;
    }
@@ -661,6 +665,7 @@ fn css_recover_title_key_with_exact_plaintext() {
    sector[0x54..0x59].copy_from_slice(&seed);
    let pes_header: [u8; 10] = [0x00, 0x00, 0x01, 0xE0, 0x00, 0x00, 0x80, 0x80, 0x05, 0x21];
    sector[0x80..0x8A].copy_from_slice(&pes_header);
+    #[allow(clippy::needless_range_loop)]
    for i in 0x8A..2048 {
        sector[i] = ((i * 13 + 7) & 0xFF) as u8;
    }
@@ -133,7 +133,9 @@ fn scan_options_default() {

 #[test]
 fn scan_options_with_keydb() {
-    let opts = ScanOptions::with_keydb("/tmp/KEYDB.cfg");
+    let opts = ScanOptions {
+        keydb_path: Some(("/tmp/KEYDB.cfg").into()),
+    };
    assert_eq!(
        opts.keydb_path.as_ref().unwrap().to_str().unwrap(),
        "/tmp/KEYDB.cfg"
@@ -143,7 +145,9 @@ fn scan_options_with_keydb() {
 #[test]
 fn scan_options_with_keydb_pathbuf() {
    let path = std::path::PathBuf::from("/home/user/.config/aacs/KEYDB.cfg");
-    let opts = ScanOptions::with_keydb(path.clone());
+    let opts = ScanOptions {
+        keydb_path: Some(path.clone()),
+    };
    assert_eq!(opts.keydb_path.unwrap(), path);
 }

@@ -511,7 +515,9 @@ fn resolve_encryption_no_keydb() {
    build_udf_with_aacs_dir(&mut reader);

    // No keydb configured and no standard keydb on the system
-    let opts = ScanOptions::with_keydb("/nonexistent/path/KEYDB.cfg");
+    let opts = ScanOptions {
+        keydb_path: Some(("/nonexistent/path/KEYDB.cfg").into()),
+    };
    let disc = Disc::scan_image(&mut reader, 1000, &opts).unwrap();

    // The disc detects encryption but can't resolve keys without a keydb
@@ -0,0 +1,504 @@
+//! Integration tests for progress reporting, halt behavior, drop safety,
+//! and the file-backed sector reader round trip.
+
+use libfreemkv::disc::{CopyOptions, DiscRegion};
+use libfreemkv::error::Result;
+use libfreemkv::pes::Stream as PesStream;
+use libfreemkv::{
+    ContentFormat, Disc, DiscFormat, DiscStream, DiscTitle, EventKind, Extent, FileSectorReader,
+    SectorReader,
+};
+use std::io::Write;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
+
+const SECTOR_SIZE: usize = 2048;
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+/// Returns zeroed sectors. Always succeeds. Counts each call.
+struct ZeroSectorReader {
+    capacity: u32,
+    calls: Arc<AtomicU64>,
+}
+
+impl ZeroSectorReader {
+    fn new(capacity: u32) -> Self {
+        Self {
+            capacity,
+            calls: Arc::new(AtomicU64::new(0)),
+        }
+    }
+}
+
+impl SectorReader for ZeroSectorReader {
+    fn read_sectors(
+        &mut self,
+        _lba: u32,
+        count: u16,
+        buf: &mut [u8],
+        _recovery: bool,
+    ) -> Result<usize> {
+        self.calls.fetch_add(1, Ordering::Relaxed);
+        let bytes = count as usize * SECTOR_SIZE;
+        buf[..bytes].fill(0);
+        Ok(bytes)
+    }
+
+    fn capacity(&self) -> u32 {
+        self.capacity
+    }
+}
+
+/// Like ZeroSectorReader but sleeps a configurable duration per call.
+/// Used by the halt test so the copy takes >1 s.
+struct SlowZeroSectorReader {
+    capacity: u32,
+    sleep_per_call: Duration,
+}
+
+impl SlowZeroSectorReader {
+    fn new(capacity: u32, sleep_per_call: Duration) -> Self {
+        Self {
+            capacity,
+            sleep_per_call,
+        }
+    }
+}
+
+impl SectorReader for SlowZeroSectorReader {
+    fn read_sectors(
+        &mut self,
+        _lba: u32,
+        count: u16,
+        buf: &mut [u8],
+        _recovery: bool,
+    ) -> Result<usize> {
+        std::thread::sleep(self.sleep_per_call);
+        let bytes = count as usize * SECTOR_SIZE;
+        buf[..bytes].fill(0);
+        Ok(bytes)
+    }
+
+    fn capacity(&self) -> u32 {
+        self.capacity
+    }
+}
+
+/// Build a Disc instance with a known capacity, no titles, no encryption.
+/// Sufficient for `Disc::copy` (which only uses capacity_sectors + decrypt keys).
+fn synthetic_disc(capacity_sectors: u32) -> Disc {
+    Disc {
+        volume_id: String::new(),
+        meta_title: None,
+        format: DiscFormat::BluRay,
+        capacity_sectors,
+        capacity_bytes: capacity_sectors as u64 * SECTOR_SIZE as u64,
+        layers: 1,
+        titles: Vec::new(),
+        region: DiscRegion::Free,
+        aacs: None,
+        css: None,
+        encrypted: false,
+        content_format: ContentFormat::BdTs,
+    }
+}
+
+/// Build a DiscTitle with a single extent of `sector_count` sectors and no
+/// streams (DiscStream still iterates sectors and would emit BytesRead).
+fn synthetic_title(sector_count: u32) -> DiscTitle {
+    DiscTitle {
+        playlist: String::new(),
+        playlist_id: 0,
+        duration_secs: 0.0,
+        size_bytes: sector_count as u64 * SECTOR_SIZE as u64,
+        clips: Vec::new(),
+        streams: Vec::new(),
+        chapters: Vec::new(),
+        extents: vec![Extent {
+            start_lba: 0,
+            sector_count,
+        }],
+        content_format: ContentFormat::BdTs,
+        codec_privates: Vec::new(),
+    }
+}
+
+// ── 1. BytesRead events emitted during disc copy (TDD red) ────────────────
+
+#[test]
+fn test_bytes_read_emitted_during_disc_copy() {
+    // Build a tiny synthetic disc and stream it through DiscStream.
+    let reader = ZeroSectorReader::new(64);
+    let title = synthetic_title(64);
+    let keys = libfreemkv::DecryptKeys::None;
+
+    let mut stream = DiscStream::new(Box::new(reader), title, keys, 60, ContentFormat::BdTs);
+
+    let count = Arc::new(AtomicU64::new(0));
+    let count_cb = count.clone();
+    stream.on_event(move |ev| {
+        if let EventKind::BytesRead { .. } = ev.kind {
+            count_cb.fetch_add(1, Ordering::Relaxed);
+        }
+    });
+
+    // Drive the stream to EOF. With no streams configured, read() returns
+    // Ok(None) once all extents are exhausted.
+    loop {
+        match stream.read() {
+            Ok(Some(_frame)) => {}
+            Ok(None) => break,
+            Err(e) => panic!("stream read failed: {e:?}"),
+        }
+    }
+
+    let n = count.load(Ordering::Relaxed);
+    // EXPECTED TO FAIL until BytesRead emission is wired up. TDD red.
+    assert!(
+        n > 0,
+        "expected at least one BytesRead event, got {n} (lib does not yet emit BytesRead)"
+    );
+}
+
+// ── 2. Disc::copy on_progress callback fires (regression guard) ───────────
+
+#[test]
+fn test_disc_copy_progress_callback_fires() {
+    let disc = synthetic_disc(64);
+    let mut reader = ZeroSectorReader::new(64);
+
+    let tmp = tempfile::NamedTempFile::new().expect("tempfile create");
+    let iso_path = tmp.path().to_path_buf();
+    drop(tmp); // we want the path, not the file handle
+
+    let calls = Arc::new(AtomicU64::new(0));
+    let last_bytes = Arc::new(AtomicU64::new(0));
+    let calls_cb = calls.clone();
+    let last_bytes_cb = last_bytes.clone();
+
+    let progress = move |bytes: u64, _total: u64| {
+        calls_cb.fetch_add(1, Ordering::Relaxed);
+        last_bytes_cb.store(bytes, Ordering::Relaxed);
+    };
+
+    let opts = CopyOptions {
+        decrypt: false,
+        on_progress: Some(&progress),
+        ..Default::default()
+    };
+
+    let result = disc.copy(&mut reader, &iso_path, &opts).expect("copy ok");
+
+    // Cleanup any sidecar mapfile + ISO before assertions.
+    let _ = std::fs::remove_file(&iso_path);
+    let _ = std::fs::remove_file(libfreemkv::disc::mapfile_path_for(&iso_path));
+
+    assert!(result.complete, "copy should be complete");
+    let n = calls.load(Ordering::Relaxed);
+    let last = last_bytes.load(Ordering::Relaxed);
+    assert!(n > 0, "on_progress should fire at least once, got {n}");
+    assert!(
+        last > 0,
+        "final progress bytes should be non-zero, got {last}"
+    );
+}
+
+// ── 3. Halt aborts disc copy promptly ─────────────────────────────────────
+
+#[test]
+fn test_halt_aborts_disc_copy_promptly() {
+    // 6000 sectors, 60-sector batches → 100 read_sectors() calls.
+    // 10 ms sleep per call → ~1 s total without halt.
+    let capacity_sectors: u32 = 6000;
+    let mut reader = SlowZeroSectorReader::new(capacity_sectors, Duration::from_millis(10));
+    let disc = synthetic_disc(capacity_sectors);
+
+    let tmp = tempfile::NamedTempFile::new().expect("tempfile create");
+    let iso_path = tmp.path().to_path_buf();
+    drop(tmp);
+
+    let halt = Arc::new(AtomicBool::new(false));
+    let halt_for_thread = halt.clone();
+    let iso_path_for_thread = iso_path.clone();
+
+    let join = std::thread::spawn(move || {
+        let opts = CopyOptions {
+            decrypt: false,
+            halt: Some(halt_for_thread),
+            ..Default::default()
+        };
+        let t0 = Instant::now();
+        let res = disc.copy(&mut reader, &iso_path_for_thread, &opts);
+        (res, t0.elapsed())
+    });
+
+    // Let copy run, then halt.
+    std::thread::sleep(Duration::from_millis(200));
+    halt.store(true, Ordering::Relaxed);
+
+    // Bound the join: should exit far before the full 1 s otherwise needed.
+    let started = Instant::now();
+    let mut joined = None;
+    while started.elapsed() < Duration::from_millis(2000) {
+        if join.is_finished() {
+            joined = Some(join.join().expect("thread join"));
+            break;
+        }
+        std::thread::sleep(Duration::from_millis(20));
+    }
+    let (result, elapsed) = joined.expect("copy thread did not exit within 2s of halt");
+
+    // Cleanup
+    let _ = std::fs::remove_file(&iso_path);
+    let _ = std::fs::remove_file(libfreemkv::disc::mapfile_path_for(&iso_path));
+
+    let copy_result = result.expect("copy returns Ok with halted=true on halt");
+    assert!(
+        copy_result.halted,
+        "copy_result.halted should be true after halt"
+    );
+    assert!(
+        !copy_result.complete,
+        "copy_result.complete should be false when halted"
+    );
+    assert!(
+        elapsed < Duration::from_millis(2000),
+        "copy thread exit elapsed {elapsed:?} exceeded 2s"
+    );
+}
+
+// ── 4. DiscStream Drop does not panic or block ────────────────────────────
+
+#[test]
+fn test_drop_impls_do_not_panic_or_block() {
+    let reader = ZeroSectorReader::new(64);
+    let title = synthetic_title(64);
+    let keys = libfreemkv::DecryptKeys::None;
+    let stream = DiscStream::new(Box::new(reader), title, keys, 60, ContentFormat::BdTs);
+
+    // Drop on a worker thread; main thread enforces the timeout.
+    let handle = std::thread::spawn(move || {
+        drop(stream);
+    });
+
+    let started = Instant::now();
+    while started.elapsed() < Duration::from_millis(100) {
+        if handle.is_finished() {
+            handle.join().expect("drop thread join");
+            return;
+        }
+        std::thread::sleep(Duration::from_millis(5));
+    }
+    panic!("DiscStream drop did not complete within 100ms");
+}
+
+// ── 5. FileSectorReader round trip ────────────────────────────────────────
+
+#[test]
+fn test_file_sector_reader_round_trip() {
+    // Build 8 sectors of pseudo-random bytes (sector-aligned).
+    const N_SECTORS: usize = 8;
+    let mut data = vec![0u8; N_SECTORS * SECTOR_SIZE];
+    for (i, b) in data.iter_mut().enumerate() {
+        // Cheap PRNG: just a multiplicative pattern, deterministic for asserts.
+        *b = ((i as u64).wrapping_mul(2654435761) >> 16) as u8;
+    }
+
+    let mut tmp = tempfile::NamedTempFile::new().expect("tempfile create");
+    tmp.write_all(&data).expect("write data");
+    tmp.flush().expect("flush");
+
+    let path = tmp.path().to_str().expect("path utf-8").to_string();
+    let mut fsr = FileSectorReader::open(&path).expect("open FileSectorReader");
+
+    assert_eq!(fsr.capacity(), N_SECTORS as u32, "capacity mismatch");
+
+    // Read each sector individually and compare.
+    let mut buf = vec![0u8; SECTOR_SIZE];
+    for lba in 0..N_SECTORS as u32 {
+        let n = fsr
+            .read_sectors(lba, 1, &mut buf, false)
+            .expect("read_sectors");
+        assert_eq!(n, SECTOR_SIZE);
+        let off = lba as usize * SECTOR_SIZE;
+        assert_eq!(
+            &buf[..],
+            &data[off..off + SECTOR_SIZE],
+            "sector {lba} mismatch"
+        );
+    }
+
+    // Read all sectors at once and compare.
+    let mut all = vec![0u8; N_SECTORS * SECTOR_SIZE];
+    let n = fsr
+        .read_sectors(0, N_SECTORS as u16, &mut all, false)
+        .expect("read all sectors");
+    assert_eq!(n, N_SECTORS * SECTOR_SIZE);
+    assert_eq!(all, data, "bulk read mismatch");
+}
+
+// ── 6. Disc::copy stall detection triggers skip-forward (TDD red) ─────────
+//
+// Regression guard for the Dell-host hang where `read_sectors` blocked inside
+// a kernel-level USB stall and `Disc::copy` sat frozen for 10+ minutes with
+// no progress and no error. The fix introduces `CopyOptions::stall_secs:
+// Option<u64>` — when elapsed-since-last-`bytes_good`-advance exceeds the
+// threshold, `Disc::copy` treats the current block as a read failure and
+// triggers the skip-forward path so the rip can advance.
+//
+// THIS TEST IS EXPECTED TO FAIL UNTIL THE PARALLEL FIX LANDS.
+// - Until `stall_secs` exists on `CopyOptions`, the test will not compile.
+// - Once the field exists but the stall guard isn't wired, the spawned copy
+//   thread will never exit (test fails on the 5s join bound).
+// - Once the guard is wired, copy returns within ~stall_secs with
+//   `complete=false` and `bytes_pending>0`.
+
+/// Reader that returns Ok for sectors `< block_after`, then returns Err for
+/// any sector `>= block_after` after a small per-call delay. Models the
+/// realistic Dell-host symptom: reads keep returning Err (skip-forward fires)
+/// but no `bytes_good` ever accrues; without a stall guard, Pass 1 grinds
+/// silently for tens of minutes.
+struct StallingSectorReader {
+    capacity: u32,
+    block_after: u32,
+    /// Per-call delay for sectors >= block_after (simulates slow reads).
+    err_delay_ms: u64,
+    release: Arc<AtomicBool>,
+    /// Retained so callers can release the reader; unused now that the
+    /// reader returns Err instead of blocking, but kept so the test's
+    /// existing release plumbing compiles.
+    park: Arc<(Mutex<()>, std::sync::Condvar)>,
+}
+
+impl StallingSectorReader {
+    fn new(capacity: u32, block_after: u32) -> Self {
+        Self {
+            capacity,
+            block_after,
+            err_delay_ms: 100,
+            release: Arc::new(AtomicBool::new(false)),
+            park: Arc::new((Mutex::new(()), std::sync::Condvar::new())),
+        }
+    }
+
+    fn release_handle(&self) -> (Arc<AtomicBool>, Arc<(Mutex<()>, std::sync::Condvar)>) {
+        (self.release.clone(), self.park.clone())
+    }
+}
+
+impl SectorReader for StallingSectorReader {
+    fn read_sectors(
+        &mut self,
+        lba: u32,
+        count: u16,
+        buf: &mut [u8],
+        _recovery: bool,
+    ) -> Result<usize> {
+        if lba >= self.block_after {
+            // Realistic stall model: read takes err_delay_ms then returns
+            // Err. With skip_on_error+skip_forward, Disc::copy will keep
+            // skip-forwarding through this region — no bytes_good accrues.
+            // The stall guard fires when bytes_good is unchanged for
+            // stall_secs.
+            std::thread::sleep(Duration::from_millis(self.err_delay_ms));
+            return Err(libfreemkv::error::Error::DiscRead { sector: lba as u64 });
+        }
+        let bytes = count as usize * SECTOR_SIZE;
+        buf[..bytes].fill(0);
+        Ok(bytes)
+    }
+
+    fn capacity(&self) -> u32 {
+        self.capacity
+    }
+}
+
+#[test]
+fn test_disc_copy_stall_detection_triggers_skip_forward() {
+    // 1024 sectors total. Reader serves the first 64 sectors instantly, then
+    // every later read blocks forever. With stall_secs=2, copy should bail
+    // out of the stalled block within ~2s and either skip forward or finish
+    // with bytes_pending > 0 / complete=false.
+    let capacity_sectors: u32 = 1024;
+    let block_after: u32 = 64;
+
+    let reader = StallingSectorReader::new(capacity_sectors, block_after);
+    let (release_flag, park) = reader.release_handle();
+    let mut reader = reader;
+
+    let disc = synthetic_disc(capacity_sectors);
+
+    let tmp = tempfile::NamedTempFile::new().expect("tempfile create");
+    let iso_path = tmp.path().to_path_buf();
+    drop(tmp);
+
+    let iso_path_for_thread = iso_path.clone();
+
+    let join = std::thread::spawn(move || {
+        let opts = CopyOptions {
+            decrypt: false,
+            skip_on_error: true,
+            skip_forward: true,
+            // ASSUMPTION: parallel fix adds `pub stall_secs: Option<u64>` to
+            // CopyOptions. If the field name differs, update here.
+            stall_secs: Some(2),
+            ..Default::default()
+        };
+        let t0 = Instant::now();
+        let res = disc.copy(&mut reader, &iso_path_for_thread, &opts);
+        (res, t0.elapsed())
+    });
+
+    // Bound the join to ~5s. With stall_secs=2 the copy should exit well
+    // within this window. If it doesn't, the stall guard isn't working.
+    let started = Instant::now();
+    let mut joined = None;
+    while started.elapsed() < Duration::from_millis(5000) {
+        if join.is_finished() {
+            joined = Some(join.join().expect("thread join"));
+            break;
+        }
+        std::thread::sleep(Duration::from_millis(50));
+    }
+
+    // Whether or not the join succeeded, release the parked reader thread so
+    // it can exit (its &mut reader is owned by the spawned thread; releasing
+    // lets that thread unwind cleanly).
+    release_flag.store(true, Ordering::Relaxed);
+    park.1.notify_all();
+
+    let (result, elapsed) = match joined {
+        Some(v) => v,
+        None => {
+            // Wait a bit longer for the thread to drain after release so we
+            // don't leave it dangling, then fail the test.
+            std::thread::sleep(Duration::from_millis(500));
+            panic!(
+                "Disc::copy did not return within 5s of stall_secs=2 — \
+                 stall guard not wired (TDD red until fix lands)"
+            );
+        }
+    };
+
+    // Cleanup
+    let _ = std::fs::remove_file(&iso_path);
+    let _ = std::fs::remove_file(libfreemkv::disc::mapfile_path_for(&iso_path));
+
+    let copy_result = result.expect("copy returns Ok with stall handling");
+
+    assert!(
+        elapsed < Duration::from_millis(5000),
+        "copy elapsed {elapsed:?} exceeded 5s bound (stall_secs=2)"
+    );
+    assert!(
+        copy_result.bytes_pending > 0,
+        "expected bytes_pending > 0 after stall-triggered skip; got {}",
+        copy_result.bytes_pending
+    );
+    assert!(
+        !copy_result.complete,
+        "expected complete=false after stall-triggered skip"
+    );
+}
@@ -30,6 +30,7 @@ fn sample_disc_title() -> DiscTitle {
                language: "eng".into(),
                sample_rate: SampleRate::S48,
                secondary: false,
+                purpose: libfreemkv::LabelPurpose::Normal,
                label: "English Atmos".into(),
            }),
            Stream::Audio(AudioStream {
@@ -39,6 +40,7 @@ fn sample_disc_title() -> DiscTitle {
                language: "fra".into(),
                sample_rate: SampleRate::S48,
                secondary: false,
+                purpose: libfreemkv::LabelPurpose::Normal,
                label: "French".into(),
            }),
            Stream::Subtitle(SubtitleStream {
@@ -46,6 +48,7 @@ fn sample_disc_title() -> DiscTitle {
                codec: Codec::Pgs,
                language: "eng".into(),
                forced: false,
+                qualifier: libfreemkv::LabelQualifier::None,
                codec_data: None,
            }),
        ],
@@ -404,6 +407,7 @@ fn meta_codec_roundtrip() {
            language: "eng".into(),
            sample_rate: SampleRate::S48,
            secondary: false,
+            purpose: libfreemkv::LabelPurpose::Normal,
            label: String::new(),
        }));
    }
@@ -413,6 +417,7 @@ fn meta_codec_roundtrip() {
            codec,
            language: "eng".into(),
            forced: false,
+            qualifier: libfreemkv::LabelQualifier::None,
            codec_data: None,
        }));
    }
@@ -501,6 +506,7 @@ fn meta_all_stream_types() {
                language: "eng".into(),
                sample_rate: SampleRate::S48,
                secondary: false,
+                purpose: libfreemkv::LabelPurpose::Normal,
                label: "Primary Audio".into(),
            }),
            Stream::Subtitle(SubtitleStream {
@@ -508,6 +514,7 @@ fn meta_all_stream_types() {
                codec: Codec::Pgs,
                language: "fra".into(),
                forced: true,
+                qualifier: libfreemkv::LabelQualifier::None,
                codec_data: None,
            }),
            Stream::Audio(AudioStream {
@@ -517,6 +524,7 @@ fn meta_all_stream_types() {
                language: "eng".into(),
                sample_rate: SampleRate::S48,
                secondary: true,
+                purpose: libfreemkv::LabelPurpose::Normal,
                label: "Commentary".into(),
            }),
        ],
@@ -623,6 +631,7 @@ fn mkvstream_roundtrip_bdts() {
            language: "eng".into(),
            sample_rate: SampleRate::S48,
            secondary: false,
+            purpose: libfreemkv::LabelPurpose::Normal,
            label: "English".into(),
        })],
        chapters: Vec::new(),
@@ -679,6 +688,7 @@ fn mkvstream_meta_preserves_all_streams() {
                language: "eng".into(),
                sample_rate: SampleRate::S48,
                secondary: false,
+                purpose: libfreemkv::LabelPurpose::Normal,
                label: "English".into(),
            }),
            Stream::Audio(AudioStream {
@@ -688,6 +698,7 @@ fn mkvstream_meta_preserves_all_streams() {
                language: "fra".into(),
                sample_rate: SampleRate::S48,
                secondary: false,
+                purpose: libfreemkv::LabelPurpose::Normal,
                label: "French".into(),
            }),
            Stream::Subtitle(SubtitleStream {
@@ -695,6 +706,7 @@ fn mkvstream_meta_preserves_all_streams() {
                codec: Codec::Pgs,
                language: "eng".into(),
                forced: false,
+                qualifier: libfreemkv::LabelQualifier::None,
                codec_data: None,
            }),
            Stream::Subtitle(SubtitleStream {
@@ -702,6 +714,7 @@ fn mkvstream_meta_preserves_all_streams() {
                codec: Codec::Pgs,
                language: "fra".into(),
                forced: true,
+                qualifier: libfreemkv::LabelQualifier::None,
                codec_data: None,
            }),
        ],
Author	SHA1	Message	Date
MattJackson	36b65f526a	v0.13.10: version sync	2026-04-25 08:25:08 -07:00
MattJackson	ca8ebf418f	v0.13.9: Disc::copy stall guard + SgIoTransport no-reopen-on-timeout Fixes the silent Pass 1 hang observed on Dune 2 with v0.13.8 (drive grinding through bad sectors at 0 KB/s, errs=0, no error surfaced). Root cause: SgIoTransport::execute's reopen-after-poll-timeout opened a fresh /dev/sg* fd on the main thread, which serialized against the spawned close() of the old fd via the kernel's per-device state lock. The userspace 1.5s timeout still fired, but the abandon-and-reopen recovery itself blocked the main thread for as long as close() took. Net: reads returned slowly, skip-forward fired on every iteration, bytes_good never advanced. - SgIoTransport::execute: on poll timeout, spawn close, set fd=-1, return Err. No reopen on the main thread. The transport is now invalidated until the consumer creates a fresh Drive. - Disc::copy: add stall guard. CopyOptions.stall_secs (default 120s). If bytes_good doesn't advance for the threshold, break 'outer cleanly with complete=false, bytes_pending > 0 so Pass 2 retries pick up the NonTrimmed ranges with recovery=true 30s timeouts. - New regression test: test_disc_copy_stall_detection_triggers_ skip_forward in tests/integration_progress_and_halt.rs.	2026-04-25 08:12:01 -07:00
MattJackson	34182d956a	v0.13.8: version sync	2026-04-25 07:11:47 -07:00
MattJackson	0f967a2084	v0.13.7: version sync	2026-04-25 06:58:43 -07:00
MattJackson	0341995c0d	fix: allow dead_code on Drive::emit (DiscStream owns BytesRead emission post-0.13.6 strip)	2026-04-24 21:43:30 -07:00
MattJackson	fe0ec0c5cf	fix: drop unused INQUIRY_* constants (clippy -D warnings)	2026-04-24 21:42:30 -07:00
MattJackson	022657d481	docs: complete 0.13.6 docs sweep (architecture, api-design, disc-to-rip, README) Follow-up to the rip-recovery + drive-access updates: aligns the remaining docs with the v0.13.6 single-shot read model and the three-layer recovery architecture. - architecture.md: module map says single-shot read; new paragraph on layered recovery with postmortem pointer. - api-design.md: EventKind enum example expanded; emission notes document that BytesRead now fires from DiscStream::fill_extents and Retry/SectorRecovered are no longer emitted in 0.13.6+. - disc-to-rip.md: Step 10 of the pipeline diagram + module table reflect single-shot read. - docs/README.md: added rip-recovery.md to the TOC.	2026-04-24 21:36:49 -07:00
MattJackson	fc8eca44e1	docs: rewrite rip-recovery + drive-access for 0.13.6 single-shot model Updates docs/ to reflect the recovery-loop strip: - rip-recovery.md: drops Phase 1/2/3 description, replaces with three-layer model (Disc::patch multi-pass / DiscStream batch halving / Drive::read single-shot). Notes that no SCSI resets fire from any retry path. - drive-access.md: removes SG_SCSI_RESET + STOP/START UNIT escalation references; SgIoTransport::reset is now kernel SG_IO flush + ALLOW MEDIUM REMOVAL only. - src/mux/disc.rs + tests/: cargo fmt cleanup.	2026-04-24 21:35:33 -07:00
MattJackson	43836865be	v0.13.6: strip Drive::read inline recovery + reset escalation; emit BytesRead Drive::read is now single-shot. Phase 1/2/3 retries + scsi::reset+reopen removed (~80 lines). recovery=true bumps timeout to 30s; recovery=false stays at 1.5s. On any failure returns Err(DiscRead) immediately — caller (Disc::patch outer loop, DiscStream batch halver) handles retries. Inline reset+reopen WAS the wedge primitive on the LG BU40N. Per prior post-mortem, every USB/SCSI reset path tested fails to recover the wedged Initio bridge — the inline retry was pure cost. SgIoTransport::reset (Linux) trimmed to kernel SG_IO state flush + ALLOW MEDIUM REMOVAL. SG_SCSI_RESET ioctl + STOP/START UNIT escalation removed. macOS reset removed (no-op). scsi::reset() top-level family removed (no callers). EventKind::BytesRead { bytes, total } now actually emitted from DiscStream::fill_extents after each successful sector read. Was declared in 0.13.0, never fired. Drives autorip per-device progress in direct mode. EventKind::Retry / SectorRecovered no longer emitted (variants kept for forward compat). SpeedChange still emitted via Drive::set_speed public path. Tests: new tests/integration_progress_and_halt.rs (5 tests). 233 unit tests + 5 integration green.	2026-04-24 21:32:45 -07:00
MattJackson	5e22199441	v0.13.5: version sync (autorip-side fixes)	2026-04-24 20:13:07 -07:00
MattJackson	761b77bbd9	v0.13.4: roll back wedge recovery + add sysfs identity fallback USB/SCSI recovery escalation in drive_has_disc (0.13.1-0.13.3) tested on LG BU40N USB BD-RE: USBDEVFS_RESET, authorized toggle, driver unbind/rebind, SCSI host rescan — all succeed at the USB transport layer but the drive firmware below the bridge stays locked. Only physical unplug-replug clears it. Rolled back so consumers can surface the real failure to the user. New: list_drives falls back to sysfs-cached vendor/model/rev from /sys/class/scsi_generic/sgN/device/ when live INQUIRY returns empty, so wedged drives still show their identity in UIs. Removed: scsi::usb_reset, usb_reset_with_timeout, per-platform usb_reset methods, recover_then_probe, is_wedge_signature. Breadcrumb comment in scsi/linux.rs::drive_has_disc points at v0.13.3 tag for the full implementation if future hardware needs it back. Linux/macOS/Windows pass-through symmetric; 233 tests passing.	2026-04-24 19:53:44 -07:00
MattJackson	cc05ef2a3a	v0.13.3: broaden is_wedge_signature — fix dead-code wedge recovery 0.13.2's is_wedge_signature gated on opcode=SCSI_INQUIRY (0x12), but drive_has_disc issues TEST UNIT READY (0x00). Production wedge errors (E4000: 0x00/0xff/0x00) never matched → SCSI reset + USB reset escalation never fired. Drop the opcode gate. Status byte 0xFF is synthesised by our own execute() path on poll() timeout — it's the ground-truth wedge marker for any opcode. Linux-only; macOS/Windows use sense-key-based wedge detection.	2026-04-24 19:26:11 -07:00
MattJackson	e27b82ce5b	v0.13.2: list_drives + drive_has_disc; SCSI primitives pub(crate) Architectural cleanup. autorip + freemkv CLI were reimplementing drive discovery (sysfs walking, type-5 filtering, sg-path construction) and calling SCSI reset primitives directly. All of that hardware-aware code moves into libfreemkv with two cheap public probes: - DriveInfo + list_drives() — multi-OS enumeration (Linux/macOS/Windows) with peripheral-type-5 filtering and INQUIRY identity. Cheap. - drive_has_disc(path) — single TUR with internal wedge recovery escalation (SCSI reset → USB reset → retry) hidden from callers. USB-layer reset (USBDEVFS_RESET / IOUSBDeviceInterface::ResetDevice / storport's combined reset) wired across all three platforms. Visibility tightening — scsi::reset, scsi::usb_reset, and the timeout constants are now pub(crate). Compile-time guarantee that no consumer crate can issue SCSI commands directly. 233 lib tests pass; clippy clean.	2026-04-24 17:31:15 -07:00
MattJackson	8af47e4c19	v0.13.1: scsi::reset() bounded by wallclock timeout Production incident: autorip's poll loop called scsi::reset() on a wedged BU40N USB drive. The Linux SG_SCSI_RESET ioctl blocked indefinitely (kernel SCSI subsystem waiting for a bus-wedged device to ack a reset that will never come). Caller's poll loop hung for 60+ seconds before manual intervention. scsi::reset() now spawns a detached worker for the platform-specific reset and bounds the caller's wait via mpsc::recv_timeout. Default 30 s (DEFAULT_RESET_TIMEOUT_SECS); reset_with_timeout(device, dur) exposes the bound for callers that want a different value. Returns DeviceResetFailed on timeout. Worker thread keeps running until the kernel eventually unblocks — leaks one OS thread per hard wedge, but the daemon stays responsive instead of hanging forever. Follow-up flagged for 0.13.2: USB-attached drives wedge at the USB Mass Storage layer below SCSI; SG_SCSI_RESET doesn't help. A scsi::usb_reset(path) using USBDEVFS_RESET is the proper escalation.	2026-04-24 16:58:13 -07:00
MattJackson	d1f09439a5	v0.13.0: zero English in library + API hygiene + dead-code sweep Audit pass against the project docs "no English text in library code" rule. Found 9 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 Error variant. New variants and codes: ScsiInterfaceUnavailable (E1004), DeviceLocked (E1005), IoKitPluginFailed (E1006), UnsupportedPlatform (E2003), PlatformNotImplemented (E2004), MapfileInvalid (E6011), DiscUrlNotDirect (E9009). labels::apply() previously pushed Commentary/Descriptive/Score/IME and " (Secondary)" English literals into AudioStream.label, leaking into MKV titles + autorip UI. AudioStream now exposes structured `purpose: LabelPurpose`, SubtitleStream `qualifier: LabelQualifier`. Callers translate to localized text. label keeps codec-formatting only. API hygiene: 11 mux/* modules dropped from `pub` to `pub(crate)` — their types are still re-exported from lib.rs, but the modules were leaking low-level EBML/TS/network primitives. Stream trait gets a real rustdoc explaining read-vs-write split. lib.rs grouped re-exports into documented sections. ScanOptions::with_keydb() removed (one-method-per- action rule); use struct literal. Dead-code sweep: removed lookahead.rs (orphan, never declared as mod), tsreader.rs (TsDemuxReader unused), ebml::{write_int,read_vint,SEEK_}, ts::{scan_first/last_pts,scan_duration,SCAN_HEAD/TAIL_SIZE,take/set_ remainder}, MkvMuxer codec_private_slots/filled fields and fill_codec_private method (deferred-codecPrivate path never used since the v0.10 PES rewrite). cargo clippy --all-targets -D warnings clean. Tests: new error::tests for variant codes + Display "no English" guard + io::ErrorKind mapping. 233 lib tests, all green (was 230). Breaking: ScanOptions::with_keydb removed; mux/ modules pub(crate); AudioStream and SubtitleStream gained required fields; UnsupportedDrive { product_revision: "Renesas not yet implemented" } no longer produced (use PlatformNotImplemented).	2026-04-24 16:41:02 -07:00