feat(recommendation): For You exploration attribution — taste vs fresh picks

Milestone #127 step 2 (#1249). For You deliberately blends two
populations — a head of top-scored taste picks and a tail sampled from
deeper ranking (the freshness injection) — but the metrics judged it as
one blob, so its skip rate couldn't distinguish "the taste engine is
missing" from "the freshness tax is too high". That number decides the
exploration share before we tune it.

- Migration 0038: nullable pick_kind ('taste'|'fresh') on both
  playlist_tracks (stamped at snapshot build) and play_events (frozen at
  play-ingestion — the snapshot rebuilds daily, so attribution cannot be
  reconstructed at read time).
- Builder: pickHeadAndTail marks head=taste / tail=fresh; the small-pool
  fallback is all taste (top-N-by-score IS the taste mechanism). Other
  variants persist NULL.
- Ingestion: for_you plays (live + offline replay) look the track up in
  the user's current snapshot; not found → unattributed, never guessed.
- Metrics: For You's row gains a breakdown (taste / fresh / earlier
  unattributed plays), parent row stays the sum; web card renders the
  sub-rows indented with the same baseline deltas + low-data dimming.

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

internal/playevents/writer.go

@@ -97,6 +97,35 @@ var systemPlaylistSources = map[string]bool{
 	"songs_like_artist": true,
 }
 
+// sourceForYou is the one source whose plays carry exploration
+// attribution (taste vs fresh pick, #1249).
+const sourceForYou = "for_you"
+
+// lookupForYouPickKind resolves a For-You play's pick_kind ('taste' or
+// 'fresh') from the user's live snapshot at ingestion time. Attribution
+// must be frozen now — the snapshot rebuilds daily, so it can't be
+// reconstructed at metrics-read time. Returns nil (unattributed) when
+// the track isn't in the current snapshot: plays predating the feature,
+// or an offline replay arriving after the track rotated out. Real DB
+// errors propagate and fail the caller's transaction.
+func lookupForYouPickKind(
+	ctx context.Context,
+	q *dbq.Queries,
+	userID, trackID pgtype.UUID,
+) (*string, error) {
+	kind, err := q.GetForYouPickKindForTrack(ctx, dbq.GetForYouPickKindForTrackParams{
+		UserID:  userID,
+		TrackID: trackID,
+	})
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return kind, nil
+}
+
 // RecordPlayStartedWithSource is RecordPlayStarted plus a `source`
 // tag identifying which surface the play came from. When source is a
 // known system-playlist kind the track is appended to that user's
@@ -127,6 +156,13 @@ func (w *Writer) RecordPlayStartedWithSource(
 		if source != "" {
 			sourcePtr = &source
 		}
+		var pickKind *string
+		if source == sourceForYou {
+			pickKind, err = lookupForYouPickKind(ctx, q, userID, trackID)
+			if err != nil {
+				return err
+			}
+		}
 		ev, err := q.InsertPlayEvent(ctx, dbq.InsertPlayEventParams{
 			UserID:    userID,
 			TrackID:   trackID,
@@ -134,6 +170,7 @@ func (w *Writer) RecordPlayStartedWithSource(
 			StartedAt: pgtype.Timestamptz{Time: at, Valid: true},
 			ClientID:  clientIDPtr,
 			Source:    sourcePtr,
+			PickKind:  pickKind,
 		})
 		if err != nil {
 			return err
@@ -395,6 +432,13 @@ func (w *Writer) RecordOfflinePlay(
 		if source != "" {
 			sourcePtr = &source
 		}
+		var pickKind *string
+		if source == sourceForYou {
+			pickKind, err = lookupForYouPickKind(ctx, q, userID, trackID)
+			if err != nil {
+				return err
+			}
+		}
 		ev, err := q.InsertPlayEvent(ctx, dbq.InsertPlayEventParams{
 			UserID:    userID,
 			TrackID:   trackID,
@@ -402,6 +446,7 @@ func (w *Writer) RecordOfflinePlay(
 			StartedAt: pgtype.Timestamptz{Time: at, Valid: true},
 			ClientID:  clientIDPtr,
 			Source:    sourcePtr,
+			PickKind:  pickKind,
 		})
 		if err != nil {
 			return err

internal/playevents/writer_test.go

@@ -488,3 +488,102 @@ func TestRecordPlayStarted_NoRotationWithoutSource(t *testing.T) {
 		t.Errorf("expected no rotation row for a source-less play")
 	}
 }
+
+// seedForYouSnapshot creates a system For You playlist containing the
+// fixture track with the given pick_kind, mimicking what the builder
+// persists (#1249).
+func seedForYouSnapshot(t *testing.T, f fixture, pickKind string) {
+	t.Helper()
+	variant := "for_you"
+	pl, err := f.q.CreateSystemPlaylist(context.Background(), dbq.CreateSystemPlaylistParams{
+		UserID: f.user, Name: "For You", SystemVariant: &variant,
+	})
+	if err != nil {
+		t.Fatalf("CreateSystemPlaylist: %v", err)
+	}
+	if _, err := f.q.AppendPlaylistTrack(context.Background(), dbq.AppendPlaylistTrackParams{
+		PlaylistID: pl.ID, TrackID: f.track, PickKind: &pickKind,
+	}); err != nil {
+		t.Fatalf("AppendPlaylistTrack: %v", err)
+	}
+}
+
+func TestRecordPlayStartedWithSource_StampsForYouPickKind(t *testing.T) {
+	f := newFixture(t, 200_000)
+	seedForYouSnapshot(t, f, "fresh")
+	res, err := f.w.RecordPlayStartedWithSource(
+		context.Background(), f.user, f.track, "c", "for_you", time.Now().UTC(),
+	)
+	if err != nil {
+		t.Fatalf("RecordPlayStartedWithSource: %v", err)
+	}
+	got, err := f.q.GetPlayEventByID(context.Background(), res.PlayEventID)
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+	if got.PickKind == nil || *got.PickKind != "fresh" {
+		t.Errorf("pick_kind = %v, want fresh (frozen from live snapshot)", got.PickKind)
+	}
+}
+
+func TestRecordPlayStartedWithSource_NoSnapshotMatch_PickKindNull(t *testing.T) {
+	// A for_you play whose track isn't in the current snapshot (rotated
+	// out, or no snapshot exists) stays unattributed rather than guessing.
+	f := newFixture(t, 200_000)
+	res, err := f.w.RecordPlayStartedWithSource(
+		context.Background(), f.user, f.track, "c", "for_you", time.Now().UTC(),
+	)
+	if err != nil {
+		t.Fatalf("RecordPlayStartedWithSource: %v", err)
+	}
+	got, err := f.q.GetPlayEventByID(context.Background(), res.PlayEventID)
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+	if got.PickKind != nil {
+		t.Errorf("pick_kind = %q, want NULL (track not in snapshot)", *got.PickKind)
+	}
+}
+
+func TestRecordPlayStartedWithSource_NonForYouSource_PickKindNull(t *testing.T) {
+	// Even with a For You snapshot containing the track, a play from a
+	// different surface must not pick up For You attribution.
+	f := newFixture(t, 200_000)
+	seedForYouSnapshot(t, f, "taste")
+	res, err := f.w.RecordPlayStartedWithSource(
+		context.Background(), f.user, f.track, "c", "discover", time.Now().UTC(),
+	)
+	if err != nil {
+		t.Fatalf("RecordPlayStartedWithSource: %v", err)
+	}
+	got, err := f.q.GetPlayEventByID(context.Background(), res.PlayEventID)
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+	if got.PickKind != nil {
+		t.Errorf("pick_kind = %q, want NULL for non-for_you source", *got.PickKind)
+	}
+}
+
+func TestRecordOfflinePlay_StampsForYouPickKind(t *testing.T) {
+	// The offline replay path threads source the same way; a replayed
+	// for_you play whose track is still in the snapshot gets attributed.
+	f := newFixture(t, 200_000)
+	seedForYouSnapshot(t, f, "taste")
+	at := time.Now().UTC().Add(-time.Hour)
+	if err := f.w.RecordOfflinePlay(
+		context.Background(), f.user, f.track, "c", "for_you", at, 180_000,
+	); err != nil {
+		t.Fatalf("RecordOfflinePlay: %v", err)
+	}
+	var pickKind *string
+	if err := f.pool.QueryRow(context.Background(),
+		`SELECT pick_kind FROM play_events WHERE user_id = $1 AND track_id = $2`,
+		f.user, f.track,
+	).Scan(&pickKind); err != nil {
+		t.Fatalf("select: %v", err)
+	}
+	if pickKind == nil || *pickKind != "taste" {
+		t.Errorf("pick_kind = %v, want taste", pickKind)
+	}
+}