refactor(reader): the HTTP layer reads through queries and writes through the service

Feed, playlists, saved views, tags and the Home pins do no database work in their routes any more:
reads go through reader/queries (and feedquery for a feed page, its counts and facets), writes
through reader/service and discover/pins, which flush; the handlers commit. Reader is fenced below
its HTTP layer too: its owner filters go through userscope, and the catalog's jobs ask Reader
instead of joining its tables (the auto-tagger's system tags, the cleanup jobs' keep rule, the
maintenance notice). A playlist sync's catalog ingest moves to sync/videos.

backend/app/routes/discover.py

@@ -13,7 +13,6 @@ from typing import Literal
 
 from fastapi import APIRouter, Depends
 from pydantic import BaseModel
-from sqlalchemy import select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
@@ -23,9 +22,8 @@ from app.discover import hero as hero_mod
 from app.discover import pins, rails
 from app.discover.budget import Budget, DEFAULT_BUDGET
 from app.models import User
-from app.reader.models import ComfortPin
 from app.plex.cards import norm_lang
-from app.routes._common import owned_or_404, not_found
+from app.routes._common import not_found
 
 router = APIRouter(prefix="/api/discover", tags=["discover"])
 
@@ -141,30 +139,19 @@ def add_pin(
         raise not_found("item")
     column, value = resolved
 
-    existing = db.execute(
-        select(ComfortPin).where(
-            ComfortPin.user_id == user.id,
-            getattr(ComfortPin, column) == value,
-        )
-    ).scalar_one_or_none()
+    existing = pins.pin_of(db, user, column, value)
     if existing is not None:
         return {"ok": True, "id": existing.id, "created": False}
 
-    pin = ComfortPin(user_id=user.id, position=pins.next_position(db, user), **{column: value})
-    db.add(pin)
     try:
+        pin = pins.add(db, user, column, value)
         db.commit()
     except IntegrityError:
         # A concurrent pin of the same thing from a second tab. The unique constraint did its job;
         # the user's intent ("be on my shelf") is satisfied either way, so report the winner rather
         # than a 500 the user can do nothing with.
         db.rollback()
-        winner = db.execute(
-            select(ComfortPin).where(
-                ComfortPin.user_id == user.id,
-                getattr(ComfortPin, column) == value,
-            )
-        ).scalar_one_or_none()
+        winner = pins.pin_of(db, user, column, value)
         if winner is None:
             # Not the unique constraint, then: the only other way in is the target row being pruned
             # between `resolve_ref` confirming it and this INSERT (a Plex sync dropping a removed
@@ -181,8 +168,10 @@ def remove_pin(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pin = owned_or_404(db, ComfortPin, pin_id, user, what="pin")
-    db.delete(pin)
+    pin = pins.own_pin(db, user, pin_id)
+    if pin is None:
+        raise not_found("pin")
+    pins.remove(db, pin)
     db.commit()
     return {"deleted": pin_id}
 

backend/app/routes/feed.py

@@ -1,9 +1,7 @@
-from datetime import date, datetime, timezone
+from datetime import date
 
 from fastapi import APIRouter, Depends, Query
 from pydantic import BaseModel
-from sqlalchemy import and_, func, or_, select
-from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session
 from sqlalchemy.orm.exc import StaleDataError
 
@@ -11,29 +9,10 @@ from app import quota
 from app.auth import current_user
 from app.db import get_db
 from app.mailtext import lang_for_user
-from app.feedquery import (
-    decode_cursor,
-    encode_cursor,
-    feed_summary,
-    feed_years,
-    filtered_query,
-    keyset_predicate,
-    order_by,
-    rank_window_start,
-    serialize,
-    sort_keys,
-    windowed_rank,
-    windowed_relevance_rows,
-)
-from app.models import User, Video
-from app.reader.models import ChannelTag, Tag, VideoState
-from app.routes._common import (
-    ProgressIn,
-    get_or_404,
-    kept_position,
-    not_found,
-    youtube_refusal,
-)
+from app.feedquery import BadCursor, facet_counts, feed_count, feed_page, feed_summary, feed_years
+from app.models import User
+from app.reader import queries, service
+from app.routes._common import ProgressIn, kept_position, not_found, youtube_refusal
 from app.sync.videos import parse_iso8601_duration
 from app.utils import iso
 from app.youtube.client import YouTubeClient, YouTubeError
@@ -103,49 +82,20 @@ def get_feed(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    query, rank_expr = filtered_query(db, user, **params)
-    lang = lang_for_user(user)
-    keys = sort_keys(sort, seed, rank_expr, lang)
-
-    vals, cursor_id, window = None, None, None
-    if cursor:
-        # The read-model raises a plain ValueError on a malformed cursor; translate it to the
-        # HTTP 400 here so feedquery stays web-framework-free.
-        try:
-            vals, cursor_id, window = decode_cursor(keys, cursor)
-        except ValueError:
-            # `from None`: the ValueError is an expected bad-input signal, not an error to chain.
-            raise refused(400, "invalid_cursor") from None
-    ranked = sort == "relevance" and rank_expr is not None
-    if ranked and not cursor:
-        window = rank_window_start(db, query)
-    if ranked and window is not None:
-        keys = sort_keys(sort, seed, windowed_rank(rank_expr, window), lang)
-
-    # Expose each key column on the row so we can build the next cursor from the last item.
-    query = query.add_columns(*[k["expr"].label(f"_k{i}") for i, k in enumerate(keys)])
-    if vals is not None:
-        for k, v in zip(keys, vals, strict=True):
-            k["value"] = v
-    if ranked and window is not None:
-        rows = windowed_relevance_rows(db, query, keys, window, cursor_id, limit + 1)
-    else:
-        query = query.order_by(*order_by(keys))
-        if cursor_id is not None:
-            query = query.where(keyset_predicate(keys, cursor_id))
-        rows = db.execute(query.limit(limit + 1)).all()
-    has_more = len(rows) > limit
-    page = rows[:limit]
-    return {
-        "items": [serialize(r) for r in page],
-        "next_cursor": (
-            encode_cursor(keys, page[-1], window if ranked else None)
-            if (has_more and page)
-            else None
-        ),
-        "has_more": has_more,
-        "limit": limit,
-    }
+    try:
+        return feed_page(
+            db,
+            user,
+            params,
+            sort=sort,
+            seed=seed,
+            limit=limit,
+            cursor=cursor,
+            lang=lang_for_user(user),
+        )
+    except BadCursor:
+        # `from None`: a malformed cursor is an expected bad-input signal, not an error to chain.
+        raise refused(400, "invalid_cursor") from None
 
 
 @router.get("/feed/count")
@@ -157,9 +107,7 @@ def get_feed_count(
     # SUPERSEDED by /feed/summary (PERF-13) — the app no longer calls this. Kept as the reference
     # oracle that test_feed_summary_matches_count_plus_facets asserts /feed/summary's `count` against;
     # remove both together with that test if this endpoint is ever retired.
-    query, _rank = filtered_query(db, user, **params)
-    total = db.scalar(select(func.count()).select_from(query.subquery()))
-    return {"count": total or 0}
+    return {"count": feed_count(db, user, **params)}
 
 
 @router.get("/facets")
@@ -181,31 +129,7 @@ def get_facets(
     SUPERSEDED by /feed/summary (PERF-13) — the app no longer calls this. Kept as the reference
     oracle for test_feed_summary_matches_count_plus_facets (it asserts /feed/summary's `facets`
     against these `counts`); retire the two together."""
-    visible = or_(ChannelTag.user_id.is_(None), ChannelTag.user_id == user.id)
-    counts: dict[int, int] = {}
-    for category in ("language", "topic", "other"):
-        # Disjunctive (OR) facets drop the category's own selections so its chips keep
-        # independent counts (you can OR more of them in). Conjunctive (AND, topics only)
-        # keeps them applied, so each remaining chip narrows to channels that ALSO have all
-        # already-selected topics — and tags that can't co-occur drop to zero (hidden).
-        conjunctive = params.get("tag_modes", {}).get(category) == "and"
-        base, _rank = filtered_query(
-            db,
-            user,
-            **{**params, "exclude_tag_category": None if conjunctive else category},
-        )
-        channels = base.with_only_columns(Video.channel_id).distinct().subquery()
-        rows = db.execute(
-            select(ChannelTag.tag_id, func.count(func.distinct(ChannelTag.channel_id)))
-            .select_from(channels)
-            .join(ChannelTag, ChannelTag.channel_id == channels.c.channel_id)
-            .join(Tag, and_(Tag.id == ChannelTag.tag_id, Tag.category == category))
-            .where(visible)
-            .group_by(ChannelTag.tag_id)
-        ).all()
-        for tag_id, count in rows:
-            counts[tag_id] = count
-    return {"counts": counts}
+    return {"counts": facet_counts(db, user, **params)}
 
 
 @router.get("/feed/summary")
@@ -234,6 +158,11 @@ def get_feed_years(
     return {"years": feed_years(db, user, **params)}
 
 
+def _video_or_404(db: Session, video_id: str) -> None:
+    if queries.video(db, video_id) is None:
+        raise not_found("video")
+
+
 class VideoStateIn(BaseModel):
     status: str
 
@@ -248,50 +177,17 @@ def set_video_state(
     status = body.status
     if status not in VALID_STATES:
         raise refused(400, "invalid_status")
-    get_or_404(db, Video, video_id, what="video")
-
-    now = datetime.now(timezone.utc)
-
+    _video_or_404(db, video_id)
     if status == "new":
-        # Un-marking: keep the row if it still holds a resume position (un-marking
-        # "watched" should restore the in-progress state, not wipe where the user left
-        # off); otherwise drop it. The in-app player fires this alongside a progress
-        # checkpoint that may DELETE the same row, so tolerate it vanishing under us.
-        row = db.execute(
-            select(VideoState).where(VideoState.user_id == user.id, VideoState.video_id == video_id)
-        ).scalar_one_or_none()
-        if row is not None:
-            if row.position_seconds:
-                row.status = "new"
-                row.watched_at = None
-            else:
-                db.delete(row)
-            try:
-                db.commit()
-            # silent-ok: the documented lost race — a concurrent player checkpoint already removed
-            # or moved this row. The state the caller asked for is the state that holds either way.
-            except StaleDataError:
-                db.rollback()
+        try:
+            service.unmark(db, user, video_id)
+            db.commit()
+        # silent-ok: the documented lost race — a concurrent player checkpoint already removed or
+        # moved this row (`service.unmark`). The state the caller asked for holds either way.
+        except StaleDataError:
+            db.rollback()
         return {"ok": True, "video_id": video_id, "status": "new"}
-
-    # watched / hidden: atomic upsert. The player marks "watched" at end-of-playback at
-    # the same instant a progress checkpoint may DELETE the in-progress row; a plain
-    # SELECT-then-UPDATE then raises StaleDataError ("0 rows matched") on that race. An
-    # INSERT … ON CONFLICT DO UPDATE keyed on uq_user_video is immune to it.
-    set_: dict = {"status": status, "updated_at": now}
-    if status == "watched":
-        set_["watched_at"] = now  # hidden keeps any existing watched_at
-    stmt = (
-        pg_insert(VideoState)
-        .values(
-            user_id=user.id,
-            video_id=video_id,
-            status=status,
-            watched_at=now if status == "watched" else None,
-        )
-        .on_conflict_do_update(constraint="uq_user_video", set_=set_)
-    )
-    db.execute(stmt)
+    service.mark(db, user, video_id, status)
     db.commit()
     return {"ok": True, "video_id": video_id, "status": status}
 
@@ -305,16 +201,12 @@ def clear_video_state(
     """Reset a video to pristine for this user — drop the whole VideoState row (status,
     watch position and watched_at), as if it had never been opened. Saved/playlist membership
     lives elsewhere and is untouched."""
-    row = db.execute(
-        select(VideoState).where(VideoState.user_id == user.id, VideoState.video_id == video_id)
-    ).scalar_one_or_none()
-    if row is not None:
-        db.delete(row)
-        try:
-            db.commit()
-        # silent-ok: the row went under the delete, which is the outcome the delete wanted.
-        except StaleDataError:
-            db.rollback()
+    try:
+        service.clear_state(db, user, video_id)
+        db.commit()
+    # silent-ok: the row went under the delete, which is the outcome the delete wanted.
+    except StaleDataError:
+        db.rollback()
     return {"ok": True, "video_id": video_id, "status": "new", "position_seconds": 0}
 
 
@@ -330,36 +222,17 @@ def set_video_progress(
     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 = kept_position(body)
-
-    get_or_404(db, Video, video_id, what="video")
-
-    row = db.execute(
-        select(VideoState).where(VideoState.user_id == user.id, VideoState.video_id == video_id)
-    ).scalar_one_or_none()
-
+    _video_or_404(db, video_id)
     if not position:
-        # Nothing meaningful to store: drop a status-less row entirely, otherwise just
-        # zero the position (a saved/hidden video keeps its status).
-        if row is not None:
-            if row.status == "new":
-                db.delete(row)
-            else:
-                row.position_seconds = 0
-                row.progress_updated_at = datetime.now(timezone.utc)
-            # A concurrent state change (e.g. the end-of-playback "watched" mark) may
-            # have removed/updated this row already — tolerate the lost race.
-            try:
-                db.commit()
-            # silent-ok: exactly the race the comment above describes; the response stays true.
-            except StaleDataError:
-                db.rollback()
+        try:
+            service.set_progress(db, user, video_id, 0)
+            db.commit()
+        # silent-ok: a concurrent state change (the end-of-playback "watched" mark) removed or
+        # updated this row already — the lost race; the response stays true.
+        except StaleDataError:
+            db.rollback()
         return {"ok": True, "video_id": video_id, "position_seconds": 0}
-
-    if row is None:
-        row = VideoState(user_id=user.id, video_id=video_id)
-        db.add(row)
-    row.position_seconds = position
-    row.progress_updated_at = datetime.now(timezone.utc)
+    service.set_progress(db, user, video_id, position)
     db.commit()
     return {"ok": True, "video_id": video_id, "position_seconds": position}
 
@@ -377,7 +250,7 @@ def get_video_detail(
     our DB (e.g. a YouTube link inside another video's description that the in-app
     player navigated to) is resolved via the YouTube API (videos.list, 1 unit,
     attributed to the requesting user)."""
-    v = db.get(Video, video_id)
+    v = queries.video(db, video_id)
     if v is not None:
         return {
             "id": v.id,

backend/app/routes/playlists.py

@@ -3,32 +3,34 @@ CRUD (create / rename / delete, add / remove / reorder items) plus YouTube two-w
 mirror the user's own YouTube playlists in (`/sync-youtube`) and push/revert local edits back
 out (`/{id}/push-plan`, `/{id}/revert-youtube`), behind the optional write scope."""
 
+from typing import TYPE_CHECKING
+
 from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel, Field
-from sqlalchemy import func, select, and_
-from sqlalchemy.orm import Session, aliased
+from sqlalchemy.orm import Session
 
 from app import quota
 from app.auth import current_user, has_read_scope, has_write_scope, require_write_scope
 from app.db import get_db
-from app.feedquery import feed_columns, serialize
-from app.models import Channel, User, Video
-from app.reader.models import Playlist, PlaylistItem, VideoState
+from app.feedquery import serialize
+from app.models import User
+from app.reader import queries, service
 from app.sync.playlists import (
     PlaylistGone,
-    lock_playlists,
     merge_playlist,
     plan_merge,
-    recompute_dirty,
     pull_user_playlists,
     repull_playlist,
     sync_claim,
     user_sync_claim,
 )
 from app.ratelimit import RateLimiter
-from app.routes._common import get_or_404, not_found, owned_or_404, youtube_refusal
+from app.routes._common import not_found, youtube_refusal
 from app.youtube.client import YouTubeClient, YouTubeError
 
+if TYPE_CHECKING:
+    from app.reader.models import Playlist
+
 router = APIRouter(prefix="/api/playlists", tags=["playlists"])
 
 # SEC-14, same reasoning as the sync module's limiter: a playlist pull lists every playlist the
@@ -57,90 +59,20 @@ def _refused(status: int, reason: str) -> HTTPException:
     return HTTPException(status_code=status, detail={"code": "playlist", "reason": reason})
 
 
-def _touch(pl: Playlist) -> None:
-    """Bump the playlist's `updated_at` for an edit that only writes `playlist_items`.
-
-    `UpdatedAtMixin`'s `onupdate` fires on an UPDATE of the PLAYLIST row, and add / remove /
-    reorder / move write the item rows instead — so without this the rail's "recently changed"
-    sort would only ever see renames. The assignment is what makes the column mean "last time
-    this list changed", which is what the rail promises the reader.
-
-    The DATABASE's clock, like the mixin's own `onupdate`: one sort key written from two clocks
-    (this process's and Postgres's) could order a rename and an item edit the wrong way round."""
-    pl.updated_at = func.now()
+def _own_playlist(db: Session, user: User, playlist_id: int, *, lock: bool = False) -> "Playlist":
+    pl = queries.own_playlist(db, user, playlist_id, lock=lock)
+    if pl is None:
+        raise not_found("playlist")
+    return pl
 
 
-def _next_playlist_position(db: Session, user_id: int) -> int:
-    """Append position for a new playlist in this user's rail."""
-    return (
-        db.scalar(
-            select(func.coalesce(func.max(Playlist.position), -1)).where(
-                Playlist.user_id == user_id
-            )
-        )
-        + 1
-    )
-
-
-def _next_item_position(db: Session, playlist_id: int) -> int:
-    """Append position for a new item at the end of a playlist. Locks the playlist row first: two
-    adds (two tabs, the rail and the page) otherwise both read the same max and land on one
-    position, and the list's order between them is then arbitrary."""
-    lock_playlists(db, playlist_id)
-    return (
-        db.scalar(
-            select(func.coalesce(func.max(PlaylistItem.position), -1)).where(
-                PlaylistItem.playlist_id == playlist_id
-            )
-        )
-        + 1
-    )
-
-
-def _add_item(db: Session, pl: Playlist, video_id: str, *, mark_dirty: bool) -> bool:
-    """Append a video to a playlist if not already present (idempotent). Returns whether it
-    was added. `mark_dirty` recomputes the YouTube-sync dirty flag (skip for Watch later).
-    Locked BEFORE the presence check: two adds of one video both saw "absent" and the second one's
-    insert hit uq_playlist_video as a 500."""
-    lock_playlists(db, pl.id)
-    exists = db.scalar(
-        select(PlaylistItem).where(
-            PlaylistItem.playlist_id == pl.id, PlaylistItem.video_id == video_id
-        )
-    )
-    if exists is not None:
-        return False
-    db.add(
-        PlaylistItem(playlist_id=pl.id, video_id=video_id, position=_next_item_position(db, pl.id))
-    )
-    if mark_dirty:
-        recompute_dirty(db, pl)
-    _touch(pl)
-    db.flush()  # the handler commits (CLAUDE.md: helpers flush)
-    return True
-
-
-def _remove_item(db: Session, pl: Playlist, video_id: str, *, mark_dirty: bool) -> bool:
-    """Remove a video from a playlist if present (idempotent). Returns whether it was removed.
-    `mark_dirty` recomputes the YouTube-sync dirty flag (skip for Watch later)."""
-    lock_playlists(db, pl.id)
-    item = db.scalar(
-        select(PlaylistItem).where(
-            PlaylistItem.playlist_id == pl.id, PlaylistItem.video_id == video_id
-        )
-    )
-    if item is None:
-        return False
-    db.delete(item)
-    if mark_dirty:
-        recompute_dirty(db, pl)
-    _touch(pl)
-    db.flush()  # the handler commits (CLAUDE.md: helpers flush)
-    return True
+def _video_or_404(db: Session, video_id: str) -> None:
+    if queries.video(db, video_id) is None:
+        raise not_found("video")
 
 
 def _summary(
-    pl: Playlist,
+    pl: "Playlist",
     count: int,
     total_duration: int = 0,
     has_video: bool | None = None,
@@ -157,7 +89,7 @@ def _summary(
         "total_duration_seconds": total_duration,
         "cover_thumbnail": cover,
         # When this list last CHANGED (rename, add/remove/move/reorder) — the rail's
-        # "recently changed first" sort reads it. See _touch for why it isn't automatic.
+        # "recently changed first" sort reads it. See `service.touch` for why it isn't automatic.
         "updated_at": pl.updated_at,
     }
     if has_video is not None:
@@ -173,73 +105,14 @@ def list_playlists(
 ) -> list[dict]:
     """The user's playlists (newest custom order). With `contains=<video_id>`, each entry
     also reports whether that video is already in it — used by the add-to-playlist popover."""
-    pls = (
-        db.execute(
-            select(Playlist)
-            .where(Playlist.user_id == user.id)
-            .order_by(Playlist.position, Playlist.created_at)
-        )
-        .scalars()
-        .all()
-    )
+    pls = queries.playlists_for(db, user)
     if not pls:
         return []
     ids = [p.id for p in pls]
-    counts = dict(
-        db.execute(
-            select(PlaylistItem.playlist_id, func.count())
-            .where(PlaylistItem.playlist_id.in_(ids))
-            .group_by(PlaylistItem.playlist_id)
-        ).all()
-    )
-    durations = dict(
-        db.execute(
-            select(
-                PlaylistItem.playlist_id,
-                func.coalesce(func.sum(Video.duration_seconds), 0),
-            )
-            .join(Video, Video.id == PlaylistItem.video_id)
-            .where(PlaylistItem.playlist_id.in_(ids))
-            .group_by(PlaylistItem.playlist_id)
-        ).all()
-    )
-    member: set[int] = set()
-    if contains:
-        member = set(
-            db.execute(
-                select(PlaylistItem.playlist_id).where(
-                    PlaylistItem.playlist_id.in_(ids),
-                    PlaylistItem.video_id == contains,
-                )
-            )
-            .scalars()
-            .all()
-        )
-    # Batch the cover thumbnails (first item per playlist by position) in ONE window query
-    # instead of a per-playlist SELECT inside _summary (the old N+1).
-    rn = (
-        func.row_number()
-        .over(
-            partition_by=PlaylistItem.playlist_id,
-            order_by=PlaylistItem.position,
-        )
-        .label("rn")
-    )
-    first_items = (
-        select(
-            PlaylistItem.playlist_id.label("pid"),
-            Video.thumbnail_url.label("thumb"),
-            rn,
-        )
-        .join(Video, Video.id == PlaylistItem.video_id)
-        .where(PlaylistItem.playlist_id.in_(ids))
-        .subquery()
-    )
-    covers = dict(
-        db.execute(
-            select(first_items.c.pid, first_items.c.thumb).where(first_items.c.rn == 1)
-        ).all()
-    )
+    counts = queries.item_counts(db, ids)
+    durations = queries.durations(db, ids)
+    member = queries.containing(db, ids, contains) if contains else set()
+    covers = queries.covers(db, ids)
     return [
         _summary(
             p,
@@ -270,29 +143,11 @@ def create_playlist(
     name = body.name.strip()
     if not name:
         raise _refused(400, "name_required")
-    pl = Playlist(user_id=user.id, name=name, position=_next_playlist_position(db, user.id))
-    db.add(pl)
+    pl = service.create_playlist(db, user, name)
     db.commit()
     return _summary(pl, 0)
 
 
-def _watch_later(db: Session, user: User) -> Playlist:
-    """The user's built-in Watch later playlist, created on first use."""
-    pl = db.scalar(
-        select(Playlist).where(Playlist.user_id == user.id, Playlist.kind == "watch_later")
-    )
-    if pl is None:
-        pl = Playlist(
-            user_id=user.id,
-            name="Watch later",
-            kind="watch_later",
-            position=_next_playlist_position(db, user.id),
-        )
-        db.add(pl)
-        db.flush()  # the id, for the item the caller adds next; the handler commits
-    return pl
-
-
 @router.post("/watch-later")
 def add_watch_later(
     body: VideoRefIn,
@@ -301,9 +156,9 @@ def add_watch_later(
 ) -> dict:
     """Bookmark shortcut: add a video to the built-in Watch later playlist."""
     video_id = body.video_id
-    get_or_404(db, Video, video_id, what="video")
-    pl = _watch_later(db, user)
-    _add_item(db, pl, video_id, mark_dirty=False)
+    _video_or_404(db, video_id)
+    pl = service.watch_later(db, user)
+    service.add_item(db, pl, video_id, mark_dirty=False)
     db.commit()
     return {"ok": True, "saved": True, "playlist_id": pl.id}
 
@@ -314,11 +169,9 @@ def remove_watch_later(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = db.scalar(
-        select(Playlist).where(Playlist.user_id == user.id, Playlist.kind == "watch_later")
-    )
+    pl = queries.watch_later(db, user)
     if pl is not None:
-        _remove_item(db, pl, video_id, mark_dirty=False)
+        service.remove_item(db, pl, video_id, mark_dirty=False)
         db.commit()
     return {"ok": True, "saved": False}
 
@@ -355,7 +208,7 @@ def revert_youtube(
     """Reset one YouTube-linked playlist to its current YouTube state, discarding local
     edits (and clearing the dirty flag). The user-facing 'undo all my changes' for a list
     once the in-session undo history is gone."""
-    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
+    pl = _own_playlist(db, user, playlist_id)
     if not pl.yt_playlist_id:
         raise _refused(400, "not_on_youtube")
     if not has_read_scope(user):
@@ -376,10 +229,10 @@ def revert_youtube(
             raise youtube_refusal(exc, playlist=True) from exc
 
 
-def _pushable(db: Session, user: User, playlist_id: int) -> Playlist:
+def _pushable(db: Session, user: User, playlist_id: int) -> "Playlist":
     """A local playlist the user may push to YouTube (create or update). The built-in
     Watch later and read-only YouTube mirrors are never pushable."""
-    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
+    pl = _own_playlist(db, user, playlist_id)
     if pl.kind == "watch_later":
         raise _refused(400, "watch_later_not_pushable")
     return pl
@@ -449,17 +302,8 @@ def get_playlist(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
-    state = aliased(VideoState)
-    rows = db.execute(
-        select(*feed_columns(user, state))
-        .join(PlaylistItem, PlaylistItem.video_id == Video.id)
-        .join(Channel, Channel.id == Video.channel_id)
-        .outerjoin(state, and_(state.video_id == Video.id, state.user_id == user.id))
-        .where(PlaylistItem.playlist_id == pl.id)
-        # `id` breaks a position tie the same way on every read (the renumbering add does too).
-        .order_by(PlaylistItem.position, PlaylistItem.id)
-    ).all()
+    pl = _own_playlist(db, user, playlist_id)
+    rows = queries.playlist_rows(db, user, pl.id)
     return {
         "id": pl.id,
         "name": pl.name,
@@ -483,34 +327,15 @@ def rename_playlist(
     db: Session = Depends(get_db),
 ) -> dict:
     # Locked: the new name moves `dirty`, which the scheduled mirror refresh reads under this lock.
-    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist", lock=True)
+    pl = _own_playlist(db, user, playlist_id, lock=True)
     if "name" in body.model_fields_set:
         name = (body.name or "").strip()
         if not name:
             raise _refused(400, "name_required")
-        if name != pl.name:
-            pl.name = name
-            recompute_dirty(db, pl)
+        service.rename_playlist(db, pl, name)
     db.commit()
-    # One aggregate for count + duration (outer join so an empty playlist still returns 0),
-    # plus a single cover lookup — was 3 separate round-trips.
-    count, total = db.execute(
-        select(
-            func.count(PlaylistItem.id),
-            func.coalesce(func.sum(Video.duration_seconds), 0),
-        )
-        .select_from(PlaylistItem)
-        .outerjoin(Video, Video.id == PlaylistItem.video_id)
-        .where(PlaylistItem.playlist_id == pl.id)
-    ).one()
-    cover = db.scalar(
-        select(Video.thumbnail_url)
-        .join(PlaylistItem, PlaylistItem.video_id == Video.id)
-        .where(PlaylistItem.playlist_id == pl.id)
-        .order_by(PlaylistItem.position)
-        .limit(1)
-    )
-    return _summary(pl, count or 0, total or 0, cover=cover)
+    count, total, cover = queries.playlist_totals(db, pl.id)
+    return _summary(pl, count, total, cover=cover)
 
 
 @router.delete("/{playlist_id}")
@@ -520,7 +345,7 @@ def delete_playlist(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
+    pl = _own_playlist(db, user, playlist_id)
     if pl.kind == "watch_later":
         raise _refused(400, "watch_later_undeletable")
     # Not in the middle of a sync of it (`sync_claim`): a push that read the list before the delete
@@ -541,9 +366,7 @@ def delete_playlist(
                         yt.delete_playlist(pl.yt_playlist_id)
             except YouTubeError as exc:
                 raise youtube_refusal(exc, playlist=True) from exc
-        # The playlist first, as every item write: the cascade deletes the items before the list row.
-        lock_playlists(db, pl.id)
-        db.delete(pl)  # items cascade
+        service.delete_playlist(db, pl)
         db.commit()
     return {"deleted": playlist_id}
 
@@ -562,26 +385,10 @@ def add_item(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
+    pl = _own_playlist(db, user, playlist_id)
     video_id = body.video_id
-    get_or_404(db, Video, video_id, what="video")
-    added = _add_item(db, pl, video_id, mark_dirty=False)
-    if added and body.position is not None:
-        # Renumber the whole list with the new row at `position` (clamped to the end): positions
-        # can have gaps after removals, so "index N" is only meaningful over the ordered rows.
-        rows = list(
-            db.execute(
-                select(PlaylistItem)
-                .where(PlaylistItem.playlist_id == pl.id)
-                .order_by(PlaylistItem.position, PlaylistItem.id)
-            ).scalars()
-        )
-        new = next(r for r in rows if r.video_id == video_id)
-        rows.remove(new)
-        rows.insert(min(body.position, len(rows)), new)
-        for pos, row in enumerate(rows):
-            row.position = pos
-    recompute_dirty(db, pl)
+    _video_or_404(db, video_id)
+    service.add_to_playlist(db, pl, video_id, body.position)
     db.commit()
     return {"ok": True, "playlist_id": pl.id, "video_id": video_id}
 
@@ -593,8 +400,8 @@ def remove_item(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
-    _remove_item(db, pl, video_id, mark_dirty=True)
+    pl = _own_playlist(db, user, playlist_id)
+    service.remove_item(db, pl, video_id, mark_dirty=True)
     db.commit()
     return {"ok": True, "playlist_id": pl.id, "video_id": video_id}
 
@@ -618,49 +425,21 @@ def move_item(
     exactly the kind of half-applied state this codebase treats as a bug rather than an edge
     case. Idempotent: if the video is already in the target, the source row is simply dropped
     (moving into a list that already has it is a removal, not a duplicate)."""
-    src = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
+    src = _own_playlist(db, user, playlist_id)
     # Its own reason: "this playlist doesn't exist any more" about a TARGET that is gone was read as
     # the list on screen — which is still there.
-    dst = owned_or_404(db, Playlist, body.target_playlist_id, user, what="move_target")
-    if src.id == dst.id:
+    dst = queries.own_playlist(db, user, body.target_playlist_id)
+    if dst is None:
+        raise not_found("move_target")
+    try:
+        service.move_item(db, src, dst, video_id)
+    except service.MoveRefused as e:
+        # A same-list move is a bad request; a video a concurrent edit (another tab, a YouTube
+        # re-pull) already took out is gone.
+        status = 400 if e.reason == "same_playlist" else 404
         raise HTTPException(
-            status_code=400, detail={"code": "playlist_move", "reason": "same_playlist"}
-        )
-    # Both lists, in id order: a move A→B beside a move B→A would otherwise lock crosswise.
-    lock_playlists(db, src.id, dst.id)
-    item = db.scalar(
-        select(PlaylistItem).where(
-            PlaylistItem.playlist_id == src.id, PlaylistItem.video_id == video_id
-        )
-    )
-    if item is None:
-        # A concurrent edit (another tab, or a YouTube re-pull) already took it out.
-        raise HTTPException(
-            status_code=404, detail={"code": "playlist_move", "reason": "not_in_playlist"}
-        )
-    already = db.scalar(
-        select(PlaylistItem).where(
-            PlaylistItem.playlist_id == dst.id, PlaylistItem.video_id == video_id
-        )
-    )
-    dst_changed = False
-    if already is None:
-        # Re-parent the existing row rather than delete+insert: `added_at` ("when I saved this")
-        # survives the move, and there is no window where the video belongs to neither list. The
-        # check above holds: both lists are locked, and an insert into the target (another tab's
-        # add, a YouTube merge) waits for the lock — its foreign key needs the target row.
-        item.playlist_id = dst.id
-        item.position = _next_item_position(db, dst.id)
-        dst_changed = True
-    if not dst_changed:
-        db.delete(item)
-    # The source always changed; the target only when the row landed in it. `_touch` on a target
-    # that already had the video promoted an untouched list in the rail's "recently changed" sort.
-    recompute_dirty(db, src)
-    _touch(src)
-    if dst_changed:
-        recompute_dirty(db, dst)
-        _touch(dst)
+            status_code=status, detail={"code": "playlist_move", "reason": e.reason}
+        ) from None
     db.commit()
     return {"ok": True, "from_playlist_id": src.id, "to_playlist_id": dst.id, "video_id": video_id}
 
@@ -677,30 +456,7 @@ def reorder_items(
     db: Session = Depends(get_db),
 ) -> dict:
     # Locked: a concurrent add between reading the items and writing the order would collide.
-    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist", lock=True)
-    order = body.video_ids
-    items = {
-        it.video_id: it
-        for it in db.execute(
-            select(PlaylistItem).where(PlaylistItem.playlist_id == pl.id)
-        ).scalars()
-    }
-    pos = 0
-    seen: set[str] = set()
-    for vid in order:
-        it = items.get(vid)
-        if it is not None:
-            it.position = pos
-            pos += 1
-            seen.add(vid)
-    # Any items the payload omitted (e.g. added concurrently in another tab) keep their relative
-    # order but get fresh trailing positions, so no two items collide on the same position.
-    for it in sorted(
-        (it for vid, it in items.items() if vid not in seen), key=lambda i: i.position
-    ):
-        it.position = pos
-        pos += 1
-    recompute_dirty(db, pl)
-    _touch(pl)
+    pl = _own_playlist(db, user, playlist_id, lock=True)
+    pos = service.reorder_items(db, pl, body.video_ids)
     db.commit()
     return {"ok": True, "playlist_id": pl.id, "count": pos}

backend/app/routes/saved_views.py

@@ -1,16 +1,20 @@
+from typing import TYPE_CHECKING
+
 from fastapi import APIRouter, Depends
 from pydantic import BaseModel, field_validator
-from sqlalchemy import func, select, update
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
 from app.auth import current_user
 from app.db import get_db
 from app.models import User
-from app.reader.models import SavedView
-from app.routes._common import owned_or_404
+from app.reader import queries, service
+from app.routes._common import not_found
 from app.refusal import refused
 
+if TYPE_CHECKING:
+    from app.reader.models import SavedView
+
 # Saved "smart views": per-user named snapshots of a module's filters (feed or plex, keyed by
 # `source`).
 router = APIRouter(prefix="/api/saved-views", tags=["saved-views"])
@@ -24,7 +28,7 @@ def _norm_source(source: str) -> str:
     return source if source in _SOURCES else "feed"
 
 
-def _serialize(v: SavedView) -> dict:
+def _serialize(v: "SavedView") -> dict:
     return {
         "id": v.id,
         "name": v.name,
@@ -34,23 +38,20 @@ def _serialize(v: SavedView) -> dict:
     }
 
 
+def _own_view(db: Session, user: User, view_id: int) -> "SavedView":
+    view = queries.own_view(db, user, view_id)
+    if view is None:
+        raise not_found("view")
+    return view
+
+
 @router.get("")
 def list_views(
     source: str = "feed",
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> list[dict]:
-    source = _norm_source(source)
-    rows = (
-        db.execute(
-            select(SavedView)
-            .where(SavedView.user_id == user.id, SavedView.source == source)
-            .order_by(SavedView.position, SavedView.id)
-        )
-        .scalars()
-        .all()
-    )
-    return [_serialize(v) for v in rows]
+    return [_serialize(v) for v in queries.views(db, user, _norm_source(source))]
 
 
 # A feed view's tag pick is read by more than the feed: the autotag job keeps every tag a view names
@@ -87,22 +88,8 @@ def create_view(
     name = body.name.strip()
     if not name:
         raise refused(400, "name_required")
-    source = _norm_source(body.source)
-    # Position is per (user, source), so each module's views number 0..N independently.
-    maxpos = db.execute(
-        select(func.coalesce(func.max(SavedView.position), -1)).where(
-            SavedView.user_id == user.id, SavedView.source == source
-        )
-    ).scalar_one()
-    view = SavedView(
-        user_id=user.id,
-        source=source,
-        name=name[:80],
-        filters=body.filters,
-        position=maxpos + 1,
-    )
-    db.add(view)
     try:
+        view = service.create_view(db, user, _norm_source(body.source), name, body.filters)
         db.commit()
     except IntegrityError:
         db.rollback()
@@ -127,32 +114,17 @@ def update_view(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    view = owned_or_404(db, SavedView, view_id, user, what="view")
+    view = _own_view(db, user, view_id)
     sent = body.model_fields_set
-    if "name" in sent:
-        name = (body.name or "").strip()
-        if not name:
-            raise refused(400, "name_required")
-        view.name = name[:80]
-    if "filters" in sent:
-        if body.filters is None:
-            raise refused(400, "filters_not_object")
-        view.filters = body.filters
-    if "is_default" in sent:
-        make_default = bool(body.is_default)
-        if make_default:
-            # At most one default per (user, source): clear the flag on this module's others first.
-            db.execute(
-                update(SavedView)
-                .where(
-                    SavedView.user_id == user.id,
-                    SavedView.source == view.source,
-                    SavedView.id != view.id,
-                )
-                .values(is_default=False)
-            )
-        view.is_default = make_default
+    name = (body.name or "").strip()
+    if "name" in sent and not name:
+        raise refused(400, "name_required")
+    if "filters" in sent and body.filters is None:
+        raise refused(400, "filters_not_object")
     try:
+        service.update_view(
+            db, view, sent=sent, name=name, filters=body.filters, is_default=body.is_default
+        )
         db.commit()
     except IntegrityError:
         db.rollback()
@@ -166,8 +138,7 @@ def delete_view(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    view = owned_or_404(db, SavedView, view_id, user, what="view")
-    db.delete(view)
+    service.delete_view(db, _own_view(db, user, view_id))
     db.commit()
     return {"deleted": view_id}
 
@@ -182,14 +153,6 @@ def reorder_views(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    ids = body.ids
-    rows = db.execute(select(SavedView).where(SavedView.user_id == user.id)).scalars().all()
-    by_id = {v.id: v for v in rows}
-    pos = 0
-    for vid in ids:
-        v = by_id.get(vid)
-        if v is not None:
-            v.position = pos
-            pos += 1
+    service.reorder_views(db, user, body.ids)
     db.commit()
     return {"ok": True}

backend/app/routes/tags.py

@@ -1,20 +1,32 @@
+from typing import TYPE_CHECKING
+
 from fastapi import APIRouter, Depends
 from pydantic import BaseModel
-from sqlalchemy import func, or_, select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
 from app.auth import current_user
 from app.db import get_db
 from app.models import User
-from app.reader.models import ChannelTag, Tag
-from app.routes._common import owned_or_404
+from app.reader import queries, service
+from app.routes._common import not_found
 from app.sync.tagsuggest import compute_tag_suggestions
 from app.refusal import refused
 
+if TYPE_CHECKING:
+    from app.reader.models import Tag
+
 router = APIRouter(prefix="/api/tags", tags=["tags"])
 
 
+def _own_tag(db: Session, user: User, tag_id: int) -> "Tag":
+    """One of the user's own tags, or a 404 — a system tag (no owner) is not theirs to edit."""
+    tag = queries.own_tag(db, user, tag_id)
+    if tag is None:
+        raise not_found("tag")
+    return tag
+
+
 @router.get("/suggestions")
 def tag_suggestions(
     user: User = Depends(current_user), db: Session = Depends(get_db)
@@ -28,13 +40,6 @@ def tag_suggestions(
 
 @router.get("")
 def list_tags(user: User = Depends(current_user), db: Session = Depends(get_db)) -> list[dict]:
-    rows = db.execute(
-        select(Tag, func.count(ChannelTag.id))
-        .outerjoin(ChannelTag, ChannelTag.tag_id == Tag.id)
-        .where(or_(Tag.user_id.is_(None), Tag.user_id == user.id))
-        .group_by(Tag.id)
-        .order_by(Tag.category, Tag.name)
-    ).all()
     return [
         {
             "id": tag.id,
@@ -44,7 +49,7 @@ def list_tags(user: User = Depends(current_user), db: Session = Depends(get_db))
             "system": tag.user_id is None,
             "channel_count": count,
         }
-        for tag, count in rows
+        for tag, count in queries.tags_with_counts(db, user)
     ]
 
 
@@ -63,16 +68,8 @@ def create_tag(
     name = body.name.strip()
     if not name:
         raise refused(400, "name_required")
-    # 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=body.color,
-        category=category,
-    )
-    db.add(tag)
     try:
+        tag = service.create_tag(db, user, name, body.category, body.color)
         db.commit()
     except IntegrityError:
         db.rollback()
@@ -100,17 +97,13 @@ def update_tag(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    # System tags (user_id NULL) are not user-editable: owned_or_404 404s them too.
-    tag = owned_or_404(db, Tag, tag_id, user, what="tag")
+    tag = _own_tag(db, user, tag_id)
     sent = body.model_fields_set
-    if "name" in sent:
-        name = (body.name or "").strip()
-        if not name:
-            raise refused(400, "name_required")
-        tag.name = name
-    if "color" in sent:
-        tag.color = body.color
+    name = (body.name or "").strip()
+    if "name" in sent and not name:
+        raise refused(400, "name_required")
     try:
+        service.update_tag(tag, sent=sent, name=name, color=body.color)
         db.commit()
     except IntegrityError:
         db.rollback()
@@ -130,8 +123,6 @@ def delete_tag(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    # System tags (user_id NULL) are not user-editable: owned_or_404 404s them too.
-    tag = owned_or_404(db, Tag, tag_id, user, what="tag")
-    db.delete(tag)  # ChannelTag rows cascade on tag delete.
+    service.delete_tag(db, _own_tag(db, user, tag_id))
     db.commit()
     return {"deleted": tag_id}