WIP: OEM disc-keys CDB path — parked pending CDB template discovery

Adds a 5th key-resolution path (KeySource::OemDiscKeys) that uses a
per-drive OEM CDB to retrieve disc-key candidates from drive firmware,
then validates each as a Media Key against the MKB's verify record
before deriving VUK and unit keys.

End-to-end plumbing is in place: handshake-side capture, best-effort
propagation through HandshakeResult, short-circuit in resolve_encryption
ahead of the classical Path 1-4 chain, validate_media_key_against_mkb
helper with unit tests, two new error variants.

Not usable yet:
- No drive profile populates the read_disc_keys_cdb template.
- Semantic of returned bytes is unconfirmed. Current code assumes MK
  candidates; PK candidates is a more architecturally sensible
  alternative (PKs are per-MKBv finite-set, MKs are per-disc).
  Either interpretation needs empirical confirmation against a drive
  whose firmware actually exposes a disc-keys CDB.
- src/aacs/verify_magics.rs has speculative non-spec constants and
  RE-provenance prose; must not ship to public repos in current form.

Parked here so the plumbing survives if/when the CDB bytes turn up.

.github/dependabot.yml

@@ -1,63 +0,0 @@
-version: 2
-
-# Dependency updates land on `dev`, never on `main`.
-#
-# `main` here is a RELEASE POINTER that release.sh moves to each tag. A bot
-# commit on it would put work there that no tag contains, which is exactly the
-# state that aborted the 1.6.2 cascade at the last step -- so pointing
-# Dependabot at main would recreate that failure on a schedule.
-updates:
-  - package-ecosystem: cargo
-    directory: /
-    target-branch: dev
-    schedule:
-      interval: weekly
-    open-pull-requests-limit: 5
-    # One PR per week for the routine bumps instead of one per crate. Eight
-    # repos times a handful of crates is a volume nobody reads, and an
-    # unread PR queue is indistinguishable from no updates at all.
-    groups:
-      minor-and-patch:
-        update-types:
-          - minor
-          - patch
-    ignore:
-      # The freemkv crates depend on each other by GIT TAG, re-pinned by
-      # release.sh as part of the release commit. Dependabot cannot see that
-      # cascade, so a PR bumping one of these would fight the release process
-      # and could pin a version whose tag does not exist yet.
-      - dependency-name: freemkv-unlock
-      - dependency-name: libfreemkv
-      - dependency-name: freemkv-keysources
-      - dependency-name: freemkv-i18n
-      - dependency-name: freemkv-engine
-
-  # The workflows are now real infrastructure -- the release cascade, the
-  # cross-platform hash matrix, the disc gate -- so their actions need the same
-  # attention as the crates.
-  - package-ecosystem: github-actions
-    directory: /
-    target-branch: dev
-    schedule:
-      interval: weekly
-    open-pull-requests-limit: 5
-    groups:
-      actions:
-        update-types:
-          - minor
-          - patch
-    ignore:
-      # NOT a dependency: `dtolnay/rust-toolchain` is versioned by the RUST
-      # release it installs, and the tag we pin is the toolchain CI is pinned
-      # to on purpose -- precommit.sh runs the same one locally so a lint that
-      # passes on a developer's newer default cannot pass CI by accident.
-      #
-      # Dependabot reads those tags as semver and proposed 1.97.0 -> 1.100.0,
-      # a Rust version that does not exist. Every such PR 404s on toolchain
-      # download across all eight repos, and they regenerate weekly -- eight
-      # permanently-red PRs that promote.yml then has to special-case when it
-      # decides whether dev is green.
-      #
-      # Bumping the toolchain is a deliberate, all-eight-repos change, made by
-      # hand together with precommit.sh. There is nothing here for a bot.
-      - dependency-name: dtolnay/rust-toolchain

.github/workflows/ci.yml

@@ -2,228 +2,41 @@ name: CI
 
 on:
   push:
-    # dev -> qa -> main. `dev` is where work lands and is meant to be pushed
-    # to often: these are the FAST checks, so a mistake surfaces in minutes.
-    # `qa` is the release candidate — it runs these too, plus the expensive
-    # suite in qa.yml. `main` only ever moves at release time, to a tagged
-    # commit that was already green on qa.
-    branches: [main, dev, qa]
+    branches: [main]
   pull_request:
 
 jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
-        with:
-          path: libfreemkv
-      # libfreemkv path-deps ../freemkv-unlock on the BRANCH tip (release.sh
-      # swaps it to a git tag only inside the tagged commit, then restores the
-      # path dep). CI checks out one repo, so the branch tip has never been
-      # buildable here — every green run you have ever seen was a tag build,
-      # and Windows/Linux were first compiled at release time.
-      #
-      # Both repos go into subdirectories because actions/checkout refuses a
-      # `path:` outside $GITHUB_WORKSPACE, and `../freemkv-unlock` is outside.
-      # With this layout the path dep resolves exactly as it does locally.
-      - uses: actions/checkout@v7
-        with:
-          repository: freemkv/freemkv-unlock
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: freemkv-unlock
-      - uses: dtolnay/rust-toolchain@1.97.0
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@1.86.0
         with:
           components: clippy, rustfmt
-      - uses: Swatinem/rust-cache@v2
-        with:
-          workspaces: libfreemkv
       - run: cargo fmt --check
-        working-directory: libfreemkv
       # libfreemkv is a library — Cargo.lock is gitignored. --locked
       # would always fail on a fresh runner because there's no committed
       # lockfile to lock against. The binary crates (freemkv, autorip,
       # bdemu) track Cargo.lock and DO use --locked.
-      # --all-targets so TEST code is linted too. Without it this crate — the
-      # reference implementation for the other seven — was the only one whose
-      # tests had never been linted at all, and it was hiding 74 findings.
-      - run: cargo clippy --all-targets -- -D warnings
-        working-directory: libfreemkv
+      - run: cargo clippy -- -D warnings
 
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
-        with:
-          path: libfreemkv
-      # libfreemkv path-deps ../freemkv-unlock on the BRANCH tip (release.sh
-      # swaps it to a git tag only inside the tagged commit, then restores the
-      # path dep). CI checks out one repo, so the branch tip has never been
-      # buildable here — every green run you have ever seen was a tag build,
-      # and Windows/Linux were first compiled at release time.
-      #
-      # Both repos go into subdirectories because actions/checkout refuses a
-      # `path:` outside $GITHUB_WORKSPACE, and `../freemkv-unlock` is outside.
-      # With this layout the path dep resolves exactly as it does locally.
-      - uses: actions/checkout@v7
-        with:
-          repository: freemkv/freemkv-unlock
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: freemkv-unlock
-      - uses: dtolnay/rust-toolchain@1.97.0
-      - uses: Swatinem/rust-cache@v2
-        with:
-          workspaces: libfreemkv
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@1.86.0
       - run: cargo test --tests
-        working-directory: libfreemkv
 
   check-macos:
-    # dev is the FAST lane: this job still runs, but on the release-candidate
-    # branches rather than on every push to dev. Nothing is deleted and no
-    # platform stops being checked before a release -- qa.yml independently
-    # covers macOS and Windows, and the jobs unique to this file (the Intel
-    # macOS build, the Windows release build) run here on qa and main. A push
-    # to dev is meant to be cheap and frequent; waiting on three runner pools
-    # to agree is what a release candidate is for.
-    #
-    # `if` SKIPS the job (it does not queue). A queued job would be far worse
-    # than a slow one: release.sh's CI gate refuses while any run for the
-    # commit is still in progress, so a never-scheduled job blocks releases
-    # silently -- see the note on real-media in qa.yml.
-    if: github.ref_name == 'qa' || github.ref_name == 'main'
     runs-on: macos-latest
     steps:
-      - uses: actions/checkout@v7
-        with:
-          path: libfreemkv
-      # libfreemkv path-deps ../freemkv-unlock on the BRANCH tip (release.sh
-      # swaps it to a git tag only inside the tagged commit, then restores the
-      # path dep). CI checks out one repo, so the branch tip has never been
-      # buildable here — every green run you have ever seen was a tag build,
-      # and Windows/Linux were first compiled at release time.
-      #
-      # Both repos go into subdirectories because actions/checkout refuses a
-      # `path:` outside $GITHUB_WORKSPACE, and `../freemkv-unlock` is outside.
-      # With this layout the path dep resolves exactly as it does locally.
-      - uses: actions/checkout@v7
-        with:
-          repository: freemkv/freemkv-unlock
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: freemkv-unlock
-      - uses: dtolnay/rust-toolchain@1.97.0
-      - uses: Swatinem/rust-cache@v2
-        with:
-          workspaces: libfreemkv
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@1.86.0
       - run: cargo check
-        working-directory: libfreemkv
 
   check-windows:
-    # dev is the FAST lane: this job still runs, but on the release-candidate
-    # branches rather than on every push to dev. Nothing is deleted and no
-    # platform stops being checked before a release -- qa.yml independently
-    # covers macOS and Windows, and the jobs unique to this file (the Intel
-    # macOS build, the Windows release build) run here on qa and main. A push
-    # to dev is meant to be cheap and frequent; waiting on three runner pools
-    # to agree is what a release candidate is for.
-    #
-    # `if` SKIPS the job (it does not queue). A queued job would be far worse
-    # than a slow one: release.sh's CI gate refuses while any run for the
-    # commit is still in progress, so a never-scheduled job blocks releases
-    # silently -- see the note on real-media in qa.yml.
-    if: github.ref_name == 'qa' || github.ref_name == 'main'
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v7
-        with:
-          path: libfreemkv
-      # libfreemkv path-deps ../freemkv-unlock on the BRANCH tip (release.sh
-      # swaps it to a git tag only inside the tagged commit, then restores the
-      # path dep). CI checks out one repo, so the branch tip has never been
-      # buildable here — every green run you have ever seen was a tag build,
-      # and Windows/Linux were first compiled at release time.
-      #
-      # Both repos go into subdirectories because actions/checkout refuses a
-      # `path:` outside $GITHUB_WORKSPACE, and `../freemkv-unlock` is outside.
-      # With this layout the path dep resolves exactly as it does locally.
-      - uses: actions/checkout@v7
-        with:
-          repository: freemkv/freemkv-unlock
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: freemkv-unlock
-      - uses: dtolnay/rust-toolchain@1.97.0
-      - uses: Swatinem/rust-cache@v2
-        with:
-          workspaces: libfreemkv
-      # Build the tests (not just `cargo check`): catches errors in test
-      # code and forces full codegen of the Windows-only SPTI transport
-      # (src/scsi/windows.rs), which never compiles on the Linux/macOS dev
-      # hosts. We don't `cargo test` here — the suite needs no drive but the
-      # extra build is the value; running tests is covered by the Linux job.
-      - run: cargo build --tests
-        working-directory: libfreemkv
-
-  # ── Did this change break anything downstream? ──────────────────────────────
-  #
-  # Every job above proves libfreemkv builds. None proved its DEPENDENTS do,
-  # and that gap is real: an engine signature change broke autorip today and
-  # went unnoticed because consumer CI only fires on a push to that consumer.
-  # libfreemkv sits below all five of them, so a break here is worth strictly
-  # more than a break anywhere else in the project.
-  #
-  # `cargo check --all-targets` only — each dependent owns its own behaviour
-  # and has its own suite. The question here is just "does everything built on
-  # me still compile against this commit".
-  consumers:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-        with: { path: libfreemkv }
-      - uses: actions/checkout@v7
-        with: { repository: freemkv/freemkv-unlock, ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}", path: freemkv-unlock }
-      - uses: actions/checkout@v7
-        with: { repository: freemkv/freemkv-keysources, ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}", path: freemkv-keysources }
-      - uses: actions/checkout@v7
-        with: { repository: freemkv/freemkv-engine, ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}", path: freemkv-engine }
-      - uses: actions/checkout@v7
-        with: { repository: freemkv/freemkv-i18n, ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}", path: freemkv-i18n }
-      - uses: actions/checkout@v7
-        with: { repository: freemkv/freemkv, ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}", path: freemkv }
-      - uses: actions/checkout@v7
-        with: { repository: freemkv/autorip, ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}", path: autorip }
-      - uses: actions/checkout@v7
-        with: { repository: freemkv/bdemu, ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}", path: bdemu }
-      - name: Point every dependent at THIS libfreemkv commit
-        shell: bash
-        run: |
-          for c in freemkv-keysources freemkv-engine freemkv autorip bdemu; do
-            mkdir -p "$c/.cargo"
-            cat > "$c/.cargo/config.toml" <<'EOF'
-          [patch.crates-io]
-          libfreemkv = { path = "../libfreemkv" }
-          freemkv-keysources = { path = "../freemkv-keysources" }
-          freemkv-engine = { path = "../freemkv-engine" }
-          freemkv-i18n = { path = "../freemkv-i18n" }
-          EOF
-          done
-      - uses: dtolnay/rust-toolchain@1.97.0
-      - uses: Swatinem/rust-cache@v2
-        with:
-          workspaces: |
-            freemkv-keysources
-            freemkv-engine
-            freemkv
-            autorip
-            bdemu
-      # `cargo check` alone only proves the dependents still COMPILE against
-      # this commit. It cannot see a behavioural change — the library keeps its
-      # signatures and a dependent's tests start failing. That is the shape of
-      # every defect worth catching here, so run their suites too.
-      - run: cargo test --tests
-        working-directory: freemkv-keysources
-      - run: cargo test --tests
-        working-directory: freemkv-engine
-      - run: cargo test --tests
-        working-directory: freemkv
-      - run: cargo test --tests
-        working-directory: autorip
-      - run: cargo test --tests
-        working-directory: bdemu
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@1.86.0
+      - run: cargo check

.github/workflows/leak-guard.yml

@@ -1,35 +0,0 @@
-name: leak-guard
-
-# Self-contained public-repo leak gate. Public CI cannot reach the private
-# tooling, so this encodes only the generic net: internal-infra references,
-# tracked CLAUDE.md/.claude paths, and AI-attribution in commit messages.
-# No project-specific reverse-engineering vocabulary lives here.
-
-on: [push, pull_request]
-
-jobs:
-  leak-guard:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-        with:
-          fetch-depth: 0
-      - name: Compute commit range
-        id: range
-        run: |
-          if [ "${{ github.event_name }}" = "pull_request" ]; then
-            base="${{ github.event.pull_request.base.sha }}"
-            head="${{ github.event.pull_request.head.sha }}"
-            echo "range=$base..$head" >> "$GITHUB_OUTPUT"
-          else
-            before="${{ github.event.before }}"
-            after="${{ github.sha }}"
-            # New branch / first push: github.event.before is all-zeros.
-            if [ -z "$before" ] || [ "$before" = "0000000000000000000000000000000000000000" ]; then
-              echo "range=$after" >> "$GITHUB_OUTPUT"
-            else
-              echo "range=$before..$after" >> "$GITHUB_OUTPUT"
-            fi
-          fi
-      - name: Run leak-guard
-        run: bash ci/leak-guard.sh "${{ steps.range.outputs.range }}"

.github/workflows/qa.yml

@@ -1,133 +0,0 @@
-name: qa
-
-# ── The qa gate: "is this production worth?" ────────────────────────────────
-#
-# dev -> qa -> main.
-#
-# `dev` is for committing often. ci.yml answers "is it green" in minutes with
-# fmt, clippy and the unit suite, so a mistake surfaces while it is still cheap
-# to fix. `qa` is the release-candidate branch, and THIS workflow is the claim
-# that a commit is production worth: everything expensive that can run without
-# physical media. `main` only ever receives a qa that went green here.
-#
-# Sibling repos are checked out at `qa`, NOT `dev`. A qa run that resolved its
-# dependencies from dev tips would be validating a combination that is not the
-# one being released, which is the exact failure this branch exists to prevent.
-#
-# What this gate CANNOT cover: `disc://` and real `iso://` need physical media,
-# and no hosted runner has an optical drive or the image hoard. Those run on a
-# self-hosted runner (see the media job at the end) and are the one leg that
-# stays on hardware.
-on:
-  push:
-    branches: [qa]
-  workflow_dispatch:
-
-jobs:
-  # ── Name the candidate ────────────────────────────────────────────────
-  #
-  # Every push to `qa` is a release candidate, so every push gets a tag:
-  # v<version>-rc<N>, N incrementing. That is the answer to "which build is on
-  # qa right now, and is it the one I tested?" — a question that otherwise gets
-  # answered from memory.
-  #
-  # This runs FIRST and does not depend on the gates, deliberately. A red
-  # candidate needs a name more than a green one does: "rc3 failed
-  # release-tests on windows" is a sentence you can act on; "qa is red" is not.
-  # Red on qa is a working gate, not an incident — it is the branch saying this
-  # is not production worth yet. Fix on dev, get dev green, push qa again.
-  #
-  # release.yml excludes v*-rc* so a candidate never publishes a release.
-  rc-tag:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@v7
-        with:
-          fetch-depth: 0
-      - name: Stamp the next rc
-        shell: bash
-        run: |
-          set -euo pipefail
-          v=$(sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -1)
-          [ -n "$v" ] || { echo "no version in Cargo.toml" >&2; exit 1; }
-          # Numeric sort on the rc ordinal: -rc10 must beat -rc9, and a plain
-          # lexical sort gets that backwards from the tenth candidate on.
-          n=$(git tag -l "v$v-rc*" | sed "s|^v$v-rc||" | sort -n | tail -1)
-          tag="v$v-rc$(( ${n:-0} + 1 ))"
-          git tag "$tag"
-          git push origin "$tag"
-          echo "### Candidate \`$tag\`" >> "$GITHUB_STEP_SUMMARY"
-
-  # The debug suite runs on every dev push. Release is a DIFFERENT build:
-  # overflow checks are off, debug_assert! is compiled out, and inlining
-  # changes what the optimiser can prove. A test that only passes in debug is
-  # a test that never guarded the binary anyone actually ships.
-  release-tests:
-    strategy:
-      fail-fast: false
-      matrix:
-        os: ['ubuntu-latest', 'macos-latest']
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v7
-        with:
-          path: libfreemkv
-      - uses: actions/checkout@v7
-        with:
-          repository: freemkv/freemkv-unlock
-          ref: qa
-          path: freemkv-unlock
-      - uses: dtolnay/rust-toolchain@1.97.0
-      - uses: Swatinem/rust-cache@v2
-        with:
-          workspaces: libfreemkv
-      - run: cargo test --release --tests
-        working-directory: libfreemkv
-
-  # clippy's output is target-dependent: cfg-gated code only gets linted on
-  # the target it compiles for. Linting solely on the dev machine's host
-  # target is how a lint that CI rejects reaches a push.
-  cross-lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-        with:
-          path: libfreemkv
-      - uses: actions/checkout@v7
-        with:
-          repository: freemkv/freemkv-unlock
-          ref: qa
-          path: freemkv-unlock
-      - uses: dtolnay/rust-toolchain@1.97.0
-        with:
-          components: clippy
-      - uses: Swatinem/rust-cache@v2
-        with:
-          workspaces: libfreemkv
-      - run: rustup target add x86_64-unknown-linux-gnu
-      - run: cargo clippy --all-targets --target x86_64-unknown-linux-gnu -- -D warnings
-        working-directory: libfreemkv
-
-  # Windows compiles the tests but does not run them, matching the policy
-  # ci.yml already set. The value here is codegen: the #[cfg(windows)] halves
-  # of the SCSI transport and platform layers compile on no other runner, so
-  # without this they are first built at release time.
-  windows-build:
-    runs-on: windows-latest
-    steps:
-      - uses: actions/checkout@v7
-        with:
-          path: libfreemkv
-      - uses: actions/checkout@v7
-        with:
-          repository: freemkv/freemkv-unlock
-          ref: qa
-          path: freemkv-unlock
-      - uses: dtolnay/rust-toolchain@1.97.0
-      - uses: Swatinem/rust-cache@v2
-        with:
-          workspaces: libfreemkv
-      - run: cargo build --release --tests
-        working-directory: libfreemkv

.github/workflows/release.yml

@@ -4,11 +4,6 @@ on:
   push:
     tags:
       - 'v*'
-      # NOT the release-candidate tags. Every push to `qa` stamps a
-      # v<version>-rc<N> so a run can be named, and 'v*' matches those too —
-      # which would have this workflow build and PUBLISH a GitHub release for
-      # every candidate, including the red ones.
-      - '!v*-rc*'
 
 permissions:
   contents: write
@@ -17,7 +12,7 @@ jobs:
   verify:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
       - name: Verify Cargo.toml version matches tag
         run: |
           CARGO_VER="v$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')"
@@ -27,37 +22,33 @@ jobs:
           fi
           echo "Version match: $CARGO_VER"
 
-  # Tests run as a PARALLEL TRIPWIRE: they fail the run if they fail, but the
-  # publish/release jobs do NOT `needs:` this job. The tag decision was already
-  # gated by the local precommit (same Rust 1.97, same commit). Binary consumers
-  # (freemkv/autorip/bdemu) git-tag-pin libfreemkv and therefore start building
-  # the instant this tag exists — so this test job and the crates.io publish
-  # below must NOT sit on their critical path.
   test:
     needs: verify
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
-      - uses: dtolnay/rust-toolchain@1.97.0
-      - uses: Swatinem/rust-cache@v2
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@1.86.0
       # libfreemkv is a library — Cargo.lock isn't tracked, so --locked
       # would always fail (no lockfile to lock against on a fresh runner).
       - run: cargo test
 
-  # NOTE: there is no crates.io publish job. libfreemkv is git-tag-only
-  # (`package.publish = false` — it git-deps the firmware crate freemkv-unlock,
-  # which never ships to crates.io). Every consumer git-tag-pins libfreemkv via
-  # a committed [patch.crates-io]; the git tag itself IS the release artifact.
-  # A `cargo publish` here fails hard on `publish = false`, so it was removed.
-
-  release:
-    # Only needs `verify`; the GitHub Release can be cut as soon as the version
-    # check passes, in parallel with test + publish.
-    needs: verify
+  publish:
+    needs: test
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@1.86.0
+      - name: Publish to crates.io
+        run: cargo publish
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+
+  release:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@v3
+        uses: softprops/action-gh-release@v2
         with:
           generate_release_notes: true

.github/workflows/update-readme.yml

@@ -0,0 +1,36 @@
+name: Update README version
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: main
+          token: ${{ secrets.ORG_DISPATCH_TOKEN }}
+
+      - name: Update version in README
+        run: |
+          VERSION="${{ github.event.release.tag_name }}"
+          FILE="README.md"
+
+          # Update cargo dependency version (e.g. "0.2" -> "0.3")
+          MAJOR_MINOR="${VERSION#v}"
+          MAJOR_MINOR="${MAJOR_MINOR%.*}"
+          sed -i "s|libfreemkv = \"[0-9]*\.[0-9]*\"|libfreemkv = \"${MAJOR_MINOR}\"|" "$FILE"
+
+      - name: Commit and push
+        run: |
+          VERSION="${{ github.event.release.tag_name }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add README.md
+          git diff --cached --quiet || git commit -m "Update to libfreemkv ${VERSION}"
+          git push

.gitignore

@@ -4,22 +4,4 @@ Cargo.lock
 *.swo
 .DS_Store
 .cargo/
-
-# session scratch — never track (may contain RE breadcrumbs)
-scratch/
-
-# stray local build artifact
-/rust_out
-
-# internal agent context — never publish (path AND dir; leak-guard blocks both)
-CLAUDE.md
-.claude/
-
-# Nightly harness output. Written into the repo it audits, and it embeds
-# absolute paths from the machine that ran it — which must never reach a public
-# repo. Ignored rather than relocated so a run from any working copy is safe.
-.nightly/
-
-# cargo-mutants working output: large, machine-specific, never committed
-mutants.out/
-mutants.out.old/
+.claude/worktrees/

CLAUDE.md

@@ -0,0 +1,94 @@
+# libfreemkv — Rules
+
+## No English in library code
+
+The library contains ZERO user-facing English text. All errors use numeric codes from `error.rs`. Applications (CLI, GUI, server) handle i18n.
+
+- `io::Error::new(kind, "english string")` — NEVER. Use `Error::VariantName.into()`.
+- If you need a new error, add a variant to `error.rs` with a code, not a string.
+- Acceptable strings: debug/trace logging, test assertions, comments, data format strings (paths, codec IDs).
+- `Error` implements `From<Error> for io::Error` — use `?` or `.into()` anywhere an `io::Error` is expected.
+
+## Architecture
+
+- **Streams are PES.** Every stream reads its format → PES frames out, or PES frames in → writes its format. One type per format.
+- **Disc::copy() for sector dumps.** disc→ISO is NOT a stream. It's `Disc::copy()`.
+- **DiscStream = any disc.** Physical drive or ISO file. Same type, different SectorReader.
+- **No IOStream.** Deleted. No byte-level Read/Write on streams.
+- **Streams don't know their size.** Progress/file_size is a CLI concern.
+- **One method per action.** No `foo_with_X` variants. Use `Option<T>` params.
+- **Streams impl Read only (conceptually).** No Seek, no File backing.
+- **Functions return errors, only main() exits.** No `process::exit` in library code.
+
+## Device rules
+
+- Always use `/dev/sg*` not `/dev/sr*` for SCSI.
+- `--raw` only skips decryption. Init/probe/speed still run.
+- Each function does one thing. One runner orchestrates the sequence.
+
+## AACS key sources
+
+Single source: `keydb.cfg`. Located at `~/.config/freemkv/keydb.cfg` by
+default, or pointed at via `ScanOptions::keydb_path`. The file holds
+all DKs, PKs, host certs, and per-disc VUK entries. No keys are
+compiled into the binary.
+
+CSS player keys (DVD) remain compiled in — they're 1999-era public
+inputs separate from the AACS key pipeline and have always lived in
+`src/css/auth.rs`.
+
+The library treats a missing `keydb.cfg` for an AACS-encrypted disc as
+`Error::KeydbLoad` with the sentinel path `<no keydb in search paths>`.
+CLIs render this as "no KEYDB.cfg found"; consumers can disambiguate
+on the sentinel string.
+
+## macOS IOKit transport
+
+The macOS SCSI transport uses exclusive IOKit access, not hybrid MMC+pread.
+
+- **C shim** (`src/scsi/macos_shim.c`):
+  - `shim_open_exclusive(bsd_name)`: `diskutil unmountDisk force` on target device only → find `IOBDServices` matching BSD name via IOKit registry walk → MMCDeviceInterface → SCSITaskDeviceInterface → `ObtainExclusiveAccess` → raw CDB dispatch.
+  - `shim_list_drives()`: registry-based enumeration. Walks all `IOBDServices` entries, reads `"Device Characteristics"` for vendor/model/firmware, walks child chain to `IOMedia` for BSD name. Zero SCSI, zero exclusive access, zero unmounts.
+  - `shim_execute()` / `shim_close()`: raw CDB dispatch and cleanup.
+- **Build** (`build.rs`): compiles shim via `cc` into static lib, linked by Cargo. NOT the `cc` crate (produces object code that breaks IOKit exclusive access).
+- **Rust** (`src/scsi/macos.rs`): FFI to `shim_open_exclusive`, `shim_close`, `shim_execute`, `shim_list_drives`. `list_drives()` uses registry-based enumeration. `MacScsiTransport::open()` uses exclusive access only when ripping a specific device.
+- **IOBDServices parent chain**: IOSCSIPeripheralDeviceType05 → IOBDServices → IOBDBlockStorageDriver → IOMedia (has `"BSD Name"`). The shim walks this chain to match BSD name to IOBDServices.
+- **IOKit lookup order**: (1) iterate all IOBDServices → match child IOMedia BSD name, (2) fallback: find IOMedia by BSD name → walk parent chain to IOBDServices, (3) fallback: first IOBDServices (single-drive systems).
+- **Test disc**: DUNE_PART_TWO UHD, `/dev/disk6`, ~84.6 GB.
+
+## Bad-sector handling (BU40N + Initio INIC-1618L)
+
+Three failure modes on this USB bridge:
+1. **NOT READY** (sense_key=2, ASC=0x04, ASCQ=0x3E) — most common on BU40N for bad sectors. Pause 3s, retry up to 3x, then mark NonTrimmed.
+2. **Transport failure** (status=0xFF) — bridge crash, auto-recovers ~15s. Aborts copy.
+3. **INCOMPATIBLE FORMAT** (ASC=0x30) wedge — ALL sectors fail, requires power cycle.
+
+### Damage-jump algorithm (Pass 1 sweep)
+
+When `skip_on_error=true` (multipass mode):
+- Read each ECC block sequentially. Track a sliding window of the last 16 ECC block results.
+- On error: zero-fill, mark NonTrimmed, push `false` to window.
+- On success: write data, mark Finished, push `true` to window. Track consecutive good count.
+- When ≥12% of the 16-block window are failures → **jump** ahead by `JUMP_BASE_SECTORS (1024) × batch × multiplier` sectors. For UHD encrypted ECC (batch=32) that's a 64 MiB base jump. Zero-fill the gap as NonTrimmed. Double the multiplier (64→128→256→512 MiB...) up to `MAX_JUMP_MULTIPLIER=64` (4 GiB cap). Plus a separate wedge-skip path of `WEDGE_JUMP_SECTORS=524288` (1 GiB) for HARDWARE_ERROR / ILLEGAL_REQUEST senses, capped at 16 consecutive wedges.
+- When 16 consecutive good reads → reset multiplier to 1, restore max read speed.
+- Only transport failures (bridge crash) abort the pass.
+
+Tuning knobs: `DAMAGE_WINDOW=16` and `DAMAGE_THRESHOLD_PCT=12%`. Calibrated from live BU40N data: old 50/25% was too diluted by good reads between sparse failures; 16/12% triggers on the 2nd scattered failure (2/16 = 12.5% ≥ 12%).
+
+### Patch (Pass N) — `disc/mod.rs:1910`
+
+- Default: **reverse** mode. Walks bad ranges from highest LBA to lowest, and within each range from end to start. Rationale: sweep jumps forward with escalating gaps, so NonTrimmed ranges have good data at their tail (where the jump landed). Reverse hits good data first, converges on actual bad block boundaries.
+- Single-sector reads with 60 s timeout (`READ_RECOVERY_TIMEOUT_MS`).
+- NOT_READY (sense=2, ASC ∈ {0x02, 0x03, 0x04}): 15 s pause, retry without immediate Unreadable mark.
+- Non-marginal SCSI sense → mark Unreadable and continue.
+- Skip escalation: damage window 16, `PASSN_DAMAGE_THRESHOLD_PCT=6`, skip `PASSN_SKIP_SECTORS_BASE (32) << escalation` sectors capped at `PASSN_SKIP_SECTORS_CAP=4096`; `MAX_SKIPS_PER_RANGE=10`, then mark range Unreadable.
+- Wedge exit: 50 consecutive failures **and** ≥ 2 ranges attempted (single-range stalls don't kill the pass).
+- Whole-pass watchdog: `STALL_SECS = 3600` on `bytes_good`. Per-range watchdog: proportional `range_sectors × SECONDS_PER_SECTOR(25)`, capped at `RANGE_BUDGET_CAP_SECS=1800` (replaces the old flat 180s/range — tiny ranges got starved).
+
+Constants live in `disc/patch.rs::Disc::patch` (PASSN_*, STALL_SECS, SECONDS_PER_SECTOR, RANGE_BUDGET_CAP_SECS, MAX_SKIPS_PER_RANGE). The full algorithm is documented in `freemkv-private/memory/project_recovery_v0_16.md`.
+
+## Public repo rules
+
+- **No internal docs.** Audit reports, test plans, roadmaps, TODOs go in freemkv-private, never here.
+- **No Co-Authored-By** in commit messages. One contributor: MattJackson.
+- **No private references.** No Gitea URLs, no /data/code paths, no internal IPs in code.

CODE_OF_CONDUCT.md

@@ -1,83 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment for our community include:
-
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall community
-
-Examples of unacceptable behavior include:
-
-* The use of sexualized language or imagery, and sexual attention or advances of any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email address, without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a professional setting
-
-## Enforcement Responsibilities
-
-Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
-
-Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
-
-## Scope
-
-This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported privately to the project maintainer via GitHub at https://github.com/MattJackson. All complaints will be reviewed and investigated promptly and fairly.
-
-All community leaders are obligated to respect the privacy and security of the reporter of any incident.
-
-## Enforcement Guidelines
-
-Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
-
-### 1. Correction
-
-**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
-
-**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
-
-### 2. Warning
-
-**Community Impact**: A violation through a single incident or series of actions.
-
-**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
-
-### 3. Temporary Ban
-
-**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
-
-**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
-
-### 4. Permanent Ban
-
-**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within the community.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
-
-Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
-
-For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
-
-[homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-[Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
-[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -24,4 +24,4 @@ cargo test
 
 ## License
 
-By contributing, you agree your code will be licensed under MIT.
+By contributing, you agree your code will be licensed under AGPL-3.0.

Cargo.toml

@@ -1,50 +1,38 @@
 [package]
 name = "libfreemkv"
-version = "1.6.6"
+version = "0.26.0"
 edition = "2024"
-rust-version = "1.97"
-license = "MIT"
+rust-version = "1.86"
+license = "AGPL-3.0-only"
 description = "Open source raw disc access library for optical drives"
 repository = "https://github.com/freemkv/libfreemkv"
 keywords = ["bluray", "uhd", "optical", "scsi", "disc"]
 categories = ["hardware-support", "multimedia"]
-# Keep internal AI-instruction / private notes out of the published crate.
-exclude = ["CLAUDE.md"]
-# OFF crates.io: libfreemkv git-deps freemkv-unlock (firmware, never published),
-# so libfreemkv itself can only be consumed by git tag. Clients git-tag-pin it.
-publish = false
-
-[profile.release]
-lto = "thin"
-codegen-units = 1
 
 [dependencies]
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 sha1 = "0.10"
-aes = "0.9"
-# Interim path dep for local cross-repo dev; the release script re-pins this to
-# `{ git = ".../freemkv-unlock", tag = "vX.Y.Z" }` before tagging libfreemkv (so
-# the released tag resolves freemkv-unlock from git, not a sibling path).
-freemkv-unlock = { git = "https://github.com/freemkv/freemkv-unlock", tag = "v1.6.5" }
-rand = "0.10"
-zip = { version = "8", default-features = false, features = ["deflate"] }
-base64 = "0.23"
-# Read-only XML DOM parser (pure Rust, forbid(unsafe_code), entity-expansion
-# bounded). Parses the HD-DVD Advanced-Content playlist `ADV_OBJ/VPLST000.XPL`
-# — untrusted disc bytes — into authoritative titles/clips/chapters. A real
-# parser, not a hand-rolled scanner: the XPL is genuine XML (comments, varied
-# attribute order, self-closing tags).
-roxmltree = "0.20"
-# Trace-level instrumentation for the read/transport path (SgIoTransport::execute
-# and friends). Permitted
+sha2 = "0.10"
+aes = "0.8"
+cbc = "0.1"
+flate2 = "1"
+num-bigint = "0.4"
+num-traits = "0.2"
+num-integer = "0.1"
+rand = "0.8"
+cmac = "0.7"
+zip = { version = "2", default-features = false, features = ["deflate"] }
+base64 = "0.22.1"
+# Trace-level instrumentation for Disc::copy + SgIoTransport::execute. Permitted
 # under CLAUDE.md ("Acceptable strings: debug/trace logging"). Consumers (autorip)
 # wire a tracing subscriber and pipe events into the JSONL debug log.
 tracing = "0.1"
 # Bounded MPSC channel with kernel-wakeup send_timeout. Used by `io::pipeline`
 # so the halt-aware send/finish loops can BLOCK on consumer drain instead of
 # polling — the 50 ms poll cadence of the previous mpsc-based impl capped mux
-# throughput at ~1 MB/s (0.21.7).
+# throughput at ~1 MB/s (see freemkv-private/memory/
+# feedback_send_with_halt_poll_throttle.md, 0.21.7).
 crossbeam-channel = "0.5"
 # Persistent work-stealing thread pool for parallel AACS unit
 # decryption. Per-call std::thread::scope spawned fresh OS threads

LICENSE

@@ -1,21 +1,16 @@
-MIT License
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
 
-Copyright (c) 2026 Matthew Jackson & Contributors
+Copyright (C) 2026 FreeMKV Contributors
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published
+by the Free Software Foundation, version 3 of the License.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.

Makefile

@@ -1,5 +1,6 @@
 # libfreemkv — local dev helper.
-# Mirrors the workspace-wide CI checks but scoped to this single crate.
+# Mirrors the cross-crate scripts in freemkv-private/scripts/test-all.sh
+# but scoped to this single crate.
 
 .PHONY: test build check ci clean
 

README.md

@@ -1,26 +1,26 @@
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Crates.io](https://img.shields.io/crates/v/libfreemkv)](https://crates.io/crates/libfreemkv)
+[![docs.rs](https://img.shields.io/docsrs/libfreemkv)](https://docs.rs/libfreemkv)
+[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)
 
 # libfreemkv
 
-Rust library for 4K UHD / Blu-ray / DVD optical drives. Drive access, disc scanning, stream labels, AACS decryption, CSS decryption, KEYDB updates, and content reading in one crate. Drive-level unlocking is handled internally; consumers work with disc access and decryption only.
+Rust library for 4K UHD / Blu-ray / DVD optical drives. Drive access, disc scanning, stream labels, AACS decryption, CSS decryption, KEYDB updates, and content reading in one crate. Bundled drive profiles — no external files needed.
 
-DVDs (CSS) decrypt out of the box. Blu-ray and UHD (AACS) require a `keydb.cfg` (default `~/.config/freemkv/keydb.cfg`) supplying disc-specific volume unique keys; no AACS key material is compiled in.
+Built-in keys cover DVDs and Blu-rays (AACS 1.0). For UHD (AACS 2.0 / 2.1) discs, an optional `keydb.cfg` supplies disc-specific volume unique keys.
 
-**12+ MB/s** sustained read speeds on BD. Drive prep (`init()`) handles unlocking internally via the `freemkv-unlock` crate — clients never see it; when no drive unlock applies, the library rips via the host-certificate AACS handshake.
+**12+ MB/s** sustained read speeds on BD. Full init: unlock, firmware upload, speed calibration — all from pure Rust.
 
 Multi-lingual by design — the library outputs structured data and numeric error codes, never English text. Build any UI or localization on top.
 
-**[Source & API](https://github.com/freemkv/libfreemkv)** · **[Technical Docs](docs/)**
+**[API Documentation](https://docs.rs/libfreemkv)** · **[Technical Docs](docs/)**
 
 Part of the [freemkv](https://github.com/freemkv) project.
 
 ## Install
 
-Consumed by git tag (not published to crates.io):
-
 ```toml
 [dependencies]
-libfreemkv = { git = "https://github.com/freemkv/libfreemkv", tag = "vX.Y.Z" }
+libfreemkv = "0.25"
 ```
 
 ## Quick Start
@@ -29,10 +29,10 @@ libfreemkv = { git = "https://github.com/freemkv/libfreemkv", tag = "vX.Y.Z" }
 use libfreemkv::{Drive, Disc, ScanOptions};
 use std::path::Path;
 
-// Open drive — identified via INQUIRY
+// Open drive — profiles are bundled, auto-identified
 let mut drive = Drive::open(Path::new("/dev/sg4"))?;
 drive.wait_ready()?;              // wait for disc
-drive.init()?;                     // unlock + prep (handled internally)
+drive.init()?;                     // unlock + firmware upload
 drive.probe_disc()?;               // probe disc surface for optimal speeds
 
 // Scan disc — UDF, playlists, streams, AACS (all automatic)
@@ -55,19 +55,52 @@ output.finish()?;
 
 ### Multi-pass recovery rip
 
-Recovery moved OUT of this crate in 1.6.0. The sweep/patch strategy, the
-ddrescue mapfile, damage classification and the multipass loop now live in the
-`freemkv-engine` crate as `freemkv_engine::recovery::{copy, sweep, patch}`.
+For damaged discs the library exposes two flat verbs — `Disc::sweep` for the
+forward Pass 1 and `Disc::patch` for retrying bad ranges. The library never
+loops; the multipass policy is the caller's job. See
+[`docs/rip-recovery.md`](docs/rip-recovery.md).
 
-libfreemkv keeps the layers underneath: the raw single-shot read
-(`Drive::read`) and the SCSI-fact translation (`SenseFamily`) that the engine's
-strategy is built on. The dependency runs engine → libfreemkv, so this crate
-cannot call into it; front-ends get recovery from the engine directly. See
-[`docs/rip-recovery.md`](docs/rip-recovery.md) for what stayed here.
+```rust
+use libfreemkv::{SweepOptions, PatchOptions};
+use libfreemkv::disc::{mapfile, mapfile_path_for};
+use std::path::Path;
+
+let iso = Path::new("disc.iso");
+
+// Pass 1: disc → ISO. Skip-on-error, zero-fill, write the sidecar mapfile.
+disc.sweep(&mut drive, iso, &SweepOptions {
+    decrypt: true,
+    resume: false,
+    batch_sectors: None,
+    skip_on_error: true,
+    progress: None,
+    halt: None,
+})?;
+
+// Pass 2..N: retry every non-finished range. Idempotent.
+loop {
+    let map = mapfile::Mapfile::load(&mapfile_path_for(iso))?;
+    let stats = map.stats();
+    if stats.bytes_pending + stats.bytes_unreadable == 0 { break; }
+
+    let outcome = disc.patch(&mut drive, iso, &PatchOptions {
+        decrypt: true,
+        block_sectors: None,
+        full_recovery: true,
+        reverse: true,
+        wedged_threshold: 50,
+        progress: None,
+        halt: None,
+    })?;
+    if outcome.bytes_recovered_this_pass == 0 { break; }
+}
+
+// Mux from the ISO via the normal stream pipeline (no drive involvement).
+```
 
 ## What It Does
 
-- **Drive access** — open, identify, internal unlock + prep, speed control, eject
+- **Drive access** — open, identify, unlock, firmware upload, speed calibration, eject
 - **12+ MB/s reads** — auto-detects kernel transfer limits, sustained full speed
 - **Disc scanning** — UDF 2.50 filesystem, MPLS playlists, CLPI clip info
 - **Stream labels** — 5 BD-J format parsers (Paramount, Criterion, Pixelogic, CTRM, Deluxe)
@@ -81,28 +114,28 @@ cannot call into it; front-ends get recovery from the engine directly. See
 | Stream | Input | Output | Transport |
 |--------|-------|--------|-----------|
 | DiscStream | Yes | -- | Optical drive via SCSI |
-| IsoStream | Yes | -- | Blu-ray ISO image file (read via stream pipeline; written by `freemkv_engine::recovery`) |
+| IsoStream | Yes | -- | Blu-ray ISO image file (read via stream pipeline; written via `Disc::sweep()`) |
 | 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 a single unified `pes::Stream` trait (re-exported as `PesStream`) exposing `read()` and `write()` on one type. `input()` / `output()` resolve URL strings to PES stream instances. All URLs use the `scheme://path` format — bare paths are rejected.
+Streams implement `FrameSource` (read) and/or `FrameSink` (write); direction is type-checked. `input()` / `output()` resolve URL strings to PES stream instances. All URLs use the `scheme://path` format — bare paths are rejected.
 
 ### Keys
 
-DVDs (CSS) decrypt out of the box, with no external key file needed.
+DVDs (CSS) decrypt out of the box — the 1999-era public player keys are compiled into the library.
 
-Blu-rays and UHD (AACS) require a `keydb.cfg` at `~/.config/freemkv/keydb.cfg` (or passed via `ScanOptions`). No AACS key material is compiled into the binary.
+Blu-rays and UHD (AACS) require a `keydb.cfg` at `~/.config/freemkv/keydb.cfg` (or passed via `ScanOptions`). The file holds all DKs, PKs, host certs, and per-disc VUKs. No AACS key material is compiled into the binary.
 
 ## Architecture
 
 ```text
-Drive                  — open, identify, init, single-shot read
+Drive                  — open, identify, init, unlock, single-shot read
   ├── ScsiTransport    — SG_IO (Linux), IOKit (macOS), SPTI (Windows)
-  └── unlock_bridge    — private seam to the freemkv-unlock crate
-                         (firmware / AACS cert / CSS bus-auth unlockers)
+  ├── DriveProfile     — per-drive unlock parameters (bundled)
+  └── PlatformDriver   — MediaTek (supported), Renesas (planned)
 
 Disc                   — scan titles, streams, AACS/CSS state
   ├── UDF reader       — Blu-ray UDF 2.50 with metadata partitions
@@ -111,11 +144,12 @@ Disc                   — scan titles, streams, AACS/CSS state
   ├── IFO parser       — DVD title sets, PGC chains, cell addresses
   ├── Labels           — 5 BD-J format parsers (detect + parse)
   ├── AACS             — key resolution + content decryption
-  ├── CSS              — DVD CSS (bus auth → player-key disc crack → known-plaintext title-key attack)
+  ├── CSS              — DVD CSS cipher (table-driven, no keys needed)
   └── KEYDB            — download + verify + save
 
 Streams                — unified PES pipeline
-  ├── PesStream        — pes::Stream: one trait, read()/write() PES frames
+  ├── FrameSource      — read() PES frames (direction-typed)
+  ├── FrameSink        — write() PES frames (direction-typed)
   ├── DiscStream       — sectors → decrypt → TS demux → PES
   ├── IsoStream        — ISO file → decrypt → TS demux → PES
   ├── MkvStream        — MKV mux/demux
@@ -141,7 +175,6 @@ All errors are structured with numeric codes. No user-facing English text — ap
 | E6xxx | Disc format errors |
 | E7xxx | AACS errors |
 | E8xxx | KEYDB update errors |
-| E9xxx | Stream / mux errors (URL, PES, ISO, pipeline, demux) |
 
 ## Platform Support
 
@@ -153,8 +186,8 @@ All errors are structured with numeric codes. No user-facing English text — ap
 
 ## Contributing
 
-Run `freemkv info disc:// --share` with the [freemkv CLI](https://github.com/freemkv/freemkv) to capture your drive's identity for contribution. Drive-unlock profiles are maintained in the [freemkv-unlock](https://github.com/freemkv/freemkv-unlock) repository.
+Run `freemkv info disc:// --share` with the [freemkv CLI](https://github.com/freemkv/freemkv) to contribute your drive's profile.
 
 ## License
 
-MIT
+AGPL-3.0-only

SECURITY.md

@@ -1,22 +0,0 @@
-# Security Policy
-
-## Supported versions
-
-| Version | Supported |
-| ------- | --------- |
-| 1.6.x   | Yes       |
-| < 1.6   | No        |
-
-Only the current 1.6.x line receives security fixes.
-
-## Reporting a vulnerability
-
-Report vulnerabilities privately through GitHub Security Advisories:
-https://github.com/freemkv/libfreemkv/security/advisories/new
-
-Do not open a public issue for a security report. Include the affected
-version, steps to reproduce, and the impact you believe the issue has.
-
-## Response time
-
-You will get an initial response within 7 days.

TROUBLESHOOTING.md

@@ -141,8 +141,8 @@ If your machine has a free SATA port, use it.
 
 freemkv uses a three-layer recovery model. See [`docs/rip-recovery.md`](docs/rip-recovery.md) for full details.
 
-- **Pass 1 (`freemkv_engine::recovery::sweep`):** Fast sweep with 64 KB reads. On failure, zero-fills the block and skips forward. Writes a ddrescue-format mapfile for later retry.
-- **Pass 2+ (`freemkv_engine::recovery::patch`):** Targeted re-reads of bad ranges with a long 60-second timeout per CDB. The drive firmware performs its own ECC and laser power retries within that window.
+- **Pass 1 (Disc::copy):** Fast sweep with 64 KB reads. On failure, zero-fills the block and skips forward. Writes a ddrescue-format mapfile for later retry.
+- **Pass 2+ (Disc::patch):** Targeted re-reads of bad ranges with a long 30-second timeout per CDB. The drive firmware performs its own ECC and laser power retries within that window.
 - **In-stream (DiscStream):** Adaptive batch halving -- reduces request size on failure to isolate bad sectors within a larger block.
 
 This means a disc with some bad sectors will still produce a usable ISO. The damaged areas are zero-filled in pass 1 and retried in subsequent passes. Structure-protected sectors (deliberate unreadable regions from copy protection) will never yield, which is expected.
@@ -302,7 +302,7 @@ Many external drive enclosures (Vantec NexStar, Sabrent, OWC, etc.) do not adver
 When something goes wrong during a rip, gather this information before filing an issue:
 
 1. **freemkv version:** `freemkv --version` or the crate version in `Cargo.toml`.
-2. **Drive model:** from the drive label, or from `freemkv info disc://`.
+2. **Drive model:** from the drive label, or from `freemkv info`.
 3. **Connection type:** USB (with bridge chipset if known) or direct SATA.
 4. **Operating system and kernel:** `uname -a`.
 5. **Kernel messages during the failure:** `dmesg | tail -50` immediately after the crash.

build.rs

@@ -1,6 +1,4 @@
 fn main() {
-    emit_git_suffix();
-
     let target = std::env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
     if target == "macos" {
         println!("cargo:rustc-link-lib=framework=IOKit");
@@ -10,22 +8,8 @@ fn main() {
         let obj = format!("{out_dir}/macos_shim.o");
         let lib = format!("{out_dir}/libmacos_scsi.a");
 
-        // Build the shim for the TARGET arch, not the host's. A bare `cc` on an
-        // Apple-Silicon CI runner defaults to arm64, so cross-building to
-        // x86_64-apple-darwin would link a host-arch object against x86_64 Rust
-        // code → "Undefined symbols for architecture x86_64". (Still raw `cc`,
-        // not the `cc` crate, which breaks IOKit exclusive access.)
-        let target_arch = std::env::var("CARGO_CFG_TARGET_ARCH").unwrap_or_default();
-        let clang_arch: &str = if target_arch == "aarch64" {
-            "arm64"
-        } else {
-            &target_arch // x86_64 → x86_64
-        };
-
-        let cc_status = std::process::Command::new("cc")
+        std::process::Command::new("cc")
             .args([
-                "-arch",
-                clang_arch,
                 "-c",
                 "src/scsi/macos_shim.c",
                 "-o",
@@ -38,67 +22,15 @@ fn main() {
                 "-O2",
             ])
             .status()
-            .expect("failed to spawn cc for macos_shim.c");
-        // `.status()` succeeding only means the process RAN. A real compile error
-        // exits non-zero, and ignoring that left no object file, which surfaced
-        // much later as an unexplained link failure against a missing symbol. The
-        // shim is macOS-only and is neither linted nor compiled on the other two
-        // platforms, so a mistake in it has exactly one chance to be noticed.
-        assert!(cc_status.success(), "cc failed to compile macos_shim.c");
+            .expect("failed to compile macos_shim.c");
 
-        let ar_status = std::process::Command::new("ar")
+        std::process::Command::new("ar")
             .args(["rcs", &lib, &obj])
             .status()
-            .expect("failed to spawn ar");
-        assert!(ar_status.success(), "ar failed to create the static lib");
+            .expect("failed to create static lib");
 
         println!("cargo:rustc-link-search=native={out_dir}");
         println!("cargo:rustc-link-lib=static=macos_scsi");
         println!("cargo:rerun-if-changed=src/scsi/macos_shim.c");
     }
 }
-
-/// Bake the git short hash into the build as `GIT_SUFFIX` so any muxed MKV or
-/// FVI index is traceable to the exact source revision (e.g. ` (g835cc99)`).
-/// Empty when git or the repo is unavailable (e.g. a crates.io tarball build),
-/// leaving just the package version. Always emitted so `env!("GIT_SUFFIX")`
-/// resolves on every target.
-fn emit_git_suffix() {
-    // Version label for the muxing-app / FVI generator tag. `FREEMKV_BUILD_LABEL`
-    // overrides the Cargo package version when set (non-empty) — used to stamp a
-    // pre-release/test build without bumping Cargo.toml and disturbing the
-    // tag-pinned [patch] version matching. Unset → the package version.
-    let version = std::env::var("FREEMKV_BUILD_LABEL")
-        .ok()
-        .filter(|s| !s.trim().is_empty())
-        .or_else(|| std::env::var("CARGO_PKG_VERSION").ok())
-        .unwrap_or_default();
-    println!("cargo:rustc-env=FREEMKV_VERSION={version}");
-    println!("cargo:rerun-if-env-changed=FREEMKV_BUILD_LABEL");
-
-    let suffix = git_short_hash()
-        .map(|h| format!(" (g{h})"))
-        .unwrap_or_default();
-    println!("cargo:rustc-env=GIT_SUFFIX={suffix}");
-
-    // Re-run when HEAD (or the branch it points at) moves so the stamp stays
-    // current without a clean rebuild.
-    println!("cargo:rerun-if-changed=.git/HEAD");
-    if let Ok(head) = std::fs::read_to_string(".git/HEAD")
-        && let Some(ref_path) = head.strip_prefix("ref: ")
-    {
-        println!("cargo:rerun-if-changed=.git/{}", ref_path.trim());
-    }
-}
-
-fn git_short_hash() -> Option<String> {
-    let out = std::process::Command::new("git")
-        .args(["rev-parse", "--short=7", "HEAD"])
-        .output()
-        .ok()?;
-    if !out.status.success() {
-        return None;
-    }
-    let h = String::from_utf8(out.stdout).ok()?.trim().to_string();
-    if h.is_empty() { None } else { Some(h) }
-}

ci/leak-guard.sh

@@ -1,120 +0,0 @@
-#!/usr/bin/env bash
-#
-# leak-guard.sh — self-contained public-repo leak gate.
-#
-# This is the LAST line of defense in CI. It is intentionally self-contained:
-# public CI cannot reach the private tooling, so this script encodes ONLY the
-# generic net — internal infrastructure references, agent-context files, and
-# AI-attribution in commit messages. It deliberately contains NO project-
-# specific reverse-engineering vocabulary (those words would themselves be a
-# leak). The richer private scanner stays private.
-#
-# Fails (exit 1) if any of the following appear in the repo:
-#   1. a tracked CLAUDE.md or .claude/ path (agent context — never public),
-#   2. tracked file content matching the internal-infra net,
-#   3. a commit message (in the given range) with AI attribution.
-#
-# Usage:
-#   leak-guard.sh [<commit-range>]
-#     <commit-range>  optional git rev-list range to scan commit messages
-#                     (e.g. "abc..def"). If omitted, commit-message scan is
-#                     skipped (path + content checks always run).
-
-set -euo pipefail
-
-# Absolute path to this script, resolved before any cd, so we can exclude it
-# from the content scan (it necessarily contains the detection patterns).
-SELF_ABS="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/$(basename "${BASH_SOURCE[0]}")"
-
-REPO="$(git rev-parse --show-toplevel)"
-cd "$REPO"
-
-fail=0
-note() { printf '  ✗ %s\n' "$1"; fail=1; }
-
-# Internal-infra net — GENERIC ONLY. This script ships in the public repo, so
-# the patterns themselves must not name any org-specific identifier (doing so
-# would itself leak the infra they guard). We catch the leak *class*:
-#   - RFC1918 private IPv4 ranges (10/8, 172.16/12, 192.168/16),
-#   - private/internal/non-routable TLDs (.internal/.local/.lan/.corp/.invalid),
-#   - docker.internal.
-# The full org-specific net (literal hostnames, service names, repo paths,
-# vendor tooling, …) lives ONLY in the private scanner and never ships here.
-INFRA_RE='\b10\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}|\b172\.(1[6-9]|2[0-9]|3[01])\.[0-9]{1,3}\.[0-9]{1,3}|\b192\.168\.[0-9]{1,3}\.[0-9]{1,3}|\.internal\b|\.local\b|\.lan\b|\.corp\b|\.invalid\b|docker\.internal'
-# Home-path net — GENERIC ONLY. Catches an absolute developer home path
-# committed into a tracked file (a macOS /Users/<user>/… or Linux /home/<user>/…
-# path). This names NO specific user — it matches the leak *class* (any home
-# path), so the pattern itself reveals nothing org- or person-specific. A real
-# leak (e.g. /Users/alice/Developer/x slipping into a public RELEASE.md) trips
-# this regardless of whose machine it came from. The username segment is a
-# literal-username class ([A-Za-z0-9._-]) so dynamic/templated paths that build
-# the user at runtime — shell `/home/$USER/`, doc `/home/<rip>/`, Rust
-# `/home/{user}/` — do NOT false-positive; only a baked-in literal home leaks.
-HOMEPATH_RE='/Users/[A-Za-z0-9._-]+/|/home/[A-Za-z0-9._-]+/'
-# AI-attribution net (case-insensitive). "claude" matches only as a standalone
-# word — NOT preceded by a dot/slash/alnum and NOT followed by .md — so legit
-# mentions of CLAUDE.md / .claude/ in a commit message don't false-positive.
-ATTR_RE='co-authored-by|generated with|🤖|(?<![.\/A-Za-z0-9])claude(?!\.md)'
-
-echo "── leak-guard: tracked agent-context paths ──"
-while IFS= read -r f; do
-  case "$f" in
-    CLAUDE.md|*/CLAUDE.md|.claude|.claude/*|*/.claude|*/.claude/*)
-      note "tracked agent-context file: $f (CLAUDE.md/.claude must never be tracked in a public repo)" ;;
-  esac
-done < <(git ls-files)
-
-# Match a PCRE against a file, emitting "LINE: MATCH". The pattern is passed as
-# an argument (not interpolated into a //) so metacharacters like the "/" in a
-# path-style token can't break the regex. Reads raw bytes so non-UTF-8 blobs
-# don't abort the scan.
-pcre_matches() {
-  perl -e '
-    my ($file, $re) = @ARGV;
-    open(my $fh, "<:raw", $file) or exit 0;
-    my $rx; eval { $rx = qr/$re/i }; exit 0 if $@;
-    while (my $l = <$fh>) { if ($l =~ /$rx/) { print "$.: $&\n"; } }
-  ' "$1" "$2" 2>/dev/null
-}
-
-# This script's own source necessarily contains the detection patterns (e.g.
-# the regex tokens in INFRA_RE), so scanning it would always self-flag. Skip it.
-SELF="$(git ls-files --full-name -- "$SELF_ABS" 2>/dev/null | head -1)"
-
-echo "── leak-guard: internal-infra references in tracked files ──"
-while IFS= read -r f; do
-  case "$f" in *.png|*.jpg|*.jpeg|*.ico|*.gif|*.bin|*.crate|*.gz|*.zip|*.pdf) continue ;; esac
-  [ -n "$SELF" ] && [ "$f" = "$SELF" ] && continue
-  [ -f "$f" ] || continue
-  while IFS= read -r hit; do
-    [ -z "$hit" ] && continue
-    note "internal-infra reference: $f:$hit"
-  done < <(pcre_matches "$f" "$INFRA_RE")
-  while IFS= read -r hit; do
-    [ -z "$hit" ] && continue
-    note "[HOME-PATH] absolute home path: $f:$hit (no local home path may be committed to a public repo)"
-  done < <(pcre_matches "$f" "$HOMEPATH_RE")
-done < <(git ls-files)
-
-RANGE="${1:-}"
-if [ -n "$RANGE" ]; then
-  echo "── leak-guard: AI-attribution in commit messages ($RANGE) ──"
-  while IFS= read -r sha; do
-    [ -z "$sha" ] && continue
-    msg="$(git log -1 --format='%B' "$sha" 2>/dev/null || true)"
-    # Pass the pattern as an argument (not interpolated into a //) so the
-    # lookbehind char class and "/" don't break the regex.
-    hit="$(printf '%s' "$msg" | perl -e '
-      my $re = $ARGV[0]; my $rx = qr/$re/i;
-      while (my $l = <STDIN>) { if ($l =~ /($rx)/) { print "$1\n"; last; } }
-    ' "$ATTR_RE" | head -1 || true)"
-    [ -n "$hit" ] && note "commit ${sha:0:12}: message contains \"$hit\" (owner rule: zero AI attribution, ever)"
-  done < <(git rev-list "$RANGE" 2>/dev/null || true)
-fi
-
-echo
-if [ "$fail" -ne 0 ]; then
-  echo "✗ leak-guard: blocking finding(s) above — DO NOT MERGE/PUBLISH"
-  exit 1
-fi
-echo "✓ leak-guard: clean"

docs/FVI_FORMAT.md

@@ -1,302 +0,0 @@
-# FVI — Freemkv Video Index Format
-
-**Specification version:** 1.0 (DRAFT)\
-**File extension:** `.fvi`\
-**Media type:** `application/vnd.freemkv.fvi+jsonl`\
-**Status:** Draft for review. This document is the normative reference for the FVI
-format; implementations and downstream tools cite it by section.
-
----
-
-## 1. Scope and purpose
-
-FVI is an open, codec-agnostic, byte-exact **index of the coded pictures** in a
-video bitstream, together with **provenance** back to the source medium.
-
-An FVI document answers, for every picture in a stream, three questions:
-
-1. **Where is it?** — the byte-exact offset of its first byte in the *source*
-   (the disc/ISO/file), so a reader can extract or seek to any picture without
-   re-parsing the whole bitstream.
-2. **What is it?** — coding type, random-access capability, GOP boundary, and
-   (where the codec defines them) field/pulldown attributes.
-3. **When is it?** — decode and presentation timestamps on a declared timescale.
-
-FVI is **not** a container, a codec, or a copy of the bitstream. It indexes; it
-never stores coded samples. It is the serialized form of an indexer's per-picture
-truth — carried from the demuxer, **never reconstructed** (§9).
-
-## 2. Conformance
-
-The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**,
-**SHOULD**, **SHOULD NOT**, **MAY**, and **OPTIONAL** are to be interpreted as
-described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all
-capitals.
-
-A **conformant writer** MUST emit a document that satisfies §4–§10. A
-**conformant reader** MUST accept any such document and MUST ignore unknown
-object members (§11) so that forward-compatible extensions do not break it.
-
-## 3. Terminology
-
-- **Picture** — one coded video frame (or pair of fields coded as a frame). The
-  unit FVI indexes.
-- **Access unit (AU)** — the set of bitstream bytes that decode to exactly one
-  picture (ISO/IEC 14496-10 §3; ISO/IEC 23008-2 §3).
-- **Coded order** — the order pictures appear in the bitstream. FVI records are
-  emitted in coded order.
-- **GOP / coded video sequence** — a self-contained run beginning at a
-  random-access point.
-- **Provenance** — the mapping from an AU back to the exact bytes of the physical
-  source it was read from (§9).
-- **Source position (`src`)** — `{ file, sector, byte }`, the provenance anchor of
-  an AU.
-
-## 4. Encoding
-
-An FVI document is a sequence of **UTF-8** text lines separated by a single LF
-(`U+000A`). Each non-empty line is exactly one JSON value (RFC 8259), forming a
-**JSON Lines / NDJSON** stream. A writer MUST NOT emit a UTF-8 BOM. A writer MUST
-NOT pretty-print: each JSON value occupies exactly one line.
-
-The first line MUST be the **Header** object (§6). Each subsequent line is one
-**Picture record** (§7), in coded order.
-
-Rationale: line-delimited JSON is streamable (a writer appends as it indexes; a
-reader processes without loading the whole file), line-addressable (picture *n*
-is near line *n+1*), append-safe, and parseable by every language without a
-custom grammar — while remaining a precisely specified format, not an ad-hoc dump.
-
-A document MAY be concatenated for multiple elementary streams: each stream is its
-own header line followed by its records. Readers MUST treat a Header line as the
-start of a new stream section.
-
-## 5. Document structure
-
-```
-<header>            line 1            (exactly one Header object)
-<record>            line 2 .. N       (one Picture record per picture, coded order)
-[<header> <record>…]                  (OPTIONAL further stream sections)
-```
-
-## 6. Header object
-
-| Member | JSON type | Req | Semantics / reference |
-|---|---|---|---|
-| `format` | string | MUST | Constant `"freemkv/video-index"`. Signature: a document begins with these bytes. |
-| `fvi_version` | integer | MUST | Document format version. This spec defines `1`. |
-| `generator` | string | SHOULD | Producing tool + version, e.g. `"freemkv/1.0.0-rc.6"`. |
-| `stream` | object | MUST | The indexed elementary stream (§6.1). |
-| `source` | object | MUST | Provenance root (§6.2). |
-| `timescale` | integer | MUST | Ticks per second for all `pts`/`dts` (§10). E.g. `90000`. |
-| `picture_count` | integer | MAY | Total pictures, if known at header time; OMITTED when streaming. |
-
-### 6.1 `stream` object
-
-| Member | JSON type | Req | Semantics / reference |
-|---|---|---|---|
-| `codec` | string | MUST | Registered codec id (Appendix B), e.g. `"mpeg2video"`, `"hevc"`. |
-| `width`,`height` | integer | MUST | Coded luma dimensions in pixels. |
-| `dar` | `[int,int]` | SHOULD | Display aspect ratio as `[num,den]`. |
-| `frame_rate` | `[int,int]` | SHOULD | Nominal rate as exact rational `[num,den]` (e.g. `[24000,1001]`). |
-| `scan` | string | MUST | `"progressive"`<br>`"interlaced"`<br>`"mbaff"` |
-| `colour` | object | SHOULD | CICP per ITU-T H.273: `primaries`, `transfer`, `matrix` (integer CICP codes or registered names)<br>`range`: `"limited"` \| `"full"`<br>HDR: `mastering_display`, `max_cll`, `max_fall` per ITU-T H.273 / SMPTE ST 2086. |
-| `language` | string | MAY | BCP 47 tag, if known. |
-
-### 6.2 `source` object
-
-| Member | JSON type | Req | Semantics / reference |
-|---|---|---|---|
-| `medium` | string | MUST | `"disc"`<br>`"iso"`<br>`"file"`<br>`"stream"` |
-| `path` | string | MAY | Source path/label. |
-| `title` | integer | MAY | Title/program number. |
-| `playlist` | string | MAY | Playlist/PGC identifier. |
-| `volume_id` | string | MAY | Disc volume identifier, if read. |
-| `sector_size` | integer | SHOULD | Bytes per `src.sector` unit (e.g. `2048`). Lets readers convert `src` to an absolute byte offset. |
-
-## 7. Picture record
-
-One JSON object per coded picture, in coded order.
-
-| Member | JSON type | Req | Semantics / reference |
-|---|---|---|---|
-| `n` | integer | MUST | Coded-order index, 0-based, contiguous. |
-| `src` | object | MUST | Provenance: `{ "file": int?, "sector": uint, "byte": uint }` — the offset of this AU's **first byte** in the source (§9). MUST be carried from demux, never reconstructed. |
-| `type` | string | MUST | Coding type:<br>`"I"`<br>`"P"`<br>`"B"`<br>_ISO/IEC 13818-2 §6.3.9; H.264/H.265 slice types collapsed to frame type._ |
-| `key` | boolean | MUST | `true` iff this picture is an intra (I) picture / parser-flagged decode-restart point (IDR / IRAP / I-picture).<br>_MPEG-2 open-GOP clean-RAP precision (`closed_gop`) is not currently distinguished — see note below._ |
-| `gop` | boolean | SHOULD | `true` iff this picture begins a GOP / coded video sequence.<br>_Omitted when the implementation does not carry a distinct GOP-boundary signal._ |
-| `pts` | integer\|null | SHOULD | Presentation timestamp in `timescale` ticks; `null` if unknown. |
-| `dts` | integer\|null | MAY | Decode timestamp in `timescale` ticks. |
-| `size` | integer | MAY | AU length in bytes; enables byte-range extraction with `src`. |
-| `recovered` | boolean | MAY | `true` iff any byte of this AU came from a retried/marginal read (§9.1).<br>_Default `false`._ |
-| codec ext | object | MAY | Codec-specific members under the codec's namespace (§8). |
-
-The `type` and `key` members are **codec-agnostic** and MUST be populated for
-every codec. `type` is the I/P/B coding type the parser decoded (collapsing
-H.264/H.265 slice types to a frame type); where no per-picture coding is carried
-(audio / synthetic frames), `type` is `"I"` for a key picture else `"P"`. `key`
-is the picture's random-access flag as the codec parser sets it (IDR / IRAP /
-I-picture). A writer MUST NOT emit a degraded record (`type:"?"` or `src:null`)
-merely because a codec lacks per-picture coding info — those fallbacks are
-reserved for a field that is genuinely unavailable (e.g. provenance absent on a
-synthetic source).
-
-> **Limitation (honest random-access).** `key` is set from the picture's
-> intra / decode-restart flag. The per-picture coding model this index carries
-> does **not** distinguish MPEG-2 open-GOP clean random-access points
-> (`closed_gop`) from any other I-picture, so `key` is the parser-flagged
-> decode-restart point, not a verified clean-RAP claim. A future revision MAY
-> tighten `key` for codecs/profiles that carry that signal; readers MUST NOT
-> assume present `key` precision beyond "intra / decode-restart point".
-
-### 7.1 Interlace / pulldown fields
-
-Codec-agnostic interlace/pulldown attributes, derived through the indexer's
-per-picture coding accessors (MPEG-2: ISO/IEC 13818-2 §6.3.10). Emitted as
-top-level members of the record, and ONLY when the codec actually measured the
-signal — an OPTIONAL member that is omitted (not defaulted) when unknown:
-
-| Member | JSON type | Req | Semantics / reference |
-|---|---|---|---|
-| `field_order` | string | MAY | Display field order:<br>`"tff"` — top field first<br>`"bff"` — bottom field first<br>`"progressive"` — no field order applies<br>_Omitted when the codec did not signal it._ |
-| `progressive` | boolean | MAY | `true` iff the picture is progressive.<br>_Omitted when the codec did not signal it._ |
-| `nb_fields` | integer | MAY | Number of displayed field periods this picture occupies (the soft-telecine / 2:3 pulldown basis):<br>`1` for a single field picture<br>`2` for a normal frame<br>`3`/`4`/`6` for `repeat_first_field` pulldown per §6.3.10 |
-
-Codecs that carry only a coding type (e.g. H.264 / HEVC / VC-1 through this
-pipeline) omit `field_order` and `progressive` rather than guessing a default.
-
-## 8. Codec model and extensibility
-
-Core record members (§7) are codec-agnostic and present for every codec.
-Codec-specific data is either (a) promoted to top-level members for a small,
-registered set per codec profile (e.g. MPEG-2 §7.1), or (b) placed under an
-`ext` object keyed by codec id for richer/optional data:
-
-```json
-{
-  "n": 42,
-  "type": "P",
-  "key": false,
-  "src": {
-    "sector": 17,
-    "byte": 924
-  },
-  "ext": {
-    "hevc": {
-      "temporal_id": 0,
-      "nal_type": 1
-    }
-  }
-}
-```
-
-New codecs and members are added through Appendix B (codec registry) without a
-breaking version bump, provided readers continue to ignore unknown members (§11).
-
-## 9. Provenance and recovery semantics
-
-`src` is **byte-exact** to the source as read. `src.sector` counts in
-`source.sector_size`-byte units; `src.byte` is the offset within that sector of
-the AU's first byte. For multi-file sources, `src.file` indexes a writer-declared
-file list. Provenance MUST be the value observed at demux time; an implementation
-MUST NOT recompute `src` by re-parsing — the point of FVI is to *carry* the truth.
-
-### 9.1 Recovery
-
-Because FVI is provenance-native, it can record reliability. A record with
-`"recovered":true` indicates the AU's source bytes required retry/marginal-read
-recovery. This lets downstream tools surface or quarantine pictures whose bytes
-are not byte-identical to a clean read — a capability legacy index formats lack.
-
-## 10. Time model
-
-All `pts`/`dts` are integers in units of `1/timescale` seconds. `pts` is
-presentation (display) time; `dts` is decode time. Records are in **coded**
-(decode) order, so `pts` is not necessarily monotonic across records (B-pictures
-reorder); `dts` is non-decreasing. Readers needing display order sort by `pts`.
-
-## 11. Versioning and forward compatibility
-
-- `fvi_version` is the document version; this spec defines `1`.
-- **Additive** changes (new OPTIONAL members, new registered codecs) do NOT bump
-  `fvi_version`. Readers MUST ignore members they do not recognize.
-- A change that alters the meaning of an existing member or makes a new member
-  REQUIRED bumps `fvi_version`.
-- A reader encountering a higher `fvi_version` than it implements SHOULD process
-  the members it understands and MUST NOT reject the document solely for the
-  version being higher, unless a member it relies on is absent.
-
-## 12. Conformance requirements (summary)
-
-A conformant **writer** MUST: emit a Header first; emit records in coded order
-with contiguous `n`; populate `src` from demux; use named/registered codec ids;
-encode one JSON value per UTF-8 LF-terminated line.
-
-A conformant **reader** MUST: accept any §4–§10 document; ignore unknown members;
-not assume `picture_count`, `pts`, or `size` are present unless required above.
-
----
-
-## Appendix A — JSON Schema (informative)
-
-Header:
-
-```json
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "required": ["format", "fvi_version", "stream", "source", "timescale"],
-  "properties": {
-    "format": { "const": "freemkv/video-index" },
-    "fvi_version": { "type": "integer", "minimum": 1 },
-    "timescale": { "type": "integer", "minimum": 1 },
-    "stream": { "type": "object", "required": ["codec", "width", "height", "scan"] },
-    "source": { "type": "object", "required": ["medium"] }
-  }
-}
-```
-
-Record:
-
-```json
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "required": ["n", "src", "type", "key"],
-  "properties": {
-    "n": { "type": "integer", "minimum": 0 },
-    "type": { "enum": ["I", "P", "B"] },
-    "key": { "type": "boolean" },
-    "src": {
-      "type": "object",
-      "required": ["sector", "byte"],
-      "properties": {
-        "file": { "type": "integer" },
-        "sector": { "type": "integer", "minimum": 0 },
-        "byte": { "type": "integer", "minimum": 0 }
-      }
-    }
-  }
-}
-```
-
-## Appendix B — Registered codec identifiers
-
-| `codec` | Bitstream | Field profile |
-|---|---|---|
-| `mpeg2video` | ISO/IEC 13818-2 | §7.1 (field_order/progressive/nb_fields) |
-| `mpeg1video` | ISO/IEC 11172-2 | §7.1 |
-| `h264` | ISO/IEC 14496-10 | core + `ext.h264` |
-| `hevc` | ISO/IEC 23008-2 | core + `ext.hevc` |
-| `vc1` | SMPTE 421M | core |
-
-## Appendix C — Normative references
-
-- RFC 2119, RFC 8174 — Requirement keywords (BCP 14).
-- RFC 8259 — JSON.
-- ISO/IEC 13818-2 — MPEG-2 video (picture coding, §6.3.9–6.3.10).
-- ISO/IEC 14496-10 — H.264/AVC. ISO/IEC 23008-2 — H.265/HEVC.
-- ITU-T H.273 — Coding-independent code points (colour primaries/transfer/matrix).
-- SMPTE ST 2086 — Mastering display colour volume (HDR).
-- BCP 47 — Language tags.
-- RFC 9559 — Matroska (alignment of colour/field-order semantics).

docs/README.md

@@ -12,7 +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) | What this crate owns of the recovery model: single-shot Drive::read, SenseFamily, DiscStream batch halving (the strategy itself moved to freemkv-engine in 1.6.0) |
+| [Rip Recovery](rip-recovery.md) | Three-layer recovery model: Disc::patch, single-shot Drive::read, DiscStream batch halving |
 | [AACS Encryption](aacs.md) | Key resolution (4 paths), content decryption, bus encryption, SCSI handshake |
 | [UDF Filesystem](udf.md) | UDF 2.50 with metadata partitions, pointer chain, how files are read from disc |
 | [MPLS Playlists](mpls.md) | Playlist format, play items, STN stream table, coding types |

docs/aacs.md

@@ -2,45 +2,191 @@
 
 ## Overview
 
-AACS (Advanced Access Content System) is the encryption layer used by Blu-ray
-and UHD 4K discs to protect content. libfreemkv implements AACS decryption so
-disc access is transparent to the application.
+AACS (Advanced Access Content System) is the encryption layer used by Blu-ray and UHD 4K discs to protect content. libfreemkv implements AACS decryption to enable transparent disc access.
 
 There are two major versions:
 
-- **AACS 1.0** -- Used by standard Blu-ray discs.
-- **AACS 2.0 / 2.1** -- Used by UHD 4K Blu-ray discs. Adds a per-sector bus
-  encryption layer on top of the standard content encryption. UHD drives accept
-  AACS 1.0 host credentials for backward compatibility.
+- **AACS 1.0** -- Used by standard Blu-ray discs. Relies on a custom 160-bit elliptic curve for bus authentication and AES-128 for content encryption. Processing keys and device keys can derive the media key from the disc's Media Key Block (MKB).
 
-All versions use AES-128 for content decryption. The library reads the keys it
-needs from `keydb.cfg`, walks the disc's Media Key Block (MKB) to resolve the
-disc's key, and decrypts the content stream. AACS-encrypted discs therefore
-require a `keydb.cfg`; CSS-protected DVDs do not (see the CSS notes in the
-library docs).
+- **AACS 2.0** -- Used by UHD 4K Blu-ray discs. Adds a per-sector bus encryption layer (read_data_key) on top of the standard content encryption. Uses P-256/SHA-256 for its native handshake, though drives accept AACS 1.0 host certificates for backward compatibility.
 
-## How it works (feature level)
+Both versions use AES-128-CBC for content decryption with a fixed initialization vector. The fundamental key hierarchy is the same: a Volume Unique Key (VUK) decrypts per-title unit keys, which in turn decrypt the content stream.
 
-When a disc is scanned, the library:
 
-1. Reads the disc's AACS key-input files from the `/AACS/` directory.
-2. Resolves the disc's key from `keydb.cfg` — either directly from a per-disc
-   entry, or by walking the MKB with the keys present in the keydb.
-3. Performs the drive-level SCSI authentication handshake needed to obtain the
-   Volume ID and, for UHD, the bus-decryption key.
-4. Decrypts the content stream as titles are read.
+## Architecture
+
+AACS support is split across two modules:
+
+### `aacs.rs` -- Keys and Decryption
+
+Handles everything related to key resolution and content decryption:
+
+- KEYDB.cfg parsing (device keys, processing keys, host certificates, per-disc entries)
+- Disc hash computation (SHA-1 of `Unit_Key_RO.inf`)
+- VUK resolution chain (4 paths, described below)
+- MKB record parsing and media key derivation
+- Subset-difference tree traversal (AACS-G3 key derivation)
+- Unit_Key_RO.inf parsing and unit key decryption
+- Content Certificate parsing (AACS version detection)
+- Aligned unit decryption (AES-128-CBC)
+- Bus decryption (AACS 2.0 read_data_key layer)
+
+### `aacs_handshake.rs` -- SCSI Authentication
+
+Handles the drive-level SCSI authentication protocol:
+
+- ECDH key agreement on the AACS 160-bit curve
+- ECDSA signing and verification
+- Bus key derivation
+- AGID management (allocate/invalidate)
+- Volume ID retrieval (encrypted with bus key, verified by AES-CMAC)
+- Read Data Key retrieval (for AACS 2.0 bus decryption)
+- AACS LA public key certificate verification
+
+
+## Key Resolution Chain
+
+When a disc is scanned, `resolve_keys()` attempts four paths in priority order. The first path that succeeds is used.
+
+### Path 1: KEYDB VUK Lookup (fastest)
+
+```
+Unit_Key_RO.inf --> SHA-1 --> disc_hash --> KEYDB lookup --> VUK
+```
+
+The disc hash is computed as the SHA-1 digest of the raw `Unit_Key_RO.inf` file from the disc's `/AACS/` directory. This hash is used as the lookup key in `KEYDB.cfg`. If a matching entry contains a VUK (`V` field), it is used directly.
+
+This is the fast path and resolves the vast majority of discs in a well-maintained KEYDB.
+
+### Path 2: KEYDB Media Key + Volume ID
+
+```
+KEYDB media_key + Volume ID (from SCSI handshake) --> VUK derivation
+```
+
+If the disc hash is not in the KEYDB but a KEYDB entry has a matching Volume ID (`I` field) and a media key (`M` field), the VUK is derived:
+
+```
+VUK = AES-128-ECB-DECRYPT(media_key, volume_id) XOR volume_id
+```
+
+Requires a successful SCSI handshake to obtain the Volume ID.
+
+### Path 3: MKB + Processing Keys
+
+```
+MKB (from disc) + processing_keys (from KEYDB) --> media_key --> VUK
+```
+
+Processing keys are pre-computed keys that work against specific MKB versions. For each processing key, the library:
+
+1. Parses the MKB to extract the Verify Media Key Record (`mk_dv`), subset-difference index, and conditional values (cvalues).
+2. Tries each processing key against each UV/cvalue pair: `mk = AES-DEC(pk, cvalue) XOR cvalue`.
+3. Validates the derived media key: `AES-ECB(mk, mk_dv)` must produce 12 leading zero bytes.
+4. Derives VUK from the validated media key and Volume ID.
+
+### Path 4: MKB + Device Keys (Subset-Difference Tree)
+
+```
+MKB + device_keys --> subset-difference tree traversal --> processing_key --> media_key --> VUK
+```
+
+The most complex path. Each device key has an associated node number, UV value, and mask parameters that position it in the AACS subset-difference tree. The library:
+
+1. Finds the subset-difference entry in the MKB that applies to the device key's node.
+2. Traverses the tree using AACS-G3 key derivation: `aesg3(key, inc) = AES-DEC(key, seed) XOR seed`, where `seed[15]` is incremented by `inc`. Each tree node produces a left child (inc=0), a processing key (inc=1), and a right child (inc=2).
+3. At each level, selects left or right based on the UV bit at the current position.
+4. The resulting processing key is validated against the MKB cvalue to derive the media key.
+5. VUK is derived from the media key and Volume ID.
+
+
+## Content Decryption
+
+### Aligned Units
+
+AACS encrypts content in aligned units of 6144 bytes (3 sectors of 2048 bytes each). The encryption flag is signaled by the copy_permission_indicator bits in byte 0 of the unit (`unit[0] & 0xC0 != 0`).
+
+### Per-Unit Key Derivation
+
+Each aligned unit has its own decryption key derived from the CPS unit key:
+
+1. **Derive**: AES-128-ECB encrypt the first 16 bytes of the unit (plaintext TP_extra_header) with the unit key.
+2. **XOR**: XOR the encrypted result with the original 16 bytes to produce the per-unit decryption key.
+3. **Decrypt**: AES-128-CBC decrypt bytes 16 through 6143 using the per-unit key and the fixed AACS IV.
+4. **Clear flag**: Clear the encryption indicator bits (`unit[0] &= !0xC0`).
+
+### Fixed IV
+
+All AES-CBC operations in AACS use the same fixed initialization vector, defined in the AACS specification.
+
+### Verification
+
+After decryption, the library verifies correctness by checking for MPEG-TS sync bytes (0x47) at the expected 192-byte packet boundaries within the unit. Blu-ray transport stream packets are 192 bytes: 4-byte TP_extra_header followed by a 188-byte TS packet.
+
+
+## Bus Encryption
+
+### AACS 1.0
+
+Standard Blu-ray discs do not use bus encryption. Content is read directly from the disc and decrypted using the unit key.
+
+### AACS 2.0
+
+UHD 4K discs add a per-sector bus encryption layer. The drive encrypts data as it is read from the disc, and the host must decrypt it before applying AACS content decryption.
+
+Bus encryption uses a **read_data_key** obtained during the SCSI handshake. For each 2048-byte sector within an aligned unit, bytes 16 through 2047 are AES-128-CBC encrypted with the read_data_key and the fixed AACS IV. The first 16 bytes of each sector remain plaintext.
+
+The full decryption pipeline for AACS 2.0:
+
+1. **Bus decrypt**: For each sector, AES-128-CBC decrypt bytes 16..2047 with the read_data_key.
+2. **Content decrypt**: Standard per-unit key derivation and AES-128-CBC decryption as described above.
+
+
+## SCSI Handshake
+
+The AACS SCSI authentication handshake establishes a shared bus key between host and drive, then uses it to securely transfer the Volume ID and read data keys.
+
+### Protocol Flow
+
+1. **Invalidate AGIDs**: Send REPORT KEY with format 0x3F for AGIDs 0-3 to clear stale sessions.
+2. **Allocate AGID**: REPORT KEY format 0x00 returns a fresh Authentication Grant ID.
+3. **Send host credentials**: SEND KEY format 0x01 transmits the host nonce (20 random bytes) and host certificate (92 bytes).
+4. **Receive drive credentials**: REPORT KEY format 0x01 returns the drive nonce and drive certificate.
+5. **Receive drive key**: REPORT KEY format 0x02 returns the drive's ephemeral EC key point and ECDSA signature over `host_nonce || drive_key_point`.
+6. **Verify drive key**: The signature is verified against the drive's public key (extracted from its certificate). AACS 1.0 certificates are verified against the AACS LA public key.
+7. **Send host key**: The host generates an ephemeral key pair, signs `drive_nonce || host_key_point` with the host private key, and sends via SEND KEY format 0x02.
+8. **Compute bus key**: ECDH shared secret = `host_private_key * drive_key_point`. The bus key is the low 128 bits of the shared point's x-coordinate.
+
+### Post-Authentication Reads
+
+- **Volume ID**: REPORT DISC STRUCTURE format 0x80. Returns 16-byte VID encrypted with the bus key, plus an AES-CMAC MAC for integrity verification.
+- **Read Data Keys**: REPORT DISC STRUCTURE format 0x84. Returns the read_data_key and write_data_key, each AES-ECB encrypted with the bus key.
+
+### Elliptic Curve
+
+AACS 1.0 uses a custom 160-bit Weierstrass curve (`y^2 = x^3 + ax + b mod p`) with 20-byte field elements. The library implements full EC arithmetic: point addition, doubling, scalar multiplication, modular inverse, ECDSA sign/verify, and ECDH key agreement.
+
+
+## AACS 2.0 Status
+
+AACS 2.0 discs are detected via the Content Certificate file (`Content000.cer` or `Content001.cer`). A certificate type byte of 0x01 indicates AACS 2.0.
+
+AACS 2.0 drives are identified by their drive certificate type (0x11). These drives natively use P-256/SHA-256, but accept AACS 1.0 host certificates for backward compatibility.
+
+Current implementation status:
+
+- AACS 2.0 detection: **implemented** (Content Certificate parsing, drive cert type check)
+- AACS 1.0 handshake with AACS 2.0 drives: **implemented** (backward compatibility mode)
+- Full P-256 AACS 2.0 handshake: **not yet implemented** (prepared but rarely needed since drives accept AACS 1.0 host certs)
+- Bus decryption with read_data_key: **implemented**
+- Content decryption: **implemented** (same as AACS 1.0)
+
+In practice, AACS 2.0 UHD discs work through the backward-compatible AACS 1.0 handshake path, with the addition of read_data_key bus decryption.
 
-A resolved key is verified against actual disc content before it is applied, so
-a stale or wrong key fails loudly rather than producing silent garbage. If no
-usable key is available for an AACS-encrypted disc, the library surfaces a
-specific error (the E70xx family) describing which part of the chain was
-missing, and a missing `keydb.cfg` surfaces as `Error::KeydbLoad` with the
-sentinel path `<no keydb in search paths>`.
 
 ## API Usage
 
-AACS decryption is transparent to the application. `Disc::scan()` handles
-everything automatically:
+AACS decryption is transparent to the application. The `Disc::scan()` method handles everything automatically:
 
 ```rust
 use libfreemkv::{Drive, Disc};
@@ -57,6 +203,7 @@ if disc.encrypted {
     if let Some(ref aacs) = disc.aacs {
         println!("AACS {}.0", aacs.version);
         println!("Key source: {}", aacs.key_source.name());
+        println!("Disc hash: {}", aacs.disc_hash);
         if let Some(mkb_ver) = aacs.mkb_version {
             println!("MKB version: {}", mkb_ver);
         }
@@ -65,55 +212,111 @@ if disc.encrypted {
     }
 }
 
-// Read content -- decryption is applied on read by the DiscStream decorator.
-// Live disc does NOT go through the URL resolver: `input("disc://...")` returns
-// Error::DiscUrlNotDirect by design.
-let keys = disc.decrypt_keys();
-let mut stream = DiscStream::new(
-    Box::new(drive),
-    disc.titles[0].clone(),
-    keys,
-    batch_sectors,
-    disc.titles[0].content_format,
-    false, // raw: false → decrypt on read
-    None,  // halt
-)?;
-while let Ok(Some(frame)) = stream.read() {
-    // decrypted PES frames
+// Read content -- decryption is automatic
+let mut reader = disc.open_title(&mut session, 0).unwrap();
+while let Some(unit) = reader.read_unit().unwrap() {
+    // unit is 6144 bytes of decrypted content
 }
 ```
 
-The application never calls decryption functions and never manages the
-drive-level handshake. It DOES own key resolution — see below.
+The application never touches keys, never calls decryption functions, and never manages handshakes. All of that is internal to `Disc::scan()` and `ContentReader::read_unit()`.
 
-### Key resolution is the caller's job
+### KEYDB Location
 
-`libfreemkv` is **lookup-free: it resolves no keys and reads no keydb.** There is
-no `ScanOptions::with_keydb`, and `ScanOptions` has no keydb field — its only
-scan input is the optional drive credentials for the live-drive authenticated
-handshake.
+`ScanOptions` controls where the KEYDB is loaded from. If no explicit path is set, the library checks:
 
-The caller resolves a key out-of-band through a key source and applies it with
-[`Disc::decrypt_with`]. `freemkv-keysources` is the crate that implements the
-keydb and key-server sources; `ScanOptions::key_sources` takes them as
-`Box<dyn KeySource>`.
+1. `~/.config/aacs/KEYDB.cfg`
+2. `/etc/aacs/KEYDB.cfg`
+
+To specify an explicit path:
+
+```rust
+let opts = ScanOptions::with_keydb("/path/to/KEYDB.cfg");
+let disc = Disc::scan(&mut session, &opts).unwrap();
+```
 
 ### AacsState
 
-After a successful scan, `disc.aacs` contains an `AacsState`:
+After a successful scan, `disc.aacs` contains an `AacsState` with:
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `version` | `u8` | AACS version (1 or 2) |
 | `bus_encryption` | `bool` | Whether bus encryption is active |
 | `mkb_version` | `Option<u32>` | MKB version from disc |
-| `disc_hash` | `String` | Identifier for the disc's key-input files |
-| `key_source` | `KeyOrigin` | How the disc's key was resolved |
+| `disc_hash` | `String` | SHA-1 of Unit_Key_RO.inf (hex with 0x prefix) |
+| `key_source` | `KeySource` | How keys were resolved |
+| `vuk` | `[u8; 16]` | Volume Unique Key |
+| `unit_keys` | `Vec<(u32, [u8; 16])>` | Decrypted unit keys (CPS unit number, key) |
+| `read_data_key` | `Option<[u8; 16]>` | AACS 2.0 bus decryption key |
+| `volume_id` | `[u8; 16]` | Volume ID from SCSI handshake |
 
-## keydb.cfg
+### KeySource
 
-`keydb.cfg` is the single source of AACS key material. It is a text file (lines
-starting with `;` or `#` are comments) holding the host credentials and per-disc
-entries the library uses to resolve a disc. autorip can auto-download and
-refresh it from a configured URL. The library does not ship any AACS keys
-compiled into the binary.
+| Variant | Description |
+|---------|-------------|
+| `KeyDb` | VUK found directly in KEYDB by disc hash |
+| `KeyDbDerived` | Media key + Volume ID from KEYDB, VUK derived |
+| `ProcessingKey` | MKB + processing keys from KEYDB |
+| `DeviceKey` | MKB + device keys, subset-difference tree traversal |
+
+
+## KEYDB.cfg Format Reference
+
+The KEYDB.cfg file contains all cryptographic material needed for AACS decryption. Lines starting with `;` or `#` are comments.
+
+### Device Keys
+
+```
+| DK | DEVICE_KEY 0x<key> | DEVICE_NODE 0x<node> | KEY_UV 0x<uv> | KEY_U_MASK_SHIFT 0x<shift>
+```
+
+- `key`: 16-byte AES device key (hex)
+- `node`: Device node number in the subset-difference tree (hex)
+- `uv`: UV value for tree positioning (hex)
+- `shift`: U mask shift value (hex)
+
+### Processing Keys
+
+```
+| PK | 0x<key>
+```
+
+- `key`: 16-byte pre-computed processing key (hex)
+
+### Host Certificate
+
+```
+| HC | HOST_PRIV_KEY 0x<privkey> | HOST_CERT 0x<cert>
+```
+
+- `privkey`: 20-byte ECDSA private key (hex)
+- `cert`: 92-byte AACS host certificate (hex)
+
+The host certificate is used for SCSI authentication. It contains the host's public key and is signed by the AACS Licensing Administrator.
+
+### Disc Entries
+
+```
+0x<disc_hash> = <title> | D | <date> | M | 0x<media_key> | I | 0x<disc_id> | V | 0x<vuk> | U | <unit_keys>
+```
+
+- `disc_hash`: 20-byte SHA-1 of Unit_Key_RO.inf (hex)
+- `title`: Human-readable disc title
+- `D`: Date tag, followed by release/rip date
+- `M`: Media key tag, followed by 16-byte media key (hex)
+- `I`: Disc ID tag, followed by 16-byte Volume ID (hex)
+- `V`: VUK tag, followed by 16-byte Volume Unique Key (hex)
+- `U`: Unit keys tag, followed by space-separated `<unit_num>-0x<key>` pairs
+
+All fields after the title are optional. A minimal entry needs only the disc hash and VUK:
+
+```
+0x<disc_hash> = <title> | V | 0x<vuk>
+```
+
+Inline comments are supported with `;`:
+
+```
+0x<disc_hash> = <title> | V | 0x<vuk> ; MKBv77
+```

docs/api-design.md

@@ -85,10 +85,10 @@ All URLs require a `scheme://path` format. Bare paths are rejected.
 // PES pipeline (frame-level) — input() returns Box<dyn FrameSource>,
 // output() returns Box<dyn FrameSink>.
 let input = libfreemkv::input("disc:///dev/sg4", &opts)?;    // DiscStream
-let input = libfreemkv::input("iso://Movie.iso", &opts)?;     // IsoStream
-let output = libfreemkv::output("mkv://Movie.mkv", &title)?;  // MkvOutputStream
-let output = libfreemkv::output("m2ts://Movie.m2ts", &title)?; // M2tsOutputStream
-let output = libfreemkv::output("network://192.0.2.10:9000", &title)?; // NetworkOutputStream
+let input = libfreemkv::input("iso://Dune.iso", &opts)?;     // IsoStream
+let output = libfreemkv::output("mkv://Dune.mkv", &title)?;  // MkvOutputStream
+let output = libfreemkv::output("m2ts://Dune.m2ts", &title)?; // M2tsOutputStream
+let output = libfreemkv::output("network://10.1.7.11:9000", &title)?; // NetworkOutputStream
 let output = libfreemkv::output("null://", &title)?;          // NullOutputStream
 ```
 
@@ -170,27 +170,24 @@ libfreemkv/src/
 │   ├── writeback_file.rs  WritebackFile (was crate::io::Writer)
 │   └── writeback.rs    sync_file_range pipeline
 ├── drive/              Drive (open, init, single-shot read)
-│   ├── mod.rs          Drive struct, init, read (single-shot), eject
-│   ├── capture.rs      Raw drive SCSI capture (INQUIRY/GET_CONFIG) for contribution
+│   ├── 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
 │   └── windows.rs      Windows drive discovery
-├── disc/               Disc (scan, titles, AACS setup, per-format parsing)
+├── disc/               Disc (scan, titles, AACS setup, sweep, patch)
 │   ├── mod.rs          Disc struct, scan, titles, formats
-│   ├── bluray.rs       Blu-ray / UHD scanning (MPLS/CLPI-driven)
-│   ├── dvd.rs          DVD-Video scanning (IFO-driven)
-│   ├── hddvd.rs        HD-DVD scanning
-│   ├── extract.rs      Per-extent content extraction
-│   ├── encrypt.rs      Encrypted-range mapping for content reads
-│   ├── dvd_audio_probe.rs   DVD audio-stream probing
-│   └── pgs_forced_probe.rs  PGS forced-subtitle probing
+│   ├── sweep.rs        Disc::sweep (Pass 1 forward sweep)
+│   ├── patch.rs        Disc::patch (Pass N retry over mapfile)
+│   ├── mapfile.rs      ddrescue-format mapfile
+│   └── read_error.rs   ReadCtx / ReadAction state machine
 ├── scsi/               SCSI transport (Linux SG_IO, macOS IOKit, Windows SPTI)
-├── unlock.rs           Unlocker trait + registry (pluggable unlock seam)
+├── platform/           Drive unlock (MT1959 A/B)
 ├── aacs/               AACS decryption (handshake, keys, keydb, decrypt)
 ├── css/                DVD CSS cipher
 ├── decrypt.rs          Unified decrypt dispatcher (AACS/CSS/None)
 ├── pes.rs              PES frame types, FrameSource / FrameSink traits
-├── sector/             Sector I/O
+├── sector/             Sector I/O (was sector.rs in 0.17)
 │   ├── mod.rs          SectorSource, SectorSink traits
 │   ├── file.rs         FileSectorSource, FileSectorSink (ISO-backed)
 │   └── decrypting.rs   DecryptingSectorSource decorator
@@ -201,6 +198,7 @@ libfreemkv/src/
 ├── labels/             BD-J label extraction (5 format parsers)
 ├── keydb.rs            KEYDB download, parse, save
 ├── identity.rs         DriveId from INQUIRY
+├── profile.rs          Bundled drive profiles
 ├── speed.rs            DriveSpeed enum
 ├── mux/
 │   ├── mod.rs          Public mux exports

docs/architecture.md

@@ -1,13 +1,11 @@
 # libfreemkv Architecture
 
 Open source optical drive access library for 4K UHD Blu-ray, Blu-ray, and DVD.
-Rust library with profiles bundled and all SCSI communication handled in-process.
-AACS decryption requires an external `keydb.cfg` (default
-`~/.config/freemkv/keydb.cfg`) — the derivation math is internal, but no AACS key
-material is compiled in; DVD CSS player keys are the only compiled-in keys.
+Rust library with no external dependencies at runtime -- profiles are bundled,
+AACS keys are derived internally, and all SCSI communication is handled in-process.
 
 **Repository:** <https://github.com/freemkv/libfreemkv>
-**License:** MIT
+**License:** AGPL-3.0-only
 
 ---
 
@@ -17,10 +15,9 @@ material is compiled in; DVD CSS player keys are the only compiled-in keys.
    format handling live in the library. CLI binaries are thin wrappers that call
    `Drive::open()` and `Disc::scan()`.
 
-2. **Firmware-clean core.** libfreemkv ships no firmware, no unlock CDBs, and no
-   drive profiles. Drive-unlock logic is plugged in by an external crate through
-   the `Unlocker` trait + registry (`register_unlocker`); without one the library
-   still rips via the host-certificate AACS handshake.
+2. **No external files.** Bundled drive profiles are compiled into the binary via
+   `include_str!`. No configuration directory, no runtime file lookups for drive
+   support.
 
 3. **Transparent AACS.** The `ContentReader` decrypts on the fly when keys are
    available. Callers read cleartext sectors without knowing whether the disc
@@ -44,9 +41,11 @@ material is compiled in; DVD CSS player keys are the only compiled-in keys.
 libfreemkv (lib.rs)
 │
 ├── Drive Access
-│   ├── drive         Drive — open, identify, init, single-shot read
+│   ├── drive         Drive — open, identify, init, unlock, single-shot read
 │   ├── scsi          ScsiTransport trait + platform backends (sg async, IOKit, SPTI)
-│   ├── unlock        Unlocker trait + registry — the pluggable unlock seam
+│   ├── platform/     Platform trait — per-chipset command handlers
+│   │   └── mt1959    MediaTek MT1959 driver (LG, ASUS, HP)
+│   ├── profile       DriveProfile loading, matching, bundled JSON
 │   ├── identity      DriveId from INQUIRY + GET_CONFIG 010C
 │   ├── speed         DriveSpeed enum, SET CD SPEED CDB builder
 │   └── event         Event system for drive status callbacks
@@ -66,7 +65,7 @@ libfreemkv (lib.rs)
 │
 ├── Streaming
 │   ├── mux/          Stream implementations (Disc, ISO, MKV, M2TS, Network, Stdio, Null)
-│   ├── pes           PES frame types; the unified pes::Stream (PesStream) read/write trait
+│   ├── pes           PES frame types; FrameSource / FrameSink direction-typed traits
 │   └── sector/       SectorSource / SectorSink traits, FileSector{Source,Sink}, DecryptingSectorSource
 │
 ├── I/O Primitives
@@ -75,7 +74,8 @@ libfreemkv (lib.rs)
 │
 ├── Support
 │   ├── keydb         KEYDB.cfg download, parse, verify, save
-│   └── error         Error enum with numeric codes E1000-E8000
+│   ├── error         Error enum with numeric codes E1000-E8000
+│   └── profile       Bundled drive profiles
 │
 └── lib.rs            Public API re-exports
 ```
@@ -89,20 +89,20 @@ Drive::open(Path::new("/dev/sg4"))
   │
   ├─ scsi::open()           Open /dev/sg4 (async write/poll/read)
   ├─ DriveId::from_drive()  INQUIRY + GET_CONFIG 010C
-  └─ Drive ready for init/read
+  ├─ profile::find_by_drive_id()  Match against bundled profiles
+  ├─ Platform::new()        Instantiate chipset driver (Mt1959)
+  └─ Drive ready for init/unlock/read
 ```
 
 After open:
-- `init()` -- routes to the matching registered unlocker (if any); otherwise
-  a no-op and the cert handshake carries the disc
+- `init()` -- unlock + firmware upload + speed calibration
 - `probe_disc()` -- probe disc surface for optimal speeds
-- `read(lba, count, buf, recovery)` -- single-shot read; `recovery` only selects the per-CDB timeout (`READ_TIMEOUT_MS` 10 s vs. `READ_RECOVERY_TIMEOUT_MS` 60 s)
+- `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
-(`freemkv_engine::recovery::patch`, in the engine crate) handles bad-range
-retry by replaying the ddrescue mapfile.
+(`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
@@ -195,20 +195,17 @@ implementing `execute()` for that OS and wiring it into `scsi::open()`.
 
 ---
 
-## Drive Unlock
+## Chipset Support
 
-libfreemkv carries no drive-unlock mechanism. The `Unlocker` trait + registry
-(`src/unlock.rs`) is the seam: an external crate implements `Unlocker` and
-registers it once via `register_unlocker(...)`. At drive-prep the registry is
-walked in order and the first unlocker whose `matches()` is true is asked to
-`unlock_drive()` over the raw `ScsiTransport`. If none match, the drive is left
-untouched and the host-certificate AACS handshake carries the disc.
+| Chipset | Drives | Status |
+|---------|--------|--------|
+| MediaTek MT1959 | LG, ASUS, HP | Supported (bundled profiles) |
+| Renesas RS8xxx/RS9xxx | Pioneer, some HL-DT-ST | Planned |
 
-The implementor owns everything firmware-specific — drive profiles, vendor CDBs,
-variant logic. Concrete unlockers live in the separate
-**[freemkv-unlock](https://github.com/freemkv/freemkv-unlock)** repository, never
-in libfreemkv. See [`drive-access.md`](drive-access.md#drive-unlock-seam) for the
-trait definition and routing.
+The `Platform` trait abstracts chipset-specific commands. Each chipset implements
+handlers (unlock, config, register, calibrate, keepalive, status, probe,
+read_sectors, timing). All handlers are accessed via SCSI READ BUFFER with
+chipset-specific mode and buffer ID bytes.
 
 ---
 

docs/clpi.md

@@ -69,23 +69,13 @@ Each stream PID entry header (14 bytes):
 ```
 Offset  Size  Field
 ------  ----  -----
-2       2     stream_PID (byte-aligned)
-4       10    Bit-packed block, 80 bits total (see below)
+0       2     Stream PID
+2       2     Reserved + EP stream type
+4       2     Number of coarse entries
+6       4     Number of fine entries (note: 32-bit, can be large)
+10      4     EP map start offset (relative to EP map start)
 ```
 
-The stream PID entry is **not** byte-aligned past `stream_PID`. Bytes 4..14 are one
-80-bit packed field, read as a `u64` plus a trailing `u16`:
-
-Bits    Width  Field
-----    -----  -----
-0-9     10     reserved
-10-13   4      EP_stream_type
-14-29   16     num_EP_coarse
-30-47   18     num_EP_fine
-48-79   32     EP_map_start_address (relative to the EP map start)
-
-Note `num_EP_fine` is **18 bits**, not 32. See `parse_cpi` in `src/clpi.rs`.
-
 libfreemkv parses only the first stream (primary video), which is sufficient for sector-level seeking.
 
 ### Two-Level Index
@@ -199,7 +189,7 @@ The full ripping pipeline chains three parsers:
 2. **CLPI** converts those timestamps to SPN ranges, then to sector extents.
 3. **UDF** provides the file's starting LBA on disc for absolute sector addressing.
 
-The `Disc::scan()` method in `src/disc/mod.rs` orchestrates this: for each play item in each playlist, it loads the corresponding CLPI, calls `get_extents()` with the play item's in/out times, and collects the resulting sector ranges into the title's extent list.
+The `Disc::scan()` method in `src/disc.rs` orchestrates this: for each play item in each playlist, it loads the corresponding CLPI, calls `get_extents()` with the play item's in/out times, and collects the resulting sector ranges into the title's extent list.
 
 ## References
 

docs/disc-to-rip.md

@@ -10,14 +10,14 @@ Insert disc
     │
     ▼
 1. Open drive (drive/mod.rs)
-    │  INQUIRY → identify drive (DriveId)
+    │  INQUIRY → identify drive
+    │  Match bundled profile → chipset, unlock parameters
     │
     ▼
-2. Init drive (drive/mod.rs → unlock seam)
-    │  Walk the registered-unlocker registry; first match unlocks the drive
-    │  (firmware/vendor handshakes are the unlocker's own business)
-    │  No match → drive untouched; host-cert AACS handshake carries the disc
-    │  Speed control → probe_disc()
+2. Init drive (drive/mod.rs → platform/mt1959)
+    │  Firmware upload (if needed, 10s recovery wait)
+    │  Unlock → vendor-specific command activates raw read mode
+    │  Speed calibration → probe_disc()
     │
     ▼
 3. AACS handshake (aacs/handshake.rs) — optional
@@ -79,7 +79,7 @@ Insert disc
      │  Or: read sectors → decrypt → raw bytes (for ISO output)
      │  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 — freemkv_engine::recovery::patch re-runs against the mapfile.
+     │  1 above this — Disc::patch re-runs against the mapfile.
      │
      ▼
   PES frames → output stream (MKV, M2TS, network, etc.)
@@ -98,7 +98,7 @@ drive.probe_disc()?;
 let disc = Disc::scan(&mut drive, &ScanOptions::default())?;
 
 // Stream pipeline — PES frames from any source to any output.
-// input() returns Box<dyn FrameSource>, output() returns Box<dyn FrameSink>;
+// 0.18: input() returns Box<dyn FrameSource>, output() returns Box<dyn FrameSink>;
 // direction is type-checked, so calling .write() on an input is a compile error.
 let opts = InputOptions::default();
 let mut input = libfreemkv::input("disc:///dev/sg4", &opts)?;
@@ -123,7 +123,7 @@ output.finish()?;
 | aacs/ | [aacs.md](aacs.md) | Key resolution + content decrypt + bus handshake |
 | css/ | -- | DVD CSS cipher |
 | decrypt.rs | -- | Unified decrypt dispatcher (AACS/CSS/None) |
-| disc/ | [rip-recovery.md](rip-recovery.md) | Disc::scan (sweep/patch/mapfile moved to freemkv-engine in 1.6.0) |
+| disc/ | [rip-recovery.md](rip-recovery.md) | Disc::scan + Disc::sweep + Disc::patch + mapfile |
 | labels/ | -- | BD-J stream labels (5 format parsers) |
 | mux/ | -- | Stream implementations (7 stream types) |
 | pes.rs | -- | PES frame types + FrameSource / FrameSink traits |

docs/drive-access.md

@@ -7,9 +7,8 @@ optical drives.
 
 ## Drive
 
-`Drive` is the primary API. It owns the SCSI transport and the drive
-identity (`DriveId`); any drive-specific unlock logic lives behind the
-pluggable [unlock seam](#drive-unlock-seam), not in `Drive` itself.
+`Drive` is the primary API. It owns the SCSI transport, the matched
+drive profile, and the chipset-specific platform driver.
 
 ### Opening a Drive
 
@@ -17,16 +16,15 @@ pluggable [unlock seam](#drive-unlock-seam), not in `Drive` itself.
 let mut drive = Drive::open(Path::new("/dev/sg4"))?;
 ```
 
-`open()` performs: open device → send INQUIRY → build `DriveId`. The drive
-is ready for `wait_ready()` and `init()` (which routes through the unlock
-seam).
+`open()` performs: open device → send INQUIRY → match profile → instantiate
+platform driver. The drive is ready for `wait_ready()` and `init()`.
 
 ### Drive Operations
 
 | Method | Description |
 |--------|-------------|
 | `wait_ready()` | Wait for disc insertion (30s timeout, TUR polling) |
-| `init()` | Route to the matching registered unlocker (if any), then prepare for reads |
+| `init()` | Firmware upload + unlock + speed calibration |
 | `probe_disc()` | Probe disc surface for optimal speeds |
 | `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. |
@@ -34,21 +32,17 @@ seam).
 | `unlock_tray()` | Allow tray ejection (also runs on Drop) |
 | `eject()` | Eject disc tray |
 | `drive_status()` | Query physical state (disc present, tray open, etc.) |
-| `has_profile()` | Whether a registered unlocker matches this drive |
+| `has_profile()` | Whether a bundled profile matched |
 | `close()` | Consume Drive, cleanup (also runs via Drop) |
 
 ### init() Sequence
 
-`init()` routes drive preparation through the unlock seam:
+`init()` orchestrates the full drive unlock:
 
-1. Walk the registered-unlocker registry; the first whose `matches()` is true
-   is asked to `unlock_drive()` over the raw transport.
-2. Whatever that unlocker needs (firmware upload, vendor handshakes, retries)
-   is the unlocker's own business — libfreemkv only forwards the transport.
-3. If no unlocker matches, the drive is left untouched and the library uses
-   the host-certificate AACS handshake.
-
-See [Drive Unlock Seam](#drive-unlock-seam) for the trait and registry.
+1. Platform driver `run_init()` — sends vendor-specific SCSI commands
+2. If firmware upload needed: upload, wait 10s for drive reset, retry
+3. Speed calibration after unlock
+4. Max 3 attempts before giving up
 
 ### read() — single-shot
 
@@ -58,16 +52,15 @@ selects the per-CDB timeout:
 
 | `recovery` | Timeout  | Used by                                  |
 |------------|----------|------------------------------------------|
-| `false`    | 10 s     | `freemkv_engine::recovery::sweep` fast skip-forward pass, `DiscStream::fill_extents` |
-| `true`     | 60 s     | `freemkv_engine::recovery::patch` retry pass over the mapfile |
+| `false`    | 1.5 s    | `Disc::sweep` fast skip-forward pass, `DiscStream::fill_extents` |
+| `true`     | 30 s     | `Disc::patch` retry pass over the mapfile |
 
 On any SCSI failure or timeout, `read` returns `Err(DiscRead)` immediately.
 There are no inline retries, no SCSI reset, no Phase 1/2/3 escalation.
 
 Recovery is layered above `Drive::read`:
 
-- **Layer 1 — `freemkv_engine::recovery::patch`** (in the engine crate, not
-  here) loops over the ddrescue mapfile and re-issues
+- **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
@@ -171,68 +164,100 @@ date for drives where Feature 010C is unavailable.
 
 ---
 
-## Drive Unlock Seam
+## Drive Profiles
 
-libfreemkv ships **no firmware, no unlock CDBs, and no drive profiles.** It
-knows only the *seam*, never the *mechanism*. The seam is the `Unlocker`
-trait plus a small process-wide registry (`src/unlock.rs`):
+Profiles are JSON objects compiled into the binary (`profiles.json`).
+Each profile contains:
+
+| Field | Purpose |
+|-------|---------|
+| `vendor_id`, `product_revision`, `vendor_specific`, `firmware_date` | Matching fields |
+| `chipset` | `"mediatek"` or `"renesas"` |
+| `unlock_mode`, `unlock_buf_id` | READ BUFFER CDB parameters |
+| `signature` | Expected 4-byte response signature |
+| `unlock_cdb` | Pre-built unlock CDB (hex-encoded) |
+| `register_offsets` | Offsets for hardware register reads |
+| `capabilities` | Feature flags: `bd_raw_read`, `dvd_all_regions`, etc. |
+
+Loading:
 
 ```rust
-pub trait Unlocker: Send + Sync {
-    /// Stable, language-neutral identifier (logged).
-    fn name(&self) -> &str;
+// Bundled (compiled-in) -- no file I/O
+let profiles = profile::load_bundled()?;
 
-    /// True if this unlocker handles the given drive.
-    fn matches(&self, id: &DriveId) -> bool;
-
-    /// Put the drive into extended-access mode. The one required capability.
-    fn unlock_drive(&self, scsi: &mut dyn ScsiTransport, id: &DriveId) -> Result<()>;
-
-    /// Read the disc Volume ID via the drive's OEM path. Default: no-op.
-    fn read_volume_id(&self, _scsi: &mut dyn ScsiTransport, _id: &DriveId)
-        -> Result<Option<[u8; 16]>> { Ok(None) }
-
-    /// Raise the drive to its maximum read speed. Default: no-op.
-    fn set_max_read_speed(&self, _scsi: &mut dyn ScsiTransport, _id: &DriveId)
-        -> Result<()> { Ok(()) }
-}
+// External file
+let profiles = profile::load_all(Path::new("/path/to/profiles.json"))?;
 ```
 
-An unlocker is supplied by an **external crate** and registered once at
-process start:
+---
 
-```rust
-libfreemkv::register_unlocker(Box::new(some_unlocker::Plugin::new()));
-```
+## Chipsets
 
-The implementor owns everything about *how* a particular drive family is
-driven — drive identification against its own profile database, firmware
-upload, vendor CDBs, variant logic. libfreemkv only hands over the raw
-`ScsiTransport` and the `DriveId`.
+### MediaTek MT1959
 
-### Routing
+Covers all LG, ASUS, and HP optical drives. Two sub-variants share identical
+logic with different SCSI parameters:
 
-At drive-prep the registry is walked in registration order; the first
-unlocker whose `matches()` returns true is asked to `unlock_drive()` (and,
-when needed, `read_volume_id()` / `set_max_read_speed()`). If no unlocker
-matches, the drive is left untouched and the library falls back to the
-standard host-certificate AACS handshake (the "OEM route"). The
-`register_unlocker(...)` line is the entire plug: drop it (and the unlocker
-crate) and libfreemkv still compiles and rips via the cert handshake.
+| Variant | READ BUFFER mode | Buffer ID |
+|---------|------------------|-----------|
+| MT1959-A | 0x01 | 0x44 |
+| MT1959-B | 0x02 | 0x77 |
 
-Concrete unlockers — including the firmware-unlock profile databases,
-variant logic, and vendor CDBs that used to live in-tree — are maintained
-in the separate **[freemkv-unlock](https://github.com/freemkv/freemkv-unlock)**
-repository, never here.
+The Platform trait maps to command handlers:
+
+| Handler | Function | Description |
+|---------|----------|-------------|
+| 0 | `unlock()` | Send READ BUFFER, verify signature + verification bytes |
+| 1 | `read_config()` | Read 1888-byte configuration block + 4-byte status |
+| 2-3 | `read_register()` | Read hardware registers at profile-specified offsets |
+| 4 | `calibrate()` | Probe disc surface, build 64-entry speed table |
+| 5 | `keepalive()` | Periodic session maintenance |
+| 6 | `status()` | Query current mode and feature flags |
+| 7 | `probe()` | Generic READ BUFFER with dynamic parameters |
+| 8 | `read_sectors()` | Speed lookup + SET CD SPEED + READ(10) with flag 0x08 |
+| 9 | `timing()` | Timing calibration |
+
+### Renesas (Planned)
+
+RS8xxx/RS9xxx chipsets used in Pioneer and some HL-DT-ST drives.
+Currently returns `Error::UnsupportedDrive` when a Renesas profile is matched.
+
+---
+
+## Why Unlock Is Needed
+
+Optical drive firmware restricts what applications can read from disc. Without
+unlock:
+
+- **READ(10) works for unencrypted filesystem data.** UDF structures, MPLS
+  playlists, and CLPI clip info are readable without unlock. Standard READ(10)
+  works on any drive.
+
+- **READ(10) fails for encrypted content sectors.** The drive firmware returns
+  SCSI errors (sense key 0x05, illegal request) when an application attempts to
+  read sectors containing encrypted m2ts content without prior AACS
+  authentication via the bus key.
+
+- **Raw mode bypasses firmware restrictions.** After unlock, the drive accepts
+  READ(10) with the raw read flag (CDB byte 1 = 0x08) for all sectors,
+  regardless of encryption status.
+
+### AACS Before Unlock
+
+AACS bus authentication uses standard MMC REPORT KEY / SEND KEY commands.
+On some drives these must execute before unlock. The `Disc::scan()` handles
+this internally — it manages the handshake/unlock ordering automatically.
 
 ---
 
 ## Speed Control
 
-A matching unlocker may raise the drive to its maximum read speed via
-`set_max_read_speed()` (a no-op when no unlocker matches or the unlocker
-declines). The library issues SET CD SPEED (0xBB) through the generic CDB
-builder; the concrete speed policy lives in the unlocker.
+After `probe_disc()`, the platform driver maintains a speed lookup table
+built by probing the disc surface. On each `read()` call, the driver:
+
+1. Looks up the optimal speed for the target LBA.
+2. Issues SET CD SPEED (0xBB) if the speed differs from current.
+3. Performs the READ(10).
 
 Available speeds:
 

docs/rip-recovery.md

@@ -1,38 +1,135 @@
-# Rip recovery — what libfreemkv owns
+# Rip recovery — three-layer architecture
 
-**Recovery strategy moved OUT of this crate in 1.6.0.** The forward sweep, the
-targeted retry pass, the ddrescue mapfile, damage classification and the
-multipass loop now live in the **`freemkv-engine`** crate as
-`freemkv_engine::recovery::{copy, sweep, patch}`. The dependency runs
-engine → libfreemkv, so this crate cannot call into the engine; front-ends
-(`freemkv` CLI, autorip) get recovery from the engine directly.
+`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.
 
-What stayed here are the two layers underneath the strategy: the single-shot
-read primitive, and the in-stream request-size adaptation that sits in front of
-it. This document covers those, plus the design constraints they encode — the
-constraints are the reason the strategy above them looks the way it does, so
-they belong with the code that enforces them.
-
-For the strategy itself — damage-jump thresholds, pass ordering, mapfile status
-state machine, wedge detection — read `freemkv-engine/src/recovery/`.
+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 | **`freemkv-engine`** (`recovery::patch`) | Re-reads non-`+` ranges with the long timeout. Idempotent; caller invokes N times. |
+| 1 — Bad-range retry | `Disc::patch` (one pass over the mapfile per call) | Re-reads non-`+` ranges with the long timeout. Idempotent; caller invokes 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` in `src/mux/disc.rs` | Halves the batch on failure, retries at the same LBA, walks back up on a clean-read streak. |
+| 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. |
 
-Layer 2 also translates drive facts: [`SenseFamily`](../src/scsi/mod.rs)
-classifies SCSI sense data into the categories the engine's strategy routes on
-(marginal vs. hardware vs. not-ready). Getting that classification wrong
-silently misroutes recovery, which is why it lives next to the transport rather
-than in the strategy.
+The library exposes flat verbs; the caller drives the multipass loop. Autorip
+runs `Disc::sweep` once, then loops `Disc::patch` until either the mapfile is
+clean or the configured retry budget is exhausted, then hands the ISO off to
+the mux pipeline. The `freemkv` CLI does the same shape with a
+terminal-output progress sink. Layer 3 runs inside any consumer of
+`DiscStream` (direct PES pipeline, ISO playback, etc.) without caller
+involvement.
 
-Layer 3 runs inside any consumer of `DiscStream` — direct PES pipeline, ISO
-playback — without caller involvement, and applies whether or not the engine's
-recovery is in play.
+Three primitives compose the disc-side flow:
 
-## In-stream — adaptive batch halving (`DiscStream::fill_extents`)
+| Primitive                 | What it does                                                          |
+|---------------------------|-----------------------------------------------------------------------|
+| `Disc::sweep`             | disc → ISO, one forward pass. Writes a sidecar `.mapfile`. Opt-in skip-on-error. |
+| `Disc::patch`             | Re-reads bad ranges from the drive. One pass per call; caller invokes N times. |
+| `DiscStream` (ISO source) | Reads sectors from the ISO, feeds decrypt → demux → codec → mux.      |
+
+## Data model
+
+### Mapfile
+
+Format: [ddrescue](https://www.gnu.org/software/ddrescue/manual/ddrescue_manual.html)-compatible
+plain text, greppable, tool-interoperable. Flushed to disk on every `record()`
+so a crashed rip loses at most one block.
+
+```
+# Rescue Logfile. Created by libfreemkv v0.13.6
+# Current pos / status / pass / pass_time
+0x000000000  ?  1  0
+#      pos        size  status
+0x000000000  0x12a35d000    +
+0x12a35d000  0x000003000    -
+0x12a360000  0x009c4a000    +
+0x12d00a000  0x000064000    *
+```
+
+Status characters match ddrescue:
+
+| Char | Meaning                                            |
+|------|----------------------------------------------------|
+| `?`  | Not yet attempted                                  |
+| `*`  | Fast-pass failed; needs edge-trim                  |
+| `/`  | Trimmed; interior needs sector scrape              |
+| `-`  | Unreadable this session                            |
+| `+`  | Finished (good)                                    |
+
+Position and size are hex byte offsets into the ISO.
+
+### `SweepOptions` and `PatchOptions`
+
+The library no longer dispatches between sweep and patch internally — the
+caller picks the verb explicitly per pass. The two option structs are flat
+and have no overlap:
+
+```rust
+SweepOptions {
+    decrypt: true,
+    resume: false,
+    batch_sectors: None,
+    skip_on_error: true,           // damage-jump + zero-fill on read failure
+    progress: Some(&reporter),
+    halt: Some(flag),
+}
+
+PatchOptions {
+    decrypt: true,
+    block_sectors: None,
+    full_recovery: true,
+    reverse: true,                 // walk bad ranges high → low LBA
+    wedged_threshold: 50,
+    progress: Some(&reporter),
+    halt: Some(flag),
+}
+```
+
+Caller-orchestrated dispatch (the policy `Disc::copy` used to embed):
+
+- No mapfile → `sweep` (fresh Pass 1).
+- Mapfile with `?` ranges → `sweep` with `resume: true`.
+- Mapfile covers full disc, only `*` / `/` / `-` ranges → `patch`.
+- Mapfile clean → done; no further pass needed.
+
+Each consumer (autorip, `freemkv` CLI) implements the loop in roughly five
+lines of `Mapfile::stats()` checks.
+
+## Algorithm
+
+### Pass 1 — fast sweep (`Disc::sweep`)
+
+1. Read one ECC block (32 sectors for UHD, 16 for BD/DVD) at the current LBA.
+2. On success: write data to ISO, mark `+`, advance.
+3. On failure (with `multipass`): zero-fill, mark `*`, advance.
+4. Track a sliding window of the last 16 ECC block results. When ≥12% are failures
+   → **damage-jump**: skip ahead by `256×batch×multiplier` sectors (8 MB base for
+   UHD). Double the multiplier on each jump (8→16→32→64 MB...). Zero-fill the gap as `*`.
+5. On 16 consecutive good reads: reset jump multiplier to 1, restore max read speed.
+6. Speed control: damage zone entry → minimum speed, exit → maximum speed.
+7. Only transport failures (USB bridge crash) abort the pass.
+
+Pass 1 completes when every byte has been visited (either `+` or `*`).
+
+### Pass 2+ — patch (`Disc::patch`)
+
+`Disc::patch` reads the mapfile and iterates every non-`+` range. Default: **reverse** mode
+(walks ranges from highest LBA to lowest, within each range from end to start).
+
+1. Issue a single-sector read with 60 s timeout (`recovery=true`). Drive firmware
+   does its own ECC recovery inside that window.
+2. On success: write the good bytes into the ISO, mark `+`.
+3. On failure with non-marginal SCSI sense: bail immediately (drive won't produce data).
+4. On failure with marginal sense: mark `-`, continue.
+5. Update the mapfile after every block — crash-safe resume.
+6. Wedged-drive exit: 50 consecutive failures with zero recovery → bail this pass.
+
+### 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`:
@@ -46,53 +143,59 @@ When a consumer reads a `DiscStream` directly (no ISO intermediate),
    `EventKind::SectorSkipped`) when `skip_errors` is set, otherwise return
    `Err(DiscRead)`.
 
-This exists so a transient single-sector glitch inside a 32-sector batch can be
-isolated and read individually without the caller implementing retry logic. See
-[`src/event.rs`](../src/event.rs) for the emitted events.
+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
 
-These are constraints on the read path, enforced here and relied on by the
-engine's strategy.
+**`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 the stop-wedge postmortem (2026-04-25) 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.
 
-**`Drive::read` is single-shot.** No inline retry phases, no SCSI reset, no
-eject cycle. The `recovery` flag controls only the per-CDB timeout (10 s vs.
-60 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 the stop-wedge postmortem (2026-04-25) 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 nothing to show for it. Recovery responsibility
-is layered instead: layer 1 handles ranges, layer 3 handles request size,
-neither touches the wedge-prone reset path.
+**No `MODE SELECT` to disable drive retries.** Research showed neither ddrescue
+nor MakeMKV does this. Drive firmware has access to raw analog signal, laser
+power control, and drive-specific ECC tuning that userspace can't replicate —
+disabling it throws away recovery headroom on marginal sectors. We fail fast
+via short SG_IO timeouts in pass 1 and let the firmware work the long timeout
+in pass 2 / patch.
 
-**No `MODE SELECT` to disable drive retries.** Neither ddrescue nor any
-consumer ripper does this. Drive firmware has access to raw analog signal,
-laser power control and drive-specific ECC tuning that userspace cannot
-replicate — disabling it throws away recovery headroom on marginal sectors. The
-fast pass fails quickly via short SG_IO timeouts and lets the firmware work the
-long timeout during retry.
+**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.
 
-**No SCSI reset from any read path.** There is no reset escape hatch on
-`Drive` at all: the `SG_SCSI_RESET` ioctl and STOP/START UNIT escalation went in
-0.13.6, the macOS reset (always a no-op) was removed entirely, and the
-top-level `scsi::reset()` wrappers went with their last callers. The only
-remaining reset is a Windows-specific device-level helper in
-[`src/scsi/windows.rs`](../src/scsi/windows.rs), never reached from a read.
-
-**ISO intermediate, even for single-pass.** The engine's Pass 1 always writes
-an ISO, and the mux stage reads it back via `FileSectorSource`. For a
-no-retry rip this costs a few minutes but buys resumability across crashes,
+**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 it with `DiscStream::new(Box::new(drive), …)` —
-nothing forbids it, and layer 3 still applies there.
+who need pure speed can bypass and use `DiscStream::new(Box::new(drive), …)`
+directly — the lib doesn't forbid it, and layer 3 (adaptive batch halving)
+still applies there.
+
+**Mapfile in ddrescue format.** Plain text so users can `less` it, `diff` it,
+or feed it to ddrescue's own tooling. Crash-safe (flush-per-record). Entries
+coalesce on adjacent same-status ranges so files stay small.
+
+**Patches target `-`, `*`, `/`, and `?` alike.** The status state machine is
+ddrescue's but `patch` collapses the distinction — it just tries every
+non-finished range with the long timeout. Future work can specialize (trim vs.
+scrape vs. retry with direction reversal) if there's measured benefit.
 
 ## References
 
 - [ddrescue manual, Algorithm chapter](https://www.gnu.org/software/ddrescue/manual/ddrescue_manual.html)
 - [ddrescue optical media notes](https://www.electric-spoon.com/doc/gddrescue/html/Optical-media.html)
-- Recovery strategy and mapfile: `freemkv-engine/src/recovery/`
-- In this crate: [`src/drive/mod.rs`](../src/drive/mod.rs) (`Drive::read`),
-  [`src/scsi/mod.rs`](../src/scsi/mod.rs) (`SenseFamily`),
-  [`src/mux/disc.rs`](../src/mux/disc.rs) (`DiscStream::fill_extents`),
-  [`src/event.rs`](../src/event.rs) (progress events).
+- Source: [`src/disc/mapfile.rs`](../src/disc/mapfile.rs), [`src/disc/sweep.rs`](../src/disc/sweep.rs) (`Disc::sweep`), [`src/disc/patch.rs`](../src/disc/patch.rs) (`Disc::patch`), [`src/drive/mod.rs`](../src/drive/mod.rs) (`Drive::read`), [`src/mux/disc.rs`](../src/mux/disc.rs) (`DiscStream::fill_extents`).

docs/udf.md

@@ -114,7 +114,7 @@ The `read_filesystem()` function in `src/udf.rs` follows the pointer chain above
 2. Scans sectors 32-63 for the Partition Descriptor and Logical Volume Descriptor.
 3. If two partition maps exist and the second is Type 2, reads the metadata file ICB at partition_start to find metadata_start.
 4. Reads the FSD at metadata_start, extracts the root directory ICB LBA.
-5. Calls `read_directory()` recursively (max depth `MAX_DIR_DEPTH` = 8) to build the full file tree.
+5. Calls `read_directory()` recursively (max depth 3) to build the full file tree.
 
 Each directory read involves two sector reads: one for the ICB, then one or more for the directory data. File sizes are read from info_length in each file's ICB.
 

examples/iso_dump.rs

@@ -0,0 +1,83 @@
+// Minimal ISO dumper — find exact stall point
+use libfreemkv::Drive;
+use std::io::{BufWriter, Write};
+use std::path::Path;
+use std::time::Instant;
+
+fn main() {
+    let args: Vec<String> = std::env::args().collect();
+    if args.len() < 3 {
+        eprintln!("Usage: iso_dump <device> <output>");
+        std::process::exit(1);
+    }
+
+    let mut drive = Drive::open(Path::new(&args[1])).unwrap();
+    drive.wait_ready().unwrap();
+    let _ = drive.init();
+    let _ = drive.probe_disc();
+
+    // AACS handshake — required to read past the protected area
+    eprint!("Scanning disc... ");
+    let _ = libfreemkv::Disc::scan(&mut drive, &libfreemkv::ScanOptions::default());
+    eprintln!("OK");
+
+    let cap = drive.read_capacity().unwrap();
+    let batch = libfreemkv::disc::detect_max_batch_sectors(drive.device_path());
+
+    eprintln!("Device: {} | {} sectors | batch {}", args[1], cap, batch);
+
+    let file = std::fs::File::create(&args[2]).unwrap();
+    let mut w = BufWriter::with_capacity(4 * 1024 * 1024, file);
+    let mut buf = vec![0u8; batch as usize * 2048];
+    let mut lba: u32 = 0;
+    let start = Instant::now();
+    let mut last = Instant::now();
+    let mut bytes: u64 = 0;
+    let mut last_bytes: u64 = 0;
+
+    while lba < cap {
+        let count = ((cap - lba) as u16).min(batch);
+        let n = count as usize * 2048;
+
+        // Tiny yield between reads — test if pacing prevents firmware throttle
+        std::thread::yield_now();
+        let t0 = Instant::now();
+        let ok = drive.read(lba, count, &mut buf[..n], true).is_ok();
+        let read_ms = t0.elapsed().as_millis();
+
+        // Flag slow reads
+        if read_ms > 2000 {
+            eprintln!("\n  SLOW READ: LBA {} took {}ms (ok={})", lba, read_ms, ok);
+        }
+
+        if !ok {
+            buf[..n].fill(0);
+        }
+        w.write_all(&buf[..n]).unwrap();
+        lba += count as u32;
+        bytes += n as u64;
+
+        if last.elapsed().as_millis() >= 1000 {
+            let delta = bytes - last_bytes;
+            let speed = delta as f64 / last.elapsed().as_secs_f64() / 1_048_576.0;
+            let avg = bytes as f64 / start.elapsed().as_secs_f64() / 1_048_576.0;
+            let pct = bytes as f64 / (cap as f64 * 2048.0) * 100.0;
+            eprint!(
+                "\r  {:.1}% LBA {} | {:.0} MB/s (avg {:.0}) | {:.1} GB    ",
+                pct,
+                lba,
+                speed,
+                avg,
+                bytes as f64 / 1e9
+            );
+            last_bytes = bytes;
+            last = Instant::now();
+        }
+    }
+    w.flush().unwrap();
+    eprintln!(
+        "\nDone: {:.1} GB in {:.0}s",
+        bytes as f64 / 1e9,
+        start.elapsed().as_secs_f64()
+    );
+}

src/aacs/crypto.rs

@@ -1,268 +0,0 @@
-//! AACS common cryptographic primitives — [C] Chapter 2 / §3.2.2.
-//!
-//! Source: `[C]` = AACS Introduction and Common Cryptographic Elements Book,
-//! Rev 0.953. The shared low-level building blocks — AES-128 ECB E/D, AES-G,
-//! the AES-G3 Triple Generator, AES-CBC decrypt — and their fixed constants
-//! (`iv0`, `s0`). Used by every AACS generation; relocated here so the
-//! primitives live in one place instead of being scattered across the
-//! content / keys / variant modules.
-
-use aes::Aes128;
-use aes::cipher::{Array, BlockCipherDecrypt, BlockCipherEncrypt, KeyInit};
-
-/// Fixed IV used by AACS for all AES-CBC operations. [C] §2.1.2 (default CBC IV, `iv0`).
-pub(crate) const AACS_IV: [u8; 16] = [
-    0x0B, 0xA0, 0xF8, 0xDD, 0xFE, 0xA6, 0x1F, 0xB3, 0xD8, 0xDF, 0x9F, 0x56, 0x6A, 0x05, 0x0F, 0x78,
-];
-
-// Per-thread count of AES-128 key schedules built through `new_cipher`.
-// Test-only instrumentation: an AES-128 key expansion is 10 round-key
-// derivations, and the CBC helpers here run on the per-aligned-unit decrypt hot
-// path of a whole disc read, so "how many times was the schedule built for one
-// loop-invariant key" is a property worth asserting rather than reasoning about.
-// THREAD-LOCAL, not a global atomic: `cargo test` runs tests concurrently, so a
-// shared counter would see every other test's expansions. See
-// `content::tests::decrypt_bus_expands_the_read_data_key_once_per_unit`.
-#[cfg(test)]
-thread_local! {
-    pub(crate) static KEY_EXPANSIONS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
-}
-
-/// Build an AES-128 key schedule for a caller that will drive
-/// [`cbc_decrypt_blocks`] over several regions under one key.
-pub(crate) fn new_cipher_for(key: &[u8; 16]) -> Aes128 {
-    new_cipher(key)
-}
-
-/// Build an AES-128 key schedule. The single construction site for the CBC
-/// helpers, so [`KEY_EXPANSIONS`] can count them under test.
-fn new_cipher(key: &[u8; 16]) -> Aes128 {
-    #[cfg(test)]
-    KEY_EXPANSIONS.with(|c| c.set(c.get() + 1));
-    Aes128::new(&(*key).into())
-}
-
-/// AES-128-ECB encrypt a single 16-byte block. [C] §2.1.1 (`AES-128E`).
-pub(crate) fn aes_ecb_encrypt(key: &[u8; 16], data: &[u8; 16]) -> [u8; 16] {
-    let cipher = Aes128::new(&(*key).into());
-    let mut block: Array<u8, _> = (*data).into();
-    cipher.encrypt_block(&mut block);
-    let mut out = [0u8; 16];
-    out.copy_from_slice(&block);
-    out
-}
-
-/// AES-128-ECB decrypt a single 16-byte block. [C] §2.1.1 (`AES-128D`).
-pub(crate) fn aes_ecb_decrypt(key: &[u8; 16], data: &[u8; 16]) -> [u8; 16] {
-    let cipher = Aes128::new(&(*key).into());
-    let mut block: Array<u8, _> = (*data).into();
-    cipher.decrypt_block(&mut block);
-    let mut out = [0u8; 16];
-    out.copy_from_slice(&block);
-    out
-}
-
-/// AES-128-CBC ENCRYPT in place under the fixed [`AACS_IV`] — the forward
-/// direction of [`aes_cbc_decrypt`], and its exact inverse. [C] §2.1.2
-/// (`AES-128CBCE`).
-///
-/// Precondition: `data.len()` is a multiple of 16; the assert
-/// documents/enforces that contract.
-///
-/// Constructs the cipher ONCE for the whole slice. Driving this from the
-/// single-block [`aes_ecb_encrypt`] instead rebuilds the AES key schedule per
-/// 16-byte block, which for a 6144-byte aligned unit is 383 redundant key
-/// expansions.
-pub(crate) fn aes_cbc_encrypt(key: &[u8; 16], data: &mut [u8]) {
-    debug_assert!(
-        data.len().is_multiple_of(16),
-        "aes_cbc_encrypt requires a block-aligned slice"
-    );
-    let cipher = new_cipher(key);
-    let num_blocks = data.len() / 16;
-    let mut prev = AACS_IV;
-    // Forward order: each block is XORed with the PRECEDING ciphertext block.
-    for i in 0..num_blocks {
-        let offset = i * 16;
-        let mut block = [0u8; 16];
-        for j in 0..16 {
-            block[j] = data[offset + j] ^ prev[j];
-        }
-        let mut ga: Array<u8, _> = block.into();
-        cipher.encrypt_block(&mut ga);
-        data[offset..offset + 16].copy_from_slice(&ga);
-        prev.copy_from_slice(&ga);
-    }
-}
-
-/// AES-128-CBC DECRYPT in-place with the fixed AACS IV. [C] §2.1.2
-/// (`AES-128CBCD`).
-///
-/// Precondition: `data.len()` is a multiple of 16. Any trailing partial
-/// block is silently ignored; all callers pass aligned regions (6128 and
-/// 2032 bytes), and the assert documents/enforces that contract.
-///
-/// (This doc block was orphaned onto `aes_cbc_encrypt` above when that function
-/// was inserted directly after it with no separating blank line, so rustdoc
-/// rendered the crate's only forward-direction AACS primitive as "decrypt" and
-/// cited the spec's DECRYPT clause for it, while this function had no doc at
-/// all. `encrypt_unit_is_the_exact_inverse_of_decrypt_unit` in `content.rs` pins
-/// the directions behaviourally so a maintainer 'fixing' the contradiction by
-/// swapping the two bodies fails the suite instead of shipping a second
-/// decryptor behind an already-set encrypted flag.)
-pub(crate) fn aes_cbc_decrypt(key: &[u8; 16], data: &mut [u8]) {
-    debug_assert!(
-        data.len().is_multiple_of(16),
-        "aes_cbc_decrypt requires a block-aligned slice"
-    );
-    cbc_decrypt_blocks(&new_cipher(key), data);
-}
-
-/// AES-128-CBC decrypt in place under the fixed [`AACS_IV`] with an ALREADY
-/// EXPANDED key schedule.
-///
-/// Split out of [`aes_cbc_decrypt`] so a caller that decrypts several regions
-/// under one loop-invariant key expands the schedule once. `decrypt_bus`
-/// ([`super::content::decrypt_bus`]) is that caller: bus encryption
-/// ([C] §4.2 / the AACS 2.0 Read Data Key) covers bytes 16..2048 of EVERY
-/// 2048-byte sector, so a 6144-byte aligned unit is three regions under one
-/// `read_data_key` — three key schedules where one suffices, on the per-unit
-/// decrypt hot path of a whole 90 GB read.
-pub(crate) fn cbc_decrypt_blocks(cipher: &Aes128, data: &mut [u8]) {
-    let num_blocks = data.len() / 16;
-    // Process blocks in reverse to avoid clobbering ciphertext needed for XOR
-    for i in (0..num_blocks).rev() {
-        let offset = i * 16;
-        let prev = if i == 0 {
-            AACS_IV
-        } else {
-            let mut p = [0u8; 16];
-            p.copy_from_slice(&data[(i - 1) * 16..i * 16]);
-            p
-        };
-        let mut chunk = [0u8; 16];
-        chunk.copy_from_slice(&data[offset..offset + 16]);
-        let mut block: Array<u8, _> = chunk.into();
-        cipher.decrypt_block(&mut block);
-        for j in 0..16 {
-            data[offset + j] = block[j] ^ prev[j];
-        }
-    }
-}
-
-/// AES-G(x1, x2) = AES-128D(x1, x2) XOR x2. [C] §2.1.3 (note: uses AES-128**D**).
-///
-/// The Media Key Variant chain uses AES-G to derive both the variant
-/// number (`Kvn = AES-G(Kp, Nonce)`) and the Volume Unique Key
-/// (`Kvu = AES-G(Km, VID)`). See [`super::derive::derive_vuk`] for the
-/// classical VUK form — the math is identical, this exposes it as a
-/// neutral primitive for the variant chain.
-pub(crate) fn aes_g(x1: &[u8; 16], x2: &[u8; 16]) -> [u8; 16] {
-    let mut out = aes_ecb_decrypt(x1, x2);
-    for i in 0..16 {
-        out[i] ^= x2[i];
-    }
-    out
-}
-
-/// AACS-G3 seed constant (`s0`). [C] §3.2.2.
-pub(crate) const AESG3_SEED: [u8; 16] = [
-    0x7B, 0x10, 0x3C, 0x5D, 0xCB, 0x08, 0xC4, 0xE5, 0x1A, 0x27, 0xB0, 0x17, 0x99, 0x05, 0x3B, 0xD9,
-];
-
-/// AACS-G3: derive a subkey from a parent key. [C] §3.2.2 (Triple AES Generator:
-/// left=`D(k,s0)⊕s0` inc 0, pk=`D(k,s0+1)⊕(s0+1)` inc 1, right=`D(k,s0+2)⊕(s0+2)` inc 2).
-/// seed[15] += inc, then AES-DEC(key, seed) XOR seed.
-///
-/// Shared with [`super::variant`] (its variant chain runs the same SD
-/// tree); a single definition keeps the two walks byte-identical.
-pub(crate) fn aesg3(key: &[u8; 16], inc: u8) -> [u8; 16] {
-    let mut seed = AESG3_SEED;
-    seed[15] = seed[15].wrapping_add(inc);
-    let mut out = aes_ecb_decrypt(key, &seed);
-    for i in 0..16 {
-        out[i] ^= seed[i];
-    }
-    out
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    /// The AACS-G3 seed `s0`, transcribed independently from [C] §3.2.2 rather
-    /// than read from [`AESG3_SEED`] — a test that sourced the seed from the
-    /// production constant would assert that constant against itself and would
-    /// still pass if it were edited.
-    const S0: [u8; 16] = [
-        0x7B, 0x10, 0x3C, 0x5D, 0xCB, 0x08, 0xC4, 0xE5, 0x1A, 0x27, 0xB0, 0x17, 0x99, 0x05, 0x3B,
-        0xD9,
-    ];
-
-    /// An arbitrary non-degenerate key. Nothing about it is secret or special;
-    /// the AES-G3 relation holds for every key, and a constant-returning body
-    /// cannot satisfy it for any.
-    const K: [u8; 16] = [
-        0x0F, 0x1E, 0x2D, 0x3C, 0x4B, 0x5A, 0x69, 0x78, 0x87, 0x96, 0xA5, 0xB4, 0xC3, 0xD2, 0xE1,
-        0xF0,
-    ];
-
-    /// `aesg3` is the node function of the AACS subset-difference tree: every
-    /// Processing Key the DK walk produces (`aesg3(node_key, 1)`) and every
-    /// descent step (`aesg3(., 0)` / `aesg3(., 2)`) is one call. A body that
-    /// returned a fixed block would make every device key in the crate derive
-    /// the SAME Processing Key, and a `^` that became `|` or `&` would derive a
-    /// wrong-but-plausible one — in both cases the MKB walk simply stops
-    /// finding Media Keys, with no error to say why.
-    ///
-    /// Pinned through the spec relation rather than a re-implementation:
-    /// [C] §3.2.2 defines `AES-G3` as `AES-128D(k, s) XOR s` for
-    /// `s = s0 + inc` (added into the last seed byte), so applying the
-    /// FORWARD primitive [`aes_ecb_encrypt`] — a different function from the
-    /// one under test — to `aesg3(k, inc) XOR s` must reproduce `s` exactly.
-    #[test]
-    fn aesg3_inverts_to_the_spec_seed_under_aes_encrypt() {
-        for inc in 0u8..=2 {
-            let mut seed = S0;
-            seed[15] = seed[15].wrapping_add(inc);
-
-            let out = aesg3(&K, inc);
-
-            // out == AES-128D(K, seed) XOR seed, so out XOR seed is the raw
-            // decryption and re-encrypting it must land back on the seed.
-            let mut pre = [0u8; 16];
-            for i in 0..16 {
-                pre[i] = out[i] ^ seed[i];
-            }
-            assert_eq!(
-                aes_ecb_encrypt(&K, &pre),
-                seed,
-                "AES-G3 inc={inc} must satisfy out = AES-128D(k, s0+inc) XOR (s0+inc)"
-            );
-        }
-    }
-
-    /// The Triple Generator's three outputs ([C] §3.2.2: left = inc 0, the
-    /// Processing Key = inc 1, right = inc 2) are the two child node keys and
-    /// the Processing Key of ONE tree node. They must be three different keys —
-    /// if `inc` were ignored, a descent would revisit its own parent and the
-    /// walk would derive the same key at every level of the tree.
-    #[test]
-    fn aesg3_yields_three_distinct_subkeys_for_the_three_increments() {
-        let left = aesg3(&K, 0);
-        let pk = aesg3(&K, 1);
-        let right = aesg3(&K, 2);
-        assert_ne!(left, pk, "left child and Processing Key must differ");
-        assert_ne!(pk, right, "Processing Key and right child must differ");
-        assert_ne!(left, right, "left and right children must differ");
-    }
-
-    /// Distinct parent keys must yield distinct subkeys — the tree would
-    /// collapse otherwise.
-    #[test]
-    fn aesg3_separates_distinct_parent_keys() {
-        let mut other = K;
-        other[0] ^= 0x01;
-        assert_ne!(aesg3(&K, 1), aesg3(&other, 1));
-    }
-}

src/aacs/decrypt.rs

@@ -0,0 +1,299 @@
+//! AACS content decryption — AES primitives, unit decryption, bus encryption.
+
+use aes::Aes128;
+use aes::cipher::{BlockDecrypt, BlockEncrypt, KeyInit, generic_array::GenericArray};
+
+// ── AACS constants ──────────────────────────────────────────────────────────
+
+/// Fixed IV used by AACS for all AES-CBC operations.
+pub(crate) const AACS_IV: [u8; 16] = [
+    0x0B, 0xA0, 0xF8, 0xDD, 0xFE, 0xA6, 0x1F, 0xB3, 0xD8, 0xDF, 0x9F, 0x56, 0x6A, 0x05, 0x0F, 0x78,
+];
+
+/// Size of an AACS aligned unit (3 × 2048-byte sectors).
+pub const ALIGNED_UNIT_LEN: usize = 6144;
+
+/// Size of one sector.
+const SECTOR_LEN: usize = 2048;
+
+/// Transport stream packet spacing in Blu-ray m2ts (192 bytes = 4 TP_extra + 188 TS).
+const TS_PACKET_LEN: usize = 192;
+
+/// TS sync byte.
+const TS_SYNC: u8 = 0x47;
+
+// ── AES primitives ──────────────────────────────────────────────────────────
+
+/// AES-128-ECB encrypt a single 16-byte block.
+pub(crate) fn aes_ecb_encrypt(key: &[u8; 16], data: &[u8; 16]) -> [u8; 16] {
+    let cipher = Aes128::new(GenericArray::from_slice(key));
+    let mut block = GenericArray::clone_from_slice(data);
+    cipher.encrypt_block(&mut block);
+    let mut out = [0u8; 16];
+    out.copy_from_slice(&block);
+    out
+}
+
+/// AES-128-ECB decrypt a single 16-byte block.
+pub(crate) fn aes_ecb_decrypt(key: &[u8; 16], data: &[u8; 16]) -> [u8; 16] {
+    let cipher = Aes128::new(GenericArray::from_slice(key));
+    let mut block = GenericArray::clone_from_slice(data);
+    cipher.decrypt_block(&mut block);
+    let mut out = [0u8; 16];
+    out.copy_from_slice(&block);
+    out
+}
+
+/// AES-128-CBC decrypt in-place with the fixed AACS IV.
+/// AES-128-CBC decrypt in-place with the fixed AACS IV.
+pub(crate) fn aes_cbc_decrypt(key: &[u8; 16], data: &mut [u8]) {
+    let cipher = Aes128::new(GenericArray::from_slice(key));
+    let num_blocks = data.len() / 16;
+    // Process blocks in reverse to avoid clobbering ciphertext needed for XOR
+    for i in (0..num_blocks).rev() {
+        let offset = i * 16;
+        let prev = if i == 0 {
+            AACS_IV
+        } else {
+            let mut p = [0u8; 16];
+            p.copy_from_slice(&data[(i - 1) * 16..i * 16]);
+            p
+        };
+        let mut block = GenericArray::clone_from_slice(&data[offset..offset + 16]);
+        cipher.decrypt_block(&mut block);
+        for j in 0..16 {
+            data[offset + j] = block[j] ^ prev[j];
+        }
+    }
+}
+
+// ── Content decryption ──────────────────────────────────────────────────────
+
+/// Check if a 6144-byte aligned unit is encrypted (copy_permission_indicator bits).
+pub fn is_unit_encrypted(unit: &[u8]) -> bool {
+    unit.len() >= ALIGNED_UNIT_LEN && (unit[0] & 0xC0) != 0
+}
+
+/// Verify decrypted unit by checking TS sync bytes at expected offsets.
+fn verify_ts(unit: &[u8]) -> bool {
+    // In a 6144-byte unit, TS packets start at byte 0 with 4-byte TP_extra_header
+    // then 188-byte TS packet, repeating every 192 bytes.
+    // Sync byte 0x47 should appear at offset 4, 196, 388, ...
+    let mut count = 0;
+    let mut offset = 4;
+    while offset < unit.len() {
+        if unit[offset] == TS_SYNC {
+            count += 1;
+        }
+        offset += TS_PACKET_LEN;
+    }
+    // Expect at least most packets to have sync bytes
+    let total = (unit.len() - 4) / TS_PACKET_LEN + 1;
+    count > total / 2
+}
+
+/// Decrypt one AACS aligned unit (6144 bytes) in-place.
+/// Returns true if decryption succeeded (verified by TS sync bytes).
+///
+/// Algorithm:
+/// 1. AES-128-ECB encrypt first 16 bytes with unit_key → derived
+/// 2. XOR derived with original 16 bytes → unit_decrypt_key
+/// 3. AES-128-CBC decrypt bytes 16..6143 with unit_decrypt_key and AACS IV
+/// 4. Clear encryption flag bits
+pub fn decrypt_unit(unit: &mut [u8], unit_key: &[u8; 16]) -> bool {
+    if unit.len() < ALIGNED_UNIT_LEN {
+        return false;
+    }
+    if !is_unit_encrypted(unit) {
+        return true; // not encrypted
+    }
+
+    // Save original first 16 bytes (they're plaintext TP_extra_header)
+    let mut header = [0u8; 16];
+    header.copy_from_slice(&unit[..16]);
+
+    // Step 1: Encrypt header with unit key to derive per-unit key
+    let derived = aes_ecb_encrypt(unit_key, &header);
+
+    // Step 2: XOR to get the actual decryption key
+    let mut decrypt_key = [0u8; 16];
+    for i in 0..16 {
+        decrypt_key[i] = derived[i] ^ header[i];
+    }
+
+    // Step 3: Decrypt bytes 16..6143 with AES-CBC
+    aes_cbc_decrypt(&decrypt_key, &mut unit[16..ALIGNED_UNIT_LEN]);
+
+    // Step 4: Clear encryption flag
+    unit[0] &= !0xC0;
+
+    // Verify
+    verify_ts(unit)
+}
+
+/// Decrypt one aligned unit trying multiple unit keys. Returns the key index that worked.
+pub fn decrypt_unit_try_keys(unit: &mut [u8], unit_keys: &[[u8; 16]]) -> Option<usize> {
+    if !is_unit_encrypted(unit) {
+        return Some(0);
+    }
+
+    // Save original for retry
+    let original = unit[..ALIGNED_UNIT_LEN].to_vec();
+
+    for (i, key) in unit_keys.iter().enumerate() {
+        unit[..ALIGNED_UNIT_LEN].copy_from_slice(&original);
+        if decrypt_unit(unit, key) {
+            return Some(i);
+        }
+    }
+
+    // Restore original on failure
+    unit[..ALIGNED_UNIT_LEN].copy_from_slice(&original);
+    None
+}
+
+/// Remove bus encryption from an aligned unit (AACS 2.0 / UHD).
+/// Bus encryption uses read_data_key, decrypting bytes 16..2047 of each 2048-byte sector.
+pub fn decrypt_bus(unit: &mut [u8], read_data_key: &[u8; 16]) {
+    for sector_start in (0..ALIGNED_UNIT_LEN).step_by(SECTOR_LEN) {
+        if sector_start + SECTOR_LEN > unit.len() {
+            break;
+        }
+        // First 16 bytes of each sector are plaintext
+        aes_cbc_decrypt(
+            read_data_key,
+            &mut unit[sector_start + 16..sector_start + SECTOR_LEN],
+        );
+    }
+}
+
+/// Full decrypt of an aligned unit: bus decrypt (if needed) then AACS decrypt.
+pub fn decrypt_unit_full(
+    unit: &mut [u8],
+    unit_key: &[u8; 16],
+    read_data_key: Option<&[u8; 16]>,
+) -> bool {
+    if !is_unit_encrypted(unit) {
+        return true;
+    }
+    if let Some(rdk) = read_data_key {
+        decrypt_bus(unit, rdk);
+    }
+    decrypt_unit(unit, unit_key)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_aes_ecb_roundtrip() {
+        let key = [
+            0x15u8, 0x66, 0x5F, 0x98, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A,
+            0x0B, 0x0C,
+        ];
+        let plain = [0x41u8; 16];
+        let enc = aes_ecb_encrypt(&key, &plain);
+        let dec = aes_ecb_decrypt(&key, &enc);
+        assert_eq!(dec, plain);
+    }
+
+    #[test]
+    fn test_decrypt_unit_unencrypted() {
+        // Unit with 0xC0 bits clear should pass through unchanged
+        let mut unit = vec![0u8; ALIGNED_UNIT_LEN];
+        unit[0] = 0x00; // not encrypted
+        let key = [0u8; 16];
+        assert!(decrypt_unit(&mut unit, &key));
+    }
+
+    #[test]
+    fn test_aes_cbc_roundtrip() {
+        let key = [
+            0x11u8, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE,
+            0xFF, 0x00,
+        ];
+        let original = vec![0x42u8; 128]; // 8 blocks
+        let mut data = original.clone();
+
+        // Encrypt with CBC manually (forward direction)
+        fn aes_cbc_encrypt(key: &[u8; 16], data: &mut [u8]) {
+            let cipher = Aes128::new(GenericArray::from_slice(key));
+            let mut prev = super::AACS_IV;
+            let num_blocks = data.len() / 16;
+            for i in 0..num_blocks {
+                let offset = i * 16;
+                for j in 0..16 {
+                    data[offset + j] ^= prev[j];
+                }
+                let mut block = GenericArray::clone_from_slice(&data[offset..offset + 16]);
+                cipher.encrypt_block(&mut block);
+                data[offset..offset + 16].copy_from_slice(&block);
+                prev.copy_from_slice(&data[offset..offset + 16]);
+            }
+        }
+
+        aes_cbc_encrypt(&key, &mut data);
+        assert_ne!(data, original); // should be different after encrypt
+
+        super::aes_cbc_decrypt(&key, &mut data);
+        assert_eq!(data, original); // should match after roundtrip
+    }
+
+    #[test]
+    fn test_decrypt_unit_synthetic() {
+        // Build a fake 6144-byte aligned unit with known TS sync pattern,
+        // encrypt it with the AACS algorithm, then decrypt and verify.
+        let unit_key = [0xAAu8; 16];
+
+        // Build plaintext unit with TS sync bytes every 192 bytes starting at offset 4
+        let mut plain = vec![0u8; ALIGNED_UNIT_LEN];
+        let mut offset = 4;
+        while offset < ALIGNED_UNIT_LEN {
+            plain[offset] = TS_SYNC;
+            offset += TS_PACKET_LEN;
+        }
+        // Set encryption flag
+        plain[0] |= 0xC0;
+
+        // Now encrypt bytes 16..6143 using the AACS algorithm (reverse of decrypt)
+        let header: [u8; 16] = plain[..16].try_into().unwrap();
+        let derived = aes_ecb_encrypt(&unit_key, &header);
+        let mut encrypt_key = [0u8; 16];
+        for i in 0..16 {
+            encrypt_key[i] = derived[i] ^ header[i];
+        }
+
+        // CBC encrypt bytes 16..6143
+        let cipher = Aes128::new(GenericArray::from_slice(&encrypt_key));
+        let mut prev = AACS_IV;
+        let num_blocks = (ALIGNED_UNIT_LEN - 16) / 16;
+        for i in 0..num_blocks {
+            let off = 16 + i * 16;
+            for j in 0..16 {
+                plain[off + j] ^= prev[j];
+            }
+            let mut block = GenericArray::clone_from_slice(&plain[off..off + 16]);
+            cipher.encrypt_block(&mut block);
+            plain[off..off + 16].copy_from_slice(&block);
+            prev.copy_from_slice(&plain[off..off + 16]);
+        }
+
+        // Now plain contains encrypted data. Decrypt it.
+        let mut unit = plain;
+        assert!(is_unit_encrypted(&unit));
+        assert!(decrypt_unit(&mut unit, &unit_key));
+        assert!(!is_unit_encrypted(&unit)); // flag should be cleared
+
+        // Verify TS sync bytes
+        let mut count = 0;
+        let mut off = 4;
+        while off < ALIGNED_UNIT_LEN {
+            if unit[off] == TS_SYNC {
+                count += 1;
+            }
+            off += TS_PACKET_LEN;
+        }
+        assert_eq!(count, (ALIGNED_UNIT_LEN - 4) / TS_PACKET_LEN + 1);
+    }
+}

src/aacs/host_certs.rs

@@ -1,22 +0,0 @@
-//! Host-certificate collection — the one libfreemkv-side concern left from the
-//! old in-tree AACS handshake. The cert mutual-auth itself now lives in the
-//! `freemkv-unlock` AACS unlocker; libfreemkv only gathers the certs (a
-//! keysource concern) and hands them across the seam.
-
-/// Union the host certificates a scan can offer the drive: the explicit
-/// `DriveCredentials`, then each key source's `host_certs(mkb)`. Host certs are
-/// keysource-served, never compiled in. `mkb` lets a source pick a
-/// generation-appropriate cert (the default impl ignores it).
-pub fn collect_host_certs(
-    opts: &crate::disc::ScanOptions,
-    mkb: Option<u32>,
-) -> Vec<crate::aacs::types::HostCert> {
-    let mut host_certs: Vec<crate::aacs::types::HostCert> = Vec::new();
-    if let Some(c) = &opts.credentials {
-        host_certs.extend(c.host_certs.iter().cloned());
-    }
-    for src in &opts.key_sources {
-        host_certs.extend(src.host_certs(mkb));
-    }
-    host_certs
-}

src/aacs/index_select.rs

@@ -1,198 +0,0 @@
-//! FMTS index selection — the pure decode-time decision for a 2.1 disc.
-//!
-//! A 2.1 disc resolves to exactly one forensic index (1..=32) for a given
-//! rip. `IndividualSegment.tbl` tags each forensic segment with an index (see
-//! [`super::segment`]); the decode keeps the segments matching our index,
-//! drops the other 31, and treats everything outside a segment as ordinary
-//! (index-0) content. This module owns that classification and nothing else —
-//! no I/O, no keys, no cipher — so it is fully testable in isolation. The
-//! decrypt pipeline consumes the [`UnitDisposition`] it returns.
-//!
-//! Where the resolved index comes from is a separate concern
-//! ([`resolve_disc_index`]): today it is read off the index keys the key
-//! source handed us; when Processing Keys are available it will come from the
-//! VK derivation instead. Either way the disposition logic below is identical.
-
-use super::segment::{Segment, segment_for_unit};
-use super::types::UnitKey;
-
-/// What the decode should do with one AACS aligned unit.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum UnitDisposition {
-    /// Outside every forensic segment: ordinary content, decrypt with the
-    /// default (index-0) unit key.
-    Default,
-    /// Inside a forensic segment tagged with OUR resolved index: decrypt with
-    /// that index's key.
-    Index(u8),
-    /// Inside a forensic segment tagged with a DIFFERENT index: not our
-    /// watermark, so it is not part of our output — drop it.
-    DropForeignIndex(u8),
-    /// Inside a forensic segment but no index key is held (the disc's index
-    /// was never resolved): the segment cannot be decoded, so it is concealed
-    /// as loss. Carries the segment's index for diagnostics.
-    ForensicNoKey(u8),
-}
-
-/// Resolve the disc's single forensic index from the keys we hold.
-///
-/// Scans for an index key (`index_number` in `1..=32`) and returns its
-/// index. `None` when only default (index-0) keys are held — i.e. no
-/// index source answered, so forensic segments are not decodable. A disc has
-/// exactly one index, so the first non-zero key decides; if several distinct
-/// index keys were somehow supplied the lowest wins (deterministic), which is
-/// only a defensive tiebreak — the probe/derivation yields one.
-pub fn resolve_disc_index(unit_keys: &[UnitKey]) -> Option<u8> {
-    unit_keys
-        .iter()
-        .map(|k| k.index_number)
-        .filter(|&v| v != 0)
-        .min()
-}
-
-/// Classify the AACS aligned unit at `unit_offset` (clip-relative bytes) given
-/// the forensic segment map and the disc's resolved index (`None` if no
-/// index key is held).
-pub fn unit_disposition(
-    unit_offset: u64,
-    segments: &[Segment],
-    disc_index: Option<u8>,
-) -> UnitDisposition {
-    match segment_for_unit(segments, unit_offset) {
-        // Not in any forensic segment → ordinary content.
-        None => UnitDisposition::Default,
-        // In a forensic segment → decide by whether it is our index.
-        Some(seg) => {
-            // `seg.index` is an untrusted u16 from IndividualSegment.tbl; a real
-            // forensic index is 1..=32. Compare in u16 space so a corrupt/crafted
-            // index above 255 can't truncate into a valid u8 and alias our index.
-            // The disposition carries a u8 for diagnostics (saturated — an
-            // out-of-range index is never ours anyway).
-            let seg_index = seg.index;
-            let diag = seg_index.min(u8::MAX as u16) as u8;
-            match disc_index {
-                Some(v) if u16::from(v) == seg_index => UnitDisposition::Index(v),
-                Some(_) => UnitDisposition::DropForeignIndex(diag),
-                None => UnitDisposition::ForensicNoKey(diag),
-            }
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::aacs::content::ALIGNED_UNIT_LEN;
-    use crate::aacs::segment::{SOURCE_PACKET_LEN, parse_individual_segments};
-
-    /// Build a one-record segment table (index, start_spn, end_spn).
-    fn tbl(recs: &[(u16, u32, u32)]) -> Vec<Segment> {
-        let mut v = Vec::new();
-        v.extend_from_slice(&0x0100_0000u32.to_be_bytes());
-        v.extend_from_slice(&(recs.len() as u16).to_be_bytes());
-        v.extend_from_slice(&16u16.to_be_bytes());
-        for &(n, s, e) in recs {
-            v.extend_from_slice(&0x0100_0000u32.to_be_bytes());
-            v.extend_from_slice(&n.to_be_bytes());
-            v.extend_from_slice(&1u16.to_be_bytes());
-            v.extend_from_slice(&s.to_be_bytes());
-            v.extend_from_slice(&e.to_be_bytes());
-        }
-        parse_individual_segments(&v).expect("parse")
-    }
-
-    fn uk(idx: u32, index: u8) -> UnitKey {
-        if index == 0 {
-            UnitKey::new(idx, [0u8; 16])
-        } else {
-            UnitKey::forensic(idx, [index; 16], index)
-        }
-    }
-
-    #[test]
-    fn resolve_picks_the_single_index_key() {
-        // Default keys only → no index resolved.
-        assert_eq!(resolve_disc_index(&[uk(0, 0)]), None);
-        assert_eq!(resolve_disc_index(&[]), None);
-        // One index key among defaults → that index.
-        assert_eq!(resolve_disc_index(&[uk(0, 0), uk(1, 7)]), Some(7));
-        // Defensive: lowest of several distinct indexes (deterministic).
-        assert_eq!(resolve_disc_index(&[uk(0, 9), uk(1, 3)]), Some(3));
-    }
-
-    #[test]
-    fn unit_outside_segments_is_default() {
-        let segs = tbl(&[(1, 343680, 346239)]);
-        let off = 1000u64 * SOURCE_PACKET_LEN; // well before the segment
-        assert_eq!(
-            unit_disposition(off, &segs, Some(1)),
-            UnitDisposition::Default
-        );
-        // With no segments at all (1.0 / 2.0), everything is Default.
-        assert_eq!(
-            unit_disposition(off, &[], Some(1)),
-            UnitDisposition::Default
-        );
-    }
-
-    #[test]
-    fn unit_in_our_index_decrypts() {
-        let segs = tbl(&[(7, 100, 200)]);
-        let off = 120u64 * SOURCE_PACKET_LEN;
-        assert_eq!(
-            unit_disposition(off, &segs, Some(7)),
-            UnitDisposition::Index(7)
-        );
-    }
-
-    #[test]
-    fn unit_in_foreign_index_drops() {
-        // Segment tagged index 7, but our disc index is 3 → drop it.
-        let segs = tbl(&[(7, 100, 200)]);
-        let off = 120u64 * SOURCE_PACKET_LEN;
-        assert_eq!(
-            unit_disposition(off, &segs, Some(3)),
-            UnitDisposition::DropForeignIndex(7)
-        );
-    }
-
-    #[test]
-    fn forensic_unit_with_no_key_is_concealed() {
-        // A forensic segment but we never resolved an index → conceal as loss.
-        let segs = tbl(&[(7, 100, 200)]);
-        let off = 120u64 * SOURCE_PACKET_LEN;
-        assert_eq!(
-            unit_disposition(off, &segs, None),
-            UnitDisposition::ForensicNoKey(7)
-        );
-    }
-
-    #[test]
-    fn out_of_range_index_does_not_truncate_into_ours() {
-        // A crafted/corrupt segment index of 288 (0x0120) truncates to 32 in a
-        // u8. With our disc index resolved as 32, the old `seg.index as u8`
-        // compare would alias it to OUR index and decrypt with the wrong key.
-        // The u16 compare must instead classify it as foreign.
-        let segs = tbl(&[(288, 100, 200)]);
-        let off = 120u64 * SOURCE_PACKET_LEN;
-        assert_eq!(
-            unit_disposition(off, &segs, Some(32)),
-            UnitDisposition::DropForeignIndex(255)
-        );
-    }
-
-    #[test]
-    fn straddling_unit_still_classified_as_its_segment() {
-        // A unit whose 32-packet span only tails into the segment still routes
-        // to the segment (matches segment_for_unit's span test).
-        let segs = tbl(&[(5, 100, 200)]);
-        let unit_packets = (ALIGNED_UNIT_LEN as u64 / SOURCE_PACKET_LEN) as u32; // 32
-        // Start so the unit covers [80, 80+31] = [80, 111]: overlaps at 100.
-        let off = 80u64 * SOURCE_PACKET_LEN;
-        assert!(80 + unit_packets > 100, "sanity: unit tails into seg");
-        assert_eq!(
-            unit_disposition(off, &segs, Some(5)),
-            UnitDisposition::Index(5)
-        );
-    }
-}

src/aacs/inf.rs

@@ -1,881 +0,0 @@
-//! AACS on-disc key-input files: `Unit_Key_RO.inf` parsing, the disc-hash
-//! keydb lookup key, the Content Certificate, and the in-drive MKB read.
-//! These turn raw disc files into the structures the key paths consume.
-
-use super::mkb::*;
-
-/// Parsed Unit_Key_RO.inf file.
-pub struct UnitKeyFile {
-    /// Disc hash (SHA1 of the entire file) — used as KEYDB lookup key
-    pub disc_hash: [u8; 20],
-    /// Application type (1 = BD-ROM)
-    pub app_type: u8,
-    /// Number of BDMV directories
-    pub num_bdmv_dir: u8,
-    /// Whether SKB MKB is used
-    pub use_skb_mkb: bool,
-    /// AACS generation this file's stride matches
-    pub version: AacsVersion,
-    /// Encrypted unit keys (CPS unit number, encrypted key)
-    pub encrypted_keys: Vec<(u32, [u8; 16])>,
-    /// Title → CPS unit index mapping (title_idx → unit_key_idx)
-    pub title_cps_unit: Vec<u16>,
-}
-
-/// Redacting `Debug`, per the policy `aacs::types` documents: this struct holds
-/// the disc's ENCRYPTED CPS unit keys — exactly the material a keydb entry stores
-/// — plus the disc hash they are looked up by. A derived `Debug` printed every key
-/// byte verbatim, so any `{:?}` (a downstream crate, an `assert_eq!` failure
-/// message, a future `tracing::debug!` in this module) leaked them. Only
-/// non-secret shape is printed. Guarded by `unit_key_file_debug_is_redacted`.
-impl std::fmt::Debug for UnitKeyFile {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("UnitKeyFile")
-            // The disc hash is the public keydb lookup key, printed as hex the
-            // same way `DiscEntry` prints its own — never as raw bytes.
-            .field("disc_hash", &disc_hash_hex(&self.disc_hash))
-            .field("app_type", &self.app_type)
-            .field("num_bdmv_dir", &self.num_bdmv_dir)
-            .field("use_skb_mkb", &self.use_skb_mkb)
-            .field("version", &self.version)
-            .field("encrypted_keys", &"<redacted>")
-            .field("encrypted_keys_len", &self.encrypted_keys.len())
-            .field("title_cps_unit", &self.title_cps_unit)
-            .finish()
-    }
-}
-
-/// Compute disc hash (SHA1 of Unit_Key_RO.inf content).
-pub fn disc_hash(data: &[u8]) -> [u8; 20] {
-    use sha1::{Digest, Sha1};
-    let hash = Sha1::digest(data);
-    let mut out = [0u8; 20];
-    out.copy_from_slice(&hash);
-    out
-}
-
-/// Format disc hash as hex string with 0x prefix (for KEYDB lookup).
-pub fn disc_hash_hex(hash: &[u8; 20]) -> String {
-    let mut s = String::with_capacity(42);
-    s.push_str("0x");
-    for b in hash {
-        s.push_str(&format!("{b:02X}"));
-    }
-    s
-}
-
-/// Parse Unit_Key_RO.inf from raw bytes.
-///
-/// Format (from AACS spec):
-///   [0..4]   BE32: offset to key storage area (uk_pos)
-///   [16]     app_type (1 = BD-ROM)
-///   [17]     num_bdmv_dir
-///   [18]     bit 7: use_skb_mkb
-///   [20..22] BE16: first_play CPS unit
-///   [22..24] BE16: top_menu CPS unit
-///   [24..26] BE16: num_titles
-///   [26..]   title entries: 2 bytes padding + 2 bytes CPS unit, × num_titles
-///
-///   Key storage at uk_pos:
-///   [uk_pos..uk_pos+2]   BE16: num_unit_keys
-///   [uk_pos+48..]        encrypted keys, 16 bytes each
-///                         AACS 1.0: 48-byte stride
-///                         AACS 2.0 / 2.1: 64-byte stride (48 + 16 extra)
-pub fn parse_unit_key_ro(data: &[u8], version: AacsVersion) -> Option<UnitKeyFile> {
-    if data.len() < 20 {
-        return None;
-    }
-
-    let hash = disc_hash(data);
-
-    // Header
-    let app_type = data[16];
-    let num_bdmv_dir = data[17];
-    let use_skb_mkb = (data[18] >> 7) & 1 == 1;
-
-    // Key storage offset
-    let uk_pos = u32::from_be_bytes([data[0], data[1], data[2], data[3]]) as usize;
-    if uk_pos + 2 > data.len() {
-        return None;
-    }
-
-    // Number of unit keys
-    let num_uk = u16::from_be_bytes([data[uk_pos], data[uk_pos + 1]]) as usize;
-    if num_uk == 0 {
-        return Some(UnitKeyFile {
-            disc_hash: hash,
-            app_type,
-            num_bdmv_dir,
-            use_skb_mkb,
-            version,
-            encrypted_keys: Vec::new(),
-            title_cps_unit: Vec::new(),
-        });
-    }
-
-    // Stride between keys
-    let stride = version.unit_key_stride();
-
-    // Validate size
-    let keys_start = uk_pos + 48; // first key at uk_pos + 48
-    if keys_start + 16 > data.len() {
-        return None;
-    }
-
-    // Extract encrypted keys
-    let mut encrypted_keys = Vec::with_capacity(num_uk);
-    let mut pos = keys_start;
-    for i in 0..num_uk {
-        if pos + 16 > data.len() {
-            break;
-        }
-        let mut key = [0u8; 16];
-        key.copy_from_slice(&data[pos..pos + 16]);
-        encrypted_keys.push(((i + 1) as u32, key));
-        pos += stride;
-    }
-
-    // The loop above `break`s if the buffer runs out mid-key. A short list
-    // means the .inf is malformed/truncated — reject it rather than silently
-    // accepting fewer keys than the header declared, which would later map
-    // title CPS units to nonexistent keys.
-    if encrypted_keys.len() != num_uk {
-        return None;
-    }
-
-    // Title → CPS unit mapping (AACS Unit_Key_RO format): each on-disc CPS
-    // value is in `1..=num_uk` (else zeroes it) and converts the 1-based on-disc
-    // index to a 0-based key index. We mirror that so the stored value is a safe,
-    // ready-to-use key index rather than a raw 1-based number.
-    let to_key_idx = |cps: u16| -> u16 {
-        if cps >= 1 && cps as usize <= num_uk {
-            cps - 1
-        } else {
-            0
-        }
-    };
-    let mut title_cps_unit = Vec::new();
-    if data.len() >= 26 {
-        let first_play = u16::from_be_bytes([data[20], data[21]]);
-        let top_menu = u16::from_be_bytes([data[22], data[23]]);
-        let num_titles = u16::from_be_bytes([data[24], data[25]]) as usize;
-
-        title_cps_unit.push(to_key_idx(first_play));
-        title_cps_unit.push(to_key_idx(top_menu));
-
-        for i in 0..num_titles {
-            let off = 26 + i * 4 + 2; // 2 bytes padding + 2 bytes CPS unit
-            if off + 2 <= data.len() {
-                let cps = u16::from_be_bytes([data[off], data[off + 1]]);
-                title_cps_unit.push(to_key_idx(cps));
-            }
-        }
-    }
-
-    Some(UnitKeyFile {
-        disc_hash: hash,
-        app_type,
-        num_bdmv_dir,
-        use_skb_mkb,
-        version,
-        encrypted_keys,
-        title_cps_unit,
-    })
-}
-
-/// HD DVD Video Title Key File (`VTKF%%%.AACS`) magic — "DVD_HD_V_TKF".
-pub const VTKF_MAGIC: &[u8; 12] = b"DVD_HD_V_TKF";
-/// Fixed header length before the first Title Key Entry (AACS HD DVD Book,
-/// Table 3-8).
-const VTKF_HEADER_LEN: usize = 0x80;
-/// Title Key Entry stride (Table 3-8): 1-byte `BIFO` + 3 reserved + 16-byte
-/// encrypted title key + 16-byte binding MAC = 36 bytes.
-const VTKF_ENTRY_LEN: usize = 0x24;
-/// Byte offset of the encrypted title key within an entry (after `BIFO` + 3
-/// reserved).
-const VTKF_KEY_OFF: usize = 4;
-/// Number of Title Key Entry slots in a VTKF (Table 3-8): a fixed 64.
-const VTKF_MAX_ENTRIES: usize = 64;
-/// `BIFO` bit 7 (`AV_FLG`): set = this slot carries an available title key.
-const VTKF_AV_FLG: u8 = 0x80;
-
-/// Parse an HD DVD `VTKF%%%.AACS` into the SAME [`UnitKeyFile`] a BD/UHD
-/// `Unit_Key_RO.inf` yields — so the shared AACS crypto (`derive_unit_keys` →
-/// `decrypt_unit_key(vuk, …)`) unwraps HD DVD title keys with no change. Only
-/// the on-disc CONTAINER differs between BD and HD DVD; the title-key unwrap is
-/// the identical AES-128 VUK step (`Kt = AES-128D(Kvu, Kte)`).
-///
-/// Layout — AACS "HD DVD and DVD Pre-recorded Book" Table 3-8, a fixed
-/// 2480-byte file, verified byte-exact against real discs (Freedom `VTKF090`,
-/// Dukes of Hazzard `VTKF000`):
-/// ```text
-///   [0x00..0x0C] magic "DVD_HD_V_TKF"
-///   [0x0C..0x10] BE32 HD_VTKF_SIZE (2480)
-///   [0x10..0x1C] associated playlist name ("VPLST%%%.XPL")
-///   [0x1C..0x80] reserved
-///   [0x80..]     64 entries × 36 bytes:
-///                  BIFO (1) | reserved (3) | ENCRYPTED title key (16) | binding MAC (16)
-///                  BIFO bit 7 (AV_FLG) set = this slot holds a title key
-///                  (pre-recorded discs fill the binding MAC with 0xFF)
-///   [0x9A0..2480] 16-byte TKF MAC (CMAC keyed by Kvu — NOT a key)
-/// ```
-/// The slot index (1-based) is the CPS unit number, so an absent slot is
-/// SKIPPED (not a terminator) — collapsing gaps would renumber later keys and
-/// hand the wrong title key to CPS unit N+1. The title→CPS mapping is
-/// playlist-driven (`VPLST%%%.XPL`) and owned by the HD DVD enumerator, so
-/// `title_cps_unit` is left empty here.
-///
-/// The prior parser used a 32-byte stride (a 12-byte pad instead of the 16-byte
-/// binding MAC). That reads entry #1 correctly but drifts +4 bytes per entry
-/// after it, so it only decrypted single-CPS-unit discs; every multi-key VTKF
-/// (Freedom, Harry Potter) yielded garbage keys for CPS unit ≥2.
-pub fn parse_vtkf(data: &[u8]) -> Option<UnitKeyFile> {
-    if data.len() < VTKF_HEADER_LEN || &data[..12] != VTKF_MAGIC {
-        return None;
-    }
-    // SHA1 of the WHOLE file — the KEYDB lookup key. BackupHDDVD-family key
-    // databases index an HD DVD disc by SHA1(VTKF000.AACS), the same role the
-    // BD disc_hash plays for `Unit_Key_RO.inf`.
-    let hash = disc_hash(data);
-
-    let mut encrypted_keys = Vec::new();
-    for n in 0..VTKF_MAX_ENTRIES {
-        let pos = VTKF_HEADER_LEN + n * VTKF_ENTRY_LEN;
-        if pos + VTKF_ENTRY_LEN > data.len() {
-            break;
-        }
-        // AV_FLG clear = empty slot: skip it, but keep the slot index as the CPS
-        // number (do NOT break — a gap must not renumber the keys that follow).
-        if data[pos] & VTKF_AV_FLG == 0 {
-            continue;
-        }
-        let mut key = [0u8; 16];
-        key.copy_from_slice(&data[pos + VTKF_KEY_OFF..pos + VTKF_KEY_OFF + 16]);
-        encrypted_keys.push((n as u32 + 1, key));
-    }
-    if encrypted_keys.is_empty() {
-        return None;
-    }
-
-    Some(UnitKeyFile {
-        disc_hash: hash,
-        app_type: 0,     // HD DVD VTKF carries no BD-ROM app_type
-        num_bdmv_dir: 0, // BD-only concept
-        use_skb_mkb: false,
-        version: AacsVersion::V10, // HD DVD is always AACS 1.0
-        encrypted_keys,
-        title_cps_unit: Vec::new(),
-    })
-}
-
-/// Parse a disc's title-key file, dispatching on the self-describing magic:
-/// an HD DVD `VTKF000.AACS` (`DVD_HD_V_TKF`) → [`parse_vtkf`]; anything else is a
-/// BD/UHD `Unit_Key_RO.inf` → [`parse_unit_key_ro`]. Both return the same
-/// [`UnitKeyFile`], so every downstream AACS derivation stays container-agnostic
-/// — the single seam where BD-vs-HD-DVD key layout is resolved (mirrors the key
-/// service, which classifies HD DVD by the very same magic).
-pub fn parse_title_keys(data: &[u8], version: AacsVersion) -> Option<UnitKeyFile> {
-    if data.len() >= 12 && &data[..12] == VTKF_MAGIC {
-        parse_vtkf(data)
-    } else {
-        parse_unit_key_ro(data, version)
-    }
-}
-
-/// MKB disc structure format code.
-const MKB_DISC_STRUCTURE_FORMAT: u8 = 0x83;
-
-/// MKB pack buffer size.
-const MKB_PACK_SIZE: usize = 32772;
-
-/// Read MKB from drive via SCSI (REPORT DISC STRUCTURE format 0x83).
-/// Returns the concatenated MKB data from all packs.
-pub fn read_mkb_from_drive(
-    session: &mut dyn crate::scsi::ScsiTransport,
-) -> crate::error::Result<Vec<u8>> {
-    use crate::scsi::{DataDirection, SCSI_READ_DISC_STRUCTURE};
-
-    let cdb = [
-        SCSI_READ_DISC_STRUCTURE,
-        0x01,
-        0x00,
-        0x00,
-        0x00,
-        0x00,
-        0x00,
-        MKB_DISC_STRUCTURE_FORMAT,
-        (MKB_PACK_SIZE >> 8) as u8,
-        (MKB_PACK_SIZE & 0xFF) as u8,
-        0x00,
-        0x00,
-    ];
-    let mut buf = vec![0u8; 32772];
-    session.execute(&cdb, DataDirection::FromDevice, &mut buf, 10_000)?;
-
-    let data_len = u16::from_be_bytes([buf[0], buf[1]]) as usize;
-    if data_len < 2 {
-        return Ok(Vec::new());
-    }
-    let len = data_len - 2;
-    let num_packs = buf[3] as usize;
-
-    let mut mkb = Vec::with_capacity(32768 * num_packs.max(1));
-    if len > 0 && len <= 32768 {
-        mkb.extend_from_slice(&buf[4..4 + len]);
-    }
-
-    // Read remaining packs
-    for pack in 1..num_packs {
-        let mut cdb = [
-            SCSI_READ_DISC_STRUCTURE,
-            0x01,
-            0x00,
-            0x00,
-            0x00,
-            0x00,
-            0x00,
-            MKB_DISC_STRUCTURE_FORMAT,
-            (MKB_PACK_SIZE >> 8) as u8,
-            (MKB_PACK_SIZE & 0xFF) as u8,
-            0x00,
-            0x00,
-        ];
-        // Pack number goes in address field
-        cdb[2] = ((pack >> 24) & 0xFF) as u8;
-        cdb[3] = ((pack >> 16) & 0xFF) as u8;
-        cdb[4] = ((pack >> 8) & 0xFF) as u8;
-        cdb[5] = (pack & 0xFF) as u8;
-
-        let mut buf = vec![0u8; 32772];
-        if session
-            .execute(&cdb, DataDirection::FromDevice, &mut buf, 10_000)
-            .is_ok()
-        {
-            let len = u16::from_be_bytes([buf[0], buf[1]]) as usize;
-            if len > 2 && len - 2 <= 32768 {
-                mkb.extend_from_slice(&buf[4..4 + len - 2]);
-            }
-        }
-    }
-
-    Ok(mkb)
-}
-
-/// AACS Content Certificate — identifies disc AACS version and features.
-#[derive(Debug)]
-pub struct ContentCert {
-    /// Bus encryption enabled flag
-    pub bus_encryption: bool,
-    /// Content Certificate ID (6 bytes)
-    pub cc_id: [u8; 6],
-    /// AACS generation indicated by the certificate type byte.
-    ///
-    /// Cert type `0x00` → [`AacsVersion::V10`]; any other value →
-    /// [`AacsVersion::V20`]. The certificate alone cannot distinguish
-    /// V20 from V21 — Variant detection happens after the MKB walk.
-    pub version: AacsVersion,
-}
-
-/// Parse a Content Certificate (ContentXXX.cer) file.
-pub fn parse_content_cert(data: &[u8]) -> Option<ContentCert> {
-    if data.len() < 20 {
-        return None;
-    }
-
-    // Content Certificate layout (per the AACS content-cert format):
-    //   [0]      certificate type (0x00 = AACS1, 0x10 = AACS2)
-    //   [1] bit7 bus_encryption_enabled_flag  (`p[1] >> 7`)
-    //   [14..20] cc_id (6 bytes)             (`p + 14`)
-    let version = if data[0] == 0x00 {
-        AacsVersion::V10
-    } else {
-        AacsVersion::V20
-    };
-    // The flag is bit 7 of byte 1, NOT bit 0. Reading bit 0 (the prior bug) made
-    // a bus-encrypted cert (byte1=0x80) read as `false`, defeating the
-    // AacsBusKeyUnavailable fail-loud gate in disc/encrypt.rs.
-    let bus_encryption = (data[1] >> 7) & 1 == 1;
-    let mut cc_id = [0u8; 6];
-    cc_id.copy_from_slice(&data[14..20]);
-
-    Some(ContentCert {
-        bus_encryption,
-        cc_id,
-        version,
-    })
-}
-
-#[cfg(test)]
-mod vtkf_tests {
-    use super::*;
-
-    /// Build a synthetic `VTKF%%%.AACS` matching the real on-disc layout (AACS
-    /// HD DVD Book Table 3-8, verified against Freedom `VTKF090` and Dukes
-    /// `VTKF000`): magic, BE32 size, playlist name, reserved to 0x80, then 64
-    /// entry slots of 36 bytes (the first `keys.len()` present with `AV_FLG`
-    /// set, the rest empty), a reserved gap, and the 16-byte trailing TKF MAC.
-    fn synth_vtkf(keys: &[[u8; 16]]) -> Vec<u8> {
-        const FILE_LEN: usize = 2480;
-        let mut v = Vec::new();
-        v.extend_from_slice(VTKF_MAGIC); // 0x00
-        v.extend_from_slice(&(FILE_LEN as u32).to_be_bytes()); // 0x0C HD_VTKF_SIZE
-        v.extend_from_slice(b"VPLST000.XPL"); // 0x10 playlist name
-        v.resize(VTKF_HEADER_LEN, 0); // reserve to first entry (0x80)
-        for n in 0..VTKF_MAX_ENTRIES {
-            if let Some(k) = keys.get(n) {
-                v.push(VTKF_AV_FLG); // BIFO: AV_FLG set (present)
-                v.extend_from_slice(&[0, 0, 0]); // reserved
-                v.extend_from_slice(k); // 16-byte encrypted title key
-                v.extend_from_slice(&[0xFFu8; 16]); // binding MAC (0xFF, pre-recorded)
-            } else {
-                v.extend_from_slice(&[0u8; VTKF_ENTRY_LEN]); // empty slot (AV_FLG clear)
-            }
-        }
-        v.resize(FILE_LEN - 16, 0); // reserved gap before the trailer
-        v.extend_from_slice(&[0xABu8; 16]); // TKF MAC (must NOT be read as a key)
-        v
-    }
-
-    #[test]
-    fn parse_vtkf_reads_present_entries_skips_empty_ignores_mac() {
-        let k1 = [0x11u8; 16];
-        let k2 = [0x22u8; 16];
-        let k3 = [0x33u8; 16];
-        let data = synth_vtkf(&[k1, k2, k3]);
-
-        let ukf = parse_vtkf(&data).expect("valid VTKF must parse");
-        // Exactly the three present entries — the empty slots and the trailing
-        // 16-byte TKF MAC are NOT mistaken for keys. Critically, k2/k3 are read
-        // at the 36-byte stride (offsets 0xA4, 0xC8); the old 32-byte stride
-        // misread them from inside the previous entry's binding MAC.
-        assert_eq!(ukf.encrypted_keys.len(), 3);
-        assert_eq!(
-            ukf.encrypted_keys[0],
-            (1, k1),
-            "CPS units = 1-based slot index"
-        );
-        assert_eq!(ukf.encrypted_keys[1], (2, k2));
-        assert_eq!(ukf.encrypted_keys[2], (3, k3));
-        assert_eq!(ukf.version, AacsVersion::V10, "HD DVD is AACS 1.0");
-        // disc_hash is SHA1 of the whole file (the KEYDB lookup key).
-        assert_eq!(ukf.disc_hash, disc_hash(&data));
-    }
-
-    #[test]
-    fn parse_vtkf_reads_a_full_64_entry_file() {
-        // Real discs (Freedom, Dukes) carry all 64 slots present. Every key must
-        // come back, none dropped and none drifted — the regression the 32-byte
-        // stride failed.
-        let keys: Vec<[u8; 16]> = (0..VTKF_MAX_ENTRIES).map(|n| [n as u8; 16]).collect();
-        let ukf = parse_vtkf(&synth_vtkf(&keys)).expect("64-entry VTKF");
-        assert_eq!(ukf.encrypted_keys.len(), 64);
-        assert_eq!(
-            ukf.encrypted_keys[63],
-            (64, [63u8; 16]),
-            "entry 64 at 0x{:x}",
-            VTKF_HEADER_LEN + 63 * VTKF_ENTRY_LEN
-        );
-    }
-
-    #[test]
-    fn parse_vtkf_rejects_non_magic() {
-        let mut data = synth_vtkf(&[[0x11u8; 16]]);
-        data[0] = b'X'; // corrupt magic
-        assert!(
-            parse_vtkf(&data).is_none(),
-            "non-VTKF magic must be rejected"
-        );
-        assert!(
-            parse_vtkf(&[0u8; 4]).is_none(),
-            "too short must be rejected"
-        );
-    }
-
-    #[test]
-    fn parse_title_keys_dispatches_by_magic() {
-        // VTKF magic → parse_vtkf.
-        let data = synth_vtkf(&[[0x44u8; 16], [0x55u8; 16]]);
-        let ukf = parse_title_keys(&data, AacsVersion::V10).expect("VTKF dispatch");
-        assert_eq!(ukf.encrypted_keys.len(), 2);
-
-        // Non-VTKF → parse_unit_key_ro (a 2-byte buffer is not a valid inf, so
-        // this proves it ROUTED to the BD parser rather than parse_vtkf).
-        assert!(
-            parse_title_keys(&[0x00, 0x00], AacsVersion::V10).is_none(),
-            "non-magic input must route to parse_unit_key_ro"
-        );
-    }
-
-    /// The whole point of the seam: a parsed VTKF feeds the SHARED VUK→title-key
-    /// crypto (`decrypt_unit_key`) exactly like a BD `Unit_Key_RO.inf` would —
-    /// no HD-DVD-specific crypto path.
-    #[test]
-    fn vtkf_encrypted_keys_feed_shared_vuk_unwrap() {
-        let enc = [0x9Au8; 16];
-        let data = synth_vtkf(&[enc]);
-        let ukf = parse_vtkf(&data).unwrap();
-        let vuk = [0x5Cu8; 16];
-        let derived = super::super::derive::decrypt_unit_key(&vuk, &ukf.encrypted_keys[0].1);
-        // Same as applying the shared unwrap directly to the stored enc key.
-        assert_eq!(derived, super::super::derive::decrypt_unit_key(&vuk, &enc));
-    }
-
-    /// `UnitKeyFile` holds the disc's ENCRYPTED CPS unit keys. A derived `Debug`
-    /// printed every byte; the hand-written impl must not. Sentinel key byte
-    /// 0xD5 = decimal 213 (a derived `Debug` renders `[u8; 16]` in decimal), the
-    /// same probe `aacs::types::redaction_tests` uses. Mutation guard: putting
-    /// `#[derive(Debug)]` back fails this.
-    #[test]
-    fn unit_key_file_debug_is_redacted() {
-        let f = UnitKeyFile {
-            disc_hash: [0xD5; 20],
-            app_type: 1,
-            num_bdmv_dir: 1,
-            use_skb_mkb: false,
-            version: AacsVersion::V20,
-            encrypted_keys: vec![(0, [0xD5; 16]), (1, [0xD5; 16])],
-            title_cps_unit: vec![0, 1],
-        };
-        let dbg = format!("{f:?}");
-        assert!(
-            !dbg.contains("213"),
-            "UnitKeyFile Debug leaked key bytes (decimal 213): {dbg}"
-        );
-        assert!(
-            dbg.contains("redacted"),
-            "UnitKeyFile Debug missing redaction marker: {dbg}"
-        );
-        // Non-secret shape is still useful for diagnostics.
-        assert!(dbg.contains("encrypted_keys_len: 2"), "{dbg}");
-    }
-}
-
-#[cfg(test)]
-mod read_mkb_tests {
-    use super::*;
-    use crate::scsi::{DataDirection, SCSI_READ_DISC_STRUCTURE, ScsiResult, ScsiTransport};
-
-    /// A drive that answers READ DISC STRUCTURE format 0x83 from a scripted set
-    /// of packs and records every CDB it was handed.
-    struct MkbDrive {
-        /// One entry per pack: the pack's MKB payload bytes.
-        packs: Vec<Vec<u8>>,
-        cdbs: Vec<Vec<u8>>,
-    }
-
-    impl ScsiTransport for MkbDrive {
-        fn execute(
-            &mut self,
-            cdb: &[u8],
-            _direction: DataDirection,
-            data: &mut [u8],
-            _timeout_ms: u32,
-        ) -> crate::error::Result<ScsiResult> {
-            self.cdbs.push(cdb.to_vec());
-            // Pack number is carried in the CDB address field (bytes 2..6),
-            // MMC-6 READ DISC STRUCTURE.
-            let pack = u32::from_be_bytes([cdb[2], cdb[3], cdb[4], cdb[5]]) as usize;
-            let body = self.packs.get(pack).cloned().unwrap_or_default();
-            // Header: BE16 data length (counts the 2 header bytes that follow
-            // it plus the payload), reserved byte, pack count, then payload.
-            let data_len = body.len() + 2;
-            data[0..2].copy_from_slice(&(data_len as u16).to_be_bytes());
-            data[2] = 0x00;
-            data[3] = self.packs.len() as u8;
-            data[4..4 + body.len()].copy_from_slice(&body);
-            Ok(ScsiResult {
-                status: 0,
-                bytes_transferred: 4 + body.len(),
-                sense: [0u8; 32],
-            })
-        }
-    }
-
-    /// `read_mkb_from_drive` is the in-drive MKB source: every AACS derivation
-    /// downstream (`mkb_find_mk_dv`, the subset-difference walk, the whole
-    /// Media Key ladder) consumes exactly what it returns. An empty return is
-    /// not a benign "no MKB" — it is a total read failure reported as success,
-    /// and every derivation then fails with a key-not-found code that points
-    /// the operator at their keydb rather than at the drive.
-    ///
-    /// This pins the CONTENT: the concatenated payload of all packs, in pack
-    /// order, byte for byte.
-    #[test]
-    fn read_mkb_from_drive_returns_the_concatenated_pack_payload() {
-        let pack0: Vec<u8> = (0..600u32).map(|i| (i % 251) as u8).collect();
-        let pack1: Vec<u8> = (0..300u32).map(|i| (i % 253) as u8 ^ 0xA5).collect();
-        let mut drive = MkbDrive {
-            packs: vec![pack0.clone(), pack1.clone()],
-            cdbs: Vec::new(),
-        };
-
-        let mkb = read_mkb_from_drive(&mut drive).expect("scripted drive answers");
-
-        let mut expected = pack0.clone();
-        expected.extend_from_slice(&pack1);
-        assert_eq!(
-            mkb.len(),
-            expected.len(),
-            "every pack's payload must be concatenated, none dropped"
-        );
-        assert!(
-            mkb == expected,
-            "MKB bytes must be the drive's payload in pack order; first \
-             mismatch at {:?}",
-            (0..expected.len()).find(|&i| mkb[i] != expected[i])
-        );
-
-        // MMC-6 READ DISC STRUCTURE with the AACS MKB format code, one command
-        // per pack, pack number in the address field.
-        assert_eq!(drive.cdbs.len(), 2, "one command per declared pack");
-        for (i, cdb) in drive.cdbs.iter().enumerate() {
-            assert_eq!(cdb[0], SCSI_READ_DISC_STRUCTURE, "opcode");
-            assert_eq!(cdb[7], 0x83, "AACS MKB disc-structure format code");
-            assert_eq!(
-                u32::from_be_bytes([cdb[2], cdb[3], cdb[4], cdb[5]]),
-                i as u32,
-                "pack {i} must be requested by number"
-            );
-        }
-    }
-
-    /// The CDB is what the drive actually acts on, and every byte of it is
-    /// load-bearing: a wrong format code returns a different disc structure
-    /// entirely, and a wrong allocation length truncates the pack. The existing
-    /// test above pins the opcode, the format code and the pack number; this
-    /// pins the WHOLE 12-byte CDB, so no field can drift unnoticed.
-    ///
-    /// Expected layout (MMC-6 READ DISC STRUCTURE, AACS MKB format):
-    ///   `[0]` opcode, `[1]` media type 0x01, `[2..6]` address = pack number
-    ///   (BE32), `[6]` layer 0, `[7]` format 0x83, `[8..10]` allocation length
-    ///   BE16 = 32772 = `0x80 0x04`, `[10..12]` reserved/control.
-    #[test]
-    fn read_mkb_from_drive_issues_the_exact_mmc_cdb_for_each_pack() {
-        let mut drive = MkbDrive {
-            packs: vec![vec![0x11u8; 64], vec![0x22u8; 64], vec![0x33u8; 64]],
-            cdbs: Vec::new(),
-        };
-        read_mkb_from_drive(&mut drive).expect("scripted drive answers");
-
-        assert_eq!(drive.cdbs.len(), 3, "one command per declared pack");
-        for (pack, cdb) in drive.cdbs.iter().enumerate() {
-            let p = pack as u32;
-            let expected: [u8; 12] = [
-                SCSI_READ_DISC_STRUCTURE,
-                0x01,
-                (p >> 24) as u8,
-                (p >> 16) as u8,
-                (p >> 8) as u8,
-                p as u8,
-                0x00,
-                0x83, // AACS MKB disc-structure format
-                0x80, // allocation length 32772 = 0x8004, high byte
-                0x04, // …low byte
-                0x00,
-                0x00,
-            ];
-            assert_eq!(
-                cdb.as_slice(),
-                &expected[..],
-                "CDB for pack {pack} must match the MMC-6 READ DISC STRUCTURE layout"
-            );
-        }
-    }
-
-    /// A pack payload filling the FULL 32768-byte window must come back whole.
-    /// The `len > 0 && len <= 32768` bound is what stands between a maximal
-    /// pack and a silently dropped one, and the small payloads used elsewhere
-    /// in this module never reach it.
-    #[test]
-    fn read_mkb_from_drive_accepts_a_full_size_pack() {
-        let full: Vec<u8> = (0..32768u32).map(|i| (i % 251) as u8).collect();
-        let other: Vec<u8> = (0..32768u32).map(|i| (i % 241) as u8 ^ 0x5A).collect();
-        // TWO maximal packs: the first-pack read and the per-pack loop carry
-        // separate bounds, so both must accept a full-window payload.
-        let mut drive = MkbDrive {
-            packs: vec![full.clone(), other.clone()],
-            cdbs: Vec::new(),
-        };
-        let mkb = read_mkb_from_drive(&mut drive).expect("scripted drive answers");
-        assert_eq!(
-            mkb.len(),
-            65536,
-            "neither maximal pack may be dropped at the size bound"
-        );
-        let mut expected = full.clone();
-        expected.extend_from_slice(&other);
-        assert!(mkb == expected, "both maximal packs' bytes must be intact");
-    }
-
-    /// A pack that declares only the 2-byte header and NO payload contributes
-    /// nothing, and must not push a phantom byte into the MKB — an off-by-one
-    /// at the zero-length boundary corrupts every following pack's alignment.
-    #[test]
-    fn read_mkb_from_drive_zero_length_pack_contributes_nothing() {
-        let mut drive = MkbDrive {
-            packs: vec![Vec::new(), vec![0xABu8; 32]],
-            cdbs: Vec::new(),
-        };
-        let mkb = read_mkb_from_drive(&mut drive).expect("scripted drive answers");
-        assert_eq!(
-            mkb.len(),
-            32,
-            "an empty pack adds no bytes; only pack 1's payload is present"
-        );
-        assert!(mkb == vec![0xABu8; 32], "and the bytes are pack 1's");
-    }
-
-    /// A drive that DECLARES more payload than it returned must not be
-    /// believed. The BE16 length in the response header is drive-supplied data:
-    /// a firmware bug, a short transfer, or a hostile device can put a value in
-    /// it that runs past the 32772-byte buffer. Copying `len` bytes on that word
-    /// alone panics the rip thread mid-scan.
-    ///
-    /// Both the first-pack read and the per-pack loop carry the same bound, so
-    /// both are exercised here: the over-declared pack contributes nothing and
-    /// the honest pack still comes through.
-    #[test]
-    fn read_mkb_from_drive_ignores_a_pack_declaring_more_than_the_buffer_holds() {
-        /// Pack 0 is honest; pack 1 declares a 60000-byte payload it never sent.
-        struct LyingDrive {
-            honest: Vec<u8>,
-        }
-        impl ScsiTransport for LyingDrive {
-            fn execute(
-                &mut self,
-                cdb: &[u8],
-                _direction: DataDirection,
-                data: &mut [u8],
-                _timeout_ms: u32,
-            ) -> crate::error::Result<ScsiResult> {
-                let pack = u32::from_be_bytes([cdb[2], cdb[3], cdb[4], cdb[5]]);
-                data[3] = 2; // two packs declared
-                if pack == 0 {
-                    let dl = self.honest.len() + 2;
-                    data[0..2].copy_from_slice(&(dl as u16).to_be_bytes());
-                    data[4..4 + self.honest.len()].copy_from_slice(&self.honest);
-                } else {
-                    // A length far beyond the 32772-byte response buffer.
-                    data[0..2].copy_from_slice(&60_000u16.to_be_bytes());
-                }
-                Ok(ScsiResult {
-                    status: 0,
-                    bytes_transferred: 4,
-                    sense: [0u8; 32],
-                })
-            }
-        }
-
-        let honest = vec![0xC7u8; 256];
-        let mut drive = LyingDrive {
-            honest: honest.clone(),
-        };
-        let mkb = read_mkb_from_drive(&mut drive).expect("an over-declared pack is not an error");
-        assert_eq!(
-            mkb.len(),
-            honest.len(),
-            "only the honest pack's bytes may be taken; the over-declared pack \
-             contributes nothing and must not be read past the buffer"
-        );
-        assert!(mkb == honest, "and those bytes are pack 0's");
-    }
-
-    /// The same over-declaration on the FIRST pack, which uses a separate bound
-    /// from the loop's.
-    #[test]
-    fn read_mkb_from_drive_ignores_a_first_pack_declaring_more_than_the_buffer() {
-        struct LyingFirst;
-        impl ScsiTransport for LyingFirst {
-            fn execute(
-                &mut self,
-                _cdb: &[u8],
-                _direction: DataDirection,
-                data: &mut [u8],
-                _timeout_ms: u32,
-            ) -> crate::error::Result<ScsiResult> {
-                data[0..2].copy_from_slice(&60_000u16.to_be_bytes());
-                data[3] = 1;
-                Ok(ScsiResult {
-                    status: 0,
-                    bytes_transferred: 4,
-                    sense: [0u8; 32],
-                })
-            }
-        }
-        let mkb = read_mkb_from_drive(&mut LyingFirst).expect("not an error");
-        assert!(
-            mkb.is_empty(),
-            "a first pack declaring more than the buffer holds yields no bytes"
-        );
-    }
-
-    /// A single-pack disc still yields that pack's bytes — the common case, and
-    /// the one where a body returning an empty vector looks most plausible.
-    #[test]
-    fn read_mkb_from_drive_returns_a_single_packs_payload() {
-        let pack: Vec<u8> = (0..1024u32).map(|i| (i * 7 % 256) as u8).collect();
-        let mut drive = MkbDrive {
-            packs: vec![pack.clone()],
-            cdbs: Vec::new(),
-        };
-        let mkb = read_mkb_from_drive(&mut drive).expect("scripted drive answers");
-        assert_eq!(mkb.len(), pack.len(), "single pack payload length");
-        assert!(mkb == pack, "single pack payload bytes");
-    }
-
-    /// A drive that reports a header-only response (`data_len < 2`) has no MKB
-    /// to give. That must be an EMPTY vec, not a partial one — the distinction
-    /// matters because the AACS paths treat a non-empty MKB as parseable.
-    #[test]
-    fn read_mkb_from_drive_empty_response_is_empty() {
-        struct NoMkb;
-        impl ScsiTransport for NoMkb {
-            fn execute(
-                &mut self,
-                _cdb: &[u8],
-                _direction: DataDirection,
-                data: &mut [u8],
-                _timeout_ms: u32,
-            ) -> crate::error::Result<ScsiResult> {
-                data[0..2].copy_from_slice(&0u16.to_be_bytes());
-                Ok(ScsiResult {
-                    status: 0,
-                    bytes_transferred: 4,
-                    sense: [0u8; 32],
-                })
-            }
-        }
-        let mkb = read_mkb_from_drive(&mut NoMkb).expect("no-MKB drive still returns Ok");
-        assert!(
-            mkb.is_empty(),
-            "a header-only response carries no MKB bytes"
-        );
-    }
-
-    /// A transport failure on the FIRST pack must propagate as an error — the
-    /// MKB is the root of the whole AACS ladder, so an unreadable one cannot be
-    /// downgraded to "an MKB with no records".
-    #[test]
-    fn read_mkb_from_drive_propagates_the_first_pack_failure() {
-        struct DeadDrive;
-        impl ScsiTransport for DeadDrive {
-            fn execute(
-                &mut self,
-                _cdb: &[u8],
-                _direction: DataDirection,
-                _data: &mut [u8],
-                _timeout_ms: u32,
-            ) -> crate::error::Result<ScsiResult> {
-                Err(crate::error::Error::ScsiError {
-                    opcode: SCSI_READ_DISC_STRUCTURE,
-                    status: 0x02,
-                    sense: None,
-                })
-            }
-        }
-        assert!(
-            read_mkb_from_drive(&mut DeadDrive).is_err(),
-            "an unreadable MKB must surface as an error, not an empty MKB"
-        );
-    }
-}

src/aacs/keydb.rs

@@ -0,0 +1,436 @@
+//! AACS Key Database parsing — KEYDB.cfg format.
+
+use std::collections::HashMap;
+
+/// Parsed AACS key database.
+#[derive(Debug)]
+pub struct KeyDb {
+    /// Device keys for MKB processing
+    pub device_keys: Vec<DeviceKey>,
+    /// Processing keys (pre-computed media keys for specific MKB versions)
+    pub processing_keys: Vec<[u8; 16]>,
+    /// Host certificate + private key for SCSI authentication
+    pub host_certs: Vec<HostCert>,
+    /// Per-disc VUK entries indexed by disc hash (hex lowercase)
+    pub disc_entries: HashMap<String, DiscEntry>,
+}
+
+/// A device key for MKB subset-difference tree processing.
+#[derive(Debug, Clone)]
+pub struct DeviceKey {
+    pub key: [u8; 16],
+    pub node: u16,
+    pub uv: u32,
+    pub u_mask_shift: u8,
+}
+
+/// Host certificate + private key for AACS SCSI authentication.
+#[derive(Debug, Clone)]
+pub struct HostCert {
+    /// AACS 1.0: 20 bytes. AACS 2.0: 32 bytes.
+    pub private_key: [u8; 20],
+    /// AACS 1.0: 92 bytes. AACS 2.0: 132 bytes.
+    pub certificate: Vec<u8>,
+    /// AACS 2.0 host private key (P-256, 32 bytes). None for AACS 1.0 only.
+    pub private_key_v2: Option<[u8; 32]>,
+    /// AACS 2.0 host certificate (type 0x11). None for AACS 1.0 only.
+    pub certificate_v2: Option<Vec<u8>>,
+}
+
+/// A per-disc entry from the key database.
+#[derive(Debug, Clone)]
+pub struct DiscEntry {
+    /// Disc hash (20 bytes, hex)
+    pub disc_hash: String,
+    /// Disc title
+    pub title: String,
+    /// Media Key (16 bytes) — from MKB processing
+    pub media_key: Option<[u8; 16]>,
+    /// Disc ID (16 bytes)
+    pub disc_id: Option<[u8; 16]>,
+    /// Volume Unique Key (16 bytes) — decrypts title keys
+    pub vuk: Option<[u8; 16]>,
+    /// Unit keys (title keys) indexed by CPS unit number
+    pub unit_keys: Vec<(u32, [u8; 16])>,
+}
+
+/// Parse a hex string like "0xABCD..." into bytes.
+pub(crate) fn parse_hex(s: &str) -> Option<Vec<u8>> {
+    let s = s.trim().trim_start_matches("0x").trim_start_matches("0X");
+    if s.len() % 2 != 0 {
+        return None;
+    }
+    let mut out = Vec::with_capacity(s.len() / 2);
+    for i in (0..s.len()).step_by(2) {
+        out.push(u8::from_str_radix(&s[i..i + 2], 16).ok()?);
+    }
+    Some(out)
+}
+
+/// Parse hex into a fixed-size array.
+pub(crate) fn parse_hex16(s: &str) -> Option<[u8; 16]> {
+    let v = parse_hex(s)?;
+    if v.len() != 16 {
+        return None;
+    }
+    let mut out = [0u8; 16];
+    out.copy_from_slice(&v);
+    Some(out)
+}
+
+pub(crate) fn parse_hex20(s: &str) -> Option<[u8; 20]> {
+    let v = parse_hex(s)?;
+    if v.len() != 20 {
+        return None;
+    }
+    let mut out = [0u8; 20];
+    out.copy_from_slice(&v);
+    Some(out)
+}
+
+impl KeyDb {
+    /// Construct an empty KeyDb. Used by unit tests; production code
+    /// reaches a populated KeyDb via [`KeyDb::load`] or [`KeyDb::parse`].
+    pub fn empty() -> Self {
+        KeyDb {
+            device_keys: Vec::new(),
+            processing_keys: Vec::new(),
+            host_certs: Vec::new(),
+            disc_entries: HashMap::new(),
+        }
+    }
+
+    /// Parse a KEYDB.cfg file from a string.
+    pub fn parse(data: &str) -> Self {
+        let mut db = KeyDb {
+            device_keys: Vec::new(),
+            processing_keys: Vec::new(),
+            host_certs: Vec::new(),
+            disc_entries: HashMap::new(),
+        };
+
+        for line in data.lines() {
+            let line = line.trim();
+
+            // Skip comments and empty lines
+            if line.is_empty() || line.starts_with(';') || line.starts_with('#') {
+                continue;
+            }
+
+            // Device Key
+            if line.starts_with("| DK") {
+                if let Some(dk) = Self::parse_device_key(line) {
+                    db.device_keys.push(dk);
+                }
+                continue;
+            }
+
+            // Processing Key
+            if line.starts_with("| PK") {
+                if let Some(pk) = Self::parse_processing_key(line) {
+                    db.processing_keys.push(pk);
+                }
+                continue;
+            }
+
+            // Host Certificate (AACS 2.0)
+            if line.starts_with("| HC2") {
+                if let Some(hc) = db.host_certs.last_mut() {
+                    if let Some((pk, cert)) = Self::parse_host_cert_v2(line) {
+                        hc.private_key_v2 = Some(pk);
+                        hc.certificate_v2 = Some(cert);
+                    }
+                }
+                continue;
+            }
+
+            // Host Certificate (AACS 1.0)
+            if line.starts_with("| HC") {
+                if let Some(hc) = Self::parse_host_cert(line) {
+                    db.host_certs.push(hc);
+                }
+                continue;
+            }
+
+            // Disc entry: starts with 0x
+            if line.starts_with("0x") && line.contains(" = ") {
+                if let Some(entry) = Self::parse_disc_entry(line) {
+                    db.disc_entries.insert(entry.disc_hash.clone(), entry);
+                }
+            }
+        }
+
+        db
+    }
+
+    /// Load a KEYDB.cfg from disk.
+    pub fn load(path: &std::path::Path) -> std::io::Result<Self> {
+        let data = std::fs::read_to_string(path)?;
+        Ok(Self::parse(&data))
+    }
+
+    /// Look up a disc by its hash. Returns the VUK if found.
+    pub fn find_vuk(&self, disc_hash: &str) -> Option<[u8; 16]> {
+        let hash = disc_hash
+            .trim()
+            .to_lowercase()
+            .trim_start_matches("0x")
+            .to_string();
+        // Try with 0x prefix and without
+        self.disc_entries
+            .get(&format!("0x{hash}"))
+            .or_else(|| self.disc_entries.get(&hash))
+            .and_then(|e| e.vuk)
+    }
+
+    /// Look up a disc by its hash. Returns the full entry.
+    pub fn find_disc(&self, disc_hash: &str) -> Option<&DiscEntry> {
+        let hash = disc_hash
+            .trim()
+            .to_lowercase()
+            .trim_start_matches("0x")
+            .to_string();
+        self.disc_entries
+            .get(&format!("0x{hash}"))
+            .or_else(|| self.disc_entries.get(&hash))
+    }
+
+    // ── Parsers ─────────────────────────────────────────────────────────────
+
+    fn parse_device_key(line: &str) -> Option<DeviceKey> {
+        // | DK | DEVICE_KEY 0x... | DEVICE_NODE 0x... | KEY_UV 0x... | KEY_U_MASK_SHIFT 0x...
+        let key_str = line.split("DEVICE_KEY").nth(1)?.split('|').next()?.trim();
+        let node_str = line.split("DEVICE_NODE").nth(1)?.split('|').next()?.trim();
+        let uv_str = line.split("KEY_UV").nth(1)?.split('|').next()?.trim();
+        let shift_str = line
+            .split("KEY_U_MASK_SHIFT")
+            .nth(1)?
+            .split(';')
+            .next()?
+            .split('|')
+            .next()?
+            .trim();
+
+        Some(DeviceKey {
+            key: parse_hex16(key_str)?,
+            node: u16::from_str_radix(node_str.trim_start_matches("0x"), 16).ok()?,
+            uv: u32::from_str_radix(uv_str.trim_start_matches("0x"), 16).ok()?,
+            u_mask_shift: u8::from_str_radix(shift_str.trim_start_matches("0x"), 16).ok()?,
+        })
+    }
+
+    fn parse_processing_key(line: &str) -> Option<[u8; 16]> {
+        // | PK | 0x...
+        let parts: Vec<&str> = line.split('|').collect();
+        if parts.len() >= 3 {
+            let key_str = parts[2].split(';').next()?.trim();
+            return parse_hex16(key_str);
+        }
+        None
+    }
+
+    fn parse_host_cert(line: &str) -> Option<HostCert> {
+        // | HC | HOST_PRIV_KEY 0x... | HOST_CERT 0x...
+        let priv_str = line
+            .split("HOST_PRIV_KEY")
+            .nth(1)?
+            .split('|')
+            .next()?
+            .trim();
+        let cert_str = line
+            .split("HOST_CERT")
+            .nth(1)?
+            .split(';')
+            .next()?
+            .split('|')
+            .next()?
+            .trim();
+
+        Some(HostCert {
+            private_key: parse_hex20(priv_str)?,
+            certificate: parse_hex(cert_str)?,
+            private_key_v2: None,
+            certificate_v2: None,
+        })
+    }
+
+    /// Parse AACS 2.0 host cert: `| HC2 | HOST_PRIV_KEY 0x... | HOST_CERT 0x...`
+    fn parse_host_cert_v2(line: &str) -> Option<([u8; 32], Vec<u8>)> {
+        let priv_str = line
+            .split("HOST_PRIV_KEY")
+            .nth(1)?
+            .split('|')
+            .next()?
+            .trim();
+        let cert_str = line
+            .split("HOST_CERT")
+            .nth(1)?
+            .split(';')
+            .next()?
+            .split('|')
+            .next()?
+            .trim();
+
+        let priv_bytes = parse_hex(priv_str)?;
+        if priv_bytes.len() != 32 {
+            return None;
+        }
+        let mut pk = [0u8; 32];
+        pk.copy_from_slice(&priv_bytes);
+
+        let cert = parse_hex(cert_str)?;
+        if cert.len() < 132 {
+            return None;
+        }
+
+        Some((pk, cert))
+    }
+
+    fn parse_disc_entry(line: &str) -> Option<DiscEntry> {
+        // 0x<hash> = <title> | D | <date> | M | 0x<mk> | I | 0x<id> | V | 0x<vuk> | U | <unit_keys>
+        let (hash_part, rest) = line.split_once(" = ")?;
+        let disc_hash = hash_part.trim().to_lowercase();
+
+        // Extract title (before first |)
+        let title_part = rest.split(" | ").next().unwrap_or("").trim();
+        // Clean title: "TITLE_NAME (Display Title)" → use display title if present
+        let title = if let Some(start) = title_part.find('(') {
+            if let Some(end) = title_part.rfind(')') {
+                title_part[start + 1..end].to_string()
+            } else {
+                title_part.to_string()
+            }
+        } else {
+            title_part.to_string()
+        };
+
+        // Parse fields by tag
+        let mut media_key = None;
+        let mut disc_id = None;
+        let mut vuk = None;
+        let mut unit_keys = Vec::new();
+
+        let parts: Vec<&str> = rest.split(" | ").collect();
+        let mut i = 0;
+        while i < parts.len() {
+            match parts[i].trim() {
+                "M" => {
+                    if i + 1 < parts.len() {
+                        media_key = parse_hex16(parts[i + 1].trim());
+                        i += 1;
+                    }
+                }
+                "I" => {
+                    if i + 1 < parts.len() {
+                        disc_id = parse_hex16(parts[i + 1].trim());
+                        i += 1;
+                    }
+                }
+                "V" => {
+                    if i + 1 < parts.len() {
+                        vuk = parse_hex16(parts[i + 1].trim());
+                        i += 1;
+                    }
+                }
+                "U" => {
+                    if i + 1 < parts.len() {
+                        // Unit keys: "1-0xKEY" or "1-0xKEY ; comment"
+                        let uk_str = parts[i + 1].split(';').next().unwrap_or("").trim();
+                        for uk in uk_str.split(' ') {
+                            let uk = uk.trim();
+                            if let Some((num, key)) = uk.split_once('-') {
+                                if let Ok(n) = num.parse::<u32>() {
+                                    if let Some(k) = parse_hex16(key) {
+                                        unit_keys.push((n, k));
+                                    }
+                                }
+                            }
+                        }
+                        i += 1;
+                    }
+                }
+                _ => {}
+            }
+            i += 1;
+        }
+
+        Some(DiscEntry {
+            disc_hash,
+            title,
+            media_key,
+            disc_id,
+            vuk,
+            unit_keys,
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Get KEYDB path from KEYDB_PATH environment variable. Returns None if not set or not found.
+    fn keydb_path() -> Option<std::path::PathBuf> {
+        let path = std::path::PathBuf::from(std::env::var("KEYDB_PATH").ok()?);
+        if path.exists() { Some(path) } else { None }
+    }
+
+    #[test]
+    fn test_parse_disc_entry() {
+        let line = r#"***REMOVED*** = DUNE_PART_TWO (Dune: Part Two) | D | 2024-04-02 | M | ***REMOVED*** | I | ***REMOVED*** | V | ***REMOVED*** | U | 1-***REMOVED*** ; MKBv77"#;
+        let entry = KeyDb::parse_disc_entry(line).unwrap();
+        assert_eq!(entry.title, "Dune: Part Two");
+        assert!(entry.media_key.is_some());
+        assert!(entry.vuk.is_some());
+        assert_eq!(entry.unit_keys.len(), 1);
+        assert_eq!(entry.unit_keys[0].0, 1);
+    }
+
+    #[test]
+    fn test_parse_device_key() {
+        let line = "| DK | DEVICE_KEY ***REMOVED*** | DEVICE_NODE 0x0800 | KEY_UV 0x00000400 | KEY_U_MASK_SHIFT 0x17 ; MKBv01-MKBv48";
+        let dk = KeyDb::parse_device_key(line).unwrap();
+        assert_eq!(dk.node, 0x0800);
+        assert_eq!(dk.u_mask_shift, 0x17);
+    }
+
+    #[test]
+    fn test_parse_host_cert() {
+        let line = "| HC | HOST_PRIV_KEY ***REMOVED*** | HOST_CERT ***REMOVED*** ; Revoked";
+        let hc = KeyDb::parse_host_cert(line).unwrap();
+        assert_eq!(hc.private_key[0], 0x90);
+        assert_eq!(hc.certificate.len(), 92);
+    }
+
+    #[test]
+    fn test_parse_full_keydb() {
+        let path = match keydb_path() {
+            Some(p) => p,
+            None => return,
+        }; // skip if not available
+
+        let db = KeyDb::load(&path).unwrap();
+
+        assert_eq!(db.device_keys.len(), 4);
+        assert_eq!(db.processing_keys.len(), 3);
+        assert!(!db.host_certs.is_empty());
+        assert!(db.disc_entries.len() > 170000);
+
+        // Look up Dune: Part Two
+        let dune = db
+            .disc_entries
+            .values()
+            .find(|e| e.title.contains("Dune: Part Two") && e.vuk.is_some())
+            .expect("Dune: Part Two not found");
+        assert!(dune.media_key.is_some());
+        assert!(dune.vuk.is_some());
+        assert!(!dune.unit_keys.is_empty());
+
+        eprintln!(
+            "Parsed {} disc entries, {} DK, {} PK",
+            db.disc_entries.len(),
+            db.device_keys.len(),
+            db.processing_keys.len()
+        );
+    }
+}

src/aacs/mkb.rs

@@ -1,540 +0,0 @@
-//! AACS Media Key Block — [C] Chapter 3.
-//!
-//! The MKB record format (framing walker, the `MkbRecord` view, record-body
-//! finders), the MKBType / AACS-generation classification, and MKB-file
-//! utilities (content length, trimming, version). Consolidated here so the one
-//! place that understands MKB bytes is `mkb`. Some duplicate record finders
-//! still live side by side pending a follow-up that collapses them.
-
-// ── MKB record types ([C] Chapter 3) ──────────────────────────────────────
-// The ONE canonical set. Every record-type comparison in the `aacs` module
-// references these, so a type byte is never a bare literal scattered across
-// files (the `0x0c` variant-data record in particular used to appear in several
-// hand-rolled forms).
-
-/// Type-and-Version — carries the 32-bit MKBType / AACS generation.
-pub(crate) const REC_TYPE_AND_VERSION: u8 = 0x10;
-/// Subset-Difference index — the per-slot `(u_mask_shift, uv)` table.
-pub(crate) const REC_SUBSET_DIFFERENCE: u8 = 0x04;
-/// Media Key Data — the classical (1.0 / 2.0) per-subset cvalue table.
-pub(crate) const REC_MEDIA_KEY_DATA: u8 = 0x05;
-/// Explicit Subset-Difference — the smaller cvalue table some MKBs use.
-pub(crate) const REC_EXPLICIT_SUBSET_DIFF: u8 = 0x07;
-/// Media Key Variant Data (AACS 2.1) — the per-subset-difference `C` table
-/// (one 16-byte C per slot); the `Kmp` step reads C from HERE, not `0x2d`.
-pub(crate) const REC_MEDIA_KEY_VARIANT_DATA: u8 = 0x0c;
-/// Variant Data + Nonce (AACS 2.1) — the `VARIANTS[uv]` table (leading bytes)
-/// with the 16-byte `Kvn` Nonce at the tail.
-pub(crate) const REC_VARIANT_DATA_AND_NONCE: u8 = 0x2d;
-/// Variant Key Data table (AACS 2.1) — 65,535×16, indexed by the resolved VKD index.
-pub(crate) const REC_VKD_TABLE: u8 = 0x2f;
-/// Verify-Media-Key — AACS 1.0.
-pub(crate) const REC_VERIFY_MEDIA_KEY_V1: u8 = 0x81;
-/// Verify-Media-Key — AACS 2.x.
-pub(crate) const REC_VERIFY_MEDIA_KEY_V2: u8 = 0x86;
-
-/// A single MKB record produced by [`walk_mkb`].
-#[derive(Debug, Clone)]
-pub struct MkbRecord {
-    /// Byte offset of the record within the MKB.
-    pub offset: usize,
-    /// Record type byte.
-    pub rec_type: u8,
-    /// Record length in bytes (includes the 4-byte header).
-    pub rec_len: usize,
-    /// Record body (the bytes after the 4-byte header).
-    pub body: Vec<u8>,
-}
-
-/// Walk an MKB into a flat list of records.
-///
-/// MKB record framing per AACS: 1 byte type, 3 bytes BE length
-/// INCLUDING the 4-byte header, followed by payload. The walker stops
-/// at the first `(type=0, len=0)` end marker or at end of buffer.
-pub fn walk_mkb(mkb: &[u8]) -> Vec<MkbRecord> {
-    mkb_records(mkb)
-        .map(|(offset, rec_type, rec_len)| MkbRecord {
-            offset,
-            rec_type,
-            rec_len,
-            body: mkb[offset + 4..offset + rec_len].to_vec(),
-        })
-        .collect()
-}
-
-/// THE single MKB record-framing walker: yields `(offset, rec_type, rec_len)`
-/// for each record — a 4-byte header (type byte + big-endian 24-bit length)
-/// then the body — stopping at the `00 000000` end marker or a
-/// malformed/out-of-bounds length. Lazy (no body clone), so a find-one-record
-/// caller never materialises the multi-MB cvalue table. [`walk_mkb`] and every
-/// MKB record walk in `aacs::resolve`/`aacs::derive` are built on this, so the framing rules — and
-/// any future fix to them — live in exactly one place (they had drifted across
-/// six hand-rolled copies).
-pub(crate) fn mkb_records(mkb: &[u8]) -> impl Iterator<Item = (usize, u8, usize)> + '_ {
-    let mut pos = 0usize;
-    std::iter::from_fn(move || {
-        if pos + 4 > mkb.len() {
-            return None;
-        }
-        let rec_type = mkb[pos];
-        let rec_len = ((mkb[pos + 1] as usize) << 16)
-            | ((mkb[pos + 2] as usize) << 8)
-            | (mkb[pos + 3] as usize);
-        if rec_type == 0 && rec_len == 0 {
-            return None;
-        }
-        if rec_len < 4 || pos + rec_len > mkb.len() {
-            return None;
-        }
-        let here = pos;
-        pos += rec_len;
-        Some((here, rec_type, rec_len))
-    })
-}
-
-pub(crate) fn mkb_find_body(records: &[MkbRecord], rec_type: u8) -> Option<&[u8]> {
-    records
-        .iter()
-        .find(|r| r.rec_type == rec_type && !r.body.is_empty())
-        .map(|r| r.body.as_slice())
-}
-
-/// AACS protection generation a disc carries.
-///
-/// The content cert byte distinguishes V10 (`0x00`) from V20 (`0x01`). V21
-/// cannot be detected from the cert alone — a V21 disc carries a V20 cert
-/// and is upgraded to `V21` only after the MKB walk turns up the real Variant
-/// records `0x2d` / `0x2f` (Encrypted Media Key Variant Data and the Variant
-/// Key Data table).
-///
-/// Key-storage stride in `Unit_Key_RO.inf` is 48 bytes for V10 and 64
-/// bytes for V20 / V21.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum AacsVersion {
-    /// AACS 1.0 — original BD-ROM.
-    V10,
-    /// AACS 2.0 — UHD-BD, classical Media Key derivation.
-    V20,
-    /// AACS 2.1 — UHD-BD with Media Key Variant chain on top of V20.
-    V21,
-}
-
-/// AACS major version as the small integer threaded through the scan / key
-/// paths (`AacsState.version`, `DiscInputs.version`, `DiscInputsCtx::new`):
-/// 1 = AACS 1.0 (BD), 2 = AACS 2.x (UHD). Centralised so the bare `1`/`2` — and
-/// the V10-vs-else stride choice it drives — lives in exactly one place.
-pub const AACS_MAJOR_BD: u8 = 1;
-
-pub const AACS_MAJOR_UHD: u8 = 2;
-
-impl AacsVersion {
-    /// Stride (in bytes) between successive encrypted unit keys in
-    /// `Unit_Key_RO.inf`.
-    pub(crate) fn unit_key_stride(self) -> usize {
-        match self {
-            AacsVersion::V10 => 48,
-            AacsVersion::V20 | AacsVersion::V21 => 64,
-        }
-    }
-
-    /// This version as the major integer ([`AACS_MAJOR_BD`] / [`AACS_MAJOR_UHD`]).
-    pub fn major(self) -> u8 {
-        match self {
-            AacsVersion::V10 => AACS_MAJOR_BD,
-            AacsVersion::V20 | AacsVersion::V21 => AACS_MAJOR_UHD,
-        }
-    }
-
-    /// The version a bare major integer selects for stride purposes: only the
-    /// BD major is V10; every other value takes the V20/V21 64-byte stride.
-    pub fn from_major(major: u8) -> Self {
-        if major == AACS_MAJOR_BD {
-            AacsVersion::V10
-        } else {
-            AacsVersion::V20
-        }
-    }
-}
-
-/// Find Verify Media Key Record (type 0x81 for AACS 1.0, 0x86 for AACS 2.0/2.1) in MKB.
-/// 0x81: [C] §3.2.5.1.4. 0x86 (AACS 2.x): [RE] — not in the public spec (from real 2.x MKBs).
-pub(crate) fn mkb_find_mk_dv(mkb: &[u8]) -> Option<[u8; 16]> {
-    // Verify-Media-Key record (0x81 for AACS 1.0, 0x86 for AACS 2.x): mk_dv is
-    // the 16 bytes at record offset 4 (body offset 0). Needs rec_len >= 20.
-    let found = mkb_records(mkb).find(|&(_, rt, len)| {
-        (rt == REC_VERIFY_MEDIA_KEY_V1 || rt == REC_VERIFY_MEDIA_KEY_V2) && len >= 20
-    });
-    match found {
-        Some((o, rec_type, rec_len)) => {
-            let mut dv = [0u8; 16];
-            dv.copy_from_slice(&mkb[o + 4..o + 20]);
-            tracing::debug!(
-                target: "freemkv::disc",
-                phase = "mkb_mk_dv_found",
-                rec_type,
-                pos = o,
-                rec_len,
-                "mk_dv extracted from MKB"
-            );
-            Some(dv)
-        }
-        None => {
-            tracing::warn!(
-                target: "freemkv::disc",
-                phase = "mkb_mk_dv_not_found",
-                "no 0x81/0x86 record with rec_len>=20 found"
-            );
-            None
-        }
-    }
-}
-
-/// Find Subset-Difference records (type 0x04) in MKB. [C] §3.2.5.1.5.
-pub(crate) fn mkb_find_subdiff_records(mkb: &[u8]) -> Option<Vec<u8>> {
-    find_record_body(mkb, 0x04)
-}
-
-/// Find the Media Key Data Record (cvalues table) in an MKB. [C] §3.2.4 / §3.2.5.1.7.
-///
-/// The cvalue table is record type `0x05` (Media Key Data) on BOTH AACS
-/// 1.0 and AACS 2.x MKBs — its 16-byte cvalue entries are 1:1 with the
-/// 5-byte Subset-Difference index entries in record `0x04` — the standard AACS
-/// MKB layout (`0x05` cvalues 1:1 with the `0x04` subset-difference index).
-///
-/// On AACS 2.x in-drive UHD MKBs the `0x05` table is large (the full
-/// subset-difference cvalue set: ~181k entries on a retail MKB, 1:1 with
-/// the giant `0x04` index), while record `0x07` (Explicit
-/// Subset-Difference Record) is a much smaller structure (~96 entries) and
-/// is NOT the cvalue table. An earlier version of this function preferred
-/// `0x07`, which under-tested the Subset-Difference walk on UHD discs and
-/// prevented the DK→walk path from ever finding the matching uv. The
-/// selection MUST therefore be `0x05`-first; `0x07` is only a fallback for
-/// malformed/legacy MKBs that somehow lack a `0x05` record.
-pub(crate) fn mkb_find_cvalues(mkb: &[u8]) -> Option<Vec<u8>> {
-    if let Some(body) = find_record_body(mkb, 0x05) {
-        return Some(body);
-    }
-    find_record_body(mkb, 0x07)
-}
-
-/// Walk an MKB and return the payload (header stripped) of the first
-/// record matching `rec_type`. Returns `None` if no such record exists or
-/// the record is empty.
-pub(crate) fn find_record_body(mkb: &[u8], rec_type_wanted: u8) -> Option<Vec<u8>> {
-    mkb_records(mkb)
-        .find(|&(_, rt, len)| rt == rec_type_wanted && len > 4)
-        .map(|(o, _, len)| mkb[o + 4..o + len].to_vec())
-}
-
-/// Real content length of an MKB: the byte offset where the record stream
-/// ends. MKB files (especially `MKB_RW.inf`, but `MKB_RO.inf` too on some
-/// discs) are allocated to a fixed size — often ~128 MiB — with the records at
-/// the front and the rest zero padding. Walking records (type+len) and stopping
-/// at the first padding byte (`type == 0` / zero-length / overrun) gives the
-/// actual size so callers can trim off megabytes of zeros before sending or
-/// archiving. Returns `mkb.len()` only if the whole buffer parsed as records.
-pub fn mkb_content_len(mkb: &[u8]) -> usize {
-    // End of the last framed record = where the fixed-region zero padding begins.
-    // (The `00 000000` terminator / overrun stops the walk; real MKBs pad with
-    // zeros, so this matches the prior "stop at the first padding byte".)
-    mkb_records(mkb)
-        .last()
-        .map(|(o, _, len)| o + len)
-        .unwrap_or(0)
-}
-
-/// Trim an MKB's trailing fixed-region padding to its real content length —
-/// but ONLY when [`mkb_content_len`] actually found one. It returns 0 for an
-/// MKB whose first record cannot be parsed; truncating to 0 in that case would
-/// hand downstream consumers (and the online key service) an EMPTY MKB that can
-/// never resolve. So a 0 (or a length that isn't strictly inside the buffer)
-/// leaves the MKB untouched. A 0.31.0 regression dropped this guard and
-/// `truncate`-d unconditionally, zeroing unrecognised MKBs.
-pub fn trim_mkb(mut mkb: Vec<u8>) -> Vec<u8> {
-    let n = mkb_content_len(&mkb);
-    if n > 0 && n < mkb.len() {
-        mkb.truncate(n);
-    }
-    mkb
-}
-
-/// Get MKB version from Type and Version Record (type 0x10).
-/// Layout: 4-byte record header at `pos` (type + BE24 length), then the
-/// record body starts at `pos + 4`. The body holds the BE u32 Type field at
-/// body offset 0 (`pos + 4`), then the BE u32 version at body offset 4
-/// (`pos + 8`).
-pub fn mkb_version(mkb: &[u8]) -> Option<u32> {
-    // Type-and-Version record (0x10): version is the BE u32 at body offset 4
-    // (record offset 8). Needs rec_len >= 12 (4 header + 4 type + 4 version).
-    mkb_records(mkb)
-        .find(|&(_, rt, len)| rt == REC_TYPE_AND_VERSION && len >= 12)
-        .map(|(o, _, _)| u32::from_be_bytes([mkb[o + 8], mkb[o + 9], mkb[o + 10], mkb[o + 11]]))
-}
-
-/// `0x00031003` — recordable media MKB (Class I & II compute Km directly).
-pub const MKB_TYPE_3_RECORDABLE: u32 = 0x0003_1003;
-
-/// `0x00041003` — AACS 1.0 pre-recorded content MKB (KCD-based). Standard BD.
-pub const MKB_TYPE_4_PRERECORDED: u32 = 0x0004_1003;
-
-/// `0x000A1003` — Class II / Unified MKB (Sequence-Key-Block functionality).
-pub const MKB_TYPE_10_CLASS_II: u32 = 0x000A_1003;
-
-/// `0x48141003` — AACS 2.0 Category C (UHD content) MKB type value.
-pub const MKB_20_CATEGORY_C: u32 = 0x4814_1003;
-
-/// `0x48151003` — AACS 2.1 Category C (UHD content) MKB type value.
-pub const MKB_21_CATEGORY_C: u32 = 0x4815_1003;
-
-/// The AACS MKB Type field, decoded.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum MkbType {
-    /// Type 3 — recordable media.
-    Recordable,
-    /// Type 4 — AACS 1.0 pre-recorded content (KCD). Standard Blu-ray.
-    Prerecorded,
-    /// Type 10 — Class II / Unified (SKB).
-    ClassII,
-    /// AACS 2.0 Category C — UHD content.
-    CategoryC20,
-    /// AACS 2.1 Category C — UHD content.
-    CategoryC21,
-    /// Unrecognized MKBType value (raw field preserved).
-    Other(u32),
-}
-
-impl MkbType {
-    pub(crate) fn from_raw(raw: u32) -> Self {
-        match raw {
-            MKB_TYPE_3_RECORDABLE => MkbType::Recordable,
-            MKB_TYPE_4_PRERECORDED => MkbType::Prerecorded,
-            MKB_TYPE_10_CLASS_II => MkbType::ClassII,
-            MKB_20_CATEGORY_C => MkbType::CategoryC20,
-            MKB_21_CATEGORY_C => MkbType::CategoryC21,
-            other => MkbType::Other(other),
-        }
-    }
-
-    /// AACS generation this MKB belongs to (Category C → 2.0/2.1, else 1.0).
-    pub fn generation(self) -> AacsVersion {
-        match self {
-            MkbType::CategoryC21 => AacsVersion::V21,
-            MkbType::CategoryC20 => AacsVersion::V20,
-            _ => AacsVersion::V10,
-        }
-    }
-
-    /// `true` for UHD (AACS 2.x Category C); `false` for Blu-ray (AACS 1.x).
-    pub fn is_uhd(self) -> bool {
-        matches!(self, MkbType::CategoryC20 | MkbType::CategoryC21)
-    }
-}
-
-/// The raw 32-bit MKBType field from the Type-and-Version record (0x10), bytes
-/// 4-7. `None` if no 0x10 record is present. [C] §3.2.5.1.1 Table 3-2.
-pub fn mkb_type_raw(mkb: &[u8]) -> Option<u32> {
-    // Type-and-Version record (0x10): the 32-bit MKBType is bytes 4-7 (body
-    // offset 0). Needs rec_len >= 8 (4 header + 4 type).
-    mkb_records(mkb)
-        .find(|&(_, rt, len)| rt == REC_TYPE_AND_VERSION && len >= 8)
-        .map(|(o, _, _)| u32::from_be_bytes([mkb[o + 4], mkb[o + 5], mkb[o + 6], mkb[o + 7]]))
-}
-
-/// Decode an MKB's Type field. `None` if no Type-and-Version record is present.
-pub fn mkb_type(mkb: &[u8]) -> Option<MkbType> {
-    mkb_type_raw(mkb).map(MkbType::from_raw)
-}
-
-/// `Some(true)` if this MKB is a UHD (AACS 2.x Category C) block, `Some(false)`
-/// for Blu-ray (AACS 1.x), `None` if the Type record is absent.
-pub fn mkb_is_uhd(mkb: &[u8]) -> Option<bool> {
-    mkb_type(mkb).map(MkbType::is_uhd)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    /// One MKB record: 1 type byte + big-endian 24-bit total length + body.
-    fn rec(rec_type: u8, body: &[u8]) -> Vec<u8> {
-        let len = 4 + body.len();
-        let mut v = vec![rec_type, (len >> 16) as u8, (len >> 8) as u8, len as u8];
-        v.extend_from_slice(body);
-        v
-    }
-
-    /// Type-and-Version record (0x10): body = 4-byte MKBType + 4-byte version.
-    fn type_and_version(mkb_type: u32, version: u32) -> Vec<u8> {
-        let mut body = mkb_type.to_be_bytes().to_vec();
-        body.extend_from_slice(&version.to_be_bytes());
-        rec(REC_TYPE_AND_VERSION, &body)
-    }
-
-    #[test]
-    fn walker_frames_records_and_stops_at_end_marker() {
-        let mut mkb = type_and_version(MKB_20_CATEGORY_C, 77);
-        mkb.extend(rec(REC_VKD_TABLE, &[0xAA; 16]));
-        mkb.extend([0x00, 0x00, 0x00, 0x00]); // end marker
-        mkb.extend(rec(0x99, &[0xFF; 8])); // must NOT be walked (past the marker)
-
-        let recs = walk_mkb(&mkb);
-        assert_eq!(recs.len(), 2, "walk stops at the 00 000000 end marker");
-        assert_eq!(recs[0].rec_type, REC_TYPE_AND_VERSION);
-        assert_eq!(recs[1].rec_type, REC_VKD_TABLE);
-        assert_eq!(recs[1].body, vec![0xAA; 16]);
-    }
-
-    #[test]
-    fn walker_stops_on_malformed_or_out_of_bounds_length() {
-        // A record whose declared length runs past the buffer end must terminate
-        // the walk rather than panic or read OOB.
-        let mkb = vec![REC_VKD_TABLE, 0x00, 0xFF, 0xFF, 0x01, 0x02]; // len=0xFFFF, only 6 bytes
-        assert!(
-            walk_mkb(&mkb).is_empty(),
-            "over-long record yields no records"
-        );
-        // A sub-4 length (shorter than the header itself) is also rejected.
-        let short = vec![REC_VKD_TABLE, 0x00, 0x00, 0x02];
-        assert!(walk_mkb(&short).is_empty(), "sub-4 length is rejected");
-        // A truncated header (< 4 bytes) yields nothing.
-        assert!(walk_mkb(&[0x10, 0x00]).is_empty());
-    }
-
-    #[test]
-    fn mkb_type_and_version_decode_from_the_type_record() {
-        let mut mkb = type_and_version(MKB_21_CATEGORY_C, 100);
-        mkb.extend([0x00, 0x00, 0x00, 0x00]);
-        assert_eq!(mkb_type_raw(&mkb), Some(MKB_21_CATEGORY_C));
-        assert_eq!(mkb_version(&mkb), Some(100));
-        assert_eq!(mkb_is_uhd(&mkb), Some(true), "2.1 Category C is UHD");
-
-        let bd = type_and_version(MKB_TYPE_4_PRERECORDED, 68);
-        assert_eq!(
-            mkb_is_uhd(&bd),
-            Some(false),
-            "AACS 1.0 prerecorded is not UHD"
-        );
-        // No Type record → None (not a panic, not a fabricated value).
-        assert_eq!(mkb_version(&rec(REC_VKD_TABLE, &[0; 16])), None);
-        assert_eq!(mkb_type_raw(&[]), None);
-    }
-
-    #[test]
-    fn trim_mkb_keeps_only_the_framed_records() {
-        let mut mkb = type_and_version(MKB_20_CATEGORY_C, 1);
-        let content_len = mkb.len(); // the single framed record, no end marker
-        mkb.extend([0x00, 0x00, 0x00, 0x00]); // end marker
-        mkb.extend([0xDE; 4096]); // trailing padding past the end marker
-        let trimmed = trim_mkb(mkb);
-        assert_eq!(
-            trimmed.len(),
-            content_len,
-            "trim keeps the framed records, dropping the end marker and padding"
-        );
-    }
-
-    // ── BE24 length field: all THREE bytes ────────────────────────────────
-
-    /// The record length is a big-endian **24-bit** field, so the high byte
-    /// carries lengths of 64 KiB and up. The MKB records that matter most are
-    /// exactly that size — a real UHD cvalue table is `46_101 * 16` bytes and a
-    /// `0x2d` variant record is ~92 KiB — so a walker that dropped the high
-    /// byte would mis-frame every record of a real MKB from the first big one
-    /// onward, and every downstream key lookup would read the wrong bytes.
-    ///
-    /// (The pre-existing high-byte test used total length `0x0110`, whose high
-    /// byte is ZERO — it exercised the middle byte only. This one puts a
-    /// non-zero value in the high byte.)
-    #[test]
-    fn mkb_records_honors_the_high_byte_of_the_be24_length() {
-        const TOTAL: usize = 0x0001_0004; // 65_540 — high byte 0x01
-        let mut mkb = vec![REC_VKD_TABLE, 0x01, 0x00, 0x04];
-        mkb.resize(TOTAL, 0xAB);
-        // A second record follows, so a walker that mis-read the length would
-        // frame a different number of records rather than merely a short one.
-        mkb.extend(rec(REC_TYPE_AND_VERSION, &[0x11; 8]));
-
-        let recs = walk_mkb(&mkb);
-        assert_eq!(recs.len(), 2, "the big record must be framed as ONE record");
-        assert_eq!(
-            recs[0].rec_len, TOTAL,
-            "rec_len must include the high BE24 byte"
-        );
-        assert_eq!(recs[0].body.len(), TOTAL - 4);
-        assert_eq!(
-            recs[1].rec_type, REC_TYPE_AND_VERSION,
-            "the following record must start where the big one ends"
-        );
-    }
-
-    // ── Header-only records and the exact end marker ──────────────────────
-
-    /// `rec_len == 4` is a well-formed HEADER-ONLY record (the minimum the
-    /// walker accepts), including one sitting at the very end of the buffer
-    /// with no bytes after it. Rejecting either — the `pos + 4` bound or the
-    /// `rec_len < 4` floor being off by one — silently drops the MKB's last
-    /// record, and "the record isn't there" is indistinguishable from "the disc
-    /// doesn't carry it".
-    #[test]
-    fn mkb_records_yields_a_header_only_record_at_the_buffer_end() {
-        let mut mkb = rec(REC_TYPE_AND_VERSION, &[0xAA, 0xBB]);
-        mkb.extend([REC_VKD_TABLE, 0x00, 0x00, 0x04]); // 4-byte, empty body, at EOF
-        assert_eq!(
-            mkb.len(),
-            10,
-            "sanity: the last record ends at the buffer end"
-        );
-
-        let recs = walk_mkb(&mkb);
-        assert_eq!(recs.len(), 2, "the trailing header-only record is a record");
-        assert_eq!(recs[1].rec_type, REC_VKD_TABLE);
-        assert_eq!(recs[1].rec_len, 4);
-        assert!(recs[1].body.is_empty());
-    }
-
-    /// ONLY the exact `00 00 00 00` marker ends the walk. A record whose TYPE
-    /// happens to be `0x00` but which declares a real length is a record, not
-    /// the end of the MKB — stopping there would truncate everything after it,
-    /// including the cvalue and verify records the key derivation needs.
-    #[test]
-    fn mkb_records_stops_only_on_the_all_zero_end_marker() {
-        // A type-0 record of length 8, then a normal record, then the marker.
-        let mut mkb = vec![0x00, 0x00, 0x00, 0x08, 1, 2, 3, 4];
-        mkb.extend(rec(REC_VKD_TABLE, &[0x55; 16]));
-        mkb.extend([0x00, 0x00, 0x00, 0x00]); // the real end marker
-        mkb.extend(rec(0x99, &[0xFF; 4])); // past the marker: not walked
-
-        let recs = walk_mkb(&mkb);
-        assert_eq!(
-            recs.len(),
-            2,
-            "a type-0 record with a non-zero length is a record, not the end"
-        );
-        assert_eq!(recs[0].rec_type, 0x00);
-        assert_eq!(recs[0].rec_len, 8);
-        assert_eq!(recs[1].rec_type, REC_VKD_TABLE);
-        assert_eq!(recs[1].body, vec![0x55; 16]);
-    }
-
-    /// `mkb_type_raw` reports the 32-bit MKBType field verbatim ([C] §3.2.5.1.1
-    /// Table 3-2), including a value this build does not recognise — the caller
-    /// uses it to tell "unknown MKB generation" from "no Type record at all".
-    /// All four bytes must come from the record body; reading any of them from
-    /// the wrong offset yields a type that silently classifies as a different
-    /// AACS generation.
-    ///
-    /// The recognised constants all share bytes with the `0x10` record-type
-    /// header byte (e.g. `MKB_21_CATEGORY_C` is `48 15 10 03`), so this uses a
-    /// value with four distinct bytes, none of them `0x10`.
-    #[test]
-    fn mkb_type_raw_reads_all_four_body_bytes() {
-        const RAW: u32 = 0xDEAD_BEEF;
-        let mkb = type_and_version(RAW, 7);
-        assert_eq!(
-            mkb_type_raw(&mkb),
-            Some(RAW),
-            "every byte of the MKBType field must come from the record body"
-        );
-        assert_eq!(mkb_version(&mkb), Some(7));
-    }
-}

src/aacs/mod.rs

@@ -8,398 +8,33 @@
 //!   | DK | DEVICE_KEY 0x... | DEVICE_NODE 0x... | KEY_UV 0x... | KEY_U_MASK_SHIFT 0x...
 //!   | PK | 0x...
 //!   | HC | HOST_PRIV_KEY 0x... | HOST_CERT 0x...
-//!   | HC2 | HOST_PRIV_KEY 0x... | HOST_CERT 0x...
 //!   0x<disc_hash> = <title> | D | <date> | M | 0x<media_key> | I | 0x<disc_id> | V | 0x<vuk> | U | <unit_keys>
 //!
 //! The VUK decrypts title keys from AACS/Unit_Key_RO.inf on disc.
 //! Title keys decrypt m2ts stream content (AES-128-CBC).
-//!
-//! ## Spec provenance
-//!
-//! The crypto below carries `[TAG] §x.y` citations back to the published AACS
-//! specification (Final Rev 0.953), so each primitive links to the section it
-//! implements:
-//!   - `[C]`  — AACS Introduction and Common Cryptographic Elements Book (primitives, MKB/key-management).
-//!   - `[PR]` — AACS Pre-recorded Video Book (Volume/Title Key layer).
-//!   - `[BD]` — AACS Blu-ray Disc Pre-recorded Book (CPS Unit Key, Aligned Unit, Block Key).
-//!   - `[RE]` — reverse-engineered from real discs, cited only where the public
-//!     spec is silent (the `0x86` verify record and the Category-C MKB type values).
 
-pub mod content;
-pub mod crypto;
-pub mod derive;
-pub mod host_certs;
-pub mod index_select;
-pub mod inf;
-pub mod mkb;
-pub mod provider;
-pub mod resolve;
-pub mod segment;
-pub mod segment_key;
-pub mod trace;
-pub mod types;
-pub mod variant;
+pub mod decrypt;
+pub mod handshake;
+pub mod keydb;
+pub mod keys;
+pub mod variants;
+pub mod verify_magics;
 
-/// On-disc UDF paths to the AACS key-input files, plus HD DVD AACS-directory
-/// discovery.
-///
-/// BD and UHD keep their key material under a fixed `/AACS/…` tree, so those
-/// paths are constants. HD DVD keeps the equivalents in a reserved root
-/// directory whose NAME is authoring-house-specific — observed `ANY!` (Dukes
-/// of Hazzard) and `AAC!` (Freedom / Memory-Tech), each with a `<name>!_BAK`
-/// mirror — and whose title-key file is NOT always `VTKF000.AACS` (Freedom
-/// ships `VTKF090.AACS` + `VTKF100.AACS`). So the HD DVD files are DISCOVERED
-/// from the parsed UDF tree ([`find_hddvd_aacs_dir`] + [`role_paths`]), never
-/// hardcoded.
-///
-/// Each key ROLE ([`AacsRole`]) resolves to an ordered candidate list — the
-/// BD/UHD constants first, then whatever the HD DVD directory actually holds —
-/// which every reader walks with [`read_first`], first-that-reads. No reader
-/// ever branches on disc type: a BD/UHD disc has the `/AACS/` files so those
-/// win; an HD DVD has none of them, so it falls through to the discovered
-/// entries. Centralised so `resolve_vid_only`, `read_aacs_inputs`,
-/// `read_mkb_content`, and `read_aacs_version` can never silently diverge the
-/// disc_hash / MKB / VID that another reader feeds a key service.
-pub const PATH_UNIT_KEY_RO: &str = "/AACS/Unit_Key_RO.inf";
-pub const PATH_UNIT_KEY_RO_DUPLICATE: &str = "/AACS/DUPLICATE/Unit_Key_RO.inf";
-pub const PATH_MKB_RO: &str = "/AACS/MKB_RO.inf";
-pub const PATH_MKB_RW: &str = "/AACS/MKB_RW.inf";
-pub const PATH_CONTENT_CERT: &str = "/AACS/Content000.cer";
-pub const PATH_CONTENT_CERT_ALT: &str = "/AACS/Content001.cer";
-
-/// An AACS key-input role. [`role_paths`] maps it to an ordered candidate path
-/// list (BD/UHD constants, then the discovered HD DVD files).
-#[derive(Clone, Copy, Debug, PartialEq, Eq)]
-pub enum AacsRole {
-    /// Title-key file: BD/UHD `Unit_Key_RO.inf`, HD DVD `VTKF*.AACS`
-    /// (magic `DVD_HD_V_TKF`). The disc_hash is `SHA1` of this file.
-    UnitKey,
-    /// Media Key Block: BD/UHD `MKB_RO/RW.inf`, HD DVD `MKBROM.AACS`.
-    Mkb,
-    /// Content certificate: BD/UHD `Content000/001.cer`, HD DVD
-    /// `CONTENT_CERT.AACS` (byte 0 gives the AACS major).
-    ContentCert,
-}
-
-/// The HD DVD AACS directory in a parsed UDF tree, if present.
-///
-/// Identified structurally, NOT by a hardcoded name: the root child directory
-/// whose name ends in `!` (so the `<name>!_BAK` backup mirror, which also ends
-/// in a non-`!` char, is not mistaken for it) and which contains `MKBROM.AACS`.
-/// Observed real names: `ANY!` (Dukes of Hazzard), `AAC!` (Freedom). A BD/UHD
-/// disc has no such directory → `None`.
-pub(crate) fn find_hddvd_aacs_dir(udf: &crate::udf::UdfFs) -> Option<&crate::udf::DirEntry> {
-    udf.root.entries.iter().find(|e| {
-        e.is_dir
-            && e.name.ends_with('!')
-            && e.entries
-                .iter()
-                .any(|c| !c.is_dir && c.name.eq_ignore_ascii_case("MKBROM.AACS"))
-    })
-}
-
-/// Ordered candidate paths for an AACS key [`AacsRole`]: the fixed BD/UHD
-/// `/AACS/…` paths first, then the actual HD DVD files discovered in the disc's
-/// AACS directory (see [`find_hddvd_aacs_dir`]). A disc has only one family, so
-/// the other family's entries simply never read.
-///
-/// For [`AacsRole::UnitKey`] every `VTKF*.AACS` in the directory is appended in
-/// sorted name order — a disc may carry more than one variant (Freedom:
-/// `VTKF090` + `VTKF100`), not just `VTKF000`.
-pub(crate) fn role_paths(udf: &crate::udf::UdfFs, role: AacsRole) -> Vec<String> {
-    let mut v: Vec<String> = match role {
-        AacsRole::UnitKey => vec![PATH_UNIT_KEY_RO, PATH_UNIT_KEY_RO_DUPLICATE],
-        AacsRole::Mkb => vec![PATH_MKB_RO, PATH_MKB_RW],
-        AacsRole::ContentCert => vec![PATH_CONTENT_CERT, PATH_CONTENT_CERT_ALT],
-    }
-    .into_iter()
-    .map(String::from)
-    .collect();
-
-    if let Some(dir) = find_hddvd_aacs_dir(udf) {
-        let d = &dir.name;
-        match role {
-            AacsRole::Mkb => v.push(format!("/{d}/MKBROM.AACS")),
-            AacsRole::ContentCert => v.push(format!("/{d}/CONTENT_CERT.AACS")),
-            AacsRole::UnitKey => {
-                // Glob VTKF*.AACS — the title-key filename is not fixed at
-                // VTKF000 (Freedom ships VTKF090 + VTKF100). Sorted for a
-                // deterministic try order.
-                //
-                // Each VTKF%%%.AACS is bound to ONE playlist (VPLST%%%.XPL): the
-                // TKF's 12-byte PLAYLIST_NAME field (bytes 0x10..0x1C) names the
-                // playlist whose Title Keys it carries, and keys from a TKF whose
-                // name does not match the title's playlist must not be used. The
-                // caller resolves this by trying candidates in sorted order and
-                // decrypting with the one whose keys verify — correct for a
-                // single-playlist disc; a name-matched selection keyed on the
-                // active playlist is the precise form for multi-playlist discs.
-                let mut names: Vec<&str> = dir
-                    .entries
-                    .iter()
-                    .filter(|e| !e.is_dir)
-                    .filter(|e| {
-                        let u = e.name.to_ascii_uppercase();
-                        u.starts_with("VTKF") && u.ends_with(".AACS")
-                    })
-                    .map(|e| e.name.as_str())
-                    .collect();
-                names.sort_unstable();
-                v.extend(names.into_iter().map(|n| format!("/{d}/{n}")));
-            }
-        }
-    }
-    v
-}
-
-/// Walk an AACS role's candidate paths (from [`role_paths`]) and return the
-/// first that reads.
-///
-/// `read` performs the actual per-path read (full file or bounded prefix), so
-/// callers share the same first-present walk regardless of read style. Returns
-/// [`Error::AacsNoKeys`] if no candidate is present. Generic over the path
-/// element (`&str` or owned `String`) so it accepts the `Vec<String>` that
-/// [`role_paths`] builds from the discovered HD DVD directory.
-pub(crate) fn read_first<S, F>(candidates: &[S], mut read: F) -> crate::error::Result<Vec<u8>>
-where
-    S: AsRef<str>,
-    F: FnMut(&str) -> crate::error::Result<Vec<u8>>,
-{
-    for path in candidates {
-        if let Ok(buf) = read(path.as_ref()) {
-            return Ok(buf);
-        }
-    }
-    Err(crate::error::Error::AacsNoKeys)
-}
-
-// The module structure IS the public API — consumers import from the owning
-// module directly (e.g. `aacs::content::decrypt_unit`, `aacs::mkb::MkbType`,
-// `aacs::derive::{derive_vuk, resolve_candidate}`, `aacs::resolve::resolve_keys_v2`).
-// The `derive::probe` reproduction harness stays reachable via its module path.
-//
-// A small set of flat re-exports is kept for the typed key primitives and the
-// content-decrypt entry points that downstream key-source crates import through
-// the `aacs::` path. These are the stable, load-bearing names; keeping them here
-// lets those crates track the module refactor without a lockstep re-pin.
-pub use content::ALIGNED_UNIT_LEN;
-pub use derive::derive_vuk;
-pub use types::{DeviceKey, HostCert, MediaKey, ProcessingKey, UnitKey, Vid, Vuk};
-
-#[cfg(test)]
-mod tests {
-    //! Surface guards. The public API is the module tree itself (no facade).
-    //! Touching one representative item per module keeps these as a
-    //! compile-time contract that the module paths stay stable.
-
-    use super::content::ALIGNED_UNIT_LEN;
-    use super::inf::{disc_hash, disc_hash_hex};
-    use super::mkb::{AacsVersion, mkb_content_len, walk_mkb};
-    use super::variant::is_variant_mkb;
-
-    #[test]
-    fn aligned_unit_len_is_three_2048_byte_sectors() {
-        // ALIGNED_UNIT_LEN is the AACS aligned-unit size: 3 × 2048 = 6144.
-        // Re-exported from decrypt; pin the value here so the public constant
-        // and the spec stay in lockstep.
-        assert_eq!(ALIGNED_UNIT_LEN, 6144);
-        assert_eq!(ALIGNED_UNIT_LEN, 3 * 2048);
-    }
-
-    #[test]
-    fn version_strides_are_reexported_and_distinct() {
-        // The three AACS generations are part of the public surface, and the
-        // V10 (48) vs V20/V21 (64) stride distinction is the load-bearing
-        // difference. Confirm the enum re-export is usable and the variants
-        // are distinct values.
-        assert_ne!(AacsVersion::V10, AacsVersion::V20);
-        assert_ne!(AacsVersion::V20, AacsVersion::V21);
-    }
-
-    #[test]
-    fn public_helpers_are_callable_by_module_path() {
-        // Touch a representative function from each module so a dropped/renamed
-        // item fails to compile. Smoke calls, not behavioural assertions.
-        let _ = !crate::aacs::content::is_clean(
-            &[0u8; ALIGNED_UNIT_LEN],
-            crate::disc::ContentFormat::BdTs,
-        );
-        let _ = mkb_content_len(&[]);
-        let _ = is_variant_mkb(&walk_mkb(&[]));
-        let _ = disc_hash_hex(&disc_hash(b"x"));
-        let _ = super::derive::resolve_candidate(
-            &super::derive::KeyCandidate::Uk(super::types::UnitKey::new(0, [0u8; 16])),
-            &[],
-            &[],
-            None,
-        );
-    }
-
-    // ── HD DVD AACS directory / filename discovery ────────────────────────
-    //
-    // The HD DVD AACS dir name and title-key filename are authoring-specific
-    // and were previously hardcoded to `/ANY!/VTKF000.AACS`. These verify the
-    // discovery replacement against both real-disc shapes: Freedom (`AAC!` +
-    // `VTKF090`/`VTKF100`) and a BD/UHD disc (no HD DVD dir).
-
-    #[test]
-    fn role_paths_discovers_hddvd_dir_and_globs_all_vtkf_variants() {
-        use crate::udf::fixture::*;
-        // Freedom-shaped: an `AAC!` dir (NOT `ANY!`) holding MKBROM + two VTKF
-        // variants (090/100, NOT 000) + a VTUF usage file (must be excluded),
-        // plus the `AAC!_BAK` mirror (must NOT be picked as the AACS dir).
-        let mut disc = MemDisc::new();
-        let aacs_files = vec![
-            file("MKBROM.AACS", 100, 5000, 4096, true),
-            file("CONTENT_CERT.AACS", 101, 5100, 2048, true),
-            file("VTKF100.AACS", 102, 5200, 2048, true),
-            file("VTKF090.AACS", 103, 5300, 2048, true),
-            file("VTUF090.AACS", 104, 5400, 2048, true),
-        ];
-        let bak_files = vec![file("MKBROM.AACS", 110, 6000, 4096, true)];
-        let root = DirSpec {
-            name: String::new(),
-            icb_lba: 10,
-            dir_data_lba: 11,
-            files: Vec::new(),
-            subdirs: vec![
-                DirSpec {
-                    name: "AAC!".to_string(),
-                    icb_lba: 20,
-                    dir_data_lba: 21,
-                    files: aacs_files,
-                    subdirs: vec![],
-                },
-                DirSpec {
-                    name: "AAC!_BAK".to_string(),
-                    icb_lba: 30,
-                    dir_data_lba: 31,
-                    files: bak_files,
-                    subdirs: vec![],
-                },
-            ],
-        };
-        build_udf_skeleton(&mut disc, 10);
-        lay_dir(&mut disc, &root);
-        let udf = crate::udf::read_filesystem(&mut disc).expect("fs");
-
-        // Discovered structurally (ends in '!', holds MKBROM.AACS) — the real
-        // AACS dir, never the `_BAK` mirror.
-        let dir = super::find_hddvd_aacs_dir(&udf).expect("aacs dir");
-        assert_eq!(dir.name, "AAC!");
-
-        // UnitKey: BD/UHD paths first, then EVERY VTKF*.AACS in sorted order
-        // (090 before 100) — NOT hardcoded VTKF000; VTUF (usage) excluded.
-        assert_eq!(
-            super::role_paths(&udf, super::AacsRole::UnitKey),
-            vec![
-                super::PATH_UNIT_KEY_RO.to_string(),
-                super::PATH_UNIT_KEY_RO_DUPLICATE.to_string(),
-                "/AAC!/VTKF090.AACS".to_string(),
-                "/AAC!/VTKF100.AACS".to_string(),
-            ]
-        );
-        assert_eq!(
-            super::role_paths(&udf, super::AacsRole::Mkb)
-                .last()
-                .unwrap(),
-            "/AAC!/MKBROM.AACS"
-        );
-        assert_eq!(
-            super::role_paths(&udf, super::AacsRole::ContentCert)
-                .last()
-                .unwrap(),
-            "/AAC!/CONTENT_CERT.AACS"
-        );
-    }
-
-    /// The `!`-suffix and the `MKBROM.AACS` presence test are BOTH required —
-    /// the discovery is a conjunction, not a disjunction.
-    ///
-    /// The existing fixtures only ever present a directory that satisfies both
-    /// (`AAC!` with `MKBROM.AACS`) alongside one that satisfies neither
-    /// (`AAC!_BAK` — which contains `MKBROM.AACS` but is ALSO reached only after
-    /// the real dir), so either half of the conjunction could be dropped and the
-    /// same directory would still be found. Here a directory satisfies the name
-    /// half and NOT the contents half: it must not be picked.
-    ///
-    /// If it were, the HD DVD path would resolve `MKBROM.AACS`,
-    /// `CONTENT_CERT.AACS` and the title-key file under a directory that holds
-    /// none of them — the disc reports "no AACS key files" and never rips.
-    #[test]
-    fn a_bang_suffixed_directory_without_mkbrom_is_not_the_aacs_directory() {
-        use crate::udf::fixture::*;
-        let mut disc = MemDisc::new();
-        let root = DirSpec {
-            name: String::new(),
-            icb_lba: 10,
-            dir_data_lba: 11,
-            files: Vec::new(),
-            subdirs: vec![DirSpec {
-                // Ends in '!' — but carries no MKBROM.AACS, so it is not the
-                // HD DVD AACS directory.
-                name: "AAC!".to_string(),
-                icb_lba: 20,
-                dir_data_lba: 21,
-                files: vec![
-                    file("VTKF090.AACS", 102, 5200, 2048, true),
-                    file("CONTENT_CERT.AACS", 103, 5300, 2048, true),
-                ],
-                subdirs: vec![],
-            }],
-        };
-        build_udf_skeleton(&mut disc, 10);
-        lay_dir(&mut disc, &root);
-        let udf = crate::udf::read_filesystem(&mut disc).expect("fs");
-
-        assert!(
-            super::find_hddvd_aacs_dir(&udf).is_none(),
-            "a '!' directory without MKBROM.AACS is not the AACS directory"
-        );
-        assert_eq!(
-            super::role_paths(&udf, super::AacsRole::UnitKey),
-            vec![
-                super::PATH_UNIT_KEY_RO.to_string(),
-                super::PATH_UNIT_KEY_RO_DUPLICATE.to_string(),
-            ],
-            "no HD DVD candidates may be appended from a directory that was \
-             never identified as the AACS directory"
-        );
-    }
-
-    #[test]
-    fn role_paths_bd_uhd_disc_yields_no_hddvd_candidates() {
-        use crate::udf::fixture::*;
-        // A `/AACS/` tree (BD/UHD) has no '!' directory → discovery finds none
-        // and the candidate list is exactly the static BD/UHD paths.
-        let mut disc = MemDisc::new();
-        let root = DirSpec {
-            name: String::new(),
-            icb_lba: 10,
-            dir_data_lba: 11,
-            files: Vec::new(),
-            subdirs: vec![DirSpec {
-                name: "AACS".to_string(),
-                icb_lba: 20,
-                dir_data_lba: 21,
-                files: vec![
-                    file("Unit_Key_RO.inf", 100, 5000, 2048, true),
-                    file("MKB_RO.inf", 101, 5100, 2048, true),
-                ],
-                subdirs: vec![],
-            }],
-        };
-        build_udf_skeleton(&mut disc, 10);
-        lay_dir(&mut disc, &root);
-        let udf = crate::udf::read_filesystem(&mut disc).expect("fs");
-
-        assert!(super::find_hddvd_aacs_dir(&udf).is_none());
-        assert_eq!(
-            super::role_paths(&udf, super::AacsRole::UnitKey),
-            vec![
-                super::PATH_UNIT_KEY_RO.to_string(),
-                super::PATH_UNIT_KEY_RO_DUPLICATE.to_string(),
-            ]
-        );
-    }
-}
+// Explicit re-exports — only items needed by external consumers and sibling crate modules.
+// AES primitives (aes_ecb_encrypt, aes_ecb_decrypt, aes_cbc_decrypt) are pub(crate) in decrypt.rs.
+pub use decrypt::{
+    ALIGNED_UNIT_LEN, decrypt_bus, decrypt_unit, decrypt_unit_full, decrypt_unit_try_keys,
+    is_unit_encrypted,
+};
+pub use keydb::{DeviceKey, DiscEntry, HostCert, KeyDb};
+pub use keys::{
+    AacsVersion, ContentCert, ResolveContext, ResolvedKeys, UnitKeyFile, decrypt_unit_key,
+    derive_media_key_from_dk, derive_media_key_from_pk, derive_vuk, disc_hash, disc_hash_hex,
+    mkb_version, parse_content_cert, parse_unit_key_ro, read_mkb_from_drive, resolve_keys_v1,
+    resolve_keys_v2, resolve_keys_v21, validate_media_key_against_mkb,
+};
+pub use variants::{
+    KEY_CORRECTION_DATA_PLACEHOLDER, MediaKeyVariantError, MkbRecord, ProcessingKeyMatch,
+    derive_media_key_variant, is_variant_mkb, variant_data_record, variant_key_data, variant_nonce,
+    walk_mkb, walk_processing_key,
+};

src/aacs/provider.rs

@@ -1,456 +0,0 @@
-//! Key source abstraction for the AACS resolve chain.
-//!
-//! libfreemkv keeps all crypto (AES-G primitives, SD-tree walking,
-//! validation, MK/VUK/TK derivation) but accepts key material from
-//! arbitrary backends via [`KeyProvider`].
-//!
-//! Methods come in two flavors:
-//!
-//! - **Bulk material** ([`device_keys`], [`processing_keys`],
-//!   [`media_keys`]) — the resolver unions (and dedups) results
-//!   across all providers and tries each candidate.
-//! - **Disc-keyed lookup** ([`lookup_disc_by_hash`],
-//!   [`lookup_disc_by_vid`]) — the resolver short-circuits on the
-//!   first hit, so providers are queried in array order with
-//!   fastest/closest first.
-//!
-//! [`host_certs`] is a sixth method but is NOT consumed by the
-//! resolver chain: the SCSI handshake reads host certs directly from
-//! the caller-supplied credentials, not from the provider array. A
-//! provider that overrides `host_certs` today has no effect on the
-//! handshake; the method is retained as a forward-looking extension
-//! point only.
-//!
-//! Default impls return empty / `None` so backends only override
-//! the methods they actually support — an external key service might
-//! implement only `lookup_disc_by_hash`, while a local file might
-//! implement all six.
-//!
-//! Calls may block (disk I/O, network round-trips). The resolver
-//! invokes each method at most a handful of times per scan; for
-//! per-disc memoization, implementations should cache internally.
-//!
-//! [`device_keys`]: KeyProvider::device_keys
-//! [`processing_keys`]: KeyProvider::processing_keys
-//! [`media_keys`]: KeyProvider::media_keys
-//! [`host_certs`]: KeyProvider::host_certs
-//! [`lookup_disc_by_hash`]: KeyProvider::lookup_disc_by_hash
-//! [`lookup_disc_by_vid`]: KeyProvider::lookup_disc_by_vid
-
-use super::types::{DeviceKey, DiscEntry, HostCert};
-
-/// Source of AACS key material.
-///
-/// Implementors return raw material only — the resolver in
-/// `aacs::resolve` and `aacs::derive` own the crypto (DK→PK walking, PK validation,
-/// MK→VUK→TK derivation). See module docs for method semantics.
-pub trait KeyProvider: Send + Sync {
-    /// Device keys (top-of-tree, walked by the resolver).
-    fn device_keys(&self) -> Vec<DeviceKey> {
-        Vec::new()
-    }
-
-    /// Processing keys — terminal PKs or walk-input PKs. The
-    /// resolver tries each as a terminal first (cheap validate).
-    fn processing_keys(&self) -> Vec<[u8; 16]> {
-        Vec::new()
-    }
-
-    /// Every Media Key this provider holds, regardless of which disc it was
-    /// filed under. An MK is MKB-scoped (shared across a pressing/MKB-family),
-    /// so the resolver can verify each against the disc's MKB (`km_verifies`)
-    /// and resolve a disc whose own hash/VID isn't directly keyed.
-    fn media_keys(&self) -> Vec<[u8; 16]> {
-        Vec::new()
-    }
-
-    /// AACS host certificates (with their private keys) for drive
-    /// authentication. Multiple in case some are revoked.
-    ///
-    /// NOTE: not consumed by the resolver chain — the handshake reads
-    /// host certs from the caller-supplied credentials directly, so
-    /// overriding this method has no effect on drive authentication
-    /// today. Retained as a forward-looking extension point.
-    fn host_certs(&self) -> Vec<HostCert> {
-        Vec::new()
-    }
-
-    /// Direct per-disc lookup by SHA-1 of `Unit_Key_RO.inf`. Returns
-    /// `Some(entry)` if this provider has pre-computed material for
-    /// the disc (paths 4 and 5). Short-circuits the resolver.
-    fn lookup_disc_by_hash(&self, _disc_hash: &[u8; 20]) -> Option<DiscEntry> {
-        None
-    }
-
-    /// Lookup by Volume ID (path 3 — pre-computed MK + matching
-    /// VID). Short-circuits the resolver on hit.
-    fn lookup_disc_by_vid(&self, _volume_id: &[u8; 16]) -> Option<DiscEntry> {
-        None
-    }
-}
-
-/// Resolver-side helpers that aggregate across a provider array.
-///
-/// The resolver wraps `ctx.providers` (`&[&dyn KeyProvider]`) in this
-/// struct; these helpers apply the union-vs-short-circuit policy per
-/// method. The bulk unions dedup so overlapping providers don't make
-/// the resolver re-walk/re-validate identical material.
-pub(crate) struct Providers<'a>(pub &'a [&'a dyn KeyProvider]);
-
-impl Providers<'_> {
-    /// Union (deduped) — gather DKs from every provider.
-    pub fn device_keys(&self) -> Vec<DeviceKey> {
-        let mut v: Vec<DeviceKey> = self.0.iter().flat_map(|p| p.device_keys()).collect();
-        // DeviceKey has no Ord/Hash; dedup on the value-defining tuple.
-        v.sort_unstable_by_key(|d| (d.key, d.node, d.uv, d.u_mask_shift));
-        v.dedup_by_key(|d| (d.key, d.node, d.uv, d.u_mask_shift));
-        v
-    }
-
-    /// Union (deduped) — gather PKs from every provider.
-    pub fn processing_keys(&self) -> Vec<[u8; 16]> {
-        let mut v: Vec<[u8; 16]> = self.0.iter().flat_map(|p| p.processing_keys()).collect();
-        v.sort_unstable();
-        v.dedup();
-        v
-    }
-
-    /// Union of distinct Media Keys across every provider, for the MK-pool
-    /// brute (`km_verifies` against the disc's MKB).
-    pub fn media_keys(&self) -> Vec<[u8; 16]> {
-        let mut v: Vec<[u8; 16]> = self.0.iter().flat_map(|p| p.media_keys()).collect();
-        v.sort_unstable();
-        v.dedup();
-        v
-    }
-
-    /// Union — gather host certs from every provider. The SCSI handshake
-    /// reads host certs from the caller-supplied credentials directly and
-    /// does not call this, so it is currently unused by the resolver chain.
-    #[allow(dead_code)]
-    pub fn host_certs(&self) -> Vec<HostCert> {
-        self.0.iter().flat_map(|p| p.host_certs()).collect()
-    }
-
-    /// Short-circuit — query providers in array order, first hit wins.
-    pub fn lookup_disc_by_hash(&self, disc_hash: &[u8; 20]) -> Option<DiscEntry> {
-        self.0.iter().find_map(|p| p.lookup_disc_by_hash(disc_hash))
-    }
-
-    /// Short-circuit — query providers in array order, first hit wins.
-    pub fn lookup_disc_by_vid(&self, volume_id: &[u8; 16]) -> Option<DiscEntry> {
-        self.0.iter().find_map(|p| p.lookup_disc_by_vid(volume_id))
-    }
-}
-
-/// A [`KeyProvider`] backed by a single caller-supplied key's raw material —
-/// the bridge for [`crate::disc::Disc::decrypt_with`].
-///
-/// The application's key source did the lookup and handed in material at one
-/// level (DK / PK / MK / VUK). This exposes exactly that material to the
-/// version-dispatched resolver, which owns ALL derivation — so a source never
-/// derives, and the lib remains the single home for the AACS chain across
-/// 1.0 / 2.0 / 2.1 / 2.x.
-///
-/// Each level fills only its own field; the rest stay empty, so the resolver
-/// naturally runs the matching path (DK→…, PK→…, MK-pool brute, or a
-/// disc-keyed VUK hit). `decrypt_with` already knows the disc, so the
-/// `lookup_disc_by_*` hash/VID arguments are irrelevant — a present
-/// `disc_entry` is returned for any query.
-pub(crate) struct SuppliedKey {
-    pub device_keys: Vec<DeviceKey>,
-    pub processing_keys: Vec<[u8; 16]>,
-    pub media_keys: Vec<[u8; 16]>,
-    pub disc_entry: Option<DiscEntry>,
-}
-
-impl KeyProvider for SuppliedKey {
-    fn device_keys(&self) -> Vec<DeviceKey> {
-        self.device_keys.clone()
-    }
-    fn processing_keys(&self) -> Vec<[u8; 16]> {
-        self.processing_keys.clone()
-    }
-    fn media_keys(&self) -> Vec<[u8; 16]> {
-        self.media_keys.clone()
-    }
-    fn lookup_disc_by_hash(&self, _disc_hash: &[u8; 20]) -> Option<DiscEntry> {
-        self.disc_entry.clone()
-    }
-    fn lookup_disc_by_vid(&self, _volume_id: &[u8; 16]) -> Option<DiscEntry> {
-        self.disc_entry.clone()
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    fn entry(hash: &str, vuk: u8) -> DiscEntry {
-        DiscEntry {
-            disc_hash: hash.to_string(),
-            title: "t".to_string(),
-            media_key: None,
-            disc_id: None,
-            vuk: Some([vuk; 16]),
-            unit_keys: Vec::new(),
-        }
-    }
-
-    /// A host cert whose (non-secret) certificate body and private key are both
-    /// filled with `byte`, so a cert is identifiable in an aggregated list.
-    fn cert(byte: u8) -> HostCert {
-        HostCert {
-            private_key: [byte; 20],
-            certificate: vec![byte; 92],
-            private_key_v2: None,
-            certificate_v2: None,
-        }
-    }
-
-    fn dk(byte: u8, node: u16) -> DeviceKey {
-        DeviceKey {
-            key: [byte; 16],
-            node,
-            uv: 1,
-            u_mask_shift: 0,
-        }
-    }
-
-    /// A provider that returns fixed bulk material and an optional disc entry
-    /// keyed unconditionally (used to test array-order short-circuiting).
-    #[derive(Default)]
-    struct Fixed {
-        dks: Vec<DeviceKey>,
-        pks: Vec<[u8; 16]>,
-        mks: Vec<[u8; 16]>,
-        hash_hit: Option<DiscEntry>,
-        vid_hit: Option<DiscEntry>,
-    }
-    impl KeyProvider for Fixed {
-        fn device_keys(&self) -> Vec<DeviceKey> {
-            self.dks.clone()
-        }
-        fn processing_keys(&self) -> Vec<[u8; 16]> {
-            self.pks.clone()
-        }
-        fn media_keys(&self) -> Vec<[u8; 16]> {
-            self.mks.clone()
-        }
-        fn lookup_disc_by_hash(&self, _h: &[u8; 20]) -> Option<DiscEntry> {
-            self.hash_hit.clone()
-        }
-        fn lookup_disc_by_vid(&self, _v: &[u8; 16]) -> Option<DiscEntry> {
-            self.vid_hit.clone()
-        }
-    }
-
-    // ── KeyProvider default methods all return empty ───────────────────────
-
-    #[test]
-    fn default_provider_methods_return_empty() {
-        // A bare provider that overrides nothing must yield empty material so
-        // the resolver simply finds nothing through it (no surprise hits).
-        struct Empty;
-        impl KeyProvider for Empty {}
-        let e = Empty;
-        assert!(e.device_keys().is_empty());
-        assert!(e.processing_keys().is_empty());
-        assert!(e.media_keys().is_empty());
-        assert!(e.host_certs().is_empty());
-        assert!(e.lookup_disc_by_hash(&[0u8; 20]).is_none());
-        assert!(e.lookup_disc_by_vid(&[0u8; 16]).is_none());
-    }
-
-    // ── Providers::processing_keys: union + dedup ──────────────────────────
-
-    #[test]
-    fn providers_processing_keys_union_and_dedup() {
-        // Two providers each carrying overlapping PKs → the aggregate is the
-        // deduped union (the resolver must not re-validate identical material).
-        let a = Fixed {
-            pks: vec![[0x01u8; 16], [0x02u8; 16]],
-            ..Default::default()
-        };
-        let b = Fixed {
-            pks: vec![[0x02u8; 16], [0x03u8; 16]],
-            ..Default::default()
-        };
-        let arr: &[&dyn KeyProvider] = &[&a, &b];
-        let mut got = Providers(arr).processing_keys();
-        got.sort();
-        assert_eq!(got, vec![[0x01u8; 16], [0x02u8; 16], [0x03u8; 16]]);
-    }
-
-    #[test]
-    fn providers_media_keys_union_and_dedup() {
-        let a = Fixed {
-            mks: vec![[0xAAu8; 16]],
-            ..Default::default()
-        };
-        let b = Fixed {
-            mks: vec![[0xAAu8; 16], [0xBBu8; 16]],
-            ..Default::default()
-        };
-        let arr: &[&dyn KeyProvider] = &[&a, &b];
-        let mut got = Providers(arr).media_keys();
-        got.sort();
-        assert_eq!(got, vec![[0xAAu8; 16], [0xBBu8; 16]]);
-    }
-
-    #[test]
-    fn providers_device_keys_dedup_on_value_tuple() {
-        // DeviceKey has no Hash/Ord; dedup keys on (key,node,uv,u_mask_shift).
-        // Two identical DKs across providers collapse to one; a DK differing
-        // only in node is kept.
-        let a = Fixed {
-            dks: vec![dk(0x11, 5), dk(0x11, 5)],
-            ..Default::default()
-        };
-        let b = Fixed {
-            dks: vec![dk(0x11, 5), dk(0x11, 6)],
-            ..Default::default()
-        };
-        let arr: &[&dyn KeyProvider] = &[&a, &b];
-        let got = Providers(arr).device_keys();
-        assert_eq!(got.len(), 2, "identical DKs dedup; differing node kept");
-        let nodes: Vec<u16> = got.iter().map(|d| d.node).collect();
-        assert!(nodes.contains(&5) && nodes.contains(&6));
-    }
-
-    // ── Disc-keyed lookups: array-order short-circuit ──────────────────────
-
-    #[test]
-    fn providers_lookup_by_hash_first_hit_wins() {
-        // Querying providers in array order, the FIRST hit wins (closest /
-        // fastest first). Provider 0 hits → its entry is returned even though
-        // provider 1 also has one.
-        let a = Fixed {
-            hash_hit: Some(entry("first", 0x01)),
-            ..Default::default()
-        };
-        let b = Fixed {
-            hash_hit: Some(entry("second", 0x02)),
-            ..Default::default()
-        };
-        let arr: &[&dyn KeyProvider] = &[&a, &b];
-        let got = Providers(arr).lookup_disc_by_hash(&[0u8; 20]).unwrap();
-        assert_eq!(got.disc_hash, "first");
-        assert_eq!(got.vuk, Some([0x01u8; 16]));
-    }
-
-    #[test]
-    fn providers_lookup_by_hash_falls_through_to_later_provider() {
-        // Provider 0 misses, provider 1 hits → the later provider's entry is
-        // used (find_map continues past None).
-        let a = Fixed::default(); // hash_hit None
-        let b = Fixed {
-            hash_hit: Some(entry("second", 0x02)),
-            ..Default::default()
-        };
-        let arr: &[&dyn KeyProvider] = &[&a, &b];
-        let got = Providers(arr).lookup_disc_by_hash(&[0u8; 20]).unwrap();
-        assert_eq!(got.disc_hash, "second");
-    }
-
-    #[test]
-    fn providers_lookup_by_vid_first_hit_wins() {
-        let a = Fixed {
-            vid_hit: Some(entry("vid-a", 0x07)),
-            ..Default::default()
-        };
-        let b = Fixed {
-            vid_hit: Some(entry("vid-b", 0x08)),
-            ..Default::default()
-        };
-        let arr: &[&dyn KeyProvider] = &[&a, &b];
-        let got = Providers(arr).lookup_disc_by_vid(&[0u8; 16]).unwrap();
-        assert_eq!(got.disc_hash, "vid-a");
-    }
-
-    /// `Providers::host_certs` is the union across the provider array. It is not
-    /// wired into the handshake today (see the module docs), so nothing else in
-    /// the crate would notice a body that dropped every cert on the floor — and
-    /// the day it IS wired in, a silently-empty cert list means the drive AACS
-    /// authentication finds no host certificate to present and every disc fails
-    /// to open, with no indication that the caller's certs were discarded.
-    ///
-    /// Unlike the bulk key unions this one does NOT dedup (HostCert is not
-    /// Ord/Hash), so the assertion is on the full concatenation in array order.
-    #[test]
-    fn providers_host_certs_unions_every_providers_certs_in_array_order() {
-        struct Certs(Vec<HostCert>);
-        impl KeyProvider for Certs {
-            fn host_certs(&self) -> Vec<HostCert> {
-                self.0.clone()
-            }
-        }
-        // Distinguish certs by their (non-secret) certificate body, so the
-        // assertion lands on WHICH certs came back, not merely how many.
-        let a = Certs(vec![cert(0xA1), cert(0xA2)]);
-        let b = Certs(vec![cert(0xB1)]);
-        let arr: &[&dyn KeyProvider] = &[&a, &b];
-
-        let got = Providers(arr).host_certs();
-        let bodies: Vec<Vec<u8>> = got.iter().map(|c| c.certificate.clone()).collect();
-        assert_eq!(
-            bodies,
-            vec![vec![0xA1u8; 92], vec![0xA2u8; 92], vec![0xB1u8; 92]],
-            "every provider's certs must survive the union, in array order"
-        );
-        // The private key travels with the cert — a union that returned default
-        // certs would still have the right count.
-        assert_eq!(got[0].private_key, [0xA1u8; 20]);
-        assert_eq!(got[2].private_key, [0xB1u8; 20]);
-    }
-
-    #[test]
-    fn providers_empty_array_yields_nothing() {
-        let arr: &[&dyn KeyProvider] = &[];
-        let p = Providers(arr);
-        assert!(p.device_keys().is_empty());
-        assert!(p.processing_keys().is_empty());
-        assert!(p.media_keys().is_empty());
-        assert!(p.lookup_disc_by_hash(&[0u8; 20]).is_none());
-        assert!(p.lookup_disc_by_vid(&[0u8; 16]).is_none());
-    }
-
-    // ── SuppliedKey: each level exposes only its own material ──────────────
-
-    #[test]
-    fn supplied_key_exposes_only_populated_fields() {
-        // A SuppliedKey filled at the DK level exposes DKs and nothing else,
-        // so the resolver runs the matching (DK→…) path and no other.
-        let sk = SuppliedKey {
-            device_keys: vec![dk(0x33, 9)],
-            processing_keys: Vec::new(),
-            media_keys: Vec::new(),
-            disc_entry: None,
-        };
-        assert_eq!(sk.device_keys().len(), 1);
-        assert!(sk.processing_keys().is_empty());
-        assert!(sk.media_keys().is_empty());
-        assert!(sk.lookup_disc_by_hash(&[0u8; 20]).is_none());
-        assert!(sk.lookup_disc_by_vid(&[0u8; 16]).is_none());
-    }
-
-    #[test]
-    fn supplied_key_disc_entry_returned_for_any_hash_or_vid() {
-        // decrypt_with already knows the disc, so a present disc_entry is
-        // returned regardless of the hash/VID argument (the lookup args are
-        // irrelevant in this bridge).
-        let sk = SuppliedKey {
-            device_keys: Vec::new(),
-            processing_keys: Vec::new(),
-            media_keys: Vec::new(),
-            disc_entry: Some(entry("supplied", 0x44)),
-        };
-        // Two unrelated hashes both return the same entry.
-        let h1 = sk.lookup_disc_by_hash(&[0x01u8; 20]).unwrap();
-        let h2 = sk.lookup_disc_by_hash(&[0xFFu8; 20]).unwrap();
-        assert_eq!(h1.disc_hash, "supplied");
-        assert_eq!(h2.disc_hash, "supplied");
-        // And by VID likewise.
-        assert!(sk.lookup_disc_by_vid(&[0x00u8; 16]).is_some());
-    }
-}

src/aacs/segment.rs

@@ -1,454 +0,0 @@
-//! AACS 2.1 FMTS forensic segment map — `AACS/IndividualSegment.tbl`.
-//!
-//! An FMTS main feature interleaves short forensic **segments** — the sequence-key
-//! / forensic-watermark mechanism. Each segment carries an **index** (1..32): a
-//! tag in `IndividualSegment.tbl` that selects which of the 32 forensic **index
-//! keys** decrypts that segment's units, in place of the ordinary CPS Unit Key.
-//!
-//! Terminology (see the project AACS reference): the **index** here is NOT the
-//! AACS 2.1 *Media Key Variant* — that is the 65536-value device selector in the
-//! MKB that decides *which set* of index keys a device receives, a layer this
-//! module does not deal with. All the index keys belong to one variant, whose
-//! number is unknown and irrelevant to the segment map. Decrypting a segment with
-//! the Unit Key yields garbage — broken HEVC reference frames (empirically:
-//! `Could not find ref with POC …` on a plain unit-key rip).
-//!
-//! This table says WHERE the segments live and which index each carries, so a
-//! decoder can decrypt them with the matching index key instead of muxing
-//! unit-key garbage.
-//!
-//! Format (validated against a retail AACS 2.1 disc):
-//! ```text
-//!   header (8 bytes):  u32 type | u16 count | u16 record_size (= 16)
-//!   record[count] (16 bytes each):
-//!     u32 marker (= 0x01000000) | u16 index | u16 flag (= 1)
-//!     u32 start_spn | u32 end_spn        (source-packet numbers, inclusive)
-//! ```
-//! `index` is the 1..32 forensic index tag, NOT a sequential segment id: measured
-//! on a retail 2.1 disc it cycles 1,2,…,32,1,2,… across records in
-//! file order — 24 full cycles of 32 plus a final partial cycle of 24 = 792
-//! records. Source-packet numbers are the 192-byte BDAV packet index: byte offset
-//! = `spn * 192`. Each segment is ~2560 packets (~480 KB) = 80 aligned units,
-//! spread across the entire 54 GB feature (one roughly every 67 MB). Inside a
-//! segment the 80 units interleave in two stride-2 halves: applying the segment's
-//! index key decrypts ~40 of them to clean TS and garbles the other ~40 (a second
-//! interleaved half, unidentified), which the demux then drops — leaving one
-//! coherent stream. Confirmed by decoding a retail disc with a full set of 32
-//! index keys.
-
-/// Fixed size of one `IndividualSegment.tbl` record.
-pub const SEGMENT_RECORD_LEN: usize = 16;
-/// Bytes per BDAV source packet (188-byte TS + 4-byte arrival-time header).
-pub const SOURCE_PACKET_LEN: u64 = 192;
-
-/// One forensic segment: the inclusive source-packet range it occupies in the
-/// FMTS clip.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct Segment {
-    /// Forensic index tag, 1..=32 (field@4 of the record). Cycles across the
-    /// table rather than counting up — it selects WHICH of the 32 index keys
-    /// decrypts this range. (`0` is not used here; the default/non-forensic
-    /// content carries no segment record at all.)
-    pub index: u16,
-    /// First source packet of the segment (inclusive).
-    pub start_spn: u32,
-    /// Last source packet of the segment (inclusive).
-    pub end_spn: u32,
-}
-
-impl Segment {
-    /// Source-packet count in this (inclusive) segment.
-    pub fn packet_count(&self) -> u32 {
-        self.end_spn
-            .saturating_sub(self.start_spn)
-            .saturating_add(1)
-    }
-
-    /// Byte offset of the segment start within the clip (`start_spn * 192`).
-    pub fn start_byte(&self) -> u64 {
-        self.start_spn as u64 * SOURCE_PACKET_LEN
-    }
-
-    /// Byte length of the segment (`packet_count * 192`).
-    pub fn byte_len(&self) -> u64 {
-        self.packet_count() as u64 * SOURCE_PACKET_LEN
-    }
-
-    /// True when source packet `spn` falls inside this segment.
-    pub fn contains_spn(&self, spn: u32) -> bool {
-        spn >= self.start_spn && spn <= self.end_spn
-    }
-
-    /// True when the inclusive source-packet span `[first, last]` overlaps this
-    /// segment. Used to decide whether an aligned unit (which spans several
-    /// packets) touches the segment at all, not just whether one packet does.
-    pub fn overlaps_spn(&self, first: u32, last: u32) -> bool {
-        first <= self.end_spn && last >= self.start_spn
-    }
-}
-
-/// Source packets spanned by one AACS aligned unit: `6144 / 192 = 32`.
-pub const PACKETS_PER_UNIT: u32 =
-    (crate::aacs::content::ALIGNED_UNIT_LEN as u64 / SOURCE_PACKET_LEN) as u32;
-
-/// Byte offset within the clip of a clip-relative 2048-byte sector `lba`. The
-/// FMTS decode reads the clip file directly, so `lba` 0 is the clip's first
-/// byte and this offset lines up with the source-packet grid the segment map
-/// uses.
-pub fn lba_byte_offset(lba: u32) -> u64 {
-    lba as u64 * 2048
-}
-
-/// The forensic segment an AACS aligned unit belongs to, if any, given the
-/// unit's clip-relative byte offset.
-///
-/// This is the routing decision behind a 2.1 decrypt-miss: a unit that
-/// overlaps a forensic segment must be opened with that segment's **index key**
-/// (selected by the segment's `index`), not the CPS Unit Key. Opening it with
-/// the Unit Key is exactly what yields the broken-reference-frame garbage a
-/// plain unit-key rip produces. A unit outside every segment is ordinary
-/// content and a miss on it is a Unit-Key miss, so this returns `None` and the
-/// caller falls back to the normal unit-key fetch.
-///
-/// The unit is tested as a packet *span* (`[off/192, (off+6144-1)/192]`) so a
-/// unit that only partly overlaps a segment edge is still classified as
-/// forensic; on the observed disc segments are unit-aligned, but the span test
-/// does not rely on that.
-pub fn segment_for_unit(segments: &[Segment], unit_offset: u64) -> Option<&Segment> {
-    let unit_len = crate::aacs::content::ALIGNED_UNIT_LEN as u64;
-    let first = (unit_offset / SOURCE_PACKET_LEN) as u32;
-    let last = ((unit_offset + unit_len - 1) / SOURCE_PACKET_LEN) as u32;
-    segments.iter().find(|s| s.overlaps_spn(first, last))
-}
-
-/// Parse `IndividualSegment.tbl` into its forensic segments, in table
-/// order. Returns `None` when the header is malformed, the record size is not
-/// [`SEGMENT_RECORD_LEN`], or the declared record count overruns the buffer —
-/// so a truncated / foreign table degrades to "no segment map" rather than
-/// yielding bogus ranges.
-pub fn parse_individual_segments(tbl: &[u8]) -> Option<Vec<Segment>> {
-    if tbl.len() < 8 {
-        return None;
-    }
-    let count = u16::from_be_bytes([tbl[4], tbl[5]]) as usize;
-    let record_size = u16::from_be_bytes([tbl[6], tbl[7]]) as usize;
-    if record_size != SEGMENT_RECORD_LEN {
-        return None;
-    }
-    if 8usize.checked_add(count.checked_mul(record_size)?)? > tbl.len() {
-        return None;
-    }
-    let mut segments = Vec::with_capacity(count);
-    for i in 0..count {
-        let o = 8 + i * record_size;
-        // o+4..o+8 = index (u16, 1..32) + flag (u16); o+8..o+16 = start/end SPN.
-        let index = u16::from_be_bytes([tbl[o + 4], tbl[o + 5]]);
-        let start_spn = u32::from_be_bytes([tbl[o + 8], tbl[o + 9], tbl[o + 10], tbl[o + 11]]);
-        let end_spn = u32::from_be_bytes([tbl[o + 12], tbl[o + 13], tbl[o + 14], tbl[o + 15]]);
-        segments.push(Segment {
-            index,
-            start_spn,
-            end_spn,
-        });
-    }
-    Some(segments)
-}
-
-/// Map a clip-relative byte offset to the absolute LBA that holds it, by walking
-/// the title's extents (the `.fmts` clip's sectors in file order). Segment
-/// offsets in [`Segment`] are clip-relative source-packet numbers, so this is how
-/// a segment's `spn` range becomes disc LBAs. `None` if the offset is past the
-/// clip.
-pub fn clip_byte_to_lba(extents: &[crate::disc::Extent], clip_byte: u64) -> Option<u32> {
-    let mut cum = 0u64;
-    for e in extents {
-        let len = e.sector_count as u64 * crate::consts::SECTOR_BYTES as u64;
-        if clip_byte < cum + len {
-            let sector_in_ext = ((clip_byte - cum) / crate::consts::SECTOR_BYTES as u64) as u32;
-            return Some(e.start_lba.saturating_add(sector_in_ext));
-        }
-        cum += len;
-    }
-    None
-}
-
-/// Build the `[start_lba, end_lba) → key_idx` ranges for an FMTS forensic key map.
-///
-/// Each forensic segment's clip-relative source-packet span becomes an absolute
-/// LBA range tagged with the key its `index` selects (via `index_to_key_idx`,
-/// e.g. `|i| i as usize` when the pool is `[base, idx1, idx2, …]`). Applying that
-/// one key across the whole segment decodes the ~40 units of its interleave half
-/// to clean TS and garbles the other ~40 (the second interleaved half), which the
-/// demux then drops — yielding one coherent stream. Ranges outside every segment
-/// are left for the map's default (the ordinary Unit Key). A segment that straddles
-/// a UDF extent boundary is emitted as one range per whole-sector slice it covers.
-///
-/// The result feeds [`AacsKeyMap::from_ranges`](crate::decrypt::AacsKeyMap::from_ranges)
-/// with the Unit-Key index as the default — the same structure the CPS map uses,
-/// only finer-grained.
-pub fn fmts_key_ranges(
-    segments: &[Segment],
-    extents: &[crate::disc::Extent],
-    index_to_key_idx: &dyn Fn(u16) -> usize,
-) -> Vec<(u32, u32, usize)> {
-    let mut ranges = Vec::new();
-    for s in segments {
-        // SPNs are untrusted (from IndividualSegment.tbl); an inverted record
-        // (start_spn > end_spn) would underflow `end_byte - 1 - start_byte` below.
-        if s.start_spn > s.end_spn {
-            continue;
-        }
-        let start_byte = s.start_spn as u64 * SOURCE_PACKET_LEN;
-        let end_byte = (s.end_spn as u64 + 1) * SOURCE_PACKET_LEN; // exclusive
-        // A segment is unit-aligned and contiguous in clip bytes; map its first
-        // and last sector to LBAs. Segments are ~480 KB and extents are GB-sized,
-        // so a segment almost never crosses an extent boundary — but if the two
-        // ends land in different extents (non-contiguous LBAs), skip rather than
-        // emit a wrong span; the units there fall to the Unit Key (garble+drop),
-        // never a mis-decrypt.
-        let (Some(a), Some(b)) = (
-            clip_byte_to_lba(extents, start_byte),
-            clip_byte_to_lba(extents, end_byte - 1),
-        ) else {
-            continue;
-        };
-        if b >= a
-            && (b - a) as u64 == (end_byte - 1 - start_byte) / crate::consts::SECTOR_BYTES as u64
-        {
-            ranges.push((a, b + 1, index_to_key_idx(s.index)));
-        }
-    }
-    ranges
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    /// Build a table with the real on-disc layout: 8-byte header + N 16-byte
-    /// records. `recs` are `(index, start_spn, end_spn)`.
-    fn build_tbl(recs: &[(u16, u32, u32)]) -> Vec<u8> {
-        let mut v = Vec::new();
-        v.extend_from_slice(&0x0100_0000u32.to_be_bytes()); // type
-        v.extend_from_slice(&(recs.len() as u16).to_be_bytes()); // count
-        v.extend_from_slice(&(SEGMENT_RECORD_LEN as u16).to_be_bytes()); // record_size
-        for &(n, s, e) in recs {
-            v.extend_from_slice(&0x0100_0000u32.to_be_bytes()); // marker
-            v.extend_from_slice(&n.to_be_bytes());
-            v.extend_from_slice(&1u16.to_be_bytes()); // flag
-            v.extend_from_slice(&s.to_be_bytes());
-            v.extend_from_slice(&e.to_be_bytes());
-        }
-        v
-    }
-
-    #[test]
-    fn fmts_key_ranges_maps_segments_to_lba_by_index() {
-        use crate::disc::Extent;
-        // One big clip extent starting at LBA 1000. Clip byte B lives at
-        // LBA 1000 + B/2048.
-        let extents = vec![Extent {
-            start_lba: 1000,
-            sector_count: 1_000_000,
-        }];
-        // Two segments, indexes 5 and 7 (spn ranges as on a real disc).
-        let segs = vec![
-            Segment {
-                index: 5,
-                start_spn: 100,
-                end_spn: 199,
-            },
-            Segment {
-                index: 7,
-                start_spn: 10_000,
-                end_spn: 10_099,
-            },
-        ];
-        // Pool layout [base, idx1, idx2, …] → index N uses key slot N.
-        let ranges = fmts_key_ranges(&segs, &extents, &|v| v as usize);
-        assert_eq!(ranges.len(), 2, "one LBA range per segment");
-        // Segment 0: spn 100..=199 → clip bytes [19200, 38400) → sectors 9..=18
-        // → LBA 1009..1019, key index 5.
-        assert_eq!(ranges[0], (1009, 1019, 5));
-        // Segment 1: spn 10000..=10099 → bytes [1_920_000, 1_939_200) →
-        // sectors 937..=946 → LBA 1937..1947, key index 7.
-        assert_eq!(ranges[1], (1937, 1947, 7));
-
-        // The ranges drive a positive AacsKeyMap: an LBA in no range has no key.
-        let map = crate::decrypt::AacsKeyMap::from_ranges(ranges);
-        assert_eq!(map.key_idx_for(500), None, "outside any segment → no key");
-        assert_eq!(
-            map.key_idx_for(1012),
-            Some(5),
-            "inside index-5 segment → key 5"
-        );
-        assert_eq!(
-            map.key_idx_for(1940),
-            Some(7),
-            "inside index-7 segment → key 7"
-        );
-        assert_eq!(
-            map.key_idx_for(1019),
-            None,
-            "segment end is exclusive → no key"
-        );
-    }
-
-    #[test]
-    fn fmts_key_ranges_skips_inverted_segment_without_underflow() {
-        use crate::disc::Extent;
-        let extents = vec![Extent {
-            start_lba: 1000,
-            sector_count: 1_000_000,
-        }];
-        // start_spn == end_spn + 1: `end_byte - 1 - start_byte` would underflow.
-        // The record must be skipped rather than panic (debug) / wrap (release).
-        let segs = vec![Segment {
-            index: 5,
-            start_spn: 200,
-            end_spn: 199,
-        }];
-        let ranges = fmts_key_ranges(&segs, &extents, &|v| v as usize);
-        assert!(ranges.is_empty(), "inverted segment yields no range");
-    }
-
-    #[test]
-    fn clip_byte_to_lba_walks_extents() {
-        use crate::disc::Extent;
-        let extents = vec![
-            Extent {
-                start_lba: 100,
-                sector_count: 10,
-            }, // clip bytes [0, 20480)
-            Extent {
-                start_lba: 500,
-                sector_count: 10,
-            }, // clip bytes [20480, 40960)
-        ];
-        assert_eq!(clip_byte_to_lba(&extents, 0), Some(100));
-        assert_eq!(clip_byte_to_lba(&extents, 2048), Some(101));
-        assert_eq!(clip_byte_to_lba(&extents, 20480), Some(500)); // second extent
-        assert_eq!(clip_byte_to_lba(&extents, 22528), Some(501));
-        assert_eq!(clip_byte_to_lba(&extents, 40960), None); // past the clip
-    }
-
-    #[test]
-    fn parses_real_disc_layout() {
-        // First three records observed on retail 2.1: the variant
-        // field counts 1,2,3,… (it wraps at 32 further into the table — see
-        // `index_field_cycles_one_to_thirty_two`), segments are 2560 packets.
-        let tbl = build_tbl(&[
-            (1, 343680, 346239),
-            (2, 695616, 698175),
-            (3, 1051840, 1054399),
-        ]);
-        let segs = parse_individual_segments(&tbl).expect("parse");
-        assert_eq!(segs.len(), 3);
-        assert_eq!(segs[0].index, 1);
-        assert_eq!(segs[1].index, 2);
-        assert_eq!(segs[2].index, 3);
-        assert_eq!(segs[0].start_spn, 343680);
-        assert_eq!(segs[0].end_spn, 346239);
-        assert_eq!(segs[0].packet_count(), 2560);
-        assert_eq!(segs[0].byte_len(), 2560 * 192);
-        assert_eq!(segs[0].start_byte(), 343680 * 192);
-        assert!(segs[0].contains_spn(345000));
-        assert!(!segs[0].contains_spn(343679));
-        assert!(!segs[0].contains_spn(346240));
-    }
-
-    #[test]
-    fn rejects_wrong_record_size() {
-        let mut tbl = build_tbl(&[(1, 0, 10)]);
-        tbl[6..8].copy_from_slice(&20u16.to_be_bytes()); // record_size != 16
-        assert!(parse_individual_segments(&tbl).is_none());
-    }
-
-    #[test]
-    fn rejects_truncated_and_overrun() {
-        assert!(parse_individual_segments(&[0u8; 4]).is_none()); // < header
-        let mut tbl = build_tbl(&[(1, 0, 10)]);
-        tbl[4..6].copy_from_slice(&99u16.to_be_bytes()); // claims 99 recs, has 1
-        assert!(parse_individual_segments(&tbl).is_none());
-    }
-
-    #[test]
-    fn empty_table_is_empty_not_none() {
-        let tbl = build_tbl(&[]);
-        assert_eq!(parse_individual_segments(&tbl), Some(Vec::new()));
-    }
-
-    #[test]
-    fn packets_per_unit_is_thirty_two() {
-        // 6144-byte aligned unit / 192-byte source packet.
-        assert_eq!(PACKETS_PER_UNIT, 32);
-    }
-
-    #[test]
-    fn unit_inside_segment_routes_to_index() {
-        // A real first-record segment: packets [343680, 346239].
-        let segs = parse_individual_segments(&build_tbl(&[(1, 343680, 346239)])).unwrap();
-        // A unit sitting squarely inside: start at packet 344000 → byte 344000*192.
-        let off = 344000u64 * SOURCE_PACKET_LEN;
-        let hit = segment_for_unit(&segs, off).expect("inside the segment");
-        assert_eq!(hit.index, 1);
-    }
-
-    #[test]
-    fn index_field_cycles_one_to_thirty_two() {
-        // Reality on a retail 2.1 disc: field@4 is the index, cycling 1..=32 in file
-        // order (NOT a sequential segment id). Reproduce one-and-a-bit cycles.
-        let mut recs = Vec::new();
-        let mut spn = 1000u32;
-        for row in 0..2 {
-            for v in 1..=32u16 {
-                recs.push((v, spn, spn + 2559));
-                spn += 50_000; // ~one segment every ~67 MB
-            }
-            let _ = row;
-        }
-        let segs = parse_individual_segments(&build_tbl(&recs)).unwrap();
-        assert_eq!(segs.len(), 64);
-        assert_eq!(segs[31].index, 32); // end of first cycle
-        assert_eq!(segs[32].index, 1); // wraps, does not become 33
-        assert!(segs.iter().all(|s| (1..=32).contains(&s.index)));
-    }
-
-    #[test]
-    fn unit_outside_every_segment_is_unit_key_miss() {
-        let segs = parse_individual_segments(&build_tbl(&[(1, 343680, 346239)])).unwrap();
-        // A unit well before the segment is ordinary content → None (unit-key path).
-        let off = 1000u64 * SOURCE_PACKET_LEN;
-        assert!(segment_for_unit(&segs, off).is_none());
-    }
-
-    #[test]
-    fn unit_straddling_a_segment_edge_counts_as_forensic() {
-        // Segment starts at packet 100. A unit that ENDS just inside it (its 32
-        // packets straddle the boundary) must still route to the index key,
-        // because part of its ciphertext is forensic-encrypted.
-        let segs = parse_individual_segments(&build_tbl(&[(7, 100, 200)])).unwrap();
-        // Unit covering packets [80, 111]: overlaps [100,200] at the tail.
-        let off = 80u64 * SOURCE_PACKET_LEN;
-        let hit = segment_for_unit(&segs, off).expect("straddles the start edge");
-        assert_eq!(hit.index, 7);
-        // A unit ending exactly at packet 99 (offset s.t. last = 99) does NOT overlap.
-        let before = 68u64 * SOURCE_PACKET_LEN; // [68, 99]
-        assert!(segment_for_unit(&segs, before).is_none());
-    }
-
-    #[test]
-    fn no_segments_never_routes_to_index() {
-        // The 1.0 / 2.0 case: no forensic map, so every miss is a unit-key miss.
-        assert!(segment_for_unit(&[], lba_byte_offset(0)).is_none());
-        assert!(segment_for_unit(&[], lba_byte_offset(9_999_999)).is_none());
-    }
-
-    #[test]
-    fn lba_maps_to_the_packet_grid() {
-        // A unit is 3 sectors (6144 bytes) = 32 packets. Clip-relative LBA 3 is
-        // the second aligned unit, which starts at packet 32.
-        let off = lba_byte_offset(3);
-        assert_eq!(off / SOURCE_PACKET_LEN, 32);
-    }
-}

src/aacs/segment_key.rs

@@ -1,165 +0,0 @@
-//! AACS 2.1 FMTS forensic segment keys, `AACS/SegmentKeyNNNNN.tbl`.
-//!
-//! One file per CPS unit (`SegmentKey00001.tbl`, ...). It is the on-disc key
-//! store for the forensic variant segments mapped by [`super::segment`]. A
-//! device does not read a segment key directly. It derives a **16-bit variant
-//! selector** from the Media Key Variant chain (see [`super::variant`]) and uses
-//! that selector to index this table, which is how the device's position in the
-//! key tree decides which variant it can decrypt (the traitor-tracing link).
-//!
-//! Container format (confirmed against a retail AACS 2.1 disc):
-//! ```text
-//!   header (8 bytes):  u32 tag | u16 index_space | u16 record_size
-//!   record[index_space]  (record_size bytes each)
-//! ```
-//! On the reference disc: `index_space` = `0xffff` (the full 16-bit selector
-//! space, 65536 records), `record_size` = `0x0218` = 536. Total
-//! `8 + 65536 * 536 = 35,127,304` bytes, which matches the file exactly. Each
-//! record begins with an 8-byte sub-header, then 528 bytes of encrypted key
-//! material.
-//!
-//! **Not yet reversed:** the internal layout of a record's 528-byte payload, and
-//! how it maps onto the segments of [`super::segment`]. One numeric coincidence
-//! worth noting for whoever cracks it: the reference disc has 792 segments and
-//! `528 = 33 * 16`, with `792 = 24 * 33`, so `33` appears on both sides. Until
-//! the mapping and the key derivation are pinned, this module exposes only the
-//! confirmed container: locate the record for a given 16-bit selector.
-
-/// Bytes of the fixed file header.
-pub const HEADER_LEN: usize = 8;
-
-/// The on-disc segment-key table container. Borrows the file bytes; a record is
-/// looked up by the 16-bit variant selector.
-#[derive(Debug, Clone, Copy)]
-pub struct SegmentKeyTable<'a> {
-    data: &'a [u8],
-    /// Number of records (the selector index space, e.g. 65536).
-    count: usize,
-    /// Bytes per record (e.g. 536).
-    record_size: usize,
-}
-
-impl<'a> SegmentKeyTable<'a> {
-    /// Parse and validate the container header against the buffer length.
-    ///
-    /// Returns `None` when the buffer is too small, or the declared
-    /// `count * record_size` (plus header) does not match the buffer, so a
-    /// truncated or foreign table degrades to "no segment keys" rather than
-    /// handing back bogus records. `index_space` of `0xffff` is read as the full
-    /// 65536-entry space (a device selector is a full 16-bit value).
-    pub fn parse(data: &'a [u8]) -> Option<Self> {
-        if data.len() < HEADER_LEN {
-            return None;
-        }
-        let index_space = u16::from_be_bytes([data[4], data[5]]);
-        let record_size = u16::from_be_bytes([data[6], data[7]]) as usize;
-        // 0xffff means the full 16-bit selector space (65536 records).
-        let count = if index_space == 0xffff {
-            0x1_0000
-        } else {
-            index_space as usize
-        };
-        if record_size == 0 {
-            return None;
-        }
-        let body = count.checked_mul(record_size)?;
-        if HEADER_LEN.checked_add(body)? != data.len() {
-            return None;
-        }
-        Some(Self {
-            data,
-            count,
-            record_size,
-        })
-    }
-
-    /// Number of records (the selector index space).
-    pub fn record_count(&self) -> usize {
-        self.count
-    }
-
-    /// Bytes per record.
-    pub fn record_size(&self) -> usize {
-        self.record_size
-    }
-
-    /// The raw record for a 16-bit variant `selector`, including its 8-byte
-    /// sub-header. `None` if the selector is past the table (only possible when
-    /// `index_space` was not the full 16-bit space).
-    pub fn record(&self, selector: u16) -> Option<&'a [u8]> {
-        let idx = selector as usize;
-        if idx >= self.count {
-            return None;
-        }
-        let start = HEADER_LEN + idx * self.record_size;
-        self.data.get(start..start + self.record_size)
-    }
-
-    /// The encrypted key payload for a selector: the record with its 8-byte
-    /// sub-header stripped. The internal layout of these bytes is not yet
-    /// reversed (see module docs).
-    pub fn record_payload(&self, selector: u16) -> Option<&'a [u8]> {
-        self.record(selector).and_then(|r| r.get(HEADER_LEN..))
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    /// Build a container with `record_size` and the given `index_space`, filling
-    /// each record with a distinguishable byte so lookups can be checked.
-    fn build(index_space: u16, record_size: u16) -> Vec<u8> {
-        let count = if index_space == 0xffff {
-            0x1_0000
-        } else {
-            index_space as usize
-        };
-        let mut v = Vec::with_capacity(HEADER_LEN + count * record_size as usize);
-        v.extend_from_slice(&0x0100_0000u32.to_be_bytes()); // tag
-        v.extend_from_slice(&index_space.to_be_bytes());
-        v.extend_from_slice(&record_size.to_be_bytes());
-        for i in 0..count {
-            let mut rec = vec![(i & 0xff) as u8; record_size as usize];
-            // sub-header, as seen on disc
-            rec[..8].copy_from_slice(&[0x01, 0x00, 0x00, 0x00, 0x00, 0x20, 0x01, 0x02]);
-            v.extend_from_slice(&rec);
-        }
-        v
-    }
-
-    #[test]
-    fn parses_retail_container_geometry() {
-        // The real disc: 0xffff index space, 536-byte records, 35,127,304 total.
-        let data = build(0xffff, 536);
-        assert_eq!(
-            data.len(),
-            35_127_304,
-            "matches the retail file size exactly"
-        );
-        let t = SegmentKeyTable::parse(&data).expect("parse");
-        assert_eq!(t.record_count(), 65_536);
-        assert_eq!(t.record_size(), 536);
-        let rec = t.record(0x1234).expect("record");
-        assert_eq!(rec.len(), 536);
-        assert_eq!(&rec[..8], &[0x01, 0x00, 0x00, 0x00, 0x00, 0x20, 0x01, 0x02]);
-        assert_eq!(t.record_payload(0x1234).unwrap().len(), 528);
-    }
-
-    #[test]
-    fn small_index_space_bounds_lookups() {
-        let data = build(4, 32);
-        let t = SegmentKeyTable::parse(&data).expect("parse");
-        assert_eq!(t.record_count(), 4);
-        assert!(t.record(3).is_some());
-        assert!(t.record(4).is_none(), "selector past the table is None");
-    }
-
-    #[test]
-    fn rejects_size_mismatch_and_truncation() {
-        assert!(SegmentKeyTable::parse(&[0u8; 4]).is_none());
-        let mut data = build(4, 32);
-        data.truncate(data.len() - 1); // body no longer matches header
-        assert!(SegmentKeyTable::parse(&data).is_none());
-    }
-}

src/aacs/trace.rs

@@ -1,144 +0,0 @@
-//! Structured resolution trace — what the unlock + key-resolution attempt did.
-//!
-//! No user-facing English. Every step's STATE is a typed enum variant;
-//! applications RENDER these into localized text (the library never does). This
-//! module only DEFINES the shape and is wired through the resolve/handshake
-//! return path far enough to compile.
-//!
-//! The `who` of each step is the source's `label()` / unlocker's `name()` — a
-//! stable identifier string (a NAME, like a codec id, NOT user-facing prose),
-//! carried verbatim so an app renderer never has to match an enum back to a name
-//! it already has. Only the OUTCOME / path enums are structured states the app
-//! maps to i18n English.
-
-/// The full trace of a resolution attempt: the unlock phase, then the
-/// key-resolution phase.
-#[derive(Debug, Clone, PartialEq, Default)]
-pub struct ResolutionTrace {
-    /// One step per unlocker consulted, in consultation order.
-    pub unlock: Vec<UnlockStep>,
-    /// One step per key source consulted, in consultation order.
-    pub keys: Vec<KeyStep>,
-}
-
-impl ResolutionTrace {
-    /// An empty trace (no steps recorded).
-    pub fn new() -> Self {
-        Self::default()
-    }
-}
-
-// ── Unlock phase ────────────────────────────────────────────────────────────
-
-/// One unlocker's contribution to the unlock phase. `who` is the unlocker's
-/// `name()` (a stable, product-neutral identifier), carried verbatim.
-#[derive(Debug, Clone, PartialEq)]
-pub struct UnlockStep {
-    pub who: String,
-    pub outcome: UnlockOutcome,
-}
-
-/// What an unlocker did.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum UnlockOutcome {
-    /// The drive was unlocked (or already usable) and a VID is available.
-    Unlocked,
-    /// This unlocker cannot unlock this drive's firmware.
-    FirmwareNotUnlockable,
-    /// No non-revoked host cert was usable for the auth attempt. `mkb` is the
-    /// disc MKB generation when known.
-    NoUsableHostCert { mkb: Option<u32> },
-    /// Every available host cert was revoked on this drive's HRL. `mkb` is the
-    /// disc MKB generation when known.
-    CertRevoked { mkb: Option<u32> },
-    /// The drive rejected the auth handshake (non-revocation rejection / wedge).
-    HandshakeRejected,
-    /// Auth succeeded (or was skipped) but the Volume ID could not be read.
-    VidUnavailable,
-}
-
-// ── Key-resolution phase ────────────────────────────────────────────────────
-
-/// One key source's contribution to the key-resolution phase, including the
-/// derivation path it walked. `who` is the source's `label()` (a stable
-/// identifier, e.g. `"keydb"` / `"online"`), carried verbatim.
-#[derive(Debug, Clone, PartialEq)]
-pub struct KeyStep {
-    pub who: String,
-    pub path: Vec<KeyNode>,
-    pub outcome: KeyOutcome,
-}
-
-/// A node on the derivation path a source walked. Ordered as encountered; not
-/// every path hits every node.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum KeyNode {
-    /// The source matched this disc (by hash / VID).
-    MatchedDisc,
-    /// The source had no entry for this disc.
-    NoEntry,
-    /// Pre-decrypted unit keys were found.
-    FoundUnitKeys,
-    /// A VUK was found.
-    FoundVuk,
-    /// A Media Key was found.
-    FoundMediaKey,
-    /// A VID is required to proceed.
-    NeedVid,
-    /// The VID came from the unlock phase.
-    VidFromUnlock,
-    /// The VID came from the keydb entry.
-    VidFromKeydb,
-    /// No VID was available.
-    NoVid,
-    /// A VUK was derived (from MK + VID).
-    DerivedVuk,
-    /// Unit keys were derived (from VUK).
-    DerivedUnitKeys,
-}
-
-/// The terminal outcome of a source's resolution attempt.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum KeyOutcome {
-    /// Usable unit keys were produced.
-    Resolved,
-    /// Derivation material existed but no VID was available to finish.
-    MissingVid,
-    /// No usable key from this source.
-    NoKey,
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    /// The trace types are constructible, derive the required traits, and an
-    /// empty trace round-trips. Pins the structural contract apps build against.
-    #[test]
-    fn trace_is_constructible_and_comparable() {
-        let t = ResolutionTrace {
-            unlock: vec![UnlockStep {
-                who: "AACS cert".to_string(),
-                outcome: UnlockOutcome::NoUsableHostCert { mkb: Some(68) },
-            }],
-            keys: vec![KeyStep {
-                who: "keydb".to_string(),
-                path: vec![
-                    KeyNode::MatchedDisc,
-                    KeyNode::FoundVuk,
-                    KeyNode::DerivedUnitKeys,
-                ],
-                outcome: KeyOutcome::Resolved,
-            }],
-        };
-        // Clone + PartialEq (derive contract the renderers rely on).
-        assert_eq!(t.clone(), t);
-        // `who` is the source's name carried verbatim.
-        assert_eq!(t.keys[0].who, "keydb");
-        assert_eq!(t.unlock[0].who, "AACS cert");
-        // Default / new is empty.
-        assert_eq!(ResolutionTrace::new(), ResolutionTrace::default());
-        assert!(ResolutionTrace::new().unlock.is_empty());
-        assert!(ResolutionTrace::new().keys.is_empty());
-    }
-}

src/aacs/types.rs

@@ -1,338 +0,0 @@
-//! AACS primitive types shared across the resolve chain.
-//!
-//! These structs describe AACS key material (device keys, host
-//! certificates, per-disc entries). They carry no parsing logic — the
-//! keydb.cfg format lives in the `freemkv-keysources` crate. libfreemkv
-//! owns only the crypto and these value types that flow through it.
-
-/// A device key for MKB subset-difference tree processing.
-#[derive(Clone)]
-pub struct DeviceKey {
-    pub key: [u8; 16],
-    pub node: u16,
-    pub uv: u32,
-    pub u_mask_shift: u8,
-}
-
-/// Host certificate + private key for AACS SCSI authentication.
-#[derive(Clone)]
-pub struct HostCert {
-    /// AACS 1.0: 20 bytes. AACS 2.0: 32 bytes.
-    pub private_key: [u8; 20],
-    /// AACS 1.0: 92 bytes. AACS 2.0: 132 bytes.
-    pub certificate: Vec<u8>,
-    /// AACS 2.0 host private key (P-256, 32 bytes). None for AACS 1.0 only.
-    pub private_key_v2: Option<[u8; 32]>,
-    /// AACS 2.0 host certificate (type 0x11). None for AACS 1.0 only.
-    pub certificate_v2: Option<Vec<u8>>,
-}
-
-/// Volume ID (16 bytes) — read from the disc via the SCSI handshake / OEM path.
-#[derive(Clone, Copy, PartialEq, Eq)]
-pub struct Vid(pub [u8; 16]);
-
-/// Media Key (Km, 16 bytes) — the MKB-scoped key derived from device keys.
-#[derive(Clone, Copy, PartialEq, Eq)]
-pub struct MediaKey(pub [u8; 16]);
-
-/// Volume Unique Key (VUK / Kvu, 16 bytes) — derived from `MediaKey` + `Vid`,
-/// decrypts the per-disc encrypted title keys in `Unit_Key_RO.inf`.
-#[derive(Clone, Copy, PartialEq, Eq)]
-pub struct Vuk(pub [u8; 16]);
-
-/// Processing Key (Kp, 16 bytes) — an MKB Subset-Difference key that yields the
-/// Media Key. A leaked/precomputed PK in the keydb, or the intermediate PK a
-/// device-key walk derives at its matching SD node.
-#[derive(Clone, Copy, PartialEq, Eq)]
-pub struct ProcessingKey(pub [u8; 16]);
-
-/// One decrypted per-CPS-unit AACS title key.
-///
-/// `idx` is the POSITIONAL index of the encrypted title key within the slice
-/// handed to the VUK→UK step (i.e. its order in `Unit_Key_RO.inf`'s key-storage
-/// area). The CPS-unit *number* association is a higher-level concern owned by
-/// [`super::inf::parse_unit_key_ro`], which pairs each positional key with its
-/// declared CPS unit; this primitive only does the AES, so it surfaces position.
-#[derive(Clone, Copy, PartialEq, Eq)]
-pub struct UnitKey {
-    pub idx: u32,
-    pub key: [u8; 16],
-    /// AACS 2.1 (FMTS) forensic **index** tag (see [`crate::aacs::segment`]).
-    ///
-    /// `0` = ordinary (non-forensic) content — the value for every 1.0 / 2.0
-    /// key and for the bulk of a 2.1 title. `1..=32` = a forensic index key that
-    /// decrypts the `IndividualSegment.tbl` segments tagged with that same index.
-    /// This is the per-segment index (1..32), NOT the AACS 2.1 Media Key Variant
-    /// (the 65536-value device selector), which is a separate MKB-layer concern.
-    pub index_number: u8,
-}
-
-impl UnitKey {
-    /// An ordinary (non-forensic) unit key: `index_number == 0`. The value
-    /// for every AACS 1.0 / 2.0 key and the bulk of a 2.1 title.
-    pub const fn new(idx: u32, key: [u8; 16]) -> Self {
-        Self {
-            idx,
-            key,
-            index_number: 0,
-        }
-    }
-
-    /// A forensic index key: `index_number` in `1..=32`, decrypting the
-    /// `IndividualSegment.tbl` segments tagged with that index.
-    pub const fn forensic(idx: u32, key: [u8; 16], index_number: u8) -> Self {
-        Self {
-            idx,
-            key,
-            index_number,
-        }
-    }
-
-    /// Whether this key decrypts ordinary (non-forensic) content (index 0).
-    pub const fn is_default_index(&self) -> bool {
-        self.index_number == 0
-    }
-}
-
-/// A per-disc entry from the key database.
-#[derive(Clone)]
-pub struct DiscEntry {
-    /// Disc hash (20 bytes, hex)
-    pub disc_hash: String,
-    /// Disc title
-    pub title: String,
-    /// Media Key (16 bytes) — from MKB processing
-    pub media_key: Option<[u8; 16]>,
-    /// Disc ID (16 bytes)
-    pub disc_id: Option<[u8; 16]>,
-    /// Volume Unique Key (16 bytes) — decrypts title keys
-    pub vuk: Option<[u8; 16]>,
-    /// Unit keys (title keys) indexed by CPS unit number
-    pub unit_keys: Vec<(u32, [u8; 16])>,
-}
-
-// ── Redacting `Debug` impls ──────────────────────────────────────────────────
-//
-// Every type above carries AACS secret material (device keys, host PRIVATE keys,
-// media/volume/processing/unit keys). `#[derive(Debug)]` would print those bytes
-// verbatim, so a stray `debug!("{:?}", …)` or a panic message would leak the
-// keys. These hand-written impls print only NON-secret shape (presence, lengths,
-// tree coordinates, indices) — never key bytes. `decrypt::DecryptKeys` follows
-// the same policy by omitting `Debug` entirely; here we keep `Debug` because
-// these are `PartialEq`/`Eq` value types used in `assert_eq!` and nested inside
-// other `#[derive(Debug)]` structs, so the trait must exist — just not leak.
-// Guarded by `redaction_tests` below.
-
-impl std::fmt::Debug for DeviceKey {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("DeviceKey")
-            .field("key", &"<redacted>")
-            .field("node", &self.node)
-            .field("uv", &self.uv)
-            .field("u_mask_shift", &self.u_mask_shift)
-            .finish()
-    }
-}
-
-impl std::fmt::Debug for HostCert {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("HostCert")
-            .field("private_key", &"<redacted>")
-            .field("certificate_len", &self.certificate.len())
-            .field("private_key_v2", &self.private_key_v2.map(|_| "<redacted>"))
-            .field(
-                "certificate_v2_len",
-                &self.certificate_v2.as_ref().map(|c| c.len()),
-            )
-            .finish()
-    }
-}
-
-impl std::fmt::Debug for Vid {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.write_str("Vid(<redacted>)")
-    }
-}
-
-impl std::fmt::Debug for MediaKey {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.write_str("MediaKey(<redacted>)")
-    }
-}
-
-impl std::fmt::Debug for Vuk {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.write_str("Vuk(<redacted>)")
-    }
-}
-
-impl std::fmt::Debug for ProcessingKey {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.write_str("ProcessingKey(<redacted>)")
-    }
-}
-
-impl std::fmt::Debug for UnitKey {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("UnitKey")
-            .field("idx", &self.idx)
-            .field("key", &"<redacted>")
-            .field("index_number", &self.index_number)
-            .finish()
-    }
-}
-
-impl std::fmt::Debug for DiscEntry {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("DiscEntry")
-            .field("disc_hash", &self.disc_hash)
-            .field("title", &self.title)
-            .field("media_key", &self.media_key.map(|_| "<redacted>"))
-            .field("disc_id", &self.disc_id.map(|_| "<redacted>"))
-            .field("vuk", &self.vuk.map(|_| "<redacted>"))
-            .field("unit_keys_len", &self.unit_keys.len())
-            .finish()
-    }
-}
-
-#[cfg(test)]
-mod unit_key_tests {
-    use super::*;
-
-    /// `is_default_index` is the public predicate that separates ordinary
-    /// (index-0) content keys from FMTS forensic index keys ([`UnitKey`] docs;
-    /// AACS 2.1 `IndividualSegment.tbl` tagging). A body answering `true` for
-    /// everything would present a forensic index key as an ordinary content
-    /// key — the caller would decrypt the bulk of the title with a key that
-    /// only opens 1/32nd of it; answering `false` for everything would hide
-    /// every ordinary key.
-    ///
-    /// Pinned against the two NAMED constructors, which are the contract:
-    /// [`UnitKey::new`] builds the ordinary key, [`UnitKey::forensic`] builds
-    /// an index key for `1..=32`.
-    #[test]
-    fn is_default_index_separates_the_two_constructors() {
-        let ordinary = UnitKey::new(0, [0xAA; 16]);
-        assert!(
-            ordinary.is_default_index(),
-            "UnitKey::new builds the ordinary (index-0) key"
-        );
-
-        // Every forensic index the spec allows must be reported as NOT default.
-        for n in 1u8..=32 {
-            let k = UnitKey::forensic(0, [0xAA; 16], n);
-            assert!(
-                !k.is_default_index(),
-                "UnitKey::forensic({n}) is an index key, not the default key"
-            );
-        }
-    }
-
-    /// The predicate must agree with the one consumer of `index_number` in the
-    /// crate: [`crate::aacs::index_select::resolve_disc_index`] resolves the
-    /// disc's forensic index from exactly the keys that are NOT default. If
-    /// the two disagree, a disc resolves an index whose key the rest of the
-    /// pipeline treats as ordinary (or vice versa).
-    #[test]
-    fn is_default_index_agrees_with_the_forensic_index_resolver() {
-        use crate::aacs::index_select::resolve_disc_index;
-
-        let keys = [
-            UnitKey::new(0, [0x11; 16]),
-            UnitKey::forensic(1, [0x22; 16], 7),
-        ];
-        assert_eq!(
-            resolve_disc_index(&keys),
-            Some(7),
-            "sanity: the resolver picks the forensic key's index"
-        );
-
-        let non_default: Vec<u8> = keys
-            .iter()
-            .filter(|k| !k.is_default_index())
-            .map(|k| k.index_number)
-            .collect();
-        assert_eq!(
-            non_default,
-            vec![7],
-            "exactly the key the resolver picked must be non-default"
-        );
-
-        // An all-ordinary key set resolves no index, and every key must report
-        // itself default.
-        let plain = [UnitKey::new(0, [0x11; 16]), UnitKey::new(1, [0x22; 16])];
-        assert_eq!(resolve_disc_index(&plain), None);
-        assert!(plain.iter().all(|k| k.is_default_index()));
-    }
-}
-
-#[cfg(test)]
-mod redaction_tests {
-    use super::*;
-
-    // Sentinel key byte 0xD5 = decimal 213. A derived `Debug` prints `[u8;N]`
-    // as decimal, so a leaked key surfaces the substring "213"; the redacting
-    // impls must not. No non-secret field below is 213, so "213" appearing means
-    // key bytes leaked. Each type must also carry a "redacted" marker (or omit
-    // the secret entirely) so re-adding `#[derive(Debug)]` fails this test.
-    const S: u8 = 0xD5;
-
-    fn assert_redacted(what: &str, dbg: &str) {
-        assert!(
-            !dbg.contains("213"),
-            "{what}: Debug leaked key bytes (found decimal 213): {dbg}"
-        );
-        assert!(
-            dbg.contains("redacted"),
-            "{what}: Debug missing redaction marker: {dbg}"
-        );
-    }
-
-    #[test]
-    fn device_key_debug_is_redacted() {
-        let d = DeviceKey {
-            key: [S; 16],
-            node: 1,
-            uv: 2,
-            u_mask_shift: 3,
-        };
-        assert_redacted("DeviceKey", &format!("{d:?}"));
-    }
-
-    #[test]
-    fn host_cert_debug_is_redacted() {
-        let h = HostCert {
-            private_key: [S; 20],
-            certificate: vec![0u8; 92],
-            private_key_v2: Some([S; 32]),
-            certificate_v2: None,
-        };
-        assert_redacted("HostCert", &format!("{h:?}"));
-    }
-
-    #[test]
-    fn newtype_keys_debug_is_redacted() {
-        assert_redacted("Vid", &format!("{:?}", Vid([S; 16])));
-        assert_redacted("MediaKey", &format!("{:?}", MediaKey([S; 16])));
-        assert_redacted("Vuk", &format!("{:?}", Vuk([S; 16])));
-        assert_redacted("ProcessingKey", &format!("{:?}", ProcessingKey([S; 16])));
-    }
-
-    #[test]
-    fn unit_key_debug_is_redacted() {
-        assert_redacted("UnitKey", &format!("{:?}", UnitKey::new(0, [S; 16])));
-    }
-
-    #[test]
-    fn disc_entry_debug_is_redacted() {
-        let e = DiscEntry {
-            disc_hash: "0xAA".into(),
-            title: "T".into(),
-            media_key: Some([S; 16]),
-            disc_id: Some([S; 16]),
-            vuk: Some([S; 16]),
-            unit_keys: vec![(1, [S; 16])],
-        };
-        assert_redacted("DiscEntry", &format!("{e:?}"));
-    }
-}

src/aacs/variants.rs

@@ -0,0 +1,679 @@
+//! AACS Media Key Variant chain.
+//!
+//! On AACS 2.1 the Media Key derivation gains a second stage on top of
+//! the classical subset-difference walk. The classical walk yields a
+//! Media Key Precursor (Kmp) rather than the final Media Key; the
+//! Precursor combines with disc-supplied Variant Key Data (VKD) and an
+//! integrator-supplied Key Correction Data (KCD) constant to produce
+//! the Media Key.
+//!
+//! This module is wiring only — `resolve_keys` is not aware of it. The
+//! entry point is [`derive_media_key_variant`]. The Variant scheme is
+//! detected via the new MKB record types `0x82` (Encrypted Media Key
+//! Variant Data + Variant Key Data) and `0x83` (Variant Number). When
+//! a disc carries neither, callers should fall back to the classical
+//! single-stage derivation in [`super::keys`].
+//!
+//! The chain follows the published spec:
+//!
+//! ```text
+//! Kmp     = AES-128D(Kp, C) XOR uv
+//! Kpnew   = Kmp XOR KCD
+//! Kvn     = AES-G(Kp, Nonce) & 0xFFFF   (low 16 bits, BE)
+//! VKD_idx = Kvn XOR VARIANTS[uv]
+//! VKD     = vkd_table[VKD_idx * 16 .. +16]
+//! Km      = AES-128D(Kpnew, VKD) XOR uv
+//! ```
+//!
+//! Two condition bits on `Kmp[15]` route off the hardcoded-KCD path
+//! (Soft Correction and Online Challenge). The chain refuses to run in
+//! either case — callers must handle those modes out of band.
+
+use super::decrypt::aes_ecb_decrypt;
+use super::keydb::DeviceKey;
+
+// ── Public constants ──────────────────────────────────────────────────────
+
+/// Placeholder Key Correction Data. Sixteen zero bytes.
+///
+/// Integrators MUST supply a non-placeholder KCD via the `kcd` argument
+/// to [`derive_media_key_variant`]; the chain refuses to operate when
+/// the supplied KCD compares equal to this placeholder.
+pub const KEY_CORRECTION_DATA_PLACEHOLDER: [u8; 16] = [0u8; 16];
+
+// ── MKB record walking ────────────────────────────────────────────────────
+
+/// A single MKB record produced by [`walk_mkb`].
+#[derive(Debug, Clone)]
+pub struct MkbRecord {
+    /// Byte offset of the record within the MKB.
+    pub offset: usize,
+    /// Record type byte.
+    pub rec_type: u8,
+    /// Record length in bytes (includes the 4-byte header).
+    pub rec_len: usize,
+    /// Record body (the bytes after the 4-byte header).
+    pub body: Vec<u8>,
+}
+
+/// Walk an MKB into a flat list of records.
+///
+/// MKB record framing per AACS: 1 byte type, 3 bytes BE length
+/// INCLUDING the 4-byte header, followed by payload. The walker stops
+/// at the first `(type=0, len=0)` end marker or at end of buffer.
+pub fn walk_mkb(mkb: &[u8]) -> Vec<MkbRecord> {
+    let mut out = Vec::new();
+    let mut pos = 0;
+    while pos + 4 <= mkb.len() {
+        let rec_type = mkb[pos];
+        let rec_len = ((mkb[pos + 1] as usize) << 16)
+            | ((mkb[pos + 2] as usize) << 8)
+            | (mkb[pos + 3] as usize);
+        if rec_type == 0 && rec_len == 0 {
+            break;
+        }
+        if rec_len < 4 || pos + rec_len > mkb.len() {
+            break;
+        }
+        let body = mkb[pos + 4..pos + rec_len].to_vec();
+        out.push(MkbRecord {
+            offset: pos,
+            rec_type,
+            rec_len,
+            body,
+        });
+        pos += rec_len;
+    }
+    out
+}
+
+/// True iff `records` contains at least one Media Key Variant record
+/// (type `0x82` or `0x83`).
+pub fn is_variant_mkb(records: &[MkbRecord]) -> bool {
+    records.iter().any(|r| matches!(r.rec_type, 0x82 | 0x83))
+}
+
+/// Body of the Encrypted Media Key Variant Data record (type `0x82`).
+pub fn variant_data_record(records: &[MkbRecord]) -> Option<&[u8]> {
+    records
+        .iter()
+        .find(|r| r.rec_type == 0x82)
+        .map(|r| r.body.as_slice())
+}
+
+/// 16-byte Nonce from the Variant Number record (type `0x83`). Returns
+/// the first 16 bytes of the body.
+pub fn variant_nonce(records: &[MkbRecord]) -> Option<[u8; 16]> {
+    let r = records.iter().find(|r| r.rec_type == 0x83)?;
+    if r.body.len() < 16 {
+        return None;
+    }
+    let mut out = [0u8; 16];
+    out.copy_from_slice(&r.body[..16]);
+    Some(out)
+}
+
+/// Body of the Variant Key Data record. Returns the first `0x82` body
+/// that is a non-empty multiple of 16 bytes.
+pub fn variant_key_data(records: &[MkbRecord]) -> Option<&[u8]> {
+    records
+        .iter()
+        .find(|r| r.rec_type == 0x82 && !r.body.is_empty() && r.body.len() % 16 == 0)
+        .map(|r| r.body.as_slice())
+}
+
+// ── AES-G ────────────────────────────────────────────────────────────────
+
+/// AES-G(x1, x2) = AES-128D(x1, x2) XOR x2.
+///
+/// The Media Key Variant chain uses AES-G to derive both the variant
+/// number (`Kvn = AES-G(Kp, Nonce)`) and the Volume Unique Key
+/// (`Kvu = AES-G(Km, VID)`). See [`super::keys::derive_vuk`] for the
+/// classical VUK form — the math is identical, this exposes it as a
+/// neutral primitive for the variant chain.
+fn aes_g(x1: &[u8; 16], x2: &[u8; 16]) -> [u8; 16] {
+    let mut out = aes_ecb_decrypt(x1, x2);
+    for i in 0..16 {
+        out[i] ^= x2[i];
+    }
+    out
+}
+
+// ── Subset-difference walk that exposes (Kp, uv) ──────────────────────────
+
+/// AES-G3 seed register initial value.
+const AESG3_SEED: [u8; 16] = [
+    0x7B, 0x10, 0x3C, 0x5D, 0xCB, 0x08, 0xC4, 0xE5, 0x1A, 0x27, 0xB0, 0x17, 0x99, 0x05, 0x3B, 0xD9,
+];
+
+/// AES-G3 single step: AES-G against the seed register at offset `inc`.
+fn aesg3_step(key: &[u8; 16], inc: u8) -> [u8; 16] {
+    let mut seed = AESG3_SEED;
+    seed[15] = seed[15].wrapping_add(inc);
+    aes_g(key, &seed)
+}
+
+fn calc_v_mask(uv: u32) -> u32 {
+    let mut v_mask: u32 = 0xFFFF_FFFF;
+    while (uv & !v_mask) == 0 && v_mask != 0 {
+        v_mask <<= 1;
+    }
+    v_mask
+}
+
+fn calc_pk_from_dk(dk: &[u8; 16], uv: u32, v_mask: u32, dev_key_v_mask: u32) -> [u8; 16] {
+    let mut left_child = aesg3_step(dk, 0);
+    let mut pk = aesg3_step(dk, 1);
+    let mut right_child = aesg3_step(dk, 2);
+    let mut current_v_mask = dev_key_v_mask;
+
+    while current_v_mask != v_mask {
+        let mut bit_pos: i32 = -1;
+        for i in (0..32).rev() {
+            if (current_v_mask & (1u32 << i)) == 0 {
+                bit_pos = i;
+                break;
+            }
+        }
+
+        let curr_key = if bit_pos < 0 || (uv & (1u32 << bit_pos as u32)) == 0 {
+            left_child
+        } else {
+            right_child
+        };
+
+        left_child = aesg3_step(&curr_key, 0);
+        pk = aesg3_step(&curr_key, 1);
+        right_child = aesg3_step(&curr_key, 2);
+
+        current_v_mask = ((current_v_mask as i32) >> 1) as u32;
+    }
+
+    pk
+}
+
+/// Outcome of a subset-difference walk against an MKB. Carries the
+/// processing key and the matching `uv` slot — both needed as inputs
+/// to the variant chain.
+#[derive(Debug, Clone, Copy)]
+pub struct ProcessingKeyMatch {
+    /// Processing Key.
+    pub kp: [u8; 16],
+    /// Subset-difference node number that matched.
+    pub uv: u32,
+    /// 16-byte cvalue that the matched uv selected.
+    pub cvalue: [u8; 16],
+    /// Index of the matching cvalue within the cvalues record.
+    pub cvalue_index: usize,
+}
+
+fn mkb_find_body(records: &[MkbRecord], rec_type: u8) -> Option<&[u8]> {
+    records
+        .iter()
+        .find(|r| r.rec_type == rec_type && !r.body.is_empty())
+        .map(|r| r.body.as_slice())
+}
+
+fn mkb_find_mk_dv(records: &[MkbRecord]) -> Option<[u8; 16]> {
+    let r = records
+        .iter()
+        .find(|r| (r.rec_type == 0x81 || r.rec_type == 0x86) && r.body.len() >= 16)?;
+    let mut out = [0u8; 16];
+    out.copy_from_slice(&r.body[..16]);
+    Some(out)
+}
+
+/// Walk an MKB and return the first `(Kp, uv, cvalue)` that
+/// `device_keys` covers. Returns `None` if no DK walks any uv.
+pub fn walk_processing_key(
+    records: &[MkbRecord],
+    device_keys: &[DeviceKey],
+) -> Option<ProcessingKeyMatch> {
+    let mk_dv = mkb_find_mk_dv(records)?;
+    let uvs = mkb_find_body(records, 0x04)?;
+    let cvalues = mkb_find_body(records, 0x07).or_else(|| mkb_find_body(records, 0x05))?;
+
+    let num_uvs = uvs
+        .chunks(5)
+        .take_while(|c| c.len() == 5 && (c[0] & 0xC0) == 0)
+        .count();
+
+    for dk in device_keys {
+        let device_number = dk.node as u32;
+
+        for uvs_idx in 0..num_uvs {
+            let p_uv = &uvs[1 + 5 * uvs_idx..];
+            let u_mask_shift = uvs[5 * uvs_idx];
+
+            if u_mask_shift & 0xC0 != 0 {
+                break;
+            }
+
+            let uv = u32::from_be_bytes([p_uv[0], p_uv[1], p_uv[2], p_uv[3]]);
+            if uv == 0 {
+                continue;
+            }
+
+            let u_mask: u32 = 0xFFFF_FFFFu32.wrapping_shl(u_mask_shift as u32);
+            let v_mask = calc_v_mask(uv);
+
+            if ((device_number & u_mask) == (uv & u_mask))
+                && ((device_number & v_mask) != (uv & v_mask))
+            {
+                let dev_key_v_mask = calc_v_mask(dk.uv);
+                let dev_key_u_mask: u32 = 0xFFFF_FFFFu32.wrapping_shl(dk.u_mask_shift as u32);
+
+                if u_mask == dev_key_u_mask && (uv & dev_key_v_mask) == (dk.uv & dev_key_v_mask) {
+                    let pk = calc_pk_from_dk(&dk.key, uv, v_mask, dev_key_v_mask);
+
+                    if uvs_idx >= cvalues.len() / 16 {
+                        continue;
+                    }
+                    let mut cv = [0u8; 16];
+                    cv.copy_from_slice(&cvalues[uvs_idx * 16..(uvs_idx + 1) * 16]);
+
+                    // Validate: AES-D(Kp, cv), XOR uv into low 4 bytes,
+                    // then AES-D(.., mk_dv) must reveal the verify magic.
+                    let mut km_candidate = aes_ecb_decrypt(&pk, &cv);
+                    let uv_bytes = uv.to_be_bytes();
+                    for i in 0..4 {
+                        km_candidate[12 + i] ^= uv_bytes[i];
+                    }
+                    let dec_vd = aes_ecb_decrypt(&km_candidate, &mk_dv);
+                    const VERIFY_MAGIC: [u8; 8] = [0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF];
+                    // On a classical (non-variant) MKB this magic must
+                    // match. On a variant MKB it won't — `km_candidate`
+                    // is really Kmp and the magic check is moot. We
+                    // still gate the walk on cvalue indexing being
+                    // sane; the chain itself enforces the variant
+                    // semantics downstream.
+                    let classical_ok = dec_vd[..8] == VERIFY_MAGIC;
+                    let variant_present = is_variant_mkb(records);
+                    if !(classical_ok || variant_present) {
+                        continue;
+                    }
+
+                    return Some(ProcessingKeyMatch {
+                        kp: pk,
+                        uv,
+                        cvalue: cv,
+                        cvalue_index: uvs_idx,
+                    });
+                }
+            }
+        }
+    }
+    None
+}
+
+// ── Error reporting ───────────────────────────────────────────────────────
+
+/// Outcome of [`derive_media_key_variant`] when the chain cannot
+/// produce a Media Key. Every variant is a classification only — no
+/// strings, no Display impl beyond the error code.
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+pub enum MediaKeyVariantError {
+    /// MKB carries no Variant records. Caller should fall back to the
+    /// classical single-stage derivation.
+    NotVariantMkb,
+    /// MKB is missing a required record (mk_dv, subset-difference,
+    /// cvalues, variant data, or variant nonce).
+    MkbIncomplete,
+    /// `device_keys` did not cover any uv slot in this MKB.
+    ProcessingKeyUnavailable,
+    /// `Kmp[15]` carries bit `0x02`: the soft-correction path applies
+    /// for this Precursor. Out of scope for the hardcoded-KCD chain.
+    SoftCorrectionRequired,
+    /// `Kmp[15]` carries bit `0x04`: the online-challenge path applies
+    /// for this Precursor. Out of scope for the hardcoded-KCD chain.
+    OnlineChallengeRequired,
+    /// Supplied KCD equals [`KEY_CORRECTION_DATA_PLACEHOLDER`]. The
+    /// derivation refuses to run with the all-zero placeholder.
+    KcdNotProvided,
+    /// `VARIANTS[uv]` lookup for the matched uv is not implemented.
+    VariantsTableUnavailable,
+    /// VKD index resolved out of the supplied `vkd_table`.
+    VkdIndexOutOfRange,
+}
+
+impl std::fmt::Display for MediaKeyVariantError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let code: u16 = match self {
+            MediaKeyVariantError::NotVariantMkb => 7100,
+            MediaKeyVariantError::MkbIncomplete => 7101,
+            MediaKeyVariantError::ProcessingKeyUnavailable => 7102,
+            MediaKeyVariantError::SoftCorrectionRequired => 7103,
+            MediaKeyVariantError::OnlineChallengeRequired => 7104,
+            MediaKeyVariantError::KcdNotProvided => 7105,
+            MediaKeyVariantError::VariantsTableUnavailable => 7106,
+            MediaKeyVariantError::VkdIndexOutOfRange => 7107,
+        };
+        write!(f, "E{code}")
+    }
+}
+
+impl std::error::Error for MediaKeyVariantError {}
+
+// ── Chain ─────────────────────────────────────────────────────────────────
+
+/// Look up `VARIANTS[uv]` for the matched uv. The byte layout of the
+/// per-uv slot in the Variant Number record is undocumented and is
+/// disc-specific; this helper returns `None` until a Variant disc is
+/// available to fix the layout against.
+fn variants_for_uv(_records: &[MkbRecord], _uv_index: usize) -> Option<u16> {
+    None
+}
+
+/// Run the Media Key Variant chain on an MKB.
+///
+/// Inputs:
+///
+/// - `mkb_records`  : MKB pre-walked via [`walk_mkb`].
+/// - `device_keys`  : pool of device keys; the chain runs against the
+///   first uv slot any DK covers.
+/// - `kcd`          : integrator-supplied Key Correction Data. Must not
+///   equal [`KEY_CORRECTION_DATA_PLACEHOLDER`].
+/// - `vid`          : 16-byte Volume ID for the disc. Used to derive
+///   the final VUK alongside the Media Key.
+///
+/// Returns `(Km, Kvu)` on success.
+pub fn derive_media_key_variant(
+    mkb_records: &[MkbRecord],
+    device_keys: &[DeviceKey],
+    kcd: &[u8; 16],
+    vid: &[u8; 16],
+) -> Result<([u8; 16], [u8; 16]), MediaKeyVariantError> {
+    if !is_variant_mkb(mkb_records) {
+        return Err(MediaKeyVariantError::NotVariantMkb);
+    }
+
+    let pkm = walk_processing_key(mkb_records, device_keys)
+        .ok_or(MediaKeyVariantError::ProcessingKeyUnavailable)?;
+
+    let nonce = variant_nonce(mkb_records).ok_or(MediaKeyVariantError::MkbIncomplete)?;
+    let vkd_table = variant_key_data(mkb_records).ok_or(MediaKeyVariantError::MkbIncomplete)?;
+    let c_value = variant_data_record(mkb_records).ok_or(MediaKeyVariantError::MkbIncomplete)?;
+    if c_value.len() < 16 {
+        return Err(MediaKeyVariantError::MkbIncomplete);
+    }
+    let mut c_block = [0u8; 16];
+    c_block.copy_from_slice(&c_value[..16]);
+
+    // Step: Kmp = AES-128D(Kp, C) XOR uv  (uv into low 4 bytes).
+    let mut kmp = aes_ecb_decrypt(&pkm.kp, &c_block);
+    let uv_bytes = pkm.uv.to_be_bytes();
+    for i in 0..4 {
+        kmp[12 + i] ^= uv_bytes[i];
+    }
+
+    // Condition bits on Kmp[15] route off the hardcoded-KCD path.
+    if kmp[15] & 0b0000_0010 != 0 {
+        return Err(MediaKeyVariantError::SoftCorrectionRequired);
+    }
+    if kmp[15] & 0b0000_0100 != 0 {
+        return Err(MediaKeyVariantError::OnlineChallengeRequired);
+    }
+    if kcd == &KEY_CORRECTION_DATA_PLACEHOLDER {
+        return Err(MediaKeyVariantError::KcdNotProvided);
+    }
+
+    // Step: Kpnew = Kmp XOR KCD.
+    let mut kpnew = [0u8; 16];
+    for i in 0..16 {
+        kpnew[i] = kmp[i] ^ kcd[i];
+    }
+
+    // Step: Kvn = AES-G(Kp, Nonce) & 0xFFFF  (low 16 bits, BE).
+    let kvn_block = aes_g(&pkm.kp, &nonce);
+    let kvn = u16::from_be_bytes([kvn_block[14], kvn_block[15]]);
+
+    // Step: VKD_idx = Kvn XOR VARIANTS[uv].
+    let v_for_uv = variants_for_uv(mkb_records, pkm.cvalue_index)
+        .ok_or(MediaKeyVariantError::VariantsTableUnavailable)?;
+    let vkd_idx = kvn ^ v_for_uv;
+
+    // Step: VKD = vkd_table[VKD_idx * 16 .. +16].
+    let off = (vkd_idx as usize) * 16;
+    if off + 16 > vkd_table.len() {
+        return Err(MediaKeyVariantError::VkdIndexOutOfRange);
+    }
+    let mut vkd = [0u8; 16];
+    vkd.copy_from_slice(&vkd_table[off..off + 16]);
+
+    // Step: Km = AES-128D(Kpnew, VKD) XOR uv.
+    let mut km = aes_ecb_decrypt(&kpnew, &vkd);
+    for i in 0..4 {
+        km[12 + i] ^= uv_bytes[i];
+    }
+
+    // Step: Kvu = AES-G(Km, VID).
+    let kvu = aes_g(&km, vid);
+
+    Ok((km, kvu))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // ── Helpers ──
+
+    fn synthetic_mkb_classical() -> Vec<u8> {
+        // Minimal MKB: type/version record + cvalues + mk_dv. No variant
+        // records.
+        let mut mkb = vec![
+            0x10, 0x00, 0x00, 0x0C, 0x48, 0x14, 0x10, 0x03, 0x00, 0x00, 0x00, 0x4D,
+        ];
+        mkb.extend_from_slice(&[0x07, 0x00, 0x00, 0x14]);
+        mkb.extend_from_slice(&[0xAB; 16]);
+        mkb.extend_from_slice(&[0x86, 0x00, 0x00, 0x14]);
+        mkb.extend_from_slice(&[0xCD; 16]);
+        mkb
+    }
+
+    fn synthetic_mkb_with_variant() -> Vec<u8> {
+        let mut mkb = synthetic_mkb_classical();
+        // 0x82 — 16-byte body (Variant data / VKD slot).
+        mkb.extend_from_slice(&[0x82, 0x00, 0x00, 0x14]);
+        mkb.extend_from_slice(&[0xEE; 16]);
+        // 0x83 — 16-byte body (Variant Nonce).
+        mkb.extend_from_slice(&[0x83, 0x00, 0x00, 0x14]);
+        mkb.extend_from_slice(&[0x55; 16]);
+        mkb
+    }
+
+    // ── Walker / record detection ──
+
+    #[test]
+    fn walker_parses_synthetic_mkb() {
+        let mkb = synthetic_mkb_classical();
+        let recs = walk_mkb(&mkb);
+        assert_eq!(recs.len(), 3);
+        assert_eq!(recs[0].rec_type, 0x10);
+        assert_eq!(recs[1].rec_type, 0x07);
+        assert_eq!(recs[2].rec_type, 0x86);
+    }
+
+    #[test]
+    fn variant_detection_negative_on_classical() {
+        let recs = walk_mkb(&synthetic_mkb_classical());
+        assert!(!is_variant_mkb(&recs));
+        assert!(variant_nonce(&recs).is_none());
+        assert!(variant_key_data(&recs).is_none());
+        assert!(variant_data_record(&recs).is_none());
+    }
+
+    #[test]
+    fn variant_detection_positive_on_variant() {
+        let recs = walk_mkb(&synthetic_mkb_with_variant());
+        assert!(is_variant_mkb(&recs));
+        assert_eq!(variant_nonce(&recs), Some([0x55; 16]));
+        assert_eq!(variant_key_data(&recs), Some(&[0xEE; 16][..]));
+        assert_eq!(variant_data_record(&recs), Some(&[0xEE; 16][..]));
+    }
+
+    // ── Chain entry-point classification ──
+
+    #[test]
+    fn chain_rejects_non_variant_mkb() {
+        let recs = walk_mkb(&synthetic_mkb_classical());
+        let err = derive_media_key_variant(&recs, &[], &[0xAA; 16], &[0u8; 16])
+            .expect_err("classical MKB must be rejected");
+        assert_eq!(err, MediaKeyVariantError::NotVariantMkb);
+    }
+
+    #[test]
+    fn chain_rejects_placeholder_kcd() {
+        // To reach the KCD check we need a complete variant MKB AND a
+        // DK that walks it. We construct both via the synthetic
+        // fixture below.
+        let (recs, dk, _kp, _expected_kmp) = synthetic_variant_setup(/*kmp15*/ 0x00);
+        let err =
+            derive_media_key_variant(&recs, &[dk], &KEY_CORRECTION_DATA_PLACEHOLDER, &[0u8; 16])
+                .expect_err("placeholder KCD must be rejected");
+        assert_eq!(err, MediaKeyVariantError::KcdNotProvided);
+    }
+
+    #[test]
+    fn chain_detects_soft_correction_bit() {
+        let (recs, dk, _, _) = synthetic_variant_setup(/*kmp15*/ 0x02);
+        let err = derive_media_key_variant(&recs, &[dk], &[0xAA; 16], &[0u8; 16])
+            .expect_err("bit 0x02 must surface SoftCorrectionRequired");
+        assert_eq!(err, MediaKeyVariantError::SoftCorrectionRequired);
+    }
+
+    #[test]
+    fn chain_detects_online_challenge_bit() {
+        let (recs, dk, _, _) = synthetic_variant_setup(/*kmp15*/ 0x04);
+        let err = derive_media_key_variant(&recs, &[dk], &[0xAA; 16], &[0u8; 16])
+            .expect_err("bit 0x04 must surface OnlineChallengeRequired");
+        assert_eq!(err, MediaKeyVariantError::OnlineChallengeRequired);
+    }
+
+    #[test]
+    fn chain_surfaces_variants_table_gap_on_clean_kmp() {
+        // With both condition bits clear and a non-placeholder KCD, the
+        // chain advances to the per-uv VARIANTS[uv] lookup, which is
+        // not yet wired. That returns VariantsTableUnavailable —
+        // proving the bit checks and KCD check all passed.
+        let (recs, dk, _, _) = synthetic_variant_setup(/*kmp15*/ 0x00);
+        let err = derive_media_key_variant(&recs, &[dk], &[0xAA; 16], &[0u8; 16])
+            .expect_err("expected VariantsTableUnavailable at the per-uv lookup");
+        assert_eq!(err, MediaKeyVariantError::VariantsTableUnavailable);
+    }
+
+    #[test]
+    fn error_display_is_code_only() {
+        // No English in Display — every variant emits "E7xxx" and
+        // nothing else.
+        let cases = [
+            MediaKeyVariantError::NotVariantMkb,
+            MediaKeyVariantError::MkbIncomplete,
+            MediaKeyVariantError::ProcessingKeyUnavailable,
+            MediaKeyVariantError::SoftCorrectionRequired,
+            MediaKeyVariantError::OnlineChallengeRequired,
+            MediaKeyVariantError::KcdNotProvided,
+            MediaKeyVariantError::VariantsTableUnavailable,
+            MediaKeyVariantError::VkdIndexOutOfRange,
+        ];
+        for e in cases {
+            let s = e.to_string();
+            assert!(
+                s.starts_with('E') && s.len() == 5,
+                "error display must be E#### only, got {s:?}"
+            );
+            assert!(
+                s.chars().skip(1).all(|c| c.is_ascii_digit()),
+                "error display must be E + digits, got {s:?}"
+            );
+        }
+    }
+
+    // ── Fixture construction ──
+
+    /// Build a synthetic variant MKB plus a DK that walks the single
+    /// subset-difference slot it carries. `kmp15` is the value of the
+    /// low byte of `Kmp[15]` that the chain will land on — pick `0x02`
+    /// to exercise the SoftCorrection bit, `0x04` to exercise
+    /// OnlineChallenge, `0x00` otherwise.
+    ///
+    /// The fixture pins:
+    /// - MKB subset-difference: `u_mask_shift=3, uv=2`. With these
+    ///   masks the discriminator bit (u_mask=1, v_mask=0) is bit 2.
+    /// - one DK at `node=4, uv=2, u_mask_shift=3`. node 4 has bit 2 set
+    ///   (differs from uv=2 on bit 2 → disagrees on v_mask) while
+    ///   agreeing with uv on bits 3+ (the u_mask=1 region). dk.uv ==
+    ///   MKB.uv and dk.u_mask_shift == MKB.u_mask_shift make
+    ///   `dev_key_v_mask == v_mask`, so `calc_pk_from_dk` loops zero
+    ///   times — Kp = aesg3_step(dk, 1).
+    /// - one cvalue in record 0x07 chosen so AES-D(Kp, C) ⊕ uv produces a
+    ///   Kmp whose byte-15 is exactly `kmp15`.
+    /// - record 0x82 with a 16-byte body (acts as both Variant Data
+    ///   and Variant Key Data; satisfies the parser heuristics).
+    /// - record 0x83 with a 16-byte Nonce.
+    ///
+    /// Returns (records, dk, planted_kp, planted_kmp).
+    fn synthetic_variant_setup(kmp15: u8) -> (Vec<MkbRecord>, DeviceKey, [u8; 16], [u8; 16]) {
+        use crate::aacs::decrypt::aes_ecb_encrypt;
+
+        // Build header.
+        let mut mkb = vec![
+            0x10, 0x00, 0x00, 0x0C, 0x48, 0x14, 0x10, 0x03, 0x00, 0x00, 0x00, 0x4D,
+        ];
+
+        // Subset-difference (0x04): u_mask_shift=3, uv=00 00 00 02.
+        mkb.extend_from_slice(&[0x04, 0x00, 0x00, 0x09]);
+        mkb.extend_from_slice(&[0x03, 0x00, 0x00, 0x00, 0x02]);
+
+        // Pick a known DK; with dk.uv == MKB.uv (==2) and
+        // dk.u_mask_shift == MKB.u_mask_shift (==1), dev_key_v_mask
+        // equals the MKB's v_mask and the calc_pk_from_dk loop is a
+        // no-op — Kp = aesg3_step(dk, 1).
+        let dk_bytes: [u8; 16] = [
+            0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE,
+            0xFF, 0x00,
+        ];
+        let kp = aesg3_step(&dk_bytes, 1);
+
+        // Plant Kmp with chosen byte-15, then compute C such that
+        // AES-D(Kp, C) ⊕ uv == Kmp. uv=2 → low-4 bytes XOR is 00 00 00 02.
+        let mut kmp = [0x42u8; 16];
+        kmp[15] = kmp15;
+        let mut aes_d_result = kmp;
+        aes_d_result[15] ^= 0x02;
+        let c_block = aes_ecb_encrypt(&kp, &aes_d_result);
+
+        // cvalues record (0x07): one 16-byte cvalue. The walker
+        // indexes it for the magic-check step; on a variant MKB the
+        // magic check fails but `variant_present` is true so the
+        // walker still returns the match. Content is don't-care.
+        mkb.extend_from_slice(&[0x07, 0x00, 0x00, 0x14]);
+        mkb.extend_from_slice(&[0xAB; 16]);
+
+        // Verify Media Key (0x86): body content is don't-care.
+        mkb.extend_from_slice(&[0x86, 0x00, 0x00, 0x14]);
+        mkb.extend_from_slice(&[0xCD; 16]);
+
+        // 0x82 record: holds C (Encrypted Media Key Variant Data) AND
+        // doubles as the VKD table (single 16-byte entry → VKDidx must
+        // resolve to 0 for `chain_surfaces_variants_table_gap` test —
+        // but the test never reaches the VKD lookup since the
+        // VARIANTS[uv] helper is not yet wired).
+        mkb.extend_from_slice(&[0x82, 0x00, 0x00, 0x14]);
+        mkb.extend_from_slice(&c_block);
+
+        // 0x83 record: 16-byte Nonce.
+        mkb.extend_from_slice(&[0x83, 0x00, 0x00, 0x14]);
+        mkb.extend_from_slice(&[0x77; 16]);
+
+        let recs = walk_mkb(&mkb);
+
+        let dk = DeviceKey {
+            key: dk_bytes,
+            node: 4,
+            uv: 2,
+            u_mask_shift: 3,
+        };
+        (recs, dk, kp, kmp)
+    }
+}

src/aacs/verify_magics.rs

@@ -0,0 +1,172 @@
+//! AACS Verify-Media-Key magic constants used to confirm Media Key
+//! candidates produced during MKB walking.
+//!
+//! AACS MKBs contain "Verify Media Key Records" whose decrypted output
+//! is a known-plaintext constant. Walking code decrypts the verify
+//! record with each MK candidate and compares the result against the
+//! magic; on match, the MK is correct.
+//!
+//! Five distinct magics are observed in the canonical reference AACS
+//! engine (MakeMKV v1.18.3, file offsets in parens):
+//!
+//! 1. **MK\_V10** at `.rodata:0x2909c0`. The original AACS-1.0 spec
+//!    constant. Single 16-byte AES-128-ECB compare. Used at 3 sites in
+//!    that engine. We already use it in `keys.rs::validate_media_key_against_mkb`.
+//!
+//! 2. **MK\_AUX\_16** at `.rodata:0x290890`. A second single-block
+//!    16-byte verification magic. Reverse-engineering of the call site
+//!    at `0x580f73` shows it after a call to the single-block AES-ECB
+//!    helper. Likely a per-vendor or per-record-type extended verify.
+//!    Use it when an MKB carries an extended verify record alongside
+//!    the standard one.
+//!
+//! 3. **MK\_SK\_32a** = `MK_SK32A_BLK0` || `MK_SK32A_BLK1`. A 32-byte
+//!    (2-block) verify magic at `.rodata:0x290910 / 0x290620`. Used at
+//!    `0x580ff0`: both blocks must match after AES-128 decrypt of a
+//!    32-byte verify record. Almost certainly the AACS-2 / Sequence
+//!    Key Block "Verify Media Key Record for Sequence Keys" expanded
+//!    form — i.e. AACS-2 SKB verification.
+//!
+//! 4. **MK\_SK\_32b** = `MK_SK32B_BLK0` || `MK_SK32B_BLK1`. A second
+//!    32-byte verify magic at `.rodata:0x290980 / 0x290a60`. Used at
+//!    `0x581063`. Different record type within the SKB family — likely
+//!    the AACS-2 SD-tree variant verification.
+//!
+//! All five are KNOWN PLAINTEXT compared bit-for-bit against the
+//! AES-128 decrypt output. They are NOT keys. They are oracle values
+//! that say "yes, the MK candidate you tried is the right one."
+//!
+//! Provenance: identified via static RE of MakeMKV v1.18.3 amd64
+//! (binary sha256 `9970a50a97231b2d09d73f521ff1daf0609ea201040a68ecaa9f31af957d6401`)
+//! on 2026-05-22 via objdump of the `pcmpeqb` callsite cluster around
+//! file offset `0x580f70..0x581080`.
+
+/// AACS-1.0 / pre-existing canonical Verify Media Key magic.
+///
+/// `AES-128-ECB-DECRYPT(MK, verify_record) == [VERIFY_MK_V10 || pad]`
+pub const VERIFY_MK_V10: [u8; 8] = [0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF];
+
+/// Single-block 16-byte verify magic (auxiliary). Compared full-16
+/// after AES-128-ECB(MK, in) at `pcmpeqb` site `0x580f73`.
+pub const VERIFY_MK_AUX_16: [u8; 16] = [
+    0xf9, 0x91, 0xa3, 0x60, 0x68, 0x15, 0xa6, 0xb9, 0x55, 0xbb, 0xce, 0xa3, 0xb1, 0x4b, 0xf8, 0xd8,
+];
+
+/// 32-byte SKB-style verify magic, block 0 of 2. Compared full-16
+/// after AES-128 decrypt of the first 16 bytes of a 32-byte verify
+/// record. `pcmpeqb` site `0x580ff0`.
+pub const VERIFY_MK_SK_32A_BLK0: [u8; 16] = [
+    0x19, 0x0f, 0xe9, 0x7f, 0xad, 0x11, 0xa4, 0x10, 0xc6, 0x56, 0x9d, 0x1c, 0x84, 0x21, 0x1d, 0x18,
+];
+
+/// 32-byte SKB-style verify magic, block 1 of 2. Compared full-16
+/// after AES-128 decrypt of bytes 16..32 of the same record.
+/// `pcmpeqb` site `0x580fe8`.
+pub const VERIFY_MK_SK_32A_BLK1: [u8; 16] = [
+    0x9b, 0x54, 0x9a, 0x25, 0x69, 0x8a, 0xa2, 0x3f, 0x9d, 0xfd, 0x2c, 0x95, 0xe2, 0x4a, 0x97, 0x02,
+];
+
+/// 32-byte SKB-style verify magic (variant B), block 0 of 2.
+/// `pcmpeqb` site `0x581063`.
+pub const VERIFY_MK_SK_32B_BLK0: [u8; 16] = [
+    0x8d, 0xee, 0xe0, 0x1e, 0xc7, 0x0c, 0xea, 0xb3, 0xdb, 0xd2, 0xfb, 0x82, 0x16, 0x3c, 0x26, 0x80,
+];
+
+/// 32-byte SKB-style verify magic (variant B), block 1 of 2.
+/// `pcmpeqb` site `0x58105b`.
+pub const VERIFY_MK_SK_32B_BLK1: [u8; 16] = [
+    0xaf, 0x93, 0x7a, 0x74, 0x8a, 0xce, 0xd3, 0x69, 0x36, 0x84, 0xe6, 0xea, 0xf8, 0x54, 0xe8, 0xa2,
+];
+
+/// Tag for a candidate-Media-Key check. Tells the verifier which
+/// known-plaintext to compare against; the verifier chooses the
+/// magic that matches the MKB record type at hand.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum VerifyMagic {
+    /// AACS-1.0 / canonical.
+    V10,
+    /// Auxiliary single-block (16-byte) verification.
+    Aux16,
+    /// SKB-style 32-byte verification, variant A.
+    Sk32A,
+    /// SKB-style 32-byte verification, variant B.
+    Sk32B,
+}
+
+/// Verify a candidate Media Key against a `dec_vd` (AES-128 decrypt
+/// of the MKB Verify Media Key Record under the candidate MK).
+///
+/// Returns `true` if `dec_vd` matches the magic identified by `tag`.
+///
+/// - `V10`: compares the first 8 bytes against `VERIFY_MK_V10`.
+/// - `Aux16`: compares the full 16 bytes against `VERIFY_MK_AUX_16`.
+/// - `Sk32A` / `Sk32B`: `dec_vd` must be exactly 32 bytes (`block0 ||
+///   block1`); compares each block against the corresponding constant.
+pub fn check_verify(tag: VerifyMagic, dec_vd: &[u8]) -> bool {
+    match tag {
+        VerifyMagic::V10 => dec_vd.len() >= 8 && dec_vd[..8] == VERIFY_MK_V10,
+        VerifyMagic::Aux16 => dec_vd.len() >= 16 && dec_vd[..16] == VERIFY_MK_AUX_16,
+        VerifyMagic::Sk32A => {
+            dec_vd.len() >= 32
+                && dec_vd[..16] == VERIFY_MK_SK_32A_BLK0
+                && dec_vd[16..32] == VERIFY_MK_SK_32A_BLK1
+        }
+        VerifyMagic::Sk32B => {
+            dec_vd.len() >= 32
+                && dec_vd[..16] == VERIFY_MK_SK_32B_BLK0
+                && dec_vd[16..32] == VERIFY_MK_SK_32B_BLK1
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn v10_matches_canonical_prefix() {
+        let mut dec = [0u8; 16];
+        dec[..8].copy_from_slice(&VERIFY_MK_V10);
+        assert!(check_verify(VerifyMagic::V10, &dec));
+    }
+
+    #[test]
+    fn aux16_matches_full_block() {
+        assert!(check_verify(VerifyMagic::Aux16, &VERIFY_MK_AUX_16));
+    }
+
+    #[test]
+    fn sk32a_requires_both_blocks() {
+        let mut dec = [0u8; 32];
+        dec[..16].copy_from_slice(&VERIFY_MK_SK_32A_BLK0);
+        dec[16..].copy_from_slice(&VERIFY_MK_SK_32A_BLK1);
+        assert!(check_verify(VerifyMagic::Sk32A, &dec));
+
+        // Mutate block 1, must fail.
+        dec[20] ^= 0x80;
+        assert!(!check_verify(VerifyMagic::Sk32A, &dec));
+    }
+
+    #[test]
+    fn sk32b_distinct_from_sk32a() {
+        let mut dec = [0u8; 32];
+        dec[..16].copy_from_slice(&VERIFY_MK_SK_32B_BLK0);
+        dec[16..].copy_from_slice(&VERIFY_MK_SK_32B_BLK1);
+        assert!(check_verify(VerifyMagic::Sk32B, &dec));
+        // Same plaintext must NOT validate as Sk32A.
+        assert!(!check_verify(VerifyMagic::Sk32A, &dec));
+    }
+
+    #[test]
+    fn short_input_never_matches() {
+        let dec = [0u8; 4];
+        for tag in [
+            VerifyMagic::V10,
+            VerifyMagic::Aux16,
+            VerifyMagic::Sk32A,
+            VerifyMagic::Sk32B,
+        ] {
+            assert!(!check_verify(tag, &dec));
+        }
+    }
+}

src/clpi.rs

@@ -6,15 +6,22 @@
 //!
 //! Reference: https://github.com/lw/BluRay/wiki/CLPI
 
+use crate::disc::Extent;
 use crate::error::{Error, Result};
 
 /// Parsed CLPI clip info.
 #[derive(Debug)]
-pub(crate) struct ClipInfo {
+#[allow(dead_code)]
+pub struct ClipInfo {
+    pub version: String,
     /// Total source packets in the m2ts (each 192 bytes)
     pub source_packet_count: u32,
+    /// Coarse EP entries for the primary video stream
+    pub ep_coarse: Vec<EpCoarse>,
+    /// Fine EP entries for the primary video stream
+    pub ep_fine: Vec<EpFine>,
     /// Per-stream metadata from the ProgramInfo section (BD spec).
-    /// Cross-validates the MPLS STN view — see `labels/clpi_audit.rs`.
+    /// Cross-validates the MPLS STN view — see `labels/clpi.rs`.
     /// Empty when program_info is missing or malformed.
     pub streams: Vec<ClpiStream>,
 }
@@ -23,14 +30,118 @@ pub(crate) struct ClipInfo {
 /// table. Mirrors the same fields the MPLS STN table carries — see
 /// `mpls::StreamEntry` for the playlist-side equivalent.
 #[derive(Debug, Clone)]
-pub(crate) struct ClpiStream {
+#[allow(dead_code)]
+pub struct ClpiStream {
     /// PID of the stream in the MPEG-TS (matches MPLS).
     pub pid: u16,
-    /// BD stream coding type byte (0x80 LPCM, 0x83 TrueHD, 0x86 DTS-HD MA,
+    /// SCSI/BD coding type byte (0x80 LPCM, 0x83 TrueHD, 0x86 DTS-HD MA,
     /// 0x90 PG, etc.). See `labels::mpls_universal::coding_type_to_codec_hint`.
     pub coding_type: u8,
     /// ISO 639-2 3-char language code. Empty for video streams.
     pub language: String,
+    /// Audio format byte (1=mono, 3=stereo, 6=5.1, 12=7.1).
+    /// Zero for non-audio streams.
+    pub audio_format: u8,
+    /// Audio sample rate (1=48kHz, 4=96kHz, 5=192kHz). Zero for non-audio.
+    pub audio_rate: u8,
+    /// Video format byte (1=480i, 4=1080i, 5=720p, 6=1080p, 8=2160p).
+    /// Zero for non-video.
+    pub video_format: u8,
+    /// Video rate (1=23.976, 2=24, 3=25, 4=29.97, 6=50, 7=59.94).
+    pub video_rate: u8,
+}
+
+#[derive(Debug, Clone)]
+#[allow(dead_code)]
+pub struct EpCoarse {
+    pub ref_to_fine_id: u32,
+    pub pts_coarse: u32,
+    pub spn_coarse: u32,
+}
+
+#[derive(Debug, Clone)]
+#[allow(dead_code)]
+pub struct EpFine {
+    pub pts_fine: u32,
+    pub spn_fine: u32,
+}
+
+#[allow(dead_code)]
+impl ClipInfo {
+    /// Reconstruct full PTS from coarse + fine entry.
+    pub fn full_pts(coarse: &EpCoarse, fine: &EpFine) -> u32 {
+        (coarse.pts_coarse << 19) + (fine.pts_fine << 8)
+    }
+
+    /// Reconstruct full SPN from coarse + fine entry.
+    pub fn full_spn(coarse: &EpCoarse, fine: &EpFine) -> u32 {
+        (coarse.spn_coarse & 0xFFFE_0000) + fine.spn_fine
+    }
+
+    /// Get all EP entries as (PTS, SPN) pairs, fully resolved.
+    pub fn resolved_ep_map(&self) -> Vec<(u32, u32)> {
+        let mut entries = Vec::new();
+
+        for (ci, coarse) in self.ep_coarse.iter().enumerate() {
+            let fine_start = coarse.ref_to_fine_id as usize;
+            let fine_end = if ci + 1 < self.ep_coarse.len() {
+                self.ep_coarse[ci + 1].ref_to_fine_id as usize
+            } else {
+                self.ep_fine.len()
+            };
+
+            for fi in fine_start..fine_end.min(self.ep_fine.len()) {
+                let fine = &self.ep_fine[fi];
+                let pts = Self::full_pts(coarse, fine);
+                let spn = Self::full_spn(coarse, fine);
+                entries.push((pts, spn));
+            }
+        }
+
+        entries
+    }
+
+    /// Get sector extents for a given in/out time range.
+    ///
+    /// Converts PTS timestamps to SPN ranges, then SPN to LBA
+    /// using the file's starting LBA on disc.
+    pub fn get_extents(&self, in_time: u32, out_time: u32) -> Vec<Extent> {
+        let ep_map = self.resolved_ep_map();
+        if ep_map.is_empty() {
+            return Vec::new();
+        }
+
+        // Find SPN at or before in_time
+        let start_spn = match ep_map.binary_search_by_key(&in_time, |(pts, _)| *pts) {
+            Ok(i) => ep_map[i].1,
+            Err(0) => ep_map[0].1,
+            Err(i) => ep_map[i - 1].1,
+        };
+
+        // Find SPN at or after out_time
+        let end_spn = match ep_map.binary_search_by_key(&out_time, |(pts, _)| *pts) {
+            Ok(i) => ep_map[i].1,
+            Err(i) if i < ep_map.len() => ep_map[i].1,
+            _ => ep_map.last().unwrap().1 + 1,
+        };
+
+        if end_spn <= start_spn {
+            return Vec::new();
+        }
+
+        // SPN → byte offset: spn × 192
+        // Byte offset → sectors: offset / 2048
+        // Note: the caller needs to add the file's starting LBA from UDF
+        let start_byte = start_spn as u64 * 192;
+        let end_byte = end_spn as u64 * 192;
+        let start_sector = (start_byte / 2048) as u32;
+        let end_sector = end_byte.div_ceil(2048) as u32;
+
+        vec![Extent {
+            start_lba: start_sector, // relative to m2ts file start
+            sector_count: end_sector - start_sector,
+        }]
+    }
 }
 
 /// Parse a CLPI file from raw bytes.
@@ -42,14 +153,16 @@ pub fn parse(data: &[u8]) -> Result<ClipInfo> {
     if &data[0..4] != b"HDMV" {
         return Err(Error::ClpiParse);
     }
+    let version = String::from_utf8_lossy(&data[4..8]).to_string();
 
     // Header offsets
     let _seq_info_start = u32::from_be_bytes([data[8], data[9], data[10], data[11]]) as usize;
     let prog_info_start = u32::from_be_bytes([data[12], data[13], data[14], data[15]]) as usize;
+    let cpi_start = u32::from_be_bytes([data[16], data[17], data[18], data[19]]) as usize;
 
     // ClipInfo section at offset 40
     // source_packet_count at offset 40 + 4(len) + 2(reserved) + 1(stream_type) + 1(app_type) + 4(reserved) + 4(ts_rate)
-    let source_packet_count = if data.len() >= 60 {
+    let source_packet_count = if data.len() > 56 {
         u32::from_be_bytes([data[56], data[57], data[58], data[59]])
     } else {
         0
@@ -65,15 +178,25 @@ pub fn parse(data: &[u8]) -> Result<ClipInfo> {
         Vec::new()
     };
 
+    // Parse CPI / EP Map
+    let (ep_coarse, ep_fine) = if cpi_start > 0 && cpi_start + 8 < data.len() {
+        parse_cpi(&data[cpi_start..])?
+    } else {
+        (Vec::new(), Vec::new())
+    };
+
     Ok(ClipInfo {
+        version,
         source_packet_count,
+        ep_coarse,
+        ep_fine,
         streams,
     })
 }
 
 /// Parse the ProgramInfo section: per-stream (pid, coding_type,
-/// language, codec sub-fields). Layout per the Blu-ray Disc Read-Only Format
-/// Part 3 CLIPINF (CLPI) specification:
+/// language, codec sub-fields). Layout per BD spec / libbluray
+/// clpi_parse.c:
 ///
 /// ```text
 /// ProgramInfo:
@@ -97,7 +220,6 @@ pub fn parse(data: &[u8]) -> Result<ClipInfo> {
 /// errors because the EP map is the primary CLPI output, and a corrupt
 /// program_info shouldn't break sector-range lookups.
 fn parse_program_info(data: &[u8]) -> Vec<ClpiStream> {
-    use crate::consts::coding_type as c;
     let mut out = Vec::new();
     if data.len() < 6 {
         return out;
@@ -129,26 +251,46 @@ fn parse_program_info(data: &[u8]) -> Vec<ClpiStream> {
             let sci = &data[pos + 3..sci_end];
             let coding_type = sci[0];
 
+            let mut audio_format = 0u8;
+            let mut audio_rate = 0u8;
+            let mut video_format = 0u8;
+            let mut video_rate = 0u8;
             let mut language = String::new();
 
             match coding_type {
-                // Video — MPEG-2, H.264, HEVC
-                c::MPEG2_VIDEO | c::H264 | c::HEVC => {}
-                // Primary audio — LPCM, AC-3, DTS, TrueHD, AC-3+, DTS-HD HR, DTS-HD MA
-                c::LPCM..=c::DTS_HD_MA => {
+                // Video — MPEG-2 (0x02), H.264 (0x1B), HEVC (0x24)
+                0x02 | 0x1B | 0x24 => {
+                    if sci.len() >= 2 {
+                        video_format = (sci[1] >> 4) & 0x0F;
+                        video_rate = sci[1] & 0x0F;
+                    }
+                }
+                // Primary audio — LPCM(0x80), AC-3(0x81), DTS(0x82),
+                // TrueHD(0x83), AC-3+(0x84), DTS-HD(0x85), DTS-HD MA(0x86)
+                0x80..=0x86 => {
+                    if sci.len() >= 2 {
+                        audio_format = (sci[1] >> 4) & 0x0F;
+                        audio_rate = sci[1] & 0x0F;
+                    }
                     if sci.len() >= 5 {
                         language = String::from_utf8_lossy(&sci[2..5]).to_string();
                     }
                 }
-                // Secondary audio (AC-3+ secondary, DTS-HD secondary)
-                c::AC3_PLUS_SECONDARY | c::DTS_HD_SECONDARY => {
+                // Secondary audio (0xA1 AC-3+, 0xA2 DTS-HD)
+                0xA1 | 0xA2 => {
+                    if sci.len() >= 2 {
+                        audio_format = (sci[1] >> 4) & 0x0F;
+                        audio_rate = sci[1] & 0x0F;
+                    }
                     if sci.len() >= 5 {
                         language = String::from_utf8_lossy(&sci[2..5]).to_string();
                     }
                 }
-                // PG, IG: coding_type + 3-byte language [+ char_code for PG]
-                c::PG | c::IG if sci.len() >= 4 => {
-                    language = String::from_utf8_lossy(&sci[1..4]).to_string();
+                // PG (0x90), IG (0x91): coding_type + 3-byte language [+ char_code for PG]
+                0x90 | 0x91 => {
+                    if sci.len() >= 4 {
+                        language = String::from_utf8_lossy(&sci[1..4]).to_string();
+                    }
                 }
                 _ => {}
             }
@@ -157,6 +299,10 @@ fn parse_program_info(data: &[u8]) -> Vec<ClpiStream> {
                 pid,
                 coding_type,
                 language,
+                audio_format,
+                audio_rate,
+                video_format,
+                video_rate,
             });
 
             pos = sci_end;
@@ -165,6 +311,140 @@ fn parse_program_info(data: &[u8]) -> Vec<ClpiStream> {
     out
 }
 
+/// Parse the CPI section containing the EP map.
+fn parse_cpi(data: &[u8]) -> Result<(Vec<EpCoarse>, Vec<EpFine>)> {
+    if data.len() < 8 {
+        return Ok((Vec::new(), Vec::new()));
+    }
+
+    let cpi_length = u32::from_be_bytes([data[0], data[1], data[2], data[3]]) as usize;
+    if cpi_length < 4 {
+        return Ok((Vec::new(), Vec::new()));
+    }
+
+    // CPI type at bits 44-47 (byte 5, lower 4 bits)
+    // Skip to EP map: offset 4 (after length) + 2 (reserved/type)
+    let ep_map = &data[6..];
+    if ep_map.len() < 4 {
+        return Ok((Vec::new(), Vec::new()));
+    }
+
+    // EP map header
+    // [0] reserved
+    // [1] number of stream PID entries
+    let num_streams = ep_map[1] as usize;
+    if num_streams == 0 {
+        return Ok((Vec::new(), Vec::new()));
+    }
+
+    // Stream PID entry headers start at offset 2
+    // Each: 2(PID) + 2(reserved+type) + 2(num_coarse) + 4(num_fine) + 4(ep_map_start) = 14 bytes
+    // We only care about the first stream (primary video)
+    if ep_map.len() < 16 {
+        return Ok((Vec::new(), Vec::new()));
+    }
+
+    // Stream PID entry — bit-packed per BD spec (libbluray clpi_parse.c):
+    //   stream_PID: 16 bits           → ep_map[2..4]
+    //   reserved: 10 bits             ┐
+    //   EP_stream_type: 4 bits        │ ep_map[4..14] = 80 bits
+    //   num_EP_coarse: 16 bits        │ (10+4+16+18+32 = 80)
+    //   num_EP_fine: 18 bits          │
+    //   EP_map_start_address: 32 bits ┘
+    if ep_map.len() < 16 {
+        return Ok((Vec::new(), Vec::new()));
+    }
+    let _stream_pid = u16::from_be_bytes([ep_map[2], ep_map[3]]);
+
+    // Read 10 bytes (80 bits) from ep_map[4..14] for bit extraction
+    // Use two u64s since we need 80 bits
+    let hi = u64::from_be_bytes([
+        ep_map[4], ep_map[5], ep_map[6], ep_map[7], ep_map[8], ep_map[9], ep_map[10], ep_map[11],
+    ]);
+    let lo_bytes = [ep_map[12], ep_map[13]];
+
+    // Bit 0-9: reserved (10)
+    // Bit 10-13: EP_stream_type (4)
+    // Bit 14-29: num_coarse (16)
+    // Bit 30-47: num_fine (18)
+    // Bit 48-79: EP_map_start (32) — bits 48-63 in hi, bits 64-79 in lo
+    let num_coarse = ((hi >> 34) & 0xFFFF) as usize;
+    let num_fine = ((hi >> 16) & 0x3FFFF) as usize;
+    let ep_map_offset = (((hi & 0xFFFF) as u32) << 16) | (u16::from_be_bytes(lo_bytes) as u32);
+    let ep_map_offset = ep_map_offset as usize;
+
+    // EP map for this stream starts at ep_map_offset relative to ep_map start
+    if ep_map_offset + 4 > ep_map.len() {
+        return Ok((Vec::new(), Vec::new()));
+    }
+
+    let stream_ep = &ep_map[ep_map_offset..];
+    if stream_ep.len() < 4 {
+        return Ok((Vec::new(), Vec::new()));
+    }
+
+    // Fine table start address (relative to this stream EP map)
+    let fine_start =
+        u32::from_be_bytes([stream_ep[0], stream_ep[1], stream_ep[2], stream_ep[3]]) as usize;
+
+    // Coarse entries start at offset 4, 8 bytes each
+    let coarse_data = &stream_ep[4..];
+    let mut ep_coarse = Vec::with_capacity(num_coarse);
+    for i in 0..num_coarse {
+        let off = i * 8;
+        if off + 8 > coarse_data.len() {
+            break;
+        }
+
+        let dword0 = u32::from_be_bytes([
+            coarse_data[off],
+            coarse_data[off + 1],
+            coarse_data[off + 2],
+            coarse_data[off + 3],
+        ]);
+        let ref_to_fine_id = dword0 >> 14;
+        let pts_coarse = dword0 & 0x3FFF;
+        let spn_coarse = u32::from_be_bytes([
+            coarse_data[off + 4],
+            coarse_data[off + 5],
+            coarse_data[off + 6],
+            coarse_data[off + 7],
+        ]);
+
+        ep_coarse.push(EpCoarse {
+            ref_to_fine_id,
+            pts_coarse,
+            spn_coarse,
+        });
+    }
+
+    // Fine entries at fine_start, 4 bytes each
+    let mut ep_fine = Vec::with_capacity(num_fine);
+    if fine_start < stream_ep.len() {
+        let fine_data = &stream_ep[fine_start..];
+        for i in 0..num_fine {
+            let off = i * 4;
+            if off + 4 > fine_data.len() {
+                break;
+            }
+
+            let dword = u32::from_be_bytes([
+                fine_data[off],
+                fine_data[off + 1],
+                fine_data[off + 2],
+                fine_data[off + 3],
+            ]);
+            // Bits: is_angle(1) + i_end_offset(3) + pts_fine(11) + spn_fine(17)
+            let pts_fine = (dword >> 17) & 0x7FF;
+            let spn_fine = dword & 0x1FFFF;
+
+            ep_fine.push(EpFine { pts_fine, spn_fine });
+        }
+    }
+
+    Ok((ep_coarse, ep_fine))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -203,20 +483,195 @@ mod tests {
         buf
     }
 
-    #[test]
-    fn parse_truncated_clipinfo_no_panic() {
-        // 57/58/59-byte CLPI with valid magic: passes the data.len() < 40
-        // guard but data[56..60] needs 60 bytes. Must not panic.
-        for len in 40..60usize {
-            let mut data = vec![0u8; len];
-            data[0..4].copy_from_slice(b"HDMV");
-            if len >= 8 {
-                data[4..8].copy_from_slice(b"0200");
-            }
-            let clip = parse(&data).expect("short CLPI should parse, not panic");
-            // source_packet_count is unreadable below 60 bytes → 0.
-            assert_eq!(clip.source_packet_count, 0);
+    /// Build a CPI section with one stream's EP map.
+    /// coarse_entries: Vec<(ref_to_fine_id, pts_coarse, spn_coarse)>
+    /// fine_entries: Vec<(pts_fine, spn_fine)>
+    fn build_cpi(
+        stream_pid: u16,
+        coarse_entries: &[(u32, u32, u32)],
+        fine_entries: &[(u32, u32)],
+    ) -> Vec<u8> {
+        // CPI section layout:
+        //   [0..4]   cpi_length (u32 BE)
+        //   [4..6]   reserved/type (2 bytes)
+        //   [6..]    EP map
+        //
+        // EP map layout (relative to byte 6 of CPI):
+        //   [0]      reserved
+        //   [1]      num_streams (1)
+        //   [2..4]   stream_PID (u16 BE)
+        //   [4..14]  80 bits: reserved(10) + EP_stream_type(4) + num_coarse(16) + num_fine(18) + EP_map_start(32)
+        //   [14..]   (next stream entry, if any)
+        //
+        // Stream EP map (at EP_map_start relative to EP map start):
+        //   [0..4]   fine_start (relative to stream EP map start)
+        //   [4..]    coarse entries, 8 bytes each
+        //   [fine_start..] fine entries, 4 bytes each
+
+        let num_coarse = coarse_entries.len() as u32;
+        let num_fine = fine_entries.len() as u32;
+
+        // EP_map_start: offset from ep_map start where the stream EP data begins.
+        // ep_map has: reserved(1) + num_streams(1) + stream_header(12) = 14 bytes
+        // So EP_map_start = 14 (first stream data right after the header)
+        let ep_map_start: u32 = 14;
+
+        // Build the 80-bit stream PID entry (10 bytes: ep_map[4..14])
+        // Bits: reserved(10) + EP_stream_type(4) + num_coarse(16) + num_fine(18) + EP_map_start(32)
+        // Total: 80 bits = 10 bytes
+        //
+        // Pack into a u128 for convenience then extract 10 bytes
+        let ep_stream_type: u32 = 1; // video
+        let packed: u128 = ((ep_stream_type as u128) << 66)           // EP_stream_type: 4 bits
+            | ((num_coarse as u128) << 50)                          // num_coarse: 16 bits
+            | ((num_fine as u128) << 32)                            // num_fine: 18 bits
+            | (ep_map_start as u128); // EP_map_start: 32 bits
+        let packed_bytes = packed.to_be_bytes(); // 16 bytes, we want the last 10
+        let stream_header_bits = &packed_bytes[6..16];
+
+        // Build stream EP data
+        // fine_start = 4 (header) + num_coarse * 8
+        let fine_start: u32 = 4 + num_coarse * 8;
+        let mut stream_ep = Vec::new();
+        stream_ep.extend_from_slice(&fine_start.to_be_bytes());
+
+        // Coarse entries: 8 bytes each
+        // dword0 = (ref_to_fine_id << 14) | (pts_coarse & 0x3FFF)
+        // dword1 = spn_coarse
+        for &(ref_id, pts_c, spn_c) in coarse_entries {
+            let dword0 = (ref_id << 14) | (pts_c & 0x3FFF);
+            stream_ep.extend_from_slice(&dword0.to_be_bytes());
+            stream_ep.extend_from_slice(&spn_c.to_be_bytes());
         }
+
+        // Fine entries: 4 bytes each
+        // dword = (is_angle(1) + i_end_offset(3) + pts_fine(11) + spn_fine(17))
+        for &(pts_f, spn_f) in fine_entries {
+            let dword: u32 = ((pts_f & 0x7FF) << 17) | (spn_f & 0x1FFFF);
+            stream_ep.extend_from_slice(&dword.to_be_bytes());
+        }
+
+        // Assemble EP map
+        let mut ep_map = Vec::new();
+        ep_map.push(0); // reserved
+        ep_map.push(1); // num_streams = 1
+        ep_map.extend_from_slice(&stream_pid.to_be_bytes());
+        ep_map.extend_from_slice(stream_header_bits);
+        ep_map.extend_from_slice(&stream_ep);
+
+        // Assemble CPI section
+        let mut cpi = Vec::new();
+        let cpi_length = (2 + ep_map.len()) as u32; // reserved/type(2) + ep_map
+        cpi.extend_from_slice(&cpi_length.to_be_bytes());
+        cpi.extend_from_slice(&[0u8; 2]); // reserved/type
+        cpi.extend_from_slice(&ep_map);
+
+        cpi
+    }
+
+    #[test]
+    fn parse_valid_clpi() {
+        let cpi = build_cpi(
+            0x1011,
+            &[(0, 100, 0x00020000)], // 1 coarse
+            &[(50, 1024)],           // 1 fine
+        );
+        let data = build_clpi(500_000, Some(&cpi));
+
+        let clip = parse(&data).expect("should parse valid CLPI");
+        assert_eq!(clip.version, "0200");
+        assert_eq!(clip.source_packet_count, 500_000);
+        assert_eq!(clip.ep_coarse.len(), 1);
+        assert_eq!(clip.ep_fine.len(), 1);
+    }
+
+    #[test]
+    fn parse_ep_map() {
+        let cpi = build_cpi(
+            0x1011,
+            &[
+                (0, 100, 0x00020000), // coarse 0: fine starts at 0, pts_coarse=100, spn_coarse=0x20000
+                (2, 200, 0x00040000), // coarse 1: fine starts at 2, pts_coarse=200, spn_coarse=0x40000
+            ],
+            &[
+                (50, 1024),  // fine 0
+                (100, 2048), // fine 1
+                (25, 512),   // fine 2
+                (75, 1536),  // fine 3
+            ],
+        );
+        let data = build_clpi(1_000_000, Some(&cpi));
+
+        let clip = parse(&data).expect("should parse EP map");
+        assert_eq!(clip.ep_coarse.len(), 2);
+        assert_eq!(clip.ep_fine.len(), 4);
+
+        // Verify coarse entries
+        assert_eq!(clip.ep_coarse[0].ref_to_fine_id, 0);
+        assert_eq!(clip.ep_coarse[0].pts_coarse, 100);
+        assert_eq!(clip.ep_coarse[0].spn_coarse, 0x00020000);
+        assert_eq!(clip.ep_coarse[1].ref_to_fine_id, 2);
+        assert_eq!(clip.ep_coarse[1].pts_coarse, 200);
+        assert_eq!(clip.ep_coarse[1].spn_coarse, 0x00040000);
+
+        // Verify fine entries
+        assert_eq!(clip.ep_fine[0].pts_fine, 50);
+        assert_eq!(clip.ep_fine[0].spn_fine, 1024);
+        assert_eq!(clip.ep_fine[1].pts_fine, 100);
+        assert_eq!(clip.ep_fine[1].spn_fine, 2048);
+        assert_eq!(clip.ep_fine[2].pts_fine, 25);
+        assert_eq!(clip.ep_fine[2].spn_fine, 512);
+        assert_eq!(clip.ep_fine[3].pts_fine, 75);
+        assert_eq!(clip.ep_fine[3].spn_fine, 1536);
+
+        // Verify resolved EP map assigns fine entries to coarse correctly
+        let resolved = clip.resolved_ep_map();
+        assert_eq!(resolved.len(), 4);
+        // First two fines belong to coarse 0, last two to coarse 1
+    }
+
+    #[test]
+    fn full_pts_calculation() {
+        let coarse = EpCoarse {
+            ref_to_fine_id: 0,
+            pts_coarse: 100,
+            spn_coarse: 0,
+        };
+        let fine = EpFine {
+            pts_fine: 50,
+            spn_fine: 0,
+        };
+        // full_pts = (100 << 19) + (50 << 8) = 52_428_800 + 12_800 = 52_441_600
+        let pts = ClipInfo::full_pts(&coarse, &fine);
+        assert_eq!(pts, (100 << 19) + (50 << 8));
+        assert_eq!(pts, 52_441_600);
+    }
+
+    #[test]
+    fn full_spn_calculation() {
+        let coarse = EpCoarse {
+            ref_to_fine_id: 0,
+            pts_coarse: 0,
+            spn_coarse: 0x00FE0000,
+        };
+        let fine = EpFine {
+            pts_fine: 0,
+            spn_fine: 0x1234,
+        };
+        // full_spn = (0x00FE0000 & 0xFFFE0000) + 0x1234 = 0x00FE0000 + 0x1234 = 0x00FE1234
+        let spn = ClipInfo::full_spn(&coarse, &fine);
+        assert_eq!(spn, 0x00FE0000 + 0x1234);
+        assert_eq!(spn, 0x00FE1234);
+
+        // Test that the low bit of spn_coarse is masked out
+        let coarse2 = EpCoarse {
+            ref_to_fine_id: 0,
+            pts_coarse: 0,
+            spn_coarse: 0x00FF0000,
+        };
+        let spn2 = ClipInfo::full_spn(&coarse2, &fine);
+        // 0x00FF0000 & 0xFFFE0000 = 0x00FE0000, so low 17 bits of coarse are zeroed
+        assert_eq!(spn2, 0x00FE0000 + 0x1234);
     }
 
     #[test]
@@ -229,313 +684,27 @@ mod tests {
         assert!(parse(&data).is_err());
     }
 
-    // ─────────────────────────────────────────────────────────────────────
-    // Added hardening tests. Grounded in the BD-ROM CLPI spec
-    // (https://github.com/lw/BluRay/wiki/CLPI).
-    // ─────────────────────────────────────────────────────────────────────
-
-    /// Build a ProgramInfo section. `streams` = Vec<(pid, sci_bytes)>.
-    /// Layout per source doc: length(4)+reserved(1)+num_programs(1)+
-    /// per program [spn(4)+pmt_pid(2)+num_streams(1)+num_groups(1)] then
-    /// per stream [pid(2)+sci_len(1)+sci].
-    fn build_program_info(streams: &[(u16, Vec<u8>)]) -> Vec<u8> {
-        let mut body = Vec::new();
-        body.push(0); // reserved (offset 4)
-        body.push(1); // num_programs = 1 (offset 5)
-        // program 0 header (8 bytes)
-        body.extend_from_slice(&0u32.to_be_bytes()); // spn_program_sequence_start
-        body.extend_from_slice(&0u16.to_be_bytes()); // program_map_pid
-        body.push(streams.len() as u8); // num_streams
-        body.push(0); // num_groups
-        for (pid, sci) in streams {
-            body.extend_from_slice(&pid.to_be_bytes());
-            body.push(sci.len() as u8);
-            body.extend_from_slice(sci);
-        }
-        // Prepend length(4) = bytes after the length field.
-        let mut out = Vec::new();
-        out.extend_from_slice(&(body.len() as u32).to_be_bytes());
-        out.extend_from_slice(&body);
-        out
-    }
-
-    /// Build a CLPI with a ProgramInfo section. prog_info_start is placed
-    /// right after the 60-byte header; cpi (if any) follows program_info.
-    fn build_clpi_with_proginfo(
-        source_packet_count: u32,
-        prog_info: &[u8],
-        cpi_data: Option<&[u8]>,
-    ) -> Vec<u8> {
-        let mut buf = vec![0u8; 60];
-        buf[0..4].copy_from_slice(b"HDMV");
-        buf[4..8].copy_from_slice(b"0200");
-        let prog_info_start: u32 = 60;
-        buf[12..16].copy_from_slice(&prog_info_start.to_be_bytes());
-        let cpi_start: u32 = if cpi_data.is_some() {
-            (60 + prog_info.len()) as u32
-        } else {
-            0
-        };
-        buf[16..20].copy_from_slice(&cpi_start.to_be_bytes());
-        buf[56..60].copy_from_slice(&source_packet_count.to_be_bytes());
-        buf.extend_from_slice(prog_info);
-        if let Some(cpi) = cpi_data {
-            buf.extend_from_slice(cpi);
-        }
-        buf
-    }
-
-    /// source_packet_count is a big-endian u32 at offset [56..60]. Verify
-    /// BE decode of a value with all four bytes distinct (not LE / wrong
-    /// offset).
     #[test]
-    fn source_packet_count_big_endian_offset_56() {
-        let data = build_clpi(0x01020304, None);
-        let clip = parse(&data).expect("should parse");
-        assert_eq!(clip.source_packet_count, 0x01020304);
+    fn parse_empty_ep_map() {
+        // cpi_start = 0 means no CPI section
+        let data = build_clpi(100_000, None);
+        let clip = parse(&data).expect("should parse with no EP map");
+        assert_eq!(clip.source_packet_count, 100_000);
+        assert!(clip.ep_coarse.is_empty());
+        assert!(clip.ep_fine.is_empty());
+
+        // Also test: CPI section present but with zero streams
+        let mut cpi = Vec::new();
+        let cpi_length: u32 = 6; // reserved/type(2) + ep_map(reserved(1) + num_streams=0(1) + 2 padding)
+        cpi.extend_from_slice(&cpi_length.to_be_bytes());
+        cpi.extend_from_slice(&[0u8; 2]); // reserved/type
+        cpi.push(0); // reserved
+        cpi.push(0); // num_streams = 0
+        cpi.extend_from_slice(&[0u8; 4]); // padding
+
+        let data2 = build_clpi(100_000, Some(&cpi));
+        let clip2 = parse(&data2).expect("should parse with zero-stream EP map");
+        assert!(clip2.ep_coarse.is_empty());
+        assert!(clip2.ep_fine.is_empty());
     }
-
-    /// Magic must be exactly "HDMV" at [0..4]. Anything else → ClpiParse.
-    /// Spec: CLPI files begin with the type_indicator "HDMV".
-    #[test]
-    fn wrong_magic_rejected() {
-        let mut data = build_clpi(1000, None);
-        data[0..4].copy_from_slice(b"INDX");
-        assert!(parse(&data).is_err());
-    }
-
-    /// Under-40-byte input is rejected before any field read
-    /// (`data.len() < 40` guard).
-    #[test]
-    fn under_40_bytes_rejected() {
-        assert!(parse(&[0u8; 39]).is_err());
-        assert!(parse(b"HDMV0200").is_err());
-        assert!(parse(&[]).is_err());
-    }
-
-    /// ProgramInfo: a video stream (coding 0x1B = H.264) carries
-    /// format/rate in sci[1] nibbles and NO language. Verify the video
-    /// arm: format hi-nibble, rate lo-nibble, language stays empty.
-    #[test]
-    fn program_info_video_stream() {
-        // sci = coding_type(0x1B) + format_rate(0x61 → fmt 6, rate 1)
-        let sci = vec![0x1Bu8, 0x61];
-        let pi = build_program_info(&[(0x1011, sci)]);
-        let data = build_clpi_with_proginfo(100, &pi, None);
-        let clip = parse(&data).expect("should parse");
-        assert_eq!(clip.streams.len(), 1);
-        assert_eq!(clip.streams[0].pid, 0x1011);
-        assert_eq!(clip.streams[0].coding_type, 0x1B);
-        assert_eq!(clip.streams[0].language, "");
-    }
-
-    /// ProgramInfo primary-audio (coding 0x80..=0x86): sci[1] = format/rate
-    /// nibbles, sci[2..5] = ISO 639 language. Verify TrueHD (0x83) at
-    /// offset, 5.1 / 48kHz, language "eng".
-    #[test]
-    fn program_info_audio_stream_lang_offset() {
-        // sci = 0x83 + 0x61 (fmt 6, rate 1) + "eng"
-        let sci = vec![0x83u8, 0x61, b'e', b'n', b'g'];
-        let pi = build_program_info(&[(0x1100, sci)]);
-        let data = build_clpi_with_proginfo(100, &pi, None);
-        let clip = parse(&data).expect("should parse");
-        assert_eq!(clip.streams[0].coding_type, 0x83);
-        assert_eq!(clip.streams[0].language, "eng");
-    }
-
-    /// ProgramInfo PG (0x90)/IG (0x91): layout is coding_type(1)+lang(3),
-    /// so language is at sci[1..4] (NOT sci[2..5] like audio). Verify the
-    /// PG arm reads from the right offset.
-    #[test]
-    fn program_info_pg_lang_offset() {
-        // sci = 0x90 + "fra" (lang directly after coding_type)
-        let sci = vec![0x90u8, b'f', b'r', b'a'];
-        let pi = build_program_info(&[(0x1200, sci)]);
-        let data = build_clpi_with_proginfo(100, &pi, None);
-        let clip = parse(&data).expect("should parse");
-        assert_eq!(clip.streams[0].coding_type, 0x90);
-        assert_eq!(clip.streams[0].language, "fra");
-        // Audio nibbles must NOT be populated for a PG stream.
-    }
-
-    /// ProgramInfo with multiple streams: PID and coding for each must be
-    /// read from the correct per-stream offset (pid(2)+sci_len(1)+sci).
-    /// Three mixed streams must all parse with distinct PIDs in order.
-    #[test]
-    fn program_info_multiple_streams_advance_correctly() {
-        let v = (0x1011u16, vec![0x24u8, 0x81]); // HEVC video
-        let a = (0x1100u16, vec![0x86u8, 0x61, b'e', b'n', b'g']); // DTS-HD MA
-        let s = (0x1200u16, vec![0x90u8, b'j', b'p', b'n']); // PG
-        let pi = build_program_info(&[v, a, s]);
-        let data = build_clpi_with_proginfo(100, &pi, None);
-        let clip = parse(&data).expect("should parse");
-        assert_eq!(clip.streams.len(), 3);
-        assert_eq!(clip.streams[0].pid, 0x1011);
-        assert_eq!(clip.streams[0].coding_type, 0x24);
-        assert_eq!(clip.streams[1].pid, 0x1100);
-        assert_eq!(clip.streams[1].coding_type, 0x86);
-        assert_eq!(clip.streams[1].language, "eng");
-        assert_eq!(clip.streams[2].pid, 0x1200);
-        assert_eq!(clip.streams[2].language, "jpn");
-    }
-
-    /// parse_program_info is best-effort: a stream whose declared sci_len
-    /// runs past the section (`sci_end > data.len()`) makes it return the
-    /// streams collected so far (here: none), never panic. Source returns
-    /// `out` early on the overflow.
-    #[test]
-    fn program_info_truncated_sci_no_panic() {
-        // One stream claiming sci_len = 200 but with no body.
-        let mut body = Vec::new();
-        body.push(0); // reserved
-        body.push(1); // num_programs
-        body.extend_from_slice(&0u32.to_be_bytes());
-        body.extend_from_slice(&0u16.to_be_bytes());
-        body.push(1); // num_streams
-        body.push(0); // num_groups
-        body.extend_from_slice(&0x1011u16.to_be_bytes()); // pid
-        body.push(200); // sci_len = 200, no body follows
-        let mut pi = Vec::new();
-        pi.extend_from_slice(&(body.len() as u32).to_be_bytes());
-        pi.extend_from_slice(&body);
-        let data = build_clpi_with_proginfo(100, &pi, None);
-        let clip = parse(&data).expect("should not panic");
-        assert!(clip.streams.is_empty());
-    }
-
-    /// parse_program_info rejects sci_len == 0 (`sci_len < 1` → return).
-    /// A zero-length stream_coding_info is unusable.
-    #[test]
-    fn program_info_zero_sci_len_yields_no_stream() {
-        let mut body = Vec::new();
-        body.push(0);
-        body.push(1);
-        body.extend_from_slice(&0u32.to_be_bytes());
-        body.extend_from_slice(&0u16.to_be_bytes());
-        body.push(1);
-        body.push(0);
-        body.extend_from_slice(&0x1011u16.to_be_bytes());
-        body.push(0); // sci_len = 0
-        let mut pi = Vec::new();
-        pi.extend_from_slice(&(body.len() as u32).to_be_bytes());
-        pi.extend_from_slice(&body);
-        let data = build_clpi_with_proginfo(100, &pi, None);
-        let clip = parse(&data).expect("should parse");
-        assert!(clip.streams.is_empty());
-    }
-
-    // ─────────────────────────────────────────────────────────────────────
-    // Section-offset gates in `parse`.
-    // ─────────────────────────────────────────────────────────────────────
-
-    /// A prog_info_start of 0 means "no ProgramInfo section" — the CLPI
-    /// header bytes at offset 0 must NOT be reinterpreted as a ProgramInfo
-    /// table. The fixture is crafted so that parsing from offset 0 WOULD
-    /// yield a stream (num_programs at [5], a second program header whose
-    /// num_streams byte at [20] is 1, then a well-formed stream record), so
-    /// the empty result can only come from the `prog_info_start > 0` gate.
-    #[test]
-    fn prog_info_start_zero_does_not_parse_header_as_program_info() {
-        let mut data = build_clpi(1000, None);
-        data[5] = 2; // num_programs = 2 if read from offset 0
-        // program 0 header = data[6..14]; its num_streams byte is data[12],
-        // which is prog_info_start's first byte and must stay 0.
-        data[20] = 1; // program 1 (header data[14..22]) declares 1 stream
-        data[22..24].copy_from_slice(&0x1011u16.to_be_bytes()); // pid
-        data[24] = 2; // sci_len
-        data[25] = 0x1B; // coding_type H.264
-        data[26] = 0x61; // video format 6 / rate 1
-        let clip = parse(&data).expect("should parse");
-        assert!(
-            clip.streams.is_empty(),
-            "prog_info_start == 0 must mean absent, got {:?}",
-            clip.streams
-        );
-    }
-
-    // ─────────────────────────────────────────────────────────────────────
-    // parse_program_info
-    // ─────────────────────────────────────────────────────────────────────
-
-    /// Secondary audio (0xA1 AC-3+ secondary, 0xA2 DTS-HD secondary) has the
-    /// same stream_coding_info layout as primary audio: sci[1] carries
-    /// audio_presentation_type in the high nibble and sampling_frequency in
-    /// the low nibble, sci[2..5] the ISO 639-2 language. Both sub-fields and
-    /// the language must be populated.
-    #[test]
-    fn program_info_secondary_audio_fields() {
-        for coding in [c_ac3_plus_secondary(), c_dts_hd_secondary()] {
-            let sci = vec![coding, 0x61, b'd', b'e', b'u'];
-            let pi = build_program_info(&[(0x1A00, sci)]);
-            let data = build_clpi_with_proginfo(100, &pi, None);
-            let clip = parse(&data).expect("should parse");
-            assert_eq!(clip.streams.len(), 1, "coding {coding:#04x}");
-            let s = &clip.streams[0];
-            assert_eq!(s.coding_type, coding);
-            // 0x61: high nibble 6, low nibble 1 — distinct values, so a
-            // swapped/ORed/XORed nibble extraction cannot pass.
-            assert_eq!(s.language, "deu", "coding {coding:#04x}");
-        }
-    }
-
-    fn c_ac3_plus_secondary() -> u8 {
-        crate::consts::coding_type::AC3_PLUS_SECONDARY
-    }
-    fn c_dts_hd_secondary() -> u8 {
-        crate::consts::coding_type::DTS_HD_SECONDARY
-    }
-
-    /// A stream_coding_info of exactly 1 byte (coding_type only) is the
-    /// minimum the parser accepts: the stream is recorded with its PID and
-    /// coding_type, and every sub-field that needs more bytes stays empty.
-    /// Notably a PG stream must NOT read sci[1..4] when only sci[0] exists.
-    #[test]
-    fn program_info_sci_len_one_yields_bare_stream() {
-        let pi = build_program_info(&[(0x1200, vec![0x90u8])]);
-        let data = build_clpi_with_proginfo(100, &pi, None);
-        let clip = parse(&data).expect("should not panic");
-        assert_eq!(clip.streams.len(), 1);
-        assert_eq!(clip.streams[0].pid, 0x1200);
-        assert_eq!(clip.streams[0].coding_type, 0x90);
-        assert_eq!(clip.streams[0].language, "");
-    }
-
-    /// Below the 6-byte ProgramInfo header (length(4)+reserved(1)+
-    /// num_programs(1)) there is nothing to read; the length guard must fire
-    /// before `data[5]`.
-    #[test]
-    fn program_info_below_header_size_is_empty() {
-        for len in 0..6usize {
-            assert!(parse_program_info(&vec![0u8; len]).is_empty(), "len={len}");
-        }
-    }
-
-    /// A declared program whose 8-byte header runs past the section end must
-    /// stop before reading num_streams at `data[pos + 6]`.
-    #[test]
-    fn program_info_truncated_program_header_is_empty() {
-        // length(4) + reserved(1) + num_programs=1 (1) + only 4 of the 8
-        // program-header bytes.
-        let mut data = vec![0u8; 6];
-        data[5] = 1;
-        data.extend_from_slice(&[0u8; 4]);
-        assert!(parse_program_info(&data).is_empty());
-    }
-
-    /// A declared stream whose 3-byte header (pid(2)+sci_len(1)) runs past
-    /// the section end must stop before reading the PID.
-    #[test]
-    fn program_info_truncated_stream_header_is_empty() {
-        let mut data = vec![0u8; 6];
-        data[5] = 1; // num_programs
-        data.extend_from_slice(&[0u8; 8]); // program header
-        data[6 + 6] = 1; // num_streams = 1
-        data.extend_from_slice(&[0u8; 2]); // only 2 of the 3 stream bytes
-        assert_eq!(data.len(), 16);
-        assert!(parse_program_info(&data).is_empty());
-    }
-
-    // ─────────────────────────────────────────────────────────────────────
-    // parse_cpi — low-level fixtures
-    // ─────────────────────────────────────────────────────────────────────
 }

src/consts.rs

@@ -1,137 +0,0 @@
-//! Physical media constants — the single source of truth.
-//!
-//! Naming convention: a constant is prefixed by the **narrowest scope where it
-//! is valid**. A value common to all optical media carries no prefix; a value
-//! specific to a container/format/disc-type is prefixed by it
-//! (`TS_`, `BD_`, …). Define each physical quantity here exactly once and import
-//! it — never re-declare a bare literal or a local copy.
-
-/// Bytes per logical sector on every optical medium freemkv reads
-/// (Blu-ray, DVD-Video, CD-ROM Mode 1). Universal — hence unprefixed.
-///
-/// `usize` because its dominant use is buffer sizing and slice indexing, where
-/// Rust *requires* `usize` (`vec![0u8; SECTOR_BYTES]`, `buf.len() < SECTOR_BYTES`).
-/// For byte-offset / capacity arithmetic — which is `u64` because a disc can
-/// exceed 4 GiB — use [`SECTOR_BYTES_U64`] instead of casting at each site.
-pub const SECTOR_BYTES: usize = 2048;
-
-/// [`SECTOR_BYTES`] as `u64`, for byte-offset and capacity arithmetic. The
-/// single `usize → u64` boundary cast lives here, once, so offset math across
-/// the workspace reads as `sectors * SECTOR_BYTES_U64` with no per-site cast.
-pub const SECTOR_BYTES_U64: u64 = SECTOR_BYTES as u64;
-
-/// Milliseconds per second. For turning a byte count ÷ bytes-per-second into a
-/// movie-time figure (`bytes / bps * MILLIS_PER_SEC`) without a bare `1000.0`.
-pub const MILLIS_PER_SEC: f64 = 1_000.0;
-
-/// Bytes per MPEG-2 transport-stream packet. Common to all MPEG-TS, not just
-/// Blu-ray — prefixed by the format, not a disc type.
-pub const TS_PACKET_BYTES: usize = 188;
-
-/// Bytes in an MPEG-2 transport-stream packet header: sync byte, the
-/// flags/PID word, and the adaptation/continuity byte.
-pub const TS_HEADER_BYTES: usize = 4;
-
-/// Bytes in the arrival-timestamp prefix a Blu-ray M2TS prepends to each TS
-/// packet to form a source packet. Same width as a TS header but a distinct
-/// quantity ([`TS_HEADER_BYTES`]) — do not conflate.
-pub const BD_TIMESTAMP_PREFIX_BYTES: usize = 4;
-
-/// Bytes of payload in an MPEG-2 transport-stream packet:
-/// [`TS_PACKET_BYTES`] minus the [`TS_HEADER_BYTES`] header.
-pub const TS_PAYLOAD_BYTES: usize = TS_PACKET_BYTES - TS_HEADER_BYTES;
-
-/// Bytes per Blu-ray M2TS *source packet*: a TS packet ([`TS_PACKET_BYTES`])
-/// prefixed with the [`BD_TIMESTAMP_PREFIX_BYTES`] arrival-timestamp header.
-/// A BDAV/M2TS construct only — DVD VOBs have no source packets — hence `BD_`.
-pub const BD_SOURCE_PACKET_BYTES: usize = TS_PACKET_BYTES + BD_TIMESTAMP_PREFIX_BYTES;
-
-/// Elementary-stream coding-type codes — the single source of truth for the
-/// byte that identifies a stream's codec.
-///
-/// This is one registry used in two places that share the same value space:
-/// the MPEG-TS PMT `stream_type` (ISO/IEC 13818-1 Table 2-34) and the Blu-ray
-/// STN/CLPI `stream_coding_type` (BD-ROM Part 3). The standardized video codes
-/// (`0x02`, `0x1B`, `0x24`) are ISO assignments (ISO/IEC 13818-1 Table 2-34);
-/// `0xEA` (VC-1) is a BD-ROM convention in the ISO user-private range. The
-/// `0x80..=0xA2` audio/graphics codes also sit in the user-private range and follow the
-/// Blu-ray Disc Association / ATSC A/52 convention. Because every consumer
-/// reads or writes this single byte, the family is unprefixed — the scope is
-/// "any elementary stream freemkv parses or muxes".
-///
-/// Each constant is `u8`: the spec defines an 8-bit field and the code compares
-/// it directly against a byte read from the buffer, so no casts are needed.
-pub mod coding_type {
-    /// MPEG-2 video (ISO/IEC 13818-1 Table 2-34).
-    pub const MPEG2_VIDEO: u8 = 0x02;
-    /// H.264 / AVC video (ISO/IEC 13818-1 Table 2-34).
-    pub const H264: u8 = 0x1B;
-    /// H.264 / MVC dependent view (Blu-ray 3D right-eye substream). Carried in
-    /// the SSIF interleaved stream under its own PID; the base view is [`H264`].
-    /// ISO/IEC 13818-1 stream_type 0x20 (MVC video sub-bitstream).
-    pub const H264_MVC: u8 = 0x20;
-    /// HEVC / H.265 video (ISO/IEC 13818-1 Table 2-34, 2015 amendment).
-    pub const HEVC: u8 = 0x24;
-    /// SMPTE VC-1 video (BD-ROM convention, ISO user-private range).
-    pub const VC1: u8 = 0xEA;
-
-    /// LPCM audio (BD-ROM convention).
-    pub const LPCM: u8 = 0x80;
-    /// Dolby Digital (AC-3) audio (BD-ROM / ATSC A/52 convention).
-    pub const AC3: u8 = 0x81;
-    /// DTS audio (BD-ROM convention).
-    pub const DTS: u8 = 0x82;
-    /// Dolby TrueHD audio (BD-ROM convention).
-    pub const TRUEHD: u8 = 0x83;
-    /// Dolby Digital Plus (E-AC-3 / AC-3+) audio (BD-ROM convention).
-    pub const AC3_PLUS: u8 = 0x84;
-    /// DTS-HD High Resolution audio (BD-ROM Part 3-1).
-    pub const DTS_HD_HR: u8 = 0x85;
-    /// DTS-HD Master Audio (lossless) (BD-ROM Part 3-1).
-    pub const DTS_HD_MA: u8 = 0x86;
-
-    /// Presentation Graphics — PG subtitle stream (BD-ROM HDMV).
-    pub const PG: u8 = 0x90;
-    /// Interactive Graphics — IG / BD-J menu overlay, NOT a subtitle (BD-ROM HDMV).
-    pub const IG: u8 = 0x91;
-    /// Text subtitle stream (BD-ROM HDMV).
-    pub const TEXT_SUBTITLE: u8 = 0x92;
-
-    /// Secondary Dolby Digital Plus audio (BD-ROM convention).
-    pub const AC3_PLUS_SECONDARY: u8 = 0xA1;
-    /// Secondary DTS-HD audio — DTS Express / DTS-HD LBR, a LOSSY low-bitrate
-    /// stream for picture-in-picture and BD-J mixing (BD-ROM Part 3
-    /// `stream_coding_type` table). The lossless primary is [`DTS_HD_MA`]
-    /// (0x86); this code is its lossy secondary counterpart, parallel to
-    /// [`AC3_PLUS_SECONDARY`] (0xA1) on the Dolby side.
-    pub const DTS_HD_SECONDARY: u8 = 0xA2;
-}
-
-/// MPEG PES `stream_id` codes — the byte after the `00 00 01` start-code prefix
-/// that identifies an elementary stream's role in a PES packet (ISO/IEC
-/// 13818-1 Table 2-22). Shared by the program-stream demuxer and the TS/M2TS
-/// muxers, so defined here once. Each is `u8` (matches the byte on the wire).
-pub mod pes_stream_id {
-    /// Video stream (`110x xxxx`; freemkv emits the base id `0xE0`).
-    pub const VIDEO: u8 = 0xE0;
-    /// system_header start code — the MPEG-PS `00 00 01 BB` structural header
-    /// (rate/bound bounds), never an elementary stream. On a DVD NAV pack it
-    /// follows the pack header, so it lands at sector offset 0x11.
-    pub const SYSTEM_HEADER: u8 = 0xBB;
-    /// private_stream_1 — AC-3 / DTS / LPCM / PGS subtitle payloads.
-    pub const PRIVATE_STREAM_1: u8 = 0xBD;
-    /// padding_stream — stuffing bytes only, no payload to demux.
-    pub const PADDING_STREAM: u8 = 0xBE;
-    /// private_stream_2 — DVD navigation (PCI/DSI); carries no muxable ES.
-    pub const PRIVATE_STREAM_2: u8 = 0xBF;
-
-    /// Highest video stream_id — the `110x xxxx` video range tops out at 0xEF.
-    pub const VIDEO_MAX: u8 = 0xEF;
-
-    /// Inclusive range of every PES `stream_id` that carries demuxable payload:
-    /// [`PRIVATE_STREAM_1`] (0xBD) through [`VIDEO_MAX`] (0xEF) — i.e. private
-    /// stream 1/2, padding, MPEG audio (0xC0-0xDF) and video (0xE0-0xEF). The
-    /// pack (0xBA), system-header (0xBB) and program-end (0xB9) codes sit below
-    /// this range and are deliberately excluded: they're structural, not ES.
-    pub const PAYLOAD_RANGE: core::ops::RangeInclusive<u8> = PRIVATE_STREAM_1..=VIDEO_MAX;
-}

src/css/auth.rs

@@ -0,0 +1,639 @@
+//! CSS drive authentication — full key hierarchy.
+//!
+//! Protocol:
+//!   1. Bus authentication (challenge-response) → bus key
+//!   2. Read disc key block (READ DVD STRUCTURE) → XOR with bus key → decrypt with player keys → disc key
+//!   3. Read title key (REPORT KEY format 0x04) → XOR with bus key → decrypt with disc key → title key
+
+use crate::drive::Drive;
+use crate::error::{Error, Result};
+
+// ── Built-in public DVD CSS player keys ────────────────────────────────────
+//
+// These 31 5-byte player keys are long-public CSS inputs. With them
+// compiled in, DVD ripping works with no external key file required.
+
+const PLAYER_KEYS: [[u8; 5]; 31] = [
+    [0x01, 0xaf, 0xe3, 0x12, 0x80],
+    [0x12, 0x11, 0xca, 0x04, 0x3b],
+    [0x14, 0x0c, 0x9e, 0xd0, 0x09],
+    [0x14, 0x71, 0x35, 0xba, 0xe2],
+    [0x1a, 0xa4, 0x33, 0x21, 0xa6],
+    [0x26, 0xec, 0xc4, 0xa7, 0x4e],
+    [0x2c, 0xb2, 0xc1, 0x09, 0xee],
+    [0x2f, 0x25, 0x9e, 0x96, 0xdd],
+    [0x33, 0x2f, 0x49, 0x6c, 0xe0],
+    [0x35, 0x5b, 0xc1, 0x31, 0x0f],
+    [0x36, 0x67, 0xb2, 0xe3, 0x85],
+    [0x39, 0x3d, 0xf1, 0xf1, 0xbd],
+    [0x3b, 0x31, 0x34, 0x0d, 0x91],
+    [0x45, 0xed, 0x28, 0xeb, 0xd3],
+    [0x48, 0xb7, 0x6c, 0xce, 0x69],
+    [0x4b, 0x65, 0x0d, 0xc1, 0xee],
+    [0x4c, 0xbb, 0xf5, 0x5b, 0x23],
+    [0x51, 0x67, 0x67, 0xc5, 0xe0],
+    [0x53, 0x94, 0xe1, 0x75, 0xbf],
+    [0x57, 0x2c, 0x8b, 0x31, 0xae],
+    [0x63, 0xdb, 0x4c, 0x5b, 0x4a],
+    [0x7b, 0x1e, 0x5e, 0x2b, 0x57],
+    [0x85, 0xf3, 0x85, 0xa0, 0xe0],
+    [0xab, 0x1e, 0xe7, 0x7b, 0x72],
+    [0xab, 0x36, 0xe3, 0xeb, 0x76],
+    [0xb1, 0xb8, 0xf9, 0x38, 0x03],
+    [0xb8, 0x5d, 0xd8, 0x53, 0xbd],
+    [0xbf, 0x92, 0xc3, 0xb0, 0xe2],
+    [0xcf, 0x1a, 0xb2, 0xf8, 0x0a],
+    [0xec, 0xa0, 0xcf, 0xb3, 0xff],
+    [0xfc, 0x95, 0xa9, 0x87, 0x35],
+];
+
+// ── CryptKey tables ───────────────────────────────────────────────────────
+
+const CRYPT_TAB0: [u8; 256] = [
+    0xB7, 0xF4, 0x82, 0x57, 0xDA, 0x4D, 0xDB, 0xE2, 0x2F, 0x52, 0x1A, 0xA8, 0x68, 0x5A, 0x8A, 0xFF,
+    0xFB, 0x0E, 0x6D, 0x35, 0xF7, 0x5C, 0x76, 0x12, 0xCE, 0x25, 0x79, 0x29, 0x39, 0x62, 0x08, 0x24,
+    0xA5, 0x85, 0x7B, 0x56, 0x01, 0x23, 0x68, 0xCF, 0x0A, 0xE2, 0x5A, 0xED, 0x3D, 0x59, 0xB0, 0xA9,
+    0xB0, 0x2C, 0xF2, 0xB8, 0xEF, 0x32, 0xA9, 0x40, 0x80, 0x71, 0xAF, 0x1E, 0xDE, 0x8F, 0x58, 0x88,
+    0xB8, 0x3A, 0xD0, 0xFC, 0xC4, 0x1E, 0xB5, 0xA0, 0xBB, 0x3B, 0x0F, 0x01, 0x7E, 0x1F, 0x9F, 0xD9,
+    0xAA, 0xB8, 0x3D, 0x9D, 0x74, 0x1E, 0x25, 0xDB, 0x37, 0x56, 0x8F, 0x16, 0xBA, 0x49, 0x2B, 0xAC,
+    0xD0, 0xBD, 0x95, 0x20, 0xBE, 0x7A, 0x28, 0xD0, 0x51, 0x64, 0x63, 0x1C, 0x7F, 0x66, 0x10, 0xBB,
+    0xC4, 0x56, 0x1A, 0x04, 0x6E, 0x0A, 0xEC, 0x9C, 0xD6, 0xE8, 0x9A, 0x7A, 0xCF, 0x8C, 0xDB, 0xB1,
+    0xEF, 0x71, 0xDE, 0x31, 0xFF, 0x54, 0x3E, 0x5E, 0x07, 0x69, 0x96, 0xB0, 0xCF, 0xDD, 0x9E, 0x47,
+    0xC7, 0x96, 0x8F, 0xE4, 0x2B, 0x59, 0xC6, 0xEE, 0xB9, 0x86, 0x9A, 0x64, 0x84, 0x72, 0xE2, 0x5B,
+    0xA2, 0x96, 0x58, 0x99, 0x50, 0x03, 0xF5, 0x38, 0x4D, 0x02, 0x7D, 0xE7, 0x7D, 0x75, 0xA7, 0xB8,
+    0x67, 0x87, 0x84, 0x3F, 0x1D, 0x11, 0xE5, 0xFC, 0x1E, 0xD3, 0x83, 0x16, 0xA5, 0x29, 0xF6, 0xC7,
+    0x15, 0x61, 0x29, 0x1A, 0x43, 0x4F, 0x9B, 0xAF, 0xC5, 0x87, 0x34, 0x6C, 0x0F, 0x3B, 0xA8, 0x1D,
+    0x45, 0x58, 0x25, 0xDC, 0xA8, 0xA3, 0x3B, 0xD1, 0x79, 0x1B, 0x48, 0xF2, 0xE9, 0x93, 0x1F, 0xFC,
+    0xDB, 0x2A, 0x90, 0xA9, 0x8A, 0x3D, 0x39, 0x18, 0xA3, 0x8E, 0x58, 0x6C, 0xE0, 0x12, 0xBB, 0x25,
+    0xCD, 0x71, 0x22, 0xA2, 0x64, 0xC6, 0xE7, 0xFB, 0xAD, 0x94, 0x77, 0x04, 0x9A, 0x39, 0xCF, 0x7C,
+];
+
+const CRYPT_TAB1: [u8; 256] = [
+    0x8C, 0x47, 0xB0, 0xE1, 0xEB, 0xFC, 0xEB, 0x56, 0x10, 0xE5, 0x2C, 0x1A, 0x5D, 0xEF, 0xBE, 0x4F,
+    0x08, 0x75, 0x97, 0x4B, 0x0E, 0x25, 0x8E, 0x6E, 0x39, 0x5A, 0x87, 0x53, 0xC4, 0x1F, 0xF4, 0x5C,
+    0x4E, 0xE6, 0x99, 0x30, 0xE0, 0x42, 0x88, 0xAB, 0xE5, 0x85, 0xBC, 0x8F, 0xD8, 0x3C, 0x54, 0xC9,
+    0x53, 0x47, 0x18, 0xD6, 0x06, 0x5B, 0x41, 0x2C, 0x67, 0x1E, 0x41, 0x74, 0x33, 0xE2, 0xB4, 0xE0,
+    0x23, 0x29, 0x42, 0xEA, 0x55, 0x0F, 0x25, 0xB4, 0x24, 0x2C, 0x99, 0x13, 0xEB, 0x0A, 0x0B, 0xC9,
+    0xF9, 0x63, 0x67, 0x43, 0x2D, 0xC7, 0x7D, 0x07, 0x60, 0x89, 0xD1, 0xCC, 0xE7, 0x94, 0x77, 0x74,
+    0x9B, 0x7E, 0xD7, 0xE6, 0xFF, 0xBB, 0x68, 0x14, 0x1E, 0xA3, 0x25, 0xDE, 0x3A, 0xA3, 0x54, 0x7B,
+    0x87, 0x9D, 0x50, 0xCA, 0x27, 0xC3, 0xA4, 0x50, 0x91, 0x27, 0xD4, 0xB0, 0x82, 0x41, 0x97, 0x79,
+    0x94, 0x82, 0xAC, 0xC7, 0x8E, 0xA5, 0x4E, 0xAA, 0x78, 0x9E, 0xE0, 0x42, 0xBA, 0x28, 0xEA, 0xB7,
+    0x74, 0xAD, 0x35, 0xDA, 0x92, 0x60, 0x7E, 0xD2, 0x0E, 0xB9, 0x24, 0x5E, 0x39, 0x4F, 0x5E, 0x63,
+    0x09, 0xB5, 0xFA, 0xBF, 0xF1, 0x22, 0x55, 0x1C, 0xE2, 0x25, 0xDB, 0xC5, 0xD8, 0x50, 0x03, 0x98,
+    0xC4, 0xAC, 0x2E, 0x11, 0xB4, 0x38, 0x4D, 0xD0, 0xB9, 0xFC, 0x2D, 0x3C, 0x08, 0x04, 0x5A, 0xEF,
+    0xCE, 0x32, 0xFB, 0x4C, 0x92, 0x1E, 0x4B, 0xFB, 0x1A, 0xD0, 0xE2, 0x3E, 0xDA, 0x6E, 0x7C, 0x4D,
+    0x56, 0xC3, 0x3F, 0x42, 0xB1, 0x3A, 0x23, 0x4D, 0x6E, 0x84, 0x56, 0x68, 0xF4, 0x0E, 0x03, 0x64,
+    0xD0, 0xA9, 0x92, 0x2F, 0x8B, 0xBC, 0x39, 0x9C, 0xAC, 0x09, 0x5E, 0xEE, 0xE5, 0x97, 0xBF, 0xA5,
+    0xCE, 0xFA, 0x28, 0x2C, 0x6D, 0x4F, 0xEF, 0x77, 0xAA, 0x1B, 0x79, 0x8E, 0x97, 0xB4, 0xC3, 0xF4,
+];
+
+const CRYPT_TAB2: [u8; 256] = [
+    0xB7, 0x75, 0x81, 0xD5, 0xDC, 0xCA, 0xDE, 0x66, 0x23, 0xDF, 0x15, 0x26, 0x62, 0xD1, 0x83, 0x77,
+    0xE3, 0x97, 0x76, 0xAF, 0xE9, 0xC3, 0x6B, 0x8E, 0xDA, 0xB0, 0x6E, 0xBF, 0x2B, 0xF1, 0x19, 0xB4,
+    0x95, 0x34, 0x48, 0xE4, 0x37, 0x94, 0x5D, 0x7B, 0x36, 0x5F, 0x65, 0x53, 0x07, 0xE2, 0x89, 0x11,
+    0x98, 0x85, 0xD9, 0x12, 0xC1, 0x9D, 0x84, 0xEC, 0xA4, 0xD4, 0x88, 0xB8, 0xFC, 0x2C, 0x79, 0x28,
+    0xD8, 0xDB, 0xB3, 0x1E, 0xA2, 0xF9, 0xD0, 0x44, 0xD7, 0xD6, 0x60, 0xEF, 0x14, 0xF4, 0xF6, 0x31,
+    0xD2, 0x41, 0x46, 0x67, 0x0A, 0xE1, 0x58, 0x27, 0x43, 0xA3, 0xF8, 0xE0, 0xC8, 0xBA, 0x5A, 0x5C,
+    0x80, 0x6C, 0xC6, 0xF2, 0xE8, 0xAD, 0x7D, 0x04, 0x0D, 0xB9, 0x3C, 0xC2, 0x25, 0xBD, 0x49, 0x63,
+    0x8C, 0x9F, 0x51, 0xCE, 0x20, 0xC5, 0xA1, 0x50, 0x92, 0x2D, 0xDD, 0xBC, 0x8D, 0x4F, 0x9A, 0x71,
+    0x2F, 0x30, 0x1D, 0x73, 0x39, 0x13, 0xFB, 0x1A, 0xCB, 0x24, 0x59, 0xFE, 0x05, 0x96, 0x57, 0x0F,
+    0x1F, 0xCF, 0x54, 0xBE, 0xF5, 0x06, 0x1B, 0xB2, 0x6D, 0xD3, 0x4D, 0x32, 0x56, 0x21, 0x33, 0x0B,
+    0x52, 0xE7, 0xAB, 0xEB, 0xA6, 0x74, 0x00, 0x4C, 0xB1, 0x7F, 0x82, 0x99, 0x87, 0x0E, 0x5E, 0xC0,
+    0x8F, 0xEE, 0x6F, 0x55, 0xF3, 0x7E, 0x08, 0x90, 0xFA, 0xB6, 0x64, 0x70, 0x47, 0x4A, 0x17, 0xA7,
+    0xB5, 0x40, 0x8A, 0x38, 0xE5, 0x68, 0x3E, 0x8B, 0x69, 0xAA, 0x9B, 0x42, 0xA5, 0x10, 0x01, 0x35,
+    0xFD, 0x61, 0x9E, 0xE6, 0x16, 0x9C, 0x86, 0xED, 0xCD, 0x2E, 0xFF, 0xC4, 0x5B, 0xA0, 0xAE, 0xCC,
+    0x4B, 0x3B, 0x03, 0xBB, 0x1C, 0x2A, 0xAC, 0x0C, 0x3F, 0x93, 0xC7, 0x72, 0x7A, 0x09, 0x22, 0x3D,
+    0x45, 0x78, 0xA9, 0xA8, 0xEA, 0xC9, 0x6A, 0xF7, 0x29, 0x91, 0xF0, 0x02, 0x18, 0x3A, 0x4E, 0x7C,
+];
+
+const CRYPT_TAB3: [u8; 288] = [
+    0x73, 0x51, 0x95, 0xE1, 0x12, 0xE4, 0xC0, 0x58, 0xEE, 0xF2, 0x08, 0x1B, 0xA9, 0xFA, 0x98, 0x4C,
+    0xA7, 0x33, 0xE2, 0x1B, 0xA7, 0x6D, 0xF5, 0x30, 0x97, 0x1D, 0xF3, 0x02, 0x60, 0x5A, 0x82, 0x0F,
+    0x91, 0xD0, 0x9C, 0x10, 0x39, 0x7A, 0x83, 0x85, 0x3B, 0xB2, 0xB8, 0xAE, 0x0C, 0x09, 0x52, 0xEA,
+    0x1C, 0xE1, 0x8D, 0x66, 0x4F, 0xF3, 0xDA, 0x92, 0x29, 0xB9, 0xD5, 0xC5, 0x77, 0x47, 0x22, 0x53,
+    0x14, 0xF7, 0xAF, 0x22, 0x64, 0xDF, 0xC6, 0x72, 0x12, 0xF3, 0x75, 0xDA, 0xD7, 0xD7, 0xE5, 0x02,
+    0x9E, 0xED, 0xDA, 0xDB, 0x4C, 0x47, 0xCE, 0x91, 0x06, 0x06, 0x6D, 0x55, 0x8B, 0x19, 0xC9, 0xEF,
+    0x8C, 0x80, 0x1A, 0x0E, 0xEE, 0x4B, 0xAB, 0xF2, 0x08, 0x5C, 0xE9, 0x37, 0x26, 0x5E, 0x9A, 0x90,
+    0x00, 0xF3, 0x0D, 0xB2, 0xA6, 0xA3, 0xF7, 0x26, 0x17, 0x48, 0x88, 0xC9, 0x0E, 0x2C, 0xC9, 0x02,
+    0xE7, 0x18, 0x05, 0x4B, 0xF3, 0x39, 0xE1, 0x20, 0x02, 0x0D, 0x40, 0xC7, 0xCA, 0xB9, 0x48, 0x30,
+    0x57, 0x67, 0xCC, 0x06, 0xBF, 0xAC, 0x81, 0x08, 0x24, 0x7A, 0xD4, 0x8B, 0x19, 0x8E, 0xAC, 0xB4,
+    0x5A, 0x0F, 0x73, 0x13, 0xAC, 0x9E, 0xDA, 0xB6, 0xB8, 0x96, 0x5B, 0x60, 0x88, 0xE1, 0x81, 0x3F,
+    0x07, 0x86, 0x37, 0x2D, 0x79, 0x14, 0x52, 0xEA, 0x73, 0xDF, 0x3D, 0x09, 0xC8, 0x25, 0x48, 0xD8,
+    0x75, 0x60, 0x9A, 0x08, 0x27, 0x4A, 0x2C, 0xB9, 0xA8, 0x8B, 0x8A, 0x73, 0x62, 0x37, 0x16, 0x02,
+    0xBD, 0xC1, 0x0E, 0x56, 0x54, 0x3E, 0x14, 0x5F, 0x8C, 0x8F, 0x6E, 0x75, 0x1C, 0x07, 0x39, 0x7B,
+    0x4B, 0xDB, 0xD3, 0x4B, 0x1E, 0xC8, 0x7E, 0xFE, 0x3E, 0x72, 0x16, 0x83, 0x7D, 0xEE, 0xF5, 0xCA,
+    0xC5, 0x18, 0xF9, 0xD8, 0x68, 0xAB, 0x38, 0x85, 0xA8, 0xF0, 0xA1, 0x73, 0x9F, 0x5D, 0x19, 0x0B,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x33, 0x72, 0x39, 0x25, 0x67, 0x26, 0x6D, 0x71,
+    0x36, 0x77, 0x3C, 0x20, 0x62, 0x23, 0x68, 0x74, 0xC3, 0x82, 0xC9, 0x15, 0x57, 0x16, 0x5D, 0x81,
+];
+
+const VARIANTS: [u8; 32] = [
+    0xB7, 0x74, 0x85, 0xD0, 0xCC, 0xDB, 0xCA, 0x73, 0x03, 0xFE, 0x31, 0x03, 0x52, 0xE0, 0xB7, 0x42,
+    0x63, 0x16, 0xF2, 0x2A, 0x79, 0x52, 0xFF, 0x1B, 0x7A, 0x11, 0xCA, 0x1A, 0x9B, 0x40, 0xAD, 0x01,
+];
+
+const SECRET: [u8; 5] = [0x55, 0xD6, 0xC4, 0xC5, 0x28];
+
+const PERM_CHALLENGE: [[usize; 10]; 3] = [
+    [1, 3, 0, 7, 5, 2, 9, 6, 4, 8],
+    [6, 1, 9, 3, 8, 5, 7, 4, 0, 2],
+    [4, 0, 3, 5, 7, 2, 8, 6, 1, 9],
+];
+
+const PERM_VARIANT: [[u8; 32]; 2] = [
+    [
+        0x0A, 0x08, 0x0E, 0x0C, 0x0B, 0x09, 0x0F, 0x0D, 0x1A, 0x18, 0x1E, 0x1C, 0x1B, 0x19, 0x1F,
+        0x1D, 0x02, 0x00, 0x06, 0x04, 0x03, 0x01, 0x07, 0x05, 0x12, 0x10, 0x16, 0x14, 0x13, 0x11,
+        0x17, 0x15,
+    ],
+    [
+        0x12, 0x1A, 0x16, 0x1E, 0x02, 0x0A, 0x06, 0x0E, 0x10, 0x18, 0x14, 0x1C, 0x00, 0x08, 0x04,
+        0x0C, 0x13, 0x1B, 0x17, 0x1F, 0x03, 0x0B, 0x07, 0x0F, 0x11, 0x19, 0x15, 0x1D, 0x01, 0x09,
+        0x05, 0x0D,
+    ],
+];
+
+// ── SCSI constants ────────────────────────────────────────────────────────
+
+const SCSI_READ_DVD_STRUCTURE: u8 = 0xAD;
+
+// ── Public API ────────────────────────────────────────────────────────────
+
+/// Perform CSS bus authentication only.
+pub fn authenticate(drive: &mut Drive) -> Result<()> {
+    let (_, _) = bus_auth(drive)?;
+    Ok(())
+}
+
+/// Full CSS key extraction: bus auth → disc key → title key.
+pub fn authenticate_and_read_title_key(drive: &mut Drive, lba: u32) -> Result<[u8; 5]> {
+    // Session 1: bus auth → disc key (AGID consumed by READ_DVD_STRUCTURE)
+    let (agid, bus_key) = bus_auth(drive)?;
+    let disc_key = read_disc_key(drive, agid, &bus_key)?;
+
+    // Session 2: fresh bus auth → title key (needs separate AGID)
+    let (agid2, bus_key2) = bus_auth(drive)?;
+    let encrypted_title = read_raw_title_key(drive, agid2, lba)?;
+
+    // Decrypt title key: XOR with bus key, then decrypt with disc key
+    let mut title_key = [0u8; 5];
+    for i in 0..5 {
+        title_key[i] = encrypted_title[i] ^ bus_key2[i];
+    }
+
+    if title_key == [0u8; 5] {
+        return Ok(title_key);
+    }
+
+    let title_key = super::lfsr::decrypt_key(0xFF, &disc_key, &title_key);
+    Ok(title_key)
+}
+
+// ── Step 1: Bus Authentication ────────────────────────────────────────────
+
+fn bus_auth(drive: &mut Drive) -> Result<(u8, [u8; 5])> {
+    let scsi = drive.scsi_mut();
+
+    // Invalidate all AGIDs via REPORT KEY format 0x3F
+    for agid in 0..4u8 {
+        let mut cdb = [0u8; 12];
+        cdb[0] = crate::scsi::SCSI_REPORT_KEY;
+        // alloc_len = 0 (no data transfer)
+        cdb[10] = (agid << 6) | 0x3F;
+        let mut buf = [0u8; 8];
+        let _ = scsi.execute(
+            &cdb,
+            crate::scsi::DataDirection::FromDevice,
+            &mut buf,
+            5_000,
+        );
+    }
+
+    // Allocate AGID
+    let mut buf = [0u8; 8];
+    scsi.execute(
+        &report_key_cdb(0, 0x00, 8),
+        crate::scsi::DataDirection::FromDevice,
+        &mut buf,
+        5_000,
+    )
+    .map_err(|_| Error::CssAuthFailed)?;
+    let agid = (buf[7] >> 6) & 0x03;
+
+    // Host sends challenge
+    let host_challenge: [u8; 10] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+    let mut hc_buf = [0u8; 16];
+    hc_buf[0] = 0x00;
+    hc_buf[1] = 0x0E;
+    for i in 0..10 {
+        hc_buf[4 + i] = host_challenge[9 - i];
+    }
+    scsi.execute(
+        &send_key_cdb(agid, 0x01, 16),
+        crate::scsi::DataDirection::ToDevice,
+        &mut hc_buf,
+        5_000,
+    )
+    .map_err(|_| Error::CssAuthFailed)?;
+
+    // Get Key1 from drive
+    let mut dk_buf = [0u8; 12];
+    scsi.execute(
+        &report_key_cdb(agid, 0x02, 12),
+        crate::scsi::DataDirection::FromDevice,
+        &mut dk_buf,
+        5_000,
+    )
+    .map_err(|_| Error::CssAuthFailed)?;
+    let mut key1 = [0u8; 5];
+    for i in 0..5 {
+        key1[i] = dk_buf[4 + (4 - i)];
+    }
+
+    // Brute-force variant (0-31)
+    let mut variant: Option<u8> = None;
+    for v in 0..32u8 {
+        if crypt_key(0, v, &host_challenge) == key1 {
+            variant = Some(v);
+            break;
+        }
+    }
+    let variant = variant.ok_or(Error::CssAuthFailed)?;
+
+    // Get drive challenge
+    let mut dc_buf = [0u8; 16];
+    scsi.execute(
+        &report_key_cdb(agid, 0x01, 16),
+        crate::scsi::DataDirection::FromDevice,
+        &mut dc_buf,
+        5_000,
+    )
+    .map_err(|_| Error::CssAuthFailed)?;
+    let mut drive_challenge = [0u8; 10];
+    for i in 0..10 {
+        drive_challenge[i] = dc_buf[4 + (9 - i)];
+    }
+
+    // Compute Key2 and send it
+    let key2 = crypt_key(1, variant, &drive_challenge);
+    let mut hk_buf = [0u8; 12];
+    hk_buf[0] = 0x00;
+    hk_buf[1] = 0x0A;
+    for i in 0..5 {
+        hk_buf[4 + i] = key2[4 - i];
+    }
+    scsi.execute(
+        &send_key_cdb(agid, 0x03, 12),
+        crate::scsi::DataDirection::ToDevice,
+        &mut hk_buf,
+        5_000,
+    )
+    .map_err(|_| Error::CssAuthFailed)?;
+
+    // Bus key = CryptKey(2, variant, key1 || key2)
+    let mut combined = [0u8; 10];
+    combined[..5].copy_from_slice(&key1);
+    combined[5..].copy_from_slice(&key2);
+    let bus_key = crypt_key(2, variant, &combined);
+
+    Ok((agid, bus_key))
+}
+
+// ── Step 2: Disc Key ──────────────────────────────────────────────────────
+
+fn read_disc_key(drive: &mut Drive, agid: u8, bus_key: &[u8; 5]) -> Result<[u8; 5]> {
+    let scsi = drive.scsi_mut();
+
+    // READ DVD STRUCTURE, format 0x02 (disc key), 2048+4 bytes
+    let alloc_len: u16 = 2048 + 4;
+    let mut cdb = [0u8; 12];
+    cdb[0] = SCSI_READ_DVD_STRUCTURE;
+    // bytes 2-5: address = 0
+    cdb[6] = 0; // layer
+    cdb[7] = 0x02; // format = disc key
+    cdb[8] = (alloc_len >> 8) as u8;
+    cdb[9] = alloc_len as u8;
+    cdb[10] = agid << 6;
+
+    let mut buf = vec![0u8; alloc_len as usize];
+    let dvd_result = scsi.execute(
+        &cdb,
+        crate::scsi::DataDirection::FromDevice,
+        &mut buf,
+        5_000,
+    );
+    dvd_result.map_err(|_| Error::CssAuthFailed)?;
+
+    // Disc key block starts at offset 4 (skip 4-byte header)
+    let disc_key_block = &mut buf[4..4 + 2048];
+
+    // XOR with reversed bus key (per libdvdcss)
+    for (i, byte) in disc_key_block.iter_mut().enumerate() {
+        *byte ^= bus_key[4 - (i % 5)];
+    }
+
+    // Try each player key against each of 408 disc key entries.
+    // Each entry in the block is the disc key encrypted with a specific player key.
+    // We try all known player keys and verify by checking that two different
+    // entries produce the same disc key.
+    let mut candidates: Vec<([u8; 5], usize, usize)> = Vec::new(); // (disc_key, pk_idx, pos)
+
+    for (pk_idx, player_key) in PLAYER_KEYS.iter().enumerate() {
+        for pos in 0..408 {
+            let offset = pos * 5;
+            if offset + 5 > disc_key_block.len() {
+                break;
+            }
+            let mut enc = [0u8; 5];
+            enc.copy_from_slice(&disc_key_block[offset..offset + 5]);
+            let candidate = super::lfsr::decrypt_key(0x00, player_key, &enc);
+
+            // Check if any previous candidate matches (same disc key from different entry/pk)
+            for (prev, _, _) in &candidates {
+                if *prev == candidate {
+                    return Ok(candidate);
+                }
+            }
+            candidates.push((candidate, pk_idx, pos));
+        }
+    }
+
+    Err(Error::CssAuthFailed)
+}
+
+// ── Step 3: Title Key ─────────────────────────────────────────────────────
+
+/// Read the raw (bus-encrypted) title key bytes from the drive.
+fn read_raw_title_key(drive: &mut Drive, agid: u8, lba: u32) -> Result<[u8; 5]> {
+    let scsi = drive.scsi_mut();
+    let mut cdb = [0u8; 12];
+    cdb[0] = crate::scsi::SCSI_REPORT_KEY;
+    cdb[2] = (lba >> 24) as u8;
+    cdb[3] = (lba >> 16) as u8;
+    cdb[4] = (lba >> 8) as u8;
+    cdb[5] = lba as u8;
+    cdb[8] = 0x00;
+    cdb[9] = 0x0C;
+    cdb[10] = (agid << 6) | 0x04;
+
+    let mut buf = [0u8; 12];
+    let result = scsi.execute(
+        &cdb,
+        crate::scsi::DataDirection::FromDevice,
+        &mut buf,
+        5_000,
+    );
+    result.map_err(|_| Error::CssAuthFailed)?;
+
+    let mut key = [0u8; 5];
+    for i in 0..5 {
+        key[i] = buf[5 + (4 - i)];
+    }
+    Ok(key)
+}
+
+#[allow(dead_code)]
+fn read_title_key(
+    drive: &mut Drive,
+    agid: u8,
+    lba: u32,
+    bus_key: &[u8; 5],
+    disc_key: &[u8; 5],
+) -> Result<[u8; 5]> {
+    let scsi = drive.scsi_mut();
+
+    let mut cdb = [0u8; 12];
+    cdb[0] = crate::scsi::SCSI_REPORT_KEY;
+    cdb[2] = (lba >> 24) as u8;
+    cdb[3] = (lba >> 16) as u8;
+    cdb[4] = (lba >> 8) as u8;
+    cdb[5] = lba as u8;
+    cdb[8] = 0x00;
+    cdb[9] = 0x0C;
+    cdb[10] = (agid << 6) | 0x04;
+
+    let mut buf = [0u8; 12];
+    let tk_result = scsi.execute(
+        &cdb,
+        crate::scsi::DataDirection::FromDevice,
+        &mut buf,
+        5_000,
+    );
+    tk_result.map_err(|_| Error::CssAuthFailed)?;
+
+    // Title key at bytes 5..10, byte-reversed
+    let mut title_key = [0u8; 5];
+    for i in 0..5 {
+        title_key[i] = buf[5 + (4 - i)];
+    }
+
+    // XOR with reversed bus key (same pattern as disc key block)
+    for i in 0..5 {
+        title_key[i] ^= bus_key[4 - i];
+    }
+
+    // Check for null key (title not encrypted)
+    if title_key == [0u8; 5] {
+        return Ok(title_key);
+    }
+
+    // Decrypt with disc key (invert=0xFF for title keys)
+    let title_key = super::lfsr::decrypt_key(0xFF, disc_key, &title_key);
+
+    Ok(title_key)
+}
+
+// ── CSSCryptKey ───────────────────────────────────────────────────────────
+
+/// Exposed for testing only.
+pub fn test_crypt_key(key_type: usize, variant: u8, challenge: &[u8; 10]) -> [u8; 5] {
+    crypt_key(key_type, variant, challenge)
+}
+
+fn crypt_key(key_type: usize, variant: u8, challenge: &[u8; 10]) -> [u8; 5] {
+    let perm = &PERM_CHALLENGE[key_type];
+    let mut scratch = [0u8; 10];
+    for i in 0..10 {
+        scratch[i] = challenge[perm[i]];
+    }
+
+    let css_variant = match key_type {
+        0 => variant as usize,
+        1 => PERM_VARIANT[0][variant as usize] as usize,
+        _ => PERM_VARIANT[1][variant as usize] as usize,
+    };
+
+    let cse = VARIANTS[css_variant] ^ CRYPT_TAB2[css_variant];
+
+    let mut tmp1 = [0u8; 5];
+    for i in 0..5 {
+        tmp1[i] = scratch[5 + i] ^ SECRET[i] ^ CRYPT_TAB2[i];
+    }
+
+    let mut lfsr0: u32 = ((tmp1[0] as u32) << 17)
+        | ((tmp1[1] as u32) << 9)
+        | (((tmp1[2] as u32) & !7) << 1)
+        | 8
+        | (tmp1[2] as u32 & 7);
+
+    let mut lfsr1: u32 = ((tmp1[3] as u32) << 9) | 0x100 | (tmp1[4] as u32);
+
+    let mut bits = [0u8; 30];
+    let mut carry: u32 = 0;
+    for idx in (0..30).rev() {
+        let mut val: u8 = 0;
+        for bit in 0..8u8 {
+            let lfsr0_out = ((lfsr0 >> 24) ^ (lfsr0 >> 21) ^ (lfsr0 >> 20) ^ (lfsr0 >> 12)) & 1;
+            lfsr0 = ((lfsr0 << 1) | lfsr0_out) & 0x1FFFFFF;
+
+            let lfsr1_out = ((lfsr1 >> 16) ^ (lfsr1 >> 2)) & 1;
+            lfsr1 = ((lfsr1 << 1) | lfsr1_out) & 0x1FFFF;
+
+            let combined = ((!lfsr1_out) & 1) + carry + ((!lfsr0_out) & 1);
+            carry = (combined >> 1) & 1;
+            val |= ((combined & 1) as u8) << bit;
+        }
+        bits[idx] = val;
+    }
+
+    let mut tmp1 = [scratch[0], scratch[1], scratch[2], scratch[3], scratch[4]];
+    let mut tmp2 = [0u8; 5];
+
+    // Round 1: bits[25..29] ^ scratch -> tmp1 (term from original scratch)
+    {
+        let mut term: u8 = 0;
+        for i in (0..5usize).rev() {
+            let idx = (bits[25 + i] ^ tmp1[i]) as usize;
+            let idx2 = (CRYPT_TAB1[idx] ^ (!CRYPT_TAB2[idx]) ^ cse) as usize;
+            tmp1[i] = CRYPT_TAB2[idx2] ^ CRYPT_TAB3[idx2] ^ term;
+            term = scratch[i]; // original challenge, NOT modified tmp1
+        }
+        tmp1[4] ^= tmp1[0];
+    }
+
+    // Round 2
+    {
+        let mut term: u8 = 0;
+        for i in (0..5usize).rev() {
+            let idx = (bits[20 + i] ^ tmp1[i]) as usize;
+            let idx2 = (CRYPT_TAB1[idx] ^ (!CRYPT_TAB2[idx]) ^ cse) as usize;
+            tmp2[i] = CRYPT_TAB2[idx2] ^ CRYPT_TAB3[idx2] ^ term;
+            term = tmp1[i];
+        }
+        tmp2[4] ^= tmp2[0];
+    }
+
+    // Round 3 (uses CRYPT_TAB0)
+    {
+        let mut term: u8 = 0;
+        for i in (0..5usize).rev() {
+            let idx = (bits[15 + i] ^ tmp2[i]) as usize;
+            let idx2 = (CRYPT_TAB1[idx] ^ (!CRYPT_TAB2[idx]) ^ cse) as usize;
+            let idx3 = (CRYPT_TAB2[idx2] ^ CRYPT_TAB3[idx2] ^ term) as usize;
+            tmp1[i] = CRYPT_TAB0[idx3] ^ CRYPT_TAB2[idx3];
+            term = tmp2[i];
+        }
+        tmp1[4] ^= tmp1[0];
+    }
+
+    // Round 4 (uses CRYPT_TAB0)
+    {
+        let mut term: u8 = 0;
+        for i in (0..5usize).rev() {
+            let idx = (bits[10 + i] ^ tmp1[i]) as usize;
+            let idx2 = (CRYPT_TAB1[idx] ^ (!CRYPT_TAB2[idx]) ^ cse) as usize;
+            let idx3 = (CRYPT_TAB2[idx2] ^ CRYPT_TAB3[idx2] ^ term) as usize;
+            tmp2[i] = CRYPT_TAB0[idx3] ^ CRYPT_TAB2[idx3];
+            term = tmp1[i];
+        }
+        tmp2[4] ^= tmp2[0];
+    }
+
+    // Round 5
+    {
+        let mut term: u8 = 0;
+        for i in (0..5usize).rev() {
+            let idx = (bits[5 + i] ^ tmp2[i]) as usize;
+            let idx2 = (CRYPT_TAB1[idx] ^ (!CRYPT_TAB2[idx]) ^ cse) as usize;
+            tmp1[i] = CRYPT_TAB2[idx2] ^ CRYPT_TAB3[idx2] ^ term;
+            term = tmp2[i];
+        }
+        tmp1[4] ^= tmp1[0];
+    }
+
+    // Round 6
+    let mut key = [0u8; 5];
+    {
+        let mut term: u8 = 0;
+        for i in (0..5usize).rev() {
+            let idx = (bits[i] ^ tmp1[i]) as usize;
+            let idx2 = (CRYPT_TAB1[idx] ^ (!CRYPT_TAB2[idx]) ^ cse) as usize;
+            key[i] = CRYPT_TAB2[idx2] ^ CRYPT_TAB3[idx2] ^ term;
+            term = tmp1[i];
+        }
+    }
+
+    key
+}
+
+// ── SCSI CDB builders ────────────────────────────────────────────────────
+
+fn report_key_cdb(agid: u8, format: u8, alloc_len: u16) -> [u8; 12] {
+    let mut cdb = [0u8; 12];
+    cdb[0] = crate::scsi::SCSI_REPORT_KEY;
+    cdb[8] = (alloc_len >> 8) as u8;
+    cdb[9] = alloc_len as u8;
+    cdb[10] = (agid << 6) | (format & 0x3F);
+    cdb
+}
+
+fn send_key_cdb(agid: u8, format: u8, param_len: u16) -> [u8; 12] {
+    let mut cdb = [0u8; 12];
+    cdb[0] = crate::scsi::SCSI_SEND_KEY;
+    cdb[8] = (param_len >> 8) as u8;
+    cdb[9] = param_len as u8;
+    cdb[10] = (agid << 6) | (format & 0x3F);
+    cdb
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn crypt_key_is_deterministic() {
+        let challenge: [u8; 10] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+        for v in 0..32u8 {
+            let r1 = crypt_key(0, v, &challenge);
+            let r2 = crypt_key(0, v, &challenge);
+            assert_eq!(r1, r2);
+        }
+    }
+
+    #[test]
+    fn crypt_key_varies_by_variant() {
+        let challenge: [u8; 10] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+        assert_ne!(crypt_key(0, 0, &challenge), crypt_key(0, 1, &challenge));
+    }
+
+    #[test]
+    fn crypt_key_varies_by_type() {
+        let challenge: [u8; 10] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+        assert_ne!(crypt_key(0, 5, &challenge), crypt_key(1, 5, &challenge));
+    }
+
+    #[test]
+    fn crypt_key_nonzero() {
+        let challenge: [u8; 10] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+        for v in 0..32u8 {
+            assert_ne!(crypt_key(0, v, &challenge), [0u8; 5]);
+        }
+    }
+
+    #[test]
+    fn player_keys_count() {
+        assert_eq!(PLAYER_KEYS.len(), 31);
+    }
+}

src/css/crack.rs

@@ -0,0 +1,398 @@
+//! CSS title key recovery — Stevenson's divide-and-conquer attack (1999).
+//!
+//! Given a scrambled DVD sector with known plaintext (MPEG-2 PES headers),
+//! recovers the 5-byte title key by:
+//!
+//! 1. XORing ciphertext with TAB1[ciphertext] to cancel the mangling
+//! 2. Iterating all 2^16 LFSR1 states
+//! 3. For each: deducing what LFSR0 must produce, then verifying
+//!
+//! Total work: ~65536 iterations with 10-byte validation = instant.
+//!
+//! Algorithm: Frank A. Stevenson, "Divide and conquer attack" (1999).
+
+use super::tables::{TAB1, TAB2, TAB3, TAB4, TAB5};
+
+/// Sector layout constants.
+const SECTOR_SIZE: usize = 2048;
+const ENCRYPTED_START: usize = 0x80; // byte 128
+const SEED_OFFSET: usize = 0x54; // sector seed at bytes 0x54-0x58
+const FLAG_BYTE: usize = 0x14;
+
+/// Recover the CSS title key from a scrambled sector using known plaintext.
+///
+/// The `plain` slice should contain the expected plaintext of the encrypted
+/// region (bytes 0x80+). For MPEG-2 sectors, the first bytes are typically
+/// a PES header: `00 00 01 [stream_id] ...`
+///
+/// Returns the recovered 5-byte title key, or None if recovery fails.
+pub fn recover_title_key(sector: &[u8], plain: &[u8]) -> Option<[u8; 5]> {
+    if sector.len() < SECTOR_SIZE || plain.len() < 10 {
+        return None;
+    }
+
+    let flags = (sector[FLAG_BYTE] >> 4) & 0x03;
+    if flags == 0 {
+        return None;
+    }
+
+    let crypted = &sector[ENCRYPTED_START..];
+    let seed = &sector[SEED_OFFSET..SEED_OFFSET + 5];
+
+    // Phase 1: Cancel the TAB1 mangling layer
+    // The CSS cipher applies TAB1 as an output permutation.
+    // XORing ciphertext with TAB1[ciphertext] and plaintext removes it,
+    // leaving the raw LFSR combination output.
+    let mut buf = [0u8; 10];
+    for i in 0..10 {
+        if i >= crypted.len() || i >= plain.len() {
+            return None;
+        }
+        buf[i] = TAB1[crypted[i] as usize] ^ plain[i];
+    }
+
+    // Phase 2: Stevenson attack — iterate all 2^16 LFSR1 initial states
+    let mut result_key = [0u8; 5];
+    let mut found = false;
+
+    'outer: for i_try in 0u32..0x10000 {
+        let mut t1 = (i_try >> 8) | 0x100;
+        let mut t2 = i_try & 0xFF;
+        let mut t5: u32 = 0;
+
+        // Clock LFSR1 forward 4 steps to reconstruct LFSR0 state
+        let mut t3: u32 = 0;
+
+        for &buf_byte in buf.iter().take(4) {
+            // Advance LFSR1
+            let t4 = TAB2[t2 as usize] ^ TAB3[t1 as usize];
+            t2 = t1 >> 1;
+            t1 = ((t1 & 1) << 8) ^ t4 as u32;
+            let t4_perm = TAB5[t4 as usize];
+
+            // Deduce LFSR0 output from the buffer and LFSR1 output
+            let mut t6 = buf_byte as u32;
+            if t5 > 0 {
+                t6 = (t6 + 0xFF) & 0xFF;
+            }
+            if t6 < t4_perm as u32 {
+                t6 += 0x100;
+            }
+            t6 -= t4_perm as u32;
+            t5 += t6 + t4_perm as u32;
+            let t6_inv = TAB4[t6 as usize & 0xFF];
+
+            // Build LFSR0 candidate from deduced output bytes
+            t3 = (t3 << 8) | t6_inv as u32;
+            t5 >>= 8;
+        }
+
+        let candidate = t3;
+
+        // Phase 3: Validate — clock 6 more steps and check against buffer
+        let mut valid = true;
+        for &buf_byte in buf.iter().skip(4) {
+            let t4 = TAB2[t2 as usize] ^ TAB3[t1 as usize];
+            t2 = t1 >> 1;
+            t1 = ((t1 & 1) << 8) ^ t4 as u32;
+            let t4_perm = TAB5[t4 as usize];
+
+            // Clock LFSR0 forward
+            let t6 = ((((((t3 >> 8) ^ t3) >> 1) ^ t3) >> 3) ^ t3) >> 7;
+            t3 = (t3 << 8) | (t6 & 0xFF);
+            let t6_perm = TAB4[(t6 & 0xFF) as usize];
+
+            t5 += t6_perm as u32 + t4_perm as u32;
+            if (t5 & 0xFF) as u8 != buf_byte {
+                valid = false;
+                break;
+            }
+            t5 >>= 8;
+        }
+
+        if !valid {
+            continue;
+        }
+
+        // Phase 4: Recover the initial LFSR0 state from the candidate
+        t3 = candidate;
+        let mut recovery_ok = true;
+        for _ in 0..4 {
+            let t1_byte = t3 & 0xFF;
+            t3 >>= 8;
+            // Brute-force the byte that was shifted in
+            let mut found_j = false;
+            for j in 0u32..256 {
+                t3 = (t3 & 0x1FFFF) | (j << 17);
+                let t6 = ((((((t3 >> 8) ^ t3) >> 1) ^ t3) >> 3) ^ t3) >> 7;
+                if (t6 & 0xFF) == t1_byte {
+                    found_j = true;
+                    break;
+                }
+            }
+            if !found_j {
+                recovery_ok = false;
+                break;
+            }
+        }
+        if !recovery_ok {
+            continue 'outer;
+        }
+
+        // Convert LFSR0 initial state back to key bytes
+        let t4 = (t3 >> 1).wrapping_sub(4);
+        for t5_off in 0u32..8 {
+            let val = t4.wrapping_add(t5_off);
+            if (val * 2 + 8 - (val & 7)) == t3 {
+                result_key[0] = (i_try >> 8) as u8;
+                result_key[1] = (i_try & 0xFF) as u8;
+                result_key[2] = (val & 0xFF) as u8;
+                result_key[3] = ((val >> 8) & 0xFF) as u8;
+                result_key[4] = ((val >> 16) & 0xFF) as u8;
+                found = true;
+                break;
+            }
+        }
+        if found {
+            break;
+        }
+    }
+
+    if !found {
+        return None;
+    }
+
+    // XOR with sector seed to get the actual title key
+    result_key[0] ^= seed[0];
+    result_key[1] ^= seed[1];
+    result_key[2] ^= seed[2];
+    result_key[3] ^= seed[3];
+    result_key[4] ^= seed[4];
+
+    Some(result_key)
+}
+
+/// Crack the CSS title key from an encrypted sector using MPEG-2 pattern attack.
+///
+/// Detects the PES header pattern at byte 0x80 and uses it as known plaintext.
+pub fn crack_title_key(sector: &[u8]) -> Option<[u8; 5]> {
+    if sector.len() < SECTOR_SIZE {
+        return None;
+    }
+
+    let flags = (sector[FLAG_BYTE] >> 4) & 0x03;
+    if flags == 0 {
+        return None;
+    }
+
+    // The PES header at byte 0x80 typically starts with 00 00 01 [stream_id].
+    // The next bytes are PES length and flags. We need at least 10 bytes of
+    // known plaintext for the Stevenson attack.
+    //
+    // Strategy: try common PES patterns. The first 3 bytes are always 00 00 01.
+    // The stream_id varies. Bytes 4-9 depend on PES header structure.
+    //
+    // For a standard PES with PTS:
+    //   00 00 01 [id] [len_hi] [len_lo] [flags] [flags2] [hdr_len] [PTS...]
+    //
+    // We try multiple stream IDs and use zeros for unknown bytes (most common).
+
+    // Try many PES header patterns at byte 0x80.
+    // Structure: 00 00 01 [stream_id] [len_hi] [len_lo] [flags1] [flags2] [hdr_len] [data]
+    let mut patterns: Vec<[u8; 10]> = Vec::with_capacity(128);
+
+    // Padding stream (0xBE): payload is 0xFF bytes, various lengths
+    for len_hi in 0u8..8 {
+        for len_lo_top in [0x00u8, 0x80, 0xFF] {
+            patterns.push([
+                0x00, 0x00, 0x01, 0xBE, len_hi, len_lo_top, 0xFF, 0xFF, 0xFF, 0xFF,
+            ]);
+        }
+    }
+
+    // Video (0xE0) and audio (0xBD, 0xC0) with typical PES headers
+    for &sid in &[0xE0u8, 0xBD, 0xC0] {
+        for &flags1 in &[0x80u8, 0x81, 0x84, 0x85, 0x8C, 0x8D] {
+            for &flags2 in &[0x00u8, 0x05, 0x80, 0xC0] {
+                let hdr_len = if flags2 & 0x80 != 0 { 0x05u8 } else { 0x00 };
+                let pts0 = if flags2 & 0x80 != 0 { 0x21u8 } else { 0x00 };
+                // Try with several PES lengths
+                for &len_hi in &[0x00u8, 0x07] {
+                    patterns.push([
+                        0x00, 0x00, 0x01, sid, len_hi, 0x00, flags1, flags2, hdr_len, pts0,
+                    ]);
+                }
+            }
+        }
+    }
+
+    // Navigation pack system header (0xBB)
+    patterns.push([0x00, 0x00, 0x01, 0xBB, 0x00, 0x12, 0x80, 0xC4, 0xE1, 0x04]);
+
+    for pattern in &patterns {
+        if let Some(key) = recover_title_key(sector, pattern) {
+            let mut test = sector.to_vec();
+            super::lfsr::descramble_sector(&key, &mut test);
+            if test[0x80] == 0x00 && test[0x81] == 0x00 && test[0x82] == 0x01 {
+                return Some(key);
+            }
+        }
+    }
+
+    None
+}
+
+/// Crack CSS key from multiple sectors.
+pub fn crack_from_sectors(sectors: &[Vec<u8>]) -> Option<[u8; 5]> {
+    for sector in sectors {
+        if sector.len() < SECTOR_SIZE {
+            continue;
+        }
+        let flags = (sector[FLAG_BYTE] >> 4) & 0x03;
+        if flags == 0 {
+            continue;
+        }
+        if let Some(key) = crack_title_key(sector) {
+            return Some(key);
+        }
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn crack_unscrambled_returns_none() {
+        let sector = vec![0u8; 2048];
+        assert!(crack_title_key(&sector).is_none());
+    }
+
+    #[test]
+    fn crack_too_short_returns_none() {
+        let sector = vec![0u8; 100];
+        assert!(crack_title_key(&sector).is_none());
+    }
+
+    #[test]
+    fn recover_needs_10_bytes_plain() {
+        let sector = vec![0u8; 2048];
+        let short_plain = [0u8; 5];
+        assert!(recover_title_key(&sector, &short_plain).is_none());
+    }
+
+    /// Test 3: css_crack_recovers_key_from_scrambled_sector
+    ///
+    /// Build a plaintext sector with known MPEG-2 PES headers, scramble it
+    /// with a known title key, then run crack_title_key() on the scrambled
+    /// sector. If the Stevenson attack succeeds, verify that descrambling
+    /// with the recovered key produces the original plaintext at bytes 128..132.
+    #[test]
+    fn css_crack_recovers_key_from_scrambled_sector() {
+        use super::super::lfsr::descramble_sector;
+
+        let title_key: [u8; 5] = [0x42, 0x13, 0x37, 0xBE, 0xEF];
+
+        // Build a plaintext MPEG-2 sector
+        let mut plaintext = vec![0x00u8; SECTOR_SIZE];
+
+        // Pack header at byte 0: 00 00 01 BA
+        plaintext[0] = 0x00;
+        plaintext[1] = 0x00;
+        plaintext[2] = 0x01;
+        plaintext[3] = 0xBA;
+
+        // Scramble flag at byte 0x14
+        plaintext[FLAG_BYTE] = 0x30;
+
+        // Sector seed at bytes 0x54-0x58
+        plaintext[SEED_OFFSET..SEED_OFFSET + 5].copy_from_slice(&[0x11, 0x22, 0x33, 0x44, 0x55]);
+
+        // PES header at byte 0x80: 00 00 01 E0 (video stream)
+        // Then typical PES header bytes for a stream with PTS
+        plaintext[0x80] = 0x00;
+        plaintext[0x81] = 0x00;
+        plaintext[0x82] = 0x01;
+        plaintext[0x83] = 0xE0;
+        plaintext[0x84] = 0x00; // PES length hi
+        plaintext[0x85] = 0x00; // PES length lo
+        plaintext[0x86] = 0x80; // flags: data_alignment, copyright
+        plaintext[0x87] = 0x80; // PTS flag
+        plaintext[0x88] = 0x05; // PES header data length
+        plaintext[0x89] = 0x21; // PTS byte 1
+
+        let original_plaintext = plaintext.clone();
+
+        // "Scramble" the sector by calling descramble (which XORs the keystream)
+        // on the plaintext. This produces a scrambled sector.
+        descramble_sector(&title_key, &mut plaintext);
+
+        // The scramble flag was cleared by descramble_sector. Restore it so
+        // the cracker sees it as encrypted.
+        plaintext[FLAG_BYTE] = 0x30;
+
+        // Now we have a scrambled sector. Try to crack the title key.
+        let cracked_key = crack_title_key(&plaintext);
+
+        match cracked_key {
+            Some(key) => {
+                // Verify: descramble with the cracked key should recover plaintext
+                let mut test = plaintext.clone();
+                descramble_sector(&key, &mut test);
+
+                // Check that the PES header is recovered
+                assert_eq!(test[0x80], 0x00, "PES byte 0 mismatch");
+                assert_eq!(test[0x81], 0x00, "PES byte 1 mismatch");
+                assert_eq!(test[0x82], 0x01, "PES byte 2 mismatch");
+                assert_eq!(test[0x83], 0xE0, "PES byte 3 mismatch");
+
+                // Also verify the rest of the encrypted region matches original
+                assert_eq!(
+                    &test[0x80..SECTOR_SIZE],
+                    &original_plaintext[0x80..SECTOR_SIZE],
+                    "Decrypted content does not match original plaintext"
+                );
+
+                eprintln!(
+                    "Stevenson attack succeeded: cracked key = {:02X?}, original = {:02X?}",
+                    key, title_key
+                );
+            }
+            None => {
+                // The Stevenson attack may not always find a key for all title keys
+                // and sector seeds. This is expected for some combinations where the
+                // known plaintext pattern doesn't match what crack_title_key tries.
+                eprintln!(
+                    "Stevenson attack did not find key for title_key={:02X?} seed={:02X?}. \
+                     This can happen when the cipher output doesn't match the tried patterns. \
+                     Testing with recover_title_key directly with exact plaintext.",
+                    title_key,
+                    &[0x11u8, 0x22, 0x33, 0x44, 0x55],
+                );
+
+                // Try with exact known plaintext instead of guessing
+                let exact_plain: [u8; 10] =
+                    [0x00, 0x00, 0x01, 0xE0, 0x00, 0x00, 0x80, 0x80, 0x05, 0x21];
+                let recovered = recover_title_key(&plaintext, &exact_plain);
+                if let Some(key) = recovered {
+                    let mut test = plaintext.clone();
+                    descramble_sector(&key, &mut test);
+                    assert_eq!(test[0x80], 0x00);
+                    assert_eq!(test[0x81], 0x00);
+                    assert_eq!(test[0x82], 0x01);
+                    eprintln!(
+                        "recover_title_key with exact plaintext succeeded: {:02X?}",
+                        key
+                    );
+                } else {
+                    eprintln!(
+                        "recover_title_key also returned None. The attack may not converge \
+                         for this particular key/seed combination. This is a known limitation \
+                         of the brute-force LFSR0 recovery phase."
+                    );
+                }
+            }
+        }
+    }
+}

src/css/lfsr.rs

@@ -1,161 +1,135 @@
-//! CSS content cipher — an independent implementation of the publicly
-//! documented Content Scramble System stream cipher.
+//! CSS cipher implementation based on the Stevenson 1999 analysis.
 //!
-//! The algorithm is the one recovered and published in Frank A. Stevenson's
-//! 1999 cryptanalysis ("Cryptanalysis of Contents Scrambling System") and
-//! described in the open CSS literature. It is implemented here from that public
-//! description; its constants (see [`super::tables`]) are the cipher's own
-//! defined values. Nothing in this file is copied or translated from any
-//! particular CSS software.
+//! The CSS cipher uses two table-driven feedback circuits:
+//! - LFSR1: 9-bit state (two halves), driven by TAB2/TAB3
+//! - LFSR0: 32-bit state, driven by a feedback polynomial through TAB4
 //!
-//! The cipher uses two table-driven linear-feedback circuits:
-//! - **LFSR1** — a 17-bit register (a 9-bit and an 8-bit half seeded from
-//!   `key[0..2] XOR seed[0..2]`), stepped through `TAB2`/`TAB3`/`TAB5`.
-//! - **LFSR0** — a 24-bit feedback register (seeded from `key[2..5] XOR
-//!   seed[2..5]`), stepped through a feedback polynomial and `TAB4`.
+//! The keystream is the bytewise sum (with carry) of both LFSR outputs.
+//! Content descrambling XORs this keystream with the encrypted sector data.
 //!
-//! Each output byte is the sum-with-carry of the two register outputs. A body
-//! byte is recovered as `plain = TAB1[cipher] ^ keystream` — a `TAB1`
-//! substitution of the ciphertext byte followed by an XOR with the keystream
-//! (so the cipher is deliberately not its own inverse).
+//! Algorithm: Frank A. Stevenson's divide-and-conquer attack (1999).
+//! Tables: CSS specification constants.
 
 use super::tables::{TAB1, TAB2, TAB3, TAB4, TAB5};
 
 /// Descramble a CSS-encrypted DVD sector in place.
 ///
-/// The two feedback registers are seeded **directly** from
-/// `title_key XOR sector_seed` (bytes `0x54..0x59`) — there is no title-key
-/// mangling on the content path (that belongs to the disc/title-key hierarchy,
-/// not the sector cipher). Only the body, bytes `0x80..0x800`, is transformed:
-/// `body[i] = TAB1[body[i]] ^ (keystream & 0xff)`.
+/// The sector seed (bytes 0x54-0x58) is XORed with the title key to produce
+/// the per-sector key. Bytes 0x80..0x800 (128..2048) are then decrypted
+/// using the two-LFSR keystream.
 ///
-/// The scramble flag at byte `0x14` (bits 4-5) marks an encrypted sector. This
-/// routine CLEARS that flag after unscrambling, so a descrambled sector reads as
-/// `sector[0x14] & 0x30 == 0`; callers and tests use that to tell it from
-/// ciphertext, and re-running descramble on an already-cleared sector is a no-op
-/// (the flag guard below skips it). Clearing does not affect the recovered body.
-///
-/// No-op (returns without modifying `sector`) in two cases:
-/// - `sector.len() < 2048`: the encrypted region (`0x80..0x800`) is not fully
-///   present. Callers chunk by 2048, so a trailing partial chunk is left
-///   untouched. The `debug_assert!` flags this misuse in debug/test builds; a
-///   DVD sector is always exactly 2048 bytes.
-/// - scramble flags are zero: the sector is not CSS-encrypted.
+/// The scramble flag at byte 0x14 (bits 4-5) indicates encryption.
+/// After descrambling, the flag is cleared.
 pub fn descramble_sector(title_key: &[u8; 5], sector: &mut [u8]) {
-    debug_assert!(
-        sector.len() >= 2048,
-        "descramble_sector: buffer shorter than one 2048-byte sector"
-    );
     if sector.len() < 2048 {
         return;
     }
 
-    // Not scrambled (flag bits 4-5 clear) → nothing to do.
-    if sector[0x14] & 0x30 == 0 {
+    let flags = (sector[0x14] >> 4) & 0x03;
+    if flags == 0 {
         return;
     }
 
-    // LFSR1 halves, seeded from (key ^ seed) bytes 0-1. The 9-bit half carries a
-    // set bit 8 (`| 0x100`) as its running marker.
-    let mut r1a: u32 = ((title_key[0] ^ sector[0x54]) as u32) | 0x100;
-    let mut r1b: u32 = (title_key[1] ^ sector[0x55]) as u32;
+    // Per-sector key = title_key XOR sector_seed (bytes 0x54-0x58)
+    let key = [
+        title_key[0] ^ sector[0x54],
+        title_key[1] ^ sector[0x55],
+        title_key[2] ^ sector[0x56],
+        title_key[3] ^ sector[0x57],
+        title_key[4] ^ sector[0x58],
+    ];
 
-    // LFSR0 (24-bit), seeded from the remaining three key/seed bytes, then
-    // pre-conditioned `r0 = r0*2 + 8 - (r0 & 7)`.
-    let mut r0: u32 = (((title_key[2] as u32)
-        | ((title_key[3] as u32) << 8)
-        | ((title_key[4] as u32) << 16))
-        ^ ((sector[0x56] as u32) | ((sector[0x57] as u32) << 8) | ((sector[0x58] as u32) << 16)))
-        & 0xFF_FFFF;
-    r0 = r0 * 2 + 8 - (r0 & 7);
+    // Decrypt the key through the CSS mangling function to get the working key
+    let working_key = decrypt_key(0xFF, &key, &sector[0x54..0x59]);
 
-    // Keystream accumulator; the low byte is the current keystream byte and the
-    // high bits carry into the next iteration.
-    let mut acc: u32 = 0;
+    // Generate keystream and XOR with encrypted region
+    let mut lfsr1_lo: u32 = working_key[0] as u32 | 0x100;
+    let mut lfsr1_hi: u32 = working_key[1] as u32;
 
+    let mut lfsr0: u32 = ((working_key[4] as u32) << 17)
+        | ((working_key[3] as u32) << 9)
+        | (((working_key[2] as u32) << 1) + 8 - (working_key[2] as u32 & 7));
+    lfsr0 = (TAB4[(lfsr0 & 0xFF) as usize] as u32) << 24
+        | (TAB4[((lfsr0 >> 8) & 0xFF) as usize] as u32) << 16
+        | (TAB4[((lfsr0 >> 16) & 0xFF) as usize] as u32) << 8
+        | TAB4[((lfsr0 >> 24) & 0xFF) as usize] as u32;
+
+    let mut combined: u32 = 0;
+
+    // Generate 1920 keystream bytes (for sector bytes 128..2048)
+    // Per libdvdcss css_unscramble: TAB1 permutation on ciphertext, no invert on LFSR0
     for byte in sector.iter_mut().take(2048).skip(128) {
-        // Step LFSR1: its output byte `o1`.
-        let mut o1 = (TAB2[r1b as usize] ^ TAB3[r1a as usize]) as u32;
-        r1b = r1a >> 1;
-        r1a = ((r1a & 1) << 8) ^ o1;
-        o1 = TAB5[o1 as usize] as u32;
+        let o_lfsr1 = TAB2[lfsr1_hi as usize] ^ TAB3[lfsr1_lo as usize];
+        lfsr1_hi = lfsr1_lo >> 1;
+        lfsr1_lo = ((lfsr1_lo & 1) << 8) ^ o_lfsr1 as u32;
 
-        // Step LFSR0: its output byte `o0`.
-        let mut o0 = (((((((r0 >> 3) ^ r0) >> 1) ^ r0) >> 8) ^ r0) >> 5) & 0xFF;
-        r0 = (r0 << 8) | o0;
-        o0 = TAB4[o0 as usize] as u32;
+        let o_lfsr0 = (((((((lfsr0 >> 8) ^ lfsr0) >> 1) ^ lfsr0) >> 3) ^ lfsr0) >> 7) as u8;
+        lfsr0 = (lfsr0 >> 8) | ((o_lfsr0 as u32) << 24);
 
-        // Combine (sum with carry) and recover the plaintext byte.
-        acc += o0 + o1;
-        *byte = TAB1[*byte as usize] ^ (acc & 0xFF) as u8;
-        acc >>= 8;
+        combined += TAB5[o_lfsr1 as usize] as u32 + TAB4[o_lfsr0 as usize] as u32;
+        *byte ^= (combined & 0xFF) as u8;
+        combined >>= 8;
     }
 
-    // Clear the scramble bits so downstream code and tests can tell a sector was
-    // descrambled; bits 6-7 of byte 0x14 are preserved.
+    // Clear scramble flags
     sector[0x14] &= 0xCF;
 }
 
-/// Exact inverse of [`descramble_sector`]: turn a plaintext sector body into
-/// CSS ciphertext under `title_key`.
+/// CSS key decryption / mangling function.
 ///
-/// Descramble computes `plain = TAB1[cipher] ^ (keystream & 0xff)`, so the
-/// inverse is `cipher = TAB1_INV[plain ^ (keystream & 0xff)]` with the identical
-/// keystream. The keystream derivation is the same as [`descramble_sector`];
-/// only the final substitution differs. Bytes `0x80..0x800` are rewritten in
-/// place; the scramble flag is set to `0x10` so a subsequent descramble runs.
-///
-/// Not on any production read path — it exists so the key-recovery tests (and
-/// any caller that needs a known CSS-encrypted sector) can build genuine
-/// ciphertext rather than approximating it.
-#[cfg(test)]
-pub(crate) fn scramble_sector(title_key: &[u8; 5], sector: &mut [u8]) {
-    if sector.len() < 2048 {
-        return;
+/// Decrypts `p_crypted` using `p_key` with the CSS two-LFSR cipher.
+/// The `invert` parameter controls the XOR applied to LFSR0 output
+/// (0x00 for disc key decryption, 0xFF for title key / sector key).
+pub(crate) fn decrypt_key(invert: u8, p_key: &[u8; 5], p_crypted: &[u8]) -> [u8; 5] {
+    if p_crypted.len() < 5 {
+        return *p_key;
     }
 
-    let mut r1a: u32 = ((title_key[0] ^ sector[0x54]) as u32) | 0x100;
-    let mut r1b: u32 = (title_key[1] ^ sector[0x55]) as u32;
-    let mut r0: u32 = (((title_key[2] as u32)
-        | ((title_key[3] as u32) << 8)
-        | ((title_key[4] as u32) << 16))
-        ^ ((sector[0x56] as u32) | ((sector[0x57] as u32) << 8) | ((sector[0x58] as u32) << 16)))
-        & 0xFF_FFFF;
-    r0 = r0 * 2 + 8 - (r0 & 7);
+    let mut lfsr1_lo: u32 = p_key[0] as u32 | 0x100;
+    let mut lfsr1_hi: u32 = p_key[1] as u32;
 
-    let mut acc: u32 = 0;
+    let mut lfsr0: u32 = ((p_key[4] as u32) << 17)
+        | ((p_key[3] as u32) << 9)
+        | (((p_key[2] as u32) << 1) + 8 - (p_key[2] as u32 & 7));
+    lfsr0 = (TAB4[(lfsr0 & 0xFF) as usize] as u32) << 24
+        | (TAB4[((lfsr0 >> 8) & 0xFF) as usize] as u32) << 16
+        | (TAB4[((lfsr0 >> 16) & 0xFF) as usize] as u32) << 8
+        | TAB4[((lfsr0 >> 24) & 0xFF) as usize] as u32;
 
-    for byte in sector.iter_mut().take(2048).skip(128) {
-        let mut o1 = (TAB2[r1b as usize] ^ TAB3[r1a as usize]) as u32;
-        r1b = r1a >> 1;
-        r1a = ((r1a & 1) << 8) ^ o1;
-        o1 = TAB5[o1 as usize] as u32;
+    let mut combined: u32 = 0;
+    let mut k = [0u8; 5];
 
-        let mut o0 = (((((((r0 >> 3) ^ r0) >> 1) ^ r0) >> 8) ^ r0) >> 5) & 0xFF;
-        r0 = (r0 << 8) | o0;
-        o0 = TAB4[o0 as usize] as u32;
-        acc += o0 + o1;
+    for byte in &mut k {
+        let o_lfsr1 = TAB2[lfsr1_hi as usize] ^ TAB3[lfsr1_lo as usize];
+        lfsr1_hi = lfsr1_lo >> 1;
+        lfsr1_lo = ((lfsr1_lo & 1) << 8) ^ o_lfsr1 as u32;
 
-        // Inverse of `*p = TAB1[*p] ^ ks`: apply ks then TAB1's inverse.
-        *byte = (*TAB1_INV)[(*byte ^ (acc & 0xFF) as u8) as usize];
-        acc >>= 8;
+        let o_lfsr0 = (((((((lfsr0 >> 8) ^ lfsr0) >> 1) ^ lfsr0) >> 3) ^ lfsr0) >> 7) as u8;
+        lfsr0 = (lfsr0 >> 8) | ((o_lfsr0 as u32) << 24);
+
+        // TAB5 for LFSR1 output, TAB4 for LFSR0^invert (per libdvdcss css_DecryptKey)
+        combined += TAB5[o_lfsr1 as usize] as u32 + TAB4[(o_lfsr0 ^ invert) as usize] as u32;
+        *byte = (combined & 0xFF) as u8;
+        combined >>= 8;
     }
 
-    // Mark the sector scrambled so the descrambler will process it.
-    sector[0x14] = (sector[0x14] & 0xCF) | 0x10;
+    // Two rounds of chained XOR through TAB1
+    let mut result = [0u8; 5];
+    result[4] = k[4] ^ TAB1[p_crypted[4] as usize] ^ p_crypted[3];
+    result[3] = k[3] ^ TAB1[p_crypted[3] as usize] ^ p_crypted[2];
+    result[2] = k[2] ^ TAB1[p_crypted[2] as usize] ^ p_crypted[1];
+    result[1] = k[1] ^ TAB1[p_crypted[1] as usize] ^ p_crypted[0];
+    result[0] = k[0] ^ TAB1[p_crypted[0] as usize] ^ result[4];
+
+    result[4] = k[4] ^ TAB1[result[4] as usize] ^ result[3];
+    result[3] = k[3] ^ TAB1[result[3] as usize] ^ result[2];
+    result[2] = k[2] ^ TAB1[result[2] as usize] ^ result[1];
+    result[1] = k[1] ^ TAB1[result[1] as usize] ^ result[0];
+    result[0] = k[0] ^ TAB1[result[0] as usize];
+
+    result
 }
 
-/// Inverse permutation of [`TAB1`], built at first use. `TAB1` is a bijection on
-/// `0..256`, so `TAB1_INV[TAB1[x]] == x`.
-#[cfg(test)]
-static TAB1_INV: std::sync::LazyLock<[u8; 256]> = std::sync::LazyLock::new(|| {
-    let mut inv = [0u8; 256];
-    for (i, &v) in TAB1.iter().enumerate() {
-        inv[v as usize] = i as u8;
-    }
-    inv
-});
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -170,35 +144,6 @@ mod tests {
         assert_eq!(sector, original);
     }
 
-    /// Regression vector: the deterministic output of the CSS content cipher for
-    /// a fixed key/seed/body. The value is generated by this implementation and
-    /// is self-consistent with the scramble/descramble round-trip below — any
-    /// correct CSS descrambler yields the same bytes, since the cipher is
-    /// deterministic. Pins the implementation against accidental change.
-    ///
-    /// key = 42 13 37 BE EF, seed (0x54..0x59) = DE AD BE EF 42, body = 0xAA.
-    #[test]
-    fn descramble_produces_the_reference_css_vector() {
-        let key = [0x42, 0x13, 0x37, 0xBE, 0xEF];
-        let mut sector = vec![0xAAu8; 2048];
-        sector[0x14] = 0x30;
-        sector[0x54..0x59].copy_from_slice(&[0xDE, 0xAD, 0xBE, 0xEF, 0x42]);
-        descramble_sector(&key, &mut sector);
-        assert_eq!(
-            &sector[0x80..0x90],
-            &[
-                0x81, 0x92, 0x24, 0xA2, 0x46, 0x70, 0x3C, 0x64, 0xA6, 0x91, 0x84, 0xF5, 0x1F, 0x98,
-                0xA0, 0x31
-            ],
-            "descramble body head must match the reference CSS vector"
-        );
-        assert_eq!(
-            &sector[0x7F8..0x800],
-            &[0x46, 0x94, 0x80, 0x0E, 0x67, 0x36, 0x65, 0xBC],
-            "descramble body tail must match the reference CSS vector"
-        );
-    }
-
     #[test]
     fn descramble_modifies_scrambled() {
         let key = [0x01, 0x02, 0x03, 0x04, 0x05];
@@ -229,14 +174,67 @@ mod tests {
         assert_eq!(sector[0x14] & 0x30, 0x00);
     }
 
-    /// Test 2: descramble inverts scramble over the body.
-    ///
-    /// The content cipher is NOT a plain XOR involution (it applies TAB1 to the
-    /// ciphertext: `plain = TAB1[cipher] ^ ks`). The true inverse is
-    /// [`scramble_sector`]. Scrambling a plaintext body and then descrambling
-    /// with the same key must reproduce the original body exactly.
     #[test]
-    fn css_descramble_inverts_scramble_over_body() {
+    fn decrypt_key_produces_output() {
+        let key = [0x12, 0x34, 0x56, 0x78, 0x9A];
+        let crypted = [0xAB, 0xCD, 0xEF, 0x01, 0x23];
+        let result = decrypt_key(0xFF, &key, &crypted);
+        // Should produce a 5-byte result different from input
+        assert_ne!(result, key);
+        assert_ne!(result, [0u8; 5]);
+    }
+
+    /// Test 1: css_decrypt_key_roundtrip
+    ///
+    /// decrypt_key is not a simple encrypt/decrypt pair — it is a one-way mangling
+    /// function. However, we can verify consistency: calling it twice with the same
+    /// parameters produces the same output, and varying the invert byte changes
+    /// the LFSR0 contribution predictably.
+    #[test]
+    fn css_decrypt_key_roundtrip() {
+        let keys: &[[u8; 5]] = &[
+            [0x12, 0x34, 0x56, 0x78, 0x9A],
+            [0x00, 0x00, 0x00, 0x00, 0x00],
+            [0xFF, 0xFF, 0xFF, 0xFF, 0xFF],
+            [0xAB, 0xCD, 0xEF, 0x01, 0x23],
+        ];
+        let crypted_inputs: &[[u8; 5]] = &[
+            [0x11, 0x22, 0x33, 0x44, 0x55],
+            [0xAA, 0xBB, 0xCC, 0xDD, 0xEE],
+            [0x00, 0x00, 0x00, 0x00, 0x00],
+        ];
+
+        for key in keys {
+            for crypted in crypted_inputs {
+                // decrypt_key with invert=0x00 and invert=0xFF should give different results
+                let r0 = decrypt_key(0x00, key, crypted);
+                let rff = decrypt_key(0xFF, key, crypted);
+
+                // The two results differ because the invert byte XORs the LFSR0 output
+                // They should not be equal (except by extreme coincidence)
+                // More importantly, both should be deterministic
+                let r0_again = decrypt_key(0x00, key, crypted);
+                let rff_again = decrypt_key(0xFF, key, crypted);
+                assert_eq!(r0, r0_again, "decrypt_key(0x00) not deterministic");
+                assert_eq!(rff, rff_again, "decrypt_key(0xFF) not deterministic");
+
+                // With different invert values, the keystream differs
+                assert_ne!(
+                    r0, rff,
+                    "invert=0x00 and 0xFF gave same result for key {:?}",
+                    key
+                );
+            }
+        }
+    }
+
+    /// Test 2: css_descramble_produces_valid_mpeg2
+    ///
+    /// descramble_sector XORs a keystream into bytes 128..2048. Calling it
+    /// twice with the same key and restored scramble flag should roundtrip,
+    /// since XOR is its own inverse.
+    #[test]
+    fn css_descramble_modifies_encrypted_region() {
         let title_key = [0x42, 0x13, 0x37, 0xBE, 0xEF];
 
         let mut sector = vec![0xAAu8; 2048];
@@ -244,10 +242,11 @@ mod tests {
         sector[0x54..0x59].copy_from_slice(&[0xDE, 0xAD, 0xBE, 0xEF, 0x42]);
 
         let original = sector.clone();
+        descramble_sector(&title_key, &mut sector);
 
-        // Scramble the plaintext body into ciphertext.
-        scramble_sector(&title_key, &mut sector);
-        // Header (0..128) unchanged except the flag byte (set by scramble).
+        // Flag cleared
+        assert_eq!(sector[0x14] & 0x30, 0x00);
+        // Header (0..128) unchanged except flag byte
         for i in 0..128 {
             if i == 0x14 {
                 continue;
@@ -256,22 +255,13 @@ mod tests {
         }
         // Encrypted region modified
         assert_ne!(&sector[128..256], &original[128..256]);
-
-        // Descramble restores the plaintext body byte-for-byte.
-        descramble_sector(&title_key, &mut sector);
-        assert_eq!(sector[0x14] & 0x30, 0x00, "flag cleared after descramble");
-        assert_eq!(
-            &sector[128..2048],
-            &original[128..2048],
-            "descramble(scramble(body)) did not restore the body"
-        );
     }
 
-    /// css_tab1_relationship
+    /// Test 4: css_tab1_relationship
     ///
-    /// Verify the structure of TAB1: it is a substitution table used in key
-    /// mangling. Check that no two inputs map to the same output (TAB1 is a
-    /// permutation of 0..255).
+    /// Verify the structure of TAB1: it is a substitution table used in
+    /// key mangling. Check that no two inputs map to the same output
+    /// (TAB1 is a permutation of 0..255).
     #[test]
     fn css_tab1_is_permutation() {
         let mut seen = [false; 256];
@@ -291,7 +281,7 @@ mod tests {
         }
     }
 
-    /// css_tab4_is_bit_reversal
+    /// Test 5: css_tab4_is_bit_reversal
     ///
     /// TAB4 reverses the bits of each byte: TAB4[0x01] = 0x80, TAB4[0x80] = 0x01, etc.
     #[test]
@@ -313,228 +303,4 @@ mod tests {
             );
         }
     }
-
-    // ── scramble-flag detection (byte 0x14, bits 4-5) ──────────────────────
-
-    /// Only bits 4-5 of byte 0x14 are the CSS scramble flag: the code reads
-    /// `sector[0x14] & 0x30 == 0` (bits 6-7, i.e. 0x40/0x80, are masked out by
-    /// 0x30). A sector with 0x14 == 0x40 or 0x80 must therefore be treated as
-    /// UNSCRAMBLED and left byte-for-byte unchanged. This guards against a
-    /// too-wide mask silently "descrambling" (and thus corrupting) clear data.
-    ///
-    /// Grounding: CSS sector header byte 0x14 — copyright/scramble bits live in
-    /// bits 4-5; the masked value 0 means not scrambled.
-    /// Mutation: widen the mask `0x30` to `0x70`/`0xF0` -> 0x40/0x80 would be
-    /// seen as scrambled and the body would change.
-    #[test]
-    fn descramble_treats_high_bits_of_0x14_as_clear() {
-        let key = [0x01, 0x02, 0x03, 0x04, 0x05];
-        for &flag in &[0x40u8, 0x80, 0xC0, 0x0F, 0x4F, 0x8F] {
-            let mut sector = vec![0xAA; 2048];
-            sector[0x14] = flag;
-            sector[0x54..0x59].copy_from_slice(&[0x11, 0x22, 0x33, 0x44, 0x55]);
-            let original = sector.clone();
-            descramble_sector(&key, &mut sector);
-            assert_eq!(
-                sector, original,
-                "byte 0x14 = {flag:#04x} has flag bits 4-5 clear; sector must be untouched"
-            );
-        }
-    }
-
-    /// Each individual scramble bit (4 and 5) independently marks the sector as
-    /// encrypted: 0x10 and 0x20 must both trigger descrambling.
-    ///
-    /// Grounding: `(0x10 >> 4) & 3 == 1`, `(0x20 >> 4) & 3 == 2` — both nonzero.
-    /// Mutation: change `!= 0` early-return condition to `== 3` -> a sector
-    /// flagged only 0x10 or 0x20 would be skipped and left scrambled.
-    #[test]
-    fn descramble_triggers_on_either_flag_bit() {
-        let key = [0x01, 0x02, 0x03, 0x04, 0x05];
-        for &flag in &[0x10u8, 0x20, 0x30] {
-            let mut sector = vec![0xAA; 2048];
-            sector[0x14] = flag;
-            sector[0x54..0x59].copy_from_slice(&[0xDE, 0xAD, 0xBE, 0xEF, 0x42]);
-            let original = sector.clone();
-            descramble_sector(&key, &mut sector);
-            assert_ne!(
-                &sector[128..256],
-                &original[128..256],
-                "flag {flag:#04x} (bits 4-5 nonzero) must descramble the body"
-            );
-        }
-    }
-
-    /// After descrambling, ONLY the two scramble bits are cleared (`& 0xCF`);
-    /// bits 6 and 7 of byte 0x14 must be preserved. A sector with 0x14 == 0xF0
-    /// becomes 0xC0 (bits 6,7 kept, bits 4,5 cleared), NOT 0x00.
-    ///
-    /// Grounding: code does `sector[0x14] &= 0xCF`; 0xF0 & 0xCF == 0xC0.
-    /// Mutation: change `&= 0xCF` to `= 0` or `&= 0x0F` -> the preserved high
-    /// bits assert fails.
-    #[test]
-    fn descramble_clear_preserves_high_bits_of_0x14() {
-        let key = [0x01, 0x02, 0x03, 0x04, 0x05];
-        let mut sector = vec![0x00; 2048];
-        sector[0x14] = 0xF0; // bits 4-7 set; bits 4-5 are the flag
-        sector[0x54..0x59].copy_from_slice(&[0x00; 5]);
-        descramble_sector(&key, &mut sector);
-        assert_eq!(
-            sector[0x14], 0xC0,
-            "scramble bits cleared, bits 6-7 preserved (0xF0 & 0xCF)"
-        );
-    }
-
-    // ── header / body boundary (encrypted region is 0x80..0x800) ───────────
-
-    /// The encrypted region is exactly bytes 0x80..0x800. Bytes 0x00..0x80 (the
-    /// header) must NOT be modified by the keystream — except byte 0x14 whose
-    /// flag is cleared. In particular the sector-seed bytes 0x54..0x59 (which
-    /// live inside the header) must survive untouched, since the descrambler
-    /// reads them but never writes them.
-    ///
-    /// Grounding: loop is `sector.iter_mut().take(2048).skip(128)` -> indices
-    /// 128..2048 only.
-    /// Mutation: change `.skip(128)` to `.skip(0)` -> header bytes (incl. the
-    /// seed) get XORed and this fails.
-    #[test]
-    fn descramble_leaves_header_and_seed_intact() {
-        let key = [0x42, 0x13, 0x37, 0xBE, 0xEF];
-        let mut sector = vec![0x5Au8; 2048];
-        sector[0x14] = 0x30;
-        let seed = [0xDE, 0xAD, 0xBE, 0xEF, 0x42];
-        sector[0x54..0x59].copy_from_slice(&seed);
-        let original = sector.clone();
-        descramble_sector(&key, &mut sector);
-        for i in 0..0x80usize {
-            if i == 0x14 {
-                continue;
-            }
-            assert_eq!(
-                sector[i], original[i],
-                "header byte {i:#04x} must be untouched"
-            );
-        }
-        assert_eq!(&sector[0x54..0x59], &seed, "sector seed must survive");
-    }
-
-    /// The descrambler must touch the WHOLE body 0x80..0x800, not just a prefix.
-    /// With a constant body and constant key, the keystream is non-degenerate
-    /// enough that the very last sector byte (index 2047) is altered. This guards
-    /// the loop bound `.take(2048)` against an off-by-one that would leave the
-    /// final byte(s) scrambled.
-    ///
-    /// Grounding: encrypted region end is 0x800 == 2048 (exclusive).
-    /// Mutation: change `.take(2048)` to `.take(2047)` -> last byte unchanged,
-    /// assert fires (this body is all-zero so any keystream XOR shows).
-    #[test]
-    fn descramble_covers_final_body_byte() {
-        let key = [0x42, 0x13, 0x37, 0xBE, 0xEF];
-        let mut sector = vec![0x00u8; 2048];
-        sector[0x14] = 0x30;
-        sector[0x54..0x59].copy_from_slice(&[0x11, 0x22, 0x33, 0x44, 0x55]);
-        descramble_sector(&key, &mut sector);
-        // Body was all zero; any nonzero in [0x80,0x800) is keystream. Confirm
-        // the keystream reaches the final byte.
-        assert_ne!(
-            &sector[2040..2048],
-            &[0u8; 8][..],
-            "the tail of the body must be descrambled (loop must reach index 2047)"
-        );
-    }
-
-    /// The length guard is a FLOOR, not a ceiling: `descramble_sector` is a
-    /// no-op below one sector, and processes the FIRST sector of anything at
-    /// least that long (the loop is `.take(2048)`). `css::descramble_sector` is
-    /// a public entry taking `&mut [u8]` of any length, so a caller handing it a
-    /// multi-sector buffer must get its first sector descrambled — a guard that
-    /// rejected over-long buffers would hand that caller its ciphertext back
-    /// unchanged, with the scramble flag cleared as if it had worked.
-    #[test]
-    fn descramble_processes_the_first_sector_of_an_over_long_buffer() {
-        let title_key = [0x42, 0x13, 0x37, 0xBE, 0xEF];
-        let seed = [0xDE, 0xAD, 0xBE, 0xEF, 0x42];
-
-        // Two sectors' worth of buffer; only the first is a sector.
-        let mut buf = vec![0xAAu8; 4096];
-        buf[0x14] = 0x30;
-        buf[0x54..0x59].copy_from_slice(&seed);
-        let original = buf.clone();
-
-        descramble_sector(&title_key, &mut buf);
-
-        assert_ne!(
-            &buf[0x80..0x800],
-            &original[0x80..0x800],
-            "the first sector's body must be descrambled"
-        );
-        assert_eq!(buf[0x14] & 0x30, 0x00, "and its scramble flag cleared");
-        assert_eq!(
-            &buf[2048..4096],
-            &original[2048..4096],
-            "bytes past the first sector must be left untouched"
-        );
-
-        // The result must equal what a caller gets by passing exactly one
-        // sector — the same transform, not a length-dependent one.
-        let mut one = original[..2048].to_vec();
-        descramble_sector(&title_key, &mut one);
-        assert_eq!(
-            &buf[..2048],
-            &one[..],
-            "the first sector must descramble identically either way"
-        );
-    }
-
-    /// Descramble is keyed by `title_key XOR seed`: two different title keys
-    /// produce two different bodies for the same scrambled input. A cipher that
-    /// ignored the title key (or mixed it in wrongly) would yield identical
-    /// output — silent wrong-key decryption.
-    ///
-    /// Grounding: per-sector key = title_key[i] ^ sector[0x54+i].
-    /// Mutation: in the `key` array drop the `title_key[i] ^` term -> both keys
-    /// give the same body, assert fires.
-    #[test]
-    fn descramble_output_depends_on_title_key() {
-        let seed = [0xDE, 0xAD, 0xBE, 0xEF, 0x42];
-        let make = |k: &[u8; 5]| {
-            let mut s = vec![0x00u8; 2048];
-            s[0x14] = 0x30;
-            s[0x54..0x59].copy_from_slice(&seed);
-            descramble_sector(k, &mut s);
-            s
-        };
-        let a = make(&[0x01, 0x02, 0x03, 0x04, 0x05]);
-        let b = make(&[0x01, 0x02, 0x03, 0x04, 0x06]); // differs in last byte
-        assert_ne!(
-            &a[128..2048],
-            &b[128..2048],
-            "different title keys must descramble differently"
-        );
-    }
-
-    /// Descramble is keyed by the sector seed too: same title key, different
-    /// seed -> different body. Pins that bytes 0x54..0x59 actually feed the
-    /// keystream (not just the per-sector XOR key).
-    ///
-    /// Mutation: replace `seed` array reads with a constant -> both seeds give
-    /// the same body, assert fires.
-    #[test]
-    fn descramble_output_depends_on_seed() {
-        let key = [0x01, 0x02, 0x03, 0x04, 0x05];
-        let make = |seed: [u8; 5]| {
-            let mut s = vec![0x00u8; 2048];
-            s[0x14] = 0x30;
-            s[0x54..0x59].copy_from_slice(&seed);
-            descramble_sector(&key, &mut s);
-            s
-        };
-        let a = make([0x11, 0x22, 0x33, 0x44, 0x55]);
-        let b = make([0x11, 0x22, 0x33, 0x44, 0x56]);
-        assert_ne!(
-            &a[128..2048],
-            &b[128..2048],
-            "different seeds must descramble differently"
-        );
-    }
 }

src/css/tables.rs

@@ -24,8 +24,7 @@ pub const TAB1: [u8; 256] = [
     0xb7, 0xf7, 0xbf, 0xa2, 0xe7, 0xa7, 0xef, 0xf2, 0xba, 0xfa, 0xb2, 0xaf, 0xea, 0xaa, 0xe2, 0xff,
 ];
 
-/// Table 2: LFSR1 high-byte feedback permutation — a fixed constant of the CSS
-/// cipher (per the published algorithm).
+/// Table 2: LFSR1 high-byte feedback permutation.
 pub const TAB2: [u8; 256] = [
     0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x09, 0x08, 0x0b, 0x0a, 0x0d, 0x0c, 0x0f, 0x0e,
     0x12, 0x13, 0x10, 0x11, 0x16, 0x17, 0x14, 0x15, 0x1b, 0x1a, 0x19, 0x18, 0x1f, 0x1e, 0x1d, 0x1c,
@@ -41,18 +40,11 @@ pub const TAB2: [u8; 256] = [
     0xa4, 0xa5, 0xa6, 0xa7, 0xa0, 0xa1, 0xa2, 0xa3, 0xad, 0xac, 0xaf, 0xae, 0xa9, 0xa8, 0xab, 0xaa,
     0xdb, 0xda, 0xd9, 0xd8, 0xdf, 0xde, 0xdd, 0xdc, 0xd2, 0xd3, 0xd0, 0xd1, 0xd6, 0xd7, 0xd4, 0xd5,
     0xc9, 0xc8, 0xcb, 0xca, 0xcd, 0xcc, 0xcf, 0xce, 0xc0, 0xc1, 0xc2, 0xc3, 0xc4, 0xc5, 0xc6, 0xc7,
-    0xff, 0xfe, 0xfd, 0xfc, 0xfb, 0xfa, 0xf9, 0xf8, 0xf6, 0xf7, 0xf4, 0xf5, 0xf2, 0xf3, 0xf0, 0xf1,
     0xed, 0xec, 0xef, 0xee, 0xe9, 0xe8, 0xeb, 0xea, 0xe4, 0xe5, 0xe6, 0xe7, 0xe0, 0xe1, 0xe2, 0xe3,
+    0xff, 0xfe, 0xfd, 0xfc, 0xfb, 0xfa, 0xf9, 0xf8, 0xf6, 0xf7, 0xf4, 0xf5, 0xf2, 0xf3, 0xf0, 0xf1,
 ];
 
-/// Table 3: LFSR1 9-bit low-word feedback table (512 entries) — a fixed constant
-/// of the CSS cipher (per the published algorithm).
-///
-/// It is the 8-value block `BASE[i & 7]` repeated 64 times. The CSS LFSR1 step
-/// indexes this table with the 9-bit low register (0x100..=0x1FF), but only the
-/// low 3 bits select the output — the high bits are ignored, hence the constant
-/// blocks. The 512-entry width simply lets the 9-bit index be used without
-/// masking.
+/// Table 3: LFSR1 low-byte feedback permutation.
 pub const TAB3: [u8; 512] = [
     0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
     0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
@@ -62,30 +54,30 @@ pub const TAB3: [u8; 512] = [
     0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
     0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
     0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
-    0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff, 0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff,
+    0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe, 0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe,
+    0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe, 0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe,
+    0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe, 0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe,
+    0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe, 0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe,
+    0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe, 0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe,
+    0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe, 0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe,
+    0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe, 0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe,
+    0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe, 0x01, 0x25, 0x48, 0x6c, 0x93, 0xb7, 0xda, 0xfe,
+    0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd, 0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd,
+    0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd, 0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd,
+    0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd, 0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd,
+    0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd, 0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd,
+    0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd, 0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd,
+    0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd, 0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd,
+    0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd, 0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd,
+    0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd, 0x02, 0x26, 0x4b, 0x6f, 0x90, 0xb4, 0xd9, 0xfd,
+    0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc, 0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc,
+    0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc, 0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc,
+    0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc, 0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc,
+    0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc, 0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc,
+    0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc, 0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc,
+    0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc, 0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc,
+    0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc, 0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc,
+    0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc, 0x03, 0x27, 0x4a, 0x6e, 0x91, 0xb5, 0xd8, 0xfc,
 ];
 
 /// Table 4: LFSR0 byte permutation (used in initialization and output).
@@ -108,10 +100,8 @@ pub const TAB4: [u8; 256] = [
     0x0f, 0x8f, 0x4f, 0xcf, 0x2f, 0xaf, 0x6f, 0xef, 0x1f, 0x9f, 0x5f, 0xdf, 0x3f, 0xbf, 0x7f, 0xff,
 ];
 
-/// Table 5: LFSR1 output permutation used in the keystream combiner.
-/// `TAB5[i] == TAB4[i] ^ 0xFF` (bitwise complement of the TAB4 bit-reversal
-/// table). Applied on the normal descramble/recrypt path (lfsr.rs) as well as
-/// in the key-recovery fallback (crack.rs).
+/// Table 5: LFSR1 output permutation for the Stevenson attack.
+/// This is the inverse byte-reversal of TAB4.
 pub const TAB5: [u8; 256] = [
     0xff, 0x7f, 0xbf, 0x3f, 0xdf, 0x5f, 0x9f, 0x1f, 0xef, 0x6f, 0xaf, 0x2f, 0xcf, 0x4f, 0x8f, 0x0f,
     0xf7, 0x77, 0xb7, 0x37, 0xd7, 0x57, 0x97, 0x17, 0xe7, 0x67, 0xa7, 0x27, 0xc7, 0x47, 0x87, 0x07,
@@ -130,155 +120,3 @@ pub const TAB5: [u8; 256] = [
     0xf8, 0x78, 0xb8, 0x38, 0xd8, 0x58, 0x98, 0x18, 0xe8, 0x68, 0xa8, 0x28, 0xc8, 0x48, 0x88, 0x08,
     0xf0, 0x70, 0xb0, 0x30, 0xd0, 0x50, 0x90, 0x10, 0xe0, 0x60, 0xa0, 0x20, 0xc0, 0x40, 0x80, 0x00,
 ];
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    /// Pins the documented relationship `TAB5[i] == TAB4[i] ^ 0xFF` so the
-    /// table doc cannot drift from the data.
-    #[test]
-    fn tab5_is_complement_of_tab4() {
-        for i in 0..256 {
-            assert_eq!(
-                TAB5[i],
-                TAB4[i] ^ 0xFF,
-                "TAB5[{i:#04x}] != TAB4[{i:#04x}] ^ 0xFF"
-            );
-        }
-    }
-
-    /// TAB1 is a bijection on 0..256. CSS uses it as an invertible output
-    /// permutation in css_DecryptKey's chained-XOR rounds; if two inputs
-    /// collided, the key mangling would not be invertible.
-    ///
-    /// Mutation: duplicate any value (e.g. set TAB1[1] = TAB1[0]) -> the
-    /// "maps two inputs" assert fires.
-    #[test]
-    fn tab1_is_a_permutation() {
-        let mut seen = [false; 256];
-        for (i, &v) in TAB1.iter().enumerate() {
-            assert!(
-                !seen[v as usize],
-                "TAB1 maps two inputs to {v:#04x} (collision at index {i:#04x})"
-            );
-            seen[v as usize] = true;
-        }
-    }
-
-    /// TAB1's fixed structural anchors from the CSS spec table:
-    /// TAB1[0x00] == 0x33 and the inverse TAB1[0x33] == 0x00. These two
-    /// entries are the canonical first-row / inverse-lookup landmarks of the
-    /// published CSS TAB1 and pin the table's orientation.
-    ///
-    /// Grounding: CSS specification TAB1, row 0 col 0 = 0x33; index 0x33
-    /// (row 3 col 3) = 0x00.
-    /// Mutation: change the first literal `0x33` in TAB1 -> first assert fails.
-    #[test]
-    fn tab1_known_spec_anchors() {
-        assert_eq!(TAB1[0x00], 0x33, "TAB1[0] is the published 0x33");
-        assert_eq!(TAB1[0x33], 0x00, "TAB1[0x33] is the published 0x00");
-    }
-
-    /// TAB2 is a permutation of 0..256 (it is the LFSR1 high-byte feedback
-    /// substitution). A non-bijective TAB2 would bias the LFSR1 keystream.
-    ///
-    /// Mutation: set TAB2[8] = 0x00 (collides with TAB2[0]) -> assert fires.
-    #[test]
-    fn tab2_is_a_permutation() {
-        let mut seen = [false; 256];
-        for (i, &v) in TAB2.iter().enumerate() {
-            assert!(
-                !seen[v as usize],
-                "TAB2 maps two inputs to {v:#04x} (collision at index {i:#04x})"
-            );
-            seen[v as usize] = true;
-        }
-    }
-
-    /// TAB3 is the CSS LFSR1 low-word table: the 8-value feedback block
-    ///   BASE = [0x00,0x24,0x49,0x6d,0x92,0xb6,0xdb,0xff]
-    /// repeated 64 times — `TAB3[i] == BASE[i & 7]`. The high bits of the
-    /// 9-bit index do not affect the output (the LFSR1 step indexes with the
-    /// full 9-bit low register but only `& 7` matters). This pins all 512
-    /// entries to the published cipher's table.
-    ///
-    /// Mutation: flip any single byte in the TAB3 literal -> the formula
-    /// check fails at that index.
-    #[test]
-    fn tab3_matches_lfsr1_generating_formula() {
-        const BASE: [u8; 8] = [0x00, 0x24, 0x49, 0x6d, 0x92, 0xb6, 0xdb, 0xff];
-        for i in 0..512usize {
-            let expected = BASE[i & 7];
-            assert_eq!(
-                TAB3[i], expected,
-                "TAB3[{i:#05x}] = {:#04x}, formula BASE[i&7] = {expected:#04x}",
-                TAB3[i]
-            );
-        }
-    }
-
-    /// TAB4 is the exact bit-reversal of each byte (CSS uses it to permute
-    /// LFSR0 bytes on seed and output). TAB4[b] reverses b's 8 bits MSB<->LSB.
-    /// Therefore it is also an involution: TAB4[TAB4[b]] == b.
-    ///
-    /// Grounding: TAB4[0x01]=0x80, TAB4[0x80]=0x01, TAB4[0x00]=0x00,
-    /// TAB4[0xFF]=0xFF.
-    /// Mutation: set TAB4[1] = 0x40 (not the reversal 0x80) -> bit-reversal
-    /// check fails at index 1.
-    #[test]
-    fn tab4_is_exact_bit_reversal_and_involution() {
-        for b in 0u16..256 {
-            let rev = (0..8).fold(0u8, |acc, k| acc | (((b as u8 >> k) & 1) << (7 - k)));
-            assert_eq!(
-                TAB4[b as usize], rev,
-                "TAB4[{b:#04x}] is not the bit-reversal {rev:#04x}"
-            );
-        }
-        for b in 0..256usize {
-            assert_eq!(
-                TAB4[TAB4[b] as usize], b as u8,
-                "TAB4 not an involution at {b:#04x}"
-            );
-        }
-        // Spec landmark entries.
-        assert_eq!(TAB4[0x01], 0x80);
-        assert_eq!(TAB4[0x80], 0x01);
-        assert_eq!(TAB4[0x00], 0x00);
-        assert_eq!(TAB4[0xFF], 0xFF);
-    }
-
-    /// TAB4 is a permutation (bit-reversal is bijective). Distinct from the
-    /// reversal test: a table that is "reversal except two swapped entries"
-    /// would still be a permutation, and a table that is "reversal except one
-    /// duplicated entry" would fail this but might pass a sampled reversal
-    /// check — the two tests pin different failure modes.
-    ///
-    /// Mutation: set TAB4[2] = TAB4[1] -> permutation assert fires.
-    #[test]
-    fn tab4_is_a_permutation() {
-        let mut seen = [false; 256];
-        for &v in TAB4.iter() {
-            assert!(!seen[v as usize], "TAB4 maps two inputs to {v:#04x}");
-            seen[v as usize] = true;
-        }
-    }
-
-    /// TAB5 is also a permutation (complement of a bijection is a bijection)
-    /// and its own self-consistency landmark: TAB5[0x00] == 0xFF (TAB4[0]^0xFF)
-    /// and TAB5[0xFF] == 0x00 (TAB4[0xFF]^0xFF). Pins orientation independent
-    /// of the complement-loop test.
-    ///
-    /// Mutation: change the first TAB5 literal 0xff -> 0xfe -> the landmark
-    /// and permutation checks both catch it.
-    #[test]
-    fn tab5_is_permutation_with_anchors() {
-        let mut seen = [false; 256];
-        for &v in TAB5.iter() {
-            assert!(!seen[v as usize], "TAB5 maps two inputs to {v:#04x}");
-            seen[v as usize] = true;
-        }
-        assert_eq!(TAB5[0x00], 0xFF, "TAB5[0] = TAB4[0]^0xFF = 0xFF");
-        assert_eq!(TAB5[0xFF], 0x00, "TAB5[0xFF] = TAB4[0xFF]^0xFF = 0x00");
-    }
-}

src/diag.rs

@@ -1,811 +0,0 @@
-//! Structured scan diagnostics — the `--log-level 3` self-diagnosing dump.
-//!
-//! A bug report log must be self-diagnosing: everything needed to explain
-//! *why* freemkv made the choices it did at scan must be in the log, in a
-//! compact, machine-parseable form. This module emits one terse line per row
-//! (title, cell, stream, decision) under the `tracing` target
-//! `freemkv::diag`, which the CLI routes to `log.txt` when `--log-level 3`
-//! (debug) is set.
-//!
-//! Format conventions (stable, greppable):
-//!   - Every line is prefixed by a `tag=` so a log scraper can filter
-//!     (`disc`, `title`, `dvd.cell`, `dvd.vattr`, `dvd.aattr`, `bd.clip`,
-//!     `bd.mark`, `aacs`, `stream`, `decision`).
-//!   - Raw bytes are shown as `0xNN` next to their decode so a wrong decode
-//!     is obvious against the raw value.
-//!   - This module only READS already-parsed scan state — it never re-reads
-//!     the disc and never mutates anything.
-//!
-//! The DVD per-cell table (with the raw cell-category byte) is emitted from
-//! the IFO scan itself ([`dump_dvd_cells`]), because the per-cell
-//! `ifo::DvdCell` detail is lowered away before the `Disc` is built. The
-//! `Disc`-level dump ([`dump_disc`]) covers everything that survives
-//! lowering: titles, streams, the picked main feature, and AACS state.
-
-use crate::disc::{ColorSpace, Disc, DiscTitle, FrameRate, HdrFormat, Resolution, Stream};
-use crate::ifo::{CellCategory, DvdTitle};
-
-const DIAG: &str = "freemkv::diag";
-
-// ── small format helpers (pure, unit-testable) ──────────────────────────────
-
-/// Compact name for a [`Resolution`] with the interlace marker preserved.
-pub fn res_str(r: Resolution) -> &'static str {
-    match r {
-        Resolution::R480i => "480i",
-        Resolution::R480p => "480p",
-        Resolution::R576i => "576i",
-        Resolution::R576p => "576p",
-        Resolution::R720p => "720p",
-        Resolution::R1080i => "1080i",
-        Resolution::R1080p => "1080p",
-        Resolution::R2160p => "2160p",
-        Resolution::R4320p => "4320p",
-        Resolution::Unknown => "res?",
-    }
-}
-
-/// Frames-per-second string for a [`FrameRate`].
-pub fn fps_str(f: FrameRate) -> &'static str {
-    match f {
-        FrameRate::F23_976 => "23.976",
-        FrameRate::F24 => "24",
-        FrameRate::F25 => "25",
-        FrameRate::F29_97 => "29.97",
-        FrameRate::F30 => "30",
-        FrameRate::F50 => "50",
-        FrameRate::F59_94 => "59.94",
-        FrameRate::F60 => "60",
-        FrameRate::Unknown => "fps?",
-    }
-}
-
-/// PAL/NTSC field-rate family inferred from the frame rate (DVD has no
-/// explicit field, so this is the colour/standard the muxer stamps).
-pub fn tv_system_str(f: FrameRate) -> &'static str {
-    match f {
-        FrameRate::F25 | FrameRate::F50 => "PAL",
-        FrameRate::F23_976 | FrameRate::F29_97 | FrameRate::F59_94 => "NTSC",
-        _ => "—",
-    }
-}
-
-/// CICP-ish short name for a [`ColorSpace`].
-pub fn color_str(c: ColorSpace) -> &'static str {
-    match c {
-        ColorSpace::Bt709 => "BT.709",
-        ColorSpace::Bt2020 => "BT.2020",
-        ColorSpace::Bt470bg => "BT.470BG",
-        ColorSpace::Smpte170m => "SMPTE-170M",
-        ColorSpace::Unknown => "color?",
-    }
-}
-
-/// HDR format short name.
-pub fn hdr_str(h: HdrFormat) -> &'static str {
-    match h {
-        HdrFormat::Sdr => "SDR",
-        HdrFormat::Hdr10 => "HDR10",
-        HdrFormat::Hdr10Plus => "HDR10+",
-        HdrFormat::DolbyVision => "DoVi",
-        HdrFormat::Hlg => "HLG",
-    }
-}
-
-// `channel_count` and `sample_rate_hz` lived here as a third copy of the
-// AudioChannels/SampleRate mappings. They were the only HONEST copy — returning
-// 0 for Unknown where the canonical accessors fabricated 6 channels at 48 kHz —
-// and their only caller was the trace line below, in this same file. The
-// canonical accessors are honest now, so the duplicates are gone rather than
-// left to drift a fourth time.
-
-// ── DVD cell-category dump (from the IFO scan, pre-lowering) ─────────────────
-
-/// One formatted cell row for the DVD per-PGC cell table. Returned as a
-/// string so it can be unit-tested without a logger.
-///
-/// Columns: `idx`, raw category (`cat=0xNN`) + decoded fields, first/last
-/// sector, duration, and the keep/drop verdict from the bug-4 leading-cell
-/// filter.
-pub fn dvd_cell_row(idx: usize, cell: &crate::ifo::DvdCell, dropped: bool) -> String {
-    let c = CellCategory::decode(cell.category);
-    // Per-cell keep/skip REASON (self-sufficient bug log): a dropped cell is a
-    // leading secondary angle/interleave block piece; a kept cell is either the
-    // first feature cell or genuine feature content. This makes the
-    // leading-cell-filter decision auditable from the log without the disc.
-    let verdict = if dropped {
-        "DROP(leading-secondary-block-piece)"
-    } else if c.is_secondary_block_piece() {
-        // Kept despite being a secondary piece — only happens past the leading
-        // run (the filter stops at the first plain feature cell).
-        "keep(feature-body)"
-    } else {
-        "keep(plain-feature)"
-    };
-    format!(
-        "tag=dvd.cell idx={idx} cat=0x{:02X} block_mode={} block_type={} \
-seamless={} ilv={} stc={} angle={} plain={} first={} last={} dur={:.1}s {}",
-        cell.category,
-        c.block_mode,
-        c.block_type,
-        c.seamless_play as u8,
-        c.interleaved as u8,
-        c.stc_discontinuity as u8,
-        c.seamless_angle as u8,
-        c.is_plain_feature() as u8,
-        cell.first_sector,
-        cell.last_sector,
-        cell.duration_secs,
-        verdict,
-    )
-}
-
-/// Emit the per-PGC cell table for one DVD title during the IFO scan.
-///
-/// `vts`/`title` identify the row group; `title` is the `DvdTitle` whose
-/// cells (and bug-4 leading-cell verdict) are dumped. Called from
-/// `scan_dvd_titles` while the `DvdTitle` is still in scope (the per-cell
-/// category byte is lowered away before the `Disc` exists).
-pub fn dump_dvd_cells(vts: u8, title_num: u16, title: &DvdTitle) {
-    if !tracing::enabled!(target: DIAG, tracing::Level::DEBUG) {
-        return;
-    }
-    let feature_start = title.feature_start_cell();
-    tracing::debug!(
-        target: DIAG,
-        "tag=dvd.pgc vts={vts} title={title_num} cells={} chapters={} \
-    dur={:.1}s feature_start_cell={feature_start}",
-        title.cells.len(),
-        title.chapters,
-        title.duration_secs,
-    );
-    for (i, cell) in title.cells.iter().enumerate() {
-        tracing::debug!(target: DIAG, "{}", dvd_cell_row(i, cell, i < feature_start));
-    }
-    // Chapter/PTT map (program → cumulative start time).
-    for (i, &t) in title.chapter_times.iter().enumerate() {
-        tracing::debug!(
-            target: DIAG,
-            "tag=dvd.chap vts={vts} title={title_num} ch={} time={:.1}s",
-            i + 1,
-            t,
-        );
-    }
-}
-
-/// Emit the IFO `video_attr` / `audio_attr` decode for one DVD title set,
-/// showing the raw bytes next to their decoded meaning. Called from the IFO
-/// scan with the still-parsed `ifo::DvdTitleSet` view.
-pub fn dump_dvd_attrs(ts: &crate::ifo::DvdTitleSet) {
-    if !tracing::enabled!(target: DIAG, tracing::Level::DEBUG) {
-        return;
-    }
-    tracing::debug!(
-        target: DIAG,
-        "tag=dvd.vobs vts={} vob_start_sector={}",
-        ts.vts_number,
-        ts.vob_start_sector,
-    );
-    let v = &ts.video;
-    tracing::debug!(
-        target: DIAG,
-        "tag=dvd.vattr vts={} codec={:?} res={} aspect={:?} std={:?}",
-        ts.vts_number,
-        v.codec,
-        res_str(v.resolution),
-        v.aspect,
-        v.standard,
-    );
-    for (i, a) in ts.audio_streams.iter().enumerate() {
-        tracing::debug!(
-            target: DIAG,
-            "tag=dvd.aattr vts={} idx={i} codec={:?} ch={} sr={}Hz lang={:?} sub_id={:?}",
-            ts.vts_number,
-            a.codec,
-            a.channels,
-            a.sample_rate,
-            a.language,
-            a.sub_stream_id.map(|x| format!("0x{x:02X}")),
-        );
-    }
-    for (i, s) in ts.subtitle_streams.iter().enumerate() {
-        tracing::debug!(
-            target: DIAG,
-            "tag=dvd.sattr vts={} idx={i} lang={:?}",
-            ts.vts_number,
-            s.language,
-        );
-    }
-}
-
-/// Emit the ACTUAL per-physical-sub-stream AC-3 channel counts read off the VOB
-/// during the mux-time sub-stream probe (the Silence-of-the-Lambs wrong-stream
-/// fix). This is the ground truth the IFO nibble is compared against: each row
-/// is `sub_id=0x8x channels=N` for a physical `private_stream_1` AC-3 sub-stream
-/// whose first frame was decoded. An empty probe (scrambled / unreadable / short
-/// VOB) logs a single `probed=0` line so the absence is explicit in a bug log.
-///
-/// Self-sufficiency: with `tag=dvd.aattr` (the IFO's declared sub_id + claimed
-/// channels) and these `tag=dvd.substream` rows (the physical reality), a bug
-/// log alone shows whether the ordinal `0x80` actually carries the declared
-/// channel layout — no disc needed to diagnose a wrong-substream rip.
-pub fn dump_dvd_substream_probe(title_id: u16, probed: &std::collections::BTreeMap<u8, u8>) {
-    if !tracing::enabled!(target: DIAG, tracing::Level::DEBUG) {
-        return;
-    }
-    if probed.is_empty() {
-        tracing::debug!(
-            target: DIAG,
-            "tag=dvd.substream title={title_id} probed=0 (no AC-3 sync in feature head — scrambled/unreadable/none)",
-        );
-        return;
-    }
-    for (sub, ch) in probed {
-        tracing::debug!(
-            target: DIAG,
-            "tag=dvd.substream title={title_id} sub_id=0x{sub:02X} channels={ch} (physical acmod read from VOB)",
-        );
-    }
-}
-
-// ── MKV TrackEntry dump (the ACTUAL container elements written) ──────────────
-
-/// `true` when the `--log-level 3` diagnostic target is enabled. Hot-path
-/// callers (the opening-frame capture) check this once and skip all work when
-/// off, so a normal run pays nothing.
-pub fn diag_enabled() -> bool {
-    tracing::enabled!(target: DIAG, tracing::Level::DEBUG)
-}
-
-/// Cap on the number of codecPrivate bytes rendered to hex in a `tag=mkv.track`
-/// line. The sequence header / avcC / hvcC prefix that matters for diagnosis
-/// (resolution, frame rate, profile) is at the front; a multi-KB blob past this
-/// is summarised as `..(+NB)` rather than flooding the log.
-const CODEC_PRIVATE_HEX_CAP: usize = 64;
-
-/// Render a track's codecPrivate as an uppercase-hex string for the diagnostic
-/// line, capped at [`CODEC_PRIVATE_HEX_CAP`] bytes (`..(+NB)` suffix beyond).
-/// `None` / empty → `"none"`. Pure (no logging) so it is directly unit-testable.
-fn codec_private_hex(cp: Option<&[u8]>) -> String {
-    match cp {
-        Some(b) if !b.is_empty() => {
-            use std::fmt::Write;
-            let shown = b.len().min(CODEC_PRIVATE_HEX_CAP);
-            let mut s = String::with_capacity(shown * 2 + 8);
-            for byte in &b[..shown] {
-                let _ = write!(s, "{byte:02X}");
-            }
-            if b.len() > CODEC_PRIVATE_HEX_CAP {
-                let _ = write!(s, "..(+{}B)", b.len() - CODEC_PRIVATE_HEX_CAP);
-            }
-            s
-        }
-        _ => "none".to_string(),
-    }
-}
-
-/// Frame the raw bytes of one captured opening frame for the `.opening.bin` side
-/// file: `[track:u8][keyframe:u8][pts_ns:i64 LE][len:u32 LE][raw bytes]`. Pure
-/// (no I/O) so the record layout is directly unit-testable; `record` appends the
-/// returned bytes to the side file.
-fn frame_record(track_idx: usize, pts_ns: i64, keyframe: bool, data: &[u8]) -> Vec<u8> {
-    let mut rec = Vec::with_capacity(14 + data.len());
-    rec.push(track_idx as u8);
-    rec.push(keyframe as u8);
-    rec.extend_from_slice(&pts_ns.to_le_bytes());
-    rec.extend_from_slice(&(data.len() as u32).to_le_bytes());
-    rec.extend_from_slice(data);
-    rec
-}
-
-/// Emit the MKV `TrackEntry` elements the muxer is about to WRITE for one
-/// track — the Windows-fps-class metadata (FlagInterlaced, FieldOrder,
-/// DefaultDuration, DefaultDecodedFieldDuration, Display dims) plus the
-/// codecPrivate as hex. With this row a bug log alone is enough to verify why
-/// Windows Explorer reports a given frame rate for an interlaced SD track: the
-/// container values that drive its fps derivation are all present, no disc and
-/// no MediaInfo needed.
-///
-/// `track_number` is the 1-based MKV track number; `track` is the built
-/// [`crate::mux::mkv::MkvTrack`] whose fields map one-to-one onto the emitted
-/// elements (see `MkvMuxer::new`). No-op unless the diag target is on.
-pub(crate) fn dump_mkv_track(track_number: u64, track: &crate::mux::mkv::MkvTrack) {
-    if !diag_enabled() {
-        return;
-    }
-    // codecPrivate as hex (capped so a multi-KB hvcC doesn't flood the log; the
-    // sequence header / avcC prefix that matters for diagnosis is at the front).
-    let cp = codec_private_hex(track.codec_private.as_deref());
-    let field_order = match track.field_order {
-        crate::mux::ebml::FIELD_ORDER_TFF => "TFF",
-        crate::mux::ebml::FIELD_ORDER_BFF => "BFF",
-        _ => "—",
-    };
-    // FlagInterlaced is only written for video tracks (1=interlaced/2=progressive);
-    // report what the muxer will emit, or "—" for non-video tracks where the
-    // element is omitted entirely.
-    let interlaced = if track.track_type == crate::mux::ebml::TRACK_TYPE_VIDEO {
-        if track.interlaced {
-            "1(interlaced)"
-        } else {
-            "2(progressive)"
-        }
-    } else {
-        "—"
-    };
-    tracing::debug!(
-        target: DIAG,
-        "tag=mkv.track num={track_number} type={} codec={} flag_interlaced={interlaced} \
-    field_order={field_order} default_duration_ns={} field_duration_ns={} \
-    pixel={}x{} display={}x{} cp_len={} cp_hex={cp}",
-        track.track_type,
-        track.codec_id,
-        track.default_duration_ns,
-        track.field_duration_ns,
-        track.pixel_width,
-        track.pixel_height,
-        track.display_width,
-        track.display_height,
-        track.codec_private.as_ref().map_or(0, |b| b.len()),
-    );
-}
-
-// ── Opening-frame capture (first ~N coded frames per track → side file) ──────
-
-/// Number of coded frames captured PER TRACK before the capture goes dormant.
-/// ~100 frames covers a DVD's first few seconds of every track (the
-/// opening-GOP / still-frame / menu window where mid-GOP open or PTS-floor bugs
-/// show up) while bounding the side file to a few MB even for HD I-frames.
-const OPENING_FRAMES_PER_TRACK: usize = 100;
-
-/// Captures the first [`OPENING_FRAMES_PER_TRACK`] coded frames of EACH track to
-/// a side file (`<output>.opening.bin`) and logs a per-frame summary line, so an
-/// opening-GOP / menu / mid-GOP-open issue is diagnosable from a future log +
-/// side file WITHOUT the disc. Gated to `--log-level 3`: constructed only when
-/// the diag target is on, so a normal run never opens the file or records a byte.
-///
-/// Side-file record framing (so a reader can split it back into frames):
-/// `[track:u8][keyframe:u8][pts_ns:i64 LE][len:u32 LE][raw frame bytes]`.
-pub struct OpeningCapture {
-    file: std::fs::File,
-    /// Frames captured so far, per track index. Capture for a track stops once
-    /// its counter reaches [`OPENING_FRAMES_PER_TRACK`].
-    counts: Vec<usize>,
-}
-
-impl OpeningCapture {
-    /// Open `<output>.opening.bin` next to the MKV output. Returns `None` (no
-    /// capture) when the diag target is off OR the side file can't be created —
-    /// a diagnostic must never fail the rip. `track_count` sizes the per-track
-    /// counters.
-    pub fn new(output_path: &std::path::Path, track_count: usize) -> Option<Self> {
-        if !diag_enabled() {
-            return None;
-        }
-        let mut name = output_path.as_os_str().to_os_string();
-        name.push(".opening.bin");
-        match std::fs::File::create(&name) {
-            Ok(file) => {
-                tracing::debug!(
-                    target: DIAG,
-                    "tag=mkv.opening.open path={:?} per_track_cap={OPENING_FRAMES_PER_TRACK}",
-                    std::path::Path::new(&name),
-                );
-                Some(Self {
-                    file,
-                    counts: vec![0; track_count],
-                })
-            }
-            Err(e) => {
-                tracing::debug!(
-                    target: DIAG,
-                    "tag=mkv.opening.open path={:?} failed={e} (capture disabled, rip unaffected)",
-                    std::path::Path::new(&name),
-                );
-                None
-            }
-        }
-    }
-
-    /// Record one coded frame for `track_idx` if that track is still under its
-    /// per-track cap. Writes the framed raw bytes to the side file and logs a
-    /// one-line summary. A write error disables further capture for the track
-    /// (counter pinned to the cap) but never propagates — the rip is unaffected.
-    pub fn record(&mut self, track_idx: usize, pts_ns: i64, keyframe: bool, data: &[u8]) {
-        let Some(count) = self.counts.get_mut(track_idx) else {
-            return;
-        };
-        if *count >= OPENING_FRAMES_PER_TRACK {
-            return;
-        }
-        use std::io::Write;
-        let rec = frame_record(track_idx, pts_ns, keyframe, data);
-        if let Err(e) = self.file.write_all(&rec) {
-            // Stop trying on this track; a broken side file must not stall mux.
-            *count = OPENING_FRAMES_PER_TRACK;
-            tracing::debug!(
-                target: DIAG,
-                "tag=mkv.opening.frame track={track_idx} write_failed={e} (capture stopped for track)",
-            );
-            return;
-        }
-        *count += 1;
-        tracing::debug!(
-            target: DIAG,
-            "tag=mkv.opening.frame track={track_idx} n={count} type={} size={} pts_ns={pts_ns}",
-            if keyframe { "key" } else { "delta" },
-            data.len(),
-        );
-    }
-}
-
-// ── Disc-level dump (post-lowering: titles, streams, decisions, AACS) ────────
-
-/// Emit the full scan diagnostic block for a built [`Disc`]. Terse, one line
-/// per row, under target `freemkv::diag` at DEBUG. No-op unless that target
-/// is enabled, so it costs nothing when `--log-level 3` is off.
-pub fn dump_disc(disc: &Disc) {
-    if !tracing::enabled!(target: DIAG, tracing::Level::DEBUG) {
-        return;
-    }
-
-    tracing::debug!(
-        target: DIAG,
-        "tag=disc vol={:?} format={:?} content={:?} cap_sectors={} layers={} titles={} encrypted={}",
-        disc.volume_id,
-        disc.format,
-        disc.content_format,
-        disc.capacity_sectors,
-        disc.layers,
-        disc.titles.len(),
-        disc.encrypted,
-    );
-
-    dump_aacs(disc);
-
-    for (ti, title) in disc.titles.iter().enumerate() {
-        dump_title(ti, title);
-    }
-
-    // freemkv's top-level DECISION: which title is the main feature.
-    if let Some(main) = disc.titles.first() {
-        tracing::debug!(
-            target: DIAG,
-            "tag=decision pick=main_feature title_idx=0 playlist={:?} dur={:.1}s \
-        size={}B clips={} reason={}",
-            main.playlist,
-            main.duration_secs,
-            main.size_bytes,
-            main.clips.len(),
-            main_feature_reason(),
-        );
-    }
-}
-
-/// The `reason=` token on the main-feature decision row.
-///
-/// DERIVED from [`Disc::CANONICAL_TITLE_ORDER_KEYS`], which lives beside the
-/// comparator that actually implements them — never restated here. The previous
-/// hand-written copy drifted (it advertised a `fewest-clips` key the comparator
-/// had replaced with largest-physical-size), which made the self-diagnosing log
-/// explain the pick with a rule the code does not apply. A diagnostic that
-/// disagrees with the decision it documents is worse than no diagnostic.
-fn main_feature_reason() -> String {
-    format!(
-        "canonical_title_order({})",
-        Disc::CANONICAL_TITLE_ORDER_KEYS.join(", ")
-    )
-}
-
-fn dump_aacs(disc: &Disc) {
-    let Some(a) = disc.aacs.as_ref() else {
-        if disc.css.is_some() {
-            tracing::debug!(target: DIAG, "tag=aacs none crypto=CSS(DVD)");
-        } else if disc.encrypted {
-            tracing::debug!(target: DIAG, "tag=aacs none crypto=encrypted-no-keys");
-        } else {
-            tracing::debug!(target: DIAG, "tag=aacs none crypto=clear");
-        }
-        return;
-    };
-    // CPS-unit / unit-key counts: at scan `unit_keys` is empty (keys are
-    // resolved later); the unit-key count is the BE16 in the raw
-    // Unit_Key_RO.inf if captured. Report both: resolved count and raw len.
-    tracing::debug!(
-        target: DIAG,
-        "tag=aacs version={} bus_enc={} mkb_version={:?} disc_hash={} key_source={:?} \
-    vuk={} unit_keys_resolved={} uk_ro_bytes={} mkb_bytes={}",
-        a.version,
-        a.bus_encryption,
-        a.mkb_version,
-        a.disc_hash,
-        a.key_source,
-        a.vuk.is_some(),
-        a.unit_keys.len(),
-        a.uk_ro.len(),
-        a.mkb.len(),
-    );
-}
-
-fn dump_title(ti: usize, title: &DiscTitle) {
-    let (mut nv, mut na, mut ns) = (0u32, 0u32, 0u32);
-    for s in &title.streams {
-        match s {
-            Stream::Video(_) => nv += 1,
-            Stream::Audio(_) => na += 1,
-            Stream::Subtitle(_) => ns += 1,
-        }
-    }
-    tracing::debug!(
-        target: DIAG,
-        "tag=title idx={ti} playlist={:?} id={} dur={:.1}s size={}B clips={} \
-    extents={} chapters={} v={nv} a={na} s={ns} fmt={:?}",
-        title.playlist,
-        title.playlist_id,
-        title.duration_secs,
-        title.size_bytes,
-        title.clips.len(),
-        title.extents.len(),
-        title.chapters.len(),
-        title.content_format,
-    );
-
-    // Per-clip rows (BD: PlayItem/CLPI; DVD has none).
-    for (ci, c) in title.clips.iter().enumerate() {
-        tracing::debug!(
-            target: DIAG,
-            "tag=clip title={ti} idx={ci} id={:?} in={} out={} dur={:.1}s src_packets={}",
-            c.clip_id,
-            c.in_time,
-            c.out_time,
-            c.duration_secs,
-            c.source_packets,
-        );
-    }
-
-    // Per-extent rows (the sectors freemkv will actually rip — the bug-4
-    // decision is visible here: leading non-feature cells are already gone).
-    for (ei, e) in title.extents.iter().enumerate() {
-        tracing::debug!(
-            target: DIAG,
-            "tag=extent title={ti} idx={ei} start_lba={} sectors={}",
-            e.start_lba,
-            e.sector_count,
-        );
-    }
-
-    // freemkv's per-stream DECISIONS (what the muxer will write).
-    for (si, s) in title.streams.iter().enumerate() {
-        match s {
-            Stream::Video(v) => tracing::debug!(
-                target: DIAG,
-                "tag=stream title={ti} idx={si} kind=video pid=0x{:04X} codec={:?} \
-            res={} interlaced={} fps={} std={} color={} hdr={} aspect={:?} secondary={}",
-                v.pid,
-                v.codec,
-                res_str(v.resolution),
-                v.resolution.is_interlaced(),
-                fps_str(v.frame_rate),
-                tv_system_str(v.frame_rate),
-                color_str(v.color_space),
-                hdr_str(v.hdr),
-                v.display_aspect,
-                v.secondary,
-            ),
-            Stream::Audio(a) => tracing::debug!(
-                target: DIAG,
-                "tag=stream title={ti} idx={si} kind=audio pid=0x{:04X} codec={:?} \
-            channels={}({}) sr={}Hz lang={:?} secondary={}",
-                a.pid,
-                a.codec,
-                a.channels,
-                a.channels.count(),
-                a.sample_rate.hz(),
-                a.language,
-                a.secondary,
-            ),
-            Stream::Subtitle(sub) => tracing::debug!(
-                target: DIAG,
-                "tag=stream title={ti} idx={si} kind=subtitle pid=0x{:04X} codec={:?} \
-            lang={:?} forced={}",
-                sub.pid,
-                sub.codec,
-                sub.language,
-                sub.forced,
-            ),
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    // Needed only by the tests: the production code in this file no longer names
-    // these types directly, since the local channel/sample-rate duplicates were
-    // deleted in favour of the canonical accessors.
-    use crate::disc::{AudioChannels, SampleRate};
-
-    /// The main-feature decision row must NAME `canonical_title_order`'s sort
-    /// keys, not restate them from memory. The restated copy had drifted: it
-    /// still advertised a "fewest-clips" key long after the comparator replaced
-    /// clip-count with largest-physical-size, so a bug report read at
-    /// `--log-level 3` explained the pick with a rule the code does not apply.
-    ///
-    /// The behavioural half is asserted first — against the comparator itself,
-    /// with literals — so the key names are checked against what the code
-    /// actually does, not against the string that names them.
-    #[test]
-    fn main_feature_reason_names_the_comparators_real_keys() {
-        use crate::disc::{Clip, Disc, DiscTitle};
-
-        let sized = |size_bytes: u64, n_clips: usize| DiscTitle {
-            size_bytes,
-            clips: (0..n_clips)
-                .map(|i| Clip {
-                    feed_span: None,
-                    clip_id: format!("{i:05}"),
-                    in_time: 0,
-                    out_time: 0,
-                    duration_secs: 0.0,
-                    source_packets: 0,
-                })
-                .collect(),
-            ..DiscTitle::empty()
-        };
-        // A 40-clip 8 GB title beats a 1-clip 1 GB title: the comparator's
-        // primary key among disc-fitting titles is LARGEST SIZE. "fewest clips"
-        // would predict the opposite, so the drifted string described a rule
-        // the comparator does not implement.
-        let many_clips_big = sized(8_000_000_000, 40);
-        let one_clip_small = sized(1_000_000_000, 1);
-        assert_eq!(
-            Disc::canonical_title_order(&many_clips_big, &one_clip_small, 25_000_000_000),
-            std::cmp::Ordering::Less,
-            "largest size wins regardless of clip count"
-        );
-
-        let reason = main_feature_reason();
-        assert!(
-            !reason.contains("clips"),
-            "the reason must not advertise a clip-count key the comparator dropped: {reason}"
-        );
-        assert_eq!(
-            reason, "canonical_title_order(fits-disc, largest-size, longest, richest-audio)",
-            "the reason must name the comparator's four keys in priority order"
-        );
-    }
-
-    #[test]
-    fn res_str_keeps_interlace_marker() {
-        assert_eq!(res_str(Resolution::R576i), "576i");
-        assert_eq!(res_str(Resolution::R480i), "480i");
-        assert_eq!(res_str(Resolution::R2160p), "2160p");
-    }
-
-    #[test]
-    fn fps_and_tv_system() {
-        assert_eq!(fps_str(FrameRate::F25), "25");
-        assert_eq!(tv_system_str(FrameRate::F25), "PAL");
-        assert_eq!(fps_str(FrameRate::F29_97), "29.97");
-        assert_eq!(tv_system_str(FrameRate::F29_97), "NTSC");
-    }
-
-    #[test]
-    fn color_and_hdr() {
-        assert_eq!(color_str(ColorSpace::Bt470bg), "BT.470BG");
-        assert_eq!(color_str(ColorSpace::Bt2020), "BT.2020");
-        assert_eq!(hdr_str(HdrFormat::Hdr10), "HDR10");
-        assert_eq!(hdr_str(HdrFormat::DolbyVision), "DoVi");
-        assert_eq!(hdr_str(HdrFormat::Sdr), "SDR");
-    }
-
-    /// Moved from the deleted local duplicates onto the canonical accessors,
-    /// with the Unknown case added — which is the whole point of the change.
-    #[test]
-    fn channel_count_matches_layout_and_is_zero_when_unknown() {
-        assert_eq!(AudioChannels::Mono.count(), 1);
-        assert_eq!(AudioChannels::Stereo.count(), 2);
-        assert_eq!(AudioChannels::Surround51.count(), 6);
-        assert_eq!(AudioChannels::Surround71.count(), 8);
-        // The one that matters. This used to return 6, which is indistinguishable
-        // from a real 5.1 track and left every caller responsible for checking
-        // the variant first.
-        assert_eq!(
-            AudioChannels::Unknown.count(),
-            0,
-            "an unknown layout must not report a plausible channel count"
-        );
-    }
-
-    #[test]
-    fn sample_rate_hz_values_and_zero_when_unknown() {
-        assert_eq!(SampleRate::S48.hz(), 48000.0);
-        assert_eq!(SampleRate::S96.hz(), 96000.0);
-        assert_eq!(
-            SampleRate::Unknown.hz(),
-            0.0,
-            "an unknown sample rate must not report a plausible 48 kHz"
-        );
-    }
-
-    #[test]
-    fn codec_private_hex_renders_caps_and_handles_empty() {
-        // None / empty → "none" (no hex). The Windows-fps diagnosis only needs
-        // the seq-header prefix, so render it but cap long blobs.
-        assert_eq!(codec_private_hex(None), "none");
-        assert_eq!(codec_private_hex(Some(&[])), "none");
-        // Short blob: full uppercase hex, no suffix. An MPEG-2 seq header starts
-        // 00 00 01 B3 — exactly what a reader greps for in a bug log.
-        assert_eq!(
-            codec_private_hex(Some(&[0x00, 0x00, 0x01, 0xB3])),
-            "000001B3"
-        );
-        // Over the cap: first CODEC_PRIVATE_HEX_CAP bytes + a "..(+NB)" summary.
-        let big = vec![0xABu8; CODEC_PRIVATE_HEX_CAP + 5];
-        let s = codec_private_hex(Some(&big));
-        assert!(s.starts_with(&"AB".repeat(CODEC_PRIVATE_HEX_CAP)), "{s}");
-        assert!(s.ends_with("..(+5B)"), "{s}");
-    }
-
-    #[test]
-    fn frame_record_layout_is_parseable() {
-        // The .opening.bin record framing must round-trip so a future tool can
-        // split the side file back into frames without the disc:
-        // [track:u8][keyframe:u8][pts_ns:i64 LE][len:u32 LE][raw bytes].
-        let data = [0xDEu8, 0xAD, 0xBE, 0xEF];
-        let rec = frame_record(2, -40_000_000, true, &data);
-        assert_eq!(rec.len(), 14 + data.len());
-        assert_eq!(rec[0], 2, "track index");
-        assert_eq!(rec[1], 1, "keyframe flag");
-        assert_eq!(
-            i64::from_le_bytes(rec[2..10].try_into().unwrap()),
-            -40_000_000,
-            "pts_ns survives (signed — opening back-anchor can be negative)"
-        );
-        assert_eq!(
-            u32::from_le_bytes(rec[10..14].try_into().unwrap()),
-            4,
-            "len"
-        );
-        assert_eq!(&rec[14..], &data, "raw frame bytes follow");
-        // A non-keyframe records the flag as 0.
-        let delta = frame_record(0, 0, false, &[]);
-        assert_eq!(delta[1], 0);
-        assert_eq!(u32::from_le_bytes(delta[10..14].try_into().unwrap()), 0);
-    }
-
-    /// The cell row shows the raw category byte (0xNN) beside the decode, and
-    /// the keep/drop verdict. A plain feature cell (0x00) is "keep"; a leading
-    /// secondary-block cell flagged dropped reads "DROP".
-    #[test]
-    fn cell_row_shows_raw_byte_and_verdict() {
-        let plain = crate::ifo::DvdCell {
-            first_sector: 100,
-            last_sector: 199,
-            category: 0x00,
-            duration_secs: 12.5,
-        };
-        let row = dvd_cell_row(0, &plain, false);
-        assert!(row.contains("cat=0x00"), "{row}");
-        assert!(row.contains("block_mode=0"), "{row}");
-        assert!(row.contains("first=100"), "{row}");
-        assert!(row.contains("last=199"), "{row}");
-        assert!(row.contains("dur=12.5s"), "{row}");
-        assert!(row.contains("keep(plain-feature)"), "{row}");
-        assert!(!row.contains("DROP"), "{row}");
-
-        // 0x90 = in-block cell of an angle block (block_mode=2, block_type=1),
-        // shown dropped as a leading secondary piece.
-        let sec = crate::ifo::DvdCell {
-            first_sector: 0,
-            last_sector: 9,
-            category: 0x90,
-            duration_secs: 1.0,
-        };
-        let row = dvd_cell_row(0, &sec, true);
-        assert!(row.contains("cat=0x90"), "{row}");
-        assert!(row.contains("block_mode=2"), "{row}");
-        assert!(row.contains("block_type=1"), "{row}");
-        assert!(row.contains("DROP(leading-secondary-block-piece)"), "{row}");
-    }
-}

src/dirimage/encode.rs

@@ -1,743 +0,0 @@
-//! ECMA-167 / UDF 1.02 descriptor encoder.
-//!
-//! Turns a [`Layout`](super::layout::Layout) — a directory tree with every
-//! ICB, directory-data and file-data block already assigned — into the set of
-//! metadata sectors a real UDF volume would carry. Nothing here touches the
-//! filesystem: it is a pure function from layout to sectors, which is what
-//! makes it testable against the production parser in `udf.rs`.
-//!
-//! What is emitted, in volume order:
-//!
-//! | sector | descriptor |
-//! |---|---|
-//! | 16, 17, 18 | Volume Recognition Sequence — `BEA01`, `NSR02`, `TEA01` (ECMA-167 2/9.1) |
-//! | 32… | Main Volume Descriptor Sequence — PVD, IUVD, PD, LVD, USD, TD |
-//! | 48… | Reserve VDS (byte-identical but for the tag locations) |
-//! | 64, 65 | Logical Volume Integrity Sequence — LVID, TD |
-//! | 256 | Anchor Volume Descriptor Pointer |
-//! | `part_start` + 0, +1 | File Set Descriptor, TD |
-//! | `part_start` + … | File Entries (ICBs) and directory data (FIDs) |
-//! | last sector | Anchor Volume Descriptor Pointer (copy) |
-//!
-//! UDF revision 1.02 with a single Type-1 partition map is deliberate: it is
-//! the DVD-Video profile, it is the shape `read_filesystem` takes when
-//! `num_partition_maps < 2`, and it avoids the UDF 2.50 Metadata Partition
-//! entirely. That also means a synthetic image never exercises the Metadata
-//! Partition path in `udf.rs` (`:946-991`) — see the module docs on `dirimage`.
-
-use super::layout::{DirNode, Layout};
-use crate::error::{Error, Result};
-use std::collections::BTreeMap;
-
-/// Logical block / sector size. Fixed for every optical profile this crate
-/// reads, and the same quantity as [`crate::consts::SECTOR_BYTES`] — aliased
-/// rather than re-declared so the two cannot drift apart. The short name is
-/// kept because it appears in ~25 extent and offset expressions across
-/// `dirimage`, where the longer one would bury the arithmetic.
-pub(super) use crate::consts::SECTOR_BYTES as SECTOR;
-
-/// Descriptor version recorded in every tag. 2 = ECMA-167 2nd edition, which
-/// is what UDF revisions up to and including 2.00 require.
-const DESC_VERSION: u16 = 2;
-
-/// UDF revision recorded in the domain EntityID suffix (1.02, BCD-ish u16).
-const UDF_REVISION: u16 = 0x0102;
-
-/// A fixed recording timestamp, so an image synthesized from the same folder
-/// twice is byte-identical. Real mtimes would make every test golden-file
-/// comparison and every `dir:// -> iso://` re-run differ for no benefit.
-const FIXED_TIME: Timestamp = Timestamp {
-    year: 2000,
-    month: 1,
-    day: 1,
-};
-
-struct Timestamp {
-    year: i16,
-    month: u8,
-    day: u8,
-}
-
-/// The synthesized metadata: absolute LBA → sector contents. Data sectors are
-/// NOT here; they are served from the backing files.
-pub(super) type MetaSectors = BTreeMap<u32, Box<[u8; SECTOR]>>;
-
-/// The descriptor-tag CRC of ECMA-167 7.2.4: polynomial 0x1021, initial value
-/// ZERO, no reflection, no final XOR — the variant catalogued as CRC-16/XMODEM
-/// (check value 0x31C3), NOT CCITT-FALSE, which seeds at 0xFFFF and would make
-/// every descriptor this crate writes fail a conformant driver's validation.
-fn crc16(data: &[u8]) -> u16 {
-    let mut crc: u16 = 0;
-    for &b in data {
-        crc ^= (b as u16) << 8;
-        for _ in 0..8 {
-            crc = if crc & 0x8000 != 0 {
-                (crc << 1) ^ 0x1021
-            } else {
-                crc << 1
-            };
-        }
-    }
-    crc
-}
-
-/// Write an ECMA-167 3/7.2 descriptor tag over `buf[0..16]`.
-///
-/// `tag_loc` is the block number of the sector holding the descriptor —
-/// ABSOLUTE for the volume-space descriptors (AVDP, VDS, LVID) and
-/// PARTITION-RELATIVE for everything inside the partition (FSD, File Entries).
-/// Getting that wrong is the classic reason a hand-built volume mounts nowhere:
-/// a driver that validates the tag location rejects the descriptor outright.
-///
-/// `desc_len` is the descriptor's total length including the tag; the CRC
-/// covers `buf[16..desc_len]`.
-fn finish_tag(buf: &mut [u8], tag_id: u16, tag_loc: u32, desc_len: usize) {
-    buf[0..2].copy_from_slice(&tag_id.to_le_bytes());
-    buf[2..4].copy_from_slice(&DESC_VERSION.to_le_bytes());
-    buf[4] = 0; // checksum, filled below
-    buf[5] = 0; // reserved
-    buf[6..8].copy_from_slice(&0u16.to_le_bytes()); // tag serial number
-    let crc_len = desc_len - 16;
-    let crc = crc16(&buf[16..desc_len]);
-    buf[8..10].copy_from_slice(&crc.to_le_bytes());
-    buf[10..12].copy_from_slice(&(crc_len as u16).to_le_bytes());
-    buf[12..16].copy_from_slice(&tag_loc.to_le_bytes());
-    // ECMA-167 3/7.2.3: sum of bytes 0..16 EXCLUDING byte 4, modulo 256.
-    let sum: u32 = buf[0..16]
-        .iter()
-        .enumerate()
-        .filter(|(i, _)| *i != 4)
-        .map(|(_, b)| *b as u32)
-        .sum();
-    buf[4] = (sum % 256) as u8;
-}
-
-/// ECMA-167 1/7.2.1 charspec: type 0 (CS0) + "OSTA Compressed Unicode".
-fn put_charspec(buf: &mut [u8]) {
-    buf[0] = 0;
-    let id = b"OSTA Compressed Unicode";
-    buf[1..1 + id.len()].copy_from_slice(id);
-}
-
-/// ECMA-167 1/7.4 EntityID: flags byte, 23 identifier bytes, 8 suffix bytes.
-fn put_entity_id(buf: &mut [u8], id: &[u8], suffix: &[u8]) {
-    buf[0] = 0;
-    let n = id.len().min(23);
-    buf[1..1 + n].copy_from_slice(&id[..n]);
-    let m = suffix.len().min(8);
-    buf[24..24 + m].copy_from_slice(&suffix[..m]);
-}
-
-/// The `*OSTA UDF Compliant` domain EntityID suffix: UDF revision, domain
-/// flags (0 = neither hard nor soft write-protected), reserved.
-fn domain_suffix() -> [u8; 8] {
-    let mut s = [0u8; 8];
-    s[0..2].copy_from_slice(&UDF_REVISION.to_le_bytes());
-    s
-}
-
-/// This crate's implementation EntityID suffix: OS class / OS identifier
-/// (0 = undefined, deliberately — the image is not OS-specific) + 6 free bytes.
-fn impl_suffix() -> [u8; 8] {
-    [0u8; 8]
-}
-
-fn put_impl_id(buf: &mut [u8]) {
-    put_entity_id(buf, b"*freemkv", &impl_suffix());
-}
-
-fn put_domain_id(buf: &mut [u8]) {
-    put_entity_id(buf, b"*OSTA UDF Compliant", &domain_suffix());
-}
-
-/// OSTA CS0 d-string: a compression-ID byte, the characters, then the used
-/// length in the FIELD'S LAST byte (ECMA-167 1/7.2.12 + UDF 2.1.3). An
-/// all-zero field is the empty string.
-fn put_dstring(buf: &mut [u8], s: &str) {
-    if s.is_empty() {
-        return;
-    }
-    let encoded = encode_cs0(s);
-    // Leave room for the trailing length byte.
-    let room = buf.len() - 1;
-    let n = encoded.len().min(room);
-    buf[..n].copy_from_slice(&encoded[..n]);
-    buf[buf.len() - 1] = n as u8;
-}
-
-/// OSTA CS0: compression ID 8 (one byte per character) when every character
-/// is ASCII, otherwise compression ID 16 (UTF-16BE).
-///
-/// ASCII rather than Latin-1 for the 8-bit form on purpose: `parse_udf_name`
-/// (`udf.rs:1467`) decodes a compression-8 name with `from_utf8_lossy`, so a
-/// 0x80-0xFF byte — legal CS0 — would come back as U+FFFD. Every character
-/// above 0x7F therefore takes the 16-bit form, which that parser decodes
-/// correctly.
-pub(super) fn encode_cs0(s: &str) -> Vec<u8> {
-    if s.is_ascii() {
-        let mut v = Vec::with_capacity(1 + s.len());
-        v.push(8u8);
-        v.extend_from_slice(s.as_bytes());
-        v
-    } else {
-        let mut v = vec![16u8];
-        for u in s.encode_utf16() {
-            v.extend_from_slice(&u.to_be_bytes());
-        }
-        v
-    }
-}
-
-/// ECMA-167 1/7.3 timestamp, 12 bytes. Type 1 (local time) with a zero
-/// offset, i.e. UTC.
-fn put_timestamp(buf: &mut [u8]) {
-    buf[0..2].copy_from_slice(&0x1000u16.to_le_bytes());
-    buf[2..4].copy_from_slice(&FIXED_TIME.year.to_le_bytes());
-    buf[4] = FIXED_TIME.month;
-    buf[5] = FIXED_TIME.day;
-}
-
-/// ECMA-167 3/7.1 extent_ad: length in BYTES, then location.
-fn put_extent_ad(buf: &mut [u8], len_bytes: u32, lba: u32) {
-    buf[0..4].copy_from_slice(&len_bytes.to_le_bytes());
-    buf[4..8].copy_from_slice(&lba.to_le_bytes());
-}
-
-/// ECMA-167 4/14.14.2 long_ad: length+type, then lb_addr (block, partition
-/// reference), then 6 implementation-use bytes.
-fn put_long_ad(buf: &mut [u8], len_bytes: u32, lba: u32) {
-    buf[0..4].copy_from_slice(&len_bytes.to_le_bytes());
-    buf[4..8].copy_from_slice(&lba.to_le_bytes());
-    buf[8..10].copy_from_slice(&0u16.to_le_bytes()); // partition reference 0
-}
-
-/// ECMA-167 4/14.14.1 short_ad. The top two bits of the length word are the
-/// extent TYPE (0 = recorded and allocated), which is exactly why `udf.rs`
-/// masks with `0x3FFF_FFFF` when it reads one back — the mask is the field
-/// boundary, not a truncation bug.
-fn put_short_ad(buf: &mut [u8], len_bytes: u32, lba: u32) {
-    debug_assert!(len_bytes <= 0x3FFF_FFFF, "AD length must fit 30 bits");
-    buf[0..4].copy_from_slice(&len_bytes.to_le_bytes());
-    buf[4..8].copy_from_slice(&lba.to_le_bytes());
-}
-
-fn blank() -> Box<[u8; SECTOR]> {
-    Box::new([0u8; SECTOR])
-}
-
-// ── Volume-space descriptors ────────────────────────────────────────────────
-
-/// ECMA-167 2/9.1 Volume Structure Descriptor: the three-sector recognition
-/// sequence an OS looks for before it will even consider the volume UDF.
-fn volume_recognition(id: &[u8; 5]) -> Box<[u8; SECTOR]> {
-    let mut s = blank();
-    s[0] = 0; // structure type
-    s[1..6].copy_from_slice(id);
-    s[6] = 1; // structure version
-    s
-}
-
-/// ECMA-167 3/10.1 Primary Volume Descriptor.
-fn primary_volume(volume_id: &str, lba: u32, seq: u32) -> Box<[u8; SECTOR]> {
-    let mut s = blank();
-    s[16..20].copy_from_slice(&seq.to_le_bytes());
-    s[20..24].copy_from_slice(&0u32.to_le_bytes()); // PVD number
-    put_dstring(&mut s[24..56], volume_id);
-    s[56..58].copy_from_slice(&1u16.to_le_bytes()); // volume sequence number
-    s[58..60].copy_from_slice(&1u16.to_le_bytes()); // max volume sequence number
-    s[60..62].copy_from_slice(&2u16.to_le_bytes()); // interchange level
-    s[62..64].copy_from_slice(&2u16.to_le_bytes()); // max interchange level
-    s[64..68].copy_from_slice(&1u32.to_le_bytes()); // character set list
-    s[68..72].copy_from_slice(&1u32.to_le_bytes()); // max character set list
-    // UDF 2.2.2.5: the first 8 characters of the volume set identifier must be
-    // unique. A fixed hex prefix plus the volume id is sufficient here — the
-    // image is single-volume and never joins a real volume set.
-    put_dstring(&mut s[72..200], &format!("46524D4B{volume_id}"));
-    put_charspec(&mut s[200..264]); // descriptor character set
-    put_charspec(&mut s[264..328]); // explanatory character set
-    put_timestamp(&mut s[376..388]);
-    put_impl_id(&mut s[388..420]);
-    finish_tag(&mut s[..], 1, lba, 512);
-    s
-}
-
-/// ECMA-167 3/10.4 + UDF 2.2.7 Implementation Use Volume Descriptor
-/// (`*UDF LV Info`). Not read by `udf.rs`, required by the spec.
-fn impl_use_volume(volume_id: &str, lba: u32, seq: u32) -> Box<[u8; SECTOR]> {
-    let mut s = blank();
-    s[16..20].copy_from_slice(&seq.to_le_bytes());
-    put_entity_id(&mut s[20..52], b"*UDF LV Info", &domain_suffix());
-    put_charspec(&mut s[52..116]); // LVI charset
-    put_dstring(&mut s[116..244], volume_id); // logical volume identifier
-    put_impl_id(&mut s[352..384]);
-    finish_tag(&mut s[..], 4, lba, 512);
-    s
-}
-
-/// ECMA-167 3/10.5 Partition Descriptor — the descriptor `read_filesystem`
-/// takes `partition_start` from (offset 188).
-fn partition(part_start: u32, part_sectors: u32, lba: u32, seq: u32) -> Box<[u8; SECTOR]> {
-    let mut s = blank();
-    s[16..20].copy_from_slice(&seq.to_le_bytes());
-    s[20..22].copy_from_slice(&1u16.to_le_bytes()); // partition flags: allocated
-    s[22..24].copy_from_slice(&0u16.to_le_bytes()); // partition number
-    put_entity_id(&mut s[24..56], b"+NSR02", &[]);
-    // s[56..184] partition contents use = Partition Header Descriptor. All
-    // zero: a read-only partition records no unallocated/freed space tables.
-    s[184..188].copy_from_slice(&1u32.to_le_bytes()); // access type: read only
-    s[188..192].copy_from_slice(&part_start.to_le_bytes());
-    s[192..196].copy_from_slice(&part_sectors.to_le_bytes());
-    put_impl_id(&mut s[196..228]);
-    finish_tag(&mut s[..], 5, lba, 512);
-    s
-}
-
-/// ECMA-167 3/10.6 Logical Volume Descriptor. Carries the FSD long_ad and the
-/// partition map table; `read_filesystem` reads `num_partition_maps` at 268
-/// and takes the single-partition path when it is 1.
-fn logical_volume(
-    volume_id: &str,
-    fsd_lba: u32,
-    integrity_lba: u32,
-    integrity_sectors: u32,
-    lba: u32,
-    seq: u32,
-) -> Box<[u8; SECTOR]> {
-    let mut s = blank();
-    s[16..20].copy_from_slice(&seq.to_le_bytes());
-    put_charspec(&mut s[20..84]);
-    put_dstring(&mut s[84..212], volume_id);
-    s[212..216].copy_from_slice(&(SECTOR as u32).to_le_bytes()); // logical block size
-    put_domain_id(&mut s[216..248]);
-    // Logical volume contents use = long_ad of the File Set Descriptor,
-    // partition-relative. One sector.
-    put_long_ad(&mut s[248..264], SECTOR as u32, fsd_lba);
-    s[264..268].copy_from_slice(&6u32.to_le_bytes()); // map table length
-    s[268..272].copy_from_slice(&1u32.to_le_bytes()); // number of partition maps
-    put_impl_id(&mut s[272..304]);
-    put_extent_ad(
-        &mut s[432..440],
-        integrity_sectors * SECTOR as u32,
-        integrity_lba,
-    );
-    // ECMA-167 3/10.7.2 Type 1 partition map.
-    s[440] = 1; // map type
-    s[441] = 6; // map length
-    s[442..444].copy_from_slice(&1u16.to_le_bytes()); // volume sequence number
-    s[444..446].copy_from_slice(&0u16.to_le_bytes()); // partition number
-    finish_tag(&mut s[..], 6, lba, 446);
-    s
-}
-
-/// ECMA-167 3/10.8 Unallocated Space Descriptor with zero extents — the whole
-/// volume is accounted for by the partition.
-fn unallocated_space(lba: u32, seq: u32) -> Box<[u8; SECTOR]> {
-    let mut s = blank();
-    s[16..20].copy_from_slice(&seq.to_le_bytes());
-    s[20..24].copy_from_slice(&0u32.to_le_bytes());
-    finish_tag(&mut s[..], 7, lba, 24);
-    s
-}
-
-/// ECMA-167 3/10.9 Terminating Descriptor.
-fn terminating(lba: u32) -> Box<[u8; SECTOR]> {
-    let mut s = blank();
-    finish_tag(&mut s[..], 8, lba, 512);
-    s
-}
-
-/// ECMA-167 3/10.10 + UDF 2.2.6 Logical Volume Integrity Descriptor, closed.
-fn integrity(
-    part_sectors: u32,
-    files: u32,
-    dirs: u32,
-    next_uid: u64,
-    lba: u32,
-) -> Box<[u8; SECTOR]> {
-    let mut s = blank();
-    put_timestamp(&mut s[16..28]);
-    s[28..32].copy_from_slice(&1u32.to_le_bytes()); // integrity type: close
-    // s[32..40] next integrity extent: none.
-    s[40..48].copy_from_slice(&next_uid.to_le_bytes()); // logical volume contents use: next unique id
-    s[72..76].copy_from_slice(&1u32.to_le_bytes()); // number of partitions
-    s[76..80].copy_from_slice(&46u32.to_le_bytes()); // length of implementation use
-    s[80..84].copy_from_slice(&0u32.to_le_bytes()); // free space: none (read-only)
-    s[84..88].copy_from_slice(&part_sectors.to_le_bytes()); // size table
-    put_impl_id(&mut s[88..120]);
-    s[120..124].copy_from_slice(&files.to_le_bytes());
-    s[124..128].copy_from_slice(&dirs.to_le_bytes());
-    s[128..130].copy_from_slice(&UDF_REVISION.to_le_bytes()); // min read revision
-    s[130..132].copy_from_slice(&UDF_REVISION.to_le_bytes()); // min write revision
-    s[132..134].copy_from_slice(&UDF_REVISION.to_le_bytes()); // max write revision
-    finish_tag(&mut s[..], 9, lba, 134);
-    s
-}
-
-/// ECMA-167 3/10.2 Anchor Volume Descriptor Pointer. `read_filesystem` reads
-/// the main VDS extent from offsets 16..24 and sweeps it.
-fn anchor(main_lba: u32, reserve_lba: u32, vds_sectors: u32, lba: u32) -> Box<[u8; SECTOR]> {
-    let mut s = blank();
-    put_extent_ad(&mut s[16..24], vds_sectors * SECTOR as u32, main_lba);
-    put_extent_ad(&mut s[24..32], vds_sectors * SECTOR as u32, reserve_lba);
-    finish_tag(&mut s[..], 2, lba, 512);
-    s
-}
-
-/// ECMA-167 4/14.1 File Set Descriptor. `read_filesystem` requires tag 256 at
-/// the first block of the (metadata =) partition and reads the root ICB block
-/// from offset 404.
-fn file_set(volume_id: &str, root_icb: u32, lba: u32) -> Box<[u8; SECTOR]> {
-    let mut s = blank();
-    put_timestamp(&mut s[16..28]);
-    s[28..30].copy_from_slice(&3u16.to_le_bytes()); // interchange level
-    s[30..32].copy_from_slice(&3u16.to_le_bytes()); // max interchange level
-    s[32..36].copy_from_slice(&1u32.to_le_bytes()); // character set list
-    s[36..40].copy_from_slice(&1u32.to_le_bytes()); // max character set list
-    s[40..44].copy_from_slice(&0u32.to_le_bytes()); // file set number
-    s[44..48].copy_from_slice(&0u32.to_le_bytes()); // file set descriptor number
-    put_charspec(&mut s[48..112]);
-    put_dstring(&mut s[112..240], volume_id);
-    put_charspec(&mut s[240..304]);
-    put_dstring(&mut s[304..336], volume_id);
-    put_long_ad(&mut s[400..416], SECTOR as u32, root_icb);
-    put_domain_id(&mut s[416..448]);
-    finish_tag(&mut s[..], 256, lba, 512);
-    s
-}
-
-// ── Partition-space descriptors ─────────────────────────────────────────────
-
-/// UDF permission word: read + execute for owner, group and other. No write
-/// bit anywhere — the volume is read-only.
-const PERM_R_X: u32 = 0x0000_1000 | 0x0000_0400 | 0x0000_0080 | 0x0000_0020 | 0x4 | 0x1;
-
-/// ECMA-167 4/14.9 File Entry (tag 261).
-///
-/// Tag 261 rather than the Extended File Entry (266) real BD-ROMs use: an EFE
-/// requires UDF 2.00+, and this image declares 1.02. `udf.rs` reads both — the
-/// 261 field offsets it uses (l_ea 168, l_ad 172, ADs at 176 + l_ea) are the
-/// ones written here.
-///
-/// `extents` are partition-relative (block, byte-length) pairs, already split
-/// so no single one exceeds the 30-bit AD length field.
-fn file_entry(
-    is_dir: bool,
-    info_len: u64,
-    extents: &[(u32, u32)],
-    link_count: u16,
-    unique_id: u64,
-    lba: u32,
-) -> Result<Box<[u8; SECTOR]>> {
-    let mut s = blank();
-    // ICB tag (ECMA-167 4/14.6) at offset 16.
-    s[16..20].copy_from_slice(&0u32.to_le_bytes()); // prior recorded direct entries
-    s[20..22].copy_from_slice(&4u16.to_le_bytes()); // strategy type 4
-    s[24..26].copy_from_slice(&1u16.to_le_bytes()); // max number of entries
-    s[27] = if is_dir { 4 } else { 5 }; // file type: directory / byte sequence
-    // s[28..34] parent ICB location: not recorded (permitted).
-    // s[34..36] ICB flags: 0 => short allocation descriptors. `udf.rs:601`
-    // reads exactly this word to pick its AD stride.
-    s[34..36].copy_from_slice(&0u16.to_le_bytes());
-    // UDF's sentinel for "not specified" is 0xFFFFFFFF, not 0 — 0 is a real
-    // uid/gid (root). A synthesized image has no meaningful owner, and a driver
-    // that maps these through would otherwise report every file as root-owned.
-    s[36..40].copy_from_slice(&u32::MAX.to_le_bytes()); // uid: not specified
-    s[40..44].copy_from_slice(&u32::MAX.to_le_bytes()); // gid: not specified
-    s[44..48].copy_from_slice(&PERM_R_X.to_le_bytes());
-    s[48..50].copy_from_slice(&link_count.to_le_bytes());
-    s[56..64].copy_from_slice(&info_len.to_le_bytes());
-    let blocks: u64 = extents
-        .iter()
-        .map(|(_, len)| (*len as u64).div_ceil(SECTOR as u64))
-        .sum();
-    s[64..72].copy_from_slice(&blocks.to_le_bytes()); // logical blocks recorded
-    put_timestamp(&mut s[72..84]); // access
-    put_timestamp(&mut s[84..96]); // modification
-    put_timestamp(&mut s[96..108]); // attribute
-    s[108..112].copy_from_slice(&1u32.to_le_bytes()); // checkpoint
-    put_impl_id(&mut s[128..160]);
-    s[160..168].copy_from_slice(&unique_id.to_le_bytes());
-    s[168..172].copy_from_slice(&0u32.to_le_bytes()); // length of EAs
-    let l_ad = extents.len() * 8;
-    // A short AD is 8 bytes and the entry has 2048 - 176 = 1872 bytes for
-    // them, i.e. 234 extents — over 200 GiB at the per-AD ceiling. Beyond
-    // that an Allocation Extent Descriptor chain would be required; refuse
-    // rather than write a truncated list.
-    if 176 + l_ad > SECTOR {
-        return Err(Error::DirImageTooLarge);
-    }
-    s[172..176].copy_from_slice(&(l_ad as u32).to_le_bytes());
-    for (i, (elba, len)) in extents.iter().enumerate() {
-        let off = 176 + i * 8;
-        put_short_ad(&mut s[off..off + 8], *len, *elba);
-    }
-    finish_tag(&mut s[..], 261, lba, 176 + l_ad);
-    Ok(s)
-}
-
-/// ECMA-167 4/14.4 File Identifier Descriptor, appended to `buf`.
-///
-/// FIDs are packed with no inter-descriptor padding beyond the 4-byte
-/// alignment the spec mandates, and they are allowed to span logical blocks —
-/// which is also what `read_directory` (`udf.rs:1312`) assumes: it walks the
-/// directory extent as one flat byte run and STOPS at the first non-257 tag,
-/// so any block-alignment gap would truncate the directory.
-fn push_fid(buf: &mut Vec<u8>, name: &str, icb_lba: u32, is_dir: bool, is_parent: bool) {
-    let start = buf.len();
-    let name_field: Vec<u8> = if is_parent {
-        Vec::new()
-    } else {
-        encode_cs0(name)
-    };
-    let l_fi = name_field.len();
-    let mut fid = vec![0u8; 38];
-    fid[16..18].copy_from_slice(&1u16.to_le_bytes()); // file version number
-    let mut chars = 0u8;
-    if is_dir {
-        chars |= 0x02;
-    }
-    if is_parent {
-        chars |= 0x08;
-    }
-    fid[18] = chars;
-    // The planner refuses any name whose encoding exceeds what this byte can
-    // hold (`layout::MAX_CS0_NAME_BYTES`), so this cannot wrap in practice. The
-    // assert states the invariant where it is relied on rather than trusting a
-    // check three files away; a wrap here would desynchronise the directory.
-    debug_assert!(
-        l_fi <= u8::MAX as usize,
-        "FID name length must fit one byte"
-    );
-    fid[19] = l_fi as u8;
-    put_long_ad(&mut fid[20..36], SECTOR as u32, icb_lba);
-    fid[36..38].copy_from_slice(&0u16.to_le_bytes()); // length of implementation use
-    buf.extend_from_slice(&fid);
-    buf.extend_from_slice(&name_field);
-    let unpadded = buf.len() - start;
-    let padded = unpadded.div_ceil(4) * 4;
-    buf.resize(start + padded, 0);
-    // The tag is written last: its CRC covers the descriptor body, which the
-    // padding is not part of (ECMA-167 4/14.4.9 counts padding outside the
-    // CRC'd length).
-    let tag_loc_placeholder = 0;
-    finish_tag(
-        &mut buf[start..start + unpadded],
-        257,
-        tag_loc_placeholder,
-        unpadded,
-    );
-}
-
-/// Serialize one directory's FID list (parent entry first, then children).
-pub(super) fn dir_fids(dir: &DirNode) -> Vec<u8> {
-    let mut buf = Vec::new();
-    push_fid(&mut buf, "", dir.parent_icb_lba, true, true);
-    for sub in &dir.dirs {
-        push_fid(&mut buf, &sub.name, sub.icb_lba, true, false);
-    }
-    for f in &dir.files {
-        push_fid(&mut buf, &f.name, f.icb_lba, false, false);
-    }
-    buf
-}
-
-/// Patch every FID's tag location to the block it actually lands in. ECMA-167
-/// 3/7.2.2 makes the tag location the block of the descriptor, and a FID that
-/// spans two blocks records the block it STARTS in.
-fn fix_fid_tag_locations(buf: &mut [u8], first_block: u32) {
-    let mut pos = 0usize;
-    while pos + 38 <= buf.len() {
-        let l_fi = buf[pos + 19] as usize;
-        let l_iu = u16::from_le_bytes([buf[pos + 36], buf[pos + 37]]) as usize;
-        let unpadded = 38 + l_iu + l_fi;
-        if pos + unpadded > buf.len() {
-            break;
-        }
-        let block = first_block + (pos / SECTOR) as u32;
-        finish_tag(&mut buf[pos..pos + unpadded], 257, block, unpadded);
-        pos += unpadded.div_ceil(4) * 4;
-    }
-}
-
-// ── Whole-image assembly ────────────────────────────────────────────────────
-
-/// Volume-space block of the Volume Recognition Sequence.
-const VRS_START: u32 = 16;
-/// Volume-space block of the Main Volume Descriptor Sequence.
-pub(super) const MAIN_VDS_START: u32 = 32;
-/// Volume-space block of the Reserve Volume Descriptor Sequence.
-pub(super) const RESERVE_VDS_START: u32 = 48;
-/// Sectors reserved for each VDS. ECMA-167 3/10.2.1 requires an anchor to
-/// record at least 16.
-pub(super) const VDS_SECTORS: u32 = 16;
-/// Volume-space block of the Logical Volume Integrity Sequence.
-pub(super) const LVID_START: u32 = 64;
-/// Sectors reserved for the integrity sequence (LVID + TD).
-pub(super) const LVID_SECTORS: u32 = 2;
-/// The mandatory anchor block (ECMA-167 3/10.2).
-pub(super) const ANCHOR_LBA: u32 = 256;
-/// First block a partition may start at. Everything above is volume space.
-pub(super) const MIN_PART_START: u32 = 320;
-
-/// Emit the six-descriptor Volume Descriptor Sequence at `start`.
-fn write_vds(out: &mut MetaSectors, layout: &Layout, start: u32) {
-    let vid = &layout.volume_id;
-    out.insert(start, primary_volume(vid, start, 1));
-    out.insert(start + 1, impl_use_volume(vid, start + 1, 2));
-    out.insert(
-        start + 2,
-        partition(layout.part_start, layout.part_sectors, start + 2, 3),
-    );
-    out.insert(
-        start + 3,
-        logical_volume(vid, 0, LVID_START, LVID_SECTORS, start + 3, 4),
-    );
-    out.insert(start + 4, unallocated_space(start + 4, 5));
-    out.insert(start + 5, terminating(start + 5));
-}
-
-/// Recursively emit one directory's File Entry and FID list, then its
-/// children's.
-fn write_dir(out: &mut MetaSectors, layout: &Layout, dir: &DirNode) -> Result<()> {
-    let mut fids = dir_fids(dir);
-    fix_fid_tag_locations(&mut fids, dir.data_lba);
-    debug_assert_eq!(fids.len(), dir.data_bytes as usize);
-
-    // A directory's link count is 1 (its own FID in the parent) plus one for
-    // each child directory's parent FID pointing back at it.
-    // The planner caps subdirectory fan-out (`layout::MAX_SUBDIRS`) so this
-    // cannot overflow; saturating rather than wrapping keeps a future change to
-    // that cap from silently producing a wrong count.
-    let link_count = (dir.dirs.len() as u16).saturating_add(1);
-    let fe = file_entry(
-        true,
-        fids.len() as u64,
-        &[(dir.data_lba, fids.len() as u32)],
-        link_count,
-        dir.unique_id,
-        dir.icb_lba,
-    )?;
-    out.insert(layout.part_start + dir.icb_lba, fe);
-
-    for (i, chunk) in fids.chunks(SECTOR).enumerate() {
-        let mut s = blank();
-        s[..chunk.len()].copy_from_slice(chunk);
-        out.insert(layout.part_start + dir.data_lba + i as u32, s);
-    }
-
-    for f in &dir.files {
-        let extents: Vec<(u32, u32)> = f.extents.iter().map(|e| (e.lba, e.bytes)).collect();
-        let fe = file_entry(false, f.size, &extents, 1, f.unique_id, f.icb_lba)?;
-        out.insert(layout.part_start + f.icb_lba, fe);
-    }
-
-    for sub in &dir.dirs {
-        write_dir(out, layout, sub)?;
-    }
-    Ok(())
-}
-
-/// Build every metadata sector of the synthesized volume.
-pub(super) fn encode(layout: &Layout) -> Result<MetaSectors> {
-    let mut out = MetaSectors::new();
-
-    out.insert(VRS_START, volume_recognition(b"BEA01"));
-    out.insert(VRS_START + 1, volume_recognition(b"NSR02"));
-    out.insert(VRS_START + 2, volume_recognition(b"TEA01"));
-
-    write_vds(&mut out, layout, MAIN_VDS_START);
-    write_vds(&mut out, layout, RESERVE_VDS_START);
-
-    out.insert(
-        LVID_START,
-        integrity(
-            layout.part_sectors,
-            layout.file_count,
-            layout.dir_count,
-            layout.next_unique_id,
-            LVID_START,
-        ),
-    );
-    out.insert(LVID_START + 1, terminating(LVID_START + 1));
-
-    let avdp = anchor(MAIN_VDS_START, RESERVE_VDS_START, VDS_SECTORS, ANCHOR_LBA);
-    out.insert(ANCHOR_LBA, avdp);
-    let last = layout.total_sectors - 1;
-    out.insert(
-        last,
-        anchor(MAIN_VDS_START, RESERVE_VDS_START, VDS_SECTORS, last),
-    );
-
-    // Partition block 0 must hold the File Set Descriptor: `read_filesystem`
-    // reads exactly `metadata_start` (== partition start on a single-partition
-    // volume) and rejects the volume outright if the tag there is not 256.
-    out.insert(
-        layout.part_start,
-        file_set(&layout.volume_id, layout.root.icb_lba, 0),
-    );
-    out.insert(layout.part_start + 1, terminating(1));
-
-    write_dir(&mut out, layout, &layout.root)?;
-    Ok(out)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    /// The reference check value for CRC-16/XMODEM — poly 0x1021 seeded at 0,
-    /// which is what ECMA-167 7.2.4 specifies: "123456789" → 0x31C3. Seeding
-    /// at 0xFFFF instead (CCITT-FALSE) yields 0x29B1, and that mutant is
-    /// invisible to `udf.rs`, which never verifies a tag CRC — it would only
-    /// show up as a volume no operating system will mount.
-    #[test]
-    fn crc16_matches_the_ecma167_check_value() {
-        assert_eq!(crc16(b"123456789"), 0x31C3);
-        assert_ne!(crc16(b"123456789"), 0x29B1, "not the 0xFFFF-seeded variant");
-    }
-
-    /// ECMA-167 3/7.2.3: the checksum is the sum of the tag's first 16 bytes
-    /// EXCLUDING the checksum byte itself, modulo 256.
-    #[test]
-    fn tag_checksum_excludes_its_own_byte() {
-        let mut buf = [0u8; 512];
-        buf[16..24].copy_from_slice(&[1, 2, 3, 4, 5, 6, 7, 8]);
-        finish_tag(&mut buf, 261, 0x1234, 512);
-        let sum: u32 = buf[0..16]
-            .iter()
-            .enumerate()
-            .filter(|(i, _)| *i != 4)
-            .map(|(_, b)| *b as u32)
-            .sum();
-        assert_eq!(buf[4] as u32, sum % 256);
-        // And the recorded CRC covers the body, not the tag.
-        let crc = u16::from_le_bytes([buf[8], buf[9]]);
-        assert_eq!(crc, crc16(&buf[16..512]));
-        assert_eq!(u16::from_le_bytes([buf[10], buf[11]]), 496);
-        assert_eq!(
-            u32::from_le_bytes([buf[12], buf[13], buf[14], buf[15]]),
-            0x1234
-        );
-    }
-
-    /// ASCII takes compression ID 8; anything above takes 16 (UTF-16BE),
-    /// because `parse_udf_name` decodes compression-8 bytes as UTF-8.
-    #[test]
-    fn cs0_picks_the_encoding_the_parser_can_decode() {
-        assert_eq!(encode_cs0("AB"), vec![8, b'A', b'B']);
-        let e = encode_cs0("Ä");
-        assert_eq!(e[0], 16);
-        assert_eq!(&e[1..], &[0x00, 0xC4]);
-        assert_eq!(crate::udf::parse_udf_name(&e), "Ä");
-    }
-
-    /// A d-string records its used length in the field's LAST byte, and the
-    /// production parser must read the same string back.
-    #[test]
-    fn dstring_round_trips_through_the_production_parser() {
-        let mut field = [0u8; 32];
-        put_dstring(&mut field, "FREEMKV");
-        assert_eq!(field[31], 8, "compid byte + 7 characters");
-        assert_eq!(crate::udf::parse_dstring_for_test(&field), "FREEMKV");
-    }
-}

src/dirimage/mod.rs

@@ -1,362 +0,0 @@
-//! `dir://` as an image-level SOURCE: a synthetic UDF volume over a folder.
-//!
-//! A user's extracted disc — a DVD `VIDEO_TS/` or a Blu-ray `BDMV/`, typically
-//! a MakeMKV-style backup — has files but no sectors, and everything above the
-//! sector layer in this crate wants sectors: `Disc::scan_image`, `UdfFs`,
-//! `ifo.rs`, `mpls.rs`, `clpi.rs` and the mux all read through a
-//! [`SectorSource`]. [`DirImage`] supplies one.
-//!
-//! The trick is that nothing is emulated. A real, minimal, valid UDF 1.02
-//! volume is synthesized over the folder:
-//!
-//! * **Metadata sectors** (anchors, the volume descriptor sequences, the File
-//!   Set Descriptor, every File Entry, every directory's FID list) are encoded
-//!   into RAM by [`encode`] — a few MiB even for a large Blu-ray.
-//! * **Data sectors** are not materialized at all. Each one maps to a byte
-//!   range of a real file, read on demand.
-//!
-//! So `udf::read_filesystem` parses this image by exactly the same code path it
-//! parses a real disc with, and every consumer above it is unchanged. The cost
-//! is that a single-partition synthetic volume never exercises the UDF 2.50
-//! Metadata Partition path (`udf.rs:946-991`) that every real BD-ROM uses —
-//! this module's tests do not cover that block and must not be read as if they
-//! did.
-//!
-//! What this module deliberately does NOT do:
-//!
-//! * **3D / SSIF** — rejected up front ([`Error::DirImageSsifUnsupported`]).
-//!   An SSIF aliases the same sectors as its base and dependent `.m2ts`; the
-//!   planner allocates disjoint extents, so a 3D folder would produce silently
-//!   wrong output.
-//! * **HD-DVD `HVDVD_TS/`** — no title enumerator constraint is modelled.
-//! * **Encrypted folders** — a folder whose content is still AACS-scrambled is
-//!   rejected by the caller-side probe, not decrypted here.
-
-mod encode;
-mod layout;
-
-use crate::error::{Error, Result};
-#[cfg(target_os = "linux")]
-use crate::io::file_sector_source::linux::drop_window;
-#[cfg(target_os = "macos")]
-use crate::io::file_sector_source::macos::drop_window;
-#[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "windows")))]
-use crate::io::file_sector_source::other::drop_window;
-#[cfg(target_os = "windows")]
-use crate::io::file_sector_source::windows::drop_window;
-use crate::sector::SectorSource;
-use encode::{MetaSectors, SECTOR};
-use std::fs::File;
-use std::io::{Read, Seek, SeekFrom};
-use std::path::{Path, PathBuf};
-
-/// How many host files may be held open at once.
-///
-/// A Blu-ray `BDMV/` can exceed a thousand files while macOS `RLIMIT_NOFILE`
-/// defaults to 256, so "open every file up front" is not available. Reads are
-/// overwhelmingly sequential through one large stream file at a time, so a
-/// small LRU keeps the hit rate near 1 while bounding descriptors.
-const HANDLE_CACHE: usize = 16;
-
-/// One file's bytes at one place in the image.
-#[derive(Debug, Clone)]
-struct DataRange {
-    /// Absolute first block.
-    start_lba: u32,
-    /// Blocks covered (the last one may be partially used, and is zero-padded).
-    sectors: u32,
-    /// Index into [`DirImage::files`].
-    file: usize,
-    /// Byte offset within the file at which this range's bytes begin.
-    offset: u64,
-    /// Byte length of the range.
-    bytes: u64,
-}
-
-/// A file the image reads through.
-#[derive(Debug)]
-struct FileRef {
-    host: PathBuf,
-    disc_path: String,
-    size: u64,
-    /// Host mtime at plan time — see `layout::FileNode::mtime` for why size
-    /// alone is not enough.
-    mtime: Option<std::time::SystemTime>,
-}
-
-/// A synthesized UDF disc image over a host directory.
-///
-/// Owns everything it reads through (`PathBuf`s and its own file handles), so
-/// it is `Send + 'static` and can be moved into `build_iso_pipeline`, which
-/// hands it to `PrefetchedSectorSource`'s producer thread.
-pub struct DirImage {
-    meta: MetaSectors,
-    /// Sorted by `start_lba`, non-overlapping.
-    ranges: Vec<DataRange>,
-    files: Vec<FileRef>,
-    open: Vec<(usize, File)>,
-    total_sectors: u32,
-    volume_id: String,
-    data_bytes: u64,
-}
-
-impl std::fmt::Debug for DirImage {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("DirImage")
-            .field("volume_id", &self.volume_id)
-            .field("total_sectors", &self.total_sectors)
-            .field("files", &self.files.len())
-            .field("meta_sectors", &self.meta.len())
-            .finish()
-    }
-}
-
-impl DirImage {
-    /// Plan and encode an image over `root`.
-    ///
-    /// Every error is decided here, at plan time, where it can name the file
-    /// responsible — the read path is deliberately left with nothing to decide
-    /// except "this file changed underneath me".
-    pub fn open(root: &Path) -> Result<Self> {
-        let plan = layout::plan(root)?;
-        let meta = encode::encode(&plan)?;
-
-        let mut nodes = Vec::new();
-        layout::flatten(&plan.root, &mut nodes);
-
-        let mut files = Vec::with_capacity(nodes.len());
-        let mut ranges = Vec::new();
-        for (idx, node) in nodes.iter().enumerate() {
-            // Carry the plan-time mtime ONLY for files whose CONTENT the plan
-            // read — the DVD IFOs, whose bytes 0xC0/0xC4 decide where every VOB
-            // is placed (`layout::place_video_ts` -> `read_head`).
-            //
-            // For every other file the plan depends on the SIZE alone, and size
-            // is already checked. Comparing mtime on those buys nothing and
-            // costs real false positives: disc backups commonly live on
-            // exFAT/FAT32, which stores local time, so a long rip spanning a
-            // DST transition sees a whole-hour shift on a file nobody touched
-            // and would abort hours in, blaming a change that did not happen.
-            // The multi-gigabyte VOBs are exactly the files a long rip re-opens
-            // after the handle cache evicts them.
-            let content_sensitive = node
-                .disc_path
-                .rsplit('.')
-                .next()
-                .is_some_and(|e| e.eq_ignore_ascii_case("IFO"));
-            files.push(FileRef {
-                host: node.host.clone(),
-                disc_path: node.disc_path.clone(),
-                size: node.size,
-                mtime: content_sensitive.then_some(node.mtime).flatten(),
-            });
-            let mut offset = 0u64;
-            for e in &node.extents {
-                ranges.push(DataRange {
-                    start_lba: plan.part_start + e.lba,
-                    sectors: (e.bytes as u64).div_ceil(SECTOR as u64) as u32,
-                    file: idx,
-                    offset,
-                    bytes: e.bytes as u64,
-                });
-                offset += e.bytes as u64;
-            }
-        }
-        ranges.sort_by_key(|r| r.start_lba);
-        debug_assert!(
-            ranges
-                .windows(2)
-                .all(|w| w[0].start_lba + w[0].sectors <= w[1].start_lba),
-            "planned data ranges must not overlap"
-        );
-
-        let data_bytes = layout::total_data_bytes(&plan.root);
-        tracing::info!(
-            target: "freemkv::dirimage",
-            volume_id = %plan.volume_id,
-            files = files.len(),
-            dirs = plan.dir_count,
-            meta_blocks = layout::metadata_block_count(&plan.root),
-            total_sectors = plan.total_sectors,
-            "synthesized UDF image over directory"
-        );
-
-        Ok(Self {
-            meta,
-            ranges,
-            files,
-            open: Vec::new(),
-            total_sectors: plan.total_sectors,
-            volume_id: plan.volume_id,
-            data_bytes,
-        })
-    }
-
-    /// UDF volume identifier the image declares (the folder's own name).
-    pub fn volume_id(&self) -> &str {
-        &self.volume_id
-    }
-
-    /// Total bytes of real file content the image carries — the folder's size,
-    /// not the image's (which also counts metadata and inter-file gaps).
-    pub fn data_bytes(&self) -> u64 {
-        self.data_bytes
-    }
-
-    /// The range covering `lba`, if any.
-    fn range_at(&self, lba: u32) -> Option<&DataRange> {
-        let i = self.ranges.partition_point(|r| r.start_lba <= lba);
-        let r = self.ranges.get(i.checked_sub(1)?)?;
-        (lba < r.start_lba + r.sectors).then_some(r)
-    }
-
-    /// Borrow an open handle for `file`, opening it (and evicting the
-    /// least-recently-used handle) if necessary.
-    ///
-    /// Opening is also where the plan is revalidated. A folder is not a disc:
-    /// a file can be shortened or replaced between planning and reading, and
-    /// zero-filling the difference would turn "the user deleted something"
-    /// into corrupt output at exit 0. The size is re-checked here, and a
-    /// truncation that happens while the handle is already open is caught by
-    /// the short read in [`Self::fill`].
-    fn handle(&mut self, file: usize) -> Result<&mut File> {
-        if let Some(pos) = self.open.iter().position(|(i, _)| *i == file) {
-            // `open` is ordered most-recently-used first.
-            let entry = self.open.remove(pos);
-            self.open.insert(0, entry);
-            return Ok(&mut self.open[0].1);
-        }
-        let f = File::open(&self.files[file].host).map_err(Error::from)?;
-        let md = f.metadata().map_err(Error::from)?;
-        // Size AND mtime. Size alone is content-blind, and this plan depends on
-        // content: a DVD's VOB placement comes from bytes 0xC0/0xC4 of its IFO,
-        // and an IFO rewritten in place keeps its length because IFOs occupy a
-        // whole number of sectors. The size check would pass while every title
-        // extent pointed at the wrong sectors — corrupt video behind an intact
-        // structure, reported complete at exit 0.
-        //
-        // Only compared when both sides have a timestamp; a platform or
-        // filesystem that reports none simply falls back to the size check
-        // rather than failing every read.
-        let changed_size = md.len() != self.files[file].size;
-        let changed_mtime = match (self.files[file].mtime, md.modified().ok()) {
-            (Some(planned), Some(live)) => planned != live,
-            _ => false,
-        };
-        if changed_size || changed_mtime {
-            return Err(Error::DirImageFileChanged {
-                path: self.files[file].disc_path.clone(),
-            });
-        }
-        if self.open.len() >= HANDLE_CACHE {
-            self.open.pop();
-        }
-        self.open.insert(0, (file, f));
-        Ok(&mut self.open[0].1)
-    }
-
-    /// Fill `out` (a whole number of sectors) from one data range, starting at
-    /// `lba`. `out` is already zeroed, so a file's tail sector comes back
-    /// zero-padded — which is exactly what `file_extents`' `div_ceil(2048)`
-    /// (`udf.rs:816`) makes every consumer expect.
-    fn fill(&mut self, r: &DataRange, lba: u32, out: &mut [u8]) -> Result<()> {
-        let within = (lba - r.start_lba) as u64 * SECTOR as u64;
-        let want = (r.bytes.saturating_sub(within)).min(out.len() as u64) as usize;
-        if want == 0 {
-            return Ok(());
-        }
-        let at = r.offset + within;
-        let file = r.file;
-        let h = self.handle(file)?;
-        h.seek(SeekFrom::Start(at)).map_err(Error::from)?;
-        let res = h.read_exact(&mut out[..want]);
-        if res.is_ok() {
-            // Release the window just read, every time.
-            //
-            // The ISO source accumulates and drops in chunks because it reads
-            // one file linearly, so a running start offset always names the
-            // bytes it has consumed. Reads here jump between files, so there is
-            // no single cursor to accumulate against — an accumulated byte
-            // count paired with one read's offset names 1/Nth of what was
-            // actually consumed and leaves the rest pinned, which is how the
-            // first version of this got it wrong.
-            //
-            // Dropping per read costs one advisory syscall per batch (4-16 MiB),
-            // which is nothing against the read itself, and it is correct
-            // regardless of how reads interleave across files.
-            if let Some((_, fh)) = self.open.iter().find(|(i, _)| *i == file) {
-                drop_window(fh, at, want as u64);
-            }
-        }
-        match res {
-            Ok(()) => Ok(()),
-            // The file shrank while the handle was open. Same verdict as the
-            // size check in `handle`, reached the other way.
-            Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => {
-                Err(Error::DirImageFileChanged {
-                    path: self.files[file].disc_path.clone(),
-                })
-            }
-            Err(e) => Err(Error::from(e)),
-        }
-    }
-}
-
-impl SectorSource for DirImage {
-    fn capacity_sectors(&self) -> u32 {
-        self.total_sectors
-    }
-
-    fn read_sectors(
-        &mut self,
-        lba: u32,
-        count: u16,
-        buf: &mut [u8],
-        _recovery: bool,
-    ) -> Result<usize> {
-        let need = count as usize * SECTOR;
-        if buf.len() < need {
-            return Err(Error::UdfBufferTooSmall);
-        }
-        buf[..need].fill(0);
-        // Walk the request in RUNS, not sector by sector. A mux batch is 8192
-        // sectors and almost always lands entirely inside one stream file's
-        // extent; per-sector seek+read would issue 8192 syscalls for what is
-        // one 16 MiB sequential read.
-        let mut i = 0u32;
-        while i < count as u32 {
-            // Checked: callers saturate their LBAs (`disc/dvd.rs` builds a cell
-            // start as `vob_start_sector.saturating_add(cell.first_sector)`, and
-            // the prefetcher adds an offset the same way), so a crafted IFO can
-            // present a request at the very top of the address space. Wrapping
-            // here would fold `at` back to a LOW sector and hand the muxer a
-            // different file's bytes with nothing reported.
-            let Some(at) = lba.checked_add(i) else {
-                break;
-            };
-            let off = i as usize * SECTOR;
-            if let Some(s) = self.meta.get(&at) {
-                buf[off..off + SECTOR].copy_from_slice(&s[..]);
-                i += 1;
-                continue;
-            }
-            // Metadata blocks all sit below the data floor, so a data range is
-            // never interrupted by one.
-            match self.range_at(at).cloned() {
-                Some(r) => {
-                    let run = (r.start_lba + r.sectors - at).min(count as u32 - i);
-                    let end = off + run as usize * SECTOR;
-                    self.fill(&r, at, &mut buf[off..end])?;
-                    i += run;
-                }
-                // A gap between planned extents. Reads as zeros, exactly as an
-                // unrecorded sector of a real image does.
-                None => i += 1,
-            }
-        }
-        Ok(need)
-    }
-}
-
-#[cfg(test)]
-mod tests;

src/disc/dvd_audio_probe.rs

@@ -1,634 +0,0 @@
-//! Physical AC-3 sub-stream probing for DVD audio routing.
-//!
-//! ## Why this exists (Silence-of-the-Lambs wrong-substream bug)
-//!
-//! A DVD VTS IFO declares its audio streams in a fixed table, and freemkv's
-//! scan assigns each declared stream a `private_stream_1` sub-stream id purely
-//! by per-codec ordinal — the first AC-3 stream becomes `0x80`, the second
-//! `0x81`, and so on (`ifo::assign_audio_sub_stream_ids`). That assumes the
-//! physical sub-stream order on the wire matches the IFO declaration order.
-//!
-//! On some discs it does NOT. The R2 PAL "The Silence of the Lambs" feature
-//! declares ONE AC-3 audio stream the IFO nibble marks as 5.1 (6 channels), but
-//! the physical VOB carries the 5.1 main mix and a 2.0 down-mix on DIFFERENT
-//! `0x8x` sub-stream ids, and the 2.0 is the one that happens to land at the
-//! ordinal `0x80` slot. Routing the declared 5.1 stream to `0x80` by ordinal
-//! therefore muxes the 2.0 down-mix while labelling it 5.1 — the wrong physical
-//! track.
-//!
-//! The robust fix is data-driven and codec/disc agnostic: read each physical
-//! AC-3 sub-stream's REAL channel count from the VOB (the `acmod`/`lfeon` of its
-//! first frame after the `0x0B77` sync) and route each IFO-declared AC-3 stream
-//! to the physical sub-stream whose actual channel count matches the IFO's
-//! declared count — instead of trusting the ordinal. This never re-reads the
-//! disc beyond a bounded head-of-feature probe and degrades to the original
-//! ordinal mapping when the probe yields nothing (unreadable/short VOB).
-
-use crate::disc::Stream;
-use crate::mux::codec::ac3;
-use crate::mux::ps::PsDemuxer;
-use crate::sector::SectorSource;
-use std::collections::BTreeMap;
-
-/// How many 2048-byte sectors of the first feature extent to probe. The head of
-/// a DVD feature opens with logos/warnings whose audio is frequently a thin 2.0
-/// bed on the FIRST sub-stream only — the other physical `0x8x` sub-streams and
-/// the main 5.1 mix do not appear until a sector or two further in. 512 sectors
-/// (1 MiB) was too short: on Greenland it saw ONLY `0x80`, and only its opening
-/// 2.0 frames. 1024 sectors (2 MiB) reliably contains at least one frame of
-/// every physical AC-3 sub-stream AND enough of `0x80` to reach its 5.1 frames.
-/// Still bounded so a live drive is never hammered (see the project "don't
-/// hammer the live drive" rule).
-const PROBE_SECTORS: u16 = 1024;
-
-/// Decode the real per-sub-stream AC-3 channel count from a buffer of decrypted
-/// MPEG-PS (DVD VOB) bytes.
-///
-/// Demuxes `private_stream_1` (0xBD), and for each AC-3 sub-stream id
-/// (`0x80..=0x87`) records the MAXIMUM channel count seen across EVERY decodable
-/// frame in the probe window (`acmod` + `lfeon` at each `0x0B77` sync). Pure and
-/// unit-testable — takes the already-read bytes, never touches the disc.
-///
-/// ## Why the maximum, not the first frame
-///
-/// The first frame of a sub-stream at the head of a feature is NOT
-/// representative. A DVD opens with logos/warnings, and the main `0x80`
-/// sub-stream there frequently carries a thin 2.0 bed before transitioning to
-/// its real 5.1 main mix a fraction of a second later (observed on Greenland:
-/// `0x80`'s first frames are acmod=2 → 2 channels, then it becomes acmod=7+lfe →
-/// 6 channels within the same 2 MiB window). Recording only the FIRST frame read
-/// `0x80=2` and missed the 5.1 entirely, defeating the channel-match routing.
-/// The 5.1 capability of a sub-stream is the *maximum* channel count any of its
-/// frames carries, so we scan them all and keep the max.
-///
-/// Returns a map `sub_id -> max channels`. Sub-streams whose frames are all too
-/// short to carry the BSI bits, or that never appear in the buffer, are absent
-/// from the map.
-pub fn probe_ac3_substream_channels(ps_bytes: &[u8]) -> BTreeMap<u8, u8> {
-    let mut found: BTreeMap<u8, u8> = BTreeMap::new();
-    let mut demux = PsDemuxer::new();
-    let mut packets = demux.feed(ps_bytes);
-    packets.extend(demux.flush());
-    for p in packets {
-        // Only private_stream_1 AC-3 sub-streams (0x80..=0x87).
-        let Some(sub) = p.sub_stream_id else { continue };
-        if !(0x80..=0x87).contains(&sub) {
-            continue;
-        }
-        // The PS demux strips the 4-byte AC-3 sub-header but does not align to a
-        // frame. Walk EVERY 0x0B77 sync in this sub-stream's payload, decode
-        // each frame's channel count, and keep the largest — the sub-stream's
-        // real (main-mix) channel capability. See the doc comment above for why
-        // the first frame alone is unreliable.
-        if let Some(ch) = max_substream_channels(&p.data) {
-            let slot = found.entry(sub).or_insert(0);
-            *slot = (*slot).max(ch);
-        }
-    }
-    found
-}
-
-/// Largest AC-3 channel count over every decodable frame in a single
-/// sub-stream's payload. Returns `None` when no frame carries enough BSI bits.
-///
-/// Each frame is advanced by its real `ac3_frame_size` so a frame's compressed
-/// body (which can contain stray `0x0B77` byte pairs) cannot be mistaken for a
-/// new frame; only when a size is unmappable do we fall back to a +2 byte
-/// rescan to re-lock the next genuine sync.
-fn max_substream_channels(data: &[u8]) -> Option<u8> {
-    let mut best: Option<u8> = None;
-    let mut pos = 0;
-    while pos < data.len() {
-        let Some(rel) = ac3::find_ac3_sync(&data[pos..]) else {
-            break;
-        };
-        let start = pos + rel;
-        let frame = &data[start..];
-        if let Some(ch) = ac3::acmod_channels(frame)
-            && ch > 0
-        {
-            best = Some(best.map_or(ch, |b| b.max(ch)));
-        }
-        // Advance past this frame by its declared size when that is mappable;
-        // otherwise step 2 bytes past the sync and re-scan for the next one.
-        let size = ac3::ac3_frame_size(frame);
-        pos = if (6..=8192).contains(&size) {
-            start + size
-        } else {
-            start + 2
-        };
-    }
-    best
-}
-
-/// Re-route the title's declared AC-3 audio streams onto the physical
-/// sub-stream ids whose REAL channel counts match, using a probed
-/// `sub_id -> channels` map.
-///
-/// For each declared AC-3 audio stream (in IFO order), it picks the physical
-/// `0x8x` sub-stream whose probed channel count equals the stream's declared
-/// channel count, never re-using a sub-stream already claimed by an earlier
-/// stream. The chosen sub-stream's PID (`0xBD00 | sub_id`) is written back onto
-/// the `Stream::Audio` so BOTH mux demux paths (`DiscStream` and the file-backed
-/// highway) route by it.
-///
-/// Conservative — it only ever REASSIGNS among the physical sub-streams the
-/// probe actually saw, and only when a better (exact-channel) match exists than
-/// the stream's current assignment. A stream whose current sub-stream already
-/// matches is left alone; a stream with no matching physical sub-stream keeps
-/// its ordinal assignment. So a normal disc (physical order == IFO order) is a
-/// no-op.
-///
-/// Returns the number of streams whose PID was changed (for diagnostics).
-pub fn remap_audio_pids(streams: &mut [Stream], probed: &BTreeMap<u8, u8>) -> usize {
-    if probed.is_empty() {
-        return 0;
-    }
-    // Sub-streams already claimed by a remapped (or matching) earlier stream,
-    // so two declared streams never collide on one physical sub-stream.
-    let mut claimed: Vec<u8> = Vec::new();
-    let mut changed = 0usize;
-
-    for s in streams.iter_mut() {
-        let Stream::Audio(a) = s else { continue };
-        if a.codec != crate::disc::Codec::Ac3 {
-            continue;
-        }
-        let declared = a.channels.count();
-        // The sub-id this stream currently routes by (low byte of its PID).
-        let current_sub = (a.pid & 0x00FF) as u8;
-
-        // If the stream's current physical sub-stream already matches its
-        // declared channel count, keep it and claim it.
-        if probed.get(&current_sub) == Some(&declared) {
-            claimed.push(current_sub);
-            continue;
-        }
-
-        // Otherwise find an unclaimed physical sub-stream whose REAL channel
-        // count equals the declared count.
-        let pick = probed
-            .iter()
-            .find(|(sub, ch)| **ch == declared && !claimed.contains(*sub))
-            .map(|(sub, _)| *sub);
-
-        if let Some(sub) = pick {
-            let new_pid = 0xBD00 | sub as u16;
-            if new_pid != a.pid {
-                tracing::debug!(
-                    target: "freemkv::scan",
-                    old_pid = a.pid,
-                    new_pid,
-                    declared_channels = declared,
-                    "dvd: re-routed AC-3 audio to physical sub-stream matching channel count"
-                );
-                a.pid = new_pid;
-                changed += 1;
-            }
-            claimed.push(sub);
-        } else {
-            // No physical match — leave the ordinal assignment, but claim its
-            // current sub so later streams don't steal a slot it may still use.
-            claimed.push(current_sub);
-        }
-    }
-    changed
-}
-
-/// Probe the first feature extent of a DVD title through a (decrypted) sector
-/// source and re-route its AC-3 audio PIDs to the physically-correct
-/// sub-streams. A bounded, best-effort scan: any read error or empty probe
-/// leaves the ordinal assignment untouched.
-///
-/// `reader` MUST yield PLAINTEXT VOB bytes (i.e. a `DecryptingSectorSource` on a
-/// CSS disc) — probing scrambled sectors yields no AC-3 syncs and is a safe
-/// no-op. Returns the number of audio streams whose PID changed.
-pub fn probe_and_remap<S: SectorSource + ?Sized>(
-    reader: &mut S,
-    title: &mut crate::disc::DiscTitle,
-) {
-    // Only DVD (MPEG-PS) titles carry private_stream_1 AC-3 sub-streams.
-    if title.content_format != crate::disc::ContentFormat::MpegPs {
-        return;
-    }
-    // Nothing to disambiguate unless there is at least one AC-3 audio stream.
-    let has_ac3 = title
-        .streams
-        .iter()
-        .any(|s| matches!(s, Stream::Audio(a) if a.codec == crate::disc::Codec::Ac3));
-    if !has_ac3 {
-        return;
-    }
-    let Some(ext) = title.extents.first() else {
-        return;
-    };
-    let count: u16 = ext.sector_count.min(PROBE_SECTORS as u32) as u16;
-    if count == 0 {
-        return;
-    }
-    let mut buf = vec![0u8; count as usize * 2048];
-    // `recovery=false`: a single best-effort attempt — the probe must never
-    // stall the mux or hammer a marginal drive. On any error, bail to ordinal.
-    let n = match reader.read_sectors(ext.start_lba, count, &mut buf, false) {
-        Ok(n) => n,
-        Err(_) => return,
-    };
-    buf.truncate(n);
-    let probed = probe_ac3_substream_channels(&buf);
-    crate::diag::dump_dvd_substream_probe(title.playlist_id, &probed);
-    remap_audio_pids(&mut title.streams, &probed);
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::disc::{
-        AudioChannels, AudioStream, Codec, ContentFormat, DiscTitle, Extent, LabelPurpose,
-        SampleRate,
-    };
-    use crate::sector::SectorSource;
-
-    /// Build a single, correctly-SIZED AC-3 frame whose `acmod`/`lfeon` encode a
-    /// known channel count. `byte4` is `fscod=0 | frmsizecod=0`, so
-    /// `ac3_frame_size` reports 128 bytes and the frame is zero-padded to exactly
-    /// that — this lets `max_substream_channels` advance frame-by-frame over a
-    /// multi-frame payload exactly as it does on real VOB data. The BSI bits are
-    /// laid down with a writer so the test never hand-miscomputes the lfeon
-    /// offset, matching `acmod_channels`' reader.
-    fn ac3_frame(acmod: u8, lfeon: bool) -> Vec<u8> {
-        let mut bits: Vec<u8> = Vec::new();
-        let push = |val: u32, n: usize, bits: &mut Vec<u8>| {
-            for i in (0..n).rev() {
-                bits.push(((val >> i) & 1) as u8);
-            }
-        };
-        push(acmod as u32, 3, &mut bits);
-        if (acmod & 0x1) != 0 && acmod != 0x1 {
-            push(0, 2, &mut bits); // cmixlev
-        }
-        if (acmod & 0x4) != 0 {
-            push(0, 2, &mut bits); // surmixlev
-        }
-        if acmod == 0x2 {
-            push(0, 2, &mut bits); // dsurmod
-        }
-        push(lfeon as u32, 1, &mut bits);
-        // Pack the bit vector MSB-first into bytes (byte6 onward).
-        let mut tail = Vec::new();
-        let mut cur = 0u8;
-        for (i, b) in bits.iter().enumerate() {
-            cur = (cur << 1) | b;
-            if i % 8 == 7 {
-                tail.push(cur);
-                cur = 0;
-            }
-        }
-        let rem = bits.len() % 8;
-        if rem != 0 {
-            cur <<= 8 - rem;
-            tail.push(cur);
-        }
-        // AC-3 frame: 0x0B 0x77 crc(2) byte4(fscod=0,frmsizecod=0) bsid<<3 then BSI.
-        let mut frame = vec![0x0B, 0x77, 0x00, 0x00, 0x00, 8u8 << 3];
-        frame.extend_from_slice(&tail);
-        // frmsizecod=0 @ 48kHz → 64 words = 128 bytes. Pad to the real size so
-        // the frame-stepping in max_substream_channels lands on the next sync.
-        frame.resize(128, 0);
-        frame
-    }
-
-    /// Build a minimal `private_stream_1` PES carrying `frames` for `sub_id`,
-    /// each preceded only by the 4-byte AC-3 sub-header at the PES head. Mirrors
-    /// the on-disc layout the PS demux expects: PES start `0x000001BD`, length,
-    /// PES header (no PTS), sub-header `[sub_id, frame_count, ptr_hi, ptr_lo]`,
-    /// then the concatenated AC-3 frames.
-    fn ps_ac3_frames(sub_id: u8, frames: &[Vec<u8>]) -> Vec<u8> {
-        // PES sub-header for AC-3: sub_id + frame_count + 2-byte access ptr.
-        let mut payload = vec![sub_id, frames.len() as u8, 0x00, 0x04];
-        for f in frames {
-            payload.extend_from_slice(f);
-        }
-        // PES packet: start code 00 00 01 BD, length(2), flags(2), hdr_len(0).
-        let pes_payload_len = 3 + payload.len(); // flags(2)+hdrlen(1)+payload
-        let mut pkt = vec![0x00, 0x00, 0x01, 0xBD];
-        pkt.extend_from_slice(&(pes_payload_len as u16).to_be_bytes());
-        pkt.extend_from_slice(&[0x80, 0x00, 0x00]); // no PTS, header_data_len=0
-        pkt.extend_from_slice(&payload);
-        pkt
-    }
-
-    /// Single-frame `private_stream_1` PES — the common case in existing tests.
-    fn ps_ac3(sub_id: u8, acmod: u8, lfeon: bool) -> Vec<u8> {
-        ps_ac3_frames(sub_id, &[ac3_frame(acmod, lfeon)])
-    }
-
-    fn ac3_stream(pid: u16, channels: AudioChannels) -> Stream {
-        Stream::Audio(AudioStream {
-            pid,
-            codec: Codec::Ac3,
-            channels,
-            language: "en".into(),
-            sample_rate: SampleRate::S48,
-            secondary: false,
-            purpose: LabelPurpose::Normal,
-            label: String::new(),
-        })
-    }
-
-    /// The probe decodes the real channel count of each physical sub-stream.
-    /// 0x80 carries a 2.0 frame (acmod=2,no lfe → 2ch); 0x81 carries 5.1
-    /// (acmod=7 + lfe → 6ch).
-    #[test]
-    fn probe_decodes_per_substream_channels() {
-        let mut bytes = ps_ac3(0x80, 2, false);
-        bytes.extend(ps_ac3(0x81, 7, true));
-        let probed = probe_ac3_substream_channels(&bytes);
-        assert_eq!(probed.get(&0x80), Some(&2), "0x80 is the 2.0 down-mix");
-        assert_eq!(probed.get(&0x81), Some(&6), "0x81 is the 5.1 main mix");
-    }
-
-    /// GREENLAND regression — the probe must read each sub-stream's TRUE
-    /// (max-mix) channel count, not be poisoned by an unrepresentative head
-    /// frame, and must NOT cross-contaminate between sub-streams.
-    ///
-    /// Mirrors the real on-disc layout that caused the mis-read: the feature
-    /// head carries `0x80` opening with a 2.0 frame and THEN a 5.1 frame (its
-    /// real main mix), interleaved with `0x81` carrying only 2.0. The old
-    /// first-frame probe read `0x80=2` (the logo bed) and missed the 5.1; the
-    /// max-over-frames probe must report `0x80=6` and `0x81=2`.
-    #[test]
-    fn probe_reads_max_channels_no_cross_contamination() {
-        let mut bytes = Vec::new();
-        // 0x80 opens with a 2.0 frame (the logo bed)...
-        bytes.extend(ps_ac3_frames(0x80, &[ac3_frame(2, false)]));
-        // ...0x81 interleaves a pure-2.0 PES (must NOT bleed 6 into 0x80)...
-        bytes.extend(ps_ac3_frames(
-            0x81,
-            &[ac3_frame(2, false), ac3_frame(2, false)],
-        ));
-        // ...then 0x80 reaches its real 5.1 main mix (acmod=7 + lfe → 6 ch),
-        // with a trailing 2.0 frame in the SAME PES to prove we take the max,
-        // not the last frame.
-        bytes.extend(ps_ac3_frames(
-            0x80,
-            &[ac3_frame(7, true), ac3_frame(2, false)],
-        ));
-
-        let probed = probe_ac3_substream_channels(&bytes);
-        assert_eq!(
-            probed.get(&0x80),
-            Some(&6),
-            "0x80's real 5.1 mix must win over its 2.0 head/tail frames"
-        );
-        assert_eq!(
-            probed.get(&0x81),
-            Some(&2),
-            "0x81 is a pure 2.0 stream — must not absorb 0x80's 6-channel frame"
-        );
-    }
-
-    /// SILENCE-OF-THE-LAMBS regression: the IFO declares ONE 5.1 AC-3 stream and
-    /// the ordinal mapping put it at 0x80, but physically 0x80 is the 2.0
-    /// down-mix and the 5.1 lives at 0x81. After probe+remap the declared 5.1
-    /// stream must route to 0x81 (PID 0xBD81), NOT the ordinal 0x80.
-    #[test]
-    fn remap_routes_declared_51_to_physical_51_substream() {
-        // Physical layout: 0x80 = 2.0, 0x81 = 5.1 (reversed vs ordinal).
-        let mut probed = BTreeMap::new();
-        probed.insert(0x80u8, 2u8);
-        probed.insert(0x81u8, 6u8);
-
-        // Declared: one 5.1 stream, ordinally assigned 0x80 (PID 0xBD80).
-        let mut streams = vec![ac3_stream(0xBD80, AudioChannels::Surround51)];
-        let changed = remap_audio_pids(&mut streams, &probed);
-        assert_eq!(changed, 1, "the one 5.1 stream must be re-routed");
-        let Stream::Audio(a) = &streams[0] else {
-            panic!("audio")
-        };
-        assert_eq!(
-            a.pid, 0xBD81,
-            "declared 5.1 must route to physical 0x81 (the real 5.1), not ordinal 0x80"
-        );
-    }
-
-    /// Conservative no-op: when the physical order already matches the IFO
-    /// order (0x80 = 5.1 as declared), remap changes nothing.
-    #[test]
-    fn remap_noop_when_physical_matches_ordinal() {
-        let mut probed = BTreeMap::new();
-        probed.insert(0x80u8, 6u8); // 0x80 really is the 5.1
-        let mut streams = vec![ac3_stream(0xBD80, AudioChannels::Surround51)];
-        let changed = remap_audio_pids(&mut streams, &probed);
-        assert_eq!(changed, 0, "matching physical order is a no-op");
-        let Stream::Audio(a) = &streams[0] else {
-            panic!()
-        };
-        assert_eq!(a.pid, 0xBD80);
-    }
-
-    /// Two declared streams (5.1 + 2.0) where the physical order is reversed:
-    /// 0x80=2.0, 0x81=5.1. The 5.1 declaration must claim 0x81 and the 2.0
-    /// declaration must claim 0x80 — no collision, both correct.
-    #[test]
-    fn remap_two_streams_no_collision() {
-        let mut probed = BTreeMap::new();
-        probed.insert(0x80u8, 2u8);
-        probed.insert(0x81u8, 6u8);
-        // Declared order: 5.1 first (ordinal 0x80), 2.0 second (ordinal 0x81).
-        let mut streams = vec![
-            ac3_stream(0xBD80, AudioChannels::Surround51),
-            ac3_stream(0xBD81, AudioChannels::Stereo),
-        ];
-        remap_audio_pids(&mut streams, &probed);
-        let pids: Vec<u16> = streams
-            .iter()
-            .filter_map(|s| match s {
-                Stream::Audio(a) => Some(a.pid),
-                _ => None,
-            })
-            .collect();
-        assert_eq!(
-            pids,
-            vec![0xBD81, 0xBD80],
-            "5.1→0x81, 2.0→0x80, no collision"
-        );
-    }
-
-    /// Empty probe (unreadable / scrambled VOB) is a no-op — the ordinal
-    /// assignment survives so behaviour never regresses below today's.
-    #[test]
-    fn remap_empty_probe_is_noop() {
-        let probed = BTreeMap::new();
-        let mut streams = vec![ac3_stream(0xBD80, AudioChannels::Surround51)];
-        let changed = remap_audio_pids(&mut streams, &probed);
-        assert_eq!(changed, 0);
-        let Stream::Audio(a) = &streams[0] else {
-            panic!()
-        };
-        assert_eq!(a.pid, 0xBD80, "no probe data → keep ordinal");
-    }
-
-    /// `max_substream_channels` must locate the sync at its true ABSOLUTE
-    /// position (`pos + rel`) when it is preceded by non-sync bytes, not just
-    /// when the sync sits at offset 0. Regression guard for a hand-checked
-    /// mutation (`+` → `-` at the `pos + rel` offset computation): with `pos`
-    /// starting at 0 and the first sync found 3 bytes in, `pos - rel` would
-    /// underflow a `usize` and panic, or (if it somehow didn't) index the
-    /// wrong start entirely. `pos + rel` is the only computation that is
-    /// always in-bounds, since `rel` is itself bounded by the length of the
-    /// slice searched from `pos`.
-    #[test]
-    fn max_substream_channels_locates_sync_after_leading_non_sync_bytes() {
-        let mut data = vec![0xAA, 0xAA, 0xAA]; // no 0x0B77 pattern in here
-        data.extend(ac3_frame(2, false)); // real 2.0 frame, sync at absolute offset 3
-        assert_eq!(
-            max_substream_channels(&data),
-            Some(2),
-            "must find and decode the frame whose sync is NOT at offset 0"
-        );
-    }
-
-    /// When an AC-3 header's `fscod`/`frmsizecod` is unmappable (reserved
-    /// `fscod == 3`), `max_substream_channels` must fall back to stepping
-    /// `start + 2` bytes past the sync to re-lock onto the next genuine sync,
-    /// and must keep making forward progress doing so (never revisit the same
-    /// sync, which would loop forever, and never jump so far that it skips
-    /// the very next real frame). This lays a bogus-sized header at absolute
-    /// offset 4 (so `start == 4`, `start + 2 == 6`) immediately followed, at
-    /// offset 6, by a real, fully decodable 2.0 frame — the position the
-    /// `+ 2` fallback must land on exactly.
-    #[test]
-    fn max_substream_channels_unmappable_size_steps_forward_by_two() {
-        let mut real = ac3_frame(2, false);
-        // Overwrite the (unchecked) CRC bytes of the real frame — these double
-        // as byte4/byte5 of the bogus header 2 bytes earlier, at absolute
-        // offset 4: byte4 = 0xC0 (fscod=3 reserved -> ac3_frame_size == 0,
-        // unmappable), byte5 = 0xF8 (bsid=31 >= 11 -> acmod_channels == None,
-        // so the bogus header itself never contributes a spurious channel
-        // count).
-        real[2] = 0xC0;
-        real[3] = 0xF8;
-        let mut data = vec![0xAA, 0xAA, 0xAA, 0xAA]; // offsets 0..4, no sync
-        data.push(0x0B); // offset 4: bogus header sync byte 0
-        data.push(0x77); // offset 5: bogus header sync byte 1
-        data.extend(real); // offset 6..: the real frame (also serves as the
-        // bogus header's byte4/byte5 at offsets 8/9)
-        assert_eq!(
-            max_substream_channels(&data),
-            Some(2),
-            "must recover the real frame 2 bytes after the unmappable-size sync, not lose it"
-        );
-    }
-
-    /// Same fallback as above, but with the unmappable-size sync at absolute
-    /// offset 0 (`start == 0`) so that stepping backward instead of forward
-    /// (`start - 2`) would underflow rather than merely land on the wrong
-    /// byte. Also proves the real frame is still found 6 bytes further in,
-    /// confirming forward progress past the bogus header.
-    #[test]
-    fn max_substream_channels_unmappable_size_at_start_steps_forward_not_back() {
-        let mut data = vec![0x0B, 0x77, 0x00, 0x00, 0xC0, 0xF8]; // bogus header, offsets 0..6
-        data.extend(ac3_frame(2, false)); // real 2.0 frame at offset 6
-        assert_eq!(
-            max_substream_channels(&data),
-            Some(2),
-            "must step forward past the bogus header at offset 0 and find the real frame at offset 6"
-        );
-    }
-
-    /// `remap_audio_pids` must read a stream's CURRENT physical sub-stream id
-    /// from the low byte of its PID via `pid & 0x00FF` — not `|` or `^` with
-    /// `0x00FF`, both of which force the low byte to `0xFF` regardless of the
-    /// real PID and so always miss the "already matches" shortcut. That
-    /// matters observably when TWO physical sub-streams share the same probed
-    /// channel count: with a correct read, a stream already sitting on a
-    /// matching sub-stream is left alone (conservative, per the module's
-    /// documented behaviour); with the low byte forced to `0xFF`,
-    /// `probed.get(&0xFF)` is always `None`, so the code falls through to the
-    /// "find any unclaimed match" path and picks the FIRST (lowest-keyed,
-    /// BTreeMap-ordered) matching physical sub-stream instead — which here is
-    /// a *different* sub-stream (0x80) than the one the PID already correctly
-    /// names (0x81), producing a spurious PID change.
-    #[test]
-    fn remap_reads_current_substream_via_and_not_or_or_xor() {
-        let mut probed = BTreeMap::new();
-        probed.insert(0x80u8, 6u8);
-        probed.insert(0x81u8, 6u8); // ambiguous: two physical 6ch sub-streams
-        let mut streams = vec![ac3_stream(0xBD81, AudioChannels::Surround51)];
-        let changed = remap_audio_pids(&mut streams, &probed);
-        assert_eq!(
-            changed, 0,
-            "already sitting on a matching physical sub-stream (0x81) must be left alone"
-        );
-        let Stream::Audio(a) = &streams[0] else {
-            panic!()
-        };
-        assert_eq!(
-            a.pid, 0xBD81,
-            "must not be bumped to the other matching sub-stream (0x80)"
-        );
-    }
-
-    /// A `SectorSource` stub that hands back fixed bytes regardless of the
-    /// requested LBA/count, for exercising `probe_and_remap`'s end-to-end
-    /// wiring (format/AC-3/extent/count guards -> read -> probe -> remap).
-    struct FixedSource {
-        data: Vec<u8>,
-    }
-
-    impl SectorSource for FixedSource {
-        fn read_sectors(
-            &mut self,
-            _lba: u32,
-            _count: u16,
-            buf: &mut [u8],
-            _recovery: bool,
-        ) -> crate::error::Result<usize> {
-            let n = self.data.len().min(buf.len());
-            buf[..n].copy_from_slice(&self.data[..n]);
-            Ok(n)
-        }
-    }
-
-    /// End-to-end `probe_and_remap`: a Silence-of-the-Lambs-shaped MpegPs
-    /// title (one declared 5.1 AC-3 stream ordinally assigned 0x80) whose
-    /// physical VOB bytes carry the 2.0 down-mix on 0x80 and the real 5.1 on
-    /// 0x81. This must reach the `remap_audio_pids` call and re-route the
-    /// stream to 0xBD81. It also, by construction, proves each of the guards
-    /// along the way lets a real, positive case through: the content-format
-    /// check must NOT bail on `MpegPs` (only on non-`MpegPs`), the AC-3
-    /// presence check must NOT bail when AC-3 IS present, and the
-    /// sector-count check must NOT bail when the count is nonzero — any one
-    /// of those inverted would skip the probe entirely and leave the PID at
-    /// its untouched ordinal value (0xBD80), which the assertion below would
-    /// catch.
-    #[test]
-    fn probe_and_remap_reroutes_silence_of_the_lambs_scenario_end_to_end() {
-        let mut bytes = ps_ac3(0x80, 2, false); // physical 0x80 = 2.0 down-mix
-        bytes.extend(ps_ac3(0x81, 7, true)); // physical 0x81 = 5.1 main mix
-        let mut title = DiscTitle {
-            playlist: "00001.ifo".into(),
-            playlist_id: 1,
-            duration_secs: 60.0,
-            size_bytes: bytes.len() as u64,
-            clips: Vec::new(),
-            streams: vec![ac3_stream(0xBD80, AudioChannels::Surround51)],
-            chapters: Vec::new(),
-            extents: vec![Extent {
-                start_lba: 0,
-                sector_count: 2,
-            }],
-            content_format: ContentFormat::MpegPs,
-            codec_privates: vec![None],
-        };
-        let mut source = FixedSource { data: bytes };
-        probe_and_remap(&mut source, &mut title);
-        let Stream::Audio(a) = &title.streams[0] else {
-            panic!("audio")
-        };
-        assert_eq!(
-            a.pid, 0xBD81,
-            "declared 5.1 stream must be re-routed to the physical 5.1 sub-stream 0x81"
-        );
-    }
-}

src/disc/mapfile.rs

@@ -0,0 +1,610 @@
+//! ddrescue-compatible mapfile for tracking rip progress.
+//!
+//! Records which byte ranges of a disc image are good, unreadable,
+//! or not-yet-attempted. Written as plain text so it's greppable,
+//! human-editable, and interoperates with ddrescue's own tools.
+//!
+//! Format:
+//! ```text
+//! # Rescue Logfile. Created by libfreemkv v0.11.21
+//! # Current pos / status / pass / pass_time (ddrescue state machine — we only populate pos)
+//! 0x000000000  ?  1  0
+//! #      pos        size  status
+//! 0x000000000  0x12345678    +
+//! 0x012345678  0x00001000    -
+//! 0x012346678  0x01234500    ?
+//! ```
+//!
+//! Status chars: `?` non-tried · `*` non-trimmed · `/` non-scraped · `-` unreadable · `+` finished.
+//!
+//! The mapfile is flushed to disk at most once per `FLUSH_INTERVAL`
+//! during `record()` calls, plus on explicit `flush()` and on `Drop`.
+//! This bounds atomic-rename RPC rate on networked staging (e.g. NFS)
+//! where per-record persists otherwise serialize the rip pipeline.
+
+use std::io::{self, Write};
+use std::path::{Path, PathBuf};
+use std::time::{Duration, Instant};
+
+/// Minimum interval between mapfile persists. `record()` updates in-memory
+/// state every call but only writes to disk when this interval has elapsed
+/// since the last persist (or when `flush()` is called explicitly, or on
+/// `Drop`). Bounds RPC rate on NFS staging where atomic-rename per record
+/// otherwise dominates throughput. On crash the worst-case progress loss
+/// is one interval's worth of records.
+const FLUSH_INTERVAL: Duration = Duration::from_millis(1000);
+
+/// Status of a byte range in the mapfile. ddrescue-compatible.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SectorStatus {
+    /// `?` — not yet attempted. Initial state for a fresh mapfile.
+    NonTried,
+    /// `*` — fast-pass read failed; edges need trimming.
+    NonTrimmed,
+    /// `/` — trimmed; interior needs sector scrape.
+    NonScraped,
+    /// `-` — drive couldn't read it this session.
+    Unreadable,
+    /// `+` — good.
+    Finished,
+}
+
+impl SectorStatus {
+    pub fn to_char(self) -> char {
+        match self {
+            Self::NonTried => '?',
+            Self::NonTrimmed => '*',
+            Self::NonScraped => '/',
+            Self::Unreadable => '-',
+            Self::Finished => '+',
+        }
+    }
+    pub fn from_char(c: char) -> Option<Self> {
+        Some(match c {
+            '?' => Self::NonTried,
+            '*' => Self::NonTrimmed,
+            '/' => Self::NonScraped,
+            '-' => Self::Unreadable,
+            '+' => Self::Finished,
+            _ => return None,
+        })
+    }
+}
+
+/// One contiguous range of bytes with a status.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MapEntry {
+    pub pos: u64,
+    pub size: u64,
+    pub status: SectorStatus,
+}
+
+/// Summary statistics over all entries.
+///
+/// `bytes_pending` aggregates `NonTried + NonTrimmed + NonScraped` for
+/// back-compat. `bytes_nontried` and `bytes_retryable` (= NonTrimmed +
+/// NonScraped) split that aggregate so UIs can distinguish *unread*
+/// territory (still ahead of Pass 1's read head) from *needs-retry*
+/// territory (Pass 1 already encountered, queued for Pass 2-N).
+#[derive(Debug, Clone, Copy, Default)]
+pub struct MapStats {
+    pub bytes_total: u64,
+    pub bytes_good: u64,
+    pub bytes_unreadable: u64,
+    pub bytes_pending: u64,
+    /// Sectors Pass 1 hasn't reached yet (`NonTried`). Subset of
+    /// `bytes_pending`.
+    pub bytes_nontried: u64,
+    /// Sectors flagged for Pass 2-N retry — `NonTrimmed` (multi-sector
+    /// read failed; needs split) + `NonScraped` (small-block read
+    /// partially recovered; remainder still pending). Subset of
+    /// `bytes_pending`. This is the right signal for a "MAYBE / will
+    /// retry" UI bucket; `bytes_pending` over-counts because it folds
+    /// in `bytes_nontried`.
+    pub bytes_retryable: u64,
+    /// Number of unreadable ranges (for UI display). Computed from
+    /// `ranges_with(&[Unreadable])`.
+    pub num_bad_ranges: u32,
+    /// Largest gap among unreadable ranges in milliseconds. Computed as
+    /// largest range size / bytes_per_sec * 1000. Set by caller (autorip)
+    /// since bytes_per_sec is application-specific.
+    pub main_lost_ms: f64,
+}
+
+/// Time-batched mapfile. `record()` keeps in-memory state up-to-date on
+/// every call; persists to disk at most once per `FLUSH_INTERVAL`.
+/// Explicit `flush()` and `Drop` guarantee state is on disk after a sweep
+/// or patch finishes. On hard crash the worst-case loss is one flush
+/// interval of records — the file's payload bytes are unaffected.
+pub struct Mapfile {
+    path: PathBuf,
+    entries: Vec<MapEntry>,
+    total_size: u64,
+    version: String,
+    /// Incrementally maintained stats — updated on every `record()` call
+    /// so `stats()` is O(1) instead of O(n).
+    stats: MapStats,
+    /// True when in-memory state has changed but `write_to_disk` has not
+    /// yet captured it.
+    dirty: bool,
+    /// Wall-clock timestamp of the last successful `write_to_disk` (or
+    /// the moment the mapfile was constructed, whichever is later).
+    last_flushed: Instant,
+}
+
+impl Mapfile {
+    /// Create a new mapfile with one `NonTried` region covering the whole disc.
+    /// Writes to disk immediately so a resume can pick up even if the caller
+    /// never records anything.
+    pub fn create(path: &Path, total_size: u64, version: &str) -> io::Result<Self> {
+        let mut mf = Self {
+            path: path.to_path_buf(),
+            entries: vec![MapEntry {
+                pos: 0,
+                size: total_size,
+                status: SectorStatus::NonTried,
+            }],
+            total_size,
+            version: version.to_string(),
+            stats: MapStats {
+                bytes_total: total_size,
+                bytes_pending: total_size,
+                bytes_nontried: total_size,
+                ..Default::default()
+            },
+            dirty: false,
+            last_flushed: Instant::now(),
+        };
+        // Eager initial persist so a resume can pick this up even if
+        // `record()` is never called.
+        mf.write_to_disk()?;
+        mf.last_flushed = Instant::now();
+        Ok(mf)
+    }
+
+    /// Load an existing mapfile from disk.
+    pub fn load(path: &Path) -> io::Result<Self> {
+        let text = std::fs::read_to_string(path)?;
+        let mut entries = Vec::new();
+        let mut saw_current_line = false;
+        let mut version = String::from("unknown");
+        for line in text.lines() {
+            let t = line.trim();
+            if t.is_empty() {
+                continue;
+            }
+            if let Some(rest) = t.strip_prefix('#') {
+                let rest = rest.trim();
+                if let Some(v) = rest.strip_prefix("Rescue Logfile. Created by ") {
+                    version = v.to_string();
+                }
+                continue;
+            }
+            // First non-comment line is the "current" state line (pos status [pass] [pass_time]).
+            // We ignore its contents but skip over it.
+            if !saw_current_line {
+                saw_current_line = true;
+                // But if the line looks like an entry (has at least 3 fields starting 0x...),
+                // it's probably actually an entry for a mapfile we wrote without a current line.
+                // Heuristic: current line has status char as 2nd field; entry has size as 2nd field.
+                let fields: Vec<&str> = t.split_whitespace().collect();
+                if fields.len() >= 3 && fields[1].starts_with("0x") {
+                    // It's an entry, not a current line — fall through to entry parse.
+                } else {
+                    continue;
+                }
+            }
+            // Entry: `pos size statuschar`
+            let fields: Vec<&str> = t.split_whitespace().collect();
+            if fields.len() < 3 {
+                continue;
+            }
+            let pos = parse_hex(fields[0])?;
+            let size = parse_hex(fields[1])?;
+            let status = fields[2]
+                .chars()
+                .next()
+                .and_then(SectorStatus::from_char)
+                .ok_or_else(|| {
+                    // 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 });
+        }
+        entries.sort_by_key(|e| e.pos);
+        let total_size = entries.last().map(|e| e.pos + e.size).unwrap_or(0);
+        let stats = Self::compute_stats(&entries, total_size);
+        Ok(Self {
+            path: path.to_path_buf(),
+            entries,
+            total_size,
+            version,
+            stats,
+            dirty: false,
+            last_flushed: Instant::now(),
+        })
+    }
+
+    /// Load if the file exists, otherwise create a fresh mapfile.
+    pub fn open_or_create(path: &Path, total_size: u64, version: &str) -> io::Result<Self> {
+        match Self::load(path) {
+            Ok(mf) => Ok(mf),
+            Err(e) if e.kind() == io::ErrorKind::NotFound => {
+                Self::create(path, total_size, version)
+            }
+            Err(e) => Err(e),
+        }
+    }
+
+    /// Mark a byte range as having the given status. Splits any overlapping
+    /// existing entries, merges with adjacent same-status entries, and flushes
+    /// to disk.
+    pub fn record(&mut self, pos: u64, size: u64, status: SectorStatus) -> io::Result<()> {
+        if size == 0 {
+            return Ok(());
+        }
+        let end = pos.saturating_add(size);
+        let mut new_entries = Vec::with_capacity(self.entries.len() + 2);
+
+        for e in self.entries.drain(..) {
+            let e_end = e.pos + e.size;
+            if e_end <= pos || e.pos >= end {
+                // entirely before or after — keep
+                new_entries.push(e);
+                continue;
+            }
+            // Overlap — keep portions outside [pos, end)
+            if e.pos < pos {
+                new_entries.push(MapEntry {
+                    pos: e.pos,
+                    size: pos - e.pos,
+                    status: e.status,
+                });
+            }
+            if e_end > end {
+                new_entries.push(MapEntry {
+                    pos: end,
+                    size: e_end - end,
+                    status: e.status,
+                });
+            }
+        }
+        new_entries.push(MapEntry { pos, size, status });
+        new_entries.sort_by_key(|e| e.pos);
+
+        // Coalesce adjacent same-status entries.
+        let mut merged: Vec<MapEntry> = Vec::with_capacity(new_entries.len());
+        for e in new_entries {
+            if let Some(last) = merged.last_mut() {
+                if last.pos + last.size == e.pos && last.status == e.status {
+                    last.size += e.size;
+                    continue;
+                }
+            }
+            merged.push(e);
+        }
+
+        // Recompute stats from merged entries. record() is already O(n) due to
+        // drain-and-rebuild, so this is a constant-factor overhead. The critical
+        // win is that stats() is now O(1) — called millions of times in the hot
+        // path during sweep/patch, it just returns the cached value.
+        self.stats = Self::compute_stats(&merged, self.total_size);
+        self.entries = merged;
+        self.dirty = true;
+        if self.last_flushed.elapsed() >= FLUSH_INTERVAL {
+            self.write_to_disk()?;
+            self.dirty = false;
+            self.last_flushed = Instant::now();
+        }
+        Ok(())
+    }
+
+    /// Persist any pending in-memory changes to disk. No-op if clean.
+    /// Callers (sweep/patch finalisation) invoke this after their last
+    /// `record()` to guarantee state is durable before returning.
+    pub fn flush(&mut self) -> io::Result<()> {
+        if self.dirty {
+            self.write_to_disk()?;
+            self.dirty = false;
+            self.last_flushed = Instant::now();
+        }
+        Ok(())
+    }
+
+    pub fn entries(&self) -> &[MapEntry] {
+        &self.entries
+    }
+
+    pub fn total_size(&self) -> u64 {
+        self.total_size
+    }
+
+    /// First range with a given status starting at or after `from`.
+    pub fn next_with(&self, from: u64, status: SectorStatus) -> Option<(u64, u64)> {
+        for e in &self.entries {
+            if e.status != status {
+                continue;
+            }
+            let e_end = e.pos + e.size;
+            if e_end <= from {
+                continue;
+            }
+            let start = e.pos.max(from);
+            return Some((start, e_end - start));
+        }
+        None
+    }
+
+    /// All ranges matching one of the given statuses, in position order.
+    pub fn ranges_with(&self, statuses: &[SectorStatus]) -> Vec<(u64, u64)> {
+        self.entries
+            .iter()
+            .filter(|e| statuses.contains(&e.status))
+            .map(|e| (e.pos, e.size))
+            .collect()
+    }
+
+    pub fn stats(&self) -> MapStats {
+        self.stats
+    }
+
+    fn compute_stats(entries: &[MapEntry], total_size: u64) -> MapStats {
+        let mut s = MapStats {
+            bytes_total: total_size,
+            ..Default::default()
+        };
+        for e in entries {
+            match e.status {
+                SectorStatus::Finished => s.bytes_good += e.size,
+                SectorStatus::Unreadable => s.bytes_unreadable += e.size,
+                SectorStatus::NonTried => {
+                    s.bytes_pending += e.size;
+                    s.bytes_nontried += e.size;
+                }
+                SectorStatus::NonTrimmed | SectorStatus::NonScraped => {
+                    s.bytes_pending += e.size;
+                    s.bytes_retryable += e.size;
+                }
+            }
+        }
+        s
+    }
+
+    fn write_to_disk(&self) -> io::Result<()> {
+        // Write to a tempfile then rename for atomicity. Appending ".tmp"
+        // rather than `with_extension` so we don't clobber the original
+        // extension (which may already be ".mapfile").
+        let tmp = {
+            let mut s = self.path.clone().into_os_string();
+            s.push(".tmp");
+            PathBuf::from(s)
+        };
+        {
+            let file = std::fs::File::create(&tmp)?;
+            let mut w = std::io::BufWriter::new(file);
+            writeln!(w, "# Rescue Logfile. Created by {}", self.version)?;
+            writeln!(w, "# Current pos / status / pass / pass_time")?;
+            writeln!(w, "0x000000000  ?  1  0")?;
+            writeln!(w, "#      pos        size  status")?;
+            for e in &self.entries {
+                writeln!(
+                    w,
+                    "0x{:09x}  0x{:09x}    {}",
+                    e.pos,
+                    e.size,
+                    e.status.to_char()
+                )?;
+            }
+            w.flush()?;
+        }
+        std::fs::rename(&tmp, &self.path)?;
+        Ok(())
+    }
+}
+
+impl Drop for Mapfile {
+    /// Best-effort flush on drop so a sweep / patch that returns early
+    /// (or unwinds) doesn't lose its in-memory state. Errors here are
+    /// swallowed because Drop has no way to surface them; explicit
+    /// `flush()` on the success path gives callers proper error handling.
+    fn drop(&mut self) {
+        let _ = self.flush();
+    }
+}
+
+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(|_| {
+        // 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)]
+mod tests {
+    use super::*;
+
+    fn tmpfile(tag: &str) -> PathBuf {
+        use std::sync::atomic::{AtomicU64, Ordering};
+        static CTR: AtomicU64 = AtomicU64::new(0);
+        let n = CTR.fetch_add(1, Ordering::Relaxed);
+        let name = format!(
+            "libfreemkv-mapfile-test-{}-{}-{}.mapfile",
+            std::process::id(),
+            tag,
+            n
+        );
+        std::env::temp_dir().join(name)
+    }
+
+    #[test]
+    fn create_has_one_nontried_region() {
+        let p = tmpfile("create_has_one_nontried_region");
+        let _ = std::fs::remove_file(&p);
+        let mf = Mapfile::create(&p, 1000, "test").unwrap();
+        assert_eq!(mf.entries().len(), 1);
+        assert_eq!(mf.entries()[0].pos, 0);
+        assert_eq!(mf.entries()[0].size, 1000);
+        assert_eq!(mf.entries()[0].status, SectorStatus::NonTried);
+        let _ = std::fs::remove_file(&p);
+    }
+
+    #[test]
+    fn record_splits_overlap() {
+        let p = tmpfile("record_splits_overlap");
+        let _ = std::fs::remove_file(&p);
+        let mut mf = Mapfile::create(&p, 1000, "test").unwrap();
+        mf.record(200, 100, SectorStatus::Finished).unwrap();
+        let es = mf.entries();
+        assert_eq!(es.len(), 3);
+        assert_eq!(
+            (es[0].pos, es[0].size, es[0].status),
+            (0, 200, SectorStatus::NonTried)
+        );
+        assert_eq!(
+            (es[1].pos, es[1].size, es[1].status),
+            (200, 100, SectorStatus::Finished)
+        );
+        assert_eq!(
+            (es[2].pos, es[2].size, es[2].status),
+            (300, 700, SectorStatus::NonTried)
+        );
+        let _ = std::fs::remove_file(&p);
+    }
+
+    #[test]
+    fn record_coalesces_adjacent_same_status() {
+        let p = tmpfile("record_coalesces_adjacent_same_status");
+        let _ = std::fs::remove_file(&p);
+        let mut mf = Mapfile::create(&p, 1000, "test").unwrap();
+        mf.record(100, 100, SectorStatus::Finished).unwrap();
+        mf.record(200, 100, SectorStatus::Finished).unwrap();
+        // Entries: [0..100 NonTried, 100..300 Finished (merged), 300..1000 NonTried]
+        let es = mf.entries();
+        assert_eq!(es.len(), 3);
+        assert_eq!(
+            (es[1].pos, es[1].size, es[1].status),
+            (100, 200, SectorStatus::Finished)
+        );
+        let _ = std::fs::remove_file(&p);
+    }
+
+    #[test]
+    fn record_replaces_existing_status() {
+        let p = tmpfile("record_replaces_existing_status");
+        let _ = std::fs::remove_file(&p);
+        let mut mf = Mapfile::create(&p, 1000, "test").unwrap();
+        mf.record(200, 100, SectorStatus::Unreadable).unwrap();
+        mf.record(200, 100, SectorStatus::Finished).unwrap();
+        let es = mf.entries();
+        // The overwrite should result in all finished at 200..300, NonTried elsewhere — 3 entries.
+        assert_eq!(es.len(), 3);
+        assert_eq!(es[1].status, SectorStatus::Finished);
+        let _ = std::fs::remove_file(&p);
+    }
+
+    #[test]
+    fn round_trip_load() {
+        let p = tmpfile("round_trip_load");
+        let _ = std::fs::remove_file(&p);
+        let mut mf = Mapfile::create(&p, 1000, "test").unwrap();
+        mf.record(100, 200, SectorStatus::Finished).unwrap();
+        mf.record(500, 100, SectorStatus::Unreadable).unwrap();
+        // record() batches; explicit flush before reading back from disk.
+        mf.flush().unwrap();
+        let loaded = Mapfile::load(&p).unwrap();
+        assert_eq!(loaded.entries(), mf.entries());
+        let _ = std::fs::remove_file(&p);
+    }
+
+    #[test]
+    fn stats_sum_correctly() {
+        let p = tmpfile("stats_sum_correctly");
+        let _ = std::fs::remove_file(&p);
+        let mut mf = Mapfile::create(&p, 1000, "test").unwrap();
+        mf.record(0, 400, SectorStatus::Finished).unwrap();
+        mf.record(400, 100, SectorStatus::Unreadable).unwrap();
+        let s = mf.stats();
+        assert_eq!(s.bytes_good, 400);
+        assert_eq!(s.bytes_unreadable, 100);
+        assert_eq!(s.bytes_pending, 500);
+        assert_eq!(s.bytes_total, 1000);
+        let _ = std::fs::remove_file(&p);
+    }
+
+    #[test]
+    fn ranges_with_filters() {
+        let p = tmpfile("ranges_with_filters");
+        let _ = std::fs::remove_file(&p);
+        let mut mf = Mapfile::create(&p, 1000, "test").unwrap();
+        mf.record(100, 50, SectorStatus::Unreadable).unwrap();
+        mf.record(300, 50, SectorStatus::Unreadable).unwrap();
+        let bad = mf.ranges_with(&[SectorStatus::Unreadable]);
+        assert_eq!(bad, vec![(100, 50), (300, 50)]);
+        let _ = std::fs::remove_file(&p);
+    }
+
+    #[test]
+    fn stats_consistent_after_overlapping_records() {
+        let p = tmpfile("stats_consistent_after_overlapping");
+        let _ = std::fs::remove_file(&p);
+        let mut mf = Mapfile::create(&p, 1000, "test").unwrap();
+        // Record some finished, some unreadable, some nontrimmed
+        mf.record(0, 300, SectorStatus::Finished).unwrap();
+        mf.record(300, 200, SectorStatus::NonTrimmed).unwrap();
+        mf.record(500, 100, SectorStatus::Unreadable).unwrap();
+        mf.record(600, 400, SectorStatus::Finished).unwrap();
+
+        // Final entries: [0..300 Finished, 300..500 NonTrimmed, 500..600 Unreadable, 600..1000 Finished]
+        let s = mf.stats();
+        assert_eq!(s.bytes_good, 700); // 300 + 400
+        assert_eq!(s.bytes_unreadable, 100); // 100
+        assert_eq!(s.bytes_pending, 200); // NonTrimmed only (NonTried=0)
+        assert_eq!(s.bytes_nontried, 0);
+        assert_eq!(s.bytes_retryable, 200); // NonTrimmed
+        assert_eq!(s.bytes_total, 1000);
+
+        // Overwrite a NonTrimmed range with Finished
+        mf.record(300, 100, SectorStatus::Finished).unwrap();
+        // Entries: [0..400 Finished, 400..500 NonTrimmed, 500..600 Unreadable, 600..1000 Finished]
+        let s2 = mf.stats();
+        assert_eq!(s2.bytes_good, 800); // 400 + 400
+        assert_eq!(s2.bytes_unreadable, 100);
+        assert_eq!(s2.bytes_pending, 100); // NonTrimmed only
+        assert_eq!(s2.bytes_retryable, 100);
+
+        let _ = std::fs::remove_file(&p);
+    }
+
+    #[test]
+    fn stats_consistent_after_split_record() {
+        let p = tmpfile("stats_consistent_after_split");
+        let _ = std::fs::remove_file(&p);
+        let mut mf = Mapfile::create(&p, 1000, "test").unwrap();
+        // Mark middle as NonTrimmed
+        mf.record(200, 400, SectorStatus::NonTrimmed).unwrap();
+        // Entries: [0..200 NonTried, 200..600 NonTrimmed, 600..1000 NonTried]
+        let s = mf.stats();
+        assert_eq!(s.bytes_pending, 1000); // NonTried(600) + NonTrimmed(400)
+        assert_eq!(s.bytes_retryable, 400); // NonTrimmed only
+        assert_eq!(s.bytes_nontried, 600); // 200 + 400
+
+        // Overwrite the NonTrimmed with Finished (splitting the remaining NonTried)
+        mf.record(200, 400, SectorStatus::Finished).unwrap();
+        // Entries: [0..200 NonTried, 200..600 Finished, 600..1000 NonTried]
+        let s2 = mf.stats();
+        assert_eq!(s2.bytes_good, 400);
+        assert_eq!(s2.bytes_pending, 600); // NonTried(200 + 400)
+        assert_eq!(s2.bytes_nontried, 600);
+        assert_eq!(s2.bytes_retryable, 0);
+
+        let _ = std::fs::remove_file(&p);
+    }
+}

src/disc/sweep.rs

@@ -0,0 +1,239 @@
+//! `Disc::sweep`'s consumer-side `Sink<WorkItem>`.
+//!
+//! Background: the original sweep loop runs strictly serialised —
+//! SCSI read → decrypt → seek + write → mapfile.record → next iter.
+//! On a healthy disc the SCSI read costs ~5-12 ms per 64 KB batch and
+//! the post-read work (decrypt 1-3 ms + file write + mapfile fsync
+//! 5-15 ms) adds another batch's worth of latency. The drive idles
+//! during the post-read work; throughput tops out at the *sum* of
+//! both costs.
+//!
+//! 0.17.11 introduced a bespoke producer/consumer split (the now-
+//! removed `disc/sweep_pipeline.rs`) to overlap the two stages. 0.18
+//! collapses that split — together with the analogous splits patch
+//! and mux need — onto the generic [`crate::io::Pipeline`] +
+//! [`crate::io::Sink`] primitive. This module is the sweep-specific
+//! `Sink` impl; the producer-side state machine (read_error context,
+//! decrypt, set_speed, halt) stays in `Disc::sweep` in `disc/mod.rs`.
+//!
+//! Correctness invariants preserved (same as 0.17.11):
+//! - Mapfile is single-writer (consumer-only). No locking.
+//! - All `read_error::ReadCtx` state stays on the producer thread.
+//! - `set_speed` calls happen on the producer thread (same thread that
+//!   owns the `SectorSource`). No new SCSI concurrency.
+//! - Per-iteration ordering of file-write → mapfile-record is kept
+//!   intact in the consumer (write before record), so the on-disk
+//!   invariant "mapfile only marks Finished what the file has
+//!   received" survives a crash mid-pass.
+//! - The BU40N+Initio bridge wedge concern is unchanged: only one
+//!   SCSI command in flight at a time, error-path timing identical,
+//!   no new retry logic.
+
+use std::io::{Seek, SeekFrom, Write};
+use std::sync::mpsc::{Receiver, SyncSender, sync_channel};
+
+use crate::error::Error;
+use crate::io::{Flow, Sink};
+
+use super::mapfile::{MapStats, Mapfile, SectorStatus};
+
+/// Reusable zero buffer for SkipFill / GapFill / BisectBad. 64 KB
+/// matches the existing zero_gap chunk size used by the pre-split
+/// sweep loop.
+const ZERO_CHUNK: usize = 65 * 1024;
+
+/// Producer → Consumer messages. The consumer applies these in FIFO
+/// order; ordering of file writes and mapfile records across items is
+/// preserved.
+pub(super) enum WorkItem {
+    /// Successful batch read. Producer has already decrypted `buf` if
+    /// `opts.decrypt` was set. Consumer writes `buf` at `pos` and
+    /// records the range as `Finished`.
+    Good { pos: u64, buf: Vec<u8> },
+
+    /// Bisect inner-loop good single sector (already decrypted by the
+    /// producer). 2048 bytes.
+    BisectGood { pos: u64, buf: Box<[u8; 2048]> },
+
+    /// Bisect inner-loop bad single sector. Consumer writes 2048
+    /// zeros at `pos` and records the sector as `NonTrimmed`.
+    BisectBad { pos: u64 },
+
+    /// Whole-batch zero-fill (failed batch on `SkipBlock`, or the
+    /// failed batch portion of `JumpAhead`). Consumer streams zeros
+    /// across `[pos, pos+len)` and records the range as `NonTrimmed`.
+    SkipFill { pos: u64, len: u64 },
+
+    /// Gap fill following a `JumpAhead`. Same effect as `SkipFill`;
+    /// distinguished only so future logging / instrumentation can
+    /// tell them apart without parsing a flag.
+    GapFill { pos: u64, len: u64 },
+
+    /// Producer wants the latest mapfile stats for the progress
+    /// callback. Consumer responds on `prog_tx` with a fresh
+    /// [`ProgressSnapshot`]. Best-effort: if the producer hasn't
+    /// drained the previous snapshot, the new one is silently
+    /// dropped — the producer's local cache stays current enough.
+    StatsRequest,
+}
+
+/// Snapshot the consumer sends back to the producer for the progress
+/// callback.
+pub(super) struct ProgressSnapshot {
+    pub stats: MapStats,
+    pub bad_ranges: Vec<(u64, u64)>,
+}
+
+/// Final summary returned by the consumer thread on shutdown — what
+/// `SweepSink::close` produces, surfaced to the producer via
+/// `Pipeline::finish`.
+pub(super) struct ConsumerSummary {
+    pub stats: MapStats,
+}
+
+/// Drain any pending progress snapshots from the consumer. Returns
+/// the most recent one, if any. The producer caches it and uses it
+/// for subsequent progress callbacks until a fresh one arrives.
+pub(super) fn try_recv_progress(rx: &Receiver<ProgressSnapshot>) -> Option<ProgressSnapshot> {
+    let mut latest = None;
+    while let Ok(snap) = rx.try_recv() {
+        latest = Some(snap);
+    }
+    latest
+}
+
+/// `Sink<WorkItem>` for sweep. Owns the writeback file + mapfile +
+/// progress back-channel. `apply` carries the file-write +
+/// mapfile.record per item; `close` drains the writeback pipeline,
+/// fsyncs the ISO, and flushes the mapfile.
+pub(super) struct SweepSink {
+    file: crate::io::WritebackFile,
+    map: Mapfile,
+    /// `sync_all`-on-failure-is-an-error iff the output is a regular
+    /// file. `/dev/null` and pipes always fail `sync_all`; that's not
+    /// a real error.
+    is_regular: bool,
+    /// Back-channel for `StatsRequest` responses. The producer caches
+    /// the latest snapshot and uses it for the progress callback;
+    /// dropped sends on a full channel are by design.
+    prog_tx: SyncSender<ProgressSnapshot>,
+    /// Reusable zero buffer for SkipFill / GapFill / BisectBad. Held
+    /// in the sink so each apply call doesn't reallocate.
+    zero: Box<[u8; ZERO_CHUNK]>,
+}
+
+impl SweepSink {
+    /// Construct a new `SweepSink` plus the matching progress
+    /// receiver. Channel depth on the back-channel is `1` — the
+    /// producer's cache is the source of truth between snapshots.
+    pub(super) fn new(
+        file: crate::io::WritebackFile,
+        map: Mapfile,
+        is_regular: bool,
+    ) -> (Self, Receiver<ProgressSnapshot>) {
+        let (prog_tx, prog_rx) = sync_channel::<ProgressSnapshot>(1);
+        let sink = SweepSink {
+            file,
+            map,
+            is_regular,
+            prog_tx,
+            zero: Box::new([0u8; ZERO_CHUNK]),
+        };
+        (sink, prog_rx)
+    }
+}
+
+impl Sink<WorkItem> for SweepSink {
+    type Output = ConsumerSummary;
+
+    fn apply(&mut self, item: WorkItem) -> Result<Flow, Error> {
+        match item {
+            WorkItem::Good { pos, buf } => {
+                // Decrypt is on the producer; consumer assumes plaintext.
+                let len = buf.len() as u64;
+                self.file
+                    .seek(SeekFrom::Start(pos))
+                    .map_err(|e| Error::IoError { source: e })?;
+                self.file
+                    .write_all(&buf)
+                    .map_err(|e| Error::IoError { source: e })?;
+                self.map
+                    .record(pos, len, SectorStatus::Finished)
+                    .map_err(|e| Error::IoError { source: e })?;
+            }
+            WorkItem::BisectGood { pos, buf } => {
+                self.file
+                    .seek(SeekFrom::Start(pos))
+                    .map_err(|e| Error::IoError { source: e })?;
+                self.file
+                    .write_all(&buf[..])
+                    .map_err(|e| Error::IoError { source: e })?;
+                self.map
+                    .record(pos, 2048, SectorStatus::Finished)
+                    .map_err(|e| Error::IoError { source: e })?;
+            }
+            WorkItem::BisectBad { pos } => {
+                self.file
+                    .seek(SeekFrom::Start(pos))
+                    .map_err(|e| Error::IoError { source: e })?;
+                self.file
+                    .write_all(&self.zero[..2048])
+                    .map_err(|e| Error::IoError { source: e })?;
+                self.map
+                    .record(pos, 2048, SectorStatus::NonTrimmed)
+                    .map_err(|e| Error::IoError { source: e })?;
+            }
+            WorkItem::SkipFill { pos, len } | WorkItem::GapFill { pos, len } => {
+                self.file
+                    .seek(SeekFrom::Start(pos))
+                    .map_err(|e| Error::IoError { source: e })?;
+                // Subsequent writes are sequential; `WritebackFile`'s
+                // seek-elision keeps them on the writeback pipeline path.
+                let mut filled = 0u64;
+                while filled < len {
+                    let chunk = (len - filled).min(self.zero.len() as u64) as usize;
+                    self.file
+                        .write_all(&self.zero[..chunk])
+                        .map_err(|e| Error::IoError { source: e })?;
+                    filled += chunk as u64;
+                }
+                self.map
+                    .record(pos, len, SectorStatus::NonTrimmed)
+                    .map_err(|e| Error::IoError { source: e })?;
+            }
+            WorkItem::StatsRequest => {
+                let stats = self.map.stats();
+                let bad_ranges = self.map.ranges_with(&[
+                    SectorStatus::NonTrimmed,
+                    SectorStatus::Unreadable,
+                    SectorStatus::NonScraped,
+                    SectorStatus::NonTried,
+                ]);
+                // Best-effort: drop on backpressure; producer's cache
+                // stays current enough.
+                let _ = self
+                    .prog_tx
+                    .try_send(ProgressSnapshot { stats, bad_ranges });
+            }
+        }
+        Ok(Flow::Continue)
+    }
+
+    fn close(mut self) -> Result<Self::Output, Error> {
+        // Drain the writeback pipeline + fsync the ISO, then persist
+        // any pending mapfile state. Same finalisation order as the
+        // pre-Pipeline consumer loop.
+        if let Err(e) = self.file.sync_all() {
+            if self.is_regular {
+                return Err(Error::IoError { source: e });
+            }
+            // Non-regular outputs (/dev/null, pipes) always fail
+            // sync_all; that's not a real error.
+        }
+        self.map.flush().map_err(|e| Error::IoError { source: e })?;
+
+        Ok(ConsumerSummary {
+            stats: self.map.stats(),
+        })
+    }
+}

src/drive/capture.rs

@@ -25,14 +25,8 @@ pub struct DriveCapture {
 /// A single GET CONFIGURATION feature response from the drive.
 #[derive(Debug, Clone)]
 pub struct CapturedFeature {
-    /// MMC-6 GET CONFIGURATION feature code (e.g. `0x010D` = AACS).
     pub code: u16,
-    /// Static human-readable label from the internal `FEATURES` table —
-    /// not a device-reported string.
     pub name: &'static str,
-    /// Raw feature-descriptor payload bytes, with the 8-byte GET
-    /// CONFIGURATION header stripped (i.e. `buf[8..]`). Unlike
-    /// [`DriveCapture::gc_010c`], which retains the full header.
     pub data: Vec<u8>,
 }
 
@@ -120,77 +114,3 @@ pub fn mask_bytes(data: &[u8]) -> Vec<u8> {
         })
         .collect()
 }
-
-#[cfg(test)]
-mod tests {
-    //! Privacy-masking + capture-orchestration tests.
-    //!
-    //! `mask_string` / `mask_bytes` redact identifying characters before
-    //! a drive capture leaves the machine: every ASCII letter → 'A',
-    //! every ASCII digit → '0', everything else (punctuation, spaces,
-    //! control bytes, non-ASCII) is preserved verbatim so structural
-    //! framing (offsets, separators) survives for diffing.
-    use super::*;
-
-    #[test]
-    fn mask_string_letters_become_a_digits_become_zero() {
-        // Mixed case letters all collapse to 'A'; digits to '0'.
-        assert_eq!(mask_string("HL-DT-ST"), "AA-AA-AA");
-        assert_eq!(mask_string("BU40N"), "AA00A");
-    }
-
-    #[test]
-    fn mask_string_preserves_non_alnum_punctuation_and_space() {
-        // Separators and spaces must be preserved so the masked output
-        // keeps the same shape as the original (the whole point of a
-        // structure-preserving redaction).
-        assert_eq!(mask_string("1.04"), "0.00");
-        assert_eq!(mask_string("a b-c.d_e"), "A A-A.A_A");
-    }
-
-    #[test]
-    fn mask_string_preserves_non_ascii_chars() {
-        // is_ascii_alphabetic/is_ascii_digit are false for non-ASCII, so
-        // multibyte chars pass through unchanged (no mojibake, no panic).
-        // 'c','a','f' are ASCII letters → 'A'; 'é' is non-ASCII →
-        // preserved; '9' → '0'.
-        assert_eq!(mask_string("café9"), "AAAé0");
-    }
-
-    #[test]
-    fn mask_bytes_matches_string_masking_for_ascii() {
-        // mask_bytes is the byte-wise analogue: letters→b'A', digits→b'0'.
-        assert_eq!(mask_bytes(b"HL-DT-ST"), b"AA-AA-AA".to_vec());
-        assert_eq!(mask_bytes(b"1.04"), b"0.00".to_vec());
-    }
-
-    #[test]
-    fn mask_bytes_preserves_non_alnum_and_high_bytes() {
-        // Control bytes (0x00), high bytes (0xFF), and punctuation are
-        // not ASCII alnum and must survive verbatim — INQUIRY payloads
-        // are space-padded binary and the framing must be diffable.
-        let input = [0x00u8, b'A', 0x20, b'7', 0xFF, b'-'];
-        assert_eq!(mask_bytes(&input), vec![0x00, b'A', 0x20, b'0', 0xFF, b'-']);
-    }
-
-    #[test]
-    fn feature_table_has_no_duplicate_codes() {
-        // capture_drive_data iterates FEATURES once per code; a duplicate
-        // code would silently capture the same feature twice (and bloat
-        // the report). Each MMC-6 feature code must be unique.
-        let mut seen = std::collections::HashSet::new();
-        for &(code, _name) in FEATURES {
-            assert!(seen.insert(code), "duplicate feature code {code:#06x}");
-        }
-    }
-
-    #[test]
-    fn feature_table_includes_aacs_010d() {
-        // AACS (0x010D) is the feature that gates UHD decryption capture;
-        // it must be in the table or AACS drives capture incompletely.
-        assert!(
-            FEATURES.iter().any(|&(c, _)| c == 0x010D),
-            "AACS feature 0x010D must be captured"
-        );
-    }
-}

src/drive/linux.rs

@@ -1,111 +1,61 @@
 //! Linux drive discovery and device resolution.
 
-use crate::drive::DeviceResolution;
 use crate::error::{Error, Result};
 use crate::identity::DriveId;
 
-/// SCSI peripheral device type 5 = MMC / optical (CD/DVD/BD), held in the
-/// low 5 bits of INQUIRY byte 0 (the high 3 bits are the peripheral
-/// qualifier, masked off here).
-const SCSI_PERIPHERAL_TYPE_OPTICAL: u8 = 0x05;
-
-/// Discover optical drives by enumerating `/dev/sg*` SCSI-generic nodes,
-/// opening each, running INQUIRY, and keeping only devices whose
-/// peripheral device type is optical (MMC, type 0x05).
-///
-/// Devices where `scsi::open` or `DriveId::from_drive` fail are silently
-/// skipped — that is intentional for enumeration (a busy or wedged node
-/// shouldn't abort discovery of the others).
 pub fn find_drives() -> Vec<(String, DriveId)> {
     let mut drives = Vec::new();
-    for name in enumerate_sg_names() {
-        let path = format!("/dev/{name}");
+    for i in 0..16 {
+        let path = format!("/dev/sg{i}");
         if !std::path::Path::new(&path).exists() {
             continue;
         }
-        if let Ok(mut transport) = crate::scsi::open(std::path::Path::new(&path))
-            && let Ok(id) = DriveId::from_drive(transport.as_mut())
-            && !id.raw_inquiry.is_empty()
-            && (id.raw_inquiry[0] & 0x1F) == SCSI_PERIPHERAL_TYPE_OPTICAL
-        {
-            drives.push((path, id));
+        if let Ok(mut transport) = crate::scsi::open(std::path::Path::new(&path)) {
+            if let Ok(id) = DriveId::from_drive(transport.as_mut()) {
+                if !id.raw_inquiry.is_empty() && (id.raw_inquiry[0] & 0x1F) == 0x05 {
+                    drives.push((path, id));
+                }
+            }
         }
     }
     drives
 }
 
-/// Enumerate `sg*` device names. Linux assigns `/dev/sgN` sequentially
-/// across *all* SCSI-generic devices (disks, tape, HBAs, optical), so a
-/// fixed `sg0..15` range can miss an optical drive on a host with many
-/// targets. Prefer the exact present-device list from
-/// `/sys/class/scsi_generic/`; fall back to a bounded `sg0..15` probe
-/// only when sysfs is unreadable (minimal containers).
-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") {
-                names.push(name);
-            }
-        }
-    } else {
-        for i in 0..16 {
-            let name = format!("sg{i}");
-            if std::path::Path::new(&format!("/dev/{name}")).exists() {
-                names.push(name);
-            }
-        }
-    }
-    names.sort();
-    names
-}
-
-/// Resolve a device path to its raw `/dev/sg*` SCSI-generic node.
-///
-/// - `/dev/sg*` paths pass through unchanged ([`DeviceResolution::Direct`]).
-/// - `/dev/sr*` block paths are matched (by vendor/product/serial) to the
-///   corresponding `/dev/sg*` node ([`DeviceResolution::SrToSg`]); if no
-///   match is found the original path is returned with
-///   [`DeviceResolution::SrNoSgMatch`].
-/// - Any other existing path passes through as [`DeviceResolution::Direct`].
 #[allow(dead_code)]
-pub fn resolve_device(path: &str) -> Result<(String, DeviceResolution)> {
+pub fn resolve_device(path: &str) -> Result<(String, Option<String>)> {
     if path.contains("/sg") {
         if !std::path::Path::new(path).exists() {
             return Err(Error::DeviceNotFound {
                 path: path.to_string(),
             });
         }
-        return Ok((path.to_string(), DeviceResolution::Direct));
+        return Ok((path.to_string(), None));
     }
     if path.contains("/sr") {
         let mut sr_transport = crate::scsi::open(std::path::Path::new(path))?;
         let sr_id = DriveId::from_drive(sr_transport.as_mut())?;
         drop(sr_transport);
         for (sg_path, sg_id) in find_drives() {
-            // Require a non-empty serial before treating vendor/product/
-            // serial as a unique match. serial_number falls back to an
-            // empty string when GET CONFIGURATION 0108h is unavailable
-            // (common on OEM drives); two same-model drives would then
-            // both compare equal and the first in enumeration order would
-            // win silently, resolving sr1 to sr0's sg node. An empty
-            // serial can't disambiguate, so fall through to the no-match
-            // path instead.
-            if !sr_id.serial_number.is_empty()
-                && sg_id.vendor_id == sr_id.vendor_id
+            if sg_id.vendor_id == sr_id.vendor_id
                 && sg_id.product_id == sr_id.product_id
                 && sg_id.serial_number == sr_id.serial_number
             {
-                return Ok((sg_path, DeviceResolution::SrToSg));
+                let warning =
+                    format!("{path} is a block device (sr) — using {sg_path} (sg) for raw access");
+                return Ok((sg_path, Some(warning)));
             }
         }
-        return Ok((path.to_string(), DeviceResolution::SrNoSgMatch));
+        return Ok((
+            path.to_string(),
+            Some(format!(
+                "{path} is a block device (sr) — no matching sg device found"
+            )),
+        ));
     }
     if !std::path::Path::new(path).exists() {
         return Err(Error::DeviceNotFound {
             path: path.to_string(),
         });
     }
-    Ok((path.to_string(), DeviceResolution::Direct))
+    Ok((path.to_string(), None))
 }

src/drive/macos.rs

@@ -4,20 +4,9 @@
 //! to discover optical drives without exclusive access or unmounts. Only
 //! the returned paths are then opened for INQUIRY to build full `DriveId`.
 
-use crate::drive::DeviceResolution;
 use crate::error::{Error, Result};
 use crate::identity::DriveId;
 
-/// SCSI peripheral device type 5 = MMC / optical, in the low 5 bits of
-/// INQUIRY byte 0.
-const SCSI_PERIPHERAL_TYPE_OPTICAL: u8 = 0x05;
-
-/// Discover optical drives via the IOKit registry (`scsi::list_drives`),
-/// then open each candidate for INQUIRY to build a full `DriveId`.
-///
-/// Any drive where `scsi::open` or `DriveId::from_drive` fails, or whose
-/// peripheral device type is not optical (MMC, type 0x05), is silently
-/// skipped — the same MMC filter the Linux and Windows backends apply.
 pub fn find_drives() -> Vec<(String, DriveId)> {
     let mut drives = Vec::new();
     let discovered = crate::scsi::list_drives();
@@ -25,10 +14,7 @@ pub fn find_drives() -> Vec<(String, DriveId)> {
         let path = std::path::Path::new(&info.path);
         match crate::scsi::open(path) {
             Ok(mut transport) => {
-                if let Ok(id) = DriveId::from_drive(transport.as_mut())
-                    && !id.raw_inquiry.is_empty()
-                    && (id.raw_inquiry[0] & 0x1F) == SCSI_PERIPHERAL_TYPE_OPTICAL
-                {
+                if let Ok(id) = DriveId::from_drive(transport.as_mut()) {
                     drives.push((info.path.clone(), id));
                 }
             }
@@ -40,45 +26,20 @@ pub fn find_drives() -> Vec<(String, DriveId)> {
     drives
 }
 
-/// Resolve a device path on macOS. There is no `sr`→`sg` style
-/// substitution here (that is a Linux concern), so any existing path is
-/// returned unchanged as [`DeviceResolution::Direct`]; the
-/// [`DeviceResolution`] return exists for cross-platform signature parity.
-pub fn resolve_device(path: &str) -> Result<(String, DeviceResolution)> {
+pub fn resolve_device(path: &str) -> Result<(String, Option<String>)> {
+    // Accept /dev/diskN or /dev/rdiskN paths as-is
+    if path.contains("/disk") || path.contains("/rdisk") {
+        if !std::path::Path::new(path).exists() {
+            return Err(Error::DeviceNotFound {
+                path: path.to_string(),
+            });
+        }
+        return Ok((path.to_string(), None));
+    }
     if !std::path::Path::new(path).exists() {
         return Err(Error::DeviceNotFound {
             path: path.to_string(),
         });
     }
-    Ok((path.to_string(), DeviceResolution::Direct))
-}
-
-#[cfg(test)]
-mod resolve_device_tests {
-    use super::*;
-
-    /// An existing path resolves unchanged as `Direct` — macOS has no
-    /// `sr`->`sg` substitution, so the returned path must be byte-identical
-    /// to the input, not some canonicalised/mutated form.
-    #[test]
-    fn existing_path_resolves_direct_unchanged() {
-        // Use the test binary's own executable path: guaranteed to exist,
-        // no fixture file needed.
-        let exe = std::env::current_exe().unwrap();
-        let path = exe.to_str().unwrap();
-        let (resolved, kind) = resolve_device(path).expect("existing path must resolve");
-        assert_eq!(resolved, path, "path must be returned unchanged");
-        assert_eq!(kind, DeviceResolution::Direct);
-    }
-
-    /// A path that does not exist must error with `DeviceNotFound` carrying
-    /// the original path, never silently succeed.
-    #[test]
-    fn missing_path_is_device_not_found() {
-        let path = "/dev/freemkv-definitely-does-not-exist-0xdead";
-        match resolve_device(path) {
-            Err(Error::DeviceNotFound { path: p }) => assert_eq!(p, path),
-            other => panic!("expected DeviceNotFound, got {other:?}"),
-        }
-    }
+    Ok((path.to_string(), None))
 }

src/drive/windows.rs

@@ -1,18 +1,9 @@
 //! Windows drive discovery and device resolution.
 
-use crate::drive::DeviceResolution;
 use crate::error::Result;
 use crate::identity::DriveId;
 use std::path::Path;
 
-/// SCSI peripheral device type 5 = MMC / optical, in the low 5 bits of
-/// INQUIRY byte 0.
-const SCSI_PERIPHERAL_TYPE_OPTICAL: u8 = 0x05;
-
-/// Discover optical drives. Probes `\\.\CdRom0..15` first; only if none
-/// are found does it fall back to scanning drive letters `D..Z`. Each
-/// candidate is opened, INQUIRY'd, and kept only if its peripheral device
-/// type is optical (MMC, type 0x05). Returns normalized `\\.\` paths.
 pub fn find_drives() -> Vec<(String, DriveId)> {
     let mut drives = Vec::new();
 
@@ -21,9 +12,7 @@ pub fn find_drives() -> Vec<(String, DriveId)> {
         let path = format!("\\\\.\\CdRom{}", i);
         if let Ok(mut transport) = crate::scsi::open(Path::new(&path)) {
             if let Ok(id) = DriveId::from_drive(transport.as_mut()) {
-                if !id.raw_inquiry.is_empty()
-                    && (id.raw_inquiry[0] & 0x1F) == SCSI_PERIPHERAL_TYPE_OPTICAL
-                {
+                if !id.raw_inquiry.is_empty() && (id.raw_inquiry[0] & 0x1F) == 0x05 {
                     drives.push((path, id));
                 }
             }
@@ -36,12 +25,8 @@ pub fn find_drives() -> Vec<(String, DriveId)> {
             let path = format!("{}:", letter as char);
             if let Ok(mut transport) = crate::scsi::open(Path::new(&path)) {
                 if let Ok(id) = DriveId::from_drive(transport.as_mut()) {
-                    if !id.raw_inquiry.is_empty()
-                        && (id.raw_inquiry[0] & 0x1F) == SCSI_PERIPHERAL_TYPE_OPTICAL
-                    {
-                        // Normalize so returned paths are consistently in
-                        // \\.\ form regardless of which loop matched.
-                        drives.push((normalize_path(&path), id));
+                    if !id.raw_inquiry.is_empty() && (id.raw_inquiry[0] & 0x1F) == 0x05 {
+                        drives.push((path, id));
                     }
                 }
             }
@@ -51,11 +36,8 @@ pub fn find_drives() -> Vec<(String, DriveId)> {
     drives
 }
 
-/// Resolve a device path to its normalized Windows `\\.\` form. Windows
-/// has no `sr`→`sg` symlink-target indirection, so resolution is purely a
-/// path normalization and always reports [`DeviceResolution::Direct`].
-pub fn resolve_device(path: &str) -> Result<(String, DeviceResolution)> {
-    Ok((normalize_path(path), DeviceResolution::Direct))
+pub fn resolve_device(path: &str) -> Result<(String, Option<String>)> {
+    Ok((normalize_path(path), None))
 }
 
 /// Normalize a device path to Windows \\.\X: format.
@@ -73,6 +55,9 @@ fn normalize_path(path: &str) -> String {
     if trimmed.len() == 2 && trimmed.as_bytes()[1] == b':' {
         return format!("\\\\.\\{}", trimmed);
     }
+    if path.to_lowercase().starts_with("cdrom") {
+        return format!("\\\\.\\{}", path);
+    }
     format!("\\\\.\\{}", path)
 }
 

src/drm/mod.rs

@@ -0,0 +1,287 @@
+//! Top-level DRM scheme dispatch.
+//!
+//! Four content-protection schemes ride through a single
+//! detect-then-load pipeline:
+//!
+//! | Scheme              | Discriminator                                  |
+//! |---------------------|------------------------------------------------|
+//! | [`DrmScheme::Css`]  | DVD probe sector flagged scrambled             |
+//! | [`DrmScheme::Aacs10`] | Content cert type byte `0x00`                |
+//! | [`DrmScheme::Aacs20`] | Content cert type byte `!= 0x00`, no Variant |
+//! | [`DrmScheme::Aacs21`] | Content cert + MKB records `0x82` / `0x83`   |
+//!
+//! Detection happens from a [`DrmProbe`] (raw inputs the caller has
+//! already extracted from the disc); resolution runs through a
+//! [`DrmContext`] (the full set of inputs the loaders need).
+//!
+//! The AACS 2.1 arm is wired but disabled. The dispatcher leaves
+//! [`crate::aacs::resolve_keys_v21`] reachable as a library entry point
+//! for fixture-driven validation, but production consumers go through
+//! [`DrmScheme::load`], which short-circuits V21 to `None` until the
+//! Variant chain has a real Variant-scheme disc to validate against.
+
+use crate::aacs;
+use crate::css;
+
+/// Which content-protection scheme governs a disc.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DrmScheme {
+    /// DVD Content Scramble System.
+    Css,
+    /// AACS 1.0 — original BD-ROM.
+    Aacs10,
+    /// AACS 2.0 — UHD-BD, classical Media Key chain.
+    Aacs20,
+    /// AACS 2.1 — UHD-BD with Media Key Variant chain.
+    Aacs21,
+}
+
+/// Inputs to [`DrmScheme::detect`]. All borrows — caller retains
+/// ownership.
+pub struct DrmProbe<'a> {
+    /// 2048-byte sample sector from inside a DVD title's extents. Used
+    /// only for CSS scramble-flag detection. `None` for non-DVD discs.
+    pub dvd_sample_sector: Option<&'a [u8]>,
+    /// Content Certificate file bytes (typically `/AACS/Content000.cer`).
+    /// `None` when the disc has no AACS directory.
+    pub content_cert: Option<&'a [u8]>,
+    /// MKB file bytes (typically `/AACS/MKB_RW.inf`). Required to
+    /// distinguish AACS 2.0 from AACS 2.1.
+    pub mkb: Option<&'a [u8]>,
+}
+
+/// Inputs to [`DrmScheme::load`]. Carries everything needed by either
+/// the AACS or CSS loader.
+pub struct DrmContext<'a> {
+    /// AACS resolver inputs — required when the scheme is any AACS
+    /// variant.
+    pub aacs: Option<aacs::ResolveContext<'a>>,
+    /// CSS resolver inputs — required when the scheme is [`DrmScheme::Css`].
+    pub css: Option<css::CssContext<'a>>,
+}
+
+/// Resolved key material, tagged by scheme.
+#[derive(Debug)]
+pub enum ResolvedScheme {
+    Css(css::CssState),
+    Aacs(aacs::ResolvedKeys),
+}
+
+impl DrmScheme {
+    /// Detect which DRM scheme protects the disc described by `probe`.
+    ///
+    /// Returns `None` for unencrypted media. The order is intentional:
+    /// CSS is checked first (DVD-format probe), then AACS (Blu-ray
+    /// format).
+    pub fn detect(probe: &DrmProbe<'_>) -> Option<DrmScheme> {
+        // CSS — DVD probe sector carries the scramble flag.
+        if let Some(sector) = probe.dvd_sample_sector {
+            if css::is_scrambled(sector) {
+                return Some(DrmScheme::Css);
+            }
+        }
+
+        // AACS — content cert type byte distinguishes V10 from V20+.
+        // V21 promotion requires MKB Variant records.
+        let cc = probe.content_cert.and_then(aacs::parse_content_cert)?;
+        match cc.version {
+            aacs::AacsVersion::V10 => Some(DrmScheme::Aacs10),
+            aacs::AacsVersion::V20 | aacs::AacsVersion::V21 => {
+                if let Some(mkb) = probe.mkb {
+                    let recs = aacs::variants::walk_mkb(mkb);
+                    if aacs::variants::is_variant_mkb(&recs) {
+                        return Some(DrmScheme::Aacs21);
+                    }
+                }
+                Some(DrmScheme::Aacs20)
+            }
+        }
+    }
+
+    /// Run key resolution for this scheme against `ctx`.
+    ///
+    /// Returns `None` when the scheme's resolver could not produce keys
+    /// (missing context, KEYDB miss, failed crypto walk, etc.) or when
+    /// the scheme itself is gated off (see the inline comment on the
+    /// `Aacs21` arm).
+    pub fn load(self, ctx: &mut DrmContext<'_>) -> Option<ResolvedScheme> {
+        match self {
+            DrmScheme::Css => ctx
+                .css
+                .as_mut()
+                .and_then(css::resolve)
+                .map(ResolvedScheme::Css),
+            DrmScheme::Aacs10 => ctx
+                .aacs
+                .as_ref()
+                .and_then(aacs::resolve_keys_v1)
+                .map(ResolvedScheme::Aacs),
+            DrmScheme::Aacs20 => ctx
+                .aacs
+                .as_ref()
+                .and_then(aacs::resolve_keys_v2)
+                .map(ResolvedScheme::Aacs),
+            // AACS 2.1 derivation is wired but disabled. KCD validation
+            // against a Variant-scheme disc is pending. To enable,
+            // uncomment the line below.
+            // DrmScheme::Aacs21 => ctx
+            //     .aacs
+            //     .as_ref()
+            //     .and_then(aacs::resolve_keys_v21)
+            //     .map(ResolvedScheme::Aacs),
+            DrmScheme::Aacs21 => None,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Build a minimal cert: type byte + bus-encryption byte + 6 zero
+    // cc_id bytes.
+    fn cert(type_byte: u8) -> Vec<u8> {
+        let mut v = vec![0u8; 8];
+        v[0] = type_byte;
+        v
+    }
+
+    // Synthetic AACS 2.x MKB with no Variant records.
+    fn mkb_classical() -> Vec<u8> {
+        vec![
+            0x10, 0x00, 0x00, 0x0C, 0x48, 0x14, 0x10, 0x03, 0x00, 0x00, 0x00, 0x4D,
+        ]
+    }
+
+    // Synthetic AACS 2.x MKB with a 0x82 + 0x83 record pair.
+    fn mkb_with_variant() -> Vec<u8> {
+        let mut m = mkb_classical();
+        m.extend_from_slice(&[0x82, 0x00, 0x00, 0x14]);
+        m.extend_from_slice(&[0xEE; 16]);
+        m.extend_from_slice(&[0x83, 0x00, 0x00, 0x14]);
+        m.extend_from_slice(&[0x55; 16]);
+        m
+    }
+
+    // Synthetic scrambled DVD sector — byte 0x14 carries the CSS
+    // scramble flag in bits 4-5.
+    fn scrambled_dvd_sector() -> Vec<u8> {
+        let mut s = vec![0u8; 2048];
+        s[0x14] = 0x30;
+        s
+    }
+
+    #[test]
+    fn detect_returns_none_for_unencrypted() {
+        let probe = DrmProbe {
+            dvd_sample_sector: None,
+            content_cert: None,
+            mkb: None,
+        };
+        assert_eq!(DrmScheme::detect(&probe), None);
+    }
+
+    #[test]
+    fn detect_returns_css_for_scrambled_dvd() {
+        let sector = scrambled_dvd_sector();
+        let probe = DrmProbe {
+            dvd_sample_sector: Some(&sector),
+            content_cert: None,
+            mkb: None,
+        };
+        assert_eq!(DrmScheme::detect(&probe), Some(DrmScheme::Css));
+    }
+
+    #[test]
+    fn detect_returns_aacs10_for_type0_cert() {
+        let c = cert(0x00);
+        let probe = DrmProbe {
+            dvd_sample_sector: None,
+            content_cert: Some(&c),
+            mkb: None,
+        };
+        assert_eq!(DrmScheme::detect(&probe), Some(DrmScheme::Aacs10));
+    }
+
+    #[test]
+    fn detect_returns_aacs20_for_type1_cert_no_variant() {
+        let c = cert(0x01);
+        let mkb = mkb_classical();
+        let probe = DrmProbe {
+            dvd_sample_sector: None,
+            content_cert: Some(&c),
+            mkb: Some(&mkb),
+        };
+        assert_eq!(DrmScheme::detect(&probe), Some(DrmScheme::Aacs20));
+    }
+
+    #[test]
+    fn detect_returns_aacs21_for_type1_cert_with_variant() {
+        let c = cert(0x01);
+        let mkb = mkb_with_variant();
+        let probe = DrmProbe {
+            dvd_sample_sector: None,
+            content_cert: Some(&c),
+            mkb: Some(&mkb),
+        };
+        assert_eq!(DrmScheme::detect(&probe), Some(DrmScheme::Aacs21));
+    }
+
+    #[test]
+    fn detect_returns_aacs20_when_mkb_absent() {
+        // Type-1 cert but no MKB to upgrade with -> Aacs20.
+        let c = cert(0x01);
+        let probe = DrmProbe {
+            dvd_sample_sector: None,
+            content_cert: Some(&c),
+            mkb: None,
+        };
+        assert_eq!(DrmScheme::detect(&probe), Some(DrmScheme::Aacs20));
+    }
+
+    #[test]
+    fn load_aacs21_returns_none() {
+        // The Aacs21 dispatch arm is commented out; load() must
+        // return None until KCD validation lands.
+        let uk_ro = vec![0u8; 256];
+        let vid = [0u8; 16];
+        let keydb = aacs::KeyDb::empty();
+        let ctx_aacs = aacs::ResolveContext {
+            unit_key_ro: &uk_ro,
+            content_cert: None,
+            volume_id: &vid,
+            keydb: &keydb,
+            mkb: None,
+        };
+        let mut ctx = DrmContext {
+            aacs: Some(ctx_aacs),
+            css: None,
+        };
+        assert!(DrmScheme::Aacs21.load(&mut ctx).is_none());
+    }
+
+    /// Exercises the V21 helper directly. Gated `#[ignore]` because
+    /// the chain reaches `MediaKeyVariantError::VariantsTableUnavailable`
+    /// without a real Variant-scheme disc to fix the per-uv table
+    /// layout against — running it here would assert only the
+    /// not-yet-wired error code. Kept as a wiring smoke-test for
+    /// future enablement.
+    #[test]
+    #[ignore]
+    fn resolve_keys_v21_helper_exists() {
+        let uk_ro = vec![0u8; 256];
+        let vid = [0xAAu8; 16];
+        let keydb = aacs::KeyDb::empty();
+        let mkb = mkb_with_variant();
+        let ctx = aacs::ResolveContext {
+            unit_key_ro: &uk_ro,
+            content_cert: None,
+            volume_id: &vid,
+            keydb: &keydb,
+            mkb: Some(&mkb),
+        };
+        // Just confirm the symbol is callable; we don't assert on the
+        // result.
+        let _ = aacs::resolve_keys_v21(&ctx);
+    }
+}

src/dvdnav/mod.rs

@@ -1,49 +0,0 @@
-//! DVD-Video navigation — read-only resolver for the **main-feature start
-//! point** (issue #40). Mirrors what a DVD player's nav VM resolves: First-Play
-//! → menu "Play" → title dispatch → the first cell of the feature, so the rip
-//! starts at the movie rather than at raw cell 0 (e.g. skipping a leading
-//! logo/warning segment when the disc's own navigation does).
-//!
-//! Byte layout follows the DVD-Video specification (VMGI/VTSI headers,
-//! PGC/cell tables, PCI/HLI button packets); the VM command decoder is
-//! verified against real discs.
-//!
-//! Current contents: [`vmcmd`] — the VM command decoder (proven against the
-//! SOTL/Greenland test discs). The IFO/PCI parsing and the navigation executor
-//! that resolves the start cell build on top of this.
-
-pub mod vmcmd;
-
-use crate::sector::SectorSource;
-
-/// Resolve the feature title's **true start cell** (0-based index into the
-/// title PGC's cell list) by following the disc's own navigation — First-Play →
-/// menu "Play" → title dispatch — the way a player reaches the movie. This is
-/// what lets the rip begin at the feature instead of at raw cell 0 when the
-/// disc's nav enters the title past a leading logo/warning segment (e.g. a
-/// disc whose "Play" resolves to a later cell than cell 0).
-///
-/// Returns `None` when navigation cannot be resolved, so the caller falls back
-/// to the structural leading-cell filter (today's behaviour, ≈ cell 0 / 0:00).
-///
-/// TODO(#40): the IFO/PCI parsing + nav executor (built on [`vmcmd`]) land
-/// incrementally. Until the executor is complete this returns `None`, so wiring
-/// it in is behaviour-neutral; improvements to the resolver take effect here
-/// without touching the call site.
-pub fn resolve_feature_start(
-    reader: &mut dyn SectorSource,
-    udf: &crate::udf::UdfFs,
-    vtsn: u16,
-    vts_ttn: u16,
-) -> Option<usize> {
-    // `reader`/`udf` are the seam inputs the nav executor will consume to read
-    // VIDEO_TS.IFO + the VTS IFOs/menu VOBs. Reserved until that lands.
-    let _ = (reader, udf);
-    tracing::trace!(
-        target: "freemkv::dvdnav",
-        vtsn,
-        vts_ttn,
-        "nav start-cell resolver: unresolved — caller falls back to leading-cell filter"
-    );
-    None
-}

src/dvdnav/vmcmd.rs

@@ -1,408 +0,0 @@
-//! DVD-Video VM command decoder.
-//!
-//! An 8-byte navigation command as found in PGC command tables (pre/post/cell)
-//! and PCI button info. Decoded per the DVD-Video VM instruction set and
-//! verified against real discs.
-//!
-//! Bit model: the 8 bytes are a big-endian 64-bit word. `byte0` bits 7-5 are the
-//! command **type**; for type 1, `byte0` bit 4 selects Link (0) vs Jump (1), and
-//! `byte1` bits 3-0 are the sub-command. Compare predicates live in `byte1`
-//! bits 6-4 with the operands in bytes 2-5.
-//!
-//! This module is pure decode + a register model — no I/O, no English (numeric
-//! semantics only), matching libfreemkv conventions. The navigation *executor*
-//! and IFO/PCI parsing build on top of this.
-
-/// A decoded navigation instruction. Only the variants freemkv's start-point
-/// resolver needs are modelled explicitly; everything else is [`Instr::Other`].
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum Instr {
-    Nop,
-    /// Stop executing the current command list (resume cell playback).
-    Break,
-    /// Goto command line within the same list (1-based).
-    Goto {
-        line: u8,
-    },
-    /// Leave the current domain.
-    Exit,
-    /// Jump to a VMG title (1-based TT_SRPT index).
-    JumpTt {
-        ttn: u8,
-    },
-    /// Jump to a title within the current VTS (1-based VTS title index).
-    JumpVtsTt {
-        ttn: u8,
-    },
-    /// Jump to a part-of-title (chapter) within a VTS title.
-    JumpVtsPtt {
-        ttn: u8,
-        pttn: u16,
-    },
-    /// Jump to the First-Play PGC.
-    JumpSsFp,
-    /// Jump to a Video-Manager menu (`menu` = menu id).
-    JumpSsVmgm {
-        menu: u8,
-    },
-    /// Jump to a Video-Title-Set menu.
-    JumpSsVtsm {
-        vts: u8,
-        ttn: u8,
-        menu: u8,
-    },
-    /// Jump to a specific VMGM menu PGC.
-    JumpSsVmgmPgc {
-        pgcn: u16,
-    },
-    /// Call a sub-domain (raw retained; resume handled by the executor).
-    CallSs {
-        sub: u8,
-    },
-    /// Link to a PGC number within the current domain.
-    LinkPgcn {
-        pgcn: u16,
-    },
-    /// Link to a part-of-title within the current PGC's title.
-    LinkPttn {
-        pttn: u16,
-    },
-    /// Link to a program number within the current PGC (1-based).
-    LinkPgn {
-        pgn: u8,
-    },
-    /// Link to a cell number within the current PGC (1-based).
-    LinkCn {
-        cn: u8,
-    },
-    /// A link "subset" op (LinkTopCell/NextPG/RSM/…); `sub` is the raw code.
-    LinkSub {
-        sub: u8,
-    },
-    /// Set a GPRM. `op` is the set-op code (1=mov, 3=add, …); value is immediate
-    /// (`imm`) when `immediate`, else the contents of register `src`.
-    SetGprm {
-        reg: u8,
-        op: u8,
-        immediate: bool,
-        imm: u16,
-        src: u8,
-    },
-    /// Set a system parameter / unmodelled set — executor may ignore.
-    SetSystem,
-    /// Anything not individually modelled (kept as raw bytes).
-    Other([u8; 8]),
-}
-
-/// A compare predicate carried by a command (`byte1` bits 6-4). `None` = always.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct Compare {
-    /// Compare op: 1=&,2===,3=!=,4=>=,5=>,6=<=,7=<.
-    pub op: u8,
-    /// Left register index (GPRM 0-15, SPRM 128+).
-    pub lhs_reg: u8,
-    /// Right side: immediate when `immediate`, else register `rhs_reg`.
-    pub immediate: bool,
-    pub imm: u16,
-    pub rhs_reg: u8,
-}
-
-/// A fully decoded command: its predicate (if any) and the instruction.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct Command {
-    pub compare: Option<Compare>,
-    pub instr: Instr,
-}
-
-// Command types — `byte0` bits 7-5.
-const TYPE_SPECIAL: u8 = 0;
-const TYPE_LINK_JUMP: u8 = 1;
-const TYPE_SET_SYSTEM: u8 = 2;
-const TYPE_SET_GPRM: u8 = 3;
-
-// Special (type 0) sub-commands — `byte1` bits 3-0.
-const SP_GOTO: u8 = 1;
-const SP_BREAK: u8 = 2;
-
-// Jump/Call (type 1, direct=1) sub-commands.
-const JP_EXIT: u8 = 1;
-const JP_JUMP_TT: u8 = 2;
-const JP_JUMP_VTS_TT: u8 = 3;
-const JP_JUMP_VTS_PTT: u8 = 5;
-const JP_JUMP_SS: u8 = 6;
-const JP_CALL_SS: u8 = 8;
-
-// Link (type 1, direct=0) sub-commands. NOTE: sub-op 0 is NOP/no-link and 1 is
-// the LinkSub form (the DVD-Video VM link instruction).
-const LK_SUB: u8 = 1;
-const LK_PGCN: u8 = 4;
-const LK_PTTN: u8 = 5;
-const LK_PGN: u8 = 6;
-const LK_CN: u8 = 7;
-
-// JumpSS sub-domain selector — `byte5` bits 7-6.
-const SS_FP: u8 = 0;
-const SS_VMGM_MENU: u8 = 1;
-const SS_VTSM: u8 = 2;
-
-// Operand field widths (spec-defined bit counts).
-const MASK_TTN: u8 = 0x7F; // 7-bit title number
-const MASK_PGN: u8 = 0x7F; // 7-bit program number
-const MASK_LINKOP: u8 = 0x1F; // 5-bit link sub-op
-const MASK_REG: u8 = 0x0F; // 4-bit GPRM index
-const MASK_MENU: u8 = 0x0F; // 4-bit menu id
-const MASK_PTTN: u16 = 0x03FF; // 10-bit part-of-title
-const MASK_PGCN: u16 = 0x7FFF; // 15-bit PGC number
-
-#[inline]
-fn be16(b: &[u8; 8], o: usize) -> u16 {
-    ((b[o] as u16) << 8) | b[o + 1] as u16
-}
-
-// Compare-operand layouts ("if_version"s) per the DVD-Video VM. The op
-// nibble is always `byte1` bits 6-4; the immediate flag is `byte1` bit 7. The
-// operand *offsets* differ by command family.
-//
-// v1 (special + link): lhs reg = b[3]; rhs imm = bytes4-5 / rhs reg = b[4].
-// v2 (jump + system-set): lhs reg = b[6]; rhs reg = b[7] (registers only).
-// v3 (set-GPRM): lhs reg = b[2]; rhs imm = bytes6-7 / rhs reg = b[6].
-fn if_v1(b: &[u8; 8]) -> Option<Compare> {
-    let op = (b[1] >> 4) & 7;
-    (op != 0).then(|| Compare {
-        op,
-        lhs_reg: b[3],
-        immediate: b[1] >> 7 != 0,
-        imm: be16(b, 4),
-        rhs_reg: b[4],
-    })
-}
-fn if_v2(b: &[u8; 8]) -> Option<Compare> {
-    let op = (b[1] >> 4) & 7;
-    (op != 0).then(|| Compare {
-        op,
-        lhs_reg: b[6],
-        immediate: false,
-        imm: 0,
-        rhs_reg: b[7],
-    })
-}
-fn if_v3(b: &[u8; 8]) -> Option<Compare> {
-    let op = (b[1] >> 4) & 7;
-    (op != 0).then(|| Compare {
-        op,
-        lhs_reg: b[2],
-        immediate: b[1] >> 7 != 0,
-        imm: be16(b, 6),
-        rhs_reg: b[6],
-    })
-}
-
-/// Decode an 8-byte VM command.
-pub fn decode(b: &[u8; 8]) -> Command {
-    let typ = b[0] >> 5;
-    let direct = (b[0] >> 4) & 1;
-    let setop = b[0] & 0x0F;
-    let cmd = b[1] & 0x0F;
-
-    // Compare predicate, with the operand layout for this command family
-    // (the DVD-Video VM command type dispatch).
-    let compare = match (typ, direct) {
-        (TYPE_SPECIAL, _) => if_v1(b),
-        (TYPE_LINK_JUMP, 1) => if_v2(b), // jump
-        (TYPE_LINK_JUMP, 0) => if_v1(b), // link
-        (TYPE_SET_SYSTEM, _) => if_v2(b),
-        (TYPE_SET_GPRM, _) => if_v3(b),
-        _ => None, // 4/5/6 compound — not needed by the resolver
-    };
-
-    // JumpSS sub-domain selector lives in byte5 bits 7-6.
-    let ss_sel = b[5] >> 6;
-
-    let instr = match typ {
-        TYPE_LINK_JUMP if direct == 1 => match cmd {
-            JP_EXIT => Instr::Exit,
-            JP_JUMP_TT => Instr::JumpTt {
-                ttn: b[5] & MASK_TTN,
-            },
-            JP_JUMP_VTS_TT => Instr::JumpVtsTt {
-                ttn: b[5] & MASK_TTN,
-            },
-            JP_JUMP_VTS_PTT => Instr::JumpVtsPtt {
-                ttn: b[5] & MASK_TTN,
-                pttn: be16(b, 2) & MASK_PTTN,
-            },
-            JP_JUMP_SS => match ss_sel {
-                SS_FP => Instr::JumpSsFp,
-                SS_VMGM_MENU => Instr::JumpSsVmgm {
-                    menu: b[5] & MASK_MENU,
-                },
-                SS_VTSM => Instr::JumpSsVtsm {
-                    vts: b[4],
-                    ttn: b[3],
-                    menu: b[5] & MASK_MENU,
-                },
-                _ => Instr::JumpSsVmgmPgc {
-                    pgcn: be16(b, 2) & MASK_PGCN,
-                },
-            },
-            JP_CALL_SS => Instr::CallSs { sub: ss_sel },
-            _ => Instr::Nop,
-        },
-        TYPE_LINK_JUMP => match cmd {
-            // direct == 0 (link). sub-op 0 = NOP/no-link.
-            LK_SUB => Instr::LinkSub {
-                sub: b[7] & MASK_LINKOP,
-            },
-            LK_PGCN => Instr::LinkPgcn {
-                pgcn: be16(b, 6) & MASK_PGCN,
-            },
-            LK_PTTN => Instr::LinkPttn {
-                pttn: be16(b, 6) & MASK_PTTN,
-            },
-            LK_PGN => Instr::LinkPgn {
-                pgn: b[7] & MASK_PGN,
-            },
-            LK_CN => Instr::LinkCn { cn: b[7] },
-            _ => Instr::Nop,
-        },
-        TYPE_SPECIAL => match cmd {
-            SP_GOTO => Instr::Goto { line: b[7] },
-            SP_BREAK => Instr::Break,
-            _ => Instr::Nop,
-        },
-        TYPE_SET_GPRM => Instr::SetGprm {
-            reg: b[3] & MASK_REG,
-            op: setop,
-            immediate: direct != 0,
-            imm: be16(b, 4),
-            src: b[5],
-        },
-        TYPE_SET_SYSTEM => Instr::SetSystem,
-        _ => Instr::Other(*b),
-    };
-
-    Command { compare, instr }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    fn h(s: &str) -> [u8; 8] {
-        let v: Vec<u8> = (0..8)
-            .map(|i| u8::from_str_radix(&s[i * 2..i * 2 + 2], 16).unwrap())
-            .collect();
-        v.try_into().unwrap()
-    }
-
-    // KATs taken from the real SOTL / Greenland discs (decoded in the PoC).
-    #[test]
-    fn greenland_first_play_is_jumptt_1() {
-        let c = decode(&h("3002000000010000"));
-        assert_eq!(c.instr, Instr::JumpTt { ttn: 1 });
-        assert!(c.compare.is_none());
-    }
-
-    #[test]
-    fn sotl_first_play_is_jumpss_vtsm_root() {
-        // 30 06 ... byte5=0x83 -> sub 2 (VTSM), vts=byte4=1, menu=byte5&0xF=3 (root)
-        let c = decode(&h("3006000101830000"));
-        assert_eq!(
-            c.instr,
-            Instr::JumpSsVtsm {
-                vts: 1,
-                ttn: 1,
-                menu: 3
-            }
-        );
-    }
-
-    #[test]
-    fn sotl_title_dispatch_is_conditional_linkpgn_2() {
-        // 20 a6 ... CmpLink: if GPRM0 == 2 -> LinkPGN 2  (cell 2 = the 5:02 start)
-        let c = decode(&h("20a6000000020002"));
-        assert_eq!(c.instr, Instr::LinkPgn { pgn: 2 });
-        let cmp = c.compare.expect("conditional");
-        assert_eq!(cmp.op, 2); // ==
-        assert_eq!(cmp.lhs_reg, 0); // GPRM0
-        assert!(cmp.immediate);
-        assert_eq!(cmp.imm, 2);
-    }
-
-    #[test]
-    fn sotl_root_button_is_linkpgcn_37() {
-        assert_eq!(
-            decode(&h("2004000000000025")).instr,
-            Instr::LinkPgcn { pgcn: 37 }
-        );
-    }
-
-    #[test]
-    fn greenland_scene_button_is_linkpgn() {
-        assert_eq!(
-            decode(&h("2006000000001401")).instr,
-            Instr::LinkPgn { pgn: 1 }
-        );
-    }
-
-    #[test]
-    fn jumpvts_ptt_decodes_ttn_and_pttn() {
-        // synthetic: 30 05 | ptt(bytes2-3)=0x0002 | ttn(byte5)=1
-        let c = decode(&h("3005000200010000"));
-        assert_eq!(c.instr, Instr::JumpVtsPtt { ttn: 1, pttn: 2 });
-    }
-
-    #[test]
-    fn setgprm_immediate_mov() {
-        // SOTL First-Play pre[0]: 71 00 | reg=byte3=6 | imm(bytes4-5)=0x03e8 -> g6 = 1000
-        match decode(&h("7100000603e80000")).instr {
-            Instr::SetGprm {
-                reg,
-                op,
-                immediate,
-                imm,
-                ..
-            } => {
-                assert_eq!(reg, 6);
-                assert_eq!(op, 1); // mov
-                assert!(immediate);
-                assert_eq!(imm, 1000);
-            }
-            other => panic!("expected SetGprm, got {other:?}"),
-        }
-    }
-
-    // Regression for the link sub-op decode: 0 = NOP, 1 = LinkSub.
-    #[test]
-    fn link_subop_zero_is_nop_one_is_linksub() {
-        assert_eq!(decode(&h("2000000000000000")).instr, Instr::Nop);
-        assert_eq!(
-            decode(&h("2001000000000010")).instr,
-            Instr::LinkSub { sub: 0x10 }
-        );
-    }
-
-    // if_version_1 register compare: rhs register is byte4 (not byte5).
-    #[test]
-    fn link_register_compare_rhs_is_byte4() {
-        // 20 26: link, cmp=EQ(2), dircmp=0(register) ; cmd=6 LinkPGN
-        let c = decode(&h("2026000304000002"));
-        assert_eq!(c.instr, Instr::LinkPgn { pgn: 2 });
-        let cmp = c.compare.expect("conditional");
-        assert!(!cmp.immediate);
-        assert_eq!(cmp.lhs_reg, 3);
-        assert_eq!(cmp.rhs_reg, 4);
-    }
-
-    // if_version_2 jump compare: both operands are registers in byte6 / byte7.
-    #[test]
-    fn jump_compare_uses_bytes6_and_7() {
-        // 30 22: jump, cmp=EQ(2) ; cmd=2 JumpTT ttn=byte5=5
-        let c = decode(&h("3022000000050607"));
-        assert_eq!(c.instr, Instr::JumpTt { ttn: 5 });
-        let cmp = c.compare.expect("conditional");
-        assert!(!cmp.immediate);
-        assert_eq!(cmp.lhs_reg, 6);
-        assert_eq!(cmp.rhs_reg, 7);
-    }
-}

src/event.rs

@@ -8,17 +8,11 @@
 //! disc.rip(&mut session, 0, output, |event| {
 //!     match event.kind {
 //!         EventKind::BytesRead { bytes, total } => update_progress(bytes, total),
-//!         EventKind::SectorSkipped { sector } => log_skip(sector),
-//!         EventKind::BatchSizeChanged { new_size, .. } => note_recovery(new_size),
+//!         EventKind::ReadError { sector, .. } => log_error(sector),
 //!         _ => {}
 //!     }
 //! });
 //! ```
-//!
-//! Note: the library currently emits only `BytesRead`, `SectorSkipped`,
-//! and `BatchSizeChanged`. The other [`EventKind`] variants are part of
-//! the stable event vocabulary for consumers (and future emit sites) but
-//! are not produced by the library today.
 
 use crate::error::Error;
 
@@ -122,29 +116,3 @@ pub enum BatchSizeReason {
 
 /// A no-op event handler. Ignores all events.
 pub fn ignore(_event: Event) {}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    /// BatchSizeReason::Shrunk != BatchSizeReason::Probed.
-    /// These two variants carry distinct meanings (error vs. recovery); they
-    /// must not compare as equal.
-    /// Mutation: deriving PartialEq without proper variant discrimination
-    ///           could make two distinct variants equal.
-    #[test]
-    fn batch_size_reason_variants_are_not_equal() {
-        assert_ne!(BatchSizeReason::Shrunk, BatchSizeReason::Probed);
-    }
-
-    /// BatchSizeReason is Clone + Copy: cloning does not move the original.
-    /// This is required because EventKind::BatchSizeChanged embeds it by value.
-    /// Mutation: removing Copy would require the caller to clone explicitly;
-    ///           code that passes reason by value would fail to compile.
-    #[test]
-    fn batch_size_reason_is_copy() {
-        let r = BatchSizeReason::Shrunk;
-        let _r2 = r; // copy, not move
-        let _r3 = r; // r still usable after copy
-    }
-}