feat(metrics): bucketed surface families + manual-plays baseline (#1248, milestone 127)

The recommendation metrics table was observable but not actionable: raw
source strings (album:<uuid> one-offs) drowned the stable surfaces, and
manual plays were excluded so skip rates had no control group.

- SQL: include NULL-source rows (the baseline) and carry completion_n
  so family merges can weight avg_completion correctly.
- Handler buckets raw sources into stable families (radio:<uuid> →
  Radio, album:/artist: → direct plays, etc.) grouped by surface
  intent: go-to / discovery / direct — each band judged against its
  job, since discovery mixes are expected to skip hotter. Families
  under 20 plays are flagged low-confidence, not hidden.
- Settings card renders the baseline row and per-surface deltas in
  percentage points vs baseline (worse-than-baseline deltas in danger
  color), intent hint copy per group, low-data rows dimmed.
- Pure-unit test for the bucketing/merge; DB test updated to the new
  contract (baseline included, radio:<uuid> collapse).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TsF3cNoKrqCYsU78cXC8U6

internal/db/dbq/recommendation_metrics.sql.go

@@ -17,12 +17,10 @@ SELECT
     pe.source,
     count(*)::bigint AS plays,
     count(*) FILTER (WHERE pe.was_skipped)::bigint AS skips,
-    COALESCE(
-        avg(pe.completion_ratio) FILTER (WHERE pe.completion_ratio IS NOT NULL),
-        0)::float8 AS avg_completion
+    count(pe.completion_ratio)::bigint AS completion_n,
+    COALESCE(avg(pe.completion_ratio), 0)::float8 AS avg_completion
 FROM play_events pe
 WHERE pe.user_id = $1
-  AND pe.source IS NOT NULL
   AND pe.started_at > now() - ($2::float8 * INTERVAL '1 day')
 GROUP BY pe.source
 ORDER BY plays DESC
@@ -37,16 +35,21 @@ type RecommendationSourceMetricsForUserRow struct {
 	Source        *string
 	Plays         int64
 	Skips         int64
+	CompletionN   int64
 	AvgCompletion float64
 }
 
 // Recommendation observability (#796 phase 4). Per-source play outcomes so the
 // operator can see whether each recommendation surface is landing and tune the
 // taste weights. Source is stamped on play_events when a play is launched from
-// a system-playlist surface ('for_you' | 'discover' | the discovery mixes);
-// NULL for library / radio / user-playlist plays, which are excluded here.
+// a recommendation surface; NULL means the user picked the track manually —
+// those rows are INCLUDED here as the baseline control group the surfaces are
+// judged against (milestone #127: delta-vs-baseline is what makes the numbers
+// actionable). Raw source strings are bucketed into stable surface families in
+// the Go handler; completion_n is carried so family merges can weight
+// avg_completion correctly.
 // $1 user_id, $2 window_days. plays/skips are counts; avg_completion is the
-// mean completion ratio over plays that recorded one (0 when none did).
+// mean completion ratio over the completion_n plays that recorded one.
 func (q *Queries) RecommendationSourceMetricsForUser(ctx context.Context, arg RecommendationSourceMetricsForUserParams) ([]RecommendationSourceMetricsForUserRow, error) {
 	rows, err := q.db.Query(ctx, recommendationSourceMetricsForUser, arg.UserID, arg.Column2)
 	if err != nil {
@@ -60,6 +63,7 @@ func (q *Queries) RecommendationSourceMetricsForUser(ctx context.Context, arg Re
 			&i.Source,
 			&i.Plays,
 			&i.Skips,
+			&i.CompletionN,
 			&i.AvgCompletion,
 		); err != nil {
 			return nil, err

internal/db/queries/recommendation_metrics.sql

@@ -1,22 +1,24 @@
 -- Recommendation observability (#796 phase 4). Per-source play outcomes so the
 -- operator can see whether each recommendation surface is landing and tune the
 -- taste weights. Source is stamped on play_events when a play is launched from
--- a system-playlist surface ('for_you' | 'discover' | the discovery mixes);
--- NULL for library / radio / user-playlist plays, which are excluded here.
+-- a recommendation surface; NULL means the user picked the track manually —
+-- those rows are INCLUDED here as the baseline control group the surfaces are
+-- judged against (milestone #127: delta-vs-baseline is what makes the numbers
+-- actionable). Raw source strings are bucketed into stable surface families in
+-- the Go handler; completion_n is carried so family merges can weight
+-- avg_completion correctly.
 
 -- name: RecommendationSourceMetricsForUser :many
 -- $1 user_id, $2 window_days. plays/skips are counts; avg_completion is the
--- mean completion ratio over plays that recorded one (0 when none did).
+-- mean completion ratio over the completion_n plays that recorded one.
 SELECT
     pe.source,
     count(*)::bigint AS plays,
     count(*) FILTER (WHERE pe.was_skipped)::bigint AS skips,
-    COALESCE(
-        avg(pe.completion_ratio) FILTER (WHERE pe.completion_ratio IS NOT NULL),
-        0)::float8 AS avg_completion
+    count(pe.completion_ratio)::bigint AS completion_n,
+    COALESCE(avg(pe.completion_ratio), 0)::float8 AS avg_completion
 FROM play_events pe
 WHERE pe.user_id = $1
-  AND pe.source IS NOT NULL
   AND pe.started_at > now() - ($2::float8 * INTERVAL '1 day')
 GROUP BY pe.source
 ORDER BY plays DESC;