feat(offline): #427 S2(+S3) — two-bucket cache model

Replaces the single 5GB capBytes with independent Liked + Rolling
budgets (5GB each default). Bucket = liked-ness, NOT CacheSource:
a cached track currently in the liked set is charged to / evicted
under Liked; everything else is Rolling. Storage-only dedup — it
never filters playback (S4's offline lists query the whole index).

- db.dart: schema 8→9, AudioCacheIndex.lastPlayedAt (real play
  recency for S4 + rolling LRU; migration backfills to cachedAt).
  drift codegen run.
- cache_settings: likedCapBytes + rollingCapBytes (+ setters); old
  cache_cap_bytes key dropped, defaults reapply (not data loss).
- audio_cache_manager: touch(); bucketUsage() counts orphan
  partials (LockCaching files never indexed) as Rolling so the cap
  truly bounds disk; evictBuckets() drains non-liked LRU then
  sweeps orphans, Liked only by its own (large) cap — normal use
  never evicts the user's liked library.
- prefetcher → evictBuckets with the cached liked set.
- storage_section: two cap selectors + per-bucket usage (folds in
  S3 to avoid a broken intermediate).
- Explicit Download dropped: removed album + playlist Download
  buttons, autoPlaylist pins, now-unused imports.
- Tests updated/compiled (drift-cohort tests are CI-skipped).

High blast radius (eviction deletes files) — liked-protective by
design; needs operator device-check before "done".

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

flutter_client/lib/cache/audio_cache_manager.dart

@@ -8,15 +8,20 @@ import 'package:path_provider/path_provider.dart';
 import '../library/library_providers.dart' show dioProvider;
 import 'db.dart';
 
+/// Per-bucket cache usage (#427 S2). Rolling includes orphan files —
+/// partials written by LockCachingAudioSource that were never indexed
+/// (skip-before-fully-buffered) — so the rolling cap actually bounds
+/// disk.
+typedef BucketUsage = ({int liked, int rolling});
+
 /// Owns the audio cache directory + drift index.
-/// API:
-///   - isCached(trackId)
-///   - pathFor(trackId)
-///   - pin(trackId, source) — downloads + indexes
-///   - unpin(trackId)
-///   - evict(targetBytes) — tiered LRU
-///   - usageBytes()
-///   - clearAll()
+///
+/// #427 S2: two storage buckets keyed by liked-ness, not by
+/// CacheSource. A cached track currently in the user's liked set is
+/// charged to (and evicted under) the Liked budget; everything else
+/// is Rolling. This dedup is storage/eviction-only — it never filters
+/// what the offline surfaces can play (S4). `CacheSource` is retained
+/// on the API for callers but is now informational.
 class AudioCacheManager {
   AudioCacheManager({
     required AppDb db,
@@ -37,7 +42,6 @@ class AudioCacheManager {
     return d.path;
   }
 
-  /// True if the trackId has a complete file on disk.
   Future<bool> isCached(String trackId) async {
     final row = await (_db.select(_db.audioCacheIndex)
           ..where((t) => t.trackId.equals(trackId)))
@@ -46,7 +50,6 @@ class AudioCacheManager {
     return File(row.path).existsSync();
   }
 
-  /// Returns the local file path if cached, else null.
   Future<String?> pathFor(String trackId) async {
     final row = await (_db.select(_db.audioCacheIndex)
           ..where((t) => t.trackId.equals(trackId)))
@@ -55,12 +58,14 @@ class AudioCacheManager {
     return File(row.path).existsSync() ? row.path : null;
   }
 
-  /// Downloads the track's stream to disk and indexes it. Idempotent —
-  /// returns the existing path if already cached.
+  /// Downloads the track's stream to disk and indexes it. Idempotent.
+  /// lastPlayedAt is set now — pinning is play-intent.
   Future<String?> pin(String trackId, {required CacheSource source}) async {
     final existing = await pathFor(trackId);
-    if (existing != null) return existing;
-
+    if (existing != null) {
+      await touch(trackId);
+      return existing;
+    }
     final dir = await _tracksDir();
     final path = '$dir/$trackId.mp3';
     final dio = await _dioFactory();
@@ -78,16 +83,15 @@ class AudioCacheManager {
             path: path,
             sizeBytes: size,
             source: source,
+            lastPlayedAt: Value(DateTime.now()),
           ),
         );
     return path;
   }
 
-  /// Registers a file already on disk in the cache index. Intended for
-  /// the streaming path (LockCachingAudioSource) which writes the file
-  /// itself; we need an index row so eviction can find and delete it
-  /// when usage exceeds the cap. `source` defaults to incidental so
-  /// stream-cached tracks are first to be evicted.
+  /// Registers a file LockCachingAudioSource wrote itself. Called
+  /// once a track is fully buffered; it's being played, so stamp
+  /// lastPlayedAt.
   Future<void> registerStreamCache(
     String trackId,
     String path,
@@ -100,11 +104,20 @@ class AudioCacheManager {
             path: path,
             sizeBytes: sizeBytes,
             source: source,
+            lastPlayedAt: Value(DateTime.now()),
           ),
         );
   }
 
-  /// Removes a track from the index AND deletes the file.
+  /// Bumps lastPlayedAt for an already-indexed track so the rolling
+  /// LRU + the offline "Recently played" view reflect real plays
+  /// (not just download time). No-op if not indexed.
+  Future<void> touch(String trackId) async {
+    await (_db.update(_db.audioCacheIndex)
+          ..where((t) => t.trackId.equals(trackId)))
+        .write(AudioCacheIndexCompanion(lastPlayedAt: Value(DateTime.now())));
+  }
+
   Future<void> unpin(String trackId) async {
     final row = await (_db.select(_db.audioCacheIndex)
           ..where((t) => t.trackId.equals(trackId)))
@@ -117,66 +130,150 @@ class AudioCacheManager {
         .go();
   }
 
-  /// Total bytes used by the cache. Walks the cache directory directly
-  /// instead of summing the index, because the streaming-as-you-play
-  /// path (audio_handler's LockCachingAudioSource) writes files
-  /// without registering an index row. The index sum would always
-  /// understate (often to zero) for users who only stream.
+  /// Total bytes on disk (directory walk — authoritative; catches
+  /// orphan partials the index misses).
   Future<int> usageBytes() async {
     final dir = Directory(await _tracksDir());
     if (!await dir.exists()) return 0;
     var total = 0;
-    await for (final entity in dir.list(followLinks: false)) {
-      if (entity is File) {
+    await for (final e in dir.list(followLinks: false)) {
+      if (e is File) {
         try {
-          total += await entity.length();
-        } catch (_) {
-          // Race against concurrent writes / deletes — just skip.
-        }
+          total += await e.length();
+        } catch (_) {}
       }
     }
     return total;
   }
 
-  /// Evicts files until usage ≤ targetBytes. Eviction order:
-  /// incidental → autoPrefetch → autoPlaylist → autoLiked.
-  /// `manual` never evicts via this path; only clearAll() removes them.
-  Future<void> evict({required int targetBytes}) async {
-    final used = await usageBytes();
-    if (used <= targetBytes) return;
-    final order = [
-      CacheSource.incidental,
-      CacheSource.autoPrefetch,
-      CacheSource.autoPlaylist,
-      CacheSource.autoLiked,
-    ];
-    int remaining = used - targetBytes;
-    for (final src in order) {
-      if (remaining <= 0) break;
-      final rows = await (_db.select(_db.audioCacheIndex)
-            ..where((t) => t.source.equalsValue(src))
-            ..orderBy([(t) => OrderingTerm.asc(t.cachedAt)]))
+  /// Bytes per bucket. Indexed rows split by liked-ness; on-disk
+  /// files with no index row (orphan partials) count as Rolling so
+  /// the rolling cap genuinely bounds disk.
+  Future<BucketUsage> bucketUsage(Set<String> liked) async {
+    final rows = await _db.select(_db.audioCacheIndex).get();
+    final indexed = <String>{};
+    var likedB = 0;
+    var rollingB = 0;
+    for (final r in rows) {
+      indexed.add(r.trackId);
+      if (liked.contains(r.trackId)) {
+        likedB += r.sizeBytes;
+      } else {
+        rollingB += r.sizeBytes;
+      }
+    }
+    final dir = Directory(await _tracksDir());
+    if (await dir.exists()) {
+      await for (final e in dir.list(followLinks: false)) {
+        if (e is! File) continue;
+        final name = e.uri.pathSegments.last;
+        final id = name.endsWith('.mp3')
+            ? name.substring(0, name.length - 4)
+            : name;
+        if (indexed.contains(id)) continue;
+        try {
+          rollingB += await e.length();
+        } catch (_) {}
+      }
+    }
+    return (liked: likedB, rolling: rollingB);
+  }
+
+  /// Enforces both budgets independently (0 = unlimited).
+  ///
+  /// Rolling: evict non-liked indexed rows LRU (oldest lastPlayedAt
+  /// /cachedAt first), then sweep orphan files oldest-by-mtime, until
+  /// rolling usage ≤ rollingCap. Liked: evict liked indexed rows LRU
+  /// until ≤ likedCap. Liked is only ever touched by its own (large)
+  /// cap, so normal use never evicts the user's liked library.
+  Future<void> evictBuckets({
+    required int likedCap,
+    required int rollingCap,
+    required Set<String> liked,
+  }) async {
+    final usage = await bucketUsage(liked);
+
+    if (rollingCap > 0 && usage.rolling > rollingCap) {
+      var over = usage.rolling - rollingCap;
+      final rolling = await (_db.select(_db.audioCacheIndex)
+            ..where((t) => t.trackId.isNotIn(liked.toList()))
+            ..orderBy([
+              (t) => OrderingTerm.asc(t.lastPlayedAt),
+              (t) => OrderingTerm.asc(t.cachedAt),
+            ]))
           .get();
-      for (final row in rows) {
-        if (remaining <= 0) break;
-        final f = File(row.path);
+      for (final r in rolling) {
+        if (over <= 0) break;
+        final f = File(r.path);
         if (f.existsSync()) await f.delete();
         await (_db.delete(_db.audioCacheIndex)
-              ..where((t) => t.trackId.equals(row.trackId)))
+              ..where((t) => t.trackId.equals(r.trackId)))
             .go();
-        remaining -= row.sizeBytes;
+        over -= r.sizeBytes;
+      }
+      if (over > 0) await _sweepOrphans(over);
+    }
+
+    if (likedCap > 0 && usage.liked > likedCap) {
+      var over = usage.liked - likedCap;
+      final likedRows = await (_db.select(_db.audioCacheIndex)
+            ..where((t) => t.trackId.isIn(liked.toList()))
+            ..orderBy([
+              (t) => OrderingTerm.asc(t.lastPlayedAt),
+              (t) => OrderingTerm.asc(t.cachedAt),
+            ]))
+          .get();
+      for (final r in likedRows) {
+        if (over <= 0) break;
+        final f = File(r.path);
+        if (f.existsSync()) await f.delete();
+        await (_db.delete(_db.audioCacheIndex)
+              ..where((t) => t.trackId.equals(r.trackId)))
+            .go();
+        over -= r.sizeBytes;
       }
     }
   }
 
-  /// Clears EVERY row + EVERY file. Wired to the operator's "Clear cache"
-  /// button — `manual` source rows are removed here but only here.
+  /// Deletes orphan files (on disk, no index row) oldest-mtime-first
+  /// until `over` bytes are reclaimed. These are unindexed partials,
+  /// always Rolling, always evict-first.
+  Future<void> _sweepOrphans(int over) async {
+    final indexed = {
+      for (final r in await _db.select(_db.audioCacheIndex).get()) r.trackId
+    };
+    final dir = Directory(await _tracksDir());
+    if (!await dir.exists()) return;
+    final orphans = <({File f, int size, DateTime mtime})>[];
+    await for (final e in dir.list(followLinks: false)) {
+      if (e is! File) continue;
+      final name = e.uri.pathSegments.last;
+      final id =
+          name.endsWith('.mp3') ? name.substring(0, name.length - 4) : name;
+      if (indexed.contains(id)) continue;
+      try {
+        final st = e.statSync();
+        orphans.add((f: e, size: st.size, mtime: st.modified));
+      } catch (_) {}
+    }
+    orphans.sort((a, b) => a.mtime.compareTo(b.mtime));
+    var remaining = over;
+    for (final o in orphans) {
+      if (remaining <= 0) break;
+      try {
+        await o.f.delete();
+        remaining -= o.size;
+      } catch (_) {}
+    }
+  }
+
+  /// Clears EVERY row + EVERY file. Wired to "Clear cache".
   Future<void> clearAll() async {
     final dir = await _tracksDir();
     final d = Directory(dir);
     if (d.existsSync()) {
-      for (final entity in d.listSync()) {
-        if (entity is File) await entity.delete();
+      for (final e in d.listSync()) {
+        if (e is File) await e.delete();
       }
     }
     await _db.delete(_db.audioCacheIndex).go();

flutter_client/lib/cache/cache_settings_provider.dart

@@ -3,17 +3,29 @@ import 'package:flutter_secure_storage/flutter_secure_storage.dart';
 
 import '../auth/auth_provider.dart' show secureStorageProvider;
 
-/// Operator-tunable cache settings (#357 plan B). Persisted via
+/// Operator-tunable cache settings. Persisted via
 /// flutter_secure_storage on the same device.
+///
+/// #427 S2: the single `capBytes` is replaced by two independent
+/// budgets — Liked and Rolling-recent — each defaulting to 5GB.
+/// Bucketing is by liked-ness (a cached track currently in the
+/// user's liked set is charged to Liked; everything else to
+/// Rolling), so the dedup is storage-only and never filters
+/// playback. The old `cache_cap_bytes` key is intentionally not
+/// migrated; defaults reapply (a one-time re-tune, not data loss).
 class CacheSettings {
   const CacheSettings({
-    required this.capBytes,
+    required this.likedCapBytes,
+    required this.rollingCapBytes,
     required this.prefetchWindow,
     required this.cacheLikedTracks,
   });
 
-  /// 0 = unlimited.
-  final int capBytes;
+  /// Liked-bucket budget. 0 = unlimited.
+  final int likedCapBytes;
+
+  /// Rolling (recently-played) budget. 0 = unlimited.
+  final int rollingCapBytes;
 
   /// 1..10. Number of next-tracks the prefetcher pre-downloads.
   final int prefetchWindow;
@@ -22,25 +34,31 @@ class CacheSettings {
   final bool cacheLikedTracks;
 
   CacheSettings copyWith({
-    int? capBytes,
+    int? likedCapBytes,
+    int? rollingCapBytes,
     int? prefetchWindow,
     bool? cacheLikedTracks,
   }) =>
       CacheSettings(
-        capBytes: capBytes ?? this.capBytes,
+        likedCapBytes: likedCapBytes ?? this.likedCapBytes,
+        rollingCapBytes: rollingCapBytes ?? this.rollingCapBytes,
         prefetchWindow: prefetchWindow ?? this.prefetchWindow,
         cacheLikedTracks: cacheLikedTracks ?? this.cacheLikedTracks,
       );
 
+  static const _fiveGiB = 5 * 1024 * 1024 * 1024;
+
   static const defaults = CacheSettings(
-    capBytes: 5 * 1024 * 1024 * 1024,
+    likedCapBytes: _fiveGiB,
+    rollingCapBytes: _fiveGiB,
     prefetchWindow: 5,
     cacheLikedTracks: true,
   );
 }
 
 class CacheSettingsController extends AsyncNotifier<CacheSettings> {
-  static const _kCap = 'cache_cap_bytes';
+  static const _kLikedCap = 'cache_liked_cap_bytes';
+  static const _kRollingCap = 'cache_rolling_cap_bytes';
   static const _kPrefetch = 'cache_prefetch_window';
   static const _kCacheLiked = 'cache_liked_tracks';
 
@@ -49,13 +67,17 @@ class CacheSettingsController extends AsyncNotifier<CacheSettings> {
   @override
   Future<CacheSettings> build() async {
     _storage = ref.read(secureStorageProvider);
-    final cap = await _storage.read(key: _kCap);
+    final likedCap = await _storage.read(key: _kLikedCap);
+    final rollingCap = await _storage.read(key: _kRollingCap);
     final pre = await _storage.read(key: _kPrefetch);
     final liked = await _storage.read(key: _kCacheLiked);
     return CacheSettings(
-      capBytes: cap == null
-          ? CacheSettings.defaults.capBytes
-          : int.tryParse(cap) ?? CacheSettings.defaults.capBytes,
+      likedCapBytes: likedCap == null
+          ? CacheSettings.defaults.likedCapBytes
+          : int.tryParse(likedCap) ?? CacheSettings.defaults.likedCapBytes,
+      rollingCapBytes: rollingCap == null
+          ? CacheSettings.defaults.rollingCapBytes
+          : int.tryParse(rollingCap) ?? CacheSettings.defaults.rollingCapBytes,
       prefetchWindow: pre == null
           ? CacheSettings.defaults.prefetchWindow
           : (int.tryParse(pre) ?? 5).clamp(1, 10),
@@ -65,9 +87,14 @@ class CacheSettingsController extends AsyncNotifier<CacheSettings> {
     );
   }
 
-  Future<void> setCapBytes(int bytes) async {
-    await _storage.write(key: _kCap, value: bytes.toString());
-    state = AsyncData(state.value!.copyWith(capBytes: bytes));
+  Future<void> setLikedCapBytes(int bytes) async {
+    await _storage.write(key: _kLikedCap, value: bytes.toString());
+    state = AsyncData(state.value!.copyWith(likedCapBytes: bytes));
+  }
+
+  Future<void> setRollingCapBytes(int bytes) async {
+    await _storage.write(key: _kRollingCap, value: bytes.toString());
+    state = AsyncData(state.value!.copyWith(rollingCapBytes: bytes));
   }
 
   Future<void> setPrefetchWindow(int n) async {

flutter_client/lib/cache/db.dart

@@ -101,6 +101,11 @@ class AudioCacheIndex extends Table {
   TextColumn get path => text()();
   IntColumn get sizeBytes => integer()();
   DateTimeColumn get cachedAt => dateTime().withDefault(currentDateAndTime)();
+  /// When the track was last played. Drives the offline "Recently
+  /// played" ordering and rolling-bucket LRU eviction. Distinct from
+  /// cachedAt (download time). Nullable for pre-schema-9 rows until
+  /// the next play touches them (migration backfills to cachedAt).
+  DateTimeColumn get lastPlayedAt => dateTime().nullable()();
   TextColumn get source => textEnum<CacheSource>()();
   @override
   Set<Column> get primaryKey => {trackId};
@@ -247,7 +252,7 @@ class AppDb extends _$AppDb {
   AppDb([QueryExecutor? e]) : super(e ?? driftDatabase(name: 'minstrel_cache'));
 
   @override
-  int get schemaVersion => 8;
+  int get schemaVersion => 9;
 
   @override
   MigrationStrategy get migration => MigrationStrategy(
@@ -300,6 +305,17 @@ class AppDb extends _$AppDb {
             // upgrade; populated by controllers when REST calls fail.
             await m.createTable(cachedMutations);
           }
+          if (from < 9) {
+            // Schema 9 (#427 S2): two-bucket cache. lastPlayedAt
+            // gives the offline "Recently played" view a real
+            // recency signal (cachedAt is download time, not play
+            // time). Nullable — backfilled to cachedAt so existing
+            // rows order sensibly until next play touches them.
+            await m.addColumn(audioCacheIndex, audioCacheIndex.lastPlayedAt);
+            await customStatement(
+              'UPDATE audio_cache_index SET last_played_at = cached_at',
+            );
+          }
         },
       );
 }

flutter_client/lib/cache/prefetcher.dart

@@ -3,6 +3,7 @@ import 'dart:async';
 import 'package:audio_service/audio_service.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 
+import '../likes/likes_provider.dart' show likedIdsProvider;
 import '../player/album_color_extractor.dart';
 import '../player/player_provider.dart';
 import 'audio_cache_manager.dart';
@@ -86,10 +87,17 @@ class Prefetcher {
       }
     }
 
-    // Eviction pass after pinning new files.
-    if (settings.capBytes > 0) {
-      await mgr.evict(targetBytes: settings.capBytes);
-    }
+    // Eviction pass after pinning new files. Per-bucket (#427 S2):
+    // liked-ness decides the bucket, so a track that's both liked
+    // and recently played is protected by the Liked cap, not the
+    // rolling LRU.
+    final liked =
+        _ref.read(likedIdsProvider).value?.tracks ?? const <String>{};
+    await mgr.evictBuckets(
+      likedCap: settings.likedCapBytes,
+      rollingCap: settings.rollingCapBytes,
+      liked: liked,
+    );
   }
 }