feat(library): AcoustID lookup worker fills the MBIDs tags leave empty (M401 #3920 #3921)

Migration 0069 adds tracks.mbid_source (tag | acoustid), a lookup state per
track (matched | ambiguous | no_match | failed) and the acoustid_settings
row (off, no key, min score 0.85).

The file's tag outranks a lookup (D4). UpsertTrack keeps a looked-up id
through a re-read that finds no tag id and replaces it as soon as one
appears. SetTrackMbidFromAcoustID refuses to write over a tag id.

The worker fingerprints each untagged track with fpcalc's compressed
print, looks it up and writes an id only when D5 settles it: one
recording at or above the threshold, or one left after matching title and
length. Ambiguous and no-match results write nothing. A key AcoustID
refuses, or the service being unreachable, stops the pass and is reported
in the worker's status. It never counts as a verdict on a track.

A changed file drops its lookup in the scan. The re-lookup takes back an
id that no longer matches.

Admin API: GET /api/admin/library/acoustid (settings, status, coverage by
source), PUT …/acoustid-settings (write-only key), POST …/acoustid/run,
GET …/acoustid/unsettled.

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

internal/db/queries/acoustid.sql

@@ -0,0 +1,99 @@
+-- AcoustID recording-id lookup (M401). Migration 0069 says what each
+-- lookup state means.
+
+-- name: ListTracksNeedingAcoustIDLookup :many
+-- The lookup worker's queue: present tracks with no tag MBID and no lookup
+-- since their file last changed. A looked-up id is included once its row is
+-- gone (the file changed), so the new bytes are checked rather than trusted.
+-- Keyset-paged on id, as the loudness queue is, so a pass ends even when
+-- every attempt is inconclusive and writes nothing.
+SELECT t.id, t.file_path, t.title, t.duration_ms
+  FROM tracks t
+ WHERE (t.mbid IS NULL OR t.mbid_source = 'acoustid')
+   AND t.missing_since IS NULL
+   AND t.id > sqlc.arg(after_id)::uuid
+   AND NOT EXISTS (SELECT 1 FROM track_acoustid_lookups l WHERE l.track_id = t.id)
+ ORDER BY t.id
+ LIMIT sqlc.arg(batch_limit);
+
+-- name: RecordAcoustIDLookup :exec
+INSERT INTO track_acoustid_lookups (track_id, state, best_score, candidates, recording_mbid, detail)
+VALUES (sqlc.arg(track_id), sqlc.arg(state), sqlc.narg(best_score), sqlc.arg(candidates),
+        sqlc.narg(recording_mbid), sqlc.narg(detail))
+ON CONFLICT (track_id) DO UPDATE SET
+    state          = EXCLUDED.state,
+    best_score     = EXCLUDED.best_score,
+    candidates     = EXCLUDED.candidates,
+    recording_mbid = EXCLUDED.recording_mbid,
+    detail         = EXCLUDED.detail,
+    looked_up_at   = now();
+
+-- name: SetTrackMbidFromAcoustID :execrows
+-- Never over a tag id (D4): the guard is here, not only in the worker, so a
+-- tag the scan read between the worker's list and this write still wins.
+-- updated_at is left alone: it gates the scan's mtime skip, and moving it
+-- past a file's mtime would hide a change made just before the lookup.
+UPDATE tracks
+   SET mbid = sqlc.arg(mbid), mbid_source = 'acoustid'
+ WHERE id = sqlc.arg(id)
+   AND (mbid IS NULL OR mbid_source = 'acoustid');
+
+-- name: ClearTrackAcoustIDMbid :exec
+-- A re-lookup of changed bytes that no longer matches takes back the id an
+-- earlier lookup wrote. A tag id is never touched.
+UPDATE tracks
+   SET mbid = NULL, mbid_source = NULL
+ WHERE id = sqlc.arg(id)
+   AND mbid_source = 'acoustid';
+
+-- name: DeleteAcoustIDLookup :exec
+-- The scan drops the lookup of bytes that are gone, so the worker checks the
+-- new ones.
+DELETE FROM track_acoustid_lookups WHERE track_id = $1;
+
+-- name: GetMbidCoverage :one
+-- The admin gauge: present tracks by where their MBID came from, and the
+-- lookup states of those a lookup has seen. pending is what the worker's
+-- queue holds.
+SELECT count(*)::bigint AS total,
+       count(*) FILTER (WHERE t.mbid_source = 'tag')::bigint AS from_tag,
+       count(*) FILTER (WHERE t.mbid_source = 'acoustid')::bigint AS from_acoustid,
+       count(*) FILTER (WHERE l.state = 'ambiguous')::bigint AS ambiguous,
+       count(*) FILTER (WHERE l.state = 'no_match')::bigint AS no_match,
+       count(*) FILTER (WHERE l.state = 'failed')::bigint AS failed,
+       count(*) FILTER (
+           WHERE l.track_id IS NULL AND (t.mbid IS NULL OR t.mbid_source = 'acoustid')
+       )::bigint AS pending
+  FROM tracks t
+  LEFT JOIN track_acoustid_lookups l ON l.track_id = t.id
+ WHERE t.missing_since IS NULL;
+
+-- name: ListUnsettledAcoustIDLookups :many
+-- The admin list of tracks a lookup could not settle (ambiguous or failed),
+-- so they are findable rather than silently empty.
+SELECT t.id, t.title, t.file_path, ar.name AS artist_name, al.title AS album_title,
+       l.state, l.best_score, l.candidates, l.detail, l.looked_up_at
+  FROM track_acoustid_lookups l
+  JOIN tracks t ON t.id = l.track_id
+  JOIN artists ar ON ar.id = t.artist_id
+  JOIN albums al ON al.id = t.album_id
+ WHERE l.state IN ('ambiguous', 'failed')
+   AND t.missing_since IS NULL
+ ORDER BY ar.name, al.title, t.disc_number NULLS FIRST, t.track_number NULLS FIRST, t.title
+ LIMIT sqlc.arg(row_limit);
+
+-- name: GetAcoustIDSettings :one
+SELECT * FROM acoustid_settings WHERE id = true;
+
+-- name: UpdateAcoustIDSettings :one
+-- The key is write-only from the admin card: set_api_key false keeps the
+-- stored one, and an empty api_key with set_api_key true clears it.
+UPDATE acoustid_settings
+   SET enabled    = sqlc.arg(enabled),
+       min_score  = sqlc.arg(min_score),
+       api_key    = CASE WHEN sqlc.arg(set_api_key)::boolean
+                         THEN NULLIF(sqlc.arg(api_key)::text, '')
+                         ELSE api_key END,
+       updated_at = now()
+ WHERE id = true
+RETURNING *;

internal/db/queries/merge.sql

@@ -88,7 +88,7 @@ ON CONFLICT (track_a_id, track_b_id, source) DO NOTHING;
 -- A recording MBID is what the similarity pipeline keys on. If only the removed
 -- copy carried one, the survivor takes it rather than going dark to similarity.
 UPDATE tracks AS survivor
-   SET mbid = loser.mbid
+   SET mbid = loser.mbid, mbid_source = loser.mbid_source
   FROM tracks AS loser
  WHERE survivor.id = sqlc.arg(survivor_id)::uuid
    AND loser.id = sqlc.arg(loser_id)::uuid

internal/db/queries/tracks.sql

@@ -1,10 +1,13 @@
 -- name: UpsertTrack :one
 -- file_path is the canonical identity for library scan; mbid is secondary.
+-- mbid is the file's tag. A looked-up id (mbid_source 'acoustid', M401)
+-- survives a re-read that finds no tag id, and a tag id replaces it (D4).
 INSERT INTO tracks (
     title, album_id, artist_id, track_number, disc_number,
     duration_ms, file_path, file_size, file_format, bitrate, mbid, genre,
-    tag_read_version
-) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
+    tag_read_version, mbid_source
+) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13,
+          CASE WHEN $11::text IS NOT NULL THEN 'tag' END)
 ON CONFLICT (file_path) DO UPDATE SET
     title = EXCLUDED.title,
     album_id = EXCLUDED.album_id,
@@ -15,7 +18,11 @@ ON CONFLICT (file_path) DO UPDATE SET
     file_size = EXCLUDED.file_size,
     file_format = EXCLUDED.file_format,
     bitrate = EXCLUDED.bitrate,
-    mbid = EXCLUDED.mbid,
+    -- Both read the row as it was before this statement.
+    mbid = CASE WHEN EXCLUDED.mbid IS NULL AND tracks.mbid_source = 'acoustid'
+                THEN tracks.mbid ELSE EXCLUDED.mbid END,
+    mbid_source = CASE WHEN EXCLUDED.mbid IS NOT NULL THEN 'tag'
+                       WHEN tracks.mbid_source = 'acoustid' THEN 'acoustid' END,
     genre = EXCLUDED.genre,
     -- Stamped on update too, so a tag-repair pass marks rows as done and the
     -- next scan can short-circuit them again (#2499).
@@ -39,7 +46,7 @@ SELECT id, file_path
 -- Heal a track's recording MBID only while still NULL — idempotent, so
 -- re-running the backfill is a no-op for already-healed rows.
 UPDATE tracks
-   SET mbid = $2, updated_at = now()
+   SET mbid = $2, mbid_source = 'tag', updated_at = now()
  WHERE id = $1 AND mbid IS NULL;
 
 -- name: GetTrackByID :one