# Catalog cache boundary `CachedMusicService` is an in-memory decorator around `MusicService`. It belongs between the app's feature state and the protocol worker; the worker still owns request construction, response parsing, sessions, and playback. ## What is cached Only parsed domain values from first catalog pages are stored: | Resource | TTL | | --- | ---: | | Search | 60 seconds | | Home | 120 seconds | | Playlists, playlist tracks, and album tracks | 300 seconds | The cache is bounded to 64 entries and evicts the least recently used entry. Pagination tokens and continuation results are kept only as part of the in-memory request/page flow. They are never persisted. Errors are never cached. The old array methods (`search`, `playlists`, and `tracks(in:)`) use the corresponding cached first page. An array-only fake therefore remains compatible and produces a page with no continuation. Home and album tracks have no old array capability; an array-only base reports `CachedMusicServiceError.unsupported` instead of fabricating content. ## Session and concurrency rules The actor assigns a session generation to catalog work. `setSession(_:)` first clears pages and invalidates all catalog tasks, then installs its successor transition before waiting for an earlier transition; the successor forwards the session only after that predecessor completes. Catalog requests are rejected while the full transition chain is in progress. A late completion from an older generation or a replaced resource task is rejected and cannot publish or evict newer data. The same rules apply to `clearCatalogCache()` and `.reload`. Identical requests share one in-flight catalog task. Each in-flight task tracks its waiters. A waiter uses a cancellation handler of its own: cancelling one caller detaches only that waiter and does not cancel the shared task or another caller's wait. When the last waiter detaches, the task is cancelled and removed before a late result can publish; a later caller starts a fresh request. Playback, stream resolution, refresh, proof-related work, credentials, visitor data, and expiring media URLs bypass the cache entirely. The clock is injectable through `CachedMusicService(base:clock:)` (or `base:now:`) so expiry and race tests do not sleep for a TTL.