docs(db/m7-coverage-gauge): note CHECK-constraint sync + bucket invariant

Code-review polish on GetAlbumCoverageRollup's comment block:
- Records the invariant that with_art + pending + settled = total
  (and that pending_no_mbid is a subset of pending, not a fourth
  bucket).
- Notes that the IN ('sidecar','embedded','mbcaa') list must stay
  in sync with the cover_art_source CHECK constraint in migration
  0016 — without this note a future source addition could silently
  undercount with_art.
This commit is contained in:
2026-05-06 09:52:10 -04:00
parent 98ec64c658
commit ff5868bdab
2 changed files with 16 additions and 0 deletions
+8
View File
@@ -145,6 +145,14 @@ type GetAlbumCoverageRollupRow struct {
// of pending; the UI surfaces it separately so operators can see how
// many "pending" albums are blocked on missing MBID and won't be
// helped by another scan.
//
// 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 ('sidecar','embedded','mbcaa') must stay in sync
// with the cover_art_source CHECK constraint in migration
// 0016_album_cover_source.up.sql. If a new source value is added there
// without updating this query, with_art will silently undercount.
func (q *Queries) GetAlbumCoverageRollup(ctx context.Context) (GetAlbumCoverageRollupRow, error) {
row := q.db.QueryRow(ctx, getAlbumCoverageRollup)
var i GetAlbumCoverageRollupRow
+8
View File
@@ -132,6 +132,14 @@ SELECT a.id AS album_id,
-- of pending; the UI surfaces it separately so operators can see how
-- many "pending" albums are blocked on missing MBID and won't be
-- helped by another scan.
--
-- 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 ('sidecar','embedded','mbcaa') must stay in sync
-- with the cover_art_source CHECK constraint in migration
-- 0016_album_cover_source.up.sql. If a new source value is added there
-- without updating this query, with_art will silently undercount.
SELECT
COUNT(*) AS total,
COUNT(*) FILTER (WHERE cover_art_source IN ('sidecar','embedded','mbcaa')) AS with_art,