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/tracks.sql.go

@@ -62,10 +62,10 @@ UPDATE tracks
  WHERE id = ANY($1::uuid[])
 `
 
-// Forgets the recording MBID of rows whose file was another song's (M498's
-// wrong-slot removal). The MBID came from that file, so it names the song kept
-// elsewhere on the album, and missing-pair folding would fold the emptied slot
-// into it: twelve slots went that way on 2026-10-20 and were never wanted back.
+// Forgets the recording MBID of rows whose file was another song's (the
+// duplicate resolver's wrong-slot removal). The MBID came from that file, so it
+// names the song kept elsewhere on the album, and missing-pair folding would
+// fold the emptied slot into it, so it would never be wanted back.
 // mbid_source goes with it (tracks_mbid_source_pair).
 func (q *Queries) ClearTrackMbids(ctx context.Context, ids []pgtype.UUID) error {
 	_, err := q.db.Exec(ctx, clearTrackMbids, ids)
@@ -177,7 +177,7 @@ type DeleteTrackRow struct {
 	Mbid     *string
 }
 
-// M7 #372: hard delete with FK cascade. The CASCADE on track_id from
+// Hard delete with FK cascade. The CASCADE on track_id from
 // play_events / general_likes_tracks / quarantine /
 // quarantine_actions handles their cleanup. RETURNING gives us
 // album_id + artist_id for the album-empty / artist-empty cascade
@@ -209,11 +209,11 @@ type FindMissingTrackByAudioHashRow struct {
 	FilePath string
 }
 
-// Move detection fallback for files with no MBID (#2528, #3914). The audio stream
+// Move detection fallback for files with no MBID. The audio stream
 // hash identifies the encoded audio itself, so it survives a rename, a move and a
-// retag — anything short of a re-encode. It replaced (file_size, duration_ms),
-// which could pair two unrelated files that happened to share a byte count and a
-// duration, and missed a file retagged in place, whose size changes.
+// retag — anything short of a re-encode. (file_size, duration_ms) would pair two
+// unrelated files that share a byte count and a duration, and miss a file
+// retagged in place, whose size changes.
 //
 // Same missing-only constraint and same LIMIT 2 rationale as the MBID variant.
 func (q *Queries) FindMissingTrackByAudioHash(ctx context.Context, audioStreamSha256 []byte) ([]FindMissingTrackByAudioHashRow, error) {
@@ -249,7 +249,7 @@ type FindMissingTrackByMbidRow struct {
 	FilePath string
 }
 
-// Move detection, strongest signal (#2528). A file that turned up at a new path
+// Move detection, strongest signal. A file that turned up at a new path
 // carrying a recording MBID we already have on a MISSING row is that recording,
 // moved — not a new track.
 //
@@ -287,8 +287,8 @@ UPDATE tracks
    AND regexp_replace(file_path, '^.*/', '') ~* $1::text
 `
 
-// Holds back present tracks whose basename carries a video-rip marker (M498
-// #5439), the same pattern the report lists. A track the operator called fine
+// Holds back present tracks whose basename carries a video-rip marker, the
+// same pattern the report lists. A track an admin called fine
 // keeps that verdict.
 func (q *Queries) FlagSuspectSourceTracks(ctx context.Context, pattern string) (int64, error) {
 	result, err := q.db.Exec(ctx, flagSuspectSourceTracks, pattern)
@@ -377,7 +377,7 @@ SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, f
 `
 
 // Batched lookup used by /api/library/sync to hydrate upsert payloads
-// (#357). Mirror of GetArtistsByIDs.
+// . Mirror of GetArtistsByIDs.
 func (q *Queries) GetTracksByIDs(ctx context.Context, dollar_1 []pgtype.UUID) ([]Track, error) {
 	rows, err := q.db.Query(ctx, getTracksByIDs, dollar_1)
 	if err != nil {
@@ -451,7 +451,7 @@ type ListArtistTracksForUserRow struct {
 	ArtistName string
 }
 
-// M6a: every track for the artist across their albums, with album_title
+// Every track for the artist across their albums, with album_title
 // and artist_name joined. Honors per-user quarantine. Used by
 // /api/artists/{id}/tracks for the artist-card play affordance, which
 // shuffles client-side. Ordering matches album/track natural order so
@@ -545,19 +545,18 @@ type ListMissingTracksRow struct {
 	LastPlayedAt pgtype.Timestamptz
 }
 
-// The admin review surface for files the scan could not find (#2527).
+// The admin review surface for files the scan could not find.
 //
 // Ordered by directory, then by the file's own position within its album,
-// because the unit an operator actually reasons about is a FOLDER: the case
-// this was built for was three whole albums that had been reorganised, and a
-// flat list ordered by timestamp presents that as forty unrelated decisions.
+// because the unit an admin actually reasons about is a FOLDER: a reorganised
+// album, listed flat by timestamp, reads as dozens of unrelated decisions.
 // Grouping happens in the handler; the ordering here is what makes a group
 // contiguous, so a page boundary splits a directory at worst.
 //
 // last_played_at is a correlated MAX rather than a join so a track with no
 // plays stays in the result with NULL. It is here because "gone six months,
 // never played" and "gone yesterday, played 200 times" deserve opposite
-// reactions, and the operator can't tell them apart from a path.
+// reactions, and an admin can't tell them apart from a path.
 func (q *Queries) ListMissingTracks(ctx context.Context, arg ListMissingTracksParams) ([]ListMissingTracksRow, error) {
 	rows, err := q.db.Query(ctx, listMissingTracks, arg.PageOffset, arg.PageLimit)
 	if err != nil {
@@ -616,7 +615,7 @@ type ListRandomTracksForUserRow struct {
 	ArtistName string
 }
 
-// #427 S4: backing query for GET /api/library/shuffle — the online
+// Backing query for GET /api/library/shuffle — the online
 // source for "Shuffle all". N random tracks across the whole
 // library, per-user-quarantine filtered. $1 user_id, $2 limit.
 func (q *Queries) ListRandomTracksForUser(ctx context.Context, arg ListRandomTracksForUserParams) ([]ListRandomTracksForUserRow, error) {
@@ -682,7 +681,7 @@ type ListStillMissingTrackLabelsRow struct {
 }
 
 // Which of the tracks a scan marked missing still are once it has adopted
-// moves and folded replacements (M542): the ones worth telling an admin
+// moves and folded replacements: the ones worth telling an admin
 // about, by name. A quality upgrade folds into its replacement and drops out.
 func (q *Queries) ListStillMissingTrackLabels(ctx context.Context, ids []pgtype.UUID) ([]ListStillMissingTrackLabelsRow, error) {
 	rows, err := q.db.Query(ctx, listStillMissingTrackLabels, ids)
@@ -719,7 +718,7 @@ SELECT t.id,
        t.source_verdict,
        t.source_verdict_at,
        -- The album's place on the wanted list: wanted for a clean copy, and
-       -- when that was last searched for (#5524).
+       -- when that was last searched for.
        COALESCE(w.upgrade, '')::text AS want_upgrade,
        w.searched_at AS searched_at
   FROM tracks t
@@ -760,7 +759,7 @@ type ListSuspectSourceTracksRow struct {
 }
 
 // The admin report of present tracks whose filename looks like a video rip
-// (#5410): "(Official Video)", "[Audio]", "Visualizer" and the like.
+// : "(Official Video)", "[Audio]", "Visualizer" and the like.
 //
 // pattern is built in Go (internal/api/admin_suspect_sources.go) from the
 // same marker list that labels each row, so the filter and the labels cannot
@@ -816,7 +815,7 @@ type ListTrackPathsForReconcileRow struct {
 }
 
 // Every row's path + current missing mark, for the scanner's reconcile pass
-// (#2523). Deliberately unfiltered and unpaged: reconcile has to compare the
+// . Deliberately unfiltered and unpaged: reconcile has to compare the
 // WHOLE table against what the walk saw, and a filtered subset would let rows
 // outside it drift forever. Three narrow columns keep it cheap even on a
 // library of a few hundred thousand tracks.
@@ -921,7 +920,7 @@ type ListTracksMissingMbidWithPathRow struct {
 // Track recording-MBID backfill: tracks with NULL mbid that still have
 // a file to re-read. $1 caps the batch (mirrors the album backfill).
 // Missing tracks are skipped: there is no file, and opening it anyway
-// logged a warning per track on every scan (#5139).
+// would log a warning per track on every scan.
 func (q *Queries) ListTracksMissingMbidWithPath(ctx context.Context, limit int32) ([]ListTracksMissingMbidWithPathRow, error) {
 	rows, err := q.db.Query(ctx, listTracksMissingMbidWithPath, limit)
 	if err != nil {
@@ -1081,7 +1080,7 @@ type SetTrackSourceVerdictParams struct {
 	ID      pgtype.UUID
 }
 
-// The operator's call on a flagged track: 'fine' lets it back into radio and
+// An admin's call on a flagged track: 'fine' lets it back into radio and
 // the mixes for good; 'suspect' holds it back again.
 func (q *Queries) SetTrackSourceVerdict(ctx context.Context, arg SetTrackSourceVerdictParams) (int64, error) {
 	result, err := q.db.Exec(ctx, setTrackSourceVerdict, arg.Verdict, arg.ID)
@@ -1115,7 +1114,7 @@ ON CONFLICT (file_path) DO UPDATE SET
                        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).
+    -- next scan can short-circuit them again.
     tag_read_version = EXCLUDED.tag_read_version,
     updated_at = now()
 RETURNING id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version, tag_read_version, missing_since, mbid_source, song_id, song_key, source_verdict, source_verdict_at, emptied_at
@@ -1138,8 +1137,8 @@ type UpsertTrackParams struct {
 }
 
 // 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).
+// mbid is the file's tag. A looked-up id (mbid_source 'acoustid')
+// survives a re-read that finds no tag id, and a tag id replaces it.
 func (q *Queries) UpsertTrack(ctx context.Context, arg UpsertTrackParams) (Track, error) {
 	row := q.db.QueryRow(ctx, upsertTrack,
 		arg.Title,