feat: closed-set admin knobs are pickers, not free text

log_level, search_source, download_layout and the transcode hw/preset
were typed by hand, and every consumer carried its own guess at what a
typo meant. The value set is now a Literal in config.py: pydantic
rejects a bad env value at boot (any letter case accepted), sysconfig
refuses a bad override and derives the admin picker's options from the
same Literal, and the consumers read the value as-is.

The Configuration page renders a choice key as a segmented bar, or a
dropdown past six options, with translated option names. Its tabs now
follow the registry's order instead of a hand-kept copy that had
already dropped the explore group.

A single-choice FilterSelect now opens on the option in use: in the
browser it could land on the first row instead.

backend/app/config.py

@@ -1,6 +1,7 @@
 from pathlib import Path
+from typing import Literal, get_args, get_origin
 
-from pydantic import model_validator
+from pydantic import ValidationInfo, field_validator, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 # Shipped placeholder; production must override it. Used by the startup guard below.
@@ -20,6 +21,25 @@ def _version_from_file() -> str:
     return "dev"
 
 
+# Closed value sets. A setting typed with one of these is a CHOICE: pydantic rejects anything else at
+# boot, and sysconfig derives the admin picker's options from the same Literal — so the list lives in
+# exactly one place and a consumer never has to guess what a typo should fall back to.
+SearchSource = Literal["scrape", "api"]
+DownloadLayout = Literal["plex", "flat"]
+LogLevel = Literal["TRACE", "DEBUG", "INFO", "WARNING", "ERROR"]
+LogFormat = Literal["json", "text"]
+TranscodeHw = Literal["auto", "on", "off"]
+# libx264's presets, fastest first (`placebo` left out on purpose: no measurable gain for its cost).
+TranscodePreset = Literal[
+    "ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow"
+]
+
+
+def choices_of(annotation: object) -> tuple[str, ...]:
+    """The allowed values of a choice-typed setting, or () for any other type."""
+    return tuple(get_args(annotation)) if get_origin(annotation) is Literal else ()
+
+
 class Settings(BaseSettings):
     model_config = SettingsConfigDict(env_file=".env", extra="ignore")
 
@@ -85,7 +105,7 @@ class Settings(BaseSettings):
     search_daily_limit_per_user: int = 70
     # Source for live YouTube search: "scrape" (InnerTube, no API quota) or "api" (search.list,
     # 100 units/page). Scrape is the default; flip to "api" if scraping is blocked/breaks.
-    search_source: str = "scrape"
+    search_source: SearchSource = "scrape"
     # Recent-first backfill: how far back to fetch on the first pass per channel.
     backfill_recent_max_videos: int = 100
     backfill_recent_max_days: int = 365
@@ -221,7 +241,7 @@ class Settings(BaseSettings):
     audit_retention_days: int = 180
     audit_gc_minutes: int = 1440
     # On-disk layout: "plex" (Channel/Season YYYY/… [id].ext + .nfo/poster) or "flat".
-    download_layout: str = "plex"
+    download_layout: DownloadLayout = "plex"
     # Default SponsorBlock (skip sponsor segments) for new custom profiles.
     sponsorblock_default: bool = False
 
@@ -230,10 +250,10 @@ class Settings(BaseSettings):
     # startup and on change without a restart. This is what a process logs at before it can reach
     # the database — and the only knob the worker/runner children read, since they are short-lived.
     # TRACE (below DEBUG) is the "Teljes" diagnostics level; see app/logs.py.
-    log_level: str = "INFO"
+    log_level: LogLevel = "INFO"
     # "json" (one object per line — what Loki and the log_events sink ingest) or "text" (a readable
     # line for a local terminal). Redaction applies to both.
-    log_format: str = "json"
+    log_format: LogFormat = "json"
 
     # --- Plex integration (optional) ---
     # The Plex module plays the LOCAL physical media file directly (our own ffmpeg/direct-serve);
@@ -276,7 +296,7 @@ class Settings(BaseSettings):
     # Hardware-encoder policy: "auto" = VAAPI (h264_vaapi) when the iGPU render node is present AND the
     # source codec is hardware-decodable, else libx264 software; "on" = force VAAPI wherever the render
     # node exists (skip the decodability gate); "off" = always software. See plex/stream.py `_select_encode`.
-    plex_transcode_hw: str = "auto"
+    plex_transcode_hw: TranscodeHw = "auto"
     # Software-fallback libx264 tuning (IGNORED on the VAAPI path). `preset` trades CPU for size; `crf`
     # trades quality for size (lower = better + bigger). `max_height` caps the SOFTWARE transcode's output
     # height (0 = keep source) so a CPU re-encode of a tall source stays affordable — the GPU path always
@@ -286,7 +306,7 @@ class Settings(BaseSettings):
     # call, not a fix. Only affects files that go through remux/transcode — a direct-played file is
     # served untouched, but those are browser-native stereo anyway, not the 5.1 mixes this is for.
     plex_audio_loudnorm: bool = False
-    plex_transcode_preset: str = "veryfast"
+    plex_transcode_preset: TranscodePreset = "veryfast"
     plex_transcode_crf: int = 20
     plex_transcode_max_height: int = 1080
     # Where on-the-fly HLS remux segments are written (transient, reaped). Empty → a `.plex-hls`
@@ -335,6 +355,18 @@ class Settings(BaseSettings):
         https OAUTH_REDIRECT_URL as the signal for 'real deployment' vs local dev."""
         return self.oauth_redirect_url.lower().startswith("https://")
 
+    @field_validator("*", mode="before")
+    @classmethod
+    def _canonical_choice(cls, value: object, info: ValidationInfo) -> object:
+        """A choice setting accepts its value in any letter case (`LOG_LEVEL=debug`) and stores the
+        canonical spelling; an unknown value still fails the boot with pydantic's own message."""
+        field = cls.model_fields.get(info.field_name or "")
+        options = choices_of(field.annotation) if field else ()
+        if options and isinstance(value, str):
+            folded = value.strip().casefold()
+            return next((o for o in options if o.casefold() == folded), value)
+        return value
+
     @model_validator(mode="after")
     def _enforce_production_secrets(self) -> "Settings":
         """Fail fast rather than boot a public instance with the shipped placeholder

backend/app/logs.py

@@ -295,20 +295,20 @@ _THIRD_PARTY_LEVELS = {
 }
 
 
-def resolve_level(raw: str | None) -> int:
-    """Level name (case-insensitive) → number, falling back to INFO for an unknown value. A typo in
-    a config knob must not silence the app."""
-    if not raw:
-        return logging.INFO
-    value = logging.getLevelName(raw.strip().upper())
-    return value if isinstance(value, int) else logging.INFO
+def resolve_level(name: str) -> int:
+    """Level name → number. Both ways in (the `LOG_LEVEL` env and the `log_level` admin knob) are
+    already held to the `LogLevel` choices, so an unknown name here is a programming error."""
+    value = logging.getLevelName(name)
+    if not isinstance(value, int):
+        raise ValueError(f"unknown log level {name!r}")
+    return value
 
 
-def configure_logging(source: str, *, level: str | None = None) -> None:
+def configure_logging(source: str) -> None:
     """Configure logging for THIS process. Call once, first thing, in every entry point:
     `main.py` (api), `worker.main`, `downloads/runner.main`, `alembic/env.py`.
 
-    `source` names the process in every line. `level` overrides `LOG_LEVEL` (the bootstrap default);
+    `source` names the process in every line. The level starts at `LOG_LEVEL` (the bootstrap default);
     the runtime admin knob goes through `set_level()` instead, so changing it needs no restart.
 
     Our loggers deliberately keep `propagate=True` and own no handler: everything reaches the single
@@ -316,7 +316,7 @@ def configure_logging(source: str, *, level: str | None = None) -> None:
     is configured the moment it is created."""
     global _source
     _source = source
-    formatter = "json" if (settings.log_format or "json").lower() != "text" else "text"
+    formatter = settings.log_format
     logging.config.dictConfig(
         {
             "version": 1,
@@ -336,16 +336,16 @@ def configure_logging(source: str, *, level: str | None = None) -> None:
                     "filters": ["context"],
                 }
             },
-            "root": {"level": resolve_level(level or settings.log_level), "handlers": ["stdout"]},
+            "root": {"level": resolve_level(settings.log_level), "handlers": ["stdout"]},
             "loggers": {name: {"level": lvl} for name, lvl in _THIRD_PARTY_LEVELS.items()},
         }
     )
 
 
-def set_level(raw: str | None) -> None:
+def set_level(name: str) -> None:
     """Change the running process's level (the `log_level` admin knob). Third-party loggers keep
     their pinned levels, so turning on DEBUG shows OUR detail, not SQLAlchemy's."""
-    logging.getLogger().setLevel(resolve_level(raw))
+    logging.getLogger().setLevel(resolve_level(name))
 
 
 def current_level() -> str:

backend/app/plex/stream.py

@@ -404,7 +404,7 @@ def _select_encode(db: DbSession, item: PlexItem, transcode: bool, src: Path) ->
     source that has an OpenCL runtime, while a 10-bit SDR source drops to software."""
     if not transcode:
         return (False, False)
-    mode = (sysconfig.get_str(db, "plex_transcode_hw") or "auto").lower()
+    mode = sysconfig.get_str(db, "plex_transcode_hw")
     if mode == "off" or not _render_node_present():
         return (False, False)
     if mode == "on":
@@ -664,7 +664,7 @@ def start_session(
         # remux ignore preset/crf/max_height, and remux must not touch the DB for them).
         preset, crf, max_height = "veryfast", 20, 0
         if transcode and not hw:
-            preset = sysconfig.get_str(db, "plex_transcode_preset") or "veryfast"
+            preset = sysconfig.get_str(db, "plex_transcode_preset")
             crf = sysconfig.get_int(db, "plex_transcode_crf")
             max_height = sysconfig.get_int(db, "plex_transcode_max_height")
         # Nice the SOFTWARE transcode child (not the HW path, and not remux) so a CPU-bound re-encode

backend/app/routes/search.py

@@ -231,9 +231,7 @@ def search_youtube(
     limit = max(1, min(limit, 100))
 
     # Source: "scrape" (InnerTube, no API quota) or "api" (search.list, 100 units/page).
-    source = (sysconfig.get_str(db, "search_source") or "scrape").lower()
-    if source != "scrape":
-        source = "api"
+    source = sysconfig.get_str(db, "search_source")
 
     # Per-user daily cap applies to both sources (anti-abuse); with scrape it's the only guard
     # since the search itself spends no quota.

backend/app/sysconfig.py

@@ -14,7 +14,7 @@ from dataclasses import dataclass
 from sqlalchemy.orm import Session
 
 from app import security
-from app.config import settings
+from app.config import Settings, choices_of, settings
 from app.models import SystemConfig
 
 log = logging.getLogger("siftlode.config")
@@ -27,7 +27,7 @@ _decrypt_warned: set[str] = set()
 @dataclass(frozen=True)
 class ConfigSpec:
     key: str
-    type: str  # "int" | "str" | "bool"
+    type: str  # "int" | "str" | "bool" | "choice"
     group: str  # admin-UI grouping (logically related keys stay together)
     default_attr: str  # attribute on `settings` holding the env/config default
     secret: bool = False
@@ -35,16 +35,33 @@ class ConfigSpec:
     max: int | None = None
     allow_empty: bool = False  # str keys: a stored "" is an explicit empty value, not "unset"
 
+    @property
+    def choices(self) -> tuple[str, ...]:
+        """A choice key's allowed values, read from its setting's Literal type in config.py — the one
+        place the list is written. The admin page renders them as a picker."""
+        return choices_of(Settings.model_fields[self.default_attr].annotation)
+
 
 # Registry of DB-overridable keys. Add a key here + wire its read through get_*() to move it
-# off env into the admin UI; the admin page renders it automatically from this list.
+# off env into the admin UI; the admin page renders it automatically from this list. The ORDER is the
+# admin page's tab order (first appearance of each group), so keep a group's keys together.
 SPECS: tuple[ConfigSpec, ...] = (
+    # --- Access / registration ---
+    ConfigSpec("allow_registration", "bool", "access", "allow_registration"),
     # --- Email / SMTP (one logical group; the password is the only secret) ---
     ConfigSpec("smtp_host", "str", "email", "smtp_host"),
     ConfigSpec("smtp_port", "int", "email", "smtp_port", min=1, max=65535),
     ConfigSpec("smtp_user", "str", "email", "smtp_user", allow_empty=True),
     ConfigSpec("smtp_from", "str", "email", "smtp_from"),
     ConfigSpec("smtp_password", "str", "email", "smtp_password", secret=True),
+    # --- YouTube Data API key (secret; optional — public reads prefer it over OAuth) ---
+    ConfigSpec("youtube_api_key", "str", "youtube", "youtube_api_key", secret=True),
+    # Optional egress proxy for YouTube API calls (fixed-IP host for an IP-restricted key).
+    ConfigSpec("youtube_api_proxy", "str", "youtube", "youtube_api_proxy", allow_empty=True),
+    # --- Google OAuth client (Sign in with Google; both encrypted, env fallback). Set from the
+    #     install wizard / Configuration page so no restart is needed when the creds change. ---
+    ConfigSpec("google_client_id", "str", "google", "google_client_id", secret=True),
+    ConfigSpec("google_client_secret", "str", "google", "google_client_secret", secret=True),
     # --- Quota (shared YouTube Data API daily budget) ---
     ConfigSpec("quota_daily_budget", "int", "quota", "quota_daily_budget", min=1, max=1_000_000),
     ConfigSpec(
@@ -59,7 +76,7 @@ SPECS: tuple[ConfigSpec, ...] = (
         max=100_000,
     ),
     # Live-search source: "scrape" (InnerTube, zero API quota) or "api" (search.list, 100u/page).
-    ConfigSpec("search_source", "str", "quota", "search_source"),
+    ConfigSpec("search_source", "choice", "quota", "search_source"),
     # --- Backfill (recent-first first pass per channel) ---
     ConfigSpec(
         "backfill_recent_max_videos",
@@ -96,16 +113,6 @@ SPECS: tuple[ConfigSpec, ...] = (
     ConfigSpec("explore_grace_days", "int", "explore", "explore_grace_days", min=0, max=3_650),
     # Days an un-kept live-search result video is kept before the cleanup job removes it.
     ConfigSpec("search_grace_days", "int", "explore", "search_grace_days", min=0, max=3_650),
-    # --- YouTube Data API key (secret; optional — public reads prefer it over OAuth) ---
-    ConfigSpec("youtube_api_key", "str", "youtube", "youtube_api_key", secret=True),
-    # Optional egress proxy for YouTube API calls (fixed-IP host for an IP-restricted key).
-    ConfigSpec("youtube_api_proxy", "str", "youtube", "youtube_api_proxy", allow_empty=True),
-    # --- Google OAuth client (Sign in with Google; both encrypted, env fallback). Set from the
-    #     install wizard / Configuration page so no restart is needed when the creds change. ---
-    ConfigSpec("google_client_id", "str", "google", "google_client_id", secret=True),
-    ConfigSpec("google_client_secret", "str", "google", "google_client_secret", secret=True),
-    # --- Access / registration ---
-    ConfigSpec("allow_registration", "bool", "access", "allow_registration"),
     # --- Download center (yt-dlp) — per-user defaults + retention/GC + layout ---
     ConfigSpec("download_total_max_bytes", "int", "downloads", "download_total_max_bytes", min=0),
     ConfigSpec(
@@ -137,7 +144,7 @@ SPECS: tuple[ConfigSpec, ...] = (
     ConfigSpec(
         "download_gc_grace_days", "int", "downloads", "download_gc_grace_days", min=0, max=3_650
     ),
-    ConfigSpec("download_layout", "str", "downloads", "download_layout"),
+    ConfigSpec("download_layout", "choice", "downloads", "download_layout"),
     ConfigSpec(
         "download_worker_concurrency",
         "int",
@@ -151,10 +158,9 @@ SPECS: tuple[ConfigSpec, ...] = (
     # Days to keep admin audit-log rows before the audit_gc job prunes them (0 = keep forever).
     ConfigSpec("audit_retention_days", "int", "audit", "audit_retention_days", min=0, max=3650),
     # --- Diagnostics (E22) ---
-    # Runtime log level for the API process: TRACE | DEBUG | INFO | WARNING | ERROR. Free-text like
-    # search_source (an unknown value falls back to INFO in logs.resolve_level, so a typo can't
-    # silence the app). Applied without a restart — see routes/config.py and main.py's lifespan.
-    ConfigSpec("log_level", "str", "diagnostics", "log_level"),
+    # Runtime log level for the API process. Applied without a restart — see routes/config.py and
+    # main.py's lifespan.
+    ConfigSpec("log_level", "choice", "diagnostics", "log_level"),
     # --- Plex integration (optional; local-file playback + Plex metadata) ---
     ConfigSpec("plex_enabled", "bool", "plex", "plex_enabled"),
     ConfigSpec("plex_server_url", "str", "plex", "plex_server_url"),
@@ -164,10 +170,10 @@ SPECS: tuple[ConfigSpec, ...] = (
     ConfigSpec("plex_overlay_map", "str", "plex", "plex_overlay_map"),
     # (plex_sync_interval_min is tuned from the Scheduler dashboard, not here — it's a scheduler job.)
     ConfigSpec("plex_max_transcodes", "int", "plex", "plex_max_transcodes", min=0, max=16),
-    # Transcode re-encode tuning (E6 S1). hw = "auto"|"on"|"off" (free-text, like search_source); the
-    # libx264 knobs apply only to the software fallback. crf 0–51 (x264 range); max_height 0 = source.
-    ConfigSpec("plex_transcode_hw", "str", "plex", "plex_transcode_hw"),
-    ConfigSpec("plex_transcode_preset", "str", "plex", "plex_transcode_preset"),
+    # Transcode re-encode tuning (E6 S1). The libx264 knobs apply only to the software fallback.
+    # crf 0–51 (x264 range); max_height 0 = source.
+    ConfigSpec("plex_transcode_hw", "choice", "plex", "plex_transcode_hw"),
+    ConfigSpec("plex_transcode_preset", "choice", "plex", "plex_transcode_preset"),
     ConfigSpec("plex_transcode_crf", "int", "plex", "plex_transcode_crf", min=0, max=51),
     ConfigSpec(
         "plex_transcode_max_height", "int", "plex", "plex_transcode_max_height", min=0, max=4320
@@ -199,11 +205,24 @@ def _default(s: ConfigSpec):
     return getattr(settings, s.default_attr)
 
 
+def _choice(s: ConfigSpec, raw: object) -> str:
+    """The canonical spelling of `raw` among the key's choices (any letter case), or ValueError."""
+    folded = str(raw).strip().casefold()
+    for option in s.choices:
+        if option.casefold() == folded:
+            return option
+    raise ValueError(f"{s.key} must be one of: {', '.join(s.choices)}")
+
+
 def _coerce(s: ConfigSpec, raw: str):
     if s.type == "int":
         return int(raw)
     if s.type == "bool":
         return raw == "true"
+    if s.type == "choice":
+        # A stored value that is no longer a choice (the list shrank) reads as the default, like a
+        # non-numeric int override does — see get().
+        return _choice(s, raw)
     return raw
 
 
@@ -279,6 +298,8 @@ def set_value(db: Session, key: str, value) -> None:
         raw = str(v)
     elif s.type == "bool":
         raw = "true" if value else "false"
+    elif s.type == "choice":
+        raw = _choice(s, value)
     else:
         raw = "" if value is None else str(value)
 
@@ -321,6 +342,7 @@ def describe(db: Session) -> dict:
             "max": s.max,
             "is_set": is_set,  # an override row exists
             "allow_empty": s.allow_empty,  # if true, the UI stores "" rather than deleting the row
+            "choices": list(s.choices),  # the picker's options; [] for any other type
         }
         if s.secret:
             item["default_is_set"] = bool(_default(s))