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
+8 -8
View File
@@ -1,26 +1,26 @@
-- Missing-pair pass (M485). A track marked missing whose replacement is already
-- Missing-pair pass. A track marked missing whose replacement is already
-- on disk under another row — most often a quality upgrade, mp3 → flac at a new
-- path — is folded into that replacement, so its history moves across and
-- re-acquisition stops chasing music the library already has.
--
-- Move adoption (#2528) cannot catch these: it links a new file to a missing row
-- Move adoption cannot catch these: it links a new file to a missing row
-- at the moment the file is first inserted, and the replacement arrives as a
-- re-encode with no recording MBID, so it has nothing to match on. AcoustID may
-- give it an MBID later; by then both rows exist and only a fold can join them.
-- name: ListMissingTrackPairs :many
-- Every candidate (missing, present) pair, with how many candidates each side
-- has. Two rules, measured on the operator's library on 2026-10-07 (#5274):
-- has. Two rules:
--
-- mbid the same recording MBID, within the album group (the album row, or
-- albums sharing a release group). 142 of 359 pairs.
-- title the same album row and the same title, ignoring case. 213 more. The
-- albums sharing a release group).
-- title the same album row and the same title, ignoring case. The
-- replacements are often not the original file — another edition,
-- re-encoded, untagged — so the metadata is what is left to go on.
--
-- Deliberately NOT gated on duration or track position. On the 142 pairs known
-- to be one recording, 18% differed by over 2s (old mp3 durations are poor
-- estimates), and the poorly tagged set is exactly where numbering is broken.
-- Deliberately NOT gated on duration or track position. Pairs known to be one
-- recording often differ by over 2s (old mp3 durations are poor estimates),
-- and the poorly tagged set is exactly where numbering is broken.
--
-- A pair whose MBIDs are both set and differ is not a title match: the tags say
-- they are different recordings. The caller folds a pair only when each side has