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/adapters_test.dart

@@ -0,0 +1,70 @@
+import 'package:flutter_test/flutter_test.dart';
+
+import 'package:minstrel/cache/adapters.dart';
+import 'package:minstrel/models/album.dart';
+import 'package:minstrel/models/artist.dart';
+import 'package:minstrel/models/playlist.dart';
+import 'package:minstrel/models/track.dart';
+
+void main() {
+  test('ArtistRef.toDrift preserves id + name + sortName', () {
+    const ref = ArtistRef(id: 'a1', name: 'Boards of Canada', sortName: 'Boards of Canada');
+    final companion = ref.toDrift();
+    expect(companion.id.value, 'a1');
+    expect(companion.name.value, 'Boards of Canada');
+    expect(companion.sortName.value, 'Boards of Canada');
+  });
+
+  test('ArtistRef.toDrift falls back to name when sortName is empty', () {
+    const ref = ArtistRef(id: 'a1', name: 'The Album Leaf');
+    final companion = ref.toDrift();
+    expect(companion.sortName.value, 'The Album Leaf');
+  });
+
+  test('AlbumRef.toDrift preserves id + title + artistId', () {
+    const ref = AlbumRef(id: 'al1', title: 'Geogaddi', artistId: 'ar1');
+    final companion = ref.toDrift();
+    expect(companion.id.value, 'al1');
+    expect(companion.title.value, 'Geogaddi');
+    expect(companion.artistId.value, 'ar1');
+  });
+
+  test('TrackRef.toDrift converts seconds to ms + preserves track/disc', () {
+    const ref = TrackRef(
+      id: 't1',
+      title: 'Roygbiv',
+      albumId: 'al1',
+      artistId: 'ar1',
+      durationSec: 137,
+      trackNumber: 4,
+      discNumber: 1,
+    );
+    final companion = ref.toDrift();
+    expect(companion.id.value, 't1');
+    expect(companion.durationMs.value, 137 * 1000);
+    expect(companion.trackNumber.value, 4);
+    expect(companion.discNumber.value, 1);
+  });
+
+  test('Playlist.toDrift preserves id + userId + name', () {
+    const p = Playlist(
+      id: 'p1',
+      userId: 'u1',
+      name: 'My Mix',
+      description: 'a great mix',
+      isPublic: true,
+      systemVariant: null,
+      trackCount: 12,
+      coverUrl: '',
+      ownerUsername: 'alice',
+      createdAt: '',
+      updatedAt: '',
+    );
+    final companion = p.toDrift();
+    expect(companion.id.value, 'p1');
+    expect(companion.userId.value, 'u1');
+    expect(companion.name.value, 'My Mix');
+    expect(companion.isPublic.value, true);
+    expect(companion.trackCount.value, 12);
+  });
+}

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();
+  });
+}