feat(flutter/cache): cacheFirst helper + drift↔model adapters (#357 plan C)

Foundation for the provider migrations. cacheFirst<D, T> wraps the
drift.watch() + REST cold-cache fallback pattern: yields cached rows
when present, kicks off REST fetch + drift populate when empty +
online, yields empty when offline. REST failures swallow to empty so
callers can surface errors via toast.

adapters.dart adds CachedX → XRef extension methods + reverse
XRef.toDrift() companions for Artist/Album/Track/Playlist. Adapters
accept some loss of server-derived fields (coverUrl, streamUrl,
ownerUsername) — UI already handles empty values; cold-cache fallback
briefly shows the real values before drift takes over.

cache_first_test covers all 4 branches (non-empty, empty+online,
empty+offline, REST failure). adapters_test covers basic round-trips.
Both safe to run on CI runner — no drift open required.

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

flutter_client/lib/cache/cache_first.dart

@@ -0,0 +1,49 @@
+// Drift-first reactive read pattern with REST cold-cache fallback (#357 plan C).
+//
+// Subscribes to a drift watch() stream. On each emission:
+//   - non-empty → map to result type T and yield
+//   - empty + online → fetch via REST, populate drift, await re-emission
+//   - empty + offline → yield mapped empty result (UI shows empty state)
+//
+// The pattern lets every read provider trust drift as the source of
+// truth. SyncController keeps drift fresh in the background; widget
+// rebuilds happen automatically as drift writes propagate via watch().
+
+import 'dart:async';
+
+/// Wraps the watch + cold-cache fallback pattern. Generic over:
+///   D — the drift row type (or TypedResult for joins)
+///   T — the result type the caller wants (e.g. List<ArtistRef>)
+///
+/// `fetchAndPopulate` is invoked when drift is empty AND `isOnline()`
+/// returns true. It must populate drift via its own side-effect; the
+/// drift watch() stream will re-emit and this helper yields the
+/// populated rows on the next iteration.
+///
+/// REST failures are swallowed — the helper falls through to yielding
+/// the empty result. Caller is responsible for surfacing errors via
+/// toast etc.
+Stream<T> cacheFirst<D, T>({
+  required Stream<List<D>> driftStream,
+  required Future<void> Function() fetchAndPopulate,
+  required T Function(List<D>) toResult,
+  required Future<bool> Function() isOnline,
+}) async* {
+  await for (final rows in driftStream) {
+    if (rows.isNotEmpty) {
+      yield toResult(rows);
+      continue;
+    }
+    if (await isOnline()) {
+      try {
+        await fetchAndPopulate();
+        // The drift watch() stream re-emits with the populated rows on
+        // the next loop iteration. Don't yield here.
+      } catch (_) {
+        yield toResult(rows); // empty result; caller surfaces error
+      }
+    } else {
+      yield toResult(rows); // empty result; offline
+    }
+  }
+}