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/test/cache/cache_first_test.dart

@@ -0,0 +1,75 @@
+import 'dart:async';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:minstrel/cache/cache_first.dart';
+
+void main() {
+  test('non-empty drift emission passes through toResult', () async {
+    final controller = StreamController<List<int>>();
+    final results = cacheFirst<int, int>(
+      driftStream: controller.stream,
+      fetchAndPopulate: () async => fail('should not fetch when rows present'),
+      toResult: (rows) => rows.fold<int>(0, (a, b) => a + b),
+      isOnline: () async => true,
+    );
+
+    final firstFuture = results.first;
+    controller.add([1, 2, 3]);
+    expect(await firstFuture, 6);
+    await controller.close();
+  });
+
+  test('empty drift emission + online triggers fetchAndPopulate', () async {
+    final controller = StreamController<List<int>>();
+    var fetchCalled = 0;
+    final results = cacheFirst<int, int>(
+      driftStream: controller.stream,
+      fetchAndPopulate: () async {
+        fetchCalled++;
+        controller.add([42]); // simulate populate causing re-emission
+      },
+      toResult: (rows) => rows.fold<int>(0, (a, b) => a + b),
+      isOnline: () async => true,
+    );
+
+    final firstFuture = results.first;
+    controller.add([]);
+    expect(await firstFuture, 42);
+    expect(fetchCalled, 1);
+    await controller.close();
+  });
+
+  test('empty drift + offline yields empty result without fetch', () async {
+    final controller = StreamController<List<int>>();
+    var fetchCalled = 0;
+    final results = cacheFirst<int, int>(
+      driftStream: controller.stream,
+      fetchAndPopulate: () async {
+        fetchCalled++;
+      },
+      toResult: (rows) => rows.fold<int>(0, (a, b) => a + b),
+      isOnline: () async => false,
+    );
+
+    final firstFuture = results.first;
+    controller.add([]);
+    expect(await firstFuture, 0);
+    expect(fetchCalled, 0);
+    await controller.close();
+  });
+
+  test('REST failure falls through to empty result', () async {
+    final controller = StreamController<List<int>>();
+    final results = cacheFirst<int, int>(
+      driftStream: controller.stream,
+      fetchAndPopulate: () async => throw Exception('REST 500'),
+      toResult: (rows) => rows.fold<int>(0, (a, b) => a + b),
+      isOnline: () async => true,
+    );
+
+    final firstFuture = results.first;
+    controller.add([]);
+    expect(await firstFuture, 0);
+    await controller.close();
+  });
+}