feat: cover-art pipeline (§1D)

Resolve, store and serve album cover art.

Sources (tag-first, mirroring enrichment): embedded artwork extracted
offline via mutagen (ID3 APIC / FLAC+OGG Picture / MP4 covr), then Cover
Art Archive by release-group MBID as a network fallback. Resolution runs
inside MetadataEnrichmentService after album resolution, only when the
album has no cover yet (idempotent, never overwrites), and is best-effort
so a cover failure never affects enrichment status.

- CoverArt value object + CoverArtExtractor/CoverArtProvider ports
- MutagenCoverExtractor + CoverArtArchiveClient adapters
- AcoustID parser now captures release_group_mbid
- Covers stored via FileStorage at covers/{album_id}.{ext} (local + S3)
- AlbumRepository.set_cover_path
- Serve real covers: GET /api/v1/albums|tracks/{id}/cover (StreamUser,
  ?token=), Subsonic getCoverArt (placeholder fallback)
- has_cover flag on AlbumOut/TrackOut
- coverart_enabled / coverart_base_url settings
- tests: cover resolution units + release_group parse + DB-backed
  test_cover_api.py (139 green via make test-api)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

app/application/metadata_service.py

@@ -12,10 +12,14 @@ Invariants (plan §6.2, CLAUDE.md):
 - **Idempotent** — re-running only fills gaps; ``apply_enrichment`` never erases.
 """
 
+import tempfile
 import uuid
 from dataclasses import dataclass
+from pathlib import Path
 
 from app.core.logging import get_logger
+from app.domain.entities.album import Album
+from app.domain.entities.cover import CoverArt
 from app.domain.entities.metadata import AudioTags, RecordingMatch
 from app.domain.ports import (
     AcoustIdClient,
@@ -23,6 +27,8 @@ from app.domain.ports import (
     ArtistRepository,
     AudioFingerprinter,
     AudioTagReader,
+    CoverArtExtractor,
+    CoverArtProvider,
     FileStorage,
     TrackRepository,
 )
@@ -50,6 +56,8 @@ class MetadataEnrichmentService:
         tag_reader: AudioTagReader,
         fingerprinter: AudioFingerprinter,
         acoustid: AcoustIdClient,
+        cover_extractor: CoverArtExtractor | None = None,
+        cover_provider: CoverArtProvider | None = None,
     ) -> None:
         self._tracks = tracks
         self._artists = artists
@@ -58,6 +66,8 @@ class MetadataEnrichmentService:
         self._tag_reader = tag_reader
         self._fingerprinter = fingerprinter
         self._acoustid = acoustid
+        self._cover_extractor = cover_extractor
+        self._cover_provider = cover_provider
 
     async def enrich(self, track_id: uuid.UUID) -> EnrichmentResult:
         track = await self._tracks.get_by_id(track_id)
@@ -92,7 +102,15 @@ class MetadataEnrichmentService:
         acoustid_id = match.acoustid if match else None
 
         artist_id = await self._resolve_artist(artist_name, fallback=track.artist_id)
-        album_id = await self._resolve_album(album_title, artist_id=artist_id, year=year, mbid=mbid)
+        album = await self._resolve_album(album_title, artist_id=artist_id, year=year, mbid=mbid)
+        album_id = album.id if album is not None else None
+
+        if album is not None:
+            await self._resolve_cover(
+                album,
+                storage_uri=track.storage_uri,
+                release_group_mbid=match.release_group_mbid if match else None,
+            )
 
         identified = bool(artist_name) or album_id is not None or mbid is not None
         status = "enriched" if identified else "failed"
@@ -148,16 +166,71 @@ class MetadataEnrichmentService:
         artist_id: uuid.UUID,
         year: int | None,
         mbid: str | None,
-    ) -> uuid.UUID | None:
+    ) -> Album | None:
         if not title:
             return None
-        album = await self._albums.get_or_create(
+        return await self._albums.get_or_create(
             title=title,
             artist_id=artist_id,
             year=year,
             musicbrainz_id=mbid,
         )
-        return album.id
+
+    async def _resolve_cover(
+        self,
+        album: Album,
+        *,
+        storage_uri: str,
+        release_group_mbid: str | None,
+    ) -> None:
+        """Fill in an album cover when it has none. Source order mirrors the
+        tag-first pipeline: embedded artwork (offline) → Cover Art Archive
+        (network, by release-group). Best-effort — any failure is swallowed so a
+        missing cover never affects enrichment status."""
+        if album.cover_path:
+            return  # already has one — never overwrite (idempotent)
+
+        cover = await self._extract_cover(storage_uri)
+        if cover is None:
+            cover = await self._fetch_cover(release_group_mbid)
+        if cover is None:
+            return
+
+        try:
+            key = await self._save_cover(album.id, cover)
+            await self._albums.set_cover_path(album.id, key)
+            log.info("cover_resolved", album_id=str(album.id), content_type=cover.content_type)
+        except Exception:
+            log.warning("cover_save_failed", album_id=str(album.id))
+
+    async def _extract_cover(self, storage_uri: str) -> CoverArt | None:
+        if self._cover_extractor is None:
+            return None
+        try:
+            async with self._storage.as_local_path(storage_uri) as path:
+                return await self._cover_extractor.extract(path)
+        except Exception:
+            log.warning("cover_extract_step_failed", storage_uri=storage_uri)
+            return None
+
+    async def _fetch_cover(self, release_group_mbid: str | None) -> CoverArt | None:
+        if self._cover_provider is None or not release_group_mbid:
+            return None
+        if not self._cover_provider.is_available():
+            return None
+        try:
+            return await self._cover_provider.fetch_release_group(release_group_mbid)
+        except Exception:
+            log.warning("cover_fetch_step_failed", release_group=release_group_mbid)
+            return None
+
+    async def _save_cover(self, album_id: uuid.UUID, cover: CoverArt) -> str:
+        key = f"covers/{album_id}.{cover.extension}"
+        with tempfile.NamedTemporaryFile(suffix=f".{cover.extension}") as tmp:
+            tmp.write(cover.data)
+            tmp.flush()
+            await self._storage.save_file(key, Path(tmp.name))
+        return key
 
 
 def _opt_str(*values: str | None) -> str | None: