# M4c — Radio Similarity-Driven Candidate Pool + Queue Refresh 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 M3's whole-library candidate pool with a 5-way SQL UNION of similarity sources (LB-similar tracks, similar-artist tracks, MB-tag overlap, likes-overlap, random fill), add a `SimilarityScore × SimilarityWeight` term to M3's `Score()`, and have the SPA auto-refresh the radio queue at 80% consumed via a new `?exclude=` query param. Closes M4.

**Architecture:** New sqlc query `LoadRadioCandidatesV2` performs the 5-way UNION + per-source scoring + final dedup-by-max in SQL. New `LoadCandidatesFromSimilarity` Go function projects rows to `[]Candidate` (same return type as M3's `LoadCandidates`, so `Shuffle()` is unchanged). Radio handler uses the new function as primary, falls back to M3's `LoadCandidates` on any error. Web client tracks `radioSeedId` and fires a refresh fetch when 80% consumed; clears on non-radio enqueues.

**Tech Stack:** Go 1.23 + sqlc + pgx/v5. SvelteKit 2 + Svelte 5 (runes) + TanStack Query. No schema migrations — relies on M4b's `track_similarity` / `artist_similarity` and existing M2 `general_likes` / M0-M1 `tracks.genre`.

**Reference:** design spec at `docs/superpowers/specs/2026-04-28-m4c-radio-design.md`.

---

## File Structure

**New server files:**

| File | Responsibility |
|---|---|
| `internal/db/queries/radio.sql` (modify) | Append `LoadRadioCandidatesV2 :many` — 5-way UNION + dedup-by-max. |
| `internal/db/dbq/radio.sql.go` | Generated bindings. |

Note: `internal/db/queries/recommendation.sql` currently holds `LoadRadioCandidates` (M3). I'll **add the V2 query to the same file** to keep radio-related queries co-located.

**Modified server files:**

| File | Change |
|---|---|
| `internal/recommendation/score.go` | `ScoringInputs` gains `SimilarityScore float64`, `ScoringWeights` gains `SimilarityWeight float64`. `Score()` adds `+ in.SimilarityScore * w.SimilarityWeight`. |
| `internal/recommendation/score_test.go` | 3 new tests for the new term. |
| `internal/recommendation/candidates.go` | Adds `CandidateSourceLimits` struct, `DefaultCandidateSourceLimits()`, `LoadCandidatesFromSimilarity()`. M3's `LoadCandidates` retained unchanged for fallback + tests. |
| `internal/recommendation/candidates_test.go` (or new `candidates_v2_test.go`) | 10 new integration tests for the similarity-pool path. |
| `internal/config/config.go` | `RecommendationConfig` gains `SimilarityWeight float64` (default `2.0`, yaml `similarity_weight`). |
| `internal/api/radio.go` | Parse `?exclude=`, build limits struct, call `LoadCandidatesFromSimilarity` first then fallback to `LoadCandidates`, thread `SimilarityWeight` into `ScoringWeights`. |
| `internal/api/radio_test.go` | 4 new tests for similarity ranking, exclude param, malformed exclude, fallback path. |
| `internal/api/auth_test.go` (or wherever `recCfg` test fixture lives) | Add `SimilarityWeight: 2.0` to the test recCfg literal. |

**Frontend files:**

| File | Responsibility |
|---|---|
| `web/src/lib/player/store.svelte.ts` | Add `radioSeedId` state, `appendRadioTracks()` helper, refresh effect, clear-on-non-radio-enqueue logic. |
| `web/src/lib/player/store.test.ts` | 5 new tests covering refresh behavior. |

---

## Task 1: sqlc query `LoadRadioCandidatesV2`

**Files:**
- Modify: `internal/db/queries/recommendation.sql` (append)
- Generated: `internal/db/dbq/recommendation.sql.go`

- [ ] **Step 1: Append the query**

Append to `internal/db/queries/recommendation.sql`:

```sql
-- name: LoadRadioCandidatesV2 :many
-- M4c: similarity-driven candidate pool. 5-way UNION:
--   $1 user_id, $2 seed_track_id, $3 recently_played_hours,
--   $4 exclude (uuid[]), $5 lb_similar K, $6 similar_artists K,
--   $7 tag_overlap K, $8 likes_overlap K, $9 random_fill K.
-- Returns same shape as LoadRadioCandidates plus similarity_score column.

WITH
seed_artist AS (SELECT artist_id FROM tracks WHERE id = $2),
seed_tags AS (
    SELECT trim(g) AS tag
    FROM tracks t,
         regexp_split_to_table(coalesce(t.genre, ''), '[;,]') AS g
    WHERE t.id = $2 AND trim(g) <> ''
),
exclude_set AS (
    SELECT unnest($4::uuid[]) AS id
    UNION ALL
    SELECT track_id FROM play_events
    WHERE user_id = $1 AND started_at > now() - $3 * interval '1 hour'
),
lb_similar AS (
    SELECT ts.track_b_id AS id, ts.score AS sim_score
    FROM track_similarity ts
    WHERE ts.track_a_id = $2
      AND ts.source = 'listenbrainz'
      AND ts.track_b_id NOT IN (SELECT id FROM exclude_set)
    ORDER BY ts.score DESC
    LIMIT $5
),
similar_artists AS (
    SELECT t.id, asim.score * 0.5 AS sim_score
    FROM artist_similarity asim
    JOIN tracks t ON t.artist_id = asim.artist_b_id
    JOIN seed_artist sa ON asim.artist_a_id = sa.artist_id
    WHERE asim.source = 'listenbrainz'
      AND t.id NOT IN (SELECT id FROM exclude_set)
    ORDER BY asim.score DESC, random()
    LIMIT $6
),
tag_overlap AS (
    SELECT t.id,
           (count(DISTINCT trim(g_raw))::float8
            / GREATEST((SELECT count(*) FROM seed_tags), 1)) AS sim_score
    FROM tracks t,
         regexp_split_to_table(coalesce(t.genre, ''), '[;,]') AS g_raw
    WHERE trim(g_raw) IN (SELECT tag FROM seed_tags)
      AND t.id NOT IN (SELECT id FROM exclude_set)
      AND t.id <> $2
    GROUP BY t.id
    HAVING count(DISTINCT trim(g_raw)) > 0
    ORDER BY sim_score DESC
    LIMIT $7
),
likes_overlap AS (
    SELECT gl.track_id AS id, 0.6::float8 AS sim_score
    FROM general_likes gl
    JOIN tracks t ON t.id = gl.track_id
    WHERE gl.user_id = $1
      AND t.id NOT IN (SELECT id FROM exclude_set)
      AND EXISTS (
          SELECT 1 FROM regexp_split_to_table(coalesce(t.genre, ''), '[;,]') g
          WHERE trim(g) IN (SELECT tag FROM seed_tags)
      )
    ORDER BY random()
    LIMIT $8
),
random_fill AS (
    SELECT t.id, 0.0::float8 AS sim_score
    FROM tracks t
    WHERE t.id NOT IN (SELECT id FROM exclude_set)
      AND t.id <> $2
      AND t.id NOT IN (
          SELECT id FROM lb_similar
          UNION SELECT id FROM similar_artists
          UNION SELECT id FROM tag_overlap
          UNION SELECT id FROM likes_overlap
      )
    ORDER BY random()
    LIMIT $9
)
SELECT
    sqlc.embed(t),
    (l.user_id IS NOT NULL)::bool AS is_liked,
    pe.last_played_at::timestamptz AS last_played_at,
    pe.play_count,
    pe.skip_count,
    max(u.sim_score) AS similarity_score
FROM (
    SELECT * FROM lb_similar
    UNION ALL SELECT * FROM similar_artists
    UNION ALL SELECT * FROM tag_overlap
    UNION ALL SELECT * FROM likes_overlap
    UNION ALL SELECT * FROM random_fill
) u
JOIN tracks t ON t.id = u.id
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
GROUP BY t.id, t.title, t.album_id, t.artist_id, t.duration_ms, t.file_path,
         t.file_format, t.file_size, t.bitrate, t.track_number, t.disc_number,
         t.mbid, t.genre, t.created_at, t.updated_at,
         l.user_id, pe.last_played_at, pe.play_count, pe.skip_count;
```

- [ ] **Step 2: Run sqlc generate**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && make generate`

Expected: `internal/db/dbq/recommendation.sql.go` regenerated with `LoadRadioCandidatesV2(ctx, arg LoadRadioCandidatesV2Params) ([]LoadRadioCandidatesV2Row, error)`. Inspect to confirm:
- The `LoadRadioCandidatesV2Params` struct has 9 fields. sqlc names them after column hints when possible; otherwise positional like `Column3`, `Column4`. Note actual generated names — Task 3 will use them.
- The `LoadRadioCandidatesV2Row` struct has the embedded `Track` plus `IsLiked bool`, `LastPlayedAt pgtype.Timestamptz`, `PlayCount int64`, `SkipCount int64`, `SimilarityScore float64`.

- [ ] **Step 3: Verify compile**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && go build ./...`

Expected: clean.

- [ ] **Step 4: Commit**

```bash
cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel
git add internal/db/queries/recommendation.sql internal/db/dbq/
git commit -m "feat(db): add LoadRadioCandidatesV2 sqlc query (5-way UNION)"
```

---

## Task 2: `Score()` + `RecommendationConfig` extension

**Files:**
- Modify: `internal/recommendation/score.go`
- Modify: `internal/recommendation/score_test.go`
- Modify: `internal/config/config.go`

- [ ] **Step 1: Write the failing tests**

Append to `internal/recommendation/score_test.go`:

```go
func TestScore_SimilarityScore_PerfectMatchAtWeight2(t *testing.T) {
	w := defaultWeights()
	w.SimilarityWeight = 2.0
	in := ScoringInputs{SimilarityScore: 1.0}
	got := Score(in, w, time.Now(), fixedRNG(0.5))
	// base 1.0 + recency 1.0 (never played) + similarity 2.0 = 4.0
	want := 4.0
	if math.Abs(got-want) > 1e-9 {
		t.Errorf("score = %v, want %v", got, want)
	}
}

func TestScore_SimilarityScore_HalfMatchAtWeight2(t *testing.T) {
	w := defaultWeights()
	w.SimilarityWeight = 2.0
	in := ScoringInputs{SimilarityScore: 0.5}
	got := Score(in, w, time.Now(), fixedRNG(0.5))
	// base 1.0 + recency 1.0 + similarity 1.0 = 3.0
	want := 3.0
	if math.Abs(got-want) > 1e-9 {
		t.Errorf("score = %v, want %v", got, want)
	}
}

func TestScore_SimilarityScore_ZeroNoEffect(t *testing.T) {
	wWithSim := defaultWeights()
	wWithSim.SimilarityWeight = 2.0
	withSim := Score(ScoringInputs{SimilarityScore: 0}, wWithSim, time.Now(), fixedRNG(0.5))
	withoutSim := Score(ScoringInputs{}, defaultWeights(), time.Now(), fixedRNG(0.5))
	if math.Abs(withSim-withoutSim) > 1e-9 {
		t.Errorf("score-with-zero-sim = %v, score-without = %v; should be equal", withSim, withoutSim)
	}
}
```

- [ ] **Step 2: Run tests to verify they fail**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && go test ./internal/recommendation/ -run Score -v`

Expected: FAIL — `ScoringInputs` has no `SimilarityScore`, `ScoringWeights` has no `SimilarityWeight`.

- [ ] **Step 3: Extend `score.go`**

Replace `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.
// ContextualMatchScore is in [0, 1] — max similarity between the user's
// current session vector and any non-seed contextual_like row for this
// track. SimilarityScore is in [0, 1] — max similarity-source score for
// this candidate (LB-similar / similar-artist × 0.5 / tag-overlap jaccard
// / likes-overlap constant; random fill = 0). Both set by candidate
// loaders before scoring.
type ScoringInputs struct {
	IsGeneralLiked       bool
	LastPlayedAt         *time.Time // nil = never played
	PlayCount            int        // total play_events
	SkipCount            int        // play_events with was_skipped=true
	ContextualMatchScore float64    // [0, 1]; 0 when no signal
	SimilarityScore      float64    // [0, 1]; 0 when no signal (M4c)
}

// 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
	ContextWeight    float64
	SimilarityWeight float64 // M4c
}

// Score computes the weighted-shuffle score per spec §6:
//
//	score = base
//	      + (is_general_liked ? LikeBoost : 0)
//	      + recency_decay * RecencyWeight
//	      - skip_ratio * SkipPenalty
//	      + contextual_match_score * ContextWeight
//	      + similarity_score * SimilarityWeight
//	      + 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 += in.ContextualMatchScore * w.ContextWeight
	s += in.SimilarityScore * w.SimilarityWeight
	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: Extend `RecommendationConfig`**

In `internal/config/config.go`, modify `RecommendationConfig`:

```go
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"`
	ContextWeight       float64 `yaml:"context_weight"`
	SimilarityWeight    float64 `yaml:"similarity_weight"` // M4c
	RecentlyPlayedHours int     `yaml:"recently_played_hours"`
	RadioSize           int     `yaml:"radio_size"`
	RadioSizeMax        int     `yaml:"radio_size_max"`
}
```

In the same file, modify `Default()`'s `Recommendation` block to include the new field:

```go
Recommendation: RecommendationConfig{
	BaseWeight:          1.0,
	LikeBoost:           2.0,
	RecencyWeight:       1.0,
	SkipPenalty:         1.0,
	JitterMagnitude:     0.1,
	ContextWeight:       2.0,
	SimilarityWeight:    2.0,
	RecentlyPlayedHours: 1,
	RadioSize:           50,
	RadioSizeMax:        200,
},
```

- [ ] **Step 5: Run tests to verify they pass**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && go test ./internal/recommendation/ -run Score -v`

Expected: PASS for all existing Score tests + 3 new similarity tests.

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && go build ./...`

Expected: clean.

- [ ] **Step 6: Verify lint clean**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && golangci-lint run ./...`

Expected: clean.

- [ ] **Step 7: Commit**

```bash
cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel
git add internal/recommendation/score.go internal/recommendation/score_test.go internal/config/config.go
git commit -m "feat(recommendation): extend Score with SimilarityScore + SimilarityWeight"
```

---

## Task 3: `LoadCandidatesFromSimilarity` Go function + integration tests

**Files:**
- Modify: `internal/recommendation/candidates.go` (append)
- Create: `internal/recommendation/candidates_v2_test.go`

- [ ] **Step 1: Write the failing integration tests**

Create `internal/recommendation/candidates_v2_test.go`:

```go
package recommendation

import (
	"context"
	"testing"
	"time"

	"github.com/jackc/pgx/v5/pgtype"

	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
)

// helperLBSimilarity inserts a track_similarity row.
func helperLBSimilarity(t *testing.T, f fixture, a, b pgtype.UUID, score float64) {
	t.Helper()
	if _, err := f.pool.Exec(context.Background(),
		`INSERT INTO track_similarity (track_a_id, track_b_id, score, source) VALUES ($1, $2, $3, 'listenbrainz')`,
		a, b, score); err != nil {
		t.Fatalf("insert track_similarity: %v", err)
	}
}

// helperArtistSimilarity inserts an artist_similarity row.
func helperArtistSimilarity(t *testing.T, f fixture, a, b pgtype.UUID, score float64) {
	t.Helper()
	if _, err := f.pool.Exec(context.Background(),
		`INSERT INTO artist_similarity (artist_a_id, artist_b_id, score, source) VALUES ($1, $2, $3, 'listenbrainz')`,
		a, b, score); err != nil {
		t.Fatalf("insert artist_similarity: %v", err)
	}
}

// helperSeedTrackWithGenre creates a track with a specified genre + mbid.
func helperSeedTrackWithGenre(t *testing.T, f fixture, title, genre, mbid string) dbq.Track {
	t.Helper()
	tr, err := f.q.UpsertTrack(context.Background(), dbq.UpsertTrackParams{
		Title:    title,
		AlbumID:  f.tracks[0].AlbumID,
		ArtistID: f.tracks[0].ArtistID,
		FilePath: "/tmp/" + title + ".flac",
		DurationMs: 180_000,
		Genre:    &genre,
		Mbid:     &mbid,
	})
	if err != nil {
		t.Fatalf("track: %v", err)
	}
	return tr
}

func defaultLimits() CandidateSourceLimits {
	return DefaultCandidateSourceLimits()
}

func TestLoadCandidatesFromSimilarity_LBSimilarSourceContributes(t *testing.T) {
	f := newFixture(t, 5)
	seed := f.tracks[0]
	target := f.tracks[1]
	helperLBSimilarity(t, f, seed.ID, target.ID, 0.85)
	got, err := LoadCandidatesFromSimilarity(
		context.Background(), f.q, f.user, seed.ID, 1, SessionVector{Seed: true}, nil, defaultLimits(),
	)
	if err != nil {
		t.Fatalf("load: %v", err)
	}
	var found *Candidate
	for i := range got {
		if got[i].Track.ID == target.ID {
			found = &got[i]
			break
		}
	}
	if found == nil {
		t.Fatal("LB-similar target missing from candidates")
	}
	if found.Inputs.SimilarityScore < 0.84 || found.Inputs.SimilarityScore > 0.86 {
		t.Errorf("LB-similar SimilarityScore = %v, want ~0.85", found.Inputs.SimilarityScore)
	}
}

func TestLoadCandidatesFromSimilarity_SimilarArtistTracksContribute(t *testing.T) {
	f := newFixture(t, 1) // seed only
	seed := f.tracks[0]
	// Add a second artist + track in that artist; relate the artists via artist_similarity.
	otherArtist, _ := f.q.UpsertArtist(context.Background(), dbq.UpsertArtistParams{Name: "OtherArtist", SortName: "OtherArtist"})
	otherAlbum, _ := f.q.UpsertAlbum(context.Background(), dbq.UpsertAlbumParams{Title: "OtherAlbum", SortTitle: "OtherAlbum", ArtistID: otherArtist.ID})
	otherTrack, _ := f.q.UpsertTrack(context.Background(), dbq.UpsertTrackParams{
		Title: "OtherTrack", AlbumID: otherAlbum.ID, ArtistID: otherArtist.ID,
		FilePath: "/tmp/other.flac", DurationMs: 180_000,
	})
	helperArtistSimilarity(t, f, seed.ArtistID, otherArtist.ID, 0.8)
	got, err := LoadCandidatesFromSimilarity(
		context.Background(), f.q, f.user, seed.ID, 1, SessionVector{Seed: true}, nil, defaultLimits(),
	)
	if err != nil {
		t.Fatalf("load: %v", err)
	}
	for _, c := range got {
		if c.Track.ID == otherTrack.ID {
			// 0.8 × 0.5 = 0.4
			if c.Inputs.SimilarityScore < 0.39 || c.Inputs.SimilarityScore > 0.41 {
				t.Errorf("similar-artist SimilarityScore = %v, want ~0.4 (0.8 × 0.5)", c.Inputs.SimilarityScore)
			}
			return
		}
	}
	t.Error("similar-artist track missing from candidates")
}

func TestLoadCandidatesFromSimilarity_TagOverlapContributes(t *testing.T) {
	f := newFixture(t, 0)
	seed := helperSeedTrackWithGenre(t, f, "Seed", "Rock; Pop", "11111111-1111-1111-1111-111111111111")
	target := helperSeedTrackWithGenre(t, f, "Target", "Rock", "22222222-2222-2222-2222-222222222222")
	got, err := LoadCandidatesFromSimilarity(
		context.Background(), f.q, f.user, seed.ID, 1, SessionVector{Seed: true}, nil, defaultLimits(),
	)
	if err != nil {
		t.Fatalf("load: %v", err)
	}
	for _, c := range got {
		if c.Track.ID == target.ID {
			// Seed has 2 tags; target shares 1 → jaccard 1/2 = 0.5.
			if c.Inputs.SimilarityScore < 0.49 || c.Inputs.SimilarityScore > 0.51 {
				t.Errorf("tag-overlap SimilarityScore = %v, want ~0.5", c.Inputs.SimilarityScore)
			}
			return
		}
	}
	t.Error("tag-overlap target missing from candidates")
}

func TestLoadCandidatesFromSimilarity_LikesOverlapContributes(t *testing.T) {
	f := newFixture(t, 0)
	seed := helperSeedTrackWithGenre(t, f, "Seed", "Rock", "11111111-1111-1111-1111-111111111111")
	liked := helperSeedTrackWithGenre(t, f, "Liked", "Rock", "22222222-2222-2222-2222-222222222222")
	if _, err := f.q.LikeTrack(context.Background(), dbq.LikeTrackParams{UserID: f.user, TrackID: liked.ID}); err != nil {
		t.Fatalf("like: %v", err)
	}
	got, err := LoadCandidatesFromSimilarity(
		context.Background(), f.q, f.user, seed.ID, 1, SessionVector{Seed: true}, nil, defaultLimits(),
	)
	if err != nil {
		t.Fatalf("load: %v", err)
	}
	for _, c := range got {
		if c.Track.ID == liked.ID {
			// Could come from tag-overlap (1.0 jaccard) OR likes-overlap (0.6) — max wins.
			// Since both tracks are tagged "Rock" identically, jaccard = 1/1 = 1.0, which beats 0.6.
			if c.Inputs.SimilarityScore < 0.59 {
				t.Errorf("likes-overlap candidate SimilarityScore = %v, want ≥ 0.6", c.Inputs.SimilarityScore)
			}
			return
		}
	}
	t.Error("liked track with shared tag missing from candidates")
}

func TestLoadCandidatesFromSimilarity_RandomFillReturnsTracks(t *testing.T) {
	f := newFixture(t, 10) // 10 tracks; no similarity data
	seed := f.tracks[0]
	got, err := LoadCandidatesFromSimilarity(
		context.Background(), f.q, f.user, seed.ID, 1, SessionVector{Seed: true}, nil, defaultLimits(),
	)
	if err != nil {
		t.Fatalf("load: %v", err)
	}
	// Random fill should provide at least some of the 9 non-seed tracks.
	if len(got) == 0 {
		t.Error("random fill returned 0 candidates; expected at least some")
	}
	// All should have SimilarityScore = 0 (no similarity sources).
	for _, c := range got {
		if c.Inputs.SimilarityScore != 0 {
			t.Errorf("random-fill track %s has SimilarityScore = %v, want 0", c.Track.Title, c.Inputs.SimilarityScore)
		}
	}
}

func TestLoadCandidatesFromSimilarity_ExcludeListRespected(t *testing.T) {
	f := newFixture(t, 5)
	seed := f.tracks[0]
	excluded := f.tracks[1].ID
	got, err := LoadCandidatesFromSimilarity(
		context.Background(), f.q, f.user, seed.ID, 1, SessionVector{Seed: true},
		[]pgtype.UUID{excluded}, defaultLimits(),
	)
	if err != nil {
		t.Fatalf("load: %v", err)
	}
	for _, c := range got {
		if c.Track.ID == excluded {
			t.Error("excluded track appeared in candidates")
		}
	}
}

func TestLoadCandidatesFromSimilarity_SeedAlwaysExcluded(t *testing.T) {
	f := newFixture(t, 5)
	seed := f.tracks[0]
	got, err := LoadCandidatesFromSimilarity(
		context.Background(), f.q, f.user, seed.ID, 1, SessionVector{Seed: true}, nil, defaultLimits(),
	)
	if err != nil {
		t.Fatalf("load: %v", err)
	}
	for _, c := range got {
		if c.Track.ID == seed.ID {
			t.Error("seed track appeared in candidates")
		}
	}
}

func TestLoadCandidatesFromSimilarity_RecentlyPlayedExcluded(t *testing.T) {
	f := newFixture(t, 5)
	seed := f.tracks[0]
	recent := f.tracks[1].ID
	// Insert a play_event within the last hour.
	var sessionID pgtype.UUID
	if err := f.pool.QueryRow(context.Background(),
		`INSERT INTO play_sessions (user_id, started_at, last_event_at, client_id)
		 VALUES ($1, now() - interval '5 minutes', now(), 'test') RETURNING id`,
		f.user).Scan(&sessionID); err != nil {
		t.Fatalf("session: %v", err)
	}
	if _, err := f.pool.Exec(context.Background(),
		`INSERT INTO play_events (user_id, track_id, session_id, started_at, ended_at, duration_played_ms, completion_ratio, was_skipped)
		 VALUES ($1, $2, $3, now() - interval '30 minutes', now() - interval '20 minutes', 200000, 0.9, false)`,
		f.user, recent, sessionID); err != nil {
		t.Fatalf("play_event: %v", err)
	}
	got, err := LoadCandidatesFromSimilarity(
		context.Background(), f.q, f.user, seed.ID, 1, SessionVector{Seed: true}, nil, defaultLimits(),
	)
	if err != nil {
		t.Fatalf("load: %v", err)
	}
	for _, c := range got {
		if c.Track.ID == recent {
			t.Error("recently-played track appeared in candidates")
		}
	}
}

func TestLoadCandidatesFromSimilarity_DedupTakesMaxScore(t *testing.T) {
	f := newFixture(t, 0)
	seed := helperSeedTrackWithGenre(t, f, "Seed", "Rock", "11111111-1111-1111-1111-111111111111")
	// Target shares the LB-similar source (high score) AND tag-overlap (low score).
	target := helperSeedTrackWithGenre(t, f, "Target", "Rock", "22222222-2222-2222-2222-222222222222")
	helperLBSimilarity(t, f, seed.ID, target.ID, 0.95)
	got, err := LoadCandidatesFromSimilarity(
		context.Background(), f.q, f.user, seed.ID, 1, SessionVector{Seed: true}, nil, defaultLimits(),
	)
	if err != nil {
		t.Fatalf("load: %v", err)
	}
	count := 0
	for _, c := range got {
		if c.Track.ID == target.ID {
			count++
			// LB 0.95 should win over tag-overlap (jaccard 1/1 = 1.0). Wait — 1.0 > 0.95. Adjust:
			// seed and target both have only "Rock" tag → jaccard = 1.0 from tag-overlap.
			// LB sim = 0.95. Max = 1.0. So this test verifies max() picks tag-overlap here.
			if c.Inputs.SimilarityScore < 0.99 {
				t.Errorf("dedup max SimilarityScore = %v, want 1.0 (tag-overlap wins)", c.Inputs.SimilarityScore)
			}
		}
	}
	if count != 1 {
		t.Errorf("target appeared %d times, want 1 (dedup failed)", count)
	}
}

func TestLoadCandidatesFromSimilarity_EmptyLibrary_NoError(t *testing.T) {
	f := newFixture(t, 0)
	// Seed an isolated track to query against.
	seed := helperSeedTrackWithGenre(t, f, "Seed", "Rock", "11111111-1111-1111-1111-111111111111")
	got, err := LoadCandidatesFromSimilarity(
		context.Background(), f.q, f.user, seed.ID, 1, SessionVector{Seed: true}, nil, defaultLimits(),
	)
	if err != nil {
		t.Fatalf("load: %v", err)
	}
	if len(got) != 0 {
		t.Errorf("got %d candidates from empty library, want 0", len(got))
	}
	_ = time.Now() // silence unused-import warning if loop never runs
}
```

The `fixture` and `newFixture` helpers come from `candidates_test.go` (existing M3 fixture). If `newFixture(t, 0)` doesn't exist (i.e. it requires ≥1 track), peek at the existing helper's signature and adjust the test to use the smallest legal value.

- [ ] **Step 2: Run tests to verify they fail**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && MINSTREL_TEST_DATABASE_URL='postgres://minstrel:minstrel@172.22.0.2:5432/minstrel?sslmode=disable' go test ./internal/recommendation/ -run LoadCandidatesFromSimilarity -v`

Expected: FAIL — `undefined: LoadCandidatesFromSimilarity`, `undefined: CandidateSourceLimits`, `undefined: DefaultCandidateSourceLimits`.

- [ ] **Step 3: Implement `LoadCandidatesFromSimilarity`**

Append to `internal/recommendation/candidates.go`:

```go
// CandidateSourceLimits controls per-source K values for the M4c
// similarity-driven pool. Defaults via DefaultCandidateSourceLimits().
type CandidateSourceLimits struct {
	LBSimilar     int
	SimilarArtist int
	TagOverlap    int
	LikesOverlap  int
	RandomFill    int
}

// DefaultCandidateSourceLimits returns the v1 hardcoded constants per spec.
func DefaultCandidateSourceLimits() CandidateSourceLimits {
	return CandidateSourceLimits{
		LBSimilar:     30,
		SimilarArtist: 30,
		TagOverlap:    20,
		LikesOverlap:  20,
		RandomFill:    30,
	}
}

// LoadCandidatesFromSimilarity is M4c's primary candidate-pool loader.
// 5-way SQL UNION (LB-similar / similar-artist tracks / MB-tag overlap /
// likes-overlap / random fill) + dedup-by-max sim_score. Returns
// []Candidate (same shape as LoadCandidates) so Shuffle is unchanged.
//
// Caller (radio handler) falls back to LoadCandidates on error.
func LoadCandidatesFromSimilarity(
	ctx context.Context,
	q *dbq.Queries,
	userID, seedID pgtype.UUID,
	recentlyPlayedHours int,
	currentVector SessionVector,
	exclude []pgtype.UUID,
	limits CandidateSourceLimits,
) ([]Candidate, error) {
	if exclude == nil {
		exclude = []pgtype.UUID{}
	}
	rows, err := q.LoadRadioCandidatesV2(ctx, dbq.LoadRadioCandidatesV2Params{
		UserID:   userID,
		ID:       seedID,
		Column3:  float64(recentlyPlayedHours),
		Column4:  exclude,
		Column5:  int32(limits.LBSimilar),
		Column6:  int32(limits.SimilarArtist),
		Column7:  int32(limits.TagOverlap),
		Column8:  int32(limits.LikesOverlap),
		Column9:  int32(limits.RandomFill),
	})
	if err != nil {
		return nil, err
	}

	likes, err := loadContextualLikesByTrack(ctx, q, userID)
	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
		}
		ctxScore := ContextualMatchScore(currentVector, likes[r.Track.ID], DefaultSimilarityWeights)
		out = append(out, Candidate{
			Track: r.Track,
			Inputs: ScoringInputs{
				IsGeneralLiked:       r.IsLiked,
				LastPlayedAt:         lpt,
				PlayCount:            int(r.PlayCount),
				SkipCount:            int(r.SkipCount),
				ContextualMatchScore: ctxScore,
				SimilarityScore:      r.SimilarityScore,
			},
		})
	}
	return out, nil
}
```

**Note on sqlc-generated param field names:** the `LoadRadioCandidatesV2Params` field names depend on sqlc's auto-generated names from the SQL parameter positions. After Task 1's `make generate`, inspect `internal/db/dbq/recommendation.sql.go` and adjust the field references (`UserID`, `ID`, `Column3`, etc.) to match what sqlc actually emitted. The actual names may be `Column3` for `$3` (recently_played_hours), `Column4` for `$4` (exclude), etc., or sqlc may pick smarter names from context. Rename to match.

- [ ] **Step 4: Run tests to verify they pass**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && MINSTREL_TEST_DATABASE_URL='postgres://minstrel:minstrel@172.22.0.2:5432/minstrel?sslmode=disable' go test ./internal/recommendation/ -run LoadCandidatesFromSimilarity -v`

Expected: PASS for all 10 tests.

- [ ] **Step 5: Verify lint clean**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && golangci-lint run ./internal/recommendation/...`

Expected: clean.

- [ ] **Step 6: Commit**

```bash
cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel
git add internal/recommendation/candidates.go internal/recommendation/candidates_v2_test.go
git commit -m "feat(recommendation): add LoadCandidatesFromSimilarity (5-source candidate pool)"
```

---

## Task 4: Radio handler — exclude param + similarity pool + fallback

**Files:**
- Modify: `internal/api/radio.go`
- Modify: `internal/api/radio_test.go`
- Modify: `internal/api/auth_test.go` (testHandlers' `recCfg` literal)

- [ ] **Step 1: Write the failing tests**

Append to `internal/api/radio_test.go`:

```go
func TestHandleRadio_WithSimilarityPool_RanksLBSimilarHigher(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)
	// Two non-seed tracks: one LB-similar (high score), one not.
	target := seedTrack(t, pool, album.ID, artist.ID, "Target", 2, 100_000)
	control := seedTrack(t, pool, album.ID, artist.ID, "Control", 3, 100_000)
	if _, err := pool.Exec(context.Background(),
		`INSERT INTO track_similarity (track_a_id, track_b_id, score, source) VALUES ($1, $2, 0.95, 'listenbrainz')`,
		seed.ID, target.ID); err != nil {
		t.Fatalf("insert sim: %v", err)
	}
	w := callRadio(h, user, "seed_track="+uuidToString(seed.ID)+"&limit=3")
	if w.Code != http.StatusOK {
		t.Fatalf("status = %d", w.Code)
	}
	var resp RadioResponse
	_ = json.Unmarshal(w.Body.Bytes(), &resp)
	// resp.Tracks[0] is seed; check whether target ranks above control.
	var targetIdx, controlIdx int
	targetIdx, controlIdx = -1, -1
	for i, tr := range resp.Tracks {
		if tr.ID == uuidToString(target.ID) {
			targetIdx = i
		}
		if tr.ID == uuidToString(control.ID) {
			controlIdx = i
		}
	}
	if targetIdx < 0 || controlIdx < 0 {
		t.Fatalf("target=%d control=%d (one not present)", targetIdx, controlIdx)
	}
	if targetIdx >= controlIdx {
		t.Errorf("target ranked at %d, control at %d — LB-similar should rank higher", targetIdx, controlIdx)
	}
}

func TestHandleRadio_ExcludeParamFiltersOut(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)
	excluded := seedTrack(t, pool, album.ID, artist.ID, "Excluded", 2, 100_000)
	for i := 3; i <= 6; i++ {
		seedTrack(t, pool, album.ID, artist.ID, "T"+string(rune('0'+i)), i, 100_000)
	}
	q := "seed_track=" + uuidToString(seed.ID) + "&limit=10&exclude=" + uuidToString(excluded.ID)
	w := callRadio(h, user, q)
	if w.Code != http.StatusOK {
		t.Fatalf("status = %d", w.Code)
	}
	var resp RadioResponse
	_ = json.Unmarshal(w.Body.Bytes(), &resp)
	for _, tr := range resp.Tracks {
		if tr.ID == uuidToString(excluded.ID) {
			t.Error("excluded track present in response")
		}
	}
}

func TestHandleRadio_ExcludeParamMalformedSkipped(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)
	other := seedTrack(t, pool, album.ID, artist.ID, "Other", 2, 100_000)
	q := "seed_track=" + uuidToString(seed.ID) + "&limit=5&exclude=not-a-uuid," + uuidToString(other.ID)
	w := callRadio(h, user, q)
	if w.Code != http.StatusOK {
		t.Fatalf("status = %d (malformed UUID should be silently dropped)", w.Code)
	}
	var resp RadioResponse
	_ = json.Unmarshal(w.Body.Bytes(), &resp)
	for _, tr := range resp.Tracks {
		if tr.ID == uuidToString(other.ID) {
			t.Error("other track should still be excluded after dropping malformed entry")
		}
	}
}

func TestHandleRadio_SeedAlwaysAtIndex0(t *testing.T) {
	// Defensive: even when the similarity pool returns no candidates,
	// the seed track must still be the first track in the response.
	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", w.Code)
	}
	var resp RadioResponse
	_ = json.Unmarshal(w.Body.Bytes(), &resp)
	if len(resp.Tracks) == 0 || resp.Tracks[0].ID != uuidToString(seed.ID) {
		t.Errorf("seed not at index 0: %v", resp.Tracks)
	}
}
```

- [ ] **Step 2: Update `auth_test.go::testHandlers` recCfg literal**

In `internal/api/auth_test.go`, find the `recCfg := config.RecommendationConfig{...}` literal in `testHandlers` and add `SimilarityWeight: 2.0`:

```go
recCfg := config.RecommendationConfig{
	BaseWeight: 1.0, LikeBoost: 2.0, RecencyWeight: 1.0,
	SkipPenalty: 1.0, JitterMagnitude: 0.1,
	ContextWeight: 2.0, SimilarityWeight: 2.0,
	RecentlyPlayedHours: 1, RadioSize: 50, RadioSizeMax: 200,
}
```

- [ ] **Step 3: Update the radio handler**

In `internal/api/radio.go`, replace the `LoadCandidates` call site. Before it, parse the exclude param + build the limits struct + add the seed to the exclude list. Keep the M3 `LoadCandidates` call as a fallback path.

Replace the section from `currentVec := loadCurrentSessionVector(...)` through `weights := recommendation.ScoringWeights{...}`:

```go
	currentVec := loadCurrentSessionVector(r, q, user.ID, h.logger)

	exclude := parseExcludeParam(r.URL.Query().Get("exclude"))
	limits := recommendation.DefaultCandidateSourceLimits()
	candidates, err := recommendation.LoadCandidatesFromSimilarity(
		r.Context(), q, user.ID, seedID,
		h.recCfg.RecentlyPlayedHours, currentVec, exclude, limits,
	)
	if err != nil {
		h.logger.Warn("api: radio: similarity-pool failed; falling back to whole-library", "err", err)
		candidates, err = recommendation.LoadCandidates(
			r.Context(), q, user.ID, seedID,
			h.recCfg.RecentlyPlayedHours, currentVec,
		)
		if err != nil {
			h.logger.Error("api: radio: load candidates fallback failed", "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,
		ContextWeight:    h.recCfg.ContextWeight,
		SimilarityWeight: h.recCfg.SimilarityWeight,
	}
```

Append the helper at the bottom of the same file:

```go
// parseExcludeParam parses a comma-separated list of UUIDs from the
// `exclude` query string, silently dropping malformed entries. Returns
// nil for empty or all-malformed input.
func parseExcludeParam(raw string) []pgtype.UUID {
	if raw == "" {
		return nil
	}
	parts := strings.Split(raw, ",")
	out := make([]pgtype.UUID, 0, len(parts))
	for _, p := range parts {
		p = strings.TrimSpace(p)
		if p == "" {
			continue
		}
		id, ok := parseUUID(p)
		if !ok {
			continue
		}
		out = append(out, id)
	}
	return out
}
```

`parseUUID` already exists in `internal/api/`. Confirm that `strings` is in the import block (it should already be).

- [ ] **Step 4: Run tests to verify they pass**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && MINSTREL_TEST_DATABASE_URL='postgres://minstrel:minstrel@172.22.0.2:5432/minstrel?sslmode=disable' go test ./internal/api/ -v 2>&1 | tail -30`

Expected: PASS for all existing API tests + 4 new radio tests.

- [ ] **Step 5: Verify lint clean**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && golangci-lint run ./...`

Expected: clean.

- [ ] **Step 6: Commit**

```bash
cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel
git add internal/api/radio.go internal/api/radio_test.go internal/api/auth_test.go
git commit -m "feat(api): radio uses similarity pool with exclude param + M3 fallback"
```

---

## Task 5: Frontend — radio queue refresh at 80%

**Files:**
- Modify: `web/src/lib/player/store.svelte.ts`
- Modify: `web/src/lib/player/store.test.ts`

- [ ] **Step 1: Write the failing tests**

Append to `web/src/lib/player/store.test.ts`:

```ts
describe('radio refresh at 80%', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  test('refresh fires at 80% queue consumption', async () => {
    const tracks: TrackRef[] = Array.from({ length: 5 }, (_, i) => ({
      id: `t${i}`, title: `T${i}`, album_id: 'al', album_title: 'Al',
      artist_id: 'ar', artist_name: 'Ar', track_number: i + 1, disc_number: 1,
      duration_sec: 100, stream_url: `/api/tracks/t${i}/stream`
    }));
    (apiGet as ReturnType<typeof vi.fn>).mockResolvedValueOnce({ tracks });
    await playRadio('seed1');
    // Now queue is the 5 tracks. Reset mock for refresh call.
    (apiGet as ReturnType<typeof vi.fn>).mockClear();
    (apiGet as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
      tracks: [tracks[0], { ...tracks[0], id: 'new1', title: 'New1' }]
    });
    // Advance to index 4 (5th of 5 = 100%, but cross 80% at index 3)
    // Skip to index 3 (4th track played; 4/5 = 80%)
    skipNext(); skipNext(); skipNext();
    // Allow $effect to fire
    await new Promise((r) => setTimeout(r, 10));
    expect(apiGet).toHaveBeenCalled();
    const callArg = (apiGet as ReturnType<typeof vi.fn>).mock.calls[0][0];
    expect(callArg).toContain('seed_track=seed1');
    expect(callArg).toContain('exclude=');
  });

  test('refresh below 80% does not fire', async () => {
    const tracks: TrackRef[] = Array.from({ length: 5 }, (_, i) => ({
      id: `t${i}`, title: `T${i}`, album_id: 'al', album_title: 'Al',
      artist_id: 'ar', artist_name: 'Ar', track_number: i + 1, disc_number: 1,
      duration_sec: 100, stream_url: `/api/tracks/t${i}/stream`
    }));
    (apiGet as ReturnType<typeof vi.fn>).mockResolvedValueOnce({ tracks });
    await playRadio('seed1');
    (apiGet as ReturnType<typeof vi.fn>).mockClear();
    skipNext(); skipNext(); // index = 2 (3 of 5 = 60%)
    await new Promise((r) => setTimeout(r, 10));
    expect(apiGet).not.toHaveBeenCalled();
  });

  test('refresh appends new tracks excluding seed at index 0', async () => {
    const initial: TrackRef[] = Array.from({ length: 5 }, (_, i) => ({
      id: `t${i}`, title: `T${i}`, album_id: 'al', album_title: 'Al',
      artist_id: 'ar', artist_name: 'Ar', track_number: i + 1, disc_number: 1,
      duration_sec: 100, stream_url: `/api/tracks/t${i}/stream`
    }));
    (apiGet as ReturnType<typeof vi.fn>).mockResolvedValueOnce({ tracks: initial });
    await playRadio('seed1');
    // Refresh response: 5 tracks where the first is the seed (will be stripped).
    const refreshTracks: TrackRef[] = Array.from({ length: 5 }, (_, i) => ({
      id: i === 0 ? initial[0].id : `n${i}`,
      title: i === 0 ? initial[0].title : `N${i}`,
      album_id: 'al', album_title: 'Al', artist_id: 'ar', artist_name: 'Ar',
      track_number: i + 1, disc_number: 1, duration_sec: 100,
      stream_url: '/api/tracks/x/stream'
    }));
    (apiGet as ReturnType<typeof vi.fn>).mockResolvedValueOnce({ tracks: refreshTracks });
    skipNext(); skipNext(); skipNext(); // index = 3 (80%)
    await new Promise((r) => setTimeout(r, 10));
    // Initial 5 + 4 new (5 in response - 1 seed stripped) = 9
    expect(player.queue.length).toBe(9);
  });

  test('refresh does NOT double-fire while in-flight', async () => {
    const tracks: TrackRef[] = Array.from({ length: 5 }, (_, i) => ({
      id: `t${i}`, title: `T${i}`, album_id: 'al', album_title: 'Al',
      artist_id: 'ar', artist_name: 'Ar', track_number: i + 1, disc_number: 1,
      duration_sec: 100, stream_url: `/api/tracks/t${i}/stream`
    }));
    (apiGet as ReturnType<typeof vi.fn>).mockResolvedValueOnce({ tracks });
    await playRadio('seed1');
    (apiGet as ReturnType<typeof vi.fn>).mockClear();
    // Hang the refresh call so the in-flight flag stays set.
    let resolveFn!: (v: unknown) => void;
    const hanging = new Promise((r) => { resolveFn = r; });
    (apiGet as ReturnType<typeof vi.fn>).mockReturnValueOnce(hanging);
    skipNext(); skipNext(); skipNext(); // 80% — fires refresh
    await new Promise((r) => setTimeout(r, 10));
    // Now advance further while in-flight; should NOT fire a second call.
    skipNext();
    await new Promise((r) => setTimeout(r, 10));
    expect(apiGet).toHaveBeenCalledTimes(1);
    resolveFn({ tracks: [] });
  });

  test('refresh resets when user enqueues from non-radio source', async () => {
    const tracks: TrackRef[] = Array.from({ length: 5 }, (_, i) => ({
      id: `t${i}`, title: `T${i}`, album_id: 'al', album_title: 'Al',
      artist_id: 'ar', artist_name: 'Ar', track_number: i + 1, disc_number: 1,
      duration_sec: 100, stream_url: `/api/tracks/t${i}/stream`
    }));
    (apiGet as ReturnType<typeof vi.fn>).mockResolvedValueOnce({ tracks });
    await playRadio('seed1');
    enqueueTrack({
      id: 'manual1', title: 'Manual', album_id: 'al', album_title: 'Al',
      artist_id: 'ar', artist_name: 'Ar', track_number: 99, disc_number: 1,
      duration_sec: 100, stream_url: '/api/tracks/manual1/stream'
    });
    (apiGet as ReturnType<typeof vi.fn>).mockClear();
    skipNext(); skipNext(); skipNext(); skipNext(); // advance past 80% on the now-6-track queue
    await new Promise((r) => setTimeout(r, 10));
    expect(apiGet).not.toHaveBeenCalled();
  });
});
```

The existing test setup may already mock `$lib/api/client` (where `apiGet` lives) — match the existing pattern in the file. If `apiGet` isn't currently mocked, add a mock at the top of `store.test.ts`:

```ts
vi.mock('$lib/api/client', () => ({
  api: { get: vi.fn(), put: vi.fn(), post: vi.fn(), del: vi.fn() }
}));
import { api } from '$lib/api/client';
const apiGet = api.get;
```

Match the existing import-style in this test file; if it already imports from `$lib/api/client`, reuse that.

- [ ] **Step 2: Run tests to verify they fail**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel/web && npm test -- --run src/lib/player/store 2>&1 | tail -10`

Expected: most/all of the new tests fail because the refresh logic doesn't exist yet.

- [ ] **Step 3: Modify the player store**

In `web/src/lib/player/store.svelte.ts`, find the existing `playRadio` function and:

1. Add a module-level `radioSeedId` state variable
2. Add a `radioRefreshInFlight` flag
3. Modify `playRadio` to set `radioSeedId`
4. Modify `playQueue`, `enqueueTrack`, `enqueueTracks` to clear `radioSeedId` (these are explicit non-radio enqueues)
5. Add an `$effect` watching consumption ratio; trigger refresh when conditions met

Replace the existing `playRadio` and the surrounding state declarations:

```ts
let _queue    = $state<TrackRef[]>([]);
let _index    = $state(0);
let _state    = $state<PlayerState>('idle');
let _position = $state(0);
let _duration = $state(0);
let _volume   = $state(readStoredVolume());
let _shuffle  = $state(false);
let _repeat   = $state<RepeatMode>('off');
let _error    = $state<string | null>(null);

// M4c: track when the queue was seeded by a radio call so we can
// auto-refresh at 80% consumption. Cleared when the user enqueues
// from a non-radio source.
let _radioSeedId        = $state<string | null>(null);
let _radioRefreshInFlight = false;
```

Modify `playQueue`, `enqueueTrack`, `enqueueTracks` to clear `_radioSeedId`. Existing code:

```ts
export function playQueue(tracks: TrackRef[], startIndex = 0): void {
  _queue = tracks;
  // ... existing logic ...
}
```

Add `_radioSeedId = null;` as the first line in `playQueue`, `enqueueTrack`, and `enqueueTracks`.

Replace `playRadio`:

```ts
export async function playRadio(seedTrackId: string): Promise<void> {
  const resp = await api.get<RadioResponse>(
    `/api/radio?seed_track=${encodeURIComponent(seedTrackId)}`
  );
  if (resp.tracks.length === 0) return;
  // playQueue clears _radioSeedId; set it back AFTER playQueue finishes.
  playQueue(resp.tracks, 0);
  _radioSeedId = seedTrackId;
}
```

Add the auto-refresh effect. Place after the state declarations (effects are top-level in `.svelte.ts` files):

```ts
$effect(() => {
  if (_radioSeedId === null) return;
  if (_radioRefreshInFlight) return;
  if (_queue.length === 0) return;
  const consumedRatio = (_index + 1) / _queue.length;
  if (consumedRatio < 0.8) return;

  _radioRefreshInFlight = true;
  const seed = _radioSeedId;
  const exclude = _queue.map((t) => t.id).join(',');
  api
    .get<RadioResponse>(
      `/api/radio?seed_track=${encodeURIComponent(seed)}&exclude=${exclude}`
    )
    .then((resp) => {
      // Strip the seed at index 0 (already in our queue) and append the rest.
      const newTracks = resp.tracks.slice(1).filter((t) => t.id !== seed);
      if (newTracks.length > 0) {
        // Append without clearing radio state — this IS a radio refresh.
        _queue = [..._queue, ...newTracks];
      }
    })
    .catch(() => {
      // Swallow; next track-advance can retry.
    })
    .finally(() => {
      _radioRefreshInFlight = false;
    });
});
```

Note: the existing code uses `_queue = [..._queue, ...newTracks]` style (immutable append) consistent with `enqueueTrack`/`enqueueTracks`. We don't call `enqueueTracks` here because it would clear `_radioSeedId`.

- [ ] **Step 4: Run tests to verify they pass**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel/web && npm test -- --run src/lib/player/store 2>&1 | tail -10`

Expected: PASS for all existing tests + 5 new refresh tests.

- [ ] **Step 5: Verify svelte-check + build**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel/web && npm run check 2>&1 | tail -3`

Expected: 0 errors, 0 warnings.

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel/web && npm run build 2>&1 | tail -5`

Expected: adapter-static emits `web/build/`.

- [ ] **Step 6: Commit**

```bash
cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel
git add web/
git commit -m "feat(web): radio queue auto-refreshes at 80% via ?exclude= param"
```

---

## Task 6: Final verification + branch finish

**Files:** none (verification only)

- [ ] **Step 1: Full Go test suite (-short -race)**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && go test -short -race ./...`

Expected: PASS across all 16 packages.

- [ ] **Step 2: Full integration suite**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && MINSTREL_TEST_DATABASE_URL='postgres://minstrel:minstrel@172.22.0.2:5432/minstrel?sslmode=disable' go test -race -p 1 ./...`

Expected: PASS apart from the pre-existing `TestScanner_Integration` flake (CI runs `-short` which skips it).

- [ ] **Step 3: Lint**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && golangci-lint run ./...`

Expected: clean.

- [ ] **Step 4: Coverage check**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && MINSTREL_TEST_DATABASE_URL='postgres://minstrel:minstrel@172.22.0.2:5432/minstrel?sslmode=disable' go test -p 1 -coverprofile=/tmp/cover-m4c.out ./internal/recommendation/... ./internal/api/ && go tool cover -func=/tmp/cover-m4c.out | tail -5`

Expected: `internal/recommendation` ≥ 80% (was 73% pre-M4c); `internal/api/radio.go` should be well-covered by the existing radio tests + 4 new ones.

- [ ] **Step 5: Web verification**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel/web && npm run check && npm test -- --run && npm run build`

Expected: svelte-check 0/0; vitest passes (180 + 5 = 185); build succeeds.

- [ ] **Step 6: Docker smoke**

Run: `cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && docker build -t minstrel:m4c-smoke .`

Expected: container builds.

- [ ] **Step 7: Manual end-to-end gate (closes M4)**

Set up:
1. `docker compose up --build -d minstrel` — pick up new code
2. Wait for M4b's similarity worker to fill `track_similarity` for ≥10 played tracks (≥1 hour of uptime + previously-played tracks, OR seed manually for testing)
3. In SPA: click radio from a played track. Queue should differ noticeably from M3's output.
4. Listen through ~80% of the queue. Observe queue length increases as auto-refresh fires (browser DevTools network tab shows the `/api/radio?seed_track=…&exclude=…` request).
5. `psql -c "SELECT count(*) FROM track_similarity WHERE source = 'listenbrainz'"` shows non-trivial similarity data.
6. Subjectively: radio quality should feel meaningfully better than M3's baseline.

This is the **closing gate for M4**.

- [ ] **Step 8: Update Fable task #347**

After PR opens, mark `in_progress`. After PR merges, mark `done` with the closing summary in the body. Note that #347 closes the M4 milestone.

- [ ] **Step 9: Finishing the branch**

**REQUIRED SUB-SKILL:** Use `superpowers:finishing-a-development-branch` to verify tests, present completion options, and execute the user's choice.

Per established cadence: this slice will land as a single-purpose PR. After merge, M4 milestone is fully closed; M5 (Lidarr quarantine + suggested-additions for tracks not in library) becomes the natural next milestone.

---

## Self-Review

**Spec coverage:**
- §3 architecture overview → Tasks 1, 3, 4, 5 ✓
- §4 candidate pool SQL → Task 1 ✓
- §5 Score() formula extension → Task 2 ✓
- §6 Go-side wiring → Tasks 3, 4 ✓
- §7 frontend queue refresh → Task 5 ✓
- §8 test plan → embedded across Tasks 2-5; verified in Task 6 ✓
- §9 decisions ledger → all 7 baked into the plan defaults ✓
- §10 backwards compatibility → preserved by zero-default new fields + LoadCandidates retained ✓

No gaps.

**Placeholder scan:** No "TBD"/"TODO" content. The "use whatever sqlc emits at make generate time" guidance in Task 3 is a known sqlc-specific instruction, not a placeholder.

**Type consistency:**
- `ScoringInputs.SimilarityScore` and `ScoringWeights.SimilarityWeight` defined in Task 2; consumed in Tasks 3 and 4.
- `CandidateSourceLimits` defined in Task 3; consumed in Task 4.
- `LoadCandidatesFromSimilarity` signature matches across Tasks 3 and 4.
- `parseExcludeParam` signature consistent with `[]pgtype.UUID` return type.
- Frontend: `_radioSeedId`, `_radioRefreshInFlight` declared at the top of Task 5 step 3; effect references them; `playRadio`/`playQueue`/etc. mutate them consistently.
- sqlc-generated `LoadRadioCandidatesV2Params` field names: deferred to implementation time (sqlc's auto-naming is positional unless column hints help; the Task 3 code uses `Column3..Column9` placeholders the implementer adjusts after `make generate`).