feat(tuning): weekly trend view — per-surface series + knob-turn markers

The verify half of the tune→verify loop (#1251), on the same admin
Tuning page as the knobs:

- RecommendationWeeklyTrends: weekly per-source outcomes aggregated
  across all users (the knobs are global, so judging a turn needs
  global outcomes — rows carry rates only, no track/user identity),
  with a taste-hit count per bucket: plays whose track's artist has a
  positive weight in the player's current taste profile. That's the
  "cheap recompute" reading — retroactive over the whole window, at
  the cost of profile drift.
- GET /api/admin/recommendation-trends?weeks=N (default 12, cap 52):
  per-family weekly series (skip rate, sample-weighted completion,
  taste-hit rate) plus the tuning-audit markers inside the window.
- Web: sparkline table under the tuning cards — skip rate per week on
  a shared axis with dashed ticks at knob turns, latest-week columns,
  window taste-hit rate, low-volume rows dimmed as anecdote, and a
  plain-text list of the window's tuning changes.

Also fixes the revive unused-parameter lint on the tuning GET handler
that failed CI run 1903 on the previous commit.

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

internal/api/admin_recommendation_trends.go

@@ -0,0 +1,202 @@
+// Admin recommendation-trends endpoint (#1251): weekly per-surface
+// outcome series with tuning-audit markers — the verify half of the
+// tune→verify loop the tuning lab (#1250) opens. Aggregated across
+// all users because the knobs are global; rows carry rates only.
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"sort"
+	"strconv"
+	"time"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/apierror"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+)
+
+const (
+	trendsDefaultWeeks = 12
+	trendsMaxWeeks     = 52
+	// trendsAuditFetchCap bounds the audit fetch; markers older than
+	// the window are dropped in Go. Far above any real knob-turn count
+	// inside a year.
+	trendsAuditFetchCap = 500
+)
+
+// trendPoint is one week of one surface family's outcomes.
+type trendPoint struct {
+	WeekStart     string  `json:"week_start"` // ISO date (Monday)
+	Plays         int64   `json:"plays"`
+	Skips         int64   `json:"skips"`
+	SkipRate      float64 `json:"skip_rate"`
+	AvgCompletion float64 `json:"avg_completion"`
+	// TasteHitRate is the share of plays whose track's artist carries a
+	// positive weight in the player's current taste profile — a drifted
+	// but retroactive read on whether the surface feeds taste-fitting
+	// tracks.
+	TasteHitRate float64 `json:"taste_hit_rate"`
+	// completionN carries the completion sample count through same-week
+	// merges so avg_completion stays sample-weighted; not serialized.
+	completionN int64
+}
+
+// trendSeries is one surface family's weekly series.
+type trendSeries struct {
+	Key    string       `json:"key"`
+	Label  string       `json:"label"`
+	Intent string       `json:"intent"` // go_to | discovery | direct; "" for the manual baseline
+	Plays  int64        `json:"plays"`  // window total, for sorting/volume-gating
+	Points []trendPoint `json:"points"`
+}
+
+// trendMarker is one tuning-audit event annotated on the timeline.
+type trendMarker struct {
+	ChangedAt string          `json:"changed_at"`
+	Scope     string          `json:"scope"`
+	Action    string          `json:"action"`
+	Changes   json.RawMessage `json:"changes"`
+}
+
+type trendsResp struct {
+	Weeks   int           `json:"weeks"`
+	Series  []trendSeries `json:"series"`
+	Markers []trendMarker `json:"markers"`
+}
+
+// handleGetRecommendationTrends implements
+// GET /api/admin/recommendation-trends?weeks=N (default 12, cap 52).
+func (h *handlers) handleGetRecommendationTrends(w http.ResponseWriter, r *http.Request) {
+	weeks := trendsDefaultWeeks
+	if v := r.URL.Query().Get("weeks"); v != "" {
+		n, err := strconv.Atoi(v)
+		if err != nil || n < 1 {
+			writeErr(w, apierror.BadRequest("bad_request", "invalid weeks"))
+			return
+		}
+		if n > trendsMaxWeeks {
+			n = trendsMaxWeeks
+		}
+		weeks = n
+	}
+
+	q := dbq.New(h.pool)
+	rows, err := q.RecommendationWeeklyTrends(r.Context(), int32(weeks))
+	if err != nil {
+		h.logger.Error("api: recommendation trends", "err", err)
+		writeErr(w, apierror.InternalMsg("lookup failed", err))
+		return
+	}
+	audits, err := q.ListTuningAudit(r.Context(), trendsAuditFetchCap)
+	if err != nil {
+		h.logger.Error("api: recommendation trends audit", "err", err)
+		writeErr(w, apierror.InternalMsg("lookup failed", err))
+		return
+	}
+
+	writeJSON(w, http.StatusOK, buildTrendsResponse(weeks, time.Now().UTC(), rows, audits))
+}
+
+// buildTrendsResponse folds weekly rows into per-family series and
+// windows the audit markers. Split from the handler for pure-unit
+// testability.
+func buildTrendsResponse(
+	weeks int, now time.Time,
+	rows []dbq.RecommendationWeeklyTrendsRow,
+	audits []dbq.RecommendationTuningAudit,
+) trendsResp {
+	type accum struct {
+		fam    recFamily
+		plays  int64
+		points []trendPoint
+	}
+	families := map[string]*accum{}
+	for _, row := range rows {
+		fam := recFamily{key: "manual", label: "Manual library plays"}
+		if row.Source != nil && *row.Source != "" {
+			fam = bucketRecSource(*row.Source)
+		}
+		acc, ok := families[fam.key]
+		if !ok {
+			acc = &accum{fam: fam}
+			families[fam.key] = acc
+		}
+		acc.plays += row.Plays
+		p := trendPoint{
+			WeekStart:     row.WeekStart.Time.Format("2006-01-02"),
+			Plays:         row.Plays,
+			Skips:         row.Skips,
+			AvgCompletion: row.AvgCompletion,
+			completionN:   row.CompletionN,
+		}
+		if row.Plays > 0 {
+			p.SkipRate = float64(row.Skips) / float64(row.Plays)
+			p.TasteHitRate = float64(row.TasteHits) / float64(row.Plays)
+		}
+		// Same family can arrive as several raw sources (radio:<uuid>);
+		// merge same-week points play-weighted.
+		if n := len(acc.points); n > 0 && acc.points[n-1].WeekStart == p.WeekStart {
+			acc.points[n-1] = mergeTrendPoints(acc.points[n-1], p)
+		} else {
+			acc.points = append(acc.points, p)
+		}
+	}
+
+	resp := trendsResp{Weeks: weeks, Series: []trendSeries{}, Markers: []trendMarker{}}
+	for _, acc := range families {
+		resp.Series = append(resp.Series, trendSeries{
+			Key:    acc.fam.key,
+			Label:  acc.fam.label,
+			Intent: acc.fam.intent,
+			Plays:  acc.plays,
+			Points: acc.points,
+		})
+	}
+	sort.Slice(resp.Series, func(i, j int) bool {
+		if resp.Series[i].Plays != resp.Series[j].Plays {
+			return resp.Series[i].Plays > resp.Series[j].Plays
+		}
+		return resp.Series[i].Key < resp.Series[j].Key
+	})
+
+	cutoff := now.Add(-time.Duration(weeks) * 7 * 24 * time.Hour)
+	for _, a := range audits {
+		if a.ChangedAt.Time.Before(cutoff) {
+			continue
+		}
+		resp.Markers = append(resp.Markers, trendMarker{
+			ChangedAt: a.ChangedAt.Time.UTC().Format(time.RFC3339),
+			Scope:     a.Scope,
+			Action:    a.Action,
+			Changes:   json.RawMessage(a.Changes),
+		})
+	}
+	// ListTuningAudit returns newest-first; the timeline reads better
+	// oldest-first.
+	sort.Slice(resp.Markers, func(i, j int) bool {
+		return resp.Markers[i].ChangedAt < resp.Markers[j].ChangedAt
+	})
+	return resp
+}
+
+// mergeTrendPoints combines two same-week points of one family:
+// counts add, skip/taste rates re-derive from the merged counts, and
+// avg_completion is weighted by each side's completion sample count.
+func mergeTrendPoints(a, b trendPoint) trendPoint {
+	out := trendPoint{
+		WeekStart:   a.WeekStart,
+		Plays:       a.Plays + b.Plays,
+		Skips:       a.Skips + b.Skips,
+		completionN: a.completionN + b.completionN,
+	}
+	if out.Plays > 0 {
+		out.SkipRate = float64(out.Skips) / float64(out.Plays)
+		out.TasteHitRate = (a.TasteHitRate*float64(a.Plays) + b.TasteHitRate*float64(b.Plays)) /
+			float64(out.Plays)
+	}
+	if out.completionN > 0 {
+		out.AvgCompletion = (a.AvgCompletion*float64(a.completionN) + b.AvgCompletion*float64(b.completionN)) /
+			float64(out.completionN)
+	}
+	return out
+}

internal/api/admin_recommendation_trends_test.go

@@ -0,0 +1,152 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/jackc/pgx/v5/pgtype"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+)
+
+func date(s string) pgtype.Date {
+	t, _ := time.Parse("2006-01-02", s)
+	return pgtype.Date{Time: t, Valid: true}
+}
+
+func TestBuildTrendsResponse_SeriesMergingAndMarkers(t *testing.T) {
+	src := func(s string) *string { return &s }
+	now := time.Date(2026, 7, 3, 12, 0, 0, 0, time.UTC)
+	rows := []dbq.RecommendationWeeklyTrendsRow{
+		// Two radio session sources in the same week collapse into one
+		// family point; completion weighting by sample count.
+		{WeekStart: date("2026-06-22"), Source: src("radio:aaaa"),
+			Plays: 3, Skips: 1, CompletionN: 3, AvgCompletion: 0.6, TasteHits: 3},
+		{WeekStart: date("2026-06-22"), Source: src("radio:bbbb"),
+			Plays: 1, Skips: 1, CompletionN: 1, AvgCompletion: 0.2, TasteHits: 0},
+		{WeekStart: date("2026-06-29"), Source: src("radio:aaaa"),
+			Plays: 2, Skips: 0, CompletionN: 2, AvgCompletion: 0.9, TasteHits: 1},
+		// NULL source = manual baseline family.
+		{WeekStart: date("2026-06-29"), Source: nil,
+			Plays: 5, Skips: 1, CompletionN: 5, AvgCompletion: 0.8, TasteHits: 4},
+	}
+	audits := []dbq.RecommendationTuningAudit{
+		{ID: 2, ChangedAt: pgtype.Timestamptz{Time: now.Add(-24 * time.Hour), Valid: true},
+			Scope: "radio", Action: "update", Changes: []byte(`[{"field":"taste_weight","old":1,"new":2}]`)},
+		// Older than the window → dropped.
+		{ID: 1, ChangedAt: pgtype.Timestamptz{Time: now.Add(-100 * 7 * 24 * time.Hour), Valid: true},
+			Scope: "taste", Action: "reset", Changes: []byte(`[]`)},
+	}
+
+	resp := buildTrendsResponse(12, now, rows, audits)
+
+	if len(resp.Series) != 2 {
+		t.Fatalf("series = %d, want 2 (radio + manual)", len(resp.Series))
+	}
+	radio := resp.Series[0] // 6 plays > manual's 5 → sorted first
+	if radio.Key != "radio" || radio.Plays != 6 {
+		t.Fatalf("series[0] = %s/%d, want radio/6", radio.Key, radio.Plays)
+	}
+	if len(radio.Points) != 2 {
+		t.Fatalf("radio points = %d, want 2 weeks", len(radio.Points))
+	}
+	wk1 := radio.Points[0]
+	if wk1.WeekStart != "2026-06-22" || wk1.Plays != 4 || wk1.Skips != 2 {
+		t.Errorf("week1 = %+v, want 2026-06-22 with 4 plays / 2 skips", wk1)
+	}
+	if wk1.SkipRate != 0.5 {
+		t.Errorf("week1 skip_rate = %v, want 0.5", wk1.SkipRate)
+	}
+	// Completion weighted by sample count: (0.6*3 + 0.2*1) / 4 = 0.5.
+	if wk1.AvgCompletion < 0.49 || wk1.AvgCompletion > 0.51 {
+		t.Errorf("week1 avg_completion = %v, want 0.5", wk1.AvgCompletion)
+	}
+	// Taste hits: 3 of 4 plays.
+	if wk1.TasteHitRate != 0.75 {
+		t.Errorf("week1 taste_hit_rate = %v, want 0.75", wk1.TasteHitRate)
+	}
+	if manual := resp.Series[1]; manual.Key != "manual" || manual.Intent != "" {
+		t.Errorf("series[1] = %+v, want the manual baseline family", manual)
+	}
+
+	if len(resp.Markers) != 1 {
+		t.Fatalf("markers = %d, want 1 (out-of-window marker dropped)", len(resp.Markers))
+	}
+	if resp.Markers[0].Scope != "radio" || resp.Markers[0].Action != "update" {
+		t.Errorf("marker = %+v, want radio/update", resp.Markers[0])
+	}
+}
+
+func newTrendsRouter(h *handlers) chi.Router {
+	r := chi.NewRouter()
+	r.Get("/api/admin/recommendation-trends", h.handleGetRecommendationTrends)
+	return r
+}
+
+func TestRecommendationTrends_EndToEnd(t *testing.T) {
+	h, pool := testHandlers(t)
+	user := seedUser(t, pool, "trends", "pw", true)
+	artist := seedArtist(t, pool, "TrendArtist")
+	album := seedAlbum(t, pool, artist.ID, "TrendAlbum", 2020)
+	tk := seedTrack(t, pool, album.ID, artist.ID, "TrendTrack", 1, 200000)
+	session := seedPlaySession(t, pool, user.ID, time.Now())
+
+	// Positive taste weight for the artist → plays count as taste hits.
+	if _, err := pool.Exec(context.Background(),
+		`INSERT INTO taste_profile_artists (user_id, artist_id, weight) VALUES ($1, $2, 1.5)`,
+		user.ID, artist.ID); err != nil {
+		t.Fatalf("seed taste profile: %v", err)
+	}
+	radio := "radio"
+	seedSourcedPlay(t, h, user.ID, tk.ID, session, &radio, nil, 0.9, false)
+	// A knob turn to mark the timeline.
+	if err := h.recSettings.UpdateProfile(context.Background(), "radio",
+		map[string]float64{"taste_weight": 2}); err != nil {
+		t.Fatalf("UpdateProfile: %v", err)
+	}
+
+	req := httptest.NewRequest(http.MethodGet, "/api/admin/recommendation-trends", nil)
+	rec := httptest.NewRecorder()
+	newTrendsRouter(h).ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200 (%s)", rec.Code, rec.Body.String())
+	}
+	var resp trendsResp
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if resp.Weeks != trendsDefaultWeeks {
+		t.Errorf("weeks = %d, want %d", resp.Weeks, trendsDefaultWeeks)
+	}
+	var radioSeries *trendSeries
+	for i := range resp.Series {
+		if resp.Series[i].Key == "radio" {
+			radioSeries = &resp.Series[i]
+		}
+	}
+	if radioSeries == nil || len(radioSeries.Points) != 1 {
+		t.Fatalf("radio series = %+v, want one point", radioSeries)
+	}
+	if radioSeries.Points[0].TasteHitRate != 1.0 {
+		t.Errorf("taste_hit_rate = %v, want 1.0 (positive-weight artist)",
+			radioSeries.Points[0].TasteHitRate)
+	}
+	if len(resp.Markers) != 1 || resp.Markers[0].Scope != "radio" {
+		t.Errorf("markers = %+v, want the radio knob turn", resp.Markers)
+	}
+}
+
+func TestRecommendationTrends_InvalidWeeks(t *testing.T) {
+	h, _ := testHandlers(t)
+	req := httptest.NewRequest(http.MethodGet, "/api/admin/recommendation-trends?weeks=zero", nil)
+	rec := httptest.NewRecorder()
+	newTrendsRouter(h).ServeHTTP(rec, req)
+	if rec.Code != http.StatusBadRequest {
+		t.Errorf("status = %d, want 400", rec.Code)
+	}
+}

internal/api/admin_recommendation_tuning.go

@@ -87,7 +87,7 @@ func (h *handlers) tuningSnapshot() tuningSnapshot {
 }
 
 // handleGetRecommendationTuning implements GET /api/admin/recommendation-tuning.
-func (h *handlers) handleGetRecommendationTuning(w http.ResponseWriter, r *http.Request) {
+func (h *handlers) handleGetRecommendationTuning(w http.ResponseWriter, _ *http.Request) {
 	writeJSON(w, http.StatusOK, h.tuningSnapshot())
 }
 

internal/api/api.go

@@ -209,6 +209,8 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 				admin.Get("/recommendation-tuning", h.handleGetRecommendationTuning)
 				admin.Patch("/recommendation-tuning/{scope}", h.handlePatchRecommendationTuning)
 				admin.Post("/recommendation-tuning/{scope}/reset", h.handleResetRecommendationTuning)
+				// Weekly outcome trends + knob-turn markers (#1251).
+				admin.Get("/recommendation-trends", h.handleGetRecommendationTrends)
 			})
 
 			authed.Get("/playlists", h.handleListPlaylists)

internal/db/dbq/recommendation_metrics.sql.go

@@ -12,7 +12,6 @@ import (
 )
 
 const recommendationSourceMetricsForUser = `-- name: RecommendationSourceMetricsForUser :many
-
 SELECT
     pe.source,
     pe.pick_kind,
@@ -41,15 +40,6 @@ type RecommendationSourceMetricsForUserRow struct {
 	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 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 the completion_n plays that recorded one.
 // pick_kind splits For You plays into taste/fresh/unattributed (#1249);
@@ -80,3 +70,83 @@ func (q *Queries) RecommendationSourceMetricsForUser(ctx context.Context, arg Re
 	}
 	return items, nil
 }
+
+const recommendationWeeklyTrends = `-- name: RecommendationWeeklyTrends :many
+
+SELECT
+    date_trunc('week', pe.started_at)::date AS week_start,
+    pe.source,
+    count(*)::bigint AS plays,
+    count(*) FILTER (WHERE pe.was_skipped)::bigint AS skips,
+    count(pe.completion_ratio)::bigint AS completion_n,
+    COALESCE(avg(pe.completion_ratio), 0)::float8 AS avg_completion,
+    count(*) FILTER (WHERE tpa.artist_id IS NOT NULL)::bigint AS taste_hits
+FROM play_events pe
+JOIN tracks t ON t.id = pe.track_id
+LEFT JOIN taste_profile_artists tpa
+       ON tpa.user_id = pe.user_id
+      AND tpa.artist_id = t.artist_id
+      AND tpa.weight > 0
+WHERE pe.started_at > now() - ($1::int * INTERVAL '1 week')
+GROUP BY 1, 2
+ORDER BY 1, 2
+`
+
+type RecommendationWeeklyTrendsRow struct {
+	WeekStart     pgtype.Date
+	Source        *string
+	Plays         int64
+	Skips         int64
+	CompletionN   int64
+	AvgCompletion float64
+	TasteHits     int64
+}
+
+// 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 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.
+// Weekly per-source outcome series for the tuning lab's trend view
+// (#1251). Aggregated across ALL users: the tuning knobs are global,
+// so judging a knob turn needs global outcomes — rows carry rates
+// only, no track or user identity. NULL-source (manual) rows are
+// included as the baseline family.
+//
+// taste_hits counts plays whose track's artist has a positive weight
+// in that user's CURRENT taste profile — the "cheap recompute" option:
+// retroactive over the whole window, at the cost of drift (the profile
+// is today's, the play may be weeks old). Good enough to read whether
+// a surface is feeding taste-fitting tracks.
+// $1 window in weeks.
+func (q *Queries) RecommendationWeeklyTrends(ctx context.Context, weeks int32) ([]RecommendationWeeklyTrendsRow, error) {
+	rows, err := q.db.Query(ctx, recommendationWeeklyTrends, weeks)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []RecommendationWeeklyTrendsRow
+	for rows.Next() {
+		var i RecommendationWeeklyTrendsRow
+		if err := rows.Scan(
+			&i.WeekStart,
+			&i.Source,
+			&i.Plays,
+			&i.Skips,
+			&i.CompletionN,
+			&i.AvgCompletion,
+			&i.TasteHits,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}

internal/db/queries/recommendation_metrics.sql

@@ -8,6 +8,37 @@
 -- the Go handler; completion_n is carried so family merges can weight
 -- avg_completion correctly.
 
+-- name: RecommendationWeeklyTrends :many
+-- Weekly per-source outcome series for the tuning lab's trend view
+-- (#1251). Aggregated across ALL users: the tuning knobs are global,
+-- so judging a knob turn needs global outcomes — rows carry rates
+-- only, no track or user identity. NULL-source (manual) rows are
+-- included as the baseline family.
+--
+-- taste_hits counts plays whose track's artist has a positive weight
+-- in that user's CURRENT taste profile — the "cheap recompute" option:
+-- retroactive over the whole window, at the cost of drift (the profile
+-- is today's, the play may be weeks old). Good enough to read whether
+-- a surface is feeding taste-fitting tracks.
+-- $1 window in weeks.
+SELECT
+    date_trunc('week', pe.started_at)::date AS week_start,
+    pe.source,
+    count(*)::bigint AS plays,
+    count(*) FILTER (WHERE pe.was_skipped)::bigint AS skips,
+    count(pe.completion_ratio)::bigint AS completion_n,
+    COALESCE(avg(pe.completion_ratio), 0)::float8 AS avg_completion,
+    count(*) FILTER (WHERE tpa.artist_id IS NOT NULL)::bigint AS taste_hits
+FROM play_events pe
+JOIN tracks t ON t.id = pe.track_id
+LEFT JOIN taste_profile_artists tpa
+       ON tpa.user_id = pe.user_id
+      AND tpa.artist_id = t.artist_id
+      AND tpa.weight > 0
+WHERE pe.started_at > now() - (sqlc.arg(weeks)::int * INTERVAL '1 week')
+GROUP BY 1, 2
+ORDER BY 1, 2;
+
 -- name: RecommendationSourceMetricsForUser :many
 -- $1 user_id, $2 window_days. plays/skips are counts; avg_completion is the
 -- mean completion ratio over the completion_n plays that recorded one.

web/src/lib/api/tuning.ts

@@ -47,3 +47,40 @@ export function patchTuning(
 export function resetTuning(scope: TuningScope): Promise<TuningSnapshot> {
   return api.post<TuningSnapshot>(`/api/admin/recommendation-tuning/${scope}/reset`, {});
 }
+
+// Trends (#1251): weekly per-surface outcome series with knob-turn
+// markers. Mirrors internal/api/admin_recommendation_trends.go.
+
+export type TrendPoint = {
+  week_start: string;
+  plays: number;
+  skips: number;
+  skip_rate: number;
+  avg_completion: number;
+  taste_hit_rate: number;
+};
+
+export type TrendSeries = {
+  key: string;
+  label: string;
+  intent: string;
+  plays: number;
+  points: TrendPoint[];
+};
+
+export type TrendMarker = {
+  changed_at: string;
+  scope: string;
+  action: string;
+  changes: { field: string; old: number; new: number }[];
+};
+
+export type TrendsResponse = {
+  weeks: number;
+  series: TrendSeries[];
+  markers: TrendMarker[];
+};
+
+export function getTrends(weeks = 12): Promise<TrendsResponse> {
+  return api.get<TrendsResponse>(`/api/admin/recommendation-trends?weeks=${weeks}`);
+}

web/src/routes/admin/tuning/+page.svelte

@@ -4,10 +4,14 @@
     getTuning,
     patchTuning,
     resetTuning,
+    getTrends,
     type TuningScope,
     type TuningSnapshot,
     type WeightProfile,
-    type TasteTuning
+    type TasteTuning,
+    type TrendsResponse,
+    type TrendSeries,
+    type TrendMarker
   } from '$lib/api/tuning';
   import { errMessage } from '$lib/api/errors';
   import { pushToast } from '$lib/stores/toast.svelte';
@@ -124,6 +128,86 @@
       saving = null;
     }
   }
+
+  // Trends (#1251): weekly skip-rate sparklines per surface with
+  // knob-turn markers — the verify half of the tune→verify loop.
+
+  let trends = $state<TrendsResponse | null>(null);
+  let trendsFailed = $state(false);
+
+  $effect(() => {
+    getTrends()
+      .then((t) => {
+        trends = t;
+      })
+      .catch(() => {
+        trendsFailed = true;
+      });
+  });
+
+  const SPARK_W = 220;
+  const SPARK_H = 36;
+  const TREND_LOW_VOLUME = 20;
+
+  // The week axis is the sorted union of every series' buckets, so all
+  // sparklines and markers share one x scale.
+  const weekAxis = $derived.by(() => {
+    if (!trends) return [] as string[];
+    const set = new Set<string>();
+    for (const s of trends.series) for (const p of s.points) set.add(p.week_start);
+    return [...set].sort();
+  });
+
+  function xFor(week: string): number {
+    const i = weekAxis.indexOf(week);
+    if (i < 0 || weekAxis.length < 2) return 0;
+    return (i / (weekAxis.length - 1)) * SPARK_W;
+  }
+
+  // Polyline of the series' weekly skip rate on a fixed [0,1] y-scale
+  // (higher = worse, drawn upward) so rows are visually comparable.
+  function sparkPoints(s: TrendSeries): string {
+    return s.points
+      .map((p) => `${xFor(p.week_start).toFixed(1)},${(SPARK_H - p.skip_rate * SPARK_H).toFixed(1)}`)
+      .join(' ');
+  }
+
+  // A marker lands on the latest axis week that starts at/before it.
+  function markerX(m: TrendMarker): number {
+    const day = m.changed_at.slice(0, 10);
+    let idx = -1;
+    for (let i = 0; i < weekAxis.length; i++) {
+      if (weekAxis[i] <= day) idx = i;
+    }
+    if (idx < 0 || weekAxis.length < 2) return 0;
+    return (idx / (weekAxis.length - 1)) * SPARK_W;
+  }
+
+  function windowTasteHitRate(s: TrendSeries): number {
+    let plays = 0;
+    let hits = 0;
+    for (const p of s.points) {
+      plays += p.plays;
+      hits += p.taste_hit_rate * p.plays;
+    }
+    return plays > 0 ? hits / plays : 0;
+  }
+
+  function latest(s: TrendSeries): { skip: number; completion: number } {
+    const last = s.points[s.points.length - 1];
+    return last ? { skip: last.skip_rate, completion: last.avg_completion } : { skip: 0, completion: 0 };
+  }
+
+  function pct(v: number): string {
+    return `${(v * 100).toFixed(0)}%`;
+  }
+
+  function markerSummary(m: TrendMarker): string {
+    const when = m.changed_at.slice(0, 10);
+    if (m.action === 'reset') return `${when} — ${m.scope} reset to defaults`;
+    const fields = (m.changes ?? []).map((c) => `${c.field} ${c.old}→${c.new}`).join(', ');
+    return `${when} — ${m.scope}: ${fields}`;
+  }
 </script>
 
 <svelte:head>
@@ -247,4 +331,104 @@
       </div>
     </section>
   {/if}
+
+  <!-- Weekly trends (#1251): the verify half. Sparklines share one
+       week axis; dashed ticks mark knob turns so cause→effect reads
+       off the chart. -->
+  <section class="space-y-3 rounded border border-border bg-surface p-4">
+    <div>
+      <h2 class="text-lg font-semibold">Weekly trends</h2>
+      <p class="text-xs text-text-secondary">
+        Skip rate per surface over the last {trends?.weeks ?? 12} weeks (lower is better; all
+        users aggregated, rates only). Dashed ticks mark tuning changes. Taste hit is the share
+        of plays whose artist fits the current taste profile.
+      </p>
+    </div>
+    {#if trendsFailed}
+      <p class="text-sm text-text-secondary">Couldn't load trends.</p>
+    {:else if !trends}
+      <p class="text-sm text-text-secondary">Loading…</p>
+    {:else if trends.series.length === 0}
+      <p class="text-sm text-text-secondary">
+        No plays recorded yet — trends appear once listening accumulates.
+      </p>
+    {:else}
+      <table class="w-full text-sm">
+        <thead>
+          <tr class="text-left text-text-secondary">
+            <th class="py-1 font-medium">Surface</th>
+            <th class="py-1 font-medium">Skip rate by week</th>
+            <th class="py-1 text-right font-medium">Plays</th>
+            <th class="py-1 text-right font-medium">Latest skip</th>
+            <th class="py-1 text-right font-medium">Latest completion</th>
+            <th class="py-1 text-right font-medium">Taste hit</th>
+          </tr>
+        </thead>
+        <tbody>
+          {#each trends.series as s (s.key)}
+            <tr
+              class="border-t border-border"
+              class:opacity-60={s.plays < TREND_LOW_VOLUME}
+              title={s.plays < TREND_LOW_VOLUME
+                ? 'Fewer than 20 plays in the window — treat as anecdote, not signal.'
+                : undefined}
+            >
+              <td class="py-1.5 pr-2">{s.label}</td>
+              <td class="py-1.5">
+                <svg
+                  width={SPARK_W}
+                  height={SPARK_H}
+                  viewBox="0 0 {SPARK_W} {SPARK_H}"
+                  role="img"
+                  aria-label="{s.label} weekly skip rate"
+                  data-testid="sparkline-{s.key}"
+                >
+                  <line x1="0" y1={SPARK_H - 0.5} x2={SPARK_W} y2={SPARK_H - 0.5}
+                        stroke="currentColor" opacity="0.15" />
+                  {#each trends.markers as m, i (i)}
+                    <line
+                      x1={markerX(m)} y1="0" x2={markerX(m)} y2={SPARK_H}
+                      stroke="currentColor" opacity="0.35" stroke-dasharray="2,2"
+                    >
+                      <title>{markerSummary(m)}</title>
+                    </line>
+                  {/each}
+                  {#if s.points.length > 1}
+                    <polyline
+                      class="text-accent"
+                      points={sparkPoints(s)}
+                      fill="none"
+                      stroke="currentColor"
+                      stroke-width="1.5"
+                    />
+                  {:else if s.points.length === 1}
+                    <circle
+                      class="text-accent"
+                      cx={xFor(s.points[0].week_start)}
+                      cy={SPARK_H - s.points[0].skip_rate * SPARK_H}
+                      r="2" fill="currentColor"
+                    />
+                  {/if}
+                </svg>
+              </td>
+              <td class="py-1.5 text-right tabular-nums">{s.plays}</td>
+              <td class="py-1.5 text-right tabular-nums">{pct(latest(s).skip)}</td>
+              <td class="py-1.5 text-right tabular-nums">{pct(latest(s).completion)}</td>
+              <td class="py-1.5 text-right tabular-nums">{pct(windowTasteHitRate(s))}</td>
+            </tr>
+          {/each}
+        </tbody>
+      </table>
+      {#if trends.markers.length > 0}
+        <div class="space-y-1">
+          <h3 class="text-sm font-medium">Tuning changes in this window</h3>
+          <ul class="space-y-0.5 text-xs text-text-secondary">
+            {#each trends.markers as m, i (i)}
+              <li>{markerSummary(m)}</li>
+            {/each}
+          </ul>
+        </div>
+      {/if}
+    {/if}
+  </section>
 </div>

web/src/routes/admin/tuning/tuning.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test, vi, beforeEach } from 'vitest';
 import { render, screen, fireEvent, waitFor } from '@testing-library/svelte';
-import type { TuningSnapshot } from '$lib/api/tuning';
+import type { TuningSnapshot, TrendsResponse } from '$lib/api/tuning';
 
 vi.mock('$lib/api/tuning', async (orig) => {
   const actual = (await orig()) as Record<string, unknown>;
@@ -8,7 +8,8 @@ vi.mock('$lib/api/tuning', async (orig) => {
     ...actual,
     getTuning: vi.fn(),
     patchTuning: vi.fn(),
-    resetTuning: vi.fn()
+    resetTuning: vi.fn(),
+    getTrends: vi.fn()
   };
 });
 
@@ -16,7 +17,7 @@ const pushToast = vi.fn();
 vi.mock('$lib/stores/toast.svelte', () => ({ pushToast: (...a: unknown[]) => pushToast(...a) }));
 
 import TuningPage from './+page.svelte';
-import { getTuning, patchTuning, resetTuning } from '$lib/api/tuning';
+import { getTuning, patchTuning, resetTuning, getTrends } from '$lib/api/tuning';
 
 const weights = (over: Partial<Record<string, number>> = {}) => ({
   base_weight: 1,
@@ -50,8 +51,11 @@ function snapshot(over: Partial<TuningSnapshot> = {}): TuningSnapshot {
   } as TuningSnapshot;
 }
 
+const emptyTrends: TrendsResponse = { weeks: 12, series: [], markers: [] };
+
 beforeEach(() => {
   vi.clearAllMocks();
+  (getTrends as ReturnType<typeof vi.fn>).mockResolvedValue(emptyTrends);
 });
 
 describe('Admin tuning page', () => {
@@ -111,4 +115,80 @@ describe('Admin tuning page', () => {
       screen.getByTitle(/deviates from the shipped default \(1\.5\)/i)
     ).toBeInTheDocument();
   });
+
+  test('renders weekly trend rows with sparklines and knob-turn markers (#1251)', async () => {
+    (getTuning as ReturnType<typeof vi.fn>).mockResolvedValue(snapshot());
+    (getTrends as ReturnType<typeof vi.fn>).mockResolvedValue({
+      weeks: 12,
+      series: [
+        {
+          key: 'radio',
+          label: 'Radio',
+          intent: 'go_to',
+          plays: 40,
+          points: [
+            {
+              week_start: '2026-06-22',
+              plays: 25,
+              skips: 5,
+              skip_rate: 0.2,
+              avg_completion: 0.8,
+              taste_hit_rate: 0.6
+            },
+            {
+              week_start: '2026-06-29',
+              plays: 15,
+              skips: 6,
+              skip_rate: 0.4,
+              avg_completion: 0.7,
+              taste_hit_rate: 0.5
+            }
+          ]
+        },
+        {
+          key: 'discover',
+          label: 'Discover',
+          intent: 'discovery',
+          plays: 5,
+          points: [
+            {
+              week_start: '2026-06-29',
+              plays: 5,
+              skips: 3,
+              skip_rate: 0.6,
+              avg_completion: 0.4,
+              taste_hit_rate: 0.2
+            }
+          ]
+        }
+      ],
+      markers: [
+        {
+          changed_at: '2026-06-30T10:00:00Z',
+          scope: 'radio',
+          action: 'update',
+          changes: [{ field: 'taste_weight', old: 1, new: 2 }]
+        }
+      ]
+    } satisfies TrendsResponse);
+    render(TuningPage);
+    await waitFor(() => expect(screen.getByText('Weekly trends')).toBeInTheDocument());
+    expect(screen.getByTestId('sparkline-radio')).toBeInTheDocument();
+    expect(screen.getByTestId('sparkline-discover')).toBeInTheDocument();
+    // Latest skip rate column for radio = 40% (also discover's latest
+    // completion, hence getAllBy).
+    expect(screen.getAllByText('40%').length).toBeGreaterThan(0);
+    // The knob turn is listed under the chart.
+    expect(screen.getByText(/2026-06-30 — radio: taste_weight 1→2/)).toBeInTheDocument();
+    // Low-volume series (5 plays) is dimmed as anecdote.
+    expect(screen.getByTitle(/fewer than 20 plays in the window/i)).toBeInTheDocument();
+  });
+
+  test('empty trends show the accumulation hint', async () => {
+    (getTuning as ReturnType<typeof vi.fn>).mockResolvedValue(snapshot());
+    render(TuningPage);
+    await waitFor(() =>
+      expect(screen.getByText(/trends appear once listening accumulates/i)).toBeInTheDocument()
+    );
+  });
 });