Make Android Auto browse invalidation snapshot-based #69

Merged
alexander merged 14 commits from mcp/issue-10-auto-browse-snapshots into main 2026-09-20 12:35:00 +02:00
Owner

Fixes #10

Baseline

  • Refreshed main: 62342d4cafe846952e1a18d9d64f601d89d034aa
  • Branch: mcp/issue-10-auto-browse-snapshots
  • No open PR overlapped the Android Auto browse-invalidation files when this work started.

Architecture

Issue #10 now derives one immutable AutoBrowseSnapshot from one profile-bound accessible-library emission. The snapshot contains:

  • profile identity plus generation;
  • ordered opaque child identities per exposed parent;
  • the ordinary parents whose membership changes may trigger targeted invalidation;
  • the profile-scoped static parents that form the hard account boundary;
  • currently exposed dynamic Series/Author parent membership;
  • the accessible opaque book-id set needed to resolve profile-boundary counts without another complete library read.

AutoBrowseInvalidationTracker compares snapshots. Its comparison engine understands only parent identity and ordered child membership; it does not know what Library, Downloads, Recently added, Listen again or Discover mean.

Today's visible hierarchy is represented only by CurrentAutoBrowseSnapshotBuilder, so issue #65 can later replace the adapter with Continue → Series → Authors → Profiles without replacing the snapshot source or comparison/orchestration mechanism. This PR does not expose the #65 hierarchy.

One-snapshot orchestration

AutoBrowseSnapshotSource switches one observeAccessibleBooks(profileId) subscription with the active profile and derives every library-backed parent decision for a candidate sweep from that same emitted List<Book>.

The previous profile-switch loop called AutoLibrary.children(...) once per static/emitted parent, which could perform another complete accessible-library read for every remembered Series/Author node. That fan-out is removed.

The few profile-bound parents whose exact count is not a pure library-shape fact (recent root, Chapters and History) resolve their count only on the hard profile boundary. They use the already-derived accessible-id set plus their narrow repositories; they do not re-read the complete accessible library.

Ordinary invalidation semantics

For ordinary library mutations:

  • ordered opaque membership is compared, not child counts;
  • same-count/different-Series and same-count/different-Author membership is detected;
  • Continue ordering/membership changes are detected;
  • optional destination appearance/disappearance is detected;
  • emitted dynamic Series/Author parents are refreshed when their children change;
  • unrelated parents are not notified;
  • persistence changes that leave the exposed browse shape unchanged produce no notification.

Media3 is still notified with notifyChildrenChanged(parentId, childCount, null).

Profile boundary

A profile-generation change ignores shape/count equality and invalidates the union of:

  • the previous and current profile-scoped static parents; and
  • every dynamic Series/Author parent actually emitted by this process.

Old dynamic parents absent from the new profile are notified with zero children. Equal counts therefore cannot keep the previous profile's cached rows alive. The implementation observes the existing active-profile owner; it introduces no second profile-switch policy.

The shape fingerprint/logging uses opaque internal ids and counts only. Titles and private media metadata are not logged or required by the comparison engine.

Automated coverage

Focused regression coverage now pins:

  1. empty → non-empty root;
  2. non-empty → empty root;
  3. first/last optional destination;
  4. Series add/remove;
  5. Author add/remove;
  6. same-count/different-Series membership;
  7. same-count/different-Author membership;
  8. meaningful Continue membership/order change;
  9. non-exposed data mutation causes no invalidation;
  10. one candidate sweep uses one complete accessible-library subscription even with many parents;
  11. profile A → B invalidates all profile-scoped static + emitted dynamic parents;
  12. equal counts across profiles cannot suppress invalidation;
  13. old emitted dynamic parents are evicted;
  14. dynamic parents are ordinarily refreshed only after they were actually emitted;
  15. repeated active-profile identity does not create a new profile generation;
  16. the current adapter still exposes today's hierarchy rather than #65.

Verification

Forgejo's authoritative PR workflow requires an existing PR number to validate refs/pull/<n>/head, so the run is dispatched after this PR is created.

  • Focused tests: covered by the playback unit-test portion of the repository-required gate.
  • Full verifyDebug, warnings-as-errors, Detekt and ktlint: pending workflow dispatch.
  • Forced rerun: will be requested for the acceptance run even though no classpath/build files changed.
  • No dependency, toolchain or workflow changes are included.

This section will be updated with the exact passing Forgejo Actions run identifier before the PR is reported ready.

DHU / physical Android Auto acceptance still required

Automated tests prove what BookWave publishes, not that a host redraws it. docs/android-auto-browse-invalidation-acceptance.md records the remaining checks:

  • optional destination add/remove;
  • Series/Author add/remove and same-count replacement;
  • Continue refresh/no-churn cases;
  • profile A → B with old subscribed dynamic nodes;
  • refresh without a full Android Auto reconnect.

No DHU or physical-car acceptance is claimed in this PR. The owner plans to combine physical acceptance later with #34, #35, #36, #6 and #65.

Fixes #10 ## Baseline - Refreshed `main`: `62342d4cafe846952e1a18d9d64f601d89d034aa` - Branch: `mcp/issue-10-auto-browse-snapshots` - No open PR overlapped the Android Auto browse-invalidation files when this work started. ## Architecture Issue #10 now derives one immutable `AutoBrowseSnapshot` from one profile-bound accessible-library emission. The snapshot contains: - profile identity plus generation; - ordered opaque child identities per exposed parent; - the ordinary parents whose membership changes may trigger targeted invalidation; - the profile-scoped static parents that form the hard account boundary; - currently exposed dynamic Series/Author parent membership; - the accessible opaque book-id set needed to resolve profile-boundary counts without another complete library read. `AutoBrowseInvalidationTracker` compares snapshots. Its comparison engine understands only parent identity and ordered child membership; it does not know what Library, Downloads, Recently added, Listen again or Discover mean. Today's visible hierarchy is represented only by `CurrentAutoBrowseSnapshotBuilder`, so issue #65 can later replace the adapter with Continue → Series → Authors → Profiles without replacing the snapshot source or comparison/orchestration mechanism. This PR does **not** expose the #65 hierarchy. ## One-snapshot orchestration `AutoBrowseSnapshotSource` switches one `observeAccessibleBooks(profileId)` subscription with the active profile and derives every library-backed parent decision for a candidate sweep from that same emitted `List<Book>`. The previous profile-switch loop called `AutoLibrary.children(...)` once per static/emitted parent, which could perform another complete accessible-library read for every remembered Series/Author node. That fan-out is removed. The few profile-bound parents whose exact count is not a pure library-shape fact (recent root, Chapters and History) resolve their count only on the hard profile boundary. They use the already-derived accessible-id set plus their narrow repositories; they do not re-read the complete accessible library. ## Ordinary invalidation semantics For ordinary library mutations: - ordered opaque membership is compared, not child counts; - same-count/different-Series and same-count/different-Author membership is detected; - Continue ordering/membership changes are detected; - optional destination appearance/disappearance is detected; - emitted dynamic Series/Author parents are refreshed when their children change; - unrelated parents are not notified; - persistence changes that leave the exposed browse shape unchanged produce no notification. Media3 is still notified with `notifyChildrenChanged(parentId, childCount, null)`. ## Profile boundary A profile-generation change ignores shape/count equality and invalidates the union of: - the previous and current profile-scoped static parents; and - every dynamic Series/Author parent actually emitted by this process. Old dynamic parents absent from the new profile are notified with zero children. Equal counts therefore cannot keep the previous profile's cached rows alive. The implementation observes the existing active-profile owner; it introduces no second profile-switch policy. The shape fingerprint/logging uses opaque internal ids and counts only. Titles and private media metadata are not logged or required by the comparison engine. ## Automated coverage Focused regression coverage now pins: 1. empty → non-empty root; 2. non-empty → empty root; 3. first/last optional destination; 4. Series add/remove; 5. Author add/remove; 6. same-count/different-Series membership; 7. same-count/different-Author membership; 8. meaningful Continue membership/order change; 9. non-exposed data mutation causes no invalidation; 10. one candidate sweep uses one complete accessible-library subscription even with many parents; 11. profile A → B invalidates all profile-scoped static + emitted dynamic parents; 12. equal counts across profiles cannot suppress invalidation; 13. old emitted dynamic parents are evicted; 14. dynamic parents are ordinarily refreshed only after they were actually emitted; 15. repeated active-profile identity does not create a new profile generation; 16. the current adapter still exposes today's hierarchy rather than #65. ## Verification Forgejo's authoritative PR workflow requires an existing PR number to validate `refs/pull/<n>/head`, so the run is dispatched after this PR is created. - Focused tests: covered by the playback unit-test portion of the repository-required gate. - Full `verifyDebug`, warnings-as-errors, Detekt and ktlint: **pending workflow dispatch**. - Forced rerun: will be requested for the acceptance run even though no classpath/build files changed. - No dependency, toolchain or workflow changes are included. This section will be updated with the exact passing Forgejo Actions run identifier before the PR is reported ready. ## DHU / physical Android Auto acceptance still required Automated tests prove what BookWave publishes, not that a host redraws it. `docs/android-auto-browse-invalidation-acceptance.md` records the remaining checks: - optional destination add/remove; - Series/Author add/remove and same-count replacement; - Continue refresh/no-churn cases; - profile A → B with old subscribed dynamic nodes; - refresh without a full Android Auto reconnect. No DHU or physical-car acceptance is claimed in this PR. The owner plans to combine physical acceptance later with #34, #35, #36, #6 and #65.
alexander deleted branch mcp/issue-10-auto-browse-snapshots 2026-09-20 12:35:00 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
alexander/Audiobookshelf-Manager-Claude!69
No description provided.