docs: query comments say what each query selects and why, not how it came to be (#6277)

Rewrites the internal/db/queries comments to rule 32 and regenerates
dbq, whose doc comments and embedded SQL carry them. The bugs behind the
tiered mixes, the md5 order seed, the score bands and the round-robin
arms are restated as the constraint each one enforces; counts from one
library and stale cross-references are gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-23 12:31:13 -04:00
co-authored by Claude Opus 5.5
parent 7e6228c13f
commit 1d4ef1a23f
100 changed files with 648 additions and 698 deletions
+6 -6
View File
@@ -46,7 +46,7 @@ SELECT COUNT(*) FROM artists WHERE name ILIKE '%' || $1::text || '%';
SELECT * FROM artists WHERE id = ANY($1::uuid[]);
-- name: ListArtistsAlphaWithCovers :many
-- M6a: alpha-sorted artist list with derived cover_album_id (most-recent
-- Alpha-sorted artist list with derived cover_album_id (most-recent
-- album whose cover_art_path is set). Replaces ListArtistsAlpha for the
-- /api/artists?sort=alpha branch — the new column is appended, so the
-- alpha branch is purely additive on the wire. album_count is computed
@@ -68,7 +68,7 @@ ORDER BY artists.sort_name, artists.name, artists.id
LIMIT $1 OFFSET $2;
-- name: DeleteArtistIfEmpty :one
-- M7 #372: deletes the artist row only when it has no remaining albums
-- Deletes the artist row only when it has no remaining albums
-- AND no remaining tracks (defensive — tracks can in principle exist
-- without an album, though the scanner doesn't write that shape today).
DELETE FROM artists a
@@ -78,7 +78,7 @@ WHERE a.id = $1
RETURNING a.id;
-- name: SetArtistMbidIfNull :exec
-- M7 #379: heal MBID on existing artist rows during rescan. Idempotent —
-- Heal MBID on existing artist rows during rescan. Idempotent —
-- only updates when the existing mbid is NULL, so concurrent scans don't
-- overwrite an existing value with a stale one.
UPDATE artists
@@ -87,7 +87,7 @@ UPDATE artists
WHERE id = $1 AND mbid IS NULL;
-- name: ListArtistsMissingArt :many
-- M7 cover-sources: returns artist rows the artist-art enricher should
-- Returns artist rows the artist-art enricher should
-- attempt. Eligible: artist_art_source IS NULL OR (= 'none' AND stale
-- artist_art_sources_version). MBID-less artists are returned but the
-- enricher skips them at the row.mbid == nil guard inside the chain.
@@ -99,7 +99,7 @@ SELECT a.id
LIMIT $2;
-- name: SetArtistArtWithVersion :exec
-- M7 cover-sources: records a successful or settled artist-art
-- Records a successful or settled artist-art
-- enrichment with the current sources_version stamp. thumb_path /
-- fanart_path are NULL on a 'none' result, or independently NULL if
-- the provider returned only one of the two image types (e.g.
@@ -113,7 +113,7 @@ UPDATE artists
WHERE id = $1;
-- name: ClearArtistArtNone :exec
-- M7 cover-sources: parallel of ClearAlbumCoverNone. Used by the
-- Parallel of ClearAlbumCoverNone. Used by the
-- eligibility loop to flip stale 'none' rows back to NULL.
UPDATE artists
SET artist_art_source = NULL,