bvandeusenandClaude Opus 5
799dab029a
The payoff slice. Until now a candidate's only claim on a slot was "some
artist you play is adjacent to it in a similarity graph" — a fact that says
nothing about whether the music sounds like anything you like. Now the
candidate's own folksonomy tags (cached by slice 5) are compared against
the user's taste-profile tags, so the deck ranks on taste and can say WHY.
The blend is MULTIPLICATIVE — score × (1 + weight × overlap) — and that
choice carries the whole safety argument:
- An untagged candidate has overlap 0, so its score is EXACTLY unchanged.
Tag coverage is permanently partial (#2376); it must cost a candidate
nothing, not sink it (rule #131).
- Nothing can leapfrog on tags alone. An additive term with a large
weight would let a near-zero-similarity artist outrank a strong match
for sharing one popular tag, which reads as noise.
- Weight 0 restores pure similarity order bit-for-bit, so the operator's
knob has a real off position.
overlap = Σ(shared) candWeight × normalizedTasteWeight ÷ Σ(all) candWeight.
Normalizing the taste side by the user's strongest tag makes the score
comparable across users (taste weights accumulate with listening, so a
heavy listener's raw numbers dwarf a new user's while meaning the same
thing). Dividing by the candidate's own mass makes it comparable across
candidates, so a densely-tagged artist can't win on tag count alone.
Applied to the whole over-fetched pool BEFORE selectSuggestions, so the
rotation and diversity rules operate on blended scores — boosting only the
twelve already chosen by similarity would leave the re-ranking undone.
A query failure is returned, NOT degraded past. Graceful degradation is
for expected absence (no taste profile, no cached tags) and both are
handled explicitly as empty inputs; swallowing a real error would hide a
broken DB behind a subtly worse ranking that nothing reports.
Migration 0051 adds a FOURTH tuning scope rather than columns on
taste_tuning, because snooze_days lives here too and a snooze must never
be read as taste signal (#2374) — filing it under 'taste' would put it one
careless join from the leak that design forbids. Expanding
recommendation_tuning_audit's CHECK is in the same migration per rule #36,
and a test asserts the audit row lands, which is what would catch its
absence.
snooze_days moves out of a Go constant onto the tuning card (rule #25),
closing the deferral from #2374.
Tag-overlap tests use deliberately SKEWED fixtures: an evenly-matching pool
cannot exercise a re-ranking, since every candidate gets the same
multiplier and the order is unchanged whether the blend works or not.
Admin UI + client attribution follow in this batch — rule #27.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
39 lines
2.0 KiB
SQL
39 lines
2.0 KiB
SQL
-- 0051_discover_tuning.up.sql — tunable knobs for the Discover request
|
|
-- surface (#2377, milestone #268 slice 6).
|
|
--
|
|
-- 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.
|
|
--
|
|
-- Per rule #25 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),
|
|
-- How strongly taste-tag overlap boosts a candidate's similarity score.
|
|
-- The blend is MULTIPLICATIVE: score * (1 + w * overlap), overlap in
|
|
-- [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_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.
|
|
snooze_days double precision NOT NULL,
|
|
updated_at timestamptz NOT NULL DEFAULT now()
|
|
);
|
|
|
|
INSERT INTO discover_tuning (singleton, tag_overlap_weight, snooze_days)
|
|
VALUES (true, 1.0, 90);
|
|
|
|
-- Rule #36: a new value for a CHECK-gated column needs the constraint
|
|
-- rewritten in the SAME change, or the first audit row written under the new
|
|
-- scope fails at runtime rather than at migrate time.
|
|
ALTER TABLE recommendation_tuning_audit
|
|
DROP CONSTRAINT recommendation_tuning_audit_scope_check;
|
|
ALTER TABLE recommendation_tuning_audit
|
|
ADD CONSTRAINT recommendation_tuning_audit_scope_check
|
|
CHECK (scope IN ('radio', 'daily_mix', 'taste', 'discover'));
|