feat: the same song on several releases counts as one song (M498 #5438)

A single and the album it is on stay two files, since each fulfils its own
release in Lidarr, but they are one song to the listener.

- tracks.song_id links copies; the generated song_key (song_id, else the
  track's own id) is what they share (migration 0076).
- The resolver links each cross-release group every pass (idempotent; only
  with auto-resolve on) and, when a link is new, shares existing likes across
  the song and logs them for sync.
- A like or unlike (web and Subsonic) reaches every copy; each change is
  logged and published so clients update every heart.
- The Liked list and its count show the song once; Shuffle and the mix writer
  take one copy per song.
- A merge keeps the removed copy's song link; "Not the same song" on the
  Across releases tab dismisses the group and undoes the link.

Shared plays ("heard via another copy") are left for a later step.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

internal/recommendation/shuffle.go

@@ -104,11 +104,24 @@ func Shuffle(
 	deferred := make([]Candidate, 0, len(scored)-limit)
 	artistCount := map[pgtype.UUID]int{}
 	albumCount := map[pgtype.UUID]int{}
+	// One song on several releases is played once (M498 #5438): after its
+	// best-scoring copy, the others are dropped, not held back.
+	songs := map[pgtype.UUID]bool{}
+	repeat := func(c Candidate) bool { return c.Track.SongKey.Valid && songs[c.Track.SongKey] }
+	take := func(c Candidate) {
+		if c.Track.SongKey.Valid {
+			songs[c.Track.SongKey] = true
+		}
+		out = append(out, c)
+	}
 
 	for _, s := range scored {
 		if len(out) == limit {
 			break
 		}
+		if repeat(s.c) {
+			continue
+		}
 		overArtist := caps.MaxPerArtist > 0 && artistCount[s.c.Track.ArtistID] >= caps.MaxPerArtist
 		overAlbum := caps.MaxPerAlbum > 0 && albumCount[s.c.Track.AlbumID] >= caps.MaxPerAlbum
 		if overArtist || overAlbum {
@@ -118,7 +131,7 @@ func Shuffle(
 		}
 		artistCount[s.c.Track.ArtistID]++
 		albumCount[s.c.Track.AlbumID]++
-		out = append(out, s.c)
+		take(s.c)
 	}
 
 	// Pass two: the caps could not fill the request, so relax them rather
@@ -128,7 +141,10 @@ func Shuffle(
 		if len(out) == limit {
 			break
 		}
-		out = append(out, c)
+		if repeat(c) {
+			continue
+		}
+		take(c)
 	}
 	return out
 }

internal/recommendation/shuffle_test.go

@@ -84,3 +84,30 @@ func titles(cs []Candidate) []string {
 // pure tests; the Track.Title field is the human-readable handle. Track ID
 // is left as zero pgtype.UUID and never compared.
 var _ pgtype.UUID
+
+// One song on two releases is played once, in its better-scoring copy's place,
+// and a capped copy held back for pass two does not slip back in either.
+func TestShuffle_OneCopyPerSong(t *testing.T) {
+	song := func(c Candidate, key string) Candidate {
+		_ = c.Track.SongKey.Scan("00000000-0000-0000-0000-" + key)
+		return c
+	}
+	album := pgtype.UUID{Bytes: [16]byte{9}, Valid: true}
+	single := song(cand("000000000001", ScoringInputs{IsGeneralLiked: true}), "00000000000a")
+	albumCut := song(cand("000000000002", ScoringInputs{}), "00000000000a")
+	other := cand("000000000003", ScoringInputs{})
+	single.Track.AlbumID, albumCut.Track.AlbumID = album, pgtype.UUID{Bytes: [16]byte{8}, Valid: true}
+
+	out := Shuffle([]Candidate{albumCut, single, other}, defaultWeights(), time.Now(), fixedRNG(0.5), 10, DiversityCaps{})
+	if got := titles(out); len(got) != 2 || got[0] != "000000000001" {
+		t.Errorf("got %v, want the liked single once and the other song", got)
+	}
+
+	// The single is capped out of pass one; pass two takes one copy, not both.
+	capped := cand("000000000004", ScoringInputs{IsGeneralLiked: true})
+	capped.Track.AlbumID = album
+	out = Shuffle([]Candidate{capped, single, albumCut}, defaultWeights(), time.Now(), fixedRNG(0.5), 3, DiversityCaps{MaxPerAlbum: 1})
+	if len(out) != 2 {
+		t.Errorf("got %v, want two tracks: one copy of the song", titles(out))
+	}
+}