Hydrate recently active books before full library expansion #57

Merged
alexander merged 11 commits from mcp/issue-41-recent-book-hotset into main 2026-09-19 10:13:26 +02:00
Owner

Summary

Implements #41 inside the existing library refresh architecture.

  • reads exactly one captured listening-session page (page=0&itemsPerPage=10) as newest-first priority hints;
  • deduplicates book IDs while preserving server order;
  • admits a candidate only when the active profile's actual catalogue batch lists it, preserving item/tag visibility as the permission evidence;
  • hydrates admitted missing/stale candidates through the existing LibraryApi.fetchBook(...) boundary;
  • writes metadata through LibrarySnapshotWriter and routes fetched progress through the existing LibraryRepository.writeProgress(...) conflict boundary;
  • mutates only the refresh-local cache facts so the later ordinary expansion skips a candidate when the stored server revision proves it current;
  • treats hot-set/history failures as best-effort and continues the authoritative full refresh.

No new Audiobookshelf endpoint or contract is introduced. Listening-session timestamps/positions are not used as progress. Foreground realtime ownership from #40 is unchanged.

Automated proof

Adds focused repository/Room coverage for:

  • one bounded history page;
  • recency-preserving deduplication and at most one targeted fetch per candidate;
  • already-current candidate skip;
  • catalogue-based library/item-tag admission;
  • inaccessible candidates never written;
  • locally unsynced progress surviving targeted hydration and final refresh;
  • listening-history failure isolation;
  • targeted-hydration failure fallback to ordinary bulk expansion;
  • no redundant later expansion after a revision-matched hot hydration;
  • useful Room state becoming available before bulk expansion.

Manual device acceptance still required

Use a realistically large Audiobookshelf library:

  1. Start BookWave once so the library has an existing cache, then background it.
  2. From another Audiobookshelf client, start or advance a different book that is not already the obvious locally remembered/active BookWave book.
  3. Foreground BookWave.
  4. Observe the Continue/library state and verify that remotely recent book becomes current and usable materially before the full expanded-item sweep finishes.
  5. Open/use the book to confirm its expanded metadata/playability is available.
  6. Let the refresh finish and verify the full library still reconciles normally: no inaccessible/tag-filtered books appear, no unrelated books disappear, and sync reaches its normal completed state.
  7. If the device has a locally unsynced position for a candidate, verify that local position is not rewound by the refresh.

Physical-device acceptance has not been performed in this PR.

Closes #41

## Summary Implements #41 inside the existing library refresh architecture. - reads exactly one captured listening-session page (`page=0&itemsPerPage=10`) as newest-first priority hints; - deduplicates book IDs while preserving server order; - admits a candidate only when the active profile's actual catalogue batch lists it, preserving item/tag visibility as the permission evidence; - hydrates admitted missing/stale candidates through the existing `LibraryApi.fetchBook(...)` boundary; - writes metadata through `LibrarySnapshotWriter` and routes fetched progress through the existing `LibraryRepository.writeProgress(...)` conflict boundary; - mutates only the refresh-local cache facts so the later ordinary expansion skips a candidate when the stored server revision proves it current; - treats hot-set/history failures as best-effort and continues the authoritative full refresh. No new Audiobookshelf endpoint or contract is introduced. Listening-session timestamps/positions are not used as progress. Foreground realtime ownership from #40 is unchanged. ## Automated proof Adds focused repository/Room coverage for: - one bounded history page; - recency-preserving deduplication and at most one targeted fetch per candidate; - already-current candidate skip; - catalogue-based library/item-tag admission; - inaccessible candidates never written; - locally unsynced progress surviving targeted hydration and final refresh; - listening-history failure isolation; - targeted-hydration failure fallback to ordinary bulk expansion; - no redundant later expansion after a revision-matched hot hydration; - useful Room state becoming available before bulk expansion. ## Manual device acceptance still required Use a realistically large Audiobookshelf library: 1. Start BookWave once so the library has an existing cache, then background it. 2. From another Audiobookshelf client, start or advance a different book that is not already the obvious locally remembered/active BookWave book. 3. Foreground BookWave. 4. Observe the Continue/library state and verify that remotely recent book becomes current and usable materially before the full expanded-item sweep finishes. 5. Open/use the book to confirm its expanded metadata/playability is available. 6. Let the refresh finish and verify the full library still reconciles normally: no inaccessible/tag-filtered books appear, no unrelated books disappear, and sync reaches its normal completed state. 7. If the device has a locally unsynced position for a candidate, verify that local position is not rewound by the refresh. Physical-device acceptance has **not** been performed in this PR. Closes #41
alexander force-pushed mcp/issue-41-recent-book-hotset from e3694b5abf to 2bbf22a425 2026-09-19 10:12:50 +02:00 Compare
alexander deleted branch mcp/issue-41-recent-book-hotset 2026-09-19 10:13:26 +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!57
No description provided.