From c5533b0ac5132e97a6a7cc82bd68de441c51189b Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 26 Jul 2026 04:17:08 +0200
Subject: [PATCH 01/18] refactor(api): shared serializer + ownership +
 write-scope helpers (R6 S1a)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Establish the R6 API-contract infra before the S1b payload:dict migration:
- iso(dt) in utils.py replaces the ~16 hand-rolled `x.isoformat() if x else None`
  serializer idioms across the routes.
- get_or_404 / owned_or_404 in routes/_common.py — one 404 + existence-leak policy;
  plex's _own_playlist_or_404 and saved_views' _own_view now delegate to it.
- require_write_scope dependency in auth.py collapses the inline has_write_scope→403
  checks (channels subscribe/unsubscribe, playlists push/push-plan) that had drifted
  into three different messages into one; the conditional delete_playlist guard stays
  inline (its message was already canonical).

No response-shape change (iso == isoformat for a present value). Gate: ruff clean,
pytest 163 green (+ test_utils for iso).
---
 backend/app/auth.py                 | 13 +++++++++
 backend/app/routes/_common.py       | 44 +++++++++++++++++++++++++++++
 backend/app/routes/admin.py         | 10 +++----
 backend/app/routes/audit.py         |  3 +-
 backend/app/routes/channels.py      | 32 ++++++++-------------
 backend/app/routes/downloads.py     |  7 +++--
 backend/app/routes/feed.py          |  5 ++--
 backend/app/routes/messages.py      |  5 ++--
 backend/app/routes/notifications.py |  3 +-
 backend/app/routes/playlists.py     | 19 ++++---------
 backend/app/routes/plex.py          | 13 +++------
 backend/app/routes/saved_views.py   |  6 ++--
 backend/app/utils.py                |  7 +++++
 backend/tests/test_utils.py         | 25 ++++++++++++++++
 14 files changed, 132 insertions(+), 60 deletions(-)
 create mode 100644 backend/app/routes/_common.py
 create mode 100644 backend/tests/test_utils.py

diff --git a/backend/app/auth.py b/backend/app/auth.py
index 024f62a..1723e25 100644
--- a/backend/app/auth.py
+++ b/backend/app/auth.py
@@ -1010,6 +1010,19 @@ def require_human(user: User = Depends(current_user)) -> User:
     return user
 
 
+def require_write_scope(user: User = Depends(require_human)) -> User:
+    """Dependency: require the YouTube write scope (subscribe/unsubscribe, playlist export/edit).
+    Single source of truth for the write gate — replaces the inline `if not has_write_scope(user)`
+    checks that had drifted into three different 403 messages across channels/playlists. Layers on
+    `require_human` because writing to YouTube needs a real, non-demo identity."""
+    if not has_write_scope(user):
+        raise HTTPException(
+            status_code=403,
+            detail="Enable YouTube editing in Settings first.",
+        )
+    return user
+
+
 def admin_user(user: User = Depends(current_user)) -> User:
     """Dependency: require the signed-in user to be an admin. Single source of truth for the
     admin gate — every admin route/action depends on this rather than re-checking the role."""
diff --git a/backend/app/routes/_common.py b/backend/app/routes/_common.py
new file mode 100644
index 0000000..9fa458a
--- /dev/null
+++ b/backend/app/routes/_common.py
@@ -0,0 +1,44 @@
+"""Route-layer shared helpers for the API contract (R6 S1a).
+
+Small, dependency-light guards that several route modules had hand-rolled with subtle
+drift. Keeping them here (imported by the route modules) means the "fetch a row or 404"
+and "fetch a row this user owns or 404" idioms have one definition, one status code, and
+one existence-leak policy.
+"""
+from typing import Any, TypeVar
+
+from fastapi import HTTPException
+from sqlalchemy.orm import Session
+
+from app.db import Base
+from app.models import User
+
+M = TypeVar("M", bound=Base)
+
+
+def get_or_404(db: Session, model: type[M], id_: Any, *, detail: str = "Not found") -> M:
+    """Fetch a row by primary key or raise 404. Replaces the `db.get(Model, id); if None: 404`
+    idiom repeated across routes."""
+    obj = db.get(model, id_)
+    if obj is None:
+        raise HTTPException(status_code=404, detail=detail)
+    return obj
+
+
+def owned_or_404(
+    db: Session,
+    model: type[M],
+    id_: Any,
+    user: User,
+    *,
+    owner_attr: str = "user_id",
+    detail: str = "Not found",
+) -> M:
+    """Fetch a row by primary key that `user` owns, or raise 404. A row owned by someone
+    else 404s (NOT 403) on purpose — a 403 would confirm the id exists to a stranger.
+    Generalizes the near-identical per-route ownership helpers (e.g. plex's
+    `_own_playlist_or_404`, the saved-views owner check)."""
+    obj = get_or_404(db, model, id_, detail=detail)
+    if getattr(obj, owner_attr) != user.id:
+        raise HTTPException(status_code=404, detail=detail)
+    return obj
diff --git a/backend/app/routes/admin.py b/backend/app/routes/admin.py
index c507c6c..c319756 100644
--- a/backend/app/routes/admin.py
+++ b/backend/app/routes/admin.py
@@ -27,7 +27,7 @@ from app.models import (
     Video,
     VideoState,
 )
-from app.utils import valid_email
+from app.utils import iso, valid_email
 
 router = APIRouter(prefix="/api/admin", tags=["admin"])
 
@@ -38,8 +38,8 @@ def _serialize(inv: Invite) -> dict:
         "email": inv.email,
         "status": inv.status,
         "note": inv.note,
-        "requested_at": inv.requested_at.isoformat() if inv.requested_at else None,
-        "decided_at": inv.decided_at.isoformat() if inv.decided_at else None,
+        "requested_at": iso(inv.requested_at),
+        "decided_at": iso(inv.decided_at),
         "decided_by": inv.decided_by,
     }
 
@@ -147,7 +147,7 @@ def _serialize_user(u: User) -> dict:
         "is_demo": u.is_demo,
         "has_password": u.password_hash is not None,
         "has_google": u.google_sub is not None,
-        "created_at": u.created_at.isoformat() if u.created_at else None,
+        "created_at": iso(u.created_at),
     }
 
 
@@ -280,7 +280,7 @@ def _serialize_demo(row: DemoWhitelist) -> dict:
         "email": row.email,
         "note": row.note,
         "added_by": row.added_by,
-        "created_at": row.created_at.isoformat() if row.created_at else None,
+        "created_at": iso(row.created_at),
     }
 
 
diff --git a/backend/app/routes/audit.py b/backend/app/routes/audit.py
index 206a32c..deffc69 100644
--- a/backend/app/routes/audit.py
+++ b/backend/app/routes/audit.py
@@ -10,6 +10,7 @@ from sqlalchemy.orm import Session
 from app import audit
 from app.audit import AuditAction
 from app.db import get_db
+from app.utils import iso
 from app.models import AuditLog, User
 from app.routes.admin import admin_user
 
@@ -23,7 +24,7 @@ MAX_ROWS = 2000
 def _serialize(row: AuditLog, actors: dict[int, str]) -> dict:
     return {
         "id": row.id,
-        "created_at": row.created_at.isoformat() if row.created_at else None,
+        "created_at": iso(row.created_at),
         # actor_id NULL = the scheduler/background did it (client shows "System"); a set id that
         # can't be resolved would mean a deleted user, but SET NULL makes that NULL — so present.
         "actor": actors.get(row.actor_id) if row.actor_id is not None else None,
diff --git a/backend/app/routes/channels.py b/backend/app/routes/channels.py
index 6b3c4da..0f02eb2 100644
--- a/backend/app/routes/channels.py
+++ b/backend/app/routes/channels.py
@@ -9,8 +9,9 @@ from sqlalchemy import func, select, update
 from sqlalchemy.orm import Session
 
 from app import quota, sysconfig
-from app.auth import current_user, has_write_scope, require_human
+from app.auth import current_user, require_human, require_write_scope
 from app.db import get_db
+from app.utils import iso
 from app.models import (
     LIVE_OR_UPCOMING,
     BlockedChannel,
@@ -67,7 +68,7 @@ def list_channels(
         ).all():
             agg[cid] = {
                 "stored": n,
-                "last_video_at": last_up.isoformat() if last_up else None,
+                "last_video_at": iso(last_up),
                 "total_duration_seconds": int(total_dur or 0),
                 "count_short": int(shorts),
                 "count_live": int(live),
@@ -232,7 +233,7 @@ def _channel_detail_dict(
         "subscriber_count": channel.subscriber_count,
         "video_count": channel.video_count,
         "total_view_count": channel.total_view_count,
-        "published_at": channel.published_at.isoformat() if channel.published_at else None,
+        "published_at": iso(channel.published_at),
         "external_links": channel.external_links or [],
         "country": channel.country,
         "default_language": channel.default_language,
@@ -454,19 +455,14 @@ def reset_backfill(
 @router.post("/{channel_id}/subscribe")
 def subscribe(
     channel_id: str,
-    user: User = Depends(current_user),
+    user: User = Depends(require_write_scope),
     db: Session = Depends(get_db),
 ) -> dict:
     """Subscribe to a channel discovered from the user's playlists. Gated behind the
-    optional write scope (YouTube subscriptions.insert). Creates the local subscription
-    with YouTube's returned resource id and enriches the channel's metadata if it's still
-    a stub, so the new row renders properly in the manager. It does NOT pull the channel's
-    videos — the scheduler picks those up on its next run, like any subscribed channel."""
-    if not has_write_scope(user):
-        raise HTTPException(
-            status_code=403,
-            detail="Enable playlist editing in Settings to subscribe on YouTube.",
-        )
+    optional write scope (YouTube subscriptions.insert) via require_write_scope. Creates the
+    local subscription with YouTube's returned resource id and enriches the channel's metadata
+    if it's still a stub, so the new row renders properly in the manager. It does NOT pull the
+    channel's videos — the scheduler picks those up on its next run, like any subscribed channel."""
     channel = db.get(Channel, channel_id)
     if channel is None:
         raise HTTPException(status_code=404, detail="Unknown channel")
@@ -524,16 +520,12 @@ def subscribe(
 @router.delete("/{channel_id}/subscription")
 def unsubscribe(
     channel_id: str,
-    user: User = Depends(current_user),
+    user: User = Depends(require_write_scope),
     db: Session = Depends(get_db),
 ) -> dict:
     """Unsubscribe from this channel on YouTube and drop the local subscription. Gated
-    behind the optional write scope; read-only users get a 403 and should Hide instead."""
-    if not has_write_scope(user):
-        raise HTTPException(
-            status_code=403,
-            detail="Enable playlist editing in Settings to unsubscribe on YouTube.",
-        )
+    behind the optional write scope (require_write_scope); read-only users get a 403 and
+    should Hide instead."""
     sub = _user_subscription(db, user, channel_id)
     if not sub.yt_subscription_id:
         raise HTTPException(
diff --git a/backend/app/routes/downloads.py b/backend/app/routes/downloads.py
index f3b4943..2d95a87 100644
--- a/backend/app/routes/downloads.py
+++ b/backend/app/routes/downloads.py
@@ -18,6 +18,7 @@ from app import sysconfig
 from app.auth import admin_user, require_human
 from app.config import settings
 from app.db import get_db
+from app.utils import iso
 from app.downloads import edit as editmod
 from app.downloads import links as linksmod
 from app.downloads import formats, quota, service, storage
@@ -80,7 +81,7 @@ def _serialize(job: DownloadJob, asset: MediaAsset | None) -> dict:
         "phase": job.phase,
         "error": job.error,
         "queue_pos": job.queue_pos,
-        "created_at": job.created_at.isoformat() if job.created_at else None,
+        "created_at": iso(job.created_at),
         "source_kind": job.source_kind,
         "source_ref": job.source_ref,
         "source_url": service.reference_url(job, asset),
@@ -106,7 +107,7 @@ def _serialize(job: DownloadJob, asset: MediaAsset | None) -> dict:
             "status": asset.status,
             "title": asset.title,
             "uploader": asset.uploader,
-            "upload_date": asset.upload_date.isoformat() if asset.upload_date else None,
+            "upload_date": iso(asset.upload_date),
             "duration_s": asset.duration_s,
             "size_bytes": asset.size_bytes,
             "width": asset.width,
@@ -114,7 +115,7 @@ def _serialize(job: DownloadJob, asset: MediaAsset | None) -> dict:
             "container": asset.container,
             "uploader_url": asset.uploader_url,
             "thumbnail_url": asset.thumbnail_url,
-            "expires_at": asset.expires_at.isoformat() if asset.expires_at else None,
+            "expires_at": iso(asset.expires_at),
         },
     }
 
diff --git a/backend/app/routes/feed.py b/backend/app/routes/feed.py
index 443ee19..71b0dd5 100644
--- a/backend/app/routes/feed.py
+++ b/backend/app/routes/feed.py
@@ -13,6 +13,7 @@ from sqlalchemy.orm.exc import StaleDataError
 from app import quota
 from app.auth import current_user
 from app.db import get_db
+from app.utils import iso
 from app.models import (
     LIVE_OR_UPCOMING,
     BlockedChannel,
@@ -97,7 +98,7 @@ def _serialize(row) -> dict:
         "channel_title": row.channel_title,
         "channel_thumbnail": row.channel_thumbnail,
         "channel_url": _channel_url(row.channel_id, row.channel_handle),
-        "published_at": row.published_at.isoformat() if row.published_at else None,
+        "published_at": iso(row.published_at),
         "thumbnail_url": row.thumbnail_url,
         "duration_seconds": row.duration_seconds,
         "view_count": row.view_count,
@@ -732,7 +733,7 @@ def get_video_detail(
             "in_db": True,
             "channel_id": v.channel_id,
             "channel_title": v.channel.title if v.channel else None,
-            "published_at": v.published_at.isoformat() if v.published_at else None,
+            "published_at": iso(v.published_at),
             "view_count": v.view_count,
             "duration_seconds": v.duration_seconds,
         }
diff --git a/backend/app/routes/messages.py b/backend/app/routes/messages.py
index 7ac772e..b953690 100644
--- a/backend/app/routes/messages.py
+++ b/backend/app/routes/messages.py
@@ -27,6 +27,7 @@ from app.ratelimit import RateLimiter
 from app.realtime import manager
 from app.security import verify_password
 from app.userscope import is_messageable_user, messageable_clauses
+from app.utils import iso
 
 router = APIRouter(prefix="/api/messages", tags=["messages"])
 
@@ -97,8 +98,8 @@ def _serialize_msg(m: Message) -> dict:
         "body": m.body,  # only set for system messages
         "ciphertext": m.ciphertext,
         "iv": m.iv,
-        "read_at": m.read_at.isoformat() if m.read_at else None,
-        "created_at": m.created_at.isoformat() if m.created_at else None,
+        "read_at": iso(m.read_at),
+        "created_at": iso(m.created_at),
     }
 
 
diff --git a/backend/app/routes/notifications.py b/backend/app/routes/notifications.py
index 224a7f7..2ee03ea 100644
--- a/backend/app/routes/notifications.py
+++ b/backend/app/routes/notifications.py
@@ -11,6 +11,7 @@ from sqlalchemy.orm import Session
 from app.auth import current_user
 from app.db import get_db
 from app.models import Notification, User
+from app.utils import iso
 from app.notifications import trim_read
 
 router = APIRouter(prefix="/api/me/notifications", tags=["notifications"])
@@ -25,7 +26,7 @@ def _serialize(n: Notification) -> dict:
         "data": n.data,
         "read": n.read,
         "dismissed": n.dismissed,
-        "created_at": n.created_at.isoformat() if n.created_at else None,
+        "created_at": iso(n.created_at),
     }
 
 
diff --git a/backend/app/routes/playlists.py b/backend/app/routes/playlists.py
index e37d625..4d8e02a 100644
--- a/backend/app/routes/playlists.py
+++ b/backend/app/routes/playlists.py
@@ -6,7 +6,7 @@ from sqlalchemy import func, select, and_
 from sqlalchemy.orm import Session, aliased
 
 from app import quota
-from app.auth import current_user, has_read_scope, has_write_scope
+from app.auth import current_user, has_read_scope, has_write_scope, require_write_scope
 from app.db import get_db
 from app.models import Channel, Playlist, PlaylistItem, User, Video, VideoState
 from app.routes.feed import _serialize, feed_columns
@@ -316,16 +316,13 @@ def _pushable(db: Session, user: User, playlist_id: int) -> Playlist:
 @router.get("/{playlist_id}/push-plan")
 def push_plan(
     playlist_id: int,
-    user: User = Depends(current_user),
+    user: User = Depends(require_write_scope),
     db: Session = Depends(get_db),
 ) -> dict:
     """Dry run: what 'Sync to YouTube' would do + the quota estimate, so the UI can show a
-    confirm. For a linked playlist this reads the live YouTube state (cheap, 1 unit/page)."""
+    confirm. For a linked playlist this reads the live YouTube state (cheap, 1 unit/page).
+    Write scope is required (require_write_scope) — syncing is a YouTube write."""
     pl = _pushable(db, user, playlist_id)
-    if not has_write_scope(user):
-        raise HTTPException(
-            status_code=403, detail="Enable YouTube editing in Settings first."
-        )
     try:
         with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PUSH):
             plan = plan_push(db, user, pl)
@@ -339,17 +336,13 @@ def push_plan(
 @router.post("/{playlist_id}/push")
 def push(
     playlist_id: int,
-    user: User = Depends(current_user),
+    user: User = Depends(require_write_scope),
     db: Session = Depends(get_db),
 ) -> dict:
     """Push a local playlist to YouTube (create it on first push, else reconcile to match
     local — local wins). Refuses if the estimated quota exceeds what's left today, so a
-    big playlist can't strand half-pushed."""
+    big playlist can't strand half-pushed. Write scope required (require_write_scope)."""
     pl = _pushable(db, user, playlist_id)
-    if not has_write_scope(user):
-        raise HTTPException(
-            status_code=403, detail="Enable YouTube editing in Settings first."
-        )
     try:
         with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PUSH):
             # Read the live playlist ONCE (linked playlists only) and share it with both the
diff --git a/backend/app/routes/plex.py b/backend/app/routes/plex.py
index 2f82edf..97cc4f4 100644
--- a/backend/app/routes/plex.py
+++ b/backend/app/routes/plex.py
@@ -41,6 +41,8 @@ from app.models import (
     PlexState,
     User,
 )
+from app.routes._common import owned_or_404
+from app.utils import iso
 from app.plex import paths as plex_paths
 from app.plex import people as plex_people
 from app.plex import stream as plex_stream
@@ -141,11 +143,7 @@ def _link_dict(link: PlexLink | None) -> dict:
         "sync_enabled": bool(link and link.sync_enabled),
         "uses_admin": bool(link and link.uses_admin),
         "initial_import_done": bool(link and link.initial_import_done),
-        "last_watch_sync_at": (
-            link.last_watch_sync_at.isoformat()
-            if link and link.last_watch_sync_at
-            else None
-        ),
+        "last_watch_sync_at": iso(link.last_watch_sync_at) if link else None,
     }
 
 
@@ -912,10 +910,7 @@ def collection_set_editable(
 
 # --- Playlists (Siftlode-native, per-user, ordered — no Plex account needed; Plex sync is a later phase).
 def _own_playlist_or_404(db: Session, pid: int, user: User) -> PlexPlaylist:
-    pl = db.query(PlexPlaylist).filter_by(id=pid, user_id=user.id).first()
-    if pl is None:
-        raise HTTPException(status_code=404, detail="Playlist not found")
-    return pl
+    return owned_or_404(db, PlexPlaylist, pid, user, detail="Playlist not found")
 
 
 def _playlist_card(pl: PlexPlaylist, count: int, thumb_rk: str | None) -> dict:
diff --git a/backend/app/routes/saved_views.py b/backend/app/routes/saved_views.py
index dd8a41e..7a2f9fe 100644
--- a/backend/app/routes/saved_views.py
+++ b/backend/app/routes/saved_views.py
@@ -6,6 +6,7 @@ from sqlalchemy.orm import Session
 from app.auth import require_human
 from app.db import get_db
 from app.models import SavedView, User
+from app.routes._common import owned_or_404
 
 # Saved "smart views": per-user named snapshots of the feed's FeedFilters. Gated behind
 # require_human so the shared demo account can't pollute a communal list (mirrors how other
@@ -71,10 +72,7 @@ def create_view(
 
 
 def _own_view(db: Session, user: User, view_id: int) -> SavedView:
-    view = db.get(SavedView, view_id)
-    if view is None or view.user_id != user.id:
-        raise HTTPException(status_code=404, detail="Unknown view")
-    return view
+    return owned_or_404(db, SavedView, view_id, user, detail="Unknown view")
 
 
 @router.patch("/{view_id}")
diff --git a/backend/app/utils.py b/backend/app/utils.py
index 70feb39..866e6e0 100644
--- a/backend/app/utils.py
+++ b/backend/app/utils.py
@@ -2,6 +2,13 @@
 import re
 from datetime import datetime, timezone
 
+
+def iso(dt: datetime | None) -> str | None:
+    """Serialize a datetime for a JSON response: ISO-8601, or None when the column is NULL.
+    Single source of truth for the `x.isoformat() if x else None` idiom the routes had
+    hand-rolled ~17 times — so a future tz/format tweak lands in one place."""
+    return dt.isoformat() if dt is not None else None
+
 # Single source of truth for "looks like an email" — used by every endpoint that accepts an
 # address (auth register/reset/demo, admin invites + demo whitelist, the setup wizard). Keep
 # the strictness in one place so routes don't drift between this and a looser "@"-in check.
diff --git a/backend/tests/test_utils.py b/backend/tests/test_utils.py
new file mode 100644
index 0000000..9c6f5d3
--- /dev/null
+++ b/backend/tests/test_utils.py
@@ -0,0 +1,25 @@
+"""iso(): the single datetime→JSON serializer the routes share (R6 S1a)."""
+from datetime import datetime, timezone
+
+from app.utils import iso
+
+
+def test_none_maps_to_none():
+    assert iso(None) is None
+
+
+def test_aware_datetime_keeps_offset():
+    dt = datetime(2026, 7, 26, 12, 30, 0, tzinfo=timezone.utc)
+    assert iso(dt) == "2026-07-26T12:30:00+00:00"
+
+
+def test_naive_datetime_serializes_without_offset():
+    dt = datetime(2026, 7, 26, 12, 30, 0)
+    assert iso(dt) == "2026-07-26T12:30:00"
+
+
+def test_matches_datetime_isoformat_contract():
+    # iso is exactly `dt.isoformat()` for a present value — guards the routes that used to
+    # hand-roll `x.isoformat() if x else None`.
+    dt = datetime(2020, 1, 2, 3, 4, 5, 678901, tzinfo=timezone.utc)
+    assert iso(dt) == dt.isoformat()

From cf8bbad8a17862c96104b40b4221d4dced973059 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 26 Jul 2026 04:25:40 +0200
Subject: [PATCH 02/18] =?UTF-8?q?refactor(api):=20code-review=20fixes=20?=
 =?UTF-8?q?=E2=80=94=20widen=20iso()=20to=20date,=20fix=20import=20order?=
 =?UTF-8?q?=20(R6=20S1a)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

/code-review high round 1 (5 findings):
- iso(dt) now typed `date | None` — MediaAsset.upload_date is a plain `date`, not a
  datetime; the helper's signature was too narrow for the type-contract epic. +test.
- restore alphabetical app.* import order in audit.py and plex.py (the new iso/_common
  imports had been dropped in mid-block).
The other 3 findings are deliberate design choices, left as-is for UAT: push/push-plan
now gate write-scope before the 404 (dependency ordering); the unified 403 message; and
owned_or_404's owner_attr kept for S1b's DownloadShare.to_user_id-style owners.

Gate: ruff clean, pytest 164 green.
---
 backend/app/routes/audit.py |  2 +-
 backend/app/routes/plex.py  |  4 ++--
 backend/app/utils.py        | 11 ++++++-----
 backend/tests/test_utils.py |  9 +++++++--
 4 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/backend/app/routes/audit.py b/backend/app/routes/audit.py
index deffc69..9e7a4ef 100644
--- a/backend/app/routes/audit.py
+++ b/backend/app/routes/audit.py
@@ -10,9 +10,9 @@ from sqlalchemy.orm import Session
 from app import audit
 from app.audit import AuditAction
 from app.db import get_db
-from app.utils import iso
 from app.models import AuditLog, User
 from app.routes.admin import admin_user
+from app.utils import iso
 
 router = APIRouter(prefix="/api/admin/audit", tags=["admin"])
 
diff --git a/backend/app/routes/plex.py b/backend/app/routes/plex.py
index 97cc4f4..ce0549f 100644
--- a/backend/app/routes/plex.py
+++ b/backend/app/routes/plex.py
@@ -41,16 +41,16 @@ from app.models import (
     PlexState,
     User,
 )
-from app.routes._common import owned_or_404
-from app.utils import iso
 from app.plex import paths as plex_paths
 from app.plex import people as plex_people
 from app.plex import stream as plex_stream
 from app.plex import sync as plex_sync
 from app.plex import watch_sync as plex_watch
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
+from app.routes._common import owned_or_404
 from app.routes.admin import admin_user
 from app.routes.feed import _to_tsquery_str
+from app.utils import iso
 
 log = logging.getLogger("siftlode.plex")
 
diff --git a/backend/app/utils.py b/backend/app/utils.py
index 866e6e0..d266187 100644
--- a/backend/app/utils.py
+++ b/backend/app/utils.py
@@ -1,12 +1,13 @@
 """Small cross-cutting helpers shared across modules (kept dependency-light on purpose)."""
 import re
-from datetime import datetime, timezone
+from datetime import date, datetime, timezone
 
 
-def iso(dt: datetime | None) -> str | None:
-    """Serialize a datetime for a JSON response: ISO-8601, or None when the column is NULL.
-    Single source of truth for the `x.isoformat() if x else None` idiom the routes had
-    hand-rolled ~17 times — so a future tz/format tweak lands in one place."""
+def iso(dt: date | None) -> str | None:
+    """Serialize a date/datetime for a JSON response: ISO-8601, or None when the column is
+    NULL. Single source of truth for the `x.isoformat() if x else None` idiom the routes had
+    hand-rolled ~17 times — so a future tz/format tweak lands in one place. Accepts `date`
+    too (datetime is a subclass) — e.g. MediaAsset.upload_date is a plain `date`."""
     return dt.isoformat() if dt is not None else None
 
 # Single source of truth for "looks like an email" — used by every endpoint that accepts an
diff --git a/backend/tests/test_utils.py b/backend/tests/test_utils.py
index 9c6f5d3..3e93b7d 100644
--- a/backend/tests/test_utils.py
+++ b/backend/tests/test_utils.py
@@ -1,5 +1,5 @@
-"""iso(): the single datetime→JSON serializer the routes share (R6 S1a)."""
-from datetime import datetime, timezone
+"""iso(): the single date/datetime→JSON serializer the routes share (R6 S1a)."""
+from datetime import date, datetime, timezone
 
 from app.utils import iso
 
@@ -8,6 +8,11 @@ def test_none_maps_to_none():
     assert iso(None) is None
 
 
+def test_plain_date_serializes_as_iso_date():
+    # MediaAsset.upload_date is a `date`, not a datetime — the contract must accept it.
+    assert iso(date(2026, 7, 26)) == "2026-07-26"
+
+
 def test_aware_datetime_keeps_offset():
     dt = datetime(2026, 7, 26, 12, 30, 0, tzinfo=timezone.utc)
     assert iso(dt) == "2026-07-26T12:30:00+00:00"

From 9fe050279ec219d72ad64c1efe534c2de1750a5d Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 26 Jul 2026 04:44:22 +0200
Subject: [PATCH 03/18] style(api): complete the S1a import-order fix (R6 S1a
 follow-up)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round-1 review finding #4 named only audit.py/plex.py, but the same misplaced
`from app.utils import iso` sat in channels/downloads/feed/notifications too — the
round missed them (ruff enforces no import order here, so the gate was silent).
Move them to alphabetical position for consistency. No behaviour change.
---
 backend/app/routes/channels.py      | 2 +-
 backend/app/routes/downloads.py     | 2 +-
 backend/app/routes/feed.py          | 2 +-
 backend/app/routes/notifications.py | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/backend/app/routes/channels.py b/backend/app/routes/channels.py
index 0f02eb2..32287ac 100644
--- a/backend/app/routes/channels.py
+++ b/backend/app/routes/channels.py
@@ -11,7 +11,6 @@ from sqlalchemy.orm import Session
 from app import quota, sysconfig
 from app.auth import current_user, require_human, require_write_scope
 from app.db import get_db
-from app.utils import iso
 from app.models import (
     LIVE_OR_UPCOMING,
     BlockedChannel,
@@ -29,6 +28,7 @@ from app.routes.admin import admin_user
 from app.sync.explore import explore_ingest_page
 from app.sync.runner import run_recent_backfill
 from app.sync.subscriptions import apply_channel_details
+from app.utils import iso
 from app.youtube.client import YouTubeClient, YouTubeError
 
 router = APIRouter(prefix="/api/channels", tags=["channels"])
diff --git a/backend/app/routes/downloads.py b/backend/app/routes/downloads.py
index 2d95a87..10c45c1 100644
--- a/backend/app/routes/downloads.py
+++ b/backend/app/routes/downloads.py
@@ -18,7 +18,6 @@ from app import sysconfig
 from app.auth import admin_user, require_human
 from app.config import settings
 from app.db import get_db
-from app.utils import iso
 from app.downloads import edit as editmod
 from app.downloads import links as linksmod
 from app.downloads import formats, quota, service, storage
@@ -33,6 +32,7 @@ from app.models import (
 )
 from app.security import hash_password
 from app.userscope import is_messageable_user, messageable_clauses
+from app.utils import iso
 
 router = APIRouter(prefix="/api/downloads", tags=["downloads"])
 admin_router = APIRouter(prefix="/api/admin/downloads", tags=["admin-downloads"])
diff --git a/backend/app/routes/feed.py b/backend/app/routes/feed.py
index 71b0dd5..8bfcc5f 100644
--- a/backend/app/routes/feed.py
+++ b/backend/app/routes/feed.py
@@ -13,7 +13,6 @@ from sqlalchemy.orm.exc import StaleDataError
 from app import quota
 from app.auth import current_user
 from app.db import get_db
-from app.utils import iso
 from app.models import (
     LIVE_OR_UPCOMING,
     BlockedChannel,
@@ -30,6 +29,7 @@ from app.models import (
     VideoState,
 )
 from app.sync.videos import parse_iso8601_duration
+from app.utils import iso
 from app.youtube.client import YouTubeClient, YouTubeError
 
 router = APIRouter(prefix="/api", tags=["feed"])
diff --git a/backend/app/routes/notifications.py b/backend/app/routes/notifications.py
index 2ee03ea..132e478 100644
--- a/backend/app/routes/notifications.py
+++ b/backend/app/routes/notifications.py
@@ -11,8 +11,8 @@ from sqlalchemy.orm import Session
 from app.auth import current_user
 from app.db import get_db
 from app.models import Notification, User
-from app.utils import iso
 from app.notifications import trim_read
+from app.utils import iso
 
 router = APIRouter(prefix="/api/me/notifications", tags=["notifications"])
 

From d982e8b9ae56b599e8d031baabd8b278bcd05ec0 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 26 Jul 2026 04:46:40 +0200
Subject: [PATCH 04/18] refactor(api): Pydantic request models for channels
 routes (R6 S1b)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

update_channel: payload:dict → ChannelUpdateIn (priority/hidden/deep_requested,
all optional for PATCH semantics). Kills the `int(payload["priority"])` 500 the
prod report hit — a non-numeric/garbage value now returns 422, not 500.
attach_tag: payload:dict → AttachTagIn(tag_id:int) — a non-int tag_id was a 500
in `db.get(Tag, ...)`; the personal-tag ownership check reuses owned_or_404.
---
 backend/app/routes/channels.py | 45 ++++++++++++++++++++++------------
 1 file changed, 29 insertions(+), 16 deletions(-)

diff --git a/backend/app/routes/channels.py b/backend/app/routes/channels.py
index 32287ac..dd04589 100644
--- a/backend/app/routes/channels.py
+++ b/backend/app/routes/channels.py
@@ -5,6 +5,7 @@ import logging
 from datetime import datetime, timezone
 
 from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
 from sqlalchemy import func, select, update
 from sqlalchemy.orm import Session
 
@@ -24,6 +25,7 @@ from app.models import (
     User,
     Video,
 )
+from app.routes._common import owned_or_404
 from app.routes.admin import admin_user
 from app.sync.explore import explore_ingest_page
 from app.sync.runner import run_recent_backfill
@@ -378,28 +380,37 @@ def _is_blocked(db: Session, user: User, channel_id: str) -> bool:
     )
 
 
+class ChannelUpdateIn(BaseModel):
+    # PATCH semantics: a field left unset (None) is untouched. Every field is optional so the
+    # UI can send just the one control it changed. int/bool coercion + rejection of garbage
+    # (a non-numeric priority, a non-bool flag) is now Pydantic's job → 422, not a 500.
+    priority: int | None = None
+    hidden: bool | None = None
+    deep_requested: bool | None = None
+
+
 @router.patch("/{channel_id}")
 def update_channel(
     channel_id: str,
-    payload: dict,
+    body: ChannelUpdateIn,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
     sub = _user_subscription(db, user, channel_id)
     channel = db.get(Channel, channel_id)
     deep_turned_on = False
-    if "priority" in payload:
-        sub.priority = int(payload["priority"])
-    if "hidden" in payload:
-        sub.hidden = bool(payload["hidden"])
+    if body.priority is not None:
+        sub.priority = body.priority
+    if body.hidden is not None:
+        sub.hidden = body.hidden
     # The demo account is SHARED, so it must not persist deep_requested (a quota-relevant flag) onto
     # the shared subscription — skip the write entirely for demo, which also keeps deep_turned_on
     # False so the immediate backfill below can never fire for it.
-    if "deep_requested" in payload and not user.is_demo:
+    if body.deep_requested is not None and not user.is_demo:
         # Opt this channel into (or out of) full-history backfill. The deep scheduler
         # picks the flag up on its next run; turning it off won't undo already-fetched
         # videos, it just stops further deep paging if nobody else still wants it.
-        want = bool(payload["deep_requested"])
+        want = body.deep_requested
         deep_turned_on = want and not sub.deep_requested
         sub.deep_requested = want
     db.commit()
@@ -601,23 +612,25 @@ def unblock_channel(
     return {"unblocked": channel_id}
 
 
+class AttachTagIn(BaseModel):
+    tag_id: int
+
+
 @router.post("/{channel_id}/tags")
 def attach_tag(
     channel_id: str,
-    payload: dict,
+    body: AttachTagIn,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
     _user_subscription(db, user, channel_id)
-    tag_id = payload.get("tag_id")
-    tag = db.get(Tag, tag_id) if tag_id is not None else None
-    # Only the user's own tags may be attached as personal links.
-    if tag is None or tag.user_id != user.id:
-        raise HTTPException(status_code=404, detail="Unknown tag")
+    # Only the user's own tags may be attached as personal links (owned_or_404 → 404 if the tag
+    # is missing OR belongs to someone else, without leaking which).
+    owned_or_404(db, Tag, body.tag_id, user, detail="Unknown tag")
     exists = db.execute(
         select(ChannelTag).where(
             ChannelTag.channel_id == channel_id,
-            ChannelTag.tag_id == tag_id,
+            ChannelTag.tag_id == body.tag_id,
             ChannelTag.user_id == user.id,
         )
     ).scalar_one_or_none()
@@ -625,13 +638,13 @@ def attach_tag(
         db.add(
             ChannelTag(
                 channel_id=channel_id,
-                tag_id=tag_id,
+                tag_id=body.tag_id,
                 user_id=user.id,
                 source="user",
             )
         )
         db.commit()
-    return {"channel_id": channel_id, "tag_id": tag_id}
+    return {"channel_id": channel_id, "tag_id": body.tag_id}
 
 
 @router.delete("/{channel_id}/tags/{tag_id}")

From a622470a28bf35d905dad1f68edbe540bc1f1607 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 26 Jul 2026 04:51:25 +0200
Subject: [PATCH 05/18] refactor(api): Pydantic request models for small route
 modules (R6 S1b)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

payload:dict → typed request models across the single/double-endpoint modules:
- tags: TagCreateIn / TagUpdateIn (color:null clears → reads model_fields_set);
  _own_tag now delegates to owned_or_404.
- config: ConfigSetIn(value:Any) — keeps the "Missing 'value'" 400 via model_fields_set.
- me: SwitchAccountIn(user_id:int).
- scheduler: JobIntervalIn / MaintenanceSettingsIn — the manual int()+400 becomes a
  clean 422 on a non-number; the range checks stay 400.
- search: ClearSearchIn(video_ids:list[str]).
- public: WatchUnlockIn(password:str).

Gate: ruff clean, pytest 164 green.
---
 backend/app/routes/config.py    | 15 ++++++++---
 backend/app/routes/me.py        |  9 +++++--
 backend/app/routes/public.py    |  9 +++++--
 backend/app/routes/scheduler.py | 23 +++++++++--------
 backend/app/routes/search.py    |  9 +++++--
 backend/app/routes/tags.py      | 44 ++++++++++++++++++++++-----------
 6 files changed, 75 insertions(+), 34 deletions(-)

diff --git a/backend/app/routes/config.py b/backend/app/routes/config.py
index 9e90a10..9513162 100644
--- a/backend/app/routes/config.py
+++ b/backend/app/routes/config.py
@@ -1,8 +1,10 @@
 """Admin Configuration page API: read/edit the DB-overridable operational settings defined in
 app.sysconfig. Secret values (e.g. SMTP password) are write-only — never returned."""
 import re
+from typing import Any
 
 from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
 from sqlalchemy.orm import Session
 
 from app import audit
@@ -30,17 +32,24 @@ def get_config(_: User = Depends(admin_user), db: Session = Depends(get_db)) ->
     return sysconfig.describe(db)
 
 
+class ConfigSetIn(BaseModel):
+    # A config value is arbitrarily typed (str/int/bool/…), validated downstream by
+    # sysconfig.set_value. `value` defaults to a sentinel so a MISSING value stays a 400
+    # ("Missing 'value'") while an explicit `null` is a real, settable value.
+    value: Any = None
+
+
 @router.patch("/{key}")
 def set_config(
     key: str,
-    payload: dict,
+    body: ConfigSetIn,
     admin: User = Depends(admin_user),
     db: Session = Depends(get_db),
 ) -> dict:
     s = sysconfig.spec(key)
     if s is None:
         raise HTTPException(status_code=404, detail="Unknown config key")
-    if "value" not in payload:
+    if "value" not in body.model_fields_set:
         raise HTTPException(status_code=400, detail="Missing 'value'")
     if s.secret and not sysconfig.secrets_manageable():
         raise HTTPException(
@@ -49,7 +58,7 @@ def set_config(
         )
     old = None if s.secret else sysconfig.get(db, key)
     try:
-        sysconfig.set_value(db, key, payload["value"])
+        sysconfig.set_value(db, key, body.value)
     except (TypeError, ValueError) as exc:
         raise HTTPException(status_code=400, detail=str(exc) or "Invalid value")
     # Never log a secret's value — only that it was changed, by whom. Non-secret values are logged
diff --git a/backend/app/routes/me.py b/backend/app/routes/me.py
index d21e9db..5d683d5 100644
--- a/backend/app/routes/me.py
+++ b/backend/app/routes/me.py
@@ -1,4 +1,5 @@
 from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request
+from pydantic import BaseModel
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
@@ -45,9 +46,13 @@ def my_accounts(
     return out
 
 
+class SwitchAccountIn(BaseModel):
+    user_id: int
+
+
 @router.post("/switch")
 def switch_account(
-    payload: dict,
+    body: SwitchAccountIn,
     request: Request,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
@@ -55,7 +60,7 @@ def switch_account(
     """Switch the active account to another one already authenticated in this browser. No
     Google round-trip — but only accounts present in the session list (proof they signed in
     here) are allowed, and access is re-checked in case the invite was revoked since."""
-    target = payload.get("user_id")
+    target = body.user_id
     if target not in (request.session.get("account_ids") or []):
         raise HTTPException(status_code=403, detail="Not an account you've signed into here.")
     u = db.get(User, target)
diff --git a/backend/app/routes/public.py b/backend/app/routes/public.py
index e7c3d0c..4d39459 100644
--- a/backend/app/routes/public.py
+++ b/backend/app/routes/public.py
@@ -8,6 +8,7 @@ a short-lived signed grant that the media URL carries (a `<video src>` can't sen
 
 from fastapi import APIRouter, Depends, HTTPException
 from fastapi.responses import FileResponse
+from pydantic import BaseModel
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
@@ -79,8 +80,12 @@ def watch_meta(token: str, db: Session = Depends(get_db)) -> dict:
     }
 
 
+class WatchUnlockIn(BaseModel):
+    password: str = ""
+
+
 @router.post("/watch/{token}/unlock")
-def watch_unlock(token: str, payload: dict, db: Session = Depends(get_db)) -> dict:
+def watch_unlock(token: str, body: WatchUnlockIn, db: Session = Depends(get_db)) -> dict:
     """Exchange the link password for a signed grant carried by the media URL."""
     if not _unlock_limit.allow(token):
         raise HTTPException(status_code=429, detail="Too many attempts. Try again later.")
@@ -92,7 +97,7 @@ def watch_unlock(token: str, payload: dict, db: Session = Depends(get_db)) -> di
             "needs_password": False,
             **linksmod.public_meta(link, job, asset, _file_url(token), _poster_url(token, asset)),
         }
-    if not verify_password((payload.get("password") or ""), link.password_hash):
+    if not verify_password(body.password, link.password_hash):
         raise HTTPException(status_code=403, detail="Wrong password.")
     job, asset = _ready_target(db, link)
     link.view_count += 1
diff --git a/backend/app/routes/scheduler.py b/backend/app/routes/scheduler.py
index eedbcd9..df20de6 100644
--- a/backend/app/routes/scheduler.py
+++ b/backend/app/routes/scheduler.py
@@ -2,6 +2,7 @@
 per-job run activity (from the in-process scheduler), the work still queued (DB-derived),
 and the shared quota picture."""
 from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
 from sqlalchemy import and_, func, or_, select
 from sqlalchemy.orm import Session
 
@@ -25,10 +26,14 @@ from app.sync.runner import estimate_deep_backfill
 router = APIRouter(prefix="/api/admin/scheduler", tags=["admin"])
 
 
+class JobIntervalIn(BaseModel):
+    interval_minutes: int
+
+
 @router.patch("/jobs/{job_id}")
 def set_job_interval(
     job_id: str,
-    payload: dict,
+    body: JobIntervalIn,
     admin: User = Depends(admin_user),
     db: Session = Depends(get_db),
 ) -> dict:
@@ -36,10 +41,7 @@ def set_job_interval(
     to the live scheduler immediately."""
     if job_id not in JOB_INTERVALS:
         raise HTTPException(status_code=404, detail="Unknown job")
-    try:
-        minutes = int(payload.get("interval_minutes"))
-    except (TypeError, ValueError):
-        raise HTTPException(status_code=400, detail="interval_minutes must be a number")
+    minutes = body.interval_minutes
     if not (MIN_INTERVAL <= minutes <= MAX_INTERVAL):
         raise HTTPException(
             status_code=400,
@@ -77,18 +79,19 @@ def run_all_now(user: User = Depends(admin_user)) -> dict:
     return {"started": trigger_all(actor_id=user.id)}
 
 
+class MaintenanceSettingsIn(BaseModel):
+    revalidate_batch: int
+
+
 @router.patch("/maintenance")
 def set_maintenance_settings(
-    payload: dict,
+    body: MaintenanceSettingsIn,
     admin: User = Depends(admin_user),
     db: Session = Depends(get_db),
 ) -> dict:
     """Admin-tune the maintenance job's rolling re-validation batch (videos re-checked per
     run). Persisted to app_state; the job reads it each run."""
-    try:
-        value = int(payload.get("revalidate_batch"))
-    except (TypeError, ValueError):
-        raise HTTPException(status_code=400, detail="revalidate_batch must be a number")
+    value = body.revalidate_batch
     if not (state.MAINTENANCE_BATCH_MIN <= value <= state.MAINTENANCE_BATCH_MAX):
         raise HTTPException(
             status_code=400,
diff --git a/backend/app/routes/search.py b/backend/app/routes/search.py
index b5489dd..375664b 100644
--- a/backend/app/routes/search.py
+++ b/backend/app/routes/search.py
@@ -16,6 +16,7 @@ from concurrent.futures import ThreadPoolExecutor
 from datetime import datetime, timezone
 
 from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
 from sqlalchemy import and_, delete, func, or_, select, update
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session, aliased
@@ -323,9 +324,13 @@ def search_youtube(
     }
 
 
+class ClearSearchIn(BaseModel):
+    video_ids: list[str] = []
+
+
 @router.post("/clear")
 def clear_search(
-    payload: dict,
+    body: ClearSearchIn,
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
@@ -333,7 +338,7 @@ def clear_search(
     for them, then hard-delete the now-orphaned ones — a via_search video nobody KEPT (no watch
     state, not playlisted, channel not subscribed) and that no other user still has as a search
     find. Kept videos and organically-owned ones are left untouched."""
-    ids = [str(v) for v in (payload.get("video_ids") or [])]
+    ids = body.video_ids
     if not ids:
         return {"removed": 0}
     db.execute(
diff --git a/backend/app/routes/tags.py b/backend/app/routes/tags.py
index 1ba7449..6e4e3e0 100644
--- a/backend/app/routes/tags.py
+++ b/backend/app/routes/tags.py
@@ -1,4 +1,5 @@
 from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
 from sqlalchemy import func, or_, select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
@@ -6,6 +7,7 @@ from sqlalchemy.orm import Session
 from app.auth import admin_user, current_user
 from app.db import get_db
 from app.models import ChannelTag, Tag, User
+from app.routes._common import owned_or_404
 from app.sync.autotag import run_autotag_all
 
 router = APIRouter(prefix="/api/tags", tags=["tags"])
@@ -33,21 +35,28 @@ def list_tags(user: User = Depends(current_user), db: Session = Depends(get_db))
     ]
 
 
+class TagCreateIn(BaseModel):
+    name: str
+    category: str = "other"
+    color: str | None = None
+
+
 @router.post("")
 def create_tag(
-    payload: dict,
+    body: TagCreateIn,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    name = (payload.get("name") or "").strip()
+    name = body.name.strip()
     if not name:
         raise HTTPException(status_code=400, detail="name is required")
-    category = payload.get("category") or "other"
+    # An unknown category silently falls back to "other" (unchanged behaviour) rather than 422.
+    category = body.category if body.category in ("language", "topic", "other") else "other"
     tag = Tag(
         user_id=user.id,
         name=name,
-        color=payload.get("color"),
-        category=category if category in ("language", "topic", "other") else "other",
+        color=body.color,
+        category=category,
     )
     db.add(tag)
     try:
@@ -59,28 +68,33 @@ def create_tag(
 
 
 def _own_tag(db: Session, user: User, tag_id: int) -> Tag:
-    tag = db.get(Tag, tag_id)
-    if tag is None or tag.user_id != user.id:
-        # System tags (user_id NULL) are not user-editable.
-        raise HTTPException(status_code=404, detail="Unknown tag")
-    return tag
+    # System tags (user_id NULL) are not user-editable → owned_or_404 404s them too.
+    return owned_or_404(db, Tag, tag_id, user, detail="Unknown tag")
+
+
+class TagUpdateIn(BaseModel):
+    # PATCH: presence matters, and `color: null` explicitly CLEARS it — so the endpoint reads
+    # model_fields_set rather than testing for None (which couldn't tell absent from cleared).
+    name: str | None = None
+    color: str | None = None
 
 
 @router.patch("/{tag_id}")
 def update_tag(
     tag_id: int,
-    payload: dict,
+    body: TagUpdateIn,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
     tag = _own_tag(db, user, tag_id)
-    if "name" in payload:
-        name = (payload.get("name") or "").strip()
+    sent = body.model_fields_set
+    if "name" in sent:
+        name = (body.name or "").strip()
         if not name:
             raise HTTPException(status_code=400, detail="name cannot be empty")
         tag.name = name
-    if "color" in payload:
-        tag.color = payload.get("color")
+    if "color" in sent:
+        tag.color = body.color
     try:
         db.commit()
     except IntegrityError:

From 99d65cea23cc26b09ffb77ae703c051403b0e583 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 26 Jul 2026 04:53:45 +0200
Subject: [PATCH 06/18] refactor(api): Pydantic request models for saved-views
 & feed state (R6 S1b)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- saved_views: CreateViewIn / UpdateViewIn / ReorderViewsIn. PATCH presence via
  model_fields_set; filters typed as dict (a non-object is now 422, an explicit
  null on update stays a 400 "filters must be an object").
- feed: VideoStateIn(status) / VideoProgressIn(position_seconds,duration_seconds) —
  the manual int()+400 in progress becomes a 422 on a non-number; the status
  membership 400 and the video 404 are unchanged.

Gate: ruff clean.
---
 backend/app/routes/feed.py        | 23 +++++++++-----
 backend/app/routes/saved_views.py | 51 +++++++++++++++++++------------
 2 files changed, 47 insertions(+), 27 deletions(-)

diff --git a/backend/app/routes/feed.py b/backend/app/routes/feed.py
index 8bfcc5f..100e296 100644
--- a/backend/app/routes/feed.py
+++ b/backend/app/routes/feed.py
@@ -5,6 +5,7 @@ import re
 from datetime import date, datetime, timedelta, timezone
 
 from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel
 from sqlalchemy import BigInteger, Select, and_, cast, false, func, or_, select
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session, aliased
@@ -571,14 +572,18 @@ def get_facets(
     return {"counts": counts}
 
 
+class VideoStateIn(BaseModel):
+    status: str
+
+
 @router.post("/videos/{video_id}/state")
 def set_video_state(
     video_id: str,
-    payload: dict,
+    body: VideoStateIn,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    status = payload.get("status")
+    status = body.status
     if status not in VALID_STATES:
         raise HTTPException(status_code=400, detail=f"status must be one of {VALID_STATES}")
     if db.get(Video, video_id) is None:
@@ -653,10 +658,15 @@ def clear_video_state(
     return {"video_id": video_id, "status": "new", "position_seconds": 0}
 
 
+class VideoProgressIn(BaseModel):
+    position_seconds: int = 0
+    duration_seconds: int = 0
+
+
 @router.post("/videos/{video_id}/progress")
 def set_video_progress(
     video_id: str,
-    payload: dict,
+    body: VideoProgressIn,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
@@ -664,11 +674,8 @@ def set_video_progress(
     Stores a per-user position on the video_states row without touching watch status, so a
     partially-watched video can render a progress bar and match the "in progress" filter.
     Trivially-early and near-finished positions clear the position rather than store it."""
-    try:
-        position = int(payload.get("position_seconds") or 0)
-        duration = int(payload.get("duration_seconds") or 0)
-    except (TypeError, ValueError):
-        raise HTTPException(status_code=400, detail="position_seconds must be an integer")
+    position = body.position_seconds
+    duration = body.duration_seconds
     if position < 0:
         position = 0
 
diff --git a/backend/app/routes/saved_views.py b/backend/app/routes/saved_views.py
index 7a2f9fe..f9bb8f6 100644
--- a/backend/app/routes/saved_views.py
+++ b/backend/app/routes/saved_views.py
@@ -1,4 +1,5 @@
 from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
 from sqlalchemy import func, select, update
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
@@ -40,25 +41,27 @@ def list_views(
     return [_serialize(v) for v in rows]
 
 
+class CreateViewIn(BaseModel):
+    name: str
+    filters: dict
+
+
 @router.post("")
 def create_view(
-    payload: dict,
+    body: CreateViewIn,
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
-    name = (payload.get("name") or "").strip()
+    name = body.name.strip()
     if not name:
         raise HTTPException(status_code=400, detail="name is required")
-    filters = payload.get("filters")
-    if not isinstance(filters, dict):
-        raise HTTPException(status_code=400, detail="filters must be an object")
     maxpos = db.execute(
         select(func.coalesce(func.max(SavedView.position), -1)).where(
             SavedView.user_id == user.id
         )
     ).scalar_one()
     view = SavedView(
-        user_id=user.id, name=name[:80], filters=filters, position=maxpos + 1
+        user_id=user.id, name=name[:80], filters=body.filters, position=maxpos + 1
     )
     db.add(view)
     try:
@@ -75,26 +78,34 @@ def _own_view(db: Session, user: User, view_id: int) -> SavedView:
     return owned_or_404(db, SavedView, view_id, user, detail="Unknown view")
 
 
+class UpdateViewIn(BaseModel):
+    # PATCH: presence decides what's touched (read via model_fields_set). filters, when sent,
+    # must be a real object — an explicit null is rejected (a view can't have null filters).
+    name: str | None = None
+    filters: dict | None = None
+    is_default: bool | None = None
+
+
 @router.patch("/{view_id}")
 def update_view(
     view_id: int,
-    payload: dict,
+    body: UpdateViewIn,
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
     view = _own_view(db, user, view_id)
-    if "name" in payload:
-        name = (payload.get("name") or "").strip()
+    sent = body.model_fields_set
+    if "name" in sent:
+        name = (body.name or "").strip()
         if not name:
             raise HTTPException(status_code=400, detail="name cannot be empty")
         view.name = name[:80]
-    if "filters" in payload:
-        filters = payload.get("filters")
-        if not isinstance(filters, dict):
+    if "filters" in sent:
+        if body.filters is None:
             raise HTTPException(status_code=400, detail="filters must be an object")
-        view.filters = filters
-    if "is_default" in payload:
-        make_default = bool(payload.get("is_default"))
+        view.filters = body.filters
+    if "is_default" in sent:
+        make_default = bool(body.is_default)
         if make_default:
             # At most one default per user: clear the flag on the others first.
             db.execute(
@@ -125,15 +136,17 @@ def delete_view(
     return {"deleted": view_id}
 
 
+class ReorderViewsIn(BaseModel):
+    ids: list[int]
+
+
 @router.post("/reorder")
 def reorder_views(
-    payload: dict,
+    body: ReorderViewsIn,
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
-    ids = payload.get("ids")
-    if not isinstance(ids, list):
-        raise HTTPException(status_code=400, detail="ids must be a list")
+    ids = body.ids
     rows = (
         db.execute(select(SavedView).where(SavedView.user_id == user.id))
         .scalars()

From ab83aae8bbdc95f8f3ab6d8398346564c9fadc32 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 26 Jul 2026 04:56:55 +0200
Subject: [PATCH 07/18] refactor(api): Pydantic request models for setup &
 admin routes (R6 S1b)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- setup: SetupAdminIn (KILLS the 3rd named 500 — a non-string password reaching
  argon2/len()), SetupTestEmailIn; setup_config stays a typed dict[str, Any] (a
  genuinely dynamic key→value settings map, not a fixed schema).
- admin: AddInviteIn / SetRoleIn / SetSuspendedIn / AddDemoWhitelistIn. The
  role/status business-rule 400s are unchanged; type errors are now 422.

All 3 ROADMAP-named 500-producers now fixed (channels priority + tag_id, setup
password). Gate: ruff clean, pytest 164 green.
---
 backend/app/routes/admin.py | 36 +++++++++++++++++++++++++++---------
 backend/app/routes/setup.py | 32 ++++++++++++++++++++++++--------
 2 files changed, 51 insertions(+), 17 deletions(-)

diff --git a/backend/app/routes/admin.py b/backend/app/routes/admin.py
index c319756..576bbc0 100644
--- a/backend/app/routes/admin.py
+++ b/backend/app/routes/admin.py
@@ -3,6 +3,7 @@ Also the demo-account admin surface: the demo email whitelist + a manual state r
 from datetime import datetime, timezone
 
 from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
+from pydantic import BaseModel
 from sqlalchemy import delete, func, select
 from sqlalchemy.orm import Session
 
@@ -110,14 +111,18 @@ def deny_invite(
     return _serialize(_decide(db, invite_id, admin, approved=False))
 
 
+class AddInviteIn(BaseModel):
+    email: str = ""
+
+
 @router.post("/invites")
 def add_invite(
-    payload: dict,
+    body: AddInviteIn,
     admin: User = Depends(admin_user),
     db: Session = Depends(get_db),
 ) -> dict:
     """Manually whitelist an email (approved straight away). Convenience for the admin."""
-    email = (payload.get("email") or "").strip().lower()
+    email = body.email.strip().lower()
     if not valid_email(email):
         raise HTTPException(status_code=400, detail="Enter a valid email address.")
     inv = db.execute(select(Invite).where(Invite.email == email)).scalar_one_or_none()
@@ -157,17 +162,21 @@ def list_users(_: User = Depends(admin_user), db: Session = Depends(get_db)) ->
     return [_serialize_user(u) for u in rows]
 
 
+class SetRoleIn(BaseModel):
+    role: str
+
+
 @router.patch("/users/{user_id}/role")
 def set_user_role(
     user_id: int,
-    payload: dict,
+    body: SetRoleIn,
     background: BackgroundTasks,
     admin: User = Depends(admin_user),
     db: Session = Depends(get_db),
 ) -> dict:
     """Promote/demote a user. Guards: can't change your own role, can't touch the demo
     account, and can't remove the last remaining admin. Emails the user when it actually changes."""
-    role = payload.get("role")
+    role = body.role
     if role not in ("user", "admin"):
         raise HTTPException(status_code=400, detail="role must be 'user' or 'admin'")
     target = db.get(User, user_id)
@@ -198,10 +207,14 @@ def set_user_role(
     return _serialize_user(target)
 
 
+class SetSuspendedIn(BaseModel):
+    suspended: bool = False
+
+
 @router.patch("/users/{user_id}/suspend")
 def set_user_suspended(
     user_id: int,
-    payload: dict,
+    body: SetSuspendedIn,
     background: BackgroundTasks,
     admin: User = Depends(admin_user),
     db: Session = Depends(get_db),
@@ -211,7 +224,7 @@ def set_user_suspended(
     suspend yourself, and can't suspend the last active admin (that would lock admin out). On
     un-suspend the user is emailed they can return (suspend is announced reactively, on a blocked
     sign-in)."""
-    suspended = bool(payload.get("suspended"))
+    suspended = body.suspended
     target = db.get(User, user_id)
     if target is None:
         raise HTTPException(status_code=404, detail="No such user")
@@ -296,15 +309,20 @@ def list_demo_whitelist(
     return [_serialize_demo(r) for r in rows]
 
 
+class AddDemoWhitelistIn(BaseModel):
+    email: str = ""
+    note: str | None = None
+
+
 @router.post("/demo/whitelist")
 def add_demo_whitelist(
-    payload: dict,
+    body: AddDemoWhitelistIn,
     admin: User = Depends(admin_user),
     db: Session = Depends(get_db),
 ) -> dict:
     """Add an email that may enter the shared demo account from the login page (no Google
     sign-in). Idempotent — re-adding an existing email just returns it."""
-    email = (payload.get("email") or "").strip().lower()
+    email = body.email.strip().lower()
     if not valid_email(email):
         raise HTTPException(status_code=400, detail="Enter a valid email address.")
     row = db.execute(
@@ -313,7 +331,7 @@ def add_demo_whitelist(
     if row is None:
         row = DemoWhitelist(
             email=email,
-            note=(payload.get("note") or "").strip() or None,
+            note=(body.note or "").strip() or None,
             added_by=admin.email,
         )
         db.add(row)
diff --git a/backend/app/routes/setup.py b/backend/app/routes/setup.py
index bea3542..be1b716 100644
--- a/backend/app/routes/setup.py
+++ b/backend/app/routes/setup.py
@@ -5,7 +5,10 @@ mutating step goes through `require_setup`: it rejects once the instance is conf
 the one-time setup token (printed to the container logs at first boot, carried by the wizard as the
 X-Setup-Token header). The wizard steps themselves are added in epic 6c.
 """
+from typing import Any
+
 from fastapi import APIRouter, Depends, Header, HTTPException
+from pydantic import BaseModel
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
@@ -45,12 +48,20 @@ def setup_info(db: Session = Depends(require_setup)) -> dict:
     return {"secrets_manageable": sysconfig.secrets_manageable()}
 
 
+class SetupAdminIn(BaseModel):
+    # Both default to "" so a missing field stays the wizard's own 400 ("Enter a valid email" /
+    # password too short) rather than a 422. `password: str` also stops a non-string value from
+    # reaching argon2 (which would 500 in len()/hash_password) — it's now a clean 422.
+    email: str = ""
+    password: str = ""
+
+
 @router.post("/admin")
-def setup_admin(payload: dict, db: Session = Depends(require_setup)) -> dict:
+def setup_admin(body: SetupAdminIn, db: Session = Depends(require_setup)) -> dict:
     """Create (or update) the first administrator. Active + verified immediately — the operator is
     configuring the instance, so there's no email-verification / approval gate here."""
-    email = (payload.get("email") or "").strip().lower()
-    password = payload.get("password") or ""
+    email = body.email.strip().lower()
+    password = body.password
     if "@" not in email:
         raise HTTPException(status_code=400, detail="Enter a valid email address.")
     if len(password) < PASSWORD_MIN_LEN:
@@ -70,11 +81,12 @@ def setup_admin(payload: dict, db: Session = Depends(require_setup)) -> dict:
 
 
 @router.post("/config")
-def setup_config(payload: dict, db: Session = Depends(require_setup)) -> dict:
+def setup_config(settings_map: dict[str, Any], db: Session = Depends(require_setup)) -> dict:
     """Persist provided DB-backed settings (Google creds, SMTP, quota…). Keys must be in the
-    sysconfig registry; empty values are skipped (left at the default)."""
+    sysconfig registry; empty values are skipped (left at the default). Genuinely dynamic
+    key→value map, so it stays a typed dict rather than a fixed model."""
     saved: list[str] = []
-    for key, value in (payload or {}).items():
+    for key, value in settings_map.items():
         if sysconfig.spec(key) is None:
             raise HTTPException(status_code=400, detail=f"Unknown setting: {key}")
         if value is None or value == "":
@@ -87,10 +99,14 @@ def setup_config(payload: dict, db: Session = Depends(require_setup)) -> dict:
     return {"saved": saved}
 
 
+class SetupTestEmailIn(BaseModel):
+    to: str = ""
+
+
 @router.post("/test-email")
-def setup_test_email(payload: dict, db: Session = Depends(require_setup)) -> dict:
+def setup_test_email(body: SetupTestEmailIn, db: Session = Depends(require_setup)) -> dict:
     """Send a test email to confirm the SMTP settings the wizard just saved."""
-    to = (payload.get("to") or "").strip()
+    to = body.to.strip()
     if "@" not in to:
         raise HTTPException(status_code=400, detail="Enter a valid email address.")
     if not email_mod.send_test(to):

From 8bf5026e7ceb34f9704ecd08f200a118462ad6fb Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 26 Jul 2026 04:58:37 +0200
Subject: [PATCH 08/18] refactor(api): Pydantic request models for playlists
 routes (R6 S1b)

CreatePlaylistIn / RenamePlaylistIn (PATCH via model_fields_set) / ReorderItemsIn,
plus a shared VideoRefIn(video_id) for both add-video endpoints (watch-later +
add-item). A non-string video_id is now a 422 instead of reaching db.get.

Gate: ruff clean.
---
 backend/app/routes/playlists.py | 44 +++++++++++++++++++++++----------
 1 file changed, 31 insertions(+), 13 deletions(-)

diff --git a/backend/app/routes/playlists.py b/backend/app/routes/playlists.py
index 4d8e02a..d61a107 100644
--- a/backend/app/routes/playlists.py
+++ b/backend/app/routes/playlists.py
@@ -2,6 +2,7 @@
 catalog. Foundation phase = local only (create / rename / delete, add / remove / reorder
 items). YouTube two-way sync (mirror existing playlists, push edits) lands in later phases."""
 from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
 from sqlalchemy import func, select, and_
 from sqlalchemy.orm import Session, aliased
 
@@ -197,13 +198,22 @@ def list_playlists(
     ]
 
 
+class CreatePlaylistIn(BaseModel):
+    name: str
+
+
+# Shared by the two "add a video" endpoints (Watch-later shortcut + explicit add-to-playlist).
+class VideoRefIn(BaseModel):
+    video_id: str
+
+
 @router.post("")
 def create_playlist(
-    payload: dict,
+    body: CreatePlaylistIn,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    name = (payload.get("name") or "").strip()
+    name = body.name.strip()
     if not name:
         raise HTTPException(status_code=400, detail="name is required")
     pl = Playlist(user_id=user.id, name=name, position=_next_playlist_position(db, user.id))
@@ -233,13 +243,13 @@ def _watch_later(db: Session, user: User) -> Playlist:
 
 @router.post("/watch-later")
 def add_watch_later(
-    payload: dict,
+    body: VideoRefIn,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
     """Bookmark shortcut: add a video to the built-in Watch later playlist."""
-    video_id = payload.get("video_id")
-    if not video_id or db.get(Video, video_id) is None:
+    video_id = body.video_id
+    if db.get(Video, video_id) is None:
         raise HTTPException(status_code=404, detail="Unknown video")
     pl = _watch_later(db, user)
     _add_item(db, pl, video_id, mark_dirty=False)
@@ -394,16 +404,20 @@ def get_playlist(
     }
 
 
+class RenamePlaylistIn(BaseModel):
+    name: str | None = None
+
+
 @router.patch("/{playlist_id}")
 def rename_playlist(
     playlist_id: int,
-    payload: dict,
+    body: RenamePlaylistIn,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
     pl = _own_playlist(db, user, playlist_id)
-    if "name" in payload:
-        name = (payload.get("name") or "").strip()
+    if "name" in body.model_fields_set:
+        name = (body.name or "").strip()
         if not name:
             raise HTTPException(status_code=400, detail="name cannot be empty")
         if name != pl.name:
@@ -462,13 +476,13 @@ def delete_playlist(
 @router.post("/{playlist_id}/items")
 def add_item(
     playlist_id: int,
-    payload: dict,
+    body: VideoRefIn,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
     pl = _own_playlist(db, user, playlist_id)
-    video_id = payload.get("video_id")
-    if not video_id or db.get(Video, video_id) is None:
+    video_id = body.video_id
+    if db.get(Video, video_id) is None:
         raise HTTPException(status_code=404, detail="Unknown video")
     _add_item(db, pl, video_id, mark_dirty=True)
     return {"playlist_id": pl.id, "video_id": video_id}
@@ -486,15 +500,19 @@ def remove_item(
     return {"playlist_id": pl.id, "video_id": video_id}
 
 
+class ReorderItemsIn(BaseModel):
+    video_ids: list[str] = []
+
+
 @router.put("/{playlist_id}/order")
 def reorder_items(
     playlist_id: int,
-    payload: dict,
+    body: ReorderItemsIn,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
     pl = _own_playlist(db, user, playlist_id)
-    order = payload.get("video_ids") or []
+    order = body.video_ids
     items = {
         it.video_id: it
         for it in db.execute(

From f4bf1bc18fecf1893fa75fc0f797563ad4a4f75c Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 26 Jul 2026 05:02:49 +0200
Subject: [PATCH 09/18] refactor(api): Pydantic request models for downloads
 routes (R6 S1b)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

All 11 download endpoints off payload:dict. Highlights:
- admin_set_quota: AdminSetQuotaIn — the `int(payload["max_bytes"])` 500 on a
  non-number is now a 422; each field set only when provided (is not None).
- profiles/enqueue/edit: CreateProfileIn / UpdateProfileIn / EnqueueDownloadIn /
  EnqueueEditIn; spec/edit_spec typed as dict (non-object → 422). _resolve_spec now
  takes (profile_id, spec) instead of the raw payload.
- meta/share/links: UpdateDownloadMetaIn / ShareDownloadIn / CreateLinkIn /
  UpdateLinkIn; _link_expiry takes an int|None instead of digging the payload.
PATCH endpoints read model_fields_set so an explicit null still clears a field.

Gate: ruff clean, pytest 164 green.
---
 backend/app/routes/downloads.py | 191 ++++++++++++++++++++------------
 1 file changed, 121 insertions(+), 70 deletions(-)

diff --git a/backend/app/routes/downloads.py b/backend/app/routes/downloads.py
index 10c45c1..2c5fefd 100644
--- a/backend/app/routes/downloads.py
+++ b/backend/app/routes/downloads.py
@@ -11,6 +11,7 @@ from urllib.parse import parse_qs, urlparse
 
 from fastapi import APIRouter, Depends, HTTPException, Request
 from fastapi.responses import FileResponse
+from pydantic import BaseModel
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
@@ -173,16 +174,19 @@ def list_profiles(
     return [_serialize_profile(p) for p in rows]
 
 
+class CreateProfileIn(BaseModel):
+    name: str
+    spec: dict
+
+
 @router.post("/profiles")
 def create_profile(
-    payload: dict, user: User = Depends(require_human), db: Session = Depends(get_db)
+    body: CreateProfileIn, user: User = Depends(require_human), db: Session = Depends(get_db)
 ) -> dict:
-    name = (payload.get("name") or "").strip()
-    spec = payload.get("spec")
+    name = body.name.strip()
+    spec = body.spec
     if not name:
         raise HTTPException(status_code=400, detail="A profile name is required.")
-    if not isinstance(spec, dict):
-        raise HTTPException(status_code=400, detail="spec must be an object")
     maxpos = db.execute(
         select(func.coalesce(func.max(DownloadProfile.sort_order), 100)).where(
             DownloadProfile.user_id == user.id
@@ -196,25 +200,31 @@ def create_profile(
     return _serialize_profile(p)
 
 
+class UpdateProfileIn(BaseModel):
+    name: str | None = None
+    spec: dict | None = None
+
+
 @router.patch("/profiles/{profile_id}")
 def update_profile(
     profile_id: int,
-    payload: dict,
+    body: UpdateProfileIn,
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
     p = db.get(DownloadProfile, profile_id)
     if p is None or p.is_builtin or p.user_id != user.id:
         raise HTTPException(status_code=404, detail="Unknown profile")
-    if "name" in payload:
-        name = (payload.get("name") or "").strip()
+    sent = body.model_fields_set
+    if "name" in sent:
+        name = (body.name or "").strip()
         if not name:
             raise HTTPException(status_code=400, detail="A profile name is required.")
         p.name = name[:80]
-    if "spec" in payload:
-        if not isinstance(payload["spec"], dict):
+    if "spec" in sent:
+        if body.spec is None:
             raise HTTPException(status_code=400, detail="spec must be an object")
-        p.spec = payload["spec"]
+        p.spec = body.spec
     db.commit()
     return _serialize_profile(p)
 
@@ -231,17 +241,18 @@ def delete_profile(
     return {"deleted": profile_id}
 
 
-def _resolve_spec(db: Session, user: User, payload: dict) -> tuple[dict, int | None]:
+def _resolve_spec(
+    db: Session, user: User, profile_id: int | None, spec: dict | None
+) -> tuple[dict, int | None]:
     """Pick the format spec for an enqueue: an explicit profile_id (builtin or the user's own),
     an inline spec, or the first builtin as a fallback."""
-    pid = payload.get("profile_id")
-    if pid is not None:
-        p = db.get(DownloadProfile, pid)
+    if profile_id is not None:
+        p = db.get(DownloadProfile, profile_id)
         if p is None or (not p.is_builtin and p.user_id != user.id):
             raise HTTPException(status_code=404, detail="Unknown profile")
         return p.spec, p.id
-    if isinstance(payload.get("spec"), dict):
-        return payload["spec"], None
+    if spec is not None:
+        return spec, None
     fallback = db.execute(
         select(DownloadProfile)
         .where(DownloadProfile.is_builtin.is_(True))
@@ -255,13 +266,20 @@ def _resolve_spec(db: Session, user: User, payload: dict) -> tuple[dict, int | N
 
 # --- enqueue + list + manage ---------------------------------------------------------------
 
+class EnqueueDownloadIn(BaseModel):
+    source: str = ""
+    profile_id: int | None = None
+    spec: dict | None = None
+    display_name: str | None = None
+
+
 @router.post("")
 def enqueue_download(
-    payload: dict, user: User = Depends(require_human), db: Session = Depends(get_db)
+    body: EnqueueDownloadIn, user: User = Depends(require_human), db: Session = Depends(get_db)
 ) -> dict:
-    source_kind, source_ref = resolve_source(payload.get("source") or "")
-    spec, profile_id = _resolve_spec(db, user, payload)
-    display_name = (payload.get("display_name") or "").strip() or None
+    source_kind, source_ref = resolve_source(body.source)
+    spec, profile_id = _resolve_spec(db, user, body.profile_id, body.spec)
+    display_name = (body.display_name or "").strip() or None
     try:
         job = service.enqueue(
             db, user.id, source_kind, source_ref, spec, profile_id, display_name
@@ -271,22 +289,26 @@ def enqueue_download(
     return _serialize_job(db, job)
 
 
+class EnqueueEditIn(BaseModel):
+    source_job_id: int = 0
+    edit_spec: dict
+    display_name: str | None = None
+
+
 @router.post("/edit")
 def enqueue_edit(
-    payload: dict, user: User = Depends(require_human), db: Session = Depends(get_db)
+    body: EnqueueEditIn, user: User = Depends(require_human), db: Session = Depends(get_db)
 ) -> dict:
     """Queue a phase-2 editor derivative (trim/crop) of a download this user can access.
 
     The source may be the user's own download OR one shared with them — either way the resulting
     clip is a NEW per-user derivative in the editor's own library (counts against their quota); the
     source file is only read, never modified, so editing a shared video is safe."""
-    source_job = _accessible_job(db, user, int(payload.get("source_job_id") or 0))
+    source_job = _accessible_job(db, user, body.source_job_id)
     if source_job.status != "done" or source_job.asset_id is None:
         raise HTTPException(status_code=409, detail="You can only edit a finished download.")
-    spec = payload.get("edit_spec")
-    if not isinstance(spec, dict):
-        raise HTTPException(status_code=400, detail="edit_spec must be an object")
-    display_name = (payload.get("display_name") or "").strip() or None
+    spec = body.edit_spec
+    display_name = (body.display_name or "").strip() or None
     try:
         job = service.enqueue_edit(db, user.id, source_job, spec, display_name)
     except quota.QuotaExceeded as e:
@@ -389,26 +411,34 @@ def _clean_url(raw) -> str | None:
     return url[:2048]
 
 
+class UpdateDownloadMetaIn(BaseModel):
+    # PATCH display-only overrides; presence (model_fields_set) decides what's touched. A field
+    # set to null/"" clears the override (falls back to the on-disk system value).
+    display_name: str | None = None
+    display_uploader: str | None = None
+    display_uploader_url: str | None = None
+    extra_links: list | None = None
+
+
 @router.patch("/{job_id}")
 def update_download_meta(
     job_id: int,
-    payload: dict,
+    body: UpdateDownloadMetaIn,
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
     """Update a download's display metadata: title, channel name + link, and extra reference URLs.
     All are display-only overrides — the on-disk file keeps its system-decided, id-bound name."""
     job = _own_job(db, user, job_id)
-    if "display_name" in payload:
-        job.display_name = ((payload.get("display_name") or "").strip())[:255] or None
-    if "display_uploader" in payload:
-        job.display_uploader = ((payload.get("display_uploader") or "").strip())[:255] or None
-    if "display_uploader_url" in payload:
-        job.display_uploader_url = _clean_url(payload.get("display_uploader_url"))
-    if "extra_links" in payload:
-        raw = payload.get("extra_links") or []
-        if not isinstance(raw, list):
-            raise HTTPException(status_code=400, detail="extra_links must be a list")
+    sent = body.model_fields_set
+    if "display_name" in sent:
+        job.display_name = ((body.display_name or "").strip())[:255] or None
+    if "display_uploader" in sent:
+        job.display_uploader = ((body.display_uploader or "").strip())[:255] or None
+    if "display_uploader_url" in sent:
+        job.display_uploader_url = _clean_url(body.display_uploader_url)
+    if "extra_links" in sent:
+        raw = body.extra_links or []
         cleaned = [u for u in (_clean_url(x) for x in raw) if u][:_MAX_EXTRA_LINKS]
         job.extra_links = cleaned or None
     db.commit()
@@ -652,17 +682,21 @@ def storyboard_image(
 
 # --- sharing -------------------------------------------------------------------------------
 
+class ShareDownloadIn(BaseModel):
+    email: str = ""
+
+
 @router.post("/{job_id}/share")
 def share_download(
     job_id: int,
-    payload: dict,
+    body: ShareDownloadIn,
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
     job = _own_job(db, user, job_id)
     if job.status != "done" or job.asset_id is None:
         raise HTTPException(status_code=409, detail="Only a finished download can be shared.")
-    target = (payload.get("email") or "").strip().lower()
+    target = body.email.strip().lower()
     if not target:
         raise HTTPException(status_code=400, detail="A recipient email is required.")
     recipient = db.execute(
@@ -771,17 +805,12 @@ def _own_link(db: Session, user: User, link_id: int) -> DownloadLink:
     return link
 
 
-def _link_expiry(payload: dict) -> datetime | None:
-    days = payload.get("expires_days")
-    if days in (None, "", 0, "0"):
+def _link_expiry(days: int | None) -> datetime | None:
+    # None/0/negative → no expiry; otherwise N days out, capped at ~10 years. The Pydantic model
+    # already coerced/validated the type, so a non-number is a 422 before we get here.
+    if not days or days <= 0:
         return None
-    try:
-        d = int(days)
-    except (TypeError, ValueError):
-        raise HTTPException(status_code=400, detail="expires_days must be a number")
-    if d <= 0:
-        return None
-    return datetime.now(timezone.utc) + timedelta(days=min(d, 3650))
+    return datetime.now(timezone.utc) + timedelta(days=min(days, 3650))
 
 
 @router.get("/{job_id}/links")
@@ -799,24 +828,30 @@ def list_links(
     return [linksmod.owner_view(row) for row in rows]
 
 
+class CreateLinkIn(BaseModel):
+    password: str = ""
+    allow_download: bool = False
+    expires_days: int | None = None
+
+
 @router.post("/{job_id}/links")
 def create_link(
     job_id: int,
-    payload: dict,
+    body: CreateLinkIn,
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
     job = _own_job(db, user, job_id)
     if job.status != "done" or job.asset_id is None:
         raise HTTPException(status_code=409, detail="Only a finished download can be shared.")
-    pw = (payload.get("password") or "").strip()
+    pw = body.password.strip()
     link = DownloadLink(
         job_id=job_id,
         token=linksmod.new_token(),
         created_by=user.id,
-        allow_download=bool(payload.get("allow_download")),
+        allow_download=body.allow_download,
         password_hash=hash_password(pw) if pw else None,
-        expires_at=_link_expiry(payload),
+        expires_at=_link_expiry(body.expires_days),
     )
     db.add(link)
     db.commit()
@@ -824,20 +859,27 @@ def create_link(
     return linksmod.owner_view(link)
 
 
+class UpdateLinkIn(BaseModel):
+    allow_download: bool | None = None
+    expires_days: int | None = None
+    password: str | None = None
+
+
 @router.patch("/links/{link_id}")
 def update_link(
     link_id: int,
-    payload: dict,
+    body: UpdateLinkIn,
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
     link = _own_link(db, user, link_id)
-    if "allow_download" in payload:
-        link.allow_download = bool(payload["allow_download"])
-    if "expires_days" in payload:
-        link.expires_at = _link_expiry(payload)
-    if "password" in payload:
-        pw = (payload.get("password") or "").strip()
+    sent = body.model_fields_set
+    if "allow_download" in sent:
+        link.allow_download = bool(body.allow_download)
+    if "expires_days" in sent:
+        link.expires_at = _link_expiry(body.expires_days)
+    if "password" in sent:
+        pw = (body.password or "").strip()
         link.password_hash = hash_password(pw) if pw else None
         # Bump the version so any grant issued under the previous password stops working now, rather
         # than living out its 6h TTL (setting/clearing/changing the password all count as a rotation).
@@ -933,10 +975,19 @@ def admin_get_quota(
     }
 
 
+class AdminSetQuotaIn(BaseModel):
+    # Each field is set only when provided as a real value (is not None). A non-numeric limit
+    # used to reach int() and 500; it's now a clean 422.
+    max_bytes: int | None = None
+    max_concurrent: int | None = None
+    max_jobs: int | None = None
+    unlimited: bool | None = None
+
+
 @admin_router.put("/quota/{user_id}")
 def admin_set_quota(
     user_id: int,
-    payload: dict,
+    body: AdminSetQuotaIn,
     admin: User = Depends(admin_user),
     db: Session = Depends(get_db),
 ) -> dict:
@@ -953,14 +1004,14 @@ def admin_set_quota(
             unlimited=cur.unlimited,
         )
         db.add(row)
-    if "max_bytes" in payload:
-        row.max_bytes = max(0, int(payload["max_bytes"]))
-    if "max_concurrent" in payload:
-        row.max_concurrent = max(1, int(payload["max_concurrent"]))
-    if "max_jobs" in payload:
-        row.max_jobs = max(1, int(payload["max_jobs"]))
-    if "unlimited" in payload:
-        row.unlimited = bool(payload["unlimited"])
+    if body.max_bytes is not None:
+        row.max_bytes = max(0, body.max_bytes)
+    if body.max_concurrent is not None:
+        row.max_concurrent = max(1, body.max_concurrent)
+    if body.max_jobs is not None:
+        row.max_jobs = max(1, body.max_jobs)
+    if body.unlimited is not None:
+        row.unlimited = body.unlimited
     db.commit()
     return admin_get_quota(user_id, admin, db)
 

From 66f4ac30d0c851200580fd414e30310a33d4c2ac Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 26 Jul 2026 05:08:27 +0200
Subject: [PATCH 10/18] refactor(api): Pydantic request models for plex routes
 + status unification (R6 S1b)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

All 14 plex payload:dict endpoints typed (watch-link, collections, native
playlists, item/show/season state & progress). Shared PlexItemKeysIn (bulk add/
remove/reorder) and WatchedIn (show/season). item_progress's manual int()+400
becomes a 422 on a non-number.

Status-code unification (ROADMAP S1):
- the 5 collection write-failure 502s → 422, matching the house "external write
  failed" convention (playlists' YouTube 422). The image/subtitle proxy-fetch 502s
  stay (genuine gateway fetches).
- the field-validation 422s ("title is required", "title and item_rating_key are
  required") → 400, matching every other module's required-field 400.

Ends S1b: no `payload: dict` remains in app/routes. Gate: ruff clean, pytest 164.
---
 backend/app/routes/plex.py | 152 ++++++++++++++++++++++++++-----------
 1 file changed, 107 insertions(+), 45 deletions(-)

diff --git a/backend/app/routes/plex.py b/backend/app/routes/plex.py
index ce0549f..2cb148a 100644
--- a/backend/app/routes/plex.py
+++ b/backend/app/routes/plex.py
@@ -21,6 +21,7 @@ from pathlib import Path
 import httpx
 from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Query, Request, Response
 from fastapi.responses import FileResponse
+from pydantic import BaseModel
 from sqlalchemy import Integer, String, and_, case, cast, func, literal, null, or_
 from sqlalchemy.orm import Session, aliased
 
@@ -156,9 +157,13 @@ def watch_link_status(
     return _link_dict(link)
 
 
+class WatchLinkIn(BaseModel):
+    enabled: bool = False
+
+
 @router.post("/watch/link")
 def watch_link_set(
-    payload: dict,
+    body: WatchLinkIn,
     user: User = Depends(admin_user),
     db: Session = Depends(get_db),
 ) -> dict:
@@ -167,7 +172,7 @@ def watch_link_set(
     "Plex is master" import immediately so the owner's existing Plex history shows up in Siftlode."""
     if not sysconfig.get_bool(db, "plex_enabled"):
         raise HTTPException(status_code=409, detail="The Plex module is disabled.")
-    enabled = bool(payload.get("enabled"))
+    enabled = body.enabled
     link = db.query(PlexLink).filter_by(user_id=user.id).first()
     if link is None:
         link = PlexLink(user_id=user.id, uses_admin=True, linked_at=datetime.now(timezone.utc))
@@ -797,14 +802,22 @@ def _editable_collection_or_403(db: Session, rating_key: str) -> PlexCollection:
     return col
 
 
+class CreateCollectionIn(BaseModel):
+    library: str = ""
+    title: str = ""
+    item_rating_key: str = ""
+
+
 @router.post("/collections")
-def create_collection(payload: dict, _: User = Depends(admin_user), db: Session = Depends(get_db)) -> dict:
+def create_collection(
+    body: CreateCollectionIn, _: User = Depends(admin_user), db: Session = Depends(get_db)
+) -> dict:
     """Create a manual collection (seeded with one item — Plex needs at least one). Editable by default."""
-    library = str(payload.get("library") or "")
-    title = (payload.get("title") or "").strip()
-    seed = str(payload.get("item_rating_key") or "")
+    library = body.library
+    title = body.title.strip()
+    seed = body.item_rating_key
     if not title or not seed:
-        raise HTTPException(status_code=422, detail="title and item_rating_key are required")
+        raise HTTPException(status_code=400, detail="title and item_rating_key are required")
     lib = db.query(PlexLibrary).filter_by(plex_key=library).first()
     if lib is None:
         raise HTTPException(status_code=404, detail="Unknown library")
@@ -816,7 +829,7 @@ def create_collection(payload: dict, _: User = Depends(admin_user), db: Session
         db.commit()
     except (PlexError, PlexNotConfigured) as e:
         db.rollback()
-        raise HTTPException(status_code=502, detail=f"Plex write failed: {e}")
+        raise HTTPException(status_code=422, detail=f"Plex write failed: {e}")
     return _collection_card(col)
 
 
@@ -833,7 +846,7 @@ def collection_add_item(
         db.commit()
     except (PlexError, PlexNotConfigured) as e:
         db.rollback()
-        raise HTTPException(status_code=502, detail=f"Plex write failed: {e}")
+        raise HTTPException(status_code=422, detail=f"Plex write failed: {e}")
     return _collection_card(col)
 
 
@@ -850,18 +863,22 @@ def collection_remove_item(
         db.commit()
     except (PlexError, PlexNotConfigured) as e:
         db.rollback()
-        raise HTTPException(status_code=502, detail=f"Plex write failed: {e}")
+        raise HTTPException(status_code=422, detail=f"Plex write failed: {e}")
     return _collection_card(col)
 
 
+class CollectionRenameIn(BaseModel):
+    title: str = ""
+
+
 @router.patch("/collections/{rating_key}")
 def collection_rename(
-    rating_key: str, payload: dict, _: User = Depends(admin_user), db: Session = Depends(get_db)
+    rating_key: str, body: CollectionRenameIn, _: User = Depends(admin_user), db: Session = Depends(get_db)
 ) -> dict:
     col = _editable_collection_or_403(db, rating_key)
-    title = (payload.get("title") or "").strip()
+    title = body.title.strip()
     if not title:
-        raise HTTPException(status_code=422, detail="title is required")
+        raise HTTPException(status_code=400, detail="title is required")
     lib = db.get(PlexLibrary, col.library_id)
     try:
         with PlexClient(db) as plex:
@@ -870,7 +887,7 @@ def collection_rename(
         db.commit()
     except (PlexError, PlexNotConfigured) as e:
         db.rollback()
-        raise HTTPException(status_code=502, detail=f"Plex write failed: {e}")
+        raise HTTPException(status_code=422, detail=f"Plex write failed: {e}")
     return _collection_card(col)
 
 
@@ -887,20 +904,24 @@ def collection_delete(
         db.commit()
     except (PlexError, PlexNotConfigured) as e:
         db.rollback()
-        raise HTTPException(status_code=502, detail=f"Plex write failed: {e}")
+        raise HTTPException(status_code=422, detail=f"Plex write failed: {e}")
     return {"deleted": rating_key}
 
 
+class CollectionEditableIn(BaseModel):
+    editable: bool = False
+
+
 @router.post("/collections/{rating_key}/editable")
 def collection_set_editable(
-    rating_key: str, payload: dict, _: User = Depends(admin_user), db: Session = Depends(get_db)
+    rating_key: str, body: CollectionEditableIn, _: User = Depends(admin_user), db: Session = Depends(get_db)
 ) -> dict:
     """Mark an existing Plex collection as 'mine to edit' (or unmark). Smart / auto-list collections
     (IMDb/TMDb/…) can never be made editable — they're regenerated outside Plex."""
     col = db.query(PlexCollection).filter_by(rating_key=str(rating_key)).first()
     if col is None:
         raise HTTPException(status_code=404, detail="Unknown collection")
-    want = bool(payload.get("editable"))
+    want = body.editable
     if want and (col.smart or _collection_source(col) != "collection"):
         raise HTTPException(status_code=400, detail="Smart / auto-list collections can't be made editable")
     col.editable = want
@@ -975,15 +996,22 @@ def playlists(
     return resp
 
 
+class CreatePlexPlaylistIn(BaseModel):
+    title: str = ""
+    item_rating_key: str = ""
+
+
 @router.post("/playlists")
-def create_playlist(payload: dict, user: User = Depends(current_user), db: Session = Depends(get_db)) -> dict:
-    title = (payload.get("title") or "").strip()
+def create_playlist(
+    body: CreatePlexPlaylistIn, user: User = Depends(current_user), db: Session = Depends(get_db)
+) -> dict:
+    title = body.title.strip()
     if not title:
-        raise HTTPException(status_code=422, detail="title is required")
+        raise HTTPException(status_code=400, detail="title is required")
     pl = PlexPlaylist(user_id=user.id, title=title)
     db.add(pl)
     db.flush()
-    seed = str(payload.get("item_rating_key") or "")
+    seed = body.item_rating_key
     count = 0
     thumb_rk = None
     if seed:
@@ -1022,12 +1050,18 @@ def playlist_detail(pid: int, user: User = Depends(current_user), db: Session =
     return {"id": pl.id, "title": pl.title, "items": cards}
 
 
+class RenamePlexPlaylistIn(BaseModel):
+    title: str = ""
+
+
 @router.patch("/playlists/{pid}")
-def rename_playlist(pid: int, payload: dict, user: User = Depends(current_user), db: Session = Depends(get_db)) -> dict:
+def rename_playlist(
+    pid: int, body: RenamePlexPlaylistIn, user: User = Depends(current_user), db: Session = Depends(get_db)
+) -> dict:
     pl = _own_playlist_or_404(db, pid, user)
-    title = (payload.get("title") or "").strip()
+    title = body.title.strip()
     if not title:
-        raise HTTPException(status_code=422, detail="title is required")
+        raise HTTPException(status_code=400, detail="title is required")
     pl.title = title
     db.commit()
     count = db.query(func.count(PlexPlaylistItem.id)).filter_by(playlist_id=pl.id).scalar() or 0
@@ -1043,10 +1077,16 @@ def delete_playlist(pid: int, user: User = Depends(current_user), db: Session =
     return {"deleted": pid}
 
 
+class PlexItemRefIn(BaseModel):
+    item_rating_key: str = ""
+
+
 @router.post("/playlists/{pid}/items")
-def playlist_add_item(pid: int, payload: dict, user: User = Depends(current_user), db: Session = Depends(get_db)) -> dict:
+def playlist_add_item(
+    pid: int, body: PlexItemRefIn, user: User = Depends(current_user), db: Session = Depends(get_db)
+) -> dict:
     pl = _own_playlist_or_404(db, pid, user)
-    it = db.query(PlexItem).filter_by(rating_key=str(payload.get("item_rating_key") or "")).first()
+    it = db.query(PlexItem).filter_by(rating_key=body.item_rating_key).first()
     if it is None:
         raise HTTPException(status_code=404, detail="Unknown item")
     exists = db.query(PlexPlaylistItem).filter_by(playlist_id=pid, item_id=it.id).first()
@@ -1069,6 +1109,10 @@ def playlist_remove_item(pid: int, item_rating_key: str, user: User = Depends(cu
     return {"ok": True}
 
 
+class PlexItemKeysIn(BaseModel):
+    item_rating_keys: list[str] = []
+
+
 def _items_by_rks(db: Session, rks: list) -> list[PlexItem]:
     """Resolve rating_keys to PlexItems, preserving the input order (drops unknown keys)."""
     order = [str(k) for k in rks if str(k)]
@@ -1086,11 +1130,13 @@ def _items_by_rks(db: Session, rks: list) -> list[PlexItem]:
 
 
 @router.post("/playlists/{pid}/items/bulk")
-def playlist_add_bulk(pid: int, payload: dict, user: User = Depends(current_user), db: Session = Depends(get_db)) -> dict:
+def playlist_add_bulk(
+    pid: int, body: PlexItemKeysIn, user: User = Depends(current_user), db: Session = Depends(get_db)
+) -> dict:
     """Append many items at once (a whole season/show). Already-present items are skipped; the input
     order is preserved for the newly-added ones. Returns how many were added + the new total."""
     pl = _own_playlist_or_404(db, pid, user)
-    items = _items_by_rks(db, payload.get("item_rating_keys") or [])
+    items = _items_by_rks(db, body.item_rating_keys)
     existing = {row[0] for row in db.query(PlexPlaylistItem.item_id).filter_by(playlist_id=pid)}
     pos = int(db.query(func.coalesce(func.max(PlexPlaylistItem.position), -1)).filter_by(playlist_id=pid).scalar())
     added = 0
@@ -1109,11 +1155,13 @@ def playlist_add_bulk(pid: int, payload: dict, user: User = Depends(current_user
 
 
 @router.post("/playlists/{pid}/items/remove-bulk")
-def playlist_remove_bulk(pid: int, payload: dict, user: User = Depends(current_user), db: Session = Depends(get_db)) -> dict:
+def playlist_remove_bulk(
+    pid: int, body: PlexItemKeysIn, user: User = Depends(current_user), db: Session = Depends(get_db)
+) -> dict:
     """Remove many items at once (a whole season/show, or a multi-select). Returns how many were
     removed + the new total."""
     pl = _own_playlist_or_404(db, pid, user)
-    ids = [it.id for it in _items_by_rks(db, payload.get("item_rating_keys") or [])]
+    ids = [it.id for it in _items_by_rks(db, body.item_rating_keys)]
     removed = 0
     if ids:
         removed = (
@@ -1129,10 +1177,12 @@ def playlist_remove_bulk(pid: int, payload: dict, user: User = Depends(current_u
 
 
 @router.put("/playlists/{pid}/order")
-def reorder_playlist(pid: int, payload: dict, user: User = Depends(current_user), db: Session = Depends(get_db)) -> dict:
+def reorder_playlist(
+    pid: int, body: PlexItemKeysIn, user: User = Depends(current_user), db: Session = Depends(get_db)
+) -> dict:
     """Set the playlist order from an explicit list of item rating_keys (0-based positions)."""
     pl = _own_playlist_or_404(db, pid, user)
-    order = [str(k) for k in (payload.get("item_rating_keys") or [])]
+    order = body.item_rating_keys
     id_by_rk = {it.rating_key: it.id for it in db.query(PlexItem).filter(PlexItem.rating_key.in_(order or [""]))}
     for pos, rk in enumerate(order):
         iid = id_by_rk.get(rk)
@@ -1892,10 +1942,16 @@ def _push_watch(
     )
 
 
+class ItemProgressIn(BaseModel):
+    position_seconds: int = 0
+    duration_seconds: int = 0
+    final: bool = False
+
+
 @router.post("/item/{rating_key}/progress")
 def item_progress(
     rating_key: str,
-    payload: dict,
+    body: ItemProgressIn,
     background: BackgroundTasks,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
@@ -1906,12 +1962,9 @@ def item_progress(
     debounces the Plex resume push: we mirror the settled position to Plex only on a final flush, so
     a single watch doesn't spray `/:/timeline` calls at the server every 10 seconds."""
     it = _item_or_404(db, rating_key)
-    try:
-        position = max(0, int(payload.get("position_seconds") or 0))
-        duration = int(payload.get("duration_seconds") or 0)
-    except (TypeError, ValueError):
-        raise HTTPException(status_code=400, detail="position_seconds must be an integer")
-    final = bool(payload.get("final"))
+    position = max(0, body.position_seconds)
+    duration = body.duration_seconds
+    final = body.final
     now = datetime.now(timezone.utc)
     st = db.query(PlexState).filter_by(user_id=user.id, item_id=it.id).first()
     was_watched = st is not None and st.status == "watched"
@@ -1957,10 +2010,14 @@ def item_progress(
     return {"position_seconds": position}
 
 
+class ItemStateIn(BaseModel):
+    status: str = ""
+
+
 @router.post("/item/{rating_key}/state")
 def item_state(
     rating_key: str,
-    payload: dict,
+    body: ItemStateIn,
     background: BackgroundTasks,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
@@ -1969,7 +2026,7 @@ def item_state(
     to a linked Plex account immediately; `hidden` is a Siftlode-only concept with no Plex analogue,
     so it never touches Plex."""
     it = _item_or_404(db, rating_key)
-    status = payload.get("status")
+    status = body.status
     if status not in ("new", "watched", "hidden"):
         raise HTTPException(status_code=400, detail="Invalid status")
     st = db.query(PlexState).filter_by(user_id=user.id, item_id=it.id).first()
@@ -2035,10 +2092,15 @@ def _bulk_state(
     return len(to_push)
 
 
+# Shared by the show- and season-level "mark all episodes watched/unwatched" endpoints.
+class WatchedIn(BaseModel):
+    watched: bool = False
+
+
 @router.post("/show/{rating_key}/state")
 def show_state(
     rating_key: str,
-    payload: dict,
+    body: WatchedIn,
     background: BackgroundTasks,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
@@ -2047,7 +2109,7 @@ def show_state(
     sh = db.query(PlexShow).filter_by(rating_key=str(rating_key)).first()
     if sh is None:
         raise HTTPException(status_code=404, detail="Unknown Plex show")
-    watched = bool(payload.get("watched"))
+    watched = body.watched
     eps = db.query(PlexItem).filter_by(show_id=sh.id, kind="episode").all()
     changed = _bulk_state(background, db, user.id, eps, watched)
     return {"changed": changed, "watched": watched}
@@ -2056,7 +2118,7 @@ def show_state(
 @router.post("/season/{rating_key}/state")
 def season_state(
     rating_key: str,
-    payload: dict,
+    body: WatchedIn,
     background: BackgroundTasks,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
@@ -2065,7 +2127,7 @@ def season_state(
     se = db.query(PlexSeason).filter_by(rating_key=str(rating_key)).first()
     if se is None:
         raise HTTPException(status_code=404, detail="Unknown Plex season")
-    watched = bool(payload.get("watched"))
+    watched = body.watched
     eps = db.query(PlexItem).filter_by(season_id=se.id, kind="episode").all()
     changed = _bulk_state(background, db, user.id, eps, watched)
     return {"changed": changed, "watched": watched}

From b0894a9994265b619ffaac83c3370371ae6f9113 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 26 Jul 2026 05:09:35 +0200
Subject: [PATCH 11/18] test(api): request-model validation for the S1b
 500-fixes (R6 S1b)

Pure-logic tests that the three ROADMAP-named 500-producers (channel priority,
tag_id, setup password) and admin quota now reject bad input at the model
boundary, and that the PATCH models separate absent from explicit-null via
model_fields_set. Mutation-checked: reverting a field type turns them red.
---
 backend/tests/test_request_models.py | 57 ++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 backend/tests/test_request_models.py

diff --git a/backend/tests/test_request_models.py b/backend/tests/test_request_models.py
new file mode 100644
index 0000000..f45f73c
--- /dev/null
+++ b/backend/tests/test_request_models.py
@@ -0,0 +1,57 @@
+"""R6 S1b: the request models turn payloads that used to 500 into clean validation errors,
+and PATCH models distinguish an absent field from an explicit null. Pure-logic (no DB) — it
+exercises the Pydantic models the route modules define, not the endpoints."""
+import pytest
+from pydantic import ValidationError
+
+from app.routes.channels import AttachTagIn, ChannelUpdateIn
+from app.routes.downloads import AdminSetQuotaIn
+from app.routes.setup import SetupAdminIn
+from app.routes.tags import TagUpdateIn
+
+
+# --- The three ROADMAP-named 500-producers are now 422s (ValidationError at the boundary). ---
+
+def test_channel_priority_rejects_non_numeric():
+    # Was `int(payload["priority"])` → 500 on garbage. Now a validation error.
+    with pytest.raises(ValidationError):
+        ChannelUpdateIn(priority="not-a-number")
+
+
+def test_channel_priority_accepts_int_and_numeric_string():
+    assert ChannelUpdateIn(priority=5).priority == 5
+    assert ChannelUpdateIn(priority="5").priority == 5  # lax numeric-string coercion, as before
+
+
+def test_channel_update_fields_all_optional():
+    m = ChannelUpdateIn()
+    assert m.priority is None and m.hidden is None and m.deep_requested is None
+
+
+def test_attach_tag_rejects_non_int_id():
+    # Was a str tag_id into db.get(Tag, ...) — a DB cast 500. Now rejected up front.
+    with pytest.raises(ValidationError):
+        AttachTagIn(tag_id="abc")
+
+
+def test_setup_admin_password_must_be_a_string():
+    # Was a non-string password reaching len()/argon2 → 500. `str` rejects it.
+    with pytest.raises(ValidationError):
+        SetupAdminIn(email="a@b.c", password=12345)
+
+
+def test_admin_quota_rejects_non_numeric_limit():
+    # Was `int(payload["max_bytes"])` → 500. Now a validation error.
+    with pytest.raises(ValidationError):
+        AdminSetQuotaIn(max_bytes="lots")
+
+
+# --- PATCH models: model_fields_set separates "absent" from "explicit null". ---
+
+def test_tag_update_absent_vs_null_color():
+    absent = TagUpdateIn()
+    assert "color" not in absent.model_fields_set  # untouched on PATCH
+
+    cleared = TagUpdateIn(color=None)
+    assert "color" in cleared.model_fields_set  # an explicit null CLEARS it
+    assert cleared.color is None

From 81d21fdeac7f298649a810b9bc2721758ac8a85a Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 26 Jul 2026 05:39:32 +0200
Subject: [PATCH 12/18] fix(api): accept fractional progress seconds (R6 S1b
 code-review round 1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

/code-review high round 1 on S1b — 5 findings, 1 fixed, 4 by-design/deferred:
- FIXED: VideoProgressIn / ItemProgressIn position_seconds & duration_seconds
  typed `int` would 422 a raw float currentTime on the 10s progress checkpoint
  (the old `int(payload.get(...))` truncated it). Back to `float`, truncated in
  the handler; +test. The live frontend floors so this was latent, not live.
By-design / deferred (no change): the 422 detail-array isn't localized by the FE
(filed under R7); PATCH is-not-none (channels/quota, null-safe) vs model_fields_set
(nullable-clear) is a deliberate split; missing-field→422 is the point of the epic;
me/switch_account's numeric-string coercion is more correct and still session-gated.

Gate: ruff clean, pytest 172 green.
---
 backend/app/routes/feed.py           | 11 +++++++----
 backend/app/routes/plex.py           | 10 ++++++----
 backend/tests/test_request_models.py | 10 ++++++++++
 3 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/backend/app/routes/feed.py b/backend/app/routes/feed.py
index 100e296..89d0367 100644
--- a/backend/app/routes/feed.py
+++ b/backend/app/routes/feed.py
@@ -659,8 +659,11 @@ def clear_video_state(
 
 
 class VideoProgressIn(BaseModel):
-    position_seconds: int = 0
-    duration_seconds: int = 0
+    # Accept a float and truncate (below) — the player may post a raw currentTime (a float), which
+    # the old `int(payload.get(...))` silently truncated. A plain `int` field would 422 that on the
+    # 10s progress hot path, losing the resume position; `float` keeps the old tolerance.
+    position_seconds: float = 0
+    duration_seconds: float = 0
 
 
 @router.post("/videos/{video_id}/progress")
@@ -674,8 +677,8 @@ def set_video_progress(
     Stores a per-user position on the video_states row without touching watch status, so a
     partially-watched video can render a progress bar and match the "in progress" filter.
     Trivially-early and near-finished positions clear the position rather than store it."""
-    position = body.position_seconds
-    duration = body.duration_seconds
+    position = int(body.position_seconds)
+    duration = int(body.duration_seconds)
     if position < 0:
         position = 0
 
diff --git a/backend/app/routes/plex.py b/backend/app/routes/plex.py
index 2cb148a..8c67e0e 100644
--- a/backend/app/routes/plex.py
+++ b/backend/app/routes/plex.py
@@ -1943,8 +1943,10 @@ def _push_watch(
 
 
 class ItemProgressIn(BaseModel):
-    position_seconds: int = 0
-    duration_seconds: int = 0
+    # float, truncated in the handler — the player may post a raw currentTime (a float); a plain
+    # `int` field would 422 it on the periodic progress checkpoint (the old `int(...)` truncated).
+    position_seconds: float = 0
+    duration_seconds: float = 0
     final: bool = False
 
 
@@ -1962,8 +1964,8 @@ def item_progress(
     debounces the Plex resume push: we mirror the settled position to Plex only on a final flush, so
     a single watch doesn't spray `/:/timeline` calls at the server every 10 seconds."""
     it = _item_or_404(db, rating_key)
-    position = max(0, body.position_seconds)
-    duration = body.duration_seconds
+    position = max(0, int(body.position_seconds))
+    duration = int(body.duration_seconds)
     final = body.final
     now = datetime.now(timezone.utc)
     st = db.query(PlexState).filter_by(user_id=user.id, item_id=it.id).first()
diff --git a/backend/tests/test_request_models.py b/backend/tests/test_request_models.py
index f45f73c..5819de0 100644
--- a/backend/tests/test_request_models.py
+++ b/backend/tests/test_request_models.py
@@ -6,6 +6,7 @@ from pydantic import ValidationError
 
 from app.routes.channels import AttachTagIn, ChannelUpdateIn
 from app.routes.downloads import AdminSetQuotaIn
+from app.routes.feed import VideoProgressIn
 from app.routes.setup import SetupAdminIn
 from app.routes.tags import TagUpdateIn
 
@@ -46,6 +47,15 @@ def test_admin_quota_rejects_non_numeric_limit():
         AdminSetQuotaIn(max_bytes="lots")
 
 
+def test_progress_accepts_fractional_seconds():
+    # The player may post a raw currentTime (a float). The field must accept it (truncated in the
+    # handler) — a plain `int` field would 422 on the progress hot path. (code-review round 1.)
+    assert VideoProgressIn(position_seconds=12.7).position_seconds == 12.7
+    assert int(VideoProgressIn(position_seconds=12.7).position_seconds) == 12
+    with pytest.raises(ValidationError):
+        VideoProgressIn(position_seconds="not-a-number")
+
+
 # --- PATCH models: model_fields_set separates "absent" from "explicit null". ---
 
 def test_tag_update_absent_vs_null_color():

From 4b6bc54aa84d062d18e537d7a1431c7e23f1c39a Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 26 Jul 2026 13:47:07 +0200
Subject: [PATCH 13/18] test(db): stand up the DB-backed pytest lane (R6 S3b)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The suite was pure-logic only (R2 S2b deferred the DB lane). Add an opt-in `db`
fixture (tests/conftest.py) that hands a test a real session against an ephemeral
Postgres; schema is built with `alembic upgrade head` (the real prod schema needs
the unaccent extension + unaccent_simple TS config that create_all can't provide,
and this also proves the migration chain applies). Each test starts from a TRUNCATEd
clean DB so tests that COMMIT — the whole point, for R6 S2's transaction work —
don't leak.

backend/docker-compose.test.yml wires an ephemeral tmpfs pg + the test image. When
no Postgres is reachable (a plain `docker run`), the DB tests SKIP and the pure-logic
lane is unchanged: 172 passed, 2 skipped. With the DB: 174 passed.

test_db_lane.py smoke-proves commit round-trip + TRUNCATE isolation. The gate wiring
(siftlode.sh) lands in the ops repo.
---
 backend/docker-compose.test.yml | 35 ++++++++++++++++++
 backend/tests/conftest.py       | 65 +++++++++++++++++++++++++++++++++
 backend/tests/test_db_lane.py   | 21 +++++++++++
 3 files changed, 121 insertions(+)
 create mode 100644 backend/docker-compose.test.yml
 create mode 100644 backend/tests/conftest.py
 create mode 100644 backend/tests/test_db_lane.py

diff --git a/backend/docker-compose.test.yml b/backend/docker-compose.test.yml
new file mode 100644
index 0000000..7a14082
--- /dev/null
+++ b/backend/docker-compose.test.yml
@@ -0,0 +1,35 @@
+# DB-backed pytest lane (R6 S3b): an ephemeral Postgres + the test image, wired together so the
+# `db` fixture (tests/conftest.py) has a real database. The whole thing is throwaway — the pg data
+# lives in tmpfs (RAM) and nothing is persisted. The pure-logic lane still runs WITHOUT this file
+# (plain `docker run … python -m pytest` — DB tests skip when no Postgres is reachable).
+#
+#   docker compose -f backend/docker-compose.test.yml up --build --abort-on-container-exit \
+#     --exit-code-from test
+#   docker compose -f backend/docker-compose.test.yml down -v
+services:
+  testdb:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: siftlode
+      POSTGRES_PASSWORD: siftlode
+      POSTGRES_DB: siftlode_test
+    tmpfs:
+      - /var/lib/postgresql/data  # ephemeral + fast; the schema is rebuilt per run
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U siftlode -d siftlode_test"]
+      interval: 1s
+      timeout: 3s
+      retries: 30
+  test:
+    build:
+      context: .
+      dockerfile: Dockerfile.test
+    depends_on:
+      testdb:
+        condition: service_healthy
+    environment:
+      DATABASE_URL: postgresql+psycopg://siftlode:siftlode@testdb:5432/siftlode_test
+    volumes:
+      - ./:/app
+    working_dir: /app
+    command: python -m pytest
diff --git a/backend/tests/conftest.py b/backend/tests/conftest.py
new file mode 100644
index 0000000..c9518a4
--- /dev/null
+++ b/backend/tests/conftest.py
@@ -0,0 +1,65 @@
+"""Pytest fixtures for the DB-backed integration lane (R6 S3b).
+
+The bulk of the suite is pure-logic and needs no database. This adds an OPT-IN `db` fixture
+that hands a test a real session against a throwaway Postgres (the app's own engine, bound to
+the test `DATABASE_URL`). When no database is reachable — the default `siftlode check` still
+runs the pure-logic tests with no Postgres — any test that asks for `db` is SKIPPED, so the
+pure-logic lane is unaffected.
+
+Schema comes from `alembic upgrade head` — not `create_all` — because the real schema depends on
+things only migrations set up (the `unaccent` extension + the `public.unaccent_simple` text-search
+config the videos.search_vector generated column needs). Building it via migrations also validates
+that the migration chain applies cleanly. Each test then gets a clean database via TRUNCATE so
+tests that COMMIT (the whole point of this lane — transaction-ownership behaviour) don't leak.
+"""
+import pytest
+from alembic import command
+from alembic.config import Config
+from sqlalchemy import text
+
+import app.models  # noqa: F401 — register every model on Base.metadata
+from app.db import Base, SessionLocal, engine
+
+
+def _db_reachable() -> bool:
+    try:
+        with engine.connect() as conn:
+            conn.execute(text("SELECT 1"))
+        return True
+    except Exception:
+        return False
+
+
+_DB_REACHABLE = _db_reachable()
+
+
+@pytest.fixture(scope="session")
+def _schema():
+    if not _DB_REACHABLE:
+        pytest.skip("no test database (set DATABASE_URL to a reachable Postgres)")
+    # Build the real prod schema via migrations (alembic env.py reads settings.database_url, i.e.
+    # the test DATABASE_URL). Idempotent — a re-run against an already-migrated DB is a no-op.
+    command.upgrade(Config("alembic.ini"), "head")
+    yield
+
+
+def _truncate_all():
+    # RESTART IDENTITY so serial PKs are deterministic per test; CASCADE handles FKs. Truncating
+    # BEFORE each test (not after) means every test — including the first, which would otherwise see
+    # migration-seeded rows — starts from the same empty slate and seeds only what it needs.
+    tables = ", ".join(t.name for t in Base.metadata.sorted_tables)
+    with engine.begin() as conn:
+        conn.execute(text(f"TRUNCATE {tables} RESTART IDENTITY CASCADE"))
+
+
+@pytest.fixture
+def db(_schema):
+    """A real session against the test Postgres, on a clean (empty) database. The code under test
+    may commit freely."""
+    _truncate_all()
+    session = SessionLocal()
+    try:
+        yield session
+    finally:
+        session.rollback()
+        session.close()
diff --git a/backend/tests/test_db_lane.py b/backend/tests/test_db_lane.py
new file mode 100644
index 0000000..59fec98
--- /dev/null
+++ b/backend/tests/test_db_lane.py
@@ -0,0 +1,21 @@
+"""Smoke test proving the DB-backed lane works (R6 S3b): a real commit round-trips, and each
+test starts from a clean database (TRUNCATE isolation), which is what lets the transaction-
+ownership tests (R6 S2) trust what they commit."""
+from sqlalchemy import func, select
+
+from app.models import User
+
+
+def test_commit_roundtrips(db):
+    db.add(User(email="lane@example.com", role="admin"))
+    db.commit()
+
+    got = db.execute(select(User).where(User.email == "lane@example.com")).scalar_one()
+    assert got.id is not None
+    assert got.role == "admin"
+    assert got.is_active is True  # server_default applied on flush/commit
+
+
+def test_isolation_starts_clean(db):
+    # If the previous test's committed row leaked, this count would be 1 — TRUNCATE must reset it.
+    assert db.scalar(select(func.count()).select_from(User)) == 0

From 39f726a5e63b70d55f0e1b865f583a8504257e39 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 26 Jul 2026 13:54:42 +0200
Subject: [PATCH 14/18] test(db): /facets regression + S3a jsonb-null
 normalization (R6 S3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

First real customers of the DB lane:
- test_plex_facets: GET /api/plex/facets?scope=show returns 200 (not the
  "cannot extract elements from a scalar" 500) for a show whose genres is a JSONB
  scalar `null` — the 0.53.1 read-guard's regression test. Mutation-checked:
  removing the jsonb_typeof='array' guard turns it red with that exact error.
- migration 0060 (S3a): one-time UPDATE …=NULL WHERE jsonb_typeof=… 'null' over the
  plex_items/plex_shows tag columns, so pre-0.53.1 JSONB-null rows become uniform SQL
  NULL and the read-guards go belt-only. test_plex_jsonb_normalize verifies scalar-null
  → SQL NULL while a real array is preserved.

Gate: ruff clean; DB lane 176 passed; pure-logic lane unchanged (skips the DB tests).
---
 .../0060_plex_jsonb_null_normalize.py         | 34 ++++++++++++++
 backend/tests/test_plex_facets.py             | 45 +++++++++++++++++++
 backend/tests/test_plex_jsonb_normalize.py    | 44 ++++++++++++++++++
 3 files changed, 123 insertions(+)
 create mode 100644 backend/alembic/versions/0060_plex_jsonb_null_normalize.py
 create mode 100644 backend/tests/test_plex_facets.py
 create mode 100644 backend/tests/test_plex_jsonb_normalize.py

diff --git a/backend/alembic/versions/0060_plex_jsonb_null_normalize.py b/backend/alembic/versions/0060_plex_jsonb_null_normalize.py
new file mode 100644
index 0000000..b87e99e
--- /dev/null
+++ b/backend/alembic/versions/0060_plex_jsonb_null_normalize.py
@@ -0,0 +1,34 @@
+"""normalize plex JSONB tag columns: scalar `null` -> SQL NULL (R6 S3a)
+
+Pre-0.53.1 rows persisted a genre-less show/movie's genres/directors/cast_names/collection_keys as
+a JSONB scalar `null` (SQLAlchemy wrote a Python None as JSON null before none_as_null=True). The
+0.53.1 hotfix added none_as_null=True (new writes are SQL NULL) + jsonb_typeof read-guards, but the
+existing rows stayed JSON `null`, which kept those read-guards load-bearing rather than belt-only.
+
+This one-time data fixup rewrites those scalars to SQL NULL so the columns are uniform. Data-only,
+forward-only: a SQL NULL is indistinguishable from the old JSON `null` to every reader (the guards
+treat both as "not an array"), so there is nothing meaningful to downgrade. No schema change.
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+revision: str = "0060_plex_jsonb_null_normalize"
+down_revision: Union[str, None] = "0059_dl_link_pw_version"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+_TABLES = ("plex_items", "plex_shows")
+_COLS = ("genres", "directors", "cast_names", "collection_keys")
+
+
+def upgrade() -> None:
+    for table in _TABLES:
+        for col in _COLS:
+            op.execute(
+                f"UPDATE {table} SET {col} = NULL WHERE jsonb_typeof({col}) = 'null'"
+            )
+
+
+def downgrade() -> None:
+    pass  # forward-only: SQL NULL == the old JSON null for every reader
diff --git a/backend/tests/test_plex_facets.py b/backend/tests/test_plex_facets.py
new file mode 100644
index 0000000..a8eae42
--- /dev/null
+++ b/backend/tests/test_plex_facets.py
@@ -0,0 +1,45 @@
+"""DB-backed regression for the 0.53.1 hotfix (R6 S3b-test): GET /api/plex/facets?scope=show
+must return 200 — not the "cannot extract elements from a scalar" 500 — for a metadata-poor
+library whose show has a JSONB-scalar `null` genres (a pre-0.53.1 row). The endpoint's
+`jsonb_typeof(genres)='array'` read-guard is what makes it safe; this test would 500 without it.
+
+Uses the DB lane (`db` fixture) — skipped when no Postgres is reachable.
+"""
+from fastapi.testclient import TestClient
+from sqlalchemy import text
+
+import app.state as state
+from app.auth import current_user
+from app.db import get_db
+from app.main import app
+from app.models import PlexLibrary, PlexShow, User
+
+
+def test_facets_survives_json_null_genres(db):
+    lib = PlexLibrary(plex_key="1", title="Shows", kind="show", enabled=True)
+    db.add(lib)
+    db.flush()
+    db.add(PlexShow(rating_key="s1", library_id=lib.id, title="No Genre Show"))
+    user = User(email="facets@example.com")
+    db.add(user)
+    # The request gate 503s an unconfigured instance; mark this throwaway DB configured.
+    state.mark_configured(db)
+    db.commit()
+    # Simulate a pre-0.53.1 row: genres persisted as a JSONB scalar `null` (what SQLAlchemy wrote
+    # before none_as_null=True), NOT SQL NULL — this is the value jsonb_array_elements_text() chokes
+    # on. A Python None now maps to SQL NULL, so we set the scalar directly.
+    db.execute(text("UPDATE plex_shows SET genres = 'null'::jsonb WHERE rating_key = 's1'"))
+    db.commit()
+
+    app.dependency_overrides[get_db] = lambda: db
+    app.dependency_overrides[current_user] = lambda: user
+    try:
+        client = TestClient(app)  # no context-manager: skip lifespan (scheduler/HLS sweep)
+        resp = client.get("/api/plex/facets?scope=show")
+    finally:
+        app.dependency_overrides.clear()
+        state._configured_cache = False  # one-way process cache — don't leak "configured" to other tests
+
+    assert resp.status_code == 200, resp.text
+    # The scalar-null show contributes no genres — and, crucially, doesn't abort the whole endpoint.
+    assert resp.json()["genres"] == []
diff --git a/backend/tests/test_plex_jsonb_normalize.py b/backend/tests/test_plex_jsonb_normalize.py
new file mode 100644
index 0000000..b709635
--- /dev/null
+++ b/backend/tests/test_plex_jsonb_normalize.py
@@ -0,0 +1,44 @@
+"""DB-backed test for the S3a data normalization (migration 0060): a JSONB scalar `null` in the
+plex tag columns becomes SQL NULL, while a real array is left untouched. Runs the migration's exact
+UPDATE statements against seeded rows (the migration itself is a no-op in the empty test DB).
+
+Uses the DB lane (`db` fixture) — skipped when no Postgres is reachable.
+"""
+from sqlalchemy import text
+
+from app.models import PlexLibrary, PlexShow
+
+# Mirror of migration 0060's statements (plex_items runs against an empty table here — proving the
+# SQL is valid for both tables; the assertions below check the seeded plex_shows rows).
+_NORMALIZE = [
+    f"UPDATE {t} SET {c} = NULL WHERE jsonb_typeof({c}) = 'null'"
+    for t in ("plex_items", "plex_shows")
+    for c in ("genres", "directors", "cast_names", "collection_keys")
+]
+
+
+def test_scalar_null_normalized_array_preserved(db):
+    lib = PlexLibrary(plex_key="1", title="Shows", kind="show", enabled=True)
+    db.add(lib)
+    db.flush()
+    db.add_all(
+        [
+            PlexShow(rating_key="null_row", library_id=lib.id, title="Null genres"),
+            PlexShow(rating_key="array_row", library_id=lib.id, title="Real genres"),
+        ]
+    )
+    db.commit()
+    # Set a pre-0.53.1 JSONB scalar null on one, a genuine array on the other.
+    db.execute(text("UPDATE plex_shows SET genres = 'null'::jsonb WHERE rating_key = 'null_row'"))
+    db.execute(text("""UPDATE plex_shows SET genres = '["Drama"]'::jsonb WHERE rating_key = 'array_row'"""))
+    db.commit()
+    assert db.scalar(text("SELECT jsonb_typeof(genres) FROM plex_shows WHERE rating_key='null_row'")) == "null"
+
+    for stmt in _NORMALIZE:
+        db.execute(text(stmt))
+    db.commit()
+
+    # The scalar null is now SQL NULL (jsonb_typeof of SQL NULL is itself NULL, not 'null')...
+    assert db.scalar(text("SELECT genres IS NULL FROM plex_shows WHERE rating_key='null_row'")) is True
+    # ...and a real array is untouched.
+    assert db.scalar(text("SELECT jsonb_typeof(genres) FROM plex_shows WHERE rating_key='array_row'")) == "array"

From 921c2bf5a43f5f8373ac47de42f300ed5eb86de2 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 26 Jul 2026 15:09:25 +0200
Subject: [PATCH 15/18] test(db): harden the DB lane per code-review (R6 S3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

/code-review high on S3 — 3 low findings, 2 fixed, 1 no-change:
- _db_reachable() now probes via a throwaway engine with connect_timeout=3, so a
  slow/firewalled DATABASE_URL can't hang the whole suite at import (the app engine
  has no connect timeout).
- test_plex_facets sets the "configured" gate flag via monkeypatch (auto-restored)
  instead of poking state._configured_cache in a manual finally — no leak risk, and
  the now-unnecessary mark_configured DB write is dropped.
No change: test_plex_jsonb_normalize copying migration 0060's SQL is deliberate —
migrations must stay self-contained (no app imports) and a shipped migration is
immutable, so there's no real drift to guard against.

Gate: ruff clean; DB lane 176 passed; pure-logic 172 passed / 4 skipped (fast).
---
 backend/tests/conftest.py         | 11 +++++++++--
 backend/tests/test_plex_facets.py |  8 ++++----
 2 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/backend/tests/conftest.py b/backend/tests/conftest.py
index c9518a4..8fa4ec8 100644
--- a/backend/tests/conftest.py
+++ b/backend/tests/conftest.py
@@ -15,19 +15,26 @@ tests that COMMIT (the whole point of this lane — transaction-ownership behavi
 import pytest
 from alembic import command
 from alembic.config import Config
-from sqlalchemy import text
+from sqlalchemy import create_engine, text
 
 import app.models  # noqa: F401 — register every model on Base.metadata
+from app.config import settings
 from app.db import Base, SessionLocal, engine
 
 
 def _db_reachable() -> bool:
+    # A throwaway engine with a bounded connect_timeout so a slow/firewalled DATABASE_URL can't
+    # hang the whole suite at import (the app engine has no connect timeout). The compose lane
+    # gates on `service_healthy`, but this keeps a manual run honest too.
+    probe = create_engine(settings.database_url, connect_args={"connect_timeout": 3})
     try:
-        with engine.connect() as conn:
+        with probe.connect() as conn:
             conn.execute(text("SELECT 1"))
         return True
     except Exception:
         return False
+    finally:
+        probe.dispose()
 
 
 _DB_REACHABLE = _db_reachable()
diff --git a/backend/tests/test_plex_facets.py b/backend/tests/test_plex_facets.py
index a8eae42..fe8198b 100644
--- a/backend/tests/test_plex_facets.py
+++ b/backend/tests/test_plex_facets.py
@@ -15,16 +15,17 @@ from app.main import app
 from app.models import PlexLibrary, PlexShow, User
 
 
-def test_facets_survives_json_null_genres(db):
+def test_facets_survives_json_null_genres(db, monkeypatch):
     lib = PlexLibrary(plex_key="1", title="Shows", kind="show", enabled=True)
     db.add(lib)
     db.flush()
     db.add(PlexShow(rating_key="s1", library_id=lib.id, title="No Genre Show"))
     user = User(email="facets@example.com")
     db.add(user)
-    # The request gate 503s an unconfigured instance; mark this throwaway DB configured.
-    state.mark_configured(db)
     db.commit()
+    # The request gate 503s an unconfigured instance; flip the process-level "configured" flag the
+    # gate reads. monkeypatch auto-restores it, so it can't leak "configured" into another test.
+    monkeypatch.setattr(state, "_configured_cache", True)
     # Simulate a pre-0.53.1 row: genres persisted as a JSONB scalar `null` (what SQLAlchemy wrote
     # before none_as_null=True), NOT SQL NULL — this is the value jsonb_array_elements_text() chokes
     # on. A Python None now maps to SQL NULL, so we set the scalar directly.
@@ -38,7 +39,6 @@ def test_facets_survives_json_null_genres(db):
         resp = client.get("/api/plex/facets?scope=show")
     finally:
         app.dependency_overrides.clear()
-        state._configured_cache = False  # one-way process cache — don't leak "configured" to other tests
 
     assert resp.status_code == 200, resp.text
     # The scalar-null show contributes no genres — and, crucially, doesn't abort the whole endpoint.

From 5809f3e431d1a7d422fd8e14cdb28cc38f433b4c Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 26 Jul 2026 15:32:46 +0200
Subject: [PATCH 16/18] refactor(quota): own the quota session; Plex
 per-section commit (R6 S2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Transaction ownership (C-A5):
- quota.record_usage / log_action write in their OWN SessionLocal(), committed
  immediately, and no longer take/commit the caller's db. The spend stays DURABLE
  regardless of the caller (read-only YouTube paths never commit; a failed job rolls
  back) — under-counting the shared daily budget would risk overspending the real
  YouTube quota — AND quota stops flushing a job's partial state mid-run behind its
  own `except: db.rollback()`. units_used_today switches to a scalar SELECT so
  measured()'s before/after diff sees the separate session's commits (READ COMMITTED).
  Call sites updated (youtube/client.py ×3, routes/search.py ×1).
- plex sync commits PER SECTION (moved the end-of-loop commit inside), so a PlexError
  on a later library keeps the ones already mirrored (idempotent; next run reconciles).

The sync jobs did NOT rely on record_usage's incidental commit for persistence — their
per-item functions (apply_rss_feed, backfill_channel_recent, import_subscriptions,
sync_user_playlists, apply_channel_autotags) all commit internally, so the in-loop
rollback handlers already isolate a failed item. No loop restructuring needed.

DB-lane tests (test_quota_ownership, 4): spend survives a caller rollback while the
caller's uncommitted row does NOT leak; accumulation; measured-style mid-txn read.
Gate: ruff clean; DB lane 180 green.
---
 backend/app/plex/sync.py              |  5 ++-
 backend/app/quota.py                  | 46 ++++++++++++++-------
 backend/app/routes/search.py          |  2 +-
 backend/app/youtube/client.py         |  6 +--
 backend/tests/test_quota_ownership.py | 57 +++++++++++++++++++++++++++
 5 files changed, 97 insertions(+), 19 deletions(-)
 create mode 100644 backend/tests/test_quota_ownership.py

diff --git a/backend/app/plex/sync.py b/backend/app/plex/sync.py
index 058349d..f1b9e82 100644
--- a/backend/app/plex/sync.py
+++ b/backend/app/plex/sync.py
@@ -129,7 +129,10 @@ def sync(db: Session) -> dict:
                 else:
                     _sync_shows(db, plex, lib, stats)
                 _sync_collections(db, plex, lib, stats)
-            db.commit()
+                # Commit each section as it completes: a PlexError on a LATER section then keeps the
+                # libraries already mirrored (idempotent — the next run reconciles the rest), instead
+                # of the old single end-of-loop commit that a late failure rolled back entirely.
+                db.commit()
             # Rich-fetch a bounded batch of not-yet-enriched titles' FULL cast, so the whole library
             # becomes filterable over successive runs (the cheap listing above only stored the top ~3).
             try:
diff --git a/backend/app/quota.py b/backend/app/quota.py
index 0e44839..25772c7 100644
--- a/backend/app/quota.py
+++ b/backend/app/quota.py
@@ -9,10 +9,12 @@ import contextvars
 from datetime import datetime, timezone
 from zoneinfo import ZoneInfo
 
+from sqlalchemy import func, select
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session
 
 from app import sysconfig
+from app.db import SessionLocal
 from app.models import ApiQuotaUsage, QuotaEvent
 
 _PACIFIC = ZoneInfo("America/Los_Angeles")
@@ -99,8 +101,13 @@ def pacific_day_start_utc() -> datetime:
 
 
 def units_used_today(db: Session) -> int:
-    row = db.get(ApiQuotaUsage, pacific_today())
-    return row.units_used if row else 0
+    # A scalar SELECT (not db.get) so it bypasses the caller session's identity map — quota writes
+    # commit in a SEPARATE session (see record_usage), and a cached ORM row would otherwise hide
+    # their effect from a caller that already loaded today's row (measured()'s before/after diff).
+    # Under READ COMMITTED a fresh SELECT sees the other session's committed writes.
+    return db.scalar(
+        select(ApiQuotaUsage.units_used).where(ApiQuotaUsage.day == pacific_today())
+    ) or 0
 
 
 def remaining_today(db: Session) -> int:
@@ -111,21 +118,24 @@ def can_spend(db: Session, units: int) -> bool:
     return remaining_today(db) >= units
 
 
-def log_action(db: Session, user_id: int, action: str) -> None:
+def log_action(user_id: int, action: str) -> None:
     """Record a zero-cost action event so per-user daily caps still count it.
 
     `record_usage` only logs when units are actually charged; a scrape-based search spends no
-    quota yet must still be rate-limited per user, so it logs its event here directly."""
-    db.add(QuotaEvent(user_id=user_id, action=action, units=0))
-    db.commit()
+    quota yet must still be rate-limited per user, so it logs its event here directly.
+
+    Writes in its OWN session (like record_usage) — quota accounting is durable independent of the
+    caller's transaction and must never commit the caller's session (that would flush a job's
+    partial state mid-run, defeating its own rollback). See [[quota-owns-its-session]]."""
+    with SessionLocal() as qs:
+        qs.add(QuotaEvent(user_id=user_id, action=action, units=0))
+        qs.commit()
 
 
 def actions_today(db: Session, user_id: int, action: str) -> int:
     """How many quota events of `action` this user has logged so far in the current Pacific
     day — for per-user, per-action daily caps (e.g. the live-search limit). Counts events,
     not units, so it only works for actions charged exactly once per user action."""
-    from sqlalchemy import func, select  # local import: keep the module's import head lean
-
     return (
         db.scalar(
             select(func.count())
@@ -140,8 +150,15 @@ def actions_today(db: Session, user_id: int, action: str) -> int:
     )
 
 
-def record_usage(db: Session, units: int) -> None:
-    """Atomically add `units` to today's counter (upsert) and log an attribution event."""
+def record_usage(units: int) -> None:
+    """Atomically add `units` to today's counter (upsert) and log an attribution event.
+
+    Uses its OWN session, committed immediately, so the spend is DURABLE regardless of what the
+    calling job does next: the units were really consumed at YouTube, so a caller that later rolls
+    back (or is read-only and never commits) must NOT lose the record — under-counting the shared
+    daily budget risks overspending the real API quota. Equally, quota must never commit the
+    CALLER's session (the old behaviour) — that persisted a job's partial state mid-run behind its
+    own `except: db.rollback()`. See [[quota-owns-its-session]]."""
     if units <= 0:
         return
     day = pacific_today()
@@ -153,7 +170,8 @@ def record_usage(db: Session, units: int) -> None:
             set_={"units_used": ApiQuotaUsage.units_used + units},
         )
     )
-    db.execute(stmt)
-    # Audit detail: who/what spent it (per-user attribution; NULL actor = system).
-    db.add(QuotaEvent(user_id=_actor_id.get(), action=_action.get(), units=units))
-    db.commit()
+    with SessionLocal() as qs:
+        qs.execute(stmt)
+        # Audit detail: who/what spent it (per-user attribution; NULL actor = system).
+        qs.add(QuotaEvent(user_id=_actor_id.get(), action=_action.get(), units=units))
+        qs.commit()
diff --git a/backend/app/routes/search.py b/backend/app/routes/search.py
index 375664b..7f4809a 100644
--- a/backend/app/routes/search.py
+++ b/backend/app/routes/search.py
@@ -290,7 +290,7 @@ def search_youtube(
     # at least one page (a total failure raises 502 above and never reaches this), keeps the cap
     # counting user searches instead of internal continuation pages.
     if source != "api":
-        quota.log_action(db, user.id, quota.QuotaAction.VIDEOS_SEARCH)
+        quota.log_action(user.id, quota.QuotaAction.VIDEOS_SEARCH)
 
     ordered = collected[:limit]
 
diff --git a/backend/app/youtube/client.py b/backend/app/youtube/client.py
index c52dfb0..0ccf64a 100644
--- a/backend/app/youtube/client.py
+++ b/backend/app/youtube/client.py
@@ -113,7 +113,7 @@ class YouTubeClient:
         else:
             headers["Authorization"] = f"Bearer {self._access_token()}"
         resp = self._send("GET", f"{API_BASE}/{path}", params=p, headers=headers)
-        quota.record_usage(self.db, cost)
+        quota.record_usage(cost)
         if resp.status_code != 200:
             log.warning("YouTube API %s -> %s: %s", path, resp.status_code, resp.text[:200])
             raise YouTubeError(f"GET {path} -> {resp.status_code}: {resp.text[:300]}")
@@ -239,7 +239,7 @@ class YouTubeClient:
             params={"id": subscription_id},
             headers={"Authorization": f"Bearer {self._access_token()}"},
         )
-        quota.record_usage(self.db, 50)
+        quota.record_usage(50)
         if resp.status_code not in (200, 204):
             log.warning(
                 "YouTube subscriptions.delete -> %s: %s",
@@ -282,7 +282,7 @@ class YouTubeClient:
         resp = self._send(
             method, f"{API_BASE}/{path}", params=params, json=json, headers=headers
         )
-        quota.record_usage(self.db, 50)
+        quota.record_usage(50)
         if resp.status_code not in (200, 204):
             log.warning("YouTube %s %s -> %s: %s", method, path, resp.status_code, resp.text[:200])
             raise YouTubeError(f"{method} {path} -> {resp.status_code}: {resp.text[:300]}")
diff --git a/backend/tests/test_quota_ownership.py b/backend/tests/test_quota_ownership.py
new file mode 100644
index 0000000..fd7138e
--- /dev/null
+++ b/backend/tests/test_quota_ownership.py
@@ -0,0 +1,57 @@
+"""DB-backed tests for R6 S2 quota transaction ownership: quota accounting writes in its OWN
+session, so a spend is DURABLE even when the calling job rolls back (the units were really consumed
+at YouTube), and it NEVER commits the caller's session (the old behaviour flushed a job's partial
+state mid-run behind its own rollback). Uses the DB lane (`db` fixture) — skipped without Postgres.
+"""
+from sqlalchemy import func, select
+
+from app import quota
+from app.models import QuotaEvent, User
+
+
+def test_record_usage_survives_caller_rollback_and_leaves_caller_uncommitted(db):
+    # The caller has uncommitted work of its own; then a YouTube call spends quota; then the caller
+    # rolls back (a failed job).
+    db.add(User(email="pending@example.com"))  # caller's own, never committed
+    quota.record_usage(10)                      # dedicated session — commits independently
+    db.rollback()                               # the job fails and rolls back
+
+    # Quota spend PERSISTED (real units were consumed) — the guard stays accurate ...
+    assert quota.units_used_today(db) == 10
+    assert db.scalar(select(func.count()).select_from(QuotaEvent)) == 1
+    # ... but the caller's own partial work did NOT leak (quota never committed the caller's session).
+    assert db.scalar(select(func.count()).select_from(User).where(User.email == "pending@example.com")) == 0
+
+
+def test_record_usage_accumulates(db):
+    quota.record_usage(10)
+    quota.record_usage(5)
+    assert quota.units_used_today(db) == 15  # atomic upsert: +10 then +5
+
+
+def test_reads_see_separate_session_spend_mid_transaction(db):
+    # Mimics measured()'s before/after diff: a read, a spend (in quota's SEPARATE session), a read.
+    # The second read must reflect the spend even though the caller's own transaction is still open —
+    # units_used_today is a scalar SELECT (READ COMMITTED sees other sessions' commits), NOT a cached
+    # ORM row that db.get would return stale.
+    before = quota.units_used_today(db)
+    quota.record_usage(7)
+    after = quota.units_used_today(db)
+    assert after - before == 7
+
+
+def test_log_action_survives_caller_rollback(db):
+    user = User(email="searcher@example.com")
+    db.add(user)
+    db.commit()  # a committed user to attribute the (free) action to
+    db.add(User(email="pending@example.com"))  # uncommitted caller work
+    quota.log_action(user.id, quota.QuotaAction.VIDEOS_SEARCH)
+    db.rollback()
+
+    # The zero-cost action event survived (per-user daily caps must still count it) ...
+    events = db.execute(select(QuotaEvent)).scalars().all()
+    assert len(events) == 1
+    assert events[0].user_id == user.id
+    assert events[0].units == 0
+    # ... and the caller's uncommitted user is gone.
+    assert db.scalar(select(func.count()).select_from(User)) == 1

From 351eb5fd130090a34ee72bca6b7c92b82691ccd4 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 26 Jul 2026 19:08:29 +0200
Subject: [PATCH 17/18] test(plex)+cleanup(quota): S2 code-review fixes (R6 S2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

/code-review high on S2 — 4 findings, 2 fixed, 2 no-change:
- test_plex_sync_txn: a faked PlexClient fails on the second library; asserts the
  first library's row survives (per-section commit). Mutation-checked — moving the
  commit back out of the loop turns it red ([] == ['1']).
- dropped the `[[quota-owns-its-session]]` memory slugs from quota.py docstrings
  (a dangling private-note reference in shipped code; the reasoning is already inline).
No change: record_usage's per-call second connection is a transient spike, fine for
this app's concurrency; the two-site `with SessionLocal()` duplication isn't worth a
helper until a third caller appears.

Gate: ruff clean; DB lane 181 green.
---
 backend/app/quota.py                |  4 +--
 backend/tests/test_plex_sync_txn.py | 44 +++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+), 2 deletions(-)
 create mode 100644 backend/tests/test_plex_sync_txn.py

diff --git a/backend/app/quota.py b/backend/app/quota.py
index 25772c7..9d31750 100644
--- a/backend/app/quota.py
+++ b/backend/app/quota.py
@@ -126,7 +126,7 @@ def log_action(user_id: int, action: str) -> None:
 
     Writes in its OWN session (like record_usage) — quota accounting is durable independent of the
     caller's transaction and must never commit the caller's session (that would flush a job's
-    partial state mid-run, defeating its own rollback). See [[quota-owns-its-session]]."""
+    partial state mid-run, defeating its own rollback)."""
     with SessionLocal() as qs:
         qs.add(QuotaEvent(user_id=user_id, action=action, units=0))
         qs.commit()
@@ -158,7 +158,7 @@ def record_usage(units: int) -> None:
     back (or is read-only and never commits) must NOT lose the record — under-counting the shared
     daily budget risks overspending the real API quota. Equally, quota must never commit the
     CALLER's session (the old behaviour) — that persisted a job's partial state mid-run behind its
-    own `except: db.rollback()`. See [[quota-owns-its-session]]."""
+    own `except: db.rollback()`."""
     if units <= 0:
         return
     day = pacific_today()
diff --git a/backend/tests/test_plex_sync_txn.py b/backend/tests/test_plex_sync_txn.py
new file mode 100644
index 0000000..0512a8c
--- /dev/null
+++ b/backend/tests/test_plex_sync_txn.py
@@ -0,0 +1,44 @@
+"""DB-backed test for R6 S2's Plex per-section commit: a PlexError on a LATER library must keep the
+libraries already mirrored (committed per section), not roll the whole reconcile back. Uses the DB
+lane (`db` fixture) with a faked PlexClient — skipped without Postgres.
+"""
+from sqlalchemy import select
+
+from app.plex import sync
+from app.plex.client import PlexError
+from app.models import PlexLibrary
+
+
+class _FakePlex:
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False  # don't suppress the PlexError
+
+    def sections(self):
+        return [
+            {"type": "movie", "key": "1", "title": "Lib One"},
+            {"type": "movie", "key": "2", "title": "Lib Two"},
+        ]
+
+
+def test_late_section_failure_keeps_earlier_sections(db, monkeypatch):
+    monkeypatch.setattr(sync.sysconfig, "get_bool", lambda *a, **k: True)  # plex_enabled
+    monkeypatch.setattr(sync, "_enabled_section_keys", lambda db: None)     # all sections wanted
+    monkeypatch.setattr(sync, "PlexClient", lambda db: _FakePlex())
+    monkeypatch.setattr(sync, "_sync_movies", lambda *a, **k: None)         # skip the real Plex fetch
+
+    # Section 1 completes and commits; section 2's collections step raises → its work rolls back.
+    def collections(db, plex, lib, stats):
+        if lib.plex_key == "2":
+            raise PlexError("boom on the second library")
+
+    monkeypatch.setattr(sync, "_sync_collections", collections)
+
+    result = sync.sync(db)
+
+    assert "error" in result  # the run reports the failure honestly
+    # Section 1's library survived the section-2 failure (per-section commit); section 2 rolled back.
+    keys = db.scalars(select(PlexLibrary.plex_key).order_by(PlexLibrary.plex_key)).all()
+    assert keys == ["1"]

From c86a15c2526e506975c148bc00845e434db40378 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 26 Jul 2026 21:25:36 +0200
Subject: [PATCH 18/18] =?UTF-8?q?chore(release):=200.55.0=20=E2=80=94=20R6?=
 =?UTF-8?q?=20API=20contract=20&=20transaction=20ownership?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 VERSION                          |  2 +-
 frontend/src/lib/releaseNotes.ts | 11 +++++++++++
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/VERSION b/VERSION
index 806cc5f..2b045fa 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.54.0
\ No newline at end of file
+0.55.0
\ No newline at end of file
diff --git a/frontend/src/lib/releaseNotes.ts b/frontend/src/lib/releaseNotes.ts
index 7df09e8..09b0f2a 100644
--- a/frontend/src/lib/releaseNotes.ts
+++ b/frontend/src/lib/releaseNotes.ts
@@ -14,6 +14,17 @@ export interface ReleaseEntry {
 }
 
 export const RELEASE_NOTES: ReleaseEntry[] = [
+  {
+    version: "0.55.0",
+    date: "2026-07-26",
+    summary:
+      "Internal hardening — every write request is type-checked at the edge, quota accounting and Plex sync hold up cleanly when something fails partway, and a new database-backed test net guards it all. No changes to normal use.",
+    chores: [
+      "API contract: every mutating endpoint (~50) now validates its request body against a typed request model at the edge, replacing scattered hand-written checks. Malformed input is rejected consistently with a clear validation error instead of occasionally causing an internal error, and response status codes were made consistent across modules.",
+      "Transaction correctness: YouTube quota accounting now writes in its own transaction — it stays accurate even if the surrounding job rolls back, and no longer commits a job's partial work early. Plex library sync commits each library as it finishes, so a failure partway through keeps the libraries already mirrored. Existing genre-less Plex rows were normalised.",
+      "Testing: a database-backed integration test lane (an ephemeral Postgres spun up for the test run) now runs in the release gate, covering the transaction behaviour and the Plex genre-less-library fix that the pure-logic tests couldn't reach.",
+    ],
+  },
   {
     version: "0.54.0",
     date: "2026-07-26",