fix(bot): ground autoplay on seed similarity + genre-condition scoring

[LucasSantana-Dev]

Problem

Autoplay drifts to mainstream/unrelated music — reported symptom: two Prince tracks in a row, then a jump to Drake.

Root cause (verified in code + prod container logs):

1. Genre guard fails open. The scorer's cross-genre veto and soft genre penalty both require Last.fm/Spotify tags. With no Last.fm link and no/quota-exhausted Spotify token, sessionGenreFamilies/currentTrackTags are empty → both defenses are skipped.
2. spotify preferred +0.4 was the single largest, genre-blind term — any Spotify track (incl. mainstream Drake) got it and outranked more-related candidates.
3. Spotify /recommendations is deprecated for this app → the "primary" recommender returns little.
4. The Last.fm collector is entirely user-link-gated — for an unlinked session the pool collapses to genre-top-tracks (mainstream).

Fix (ADR decisions/2026-06-07-autoplay-seed-similarity-spine.md)

A — Seed-similarity spine. New seedSimilarityCollector grounds autoplay on Last.fm track.getSimilar for the currently-playing track, independent of user linking. Runs as a primary source in the replenisher. Guardrails: 2s timeout + ~1h per-seed cache + cap 10; empty/timeout falls through (never stalls). SEED_SIMILAR is a distinct RecommendationSource (enum + migration) so per-source acceptance telemetry can measure the spine.

B — Genre-condition the scoring. spotify preferred is now full only when the candidate overlaps the session family, half when its genre is unknown, none on a known cross-family candidate. The genre guard fails closed for strong-family sessions (rap/rock/latin) when a candidate is untagged (penalty, not hard reject; relaxed in skip storms). Session family is inferred from history (sessionGenreFamilies), so an untagged current track still carries the session's genre.

C (replace the broad fallback's genre-top-tracks with seed-artist-similar) is intentionally deferred — a fast-follow only if telemetry shows residual drift post-deploy (see ADR "Revisit when").

Tests

• New seedSimilarityCollector.spec.ts (7 cases): grounds on current track, match weighting (0..1 with 0.5× floor), disliked-skip, never-stall on fetch reject.
• New scorer cases (approach B): full/half/no spotify boost by genre overlap, fail-closed on untagged strong-family, no false-positive on non-strong session.
• Full packages/bot/src/utils/music/autoplay/ suite green (256 tests); bot typecheck clean.

Notes

• Surfaced a pre-existing sibling bug while here: lastFmSeeder.ts scores lastfm-similar with * (s.match / 100) but match is already 0..1 — crushes those scores ~100×. Filed as fix(bot): lastfm-similar score crushed ~100x by match/100 (match is 0..1, not 0..100) #1267 (not fixed here to keep this change scoped; the new spine scores match correctly).

Closes the Prince→Drake drift report.

---

Summary by cubic

Grounds autoplay on Last.fm seed similarity and tightens genre-aware scoring to stop mainstream drift without risking stalls. The seed-similar spine now always runs in the replenisher when a requester is known and is tracked separately.

• New Features

  • Add seedSimilarityCollector using Last.fm track.getSimilar for the current track; 2s timeout, ~1h per-seed cache with proper eviction, cap 10; not link-gated; runs before the user-linked Last.fm collector and no longer early-outs on pool size; tracked via SEED_SIMILAR (Prisma enum added).

• Bug Fixes

  • Make Spotify “preferred” boost genre-conditional: full on family overlap, half when genre unknown, none on cross-family.
  • Fail closed on untagged candidates in strong-family sessions (rap/rock/latin) via a penalty, using sessionGenreFamilies so untagged seeds still carry session genre.
  • Ensure the replenisher invokes the seed-similar spine (called/not-called tests added); ADR corrected to reference track.getSimilar.

^{Written for commit b699ca0. Summary will update on new commits.}

Summary by CodeRabbit

• New Features

  • Added a "seed-similar" recommendation spine to seed autoplay from the currently playing track and keep fallbacks on-genre.
  • Autoplay now prefers artist-similarity plus a stronger genre-family guard to reduce genre drift and conditionally apply source boosts.

• Documentation

  • New ADR describing the autoplay strategy and non-stalling fallthrough behavior.

• Tests

  • Expanded tests covering genre-guard behavior, conditional boosts, and seed-similar collection.

• Chores

  • Persisted new recommendation source in schema/migration.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
lucky	Ready	Preview, Comment	Jun 8, 2026 12:09am

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5ae0dc89-371f-4b80-8758-e8db7cbda658

📥 Commits

Reviewing files that changed from the base of the PR and between b2f8c14 and b699ca0.

📒 Files selected for processing (3)

• decisions/2026-06-07-autoplay-seed-similarity-spine.md
• packages/bot/src/utils/music/autoplay/replenisher.spec.ts
• packages/bot/src/utils/music/autoplay/seedSimilarityCollector.ts

✅ Files skipped from review due to trivial changes (1)

• decisions/2026-06-07-autoplay-seed-similarity-spine.md

📜 Recent review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (9)

• GitHub Check: Test — frontend
• GitHub Check: Checks
• GitHub Check: Test — backend
• GitHub Check: Test — bot
• GitHub Check: quality / Lint (lint)
• GitHub Check: quality / SAST (CodeQL) (javascript-typescript)
• GitHub Check: Build — frontend
• GitHub Check: Build — bot
• GitHub Check: Build — backend

🔇 Additional comments (7)

packages/bot/src/utils/music/autoplay/seedSimilarityCollector.ts (3)

64-72: LGTM!

---

113-118: LGTM!

---

154-158: LGTM!

packages/bot/src/utils/music/autoplay/replenisher.spec.ts (4)

78-80: LGTM!

---

184-188: LGTM!

---

378-391: LGTM!

---

393-405: LGTM!

---

📝 Walkthrough

Walkthrough

Introduces ADR and code to add a Last.fm seed-similarity candidate spine (with cache/timeout), a session-family fail-closed genre guard that conditions the Spotify-preferred boost, schema/type changes for SEED_SIMILAR, replenisher wiring to collect seed-similar candidates, and tests covering the new behaviors.

Changes

Autoplay seed-similarity and genre-aware scoring

Layer / File(s)	Summary
ADR: autoplay seed-similarity and fail-closed genre guard decisions/2026-06-07-autoplay-seed-similarity-spine.md	Decision record documenting drift, prescribing a Last.fm seed-similarity backbone (with timeout/caching/caps), a fail-closed session-family genre guard, optional fallback changes, rejected alternatives, and telemetry thresholds.
Schema and type updates for seed-similar source prisma/schema.prisma, prisma/migrations/..., packages/bot/src/utils/music/autoplay/recommendationBasis.ts, packages/bot/src/utils/music/autoplay/recommendationSourceMapping.ts	Adds SEED_SIMILAR to Prisma enum and bot RecommendationSource; updates serializeBasis label mapping and preserves signal deduplication/formatting.
Seed-similarity candidate collector with Last.fm sourcing packages/bot/src/utils/music/autoplay/seedSimilarityCollector.ts, packages/bot/src/utils/music/autoplay/seedSimilarityCollector.spec.ts	Adds fetchSeedSimilar (cache + 2s timeout + eviction) and collectSeedSimilarCandidates which searches Last.fm per similar item, filters, scores (match-weight + seed boost, skip disliked), upserts into shared candidates map, and logs summaries; comprehensive tests validate early exits, grounding, scoring floors/boosts, dislike skipping, and error resilience.
Genre-aware fail-closed scoring with conditional Spotify boost packages/bot/src/utils/music/autoplay/candidateScorer.ts, packages/bot/src/utils/music/autoplay/candidateScorer.spec.ts	Defines STRONG_GENRE_FAMILIES, computes referenceFamilies from session or current-track tags, applies demotion/signal for untagged candidates in strong-family sessions (outside skip-storms), and conditions the Spotify-preferred boost (full/none/half) based on family overlap; tests cover boost permutations and drift signaling.
Wiring seed-similar collection into replenishment pipeline packages/bot/src/utils/music/autoplay/replenisher.ts, packages/bot/src/utils/music/autoplay/replenisher.spec.ts	Imports and conditionally invokes collectSeedSimilarCandidates when requestedBy exists, tracks sourcesCounts.seedSimilar, and adds tests asserting invocation behavior.

Sequence Diagram

sequenceDiagram
  participant Replenisher
  participant Collector as collectSeedSimilarCandidates
  participant Fetcher as fetchSeedSimilar
  participant LastFm as Last.fm API
  participant Search as searchLastFmQuery
  participant Scorer as calculateRecommendationScore
  participant Candidates as candidates Map
  Replenisher->>Collector: invoke with requestedBy, currentTrack
  Collector->>Fetcher: request cached similar for seed (artist::title)
  Fetcher->>LastFm: track.getSimilar (2s timeout)
  LastFm-->>Fetcher: similar tracks
  loop per similar track
    Collector->>Search: searchLastFmQuery(query)
    Search-->>Collector: candidate tracks
    Collector->>Scorer: compute base score (skip novelty)
    Scorer-->>Collector: base score
    Collector->>Candidates: upsert with seed boost + match weighting
  end
  Collector-->>Replenisher: debug log (counts)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related issues

• fix(bot): lastfm-similar score crushed ~100x by match/100 (match is 0..1, not 0..100) #1267: Related — addresses Last.fm match weighting and seed-similar scoring behavior that overlaps with the new collector's match handling.

Possibly related PRs

• LucasSantana-Dev/Lucky#567: Both add seed-similar generation via Last.fm track.getSimilar and integrate similar-track candidates.
• LucasSantana-Dev/Lucky#1020: Overlaps in tests and spotify-preferred/genre-family scoring adjustments in candidateScorer.spec.ts.
• LucasSantana-Dev/Lucky#782: Related changes to session-family genre logic and scoring pipeline that this PR extends with a seed-similar spine.

Suggested labels

enhancement, bot, database, size/l

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 27.27% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the two main changes: implementing seed-similarity grounding for autoplay and applying genre conditioning to the scoring logic, which align directly with the PR's core objectives.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/autoplay-seed-similarity

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Failed to generate code suggestions for PR

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (4)

packages/bot/src/utils/music/autoplay/seedSimilarityCollector.ts (3)

109-111: 💤 Low value

Remove redundant slice operation.

Line 109 slices similar to MAX_SEED_SIMILAR, but fetchSeedSimilar already passes MAX_SEED_SIMILAR as the limit parameter to getSimilarTracks (line 56), so the API response is already capped. The slice is harmless but unnecessary.

♻️ Optional cleanup

-    for (const s of similar.slice(0, MAX_SEED_SIMILAR)) {
+    for (const s of similar) {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/bot/src/utils/music/autoplay/seedSimilarityCollector.ts` around
lines 109 - 111, The for-loop over similar unnecessarily calls similar.slice(0,
MAX_SEED_SIMILAR); remove the slice and iterate directly over the similar array
instead (for (const s of similar) { ... }) since fetchSeedSimilar already limits
results via getSimilarTracks with MAX_SEED_SIMILAR; update the loop in
seedSimilarityCollector where similar is consumed (referencing the
variables/functions similar, MAX_SEED_SIMILAR, AUTOPLAY_BUFFER_SIZE,
fetchSeedSimilar, getSimilarTracks, and cleanSearchQuery) and keep the existing
early-break when candidates.size >= AUTOPLAY_BUFFER_SIZE.

---

146-149: 💤 Low value

Clarify match-weight floor in comment.

The comment says "never crush below 0.5×" but the formula 0.5 + 0.5 * match produces a weight in [0.5, 1.0], not a 0.5× multiplier. Consider rewording to "never weight below 0.5" for precision.

📝 Clearer wording

             // Last.fm returns `match` on a 0..1 scale. Weight by it but keep
-            // seed-similar competitive — never crush below 0.5× even on a weak
-            // match, so the spine still grounds a thin pool.
+            // seed-similar competitive — floor weight at 0.5 even on a weak
+            // match (0.0), so the spine still grounds a thin pool.
             const matchWeight = 0.5 + 0.5 * Math.min(Math.max(s.match, 0), 1)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/bot/src/utils/music/autoplay/seedSimilarityCollector.ts` around
lines 146 - 149, The comment incorrectly describes matchWeight as a "0.5×"
multiplier; update the comment near the matchWeight calculation in
seedSimilarityCollector.ts (the line that defines const matchWeight = 0.5 + 0.5
* Math.min(Math.max(s.match, 0), 1)) to say that the weight is clamped to the
range [0.5, 1.0] or "never weighted below 0.5" (not "0.5×"), so it precisely
matches the formula and clarifies the intent.

---

64-73: ⚡ Quick win

Edge case: cache eviction with expired entries may undercount.

When updating an expired cache entry that is not the oldest entry, the current logic may leave the cache under capacity:

1. Cache contains [A, B, C] at max size
2. Request updates B (which is expired)
3. Line 65 detects size ≥ max, deletes A
4. Line 69 Map.set(key, ...) updates B's value but B remains in its original position (Maps don't reorder on update)
5. Cache is now [B, C] (size 2), losing one slot

This is a minor efficiency issue, not a correctness bug, and only occurs when the cache is full and an expired non-oldest entry is refreshed.

🔧 Suggested fix

     if (tracks.length > 0) {
+        // Remove existing entry first (if expired) so size check is accurate
+        similarCache.delete(key)
         if (similarCache.size >= SIMILAR_CACHE_MAX) {
             const oldest = similarCache.keys().next().value
             if (oldest) similarCache.delete(oldest)
         }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/bot/src/utils/music/autoplay/seedSimilarityCollector.ts` around
lines 64 - 73, The cache eviction can undercount when refreshing an expired
non-oldest entry; update similarCache handling in seedSimilarityCollector.ts so
you first prune expired entries (check each entry.expiresAt against now and
delete expired ones) and/or if you are about to refresh an existing key, remove
it first (if (similarCache.has(key)) similarCache.delete(key)) before checking
SIMILAR_CACHE_MAX and calling similarCache.set(key, { tracks, expiresAt }),
ensuring Map order is correct and eviction uses current live size.

packages/bot/src/utils/music/autoplay/recommendationSourceMapping.ts (1)

35-38: 💤 Low value

Consider wrapping the exhaustiveness check in a block to satisfy the linter.

The const _exhaustive declaration triggers a Biome lint rule because switch cases don't create block scopes. While this is a standard TypeScript exhaustiveness pattern and the default case is never reached in practice, wrapping it in braces would silence the warning.

♻️ Proposed fix

         case 'genre-tag':
             return PrismaRecommendationSource.GENRE_TAG
-        default:
-            const _exhaustive: never = src
-            return _exhaustive
+        default: {
+            const _exhaustive: never = src
+            return _exhaustive
+        }
     }
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/bot/src/utils/music/autoplay/recommendationSourceMapping.ts` around
lines 35 - 38, Wrap the default branch of the switch in
recommendationSourceMapping's switch (where the const _exhaustive: never = src
is declared) inside a block (i.e., add { ... } around the default case body) so
the const is scoped to that block and the Biome lint rule is satisfied; keep the
same never-assignment pattern and return the _exhaustive variable from inside
that block.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@decisions/2026-06-07-autoplay-seed-similarity-spine.md`:
- Around line 35-38: The ADR currently names Last.fm artist.getSimilar but the
implementation and helpers use track.getSimilar (see getSimilarTracks(artist,
title, limit) and calls in seedSimilarityCollector and lastFmApi); update the
ADR text to reference Last.fm track.getSimilar (and mention it uses the
currently-playing track as the seed) and adjust the description of the source
boost ("seed-similar") accordingly so the document matches the implemented
behavior.

---

Nitpick comments:
In `@packages/bot/src/utils/music/autoplay/recommendationSourceMapping.ts`:
- Around line 35-38: Wrap the default branch of the switch in
recommendationSourceMapping's switch (where the const _exhaustive: never = src
is declared) inside a block (i.e., add { ... } around the default case body) so
the const is scoped to that block and the Biome lint rule is satisfied; keep the
same never-assignment pattern and return the _exhaustive variable from inside
that block.

In `@packages/bot/src/utils/music/autoplay/seedSimilarityCollector.ts`:
- Around line 109-111: The for-loop over similar unnecessarily calls
similar.slice(0, MAX_SEED_SIMILAR); remove the slice and iterate directly over
the similar array instead (for (const s of similar) { ... }) since
fetchSeedSimilar already limits results via getSimilarTracks with
MAX_SEED_SIMILAR; update the loop in seedSimilarityCollector where similar is
consumed (referencing the variables/functions similar, MAX_SEED_SIMILAR,
AUTOPLAY_BUFFER_SIZE, fetchSeedSimilar, getSimilarTracks, and cleanSearchQuery)
and keep the existing early-break when candidates.size >= AUTOPLAY_BUFFER_SIZE.
- Around line 146-149: The comment incorrectly describes matchWeight as a "0.5×"
multiplier; update the comment near the matchWeight calculation in
seedSimilarityCollector.ts (the line that defines const matchWeight = 0.5 + 0.5
* Math.min(Math.max(s.match, 0), 1)) to say that the weight is clamped to the
range [0.5, 1.0] or "never weighted below 0.5" (not "0.5×"), so it precisely
matches the formula and clarifies the intent.
- Around line 64-73: The cache eviction can undercount when refreshing an
expired non-oldest entry; update similarCache handling in
seedSimilarityCollector.ts so you first prune expired entries (check each
entry.expiresAt against now and delete expired ones) and/or if you are about to
refresh an existing key, remove it first (if (similarCache.has(key))
similarCache.delete(key)) before checking SIMILAR_CACHE_MAX and calling
similarCache.set(key, { tracks, expiresAt }), ensuring Map order is correct and
eviction uses current live size.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 18bbafbc-0118-46b0-aded-1b85f48fe36f

📥 Commits

Reviewing files that changed from the base of the PR and between 7180579 and b2f8c14.

📒 Files selected for processing (10)

• decisions/2026-06-07-autoplay-seed-similarity-spine.md
• packages/bot/src/utils/music/autoplay/candidateScorer.spec.ts
• packages/bot/src/utils/music/autoplay/candidateScorer.ts
• packages/bot/src/utils/music/autoplay/recommendationBasis.ts
• packages/bot/src/utils/music/autoplay/recommendationSourceMapping.ts
• packages/bot/src/utils/music/autoplay/replenisher.ts
• packages/bot/src/utils/music/autoplay/seedSimilarityCollector.spec.ts
• packages/bot/src/utils/music/autoplay/seedSimilarityCollector.ts
• prisma/migrations/20260607000000_add_seed_similar_recommendation_source/migration.sql
• prisma/schema.prisma

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (9)

• GitHub Check: Test — backend
• GitHub Check: Test — bot
• GitHub Check: Checks
• GitHub Check: Test — frontend
• GitHub Check: quality / Dead code (knip)
• GitHub Check: quality / SAST (CodeQL) (javascript-typescript)
• GitHub Check: Build — backend
• GitHub Check: Build — frontend
• GitHub Check: Build — bot

🧰 Additional context used

🪛 Biome (2.4.16)

packages/bot/src/utils/music/autoplay/recommendationSourceMapping.ts

[error] 36-36: Other switch clauses can erroneously access this declaration.
Wrap the declaration in a block to restrict its access to the switch clause.

(lint/correctness/noSwitchDeclarations)

🔇 Additional comments (16)

prisma/migrations/20260607000000_add_seed_similar_recommendation_source/migration.sql (1)

1-11: LGTM!

packages/bot/src/utils/music/autoplay/seedSimilarityCollector.ts (1)

42-75: LGTM!

Also applies to: 90-173

packages/bot/src/utils/music/autoplay/seedSimilarityCollector.spec.ts (1)

1-214: LGTM!

packages/bot/src/utils/music/autoplay/replenisher.ts (1)

36-36: LGTM!

Also applies to: 101-101, 336-357

prisma/schema.prisma (1)

461-470: LGTM!

packages/bot/src/utils/music/autoplay/recommendationBasis.ts (2)

6-14: LGTM!

---

58-84: LGTM!

packages/bot/src/utils/music/autoplay/recommendationSourceMapping.ts (1)

18-34: LGTM!

packages/bot/src/utils/music/autoplay/candidateScorer.ts (5)

44-51: LGTM!

---

209-219: LGTM!

---

268-286: LGTM!

---

288-298: LGTM!

---

440-469: LGTM!

packages/bot/src/utils/music/autoplay/candidateScorer.spec.ts (3)

199-271: LGTM!

---

273-288: LGTM!

---

290-305: LGTM!

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
89.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud