feat(discover): rank suggestions by taste-tag overlap — #2377 (server)

The payoff slice. Until now a candidate's only claim on a slot was "some
artist you play is adjacent to it in a similarity graph" — a fact that says
nothing about whether the music sounds like anything you like. Now the
candidate's own folksonomy tags (cached by slice 5) are compared against
the user's taste-profile tags, so the deck ranks on taste and can say WHY.

The blend is MULTIPLICATIVE — score × (1 + weight × overlap) — and that
choice carries the whole safety argument:

  - An untagged candidate has overlap 0, so its score is EXACTLY unchanged.
    Tag coverage is permanently partial (#2376); it must cost a candidate
    nothing, not sink it (rule #131).
  - Nothing can leapfrog on tags alone. An additive term with a large
    weight would let a near-zero-similarity artist outrank a strong match
    for sharing one popular tag, which reads as noise.
  - Weight 0 restores pure similarity order bit-for-bit, so the operator's
    knob has a real off position.

overlap = Σ(shared) candWeight × normalizedTasteWeight ÷ Σ(all) candWeight.
Normalizing the taste side by the user's strongest tag makes the score
comparable across users (taste weights accumulate with listening, so a
heavy listener's raw numbers dwarf a new user's while meaning the same
thing). Dividing by the candidate's own mass makes it comparable across
candidates, so a densely-tagged artist can't win on tag count alone.

Applied to the whole over-fetched pool BEFORE selectSuggestions, so the
rotation and diversity rules operate on blended scores — boosting only the
twelve already chosen by similarity would leave the re-ranking undone.

A query failure is returned, NOT degraded past. Graceful degradation is
for expected absence (no taste profile, no cached tags) and both are
handled explicitly as empty inputs; swallowing a real error would hide a
broken DB behind a subtly worse ranking that nothing reports.

Migration 0051 adds a FOURTH tuning scope rather than columns on
taste_tuning, because snooze_days lives here too and a snooze must never
be read as taste signal (#2374) — filing it under 'taste' would put it one
careless join from the leak that design forbids. Expanding
recommendation_tuning_audit's CHECK is in the same migration per rule #36,
and a test asserts the audit row lands, which is what would catch its
absence.

snooze_days moves out of a Go constant onto the tuning card (rule #25),
closing the deferral from #2374.

Tag-overlap tests use deliberately SKEWED fixtures: an evenly-matching pool
cannot exercise a re-ranking, since every candidate gets the same
multiplier and the order is unchanged whether the blend works or not.

Admin UI + client attribution follow in this batch — rule #27.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

internal/db/dbq/recommendation_tuning.sql.go

@@ -9,6 +9,22 @@ import (
 	"context"
 )
 
+const getDiscoverTuning = `-- name: GetDiscoverTuning :one
+SELECT singleton, tag_overlap_weight, snooze_days, updated_at FROM discover_tuning WHERE singleton = true
+`
+
+func (q *Queries) GetDiscoverTuning(ctx context.Context) (DiscoverTuning, error) {
+	row := q.db.QueryRow(ctx, getDiscoverTuning)
+	var i DiscoverTuning
+	err := row.Scan(
+		&i.Singleton,
+		&i.TagOverlapWeight,
+		&i.SnoozeDays,
+		&i.UpdatedAt,
+	)
+	return i, err
+}
+
 const getTasteTuning = `-- name: GetTasteTuning :one
 SELECT singleton, half_life_days, engagement_hard_skip, engagement_neutral, engagement_full, updated_at, enriched_tag_scale, era_scale, mood_scale FROM taste_tuning WHERE singleton = true
 `
@@ -118,6 +134,32 @@ func (q *Queries) ListWeightProfiles(ctx context.Context) ([]RecommendationWeigh
 	return items, nil
 }
 
+const updateDiscoverTuning = `-- name: UpdateDiscoverTuning :one
+UPDATE discover_tuning
+   SET tag_overlap_weight = $1,
+       snooze_days        = $2,
+       updated_at         = now()
+ WHERE singleton = true
+RETURNING singleton, tag_overlap_weight, snooze_days, updated_at
+`
+
+type UpdateDiscoverTuningParams struct {
+	TagOverlapWeight float64
+	SnoozeDays       float64
+}
+
+func (q *Queries) UpdateDiscoverTuning(ctx context.Context, arg UpdateDiscoverTuningParams) (DiscoverTuning, error) {
+	row := q.db.QueryRow(ctx, updateDiscoverTuning, arg.TagOverlapWeight, arg.SnoozeDays)
+	var i DiscoverTuning
+	err := row.Scan(
+		&i.Singleton,
+		&i.TagOverlapWeight,
+		&i.SnoozeDays,
+		&i.UpdatedAt,
+	)
+	return i, err
+}
+
 const updateTasteTuning = `-- name: UpdateTasteTuning :one
 UPDATE taste_tuning
    SET half_life_days       = $1,
@@ -226,6 +268,24 @@ func (q *Queries) UpdateWeightProfile(ctx context.Context, arg UpdateWeightProfi
 	return i, err
 }
 
+const upsertDiscoverTuningDefaults = `-- name: UpsertDiscoverTuningDefaults :exec
+INSERT INTO discover_tuning (singleton, tag_overlap_weight, snooze_days)
+VALUES (true, $1, $2)
+ON CONFLICT (singleton) DO NOTHING
+`
+
+type UpsertDiscoverTuningDefaultsParams struct {
+	TagOverlapWeight float64
+	SnoozeDays       float64
+}
+
+// Boot reconcile for the Discover scope (#2377). Never overwrites
+// operator-tuned values, same contract as the other two.
+func (q *Queries) UpsertDiscoverTuningDefaults(ctx context.Context, arg UpsertDiscoverTuningDefaultsParams) error {
+	_, err := q.db.Exec(ctx, upsertDiscoverTuningDefaults, arg.TagOverlapWeight, arg.SnoozeDays)
+	return err
+}
+
 const upsertTasteTuningDefaults = `-- name: UpsertTasteTuningDefaults :exec
 INSERT INTO taste_tuning (
     singleton, half_life_days, engagement_hard_skip,