[BW-AUTO-01] Make Android Auto browse invalidation shape-aware and snapshot-based #10

Closed
opened 2026-09-18 08:44:31 +02:00 by alexander · 0 comments
Owner

Migrated from GitHub issue #99. Forgejo issue: #10. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links.

Classification

Active follow-up from GitHub PR #78. Canonical roadmap item BW-AUTO-01.

Problem / opportunity

PlaybackService.observeBrowseTreeInvalidation currently asks AutoLibrary for browsable-parent children separately during invalidation. GitHub PR #78 strengthens profile-boundary invalidation and remembers emitted dynamic series/author nodes, but ordinary library mutations can change the actual Android Auto browse shape: empty/non-empty transitions, first/last download, first/last series/author, and shelf availability.

Naively invalidating on every persistence write would be correct but noisy. Recomputing each parent from an independent complete repository read also produces avoidable work and inconsistent counts within one sweep.

User value

The car updates promptly when meaningful library/navigation shape changes, never keeps another profile's cached titles, and does not turn a routine library mutation into N complete reads for N emitted series/author nodes.

Scope

Derive the actual exposed browse-tree shape from one profile-bound library snapshot and make that the invalidation fact.

  • Read relevant accessible library/shelf state once per candidate change/invalidation sweep.
  • Derive a compact immutable shape/fingerprint containing:
    • empty vs non-empty root state;
    • static discovery-section availability;
    • dynamic series parents;
    • dynamic author parents;
    • Downloads availability;
    • Recently added / Listen again / Discover availability;
    • Continue availability/contents as needed by Media3 invalidation semantics;
    • child membership/count information needed to decide which parents are stale.
  • Compare previous published shape with the new shape.
  • Notify only parents whose exposed children changed; do not rely on count-only comparison when membership can change with the same count.
  • Use the same snapshot for every child count/decision in one sweep.
  • Preserve a hard profile boundary: a profile switch must invalidate all previously emitted dynamic parents required to evict the old profile's cached tree.
  • Avoid N full library reads for N remembered dynamic parents.

Explicitly out of scope

  • Do not redesign ADR-0029's stable Android Auto root/product structure.
  • Do not add car-specific resume freshness; GitHub PR #93 owns resume freshness for every Play surface.
  • Do not change routing behavior.
  • Do not broaden GitHub #78 while it is still under test; this is its follow-up.

Dependencies

  • GitHub PR #78 — Android Auto/routing finalization and ADR-0029 must land first or this issue must be rebased onto its final browse contract.

Architecture seams affected

  • AutoLibrary browse-tree derivation.
  • PlaybackService / MediaLibrarySession.notifyChildrenChanged orchestration.
  • LibraryRepository / shelf derivation reads.
  • Profile-switch invalidation boundary.

Server / API assumptions

No server API change. The shape is derived from BookWave's current grant-filtered local library/cache. Server refresh/realtime work may cause a new snapshot; it does not directly own Android Auto invalidation policy.

Storage / migration implications

None. The browse shape is derived state, not a new persisted source of truth.

Privacy / security

Profile switching is a privacy boundary, not merely a stale-UI concern. Old-profile dynamic node IDs/titles must be invalidated even if the newly selected profile happens to have the same child counts.

Do not include media titles or raw IDs in diagnostics beyond existing privacy rules simply to fingerprint the shape; stable internal opaque keys/counts/sets are sufficient.

Automated-test level

Pure/JVM/Robolectric tests should cover:

  • library empty -> non-empty and non-empty -> empty;
  • first/last downloaded book adds/removes Downloads;
  • series addition/removal, including dynamic parent with same child count but different membership;
  • author addition/removal;
  • Recently added availability;
  • Listen again availability;
  • Discover availability;
  • Continue availability/meaningful membership change;
  • profile switch invalidates all relevant static + emitted dynamic parents;
  • one orchestration sweep uses one library snapshot rather than repeated complete reads;
  • a mutation that does not change exposed tree shape does not cause unnecessary invalidation.

Device / platform acceptance

A JVM test proves shape derivation and which notifications BookWave sends. It does not prove a head unit refreshes the rendered tree.

Verify on DHU and, where practical, the real head unit:

  • add/remove a download and see Downloads appear/disappear without reconnecting;
  • change library contents enough to add/remove series/author nodes;
  • switch profile and confirm old account titles disappear;
  • confirm the host refreshes the relevant nodes without a full reconnect.

Estimated effort

Medium.

Implementation risk

Medium. Under-invalidation leaks stale/profile content; over-invalidation causes unnecessary database/controller churn.

After GitHub #78. Independent of widgets/iOS and does not need to wait for appearance/settings PRs.

Acceptance criteria

  • One candidate invalidation sweep derives from one consistent library snapshot.
  • Relevant exposed-tree membership changes are detected even when child counts remain equal.
  • Only affected nodes are invalidated for ordinary library changes.
  • Profile switch remains a hard invalidation boundary for all previously emitted nodes.
  • No N-complete-read fan-out for N remembered series/author nodes.
  • DHU/real-car acceptance records host behavior separately from JVM evidence.
  • Origin: GitHub PR #78 review follow-up
  • Canonical roadmap: BW-AUTO-01
> Migrated from [GitHub issue #99](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/99). Forgejo issue: #10. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links. ## Classification Active follow-up from [GitHub PR #78](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/78). Canonical roadmap item **BW-AUTO-01**. ## Problem / opportunity `PlaybackService.observeBrowseTreeInvalidation` currently asks `AutoLibrary` for browsable-parent children separately during invalidation. [GitHub PR #78](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/78) strengthens profile-boundary invalidation and remembers emitted dynamic series/author nodes, but ordinary library mutations can change the actual Android Auto browse shape: empty/non-empty transitions, first/last download, first/last series/author, and shelf availability. Naively invalidating on every persistence write would be correct but noisy. Recomputing each parent from an independent complete repository read also produces avoidable work and inconsistent counts within one sweep. ## User value The car updates promptly when meaningful library/navigation shape changes, never keeps another profile's cached titles, and does not turn a routine library mutation into N complete reads for N emitted series/author nodes. ## Scope Derive the **actual exposed browse-tree shape from one profile-bound library snapshot** and make that the invalidation fact. - Read relevant accessible library/shelf state once per candidate change/invalidation sweep. - Derive a compact immutable shape/fingerprint containing: - empty vs non-empty root state; - static discovery-section availability; - dynamic series parents; - dynamic author parents; - Downloads availability; - Recently added / Listen again / Discover availability; - Continue availability/contents as needed by Media3 invalidation semantics; - child membership/count information needed to decide which parents are stale. - Compare previous published shape with the new shape. - Notify only parents whose exposed children changed; do not rely on count-only comparison when membership can change with the same count. - Use the same snapshot for every child count/decision in one sweep. - Preserve a hard profile boundary: a profile switch must invalidate all previously emitted dynamic parents required to evict the old profile's cached tree. - Avoid N full library reads for N remembered dynamic parents. ## Explicitly out of scope - Do not redesign ADR-0029's stable Android Auto root/product structure. - Do not add car-specific resume freshness; [GitHub PR #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/93) owns resume freshness for every Play surface. - Do not change routing behavior. - Do not broaden [GitHub #78](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/78) while it is still under test; this is its follow-up. ## Dependencies - **[GitHub PR #78](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/78)** — Android Auto/routing finalization and ADR-0029 must land first or this issue must be rebased onto its final browse contract. ## Architecture seams affected - `AutoLibrary` browse-tree derivation. - `PlaybackService` / `MediaLibrarySession.notifyChildrenChanged` orchestration. - `LibraryRepository` / shelf derivation reads. - Profile-switch invalidation boundary. ## Server / API assumptions No server API change. The shape is derived from BookWave's current grant-filtered local library/cache. Server refresh/realtime work may cause a new snapshot; it does not directly own Android Auto invalidation policy. ## Storage / migration implications None. The browse shape is derived state, not a new persisted source of truth. ## Privacy / security Profile switching is a privacy boundary, not merely a stale-UI concern. Old-profile dynamic node IDs/titles must be invalidated even if the newly selected profile happens to have the same child counts. Do not include media titles or raw IDs in diagnostics beyond existing privacy rules simply to fingerprint the shape; stable internal opaque keys/counts/sets are sufficient. ## Automated-test level Pure/JVM/Robolectric tests should cover: - library empty -> non-empty and non-empty -> empty; - first/last downloaded book adds/removes Downloads; - series addition/removal, including dynamic parent with same child count but different membership; - author addition/removal; - Recently added availability; - Listen again availability; - Discover availability; - Continue availability/meaningful membership change; - profile switch invalidates all relevant static + emitted dynamic parents; - one orchestration sweep uses one library snapshot rather than repeated complete reads; - a mutation that does not change exposed tree shape does not cause unnecessary invalidation. ## Device / platform acceptance A JVM test proves shape derivation and which notifications BookWave sends. It does **not** prove a head unit refreshes the rendered tree. Verify on DHU and, where practical, the real head unit: - add/remove a download and see Downloads appear/disappear without reconnecting; - change library contents enough to add/remove series/author nodes; - switch profile and confirm old account titles disappear; - confirm the host refreshes the relevant nodes without a full reconnect. ## Estimated effort Medium. ## Implementation risk Medium. Under-invalidation leaks stale/profile content; over-invalidation causes unnecessary database/controller churn. ## Recommended sequence After [GitHub #78](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/78). Independent of widgets/iOS and does not need to wait for appearance/settings PRs. ## Acceptance criteria - One candidate invalidation sweep derives from one consistent library snapshot. - Relevant exposed-tree membership changes are detected even when child counts remain equal. - Only affected nodes are invalidated for ordinary library changes. - Profile switch remains a hard invalidation boundary for all previously emitted nodes. - No N-complete-read fan-out for N remembered series/author nodes. - DHU/real-car acceptance records host behavior separately from JVM evidence. ## Links - Origin: [GitHub PR #78](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/78) review follow-up - Canonical roadmap: BW-AUTO-01
Sign in to join this conversation.
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#10
No description provided.