feat(taste): device-class context conditioning — #1551

Milestone #160 Opt 3b. Adds device class as a third context axis on top
of the #1531 time-of-day/weekday affinity: on the radio path, a candidate
is boosted when its artist concentrates in the current (daypart × weekday
× device) cell. Client-sent (client_id is opaque; no UA stored), so it's
captured going forward and applies to radio only (daily mixes are
cron-built with no device → stay device-agnostic).

Server:
- Migration 0048: play_events.device_class text NULL (no CHECK; normalized
  in Go — one whitelist entry per new client class, not a migration).
- events.go: eventRequest.device_class + normalizeDeviceClass (whitelist →
  mobile/web/…, else "other", empty → NULL); threaded through both
  RecordPlayStartedWithSource and RecordOfflinePlay into InsertPlayEvent.
- ListArtistContextPlayCountsForUser gains a current-device param; the cell
  FILTER adds AND ($2='' OR device_class=$2) — '' reproduces the #1531
  time-only behaviour exactly (used by mixes). SessionVector.DeviceClass
  carries it; the radio handler derives the current device from the user's
  latest play (GetLatestPlayDeviceClassForUser) — request-free proxy.
- No new tuning knob: device narrows the existing ContextAffinityScore
  (reuses context_time_weight).

Clients:
- web: play_started sends device_class 'web'.
- android: play_started + offline replay send 'mobile' (EventsWire +
  PlayOfflinePayload + MutationReplayer + PlayEventsReporter).

Test: LoadContextAffinity device-narrowing integration test (mobile vs web
artist separation; device-agnostic parity).

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

internal/db/dbq/events.sql.go

@@ -54,7 +54,7 @@ func (q *Queries) GetMostRecentPlaySessionForUser(ctx context.Context, userID pg
 }
 
 const getOpenPlayEventForUser = `-- name: GetOpenPlayEventForUser :one
-SELECT id, user_id, track_id, session_id, started_at, ended_at, duration_played_ms, completion_ratio, was_skipped, client_id, session_vector_at_play, scrobbled_at, source, pick_kind FROM play_events
+SELECT id, user_id, track_id, session_id, started_at, ended_at, duration_played_ms, completion_ratio, was_skipped, client_id, session_vector_at_play, scrobbled_at, source, pick_kind, device_class FROM play_events
 WHERE user_id = $1 AND ended_at IS NULL
 ORDER BY started_at DESC
 LIMIT 1
@@ -80,12 +80,13 @@ func (q *Queries) GetOpenPlayEventForUser(ctx context.Context, userID pgtype.UUI
 		&i.ScrobbledAt,
 		&i.Source,
 		&i.PickKind,
+		&i.DeviceClass,
 	)
 	return i, err
 }
 
 const getPlayEventByID = `-- name: GetPlayEventByID :one
-SELECT id, user_id, track_id, session_id, started_at, ended_at, duration_played_ms, completion_ratio, was_skipped, client_id, session_vector_at_play, scrobbled_at, source, pick_kind FROM play_events WHERE id = $1
+SELECT id, user_id, track_id, session_id, started_at, ended_at, duration_played_ms, completion_ratio, was_skipped, client_id, session_vector_at_play, scrobbled_at, source, pick_kind, device_class FROM play_events WHERE id = $1
 `
 
 func (q *Queries) GetPlayEventByID(ctx context.Context, id pgtype.UUID) (PlayEvent, error) {
@@ -106,6 +107,7 @@ func (q *Queries) GetPlayEventByID(ctx context.Context, id pgtype.UUID) (PlayEve
 		&i.ScrobbledAt,
 		&i.Source,
 		&i.PickKind,
+		&i.DeviceClass,
 	)
 	return i, err
 }
@@ -144,19 +146,22 @@ func (q *Queries) GetSystemPickKindForTrack(ctx context.Context, arg GetSystemPi
 
 const insertPlayEvent = `-- name: InsertPlayEvent :one
 INSERT INTO play_events (
-    user_id, track_id, session_id, started_at, client_id, source, pick_kind
-) VALUES ($1, $2, $3, $4, $5, $6, $7::text)
-RETURNING id, user_id, track_id, session_id, started_at, ended_at, duration_played_ms, completion_ratio, was_skipped, client_id, session_vector_at_play, scrobbled_at, source, pick_kind
+    user_id, track_id, session_id, started_at, client_id, source, pick_kind,
+    device_class
+) VALUES ($1, $2, $3, $4, $5, $6, $7::text,
+    $8::text)
+RETURNING id, user_id, track_id, session_id, started_at, ended_at, duration_played_ms, completion_ratio, was_skipped, client_id, session_vector_at_play, scrobbled_at, source, pick_kind, device_class
 `
 
 type InsertPlayEventParams struct {
-	UserID    pgtype.UUID
-	TrackID   pgtype.UUID
-	SessionID pgtype.UUID
-	StartedAt pgtype.Timestamptz
-	ClientID  *string
-	Source    *string
-	PickKind  *string
+	UserID      pgtype.UUID
+	TrackID     pgtype.UUID
+	SessionID   pgtype.UUID
+	StartedAt   pgtype.Timestamptz
+	ClientID    *string
+	Source      *string
+	PickKind    *string
+	DeviceClass *string
 }
 
 // pick_kind is non-NULL only for system-playlist plays whose track was
@@ -171,6 +176,7 @@ func (q *Queries) InsertPlayEvent(ctx context.Context, arg InsertPlayEventParams
 		arg.ClientID,
 		arg.Source,
 		arg.PickKind,
+		arg.DeviceClass,
 	)
 	var i PlayEvent
 	err := row.Scan(
@@ -188,6 +194,7 @@ func (q *Queries) InsertPlayEvent(ctx context.Context, arg InsertPlayEventParams
 		&i.ScrobbledAt,
 		&i.Source,
 		&i.PickKind,
+		&i.DeviceClass,
 	)
 	return i, err
 }
@@ -333,7 +340,7 @@ SET ended_at = $2,
     completion_ratio = $4,
     was_skipped = $5
 WHERE id = $1
-RETURNING id, user_id, track_id, session_id, started_at, ended_at, duration_played_ms, completion_ratio, was_skipped, client_id, session_vector_at_play, scrobbled_at, source, pick_kind
+RETURNING id, user_id, track_id, session_id, started_at, ended_at, duration_played_ms, completion_ratio, was_skipped, client_id, session_vector_at_play, scrobbled_at, source, pick_kind, device_class
 `
 
 type UpdatePlayEventEndedParams struct {
@@ -371,6 +378,7 @@ func (q *Queries) UpdatePlayEventEnded(ctx context.Context, arg UpdatePlayEventE
 		&i.ScrobbledAt,
 		&i.Source,
 		&i.PickKind,
+		&i.DeviceClass,
 	)
 	return i, err
 }

internal/db/dbq/models.go

@@ -384,6 +384,7 @@ type PlayEvent struct {
 	ScrobbledAt         pgtype.Timestamptz
 	Source              *string
 	PickKind            *string
+	DeviceClass         *string
 }
 
 type PlaySession struct {

internal/db/dbq/recommendation.sql.go

@@ -11,6 +11,24 @@ import (
 	"github.com/jackc/pgx/v5/pgtype"
 )
 
+const getLatestPlayDeviceClassForUser = `-- name: GetLatestPlayDeviceClassForUser :one
+SELECT device_class
+FROM play_events
+WHERE user_id = $1
+ORDER BY started_at DESC
+LIMIT 1
+`
+
+// The device_class of the user's most recent play (#1551), used as the
+// "current device" for radio context conditioning. NULL when the latest play
+// predates device capture or came from a client that didn't send one.
+func (q *Queries) GetLatestPlayDeviceClassForUser(ctx context.Context, userID pgtype.UUID) (*string, error) {
+	row := q.db.QueryRow(ctx, getLatestPlayDeviceClassForUser, userID)
+	var device_class *string
+	err := row.Scan(&device_class)
+	return device_class, err
+}
+
 const listArtistContextPlayCountsForUser = `-- name: ListArtistContextPlayCountsForUser :many
 WITH tz AS (
     SELECT COALESCE(NULLIF(u.timezone, ''), 'UTC') AS zone
@@ -30,6 +48,7 @@ now_cell AS (
 ),
 plays AS (
     SELECT t.artist_id,
+           pe.device_class,
            CASE
                WHEN EXTRACT(hour FROM pe.started_at AT TIME ZONE tz.zone) < 5  THEN 3
                WHEN EXTRACT(hour FROM pe.started_at AT TIME ZONE tz.zone) < 12 THEN 0
@@ -50,11 +69,17 @@ SELECT p.artist_id,
        count(*) FILTER (
            WHERE p.daypart = (SELECT daypart FROM now_cell)
              AND p.is_weekend = (SELECT is_weekend FROM now_cell)
+             AND ($2::text = '' OR p.device_class = $2::text)
        ) AS cell_plays
 FROM plays p
 GROUP BY p.artist_id
 `
 
+type ListArtistContextPlayCountsForUserParams struct {
+	ID      pgtype.UUID
+	Column2 string
+}
+
 type ListArtistContextPlayCountsForUserRow struct {
 	ArtistID   pgtype.UUID
 	TotalPlays int64
@@ -62,14 +87,16 @@ type ListArtistContextPlayCountsForUserRow struct {
 }
 
 // Per-artist completed-play counts split by whether each play falls in the
-// CURRENT daypart × weekday-type cell, in the user's local timezone (#1531).
-// Feeds the context-affinity scoring term: an artist whose plays concentrate
-// in the current cell (vs the user's overall baseline, computed Go-side from
-// these rows) gets boosted right now. Skips excluded; a 365-day window bounds
-// cost. Daypart buckets: night [22,5) morning [5,12) afternoon [12,17)
-// evening [17,22). Weekend = ISO days 6–7 (Sat/Sun).
-func (q *Queries) ListArtistContextPlayCountsForUser(ctx context.Context, id pgtype.UUID) ([]ListArtistContextPlayCountsForUserRow, error) {
-	rows, err := q.db.Query(ctx, listArtistContextPlayCountsForUser, id)
+// CURRENT context cell, in the user's local timezone (#1531). The cell is
+// daypart × weekday-type, optionally narrowed by device class (#1551): when
+// $2 (the current device) is ”, the device dimension is ignored (identical to
+// the time-only #1531 behaviour, used by the daily mixes which have no device);
+// when $2 is set (radio), a play only counts in the cell if its device_class
+// matches. Feeds the context-affinity scoring term. Skips excluded; a 365-day
+// window bounds cost. Daypart buckets: night [22,5) morning [5,12)
+// afternoon [12,17) evening [17,22). Weekend = ISO days 6–7 (Sat/Sun).
+func (q *Queries) ListArtistContextPlayCountsForUser(ctx context.Context, arg ListArtistContextPlayCountsForUserParams) ([]ListArtistContextPlayCountsForUserRow, error) {
+	rows, err := q.db.Query(ctx, listArtistContextPlayCountsForUser, arg.ID, arg.Column2)
 	if err != nil {
 		return nil, err
 	}

internal/db/migrations/0048_play_events_device_class.down.sql

@@ -0,0 +1 @@
+ALTER TABLE play_events DROP COLUMN IF EXISTS device_class;

internal/db/migrations/0048_play_events_device_class.up.sql

@@ -0,0 +1,9 @@
+-- 0048_play_events_device_class.up.sql — device-class context conditioning
+-- (#1551, milestone #160 Opt 3b). Records which class of device a play came
+-- from (mobile / web / …), sent by the client on play-start and normalized
+-- server-side. Extends the #1531 time-of-day/weekday affinity cell to
+-- (daypart × weekday × device) for the radio path. Nullable + no CHECK: values
+-- are normalized in Go (avoids a CHECK-migration each time a client class is
+-- added, rule #36), and historical rows stay NULL → excluded from the device
+-- dimension (a graceful cold-start; the facet ramps as new plays land).
+ALTER TABLE play_events ADD COLUMN device_class text;

internal/db/queries/events.sql

@@ -28,8 +28,10 @@ LIMIT 1;
 -- found (with a stamped kind) in the user's live snapshot for that
 -- variant at ingestion time (#1249, generalized in #1270).
 INSERT INTO play_events (
-    user_id, track_id, session_id, started_at, client_id, source, pick_kind
-) VALUES ($1, $2, $3, $4, $5, $6, sqlc.narg(pick_kind)::text)
+    user_id, track_id, session_id, started_at, client_id, source, pick_kind,
+    device_class
+) VALUES ($1, $2, $3, $4, $5, $6, sqlc.narg(pick_kind)::text,
+    sqlc.narg(device_class)::text)
 RETURNING *;
 
 -- name: GetSystemPickKindForTrack :one

internal/db/queries/recommendation.sql

@@ -195,12 +195,14 @@ GROUP BY t.id, t.title, t.album_id, t.artist_id, t.duration_ms, t.file_path,
 
 -- name: ListArtistContextPlayCountsForUser :many
 -- Per-artist completed-play counts split by whether each play falls in the
--- CURRENT daypart × weekday-type cell, in the user's local timezone (#1531).
--- Feeds the context-affinity scoring term: an artist whose plays concentrate
--- in the current cell (vs the user's overall baseline, computed Go-side from
--- these rows) gets boosted right now. Skips excluded; a 365-day window bounds
--- cost. Daypart buckets: night [22,5) morning [5,12) afternoon [12,17)
--- evening [17,22). Weekend = ISO days 6–7 (Sat/Sun).
+-- CURRENT context cell, in the user's local timezone (#1531). The cell is
+-- daypart × weekday-type, optionally narrowed by device class (#1551): when
+-- $2 (the current device) is '', the device dimension is ignored (identical to
+-- the time-only #1531 behaviour, used by the daily mixes which have no device);
+-- when $2 is set (radio), a play only counts in the cell if its device_class
+-- matches. Feeds the context-affinity scoring term. Skips excluded; a 365-day
+-- window bounds cost. Daypart buckets: night [22,5) morning [5,12)
+-- afternoon [12,17) evening [17,22). Weekend = ISO days 6–7 (Sat/Sun).
 WITH tz AS (
     SELECT COALESCE(NULLIF(u.timezone, ''), 'UTC') AS zone
     FROM users u WHERE u.id = $1
@@ -219,6 +221,7 @@ now_cell AS (
 ),
 plays AS (
     SELECT t.artist_id,
+           pe.device_class,
            CASE
                WHEN EXTRACT(hour FROM pe.started_at AT TIME ZONE tz.zone) < 5  THEN 3
                WHEN EXTRACT(hour FROM pe.started_at AT TIME ZONE tz.zone) < 12 THEN 0
@@ -239,10 +242,21 @@ SELECT p.artist_id,
        count(*) FILTER (
            WHERE p.daypart = (SELECT daypart FROM now_cell)
              AND p.is_weekend = (SELECT is_weekend FROM now_cell)
+             AND ($2::text = '' OR p.device_class = $2::text)
        ) AS cell_plays
 FROM plays p
 GROUP BY p.artist_id;
 
+-- name: GetLatestPlayDeviceClassForUser :one
+-- The device_class of the user's most recent play (#1551), used as the
+-- "current device" for radio context conditioning. NULL when the latest play
+-- predates device capture or came from a client that didn't send one.
+SELECT device_class
+FROM play_events
+WHERE user_id = $1
+ORDER BY started_at DESC
+LIMIT 1;
+
 -- name: SuggestArtistsForUser :many
 -- M5c: per-user artist suggestions ranked by signal x similarity. The
 -- seeds CTE collects the user's likes (x5) plus recency-decayed plays