v1.7.5: bump version (freemkv-unlock git-pinned for the tag)

docs: 1.7.5 changelog entry for the unified release [skip-media]
Version aligned to 1.7.5. No functional change to this crate — the release is driven by freemkv-unlock mirroring the freemkv-firmware 0.9.0 ABI, where the drive's separate Ake (0x06) and Bus (0x07) levers are retired into a single Encryption (0x06) lever.
2026-10-07 18:13:10 +00:00 · 2026-09-23 04:40:51 +00:00 · 2026-09-22 21:04:54 -07:00 · 2026-09-21 16:39:26 -07:00 · 2026-09-21 23:03:36 +00:00 · 2026-09-21 23:03:33 +00:00
53 changed files with 4471 additions and 1009 deletions
@@ -2,44 +2,38 @@ 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.
+    # dev -> qa -> main. `dev` is where work lands and is pushed to often: these
+    # are the FAST checks. `qa` runs these plus the expensive suite in qa.yml.
+    # `main` only moves at release time, to a commit already green on qa.
    branches: [main, dev, qa]
  pull_request:

+# Rapid dev pushes supersede their own in-progress runs instead of stacking.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
-  # ── Single source of truth for the MSRV ─────────────────────────────────────
-  #
-  # `rust-version` in Cargo.toml is the ONE place the MSRV is declared. This job
-  # reads it; every job that must build/test AT the MSRV consumes
-  # `needs.resolve-msrv.outputs.v` instead of a hardcoded pin, so the floor
-  # cannot drift out of sync across workflow files. The `test` job building
-  # green at this value IS the verification that the declared MSRV is real.
-  # clippy and the `consumers` job deliberately do NOT use it — they run on
-  # `stable` (lint debt is caught against current Rust; dependents float highest).
+  # Single source of truth for the MSRV: `rust-version` in Cargo.toml. Every job
+  # that builds AT the MSRV consumes needs.resolve-msrv.outputs.v so the floor
+  # cannot drift. clippy and `consumers` deliberately run on `stable`.
  resolve-msrv:
    runs-on: ubuntu-latest
    outputs:
      v: ${{ steps.msrv.outputs.v }}
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
      - id: msrv
        shell: bash
        run: echo "v=$(grep -m1 '^rust-version' Cargo.toml | sed -E 's/.*\"([^\"]+)\".*/\1/')" >> "$GITHUB_OUTPUT"

-  # CI owns the changelog: main may never carry a released version without a
-  # CHANGELOG.md entry for it. The release orchestrator dates an existing
-  # `## [X.Y.Z]` heading — it does NOT invent one — so a version bump that
-  # forgot its changelog entry must fail here rather than ship a blank release.
-  # Hard-fails on main (and PRs targeting main); warns elsewhere so an
-  # in-progress dev/qa branch whose entry isn't written yet is not blocked.
+  # main may never carry a released version without a CHANGELOG.md entry. Hard-
+  # fails on main (and PRs to main); warns elsewhere so an in-progress branch
+  # whose entry isn't written yet is not blocked.
  changelog:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
      - name: Require a CHANGELOG entry for the crate version on main
        shell: bash
        run: |
@@ -56,34 +50,18 @@ jobs:
          fi
          echo "::warning::${msg} (allowed on ${GITHUB_REF_NAME:-unknown}; required before it can reach main)."

+  # fmt on the pinned MSRV; clippy on stable so new-lint debt is a blocking gate
+  # the pinned version would hide. --all-targets lints test code too.
  lint:
    needs: resolve-msrv
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
        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
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
        with:
-          repository: freemkv/freemkv-unlock
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: freemkv-unlock
-      # fmt runs on the pinned MSRV toolchain; clippy runs on stable. Third
-      # parties compile our source on their own toolchain and never run our
-      # clippy, so the lint toolchain need not match the MSRV — only build/test
-      # must (see the test/cross jobs). Linting on stable makes new-lint debt a
-      # BLOCKING gate the pinned version would otherwise hide. The MSRV pin is
-      # installed second so it stays the default toolchain (fmt uses it
-      # implicitly); clippy is invoked explicitly with `+stable`.
+          checkout: freemkv-unlock
      - uses: dtolnay/rust-toolchain@stable
        with:
          components: clippy
@@ -96,13 +74,6 @@ jobs:
          workspaces: libfreemkv
      - run: cargo fmt --check
        working-directory: libfreemkv
-      # Cargo.lock is now committed (issue #15) and the `deny` job audits the
-      # resolved graph, but --locked is still omitted: CI's sibling path-patch
-      # layout resolves the freemkv crates as path packages, which --locked
-      # can't satisfy — the same reason the binary crates omit it in ci.yml.
-      # --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 +stable clippy --all-targets -- -D warnings
        working-directory: libfreemkv

@@ -110,23 +81,12 @@ jobs:
    needs: resolve-msrv
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
        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
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
        with:
-          repository: freemkv/freemkv-unlock
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: freemkv-unlock
+          checkout: freemkv-unlock
      - uses: dtolnay/rust-toolchain@master
        with:
          toolchain: ${{ needs.resolve-msrv.outputs.v }}
@@ -136,35 +96,24 @@ jobs:
      - run: cargo test --tests
        working-directory: libfreemkv

-  # The memory orderings in `scsi::fd_handoff` — the fd hand-off between a
-  # recovery thread and `SgIoTransport::drop` — cannot be checked by `cargo
-  # test`: they compile to the same instructions on x86_64, so the WRONG ones
-  # pass every run. loom enumerates the executions the C++20 model permits and
-  # reports the leaked descriptor directly, which makes it the only regression
-  # coverage that part of the module has. If this job stops running, that
-  # coverage disappears silently behind a green build.
-  #
-  # Its own job rather than a step in `test` because `RUSTFLAGS` is part of the
-  # rust-cache key: folding it into `test` costs that job a full cache miss on
-  # every run. It takes the same sibling checkout as the jobs above even though
-  # `--no-default-features` drops freemkv-unlock from the BUILD — `--features`
-  # does not exempt an optional path dependency from manifest RESOLUTION, so
-  # without the sibling this job would fail the moment the branch tip carries
-  # the path-dep form of that dependency rather than a git tag.
+  # The memory orderings in `scsi::fd_handoff` compile to the same instructions
+  # on x86_64, so the WRONG ones pass every run; loom enumerates the executions
+  # the C++20 model permits and is the only regression coverage that code has.
+  # Its own job because RUSTFLAGS is part of the rust-cache key. Takes the sibling
+  # checkout even with --no-default-features: features don't exempt an optional
+  # path dep from manifest RESOLUTION.
  loom:
    needs: resolve-msrv
    runs-on: ubuntu-latest
    env:
      RUSTFLAGS: --cfg loom
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
        with:
          path: libfreemkv
-      - uses: actions/checkout@v7
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
        with:
-          repository: freemkv/freemkv-unlock
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: freemkv-unlock
+          checkout: freemkv-unlock
      - uses: dtolnay/rust-toolchain@master
        with:
          toolchain: ${{ needs.resolve-msrv.outputs.v }}
@@ -174,7 +123,7 @@ jobs:
          workspaces: libfreemkv
      - run: cargo test --lib --no-default-features --features scsi fd_handoff
        working-directory: libfreemkv
-      # `lint` runs clippy without `--cfg loom`, so this is the only place the
+      # `lint` runs clippy without --cfg loom, so this is the only place the
      # model code is linted at all.
      - run: cargo clippy --lib --no-default-features --features scsi --profile test -- -D warnings
        working-directory: libfreemkv
@@ -182,63 +131,32 @@ jobs:
  deny:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
        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
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
        with:
-          repository: freemkv/freemkv-unlock
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: freemkv-unlock
+          checkout: freemkv-unlock
      - uses: dtolnay/rust-toolchain@stable
      - uses: EmbarkStudios/cargo-deny-action@v2
        with:
          command: check advisories bans licenses sources
          manifest-path: libfreemkv/Cargo.toml

+  # dev is the FAST lane: the platform jobs run on qa/main only (qa.yml also
+  # covers macOS/Windows). `if` SKIPS (does not queue) so a never-scheduled job
+  # can't block the release gate.
  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.
    needs: resolve-msrv
    if: github.ref_name == 'qa' || github.ref_name == 'main'
    runs-on: macos-latest
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
        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
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
        with:
-          repository: freemkv/freemkv-unlock
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: freemkv-unlock
+          checkout: freemkv-unlock
      - uses: dtolnay/rust-toolchain@master
        with:
          toolchain: ${{ needs.resolve-msrv.outputs.v }}
@@ -249,83 +167,40 @@ jobs:
        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.
    needs: resolve-msrv
    if: github.ref_name == 'qa' || github.ref_name == 'main'
    runs-on: windows-latest
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
        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
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
        with:
-          repository: freemkv/freemkv-unlock
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: freemkv-unlock
+          checkout: freemkv-unlock
      - uses: dtolnay/rust-toolchain@master
        with:
          toolchain: ${{ needs.resolve-msrv.outputs.v }}
      - 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.
+      # Build the tests: forces full codegen of the Windows-only SPTI transport
+      # (src/scsi/windows.rs), which never compiles on Linux/macOS dev hosts.
      - 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".
+  # Did this change break anything downstream? libfreemkv sits below all five
+  # dependents; a break here is worth strictly more than anywhere else. Runs
+  # their suites (not just check) — a behavioural change keeps signatures but
+  # fails a dependent's tests, which is the shape worth catching. This caught an
+  # engine fixture break the moment it landed, so it stays on the dev fast lane.
  consumers:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
        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 }
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
+        with:
+          checkout: freemkv-unlock freemkv-keysources freemkv-engine freemkv-i18n freemkv autorip bdemu
      - name: Point every dependent at THIS libfreemkv commit
        shell: bash
        run: |
@@ -339,10 +214,9 @@ jobs:
          freemkv-i18n = { path = "../freemkv-i18n" }
          EOF
          done
-      # The dependents span a higher MSRV than libfreemkv itself — the binaries
-      # (freemkv/autorip/bdemu) always track the highest supported Rust. Build
-      # them on `stable` so this job satisfies the highest dependent floor; the
-      # library's own lower MSRV (verified by the `test` job) cannot compile them.
+      # Dependents track the highest supported Rust — build on stable so this job
+      # satisfies the highest dependent floor (the library's own lower MSRV, which
+      # the `test` job verifies, cannot compile them).
      - uses: dtolnay/rust-toolchain@stable
      - uses: Swatinem/rust-cache@v2
        with:
@@ -352,10 +226,6 @@ jobs:
            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
@@ -367,29 +237,17 @@ jobs:
      - run: cargo test --tests
        working-directory: bdemu

-  # ── Coverage (non-required, additive) ───────────────────────────────────────
-  #
-  # Reports line coverage to Codecov. Deliberately NOT wired into any release
-  # gate: it is informational only (see codecov.yml) and no other job `needs:`
-  # it. Mirrors the `test` job's layout exactly — same MSRV toolchain (resolved
-  # from Cargo.toml), same dual checkout so `../freemkv-unlock` resolves, cache
-  # workspace and working-directory. cargo-llvm-cov comes as a prebuilt binary
-  # from taiki-e/install-action, so it is toolchain-independent.
-  #
-  # No `--locked`: like the fmt/clippy/test jobs above, the sibling path-patch
-  # layout resolves the freemkv crates as path packages, which --locked can't satisfy.
+  # Coverage: non-required, informational only (codecov.yml), no job needs: it.
  coverage:
    needs: resolve-msrv
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
        with:
          path: libfreemkv
-      - uses: actions/checkout@v7
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
        with:
-          repository: freemkv/freemkv-unlock
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: freemkv-unlock
+          checkout: freemkv-unlock
      - uses: dtolnay/rust-toolchain@master
        with:
          toolchain: ${{ needs.resolve-msrv.outputs.v }}
@@ -1,17 +1,12 @@
 name: comment-guard

-# Caps explanatory prose by COMMENT INTENT (not visibility):
-#   //! / /*! module docs  — unbounded (module-scoped, can't hide per-item text)
-#   ///  / /** */ item docs — 8 prose lines (fenced ``` examples excluded)
-#   //   / /* */  asides    — 3 lines (single-blank-separated runs count as one)
-# Overflow belongs in the module //! or docs/<topic>.md with a one-line // pointer.
-
+# Thin caller → the canonical reusable guard in freemkv/.github (one definition
+# for every repo). Fork PRs still run it; same-repo pushes aren't double-run.
 on: [push, pull_request]
-
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 jobs:
  comment-guard:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-      - name: Run comment-guard
-        run: python3 ci/comment-guard.py
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork
+    uses: freemkv/.github/.github/workflows/guard-comment.yml@v1
@@ -1,32 +1,17 @@
 name: doc-links

-# Fails on broken intra-doc links in `///`/`//!` doc comments (e.g. a `[Type]`
-# link to a renamed/removed item). Catches doc drift that `cargo build` misses.
-#
-# libfreemkv path-deps ../freemkv-unlock on the branch tip, so — like ci.yml —
-# both repos are checked out into sibling subdirectories for the path dep to
-# resolve.
-
+# Thin caller → the canonical reusable doc-links gate in freemkv/.github.
+# libfreemkv path-deps freemkv-unlock, so the reusable checks it out as a sibling
+# (no [patch] needed — the layout resolves the path dep) and resolves the
+# toolchain from rust-version.
 on: [push, pull_request]
-
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 jobs:
  doc-links:
-    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: dtolnay/rust-toolchain@1.98.0
-      - uses: Swatinem/rust-cache@v2
-        with:
-          workspaces: libfreemkv
-      - name: cargo doc (deny broken intra-doc links)
-        working-directory: libfreemkv
-        env:
-          RUSTDOCFLAGS: "-D rustdoc::broken_intra_doc_links"
-        run: cargo doc --no-deps --document-private-items --lib --bins
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork
+    uses: freemkv/.github/.github/workflows/guard-doclinks.yml@v1
+    with:
+      self: libfreemkv
+      checkout: freemkv-unlock
@@ -1,41 +1,14 @@
 name: identity-guard
-# Prevention: no commit may carry an unrelated-business or non-canonical author/
-# committer email. dev@example.com (a dead corp address) once slipped onto the
-# release cascade + a batch of local commits; this fails the build if it recurs.
+
+# Thin caller → the canonical reusable guard in freemkv/.github.
 on:
  push:
    branches: [dev, qa, main]
  pull_request:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 jobs:
  identity:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-        with:
-          fetch-depth: 0
-      - name: Reject banned author/committer emails
-        env:
-          BEFORE: ${{ github.event.before }}
-          AFTER: ${{ github.sha }}
-          EVENT: ${{ github.event_name }}
-          PR_BASE: ${{ github.event.pull_request.base.sha }}
-          PR_HEAD: ${{ github.event.pull_request.head.sha }}
-        run: |
-          set -euo pipefail
-          # Unrelated business domains + a personal address normalized to the
-          # GitHub noreply. Real external contributors are unaffected.
-          BANNED='@example-a\.invalid|@example-b\.invalid|owner@example\.invalid'
-          if [ "$EVENT" = "pull_request" ]; then
-            range="$PR_BASE..$PR_HEAD"
-          elif [ -n "${BEFORE:-}" ] && [ "$BEFORE" != "0000000000000000000000000000000000000000" ] && git cat-file -e "$BEFORE" 2>/dev/null; then
-            range="$BEFORE..$AFTER"
-          else
-            range="$AFTER~1..$AFTER"
-          fi
-          bad=$(git log --format='%an <%ae>%n%cn <%ce>' "$range" 2>/dev/null | sort -u | grep -iE "$BANNED" || true)
-          if [ -n "$bad" ]; then
-            echo "::error::commit(s) carry a banned author/committer identity:"; echo "$bad" | sed 's/^/  /'
-            echo "::error::Commit as your GitHub noreply (1085847+MattJackson@users.noreply.github.com). Fix: git config user.email <noreply>; git commit --amend --reset-author."
-            exit 1
-          fi
-          echo "identity-guard: clean"
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork
+    uses: freemkv/.github/.github/workflows/guard-identity.yml@v1
@@ -1,35 +1,11 @@
 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.
-
+# Thin caller → the canonical reusable guard in freemkv/.github.
 on: [push, pull_request]
-
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 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 }}"
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork
+    uses: freemkv/.github/.github/workflows/guard-leak.yml@v1
@@ -15,14 +15,18 @@ name: qa
 # 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.
+# and no hosted runner has an optical drive or the image hoard. That coverage
+# lives in freemkv's qa.yml (the real-media EC2 matrix), not in this file.
 on:
  push:
    branches: [qa]
  workflow_dispatch:

+# Rapid dev pushes supersede their own in-progress runs instead of stacking.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
  # Single source of truth for the MSRV — see ci.yml. Jobs that build/test AT
  # the MSRV read `needs.resolve-msrv.outputs.v` from Cargo.toml's rust-version;
@@ -32,7 +36,7 @@ jobs:
    outputs:
      v: ${{ steps.msrv.outputs.v }}
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
      - id: msrv
        shell: bash
        run: echo "v=$(grep -m1 '^rust-version' Cargo.toml | sed -E 's/.*\"([^\"]+)\".*/\1/')" >> "$GITHUB_OUTPUT"
@@ -56,7 +60,7 @@ jobs:
    permissions:
      contents: write
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - name: Stamp the next rc
@@ -85,14 +89,12 @@ jobs:
        os: ['ubuntu-latest', 'macos-latest']
    runs-on: ${{ matrix.os }}
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
        with:
          path: libfreemkv
-      - uses: actions/checkout@v7
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
        with:
-          repository: freemkv/freemkv-unlock
-          ref: qa
-          path: freemkv-unlock
+          checkout: freemkv-unlock
      - uses: dtolnay/rust-toolchain@master
        with:
          toolchain: ${{ needs.resolve-msrv.outputs.v }}
@@ -108,14 +110,12 @@ jobs:
  cross-lint:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
        with:
          path: libfreemkv
-      - uses: actions/checkout@v7
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
        with:
-          repository: freemkv/freemkv-unlock
-          ref: qa
-          path: freemkv-unlock
+          checkout: freemkv-unlock
      # clippy runs on stable (matches ci.yml's lint job); build/test stay on
      # the MSRV pin. See ci.yml for why the lint toolchain need not be the MSRV.
      - uses: dtolnay/rust-toolchain@stable
@@ -136,14 +136,12 @@ jobs:
    needs: resolve-msrv
    runs-on: windows-latest
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
        with:
          path: libfreemkv
-      - uses: actions/checkout@v7
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
        with:
-          repository: freemkv/freemkv-unlock
-          ref: qa
-          path: freemkv-unlock
+          checkout: freemkv-unlock
      - uses: dtolnay/rust-toolchain@master
        with:
          toolchain: ${{ needs.resolve-msrv.outputs.v }}
@@ -29,7 +29,7 @@ jobs:

  # 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 MSRV, same commit). Binary consumers
+  # gated by CI (ci.yml on dev, then a green qa.yml on the 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.
@@ -0,0 +1,27 @@
+name: Scorecard
+on:
+  branch_protection_rule:
+  schedule:
+    - cron: '22 9 * * 2'
+  push:
+    branches: ["dev"]
+permissions: read-all
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: ossf/scorecard-action@v2.4.0
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif
@@ -1,6 +1,33 @@
 # Changelog

-## [1.7.2] — 2026-09-18
+## [1.7.5] — 2026-09-23
+
+### Changed
+
+- Version aligned to 1.7.5 for the unified release. No functional changes to this crate; the release is driven by freemkv-unlock mirroring the freemkv-firmware 0.9.0 ABI (the drive's `Ake` and `Bus` levers retired into a single `Encryption` lever).
+
+## [1.7.4] — 2026-09-21
+### Fixed
+
+- BD-J / Java-menu main-title selection reworked (#45): a chapter-completeness failsafe, a BD-J menu-walk (parses the BDJO objects and jar manifests), and a stream-richness tiebreak now cooperate so discs driven by a Java menu pick the real main feature — keeping the Dolby Vision enhancement layer and all subtitle tracks — instead of a lower-id sibling playlist.
+- PGS subtitles now get a synthesized `BlockDuration` on every block, fixing ffmpeg's "Timestamps are unset" mux error, plus a defensive HEVC NAL length-prefix guard (#52).
+- keydb "no entry" is de-conflated into a true miss versus matched-but-no-usable-VID, and the disc hash is surfaced; adds `KeyStep.matched_entry` and `KeyStep.store_entries` (#46).
+
+### Maintenance
+
+- CI moved to the central reusable workflows.
+
+## [1.7.3] — 2026-09-19
+
+### Fixed
+
+- MPLS title enumeration: the STN (stream number) table of the first PlayItem is now located past the multi-angle *angle block* instead of at the fixed offset 32. A multi-angle first PlayItem (e.g. a seamless-branch UHD title) carries `number_of_angles` extra 10-byte angle entries before the STN table, so the old fixed offset read the wrong bytes and misparsed the primary title's streams — the root cause behind autorip/CLI picking the wrong (or no) main feature on some UHD discs. Validated against a 92-disc real-media corpus with zero regressions (issue #45).
+
+### Added
+
+- `disc::read_structure_files()` — captures a disc's **structure metadata** (`BDMV/index.bdmv`, `MovieObject.bdmv`, `PLAYLIST/*.mpls`, `CLIPINF/*.clpi`, `BDJO/*.bdjo`, `META/DL/*.xml`, DVD `VIDEO_TS/*.IFO`) over any `SectorSource` (drive, ISO, `dir://`). No audio/video essence and no AACS keys are read, so the result is safe to attach to a bug report (a few hundred KB). Powers `freemkv info … --share` so a reporter can reproduce a title-selection issue without shipping the full ISO.
+
+## [1.7.2] — UNRELEASED

 ### Fixed

@@ -221,7 +221,7 @@ dependencies = [

 [[package]]
 name = "freemkv-unlock"
-version = "1.7.1"
+version = "1.7.4"
 dependencies = [
 "aes",
 "base64",
@@ -317,7 +317,7 @@ checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"

 [[package]]
 name = "libfreemkv"
-version = "1.7.1"
+version = "1.7.4"
 dependencies = [
 "aes",
 "base64",
@@ -839,12 +839,12 @@ dependencies = [

 [[patch.unused]]
 name = "freemkv-engine"
-version = "1.7.1"
+version = "1.7.4"

 [[patch.unused]]
 name = "freemkv-i18n"
-version = "1.7.1"
+version = "1.7.4"

 [[patch.unused]]
 name = "freemkv-keysources"
-version = "1.7.1"
+version = "1.7.4"
@@ -1,6 +1,6 @@
 [package]
 name = "libfreemkv"
-version = "1.7.2"
+version = "1.7.5"
 edition = "2024"
 rust-version = "1.88"
 license = "MIT"
@@ -59,7 +59,7 @@ aes = { version = "0.9", optional = true }
 # this to `{ git = ".../freemkv-unlock", tag = "vX.Y.Z" }` in the tagged commit
 # (so the released tag resolves freemkv-unlock from git, not a sibling path) and
 # restores the path dep on the branch tip.
-freemkv-unlock = { git = "https://github.com/freemkv/freemkv-unlock", tag = "v1.7.2", optional = true }
+freemkv-unlock = { git = "https://github.com/freemkv/freemkv-unlock", tag = "v1.7.5", optional = true }
 zip = { version = "8", default-features = false, features = ["deflate"], optional = true }
 base64 = { version = "0.23", optional = true }
 # Read-only XML DOM parser (pure Rust, forbid(unsafe_code), entity-expansion
@@ -3,6 +3,10 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 [![CI](https://github.com/freemkv/libfreemkv/actions/workflows/ci.yml/badge.svg)](https://github.com/freemkv/libfreemkv/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/freemkv/libfreemkv/branch/dev/graph/badge.svg)](https://codecov.io/gh/freemkv/libfreemkv)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/freemkv/libfreemkv/badge)](https://scorecard.dev/viewer/?uri=github.com/freemkv/libfreemkv)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14745/badge)](https://www.bestpractices.dev/projects/14745)
+[![REUSE status](https://api.reuse.software/badge/github.com/freemkv/libfreemkv)](https://api.reuse.software/info/github.com/freemkv/libfreemkv)
+[![MSRV](https://img.shields.io/badge/MSRV-1.88-blue.svg)](#minimum-supported-rust-version)

 # libfreemkv

@@ -14,7 +18,7 @@ DVDs (CSS) decrypt out of the box. Blu-ray and UHD (AACS) require disc-specific

 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/)**
+**[Source & API](https://github.com/freemkv/libfreemkv)** · **[Technical Docs](docs/)** · **[Changelog](CHANGELOG.md)**

 Part of the [freemkv](https://github.com/freemkv) project.

@@ -157,6 +161,29 @@ All errors are structured with numeric codes. No user-facing English text — ap

 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.

+## What this is NOT
+
+To keep expectations honest:
+
+- **No bundled AACS or CSS keys.** No AACS key material is compiled into the
+  crate. Blu-ray/UHD unit keys are supplied by the consumer at runtime (e.g. via
+  [freemkv-keysources](https://github.com/freemkv/freemkv-keysources)'s
+  `keydb.cfg` lookup); libfreemkv never reads `keydb.cfg` or downloads keys.
+- **Not published to crates.io.** The crate is `publish = false`. It is consumed
+  by git tag or path only (see [Install](#install)) — there is no crates.io
+  version, docs.rs page, or download count.
+- **No independent security audit.** No external or third-party security audit
+  has been performed. [SECURITY.md](SECURITY.md) is an assurance case authored by
+  the project, not an attestation by an outside auditor.
+- **CSS is legacy, weak crypto.** DVD CSS is handled solely for format
+  interoperability with existing discs. It is a broken cipher by modern
+  standards and is not, and should not be treated as, a security mechanism.
+
+## Minimum Supported Rust Version
+
+The minimum supported Rust version (MSRV) is **1.88**, declared as
+`rust-version` in [`Cargo.toml`](Cargo.toml) and enforced in CI on every change.
+
 ## License

 MIT
@@ -0,0 +1,41 @@
+version = 1
+
+# REUSE (https://reuse.software) machine-readable licensing for the whole repo.
+#
+# Licensing is declared here in the manifest rather than as per-file inline
+# headers: the project's comment-guard lint caps stacked `//` comment blocks, so
+# a two-line SPDX header prepended above an existing top-of-file comment would
+# trip it. REUSE explicitly supports manifest-based annotation, so every file —
+# Rust sources, documentation, configuration, workflows, scripts, binary assets,
+# and the byte-exact `.golden` test fixtures — is covered here instead.
+#
+# The whole repository is the project's own work under the MIT licence; there is
+# no third-party vendored source here.
+
+[[annotations]]
+path = [
+    "**/*.rs",
+    "**/*.md",
+    "**/*.toml",
+    "**/*.lock",
+    "**/*.yml",
+    "**/*.yaml",
+    "**/*.json",
+    "**/*.sh",
+    "**/*.py",
+    "**/*.ps1",
+    "**/*.golden",
+    "**/*.svg",
+    "**/*.png",
+    "**/*.ico",
+    "**/*.plist",
+    "**/*.manifest",
+    "**/.gitignore",
+    ".gitignore",
+    "Makefile",
+    "LICENSE",
+    "build.rs",
+]
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2026 Matthew Jackson & Contributors"
+SPDX-License-Identifier = "MIT"
@@ -1,252 +0,0 @@
-#!/usr/bin/env python3
-"""comment-guard: cap explanatory prose by COMMENT INTENT, not visibility.
-
-Three tiers, keyed on the syntax the author reached for:
-
-  * `//!` / `/*!` — a module (or crate) design doc. UNBOUNDED. There is one per
-    file, at the top, documenting the module as a whole, so it can't be used to
-    smuggle per-item rationale the way item docs can. Long correctness / design
-    essays (e.g. a memory-ordering proof) legitimately live here.
-  * `///` / `/** */` — item documentation. Up to DOC_CAP *prose* lines. Fenced
-    ``` code blocks do NOT count, so real examples aren't punished. This holds
-    whether or not the item is `pub`: a `pub(crate)` fn deserves a real doc
-    paragraph just like a `pub` one. Capping `///` here (rather than exempting
-    it, as the old guard did — issue #17) is what stops rationale being hidden
-    behind a doc sigil, while still leaving room for a genuine paragraph.
-  * `//` / `/* */` — a quick internal aside. Up to INLINE_CAP lines. This is the
-    shape that sprawls into walls, so it's kept tight: stanzas separated by a
-    single blank line count CUMULATIVELY, so one essay can't be split into runs.
-
-Overflow belongs in the module `//!`, or in docs/<topic>.md with a one-line `//`
-pointer — both show up in review.
-
-Scans src/ and tests/ under the given root (default cwd). `--selftest` runs
-built-in cases. Exit non-zero if any block exceeds its cap.
-"""
-import re
-import sys
-from pathlib import Path
-
-INLINE_CAP = 3
-DOC_CAP = 8
-
-_RAW_OPEN = re.compile(r'r(#*)"')  # raw string opener: r"…", r#"…"#, br##"…"## …
-
-
-def _strip_line_comment(s):
-    """Return (kind, body) for a whole-line comment, else (None, None).
-
-    kind is 'doc' for `///`/`//!`, 'plain' for other `//`. A trailing comment on
-    a code line is not a whole-line comment and is ignored (single-line, cheap).
-    """
-    if s.startswith("//!"):
-        return "doc", s[3:]
-    if s.startswith("///") and not s.startswith("////"):
-        return "doc", s[3:]
-    if s.startswith("//"):
-        return "plain", s[2:]
-    return None, None
-
-
-def _fence_toggle(body):
-    """True if this doc body line opens/closes a ``` fenced code block."""
-    return body.strip().startswith("```")
-
-
-def _classify(lines):
-    """Yield per-line dicts: comment kind ('doc'/'plain'/None), doc-ness of
-    block comments, and code info. Block comments are tracked across lines.
-    """
-    info = []
-    in_block = False
-    block_is_doc = False
-    raw_hashes = None  # None = not in a raw string; int N = open, needs '"' + N*'#'
-    for raw in lines:
-        s = raw.lstrip()
-        rec = {"raw": raw, "s": s, "comment": None, "is_doc": False, "code": False}
-        # Inside a raw string literal (e.g. an embedded HTML/CSS/JS asset): the
-        # bytes are string data, not Rust comments, so the guard is blind to them
-        # until the string closes. Prevents `/* */` or `//` lines in an embedded
-        # page from being counted as comment blocks.
-        if raw_hashes is not None:
-            if ('"' + "#" * raw_hashes) in raw:
-                raw_hashes = None
-            info.append(rec)
-            continue
-        if in_block:
-            rec["comment"] = "doc" if block_is_doc else "plain"
-            rec["is_doc"] = block_is_doc
-            if "*/" in raw:
-                in_block = False
-            info.append(rec)
-            continue
-        # A block comment only starts a comment-line if it's the first token.
-        if s.startswith("/*"):
-            rec["is_doc"] = s.startswith("/**") or s.startswith("/*!")
-            rec["comment"] = "doc" if rec["is_doc"] else "plain"
-            if "*/" not in s[2:]:
-                in_block = True
-                block_is_doc = rec["is_doc"]
-            info.append(rec)
-            continue
-        kind, _ = _strip_line_comment(s)
-        if kind is not None:
-            rec["comment"] = kind
-            rec["is_doc"] = kind == "doc"
-            info.append(rec)
-            continue
-        # Code (or blank). Blank = empty after strip.
-        rec["code"] = s != ""
-        # A code line may OPEN a raw string that spans following lines. Detected
-        # only on code (comments were handled above), so `// see r"x"` is safe.
-        m = _RAW_OPEN.search(raw)
-        if m and ('"' + "#" * len(m.group(1))) not in raw[m.end():]:
-            raw_hashes = len(m.group(1))
-        info.append(rec)
-    return info
-
-
-def violations(path):
-    lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
-    info = _classify(lines)
-    n = len(info)
-    out = []
-
-    i = 0
-    while i < n:
-        rec = info[i]
-        if rec["comment"] is None:
-            i += 1
-            continue
-
-        start = i
-        if rec["is_doc"]:
-            # Doc run: contiguous doc lines. `//!` / `/*!` module docs are
-            # UNBOUNDED; any other doc run caps PROSE (fenced ``` excluded) at
-            # DOC_CAP, regardless of the documented item's visibility.
-            j = i
-            prose = 0
-            in_fence = False
-            module_doc = False
-            while j < n and info[j]["comment"] == "doc":
-                s = info[j]["s"]
-                if s.startswith("//!") or s.startswith("/*!"):
-                    module_doc = True
-                body = (
-                    s[3:] if (s.startswith("///") or s.startswith("//!")) else s
-                )
-                if _fence_toggle(body):
-                    in_fence = not in_fence
-                elif not in_fence and body.strip() != "":
-                    prose += 1
-                j += 1
-            if not module_doc and prose > DOC_CAP:
-                out.append((start + 1, prose, DOC_CAP, "doc prose"))
-            i = j
-            continue
-
-        # Internal (plain) run, with single-blank bridging (cumulative).
-        j = i
-        count = 0
-        while j < n:
-            r = info[j]
-            if r["comment"] == "plain":
-                count += 1
-                j += 1
-                continue
-            if r["comment"] == "doc":
-                break
-            if r["comment"] is None and not r["code"]:
-                # blank: bridge only a SINGLE blank, else stop
-                if j + 1 < n and info[j + 1]["comment"] == "plain":
-                    j += 1
-                    continue
-                break
-            break  # code
-        if count > INLINE_CAP:
-            out.append((start + 1, count, INLINE_CAP, "inline comment"))
-        i = j
-    return out
-
-
-def main(argv):
-    if "--selftest" in argv:
-        return _selftest()
-    root = Path(argv[1]) if len(argv) > 1 else Path.cwd()
-    files = sorted(p for d in ("src", "tests") for p in (root / d).rglob("*.rs"))
-    total = 0
-    for f in files:
-        for start, length, cap, kind in violations(f):
-            rel = f.relative_to(root)
-            print(f"{rel}:{start}: {kind} block is {length} lines (max {cap})")
-            total += 1
-    if total:
-        print(f"\ncomment-guard: {total} comment block(s) exceed their cap.")
-        print(
-            f"Inline // asides cap at {INLINE_CAP}; /// item-doc prose caps at "
-            f"{DOC_CAP} (fenced examples excluded); //! module docs are unbounded. "
-            "Trim, move the rationale into the module //!, or docs/<topic>.md "
-            "with a // pointer."
-        )
-        return 1
-    return 0
-
-
-def _selftest():
-    import tempfile
-
-    cases = [
-        # (rust source, expected number of violations)
-        # short /// doc -> ok
-        ("/// short doc\npub fn a() {}\n", 0),
-        # /// on a PRIVATE item now gets the doc cap (8), so 4 lines is fine
-        ("/// l1\n/// l2\n/// l3\n/// l4\nfn priv_a() {}\n", 0),
-        # ...but /// is NOT unlimited: 9 prose lines on a private item fails
-        ("".join(f"/// l{k}\n" for k in range(9)) + "fn priv_b() {}\n", 1),
-        # 8 prose /// on a pub item -> ok (boundary)
-        ("".join(f"/// l{k}\n" for k in range(8)) + "pub fn c() {}\n", 0),
-        # 9 prose /// on a pub item -> violation
-        ("".join(f"/// l{k}\n" for k in range(9)) + "pub fn d() {}\n", 1),
-        # /// with a long fenced example -> example excluded, ok
-        (
-            "/// summary\n/// # Examples\n/// ```\n"
-            + "".join("/// code\n" for _ in range(12))
-            + "/// ```\npub fn e() {}\n",
-            0,
-        ),
-        # pub(crate) gets the SAME doc cap as pub (no pub/private split anymore)
-        ("".join(f"/// l{k}\n" for k in range(6)) + "pub(crate) fn f() {}\n", 0),
-        # bare inline 4 lines -> violation
-        ("// a\n// b\n// c\n// d\nlet x = 1;\n", 1),
-        # blank-split dodge: 3 + blank + 3 inline -> cumulative -> violation
-        ("// a\n// b\n// c\n\n// d\n// e\n// f\nfn z() {}\n", 1),
-        # plain /* */ block, 5 lines -> inline cap -> violation
-        ("/* one\n two\n three\n four\n five */\nfn q() {}\n", 1),
-        # comment-like lines INSIDE a raw string are string data, not comments
-        (
-            'const H: &str = r##"<style>\n'
-            + "".join("/* css note */\n" for _ in range(8))
-            + '</style>"##;\nfn h() {}\n',
-            0,
-        ),
-        # //! module doc may run long -> EXEMPT (no cap)
-        ("".join(f"//! l{k}\n" for k in range(40)) + "\npub fn m() {}\n", 0),
-        # /*! block module doc may run long -> EXEMPT
-        ("/*! l0\n" + "".join(f" l{k}\n" for k in range(30)) + "*/\nfn n() {}\n", 0),
-    ]
-    ok = True
-    with tempfile.TemporaryDirectory() as d:
-        for idx, (src, want) in enumerate(cases):
-            p = Path(d) / f"case{idx}.rs"
-            p.write_text(src)
-            got = len(violations(p))
-            flag = "ok" if got == want else "FAIL"
-            if got != want:
-                ok = False
-            print(f"  selftest {idx}: want {want} got {got} [{flag}]")
-    print("selftest PASSED" if ok else "selftest FAILED")
-    return 0 if ok else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main(sys.argv))
@@ -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"
@@ -12,3 +12,33 @@ unlock phase, then the key-resolution phase).
  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.
+
+## `KeyStep` — a source's contribution to the key phase
+
+Each source that ran contributes one `KeyStep`: `who` (its `label()`), `path`
+(the `Vec<KeyNode>` it walked), and `outcome` (`KeyOutcome`). Two fields
+de-conflate a keyless result — WHY a matched disc produced no usable key:
+
+- `matched_entry: Option<MatchedEntry>` — the shape of the source's MATCHED
+  entry when it matched this disc; `None` for a true miss or a source kind
+  with no such shape. An app MAY log it verbatim and render a
+  matched-but-no-key verdict.
+- `store_entries: Option<usize>` — per-disc entries loaded in the source's
+  store, when known, so a true-miss verdict can name the store size (`… not in
+  keydb (N entries loaded)`). `None` for a source that carries no such count.
+
+## `MatchedEntry` — booleans-and-lengths, never material
+
+A shape summary of a matched entry — safe to print at any log level, no key
+MATERIAL: `has_vuk`, `has_unit_keys`, `unit_keys_len`, `has_media_key`,
+`has_keydb_vid`, `enc_title_keys_len`, `vid_available`. It answers "the disc
+WAS found — so why no key?" (e.g. a Media Key present but no VID on this path).
+
+## `KeyNode::NoDerivableKey`
+
+A derivation-path node distinct from `NoEntry`: the source MATCHED this disc
+but could not derive any usable key from the matched entry (no derivation
+material for the path taken). `NoEntry` = the disc was not found at all;
+`NoDerivableKey` = found, but the key was not — the node that turns a flat
+`no entry` verdict into `matched disc > … > NO KEY`. See docs/keysource.md
+(`resolve_unit_keys`) for how a source populates it.
@@ -217,10 +217,40 @@ authoring an entire synthetic disc image. Running it against an HD-DVD/DVD

 This catches both the wrapper decoy (`00245 ⊋ 00001`) and the oversize
 play-all — independent of capacity, which the `fits-disc` gate needs and
-which is `0`/unknown on drives that fail READ CAPACITY. The corpus
-title-selection gate is the backstop across the disc hoard for the known
-residual (a real feature with a separate "resume from the middle" branch
-playlist reusing most of its clips).
+which is `0`/unknown on drives that fail READ CAPACITY.
+
+### Wrapper-shape gate (issue #45)
+
+A proper-subset relation with `Q.size ≥ 0.5·P.size` is NOT by itself proof
+that `P` is a wrapper. A genuine **seamless-branch feature** `P` (body clip
+plus intro/credits/alternate-branch segments) is a *superset* of its
+single-clip body decoy `Q`: `Q` runs almost as long as `P` (e.g. 1h50 vs
+2h03, ~0.89 of the duration) yet is markedly smaller, because `P`'s branch
+segments add bytes without adding much played runtime. The old size-only
+gate mis-flagged such a `P` as a "play-all wrapper" and demoted the real
+2h03 feature below the shorter 1h50 body — a SAFETY bug (wrong title ripped).
+
+So the composite flag additionally requires `P` to *have* a wrapper shape,
+via one of two capacity-independent, per-title (`duration_secs`, `size_bytes`)
+signals on the subset `Q`:
+
+- **concat / play-all:** `Q.duration < 0.85·P.duration` — `Q` is a much
+  shorter cut and `P` pads its runtime with other segments (the true
+  play-all runs ~the SUM of its parts, so each part is well under half).
+- **bumper / outro wrapper:** `Q.size ≥ 0.90·P.size` — `Q` already holds
+  almost all of `P`'s bytes and `P` merely prepends/appends a short
+  non-feature lead/tail (the `00245 ⊋ 00001` decoy: `Q` is ~0.96 of both the
+  duration and the size, so the size limb keeps it demoted).
+
+Otherwise — `Q` runs almost as long as `P` (≥0.85) yet is well under 0.90 of
+its size — `P` is the fuller branch set and is kept. `0.85` sits above a real
+concat's per-part ratio (~0.5) and below a seamless body's (~0.89); `0.90`
+sits above a bumper wrapper's near-1.0 size share and below a branch body's.
+
+**Known residual:** a wrapper that pads runtime only modestly AND withholds
+most of its bytes from the body clip is ambiguous by shape alone. The corpus
+title-selection gate is the backstop across the disc hoard, and
+higher-precedence nav/authoring signals override the composite key.

 ## aligned_unit_keys_validate

@@ -111,6 +111,24 @@ streaming decode self-healing. Re-sending an identical param set is benign
 This strictly supersets the earlier change-only re-assert, so the
 param-set-revert fix is unaffected.

+## length-prefix self-check (issue #52)
+
+`length_prefix_tiles` walks the assembled `frame_data` ([u32-BE len][body]
+records) and confirms they EXACTLY tile it: every declared length fits, none is
+zero, and the last body ends precisely at the buffer end with no trailing
+bytes. `frame_data` is length-prefixed by construction (`push_length_prefixed`
+/ `handle_param_set` write a 4-byte BE prefix — `LENGTH_PREFIX_SIZE`, which MUST
+equal the hvcC `lengthSizeMinusOne + 1`), so a `false` means a framing desync a
+downstream demuxer would report as "Invalid NAL unit size (N>M)".
+
+`HevcParser::parse` runs this as defense in depth: if the self-check fails it
+logs `src` at WARN and DROPS the access unit (`return Vec::new()`) rather than
+emit a mis-framed frame. Because no real input can desync a
+built-by-construction buffer, the drop branch is exercised end-to-end via a
+test-only seam (`FORCE_FRAMING_DESYNC`) that appends a stray byte just before
+the guard; see `parse_drops_desynced_access_unit`. Disconnecting the guard from
+`parse` fails that test.
+
 ## `parse_mastering_display`

 Parses a Mastering Display Colour Volume SEI payload (Rec. ITU-T H.265
@@ -99,6 +99,32 @@ on `disc_hash` and reads no samples; the online source submits the ctx's
 content samples (a base batch for `get_unit_keys`, an index-1 anchor batch
 for `get_fmts_indexes`) to the key service.

+## `resolve_unit_keys` — de-conflating "no entry" from "matched, no key"
+
+`get_unit_keys` returns a bare `Vec<UnitKey>`: an empty result cannot say
+WHETHER the source had no entry for this disc at all, or matched the disc and
+still derived nothing (the classic "matched but needs a VID this path can't
+supply"). `resolve_unit_keys` carries that distinction. It returns a
+`UnitKeyResolution`:
+
+* `keys: Vec<UnitKey>` — the terminal Unit Keys produced (empty = none).
+* `matched: bool` — the source matched this disc in its store (by hash / VID)
+  even if it then derived no key; `false` is a genuine miss.
+* `miss_path: Vec<KeyNode>` — when `matched` and `keys` is empty, the nodes
+  walked AFTER the implicit `MatchedDisc` node (e.g. `[NoVid]` or
+  `[NoDerivableKey]`); empty means the caller supplies a bare
+  `NoDerivableKey`. Ignored unless `matched` and `keys` is empty.
+* `matched_entry: Option<MatchedEntry>` — a booleans-and-lengths shape of the
+  matched entry (no key material) for the application to log.
+* `store_entries: Option<usize>` — per-disc entries loaded in this source's
+  store, so a true-miss verdict can name the store size.
+
+The trait's default is coarse: forward to `get_unit_keys` and report
+`matched = false`. A source that keys on a per-disc identity (a keydb)
+overrides it to set `matched` / `miss_path` / `matched_entry`, so the trace can
+render `matched disc > no VID > NO KEY` instead of a flat `no entry`. See
+docs/aacs-trace.md for the trace-node shapes.
+
 ## `resolve_and_apply_traced` — one-shot semantics and CPS-unit numbering

 One-shot per source: each source's `KeySource::get_unit_keys` is called
@@ -0,0 +1,179 @@
+// Corpus title-shape dump for issue #45 fallback tuning.
+//
+// Runs the REAL offline scan (Disc::scan_image → sort_titles_by_main_feature)
+// over a directory of decrypted ISOs and emits one NDJSON line per disc:
+// every title's duration/size/clip-shape plus the rank flags the selector
+// computed (nav/authoring/composite) and which title it picked (titles[0]).
+//
+// The point: measure, across many real discs, how cleanly any candidate
+// discriminator separates the true main feature from play-all wrappers and
+// seamless-branch decoys — so the #45 fallback is derived from data, not a
+// guessed 0.85/0.90 constant.
+//
+// Usage: corpus_titledump <iso_dir> [<iso_dir>...]  > corpus.ndjson
+
+use libfreemkv::disc::{Disc, ScanOptions};
+use libfreemkv::io::file_sector_source::FileSectorSource;
+use libfreemkv::sector::SectorSource;
+use std::path::{Path, PathBuf};
+
+// scan_image wants the disc capacity in sectors; FileSectorSource knows it.
+
+fn jstr(s: &str) -> String {
+    let mut o = String::with_capacity(s.len() + 2);
+    o.push('"');
+    for c in s.chars() {
+        match c {
+            '"' => o.push_str("\\\""),
+            '\\' => o.push_str("\\\\"),
+            '\n' => o.push_str("\\n"),
+            '\r' => o.push_str("\\r"),
+            '\t' => o.push_str("\\t"),
+            c if (c as u32) < 0x20 => o.push_str(&format!("\\u{:04x}", c as u32)),
+            c => o.push(c),
+        }
+    }
+    o.push('"');
+    o
+}
+
+fn dump_one(path: &Path) -> String {
+    let name = path.file_name().and_then(|s| s.to_str()).unwrap_or("?");
+    let mut reader = match FileSectorSource::open(path) {
+        Ok(r) => r,
+        Err(e) => {
+            return format!(
+                "{{\"iso\":{},\"error\":\"open: {:?}\"}}",
+                jstr(name),
+                format!("{e}")
+            );
+        }
+    };
+    let cap = reader.capacity_sectors();
+    let opts = ScanOptions::default();
+    let disc = match Disc::scan_image(&mut reader, cap, &opts) {
+        Ok(d) => d,
+        Err(e) => {
+            return format!(
+                "{{\"iso\":{},\"error\":\"scan: {}\"}}",
+                jstr(name),
+                jstr(&format!("{e}"))
+            );
+        }
+    };
+
+    // Recompute the rank flags the selector used so we can see WHY it ordered
+    // things the way it did. nav/authoring hint aren't available offline here
+    // (scan_with already applied them into titles[0]); pass None/None so the
+    // flags reflect the pure composite/video/size classification, which is the
+    // fallback we are tuning.
+    let ranks = Disc::rank_titles(&disc.titles, None, None);
+
+    // pick = titles[0] (post-sort main feature). Also compute the naive
+    // "longest video title" as a ground-truth proxy for single-movie discs.
+    let pick_pl = disc.titles.first().map(|t| t.playlist_id).unwrap_or(0);
+    let longest_video_pl = disc
+        .titles
+        .iter()
+        .filter(|t| t.has_probable_video())
+        .max_by(|a, b| a.duration_secs.partial_cmp(&b.duration_secs).unwrap())
+        .map(|t| t.playlist_id);
+
+    let mut titles_json = String::from("[");
+    for (i, t) in disc.titles.iter().enumerate() {
+        if i > 0 {
+            titles_json.push(',');
+        }
+        let r = &ranks[i];
+        // Sum of the FULL durations of this title's distinct clips (each clip
+        // counted once at its clip-level duration). A play-all concat wrapper's
+        // title duration ≈ this sum; a seamless-branch feature's is dominated by
+        // one clip. This is the structural discriminator to evaluate.
+        let mut seen = std::collections::BTreeMap::<&str, f64>::new();
+        for c in &t.clips {
+            seen.entry(c.clip_id.as_str()).or_insert(c.duration_secs);
+        }
+        let sum_distinct_clip_dur: f64 = seen.values().sum();
+        let max_distinct_clip_dur: f64 = seen.values().cloned().fold(0.0, f64::max);
+        let n_distinct_clips = seen.len();
+        let clip_ids: String = {
+            let mut s = String::from("[");
+            for (k, id) in seen.keys().enumerate() {
+                if k > 0 {
+                    s.push(',');
+                }
+                s.push_str(&jstr(id));
+            }
+            s.push(']');
+            s
+        };
+        titles_json.push_str(&format!(
+            "{{\"pl\":{},\"dur\":{:.1},\"size\":{},\"clips\":{},\"distinct_clips\":{},\
+             \"sum_distinct_clip_dur\":{:.1},\"max_distinct_clip_dur\":{:.1},\
+             \"has_video\":{},\"has_probable_video\":{},\
+             \"nav\":{},\"authoring\":{},\"composite\":{},\"clip_ids\":{}}}",
+            t.playlist_id,
+            t.duration_secs,
+            t.size_bytes,
+            t.clips.len(),
+            n_distinct_clips,
+            sum_distinct_clip_dur,
+            max_distinct_clip_dur,
+            t.has_video(),
+            t.has_probable_video(),
+            r.nav,
+            r.authoring,
+            r.composite,
+            clip_ids,
+        ));
+    }
+    titles_json.push(']');
+
+    format!(
+        "{{\"iso\":{},\"format\":\"{:?}\",\"cap\":{},\"n_titles\":{},\
+         \"pick_pl\":{},\"longest_video_pl\":{},\"pick_is_longest_video\":{},\"titles\":{}}}",
+        jstr(name),
+        disc.format,
+        cap,
+        disc.titles.len(),
+        pick_pl,
+        longest_video_pl
+            .map(|p| p.to_string())
+            .unwrap_or_else(|| "null".into()),
+        longest_video_pl.map(|p| p == pick_pl).unwrap_or(false),
+        titles_json,
+    )
+}
+
+fn main() {
+    let dirs: Vec<PathBuf> = std::env::args().skip(1).map(PathBuf::from).collect();
+    if dirs.is_empty() {
+        eprintln!("usage: corpus_titledump <iso_dir> [<iso_dir>...]");
+        std::process::exit(2);
+    }
+    let mut isos: Vec<PathBuf> = Vec::new();
+    for d in &dirs {
+        if d.is_file() {
+            isos.push(d.clone());
+            continue;
+        }
+        if let Ok(rd) = std::fs::read_dir(d) {
+            for e in rd.flatten() {
+                let p = e.path();
+                if p.extension()
+                    .and_then(|s| s.to_str())
+                    .map(|s| s.eq_ignore_ascii_case("iso"))
+                    .unwrap_or(false)
+                {
+                    isos.push(p);
+                }
+            }
+        }
+    }
+    isos.sort();
+    eprintln!("scanning {} ISOs", isos.len());
+    for (i, p) in isos.iter().enumerate() {
+        eprintln!("[{}/{}] {}", i + 1, isos.len(), p.display());
+        println!("{}", dump_one(p));
+    }
+}
@@ -280,6 +280,52 @@ pub fn decrypt_bus(unit: &mut [u8], read_data_key: &[u8; 16]) {
    }
 }

+/// Remove bus encryption across a sector-aligned `buf`, gated to the disc's
+/// encrypted-content ranges. `base_lba` is the LBA of `buf`'s first 2048-byte
+/// sector (sector `i` = `base_lba + i`). A sector is de-bussed only when `ranges`
+/// is `None` (content-only caller) or its LBA falls inside a sorted
+/// `(start_lba, sector_count)` range — a clear UDF/nav sector outside content is
+/// left untouched (de-bussing it would corrupt plaintext). Key schedule expanded
+/// once. Single de-bus entry point (see the `sector::bus_removal` module doc).
+pub(crate) fn decrypt_bus_in_content(
+    buf: &mut [u8],
+    read_data_key: &[u8; 16],
+    base_lba: u32,
+    ranges: Option<&[(u32, u32)]>,
+) {
+    debug_assert!(
+        ranges.is_none_or(|rs| rs.windows(2).all(|w| w[0].0 <= w[1].0)),
+        "content ranges must be sorted ascending by start LBA for the binary search"
+    );
+    let in_content = |lba: u32| -> bool {
+        match ranges {
+            None => true,
+            // `rs` is sorted ascending by start and non-overlapping (merged
+            // extents), so binary-search the last range with start <= lba and
+            // test containment — O(log n) per sector, not O(ranges).
+            Some(rs) => {
+                let i = rs.partition_point(|&(start, _)| start <= lba);
+                i > 0 && {
+                    let (start, cnt) = rs[i - 1];
+                    (lba as u64) < start as u64 + cnt as u64
+                }
+            }
+        }
+    };
+    let cipher = crate::aacs::crypto::new_cipher_for(read_data_key);
+    for (i, sector) in buf.chunks_mut(SECTOR_BYTES).enumerate() {
+        if sector.len() < SECTOR_BYTES {
+            break; // trailing partial sector (never on a whole-sector read)
+        }
+        let lba = base_lba.saturating_add(i as u32);
+        if !in_content(lba) {
+            continue;
+        }
+        // First 16 bytes of each sector are plaintext on the wire.
+        crate::aacs::crypto::cbc_decrypt_blocks(&cipher, &mut sector[16..SECTOR_BYTES]);
+    }
+}
+
 /// Test-only exact inverse of [`decrypt_bus`]: apply AACS 2.0 bus ENCRYPTION to
 /// an aligned unit in place — per-sector AES-CBC-encrypt bytes 16..2048 of each
 /// 2048-byte sector under `read_data_key`, leaving the first 16 bytes of every
@@ -61,6 +61,41 @@ pub struct KeyStep {
    pub who: String,
    pub path: Vec<KeyNode>,
    pub outcome: KeyOutcome,
+    /// Shape of the source's MATCHED entry, when it matched this disc — a
+    /// booleans-and-lengths summary (no key material) that de-conflates WHY a
+    /// matched disc produced no key. `None` when the source did not match (a
+    /// true miss) or the source kind carries no such shape. An application MAY
+    /// log it verbatim and render it into a matched-but-no-key verdict.
+    pub matched_entry: Option<MatchedEntry>,
+    /// Number of per-disc entries loaded in the source's store, when known — so
+    /// a true-miss verdict can name the store size (`… not in keydb (N entries
+    /// loaded)`) and a reporter can confirm a wrong-pressing at a glance.
+    /// `None` for a source that carries no such count. No secret.
+    pub store_entries: Option<usize>,
+}
+
+/// A shape summary of a key source's MATCHED entry — booleans and lengths only,
+/// never key MATERIAL — so an application can log WHY a disc that WAS found in
+/// the store still produced no usable key (the classic "matched but needs a VID
+/// this path can't supply"). Every field is safe to print at any log level.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub struct MatchedEntry {
+    /// The entry carries a Volume Unique Key (title keys can boil directly).
+    pub has_vuk: bool,
+    /// The entry carries one or more pre-decrypted terminal Unit Keys.
+    pub has_unit_keys: bool,
+    /// Count of pre-decrypted terminal Unit Keys the entry carries.
+    pub unit_keys_len: usize,
+    /// The entry carries a Media Key (a VID is still needed to reach the VUK).
+    pub has_media_key: bool,
+    /// The entry carries its own Volume ID (the keydb `I` token).
+    pub has_keydb_vid: bool,
+    /// Count of the disc's encrypted title keys available to boil (from
+    /// `Unit_Key_RO.inf`); `0` when none were captured.
+    pub enc_title_keys_len: usize,
+    /// A Volume ID is available on this resolve path (from the drive handshake
+    /// or the entry) — the gate the `MK → VUK` step needs.
+    pub vid_available: bool,
 }

 /// A node on the derivation path a source walked. Ordered as encountered; not
@@ -71,6 +106,10 @@ pub enum KeyNode {
    MatchedDisc,
    /// The source had no entry for this disc.
    NoEntry,
+    /// The source matched this disc but could not derive any usable key from the
+    /// matched entry (e.g. no derivation material for the path taken). Distinct
+    /// from [`NoEntry`](Self::NoEntry): the disc WAS found, the key was not.
+    NoDerivableKey,
    /// Pre-decrypted unit keys were found.
    FoundUnitKeys,
    /// A VUK was found.
@@ -123,6 +162,8 @@ mod tests {
                    KeyNode::DerivedUnitKeys,
                ],
                outcome: KeyOutcome::Resolved,
+                matched_entry: None,
+                store_entries: None,
            }],
        };
        // Clone + PartialEq (derive contract the renderers rely on).
@@ -0,0 +1,431 @@
+//! Minimal, read-only parser for `/BDMV/BDJO/*.bdjo` — the BD-J Object files.
+//!
+//! Only the Application Management Table (AMT) is decoded, and only the four
+//! fields the issue #45 Tier-2 menu-walk needs from each application record:
+//! its `application_control_code` (1 = AUTOSTART), `base_directory`,
+//! `classpath_extension`, and `initial_class` (the Xlet's fully-qualified class
+//! name). Everything else in the file is skipped by width.
+//!
+//! Layout follows the published BD-J Object (BDJO) file format: a fixed 48-byte
+//! header (8-byte magic+version, then a 40-byte section-address table that real
+//! players skip), followed by the terminal-info, app-cache-info,
+//! accessible-playlists, and application-management-table sections in sequence.
+//!
+//! This is a DOCUMENTED BINARY FORMAT read as data, never executed. Every field
+//! is bounds-checked and any malformed input yields `None` — panic-free like
+//! [`crate::bdnav::index`]. Tier-2 falls back to scanning every jar when this
+//! returns `None`.
+
+/// One application record from a BDJO Application Management Table — only the
+/// fields the menu-walk consumes.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct BdjoApp {
+    /// `application_control_code`: 1 = AUTOSTART, 2 = PRESENT.
+    pub control_code: u8,
+    /// `base_directory` — the primary jar id (e.g. "00000"), naming
+    /// `/BDMV/JAR/<base_directory>.jar`.
+    pub base_dir: String,
+    /// `classpath_extension` — additional `;`-separated jar ids on the
+    /// classpath, or empty.
+    pub classpath_extension: String,
+    /// `initial_class` — the autostart Xlet's fully-qualified class name
+    /// (e.g. "com.foxbd.StandardMenuXlet").
+    pub initial_class: String,
+}
+
+impl BdjoApp {
+    /// Whether this application autostarts (the one whose Xlet drives the disc).
+    pub fn is_autostart(&self) -> bool {
+        self.control_code == AUTOSTART
+    }
+
+    /// The jar ids that make up this app's classpath: `base_directory` first,
+    /// then each `;`-separated `classpath_extension` entry. Empty tokens are
+    /// dropped. These name `/BDMV/JAR/<id>.jar`.
+    pub fn jar_ids(&self) -> Vec<String> {
+        let mut out = Vec::new();
+        let base = self.base_dir.trim();
+        if !base.is_empty() {
+            out.push(base.to_string());
+        }
+        for part in self.classpath_extension.split(';') {
+            let part = part.trim();
+            if !part.is_empty() && !out.iter().any(|e| e == part) {
+                out.push(part.to_string());
+            }
+        }
+        out
+    }
+}
+
+const AUTOSTART: u8 = 1;
+
+// "BDJO" magic. The 4-byte version that follows ("0100"/"0200"/"0240"/"0300")
+// is read but not validated — a future revision must still let Tier-2 fall back
+// gracefully rather than mis-reject a readable table.
+const MAGIC: u32 = u32::from_be_bytes(*b"BDJO");
+
+// Cap on applications parsed from one AMT. `number_of_applications` is a u8, so
+// 255 is the hard ceiling already; the cap is a belt-and-suspenders bound.
+const MAX_APPS: usize = 256;
+
+/// Parse a `.bdjo` file's Application Management Table. Returns the list of
+/// application records (in file order), or `None` on any structural problem.
+pub(crate) fn parse(data: &[u8]) -> Option<Vec<BdjoApp>> {
+    let mut r = BitReader::new(data);
+
+    // ── Header ──────────────────────────────────────────────────────────────
+    if r.read(32)? as u32 != MAGIC {
+        return None;
+    }
+    r.skip(32)?; // version_number (not load-bearing for resolution)
+    r.skip(40 * 8)?; // section-address table (players read sections sequentially)
+
+    // ── TerminalInfo ────────────────────────────────────────────────────────
+    r.skip(32)?; // length
+    r.skip(5 * 8)?; // default_font (5 bytes)
+    r.skip(4 + 1 + 1)?; // initial_havi_config_id + menu_call_mask + title_search_mask
+    r.skip(34)?; // padding
+
+    // ── AppCacheInfo ──────────────────────────────────────────────────────────
+    r.skip(32)?; // length
+    let num_item = r.read(8)? as usize;
+    r.skip(8)?; // padding
+    for _ in 0..num_item {
+        r.skip(12 * 8)?; // each item: type(1) + ref_to_name(5) + lang_code(3) + pad(3)
+    }
+
+    // ── AccessiblePlaylists ───────────────────────────────────────────────────
+    r.skip(32)?; // length
+    let num_pl = r.read(11)? as usize;
+    r.skip(1 + 1)?; // access_to_all_flag + autostart_first_playlist_flag
+    r.skip(19)?; // padding
+    for _ in 0..num_pl {
+        r.skip(6 * 8)?; // each: name(5) + pad(1)
+    }
+
+    // ── ApplicationManagementTable ────────────────────────────────────────────
+    r.skip(32)?; // length
+    let num_app = r.read(8)? as usize;
+    r.skip(8)?; // padding
+    if num_app > MAX_APPS {
+        return None;
+    }
+    let mut apps = Vec::with_capacity(num_app);
+    for _ in 0..num_app {
+        apps.push(parse_app(&mut r)?);
+    }
+    Some(apps)
+}
+
+// Parse one Application() record from the Application Management Table.
+fn parse_app(r: &mut BitReader<'_>) -> Option<BdjoApp> {
+    let control_code = r.read(8)? as u8;
+    r.skip(4)?; // application_type
+    r.skip(4)?; // reserved
+    r.skip(32)?; // organization_id
+    r.skip(16)?; // application_id
+    r.skip(80)?; // descriptor tag + length (10 bytes)
+
+    // application descriptor
+    let num_profile = r.read(4)? as usize;
+    r.skip(12)?; // padding
+    for _ in 0..num_profile {
+        r.skip(6 * 8)?; // profile_number(2) + major/minor/micro(3) + pad(1)
+    }
+
+    r.skip(8)?; // application_priority
+    r.skip(2 + 2 + 4)?; // binding + visibility + reserved
+
+    // application_name section: u16 data_length, then that many bytes, word-aligned.
+    let names_len = r.read(16)? as usize;
+    r.skip(names_len * 8)?;
+    if !names_len.is_multiple_of(2) {
+        r.skip(8)?;
+    }
+
+    // icon_locator (word-aligned string), then icon_flags(16).
+    read_app_string(r)?;
+    r.skip(16)?;
+
+    let base_dir = read_app_string(r)?;
+    let classpath_extension = read_app_string(r)?;
+    let initial_class = read_app_string(r)?;
+
+    // application_parameters: u8 data_length, that many bytes, word-aligned.
+    let params_len = r.read(8)? as usize;
+    r.skip(params_len * 8)?;
+    if params_len.is_multiple_of(2) {
+        r.skip(8)?;
+    }
+
+    Some(BdjoApp {
+        control_code,
+        base_dir,
+        classpath_extension,
+        initial_class,
+    })
+}
+
+// A word-aligned length-prefixed string (`_read_app_string`): u8 length, then
+// `length` bytes, then one pad byte when `length` is EVEN. Bytes are Latin-1
+// decoded (FQCNs/jar ids are ASCII); trailing NULs are trimmed.
+fn read_app_string(r: &mut BitReader<'_>) -> Option<String> {
+    let len = r.read(8)? as usize;
+    let mut s = String::with_capacity(len);
+    for _ in 0..len {
+        s.push(r.read(8)? as u8 as char);
+    }
+    if len.is_multiple_of(2) {
+        r.skip(8)?;
+    }
+    Some(s.trim_end_matches('\0').to_string())
+}
+
+// ── MSB-first bit reader ─────────────────────────────────────────────────────
+// BDJO integers are bit-packed and consumed most-significant-first.
+// Every read/skip is bounds-checked and returns `None` past the end.
+struct BitReader<'a> {
+    data: &'a [u8],
+    bit_pos: usize,
+}
+
+impl<'a> BitReader<'a> {
+    fn new(data: &'a [u8]) -> Self {
+        BitReader { data, bit_pos: 0 }
+    }
+
+    fn total_bits(&self) -> usize {
+        self.data.len() * 8
+    }
+
+    // Read up to 64 bits, MSB-first. `None` if fewer than `n` bits remain.
+    fn read(&mut self, n: u32) -> Option<u64> {
+        if n == 0 {
+            return Some(0);
+        }
+        if n > 64 {
+            return None;
+        }
+        let end = self.bit_pos.checked_add(n as usize)?;
+        if end > self.total_bits() {
+            return None;
+        }
+        let mut v: u64 = 0;
+        for _ in 0..n {
+            let byte = self.data[self.bit_pos >> 3];
+            let bit = (byte >> (7 - (self.bit_pos & 7))) & 1;
+            v = (v << 1) | bit as u64;
+            self.bit_pos += 1;
+        }
+        Some(v)
+    }
+
+    // Advance `n` bits. `None` if that would run past the end.
+    fn skip(&mut self, n: usize) -> Option<()> {
+        let end = self.bit_pos.checked_add(n)?;
+        if end > self.total_bits() {
+            return None;
+        }
+        self.bit_pos = end;
+        Some(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // ── Bit reader unit tests ──────────────────────────────────────────────
+    #[test]
+    fn bit_reader_reads_msb_first_and_bounds_checks() {
+        let data = [0b1011_0010u8, 0b0100_0001];
+        let mut r = BitReader::new(&data);
+        assert_eq!(r.read(1), Some(1));
+        assert_eq!(r.read(3), Some(0b011));
+        assert_eq!(r.read(4), Some(0b0010));
+        assert_eq!(r.read(8), Some(0b0100_0001));
+        // Nothing left.
+        assert_eq!(r.read(1), None);
+        assert_eq!(r.read(0), Some(0));
+    }
+
+    #[test]
+    fn bit_reader_skip_past_end_is_none() {
+        let data = [0u8; 2];
+        let mut r = BitReader::new(&data);
+        assert_eq!(r.skip(16), Some(()));
+        assert_eq!(r.skip(1), None);
+    }
+
+    // ── Fixture builder ─────────────────────────────────────────────────────
+    // Byte-aligned BDJO builder for a single-app AMT. All bit fields here happen
+    // to fall on byte boundaries, so the fixture can be assembled from bytes.
+    struct AppSpec {
+        control_code: u8,
+        base_dir: &'static str,
+        classpath_extension: &'static str,
+        initial_class: &'static str,
+    }
+
+    fn push_app_string(buf: &mut Vec<u8>, s: &str) {
+        buf.push(s.len() as u8);
+        buf.extend_from_slice(s.as_bytes());
+        if s.len().is_multiple_of(2) {
+            buf.push(0); // word-align pad on even length
+        }
+    }
+
+    fn build_bdjo(apps: &[AppSpec]) -> Vec<u8> {
+        let mut b = Vec::new();
+        // Header
+        b.extend_from_slice(b"BDJO");
+        b.extend_from_slice(b"0200");
+        b.extend_from_slice(&[0u8; 40]); // section-address table
+
+        // TerminalInfo: length(4) + default_font(5) + 1 byte (havi+masks) + pad(34 bits)
+        b.extend_from_slice(&[0u8; 4]);
+        b.extend_from_slice(&[0u8; 5]);
+        // 4+1+1 = 6 bits then 34 bits padding = 40 bits = 5 bytes total.
+        b.extend_from_slice(&[0u8; 5]);
+
+        // AppCacheInfo: length(4) + num_item(1)=0 + pad(1)
+        b.extend_from_slice(&[0u8; 4]);
+        b.push(0);
+        b.push(0);
+
+        // AccessiblePlaylists: length(4) + [num_pl(11)+flags(2)+pad(19)] = 4 bytes, num_pl=0
+        b.extend_from_slice(&[0u8; 4]);
+        b.extend_from_slice(&[0u8; 4]);
+
+        // AppManagementTable: length(4) + num_app(1) + pad(1)
+        b.extend_from_slice(&[0u8; 4]);
+        b.push(apps.len() as u8);
+        b.push(0);
+
+        for a in apps {
+            b.push(a.control_code); // control_code(8)
+            b.push(0); // type(4)+reserved(4)
+            b.extend_from_slice(&[0u8; 4]); // org_id(32)
+            b.extend_from_slice(&[0u8; 2]); // app_id(16)
+            b.extend_from_slice(&[0u8; 10]); // descriptor tag+length(80)
+            b.push(0); // num_profile(4)+pad(4)... wait 4+12=16 bits
+            b.push(0); // (num_profile nibble high, then 12 bits pad) => 2 bytes, 0 profiles
+            b.push(0); // priority(8)
+            b.push(0); // binding(2)+visibility(2)+reserved(4)
+            // application_name: data_length(16)=0, no word-align (even 0)
+            b.extend_from_slice(&[0u8; 2]);
+            // icon_locator (empty word-aligned string): len=0 + pad
+            push_app_string(&mut b, "");
+            b.extend_from_slice(&[0u8; 2]); // icon_flags(16)
+            push_app_string(&mut b, a.base_dir);
+            push_app_string(&mut b, a.classpath_extension);
+            push_app_string(&mut b, a.initial_class);
+            // application_parameters: data_length(8)=0 + word-align (even) pad
+            b.push(0);
+            b.push(0);
+        }
+        b
+    }
+
+    #[test]
+    fn parses_autostart_app_fqcn_and_jar_ids() {
+        let bytes = build_bdjo(&[AppSpec {
+            control_code: 1,
+            base_dir: "00000",
+            classpath_extension: "00001;00002",
+            initial_class: "com.foxbd.StandardMenuXlet",
+        }]);
+        let apps = parse(&bytes).expect("parses");
+        assert_eq!(apps.len(), 1);
+        let a = &apps[0];
+        assert!(a.is_autostart());
+        assert_eq!(a.initial_class, "com.foxbd.StandardMenuXlet");
+        assert_eq!(a.base_dir, "00000");
+        assert_eq!(a.jar_ids(), vec!["00000", "00001", "00002"]);
+    }
+
+    #[test]
+    fn parses_multiple_apps_and_finds_the_autostart_one() {
+        let bytes = build_bdjo(&[
+            AppSpec {
+                control_code: 2, // PRESENT, not autostart
+                base_dir: "00009",
+                classpath_extension: "",
+                initial_class: "com.studio.Helper",
+            },
+            AppSpec {
+                control_code: 1, // AUTOSTART
+                base_dir: "00000",
+                classpath_extension: "",
+                initial_class: "com.studio.MainXlet",
+            },
+        ]);
+        let apps = parse(&bytes).expect("parses");
+        assert_eq!(apps.len(), 2);
+        let auto: Vec<&BdjoApp> = apps.iter().filter(|a| a.is_autostart()).collect();
+        assert_eq!(auto.len(), 1);
+        assert_eq!(auto[0].initial_class, "com.studio.MainXlet");
+        assert_eq!(auto[0].jar_ids(), vec!["00000"]);
+    }
+
+    #[test]
+    fn rejects_bad_magic() {
+        let mut bytes = build_bdjo(&[AppSpec {
+            control_code: 1,
+            base_dir: "00000",
+            classpath_extension: "",
+            initial_class: "X",
+        }]);
+        bytes[0..4].copy_from_slice(b"NOPE");
+        assert!(parse(&bytes).is_none());
+    }
+
+    #[test]
+    fn truncation_yields_none_never_panics() {
+        let bytes = build_bdjo(&[AppSpec {
+            control_code: 1,
+            base_dir: "00000",
+            classpath_extension: "",
+            initial_class: "com.studio.MainXlet",
+        }]);
+        // Every truncation length must return None (or Some), never panic.
+        for cut in 0..bytes.len() {
+            let _ = parse(&bytes[..cut]);
+        }
+    }
+
+    #[test]
+    fn parse_never_panics_on_random_bytes() {
+        let mut state: u64 = 0xB0D0_DEAD_BEEF_1234u64;
+        for _ in 0..500 {
+            // xorshift64*
+            let mut x = state;
+            x ^= x << 13;
+            x ^= x >> 7;
+            x ^= x << 17;
+            state = x;
+            let len = (x % 300) as usize;
+            let mut buf = vec![0u8; len];
+            for (i, b) in buf.iter_mut().enumerate() {
+                *b = ((x >> (i % 57)) & 0xFF) as u8;
+            }
+            // Give some of them a valid magic to exercise deeper paths.
+            if len >= 4 && x & 1 == 0 {
+                buf[0..4].copy_from_slice(b"BDJO");
+            }
+            let _ = parse(&buf);
+        }
+    }
+
+    #[test]
+    fn jar_ids_dedups_and_skips_empties() {
+        let a = BdjoApp {
+            control_code: 1,
+            base_dir: "00000".into(),
+            classpath_extension: "00000;;00003; ".into(),
+            initial_class: "X".into(),
+        };
+        assert_eq!(a.jar_ids(), vec!["00000", "00003"]);
+    }
+}
@@ -7,6 +7,7 @@
 //!
 //! Contract: read-only, bounded, and never panics or hard-fails.

+pub(crate) mod bdjo;
 pub(crate) mod index;
 pub(crate) mod mobj;
 pub(crate) mod vm;
@@ -1308,7 +1308,6 @@ mod tests {
        }];
        let mut keys = crate::decrypt::DecryptKeys::Aacs {
            unit_keys: vec![(0, [0u8; 16])],
-            read_data_key: None,
            format: crate::disc::ContentFormat::MpegPs,
        };
        resolve_dvd_title_key(
@@ -116,14 +116,15 @@ pub fn decrypt_threads() -> usize {
 pub enum DecryptKeys {
    /// No encryption on this disc.
    None,
-    /// AACS (Blu-ray / UHD / HD-DVD). Unit keys + optional read data key. The
-    /// `format` is the disc's content container (BD/UHD/FMTS = Transport Stream,
-    /// HD-DVD `.evo` = Program Stream); it travels with the keys because both are
-    /// resolved once per disc, and the key SELECTOR (`is_clean`) needs it to prove
-    /// a key structurally against the right container.
+    /// AACS (Blu-ray / UHD / HD-DVD). Unit keys only — bus encryption is ALREADY
+    /// removed upstream by the drive's single de-bus point
+    /// ([`crate::sector::bus_removal::BusStage`]), so no read data key is threaded
+    /// here. The `format` is the disc's content container (BD/UHD/FMTS = Transport
+    /// Stream, HD-DVD `.evo` = Program Stream); it travels with the keys because
+    /// both are resolved once per disc, and the key SELECTOR (`is_clean`) needs it
+    /// to prove a key structurally against the right container.
    Aacs {
        unit_keys: Vec<(u32, [u8; 16])>,
-        read_data_key: Option<[u8; 16]>,
        format: crate::disc::ContentFormat,
    },
    /// CSS (DVD). Title key for sector descrambling.
@@ -366,9 +367,17 @@ pub(crate) fn decrypt_sectors_mapped_in_content(
 /// mapped decrypt so clear filesystem/nav units outside every encrypted-content
 /// extent are passed through untouched.
 fn lba_in_content_ranges(lba: u32, ranges: &[(u32, u32)]) -> bool {
-    ranges
-        .iter()
-        .any(|&(start, count)| lba >= start && (lba - start) < count)
+    debug_assert!(
+        ranges.windows(2).all(|w| w[0].0 <= w[1].0),
+        "content ranges must be sorted ascending by start LBA for the binary search"
+    );
+    // Sorted, non-overlapping (merged extents): binary-search the last range
+    // whose start <= lba and test containment — O(log n), not O(ranges).
+    let i = ranges.partition_point(|&(start, _)| start <= lba);
+    i > 0 && {
+        let (start, count) = ranges[i - 1];
+        (lba - start) < count
+    }
 }

 // AACS scheme step: apply `map`'s per-unit keys to `buf`, in-place — no key
@@ -381,12 +390,8 @@ fn apply_aacs_map(
    map: &AacsKeyMap,
    content: Option<&[(u32, u32)]>,
 ) -> Result<(), crate::error::Error> {
-    let (unit_keys, rdk, format) = match keys {
-        DecryptKeys::Aacs {
-            unit_keys,
-            read_data_key,
-            format,
-        } => (unit_keys, *read_data_key, *format),
+    let (unit_keys, format) = match keys {
+        DecryptKeys::Aacs { unit_keys, format } => (unit_keys, *format),
        // Clear / CSS: the mapped path is AACS-only. Leave the buffer untouched;
        // CSS descrambles via `decrypt_sectors` and `None` is already clear.
        _ => return Ok(()),
@@ -451,11 +456,10 @@ fn apply_aacs_map(
        if !aacs::content::aacs_unit_encrypted(chunk, format) {
            return;
        }
-        // Bounds already proven above; index directly.
+        // Bounds already proven above; index directly. Bus encryption was already
+        // removed by the drive's single de-bus point before this buffer arrived —
+        // this path only applies the CPS unit key.
        let key = &unit_keys[key_idx].1;
-        if let Some(ref rdk_key) = rdk {
-            aacs::content::decrypt_bus(chunk, rdk_key);
-        }
        aacs::content::decrypt_unit(chunk, key);
        // Correct-phase forensic verify (silent unless the map is wrong).
        if matches!(phase, Phase::Even | Phase::Odd) && !aacs::content::is_clean(chunk, format) {
@@ -711,7 +715,6 @@ mod tests {
    fn content_gate_aacs_keys_fail_loud_not_ok_zero() {
        let mut keys = DecryptKeys::Aacs {
            unit_keys: vec![(1, [0xAB; 16])],
-            read_data_key: None,
            format: crate::disc::ContentFormat::BdTs,
        };
        let original = scrambled_region(aacs::content::ALIGNED_UNIT_LEN);
@@ -801,7 +804,6 @@ mod tests {
    fn aacs_scrambled_trailing_partial_is_rejected() {
        let keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, [0xAB; 16])],
-            read_data_key: None,
            format: crate::disc::ContentFormat::BdTs,
        };
        // One CLEAR leading unit (passes through) + a 4096-byte (two-sector) tail
@@ -828,7 +830,6 @@ mod tests {
    fn aacs_clear_trailing_partial_passes_through() {
        let keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, [0xAB; 16])],
-            read_data_key: None,
            format: crate::disc::ContentFormat::BdTs,
        };
        let mut buf = clear_ts_region(aacs::content::ALIGNED_UNIT_LEN);
@@ -866,7 +867,6 @@ mod tests {
        assert!(
            DecryptKeys::Aacs {
                unit_keys: vec![(0, [0; 16])],
-                read_data_key: None,
                format: crate::disc::ContentFormat::BdTs,
            }
            .is_encrypted()
@@ -1042,7 +1042,6 @@ mod tests {
    fn aacs_mapped_out_of_range_key_idx_errors() {
        let keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, [0xAB; 16])],
-            read_data_key: None,
            format: crate::disc::ContentFormat::BdTs,
        };
        let mut buf = clear_ts_region(aacs::content::ALIGNED_UNIT_LEN);
@@ -1062,7 +1061,6 @@ mod tests {
    fn aacs_mapped_empty_unit_keys_errors() {
        let keys = DecryptKeys::Aacs {
            unit_keys: vec![],
-            read_data_key: None,
            format: crate::disc::ContentFormat::BdTs,
        };
        let mut buf = clear_ts_region(aacs::content::ALIGNED_UNIT_LEN);
@@ -1079,7 +1077,6 @@ mod tests {
    fn aacs_via_unmapped_decrypt_sectors_fails_loud() {
        let mut keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, [0xAB; 16])],
-            read_data_key: None,
            format: crate::disc::ContentFormat::BdTs,
        };
        let mut buf = clear_ts_region(aacs::content::ALIGNED_UNIT_LEN);
@@ -1114,63 +1111,117 @@ mod tests {
        unit
    }

-    // AACS 2.0 / UHD "OEM route": a drive delivers bus_encrypt(encrypt_unit(clear))
-    // and the mapped decrypt must strip the bus layer with the read_data_key FIRST,
-    // then the unit-key layer — the `if let Some(rdk)` arm no other test reaches.
+    // A `SectorSource` that returns a fixed wire buffer for any read (the bytes a
+    // bus-encrypted drive would put on the transport), reporting the full span —
+    // the input to the drive-owned bus-removal stream in the ordering tests below.
+    struct WireSource {
+        bytes: Vec<u8>,
+    }
+    impl crate::sector::SectorSource for WireSource {
+        fn capacity_sectors(&self) -> u32 {
+            (self.bytes.len() / 2048) as u32
+        }
+        fn read_sectors(
+            &mut self,
+            _lba: u32,
+            count: u16,
+            buf: &mut [u8],
+            _recovery: bool,
+        ) -> crate::error::Result<usize> {
+            let n = (count as usize * 2048).min(self.bytes.len());
+            buf[..n].copy_from_slice(&self.bytes[..n]);
+            Ok(n)
+        }
+    }
+
+    // AACS 2.0 bus-then-unit ordering, proven at the SINGLE de-bus point: the
+    // drive-owned bus-removal stream strips the bus layer AT READ TIME, then the
+    // downstream mapped decrypt strips the unit-key layer (no bus key threaded).
    #[test]
-    fn mapped_decrypt_removes_bus_then_unit_encryption_end_to_end() {
+    fn bus_removal_then_mapped_unit_decrypt_recovers_plaintext_end_to_end() {
+        use crate::sector::SectorSource;
+        use crate::sector::bus_removal::{BusRemovalSectorSource, BusStage};
+
        let unit_key = [0x5Au8; 16];
        let rdk = [0x91u8; 16];
        let mut clear = clear_ts_unit();
        clear[0] |= 0xC0; // the encrypted flag lives in the clear seed
-        let mut buf = clear.clone();
-        // Inner layer: unit-key encryption. Outer layer: drive bus-encryption.
-        aacs_encrypt_unit_for_test(&mut buf, &unit_key);
-        aacs::content::encrypt_bus(&mut buf, &rdk);
+        // Inner layer: unit-key encryption. Outer layer: drive bus-encryption —
+        // exactly the bytes a bus-encrypted drive puts on the wire.
+        let mut wire = clear.clone();
+        aacs_encrypt_unit_for_test(&mut wire, &unit_key);
+        aacs::content::encrypt_bus(&mut wire, &rdk);
+
+        // Read the wire through the drive-owned bus-removal stream (host-key
+        // stage): the ONE place bus decryption is applied.
+        let mut src =
+            BusRemovalSectorSource::new(WireSource { bytes: wire }, BusStage::AacsHostKey(rdk));
+        let mut buf = vec![0u8; aacs::content::ALIGNED_UNIT_LEN];
+        let n = src.read_sectors(0, 3, &mut buf, false).unwrap();
+        assert_eq!(n, aacs::content::ALIGNED_UNIT_LEN);
+        // Bus removed, but the CPS unit-key layer is still in place — not yet clear.
        assert!(
            !aacs::content::is_clean(&buf, crate::disc::ContentFormat::BdTs),
-            "the delivered unit must still be scrambled before decrypt"
+            "bus removed at read, but the CPS unit-key layer must still be scrambled"
        );

+        // The downstream mapped decrypt applies ONLY the unit key over the
+        // already-de-bussed content.
        let keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, unit_key)],
-            read_data_key: Some(rdk),
            format: crate::disc::ContentFormat::BdTs,
        };
        let map = AacsKeyMap::from_ranges(vec![(0, u32::MAX, 0)]);
        decrypt_sectors_mapped(&mut buf, &keys, 0, &map)
-            .expect("bus + unit-key decrypt must succeed");
+            .expect("unit-key decrypt over de-bussed content must succeed");
        assert_eq!(
            buf, clear,
-            "read_data_key (bus) then unit-key must recover the plaintext exactly"
+            "bus removal (at read) then unit-key decrypt must recover the plaintext exactly"
        );
    }

-    // Necessity + ordering proof: the SAME delivered bytes with NO read_data_key
-    // run only the unit-key decrypt over still-bus-encrypted data and must NOT
-    // recover clear — so the rdk arm genuinely runs, and runs BEFORE the unit key.
+    // Necessity: the SAME wire bytes read through a PASSTHROUGH stage keep the bus
+    // layer, so unit-key decrypt alone runs over bus-encrypted data and cannot
+    // recover clear — the bus key is genuinely required, and de-bus precedes it.
    #[test]
-    fn mapped_decrypt_without_read_data_key_cannot_clear_bus_encrypted_content() {
+    fn without_bus_removal_mapped_unit_decrypt_cannot_clear_bus_encrypted_content() {
+        use crate::sector::SectorSource;
+        use crate::sector::bus_removal::{BusRemovalSectorSource, BusStage};
+
        let unit_key = [0x5Au8; 16];
        let rdk = [0x91u8; 16];
        let mut clear = clear_ts_unit();
        clear[0] |= 0xC0;
-        let mut buf = clear.clone();
-        aacs_encrypt_unit_for_test(&mut buf, &unit_key);
-        aacs::content::encrypt_bus(&mut buf, &rdk);
+        let mut wire = clear.clone();
+        aacs_encrypt_unit_for_test(&mut wire, &unit_key);
+        aacs::content::encrypt_bus(&mut wire, &rdk);

-        let keys_no_rdk = DecryptKeys::Aacs {
+        // Passthrough: no bus key, so the wire is delivered still-bus-encrypted.
+        let mut src =
+            BusRemovalSectorSource::new(WireSource { bytes: wire }, BusStage::Passthrough);
+        let mut buf = vec![0u8; aacs::content::ALIGNED_UNIT_LEN];
+        src.read_sectors(0, 3, &mut buf, false).unwrap();
+        // Snapshot the still-bus-encrypted wire as delivered, so we can prove the
+        // unit-key decrypt actually TOUCHED the buffer (not a silent no-op) — a
+        // bare `!= clear` also passes on an untouched buffer.
+        let wire_delivered = buf.clone();
+
+        let keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, unit_key)],
-            read_data_key: None,
            format: crate::disc::ContentFormat::BdTs,
        };
        let map = AacsKeyMap::from_ranges(vec![(0, u32::MAX, 0)]);
        // Phase::All never runs the forensic verify, so this returns Ok either
-        // way; the point is the BYTES are not the plaintext without the bus key.
-        let _ = decrypt_sectors_mapped(&mut buf, &keys_no_rdk, 0, &map);
+        // way; the point is the BYTES are not the plaintext without bus removal.
+        let _ = decrypt_sectors_mapped(&mut buf, &keys, 0, &map);
        assert_ne!(
            buf, clear,
-            "without the read_data_key, unit-key decrypt alone cannot recover clear"
+            "without bus removal first, unit-key decrypt alone cannot recover clear"
+        );
+        assert_ne!(
+            buf, wire_delivered,
+            "unit-key decrypt must have actually run over the buffer (not a no-op); \
+             it just can't recover clear without bus removal first"
        );
    }

@@ -1390,7 +1441,6 @@ mod tests {
        // AACS, encrypted, no map installed at all.
        let mut aacs_keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, [0xAAu8; 16])],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        let mut buf = vec![0u8; ul];
@@ -1440,7 +1490,6 @@ mod tests {

        let keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, key)],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        // The map covers unit 0 only. Unit 1 is the orphan.
@@ -1500,7 +1549,6 @@ mod tests {
        }
        let keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, key_a)],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        let map = AacsKeyMap::from_ranges_phased(vec![(0, 8 * usz, 0, Phase::Even)]);
@@ -1535,7 +1583,6 @@ mod tests {

        let keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, unit_key)],
-            read_data_key: None,
            format: crate::disc::ContentFormat::BdTs,
        };
        let map = AacsKeyMap::from_ranges(vec![(0, u32::MAX, 0)]);
@@ -1579,7 +1626,6 @@ mod tests {
        }
        let keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, key)],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        let map = AacsKeyMap::from_ranges(vec![(0, (n as u32) * usz, 0)]);
@@ -1623,7 +1669,6 @@ mod tests {
        let mut buf = build();
        let keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, key_a), (1, key_b)],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        decrypt_sectors_mapped(&mut buf, &keys, 0, &map)
@@ -1634,7 +1679,6 @@ mod tests {
        let mut buf = build();
        let swapped = DecryptKeys::Aacs {
            unit_keys: vec![(1, key_b), (0, key_a)],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        assert!(
@@ -1657,7 +1701,6 @@ mod tests {
        buf[..ul].copy_from_slice(&u0);
        let keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, [0xCCu8; 16])], // map slot points at the WRONG key
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        let map = AacsKeyMap::from_ranges_phased(vec![(0, 2 * usz, 0, Phase::Even)]);
@@ -1682,7 +1725,6 @@ mod tests {
        }
        let keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, key)],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        decrypt_sectors_mapped(
@@ -646,7 +646,7 @@ mod tests {
        );
        assert_eq!(
            reason,
-            "main_feature_order(nav-feature, authoring-feature, standalone, has-video, fits-disc, largest-size, longest, richest-audio)",
+            "main_feature_order(nav-feature, authoring-feature, standalone, has-video, fits-disc, largest-size, longest, richest-audio, more-video, more-subs)",
            "the reason must name the selection keys (authoring, standalone-over-composite, and has-video gates, then the physical keys) in priority order"
        );
    }
@@ -372,7 +372,6 @@ impl Disc {
            key_source: KeyOrigin::ExternalUk,
            vuk: None,
            unit_keys: vec![],
-            read_data_key: handshake.and_then(|h| h.read_data_key),
            volume_id: handshake.map(|h| h.volume_id).unwrap_or([0u8; 16]),
            uk_ro: uk_ro_data,
            mkb: mkb_bytes,
@@ -772,7 +771,8 @@ mod tests {
        };
        let st = Disc::resolve_vid_only(&udf, &mut disc, Some(&hs)).expect("state");
        assert_eq!(st.volume_id, vid);
-        assert_eq!(st.read_data_key, Some(rdk));
+        // The bus key no longer propagates onto AacsState — it feeds the drive's
+        // single de-bus point via the handshake, not a decrypt-time field.
    }

    // OEM bus-key gate: a bus-encrypted disc on a LIVE drive with no
@@ -831,7 +831,6 @@ mod tests {
        };
        let st = Disc::resolve_vid_only(&udf, &mut disc, Some(&hs)).expect("bus key present → ok");
        assert!(st.bus_encryption);
-        assert_eq!(st.read_data_key, Some([0x22u8; 16]));
    }

    /// Finding: `is_drive_unlocker(matched)` on the cert route was provably always
@@ -864,10 +863,6 @@ mod tests {
        let st = Disc::resolve_vid_only(&udf, &mut disc, Some(&hs))
            .expect("a drive-unlocked disc removes bus encryption even without a read_data_key");
        assert!(st.bus_encryption);
-        assert_eq!(
-            st.read_data_key, None,
-            "the drive-unlock path carries no read_data_key"
-        );
    }

    /// ISO scan (handshake None) of a bus_encryption disc → Ok. Bus encryption
@@ -878,7 +873,6 @@ mod tests {
        let (mut disc, udf) = disc_with_cert(0x01, true);
        let st = Disc::resolve_vid_only(&udf, &mut disc, None).expect("ISO bus disc → ok");
        assert!(st.bus_encryption);
-        assert_eq!(st.read_data_key, None);
    }

    /// AACS 1.0 BD (V10 cert, bus_encryption off) on a live drive with NO
@@ -895,7 +889,6 @@ mod tests {
        };
        let st = Disc::resolve_vid_only(&udf, &mut disc, Some(&hs)).expect("AACS 1.0 → ok");
        assert!(!st.bus_encryption);
-        assert_eq!(st.read_data_key, None);
    }

    /// With NO handshake, volume_id defaults to all-zero (encrypt.rs
@@ -914,7 +907,6 @@ mod tests {
        );
        let st = Disc::resolve_vid_only(&udf, &mut disc, None).expect("state");
        assert_eq!(st.volume_id, [0u8; 16]);
-        assert_eq!(st.read_data_key, None);
    }

    /// `handshake_has_volume_id` treats an all-zero Volume ID as absent and
@@ -1291,11 +1283,10 @@ mod tests {
        ));
    }

-    /// A handshake that carries a VID but `read_data_key: None` must SURFACE the
-    /// `None` onto the state — not silently drop it or synthesize a key. On a
-    /// non-bus-encrypted disc (so the bus-key gate does not fire) the VID still
-    /// propagates while `read_data_key` stays `None`. This is the AACS-2.0
-    /// "VID present, no RDK" signal the downstream gate keys off.
+    /// A handshake that carries a VID but `read_data_key: None` must still surface
+    /// the VID onto the state. On a non-bus-encrypted disc (so the bus-key gate
+    /// does not fire) the VID propagates; the bus key itself no longer lives on
+    /// AacsState — it feeds the drive's single de-bus point via the handshake.
    #[test]
    fn resolve_vid_only_surfaces_vid_with_absent_read_data_key() {
        let (mut disc, udf) = disc_with_cert(0x00, false); // V10, bus off
@@ -1311,9 +1302,5 @@ mod tests {
            st.volume_id, vid,
            "the VID must propagate even without an RDK"
        );
-        assert_eq!(
-            st.read_data_key, None,
-            "a handshake bus_key of None must surface as None, not be dropped or faked"
-        );
    }
 }
@@ -1226,7 +1226,6 @@ mod tests {
            key_source: crate::disc::KeyOrigin::ExternalUk,
            vuk: None,
            unit_keys: vec![(0u32, [0u8; 16])],
-            read_data_key: None,
            volume_id: [0u8; 16],
            uk_ro: Vec::new(),
            mkb: Vec::new(),
@@ -1593,11 +1592,9 @@ mod tests {
        assert!(matches!(err, Error::DirNameCollision { .. }));
    }

-    // Two disc names differing only by CASE fold to one host file on a case-
-    // INSENSITIVE host (macOS APFS / Windows NTFS) — that must be a collision,
-    // not a silent overwrite reported clean. On a case-SENSITIVE volume the two
-    // are distinct files that coexist, so the extract must NOT abort. The
-    // outcome tracks the REAL target volume, tested by probing it.
+    // Two names differing only by CASE collide on a case-INSENSITIVE host (macOS
+    // APFS / Windows NTFS) but coexist on a case-SENSITIVE one, so the extract
+    // must abort on the former and not the latter — outcome tracks the real volume.
    #[test]
    fn names_differing_only_by_case_collide_only_on_a_case_insensitive_host() {
        let root = DirSpec {
@@ -492,6 +492,53 @@ pub(crate) fn aacs_dir_present(udf_fs: &crate::udf::UdfFs) -> bool {
    udf_fs.find_dir("/AACS").is_some() || udf_fs.find_dir("/BDMV/AACS").is_some()
 }

+// Title-ranking heuristic thresholds. Each gates a DISTINCT decision — several
+// share a value (0.5) by coincidence, so they are named and tuned separately.
+// See docs/disc-mod.md for the shape gate.
+/// Nav candidate: a real-video title qualifies only if it runs at least this
+/// fraction of the longest probable-video title's duration.
+const NAV_CANDIDATE_MIN_DURATION_FRAC: f64 = 0.5;
+/// Payload floor: a promoted title must hold at least this fraction of the
+/// largest video-bearing title's byte size, else a tiny playback-valid branch
+/// could win nav/authoring.
+const FEATURE_PAYLOAD_MIN_SIZE_FRAC: f64 = 0.10;
+/// Composite/wrapper gate: candidate wrapper Q must be at least this fraction of
+/// the outer title P's byte size to count as a plausible wrapper.
+const WRAPPER_MIN_SIZE_FRAC: f64 = 0.5;
+/// Seamless-branch guard (issue #45): Q is a wrapper if it is a much SHORTER cut,
+/// i.e. its duration is below this fraction of P's duration.
+const SEAMLESS_SHORTER_CUT_DURATION_FRAC: f64 = 0.85;
+/// Seamless-branch guard (issue #45): Q is a wrapper if it is nearly P's SIZE, i.e.
+/// its byte size is at least this fraction of P's (a bumper, not a real branch).
+const SEAMLESS_BUMPER_SIZE_FRAC: f64 = 0.90;
+/// Authoring hint: honoured only when the title runs at least this fraction of the
+/// longest probable-video title's duration.
+const AUTHORING_MIN_DURATION_FRAC: f64 = 0.5;
+/// Seamless-branch guard (issue #45): the minimum number of chapter marks a title
+/// must carry to look like a COMPLETE feature presentation (a real feature has a
+/// full chapter table; a bare body/branch subset carries one mark or none).
+const MIN_FEATURE_CHAPTERS: usize = 2;
+/// Seamless-branch guard (issue #45): a complete feature's chapter marks span at
+/// least this fraction of its own runtime (start-to-last), distinguishing a real
+/// chapter table from a couple of clustered marks.
+const CHAPTER_SPAN_MIN_FRAC: f64 = 0.5;
+
+/// Issue #45: does `q` look like a COMPLETE feature presentation — a real chapter
+/// table (≥ [`MIN_FEATURE_CHAPTERS`] marks) spanning ≥ [`CHAPTER_SPAN_MIN_FRAC`]
+/// of its runtime? A bare body subset (Alita's 00703 = one mark) fails; a genuine
+/// feature (Alita's 00800 = 37 marks) passes. Gates the composite bumper limb so a
+/// chaptered feature is not demoted below its own un-chaptered body subset. This is
+/// the ABSOLUTE-threshold form; to switch to the RELATIVE form (only if a hoard
+/// sweep finds an SM3-style decoy whose chaptered member is the SUPERSET) replace
+/// the call site with `p.chapters.len() <= q.chapters.len()`. See docs/disc-mod.md.
+fn is_complete_feature_presentation(q: &DiscTitle) -> bool {
+    q.chapters.len() >= MIN_FEATURE_CHAPTERS
+        && q.duration_secs > 0.0
+        && (q.chapters.last().map(|c| c.time_secs).unwrap_or(0.0)
+            - q.chapters.first().map(|c| c.time_secs).unwrap_or(0.0))
+            >= CHAPTER_SPAN_MIN_FRAC * q.duration_secs
+}
+
 /// Union a set of extents into sorted, merged, disjoint `(start_lba,
 /// sector_count)` ranges — the pure, testable core of
 /// [`Disc::encrypted_content_ranges`]. Reuses [`crate::udf::merge_ranges`].
@@ -1435,8 +1482,6 @@ pub struct AacsState {
    pub vuk: Option<[u8; 16]>,
    /// Decrypted unit keys (CPS unit number, key)
    pub unit_keys: Vec<(u32, [u8; 16])>,
-    /// Read data key for AACS 2.0 bus decryption -- None for AACS 1.0
-    pub read_data_key: Option<[u8; 16]>,
    /// Volume ID (16 bytes) -- from SCSI handshake
    pub volume_id: [u8; 16],
    /// Raw `Unit_Key_RO.inf` bytes (encrypted unit keys + CPS map). Stashed at
@@ -1461,7 +1506,6 @@ impl std::fmt::Debug for AacsState {
            .field("key_source", &self.key_source)
            .field("vuk", &self.vuk.map(|_| "<redacted>"))
            .field("unit_keys_len", &self.unit_keys.len())
-            .field("read_data_key", &self.read_data_key.map(|_| "<redacted>"))
            .field("volume_id", &"<redacted>")
            .field("uk_ro_len", &self.uk_ro.len())
            .field("mkb_len", &self.mkb.len())
@@ -1736,6 +1780,10 @@ impl Disc {
            buffered.prefetch_ranges(&ranges);
        }

+        // The AACS bus stage is decided ONCE from the handshake result, captured
+        // before `handshake` is moved into `scan_with` (see `BusStage`).
+        let bus_key = handshake.as_ref().and_then(|h| h.read_data_key);
+
        tracing::info!(target: "freemkv::scan", "phase: parsing titles/streams");
        let disc = Self::scan_with(
            &mut buffered,
@@ -1747,6 +1795,11 @@ impl Disc {
        )?;
        tracing::info!(target: "freemkv::scan", titles = disc.titles.len(), format = ?disc.content_format, "phase: titles parsed");

+        // Wire the SINGLE de-bus point onto the drive from the handshake result,
+        // BEFORE the caller samples keys or muxes (the earlier UDF/metadata reads
+        // ran under default Passthrough).
+        Self::wire_bus_removal(session, bus_key, disc.encrypted_content_ranges());
+
        // No CSS key recovery at scan time: DVD CSS keys are per-title and are
        // re-cracked keylessly at read/decrypt time (`disc.css` stays unset),
        // so log the format rather than a key state that is always `None`.
@@ -1754,6 +1807,25 @@ impl Disc {
        Ok(disc)
    }

+    /// Wire the SINGLE AACS bus-removal de-bus point onto `session` from a
+    /// completed handshake. The cert-route Read Data Key (`bus_key`, `None` on
+    /// the firmware/vendor route) picks the `BusStage`; the encrypted-content
+    /// ranges gate it. ALWAYS install the ranges even when empty: `None` means
+    /// "de-bus every sector", `Some([])` means "de-bus none" — so a host-key disc
+    /// that parsed zero content extents fails SAFE (untouched) instead of de-bussing
+    /// clear UDF/nav bytes to garbage. Extracted from [`Self::scan`] so it is
+    /// unit-testable without a live SCSI handshake.
+    pub(crate) fn wire_bus_removal(
+        session: &mut Drive,
+        bus_key: Option<[u8; 16]>,
+        content_ranges: Vec<(u32, u32)>,
+    ) {
+        session.set_bus_stage(crate::sector::bus_removal::BusStage::from_read_data_key(
+            bus_key,
+        ));
+        session.set_bus_content_ranges(std::sync::Arc::from(content_ranges.into_boxed_slice()));
+    }
+
    // The extents an image-time CSS crack scans, in the crate's CANONICAL
    // order (main feature's own extents, playback order) — do not re-derive
    // this inline. See docs/disc-mod.md — image_crack_extents.
@@ -1903,6 +1975,61 @@ impl Disc {
        Self::read_aacs_inputs_from_reader(&mut reader, &udf_fs)
    }

+    /// Read a disc's **structure metadata** for diagnostics — `(relative_path,
+    /// bytes)` for each present index file that drives title enumeration and
+    /// main-feature selection: `BDMV/index.bdmv`, `MovieObject.bdmv`,
+    /// `PLAYLIST/*.mpls`, `CLIPINF/*.clpi`, `BDJO/*.bdjo`, `META/DL/*.xml`, DVD
+    /// `VIDEO_TS/*.IFO`. No audio/video essence and no AACS keys are read, so the
+    /// result is safe to share in a bug report (a few hundred KB); missing files
+    /// are skipped and empty = no readable structure. Powers `freemkv info …
+    /// --share` over any [`SectorSource`] (drive, ISO, `dir://`) — issue #45.
+    pub fn read_structure_files(reader: &mut dyn SectorSource) -> Result<Vec<(String, Vec<u8>)>> {
+        let udf_fs = udf::read_filesystem(reader)?;
+        let mut out: Vec<(String, Vec<u8>)> = Vec::new();
+
+        // Read one named file into `out` under `rel`, skipping if absent.
+        let mut grab = |udf_fs: &udf::UdfFs, reader: &mut dyn SectorSource, rel: &str| {
+            if let Ok(bytes) = udf_fs.read_file(reader, &format!("/{rel}")) {
+                out.push((rel.to_string(), bytes));
+            }
+        };
+
+        // Top-level BD nav files.
+        grab(&udf_fs, reader, "BDMV/index.bdmv");
+        grab(&udf_fs, reader, "BDMV/MovieObject.bdmv");
+
+        // List a directory's files by extension first (immutable borrow of
+        // udf_fs), then read them (needs &mut reader) — so the directory borrow
+        // is released before the reads. Sorted for deterministic bundles.
+        let list = |udf_fs: &udf::UdfFs, dir: &str, ext: &str| -> Vec<String> {
+            let mut names: Vec<String> = match udf_fs.find_dir(&format!("/{dir}")) {
+                Some(d) => d
+                    .entries
+                    .iter()
+                    .filter(|e| !e.is_dir && e.name.to_ascii_lowercase().ends_with(ext))
+                    .map(|e| e.name.clone())
+                    .collect(),
+                None => Vec::new(),
+            };
+            names.sort();
+            names
+        };
+
+        for (dir, ext) in [
+            ("BDMV/PLAYLIST", ".mpls"),
+            ("BDMV/CLIPINF", ".clpi"),
+            ("BDMV/BDJO", ".bdjo"),
+            ("BDMV/META/DL", ".xml"),
+            ("VIDEO_TS", ".ifo"),
+        ] {
+            for name in list(&udf_fs, dir, ext) {
+                grab(&udf_fs, reader, &format!("{dir}/{name}"));
+            }
+        }
+
+        Ok(out)
+    }
+
    /// Same as [`Disc::read_aacs_inputs`] but reads from a live drive. The
    /// out-of-band Unit Key path fetches the disc's key files from the drive,
    /// resolves a key from them however it likes, then applies it via
@@ -1990,7 +2117,9 @@ impl Disc {
                .iter()
                .filter(|t| {
                    t.has_video()
-                        && (longest_video_dur <= 0.0 || t.duration_secs >= 0.5 * longest_video_dur)
+                        && (longest_video_dur <= 0.0
+                            || t.duration_secs
+                                >= NAV_CANDIDATE_MIN_DURATION_FRAC * longest_video_dur)
                })
                .map(|t| t.playlist_id)
                .collect();
@@ -2079,8 +2208,14 @@ impl Disc {
    /// duration sort: a branching UHD's play-all can report an inflated
    /// duration/size exceeding the disc's physical capacity. These are the
    /// [`Self::canonical_title_order`] sort keys; see docs/disc-mod.md.
-    pub const CANONICAL_TITLE_ORDER_KEYS: &'static [&'static str] =
-        &["fits-disc", "largest-size", "longest", "richest-audio"];
+    pub const CANONICAL_TITLE_ORDER_KEYS: &'static [&'static str] = &[
+        "fits-disc",
+        "largest-size",
+        "longest",
+        "richest-audio",
+        "more-video",
+        "more-subs",
+    ];

    // Content-based forced-subtitle detection, restricted to `BdTs` titles —
    // gates on STREAM CONTAINER not disc-tree format (only BdTs carries
@@ -2122,6 +2257,19 @@ impl Disc {
            // (a full-audio main vs a stereo-only twin) — prefer lossless-multichannel.
            .then_with(|| b.duration_secs.total_cmp(&a.duration_secs))
            .then_with(|| Self::audio_richness(b).cmp(&Self::audio_richness(a)))
+            // Issue #45: before the lowest-id key, prefer the STREAM-RICHER sibling on
+            // the axes audio_richness misses (extra video = Dolby Vision EL; extra
+            // subtitle). True siblings match both and fall through to lowest-id.
+            .then_with(|| b.video_streams().count().cmp(&a.video_streams().count()))
+            .then_with(|| {
+                b.subtitle_streams()
+                    .count()
+                    .cmp(&a.subtitle_streams().count())
+            })
+            // Final determinism (issue #45): among equal-size seamless siblings
+            // (Alita 00800-00808, same body + different logo) pick the LOWEST
+            // playlist_id. Inert where an earlier key separates the pair.
+            .then_with(|| a.playlist_id.cmp(&b.playlist_id))
    }

    /// The keys [`Self::main_feature_order`] layers ON TOP of
@@ -2142,11 +2290,11 @@ impl Disc {
    /// Precompute the [`TitleRank`] for every title, in the same index
    /// order. Composite detection: title `P` is a composite when some OTHER
    /// title `Q` has a non-empty clip-id set that is a PROPER SUBSET of `P`'s,
-    /// `Q` has plausible video, and `Q` accounts for at least half of `P`'s
-    /// declared size — independent of capacity, which may be `0`/unknown.
-    /// Known residual: a "resume from the middle" branch playlist could be
-    /// mis-flagged; rare, and higher-precedence nav/authoring signals
-    /// override it. See docs/disc-mod.md for detail.
+    /// `Q` has plausible video, `Q` accounts for at least half of `P`'s
+    /// declared size, AND `P` has a WRAPPER shape (issue #45): either `Q` is a
+    /// much shorter cut or `Q` is nearly `P`'s size-equal. Capacity-independent
+    /// (`capacity` may be `0`/unknown). See docs/disc-mod.md for the shape
+    /// gate, its thresholds, and the known residual.
    pub fn rank_titles(
        titles: &[DiscTitle],
        hint: Option<&crate::labels::FeaturePlaylistHint>,
@@ -2171,7 +2319,8 @@ impl Disc {
            .max()
            .unwrap_or(0);
        let carries_feature_payload = |t: &DiscTitle| {
-            max_video_size == 0 || t.size_bytes as f64 >= 0.10 * max_video_size as f64
+            max_video_size == 0
+                || t.size_bytes as f64 >= FEATURE_PAYLOAD_MIN_SIZE_FRAC * max_video_size as f64
        };
        // The composite scan below is O(n^2 * clip-set-size); title/clip counts are
        // untrusted, so a crafted image could stall it. Bound the total pair work;
@@ -2199,7 +2348,15 @@ impl Disc {
                            !qj.is_empty()
                                && qj.len() < pi.len()
                                && q.has_probable_video()
-                                && q.size_bytes as f64 >= 0.5 * p.size_bytes as f64
+                                && q.size_bytes as f64 >= WRAPPER_MIN_SIZE_FRAC * p.size_bytes as f64
+                                // Seamless-branch guard (issue #45): wrapper only if Q is
+                                // a much SHORTER cut (concat) OR nearly P's SIZE AND a
+                                // complete feature (bumper) — see is_complete_feature_presentation.
+                                && (q.duration_secs
+                                    < SEAMLESS_SHORTER_CUT_DURATION_FRAC * p.duration_secs
+                                    || (q.size_bytes as f64
+                                        >= SEAMLESS_BUMPER_SIZE_FRAC * p.size_bytes as f64
+                                        && is_complete_feature_presentation(q)))
                                && qj.is_subset(pi)
                        }
                    });
@@ -2209,7 +2366,8 @@ impl Disc {
                let authoring = !composite
                    && hint.is_some_and(|h| h.matches(p.playlist_id, &p.playlist))
                    && p.has_video()
-                    && (longest_video_dur <= 0.0 || p.duration_secs >= 0.5 * longest_video_dur)
+                    && (longest_video_dur <= 0.0
+                        || p.duration_secs >= AUTHORING_MIN_DURATION_FRAC * longest_video_dur)
                    && carries_feature_payload(p);
                // Nav result is video- and payload-gated like the authoring hint,
                // so a streamless or low-byte branch/DV presentation cannot win
@@ -2439,13 +2597,10 @@ impl std::fmt::Debug for Key {
 // CPS units. See docs/disc-mod.md for why "first sample decrypts" is unsafe.
 fn aligned_unit_keys_validate(
    unit_keys: &[(u32, [u8; 16])],
-    read_data_key: Option<&[u8; 16]>,
    samples: &[Vec<u8>],
    format: ContentFormat,
 ) -> bool {
-    use crate::aacs::content::{
-        ALIGNED_UNIT_LEN, aacs_unit_needs_decrypt, decrypt_bus, decrypt_unit, is_clean,
-    };
+    use crate::aacs::content::{ALIGNED_UNIT_LEN, aacs_unit_needs_decrypt, decrypt_unit, is_clean};
    let scrambled: Vec<&[u8]> = samples
        .iter()
        .map(|s| s.as_slice())
@@ -2471,11 +2626,9 @@ fn aligned_unit_keys_validate(
            hb.tick_cpu(tried, total);
            tried += 1;
            probe.copy_from_slice(&sample[..ALIGNED_UNIT_LEN]);
-            // bus layer (AACS 2.0) first, then the CPS unit key, then the structural
-            // proof — the composed form of the old `decrypt_unit_full`.
-            if let Some(rdk) = read_data_key {
-                decrypt_bus(&mut probe, rdk);
-            }
+            // Samples arrive ALREADY de-bussed (the drive's single de-bus point
+            // removed AACS 2.0 bus encryption at read time), so validation only
+            // applies the CPS unit key, then the structural proof.
            decrypt_unit(&mut probe, k);
            if is_clean(&probe, format) {
                covered = true;
@@ -2517,7 +2670,6 @@ impl Disc {
            }
            crate::decrypt::DecryptKeys::Aacs {
                unit_keys: aacs.unit_keys.clone(),
-                read_data_key: aacs.read_data_key,
                format: self.content_format,
            }
        } else if let Some(ref css) = self.css {
@@ -2819,7 +2971,6 @@ impl Disc {
                key_source: KeyOrigin::ExternalUk,
                vuk: None,
                unit_keys: keys,
-                read_data_key: None,
                volume_id: [0u8; 16],
                uk_ro: Vec::new(),
                mkb: Vec::new(),
@@ -2867,14 +3018,9 @@ impl Disc {
    /// rejected key (`Err(AacsKeyRejected)`) falls through to the caller's
    /// next candidate. Pass `&[]` to skip validation (resume / mapfile cache).
    pub fn decrypt_with(&mut self, key: Key, samples: &[Vec<u8>]) -> Result<()> {
-        // The AACS 2.x bus key, needed to de-scramble a sample for validation;
-        // captured before any mutable borrow. None for AACS 1.0 and file-backed
-        // ISO units (bus encryption was already removed at read time).
-        let read_data_key = self.aacs.as_ref().and_then(|a| a.read_data_key);
-
-        // Resolve the supplied key DOWN to candidate unit keys WITHOUT
-        // committing them, so a wrong higher-level key can be rejected before it
-        // poisons disc state.
+        // Samples arrive already de-bussed (drive's single bus-removal point), so
+        // validation needs no bus key. Resolve the key DOWN to candidate unit keys
+        // WITHOUT committing — a wrong higher key is rejected before it poisons state.
        let (candidate_unit_keys, candidate_vuk) = if let Key::Unit(keys) = key {
            // Terminal — the source / mapfile already holds the final UKs.
            (keys, None)
@@ -2943,12 +3089,7 @@ impl Disc {
        // VALIDATE against real ciphertext. Conservative: reject only when a
        // supplied sample is AACS-scrambled and NO candidate key can de-scramble
        // it; with no samples the key is accepted as-is (sample-less paths unchanged).
-        if !aligned_unit_keys_validate(
-            &candidate_unit_keys,
-            read_data_key.as_ref(),
-            samples,
-            self.content_format,
-        ) {
+        if !aligned_unit_keys_validate(&candidate_unit_keys, samples, self.content_format) {
            return Err(crate::error::Error::AacsKeyRejected);
        }

@@ -3736,7 +3877,6 @@ mod tests {
            key_source: KeyOrigin::ExternalUk,
            vuk: Some([0xD5; 16]),
            unit_keys: vec![(1, [0xD5; 16])],
-            read_data_key: Some([0xD5; 16]),
            volume_id: [0xD5; 16],
            uk_ro: vec![1, 2, 3],
            mkb: vec![4, 5, 6],
@@ -4398,6 +4538,65 @@ mod tests {
        );
    }

+    // Issue #45: equal size/duration/audio siblings differing only on video-count or
+    // subtitle-count must pick the stream-richer playlist (not lowest id); truly
+    // identical siblings still fall through to lowest-id determinism.
+    #[test]
+    fn canonical_title_order_prefers_stream_richer_sibling_issue_45() {
+        let cap = 100_000_000_000u64;
+        let base = |id: u16| DiscTitle {
+            playlist_id: id,
+            size_bytes: 57_000_000_000,
+            duration_secs: 8000.0,
+            ..title_with_video(Codec::Hevc, Resolution::R2160p)
+        };
+        // Higher-id sibling carries an extra VIDEO stream (a Dolby Vision EL).
+        let mut richer_v = base(801);
+        richer_v.streams.push(Stream::Video(VideoStream {
+            pid: 0x1015,
+            codec: Codec::Hevc,
+            resolution: Resolution::R1080p,
+            frame_rate: FrameRate::F23_976,
+            hdr: HdrFormat::Sdr,
+            color_space: ColorSpace::Bt709,
+            display_aspect: None,
+            secondary: true,
+            label: String::new(),
+            measured_cicp: None,
+        }));
+        let mut vv = [base(40), richer_v];
+        vv.sort_by(|a, b| Disc::canonical_title_order(a, b, cap));
+        assert_eq!(
+            vv[0].playlist_id, 801,
+            "the video-richer sibling (Dolby Vision EL) must win over the lowest id"
+        );
+
+        // Higher-id sibling carries an extra SUBTITLE track.
+        let mut richer_s = base(801);
+        richer_s.streams.push(Stream::Subtitle(SubtitleStream {
+            pid: 0x12a4,
+            codec: Codec::Pgs,
+            language: "eng".into(),
+            forced: false,
+            qualifier: LabelQualifier::None,
+            codec_data: None,
+        }));
+        let mut ss = [base(40), richer_s];
+        ss.sort_by(|a, b| Disc::canonical_title_order(a, b, cap));
+        assert_eq!(
+            ss[0].playlist_id, 801,
+            "the subtitle-richer sibling must win over the lowest id"
+        );
+
+        // Truly identical siblings → lowest-id determinism preserved.
+        let mut ii = [base(808), base(800)];
+        ii.sort_by(|a, b| Disc::canonical_title_order(a, b, cap));
+        assert_eq!(
+            ii[0].playlist_id, 800,
+            "identical seamless siblings still pick the lowest id"
+        );
+    }
+
    /// A BD title carrying video, `id`, `dur`/`size`, and the given clip ids.
    fn bd_title(playlist: &str, id: u16, dur: f64, size: u64, clip_ids: &[&str]) -> DiscTitle {
        DiscTitle {
@@ -4420,6 +4619,88 @@ mod tests {
        }
    }

+    /// A BD title as [`bd_title`], plus a chapter table of `n_chapters` marks
+    /// evenly spanning `dur` (first at 0, last at `dur`) — models a COMPLETE
+    /// feature presentation for the issue #45 seamless-branch guard. `n_chapters`
+    /// must be ≥ 2 for the marks to span any runtime.
+    fn bd_title_chaptered(
+        playlist: &str,
+        id: u16,
+        dur: f64,
+        size: u64,
+        clip_ids: &[&str],
+        n_chapters: usize,
+    ) -> DiscTitle {
+        let chapters = (0..n_chapters)
+            .map(|i| Chapter {
+                time_secs: if n_chapters <= 1 {
+                    0.0
+                } else {
+                    i as f64 * dur / (n_chapters - 1) as f64
+                },
+                name: (i + 1).to_string(),
+            })
+            .collect();
+        DiscTitle {
+            chapters,
+            ..bd_title(playlist, id, dur, size, clip_ids)
+        }
+    }
+
+    /// A BD title with `n_chapters` marks clustered in the first `span_secs` of a
+    /// `dur`-second runtime (first at 0, last at `span_secs`) — lets a test drive
+    /// the CHAPTER_SPAN_MIN_FRAC boundary independently of chapter count.
+    fn bd_title_chaptered_span(
+        playlist: &str,
+        id: u16,
+        dur: f64,
+        size: u64,
+        clip_ids: &[&str],
+        n_chapters: usize,
+        span_secs: f64,
+    ) -> DiscTitle {
+        let chapters = (0..n_chapters)
+            .map(|i| Chapter {
+                time_secs: if n_chapters <= 1 {
+                    0.0
+                } else {
+                    i as f64 * span_secs / (n_chapters - 1) as f64
+                },
+                name: (i + 1).to_string(),
+            })
+            .collect();
+        DiscTitle {
+            chapters,
+            ..bd_title(playlist, id, dur, size, clip_ids)
+        }
+    }
+
+    // Issue #45 boundary: marks that cluster in the first ~20% of runtime span
+    // < CHAPTER_SPAN_MIN_FRAC of duration, so they are NOT a complete feature.
+    #[test]
+    fn is_complete_feature_presentation_false_when_marks_cluster_early() {
+        // 5 marks over the first 20% (span 0.2 < 0.5 of duration).
+        let clustered =
+            bd_title_chaptered_span("00001.mpls", 1, 1000.0, 1_000_000, &["00001"], 5, 200.0);
+        assert!(
+            !is_complete_feature_presentation(&clustered),
+            "marks spanning < 0.5 of runtime are not a complete feature"
+        );
+    }
+
+    // Issue #45 boundary: marks spanning exactly CHAPTER_SPAN_MIN_FRAC of the
+    // runtime (with >= MIN_FEATURE_CHAPTERS marks) DO look like a real feature.
+    #[test]
+    fn is_complete_feature_presentation_true_at_span_threshold() {
+        // 2 marks (== MIN_FEATURE_CHAPTERS) spanning exactly 0.5 of duration.
+        let at_threshold =
+            bd_title_chaptered_span("00001.mpls", 1, 1000.0, 1_000_000, &["00001"], 2, 500.0);
+        assert!(
+            is_complete_feature_presentation(&at_threshold),
+            "marks spanning >= 0.5 of runtime with enough marks are a complete feature"
+        );
+    }
+
    /// Same, but with an empty STN stream list — models a title whose FIRST
    /// PlayItem is a non-video bumper (`has_video()` is false; `streams` reflect
    /// PlayItem 0 only).
@@ -4436,9 +4717,9 @@ mod tests {
        }
    }

-    // Regression for a real UHD decoy hang: 00245.mpls is a WRAPPER
-    // COMPOSITE (bumper+feature+outro) that is LONGEST/LARGEST; must be
-    // demoted STRUCTURALLY, not by stream count. See docs/disc-mod.md.
+    // Regression for a real UHD decoy hang: 00245.mpls is a WRAPPER COMPOSITE
+    // (bumper+feature+outro), LONGEST/LARGEST; demoted STRUCTURALLY by the chapter
+    // table (issue #45) — wrapped feature 00001 is chaptered, the decoy is not.
    #[test]
    fn main_feature_order_demotes_wrapper_composite_decoy() {
        let decoy = bd_title_no_stn_video(
@@ -4448,7 +4729,7 @@ mod tests {
            78_427_502_592,
            &["00339", "00001", "00336"],
        );
-        let feature = bd_title("00001.mpls", 1, 8038.4, 76_525_627_392, &["00001"]);
+        let feature = bd_title_chaptered("00001.mpls", 1, 8038.4, 76_525_627_392, &["00001"], 12);
        let extra = bd_title("00248.mpls", 248, 794.2, 60_000_000_000, &["00248"]);
        let capacity = 88_000_000_000u64;

@@ -4487,7 +4768,9 @@ mod tests {
            78_000_000_000,
            &["dead", "00001"],
        );
-        let feature = bd_title("00001.mpls", 1, 8000.0, 76_000_000_000, &["00001"]);
+        // The wrapped feature carries the real chapter table (issue #45), so the
+        // bumper limb correctly detects 00245 as its wrapper composite.
+        let feature = bd_title_chaptered("00001.mpls", 1, 8000.0, 76_000_000_000, &["00001"], 12);
        let small = vec![decoy.clone(), feature.clone()];
        assert!(
            Disc::rank_titles(&small, None, None)[0].composite,
@@ -4518,7 +4801,9 @@ mod tests {
            78_427_502_592,
            &["00001", "00336"],
        );
-        let feature = bd_title("00001.mpls", 1, 8038.4, 76_525_627_392, &["00001"]);
+        // The wrapped feature carries the real chapter table (issue #45); the
+        // video-bearing wrapper carries none, so it stays demoted.
+        let feature = bd_title_chaptered("00001.mpls", 1, 8038.4, 76_525_627_392, &["00001"], 12);
        let capacity = 88_000_000_000u64;

        let mut titles = vec![composite, feature];
@@ -4552,6 +4837,235 @@ mod tests {
        );
    }

+    /// Issue #45 (SAFETY): the REAL Alita BD-J numbers. Feature 00800 (4 clips,
+    /// 7317 s, 58.61 GB, 37 chapter marks) is a SUPERSET of its single-clip body
+    /// 00703 ([00688], 6951 s, 56.88 GB, 1 mark). The body is 0.97 of the feature's
+    /// size, so the size-only bumper limb fires (0.97 ≥ 0.90) while the body runs
+    /// over 0.85 of the feature so the concat limb does NOT — the OLD gate demoted
+    /// 00800 and ripped the body. The chapter-table guard keeps 00800: its body
+    /// subset carries one mark (< MIN_FEATURE_CHAPTERS), not a complete feature.
+    #[test]
+    fn seamless_branch_feature_not_demoted_issue_45() {
+        // 00800: real feature = body + intro/credits/seamless branch segments,
+        // with a full 37-mark chapter table.
+        let feature = bd_title_chaptered(
+            "00800.mpls",
+            800,
+            7317.0,
+            58_610_000_000,
+            &["00687", "00688", "00674", "00689"],
+            37,
+        );
+        // 00703: single body clip, a PROPER subset, 6951 s (~0.95 of 00800's
+        // duration → concat limb inert) and 56.88 GB (~0.97 of its size → old
+        // bumper limb would fire) — one chapter mark, not a feature.
+        let decoy = bd_title_chaptered("00703.mpls", 703, 6951.0, 56_880_000_000, &["00688"], 1);
+        let capacity = 88_000_000_000u64;
+
+        // The body subset is a proper subset with ≥90 % size — the OLD gate
+        // flagged 00800 composite on that alone. It must no longer be flagged.
+        let ranks = Disc::rank_titles(&[feature.clone(), decoy.clone()], None, None);
+        assert!(
+            !ranks[0].composite,
+            "the seamless-branch feature must not be flagged a wrapper composite"
+        );
+        assert!(!ranks[1].composite, "the shorter body subset is standalone");
+
+        let mut titles = vec![decoy, feature];
+        Disc::sort_titles_by_main_feature(&mut titles, capacity, None, None);
+        assert_eq!(
+            titles[0].playlist_id, 800,
+            "the full seamless-branch feature is selected, not the shorter body decoy"
+        );
+    }
+
+    /// The seamless-branch guard must NOT weaken the real play-all case: a
+    /// concat wrapper (00099, four distinct parts, ~4h13 = their SUM) whose body
+    /// subset is much SHORTER (00800, one part, ~2h02, <half the runtime) is
+    /// still flagged composite and demoted below that standalone part.
+    #[test]
+    fn true_play_all_concat_wrapper_still_demoted() {
+        let playall = bd_title(
+            "00099.mpls",
+            99,
+            15_180.0, // ~4h13 — the SUM of its four parts
+            92_400_000_000,
+            &["00800", "00801", "00802", "00803"],
+        );
+        // The real feature = one part, ~2h02, less than half the wrapper's runtime.
+        let feature = bd_title("00800.mpls", 800, 7320.0, 57_200_000_000, &["00800"]);
+        let capacity = 100_000_000_000u64;
+
+        let ranks = Disc::rank_titles(&[playall.clone(), feature.clone()], None, None);
+        assert!(
+            ranks[0].composite,
+            "a concat play-all whose subset is much shorter is still a composite"
+        );
+        assert!(!ranks[1].composite, "the standalone feature part is not");
+
+        let mut titles = vec![playall, feature];
+        Disc::sort_titles_by_main_feature(&mut titles, capacity, None, None);
+        assert_eq!(
+            titles[0].playlist_id, 800,
+            "the standalone feature wins; the concat play-all is demoted"
+        );
+    }
+
+    /// Issue #45 (Alita BD-J): the disc has NO authoritative static playlist
+    /// chain (First-Play is a BD-J Xlet, index title's playlist has an empty
+    /// TableOfAccessiblePlayLists), so selection is a pure structural failsafe.
+    /// The chaptered feature 00800 is a SUPERSET of its un-chaptered body subset
+    /// 00703 that is 0.97 of its size — the size-only bumper limb would demote
+    /// it. The chapter-table guard keeps 00800 (its body carries one mark).
+    #[test]
+    fn alita_bdj_body_subset_does_not_demote_chaptered_feature_issue_45() {
+        let feature = bd_title_chaptered(
+            "00800.mpls",
+            800,
+            7317.0,
+            58_610_000_000,
+            &["00687", "00688", "00674", "00689"],
+            37,
+        );
+        let body = bd_title_chaptered("00703.mpls", 703, 6951.0, 56_880_000_000, &["00688"], 1);
+        let capacity = 88_000_000_000u64;
+
+        let ranks = Disc::rank_titles(&[feature.clone(), body.clone()], None, None);
+        assert!(
+            !ranks[0].composite,
+            "the chaptered feature must not be flagged a wrapper composite of its body"
+        );
+
+        // No hint, no nav — the BD-J disc gives neither; selection is structural.
+        let mut titles = vec![body, feature];
+        Disc::sort_titles_by_main_feature(&mut titles, capacity, None, None);
+        assert_eq!(
+            titles[0].playlist_id, 800,
+            "the chaptered feature is selected, not its un-chaptered body subset"
+        );
+    }
+
+    /// Issue #45 (secondary determinism): the nine feature variants 00800-00808
+    /// share the body clip 00688 and differ only by opening logo, so they are
+    /// equal in size/duration/audio — the lowest-playlist_id final tie-break
+    /// deterministically picks 00800. All nine rank above the un-chaptered body
+    /// subset 00703, and none is demoted as a composite of it.
+    #[test]
+    fn alita_full_family_ranks_above_body() {
+        let mut titles: Vec<DiscTitle> = (0..9)
+            .map(|k| {
+                let id = 800 + k as u16;
+                bd_title_chaptered(
+                    &format!("008{k:02}.mpls"),
+                    id,
+                    7317.0,
+                    58_610_000_000,
+                    &[&format!("logo{k}"), "00688"],
+                    37,
+                )
+            })
+            .collect();
+        // The bare body: a proper subset of every family member, one chapter mark,
+        // 0.97 of their size (would trip the old bumper limb).
+        titles.push(bd_title_chaptered(
+            "00703.mpls",
+            703,
+            6951.0,
+            56_880_000_000,
+            &["00688"],
+            1,
+        ));
+        let capacity = 88_000_000_000u64;
+
+        let ranks = Disc::rank_titles(&titles, None, None);
+        assert!(
+            ranks.iter().all(|r| !r.composite),
+            "no equal-size seamless sibling nor its body subset is a composite"
+        );
+
+        Disc::sort_titles_by_main_feature(&mut titles, capacity, None, None);
+        assert_eq!(
+            titles[0].playlist_id, 800,
+            "the lowest-id feature variant is the deterministic pick among equals"
+        );
+        assert_eq!(
+            titles.last().unwrap().playlist_id,
+            703,
+            "the smaller body subset ranks below the whole feature family"
+        );
+    }
+
+    /// Issue #45 (SM3 topology, opposite of Alita): the real chaptered feature
+    /// 00001 is the SUBSET; the decoy 00245 = [bumper][feature][outro] is the
+    /// SUPERSET. Because the subset IS a complete feature presentation (real
+    /// chapter table), the bumper limb still fires and the wrapper stays demoted.
+    #[test]
+    fn bumper_wrapper_with_chaptered_subset_still_demoted() {
+        let wrapper = bd_title(
+            "00245.mpls",
+            245,
+            8350.0,
+            78_000_000_000,
+            &["00339", "00001", "00336"],
+        );
+        // 0.98 of the wrapper's size (bumper limb) and a full chapter table.
+        let feature = bd_title_chaptered("00001.mpls", 1, 8038.0, 76_500_000_000, &["00001"], 24);
+        let capacity = 88_000_000_000u64;
+
+        let ranks = Disc::rank_titles(&[wrapper.clone(), feature.clone()], None, None);
+        assert!(
+            ranks[0].composite,
+            "a bumper wrapper of a CHAPTERED feature subset is still a composite"
+        );
+        assert!(
+            !ranks[1].composite,
+            "the chaptered feature subset is standalone"
+        );
+
+        let mut titles = vec![wrapper, feature];
+        Disc::sort_titles_by_main_feature(&mut titles, capacity, None, None);
+        assert_eq!(
+            titles[0].playlist_id, 1,
+            "the chaptered feature wins; its bumper wrapper is demoted"
+        );
+    }
+
+    /// Issue #45: when the bumper-size subset carries NO chapter table it is not
+    /// a complete feature, so the bumper limb does not fire and the SUPERSET is
+    /// kept — the exact mechanism that saves Alita's 00800 over its body 00703.
+    #[test]
+    fn un_chaptered_bumper_subset_keeps_superset() {
+        // Superset feature, chaptered.
+        let superset = bd_title_chaptered(
+            "00800.mpls",
+            800,
+            7317.0,
+            58_610_000_000,
+            &["00687", "00688", "00674", "00689"],
+            30,
+        );
+        // Subset: 0.97 of the superset's size (bumper limb size), but NO chapters.
+        let subset = bd_title("00703.mpls", 703, 6951.0, 56_880_000_000, &["00688"]);
+        assert!(
+            subset.chapters.is_empty(),
+            "the body subset carries no marks"
+        );
+        let capacity = 88_000_000_000u64;
+
+        let ranks = Disc::rank_titles(&[superset.clone(), subset.clone()], None, None);
+        assert!(
+            !ranks[0].composite,
+            "an un-chaptered bumper-size subset must not demote its superset"
+        );
+
+        let mut titles = vec![subset, superset];
+        Disc::sort_titles_by_main_feature(&mut titles, capacity, None, None);
+        assert_eq!(
+            titles[0].playlist_id, 800,
+            "the superset feature is kept, not the un-chaptered body subset"
+        );
+    }
+
    /// The disc's own authoring-designated feature wins even when it is NOT the
    /// longest/largest title — a size-independent signal a decoy cannot forge.
    #[test]
@@ -4617,7 +5131,9 @@ mod tests {
            78_000_000_000,
            &["00339", "00001", "00336"],
        );
-        let feature = bd_title("00001.mpls", 1, 8000.0, 76_000_000_000, &["00001"]);
+        // The wrapped feature carries the real chapter table (issue #45), so the
+        // streamless wrapper 00245 is detected as a composite and demoted.
+        let feature = bd_title_chaptered("00001.mpls", 1, 8000.0, 76_000_000_000, &["00001"], 12);
        let capacity = 88_000_000_000u64;

        let mut titles = vec![streamless, feature];
@@ -5036,13 +5552,8 @@ mod tests {
        disc.inject_unit_keys(uk.clone());

        match disc.decrypt_keys() {
-            crate::decrypt::DecryptKeys::Aacs {
-                unit_keys,
-                read_data_key,
-                ..
-            } => {
+            crate::decrypt::DecryptKeys::Aacs { unit_keys, .. } => {
                assert_eq!(unit_keys, uk, "injected UK must be the decrypt key");
-                assert_eq!(read_data_key, None, "ISO mux needs no bus key");
            }
            _ => panic!("expected Aacs decrypt keys after injecting a UK"),
        }
@@ -5085,7 +5596,6 @@ mod tests {
            key_source: KeyOrigin::DeviceKey,
            vuk: None,
            unit_keys,
-            read_data_key: None,
            volume_id: [0u8; 16],
            uk_ro: Vec::new(),
            mkb: Vec::new(),
@@ -5338,6 +5848,131 @@ mod tests {
        }
    }

+    /// Issue #46: a source that MATCHED the disc but derived no key must render
+    /// distinctly from a true miss — `matched disc > no VID`, NOT `no entry` —
+    /// and carry the matched entry's shape for the app to log.
+    #[test]
+    fn matched_but_underivable_disc_is_not_reported_as_no_entry() {
+        use crate::aacs::trace::{KeyNode, MatchedEntry};
+        use crate::keysource::{
+            KeySource, ResolveCtx, UnitKeyResolution, resolve_and_apply_traced,
+        };
+
+        /// Matched the disc, had a Media Key, but no VID on this path — the
+        /// classic issue-#46 case (a keydb hit that cannot finish).
+        struct MatchedNoVid;
+        impl KeySource for MatchedNoVid {
+            fn get_unit_keys(
+                &self,
+                _ctx: &dyn ResolveCtx,
+            ) -> std::result::Result<Vec<crate::aacs::types::UnitKey>, crate::error::Error>
+            {
+                Ok(Vec::new())
+            }
+            fn resolve_unit_keys(
+                &self,
+                _ctx: &dyn ResolveCtx,
+            ) -> std::result::Result<UnitKeyResolution, crate::error::Error> {
+                Ok(UnitKeyResolution {
+                    keys: Vec::new(),
+                    matched: true,
+                    miss_path: vec![KeyNode::NoVid],
+                    matched_entry: Some(MatchedEntry {
+                        has_media_key: true,
+                        enc_title_keys_len: 1,
+                        ..Default::default()
+                    }),
+                    store_entries: Some(3),
+                })
+            }
+            fn label(&self) -> &'static str {
+                "keydb"
+            }
+        }
+
+        let inputs = crate::keysource::DiscInputs {
+            disc_hash: "0xMATCH".into(),
+            volume_id: [0u8; 16],
+            version: crate::aacs::mkb::AACS_MAJOR_UHD,
+            mkb: Vec::new(),
+            unit_key_ro: Vec::new(),
+            samples: Vec::new(),
+            volume_label: None,
+        };
+        let mut disc = {
+            let mut d = make_test_disc(1000, "UHD");
+            d.encrypted = true;
+            d.aacs = Some(aacs_with(Vec::new()));
+            d
+        };
+        let sources: Vec<Box<dyn KeySource>> = vec![Box::new(MatchedNoVid)];
+        let (ok, trace) = resolve_and_apply_traced(&sources, &inputs, &mut disc);
+        assert!(!ok);
+        assert_eq!(
+            trace.keys[0].path,
+            vec![KeyNode::MatchedDisc, KeyNode::NoVid],
+            "a matched-but-underivable disc must NOT collapse to `no entry`"
+        );
+        assert_eq!(
+            trace.keys[0].matched_entry.map(|m| m.has_media_key),
+            Some(true),
+            "the matched entry's shape must survive to the trace for logging"
+        );
+    }
+
+    /// Companion to the above: a matched entry with NO derivation material at all
+    /// gets the library's default `no derivable key` node (empty `miss_path`),
+    /// still distinct from a true miss.
+    #[test]
+    fn matched_with_no_material_renders_no_derivable_key() {
+        use crate::aacs::trace::KeyNode;
+        use crate::keysource::{
+            KeySource, ResolveCtx, UnitKeyResolution, resolve_and_apply_traced,
+        };
+
+        struct MatchedNoMaterial;
+        impl KeySource for MatchedNoMaterial {
+            fn get_unit_keys(
+                &self,
+                _ctx: &dyn ResolveCtx,
+            ) -> std::result::Result<Vec<crate::aacs::types::UnitKey>, crate::error::Error>
+            {
+                Ok(Vec::new())
+            }
+            fn resolve_unit_keys(
+                &self,
+                _ctx: &dyn ResolveCtx,
+            ) -> std::result::Result<UnitKeyResolution, crate::error::Error> {
+                Ok(UnitKeyResolution {
+                    matched: true,
+                    ..Default::default()
+                })
+            }
+        }
+
+        let inputs = crate::keysource::DiscInputs {
+            disc_hash: "0xMATCH".into(),
+            volume_id: [0u8; 16],
+            version: crate::aacs::mkb::AACS_MAJOR_UHD,
+            mkb: Vec::new(),
+            unit_key_ro: Vec::new(),
+            samples: Vec::new(),
+            volume_label: None,
+        };
+        let mut disc = {
+            let mut d = make_test_disc(1000, "UHD");
+            d.encrypted = true;
+            d.aacs = Some(aacs_with(Vec::new()));
+            d
+        };
+        let sources: Vec<Box<dyn KeySource>> = vec![Box::new(MatchedNoMaterial)];
+        let (_ok, trace) = resolve_and_apply_traced(&sources, &inputs, &mut disc);
+        assert_eq!(
+            trace.keys[0].path,
+            vec![KeyNode::MatchedDisc, KeyNode::NoDerivableKey],
+        );
+    }
+
    /// Same AACS-no-key disc under `--raw` (raw=true) must PROCEED — the user
    /// asked for the encrypted image and needs no key.
    #[test]
@@ -5716,7 +6351,6 @@ mod tests {
        // like resume / mapfile must be unaffected).
        assert!(super::aligned_unit_keys_validate(
            &[(0, [0x11u8; 16])],
-            None,
            &[],
            ContentFormat::BdTs
        ));
@@ -5735,7 +6369,6 @@ mod tests {
        ));
        assert!(super::aligned_unit_keys_validate(
            &[(0, [0x11u8; 16])],
-            None,
            &[clear.clone()],
            ContentFormat::BdTs
        ));
@@ -5751,21 +6384,18 @@ mod tests {
        // Right key -> de-scrambles -> accept (NO false reject of a good key).
        assert!(super::aligned_unit_keys_validate(
            &[(7, uk)],
-            None,
            std::slice::from_ref(&enc),
            ContentFormat::BdTs
        ));
        // Wrong key -> cannot de-scramble a scrambled sample -> reject.
        assert!(!super::aligned_unit_keys_validate(
            &[(7, [0x00u8; 16])],
-            None,
            std::slice::from_ref(&enc),
            ContentFormat::BdTs
        ));
        // Empty key set against a scrambled sample -> reject.
        assert!(!super::aligned_unit_keys_validate(
            &[],
-            None,
            &[enc],
            ContentFormat::BdTs
        ));
@@ -5804,7 +6434,6 @@ mod tests {
        // reject. This is the bug fix: previously this returned true.
        assert!(!super::aligned_unit_keys_validate(
            &[(0, uk0)],
-            None,
            &samples,
            ContentFormat::BdTs
        ));
@@ -5812,7 +6441,6 @@ mod tests {
        // Complete key set (both CPS units) -> accept.
        assert!(super::aligned_unit_keys_validate(
            &[(0, uk0), (1, uk1)],
-            None,
            &samples,
            ContentFormat::BdTs
        ));
@@ -5820,7 +6448,6 @@ mod tests {
        // Order-independent: covering key present anywhere in the set is fine.
        assert!(super::aligned_unit_keys_validate(
            &[(1, uk1), (0, uk0)],
-            None,
            &samples,
            ContentFormat::BdTs
        ));
@@ -116,6 +116,20 @@ pub struct Drive {
    halt: Arc<AtomicBool>,
    /// Event handler — fires for read errors and library-level state changes.
    event_fn: Option<Box<dyn Fn(Event) + Send>>,
+    /// The SINGLE AACS bus-encryption removal point. Decided ONCE from the
+    /// unlock/handshake result during [`crate::disc::Disc::scan`] and applied on
+    /// every read below this drive, so every reader above (sampler, mux, sweep,
+    /// validation) sees already-de-bussed content and never threads a bus key.
+    /// Defaults to [`BusStage::Passthrough`](crate::sector::bus_removal::BusStage)
+    /// (firmware/vendor unlock de-busses at the drive, or the disc carries no bus
+    /// encryption).
+    bus_stage: crate::sector::bus_removal::BusStage,
+    /// Encrypted-content extent map (sorted `(start_lba, sector_count)`) that
+    /// gates the host-key de-bus to content sectors — clear UDF/nav sectors read
+    /// during a whole-disc pass are left untouched. `None` = de-bus every read
+    /// sector (a content-only reader). Ignored entirely under
+    /// `BusStage::Passthrough`. See docs/drive-mod.md — bus-removal wiring.
+    bus_content_ranges: Option<Arc<[(u32, u32)]>>,
    /// Linux only: raw fd for the corresponding block device (`/dev/sr*`)
    /// used as a recovery fallback when SCSI READ via `/dev/sg*` returns
    /// an error. The kernel `sr_mod` driver auto-retries failed reads
@@ -157,11 +171,46 @@ impl Drive {
            device_path: device.to_string_lossy().to_string(),
            halt: Arc::new(AtomicBool::new(false)),
            event_fn: None,
+            bus_stage: crate::sector::bus_removal::BusStage::Passthrough,
+            bus_content_ranges: None,
            #[cfg(target_os = "linux")]
            block_dev_fd,
        })
    }

+    /// Set the SINGLE AACS bus-removal stage for this drive, decided once from
+    /// the unlock/handshake result. `AacsHostKey(rdk)` de-busses each content
+    /// read in software; `Passthrough` (a firmware/vendor unlock, or a non-bus
+    /// disc) is a no-op. Every reader above the drive inherits the result.
+    pub fn set_bus_stage(&mut self, stage: crate::sector::bus_removal::BusStage) {
+        self.bus_stage = stage;
+    }
+
+    /// Gate host-key de-bussing to the disc's encrypted-content extents (sorted
+    /// `(start_lba, sector_count)`), so clear UDF/nav sectors read during a
+    /// whole-disc pass are left untouched. Set after the disc structure is parsed
+    /// (see [`crate::disc::Disc::encrypted_content_ranges`]); unset means every
+    /// read sector is treated as content.
+    pub fn set_bus_content_ranges(&mut self, ranges: Arc<[(u32, u32)]>) {
+        self.bus_content_ranges = Some(ranges);
+    }
+
+    /// The SOLE application of AACS bus decryption in the read path: under a
+    /// host-key stage, de-bus the `data` that a raw read landed at `lba`, gated
+    /// to the encrypted-content ranges. `Passthrough` is a no-op, so the raw
+    /// `read`/`read_fua` used by internal callers stay bus-encrypted while
+    /// `SectorSource` readers above see plaintext content.
+    fn remove_bus_encryption(&self, lba: u32, data: &mut [u8]) {
+        if let crate::sector::bus_removal::BusStage::AacsHostKey(rdk) = &self.bus_stage {
+            crate::aacs::content::decrypt_bus_in_content(
+                data,
+                rdk,
+                lba,
+                self.bus_content_ranges.as_deref(),
+            );
+        }
+    }
+
    // Test-only constructor: build a `Drive` over an arbitrary `ScsiTransport`
    // (no profile, no platform driver, no block-device fallback) so
    // command-builder/response-parser logic can be exercised against a mock.
@@ -186,6 +235,8 @@ impl Drive {
            device_path: "test".to_string(),
            halt: Arc::new(AtomicBool::new(false)),
            event_fn: None,
+            bus_stage: crate::sector::bus_removal::BusStage::Passthrough,
+            bus_content_ranges: None,
            #[cfg(target_os = "linux")]
            block_dev_fd: None,
        }
@@ -1169,7 +1220,9 @@ impl SectorSource for Drive {
        buf: &mut [u8],
        recovery: bool,
    ) -> Result<usize> {
-        self.read(lba, count, buf, recovery)
+        let n = self.read(lba, count, buf, recovery)?;
+        self.remove_bus_encryption(lba, &mut buf[..n]);
+        Ok(n)
    }

    fn read_sectors_fua(
@@ -1180,7 +1233,9 @@ impl SectorSource for Drive {
        recovery: bool,
        fua: bool,
    ) -> Result<usize> {
-        self.read_fua(lba, count, buf, recovery, fua)
+        let n = self.read_fua(lba, count, buf, recovery, fua)?;
+        self.remove_bus_encryption(lba, &mut buf[..n]);
+        Ok(n)
    }

    fn set_speed(&mut self, kbs: u16) {
@@ -1519,6 +1574,208 @@ mod command_tests {
        Drive::from_transport_for_test(Box::new(FixedTransport { payload }))
    }

+    // AACS bus-removal tests (the drive's single de-bus point): a clear "content"
+    // buffer with plaintext first-16-of-each-sector (bus enc leaves those clear on
+    // the wire) and a known 16..2048 pattern; `sectors` exercises cross-sector gating.
+    fn clear_bus_content(sectors: usize) -> Vec<u8> {
+        let mut v = vec![0u8; sectors * 2048];
+        for (i, b) in v.iter_mut().enumerate() {
+            *b = (i as u8).wrapping_mul(31).wrapping_add(7);
+        }
+        v
+    }
+
+    // Passthrough (the default) is a no-op: every read byte comes back verbatim,
+    // even when the wire happens to be clear content.
+    #[test]
+    fn bus_passthrough_read_returns_bytes_unchanged() {
+        use crate::sector::SectorSource;
+        let clear = clear_bus_content(3);
+        let mut d = drive_with(clear.clone());
+        let mut got = vec![0u8; clear.len()];
+        let n = d.read_sectors(0, 3, &mut got, false).unwrap();
+        assert_eq!(n, clear.len());
+        assert_eq!(got, clear, "default Passthrough must not alter any byte");
+    }
+
+    // Host-key stage de-busses at read time: a bus-ENCRYPTED wire comes back as
+    // the known plaintext. MUTATION: leaving `bus_stage` Passthrough (dropping the
+    // de-bus call) returns ciphertext, so this goes red.
+    #[test]
+    fn bus_host_key_removes_bus_encryption_at_read() {
+        use crate::sector::SectorSource;
+        let rdk = [0x5Au8; 16];
+        let clear = clear_bus_content(3);
+        let mut wire = clear.clone();
+        crate::aacs::content::encrypt_bus(&mut wire, &rdk); // model the drive's forward bus transform
+        assert_ne!(wire, clear, "fixture must actually be bus-encrypted");
+
+        let mut d = drive_with(wire);
+        d.set_bus_stage(crate::sector::bus_removal::BusStage::AacsHostKey(rdk));
+        let mut got = vec![0u8; clear.len()];
+        let n = d.read_sectors(0, 3, &mut got, false).unwrap();
+        assert_eq!(n, clear.len());
+        assert_eq!(
+            got, clear,
+            "AacsHostKey must recover the plaintext byte-for-byte"
+        );
+    }
+
+    // The FUA read path applies the same single de-bus step (the per-sector
+    // recovery lever must not ship ciphertext).
+    #[test]
+    fn bus_host_key_removes_bus_encryption_on_fua_read() {
+        use crate::sector::SectorSource;
+        let rdk = [0x5Au8; 16];
+        let clear = clear_bus_content(3);
+        let mut wire = clear.clone();
+        crate::aacs::content::encrypt_bus(&mut wire, &rdk);
+
+        let mut d = drive_with(wire);
+        d.set_bus_stage(crate::sector::bus_removal::BusStage::AacsHostKey(rdk));
+        let mut got = vec![0u8; clear.len()];
+        let n = d.read_sectors_fua(0, 3, &mut got, false, true).unwrap();
+        assert_eq!(n, clear.len());
+        assert_eq!(got, clear, "the FUA path must de-bus too");
+    }
+
+    // Content-range gating: a sector OUTSIDE the encrypted-content extents is
+    // clear filesystem/nav and must pass through untouched — de-bussing it would
+    // corrupt plaintext. LBA 0 is outside content [300,303).
+    #[test]
+    fn bus_content_ranges_pass_through_sectors_outside_content() {
+        use crate::sector::SectorSource;
+        let rdk = [0x5Au8; 16];
+        let clear = clear_bus_content(1); // clear filesystem sector on the wire
+        let mut d = drive_with(clear.clone());
+        d.set_bus_stage(crate::sector::bus_removal::BusStage::AacsHostKey(rdk));
+        d.set_bus_content_ranges(std::sync::Arc::from(
+            vec![(300u32, 3u32)].into_boxed_slice(),
+        ));
+        let mut got = vec![0u8; clear.len()];
+        // LBA 0 is outside content → no de-bus → bytes unchanged.
+        let n = d.read_sectors(0, 1, &mut got, false).unwrap();
+        assert_eq!(n, clear.len());
+        assert_eq!(
+            got, clear,
+            "a sector outside content must pass through untouched"
+        );
+    }
+
+    // The complement: a bus-encrypted sector INSIDE the content map is de-bussed.
+    #[test]
+    fn bus_content_ranges_debus_sectors_inside_content() {
+        use crate::sector::SectorSource;
+        let rdk = [0x33u8; 16];
+        let clear = clear_bus_content(3);
+        let mut wire = clear.clone();
+        crate::aacs::content::encrypt_bus(&mut wire, &rdk);
+        let mut d = drive_with(wire);
+        d.set_bus_stage(crate::sector::bus_removal::BusStage::AacsHostKey(rdk));
+        d.set_bus_content_ranges(std::sync::Arc::from(
+            vec![(300u32, 3u32)].into_boxed_slice(),
+        ));
+        let mut got = vec![0u8; clear.len()];
+        // Read the 3 content sectors at LBA 300 → all inside → de-bussed to plaintext.
+        let n = d.read_sectors(300, 3, &mut got, false).unwrap();
+        assert_eq!(n, clear.len());
+        assert_eq!(got, clear, "content sectors must be de-bussed to plaintext");
+    }
+
+    // Partial gating within one read: content [301,302) covers only the middle
+    // sector of a 3-sector read at LBA 300. Only that sector is de-bussed; the
+    // clear neighbours (300, 302) pass through untouched.
+    #[test]
+    fn bus_content_ranges_gate_per_sector_within_a_read() {
+        use crate::sector::SectorSource;
+        let rdk = [0x44u8; 16];
+        // Sector 1 is bus-encrypted content; sectors 0 and 2 are clear on the wire.
+        let clear = clear_bus_content(3);
+        let mut wire = clear.clone();
+        let mut mid = clear[2048..4096].to_vec();
+        crate::aacs::content::encrypt_bus(&mut mid, &rdk); // encrypt only the middle sector's body
+        wire[2048..4096].copy_from_slice(&mid);
+
+        let mut d = drive_with(wire);
+        d.set_bus_stage(crate::sector::bus_removal::BusStage::AacsHostKey(rdk));
+        d.set_bus_content_ranges(std::sync::Arc::from(
+            vec![(301u32, 1u32)].into_boxed_slice(),
+        ));
+        let mut got = vec![0u8; clear.len()];
+        d.read_sectors(300, 3, &mut got, false).unwrap();
+        // All three sectors come back as the known plaintext: 0 and 2 were clear
+        // and untouched; 1 was de-bussed back to clear.
+        assert_eq!(
+            got, clear,
+            "only the in-range sector is de-bussed; clear neighbours untouched"
+        );
+    }
+
+    // F1 fail-safe: an AacsHostKey stage with an EMPTY content map must de-bus
+    // NOTHING (empty `Some([])`), not everything — Disc::scan always installs the
+    // map now, so a host-key disc that parsed no titles leaves clear sectors alone.
+    #[test]
+    fn bus_empty_content_ranges_debus_nothing() {
+        use crate::sector::SectorSource;
+        let rdk = [0x7Eu8; 16];
+        let clear = clear_bus_content(2);
+        let mut wire = clear.clone();
+        crate::aacs::content::encrypt_bus(&mut wire, &rdk);
+        let mut d = drive_with(wire.clone());
+        d.set_bus_stage(crate::sector::bus_removal::BusStage::AacsHostKey(rdk));
+        // Empty map = "no content anywhere" → de-bus nothing (fail-safe).
+        d.set_bus_content_ranges(std::sync::Arc::from(
+            Vec::<(u32, u32)>::new().into_boxed_slice(),
+        ));
+        let mut got = vec![0u8; clear.len()];
+        d.read_sectors(300, 2, &mut got, false).unwrap();
+        assert_eq!(
+            got, wire,
+            "empty content map must leave every sector untouched (still bus-encrypted), \
+             never de-bus clear bytes into garbage"
+        );
+    }
+
+    // scan()'s handshake→bus_stage wiring, via the `wire_bus_removal` seam. CERT
+    // route: a Some(rdk) handshake arms AacsHostKey + installs the content map, so
+    // an in-range bus-encrypted sector is de-bussed to plaintext.
+    #[test]
+    fn wire_bus_removal_cert_route_arms_host_key_and_ranges() {
+        use crate::sector::SectorSource;
+        let rdk = [0x6Bu8; 16];
+        let clear = clear_bus_content(1);
+        let mut wire = clear.clone();
+        crate::aacs::content::encrypt_bus(&mut wire, &rdk);
+        let mut d = drive_with(wire);
+        crate::disc::Disc::wire_bus_removal(&mut d, Some(rdk), vec![(300u32, 3u32)]);
+        let mut got = vec![0u8; clear.len()];
+        d.read_sectors(300, 1, &mut got, false).unwrap();
+        assert_eq!(
+            got, clear,
+            "Some(read_data_key) must arm AacsHostKey + ranges so content is de-bussed"
+        );
+    }
+
+    // FIRMWARE/vendor route: a None handshake maps to Passthrough, so even an
+    // in-range sector is NOT de-bussed. MUTATION: mapping None to AacsHostKey
+    // would corrupt these bytes here.
+    #[test]
+    fn wire_bus_removal_firmware_route_is_passthrough() {
+        use crate::sector::SectorSource;
+        let rdk = [0x6Bu8; 16];
+        let clear = clear_bus_content(1);
+        let mut wire = clear.clone();
+        crate::aacs::content::encrypt_bus(&mut wire, &rdk); // still bus-encrypted on the wire
+        let mut d = drive_with(wire.clone());
+        crate::disc::Disc::wire_bus_removal(&mut d, None, vec![(300u32, 3u32)]);
+        let mut got = vec![0u8; clear.len()];
+        d.read_sectors(300, 1, &mut got, false).unwrap();
+        assert_eq!(
+            got, wire,
+            "None must map to Passthrough — no host-side de-bus, bytes returned verbatim"
+        );
+    }
+
    #[test]
    fn read_capacity_normal_adds_one() {
        // last_lba = 0x0000_0063 (99) → capacity 100 sectors.
@@ -226,6 +226,33 @@ impl ResolveCtx for DiscInputsCtx<'_> {
    }
 }

+/// The de-conflated result of a source's unit-key resolution: the keys it
+/// produced (empty when none) PLUS why it produced them — so a caller can tell
+/// a genuine "no entry for this disc" from a MATCHED disc that yielded no
+/// derivable key. The bare `Vec` of [`KeySource::get_unit_keys`] cannot make
+/// that distinction; [`KeySource::resolve_unit_keys`] carries it.
+#[derive(Debug, Clone, Default)]
+pub struct UnitKeyResolution {
+    /// Terminal Unit Keys produced (empty = this source yielded none).
+    pub keys: Vec<UnitKey>,
+    /// The source matched this disc in its store (by hash / VID), even if it
+    /// then derived no key. `false` = a genuine miss ("no entry").
+    pub matched: bool,
+    /// When `matched` and `keys` is empty: the derivation nodes walked AFTER the
+    /// implicit `MatchedDisc` node — e.g. `[NoVid]` (had a Media Key, no VID) or
+    /// `[NoDerivableKey]` (no material at all). Empty ⇒ the caller supplies a
+    /// bare `NoDerivableKey`. Ignored unless `matched` and `keys` is empty.
+    pub miss_path: Vec<crate::aacs::trace::KeyNode>,
+    /// When `matched`: a booleans-and-lengths shape of the matched entry (no key
+    /// material), for the application to log. `None` for a miss or a source kind
+    /// with no such shape.
+    pub matched_entry: Option<crate::aacs::trace::MatchedEntry>,
+    /// Number of per-disc entries loaded in this source's store, when known — so
+    /// a true-miss verdict can name the store size. `None` for a source that
+    /// carries no such count.
+    pub store_entries: Option<usize>,
+}
+
 /// A key source: an adapter over a backing store that resolves a disc's terminal
 /// Unit Keys.
 ///
@@ -240,6 +267,21 @@ pub trait KeySource {
    /// `Vec` is a genuine "no key here"; `Err` is a source failure.
    fn get_unit_keys(&self, ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, Error>;

+    /// De-conflated counterpart to [`get_unit_keys`](Self::get_unit_keys):
+    /// besides the keys, report whether this disc MATCHED the source's store and
+    /// (on a keyless match) why nothing was derivable — so the trace can render
+    /// `matched disc > no VID > NO KEY` instead of a flat `no entry`.
+    ///
+    /// The default is coarse: forward to [`get_unit_keys`](Self::get_unit_keys)
+    /// and report `matched = false`. A source that keys on a per-disc identity
+    /// (a keydb) overrides this to set `matched`/`miss_path`/`matched_entry`.
+    fn resolve_unit_keys(&self, ctx: &dyn ResolveCtx) -> Result<UnitKeyResolution, Error> {
+        Ok(UnitKeyResolution {
+            keys: self.get_unit_keys(ctx)?,
+            ..Default::default()
+        })
+    }
+
    /// Resolve this disc's AACS 2.1 forensic index keys — the per-index keys the
    /// base Unit Key cannot open (see [`crate::aacs::segment`]) — ordered by
    /// forensic index (element `i` carries `UnitKey.idx == i`, forensic index
@@ -312,10 +354,11 @@ pub fn resolve_and_apply_traced(
    for source in sources {
        // `who` is the source's own stable identifier — no enum to map back to.
        let who = source.label().to_string();
-        match source.get_unit_keys(&ctx) {
-            Ok(uks) if !uks.is_empty() => {
+        match source.resolve_unit_keys(&ctx) {
+            Ok(r) if !r.keys.is_empty() => {
                // Positional index → canonical CPS-unit number (position + 1).
-                let unit_keys: Vec<(u32, [u8; 16])> = uks
+                let unit_keys: Vec<(u32, [u8; 16])> = r
+                    .keys
                    .iter()
                    .map(|uk| (uk.idx.saturating_add(1), uk.key))
                    .collect();
@@ -327,6 +370,8 @@ pub fn resolve_and_apply_traced(
                        who,
                        path: vec![KeyNode::FoundUnitKeys, KeyNode::DerivedUnitKeys],
                        outcome: KeyOutcome::Resolved,
+                        matched_entry: r.matched_entry,
+                        store_entries: r.store_entries,
                    });
                    return (true, trace);
                }
@@ -335,15 +380,31 @@ pub fn resolve_and_apply_traced(
                    who,
                    path: vec![KeyNode::FoundUnitKeys],
                    outcome: KeyOutcome::NoKey,
+                    matched_entry: r.matched_entry,
+                    store_entries: r.store_entries,
                });
            }
-            // The source ANSWERED and holds nothing for this disc. This — and
-            // only this — is `NoEntry`: the claim "I looked, it is not there".
-            Ok(_) => {
+            // The source ANSWERED with no keys. De-conflate a MATCHED-but-
+            // underivable disc from a true miss (`NoEntry`); a source that can't
+            // tell them apart (the trait default) reports `matched = false`.
+            Ok(r) => {
+                let path = if r.matched {
+                    let mut p = vec![KeyNode::MatchedDisc];
+                    if r.miss_path.is_empty() {
+                        p.push(KeyNode::NoDerivableKey);
+                    } else {
+                        p.extend(r.miss_path);
+                    }
+                    p
+                } else {
+                    vec![KeyNode::NoEntry]
+                };
                trace.keys.push(KeyStep {
                    who,
-                    path: vec![KeyNode::NoEntry],
+                    path,
                    outcome: KeyOutcome::NoKey,
+                    matched_entry: r.matched_entry,
+                    store_entries: r.store_entries,
                });
            }
            // The source could NOT answer (unreachable/errored/refused), so path is
@@ -357,6 +418,8 @@ pub fn resolve_and_apply_traced(
                    who,
                    path: Vec::new(),
                    outcome: KeyOutcome::NoKey,
+                    matched_entry: None,
+                    store_entries: None,
                });
            }
        }
@@ -0,0 +1,719 @@
+//! Generic BD-J feature-playlist resolver — the issue #45 "menu-walk"
+//! authoritative layer, run when no framework parser surfaced a manifest hint.
+//!
+//! Two tiers, most reliable first:
+//!
+//! * **Tier 1 — jar-space resource sweep (High confidence).** Newer discs embed
+//!   the same `dcx.xml` / `playlists.xml` / `*.properties` manifests that Fox
+//!   and Paramount ship loose, but INSIDE a `/BDMV/JAR/*.jar` instead. The
+//!   feature id is still statically recoverable: reuse
+//!   [`fox::feature_hint`](super::fox::feature_hint) /
+//!   [`paramount::feature_hint_from_xml`](super::paramount::feature_hint_from_xml).
+//!
+//! * **Tier 2 — autostart-Xlet locator scan (best-effort, Medium).** Parse the
+//!   `/BDMV/BDJO/*.bdjo` Application Management Table for the AUTOSTART app's
+//!   jar(s) ([`crate::bdnav::bdjo`]), harvest `NNNNN.mpls` / `bd://…PLAYLIST:N`
+//!   String constants from that jar's `.class` constant pools, intersect them
+//!   with the real `/BDMV/PLAYLIST/*.mpls` set, and disambiguate by parsed
+//!   duration — the feature is a single candidate that dominates the runner-up
+//!   and carries multiple audio streams. A hint is emitted ONLY when a single
+//!   dominant candidate survives; integer-only evidence never emits.
+//!
+//! Everything failing here (modern-Fox pure-bytecode `StandardMenuXlet` with no
+//! usable `.mpls` string, no usable integer constant) is left to the chapter
+//! failsafe in `disc::mod`. This module is read-only, bounded, and never panics
+//! (the caller also wraps it in `catch_unwind`).
+
+use super::class_reader::CpInfo;
+use super::{FeaturePlaylistHint, fox, jar, paramount};
+use crate::bdnav::bdjo;
+use crate::sector::SectorSource;
+use crate::udf::UdfFs;
+use std::collections::HashSet;
+
+/// Resolve the disc's feature playlist by walking the BD-J jar space. Returns a
+/// hint only when one is unambiguously recoverable; `None` otherwise (defer to
+/// the failsafe).
+pub(crate) fn resolve(reader: &mut dyn SectorSource, udf: &UdfFs) -> Option<FeaturePlaylistHint> {
+    if let Some(hint) = tier1_manifest_sweep(reader, udf).filter(|h| !h.is_empty()) {
+        tracing::info!(?hint, "bdj menu-walk: Tier-1 embedded manifest hint");
+        return Some(hint);
+    }
+    if let Some(hint) = tier2_locator_scan(reader, udf).filter(|h| !h.is_empty()) {
+        tracing::info!(?hint, "bdj menu-walk: Tier-2 autostart-Xlet locator hint");
+        return Some(hint);
+    }
+    None
+}
+
+// ── Tier 1 ───────────────────────────────────────────────────────────────────
+
+// Cap on bytes decoded from a single embedded manifest as UTF-8. Manifests are
+// small; a hostile jar entry can't force an unbounded scan.
+const MAX_MANIFEST_BYTES: usize = 4 * 1024 * 1024;
+
+fn tier1_manifest_sweep(reader: &mut dyn SectorSource, udf: &UdfFs) -> Option<FeaturePlaylistHint> {
+    jar::for_each_jar(reader, udf, |_entry, archive| {
+        jar::try_each_resource(archive, |name, bytes| {
+            if bytes.len() > MAX_MANIFEST_BYTES {
+                return None;
+            }
+            let text = std::str::from_utf8(bytes).ok()?;
+            hint_from_manifest(name, text)
+        })
+    })
+}
+
+// Derive a feature hint from one embedded manifest, dispatched by filename.
+fn hint_from_manifest(name: &str, text: &str) -> Option<FeaturePlaylistHint> {
+    let lower = name.to_ascii_lowercase();
+    if lower.ends_with("dcx.xml") {
+        fox::feature_hint(text)
+    } else if lower.ends_with("playlists.xml") {
+        paramount::feature_hint_from_xml(text)
+    } else if lower.ends_with(".properties") || lower.ends_with(".version") {
+        props_hint(text)
+    } else {
+        None
+    }
+}
+
+// Scan a `key=value` properties/version manifest for a feature-playlist id. A
+// key naming both a feature/playlist AND an id (or playlist) whose value carries
+// a u16 playlist number yields the canonical `NNNNN.mpls` hint.
+fn props_hint(text: &str) -> Option<FeaturePlaylistHint> {
+    for line in text.lines() {
+        let line = line.trim();
+        if line.starts_with('#') || line.starts_with('!') {
+            continue;
+        }
+        let Some((key, val)) = line.split_once('=') else {
+            continue;
+        };
+        let key = key.trim().to_ascii_lowercase();
+        let names_playlist = key.contains("feature") || key.contains("playlist");
+        let names_id = key.contains("id") || key.contains("playlist");
+        if !(names_playlist && names_id) {
+            continue;
+        }
+        if let Some(id) = playlist_id_from_str(val.trim()) {
+            return Some(hint_for(id));
+        }
+    }
+    None
+}
+
+// ── Tier 2 ───────────────────────────────────────────────────────────────────
+
+// Cap on distinct harvested playlist-id candidates — bounds work on a hostile
+// jar. Real menus reference a handful.
+const MAX_CANDIDATES: usize = 1024;
+
+// The feature must run at least this many times longer than the runner-up to be
+// unambiguous; a closer field is not resolvable here and defers to the failsafe.
+const DOMINANCE_RATIO: f64 = 1.5;
+
+fn tier2_locator_scan(reader: &mut dyn SectorSource, udf: &UdfFs) -> Option<FeaturePlaylistHint> {
+    // 1. AUTOSTART app's jar(s) from the BDJO AMT. Empty → scan every jar.
+    let targets = autostart_jar_ids(reader, udf);
+
+    // 2. Harvest playlist-id candidates from those jars' `.class` constant pools.
+    let candidates = harvest_candidates(reader, udf, &targets);
+    if candidates.is_empty() {
+        return None;
+    }
+
+    // 3. Intersect with the playlists that actually exist on the disc.
+    let real = real_playlist_ids(udf);
+    let hits: Vec<u16> = candidates
+        .into_iter()
+        .filter(|id| real.contains(id))
+        .collect();
+    if hits.is_empty() {
+        return None;
+    }
+
+    // 4. Score each survivor by (duration secs, primary-audio count).
+    let mut scored: Vec<(u16, u64, usize)> = hits
+        .into_iter()
+        .filter_map(|id| mpls_stats(reader, udf, id).map(|(secs, aud)| (id, secs, aud)))
+        .collect();
+    if scored.is_empty() {
+        return None;
+    }
+    // Longest first; lowest id breaks a duration tie (deterministic).
+    scored.sort_by(|a, b| b.1.cmp(&a.1).then(a.0.cmp(&b.0)));
+
+    // 5. Emit only a single dominant, multi-audio candidate.
+    choose_dominant(&scored).map(hint_for)
+}
+
+// The dominant feature id, or None when the field is ambiguous. Requires the top
+// candidate to carry multiple audio streams and (when a runner-up exists) to run
+// at least DOMINANCE_RATIO times longer than it.
+fn choose_dominant(scored: &[(u16, u64, usize)]) -> Option<u16> {
+    let (top_id, top_secs, top_aud) = *scored.first()?;
+    if top_aud < 2 {
+        return None;
+    }
+    match scored.get(1) {
+        None => Some(top_id), // single candidate: unambiguous
+        Some(&(_, runner_secs, _)) => {
+            (top_secs as f64 >= DOMINANCE_RATIO * runner_secs as f64).then_some(top_id)
+        }
+    }
+}
+
+// The jar ids of every AUTOSTART application across all `.bdjo` files. Empty when
+// there is no readable BDJO — Tier-2 then scans every jar.
+fn autostart_jar_ids(reader: &mut dyn SectorSource, udf: &UdfFs) -> HashSet<String> {
+    let mut out = HashSet::new();
+    let Some(dir) = udf.find_dir("/BDMV/BDJO") else {
+        return out;
+    };
+    let names: Vec<String> = dir
+        .entries
+        .iter()
+        .filter(|e| !e.is_dir && e.name.to_ascii_lowercase().ends_with(".bdjo"))
+        .map(|e| e.name.clone())
+        .collect();
+    for name in names {
+        let path = format!("/BDMV/BDJO/{name}");
+        let Ok(data) = udf.read_file(reader, &path) else {
+            continue;
+        };
+        let Some(apps) = bdjo::parse(&data) else {
+            continue;
+        };
+        for app in apps.iter().filter(|a| a.is_autostart()) {
+            for id in app.jar_ids() {
+                out.insert(id);
+            }
+        }
+    }
+    out
+}
+
+// Harvest playlist-id candidates from `.class` constant pools. When `targets` is
+// non-empty, only jars whose id is in it are scanned (the autostart classpath);
+// otherwise every jar is scanned.
+fn harvest_candidates(
+    reader: &mut dyn SectorSource,
+    udf: &UdfFs,
+    targets: &HashSet<String>,
+) -> HashSet<u16> {
+    let mut ids = HashSet::new();
+    let _: Option<()> = jar::for_each_jar(reader, udf, |entry_name, archive| {
+        if !targets.is_empty() && !targets.contains(jar_stem(entry_name)) {
+            return None;
+        }
+        jar::for_each_class(archive, |_class_name, class| {
+            for (_, cp) in class.constant_pool.iter() {
+                if let CpInfo::Utf8(s) = cp {
+                    scan_locator_ids(s, &mut ids);
+                }
+            }
+        });
+        None
+    });
+    ids
+}
+
+// The jar id of a `/BDMV/JAR/*.jar` entry name ("00000.jar" -> "00000").
+fn jar_stem(entry_name: &str) -> &str {
+    let lower = entry_name.to_ascii_lowercase();
+    if lower.ends_with(".jar") {
+        &entry_name[..entry_name.len() - 4]
+    } else {
+        entry_name
+    }
+}
+
+// Harvest playlist ids from one string: `NNNNN.mpls` filenames and
+// `PLAYLIST:NNNNN` locator constants. Integer-only evidence is intentionally NOT
+// harvested here — the design leaves bare integers to the failsafe.
+fn scan_locator_ids(s: &str, out: &mut HashSet<u16>) {
+    if out.len() >= MAX_CANDIDATES {
+        return;
+    }
+    let lower = s.to_ascii_lowercase();
+    let bytes = s.as_bytes(); // same byte positions as `lower` (ASCII case only)
+
+    // `NNNNN.mpls`: digits immediately preceding a ".mpls".
+    let mut from = 0;
+    while let Some(rel) = lower[from..].find(".mpls") {
+        let at = from + rel;
+        let mut start = at;
+        while start > 0 && bytes[start - 1].is_ascii_digit() {
+            start -= 1;
+        }
+        if start < at
+            && let Ok(id) = s[start..at].parse::<u16>()
+        {
+            out.insert(id);
+            if out.len() >= MAX_CANDIDATES {
+                return;
+            }
+        }
+        from = at + ".mpls".len();
+    }
+
+    // `PLAYLIST:NNNNN`: digits immediately following a "playlist:" token.
+    let mut from = 0;
+    while let Some(rel) = lower[from..].find("playlist:") {
+        let at = from + rel + "playlist:".len();
+        let mut end = at;
+        while end < bytes.len() && bytes[end].is_ascii_digit() {
+            end += 1;
+        }
+        if end > at
+            && let Ok(id) = s[at..end].parse::<u16>()
+        {
+            out.insert(id);
+            if out.len() >= MAX_CANDIDATES {
+                return;
+            }
+        }
+        from = at.max(from + 1);
+    }
+}
+
+// The playlist ids present as `/BDMV/PLAYLIST/NNNNN.mpls`.
+fn real_playlist_ids(udf: &UdfFs) -> HashSet<u16> {
+    let mut out = HashSet::new();
+    let Some(dir) = udf.find_dir("/BDMV/PLAYLIST") else {
+        return out;
+    };
+    for e in &dir.entries {
+        if e.is_dir || !e.name.to_ascii_lowercase().ends_with(".mpls") {
+            continue;
+        }
+        let stem = &e.name[..e.name.len() - ".mpls".len()];
+        if let Ok(id) = stem.parse::<u16>() {
+            out.insert(id);
+        }
+    }
+    out
+}
+
+// (duration_secs, primary-audio-stream count) for one playlist id, or None if it
+// cannot be read/parsed.
+fn mpls_stats(reader: &mut dyn SectorSource, udf: &UdfFs, id: u16) -> Option<(u64, usize)> {
+    let path = format!("/BDMV/PLAYLIST/{id:05}.mpls");
+    let data = udf.read_file(reader, &path).ok()?;
+    let pl = crate::mpls::parse(&data).ok()?;
+    let ticks: u64 = pl
+        .play_items
+        .iter()
+        .map(|pi| pi.out_time.saturating_sub(pi.in_time) as u64)
+        .sum();
+    let secs = ticks / 45_000;
+    // stream_type 2 == primary audio (see mpls::StreamEntry).
+    let audio = pl.streams.iter().filter(|s| s.stream_type == 2).count();
+    Some((secs, audio))
+}
+
+// ── Shared helpers ───────────────────────────────────────────────────────────
+
+fn hint_for(id: u16) -> FeaturePlaylistHint {
+    FeaturePlaylistHint {
+        playlist_id: Some(id),
+        filename: Some(format!("{id:05}.mpls")),
+    }
+}
+
+// A playlist id from a free-form string value: keep leading digits, parse u16.
+fn playlist_id_from_str(v: &str) -> Option<u16> {
+    let digits: String = v.chars().take_while(|c| c.is_ascii_digit()).collect();
+    let digits = if digits.is_empty() {
+        v.chars().filter(|c| c.is_ascii_digit()).collect()
+    } else {
+        digits
+    };
+    digits.parse::<u16>().ok()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::udf::fixture::{DirSpec, FileSpec, MemDisc, build_udf_skeleton, file_with, lay_dir};
+    use std::io::{Cursor, Write as _};
+
+    // ── scan_locator_ids ────────────────────────────────────────────────────
+    #[test]
+    fn scan_finds_mpls_filenames() {
+        let mut ids = HashSet::new();
+        scan_locator_ids("bd://JAR:00000/00800.mpls", &mut ids);
+        assert!(ids.contains(&800));
+        let mut ids = HashSet::new();
+        scan_locator_ids("00243.MPLS", &mut ids);
+        assert!(ids.contains(&243));
+    }
+
+    #[test]
+    fn scan_finds_playlist_locator_constants() {
+        let mut ids = HashSet::new();
+        scan_locator_ids("bd://0.PLAYLIST:00800", &mut ids);
+        assert!(ids.contains(&800));
+    }
+
+    #[test]
+    fn scan_ignores_bare_integers() {
+        // An integer-only string carries no ".mpls"/"PLAYLIST:" locator, so it
+        // must NOT become a candidate — bare integers defer to the failsafe.
+        let mut ids = HashSet::new();
+        scan_locator_ids("800", &mut ids);
+        scan_locator_ids("theNumberIs 00800 done", &mut ids);
+        assert!(ids.is_empty());
+    }
+
+    // ── choose_dominant ─────────────────────────────────────────────────────
+    #[test]
+    fn dominant_single_multi_audio_candidate_wins() {
+        assert_eq!(choose_dominant(&[(800, 7000, 6)]), Some(800));
+    }
+
+    #[test]
+    fn dominant_requires_multiple_audio() {
+        // A lone candidate with a single audio stream is not a feature.
+        assert_eq!(choose_dominant(&[(800, 7000, 1)]), None);
+    }
+
+    #[test]
+    fn dominant_needs_1_5x_over_runner_up() {
+        // 7000 vs 5000 = 1.4x → ambiguous → None.
+        assert_eq!(choose_dominant(&[(800, 7000, 6), (801, 5000, 6)]), None);
+        // 7000 vs 4000 = 1.75x → dominant.
+        assert_eq!(
+            choose_dominant(&[(800, 7000, 6), (801, 4000, 6)]),
+            Some(800)
+        );
+    }
+
+    #[test]
+    fn dominant_two_equal_durations_is_none() {
+        assert_eq!(choose_dominant(&[(800, 7000, 6), (801, 7000, 6)]), None);
+    }
+
+    // ── props_hint ──────────────────────────────────────────────────────────
+    #[test]
+    fn props_hint_reads_feature_playlist_key() {
+        let text = "menu.jar=00001\nfeature.playlist.id=00800\nfoo=bar\n";
+        let h = props_hint(text).expect("hint");
+        assert_eq!(h.playlist_id, Some(800));
+        assert_eq!(h.filename.as_deref(), Some("00800.mpls"));
+    }
+
+    #[test]
+    fn props_hint_ignores_unrelated_keys() {
+        assert!(props_hint("version=1\nbuild=42\n").is_none());
+    }
+
+    // ── mpls fixture builder (compact single-play-item playlist) ─────────────
+    fn audio_stream_entry(pid: u16) -> Vec<u8> {
+        let mut out = vec![3u8, 0x01]; // se_len, type = PlayItem clip
+        out.extend_from_slice(&pid.to_be_bytes());
+        // attrs: coding_type(TrueHD) + (5.1<<4|48k) + language
+        let attrs = [0x83u8, (6 << 4) | 1, b'e', b'n', b'g'];
+        out.push(attrs.len() as u8);
+        out.extend_from_slice(&attrs);
+        out
+    }
+
+    // A playlist: one play item of `secs` seconds with `n_audio` audio streams.
+    fn build_mpls(secs: u32, n_audio: u8) -> Vec<u8> {
+        let playlist_start: u32 = 40;
+        let mut buf = Vec::new();
+        buf.extend_from_slice(b"MPLS0200");
+        buf.extend_from_slice(&playlist_start.to_be_bytes());
+        buf.extend_from_slice(&[0u8; 28]); // mark_start + pad to 40
+
+        let pl_start = buf.len();
+        buf.extend_from_slice(&[0u8; 4]); // length placeholder
+        buf.extend_from_slice(&[0u8; 2]); // reserved
+        buf.extend_from_slice(&1u16.to_be_bytes()); // num_play_items
+        buf.extend_from_slice(&[0u8; 2]); // num_sub_paths
+
+        let mut item = Vec::new();
+        item.extend_from_slice(b"00000"); // clip_id
+        item.extend_from_slice(b"M2TS");
+        item.push(0); // reserved
+        item.push(0); // is_multi_angle + connection_condition
+        item.push(0); // stc_id
+        item.extend_from_slice(&0u32.to_be_bytes()); // in_time
+        item.extend_from_slice(&(secs * 45000).to_be_bytes()); // out_time
+        item.extend_from_slice(&[0u8; 8]); // UO mask
+        item.push(0); // misc
+        item.push(0); // still_mode
+        item.extend_from_slice(&[0u8; 2]); // still_time
+
+        // STN table
+        let stn_start = item.len();
+        item.extend_from_slice(&[0u8; 2]); // length placeholder
+        item.extend_from_slice(&[0u8; 2]); // reserved
+        item.push(0); // n_video
+        item.push(n_audio); // n_audio
+        item.extend_from_slice(&[0u8; 6]); // pg/ig/sec.../dv counts
+        item.extend_from_slice(&[0u8; 4]); // reserved
+        for i in 0..n_audio {
+            item.extend_from_slice(&audio_stream_entry(0x1100 + i as u16));
+        }
+        let stn_len = (item.len() - stn_start - 2) as u16;
+        item[stn_start..stn_start + 2].copy_from_slice(&stn_len.to_be_bytes());
+
+        buf.extend_from_slice(&(item.len() as u16).to_be_bytes());
+        buf.extend_from_slice(&item);
+
+        let pl_len = (buf.len() - pl_start - 4) as u32;
+        buf[pl_start..pl_start + 4].copy_from_slice(&pl_len.to_be_bytes());
+        buf
+    }
+
+    // Minimal `.class` carrying the given Utf8 constants (no fields/methods).
+    fn build_class(utf8: &[&str]) -> Vec<u8> {
+        let mut out = Vec::new();
+        out.extend_from_slice(&0xCAFEBABEu32.to_be_bytes());
+        out.extend_from_slice(&0u16.to_be_bytes()); // minor
+        out.extend_from_slice(&52u16.to_be_bytes()); // major
+        out.extend_from_slice(&((utf8.len() + 1) as u16).to_be_bytes());
+        for s in utf8 {
+            out.push(1);
+            out.extend_from_slice(&(s.len() as u16).to_be_bytes());
+            out.extend_from_slice(s.as_bytes());
+        }
+        out.extend_from_slice(&[0u8; 14]); // access/this/super/interfaces/fields/methods/attrs (7 u16)
+        out
+    }
+
+    // Zip entries into an in-memory jar (Stored).
+    fn build_jar(entries: &[(&str, Vec<u8>)]) -> Vec<u8> {
+        let mut buf = Vec::new();
+        {
+            let mut w = zip::ZipWriter::new(Cursor::new(&mut buf));
+            let opts = zip::write::SimpleFileOptions::default()
+                .compression_method(zip::CompressionMethod::Stored);
+            for (name, data) in entries {
+                w.start_file(*name, opts).unwrap();
+                w.write_all(data).unwrap();
+            }
+            w.finish().unwrap();
+        }
+        buf
+    }
+
+    // Lay a BDMV tree with the given PLAYLIST + JAR (+ optional BDJO) files onto
+    // an in-memory disc and return (disc, udf). LBAs are hand-assigned and never
+    // overlap.
+    fn build_disc(
+        playlists: Vec<(&str, Vec<u8>)>,
+        jars: Vec<(&str, Vec<u8>)>,
+        bdjos: Vec<(&str, Vec<u8>)>,
+    ) -> (MemDisc, crate::udf::UdfFs) {
+        let mut icb = 100u32;
+        let mut data = 2000u32;
+        let mut next = |sz: u64| {
+            let (i, d) = (icb, data);
+            icb += 1;
+            data += (sz / 2048) as u32 + 2;
+            (i, d)
+        };
+
+        let mk = |files: Vec<(&str, Vec<u8>)>, next: &mut dyn FnMut(u64) -> (u32, u32)| {
+            files
+                .into_iter()
+                .map(|(name, bytes)| {
+                    let (i, d) = next(bytes.len() as u64);
+                    file_with(name, i, d, bytes, true)
+                })
+                .collect::<Vec<FileSpec>>()
+        };
+
+        let playlist_dir = DirSpec {
+            name: "PLAYLIST".to_string(),
+            icb_lba: 50,
+            dir_data_lba: 51,
+            files: mk(playlists, &mut next),
+            subdirs: vec![],
+        };
+        let jar_dir = DirSpec {
+            name: "JAR".to_string(),
+            icb_lba: 52,
+            dir_data_lba: 53,
+            files: mk(jars, &mut next),
+            subdirs: vec![],
+        };
+        let mut subdirs = vec![playlist_dir, jar_dir];
+        if !bdjos.is_empty() {
+            subdirs.push(DirSpec {
+                name: "BDJO".to_string(),
+                icb_lba: 54,
+                dir_data_lba: 55,
+                files: mk(bdjos, &mut next),
+                subdirs: vec![],
+            });
+        }
+        let bdmv = DirSpec {
+            name: "BDMV".to_string(),
+            icb_lba: 12,
+            dir_data_lba: 13,
+            files: vec![],
+            subdirs,
+        };
+        let root = DirSpec {
+            name: String::new(),
+            icb_lba: 10,
+            dir_data_lba: 11,
+            files: vec![],
+            subdirs: vec![bdmv],
+        };
+        let mut disc = MemDisc::new();
+        build_udf_skeleton(&mut disc, 10);
+        lay_dir(&mut disc, &root);
+        let udf = crate::udf::read_filesystem(&mut disc).expect("fs");
+        (disc, udf)
+    }
+
+    // ── Tier 1 integration ──────────────────────────────────────────────────
+    #[test]
+    fn tier1_resolves_from_embedded_playlists_xml() {
+        let xml = br#"<playlists>
+            <playlist name="Feature" id="00800" aud="eng,fra,spa" duration="7000" />
+            <playlist name="Preview" id="00050" aud="eng" duration="120" />
+        </playlists>"#;
+        let jar = build_jar(&[
+            ("com/studio/Menu.class", build_class(&["unrelated"])),
+            ("00000/playlists.xml", xml.to_vec()),
+        ]);
+        let (mut disc, udf) = build_disc(vec![], vec![("00000.jar", jar)], vec![]);
+        let hint = resolve(&mut disc, &udf).expect("Tier-1 hint");
+        assert_eq!(hint.playlist_id, Some(800));
+    }
+
+    // ── Tier 2 integration ──────────────────────────────────────────────────
+    #[test]
+    fn tier2_resolves_dominant_mpls_locator() {
+        // Autostart jar's class references "00800.mpls"; the disc has a long
+        // 00800 (multi-audio) and a short 00801. No manifest → Tier-2 resolves.
+        let class = build_class(&["bd://JAR:00000/00800.mpls", "some/other/String"]);
+        let jar = build_jar(&[("com/studio/MainXlet.class", class)]);
+        let (mut disc, udf) = build_disc(
+            vec![
+                ("00800.mpls", build_mpls(7000, 6)),
+                ("00801.mpls", build_mpls(120, 2)),
+            ],
+            vec![("00000.jar", jar)],
+            vec![], // no BDJO → scan all jars
+        );
+        let hint = resolve(&mut disc, &udf).expect("Tier-2 hint");
+        assert_eq!(hint.playlist_id, Some(800));
+        assert_eq!(hint.filename.as_deref(), Some("00800.mpls"));
+    }
+
+    #[test]
+    fn tier2_abstains_when_candidate_not_a_real_playlist() {
+        // The class points at 09999.mpls, which is not on the disc → no hit.
+        let class = build_class(&["09999.mpls"]);
+        let jar = build_jar(&[("com/studio/MainXlet.class", class)]);
+        let (mut disc, udf) = build_disc(
+            vec![("00800.mpls", build_mpls(7000, 6))],
+            vec![("00000.jar", jar)],
+            vec![],
+        );
+        assert!(resolve(&mut disc, &udf).is_none());
+    }
+
+    #[test]
+    fn tier2_abstains_on_integer_only_bytecode() {
+        // The autostart class carries only a bare integer constant (800) and no
+        // .mpls / PLAYLIST: locator string — modern-Fox StandardMenuXlet shape.
+        // No candidate is harvested → defer to the chapter failsafe.
+        let mut class = Vec::new();
+        class.extend_from_slice(&0xCAFEBABEu32.to_be_bytes());
+        class.extend_from_slice(&0u16.to_be_bytes());
+        class.extend_from_slice(&52u16.to_be_bytes());
+        class.extend_from_slice(&2u16.to_be_bytes()); // cp_count = 2 (one entry)
+        class.push(3); // CONSTANT_Integer
+        class.extend_from_slice(&800u32.to_be_bytes());
+        class.extend_from_slice(&[0u8; 14]);
+        let jar = build_jar(&[("com/foxbd/StandardMenuXlet.class", class)]);
+        let (mut disc, udf) = build_disc(
+            vec![("00800.mpls", build_mpls(7000, 6))],
+            vec![("00000.jar", jar)],
+            vec![],
+        );
+        assert!(resolve(&mut disc, &udf).is_none());
+    }
+
+    #[test]
+    fn tier2_uses_bdjo_autostart_jar_targeting() {
+        // Two jars; only the autostart one (00000) names the feature. A decoy jar
+        // (00009) points at a different real playlist. The BDJO AMT pins 00000 as
+        // autostart, so only its candidate (00800) is harvested.
+        let auto_class = build_class(&["00800.mpls"]);
+        let decoy_class = build_class(&["00801.mpls"]);
+        let auto_jar = build_jar(&[("com/studio/MainXlet.class", auto_class)]);
+        let decoy_jar = build_jar(&[("com/studio/Decoy.class", decoy_class)]);
+
+        let bdjo = bdjo_with_autostart("00000");
+        let (mut disc, udf) = build_disc(
+            vec![
+                ("00800.mpls", build_mpls(7000, 6)),
+                // 00801 is LONGER, so if the decoy jar were scanned it would win.
+                ("00801.mpls", build_mpls(9000, 6)),
+            ],
+            vec![("00000.jar", auto_jar), ("00009.jar", decoy_jar)],
+            vec![("00000.bdjo", bdjo)],
+        );
+        let hint = resolve(&mut disc, &udf).expect("Tier-2 hint via BDJO targeting");
+        assert_eq!(
+            hint.playlist_id,
+            Some(800),
+            "only the autostart jar's candidate should be considered"
+        );
+    }
+
+    // Build a minimal single-app BDJO whose AUTOSTART app has the given base_dir.
+    fn bdjo_with_autostart(base_dir: &str) -> Vec<u8> {
+        fn app_string(buf: &mut Vec<u8>, s: &str) {
+            buf.push(s.len() as u8);
+            buf.extend_from_slice(s.as_bytes());
+            if s.len().is_multiple_of(2) {
+                buf.push(0);
+            }
+        }
+        let mut b = Vec::new();
+        b.extend_from_slice(b"BDJO");
+        b.extend_from_slice(b"0200");
+        b.extend_from_slice(&[0u8; 40]); // section-address table
+        b.extend_from_slice(&[0u8; 4]); // TerminalInfo length
+        b.extend_from_slice(&[0u8; 5]); // default_font
+        b.extend_from_slice(&[0u8; 5]); // havi/masks + padding (40 bits)
+        b.extend_from_slice(&[0u8; 4]); // AppCacheInfo length
+        b.push(0); // num_item
+        b.push(0); // padding
+        b.extend_from_slice(&[0u8; 4]); // AccessiblePlaylists length
+        b.extend_from_slice(&[0u8; 4]); // num_pl(11)+flags(2)+pad(19) = 0
+        b.extend_from_slice(&[0u8; 4]); // AMT length
+        b.push(1); // num_app
+        b.push(0); // padding
+        // App record
+        b.push(1); // control_code = AUTOSTART
+        b.push(0); // type(4)+reserved(4)
+        b.extend_from_slice(&[0u8; 4]); // org_id
+        b.extend_from_slice(&[0u8; 2]); // app_id
+        b.extend_from_slice(&[0u8; 10]); // descriptor tag+length
+        b.push(0); // num_profile(4)+pad
+        b.push(0);
+        b.push(0); // priority
+        b.push(0); // binding/visibility/reserved
+        b.extend_from_slice(&[0u8; 2]); // app_name data_length = 0
+        app_string(&mut b, ""); // icon_locator
+        b.extend_from_slice(&[0u8; 2]); // icon_flags
+        app_string(&mut b, base_dir); // base_dir
+        app_string(&mut b, ""); // classpath_extension
+        app_string(&mut b, "com.studio.MainXlet"); // initial_class
+        b.push(0); // params data_length = 0
+        b.push(0); // word-align pad
+        b
+    }
+}
@@ -155,12 +155,25 @@ pub(crate) fn labels_from_dcx(text: &str) -> Vec<StreamLabel> {
    labels
 }

-// Pick the richest `<playlist name="feature">` element (ties to first) —
-// Fox presses one per regional variant. Returning ONE avoids merging two
-// STN tables. See docs/fox.md for full rationale.
+// A feature runs at least this long (`durs` is seconds — durs=7628 is a 2h7m
+// feature). A stated sub-minute `name="feature"` is a decoy and is never
+// selected; the guard is inert when no `durs` is present. Shared with paramount.
+use super::MIN_FEATURE_SECS;
+
+// The `durs` (seconds) of a `<playlist>` element, digits only, when stated.
+fn playlist_duration_secs(element: &str) -> Option<u64> {
+    let v = xml::attr(element, "durs")?;
+    let digits: String = v.chars().filter(|c| c.is_ascii_digit()).collect();
+    digits.parse::<u64>().ok().filter(|&d| d > 0)
+}
+
+// Pick the richest `<playlist name="feature">` (most nested streams; a `durs`
+// tiebreak breaks a count tie by longest time; first feature wins a full tie; a
+// stated sub-minute feature is skipped). See docs/fox.md for full rationale.
 fn select_feature_playlist(text: &str) -> Option<&str> {
-    let mut best: Option<&str> = None;
-    let mut best_streams = 0usize;
+    // rank = (nested stream count, durs seconds). None durs sorts as 0 so it
+    // never displaces a stream-count-equal sibling that states a longer time.
+    let mut best: Option<(&str, (usize, u64))> = None;
    let mut from = 0;
    while let Some((s, e)) = xml::find_element(text, "playlist", from) {
        let element = &text[s..e];
@@ -173,16 +186,21 @@ fn select_feature_playlist(text: &str) -> Option<&str> {
        if !is_feature {
            continue;
        }
+        let dur = playlist_duration_secs(element);
+        // A stated sub-minute feature is a decoy — never the real feature.
+        if dur.is_some_and(|d| d < MIN_FEATURE_SECS) {
+            continue;
+        }
        let streams = count_elements(element, "audio") + count_elements(element, "subtitle");
-        // First feature wins the tie (matches the registry's first-wins rule);
-        // a strictly richer table displaces it. `best.is_none()` so a feature
-        // with zero nested streams is still selected — its id feeds the hint.
-        if best.is_none() || streams > best_streams {
-            best_streams = streams;
-            best = Some(element);
+        let rank = (streams, dur.unwrap_or(0));
+        // Strictly-better rank displaces; a full tie keeps the first feature.
+        // `best.is_none()` so a feature with zero nested streams is still
+        // selected — its id feeds the hint.
+        if best.is_none_or(|(_, br)| rank > br) {
+            best = Some((element, rank));
        }
    }
-    best
+    best.map(|(el, _)| el)
 }

 /// The authoring id (digits only, e.g. "00800") of the selected feature
@@ -485,6 +503,41 @@ mod tests {
        assert_eq!(feature_playlist_id(menus_only), None);
    }

+    /// On an equal nested-stream count, the longer `durs` (seconds) wins the
+    /// tiebreak rather than document order.
+    #[test]
+    fn feature_duration_breaks_a_stream_count_tie() {
+        let doc = r#"<dcx><disc>
+            <playlist id="00800" lang="eng" name="feature" durs="6000">
+                <audio id="01" lang="eng" type="feature"/>
+                <subtitle id="01" lang="eng" type="feature"/>
+            </playlist>
+            <playlist id="00900" lang="eng" name="feature" durs="8000">
+                <audio id="01" lang="eng" type="feature"/>
+                <subtitle id="01" lang="eng" type="feature"/>
+            </playlist>
+        </disc></dcx>"#;
+        assert_eq!(feature_playlist_id(doc), Some("00900".to_string()));
+    }
+
+    /// A stated sub-minute `name="feature"` is a decoy and is skipped in favour
+    /// of the real (longer) feature.
+    #[test]
+    fn sub_minute_feature_is_skipped() {
+        let doc = r#"<dcx><disc>
+            <playlist id="00050" lang="eng" name="feature" durs="4">
+                <audio id="01" lang="eng" type="feature"/>
+                <audio id="02" lang="fra" type="feature"/>
+                <subtitle id="01" lang="eng" type="feature"/>
+            </playlist>
+            <playlist id="00800" lang="eng" name="feature" durs="7628">
+                <audio id="01" lang="eng" type="feature"/>
+            </playlist>
+        </disc></dcx>"#;
+        // 00050 has more nested streams but is sub-minute → rejected; 00800 wins.
+        assert_eq!(feature_playlist_id(doc), Some("00800".to_string()));
+    }
+
    /// A feature playlist with no nested streams (an authoring edge) produces
    /// no labels rather than a spurious empty-slot entry.
    #[test]
@@ -18,6 +18,11 @@ use zip::ZipArchive;
 // pre-sizing. See docs/jar.md — MAX_CLASS_BYTES rationale.
 const MAX_CLASS_BYTES: u64 = 64 * 1024 * 1024;

+// Cap on bytes read from one non-`.class` resource entry (the dcx.xml /
+// playlists.xml / *.properties manifests the Tier-1 sweep reads). Same
+// attacker-controlled-size defence as MAX_CLASS_BYTES — see docs/jar.md.
+const MAX_RESOURCE_BYTES: u64 = 16 * 1024 * 1024;
+
 /// In-memory zip archive: backed by a `Vec<u8>` read from UDF. Owns
 /// the buffer; callers pass it to [`has_path_prefix`], [`for_each_class`],
 /// etc.
@@ -119,6 +124,44 @@ where
    None
 }

+/// Iterate every NON-`.class` entry in the jar, read its bytes (bounded by
+/// [`MAX_RESOURCE_BYTES`]), and call `f` with `(entry_name, &bytes)`. Returns
+/// the first `Some(R)` the callback produces, or `None` when every resource was
+/// visited without a hit.
+///
+/// This is the Tier-1 menu-walk sweep: newer discs embed the same
+/// `dcx.xml`/`playlists.xml` manifests INSIDE a jar rather than as loose
+/// `/BDMV/JAR/<id>/` files. Directory entries and `.class` files are skipped;
+/// unreadable entries are silently ignored (robustness over completeness).
+pub fn try_each_resource<R, F>(archive: &mut Jar, mut f: F) -> Option<R>
+where
+    F: FnMut(&str, &[u8]) -> Option<R>,
+{
+    for i in 0..archive.len() {
+        let Ok(entry) = archive.by_index(i) else {
+            continue;
+        };
+        let name = entry.name().to_string();
+        if name.ends_with('/') || name.to_ascii_lowercase().ends_with(".class") {
+            continue;
+        }
+        // Declared uncompressed size is attacker-controlled — grow the buffer
+        // incrementally and cap the read rather than pre-sizing from it.
+        let mut bytes = Vec::new();
+        if entry
+            .take(MAX_RESOURCE_BYTES)
+            .read_to_end(&mut bytes)
+            .is_err()
+        {
+            continue;
+        }
+        if let Some(r) = f(&name, &bytes) {
+            return Some(r);
+        }
+    }
+    None
+}
+
 #[cfg(test)]
 mod tests {
    use super::*;
@@ -292,4 +335,36 @@ mod tests {
        for_each_class(&mut jar, |_, _| visited += 1);
        assert_eq!(visited, 1);
    }
+
+    #[test]
+    fn try_each_resource_reads_non_class_entries_and_skips_classes() {
+        let xml = b"<dcx><disc/></dcx>";
+        // A .class entry must be skipped; the .xml resource must be surfaced.
+        let mut jar = {
+            use std::io::{Cursor, Write as _};
+            let mut buf = Vec::new();
+            {
+                let mut w = zip::ZipWriter::new(Cursor::new(&mut buf));
+                let opts = zip::write::SimpleFileOptions::default()
+                    .compression_method(zip::CompressionMethod::Stored);
+                w.start_file("com/x/Menu.class", opts).unwrap();
+                w.write_all(MINIMAL_CLASS).unwrap();
+                w.start_file("00000/dcx.xml", opts).unwrap();
+                w.write_all(xml).unwrap();
+                w.finish().unwrap();
+            }
+            ZipArchive::new(Cursor::new(buf)).expect("valid zip")
+        };
+
+        let mut seen: Vec<String> = Vec::new();
+        let found: Option<Vec<u8>> = try_each_resource(&mut jar, |name, bytes| {
+            seen.push(name.to_string());
+            name.ends_with("dcx.xml").then(|| bytes.to_vec())
+        });
+        assert_eq!(found.as_deref(), Some(&xml[..]));
+        assert!(
+            !seen.iter().any(|n| n.ends_with(".class")),
+            "a .class entry must never be offered as a resource"
+        );
+    }
 }
@@ -8,6 +8,7 @@
 //!      (set [`ParseResult::confidence`] to drive tie-breaking)
 //!   4. Add `mod myformat;` below and one line to `PARSERS` array

+mod bdj_feature;
 mod bdmt;
 pub(crate) mod class_reader;
 pub mod clpi_audit;
@@ -252,13 +253,35 @@ pub fn apply(
    udf: &UdfFs,
    titles: &mut [DiscTitle],
 ) -> Option<FeaturePlaylistHint> {
-    let (labels, feature_playlist) =
+    let (labels, winner_hint) =
        std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| extract(reader, udf)))
            .unwrap_or_default();
    if !labels.is_empty() {
        apply_labels(&labels, titles);
    }
-    feature_playlist.filter(|h| !h.is_empty())
+    // The feature hint rides its own pass, independent of whether any parser
+    // produced labels (like bdmt): a jar-only disc still yields a hint. Wrapped
+    // separately so a menu-walk fault can't lose an already-extracted hint.
+    let hint = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+        resolve_feature_hint(reader, udf, winner_hint)
+    }))
+    .ok()
+    .flatten();
+    hint.filter(|h| !h.is_empty())
+}
+
+// The disc's feature-playlist hint: the winning parser's manifest hint when it
+// carries one, else the generic BD-J menu-walk (`bdj_feature::resolve`). Kept
+// separate from extraction so a hint survives an empty/absent label set.
+fn resolve_feature_hint(
+    reader: &mut dyn SectorSource,
+    udf: &UdfFs,
+    winner_hint: Option<FeaturePlaylistHint>,
+) -> Option<FeaturePlaylistHint> {
+    if let Some(hint) = winner_hint.filter(|h| !h.is_empty()) {
+        return Some(hint);
+    }
+    bdj_feature::resolve(reader, udf)
 }

 // Min streams of one type before a language sequence anchors the label
@@ -270,6 +293,11 @@ const MIN_ANCHOR_STREAMS: usize = 2;
 // so 0 is unused; only stream_id-bearing labels may carry it.
 const NO_STN_SLOT: u16 = 0;

+// A stated feature playlist runs at least this long (seconds); a sub-minute
+// stated duration is a decoy (Fox name=feature, Paramount _Start_Angle), never
+// the feature. Inert when no duration is stated. Shared by fox and paramount.
+pub(crate) const MIN_FEATURE_SECS: u64 = 60;
+
 // Two ISO 639-2 codes that do NOT contradict: equal (case/padding
 // insensitive), or either side is empty ("unknown", never a contradiction).
 fn languages_compatible(a: &str, b: &str) -> bool {
@@ -3376,3 +3404,130 @@ mod clpi_orphan_tests {
        assert_eq!(labels.len(), 1);
    }
 }
+
+// ── apply(): independent feature-hint pass (issue #45 menu-walk) ─────────────
+
+#[cfg(test)]
+mod feature_hint_pass_tests {
+    use super::*;
+    use crate::udf::fixture::*;
+    use std::io::{Cursor, Write as _};
+
+    // Zip entries into an in-memory jar (Stored, no compression).
+    fn build_jar(entries: &[(&str, Vec<u8>)]) -> Vec<u8> {
+        let mut buf = Vec::new();
+        {
+            let mut w = zip::ZipWriter::new(Cursor::new(&mut buf));
+            let opts = zip::write::SimpleFileOptions::default()
+                .compression_method(zip::CompressionMethod::Stored);
+            for (name, data) in entries {
+                w.start_file(*name, opts).unwrap();
+                w.write_all(data).unwrap();
+            }
+            w.finish().unwrap();
+        }
+        buf
+    }
+
+    /// A jar-only disc — no loose manifest, no vendor labels, no parser matches —
+    /// still yields a feature hint, because the menu-walk hint pass runs
+    /// independently of `labels.is_empty()`. This is the whole point of routing
+    /// the hint through `resolve_feature_hint` rather than dropping it with the
+    /// (empty) label set. The embedded `playlists.xml` names the feature 00800.
+    #[test]
+    fn apply_returns_hint_for_a_jar_only_disc_with_no_labels() {
+        let xml = br#"<playlists>
+            <playlist name="Feature" id="00800" aud="eng,fra,spa" duration="7000" />
+            <playlist name="Preview" id="00050" aud="eng" duration="90" />
+        </playlists>"#;
+        let jar = build_jar(&[
+            ("com/studio/Menu.class", Vec::new()), // an entry, not a parseable class
+            ("00000/playlists.xml", xml.to_vec()),
+        ]);
+        let jar_dir = DirSpec {
+            name: "JAR".to_string(),
+            icb_lba: 30,
+            dir_data_lba: 31,
+            files: vec![file_with("00000.jar", 32, 4000, jar, true)],
+            subdirs: vec![],
+        };
+        let bdmv = DirSpec {
+            name: "BDMV".to_string(),
+            icb_lba: 20,
+            dir_data_lba: 21,
+            files: Vec::new(),
+            subdirs: vec![jar_dir],
+        };
+        let root = DirSpec {
+            name: String::new(),
+            icb_lba: 10,
+            dir_data_lba: 11,
+            files: Vec::new(),
+            subdirs: vec![bdmv],
+        };
+        let mut disc = MemDisc::new();
+        build_udf_skeleton(&mut disc, 10);
+        lay_dir(&mut disc, &root);
+        let udf = crate::udf::read_filesystem(&mut disc).expect("fs");
+
+        // No titles to label; the hint pass must still fire.
+        let mut titles: Vec<DiscTitle> = Vec::new();
+        let hint =
+            apply(&mut disc, &udf, &mut titles).expect("a jar-only disc still yields a hint");
+        assert_eq!(hint.playlist_id, Some(800));
+        assert_eq!(hint.filename.as_deref(), Some("00800.mpls"));
+    }
+
+    /// The winner_hint early-return: when the winning parser already carried a
+    /// non-empty hint, resolve_feature_hint returns it verbatim and never runs
+    /// the Tier-2 menu-walk. The disc's bdj_feature::resolve would yield 00800,
+    /// but the supplied winner_hint (00042) must win — proving the short-circuit.
+    #[test]
+    fn resolve_feature_hint_returns_winner_hint_over_menu_walk() {
+        let xml = br#"<playlists>
+            <playlist name="Feature" id="00800" aud="eng,fra,spa" duration="7000" />
+        </playlists>"#;
+        let jar = build_jar(&[("00000/playlists.xml", xml.to_vec())]);
+        let jar_dir = DirSpec {
+            name: "JAR".to_string(),
+            icb_lba: 30,
+            dir_data_lba: 31,
+            files: vec![file_with("00000.jar", 32, 4000, jar, true)],
+            subdirs: vec![],
+        };
+        let bdmv = DirSpec {
+            name: "BDMV".to_string(),
+            icb_lba: 20,
+            dir_data_lba: 21,
+            files: Vec::new(),
+            subdirs: vec![jar_dir],
+        };
+        let root = DirSpec {
+            name: String::new(),
+            icb_lba: 10,
+            dir_data_lba: 11,
+            files: Vec::new(),
+            subdirs: vec![bdmv],
+        };
+        let mut disc = MemDisc::new();
+        build_udf_skeleton(&mut disc, 10);
+        lay_dir(&mut disc, &root);
+        let udf = crate::udf::read_filesystem(&mut disc).expect("fs");
+
+        // Sanity: the Tier-2 menu-walk on this disc resolves to 00800.
+        let tier2 = bdj_feature::resolve(&mut disc, &udf);
+        assert_eq!(tier2.and_then(|h| h.playlist_id), Some(800));
+
+        // A DIFFERENT non-empty winner_hint must short-circuit before Tier-2.
+        let winner = FeaturePlaylistHint {
+            playlist_id: Some(42),
+            filename: Some("00042.mpls".to_string()),
+        };
+        let got = resolve_feature_hint(&mut disc, &udf, Some(winner.clone()));
+        assert_eq!(
+            got,
+            Some(winner),
+            "a non-empty winner_hint wins over the Tier-2 menu-walk result"
+        );
+    }
+}
@@ -212,37 +212,137 @@ fn labels_from_feature(feature: &str) -> Vec<StreamLabel> {
    labels
 }

-/// Find the feature playlist element (the one with the most non-empty
-/// audio slots).
+/// The feature playlist hint for a whole `playlists.xml` document — selects the
+/// feature element and derives its id/filename. Exposed for the generic BD-J
+/// menu-walk (`bdj_feature`) Tier-1 sweep, which finds this manifest embedded
+/// inside a jar rather than as a loose file.
+pub(crate) fn feature_hint_from_xml(text: &str) -> Option<super::FeaturePlaylistHint> {
+    let feature = find_feature_playlist(text)?;
+    feature_hint(&feature)
+}
+
+// A playlist must run at least this long (seconds) to be the feature — kills the
+// `_Start_Angle` 2-second decoy (Sony SM3 UHD id 00243). Applied only when a
+// duration is actually stated; absent, it stays inert. Shared with fox.
+use super::MIN_FEATURE_SECS;
+
+// A `<playlist>` element's stated running time in seconds, if any. Read from the
+// first present of a set of duration-like attributes (the corpus is not a spec;
+// `durs` matches the sibling Fox manifest's seconds convention). Digits only.
+fn playlist_duration_secs(element: &str) -> Option<u64> {
+    for key in ["duration", "durs", "dur", "runtime", "length", "len"] {
+        if let Some(v) = xml::attr(element, key) {
+            let digits: String = v.chars().filter(|c| c.is_ascii_digit()).collect();
+            if let Ok(secs) = digits.parse::<u64>()
+                && secs > 0
+            {
+                return Some(secs);
+            }
+        }
+    }
+    None
+}
+
+// A feature-selection candidate: the element text, its non-empty audio-slot
+// count, and its stated duration (seconds) when known.
+struct Candidate {
+    element: String,
+    aud: usize,
+    dur: Option<u64>,
+}
+
+impl Candidate {
+    // A candidate whose duration is stated AND sub-minute can never be the
+    // feature — the _Start_Angle decoy guard.
+    fn is_sub_minute(&self) -> bool {
+        self.dur.is_some_and(|d| d < MIN_FEATURE_SECS)
+    }
+}
+
+/// Find the feature playlist element. Order, refined for Sony SM3 UHD:
+///   1. exact `name="Feature"` (case-insensitive) — longest-duration among any,
+///      else first;
+///   2. else any name matching `/feature/i` (`_Feature`, `Feature_A`, …) —
+///      longest-duration among them, else the most-audio one;
+///   3. else the most-audio playlist overall, breaking ties by longest duration.
+///
+/// A playlist whose stated duration is sub-minute is never returned (the
+/// `_Start_Angle` decoy).
 fn find_feature_playlist(text: &str) -> Option<String> {
-    let mut best: Option<String> = None;
-    let mut best_aud_count = 0;
+    let mut exact: Vec<Candidate> = Vec::new();
+    let mut feature_like: Vec<Candidate> = Vec::new();
+    let mut all: Vec<Candidate> = Vec::new();
    let mut from = 0;

    while let Some((start, end)) = xml::find_element(text, "playlist", from) {
        let element = &text[start..end];
-
-        // Prefer name="Feature" explicitly.
-        if let Some(name) = xml::attr(element, "name")
-            && name.eq_ignore_ascii_case("Feature")
-        {
-            return Some(element.to_string());
-        }
-
-        // Otherwise pick the one with the most audio streams. Count only
-        // non-empty slots so a malformed `aud=",,,,,"` can't outscore a
-        // legitimate feature.
-        if let Some(aud) = xml::attr(element, "aud") {
-            let count = aud.split(',').filter(|s| !s.trim().is_empty()).count();
-            if count > best_aud_count {
-                best_aud_count = count;
-                best = Some(element.to_string());
-            }
-        }
-
        from = end;
+
+        // Count only non-empty audio slots so a malformed `aud=",,,,,"` can't
+        // outscore a legitimate feature.
+        let aud = xml::attr(element, "aud")
+            .map(|a| a.split(',').filter(|s| !s.trim().is_empty()).count())
+            .unwrap_or(0);
+        let dur = playlist_duration_secs(element);
+        let make = || Candidate {
+            element: element.to_string(),
+            aud,
+            dur,
+        };
+
+        match xml::attr(element, "name") {
+            Some(name) if name.eq_ignore_ascii_case("Feature") => exact.push(make()),
+            Some(name) if name.to_ascii_lowercase().contains("feature") => {
+                feature_like.push(make())
+            }
+            _ => {}
+        }
+        all.push(make());
    }
-    best
+
+    // Tier 1: exact name="Feature" — longest duration, else first. A
+    // zero-audio exact feature is still valid (its id feeds the hint).
+    if let Some(el) = pick(&exact, Key::Duration, false) {
+        return Some(el);
+    }
+    // Tier 2: /feature/i names (Sony `_Feature`, `Feature_A`, `Feature_B`) —
+    // longest duration among them, else most audio.
+    if let Some(el) = pick(&feature_like, Key::Duration, true) {
+        return Some(el);
+    }
+    // Tier 3: most audio across all playlists, longest duration as the tiebreak.
+    pick(&all, Key::Audio, true)
+}
+
+// Which signal dominates candidate ranking: duration (tiers 1-2) or audio-slot
+// count (tier 3). The other is the tiebreak.
+#[derive(Clone, Copy)]
+enum Key {
+    Duration,
+    Audio,
+}
+
+// Choose the best candidate under `key`: skip sub-minute decoys; first-wins on a
+// full tie (strict `>`). When `require_audio`, a candidate needs at least one
+// audio slot to be eligible. `None` duration sorts below any stated duration.
+fn pick(cands: &[Candidate], key: Key, require_audio: bool) -> Option<String> {
+    let rank = |c: &Candidate| match key {
+        Key::Duration => (c.dur, c.aud as u64),
+        Key::Audio => (Some(c.aud as u64), c.dur.unwrap_or(0)),
+    };
+    let mut best: Option<&Candidate> = None;
+    for c in cands {
+        if c.is_sub_minute() {
+            continue;
+        }
+        if require_audio && c.aud == 0 {
+            continue;
+        }
+        if best.is_none_or(|b| rank(c) > rank(b)) {
+            best = Some(c);
+        }
+    }
+    best.map(|c| c.element.clone())
 }

 #[cfg(test)]
@@ -750,4 +850,69 @@ mod tests {
            "first playlist must win a tie, got: {feature}"
        );
    }
+
+    // Sony SM3 UHD regression: `_Start_Angle` (id 00243, 2s) shares the
+    // feature's audio slots and comes first — `/feature/i` matching plus the
+    // sub-minute guard now reject the decoy the old rule picked.
+    #[test]
+    fn feature_selection_rejects_start_angle_decoy() {
+        let xml = r#"
+            <playlist name="_Start_Angle" id="00243" aud="eng,fra,spa" duration="2" />
+            <playlist name="_Feature"     id="00800" aud="eng,fra,spa" duration="7000" />
+            <playlist name="Feature_A"    id="00801" aud="eng,fra,spa" duration="7000" />
+        "#;
+        let feature = find_feature_playlist(xml).expect("a feature is found");
+        assert!(
+            !feature.contains("_Start_Angle"),
+            "the 2-second angle decoy must never be the feature: {feature}"
+        );
+        // Tie between the two /feature/i playlists → first wins (_Feature, 00800).
+        let h = feature_hint_from_xml(xml).expect("hint");
+        assert_eq!(h.playlist_id, Some(800));
+        assert_eq!(h.filename.as_deref(), Some("00800.mpls"));
+    }
+
+    // Among /feature/i playlists, the longest duration wins — not document order.
+    #[test]
+    fn feature_like_longest_duration_wins() {
+        let xml = r#"
+            <playlist name="_Feature"  id="00800" aud="eng,fra" duration="6000" />
+            <playlist name="Feature_B" id="00802" aud="eng,fra" duration="8000" />
+        "#;
+        let h = feature_hint_from_xml(xml).expect("hint");
+        assert_eq!(
+            h.playlist_id,
+            Some(802),
+            "the longer /feature/i playlist wins"
+        );
+    }
+
+    // The sub-minute guard also applies when the ONLY /feature/i playlist is a
+    // decoy: it is rejected and selection falls through to the real feature.
+    #[test]
+    fn sub_minute_feature_name_is_rejected() {
+        let xml = r#"
+            <playlist name="Feature_Trailer" id="00050" aud="eng,fra,spa" duration="30" />
+            <playlist name="MainMovie"       id="00800" aud="eng,fra,spa" duration="7000" />
+        "#;
+        let feature = find_feature_playlist(xml).expect("a feature is found");
+        // Feature_Trailer is /feature/i but sub-minute → rejected; tier 3 picks
+        // MainMovie (equal audio, far longer duration).
+        assert!(feature.contains(r#"id="00800""#), "got {feature}");
+    }
+
+    // Duration attribute reading: several key spellings, digits only, zero → None.
+    #[test]
+    fn playlist_duration_reads_known_attrs() {
+        assert_eq!(
+            playlist_duration_secs(r#"<playlist duration="7000" />"#),
+            Some(7000)
+        );
+        assert_eq!(
+            playlist_duration_secs(r#"<playlist durs="7628" />"#),
+            Some(7628)
+        );
+        assert_eq!(playlist_duration_secs(r#"<playlist dur="0" />"#), None);
+        assert_eq!(playlist_duration_secs(r#"<playlist name="x" />"#), None);
+    }
 }
@@ -5,6 +5,21 @@
 //! stream info (video, audio, subtitle tracks).
 //!
 //! Format is documented in the BD-ROM PlayList (MPLS) specification.
+//!
+//! ## Multi-angle PlayItem STN offset (issue #45)
+//! The STN (stream-number) table sits at PlayItem offset 32 for a single-angle
+//! item, but a MULTI-ANGLE item (is_multi_angle = bit 4 of `item[10]`) inserts an
+//! angle block right after still_time at offset 32:
+//!   number_of_angles(1) + flags(1) + (number_of_angles − 1) angle references,
+//!   each clip_name(5) + clip_codec_id(4) + ref_to_STC_id(1) = 10 bytes
+//! (the first angle is the primary clip already at `item[0..5]`). So the real STN
+//! begins at `32 + 2 + (number_of_angles − 1) * 10`. A fixed offset of 32 lands
+//! INSIDE that block and misreads the stream counts as garbage (e.g. n_video =
+//! 51 on Spider-Man 3 UHD 00245/00246.mpls, number_of_angles = 2 ⇒ real offset
+//! 44), dropping every stream — the primary video included. That makes
+//! `DiscTitle::has_video()` return false, which drops a multi-angle/seamless-
+//! branch FEATURE from the disc's nav candidate set (see `Disc::scan_with`) and
+//! loses it in main-title selection. `parse` computes the offset accordingly.

 use crate::error::{Error, Result};

@@ -150,25 +165,31 @@ pub fn parse(data: &[u8]) -> Result<Playlist> {
        let in_time = u32::from_be_bytes([item[12], item[13], item[14], item[15]]);
        let out_time = u32::from_be_bytes([item[16], item[17], item[18], item[19]]);

-        // Parse STN table from the first play item. PlayItem layout after out_time:
-        // UO_mask_table(8) + misc flags(1) + still_mode(1) + still_time(2), then
-        // STN_table starting at STN_OFFSET.
-        const STN_OFFSET: usize = 32;
-        // `>=`, not `>`: the 16-byte STN header spans item[STN_OFFSET..STN_OFFSET+16], so
-        // item.len() == STN_OFFSET + 16 already holds every header byte. Strict `>` demanded
+        // STN table offset: base 32, shifted past the multi-angle angle block when
+        // present (issue #45 — see the module `//!` header for the layout and why a
+        // fixed 32 misparses). is_multi_angle is bit 4 of item[10].
+        let is_multi_angle = (item[10] & 0x10) != 0;
+        let stn_offset = if is_multi_angle && item.len() > 32 {
+            let number_of_angles = item[32] as usize;
+            32 + 2 + number_of_angles.saturating_sub(1) * 10
+        } else {
+            32
+        };
+        // `>=`, not `>`: the 16-byte STN header spans item[stn_offset..stn_offset+16], so
+        // item.len() == stn_offset + 16 already holds every header byte. Strict `>` demanded
        // one extra byte, skipping a play item whose STN header ends exactly at the boundary (stream-less STN table).
-        if item_idx == 0 && item.len() >= STN_OFFSET + 16 {
+        if item_idx == 0 && item.len() >= stn_offset + 16 {
            // STN header: length(2) + reserved(2) + counts(8) + reserved(4) = 16 bytes
-            let n_video = item[STN_OFFSET + 4] as usize;
-            let n_audio = item[STN_OFFSET + 5] as usize;
-            let n_pg = item[STN_OFFSET + 6] as usize;
-            let n_ig = item[STN_OFFSET + 7] as usize;
-            let n_sec_audio = item[STN_OFFSET + 8] as usize;
-            let n_sec_video = item[STN_OFFSET + 9] as usize;
-            let n_pip_pg = item[STN_OFFSET + 10] as usize;
-            let n_dv = item[STN_OFFSET + 11] as usize;
+            let n_video = item[stn_offset + 4] as usize;
+            let n_audio = item[stn_offset + 5] as usize;
+            let n_pg = item[stn_offset + 6] as usize;
+            let n_ig = item[stn_offset + 7] as usize;
+            let n_sec_audio = item[stn_offset + 8] as usize;
+            let n_sec_video = item[stn_offset + 9] as usize;
+            let n_pip_pg = item[stn_offset + 10] as usize;
+            let n_dv = item[stn_offset + 11] as usize;

-            let mut spos = STN_OFFSET + 16;
+            let mut spos = stn_offset + 16;

            // Primary video
            for _ in 0..n_video {
@@ -753,6 +774,70 @@ mod tests {
        );
    }

+    // Regression for issue #45 (see module `//!` header): a multi-angle first
+    // PlayItem puts its STN past the angle block (2 angles ⇒ offset 44); a fixed
+    // offset of 32 misreads it and drops the video. Assert the video is found.
+    #[test]
+    fn multi_angle_first_play_item_stn_is_located_after_the_angle_block() {
+        let in_time = 0u32;
+        let out_time = 9_000_000u32;
+        let number_of_angles = 2u8;
+
+        let mut item = Vec::new();
+        item.extend_from_slice(b"00001"); // [0..5] clip_id (angle 1 = primary)
+        item.extend_from_slice(b"M2TS"); // [5..9] codec_id
+        item.push(0); // [9] reserved
+        item.push(0x10); // [10] is_multi_angle (bit 4), connection_condition = 0
+        item.push(0); // [11] stc_id
+        item.extend_from_slice(&in_time.to_be_bytes()); // [12..16]
+        item.extend_from_slice(&out_time.to_be_bytes()); // [16..20]
+        item.extend_from_slice(&[0u8; 8]); // [20..28] UO mask
+        item.push(0); // [28] misc flags
+        item.push(0); // [29] still_mode
+        item.extend_from_slice(&[0u8; 2]); // [30..32] still_time
+        // Angle block: number_of_angles(1) + flags(1) + (angles-1) refs * 10 bytes.
+        item.push(number_of_angles); // [32]
+        item.push(0); // [33] is_different_audios / is_seamless_angle_change
+        item.extend_from_slice(b"00002"); // angle 2 clip_name(5)
+        item.extend_from_slice(b"M2TS"); // angle 2 codec_id(4)
+        item.push(0); // angle 2 ref_to_STC_id(1)  -> STN now begins at offset 44
+        // STN table: length(2) + reserved(2) + counts(8) + reserved(4) + entries.
+        let stn_start = item.len();
+        item.extend_from_slice(&[0u8; 2]); // STN length placeholder
+        item.extend_from_slice(&[0u8; 2]); // reserved
+        item.extend_from_slice(&[1, 0, 0, 0, 0, 0, 0, 0]); // n_video=1, rest 0
+        item.extend_from_slice(&[0u8; 4]); // reserved
+        item.extend_from_slice(&build_stream_entry_video(0x1011, 0x24, 8, 1, Some(0x12)));
+        let stn_len = (item.len() - stn_start - 2) as u16;
+        item[stn_start..stn_start + 2].copy_from_slice(&stn_len.to_be_bytes());
+
+        // Wrap in the file + PlayList headers.
+        let mut buf = Vec::new();
+        buf.extend_from_slice(b"MPLS0200");
+        buf.extend_from_slice(&40u32.to_be_bytes()); // playlist_start
+        buf.extend_from_slice(&[0u8; 28]); // mark_start(0) + padding to 40
+        let pl_start = buf.len();
+        buf.extend_from_slice(&[0u8; 4]); // PlayList length placeholder
+        buf.extend_from_slice(&[0u8; 2]); // reserved
+        buf.extend_from_slice(&1u16.to_be_bytes()); // num_play_items
+        buf.extend_from_slice(&[0u8; 2]); // num_sub_paths
+        buf.extend_from_slice(&(item.len() as u16).to_be_bytes());
+        buf.extend_from_slice(&item);
+        let pl_len = (buf.len() - pl_start - 4) as u32;
+        buf[pl_start..pl_start + 4].copy_from_slice(&pl_len.to_be_bytes());
+
+        let playlist = parse(&buf).expect("multi-angle MPLS must parse");
+        assert_eq!(playlist.play_items.len(), 1);
+        assert_eq!(
+            playlist.streams.len(),
+            1,
+            "the primary video must be found past the angle block, not misread as garbage"
+        );
+        assert_eq!(playlist.streams[0].stream_type, 1, "it is a video stream");
+        assert_eq!(playlist.streams[0].pid, 0x1011);
+        assert_eq!(playlist.streams[0].coding_type, 0x24); // HEVC
+    }
+
    #[test]
    fn parse_invalid_magic() {
        let mut data = build_mpls(&[(b"00001", 1, 0, 9000000)], (0, 0, 0, 0, 0, 0, 0, 0), &[]);
@@ -186,6 +186,14 @@ thread_local! {
    static PARAM_REASSERT_REALLOCS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
 }

+// Test-only: forces a framing desync just before the parse() self-check guard
+// so its drop branch is exercised end-to-end (frame_data is length-prefixed by
+// construction, so no real input desyncs it). See parse_drops_desynced_access_unit.
+#[cfg(test)]
+thread_local! {
+    static FORCE_FRAMING_DESYNC: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
+}
+
 // 33-bit 90kHz PTS wraps at 2^33 ticks (~26.5h). A backward step of ~2^33 is a
 // wraparound (unwrap, add 2^33) not a clip reset (arbitrary sub-2^33 backward
 // step); accepting steps within `PTS_WRAP_PERIOD`/2 of a full period separates the two cases.
@@ -362,6 +370,11 @@ fn reassert_active(prefix: &mut Vec<u8>, cur: &Option<Vec<u8>>, emitted: bool) {
    push_length_prefixed(prefix, active);
 }

+// Width of the NAL length prefix this parser writes (4-byte BE, `u32::to_be_bytes`).
+// MUST equal hvcC `lengthSizeMinusOne + 1` (byte 21, low bits = 3 => 4); a mismatch
+// is the framing desync a demuxer reports as "Invalid NAL unit size".
+const LENGTH_PREFIX_SIZE: usize = 4;
+
 // Appends `nal` as a 4-byte BE length prefix + body. Skipped (not
 // mis-framed) if `nal.len()` overflows u32 — unreachable in practice.
 fn push_length_prefixed(out: &mut Vec<u8>, nal: &[u8]) {
@@ -372,6 +385,37 @@ fn push_length_prefixed(out: &mut Vec<u8>, nal: &[u8]) {
    out.extend_from_slice(nal);
 }

+/// Walk a length-prefixed NAL buffer (`[u32-BE len][body]` records) and confirm the
+/// records EXACTLY tile it: every declared length fits, none is zero, and the last
+/// body ends precisely at the buffer end with no trailing bytes. Our `frame_data`
+/// is length-prefixed by construction, so this is a self-consistency guard — a
+/// `false` means a framing desync that a downstream demuxer would report as
+/// "Invalid NAL unit size (N>M)", and such an access unit must be dropped rather
+/// than emitted. See docs/hevc.md — length-prefix self-check (issue #52).
+fn length_prefix_tiles(data: &[u8]) -> bool {
+    let mut pos = 0usize;
+    while pos < data.len() {
+        // The full length field must be present.
+        if pos + LENGTH_PREFIX_SIZE > data.len() {
+            return false;
+        }
+        let len =
+            u32::from_be_bytes([data[pos], data[pos + 1], data[pos + 2], data[pos + 3]]) as usize;
+        // A zero-length record is a structurally invalid (empty) NALU.
+        if len == 0 {
+            return false;
+        }
+        pos += LENGTH_PREFIX_SIZE;
+        // The declared body must fit within the remaining buffer.
+        match pos.checked_add(len) {
+            Some(end) if end <= data.len() => pos = end,
+            _ => return false,
+        }
+    }
+    // Exact tiling: the walk must land precisely on the buffer end.
+    pos == data.len()
+}
+
 impl CodecParser for HevcParser {
    fn parse(&mut self, pes: &PesPacket) -> Vec<Frame> {
        if pes.data.is_empty() {
@@ -563,6 +607,28 @@ impl CodecParser for HevcParser {
            }
        }

+        // Test-only seam: append a stray byte so the guard below sees a desync,
+        // exercising its drop branch end-to-end (no real input can desync here).
+        #[cfg(test)]
+        if FORCE_FRAMING_DESYNC.with(|c| c.get()) {
+            frame_data.push(0xFF);
+        }
+
+        // Defense in depth (issue #52): frame_data is length-prefixed by
+        // construction, but a desynced buffer would surface as "Invalid NAL unit
+        // size". Drop it (log src) rather than emit a mis-framed access unit.
+        if !length_prefix_tiles(&frame_data) {
+            tracing::warn!(
+                target: "freemkv::mux::hevc",
+                src = ?pes.source,
+                frame_len = frame_data.len(),
+                keyframe,
+                "HEVC length-prefix self-check failed; dropping desynced access unit \
+                 (would surface downstream as \"Invalid NAL unit size\")"
+            );
+            return Vec::new();
+        }
+
        // HDR10 static metadata is stamped onto every frame's PictureInfo once
        // both SEI messages are seen, riding the deferred-muxer path (reads it
        // from the first coded picture before the track header). `None` for SDR tracks.
@@ -2689,6 +2755,134 @@ mod tests {
        );
    }

+    // ── issue #52 (Fix A): length-prefix self-consistency ───────────────────
+
+    #[test]
+    fn hvcc_length_size_matches_push_length_prefixed_width() {
+        // Regression: hvcC byte-21 lengthSizeMinusOne+1 (low 2 bits) MUST equal the
+        // prefix width push_length_prefixed writes (LENGTH_PREFIX_SIZE); a divergence
+        // is the framing desync reported as "Invalid NAL unit size".
+        let sps = make_sps_with_chroma(1, 2, 2);
+        let cp = codec_private_from_sps(&sps);
+        let length_size_minus_one = (cp[21] & 0x03) as usize;
+        assert_eq!(
+            length_size_minus_one + 1,
+            LENGTH_PREFIX_SIZE,
+            "hvcC lengthSizeMinusOne+1 must equal the NAL length-prefix width"
+        );
+        assert_eq!(LENGTH_PREFIX_SIZE, 4, "HEVC length prefix is 4-byte BE");
+    }
+
+    #[test]
+    fn length_prefix_tiles_accepts_well_formed_records() {
+        // Two records: len 3 + len 2, back to back, tiling the buffer exactly.
+        let mut buf = Vec::new();
+        push_length_prefixed(&mut buf, &[0xAA, 0xBB, 0xCC]);
+        push_length_prefixed(&mut buf, &[0x11, 0x22]);
+        assert!(length_prefix_tiles(&buf));
+        assert!(length_prefix_tiles(&[]), "an empty buffer trivially tiles");
+    }
+
+    #[test]
+    fn length_prefix_tiles_rejects_a_desynced_frame() {
+        // A declared length that OVERRUNS the buffer — the shape that surfaces as
+        // "Invalid NAL unit size (N>M)". Declared 0x1000_0001 bytes, only a few
+        // present.
+        let overrun = [0x10, 0x00, 0x00, 0x01, 0xAA, 0xBB, 0xCC];
+        assert!(
+            !length_prefix_tiles(&overrun),
+            "a length that overruns the buffer must be rejected"
+        );
+        // Trailing garbage past the last complete record.
+        let mut trailing = Vec::new();
+        push_length_prefixed(&mut trailing, &[0xAA, 0xBB]);
+        trailing.push(0x99); // one stray byte, not a full length field
+        assert!(
+            !length_prefix_tiles(&trailing),
+            "trailing bytes that don't form a record must be rejected"
+        );
+        // A zero-length record (empty NALU) is structurally invalid.
+        let zero_len = [0x00, 0x00, 0x00, 0x00];
+        assert!(
+            !length_prefix_tiles(&zero_len),
+            "a zero-length record must be rejected"
+        );
+        // A truncated length prefix (fewer than 4 bytes at the tail).
+        assert!(
+            !length_prefix_tiles(&[0x00, 0x00]),
+            "a truncated length prefix must be rejected"
+        );
+    }
+
+    #[test]
+    fn parsed_annex_b_access_unit_tiles_exactly_and_is_emitted() {
+        // Positive path: a normal Annex-B AU (VPS + SPS + PPS + IDR slice) parses
+        // to a frame whose length-prefixed data tiles EXACTLY, so the guard emits
+        // it (never dropped).
+        let mut parser = HevcParser::new();
+        let sps = make_sps_with_chroma(1, 2, 2);
+        let mut data = Vec::new();
+        data.extend_from_slice(&[0x00, 0x00, 0x01]);
+        data.extend_from_slice(&hevc_nal_header(32)); // VPS
+        data.extend_from_slice(&[0xAA, 0xBB]);
+        data.extend_from_slice(&[0x00, 0x00, 0x01]);
+        data.extend_from_slice(&sps); // SPS
+        data.extend_from_slice(&[0x00, 0x00, 0x01]);
+        data.extend_from_slice(&hevc_nal_header(34)); // PPS
+        data.extend_from_slice(&[0xDD, 0xEE]);
+        data.extend_from_slice(&[0x00, 0x00, 0x01]);
+        data.extend_from_slice(&hevc_nal_header(19)); // IDR_W_RADL slice → keyframe
+        data.extend_from_slice(&[0x10, 0x20, 0x30]);
+
+        let frames = parser.parse(&make_pes(data, Some(0)));
+        assert_eq!(frames.len(), 1, "the access unit is emitted, not dropped");
+        assert!(
+            length_prefix_tiles(&frames[0].data),
+            "an emitted HEVC frame's records must tile exactly"
+        );
+    }
+
+    // The build a normal Annex-B AU (VPS + SPS + PPS + IDR) as a helper for the
+    // end-to-end guard test below.
+    #[cfg(test)]
+    fn annex_b_access_unit() -> Vec<u8> {
+        let sps = make_sps_with_chroma(1, 2, 2);
+        let mut data = Vec::new();
+        data.extend_from_slice(&[0x00, 0x00, 0x01]);
+        data.extend_from_slice(&hevc_nal_header(32)); // VPS
+        data.extend_from_slice(&[0xAA, 0xBB]);
+        data.extend_from_slice(&[0x00, 0x00, 0x01]);
+        data.extend_from_slice(&sps); // SPS
+        data.extend_from_slice(&[0x00, 0x00, 0x01]);
+        data.extend_from_slice(&hevc_nal_header(34)); // PPS
+        data.extend_from_slice(&[0xDD, 0xEE]);
+        data.extend_from_slice(&[0x00, 0x00, 0x01]);
+        data.extend_from_slice(&hevc_nal_header(19)); // IDR_W_RADL slice → keyframe
+        data.extend_from_slice(&[0x10, 0x20, 0x30]);
+        data
+    }
+
+    // Issue #52: the guard's WIRING in parse() — a desynced access unit is
+    // dropped (empty emit), a well-formed one is emitted. Disconnecting the guard
+    // from parse() would let the desynced case through and fail this test.
+    #[test]
+    fn parse_drops_desynced_access_unit() {
+        // Well-formed: emitted.
+        let mut parser = HevcParser::new();
+        let frames = parser.parse(&make_pes(annex_b_access_unit(), Some(0)));
+        assert_eq!(frames.len(), 1, "a well-formed access unit is emitted");
+
+        // Same AU, framing forced out of sync: the guard drops it.
+        FORCE_FRAMING_DESYNC.with(|c| c.set(true));
+        let mut parser2 = HevcParser::new();
+        let dropped = parser2.parse(&make_pes(annex_b_access_unit(), Some(0)));
+        FORCE_FRAMING_DESYNC.with(|c| c.set(false));
+        assert!(
+            dropped.is_empty(),
+            "a desynced access unit is dropped by parse(), not emitted"
+        );
+    }
+
    #[test]
    fn hvcc_handles_emulation_prevention_in_sps() {
        // Insert emulation-prevention bytes (00 00 03) after the parsed fields
@@ -16,6 +16,14 @@ const SEGMENT_PCS: u8 = 0x16;
 // Caps a malformed stream that appends non-PCS segments forever without a PCS,
 // dropping further appends until the next PCS resyncs — mirrors DTS/AC-3 caps.
 const MAX_PGS_PENDING_BYTES: usize = 4 * 1024 * 1024;
+// Fallback on-screen dwell (5 s) for a display set whose real end is unknown (EOS
+// trailing set, no-PTS/truncated arms): a None duration on a DefaultDuration-less
+// subtitle track leaves ffmpeg "Timestamps are unset in a packet" (issue #52).
+const DEFAULT_PGS_DURATION_NS: u64 = 5_000_000_000;
+// Cap on a COMPUTED span (clear_pts - display_pts): a missing intermediate PCS can
+// inflate one set to minutes. Past this the value is untrusted and the fallback
+// dwell is used instead; set well above any real dwell so long cues aren't clipped.
+const MAX_PGS_DURATION_NS: u64 = 30_000_000_000;
 // Offset of number_of_composition_objects in a PCS: 3-byte segment header +
 // 10 bytes of PCS fields (video_w/h, frame_rate, comp_num, comp_state,
 // palette_update, palette_id_ref) = 13.
@@ -209,7 +217,15 @@ impl PgsParser {
    fn emit_pending(&mut self, end_pts_ns: i64) -> Option<Frame> {
        let (facts, data) = self.pending.take()?;
        let start_pts = facts.presentation_ns().unwrap_or(0);
-        let duration = end_pts_ns.saturating_sub(start_pts).max(0) as u64;
+        let computed = end_pts_ns.saturating_sub(start_pts).max(0) as u64;
+        // Trust the real computed span, but clamp a pathologically large one (a
+        // missing intermediate PCS makes one set look like it lingered for
+        // minutes) back to the fallback dwell rather than emit an absurd cue.
+        let duration = if computed > MAX_PGS_DURATION_NS {
+            DEFAULT_PGS_DURATION_NS
+        } else {
+            computed
+        };
        Some(Frame {
            discontinuity: false,
            coding: None,
@@ -249,7 +265,7 @@ impl CodecParser for PgsParser {
                        pts_ns: facts.presentation_ns().unwrap_or(0),
                        keyframe: true,
                        data,
-                        duration_ns: None,
+                        duration_ns: Some(DEFAULT_PGS_DURATION_NS),
                    }]
                })
                .unwrap_or_default();
@@ -276,7 +292,7 @@ impl CodecParser for PgsParser {
                        pts_ns: facts.presentation_ns().unwrap_or(0),
                        keyframe: true,
                        data,
-                        duration_ns: None,
+                        duration_ns: Some(DEFAULT_PGS_DURATION_NS),
                    }),
                };
                out.extend(frame);
@@ -307,7 +323,7 @@ impl CodecParser for PgsParser {
                        pts_ns: facts.presentation_ns().unwrap_or(0),
                        keyframe: true,
                        data,
-                        duration_ns: None,
+                        duration_ns: Some(DEFAULT_PGS_DURATION_NS),
                    }));
                }
            },
@@ -336,7 +352,7 @@ impl CodecParser for PgsParser {
                        pts_ns: pts.unwrap_or(0),
                        keyframe: true,
                        data: pes.data.clone(),
-                        duration_ns: None,
+                        duration_ns: Some(DEFAULT_PGS_DURATION_NS),
                    });
                }
                // No pending set AND no PTS: drop it. Emitting at pts_ns=0 would
@@ -360,7 +376,7 @@ impl CodecParser for PgsParser {
                pts_ns: facts.presentation_ns().unwrap_or(0),
                keyframe: true,
                data,
-                duration_ns: None,
+                duration_ns: Some(DEFAULT_PGS_DURATION_NS),
            }],
            None => Vec::new(),
        }
@@ -548,8 +564,10 @@ mod tests {
        assert_eq!(frames.len(), 1, "final pending subtitle must flush");
        assert_eq!(frames[0].pts_ns, 1_000_000_000);
        assert_eq!(frames[0].data, display);
-        // Trailing block lingers to EOF — no duration per module doc.
-        assert_eq!(frames[0].duration_ns, None);
+        // Trailing block has no follower PCS, so its real end is unknown; it now
+        // carries the synthesized fallback dwell (was `None`) so every subtitle
+        // block gets a BlockDuration (issue #52).
+        assert_eq!(frames[0].duration_ns, Some(DEFAULT_PGS_DURATION_NS));
    }

    #[test]
@@ -575,16 +593,20 @@ mod tests {
    }

    #[test]
-    fn clear_pcs_without_pts_emits_pending_undurated() {
-        // A clear PCS that lacks a PTS can't compute a duration; the pending
-        // display is still emitted, but with no duration (lingers to EOF)
-        // instead of a bogus absurd one.
+    fn clear_pcs_without_pts_emits_fallback_duration() {
+        // A clear PCS that lacks a PTS can't compute a real duration; the pending
+        // display is still emitted, now with the synthesized fallback dwell (was
+        // `None`) so the subtitle block carries a BlockDuration (issue #52).
        let mut parser = PgsParser::new();
        let _ = parser.parse(&make_pes(pcs_bytes(1), Some(90000)));
        let f = parser.parse(&make_pes(pcs_bytes(0), None));
        assert_eq!(f.len(), 1);
        assert_eq!(f[0].pts_ns, 1_000_000_000, "pending keeps its real start");
-        assert_eq!(f[0].duration_ns, None, "no duration without a clear PTS");
+        assert_eq!(
+            f[0].duration_ns,
+            Some(DEFAULT_PGS_DURATION_NS),
+            "fallback duration when the clear PCS carries no PTS"
+        );
    }

    #[test]
@@ -605,7 +627,11 @@ mod tests {
        let frames = parser.parse(&make_pes(truncated, Some(180000)));
        assert_eq!(frames.len(), 1, "pending display flushed on truncated PCS");
        assert_eq!(frames[0].data, display, "pending bitmap not polluted");
-        assert_eq!(frames[0].duration_ns, None, "flushed undurated");
+        assert_eq!(
+            frames[0].duration_ns,
+            Some(DEFAULT_PGS_DURATION_NS),
+            "flushed with fallback duration (issue #52)"
+        );
        assert!(parser.pending.is_none(), "parser resynced");
    }

@@ -695,6 +721,37 @@ mod tests {
        assert_eq!(f[0].duration_ns, Some(0));
    }

+    #[test]
+    fn pathologically_large_computed_duration_clamps_to_fallback() {
+        // A missing intermediate clear PCS makes a set appear to linger until a much
+        // later one; a computed span past MAX_PGS_DURATION_NS is untrusted and falls
+        // back to the dwell instead of an absurd multi-minute cue (90000 ticks = 1s).
+        let display_pts = 90_000_i64; // 1 s
+        // 40 s later in 90 kHz ticks (> 30 s cap).
+        let clear_pts = display_pts + 40 * 90_000;
+        let mut parser = PgsParser::new();
+        let _ = parser.parse(&make_pes(pcs_bytes(1), Some(display_pts)));
+        let f = parser.parse(&make_pes(pcs_bytes(0), Some(clear_pts)));
+        assert_eq!(f.len(), 1);
+        assert_eq!(
+            f[0].duration_ns,
+            Some(DEFAULT_PGS_DURATION_NS),
+            "a >30s computed span is clamped to the fallback dwell"
+        );
+    }
+
+    #[test]
+    fn legitimate_long_duration_is_not_clamped() {
+        // A real, in-range dwell (10 s, well under the 30 s cap) is preserved
+        // exactly — the clamp must never clip a legitimately long subtitle.
+        let display_pts = 90_000_i64; // 1 s
+        let clear_pts = display_pts + 10 * 90_000; // +10 s
+        let mut parser = PgsParser::new();
+        let _ = parser.parse(&make_pes(pcs_bytes(1), Some(display_pts)));
+        let f = parser.parse(&make_pes(pcs_bytes(0), Some(clear_pts)));
+        assert_eq!(f[0].duration_ns, Some(10_000_000_000));
+    }
+
    // --- clear / replace edge cases ---

    #[test]
@@ -722,11 +779,11 @@ mod tests {
        assert_eq!(f2.len(), 1);
        assert_eq!(f2[0].pts_ns, 2_000_000_000);
        assert_eq!(f2[0].duration_ns, Some(1_000_000_000));
-        // Third held; flush emits it undurated.
+        // Third held; flush emits it with the fallback dwell (no follower PCS).
        let tail = parser.flush();
        assert_eq!(tail.len(), 1);
        assert_eq!(tail[0].pts_ns, 3_000_000_000);
-        assert_eq!(tail[0].duration_ns, None);
+        assert_eq!(tail[0].duration_ns, Some(DEFAULT_PGS_DURATION_NS));
    }

    #[test]
@@ -740,7 +797,7 @@ mod tests {
        let exactly_13 = vec![SEGMENT_PCS; PCS_NUM_OBJECTS_OFFSET]; // 13 bytes
        let f = parser.parse(&make_pes(exactly_13, Some(180000)));
        assert_eq!(f.len(), 1, "13-byte PCS is truncated → flush pending");
-        assert_eq!(f[0].duration_ns, None);
+        assert_eq!(f[0].duration_ns, Some(DEFAULT_PGS_DURATION_NS));
        assert!(parser.pending.is_none());
    }

@@ -768,7 +825,9 @@ mod tests {
        assert_eq!(f.len(), 1);
        assert!(f[0].keyframe);
        assert_eq!(f[0].pts_ns, 1_000_000_000);
-        assert_eq!(f[0].duration_ns, None);
+        // A pass-through segment has no known end; it now carries the fallback
+        // dwell (was `None`) so it too gets a BlockDuration (issue #52).
+        assert_eq!(f[0].duration_ns, Some(DEFAULT_PGS_DURATION_NS));
    }

    #[test]
@@ -1383,7 +1383,6 @@ mod tests {
        // engages. Key contents are irrelevant to the read plan.
        let aacs = DecryptKeys::Aacs {
            unit_keys: vec![(0, [0u8; 16]), (1, [1u8; 16])],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        // 100 units (300 sectors). A 10-unit Even forensic segment at LBA [30,60):
@@ -1859,7 +1858,6 @@ mod tests {
        let title = synthetic_title(COUNT);
        let keys = crate::decrypt::DecryptKeys::Aacs {
            unit_keys: vec![(0, [0u8; 16])],
-            read_data_key: None,
            format: crate::disc::ContentFormat::BdTs,
        };
        let mut stream = DiscStream::new(
@@ -2385,7 +2383,6 @@ mod tests {
                synthetic_title(8),
                crate::decrypt::DecryptKeys::Aacs {
                    unit_keys: vec![(0, [0x11u8; 16])],
-                    read_data_key: None,
                    format: ContentFormat::BdTs,
                },
                3,
@@ -1584,7 +1584,6 @@ mod tests {
        }];
        let keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, unit_key)],
-            read_data_key: None,
            format: crate::disc::ContentFormat::BdTs,
        };

@@ -1644,7 +1643,6 @@ mod tests {
                key_source: crate::disc::KeyOrigin::KeyDb,
                vuk: None,
                unit_keys: vec![(0, unit_key)],
-                read_data_key: None,
                volume_id: [0u8; 16],
                uk_ro: Vec::new(),
                mkb: Vec::new(),
@@ -1852,7 +1850,6 @@ mod tests {
        let mut r = mk_reader();
        let mut keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, unit_key)],
-            read_data_key: None,
            format: crate::disc::ContentFormat::BdTs,
        };
        let map = resolve_inline_base_map(
@@ -1871,7 +1868,6 @@ mod tests {
        let mut r = mk_reader();
        let mut keys_raw = DecryptKeys::Aacs {
            unit_keys: vec![(0, unit_key)],
-            read_data_key: None,
            format: crate::disc::ContentFormat::BdTs,
        };
        let map_raw = resolve_inline_base_map(
@@ -546,6 +546,14 @@ pub struct MkvMuxer<W: Write + Seek> {
    /// non-monotonic. Keying the exemption on track type (not index) keeps that
    /// EL's true PTS instead of clobbering it to prev+1ms.
    track_is_video: Vec<bool>,
+    /// Per-track-index flag: true if the track is a subtitle track
+    /// (`track_type == 17`). A subtitle block must NEVER be written as a bare
+    /// `SimpleBlock`: subtitle tracks carry no `DefaultDuration`, so without a
+    /// `BlockDuration` a demuxer has nothing to bound the cue and ffmpeg reports
+    /// "Timestamps are unset in a packet for stream N" (issue #52). Keyed on
+    /// track type (mirroring `track_is_video`) so the invariant holds for every
+    /// subtitle track — including a sparse forced-narrative second track.
+    track_is_subtitle: Vec<bool>,
    /// Index of the PRIMARY video track — the first track whose type is video.
    /// This (not the literal index 0) is the clip-boundary epoch driver: the
    /// M2TS/PMT path orders streams by PMT declaration order and may list an
@@ -698,6 +706,11 @@ struct InterlacedRewrite {
 // video and TrueHD's 0.833 ms AUs. See docs/mkv-mux.md — TimestampScale choice.
 const TIMESTAMP_SCALE_NS: i64 = 100_000;

+// Last-resort BlockDuration (1 s) for a SUBTITLE frame that reaches the muxer with
+// no duration. Parsers (PGS) already synthesize one; this only fires if another
+// subtitle path forgets, keeping every subtitle block durated (issue #52).
+const MIN_SUBTITLE_BLOCK_DURATION_NS: i64 = 1_000_000_000;
+
 // Nominal new-cluster interval (2 s) in TimestampScale ticks; a keyframe
 // only opens a new cluster once this much has elapsed. See docs/mkv-mux.md
 // — cluster duration vs. i16 block-relative limit.
@@ -1128,6 +1141,10 @@ impl<W: Write + Seek> MkvMuxer<W> {
                .iter()
                .map(|t| t.track_type == ebml::TRACK_TYPE_VIDEO)
                .collect(),
+            track_is_subtitle: tracks
+                .iter()
+                .map(|t| t.track_type == ebml::TRACK_TYPE_SUBTITLE)
+                .collect(),
            primary_video_track: tracks
                .iter()
                .position(|t| t.track_type == ebml::TRACK_TYPE_VIDEO),
@@ -1350,6 +1367,21 @@ impl<W: Write + Seek> MkvMuxer<W> {
        let relative_ts = (pts_ticks - self.cluster_ts_ticks) as i16;
        let duration_ticks =
            duration_ns.map(|dur_ns| (dur_ns as i64 / TIMESTAMP_SCALE_NS).max(1) as u64);
+        // Defense in depth (issue #52): a SUBTITLE block must never be a bare
+        // SimpleBlock (no DefaultDuration => unbounded cue, ffmpeg "Timestamps are
+        // unset"). Substitute a minimum fallback so it takes the BlockGroup arm.
+        let is_subtitle = self
+            .track_is_subtitle
+            .get(track_idx)
+            .copied()
+            .unwrap_or(false);
+        let duration_ticks = match duration_ticks {
+            Some(dt) => Some(dt),
+            None if is_subtitle => {
+                Some((MIN_SUBTITLE_BLOCK_DURATION_NS / TIMESTAMP_SCALE_NS).max(1) as u64)
+            }
+            None => None,
+        };
        // A BlockAdditional with BlockAddID=2 conforms only when the track declared
        // the matching mvcC mapping; if not (dependent-view params never captured
        // before the header was written), drop it and emit a plain block instead.
@@ -4790,6 +4822,133 @@ mod tests {
        );
    }

+    // ── issue #52: every subtitle block carries a BlockDuration ──────────────
+
+    fn make_subtitle_track() -> MkvTrack {
+        MkvTrack {
+            track_type: ebml::TRACK_TYPE_SUBTITLE,
+            codec_id: ebml::CODEC_PGS,
+            language: "eng".into(),
+            name: String::new(),
+            codec_private: None,
+            is_default: false,
+            is_forced: false,
+            pixel_width: 0,
+            pixel_height: 0,
+            default_duration_ns: 0,
+            display_width: 0,
+            display_height: 0,
+            colour_matrix: 0,
+            colour_transfer: 0,
+            colour_primaries: 0,
+            colour_range: 0,
+            interlaced: false,
+            field_order: ebml::FIELD_ORDER_UNDETERMINED,
+            field_duration_ns: 0,
+            sample_rate: 0.0,
+            channels: 0,
+            bit_depth: 0,
+            dv_config: None,
+            hdr10: None,
+            mvc_params: None,
+        }
+    }
+
+    /// Matroska TrackNumbers (1-based) of every SimpleBlock in the output, in
+    /// emission order. The subtitle invariant is that NONE of these is a
+    /// subtitle track.
+    fn all_simple_block_tracks(data: &[u8]) -> Vec<u64> {
+        let mut out = Vec::new();
+        for (body_start, body_size, _ts) in find_clusters(data) {
+            let body = &data[body_start..body_start + body_size as usize];
+            let mut cursor = Cursor::new(body);
+            let (tid, tsize, _) = ebml::read_element_header(&mut cursor).unwrap();
+            assert_eq!(tid, ebml::CLUSTER_TIMESTAMP);
+            cursor.seek(io::SeekFrom::Current(tsize as i64)).unwrap();
+            while (cursor.position() as usize) < body.len() {
+                let Ok((id, size, _)) = ebml::read_element_header(&mut cursor) else {
+                    break;
+                };
+                let start = cursor.position() as usize;
+                if start + size as usize > body.len() {
+                    break;
+                }
+                if id == ebml::SIMPLE_BLOCK {
+                    let blk = &body[start..start + size as usize];
+                    let track = if blk[0] & 0x80 != 0 {
+                        (blk[0] & 0x7F) as u64
+                    } else {
+                        (((blk[0] & 0x3F) as u64) << 8) | blk[1] as u64
+                    };
+                    out.push(track);
+                }
+                cursor.seek(io::SeekFrom::Current(size as i64)).unwrap();
+            }
+        }
+        out
+    }
+
+    #[test]
+    fn subtitle_frame_with_no_duration_becomes_block_group_with_block_duration() {
+        // issue #52: a SUBTITLE frame with duration=None must never be a bare
+        // SimpleBlock (no DefaultDuration => unbounded cue). The muxer substitutes a
+        // minimum fallback and emits a BlockGroup WITH a BlockDuration.
+        let tracks = [make_subtitle_track()];
+        let data = mux_with_durations(&tracks, &[(0, 0, true, vec![0x16, 0xAA], None)]);
+
+        let groups = all_block_groups(&data);
+        assert_eq!(
+            groups.len(),
+            1,
+            "the subtitle frame must be a BlockGroup, not a SimpleBlock"
+        );
+        assert!(
+            groups[0].duration > 0,
+            "the BlockGroup must carry a BlockDuration (got {})",
+            groups[0].duration
+        );
+        assert!(
+            all_simple_block_tracks(&data).is_empty(),
+            "no subtitle frame may be emitted as a bare SimpleBlock"
+        );
+    }
+
+    #[test]
+    fn every_block_on_both_subtitle_tracks_has_a_block_duration() {
+        // Models a Blu-ray's two PGS tracks: a DENSE dialogue track and a SPARSE
+        // forced-narrative one. EVERY block on BOTH must be a BlockGroup carrying a
+        // BlockDuration, even those handed in with duration=None.
+        let tracks = [make_subtitle_track(), make_subtitle_track()];
+        let frames: Vec<DurFrame> = vec![
+            // Track 0 (dense): opens the cluster, then two more, mixing a real
+            // duration with two None durations.
+            (0, 0, true, vec![0x16, 0x01], Some(2_000_000_000)),
+            (0, 1_000_000_000, true, vec![0x16, 0x02], None),
+            (0, 2_000_000_000, true, vec![0x16, 0x03], None),
+            // Track 1 (sparse): a single forced cue, handed in with no duration.
+            (1, 500_000_000, true, vec![0x16, 0xFF], None),
+        ];
+        let data = mux_with_durations(&tracks, &frames);
+
+        assert!(
+            all_simple_block_tracks(&data).is_empty(),
+            "no subtitle frame on EITHER track may be a bare SimpleBlock"
+        );
+        let groups = all_block_groups(&data);
+        assert_eq!(groups.len(), 4, "all four subtitle frames are BlockGroups");
+        for g in &groups {
+            assert!(
+                g.duration > 0,
+                "every subtitle block must carry a BlockDuration (track {}, dur {})",
+                g.track,
+                g.duration
+            );
+        }
+        // Both subtitle tracks (Matroska TrackNumbers 1 and 2) are represented.
+        assert!(groups.iter().any(|g| g.track == 1), "dense track present");
+        assert!(groups.iter().any(|g| g.track == 2), "sparse track present");
+    }
+
    // Cluster boundary (CLUSTER_DURATION_TICKS): a new cluster opens on a video
    // keyframe once >= the cluster duration has elapsed since the open cluster's
    // timestamp; one just under the boundary stays in the current cluster.
@@ -2359,7 +2359,6 @@ mod tests {
        // (pool_len == 1 would short-circuit to content_map before any read).
        let mut keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, [0x11u8; 16]), (1, [0x22u8; 16])],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        let mut reader = HaltCountSource {
@@ -2397,7 +2396,6 @@ mod tests {
        }];
        let mut keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, [0x11u8; 16]), (1, [0x22u8; 16])],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        let mut reader = HaltCountSource {
@@ -3170,7 +3168,6 @@ mod tests {
        };
        let mut keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, key_a), (1, key_b), (2, key_c)],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        let title = multi_cps_title(start, sectors);
@@ -3205,7 +3202,6 @@ mod tests {
        };
        let mut keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, key_a), (1, key_b)],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        let title = multi_cps_title(start, sectors);
@@ -3237,7 +3233,6 @@ mod tests {
        };
        let mut keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, key_a), (1, key_b)],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        let title = multi_cps_title(start, sectors);
@@ -3337,7 +3332,6 @@ mod tests {
        ]);
        let mut keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, key_a), (1, key_b), (2, key_c)],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        let mut cache = super::DiscKeyCache::new();
@@ -3430,7 +3424,6 @@ mod tests {
        ];
        let mut keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, key_a), (1, key_b), (2, key_c)],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };

@@ -3499,7 +3492,6 @@ mod tests {
        ]);
        let mut keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, key_a), (1, key_b), (2, key_c)],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        let mut cache = super::DiscKeyCache::new();
@@ -3575,7 +3567,6 @@ mod tests {
        // to index 0 without sampling); neither opens the extent → fail loud.
        let mut keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, key_a), (1, [0x02u8; 16])],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        super::resolve_mux_key_map_cached(
@@ -3643,7 +3634,6 @@ mod tests {
        let title = multi_cps_title(1000, 30);
        let mut keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, [0x01u8; 16])],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        let got = super::resolve_fmts_key_map(
@@ -3680,7 +3670,6 @@ mod tests {
        let title = multi_cps_title(1000, 30);
        let mut keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, [0x01u8; 16])],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        let got = super::resolve_fmts_key_map(
@@ -4016,7 +4005,6 @@ mod tests {
    fn fmts_keys() -> DecryptKeys {
        DecryptKeys::Aacs {
            unit_keys: vec![(0, FMTS_BASE_KEY)],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        }
    }
@@ -4042,7 +4030,6 @@ mod tests {
    fn fmts_two_cps_keys() -> DecryptKeys {
        DecryptKeys::Aacs {
            unit_keys: vec![(1, FMTS_BASE_KEY), (2, FMTS_CPS2_KEY)],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        }
    }
@@ -4407,7 +4394,6 @@ mod tests {
        ]);
        let mut keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, key_a), (1, key_b)],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        let mut cache = super::DiscKeyCache::new();
@@ -5012,7 +4998,6 @@ mod tests {
        )]);
        let mut keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, key_a), (1, key_b), (2, key_c)],
-            read_data_key: None,
            format: ContentFormat::BdTs,
        };
        let mut cache = super::DiscKeyCache::new();
@@ -2089,11 +2089,9 @@ mod tests {
        );
    }

-    // A provisional must retire even PAST the epoch-history cap. Epoch identity
-    // was `epoch_offsets.len()`, which pins at MAX_EPOCHS once the ring is full,
-    // so a provisional captured then compared equal forever and never retired —
-    // drifting that track away from every other for the rest of the title. The
-    // monotonic `epoch_seq` keeps distinguishing epochs past the cap.
+    // A provisional must retire even PAST the epoch-history cap: the old identity
+    // `epoch_offsets.len()` pinned at MAX_EPOCHS once the ring filled, so a
+    // provisional compared equal forever; monotonic `epoch_seq` fixes that.
    #[test]
    fn a_provisional_retires_even_past_the_epoch_history_cap() {
        let mut tc = TimelineContinuity::new();
@@ -141,18 +141,17 @@ impl PesFrame {
        if len > MAX_FRAME_SIZE {
            return Err(crate::error::Error::PesFrameTooLarge { size: len }.into());
        }
-        // Grow the buffer INCREMENTALLY (not `vec![0u8; len]`): `len` is attacker-controlled
-        // up to MAX_FRAME_SIZE (256 MiB), so a truncated stream claiming a huge frame must not
-        // pre-allocate the max; a bounded scratch chunk tracks delivered bytes, short reads still surface UnexpectedEof, valid frames assemble byte-for-byte.
-        const GROW_CHUNK: usize = 1024 * 1024; // 1 MiB scratch, heap-allocated
+        // Grow INCREMENTALLY (not `vec![0u8; len]`): `len` is attacker-controlled to 256 MiB, so
+        // a truncated stream claiming a huge frame must not pre-allocate the max. Read each chunk
+        // straight into `data`'s own tail — no scratch buffer, no second copy; short reads EOF.
+        const GROW_CHUNK: usize = 1024 * 1024; // 1 MiB growth step
        let mut data: Vec<u8> = Vec::with_capacity(len.min(GROW_CHUNK));
-        let mut chunk = vec![0u8; GROW_CHUNK.min(len).max(1)];
-        let mut remaining = len;
-        while remaining > 0 {
-            let want = remaining.min(chunk.len());
-            r.read_exact(&mut chunk[..want])?;
-            data.extend_from_slice(&chunk[..want]);
-            remaining -= want;
+        let mut filled = 0usize;
+        while filled < len {
+            let want = (len - filled).min(GROW_CHUNK);
+            data.resize(filled + want, 0);
+            r.read_exact(&mut data[filled..filled + want])?;
+            filled += want;
        }
        Ok(Some(Self {
            track,
@@ -338,24 +338,25 @@ impl ScsiTransport for SgIoTransport {
            let recovery = self.fd_recovery.clone();
            let dead = self.dead.clone();

-            // Cap outstanding recovery threads: past MAX_RECOVERY_THREADS a
-            // sustained wedge would spawn unbounded threads, so fall back to
-            // doing the close/reopen inline on this thread instead.
+            // Cap outstanding recovery threads (past MAX a sustained wedge spawns
+            // unbounded threads): reserve the slot ATOMICALLY via fetch_add, act on
+            // the pre-increment value, and give the slot back if it overshoots.
            use std::sync::atomic::Ordering;
-            if RECOVERY_THREADS.load(Ordering::Acquire) < MAX_RECOVERY_THREADS {
-                RECOVERY_THREADS.fetch_add(1, Ordering::AcqRel);
+            if RECOVERY_THREADS.fetch_add(1, Ordering::AcqRel) < MAX_RECOVERY_THREADS {
                std::thread::spawn(move || {
                    if old_fd >= 0 {
                        unsafe { libc::close(old_fd) };
                    }
                    RECOVERY_THREADS.fetch_sub(1, Ordering::AcqRel);
                });
-            } else if old_fd >= 0 {
-                unsafe { libc::close(old_fd) };
+            } else {
+                RECOVERY_THREADS.fetch_sub(1, Ordering::AcqRel);
+                if old_fd >= 0 {
+                    unsafe { libc::close(old_fd) };
+                }
            }

-            if RECOVERY_THREADS.load(Ordering::Acquire) < MAX_RECOVERY_THREADS {
-                RECOVERY_THREADS.fetch_add(1, Ordering::AcqRel);
+            if RECOVERY_THREADS.fetch_add(1, Ordering::AcqRel) < MAX_RECOVERY_THREADS {
                std::thread::spawn(move || {
                    // Don't unwrap: a device path with an interior NUL would
                    // panic this detached thread (silently swallowed). Bail
@@ -383,17 +384,20 @@ impl ScsiTransport for SgIoTransport {
                    }
                    RECOVERY_THREADS.fetch_sub(1, Ordering::AcqRel);
                });
-            } else if let Ok(c_path) = std::ffi::CString::new(path.as_os_str().as_encoded_bytes()) {
-                // At the recovery-thread cap: reopen inline (blocking this
-                // call briefly) instead of spawning an unbounded 9th thread.
-                let new_fd = unsafe {
-                    libc::open(
-                        c_path.as_ptr() as *const libc::c_char,
-                        libc::O_RDWR | libc::O_NONBLOCK | libc::O_CLOEXEC,
-                    )
-                };
-                if new_fd >= 0 {
-                    self.fd = new_fd;
+            } else {
+                // Over the cap: give the reservation back, then reopen inline
+                // (blocking this call briefly) instead of spawning a 9th thread.
+                RECOVERY_THREADS.fetch_sub(1, Ordering::AcqRel);
+                if let Ok(c_path) = std::ffi::CString::new(path.as_os_str().as_encoded_bytes()) {
+                    let new_fd = unsafe {
+                        libc::open(
+                            c_path.as_ptr() as *const libc::c_char,
+                            libc::O_RDWR | libc::O_NONBLOCK | libc::O_CLOEXEC,
+                        )
+                    };
+                    if new_fd >= 0 {
+                        self.fd = new_fd;
+                    }
                }
            }

@@ -0,0 +1,398 @@
+//! `BusRemovalSectorSource` — a stream form of AACS bus-encryption removal.
+//!
+//! # Where bus removal actually happens
+//! AACS 2.0 "bus encryption" (BEE) wraps content on the drive↔host transport,
+//! and removing it is the UNLOCKER's job. The single de-bus TRANSFORM is
+//! [`decrypt_bus_in_content`]; in the PRODUCTION path it is applied once, at the
+//! very bottom of the read chain, inside the live drive's own `SectorSource`
+//! impl (`Drive::remove_bus_encryption`, gated by the drive's `BusStage` +
+//! content ranges). Every reader above it (key sampler, mux, unit-key
+//! validation, whole-disc sweep) reads the `Drive` as `&mut dyn SectorSource`
+//! and so transparently sees bus-removed sectors and never reasons about bus
+//! encryption.
+//!
+//! This decorator is an equivalent, independently-tested STREAM form of that
+//! same transform (it also calls [`decrypt_bus_in_content`]), kept for tests and
+//! for any future non-`Drive` source that needs de-bussing. It is NOT wired into
+//! the production chain today. DANGER: never wrap the live `Drive` in this
+//! decorator — the `Drive` already de-busses, so a second pass would DOUBLE-
+//! de-bus and corrupt content. There must only ever be ONE de-bus in a chain.
+//!
+//! # How the stage is chosen
+//! [`BusStage`] is computed ONCE from the unlock result:
+//!   * a firmware/vendor unlocker (freemkv / LibreDrive / Renesas) removes bus
+//!     encryption AT THE DRIVE (`Bus=off`), and a non-bus disc (DVD / clear BD)
+//!     has none → [`BusStage::Passthrough`] (reads pass through untouched);
+//!   * the AACS cert route yields the Read Data Key from the AKE, so the host
+//!     must de-bus each content sector → [`BusStage::AacsHostKey`].
+//!
+//! # Content gating
+//! De-bussing a clear UDF/nav sector would corrupt plaintext, so the host-key
+//! path is gated to the disc's encrypted-content extents via
+//! [`with_content_ranges`](BusRemovalSectorSource::with_content_ranges) — the
+//! same `(start_lba, sector_count)` map [`DecryptingSectorSource`] uses. Absent
+//! a map, the caller reads content-only (title extents) and every sector is
+//! treated as content — matching the pre-overhaul behaviour where `decrypt_bus`
+//! ran on content units only.
+//!
+//! [`decrypt_bus_in_content`]: crate::aacs::content::decrypt_bus_in_content
+//! [`DecryptingSectorSource`]: crate::sector::decrypting::DecryptingSectorSource
+
+use std::sync::Arc;
+
+use crate::error::Result;
+
+use super::SectorSource;
+
+/// How this drive's AACS bus encryption is removed — decided once from the
+/// unlock result, never re-examined downstream.
+#[derive(Clone)]
+pub enum BusStage {
+    /// Bus encryption was removed at the drive by a firmware/vendor unlocker
+    /// (`Bus=off`), or the disc carries none (DVD / clear BD). Reads pass
+    /// through untouched.
+    Passthrough,
+    /// AACS cert route: the host holds the Read Data Key from the AKE and
+    /// de-busses each content sector in software.
+    AacsHostKey([u8; 16]),
+}
+
+impl BusStage {
+    /// Map an unlock/handshake result to the bus stage: a cert-route Read Data
+    /// Key (`Some`) means the host must de-bus content in software
+    /// ([`BusStage::AacsHostKey`]); its absence (`None`) means bus encryption was
+    /// removed at the drive by a firmware/vendor unlock, or the disc never had it
+    /// ([`BusStage::Passthrough`]). This is the SINGLE decision point that wires
+    /// [`crate::disc::Disc::scan`]'s handshake to the drive's de-bus.
+    pub fn from_read_data_key(read_data_key: Option<[u8; 16]>) -> Self {
+        match read_data_key {
+            Some(rdk) => BusStage::AacsHostKey(rdk),
+            None => BusStage::Passthrough,
+        }
+    }
+}
+
+// `BusStage` wraps a raw key; keep it out of logs.
+impl std::fmt::Debug for BusStage {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            BusStage::Passthrough => write!(f, "BusStage::Passthrough"),
+            BusStage::AacsHostKey(_) => write!(f, "BusStage::AacsHostKey([redacted])"),
+        }
+    }
+}
+
+/// Decorator: read from `inner`, then remove AACS bus encryption from the bytes
+/// that landed in `buf` when the [`BusStage`] carries a host key. A
+/// [`BusStage::Passthrough`] stream is a zero-cost pass-through.
+pub struct BusRemovalSectorSource<S: SectorSource> {
+    inner: S,
+    stage: BusStage,
+    /// Encrypted-content extent map (sorted/merged `(start_lba, sector_count)`).
+    /// `None` = caller reads content-only, so every sector is de-bussed;
+    /// `Some` = a whole-disc reader, so clear sectors outside these ranges pass
+    /// through untouched. Ignored entirely by [`BusStage::Passthrough`].
+    content_ranges: Option<Arc<[(u32, u32)]>>,
+}
+
+impl<S: SectorSource> BusRemovalSectorSource<S> {
+    /// Wrap `inner` with the bus stage decided by the unlock result.
+    pub fn new(inner: S, stage: BusStage) -> Self {
+        Self {
+            inner,
+            stage,
+            content_ranges: None,
+        }
+    }
+
+    /// Restrict host-key de-bussing to the disc's encrypted-content extents;
+    /// clear sectors outside them pass through untouched. Whole-disc readers
+    /// (sweep / patch) set this; content-only readers (mux title extents,
+    /// sampler) leave it unset.
+    pub fn with_content_ranges(mut self, ranges: Arc<[(u32, u32)]>) -> Self {
+        self.content_ranges = Some(ranges);
+        self
+    }
+
+    /// `&mut` counterpart of [`with_content_ranges`](Self::with_content_ranges),
+    /// for readers that build the stream before the content map is known.
+    pub fn set_content_ranges(&mut self, ranges: Arc<[(u32, u32)]>) {
+        self.content_ranges = Some(ranges);
+    }
+
+    /// Borrow the inner source (tests / introspection).
+    pub fn inner(&self) -> &S {
+        &self.inner
+    }
+
+    /// Mutable borrow of the inner source.
+    pub fn inner_mut(&mut self) -> &mut S {
+        &mut self.inner
+    }
+
+    /// Consume the decorator and return the underlying source.
+    pub fn into_inner(self) -> S {
+        self.inner
+    }
+}
+
+impl<S: SectorSource> SectorSource for BusRemovalSectorSource<S> {
+    fn capacity_sectors(&self) -> u32 {
+        self.inner.capacity_sectors()
+    }
+
+    fn read_sectors(
+        &mut self,
+        lba: u32,
+        count: u16,
+        buf: &mut [u8],
+        recovery: bool,
+    ) -> Result<usize> {
+        self.read_sectors_fua(lba, count, buf, recovery, false)
+    }
+
+    fn read_sectors_fua(
+        &mut self,
+        lba: u32,
+        count: u16,
+        buf: &mut [u8],
+        recovery: bool,
+        fua: bool,
+    ) -> Result<usize> {
+        let n = self
+            .inner
+            .read_sectors_fua(lba, count, buf, recovery, fua)?;
+        if let BusStage::AacsHostKey(rdk) = &self.stage {
+            crate::aacs::content::decrypt_bus_in_content(
+                &mut buf[..n],
+                rdk,
+                lba,
+                self.content_ranges.as_deref(),
+            );
+        }
+        Ok(n)
+    }
+
+    fn set_speed(&mut self, kbs: u16) {
+        self.inner.set_speed(kbs)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::aacs::content::encrypt_bus;
+    use crate::consts::SECTOR_BYTES;
+
+    /// A source returning a fixed buffer for any read (starting at whatever the
+    /// fixture built), reporting the full span.
+    struct FixedSource {
+        bytes: Vec<u8>,
+    }
+    impl SectorSource for FixedSource {
+        fn capacity_sectors(&self) -> u32 {
+            (self.bytes.len() / SECTOR_BYTES) as u32
+        }
+        fn read_sectors(
+            &mut self,
+            _lba: u32,
+            count: u16,
+            buf: &mut [u8],
+            _recovery: bool,
+        ) -> Result<usize> {
+            let n = (count as usize * SECTOR_BYTES).min(self.bytes.len());
+            buf[..n].copy_from_slice(&self.bytes[..n]);
+            Ok(n)
+        }
+    }
+
+    // A recognisable clear "content" unit: plaintext first 16 bytes of each
+    // sector (bus enc leaves those clear on the wire), a known pattern in
+    // 16..2048. Two sectors so cross-sector gating is exercised.
+    fn clear_content(sectors: usize) -> Vec<u8> {
+        let mut v = vec![0u8; sectors * SECTOR_BYTES];
+        for (i, b) in v.iter_mut().enumerate() {
+            *b = (i as u8).wrapping_mul(31).wrapping_add(7);
+        }
+        v
+    }
+
+    // The single wiring decision: a cert-route Read Data Key becomes a host-key
+    // stage; its absence (firmware/vendor unlock, or a non-bus disc) is Passthrough.
+    #[test]
+    fn from_read_data_key_maps_handshake_to_stage() {
+        let rdk = [0xABu8; 16];
+        match BusStage::from_read_data_key(Some(rdk)) {
+            BusStage::AacsHostKey(k) => {
+                assert_eq!(k, rdk, "cert RDK carries into the host-key stage")
+            }
+            BusStage::Passthrough => panic!("a Some(read_data_key) must map to AacsHostKey"),
+        }
+        assert!(
+            matches!(BusStage::from_read_data_key(None), BusStage::Passthrough),
+            "no read_data_key (firmware/vendor unlock or non-bus disc) must map to Passthrough"
+        );
+    }
+
+    // Passthrough must hand bytes back byte-identical — even a stream fed
+    // already-clear content never touches it.
+    #[test]
+    fn passthrough_returns_bytes_unchanged() {
+        let clear = clear_content(2);
+        let src = FixedSource {
+            bytes: clear.clone(),
+        };
+        let mut s = BusRemovalSectorSource::new(src, BusStage::Passthrough);
+        let mut got = vec![0u8; 2 * SECTOR_BYTES];
+        let n = s.read_sectors(100, 2, &mut got, false).unwrap();
+        assert_eq!(n, 2 * SECTOR_BYTES);
+        assert_eq!(got, clear, "Passthrough must not alter any byte");
+    }
+
+    // The core contract: a bus-ENCRYPTED sector read through an AacsHostKey
+    // stream comes back as the known plaintext. MUTATION: dropping the de-bus
+    // call (or using Passthrough) leaves the ciphertext, so this goes red.
+    #[test]
+    fn host_key_removes_bus_encryption() {
+        let rdk = [0x5Au8; 16];
+        let clear = clear_content(2);
+        let mut wire = clear.clone();
+        encrypt_bus(&mut wire, &rdk); // model the drive's forward bus transform
+        assert_ne!(wire, clear, "fixture must actually be bus-encrypted");
+
+        let src = FixedSource { bytes: wire };
+        let mut s = BusRemovalSectorSource::new(src, BusStage::AacsHostKey(rdk));
+        let mut got = vec![0u8; 2 * SECTOR_BYTES];
+        let n = s.read_sectors(0, 2, &mut got, false).unwrap();
+        assert_eq!(n, 2 * SECTOR_BYTES);
+        assert_eq!(
+            got, clear,
+            "AacsHostKey must recover the plaintext byte-for-byte"
+        );
+    }
+
+    // A sector OUTSIDE the content map is clear filesystem and must pass through
+    // untouched (de-bussing it would corrupt plaintext). LBA 0 is outside content
+    // [300,303), so the unencrypted bytes come back verbatim.
+    #[test]
+    fn host_key_passes_through_sectors_outside_content() {
+        let rdk = [0x5Au8; 16];
+        let clear = clear_content(1); // clear filesystem sector on the wire
+        let src = FixedSource {
+            bytes: clear.clone(),
+        };
+        let ranges: Arc<[(u32, u32)]> = Arc::from(vec![(300u32, 3u32)].into_boxed_slice());
+        let mut s = BusRemovalSectorSource::new(src, BusStage::AacsHostKey(rdk))
+            .with_content_ranges(ranges);
+        let mut got = vec![0u8; SECTOR_BYTES];
+        // LBA 0 is outside content → no de-bus → bytes unchanged.
+        let n = s.read_sectors(0, 1, &mut got, false).unwrap();
+        assert_eq!(n, SECTOR_BYTES);
+        assert_eq!(
+            got, clear,
+            "a sector outside content must pass through untouched"
+        );
+    }
+
+    // The complement: a bus-encrypted sector INSIDE the content map is de-bussed.
+    #[test]
+    fn host_key_debusses_sectors_inside_content() {
+        let rdk = [0x33u8; 16];
+        let clear = clear_content(1);
+        let mut wire = clear.clone();
+        encrypt_bus(&mut wire, &rdk);
+        let src = FixedSource { bytes: wire };
+        let ranges: Arc<[(u32, u32)]> = Arc::from(vec![(300u32, 3u32)].into_boxed_slice());
+        let mut s = BusRemovalSectorSource::new(src, BusStage::AacsHostKey(rdk))
+            .with_content_ranges(ranges);
+        let mut got = vec![0u8; SECTOR_BYTES];
+        // LBA 300 is inside content → de-bus → plaintext recovered.
+        let n = s.read_sectors(300, 1, &mut got, false).unwrap();
+        assert_eq!(n, SECTOR_BYTES);
+        assert_eq!(
+            got, clear,
+            "a content sector must be de-bussed to plaintext"
+        );
+    }
+
+    // Per-sector gating WITHIN one multi-sector read at the decorator level:
+    // content [301,302) covers only the middle sector of a 3-sector read at 300.
+    // MUTATION: gating the whole buffer on the first sector's LBA goes red here.
+    #[test]
+    fn host_key_gates_per_sector_within_a_multi_sector_read() {
+        let rdk = [0x44u8; 16];
+        let clear = clear_content(3);
+        let mut wire = clear.clone();
+        // Encrypt ONLY the middle sector's body; 0 and 2 stay clear on the wire.
+        let mut mid = clear[SECTOR_BYTES..2 * SECTOR_BYTES].to_vec();
+        encrypt_bus(&mut mid, &rdk);
+        wire[SECTOR_BYTES..2 * SECTOR_BYTES].copy_from_slice(&mid);
+
+        let src = FixedSource { bytes: wire };
+        let ranges: Arc<[(u32, u32)]> = Arc::from(vec![(301u32, 1u32)].into_boxed_slice());
+        let mut s = BusRemovalSectorSource::new(src, BusStage::AacsHostKey(rdk))
+            .with_content_ranges(ranges);
+        let mut got = vec![0u8; 3 * SECTOR_BYTES];
+        s.read_sectors(300, 3, &mut got, false).unwrap();
+        assert_eq!(
+            got, clear,
+            "only the in-range middle sector is de-bussed; clear neighbours untouched"
+        );
+    }
+
+    // Only the reported `n` bytes are de-bussed; a short read must not touch
+    // bytes beyond `n`. Also proves capacity delegates.
+    #[test]
+    fn debus_bounded_by_reported_n_and_capacity_delegates() {
+        let rdk = [0x77u8; 16];
+        // Two IDENTICAL bus-encrypted sectors on the wire, but the source reports
+        // only the FIRST was read. Sector 0 must be de-bussed to plaintext; sector
+        // 1 (beyond the reported n) must be left as ciphertext, untouched.
+        let clear = clear_content(1);
+        let mut enc = clear.clone();
+        encrypt_bus(&mut enc, &rdk);
+        let mut bytes = enc.clone();
+        bytes.extend_from_slice(&enc); // two encrypted sectors
+
+        struct ShortSource {
+            bytes: Vec<u8>,
+            report: usize,
+        }
+        impl SectorSource for ShortSource {
+            fn capacity_sectors(&self) -> u32 {
+                42
+            }
+            fn read_sectors(
+                &mut self,
+                _lba: u32,
+                _count: u16,
+                buf: &mut [u8],
+                _recovery: bool,
+            ) -> Result<usize> {
+                buf[..self.bytes.len()].copy_from_slice(&self.bytes);
+                Ok(self.report)
+            }
+        }
+        let src = ShortSource {
+            bytes,
+            report: SECTOR_BYTES, // only sector 0 "read"
+        };
+        let mut s = BusRemovalSectorSource::new(src, BusStage::AacsHostKey(rdk));
+        assert_eq!(s.capacity_sectors(), 42, "capacity must delegate to inner");
+        let mut got = vec![0u8; 2 * SECTOR_BYTES];
+        let n = s.read_sectors(0, 2, &mut got, false).unwrap();
+        assert_eq!(n, SECTOR_BYTES);
+        // Sector 0 was de-bussed to plaintext...
+        assert_eq!(
+            &got[..SECTOR_BYTES],
+            &clear[..],
+            "reported sector de-bussed"
+        );
+        // ...and sector 1 (beyond n) was NOT touched — still ciphertext.
+        assert_eq!(
+            &got[SECTOR_BYTES..],
+            &enc[..],
+            "bytes beyond the reported n must stay ciphertext"
+        );
+    }
+}
@@ -566,7 +566,6 @@ mod tests {
            src,
            DecryptKeys::Aacs {
                unit_keys: Vec::new(),
-                read_data_key: None,
                format: crate::disc::ContentFormat::BdTs,
            },
        );
@@ -757,7 +756,6 @@ mod tests {
        let src = FixedUnit { unit };
        let keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, key)],
-            read_data_key: None,
            format: crate::disc::ContentFormat::BdTs,
        };
        let map = std::sync::Arc::new(crate::decrypt::AacsKeyMap::from_ranges(vec![(
@@ -789,7 +787,6 @@ mod tests {
        let src = FixedUnit { unit };
        let keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, key)],
-            read_data_key: None,
            format: crate::disc::ContentFormat::BdTs,
        };
        let mut dec = DecryptingSectorSource::new(src, keys); // no with_key_map
@@ -811,7 +808,6 @@ mod tests {
        let src = FixedUnit { unit };
        let keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, key)],
-            read_data_key: None,
            format: crate::disc::ContentFormat::BdTs,
        };
        let map = std::sync::Arc::new(crate::decrypt::AacsKeyMap::from_ranges(vec![(
@@ -841,7 +837,6 @@ mod tests {
        let src = PatternedSource { capacity: 16 };
        let keys = DecryptKeys::Aacs {
            unit_keys: vec![(0, [0u8; 16])],
-            read_data_key: None,
            format: crate::disc::ContentFormat::BdTs,
        };
        let map = std::sync::Arc::new(crate::decrypt::AacsKeyMap::from_ranges(vec![(300, 303, 0)]));
@@ -8,6 +8,7 @@
 //!   `SectorSource` and applies AACS / CSS in-place decrypt to
 //!   yield plaintext sectors.

+pub mod bus_removal;
 pub mod decrypting;
 pub mod prefetched;

@@ -692,7 +692,6 @@ mod tests {
                key_source: crate::disc::KeyOrigin::KeyDb,
                vuk: None,
                unit_keys: Vec::new(),
-                read_data_key: None,
                volume_id: [0u8; 16],
                uk_ro: Vec::new(),
                mkb: Vec::new(),
@@ -4470,6 +4470,124 @@ mod tests {
        );
    }

+    // read_directory follows a type-3 CONTINUATION pointer (ECMA-167 4/14.14.1.1):
+    // extent 0 (sector 60) has the first FID; a type-3 AD → block 50 → tail AD →
+    // extent 1 (sector 61) with the second FID. MUTATION: not following loses it.
+    #[test]
+    fn read_directory_follows_type3_continuation() {
+        let mut e0 = Vec::new();
+        push_fid_iu(&mut e0, "", 5, true, true, 0); // parent (..)
+        push_fid_iu(&mut e0, "FIRST.CLPI", 7, false, false, 1959);
+        assert_eq!(e0.len(), 2048, "extent 0 must fill its sector exactly");
+        let mut sec0 = [0u8; 2048];
+        sec0.copy_from_slice(&e0);
+
+        let mut e1 = Vec::new();
+        push_fid_iu(&mut e1, "SECOND.CLPI", 8, false, false, 0);
+        let mut sec1 = [0u8; 2048];
+        sec1[..e1.len()].copy_from_slice(&e1);
+
+        // ICB ADs: (recorded, 2048, lba=60) then a type-3 continuation (→ lba 50).
+        let mut body = Vec::new();
+        body.extend_from_slice(&2048u32.to_le_bytes());
+        body.extend_from_slice(&60u32.to_le_bytes());
+        body.extend_from_slice(&((3u32 << 30) | 2048).to_le_bytes());
+        body.extend_from_slice(&50u32.to_le_bytes());
+
+        let mut reader = MemReader::new();
+        reader.put(5, build_dir_icb_flagged(0, &body));
+        reader.put(60, sec0);
+        reader.put(50, build_cont_block(&[(0, e1.len() as u32, 61)]));
+        reader.put(61, sec1);
+        reader.put(7, build_efe_icb(11, 2048, 0));
+        reader.put(8, build_efe_icb(22, 2048, 0));
+
+        let parsed = read_directory(&mut reader, 0, 0, 5, "ROOT", 0, &mut 0, &mut HashSet::new())
+            .expect("a directory with a continuation AD must be readable");
+        assert_eq!(
+            child_names(&parsed),
+            vec!["FIRST.CLPI".to_string(), "SECOND.CLPI".to_string()],
+            "the FID in the continuation block must be read, not dropped"
+        );
+        assert_eq!(parsed.size, 2048 + e1.len() as u64);
+    }
+
+    // A continuation block opens with a 24-byte AED (tag 258); read_directory reads
+    // the tail ADs from offset 24, not 0. MUTATION: reading from 0 mis-parses the
+    // AED tag as a bogus AD and loses the continuation extent (Blu-ray 3D bug).
+    #[test]
+    fn read_directory_continuation_skips_aed_header() {
+        let mut e0 = Vec::new();
+        push_fid_iu(&mut e0, "", 5, true, true, 0);
+        push_fid_iu(&mut e0, "FIRST.CLPI", 7, false, false, 1959);
+        let mut sec0 = [0u8; 2048];
+        sec0.copy_from_slice(&e0);
+
+        let mut e1 = Vec::new();
+        push_fid_iu(&mut e1, "SECOND.CLPI", 8, false, false, 0);
+        let mut sec1 = [0u8; 2048];
+        sec1[..e1.len()].copy_from_slice(&e1);
+
+        let mut body = Vec::new();
+        body.extend_from_slice(&2048u32.to_le_bytes());
+        body.extend_from_slice(&60u32.to_le_bytes());
+        body.extend_from_slice(&((3u32 << 30) | 2048).to_le_bytes());
+        body.extend_from_slice(&50u32.to_le_bytes());
+
+        let mut cont = build_cont_block(&[(0, e1.len() as u32, 61)]);
+        // Stamp a realistic AED tag (258) so a from-offset-0 regression mis-parses it.
+        cont[0..2].copy_from_slice(&258u16.to_le_bytes());
+
+        let mut reader = MemReader::new();
+        reader.put(5, build_dir_icb_flagged(0, &body));
+        reader.put(60, sec0);
+        reader.put(50, cont);
+        reader.put(61, sec1);
+        reader.put(7, build_efe_icb(11, 2048, 0));
+        reader.put(8, build_efe_icb(22, 2048, 0));
+
+        let parsed = read_directory(&mut reader, 0, 0, 5, "ROOT", 0, &mut 0, &mut HashSet::new())
+            .expect("continuation with an AED header must be readable");
+        assert_eq!(
+            child_names(&parsed),
+            vec!["FIRST.CLPI".to_string(), "SECOND.CLPI".to_string()],
+            "continuation ADs must be read past the 24-byte AED header, not from offset 0"
+        );
+    }
+
+    // Hostile input: a continuation pointer that cycles to its own block. The
+    // MAX_AD_BLOCKS budget must bound the walk so it TERMINATES (returns the FIDs
+    // gathered before the cycle) instead of looping forever or panicking.
+    #[test]
+    fn read_directory_self_cycling_continuation_terminates() {
+        let mut e0 = Vec::new();
+        push_fid_iu(&mut e0, "", 5, true, true, 0);
+        push_fid_iu(&mut e0, "FIRST.CLPI", 7, false, false, 1959);
+        let mut sec0 = [0u8; 2048];
+        sec0.copy_from_slice(&e0);
+
+        let mut body = Vec::new();
+        body.extend_from_slice(&2048u32.to_le_bytes());
+        body.extend_from_slice(&60u32.to_le_bytes());
+        body.extend_from_slice(&((3u32 << 30) | 2048).to_le_bytes());
+        body.extend_from_slice(&50u32.to_le_bytes());
+
+        let mut reader = MemReader::new();
+        reader.put(5, build_dir_icb_flagged(0, &body));
+        reader.put(60, sec0);
+        // Continuation block 50 points at ITSELF (type-3 → lba 50).
+        reader.put(50, build_cont_block(&[(3, 2048, 50)]));
+        reader.put(7, build_efe_icb(11, 2048, 0));
+
+        let parsed = read_directory(&mut reader, 0, 0, 5, "ROOT", 0, &mut 0, &mut HashSet::new())
+            .expect("a self-cycling continuation must terminate, not hang or error");
+        assert_eq!(
+            child_names(&parsed),
+            vec!["FIRST.CLPI".to_string()],
+            "FIDs before the cycle are returned; the MAX_AD_BLOCKS budget bounds the walk"
+        );
+    }
+
    #[test]
    fn read_directory_reads_an_extended_ad_directorys_extent_location() {
        // ECMA-167 4/14.14.3 extended_ad (20B) keeps extent_location at offset 12, NOT offset 4
@@ -88,7 +88,6 @@ fn decrypt_keys_is_encrypted_variants() {

    let aacs = DecryptKeys::Aacs {
        unit_keys: vec![],
-        read_data_key: None,
        format: libfreemkv::disc::ContentFormat::BdTs,
    };
    assert!(aacs.is_encrypted());
Author	SHA1	Message	Date
Matthew Jackson	49992a5c2d	v1.7.5: bump version (freemkv-unlock git-pinned for the tag)	2026-09-23 04:40:51 +00:00
Matthew Jackson	c1caac3a7e	docs: 1.7.5 changelog entry for the unified release [skip-media] Version aligned to 1.7.5. No functional change to this crate — the release is driven by freemkv-unlock mirroring the freemkv-firmware 0.9.0 ABI, where the drive's separate Ake (0x06) and Bus (0x07) levers are retired into a single Encryption (0x06) lever.	2026-09-22 21:04:54 -07:00
Matthew Jackson	b69002694f	ci: add OpenSSF Scorecard workflow (publish_results on default branch)	2026-09-21 16:39:26 -07:00
Matthew Jackson	11c869f8e9	restore freemkv-unlock path dep for local dev (post-v1.7.4)	2026-09-21 23:03:36 +00:00
Matthew Jackson	8ce40edba3	v1.7.4: bump version (freemkv-unlock git-pinned for the tag)	2026-09-21 23:03:33 +00:00
Matthew Jackson	bccc8eb9a7	docs: mark 1.7.4 changelog heading UNRELEASED (release workflow dates it)	2026-09-21 15:07:08 -07:00
Matthew Jackson	0edbdfbb21	docs: 1.7.4 changelog + consumer release notes	2026-09-21 11:47:20 -07:00
Matthew Jackson	2499f1600d	docs: OpenSSF Best Practices badge (project 14745, 198%) + REUSE.toml/badge — parity with freemkv	2026-09-21 09:22:49 -07:00
Matthew Jackson	bb3b1920a9	docs: add OpenSSF Scorecard + REUSE + MSRV badges and a 'what this is not' honesty section	2026-09-21 09:11:52 -07:00
Matthew Jackson	551173fa46	docs/ci: drop stale local-precommit/release.sh references — CI is the only gate	2026-09-21 09:11:34 -07:00
Matthew Jackson	26a9cb9e62	ci(qa): use central checkout-siblings composite + concurrency Convert qa.yml to the central pattern already applied to ci.yml (`86d66d3`): - add top-level concurrency (cancel-in-progress) group - replace per-job freemkv-unlock checkout (ref qa) with the freemkv/.github checkout-siblings@v1 composite (checkout: freemkv-unlock) in release-tests, cross-lint and windows-build - standardize actions/checkout to @v5 No heredoc patching existed in any job, so no patch inputs. The composite resolves siblings 3-way, so qa runs now pin siblings at qa automatically.	2026-09-21 08:46:53 -07:00
Matthew Jackson	86d66d3113	ci: use central checkout-siblings composite + concurrency; fixes main->main sibling ref (was main->dev) Replaces the 8x-repeated sibling-checkout block with freemkv/.github checkout-siblings@v1. Adds concurrency cancel-in-progress. All jobs (incl. consumers running dependent suites) preserved.	2026-09-21 08:37:48 -07:00
Matthew Jackson	6d20c854c0	comment: trim two 5-line inline blocks to 3 (surfaced by the more-accurate central comment-guard lexer)	2026-09-21 08:35:27 -07:00
Matthew Jackson	24f29d83f0	ci: guards → central reusable workflows (comment/leak/identity/doc-links) Thin callers to freemkv/.github@v1; delete the now-duplicated local ci/ scripts. Adds concurrency cancel-in-progress and drops the push+PR double-fire (fork PRs still run). doc-links now resolves toolchain from rust-version (was hardcoded 1.98).	2026-09-21 08:33:46 -07:00
Matthew Jackson	471a441799	doc: backtick the NAL [len][body] notation so rustdoc doesn't parse it as an intra-doc link (fixes doc-links CI)	2026-09-21 08:05:21 -07:00
Matthew Jackson	aeb6bf5cc1	disc: scope the #45 lowest-id tiebreak behind stream-richness (recover Dolby Vision / subtitle on BlacKkKlansman + WickedForGood)	2026-09-20 21:50:21 -07:00
Matthew Jackson	0062d79d2c	bdnav/bdjo: cite the BDJO format, not libbluray's GPL source (scan-secrets REF-IMPL-CITATION)	2026-09-20 20:45:55 -07:00
Matthew Jackson	b0e297bd41	Merge codeaudit-1.7.4: chapter-span + hevc-guard + winner-hint tests, doc-drift, hoist MIN_FEATURE_SECS	2026-09-20 20:45:24 -07:00
Matthew Jackson	0cd967a5ac	fix: close code-audit test gaps + doc drift (1.7.4 delta, #45/#52/#46) Test gaps (guarded code was untested): - disc: cover is_complete_feature_presentation's CHAPTER_SPAN_MIN_FRAC (0.5) boundary — clustered marks (span < 0.5*dur) are not a feature; marks at the 0.5 threshold are. Adds bd_title_chaptered_span helper (issue #45). - hevc: exercise the length-prefix self-check WIRING in HevcParser::parse end-to-end — a desynced access unit is dropped, a well-formed one emitted. Adds a test-only FORCE_FRAMING_DESYNC seam (frame_data is length-prefixed by construction, so no real input desyncs it) (issue #52). - labels: cover resolve_feature_hint's winner_hint early-return — a non-empty winner_hint wins over the Tier-2 bdj_feature menu-walk result (issue #46). Doc drift: - keysource.md: resolve_unit_keys + UnitKeyResolution (matched/miss_path/ matched_entry/store_entries de-conflation). - aacs-trace.md: MatchedEntry, KeyStep.matched_entry/store_entries, and the KeyNode::NoDerivableKey node. - hevc.md: add the "length-prefix self-check (issue #52)" section the hevc.rs comment points to. Craft: - labels: hoist the duplicated MIN_FEATURE_SECS (60) from fox.rs and paramount.rs to a single shared const in labels/mod.rs.	2026-09-20 20:44:28 -07:00
Matthew Jackson	d7b6aca6e8	fix(#45 ): add bdj_feature.rs (unstaged in `0109db9` menu-walk commit)	2026-09-20 20:09:35 -07:00
Matthew Jackson	3a41e0eec7	Merge #45 menu-walk: BD-J feature resolution (BDJO AMT + jar/manifest + Tier-2 locator) above the chapter failsafe	2026-09-20 20:08:39 -07:00
Matthew Jackson	0109db984f	fix(#45 ): BD-J menu-walk — authoritative feature-resolution layer Adds a generic BD-J feature-playlist resolver that runs when no framework parser surfaced a manifest hint, plus a refinement to Sony/Fox feature selection. The hint now rides an independent pass so it survives even when the winning parser (or no parser) produced any labels. - labels/mod.rs: resolve_feature_hint() independent hint pass wired into apply(); register mod bdj_feature. - labels/paramount.rs (+ fox.rs mirror): refine feature selection — exact name="Feature" → /feature/i by longest duration → most-audio by duration; hard-reject sub-minute playlists (kills the _Start_Angle 2s decoy). Fixes Sony SM3 UHD. feature_hint_from_xml() exposed for Tier-1. - labels/bdj_feature.rs (NEW): Tier-1 jar-space resource sweep (dcx.xml/playlists.xml/.properties) reusing fox/paramount hints; Tier-2 autostart-Xlet locator scan (BDJO AMT → autostart jar → NNNNN.mpls / PLAYLIST:N String constants → intersect real PLAYLIST set → longest-dominant multi-audio wins; integer-only never emits). - bdnav/bdjo.rs (NEW): minimal bounds-checked /BDMV/BDJO/.bdjo Application Management Table reader (autostart initial_class + jar ids), panic-free like bdnav/index.rs. - labels/jar.rs: try_each_resource() helper for the Tier-1 sweep. No changes to disc/mod.rs selection or bdnav/vm.rs.	2026-09-20 20:07:45 -07:00
Matthew Jackson	841328af0f	Merge #45 failsafe: chapter-gated composite bumper limb + lowest-id tiebreak	2026-09-20 19:36:33 -07:00
Matthew Jackson	a35f336c52	Merge #52 : PGS BlockDuration + HEVC NAL guard	2026-09-20 19:36:33 -07:00
Matthew Jackson	00f590f634	mux: guarantee a BlockDuration on every subtitle block (#52 ) Fix (B) — the reproducible bug behind ffmpeg "Timestamps are unset in a packet for stream N" on PGS subtitle tracks (worst on the sparse forced track). Subtitle tracks carry no DefaultDuration, so a frame emitted with duration_ns: None became a bare SimpleBlock with nothing to bound the cue. - codec/pgs.rs: synthesize a fallback dwell (DEFAULT_PGS_DURATION_NS, 5 s) for every emission that was duration_ns: None — the EOS trailing set and the no-PTS clear/display, truncated, and lone-pass-through arms. emit_pending keeps its real computed span but clamps a pathologically large one (missing intermediate PCS) past MAX_PGS_DURATION_NS back to the fallback. - mkv.rs: track_is_subtitle (track_type == 17), mirroring track_is_video. In write_frame_at a subtitle frame with no duration now substitutes a minimum fallback (MIN_SUBTITLE_BLOCK_DURATION_NS, 1 s) so it is emitted as a BlockGroup WITH BlockDuration, never a bare SimpleBlock (defense in depth). Fix (A) — defensive HEVC guard (the "Invalid NAL unit size" error is not reproducible in our clean disc->MKV path; this makes our output structurally incapable of originating it): - codec/hevc.rs: length_prefix_tiles() self-consistency check — the [u32-BE len][body] records must EXACTLY tile the frame; on mismatch the desynced access unit is dropped (logging src position) rather than emitted. - LENGTH_PREFIX_SIZE constant + regression test that hvcC byte-21 lengthSizeMinusOne+1 equals the prefix width push_length_prefixed writes. Tests: pgs.rs None-arm duration assertions updated to the fallback + a clamp/no-clamp pair; mkv.rs subtitle-BlockGroup and two-track (dense+sparse) "every block has a BlockDuration" cases; hevc.rs tiling accept/reject, byte-21 regression, and a positive parsed-AU-tiles-exactly test.	2026-09-20 19:33:25 -07:00
Matthew Jackson	827eaf0452	disc: gate composite bumper limb on a complete chapter table (#45 ) A BD-J disc (Alita) has no authoritative static playlist chain, so main- feature selection is a structural failsafe. Its chaptered feature 00800 is a SUPERSET of an un-chaptered body subset 00703 that is 0.97 of its size, so the size-only seamless bumper limb fired and demoted the real feature, ripping the body instead. Gate ONLY the bumper limb on is_complete_feature_presentation(q): the wrapped/subset title must carry a real chapter table (>= MIN_FEATURE_CHAPTERS marks spanning >= CHAPTER_SPAN_MIN_FRAC of its runtime). The concat limb (much-shorter cut) is untouched. This is the ABSOLUTE-threshold predicate; a one-line swap to the RELATIVE form (p.chapters.len() <= q.chapters.len()) is documented at the call site and in the predicate doc, pending a hoard sweep of SM3's real chapter counts. Also add lowest playlist_id as the final canonical_title_order tie-break so equal-size seamless siblings (00800-00808) pick 00800 deterministically. Fixtures re-based on the real chapter discriminator (not a size coincidence) and new tests cover both topologies (Alita superset-feature, SM3 subset- feature) plus the un-chaptered-subset keep-superset case.	2026-09-20 19:32:39 -07:00
Matthew Jackson	f4ea6ea129	aacs/keysource: de-conflate "no entry" vs matched-but-underivable (#46 ) The keydb lookup returned an empty Vec for two very different outcomes: a true hash miss, and a MATCHED disc that derived no key (e.g. an MK-only entry with no VID). Both rendered as `keydb > no entry`, misleading reporters whose disc IS present in the keydb. Add KeySource::resolve_unit_keys -> UnitKeyResolution { keys, matched, miss_path, matched_entry, store_entries }; the trait default delegates to get_unit_keys (matched=false) so every existing source is unchanged. resolve_and_apply_traced now renders MatchedDisc + NoVid/NoDerivableKey for a matched-but-no-key disc and reserves NoEntry for a genuine miss. New KeyNode::NoDerivableKey, a MatchedEntry shape (booleans + lengths, no key material), and KeyStep.{matched_entry, store_entries} carry the diagnostics to the app-layer renderer. Tests cover both verdict paths.	2026-09-20 19:16:06 -07:00
Matthew Jackson	b47bccce7b	libfreemkv 1.7.4: codeaudit fixes (v1.7.0..HEAD sweep) Bus content-range de-bus: - F1 disc/mod.rs: always install content ranges (extracted wire_bus_removal); empty ranges => Some([]) => de-bus NOTHING (fail-safe), not None => de-bus everything — closes silent clear-sector corruption on the AACS cert route. - F4 aacs/content.rs, F5 decrypt.rs: content gate is now a partition_point binary search (O(log n)/sector) over the sorted, merged-disjoint ranges, replacing the per-sector O(ranges) linear scan on the de-bus hot path. - F2 scsi/linux.rs: RECOVERY_THREADS cap uses atomic reserve-then-check (fetch_add first, fall back on overshoot) — removes the TOCTOU that let concurrent multi-drive rips exceed MAX_RECOVERY_THREADS. - F3 pes.rs: PesFrame::deserialize reads each chunk straight into data's tail; drops the scratch Vec + double-copy, keeps the incremental-growth DoS guard. - F7 disc/mod.rs: six inline rank_titles thresholds -> named consts. Tests: bus fail-safe + scan wiring (both routes), per-sector gate straddle, read_directory type-3 continuation/AED-skip/cycle-guard, strengthened without_bus_removal no-op guard. F6 (pub decrypt_bus) left by-design.	2026-09-19 16:19:48 -07:00
Matthew Jackson	13b93f803b	libfreemkv: fix broken intra-doc links to BusStage::Passthrough in drive/mod.rs (doc-links gate)	2026-09-19 14:25:13 -07:00
Matthew Jackson	1894fa1a49	libfreemkv 1.7.4: single drive-owned AACS bus-removal point Relocate AACS bus decryption to one spot at the bottom of the sector chain: the Drive's SectorSource impl applies decrypt_bus_in_content (gated to encrypted-content ranges), with the stage decided once from the unlock/ handshake result (BusStage::from_read_data_key). Remove read_data_key from DecryptKeys::Aacs and AacsState and the two downstream decrypt_bus call sites; every reader (key sampler, mux, unit-key validation) now sees already-de-bussed content and never reasons about bus encryption. Add BusRemovalSectorSource stream + tests; keep the AacsBusKeyUnavailable fail-loud gate.	2026-09-19 13:59:52 -07:00
Matthew Jackson	5696175520	restore freemkv-unlock path dep for local dev (post-v1.7.3)	2026-09-19 05:31:13 +00:00
Matthew Jackson	e99cb95bd4	v1.7.3: bump version (freemkv-unlock git-pinned for the tag)	2026-09-19 05:31:10 +00:00
Matthew Jackson	1794f5c406	merge: record v1.7.2 release into dev (-s ours; keep path deps + dev's next-cycle work)	2026-09-18 21:39:15 -07:00
Matthew Jackson	9379507c15	docs: backtick item[10]/item[0..5] in mpls module doc so rustdoc doesn't read them as intra-doc links (doc-links CI)	2026-09-18 21:30:25 -07:00
Matthew Jackson	8457efb5da	changelog: 1.7.3 — multi-angle MPLS STN fix (#45 ) + read_structure_files for --share	2026-09-18 21:11:59 -07:00
Matthew Jackson	dbc135bee0	disc: add read_structure_files() to capture BDMV/DVD index metadata for --share diagnostics	2026-09-18 21:08:28 -07:00
Matthew Jackson	48fb9b2cf6	mpls: locate STN table past the multi-angle angle block (issue #45 ) The PlayItem STN (stream-number) table offset was hard-coded to 32, which is only correct for a single-angle PlayItem. A multi-angle PlayItem inserts number_of_angles(1) + flags(1) + (number_of_angles-1) angle references (10 bytes each) right after still_time, so its STN begins at 32 + 2 + (number_of_angles-1)*10. The fixed offset lands inside that angle block and misreads the stream counts as garbage (e.g. n_video=51 on Spider-Man 3 UHD 00245/00246.mpls, number_of_angles=2 => real offset 44), dropping every stream including the primary video. That makes DiscTitle::has_video() return false, which drops a multi-angle/seamless-branch feature from the disc's nav candidate set and loses it in main-title selection. Compute the STN offset from is_multi_angle (bit 4 of item[10]) + number_of _angles. Add a regression test building a 2-angle PlayItem and asserting the video stream is found past the angle block. Validated on a 92-disc real UHD/BD corpus (offline scan): 0 main-feature pick changes vs baseline, 3 multi-angle titles (Spider-Man 3 244/245/246) recover has_video. Adds examples/corpus_titledump.rs as the regression tool.	2026-09-18 16:38:45 -07:00
Matthew Jackson	013f27eede	fix(disc): SAFETY — spare seamless-branch feature from wrapper-composite demotion (#45 ) The fallback composite gate in rank_titles flagged title P as a "play-all wrapper" whenever some other title Q's clip set was a proper subset of P's, Q had video, and Q.size >= 0.5 * P.size. main_feature_order then ranks standalone-before-composite, demoting P below the decoy Q. On a seamless-branch feature this inverts the pick: the real 00800 (2h03, 4 clips = body + intro/credits/seamless segments) is a SUPERSET of the single-clip body decoy 00700 (1h50), and 700 >= 50% of 800's size, so 800 was mis-flagged composite and lost to the shorter 700 — the wrong title gets ripped. Add a duration-first wrapper-shape gate: P is only a composite when the subset Q is EITHER a much shorter cut (Q.duration < 0.85 * P.duration, a concat/play-all padding Q's runtime) OR nearly size-equal (Q.size >= 0.90 * P.size, a bumper/outro wrapper). A near-full-length but markedly smaller body subset (Q runs ~0.89 of P's duration yet holds far fewer bytes, because P's branch segments add bytes not runtime) is a real seamless branch, so P is kept. Uses per-title duration_secs/size_bytes, stays capacity-independent and feature-gate-safe. Preserves the real play-all avoidance: the 00245 bumper-wrapper decoy (Q ~0.96 of both duration and size) stays demoted via the size limb, and a concat play-all (subset < half the runtime) via the duration limb. Add regression tests: seamless_branch_feature_not_demoted_issue_45 and true_play_all_concat_wrapper_still_demoted. All existing selection tests pass.	2026-09-18 13:34:50 -07:00
Matthew Jackson	9f0e10a524	restore freemkv-unlock path dep for local dev (post-v1.7.2)	2026-09-18 18:37:24 +00:00