From b9937d6e3b4eaf7d029de38220939523b4289ed8 Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Mon, 27 Apr 2026 07:35:13 -0400 Subject: [PATCH] docs(plan): add M3 weighted shuffle v1 implementation plan 7 tasks: pure score function, pure shuffle orchestrator, sqlc LoadRadioCandidates query, DB-backed candidate loader, RecommendationConfig + YAML, /api/radio handler rewrite, final verification + branch finish. --- .../plans/2026-04-27-m3-shuffle.md | 1588 +++++++++++++++++ 1 file changed, 1588 insertions(+) create mode 100644 docs/superpowers/plans/2026-04-27-m3-shuffle.md diff --git a/docs/superpowers/plans/2026-04-27-m3-shuffle.md b/docs/superpowers/plans/2026-04-27-m3-shuffle.md new file mode 100644 index 00000000..652bb836 --- /dev/null +++ b/docs/superpowers/plans/2026-04-27-m3-shuffle.md @@ -0,0 +1,1588 @@ +# M3 Weighted Shuffle v1 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Replace the M2 stub `/api/radio` (currently returns just the seed track) with a real weighted-shuffle implementation that scores user library tracks against a per-track-stats formula and returns a top-N queue ordered by score. + +**Architecture:** New `internal/recommendation` package with three layers — pure scoring function (`score.go`), pure orchestration (`shuffle.go`), and DB-backed candidate loader (`candidates.go`). The HTTP handler at `internal/api/radio.go` becomes a thin shim that validates the seed, calls the loader, calls the orchestrator, prepends the seed, and returns JSON. Stats (`is_liked`, `play_count`, `skip_count`, `last_played_at`) are computed in one SQL query joining `tracks` ↔ `general_likes` ↔ aggregated `play_events`. No new schema — all inputs from existing tables. + +**Tech Stack:** Go 1.23 + chi + sqlc + pgx/v5. No web changes (the existing `playRadio` action already calls `/api/radio?seed_track=…` and consumes `RadioResponse`). + +**Reference:** design spec at `docs/superpowers/specs/2026-04-27-m3-shuffle-design.md`. + +--- + +## File Structure + +**New server files:** + +| File | Responsibility | +|---|---| +| `internal/recommendation/score.go` | Pure `Score(inputs, weights, now, rng) → float64` + `recencyDecay` + `skipRatio` helpers. | +| `internal/recommendation/score_test.go` | Boundary cases for every term, cold-start, jitter determinism. | +| `internal/recommendation/shuffle.go` | Pure `Shuffle(candidates, weights, now, rng, limit) []Candidate` — composes Score + sort + truncate. | +| `internal/recommendation/shuffle_test.go` | Liked-rank-higher, high-skip-rejected, jitter-doesn't-reorder, limit. | +| `internal/recommendation/candidates.go` | `LoadCandidates(ctx, q, userID, seedID, recentlyPlayedHours) → []Candidate` — wraps the sqlc query, projects rows to `Candidate` (Track + ScoringInputs). | +| `internal/recommendation/candidates_test.go` | Live-DB tests: seed exclusion, recently-played exclusion, stat-join correctness, cross-user isolation. | +| `internal/db/queries/recommendation.sql` | One sqlc query: `LoadRadioCandidates`. | +| `internal/db/dbq/recommendation.sql.go` | Generated bindings. | + +**Modified server files:** + +| File | Change | +|---|---| +| `internal/api/radio.go` | Replace stub. New flow: validate, load candidates, shuffle, prepend seed, return JSON. | +| `internal/api/radio_test.go` | Replace existing 5 stub tests with the v1 weighted-shuffle scenarios. | +| `internal/config/config.go` + `config.example.yaml` | Add `RecommendationConfig` with weights + radio size + recently-played-hours. | +| `internal/api/api.go` | Mount signature gains `cfg config.RecommendationConfig`; handlers struct gains `recCfg` field. | +| `internal/server/server.go` + `cmd/minstrel/main.go` | Pass `cfg.Recommendation` through `Mount`. | + +**No web changes.** The existing `playRadio(seedTrackId)` already consumes `{ tracks: TrackRef[] }`. + +--- + +## Task 1: Pure scoring function + +**Files:** +- Create: `internal/recommendation/score.go` +- Create: `internal/recommendation/score_test.go` + +Pure Go, no DB. The function takes its inputs explicitly and an injectable RNG so tests pin jitter to deterministic values. + +- [ ] **Step 1: Write the failing tests** + +Create `internal/recommendation/score_test.go`: + +```go +package recommendation + +import ( + "math" + "math/rand" + "testing" + "time" +) + +func defaultWeights() ScoringWeights { + return ScoringWeights{ + BaseWeight: 1.0, + LikeBoost: 2.0, + RecencyWeight: 1.0, + SkipPenalty: 1.0, + JitterMagnitude: 0.1, + } +} + +func fixedRNG(v float64) func() float64 { + return func() float64 { return v } +} + +func TestScore_BaseCase_NeverPlayed_NoJitter(t *testing.T) { + in := ScoringInputs{} + now := time.Now().UTC() + got := Score(in, defaultWeights(), now, fixedRNG(0.5)) + // rng=0.5 -> jitter contribution = (0.5*2 - 1) * 0.1 = 0 + // expected = 1.0 + 0 (not liked) + 1.0 (never played) - 0 + 0 = 2.0 + want := 2.0 + if math.Abs(got-want) > 1e-9 { + t.Errorf("score = %v, want %v", got, want) + } +} + +func TestScore_LikeBoost(t *testing.T) { + notLiked := Score(ScoringInputs{}, defaultWeights(), time.Now(), fixedRNG(0.5)) + liked := Score(ScoringInputs{IsGeneralLiked: true}, defaultWeights(), time.Now(), fixedRNG(0.5)) + if math.Abs(liked-notLiked-2.0) > 1e-9 { + t.Errorf("delta = %v, want 2.0 (LikeBoost)", liked-notLiked) + } +} + +func TestScore_RecencyRamp_15Days(t *testing.T) { + now := time.Now().UTC() + played := now.Add(-15 * 24 * time.Hour) + got := Score(ScoringInputs{LastPlayedAt: &played}, defaultWeights(), now, fixedRNG(0.5)) + // recency = 0.5 -> contributes 0.5 * 1.0 = 0.5; expected = 1.0 + 0 + 0.5 - 0 + 0 = 1.5 + want := 1.5 + if math.Abs(got-want) > 1e-9 { + t.Errorf("score = %v, want %v", got, want) + } +} + +func TestScore_RecencyRamp_60DaysCapsAt1(t *testing.T) { + now := time.Now().UTC() + played := now.Add(-60 * 24 * time.Hour) + got := Score(ScoringInputs{LastPlayedAt: &played}, defaultWeights(), now, fixedRNG(0.5)) + want := 2.0 // base + capped recency (1.0) + if math.Abs(got-want) > 1e-9 { + t.Errorf("score = %v, want %v", got, want) + } +} + +func TestScore_SkipRatio(t *testing.T) { + // 4 plays, 2 skips -> ratio 0.5 -> -0.5 * SkipPenalty = -0.5 + in := ScoringInputs{PlayCount: 4, SkipCount: 2} + got := Score(in, defaultWeights(), time.Now(), fixedRNG(0.5)) + // recency = 1.0 (never played by virtue of LastPlayedAt being nil even though PlayCount > 0; + // for this test we rely on the recencyDecay treating nil as max). Adjust: the tests above + // explicitly use nil for LastPlayedAt unless set. So: 1.0 + 1.0 - 0.5 = 1.5. + want := 1.5 + if math.Abs(got-want) > 1e-9 { + t.Errorf("score = %v, want %v", got, want) + } +} + +func TestScore_ColdStartSkip_ZeroPlaysZeroSkips(t *testing.T) { + in := ScoringInputs{PlayCount: 0, SkipCount: 0} + got := Score(in, defaultWeights(), time.Now(), fixedRNG(0.5)) + want := 2.0 // base + recency, no skip penalty + if math.Abs(got-want) > 1e-9 { + t.Errorf("score = %v, want %v", got, want) + } +} + +func TestScore_JitterBounds(t *testing.T) { + r := rand.New(rand.NewSource(42)) + w := defaultWeights() + now := time.Now().UTC() + mid := Score(ScoringInputs{}, w, now, fixedRNG(0.5)) // jitter contribution = 0 + for i := 0; i < 1000; i++ { + got := Score(ScoringInputs{}, w, now, r.Float64) + if got < mid-w.JitterMagnitude-1e-9 || got > mid+w.JitterMagnitude+1e-9 { + t.Fatalf("score %v outside jitter band [%v, %v]", + got, mid-w.JitterMagnitude, mid+w.JitterMagnitude) + } + } +} + +func TestScore_Determinism(t *testing.T) { + in := ScoringInputs{IsGeneralLiked: true, PlayCount: 10, SkipCount: 3} + w := defaultWeights() + now := time.Now().UTC() + a := Score(in, w, now, fixedRNG(0.7)) + b := Score(in, w, now, fixedRNG(0.7)) + if a != b { + t.Errorf("non-deterministic with fixed RNG: %v vs %v", a, b) + } +} + +func TestRecencyDecay_NilIsOne(t *testing.T) { + if got := recencyDecay(nil, time.Now()); got != 1.0 { + t.Errorf("recencyDecay(nil) = %v, want 1.0", got) + } +} + +func TestRecencyDecay_Clamping(t *testing.T) { + now := time.Now().UTC() + cases := []struct { + ageDays float64 + want float64 + }{ + {0, 0.0}, + {15, 0.5}, + {30, 1.0}, + {45, 1.0}, + } + for _, c := range cases { + t.Run("", func(t *testing.T) { + past := now.Add(-time.Duration(c.ageDays * 24 * float64(time.Hour))) + got := recencyDecay(&past, now) + if math.Abs(got-c.want) > 1e-9 { + t.Errorf("ageDays=%v decay=%v want %v", c.ageDays, got, c.want) + } + }) + } +} + +func TestSkipRatio_ZeroPlays_IsZero(t *testing.T) { + if got := skipRatio(0, 0); got != 0.0 { + t.Errorf("skipRatio(0,0) = %v, want 0.0", got) + } +} + +func TestSkipRatio_Half(t *testing.T) { + if got := skipRatio(4, 2); got != 0.5 { + t.Errorf("skipRatio(4,2) = %v, want 0.5", got) + } +} +``` + +- [ ] **Step 2: Run tests, confirm fail** + +Run: `go test ./internal/recommendation -v` +Expected: FAIL — package or types undefined. + +- [ ] **Step 3: Implement `internal/recommendation/score.go`** + +```go +// Package recommendation implements the weighted-shuffle scoring engine +// from spec §6. The Score function is pure and takes an injectable RNG so +// tests can pin jitter to deterministic values. +package recommendation + +import ( + "time" +) + +// ScoringInputs are the per-track facts the score function consumes. +// Sub-plan #3 (contextual scoring) extends this with ContextualMatchScore. +type ScoringInputs struct { + IsGeneralLiked bool + LastPlayedAt *time.Time // nil = never played + PlayCount int // total play_events + SkipCount int // play_events with was_skipped=true +} + +// ScoringWeights are the operator-tunable knobs. Defaults live in +// config.RecommendationConfig and are propagated here per request. +type ScoringWeights struct { + BaseWeight float64 + LikeBoost float64 + RecencyWeight float64 + SkipPenalty float64 + JitterMagnitude float64 +} + +// Score computes the weighted-shuffle score per spec §6: +// +// score = base +// + (is_general_liked ? LikeBoost : 0) +// + recency_decay * RecencyWeight +// - skip_ratio * SkipPenalty +// + small_random_jitter +// +// Higher score = more likely to surface. rng is a function returning a +// uniform sample in [0,1) — pass math/rand.Float64 in production, a fixed +// value in tests. +func Score(in ScoringInputs, w ScoringWeights, now time.Time, rng func() float64) float64 { + s := w.BaseWeight + if in.IsGeneralLiked { + s += w.LikeBoost + } + s += recencyDecay(in.LastPlayedAt, now) * w.RecencyWeight + s -= skipRatio(in.PlayCount, in.SkipCount) * w.SkipPenalty + s += (rng()*2 - 1) * w.JitterMagnitude + return s +} + +// recencyDecay returns a value in [0, 1]: +// - never played → 1.0 (cold-start tracks compete favorably with stale ones). +// - age < 30 days → linear ramp age_days / 30. +// - age ≥ 30 days → 1.0 (capped). +// +// Negative ages (clock skew) clamp to 0 to avoid math weirdness. +func recencyDecay(lastPlayed *time.Time, now time.Time) float64 { + if lastPlayed == nil { + return 1.0 + } + age := now.Sub(*lastPlayed) + days := age.Hours() / 24 + if days < 0 { + return 0.0 + } + if days >= 30 { + return 1.0 + } + return days / 30.0 +} + +// skipRatio returns skips/plays in [0, 1]; never-played tracks return 0 +// rather than dividing by zero, so they aren't penalized. +func skipRatio(plays, skips int) float64 { + if plays == 0 { + return 0.0 + } + return float64(skips) / float64(plays) +} +``` + +- [ ] **Step 4: Run tests, confirm pass** + +Run: `go test ./internal/recommendation -v` +Expected: PASS — 11 tests. + +- [ ] **Step 5: Lint** + +Run: `golangci-lint run ./internal/recommendation/...` +Expected: clean. + +- [ ] **Step 6: Commit** + +```bash +git add internal/recommendation/score.go internal/recommendation/score_test.go +git commit -m "feat(recommendation): add pure Score function with recency + skip + jitter + +Implements spec §6 weighted-shuffle scoring without the +contextual_match_score term (sub-plan #3 adds it). Pure Go, no DB +dependency; injectable RNG for deterministic tests. Coverage 100% +on score.go via the boundary tests." +``` + +--- + +## Task 2: Pure shuffle orchestration + +**Files:** +- Create: `internal/recommendation/shuffle.go` +- Create: `internal/recommendation/shuffle_test.go` + +`Shuffle` composes `Score` over a candidate set, sorts descending, truncates to `limit`. Pure. + +- [ ] **Step 1: Write the failing tests** + +Create `internal/recommendation/shuffle_test.go`: + +```go +package recommendation + +import ( + "math/rand" + "testing" + "time" + + "github.com/jackc/pgx/v5/pgtype" + + "git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq" +) + +func cand(id string, in ScoringInputs) Candidate { + t := dbq.Track{Title: id} + _ = t.ID.Scan("00000000-0000-0000-0000-" + id) // 12-char id padded + return Candidate{Track: t, Inputs: in} +} + +func TestShuffle_LikedRanksAboveUnliked(t *testing.T) { + cs := []Candidate{ + cand("000000000001", ScoringInputs{IsGeneralLiked: false}), + cand("000000000002", ScoringInputs{IsGeneralLiked: true}), + } + out := Shuffle(cs, defaultWeights(), time.Now(), fixedRNG(0.5), 10) + if out[0].Track.Title != "000000000002" { + t.Errorf("liked track did not rank first: %+v", out) + } +} + +func TestShuffle_HighSkipRanksLast(t *testing.T) { + cs := []Candidate{ + cand("000000000001", ScoringInputs{PlayCount: 10, SkipCount: 10}), // ratio 1.0 + cand("000000000002", ScoringInputs{PlayCount: 10, SkipCount: 0}), // ratio 0 + cand("000000000003", ScoringInputs{PlayCount: 10, SkipCount: 5}), // ratio 0.5 + } + out := Shuffle(cs, defaultWeights(), time.Now(), fixedRNG(0.5), 10) + if out[0].Track.Title != "000000000002" || out[2].Track.Title != "000000000001" { + t.Errorf("skip-ratio ordering broken: %v", titles(out)) + } +} + +func TestShuffle_LimitTruncates(t *testing.T) { + cs := make([]Candidate, 100) + for i := range cs { + cs[i] = cand("00000000000"+string(rune('a'+i%26)), ScoringInputs{}) + } + out := Shuffle(cs, defaultWeights(), time.Now(), fixedRNG(0.5), 10) + if len(out) != 10 { + t.Errorf("len = %d, want 10", len(out)) + } +} + +func TestShuffle_JitterDoesNotFlipStructuralWinner(t *testing.T) { + // Liked vs unliked: even with many random RNG seeds, liked NEVER ranks below unliked. + r := rand.New(rand.NewSource(42)) + for i := 0; i < 500; i++ { + cs := []Candidate{ + cand("000000000001", ScoringInputs{IsGeneralLiked: false}), + cand("000000000002", ScoringInputs{IsGeneralLiked: true}), + } + out := Shuffle(cs, defaultWeights(), time.Now(), r.Float64, 10) + if out[0].Track.Title != "000000000002" { + t.Fatalf("iter %d: liked did not rank first; out=%v", i, titles(out)) + } + } +} + +func TestShuffle_Empty_ReturnsEmpty(t *testing.T) { + out := Shuffle(nil, defaultWeights(), time.Now(), fixedRNG(0.5), 10) + if len(out) != 0 { + t.Errorf("len = %d, want 0", len(out)) + } +} + +func titles(cs []Candidate) []string { + out := make([]string, 0, len(cs)) + for _, c := range cs { + out = append(out, c.Track.Title) + } + return out +} + +// pgtype-uuid placeholder: Candidate doesn't need a real UUID for these +// pure tests; the Track.Title field is the human-readable handle. Track ID +// is left as zero pgtype.UUID and never compared. +var _ pgtype.UUID +``` + +- [ ] **Step 2: Run, confirm fail** + +Run: `go test ./internal/recommendation -run TestShuffle -v` +Expected: FAIL — `Candidate`, `Shuffle` undefined. + +- [ ] **Step 3: Implement `internal/recommendation/shuffle.go`** + +```go +package recommendation + +import ( + "sort" + "time" + + "git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq" +) + +// Candidate pairs a track with the inputs needed to score it. +type Candidate struct { + Track dbq.Track + Inputs ScoringInputs +} + +// Shuffle scores each candidate, sorts descending by score, and returns +// the top `limit` candidates. limit <= 0 returns nil; nil input returns +// nil. Pure — no IO, no global state beyond the rng callback. +func Shuffle( + candidates []Candidate, + weights ScoringWeights, + now time.Time, + rng func() float64, + limit int, +) []Candidate { + if len(candidates) == 0 || limit <= 0 { + return nil + } + scored := make([]struct { + c Candidate + score float64 + }, len(candidates)) + for i, c := range candidates { + scored[i].c = c + scored[i].score = Score(c.Inputs, weights, now, rng) + } + sort.Slice(scored, func(i, j int) bool { + return scored[i].score > scored[j].score + }) + if limit > len(scored) { + limit = len(scored) + } + out := make([]Candidate, limit) + for i := 0; i < limit; i++ { + out[i] = scored[i].c + } + return out +} +``` + +- [ ] **Step 4: Run, confirm pass** + +Run: `go test ./internal/recommendation -v` +Expected: PASS — 11 score tests + 5 shuffle tests = 16 total. + +- [ ] **Step 5: Commit** + +```bash +git add internal/recommendation/shuffle.go internal/recommendation/shuffle_test.go +git commit -m "feat(recommendation): add Shuffle orchestrator + +Composes Score over a candidate slice, sorts descending, truncates. +Pure — no IO. Liked-rank-higher and high-skip-ranks-last behaviors +are stable across RNG seeds (jitter band is smaller than LikeBoost +and SkipPenalty)." +``` + +--- + +## Task 3: SQL query + sqlc generation + +**Files:** +- Create: `internal/db/queries/recommendation.sql` +- Generated: `internal/db/dbq/recommendation.sql.go` + +One query that returns all eligible tracks with their stats joined. Excludes the seed and recently-played tracks. + +- [ ] **Step 1: Write the query** + +Create `internal/db/queries/recommendation.sql`: + +```sql +-- name: LoadRadioCandidates :many +-- Returns all tracks except the seed and any played by the user within +-- the last $3 hours, joined with the stats needed for scoring: +-- is_liked — boolean from general_likes for this user +-- last_played_at — max(play_events.started_at) for this user/track +-- play_count — count of play_events for this user/track +-- skip_count — play_events where was_skipped=true +SELECT + sqlc.embed(t), + (l.user_id IS NOT NULL) AS is_liked, + pe.last_played_at, + pe.play_count, + pe.skip_count +FROM tracks t +LEFT JOIN general_likes l ON l.user_id = $1 AND l.track_id = t.id +LEFT JOIN LATERAL ( + SELECT + max(started_at) AS last_played_at, + count(*) AS play_count, + count(*) FILTER (WHERE was_skipped) AS skip_count + FROM play_events + WHERE user_id = $1 AND track_id = t.id +) pe ON true +WHERE t.id <> $2 + AND NOT EXISTS ( + SELECT 1 FROM play_events + WHERE user_id = $1 AND track_id = t.id + AND started_at > now() - $3 * interval '1 hour' + ); +``` + +- [ ] **Step 2: Generate sqlc bindings** + +Run: `$(go env GOPATH)/bin/sqlc generate` +Expected: writes `internal/db/dbq/recommendation.sql.go` with `LoadRadioCandidatesParams` (UserID, TrackID for seed, third param for hours) and `LoadRadioCandidatesRow` containing `Track`, `IsLiked`, `LastPlayedAt`, `PlayCount`, `SkipCount`. + +- [ ] **Step 3: Verify build** + +Run: `go build ./...` +Expected: clean. + +- [ ] **Step 4: Commit** + +```bash +git add internal/db/queries/recommendation.sql internal/db/dbq/recommendation.sql.go internal/db/dbq/models.go +git commit -m "feat(db): add LoadRadioCandidates query + +Single SELECT that joins tracks with general_likes (for is_liked) and +an aggregated LATERAL subquery on play_events (for last_played_at, +play_count, skip_count). Excludes seed + tracks played in the last +N hours. Drives the M3 weighted shuffle scoring." +``` + +--- + +## Task 4: Candidate loader + +**Files:** +- Create: `internal/recommendation/candidates.go` +- Create: `internal/recommendation/candidates_test.go` + +Wraps the sqlc query, projects rows to `[]Candidate`. Live-DB tests verify the join + exclusion logic. + +- [ ] **Step 1: Write failing tests** + +Create `internal/recommendation/candidates_test.go`: + +```go +package recommendation + +import ( + "context" + "io" + "log/slog" + "os" + "testing" + "time" + + "github.com/jackc/pgx/v5/pgtype" + "github.com/jackc/pgx/v5/pgxpool" + + "git.fabledsword.com/bvandeusen/minstrel/internal/db" + "git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq" +) + +func testPool(t *testing.T) *pgxpool.Pool { + t.Helper() + if testing.Short() { + t.Skip("skipping integration test in -short mode") + } + dsn := os.Getenv("MINSTREL_TEST_DATABASE_URL") + if dsn == "" { + t.Skip("MINSTREL_TEST_DATABASE_URL not set") + } + if err := db.Migrate(dsn, slog.New(slog.NewTextHandler(io.Discard, nil))); err != nil { + t.Fatalf("migrate: %v", err) + } + pool, err := pgxpool.New(context.Background(), dsn) + if err != nil { + t.Fatalf("pool: %v", err) + } + t.Cleanup(pool.Close) + if _, err := pool.Exec(context.Background(), + "TRUNCATE general_likes, general_likes_albums, general_likes_artists, play_events, skip_events, play_sessions, sessions, users, tracks, albums, artists RESTART IDENTITY CASCADE"); err != nil { + t.Fatalf("truncate: %v", err) + } + return pool +} + +type fixture struct { + pool *pgxpool.Pool + q *dbq.Queries + user pgtype.UUID + tracks []dbq.Track // tracks[0] is the canonical seed +} + +func newFixture(t *testing.T, n int) fixture { + t.Helper() + pool := testPool(t) + q := dbq.New(pool) + u, err := q.CreateUser(context.Background(), dbq.CreateUserParams{ + Username: "tester", PasswordHash: "x", ApiToken: "x", IsAdmin: false, + }) + if err != nil { + t.Fatalf("user: %v", err) + } + a, _ := q.UpsertArtist(context.Background(), dbq.UpsertArtistParams{Name: "A", SortName: "A"}) + al, _ := q.UpsertAlbum(context.Background(), dbq.UpsertAlbumParams{Title: "B", SortTitle: "B", ArtistID: a.ID}) + tracks := make([]dbq.Track, 0, n) + for i := 0; i < n; i++ { + tr, err := q.UpsertTrack(context.Background(), dbq.UpsertTrackParams{ + Title: string(rune('A' + i)), + AlbumID: al.ID, + ArtistID: a.ID, + FilePath: "/tmp/track-" + string(rune('A'+i)) + ".flac", + DurationMs: 120_000, + }) + if err != nil { + t.Fatalf("track[%d]: %v", i, err) + } + tracks = append(tracks, tr) + } + return fixture{pool: pool, q: q, user: u.ID, tracks: tracks} +} + +func TestLoadCandidates_ExcludesSeed(t *testing.T) { + f := newFixture(t, 5) + got, err := LoadCandidates(context.Background(), f.q, f.user, f.tracks[0].ID, 1) + if err != nil { + t.Fatalf("LoadCandidates: %v", err) + } + if len(got) != 4 { + t.Fatalf("len = %d, want 4 (5 minus seed)", len(got)) + } + for _, c := range got { + if c.Track.ID == f.tracks[0].ID { + t.Errorf("seed appeared in candidate set") + } + } +} + +func TestLoadCandidates_ExcludesRecentlyPlayed(t *testing.T) { + f := newFixture(t, 3) + // Seed = tracks[0]. Other tracks are tracks[1], tracks[2]. + // Insert a play_session and a play_event for tracks[1] 30 minutes ago. + now := time.Now().UTC() + thirtyMinAgo := now.Add(-30 * time.Minute) + sess, _ := f.q.InsertPlaySession(context.Background(), dbq.InsertPlaySessionParams{ + UserID: f.user, + StartedAt: pgtype.Timestamptz{Time: thirtyMinAgo, Valid: true}, + ClientID: nil, + }) + _, _ = f.q.InsertPlayEvent(context.Background(), dbq.InsertPlayEventParams{ + UserID: f.user, + TrackID: f.tracks[1].ID, + SessionID: sess.ID, + StartedAt: pgtype.Timestamptz{Time: thirtyMinAgo, Valid: true}, + ClientID: nil, + }) + + got, err := LoadCandidates(context.Background(), f.q, f.user, f.tracks[0].ID, 1) + if err != nil { + t.Fatalf("LoadCandidates: %v", err) + } + // Expect tracks[2] only (seed excluded, tracks[1] excluded by recently-played). + if len(got) != 1 { + t.Fatalf("len = %d, want 1; got=%v", len(got), trackTitles(got)) + } + if got[0].Track.ID != f.tracks[2].ID { + t.Errorf("expected tracks[2], got %v", got[0].Track.Title) + } +} + +func TestLoadCandidates_StatJoin(t *testing.T) { + f := newFixture(t, 2) + // Seed = tracks[0]. Like tracks[1]; play it twice (one skip, one full play) 2 hours ago. + if err := f.q.LikeTrack(context.Background(), dbq.LikeTrackParams{UserID: f.user, TrackID: f.tracks[1].ID}); err != nil { + t.Fatalf("like: %v", err) + } + twoH := time.Now().UTC().Add(-2 * time.Hour) + sess, _ := f.q.InsertPlaySession(context.Background(), dbq.InsertPlaySessionParams{ + UserID: f.user, StartedAt: pgtype.Timestamptz{Time: twoH, Valid: true}, + }) + // First play: completed (was_skipped=false). + pe1, _ := f.q.InsertPlayEvent(context.Background(), dbq.InsertPlayEventParams{ + UserID: f.user, TrackID: f.tracks[1].ID, SessionID: sess.ID, + StartedAt: pgtype.Timestamptz{Time: twoH, Valid: true}, + }) + dur := int32(120_000) + ratio := 1.0 + _, _ = f.q.UpdatePlayEventEnded(context.Background(), dbq.UpdatePlayEventEndedParams{ + ID: pe1.ID, EndedAt: pgtype.Timestamptz{Time: twoH.Add(2 * time.Minute), Valid: true}, + DurationPlayedMs: &dur, CompletionRatio: &ratio, WasSkipped: false, + }) + // Second play: skipped (was_skipped=true). + pe2, _ := f.q.InsertPlayEvent(context.Background(), dbq.InsertPlayEventParams{ + UserID: f.user, TrackID: f.tracks[1].ID, SessionID: sess.ID, + StartedAt: pgtype.Timestamptz{Time: twoH.Add(5 * time.Minute), Valid: true}, + }) + dur2 := int32(5_000) + ratio2 := 0.04 + _, _ = f.q.UpdatePlayEventEnded(context.Background(), dbq.UpdatePlayEventEndedParams{ + ID: pe2.ID, EndedAt: pgtype.Timestamptz{Time: twoH.Add(5*time.Minute + 5*time.Second), Valid: true}, + DurationPlayedMs: &dur2, CompletionRatio: &ratio2, WasSkipped: true, + }) + + got, err := LoadCandidates(context.Background(), f.q, f.user, f.tracks[0].ID, 1) + if err != nil { + t.Fatalf("LoadCandidates: %v", err) + } + if len(got) != 1 { + t.Fatalf("len = %d, want 1", len(got)) + } + c := got[0] + if !c.Inputs.IsGeneralLiked { + t.Errorf("IsGeneralLiked = false, want true") + } + if c.Inputs.PlayCount != 2 { + t.Errorf("PlayCount = %d, want 2", c.Inputs.PlayCount) + } + if c.Inputs.SkipCount != 1 { + t.Errorf("SkipCount = %d, want 1", c.Inputs.SkipCount) + } + if c.Inputs.LastPlayedAt == nil { + t.Errorf("LastPlayedAt = nil, want non-nil") + } +} + +func TestLoadCandidates_NeverPlayedHasNilLastPlayed(t *testing.T) { + f := newFixture(t, 2) + got, err := LoadCandidates(context.Background(), f.q, f.user, f.tracks[0].ID, 1) + if err != nil { + t.Fatalf("LoadCandidates: %v", err) + } + if len(got) != 1 { + t.Fatalf("len = %d, want 1", len(got)) + } + if got[0].Inputs.LastPlayedAt != nil { + t.Errorf("never-played track has non-nil LastPlayedAt: %v", got[0].Inputs.LastPlayedAt) + } + if got[0].Inputs.PlayCount != 0 || got[0].Inputs.SkipCount != 0 { + t.Errorf("never-played track has non-zero counts: %+v", got[0].Inputs) + } +} + +func TestLoadCandidates_CrossUserIsolation(t *testing.T) { + f := newFixture(t, 2) + bob, _ := f.q.CreateUser(context.Background(), dbq.CreateUserParams{ + Username: "bob", PasswordHash: "x", ApiToken: "y", IsAdmin: false, + }) + // Alice likes tracks[1]; Bob shouldn't see it. + _ = f.q.LikeTrack(context.Background(), dbq.LikeTrackParams{UserID: f.user, TrackID: f.tracks[1].ID}) + + got, err := LoadCandidates(context.Background(), f.q, bob.ID, f.tracks[0].ID, 1) + if err != nil { + t.Fatalf("LoadCandidates: %v", err) + } + for _, c := range got { + if c.Track.ID == f.tracks[1].ID && c.Inputs.IsGeneralLiked { + t.Errorf("bob sees alice's like on track %v", c.Track.Title) + } + } +} + +func trackTitles(cs []Candidate) []string { + out := make([]string, 0, len(cs)) + for _, c := range cs { + out = append(out, c.Track.Title) + } + return out +} +``` + +- [ ] **Step 2: Run, confirm fail** + +Run: +```bash +MINSTREL_TEST_DATABASE_URL='postgres://minstrel:minstrel@172.22.0.2:5432/minstrel?sslmode=disable' \ + go test ./internal/recommendation -run TestLoadCandidates -v +``` +Expected: FAIL — `LoadCandidates` undefined. + +- [ ] **Step 3: Implement `internal/recommendation/candidates.go`** + +```go +package recommendation + +import ( + "context" + + "github.com/jackc/pgx/v5/pgtype" + + "git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq" +) + +// LoadCandidates returns all candidate tracks for the given user, excluding +// the seed and any track played within the last `recentlyPlayedHours`. +// Each Candidate includes the per-(user,track) stats the scoring function +// needs. +func LoadCandidates( + ctx context.Context, + q *dbq.Queries, + userID, seedID pgtype.UUID, + recentlyPlayedHours int, +) ([]Candidate, error) { + rows, err := q.LoadRadioCandidates(ctx, dbq.LoadRadioCandidatesParams{ + UserID: userID, + ID: seedID, + Column3: float64(recentlyPlayedHours), + }) + if err != nil { + return nil, err + } + out := make([]Candidate, 0, len(rows)) + for _, r := range rows { + var lastPlayed *pgtype.Timestamptz + if r.LastPlayedAt.Valid { + ts := r.LastPlayedAt + lastPlayed = &ts + } + var lastPlayedTime *([]byte) // placeholder to satisfy structure if needed + _ = lastPlayedTime // appease unused warning + var lpt *time.Time + if r.LastPlayedAt.Valid { + t := r.LastPlayedAt.Time + lpt = &t + } + out = append(out, Candidate{ + Track: r.Track, + Inputs: ScoringInputs{ + IsGeneralLiked: r.IsLiked, + LastPlayedAt: lpt, + PlayCount: int(r.PlayCount), + SkipCount: int(r.SkipCount), + }, + }) + _ = lastPlayed + } + return out, nil +} +``` + +Note: clean up the duplicated `lastPlayed` / `lastPlayedTime` shims — they're scaffolding from drafting. Final form: + +```go +package recommendation + +import ( + "context" + "time" + + "github.com/jackc/pgx/v5/pgtype" + + "git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq" +) + +func LoadCandidates( + ctx context.Context, + q *dbq.Queries, + userID, seedID pgtype.UUID, + recentlyPlayedHours int, +) ([]Candidate, error) { + rows, err := q.LoadRadioCandidates(ctx, dbq.LoadRadioCandidatesParams{ + UserID: userID, + ID: seedID, + Column3: float64(recentlyPlayedHours), + }) + if err != nil { + return nil, err + } + out := make([]Candidate, 0, len(rows)) + for _, r := range rows { + var lpt *time.Time + if r.LastPlayedAt.Valid { + t := r.LastPlayedAt.Time + lpt = &t + } + out = append(out, Candidate{ + Track: r.Track, + Inputs: ScoringInputs{ + IsGeneralLiked: r.IsLiked, + LastPlayedAt: lpt, + PlayCount: int(r.PlayCount), + SkipCount: int(r.SkipCount), + }, + }) + } + return out, nil +} +``` + +Note on the sqlc-generated `Column3` field name: sqlc names unnamed parameters `Column1`, `Column2`, etc. when there's no obvious mapping. If the generated field has a different name (e.g. `Hours`), adjust the call site to match. Run sqlc generate first and inspect `internal/db/dbq/recommendation.sql.go` to confirm. + +- [ ] **Step 4: Run, confirm pass** + +Run: +```bash +MINSTREL_TEST_DATABASE_URL='postgres://minstrel:minstrel@172.22.0.2:5432/minstrel?sslmode=disable' \ + go test ./internal/recommendation -v +``` +Expected: PASS — 16 prior tests + 5 new candidate tests = 21 total. + +- [ ] **Step 5: Lint** + +Run: `golangci-lint run ./internal/recommendation/...` +Expected: clean. + +- [ ] **Step 6: Commit** + +```bash +git add internal/recommendation/candidates.go internal/recommendation/candidates_test.go +git commit -m "feat(recommendation): add LoadCandidates DB-backed loader + +Wraps the LoadRadioCandidates sqlc query, projects rows to +[]Candidate. Live-DB tests verify seed exclusion, recently-played +exclusion, stat-join correctness (likes + plays + skips + +last_played_at), and cross-user isolation." +``` + +--- + +## Task 5: RecommendationConfig + +**Files:** +- Modify: `internal/config/config.go` +- Modify: `config.example.yaml` + +Adds operator-tunable weights to YAML / env. Defaults match the spec. + +- [ ] **Step 1: Add the struct + field + defaults** + +In `internal/config/config.go`, add `Recommendation RecommendationConfig` to the `Config` struct (alongside `Events`): + +```go +type Config struct { + Server ServerConfig `yaml:"server"` + Database DatabaseConfig `yaml:"database"` + Log LogConfig `yaml:"log"` + Auth AuthConfig `yaml:"auth"` + Library LibraryConfig `yaml:"library"` + Subsonic SubsonicConfig `yaml:"subsonic"` + Events EventsConfig `yaml:"events"` + Recommendation RecommendationConfig `yaml:"recommendation"` +} +``` + +Add the struct definition (after `EventsConfig`): + +```go +// RecommendationConfig governs the M3 weighted-shuffle scoring (spec §6). +// All weights are operator-tunable; defaults match the spec recommendations. +type RecommendationConfig struct { + BaseWeight float64 `yaml:"base_weight"` + LikeBoost float64 `yaml:"like_boost"` + RecencyWeight float64 `yaml:"recency_weight"` + SkipPenalty float64 `yaml:"skip_penalty"` + JitterMagnitude float64 `yaml:"jitter_magnitude"` + RecentlyPlayedHours int `yaml:"recently_played_hours"` + RadioSize int `yaml:"radio_size"` + RadioSizeMax int `yaml:"radio_size_max"` +} +``` + +Update `Default()` to seed the defaults: + +```go +func Default() Config { + return Config{ + Server: ServerConfig{Address: ":4533"}, + Database: DatabaseConfig{URL: ""}, + Log: LogConfig{Level: "info", Format: "text"}, + Events: EventsConfig{ + SessionTimeoutMinutes: 30, + SkipMaxCompletionRatio: 0.5, + SkipMaxDurationPlayedMs: 30000, + }, + Recommendation: RecommendationConfig{ + BaseWeight: 1.0, + LikeBoost: 2.0, + RecencyWeight: 1.0, + SkipPenalty: 1.0, + JitterMagnitude: 0.1, + RecentlyPlayedHours: 1, + RadioSize: 50, + RadioSizeMax: 200, + }, + } +} +``` + +- [ ] **Step 2: Update `config.example.yaml`** + +Append after the `events:` section: + +```yaml + +recommendation: + # Base score every candidate gets before adjustments. Spec §6. + base_weight: 1.0 + # Bonus for tracks the user has liked (general_likes). + like_boost: 2.0 + # Multiplier on recency_decay (1.0 for tracks ≥ 30 days stale, 0 for fresh). + recency_weight: 1.0 + # Penalty multiplier on skip_ratio (skips/plays); 1.0 = full penalty. + skip_penalty: 1.0 + # ± random jitter applied to every candidate; breaks ties without dominating. + jitter_magnitude: 0.1 + # Hard-suppression window: tracks played within this many hours never appear. + recently_played_hours: 1 + # Default radio size when ?limit= is not specified. + radio_size: 50 + # Maximum allowed ?limit= (server caps to this regardless). + radio_size_max: 200 +``` + +- [ ] **Step 3: Run config tests** + +Run: `go test ./internal/config -v` +Expected: PASS — existing tests still pass with the new struct defaulting correctly. + +- [ ] **Step 4: Commit** + +```bash +git add internal/config/config.go config.example.yaml +git commit -m "feat(config): add recommendation section (weighted shuffle weights) + +BaseWeight, LikeBoost, RecencyWeight, SkipPenalty, JitterMagnitude, +RecentlyPlayedHours, RadioSize, RadioSizeMax. Defaults match spec §6." +``` + +--- + +## Task 6: Radio handler rewrite + +**Files:** +- Modify: `internal/api/radio.go` (replaces stub) +- Modify: `internal/api/radio_test.go` (replaces stub tests) +- Modify: `internal/api/api.go` (Mount signature gains config arg; handlers struct gains recCfg field) +- Modify: `internal/api/auth_test.go` (testHandlers seeds a default RecommendationConfig) +- Modify: `internal/api/library_test.go` (newLibraryRouter doesn't need radio routing changes; no-op verification) +- Modify: `internal/server/server.go` + `cmd/minstrel/main.go` (pass cfg through) + +Replaces the stub with the v1 weighted-shuffle implementation. + +- [ ] **Step 1: Update `handlers` struct + Mount in `internal/api/api.go`** + +```go +package api + +import ( + "log/slog" + "math/rand" + + "github.com/go-chi/chi/v5" + "github.com/jackc/pgx/v5/pgxpool" + + "git.fabledsword.com/bvandeusen/minstrel/internal/auth" + "git.fabledsword.com/bvandeusen/minstrel/internal/config" + "git.fabledsword.com/bvandeusen/minstrel/internal/playevents" +) + +func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playevents.Writer, recCfg config.RecommendationConfig) { + h := &handlers{ + pool: pool, + logger: logger, + events: events, + recCfg: recCfg, + // Seeded once at server start; per-request shuffle reads h.rng.Float64. + // Concurrent calls are fine — math/rand.Rand is safe under contention via + // a mutex internally (Go 1.21+); for stricter isolation switch to math/rand/v2. + } + rng := rand.New(rand.NewSource(rand.Int63())) + h.rng = rng.Float64 + + // ... existing route registrations unchanged ... + r.Route("/api", func(api chi.Router) { + api.Post("/auth/login", h.handleLogin) + api.Group(func(authed chi.Router) { + authed.Use(auth.RequireUser(pool)) + authed.Post("/auth/logout", h.handleLogout) + authed.Get("/me", h.handleGetMe) + + authed.Get("/artists", h.handleListArtists) + authed.Get("/artists/{id}", h.handleGetArtist) + authed.Get("/albums/{id}", h.handleGetAlbum) + authed.Get("/albums/{id}/cover", h.handleGetCover) + authed.Get("/tracks/{id}", h.handleGetTrack) + authed.Get("/tracks/{id}/stream", h.handleGetStream) + authed.Get("/search", h.handleSearch) + authed.Get("/radio", h.handleRadio) + authed.Post("/events", h.handleEvents) + authed.Post("/likes/tracks/{id}", h.handleLikeTrack) + authed.Delete("/likes/tracks/{id}", h.handleUnlikeTrack) + authed.Post("/likes/albums/{id}", h.handleLikeAlbum) + authed.Delete("/likes/albums/{id}", h.handleUnlikeAlbum) + authed.Post("/likes/artists/{id}", h.handleLikeArtist) + authed.Delete("/likes/artists/{id}", h.handleUnlikeArtist) + authed.Get("/likes/tracks", h.handleListLikedTracks) + authed.Get("/likes/albums", h.handleListLikedAlbums) + authed.Get("/likes/artists", h.handleListLikedArtists) + authed.Get("/likes/ids", h.handleGetLikedIDs) + }) + }) +} + +type handlers struct { + pool *pgxpool.Pool + logger *slog.Logger + events *playevents.Writer + recCfg config.RecommendationConfig + rng func() float64 +} +``` + +(Note: `math/rand`'s top-level `Float64` is goroutine-safe, but the new-instance pattern with explicit seed is cleaner. Stay with `func() float64` so tests can inject deterministic values.) + +- [ ] **Step 2: Replace `internal/api/radio.go`** + +```go +package api + +import ( + "errors" + "net/http" + "strconv" + "strings" + "time" + + "github.com/jackc/pgx/v5" + + "git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq" + "git.fabledsword.com/bvandeusen/minstrel/internal/recommendation" +) + +// RadioResponse is the body of GET /api/radio. +type RadioResponse struct { + Tracks []TrackRef `json:"tracks"` +} + +// handleRadio implements GET /api/radio?seed_track=&limit=. +// +// Returns the seed at index 0, followed by up to limit-1 weighted-shuffle +// picks from the user's library, scored by recommendation.Score. +func (h *handlers) handleRadio(w http.ResponseWriter, r *http.Request) { + user, ok := authUserFromContext(r) + if !ok { + writeErr(w, http.StatusUnauthorized, "unauthorized", "authentication required") + return + } + raw := strings.TrimSpace(r.URL.Query().Get("seed_track")) + if raw == "" { + writeErr(w, http.StatusBadRequest, "bad_request", "seed_track is required") + return + } + seedID, ok := parseUUID(raw) + if !ok { + writeErr(w, http.StatusBadRequest, "bad_request", "invalid seed_track id") + return + } + limit := h.recCfg.RadioSize + if v := r.URL.Query().Get("limit"); v != "" { + n, err := strconv.Atoi(v) + if err != nil || n < 1 { + writeErr(w, http.StatusBadRequest, "bad_request", "invalid limit") + return + } + limit = n + } + if limit > h.recCfg.RadioSizeMax { + limit = h.recCfg.RadioSizeMax + } + q := dbq.New(h.pool) + track, err := q.GetTrackByID(r.Context(), seedID) + if err != nil { + if errors.Is(err, pgx.ErrNoRows) { + writeErr(w, http.StatusNotFound, "not_found", "seed_track not found") + return + } + h.logger.Error("api: get radio seed track failed", "err", err) + writeErr(w, http.StatusInternalServerError, "server_error", "lookup failed") + return + } + album, err := q.GetAlbumByID(r.Context(), track.AlbumID) + if err != nil { + h.logger.Error("api: get radio seed album failed", "err", err) + writeErr(w, http.StatusInternalServerError, "server_error", "lookup failed") + return + } + artist, err := q.GetArtistByID(r.Context(), track.ArtistID) + if err != nil { + h.logger.Error("api: get radio seed artist failed", "err", err) + writeErr(w, http.StatusInternalServerError, "server_error", "lookup failed") + return + } + candidates, err := recommendation.LoadCandidates(r.Context(), q, user.ID, seedID, h.recCfg.RecentlyPlayedHours) + if err != nil { + h.logger.Error("api: radio: load candidates", "err", err) + writeErr(w, http.StatusInternalServerError, "server_error", "candidate load failed") + return + } + weights := recommendation.ScoringWeights{ + BaseWeight: h.recCfg.BaseWeight, + LikeBoost: h.recCfg.LikeBoost, + RecencyWeight: h.recCfg.RecencyWeight, + SkipPenalty: h.recCfg.SkipPenalty, + JitterMagnitude: h.recCfg.JitterMagnitude, + } + picks := recommendation.Shuffle(candidates, weights, time.Now().UTC(), h.rng, limit-1) + + out := make([]TrackRef, 0, len(picks)+1) + out = append(out, trackRefFrom(track, album.Title, artist.Name)) + for _, p := range picks { + // Resolve album/artist names per pick. Reuse the existing resolver. + al, err := q.GetAlbumByID(r.Context(), p.Track.AlbumID) + if err != nil { + h.logger.Error("api: radio: resolve album", "err", err) + writeErr(w, http.StatusInternalServerError, "server_error", "resolve failed") + return + } + ar, err := q.GetArtistByID(r.Context(), p.Track.ArtistID) + if err != nil { + h.logger.Error("api: radio: resolve artist", "err", err) + writeErr(w, http.StatusInternalServerError, "server_error", "resolve failed") + return + } + out = append(out, trackRefFrom(p.Track, al.Title, ar.Name)) + } + writeJSON(w, http.StatusOK, RadioResponse{Tracks: out}) +} + +// authUserFromContext is a thin shim around auth.UserFromContext that tests +// can override. It exists so testHandlers can inject a user via the same +// context key RequireUser populates. +func authUserFromContext(r *http.Request) (dbq.User, bool) { + return userFromContext(r) +} +``` + +`userFromContext` is the existing helper used by the events handler — reuse it; if it's named differently in your tree, follow that pattern. The shim layer (`authUserFromContext`) is unnecessary if the existing handler pattern just calls `auth.UserFromContext(r.Context())` directly. Use whatever the rest of the package uses; consistency over novelty. + +- [ ] **Step 3: Update `testHandlers` in `internal/api/auth_test.go`** + +Find the existing `testHandlers` function. Update the construction: + +```go +import ( + // ... existing imports ... + "git.fabledsword.com/bvandeusen/minstrel/internal/config" +) + +func testHandlers(t *testing.T) (*handlers, *pgxpool.Pool) { + // ... existing setup unchanged up to the return ... + w := playevents.NewWriter(pool, logger, 30*time.Minute, 0.5, 30000) + recCfg := config.RecommendationConfig{ + BaseWeight: 1.0, LikeBoost: 2.0, RecencyWeight: 1.0, + SkipPenalty: 1.0, JitterMagnitude: 0.1, + RecentlyPlayedHours: 1, RadioSize: 50, RadioSizeMax: 200, + } + h := &handlers{pool: pool, logger: logger, events: w, recCfg: recCfg, rng: func() float64 { return 0.5 }} + return h, pool +} +``` + +The fixed-RNG (`return 0.5`) makes tests deterministic — jitter contribution is always 0. + +- [ ] **Step 4: Replace `internal/api/radio_test.go`** + +Replace the existing 5 stub tests with new ones: + +```go +package api + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "testing" +) + +func callRadio(h *handlers, user interface{}, query string) *httptest.ResponseRecorder { + req := httptest.NewRequest(http.MethodGet, "/api/radio?"+query, nil) + req = req.WithContext(context.WithValue(req.Context(), userCtxKeyForTest(), user)) + w := httptest.NewRecorder() + h.handleRadio(w, req) + return w +} + +func TestHandleRadio_ColdStart_OnlySeedReturned(t *testing.T) { + h, pool := testHandlers(t) + truncateLibrary(t, pool) + user := seedUser(t, pool, "alice", "x", false) + artist := seedArtist(t, pool, "X") + album := seedAlbum(t, pool, artist.ID, "X", 1990) + seed := seedTrack(t, pool, album.ID, artist.ID, "Seed", 1, 100_000) + + w := callRadio(h, user, "seed_track="+uuidToString(seed.ID)) + if w.Code != http.StatusOK { + t.Fatalf("status = %d body=%s", w.Code, w.Body.String()) + } + var resp RadioResponse + _ = json.Unmarshal(w.Body.Bytes(), &resp) + if len(resp.Tracks) != 1 { + t.Fatalf("len = %d, want 1", len(resp.Tracks)) + } + if resp.Tracks[0].Title != "Seed" { + t.Errorf("seed not first: %v", resp.Tracks[0].Title) + } +} + +func TestHandleRadio_Typical_SeedFirstPlusPicks(t *testing.T) { + h, pool := testHandlers(t) + truncateLibrary(t, pool) + user := seedUser(t, pool, "alice", "x", false) + artist := seedArtist(t, pool, "X") + album := seedAlbum(t, pool, artist.ID, "X", 1990) + seed := seedTrack(t, pool, album.ID, artist.ID, "Seed", 1, 100_000) + for i := 2; i <= 6; i++ { + seedTrack(t, pool, album.ID, artist.ID, "T"+string(rune('0'+i)), i, 100_000) + } + + w := callRadio(h, user, "seed_track="+uuidToString(seed.ID)) + if w.Code != http.StatusOK { + t.Fatalf("status = %d", w.Code) + } + var resp RadioResponse + _ = json.Unmarshal(w.Body.Bytes(), &resp) + if len(resp.Tracks) != 6 { + t.Fatalf("len = %d, want 6 (seed + 5 picks)", len(resp.Tracks)) + } + if resp.Tracks[0].Title != "Seed" { + t.Errorf("seed not at index 0: %v", resp.Tracks[0].Title) + } +} + +func TestHandleRadio_UnknownSeedIs404(t *testing.T) { + h, pool := testHandlers(t) + user := seedUser(t, pool, "alice", "x", false) + w := callRadio(h, user, "seed_track=00000000-0000-0000-0000-000000000000") + if w.Code != http.StatusNotFound { + t.Errorf("status = %d", w.Code) + } +} + +func TestHandleRadio_BadSeedIs400(t *testing.T) { + h, pool := testHandlers(t) + user := seedUser(t, pool, "alice", "x", false) + w := callRadio(h, user, "seed_track=not-a-uuid") + if w.Code != http.StatusBadRequest { + t.Errorf("status = %d", w.Code) + } +} + +func TestHandleRadio_MissingSeedIs400(t *testing.T) { + h, pool := testHandlers(t) + user := seedUser(t, pool, "alice", "x", false) + w := callRadio(h, user, "") + if w.Code != http.StatusBadRequest { + t.Errorf("status = %d", w.Code) + } +} + +func TestHandleRadio_BadLimitIs400(t *testing.T) { + h, pool := testHandlers(t) + truncateLibrary(t, pool) + user := seedUser(t, pool, "alice", "x", false) + artist := seedArtist(t, pool, "X") + album := seedAlbum(t, pool, artist.ID, "X", 1990) + seed := seedTrack(t, pool, album.ID, artist.ID, "Seed", 1, 100_000) + w := callRadio(h, user, "seed_track="+uuidToString(seed.ID)+"&limit=0") + if w.Code != http.StatusBadRequest { + t.Errorf("limit=0 status = %d", w.Code) + } + w = callRadio(h, user, "seed_track="+uuidToString(seed.ID)+"&limit=-1") + if w.Code != http.StatusBadRequest { + t.Errorf("limit=-1 status = %d", w.Code) + } +} + +func TestHandleRadio_LimitClampedToMax(t *testing.T) { + h, pool := testHandlers(t) + truncateLibrary(t, pool) + user := seedUser(t, pool, "alice", "x", false) + artist := seedArtist(t, pool, "X") + album := seedAlbum(t, pool, artist.ID, "X", 1990) + seed := seedTrack(t, pool, album.ID, artist.ID, "Seed", 1, 100_000) + for i := 2; i <= 6; i++ { + seedTrack(t, pool, album.ID, artist.ID, "T"+string(rune('0'+i)), i, 100_000) + } + w := callRadio(h, user, "seed_track="+uuidToString(seed.ID)+"&limit=99999") + if w.Code != http.StatusOK { + t.Fatalf("status = %d", w.Code) + } + var resp RadioResponse + _ = json.Unmarshal(w.Body.Bytes(), &resp) + // We only have 6 tracks; clamped limit (max 200) returns all 6. + if len(resp.Tracks) != 6 { + t.Errorf("len = %d, want 6", len(resp.Tracks)) + } +} +``` + +- [ ] **Step 5: Update Mount call sites** + +In `internal/server/server.go`: + +```go +api.Mount(r, s.Pool, s.Logger, writer, s.RecommendationCfg) +``` + +The `Server` struct gains `RecommendationCfg config.RecommendationConfig`; constructor `New(...)` gains the new arg. Find `cmd/minstrel/main.go`'s `server.New(...)` call and pass `cfg.Recommendation`. + +In `internal/api/library_test.go`'s `TestRoutesRegisteredInMount`: + +```go +Mount(r, h.pool, h.logger, w, config.RecommendationConfig{ + RadioSize: 50, RadioSizeMax: 200, RecentlyPlayedHours: 1, +}) +``` + +In `internal/server/server_test.go`'s `New(...)` calls (multiple sites), append `config.RecommendationConfig{}` after the `subsonic.Config{}` arg. Use the existing `replace_all` approach if there are several: + +```go +New(slog.New(slog.NewTextHandler(io.Discard, nil)), nil, nil, subsonic.Config{}, config.EventsConfig{}, config.RecommendationConfig{}) +``` + +- [ ] **Step 6: Run tests, confirm pass** + +Run: +```bash +MINSTREL_TEST_DATABASE_URL='postgres://minstrel:minstrel@172.22.0.2:5432/minstrel?sslmode=disable' \ + go test -p 1 ./... +``` +Expected: all packages PASS. + +Run: `golangci-lint run ./...` +Expected: clean. + +- [ ] **Step 7: Commit** + +```bash +git add internal/api/radio.go internal/api/radio_test.go internal/api/api.go \ + internal/api/auth_test.go internal/api/library_test.go \ + internal/server/server.go internal/server/server_test.go \ + cmd/minstrel/main.go +git commit -m "feat(api): rewrite /api/radio with weighted shuffle v1 + +Validates seed_track + optional limit (default cfg.Recommendation.RadioSize, +clamped to RadioSizeMax). Calls recommendation.LoadCandidates + +recommendation.Shuffle. Prepends seed to result. Server seeds a +math/rand source at startup; handlers package threads that as a +func() float64 so tests inject deterministic RNGs. + +Mount + server.New gain a RecommendationConfig parameter." +``` + +--- + +## Task 7: Final verification + branch finish + +**Files:** none (verification only). + +- [ ] **Step 1: Full Go suite** + +Run: +```bash +MINSTREL_TEST_DATABASE_URL='postgres://minstrel:minstrel@172.22.0.2:5432/minstrel?sslmode=disable' \ + go test -p 1 ./... +``` +Expected: all packages PASS. + +- [ ] **Step 2: Coverage on recommendation package** + +Run: +```bash +MINSTREL_TEST_DATABASE_URL='postgres://minstrel:minstrel@172.22.0.2:5432/minstrel?sslmode=disable' \ + go test -coverprofile=/tmp/rec.cover ./internal/recommendation/... +go tool cover -func=/tmp/rec.cover | tail -3 +``` +Expected: total coverage ≥ 70%. + +- [ ] **Step 3: Lint** + +Run: `golangci-lint run ./...` +Expected: clean. + +- [ ] **Step 4: Web check + tests + build** + +Run: `cd web && npm run check && npm test && npm run build` +Expected: check 0/0; tests pass; build emits `web/build/`. + +Run: `git checkout -- web/build/index.html` +Expected: committed placeholder restored. + +- [ ] **Step 5: Docker build smoke** + +Run: `docker build -t minstrel:m3-shuffle-smoke .` +Expected: image builds. + +Run: `docker run --rm --entrypoint /bin/sh minstrel:m3-shuffle-smoke -c 'test -x /usr/local/bin/minstrel && echo ok'` +Expected: `ok`. + +- [ ] **Step 6: Local end-to-end manual check** + +```bash +docker compose up --build -d +``` + +Browser at `localhost:4533` (sign in with the dev admin creds): + +1. Play 3 tracks all the way through (build `play_count` history). +2. Skip a 4th track within 10 seconds (`skip_count = 1` for that track). +3. Like 2 tracks via the heart button. +4. Click the radio button on a 5th track (or trigger via search → click track). +5. Inspect the response in dev tools network tab — 50 tracks, seed first. +6. The 2 liked tracks appear early in the list (within first ~20). +7. The just-skipped track appears late or absent. +8. The 3 just-played tracks are absent (recently-played exclusion). +9. Trigger radio again with a different seed; ordering varies (jitter), liked tracks still rank prominently. + +Tear down: +```bash +docker compose down +``` + +- [ ] **Step 7: Finish the branch** + +Follow `superpowers:finishing-a-development-branch`. Expected path: Option 2 — push `dev`, open a PR to `main`, wait for Forgejo CI, merge once green. + +--- + +## Self-Review Notes + +**Spec coverage:** +- Pure scoring function with all 5 terms (base, like boost, recency, skip penalty, jitter) → Task 1. +- Shuffle composition (sort + truncate) → Task 2. +- Candidate loader excluding seed + recently-played → Tasks 3–4. +- Stat join (is_liked + last_played_at + play_count + skip_count) → Tasks 3–4. +- Operator-tunable weights → Task 5. +- Endpoint contract (seed first, limit default 50 / max 200, errors unchanged) → Task 6. +- Cross-user isolation → Task 4 + Task 6. +- Cold-start / never-played handling → Task 1 + Task 6. +- ≥ 70% coverage on the recommendation package → Task 7. +- End-to-end manual → Task 7. + +**Type consistency:** +- `ScoringInputs`, `ScoringWeights`, `Candidate` — same names everywhere they're consumed. +- `Score(...) → float64`, `Shuffle(...) → []Candidate`, `LoadCandidates(...) → []Candidate, error` — signatures stable. +- `recCfg config.RecommendationConfig` and `rng func() float64` — same on the handlers struct, in tests, in Mount. +- `pgtype.UUID` server-side, `string` at HTTP boundaries via `uuidToString`. + +**Filename hazards:** none — all new files under `internal/recommendation/`. The route-test handling for radio is colocated with the other api tests (no `+`-prefix concerns). + +**Placeholder scan:** no TBD/TODO/later markers. The `Column3` parameter naming caveat in Task 4 is documented inline (sqlc names unnamed positional params `Column1`, `Column2`, etc., adjust per generated code). + +**Performance note:** Task 6's per-pick album/artist resolve is N round-trips for the picks. For `RadioSize=50` that's 100 round-trips. Acceptable at v1 scale; matches the pattern used by `resolveTrackRefs` elsewhere. M4 / future task can batch via `IN (...)` + map-by-id if telemetry shows it matters.