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/db/dbq/events.sql.go

@@ -261,7 +261,7 @@ func (q *Queries) InsertSkipEvent(ctx context.Context, arg InsertSkipEventParams
 }
 
 const listRecentSessionTracks = `-- name: ListRecentSessionTracks :many
-SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source FROM tracks t
+SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source, t.song_id, t.song_key FROM tracks t
 JOIN play_events pe ON pe.track_id = t.id
 WHERE pe.session_id = $1
   AND pe.started_at < $2
@@ -308,6 +308,8 @@ func (q *Queries) ListRecentSessionTracks(ctx context.Context, arg ListRecentSes
 			&i.TagReadVersion,
 			&i.MissingSince,
 			&i.MbidSource,
+			&i.SongID,
+			&i.SongKey,
 		); err != nil {
 			return nil, err
 		}

internal/db/dbq/history.sql.go

@@ -14,7 +14,7 @@ import (
 const listUserHistory = `-- name: ListUserHistory :many
 SELECT pe.id           AS event_id,
        pe.started_at,
-       t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source,
+       t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source, t.song_id, t.song_key,
        albums.title    AS album_title,
        artists.name    AS artist_name
   FROM play_events pe
@@ -82,6 +82,8 @@ func (q *Queries) ListUserHistory(ctx context.Context, arg ListUserHistoryParams
 			&i.Track.TagReadVersion,
 			&i.Track.MissingSince,
 			&i.Track.MbidSource,
+			&i.Track.SongID,
+			&i.Track.SongKey,
 			&i.AlbumTitle,
 			&i.ArtistName,
 		); err != nil {

internal/db/dbq/likes.sql.go

@@ -34,9 +34,12 @@ func (q *Queries) CountLikedArtists(ctx context.Context, userID pgtype.UUID) (in
 }
 
 const countLikedTracks = `-- name: CountLikedTracks :one
-SELECT count(*) FROM general_likes WHERE user_id = $1
+SELECT count(DISTINCT t.song_key) FROM general_likes l
+  JOIN tracks t ON t.id = l.track_id
+ WHERE l.user_id = $1
 `
 
+// Liked songs, each counted once however many releases hold it.
 func (q *Queries) CountLikedTracks(ctx context.Context, userID pgtype.UUID) (int64, error) {
 	row := q.db.QueryRow(ctx, countLikedTracks, userID)
 	var count int64
@@ -76,10 +79,13 @@ func (q *Queries) LikeArtist(ctx context.Context, arg LikeArtistParams) error {
 	return err
 }
 
-const likeTrack = `-- name: LikeTrack :execrows
+const likeTrack = `-- name: LikeTrack :many
 INSERT INTO general_likes (user_id, track_id)
-VALUES ($1, $2)
+SELECT $1::uuid, t.id
+  FROM tracks t
+ WHERE t.song_key = (SELECT s.song_key FROM tracks s WHERE s.id = $2::uuid)
 ON CONFLICT (user_id, track_id) DO NOTHING
+RETURNING track_id
 `
 
 type LikeTrackParams struct {
@@ -87,12 +93,27 @@ type LikeTrackParams struct {
 	TrackID pgtype.UUID
 }
 
-func (q *Queries) LikeTrack(ctx context.Context, arg LikeTrackParams) (int64, error) {
-	result, err := q.db.Exec(ctx, likeTrack, arg.UserID, arg.TrackID)
+// A like is on the song (M498 #5438): every copy of it sharing the track's
+// song_key is liked. Returns the tracks newly liked, for the sync log; empty
+// when the song was already liked.
+func (q *Queries) LikeTrack(ctx context.Context, arg LikeTrackParams) ([]pgtype.UUID, error) {
+	rows, err := q.db.Query(ctx, likeTrack, arg.UserID, arg.TrackID)
 	if err != nil {
-		return 0, err
+		return nil, err
 	}
-	return result.RowsAffected(), nil
+	defer rows.Close()
+	var items []pgtype.UUID
+	for rows.Next() {
+		var track_id pgtype.UUID
+		if err := rows.Scan(&track_id); err != nil {
+			return nil, err
+		}
+		items = append(items, track_id)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
 }
 
 const listLikedAlbumIDs = `-- name: ListLikedAlbumIDs :many
@@ -260,10 +281,14 @@ func (q *Queries) ListLikedTrackIDs(ctx context.Context, userID pgtype.UUID) ([]
 }
 
 const listLikedTrackRows = `-- name: ListLikedTrackRows :many
-SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source FROM tracks t
-JOIN general_likes l ON l.track_id = t.id
-WHERE l.user_id = $1
-ORDER BY l.liked_at DESC
+SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source, t.song_id, t.song_key FROM tracks t
+JOIN (SELECT DISTINCT ON (lt.song_key) l.track_id, l.liked_at
+        FROM general_likes l
+        JOIN tracks lt ON lt.id = l.track_id
+       WHERE l.user_id = $1
+       ORDER BY lt.song_key, (lt.missing_since IS NOT NULL), l.liked_at, lt.id) l
+  ON l.track_id = t.id
+ORDER BY l.liked_at DESC, t.id
 LIMIT $2 OFFSET $3
 `
 
@@ -273,6 +298,8 @@ type ListLikedTrackRowsParams struct {
 	Offset int32
 }
 
+// One row per liked song: of its copies, the one present on disk, then the
+// one liked first.
 func (q *Queries) ListLikedTrackRows(ctx context.Context, arg ListLikedTrackRowsParams) ([]Track, error) {
 	rows, err := q.db.Query(ctx, listLikedTrackRows, arg.UserID, arg.Limit, arg.Offset)
 	if err != nil {
@@ -303,6 +330,8 @@ func (q *Queries) ListLikedTrackRows(ctx context.Context, arg ListLikedTrackRows
 			&i.TagReadVersion,
 			&i.MissingSince,
 			&i.MbidSource,
+			&i.SongID,
+			&i.SongKey,
 		); err != nil {
 			return nil, err
 		}
@@ -342,8 +371,13 @@ func (q *Queries) UnlikeArtist(ctx context.Context, arg UnlikeArtistParams) erro
 	return err
 }
 
-const unlikeTrack = `-- name: UnlikeTrack :exec
-DELETE FROM general_likes WHERE user_id = $1 AND track_id = $2
+const unlikeTrack = `-- name: UnlikeTrack :many
+DELETE FROM general_likes
+ WHERE user_id = $1::uuid
+   AND (track_id = $2::uuid
+        OR track_id IN (SELECT t.id FROM tracks t
+                         WHERE t.song_key = (SELECT s.song_key FROM tracks s WHERE s.id = $2::uuid)))
+RETURNING track_id
 `
 
 type UnlikeTrackParams struct {
@@ -351,7 +385,24 @@ type UnlikeTrackParams struct {
 	TrackID pgtype.UUID
 }
 
-func (q *Queries) UnlikeTrack(ctx context.Context, arg UnlikeTrackParams) error {
-	_, err := q.db.Exec(ctx, unlikeTrack, arg.UserID, arg.TrackID)
-	return err
+// Unlikes the song: every copy sharing the track's song_key. Returns the
+// tracks unliked, for the sync log.
+func (q *Queries) UnlikeTrack(ctx context.Context, arg UnlikeTrackParams) ([]pgtype.UUID, error) {
+	rows, err := q.db.Query(ctx, unlikeTrack, arg.UserID, arg.TrackID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []pgtype.UUID
+	for rows.Next() {
+		var track_id pgtype.UUID
+		if err := rows.Scan(&track_id); err != nil {
+			return nil, err
+		}
+		items = append(items, track_id)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
 }

internal/db/dbq/models.go

@@ -754,6 +754,8 @@ type Track struct {
 	TagReadVersion    int16
 	MissingSince      pgtype.Timestamptz
 	MbidSource        *string
+	SongID            pgtype.UUID
+	SongKey           pgtype.UUID
 }
 
 type TrackAcoustidLookup struct {

internal/db/dbq/recommendation.sql.go

@@ -208,7 +208,7 @@ WITH plays AS (
     WHERE user_id = $2 AND was_skipped = false
     GROUP BY track_id
 )
-SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source,
+SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source, t.song_id, t.song_key,
        albums.title AS album_title,
        artists.name AS artist_name
 FROM plays p
@@ -271,6 +271,8 @@ func (q *Queries) ListMostPlayedTracksForArtist(ctx context.Context, arg ListMos
 			&i.Track.TagReadVersion,
 			&i.Track.MissingSince,
 			&i.Track.MbidSource,
+			&i.Track.SongID,
+			&i.Track.SongKey,
 			&i.AlbumTitle,
 			&i.ArtistName,
 		); err != nil {
@@ -291,7 +293,7 @@ WITH plays AS (
     WHERE user_id = $1 AND was_skipped = false
     GROUP BY track_id
 )
-SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source,
+SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source, t.song_id, t.song_key,
        albums.title AS album_title,
        artists.name AS artist_name
 FROM plays p
@@ -356,6 +358,8 @@ func (q *Queries) ListMostPlayedTracksForUser(ctx context.Context, arg ListMostP
 			&i.Track.TagReadVersion,
 			&i.Track.MissingSince,
 			&i.Track.MbidSource,
+			&i.Track.SongID,
+			&i.Track.SongKey,
 			&i.AlbumTitle,
 			&i.ArtistName,
 		); err != nil {
@@ -695,7 +699,7 @@ func (q *Queries) ListRediscoverArtistsForUser(ctx context.Context, arg ListRedi
 
 const loadRadioCandidates = `-- name: LoadRadioCandidates :many
 SELECT
-    t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source,
+    t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source, t.song_id, t.song_key,
     (l.user_id IS NOT NULL)::bool AS is_liked,
     pe.last_played_at::timestamptz AS last_played_at,
     pe.play_count,
@@ -777,6 +781,8 @@ func (q *Queries) LoadRadioCandidates(ctx context.Context, arg LoadRadioCandidat
 			&i.Track.TagReadVersion,
 			&i.Track.MissingSince,
 			&i.Track.MbidSource,
+			&i.Track.SongID,
+			&i.Track.SongKey,
 			&i.IsLiked,
 			&i.LastPlayedAt,
 			&i.PlayCount,
@@ -925,7 +931,7 @@ random_fill AS (
     LIMIT $9
 )
 SELECT
-    t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source,
+    t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source, t.song_id, t.song_key,
     (l.user_id IS NOT NULL)::bool AS is_liked,
     pe.last_played_at::timestamptz AS last_played_at,
     pe.play_count,
@@ -1053,6 +1059,8 @@ func (q *Queries) LoadRadioCandidatesV2(ctx context.Context, arg LoadRadioCandid
 			&i.Track.TagReadVersion,
 			&i.Track.MissingSince,
 			&i.Track.MbidSource,
+			&i.Track.SongID,
+			&i.Track.SongKey,
 			&i.IsLiked,
 			&i.LastPlayedAt,
 			&i.PlayCount,

internal/db/dbq/songs.sql.go

@@ -0,0 +1,150 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: songs.sql
+
+package dbq
+
+import (
+	"context"
+
+	"github.com/jackc/pgx/v5/pgtype"
+)
+
+const linkTracksAsSong = `-- name: LinkTracksAsSong :one
+
+WITH keys AS (
+    SELECT DISTINCT song_key FROM tracks WHERE id = ANY($1::uuid[])
+), target AS (
+    SELECT song_key FROM keys ORDER BY song_key LIMIT 1
+), moved AS (
+    UPDATE tracks t
+       SET song_id = (SELECT song_key FROM target)
+     WHERE t.song_key IN (SELECT song_key FROM keys)
+       AND t.song_key <> (SELECT song_key FROM target)
+    RETURNING t.id
+)
+SELECT (SELECT song_key FROM target)::uuid AS song_key,
+       (SELECT count(*) FROM moved)::bigint AS moved
+`
+
+type LinkTracksAsSongRow struct {
+	SongKey pgtype.UUID
+	Moved   int64
+}
+
+// Song links (M498 #5438): copies of one song on different releases share a
+// song_key (migration 0076).
+// Links the tracks into one song, joining any songs they already belong to.
+// The song keeps the lowest key among them, so linking the same set again
+// changes nothing. Returns that key and how many tracks moved to it.
+func (q *Queries) LinkTracksAsSong(ctx context.Context, trackIds []pgtype.UUID) (LinkTracksAsSongRow, error) {
+	row := q.db.QueryRow(ctx, linkTracksAsSong, trackIds)
+	var i LinkTracksAsSongRow
+	err := row.Scan(&i.SongKey, &i.Moved)
+	return i, err
+}
+
+const listTrackSongKeys = `-- name: ListTrackSongKeys :many
+SELECT id, song_key FROM tracks WHERE id = ANY($1::uuid[])
+`
+
+type ListTrackSongKeysRow struct {
+	ID      pgtype.UUID
+	SongKey pgtype.UUID
+}
+
+func (q *Queries) ListTrackSongKeys(ctx context.Context, ids []pgtype.UUID) ([]ListTrackSongKeysRow, error) {
+	rows, err := q.db.Query(ctx, listTrackSongKeys, ids)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListTrackSongKeysRow
+	for rows.Next() {
+		var i ListTrackSongKeysRow
+		if err := rows.Scan(&i.ID, &i.SongKey); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const mergeInheritSongLink = `-- name: MergeInheritSongLink :exec
+UPDATE tracks s
+   SET song_id = l.song_key
+  FROM tracks l
+ WHERE s.id = $1::uuid
+   AND l.id = $2::uuid
+   AND s.song_id IS NULL
+   AND l.song_key <> l.id
+`
+
+type MergeInheritSongLinkParams struct {
+	SurvivorID pgtype.UUID
+	LoserID    pgtype.UUID
+}
+
+// A merge keeps the removed copy's song link: when the copy being removed was
+// linked to copies on other releases and the survivor was not, the survivor
+// joins that song.
+func (q *Queries) MergeInheritSongLink(ctx context.Context, arg MergeInheritSongLinkParams) error {
+	_, err := q.db.Exec(ctx, mergeInheritSongLink, arg.SurvivorID, arg.LoserID)
+	return err
+}
+
+const shareSongLikes = `-- name: ShareSongLikes :many
+INSERT INTO general_likes (user_id, track_id, liked_at)
+SELECT l.user_id, t.id, min(l.liked_at)
+  FROM general_likes l
+  JOIN tracks lt ON lt.id = l.track_id
+  JOIN tracks t  ON t.song_key = lt.song_key
+ WHERE lt.song_key = $1::uuid
+ GROUP BY l.user_id, t.id
+ON CONFLICT (user_id, track_id) DO NOTHING
+RETURNING user_id, track_id
+`
+
+type ShareSongLikesRow struct {
+	UserID  pgtype.UUID
+	TrackID pgtype.UUID
+}
+
+// A like on any copy of the song becomes a like on every copy, dated the
+// earliest. Returns the likes added, for the sync log.
+func (q *Queries) ShareSongLikes(ctx context.Context, songKey pgtype.UUID) ([]ShareSongLikesRow, error) {
+	rows, err := q.db.Query(ctx, shareSongLikes, songKey)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ShareSongLikesRow
+	for rows.Next() {
+		var i ShareSongLikesRow
+		if err := rows.Scan(&i.UserID, &i.TrackID); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const unlinkDuplicateGroupSongs = `-- name: UnlinkDuplicateGroupSongs :exec
+UPDATE tracks SET song_id = NULL
+ WHERE song_id IS NOT NULL
+   AND id IN (SELECT track_id FROM duplicate_group_members WHERE group_id = $1)
+`
+
+// "Not the same song": the group's copies stop sharing a song. Likes already
+// shared stay where they are.
+func (q *Queries) UnlinkDuplicateGroupSongs(ctx context.Context, groupID pgtype.UUID) error {
+	_, err := q.db.Exec(ctx, unlinkDuplicateGroupSongs, groupID)
+	return err
+}

internal/db/dbq/tracks.sql.go

@@ -247,7 +247,7 @@ func (q *Queries) FindMissingTrackByMbid(ctx context.Context, mbid string) ([]Fi
 }
 
 const getTrackByID = `-- name: GetTrackByID :one
-SELECT 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 FROM tracks WHERE id = $1
+SELECT 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 FROM tracks WHERE id = $1
 `
 
 func (q *Queries) GetTrackByID(ctx context.Context, id pgtype.UUID) (Track, error) {
@@ -274,12 +274,14 @@ func (q *Queries) GetTrackByID(ctx context.Context, id pgtype.UUID) (Track, erro
 		&i.TagReadVersion,
 		&i.MissingSince,
 		&i.MbidSource,
+		&i.SongID,
+		&i.SongKey,
 	)
 	return i, err
 }
 
 const getTrackByPath = `-- name: GetTrackByPath :one
-SELECT 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 FROM tracks WHERE file_path = $1
+SELECT 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 FROM tracks WHERE file_path = $1
 `
 
 func (q *Queries) GetTrackByPath(ctx context.Context, filePath string) (Track, error) {
@@ -306,12 +308,14 @@ func (q *Queries) GetTrackByPath(ctx context.Context, filePath string) (Track, e
 		&i.TagReadVersion,
 		&i.MissingSince,
 		&i.MbidSource,
+		&i.SongID,
+		&i.SongKey,
 	)
 	return i, err
 }
 
 const getTracksByIDs = `-- name: GetTracksByIDs :many
-SELECT 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 FROM tracks WHERE id = ANY($1::uuid[])
+SELECT 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 FROM tracks WHERE id = ANY($1::uuid[])
 `
 
 // Batched lookup used by /api/library/sync to hydrate upsert payloads
@@ -346,6 +350,8 @@ func (q *Queries) GetTracksByIDs(ctx context.Context, dollar_1 []pgtype.UUID) ([
 			&i.TagReadVersion,
 			&i.MissingSince,
 			&i.MbidSource,
+			&i.SongID,
+			&i.SongKey,
 		); err != nil {
 			return nil, err
 		}
@@ -358,7 +364,7 @@ func (q *Queries) GetTracksByIDs(ctx context.Context, dollar_1 []pgtype.UUID) ([
 }
 
 const listArtistTracksForUser = `-- name: ListArtistTracksForUser :many
-SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source,
+SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source, t.song_id, t.song_key,
        albums.title AS album_title,
        artists.name AS artist_name
 FROM tracks t
@@ -419,6 +425,8 @@ func (q *Queries) ListArtistTracksForUser(ctx context.Context, arg ListArtistTra
 			&i.Track.TagReadVersion,
 			&i.Track.MissingSince,
 			&i.Track.MbidSource,
+			&i.Track.SongID,
+			&i.Track.SongKey,
 			&i.AlbumTitle,
 			&i.ArtistName,
 		); err != nil {
@@ -519,7 +527,7 @@ func (q *Queries) ListMissingTracks(ctx context.Context, arg ListMissingTracksPa
 }
 
 const listRandomTracksForUser = `-- name: ListRandomTracksForUser :many
-SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source,
+SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at, t.tag_source, t.tag_sources_version, t.tag_read_version, t.missing_since, t.mbid_source, t.song_id, t.song_key,
        albums.title AS album_title,
        artists.name AS artist_name
 FROM tracks t
@@ -577,6 +585,8 @@ func (q *Queries) ListRandomTracksForUser(ctx context.Context, arg ListRandomTra
 			&i.Track.TagReadVersion,
 			&i.Track.MissingSince,
 			&i.Track.MbidSource,
+			&i.Track.SongID,
+			&i.Track.SongKey,
 			&i.AlbumTitle,
 			&i.ArtistName,
 		); err != nil {
@@ -709,7 +719,7 @@ func (q *Queries) ListTrackPathsForReconcile(ctx context.Context) ([]ListTrackPa
 }
 
 const listTracksByAlbum = `-- name: ListTracksByAlbum :many
-SELECT 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 FROM tracks
+SELECT 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 FROM tracks
 WHERE album_id = $1
   AND NOT EXISTS (
     SELECT 1 FROM lidarr_quarantine q
@@ -756,6 +766,8 @@ func (q *Queries) ListTracksByAlbum(ctx context.Context, arg ListTracksByAlbumPa
 			&i.TagReadVersion,
 			&i.MissingSince,
 			&i.MbidSource,
+			&i.SongID,
+			&i.SongKey,
 		); err != nil {
 			return nil, err
 		}
@@ -829,7 +841,7 @@ func (q *Queries) MarkTracksMissing(ctx context.Context, ids []pgtype.UUID) (int
 }
 
 const searchTracks = `-- name: SearchTracks :many
-SELECT 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 FROM tracks
+SELECT 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 FROM tracks
 WHERE title ILIKE '%' || $1::text || '%'
   AND NOT EXISTS (
     SELECT 1 FROM lidarr_quarantine q
@@ -883,6 +895,8 @@ func (q *Queries) SearchTracks(ctx context.Context, arg SearchTracksParams) ([]T
 			&i.TagReadVersion,
 			&i.MissingSince,
 			&i.MbidSource,
+			&i.SongID,
+			&i.SongKey,
 		); err != nil {
 			return nil, err
 		}
@@ -939,7 +953,7 @@ ON CONFLICT (file_path) DO UPDATE SET
     -- next scan can short-circuit them again (#2499).
     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
+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
 `
 
 type UpsertTrackParams struct {
@@ -999,6 +1013,8 @@ func (q *Queries) UpsertTrack(ctx context.Context, arg UpsertTrackParams) (Track
 		&i.TagReadVersion,
 		&i.MissingSince,
 		&i.MbidSource,
+		&i.SongID,
+		&i.SongKey,
 	)
 	return i, err
 }

internal/db/migrations/0076_track_song_link.down.sql

@@ -0,0 +1,3 @@
+DROP INDEX IF EXISTS tracks_song_key_idx;
+ALTER TABLE tracks DROP COLUMN IF EXISTS song_key;
+ALTER TABLE tracks DROP COLUMN IF EXISTS song_id;

internal/db/migrations/0076_track_song_link.up.sql

@@ -0,0 +1,15 @@
+-- 0076_track_song_link.up.sql — the same song on several releases counts as
+-- one song (Scribe milestone #498, #5438; operator decision D-b).
+--
+-- A single and the album it came from each hold the song, and Lidarr keeps
+-- both: each fulfils its own release. Minstrel keeps both files and links
+-- them, so a like on one is a like on the song, and a mix or radio picks the
+-- song once rather than once per release.
+--
+-- song_id is set only on a linked track, to the song_key the link chose.
+-- song_key is what everything reads: the track's own id until it is linked.
+-- No foreign key: the track whose id names a song may itself be merged away
+-- later, and the key still groups the copies left.
+ALTER TABLE tracks ADD COLUMN song_id uuid;
+ALTER TABLE tracks ADD COLUMN song_key uuid GENERATED ALWAYS AS (COALESCE(song_id, id)) STORED;
+CREATE INDEX tracks_song_key_idx ON tracks (song_key);

internal/db/queries/likes.sql

@@ -1,20 +1,42 @@
--- name: LikeTrack :execrows
+-- name: LikeTrack :many
+-- A like is on the song (M498 #5438): every copy of it sharing the track's
+-- song_key is liked. Returns the tracks newly liked, for the sync log; empty
+-- when the song was already liked.
 INSERT INTO general_likes (user_id, track_id)
-VALUES ($1, $2)
-ON CONFLICT (user_id, track_id) DO NOTHING;
+SELECT sqlc.arg(user_id)::uuid, t.id
+  FROM tracks t
+ WHERE t.song_key = (SELECT s.song_key FROM tracks s WHERE s.id = sqlc.arg(track_id)::uuid)
+ON CONFLICT (user_id, track_id) DO NOTHING
+RETURNING track_id;
 
--- name: UnlikeTrack :exec
-DELETE FROM general_likes WHERE user_id = $1 AND track_id = $2;
+-- name: UnlikeTrack :many
+-- Unlikes the song: every copy sharing the track's song_key. Returns the
+-- tracks unliked, for the sync log.
+DELETE FROM general_likes
+ WHERE user_id = sqlc.arg(user_id)::uuid
+   AND (track_id = sqlc.arg(track_id)::uuid
+        OR track_id IN (SELECT t.id FROM tracks t
+                         WHERE t.song_key = (SELECT s.song_key FROM tracks s WHERE s.id = sqlc.arg(track_id)::uuid)))
+RETURNING track_id;
 
 -- name: ListLikedTrackRows :many
+-- One row per liked song: of its copies, the one present on disk, then the
+-- one liked first.
 SELECT t.* FROM tracks t
-JOIN general_likes l ON l.track_id = t.id
-WHERE l.user_id = $1
-ORDER BY l.liked_at DESC
+JOIN (SELECT DISTINCT ON (lt.song_key) l.track_id, l.liked_at
+        FROM general_likes l
+        JOIN tracks lt ON lt.id = l.track_id
+       WHERE l.user_id = $1
+       ORDER BY lt.song_key, (lt.missing_since IS NOT NULL), l.liked_at, lt.id) l
+  ON l.track_id = t.id
+ORDER BY l.liked_at DESC, t.id
 LIMIT $2 OFFSET $3;
 
 -- name: CountLikedTracks :one
-SELECT count(*) FROM general_likes WHERE user_id = $1;
+-- Liked songs, each counted once however many releases hold it.
+SELECT count(DISTINCT t.song_key) FROM general_likes l
+  JOIN tracks t ON t.id = l.track_id
+ WHERE l.user_id = $1;
 
 -- name: ListLikedTrackIDs :many
 SELECT track_id FROM general_likes WHERE user_id = $1 ORDER BY liked_at DESC;

internal/db/queries/songs.sql

@@ -0,0 +1,55 @@
+-- Song links (M498 #5438): copies of one song on different releases share a
+-- song_key (migration 0076).
+
+-- name: LinkTracksAsSong :one
+-- Links the tracks into one song, joining any songs they already belong to.
+-- The song keeps the lowest key among them, so linking the same set again
+-- changes nothing. Returns that key and how many tracks moved to it.
+WITH keys AS (
+    SELECT DISTINCT song_key FROM tracks WHERE id = ANY(sqlc.arg(track_ids)::uuid[])
+), target AS (
+    SELECT song_key FROM keys ORDER BY song_key LIMIT 1
+), moved AS (
+    UPDATE tracks t
+       SET song_id = (SELECT song_key FROM target)
+     WHERE t.song_key IN (SELECT song_key FROM keys)
+       AND t.song_key <> (SELECT song_key FROM target)
+    RETURNING t.id
+)
+SELECT (SELECT song_key FROM target)::uuid AS song_key,
+       (SELECT count(*) FROM moved)::bigint AS moved;
+
+-- name: ShareSongLikes :many
+-- A like on any copy of the song becomes a like on every copy, dated the
+-- earliest. Returns the likes added, for the sync log.
+INSERT INTO general_likes (user_id, track_id, liked_at)
+SELECT l.user_id, t.id, min(l.liked_at)
+  FROM general_likes l
+  JOIN tracks lt ON lt.id = l.track_id
+  JOIN tracks t  ON t.song_key = lt.song_key
+ WHERE lt.song_key = sqlc.arg(song_key)::uuid
+ GROUP BY l.user_id, t.id
+ON CONFLICT (user_id, track_id) DO NOTHING
+RETURNING user_id, track_id;
+
+-- name: UnlinkDuplicateGroupSongs :exec
+-- "Not the same song": the group's copies stop sharing a song. Likes already
+-- shared stay where they are.
+UPDATE tracks SET song_id = NULL
+ WHERE song_id IS NOT NULL
+   AND id IN (SELECT track_id FROM duplicate_group_members WHERE group_id = sqlc.arg(group_id));
+
+-- name: ListTrackSongKeys :many
+SELECT id, song_key FROM tracks WHERE id = ANY(sqlc.arg(ids)::uuid[]);
+
+-- name: MergeInheritSongLink :exec
+-- A merge keeps the removed copy's song link: when the copy being removed was
+-- linked to copies on other releases and the survivor was not, the survivor
+-- joins that song.
+UPDATE tracks s
+   SET song_id = l.song_key
+  FROM tracks l
+ WHERE s.id = sqlc.arg(survivor_id)::uuid
+   AND l.id = sqlc.arg(loser_id)::uuid
+   AND s.song_id IS NULL
+   AND l.song_key <> l.id;