feat(admin): the duplicates report — review proposed duplicate groups (M400 #3912)

A new admin tab, Duplicates, beside Missing files: the proposals from
the duplicate sweep, with a Sweep now trigger and a Not duplicates
dismissal. Nothing on it merges or deletes; the merge is #3911.

Each group shows:
- whether it is identical audio or the same recording, with a match
  percentage from the weakest link between members
- every copy's format, size, duration, path, and the likes and plays
  it carries (every user's; this is admin-only, and it is what decides
  which copy to keep)
- the copy proposed to keep, and the rule that chose it

The survivor rule is library.ProposeSurvivor, a pure function the
merge will reuse: lossless over lossy, then the larger file, then the
copy in the library longest, then lowest id. Bitrate is not in it
because the scanner never fills tracks.bitrate, and for one recording
at one duration a larger file is the higher bitrate. m4a is not counted
as lossless: it may be AAC. The reason names the rule that separated
first place from second, not every rule the winner passed.

An empty report has three causes, and the page says which: still
fingerprinting, the sweep has never run, or it ran and found nothing.
The sweep's state and the backfill's progress come back with the groups
for that reason. Groups left with fewer than two members since the
sweep are not shown.

GET /api/admin/library/duplicates, POST .../sweep (202, or 409
sweep_in_progress), POST .../{id}/dismiss (404
duplicate_group_not_pending when already resolved).

Migration 0060 indexes play_events by track_id. Its only indexes led
with user_id, so each copy's play count, and the merge's repointing of
play history, would scan the whole table.

Web only, like Missing files: Android has no library-health admin
screens.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SQ31KQpYbStyK5y58UmPLH

internal/db/dbq/duplicates.sql.go

@@ -27,6 +27,23 @@ func (q *Queries) AddDuplicateGroupMember(ctx context.Context, arg AddDuplicateG
 	return err
 }
 
+const countPendingDuplicateGroups = `-- name: CountPendingDuplicateGroups :one
+SELECT count(*)::bigint
+  FROM duplicate_groups g
+ WHERE g.status = 'pending'
+   AND (SELECT count(*) FROM duplicate_group_members m WHERE m.group_id = g.id) >= 2
+`
+
+// Proposals awaiting review. A group left with one member — its other tracks
+// deleted since the sweep — is no proposal at all and is not counted; the next
+// sweep retires it.
+func (q *Queries) CountPendingDuplicateGroups(ctx context.Context) (int64, error) {
+	row := q.db.QueryRow(ctx, countPendingDuplicateGroups)
+	var column_1 int64
+	err := row.Scan(&column_1)
+	return column_1, err
+}
+
 const deleteStalePendingDuplicateGroups = `-- name: DeleteStalePendingDuplicateGroups :execrows
 DELETE FROM duplicate_groups g
  WHERE g.status = 'pending'
@@ -51,6 +68,22 @@ func (q *Queries) DeleteStalePendingDuplicateGroups(ctx context.Context, sweepID
 	return result.RowsAffected(), nil
 }
 
+const dismissDuplicateGroup = `-- name: DismissDuplicateGroup :execrows
+UPDATE duplicate_groups
+   SET status = 'dismissed', resolved_at = now()
+ WHERE id = $1 AND status = 'pending'
+`
+
+// "These are not duplicates." Only a pending group can be dismissed; zero rows
+// means it was already resolved or no longer exists.
+func (q *Queries) DismissDuplicateGroup(ctx context.Context, id pgtype.UUID) (int64, error) {
+	result, err := q.db.Exec(ctx, dismissDuplicateGroup, id)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected(), nil
+}
+
 const finishDuplicateSweep = `-- name: FinishDuplicateSweep :exec
 UPDATE duplicate_sweeps
    SET finished_at       = now(),
@@ -270,6 +303,104 @@ func (q *Queries) ListExactDuplicateHashes(ctx context.Context, currentVersion i
 	return items, nil
 }
 
+const listPendingDuplicateGroupMembers = `-- name: ListPendingDuplicateGroupMembers :many
+WITH page AS (
+    SELECT g.id, g.tier, g.worst_bit_error_rate, g.detected_at
+      FROM duplicate_groups g
+     WHERE g.status = 'pending'
+       AND (SELECT count(*) FROM duplicate_group_members m WHERE m.group_id = g.id) >= 2
+     ORDER BY g.detected_at DESC, g.id
+     LIMIT $2 OFFSET $1
+)
+SELECT p.id                  AS group_id,
+       p.tier,
+       p.worst_bit_error_rate,
+       p.detected_at,
+       t.id                  AS track_id,
+       t.title,
+       artists.name          AS artist_name,
+       albums.id             AS album_id,
+       albums.title          AS album_title,
+       t.file_path,
+       t.file_format,
+       t.file_size,
+       t.duration_ms,
+       t.added_at,
+       (SELECT count(*) FROM general_likes l WHERE l.track_id = t.id)::bigint AS like_count,
+       (SELECT count(*) FROM play_events e WHERE e.track_id = t.id)::bigint   AS play_count
+  FROM page p
+  JOIN duplicate_group_members m ON m.group_id = p.id
+  JOIN tracks t  ON t.id = m.track_id
+  JOIN albums    ON albums.id  = t.album_id
+  JOIN artists   ON artists.id = t.artist_id
+ ORDER BY p.detected_at DESC, p.id, t.id
+`
+
+type ListPendingDuplicateGroupMembersParams struct {
+	PageOffset int32
+	PageLimit  int32
+}
+
+type ListPendingDuplicateGroupMembersRow struct {
+	GroupID           pgtype.UUID
+	Tier              string
+	WorstBitErrorRate *float32
+	DetectedAt        pgtype.Timestamptz
+	TrackID           pgtype.UUID
+	Title             string
+	ArtistName        string
+	AlbumID           pgtype.UUID
+	AlbumTitle        string
+	FilePath          string
+	FileFormat        string
+	FileSize          int64
+	DurationMs        int32
+	AddedAt           pgtype.Timestamptz
+	LikeCount         int64
+	PlayCount         int64
+}
+
+// One page of proposals, newest first, flattened to one row per member so the
+// handler folds them without a query per group. What each copy carries — likes
+// and plays from every user — is here because it is what the operator weighs
+// when deciding which copy to keep.
+func (q *Queries) ListPendingDuplicateGroupMembers(ctx context.Context, arg ListPendingDuplicateGroupMembersParams) ([]ListPendingDuplicateGroupMembersRow, error) {
+	rows, err := q.db.Query(ctx, listPendingDuplicateGroupMembers, arg.PageOffset, arg.PageLimit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListPendingDuplicateGroupMembersRow
+	for rows.Next() {
+		var i ListPendingDuplicateGroupMembersRow
+		if err := rows.Scan(
+			&i.GroupID,
+			&i.Tier,
+			&i.WorstBitErrorRate,
+			&i.DetectedAt,
+			&i.TrackID,
+			&i.Title,
+			&i.ArtistName,
+			&i.AlbumID,
+			&i.AlbumTitle,
+			&i.FilePath,
+			&i.FileFormat,
+			&i.FileSize,
+			&i.DurationMs,
+			&i.AddedAt,
+			&i.LikeCount,
+			&i.PlayCount,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
 const startDuplicateSweep = `-- name: StartDuplicateSweep :one
 INSERT INTO duplicate_sweeps DEFAULT VALUES RETURNING id, started_at
 `

internal/db/migrations/0060_play_events_track_index.down.sql

@@ -0,0 +1 @@
+DROP INDEX IF EXISTS play_events_track_idx;

internal/db/migrations/0060_play_events_track_index.up.sql

@@ -0,0 +1,8 @@
+-- 0060_play_events_track_index.up.sql — play_events by track (Scribe #3912, #3911).
+--
+-- play_events is indexed by (user_id, started_at) and (user_id, track_id), both
+-- led by user. Nothing reached it by track alone until the duplicates report,
+-- which shows each copy's play count — a scan of the whole table per copy — and
+-- the merge (#3911), which repoints a duplicate's play history onto the copy
+-- being kept. Both ask "every play of this track", whoever played it.
+CREATE INDEX play_events_track_idx ON play_events (track_id);

internal/db/queries/duplicates.sql

@@ -98,3 +98,55 @@ DELETE FROM duplicate_groups g
    AND (g.last_seen_sweep_id IS NULL
         OR (SELECT s.started_at FROM duplicate_sweeps s WHERE s.id = g.last_seen_sweep_id)
            < (SELECT s.started_at FROM duplicate_sweeps s WHERE s.id = sqlc.arg(sweep_id)));
+
+-- name: CountPendingDuplicateGroups :one
+-- Proposals awaiting review. A group left with one member — its other tracks
+-- deleted since the sweep — is no proposal at all and is not counted; the next
+-- sweep retires it.
+SELECT count(*)::bigint
+  FROM duplicate_groups g
+ WHERE g.status = 'pending'
+   AND (SELECT count(*) FROM duplicate_group_members m WHERE m.group_id = g.id) >= 2;
+
+-- name: ListPendingDuplicateGroupMembers :many
+-- One page of proposals, newest first, flattened to one row per member so the
+-- handler folds them without a query per group. What each copy carries — likes
+-- and plays from every user — is here because it is what the operator weighs
+-- when deciding which copy to keep.
+WITH page AS (
+    SELECT g.id, g.tier, g.worst_bit_error_rate, g.detected_at
+      FROM duplicate_groups g
+     WHERE g.status = 'pending'
+       AND (SELECT count(*) FROM duplicate_group_members m WHERE m.group_id = g.id) >= 2
+     ORDER BY g.detected_at DESC, g.id
+     LIMIT sqlc.arg(page_limit) OFFSET sqlc.arg(page_offset)
+)
+SELECT p.id                  AS group_id,
+       p.tier,
+       p.worst_bit_error_rate,
+       p.detected_at,
+       t.id                  AS track_id,
+       t.title,
+       artists.name          AS artist_name,
+       albums.id             AS album_id,
+       albums.title          AS album_title,
+       t.file_path,
+       t.file_format,
+       t.file_size,
+       t.duration_ms,
+       t.added_at,
+       (SELECT count(*) FROM general_likes l WHERE l.track_id = t.id)::bigint AS like_count,
+       (SELECT count(*) FROM play_events e WHERE e.track_id = t.id)::bigint   AS play_count
+  FROM page p
+  JOIN duplicate_group_members m ON m.group_id = p.id
+  JOIN tracks t  ON t.id = m.track_id
+  JOIN albums    ON albums.id  = t.album_id
+  JOIN artists   ON artists.id = t.artist_id
+ ORDER BY p.detected_at DESC, p.id, t.id;
+
+-- name: DismissDuplicateGroup :execrows
+-- "These are not duplicates." Only a pending group can be dismissed; zero rows
+-- means it was already resolved or no longer exists.
+UPDATE duplicate_groups
+   SET status = 'dismissed', resolved_at = now()
+ WHERE id = sqlc.arg(id) AND status = 'pending';