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>

internal/db/dbq/albums.sql.go

@@ -15,7 +15,7 @@ const countAlbums = `-- name: CountAlbums :one
 SELECT COUNT(*) FROM albums
 `
 
-// M6a: total album count for the /api/library/albums envelope.
+// Total album count for the /api/library/albums envelope.
 func (q *Queries) CountAlbums(ctx context.Context) (int64, error) {
 	row := q.db.QueryRow(ctx, countAlbums)
 	var count int64
@@ -59,7 +59,7 @@ type DeleteAlbumIfEmptyRow struct {
 	ArtistID pgtype.UUID
 }
 
-// M7 #372: deletes the album row only when it has no remaining tracks.
+// Deletes the album row only when it has no remaining tracks.
 // Used after a track delete to tidy up orphaned albums. RETURNING gives
 // us the artist_id so the service can chain into the artist-empty check.
 // Returns no rows when the album still has tracks; the service treats
@@ -91,12 +91,12 @@ type GetAlbumByArtistAndTitleParams struct {
 }
 
 // Scanner uses this for the no-mbid dedupe path: resolve-or-create. An album
-// of the same name in another release group is a different album (Weezer's
-// six self-titled albums shared one row until 2026-10-20), so a row whose
+// of the same name in another release group is a different album (one
+// artist's self-titled albums), so a row whose
 // group is known and differs is not returned. A row of the file's own group
 // comes first, then one with no group yet, then the one holding the most
 // tracks from the file's folder: a file tagged with no group (a live bonus
-// track beside Weezer's 1994 album) belongs with its folder, not the oldest
+// track beside its album) belongs with its folder, not the oldest
 // row, and a few strays already misfiled do not outvote the folder.
 func (q *Queries) GetAlbumByArtistAndTitle(ctx context.Context, arg GetAlbumByArtistAndTitleParams) (Album, error) {
 	row := q.db.QueryRow(ctx, getAlbumByArtistAndTitle,
@@ -166,7 +166,7 @@ type GetAlbumCoverageRollupRow struct {
 	PendingNoMbid int64
 }
 
-// M7 coverage-gauge: library-wide cover-art coverage rollup for the
+// Library-wide cover-art coverage rollup for the
 // admin gauge. Single sequential scan with FILTER aggregates —
 // sub-millisecond on realistic libraries. pending_no_mbid is a SUBSET
 // of pending; the UI surfaces it separately so operators can see how
@@ -176,12 +176,9 @@ type GetAlbumCoverageRollupRow struct {
 // Invariant: with_art + pending + settled = total. (pending_no_mbid is
 // not part of the sum — it's a subset of pending, surfaced separately.)
 //
-// The IN list below must stay in sync with the cover_art_source CHECK
-// constraint — currently relaxed by migration 0020 to include 'deezer'
-// and 'lastfm', and migration 0030 further relaxed it to any non-empty
-// string. If a new source value is added without updating this query,
-// with_art will silently undercount. Drift #556 caught the deezer +
-// lastfm omission introduced by migration 0020.
+// The IN list below must name every source the enrichers write (the
+// cover_art_source CHECK accepts any non-empty string since migration
+// 0030). A source missing here makes with_art silently undercount.
 func (q *Queries) GetAlbumCoverageRollup(ctx context.Context) (GetAlbumCoverageRollupRow, error) {
 	row := q.db.QueryRow(ctx, getAlbumCoverageRollup)
 	var i GetAlbumCoverageRollupRow
@@ -236,7 +233,7 @@ SELECT id, title, sort_title, artist_id, release_date, mbid, cover_art_path, cre
 `
 
 // Batched lookup used by /api/library/sync to hydrate upsert payloads
-// (#357). Mirror of GetArtistsByIDs.
+// . Mirror of GetArtistsByIDs.
 func (q *Queries) GetAlbumsByIDs(ctx context.Context, dollar_1 []pgtype.UUID) ([]Album, error) {
 	rows, err := q.db.Query(ctx, getAlbumsByIDs, dollar_1)
 	if err != nil {
@@ -277,7 +274,7 @@ SELECT release_group_mbid::text
  LIMIT 1
 `
 
-// #5241: the release group the library already knows for a release id, so a
+// The release group the library already knows for a release id, so a
 // request carrying a release id can be repaired without asking MusicBrainz.
 func (q *Queries) GetReleaseGroupForReleaseMbid(ctx context.Context, mbid *string) (string, error) {
 	row := q.db.QueryRow(ctx, getReleaseGroupForReleaseMbid, mbid)
@@ -400,7 +397,7 @@ type ListAlbumsAlphaWithArtistRow struct {
 	ArtistName string
 }
 
-// M6a: alpha-sorted album list joined with artist_name. Used by
+// Alpha-sorted album list joined with artist_name. Used by
 // /api/library/albums for the wrapping-grid page. Stable id-tiebreak.
 func (q *Queries) ListAlbumsAlphaWithArtist(ctx context.Context, arg ListAlbumsAlphaWithArtistParams) ([]ListAlbumsAlphaWithArtistRow, error) {
 	rows, err := q.db.Query(ctx, listAlbumsAlphaWithArtist, arg.Limit, arg.Offset)
@@ -547,12 +544,10 @@ type ListAlbumsByGenreParams struct {
 // Album "belongs to" a genre if any of its tracks carry that genre.
 // Serves Subsonic getAlbumList?type=byGenre.
 //
-// Splits tracks.genre on [;,] as of #367. It previously compared the whole
-// column verbatim, so a track tagged "Rock;Pop" was unreachable from EITHER
-// "Rock" or "Pop" — a Subsonic client asking for a genre silently missed
-// every multi-genre track. This also aligns the endpoint with
-// recommendation.sql / discover.sql, which have always split, and with the
-// genre browse index that #367 adds.
+// Splits tracks.genre on [;,], so a track tagged "Rock;Pop" is reachable from
+// both "Rock" and "Pop"; comparing the whole column would hide every
+// multi-genre track from a Subsonic client asking for a genre. The same split
+// as recommendation.sql, discover.sql and the genre browse index.
 //
 // EXISTS rather than JOIN + DISTINCT ON: the lateral split emits one row per
 // (track, genre-fragment), so a join would multiply rows per album and lean
@@ -620,7 +615,7 @@ type ListAlbumsMissingMbidWithTrackRow struct {
 // one of its tracks' file_path so the worker can re-read tags. LIMIT
 // supplied by caller for batching/progress purposes. The track read is
 // one still on disk; an album with none left is skipped until a scan
-// finds its files again (#5139).
+// finds its files again.
 func (q *Queries) ListAlbumsMissingMbidWithTrack(ctx context.Context, limit int32) ([]ListAlbumsMissingMbidWithTrackRow, error) {
 	rows, err := q.db.Query(ctx, listAlbumsMissingMbidWithTrack, limit)
 	if err != nil {
@@ -738,7 +733,7 @@ type ListRecentlyAddedAlbumsWithArtistRow struct {
 	ArtistName string
 }
 
-// M6a: recently-added albums joined with artist_name + artist_id for the
+// Recently-added albums joined with artist_name + artist_id for the
 // home-page section. created_at is the row-insert timestamp from the
 // scanner — the closest proxy to "added to library". Stable secondary
 // ordering by id keeps pagination tie-break deterministic.
@@ -838,7 +833,7 @@ type SetAlbumCoverWithVersionParams struct {
 	CoverArtSourcesVersion int32
 }
 
-// M7 cover-sources: records a successful or settled enrichment with the
+// Records a successful or settled enrichment with the
 // current sources_version stamp. cover_art_path is NULL when source is
 // 'none' (no file written). Atomic; called per album per pass.
 func (q *Queries) SetAlbumCoverWithVersion(ctx context.Context, arg SetAlbumCoverWithVersionParams) error {
@@ -863,7 +858,7 @@ type SetAlbumMbidIfNullParams struct {
 	Mbid *string
 }
 
-// M7 #379: heal MBID on existing album rows during rescan. Idempotent —
+// Heal MBID on existing album rows during rescan. Idempotent —
 // only updates when the existing mbid is NULL.
 func (q *Queries) SetAlbumMbidIfNull(ctx context.Context, arg SetAlbumMbidIfNullParams) error {
 	_, err := q.db.Exec(ctx, setAlbumMbidIfNull, arg.ID, arg.Mbid)
@@ -882,7 +877,7 @@ type SetAlbumReleaseGroupMbidIfNullParams struct {
 	ReleaseGroupMbid *string
 }
 
-// #5241: heal the release-group id on an existing album row, from a rescan's
+// Heal the release-group id on an existing album row, from a rescan's
 // tags or from the re-acquisition sweeper's MusicBrainz lookup. Only fills a
 // NULL, so a tag never gets overwritten by a later guess or vice versa.
 func (q *Queries) SetAlbumReleaseGroupMbidIfNull(ctx context.Context, arg SetAlbumReleaseGroupMbidIfNullParams) error {
@@ -902,7 +897,7 @@ type SetReleaseGroupForReleaseMbidIfNullParams struct {
 	ReleaseMbid      string
 }
 
-// #5241: cache a MusicBrainz-resolved release group onto the album row that
+// Cache a MusicBrainz-resolved release group onto the album row that
 // holds the release, filling only a NULL.
 func (q *Queries) SetReleaseGroupForReleaseMbidIfNull(ctx context.Context, arg SetReleaseGroupForReleaseMbidIfNullParams) error {
 	_, err := q.db.Exec(ctx, setReleaseGroupForReleaseMbidIfNull, arg.ReleaseGroupMbid, arg.ReleaseMbid)