S10.6 — Recently Played (frecency)

[ramith]

S10.6 — Recently Played (frecency)

Reworks the S10.2 History tab into an all-time, per-track, frecency-ranked "Recently Played" view (US-PLAY-10). Each track appears once with a play count, ordered so recency outweighs raw count — the duplicate-row-on-replay bug is gone by construction.

Design + full expert/Fool review trail: recently-played-frecency-design.md (merged in #56; §8 carries the research-grounded resolutions).

What shipped (3 chunks)

• Store (schema v4): frecency_score (decayed-play accumulator) + frecency_rank (indexed projected read key) + idx_tracks_frecency_rank. Write is a read-modify-write in one txn: score = prev·2^(−max(0,now−lp)/H) + 1; rank = now + (H/ln2)·ln(score); H = 7 days. Read: WHERE play_count>0 ORDER BY frecency_rank DESC, id DESC — index-driven, no now, no temp b-tree.
• ≥60% play detection: pure PlaybackQueueKit.PlayThroughTracker — counts once per play-through at min(60%·duration, 240s) with a ≥30s floor. Accrues suspend-stopping monotonic playback time every tick (immune to seeks/stalls/sleep/clock-skew); the four completion sites are gated (no unconditional count).
• UX: "Recently Played" tab, RecentlyPlayedRow (artwork + title + "N plays · «time ago»" cue + now-playing ▶), tap = play-now; refreshes on a post-commit playCountRevision. The in-memory session log is deleted.

Research-grounded design (Last.fm scrobble rule · Firefox/Mozilla-Places frecency · fre)

• Firefox's projected-rank trick makes the sort indexable (no filesort, no read-time decay) — proven equivalent to current frecency 2^((rank−t)/H) analytically, numerically (0 mismatches / 200 now × 400 rows), and by EXPLAIN on 10k rows.
• Last.fm's playback-time measure + >30s floor → the monotonic ≥60% rule.

Review & QA (the bar, not just the gate)

• architect-reviewer + swift-expert + qa-expert + two Fool passes across the design; the pre-implementation Fool found 10 issues, all resolved or accepted.
• qa-expert break-it on the real code found + fixed a HIGH race (deferred tracker reset counting the outgoing track against the newly-selected one on a manual switch) + a LOW display clamp; it confirmed the gapless-seam ordering, migration path, refresh race, and Swift-6 isolation safe.
• Gate: make strict-gate PASSED — 0 lint, clang-tidy + periphery clean, 144 swift tests (incl. 12 PlayThroughTracker cases), VerifyLibraryStore 114/114 (+8 new FR checks: first-play, decay, burst-vs-spread, recency-outweighs-count, never-played-excluded, rank≡current-frecency equivalence, backward-clock-clamp, indexed-read), leak-check clean. Founder by-ear ✓.

Notes

• Schema v4 resets play counts once (delete-rebuild posture, founder D9); the read is NULL-tolerant (NULLs sort last) so it's robust on a non-wiped store too.
• H is baked into stored ranks (changing it later needs a rank recompute). S10.6 is an enhancement — not an R1 gate.

🤖 Generated with Claude Code