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/recsettings/service_test.go

@@ -281,3 +281,118 @@ func TestUpdate_NoOpWritesNoAudit(t *testing.T) {
 		t.Errorf("no-op update wrote %d audit rows, want 0", len(rows))
 	}
 }
+
+// --- Discover scope (#2377, milestone #268 slice 6) ---
+
+func TestNew_SeedsDiscoverDefaults(t *testing.T) {
+	pool := newPool(t)
+	s := newService(t, pool)
+	got := s.Discover()
+	want := ShippedDiscoverTuning()
+	if got != want {
+		t.Errorf("Discover() = %+v, want shipped %+v", got, want)
+	}
+}
+
+func TestUpdateDiscover_PersistsAndAudits(t *testing.T) {
+	pool := newPool(t)
+	s := newService(t, pool)
+	if err := s.UpdateDiscover(context.Background(), map[string]float64{
+		"tag_overlap_weight": 2.5,
+		"snooze_days":        30,
+	}); err != nil {
+		t.Fatalf("UpdateDiscover: %v", err)
+	}
+	if got := s.Discover().TagOverlapWeight; got != 2.5 {
+		t.Errorf("TagOverlapWeight = %v, want 2.5", got)
+	}
+	if got := s.Discover().SnoozeDays; got != 30 {
+		t.Errorf("SnoozeDays = %v, want 30", got)
+	}
+
+	// The audit row must land under the new scope. This is the assertion that
+	// would have caught a missing rule-#36 CHECK migration: without expanding
+	// recommendation_tuning_audit's whitelist, this INSERT fails at runtime.
+	rows := auditRows(t, pool)
+	if len(rows) != 1 {
+		t.Fatalf("audit rows = %d, want 1", len(rows))
+	}
+	if rows[0].Scope != ScopeDiscover {
+		t.Errorf("audit scope = %q, want %q", rows[0].Scope, ScopeDiscover)
+	}
+	if len(rows[0].Changes) != 2 {
+		t.Errorf("audit changes = %+v, want both fields", rows[0].Changes)
+	}
+
+	// Reload from the DB to prove it persisted rather than only caching.
+	s2 := newService(t, pool)
+	if got := s2.Discover().TagOverlapWeight; got != 2.5 {
+		t.Errorf("after reload TagOverlapWeight = %v, want 2.5 (not re-seeded to shipped)", got)
+	}
+}
+
+func TestUpdateDiscover_Validation(t *testing.T) {
+	pool := newPool(t)
+	s := newService(t, pool)
+	cases := []struct {
+		name  string
+		patch map[string]float64
+	}{
+		{"unknown field", map[string]float64{"nope": 1}},
+		{"negative weight", map[string]float64{"tag_overlap_weight": -1}},
+		{"weight past the typo bound", map[string]float64{"tag_overlap_weight": 100}},
+		// A sub-day snooze isn't a snooze, it's a flicker.
+		{"snooze under a day", map[string]float64{"snooze_days": 0.5}},
+		// Past a year it's a permanent dismissal wearing a snooze's clothes —
+		// the shape rule #101 rules out.
+		{"snooze past a year", map[string]float64{"snooze_days": 400}},
+	}
+	for _, c := range cases {
+		if err := s.UpdateDiscover(context.Background(), c.patch); err == nil {
+			t.Errorf("%s: expected rejection, got nil", c.name)
+		}
+	}
+	if got := s.Discover(); got != ShippedDiscoverTuning() {
+		t.Errorf("a rejected patch mutated state: %+v", got)
+	}
+	if rows := auditRows(t, pool); len(rows) != 0 {
+		t.Errorf("rejected patches wrote %d audit rows, want 0", len(rows))
+	}
+}
+
+// Weight 0 must be accepted — it's the operator's off switch for the whole
+// tag term, so a "must be positive" bound would remove their ability to
+// disable the feature.
+func TestUpdateDiscover_ZeroWeightIsAllowed(t *testing.T) {
+	pool := newPool(t)
+	s := newService(t, pool)
+	if err := s.UpdateDiscover(context.Background(),
+		map[string]float64{"tag_overlap_weight": 0}); err != nil {
+		t.Fatalf("UpdateDiscover(0): %v", err)
+	}
+	if got := s.Discover().TagOverlapWeight; got != 0 {
+		t.Errorf("TagOverlapWeight = %v, want 0", got)
+	}
+}
+
+func TestResetDiscover_RestoresShippedDefaults(t *testing.T) {
+	pool := newPool(t)
+	s := newService(t, pool)
+	if err := s.UpdateDiscover(context.Background(),
+		map[string]float64{"tag_overlap_weight": 4}); err != nil {
+		t.Fatalf("UpdateDiscover: %v", err)
+	}
+	if err := s.Reset(context.Background(), ScopeDiscover); err != nil {
+		t.Fatalf("Reset: %v", err)
+	}
+	if got := s.Discover(); got != ShippedDiscoverTuning() {
+		t.Errorf("after reset = %+v, want shipped %+v", got, ShippedDiscoverTuning())
+	}
+	// Already-at-defaults is a no-op: update + reset = 2 rows, not 3.
+	if err := s.Reset(context.Background(), ScopeDiscover); err != nil {
+		t.Fatalf("second Reset: %v", err)
+	}
+	if rows := auditRows(t, pool); len(rows) != 2 {
+		t.Errorf("audit rows = %d, want 2 (the no-op reset must not audit)", len(rows))
+	}
+}