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/library/duplicate_sweep.go

@@ -32,10 +32,17 @@ import (
 // carries a ~4 KB fingerprint, so a page is about 2 MB.
 const duplicateCandidatePage = 500
 
-// duplicateSweepTick is how often the worker checks for anything new to sweep.
-// With nothing new, a tick is two cheap aggregate queries.
+// duplicateSweepTick is how often the worker checks whether a sweep is due. The
+// operator's sweep interval (#3913) is the least time between sweeps; the tick
+// only bounds how late past it one starts. With nothing due, a tick is two cheap
+// aggregate queries.
 const duplicateSweepTick = time.Hour
 
+// sweepIntervalSlack absorbs the moment between a tick and the sweep it starts
+// stamping started_at. Without it a one-hour interval checked on a one-hour tick
+// would find the last sweep a moment under an hour old, and skip every other tick.
+const sweepIntervalSlack = 5 * time.Minute
+
 // staleDuplicateSweepThreshold is the age past which an in-flight sweep is
 // assumed dead — a crash mid-sweep leaves finished_at NULL for ever — and another
 // may start. Twice the library scan's threshold, because a sweep compares
@@ -58,13 +65,16 @@ type DuplicateSweepResult struct {
 	Oversize   int // acoustic clusters too large to propose
 }
 
-// RunDuplicateSweep runs one sweep and records it in duplicate_sweeps.
-func RunDuplicateSweep(ctx context.Context, pool *pgxpool.Pool, logger *slog.Logger) (DuplicateSweepResult, error) {
-	return runDuplicateSweep(ctx, pool, logger, duplicateCandidatePage)
+// RunDuplicateSweep runs one sweep and records it in duplicate_sweeps. cfg is a
+// snapshot: one sweep applies one threshold and one length throughout.
+func RunDuplicateSweep(
+	ctx context.Context, pool *pgxpool.Pool, logger *slog.Logger, cfg FingerprintSettings,
+) (DuplicateSweepResult, error) {
+	return runDuplicateSweep(ctx, pool, logger, cfg, duplicateCandidatePage)
 }
 
 func runDuplicateSweep(
-	ctx context.Context, pool *pgxpool.Pool, logger *slog.Logger, pageSize int32,
+	ctx context.Context, pool *pgxpool.Pool, logger *slog.Logger, cfg FingerprintSettings, pageSize int32,
 ) (DuplicateSweepResult, error) {
 	q := dbq.New(pool)
 	sweep, err := q.StartDuplicateSweep(ctx)
@@ -72,7 +82,7 @@ func runDuplicateSweep(
 		return DuplicateSweepResult{}, fmt.Errorf("start duplicate sweep: %w", err)
 	}
 
-	res, runErr := sweepDuplicates(ctx, q, sweep.ID, pageSize)
+	res, runErr := sweepDuplicates(ctx, q, sweep.ID, cfg, pageSize)
 
 	finishCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), duplicateSweepFinishTimeout)
 	defer cancel()
@@ -98,7 +108,7 @@ func runDuplicateSweep(
 }
 
 func sweepDuplicates(
-	ctx context.Context, q *dbq.Queries, sweepID pgtype.UUID, pageSize int32,
+	ctx context.Context, q *dbq.Queries, sweepID pgtype.UUID, cfg FingerprintSettings, pageSize int32,
 ) (DuplicateSweepResult, error) {
 	var res DuplicateSweepResult
 
@@ -119,9 +129,12 @@ func sweepDuplicates(
 
 	// Acoustic tier, streamed in duration order. The first member of an exact
 	// group the stream meets stands in for the whole group; the rest are skipped.
-	grouper := newStreamGrouper(defaultAcousticMaxBitErrorRate)
+	// Only prints at the current length are streamed: a print at another length
+	// cannot be compared, and is waiting on the backfill to be re-derived.
+	grouper := newStreamGrouper(cfg.AcousticMaxBitErrorRate)
 	params := dbq.ListDuplicateCandidatesParams{
-		CurrentVersion: fingerprintVersion,
+		CurrentVersion:       fingerprintVersion,
+		ChromaprintLengthSec: cfg.ChromaprintLengthSec,
 		// Durations are never negative, and the all-zero uuid sorts first: every
 		// row is after this cursor. Valid must be true, or "> NULL" matches nothing.
 		AfterDurationMs: -1,
@@ -262,7 +275,9 @@ func formatUUIDs(ids []pgtype.UUID) []string {
 // running, reaping a sweep that has been in flight past
 // staleDuplicateSweepThreshold. Mirrors TryStartScan. The sweep runs on ctx, so
 // a caller answering an HTTP request must pass a context that outlives it.
-func TryStartDuplicateSweep(ctx context.Context, pool *pgxpool.Pool, logger *slog.Logger) (bool, error) {
+func TryStartDuplicateSweep(
+	ctx context.Context, pool *pgxpool.Pool, logger *slog.Logger, cfg FingerprintSettings,
+) (bool, error) {
 	q := dbq.New(pool)
 	row, err := q.GetInFlightDuplicateSweep(ctx)
 	switch {
@@ -282,23 +297,28 @@ func TryStartDuplicateSweep(ctx context.Context, pool *pgxpool.Pool, logger *slo
 	}
 
 	go func() {
-		if _, err := RunDuplicateSweep(ctx, pool, logger); err != nil {
+		if _, err := RunDuplicateSweep(ctx, pool, logger, cfg); err != nil {
 			logger.Warn("duplicate sweep failed", "err", err)
 		}
 	}()
 	return true, nil
 }
 
-// DuplicateSweepWorker sweeps whenever fingerprints have changed.
+// DuplicateSweepWorker sweeps whenever its input has changed, at most once per
+// the operator's sweep interval.
 type DuplicateSweepWorker struct {
-	pool   *pgxpool.Pool
-	logger *slog.Logger
-	tick   time.Duration
+	pool     *pgxpool.Pool
+	logger   *slog.Logger
+	settings *FingerprintSettingsService
+	tick     time.Duration
 }
 
-// NewDuplicateSweepWorker builds a worker with the production cadence.
-func NewDuplicateSweepWorker(pool *pgxpool.Pool, logger *slog.Logger) *DuplicateSweepWorker {
-	return &DuplicateSweepWorker{pool: pool, logger: logger, tick: duplicateSweepTick}
+// NewDuplicateSweepWorker builds a worker with the production cadence. settings
+// is shared with the admin API; nil runs on defaults.
+func NewDuplicateSweepWorker(
+	pool *pgxpool.Pool, logger *slog.Logger, settings *FingerprintSettingsService,
+) *DuplicateSweepWorker {
+	return &DuplicateSweepWorker{pool: pool, logger: logger, settings: settings, tick: duplicateSweepTick}
 }
 
 // Run blocks until ctx is cancelled, checking once at start and then each tick.
@@ -323,7 +343,8 @@ func (w *DuplicateSweepWorker) tickOnce(ctx context.Context) {
 			w.logger.Error("duplicate sweep: tick panicked", "panic", r)
 		}
 	}()
-	due, err := duplicateSweepDue(ctx, dbq.New(w.pool))
+	cfg := w.settings.Get()
+	due, err := duplicateSweepDue(ctx, dbq.New(w.pool), cfg, time.Now())
 	if err != nil {
 		if ctx.Err() == nil {
 			w.logger.Warn("duplicate sweep: due check failed", "err", err)
@@ -333,28 +354,45 @@ func (w *DuplicateSweepWorker) tickOnce(ctx context.Context) {
 	if !due {
 		return
 	}
-	if _, err := TryStartDuplicateSweep(ctx, w.pool, w.logger); err != nil {
+	if _, err := TryStartDuplicateSweep(ctx, w.pool, w.logger, cfg); err != nil {
 		w.logger.Warn("duplicate sweep: start failed", "err", err)
 	}
 }
 
-// duplicateSweepDue reports whether any fingerprint was written after the latest
-// sweep started. Fingerprints are the sweep's only input, so nothing else can
-// change its answer; while the backfill is running this is true every tick.
-func duplicateSweepDue(ctx context.Context, q *dbq.Queries) (bool, error) {
+// duplicateSweepDue reads what sweepIsDue decides on.
+func duplicateSweepDue(ctx context.Context, q *dbq.Queries, cfg FingerprintSettings, now time.Time) (bool, error) {
 	latest, err := q.GetLatestFingerprintComputedAt(ctx)
 	if err != nil {
 		return false, fmt.Errorf("latest fingerprint: %w", err)
 	}
-	if !latest.Valid {
-		return false, nil // nothing fingerprinted yet
-	}
+	var lastStart pgtype.Timestamptz
 	last, err := q.GetLatestDuplicateSweep(ctx)
-	if errors.Is(err, pgx.ErrNoRows) {
-		return true, nil
-	}
-	if err != nil {
+	switch {
+	case err == nil:
+		lastStart = last.StartedAt
+	case !errors.Is(err, pgx.ErrNoRows):
 		return false, fmt.Errorf("latest duplicate sweep: %w", err)
 	}
-	return latest.Time.After(last.StartedAt.Time), nil
+	return sweepIsDue(latest, lastStart, cfg, now), nil
+}
+
+// sweepIsDue reports whether a sweep should start: something it reads has
+// changed since the last sweep started, and the operator's interval has passed.
+//
+// Two things can change its answer. Fingerprints are its input, so any written
+// after the last sweep began count; while the backfill runs that is true every
+// tick, which is what the interval is for. And a settings save counts, because a
+// new threshold or length changes what the same fingerprints group into.
+func sweepIsDue(latestFingerprint, lastSweepStart pgtype.Timestamptz, cfg FingerprintSettings, now time.Time) bool {
+	if !latestFingerprint.Valid {
+		return false // nothing fingerprinted yet
+	}
+	if !lastSweepStart.Valid {
+		return true // never swept
+	}
+	interval := time.Duration(cfg.SweepIntervalHours) * time.Hour
+	if now.Sub(lastSweepStart.Time) < interval-sweepIntervalSlack {
+		return false
+	}
+	return latestFingerprint.Time.After(lastSweepStart.Time) || cfg.UpdatedAt.After(lastSweepStart.Time)
 }