test(online): trim interpret_reply reachability aside to 3 lines for comment-guard

ci: adopt central freemkv/.github guards + checkout-siblings composite
Thin-caller comment/leak/identity guards → freemkv/.github reusable workflows; drop local ci/comment-guard.py and ci/leak-guard.sh. Replace per-job sibling checkout + .cargo/config heredoc with the shared checkout-siblings@v1 composite (checkout libfreemkv+freemkv-unlock, patch libfreemkv). Add cancel-in-progress concurrency to ci.yml/qa.yml; standardize actions/checkout to @v5.
2026-10-07 18:13:11 +00:00 · 2026-09-21 08:51:04 -07:00 · 2026-09-21 08:48:58 -07:00 · 2026-09-20 20:15:19 -07:00 · 2026-09-20 20:03:54 -07:00 · 2026-09-20 19:16:06 -07:00
32 changed files with 6209 additions and 1083 deletions
@@ -46,3 +46,18 @@ updates:
        update-types:
          - minor
          - patch
+    ignore:
+      # NOT a dependency: `dtolnay/rust-toolchain` is versioned by the RUST
+      # release it installs, and the tag we pin is the toolchain CI is pinned
+      # to on purpose -- precommit.sh runs the same one locally so a lint that
+      # passes on a developer's newer default cannot pass CI by accident.
+      #
+      # Dependabot reads those tags as semver and proposed 1.97.0 -> 1.100.0,
+      # a Rust version that does not exist. Every such PR 404s on toolchain
+      # download across all eight repos, and they regenerate weekly -- eight
+      # permanently-red PRs that promote.yml then has to special-case when it
+      # decides whether dev is green.
+      #
+      # Bumping the toolchain is a deliberate, all-eight-repos change, made by
+      # hand together with precommit.sh. There is nothing here for a bot.
+      - dependency-name: dtolnay/rust-toolchain
@@ -10,6 +10,11 @@ on:
    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
+
 # WHY THE SIBLING CHECKOUTS — this is NOT a monorepo.
 #
 # The committed Cargo.toml resolves libfreemkv from a git TAG (it is off
@@ -18,8 +23,9 @@ on:
 # across the two repos could not be verified until release.sh cut the tags.
 # Green here meant "compiles against last month's library".
 #
-# The fix mirrors the developer's local layout. Every repo is checked out into
-# a subdirectory of $GITHUB_WORKSPACE, reproducing
+# The fix mirrors the developer's local layout via the shared composite
+# freemkv/.github//actions/checkout-siblings: every sibling repo is checked out
+# into a subdirectory of $GITHUB_WORKSPACE, reproducing
 # ~/Developer/freemkv/{freemkv-keysources,libfreemkv,freemkv-unlock}, and a
 # generated .cargo/config.toml redirects the git-tag patch to those paths.
 # Config-level [patch.crates-io] wins over the manifest one, which is the same
@@ -32,81 +38,125 @@ on:
 # libfreemkv path-deps ../freemkv-unlock, which resolves to the workspace root
 # under this layout — hence the third checkout.
 #
-# `--locked` is deliberately absent: Cargo.lock is gitignored here (library
-# convention), so there is nothing to lock against and it fails rather than
-# resolves. That is what was breaking this workflow. The lock that has to hold
-# is the one release.sh regenerates in each consuming binary.
+# `--locked` is deliberately absent: Cargo.lock is now committed (issue #15) and
+# the `deny` job audits the resolved graph, but 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. The lock that has to hold is the one
+# release.sh regenerates in each consuming binary.

 jobs:
-  lint:
+  # Single source of truth for the MSRV — read rust-version from Cargo.toml once
+  # and export it; MSRV-bound jobs consume needs.resolve-msrv.outputs.v. clippy
+  # runs on stable instead (see CI.md's Toolchain policy).
+  resolve-msrv:
+    runs-on: ubuntu-latest
+    outputs:
+      v: ${{ steps.msrv.outputs.v }}
+    steps:
+      - 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.
+  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: |
+          set -euo pipefail
+          version=$(grep -m1 '^version = ' Cargo.toml | sed -E 's/.*"([^"]+)".*/\1/')
+          if grep -qE "^## \[${version}\]" CHANGELOG.md; then
+            echo "CHANGELOG.md has an entry for ${version}."
+            exit 0
+          fi
+          msg="CHANGELOG.md has no '## [${version}]' entry"
+          if [ "${GITHUB_REF_NAME:-}" = "main" ] || [ "${GITHUB_BASE_REF:-}" = "main" ]; then
+            echo "::error::${msg} — main requires a changelog entry for the released version."
+            exit 1
+          fi
+          echo "::warning::${msg} (allowed on ${GITHUB_REF_NAME:-unknown}; required before it can reach main)."
+
+  lint:
+    needs: resolve-msrv
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
        with:
          path: freemkv-keysources
-      - uses: actions/checkout@v7
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
        with:
-          repository: freemkv/libfreemkv
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: libfreemkv
-      - uses: actions/checkout@v7
+          checkout: libfreemkv freemkv-unlock
+          patch: libfreemkv
+          self: freemkv-keysources
+      # fmt runs on the MSRV pin; clippy runs on stable so new-lint debt is a
+      # blocking gate the pinned toolchain would hide. Stable is installed first
+      # for clippy; the MSRV pin goes second so it stays fmt's default toolchain.
+      - uses: dtolnay/rust-toolchain@stable
        with:
-          repository: freemkv/freemkv-unlock
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: freemkv-unlock
-      - name: Resolve siblings from their dev tips
-        shell: bash
-        working-directory: freemkv-keysources
-        run: |
-          mkdir -p .cargo
-          cat > .cargo/config.toml <<'EOF'
-          [patch.crates-io]
-          libfreemkv = { path = "../libfreemkv" }
-          EOF
-      - uses: dtolnay/rust-toolchain@1.97.0
+          components: clippy
+      - uses: dtolnay/rust-toolchain@master
        with:
-          components: clippy, rustfmt
+          toolchain: ${{ needs.resolve-msrv.outputs.v }}
+          components: rustfmt
      - uses: Swatinem/rust-cache@v2
        with:
          workspaces: freemkv-keysources
      - run: cargo fmt --check
        working-directory: freemkv-keysources
      # --all-targets so the test code is linted too, not just the library.
-      - run: cargo clippy --all-targets -- -D warnings
+      - run: cargo +stable clippy --all-targets -- -D warnings
        working-directory: freemkv-keysources

  test:
+    needs: resolve-msrv
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
        with:
          path: freemkv-keysources
-      - uses: actions/checkout@v7
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
        with:
-          repository: freemkv/libfreemkv
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: libfreemkv
-      - uses: actions/checkout@v7
+          checkout: libfreemkv freemkv-unlock
+          patch: libfreemkv
+          self: freemkv-keysources
+      - uses: dtolnay/rust-toolchain@master
        with:
-          repository: freemkv/freemkv-unlock
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: freemkv-unlock
-      - name: Resolve siblings from their dev tips
-        shell: bash
-        working-directory: freemkv-keysources
-        run: |
-          mkdir -p .cargo
-          cat > .cargo/config.toml <<'EOF'
-          [patch.crates-io]
-          libfreemkv = { path = "../libfreemkv" }
-          EOF
-      - uses: dtolnay/rust-toolchain@1.97.0
+          toolchain: ${{ needs.resolve-msrv.outputs.v }}
      - uses: Swatinem/rust-cache@v2
        with:
          workspaces: freemkv-keysources
      - run: cargo test --tests
        working-directory: freemkv-keysources

+  # Dependency-audit gate. Mirrors the `test` job's sibling-checkout layout and
+  # generated .cargo/config.toml so `cargo metadata` resolves the git-tag patch
+  # to the local sibling paths; cargo-deny then audits advisories, bans,
+  # licenses, and sources against the committed deny.toml.
+  deny:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          path: freemkv-keysources
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
+        with:
+          checkout: libfreemkv freemkv-unlock
+          patch: libfreemkv
+          self: freemkv-keysources
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: EmbarkStudios/cargo-deny-action@v2
+        with:
+          command: check advisories bans licenses sources
+          manifest-path: freemkv-keysources/Cargo.toml
+
  # This crate ships wherever freemkv and autorip ship, and it drags in all of
  # libfreemkv's platform code (SCSI transports included). Build the tests, not
  # `cargo check` — check skips codegen and never compiles test-only code.
@@ -123,38 +173,62 @@ jobs:
    # 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: freemkv-keysources
-      - uses: actions/checkout@v7
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
        with:
-          repository: freemkv/libfreemkv
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: libfreemkv
-      - uses: actions/checkout@v7
+          checkout: libfreemkv freemkv-unlock
+          patch: libfreemkv
+          self: freemkv-keysources
+      - uses: dtolnay/rust-toolchain@master
        with:
-          repository: freemkv/freemkv-unlock
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: freemkv-unlock
-      - name: Resolve siblings from their dev tips
-        shell: bash
-        working-directory: freemkv-keysources
-        run: |
-          mkdir -p .cargo
-          cat > .cargo/config.toml <<'EOF'
-          [patch.crates-io]
-          libfreemkv = { path = "../libfreemkv" }
-          EOF
-      - uses: dtolnay/rust-toolchain@1.97.0
+          toolchain: ${{ needs.resolve-msrv.outputs.v }}
      - uses: Swatinem/rust-cache@v2
        with:
          workspaces: freemkv-keysources
      - run: cargo build --tests
        working-directory: freemkv-keysources

+  # Additive, NON-REQUIRED coverage. Mirrors the `test` job's sibling-checkout
+  # layout and pinned toolchain (nothing in the release cascade depends on it,
+  # and codecov upload is tokenless with fail_ci_if_error:false, so a flaky
+  # upload never reddens the run). `--locked` is deliberately absent here for
+  # the same reason it is in `test`: CI's sibling path-patch layout resolves the
+  # freemkv crates as path packages, which `--locked` can't satisfy.
+  coverage:
+    needs: resolve-msrv
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          path: freemkv-keysources
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
+        with:
+          checkout: libfreemkv freemkv-unlock
+          patch: libfreemkv
+          self: freemkv-keysources
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ needs.resolve-msrv.outputs.v }}
+          components: llvm-tools-preview
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: freemkv-keysources
+      - uses: taiki-e/install-action@cargo-llvm-cov
+      - run: cargo llvm-cov --workspace --ignore-run-fail --lcov --output-path lcov.info
+        working-directory: freemkv-keysources
+      - uses: codecov/codecov-action@v7
+        with:
+          files: freemkv-keysources/lcov.info
+          slug: freemkv/freemkv-keysources
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
+
  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
@@ -168,32 +242,21 @@ jobs:
    # 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: freemkv-keysources
-      - uses: actions/checkout@v7
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
        with:
-          repository: freemkv/libfreemkv
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: libfreemkv
-      - uses: actions/checkout@v7
+          checkout: libfreemkv freemkv-unlock
+          patch: libfreemkv
+          self: freemkv-keysources
+      - uses: dtolnay/rust-toolchain@master
        with:
-          repository: freemkv/freemkv-unlock
-          ref: "${{ github.ref_name == 'qa' && 'qa' || 'dev' }}"
-          path: freemkv-unlock
-      - name: Resolve siblings from their dev tips
-        shell: bash
-        working-directory: freemkv-keysources
-        run: |
-          mkdir -p .cargo
-          cat > .cargo/config.toml <<'EOF'
-          [patch.crates-io]
-          libfreemkv = { path = "../libfreemkv" }
-          EOF
-      - uses: dtolnay/rust-toolchain@1.97.0
+          toolchain: ${{ needs.resolve-msrv.outputs.v }}
      - uses: Swatinem/rust-cache@v2
        with:
          workspaces: freemkv-keysources
@@ -0,0 +1,12 @@
+name: comment-guard
+
+# 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:
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork
+    uses: freemkv/.github/.github/workflows/guard-comment.yml@v1
@@ -0,0 +1,14 @@
+name: identity-guard
+
+# 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:
+    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
@@ -13,6 +13,7 @@ name: qa
 # Sibling repos are checked out at `qa`, NOT `dev`. A qa run that resolved its
 # dependencies from dev tips would be validating a combination that is not the
 # one being released, which is the exact failure this branch exists to prevent.
+# The shared checkout-siblings composite resolves qa->qa from the caller branch.
 #
 # 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
@@ -23,7 +24,25 @@ on:
    branches: [qa]
  workflow_dispatch:

+# Supersede an in-progress qa run when a newer candidate lands on the branch.
+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;
+  # clippy (cross-lint) runs on stable instead.
+  resolve-msrv:
+    runs-on: ubuntu-latest
+    outputs:
+      v: ${{ steps.msrv.outputs.v }}
+    steps:
+      - uses: actions/checkout@v5
+      - id: msrv
+        shell: bash
+        run: echo "v=$(grep -m1 '^rust-version' Cargo.toml | sed -E 's/.*\"([^\"]+)\".*/\1/')" >> "$GITHUB_OUTPUT"
+
  # ── Name the candidate ────────────────────────────────────────────────
  #
  # Every push to `qa` is a release candidate, so every push gets a tag:
@@ -43,7 +62,7 @@ jobs:
    permissions:
      contents: write
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - name: Stamp the next rc
@@ -65,35 +84,24 @@ jobs:
  # changes what the optimiser can prove. A test that only passes in debug is
  # a test that never guarded the binary anyone actually ships.
  release-tests:
+    needs: resolve-msrv
    strategy:
      fail-fast: false
      matrix:
        os: ['ubuntu-latest', 'macos-latest']
    runs-on: ${{ matrix.os }}
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
        with:
          path: freemkv-keysources
-      - uses: actions/checkout@v7
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
        with:
-          repository: freemkv/libfreemkv
-          ref: qa
-          path: libfreemkv
-      - uses: actions/checkout@v7
+          checkout: libfreemkv freemkv-unlock
+          patch: libfreemkv
+          self: freemkv-keysources
+      - uses: dtolnay/rust-toolchain@master
        with:
-          repository: freemkv/freemkv-unlock
-          ref: qa
-          path: freemkv-unlock
-      - name: Resolve siblings from their qa tips
-        shell: bash
-        working-directory: freemkv-keysources
-        run: |
-          mkdir -p .cargo
-          cat > .cargo/config.toml <<'EOF'
-          [patch.crates-io]
-          libfreemkv = { path = "../libfreemkv" }
-          EOF
-      - uses: dtolnay/rust-toolchain@1.97.0
+          toolchain: ${{ needs.resolve-msrv.outputs.v }}
      - uses: Swatinem/rust-cache@v2
        with:
          workspaces: freemkv-keysources
@@ -106,29 +114,15 @@ jobs:
  cross-lint:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
        with:
          path: freemkv-keysources
-      - uses: actions/checkout@v7
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
        with:
-          repository: freemkv/libfreemkv
-          ref: qa
-          path: libfreemkv
-      - uses: actions/checkout@v7
-        with:
-          repository: freemkv/freemkv-unlock
-          ref: qa
-          path: freemkv-unlock
-      - name: Resolve siblings from their qa tips
-        shell: bash
-        working-directory: freemkv-keysources
-        run: |
-          mkdir -p .cargo
-          cat > .cargo/config.toml <<'EOF'
-          [patch.crates-io]
-          libfreemkv = { path = "../libfreemkv" }
-          EOF
-      - uses: dtolnay/rust-toolchain@1.97.0
+          checkout: libfreemkv freemkv-unlock
+          patch: libfreemkv
+          self: freemkv-keysources
+      - uses: dtolnay/rust-toolchain@stable
        with:
          components: clippy
      - uses: Swatinem/rust-cache@v2
@@ -143,31 +137,20 @@ jobs:
  # of the SCSI transport and platform layers compile on no other runner, so
  # without this they are first built at release time.
  windows-build:
+    needs: resolve-msrv
    runs-on: windows-latest
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
        with:
          path: freemkv-keysources
-      - uses: actions/checkout@v7
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
        with:
-          repository: freemkv/libfreemkv
-          ref: qa
-          path: libfreemkv
-      - uses: actions/checkout@v7
+          checkout: libfreemkv freemkv-unlock
+          patch: libfreemkv
+          self: freemkv-keysources
+      - uses: dtolnay/rust-toolchain@master
        with:
-          repository: freemkv/freemkv-unlock
-          ref: qa
-          path: freemkv-unlock
-      - name: Resolve siblings from their qa tips
-        shell: bash
-        working-directory: freemkv-keysources
-        run: |
-          mkdir -p .cargo
-          cat > .cargo/config.toml <<'EOF'
-          [patch.crates-io]
-          libfreemkv = { path = "../libfreemkv" }
-          EOF
-      - uses: dtolnay/rust-toolchain@1.97.0
+          toolchain: ${{ needs.resolve-msrv.outputs.v }}
      - uses: Swatinem/rust-cache@v2
        with:
          workspaces: freemkv-keysources
@@ -17,7 +17,7 @@ jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
      - name: Verify Cargo.toml version matches tag
        run: |
          CARGO_VER="v$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')"
@@ -29,10 +29,11 @@ jobs:

  # Tests run as a PARALLEL TRIPWIRE: they fail the run if they fail, but the
  # release job does NOT `needs:` this job. The tag decision was already gated by
-  # the local precommit (same Rust 1.86, same commit).
+  # the local precommit (same MSRV, same commit).
  #
-  # freemkv-keysources is a library — Cargo.lock isn't tracked, so --locked
-  # would always fail (no lockfile to lock against on a fresh runner). Its
+  # Cargo.lock is now committed (issue #15), but --locked is still omitted: on
+  # the runner the libfreemkv dep resolves from crates.io, not the local path
+  # patch, which --locked can't reconcile. Its
  # libfreemkv dep resolves from crates.io (the dev .cargo/config.toml patch is
  # gitignored and absent on the runner), so libfreemkv must already be published
  # at this version — the release script enforces that ordering before tagging.
@@ -40,8 +41,13 @@ jobs:
    needs: verify
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v7
-      - uses: dtolnay/rust-toolchain@1.97.0
+      - uses: actions/checkout@v5
+      - id: msrv
+        shell: bash
+        run: echo "v=$(grep -m1 '^rust-version' Cargo.toml | sed -E 's/.*\"([^\"]+)\".*/\1/')" >> "$GITHUB_OUTPUT"
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ steps.msrv.outputs.v }}
      - uses: Swatinem/rust-cache@v2
      - run: cargo test

@@ -58,7 +64,7 @@ jobs:
    needs: verify
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v5
      - name: Create GitHub Release
        uses: softprops/action-gh-release@v3
        with:
@@ -1,5 +1,4 @@
 /target
-Cargo.lock

 # session scratch — never track (may contain RE breadcrumbs)
 scratch/
@@ -1,5 +1,184 @@
 # Changelog

+## [1.7.3] — 2026-09-19
+
+### Changed
+
+- Unified release with freemkv 1.7.3 (`info --share` disc-structure capture for bug reports + the multi-angle UHD main-title fix in libfreemkv; see the libfreemkv/freemkv 1.7.3 notes). No functional changes to this crate.
+
+## [1.7.2] — UNRELEASED
+
+### Added
+
+- `OnlineSource` now records the reachability outcome of its actual `/decode` POST (an HTTP `Status(code)` for any answer, including 200/404/422/429/5xx, or `Transport` for a connect/timeout/DNS/TLS failure) in a per-thread slot, readable via the new `take_last_decode_reachability()` / `DecodeReachability`. This lets a caller (autorip) classify a no-key result from the REAL decode's outcome instead of firing a second, redundant probe against the POST-only endpoint. No behavioural change to key resolution itself.
+
+## [1.7.1] — UNRELEASED
+
+### Changed
+
+- Version aligned to 1.7.1 for the unified release (freemkv-unlock 1.7.1 LibreDrive unlock fix); no functional changes.
+
+## [1.7.0] — 2026-09-02
+
+### Changed
+
+- Version aligned to 1.7.0 for the unified release. Internal CI/lint hardening only (stable-clippy MSRV split, cargo-deny dependency-audit gate, audience-based comment-guard); no functional changes.
+
+## [1.6.14] — 2026-08-31
+
+### Changed
+
+- Version aligned to 1.6.14 for the unified release.
+
+## [1.6.13] — 2026-08-28
+
+### Changed
+
+- Version aligned to 1.6.13 for the unified release.
+
+## [1.6.12] — 2026-08-27
+
+### Changed
+
+- Version aligned to 1.6.12 for the unified release; no functional changes.
+
+## [1.6.11] — 2026-08-26
+
+### Changed
+
+- Version aligned to 1.6.11 for the unified release. No functional changes to
+  this crate; the release was driven by the libfreemkv main-feature selection
+  improvements and the autorip mux-quarantine fix (see the libfreemkv and
+  autorip 1.6.11 notes).
+
+### Added
+
+- Codecov coverage reporting and badge.
+- Substantially expanded unit-test coverage.
+
+## [1.6.10] — 2026-08-23
+
+### Changed
+
+- Version aligned to 1.6.10 for the unified release. No functional changes to
+  this crate; the release was driven by libfreemkv (TrueHD/MLP audio now resyncs
+  to the next major-sync access unit after a source transport-stream
+  discontinuity, instead of splicing post-gap audio mid-stream — fixing
+  decoder-choking seams on discs whose stream carries a continuity-counter gap;
+  see the libfreemkv 1.6.10 notes).
+
+## [1.6.9] — 2026-08-22
+
+### Changed
+
+- Version aligned to 1.6.9 for the unified release. No functional changes to
+  this crate; the release was driven by autorip (automatic per-episode TV
+  ripping — each episode named `S{NN}E{MM}`, with TMDB runtime-aligned episode
+  numbering across multi-disc seasons — a Manual Rename option, and a unified
+  per-disc staging state file — see the autorip 1.6.9 notes).
+
+## [1.6.8] — 2026-08-21
+
+### Changed
+
+- Version aligned to 1.6.8 for the unified release. No functional changes to
+  this crate; the release was driven by autorip (webhooks now fire per pipeline
+  stage — Rip / Mux / Move — with the Rip hook firing the moment the drive is
+  free again, plus a Ripper-tab activity-banner fix so it also shows during
+  moves — see the autorip 1.6.8 notes).
+
+## [1.6.7] — 2026-08-21
+
+### Changed
+
+- Version aligned to 1.6.7 for the unified release. No functional changes to
+  this crate; the release was driven by autorip (per-webhook event selection,
+  a progress bar per moved artifact, and move-queue / webhook-error fixes —
+  see the autorip 1.6.7 notes).
+
+## [1.6.6] — 2026-08-20
+
+### Changed
+
+- Version aligned to 1.6.6 for the unified release. No functional changes
+  to this crate; the release was driven by autorip (webhooks may now target
+  private/LAN addresses — see the autorip 1.6.6 notes).
+
+## [1.6.5] — 2026-08-20
+
+### Fixed
+
+- **A media, disc-ID, or VUK key at the end of a keydb row is no longer
+  lost to the comment beside it.** Many `keydb.cfg` rows end with a
+  `; MKBv…` note. When that note sat directly after the row's final
+  field and that field was the media key (`M`), disc ID (`I`), or VUK
+  (`V`) — rather than a unit key (`U`) — the note was read as part of the
+  value, the hex parse failed, and the key was silently dropped, so the
+  disc reported no key even though the file held one. The note is now
+  stripped from those three fields exactly as it already was from the
+  unit-key field (a hex value never contains `;`, so the split is safe).
+  A disc that stopped resolving for this reason resolves again.
+
+- **A misconfigured key service is no longer quieter than an outage.** A
+  mistyped port, an `http://` URL, or a key-service address the SSRF guard
+  refuses all mean the same thing: the service was never asked, so nothing is
+  known about the disc. They were reported as an empty result — the same value a
+  service returns when it genuinely holds no key — so a standing
+  misconfiguration surfaced to the operator as "no key for this disc" and never
+  self-corrected, while a transient DNS failure was correctly reported as a
+  failure. All three are now failures, logged at error level and separated in
+  the log text from an outage: one says fix the URL, the other says wait. A
+  later key source's real key still wins, so nothing that used to rip stops
+  ripping.
+- **A replaced `keydb.cfg` can no longer be missed.** The parsed keydb is cached
+  behind the file's identity, and that identity was size plus modification time
+  — which are byte-identical when a file is replaced within the same second by
+  one of the same length, the common shape of a daily refresh on a filesystem
+  that records whole seconds. The old, superseded keys were then served for the
+  rest of the process's life while every lookup reported success. The identity
+  now includes the file's inode, and a cache entry is not trusted until the file
+  has been unmodified long enough for its timestamp to be meaningful.
+- **A corrupt keydb keeps saying so.** The summary warning that counts rejected
+  and duplicated rows is produced while parsing, and the cache skips parsing —
+  so a damaged keydb warned once, at whatever moment it was first read, and was
+  then served in silence to every later disc. The summary is now re-emitted on
+  every lookup that serves that file. An intact keydb stays silent.
+- **A keydb's identity and its contents are read through one file handle.** The
+  cache used to stat the path and then separately open it, so a replacement
+  landing between the two stored one file's identity beside another file's keys.
+
+### Security
+
+- **`{:?}` on a keydb no longer spells out its keys.** `KeyDb` and
+  `DiscEntry` derived their `Debug`, so a single `{:?}` in a log line, a
+  tracing field, or a panic message wrote out every processing key and
+  every disc's media key, disc ID, VUK, and unit keys in full — on the
+  published file, all 184,860 discs' worth. Both are public API, so any
+  caller could trip it. Both types now format through a redacting `Debug`
+  that names each field without its bytes, matching the AACS types this
+  parser was split from, and a test fails if the plain derive ever returns.
+
+- **The host certificate's redaction is now pinned by a test.** `{:?}` on a
+  keydb host certificate does not print the AACS host private key, and never
+  did — but that depended entirely on libfreemkv's own redacting formatter,
+  with nothing in this crate to notice if it changed. The whole-database
+  formatter's test did not cover it. It does now, along with device keys.
+
+### Changed
+
+- **Breaking (API):** `KeyDb::disc_entries`' key and `DiscEntry::disc_hash` are
+  `Arc<str>` rather than `String` (a ~13 MB saving on the published keydb, which
+  is now held in memory). Code that requires an owned `String` from either needs
+  `.to_string()`. Unreleased in 1.6.4; recorded here because it shipped to git
+  consumers without a note.
+
+## [1.6.4] — 2026-08-15
+
+### Changed
+
+- **No functional change.** This crate ships alongside the rest of freemkv at a
+  matching version; its behaviour is untouched.
+
 ## [1.6.3] — 2026-08-10

 ### Changed
@@ -1,8 +1,8 @@
 [package]
 name = "freemkv-keysources"
-version = "1.6.3"
+version = "1.7.4"
 edition = "2024"
-rust-version = "1.97"
+rust-version = "1.88"
 license = "MIT"
 description = "Pluggable AACS key sources (keydb, online key service) for libfreemkv. Each source looks a disc up and hands libfreemkv its terminal Unit Keys via get_unit_keys; the library does all derivation."
 repository = "https://github.com/freemkv/freemkv-keysources"
@@ -17,7 +17,7 @@ publish = false
 # The crate provides the `KeySource` trait + `Key`/`DiscInputs` types these impls fill.
 # libfreemkv is git-only now; the committed [patch.crates-io] below redirects this
 # bare version req to the libfreemkv git tag (local dev overrides it to a path).
-libfreemkv = "1.6"
+libfreemkv = "1.7"
 # OnlineSource: POST disc inputs + samples to a key service over HTTP.
 ureq = { version = "3", features = ["json"] }
 serde_json = "1"
@@ -34,10 +34,13 @@ tracing = "0.1"
 lto = "thin"
 codegen-units = 1

-# libfreemkv is git-only (off crates.io). Redirect the bare `libfreemkv = "1.5"`
+# libfreemkv is git-only (off crates.io). Redirect the bare `libfreemkv = "1.6"`
 # req above to the git tag — committed and CI-visible. The release script
 # rewrites this tag to the new version before regenerating Cargo.lock. Local dev
 # overrides it with a path patch via the gitignored .cargo/config.toml (a
 # config-level [patch.crates-io] wins over this manifest one for the same crate).
 [patch.crates-io]
-libfreemkv = { git = "https://github.com/freemkv/libfreemkv", tag = "v1.6.2" }
+libfreemkv = { git = "https://github.com/freemkv/libfreemkv", tag = "v1.7.3" }
+
+[lints.clippy]
+uninlined_format_args = "allow"
@@ -0,0 +1,14 @@
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![CI](https://github.com/freemkv/freemkv-keysources/actions/workflows/ci.yml/badge.svg)](https://github.com/freemkv/freemkv-keysources/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/freemkv/freemkv-keysources/branch/dev/graph/badge.svg)](https://codecov.io/gh/freemkv/freemkv-keysources)
+
+# freemkv-keysources
+
+Pluggable AACS key sources (keydb, online key service) for
+[libfreemkv](https://github.com/freemkv/libfreemkv). Each source looks a disc up
+and hands libfreemkv its terminal Unit Keys via `get_unit_keys`; the library
+does all derivation.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
@@ -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"
@@ -0,0 +1,19 @@
+# Coverage is informational only: it never blocks a merge or a release. The
+# release cascade is gated by ci.yml / qa.yml and the local precommit, not by
+# a coverage threshold.
+coverage:
+  status:
+    project:
+      default:
+        informational: true
+    patch:
+      default:
+        informational: true
+
+# No PR comment noise; the badge and the Codecov UI are enough.
+comment: false
+
+# Exclude non-product code from the coverage denominator.
+ignore:
+  - "tests/**"
+  - "ci/**"
@@ -0,0 +1,42 @@
+# cargo-deny — gates the RESOLVED dependency graph (issue #15).
+# Runs in CI against the committed Cargo.lock: RUSTSEC advisories, a permissive
+# licence allow-list, and source/ban hygiene. Update the lock (cargo update)
+# to clear an advisory rather than adding an `ignore` entry without cause.
+
+[advisories]
+yanked = "deny"
+# ignore = ["RUSTSEC-0000-0000"]  # only with a written justification
+
+[licenses]
+# The whole tree is permissive. r-efi's LGPL arm is satisfied by Apache-2.0
+# (its expression is "Apache-2.0 OR LGPL-2.1-or-later"), so no copyleft is
+# allowed here. Add a licence only when a real dependency introduces it.
+allow = [
+    "MIT",
+    "Apache-2.0",
+    "Apache-2.0 WITH LLVM-exception",
+    "0BSD",
+    "Unicode-3.0",
+    "Unlicense",
+    "Zlib",
+    "BSD-2-Clause",
+    "BSD-3-Clause",
+    "ISC",
+    "CDLA-Permissive-2.0",
+]
+confidence-threshold = 0.9
+
+[bans]
+multiple-versions = "warn"   # transitive dupes (digest 0.10/0.11 etc.) are noise, not a gate
+wildcards = "deny"
+# The freemkv siblings resolve as path deps under CI's path-patch layout, which
+# reads as a wildcard version req. That is internal, not a supply-chain wildcard.
+allow-wildcard-paths = true
+
+[sources]
+unknown-registry = "deny"
+unknown-git = "deny"
+# The freemkv siblings are first-party git-tag deps; allow git sources from
+# our own org only (CI resolves them as git, not the local path override).
+[sources.allow-org]
+github = ["freemkv"]
@@ -0,0 +1,159 @@
+# keydb_format.rs — design notes
+
+## Full parser API retained on purpose
+
+The parser is copied verbatim, so it carries the full KeyDb/DiscEntry API
+even though this crate's consumer (`keydb.rs`) only exercises a subset
+(`load`, `find_disc`, `iter_disc_entries`, and the public fields read by
+`KeydbSource::unit_keys_from` / `KeydbSource::host_certs`). NOTE: an earlier
+revision of this comment cited a `candidates_from` function — no such
+function has ever existed in this crate; the real consumer is
+`KeydbSource::unit_keys_from` (keydb.rs), which reads `unit_keys`, `vuk`,
+`media_key` AND `vid` (`vid` is load-bearing for the MK+VID derivation the
+kat_c / kat_d KATs pin — it is NOT unused). `DiscEntry::title` is likewise
+read — by `to_keydb_cfg` and the redacting `Debug` impl — so it is not
+unused either. The genuinely unused items — `empty` and `find_vuk` — are
+part of the faithful copy and are retained rather than pruned; allow
+dead_code so the byte-for-byte copy compiles clean without diverging from
+the libfreemkv original.
+
+## ParseStats — what `KeyDb::parse` threw away
+
+The parser is fed a THIRD-PARTY file: a mirror can serve a truncated or
+byte-shifted download that is still valid UTF-8, still contains enough
+recognisable rows to pass `KeydbSource::save`'s "at least one entry" check,
+and is then atomically committed as the new keydb — after which every disc
+past the corruption point silently resolves nothing. Before this counter,
+each malformed `| DK` / `| PK` / `| HC` / `| HC2` / `0x…` row was dropped by
+an `if let Some(..) = .. { }` with no `else`, no counter and no log, so that
+file was indistinguishable from a healthy one at every layer above.
+
+The counts are logged ONCE per parse (a per-line log would be 181k lines on
+a real keydb, which is why the rate limit is "one summary", never "hide the
+count").
+
+## `KeyDb::load_counted` — same-descriptor stamp + parse
+
+Two callers need this seam, both in `crate::KeydbSource`:
+
+* The identity stamp and the bytes must come from the SAME descriptor.
+  Stat-the-path-then-load-the-path is two independent resolutions of one
+  name, so an atomic rename landing between them stored a stamp
+  describing one file next to the parsed contents of another — and the
+  cache then served that pairing until the stamp changed again. `fstat`
+  on the open handle cannot be pointed at a different inode.
+* The rejection counts have to be RETAINED, not just logged, so a cache
+  hit can re-emit them.
+
+## `to_keydb_cfg` — trailing-comment placement
+
+The trailing `; <comment>` (MKB version / volume size / UHD) is emitted
+ONLY after a `U` (unit-keys) field — that is the one place the parser
+splits the value on `;`. Gluing a comment onto an `M`/`I`/`V` value would
+make `parse_hex16` reject the whole field, so a comment-bearing entry that
+has no unit keys drops its comment (keys always survive; the metadata is a
+derivable hint). Real per-disc rows that carry metadata also carry keys.
+
+## `parse_disc_entry` title handling
+
+Title = everything between `= ` and the first ` | ` field (or the trailing
+`;` comment), kept VERBATIM (trimmed). This is a FAITHFUL copy of the keydb
+title, so it must round-trip exactly: a previous version extracted a `(...)`
+substring as a "display title", but that TRUNCATED real titles that
+legitimately contain parentheses ("Lawrence of Arabia (Restored Version) –
+Disc 2 …" → "Restored Version") and broke serialize→parse idempotence.
+Display prettification, if wanted, belongs in the title-display layer, NOT
+this codec.
+
+## Real-data test notes
+
+`to_keydb_cfg_is_idempotent_on_real_keydb`: parse the full keydb -> serialize
+(S1) -> parse S1 -> serialize again (S2). S1 MUST equal S2 byte-for-byte.
+This is the right invariant: a raw keydb.cfg has formatting variance
+(whitespace, optional fields, comment style) that our CANONICAL serializer
+normalizes, so `text == to_keydb_cfg` is NOT expected — but once normalized,
+a re-load+re-serialize must be stable. Idempotence here proves `parse` is
+lossless on its own output and `to_keydb_cfg` is deterministic. Also asserts
+no rows are dropped. It used to carry no `#[ignore]` and `return` early when
+`KEYDB_PATH` was unset — so CI ran it, asserted NOTHING about 181k-entry
+behaviour, and reported green. A skip has to be visible in the test output
+to mean anything, and an ignored test that is RUN without its fixture must
+fail loudly rather than silently pass.
+
+`real_keydb_path`: the old pattern (`match keydb_path() { Some(p) => p, None
+=> return }`) on a non-ignored test is the worst of both worlds: CI ran the
+test, asserted nothing, and reported success. These tests are `#[ignore]`d,
+so running one at all is an explicit request — and an explicit request with
+no fixture must fail, not quietly pass.
+
+## `load_counted_reads_the_handle_not_the_path` test
+
+`load_counted` must read the HANDLE it was given, never re-resolve the
+path. `KeydbSource::cached_db` stamps the open file with `fstat` and then
+parses from that same descriptor precisely so the recorded identity and
+the parsed bytes cannot describe two different files; the moment this
+function re-opens the path, that guarantee is gone and an atomic rename
+landing in between stores one file's stamp beside another file's keys —
+a mismatch the cache then serves as if it were valid.
+
+The race itself cannot be scheduled deterministically in-process, so the
+SEAM is what is pinned: with the path already replaced, the handle's
+contents must still win. Catches the mutation that restores an internal
+`File::open(path)`.
+
+## `host_cert_debug_is_redacted_including_the_sibling_wrapper` test
+
+The SIBLING type. `KeyDb`'s hand-written `Debug` prints `host_certs_len`, so
+it protects the whole-db rendering and nothing else — `KeyDb::host_certs` is
+a public field, and `{:?}` on ONE element of it walks a completely different
+code path: `KeydbHostCert`'s derive, then `HostCert`'s impl. That path
+carries the AACS host PRIVATE key, the only key material in the crate that
+authenticates US rather than opening a disc.
+
+It is safe today only because `libfreemkv::HostCert` hand-writes a redacting
+`Debug` (`aacs::types`, `private_key: "<redacted>"` + `certificate_len`) —
+an EXTERNAL guarantee this crate silently inherits through the derive, with
+nothing on this side pinning it. This test pins it: it catches a libfreemkv
+upgrade that swaps that impl for `#[derive(Debug)]`, which would leak the
+host private key out of this crate's public API with no diff in this
+repository at all.
+
+Rendered three ways because callers reach the cert three ways: the whole
+`Vec` (`db.host_certs`), one element, and the inner `HostCert` a caller
+gets back from `KeyDb::host_certs(mkb)`.
+
+## KEYDB-parser integration tests relocated from libfreemkv
+
+These exercise the parser (`KeyDb::load`) end-to-end against a real
+keydb.cfg and feed its material into libfreemkv's AACS crypto
+(`derive_vuk`, then `decrypt_unit` + `is_clean_ts`). They live here now
+that the parser lives here. All are `KEYDB_PATH`-env-gated and no-op in CI
+when the env is unset; they must still COMPILE.
+
+## `test_decrypt_real_unit` — no-decrypt outcome
+
+Reaching the fallback path is the EXPECTED outcome for the AACS 2.0 (BEE)
+sample this test was written against: the unit is still bus-encrypted, so
+no unit key alone can open it. That makes "no key worked" an unusable
+assertion on its own — which is exactly why this test used to end in an
+`eprintln!` and fall off the end, i.e. pass unconditionally. A no-op
+`decrypt_unit`, an `is_clean` stuck at `false`, or a parser that yielded
+zero keys would all have produced this same clean exit.
+
+What CAN be asserted regardless of the sample: the pipeline actually ran,
+and the decrypt primitive actually transformed the bytes.
+
+## Hand-written redacting `Debug`
+
+Key material must never reach a log, a panic message, or a bug report. Both
+`KeyDb` and `DiscEntry` carry raw AACS key bytes, and both are public API, so
+a `#[derive(Debug)]` on either is a leak of the crown jewels: `{:?}` on a
+loaded `KeyDb` printed every processing key plus every disc's Media Key,
+VID, VUK and Unit Keys. libfreemkv's equivalent types (`aacs::types`:
+`DeviceKey`, `HostCert`, `Vid`, `MediaKey`, `Vuk`, `ProcessingKey`,
+`UnitKey`, its own `DiscEntry`) all hand-write a redacting `Debug` for
+exactly this reason; this crate's copy of the parser dropped that
+convention when it was relocated. These restore it, field-for-field in the
+same style (`<redacted>` for key bytes, a `_len` for key-bearing
+collections). Pinned by `keydb_debug_is_redacted` /
+`disc_entry_debug_is_redacted`.
@@ -0,0 +1,432 @@
+# `keydb.rs` design notes
+
+Long-form rationale moved out of `src/keydb.rs` doc comments to satisfy the
+repo's comment-guard line caps. Each section is pointed to from the file by a
+one-line `// See docs/keydb.md#<anchor>` comment.
+
+## candidate-order
+
+Full derivation path this source walks, cheapest-first:
+
+1. per-disc **Unit Keys** (hash hit) → returned terminal, no derivation.
+2. per-disc **VUK** (hash hit) → `uks_from_vuk` over the disc's encrypted
+   title keys.
+3. a **Media Key**, then `derive_vuk` → `uks_from_vuk`. The MK comes from, in
+   order: the disc's stored MK (hash hit); the keydb's **Processing Key**
+   pool walked against THIS disc's MKB via `derive_media_key_from_pk`; or the
+   device-key pool via `derive_media_key_from_dk`. The PK and DK pools
+   resolve the Media Key WITHOUT a VID; the final `derive_vuk` still needs
+   one. The VID is the unlocker's physical VID (`ResolveCtx::vid`) when
+   present, else the keydb entry's OWN stored VID (the `I` field, `vid`) for
+   the non-physical / ISO path. With no VID from either source the MK path
+   cannot complete — return nothing.
+
+The cross-disc MK-pool brute (trying OTHER discs' stored media keys against
+this disc) stays RETIRED: every MK path here is anchored to the matched
+disc's own MKB or stored material.
+
+The library still OWNS the crypto; this source owns only which primitive to
+call with which material. Returning an empty `Vec` is a genuine "no key for
+this disc here".
+
+## file-identity
+
+`(len, modified)` ALONE IS NOT AN IDENTITY. mtime is stored at whole-second
+resolution on HFS+, on many container overlays and on most network
+filesystems, so a writer that replaces `keydb.cfg` within the same second
+with a file of the same byte length leaves `(len, modified)` bit-identical —
+and the cache then serves the superseded parse for the rest of the process's
+life. For a key database that is not a stale page: it is serving retired or
+since-corrected keys while reporting success. The writers that hit this are
+real and named in this crate's own docs: the daily-refresh job, a second
+freemkv process, an operator's editor, a sync tool.
+
+Two independent discriminators close it:
+
+1. `dev` + `ino`. Every writer that publishes ATOMICALLY (temp file, fsync,
+   rename — what `KeydbSource::save` does, and what any correct publisher
+   does) creates a NEW inode, so the stamp differs immediately and
+   unconditionally, whatever the clock or the mtime resolution did. Zero on
+   platforms without them (see `FileStamp::of`), which costs nothing: rule 2
+   stands alone.
+2. A freshness rule on the cache entry — `CacheEntry::is_settled` — which
+   covers the residual in-place rewrite that reuses the inode.
+
+What this still does NOT catch: a writer that FORGES the timestamp, i.e.
+restores an mtime equal to the cached one (`touch -t`, `rsync --times`, a
+tar/backup restore) into the SAME inode with the SAME length. Nothing short
+of hashing the content can see that, and hashing 62 MiB per lookup is
+precisely the cost the cache exists to remove (~141 ms × ≥3 loads per rip).
+`KeydbSource::save` therefore keeps invalidating the cache directly, so the
+one write path this crate owns never depends on any of the above.
+
+## settle-proof
+
+Whether a cache entry's stamp can be TRUSTED to change if the file changes.
+
+The proof, for a filesystem storing mtime at granularity `G`: suppose this
+entry was stamped at `stamped_at` with `stamped_at - modified >= G`, and some
+writer later rewrites the file in place at wall time `T > stamped_at`. The
+recorded mtime `m'` of that write is within one granule of `T`, so
+`m' >= T - G > stamped_at - G >= modified`. Hence `m' != modified` and the
+stamp DOES change. The ambiguous window is therefore exactly the one where
+the cached entry was stamped less than `G` after the file's own mtime — i.e.
+we looked at the file while it was still "hot" — and in that window the
+entry is refused and the file is re-read. Once the file has been quiet for
+`G`, its entry settles and the cache is fully effective again.
+
+Cost: after every keydb write, lookups re-parse for up to `G` (2 s). The
+published keydb is rewritten daily, so that is ~2 s of re-parsing per day
+against a cache that saves ~420 ms per rip.
+
+`modified: None` (a filesystem that reports no mtime) never settles: the only
+two discriminators left would be size and inode, so the entry is re-read
+every time rather than being trusted on a weaker basis.
+
+CLOCK CAVEAT: `stamped_at` is the local clock and `modified` is the
+filesystem's. On a network share whose server clock runs AHEAD of the
+client's by more than `G`, entries never settle (safe: more re-parsing). A
+server clock BEHIND the client's makes an entry settle early, which re-opens
+the same-second window it closes — the inode rule (1) is what covers the
+realistic writers there.
+
+## keydbsource-cache
+
+`KeydbSource` caches the parsed database behind the file's identity stamp.
+The published keydb is ~62 MiB / ~181k entries and a single AACS-cert rip
+parses it repeatedly — `host_certs()` for the drive handshake (freemkv's
+`pipe.rs`/`engine.rs`, autorip's `keysource.rs` each build their own source),
+then the trait `host_certs(mkb)` during resolution, then `get_unit_keys` —
+and every one of those calls used to re-read all 62 MiB from disk and
+re-parse it from scratch, because the struct held nothing but a `PathBuf`.
+
+A keydb replaced underneath this source is picked up on the next call, with
+ONE stated exception: a writer that rewrites the file in place, into the
+same inode, at the same byte length, having restored the previous mtime
+exactly (`touch -t` / `rsync --times` / a backup restore). Everything else —
+any atomic rename, any length change, any real clock advance — changes the
+stamp. `FileStamp` and `CacheEntry::is_settled` carry the full argument and
+the clock caveats; do not weaken either without re-reading them. (The
+earlier wording here — "an externally replaced keydb is still picked up" —
+was simply false for a same-second, same-length replacement, which is the
+common shape of a daily-refresh job on a whole-second-mtime filesystem.)
+
+MEMORY RESIDENCY (accepted, and deliberately recorded rather than fixed
+here): a hit keeps the entire parsed keydb — every disc's Media Key / VID /
+VUK / Unit Keys, the processing- and device-key pools, and the host-cert
+PRIVATE keys — resident for the process's life, where the pre-cache code
+held one parse transiently. Nothing in this crate zeroizes on drop, so that
+material was always exposed to a core dump or a swapped page; the cache
+widens the WINDOW, it does not create the class. Closing it properly means
+zeroize-on-drop across `KeyDb`, `DiscEntry` and libfreemkv's `aacs::types`
+(which owns most of the buffers) — a cross-crate change, tracked separately,
+NOT smuggled in behind a cache fix.
+
+## cached-db-one-open
+
+Errors are the same ones `KeyDb::load` produces, unchanged: a missing file
+is `NotFound` (the documented benign case), an over-cap or non-UTF-8 file is
+`InvalidData`. The stamp costs an `fstat`, not a 62 MiB read.
+
+ONE OPEN, ONE IDENTITY. The file is opened once and both the stamp (`fstat`
+on that handle) and, on a miss, the bytes come from it. The previous shape —
+`std::fs::metadata(path)` and then a separate `KeyDb::load(path)` — resolved
+the path TWICE with no atomicity between them, so a rename landing in the
+gap cached the new file's stamp beside the old file's contents (or the
+reverse); the pairing was then served, looking perfectly valid, until the
+stamp changed again. The stamp is read BEFORE the bytes on purpose: a write
+racing the read then leaves the OLD stamp cached, which the next call
+detects, whereas stamping afterwards would file torn content under a
+fresh-looking identity and pin it.
+
+## cached-db-reemit
+
+Re-emit the parser's rejection summary on EVERY hit, not just on the parse
+that produced it. `KeyDb::parse` is what logs it, and a hit skips `parse`
+entirely — so a daemon that cached a corrupt keydb logged its rejected-row
+counts exactly once, at whatever moment it first read the file, and then
+served that same damaged database to every later rip in silence. Repetition
+is the correct failure mode here: the line is emitted only when the file
+really does have rejected or duplicate rows, and a warning an operator can
+still see on the tenth rip is worth more than one they had to catch on the
+first.
+
+## load-failure
+
+A MISSING keydb is the documented benign case: the app may simply not have
+one, another source may hold the key, and "no keydb" is genuinely "no key
+here". Everything else is NOT that: `InvalidData` is a keydb over the
+128 MiB cap or one that is not valid UTF-8 — i.e. corrupt, truncated, or a
+half-finished download — and a permission/IO failure means the file could
+not be read at all. Reporting either as an empty result made a broken keydb
+indistinguishable from "this disc has no key" (the same conflation as the
+seven-hour 502), with no log to notice it by. Both are now logged AND
+surfaced as errors so the resolver reports a source failure instead of
+`E7022`.
+
+## save-mirror-parse
+
+Mirror `KeyDb::parse`'s disc-entry rule EXACTLY by CALLING it
+(`is_disc_entry_line`), so `save()` never validates + persists content that
+parses to zero usable entries (e.g. a stray "0xDEADBEEF" comment line) and
+the two can no longer drift — they did drift once already, on the `0X` case
+rule.
+
+## unit-keys-from
+
+CPS-unit numbering: a returned `UnitKey::idx` is the POSITIONAL index
+libfreemkv's `resolve_and_apply` turns into the canonical CPS-unit number
+`idx + 1`. For the terminal per-disc unit-key path we therefore map the
+keydb's stored CPS number `num` to `idx = num - 1`, so the committed number
+is byte-identical to the keydb's `num` (and to what the OLD
+`Key::Unit(entry.unit_keys)` path committed). For the VUK / MK paths the
+boil primitive already yields 0-based positional indices, matching
+`parse_unit_key_ro`'s `(i + 1)` after the resolver's `+ 1`.
+
+## unit-keys-per-disc-hit
+
+Per-disc hit (most specific). `find_disc` normalizes the hash form. Without
+a matched entry this keydb has no per-disc material (Unit Keys / VUK / Media
+Key / stored VID) to anchor a derivation for the disc, so it resolves
+nothing. (The PK and DK pools are global, but the cross-disc MK-pool brute —
+trying OTHER discs' media keys against this disc — stays retired; a PK/DK
+pool only ever resolves a disc reached through its own matched entry below.)
+
+## unit-keys-union
+
+UNION every source of terminal keys, then dedup — never first-hit. A stored
+`unit_keys` list can be PARTIAL (the key-import tool only ever sampled the
+CPS units reachable from a playlist, so an orphan unit's key may be
+missing), while the per-disc VUK boils EVERY declared CPS unit. Taking the
+stored list alone (the old return-at-first-path) would shadow the VUK and
+silently drop the orphan unit's key. So gather both and keep a unique-by-key
+list: the read path tries every key per unit, so an extra or stale key is
+harmless — only a MISSING key hurts.
+
+## unit-keys-vuk-or-mk
+
+2. Per-disc VUK — one step, no VID needed; boils ALL declared units.
+3. Else a Media Key path (stored MK / PK pool / DK pool) → VUK → all
+   declared units. The MK itself carries no VID, but the final `vuk_from_mk`
+   needs one: physical (unlocker) VID first, else the entry's stored VID
+   (`I` field), else cannot derive. Either branch yields the COMPLETE
+   declared set, so we take the first that resolves (VUK preferred —
+   cheapest).
+
+## write-atomic
+
+keydb.cfg is the single source of AACS truth, and save/update run
+unattended (first-boot download + daily-refresh thread, with a container
+restart on every release). A bare in-place `fs::write` truncates the file
+before writing, so a SIGKILL (docker stop's grace window), OOM-kill, power
+loss, or ENOSPC mid-write would leave the keydb half-written — the prior
+good copy already gone. A truncated keydb doesn't error at write time; it
+silently breaks key resolution on every later AACS rip. Writing to a temp
+file then renaming (POSIX rename is atomic within a filesystem) means an
+interrupted update leaves the previous keydb fully intact.
+
+The fsync MUST succeed before the rename: a `sync_all` failure (ENOSPC,
+ESTALE on the bind-mounted volume) means the kernel never guaranteed the
+bytes reached stable storage, so publishing them via rename would defeat
+crash-safety. The temp name is unique per call (pid + monotonic counter) so
+a concurrent update can't share a fixed temp path and rename a mangled file
+over the keydb.
+
+## get-unit-keys-trait
+
+A MISSING keydb is not an error — it simply yields no keys (another source
+may have them), the same as the library's own loader. A keydb that exists
+but cannot be USED (over the size cap, not UTF-8, unreadable) is a source
+failure and returns `Err`: it says nothing about whether this disc has a
+key, and reporting it as an empty result is the same looks-like-success
+failure as a 502 reported as `E7022`.
+
+The keydb carries no AACS 2.1 forensic index keys today, so it does not
+override `get_fmts_indexes` — the default (empty) opts it out, and an FMTS
+disc's forensic set comes from the online source.
+
+## host-certs-trait
+
+Expose the keydb's host certs through the trait — the OEM/AACS cert-auth
+route collects them across every source via this method. Wires the disc's
+MKB generation through for revocation filtering (the keydb parser's
+`; Revoked in MKBv<N>` annotation): a cert revoked at generation `R` is
+withheld once the disc's generation reaches `R`.
+
+## test-pinned-mtime
+
+Force a file's mtime to `PINNED_MTIME`, so two different files can be made
+bit-identical to a `(len, mtime)` stamp on purpose. The cache tests that
+matter all depend on FORCING the indistinguishable case rather than hoping
+the filesystem produces it: on APFS (nanosecond mtimes) a same-second
+replacement is otherwise detected by mtime alone, and a test that relies on
+that passes with the fix reverted — which is worth nothing.
+
+## test-committed
+
+The committed `(cps, key)` pairs libfreemkv's `resolve_and_apply` derives
+from a source's Unit Keys: positional `idx` → canonical CPS number
+`idx + 1`. The KATs compare against THIS to prove byte-identical parity with
+the OLD `Key::Unit` / resolver-derived commit.
+
+## test-mock-ctx-stub
+
+`MockCtx` implements the full `ResolveCtx` trait so it can stand in for a
+real disc, but `KeydbSource` itself never calls `title()`/`samples()` (those
+matter to the online source, not the local keydb). Exercise them directly
+so the mock's trait surface is proven correct too.
+
+## test-kat-a
+
+Here `enc_title_keys` is empty, so the VUK can't derive anything — only the
+stored list contributes, and it commits byte-identically to the stored
+`(cps, key)` pairs.
+
+## test-orphan-union
+
+Orphan-unit completeness (the real keydb bug): an entry stores only `uk1`
+(the key-import tool sampled one reachable CPS unit) but ALSO carries the
+VUK, which boils BOTH declared units. The old return-at-first-path handed
+back just `[uk1]`, shadowing the VUK and silently dropping the orphan unit.
+The union must return BOTH — the stored uk1 AND the VUK-derived second unit.
+
+## test-kat-c
+
+A hash hit with a Media Key and a physical VID (from the unlocker) derives
+`MK → VUK → UK`. The PHYSICAL VID must be used in preference to the keydb's
+stored VID — proven by giving the entry a DIFFERENT stored VID and showing
+the result tracks the physical one.
+
+## test-kat-f
+
+Owner decision #1 (AACS): a keydb Processing Key must be walked against the
+matched disc's own MKB to recover the Media Key, then driven down the full
+chain `PK → MK → VUK → UK`. The disc entry carries NO stored MK/VUK/UK — the
+only key material is a global `PK` row — and the result must be the real
+Unit Keys, byte-identical to deriving from the recovered MK.
+
+The MKB + PK use a known-answer construction (a planted PK whose derived MK
+satisfies the synthetic verify record); the constants are precomputed AES
+vectors so this crate needs no AES primitive of its own. They mirror
+libfreemkv's `boil::mk_from_pk_drives_full_chain_to_uks` KAT.
+
+## test-repeated-lookups
+
+A single AACS-cert rip drives this source at least three times — the
+scan-options builder's inherent `host_certs()`, the trait `host_certs(mkb)`
+during the handshake, then `get_unit_keys` — and each call used to re-read
+and re-parse the WHOLE file, because `KeydbSource` held nothing but a
+`PathBuf`. Measured on the real 62 MiB / 184,860-entry keydb: ~140 ms per
+parse in `--release`, i.e. ~420 ms and ~186 MiB of file reads per rip,
+against ~1 µs for a cache hit.
+
+Catches the mutation that drops the cache (every call re-parses: count 3)
+and the mutation that makes the cache unconditional (see the invalidation
+tests below).
+
+The mtime is pinned into the PAST first, because a cache entry is only
+trusted once the file has been quiet for the mtime granularity
+(`CacheEntry::is_settled`) — a keydb written microseconds ago is
+deliberately re-read. Unix-only: pinning an mtime needs `touch -t` (no
+`filetime` dependency for a test).
+
+## test-changed-keydb
+
+The cache must not go stale: a keydb replaced UNDERNEATH the source (the
+daily-refresh thread writing through a different `KeydbSource`, or an
+operator dropping in a new file) has a different size/mtime stamp and must
+be re-read. Catches the mutation that caches on first load and never
+re-stats — which would pin a rip to a keydb deleted hours earlier.
+
+## test-two-discriminators
+
+The defect both of the inode/settle tests below pin: `(len, mtime)` is not a
+file identity. An external writer — the daily-refresh job, a second freemkv
+process, an editor, a sync tool — that replaces `keydb.cfg` inside one mtime
+granule with a file of the SAME length leaves that pair bit-identical, and
+the source then serves the superseded parse for the rest of the process's
+life: retired or since-corrected keys, reported as success.
+
+Each test disables the OTHER discriminator through `mtime_granularity`, so
+neither can pass on the strength of the one it is not testing, and neither
+depends on the host filesystem's real mtime resolution (on APFS the naive
+scenario is not reproducible at all).
+
+## test-inode-rename
+
+A keydb replaced by ATOMIC RENAME — how every correct publisher, including
+this crate's own `save()`, installs a new file — must be re-read even when
+length and mtime are identical. `mtime_granularity: 0` makes every entry
+settle, so ONLY dev+ino can distinguish the two files here.
+
+Catches the mutation that drops `dev`/`ino` from `FileStamp` (the original
+`(len, modified)` stamp): the source then keeps answering with the previous
+keydb's keys.
+
+## test-inplace-rewrite
+
+A keydb rewritten IN PLACE — same inode, same length, mtime forced back to
+the same value — must still be re-read while the cached entry is too young
+to trust. `mtime_granularity` is set to a decade so nothing ever settles,
+which is the same condition a real same-second, whole-second-mtime
+replacement creates and the only way to reproduce it deterministically on a
+nanosecond-mtime filesystem.
+
+Catches the mutation that deletes the `is_settled` check from `cached_db`
+(every stamp match trusted unconditionally, which is what the original code
+did): dev, ino, len and mtime are ALL identical here, so without the
+freshness rule the source serves the old keys forever.
+
+## test-corrupt-warns
+
+`ParseStats::log` runs inside `KeyDb::parse`, and a cache hit skips `parse`
+— so once the cache landed, the rejected-row summary for a given file was
+emitted exactly ONCE for the entire life of the process, while that same
+damaged file went on being served to every subsequent rip. A long-running
+daemon (autorip) logs it at startup, the operator misses it in the startup
+noise or loses it to log rotation, and there is no second chance for as long
+as the process runs.
+
+Catches the mutation that deletes the `emit_parse_stats` call from the
+cache-HIT arm of `cached_db`: warnings would drop to 1 while the file is
+still served three times.
+
+## test-healthy-silent
+
+Catches the mutation that makes `emit_parse_stats` unconditional (drops
+`ParseStats::log`'s empty-counts early return).
+
+## test-fresh-not-trusted
+
+Catches the mutation that widens the window to something unbounded (a
+granularity of hours would re-parse 62 MiB on every lookup all day) by
+pairing with `repeated_lookups_parse_the_keydb_once`, which proves the entry
+DOES settle once the mtime is in the past.
+
+## test-save-invalidates
+
+`save()` replaces the very file this source reads, so it drops the cached
+parse ITSELF rather than trusting the (size, mtime) stamp: a same-size
+rewrite that lands inside the filesystem's timestamp granularity is the one
+change the stamp cannot see — and it is exactly the change this crate
+performs (the daily-refresh thread re-saving a keydb through the source it
+then reads from).
+
+The test forces that indistinguishable case rather than hoping for it: the
+file is written, stamped to a FIXED mtime, cached, re-saved with different
+keys of the SAME length, and stamped back to the same mtime. To the stamp
+the two files are identical, so only the explicit invalidation can produce
+the new key. Unix-only because pinning an mtime needs `touch -t` (no
+`filetime` dependency for one test).
+
+## test-corrupt-is-error
+
+`KeyDb::load` fails distinguishably for a keydb that is over the 128 MiB cap
+or not valid UTF-8 — a truncated download, a half-written file, a binary
+blob dropped in by mistake. Both used to collapse into `Ok(Vec::new())` with
+ZERO tracing, i.e. into the benign "no key for this disc" the resolver
+reports as `E7022` — the same looks-like-success failure as the seven-hour
+502. Only a MISSING file is genuinely benign.
+
+Catches the mutation that restores `Err(_) => Ok(Vec::new())`.
+</content>
@@ -0,0 +1,49 @@
+# freemkv-keysources: scope and design notes
+
+## Mechanism vs. policy
+
+Applications (autorip, the `freemkv` CLI) choose and order the key sources
+from their own config — the local-vs-online policy is just which impls they
+plug in — then resolve and hand the resulting key to `Disc::decrypt_with`.
+
+Each source resolves a disc's terminal **Unit Keys** in one shot via
+`KeySource::get_unit_keys`, driving libfreemkv's boil-down crypto primitives
+for whatever level of material it holds. Compose several with `MultiSource`
+in the caller's chosen order.
+
+Reading the encrypted content-sample units a key server validates on, and
+applying the resolved keys against a disc, is decryption *mechanism* — it
+lives in the library (`libfreemkv::resolve_and_apply`,
+`libfreemkv::read_encrypted_units`), not here.
+
+## `MultiSource` failure semantics
+
+`MultiSource::get_unit_keys` tries each inner source in order and returns the
+first non-empty Unit Key set (and `get_fmts_indexes` does the same for the
+forensic set). The caller supplies the list AND the order — local-first
+`[Keydb, Online]`, online-first `[Online, Keydb]`, etc. — so the "which
+sources, in what order" policy lives entirely with the application, not the
+library. `MultiSource` is itself a `KeySource`, so it nests and composes.
+
+**A source that could not ANSWER is not a source that answered "no key".**
+When no inner source produces keys, the composition returns `Err` if any
+inner source failed, and `Ok(empty)` only when every source genuinely
+answered and none held a key. This mirrors libfreemkv's own resolver
+(`keysource::drive_unit_keys`, which tracks an `errored` flag, and
+`source_failure`, which stamps the first failure onto the disc) — a
+composition that swallowed the `Err` would hand the resolver a clean
+`Ok(empty)`, and an outage would once again be reported to the operator as
+`E7022 No key source has a decryption key for this disc`.
+
+## `first_non_empty` ordering rule
+
+A source failure never blocks the chain (a later source is still tried, and
+a later success still wins outright, error or no error), but it is not
+forgotten either: with no keys anywhere, the FIRST failure is returned.
+First (not last) matches libfreemkv's `source_failure` rule, so the
+most-preferred source's reason is the one the operator is told about, in the
+same order the caller expressed a preference for successes.
+
+`get` selects which trait method to drive, so the base and forensic paths
+share ONE implementation of this rule and cannot drift apart — the forensic
+half carried the identical bug.
@@ -0,0 +1,13 @@
+# `MultiSource`: a source that could not answer is not a source that said no
+
+`MultiSource` used to re-collapse the Ok/Err distinction `OnlineSource` was
+engineered to draw: `if let Ok(uks) = s.get_unit_keys(ctx)` discarded every
+`Err`, so a composition whose sources ALL failed returned `Ok(Vec::new())` —
+which the resolver reports as `E7022 No key source has a decryption key for
+this disc`. That is the seven-hour-502 incident reproduced one layer up.
+
+The regression test `multi_source_reports_a_source_failure_instead_of_a_clean_no_key`
+is THE regression check, one layer up from `interpret_reply`: when no source
+holds a key AND a source could not answer, the composition must report the
+FAILURE, never a clean "no key". It catches the mutation that restores
+`if let Ok(uks) = ..` (which drops the `Err` and returns `Ok(empty)`).
@@ -0,0 +1,39 @@
+# `src/online.rs` — `OnlineSource::agent` caching
+
+## Why cache at all
+
+`query` used to build a FRESH `ureq::Agent` every call, and an FMTS disc
+makes two calls per rip (`get_unit_keys` + `get_fmts_indexes`), so it paid
+two TLS handshakes to the same host for no reason — an agent owns the
+connection pool, and a discarded agent discards the pooled, already
+negotiated TLS connection with it.
+
+## Security invariant
+
+The agent is reused ONLY when the freshly resolved + guarded address SET is
+identical to the one the cached agent is pinned to. Every query still
+re-resolves and re-runs the SSRF guard — that is the whole anti-rebinding
+defence and is deliberately not cached; what is reused is the connection,
+and only to addresses just re-validated this call.
+
+## Why the cache key is a sorted, deduped SET, not an ordered sequence
+
+`to_socket_addrs` hands back whatever order the resolver felt like, and a
+round-robin keyserver reorders its A/AAAA records on essentially every
+lookup — an ordered `==` therefore missed the cache every single time
+against exactly the deployment that most needs it, silently degrading to
+the per-query TLS handshake this field exists to avoid.
+
+Set equality is also the honest predicate: the security property being
+asserted is "these are the same validated addresses", which says nothing
+about their order. The agent itself stays pinned to the order it was BUILT
+with; that is safe because an equal set means every address it holds was
+re-resolved and re-guarded this call.
+
+## `a_reordered_but_identical_address_set_reuses_the_agent`
+
+Catches the mutation that drops the sort/dedup from `agent_for`'s key (the
+reversed order would then build a second agent) and, via the second half of
+the test, the mutation that "fixes" order-sensitivity by comparing only
+lengths or the first element — which would wrongly reuse an agent pinned to
+a DIFFERENT address.
@@ -0,0 +1,41 @@
+# `src/online.rs` — `GuardFail` classification details
+
+## Malformed-port authority
+
+A `host:port` authority whose port is not a u16 is a TYPO in the operator's
+config — `https://example.com:notaport/keys`. This used to fall back to the
+WHOLE authority as the hostname (port text included), which of course never
+resolves, so the URL surfaced as `GuardFail::Unreachable` →
+`Err(KeyServiceUnavailable)`: a standing misconfiguration reported as a
+transient outage, the exact collapse `GuardFail`'s own doc says must not
+happen, because the two halves demand OPPOSITE operator actions (fix the URL
+vs. wait).
+
+Reject it as `Config`, identical to the bracketed-IPv6 branch a few lines
+above, which already returns `Config` for an unparseable port. Silently
+substituting `default_port` would be worse still — it would ship the bearer
+token and key material to a port the operator never configured.
+
+## Guard-blocked address (`Config` arm, `resolve_and_guard`)
+
+Log THAT the URL was rejected, never WHY: the guard's message names the
+resolved address, and an internal address must not reach a log an operator
+may paste into a bug report. The static label is enough to separate
+"misconfigured/blocked key-service URL" from "this disc has no key", which
+is the only distinction the operator needs here.
+
+`error!`, not `warn!`, and `Err`, not `Ok(empty)`. This arm used to return
+`Ok(Vec::new())`, which made the PERMANENT fault quieter than the transient
+one directly above it: the service was never asked, yet the composition was
+handed a clean empty and — with no other source holding the key — told the
+operator `E7022 no key for this disc`. Same lie as the seven-hour 502, from
+a config typo that never self-heals. A failure to ask is never evidence
+about the disc, so it leaves as `Err`; `MultiSource::first_non_empty` still
+lets a later source's real key win outright, so this cannot fail a rip that
+the local keydb could have served.
+
+NOTE (reported upstream): libfreemkv has no `KeyServiceMisconfigured` code,
+so the permanent fault borrows the transient E7028. E7028's contract — "the
+source never got as far as answering the question" — is exactly true here;
+only its "transient, retry later" hint is wrong, and the `error!` log
+carries the correcting detail until a 70xx config code exists.
@@ -0,0 +1,20 @@
+# `src/online.rs` tests — pre-flight guards in `query`
+
+Each of the three guards (cleartext scheme, over-cap MKB, under-sampled)
+fires BEFORE any address is resolved and before anything is sent. None was
+exercised before these tests: a reordering that let the cleartext POST
+through would have shipped green, and that POST carries the bearer token
+plus base64 key material.
+
+Their VERDICTS differ on purpose (see docs/online-query-guards.md): the
+cleartext-scheme guard is an operator fault and yields `Err`, while the two
+input-shaped guards yield `Ok(empty)` — this source has nothing for THIS
+disc, permanently, and calling that an outage would send the operator
+waiting for nothing.
+
+The discriminator in all three: the configured host is `.test`, which RFC
+6761 guarantees never resolves. On the guarded path nothing resolves it, so
+the test touches no network and returns `Ok(empty)`. Remove the guard and
+control reaches `resolve_and_guard`, which fails as `Unreachable` ->
+`Err(KeyServiceUnavailable)` — a different Result, so the mutation cannot
+pass.
@@ -0,0 +1,19 @@
+# `src/online.rs` — `OnlineSource::query` return contract
+
+The return type draws THE distinction this source exists to draw:
+
+* `Ok(non-empty)` — the service answered with a key.
+* `Ok(empty)` — the service ANSWERED and holds no key for this disc, or this
+  source had nothing to ask with (no service configured, a misconfigured
+  URL, an over-cap MKB, too few samples). A genuine miss; the resolver moves
+  to the next source and `E7022` is the right verdict.
+* `Err(..)` — the service could not answer: unreachable, timed out, DNS
+  failed, returned 5xx, rejected the token (401/403), rate-limited (429), or
+  replied with something unreadable. NOTHING is known about whether a key
+  exists. Collapsing this into `Ok(empty)` is the bug this signature fixes:
+  a seven-hour run of HTTP 502s was reported to operators as
+  `E7022 No key source has a decryption key for this disc`, and they went
+  hunting for a VUK when the correct action was to wait.
+
+`&self`: one-shot is the resolver's contract (each source's
+`get_unit_keys` is called once), so no per-call latch is needed.
@@ -0,0 +1,57 @@
+# `src/online.rs` — `OnlineSource::query` pre-flight guards
+
+## Refusing cleartext (`http://`)
+
+The request body always carries base64 AACS key material
+(inf/mkb/units/vid) and, when configured, a bearer token in a header — so an
+`http://` POST hands both to any on-path observer, and the token is
+replayable.
+
+There is no legitimate plaintext deployment to preserve here: the address
+guard rejects loopback, RFC1918, ULA and link-local, so an `http://` URL can
+only ever reach the PUBLIC internet — the single worst case for cleartext. A
+self-hosted keyserver on a LAN is already impossible by that guard, whatever
+its scheme.
+
+Still falls THROUGH to the next key source (a local keydb) — an `Err` here
+does not block the chain, because `MultiSource::first_non_empty` returns any
+later source's non-empty key set outright and only surfaces the failure
+when nothing anywhere resolved. What it does stop is the silent case: a
+cleartext URL is the same permanent operator fault as the address-guard
+rejection (see `GuardFail`), so it gets the same verdict. Returning
+`Ok(empty)` here made "we refused to ask" indistinguishable from "the
+service answered and has no key".
+
+## The three-way skip/fault/miss line (MKB cap, sample count)
+
+Written out after the `Config`-was-quieter-than-`Unreachable` bug, in three
+parts:
+
+* NO URL AT ALL is not a fault: the operator did not configure an online
+  source, so there is nothing to report. `Ok(empty)`, silently (the first
+  guard in `query`).
+* A bad URL — wrong scheme, mistyped port, guard-blocked address — is an
+  OPERATOR FAULT. Every disc is affected, nothing was asked, and the fix is
+  to edit the config. That is `Err`.
+* An over-cap MKB or too few content samples is a property of THIS DISC's
+  inputs, not a fault: the request cannot be *formed* for this disc, so this
+  source has nothing for it and never will, whatever the operator does and
+  however long they wait. Reporting that as `KeyServiceUnavailable` would
+  send the operator waiting out an outage that does not exist — the same
+  mislabelling in the opposite direction. These stay `Ok(empty)`, and stay
+  logged.
+
+Logging on the MKB-cap skip matters: a silent empty return there is
+indistinguishable from "no key", so the real cause is surfaced (the cap is
+64 MiB, far above any real trimmed MKB).
+
+## `cleartext_http_url_is_refused_before_anything_is_sent`
+
+Catches two mutations: sending the request anyway (the host is `.test` and
+would surface as `Unreachable`, but the assertion would still hold, which is
+why `too_few_samples_skips_the_request` guards the send-path ordering
+separately) and — the one this test was rewritten for — returning
+`Ok(Vec::new())`, which made a permanent cleartext misconfiguration
+indistinguishable from a genuine miss. A later source's real key still wins
+(`MultiSource::first_non_empty`), so refusing does not fail a rip the local
+keydb can serve.
@@ -0,0 +1,44 @@
+# `src/online.rs` — SSRF guard
+
+## Threat model
+
+The keyserver URL is operator-supplied and the bearer token is confidential.
+After `validate_keyserver_url` checked the host at config time, an attacker
+who controls the keyserver's DNS can rebind it to 169.254.169.254 (cloud
+metadata) or an RFC1918 host in the window between validation and the actual
+POST, exfiltrating the key material and the Authorization token.
+
+## Defence
+
+Resolve the host once just before the POST, reject any blocked IP, and pin
+the ureq connection to those validated addresses so a subsequent DNS flip
+cannot redirect the request. Use `redirects(0)` so a public URL can't
+30x-redirect to an internal host.
+
+## Resolver wiring pitfall (`PinnedResolver`)
+
+ureq 3 replaced v2's resolver closure with the `Resolver` trait. The agent
+MUST be built through `Agent::with_parts` to take a custom one:
+`Agent::new_with_config` silently keeps the default resolver, which would
+send the request to live DNS and quietly reopen the rebinding window this
+module exists to close. That failure is invisible — it has no symptom short
+of an actual attack — so it is pinned by the test
+`hardened_agent_connects_to_the_pinned_address_not_dns`.
+
+## Why that test is structured the way it is
+
+`resolve_and_guard` VALIDATES addresses; `hardened_agent` PINS them, so a
+hostname cannot re-resolve to an internal address between validation and
+connection. The validation half is well covered by other tests — but every
+one of those still passes if the pinned resolver is never consulted, because
+none of them makes a connection. Nothing else in the file proves the agent
+honours the pin, and a mis-wired resolver fails OPEN: the connection quietly
+falls back to live DNS and the rebinding window this module exists to close
+is reopened, with no visible symptom.
+
+The discriminator: pin the agent to a loopback listener the test owns, then
+ask it for a host that CANNOT resolve — `.test` is reserved by RFC 6761 and
+never resolves in the public DNS. Only a consulted resolver can turn that
+name into a connection; a fallback to live DNS fails instead. No network is
+touched, and `query` (whose guard blocks loopback by design) is not
+involved — this drives `hardened_agent` directly.
@@ -0,0 +1,13 @@
+# `keydb.cfg` path policy (`src/paths.rs`)
+
+Key-path policy belongs with the key sources (this crate), not the library:
+libfreemkv is handed a path and reads it. The CLI/app asks here for the
+list of locations to *search* (first existing wins) and for the single
+*default* location to write to (e.g. `update-keys`/save).
+
+freemkv is a portable, standalone binary: the `keydb.cfg` lives *next to*
+the executable — `<dir of current exe>/keydb.cfg` — and nowhere else. There
+is no OS-specific config-dir lookup (`%APPDATA%`, `%USERPROFILE%\.config`,
+`$XDG_CONFIG_HOME`, `$HOME/.config`). Drop the exe and its `keydb.cfg` in
+the same folder and it works. Callers needing a custom location pass
+`--keydb PATH`, which bypasses this module entirely.
@@ -1,24 +1,11 @@
 //! Pluggable AACS key sources for libfreemkv.
 //!
-//! libfreemkv owns the AACS crypto; this crate provides the published
-//! [`KeySource`] implementations that look a disc up and drive the boil-down
-//! primitives down to terminal Unit Keys:
-//!
-//! - [`KeydbSource`] — a local `keydb.cfg` (source #1).
-//! - [`OnlineSource`] — a remote key service (source #2).
-//!
-//! Applications (autorip, the `freemkv` CLI) choose and order the sources from
-//! their own config — the local-vs-online policy is just which impls they plug
-//! in — then resolve and hand the resulting key to `Disc::decrypt_with`.
-//!
-//! Each source resolves a disc's terminal **Unit Keys** in one shot via
-//! [`KeySource::get_unit_keys`], driving libfreemkv's boil-down crypto primitives for
-//! whatever level of material it holds. Compose several with [`MultiSource`] in
-//! the caller's chosen order. Reading the encrypted content-sample units a key
-//! server validates on, and applying the resolved keys against a disc, is
-//! decryption *mechanism* — it lives in the library
-//! (`libfreemkv::resolve_and_apply`, `libfreemkv::read_encrypted_units`), not
-//! here.
+//! libfreemkv owns the AACS crypto; this crate provides [`KeySource`] impls
+//! that look a disc up and drive the boil-down primitives to terminal Unit
+//! Keys: [`KeydbSource`] (local `keydb.cfg`) and [`OnlineSource`] (remote key
+//! service). Applications choose and order sources, then resolve and hand
+//! the key to `Disc::decrypt_with`; compose several with [`MultiSource`].
+//! See docs/lib-scope.md for the mechanism-vs-policy split with libfreemkv.

 mod keydb;
 /// The `keydb.cfg` parser (`KeyDb`, `DiscEntry`, …). Public: parsing the keydb
@@ -30,7 +17,10 @@ mod paths;

 pub use keydb::{KeydbSource, UpdateResult};
 pub use keydb_format::{DiscEntry, KeyDb};
-pub use online::{MIN_SAMPLE_UNITS, OnlineSource, validate_keyserver_url};
+pub use online::{
+    DecodeReachability, MIN_SAMPLE_UNITS, OnlineSource, take_last_decode_reachability,
+    validate_keyserver_url,
+};
 pub use paths::{default_keydb_path, existing_keydb_path, keydb_search_paths};

 // Re-exported for downstream convenience so apps need only depend on this crate
@@ -39,10 +29,9 @@ pub use libfreemkv::aacs::types::UnitKey;
 pub use libfreemkv::keysource::ResolveCtx;
 pub use libfreemkv::{DiscInputs, KeySource};

-/// VUK → the disc's terminal Unit Keys (positional index), one AES-ECB-decrypt
-/// per encrypted title key. Composes the raw `aacs::derive::decrypt_unit_key`
-/// primitive directly — replaces the removed libfreemkv `aacs::boil::uk_from_vuk`
-/// wrapper (that veneer is gone; libfreemkv owns only the AES).
+// VUK -> the disc's terminal Unit Keys (positional index), one AES-ECB-decrypt
+// per encrypted title key, via `aacs::derive::decrypt_unit_key`. Replaces the
+// removed libfreemkv `aacs::boil::uk_from_vuk` wrapper.
 pub(crate) fn uks_from_vuk(vuk: &[u8; 16], enc_title_keys: &[[u8; 16]]) -> Vec<UnitKey> {
    enc_title_keys
        .iter()
@@ -52,14 +41,14 @@ pub(crate) fn uks_from_vuk(vuk: &[u8; 16], enc_title_keys: &[[u8; 16]]) -> Vec<U
 }

 /// An ordered composition of key sources, driven as one.
-/// [`MultiSource::get_unit_keys`] tries each inner source in order and returns
-/// the first non-empty Unit Key set (and [`MultiSource::get_fmts_indexes`] does
-/// the same for the forensic set). **The caller supplies the list AND the
-/// order** — local-first `[Keydb,
-/// Online]`, online-first `[Online, Keydb]`, etc. —
-/// so the "which sources, in what order" policy lives entirely with the
-/// application, not the library. `MultiSource` is itself a [`KeySource`], so it
-/// nests and composes.
+///
+/// [`MultiSource::get_unit_keys`] tries each inner source in order and
+/// returns the first non-empty Unit Key set (and
+/// [`MultiSource::get_fmts_indexes`] does the same for the forensic set). The
+/// caller supplies the list AND the order — local-first `[Keydb, Online]`,
+/// online-first `[Online, Keydb]`, etc. `MultiSource` is itself a
+/// [`KeySource`], so it nests and composes. See docs/lib-scope.md for the
+/// `Err`-vs-`Ok(empty)` failure contract.
 pub struct MultiSource {
    sources: Vec<Box<dyn KeySource>>,
 }
@@ -71,35 +60,81 @@ impl MultiSource {
    }
 }

-impl KeySource for MultiSource {
-    /// Try each inner source in order; the FIRST to return a non-empty base Unit
-    /// Key set wins. An inner source that returns empty OR errors is treated as
-    /// "no key here" and the next is tried (a single source failure never blocks
-    /// the chain). All sources exhausted → empty.
-    fn get_unit_keys(&self, ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
-        for s in &self.sources {
-            if let Ok(uks) = s.get_unit_keys(ctx)
-                && !uks.is_empty()
-            {
-                return Ok(uks);
+// Drive `sources` in order, returning the first non-empty result and
+// preserving Ok/Err when nothing resolves. `get` selects the trait method so
+// the base and forensic paths share one implementation. See docs/lib-scope.md.
+fn first_non_empty(
+    sources: &[Box<dyn KeySource>],
+    get: impl Fn(&dyn KeySource, &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error>,
+    ctx: &dyn ResolveCtx,
+) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+    let mut first_failure: Option<libfreemkv::Error> = None;
+    for s in sources {
+        match get(s.as_ref(), ctx) {
+            Ok(uks) if !uks.is_empty() => return Ok(uks),
+            Ok(_) => {}
+            Err(e) => {
+                if first_failure.is_none() {
+                    first_failure = Some(e);
+                }
            }
        }
-        Ok(Vec::new())
+    }
+    match first_failure {
+        // At least one source could not answer, and nothing else had a key: the
+        // composition does NOT know that this disc has no key.
+        Some(e) => Err(e),
+        // Every source answered; none holds a key. The genuine miss.
+        None => Ok(Vec::new()),
+    }
+}
+
+impl KeySource for MultiSource {
+    // First inner source to return a non-empty base Unit Key set wins. All
+    // exhausted -> `Ok(empty)` if all answered, else the first failure (see
+    // [`MultiSource`]).
+    fn get_unit_keys(&self, ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+        first_non_empty(&self.sources, |s, c| s.get_unit_keys(c), ctx)
    }

-    /// Forensic-index counterpart: try each inner source's `get_fmts_indexes` in
-    /// the same order and return the first non-empty set. A source with no
-    /// forensic material (the keydb, via the trait default) contributes empty and
-    /// is skipped; on today's discs the online source answers.
-    fn get_fmts_indexes(&self, ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+    // De-conflated counterpart: first inner source with keys wins; else the
+    // richest miss survives composition (a MATCHED inner source beats a plain
+    // miss). Same Err/Ok failure contract as `get_unit_keys`.
+    fn resolve_unit_keys(
+        &self,
+        ctx: &dyn ResolveCtx,
+    ) -> Result<libfreemkv::keysource::UnitKeyResolution, libfreemkv::Error> {
+        let mut first_failure: Option<libfreemkv::Error> = None;
+        let mut matched: Option<libfreemkv::keysource::UnitKeyResolution> = None;
        for s in &self.sources {
-            if let Ok(uks) = s.get_fmts_indexes(ctx)
-                && !uks.is_empty()
-            {
-                return Ok(uks);
+            match s.resolve_unit_keys(ctx) {
+                Ok(r) if !r.keys.is_empty() => return Ok(r),
+                Ok(r) => {
+                    if r.matched && matched.is_none() {
+                        matched = Some(r);
+                    }
+                }
+                Err(e) => {
+                    if first_failure.is_none() {
+                        first_failure = Some(e);
+                    }
+                }
            }
        }
-        Ok(Vec::new())
+        if let Some(r) = matched {
+            return Ok(r);
+        }
+        match first_failure {
+            Some(e) => Err(e),
+            None => Ok(libfreemkv::keysource::UnitKeyResolution::default()),
+        }
+    }
+
+    // Forensic-index counterpart to `get_unit_keys`, same failure-preserving
+    // rule. A source with no forensic material (keydb, via the trait default)
+    // contributes empty and is skipped; today the online source answers.
+    fn get_fmts_indexes(&self, ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+        first_non_empty(&self.sources, |s, c| s.get_fmts_indexes(c), ctx)
    }

    /// UNION every inner source's host certs (filtered at the given MKB
@@ -116,3 +151,96 @@ impl KeySource for MultiSource {
        "multi"
    }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use libfreemkv::aacs::types::HostCert;
+
+    // A minimal KeySource that only supplies host certs — the sole MultiSource
+    // behaviour under test. It never resolves a unit key.
+    struct CertOnly {
+        certs: Vec<HostCert>,
+    }
+    impl KeySource for CertOnly {
+        fn get_unit_keys(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+            Ok(Vec::new())
+        }
+        fn host_certs(&self, _mkb: Option<u32>) -> Vec<HostCert> {
+            self.certs.clone()
+        }
+    }
+
+    // A host cert tagged with a distinct marker byte so a returned set can be
+    // identified exactly. Synthetic bytes only; no real key material.
+    fn cert(marker: u8) -> HostCert {
+        HostCert {
+            private_key: [marker; 20],
+            certificate: vec![marker; 92],
+            private_key_v2: None,
+            certificate_v2: None,
+        }
+    }
+
+    fn boxed(certs: Vec<HostCert>) -> Box<dyn KeySource> {
+        Box::new(CertOnly { certs }) as Box<dyn KeySource>
+    }
+
+    /// `MultiSource::host_certs` must UNION every inner source's certs. Without
+    /// this a composed source hides an inner source's cert from the OEM
+    /// cert-auth route — the gap the union closes.
+    #[test]
+    fn multi_source_host_certs_unions_every_inner_source() {
+        let multi = MultiSource::new(vec![
+            boxed(vec![cert(0x01)]),
+            boxed(vec![cert(0x02), cert(0x03)]),
+        ]);
+        let mut markers: Vec<u8> = multi
+            .host_certs(Some(50))
+            .iter()
+            .map(|c| c.certificate[0])
+            .collect();
+        markers.sort_unstable();
+        assert_eq!(
+            markers,
+            vec![0x01, 0x02, 0x03],
+            "certs from every inner source must be unioned"
+        );
+    }
+
+    /// With no inner source holding a cert, the union is empty (not an error).
+    #[test]
+    fn multi_source_host_certs_empty_when_no_source_has_one() {
+        let multi = MultiSource::new(vec![boxed(vec![]), boxed(vec![])]);
+        assert!(multi.host_certs(None).is_empty());
+    }
+
+    /// The `mkb` generation must reach each inner source so its OWN revocation
+    /// filter can act; a source that drops everything at a given generation is
+    /// honoured by the union.
+    #[test]
+    fn multi_source_host_certs_passes_mkb_through_to_inner_sources() {
+        struct GenAware;
+        impl KeySource for GenAware {
+            fn get_unit_keys(
+                &self,
+                _c: &dyn ResolveCtx,
+            ) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+                Ok(Vec::new())
+            }
+            fn host_certs(&self, mkb: Option<u32>) -> Vec<HostCert> {
+                match mkb {
+                    // Modelled on a cert revoked in MKBv72.
+                    Some(g) if g >= 72 => Vec::new(),
+                    _ => vec![cert(0xaa)],
+                }
+            }
+        }
+        let multi = MultiSource::new(vec![Box::new(GenAware) as Box<dyn KeySource>]);
+        assert_eq!(multi.host_certs(Some(50)).len(), 1, "usable below gen 72");
+        assert!(
+            multi.host_certs(Some(72)).is_empty(),
+            "the gen must reach the inner source's filter"
+        );
+    }
+}
@@ -1,16 +1,12 @@
 //! Where the `keydb.cfg` lives: local to the executable, local ONLY.
 //!
-//! Key-path policy belongs with the key sources (this crate), not the library:
-//! libfreemkv is handed a path and reads it. The CLI/app asks here for the
-//! list of locations to *search* (first existing wins) and for the single
-//! *default* location to write to (e.g. `update-keys`/save).
+//! Key-path policy belongs here (key sources), not in libfreemkv, which
+//! just reads a handed-in path. This module gives the *search* list (first
+//! existing wins) and the single *default* write location.
 //!
-//! freemkv is a portable, standalone binary: the `keydb.cfg` lives *next to*
-//! the executable — `<dir of current exe>/keydb.cfg` — and nowhere else. There
-//! is no OS-specific config-dir lookup (`%APPDATA%`, `%USERPROFILE%\.config`,
-//! `$XDG_CONFIG_HOME`, `$HOME/.config`). Drop the exe and its `keydb.cfg` in
-//! the same folder and it works. Callers needing a custom location pass
-//! `--keydb PATH`, which bypasses this module entirely.
+//! freemkv is portable: `keydb.cfg` lives next to the exe —
+//! `<dir of current exe>/keydb.cfg` — with no OS config-dir fallback.
+//! `--keydb PATH` bypasses this module. See docs/paths.md for rationale.

 use std::path::PathBuf;

@@ -1,15 +1,12 @@
 //! Fixture-based integration tests for the published key sources.
 //!
 //! These exercise the *public* surface of `freemkv-keysources` end-to-end —
-//! real files on disk, the real `KeyDb` parser from libfreemkv, and
-//! the `KeySource` trait (`get_unit_keys` over a `ResolveCtx`) the applications drive.
-//!
-//! Covered:
-//! - `KeydbSource`: terminal unit-key lookup by disc hash through a real
-//!   `keydb.cfg`; the exe-local path helpers; MKB-aware host-cert serving.
-//! - `OnlineSource`: SSRF/scheme validation and the unconfigured no-op.
-//! - `MultiSource`: caller-supplied ordering / precedence, host-cert UNION,
-//!   and nesting.
+//! real files on disk, the real `KeyDb` parser from libfreemkv, and the
+//! `KeySource` trait (`get_unit_keys` over a `ResolveCtx`) the applications
+//! drive. Covered: `KeydbSource` terminal unit-key lookup by disc hash
+//! (plus exe-local path helpers and MKB-aware host-cert serving);
+//! `OnlineSource` SSRF/scheme validation and the unconfigured no-op; and
+//! `MultiSource` ordering/precedence, host-cert UNION, and nesting.

 use std::io::Write;
 use std::path::{Path, PathBuf};
@@ -270,6 +267,15 @@ fn uk(b: u8) -> UnitKey {
    UnitKey::new(0, [b; 16])
 }

+/// `MultiSource` itself reports a fixed label, distinct from any inner
+/// source's own label — this is what a rip's source-attribution log shows
+/// when the composition, not one of its members, answered.
+#[test]
+fn multi_source_label_is_multi() {
+    let multi = MultiSource::new(vec![Box::new(ScriptedSource::new("A", Vec::new()))]);
+    assert_eq!(multi.label(), "multi");
+}
+
 #[test]
 fn multi_source_first_non_empty_wins_in_caller_order() {
    // Caller supplies [A, B]; A is non-empty so A's keys win.
@@ -362,6 +368,141 @@ fn multi_source_real_keydb_resolves_through_chain() {
    );
 }

+// ── MultiSource: a source that could not ANSWER is not a source that said no ─
+// See docs/multi-source-failure-collapse.md — the Ok/Err collapse incident
+// this section's tests exist to catch.
+
+/// A source that always fails, with a chosen error — the key-service outage.
+struct FailingSource {
+    err: fn() -> libfreemkv::Error,
+    label: &'static str,
+}
+
+impl KeySource for FailingSource {
+    fn get_unit_keys(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+        Err((self.err)())
+    }
+    fn get_fmts_indexes(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+        Err((self.err)())
+    }
+    fn label(&self) -> &'static str {
+        self.label
+    }
+}
+
+fn unavailable() -> libfreemkv::Error {
+    libfreemkv::Error::KeyServiceUnavailable
+}
+
+fn unauthorized() -> libfreemkv::Error {
+    libfreemkv::Error::KeyServiceUnauthorized
+}
+
+// See docs/multi-source-failure-collapse.md — must report FAILURE, not a
+// clean "no key", when no source holds a key and one could not answer.
+#[test]
+fn multi_source_reports_a_source_failure_instead_of_a_clean_no_key() {
+    let multi = MultiSource::new(vec![
+        Box::new(FailingSource {
+            err: unavailable,
+            label: "down",
+        }),
+        Box::new(ScriptedSource::new("empty", vec![])),
+    ]);
+    let err = multi
+        .get_unit_keys(&DiscInputsCtx::new(&inputs("x")))
+        .expect_err("a failed source must not collapse into a clean no-key");
+    assert_eq!(
+        err.code(),
+        libfreemkv::error::E_KEY_SERVICE_UNAVAILABLE,
+        "the composition must surface the service outage"
+    );
+    assert_ne!(
+        err.code(),
+        libfreemkv::error::E_NO_DISC_KEY,
+        "an outage must never be reported as 'this disc has no key'"
+    );
+}
+
+/// The forensic half carried the identical bug and is now driven through the
+/// same helper — pinned separately so a future edit cannot fix one and leave
+/// the other.
+#[test]
+fn multi_source_fmts_indexes_also_preserve_a_source_failure() {
+    let multi = MultiSource::new(vec![Box::new(FailingSource {
+        err: unavailable,
+        label: "down",
+    })]);
+    assert_eq!(
+        multi
+            .get_fmts_indexes(&DiscInputsCtx::new(&inputs("x")))
+            .expect_err("the forensic path must preserve the failure too")
+            .code(),
+        libfreemkv::error::E_KEY_SERVICE_UNAVAILABLE,
+    );
+}
+
+/// A source failure must NOT block the chain: a later source that actually has
+/// the key still wins outright. Pins the other half of the contract, so the fix
+/// cannot be over-applied into "any error aborts the composition".
+#[test]
+fn multi_source_failure_never_blocks_a_later_success() {
+    let multi = MultiSource::new(vec![
+        Box::new(FailingSource {
+            err: unavailable,
+            label: "down",
+        }),
+        Box::new(ScriptedSource::new("real", vec![uk(0xc1)])),
+    ]);
+    assert_eq!(
+        resolve(&multi, &inputs("x")),
+        vec![uk(0xc1)],
+        "a failing first source must not stop the second from resolving"
+    );
+}
+
+/// FIRST failure wins, matching libfreemkv's `source_failure` rule: the
+/// most-preferred source's reason is the one the operator is told about, in the
+/// same order the caller expressed a preference for successes.
+#[test]
+fn multi_source_reports_the_first_failure_not_the_last() {
+    let multi = MultiSource::new(vec![
+        Box::new(FailingSource {
+            err: unauthorized,
+            label: "bad-token",
+        }),
+        Box::new(FailingSource {
+            err: unavailable,
+            label: "down",
+        }),
+    ]);
+    assert_eq!(
+        multi
+            .get_unit_keys(&DiscInputsCtx::new(&inputs("x")))
+            .expect_err("both sources failed")
+            .code(),
+        libfreemkv::error::E_KEY_SERVICE_UNAUTHORIZED,
+        "the first source's failure is the one reported"
+    );
+}
+
+/// The contrast case: every source ANSWERED and none holds a key. That is the
+/// genuine miss, and `E7022` is then the truth — so the fix must not turn an
+/// honest empty into an error.
+#[test]
+fn multi_source_all_sources_answering_empty_is_still_a_clean_no_key() {
+    let multi = MultiSource::new(vec![
+        Box::new(ScriptedSource::new("a", vec![])),
+        Box::new(ScriptedSource::new("b", vec![])),
+    ]);
+    assert!(
+        multi
+            .get_unit_keys(&DiscInputsCtx::new(&inputs("x")))
+            .expect("every source answered; this is a genuine miss")
+            .is_empty()
+    );
+}
+
 /// The `Path`-typed constructor accepts a borrowed path.
 #[test]
 fn keydb_source_accepts_borrowed_path() {