feat(admin): fingerprinting settings — on/off, length, match threshold, concurrency, sweep interval (M400 #3913)

Rule 25: the fingerprinting knobs move out of source into a DB-backed
singleton (migration 0061), edited from a card on the Duplicates page and
shared live with the scanner, the backfill and the duplicate sweep through
one service instance, so a save needs no restart.

The length is the knob that can silently break the library: prints taken
at two lengths never match. Each track_fingerprints row now records the
length it was taken at, and every reader filters on the current one — the
backfill treats another length as stale, the gauge counts it pending, the
sweep never streams it. Equivalent to a version bump, except that setting
the length back makes rows not yet redone current again. The card warns
before a length change re-fingerprints the library.

Off stops every decode: the scan takes only the stream hash (a demux, and
what recognises a moved file) and stores nothing, dropping a changed file's
stale row; the backfill idles. A save also makes a sweep due, since a new
threshold or length changes what the same prints group into, and the sweep
interval gains slack so an hourly interval on an hourly tick doesn't skip
every other tick.

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

@@ -211,16 +211,21 @@ SELECT t.id, t.duration_ms, f.audio_stream_sha256, f.chromaprint
  WHERE t.missing_since IS NULL
    AND f.fingerprint_version >= $1
    AND f.chromaprint IS NOT NULL
-   AND (t.duration_ms, t.id) > ($2::integer, $3::uuid)
+   -- Only chromaprints taken at the current length: prints at two lengths are not
+   -- comparable, and after a length change the backfill is still re-deriving the
+   -- rest (#3913).
+   AND f.chromaprint_length_sec = $2
+   AND (t.duration_ms, t.id) > ($3::integer, $4::uuid)
  ORDER BY t.duration_ms, t.id
- LIMIT $4
+ LIMIT $5
 `
 
 type ListDuplicateCandidatesParams struct {
-	CurrentVersion  int16
-	AfterDurationMs int32
-	AfterID         pgtype.UUID
-	PageLimit       int32
+	CurrentVersion       int16
+	ChromaprintLengthSec int32
+	AfterDurationMs      int32
+	AfterID              pgtype.UUID
+	PageLimit            int32
 }
 
 type ListDuplicateCandidatesRow struct {
@@ -237,6 +242,7 @@ type ListDuplicateCandidatesRow struct {
 func (q *Queries) ListDuplicateCandidates(ctx context.Context, arg ListDuplicateCandidatesParams) ([]ListDuplicateCandidatesRow, error) {
 	rows, err := q.db.Query(ctx, listDuplicateCandidates,
 		arg.CurrentVersion,
+		arg.ChromaprintLengthSec,
 		arg.AfterDurationMs,
 		arg.AfterID,
 		arg.PageLimit,

internal/db/dbq/fingerprint_settings.sql.go

@@ -0,0 +1,72 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: fingerprint_settings.sql
+
+package dbq
+
+import (
+	"context"
+)
+
+const getFingerprintSettings = `-- name: GetFingerprintSettings :one
+SELECT id, enabled, chromaprint_length_sec, acoustic_max_bit_error_rate, backfill_concurrency, sweep_interval_hours, updated_at FROM fingerprint_settings WHERE id = true
+`
+
+func (q *Queries) GetFingerprintSettings(ctx context.Context) (FingerprintSetting, error) {
+	row := q.db.QueryRow(ctx, getFingerprintSettings)
+	var i FingerprintSetting
+	err := row.Scan(
+		&i.ID,
+		&i.Enabled,
+		&i.ChromaprintLengthSec,
+		&i.AcousticMaxBitErrorRate,
+		&i.BackfillConcurrency,
+		&i.SweepIntervalHours,
+		&i.UpdatedAt,
+	)
+	return i, err
+}
+
+const updateFingerprintSettings = `-- name: UpdateFingerprintSettings :one
+UPDATE fingerprint_settings
+   SET enabled                     = $1,
+       chromaprint_length_sec      = $2,
+       acoustic_max_bit_error_rate = $3,
+       backfill_concurrency        = $4,
+       sweep_interval_hours        = $5,
+       updated_at                  = now()
+ WHERE id = true
+RETURNING id, enabled, chromaprint_length_sec, acoustic_max_bit_error_rate, backfill_concurrency, sweep_interval_hours, updated_at
+`
+
+type UpdateFingerprintSettingsParams struct {
+	Enabled                 bool
+	ChromaprintLengthSec    int32
+	AcousticMaxBitErrorRate float64
+	BackfillConcurrency     int32
+	SweepIntervalHours      int32
+}
+
+// Whole-row write from the admin card; migration 0061's CHECKs are the backstop
+// behind the service's own validation.
+func (q *Queries) UpdateFingerprintSettings(ctx context.Context, arg UpdateFingerprintSettingsParams) (FingerprintSetting, error) {
+	row := q.db.QueryRow(ctx, updateFingerprintSettings,
+		arg.Enabled,
+		arg.ChromaprintLengthSec,
+		arg.AcousticMaxBitErrorRate,
+		arg.BackfillConcurrency,
+		arg.SweepIntervalHours,
+	)
+	var i FingerprintSetting
+	err := row.Scan(
+		&i.ID,
+		&i.Enabled,
+		&i.ChromaprintLengthSec,
+		&i.AcousticMaxBitErrorRate,
+		&i.BackfillConcurrency,
+		&i.SweepIntervalHours,
+		&i.UpdatedAt,
+	)
+	return i, err
+}

internal/db/dbq/fingerprints.sql.go

@@ -27,20 +27,29 @@ const getFingerprintCoverage = `-- name: GetFingerprintCoverage :one
 SELECT count(*)::bigint AS total,
        count(*) FILTER (
            WHERE f.fingerprint_version >= $1
+             AND f.chromaprint_length_sec = $2
              AND f.audio_stream_sha256 IS NOT NULL AND f.chromaprint IS NOT NULL
        )::bigint AS fingerprinted,
        count(*) FILTER (
            WHERE f.fingerprint_version >= $1
+             AND f.chromaprint_length_sec = $2
              AND (f.audio_stream_sha256 IS NULL OR f.chromaprint IS NULL)
        )::bigint AS rejected,
        count(*) FILTER (
-           WHERE f.track_id IS NULL OR f.fingerprint_version < $1
+           WHERE f.track_id IS NULL
+              OR f.fingerprint_version < $1
+              OR f.chromaprint_length_sec <> $2
        )::bigint AS pending
   FROM tracks t
   LEFT JOIN track_fingerprints f ON f.track_id = t.id
  WHERE t.missing_since IS NULL
 `
 
+type GetFingerprintCoverageParams struct {
+	CurrentVersion       int16
+	ChromaprintLengthSec int32
+}
+
 type GetFingerprintCoverageRow struct {
 	Total         int64
 	Fingerprinted int64
@@ -49,11 +58,13 @@ type GetFingerprintCoverageRow struct {
 }
 
 // The admin gauge for the backfill. fingerprinted + rejected + pending = total.
-// rejected is a row at the current version with a NULL half: a tool ran and
-// refused the file, which is settled rather than waiting. Missing tracks are
-// excluded, or the gauge could never reach the end.
-func (q *Queries) GetFingerprintCoverage(ctx context.Context, currentVersion int16) (GetFingerprintCoverageRow, error) {
-	row := q.db.QueryRow(ctx, getFingerprintCoverage, currentVersion)
+// "Current" means derived by the current method AT the current length: a row at
+// another length is pending, because the backfill will re-derive it. rejected is
+// a current row with a NULL half: a tool ran and refused the file, which is
+// settled rather than waiting. Missing tracks are excluded, or the gauge could
+// never reach the end.
+func (q *Queries) GetFingerprintCoverage(ctx context.Context, arg GetFingerprintCoverageParams) (GetFingerprintCoverageRow, error) {
+	row := q.db.QueryRow(ctx, getFingerprintCoverage, arg.CurrentVersion, arg.ChromaprintLengthSec)
 	var i GetFingerprintCoverageRow
 	err := row.Scan(
 		&i.Total,
@@ -69,16 +80,21 @@ SELECT t.id, t.file_path
   FROM tracks t
   LEFT JOIN track_fingerprints f ON f.track_id = t.id
  WHERE t.missing_since IS NULL
-   AND (f.track_id IS NULL OR f.fingerprint_version < $1)
-   AND t.id > $2
+   -- A row taken at another length is as stale as one from an older method:
+   -- chromaprints at two lengths cannot be compared (#3913).
+   AND (f.track_id IS NULL
+        OR f.fingerprint_version < $1
+        OR f.chromaprint_length_sec <> $2)
+   AND t.id > $3
  ORDER BY t.id
- LIMIT $3
+ LIMIT $4
 `
 
 type ListTracksNeedingFingerprintParams struct {
-	CurrentVersion int16
-	AfterID        pgtype.UUID
-	BatchLimit     int32
+	CurrentVersion       int16
+	ChromaprintLengthSec int32
+	AfterID              pgtype.UUID
+	BatchLimit           int32
 }
 
 type ListTracksNeedingFingerprintRow struct {
@@ -93,7 +109,12 @@ type ListTracksNeedingFingerprintRow struct {
 // and retried in a tight loop. Missing tracks are skipped — there is no file to
 // read.
 func (q *Queries) ListTracksNeedingFingerprint(ctx context.Context, arg ListTracksNeedingFingerprintParams) ([]ListTracksNeedingFingerprintRow, error) {
-	rows, err := q.db.Query(ctx, listTracksNeedingFingerprint, arg.CurrentVersion, arg.AfterID, arg.BatchLimit)
+	rows, err := q.db.Query(ctx, listTracksNeedingFingerprint,
+		arg.CurrentVersion,
+		arg.ChromaprintLengthSec,
+		arg.AfterID,
+		arg.BatchLimit,
+	)
 	if err != nil {
 		return nil, err
 	}
@@ -114,23 +135,25 @@ func (q *Queries) ListTracksNeedingFingerprint(ctx context.Context, arg ListTrac
 
 const upsertTrackFingerprint = `-- name: UpsertTrackFingerprint :exec
 INSERT INTO track_fingerprints (
-    track_id, audio_stream_sha256, chromaprint, fingerprint_version
+    track_id, audio_stream_sha256, chromaprint, fingerprint_version, chromaprint_length_sec
 ) VALUES (
     $1, $2, $3,
-    $4
+    $4, $5
 )
 ON CONFLICT (track_id) DO UPDATE SET
-    audio_stream_sha256 = EXCLUDED.audio_stream_sha256,
-    chromaprint         = EXCLUDED.chromaprint,
-    fingerprint_version = EXCLUDED.fingerprint_version,
-    computed_at         = now()
+    audio_stream_sha256    = EXCLUDED.audio_stream_sha256,
+    chromaprint            = EXCLUDED.chromaprint,
+    fingerprint_version    = EXCLUDED.fingerprint_version,
+    chromaprint_length_sec = EXCLUDED.chromaprint_length_sec,
+    computed_at            = now()
 `
 
 type UpsertTrackFingerprintParams struct {
-	TrackID            pgtype.UUID
-	AudioStreamSha256  []byte
-	Chromaprint        []int32
-	FingerprintVersion int16
+	TrackID              pgtype.UUID
+	AudioStreamSha256    []byte
+	Chromaprint          []int32
+	FingerprintVersion   int16
+	ChromaprintLengthSec int32
 }
 
 // Written whenever a track's fingerprint is derived: by the scan when a file is
@@ -143,6 +166,7 @@ func (q *Queries) UpsertTrackFingerprint(ctx context.Context, arg UpsertTrackFin
 		arg.AudioStreamSha256,
 		arg.Chromaprint,
 		arg.FingerprintVersion,
+		arg.ChromaprintLengthSec,
 	)
 	return err
 }

internal/db/dbq/models.go

@@ -323,6 +323,16 @@ type DuplicateSweep struct {
 	ErrorMessage     *string
 }
 
+type FingerprintSetting struct {
+	ID                      bool
+	Enabled                 bool
+	ChromaprintLengthSec    int32
+	AcousticMaxBitErrorRate float64
+	BackfillConcurrency     int32
+	SweepIntervalHours      int32
+	UpdatedAt               pgtype.Timestamptz
+}
+
 type GeneralLike struct {
 	UserID  pgtype.UUID
 	TrackID pgtype.UUID
@@ -694,11 +704,12 @@ type Track struct {
 }
 
 type TrackFingerprint struct {
-	TrackID            pgtype.UUID
-	AudioStreamSha256  []byte
-	Chromaprint        []int32
-	FingerprintVersion int16
-	ComputedAt         pgtype.Timestamptz
+	TrackID              pgtype.UUID
+	AudioStreamSha256    []byte
+	Chromaprint          []int32
+	FingerprintVersion   int16
+	ComputedAt           pgtype.Timestamptz
+	ChromaprintLengthSec int32
 }
 
 type TrackSimilarity struct {