feat(tuning): scoring weights → DB-backed admin tuning lab

The recommendation scoring knobs move out of YAML (radio profile) and
out of the systemMixWeights hard-code (daily_mix profile) into
DB-backed settings with live effect (#1250) — the defaults-discovery
lab per decision #1247: the operator turns knobs to find good values,
which then get baked back into shipped defaults; end users and other
operators should never need the card.

- Migration 0040: recommendation_weight_profiles (radio / daily_mix,
  8 weight columns), taste_tuning singleton (engagement half-life +
  completion-curve points), recommendation_tuning_audit (one row per
  change with a {field, old, new} diff — the trend view's markers,
  #1251).
- internal/recsettings: boot reconcile seeds shipped defaults without
  clobbering tuned rows (coverart SettingsService pattern), validates
  patches (bounds, curve ordering), writes audit rows, and pushes
  daily_mix weights + taste config into package playlists. No-op
  patches write no audit row.
- playlists gains SetSystemMixWeights / SetTasteConfig swap points
  under a RWMutex — no signature threading through the producers; the
  scheduler's taste rebuild reads the pushed config.
- Radio reads its weight profile from the service per request; the 8
  weight fields leave config.RecommendationConfig (YAML keeps only
  RecentlyPlayedHours / RadioSize / RadioSizeMax).
- Admin API: GET/PATCH/reset under /api/admin/recommendation-tuning,
  echoing current + shipped values.
- Web: new admin Tuning tab — two weight profiles side by side, taste
  card, per-scope save (changed fields only) + reset, deviation dots
  against shipped defaults.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TsF3cNoKrqCYsU78cXC8U6

internal/api/admin_recommendation_tuning.go

@@ -0,0 +1,152 @@
+// Admin recommendation-tuning endpoints (#1250): the defaults-
+// discovery lab. GET returns current values + shipped defaults for
+// every scope; PATCH applies a partial update to one scope; reset
+// restores a scope to shipped defaults. Every change writes an audit
+// row (consumed by the metrics trend view, #1251).
+package api
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/apierror"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/recommendation"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/recsettings"
+)
+
+// weightsResp is one weight profile on the wire, keyed by the same
+// snake_case field names the PATCH body accepts.
+type weightsResp struct {
+	BaseWeight       float64 `json:"base_weight"`
+	LikeBoost        float64 `json:"like_boost"`
+	RecencyWeight    float64 `json:"recency_weight"`
+	SkipPenalty      float64 `json:"skip_penalty"`
+	JitterMagnitude  float64 `json:"jitter_magnitude"`
+	ContextWeight    float64 `json:"context_weight"`
+	SimilarityWeight float64 `json:"similarity_weight"`
+	TasteWeight      float64 `json:"taste_weight"`
+}
+
+func weightsRespFrom(w recommendation.ScoringWeights) weightsResp {
+	return weightsResp{
+		BaseWeight:       w.BaseWeight,
+		LikeBoost:        w.LikeBoost,
+		RecencyWeight:    w.RecencyWeight,
+		SkipPenalty:      w.SkipPenalty,
+		JitterMagnitude:  w.JitterMagnitude,
+		ContextWeight:    w.ContextWeight,
+		SimilarityWeight: w.SimilarityWeight,
+		TasteWeight:      w.TasteWeight,
+	}
+}
+
+type tasteTuningResp struct {
+	HalfLifeDays       float64 `json:"half_life_days"`
+	EngagementHardSkip float64 `json:"engagement_hard_skip"`
+	EngagementNeutral  float64 `json:"engagement_neutral"`
+	EngagementFull     float64 `json:"engagement_full"`
+}
+
+func tasteRespFrom(t recsettings.TasteTuning) tasteTuningResp {
+	return tasteTuningResp{
+		HalfLifeDays:       t.HalfLifeDays,
+		EngagementHardSkip: t.EngagementHardSkip,
+		EngagementNeutral:  t.EngagementNeutral,
+		EngagementFull:     t.EngagementFull,
+	}
+}
+
+// tuningSnapshot is both the GET response and the post-mutation echo:
+// current values alongside shipped defaults so the card can mark
+// which knobs deviate.
+type tuningSnapshot struct {
+	Profiles map[string]weightsResp `json:"profiles"`
+	Taste    tasteTuningResp        `json:"taste"`
+	Shipped  struct {
+		Profiles map[string]weightsResp `json:"profiles"`
+		Taste    tasteTuningResp        `json:"taste"`
+	} `json:"shipped"`
+}
+
+func (h *handlers) tuningSnapshot() tuningSnapshot {
+	var out tuningSnapshot
+	out.Profiles = map[string]weightsResp{
+		recsettings.ScopeRadio:    weightsRespFrom(h.recSettings.Weights(recsettings.ScopeRadio)),
+		recsettings.ScopeDailyMix: weightsRespFrom(h.recSettings.Weights(recsettings.ScopeDailyMix)),
+	}
+	out.Taste = tasteRespFrom(h.recSettings.Taste())
+	out.Shipped.Profiles = map[string]weightsResp{
+		recsettings.ScopeRadio:    weightsRespFrom(recsettings.ShippedRadioWeights()),
+		recsettings.ScopeDailyMix: weightsRespFrom(recsettings.ShippedDailyMixWeights()),
+	}
+	out.Shipped.Taste = tasteRespFrom(recsettings.ShippedTasteTuning())
+	return out
+}
+
+// handleGetRecommendationTuning implements GET /api/admin/recommendation-tuning.
+func (h *handlers) handleGetRecommendationTuning(w http.ResponseWriter, r *http.Request) {
+	writeJSON(w, http.StatusOK, h.tuningSnapshot())
+}
+
+// patchTuningReq carries the partial update: field name → new value,
+// using the same snake_case names the GET response emits.
+type patchTuningReq struct {
+	Values map[string]float64 `json:"values"`
+}
+
+// handlePatchRecommendationTuning implements
+// PATCH /api/admin/recommendation-tuning/{scope}.
+func (h *handlers) handlePatchRecommendationTuning(w http.ResponseWriter, r *http.Request) {
+	scope := chi.URLParam(r, "scope")
+	var body patchTuningReq
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		writeErr(w, apierror.BadRequest("bad_body", "invalid JSON"))
+		return
+	}
+	if len(body.Values) == 0 {
+		writeErr(w, apierror.BadRequest("bad_body", "values is empty"))
+		return
+	}
+
+	var err error
+	if scope == recsettings.ScopeTaste {
+		err = h.recSettings.UpdateTaste(r.Context(), body.Values)
+	} else {
+		err = h.recSettings.UpdateProfile(r.Context(), scope, body.Values)
+	}
+	if err != nil {
+		writeTuningErr(w, h, scope, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, h.tuningSnapshot())
+}
+
+// handleResetRecommendationTuning implements
+// POST /api/admin/recommendation-tuning/{scope}/reset.
+func (h *handlers) handleResetRecommendationTuning(w http.ResponseWriter, r *http.Request) {
+	scope := chi.URLParam(r, "scope")
+	if err := h.recSettings.Reset(r.Context(), scope); err != nil {
+		writeTuningErr(w, h, scope, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, h.tuningSnapshot())
+}
+
+// writeTuningErr maps recsettings validation errors to 400s and
+// everything else to a logged 500.
+func writeTuningErr(w http.ResponseWriter, h *handlers, scope string, err error) {
+	switch {
+	case errors.Is(err, recsettings.ErrUnknownScope):
+		writeErr(w, &apierror.Error{
+			Status: http.StatusNotFound, Code: "not_found", Message: "no such tuning scope",
+		})
+	case errors.Is(err, recsettings.ErrUnknownField), errors.Is(err, recsettings.ErrOutOfRange):
+		writeErr(w, apierror.BadRequest("invalid_tuning", err.Error()))
+	default:
+		h.logger.Error("admin: recommendation tuning", "scope", scope, "err", err)
+		writeErr(w, apierror.InternalMsg("tuning update failed", err))
+	}
+}

internal/api/admin_recommendation_tuning_test.go

@@ -0,0 +1,110 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/recsettings"
+)
+
+func newTuningRouter(h *handlers) chi.Router {
+	r := chi.NewRouter()
+	r.Get("/api/admin/recommendation-tuning", h.handleGetRecommendationTuning)
+	r.Patch("/api/admin/recommendation-tuning/{scope}", h.handlePatchRecommendationTuning)
+	r.Post("/api/admin/recommendation-tuning/{scope}/reset", h.handleResetRecommendationTuning)
+	return r
+}
+
+func decodeTuning(t *testing.T, rec *httptest.ResponseRecorder) tuningSnapshot {
+	t.Helper()
+	var snap tuningSnapshot
+	if err := json.Unmarshal(rec.Body.Bytes(), &snap); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	return snap
+}
+
+func TestRecommendationTuning_GetReturnsShippedDefaults(t *testing.T) {
+	h, _ := testHandlers(t)
+	req := httptest.NewRequest(http.MethodGet, "/api/admin/recommendation-tuning", nil)
+	rec := httptest.NewRecorder()
+	newTuningRouter(h).ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", rec.Code)
+	}
+	snap := decodeTuning(t, rec)
+	if snap.Profiles["radio"].TasteWeight != 1.0 || snap.Profiles["daily_mix"].TasteWeight != 1.5 {
+		t.Errorf("profiles = %+v, want shipped taste weights 1.0 / 1.5", snap.Profiles)
+	}
+	if snap.Taste.HalfLifeDays != 75 {
+		t.Errorf("taste half-life = %v, want shipped 75", snap.Taste.HalfLifeDays)
+	}
+	if snap.Shipped.Profiles["radio"] != snap.Profiles["radio"] {
+		t.Error("untouched values must equal shipped defaults")
+	}
+}
+
+func TestRecommendationTuning_PatchAndReset(t *testing.T) {
+	h, _ := testHandlers(t)
+	r := newTuningRouter(h)
+
+	req := httptest.NewRequest(http.MethodPatch, "/api/admin/recommendation-tuning/radio",
+		strings.NewReader(`{"values":{"taste_weight": 2.5}}`))
+	rec := httptest.NewRecorder()
+	r.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("patch status = %d, want 200 (%s)", rec.Code, rec.Body.String())
+	}
+	snap := decodeTuning(t, rec)
+	if snap.Profiles["radio"].TasteWeight != 2.5 {
+		t.Errorf("patched taste_weight = %v, want 2.5", snap.Profiles["radio"].TasteWeight)
+	}
+	// The change is live for the radio scoring path.
+	if got := h.recSettings.Weights(recsettings.ScopeRadio).TasteWeight; got != 2.5 {
+		t.Errorf("service taste_weight = %v, want 2.5 (live effect)", got)
+	}
+
+	req = httptest.NewRequest(http.MethodPost, "/api/admin/recommendation-tuning/radio/reset", nil)
+	rec = httptest.NewRecorder()
+	r.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("reset status = %d, want 200", rec.Code)
+	}
+	snap = decodeTuning(t, rec)
+	if snap.Profiles["radio"].TasteWeight != 1.0 {
+		t.Errorf("reset taste_weight = %v, want shipped 1.0", snap.Profiles["radio"].TasteWeight)
+	}
+}
+
+func TestRecommendationTuning_PatchErrors(t *testing.T) {
+	h, _ := testHandlers(t)
+	r := newTuningRouter(h)
+	cases := []struct {
+		name, path, body string
+		want             int
+	}{
+		{"unknown scope", "/api/admin/recommendation-tuning/banana",
+			`{"values":{"taste_weight":1}}`, http.StatusNotFound},
+		{"unknown field", "/api/admin/recommendation-tuning/radio",
+			`{"values":{"vibes":1}}`, http.StatusBadRequest},
+		{"out of range", "/api/admin/recommendation-tuning/taste",
+			`{"values":{"engagement_neutral":2}}`, http.StatusBadRequest},
+		{"empty values", "/api/admin/recommendation-tuning/radio",
+			`{"values":{}}`, http.StatusBadRequest},
+		{"bad json", "/api/admin/recommendation-tuning/radio",
+			`{`, http.StatusBadRequest},
+	}
+	for _, c := range cases {
+		req := httptest.NewRequest(http.MethodPatch, c.path, strings.NewReader(c.body))
+		rec := httptest.NewRecorder()
+		r.ServeHTTP(rec, req)
+		if rec.Code != c.want {
+			t.Errorf("%s: status = %d, want %d", c.name, rec.Code, c.want)
+		}
+	}
+}

internal/api/api.go

@@ -22,16 +22,18 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/mailer"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/playevents"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/playlists"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/recsettings"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/tracks"
 )
 
 // Mount attaches /api/* handlers to r. Public endpoints (login) are outside
 // RequireUser; everything else is gated by the middleware. The events writer
 // is shared with the Subsonic mount so /rest/scrobble feeds the same store.
-func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playevents.Writer, recCfg config.RecommendationConfig, lidarrCfg *lidarrconfig.Service, lidarrReqs *lidarrrequests.Service, lidarrQuar *lidarrquarantine.Service, tracksSvc *tracks.Service, playlistsSvc *playlists.Service, coverEnricher *coverart.Enricher, coverSettings *coverart.SettingsService, scanner *library.Scanner, scanCfg library.RunScanConfig, dataDir string, sender mailer.Sender, bus *eventbus.Bus, playlistScheduler *playlists.Scheduler, streamSecret []byte) {
+func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playevents.Writer, recCfg config.RecommendationConfig, recSettings *recsettings.Service, lidarrCfg *lidarrconfig.Service, lidarrReqs *lidarrrequests.Service, lidarrQuar *lidarrquarantine.Service, tracksSvc *tracks.Service, playlistsSvc *playlists.Service, coverEnricher *coverart.Enricher, coverSettings *coverart.SettingsService, scanner *library.Scanner, scanCfg library.RunScanConfig, dataDir string, sender mailer.Sender, bus *eventbus.Bus, playlistScheduler *playlists.Scheduler, streamSecret []byte) {
 	rng := rand.New(rand.NewSource(rand.Int63()))
 	h := &handlers{
 		pool: pool, logger: logger, events: events, recCfg: recCfg,
+		recSettings:       recSettings,
 		rng:               rng.Float64,
 		lidarrCfg:         lidarrCfg,
 		lidarrRequests:    lidarrReqs,
@@ -201,6 +203,12 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 				admin.Get("/smtp-config", h.handleGetSMTPConfig)
 				admin.Put("/smtp-config", h.handleUpdateSMTPConfig)
 				admin.Post("/smtp-config/test", h.handleTestSMTPConfig)
+
+				// Recommendation tuning lab (#1250): scoring-weight
+				// profiles + taste-build knobs, DB-backed, live effect.
+				admin.Get("/recommendation-tuning", h.handleGetRecommendationTuning)
+				admin.Patch("/recommendation-tuning/{scope}", h.handlePatchRecommendationTuning)
+				admin.Post("/recommendation-tuning/{scope}/reset", h.handleResetRecommendationTuning)
 			})
 
 			authed.Get("/playlists", h.handleListPlaylists)
@@ -223,6 +231,7 @@ type handlers struct {
 	logger            *slog.Logger
 	events            *playevents.Writer
 	recCfg            config.RecommendationConfig
+	recSettings       *recsettings.Service
 	rng               func() float64
 	lidarrCfg         *lidarrconfig.Service
 	lidarrRequests    *lidarrrequests.Service

internal/api/auth_test.go

@@ -29,6 +29,7 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/mailer"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/playevents"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/playlists"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/recsettings"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/tracks"
 )
 
@@ -56,11 +57,12 @@ func testHandlers(t *testing.T) (*handlers, *pgxpool.Pool) {
 	dbtest.ResetDB(t, pool)
 	w := playevents.NewWriter(pool, logger, 30*time.Minute, 0.5, 30000)
 	recCfg := config.RecommendationConfig{
-		BaseWeight: 1.0, LikeBoost: 2.0, RecencyWeight: 1.0,
-		SkipPenalty: 1.0, JitterMagnitude: 0.1,
-		ContextWeight: 2.0, SimilarityWeight: 2.0,
 		RecentlyPlayedHours: 1, RadioSize: 50, RadioSizeMax: 200,
 	}
+	recSettings, err := recsettings.New(context.Background(), pool, logger)
+	if err != nil {
+		t.Fatalf("recsettings: %v", err)
+	}
 	lidarrCfg := lidarrconfig.New(pool)
 	lidarrReqs := lidarrrequests.NewService(pool, lidarrCfg, nil, nil)
 	lidarrQuar := lidarrquarantine.NewService(pool, lidarrCfg, nil)
@@ -70,7 +72,7 @@ func testHandlers(t *testing.T) (*handlers, *pgxpool.Pool) {
 	dataDir := t.TempDir()
 	tracksSvc := tracks.NewService(pool, logger, nil, dataDir)
 	playlistsSvc := playlists.NewService(pool, logger, dataDir)
-	h := &handlers{pool: pool, logger: logger, events: w, recCfg: recCfg, rng: func() float64 { return 0.5 }, lidarrCfg: lidarrCfg, lidarrRequests: lidarrReqs, lidarrQuarantine: lidarrQuar, tracks: tracksSvc, playlists: playlistsSvc, dataDir: dataDir, scanner: nil, scanCfg: library.RunScanConfig{}, mailer: &mailer.FakeSender{}}
+	h := &handlers{pool: pool, logger: logger, events: w, recCfg: recCfg, recSettings: recSettings, rng: func() float64 { return 0.5 }, lidarrCfg: lidarrCfg, lidarrRequests: lidarrReqs, lidarrQuarantine: lidarrQuar, tracks: tracksSvc, playlists: playlistsSvc, dataDir: dataDir, scanner: nil, scanCfg: library.RunScanConfig{}, mailer: &mailer.FakeSender{}}
 	return h, pool
 }
 

internal/api/library_test.go

@@ -465,7 +465,7 @@ func TestRoutesRegisteredInMount(t *testing.T) {
 	r := chi.NewRouter()
 	w := playevents.NewWriter(h.pool, slog.New(slog.NewTextHandler(io.Discard, nil)),
 		30*time.Minute, 0.5, 30000)
-	Mount(r, h.pool, h.logger, w, config.RecommendationConfig{RadioSize: 50, RadioSizeMax: 200, RecentlyPlayedHours: 1}, h.lidarrCfg, h.lidarrRequests, h.lidarrQuarantine, h.tracks, h.playlists, h.coverart, h.coverSettings, h.scanner, h.scanCfg, h.dataDir, nil, eventbus.New(), nil, nil)
+	Mount(r, h.pool, h.logger, w, config.RecommendationConfig{RadioSize: 50, RadioSizeMax: 200, RecentlyPlayedHours: 1}, h.recSettings, h.lidarrCfg, h.lidarrRequests, h.lidarrQuarantine, h.tracks, h.playlists, h.coverart, h.coverSettings, h.scanner, h.scanCfg, h.dataDir, nil, eventbus.New(), nil, nil)
 
 	paths := []string{
 		"/api/artists",

internal/api/radio.go

@@ -15,6 +15,7 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/apierror"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/recommendation"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/recsettings"
 )
 
 // RadioResponse is the body of GET /api/radio.
@@ -100,16 +101,9 @@ func (h *handlers) handleRadio(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
-	weights := recommendation.ScoringWeights{
-		BaseWeight:       h.recCfg.BaseWeight,
-		LikeBoost:        h.recCfg.LikeBoost,
-		RecencyWeight:    h.recCfg.RecencyWeight,
-		SkipPenalty:      h.recCfg.SkipPenalty,
-		JitterMagnitude:  h.recCfg.JitterMagnitude,
-		ContextWeight:    h.recCfg.ContextWeight,
-		SimilarityWeight: h.recCfg.SimilarityWeight,
-		TasteWeight:      h.recCfg.TasteWeight,
-	}
+	// Scoring weights come from the DB-backed tuning lab (#1250) —
+	// read per request so an admin change takes effect live.
+	weights := h.recSettings.Weights(recsettings.ScopeRadio)
 	picks := recommendation.Shuffle(candidates, weights, time.Now().UTC(), h.rng, limit-1)
 
 	out := make([]TrackRef, 0, len(picks)+1)