feat(metadata): implement single-track metadata editor API (§A7/§1H)

Adds inline AcoustID match-finding (multiple ranked candidates via
lookup_all) and PUT /tracks/{id}/metadata for manual edits, resolving
artist/album and setting metadata_status=manual. Extends TrackOut with
genre/year/track_number.

app/api/v1/tracks.py

@@ -12,11 +12,18 @@ from app.api.deps import (
     ArtistRepoDep,
     CurrentUser,
     FileStorageDep,
+    MetadataServiceDep,
     StreamUser,
     TrackRepoDep,
 )
 from app.api.schemas.pagination import PagedResponse
-from app.api.schemas.track import TrackOut, TrackUpdate
+from app.api.schemas.track import (
+    MetadataApply,
+    MetadataMatch,
+    MetadataMatchesOut,
+    TrackOut,
+    TrackUpdate,
+)
 from app.domain.entities.album import Album
 from app.domain.entities.track import Artist, Track
 from app.domain.errors import NotFoundError
@@ -41,6 +48,9 @@ async def _build_track_out(
             duration_seconds=t.duration_seconds,
             file_format=t.file_format,
             file_size=t.file_size,
+            genre=t.genre,
+            year=t.year,
+            track_number=t.track_number,
             metadata_status=t.metadata_status,
             metadata_error=t.metadata_error,
             enriched_at=t.enriched_at,
@@ -187,8 +197,83 @@ async def enrich_metadata(
 
 
 @router.get("/{track_id}/metadata/matches")
-async def get_metadata_matches(track_id: uuid.UUID, _: CurrentUser) -> Any: ...
+async def get_metadata_matches(
+    track_id: uuid.UUID,
+    track_repo: TrackRepoDep,
+    metadata_service: MetadataServiceDep,
+    _: CurrentUser,
+) -> MetadataMatchesOut:
+    """AcoustID candidates for the metadata editor's match picker (§A7).
+
+    Runs the fingerprint lookup inline (single track, user-triggered) and
+    never mutates the track. Degrades to an empty list if fpcalc/AcoustID are
+    unavailable or no match is found.
+    """
+    track = await track_repo.get_by_id(track_id)
+    if track is None:
+        raise NotFoundError(f"Track {track_id} not found.")
+    matches = await metadata_service.find_matches(track_id)
+    return MetadataMatchesOut(
+        items=[
+            MetadataMatch(
+                acoustid=m.acoustid,
+                score=m.score,
+                recording_mbid=m.recording_mbid,
+                release_group_mbid=m.release_group_mbid,
+                title=m.title,
+                artist=m.artist,
+                album=m.album,
+                year=m.year,
+            )
+            for m in matches
+        ]
+    )
 
 
 @router.put("/{track_id}/metadata")
-async def set_metadata(track_id: uuid.UUID, _: CurrentUser) -> Any: ...
+async def set_metadata(
+    track_id: uuid.UUID,
+    body: MetadataApply,
+    track_repo: TrackRepoDep,
+    artist_repo: ArtistRepoDep,
+    album_repo: AlbumRepoDep,
+    _: CurrentUser,
+) -> TrackOut:
+    """Apply manual edits or an accepted AcoustID match (§A7). Sets
+    ``metadata_status = manual`` — never overwritten by auto-enrichment."""
+    track = await track_repo.get_by_id(track_id)
+    if track is None:
+        raise NotFoundError(f"Track {track_id} not found.")
+
+    artist_id: uuid.UUID | None = None
+    if body.artist_name:
+        artist = await artist_repo.get_or_create(body.artist_name)
+        artist_id = artist.id
+
+    album_id: uuid.UUID | None = None
+    if body.album_title:
+        album = await album_repo.get_or_create(
+            title=body.album_title,
+            artist_id=artist_id or track.artist_id,
+            year=body.year,
+            musicbrainz_id=None,
+        )
+        album_id = album.id
+
+    track = await track_repo.update(
+        track_id,
+        title=body.title,
+        genre=body.genre,
+        year=body.year,
+        artist_id=artist_id,
+        album_id=album_id,
+        track_number=body.track_number,
+    )
+
+    artist_ids = [track.artist_id]
+    album_ids = [track.album_id] if track.album_id else []
+    artists = {a.id: a for a in await artist_repo.get_many(artist_ids)}
+    albums = {a.id: a for a in await album_repo.get_many(album_ids)}
+
+    items = await _build_track_out([track], artists, albums)
+    return items[0]