Compare commits

...
2 Commits
Author SHA1 Message Date
bvandeusenandClaude Opus 5.5 6028d78844 docs: migration headers keep the before and after, without ids, quotes or one library's numbers (#6277)
release / govulncheck (push) Successful in 17s
release / web (push) Successful in 1m33s
release / go (push) Successful in 1m49s
release / integration (push) Successful in 5m42s
release / android (push) Successful in 5m59s
release / Build signed APK (releases and dev) (push) Successful in 6m9s
release / Attach APK to the Release (tag releases only) (push) Skipped
release / Build + push container image (push) Successful in 16s
release / Verify release artifacts (tag releases only) (push) Skipped
Applies rule 32's migration exception: each header still says what the
schema was, what changes and what it prevents, but task, milestone,
decision and rule ids are replaced by the practice they stood for, the
operator quotes by the decision, single-install counts are dropped, and
pointers to a deleted package and an external design doc are gone.
golang-migrate keeps no checksum, so editing applied migrations'
comments is safe.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-23 12:34:39 -04:00
bvandeusenandClaude Opus 5.5 1d4ef1a23f docs: query comments say what each query selects and why, not how it came to be (#6277)
Rewrites the internal/db/queries comments to rule 32 and regenerates
dbq, whose doc comments and embedded SQL carry them. The bugs behind the
tiered mixes, the md5 order seed, the score bands and the round-robin
arms are restated as the constraint each one enforces; counts from one
library and stale cross-references are gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-23 12:31:13 -04:00
193 changed files with 949 additions and 1036 deletions
+2 -2
View File
@@ -120,7 +120,7 @@ type ListTracksNeedingAcoustIDLookupRow struct {
DurationMs int32
}
// AcoustID recording-id lookup (M401). Migration 0069 says what each
// AcoustID recording-id lookup. Migration 0069 says what each
// lookup state means.
// The lookup worker's queue: present tracks with no tag MBID and no lookup
// since their file last changed. A looked-up id is included once its row is
@@ -257,7 +257,7 @@ type SetTrackMbidFromAcoustIDParams struct {
ID pgtype.UUID
}
// Never over a tag id (D4): the guard is here, not only in the worker, so a
// Never over a tag id: the guard is here, not only in the worker, so a
// tag the scan read between the worker's list and this write still wins.
// updated_at is left alone: it gates the scan's mtime skip, and moving it
// past a file's mtime would hide a change made just before the lookup.
+1 -1
View File
@@ -147,7 +147,7 @@ type ListAcquisitionServicesRow struct {
UpdatedAt pgtype.Timestamptz
}
// Indexers and download clients (M502 #5518).
// Indexers and download clients.
// Returns no secret, only whether one is set: this feeds the settings page.
func (q *Queries) ListAcquisitionServices(ctx context.Context) ([]ListAcquisitionServicesRow, error) {
rows, err := q.db.Query(ctx, listAcquisitionServices)
+1 -1
View File
@@ -109,7 +109,7 @@ type ListListeningNowRow struct {
AlbumTitle string
}
// The admin Overview's status sections (M504): who is listening, what is
// The admin Overview's status sections: who is listening, what is
// downloading, what the library holds. Each is one cheap read.
// Plays in progress: open play events still inside their track's length,
// with a few minutes' grace for a pause. A client that never says a play
+3 -3
View File
@@ -16,7 +16,7 @@ SELECT
(SELECT count(*) FROM requests WHERE status = 'pending')::bigint AS requests,
(SELECT min(requested_at) FROM requests WHERE status = 'pending')::timestamptz AS requests_since,
-- A broken track is one report however it was found: a listener flagged
-- it, or it failed to play (#5606). Counted by track, as the Reports
-- it, or it failed to play. Counted by track, as the Reports
-- page lists them.
(SELECT count(*) FROM (
SELECT track_id FROM quarantine
@@ -53,11 +53,11 @@ type AdminSummaryRow struct {
MissingSince pgtype.Timestamptz
}
// What the admin rail and the Overview's verdict read (#5605): each queue
// What the admin rail and the Overview's verdict read: each queue
// that waits on a person, with how many and since when. One round trip, so
// the rail costs one cheap read on every admin page. The "since" is the
// oldest item still waiting: how long the queue has been left, which is what
// tells the operator a count of 2 is fine today and wrong after a month.
// tells an admin a count of 2 is fine today and wrong after a month.
func (q *Queries) AdminSummary(ctx context.Context) (AdminSummaryRow, error) {
row := q.db.QueryRow(ctx, adminSummary)
var i AdminSummaryRow
+22 -27
View File
@@ -15,7 +15,7 @@ const countAlbums = `-- name: CountAlbums :one
SELECT COUNT(*) FROM albums
`
// M6a: total album count for the /api/library/albums envelope.
// Total album count for the /api/library/albums envelope.
func (q *Queries) CountAlbums(ctx context.Context) (int64, error) {
row := q.db.QueryRow(ctx, countAlbums)
var count int64
@@ -59,7 +59,7 @@ type DeleteAlbumIfEmptyRow struct {
ArtistID pgtype.UUID
}
// M7 #372: deletes the album row only when it has no remaining tracks.
// Deletes the album row only when it has no remaining tracks.
// Used after a track delete to tidy up orphaned albums. RETURNING gives
// us the artist_id so the service can chain into the artist-empty check.
// Returns no rows when the album still has tracks; the service treats
@@ -91,12 +91,12 @@ type GetAlbumByArtistAndTitleParams struct {
}
// Scanner uses this for the no-mbid dedupe path: resolve-or-create. An album
// of the same name in another release group is a different album (Weezer's
// six self-titled albums shared one row until 2026-10-20), so a row whose
// of the same name in another release group is a different album (one
// artist's self-titled albums), so a row whose
// group is known and differs is not returned. A row of the file's own group
// comes first, then one with no group yet, then the one holding the most
// tracks from the file's folder: a file tagged with no group (a live bonus
// track beside Weezer's 1994 album) belongs with its folder, not the oldest
// track beside its album) belongs with its folder, not the oldest
// row, and a few strays already misfiled do not outvote the folder.
func (q *Queries) GetAlbumByArtistAndTitle(ctx context.Context, arg GetAlbumByArtistAndTitleParams) (Album, error) {
row := q.db.QueryRow(ctx, getAlbumByArtistAndTitle,
@@ -166,7 +166,7 @@ type GetAlbumCoverageRollupRow struct {
PendingNoMbid int64
}
// M7 coverage-gauge: library-wide cover-art coverage rollup for the
// Library-wide cover-art coverage rollup for the
// admin gauge. Single sequential scan with FILTER aggregates —
// sub-millisecond on realistic libraries. pending_no_mbid is a SUBSET
// of pending; the UI surfaces it separately so operators can see how
@@ -176,12 +176,9 @@ type GetAlbumCoverageRollupRow struct {
// Invariant: with_art + pending + settled = total. (pending_no_mbid is
// not part of the sum — it's a subset of pending, surfaced separately.)
//
// The IN list below must stay in sync with the cover_art_source CHECK
// constraint — currently relaxed by migration 0020 to include 'deezer'
// and 'lastfm', and migration 0030 further relaxed it to any non-empty
// string. If a new source value is added without updating this query,
// with_art will silently undercount. Drift #556 caught the deezer +
// lastfm omission introduced by migration 0020.
// The IN list below must name every source the enrichers write (the
// cover_art_source CHECK accepts any non-empty string since migration
// 0030). A source missing here makes with_art silently undercount.
func (q *Queries) GetAlbumCoverageRollup(ctx context.Context) (GetAlbumCoverageRollupRow, error) {
row := q.db.QueryRow(ctx, getAlbumCoverageRollup)
var i GetAlbumCoverageRollupRow
@@ -236,7 +233,7 @@ SELECT id, title, sort_title, artist_id, release_date, mbid, cover_art_path, cre
`
// Batched lookup used by /api/library/sync to hydrate upsert payloads
// (#357). Mirror of GetArtistsByIDs.
// . Mirror of GetArtistsByIDs.
func (q *Queries) GetAlbumsByIDs(ctx context.Context, dollar_1 []pgtype.UUID) ([]Album, error) {
rows, err := q.db.Query(ctx, getAlbumsByIDs, dollar_1)
if err != nil {
@@ -277,7 +274,7 @@ SELECT release_group_mbid::text
LIMIT 1
`
// #5241: the release group the library already knows for a release id, so a
// The release group the library already knows for a release id, so a
// request carrying a release id can be repaired without asking MusicBrainz.
func (q *Queries) GetReleaseGroupForReleaseMbid(ctx context.Context, mbid *string) (string, error) {
row := q.db.QueryRow(ctx, getReleaseGroupForReleaseMbid, mbid)
@@ -400,7 +397,7 @@ type ListAlbumsAlphaWithArtistRow struct {
ArtistName string
}
// M6a: alpha-sorted album list joined with artist_name. Used by
// Alpha-sorted album list joined with artist_name. Used by
// /api/library/albums for the wrapping-grid page. Stable id-tiebreak.
func (q *Queries) ListAlbumsAlphaWithArtist(ctx context.Context, arg ListAlbumsAlphaWithArtistParams) ([]ListAlbumsAlphaWithArtistRow, error) {
rows, err := q.db.Query(ctx, listAlbumsAlphaWithArtist, arg.Limit, arg.Offset)
@@ -547,12 +544,10 @@ type ListAlbumsByGenreParams struct {
// Album "belongs to" a genre if any of its tracks carry that genre.
// Serves Subsonic getAlbumList?type=byGenre.
//
// Splits tracks.genre on [;,] as of #367. It previously compared the whole
// column verbatim, so a track tagged "Rock;Pop" was unreachable from EITHER
// "Rock" or "Pop" — a Subsonic client asking for a genre silently missed
// every multi-genre track. This also aligns the endpoint with
// recommendation.sql / discover.sql, which have always split, and with the
// genre browse index that #367 adds.
// Splits tracks.genre on [;,], so a track tagged "Rock;Pop" is reachable from
// both "Rock" and "Pop"; comparing the whole column would hide every
// multi-genre track from a Subsonic client asking for a genre. The same split
// as recommendation.sql, discover.sql and the genre browse index.
//
// EXISTS rather than JOIN + DISTINCT ON: the lateral split emits one row per
// (track, genre-fragment), so a join would multiply rows per album and lean
@@ -620,7 +615,7 @@ type ListAlbumsMissingMbidWithTrackRow struct {
// one of its tracks' file_path so the worker can re-read tags. LIMIT
// supplied by caller for batching/progress purposes. The track read is
// one still on disk; an album with none left is skipped until a scan
// finds its files again (#5139).
// finds its files again.
func (q *Queries) ListAlbumsMissingMbidWithTrack(ctx context.Context, limit int32) ([]ListAlbumsMissingMbidWithTrackRow, error) {
rows, err := q.db.Query(ctx, listAlbumsMissingMbidWithTrack, limit)
if err != nil {
@@ -738,7 +733,7 @@ type ListRecentlyAddedAlbumsWithArtistRow struct {
ArtistName string
}
// M6a: recently-added albums joined with artist_name + artist_id for the
// Recently-added albums joined with artist_name + artist_id for the
// home-page section. created_at is the row-insert timestamp from the
// scanner — the closest proxy to "added to library". Stable secondary
// ordering by id keeps pagination tie-break deterministic.
@@ -838,7 +833,7 @@ type SetAlbumCoverWithVersionParams struct {
CoverArtSourcesVersion int32
}
// M7 cover-sources: records a successful or settled enrichment with the
// Records a successful or settled enrichment with the
// current sources_version stamp. cover_art_path is NULL when source is
// 'none' (no file written). Atomic; called per album per pass.
func (q *Queries) SetAlbumCoverWithVersion(ctx context.Context, arg SetAlbumCoverWithVersionParams) error {
@@ -863,7 +858,7 @@ type SetAlbumMbidIfNullParams struct {
Mbid *string
}
// M7 #379: heal MBID on existing album rows during rescan. Idempotent —
// Heal MBID on existing album rows during rescan. Idempotent —
// only updates when the existing mbid is NULL.
func (q *Queries) SetAlbumMbidIfNull(ctx context.Context, arg SetAlbumMbidIfNullParams) error {
_, err := q.db.Exec(ctx, setAlbumMbidIfNull, arg.ID, arg.Mbid)
@@ -882,7 +877,7 @@ type SetAlbumReleaseGroupMbidIfNullParams struct {
ReleaseGroupMbid *string
}
// #5241: heal the release-group id on an existing album row, from a rescan's
// Heal the release-group id on an existing album row, from a rescan's
// tags or from the re-acquisition sweeper's MusicBrainz lookup. Only fills a
// NULL, so a tag never gets overwritten by a later guess or vice versa.
func (q *Queries) SetAlbumReleaseGroupMbidIfNull(ctx context.Context, arg SetAlbumReleaseGroupMbidIfNullParams) error {
@@ -902,7 +897,7 @@ type SetReleaseGroupForReleaseMbidIfNullParams struct {
ReleaseMbid string
}
// #5241: cache a MusicBrainz-resolved release group onto the album row that
// Cache a MusicBrainz-resolved release group onto the album row that
// holds the release, filling only a NULL.
func (q *Queries) SetReleaseGroupForReleaseMbidIfNull(ctx context.Context, arg SetReleaseGroupForReleaseMbidIfNullParams) error {
_, err := q.db.Exec(ctx, setReleaseGroupForReleaseMbidIfNull, arg.ReleaseGroupMbid, arg.ReleaseMbid)
+6 -6
View File
@@ -19,7 +19,7 @@ UPDATE artists
AND artist_art_source = 'none'
`
// M7 cover-sources: parallel of ClearAlbumCoverNone. Used by the
// Parallel of ClearAlbumCoverNone. Used by the
// eligibility loop to flip stale 'none' rows back to NULL.
func (q *Queries) ClearArtistArtNone(ctx context.Context, id pgtype.UUID) error {
_, err := q.db.Exec(ctx, clearArtistArtNone, id)
@@ -56,7 +56,7 @@ WHERE a.id = $1
RETURNING a.id
`
// M7 #372: deletes the artist row only when it has no remaining albums
// Deletes the artist row only when it has no remaining albums
// AND no remaining tracks (defensive — tracks can in principle exist
// without an album, though the scanner doesn't write that shape today).
func (q *Queries) DeleteArtistIfEmpty(ctx context.Context, id pgtype.UUID) (pgtype.UUID, error) {
@@ -253,7 +253,7 @@ type ListArtistsAlphaWithCoversRow struct {
AlbumCount int64
}
// M6a: alpha-sorted artist list with derived cover_album_id (most-recent
// Alpha-sorted artist list with derived cover_album_id (most-recent
// album whose cover_art_path is set). Replaces ListArtistsAlpha for the
// /api/artists?sort=alpha branch — the new column is appended, so the
// alpha branch is purely additive on the wire. album_count is computed
@@ -305,7 +305,7 @@ type ListArtistsMissingArtParams struct {
Limit int32
}
// M7 cover-sources: returns artist rows the artist-art enricher should
// Returns artist rows the artist-art enricher should
// attempt. Eligible: artist_art_source IS NULL OR (= 'none' AND stale
// artist_art_sources_version). MBID-less artists are returned but the
// enricher skips them at the row.mbid == nil guard inside the chain.
@@ -432,7 +432,7 @@ type SetArtistArtWithVersionParams struct {
ArtistArtSourcesVersion int32
}
// M7 cover-sources: records a successful or settled artist-art
// Records a successful or settled artist-art
// enrichment with the current sources_version stamp. thumb_path /
// fanart_path are NULL on a 'none' result, or independently NULL if
// the provider returned only one of the two image types (e.g.
@@ -460,7 +460,7 @@ type SetArtistMbidIfNullParams struct {
Mbid *string
}
// M7 #379: heal MBID on existing artist rows during rescan. Idempotent —
// Heal MBID on existing artist rows during rescan. Idempotent —
// only updates when the existing mbid is NULL, so concurrent scans don't
// overwrite an existing value with a stale one.
func (q *Queries) SetArtistMbidIfNull(ctx context.Context, arg SetArtistMbidIfNullParams) error {
+1 -1
View File
@@ -84,7 +84,7 @@ type ListAuditLogByActionsParams struct {
}
// One page of the given actions, newest first: the duplicates report's
// "resolved automatically" activity (M498) reads the resolver's merges from
// "resolved automatically" activity reads the resolver's merges from
// here.
func (q *Queries) ListAuditLogByActions(ctx context.Context, arg ListAuditLogByActionsParams) ([]AuditLog, error) {
rows, err := q.db.Query(ctx, listAuditLogByActions,
+16 -23
View File
@@ -75,7 +75,7 @@ type ListAlbumYearsWithCountRow struct {
AlbumCount int64
}
// Year browse index (#367). Only albums with a release_date appear — an
// Year browse index. Only albums with a release_date appear — an
// album with no date isn't "year unknown" as a browsable bucket, it's absent
// from this axis, and the UI says so rather than inventing a 0 row.
// Newest first: recent releases are the likelier browse target.
@@ -244,8 +244,7 @@ ORDER BY trim(g.genre)
// Distinct genres carried by an album's tracks, for the album detail page's
// quick-jump chips. Split and trimmed identically to ListGenresWithCount, so a
// chip always leads to a page that actually contains this album — the two
// diverging is exactly the bug #367 had to fix in ListAlbumsByGenre.
// chip always leads to a page that actually contains this album.
func (q *Queries) ListGenresForAlbum(ctx context.Context, albumID pgtype.UUID) ([]string, error) {
rows, err := q.db.Query(ctx, listGenresForAlbum, albumID)
if err != nil {
@@ -314,30 +313,24 @@ type ListGenresWithCountRow struct {
TrackCount int64
}
// Every query in this file filters `tracks.missing_since IS NULL` (#2523).
// A row whose file has vanished keeps its genre forever — the scanner walks the
// filesystem, so it never revisits a path that no longer exists — which is how
// pre-#2499 welded genres survived a full re-scan and kept showing in the index.
// Browsing is a way of finding something to play, so a track that cannot play
// Every query in this file filters `tracks.missing_since IS NULL`. A row whose
// file has vanished keeps its genre forever — the scanner walks the
// filesystem, so it never revisits a path that no longer exists — and
// browsing is a way of finding something to play, so a track that cannot play
// should not shape it.
//
// The year axis filters too (#2702). It used to join albums only, on the
// reasoning that an album is a real release even when some of its tracks are
// gone — true, but it left the two browse axes disagreeing: the genre queries
// above filter tracks.missing_since, so an album whose every file had vanished
// was already absent from genre while still listed under its year, where
// opening it found nothing playable.
// The year axis filters too, so the two axes agree: an album whose every file
// has vanished is absent from both, rather than absent from its genre and
// still listed under its year, where opening it would find nothing playable.
//
// Hiding is the answer rather than showing-and-marking because browsing is how
// you go looking for something to play, and the operator's rule for that case
// is to take it out of view; the admin missing-files surface is where absence
// is reported. It also means changing the axis that was inconsistent rather
// than the one that was already right.
// Hiding rather than showing-and-marking, because browsing is how you go
// looking for something to play; the admin missing-files surface is where
// absence is reported.
//
// The predicate is "has at least one playable track", so it also excludes an
// album with no tracks at all. That is the same answer for the same reason:
// nothing to play, nothing to browse to.
// Genre browse index (#367).
// Genre browse index.
//
// Genres live inline on tracks.genre as a delimited string, so this splits on
// the same [;,] pattern already used by recommendation.sql and discover.sql —
@@ -348,14 +341,14 @@ type ListGenresWithCountRow struct {
// trim() but deliberately NO lower(): trimming repairs an artifact of OUR
// splitting ("Rock; Pop" yields " Pop", and showing that as a distinct genre
// would be a bug), whereas case is what the tag actually says. Raw ID3 is
// exposed as-is for v1, so "Rock" and "rock" appear as separate rows.
// exposed as-is, so "Rock" and "rock" appear as separate rows.
//
// COUNT(DISTINCT) because a sloppy tag like "Rock;Rock" would otherwise
// inflate its own row.
//
// Ordered by count first: raw ID3 data has a long tail of one-off junk tags,
// so alphabetical would bury the handful of genres an operator actually has a
// library's worth of. Name breaks ties for a stable order.
// so alphabetical would bury the handful of genres a library actually has
// a lot of. Name breaks ties for a stable order.
// Ordered by the expression, not the output alias: `ORDER BY genre` is
// ambiguous between the alias and tracks.genre, and sqlc rejects it.
func (q *Queries) ListGenresWithCount(ctx context.Context) ([]ListGenresWithCountRow, error) {
+2 -2
View File
@@ -110,7 +110,7 @@ SELECT candidate_mbid, tag, weight
WHERE candidate_mbid = ANY($1::text[])
`
// Cached tags for a set of candidates, for slice 6's taste-overlap ranking.
// Cached tags for a set of candidates, for the taste-overlap ranking.
// One row per (candidate, tag).
func (q *Queries) ListCandidateArtistTagsForMbids(ctx context.Context, dollar_1 []string) ([]CandidateArtistTag, error) {
rows, err := q.db.Query(ctx, listCandidateArtistTagsForMbids, dollar_1)
@@ -160,7 +160,7 @@ type ListCandidateArtistsMissingTagsRow struct {
TotalScore float64
}
// Folksonomy tags for out-of-library Discover candidates (#2376). Parallel to
// Folksonomy tags for out-of-library Discover candidates. Parallel to
// track_tags.sql, but keyed by MBID because the artist has no local row. See
// 0050_candidate_artist_tags.up.sql for why the bookkeeping is its own table.
// Candidates eligible for tag enrichment: never processed (no state row) or
+1 -1
View File
@@ -352,7 +352,7 @@ type UpsertMBArtistParams struct {
Country string
}
// The release catalogue read from MusicBrainz (M502 #5519).
// The release catalogue read from MusicBrainz.
func (q *Queries) UpsertMBArtist(ctx context.Context, arg UpsertMBArtistParams) error {
_, err := q.db.Exec(ctx, upsertMBArtist,
arg.Mbid,
+1 -1
View File
@@ -14,7 +14,7 @@ const deleteArtistCoplayEdges = `-- name: DeleteArtistCoplayEdges :exec
DELETE FROM artist_similarity WHERE source = 'user_cooccurrence'
`
// Household co-play similarity (#1533, milestone #160 Opt 5). Minstrel is a
// Household co-play similarity. Minstrel is a
// single shared-library, multi-user server (no per-user library ACL), so the
// "household" is the whole instance's user set. These queries recompute
// artist–artist co-occurrence edges from play_events and store them in
+2 -2
View File
@@ -77,7 +77,7 @@ SELECT provider_id, enabled, api_key, display_order, created_at, updated_at
ORDER BY display_order, provider_id
`
// M7 cover-sources: queries for the cover_art_provider_settings table
// Queries for the cover_art_provider_settings table
// and the cover_art_sources_meta singleton. The SettingsService
// consumes these.
// Returns all rows from cover_art_provider_settings. Used by the
@@ -155,7 +155,7 @@ type UpsertProviderSettingsParams struct {
// INSERT a default row for a newly-registered provider, or update an
// existing row's display_order on boot reconciliation. Does NOT
// overwrite enabled / api_key on conflict — the operator's settings
// overwrite enabled / api_key on conflict — an admin's settings
// persist across restarts.
func (q *Queries) UpsertProviderSettings(ctx context.Context, arg UpsertProviderSettingsParams) error {
_, err := q.db.Exec(ctx, upsertProviderSettings, arg.ProviderID, arg.Enabled, arg.DisplayOrder)
+3 -3
View File
@@ -31,7 +31,7 @@ UPDATE albums
WHERE id = $1 AND cover_art_source = 'none'
`
// M7 #380: when MBID backfill heals an album, clear its 'none' cover_art_source
// When MBID backfill heals an album, clear its 'none' cover_art_source
// back to NULL so the enricher's next batch retries the MBCAA fetch.
// Idempotent — only updates rows currently stamped 'none'.
func (q *Queries) ClearAlbumCoverNone(ctx context.Context, id pgtype.UUID) error {
@@ -128,8 +128,8 @@ type ListAlbumsMissingCoverParams struct {
Limit int32
}
// M7 #353: album cover enrichment queries.
// M7 cover-sources: returns rows the enricher should attempt. Eligible:
// Album cover enrichment queries.
// Returns rows the enricher should attempt. Eligible:
// cover_art_source IS NULL (never tried), OR cover_art_source = 'none'
// AND cover_art_sources_version != current (settled under an older
// source set; recheck against the current chain). LIMIT supplied by
+14 -14
View File
@@ -15,7 +15,7 @@ const listCrossUserLikedTracksForDiscover = `-- name: ListCrossUserLikedTracksFo
SELECT t.id, t.album_id, t.artist_id
FROM general_likes gl
JOIN tracks t ON t.id = gl.track_id
WHERE t.missing_since IS NULL -- #2523: never offer a file that is gone
WHERE t.missing_since IS NULL -- never offer a file that is gone
AND gl.user_id != $1
AND NOT EXISTS (
SELECT 1 FROM play_events pe
@@ -55,8 +55,8 @@ type ListCrossUserLikedTracksForDiscoverRow struct {
//
// GROUP BY (not SELECT DISTINCT) so the md5 ORDER BY expression need
// not appear in the select list — Postgres rejects DISTINCT + ORDER BY
// by-expression at plan time (SQLSTATE 42P10), which previously caused
// the entire Discover build to fail silently.
// by-expression at plan time (SQLSTATE 42P10), which would fail the
// entire Discover build.
func (q *Queries) ListCrossUserLikedTracksForDiscover(ctx context.Context, arg ListCrossUserLikedTracksForDiscoverParams) ([]ListCrossUserLikedTracksForDiscoverRow, error) {
rows, err := q.db.Query(ctx, listCrossUserLikedTracksForDiscover, arg.UserID, arg.Column2)
if err != nil {
@@ -96,7 +96,7 @@ dormant_artists AS (
SELECT t.id, t.album_id, t.artist_id
FROM tracks t
JOIN dormant_artists da ON da.id = t.artist_id
WHERE t.missing_since IS NULL -- #2523: never offer a file that is gone
WHERE t.missing_since IS NULL -- never offer a file that is gone
AND NOT EXISTS (
SELECT 1 FROM play_events pe
WHERE pe.user_id = $1
@@ -161,7 +161,7 @@ func (q *Queries) ListDormantArtistTracksForDiscover(ctx context.Context, arg Li
const listRandomUnheardTracksForDiscover = `-- name: ListRandomUnheardTracksForDiscover :many
SELECT t.id, t.album_id, t.artist_id
FROM tracks t
WHERE t.missing_since IS NULL -- #2523: never offer a file that is gone
WHERE t.missing_since IS NULL -- never offer a file that is gone
AND NOT EXISTS (
SELECT 1 FROM play_events pe
WHERE pe.user_id = $1
@@ -223,7 +223,7 @@ WITH scored AS (
FROM tracks t
JOIN LATERAL regexp_split_to_table(coalesce(t.genre, ''), '[;,]') AS g_split(g) ON true
JOIN taste_profile_tags nt ON nt.user_id = $3 AND trim(g_split.g) = nt.tag
WHERE t.missing_since IS NULL -- #2523: never offer a file that is gone
WHERE t.missing_since IS NULL -- never offer a file that is gone
AND nt.weight > 0
AND trim(g_split.g) <> ''
AND NOT EXISTS (
@@ -274,7 +274,7 @@ type ListTasteUnheardTracksForDiscoverRow struct {
}
// Taste-targeted novelty: unheard tracks whose genres overlap the user's
// taste-profile tags (taste_profile_tags, #796), ranked by summed tag
// taste-profile tags (taste_profile_tags), ranked by summed tag
// weight — "new to you, but your vibe" rather than the crude random arm.
// Genres live inline on tracks.genre as a delimited string, split the
// same way the radio tag_overlap arm does (regexp_split_to_table on
@@ -282,13 +282,13 @@ type ListTasteUnheardTracksForDiscoverRow struct {
// when the user has no taste tags yet (cold start), so the caller
// redistributes its slots to the other buckets. Stamped 'taste_unheard'.
//
// The per-album and per-artist caps apply BEFORE the LIMIT (#5356). Summed
// weight rewards a track for carrying many of the user's tags, so a few
// artists whose every track is tagged with the whole profile take every row
// of a plain LIMIT; the caller's caps then left 6 of 120 on the deploy, and
// the best-performing arm handed its slots to the others. Ranking within
// album, then within artist over what the album cap kept, is the same walk
// capByAlbumAndArtist makes, so the caller's caps keep everything here.
// The per-album and per-artist caps apply BEFORE the LIMIT. Summed weight
// rewards a track for carrying many of the user's tags, so a few artists
// whose every track is tagged with the whole profile would take every row of
// a plain LIMIT, the caller's caps would then leave a handful, and the arm
// would hand its slots to the others. Ranking within album, then within
// artist over what the album cap kept, is the same walk capByAlbumAndArtist
// makes, so the caller's caps keep everything here.
func (q *Queries) ListTasteUnheardTracksForDiscover(ctx context.Context, arg ListTasteUnheardTracksForDiscoverParams) ([]ListTasteUnheardTracksForDiscoverRow, error) {
rows, err := q.db.Query(ctx, listTasteUnheardTracksForDiscover,
arg.MaxPerArtist,
+10 -10
View File
@@ -55,9 +55,9 @@ SELECT count(*)::bigint
END
`
// CountPendingDuplicateGroups narrowed to one view of the report (M498):
// CountPendingDuplicateGroups narrowed to one view of the report:
//
// review what the operator still has to decide: every class but
// review what an admin still has to decide: every class but
// cross_release, and groups not yet classified
// cross_release the same song on different releases, which is kept, not merged
func (q *Queries) CountPendingDuplicateGroupsInView(ctx context.Context, view string) (int64, error) {
@@ -205,7 +205,7 @@ type ListDismissedDuplicateMemberSetsRow struct {
TrackIds []pgtype.UUID
}
// What the operator has already said are not duplicates. A new proposal whose
// What an admin has already said are not duplicates. A new proposal whose
// every member sat together in one of these is not proposed again.
func (q *Queries) ListDismissedDuplicateMemberSets(ctx context.Context) ([]ListDismissedDuplicateMemberSetsRow, error) {
rows, err := q.db.Query(ctx, listDismissedDuplicateMemberSets)
@@ -236,7 +236,7 @@ SELECT t.id, t.duration_ms, f.audio_stream_sha256, f.chromaprint
AND f.chromaprint IS NOT NULL
-- Only chromaprints taken at the current length: prints at two lengths are not
-- comparable, and after a length change the backfill is still re-deriving the
-- rest (#3913).
-- rest.
AND f.chromaprint_length_sec = $2
AND (t.duration_ms, t.id) > ($3::integer, $4::uuid)
ORDER BY t.duration_ms, t.id
@@ -356,19 +356,19 @@ type ListDuplicateGroupsForResolveRow struct {
AcoustidRecording *string
}
// Every pending group's present copies, for the resolver (M498 #5435): what it
// Every pending group's present copies, for the resolver: what it
// needs to classify the group and to choose the copy to keep. One row per copy,
// grouped by group. position_clash is true when another present track on the
// same album claims the same disc and track number: tags that do not fit the
// album, which the survivor rule weighs against a copy. source_verdict says
// whether the copy is a video rip ('suspect') or one the operator kept ('fine').
// whether the copy is a video rip ('suspect') or one an admin kept ('fine').
// prior_class is the class the last pass gave the group, NULL for a group no
// pass has seen. release_group_mbid is the album's MusicBrainz group, from its
// tags or the library listing's match; ” when neither names one.
// acoustid_state and acoustid_recording are what AcoustID said of the file,
// when it was looked up (#6169: which song one recording cut to several slots
// is). group_id narrows it to one group, for the operator settling it (#6184);
// NULL reads them all.
// when it was looked up: which song a recording cut to several slots is.
// group_id narrows it to one group, for an admin settling it; NULL reads them
// all.
func (q *Queries) ListDuplicateGroupsForResolve(ctx context.Context, groupID pgtype.UUID) ([]ListDuplicateGroupsForResolveRow, error) {
rows, err := q.db.Query(ctx, listDuplicateGroupsForResolve, groupID)
if err != nil {
@@ -533,7 +533,7 @@ type ListPendingDuplicateGroupMembersRow struct {
// One page of proposals in one view (see CountPendingDuplicateGroupsInView),
// newest first, flattened to one row per member so the handler folds them
// without a query per group. What each copy carries — likes and plays from
// every user — is here because it is what the operator weighs when deciding
// every user — is here because it is what an admin weighs when deciding
// which copy to keep.
func (q *Queries) ListPendingDuplicateGroupMembers(ctx context.Context, arg ListPendingDuplicateGroupMembersParams) ([]ListPendingDuplicateGroupMembersRow, error) {
rows, err := q.db.Query(ctx, listPendingDuplicateGroupMembers, arg.View, arg.PageOffset, arg.PageLimit)
+2 -2
View File
@@ -131,7 +131,7 @@ type GetSystemPickKindForTrackParams struct {
// Looks a track up in the user's CURRENT snapshot of the given system
// variant and returns its pick_kind. Used at play-ingestion time to
// freeze provenance onto the play_event — snapshots rebuild daily, so
// attribution can't be reconstructed at read time (#1249/#1270). No
// attribution can't be reconstructed at read time. No
// row = track not in today's snapshot (caller stores NULL); a row with
// NULL pick_kind = the variant doesn't stamp (yet). songs_like_artist
// is non-singleton (up to 3 mixes/user); a track in two of them takes
@@ -166,7 +166,7 @@ type InsertPlayEventParams struct {
// pick_kind is non-NULL only for system-playlist plays whose track was
// found (with a stamped kind) in the user's live snapshot for that
// variant at ingestion time (#1249, generalized in #1270).
// variant at ingestion time.
func (q *Queries) InsertPlayEvent(ctx context.Context, arg InsertPlayEventParams) (PlayEvent, error) {
row := q.db.QueryRow(ctx, insertPlayEvent,
arg.UserID,
+3 -3
View File
@@ -81,7 +81,7 @@ SELECT t.id, t.file_path
LEFT JOIN track_fingerprints f ON f.track_id = t.id
WHERE t.missing_since IS NULL
-- A row taken at another length is as stale as one from an older method:
-- chromaprints at two lengths cannot be compared (#3913).
-- chromaprints at two lengths cannot be compared.
AND (f.track_id IS NULL
OR f.fingerprint_version < $1
OR f.chromaprint_length_sec <> $2)
@@ -102,7 +102,7 @@ type ListTracksNeedingFingerprintRow struct {
FilePath string
}
// The backfill's work queue (#3908): tracks with no fingerprint, or one derived
// The backfill's work queue: tracks with no fingerprint, or one derived
// by an older method. Keyset-paged on id so a pass visits each track at most
// once. That cursor is load-bearing: an inconclusive attempt writes no row, so
// without it a file that keeps timing out would be listed again straight away
@@ -157,7 +157,7 @@ type UpsertTrackFingerprintParams struct {
}
// Written whenever a track's fingerprint is derived: by the scan when a file is
// new or its bytes changed, and by the backfill (#3908) for rows derived by an
// new or its bytes changed, and by the backfill for rows derived by an
// older method. Replaces the row wholesale — a fingerprint of the old bytes has
// no standing once the file has changed.
func (q *Queries) UpsertTrackFingerprint(ctx context.Context, arg UpsertTrackFingerprintParams) error {
+9 -11
View File
@@ -20,10 +20,9 @@ UPDATE play_sessions
)
`
// #565: play_sessions.ended_at was added but never populated by any
// writer. Close sessions whose last_event_at is older than 6h —
// treating that as "user moved on" the same way audio_service does
// after grace periods. Sessions with NO events (track_count = 0)
// play_sessions.ended_at has no other writer. Close sessions whose
// last_event_at is older than 6h — treating that as "user moved on" the
// same way audio_service does after grace periods. Sessions with NO events (track_count = 0)
// older than 1h are also closed (stale handshakes from clients that
// never recorded a play). ended_at is set to last_event_at so the
// session's duration reads naturally.
@@ -46,12 +45,11 @@ UPDATE play_events
AND started_at < now() - INTERVAL '24 hours'
`
// Background garbage-collector / lifecycle queries. All five address
// drift findings from the 2026-06-02 audit (Scribe parent #552):
// #565 #566 #567 #574 #575. Sweeper runs on a long tick (default 1h)
// Background garbage-collector / lifecycle queries: rows nothing else closes
// or removes. Sweeper runs on a long tick (default 1h)
// so per-query cost is amortised; each is idempotent (re-running on
// already-closed/-deleted rows is a no-op).
// #566: play_events rows opened more than 24h ago that never got a
// Play_events rows opened more than 24h ago that never got a
// play_ended. Client crashed mid-track, network dropped, etc. We
// synthesize ended_at = started_at + duration_played_ms when present,
// otherwise leave duration_played_ms null and stamp ended_at = now()
@@ -72,7 +70,7 @@ DELETE FROM password_resets
OR (used_at IS NULL AND expires_at < now() - INTERVAL '1 hour')
`
// #575: password_resets accumulates expired + used rows forever. The
// Password_resets accumulates expired + used rows forever. The
// validation path already rejects them; this just keeps the table
// from growing unbounded. Used rows are kept for 7 days for audit;
// unused expired rows go immediately.
@@ -106,7 +104,7 @@ DELETE FROM scrobble_queue
AND enqueued_at < now() - INTERVAL '14 days'
`
// #567: scrobble_queue rows that have been in status='failed' for
// Scrobble_queue rows that have been in status='failed' for
// more than 14 days. The worker stops retrying after maxAttempts;
// failed rows accumulate forever otherwise. CASCADE from play_events
// already drops the row when the underlying event is deleted, so this
@@ -127,7 +125,7 @@ UPDATE system_playlist_runs
AND last_run_at < now() - INTERVAL '10 minutes'
`
// #574: system_playlist_runs.in_flight = true can wedge on a
// System_playlist_runs.in_flight = true can wedge on a
// goroutine panic between SET in_flight=true and SET in_flight=false.
// The duplicate-prevention check refuses to start a fresh regen while
// in_flight, so a stuck row blocks all future regens for that user.
+1 -1
View File
@@ -45,7 +45,7 @@ type ListUserHistoryRow struct {
ArtistName string
}
// M7 #365: track-level listening history. Returns one row per
// Track-level listening history. Returns one row per
// play_events entry, newest first, joined with tracks/albums/artists
// so the SPA can render a TrackRef without follow-up fetches. Filters
// out skipped events and tracks the user has quarantined (per-user
+5 -5
View File
@@ -297,7 +297,7 @@ type ListGrabsRow struct {
// The Wanted view's Activity tab: downloads waiting on a person first, then
// the rest still running, then the ended ones newest first. Each carries
// what is wrong with it now, if anything (#5523).
// what is wrong with it now, if anything.
func (q *Queries) ListGrabs(ctx context.Context, arg ListGrabsParams) ([]ListGrabsRow, error) {
rows, err := q.db.Query(ctx, listGrabs, arg.Skip, arg.MaxRows)
if err != nil {
@@ -366,7 +366,7 @@ type ListImportedGrabsHoldingRow struct {
// The downloads Minstrel imported into the folder holding path: the releases a
// file there came from, to block when the files proved not to be the album
// (#6169). A file imported before Minstrel downloaded anything has none.
// . A file imported before Minstrel downloaded anything has none.
func (q *Queries) ListImportedGrabsHolding(ctx context.Context, path string) ([]ListImportedGrabsHoldingRow, error) {
rows, err := q.db.Query(ctx, listImportedGrabsHolding, path)
if err != nil {
@@ -441,7 +441,7 @@ type ListLiveGrabsRow struct {
WantAlbumID pgtype.UUID
}
// Import with verification (M502 #5522).
// Import with verification.
// Every download still running or waiting on its import, oldest first.
func (q *Queries) ListLiveGrabs(ctx context.Context) ([]ListLiveGrabsRow, error) {
rows, err := q.db.Query(ctx, listLiveGrabs)
@@ -574,7 +574,7 @@ type ListUpgradeTracksRow struct {
SourceVerdict *string
}
// The tracks an upgrade may replace (#5524): the present tracks of the album
// The tracks an upgrade may replace: the present tracks of the album
// the want holds.
func (q *Queries) ListUpgradeTracks(ctx context.Context, albumID pgtype.UUID) ([]ListUpgradeTracksRow, error) {
rows, err := q.db.Query(ctx, listUpgradeTracks, albumID)
@@ -694,7 +694,7 @@ UPDATE grabs
import_forced = false,
imported_at = CASE WHEN $1::text = 'imported' THEN now() ELSE imported_at END,
-- The files were copied, so an imported download goes on sharing
-- until the lifecycle removes it (#5523).
-- until the lifecycle removes it.
seeding = $1::text = 'imported',
imported_files = $4,
destination = $5,
+4 -5
View File
@@ -116,11 +116,10 @@ type InsertLibraryChangesParams struct {
Op string
}
// Batch form, for a mutation that touches many rows at once (#2704: the scan's
// reconcile pass can mark up to a quarter of a library missing in one go).
// Every caller before this one changed a single entity, so per-row inserts
// were the right shape; a loop here would be thousands of round-trips inside
// a scan that is already the slow path.
// Batch form, for a mutation that touches many rows at once (the scan's
// reconcile pass can mark up to a quarter of a library missing in one go). A
// loop of single inserts would be thousands of round-trips inside a scan that
// is already the slow path.
func (q *Queries) InsertLibraryChanges(ctx context.Context, arg InsertLibraryChangesParams) error {
_, err := q.db.Exec(ctx, insertLibraryChanges, arg.EntityType, arg.EntityIds, arg.Op)
return err
+1 -1
View File
@@ -101,7 +101,7 @@ type RerootTrackPathsParams struct {
OldRoot string
}
// A library folder that moved (#6129): every path under old_root is rewritten
// A library folder that moved: every path under old_root is rewritten
// to the same place under new_root, so the tracks keep their ids and with them
// their plays, likes and playlists. updated_at is left alone on purpose: the
// scan compares it with each file's mtime, and the files have not changed.
+2 -2
View File
@@ -22,7 +22,7 @@ type CountGoneGrabsParams struct {
}
// How many of a release's grabs ended gone since a time: a release that keeps
// leaving its client is held back rather than taken on every pass (#6176).
// leaving its client is held back rather than taken on every pass.
func (q *Queries) CountGoneGrabs(ctx context.Context, arg CountGoneGrabsParams) (int64, error) {
row := q.db.QueryRow(ctx, countGoneGrabs, arg.InfoHash, arg.Since)
var count int64
@@ -289,7 +289,7 @@ type RaiseInterventionParams struct {
Detail string
}
// The download lifecycle (M502 #5523): the intervention ledger, giving a
// The download lifecycle: the intervention ledger, giving a
// download up, and seeding after import.
// A condition seen, or seen again: a second pass lands on the open row, so
// a download stuck for a week is one row that says how long. The name only
+1 -1
View File
@@ -93,7 +93,7 @@ type LikeTrackParams struct {
TrackID pgtype.UUID
}
// A like is on the song (M498 #5438): every copy of it sharing the track's
// A like is on the song: every copy of it sharing the track's
// song_key is liked. Returns the tracks newly liked, for the sync log; empty
// when the song was already liked.
func (q *Queries) LikeTrack(ctx context.Context, arg LikeTrackParams) ([]pgtype.UUID, error) {
+3 -3
View File
@@ -164,7 +164,7 @@ type GetReplayGainByTrackIDsRow struct {
}
// Track and album loudness for a set of tracks, for every surface that hands
// gains to a client (#4997). A measurement from an older analysis version is
// gains to a client. A measurement from an older analysis version is
// still delivered: it is a better gain than none until the backfill redoes it.
func (q *Queries) GetReplayGainByTrackIDs(ctx context.Context, ids []pgtype.UUID) ([]GetReplayGainByTrackIDsRow, error) {
rows, err := q.db.Query(ctx, getReplayGainByTrackIDs, ids)
@@ -280,7 +280,7 @@ type ListAlbumsNeedingLoudnessRow struct {
Digest string
}
// The album pass's work queue (#4996): albums whose present tracks or their
// The album pass's work queue: albums whose present tracks or their
// measurements have changed since album loudness was last computed, or that
// never had it. The digest is over every present track's id and the
// measurement it holds at the current version ('-' for none), so a track
@@ -484,7 +484,7 @@ type UpsertTrackLoudnessParams struct {
AnalysisVersion int16
}
// Written when the backfill measures a track (#4995). Replaces the row
// Written when the backfill measures a track. Replaces the row
// wholesale: a measurement of the old bytes has no standing once the file has
// changed.
func (q *Queries) UpsertTrackLoudness(ctx context.Context, arg UpsertTrackLoudnessParams) error {
+1 -1
View File
@@ -69,7 +69,7 @@ type LockDuplicateGroupForMergeRow struct {
Status string
}
// Duplicate merge (Scribe #3911). Every statement here runs inside the one
// Duplicate merge. Every statement here runs inside the one
// transaction library.MergeDuplicateGroup opens, after the removed copy's file
// is already gone. The loser's own track row is deleted last with DeleteTrack;
// what these do is move everything it carries onto the survivor first, so that
+8 -8
View File
@@ -63,27 +63,27 @@ type ListMissingTrackPairsRow struct {
PresentCandidates int32
}
// Missing-pair pass (M485). A track marked missing whose replacement is already
// Missing-pair pass. A track marked missing whose replacement is already
// on disk under another row — most often a quality upgrade, mp3 → flac at a new
// path — is folded into that replacement, so its history moves across and
// re-acquisition stops chasing music the library already has.
//
// Move adoption (#2528) cannot catch these: it links a new file to a missing row
// Move adoption cannot catch these: it links a new file to a missing row
// at the moment the file is first inserted, and the replacement arrives as a
// re-encode with no recording MBID, so it has nothing to match on. AcoustID may
// give it an MBID later; by then both rows exist and only a fold can join them.
// Every candidate (missing, present) pair, with how many candidates each side
// has. Two rules, measured on the operator's library on 2026-10-07 (#5274):
// has. Two rules:
//
// mbid the same recording MBID, within the album group (the album row, or
// albums sharing a release group). 142 of 359 pairs.
// title the same album row and the same title, ignoring case. 213 more. The
// albums sharing a release group).
// title the same album row and the same title, ignoring case. The
// replacements are often not the original file — another edition,
// re-encoded, untagged — so the metadata is what is left to go on.
//
// Deliberately NOT gated on duration or track position. On the 142 pairs known
// to be one recording, 18% differed by over 2s (old mp3 durations are poor
// estimates), and the poorly tagged set is exactly where numbering is broken.
// Deliberately NOT gated on duration or track position. Pairs known to be one
// recording often differ by over 2s (old mp3 durations are poor estimates),
// and the poorly tagged set is exactly where numbering is broken.
//
// A pair whose MBIDs are both set and differ is not a title match: the tags say
// they are different recordings. The caller folds a pair only when each side has
+7 -7
View File
@@ -54,7 +54,7 @@ type InsertNotificationParams struct {
EmailWanted bool
}
// M489 notifications inbox (#726). Rows are written only through
// Notifications inbox. Rows are written only through
// internal/notifications.Notifier, which decides recipients and honours each
// recipient's inbox preference before it reaches these.
// email_wanted is the recipient's email channel for this kind as of now. A
@@ -122,7 +122,7 @@ type ListEmailPendingNotificationsRow struct {
ReadAsOf pgtype.Timestamptz
}
// Email digest (#5346) ------------------------------------------------------
// Email digest ------------------------------------------------------
// Every unread, un-emailed row of a user who has an address, oldest first.
// Read rows are never selected: the user has seen them, so they are not news.
// read_as_of is the database's clock at the read, handed back to
@@ -348,7 +348,7 @@ type MarkAllNotificationsReadParams struct {
// all read" queued offline and replayed later must not mark notices that
// arrived in between, which the user never saw. A coalesced row that grew
// since then is marked read with it: it arrived before they asked, and its
// growth is a quiet update to a notice they had seen (M542).
// growth is a quiet update to a notice they had seen.
func (q *Queries) MarkAllNotificationsRead(ctx context.Context, arg MarkAllNotificationsReadParams) (int64, error) {
result, err := q.db.Exec(ctx, markAllNotificationsRead, arg.UserID, arg.UpTo)
if err != nil {
@@ -484,10 +484,10 @@ type UpsertCoalescedNotificationParams struct {
// ten. Every coalesced kind's event is "N more happened", never a restated
// total, so the row always says what is new since it was last read.
//
// created_at and emailed_at are left alone (M542): an update changes what the
// notice says, not when it arrived. Moving created_at made the phone announce
// it again and clearing emailed_at sent it again, so a notice the hourly
// duplicate pass kept growing alerted every hour.
// created_at and emailed_at are left alone: an update changes what the
// notice says, not when it arrived. Moving created_at would make the phone
// announce it again and clearing emailed_at would send it again, so a notice
// that keeps growing would alert on every update.
func (q *Queries) UpsertCoalescedNotification(ctx context.Context, arg UpsertCoalescedNotificationParams) (pgtype.UUID, error) {
row := q.db.QueryRow(ctx, upsertCoalescedNotification,
arg.UserID,
+3 -3
View File
@@ -38,7 +38,7 @@ type AppendPlaylistTrackParams struct {
// Inserts at the next available position. Snapshot fields are copied
// from the tracks/albums/artists join at insert time. tracks.duration_ms
// is converted to seconds for the snapshot. pick_kind is NULL for manual
// playlists; the For You builder stamps 'taste'/'fresh' (#1249).
// playlists; the For You builder stamps 'taste'/'fresh'.
func (q *Queries) AppendPlaylistTrack(ctx context.Context, arg AppendPlaylistTrackParams) (PlaylistTrack, error) {
row := q.db.QueryRow(ctx, appendPlaylistTrack, arg.PlaylistID, arg.PickKind, arg.TrackID)
var i PlaylistTrack
@@ -182,7 +182,7 @@ SELECT id, user_id, name, description, is_public, cover_path, track_count, durat
`
// Batched lookup used by /api/library/sync to hydrate upsert payloads
// (#357). Mirror of GetArtistsByIDs.
// . Mirror of GetArtistsByIDs.
func (q *Queries) GetPlaylistsByIDs(ctx context.Context, dollar_1 []pgtype.UUID) ([]Playlist, error) {
rows, err := q.db.Query(ctx, getPlaylistsByIDs, dollar_1)
if err != nil {
@@ -295,7 +295,7 @@ type ListPlaylistTracksRow struct {
// (track was removed from the library). The denormalized snapshot fields
// on playlist_tracks remain authoritative for title/artist/album text.
//
// Deliberately NOT filtered on missing_since (#2527), unlike every browse /
// Deliberately NOT filtered on missing_since, unlike every browse /
// discover / mix query. A playlist entry is something the user put here on
// purpose, so a missing file stays in the list and renders as a dead row
// rather than silently vanishing; missing_since rides along so the service
+8 -8
View File
@@ -35,9 +35,9 @@ const getReacquisitionSettings = `-- name: GetReacquisitionSettings :one
SELECT id, enabled, grace_hours, max_per_pass FROM reacquisition_settings WHERE id = true
`
// Re-acquisition of missing files (milestone #290, reworked for M502 #5520).
// Re-acquisition of missing files.
// The unit is the album: an album whose files went missing becomes a want for
// its release group, and the search schedule (#5521) looks for it.
// its release group, and the search schedule looks for it.
func (q *Queries) GetReacquisitionSettings(ctx context.Context) (ReacquisitionSetting, error) {
row := q.db.QueryRow(ctx, getReacquisitionSettings)
var i ReacquisitionSetting
@@ -140,17 +140,17 @@ type ListAlbumsDueReacquisitionRow struct {
//
// - it still has at least one track whose file has been missing longer than
// the grace window. Measured on missing_since, which reconcile never
// re-stamps (#2523), so it is a genuine "gone since" clock;
// re-stamps, so it is a genuine "gone since" clock;
// - MusicBrainz can name it: the artist has an MBID, and the album a
// release MBID or a release group. The release MBID is only ever used to
// find the group, and 238 albums matched to a group carried no release
// id, so their losses were never wanted back (#6167). Albums failing this
// are counted separately (CountAlbumsMissingWithoutMbid);
// - it is on the wanted list (#5567): an album taken off the list, or
// find the group, and an album matched to a group may carry no release
// id. Albums failing this are counted separately
// (CountAlbumsMissingWithoutMbid);
// - it is on the wanted list: an album taken off the list, or
// dropped into the library by hand, is not fetched back;
// - no want already covers it: none open, and none held since its files
// went missing. A want held after the loss means the library has a full
// copy despite the missing rows (#5245), so asking again would loop.
// copy despite the missing rows, so asking again would loop.
func (q *Queries) ListAlbumsDueReacquisition(ctx context.Context, arg ListAlbumsDueReacquisitionParams) ([]ListAlbumsDueReacquisitionRow, error) {
rows, err := q.db.Query(ctx, listAlbumsDueReacquisition, arg.GraceHours, arg.PageLimit)
if err != nil {
+42 -49
View File
@@ -19,7 +19,7 @@ ORDER BY started_at DESC
LIMIT 1
`
// The device_class of the user's most recent play (#1551), used as the
// The device_class of the user's most recent play, used as the
// "current device" for radio context conditioning. NULL when the latest play
// predates device capture or came from a client that didn't send one.
func (q *Queries) GetLatestPlayDeviceClassForUser(ctx context.Context, userID pgtype.UUID) (*string, error) {
@@ -87,10 +87,10 @@ type ListArtistContextPlayCountsForUserRow struct {
}
// Per-artist completed-play counts split by whether each play falls in the
// CURRENT context cell, in the user's local timezone (#1531). The cell is
// daypart × weekday-type, optionally narrowed by device class (#1551): when
// $2 (the current device) is ”, the device dimension is ignored (identical to
// the time-only #1531 behaviour, used by the daily mixes which have no device);
// CURRENT context cell, in the user's local timezone. The cell is
// daypart × weekday-type, optionally narrowed by device class: when
// $2 (the current device) is ”, the device dimension is ignored (time only,
// for the daily mixes, which have no device);
// when $2 is set (radio), a play only counts in the cell if its device_class
// matches. Feeds the context-affinity scoring term. Skips excluded; a 365-day
// window bounds cost. Daypart buckets: night [22,5) morning [5,12)
@@ -154,7 +154,7 @@ type ListLastPlayedArtistsForUserRow struct {
LastPlayedAt pgtype.Timestamptz
}
// M6a: artists ranked by max(play_events.started_at) for the user, with
// Artists ranked by max(play_events.started_at) for the user, with
// a derived cover_album_id via a representative-album lateral join (most
// recent album that has cover_art_path set). album_count joined for the
// ArtistRef wire shape.
@@ -216,7 +216,7 @@ JOIN tracks t ON t.id = p.track_id
JOIN albums ON albums.id = t.album_id
JOIN artists ON artists.id = t.artist_id
WHERE t.artist_id = $1
AND t.missing_since IS NULL -- #2523: never offer a file that is gone
AND t.missing_since IS NULL -- never offer a file that is gone
AND NOT EXISTS (
SELECT 1 FROM quarantine q
WHERE q.user_id = $2 AND q.track_id = t.id
@@ -303,7 +303,7 @@ FROM plays p
JOIN tracks t ON t.id = p.track_id
JOIN albums ON albums.id = t.album_id
JOIN artists ON artists.id = t.artist_id
WHERE t.missing_since IS NULL -- #2523: never offer a file that is gone
WHERE t.missing_since IS NULL -- never offer a file that is gone
AND NOT EXISTS (
SELECT 1 FROM quarantine q
WHERE q.user_id = $1 AND q.track_id = t.id
@@ -323,7 +323,7 @@ type ListMostPlayedTracksForUserRow struct {
ArtistName string
}
// M6a: top-N tracks by completed-play count for the user. was_skipped
// Top-N tracks by completed-play count for the user. was_skipped
// excludes skips so a user spamming next doesn't fabricate a top track.
// Quarantined tracks (per-user soft-hide from M5b) are filtered out.
//
@@ -723,7 +723,7 @@ LEFT JOIN LATERAL (
WHERE user_id = $1 AND track_id = t.id
) pe ON true
WHERE t.id <> $2
AND t.missing_since IS NULL -- #2523: never offer a file that is gone
AND t.missing_since IS NULL -- never offer a file that is gone
AND NOT EXISTS (
SELECT 1 FROM play_events
WHERE user_id = $1 AND track_id = t.id
@@ -843,11 +843,10 @@ lb_similar AS (
LIMIT $5
),
similar_artists AS (
-- Round-robin across the similar artists (#5297): each artist's first
-- Round-robin across the similar artists: each artist's first
-- track, best-scoring artist first, then each one's second, and so on.
-- Ordering by artist score alone let the closest similar artist's
-- catalogue fill the whole LIMIT; on the operator's library this arm held
-- exactly one artist for all 17 seeds measured (#3879).
-- Ordering by artist score alone would let the closest similar artist's
-- catalogue fill the whole LIMIT.
SELECT track_id, sim_score
FROM (
SELECT t.id AS track_id, asim.score * 0.5 AS sim_score, asim.score AS artist_score,
@@ -873,11 +872,10 @@ tag_overlap AS (
AND t.id <> $2
GROUP BY t.id
HAVING count(DISTINCT trim(g_split.g)) > 0
-- md5 breaks the ties (#3880). A seed with one tag gives every track of
-- that genre the same score, 7,804 tracks on the operator's library, and
-- with no tie-break the LIMIT took whichever rows Postgres reached first:
-- the same slice for every seed of the genre, and not one the order seed
-- controls.
-- md5 breaks the ties. A seed with one tag gives every track of that
-- genre the same score, and with no tie-break the LIMIT would take
-- whichever rows Postgres reached first: the same slice for every seed of
-- the genre, and not one the order seed controls.
ORDER BY sim_score DESC, md5(t.id::text || $12::text)
LIMIT $7
),
@@ -896,12 +894,10 @@ likes_overlap AS (
LIMIT $8
),
taste_overlap AS (
-- Round-robin across the taste artists (#3880), as similar_artists is
-- (#5297): each artist's first track, strongest artist first, then each
-- one's second. Ordered by weight then track id, the strongest artist's
-- catalogue filled the whole arm with the same lowest-id tracks every
-- time; on the operator's library that was 20 tracks of one artist of
-- 174, whose catalogue is 197 tracks.
-- Round-robin across the taste artists, as similar_artists is: each
-- artist's first track, strongest artist first, then each one's second.
-- Ordered by weight then track id, the strongest artist's catalogue would
-- fill the whole arm with the same lowest-id tracks every time.
SELECT track_id, sim_score
FROM (
SELECT t.id AS track_id, 0.0::float8 AS sim_score, tpa.weight,
@@ -918,7 +914,7 @@ taste_overlap AS (
LIMIT $10
),
coplay_artists AS (
-- Household co-play (#1533): tracks by artists co-played across the
-- Household co-play: tracks by artists co-played across the
-- instance with the seed's artist (source='user_cooccurrence', built by
-- the coplay worker). Mirrors similar_artists but from local co-occurrence
-- instead of ListenBrainz; empty on single-user servers. Same 0.5 damp as
@@ -972,7 +968,7 @@ FROM (
UNION ALL SELECT track_id, sim_score FROM coplay_artists
UNION ALL SELECT track_id, sim_score FROM random_fill
) u
JOIN tracks t ON t.id = u.track_id AND t.missing_since IS NULL -- #2523: never offer a file that is gone
JOIN tracks t ON t.id = u.track_id AND t.missing_since IS NULL -- never offer a file that is gone
JOIN albums al ON al.id = t.album_id
LEFT JOIN general_likes l ON l.user_id = $1 AND l.track_id = t.id
LEFT JOIN LATERAL (
@@ -1014,26 +1010,23 @@ type LoadRadioCandidatesV2Row struct {
SimilarityScore interface{}
}
// M4c: similarity-driven candidate pool. 6-way UNION:
// Similarity-driven candidate pool. 6-way UNION:
//
// $1 user_id, $2 seed_track_id, $3 recently_played_hours,
// $4 exclude (uuid[]), $5 lb_similar K, $6 similar_artists K,
// $7 tag_overlap K, $8 likes_overlap K, $9 random_fill K,
// $10 taste_overlap K (#796 phase 2b — tracks by the user's top
// $10 taste_overlap K (tracks by the user's top
// positively-weighted taste-profile artists, so taste-relevant tracks
// enter the pool even when the similarity/random arms miss them; scored
// in Go via TasteMatch, so sim_score here is 0 pool-inclusion),
// $11 coplay_artists K (#1533 — tracks by artists co-played across the
// $11 coplay_artists K (tracks by artists co-played across the
// instance with the seed's artist; source='user_cooccurrence'),
// $12 order_seed (text) — see below.
//
// $12 REPLACES `ORDER BY random()` IN FOUR ARMS (#3889). Those arms returned
// a stable set only while their LIMIT exceeded the rows eligible for them: at
// that point they returned all of them and the order stopped mattering,
// because the caller sorts by track id before scoring. Below that threshold
// they returned a random SUBSET, and two builds on the same day drew
// different ones — so "daily determinism" held by accident, and only for
// libraries smaller than the limits.
// $12 orders four arms by md5(id || seed), not random(). An arm whose LIMIT is
// below the rows eligible for it returns a SUBSET, and with random() two
// builds on the same day would draw different ones; the caller sorts by track
// id before scoring, so only the subset matters.
//
// md5(id || seed) keeps the intent — an arbitrary spread that changes when
// the seed does — while making it reproducible for a given seed. The CALLER
@@ -1042,7 +1035,7 @@ type LoadRadioCandidatesV2Row struct {
// keeps varying, which is what a radio should do.
// Returns same shape as LoadRadioCandidates plus similarity_score column.
//
// sim_score BANDS keep the tiers in order (rule 131, #6177). Similarity edges
// sim_score BANDS keep the eligibility tiers in order. Similarity edges
// are stored relative to the seed's best match, 0 to 1, so the arms are placed
// in bands rather than compared raw:
//
@@ -1052,9 +1045,9 @@ type LoadRadioCandidatesV2Row struct {
// likes_overlap 0.3, flat
// tier 3 taste_overlap, random_fill 0
//
// Without the bands, the seed's weaker LB edges fell below a shared genre tag
// and the flat likes score, and the one arm that measures the seed lost to
// the ones that guess.
// Without the bands, the seed's weaker LB edges would fall below a shared
// genre tag and the flat likes score, and the one arm that measures the seed
// would lose to the ones that guess.
func (q *Queries) LoadRadioCandidatesV2(ctx context.Context, arg LoadRadioCandidatesV2Params) ([]LoadRadioCandidatesV2Row, error) {
rows, err := q.db.Query(ctx, loadRadioCandidatesV2,
arg.UserID,
@@ -1122,9 +1115,9 @@ func (q *Queries) LoadRadioCandidatesV2(ctx context.Context, arg LoadRadioCandid
const suggestArtistsForUser = `-- name: SuggestArtistsForUser :many
WITH artist_plays AS (
-- Completed plays only. The previous seed query counted every play_event,
-- so skipping an artist repeatedly INCREASED its signal and pushed more of
-- its neighbours at the user (issue #2367 mechanism 3).
-- Completed plays only: counting every play_event would make skipping an
-- artist repeatedly INCREASE its signal and push more of its neighbours
-- at the user.
SELECT t.artist_id, count(*)::bigint AS play_count
FROM play_events pe
JOIN tracks t ON t.id = pe.track_id
@@ -1181,7 +1174,7 @@ contributions AS (
AND r.artist_mbid = u.candidate_mbid
AND r.status NOT IN ('rejected', 'failed')
)
-- Snoozed by this user and not yet expired (#2374). Time-boxed and
-- Snoozed by this user and not yet expired. Time-boxed and
-- per-user: the candidate returns on its own once snoozed_until
-- passes, and stays visible to everyone else meanwhile. Deliberately
-- filtered at the candidate stage, NOT folded into the score — a
@@ -1226,7 +1219,7 @@ type SuggestArtistsForUserRow struct {
// Per-user artist suggestions ranked by taste signal x similarity, projected
// through artist_similarity_unmatched (out-of-library candidates only).
//
// Seeds are TIERED (rule #131) so the surface never empties:
// Seeds are TIERED so the surface never empties:
//
// tier 1 - taste_profile_artists.weight: engagement-graded, time-decayed and
// SIGNED by internal/taste, so an artist the user has drifted away
@@ -1234,9 +1227,9 @@ type SuggestArtistsForUserRow struct {
// tier 2 - likes + completed plays, used ONLY when the profile has no rows
// (new account, or before the first daily recompute).
//
// The signal is log-damped: contribution is signal x similarity, and the old
// undamped sum let one heavily-played artist's neighbours take every slot --
// entrenching harder the MORE the user listened (issue #2367 mechanism 2).
// The signal is log-damped: contribution is signal x similarity, and an
// undamped sum would let one heavily-played artist's neighbours take every
// slot -- entrenching harder the MORE the user listened.
//
// Candidates already in the library, already requested and not terminal, or
// snoozed by this user, are excluded. $1=user_id, $2=half_life_days (tier 2
@@ -44,12 +44,12 @@ type RecommendationSourceMetricsForUserRow struct {
// $1 user_id, $2 window_days. plays/skips are counts; avg_completion is the
// mean completion ratio over the completion_n plays that recorded one.
// pick_kind splits For You plays into taste/fresh/unattributed (#1249);
// pick_kind splits For You plays into taste/fresh/unattributed;
// it is NULL for every other source, so those still group to one row.
//
// completion_sqsum carries the sum of SQUARED completion ratios so the Go
// handler can compute a variance — needed for the margin of error on a
// completion delta (#2495). It is the sum rather than `stddev_samp` on purpose:
// completion delta. It is the sum rather than `stddev_samp` on purpose:
// raw source rows get merged into surface families in Go, and sums of squares
// add across groups exactly, whereas standard deviations cannot be combined
// without them. Variance = (sqsum - sum²/n) / (n-1), with sum = avg × n.
@@ -112,17 +112,17 @@ type RecommendationWeeklyTrendsRow struct {
TasteHits int64
}
// Recommendation observability (#796 phase 4). Per-source play outcomes so the
// Recommendation observability. Per-source play outcomes so the
// operator can see whether each recommendation surface is landing and tune the
// taste weights. Source is stamped on play_events when a play is launched from
// a recommendation surface; NULL means the user picked the track manually —
// those rows are INCLUDED here as the baseline control group the surfaces are
// judged against (milestone #127: delta-vs-baseline is what makes the numbers
// actionable). Raw source strings are bucketed into stable surface families in
// the Go handler; completion_n is carried so family merges can weight
// judged against (delta-vs-baseline is what makes the numbers actionable).
// Raw source strings are bucketed into stable surface families in the Go
// handler; completion_n is carried so family merges can weight
// avg_completion correctly.
// Weekly per-source outcome series for the tuning lab's trend view
// (#1251). Aggregated across ALL users: the tuning knobs are global,
// . Aggregated across ALL users: the tuning knobs are global,
// so judging a knob turn needs global outcomes — rows carry rates
// only, no track or user identity. NULL-source (manual) rows are
// included as the baseline family.
+5 -5
View File
@@ -70,7 +70,7 @@ SELECT id, changed_at, scope, action, changes
LIMIT $1
`
// Newest first; consumed by the metrics trend view (#1251) to annotate
// Newest first; consumed by the metrics trend view to annotate
// knob turns on the timeline.
func (q *Queries) ListTuningAudit(ctx context.Context, limit int32) ([]RecommendationTuningAudit, error) {
rows, err := q.db.Query(ctx, listTuningAudit, limit)
@@ -279,8 +279,8 @@ type UpsertDiscoverTuningDefaultsParams struct {
SnoozeDays float64
}
// Boot reconcile for the Discover scope (#2377). Never overwrites
// operator-tuned values, same contract as the other two.
// Boot reconcile for the Discover scope. Never overwrites
// admin-tuned values, same contract as the other two.
func (q *Queries) UpsertDiscoverTuningDefaults(ctx context.Context, arg UpsertDiscoverTuningDefaultsParams) error {
_, err := q.db.Exec(ctx, upsertDiscoverTuningDefaults, arg.TagOverlapWeight, arg.SnoozeDays)
return err
@@ -341,10 +341,10 @@ type UpsertWeightProfileDefaultsParams struct {
ContextTimeWeight float64
}
// Recommendation tuning lab queries (#1250). Seeding happens via the
// Recommendation tuning lab queries. Seeding happens via the
// recsettings boot reconcile; shipped defaults live in Go only.
// Boot reconcile: insert the shipped defaults for a profile if the row
// doesn't exist yet. Never overwrites operator-tuned values.
// doesn't exist yet. Never overwrites admin-tuned values.
func (q *Queries) UpsertWeightProfileDefaults(ctx context.Context, arg UpsertWeightProfileDefaultsParams) error {
_, err := q.db.Exec(ctx, upsertWeightProfileDefaults,
arg.Profile,
+1 -1
View File
@@ -520,7 +520,7 @@ type RepointRequestsAlbumMbidParams struct {
OldMbid *string
}
// A want moved from a release id to its group (#5241) takes the requests
// A want moved from a release id to its group takes the requests
// that name it along, so the reconciler finds it.
func (q *Queries) RepointRequestsAlbumMbid(ctx context.Context, arg RepointRequestsAlbumMbidParams) error {
_, err := q.db.Exec(ctx, repointRequestsAlbumMbid, arg.NewMbid, arg.OldMbid)
+2 -2
View File
@@ -98,7 +98,7 @@ type InsertScanRunRow struct {
StartedAt pgtype.Timestamptz
}
// M7 #381: scan-run lifecycle queries.
// Scan-run lifecycle queries.
// Creates a new scan_runs row with started_at=now(). Stages are filled in
// as each completes via UpdateScanRunStage; finished_at is set by FinishScanRun.
func (q *Queries) InsertScanRun(ctx context.Context) (InsertScanRunRow, error) {
@@ -119,7 +119,7 @@ type UpdateScanRunArtistArtEnrichParams struct {
ArtistArtEnrich []byte
}
// M7 cover-sources: persists the artist-art enrich stage tally JSON.
// Persists the artist-art enrich stage tally JSON.
func (q *Queries) UpdateScanRunArtistArtEnrich(ctx context.Context, arg UpdateScanRunArtistArtEnrichParams) error {
_, err := q.db.Exec(ctx, updateScanRunArtistArtEnrich, arg.ID, arg.ArtistArtEnrich)
return err
+3 -3
View File
@@ -99,7 +99,7 @@ const getAcquisitionSettings = `-- name: GetAcquisitionSettings :one
SELECT id, auto_grab, search_interval_hours, allowed_qualities, last_pass_at, last_pass, updated_at, import_root, seed_ratio, seed_days, stall_hours, library_listing_started_at, library_listed_at, library_unlisted, upgrade_until FROM acquisition_settings WHERE id = true
`
// Searching for wants and grabbing releases (M502 #5521).
// Searching for wants and grabbing releases.
func (q *Queries) GetAcquisitionSettings(ctx context.Context) (AcquisitionSetting, error) {
row := q.db.QueryRow(ctx, getAcquisitionSettings)
var i AcquisitionSetting
@@ -385,7 +385,7 @@ SELECT info_hash, name, reason, detail, want_id, blocked_by, blocked_at, expires
`
// Every release set aside and still held back: a stalled one lifts by itself
// at expires_at (#5523).
// at expires_at.
func (q *Queries) ListReleaseBlocks(ctx context.Context) ([]ReleaseBlock, error) {
rows, err := q.db.Query(ctx, listReleaseBlocks)
if err != nil {
@@ -500,7 +500,7 @@ type ListWantsDueForSearchRow struct {
// Wants with no download running that were never searched or not since
// @hours ago: open wants first (never-searched, then requests, then missing
// files, then followed artists' releases), then held albums wanted for an
// upgrade (#5524), which are searched at most weekly.
// upgrade, which are searched at most weekly.
func (q *Queries) ListWantsDueForSearch(ctx context.Context, arg ListWantsDueForSearchParams) ([]ListWantsDueForSearchRow, error) {
rows, err := q.db.Query(ctx, listWantsDueForSearch, arg.Hours, arg.MaxRows)
if err != nil {
+2 -1
View File
@@ -57,7 +57,8 @@ type DeleteSessionForUserParams struct {
UserID pgtype.UUID
}
// Scoped by user_id, not just id (rule #47). Keyed on the id alone, any
// Scoped by user_id, not just id: household data is per-user. Keyed on the
// id alone, any
// household member could revoke another member's session by guessing a uuid.
// execrows lets the handler answer 404 rather than a false 204 when the row
// isn't theirs.
+5 -5
View File
@@ -134,8 +134,8 @@ type ListPlayedTracksNeedingSimilarityRow struct {
// ListenBrainz has never answered for, or not in 30 days. Never-fetched first,
// then the oldest answer. Freshness is read from track_similarity_fetches, not
// from the edges, so a seed whose answer matched nothing in the library still
// counts as fetched (#5296); reading the edges is what let 25 such seeds hold
// the head of the queue forever.
// counts as fetched; reading the edges would let such seeds hold the head of
// the queue forever.
func (q *Queries) ListPlayedTracksNeedingSimilarity(ctx context.Context, limit int32) ([]ListPlayedTracksNeedingSimilarityRow, error) {
rows, err := q.db.Query(ctx, listPlayedTracksNeedingSimilarity, limit)
if err != nil {
@@ -310,9 +310,9 @@ WHERE ts.source = 'listenbrainz'
//
// The score is RELATIVE: each edge's LB score over the seed's best score in its
// whole cached answer, so 1.0 is the seed's closest recording and the rest fall
// below it (#6177). LB's raw scores are counts (16 to 1445 on the operator's
// library) and reached the scorer, which reads similarity as 0 to 1, so one
// edge outweighed likes, skips and recency together. The cache keeps the raw
// below it. LB's raw scores are counts, into the thousands, and the scorer
// reads similarity as 0 to 1, so a raw edge would outweigh likes, skips and
// recency together. The cache keeps the raw
// answer; only the edge is scaled.
//
// Only edges of seeds the cache owns are removed, those with a fetch row.
+2 -2
View File
@@ -33,7 +33,7 @@ type LinkTracksAsSongRow struct {
Moved int64
}
// Song links (M498 #5438): copies of one song on different releases share a
// Song links: copies of one song on different releases share a
// song_key (migration 0076).
// Links the tracks into one song, joining any songs they already belong to.
// The song keeps the lowest key among them, so linking the same set again
@@ -57,7 +57,7 @@ type ListTrackSongKeysRow struct {
}
// What the mix writer needs to place a track: its song, and whether it is a
// video rip held back from the mixes (#5439).
// video rip held back from the mixes.
func (q *Queries) ListTrackSongKeys(ctx context.Context, ids []pgtype.UUID) ([]ListTrackSongKeysRow, error) {
rows, err := q.db.Query(ctx, listTrackSongKeys, ids)
if err != nil {
+1 -1
View File
@@ -85,7 +85,7 @@ type SnoozeSuggestionParams struct {
Column4 float64
}
// Time-boxed "not right now" on a Discover artist suggestion (#2374).
// Time-boxed "not right now" on a Discover artist suggestion.
//
// See 0049_suggestion_snoozes.up.sql for why this is a snooze and not a
// dismissal: it records no verdict on the music, expires on its own, and
+37 -40
View File
@@ -39,7 +39,7 @@ SELECT t.id, t.album_id, t.artist_id
JOIN affinity_artists aa ON aa.artist_id = t.artist_id
LEFT JOIN play_counts pc ON pc.track_id = t.id
LEFT JOIN skip_counts sc ON sc.track_id = t.id
WHERE t.missing_since IS NULL -- #2523: never offer a file that is gone
WHERE t.missing_since IS NULL -- never offer a file that is gone
AND COALESCE(pc.c, 0) <= 2
AND COALESCE(sc.c, 0) < 2
AND NOT EXISTS (
@@ -62,18 +62,18 @@ type ListDeepCutsTracksRow struct {
}
// Candidate queries for the discovery system-playlist mixes
// (#419-423). Each returns (id, album_id, artist_id) rows; the Go
// . Each returns (id, album_id, artist_id) rows; the Go
// producer caps + truncates and converts to rankedCandidate. Daily-
// deterministic md5(id||dateStr) ordering (where used) keeps a mix
// stable within a day while rotating across days; shuffle-on-play
// gives per-play variety on top.
// #419 Deep Cuts: low-play tracks (<=2 plays) from artists the user
// Deep Cuts: low-play tracks (<=2 plays) from artists the user
// has liked OR played heavily (>=5 non-skip plays across the artist).
// Tracks the user has skipped twice or more don't qualify (#1257):
// eligibility used to count only unskipped plays, so the most actively
// rejected tracks read as "barely heard" and kept being re-offered.
// Threshold 2 so a single accidental skip doesn't banish a track;
// passive-signal only (no dislike UI, rule #101).
// Tracks the user has skipped twice or more don't qualify: counting only
// unskipped plays would make the most actively rejected tracks read as
// "barely heard" and keep re-offering them. Threshold 2 so a single
// accidental skip doesn't banish a track; passive signal only (there is no
// dislike button).
// $1 user_id, $2 date string.
func (q *Queries) ListDeepCutsTracks(ctx context.Context, arg ListDeepCutsTracksParams) ([]ListDeepCutsTracksRow, error) {
rows, err := q.db.Query(ctx, listDeepCutsTracks, arg.UserID, arg.Column2)
@@ -125,7 +125,7 @@ SELECT t.id, t.album_id, t.artist_id, alt.tier::int AS tier
FROM tracks t
JOIN albums al ON al.id = t.album_id
JOIN albums_tiered alt ON alt.album_id = al.id
WHERE t.missing_since IS NULL -- #2523: never offer a file that is gone
WHERE t.missing_since IS NULL -- never offer a file that is gone
AND alt.tier IS NOT NULL
AND NOT EXISTS (SELECT 1 FROM attempted a WHERE a.track_id = t.id)
AND NOT EXISTS (
@@ -153,11 +153,10 @@ type ListFirstListensTracksRow struct {
Tier int32
}
// #423 First Listens: songs the user has never heard or even
// attempted. "Attempted" is track-level with a >=30s listen threshold
// (#1268, operator decision 2026-07-03) — the old version disqualified
// a whole album on ANY play_event, so a 2-second accidental brush
// banished it permanently.
// First Listens: songs the user has never heard or even
// attempted. "Attempted" is track-level with a >=30s listen threshold:
// disqualifying a whole album on ANY play_event would let a 2-second
// accidental brush banish it permanently.
//
// tier 1 the exact desire: albums with ZERO attempted tracks
// tier 2 step back: barely-attempted albums (<=25% of tracks
@@ -227,7 +226,7 @@ albums_tiered AS (
SELECT t.id, t.album_id, t.artist_id, alt.tier::int AS tier
FROM tracks t
JOIN albums_tiered alt ON alt.album_id = t.album_id
WHERE t.missing_since IS NULL -- #2523: never offer a file that is gone
WHERE t.missing_since IS NULL -- never offer a file that is gone
AND NOT EXISTS (
SELECT 1 FROM quarantine q
WHERE q.user_id = $1 AND q.track_id = t.id
@@ -244,14 +243,13 @@ type ListNewForYouTracksRow struct {
Tier int32
}
// #421 New for you, tiered per project rule #131 (#1267). The old
// single hard rule (added <30d AND direct affinity) had two failure
// modes with one root: no notion of consumption — the album you
// devoured in week one crowded the mix for three more weeks, and
// after a quiet month nothing qualified at all.
// New for you, tiered so the mix degrades rather than vanishes. A
// single hard rule (added <30d AND direct affinity) has no notion of
// consumption: the album you devoured in week one would crowd the mix
// for three more weeks, and after a quiet month nothing would qualify.
//
// "Consumed" = any track attempted for >=30s (the First Listens
// threshold, #1268): once you've meaningfully engaged, the album is
// threshold): once you've meaningfully engaged, the album is
// no longer news. Applies to every tier — played albums leave the
// mix the next build.
//
@@ -306,7 +304,7 @@ WITH windowed AS (
SELECT t.id, t.album_id, t.artist_id
FROM tracks t
JOIN windowed w ON w.track_id = t.id
WHERE t.missing_since IS NULL -- #2523: never offer a file that is gone
WHERE t.missing_since IS NULL -- never offer a file that is gone
AND NOT EXISTS (
SELECT 1 FROM quarantine q
WHERE q.user_id = $1 AND q.track_id = t.id
@@ -326,18 +324,18 @@ type ListOnThisDayTracksRow struct {
ArtistID pgtype.UUID
}
// #422 On This Day: tracks the user played around this calendar date
// On This Day: tracks the user played around this calendar date
// (±10 day-of-year) in the past, excluding the very recent (>30 days
// ago) so it's nostalgic, not just "last week". Weighted by how much
// they were played in those windows. Floor relaxed from 60→30 days
// and window ±7→±10 so it surfaces on a months-old library instead
// of needing a full year of history; still skips cleanly (no rows →
// no playlist) when there's no qualifying history yet.
// Day-of-year distance is circular (#1256): plain ABS made Dec 28 vs
// Jan 3 read as 359 days apart, silently gutting the window for ~3
// weeks around every New Year — precisely when holiday nostalgia is
// the point. LEAST(d, 365-d) wraps the boundary; leap-year drift of
// ±1 is absorbed by the ±10 window. The build date ($2, already here
// they were played in those windows. The 30-day floor and ±10 window
// let it surface on a months-old library rather than needing a full
// year of history; it still skips cleanly (no rows → no playlist)
// when there's no qualifying history yet.
// Day-of-year distance is circular: plain ABS would read Dec 28 vs
// Jan 3 as 359 days apart, gutting the window for ~3 weeks around
// every New Year — precisely when holiday nostalgia is the point.
// LEAST(d, 365-d) wraps the boundary; leap-year drift of ±1 is absorbed
// by the ±10 window. The build date ($2, already here
// for the md5 rotation) anchors "today" instead of now() so the
// window is testable and consistent with the mix's daily determinism.
// $1 user_id, $2 date string.
@@ -371,18 +369,18 @@ WITH stats AS (
SELECT t.id, t.album_id, t.artist_id
FROM tracks t
JOIN stats s ON s.track_id = t.id
WHERE t.missing_since IS NULL -- #2523: never offer a file that is gone
WHERE t.missing_since IS NULL -- never offer a file that is gone
AND s.c >= 3
AND s.last_at <= now() - interval '30 days'
AND NOT EXISTS (
SELECT 1 FROM quarantine q
WHERE q.user_id = $1 AND q.track_id = t.id
)
-- Declined-resurfacing cooldown (#1258): a skip on a
-- Declined-resurfacing cooldown: a skip on a
-- rediscover-sourced play is the user explicitly saying "I've moved
-- on" to the exact invitation this mix extends — such tracks sit
-- out ~90 days instead of re-qualifying the next day. Passive
-- signal only (rule #101).
-- signal only.
AND NOT EXISTS (
SELECT 1 FROM play_events rp
WHERE rp.user_id = $1
@@ -403,11 +401,10 @@ type ListRediscoverTracksRow struct {
ArtistID pgtype.UUID
}
// #420 Rediscover: tracks the user played a lot but has drifted away
// from. One blended pool (issue #1246: the old two-tier UNION was
// all-or-nothing — a single ">=6 months cold" row suppressed the whole
// ">=30 days" tier, which is how a one-song playlist shipped; the 6mo
// tier was also a strict subset of the 30d tier). Eligibility is >=3
// Rediscover: tracks the user played a lot but has drifted away
// from. One blended pool, not a two-tier UNION: the ">=6 months cold" tier is
// a strict subset of the ">=30 days" one, and a UNION that let one row of it
// suppress the wider tier would ship a one-song playlist. Eligibility is >=3
// non-skip plays and >=30 days cold; the bar sits at 3 rather than 5
// so a weeks-old library still fields a pool — on young histories the
// >=5-play tracks are precisely the ones still in rotation. Ordering
@@ -34,7 +34,7 @@ type AppendRotationPlayedParams struct {
TrackID pgtype.UUID
}
// Rotation state for system-playlist sample-history dedup (#415).
// Rotation state for system-playlist sample-history dedup.
// One row per (user, playlist_kind). played_track_ids accumulates
// tracks heard from that playlist in the current rotation; shuffle
// prefers ids NOT in this set, then resets when the snapshot is
+10 -10
View File
@@ -198,14 +198,14 @@ SELECT u.id FROM users u
)
`
// Track picks here join `tracks ... AND t.missing_since IS NULL` (#2523): a
// Track picks here join `tracks ... AND t.missing_since IS NULL`: a
// seed or For-You candidate has to be something that can actually play. Note
// this only affects newly GENERATED playlists — already-stored system
// playlists keep their rows until the next daily rebuild, which is why the
// shared ListPlaylistTracks read path is deliberately left unfiltered (it
// also serves user-curated playlists, where hiding a track the user added
// themselves would be wrong).
// M7 #352 slice 2: system-generated playlist queries.
// System-generated playlist queries.
// Active = had a play in the last 7 days. The cron iterates this list.
func (q *Queries) ListActiveUsersForSystemPlaylists(ctx context.Context) ([]pgtype.UUID, error) {
rows, err := q.db.Query(ctx, listActiveUsersForSystemPlaylists)
@@ -368,10 +368,10 @@ type PickSeedArtistsRow struct {
}
// Top-12 most-engaged distinct artist candidates, tiered so the
// "Songs like X" mixes never silently vanish (#1255): the old hard
// 7-day window emptied the seed pool after a quiet week, and the
// daily atomic-replace build then deleted every existing mix until
// the user played something again. Same fallback shape as
// "Songs like X" mixes never silently vanish: a hard 7-day window
// would empty the seed pool after a quiet week, and the daily
// atomic-replace build would then delete every existing mix until the
// user played something again. Same fallback shape as
// PickTopPlayedTracksForUser (For You's seeds):
//
// tier 0 engagement in the last 7 days
@@ -380,12 +380,12 @@ type PickSeedArtistsRow struct {
// tier 3 (only if 0-2 empty) liked artists with no play history
//
// All returned rows share one tier; produceSeedMixes maps it onto the
// rule-#131 pick-kind ladder and stamps the built tracks, so metrics
// tiered pick-kind ladder and stamps the built tracks, so metrics
// can compare mixes seeded from fresh vs stale engagement.
// Score = unskipped-play count + 5 if user has liked the artist. The
// Go-side picker (pickSeedArtistsForDay) shuffles the 12
// daily-deterministically and takes songsLikeSeedCount (6) so the mix
// set both rotates day-to-day and fills the dedicated Home row (#1491).
// set both rotates day-to-day and fills the dedicated Home row.
func (q *Queries) PickSeedArtists(ctx context.Context, userID pgtype.UUID) ([]PickSeedArtistsRow, error) {
rows, err := q.db.Query(ctx, pickSeedArtists, userID)
if err != nil {
@@ -452,7 +452,7 @@ SELECT COALESCE(
FROM tracks t
JOIN albums a ON a.id = t.album_id
WHERE t.artist_id = $2
AND t.missing_since IS NULL -- #2701: the play branch filters; this one must too
AND t.missing_since IS NULL -- the play branch filters; this one must too
ORDER BY a.release_date DESC NULLS LAST,
t.disc_number NULLS LAST,
t.track_number NULLS LAST,
@@ -530,7 +530,7 @@ SELECT id
// library with sparse history.
// A likes-only read still joins tracks: a like outlives its file, and a
// seed whose file is gone points For You at something the user can't hear
// (#2701). The other two tiers get the same filter from their play_events
// . The other two tiers get the same filter from their play_events
// join.
func (q *Queries) PickTopPlayedTracksForUser(ctx context.Context, userID pgtype.UUID) ([]pgtype.UUID, error) {
rows, err := q.db.Query(ctx, pickTopPlayedTracksForUser, userID)
+2 -2
View File
@@ -74,7 +74,7 @@ SELECT provider_id, enabled, api_key, display_order, created_at, updated_at
ORDER BY display_order, provider_id
`
// Tag-enrichment provider settings queries (milestone #160, #1490 Step 2).
// Tag-enrichment provider settings queries.
// The tags.SettingsService consumes these — parallel to the cover-art
// SettingsService (coverart_settings.sql). Keeping the two independent
// means a new tag source is added without touching the art settings.
@@ -150,7 +150,7 @@ type UpsertTagProviderSettingsParams struct {
// INSERT a default row for a newly-registered provider, or refresh an
// existing row's display_order on boot. Does NOT overwrite enabled /
// api_key on conflict — the operator's settings persist across restarts.
// api_key on conflict — an admin's settings persist across restarts.
func (q *Queries) UpsertTagProviderSettings(ctx context.Context, arg UpsertTagProviderSettingsParams) error {
_, err := q.db.Exec(ctx, upsertTagProviderSettings, arg.ProviderID, arg.Enabled, arg.DisplayOrder)
return err
+7 -7
View File
@@ -153,7 +153,7 @@ type ListLikedTrackTasteInputsForUserRow struct {
// (track_id, artist_id, genre, release_date) for each track the user has
// explicitly liked. Feeds the track-like bonus into the liked track's artist,
// tags, and era (#1530); track_id keys the enriched track_tags lookup (#1490).
// tags, and era; track_id keys the enriched track_tags lookup.
func (q *Queries) ListLikedTrackTasteInputsForUser(ctx context.Context, userID pgtype.UUID) ([]ListLikedTrackTasteInputsForUserRow, error) {
rows, err := q.db.Query(ctx, listLikedTrackTasteInputsForUser, userID)
if err != nil {
@@ -216,14 +216,14 @@ type ListPlayEngagementInputsForUserRow struct {
AgeDays float64
}
// Taste profile (#796 phase 1). The daily build computes signed artist/tag
// Taste profile. The daily build computes signed artist/tag
// weights in Go (graded engagement + decay + like bonus) and atomic-replaces
// them here. Read queries serve "top taste" lookups (used in phase 2).
// them here. Read queries serve the scorer's "top taste" lookups.
// One row per play in the decay-relevant window. completion is the play's
// completion ratio (precomputed column when present, else duration_played /
// track duration, clamped to [0,1]); age_days drives the time-decay. Genre
// is split into tags in Go; release_date derives the decade for the era
// facet (#1530). Quarantined tracks are excluded.
// facet. Quarantined tracks are excluded.
func (q *Queries) ListPlayEngagementInputsForUser(ctx context.Context, arg ListPlayEngagementInputsForUserParams) ([]ListPlayEngagementInputsForUserRow, error) {
rows, err := q.db.Query(ctx, listPlayEngagementInputsForUser, arg.UserID, arg.Column2)
if err != nil {
@@ -269,7 +269,7 @@ type ListTasteProfileArtistsForUserRow struct {
Weight float64
}
// Top-weighted taste artists (phase-2 consumption + tests).
// Top-weighted taste artists, for the scorer and tests.
func (q *Queries) ListTasteProfileArtistsForUser(ctx context.Context, arg ListTasteProfileArtistsForUserParams) ([]ListTasteProfileArtistsForUserRow, error) {
rows, err := q.db.Query(ctx, listTasteProfileArtistsForUser, arg.UserID, arg.Limit)
if err != nil {
@@ -308,7 +308,7 @@ type ListTasteProfileErasForUserRow struct {
Weight float64
}
// Top-weighted taste eras (#1530); consumed by the scorer's era term.
// Top-weighted taste eras; consumed by the scorer's era term.
func (q *Queries) ListTasteProfileErasForUser(ctx context.Context, arg ListTasteProfileErasForUserParams) ([]ListTasteProfileErasForUserRow, error) {
rows, err := q.db.Query(ctx, listTasteProfileErasForUser, arg.UserID, arg.Limit)
if err != nil {
@@ -347,7 +347,7 @@ type ListTasteProfileMoodsForUserRow struct {
Weight float64
}
// Top-weighted taste moods (#1534); consumed by the scorer's mood term.
// Top-weighted taste moods; consumed by the scorer's mood term.
func (q *Queries) ListTasteProfileMoodsForUser(ctx context.Context, arg ListTasteProfileMoodsForUserParams) ([]ListTasteProfileMoodsForUserRow, error) {
rows, err := q.db.Query(ctx, listTasteProfileMoodsForUser, arg.UserID, arg.Limit)
if err != nil {
+3 -3
View File
@@ -121,7 +121,7 @@ type ListTrackTagsForTracksRow struct {
Tag string
}
// Enriched tags for a set of candidate tracks (#1534), so the scorer can
// Enriched tags for a set of candidate tracks, so the scorer can
// derive each candidate's mood buckets at scoring time. One row per (track,
// tag); the caller filters to mood words via the internal/mood vocabulary.
func (q *Queries) ListTrackTagsForTracks(ctx context.Context, dollar_1 []pgtype.UUID) ([]ListTrackTagsForTracksRow, error) {
@@ -168,7 +168,7 @@ type ListTracksMissingTagsRow struct {
ArtistMbid *string
}
// Track-tag enrichment queries (milestone #160, #1490). The tag enricher
// Track-tag enrichment queries. The tag enricher
// drains ListTracksMissingTags, fetches from the provider chain, and
// writes the merged top-K via DeleteTrackTags + InsertTrackTag, then
// stamps SetTrackTagSource. Mirrors the coverart artist-enricher shape.
@@ -176,7 +176,7 @@ type ListTracksMissingTagsRow struct {
// or previously settled 'none' under an older provider version. Returns
// the fields the provider chain needs — recording MBID (nullable) for
// keyed lookups, title + artist name for name-based fallback, and the
// artist MBID (nullable) for MusicBrainz's artist-tag fallback (#1519).
// artist MBID (nullable) for MusicBrainz's artist-tag fallback.
// $1 = current tag_sources_version, $2 = limit.
func (q *Queries) ListTracksMissingTags(ctx context.Context, arg ListTracksMissingTagsParams) ([]ListTracksMissingTagsRow, error) {
rows, err := q.db.Query(ctx, listTracksMissingTags, arg.TagSourcesVersion, arg.Limit)
+28 -29
View File
@@ -62,10 +62,10 @@ UPDATE tracks
WHERE id = ANY($1::uuid[])
`
// Forgets the recording MBID of rows whose file was another song's (M498's
// wrong-slot removal). The MBID came from that file, so it names the song kept
// elsewhere on the album, and missing-pair folding would fold the emptied slot
// into it: twelve slots went that way on 2026-10-20 and were never wanted back.
// Forgets the recording MBID of rows whose file was another song's (the
// duplicate resolver's wrong-slot removal). The MBID came from that file, so it
// names the song kept elsewhere on the album, and missing-pair folding would
// fold the emptied slot into it, so it would never be wanted back.
// mbid_source goes with it (tracks_mbid_source_pair).
func (q *Queries) ClearTrackMbids(ctx context.Context, ids []pgtype.UUID) error {
_, err := q.db.Exec(ctx, clearTrackMbids, ids)
@@ -177,7 +177,7 @@ type DeleteTrackRow struct {
Mbid *string
}
// M7 #372: hard delete with FK cascade. The CASCADE on track_id from
// Hard delete with FK cascade. The CASCADE on track_id from
// play_events / general_likes_tracks / quarantine /
// quarantine_actions handles their cleanup. RETURNING gives us
// album_id + artist_id for the album-empty / artist-empty cascade
@@ -209,11 +209,11 @@ type FindMissingTrackByAudioHashRow struct {
FilePath string
}
// Move detection fallback for files with no MBID (#2528, #3914). The audio stream
// Move detection fallback for files with no MBID. The audio stream
// hash identifies the encoded audio itself, so it survives a rename, a move and a
// retag — anything short of a re-encode. It replaced (file_size, duration_ms),
// which could pair two unrelated files that happened to share a byte count and a
// duration, and missed a file retagged in place, whose size changes.
// retag — anything short of a re-encode. (file_size, duration_ms) would pair two
// unrelated files that share a byte count and a duration, and miss a file
// retagged in place, whose size changes.
//
// Same missing-only constraint and same LIMIT 2 rationale as the MBID variant.
func (q *Queries) FindMissingTrackByAudioHash(ctx context.Context, audioStreamSha256 []byte) ([]FindMissingTrackByAudioHashRow, error) {
@@ -249,7 +249,7 @@ type FindMissingTrackByMbidRow struct {
FilePath string
}
// Move detection, strongest signal (#2528). A file that turned up at a new path
// Move detection, strongest signal. A file that turned up at a new path
// carrying a recording MBID we already have on a MISSING row is that recording,
// moved — not a new track.
//
@@ -287,8 +287,8 @@ UPDATE tracks
AND regexp_replace(file_path, '^.*/', '') ~* $1::text
`
// Holds back present tracks whose basename carries a video-rip marker (M498
// #5439), the same pattern the report lists. A track the operator called fine
// Holds back present tracks whose basename carries a video-rip marker, the
// same pattern the report lists. A track an admin called fine
// keeps that verdict.
func (q *Queries) FlagSuspectSourceTracks(ctx context.Context, pattern string) (int64, error) {
result, err := q.db.Exec(ctx, flagSuspectSourceTracks, pattern)
@@ -377,7 +377,7 @@ SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, f
`
// Batched lookup used by /api/library/sync to hydrate upsert payloads
// (#357). Mirror of GetArtistsByIDs.
// . Mirror of GetArtistsByIDs.
func (q *Queries) GetTracksByIDs(ctx context.Context, dollar_1 []pgtype.UUID) ([]Track, error) {
rows, err := q.db.Query(ctx, getTracksByIDs, dollar_1)
if err != nil {
@@ -451,7 +451,7 @@ type ListArtistTracksForUserRow struct {
ArtistName string
}
// M6a: every track for the artist across their albums, with album_title
// Every track for the artist across their albums, with album_title
// and artist_name joined. Honors per-user quarantine. Used by
// /api/artists/{id}/tracks for the artist-card play affordance, which
// shuffles client-side. Ordering matches album/track natural order so
@@ -545,19 +545,18 @@ type ListMissingTracksRow struct {
LastPlayedAt pgtype.Timestamptz
}
// The admin review surface for files the scan could not find (#2527).
// The admin review surface for files the scan could not find.
//
// Ordered by directory, then by the file's own position within its album,
// because the unit an operator actually reasons about is a FOLDER: the case
// this was built for was three whole albums that had been reorganised, and a
// flat list ordered by timestamp presents that as forty unrelated decisions.
// because the unit an admin actually reasons about is a FOLDER: a reorganised
// album, listed flat by timestamp, reads as dozens of unrelated decisions.
// Grouping happens in the handler; the ordering here is what makes a group
// contiguous, so a page boundary splits a directory at worst.
//
// last_played_at is a correlated MAX rather than a join so a track with no
// plays stays in the result with NULL. It is here because "gone six months,
// never played" and "gone yesterday, played 200 times" deserve opposite
// reactions, and the operator can't tell them apart from a path.
// reactions, and an admin can't tell them apart from a path.
func (q *Queries) ListMissingTracks(ctx context.Context, arg ListMissingTracksParams) ([]ListMissingTracksRow, error) {
rows, err := q.db.Query(ctx, listMissingTracks, arg.PageOffset, arg.PageLimit)
if err != nil {
@@ -616,7 +615,7 @@ type ListRandomTracksForUserRow struct {
ArtistName string
}
// #427 S4: backing query for GET /api/library/shuffle — the online
// Backing query for GET /api/library/shuffle — the online
// source for "Shuffle all". N random tracks across the whole
// library, per-user-quarantine filtered. $1 user_id, $2 limit.
func (q *Queries) ListRandomTracksForUser(ctx context.Context, arg ListRandomTracksForUserParams) ([]ListRandomTracksForUserRow, error) {
@@ -682,7 +681,7 @@ type ListStillMissingTrackLabelsRow struct {
}
// Which of the tracks a scan marked missing still are once it has adopted
// moves and folded replacements (M542): the ones worth telling an admin
// moves and folded replacements: the ones worth telling an admin
// about, by name. A quality upgrade folds into its replacement and drops out.
func (q *Queries) ListStillMissingTrackLabels(ctx context.Context, ids []pgtype.UUID) ([]ListStillMissingTrackLabelsRow, error) {
rows, err := q.db.Query(ctx, listStillMissingTrackLabels, ids)
@@ -719,7 +718,7 @@ SELECT t.id,
t.source_verdict,
t.source_verdict_at,
-- The album's place on the wanted list: wanted for a clean copy, and
-- when that was last searched for (#5524).
-- when that was last searched for.
COALESCE(w.upgrade, '')::text AS want_upgrade,
w.searched_at AS searched_at
FROM tracks t
@@ -760,7 +759,7 @@ type ListSuspectSourceTracksRow struct {
}
// The admin report of present tracks whose filename looks like a video rip
// (#5410): "(Official Video)", "[Audio]", "Visualizer" and the like.
// : "(Official Video)", "[Audio]", "Visualizer" and the like.
//
// pattern is built in Go (internal/api/admin_suspect_sources.go) from the
// same marker list that labels each row, so the filter and the labels cannot
@@ -816,7 +815,7 @@ type ListTrackPathsForReconcileRow struct {
}
// Every row's path + current missing mark, for the scanner's reconcile pass
// (#2523). Deliberately unfiltered and unpaged: reconcile has to compare the
// . Deliberately unfiltered and unpaged: reconcile has to compare the
// WHOLE table against what the walk saw, and a filtered subset would let rows
// outside it drift forever. Three narrow columns keep it cheap even on a
// library of a few hundred thousand tracks.
@@ -921,7 +920,7 @@ type ListTracksMissingMbidWithPathRow struct {
// Track recording-MBID backfill: tracks with NULL mbid that still have
// a file to re-read. $1 caps the batch (mirrors the album backfill).
// Missing tracks are skipped: there is no file, and opening it anyway
// logged a warning per track on every scan (#5139).
// would log a warning per track on every scan.
func (q *Queries) ListTracksMissingMbidWithPath(ctx context.Context, limit int32) ([]ListTracksMissingMbidWithPathRow, error) {
rows, err := q.db.Query(ctx, listTracksMissingMbidWithPath, limit)
if err != nil {
@@ -1081,7 +1080,7 @@ type SetTrackSourceVerdictParams struct {
ID pgtype.UUID
}
// The operator's call on a flagged track: 'fine' lets it back into radio and
// An admin's call on a flagged track: 'fine' lets it back into radio and
// the mixes for good; 'suspect' holds it back again.
func (q *Queries) SetTrackSourceVerdict(ctx context.Context, arg SetTrackSourceVerdictParams) (int64, error) {
result, err := q.db.Exec(ctx, setTrackSourceVerdict, arg.Verdict, arg.ID)
@@ -1115,7 +1114,7 @@ ON CONFLICT (file_path) DO UPDATE SET
WHEN tracks.mbid_source = 'acoustid' THEN 'acoustid' END,
genre = EXCLUDED.genre,
-- Stamped on update too, so a tag-repair pass marks rows as done and the
-- next scan can short-circuit them again (#2499).
-- next scan can short-circuit them again.
tag_read_version = EXCLUDED.tag_read_version,
updated_at = now()
RETURNING id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version, tag_read_version, missing_since, mbid_source, song_id, song_key, source_verdict, source_verdict_at, emptied_at
@@ -1138,8 +1137,8 @@ type UpsertTrackParams struct {
}
// file_path is the canonical identity for library scan; mbid is secondary.
// mbid is the file's tag. A looked-up id (mbid_source 'acoustid', M401)
// survives a re-read that finds no tag id, and a tag id replaces it (D4).
// mbid is the file's tag. A looked-up id (mbid_source 'acoustid')
// survives a re-read that finds no tag id, and a tag id replaces it.
func (q *Queries) UpsertTrack(ctx context.Context, arg UpsertTrackParams) (Track, error) {
row := q.db.QueryRow(ctx, upsertTrack,
arg.Title,
+1 -1
View File
@@ -584,7 +584,7 @@ type SetSubsonicPasswordParams struct {
// Stores (or clears with NULL) the per-user Subsonic legacy credential used
// for t/s and p auth on /rest/*. Must be plaintext; see migration 0003. Only
// ever a server-generated value, never the login password (#5026).
// ever a server-generated value, never the login password.
func (q *Queries) SetSubsonicPassword(ctx context.Context, arg SetSubsonicPasswordParams) error {
_, err := q.db.Exec(ctx, setSubsonicPassword, arg.ID, arg.SubsonicPassword)
return err
+21 -21
View File
@@ -68,15 +68,15 @@ const countWants = `-- name: CountWants :one
SELECT COUNT(*) FILTER (WHERE fulfilled_at IS NULL AND reason <> 'missing')::bigint AS wanted,
COUNT(*) FILTER (WHERE fulfilled_at IS NULL AND reason = 'missing')::bigint AS missing,
COUNT(*) FILTER (WHERE fulfilled_at IS NOT NULL)::bigint AS held,
-- Held albums wanted for a better copy (#5524).
-- Held albums wanted for a better copy.
COUNT(*) FILTER (WHERE fulfilled_at IS NOT NULL AND upgrade <> '')::bigint AS upgrades,
COUNT(DISTINCT artist_mbid)::bigint AS artists,
-- Library albums waiting to be matched by hand (#5579).
-- Library albums waiting to be matched by hand.
(SELECT COUNT(*) FROM library_album_matches m
WHERE m.outcome = 'unmatched'
AND EXISTS (SELECT 1 FROM tracks t WHERE t.album_id = m.album_id))::bigint AS unmatched,
(SELECT COUNT(*) FROM follows)::bigint AS following,
-- The Wanted view's other tabs (#5522): downloads running, those
-- The Wanted view's other tabs: downloads running, those
-- waiting on a person, and releases set aside.
(SELECT COUNT(*) FROM grabs WHERE ended_at IS NULL)::bigint AS activity,
(SELECT COUNT(*) FROM grabs
@@ -324,7 +324,7 @@ type GetLibraryListingRow struct {
LibraryUnlisted int32
}
// The one-time listing of the library (#5567). ---------------------------
// The one-time listing of the library. ---------------------------
func (q *Queries) GetLibraryListing(ctx context.Context) (GetLibraryListingRow, error) {
row := q.db.QueryRow(ctx, getLibraryListing)
var i GetLibraryListingRow
@@ -361,7 +361,7 @@ type GetWantAlbumRow struct {
AlbumID pgtype.UUID
}
// What the Wanted view's track list needs of a want (#5572).
// What the Wanted view's track list needs of a want.
func (q *Queries) GetWantAlbum(ctx context.Context, id pgtype.UUID) (GetWantAlbumRow, error) {
row := q.db.QueryRow(ctx, getWantAlbum, id)
var i GetWantAlbumRow
@@ -547,9 +547,9 @@ type ListAlbumsToMatchRow struct {
// Library albums the listing has not decided, or that an older matcher
// refused, or whose tracks changed since they were refused: each is matched
// to MusicBrainz (#5569). A library album is one from before the cutoff, or
// to MusicBrainz. A library album is one from before the cutoff, or
// one whose tracks were: a re-tag files a track under a new album row but
// keeps the track (#5579). An album row with no tracks is not an album in
// keeps the track. An album row with no tracks is not an album in
// the library; one a person left off stays off.
func (q *Queries) ListAlbumsToMatch(ctx context.Context, arg ListAlbumsToMatchParams) ([]ListAlbumsToMatchRow, error) {
rows, err := q.db.Query(ctx, listAlbumsToMatch, arg.Cutoff, arg.Matcher, arg.MaxRows)
@@ -752,7 +752,7 @@ type ListHeldWantFormatsRow struct {
Rips int32
}
// Upgrades (#5524). -------------------------------------------------------
// Upgrades. -------------------------------------------------------
// What each held album's copy is made of, for judging whether it is worth
// upgrading: its present tracks grouped by format, with their bytes and
// length summed, and how many are held back as video rips. A held want whose
@@ -936,7 +936,7 @@ type ListReleaseTypeProfilesRow struct {
FollowCount int64
}
// The wanted list (M502 #5520): release-type profiles, follows and wants.
// The wanted list: release-type profiles, follows and wants.
func (q *Queries) ListReleaseTypeProfiles(ctx context.Context) ([]ListReleaseTypeProfilesRow, error) {
rows, err := q.db.Query(ctx, listReleaseTypeProfiles)
if err != nil {
@@ -988,7 +988,7 @@ type ListUnmatchedLibraryAlbumsRow struct {
Tracks int32
}
// The Collection's Unmatched section (#5579): the albums the listing could
// The Collection's Unmatched section: the albums the listing could
// not match, and below them the ones a person left off. An album whose
// tracks have all moved to another row is gone, not unmatched.
func (q *Queries) ListUnmatchedLibraryAlbums(ctx context.Context, maxRows int32) ([]ListUnmatchedLibraryAlbumsRow, error) {
@@ -1070,7 +1070,7 @@ type ListWantArtistsRow struct {
Total int64
}
// The Wanted view's main page (#5572): every artist on the list, A–Z like
// The Wanted view's main page: every artist on the list, A–Z like
// the library, with how many of their albums are held of how many are on
// the list. q matches the artist's name or any of their albums' titles;
// artist_mbid narrows to one artist, for their page's header.
@@ -1114,7 +1114,7 @@ func (q *Queries) ListWantArtists(ctx context.Context, arg ListWantArtistsParams
const listWants = `-- name: ListWants :many
SELECT w.id, w.release_group_mbid, w.artist_mbid, w.artist_name, w.title, w.reason,
w.album_id, w.wanted_at, w.fulfilled_at,
-- Why a held album is wanted again, and the copy it has (#5524).
-- Why a held album is wanted again, and the copy it has.
w.upgrade, w.held_quality,
-- A request names an album before the catalogue has read it: the
-- catalogue's type and date fill in once it has.
@@ -1124,10 +1124,10 @@ SELECT w.id, w.release_group_mbid, w.artist_mbid, w.artist_name, w.title, w.reas
u.username AS requested_by,
la.id AS library_artist_id,
COUNT(*) OVER () AS total,
-- The search schedule's last look (#5521), and the download running.
-- The search schedule's last look, and the download running.
w.searched_at, w.search_outcome, w.search_considered, w.best_release, w.best_verdict, w.search_error,
-- Its latest download, running or ended, and what the import made of
-- it (#5522).
-- it.
gr.id AS grab_id, gr.name AS grab_name, gr.grabbed_at, gr.origin AS grab_origin,
gr.quality AS grab_quality, gr.ended_at AS grab_ended_at, gr.end_reason AS grab_end_reason,
gr.progress AS grab_progress, gr.import_state AS grab_import_state,
@@ -1147,7 +1147,7 @@ SELECT w.id, w.release_group_mbid, w.artist_mbid, w.artist_name, w.title, w.reas
ELSE w.fulfilled_at IS NULL AND w.reason <> 'missing'
END
AND ($2::text = '' OR w.artist_mbid = $2::text)
-- want_ids narrows to given wants: the Missing page's folders (M504).
-- want_ids narrows to given wants: the Missing page's folders.
AND (COALESCE(cardinality($3::uuid[]), 0) = 0 OR w.id = ANY($3::uuid[]))
AND ($4::text = ''
OR strpos(lower(w.artist_name), lower($4::text)) > 0
@@ -1208,7 +1208,7 @@ type ListWantsRow struct {
// The Wanted page: open wants (all but missing ones, or only missing ones),
// the held ones, or all of them; artist_mbid narrows to one artist's page,
// want_ids to given wants. Ordered like the library (#5572): artists A–Z by the
// want_ids to given wants. Ordered like the library: artists A–Z by the
// library's sort name when it holds the artist, each artist's albums by
// release date, so the page groups them as they arrive. q narrows to an
// artist or album title; total counts every match, past the page.
@@ -1349,7 +1349,7 @@ ON CONFLICT (album_id) DO NOTHING
`
// The albums ListLibraryAlbums takes are decided as listed by their tags,
// so the matching that follows leaves them alone (#5569).
// so the matching that follows leaves them alone.
func (q *Queries) RecordListedAlbums(ctx context.Context, cutoff pgtype.Timestamptz) error {
_, err := q.db.Exec(ctx, recordListedAlbums, cutoff)
return err
@@ -1379,7 +1379,7 @@ type RepointWantParams struct {
ReleaseGroupMbid string
}
// A want recorded under a release id before #5241 is moved to its group.
// A want recorded under a release id is moved to its group.
func (q *Queries) RepointWant(ctx context.Context, arg RepointWantParams) error {
_, err := q.db.Exec(ctx, repointWant, arg.ID, arg.ReleaseGroupMbid)
return err
@@ -1571,10 +1571,10 @@ SELECT a.id AS album_id,
COALESCE(bool_or(t.missing_since IS NULL AND t.added_at > $1::timestamptz), false)::bool AS arrived_since,
COALESCE(bool_or(t.missing_since IS NOT NULL AND t.missing_since < $1::timestamptz), false)::bool AS missing_before,
-- Missing tracks no track on disk stands in for, by position or
-- title. A missing row whose song is back at a new path (#5245) is
-- title. A missing row whose song is back at a new path is
-- covered; a lost bonus track is not. A track with no disc number is
-- on disc 1: Air's Love 2 stayed wanted, and was downloaded again for
-- nothing, over a missing track 6 with no disc beside a present 1/6.
-- on disc 1, so a missing track 6 with no disc beside a present 1/6
-- does not keep the album wanted.
COUNT(*) FILTER (WHERE t.missing_since IS NOT NULL AND NOT EXISTS (
SELECT 1 FROM tracks p
WHERE p.album_id = a.id AND p.missing_since IS NULL
+1 -1
View File
@@ -26,7 +26,7 @@ type CountListeningSignalForUserRow struct {
DistinctArtists int64
}
// "You might like" Home rows (#790). The daily build computes ranked
// "You might like" Home rows. The daily build computes ranked
// album/artist IDs in Go (similarity roll-up + cold-start gate) and
// atomic-replaces them here; /api/home reads them back hydrated.
// Cold-start gate. Returns the breadth of the user's real listening:
@@ -1,5 +1,5 @@
-- Core library schema per spec §5. Dual-like, session, scrobble, and
-- similarity tables land with their respective feature milestones.
-- Core library schema: artists, albums, tracks and users. Likes, sessions,
-- scrobbling and similarity get tables of their own in later migrations.
CREATE EXTENSION IF NOT EXISTS "pgcrypto";
+3 -4
View File
@@ -1,10 +1,9 @@
-- Session tokens authenticate /api/* requests. We store sha256(token) so a
-- read-only DB leak doesn't grant active sessions; the raw token lives only
-- in the client's cookie (web) or bearer header (Flutter).
-- in the client's cookie (web) or bearer header (native clients).
--
-- last_seen_at enables an "active sessions" UI later (not wired in this plan)
-- without schema churn. user_agent is captured at issue time for the same
-- reason — free metadata now, no migration later.
-- last_seen_at and user_agent (captured at issue time) are for an "active
-- sessions" list.
CREATE TABLE sessions (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+5 -6
View File
@@ -1,11 +1,10 @@
-- M2 listening telemetry: play_sessions, play_events, skip_events.
-- Note the table is named play_sessions (not sessions — that table already
-- Listening telemetry: play_sessions, play_events, skip_events.
-- The table is named play_sessions (not sessions — that table already
-- exists from migration 0004 and holds HTTP auth sessions). Listening
-- sessions are an entirely separate concept driven by spec §6.
-- sessions are an entirely separate concept.
--
-- session_vector_at_play and contextual_likes ship as nullable now even
-- though M2 writes NULL; M3 will populate them without a follow-up
-- migration.
-- session_vector_at_play is nullable: plays are recorded before the
-- recommendation engine fills it.
CREATE TABLE play_sessions (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+2 -3
View File
@@ -1,6 +1,5 @@
-- M2 likes: three tables, one per entity type. Schema follows the spec §5
-- pattern (general_likes was originally track-only); this slice extends it
-- to albums and artists for full Subsonic star/unstar support.
-- Likes: three tables, one per entity type. general_likes was track-only;
-- albums and artists get the same shape for Subsonic star/unstar.
CREATE TABLE general_likes (
user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
@@ -1,16 +1,12 @@
-- contextual_likes captures a per-session-context snapshot at the time of
-- each like. The recommendation engine in M3 sub-plan #3 uses these rows
-- to compute contextual_match_score per (current session, candidate track).
-- contextual_likes captures a per-session-context snapshot at the time of each
-- like. The recommendation engine uses these rows to compute
-- contextual_match_score per (current session, candidate track).
--
-- Multiple rows per (user, track) are allowed and expected — each row
-- represents a like in a specific session context. Soft-deleted rows
-- remain in the table (deleted_at populated) but are filtered out of the
-- engine's queries via the partial index. Re-liking a previously-unliked
-- track adds a NEW row (does not undelete the old one).
--
-- Note: the M2 events migration (0005) commented that contextual_likes
-- "ships nullable now" but the actual CREATE TABLE was missed. This slice
-- ships the table for the first time.
CREATE TABLE contextual_likes (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -27,6 +23,6 @@ CREATE INDEX contextual_likes_active_idx
ON contextual_likes (user_id, track_id)
WHERE deleted_at IS NULL;
-- Vector similarity queries from M3 sub-plan #3 will use this.
-- For the engine's vector similarity queries.
CREATE INDEX contextual_likes_vector_idx
ON contextual_likes USING gin (session_vector);
+3 -3
View File
@@ -1,8 +1,8 @@
-- M4a: outbound ListenBrainz scrobble worker.
-- Outbound ListenBrainz scrobble worker.
-- Per-user LB config (plaintext token; users rotate via /settings if leaked).
-- scrobble_queue is a work list, not a log: successfully-sent rows are
-- DELETEd by the worker (the canonical record stays in play_events.scrobbled_at
-- via M2's column). Only `pending` and `failed` states exist.
-- DELETEd by the worker (the canonical record stays in
-- play_events.scrobbled_at). Only `pending` and `failed` states exist.
ALTER TABLE users
ADD COLUMN listenbrainz_token TEXT NULL,
@@ -1,4 +1,4 @@
-- M4b: ListenBrainz similarity ingest. Two symmetric tables — tracks and
-- ListenBrainz similarity ingest. Two symmetric tables — tracks and
-- artists — both keyed by (a_id, b_id, source) so the schema reserves room
-- for additional similarity sources (musicbrainz_tag, user_cooccurrence)
-- alongside listenbrainz. M4b only writes 'listenbrainz' rows.
+2 -2
View File
@@ -1,6 +1,6 @@
-- M5a: Lidarr integration foundation. Two tables:
-- Lidarr integration. Two tables:
--
-- lidarr_config — singleton (CHECK id=1) holding the operator's Lidarr
-- lidarr_config — singleton (CHECK id=1) holding the Lidarr
-- connection. enabled=false is the unconfigured state.
--
-- lidarr_requests — per-request lifecycle row created by users at
@@ -1,4 +1,4 @@
-- M5b: per-user track quarantines + admin action audit log.
-- Per-user track quarantines + admin action audit log.
--
-- lidarr_quarantine — one row per (user, track) complaint. PK matches
-- the general_likes pattern. Re-flagging the same track upserts. Deleted
@@ -1,4 +1,4 @@
-- M5c: persist unmatched-similar-artist MBIDs that the M4b worker would
-- Persist unmatched-similar-artist MBIDs that the M4b worker would
-- otherwise discard. Mirrors artist_similarity shape: same composite PK
-- with source, same (seed_id, score DESC) index, same source enum check.
-- The candidate side is text + name (no FK) — that's the whole point.
@@ -1,9 +1,8 @@
-- M6a follow-up: persist the operator's metadata-profile choice alongside
-- quality profile + root folder. Lidarr POST /api/v1/artist requires
-- metadataProfileId; without storing it we'd refetch and pick first on
-- every Approve, denying the operator a choice. Nullable: existing rows
-- (and operators upgrading from before this migration) get NULL and the
-- service falls back to "fetch list and pick first" until they save.
-- Persist the chosen Lidarr metadata profile alongside quality profile +
-- root folder. Lidarr POST /api/v1/artist requires metadataProfileId;
-- without storing it every Approve would refetch and pick the first.
-- Nullable: existing rows get NULL and the service falls back to "fetch
-- list and pick first" until an admin saves.
ALTER TABLE lidarr_config
ADD COLUMN default_metadata_profile_id integer;
+1 -2
View File
@@ -1,5 +1,4 @@
-- M7 #352 slice 1: playlists CRUD foundation.
-- See docs/superpowers/specs/2026-05-03-m7-playlists-crud-design.md.
-- User playlists.
CREATE TABLE playlists (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -1,7 +1,7 @@
-- M7 #352 slice 2: system-generated playlists.
-- System-generated playlists.
-- Adds kind/system_variant/seed_artist_id columns to playlists and a
-- per-user run-tracking table. Backfills existing slice-1 playlists
-- to kind='user'.
-- per-user run-tracking table. Backfills existing playlists to
-- kind='user'.
-- Discriminator on existing playlists table.
ALTER TABLE playlists
@@ -1,5 +1,5 @@
-- M7 #353: album cover origin attribution.
-- 'embedded' — extracted from audio file (reserved for future slice).
-- Album cover origin attribution.
-- 'embedded' — extracted from audio file (reserved).
-- 'sidecar' — found in the album directory (cover.jpg/folder.jpg/etc).
-- 'mbcaa' — fetched from MusicBrainz Cover Art Archive.
-- 'none' — tried, no cover available. Skip auto-retry; only manual.
+1 -1
View File
@@ -1,4 +1,4 @@
-- M7 #381: track library-scan / MBID-backfill / cover-enrich runs so the
-- Track library-scan / MBID-backfill / cover-enrich runs so the
-- admin overview can show last-run results + manual trigger state.
CREATE TABLE scan_runs (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -1,6 +1,5 @@
-- M7 cover-sources: schema for additional cover-art providers (TheAudioDB
-- as the v1 implementation), artist art (thumb + fanart), and the
-- recheck-on-source-change trigger.
-- Schema for additional cover-art providers (TheAudioDB first), artist art
-- (thumb + fanart), and the recheck-on-source-change trigger.
-- (0) Extend the existing albums.cover_art_source CHECK to accept the
-- new 'theaudiodb' value. The constraint was created in migration 0016
@@ -1,4 +1,4 @@
-- M7 recurring-scans: singleton table holding the operator's schedule
-- Recurring scans: singleton table holding the scan schedule
-- config. mode is the discriminator: 'off' / 'interval' / 'daily' / 'weekly'.
-- Per-mode fields are populated only when their mode is selected; others
-- stay NULL. weekly_day uses ISO 8601: 1=Monday … 7=Sunday.
@@ -1,5 +1,5 @@
-- Relax cover-art and artist-art source CHECK constraints so the new
-- Deezer and Last.fm providers (next slice) can persist their IDs as
-- Deezer and Last.fm providers can persist their IDs as
-- accepted source values. Also add the
-- last_registered_providers_hash column to cover_art_sources_meta for
-- boot-time auto-bump detection (when the registered-provider set
@@ -1,14 +1,14 @@
-- User management foundation (U1 of #376):
-- User management:
--
-- - users.display_name: optional human-readable name distinct from username.
-- - user_invites: admin-generated tokens; user redeems during signup.
-- - registration_settings (singleton): controls whether registration is
-- 'invite_only' (default after first admin) or 'open' (admin can
-- re-enable). The handler in U1-T2 also has a special-case for the
-- re-enable). The registration handler also has a special-case for the
-- "no users yet" state where it ignores invites and lets the first
-- register as admin.
-- - audit_log: append-only record of admin-driven user mutations.
-- No retention policy in v1.
-- No retention policy.
ALTER TABLE users ADD COLUMN IF NOT EXISTS display_name text;
@@ -1,7 +1,5 @@
-- Adds users.auto_approve_requests for the per-user auto-approve toggle
-- (#355 sub-feature surface). The handler that honors this flag in
-- the request submission flow is sibling work (U2.5 follow-up); this
-- migration just lands the schema + the column default.
-- Adds users.auto_approve_requests for the per-user auto-approve toggle:
-- the request submission flow approves that user's requests at once.
--
-- Default false: existing users keep manual approval, opt-in via the
-- admin user-management UI.
@@ -1,13 +1,10 @@
-- Append-only change log for library entities. Every mutation on
-- artists/albums/tracks/likes/playlists/playlist_tracks writes a row
-- in the same transaction as the mutation itself. Powers the Flutter
-- delta-sync endpoint (#357) — clients pass back the last-seen `id`
-- as a cursor.
-- in the same transaction as the mutation itself. Powers the delta-sync
-- endpoint — clients pass back the last-seen `id` as a cursor.
--
-- Retention: not capped here. If the table grows unbounded a follow-up
-- adds a periodic compactor (collapse contiguous upserts on the same
-- entity, drop pre-delete history). Cursor reset path (410) covers the
-- compactor's edge.
-- Retention: not capped here. A cursor older than what the table keeps gets
-- the reset path (410).
CREATE TABLE library_changes (
id BIGSERIAL PRIMARY KEY,
@@ -1,5 +1,5 @@
-- 0026_users_timezone.up.sql — per-user timezone for the system-playlist
-- scheduler (#392 Half B). Default 'UTC' so existing rows + brand-new
-- scheduler. Default 'UTC' so existing rows + brand-new
-- users have a safe value before their first client check-in via
-- PUT /api/me/timezone. The scheduler reads this column to decide
-- which IANA zone to anchor each user's daily 03:00 build to.
@@ -1,5 +1,5 @@
-- 0027_system_playlist_rotation.up.sql — sample-history dedup for
-- system playlists (Fable #415). Two parts:
-- system playlists. Two parts:
--
-- 1. play_events.source: which system playlist a play originated
-- from ('for_you' | 'discover' | future kinds), or NULL for any
@@ -1,11 +1,9 @@
-- #411 R3 bugfix: the five discovery mixes (deep_cuts, rediscover,
-- new_for_you, on_this_day, first_listens) were added as producers +
-- registry entries but their system_variant values were never added
-- to the two playlists CHECK constraints. Result: insertSystemPlaylist
-- for any new mix fails with playlists_kind_variant_consistent
-- (SQLSTATE 23514), which — because BuildSystemPlaylists is one
-- all-or-nothing transaction — aborts the WHOLE build, so For-You /
-- Discover refresh 500s and the lazy daily build fails too.
-- Before: the five discovery mixes (deep_cuts, rediscover, new_for_you,
-- on_this_day, first_listens) had producers and registry entries but no
-- system_variant values in the two playlists CHECK constraints, so inserting
-- any of them failed playlists_kind_variant_consistent (SQLSTATE 23514) —
-- and because BuildSystemPlaylists is one all-or-nothing transaction, that
-- aborts the WHOLE build. After: the constraints accept them.
--
-- All five are seedless (like for_you/discover): seed_artist_id IS
-- NULL. Drop + re-add both constraints with the expanded set, same
@@ -2,9 +2,8 @@
-- provider's registry ID. coverart.Register makes the provider set
-- extensible, so a fixed IN-list CHECK (0016 → 0018 → 0020) required a
-- schema migration for every new provider and rejected any
-- out-of-list value (e.g. test stub providers). Same brittleness
-- class as the discovery-mix CHECK incident (#433): a fixed-value
-- CHECK fighting an extensible value set. Relax to "NULL or any
-- out-of-list value (e.g. test stub providers): a fixed-value CHECK
-- fighting an extensible value set. Relax to "NULL or any
-- non-empty string" — the registry, not the schema, is the source of
-- truth for valid provider IDs.
@@ -2,7 +2,7 @@
-- for an approved request. NULL = not yet sent/confirmed; the
-- reconciler idempotently (re)sends the add until this is set, then
-- watches for the import. Decouples the durable admin approval from the
-- best-effort Lidarr call so a transient Lidarr outage no longer forces
-- a manual re-approve.
-- best-effort Lidarr call, so a transient Lidarr outage does not force a
-- manual re-approve.
ALTER TABLE lidarr_requests
ADD COLUMN lidarr_add_confirmed_at timestamptz;
@@ -1,6 +1,6 @@
-- Client-reported playback errors. Populated by clients when a track
-- fails to play (zero duration, decode error, etc.); surfaced in the
-- admin /admin/playback-errors inbox so the operator can hide / delete
-- admin /admin/playback-errors inbox so an admin can hide / delete
-- / re-request the offending track.
--
-- resolved_at + resolved_by + resolution are NULL until an admin acts
@@ -10,8 +10,8 @@
-- unresolved-queue lookup fast even as resolved history accumulates.
--
-- CHECK constraints on kind/resolution gate the enum values so client
-- typos can't pollute the data (per the standing rule about
-- enum-CHECK whitelists needing migrations).
-- typos can't pollute the data; a new value means swapping the constraint
-- in the same migration as the code that writes it.
CREATE TABLE playback_errors (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -1,4 +1,4 @@
-- Retire the configurable scan scheduler. New-file pickup is now handled by
-- the fsnotify watcher + a hardcoded safety-net delta walk (cmd/minstrel),
-- so the operator-configurable schedule (and its admin UI) is gone.
-- so the configurable schedule (and its admin UI) is gone.
DROP TABLE IF EXISTS scan_schedule;
@@ -1,4 +1,4 @@
-- 0034_you_might_like.up.sql — "You might like" Home rows (#790).
-- 0034_you_might_like.up.sql — "You might like" Home rows.
--
-- Per-user ranked lists of IN-LIBRARY albums/artists the listener
-- doesn't actively spin but is predicted to enjoy, derived from the
@@ -1,11 +1,11 @@
-- 0035_taste_profile.up.sql — per-user taste profile (#796 phase 1).
-- 0035_taste_profile.up.sql — per-user taste profile.
--
-- A persistent, decaying model of each user's taste, rebuilt daily from
-- graded play engagement (completion + skip position) plus explicit
-- likes. Two facet tables: weighted artists and weighted genre tags.
-- Weight is a signed float — positive = drawn to, negative = (passively)
-- avoided; magnitude reflects decayed engagement. Phase 1 only BUILDS
-- these; consumption (candidate sourcing + scoring) lands in phase 2.
-- avoided; magnitude reflects decayed engagement. Candidate sourcing and
-- scoring read them.
--
-- CASCADE on user/artist deletes keeps them clean. Indexed by
-- (user_id, weight DESC) to serve "top taste artists/tags" reads cheaply.
@@ -1,4 +1,4 @@
-- Device diagnostics / debug-reporting subsystem (M9).
-- Device diagnostics / debug-reporting subsystem.
--
-- When an account has users.debug_mode_enabled = true, that account's
-- client(s) stream a timeseries of device state here: connectivity +
@@ -8,12 +8,12 @@
-- /admin/diagnostics view filters by account + device + time window and
-- exports the slice as JSON for offline analysis.
--
-- `kind` is a COARSE category gated by a CHECK whitelist; the finer
-- event discriminator + all event-specific fields live in the `payload`
-- jsonb. This keeps the enum small and stable so new event variants
-- don't require a migration (per the enum-CHECK-whitelist rule, only a
-- new *category* would). If you add a category here, mirror it in the
-- handler whitelist in internal/api/diagnostics.go.
-- `kind` is a COARSE category gated by a CHECK whitelist; the finer event
-- discriminator + all event-specific fields live in the `payload` jsonb. This
-- keeps the enum small and stable so new event variants don't require a
-- migration (only a new *category* would: a new CHECK value means swapping the
-- constraint in the same migration). If you add a category here, mirror it in
-- the handler whitelist in internal/api/diagnostics.go.
--
-- Two timestamps on purpose: occurred_at is the client device clock
-- (when the event happened on the phone — may be skewed/wrong, e.g. in
@@ -1,14 +1,14 @@
-- Add 'playback' to the diagnostic_events kind whitelist (M9 follow-up).
-- Add 'playback' to the diagnostic_events kind whitelist.
--
-- `route` and `player_state` events fire for EVERY output route (phone
-- speaker, Bluetooth, UPnP/Sonos), so bucketing them under 'upnp_sync'
-- was misleading — an operator on Bluetooth earbuds saw "upnp_sync"
-- was misleading — a listener on Bluetooth earbuds produced "upnp_sync"
-- rows. 'upnp_sync' now means genuinely UPnP/Sonos-specific signal
-- (drops, and future resync/desync); general playback + route telemetry
-- moves to the new 'playback' kind.
--
-- Per the enum-CHECK-whitelist rule, the new value lands by dropping and
-- re-adding the constraint in the same change. Existing rows tagged
-- The new value lands by dropping and re-adding the constraint in the same
-- migration. Existing rows tagged
-- 'upnp_sync' stay as-is (debug telemetry on a 30-day retention).
ALTER TABLE diagnostic_events DROP CONSTRAINT diagnostic_events_kind_check;
@@ -1,9 +1,9 @@
-- For You exploration attribution (milestone #127 step 2, Scribe #1249).
-- For You exploration attribution.
--
-- For You is deliberately composed of two populations: a head of
-- top-scored similarity matches ("taste" picks) and a tail sampled from
-- deeper in the candidate ranking ("fresh" picks — the freshness
-- injection). Until now the metrics could only judge For You as one
-- injection). Before this the metrics could only judge For You as one
-- blob, so a high skip rate couldn't be read as "the taste engine is
-- missing" vs "the freshness tax is too high".
--
@@ -1,6 +1,6 @@
-- Provenance as standard (milestone #127, Scribe #1270).
-- Provenance as standard.
--
-- #1249 introduced pick_kind as a For You one-off ('taste'/'fresh').
-- 0038 introduced pick_kind as a For You one-off ('taste'/'fresh').
-- The mechanism — stamp WHY a track is in the snapshot at build time,
-- freeze it onto the play at ingestion, break it down in metrics — is
-- now the standard for every system mix, so the CHECK vocabulary
@@ -11,9 +11,9 @@
-- Discover's three candidate buckets — makes
-- the 40/30/30 allocation measurable instead
-- of a guess
-- tier1 / tier2 / tier3 the tiered-eligibility ladder (project rule
-- #131): tier 1 pins the mix's exact desire,
-- each higher tier steps back a little. Tier
-- tier1 / tier2 / tier3 the tiered-eligibility ladder: tier 1 pins the
-- mix's exact desire, each higher tier steps
-- back a little. Tier
-- provenance is how we measure what the
-- step-back trades away.
--
@@ -1,11 +1,10 @@
-- Recommendation tuning lab (milestone #127, Scribe #1250).
-- Recommendation tuning lab.
--
-- The scoring weights move out of YAML (radio profile) and out of the
-- systemMixWeights hard-code (daily_mix profile) into DB-backed
-- settings with live effect — the defaults-discovery lab (decision
-- #1247): the operator turns knobs here to FIND good values, which
-- then get baked into shipped defaults; end users and other operators
-- should never need this card.
-- settings with live effect — a lab for FINDING good values, which then
-- get baked into shipped defaults; nobody should need this card to get
-- good recommendations.
--
-- Rows are seeded by the recsettings service's boot reconcile (the
-- coverart SettingsService pattern), not by this migration, so shipped
@@ -39,7 +38,7 @@ CREATE TABLE taste_tuning (
);
-- Every knob turn writes one audit row; the metrics trend view
-- (#1251) annotates these on its timeline so cause→effect is visible
-- annotates these on its timeline so cause→effect is visible
-- after a change. changes is a jsonb array of {field, old, new}.
CREATE TABLE recommendation_tuning_audit (
id bigserial PRIMARY KEY,
@@ -1,16 +1,13 @@
-- Discover taste-targeted novelty bucket (milestone #127, Scribe #1252/#1488).
-- Discover taste-targeted novelty bucket.
--
-- The 2-week metrics review found Discover beating the manual baseline on
-- skip rate — which for a discovery surface means it is playing it safe:
-- on a single-user server it is effectively dormant + crude-random, and
-- the per-user taste profile (n_tags, #796) went unused. This adds a
-- Without it, Discover on a single-user server is effectively dormant +
-- crude-random, and the per-user taste profile's tags go unused. This adds a
-- fourth Discover candidate bucket that ranks unheard tracks by the
-- user's taste-profile tag weights ("novelty that fits your vibe"), so
-- its picks need a new pick_kind provenance value.
--
-- Postgres CHECK whitelists can't be altered in place: DROP + re-ADD with
-- the expanded list, in the same migration (family rule — new CHECK-enum
-- value needs a same-change migration).
-- the expanded list, in the same migration.
ALTER TABLE playlist_tracks
DROP CONSTRAINT playlist_tracks_pick_kind_check;
ALTER TABLE playlist_tracks
@@ -1,4 +1,4 @@
-- Track-level folksonomy tags for taste enrichment (milestone #160, #1490).
-- Track-level folksonomy tags for taste enrichment.
--
-- A global (not per-user) cache of style/mood tags fetched from
-- MusicBrainz (keyless) + Last.fm (when a key is configured), keyed by
@@ -1,4 +1,4 @@
-- Tag-enrichment provider settings (milestone #160, #1490 Step 2).
-- Tag-enrichment provider settings.
--
-- Mirrors the cover-art provider-settings substrate (migration 0018) so
-- adding a new tag source later is "register a provider + it auto-upserts
@@ -28,8 +28,9 @@ CREATE TABLE tag_sources_meta (
INSERT INTO tag_sources_meta (id, current_version) VALUES (true, 1);
-- Seed the v1 providers. MusicBrainz is the keyless always-on default;
-- Last.fm ships disabled and is opt-in once the operator supplies a key
-- (Step 4 Settings UI), per the no-coercive-settings rule (#26). The
-- Last.fm ships disabled and is opt-in once an admin supplies a key in
-- Settings: a feature that needs a third-party account is never on by
-- default. The
-- SettingsService also upserts these at boot, so the seed is belt-and-
-- suspenders / documents the intended defaults.
INSERT INTO tag_provider_settings (provider_id, enabled, display_order) VALUES
@@ -1,6 +1,6 @@
-- Expose EnrichedTagScale in the tuning lab (#1520). Adds the enriched-tag
-- weight knob to the taste_tuning singleton so operators can dial how much
-- folksonomy tags (#1490) count vs raw ID3 genre. DEFAULT 0.5 backfills the
-- Expose EnrichedTagScale in the tuning lab. Adds the enriched-tag
-- weight knob to the taste_tuning singleton so an admin can dial how much
-- folksonomy tags count vs raw ID3 genre. DEFAULT 0.5 backfills the
-- existing row and matches taste.DefaultConfig().EnrichedTagScale.
ALTER TABLE taste_tuning
ADD COLUMN enriched_tag_scale double precision NOT NULL DEFAULT 0.5;
@@ -1,5 +1,5 @@
-- 0045_taste_profile_eras.up.sql — era/decade taste facet (#1530,
-- milestone #160 Opt 2). A third taste facet alongside artists + tags:
-- 0045_taste_profile_eras.up.sql — era/decade taste facet. A third taste
-- facet alongside artists + tags:
-- signed weights over decade buckets ("1990s") derived from
-- albums.release_date, rebuilt daily by internal/taste next to the
-- artist/tag facets. Weight is a signed float — positive = drawn to
@@ -18,8 +18,8 @@ CREATE TABLE taste_profile_eras (
CREATE INDEX taste_profile_eras_user_weight_idx
ON taste_profile_eras (user_id, weight DESC);
-- Era-facet build knob, tunable in the lab (mirrors enriched_tag_scale,
-- #1520): scales how strongly a decade-play imprints on the profile.
-- Era-facet build knob, tunable in the lab (mirrors enriched_tag_scale):
-- scales how strongly a decade-play imprints on the profile.
-- DEFAULT 0.5 backfills the existing singleton and matches
-- taste.DefaultConfig().EraScale; 0 disables the era facet entirely.
ALTER TABLE taste_tuning
@@ -1,5 +1,5 @@
-- 0046_context_time_weight.up.sql — time-of-day/weekday context conditioning
-- (#1531, milestone #160 Opt 3). Adds a per-profile scoring weight for the new
-- 0046_context_time_weight.up.sql — time-of-day/weekday context conditioning.
-- Adds a per-profile scoring weight for the new
-- context-affinity term: how strongly a candidate is boosted when its artist's
-- play history concentrates in the current daypart × weekday-type cell (in the
-- user's local timezone). Mirrors the other ScoringWeights columns.
@@ -7,6 +7,6 @@
-- DEFAULT 1.0 backfills both existing profile rows to a modest on-value; the
-- Go ShippedRadioWeights/ShippedDailyMixWeights carry the same 1.0 so fresh
-- installs seed identically. Reconcile only seeds MISSING rows (ON CONFLICT DO
-- NOTHING), so existing rows rely on this DEFAULT until an operator resets.
-- NOTHING), so existing rows rely on this DEFAULT until an admin resets.
ALTER TABLE recommendation_weight_profiles
ADD COLUMN context_time_weight double precision NOT NULL DEFAULT 1.0;
@@ -1,11 +1,11 @@
-- 0047_taste_profile_moods.up.sql — mood taste facet (#1534, milestone #160
-- Opt 2b). A fourth taste facet alongside artists + tags + eras: signed weights
-- over canonical mood buckets (melancholic / energetic / chill / …) derived
-- from a track's enriched folksonomy tags (#1490) via the internal/mood
-- vocabulary, rebuilt daily. Weight is a signed float — positive = drawn to
-- that mood, negative = passively avoided. Coverage is partial (grows with tag
-- enrichment), so it's a supplement, not a foundation. Mirrors
-- taste_profile_tags: CASCADE on user delete, indexed by (user_id, weight DESC).
-- 0047_taste_profile_moods.up.sql — mood taste facet. A fourth taste facet
-- alongside artists + tags + eras: signed weights over canonical mood buckets
-- (melancholic / energetic / chill / …) derived from a track's enriched
-- folksonomy tags via the internal/mood vocabulary, rebuilt daily. Weight is a
-- signed float — positive = drawn to that mood, negative = passively avoided.
-- Coverage is partial (grows with tag enrichment), so it's a supplement, not a
-- foundation. Mirrors taste_profile_tags: CASCADE on user delete, indexed by
-- (user_id, weight DESC).
CREATE TABLE taste_profile_moods (
user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
mood text NOT NULL,
@@ -1,9 +1,9 @@
-- 0048_play_events_device_class.up.sql — device-class context conditioning
-- (#1551, milestone #160 Opt 3b). Records which class of device a play came
-- from (mobile / web / …), sent by the client on play-start and normalized
-- server-side. Extends the #1531 time-of-day/weekday affinity cell to
-- (daypart × weekday × device) for the radio path. Nullable + no CHECK: values
-- are normalized in Go (avoids a CHECK-migration each time a client class is
-- added, rule #36), and historical rows stay NULL → excluded from the device
-- dimension (a graceful cold-start; the facet ramps as new plays land).
-- 0048_play_events_device_class.up.sql — device-class context conditioning.
-- Records which class of device a play came from (mobile / web / …), sent by
-- the client on play-start and normalized server-side. Extends the
-- time-of-day/weekday affinity cell (0046) to (daypart × weekday × device) for
-- the radio path. Nullable + no CHECK: values are normalized in Go, so a new
-- client class needs no migration, and historical rows stay NULL → excluded
-- from the device dimension (a graceful cold-start; the facet ramps as new
-- plays land).
ALTER TABLE play_events ADD COLUMN device_class text;
@@ -1,14 +1,15 @@
-- 0049_suggestion_snoozes.up.sql — time-boxed "not right now" on a Discover
-- artist suggestion (#2374, milestone #268 slice 3).
-- artist suggestion.
--
-- This is NOT a dislike. Rule #101 forbids a "Not for me" / thumbs-down /
-- exclusion UI, and a snooze deliberately isn't one: it records no verdict on
-- This is NOT a dislike. Minstrel has no "Not for me" / thumbs-down /
-- exclusion control — taste is learned from listening — and a snooze
-- deliberately isn't one: it records no verdict on
-- the music, expires on its own, and MUST NEVER feed the taste profile. It is
-- acquisition triage — "I don't want to request this right now" — so the same
-- candidate is free to return once snoozed_until passes. Anything that reads
-- this table as negative preference signal is a bug.
--
-- Per-user (rule #47), never global: one household member parking a
-- Per-user, never global: one household member parking a
-- suggestion must not remove it from anyone else's deck.
--
-- candidate_mbid is text with NO foreign key, on purpose. Suggestions come
@@ -1,18 +1,17 @@
-- 0050_candidate_artist_tags.up.sql — folksonomy tags for OUT-OF-LIBRARY
-- artists (#2376, milestone #268 slice 5).
-- artists.
--
-- track_tags (0042) cannot hold these: it is FK'd to tracks(id), and a
-- Discover candidate has no local row by definition. So this is a parallel
-- cache keyed by the candidate's MusicBrainz MBID — the only stable identity
-- available for an artist we don't have.
--
-- Purpose is slice 6: rank suggestions by overlap between these tags and the
-- Purpose: rank Discover suggestions by overlap between these tags and the
-- user's taste_profile_tags, turning "neighbour of an artist you play" into
-- "matches the sound you like".
--
-- GLOBAL, not per-user: a candidate's tags are a property of the artist, not
-- of anyone's taste. Nothing here is user-scoped, so rule #47 has nothing to
-- scope — the per-user part lives entirely in slice 6's ranking.
-- of anyone's taste. The per-user part lives entirely in the ranking.
--
-- weight is a normalized folksonomy strength in [0,1], same scale as
-- track_tags, so the two can be compared without a conversion step.
@@ -1,14 +1,14 @@
-- 0051_discover_tuning.up.sql — tunable knobs for the Discover request
-- surface (#2377, milestone #268 slice 6).
-- surface.
--
-- A FOURTH tuning scope alongside radio / daily_mix / taste. Its own scope
-- rather than extra columns on taste_tuning, for a reason that matters:
-- snooze_days lives here, and a snooze must never be read as taste signal
-- (#2374). Filing it under 'taste' would put it one careless join away from
-- exactly the leak that design forbids.
-- (0049). Filing it under 'taste' would put it one careless join away from
-- exactly that leak.
--
-- Per rule #25 these are DB-backed and editable in the admin UI with no
-- restart — the shipped values below are defaults, not settings.
-- These are DB-backed and editable in the admin UI with no restart — the
-- shipped values below are defaults, not settings.
CREATE TABLE discover_tuning (
singleton boolean PRIMARY KEY DEFAULT true
CONSTRAINT discover_tuning_singleton_check CHECK (singleton),
@@ -17,10 +17,10 @@ CREATE TABLE discover_tuning (
-- [0,1]. So 0 disables the feature outright and leaves pure similarity
-- ranking, 1.0 lets a perfectly-matching candidate double its score, and
-- a candidate with no cached tags is unchanged rather than penalised
-- (rule #131 — tag coverage is permanently partial, see #2376).
-- (tag coverage is permanently partial, so a missing tag is no signal).
tag_overlap_weight double precision NOT NULL,
-- Default snooze duration in days. Was a Go constant in
-- internal/api/suggestions.go; moved here per rule #25.
-- Default snooze duration in days. Before this a Go constant in
-- internal/api/suggestions.go; now an admin setting.
snooze_days double precision NOT NULL,
updated_at timestamptz NOT NULL DEFAULT now()
);
@@ -1,4 +1,4 @@
-- Session provenance for the active-sessions surface (#370).
-- Session provenance for the active-sessions surface.
--
-- TWO addresses, not one, and the pair is the point: a session created at
-- home and now being used from somewhere else is the shape of a stolen
@@ -1,4 +1,4 @@
-- Trusted reverse-proxy depth for client-IP extraction (#2453).
-- Trusted reverse-proxy depth for client-IP extraction.
--
-- X-Forwarded-For grows left-to-right: each proxy APPENDS the peer it
-- received the request from. For client -> CDN -> own-proxy -> Minstrel the
@@ -11,14 +11,15 @@
--
-- Default 1: a publicly reachable Minstrel needs a TLS terminator in front of
-- it, and recording that terminator's own address for every session makes the
-- active-sessions surface (#370) useless — created_ip and last_ip would both
-- active-sessions surface useless — created_ip and last_ip would both
-- be the proxy, so the "address changed" signal could never fire.
--
-- The cost, stated on the admin card rather than buried: hops >= 1 DECLARES
-- that a proxy exists. If one doesn't, a client can forge X-Forwarded-For and
-- choose what its own session row shows, which defeats exactly the compromise
-- detection #370 exists for. That is inherent to the trusted-hop model, which
-- is why 0 is a first-class setting and not a hidden escape hatch.
-- detection the active-sessions surface exists for. That is inherent to the
-- trusted-hop model, which is why 0 is a first-class setting and not a hidden
-- escape hatch.
--
-- Upper bound 10 guards a typo turning into "trust the whole header"; no real
-- deployment chains ten proxies.
@@ -1,11 +1,11 @@
-- Records which version of the scanner's tag-extraction logic last wrote a
-- track's tag-derived columns (#2499).
-- track's tag-derived columns.
--
-- DEFAULT 0 is the point of this migration: every existing row lands below the
-- scanner's current library.tagReadVersion, so the next scan re-reads its tags
-- instead of short-circuiting on the mtime check. That repairs genre values the
-- old reader welded together ("Alternative Rock" + "Rock" -> "Alternative
-- RockRock") without asking the operator to wipe and rebuild the library.
-- RockRock") without anyone wiping and rebuilding the library.
--
-- Bump library.tagReadVersion in Go — not this default — whenever a tag
-- extraction fix needs to reach already-indexed files. That makes tag repairs a
@@ -1,4 +1,4 @@
-- Marks a track whose file the scanner could no longer find (#2523).
-- Marks a track whose file the scanner could no longer find.
--
-- NULL means present. A timestamp means the file was absent as of that scan,
-- and is the point from which "how long has this been gone" is measured — which

Some files were not shown because too many files have changed in this diff Show More