refactor(library): move detection matches on the audio hash, not size and duration (M400 #3914)

A file that comes back renamed or moved keeps its track row, and with
it its likes and play history, by being matched to the missing row it
replaces (#2528). Untagged files were matched on (file_size,
duration_ms), which was never a fingerprint. It could pair two
unrelated files that happened to share a byte count and a duration,
and it missed a file retagged in place, whose size changes. The only
defence was requiring a unique match and otherwise giving up.

Now there is a real identity. FindMissingTrackByAudioHash matches a
missing track by the SHA-256 of its encoded audio (track_fingerprints,
#3906). That survives a rename, a move and a retag, and only an
identical recording can match it. adoptMovedTrack takes the new file's
hash, which the scan already computes before adoption. The size and
duration query and fallback are removed outright, with no second path
(rule 22).

Unchanged:
- MBID first: it identifies the recording and survives a re-encode
  that even the hash does not
- a unique match is still required
- an absent hash is never looked up, so unhashable files cannot pair
  with each other

The test fake answers the hash lookup only for the hash it holds, so
the tests can tell adoption by identity apart from adoption by
coincidence. That includes the case the old pair got wrong: different
audio of equal size and duration is not adopted.

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

internal/library/moved_test.go

@@ -1,6 +1,7 @@
 package library
 
 import (
+	"bytes"
 	"context"
 	"errors"
 	"testing"
@@ -10,18 +11,21 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
 )
 
+// fakeAdopter answers the audio-hash lookup only for the hash it holds, the way
+// the real query does. A fake that returned its rows for any hash could not tell
+// adoption by identity apart from adoption by coincidence.
 type fakeAdopter struct {
-	byMbid        []dbq.FindMissingTrackByMbidRow
-	byFingerprint []dbq.FindMissingTrackByFingerprintRow
+	byMbid    []dbq.FindMissingTrackByMbidRow
+	hash      []byte
+	byHash    []dbq.FindMissingTrackByAudioHashRow
+	mbidErr   error
+	hashErr   error
+	adoptErr  error
+	adoptRows int64
 
-	mbidErr        error
-	fingerprintErr error
-	adoptErr       error
-	adoptRows      int64
-
-	mbidQueried        []string
-	fingerprintQueried []dbq.FindMissingTrackByFingerprintParams
-	adopted            []dbq.AdoptTrackPathParams
+	mbidQueried []string
+	hashQueried [][]byte
+	adopted     []dbq.AdoptTrackPathParams
 }
 
 func (f *fakeAdopter) FindMissingTrackByMbid(_ context.Context, mbid string) ([]dbq.FindMissingTrackByMbidRow, error) {
@@ -29,11 +33,17 @@ func (f *fakeAdopter) FindMissingTrackByMbid(_ context.Context, mbid string) ([]
 	return f.byMbid, f.mbidErr
 }
 
-func (f *fakeAdopter) FindMissingTrackByFingerprint(
-	_ context.Context, arg dbq.FindMissingTrackByFingerprintParams,
-) ([]dbq.FindMissingTrackByFingerprintRow, error) {
-	f.fingerprintQueried = append(f.fingerprintQueried, arg)
-	return f.byFingerprint, f.fingerprintErr
+func (f *fakeAdopter) FindMissingTrackByAudioHash(
+	_ context.Context, audioStreamSha256 []byte,
+) ([]dbq.FindMissingTrackByAudioHashRow, error) {
+	f.hashQueried = append(f.hashQueried, audioStreamSha256)
+	if f.hashErr != nil {
+		return nil, f.hashErr
+	}
+	if !bytes.Equal(audioStreamSha256, f.hash) {
+		return nil, nil
+	}
+	return f.byHash, nil
 }
 
 func (f *fakeAdopter) AdoptTrackPath(_ context.Context, arg dbq.AdoptTrackPathParams) (int64, error) {
@@ -51,10 +61,12 @@ func mbidRow(n byte, path string) dbq.FindMissingTrackByMbidRow {
 	return dbq.FindMissingTrackByMbidRow{ID: testUUID(n), FilePath: path}
 }
 
-func fpRow(n byte, path string) dbq.FindMissingTrackByFingerprintRow {
-	return dbq.FindMissingTrackByFingerprintRow{ID: testUUID(n), FilePath: path}
+func hashRow(n byte, path string) dbq.FindMissingTrackByAudioHashRow {
+	return dbq.FindMissingTrackByAudioHashRow{ID: testUUID(n), FilePath: path}
 }
 
+func audioHash(b byte) []byte { return bytes.Repeat([]byte{b}, 32) }
+
 const (
 	oldPath = "/music/Linkin Park/Minutes to Midnight/02 - Bleed It Out.mp3"
 	newPath = "/music/Linkin Park/Minutes to Midnight/04 - Bleed It Out.mp3"
@@ -64,47 +76,53 @@ func TestAdoptMovedTrack_MatchesByMbid(t *testing.T) {
 	s := testScanner(t)
 	q := &fakeAdopter{byMbid: []dbq.FindMissingTrackByMbidRow{mbidRow(7, oldPath)}, adoptRows: 1}
 
-	if !s.adoptMovedTrack(context.Background(), q, newPath, 5_000_000, 200_000, "rec-mbid") {
+	if !s.adoptMovedTrack(context.Background(), q, newPath, audioHash(1), "rec-mbid") {
 		t.Fatal("expected the moved track to be adopted")
 	}
-	if len(q.adopted) != 1 {
-		t.Fatalf("adopted %d rows, want 1", len(q.adopted))
-	}
-	if q.adopted[0].ID != testUUID(7) {
-		t.Errorf("adopted the wrong row: %v", q.adopted[0].ID)
-	}
-	if q.adopted[0].FilePath != newPath {
-		t.Errorf("adopted FilePath = %q, want %q", q.adopted[0].FilePath, newPath)
+	if len(q.adopted) != 1 || q.adopted[0].ID != testUUID(7) || q.adopted[0].FilePath != newPath {
+		t.Fatalf("adopted = %+v, want row 7 at %q", q.adopted, newPath)
 	}
 	// MBID matched, so the weaker signal should not have been consulted.
-	if len(q.fingerprintQueried) != 0 {
-		t.Errorf("queried the fingerprint despite an MBID match")
+	if len(q.hashQueried) != 0 {
+		t.Errorf("queried the audio hash despite an MBID match")
 	}
 }
 
-func TestAdoptMovedTrack_FallsBackToFingerprint(t *testing.T) {
+func TestAdoptMovedTrack_FallsBackToAudioHash(t *testing.T) {
 	s := testScanner(t)
-	q := &fakeAdopter{byFingerprint: []dbq.FindMissingTrackByFingerprintRow{fpRow(3, oldPath)}, adoptRows: 1}
+	q := &fakeAdopter{hash: audioHash(3), byHash: []dbq.FindMissingTrackByAudioHashRow{hashRow(3, oldPath)}, adoptRows: 1}
 
 	// No MBID: an untagged file, which is exactly what the fallback is for.
-	if !s.adoptMovedTrack(context.Background(), q, newPath, 4_200_000, 187_000, "") {
-		t.Fatal("expected adoption via fingerprint")
+	if !s.adoptMovedTrack(context.Background(), q, newPath, audioHash(3), "") {
+		t.Fatal("expected adoption via the audio hash")
 	}
 	if len(q.mbidQueried) != 0 {
 		t.Errorf("queried by MBID with no MBID available")
 	}
-	if len(q.fingerprintQueried) != 1 {
-		t.Fatalf("fingerprint queried %d times, want 1", len(q.fingerprintQueried))
-	}
-	got := q.fingerprintQueried[0]
-	if got.FileSize != 4_200_000 || got.DurationMs != 187_000 {
-		t.Errorf("fingerprint = %+v, want size 4200000 duration 187000", got)
+	if len(q.hashQueried) != 1 || !bytes.Equal(q.hashQueried[0], audioHash(3)) {
+		t.Fatalf("hash queried = %x, want exactly the file's hash", q.hashQueried)
 	}
 	if len(q.adopted) != 1 || q.adopted[0].ID != testUUID(3) {
 		t.Errorf("adopted = %+v, want row 3", q.adopted)
 	}
 }
 
+// The case the old (file_size, duration_ms) pair got wrong: an unrelated file
+// that happens to share a size and a duration with a missing track. Size and
+// duration are no longer inputs at all; only the audio itself can match, and a
+// different recording has a different hash.
+func TestAdoptMovedTrack_DifferentAudioIsNotAdopted(t *testing.T) {
+	s := testScanner(t)
+	q := &fakeAdopter{hash: audioHash(0xAA), byHash: []dbq.FindMissingTrackByAudioHashRow{hashRow(1, oldPath)}, adoptRows: 1}
+
+	if s.adoptMovedTrack(context.Background(), q, newPath, audioHash(0xBB), "") {
+		t.Fatal("adopted a missing track whose audio differs")
+	}
+	if len(q.adopted) != 0 {
+		t.Errorf("adopted = %+v, want none", q.adopted)
+	}
+}
+
 // Two missing rows carrying the same recording MBID means real duplicates.
 // Adopting one arbitrarily would attach this file's future history to a coin
 // flip, so it must insert fresh instead.
@@ -115,7 +133,7 @@ func TestAdoptMovedTrack_RefusesAmbiguousMbidMatch(t *testing.T) {
 		mbidRow(2, "/music/b.mp3"),
 	}, adoptRows: 1}
 
-	if s.adoptMovedTrack(context.Background(), q, newPath, 0, 0, "rec-mbid") {
+	if s.adoptMovedTrack(context.Background(), q, newPath, nil, "rec-mbid") {
 		t.Fatal("expected refusal on an ambiguous MBID match")
 	}
 	if len(q.adopted) != 0 {
@@ -123,66 +141,57 @@ func TestAdoptMovedTrack_RefusesAmbiguousMbidMatch(t *testing.T) {
 	}
 }
 
-// An ambiguous MBID may still be resolvable by the fingerprint, which is a
+// An ambiguous MBID may still be resolvable by the audio hash, which is a
 // narrower signal — so falling through is allowed to succeed.
-func TestAdoptMovedTrack_AmbiguousMbidFallsThroughToFingerprint(t *testing.T) {
+func TestAdoptMovedTrack_AmbiguousMbidFallsThroughToAudioHash(t *testing.T) {
 	s := testScanner(t)
 	q := &fakeAdopter{
 		byMbid: []dbq.FindMissingTrackByMbidRow{
 			mbidRow(1, "/music/a.mp3"),
 			mbidRow(2, "/music/b.mp3"),
 		},
-		byFingerprint: []dbq.FindMissingTrackByFingerprintRow{fpRow(2, "/music/b.mp3")},
-		adoptRows:     1,
+		hash:      audioHash(2),
+		byHash:    []dbq.FindMissingTrackByAudioHashRow{hashRow(2, "/music/b.mp3")},
+		adoptRows: 1,
 	}
 
-	if !s.adoptMovedTrack(context.Background(), q, newPath, 1000, 2000, "rec-mbid") {
-		t.Fatal("expected the fingerprint to disambiguate")
+	if !s.adoptMovedTrack(context.Background(), q, newPath, audioHash(2), "rec-mbid") {
+		t.Fatal("expected the audio hash to disambiguate")
 	}
 	if len(q.adopted) != 1 || q.adopted[0].ID != testUUID(2) {
 		t.Errorf("adopted = %+v, want row 2", q.adopted)
 	}
 }
 
-func TestAdoptMovedTrack_RefusesAmbiguousFingerprintMatch(t *testing.T) {
+// Two missing tracks with identical audio are duplicates of each other; a new
+// file matching both cannot be assigned to either.
+func TestAdoptMovedTrack_RefusesAmbiguousAudioHashMatch(t *testing.T) {
 	s := testScanner(t)
-	q := &fakeAdopter{byFingerprint: []dbq.FindMissingTrackByFingerprintRow{
-		fpRow(1, "/music/a.mp3"),
-		fpRow(2, "/music/b.mp3"),
+	q := &fakeAdopter{hash: audioHash(5), byHash: []dbq.FindMissingTrackByAudioHashRow{
+		hashRow(1, "/music/a.mp3"),
+		hashRow(2, "/music/b.mp3"),
 	}, adoptRows: 1}
 
-	if s.adoptMovedTrack(context.Background(), q, newPath, 1000, 2000, "") {
-		t.Fatal("expected refusal on an ambiguous fingerprint match")
+	if s.adoptMovedTrack(context.Background(), q, newPath, audioHash(5), "") {
+		t.Fatal("expected refusal on an ambiguous audio-hash match")
 	}
 	if len(q.adopted) != 0 {
 		t.Errorf("adopted despite ambiguity: %+v", q.adopted)
 	}
 }
 
-// duration_ms is 0 when ffprobe failed. Matching 0 against 0 would pair up
-// unrelated broken files, so the fingerprint must not be attempted.
-func TestAdoptMovedTrack_SkipsFingerprintWithoutRealValues(t *testing.T) {
-	tests := []struct {
-		name     string
-		size     int64
-		duration int32
-	}{
-		{"no duration", 1000, 0},
-		{"no size", 0, 2000},
-		{"neither", 0, 0},
-	}
-	for _, tc := range tests {
-		t.Run(tc.name, func(t *testing.T) {
+// No hash means it could not be taken. An empty hash must never be looked up:
+// every unhashable file would pair with every other.
+func TestAdoptMovedTrack_SkipsAudioHashWhenAbsent(t *testing.T) {
+	for name, hash := range map[string][]byte{"nil": nil, "empty": {}} {
+		t.Run(name, func(t *testing.T) {
 			s := testScanner(t)
-			q := &fakeAdopter{
-				byFingerprint: []dbq.FindMissingTrackByFingerprintRow{fpRow(1, oldPath)},
-				adoptRows:     1,
+			q := &fakeAdopter{hash: hash, byHash: []dbq.FindMissingTrackByAudioHashRow{hashRow(1, oldPath)}, adoptRows: 1}
+			if s.adoptMovedTrack(context.Background(), q, newPath, hash, "") {
+				t.Error("adopted without an audio hash")
 			}
-			if s.adoptMovedTrack(context.Background(), q, newPath, tc.size, tc.duration, "") {
-				t.Error("adopted on an unusable fingerprint")
-			}
-			if len(q.fingerprintQueried) != 0 {
-				t.Error("queried the fingerprint with unusable values")
+			if len(q.hashQueried) != 0 {
+				t.Error("looked up an absent audio hash")
 			}
 		})
 	}
@@ -192,7 +201,7 @@ func TestAdoptMovedTrack_NoCandidates(t *testing.T) {
 	s := testScanner(t)
 	q := &fakeAdopter{adoptRows: 1}
 
-	if s.adoptMovedTrack(context.Background(), q, newPath, 1000, 2000, "rec-mbid") {
+	if s.adoptMovedTrack(context.Background(), q, newPath, audioHash(9), "rec-mbid") {
 		t.Fatal("expected no adoption when nothing matches")
 	}
 	if len(q.adopted) != 0 {
@@ -209,7 +218,7 @@ func TestAdoptMovedTrack_LostRaceReportsNotAdopted(t *testing.T) {
 		adoptRows: 0,
 	}
 
-	if s.adoptMovedTrack(context.Background(), q, newPath, 1000, 2000, "rec-mbid") {
+	if s.adoptMovedTrack(context.Background(), q, newPath, audioHash(5), "rec-mbid") {
 		t.Fatal("expected not-adopted when the update matched no rows")
 	}
 }
@@ -223,7 +232,7 @@ func TestAdoptMovedTrack_ToleratesQueryErrors(t *testing.T) {
 		q    *fakeAdopter
 	}{
 		{"mbid lookup fails", &fakeAdopter{mbidErr: sentinel}},
-		{"fingerprint lookup fails", &fakeAdopter{fingerprintErr: sentinel}},
+		{"audio hash lookup fails", &fakeAdopter{hashErr: sentinel}},
 		{"adopt fails", &fakeAdopter{
 			byMbid:   []dbq.FindMissingTrackByMbidRow{mbidRow(1, oldPath)},
 			adoptErr: sentinel,
@@ -232,24 +241,25 @@ func TestAdoptMovedTrack_ToleratesQueryErrors(t *testing.T) {
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
 			s := testScanner(t)
-			if s.adoptMovedTrack(context.Background(), tc.q, newPath, 1000, 2000, "rec-mbid") {
+			if s.adoptMovedTrack(context.Background(), tc.q, newPath, audioHash(1), "rec-mbid") {
 				t.Error("reported adoption despite a query error")
 			}
 		})
 	}
 }
 
-// A failed MBID lookup must not stop the fingerprint from being tried.
-func TestAdoptMovedTrack_MbidErrorStillTriesFingerprint(t *testing.T) {
+// A failed MBID lookup must not stop the audio hash from being tried.
+func TestAdoptMovedTrack_MbidErrorStillTriesAudioHash(t *testing.T) {
 	s := testScanner(t)
 	q := &fakeAdopter{
-		mbidErr:       errors.New("db hiccup"),
-		byFingerprint: []dbq.FindMissingTrackByFingerprintRow{fpRow(9, oldPath)},
-		adoptRows:     1,
+		mbidErr:   errors.New("db hiccup"),
+		hash:      audioHash(9),
+		byHash:    []dbq.FindMissingTrackByAudioHashRow{hashRow(9, oldPath)},
+		adoptRows: 1,
 	}
 
-	if !s.adoptMovedTrack(context.Background(), q, newPath, 1000, 2000, "rec-mbid") {
-		t.Fatal("expected the fingerprint to be tried after an MBID lookup error")
+	if !s.adoptMovedTrack(context.Background(), q, newPath, audioHash(9), "rec-mbid") {
+		t.Fatal("expected the audio hash to be tried after an MBID lookup error")
 	}
 	if len(q.adopted) != 1 || q.adopted[0].ID != testUUID(9) {
 		t.Errorf("adopted = %+v, want row 9", q.adopted)
@@ -280,9 +290,9 @@ func TestRowConverters(t *testing.T) {
 	if len(got) != 2 || got[0].id != testUUID(1) || got[1].filePath != "/b" {
 		t.Errorf("rowsFromMbid = %+v", got)
 	}
-	got = rowsFromFingerprint([]dbq.FindMissingTrackByFingerprintRow{fpRow(3, "/c")})
+	got = rowsFromAudioHash([]dbq.FindMissingTrackByAudioHashRow{hashRow(3, "/c")})
 	if len(got) != 1 || got[0].id != testUUID(3) || got[0].filePath != "/c" {
-		t.Errorf("rowsFromFingerprint = %+v", got)
+		t.Errorf("rowsFromAudioHash = %+v", got)
 	}
 }