feat(taste): mood taste facet — #1534

Milestone #160 Opt 2b (mood half of the era+mood option). A fourth taste
facet alongside artists + genre tags + eras: signed weights over canonical
mood buckets (melancholic / energetic / chill / …) derived from a track's
enriched folksonomy tags (#1490).

- internal/mood: shared vocabulary — Of(tags) maps folksonomy tags to
  canonical mood buckets (synonyms collapse). Imported by both the taste
  builder and the scorer so a track's mood is derived identically.
- Migration 0047: taste_profile_moods table + taste_tuning.mood_scale
  (DEFAULT 0.5).
- Build side (internal/taste): Config.MoodScale ([0,1] damper, mirrors
  EraScale); accumulate folds each play/like's mood buckets at
  base*MoodScale; persist atomic-replaces the mood rows.
- Scorer (internal/recommendation): TasteProfile gains a mood term
  (own tanh scale + additive 0.12 share, so it never weakens the existing
  signal when a track has no mood tags). Match now takes the candidate's
  mood buckets; loaded per candidate (ListTrackTagsForTracks → mood.Of) in
  the primary similarity loader only — the near-whole-library fallback
  pool passes nil (mood → 0) to avoid a full-library tag scan.
- Tuning lab: mood_scale threaded through recsettings + admin API + web
  card ("Mood weight" row) + Go/web tests.

Coverage is partial (grows with tag enrichment; richer once Last.fm is
keyed), so mood is a supplement — neutral for tracks with no mood tags.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

internal/db/dbq/models.go

@@ -562,6 +562,13 @@ type TasteProfileEra struct {
 	UpdatedAt pgtype.Timestamptz
 }
 
+type TasteProfileMood struct {
+	UserID    pgtype.UUID
+	Mood      string
+	Weight    float64
+	UpdatedAt pgtype.Timestamptz
+}
+
 type TasteProfileTag struct {
 	UserID    pgtype.UUID
 	Tag       string
@@ -578,6 +585,7 @@ type TasteTuning struct {
 	UpdatedAt          pgtype.Timestamptz
 	EnrichedTagScale   float64
 	EraScale           float64
+	MoodScale          float64
 }
 
 type Track struct {

internal/db/dbq/recommendation_tuning.sql.go

@@ -10,7 +10,7 @@ import (
 )
 
 const getTasteTuning = `-- name: GetTasteTuning :one
-SELECT singleton, half_life_days, engagement_hard_skip, engagement_neutral, engagement_full, updated_at, enriched_tag_scale, era_scale FROM taste_tuning WHERE singleton = true
+SELECT singleton, half_life_days, engagement_hard_skip, engagement_neutral, engagement_full, updated_at, enriched_tag_scale, era_scale, mood_scale FROM taste_tuning WHERE singleton = true
 `
 
 func (q *Queries) GetTasteTuning(ctx context.Context) (TasteTuning, error) {
@@ -25,6 +25,7 @@ func (q *Queries) GetTasteTuning(ctx context.Context) (TasteTuning, error) {
 		&i.UpdatedAt,
 		&i.EnrichedTagScale,
 		&i.EraScale,
+		&i.MoodScale,
 	)
 	return i, err
 }
@@ -125,9 +126,10 @@ UPDATE taste_tuning
        engagement_full      = $4,
        enriched_tag_scale   = $5,
        era_scale            = $6,
+       mood_scale           = $7,
        updated_at           = now()
  WHERE singleton = true
-RETURNING singleton, half_life_days, engagement_hard_skip, engagement_neutral, engagement_full, updated_at, enriched_tag_scale, era_scale
+RETURNING singleton, half_life_days, engagement_hard_skip, engagement_neutral, engagement_full, updated_at, enriched_tag_scale, era_scale, mood_scale
 `
 
 type UpdateTasteTuningParams struct {
@@ -137,6 +139,7 @@ type UpdateTasteTuningParams struct {
 	EngagementFull     float64
 	EnrichedTagScale   float64
 	EraScale           float64
+	MoodScale          float64
 }
 
 func (q *Queries) UpdateTasteTuning(ctx context.Context, arg UpdateTasteTuningParams) (TasteTuning, error) {
@@ -147,6 +150,7 @@ func (q *Queries) UpdateTasteTuning(ctx context.Context, arg UpdateTasteTuningPa
 		arg.EngagementFull,
 		arg.EnrichedTagScale,
 		arg.EraScale,
+		arg.MoodScale,
 	)
 	var i TasteTuning
 	err := row.Scan(
@@ -158,6 +162,7 @@ func (q *Queries) UpdateTasteTuning(ctx context.Context, arg UpdateTasteTuningPa
 		&i.UpdatedAt,
 		&i.EnrichedTagScale,
 		&i.EraScale,
+		&i.MoodScale,
 	)
 	return i, err
 }
@@ -224,8 +229,9 @@ func (q *Queries) UpdateWeightProfile(ctx context.Context, arg UpdateWeightProfi
 const upsertTasteTuningDefaults = `-- name: UpsertTasteTuningDefaults :exec
 INSERT INTO taste_tuning (
     singleton, half_life_days, engagement_hard_skip,
-    engagement_neutral, engagement_full, enriched_tag_scale, era_scale
-) VALUES (true, $1, $2, $3, $4, $5, $6)
+    engagement_neutral, engagement_full, enriched_tag_scale, era_scale,
+    mood_scale
+) VALUES (true, $1, $2, $3, $4, $5, $6, $7)
 ON CONFLICT (singleton) DO NOTHING
 `
 
@@ -236,6 +242,7 @@ type UpsertTasteTuningDefaultsParams struct {
 	EngagementFull     float64
 	EnrichedTagScale   float64
 	EraScale           float64
+	MoodScale          float64
 }
 
 func (q *Queries) UpsertTasteTuningDefaults(ctx context.Context, arg UpsertTasteTuningDefaultsParams) error {
@@ -246,6 +253,7 @@ func (q *Queries) UpsertTasteTuningDefaults(ctx context.Context, arg UpsertTaste
 		arg.EngagementFull,
 		arg.EnrichedTagScale,
 		arg.EraScale,
+		arg.MoodScale,
 	)
 	return err
 }

internal/db/dbq/taste_profile.sql.go

@@ -29,6 +29,15 @@ func (q *Queries) DeleteTasteProfileErasForUser(ctx context.Context, userID pgty
 	return err
 }
 
+const deleteTasteProfileMoodsForUser = `-- name: DeleteTasteProfileMoodsForUser :exec
+DELETE FROM taste_profile_moods WHERE user_id = $1
+`
+
+func (q *Queries) DeleteTasteProfileMoodsForUser(ctx context.Context, userID pgtype.UUID) error {
+	_, err := q.db.Exec(ctx, deleteTasteProfileMoodsForUser, userID)
+	return err
+}
+
 const deleteTasteProfileTagsForUser = `-- name: DeleteTasteProfileTagsForUser :exec
 DELETE FROM taste_profile_tags WHERE user_id = $1
 `
@@ -70,6 +79,22 @@ func (q *Queries) InsertTasteProfileEra(ctx context.Context, arg InsertTasteProf
 	return err
 }
 
+const insertTasteProfileMood = `-- name: InsertTasteProfileMood :exec
+INSERT INTO taste_profile_moods (user_id, mood, weight)
+VALUES ($1, $2, $3)
+`
+
+type InsertTasteProfileMoodParams struct {
+	UserID pgtype.UUID
+	Mood   string
+	Weight float64
+}
+
+func (q *Queries) InsertTasteProfileMood(ctx context.Context, arg InsertTasteProfileMoodParams) error {
+	_, err := q.db.Exec(ctx, insertTasteProfileMood, arg.UserID, arg.Mood, arg.Weight)
+	return err
+}
+
 const insertTasteProfileTag = `-- name: InsertTasteProfileTag :exec
 INSERT INTO taste_profile_tags (user_id, tag, weight)
 VALUES ($1, $2, $3)
@@ -304,6 +329,45 @@ func (q *Queries) ListTasteProfileErasForUser(ctx context.Context, arg ListTaste
 	return items, nil
 }
 
+const listTasteProfileMoodsForUser = `-- name: ListTasteProfileMoodsForUser :many
+SELECT mood, weight
+FROM taste_profile_moods
+WHERE user_id = $1
+ORDER BY weight DESC
+LIMIT $2
+`
+
+type ListTasteProfileMoodsForUserParams struct {
+	UserID pgtype.UUID
+	Limit  int32
+}
+
+type ListTasteProfileMoodsForUserRow struct {
+	Mood   string
+	Weight float64
+}
+
+// Top-weighted taste moods (#1534); 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 {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListTasteProfileMoodsForUserRow
+	for rows.Next() {
+		var i ListTasteProfileMoodsForUserRow
+		if err := rows.Scan(&i.Mood, &i.Weight); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
 const listTasteProfileTagsForUser = `-- name: ListTasteProfileTagsForUser :many
 SELECT tag, weight
 FROM taste_profile_tags

internal/db/dbq/track_tags.sql.go

@@ -110,6 +110,40 @@ func (q *Queries) ListPlayedTrackTagsForUser(ctx context.Context, arg ListPlayed
 	return items, nil
 }
 
+const listTrackTagsForTracks = `-- name: ListTrackTagsForTracks :many
+SELECT tt.track_id, tt.tag
+  FROM track_tags tt
+ WHERE tt.track_id = ANY($1::uuid[])
+`
+
+type ListTrackTagsForTracksRow struct {
+	TrackID pgtype.UUID
+	Tag     string
+}
+
+// Enriched tags for a set of candidate tracks (#1534), 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) {
+	rows, err := q.db.Query(ctx, listTrackTagsForTracks, dollar_1)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListTrackTagsForTracksRow
+	for rows.Next() {
+		var i ListTrackTagsForTracksRow
+		if err := rows.Scan(&i.TrackID, &i.Tag); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
 const listTracksMissingTags = `-- name: ListTracksMissingTags :many
 
 SELECT t.id, t.mbid, t.title, a.name AS artist_name, a.mbid AS artist_mbid

internal/db/migrations/0047_taste_profile_moods.down.sql

@@ -0,0 +1,2 @@
+ALTER TABLE taste_tuning DROP COLUMN IF EXISTS mood_scale;
+DROP TABLE IF EXISTS taste_profile_moods;

internal/db/migrations/0047_taste_profile_moods.up.sql

@@ -0,0 +1,25 @@
+-- 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).
+CREATE TABLE taste_profile_moods (
+    user_id    uuid             NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    mood       text             NOT NULL,
+    weight     double precision NOT NULL,
+    updated_at timestamptz      NOT NULL DEFAULT now(),
+    PRIMARY KEY (user_id, mood)
+);
+
+CREATE INDEX taste_profile_moods_user_weight_idx
+    ON taste_profile_moods (user_id, weight DESC);
+
+-- Mood-facet build knob, tunable in the lab (mirrors era_scale / enriched_tag_
+-- scale): scales how strongly a mood-tagged play imprints on the profile.
+-- DEFAULT 0.5 backfills the existing singleton and matches
+-- taste.DefaultConfig().MoodScale; 0 disables the mood facet entirely.
+ALTER TABLE taste_tuning
+    ADD COLUMN mood_scale double precision NOT NULL DEFAULT 0.5;

internal/db/queries/recommendation_tuning.sql

@@ -32,8 +32,9 @@ RETURNING *;
 -- name: UpsertTasteTuningDefaults :exec
 INSERT INTO taste_tuning (
     singleton, half_life_days, engagement_hard_skip,
-    engagement_neutral, engagement_full, enriched_tag_scale, era_scale
-) VALUES (true, $1, $2, $3, $4, $5, $6)
+    engagement_neutral, engagement_full, enriched_tag_scale, era_scale,
+    mood_scale
+) VALUES (true, $1, $2, $3, $4, $5, $6, $7)
 ON CONFLICT (singleton) DO NOTHING;
 
 -- name: GetTasteTuning :one
@@ -47,6 +48,7 @@ UPDATE taste_tuning
        engagement_full      = $4,
        enriched_tag_scale   = $5,
        era_scale            = $6,
+       mood_scale           = $7,
        updated_at           = now()
  WHERE singleton = true
 RETURNING *;

internal/db/queries/taste_profile.sql

@@ -85,3 +85,18 @@ FROM taste_profile_eras
 WHERE user_id = $1
 ORDER BY weight DESC
 LIMIT $2;
+
+-- name: DeleteTasteProfileMoodsForUser :exec
+DELETE FROM taste_profile_moods WHERE user_id = $1;
+
+-- name: InsertTasteProfileMood :exec
+INSERT INTO taste_profile_moods (user_id, mood, weight)
+VALUES ($1, $2, $3);
+
+-- name: ListTasteProfileMoodsForUser :many
+-- Top-weighted taste moods (#1534); consumed by the scorer's mood term.
+SELECT mood, weight
+FROM taste_profile_moods
+WHERE user_id = $1
+ORDER BY weight DESC
+LIMIT $2;

internal/db/queries/track_tags.sql

@@ -56,3 +56,11 @@ SELECT tt.track_id, tt.tag, tt.weight
   FROM track_tags tt
   JOIN general_likes gl ON gl.track_id = tt.track_id
  WHERE gl.user_id = $1;
+
+-- name: ListTrackTagsForTracks :many
+-- Enriched tags for a set of candidate tracks (#1534), 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.
+SELECT tt.track_id, tt.tag
+  FROM track_tags tt
+ WHERE tt.track_id = ANY($1::uuid[]);