541 Commits

Include renames

Author	SHA1	Message	Date
bvandeusenandClaude Opus 5	4ce47397a9	fix(recommendation): a nil LibrarySize must degrade, not panic ... Fixes the integration failure from 72115484: a SIGSEGV inside handleRadio took down TestHandleRadio_ColdStart_OnlySeedReturned. recommendation.(*LibrarySize).Get(0x0, ...) library_scale.go:146 api.(*handlers).handleRadio(...) radio.go:95 internal/api builds its handlers struct directly in a dozen tests, none of which know about every field, so librarySize arrives nil there. Get took l.mu.Lock() straight off the nil receiver. The shape of the bug is what matters more than the nil check. This value's entire contract is that it degrades — an errored count keeps the last known number, a never-counted cache returns 0, and 0 scales to the base limits, i.e. today's behaviour. A pool-sizing HINT then turned a request into a crash, which is the precise opposite of that. A nil receiver is now VALID and means "no cache": the count still runs, it is just not memoised. Correct-but-uncached rather than zero, so a wiring miss in production would cost a query per request, not silently unscale every pool — a performance bug is findable, a quietly-wrong pool is not. Patching the test constructors was the alternative and is worse: a dozen call sites, and the next test to build a handlers literal reintroduces it. Guarded with the nil path exercised directly, including that it counts again rather than memoising, and still returns 0 on a failed count. The old shape fails it by panicking. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SQ31KQpYbStyK5y58UmPLH	2026-09-10 23:29:35 -04:00
bvandeusenandClaude Opus 5	721154847e	fix(recommendation): size the candidate pool to the library ... Operator, 2026-09-10: "is the pool that we draw from somehow scaled to the amount of music in the library... my earlier understanding of the tuning and work may have been skewed by what was in my library." It was not. DefaultCandidateSourceLimits returns what its own comment calls "the v1 hardcoded constants per spec" — ~170 candidates for a 500-track library and a 100,000-track one alike. The pool therefore samples a shrinking FRACTION of a growing collection: 17% of 1,000 tracks, 1.7% of 10,000, 0.17% of 100,000. RandomFill, whose whole job is exploration, becomes a thinner and noisier slice at exactly the moment a library gets more diverse — which is the "starting to feel weird" being reported. 1,000 tracks -> pool 170 (unchanged) 5,000 -> pool 170 (unchanged) 20,000 -> pool 280 80,000 -> pool 500 (ceiling) THE SCALING IS PER-ARM, and that is the substance rather than a refinement. A limit only matters if there are rows for it to cut off, so what an arm is BOUNDED BY decides whether library size can help it. LBSimilar, SimilarArtist, TagOverlap and RandomFill grow: they are bounded by similarity/tag data and by the library itself. LikesOverlap, UserCoplay and TasteOverlap do not: they are bounded by the user's likes, the instance's co-play graph and the taste profile, none of which grow when the library does. Raising those would sample more of a set that did not change — churn, not reach. It also keeps this from inflating the sim_score-0 share, since TasteOverlap is one of the two zero-similarity arms. sqrt, not linear: linear would put a 100,000-track library at a 3,400-candidate pool, long past where more candidates improve the answer. A 4x ceiling bounds it at ~500. Never shrinks an arm. The base limits are a floor, and #3889 makes that load-bearing rather than tidy — shrinking an arm ordered by unseeded random() changes pool membership between same-day rebuilds. Library size comes from a TTL-cached count reusing CountTracksMatching with an empty pattern (rule 28 — a new query would need sqlc regeneration, which is blocked). The ILIKE defeats every index, so it is a full scan and must not run per request. It degrades rather than fails: an error keeps the last known value, a never-counted cache returns 0, and 0 scales to the base limits — today's behaviour exactly. Nothing about sizing a pool justifies failing the request it is sizing. Bounded by a 3s deadline (rule 156), and a failed refresh does not stamp the clock, so a blip cannot pin a stale value for the whole TTL. THE REFERENCE IS ASSUMED, NOT MEASURED. libraryScaleReference = 5000 is where growth starts, and the size the v1 constants were really tuned against is unrecorded. #3879 should replace it; until then that constant is the one thing to change. Deliberately conservative: below it nothing scales at all, so no existing install changes behaviour. Falsification caught a weak guard: the sqrt-vs-linear assertion was written at SIXTEEN times the reference, where linear has already been clamped by the ceiling and both curves land on 4x. It proved nothing. Moved to four times the reference, below the ceiling for both, where sqrt gives 2x and linear would give 4x. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SQ31KQpYbStyK5y58UmPLH	2026-09-10 23:23:04 -04:00
bvandeusenandClaude Opus 5	633d4f591f	fix(radio): cap any one artist's share of a radio session ... Operator, 2026-09-10: started radio from a song and "literally all of the songs in the playlist after that were from a single artist which was not expected." There was no per-artist cap anywhere in the radio path. radio.go built the pool and handed it straight to Shuffle, which scores, sorts and takes the top N — nothing between those steps bounded any artist's share, so a pool dominated by one artist produced an output dominated by it. The asymmetry was the tell: discover.go, you_might_like.go and home.go all cap; radio never got one. With the fixture that reproduces it — 20 liked tracks by one artist plus 10 by ten others — the old path returns 10 tracks from 1 artist. It now returns 10 from 8. TWO PASSES, and that is the whole design. A hard cap was the easy mistake: radio asks for 50 tracks by default and 200 at most, so capping at three per artist over a concentrated pool would hand back a six-track "radio". Pass one takes candidates that fit under the caps; pass two fills any remaining slots from those it skipped, still in score order. The result always holds min(limit, len(candidates)) — the caps change WHICH tracks are picked, never HOW MANY. Rule 131's principle past the system mixes it was written for. The caps SCALE with the requested length rather than being a constant. Three-per-artist is a sensible 12% of a 25-track mix and an absurd 1.5% of a 200-track radio, where every selection would sit in the relaxation path and the cap would be decorative. RadioDiversityCaps holds the system mixes' proportion at any length: 3/2 at 25, 6/4 at 50, 24/16 at 200, with floors so a very short radio is not capped down to one track per artist. A BOUND, NOT AN EXCLUSION — the operator asked for the opposite of removal: "again it should be able to add songs from the same artist." The dominant artist still appears, just not exclusively. Guarded, because the tempting wrong fix is the filter songs-like used to carry. Shuffle grew the parameter rather than gaining a capped twin: radio is its only production caller, so a second function would have left the original dead (rule 22). Falsified against each named regression: uncapped gives 10/10 to one artist; a hard cap returns 3 of 10 on a single-artist pool; a cap-as-exclusion drops the artist entirely; a fixed cap stays 3 where the scaled one reaches 24. Caught while writing the guards: the artist-key constant was hand-written hex and wrong — the fixture's artist UUID carries 0001 in its fourth group, so the lookup missed and the assertion measured nothing. Derived from the same construction the fixture uses now. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SQ31KQpYbStyK5y58UmPLH	2026-09-10 22:14:42 -04:00
bvandeusenandClaude Opus 5	f5dd4462de	test(playlists): the same-artist guard needed a fixture that has same artists ... Fixes the integration failure from 31190657. The test was wrong, not the code: it could not have passed whatever produceSeedMixes did. seedActiveLibrary builds its tracks through seedTrack, whose own comment says "artist and album are not deduplicated across calls (mbid-less upsert)". So every track gets a fresh artist row despite sharing a name — 4 artists x 5 tracks is really 20 artists with one track each. A seed artist's only track IS the seed, which is excluded from its own mix, so "does this mix contain a track by its seed artist" was structurally answerable only as no. That is the failure mode worth naming: the assertion was measuring the fixture, not the behaviour, and it reported the behaviour as broken. seedSharedArtistLibrary upserts each artist ONCE and reuses the id across its tracks, so a seed artist genuinely owns five others. Albums are still not deduplicated, which suits this test — the per-album cap never binds, so the per-artist cap (3) is unambiguously what is under test. Noted in the fixture, because "tidying" the album titles into something shared would silently change which cap the assertion measures. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SQ31KQpYbStyK5y58UmPLH	2026-09-10 21:25:49 -04:00
bvandeusenandClaude Opus 5	31190657d8	feat(recommendation): Songs-like can include the seed artist's own music ... Operator, 2026-09-10: "it should also be able to include music from the same artist." Completes #3881 — the weights and pool landed in f367eeaa; this is the eligibility half. produceSeedMixes filtered the seed artist out entirely: // "Songs like X" excludes X's own songs. if !pgtypeUUIDEqual(c.Track.ArtistID, artistID) { ... } That reads as obviously right and is not. The seed is a TRACK — the artist's top-played one — and the tracks most likely to sound like it are usually the rest of that artist's catalogue. The filter threw away the seed's nearest neighbours, then reached FURTHER OUT to replace them. On the one surface whose job is staying in a neighbourhood, that is backwards, and it worked against the coherence tuning rather than with it. Domination is bounded by the cap instead of by exclusion, which is the distinction that makes this safe rather than a new problem: capCandidatesByAlbumAndArtist already allows at most 3 tracks per artist in a 25-track mix, so the seed artist gets 12% at most — a presence, not a takeover. Without that bound this would just be the radio failure (#3882) arriving on a different surface. The seed track itself still cannot appear; it is passed to LoadCandidatesFromSimilarity as an exclusion. Guarded end-to-end rather than by reading the source, for two reasons: the check has to survive the filter returning in a different shape, and an absence check would now match the comment that explains why the filter is gone — rule 167's prose trap exactly. The test asserts both directions, that at least one mix contains its seed artist and that none exceeds the cap. Its falsification is by construction rather than by execution: under the previous code every mix's own-artist count was necessarily zero, so the assertion could not have passed. Running it needs Postgres, which is the integration lane's job. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SQ31KQpYbStyK5y58UmPLH	2026-09-10 21:13:32 -04:00
bvandeusenandClaude Opus 5	ecfa056d4d	fix(recommendation): don't shrink a candidate arm ordered by unseeded random() ... Fixes the integration failure from f367eeaa: "same-day rebuild produced different track lists". Cutting RandomFill 30→10 for Songs-like broke TestBuildSystemPlaylists_DailyNonceDeterminism, and the reason is worth stating because the number is not the bug. `likes_overlap` and `random_fill` end in a bare `ORDER BY random()` with no daily seed (recommendation.sql:118, :161). Such an arm returns a STABLE set only while its LIMIT exceeds the rows eligible for it — then it returns all of them, and the random order stops mattering because scoreAndSortCandidates sorts by track id before drawing jitter. Below that threshold the arm returns a random SUBSET, and two builds on the same day draw different ones. So the test was green by accident. It seeds ~20 tracks against a default RandomFill of 30; the limit exceeded the library, so the arm returned everything. Determinism held for a reason unrelated to the code being right. Which means it does NOT hold in production. Any real library is larger than 30, so same-day rebuilds have been drawing different mixes since that arm was written — invisible, because a mix changing after a refresh looks like a feature. Filed as #3889; the fix is a seeded ordering per (user, day), which needs a .sql change and sqlc regeneration and so cannot land from here. The correction: grow an arm freely, never shrink one whose ordering is unseeded random. LikesOverlap and RandomFill go back to the defaults; TasteOverlap stays halved because it sorts by `tpa.weight DESC, t.id` and is genuinely deterministic. Guarded by a test that names the reasoning, so the next person to trim these has to read why first — and it should be DELETED once #3889 lands rather than worked around. The cost is honest: the seed-independent share of the Songs-like pool falls from 29% to 20% instead of the intended cut. That matters less than it sounds. The pool only biases the draw; the songs_like WEIGHTS are what actually demote sim_score-0 candidates, and they are untouched here — a perfect match still scores 5.00 against an unrelated favourite's 2.00. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SQ31KQpYbStyK5y58UmPLH	2026-09-10 20:59:39 -04:00
bvandeusenandClaude Opus 5	f367eeaa9d	fix(recommendation): Songs-like gets its own profile so it stops wandering ... Operator, 2026-09-10: "when I play it I'm expecting to get a consistent sound and style from the experience... I was getting a seeming wide variety of music from each one when I was hoping to stay in a certain neighborhood." Songs-like shared the `daily_mix` weight profile with For-You, and that sharing WAS the bug. The two surfaces want opposite things: For-You answers "what will they enjoy today" and is supposed to roam; Songs-like answers "what sounds like THIS". Under one profile the broad answer wins. The arithmetic, from the shared weights: unrelated track, liked, not played recently → 1.0 + 2.0 + 1.0 = 4.0 PERFECT similarity match, not liked → 1.0 + 1.5 = 2.5 Liking something outranked sounding like the seed, because LikeBoost (2.0) exceeded SimilarityWeight's whole range (1.5) and TasteWeight (1.5, and seed-INDEPENDENT) matched it outright. Under the new profile the same pair scores 5.00 vs 2.00. Two levers, because either alone leaves the other's failure intact: POOL. Songs-like now takes its own CandidateSourceLimits. The default gave ~29% of candidates a sim_score of literally zero — `taste_overlap` and `random_fill` are both `0.0::float8` in recommendation.sql, seed-independent by construction. Same total pool size; composition shifts to arms that measure distance from the seed, LBSimilar doubled. WEIGHTS. A third profile beside radio and daily_mix, DB-backed and live per rule 25, with the property that similarity's range exceeds the combined range of every seed-independent differentiator — so a closer match cannot be beaten on likes, freshness and taste alone, while tracks within ~0.39 similarity of each other still get ordered by what the user likes. Rule 131 changed the pool design mid-way and for the better. Zeroing the two seed-independent arms was the first instinct and is exactly the vanish-or-nothing shape that rule forbids: a seed with thin ListenBrainz coverage would yield a short mix or none. They are the tier-3 FLOOR — cut hard, never removed — and the weights keep them at the bottom of the ranking rather than out of the pool. "A few tracks further from the seed than we'd like" beats "no playlist". Caught while wiring it: switching only pickTopN's final Score would have been nearly INERT. scoreAndSortCandidates does the selection sort, and the caller caps and truncates in that order — so the playlist would still have been chosen by daily_mix and merely relabelled with songs_like numbers. It now takes the profile as a parameter, and each surface passes its own. Also corrects the daily_mix card's blurb, which claimed Songs-like as one of its surfaces and no longer is. Guards pin behaviour rather than the numbers, since numbers get retuned: that similarity beats an unrelated liked track, that daily_mix still DOESN'T (or the split buys nothing), that the tier-3 floor is non-zero, and that the UI card shows its own values rather than falling back. Each falsified against its named regression first. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SQ31KQpYbStyK5y58UmPLH	2026-09-10 20:51:15 -04:00
bvandeusenandClaude Opus 5	270ad7a71b	fix(ci): tests do not ship, so they must not re-version an artifact ... Completes the pathspec. 17212e9e excluded CI, docs and tooling but left tests in the shipped set, so its own commit re-versioned the image on the strength of a _test.go file. `go build` drops *_test.go outright and the Vite build never imports a .test.ts — neither reaches an image or an APK. Globs over files rather than a directory exclusion, because this repo has no tests/ tree to exclude: Go tests sit inline beside the code they cover (158 files) and the web suite beside its modules (115). Patterns match what exists and nothing speculative — there are no .spec.* files, no __tests__/ directories and no androidTest/ tree. If any appear they re-version until named, which is the harmless direction and the point of a denylist. The guard that matters is not "a test-only commit is inert" — it is that a commit touching a test AND its source still moves the version. `':!internal'` would satisfy every inertness assertion while silently excluding the entire server, which is the stale-version-on-changed-artifact failure this whole derivation exists to prevent. Falsified: drop the Go exclusion and a _test.go commit moves the version; drop the web one and a .test.ts does; replace the globs with `':!internal'` and the source-alongside-test case breaks. That last check failed first time, on a bug in the FIXTURE rather than the derivation, and it is worth recording because it makes a test pass for the wrong reason. Both commit helpers wrote the constant "x\n", so re-writing a file with identical bytes recorded NOTHING — the "source and test together" commit actually contained only the test, and the assertion was quietly checking the case it was meant to contrast against. Content is now derived from the commit's epoch, and the test asserts HEAD really contains both paths before drawing any conclusion from it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SQ31KQpYbStyK5y58UmPLH	2026-09-10 18:21:12 -04:00
bvandeusenandClaude Opus 5	17212e9eb4	fix(ci): version derives from the shipped set; untrack an 18MB binary ... Three build-hygiene fixes that turned up while explaining the pathspec. **version.sh derives from what SHIPPED.** It read bare HEAD, so any commit moved the version — including one touching only CI or a README. Rules 148 and 149 both specify the pathspec form. Now a denylist, and the direction is the point: as an allowlist the list must be updated by whoever adds a directory and nothing fails if they don't, so the failure mode is a changed artifact keeping its old version silently on a green run. Inverted, new content counts by default. android/ is deliberately NOT excluded, and that is the subtle part. This repo ships TWO artifacts from ONE derivation: android/ is in no server image, but it is the APK's entire source, and excluding it would stop an Android-only commit from moving the APK's own version — the silent downgrade the versioning rework exists to prevent. So the list is the union: exclude only what ships in neither, and accept that an Android commit also nudges the server's reported version. Over-inclusion across the two, which is the harmless direction. roundtable/roundtable-android each keep tighter lists because they are one-artifact repos; don't copy theirs. **.dockerignore excluded the wrong CI directory.** It named .forgejo/ and .github/, neither of which this repo has. Gitea Actions reads .gitea/, so the one directory that exists was the one not excluded. The "Flutter mobile client" block had also lost its PATTERN when flutter_client/ was deleted, leaving a comment describing an exclusion that was not happening — android/ never took its place, so 4.1MB of Gradle project entered the context and busted the `COPY . .` layer on every Android-only change. bin/ excluded too. **bin/minstrel was tracked** — an 18MB binary last refreshed by a commit about web test mocks, and re-dirtied by every `make build` since. Untracked and ignored; the file stays on disk. Guards are behavioural rather than textual: they build throwaway repos with pinned commit timestamps and run version.sh against them, so they break when the derivation changes rather than when the wording does. Falsified — drop the .gitea exclusion and the CI-only commit moves the version; add an android exclusion and an Android commit stops moving it; exclude everything and a source commit refuses. One honest note on the refusal test: the script already refused an empty result via the downstream date check, so the new explicit check improves the diagnostic ("no commit touches the shipped file set — shallow clone?") and not the safety. The test pins the property, which is defended in depth. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SQ31KQpYbStyK5y58UmPLH	2026-09-10 17:55:36 -04:00
bvandeusenandClaude Opus 5	aeb8781c4e	fix(release): drop version image tags, mint the rollback unit on main ... The image tag map was the inverse of family rules 145 and 147 on every count: it published :vYYYY.MM.DD.HHMM that nobody pinned, published :main that rule 147 says should not exist, and published no commit-addressable image at all — so the rollback unit the rule names did not exist in this repo. A bad main push had nothing to roll back to but the previous release tag, which may be many commits back. The whole map is now: dev → :dev main → :latest + :<sha> tag → :latest A release refreshes the channel and mints nothing else. The tag build rebuilds the SAME SOURCE as main's build minutes earlier, differing only in which APK is baked in, so rule 145's immutability clause applies directly: move the channel tag, never re-push a commit-addressable one. :latest has to move here rather than waiting for the next main push, or the channel would carry the previous release's APK indefinitely — a channel that cannot refresh itself (rule 146). Two consequences that are not optional: The verify job asserted the :<version> image existed. With version tags gone that would fail every release for a tag nothing mints. Re-pointed at the :<sha> image rather than deleted — deleting it is the tempting way to make a failing guard go green, and it earns its keep twice now: it still catches an image push that silently did not happen, and it additionally proves the ordering, since a tag cut on a commit whose main build never completed has no rollback target. The server's self-reported version was the literal string "main" or "dev". That was survivable while :vYYYY.MM.DD.HHMM existed to identify a build; with version tags gone it is the ONLY thing that says which build is running, and two dev images months apart were indistinguishable. It now carries the derived name from ci/version.sh on every lane, with the channel as a sibling field (rule 149) rather than folded into the string. Surfaced at /healthz and beside the version in Settings. Guards added for each arm of the policy, and every one was falsified against the specific regression it names before committing. That caught two real bugs in the guards themselves: stepBody cut at the next `- name:`, which returns an EMPTY body for the last step in a job and made the assertions pass vacuously, and its replacement cut at any blank line followed by indentation, which truncated a step mid-run-block. The helper now refuses an empty body outright. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SQ31KQpYbStyK5y58UmPLH	2026-09-10 15:10:15 -04:00
bvandeusenandClaude Opus 5	88508b536b	fix(release): a non-matching grep must not kill the rebundle step ... The first `main` build after the version rework failed, and the bug was mine. :latest was never moved — "Build and push" was skipped — so nothing reached production, but every subsequent main push would have failed the same way. The runner invokes `shell: bash` as `bash -e -o pipefail`. Under pipefail a command substitution reports the FIRST non-zero status in its pipeline, not the last, so VAR="$(printf ... | grep -oP ... | grep -E '\.apk\.version$' | head -1)" exits non-zero when that grep matches nothing, even though `head` succeeded. With -e the step dies AT THE ASSIGNMENT — before reaching the `if` written to handle exactly the empty case. Which is what happened: v2026.09.09 predates sidecar assets, so its `.apk.version` grep matched nothing and the step aborted instead of falling through to the name-only branch I added in 9f3e0b8c for precisely that release. The transition case was described correctly in that commit message and then not handled in code. The other two assignments carried the same latent hazard and had simply never fired, because a release always has a tag_name and an .apk asset. So the step's documented promise — "degrades to an empty client/ (404 update channel) — never a wrong version — if no release or APK asset can be resolved" — was never actually reachable under pipefail. All three now carry `|| true`. Reproduced under the runner's exact shell before fixing: without `|| true` the script exits 1 with no output at all, proving it never reaches the branch; with it, the fallback runs and emits the name-only sidecar. Guarded, since the graceful degradation depends on this and the failure is invisible until the one release that triggers it: the new test asserts every command-substitution grep in that step ends with `|| true`, and was falsified by removing it from the sidecar line. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SQ31KQpYbStyK5y58UmPLH	2026-09-10 08:37:23 -04:00
bvandeusenandClaude Opus 5	90bb3538c6	feat(release): build a dev channel so testing stops requiring a release ... There was no test channel at all. release.yml ran only on main and tags, so no :dev image existed and no APK was produced outside a release — the only way to get a build onto a phone was to ship one, which made `main` the staging area by default. A push to dev now builds a signed APK, bundles it, and publishes :dev. Signed with the SAME key as release builds, deliberately. A differently signed APK cannot install over the stable app, so anyone moving between channels would have to uninstall and lose their local data. Same key means both directions work. :dev is published ALONE, with no per-commit tag. A rolling channel is rolling by definition; a commit-addressable image for it would be a rollback target nobody ever pulls, kept forever. Recovery on dev is to fix forward, and that is a deliberate trade rather than an omission. The channel is derived from the REF, not the commit, which is why it is computed in the workflow and not in ci/version.sh. The same commit built on dev and on main reports the same version NAME and differs only in the channel field — that separation is the entire point of keeping the three values apart. What this repo deliberately does NOT get: a cross-repo dispatch to refresh the channel when its bundled APK is rebuilt. That mechanism exists elsewhere in the family because the app and server live in separate repos, and a channel that can only be refreshed by an unrelated commit is not a channel. Minstrel is a monorepo — one push builds the APK and the image in the same run from the same commit, so the channel cannot go stale against its own artifact. The requirement is met structurally; copying the mechanism would add a moving part to fix a problem that does not exist here. Two guards, for the two ways this wiring can fail quietly: A dev push must never move :latest. That would ship untested code to every stable operator on their next pull, with the build green and the image perfectly valid — just the wrong audience. Nothing else in the suite would notice. The two bundling paths must stay mutually exclusive. The rebundle step is now gated to main specifically, not to "not a tag": under the looser condition a dev push would run BOTH steps, staging its fresh APK and then overwriting it with the previous release's. The image still builds, the sidecar still parses, and the channel whose whole job is being current quietly serves stale art. Both falsified against the regressions they name before committing. Scribe task #3819, milestone #390. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SQ31KQpYbStyK5y58UmPLH	2026-09-09 22:47:42 -04:00
bvandeusenandClaude Opus 5	eaf4654c0a	test(release): make the version derivation executable, and guard it on dev ... Steps 1 and 2 of this milestone shipped with no CI coverage at all, and the reason generalises: release.yml triggers only on main and tags, so nothing inside it is exercised until a release is already running. That is the worst place in the repo to be unguarded, because the failure mode is silence — a version nobody can compare looks exactly like being up to date, and nobody reports an update they were never offered. The fix is not a test that reads YAML. The derivation moved into ci/version.sh, so it can be RUN, and internal/server/release_version_test.go runs it on every push. release.yml now calls the same script, so the thing that ships and the thing under test are one artifact rather than two copies that agree until they don't. test-go.yml gains 'ci/**' and '.gitea/workflows/release.yml' in its paths. Without that the guard exists but never fires on the changes it protects, which is the same nothing it replaces. What is pinned, and why each one: - HHMM is zero-padded. A build at 00:42 must emit "0042"; a stripped leading zero shifts the segment two orders of magnitude and reverses comparisons against every other build that day. It only bites for a tenth of the day, so it will not be found by chance. - The name derives from the COMMIT and the code from the BUILD. Asserted by holding one clock and moving the other: the name must not move, the code must. - The code clears 1895, the highest versionCode the retired commit-count scheme shipped. Below that Android refuses the upgrade as a downgrade and the channel becomes a one-way door. - The tag is the name with a `v`, never chosen. - release.yml still calls the script, and does not derive a commit count again. This pins the WIRING: without it every other assertion keeps passing while the shipped path silently drifts out of coverage. The script rejects unusable clocks rather than emitting something plausible, and those rejections are tested — a guard that cannot fail is worse than none, because it reads as coverage. Falsified before committing rather than after: ran the script against good and broken inputs and watched all three failure paths fire; verified every asserted value by executing it rather than by reading it; and checked the two workflow predicates catch their regressions while staying immune to a comment that merely names the old formula. Step 5 of 5 — Scribe task #3812, milestone #390. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SQ31KQpYbStyK5y58UmPLH	2026-09-09 22:11:51 -04:00
bvandeusenandClaude Opus 5	9f3e0b8cd3	feat(version): sidecar and /api/client/version carry name, code and channel ... The client compares names while Android installs by versionCode, and the wire had no way to close that gap: the sidecar was one positional line and the endpoint returned a name only. This is the plumbing that makes the ordering key decidable by the client at all. The sidecar is now JSON rather than a grown positional string. That shape was chosen against a specific failure: the obvious growth path was "<name> <code>", which a first-space split silently mangles the moment a third field appears — the code stops parsing as an integer and the reader falls back to name comparison WITHOUT erroring. JSON cannot mistake a new field for an old one. code is a POINTER on both sides, and omitempty on the wire. Absent has to stay distinguishable from zero: a build published before ordering keys were recorded genuinely has no code, and zero would claim it is infinitely old rather than unknown. A malformed sidecar now fails loudly instead of serving a blank version. If an unreadable file produced an empty name, every client would compare against nothing, conclude it was current, and go quiet — "I cannot read this" and "there is nothing newer" would return the same answer, which is the failure mode nobody reports because nobody is offered anything to report. The non-tag :latest path no longer RECONSTRUCTS the bundled APK's version. android-release now publishes the sidecar as a release asset beside the APK, and the image build downloads it. The old reconstruction duplicated a derivation formula across two files, and could only ever recover the name — the ordering key is build-time minutes and exists nowhere once that build ends. Releases predating the sidecar report their name with a null code, which is the honest answer rather than a guessed one. image-release also drops to a shallow checkout: it needed full history and tags only to re-derive versions from the tagged commit, and now touches git for nothing. MINSTREL_VERSION comes from GITHUB_REF. Two things checked rather than assumed. The Android Json sets ignoreUnknownKeys, so the added fields cannot break already-installed apps. It also sets coerceInputValues, which will silently turn a null code into 0 if step 4 declares the field non-nullable — recorded on task #3811, because reading the field declaration alone would never reveal it. Also fixes a stale comment block describing "the Flutter client", deleted in v2026.08.18. Step 3 of 5 — Scribe task #3810, milestone #390. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SQ31KQpYbStyK5y58UmPLH	2026-09-09 21:51:41 -04:00
bvandeusen	955a61194e	fix(library): a fully-missing album leaves the year axis too — #2702 ... Filed as a product decision, but the code had already made it: the genre queries filter tracks.missing_since inside their EXISTS, so an album whose every file had gone was ALREADY absent from genre while still listed under its year — where opening it found nothing playable. The two browse axes disagreed, and whichever answer won, one of them had to change. Hiding is the answer. Browsing is how you go looking for something to play, and the rule for that case is to take it out of view; the admin missing-files surface is where absence gets reported, with far more detail than a silent gap in a grid. It also means changing the axis that was inconsistent rather than the one that was already right. All three year queries move together — index, list and count. That is the invariant #367 needed care for at the genre level: if the index groups differently from the filter, a year leads to an empty page, and if the count disagrees with the list then "Load more" promises rows that never arrive. The predicate is "has at least one playable track", which also excludes an album carrying no tracks at all. Same answer for the same reason — nothing to play, nothing to browse to — and it is what genre has always done, since an album with no tracks contributes no genres either. That last part changed two existing tests, which had been seeding trackless albums as a convenience. Their intent (undated albums never appear in a range) is untouched; they now seed a track each, which is what a real album looks like anyway. Two new tests pin the actual behaviour: a fully-missing album leaves the axis while a half-missing one stays, and the count agrees with the filtered list.	2026-08-17 13:38:08 -04:00
bvandeusen	7ba673ed83	fix(library): tell clients when a file goes missing or comes back — #2704 ... The wire field shipped in 366692a1 was inert. MarkTracksMissing and ClearTracksMissing are plain UPDATEs, and /api/library/sync is a change-log feed: a row that never produces a change row is never re-sent. Clients would have kept their stale copy until an unrelated edit touched the track or the cursor fell out of the retention window and forced a full resync -- so the flag existed and nothing ever told anyone to read it. Found by checking the consumer set rather than the code: the field was threaded end to end and every test passed, because none of them asked the question "how does this reach a client?". Logged BEFORE the mutation, which is the opposite of the scanner's log-after-success pattern, and deliberately so. The failure modes are not symmetric. Log-then-fail-to-mark makes clients re-read a track that has not changed: one wasted fetch. Mark-then-fail-to-log leaves the mark with no change row -- and because both statements are idempotent (missing_since IS NULL / IS NOT NULL guards), the next scan will not retry the pair, so the client never learns. Permanently. A spurious re-read is much the cheaper mistake. Restoring logs too. A file coming back that nobody is told about stays greyed out on every device until something unrelated touches it, which would be a worse bug than the one being fixed. Op is upsert, not delete: the track still exists and keeps its history. Delete would tell clients to drop the row, which is precisely the design #2704 rejected when it chose to ship state instead of filtering the feed. Adds sync.LogChanges alongside LogChange, backed by an unnest batch insert. Every existing caller mutates one entity, so per-row was right for them; reconcile can mark a quarter of a library in one sweep, where a loop would be thousands of round-trips inside an already-slow scan.	2026-08-17 13:04:14 -04:00
bvandeusen	366692a1fc	fix: stop the sync feed hiding missing files from clients — #2704 ... #2523 filtered missing tracks out of every path that CHOOSES music, but the client sync feed was never touched: GetTracksByIDs has no filter and the wire had no field for it. So every Android client held a cached library containing tracks whose files are gone, with no way to tell, and could queue them from any cache-first path -- the exact failure #2523 existed to prevent, reached by a different route. Ships the state rather than filtering the feed, of the two options the ticket weighed. A missing file is expected to come back: the scanner clears the mark, and adopts the row if it returns renamed (#2528). Withholding the row would mean a delete-and-recreate on every client for what is usually a transient unmount, churning caches and throwing away the identity #2528 works to preserve. Room goes to v8. No hand-written migration: the pre-v1 destructive fallback rebuilds from sync, which repopulates every row with the new column -- exactly the case that policy exists for. The interesting part was working out what "missing" means to a client, and it is NOT "unplayable". Two findings shaped the fix: Server search and album detail never filtered missing tracks either, and that turns out to be right rather than an oversight. The consistent rule the codebase already follows is that Minstrel never PICKS a missing track for you -- recommendation, discover, mixes and browse all exclude them -- but it does not hide one you went looking for by name or opened an album to find. Hiding track 4 makes an album look wrong. So the fix is to mark and to keep it out of queues, not to hide it. And a track whose server file is missing still plays perfectly if its audio is already in the device cache. ShuffleSource's offline pools filter to exactly those residents, so it now clears the mark on the way out: the bytes are local and the server's loss is irrelevant. Without that, the queue filter below would have thrown away tracks that work, turning a fix into an offline regression. The queue protection is one choke point rather than five call sites. setQueue is where playlists, album play-all, search, radio and cold-boot resume all converge. dropUnavailable is pure so the index arithmetic is pinned by tests -- removing entries ahead of the requested position would otherwise start playback on the wrong track, and asking to start on a missing track now starts the next playable one, which is the "gets skipped" behaviour the operator asked for. An entirely missing queue returns empty and the caller leaves the player alone rather than replacing what is playing with silence.	2026-08-17 12:56:31 -04:00
bvandeusen	414dfb23b6	feat: show what re-acquisition has done, per folder — #2527 ... Completes milestone #290. The sweeper has been running and the settings have been editable, but the list itself said nothing about either, so the only way to tell "not tried yet" from "asked twice and nothing came back" was to go and read the Requests queue. Each folder now carries its album's attempt record: how many times, when last, when next -- or that it gave up, with the reassurance that a file coming back and going missing later starts the process over. Null when nothing has been attempted, which is the common case for a folder that just went missing and would be noise on every row. next_attempt_at is computed, not stored. The schedule is a function of the attempt count and the current settings, so persisting it would go stale the moment an operator edited the backoff -- and the card lets them do exactly that. Needed a forward-looking formatter. relativeTime deliberately collapses a future timestamp to "just now" (pinned by its own test) because that is the right answer for a clock-skewed past event; it is the wrong one for a scheduled future attempt, which would have rendered "next just now". timeUntil is its companion rather than a sign-aware rewrite: the two read differently in the same sentence -- "last tried 3d ago, next in 4h" -- and a test asserts they disagree about the future on purpose, so nobody later "fixes" the divergence. The state lookup is one batched query for the whole page and best-effort: this is context on a list whose real job is showing what is missing, so a failure leaves the groups bare rather than failing the page. The settings service is read with a nil guard falling back to the shipped defaults, since contexts that wire routing without services exist and a backoff projection is not worth a nil-pointer panic (rule #48).	2026-08-17 00:19:48 -04:00
bvandeusen	c2862e97bd	test(api): cover the missing-file admin routes in the Mount test — #2527 ... go vet caught the Mount signature change: library_test.go calls it from inside the package, so the earlier grep for "api.Mount(" missed it. Rather than only appending the argument, the route table now includes both admin surfaces from this arc. That test exists to prove every route is actually registered — a 404 there means the route is missing — and the two paths added today had no such coverage. Both are in the admin group, so reaching the 401 is what proves they are wired. The new service is passed as nil, matching the other optional services in this call: the test asserts routing, never executes an admin handler, and constructing a settings service would need a pool round-trip for nothing.	2026-08-17 00:07:10 -04:00
bvandeusen	30a5ac56ce	feat(api): admin endpoints for the re-acquisition policy — #2527 ... GET/PUT /api/admin/library/reacquisition, so every knob the sweeper reads is editable without a restart (rule #25). Routed under /library beside the missing-files list it governs rather than under /lidarr: Lidarr is the mechanism, but missing files are the problem the operator came to solve, and that is the surface they meet it on. The payload carries one thing the settings table doesn't: the count of albums with missing files that can never be auto-requested, because neither they nor their artist has an MBID. Nothing can be asked of Lidarr for a release MusicBrainz cannot name, and a feature that silently does nothing for part of its input reads as broken -- so the card states the number instead of leaving it to be inferred. Counted best-effort: the settings are the point of the endpoint, and failing the whole card because a count query hiccuped would be the wrong trade. Range errors come back as 400 naming the field. The Go-side validation mirrors migration 0056's CHECKs precisely so the operator reads "grace_hours must be 1-720" rather than a constraint-violation string surfacing as a 500.	2026-08-17 00:02:41 -04:00
bvandeusen	bab9b16831	feat(library): a missing file asks Lidarr for itself, on a backoff — #2527 ... Answers the open fork on #2527's last slice: automatic, not a button. Until now missing_since was a dead end -- reconcile marks it, every selection path skips it, the admin surface lists it, and there it sits. Two decisions carry most of the safety, both at the design level rather than as rate limits bolted on afterwards. The unit is the ALBUM, not the track. Lidarr acquires releases; there is no meaningful "fetch me one track", and a track-kind request needs a recording MBID plenty of files lack. Grouping means the loss that produced #2523 -- three reorganised albums, ~40 missing files -- becomes three requests instead of forty. The flood problem mostly dissolves. And nothing is requested until a file has been missing longer than the grace window (24h default). A filesystem lies transiently: an unmounted volume, a container that started before its media mount attached, a NAS mid-reboot. Every one of those resolves itself well inside a day at no cost. missing_since is never re-stamped (#2523), so it is a true "gone since" clock to measure against, not "when we last noticed". This is the difference between automatic and trigger-happy. Then the backoff proper: 6h -> 12h -> 24h -> 48h per album, clamped to a week, three attempts before giving up, and a per-pass ceiling so a genuinely large loss trickles instead of dumping hundreds of rows into the queue. Giving up is stamped as a timestamp rather than inferred from attempts >= max, so the verdict survives an operator later raising the maximum and the surface can say when. A sweeper, not a hook inside reconcile. Reconcile runs inside a scan and has no business deciding to talk to a third-party service; it also re-runs often, which would make "attempt once, then back off" awkward to express. A worker paces itself, survives a restart, and retries without needing another scan. Recovered albums have their state deleted rather than reset -- a future loss is a new problem, not a continuation. Requests are attributed to the oldest admin: lidarr_requests.user_id is NOT NULL and a re-acquisition has no requesting human, so this keeps the row auditable and in the same queue as everything else without inventing a synthetic principal the schema would have to understand. Auto-approve defaults ON. Requests are created pending and nothing reaches Lidarr until approval, so with it off this would be a notification rather than an attempt. Lidarr disabled leaves the request pending rather than counting a failure -- the record of intent is still right and becomes actionable the moment Lidarr is configured. Albums with no MBID are counted, not silently skipped: nothing can be asked of Lidarr for a release MusicBrainz cannot name, and quietly doing nothing would read as the feature being broken. Settings are DB-backed per rule #25 with CHECK-guarded ranges, validated in Go as well so the API answers 400 rather than surfacing a constraint violation. The admin card and the state on the missing-files page are next; this is the engine.	2026-08-16 23:53:21 -04:00
bvandeusen	03a8d12079	docs: stop pointing at the deleted Flutter tree — #2710 ... Every comment naming a path in flutter_client/ now resolves to nothing, which is the failure mode this project has already been bitten by twice -- drift #572 came from delete.go describing behaviour it no longer had, and that same docstring was still wrong when it was fixed last week. A pointer to a deleted directory is the same thing in slower motion: the reader follows it, finds nothing, and cannot tell whether the comment is stale or they are looking in the wrong place. Three treatments, per what each comment was actually doing: - Naming a concept ("mirrors db.dart's CachedTracks Drift table"): keep the concept, drop the path. The Drift table is why the entity looks as it does; the file it lived in is not. - Pure port bookkeeping ("Mirrors <path>." and nothing else): deleted. Git history records the port; the comment only restated it. - Substance introduced by a pointer (a lifecycle list, a 200 px/s threshold, an inverted control-row placement): keep the substance, drop the lead-in. The two Go comments were the valuable ones and got more than a trim. They stated a live contract -- "field names match the client's FromJson helpers exactly, or fields are silently dropped" -- against a client that no longer exists. They now name the real consumer, SyncResponseWire.kt, and say why the failure is silent there too: kotlinx.serialization skips unknown keys, so a renamed field arrives as a default value rather than an error. The ticket counted 64 files by grepping flutter_client/. A second tier turned up during the sweep: 15 more references naming bare Dart files (player_bar.dart, now_playing_screen.dart:464, auth_provider.dart) with no directory prefix. Same dead tree, same treatment, folded in here. Comments only -- verified no non-comment line is touched in the diff.	2026-08-16 22:40:58 -04:00
bvandeusen	4dd0a58d63	feat(api): admin surface for files the library has lost — #2527 ... The scan has marked missing files since f6d1cf24 and every selection path filters them out, so they cause no harm -- and are invisible. The operator found out about the first batch only because an unrelated MBID backfill logged "no such file or directory" forty times. GET /api/admin/library/missing reports them, grouped by directory. The grouping is the whole ergonomic argument: the case that produced #2523 was three reorganised albums, which a flat list renders as forty unrelated problems and a folder list renders as three decisions. ListMissingTracks orders by directory so the handler can fold runs without a map, which also keeps the query's ordering instead of Go's random map iteration. Each row carries last_played_at, nullable, because "gone six months, never played" and "gone yesterday, played 200 times" deserve opposite reactions and a file path tells you neither. The correlated MAX needs its ::timestamptz cast or sqlc infers interface{} and the Go layer loses the type. Read-only, deliberately. Nothing here deletes: a missing file keeps its row, its play history and its likes because it may come back, and if it comes back renamed the scanner adopts it (#2528). The route sits under /library rather than /tracks so it can't be confused with the destructive DELETE /admin/tracks/{id} beside it.	2026-08-16 11:48:45 -04:00
bvandeusen	c3f3a17c6d	feat(library): a missing file stays in the playlist, greyed and unplayable — #2527 ... Every browse, discover and mix query filters missing_since, so a track whose file vanished disappears from the places Minstrel chooses music. A playlist is different: the entry is there because the user put it there, and silently dropping it rewrites their list behind their back. So playlists keep the row and mark it instead. ListPlaylistTracks now carries missing_since (still deliberately unfiltered), the service layer surfaces it as PlaylistTrack.Unavailable, and the wire gains "unavailable" on each entry. A missing entry also loses its stream_url. Refusing to hand out a URL that cannot serve is stronger than trusting every client to honour the flag, and "stream_url": null is a shape the clients already model -- PlaylistWire.streamUrl is documented nullable for the track-removed case -- so an older build degrades to "present but not playable" with no change. Nothing is deleted here and nothing should be: the row, its play history, its likes and its taste contribution all survive a file going missing, because the file may come back (and #2528 will adopt it if it comes back renamed). Also corrects two comments that had drifted into lying. delete.go still claimed the file-gone case was NOT auto-reconciled and told admins to delete rows by hand -- untrue since f6d1cf24, and that exact staleness is what produced drift #572. It now says what DeleteTrackFile really is: the destructive admin action, which CASCADEs play_events and likes, and is emphatically not the missing-file path. watcher.go claimed the safety-net scan "covers anything missed"; the walk only covers additions, and it is reconcile that covers removals.	2026-08-16 11:43:05 -04:00
bvandeusen	8e1d25a772	fix(scanner): repair acronym and apostrophe casing on genre tags — #2468 ... Operator decision: keep the ID3v1 table canonical, fix the casing. The operator's library carries "Edm", "Idm", "Aor", "Uk Garage", "Uk Hardcore", "Trap Edm", "Glitch Hop Edm" and "Children'S Music" — an external tag editor title-cased the whole genre field. The "'S" is the giveaway. Fixed at SCAN time, not in the display layer: taste_profile.sql reads tracks.genre directly, so a cosmetic-only fix would leave the taste vocabulary holding "Edm" while the UI showed "EDM", and any correctly tagged file would contribute a second, separate tag. trueUpCasing only ever changes case, never letters, so it cannot silently turn one genre into a different one — that is what separates it from the label-remapping idea this task rejected. Two narrow rules: - A short, evidence-led acronym list, matched case-insensitively so "edm", "Edm" and "EDM" all land on "EDM". This is a deliberate exception to the project's rule that genre case is exposed as the file says it: "Rock" and "rock" still stay separate rows, because folding those is a judgement about labels, whereas there is no genre named "Edm". - Apostrophe suffixes from a FIXED contraction list, so "Children'S" is repaired while "O'Brien" and "D'Angelo" keep their capital. A blanket "lowercase after an apostrophe" would have broken both. Matching uses the word's letter core rather than the raw word, so "(Edm)" and "Edm," are repaired and their punctuation re-attached. Interior punctuation stays in the core, so "Lo-Fi" and "R&B" are compared whole and cannot match a fragment by accident. My first version missed this and a test expecting "(Live EDM)" caught it. Names resolved from the ID3v1 table are deliberately NOT re-cased, per the operator's call — entry 40's "AlternRock" stays as the table spells it, with a test pinning that so a later tidy-up doesn't quietly "fix" it. tagReadVersion 1 -> 2, so this reaches the existing library on the next scan rather than new files only. That re-read reuses stored durations, so it costs tag reads and no ffprobe.	2026-08-07 14:43:36 -04:00
bvandeusen	481f906059	feat(metrics): publish margin of error on every delta — #2495, #2524 ... The metrics card had one volume threshold doing two jobs. recMetricsLowVolume = 20 is a DISPLAY floor — below that a skip rate is anecdote — but the card then presented deltas as though it were also a DECISION floor. Those differ by an order of magnitude: detecting the ~13pp differences that matter needs ~133 plays per arm for 80% power at a=0.05. So Discover's taste-matched (59 plays) and random-unheard (70) both rendered as full-confidence rows with a bold delta beside them, and that comparison sits at p ~ 0.06. The card said "signal"; the arithmetic said "maybe". It produced a recommendation the data didn't support, and any reader with the same numbers would have made the same call. Deltas now carry a 95% margin of error and a `distinguishable` flag, computed server-side so both clients read the same arithmetic instead of each re-deriving it. Skip rate is a two-proportion difference; completion is Welch, which needs a variance — hence completion_sqsum in the query. It is the sum of squares rather than stddev_samp on purpose: raw source rows are merged into surface families in Go, and sums of squares combine across groups exactly whereas standard deviations cannot. recMetricsLowVolume is untouched. "Too thin to show" and "too thin to act on" are different questions. Web renders an indistinguishable delta as dimmed and prefixed "≈", with the range on hover and a legend explaining the glyph. Colour is withheld unless the delta clears its margin — colouring noise red is what made the old card misleading. Breakdown rows go through the same path; those are the thinnest samples on screen and where the old card misled most. Also fixes the admin trends view, which had the same problem worse: its "Latest skip"/"Latest completion" columns are one WEEK while the adjacent Plays column is the whole window. I misread exactly that and briefly concluded Deep cuts was the worst surface, from ~17 plays in a single week — over 180 days it is one of the best. Headers now name their period and the skip cell carries that week's play count. #2524: resolveArtist now recognises a duplicate-MBID unique violation as the expected condition it is, matching resolveAlbum. Two rows mapping to one MusicBrainz artist is a merge candidate, not a fault; without the branch it logged a generic warning plus a Postgres ERROR line on every scan, which teaches an operator to ignore database errors.	2026-08-06 21:08:58 -04:00
bvandeusen	24d330424f	feat(library): adopt moved files instead of forking their history — #2528 ... Track identity was file_path, so a file that came back renamed or in a different directory looked like a deletion plus an unrelated new track: the old row kept the like and every play_event while a fresh zero-history row appeared, and nothing connected them. A liked song read as unliked, its play count reset, and Rediscover could offer it as a discovery — silently. Renumbering an album was enough, which is what happened to the operator's copy of Minutes to Midnight. Adoption re-points the existing row's file_path at the new location and clears its missing mark. The normal UpsertTrack then conflicts on file_path and updates THAT row, so the track id survives and likes, plays and playlist memberships travel with it — and clients see an update rather than a delete-and-create, so no cache churn either. Matching is MBID first (identifies the recording, so it survives a re-encode), then file_size + duration_ms for untagged files. Both fingerprint components must be non-zero: duration_ms is 0 when ffprobe failed, and matching 0 against 0 would pair up unrelated broken files. Only rows already marked missing are eligible — a row whose file is present elsewhere is a duplicate, not a move, and re-pointing it would corrupt the copy that still exists. An ambiguous match inserts fresh rather than adopting one arbitrarily: a fork is recoverable later, a wrong merge isn't. Scan is now three phases, and the order is the point. Adoption can only claim a row that is ALREADY marked missing, but reconcile previously ran after processing — so a rename performed while the server was down surfaced the deletion and the addition in the same scan, the new path inserted first, and the fork became permanent. Enumeration is therefore separated from processing so reconcile can run between them: walk (paths only, no tag reads or probes) -> reconcile -> process in walk order. Consequence worth knowing: when reconcile refuses (an absent root, or a reorganisation exceeding the 25% mark cap) adoption cannot fire and renamed files fork as before. That's the pre-#2528 behaviour rather than a new failure, and the warning now names it. The old outer walk-error branch was unreachable — the callback always returned nil, so WalkDir never surfaced an error — and verifyRootsPresent is the real protection, so enumerate counts walk errors instead of pretending to abort on them.	2026-08-06 15:56:07 -04:00
bvandeusen	f6d1cf24f0	feat(library): detect missing files and stop offering them — #2523 ... Nothing in Minstrel ever noticed a deleted file. The walk only visits paths that exist, so a row whose file was gone was never scanned, never errored, never counted — permanently invisible. classifyEvent ignores fsnotify removals by design, and the safety-net scan is the same walk, so it covers additions only. Rows accumulated forever. Found on the operator's library: a completed scan reported skipped=24185 errored=0 while the MBID backfill (which opens files by DB path rather than walking) logged ~40 "no such file or directory" across three reorganised albums. Those rows also kept their pre-#2499 welded genre, which is how this surfaced — the version-stamped tag re-read can only reach files the walk visits. The harm is not cosmetic. tracks is the candidate universe for recommendation.sql / discover.sql / system_mixes.sql and nothing filtered on file existence, so a mix could spend a slot on a track that cannot stream. Marks rather than deletes. A missing file is a claim about the filesystem and the filesystem lies transiently — an unmounted volume, a network blip, a container that started before its media mount attached. Every sweep in internal/gc resolves a truth INSIDE the database and is safe to run blind; this one is not, so no deletion happens here. Three guards refuse to act on ambiguous evidence: every scan root must resolve to a non-empty directory, the walk must have seen at least one file, and one reconcile may newly mark at most 25% of the library. Clearing a mark is never the dangerous direction, so it runs unconditionally — otherwise a library that tripped the cap could never recover once the mount returned. Only a full Scan reconciles. The walk's set of seen paths is the evidence, and ScanFiles has no basis for concluding anything about files it did not look at. Excludes marked tracks from all 13 track-emitting queries (radio x2, system mixes x5, discover x4, most-played x2), the 6 play-history seed picks, and the genre browse axis. Deliberately NOT filtered: the shared ListPlaylistTracks read path, because it also serves user-curated playlists where hiding a track the user added would be wrong — system playlists shed orphans on their next daily rebuild instead. History and the taste profile also keep them: those record the past, and a track you played 200 times still says something about your taste. Reconcile tallies land in scan_runs so a disappearance is visible rather than discovered when a mix comes up short.	2026-08-06 14:34:53 -04:00
bvandeusen	fd27819cdd	style(scanner): tagged switch on ID3 major version — #2499	2026-08-05 21:22:53 -04:00
bvandeusen	37b396a7e4	fix(scanner): read multi-value genre frames correctly — #2499 ... dhowden/tag's readTFrame splits ID3v2 null-separated multi-value text frames and rejoins them with the EMPTY string, so a file tagged "Alternative Rock" + "Rock" was stored as "Alternative RockRock". It also leaves bare numeric ID3v1 references unresolved, which is why the library showed genres like "4017" and "526617". This corrupted more than the browse axis added in #367: taste_profile.sql reads tracks.genre directly, so the welded tokens were entering the taste profile's tag vocabulary, and recommendation.sql/discover.sql were comparing them as single opaque tags. Genre counts were wrong everywhere. ffprobe is not a fix — ffmpeg's read_ttag calls decode_str once with no loop, keeping only the first value. Truncating multi-genre tags would blunt the similarity signal genre mainly feeds. So the TCON frame is now parsed directly (ID3v2.2/2.3/2.4, all four text encodings, per-frame and tag-level unsynchronisation, numeric and parenthesised ID3v1 references); everything else still comes from dhowden/tag. Values are stored ";"-delimited, which the read side already splits on, so no query changes. Existing rows are repaired without an operator-run rebuild: migration 0054 adds tracks.tag_read_version DEFAULT 0, below the scanner's current tagReadVersion, so the next scan re-reads tags it would otherwise skip on mtime. Such a re-read reuses the stored duration instead of re-running ffprobe, keeping a repair pass tag-read-bound rather than one fork+exec per file. Bumping the constant is how a future extraction fix reaches an existing library. Only ID3v2 is in scope — dhowden welds nowhere else. The Vorbis/MP4 repeated-field question is #2500, unproven and deliberately not built.	2026-08-05 21:17:59 -04:00
bvandeusen	a9ca49dc4e	feat(library): genre + year quick-jumps on album and artist detail — #367 ... Last bullet of #367. From an album you like, one click to everything else from that year or in that genre. Year was free — AlbumRef already carried it. Genre was not: AlbumDetail is AlbumRef + tracks and neither carried genre, because genre lives on TRACKS. So both detail responses gained a derived `genres` array, computed from the entity's tracks rather than stored, since an album's tracks can legitimately disagree about genre. Split and trimmed identically to the browse index. That's the invariant this whole task turned on: if the chip's matching diverged from the index's splitting, a chip would lead to a page that doesn't contain the album you clicked from. No year link on artist detail. An artist spans many years, so a single one would be a lie about the discography — genres only there. Genre lookup failure is logged and degrades to no chips rather than failing the request; a navigation nicety must not 404 a detail page that otherwise loaded. `genres` is always an array at JSON, never null, matching how every other list field in this package is emitted. ## Type widening, and the TypeScript version of a lesson from earlier today Adding a required field to AlbumDetail/ArtistDetail breaks every typed fixture that constructs one. Six of them across three test files. That's the same shape as the Go signature changes that cost three CI rounds in #2453 — change a type, then go find everything that builds it — so I searched for the constructions before pushing instead of after. All six updated. Tests: the encoded href for a slash-bearing genre ("Rock/Pop" → ?g=Rock%2FPop), the year href, and the no-tags case rendering no chips at all. gofmt verified clean via docker rather than guessed.	2026-08-05 13:50:29 -04:00
bvandeusen	f8f2273aec	style: gofmt alignment in library_browse_test — #367 ... One space. `name:` had to align with `query:` inside a composite literal where both sat on their own lines. Found via `docker run golang:1.25-alpine gofmt -l`, which is the actual point of this commit: gofmt is available here the same way sqlc is, and there is no reason to have let CI discover a formatting nit. Whole tree verified clean, not just this file. The substance of 1126bfcf was already sound — verify-generate, vet and the full integration suite passed, so the genre-splitting behaviour holds against a real database. Only the formatter objected.	2026-08-05 13:29:28 -04:00
bvandeusen	1126bfcf78	feat(library): genre + year browse queries and endpoints — #367 ... Server half of #367. Web UI follows. Genres are exposed AS-IS per the operator: split on the delimiter, trimmed, but no case folding and no synonym mapping. So "Rock" and "rock" appear as separate rows, as does "Rock/Pop" alongside "Rock" and "Pop". The raw spread has to be visible before anyone can judge whether it needs normalising, and the alternative is a mapping table to invent and then maintain. Trimming is not an exception to that. Splitting "Rock; Pop" yields " Pop", and showing that as a genre distinct from "Pop" would be a bug in OUR splitting, not fidelity to the operator's tags. ## The correctness trap this had to avoid ListAlbumsByGenre compared tracks.genre verbatim, while recommendation.sql and discover.sql have always split it on [;,]. Building the browse index by splitting while matching exactly would have listed genres whose pages are empty — every multi-genre track unreachable from either of its genres. So ListAlbumsByGenre now splits too. That also fixes Subsonic getAlbumList?type=byGenre, its only caller, which silently missed every multi-genre track. Its Genre param went *string → string as a result. EXISTS rather than JOIN + DISTINCT ON throughout: the lateral split emits one row per (track, fragment), so a join multiplies rows per album and needs DISTINCT to undo itself. EXISTS asks the question directly, and the count query then matches the list query by construction rather than by coincidence. ## Genre is a query parameter, not a path segment Because "Rock/Pop" is a real ID3 tag — the one the task itself cites — and a slash cannot survive a path segment: Go normalises %2F and the router would split the value in two. So filtering rides GET /api/library/albums?genre=, which also reuses the existing paged album surface instead of adding a parallel one. Endpoints: GET /api/library/genres unpaged index + track counts GET /api/library/years unpaged index + album counts GET /api/library/albums?genre= filtered page GET /api/library/albums?year_from=&year_to= filtered page, either edge open The indexes are unpaged deliberately: a client needs the whole set to render a browsable picker, and paging would let it show only a prefix of an ordering the user didn't choose. Two refusals rather than guesses: genre+year together is a 400 (the UI browses them as separate axes, and quietly dropping half a filter would report a narrower result than it returned), and an inverted year range is a 400 rather than being silently swapped. Undated albums are absent from the year axis rather than bucketed under 0 — "unknown" is not a year, and a 0 row would sort to one end of a chronological list looking like data. Tests: parseYearFilter is pure and runs in the fast lane. The integration tests assert the thing that would otherwise be silently broken — that a "Rock;Pop" track is reachable from BOTH genres, that "Rock/Pop" survives as a filter value, that fragment whitespace is trimmed, and that undated albums stay out of every year range. Reused the existing seedAlbum/seedTrackWithGenre fixtures, which already took exactly the year and genre arguments needed.	2026-08-05 13:22:30 -04:00
bvandeusen	5b36d79ff9	fix(server): access log reports the real client, not the proxy — #2453 ... Closes the disagreement left open by #2453: requestlog.go logged raw r.RemoteAddr while the Active-sessions surface resolved through the operator's configured proxy depth. Behind a proxy — the normal deployment for anything public — every access-log line carried the same useless proxy address, and the two surfaces contradicted each other about who connected. Logs and UI disagreeing is worse than either being wrong alone, because it costs you trust in both. `remote` now holds auth.ClientIP(r, hops). The attribute KEY is deliberately unchanged so existing log greps keep working; only its accuracy improved. Wiring note. The access log covers /healthz and the SPA, so it's registered before the pool-bearing branch that used to build the settings service. Rather than close over a variable reassigned later — which works, but leaves a mutable-after-registration seam and an awkward question about races — I hoisted netsettings.New above the router entirely. It already handles a nil pool by returning a default-valued service, so no branch is needed and the accessor stays a plain method value. Applied the lesson from the last three CI failures BEFORE pushing this time: a bare-identifier grep for `requestLog(` found three call sites in requestlog_test.go that a qualified pattern could never have matched, since the function is package-private and its tests are in-package. Also swept netsettings.New and ClientIP the same way. Tests: the behaviour change gets its own table — nil accessor and depth 0 log the socket peer, depth 1 through a PUBLIC-addressed proxy logs the client (the exact case the old heuristic got wrong forever), depth 2 reaches through a CDN. Added `remote` to the required-keys assertion so the attribute can't quietly disappear.	2026-08-05 13:02:36 -04:00
bvandeusen	11538095be	fix(net): validate hop range before checking availability — #2453 ... TestSetHops_RejectsOutOfRange caught a real ordering bug in code I wrote in the same commit: the nil-pool guard sat ahead of the range check, so SetHops(-1) on a service with no pool returned "network settings unavailable" instead of ErrHopsOutOfRange. Range first is correct, and the distinction is user-visible rather than cosmetic: the argument is invalid regardless of whether the database is reachable, and admin_network.go maps ErrHopsOutOfRange to 400 while anything else becomes 500. The old order blamed the server for the caller's input. Note this is the first failure in this sequence that wasn't a missed call site — vet and golangci-lint both passed, and a test asserting a specific sentinel error found it. Worth the extra assertion; `err != nil` would have passed happily.	2026-08-05 10:27:10 -04:00
bvandeusen	d5ab3b0764	fix(net): update the in-package Mount call site in library_test — #2453 ... Third attempt at the same class of mistake, so worth naming precisely. TestRoutesRegisteredInMount calls Mount() from INSIDE package api, so the call reads `Mount(...)` unqualified. My verification grep was `api.Mount(`, which cannot match it. Same shape as the previous failure, where I grepped `auth.ClientIP(` and missed nothing — but only because those callers happened to be in other packages. The lesson generalises: after changing an exported signature, search for the bare identifier, not the package-qualified form. In-package callers — which in Go means most tests — are invisible to the qualified pattern. This time I swept every signature I touched (Mount, RequireUser, ClientIP, TouchSessionLastSeen) with an unqualified pattern before pushing, rather than letting CI enumerate them one per run. Passing h.netSettings (nil in test handlers) is deliberate, not a placeholder: this test asserts route registration, and Hops() is nil-safe by design so the middleware reads "trust nothing" rather than panicking. Also gave netsettings' logger field a use — it was assigned and never read, which staticcheck's unused pass can flag. A hop-count change alters how much of a client-supplied header the server believes, so it earns a log line for anyone later debugging odd addresses in the sessions list.	2026-08-05 10:21:16 -04:00
bvandeusen	a07fb3867a	fix(net): thread hops into session creation; disambiguate card tests — #2453 ... Two CI failures from 381e9ced, both mine. **Go (vet, which cascaded into the integration job).** Widening auth.ClientIP to take a hop count, I updated the middleware that TOUCHES a session but missed the two places that CREATE one — handleLogin and handleRegister. So `created_ip`, the frozen origin address that the whole "address changed" comparison rests on, was the one value still being computed the old way. Both now read h.netSettings.Hops(), which is nil-safe so test handlers constructed without the service still work. Worth noting the shape of this miss: I checked call sites by searching for the middleware's own usage and stopped there, rather than for every caller of the function whose signature I changed. vet found it in seconds; a grep for `auth.ClientIP(` would have too. **Web (vitest).** Three tests waited on `findByText('198.51.100.7')`, which matches TWO elements in the fixture — the detected client address and the forwarded chain, identical strings for a single-proxy setup — and findByText throws on multiple matches. Now they wait on the unique "Your address right now" label and assert the address with getAllByText where duplication is legitimate. The duplication is correct behaviour, so the test moved rather than the component.	2026-08-05 10:14:38 -04:00
bvandeusen	381e9cedb7	feat(net): trusted-proxy depth so real client IPs survive a proxy — #2453 ... Fixes the defect the operator spotted in #370 immediately after it shipped: auth.ClientIP ignored X-Forwarded-For whenever RemoteAddr was public, so a proxy on a public address — a separate host, or a CDN, i.e. anyone running this publicly, since public means TLS means a proxy — recorded the PROXY for every session. created_ip and last_ip were then always equal and the "Address changed" signal could never fire. The feature looked like it worked and reported nothing. Replaced with the standard trusted-hop model (Rails, Caddy, Traefik, nginx). XFF grows left-to-right as each proxy appends the peer it received from, so for client -> CDN -> own-proxy -> app the app sees [client, CDN] with RemoteAddr = own-proxy, and the client sits at XFF[len - hops]: 0 RemoteAddr, XFF ignored — no proxy 1 the address your own proxy observed 2 through a CDN in front of your proxy Default 1, per the operator: publicly reachable means a TLS terminator in front. The cost is real and stated rather than hidden. hops >= 1 DECLARES that a proxy exists; set it with no proxy, or deeper than the actual chain, and the index reaches attacker-supplied entries, letting a visitor choose which address their own session shows — defeating exactly the detection #370 is for. That's inherent to the model, which is why 0 is a first-class value and the admin card says "count your proxies, don't guess high" instead of just exposing a number. Both mis-set shapes are pinned by tests so they stay known consequences rather than surprises. Migration 0053 + internal/netsettings, cached under an RWMutex. That's not an optimisation: ClientIP runs in RequireUser for every authenticated request, so a per-request query would put the database on the critical path of the whole API. New() always returns a usable service so a boot-time DB hiccup degrades to the default instead of breaking that path (rule #131), and Hops() is nil-safe because test routers construct middleware without it. RequireUser now takes a func() int rather than an int — the value is operator-editable at runtime while the middleware is built once at boot, and reading it per request is what makes a save take effect with no restart (rule #25). The admin card is verifiable, not just configurable: it reports the address the CURRENT setting resolves THIS request to, the raw forwarded chain, and the socket peer — so you set the number, save, and confirm the address matches the machine you're on. It also counts the arriving chain and says how many proxies that implies. GET/PUT both return that payload, PUT recomputed under the new value, so the effect is visible without a reload. Also fixes styling in the #370 card that CI could not catch: text-destructive and bg-destructive don't exist in this Tailwind config — the palette is colors.action.destructive — so the "Address changed" warning and the sign-out-others button were rendering unstyled. Both now use text-action-destructive / bg-action-destructive / text-action-fg. Not done here: requestlog.go still logs raw RemoteAddr and will disagree with the sessions UI about who connected. Left for its own change.	2026-08-05 10:07:43 -04:00
bvandeusen	d86af7397d	feat(auth): active sessions API with origin/current IP — #370 ... Server half of the active-sessions surface. Web UI follows. The operator wants this specifically to notice a compromised account, which sets the bar: the addresses have to be trustworthy, or the feature is worse than absent because it looks like evidence. Migration 0052 adds created_ip + last_ip. Two columns, not one, and the pair is the signal: a session issued at home and now being used from elsewhere is the shape of a stolen token, and neither column alone can show that. Typed text, matching the user_agent column beside it — these are displayed, never queried by subnet, and inet round-trips through pgx as a netip.Prefix that renders "1.2.3.4/32". The rest of the schema was already waiting. Migration 0004 anticipated this exactly: "last_seen_at enables an 'active sessions' UI later (not wired in this plan) without schema churn." last_seen_at is live data — the auth middleware already touches it per request — so last_ip rides that same UPDATE for free. Getting the address right is the substance here. Nothing extracted a client IP anywhere before, and both obvious approaches are wrong: - RemoteAddr alone shows the reverse proxy on every session, which is the normal self-hosted deployment. Noise shaped like data. - Trusting X-Forwarded-For lets any client choose what its victim sees. A security surface an attacker can write to is worse than none. So auth.ClientIP trusts the header only when the request actually arrived from a proxy range. Public RemoteAddr means a direct connection, so XFF is attacker-controlled and ignored outright. Private RemoteAddr means we walk XFF right-to-left — proxies append, so the right end is what our own infrastructure wrote — and take the first non-proxy address. A forged XFF only prepends to the left end, which that walk never reaches. Unit-tested, including both spoofing shapes. Fails closed on a public-addressed proxy (separate host, CDN): we report the proxy rather than trusting a forgeable header. Documented at the function. Endpoints, all scoped by user_id per rule #47: GET /api/me/sessions → list, flagging the current row DELETE /api/me/sessions/{id} → 204, or 404 if not yours POST /api/me/sessions/logout-others → {"revoked": n} Keyed on session id alone, any household member could revoke another's session by guessing a uuid, so the delete carries user_id in its WHERE and :execrows distinguishes "not yours" (404) from a false 204. There's a test that asserts the row actually survives, not merely that we returned 404. The middleware now also puts the session id in context. logout-others is defined by exclusion, and without knowing which session is ours the safe-looking action deletes everything including the caller's — so it refuses rather than guesses when the id is absent, and that refusal is tested for non-deletion too. audit_log.action is plain text with no CHECK, so the two new actions need no migration (rule #36 checked, not assumed). Codegen is real sqlc 1.31.1 via the container in `make generate` — docker is present on this workstation even though Go and sqlc aren't — rather than the hand-written .sql.go shortcut used in milestone #268.	2026-08-05 09:17:40 -04:00
bvandeusenandClaude Opus 5	cf0d37bf8e	fix(discover): compare against a baseline run, not a hardcoded score — #2377 ... TestSuggestArtists_UntaggedCandidateSurvivesAlongsideTagged asserted the untagged candidate's score was 0.9 — the raw similarity value I'd seeded. It's actually 1.61, because the pool score is signal-weighted by the seed query: ln(1+signal) x similarity, and a liked seed carries signal 5, so ln(6) x 0.9. The assertion was testing the seeding arithmetic, which is a different layer and not what the test is about. Rewritten to run the same request twice — once with the tag term disabled, once enabled — and assert the untagged candidate's score is IDENTICAL across both. That states the real property (the blend leaves untagged candidates alone) without depending on how the pool score is derived, so it survives future changes to seeding. Added a sanity assertion that the TAGGED candidate's score did move, so the comparison can't pass by both runs being trivially identical — the same "a test that cannot fail" trap recorded for this milestone. Exact-preservation at the arithmetic level is already covered where it belongs, by TestApplyTagOverlap_UntaggedCandidateScoreIsUnchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-02 23:45:48 -04:00
bvandeusenandClaude Opus 5	799dab029a	feat(discover): rank suggestions by taste-tag overlap — #2377 (server) ... The payoff slice. Until now a candidate's only claim on a slot was "some artist you play is adjacent to it in a similarity graph" — a fact that says nothing about whether the music sounds like anything you like. Now the candidate's own folksonomy tags (cached by slice 5) are compared against the user's taste-profile tags, so the deck ranks on taste and can say WHY. The blend is MULTIPLICATIVE — score × (1 + weight × overlap) — and that choice carries the whole safety argument: - An untagged candidate has overlap 0, so its score is EXACTLY unchanged. Tag coverage is permanently partial (#2376); it must cost a candidate nothing, not sink it (rule #131). - Nothing can leapfrog on tags alone. An additive term with a large weight would let a near-zero-similarity artist outrank a strong match for sharing one popular tag, which reads as noise. - Weight 0 restores pure similarity order bit-for-bit, so the operator's knob has a real off position. overlap = Σ(shared) candWeight × normalizedTasteWeight ÷ Σ(all) candWeight. Normalizing the taste side by the user's strongest tag makes the score comparable across users (taste weights accumulate with listening, so a heavy listener's raw numbers dwarf a new user's while meaning the same thing). Dividing by the candidate's own mass makes it comparable across candidates, so a densely-tagged artist can't win on tag count alone. Applied to the whole over-fetched pool BEFORE selectSuggestions, so the rotation and diversity rules operate on blended scores — boosting only the twelve already chosen by similarity would leave the re-ranking undone. A query failure is returned, NOT degraded past. Graceful degradation is for expected absence (no taste profile, no cached tags) and both are handled explicitly as empty inputs; swallowing a real error would hide a broken DB behind a subtly worse ranking that nothing reports. Migration 0051 adds a FOURTH tuning scope rather than columns on taste_tuning, because snooze_days lives here too and a snooze must never be read as taste signal (#2374) — filing it under 'taste' would put it one careless join from the leak that design forbids. Expanding recommendation_tuning_audit's CHECK is in the same migration per rule #36, and a test asserts the audit row lands, which is what would catch its absence. snooze_days moves out of a Go constant onto the tuning card (rule #25), closing the deferral from #2374. Tag-overlap tests use deliberately SKEWED fixtures: an evenly-matching pool cannot exercise a re-ranking, since every candidate gets the same multiplier and the order is unchanged whether the blend works or not. Admin UI + client attribution follow in this batch — rule #27. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-02 20:31:12 -04:00
bvandeusenandClaude Opus 5	7315e37c15	fix(db): apply sqlc's actual output for candidate_artist_tags — #2376 ... Three divergences in the hand-written generated file, all caught by verify-generate on the first run. Two are sqlc rules I had wrong: 1. When a query's SELECT list exactly matches a table's columns in order, sqlc REUSES the model struct rather than emitting a bespoke Row type. So ListCandidateArtistTagsForMbids returns []CandidateArtistTag, and ListCandidateArtistTagsForMbidsRow should never have existed. 2. models.go is ordered by GO STRUCT NAME, not table name. Table order would put candidate_artist_tag_state before candidate_artist_tags; sqlc emits CandidateArtistTag before CandidateArtistTagState. The earlier slice-3 observation ("ordered by table name") was consistent with both orderings and so never discriminated — this case does. 3. sqlc smart-quotes a doubled '' inside a promoted comment into a typographic ”. Reworded the prose to say "the empty string" instead of encoding a mangling into the source. Note the integration lane PASSED on the broken push while this failed. That is #2380's lesson landing again, and the reason the check exists: valid SQL executing against real Postgres proves nothing about whether the committed Go matches its source. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-02 20:11:03 -04:00
bvandeusenandClaude Opus 5	4f9b083eec	feat(discover): artist-tag cache for out-of-library candidates — #2376 ... Migration 0050 adds candidate_artist_tags + candidate_artist_tag_state: folksonomy tags for artists NOT in the library, which track_tags cannot hold because it's FK'd to tracks(id) and a Discover candidate has no local row. Slice 6 ranks against these; this slice only fills the cache. The reuse the task claimed is real and verified: MusicBrainz's fetchEntityTags(ctx, "artist", mbid, scale) already existed for the #1519 recording→artist fallback, so FetchArtistTags is a thin wrapper. Two subtleties it does NOT inherit: - Weight scale is 1.0, not artistTagWeightFactor (0.6). That discount exists because FetchTrackTags uses artist tags as a *proxy* for a track's; here the artist IS the subject. Applying it would make these weights incomparable with track_tags — exactly the comparison slice 6 depends on. Pinned by a test. - fetchEntityTags reports existing-but-untagged as (empty, nil) so the track path can fall through. There's no next level here, so empty becomes the terminal ErrNotFound; otherwise the enricher would settle a candidate as "enriched" with zero tags. ArtistTagProvider is the split TrackTagProvider's own doc comment anticipated ("e.g. artist-level tags"). Last.fm gains artist.getTopTags, which returns the same toptags envelope, so the response type and normalizer are reused unchanged. Rather than write the merge-and-classify loop twice, extracted it from EnrichTrack into runChain(). The ErrNotFound-vs-transient split is the load-bearing part — those lead to opposite persistence decisions — so it now has direct unit tests it never had while inlined. Bookkeeping is a separate table, not columns, because the "providers had nothing" outcome must be recordable for a candidate with zero tag rows, and there is no per-candidate row to hang columns off ( artist_similarity_unmatched holds many rows per candidate). Absence of a state row means "never processed", so a transient failure writes nothing and stays eligible. Two capacity realities are designed for, not papered over: - The pool is O(library artists x neighbours) and MusicBrainz allows ~1 req/s, so it can never drain in one pass. The eligibility query returns candidates in descending summed-similarity order, so the ones that can actually reach a deck are enriched first. - candidateBatch (50) is smaller than the track batch (200): tracks are finite and drain to completion, candidates are effectively unbounded and would otherwise starve the track arm forever. GC sweeps both tables — the similarity feed churns, and a candidate that joins the library has its tags in track_tags now. Tags swept before state so a mid-sweep crash leaves a valid state, not a re-fetch loop. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-02 20:04:15 -04:00
bvandeusenandClaude Opus 5	86af79bd2f	feat(discover): time-boxed suggestion snooze, server side — #2374 ... Migration 0049 adds suggestion_snoozes(user_id, candidate_mbid, candidate_name, snoozed_until), and SuggestArtistsForUser excludes rows whose snooze hasn't expired. This is NOT a dislike. Rule #101 forbids a "Not for me" / thumbs-down UI; a snooze is the approved shape instead because it records no verdict on the music, expires on its own (~90d), and never reaches the taste profile. It's acquisition triage — "not right now" — so the filter sits at the candidate stage rather than in the score, where it would become a ranking signal by the back door. Per-user throughout (rule #47): one household member parking a candidate leaves everyone else's deck untouched. candidate_name is denormalized because suggestions are out-of-library by definition — there is no artists row to resolve a display name from, and the un-snooze list has to show something. That list is why GET /discover/snoozes exists at all: a parked candidate is by definition absent from the deck, so without it the DELETE would be unreachable. Also fixes a hole in the codegen check from #2380: `git diff` ignores untracked paths, so a brand-new generated file would have passed it silently. `git add -N` first. This commit is the first to add one. Endpoints: POST /api/discover/suggestions/{mbid}/snooze (body: name, days) DELETE /api/discover/suggestions/{mbid}/snooze GET /api/discover/snoozes UI lands in slice 4 (#2375) before any of this merges — rule #27. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-01 22:51:51 -04:00
bvandeusenandClaude Opus 5	e006de5d4b	fix(db): apply sqlc's actual output for SuggestArtistsForUser — #2380 ... The new codegen check failed on its first run, against the slice-1 hand-edit, which is precisely why it landed on its own commit. What I got wrong: sqlc does not embed the leading `--` header block in the SQL const. It strips those lines and promotes them to the generated method's Go doc comment, gofmt-formatted — blank `//` separators around the indented list, tabs for the indent. My hand-edit left the header inside the string AND left the stale M5c doc comment sitting on the function, so the generated file described behaviour the query no longer had. Comments *inside* the statement body are kept as-is; only the header block moves. Worth knowing before slices 5 and 6 add more queries. Taken verbatim from the diff the check printed, which is the reason it prints before asserting. Round-trip cost: one CI run, no guessing. Note the integration lane passed on the previous push even with the wrong generated file — the SQL text was valid and the signature was unchanged, so executing it against real Postgres proved nothing about whether the committed Go matched its source. That gap is exactly what #2380 closes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-01 22:23:35 -04:00
bvandeusenandClaude Opus 5	b27029f674	feat(discover): rotate the suggestion deck daily + cap one seed's share — #2373 ... Second half of the reported symptom: suggestions "show the same artists until you request one". The ranking was `ORDER BY total_score DESC` with no randomization and no seen-state, so the only things that could ever change the deck were a candidate entering the library or the user filing a request. The tail of the ranking was unreachable — requesting was literally the only lever. No SQL change was needed. The query already takes a limit, so it over-fetches a pool (4x the slots, capped at 60) and the selection moves to Go, where it is a pure function of (pool, limit, day) — no DB, no clock — and therefore unit testable in the fast lane instead of behind the integration gate. Three rules. The best few by score always lead, so the strongest matches never rotate out of sight (For You's head/tail shape). The remaining slots are drawn by md5(mbid + day), the same daily-stable idiom the Home rows already use: stable within a day so pull-to-refresh doesn't reshuffle, different tomorrow, and no stored state. And a per-seed cap keeps roughly a quarter of the deck attributable to any one seed artist, so twelve neighbours of a single artist can't be the whole surface. The cap is a preference, not a quota. A user whose pool hangs off one or two seeds would otherwise get a three-card surface — worse than the monoculture being avoided, and exactly the vanish-or-nothing shape rule #131 exists to prevent — so a short deck tops up in score order from what the cap set aside. This is also what keeps the existing Top12Cap integration test honest: its 30 candidates share one seed, and without the top-up it would return 3. Eight unit tests, including one that had to be rewritten mid-change: the first version asserted the cap against an evenly-spread pool, where the top-N is already diverse and the assertion could not fail. It now uses a skewed pool where one seed owns the entire top of the ranking, which is the only shape that actually exercises a cap. Dropped two //nolint:gosec directives added in passing — gosec isn't in .golangci.yml, so they suppressed nothing and only implied a check that runs. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-01 12:56:42 -04:00
bvandeusenandClaude Opus 5	14aa22198f	feat(discover): seed request suggestions from the taste profile — #2372 ... The Discover request surface was the one recommendation surface still on its M5c implementation from early May. #796's taste profile, #1488's taste_unheard bucket and #1490's folksonomy enrichment all modernized in-library surfaces; this one was never in scope for any of them, so it still projected raw likes + plays through artist_similarity_unmatched. Two defects fall out of that signal, `5*liked + Σexp(-age/halflife)` summed over every play of the artist. It is unbounded, and contribution is signal × similarity — so a handful of heavily-played artists monopolize all twelve slots, and their share GROWS the more the user listens. The surface entrenched harder the better it knew you, which is exactly backwards and matches the reported "goes stale once it has a strong signal of your taste". It also counted every play_event with no was_skipped filter, so skipping an artist repeatedly INCREASED its signal and pushed more of its neighbours at the user. ListMostPlayedTracksForUser and the taste engine both filter skips; this query was the odd one out. Seeds now come from taste_profile_artists.weight, which the taste engine has already engagement-graded, time-decayed and signed — an artist the user drifted away from stops contributing instead of accumulating forever, and can even contribute negatively. Tiered per rule #131 rather than hard-switched: tier 1 is the profile, tier 2 is likes + completed plays for a user who has no profile rows yet (new account, or before the first daily recompute), so the surface never empties. The old unfiltered-play signal is gone, not kept behind a toggle. The signal is also log-damped, so one artist cannot take every slot even when its weight dwarfs the rest. $2 stays wired to the tier-2 decay: it is genuinely still used there, and dropping the parameter would have changed the generated signature. sqlc's image is not on this workstation and the change preserves the query signature exactly — same three params, same seven columns — so only the embedded SQL const moves. Both copies are edited and verified byte-identical rather than pulling a container onto the operator's machine; a malformed query fails the integration lane loudly, which is the real check either way. Four integration tests cover what changed: a taste weight alone seeds with no like or play; tier 2 does not run alongside tier 1; a non-positive weight never seeds (guarded by a second positive row, so an empty tier 1 can't make it pass for the wrong reason); and skip-only history seeds nothing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-01 12:45:34 -04:00
bvandeusenandClaude Opus 4.8	5749f48b4a	feat(taste): device-class context conditioning — #1551 ... Milestone #160 Opt 3b. Adds device class as a third context axis on top of the #1531 time-of-day/weekday affinity: on the radio path, a candidate is boosted when its artist concentrates in the current (daypart × weekday × device) cell. Client-sent (client_id is opaque; no UA stored), so it's captured going forward and applies to radio only (daily mixes are cron-built with no device → stay device-agnostic). Server: - Migration 0048: play_events.device_class text NULL (no CHECK; normalized in Go — one whitelist entry per new client class, not a migration). - events.go: eventRequest.device_class + normalizeDeviceClass (whitelist → mobile/web/…, else "other", empty → NULL); threaded through both RecordPlayStartedWithSource and RecordOfflinePlay into InsertPlayEvent. - ListArtistContextPlayCountsForUser gains a current-device param; the cell FILTER adds AND ($2='' OR device_class=$2) — '' reproduces the #1531 time-only behaviour exactly (used by mixes). SessionVector.DeviceClass carries it; the radio handler derives the current device from the user's latest play (GetLatestPlayDeviceClassForUser) — request-free proxy. - No new tuning knob: device narrows the existing ContextAffinityScore (reuses context_time_weight). Clients: - web: play_started sends device_class 'web'. - android: play_started + offline replay send 'mobile' (EventsWire + PlayOfflinePayload + MutationReplayer + PlayEventsReporter). Test: LoadContextAffinity device-narrowing integration test (mobile vs web artist separation; device-agnostic parity). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-14 12:47:59 -04:00
bvandeusenandClaude Opus 4.8	f0c08e7326	feat(taste): mood taste facet — #1534 ... Milestone #160 Opt 2b (mood half of the era+mood option). A fourth taste facet alongside artists + genre tags + eras: signed weights over canonical mood buckets (melancholic / energetic / chill / …) derived from a track's enriched folksonomy tags (#1490). - internal/mood: shared vocabulary — Of(tags) maps folksonomy tags to canonical mood buckets (synonyms collapse). Imported by both the taste builder and the scorer so a track's mood is derived identically. - Migration 0047: taste_profile_moods table + taste_tuning.mood_scale (DEFAULT 0.5). - Build side (internal/taste): Config.MoodScale ([0,1] damper, mirrors EraScale); accumulate folds each play/like's mood buckets at base*MoodScale; persist atomic-replaces the mood rows. - Scorer (internal/recommendation): TasteProfile gains a mood term (own tanh scale + additive 0.12 share, so it never weakens the existing signal when a track has no mood tags). Match now takes the candidate's mood buckets; loaded per candidate (ListTrackTagsForTracks → mood.Of) in the primary similarity loader only — the near-whole-library fallback pool passes nil (mood → 0) to avoid a full-library tag scan. - Tuning lab: mood_scale threaded through recsettings + admin API + web card ("Mood weight" row) + Go/web tests. Coverage is partial (grows with tag enrichment; richer once Last.fm is keyed), so mood is a supplement — neutral for tracks with no mood tags. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-14 10:32:41 -04:00
bvandeusenandClaude Opus 4.8	199fec2058	feat(taste): household co-play similarity — #1533 ... Milestone #160 Opt 5. A collaborative candidate arm: tracks by artists co-played across the instance with the seed's artist. Minstrel is a single shared-library, multi-user server (no per-user library ACL — verified: no owner/share/group model), so the "household" is the whole instance's user set; the rule #47 scoping is satisfied by the shared-library boundary. Single-user servers produce no edges. - No migration: source='user_cooccurrence' was pre-whitelisted in the 0009 similarity CHECK from day one. - internal/db/queries/coplay.sql: Delete + Insert artist co-play edges. Score = Jaccard of the two artists' distinct-player sets (controls for globally-popular artists); >= 2 co-players AND Jaccard >= floor kept (the floor also self-limits hub artists). Completed plays, 365d window. - internal/coplay: periodic worker (6h) that atomic-replaces the user_cooccurrence edge set from play_events — pure local SQL, no external calls. Wired in main.go alongside the similarity worker. - LoadRadioCandidatesV2: new coplay_artists arm (source='user_cooccurrence', seed-artist based, 0.5 damp like similar_artists) + $11 limit; CandidateSourceLimits.UserCoplay (default 20, For-You 40). - Integration tests: perfect-overlap Jaccard=1.0 edge + single-user empty-set gate. Device axis and AcousticBrainz (Opt 4) are separately tracked; this closes the milestone-#160 sequential options. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-14 10:07:19 -04:00